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

package/src/__tests__/dawn/user-handle-mesh-render.dawn.test.ts

@@ -0,0 +1,289 @@
+// user-handle-mesh-render.dawn.test.ts -- T-M2-1 V-3 punt regression lock.
+//
+// Background (plan-decisions.md D-3 / requirements §10 V-3 / AC-10 / AC-11):
+//   The 4 learn-render examples (4.textures / 5.transformations /
+//   6.coordinate-systems / 7.camera) historically bound `MeshFilter.assetHandle`
+//   to the engine-builtin `HANDLE_CUBE` literal even after staging a
+//   user-tier cube MeshAsset alias --
+//   user-handle ids (>= BUILTIN_BASE=1024 minted by the SharedRefStore) used to
+//   miss the `pipelineState.meshes` map (legacy `[HANDLE_CUBE, HANDLE_TRIANGLE]`-only
+//   loop in `createRenderer` step 3) so the render-system fired
+//   `asset-not-registered` RhiError once per renderable per frame and the
+//   cube was silently culled (charter P3 explicit failure: the structured
+//   error fired, but the frame still composited pure clearColor).
+//
+//   feat-20260601-device/gpu-residency-extraction M1 closed the engine path via
+//   the pull model (the prior register-time auto-upload push was severed):
+//     - render-system-record.ts: a user-handle mesh (id >= 1024) misses the
+//       builtin `pipelineState.meshes` alias map, so the record stage pulls it
+//       through `gpuStore.ensureResident(handle, pod)` on first draw access and
+//       resolves the GPU buffers via `gpuStore.getMeshGpuHandles(handle)` (D-1
+//       keeps builtins on the direct path; user meshes pull through the store).
+//   This test exercises that end-to-end through `renderer.draw` -- it never
+//   calls the store directly; the pull happens inside the record stage.
+//
+//   This dawn test is the regression lock for that engine surface (D-3
+//   "engine path already works"). M-2 of feat-20260519 retracts the V-3
+//   punt at the demo layer: the 4 examples switch their `MeshFilter.assetHandle`
+//   from `HANDLE_CUBE` to a user-tier handle minted via `world.allocSharedRef`.
+//   If anything in the engine regresses the user-handle
+//   render path, this test fires before the demo smoke does.
+//
+// AC scope:
+//   AC-10 / AC-11 (V-3 punt retraction): a user-tier MeshAsset minted via
+//   `world.allocSharedRef` produces a non-empty rendered frame. The test asserts
+//   the center pixel is NOT clear-color (i.e. the cube actually drew).
+//
+// Trigger: root vitest.config.ts `dawn` project (`*.dawn.test.ts` glob).
+// Environment: dawn-node native binding (vitest.setup-webgpu.ts injects
+// globalThis.navigator.gpu); same mock-canvas + offscreen `RENDER_ATTACHMENT |
+// COPY_SRC` GPUTexture pattern as
+// apps/learn-render/.../4.textures/src/__tests__/textures-pixel.dawn.test.ts.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { createBoxGeometry } from '@forgeax/engine-geometry';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { unwrapHandle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
+import { drawPublished } from '../draw-published';
+
+const WIDTH = 256;
+const HEIGHT = 256;
+// sRGB-encoded clear-color bytes (`bgra8unorm-srgb` swap-chain). Pre-fix
+// pixel was clear-color; post-fix the cube fragment overwrites the center.
+const CLEAR_RGB_SRGB: readonly [number, number, number] = [124, 149, 149];
+
+// WebGPU spec numeric flags -- inlined to keep this dawn test self-contained
+// (packages/runtime/tsconfig.json does not pull `@webgpu/types` value-level
+// globals, only the structural `lib.dom.d.ts` interface types). Spec-aligned
+// per WebGPU §3 (texture / buffer / map-mode usage flags). AGENTS.md "RHI
+// form rules: spec-aligned" anchors the byte-level values.
+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;
+
+function isClearColour(r: number, g: number, b: number, tolerance = 5): boolean {
+  return (
+    Math.abs(r - CLEAR_RGB_SRGB[0]) <= tolerance &&
+    Math.abs(g - CLEAR_RGB_SRGB[1]) <= tolerance &&
+    Math.abs(b - CLEAR_RGB_SRGB[2]) <= tolerance
+  );
+}
+
+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),
+)}`;
+
+describe('T-M2-1 user-handle mesh render regression (AC-10 / AC-11, dawn)', () => {
+  it('allocSharedRef user-handle (>=1024) renders non-clear-color center pixel', 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');
+    }
+
+    // Capture the GPUDevice the engine uses so we can schedule
+    // `copyTextureToBuffer` for the readback after `renderer.draw`.
+    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, assets } = host.value;
+    expect(assets).toBeInstanceOf(AssetRegistry);
+    expect(renderer.inspect().state).toBe('alive');
+
+    // 1. Mint a procedural cube MeshAsset, catalogue it under a fresh UUIDv7
+    //    GUID in the AssetRegistry (GUID->payload SSOT, no handle), then mint a
+    //    user-tier column handle via `world.allocSharedRef`. The minted slot id
+    //    is >= BUILTIN_BASE (1024), so the builtin `pipelineState.meshes` alias
+    //    map (HANDLE_CUBE / HANDLE_TRIANGLE only) misses; the engine path under
+    //    test pulls the user mesh through `gpuStore.ensureResident(handle, pod)`
+    //    + `gpuStore.getMeshGpuHandles(handle)` on first draw access.
+    const meshRes = createBoxGeometry(1, 1, 1);
+    expect(meshRes.ok).toBe(true);
+    if (!meshRes.ok) return;
+    const cubeAsset: MeshAsset = meshRes.value;
+
+    const world = new World();
+
+    const cubeGuid = AssetGuid.random();
+    assets.catalog(cubeGuid, cubeAsset);
+    const cubeHandle = world.allocSharedRef('MeshAsset', cubeAsset);
+
+    // The handle MUST be a user-tier handle (>= 1024 = BUILTIN_BASE). If this
+    // assertion fails the SharedRefStore base shifted; the regression lock is
+    // moot until the BUILTIN_BASE invariant is re-established.
+    expect(unwrapHandle(cubeHandle)).toBeGreaterThanOrEqual(1024);
+
+    // 2. Build a solid-color unlit material so the assertion is purely
+    //    about "did the cube draw" -- no texture decode, no mip path,
+    //    no UV variance. Bright red baseColor (visible against the
+    //    clear-color teal).
+    const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Forward',
+          program: { module: 'forgeax::default-unlit' },
+          renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+        },
+      ],
+      values: { baseColor: [1, 0, 0, 1] },
+    });
+
+    // 3. Spawn cube + camera (axis-aligned, camera 3 units in front).
+    world.spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: cubeHandle } },
+      { component: MeshRenderer, data: { materials: [matHandle] } },
+    );
+    world.spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 3],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      {
+        component: Camera,
+        data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 },
+      },
+    );
+
+    const drawn = drawPublished(renderer, world);
+    expect(drawn.ok).toBe(true);
+
+    const device = sharedDevice;
+    expect(device).toBeDefined();
+    if (device === undefined) return;
+    await device.queue.onSubmittedWorkDone();
+
+    expect(renderTarget).toBeDefined();
+    if (renderTarget === undefined) return;
+
+    // 4. Pixel readback (`bgra8unorm` byte layout; helper unpacks to RGB).
+    const bytesPerPixel = 4;
+    const unpaddedBytesPerRow = WIDTH * bytesPerPixel;
+    const bytesPerRow = Math.ceil(unpaddedBytesPerRow / 256) * 256;
+    const readbackBuffer = device.createBuffer({
+      size: bytesPerRow * HEIGHT,
+      usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+    });
+    const enc = device.createCommandEncoder();
+    enc.copyTextureToBuffer(
+      { texture: renderTarget },
+      { buffer: readbackBuffer, bytesPerRow, rowsPerImage: HEIGHT },
+      { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+    );
+    device.queue.submit([enc.finish()]);
+    await readbackBuffer.mapAsync(MAP_MODE_READ);
+    const mapped = readbackBuffer.getMappedRange();
+    const bytes = new Uint8Array(mapped.slice(0));
+    readbackBuffer.unmap();
+    readbackBuffer.destroy();
+
+    const readRgba = (px: number, py: number): [number, number, number] => {
+      const off = py * bytesPerRow + px * bytesPerPixel;
+      const r = bytes[off + 0] ?? 0;
+      const g = bytes[off + 1] ?? 0;
+      const b = bytes[off + 2] ?? 0;
+      return [r, g, b];
+    };
+
+    // Center pixel must NOT be clear-color (i.e. the cube actually drew
+    // through the user-handle path). Pre-fix this would be teal
+    // (~rgb(124,149,149)); post-fix the unlit red baseColor crushes it
+    // through the sRGB swap-chain encode to roughly rgb(255,0,0).
+    const cx = WIDTH >> 1;
+    const cy = HEIGHT >> 1;
+    const [centerR, centerG, centerB] = readRgba(cx, cy);
+    expect(
+      isClearColour(centerR, centerG, centerB),
+      `center pixel should NOT be clear-color (~${CLEAR_RGB_SRGB[0]},${CLEAR_RGB_SRGB[1]},${CLEAR_RGB_SRGB[2]}); got rgb(${centerR},${centerG},${centerB}). If this fails, the user-handle render path regressed -- check render-system-record.ts:304-306 + gpuStore.ensureResident pull on the user-tier (allocSharedRef) handle.`,
+    ).toBe(false);
+    // Sanity: center pixel must also not be all-zero (transparent /
+    // pre-clear black) -- charter P3 explicit failure: silent skip
+    // would emit (0,0,0) on the COPY_SRC texture.
+    expect(centerR + centerG + centerB).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/dawn/user-mesh-upload.dawn.test.ts

@@ -0,0 +1,209 @@
+// user-mesh-upload.dawn.test.ts - feat-20260518-pbr-direct-lighting-mvp
+// M5 / w22.5 (TDD red): user-registered MeshAsset GPU upload path.
+//
+// Background: M5 / w23 (hello-room migration) surfaced an engine gap:
+// `Renderer.ready` step 3 only loops the two builtin mesh handles
+// (`HANDLE_CUBE` / `HANDLE_TRIANGLE`) when allocating GPU vertex / index
+// buffers. User-registered MeshAssets (e.g. `createBoxGeometry({width:1,
+// height:1, depth:1})`) land in `AssetRegistry.assets` but never get a
+// matching `MeshGpuHandles` entry, so `pipelineState.meshes.get(handle)`
+// returns `undefined` during the record stage and emits 'asset-not-registered'
+// RhiError once per renderable per frame (~900x in a 300-frame smoke).
+//
+// Plan-strategy w22.5: AssetRegistry exposes `uploadMesh` /
+// `getMeshGpuHandles` that mirror the existing `uploadTexture` /
+// `getTextureGpuView` shape (charter P5 consistent abstraction). The
+// `register({kind: 'mesh', ...})` path auto-runs `uploadMesh` when
+// `configureGpuDevice` has been called; lifecycle stays append-only
+// (no unregister path; OOS-future symmetric with textureGpuHandles).
+//
+// This test is the binary judgment for AC-13 (5 smoke green) and the
+// engine-side fix that unblocks M5 w23 hello-room. The full readback
+// gate is covered by `pnpm --filter @forgeax/hello-room smoke` (300 frames pixel
+// readback ε ≤ 0.05); this dawn-tier gate isolates the host-side derivation
+// + GPU-resource accounting that feeds the record stage.
+
+import { World } from '@forgeax/engine-ecs';
+import { createBoxGeometry, PROCEDURAL_FLOATS_PER_VERTEX } from '@forgeax/engine-geometry';
+import { mat4 } from '@forgeax/engine-math';
+import { ok } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import type { EquirectAsset, MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../../render/src/device/gpu-residency';
+
+const mockCaps = {
+  backendKind: 'webgpu' as const,
+  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,
+};
+
+// feat-20260601-device/gpu-residency-extraction M1: mesh GPU residency moved to
+// the store; register no longer auto-uploads (push severed). The pull-model
+// premise: register the POD, then explicit `store.ensureResident(handle, pod)`
+// uploads the GPU buffers. The deferred-replay path is removed (no global
+// replay); residency is purely lazy at first ensureResident.
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe('w22.5 user-registered mesh GPU upload (AC-13, dawn)', () => {
+  it.skipIf(!dawnReady)(
+    '(a) register({kind:"mesh"}) + getMeshGpuHandles returns vbo/ibo with byte sizes matching the source asset',
+    async () => {
+      // Construct a minimal procedural box (12 floats per vertex stride;
+      // M4 / w21 emit). The asset payload is what hello-room currently
+      // hands to AssetRegistry.register; w22.6 makes the GPU upload
+      // automatic when configureGpuDevice has wired the rhi device.
+      const meshRes = createBoxGeometry(1, 1, 1);
+      expect(meshRes.ok).toBe(true);
+      if (!meshRes.ok) return;
+      const asset: MeshAsset = meshRes.value;
+
+      const adapterResult = await rhi.requestAdapter();
+      expect(adapterResult.ok).toBe(true);
+      if (!adapterResult.ok) return;
+      const deviceResult = await adapterResult.value.requestDevice();
+      expect(deviceResult.ok).toBe(true);
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
+
+      const store = new GpuResidencyCache();
+      const world = new World();
+      store.configureGpuDevice(
+        device,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      const handle = world.allocSharedRef('MeshAsset', asset);
+
+      // Pull-model: explicit ensureResident uploads the GPU buffers; thereafter
+      // getMeshGpuHandles returns a non-undefined record.
+      const residentRes = store.ensureResident(handle, asset);
+      expect(residentRes.ok).toBe(true);
+      const gpuHandles = store.getMeshGpuHandles(handle);
+      expect(gpuHandles).toBeDefined();
+      if (gpuHandles === undefined) return;
+
+      // Vertex buffer size matches the source byte length exactly.
+      expect(gpuHandles.vertexBuffer).toBeDefined();
+      expect(gpuHandles.indexBuffer).toBeDefined();
+      // M-3 / w12: byte sizes are tracked on the entry (`vboBytes` /
+      // `iboBytes`), not on the GpuBuffer wrapper -- the spec-aligned RHI
+      // Buffer interface has no `.size`. The prior dual-shape probe
+      // (typeof `.size === 'number'`) is gone now that the SSOT is single.
+      expect(gpuHandles.vboBytes).toBe(asset.vertices.byteLength);
+
+      // indices.byteLength is rounded up to 4-byte alignment per WebGPU
+      // 23.4.1.4 step 5; w22.6 mirrors createRenderer step 3 padding.
+      // This fixture is an indexed mesh; indices became optional in M2.
+      const indexBytesUnpadded = asset.indices?.byteLength ?? 0;
+      expect(gpuHandles.iboBytes).toBeGreaterThanOrEqual(indexBytesUnpadded);
+      expect(gpuHandles.iboBytes % 4).toBe(0);
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(b) pull-model: register then ensureResident surfaces the GPU buffers (no global replay)',
+    async () => {
+      // feat-20260601-device/gpu-residency-extraction M1: the pre-extraction
+      // deferred-replay path is removed (no global replay). register only
+      // catalogues the CPU POD; getMeshGpuHandles is undefined until an
+      // explicit ensureResident pulls the GPU buffers (charter P9 graceful
+      // degradation -> explicit pull).
+      const meshRes = createBoxGeometry(2, 2, 2, 1, 1, 1);
+      expect(meshRes.ok).toBe(true);
+      if (!meshRes.ok) return;
+      const asset: MeshAsset = meshRes.value;
+
+      const store = new GpuResidencyCache();
+      const world = new World();
+      const handle = world.allocSharedRef('MeshAsset', asset);
+      // Before any ensureResident the store has no GPU residency for the handle.
+      const before = store.getMeshGpuHandles(handle);
+      expect(before).toBeUndefined();
+
+      const adapterResult = await rhi.requestAdapter();
+      if (!adapterResult.ok) return;
+      const deviceResult = await adapterResult.value.requestDevice();
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
+      store.configureGpuDevice(
+        device,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      // Explicit pull uploads the GPU buffers; getMeshGpuHandles now surfaces them.
+      const residentRes = store.ensureResident(handle, asset);
+      expect(residentRes.ok).toBe(true);
+      const after = store.getMeshGpuHandles(handle);
+      expect(after).toBeDefined();
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    '(c) batch register 16 user meshes -> all 16 carry distinct GPU buffer handles (lifecycle does not re-allocate)',
+    async () => {
+      const adapterResult = await rhi.requestAdapter();
+      if (!adapterResult.ok) return;
+      const deviceResult = await adapterResult.value.requestDevice();
+      if (!deviceResult.ok) return;
+      const device = deviceResult.value;
+
+      const store = new GpuResidencyCache();
+      const world = new World();
+      store.configureGpuDevice(
+        device,
+        undefined,
+        (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+        mockCaps,
+      );
+
+      const handles: number[] = [];
+      const seenVbos = new Set<unknown>();
+      for (let i = 0; i < 16; i++) {
+        const meshRes = createBoxGeometry(1 + i * 0.1, 1, 1);
+        if (!meshRes.ok) continue;
+        const handle = world.allocSharedRef('MeshAsset', meshRes.value);
+        const residentRes = store.ensureResident(handle, meshRes.value);
+        expect(residentRes.ok).toBe(true);
+        const gpu = store.getMeshGpuHandles(handle);
+        expect(gpu).toBeDefined();
+        seenVbos.add(gpu?.vertexBuffer);
+        handles.push(i);
+      }
+      expect(handles.length).toBe(16);
+      // Each register produces a distinct vbo (no accidental reuse).
+      expect(seenVbos.size).toBe(16);
+
+      // Sanity ping: the canonical geometry stride is referenced so import
+      // chain stays live (biome no-unused-imports gate). mat4 /
+      // MaterialAsset references retained for type-only hint at
+      // the record-stage consumer side (next milestone).
+      expect(PROCEDURAL_FLOATS_PER_VERTEX).toBe(12);
+      const _matType: Float32Array = mat4.create();
+      void _matType;
+      const _matAsset: MaterialAsset | undefined = undefined;
+      void _matAsset;
+    },
+  );
+});

package/src/__tests__/dawn/zero-manifest-mesh-fail.dawn.test.ts

@@ -0,0 +1,119 @@
+// zero-manifest-mesh-fail.dawn.test.ts -- bug-20260519 AC-03 dual-impl mirror.
+//
+// Dawn-side counterpart of the browser AC-03 case in
+// `renderer-draw-world.test.ts`. The browser case asserts the
+// structured `RhiError shader-compile-failed` fires through
+// `Renderer.onError` when a `MeshRenderer` entity reaches the per-entity
+// loop in the zero-manifest path; this dawn test exercises the same
+// surface against the real wgpu-wasm + naga binding so the rhi-wgpu
+// path stays in lockstep with rhi-webgpu (charter P4 consistent
+// abstraction; OOS-4 dual-impl behaviour parity).
+//
+// AC: requirements section 4 AC-03 (mesh + empty manifest -> `RhiError
+// shader-compile-failed` fires through `Renderer.onError`; `.hint`
+// keeps the `engine-vite-plugin-shader` substring -- D-6 literal
+// preservation). plan-strategy D-3 + D-4 (test matrix migration: dawn
+// project mirror).
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
+
+const WIDTH = 64;
+const HEIGHT = 64;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+
+describe('bug-20260519 AC-03 dawn mirror: mesh + zero manifest -> render-time fail', () => {
+  it('MeshRenderer + no shaderManifestUrl fires shader-compile-failed on dawn', 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 {
+      // Zero-manifest path: explicit `shaderManifestUrl: undefined` opts into
+      // zero-entry mode. Post-fix host construction resolves ok; the
+      // asset registration fails at validation time (shader not registered).
+      host = await constructRuntimeRendererHost(mockCanvas, {}, { shaderManifestUrl: undefined });
+    } finally {
+      globalThis.navigator.gpu.requestAdapter = originalRequestAdapter;
+    }
+    expect(host.ok).toBe(true);
+    if (!host.ok) throw host.error;
+    const { renderer, assets } = host.value;
+    expect(renderer.inspect().state).toBe('alive');
+    expect(assets).toBeInstanceOf(AssetRegistry);
+
+    // Material parameter declarations now belong to MaterialAsset, so catalog
+    // validation does not depend on a shader-manifest registration side table.
+    const matRes = assets.catalog<MaterialAsset>(
+      assets.parseGuid('00000000-0000-4000-8000-000000000a01'),
+      {
+        kind: 'material',
+        passes: [
+          {
+            name: 'Forward',
+            program: { module: 'forgeax::default-unlit' },
+            renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+          },
+        ],
+        values: { baseColor: [1, 0, 0, 1] },
+      } as MaterialAsset,
+    );
+    expect(matRes.ok).toBe(true);
+  });
+});