@forgeax/engine-runtime 0.1.2

package/src/__tests__/dawn/sprite-nineslice-mesh-bind.dawn.test.ts

@@ -0,0 +1,251 @@
+// sprite-nineslice-mesh-bind.dawn.test.ts -- feat-20260527-sprite-nineslice
+// M2 / w13. dawn-node smoke that the nine-slice quad GPU buffers are
+// resident and bind cleanly when a sprite material declares non-zero `slices`.
+//
+// Plan-strategy §M2 boundary clause: M2 must include at least one dawn fixture so
+// the dangling-slot regression (the prior implement's round-1 issue #2:
+// builtin handle imported but not GPU-uploaded) trips before verify, not at
+// PR review. This fixture renders ONE frame with `slices=[0.25,0.25,0.25,0.25]`
+// + `sliceMode=0` + a 4x4 RGBA texture, then asserts:
+//   (a) renderer.draw returns ok (no thrown error).
+//   (b) zero RhiError fires through `Renderer.onError`.
+// It does NOT assert pixel content -- M3 / w15 (hello-sprite-nineslice-section
+// dawn fixture) covers stretch + tile pixel parity.
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '@forgeax/engine-render/authoring';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render/internal';
+import { createRenderer } from '@forgeax/engine-runtime';
+import { Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset, SamplerAsset, TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { drawPublished } from '../draw-published';
+
+const WIDTH = 64;
+const HEIGHT = 64;
+const TEXTURE_USAGE_COPY_SRC = 0x01;
+const TEXTURE_USAGE_RENDER_ATTACHMENT = 0x10;
+
+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('feat-20260527-sprite-nineslice w13 dawn smoke (HANDLE_NINESLICE_QUAD bind)', () => {
+  it('sprite + slices=[.25,.25,.25,.25] renders one frame with 0 RhiError', 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 world = new World();
+    const nineSliceHandle = world.internSharedRef(
+      'MeshAsset',
+      createPrimitiveMesh('nine-slice-quad').unwrap(),
+    );
+
+    // ── Build a 4x4 RGBA texture (16 texels) with a recognizable pattern. ──
+    // The exact pixels are not asserted -- the frame just needs to render
+    // without firing RhiError. 4x4 is below the wgpu mipmap requirement so
+    // mipmap=false in the import settings.
+    const pixels = new Uint8Array(4 * 4 * 4);
+    for (let i = 0; i < 16; i++) {
+      pixels[i * 4 + 0] = (i * 16) & 0xff;
+      pixels[i * 4 + 1] = 0x88;
+      pixels[i * 4 + 2] = 0x44;
+      pixels[i * 4 + 3] = 0xff;
+    }
+    const texAsset: TextureAsset = {
+      kind: 'texture',
+      width: 4,
+      height: 4,
+      format: 'rgba8unorm-srgb',
+      colorSpace: 'srgb',
+      mipmap: false,
+      data: pixels,
+    };
+    const texHandle = world.allocSharedRef<'TextureAsset', TextureAsset>('TextureAsset', texAsset);
+    // feat-20260601-gpu-resource-store-extraction M1: explicit texture GPU upload.
+    const texUploadRes = await renderer.store.uploadTexture(texHandle, texAsset, {
+      bytes: pixels,
+      width: 4,
+      height: 4,
+      mime: 'image/png',
+      colorSpace: 'srgb',
+      mipmap: false,
+    });
+    expect(texUploadRes.ok).toBe(true);
+    if (!texUploadRes.ok) return;
+
+    const samplerAsset: SamplerAsset = {
+      kind: 'sampler',
+      addressModeU: 'repeat',
+      addressModeV: 'repeat',
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmapFilter: 'nearest',
+    };
+    const samplerHandle = world.allocSharedRef<'SamplerAsset', SamplerAsset>(
+      'SamplerAsset',
+      samplerAsset,
+    );
+
+    // Sprite material with non-zero slices -- this triggers the w11 mesh
+    // routing override to HANDLE_NINESLICE_QUAD. values includes
+    // texture + sampler so the missing-texture debug-pink branch stays cold.
+    //
+    // feat-20260625-refactor-sprite-as-transparent-mesh M4 / w16 — updated
+    // to use the post-M2/M3 SSOT material shape:
+    //   - first-pass `transparent: true` flag (M2 / w6, Q3=b) drives the
+    //     LDR split + premultiplied-alpha blend pipeline (replaces the
+    //     legacy shadingModel='sprite' arm ablated in M3 / w15).
+    //   - values field names are UBO-aligned to sprite.material.json
+    //     paramSchema (M3 / w11, D-4): `baseColorTexture` (was `texture`)
+    //     and `slicesAndMode` vec4 (was `slices` + `sliceMode` split).
+    // feat-20260626-sprite-transparent-collapse M1/M4: the boolean
+    // `transparent` field has collapsed into `renderState.blend` as the
+    // single asset-side SSOT; transparent routing now derives from
+    // `renderState.blend !== undefined`.
+    // The slices mesh routing decision (D-2 sentinel:
+    // unit quad -> nine-slice quad when slices != [0,0,0,0]) is
+    // unchanged; the record stage reads it via the materialShaderId ===
+    // 'forgeax::sprite' + non-zero `slicesAndMode.xyz` predicate.
+    const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+      kind: 'material',
+      passes: [
+        {
+          name: 'Sprite',
+          program: { module: 'forgeax::sprite' },
+          renderState: {
+            ...{ blend: SPRITE_PREMULTIPLIED_ALPHA_BLEND },
+            queue: 3000,
+            tags: { LightMode: 'Forward' },
+          },
+        },
+      ],
+      values: {
+        baseColorTexture: {
+          texture: texHandle as unknown as never,
+          coordinates: {
+            set: 0,
+            transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
+            physicalUvScale: [1, 1],
+          },
+        },
+        sampler: { texture: samplerHandle as unknown as never },
+        slicesAndMode: [0.25, 0.25, 0.25, 0.25],
+      },
+    });
+
+    const errors: unknown[] = [];
+    renderer.onError((e) => {
+      errors.push(e);
+    });
+
+    world.spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: nineSliceHandle } },
+      { 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);
+    if (sharedDevice !== undefined) {
+      await sharedDevice.queue.onSubmittedWorkDone();
+    }
+
+    // The sprite-nineslice path should produce zero RhiError fires -- the
+    // GPU buffers for HANDLE_NINESLICE_QUAD are resident (w12 step-3 upload),
+    // the sprite UBO carries the 4-vec4 slot 3 (w11 helper), and the sprite
+    // pipeline binds the same 12F vertex layout (D-2 reuse).
+    expect(errors).toEqual([]);
+  });
+});

package/src/__tests__/dawn/tonemap.dawn.test.ts

@@ -0,0 +1,107 @@
+// tonemap.dawn.test.ts - feat-20260519-tonemap-reinhard-mvp / M3 / T-M3.4
+// (dawn tier).
+//
+// Numerically aligns the host-side TS port (`packages/runtime/src/systems/
+// tonemap.ts`) against the canonical Reinhard 2002 extended formula, with
+// the AC-04 / AC-05 / AC-06 anchor inputs the WGSL fragment stage agrees
+// on byte-for-byte (D-O3 shared `TONEMAP_LUMINANCE_EPSILON`).
+//
+// This tier asserts the TS-side derivation that the host writes into the
+// `TonemapParams` UBO + the post-process fragment stage consumes; the
+// fullscreen-pass GPU readback path is covered by the apps/hello/tonemap
+// smoke gate (T-M4.2 dawn-node + chromium 300 frames) and the AC-07/08/09
+// pixel-parity checks land there.
+//
+// Tier discipline mirrors mesh-ssbo-normal-matrix.dawn.test.ts: real GPU
+// presence is checked via `navigator.gpu` and `it.skipIf(!dawnReady)`
+// guards every assertion; the actual numeric assertions run against the
+// pure-TS port so the test stays deterministic across hardware /
+// driver / chromium-channel.
+
+import { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { tonemapReinhardLuminance } from '../../systems/tonemap';
+
+const dawnReady = typeof navigator !== 'undefined' && navigator.gpu !== undefined;
+
+describe('T-M3.4 tonemap dawn-tier numeric anchor (AC-04 / AC-05 / AC-06)', () => {
+  it.skipIf(!dawnReady)(
+    'AC-04: high-intensity HDR sample compresses without NaN + preserves channel ratios',
+    () => {
+      // intensity=20 PBR direct-lit sample at the highlight peak. With
+      // exposure=1 + Lw=4, the luminance Y ~ 13.2 maps to Y' ~ 1.7 (knee-
+      // saturated; AC-06 anchor: Lw=Y is the knee point, so Y > Lw lands in
+      // the saturation regime). Per-channel output preserves the input
+      // ratio exactly (no hue shift; only the luminance scale changes).
+      // The swap-chain bgra8unorm-srgb store-op clamps each channel to
+      // [0, 1] at hardware encode time, so AC-07 (no integer-white burn)
+      // is enforced by the hardware, not the shader formula. The TS port
+      // mirrors the formula 1:1 so this test asserts the pre-clamp
+      // numerical shape the GPU then writes through the sRGB encode.
+      const lIn: [number, number, number] = [20, 12, 5];
+      const out = tonemapReinhardLuminance(lIn, 1.0, 4.0);
+      expect(Number.isFinite(out[0])).toBe(true);
+      expect(Number.isFinite(out[1])).toBe(true);
+      expect(Number.isFinite(out[2])).toBe(true);
+      expect(out[0]).toBeGreaterThan(0);
+      expect(out[1]).toBeGreaterThan(0);
+      expect(out[2]).toBeGreaterThan(0);
+      // Per-channel ratio preserved.
+      const inGR = 12 / 20;
+      const outGR = (out[1] ?? 0) / (out[0] ?? 1);
+      expect(outGR).toBeCloseTo(inGR, 3);
+      const inBR = 5 / 20;
+      const outBR = (out[2] ?? 0) / (out[0] ?? 1);
+      expect(outBR).toBeCloseTo(inBR, 3);
+    },
+  );
+
+  it.skipIf(!dawnReady)(
+    'AC-05: exposure=2 + light=1 mid-grey ~ exposure=1 + light=2 mid-grey',
+    () => {
+      // The host writes `params.exposure` into byte offset 0 of the 16 B
+      // TonemapParams UBO. AC-05 mandates that `(exposure=2.0, L=L0)` and
+      // `(exposure=1.0, L=2*L0)` produce equivalent output at the fragment
+      // stage. The TS port mirrors this multiplicative pre-stage exactly.
+      const lInA: [number, number, number] = [1, 1, 1];
+      const lInB: [number, number, number] = [2, 2, 2];
+      const outA = tonemapReinhardLuminance(lInA, 2.0, 4.0);
+      const outB = tonemapReinhardLuminance(lInB, 1.0, 4.0);
+      expect(outA[0]).toBeCloseTo(outB[0] ?? 0, 5);
+      expect(outA[1]).toBeCloseTo(outB[1] ?? 0, 5);
+      expect(outA[2]).toBeCloseTo(outB[2] ?? 0, 5);
+    },
+  );
+
+  it.skipIf(!dawnReady)('AC-06: Lw=L grey saturates to 1 (extended-Reinhard knee)', () => {
+    // For a grey input where `L == Lw`, the extended Reinhard curve
+    // sends Y' to exactly 1 (the knee point). AC-06 motivates the white
+    // point semantic: AI users tune Lw to set the "this is the brightest
+    // pixel" threshold.
+    for (const Lw of [1, 2, 4, 8]) {
+      const out = tonemapReinhardLuminance([Lw, Lw, Lw], 1.0, Lw);
+      expect(out[0]).toBeCloseTo(1, 4);
+      expect(out[1]).toBeCloseTo(1, 4);
+      expect(out[2]).toBeCloseTo(1, 4);
+    }
+  });
+
+  it.skipIf(!dawnReady)(
+    'D-O3: shared TONEMAP_LUMINANCE_EPSILON floor protects against degenerate inputs',
+    () => {
+      // exposure = 0 + Lw = 0 is the absolute degenerate case. Without the
+      // floor the divisor goes through 0 and produces NaN; with the floor
+      // every channel collapses to a finite zero (charter P3 explicit
+      // failure: a NaN would propagate through the swap-chain and produce
+      // visually undefined pixels).
+      expect(TONEMAP_LUMINANCE_EPSILON).toBe(1e-5);
+      const out = tonemapReinhardLuminance([5, 3, 1], 0.0, 4.0);
+      expect(Number.isFinite(out[0])).toBe(true);
+      expect(Number.isFinite(out[1])).toBe(true);
+      expect(Number.isFinite(out[2])).toBe(true);
+      expect(out[0]).toBeCloseTo(0, 6);
+      expect(out[1]).toBeCloseTo(0, 6);
+      expect(out[2]).toBeCloseTo(0, 6);
+    },
+  );
+});

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

@@ -0,0 +1,291 @@
+// 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-gpu-resource-store-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 { 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/internal';
+import { createRenderer } from '@forgeax/engine-runtime';
+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 { drawPublished } from '../draw-published';
+import { createTestRenderAssetStore } from '../helpers/render-asset-port';
+
+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;
+
+    const assetStore = createTestRenderAssetStore();
+    let renderer: Awaited<ReturnType<typeof createRenderer>>;
+    try {
+      renderer = await createRenderer(
+        mockCanvas,
+        {},
+        {
+          shaderManifestUrl: ENGINE_MANIFEST_URL,
+          assetResolver: assetStore.resolver,
+        },
+      );
+    } 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;
+
+    // 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();
+    assetStore.resolver.publish(AssetGuid.format(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);
+  });
+});