@forgeax/engine-runtime 0.1.2

package/src/__tests__/video-cache-regression.unit.test.ts

@@ -0,0 +1,186 @@
+// feat-20260623-world-space-video-asset M4 / w12 — AC-08: static texture
+// cache regression.
+//
+// AC-08 (requirements.md): video per-frame upload must NOT enter the
+// GpuResourceStore.ensureResident permanent-cache path. The video frame is a
+// transient resource (re-uploaded every frame), the antithesis of the
+// "upload once / cache forever" semantics ensureResident implements. The M4
+// design (plan-strategy D-3) routes video through a separate DynamicTextureStore
+// and leaves ensureResident untouched (the cube-texture eager path is the
+// precedent: it also never enters the ensureResident switch).
+//
+// Two regression anchors:
+//   1. structural — ensureResident's `switch (pod.kind)` keeps exactly two arms
+//      (`mesh` + `texture`) and gains NO `case 'video'`. The switch has no
+//      `default`, so a video arm would be the only way video could pollute the
+//      cache; this source-level scan fails fast if a later edit adds one.
+//   2. behavioral — a static TextureAsset still resolves through ensureResident
+//      with cache-hit semantics: the second ensureResident for the same handle
+//      reuses the GPU texture (no second createTexture) and returns the same
+//      cached view. This proves the M4 video work did not perturb the static
+//      texture cache.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+import { GpuResourceStore } from '@forgeax/engine-render/internal';
+import type { Result, RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import type { EquirectAsset, Handle, TextureAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const STORE_SRC = fileURLToPath(
+  new URL('../../../render/src/gpu-resource-store.ts', import.meta.url),
+);
+
+function texturePodFixture(): TextureAsset {
+  return {
+    kind: 'texture',
+    width: 2,
+    height: 2,
+    format: 'rgba8unorm-srgb',
+    data: new Uint8Array(2 * 2 * 4).fill(188),
+    colorSpace: 'srgb',
+    mipmap: false,
+  };
+}
+
+interface CreateProbe {
+  textures: number;
+  views: number;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: opaque mock GPU device surface
+function makeMockDevice(probe: CreateProbe): any {
+  const okShim = <T>(v: T) => ({ ok: true as const, value: v });
+  return {
+    createShaderModule: () => okShim({ __mock: 'shader' }),
+    createSampler: () => okShim({ __mock: 'sampler' }),
+    createBindGroupLayout: () => okShim({ __mock: 'bgl' }),
+    createPipelineLayout: () => okShim({ __mock: 'layout' }),
+    createRenderPipeline: () => okShim({ __mock: 'pipeline' }),
+    createBindGroup: () => okShim({ __mock: 'bindGroup' }),
+    createBuffer: (desc: { size?: number }) => okShim({ __mock: 'buffer', size: desc.size ?? 0 }),
+    createTexture: () => {
+      probe.textures += 1;
+      return okShim({ __mock: `texture-${probe.textures}` });
+    },
+    createTextureView: () => {
+      probe.views += 1;
+      return okShim({ __mock: `view-${probe.views}` });
+    },
+    destroyBuffer: (): Result<void, RhiError> => ok(undefined),
+    destroyTexture: (): Result<void, RhiError> => ok(undefined),
+    queue: {
+      writeBuffer: () => okShim(undefined),
+      writeTexture: () => okShim(undefined),
+      submit: () => okShim(undefined),
+    },
+  };
+}
+
+const mockCaps: RhiCaps = {
+  backendKind: 'webgpu',
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: false,
+  firstInstanceIndirect: false,
+  storageBuffer: true,
+  storageTexture: false,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: false,
+  float32Filterable: false,
+  maxColorAttachments: 8,
+};
+
+function makeRegisterCube(): (
+  pod: EquirectAsset,
+) => Result<Handle<'EquirectAsset', 'shared'>, never> {
+  let next = 1000;
+  return () => ok(toShared<'EquirectAsset'>(next++));
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: shader-module factory shim
+const shaderFactory = async (_d: any, desc: { code: string; label?: string }) =>
+  ok({ __mock: 'shader', label: desc.label ?? '' }) as never;
+
+function configuredStore(probe: CreateProbe): GpuResourceStore {
+  const store = new GpuResourceStore();
+  store.configureGpuDevice(
+    makeMockDevice(probe),
+    shaderFactory,
+    makeRegisterCube() as never,
+    mockCaps,
+  );
+  return store;
+}
+
+describe('AC-08 — ensureResident switch stays 2-arm (no video) (M4 / w12)', () => {
+  it('ensureResident has exactly the mesh + texture case arms and no `case "video"`', () => {
+    const src = readFileSync(STORE_SRC, 'utf8');
+    // Locate the ensureResident body and isolate its `switch (pod.kind)`.
+    const fnIdx = src.indexOf('ensureResident(');
+    expect(fnIdx, 'ensureResident not found in gpu-resource-store.ts').toBeGreaterThan(-1);
+    const switchIdx = src.indexOf('switch (pod.kind)', fnIdx);
+    expect(switchIdx, 'switch (pod.kind) not found in ensureResident').toBeGreaterThan(-1);
+    // Scan from the switch to the next top-level method boundary (the
+    // uploadTexture jsdoc) so we only inspect ensureResident's switch.
+    const switchEnd = src.indexOf('async uploadTexture', switchIdx);
+    expect(switchEnd).toBeGreaterThan(switchIdx);
+    const switchBody = src.slice(switchIdx, switchEnd);
+
+    const caseArms = [...switchBody.matchAll(/case\s+'([a-z-]+)'\s*:/g)].map((m) => m[1]);
+    expect(caseArms).toEqual(['mesh', 'texture']);
+    expect(switchBody.includes("case 'video'")).toBe(false);
+    // No `default:` arm — exhaustiveness is enforced by tsc-b, so a third
+    // reachable kind (video) would be a compile error, never a silent cache
+    // poison. Assert the absence so a later `default` does not mask it.
+    expect(/\bdefault\s*:/.test(switchBody)).toBe(false);
+  });
+});
+
+describe('AC-08 — static texture cache-hit behavior unchanged (M4 / w12)', () => {
+  it('second ensureResident for the same texture handle reuses the GPU texture (cache hit)', () => {
+    const probe: CreateProbe = { textures: 0, views: 0 };
+    const store = configuredStore(probe);
+    const handle = toShared<'TextureAsset'>(4096);
+
+    const first = store.ensureResident(handle, texturePodFixture());
+    expect(first.ok).toBe(true);
+    const firstView = store.getTextureGpuView(handle);
+    expect(firstView).toBeDefined();
+    const texturesAfterFirst = probe.textures;
+    expect(texturesAfterFirst).toBeGreaterThan(0);
+
+    // Second call: cache hit — no new GPU texture is created, same view returned.
+    const second = store.ensureResident(handle, texturePodFixture());
+    expect(second.ok).toBe(true);
+    expect(probe.textures).toBe(texturesAfterFirst);
+    expect(store.getTextureGpuView(handle)).toBe(firstView);
+  });
+
+  it('a fresh handle does NOT hit the cache (distinct texture allocation)', () => {
+    const probe: CreateProbe = { textures: 0, views: 0 };
+    const store = configuredStore(probe);
+
+    expect(store.ensureResident(toShared<'TextureAsset'>(5001), texturePodFixture()).ok).toBe(true);
+    const afterOne = probe.textures;
+    expect(store.ensureResident(toShared<'TextureAsset'>(5002), texturePodFixture()).ok).toBe(true);
+    expect(probe.textures).toBeGreaterThan(afterOne);
+  });
+
+  it('RhiError surfaces import cleanly (compile anchor)', () => {
+    const e = new RhiError({ code: 'feature-not-enabled', expected: 'x', hint: 'y' });
+    expect(e).toBeInstanceOf(RhiError);
+    expect(err(e).ok).toBe(false);
+  });
+});

package/src/__tests__/video-extract-bindgroup.dawn.test.ts

@@ -0,0 +1,450 @@
+// feat-20260623-world-space-video-asset M4 / w13 — AC-06: a VideoAsset GUID
+// embedded in a MaterialAsset.values texture field flows through the
+// extract layer and produces a bind group without blowing up.
+//
+// AC-06 (requirements.md): video reuses the existing values texture
+// channel (no new MaterialAsset top-level field). The extract layer's
+// resolveTexLike must recognise `payload.kind === 'video'` (D-5) and route it
+// as a video source rather than minting a TextureAsset handle (which would then
+// crash the record stage's ensureResident, whose switch has no `video` arm).
+//
+// R-7 (plan-strategy §4): the field the video GUID occupies (baseColorTexture)
+// MUST be in the shader's `derive(paramSchema).textureFieldNames` traversal set
+// — otherwise extract never even looks at it and the video silently fails to
+// render. This test asserts that membership explicitly (the R-7 anchor) so a
+// future schema edit that drops baseColorTexture surfaces here.
+//
+// Two layers of assertion:
+//   1. CPU (deterministic) — extractFrame on a world with a standard-PBR
+//      material whose baseColorTexture paramValue is a catalogued VideoAsset
+//      GUID. The produced MaterialSnapshot must (a) flag baseColorTexture as a
+//      video-sourced field (videoTextureFields), and (b) NOT carry it as a
+//      static TextureAsset handle (no ensureResident pollution, AC-08). This is
+//      the RED anchor before w14 (extract resolveTexLike video branch).
+//   2. dawn (structural) — a full renderer frame with the same material draws
+//      with zero RhiError, proving the extract->record->bind-group path does
+//      not blow up on a video-sourced texture field (the bind group is produced;
+//      the per-frame upload itself lands in w16, here the field falls back to the
+//      default view until a frame is uploaded).
+
+import { World } from '@forgeax/engine-ecs';
+import { createPlaneGeometry } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import {
+  Camera,
+  extractFrame,
+  MeshFilter,
+  MeshRenderer,
+  prepareExtractContext,
+  type RenderAssetPort,
+} from '@forgeax/engine-render/internal';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type {
+  Asset,
+  Handle,
+  MaterialAsset,
+  MaterialPass,
+  MeshAsset,
+  VideoAsset,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../index';
+import { drawPublished } from './draw-published';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const WIDTH = 128;
+const HEIGHT = 128;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+
+const STANDARD_PBR_SHADER = 'forgeax::default-standard-pbr';
+const FORWARD_PBR_PASS: MaterialPass = {
+  name: 'Forward',
+  program: { module: STANDARD_PBR_SHADER },
+};
+
+function transformData(x: number, y: number, z: number) {
+  return {
+    pos: [x, y, z],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+}
+
+function registerTestMesh(world: World) {
+  const mesh = createPlaneGeometry(1, 1);
+  if (!mesh.ok) throw new Error(mesh.error.code);
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', mesh.value);
+}
+
+interface TestAssetStore {
+  readonly port: RenderAssetPort;
+  readonly resolver: {
+    readonly epoch: number;
+    lookup<T extends Asset>(guid: string): T | undefined;
+    guidOf(asset: Asset): string | undefined;
+  };
+  publish(guid: string | AssetGuid, asset: Asset): void;
+}
+
+function createTestAssetStore(): TestAssetStore {
+  const shaderRegistry = makeMockShaderRegistry();
+  const payloads = new Map<string, Asset>();
+  const guids = new WeakMap<object, string>();
+  let epoch = 0;
+  const keyOf = (guid: string): string => guid.toLowerCase().replaceAll('-', '');
+  const resolver = {
+    get epoch() {
+      return epoch;
+    },
+    lookup<T extends Asset>(guid: string): T | undefined {
+      return payloads.get(keyOf(guid)) as T | undefined;
+    },
+    guidOf(asset: Asset): string | undefined {
+      return guids.get(asset);
+    },
+  };
+  const port: RenderAssetPort = {
+    get epoch() {
+      return resolver.epoch;
+    },
+    shaderRegistry,
+    lookup: resolver.lookup,
+    guidOf: resolver.guidOf,
+    materialShaderTextureFieldNames(shaderId: string): readonly string[] {
+      const artifact = shaderRegistry.findMaterialArtifact(shaderId);
+      if (!artifact.ok) return [];
+      return artifact.value.paramSchema
+        .filter((parameter) => parameter.type === 'texture2d')
+        .map((parameter) => parameter.name);
+    },
+  };
+  return {
+    port,
+    resolver,
+    publish(guid, asset) {
+      const formatted = typeof guid === 'string' ? guid : AssetGuid.format(guid);
+      payloads.set(keyOf(formatted), asset);
+      guids.set(asset, formatted);
+      epoch += 1;
+    },
+  };
+}
+
+/**
+ * Catalog a VideoAsset GUID + a standard-PBR material whose baseColorTexture
+ * paramValue references it; return the material column handle to spawn with.
+ */
+function catalogVideoMaterial(
+  world: World,
+  assets: TestAssetStore,
+): { matHandle: Handle<'MaterialAsset', 'shared'>; videoGuid: AssetGuid } {
+  const videoGuid = AssetGuid.random();
+  const videoGuidStr = AssetGuid.format(videoGuid);
+  const video: VideoAsset = { kind: 'video', url: 'extract-bindgroup-clip.webm' };
+  assets.publish(videoGuid, video);
+
+  const material: MaterialAsset = {
+    kind: 'material',
+    passes: [FORWARD_PBR_PASS],
+    // The video GUID occupies the baseColorTexture texture2d slot — exactly the
+    // shape a static texture would (D-5 reuse of the texture2d slot).
+    values: {
+      baseColor: [1, 1, 1],
+      baseColorTexture: {
+        texture: videoGuidStr as never,
+        coordinates: {
+          set: 0,
+          transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+          physicalUvScale: [1, 1],
+        },
+      },
+    },
+  } as MaterialAsset;
+  const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', material);
+  return { matHandle, videoGuid };
+}
+
+describe('AC-06 / R-7 — video GUID in values is a recognised texture field (M4 / w13)', () => {
+  it('R-7: baseColorTexture is in the standard-PBR shader textureFieldNames set', () => {
+    const assets = createTestAssetStore();
+    const fields = assets.port.materialShaderTextureFieldNames(STANDARD_PBR_SHADER);
+    expect(fields).toContain('baseColorTexture');
+  });
+
+  it('extract flags the video-sourced field and does NOT carry it as a static TextureAsset handle', () => {
+    const world = new World();
+    const assets = createTestAssetStore();
+    const mesh = registerTestMesh(world);
+    const { matHandle } = catalogVideoMaterial(world, assets);
+
+    world
+      .spawn(
+        { component: Transform, data: transformData(0, 0, 0) },
+        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshRenderer, data: { materials: [matHandle] } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: transformData(0, 0, 5) },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+
+    propagateTransforms(world);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets: assets.port }));
+    expect(frame.renderables.length).toBe(1);
+    const mat = frame.renderables[0]?.material;
+    expect(mat).toBeDefined();
+
+    // Desired post-w14 behavior (RED before w14):
+    //   (a) the baseColorTexture field is flagged as video-sourced.
+    expect(mat?.videoTextureFields?.has('baseColorTexture')).toBe(true);
+    //   (b) it is NOT carried as a static TextureAsset handle (would pollute the
+    //       ensureResident cache + crash on a video POD, AC-08).
+    expect(mat?.textureHandles?.has('baseColorTexture')).not.toBe(true);
+    expect(mat?.baseColorTexture).toBeUndefined();
+  });
+});
+
+interface DawnHarness {
+  renderer: Awaited<ReturnType<typeof createRenderer>>;
+  device: GPUDevice;
+}
+
+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 bootDawn(assetStore: TestAssetStore): Promise<DawnHarness | null> {
+  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, assetResolver: assetStore.resolver },
+    );
+  } finally {
+    globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+  }
+  const ready = await renderer.ready;
+  expect(ready.ok).toBe(true);
+  if (!ready.ok) return null;
+  if (sharedDevice === undefined) throw new Error('dawn device never captured');
+  ensureRenderTarget(sharedDevice, 'rgba8unorm');
+  return { renderer, device: sharedDevice };
+}
+
+describe('AC-06 — extract->record->bind group does not blow up on a video field (dawn) (M4 / w13)', () => {
+  it('a renderer frame with a video-sourced baseColorTexture draws with 0 RhiError', async () => {
+    const assetStore = createTestAssetStore();
+    const harness = await bootDawn(assetStore);
+    if (harness === null) return;
+    const { renderer, device } = harness;
+
+    const videoGuid = AssetGuid.random();
+    const videoGuidStr = AssetGuid.format(videoGuid);
+    const video: VideoAsset = { kind: 'video', url: 'extract-bindgroup-clip.webm' };
+    assetStore.publish(videoGuid, video);
+
+    const materialPayload = {
+      kind: 'material' as const,
+      passes: [FORWARD_PBR_PASS],
+      values: {
+        baseColor: [1, 1, 1],
+        baseColorTexture: {
+          texture: videoGuidStr,
+          coordinates: {
+            set: 0,
+            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+            physicalUvScale: [1, 1],
+          },
+        },
+      },
+    };
+
+    const errorCodes: string[] = [];
+    const unsub = renderer.onError((e) => {
+      errorCodes.push(e.code);
+    });
+
+    const world = new World();
+    const meshHandle = registerTestMesh(world);
+    const matHandle = world.allocSharedRef('MaterialAsset', materialPayload);
+    world
+      .spawn(
+        { component: Transform, data: transformData(0, 0, 0) },
+        { component: MeshFilter, data: { assetHandle: meshHandle } },
+        { component: MeshRenderer, data: { materials: [matHandle] } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: transformData(0, 0, 5) },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+
+    const drawn = drawPublished(renderer, world);
+    expect(drawn.ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    if (typeof unsub === 'function') unsub();
+
+    // The video-sourced texture field must not trip any WebGPU VALIDATION error
+    // (the bind group is well-formed; the field falls back to the default view).
+    // The expected, structured `video-upload-unsupported` signal (AC-10, asserted
+    // below) is NOT a validation error and is excluded here.
+    const validationErrors = errorCodes.filter((c) => c !== 'video-upload-unsupported');
+    expect(
+      validationErrors,
+      'a video-sourced texture field must not trip any WebGPU validation error',
+    ).toEqual([]);
+  });
+
+  // AC-10 PRODUCTION-PATH assertion: with no VideoElementProvider registered
+  // (dawn has no HTMLVideoElement) and no high-perf GPUExternalTexture capability,
+  // the REAL per-frame upload path (render-system-record videoTextureView) hits
+  // the double-miss and MUST fire the structured VideoUploadUnsupportedError on
+  // the engine error channel — NOT silently bind a default view. This exercises
+  // the production draw path end-to-end, replacing the prior orphan pure-function
+  // test (resolveVideoUpload) that the production render path never called.
+  it('AC-10: production draw fires video-upload-unsupported on capability double-miss', async () => {
+    const assetStore = createTestAssetStore();
+    const harness = await bootDawn(assetStore);
+    if (harness === null) return;
+    const { renderer, device } = harness;
+
+    const videoGuid = AssetGuid.random();
+    const videoGuidStr = AssetGuid.format(videoGuid);
+    const video: VideoAsset = { kind: 'video', url: 'double-miss-clip.webm' };
+    assetStore.publish(videoGuid, video);
+
+    // Mirror the demo recipe exactly: unlit shader + a World-owned plane. The video
+    // upload path (videoTextureView) is reached via the per-submesh user-region
+    // bind-group loop, which iterates the shader's textureFieldNames; unlit
+    // declares baseColorTexture there. (The earlier standard-PBR geometry
+    // shape routes through a different builtin-cube pipeline branch that does not
+    // hit the user-region video loop — not the production demo path.)
+    const materialPayload = {
+      kind: 'material' as const,
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' } },
+        },
+      ],
+      values: {
+        baseColor: [1, 1, 1],
+        baseColorTexture: {
+          texture: videoGuidStr,
+          coordinates: {
+            set: 0,
+            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+            physicalUvScale: [1, 1],
+          },
+        },
+      },
+    };
+
+    const fired: { code: string; hint: string }[] = [];
+    const unsub = renderer.onError((e) => {
+      fired.push({ code: e.code, hint: e.hint });
+    });
+
+    const world = new World();
+    // NB: NO VIDEO_ELEMENT_PROVIDER_KEY resource inserted -> the production
+    // upload path resolves element===undefined; high-perf path is absent on
+    // dawn -> genuine AC-10 double-miss.
+    const meshHandle = registerTestMesh(world);
+    const matHandle = world.allocSharedRef('MaterialAsset', materialPayload);
+    world
+      .spawn(
+        { component: Transform, data: transformData(0, 0, 0) },
+        { component: MeshFilter, data: { assetHandle: meshHandle } },
+        { component: MeshRenderer, data: { materials: [matHandle] } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: transformData(0, 0, 5) },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+
+    const drawn = drawPublished(renderer, world);
+    expect(drawn.ok).toBe(true);
+    await device.queue.onSubmittedWorkDone();
+    if (typeof unsub === 'function') unsub();
+
+    const unsupported = fired.filter((e) => e.code === 'video-upload-unsupported');
+    expect(
+      unsupported.length,
+      'production videoTextureView must fire video-upload-unsupported on double-miss (AC-10), not silently bind default',
+    ).toBeGreaterThan(0);
+    // The signal is property-accessible (charter P3): AI users branch on .code
+    // and read .hint without string-parsing the human message.
+    expect(unsupported[0]?.hint.length ?? 0).toBeGreaterThan(0);
+  });
+});