@forgeax/engine-scene 0.1.2

package/src/__tests__/asset-owner.integration.test.ts

@@ -0,0 +1,245 @@
+import { defineComponent, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { err, ok, type SceneAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { sceneAssetDecoder } from '../assets/scene-decoder';
+import {
+  projectSceneAsset,
+  SCENE_ASSET_MESH_DEFAULT_RESOLVER_RESOURCE_KEY,
+  type SceneAssetMeshDefaultResolver,
+} from '../assets/scene-projection';
+import { ChildOf, Children } from '../components/children';
+import {
+  worldInstantiateScene,
+  worldInstantiateSceneFlat,
+  worldSetSceneInstantiateHook,
+} from '../instances/scene-instances';
+
+const SceneInstance = defineComponent('SceneInstance', {
+  source: { type: 'shared<SceneAsset>' },
+  mapping: { type: 'array<entity>' },
+  state: { type: 'unique<SceneInstanceState>' },
+});
+const SceneMarker = defineComponent('M2SceneOwnerMarker', { value: 'i32' });
+const SceneAssetRefs = defineComponent('M2SceneAssetRefs', {
+  mesh: 'shared<MeshAsset>',
+  materials: 'array<shared<MaterialAsset>>',
+});
+void SceneAssetRefs;
+
+function registerSceneWorld(world: World): void {
+  for (const component of [SceneInstance, ChildOf, Children, SceneMarker, SceneAssetRefs]) {
+    world.components.register(component).unwrap();
+  }
+}
+
+function scene(): SceneAsset {
+  return {
+    kind: 'scene',
+    entities: [
+      {
+        localId: 0 as never,
+        components: { M2SceneOwnerMarker: { value: 7 } },
+      },
+    ],
+  };
+}
+
+describe('scene owner direct contract', () => {
+  it('instantiates a real SceneAsset through a World and keeps the payload identity', () => {
+    const world = new World();
+    registerSceneWorld(world);
+    const handle = world.allocSharedRef('SceneAsset', scene());
+
+    const result = worldInstantiateSceneFlat(world, handle);
+
+    expect(result.ok).toBe(true);
+    expect(world.sharedRefs.resolve(handle)).toMatchObject({ ok: true, value: { kind: 'scene' } });
+    if (!result.ok) return;
+    expect(result.value.roots).toHaveLength(1);
+    expect(world.get(result.value.roots[0] as never, SceneMarker)).toMatchObject({
+      ok: true,
+      value: { value: 7 },
+    });
+  });
+
+  it('rolls back a failed scene mount without leaving a partial entity', () => {
+    const world = new World();
+    registerSceneWorld(world);
+    const invalid = world.allocSharedRef('SceneAsset', {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { MissingComponent: { value: 1 } } }],
+    } as SceneAsset);
+
+    const result = worldInstantiateSceneFlat(world, invalid);
+
+    expect(result.ok).toBe(false);
+    const query = world.query({ read: [SceneMarker] });
+    expect(query.ok ? Array.from(query.value) : []).toHaveLength(0);
+  });
+
+  it('rolls back the materialized subtree when an owner hook fails', () => {
+    const world = new World();
+    registerSceneWorld(world);
+    const handle = world.allocSharedRef('SceneAsset', scene());
+    const expected = { code: 'scene-owner-hook-failed' };
+    worldSetSceneInstantiateHook(world, () => ({ ok: false, error: expected }));
+
+    const result = worldInstantiateScene(world, handle);
+
+    expect(result).toEqual({ ok: false, error: expected });
+    const query = world.query({ read: [SceneMarker] });
+    expect(query.ok ? Array.from(query.value) : []).toHaveLength(0);
+  });
+
+  it('keeps Pack refs[] indices for World-local shared-field projection', async () => {
+    const decoded = await sceneAssetDecoder.decode({
+      envelope: {
+        guid: 'scene-guid',
+        kind: 'scene',
+        refs: ['mesh-guid', 'material-guid'],
+        artifacts: {},
+        payload: {
+          kind: 'scene',
+          entities: [
+            {
+              localId: 0 as never,
+              components: {
+                M2SceneAssetRefs: { mesh: 0, materials: [1] },
+              },
+            },
+          ],
+        } as unknown as SceneAsset,
+      },
+      artifacts: { read: async () => err({ code: 'asset-artifact-missing' } as never) },
+      signal: new AbortController().signal,
+    });
+
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.value.entities[0]?.components.M2SceneAssetRefs).toEqual({
+      mesh: 0,
+      materials: [1],
+    });
+
+    const world = new World();
+    registerSceneWorld(world);
+    const projected = await projectSceneAsset(world, decoded.value, async (guid, kind) =>
+      ok({ kind, guid }),
+    );
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    const fields = projected.value.entities[0]?.components.M2SceneAssetRefs as Record<
+      string,
+      unknown
+    >;
+    expect(world.sharedRefs.resolve(fields.mesh as never)).toMatchObject({
+      value: { kind: 'mesh', guid: 'mesh-guid' },
+    });
+    expect(world.sharedRefs.resolve((fields.materials as unknown[])[0] as never)).toMatchObject({
+      value: { kind: 'material', guid: 'material-guid' },
+    });
+  });
+
+  it('projects GUID fields and nested mounts into World-owned shared refs', async () => {
+    const world = new World();
+    registerSceneWorld(world);
+    const child: SceneAsset = {
+      kind: 'scene',
+      entities: [{ localId: 0 as never, components: { M2SceneOwnerMarker: { value: 1 } } }],
+    };
+    const root: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        {
+          localId: 0 as never,
+          components: {
+            M2SceneAssetRefs: { mesh: 'mesh-guid', materials: ['material-guid'] },
+          },
+        },
+      ],
+      mounts: [
+        {
+          localId: 1 as never,
+          source: 'child-guid',
+          memberFirst: 2 as never,
+          memberCount: 1,
+          components: { M2SceneOwnerMarker: { value: 2 } },
+        },
+      ],
+    };
+    const payloads: Record<string, unknown> = {
+      'mesh-guid': { kind: 'mesh' },
+      'material-guid': { kind: 'material' },
+      'child-guid': child,
+    };
+
+    const projected = await projectSceneAsset(world, root, async (guid, kind) => {
+      const payload = payloads[guid];
+      if (payload === undefined) return err({ code: 'asset-not-found' } as never);
+      expect((payload as { readonly kind: string }).kind).toBe(kind);
+      return ok(payload);
+    });
+
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    const fields = projected.value.entities[0]?.components.M2SceneAssetRefs as Record<
+      string,
+      unknown
+    >;
+    expect(typeof fields.mesh).toBe('number');
+    expect(Array.isArray(fields.materials)).toBe(true);
+    const mountSource = projected.value.mounts?.[0]?.source;
+    expect(typeof mountSource).toBe('number');
+    expect(world.sharedRefs.resolve(fields.mesh as never)).toMatchObject({
+      value: { kind: 'mesh' },
+    });
+    expect(world.sharedRefs.resolve(mountSource as never)).toMatchObject({
+      value: { kind: 'scene' },
+    });
+
+    const sceneHandle = world.allocSharedRef('SceneAsset', projected.value);
+    const instantiated = worldInstantiateScene(world, sceneHandle);
+    expect(instantiated.ok).toBe(true);
+  });
+
+  it('projects mesh-owned material defaults into the World render view', async () => {
+    const world = new World();
+    registerSceneWorld(world);
+    const materialGuid = '019eb2cf-0001-7000-8000-deadbeef0002';
+    const parsedGuid = AssetGuid.parse(materialGuid);
+    expect(parsedGuid.ok).toBe(true);
+    if (!parsedGuid.ok) return;
+
+    const root: SceneAsset = {
+      kind: 'scene',
+      entities: [
+        {
+          localId: 0 as never,
+          components: { M2SceneAssetRefs: { mesh: 'mesh-guid', materials: [] } },
+        },
+      ],
+    };
+    const payloads: Record<string, unknown> = {
+      'mesh-guid': {
+        kind: 'mesh',
+        materialSlots: [{ slotName: 'Default', defaultMaterial: parsedGuid.value }],
+      },
+      [materialGuid]: { kind: 'material' },
+    };
+
+    const projected = await projectSceneAsset(world, root, async (guid, kind) => {
+      const payload = payloads[guid.toLowerCase()];
+      if (payload === undefined) return err({ code: 'asset-not-found' } as never);
+      expect((payload as { readonly kind: string }).kind).toBe(kind);
+      return ok(payload);
+    });
+
+    expect(projected.ok).toBe(true);
+    if (!projected.ok) return;
+    const resolver = world.getResource<SceneAssetMeshDefaultResolver>(
+      SCENE_ASSET_MESH_DEFAULT_RESOLVER_RESOURCE_KEY,
+    );
+    expect(resolver.resolveMeshDefaultMaterial(materialGuid)).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/components.unit.test.ts

@@ -0,0 +1,26 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Children, Name, Transform } from '../index';
+
+describe('scene component roster', () => {
+  it('exports exactly the four scene components', () => {
+    expect(Object.keys({ Name, Transform, ChildOf, Children }).sort()).toEqual([
+      'ChildOf',
+      'Children',
+      'Name',
+      'Transform',
+    ]);
+  });
+
+  it('registers and spawns in a headless world', () => {
+    const world = new World();
+    const entity = world
+      .spawn(
+        { component: Name, data: { value: 'root' } },
+        { component: Transform, data: {} },
+        { component: Children, data: {} },
+      )
+      .unwrap();
+    expect(world.get(entity, Name).unwrap().value).toBe('root');
+  });
+});

package/src/__tests__/diagnostic-type-surface.test-d.ts

@@ -0,0 +1,11 @@
+import type * as SceneSurface from '../index';
+
+type DiagnosticSurface = Pick<SceneSurface.SceneHierarchyDiagnostic, 'code' | 'detail'>;
+const diagnosticSurface: DiagnosticSurface | undefined = undefined;
+void diagnosticSurface;
+
+// These names were duplicate projections of the SceneError code/detail owners.
+// @ts-expect-error hierarchy diagnostics use SceneErrorCode directly.
+export type RemovedDiagnosticCode = SceneSurface['SceneHierarchyDiagnosticCode'];
+// @ts-expect-error hierarchy diagnostics use SceneErrorDetail directly.
+export type RemovedDiagnosticDetail = SceneSurface['SceneHierarchyDiagnosticDetail'];

package/src/__tests__/direct-child-of-import.unit.test.ts

@@ -0,0 +1,13 @@
+import { componentSchema } from '@forgeax/engine-ecs/internal';
+import { describe, expect, it, vi } from 'vitest';
+
+describe('scene ChildOf module', () => {
+  it('registers its Children mirror when imported directly', async () => {
+    vi.resetModules();
+    const { ChildOf } = await import('../components/child-of');
+    const { Children } = await import('../components/children');
+
+    expect(ChildOf.name).toBe('ChildOf');
+    expect(componentSchema(Children).entities).toBe('array<entity>');
+  });
+});

package/src/__tests__/fixtures/malformed-hierarchy-edge.ts

@@ -0,0 +1,15 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { ChildOf } from '../../index';
+
+/**
+ * Scene-owned malformed-edge fixture. The public relationship write accepts
+ * stale handles as data; the projection then owns the liveness diagnostic.
+ * Keeping this fixture on `world.set` avoids a private ECS graph seam.
+ */
+export function setMalformedParentEdge(
+  world: World,
+  child: EntityHandle,
+  parent: EntityHandle,
+): void {
+  world.set(child, ChildOf, { parent }).unwrap();
+}

package/src/__tests__/hierarchy-projection-contract.unit.test.ts

@@ -0,0 +1,45 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Transform } from '../index';
+import { projectHierarchy, type SceneHierarchyDiagnostic } from '../systems';
+import { setMalformedParentEdge } from './fixtures/malformed-hierarchy-edge';
+
+describe('scene hierarchy projection contract', () => {
+  it('exposes stable parent edges and diagnostic detail without throwing', () => {
+    const world = new World();
+    const parent = world.spawn({ component: Transform, data: {} }).unwrap();
+    const child = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+      .unwrap();
+
+    const snapshot = projectHierarchy(world);
+
+    expect(snapshot.parentOf.get(child)).toBe(parent);
+    expect(snapshot.diagnostics).toEqual([]);
+  });
+
+  it('keeps every diagnostic machine-readable and deterministically ordered', () => {
+    const world = new World();
+    const first = world.spawn({ component: Transform, data: {} }).unwrap();
+    const second = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: first } })
+      .unwrap();
+    const third = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: second } })
+      .unwrap();
+    setMalformedParentEdge(world, second, third);
+
+    const diagnostics: readonly SceneHierarchyDiagnostic[] = projectHierarchy(world).diagnostics;
+
+    expect(diagnostics.map((item) => item.detail.entity)).toEqual(
+      [...diagnostics.map((item) => item.detail.entity)].sort((a, b) => a - b),
+    );
+    for (const diagnostic of diagnostics) {
+      expect(['hierarchy-cycle', 'hierarchy-broken']).toContain(diagnostic.code);
+      expect(diagnostic.expected).toEqual(expect.any(String));
+      expect(diagnostic.hint).toEqual(expect.any(String));
+      expect(diagnostic.detail.entity).toEqual(expect.any(Number));
+      expect(diagnostic.detail.parent).toEqual(expect.any(Number));
+    }
+  });
+});

package/src/__tests__/hierarchy-projection.unit.test.ts

@@ -0,0 +1,92 @@
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Transform } from '../index';
+import { projectHierarchy } from '../systems';
+import { setMalformedParentEdge } from './fixtures/malformed-hierarchy-edge';
+
+function childOf(world: World, parent: EntityHandle): EntityHandle {
+  return world
+    .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+    .unwrap();
+}
+
+describe('scene hierarchy projection', () => {
+  it('keeps a live parent edge even when the parent has no Transform', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = childOf(world, parent);
+
+    const snapshot = projectHierarchy(world);
+
+    expect(snapshot.getParent(child)).toBe(parent);
+    expect(snapshot.diagnostics).toEqual([]);
+  });
+
+  it('cuts a stale parent edge and reports a machine-readable diagnostic', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = childOf(world, parent);
+    const staleParent = world.spawn().unwrap();
+    world.despawn(staleParent).unwrap();
+    setMalformedParentEdge(world, child, staleParent);
+
+    const snapshot = projectHierarchy(world);
+    const diagnostic = snapshot.diagnostics[0];
+
+    expect(snapshot.getParent(child)).toBeUndefined();
+    expect(diagnostic?.code).toBe('hierarchy-broken');
+    expect(diagnostic?.detail.entity).toBe(child);
+    expect(diagnostic?.detail.parent).toBe(staleParent);
+    expect(diagnostic?.expected).toContain('live entity');
+    expect(diagnostic?.hint.length).toBeGreaterThan(0);
+  });
+
+  it('terminates self and multi-member cycles and sorts diagnostics by entity', () => {
+    const world = new World();
+    const self = childOf(world, world.spawn().unwrap());
+    const a = childOf(world, world.spawn().unwrap());
+    const b = childOf(world, world.spawn().unwrap());
+    const c = childOf(world, world.spawn().unwrap());
+    setMalformedParentEdge(world, self, self);
+    setMalformedParentEdge(world, a, b);
+    setMalformedParentEdge(world, b, c);
+    setMalformedParentEdge(world, c, a);
+
+    const snapshot = projectHierarchy(world);
+    const cycleDiagnostics = snapshot.diagnostics.filter((item) => item.code === 'hierarchy-cycle');
+    const diagnosticEntities = cycleDiagnostics.map((item) => item.detail.entity);
+
+    expect(snapshot.getParent(self)).toBeUndefined();
+    expect(snapshot.getParent(a)).toBeUndefined();
+    expect(snapshot.getParent(b)).toBeUndefined();
+    expect(snapshot.getParent(c)).toBeUndefined();
+    expect(cycleDiagnostics).toHaveLength(4);
+    expect(diagnosticEntities).toEqual([...diagnosticEntities].sort((x, y) => x - y));
+    expect(cycleDiagnostics.every((item) => item.detail.parent !== undefined)).toBe(true);
+  });
+
+  it('does not invent a parent edge for a root entity', () => {
+    const world = new World();
+    const root = world.spawn().unwrap();
+
+    expect(projectHierarchy(world).getParent(root)).toBeUndefined();
+  });
+
+  it('reuses a stable World projection and invalidates it after a hierarchy mutation', () => {
+    const world = new World();
+    const firstParent = world.spawn().unwrap();
+    const secondParent = world.spawn().unwrap();
+    const child = childOf(world, firstParent);
+
+    const first = projectHierarchy(world);
+    expect(projectHierarchy(world)).toBe(first);
+    expect(first.getParent(child)).toBe(firstParent);
+
+    world.set(child, ChildOf, { parent: secondParent }).unwrap();
+
+    const second = projectHierarchy(world);
+    expect(second).not.toBe(first);
+    expect(second.getParent(child)).toBe(secondParent);
+    expect(projectHierarchy(world)).toBe(second);
+  });
+});

package/src/__tests__/plugin.integration.test.ts

@@ -0,0 +1,23 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, scenePlugin, Transform } from '../index';
+
+describe('scenePlugin', () => {
+  it('installs propagation without render or animation capabilities', async () => {
+    const world = new World();
+    const ctx = await createWorldContext(world, [scenePlugin()]);
+    const root = world.spawn({ component: Transform, data: { pos: [4, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [1, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    world.update(1 / 60).unwrap();
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+    await ctx.fiber.dispose();
+    expect(world.inspect().systems.some((system) => system.name === 'propagateTransforms')).toBe(
+      false,
+    );
+  });
+});

package/src/__tests__/propagation.unit.test.ts

@@ -0,0 +1,163 @@
+import { FixedUpdate, Update, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, propagateTransforms, Transform } from '../index';
+import { registerPropagateTransforms } from '../systems';
+
+describe('scene propagation', () => {
+  it('registers ordinary transform owners without exposing terminal publication as a schedule', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+
+    expect(
+      world
+        .inspect()
+        .schedules.find((entry) => entry.schedule === Update)
+        ?.systems.map((system) => system.name),
+    ).toContain('propagateTransforms');
+    expect(
+      world
+        .inspect()
+        .schedules.find((entry) => entry.schedule === FixedUpdate)
+        ?.systems.map((system) => system.name),
+    ).toContain('propagateTransformsFixed');
+    expect(world.inspect().schedules.map((entry) => entry.schedule.name)).not.toContain(
+      'FramePublish',
+    );
+  });
+  it('propagates a root and child in a headless world', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+  });
+
+  it('cascades linked children when a parent is despawned', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const parent = world.spawn({ component: Transform, data: {} }).unwrap();
+    const child = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+      .unwrap();
+    world.despawn(parent);
+    const result = world.update(1 / 60);
+    expect(result.ok).toBe(true);
+    expect(world.get(child, Transform).ok).toBe(false);
+  });
+
+  it('keeps equal entity handles isolated across Worlds', () => {
+    const first = new World();
+    const second = new World();
+    const firstRoot = first.spawn({ component: Transform, data: { pos: [3, 0, 0] } }).unwrap();
+    const secondRoot = second.spawn({ component: Transform, data: { pos: [7, 0, 0] } }).unwrap();
+
+    expect(firstRoot).toBe(secondRoot);
+    expect(propagateTransforms(first).ok).toBe(true);
+    expect(propagateTransforms(second).ok).toBe(true);
+    expect(first.get(firstRoot, Transform).unwrap().world[12]).toBeCloseTo(3);
+    expect(second.get(secondRoot, Transform).unwrap().world[12]).toBeCloseTo(7);
+  });
+
+  it('reuses a stable propagation result and invalidates it after a local edit', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+
+    const first = propagateTransforms(world);
+    const second = propagateTransforms(world);
+    expect(first).toBe(second);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+
+    world.set(root, Transform, { pos: [7, 0, 0] }).unwrap();
+    const third = propagateTransforms(world);
+    expect(third).not.toBe(second);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+  });
+
+  it('incrementally recomputes an edited transform and its descendants', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const grandchild = world
+      .spawn(
+        { component: Transform, data: { pos: [4, 0, 0] } },
+        { component: ChildOf, data: { parent: child } },
+      )
+      .unwrap();
+    const sibling = world.spawn({ component: Transform, data: { pos: [20, 0, 0] } }).unwrap();
+
+    propagateTransforms(world).unwrap();
+    world.set(child, Transform, { pos: [8, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+
+    expect(world.get(root, Transform).unwrap().world[12]).toBeCloseTo(2);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+    expect(world.get(grandchild, Transform).unwrap().world[12]).toBeCloseTo(14);
+    expect(world.get(sibling, Transform).unwrap().world[12]).toBeCloseTo(20);
+  });
+
+  it('expands a generic ChildOf mutation from the validated hierarchy snapshot', () => {
+    const world = new World();
+    const firstParent = world.spawn({ component: Transform, data: { pos: [10, 0, 0] } }).unwrap();
+    const secondParent = world.spawn({ component: Transform, data: { pos: [100, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [1, 0, 0] } },
+        { component: ChildOf, data: { parent: firstParent } },
+      )
+      .unwrap();
+    const grandchild = world
+      .spawn(
+        { component: Transform, data: { pos: [2, 0, 0] } },
+        { component: ChildOf, data: { parent: child } },
+      )
+      .unwrap();
+
+    propagateTransforms(world).unwrap();
+    world.set(child, ChildOf, { parent: secondParent }).unwrap();
+    propagateTransforms(world).unwrap();
+
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(101);
+    expect(world.get(grandchild, Transform).unwrap().world[12]).toBeCloseTo(103);
+  });
+
+  it('publishes transform writes when propagation is explicitly ordered after gameplay', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    world
+      .addSystem(Update, {
+        name: 'late-pose',
+        before: ['propagateTransforms'],
+        queries: [],
+        fn: () => world.set(child, Transform, { pos: [8, 0, 0] }),
+      })
+      .unwrap();
+
+    world.update(0).unwrap();
+
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+  });
+});