Add ProjectDocument support for scene building and validation

tests/unit/first-person-navigation-controller.test.ts

@@ -162,6 +162,43 @@ describe("FirstPersonNavigationController", () => {
     expect(exitPointerLockSpy).toHaveBeenCalledTimes(1);
   });
 
+  it("applies authored horizontal mouse inversion while pointer-locked", () => {
+    const playerStart = createPlayerStartEntity({
+      id: "entity-player-start-invert-first-person",
+      invertMouseCameraHorizontal: true
+    });
+    const { context, domElement } = createRuntimeControllerContext(playerStart);
+    const controller = new FirstPersonNavigationController();
+    const mouseMoveEvent = new MouseEvent("mousemove");
+
+    Object.defineProperty(mouseMoveEvent, "movementX", {
+      configurable: true,
+      value: 20
+    });
+    Object.defineProperty(mouseMoveEvent, "movementY", {
+      configurable: true,
+      value: 0
+    });
+    Object.defineProperty(document, "pointerLockElement", {
+      configurable: true,
+      get: () => domElement
+    });
+
+    controller.activate(context);
+    document.dispatchEvent(mouseMoveEvent);
+    controller.update(0);
+
+    const telemetry =
+      context.setPlayerControllerTelemetry.mock.calls.at(-1)?.[0];
+
+    expect(telemetry?.pointerLocked).toBe(true);
+    expect(telemetry?.yawDegrees).toBeGreaterThan(0);
+
+    controller.deactivate(context, {
+      releasePointerLock: false
+    });
+  });
+
   it("uses authored gamepad bindings instead of the hardcoded stick mapping", () => {
     const playerStart = createPlayerStartEntity({
       id: "entity-player-start-custom-gamepad",

tests/unit/runtime-host.test.ts

@@ -3773,6 +3773,64 @@ describe("RuntimeHost", () => {
     host.dispose();
   });
 
+  it("preserves pointer lock when switching between first- and third-person controllers", () => {
+    const host = new RuntimeHost({
+      enableRendering: false
+    });
+    const runtimeScene = buildRuntimeSceneFromDocument(
+      createEmptySceneDocument(),
+      {
+        navigationMode: "firstPerson"
+      }
+    );
+    const hostInternals = host as unknown as {
+      activeController: {
+        id: "firstPerson" | "thirdPerson";
+        deactivate: ReturnType<typeof vi.fn>;
+      } | null;
+      controllerContext: unknown;
+      desiredNavigationMode: "firstPerson" | "thirdPerson";
+      runtimeScene: ReturnType<typeof buildRuntimeSceneFromDocument> | null;
+      sceneReady: boolean;
+      thirdPersonController: {
+        id: "thirdPerson";
+        activate: ReturnType<typeof vi.fn>;
+      };
+      activateDesiredNavigationController(): void;
+    };
+    const deactivate = vi.fn();
+    const activate = vi.fn();
+    const domElement = (
+      host as unknown as {
+        domElement: HTMLCanvasElement;
+      }
+    ).domElement;
+
+    hostInternals.runtimeScene = runtimeScene;
+    hostInternals.sceneReady = true;
+    hostInternals.activeController = {
+      id: "firstPerson",
+      deactivate
+    };
+    hostInternals.desiredNavigationMode = "thirdPerson";
+    hostInternals.thirdPersonController = {
+      id: "thirdPerson",
+      activate
+    };
+    Object.defineProperty(document, "pointerLockElement", {
+      configurable: true,
+      get: () => domElement
+    });
+
+    hostInternals.activateDesiredNavigationController();
+
+    expect(deactivate).toHaveBeenCalledWith(hostInternals.controllerContext, {
+      releasePointerLock: false
+    });
+    expect(activate).toHaveBeenCalledWith(hostInternals.controllerContext);
+    host.dispose();
+  });
+
   it("switches an active target once from directional screen-space look input", () => {
     const host = new RuntimeHost({
       enableRendering: false

tests/unit/third-person-navigation-controller.test.ts

@@ -171,6 +171,43 @@ describe("ThirdPersonNavigationController", () => {
     controller.deactivate(context);
   });
 
+  it("captures pointer-locked third-person mouse look and honors horizontal inversion", () => {
+    const playerStart = createPlayerStartEntity({
+      id: "entity-player-start-invert-third-person",
+      invertMouseCameraHorizontal: true
+    });
+    const { context, domElement } = createRuntimeControllerContext(playerStart);
+    const controller = new ThirdPersonNavigationController();
+    const mouseMoveEvent = new MouseEvent("mousemove");
+
+    Object.defineProperty(mouseMoveEvent, "movementX", {
+      configurable: true,
+      value: 24
+    });
+    Object.defineProperty(mouseMoveEvent, "movementY", {
+      configurable: true,
+      value: 0
+    });
+    Object.defineProperty(document, "pointerLockElement", {
+      configurable: true,
+      get: () => domElement
+    });
+
+    controller.activate(context);
+    document.dispatchEvent(mouseMoveEvent);
+    controller.update(0);
+
+    const telemetry =
+      context.setPlayerControllerTelemetry.mock.calls.at(-1)?.[0];
+
+    expect(telemetry?.pointerLocked).toBe(true);
+    expect(context.camera.position.x).toBeLessThan(0);
+
+    controller.deactivate(context, {
+      releasePointerLock: false
+    });
+  });
+
   it("smooths the third-person camera back out when collision clears", () => {
     const { context } = createRuntimeControllerContext();
     const controller = new ThirdPersonNavigationController();