@forgeax/engine-runtime 0.1.2

package/src/__tests__/tilemap-validate.test.ts

@@ -0,0 +1,201 @@
+// tilemap-validate.test - validateTilemapAtRegister + validateTileLayerAtRegister
+// baseline fail-fast (feat-20260608 M0 baseline rebuild).
+//
+// validateTilemapAtRegister checks the Tilemap component invariants after
+// spawn:
+//   - cols / rows >= 1
+//   - chunkSize >= 1
+//   - tileset GUID is non-empty
+//
+// validateTileLayerAtRegister checks the TileLayer component invariants:
+//   - tiles.length === parent.Tilemap.cols * rows (M0 second-stage
+//     mutation-recheck — invariant must hold post-spawn).
+//   - ChildOf parent must point at an entity carrying Tilemap.
+//
+// On invariant break the validator returns `Result.err(AssetError)` with
+// `code === 'asset-invalid-value'` and `.detail.field` pointing at the
+// offending invariant — consistent with the existing AssetRegistry
+// validation shape (charter P4, fail-fast at register time).
+//
+// Anchors: plan-tasks m0-t5; plan-strategy §M0 (asset-registry validator
+// baseline); charter P3.
+
+import { World } from '@forgeax/engine-ecs';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf } from '@forgeax/engine-scene';
+import { AssetError } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  validateTileLayerAtRegister,
+  validateTilemapAtRegister,
+} from '../tilemap-register-validate';
+
+function makeTilesetGuid(_world: World) {
+  return 'test/tileset';
+}
+
+describe('validateTilemapAtRegister — M0 baseline invariants', () => {
+  it('valid Tilemap returns Result.ok', () => {
+    const world = new World();
+    const tilesetGuid = makeTilesetGuid(world);
+    const e = world
+      .spawn({
+        component: Tilemap,
+        data: {
+          cols: 2,
+          rows: 2,
+          tileSize: [16, 16],
+          chunkSize: 8,
+          tileset: tilesetGuid,
+        },
+      })
+      .unwrap();
+    const r = validateTilemapAtRegister(world, e);
+    expect(r.ok).toBe(true);
+  });
+
+  it('cols === 0 fails', () => {
+    const world = new World();
+    const tilesetGuid = makeTilesetGuid(world);
+    const e = world
+      .spawn({
+        component: Tilemap,
+        data: {
+          cols: 0,
+          rows: 2,
+          tileSize: [16, 16],
+          chunkSize: 8,
+          tileset: tilesetGuid,
+        },
+      })
+      .unwrap();
+    const r = validateTilemapAtRegister(world, e);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toBeInstanceOf(AssetError);
+      expect(r.error.code).toBe('asset-invalid-value');
+    }
+  });
+
+  it('rows === 0 fails', () => {
+    const world = new World();
+    const tilesetGuid = makeTilesetGuid(world);
+    const e = world
+      .spawn({
+        component: Tilemap,
+        data: {
+          cols: 2,
+          rows: 0,
+          tileSize: [16, 16],
+          chunkSize: 8,
+          tileset: tilesetGuid,
+        },
+      })
+      .unwrap();
+    const r = validateTilemapAtRegister(world, e);
+    expect(r.ok).toBe(false);
+  });
+
+  it('chunkSize === 0 fails', () => {
+    const world = new World();
+    const tilesetGuid = makeTilesetGuid(world);
+    const e = world
+      .spawn({
+        component: Tilemap,
+        data: {
+          cols: 2,
+          rows: 2,
+          tileSize: [16, 16],
+          chunkSize: 0,
+          tileset: tilesetGuid,
+        },
+      })
+      .unwrap();
+    const r = validateTilemapAtRegister(world, e);
+    expect(r.ok).toBe(false);
+  });
+
+  it('empty tileset GUID fails', () => {
+    const world = new World();
+    const e = world
+      .spawn({
+        component: Tilemap,
+        data: {
+          cols: 2,
+          rows: 2,
+          tileSize: [16, 16],
+          chunkSize: 8,
+          tileset: '',
+        },
+      })
+      .unwrap();
+    const r = validateTilemapAtRegister(world, e);
+    expect(r.ok).toBe(false);
+  });
+});
+
+describe('validateTileLayerAtRegister — M0 baseline invariants', () => {
+  function spawnLayered(cols: number, rows: number, tileLen: number) {
+    const world = new World();
+    const tilesetGuid = makeTilesetGuid(world);
+    const tilemap = world
+      .spawn({
+        component: Tilemap,
+        data: { cols, rows, tileSize: [16, 16], chunkSize: 8, tileset: tilesetGuid },
+      })
+      .unwrap();
+    const layer = world
+      .spawn(
+        { component: TileLayer, data: { tiles: new Uint32Array(tileLen), layerOrder: 0 } },
+        { component: ChildOf, data: { parent: tilemap } },
+      )
+      .unwrap();
+    return { world, tilemap, layer };
+  }
+
+  it('matching tiles.length passes', () => {
+    const { world, layer } = spawnLayered(4, 3, 12);
+    const r = validateTileLayerAtRegister(world, layer);
+    expect(r.ok).toBe(true);
+  });
+
+  it('tiles.length too small fails', () => {
+    const { world, layer } = spawnLayered(4, 3, 11);
+    const r = validateTileLayerAtRegister(world, layer);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error).toBeInstanceOf(AssetError);
+      expect(r.error.code).toBe('asset-invalid-value');
+    }
+  });
+
+  it('tiles.length too large fails', () => {
+    const { world, layer } = spawnLayered(4, 3, 13);
+    const r = validateTileLayerAtRegister(world, layer);
+    expect(r.ok).toBe(false);
+  });
+
+  it('missing ChildOf fails', () => {
+    const world = new World();
+    const orphan = world
+      .spawn({ component: TileLayer, data: { tiles: new Uint32Array(4) } })
+      .unwrap();
+    const r = validateTileLayerAtRegister(world, orphan);
+    expect(r.ok).toBe(false);
+  });
+
+  it('ChildOf parent without Tilemap fails', () => {
+    const world = new World();
+    const nonTilemap = world
+      .spawn({ component: TileLayer, data: { tiles: new Uint32Array(0) } })
+      .unwrap();
+    const layer = world
+      .spawn(
+        { component: TileLayer, data: { tiles: new Uint32Array(4) } },
+        { component: ChildOf, data: { parent: nonTilemap } },
+      )
+      .unwrap();
+    const r = validateTileLayerAtRegister(world, layer);
+    expect(r.ok).toBe(false);
+  });
+});

package/src/__tests__/transform-hierarchy-pixel-diff.dawn.test.ts

@@ -0,0 +1,274 @@
+// transform-hierarchy-pixel-diff.dawn.test.ts -
+// feat-20260531-render-consume-global-transform-hierarchy / M3 / w13.
+//
+// Dawn integration test mirroring the hello-transform-hierarchy smoke
+// (apps/hello/transform-hierarchy/scripts/smoke-dawn.mjs): AC-08
+// parent-moves-child-follows. Single World wires the consume path
+// through renderer.attachWorld, spawns a non-identity parent + a ChildOf
+// child + a static reference sphere, then proves moving the PARENT moves the
+// CHILD's rendered world position (the child gets no Transform write of its
+// own between frames; the only change is the parent's resolved Transform.world
+// mat4 propagated down the ChildOf edge). This is the vitest-dawn-project
+// counterpart to the CI
+// smoke step so `pnpm test:dawn` exercises the visual-evidence path
+// (plan-strategy section 5.5 "Vitest dawn project" row).
+//
+// Follows the fxaa-pixel-diff.dawn.test.ts pattern for canvas mock,
+// device capture, and pixel readback.
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+} from '@forgeax/engine-render/internal';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../index';
+
+const WIDTH = 256;
+const HEIGHT = 256;
+
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const MAP_MODE_READ = 0x0001;
+
+const PARENT_X_REST = -0.6;
+const PARENT_X_MOVED = 1.0;
+const TOTAL_PIXELS = WIDTH * HEIGHT;
+const DIFF_THRESHOLD = Math.floor(TOTAL_PIXELS * 0.001);
+
+const ENGINE_MANIFEST = await (async () => {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  return buildEngineShaderManifest();
+})();
+const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
+  JSON.stringify(ENGINE_MANIFEST),
+)}`;
+
+async function doReadPixels(device: GPUDevice, renderTarget: GPUTexture): Promise<Uint8Array> {
+  const bytesPerPixel = 4;
+  const unpaddedBytesPerRow = WIDTH * bytesPerPixel;
+  const bytesPerRow = Math.ceil(unpaddedBytesPerRow / 256) * 256;
+  const buf = device.createBuffer({
+    size: bytesPerRow * HEIGHT,
+    usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+  });
+  const enc = device.createCommandEncoder();
+  enc.copyTextureToBuffer(
+    { texture: renderTarget },
+    { buffer: buf, bytesPerRow, rowsPerImage: HEIGHT },
+    { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+  );
+  device.queue.submit([enc.finish()]);
+  await device.queue.onSubmittedWorkDone();
+  await buf.mapAsync(MAP_MODE_READ);
+  const mapped = buf.getMappedRange();
+  const bytes = new Uint8Array(mapped.slice(0));
+  buf.unmap();
+  buf.destroy();
+  return bytes;
+}
+
+function diffCountOf(a: Uint8Array, b: Uint8Array): number {
+  let n = 0;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) n++;
+  }
+  return n;
+}
+
+describe('feat-20260531 M3 w13: AC-08 parent moves -> child follows (dawn)', () => {
+  it('moving the parent moves the ChildOf child rendered world position', async () => {
+    const dawnAvailable = typeof globalThis.navigator?.gpu?.requestAdapter === 'function';
+    if (!dawnAvailable)
+      throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
+
+    let sharedDevice: GPUDevice | undefined;
+    const originalRequestAdapter = globalThis.navigator.gpu.requestAdapter.bind(
+      globalThis.navigator.gpu,
+    );
+    globalThis.navigator.gpu.requestAdapter = async (opts) => {
+      const rawAdapter = await originalRequestAdapter(opts);
+      if (rawAdapter === null) return rawAdapter;
+      const originalRequestDevice = rawAdapter.requestDevice.bind(rawAdapter);
+      rawAdapter.requestDevice = async (desc) => {
+        const dev = await originalRequestDevice(desc);
+        if (sharedDevice === undefined) sharedDevice = dev;
+        return dev;
+      };
+      return rawAdapter;
+    };
+
+    let renderTarget: GPUTexture | undefined;
+    const ensureRenderTarget = (device: GPUDevice, format: GPUTextureFormat): GPUTexture => {
+      if (renderTarget !== undefined) return renderTarget;
+      renderTarget = device.createTexture({
+        size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+        format,
+        usage: TEXTURE_USAGE_RENDER_ATTACHMENT | TEXTURE_USAGE_COPY_SRC,
+        viewFormats: ['rgba8unorm-srgb'],
+      });
+      return renderTarget;
+    };
+    const mockCanvas = {
+      width: WIDTH,
+      height: HEIGHT,
+      getContext(kind: string): unknown {
+        if (kind !== 'webgpu') return null;
+        return {
+          configure(desc: { device: GPUDevice; format?: GPUTextureFormat }) {
+            ensureRenderTarget(desc.device, desc.format ?? 'rgba8unorm');
+          },
+          unconfigure() {},
+          getCurrentTexture(): GPUTexture {
+            if (renderTarget === undefined) {
+              if (sharedDevice === undefined)
+                throw new Error('render target requested before device captured');
+              return ensureRenderTarget(sharedDevice, 'rgba8unorm');
+            }
+            return renderTarget;
+          },
+        };
+      },
+      addEventListener() {},
+      removeEventListener() {},
+    } as unknown as HTMLCanvasElement;
+
+    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    try {
+      renderer = await createRenderer(mockCanvas, {}, { shaderManifestUrl: ENGINE_MANIFEST_URL });
+    } finally {
+      globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+    }
+    expect(renderer.backend).toBe('webgpu');
+    const ready = await renderer.ready;
+    expect(ready.ok).toBe(true);
+    if (!ready.ok) return;
+    const device = sharedDevice;
+    if (device === undefined) throw new Error('GPUDevice not captured');
+
+    const assets = renderer.assets;
+    if (assets === null) throw new Error('AssetRegistry is null');
+
+    // Single World wires the consume path through renderer.attachWorld so the
+    // child's resolved Transform.world mat4 is derived each frame. feat-20260614
+    // M8: the material is a per-World column handle minted via allocSharedRef
+    // (AssetRegistry has no handle concept).
+    const world = new World();
+    const cubeHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+    const sphereHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('sphere').unwrap());
+    const attachment = renderer.attachWorld(world);
+    if (!attachment.ok) throw attachment.error;
+
+    const materialHandle = world.allocSharedRef('MaterialAsset', {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-standard-pbr' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: [0.7, 0.7, 0.7], metallic: 0, roughness: 0.4 },
+    });
+
+    const parent = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [PARENT_X_REST, -0.4, 0],
+            quat: [0, 0, 0, 1],
+            scale: [0.4, 0.4, 0.4],
+          },
+        },
+        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshRenderer, data: { materials: [materialHandle] } },
+      )
+      .unwrap();
+
+    world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [0, 2.0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        { component: ChildOf, data: { parent } },
+        { component: MeshFilter, data: { assetHandle: cubeHandle } },
+        { component: MeshRenderer, data: { materials: [materialHandle] } },
+      )
+      .unwrap();
+
+    world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [1.4, 0, 0], quat: [0, 0, 0, 1], scale: [0.4, 0.4, 0.4] },
+        },
+        { component: MeshFilter, data: { assetHandle: sphereHandle } },
+        { component: MeshRenderer, data: { materials: [materialHandle] } },
+      )
+      .unwrap();
+
+    world
+      .spawn({
+        component: DirectionalLight,
+        data: {
+          direction: [-0.4, -0.6, -0.7],
+          color: [1, 1, 1],
+          intensity: 1.5,
+        },
+      })
+      .unwrap();
+
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 7] } },
+        {
+          component: Camera,
+          data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } as Record<
+            string,
+            unknown
+          > as never,
+        },
+      )
+      .unwrap();
+
+    // Frame A: parent at rest. world.update(1 / 60).unwrap() runs propagateTransforms.
+    world.update(1 / 60).unwrap();
+    const drawA = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    expect(drawA.ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    if (renderTarget === undefined) throw new Error('renderTarget not configured');
+    const pixelsA = await doReadPixels(device, renderTarget);
+
+    // Stability: a second render of the rest scene must be pixel-stable.
+    world.update(1 / 60).unwrap();
+    const drawAA = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    expect(drawAA.ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    const pixelsAA = await doReadPixels(device, renderTarget);
+    expect(diffCountOf(pixelsA, pixelsAA)).toBe(0);
+
+    // Frame B: move the PARENT only. propagate re-derives the child's world transform.
+    const setRes = world.set(parent, Transform, { pos: [PARENT_X_MOVED, 0, 0] });
+    expect(setRes.ok).toBe(true);
+    world.update(1 / 60).unwrap();
+    const drawB = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+    expect(drawB.ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    const pixelsB = await doReadPixels(device, renderTarget);
+
+    // AC-08: the child followed the parent's world displacement.
+    const diffCount = diffCountOf(pixelsA, pixelsB);
+    expect(
+      diffCount,
+      `expected parent-move pixel diff > ${DIFF_THRESHOLD}; got ${diffCount}`,
+    ).toBeGreaterThan(DIFF_THRESHOLD);
+  });
+});

package/src/__tests__/transient-fields-collect.test.ts

@@ -0,0 +1,203 @@
+// feat-20260709-component-vec-fields-and-field-transient-batch M1 / w1 + w2:
+//   w1: AC-07 transient exclusion tests for SpriteAnimation and VideoPlayer.
+//   w2: AC-08 round-trip + rebuild tests for SpriteAnimation and VideoPlayer.
+//
+// TDD red-phase: these assertions will FAIL before w3 lands the transient
+// declarations, then turn green after w3 adds transient: true to the
+// relevant fields.
+//
+// Rebuild points (research Finding 9):
+//   - currentFrame + accumDt ← spriteAnimationTickSystem (sprite-animation-tick.ts:255-256)
+//   - VideoPlayer.currentTime: NO ECS rebuild system (D-R2); playback head on host HTMLVideoElement
+
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { VideoPlayer } from '@forgeax/engine-graphics-extras';
+import { SpriteAnimation } from '@forgeax/engine-render/authoring';
+import * as SceneOwner from '@forgeax/engine-scene';
+import type { SceneEntity } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { rootsToSceneAsset } from '../collect-scene-asset';
+import { registerSceneComponents } from './helpers/register-scene-components';
+import { createTestSceneAssetStore } from './helpers/scene-asset-port';
+
+function compField(entity: SceneEntity, compName: string, fieldName: string): unknown {
+  const comp = (entity.components as Record<string, Record<string, unknown>>)[compName];
+  return comp?.[fieldName];
+}
+
+function hasComp(entity: SceneEntity, compName: string): boolean {
+  return (entity.components as Record<string, Record<string, unknown>>)[compName] !== undefined;
+}
+
+function registerTransientWorld(world: World): void {
+  registerSceneComponents(world, [SpriteAnimation, VideoPlayer]);
+}
+
+describe('w1 — AC-07 transient exclusion (SpriteAnimation, VideoPlayer)', () => {
+  it('SpriteAnimation: currentFrame and accumDt are absent from collect output', () => {
+    const world = new World();
+    registerTransientWorld(world);
+    const e = world.spawn({
+      component: SpriteAnimation,
+      data: { frameCount: 4, frameDuration: 0.1, regions: new Float32Array(16) },
+    });
+    if (!e.ok) return expect(e.ok).toBe(true);
+
+    const assets = createTestSceneAssetStore();
+    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+
+    const entity = collected.value.entities[0];
+    expect(entity).toBeDefined();
+    if (!entity) return;
+
+    // SpriteAnimation component should be present (it is not transient at component level).
+    expect(hasComp(entity, 'SpriteAnimation')).toBe(true);
+
+    // currentFrame and accumDt are runtime state — should be excluded.
+    expect(compField(entity, 'SpriteAnimation', 'currentFrame')).toBeUndefined();
+    expect(compField(entity, 'SpriteAnimation', 'accumDt')).toBeUndefined();
+
+    // Other fields (frameCount, frameDuration, playbackMode) should be present.
+    expect(compField(entity, 'SpriteAnimation', 'frameCount')).toBe(4);
+    expect(compField(entity, 'SpriteAnimation', 'frameDuration')).toBeCloseTo(0.1, 5);
+    expect(compField(entity, 'SpriteAnimation', 'playbackMode')).toBe(0);
+  });
+
+  it('VideoPlayer: currentTime is absent from collect output', () => {
+    const world = new World();
+    registerTransientWorld(world);
+    const e = world.spawn({
+      component: VideoPlayer,
+      data: { playing: true, loop: false, currentTime: 5.5 },
+    });
+    if (!e.ok) return expect(e.ok).toBe(true);
+
+    const assets = createTestSceneAssetStore();
+    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+
+    const entity = collected.value.entities[0];
+    expect(entity).toBeDefined();
+    if (!entity) return;
+
+    // VideoPlayer component should be present.
+    expect(hasComp(entity, 'VideoPlayer')).toBe(true);
+
+    // currentTime is runtime state (playback head on host HTMLVideoElement) — should be excluded.
+    expect(compField(entity, 'VideoPlayer', 'currentTime')).toBeUndefined();
+
+    // Other fields should be present.
+    expect(compField(entity, 'VideoPlayer', 'playing')).toBe(true);
+    expect(compField(entity, 'VideoPlayer', 'loop')).toBe(false);
+  });
+});
+
+describe('w2 — AC-08 round-trip tests (SpriteAnimation, VideoPlayer)', () => {
+  it('SpriteAnimation: currentFrame/accumDt excluded, round-trip defaults to 0', () => {
+    const world = new World();
+    registerTransientWorld(world);
+    const e = world.spawn({
+      component: SpriteAnimation,
+      data: {
+        frameCount: 4,
+        frameDuration: 0.1,
+        regions: new Float32Array(16),
+        currentFrame: 3,
+        accumDt: 0.5,
+      },
+    });
+    if (!e.ok) return expect(e.ok).toBe(true);
+
+    const assets = createTestSceneAssetStore();
+    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+
+    const entity = collected.value.entities[0];
+    expect(entity).toBeDefined();
+    if (!entity) return;
+
+    // Transient fields excluded.
+    expect(compField(entity, 'SpriteAnimation', 'currentFrame')).toBeUndefined();
+    expect(compField(entity, 'SpriteAnimation', 'accumDt')).toBeUndefined();
+
+    // Round-trip: instantiate the collected scene → read ECS state directly.
+    const handle = world.allocSharedRef('SceneAsset', collected.value);
+    const inst = SceneOwner.worldInstantiateScene(world, handle);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+
+    // Find the SpriteAnimation entity in the instantiated descendant tree.
+    let saEnt: EntityHandle | undefined;
+    for (const desc of world.iterDescendants(inst.value.root)) {
+      const v = world.get(desc, SpriteAnimation);
+      if (v.ok) {
+        saEnt = desc;
+        break;
+      }
+    }
+    expect(saEnt).toBeDefined();
+    if (!saEnt) return;
+    const saVal = world.get(saEnt, SpriteAnimation);
+    expect(saVal.ok).toBe(true);
+    if (!saVal.ok) return;
+    // currentFrame and accumDt default to 0 (layer-3 fallback for u32/f32).
+    expect(saVal.value.currentFrame).toBe(0);
+    expect(saVal.value.accumDt).toBe(0);
+    // Other fields survive round-trip.
+    expect(saVal.value.frameCount).toBe(4);
+    expect(saVal.value.frameDuration).toBeCloseTo(0.1, 5);
+  });
+
+  it('VideoPlayer: currentTime excluded, round-trip defaults to 0 (D-R2: no system rebuild)', () => {
+    // Per D-R2: VideoPlayer.currentTime has NO ECS rebuild system.
+    // The playback head is authoritative on the host HTMLVideoElement.
+    // This test asserts exclusion + round-trip to default 0 only.
+    const world = new World();
+    registerTransientWorld(world);
+    const e = world.spawn({
+      component: VideoPlayer,
+      data: { playing: true, loop: true, currentTime: 42.0 },
+    });
+    if (!e.ok) return expect(e.ok).toBe(true);
+
+    const assets = createTestSceneAssetStore();
+    const collected = rootsToSceneAsset(assets.port, world, [e.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+
+    const entity = collected.value.entities[0];
+    expect(entity).toBeDefined();
+    if (!entity) return;
+
+    // currentTime excluded.
+    expect(compField(entity, 'VideoPlayer', 'currentTime')).toBeUndefined();
+
+    // Round-trip: instantiate the collected scene → read ECS state directly.
+    const handle = world.allocSharedRef('SceneAsset', collected.value);
+    const inst = SceneOwner.worldInstantiateScene(world, handle);
+    expect(inst.ok).toBe(true);
+    if (!inst.ok) return;
+
+    // Find the VideoPlayer entity in the instantiated descendant tree.
+    let vpEnt: EntityHandle | undefined;
+    for (const desc of world.iterDescendants(inst.value.root)) {
+      const v = world.get(desc, VideoPlayer);
+      if (v.ok) {
+        vpEnt = desc;
+        break;
+      }
+    }
+    expect(vpEnt).toBeDefined();
+    if (!vpEnt) return;
+    const vpVal = world.get(vpEnt, VideoPlayer);
+    expect(vpVal.ok).toBe(true);
+    if (!vpVal.ok) return;
+    expect(vpVal.value.currentTime).toBe(0);
+    expect(vpVal.value.playing).toBe(true);
+    expect(vpVal.value.loop).toBe(true);
+  });
+});

package/src/__tests__/transitional-authoring.integration.test.ts

@@ -0,0 +1,7 @@
+import { describe, expect, it } from 'vitest';
+
+describe('transitional authoring', () => {
+  it('retains a single runtime record path', () => {
+    expect(true).toBe(true);
+  });
+});