@forgeax/engine-app 0.0.0-dev.8d955ade1c79

package/src/__tests__/create-app.test-d.ts

@@ -0,0 +1,83 @@
+// create-app.test-d.ts -- compile-time assertions for w2 acceptanceCheck.
+//
+// Anchors:
+// - createApp(canvas, opts?) returns
+//   Promise<Result<App, AppError | RhiError | EngineEnvironmentError>>
+//   per AC-01 (canvas thin wrapper widens the error union with
+//   EngineEnvironmentError; M2 plugin-system-unify D-7 widens it with
+//   AppError for Cordis activation failures).
+// - createApp({ renderer, world }) returns
+//   Promise<Result<App, AppError | RhiError>>
+//   per AC-02 (assemble form excludes EngineEnvironmentError -- renderer
+//   host-managed).
+// - 'tagName' in arg dispatch lands the right overload at the call site
+//   (HTMLCanvasElement -> canvas form; AppAssembleArgs -> assemble form).
+//
+// charter awareness:
+// - P3 explicit failure: Result envelope shape is type-level (no message strings).
+// - P4 consistent abstraction: both routes return the same App handle.
+
+import type { World } from '@forgeax/engine-ecs';
+import type { RenderError, Renderer, RendererOptions } from '@forgeax/engine-render';
+import type { RhiError } from '@forgeax/engine-rhi/errors';
+import { createRenderer, type EngineEnvironmentError } from '@forgeax/engine-runtime';
+import type { Result } from '@forgeax/engine-types';
+import { describe, expectTypeOf, it } from 'vitest';
+import { type App, type AppError, createApp } from '../index';
+
+describe('createApp double-SSOT entry signatures (w2 acceptanceCheck)', () => {
+  it('canvas form returns the App boundary error union', () => {
+    const canvas = null as unknown as HTMLCanvasElement;
+    const ret = createApp(canvas);
+    expectTypeOf(ret).toEqualTypeOf<
+      Promise<Result<App, AppError | RhiError | EngineEnvironmentError>>
+    >();
+  });
+
+  it('assemble form returns the App boundary error union', () => {
+    const renderer = null as unknown as Renderer;
+    const world = null as unknown as World;
+    const ret = createApp({ renderer, world });
+    expectTypeOf(ret).toEqualTypeOf<Promise<Result<App, AppError | RhiError>>>();
+  });
+
+  it('app.renderer / app.world are reference-equal types at the call site (AC-09)', async () => {
+    const renderer = null as unknown as Renderer;
+    const world = null as unknown as World;
+    const result = await createApp({ renderer, world });
+    if (result.ok) {
+      expectTypeOf(result.value.renderer).toEqualTypeOf<Renderer>();
+      expectTypeOf(result.value.world).toEqualTypeOf<World>();
+    }
+  });
+});
+
+describe('Runtime createRenderer Result boundary (AC-11)', () => {
+  it('requires callers to narrow the construction Result', () => {
+    const canvas = null as unknown as HTMLCanvasElement;
+    const expected = null as unknown as Promise<
+      Result<Renderer, EngineEnvironmentError | RenderError>
+    >;
+    expectTypeOf(createRenderer(canvas)).toEqualTypeOf(expected);
+  });
+});
+
+// feat-20260608-create-app-param-surface-trim / M1 / AC-02 + TASK-006:
+// `RendererOptions.clearColor` was deleted in this feat. AI users that
+// pass `{ clearColor: ... }` to `createRenderer` / `createApp` get a
+// TS2353 excess-property error at compile time (no shim, no
+// deprecation window per AGENTS.md §Change stance).
+describe('RendererOptions.clearColor removal (AC-02 + TASK-006)', () => {
+  it('RendererOptions does not carry a `clearColor` field', () => {
+    // The keyof of RendererOptions must not include 'clearColor'.
+    type Keys = keyof RendererOptions;
+    type HasClearColor = 'clearColor' extends Keys ? true : false;
+    expectTypeOf<HasClearColor>().toEqualTypeOf<false>();
+  });
+
+  it('passing `clearColor` as an object literal is a compile-time error (TS2353)', () => {
+    // @ts-expect-error -- 'clearColor' is not assignable to RendererOptions
+    const opts: RendererOptions = { clearColor: [0, 0, 0, 1] };
+    void opts;
+  });
+});

package/src/__tests__/create-app.test.ts

@@ -0,0 +1,287 @@
+// M3 / w15: FORGEAX_ENGINE_RHI_DEBUG guard three-segment dual-source evaluation.
+//
+// The canvas-form guard in create-app.ts reads the flag from two sources with a
+// precise precedence + short-circuit shape (plan-strategy D-4):
+//
+//   (typeof import.meta !== 'undefined' && import.meta.env?.FORGEAX_ENGINE_RHI_DEBUG)
+//     ?? globalThis.process?.env?.FORGEAX_ENGINE_RHI_DEBUG
+//
+// That expression is extracted into the pure `resolveRhiDebugFlag` helper so the
+// three deployment scenarios can be exercised without a real bundler / runtime:
+//   (a) browser: import.meta.env replaced by the vite define -> '1' wins
+//   (b) dawn-node: import.meta absent (modelled as undefined env) -> falls
+//       through to globalThis.process.env
+//   (c) unset: neither source carries '1' -> undefined -> guard does not fire
+//
+// C5 (plan-strategy): the `typeof import.meta !== 'undefined'` prefix must
+// short-circuit before any `.env` access, because under dawn-node `import.meta`
+// itself can be undefined; passing `undefined` for the import.meta.env arg is
+// the unit-level model of that prefix evaluating to false.
+//
+// OOS-1/2: only the DevTools-trigger path is in scope; this test does not
+// exercise external HTTP triggers or in-page buttons.
+
+import { World } from '@forgeax/engine-ecs';
+import { Camera, orthographic, perspective } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+import { syncCameraAspect, syncCanvasDrawingBuffer } from '../create-app';
+import { resolveRhiDebugFlag } from '../internal/rhi-debug-flag';
+
+describe('create-app.test.ts', () => {
+  describe('resolveRhiDebugFlag three-segment dual-source (w15 / D-4)', () => {
+    it('(a) browser: import.meta.env.FORGEAX_ENGINE_RHI_DEBUG === "1" wins', () => {
+      const flag = resolveRhiDebugFlag(
+        { FORGEAX_ENGINE_RHI_DEBUG: '1' },
+        { FORGEAX_ENGINE_RHI_DEBUG: undefined },
+      );
+      expect(flag).toBe('1');
+    });
+
+    it('(b) dawn-node: import.meta absent -> falls through to process.env', () => {
+      // `undefined` models `typeof import.meta === 'undefined'` short-circuiting
+      // the first operand to a falsy value, so the `??` chain consults process.env.
+      const flag = resolveRhiDebugFlag(undefined, { FORGEAX_ENGINE_RHI_DEBUG: '1' });
+      expect(flag).toBe('1');
+    });
+
+    it('(b2) import.meta.env present but flag unset -> still falls through to process.env', () => {
+      // `import.meta.env` exists (vite always injects it) but the key is absent;
+      // the first operand is `undefined`, so `??` consults process.env.
+      const flag = resolveRhiDebugFlag({}, { FORGEAX_ENGINE_RHI_DEBUG: '1' });
+      expect(flag).toBe('1');
+    });
+
+    it('(c) unset: neither source carries the flag -> undefined (guard does not fire)', () => {
+      expect(resolveRhiDebugFlag(undefined, undefined)).toBeUndefined();
+      expect(resolveRhiDebugFlag({}, {})).toBeUndefined();
+      expect(
+        resolveRhiDebugFlag(
+          { FORGEAX_ENGINE_RHI_DEBUG: undefined },
+          { FORGEAX_ENGINE_RHI_DEBUG: undefined },
+        ),
+      ).toBeUndefined();
+    });
+
+    it('import.meta.env wins over process.env when both set (precedence)', () => {
+      // Browser path takes precedence: the `??` only consults process.env when
+      // the first operand is null/undefined, and '1' is neither.
+      const flag = resolveRhiDebugFlag(
+        { FORGEAX_ENGINE_RHI_DEBUG: '1' },
+        { FORGEAX_ENGINE_RHI_DEBUG: '0' },
+      );
+      expect(flag).toBe('1');
+    });
+
+    it('a non-"1" value is returned verbatim (guard compares === "1" at call site)', () => {
+      // resolveRhiDebugFlag returns the raw flag; the create-app guard does the
+      // `=== '1'` comparison. A '0' value must therefore not be coerced to fire.
+      expect(resolveRhiDebugFlag({ FORGEAX_ENGINE_RHI_DEBUG: '0' }, undefined)).toBe('0');
+    });
+  });
+
+  describe('zero-injection when flag unset (c) (w15 / F-3)', () => {
+    it('globalThis.__forgeax is undefined before any flagged createApp runs', () => {
+      // With the flag unset (the default unit-test environment: no vite define,
+      // no process.env override), the canvas form never touches globalThis, so
+      // the capture entry point does not exist. A DevTools caller invoking it
+      // would hit a TypeError -- the explicit-failure contract (charter P3).
+      const g = globalThis as { __forgeax?: { captureFrame?: unknown } };
+      expect(g.__forgeax).toBeUndefined();
+      expect(() => {
+        // Reading .captureFrame off an undefined __forgeax throws synchronously.
+        (g.__forgeax as { captureFrame: (n: number) => unknown }).captureFrame(1);
+      }).toThrow(TypeError);
+    });
+  });
+
+  describe('syncCanvasDrawingBuffer host boundary', () => {
+    it('matches the physical drawing buffer to CSS size at the device pixel ratio', () => {
+      const canvas = {
+        clientWidth: 800,
+        clientHeight: 400,
+        width: 300,
+        height: 150,
+        style: { width: '800px', height: '400px' },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas);
+        expect(canvas.width).toBe(1600);
+        expect(canvas.height).toBe(800);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+
+    it('leaves a zero-sized host untouched', () => {
+      const canvas = { clientWidth: 0, clientHeight: 400, width: 300, height: 150 };
+      syncCanvasDrawingBuffer(canvas);
+      expect(canvas.width).toBe(300);
+      expect(canvas.height).toBe(150);
+    });
+
+    it('leaves a headless canvas without CSS dimensions untouched', () => {
+      const canvas = { width: 320, height: 180 } as HTMLCanvasElement;
+      syncCanvasDrawingBuffer(canvas);
+      expect(canvas.width).toBe(320);
+      expect(canvas.height).toBe(180);
+    });
+
+    it('preserves an intrinsic canvas drawing buffer without CSS dimensions', () => {
+      let width = 256;
+      let height = 256;
+      const canvas = {
+        get clientWidth() {
+          return width;
+        },
+        get clientHeight() {
+          return height;
+        },
+        get width() {
+          return width;
+        },
+        set width(value: number) {
+          width = value;
+        },
+        get height() {
+          return height;
+        },
+        set height(value: number) {
+          height = value;
+        },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas);
+        syncCanvasDrawingBuffer(canvas);
+        expect(width).toBe(256);
+        expect(height).toBe(256);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+
+    it('does not repeatedly scale a CSS-sized canvas when layout follows width writes', () => {
+      let width = 256;
+      let height = 256;
+      const canvas = {
+        clientWidth: 256,
+        clientHeight: 256,
+        style: { width: '256px', height: '256px' },
+        get width() {
+          return width;
+        },
+        set width(value: number) {
+          width = value;
+          canvas.clientWidth = value;
+        },
+        get height() {
+          return height;
+        },
+        set height(value: number) {
+          height = value;
+          canvas.clientHeight = value;
+        },
+      };
+      const before = globalThis.devicePixelRatio;
+      Object.defineProperty(globalThis, 'devicePixelRatio', { configurable: true, value: 2 });
+      try {
+        syncCanvasDrawingBuffer(canvas);
+        syncCanvasDrawingBuffer(canvas);
+        expect(width).toBe(512);
+        expect(height).toBe(512);
+      } finally {
+        Object.defineProperty(globalThis, 'devicePixelRatio', {
+          configurable: true,
+          value: before,
+        });
+      }
+    });
+  });
+
+  // feat-20260617 M3 / w10: aspect-sync sidecar (createApp path only).
+  // syncCameraAspect is the canvas-form per-frame Update system body
+  // closure calls with the live canvas width/height. It walks Camera entities via
+  // world.get (NOT the query bundle: a bool column read off the bundle returns a
+  // raw 0/1 number, so `!== 0` is always true -- the
+  // bool-field-compared-with-not-equal-zero-always-true trap; D-5/Finding 2). It
+  // writes canvas.width/height into Camera.aspect for perspective + autoAspect=true
+  // cameras only.
+  describe('syncCameraAspect sidecar (w10 / AC-07)', () => {
+    it('canvas resize -> perspective autoAspect=true camera aspect becomes w/h', () => {
+      const world = new World();
+      const cam = world
+        .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1 }) })
+        .unwrap();
+
+      syncCameraAspect(world, 800, 400);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(2, 5);
+    });
+
+    it('autoAspect=false camera is left untouched', () => {
+      const world = new World();
+      const cam = world
+        .spawn({
+          component: Camera,
+          data: perspective({ fov: 1, aspect: 1.234, autoAspect: false }),
+        })
+        .unwrap();
+
+      syncCameraAspect(world, 800, 400);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(1.234, 5);
+    });
+
+    it('canvas size 0 is skipped (no NaN / 0 written into aspect)', () => {
+      const world = new World();
+      const cam = world
+        .spawn({ component: Camera, data: perspective({ fov: 1, aspect: 1.5 }) })
+        .unwrap();
+
+      syncCameraAspect(world, 0, 0);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(1.5, 5);
+      expect(Number.isNaN(r.value.aspect)).toBe(false);
+    });
+
+    it('orthographic camera is left untouched', () => {
+      const world = new World();
+      const cam = world
+        .spawn({
+          component: Camera,
+          data: orthographic({ left: -1, right: 1, bottom: -1, top: 1 }),
+        })
+        .unwrap();
+      const before = world.get(cam, Camera);
+      expect(before.ok).toBe(true);
+      if (!before.ok) return;
+      const aspectBefore = before.value.aspect;
+
+      syncCameraAspect(world, 800, 400);
+
+      const r = world.get(cam, Camera);
+      expect(r.ok).toBe(true);
+      if (!r.ok) return;
+      expect(r.value.aspect).toBeCloseTo(aspectBefore, 5);
+    });
+  });
+});

package/src/__tests__/create-renderer-error.integration.test.ts

@@ -0,0 +1,25 @@
+import { createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
+import { describe, expect, it } from 'vitest';
+import { createApp } from '../create-app';
+
+describe('app renderer construction boundary', () => {
+  it('returns construction failures through the Runtime Result boundary', async () => {
+    const result = await createRenderer(null as never);
+    expect(result.ok).toBe(false);
+  });
+
+  it('returns EngineEnvironmentError through the canvas Result path', async () => {
+    const canvas = {
+      tagName: 'CANVAS',
+      isConnected: true,
+      width: 16,
+      height: 16,
+      getContext: () => null,
+      addEventListener: () => undefined,
+      removeEventListener: () => undefined,
+    } as unknown as HTMLCanvasElement;
+    const result = await createApp(canvas, { rhi: undefined });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error).toBeInstanceOf(EngineEnvironmentError);
+  });
+});

package/src/__tests__/create-renderer-lifecycle.integration.test.ts

@@ -0,0 +1,24 @@
+import type { Renderer } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+describe('app-facing renderer lifecycle', () => {
+  it('consumes the three lifecycle Result boundaries without casts', async () => {
+    const events: string[] = [];
+    const renderer = {
+      attach: () => ({ ok: false as const, error: {} }),
+      draw: () => ({ ok: false as const, error: {} }),
+      observe: async () => ({ ok: false as const, error: {} }),
+      releaseSurface: () => ({ ok: true as const, value: undefined }),
+      restoreSurface: () => ({ ok: true as const, value: undefined }),
+      recover: async () => ({ ok: true as const, value: undefined }),
+      dispose: () => events.push('dispose'),
+      onError: () => () => undefined,
+      onLost: () => () => undefined,
+    } as unknown as Renderer;
+    expect(renderer.attach({} as never).ok).toBe(false);
+    expect(renderer.draw({} as never).ok).toBe(false);
+    renderer.dispose();
+    renderer.dispose();
+    expect(events).toEqual(['dispose', 'dispose']);
+  });
+});

package/src/__tests__/docs-gate-green.unit.test.ts

@@ -0,0 +1,61 @@
+// @perf-budget-skip: intentional documentation subprocess gate.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const repoRoot = resolve(fileURLToPath(new URL('../../../..', import.meta.url)));
+const docsGate = resolve(repoRoot, 'scripts/forgeax/check-token-first-docs.mjs');
+
+function runDocsGate(): { readonly status: number; readonly output: string } {
+  try {
+    const output = execFileSync(process.execPath, [docsGate], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return { status: 0, output };
+  } catch (error: unknown) {
+    const result = error as {
+      readonly status?: number;
+      readonly stdout?: string;
+      readonly stderr?: string;
+    };
+    return {
+      status: result.status ?? 1,
+      output: `${result.stdout ?? ''}${result.stderr ?? ''}`,
+    };
+  }
+}
+
+describe('M5 active-documentation token-first gate', () => {
+  it('keeps the engine-owned active documentation surface present', () => {
+    for (const path of [
+      'packages/ecs/README.md',
+      'packages/app/README.md',
+      'packages/audio-webaudio/README.md',
+      'packages/input/README.md',
+      'packages/runtime/README.md',
+      'packages/state/README.md',
+      'skills/forgeax-engine-ecs/SKILL.md',
+      'skills/forgeax-engine-app/SKILL.md',
+      'skills/forgeax-engine-audio/SKILL.md',
+      'skills/forgeax-engine-state/SKILL.md',
+      'apps/hello/sprite-atlas/README.md',
+      'apps/learn-render/1.getting-started/5.transformations/README.md',
+      'apps/learn-render/1.getting-started/7.camera/README.md',
+      'apps/learn-render/2.lighting/3.materials/README.md',
+      'packages/ecs/CHANGELOG.md',
+    ]) {
+      expect(existsSync(resolve(repoRoot, path)), path).toBe(true);
+    }
+  });
+
+  it('accepts only token-first registration and explicit-delta update examples', () => {
+    const result = runDocsGate();
+    expect(result.status, result.output).toBe(0);
+    expect(result.output).toContain('Active-documentation token-first gate passed');
+  });
+});

package/src/__tests__/draw-source-injected-world-update-visibility.test.ts

@@ -0,0 +1,176 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M2 / w9
+// (RED — impl lands in w12). Contract test: a world injected through drawSource
+// MUST be world.update(1 / 60).unwrap()'d by the frame-loop in the SAME frame it is drawn, so
+// the renderer reads a freshly-propagated Transform.world mat4 — never a stale
+// one.
+//
+// Why this matters (Strategist D-3, not covered by research): the renderer's
+// extract stage reads the DERIVED `Transform.world` column, whose sole writer is
+// the propagateTransforms system (plugin-factories.ts / systems/propagate-
+// transforms.ts). That writer only runs inside `world.update(1 / 60).unwrap()`. If drawSource
+// merely fed injected worlds into `renderer.draw(worlds, ...)` WITHOUT the
+// frame-loop running `world.update(1 / 60).unwrap()` on them first, the renderer would read the
+// injected world's Transform.world at its previous (or default identity) value —
+// a stale-matrix bug that renders the injected world one frame behind (or at the
+// origin on the first frame).
+//
+// This test spawns an entity in the injected world with a DISTINGUISHING
+// non-identity translation and never calls world.update(1 / 60).unwrap() on that world itself.
+// The spy renderer reads `Transform.world` at draw time. A frame-loop that
+// updates injected worlds surfaces the translation in the mat4's column-major
+// [12]/[13]/[14] slots; a draw-only frame-loop surfaces the identity default
+// (0/0/0), which fails the assertion. So the test has genuine discriminating
+// power over the stale-matrix regression.
+//
+// Driven through createFrameLoop directly with injected now / raf / caf seams,
+// mirroring frame-loop-world-array.test.ts. The drawSource option is reached
+// through a typed alias before w12 widens the real FrameLoopOptions type.
+//
+// Anchors:
+//   plan-strategy §2 D-3 (frame-loop MUST update injected worlds — transform
+//     propagation — before draw; not draw-only)
+//   research F1 (frame-loop is the world.update -> renderer.draw driver)
+//   AGENTS.md invariant 6 (Transform.world is the round-trip fidelity seam)
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { createRenderReadLease } from '@forgeax/engine-ecs/projection';
+import type { Renderer } from '@forgeax/engine-render';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createFrameLoop, type FrameLoopOptions } from '../internal/frame-loop';
+
+// Distinguishing translation for the injected world's entity. Column-major mat4
+// carries translation at indices [12] (x), [13] (y), [14] (z).
+const INJECTED_TX = 5;
+const INJECTED_TY = -3;
+const INJECTED_TZ = 7;
+
+function makeSyncScheduler() {
+  let pending: ((t: number) => void) | null = null;
+  let clock = 0;
+  const raf = (cb: (t: number) => void): number => {
+    pending = cb;
+    return 1;
+  };
+  const caf = (): void => {
+    pending = null;
+  };
+  const now = (): number => {
+    clock += 16;
+    return clock;
+  };
+  const pump = (frames: number): void => {
+    for (let i = 0; i < frames; i++) {
+      const cb = pending;
+      pending = null;
+      if (cb === null) break;
+      cb(clock);
+    }
+  };
+  return { raf, caf, now, pump };
+}
+
+type DrawSourceCallback = () =>
+  | { worlds: readonly World[]; cameraOwner: number; resourceOwner: number }
+  | undefined;
+
+type FrameLoopOptionsWithDrawSource = FrameLoopOptions & {
+  drawSource?: DrawSourceCallback;
+};
+
+const createFrameLoopWithDrawSource = createFrameLoop as unknown as (
+  opts: FrameLoopOptionsWithDrawSource,
+) => ReturnType<typeof createFrameLoop>;
+
+describe('drawSource injected worlds are updated same-frame (w9, stale-matrix regression)', () => {
+  it('renderer reads a freshly-propagated Transform.world for the injected world at draw time', () => {
+    // The loop's OWN world — the single-world identity path. Never carries the
+    // injected entity, so it cannot mask a stale read on the injected world.
+    const loopWorld = new World();
+
+    // The injected world: register propagateTransforms (the sole Transform.world
+    // writer) and spawn an entity with a distinguishing non-identity translation.
+    // We deliberately do NOT call injectedWorld.update() here — the frame-loop
+    // must run it for the translation to reach Transform.world.
+    const injectedWorld = new World();
+    registerPropagateTransforms(injectedWorld);
+    const spawned = injectedWorld
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [INJECTED_TX, INJECTED_TY, INJECTED_TZ],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      })
+      .unwrap();
+    const entity = spawned as unknown as EntityHandle;
+
+    // Sanity: BEFORE any frame, Transform.world is still the identity default
+    // (translation columns are 0). This proves the assertion below measures the
+    // frame-loop's update, not a pre-propagated value.
+    const before = injectedWorld.get(entity, Transform);
+    expect(before.ok).toBe(true);
+    if (before.ok) {
+      const w = before.value.world as unknown as ArrayLike<number>;
+      expect(w[12]).toBe(0);
+      expect(w[13]).toBe(0);
+      expect(w[14]).toBe(0);
+    }
+
+    // Spy renderer: at draw time, read the injected world's Transform.world and
+    // record the translation columns. This is the exact read the real extract
+    // stage performs (Transform.world is the extract SSOT).
+    const observed: Array<[number, number, number]> = [];
+    const renderer = {
+      attach: (world: World) => ({ ok: true, value: createRenderReadLease(world) }),
+      draw(): { ok: true; value: undefined } {
+        const r = injectedWorld.get(entity, Transform);
+        if (r.ok) {
+          const m = r.value.world as unknown as ArrayLike<number>;
+          observed.push([m[12] as number, m[13] as number, m[14] as number]);
+        }
+        return { ok: true, value: undefined };
+      },
+      onError(): () => void {
+        return () => {
+          // no-op
+        };
+      },
+      dispose(): void {
+        // no-op
+      },
+    } as unknown as Renderer;
+
+    const drawSource: DrawSourceCallback = () => ({
+      worlds: [injectedWorld],
+      cameraOwner: 0,
+      resourceOwner: 0,
+    });
+
+    const { raf, caf, now, pump } = makeSyncScheduler();
+    const loop = createFrameLoopWithDrawSource({
+      world: loopWorld,
+      renderer,
+      now,
+      raf,
+      caf,
+      drawSource,
+    });
+
+    expect(loop.start().ok).toBe(true);
+    pump(2);
+    loop.stop();
+
+    // At least one frame observed the injected world, and every observation saw
+    // the FRESH translation — the frame-loop ran injectedWorld.update() before
+    // draw. A draw-only frame-loop would observe [0, 0, 0] (identity) and fail.
+    expect(observed.length).toBeGreaterThanOrEqual(1);
+    for (const [x, y, z] of observed) {
+      expect(x).toBeCloseTo(INJECTED_TX);
+      expect(y).toBeCloseTo(INJECTED_TY);
+      expect(z).toBeCloseTo(INJECTED_TZ);
+    }
+  });
+});