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

package/src/__tests__/transcode-fallback.unit.test.ts

@@ -0,0 +1,207 @@
+// w31 -- transcode fallback dispatch unit tests (AC-04, section 8 P3).
+//
+// `loadTextureAsset` grows a Basis arm (w34): when a catalog row's
+// `compression` is a `basis-*` member, the loader parses the KTX2 container,
+// picks a transcode target from `ctx.transcodeCaps` via the codec's pure
+// `selectTranscodeTarget`, transcodes, and stamps `TextureAsset.format` with the
+// chosen target. Degradation is silent but OBSERVABLE: with no compression cap
+// the arm lands on `rgba8unorm[-srgb]` and `tex.format` reflects that reality
+// (never a black texture -- section 8 P3).
+//
+// This test keeps the REAL `selectTranscodeTarget` (its priority chain is
+// codec-w8's concern) and mocks only the container-parse + WASM-transcode seams
+// (`parseKtx2` / `transcodeKtx2`), so it validates the LOADER's dispatch:
+// caps + build-time model -> target -> `tex.format`.
+//
+// TDD-RED before w33 (LoadContext.transcodeCaps) + w34 (the Basis arm).
+//
+// Constraints (plan-tasks w31):
+//   - no real transcoder WASM execution (mocked transcode echoes the target)
+//   - no equirect fallback (w32 owns that)
+//   - degradation is not an error (only corrupt payloads raise transcode-failed)
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { TranscodeCaps } from '@forgeax/engine-types';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+// Mock only the container-parse + WASM-transcode seams; keep the real
+// selectTranscodeTarget / KTX2_IDENTIFIER / block-format table.
+vi.mock('@forgeax/engine-codec', async (importActual) => {
+  const actual = await importActual<typeof import('@forgeax/engine-codec')>();
+  return {
+    ...actual,
+    // Basis colorModel echoed via header/dfd; the loader derives the model from
+    // the catalog `compression` member, so the parsed shape only needs a valid
+    // header + rawBytes.
+    parseKtx2: vi.fn(async (bytes: Uint8Array) => ({
+      ok: true as const,
+      value: {
+        header: {
+          vkFormat: 0,
+          typeSize: 1,
+          pixelWidth: 4,
+          pixelHeight: 4,
+          pixelDepth: 0,
+          layerCount: 0,
+          faceCount: 1,
+          levelCount: 1,
+          supercompressionScheme: 1,
+        },
+        index: {
+          dfdByteOffset: 0,
+          dfdByteLength: 0,
+          kvdByteOffset: 0,
+          kvdByteLength: 0,
+          sgdByteOffset: 0,
+          sgdByteLength: 0,
+        },
+        levelIndex: [{ byteOffset: 0, byteLength: bytes.length, uncompressedByteLength: 0 }],
+        dfd: null,
+        kvEntries: [],
+        sgd: null,
+        rawBytes: bytes,
+      },
+    })),
+    ktx2ColorSpace: vi.fn(() => mockedColorSpace),
+    // Echo the requested target so tex.format == the selected transcode target.
+    transcodeKtx2: vi.fn(async (_parsed: unknown, targetFormat: GPUTextureFormat) => ({
+      ok: true as const,
+      value: {
+        format: targetFormat,
+        width: 4,
+        height: 4,
+        mips: [{ level: 0, width: 4, height: 4, data: new Uint8Array(16) }],
+      },
+    })),
+  };
+});
+
+const GUID_TEX = 'c0000000-0000-4000-a000-000074657874';
+const PACK_INDEX_URL = '/test-transcode-fallback-pack-index.json';
+let mockedColorSpace: 'srgb' | 'linear' = 'srgb';
+// A minimal buffer whose first 12 bytes are the KTX2 identifier so the loader's
+// magic dispatch enters the codec arm.
+const KTX2_MAGIC = new Uint8Array([
+  0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+
+function parseGuid(g: string): AssetGuid {
+  const parsed = AssetGuid.parse(g);
+  if (!parsed.ok) throw new Error(`bad guid ${g}`);
+  return parsed.value;
+}
+
+let originalFetch: typeof globalThis.fetch;
+
+function wireFetch(
+  compression: 'basis-uastc' | 'basis-etc1s',
+  colorSpace: 'srgb' | 'linear',
+): void {
+  mockedColorSpace = colorSpace;
+  globalThis.fetch = vi.fn().mockImplementation((input: string) => {
+    const url = typeof input === 'string' ? input : String(input);
+    if (url === PACK_INDEX_URL) {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve([
+            {
+              guid: GUID_TEX,
+              packageUrl: `/ddc/${GUID_TEX}.pack.json`,
+              kind: 'texture',
+            },
+          ]),
+      });
+    }
+    if (url === `/ddc/${GUID_TEX}.pack.json`) {
+      return Promise.resolve({
+        ok: true,
+        json: () =>
+          Promise.resolve({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: GUID_TEX,
+                kind: 'texture',
+                payload: { width: 4, height: 4, colorSpace },
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: `${GUID_TEX}.ktx2`,
+                    mediaType: 'image/ktx2',
+                    assetCodec: {
+                      name: 'basis',
+                      container: 'ktx2',
+                      profile: compression.slice(6),
+                    },
+                  },
+                },
+              },
+            ],
+          }),
+      });
+    }
+    return Promise.resolve({ ok: true, arrayBuffer: () => Promise.resolve(KTX2_MAGIC.buffer) });
+  }) as typeof globalThis.fetch;
+}
+
+async function loadFormat(
+  caps: TranscodeCaps,
+  compression: 'basis-uastc' | 'basis-etc1s',
+  colorSpace: 'srgb' | 'linear' = 'srgb',
+): Promise<{ ok: boolean; format?: GPUTextureFormat }> {
+  wireFetch(compression, colorSpace);
+  const reg = new AssetRegistry(makeMockShaderRegistry());
+  reg.configurePackIndex(PACK_INDEX_URL);
+  reg.setTranscodeCaps(caps);
+  const result = await reg.loadByGuid(parseGuid(GUID_TEX));
+  if (!result.ok) return { ok: false };
+  return { ok: true, format: (result.value as { format: GPUTextureFormat }).format };
+}
+
+const NO_CAPS: TranscodeCaps = { bc: false, etc2: false, astc: false };
+const BC_ONLY: TranscodeCaps = { bc: true, etc2: false, astc: false };
+
+describe('loadTextureAsset -- transcode fallback dispatch (w31, AC-04)', () => {
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    vi.clearAllMocks();
+  });
+
+  it('no cap -> rgba8unorm-srgb fallback, format field reflects reality', async () => {
+    const out = await loadFormat(NO_CAPS, 'basis-uastc', 'srgb');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('rgba8unorm-srgb');
+  });
+
+  it('no cap + linear -> rgba8unorm fallback', async () => {
+    const out = await loadFormat(NO_CAPS, 'basis-etc1s', 'linear');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('rgba8unorm');
+  });
+
+  it('bc-only -> BC7 target, format field is the block format', async () => {
+    const out = await loadFormat(BC_ONLY, 'basis-uastc', 'srgb');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('bc7-rgba-unorm-srgb');
+  });
+
+  it('bc-only linear -> bc7-rgba-unorm (no srgb suffix)', async () => {
+    const out = await loadFormat(BC_ONLY, 'basis-etc1s', 'linear');
+    expect(out.ok).toBe(true);
+    expect(out.format).toBe('bc7-rgba-unorm');
+  });
+
+  it('every caps path loads without throwing (degradation is normal, not an error)', async () => {
+    for (const caps of [NO_CAPS, BC_ONLY, { bc: false, etc2: true, astc: false }] as const) {
+      const out = await loadFormat(caps, 'basis-uastc', 'srgb');
+      expect(out.ok).toBe(true);
+    }
+  });
+});

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

@@ -0,0 +1,282 @@
+// 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.attach, 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 { HANDLE_CUBE, HANDLE_SPHERE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Camera, DirectionalLight, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../renderer-host';
+
+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 host: Awaited<ReturnType<typeof constructRuntimeRendererHost>>;
+    try {
+      host = await constructRuntimeRendererHost(
+        mockCanvas,
+        {},
+        {
+          shaderManifestUrl: ENGINE_MANIFEST_URL,
+        },
+      );
+    } finally {
+      globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+    }
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer } = host.value;
+    expect(renderer.inspect().state).toBe('alive');
+    const device = sharedDevice;
+    if (device === undefined) throw new Error('GPUDevice not captured');
+
+    // Single World wires the consume path through renderer.attach 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 attachment = renderer.attach(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: HANDLE_CUBE } },
+        { 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: HANDLE_CUBE } },
+        { 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: HANDLE_SPHERE } },
+        { 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({
+      leases: [attachment.value],
+      camera: { lease: attachment.value },
+      environment: { lease: attachment.value },
+    });
+    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({
+      leases: [attachment.value],
+      camera: { lease: attachment.value },
+      environment: { lease: attachment.value },
+    });
+    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({
+      leases: [attachment.value],
+      camera: { lease: attachment.value },
+      environment: { lease: attachment.value },
+    });
+    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,210 @@
+import * as SceneOwner from '@forgeax/engine-scene';
+// 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 { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { VideoPlayer } from '@forgeax/engine-graphics-extras';
+import { SpriteAnimation } from '@forgeax/engine-render/authoring';
+import type { SceneEntity } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { rootsToSceneAsset } from '../collect-scene-asset';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { registerRuntimeComponents } from './helpers/register-runtime-components';
+
+function makeRegistry(): AssetRegistry {
+  return new AssetRegistry(makeMockShaderRegistry());
+}
+
+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;
+}
+
+describe('w1 — AC-07 transient exclusion (SpriteAnimation, VideoPlayer)', () => {
+  it('SpriteAnimation: currentFrame and accumDt are absent from collect output', () => {
+    const world = new World();
+    registerRuntimeComponents(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 reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, 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();
+    registerRuntimeComponents(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 reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, 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();
+    registerRuntimeComponents(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 reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, 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 as Parameters<typeof SceneOwner.worldInstantiateScene>[1],
+    );
+    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();
+    registerRuntimeComponents(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 reg = makeRegistry();
+    const collected = rootsToSceneAsset(reg, 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 as Parameters<typeof SceneOwner.worldInstantiateScene>[1],
+    );
+    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);
+  });
+});