Introduce minimal 3D camera foundation<BUILD_PR_LEVEL_17_3_CAMERA_FOUNDATION>

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,8 +2,8 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Implement isolated 3D scene boot:
-- add 3D scene initializer
-- hook render pipeline safely
-- do not modify existing 2D paths
-- validate all 2D samples still run
+Implement minimal 3D camera:
+- create camera state (position, rotation)
+- integrate into scene safely
+- ensure no impact to 2D camera
+- validate all samples still pass

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_17_2_RENDER_SCENE_BOOT_VALIDATION - safe 3D scene boot + render hook
+Introduce minimal 3D camera foundation<BUILD_PR_LEVEL_17_3_CAMERA_FOUNDATION>

docs/dev/reports/launch_smoke_report.md

@@ -1,6 +1,6 @@
 # Launch Smoke Report
 
-Generated: 2026-04-15T19:00:55.207Z
+Generated: 2026-04-15T19:11:35.746Z
 
 Filters: games=false, samples=true, tools=false, sampleRange=all
 

docs/dev/reports/validation_report.txt

@@ -1 +1 @@
-Post-run: confirm 2D stability + 3D boot success
+Post-run: verify camera init + no regression

docs/pr/BUILD_PR_LEVEL_17_3_CAMERA_FOUNDATION.md

@@ -0,0 +1,18 @@
+# BUILD PR: 17.3 Camera Foundation (3D Safe Introduction)
+
+## Purpose
+Introduce a minimal 3D camera system without impacting 2D camera.
+
+## Scope
+- Add 3D camera model (position, rotation)
+- Non-invasive integration point
+- No modification to 2D camera
+
+## Testability
+- 2D camera unaffected
+- 3D camera can initialize and update safely
+
+## Acceptance
+- [ ] Engine boot passes
+- [ ] 2D camera unchanged
+- [ ] 3D camera initializes and updates

src/engine/camera/Camera3D.js

@@ -0,0 +1,55 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/15/2026
+Camera3D.js
+*/
+function toVector3(value, fallback) {
+  if (!value || typeof value !== 'object') {
+    return { ...fallback };
+  }
+
+  return {
+    x: Number.isFinite(value.x) ? value.x : fallback.x,
+    y: Number.isFinite(value.y) ? value.y : fallback.y,
+    z: Number.isFinite(value.z) ? value.z : fallback.z,
+  };
+}
+
+export default class Camera3D {
+  constructor({ position = null, rotation = null } = {}) {
+    this.position = toVector3(position, { x: 0, y: 0, z: 0 });
+    this.rotation = toVector3(rotation, { x: 0, y: 0, z: 0 });
+  }
+
+  setPosition(position = {}) {
+    this.position = toVector3(position, this.position);
+    return this.getState();
+  }
+
+  setRotation(rotation = {}) {
+    this.rotation = toVector3(rotation, this.rotation);
+    return this.getState();
+  }
+
+  translate({ x = 0, y = 0, z = 0 } = {}) {
+    this.position.x += Number.isFinite(x) ? x : 0;
+    this.position.y += Number.isFinite(y) ? y : 0;
+    this.position.z += Number.isFinite(z) ? z : 0;
+    return this.getState();
+  }
+
+  rotate({ x = 0, y = 0, z = 0 } = {}) {
+    this.rotation.x += Number.isFinite(x) ? x : 0;
+    this.rotation.y += Number.isFinite(y) ? y : 0;
+    this.rotation.z += Number.isFinite(z) ? z : 0;
+    return this.getState();
+  }
+
+  getState() {
+    return {
+      position: { ...this.position },
+      rotation: { ...this.rotation },
+    };
+  }
+}

src/engine/camera/index.js

@@ -5,5 +5,6 @@ David Quesenberry
 index.js
 */
 export { default as Camera2D } from './Camera2D.js';
+export { default as Camera3D } from './Camera3D.js';
 export { followCameraTarget, worldRectToScreen } from './CameraSystem.js';
 export { updateZoneCamera } from './ZoneCameraSystem.js';

src/engine/core/Engine.js

@@ -9,6 +9,7 @@ import RuntimeMetrics from './RuntimeMetrics.js';
 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 { AudioService } from '../audio/index.js';
 import { Logger } from '../logging/index.js';
@@ -30,6 +31,7 @@ export default class Engine {
     fullscreenBezelLayer = null,
     audio = null,
     logger = null,
+    camera3D = null,
   } = {}) {
     if (!canvas) {
       throw new Error('Engine requires a canvas.');
@@ -68,6 +70,7 @@ export default class Engine {
     });
     this.audio = audio || new AudioService();
     this.logger = logger || new Logger({ channel: 'engine' });
+    this.camera3D = camera3D || new Camera3D();
     this.settings = new SettingsSystem({
       namespace: 'toolboxaid:engine-settings',
       defaults: {
@@ -97,12 +100,42 @@ export default class Engine {
     }
 
     this.scene = scene;
+    this.attachScene3DCamera(this.scene);
 
     if (this.scene && typeof this.scene.enter === 'function') {
       this.scene.enter(this);
     }
   }
 
+  attachScene3DCamera(scene) {
+    if (!scene || !this.camera3D) {
+      return;
+    }
+
+    if (typeof scene.setCamera3D === 'function') {
+      try {
+        scene.setCamera3D(this.camera3D, this);
+      } catch (error) {
+        this.logger?.warn?.('Engine scene setCamera3D hook failed.', {
+          error: error?.message || String(error),
+        });
+      }
+      return;
+    }
+
+    if (scene.camera3D !== undefined && scene.camera3D !== null) {
+      return;
+    }
+
+    try {
+      scene.camera3D = this.camera3D;
+    } catch (error) {
+      this.logger?.warn?.('Engine scene camera3D assignment failed.', {
+        error: error?.message || String(error),
+      });
+    }
+  }
+
   start() {
     if (this.input && typeof this.input.attach === 'function') {
       this.input.attach();

src/engine/core/index.js

@@ -11,4 +11,4 @@ export { default as RuntimeMetrics } from './RuntimeMetrics.js';
 
 // Baseline core service cluster exports (timing/frame, event routing, camera integration).
 export { EventBus } from '../events/index.js';
-export { Camera2D, followCameraTarget, worldRectToScreen, updateZoneCamera } from '../camera/index.js';
+export { Camera2D, Camera3D, followCameraTarget, worldRectToScreen, updateZoneCamera } from '../camera/index.js';

tests/core/EngineCoreBoundaryBaseline.test.mjs

@@ -68,6 +68,20 @@ export function run() {
   assert.equal(typeof rect.y, 'number');
   assert.equal(rect.width, 10);
   assert.equal(rect.height, 10);
+
+  const camera3D = new core.Camera3D({
+    position: { x: 1, y: 2, z: 3 },
+    rotation: { x: 0.1, y: 0.2, z: 0.3 },
+  });
+  camera3D.translate({ x: 2, y: -1, z: 5 });
+  camera3D.rotate({ y: 0.5 });
+  const camera3DState = camera3D.getState();
+  assert.equal(camera3DState.position.x, 3);
+  assert.equal(camera3DState.position.y, 1);
+  assert.equal(camera3DState.position.z, 8);
+  assert.equal(camera3DState.rotation.x, 0.1);
+  assert.equal(camera3DState.rotation.y, 0.7);
+  assert.equal(camera3DState.rotation.z, 0.3);
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {