@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/derive-bgl-integration.test.ts

@@ -25,10 +25,10 @@
 //       std140 walk produced by derive — caller writes scalars at the
 //       reported offsets and the totalBytes is the buffer allocation size.
 
-import { appendInjection } from '@forgeax/engine-render/internal';
 import type { ParamSchemaEntry } from '@forgeax/engine-types';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { appendInjection } from '../../../render/src/pbr-pipeline';
 
 // ─── Synthetic schemas (one per built-in shader family) ─────────────────────
 //
@@ -54,9 +54,7 @@ const standardPbrSchema: readonly ParamSchemaEntry[] = [
   { name: 'baseColorTexture', type: 'texture2d' },
   { name: 'metallicRoughnessTexture', type: 'texture2d' },
   { name: 'normalTexture', type: 'texture2d' },
-  { name: 'specularTintTexture', type: 'texture2d' },
   { name: 'emissiveTexture', type: 'texture2d' },
-  { name: 'occlusionTexture', type: 'texture2d' },
 ];
 
 const skinSchema: readonly ParamSchemaEntry[] = [
@@ -179,7 +177,7 @@ describe('derive(schema) integration over 5 built-in shader families (M3 w11)',
 //           injection order ibl-then-lightmap (D-8).
 
 // Exact paramSchema from packages/shader/src/default-standard-pbr.material.json:68-77
-// (15 numeric entries + 6 texture2d entries).
+// (15 numeric entries + 4 texture2d entries).
 const defaultStandardPbrSchema: readonly ParamSchemaEntry[] = [
   { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
   { name: 'metallic', type: 'f32', default: 0 },
@@ -199,22 +197,20 @@ const defaultStandardPbrSchema: readonly ParamSchemaEntry[] = [
   { name: 'metallicRoughnessTexture', type: 'texture2d' },
   { name: 'normalTexture', type: 'texture2d' },
   { name: 'specularTintTexture', type: 'texture2d' },
-  { name: 'emissiveTexture', type: 'texture2d' },
-  { name: 'occlusionTexture', type: 'texture2d' },
 ];
 
 describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
-  it('w1 user-region: derive produces 13 entries (binding 0 UBO + 6 sampler/texture pairs), userRegionBindingEnd=13', () => {
+  it('w1 user-region: derive produces 9 entries (binding 0 UBO + 4 sampler/texture pairs), userRegionBindingEnd=9', () => {
     const out = derive(defaultStandardPbrSchema);
 
-    // 15 numeric entries run-merged into binding 0 UBO + 6 textures x 2 = 1 + 12 = 13.
-    expect(out.bglEntries.length).toBe(13);
-    expect(out.userRegionBindingEnd).toBe(13);
+    // 15 numeric entries run-merged into binding 0 UBO + 4 textures x 2 = 1 + 8 = 9.
+    expect(out.bglEntries.length).toBe(9);
+    expect(out.userRegionBindingEnd).toBe(9);
 
     // Bindings 0..6 dense, no gaps.
     const bindings = out.bglEntries.map((e) => e.binding);
-    expect(new Set(bindings).size).toBe(13);
-    for (let i = 0; i < 13; i++) {
+    expect(new Set(bindings).size).toBe(9);
+    for (let i = 0; i < 9; i++) {
       expect(bindings).toContain(i);
     }
 
@@ -222,28 +218,24 @@ describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
     expect(out.bglEntries[0]?.binding).toBe(0);
     expect(out.bglEntries[0]?.buffer?.type).toBe('uniform');
 
-    // textureFieldNames covers exactly the 6 texture2d entries.
-    expect(out.textureFieldNames.size).toBe(6);
+    // textureFieldNames covers exactly the 4 texture2d entries.
+    expect(out.textureFieldNames.size).toBe(4);
     expect(out.textureFieldNames.has('baseColorTexture')).toBe(true);
     expect(out.textureFieldNames.has('metallicRoughnessTexture')).toBe(true);
     expect(out.textureFieldNames.has('normalTexture')).toBe(true);
     expect(out.textureFieldNames.has('specularTintTexture')).toBe(true);
-    expect(out.textureFieldNames.has('emissiveTexture')).toBe(true);
-    expect(out.textureFieldNames.has('occlusionTexture')).toBe(true);
 
     // sampler map: each texture has a paired sampler.
-    expect(out.samplerForTexture.size).toBe(6);
+    expect(out.samplerForTexture.size).toBe(4);
     expect(out.samplerForTexture.get('baseColorTexture')).toBe('baseColorTexture_sampler');
     expect(out.samplerForTexture.get('metallicRoughnessTexture')).toBe(
       'metallicRoughnessTexture_sampler',
     );
     expect(out.samplerForTexture.get('normalTexture')).toBe('normalTexture_sampler');
     expect(out.samplerForTexture.get('specularTintTexture')).toBe('specularTintTexture_sampler');
-    expect(out.samplerForTexture.get('emissiveTexture')).toBe('emissiveTexture_sampler');
-    expect(out.samplerForTexture.get('occlusionTexture')).toBe('occlusionTexture_sampler');
   });
 
-  it('w1 full pipeline: derive + ibl injection + lightmap injection = 24 entries dense 0..23', () => {
+  it('w1 full pipeline: derive + ibl injection + lightmap injection = 20 entries dense 0..19', () => {
     const out = derive(defaultStandardPbrSchema);
     // Same cast as append-injection.test.ts — forgeax shim → @webgpu/types via
     // explicit two-step `as unknown as`, exempt from RHI gate j.
@@ -252,21 +244,21 @@ describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
     // Injection start = userRegionBindingEnd (NOT a hardcoded 7 literal).
     const afterIbl = appendInjection(userBgl, 'ibl');
     expect(afterIbl.length).toBe(7);
-    expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd); // 13
+    expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd); // 9
 
     const mergedAfterIbl = [...userBgl, ...afterIbl];
 
     const afterLightmap = appendInjection(mergedAfterIbl, 'lightmap');
     expect(afterLightmap.length).toBe(4);
-    expect(afterLightmap[0]?.binding).toBe(mergedAfterIbl.length); // 20
+    expect(afterLightmap[0]?.binding).toBe(mergedAfterIbl.length); // 16
 
     const fullSet = [...mergedAfterIbl, ...afterLightmap];
-    expect(fullSet.length).toBe(24);
+    expect(fullSet.length).toBe(20);
 
     // Bindings 0..17 dense, no gaps.
     const bindings = fullSet.map((e) => e.binding);
-    expect(new Set(bindings).size).toBe(24);
-    for (let i = 0; i < 24; i++) {
+    expect(new Set(bindings).size).toBe(20);
+    for (let i = 0; i < 20; i++) {
       expect(bindings).toContain(i);
     }
 
@@ -289,7 +281,7 @@ describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
 
   it('w1 injection start is userRegionBindingEnd, not a hardcoded literal', () => {
     const out = derive(defaultStandardPbrSchema);
-    // Prove that userRegionBindingEnd (13 today) is what feeds injection, not a
+    // Prove that userRegionBindingEnd (9 today) is what feeds injection, not a
     // hardcoded constant embedded in test logic. The derive() output IS the SSOT.
     const userBgl = [...out.bglEntries] as unknown as readonly GPUBindGroupLayoutEntry[];
 
@@ -299,8 +291,8 @@ describe('built-in PBR derive+injection regression fence (M1 w1)', () => {
     // derive later shifts userRegionBindingEnd (e.g. to 9 for 4-texture),
     // this assertion catches the desync.
     expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd);
-    // read-back guard: confirm the derived standard contract has six textures.
-    expect(out.userRegionBindingEnd).toBe(13);
+    // read-back guard: confirm the derive result really is 9 today.
+    expect(out.userRegionBindingEnd).toBe(9);
   });
 });
 
@@ -336,21 +328,19 @@ const parallax4TextureSchema: readonly ParamSchemaEntry[] = [
   { name: 'normalTexture', type: 'texture2d' },
   { name: 'specularTintTexture', type: 'texture2d' },
   { name: 'heightTexture', type: 'texture2d' },
-  { name: 'emissiveTexture', type: 'texture2d' },
-  { name: 'occlusionTexture', type: 'texture2d' },
 ];
 
 describe('5-texture custom schema derive: heightTexture binding + injection shift (M2 w2)', () => {
   it('(a) heightTexture earns a distinct sampler(7)/texture(8) binding pair', () => {
     const out = derive(parallax4TextureSchema);
 
-    // textureFieldNames covers all 7 declared textures.
-    expect(out.textureFieldNames.size).toBe(7);
+    // textureFieldNames covers all 5 declared textures.
+    expect(out.textureFieldNames.size).toBe(5);
     expect(out.textureFieldNames.has('heightTexture')).toBe(true);
     expect(out.samplerForTexture.get('heightTexture')).toBe('heightTexture_sampler');
 
-    // 1 UBO + 7 sampler/texture pairs = 15 entries.
-    expect(out.bglEntries.length).toBe(15);
+    // 1 UBO + 5 sampler/texture pairs = 11 entries.
+    expect(out.bglEntries.length).toBe(11);
 
     // heightTexture is the 5th texture: sampler at binding 9, texture at binding 10.
     // (after baseColor 1/2, MR 3/4, normal 5/6, specular tint 7/8).
@@ -365,8 +355,8 @@ describe('5-texture custom schema derive: heightTexture binding + injection shif
   it('(b) userRegionBindingEnd=11 (4-texture baseline 9, shifted +2 by heightTexture)', () => {
     const baseline = derive(defaultStandardPbrSchema);
     const parallax = derive(parallax4TextureSchema);
-    expect(baseline.userRegionBindingEnd).toBe(13);
-    expect(parallax.userRegionBindingEnd).toBe(15);
+    expect(baseline.userRegionBindingEnd).toBe(9);
+    expect(parallax.userRegionBindingEnd).toBe(11);
     // Exactly one sampler/texture pair (2 bindings) of shift.
     expect(parallax.userRegionBindingEnd - baseline.userRegionBindingEnd).toBe(2);
   });
@@ -377,21 +367,21 @@ describe('5-texture custom schema derive: heightTexture binding + injection shif
 
     const afterIbl = appendInjection(userBgl, 'ibl');
     // Injection start follows derive().userRegionBindingEnd dynamically — for a
-    // 7-texture schema that is 15, not the 6-texture baseline's 13.
+    // 5-texture schema that is 11, not the 4-texture baseline's 9.
     expect(afterIbl[0]?.binding).toBe(out.userRegionBindingEnd);
-    expect(afterIbl[0]?.binding).toBe(15);
+    expect(afterIbl[0]?.binding).toBe(11);
 
     const mergedAfterIbl = [...userBgl, ...afterIbl];
     const afterLightmap = appendInjection(mergedAfterIbl, 'lightmap');
-    // Lightmap follows IBL: 15 + 7 = 22.
-    expect(afterLightmap[0]?.binding).toBe(22);
+    // Lightmap follows IBL: 11 + 7 = 18.
+    expect(afterLightmap[0]?.binding).toBe(18);
 
-    // Full set: 15 user-region + 7 ibl + 4 lightmap = 26 entries, dense 0..25.
+    // Full set: 11 user-region + 7 ibl + 4 lightmap = 22 entries, dense 0..21.
     const fullSet = [...mergedAfterIbl, ...afterLightmap];
-    expect(fullSet.length).toBe(26);
+    expect(fullSet.length).toBe(22);
     const bindings = fullSet.map((e) => e.binding);
-    expect(new Set(bindings).size).toBe(26);
-    for (let i = 0; i < 26; i++) {
+    expect(new Set(bindings).size).toBe(22);
+    for (let i = 0; i < 22; i++) {
       expect(bindings).toContain(i);
     }
   });

package/src/__tests__/derive-render-data-skin.unit.test.ts

@@ -3,9 +3,9 @@
 // order, including skin streams, without a parallel stride discriminator.
 
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
-import { deriveRenderDataMesh } from '@forgeax/engine-render/internal';
 import type { MeshAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { deriveRenderDataMesh } from '../../../render/src/render-data';
 
 function canonicalAttributes(vertexCount: number): MeshAsset['attributes'] {
   return {

package/src/__tests__/draw-published.ts

@@ -1,10 +1,17 @@
 import type { World } from '@forgeax/engine-ecs';
-import type { Renderer } from '@forgeax/engine-render';
+import type { FrameReceipt, RenderError, Renderer, RenderResult } from '@forgeax/engine-render';
 
 /** Drive the production attach -> update -> draw contract in direct-render tests. */
-export function drawPublished(renderer: Renderer, world: World): ReturnType<Renderer['draw']> {
-  const attached = renderer.attachWorld(world);
+export function drawPublished(
+  renderer: Renderer,
+  world: World,
+): RenderResult<FrameReceipt, RenderError> {
+  const attached = renderer.attach(world);
   if (!attached.ok) throw attached.error;
   world.update(1 / 60).unwrap();
-  return renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
+  return renderer.draw({
+    leases: [attached.value],
+    camera: { lease: attached.value },
+    environment: { lease: attached.value },
+  });
 }

package/src/__tests__/dynamic-texture-store.unit.test.ts

@@ -0,0 +1,190 @@
+// feat-20260623-world-space-video-asset M4 / w15 — DynamicTextureStore unit.
+//
+// D-3 / AC-08: the transient video texture path is fully independent of
+// GpuResidencyCache.ensureResident (the static "upload once / cache forever"
+// cache). This test pins the three load-bearing properties:
+//   1. isolation — the module does NOT import GpuResidencyCache (source scan).
+//   2. allocate-once — a steady-size clip creates exactly one GPU texture; each
+//      subsequent frame is a copyExternalImageToTexture write, not a new create.
+//   3. resize-on-change — a dimension change destroys the old texture and
+//      allocates a new one (so a clip whose intrinsic size resolves late still
+//      renders correctly).
+// Plus the structured-failure contract (charter P3): a device that rejects the
+// copy returns a Result.err, never throws.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { type DynamicTextureDevice, DynamicTextureStore } from '@forgeax/engine-assets-runtime';
+import type { Result, Texture, TextureView } from '@forgeax/engine-rhi';
+import { err, ok, RhiError } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+
+const STORE_SRC = fileURLToPath(
+  new URL('../../../assets-runtime/src/dynamic-texture-store.ts', import.meta.url),
+);
+
+interface DeviceProbe {
+  created: number;
+  destroyed: number;
+  copies: number;
+}
+
+function makeMockDevice(
+  probe: DeviceProbe,
+  opts: { copyFails?: boolean } = {},
+): DynamicTextureDevice {
+  let nextTex = 0;
+  return {
+    createTexture: (): Result<Texture, RhiError> => {
+      probe.created += 1;
+      return ok({ __tex: `tex-${++nextTex}` } as unknown as Texture);
+    },
+    createTextureView: (tex: Texture): Result<TextureView, RhiError> =>
+      ok({ __view: tex } as unknown as TextureView),
+    destroyTexture: (): Result<void, RhiError> => {
+      probe.destroyed += 1;
+      return ok(undefined);
+    },
+    queue: {
+      copyExternalImageToTexture: (): Result<void, RhiError> => {
+        probe.copies += 1;
+        if (opts.copyFails === true) {
+          return err(
+            new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'copyExternalImageToTexture succeeds',
+              hint: 'video source not yet decodable',
+            }),
+          );
+        }
+        return ok(undefined);
+      },
+    },
+  };
+}
+
+const FAKE_SOURCE = {} as unknown as GPUCopyExternalImageSourceInfo['source'];
+
+function clip(id: number): Handle<'VideoAsset', 'shared'> {
+  return toShared<'VideoAsset'>(id);
+}
+
+describe('DynamicTextureStore isolation (M4 / w15)', () => {
+  it('does NOT import GpuResidencyCache (AC-08 / D-3 independence)', () => {
+    const src = readFileSync(STORE_SRC, 'utf8');
+    // Scan import statements only — the file's prose comments reference the
+    // store/ensureResident to explain WHY they are kept separate (D-3); the
+    // load-bearing invariant is the absence of an actual import edge.
+    const importLines = src.split('\n').filter((l) => /^\s*import\b/.test(l));
+    for (const line of importLines) {
+      expect(line.includes('device/gpu-residency'), `unexpected import: ${line}`).toBe(false);
+    }
+    // No call to the static residency cache method anywhere in executable code
+    // (strip comments first so the explanatory prose does not trip the gate).
+    const stripped = src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+    expect(stripped.includes('ensureResident')).toBe(false);
+  });
+});
+
+describe('DynamicTextureStore lifecycle (M4 / w15)', () => {
+  it('allocate-once: a steady-size clip creates one texture, writes every frame', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    const h = clip(701);
+
+    for (let frame = 0; frame < 5; frame++) {
+      const res = store.uploadFrame(h, FAKE_SOURCE, 320, 240);
+      expect(res?.ok).toBe(true);
+    }
+    expect(probe.created).toBe(1);
+    expect(probe.copies).toBe(5);
+    expect(probe.destroyed).toBe(0);
+    expect(store.getView(h)).toBeDefined();
+  });
+
+  it('resize-on-change: a dimension change destroys the old texture + allocates a new one', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    const h = clip(702);
+
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+    expect(probe.created).toBe(1);
+
+    // Intrinsic size resolved (e.g. metadata loaded) -> new dimensions.
+    expect(store.uploadFrame(h, FAKE_SOURCE, 640, 480)?.ok).toBe(true);
+    expect(probe.created).toBe(2);
+    expect(probe.destroyed).toBe(1);
+  });
+
+  it('two clips get independent transient textures', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+
+    expect(store.uploadFrame(clip(710), FAKE_SOURCE, 100, 100)?.ok).toBe(true);
+    expect(store.uploadFrame(clip(711), FAKE_SOURCE, 100, 100)?.ok).toBe(true);
+    expect(probe.created).toBe(2);
+    expect(store.getView(clip(710))).not.toBe(store.getView(clip(711)));
+  });
+
+  it('device swap destroys stale entries before reusing a clip', () => {
+    const first: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const second: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    const h = clip(740);
+
+    store.configureGpuDevice(makeMockDevice(first));
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+
+    store.configureGpuDevice(makeMockDevice(second));
+    expect(first.destroyed).toBe(1);
+    expect(store.getView(h)).toBeUndefined();
+
+    expect(store.uploadFrame(h, FAKE_SOURCE, 320, 240)?.ok).toBe(true);
+    expect(second.created).toBe(1);
+    expect(second.copies).toBe(1);
+  });
+});
+
+describe('DynamicTextureStore degrade paths (M4 / w15, charter P3)', () => {
+  it('returns undefined (not an error) before a device is wired', () => {
+    const store = new DynamicTextureStore();
+    expect(store.uploadFrame(clip(720), FAKE_SOURCE, 320, 240)).toBeUndefined();
+    expect(store.getView(clip(720))).toBeUndefined();
+  });
+
+  it('returns undefined for zero / unknown source dimensions (metadata pending)', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    expect(store.uploadFrame(clip(721), FAKE_SOURCE, 0, 0)).toBeUndefined();
+    expect(probe.created).toBe(0);
+  });
+
+  it('returns a structured RhiError when the copy fails (never throws)', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe, { copyFails: true }));
+    const res = store.uploadFrame(clip(722), FAKE_SOURCE, 320, 240);
+    expect(res?.ok).toBe(false);
+    if (res !== undefined && !res.ok) {
+      expect(res.error.code).toBe('webgpu-runtime-error');
+    }
+  });
+
+  it('destroyAll destroys every transient texture + clears the views', () => {
+    const probe: DeviceProbe = { created: 0, destroyed: 0, copies: 0 };
+    const store = new DynamicTextureStore();
+    store.configureGpuDevice(makeMockDevice(probe));
+    store.uploadFrame(clip(730), FAKE_SOURCE, 64, 64);
+    store.uploadFrame(clip(731), FAKE_SOURCE, 64, 64);
+    store.destroyAll();
+    expect(probe.destroyed).toBe(2);
+    expect(store.getView(clip(730))).toBeUndefined();
+  });
+});

package/src/__tests__/equirect-bc6h.integration.test.ts

@@ -1,23 +1,148 @@
-import { deriveRenderDataCubemap } from '@forgeax/engine-render/internal';
+// equirect renderable-source integration test (feat-20260707 M5 fix, dawn env).
+//
+// The full HDR equirect chain, end to end: an equirect is ALWAYS an IBL / skybox
+// source (Skylight.equirect / SkyboxBackground.equirect drive equirect-to-cube /
+// irradiance / prefilter RENDER passes). A block-compressed HDR format
+// (bc6h-rgb-ufloat) is sample-only, never a color-renderable render target
+// ("BC6HRGBUfloat is not color renderable"), so an equirect is never
+// block-compressed: it is delivered uncompressed rgba16float. This test asserts
+// the equirect loader yields an rgba16float POD and `deriveRenderDataCubemap`
+// accepts it (renderable cube source), regardless of the device bc cap.
+//
+// This replaces the earlier "equirect -> BC6H by cap" premise, which was itself
+// the bug: BC6H equirect broke cube projection with a WebGPU device error.
+//
+// dawn env: the caps triple is printed so the lavapipe/llvmpipe BC-support
+// question stays empirically visible in CI logs; the equirect path is
+// cap-independent (always rgba16float).
+//
+// File is named `.integration.test.ts`; it is added to the dawn project
+// `include` array in the root vitest.config.ts so it runs under the dawn-node GPU
+// env, and skips itself when navigator.gpu is absent (the per-package unit
+// project) rather than failing.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
 import type { EquirectAsset } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-
-function makeEquirect(width: number, height: number): EquirectAsset {
-  const pixels = new Uint16Array(width * height * 4);
-  pixels.fill(0x3c00);
-  return {
-    kind: 'equirect',
-    width,
-    height,
-    format: 'rgba16float',
-    data: new Uint8Array(pixels.buffer),
-    colorSpace: 'linear',
-  };
+import { beforeAll, describe, expect, it } from 'vitest';
+import { deriveRenderDataCubemap } from '../../../render/src/render-data';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+const gpu = globalThis.navigator?.gpu;
+const hasGpu = gpu !== undefined;
+
+const GUID_EQUI = 'c0000000-0000-4000-a000-000065717569';
+const PACK_INDEX_URL = '/test-equirect-renderable-pack-index.json';
+
+function parseGuid(g: string): AssetGuid {
+  const parsed = AssetGuid.parse(g);
+  if (!parsed.ok) throw new Error(`bad guid ${g}`);
+  return parsed.value;
 }
 
-describe('equirect renderable-source integration', () => {
-  it('accepts the uncompressed rgba16float source required by cubemap render passes', () => {
-    const asset = makeEquirect(64, 32);
+/** A deterministic WxH rgba16float (IEEE-754 binary16) HDR image. */
+function makeHdrHalf(w: number, h: number): Uint8Array {
+  // 0x3c00 = 1.0 in binary16; vary channels so the bytes are non-trivial.
+  const px = new Uint16Array(w * h * 4);
+  for (let i = 0; i < w * h; i++) {
+    px[i * 4] = 0x3c00;
+    px[i * 4 + 1] = 0x3800; // 0.5
+    px[i * 4 + 2] = 0x3400; // 0.25
+    px[i * 4 + 3] = 0x3c00;
+  }
+  return new Uint8Array(px.buffer);
+}
+
+let bcCap = false;
+
+describe.skipIf(!hasGpu)('equirect renderable-source integration (feat-20260707 fix)', () => {
+  const width = 64;
+  const height = 32;
+  let binBytes: Uint8Array;
+  const packageUrl = '/ddc/equirect.pack.json';
+  const artifactUrl = '/ddc/equirect.bin';
+
+  beforeAll(async () => {
+    // biome-ignore lint/style/noNonNullAssertion: skipIf(!hasGpu) guards this
+    const adapter = await gpu!.requestAdapter();
+    if (adapter === null) throw new Error('no GPU adapter under dawn');
+    bcCap = adapter.features.has('texture-compression-bc');
+    // biome-ignore lint/suspicious/noConsole: keep the caps triple empirically visible in CI logs
+    console.info(
+      `[equirect caps] bc=${bcCap} etc2=${adapter.features.has(
+        'texture-compression-etc2',
+      )} astc=${adapter.features.has('texture-compression-astc')}`,
+    );
+    binBytes = makeHdrHalf(width, height);
+  });
+
+  function wireFetch(): void {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      const url = typeof input === 'string' ? input : String(input);
+      if (url === PACK_INDEX_URL) {
+        return {
+          ok: true,
+          json: async () => [{ guid: GUID_EQUI, packageUrl, kind: 'equirect' }],
+        } as Response;
+      }
+      if (url === packageUrl) {
+        return {
+          ok: true,
+          json: async () => ({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              {
+                guid: GUID_EQUI,
+                kind: 'equirect',
+                payload: {
+                  kind: 'equirect',
+                  width,
+                  height,
+                  format: 'rgba16float',
+                  colorSpace: 'linear',
+                },
+                refs: [],
+                artifacts: {
+                  body: {
+                    path: 'equirect.bin',
+                    mediaType: 'application/x-forgeax-rgba16f',
+                  },
+                },
+              },
+            ],
+          }),
+        } as Response;
+      }
+      if (url === artifactUrl) {
+        return { ok: true, arrayBuffer: async () => binBytes.buffer } as Response;
+      }
+      return { ok: false, status: 404 } as Response;
+    }) as typeof globalThis.fetch;
+  }
+
+  async function loadEquirect(): Promise<EquirectAsset> {
+    wireFetch();
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    reg.configurePackIndex(PACK_INDEX_URL);
+    reg.setTranscodeCaps({ bc: bcCap, etc2: false, astc: false });
+    const res = await reg.loadByGuid<EquirectAsset>(parseGuid(GUID_EQUI));
+    if (!res.ok) throw new Error(`equirect load failed: ${(res.error as { code: string }).code}`);
+    return res.value;
+  }
+
+  it('equirect is uncompressed rgba16float regardless of bc cap (IBL render source)', async () => {
+    const asset = await loadEquirect();
+    expect(asset.kind).toBe('equirect');
+    // Never a block-compressed format: an equirect drives cube RENDER passes and
+    // BC6H is not color-renderable.
+    expect(asset.format).toBe('rgba16float');
+  });
+
+  it('deriveRenderDataCubemap accepts the rgba16float equirect (renderable cube source)', async () => {
+    const asset = await loadEquirect();
+    // deriveRenderDataCubemap consumes a TextureAsset-shaped source; the equirect
+    // POD mirrors that 2D surface.
     const source = {
       kind: 'texture' as const,
       width: asset.width,
@@ -27,9 +152,7 @@ describe('equirect renderable-source integration', () => {
       colorSpace: asset.colorSpace,
       mipmap: false,
     };
-
-    const result = deriveRenderDataCubemap(source);
-
-    expect(result.ok).toBe(true);
+    const res = deriveRenderDataCubemap(source);
+    expect(res.ok).toBe(true);
   });
 });