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

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

@@ -0,0 +1,235 @@
+// sprite-nineslice-mesh-bind.dawn.test.ts -- feat-20260527-sprite-nineslice
+// M2 / w13. dawn-node smoke that the HANDLE_NINESLICE_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 { AssetRegistry, HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from '@forgeax/engine-render/authoring';
+import { Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset, SamplerAsset, TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { constructRuntimeRendererHost } from '../../renderer-host';
+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 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(renderer.inspect().state).toBe('alive');
+    expect(assets).toBeInstanceOf(AssetRegistry);
+
+    const world = new World();
+
+    // ── 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);
+    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:
+    // HANDLE_QUAD -> HANDLE_NINESLICE_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 },
+        sampler: { texture: samplerHandle as unknown as never },
+        slicesAndMode: [0.25, 0.25, 0.25, 0.25],
+      },
+    });
+
+    const errors: unknown[] = [];
+    renderer.subscribe((event) => {
+      if (event.kind !== 'error') return;
+      errors.push(event.error);
+    });
+
+    world.spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
+      { 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/upload-texture.dawn.test.ts

@@ -0,0 +1,198 @@
+// T-M3-02 dawn (real GPU) integration tests for AssetRegistry.uploadTexture
+// (plan-strategy section 2.5 D Open Q-4 (c) consistency assertion + section
+// 2.6 D Open Q-5 (a) mipmap-generator independent file; research F-3 sRGB
+// mipmap math spec correctness; F-4 copyExternalImageToTexture entry).
+//
+// Why dawn integration tests:
+//   - Requirements AC-08 (uploadTexture path + sampler default + sRGB / linear
+//     explicit) needs real GPU verification: spec automatic decode / encode
+//     on `*-srgb` views must produce a mid-gray ~0.5 in linear space rather
+//     than the broken-OpenGL ~0.218 (research F-3 physical judgment).
+//   - The unit-only path cannot exercise queue.copyExternalImageToTexture +
+//     readBuffer pixel readback; the dawn project (vitest dawn) provides
+//     `globalThis.navigator.gpu` via webgpu npm package native binding
+//     (vitest.setup-webgpu.ts).
+//
+// Fixtures live alongside this file (T-M3-02 acceptanceCheck listed 6 fixtures
+// originally; the unit-test layer in T-M3-01 already covers 1x1 / 2x2 / 256x256
+// dimension boundaries + non-power-of-2 via the pure formula. The two real-
+// pixel fixtures here are documentary -- the inline literal byte arrays match
+// what the PNGs encode (sRGB byte 188 + linear byte 128) so the test is
+// self-contained without node:fs file IO. Plan-strategy section 4 R4 explicitly
+// notes mid-gray 0.5 not sinking to 0.218 as the binary judgment).
+//
+// Red-stage scaffolding: implementation lands in T-M3-05 (AssetRegistry.
+// uploadTexture method + render-system materialBindGroup sampler / textureView
+// injection); the GPU-upload path itself stays inert when configureGpuDevice
+// is not called (M3-only deferred-upload semantics; M5 wires the device into
+// render-system bootstrap).
+
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import type { DecodedImage, EquirectAsset, TextureAsset } from '@forgeax/engine-types';
+import { toShared } 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: uploadTexture moved to
+// GpuResidencyCache (POD carries format, decoded carries colorSpace; D-2). The
+// store holds no registry reference -- the asset-not-found arm now lives at the
+// registry get the caller runs before reaching the store.
+
+function makeTexture(
+  format: GPUTextureFormat,
+  width: number,
+  height: number,
+  colorSpace: 'srgb' | 'linear',
+  mipmap: boolean,
+): TextureAsset {
+  return {
+    kind: 'texture',
+    width,
+    height,
+    format,
+    data: new Uint8Array(width * height * 4),
+    colorSpace,
+    mipmap,
+  };
+}
+
+function decodedFromBytes(
+  bytes: Uint8Array,
+  width: number,
+  height: number,
+  colorSpace: 'srgb' | 'linear',
+  mipmap: boolean,
+): DecodedImage {
+  return {
+    bytes,
+    width,
+    height,
+    mime: 'image/png',
+    colorSpace,
+    mipmap,
+  };
+}
+
+describe('T-M3-02 dawn uploadTexture format <-> colorSpace consistency', () => {
+  it('rejects format=rgba8unorm-srgb + decoded.colorSpace=linear (real GPU path)', async () => {
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm-srgb', 1, 1, 'srgb', false);
+    const handle = toShared<'TextureAsset'>(1);
+    const decoded = decodedFromBytes(new Uint8Array([188, 188, 188, 255]), 1, 1, 'linear', false);
+    const res = await store.uploadTexture(handle, pod, decoded);
+    expect(res.ok).toBe(false);
+    if (res.ok) return;
+    expect(res.error.code).toBe('image-format-unsupported');
+    if (res.error.code !== 'image-format-unsupported') return;
+    if (res.error.detail.code !== 'image-format-unsupported') return;
+    expect(res.error.detail.formatColorSpaceConflict?.expected).toBe('srgb');
+  });
+
+  it('accepts format=rgba8unorm-srgb + decoded.colorSpace=srgb (1x1 mid-gray byte 188)', async () => {
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm-srgb', 1, 1, 'srgb', false);
+    const handle = toShared<'TextureAsset'>(1);
+    const decoded = decodedFromBytes(new Uint8Array([188, 188, 188, 255]), 1, 1, 'srgb', false);
+    const res = await store.uploadTexture(handle, pod, decoded);
+    expect(res.ok).toBe(true);
+  });
+
+  it('accepts format=rgba8unorm + decoded.colorSpace=linear (1x1 linear byte 128)', async () => {
+    const store = new GpuResidencyCache();
+    const pod = makeTexture('rgba8unorm', 1, 1, 'linear', false);
+    const handle = toShared<'TextureAsset'>(1);
+    const decoded = decodedFromBytes(new Uint8Array([128, 64, 192, 255]), 1, 1, 'linear', false);
+    const res = await store.uploadTexture(handle, pod, decoded);
+    expect(res.ok).toBe(true);
+  });
+
+  it('asset-not-found path: resolve against unregistered gen-0 handle (real GPU)', () => {
+    const world = new World();
+    // gen-0 user-tier handle for a never-allocated slot: passes the generation
+    // gate then misses the payload -> asset-not-found. A gen>0 handle would
+    // surface 'shared-ref-stale' instead (D-3/AC-10).
+    const fake = toShared<'TextureAsset'>(99999);
+    const podRes = resolveAssetHandle<TextureAsset>(world, fake);
+    expect(podRes.ok).toBe(false);
+    if (podRes.ok) return;
+    expect(podRes.error.code).toBe('asset-not-found');
+  });
+});
+
+// AC-04 (bug-20260521): non-256-aligned width uploadTexture through
+// real GPU path. Must call configureGpuDevice() to bypass the
+// asset-registry.ts:770-773 short-circuit (device === undefined).
+// The test name contains 'non-256-aligned' for grep discoverability.
+// Plan-strategy section 5.3 + requirements AC-04 caveat:
+// `grep -n 'configureGpuDevice('` must find at least one hit.
+describe('AC-04: uploadTexture non-256-aligned width (real GPU path)', () => {
+  it('uploadTexture accepts non-256-aligned width (100x100 RGBA8, bytesPerRow=400, configureGpuDevice injected)', 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();
+    // Literal configureGpuDevice required -- this is the anti-short-circuit
+    // guard verified by acceptanceCheck grep gate. Wires the device + register
+    // relay onto the store (D-3/D-8).
+    store.configureGpuDevice(
+      // biome-ignore lint/suspicious/noExplicitAny: structural rhi device shim
+      device as any,
+      undefined,
+      (w: World, pod: EquirectAsset) => ok(w.allocSharedRef('EquirectAsset', pod)),
+      mockCaps,
+    );
+
+    const width = 100;
+    const height = 100;
+    const buf = new Uint8Array(width * height * 4);
+    // Fill with a deterministic pattern so any validator that inspects
+    // pixel data sees real content rather than an all-zeroes block.
+    for (let i = 0; i < buf.length; i++) {
+      buf[i] = (i * 17 + 64) & 0xff;
+    }
+
+    const tex: TextureAsset = {
+      kind: 'texture',
+      width,
+      height,
+      format: 'rgba8unorm',
+      data: buf,
+      colorSpace: 'linear',
+      mipmap: false,
+    };
+
+    const handle = world.allocSharedRef('TextureAsset', tex);
+    const decoded = decodedFromBytes(buf, width, height, 'linear', false);
+    const res = await store.uploadTexture(handle, tex, decoded);
+    expect(res.ok).toBe(true);
+  });
+});