Add runtime monitoring and logging foundation

- runtime error tracking added
- performance monitoring hooks added
- logging standardized
- roadmap advanced

Author: ToolboxAid

docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_ERROR_TRACKING.md

@@ -0,0 +1,27 @@
+# BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION — Error Tracking
+
+## Scope Implemented
+- Added `createRuntimeMonitoringHooks` in `src/engine/runtime/RuntimeMonitoringHooks.js` as the shared runtime error/performance hook surface.
+- Wired engine runtime monitoring lifecycle in `src/engine/core/Engine.js`:
+  - start hooks during `engine.start()`
+  - stop hooks during `engine.stop()`
+  - emit monitoring events to runtime consumers:
+    - `engine:runtime-monitoring-error`
+    - `engine:runtime-monitoring-performance`
+- Wired tools runtime monitoring in `tools/shared/platformShell.js` with the shared hook surface and tools runtime context capture.
+
+## Error Tracking Behavior
+- Captures global runtime errors when `window` is available:
+  - `window.error`
+  - `window.unhandledrejection`
+- Emits normalized payloads using `runtime.monitoring.v1`.
+- Preserves non-breaking behavior by keeping existing `engine:runtime-error` and `trackRuntimeError(...)` flow unchanged.
+
+## Files
+- `src/engine/runtime/RuntimeMonitoringHooks.js`
+- `src/engine/runtime/index.js`
+- `src/engine/core/Engine.js`
+- `tools/shared/platformShell.js`
+- `tests/runtime/RuntimeMonitoringHooks.test.mjs`
+- `tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs`
+- `tests/run-tests.mjs`

docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_LOGGING_STANDARD.md

@@ -0,0 +1,24 @@
+# BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION — Logging Standard
+
+## Logging Baseline
+- Existing standardized logger format remains authoritative:
+  - `format: engine.log.v1`
+- This PR adds runtime monitoring event usage aligned to that format:
+  - `runtime.monitoring.error`
+  - `runtime.monitoring.performance`
+
+## Standardized Expectations
+- Every emitted logger entry includes:
+  - `format`
+  - `level`
+  - `channel`
+  - `event`
+  - `message`
+  - `meta`
+  - `timestamp`
+- Runtime monitoring payload contract is versioned separately as:
+  - `format: runtime.monitoring.v1`
+
+## Non-Breaking Guarantee
+- Existing logger behavior is unchanged.
+- Existing engine runtime error/performance events are preserved.

docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_PERFORMANCE_MONITORING.md

@@ -0,0 +1,22 @@
+# BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION — Performance Monitoring
+
+## Scope Implemented
+- Added shared runtime performance sampling via `createRuntimeMonitoringHooks(...)`.
+- Hook emits performance samples at runtime start and on configured interval.
+- Engine now starts/stops monitoring with runtime lifecycle.
+- Tools platform shell now starts/stops monitoring for tool runtime surfaces.
+
+## Monitoring Payload
+- Format: `runtime.monitoring.v1`
+- Kind: `performance`
+- Fields:
+  - `source`
+  - `reason` (`start`, `interval`, `manual`)
+  - `timestamp`
+  - `sample.nowMs`
+  - optional `sample.memory` (when available)
+  - `context`
+
+## Validation Notes
+- Targeted tests verify start sample, interval sample, and manual sample behavior.
+- Existing lifecycle validation confirms engine performance frame publication remains intact (`engine:performance-frame`).

docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_VALIDATION.md

@@ -0,0 +1,29 @@
+# BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION — Validation
+
+## Commands Run
+1. `node --input-type=module -e "import { run as runHooks } from './tests/runtime/RuntimeMonitoringHooks.test.mjs'; import { run as runLifecycle } from './tests/runtime/Phase19RuntimeLifecycleValidation.test.mjs'; runHooks(); runLifecycle(); console.log('PASS runtime monitoring + lifecycle');"`
+2. `node --input-type=module -e "import { run as runShell } from './tests/tools/PlatformShellHeaderAlignment.test.mjs'; runShell(); console.log('PASS platform shell header alignment');"`
+
+## Results
+- PASS runtime monitoring + lifecycle
+- PASS platform shell header alignment
+
+## Validation Coverage
+- Runtime hook payload contracts (`runtime.monitoring.v1`) validated.
+- Runtime lifecycle integration (engine start/stop monitoring) validated.
+- Existing runtime lifecycle and logging format behavior validated.
+- Tools shell integration change validated against existing shell alignment test surface.
+
+## Roadmap Status Handling
+- Checked `docs/dev/roadmaps/MASTER_ROADMAP_ENGINE.md` Track 20B.
+- Items were already `[x]` before this PR:
+  - runtime error tracking
+  - performance monitoring hooks
+  - logging standardization
+- No roadmap text rewrite performed.
+- No non-status roadmap edits performed.
+
+## Scope Confirmation
+- No `start_of_day` changes.
+- No unrelated cleanup.
+- Smallest scoped implementation for runtime monitoring/logging foundation.

docs/pr/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION.md

@@ -0,0 +1,27 @@
+# BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION
+
+## Purpose
+Establish runtime monitoring, error tracking, and logging standardization across the system.
+
+## Scope
+- runtime error tracking hooks
+- performance monitoring hooks
+- logging standardization baseline
+
+## Roadmap Advancement
+
+### Track B — Stability & Monitoring
+- `runtime error tracking` [ ] -> [x]
+- `performance monitoring hooks` [ ] -> [x]
+- `logging standardization` [ ] -> [x]
+
+## Required Outputs
+- docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_ERROR_TRACKING.md
+- docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_PERFORMANCE_MONITORING.md
+- docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_LOGGING_STANDARD.md
+- docs/dev/reports/BUILD_PR_LEVEL_22_1_RUNTIME_MONITORING_AND_LOGGING_FOUNDATION_VALIDATION.md
+
+## Rules
+- no breaking changes
+- no feature expansion
+- no start_of_day changes

src/engine/core/Engine.js

@@ -10,7 +10,13 @@ import FrameClock from './FrameClock.js';
 import FixedTicker from './FixedTicker.js';
 import EventBus from '../events/EventBus.js';
 import { Camera3D } from '../camera/index.js';
-import { backgroundImage, fullscreenBezel, FullscreenService, resolvePreferredFullscreenTarget } from '../runtime/index.js';
+import {
+  backgroundImage,
+  fullscreenBezel,
+  FullscreenService,
+  resolvePreferredFullscreenTarget,
+  createRuntimeMonitoringHooks
+} from '../runtime/index.js';
 import { AudioService } from '../audio/index.js';
 import { Logger } from '../logging/index.js';
 import { SettingsSystem } from '../release/index.js';
@@ -33,6 +39,7 @@ export default class Engine {
     logger = null,
     camera3D = null,
     runtimeHooks = null,
+    runtimeMonitoring = null,
   } = {}) {
     if (!canvas) {
       throw new Error('Engine requires a canvas.');
@@ -75,6 +82,20 @@ export default class Engine {
       onError: typeof runtimeHooks?.onError === 'function' ? runtimeHooks.onError : null,
       onPerformance: typeof runtimeHooks?.onPerformance === 'function' ? runtimeHooks.onPerformance : null,
     };
+    this.runtimeMonitoring = runtimeMonitoring || createRuntimeMonitoringHooks({
+      logger: this.logger,
+      source: 'engine',
+      sampleIntervalMs: 10000,
+      onError: (payload) => {
+        this.events?.emit?.('engine:runtime-monitoring-error', payload);
+      },
+      onPerformance: (payload) => {
+        this.events?.emit?.('engine:runtime-monitoring-performance', payload);
+      },
+      contextProvider: () => ({
+        sceneType: this.scene?.constructor?.name || '',
+      }),
+    });
     this.camera3D = camera3D || new Camera3D();
     this.settings = new SettingsSystem({
       namespace: 'toolboxaid:engine-settings',
@@ -202,6 +223,15 @@ export default class Engine {
 
     this.frameClock.reset();
     this.fixedTicker.reset();
+    try {
+      this.runtimeMonitoring?.start?.();
+    } catch (error) {
+      this.trackRuntimeError('runtimeMonitoring.start', error, {
+        severity: 'warn',
+        isolated: true,
+        message: 'Engine runtime monitoring hooks failed to start.',
+      });
+    }
     this.rafId = requestAnimationFrame(this.tick);
   }
 
@@ -223,6 +253,15 @@ export default class Engine {
     if (this.fullscreenBezelLayer && typeof this.fullscreenBezelLayer.detach === 'function') {
       this.fullscreenBezelLayer.detach();
     }
+    try {
+      this.runtimeMonitoring?.stop?.();
+    } catch (error) {
+      this.trackRuntimeError('runtimeMonitoring.stop', error, {
+        severity: 'warn',
+        isolated: true,
+        message: 'Engine runtime monitoring hooks failed to stop.',
+      });
+    }
   }
 
   tick(now) {