Add Stats Logging System with Build Flag Control

[wouterlucas]

Summary

This PR adds a comprehensive stats logging system that tracks component, element, and event listener activity throughout the application. The system is fully controlled by a Vite build flag (__BLITS_STATS__), ensuring all stats-related code is optimized out of production builds for maximum performance.

Key Features

Build-Time Flag for Zero Runtime Overhead

• Added __BLITS_STATS__ Vite flag to enable/disable stats at build time
• Implemented dead code elimination for all stats code when flag is disabled
• Exposed BLITS_STATS_ENABLED for use in other modules

Enhanced Statistics Collection

• Added metrics tracking for components, elements, event listeners, timeouts, and intervals
• Implemented rolling averages (1min, 5min, 15min) for load statistics
• Added memory usage tracking (memory used, renderable memory, textures)
• Added proper cleanup and guard conditions for all stats operations

Visual Stats Overlay Component

• Created StatsOverlay component for real-time stats visualization
• Component only renders when stats are enabled (returns null otherwise)
• Displays system statistics and renderer memory information
• Auto-updates every 500ms for live monitoring

Documentation

• Added comprehensive documentation in docs/built-in/stats.md
• Updated JSDoc comments throughout the codebase
• Documented best practices for stats usage

Implementation Details

• Fixed event listener registration bugs (typo: bla.set → eventsMap.set)
• Made all increment/decrement calls conditional on the stats flag
• Updated launch.js to only start logging if stats are enabled
• Added bytesToMb utility function for memory formatting
• Used memory information from renderer for additional insights

Testing

• Manually tested in development environment with flag enabled
• Verified bundle size reduction with flag disabled
• Validated that stats overlay properly displays all metrics

Future Improvements

• Consider adding CPU usage metrics
• Add FPS metrics to the stats overlay
• Potential for persistent logging to file for longer-term analysis

This change maintains the high-performance standards of Blits while providing valuable debug and monitoring capabilities for developers during the development process.

[github-actions]

Test Results: ❌ FAILED

Run at: 2025-05-26T09:48:06.409Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:

> @lightningjs/blits@1.29.0 test
> c8 npm run test:run


> @lightningjs/blits@1.29.0 test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/log' imported from /home/runner/work/blits/blits/src/lib/stats.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/log'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (521ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

[github-actions]

Test Results: ❌ FAILED

Run at: 2025-05-26T09:48:06.409Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:

> @lightningjs/blits@1.29.0 test
> c8 npm run test:run


> @lightningjs/blits@1.29.0 test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/log' imported from /home/runner/work/blits/blits/src/lib/stats.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/log'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (521ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

[github-actions]

Test Results: ❌ FAILED

Run at: 2025-05-26T11:04:33.055Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:

> @lightningjs/blits@1.29.0 test
> c8 npm run test:run


> @lightningjs/blits@1.29.0 test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/log' imported from /home/runner/work/blits/blits/src/lib/stats.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/log'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (498ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

[github-actions]

Test Results: ❌ FAILED

Run at: 2025-05-26T11:11:08.325Z

Summary:
Test execution encountered errors. No tests were run.

Error Output:

> @lightningjs/blits@1.29.0 test
> c8 npm run test:run


> @lightningjs/blits@1.29.0 test:run
> node -r global-jsdom/register ./node_modules/.bin/tape '{,!(node_modules|packages)/**/}*.test.js' | tap-diff

(node:2169) ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
node:internal/modules/esm/resolve:265
    throw new ERR_MODULE_NOT_FOUND(
          ^

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/home/runner/work/blits/blits/src/lib/stats' imported from /home/runner/work/blits/blits/src/lib/eventListeners.js
    at finalizeResolution (node:internal/modules/esm/resolve:265:11)
    at moduleResolve (node:internal/modules/esm/resolve:933:10)
    at defaultResolve (node:internal/modules/esm/resolve:1169:11)
    at ModuleLoader.defaultResolve (node:internal/modules/esm/loader:383:12)
    at ModuleLoader.resolve (node:internal/modules/esm/loader:352:25)
    at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:227:38)
    at ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:87:39)
    at link (node:internal/modules/esm/module_job:86:36) {
  code: 'ERR_MODULE_NOT_FOUND',
  url: 'file:///home/runner/work/blits/blits/src/lib/stats'
}

Node.js v20.16.0

passed: 0  failed: 0  of 0 tests  (514ms)

All of 0 tests passed!

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
----------|---------|----------|---------|---------|-------------------
All files |       0 |        0 |       0 |       0 |                   
----------|---------|----------|---------|---------|-------------------

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-26T12:14:21.408Z

Summary:
passed: 116 failed: 0 of 116 tests

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-26T12:41:11.004Z

Summary:
passed: 116 failed: 0 of 116 tests

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-26T14:07:55.319Z

Summary:
passed: 116 failed: 0 of 116 tests

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-26T16:29:18.953Z

Summary:
passed: 521 failed: 0 of 521 tests

[wouterlucas]

Squashed and rebased against latest master, will need some @DouweCnossen or @erikhaandrikman love on the overlay. Maybe sprites down the road.

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-27T07:34:57.281Z

Summary:
passed: 521 failed: 0 of 521 tests

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-27T08:16:07.059Z

Summary:
passed: 116 failed: 0 of 116 tests

[github-actions]

Test Results: ✅ PASSED

Run at: 2025-05-28T11:57:41.212Z

Summary:
passed: 521 failed: 0 of 521 tests