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

package/src/__tests__/postprocess-camera-consistency.test.ts

@@ -0,0 +1,375 @@
+// m2-t4: postProcessParams <-> cameras same-origin constraint test (TDD red).
+//
+// Test R-6 risk mitigation: the merged frame's postProcessParams and cameras
+// must come from the same (owner) world, because the built-in tonemap provider
+// reads cameras[0] (render-system-extract.ts:3341-3351) and the two must be
+// atomically consistent.
+//
+// Construct dual-world scenario:
+//   - owner world A has postProcessParams + camera
+//   - world B has different postProcessParams + camera
+// Assert after merge: postProcessParams and cameras both come from owner A.
+// Non-owner B's postProcessParams are discarded.
+//
+// Anchors:
+//   plan-tasks.json m2-t4
+//   plan-strategy D-3 (owner snapshot holistic selection)
+//   research Finding 3 / R-6
+//   requirements AC-05/06
+
+import { World } from '@forgeax/engine-ecs';
+import { Camera, PostProcessParams } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import type { CameraSnapshot } from '../../../render/src/render-contract';
+import type { ExtractedFrame } from '../../../render/src/render-system-extract';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function identityTransform(): {
+  pos: [number, number, number];
+  quat: [number, number, number, number];
+  scale: [number, number, number];
+} {
+  return {
+    pos: [0, 0, 0],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+}
+
+/**
+ * Simulate the D-3 merge that extractFrames will implement, specifically
+ * for postProcessParams and cameras same-origin verification.
+ *
+ * Per D-3: cameras + postProcessParams are taken from the owner world's
+ * frame holistically. Non-owner's same-type items are discarded.
+ */
+function simulateMergeWithOwnerSelection(
+  frames: ExtractedFrame[],
+  ownerIndex: number,
+): {
+  cameras: CameraSnapshot[];
+  postProcessParams: ReadonlyMap<string, Uint8Array>;
+  singleWorldCameras: CameraSnapshot[][];
+  singleWorldPostProcess: ReadonlyMap<string, Uint8Array>[];
+} {
+  // biome-ignore lint/style/noNonNullAssertion: ownerIndex is validated, frames is dense
+  const ownerFrame = frames[ownerIndex]!;
+
+  // D-3: cameras only from owner world
+  const cameras = [...ownerFrame.cameras];
+
+  // D-3: postProcessParams only from owner world
+  const postProcessParams = new Map(ownerFrame.postProcessParams);
+
+  return {
+    cameras,
+    postProcessParams,
+    singleWorldCameras: frames.map((f) => f.cameras),
+    singleWorldPostProcess: frames.map((f) => f.postProcessParams),
+  };
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('postProcessParams <-> cameras same-origin constraint (m2-t4, R-6)', () => {
+  // ── R-6: postProcessParams and cameras from same world ─────────────────────
+
+  it('R-6: merged postProcessParams and cameras both come from owner world', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            near: 0.1,
+            far: 100,
+            aspect: 1,
+            clearColor: [0.1, 0.2, 0.3, 1],
+          },
+        },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::owner-effect',
+            data: new Uint8Array([1, 2, 3]),
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 3,
+            near: 0.5,
+            far: 50,
+            aspect: 2,
+            clearColor: [0.9, 0.8, 0.7, 1],
+          },
+        },
+      )
+      .unwrap();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::non-owner-effect',
+            data: new Uint8Array([9, 9, 9]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    // Verify both worlds have their own cameras and postProcessParams
+    expect(frameA.cameras.length).toBeGreaterThanOrEqual(1);
+    expect(frameB.cameras.length).toBeGreaterThanOrEqual(1);
+    expect(frameA.postProcessParams.has('forgeax::owner-effect')).toBe(true);
+    expect(frameB.postProcessParams.has('forgeax::non-owner-effect')).toBe(true);
+
+    // owner=0 (worldA)
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // Cameras come from owner world A
+    expect(merged.cameras.length).toBe(frameA.cameras.length);
+    // postProcessParams come from owner world A
+    expect(merged.postProcessParams.has('forgeax::owner-effect')).toBe(true);
+    // Non-owner's postProcessParams are discarded
+    expect(merged.postProcessParams.has('forgeax::non-owner-effect')).toBe(false);
+
+    // owner=1 (worldB)
+    const merged2 = simulateMergeWithOwnerSelection([frameA, frameB], 1);
+
+    // Cameras come from owner world B
+    expect(merged2.cameras.length).toBe(frameB.cameras.length);
+    // postProcessParams come from owner world B
+    expect(merged2.postProcessParams.has('forgeax::non-owner-effect')).toBe(true);
+    expect(merged2.postProcessParams.has('forgeax::owner-effect')).toBe(false);
+  });
+
+  // ── Non-owner postProcessParams discarded ──────────────────────────────────
+
+  it('R-6: non-owner postProcessParams are discarded, not merged', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: Camera, data: { fov: Math.PI / 4, near: 0.1, far: 100, aspect: 1 } },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-a',
+            data: new Uint8Array([1]),
+          },
+        },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-b',
+            data: new Uint8Array([2]),
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-c',
+            data: new Uint8Array([3]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // Owner's params are present
+    expect(merged.postProcessParams.has('forgeax::effect-a')).toBe(true);
+    expect(merged.postProcessParams.has('forgeax::effect-b')).toBe(true);
+    // Non-owner's params are discarded
+    expect(merged.postProcessParams.has('forgeax::effect-c')).toBe(false);
+  });
+
+  // ── Empty world postProcessParams ──────────────────────────────────────────
+
+  it('R-6: when owner world has no user PostProcessParams, only engine-injected tonemap is present', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: Camera, data: { fov: Math.PI / 4, near: 0.1, far: 100, aspect: 1 } },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-b',
+            data: new Uint8Array([2]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    // owner=0: worldA has no user PostProcessParams, but has a camera
+    // so engine injects forgeax::tonemap
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // Non-owner's user-defined postProcessParams are NOT carried over
+    expect(merged.postProcessParams.has('forgeax::effect-b')).toBe(false);
+    // But owner's engine-injected forgeax::tonemap is present
+    // (camera exists, so engine provides it)
+    const ownerHasTonemap = frameA.postProcessParams.has('forgeax::tonemap');
+    expect(merged.postProcessParams.has('forgeax::tonemap')).toBe(ownerHasTonemap);
+  });
+
+  // ── Same-origin: cameras[0] exists in the same world as postProcessParams ──
+
+  it('R-6: tonemap hidden dependency safety — cameras[0] and postProcessParams from same owner', () => {
+    // The built-in tonemap provider reads cameras[0] (render-system-extract.ts:3341-3351).
+    // If postProcessParams came from owner but cameras came from non-owner,
+    // the tonemap would read the wrong camera's exposure/tonemap/whitePoint.
+    // This test verifies the merge contract guarantees they are same-origin.
+
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            near: 0.1,
+            far: 100,
+            aspect: 1,
+            tonemap: 1, // 'reinhard'
+            exposure: 1.5,
+            whitePoint: 3.0,
+          },
+        },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::custom-effect',
+            data: new Uint8Array([1, 2, 3]),
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 3,
+            near: 0.5,
+            far: 50,
+            aspect: 2,
+            tonemap: 0, // 'none'
+            exposure: 0.5,
+            whitePoint: 1.0,
+          },
+        },
+      )
+      .unwrap();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::other-effect',
+            data: new Uint8Array([9, 9, 9]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // postProcessParams and cameras[0] both come from owner worldA
+    expect(merged.cameras.length).toBeGreaterThanOrEqual(1);
+    expect(merged.cameras[0]?.exposure).toBe(1.5);
+    expect(merged.cameras[0]?.whitePoint).toBe(3.0);
+
+    // Owner's user-defined postProcessParams are carried over
+    expect(merged.postProcessParams.has('forgeax::custom-effect')).toBe(true);
+    // Non-owner's user-defined postProcessParams are discarded
+    expect(merged.postProcessParams.has('forgeax::other-effect')).toBe(false);
+
+    // When owner=1 (worldB), cameras[0] has different values
+    const merged2 = simulateMergeWithOwnerSelection([frameA, frameB], 1);
+    expect(merged2.cameras[0]?.exposure).toBe(0.5);
+    expect(merged2.cameras[0]?.whitePoint).toBe(1.0);
+
+    // Owner=1's user-defined postProcessParams are carried over
+    expect(merged2.postProcessParams.has('forgeax::other-effect')).toBe(true);
+    // Non-owner's user-defined postProcessParams are discarded
+    expect(merged2.postProcessParams.has('forgeax::custom-effect')).toBe(false);
+
+    // Both frames have engine-injected forgeax::tonemap (because both have cameras).
+    // When owner=0, the forgeax::tonemap comes from worldA's camera context.
+    // When owner=1, it comes from worldB's camera context.
+    // Both are present because each owner has a camera.
+    expect(merged.postProcessParams.has('forgeax::tonemap')).toBe(
+      frameA.postProcessParams.has('forgeax::tonemap'),
+    );
+    expect(merged2.postProcessParams.has('forgeax::tonemap')).toBe(
+      frameB.postProcessParams.has('forgeax::tonemap'),
+    );
+  });
+});

package/src/__tests__/profiler-assembly.integration.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createProfiler } from '@forgeax/engine-profiler';
+import type { RendererOptions } from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+
+describe('runtime profiler assembly', () => {
+  it('accepts the host profiler capability without creating a second owner', () => {
+    const profiler = createProfiler();
+    const options = { profiler } satisfies RendererOptions;
+
+    expect(options.profiler).toBe(profiler);
+    expect(profiler.activeSession()).toBeUndefined();
+  });
+
+  it('forwards the explicit capability and keeps runtime free of Remote and CLI ownership', () => {
+    const source = readFileSync(
+      fileURLToPath(new URL('../createRenderer.ts', import.meta.url)),
+      'utf8',
+    );
+
+    expect(source).toContain('profiler');
+    expect(source).not.toContain('@forgeax/engine-remote');
+    expect(source).not.toContain('phaseCatalog');
+    expect(source).not.toContain('createProfiler');
+  });
+
+  it('preserves capture completeness across stop and overflow boundaries', () => {
+    const stopped = createProfiler();
+    const stoppedSession = stopped.startCapture({ frameLimit: 2, eventLimit: 8 });
+    expect(stoppedSession.ok).toBe(true);
+    if (!stoppedSession.ok) return;
+    expect(stoppedSession.value.beginFrame(1).ok).toBe(true);
+    expect(stoppedSession.value.endFrame().ok).toBe(true);
+    const partial = stoppedSession.value.finish();
+    expect(partial.ok).toBe(true);
+    if (partial.ok) expect(partial.value.completeness.status).toBe('partial');
+
+    const overflow = createProfiler({ phaseCatalog: { app: [], render: ['record'] } });
+    const overflowSession = overflow.startCapture({ frameLimit: 2, eventLimit: 1 });
+    expect(overflowSession.ok).toBe(true);
+    if (!overflowSession.ok) return;
+    for (const frameId of [1, 2]) {
+      expect(overflowSession.value.beginFrame(frameId).ok).toBe(true);
+      expect(
+        overflowSession.value.recordSkip({ source: 'render', phase: 'record', reason: 'no-render' })
+          .ok,
+      ).toBe(true);
+      expect(overflowSession.value.endFrame().ok).toBe(true);
+    }
+    const artifact = overflowSession.value.finish();
+    expect(artifact.ok).toBe(true);
+    if (artifact.ok) expect(artifact.value.completeness.status).toBe('overflow');
+  });
+
+  it('isolates sink Result.err and thrown failures without losing latest capture', () => {
+    for (const sink of [
+      { write: () => ({ ok: false as const, error: { code: 'sink-rejected' } }) },
+      {
+        write: () => {
+          throw new Error('sink-threw');
+        },
+      },
+    ]) {
+      const profiler = createProfiler({ sink });
+      const session = profiler.startCapture({ frameLimit: 1, eventLimit: 4 });
+      expect(session.ok).toBe(true);
+      if (!session.ok) continue;
+      const result = session.value.finish();
+      expect(result.ok).toBe(false);
+      expect(profiler.latestCapture()).toBeDefined();
+    }
+  });
+});

package/src/__tests__/propagate-transforms.dawn.test.ts

@@ -0,0 +1,254 @@
+// propagate-transforms.dawn.test.ts -- vitest dawn project (AC-04) CPU-only
+// propagateTransforms behaviour test.
+//
+// Trigger: root vitest.config.ts `dawn` project (`*.dawn.test.ts` glob).
+// Environment: node + setupFiles ./vitest.setup-webgpu.ts injects
+//   globalThis.navigator.gpu (provided by dawn.node native binding).
+//
+// feat-20260601 M4: GlobalTransform is retired. propagateTransforms now writes
+// the resolved world mat4 into the `Transform.world` column (column-major 16
+// floats). Tests read that column via the ECS array view and assert the
+// translation column (m[12,13,14]).
+//
+// Scope (w6 acceptanceCheck):
+//   (a) root-only entity: Transform.world translation = local translation
+//   (b) 2-level hierarchy: child.world = parent.world x child local
+//   (c) stale ChildOf ref: Result.err(RhiError({ code: 'hierarchy-broken' }))
+//   (d) N=3 deep chain: composition stacks correctly
+//
+// Although propagateTransforms is pure CPU code (no GPU access), the test is
+// duplicated under the dawn layer so the AC-04 gate executes in both the
+// browser GPU env and the dawn-node env -- matching plan-strategy §4 test
+// matrix + requirements AC-04 two-layer coverage.
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { readRenderArrayView } from '@forgeax/engine-ecs/projection';
+import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { TileLayer, Tilemap } from '../../../render/src/components';
+
+function identityTransformData() {
+  return {
+    pos: [0, 0, 0],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+}
+
+// Read the resolved world mat4 (column-major 16 floats) from the Transform
+// world column array view. Translation lives in column 3 (m[12,13,14]).
+function worldOf(world: World, entity: EntityHandle): Float32Array {
+  const view = readRenderArrayView(world, entity, Transform, 'world');
+  if (view === undefined) throw new Error('Transform.world view missing');
+  return view as Float32Array;
+}
+
+describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (AC-04)', () => {
+  it('root entity: Transform.world translation = local translation (identity chain)', () => {
+    const world = new World();
+    const root = world
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [3, 4, 5],
+          quat: [0, 0, 0, 1],
+          scale: [2, 2, 2],
+        },
+      })
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const w = worldOf(world, root);
+    expect(w.length).toBe(16);
+    expect(w[12]).toBeCloseTo(3, 5);
+    expect(w[13]).toBeCloseTo(4, 5);
+    expect(w[14]).toBeCloseTo(5, 5);
+    // Scale 2 lands on the diagonal of the rotation/scale 3x3 block.
+    expect(w[0]).toBeCloseTo(2, 5);
+  });
+
+  it('2-level hierarchy: child.world = parent.world x child local (translation compose)', () => {
+    const world = new World();
+    const root = world
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [10, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      })
+      .unwrap();
+    const child = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [2, 3, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const wc = worldOf(world, child);
+    // parent translation (10,0,0) composed with child local translation
+    // (2,3,0) and identity rotation/scale -> world position (12,3,0).
+    expect(wc[12]).toBeCloseTo(12, 5);
+    expect(wc[13]).toBeCloseTo(3, 5);
+    expect(wc[14]).toBeCloseTo(0, 5);
+    // Root world translation unaffected (identity chain writes).
+    const wr = worldOf(world, root);
+    expect(wr[12]).toBeCloseTo(10, 5);
+  });
+
+  it('N=3 deep hierarchy: grandchild position chains through two parent translations', () => {
+    const world = new World();
+    const root = world
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [1, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      })
+      .unwrap();
+    const mid = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [2, 0, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const leaf = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [4, 0, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: ChildOf, data: { parent: mid } },
+      )
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const wl = worldOf(world, leaf);
+    // 1 + 2 + 4 = 7 along x-axis.
+    expect(wl[12]).toBeCloseTo(7, 5);
+  });
+
+  // AC-07 (tweak-20260714-tilemap-layer-childed-render-entities M5): TileLayer
+  // as an identity middle node must be transparent to propagateTransforms -- the
+  // layer's Transform.world (16 f32) must equal its Tilemap parent's world mat4
+  // byte-for-byte. This proves M1's coAttach injection produces a genuinely
+  // identity TRS (pos=[0,0,0], quat=[0,0,0,1], scale=[1,1,1]) and the compose
+  // (parent.world x identity) is a no-op in mat4 form.
+  //
+  // FALSIFY note (kept out of the test body per OOS-1 -- non-identity TileLayer
+  // Transform is out of scope for this tweak): if the layer's Transform were
+  // mutated to a non-identity value, propagateTransforms would compose it into
+  // TileLayer.world and the byte-identity assertion below would fail. Not
+  // asserted here because the M1 contract is precisely "identity default,
+  // callers may override" -- the interesting invariant is transparency in the
+  // default case.
+  it('AC-07: identity TileLayer middle node -> Transform.world byte-identical to Tilemap parent', () => {
+    const world = new World();
+    for (const component of [ChildOf, TileLayer, Tilemap, Transform]) {
+      world.components.register(component).unwrap();
+    }
+    // Parent Tilemap carries a non-identity translation so that the identity /
+    // non-identity distinction is observable in the low three translation
+    // slots of the 16-float world mat4.
+    const tilemap = world
+      .spawn(
+        {
+          component: Tilemap,
+          data: { cols: 1, rows: 1, tileSize: [1, 1], chunkSize: 16, tileset: 'test/tileset' },
+        },
+        {
+          component: Transform,
+          data: {
+            pos: [7, -3, 11],
+            quat: [0, 0, 0, 1],
+            scale: [2, 2, 2],
+          },
+        },
+      )
+      .unwrap();
+    // TileLayer carries an explicit identity Transform in the current ECS
+    // component vocabulary. This mirrors the demo spawn pattern in
+    // apps/hello/tilemap/** and keeps the hierarchy contract explicit.
+    const layer = world
+      .spawn(
+        {
+          component: TileLayer,
+          data: {
+            tiles: new Uint32Array([0]),
+            layerOrder: 0,
+            dirty: 1,
+            sortScope: 0,
+          },
+        },
+        { component: ChildOf, data: { parent: tilemap } },
+        { component: Transform, data: identityTransformData() },
+      )
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const wTilemap = worldOf(world, tilemap);
+    const wLayer = worldOf(world, layer);
+    expect(wTilemap.length).toBe(16);
+    expect(wLayer.length).toBe(16);
+    // Byte-identical: identity middle node composes as a no-op. Direct index
+    // comparison (not toBeCloseTo) is the tight assertion -- any floating-point
+    // drift on identity compose would signal a real regression.
+    for (let i = 0; i < 16; i++) {
+      expect(wLayer[i]).toBe(wTilemap[i]);
+    }
+    // Sanity: translation column (m[12..14]) really carries the parent's pos.
+    expect(wLayer[12]).toBeCloseTo(7, 5);
+    expect(wLayer[13]).toBeCloseTo(-3, 5);
+    expect(wLayer[14]).toBeCloseTo(11, 5);
+  });
+
+  it('stale ChildOf ref: Result.err(RhiError({ code: "hierarchy-broken" }))', () => {
+    const world = new World();
+    const ghost = world
+      .spawn({
+        component: Transform,
+        data: identityTransformData(),
+      })
+      .unwrap();
+    world.despawn(ghost).unwrap();
+    const orphan = world
+      .spawn(
+        {
+          component: Transform,
+          data: identityTransformData(),
+        },
+        { component: ChildOf, data: { parent: ghost } },
+      )
+      .unwrap();
+    void orphan;
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.code).toBe('hierarchy-broken');
+    expect(r.error.hint.length).toBeGreaterThan(0);
+    expect(r.error.expected.length).toBeGreaterThan(0);
+  });
+});