@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/render-system-record.test.ts

@@ -6,25 +6,13 @@
 // Each original file body sits in its own block-scope so helper names
 // cannot collide; describe() inside still registers globally with vitest.
 
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import {
   SPRITE_PREMULTIPLIED_ALPHA_BLEND,
   SpriteRegionOverride,
 } from '@forgeax/engine-render/authoring';
-import type { DispatchEntry } from '@forgeax/engine-render/internal';
-import * as recordModule from '@forgeax/engine-render/internal';
-import {
-  Camera,
-  createEngineMetrics,
-  detectNineSliceScaleTooSmall,
-  extractFrame,
-  isLitMaterialSnapshot,
-  type MaterialSnapshot,
-  MeshFilter,
-  MeshRenderer,
-  prepareExtractContext,
-  writeMaterialSnapshotPayload,
-} from '@forgeax/engine-render/internal';
 import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 import { ShaderRegistry, type ShaderRegistryDevice } from '@forgeax/engine-shader';
 import type {
@@ -33,40 +21,200 @@ import type {
   MaterialPass,
   MeshAsset,
   ParamSchemaEntry,
-  PassSelector,
 } from '@forgeax/engine-types';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { createTestRenderAssetOwner } from './helpers/render-asset-port';
+import { createEngineMetrics } from '../../../render/src/engine-metrics';
+import { isLitMaterialSnapshot } from '../../../render/src/record/helpers';
+import * as recordModule from '../../../render/src/record/main-pass-material';
+import { detectNineSliceScaleTooSmall } from '../../../render/src/record/main-pass-material';
+import * as spriteRecordModule from '../../../render/src/record/main-pass-sprite-draws';
+import { filterDispatchBySelector } from '../../../render/src/record/shadow-pass';
+import type { DispatchEntry, MaterialSnapshot } from '../../../render/src/render-system-extract';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+
+// ─── from render-system-record-pbr-ubo-stable.test.ts ───
+{
+  // render-system-record-pbr-ubo-stable - feat-20260527-sprite-nineslice M2 / w6.
+  //
+  // PBR Material UBO byte-sequence regression net (D-7 isolation):
+  // any deviation in the PBR write path's byte sequence (even 1 byte) caused
+  // by the sprite-branch schema-driven UBO extension (w11) MUST fail this test
+  // — that triggers R-8 fallback (revert D-7 to physically isolated sprite
+  // write function).
+  //
+  // w11 will extract the inline PBR UBO write path
+  // (render-system-record.ts:2194-2277 -- baseColor, metallic, roughness,
+  // channelMap u32 packing, emissive, occlusionStrength, paramSnapshot
+  // schema-driven overlay) into a pure helper
+  // `buildPbrMaterialUboPayload(material) -> Uint8Array(288B)` so this
+  // regression test can exercise the PBR write byte-for-byte.
+  //
+  // The helper MUST produce the exact byte sequence the inline path produced
+  // pre-feat (no slices-related side effects on the PBR layout). This test
+  // asserts the PBR baseline against literal byte values.
+  //
+  // Coverage:
+  //   - 304 B payload (STANDARD_PBR_UBO_SIZE)
+  //   - slot 0 = baseColor.rgb + 1 (alpha hardcoded)
+  //   - slot 1 first 8 B = metallic, roughness (f32x2)
+  //   - slot 1 last 4 u32 (channelMap) = [2, 1, 0, 0]
+  //   - slot 2 = emissive.rgb + emissiveIntensity
+  //   - slot 3 first 4 B = occlusionStrength; rest stays 0 (no schema overlay
+  //     in default-standard-pbr path; paramSnapshot reuses slot 0/1/2 by
+  //     position).
+  //
+  // Anchors: plan-strategy §R-8, §5.3 key tests #2; AGENTS.md §Error model
+  // (closed-union AssetErrorCode unchanged, baseline test does not depend on
+  // new error members).
 
-describe('derived material record stop-draw (w28)', () => {
-  it('returns a structured bounds error before a slot can be uploaded', () => {
-    const result = writeMaterialSnapshotPayload(
-      {
-        baseColor: new Float32Array([1, 1, 1]) as unknown as MaterialSnapshot['baseColor'],
-        metallic: 0,
-        roughness: 1,
-        materialParamSchema: [{ name: 'albedo', type: 'texture2d' }],
-        textureCoordinates: new Map([
-          [
-            'albedo',
-            {
-              set: 0,
-              transform: { offset: [0, 0], scale: [1, 1], rotation: 0 },
-              physicalUvScale: [1, 1],
-            },
-          ],
-        ]),
-      },
-      16,
-    );
+  const mod = recordModule as unknown as {
+    buildPbrMaterialUboPayload?: (material: MaterialSnapshot) => Uint8Array;
+    applyMaterialTextureUvScales?: (
+      payload: ArrayBuffer | Uint8Array,
+      material: MaterialSnapshot,
+      world: World,
+    ) => void;
+  };
 
-    expect(result).toMatchObject({
-      ok: false,
-      error: { code: 'material-payload-bounds', detail: { action: 'stop-draw' } },
+  function makePbrSnapshot(opts: {
+    baseColor?: readonly [number, number, number, number];
+    metallic?: number;
+    roughness?: number;
+    emissive?: readonly [number, number, number];
+    emissiveIntensity?: number;
+    occlusionStrength?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    specularTint?: readonly [number, number, number];
+  }): MaterialSnapshot {
+    return {
+      baseColor: opts.baseColor ?? [0.5, 0.6, 0.7, 1],
+      metallic: opts.metallic ?? 0.1,
+      roughness: opts.roughness ?? 0.4,
+      materialShaderId: 'forgeax::default-standard-pbr',
+      paramSnapshot: undefined,
+      ...(opts.emissive !== undefined && { emissive: opts.emissive }),
+      ...(opts.emissiveIntensity !== undefined && { emissiveIntensity: opts.emissiveIntensity }),
+      ...(opts.occlusionStrength !== undefined && { occlusionStrength: opts.occlusionStrength }),
+      ...(opts.clearcoat !== undefined && { clearcoat: opts.clearcoat }),
+      ...(opts.clearcoatRoughness !== undefined && { clearcoatRoughness: opts.clearcoatRoughness }),
+      ...(opts.specularTint !== undefined && { specularTint: opts.specularTint }),
+    } as unknown as MaterialSnapshot;
+  }
+
+  describe('PBR Material UBO byte sequence regression net (M2 / w6, D-7 isolation)', () => {
+    it('export: buildPbrMaterialUboPayload helper is exported from render-system-record', () => {
+      expect(typeof mod.buildPbrMaterialUboPayload).toBe('function');
+    });
+
+    it('304 B payload size + standard PBR slot layout (baseline)', () => {
+      if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
+        throw new Error('helper not exported yet');
+      }
+      const snap = makePbrSnapshot({
+        baseColor: [0.5, 0.6, 0.7, 1],
+        metallic: 0.1,
+        roughness: 0.4,
+        emissive: [0, 0, 0],
+        emissiveIntensity: 0,
+        occlusionStrength: 1,
+        clearcoat: 0.85,
+        clearcoatRoughness: 0.12,
+        specularTint: [0.11, 0.22, 0.33],
+      });
+      const buf = mod.buildPbrMaterialUboPayload(snap);
+      expect(buf.byteLength).toBe(304);
+      const f32 = new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+      // feat-20260613 fix-issue-1 (D-8 channelMap split): the 4 channelMap
+      // u32 slots collapse into 4 independent f32 channel selectors at
+      // f32[6..9] (metallicChannel/roughnessChannel/aoChannel/extraChannel).
+      // baseColor.rgb + alpha=1 (alpha hardcoded in PBR write path).
+      expect(f32[0]).toBeCloseTo(0.5);
+      expect(f32[1]).toBeCloseTo(0.6);
+      expect(f32[2]).toBeCloseTo(0.7);
+      expect(f32[3]).toBe(1);
+      // metallic + roughness (first 8 B of slot 1).
+      expect(f32[4]).toBeCloseTo(0.1);
+      expect(f32[5]).toBeCloseTo(0.4);
+      // 4 channel selectors as f32 (default = B/G/R/_ glTF packing).
+      expect(f32[6]).toBe(2); // metallicChannel  <- B
+      expect(f32[7]).toBe(1); // roughnessChannel <- G
+      expect(f32[8]).toBe(0); // aoChannel        <- R
+      expect(f32[9]).toBe(0); // extraChannel     <- reserved
+      // offsets 40..47 implicit pad (vec3 align=16 before emissive).
+      expect(f32[10]).toBe(0);
+      expect(f32[11]).toBe(0);
+      // emissive.rgb + emissiveIntensity (offset 48..63).
+      expect(f32[12]).toBe(0);
+      expect(f32[13]).toBe(0);
+      expect(f32[14]).toBe(0);
+      expect(f32[15]).toBe(0);
+      // occlusionStrength (offset 64..67).
+      expect(f32[16]).toBe(1);
+      // alphaCutoff (offset 68).
+      expect(f32[17]).toBe(0);
+      // clearcoat layer (offsets 72..79).
+      expect(f32[18]).toBeCloseTo(0.85);
+      expect(f32[19]).toBeCloseTo(0.12);
+      // specularTint vec3 (offsets 80..92).
+      expect(f32[20]).toBeCloseTo(0.11);
+      expect(f32[21]).toBeCloseTo(0.22);
+      expect(f32[22]).toBeCloseTo(0.33);
+      expect(f32[72]).toBe(1);
+    });
+
+    it('writes schema-carried alphaCutoff into the baseline PBR payload', () => {
+      if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
+        throw new Error('helper not exported yet');
+      }
+      const payload = mod.buildPbrMaterialUboPayload({
+        ...makePbrSnapshot({}),
+        paramSnapshot: { alphaCutoff: 0.5 },
+      } as MaterialSnapshot);
+      const f32 = new Float32Array(payload.buffer, payload.byteOffset, payload.byteLength / 4);
+      expect(f32[17]).toBeCloseTo(0.5);
+    });
+
+    it('keeps engine-owned texture UV tails aligned across PBR and sprite layouts', () => {
+      const apply = mod.applyMaterialTextureUvScales;
+      if (typeof apply !== 'function') throw new Error('helper not exported yet');
+      const world = new World();
+      const pbrPayload = new ArrayBuffer(304);
+      apply(pbrPayload, makePbrSnapshot({}), world);
+      const pbrF32 = new Float32Array(pbrPayload);
+      expect(pbrF32[26]).toBe(1);
+      expect(pbrF32[34]).toBe(1);
+      expect(pbrF32[42]).toBe(1);
+      expect(pbrF32[50]).toBe(1);
+      expect(pbrF32[58]).toBe(1);
+      expect(pbrF32[66]).toBe(1);
+
+      const spritePayload = new ArrayBuffer(128);
+      apply(
+        spritePayload,
+        { ...makePbrSnapshot({}), materialShaderId: 'forgeax::sprite' } as MaterialSnapshot,
+        world,
+      );
+      const spriteF32 = new Float32Array(spritePayload);
+      expect(Array.from(spriteF32.slice(16, 24))).toEqual([0, 0, 1, 1, 0, 0, 1, 1]);
+    });
+
+    it('byte-stable across two equivalent PBR snapshots (idempotent write)', () => {
+      if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
+        throw new Error('helper not exported yet');
+      }
+      const snap = makePbrSnapshot({
+        baseColor: [0.2, 0.3, 0.4, 1],
+        metallic: 0.5,
+        roughness: 0.5,
+      });
+      const a = mod.buildPbrMaterialUboPayload(snap);
+      const b = mod.buildPbrMaterialUboPayload(snap);
+      expect(new Uint8Array(a)).toEqual(new Uint8Array(b));
     });
   });
-});
+}
 
 // ─── from render-system-record-scale-too-small.test.ts ───
 {
@@ -74,7 +222,7 @@ describe('derived material record stop-draw (w28)', () => {
   //
   // AC-16 end-to-end: when a 9-slice sprite entity carries a Transform.scale
   // below the four corner anchors, the detection path bumps
-  // `renderer.metrics.snapshot()['nineslice.scale-too-small']` once per offending
+  // the owner metrics snapshot's `nineslice.scale-too-small` key once per offending
   // renderableIndex per RenderSystem lifetime. AI users observe the breach
   // through the EngineMetrics counter rather than parsing console.warn text
   // (charter P3 machine-readable signals).
@@ -290,7 +438,7 @@ describe('derived material record stop-draw (w28)', () => {
   describe('SpriteRegionOverride compose 9-slice (M4 / w17b, AC-14)', () => {
     it('(1) entity without override uses asset-side region', () => {
       const world = new World();
-      const assets = createTestRenderAssetOwner(makeShaderRegistryWithSprite());
+      const assets = new AssetRegistry(makeShaderRegistryWithSprite());
       const mesh = registerSpriteMesh(world);
       const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
         kind: 'material',
@@ -318,7 +466,7 @@ describe('derived material record stop-draw (w28)', () => {
 
     it('(2) entity with override uses the override region in the snapshot', () => {
       const world = new World();
-      const assets = createTestRenderAssetOwner(makeShaderRegistryWithSprite());
+      const assets = new AssetRegistry(makeShaderRegistryWithSprite());
       const mesh = registerSpriteMesh(world);
       const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
         kind: 'material',
@@ -352,7 +500,7 @@ describe('derived material record stop-draw (w28)', () => {
 
     it('(3) two entities sharing one material diverge on effective region (compose with 9-slice)', () => {
       const world = new World();
-      const assets = createTestRenderAssetOwner(makeShaderRegistryWithSprite());
+      const assets = new AssetRegistry(makeShaderRegistryWithSprite());
       const mesh = registerSpriteMesh(world);
       const matHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
         kind: 'material',
@@ -583,15 +731,6 @@ describe('derived material record stop-draw (w28)', () => {
   //
   // Anchors: plan-strategy section 5.3 key tests; requirements AC-03/AC-04/AC-18.
 
-  const filterDispatchBySelector = (
-    recordModule as unknown as {
-      filterDispatchBySelector?: (
-        dispatch: readonly DispatchEntry[],
-        selector: PassSelector,
-      ) => readonly DispatchEntry[];
-    }
-  ).filterDispatchBySelector;
-
   function makeDispatchEntry(
     renderableIndex: number,
     passIndex: number,
@@ -890,6 +1029,191 @@ describe('derived material record stop-draw (w28)', () => {
   });
 }
 
+// --- from feat-20260625-refactor-sprite-as-transparent-mesh M1 / w2 ---
+{
+  // standard-pbr regression: the generic writer over the engine-shipped
+  // default-standard-pbr.material.json paramSchema (15 numeric entries
+  // std140-packed into 96 B) must produce byte-identical output to
+  // buildPbrMaterialUboPayload. This is the gate plan-strategy section 2
+  // D-2 sets so the generic writer can replace the inline overlay without
+  // perturbing PBR rendering. RED until w3 lands the helper.
+
+  const mod = recordModule as unknown as {
+    applyParamSnapshotToUbo?: (
+      payload: ArrayBuffer | Uint8Array,
+      paramSchema: readonly ParamSchemaEntry[] | undefined,
+      paramSnapshot:
+        | Readonly<Record<string, number | readonly number[] | string | undefined>>
+        | undefined,
+    ) => void;
+    buildPbrMaterialUboPayload?: (material: MaterialSnapshot) => Uint8Array;
+  };
+
+  // Mirror the engine-shipped default-standard-pbr.material.json schema
+  // (the on-disk SSOT; inline here to keep the unit suite free of asset
+  // loads).
+  const STANDARD_PBR_SCHEMA: readonly ParamSchemaEntry[] = [
+    { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+    { name: 'metallic', type: 'f32', default: 0 },
+    { name: 'roughness', type: 'f32', default: 0.5 },
+    { name: 'metallicChannel', type: 'f32', default: 2 },
+    { name: 'roughnessChannel', type: 'f32', default: 1 },
+    { name: 'aoChannel', type: 'f32', default: 0 },
+    { name: 'extraChannel', type: 'f32', default: 0 },
+    { name: 'emissive', type: 'vec3', default: [0, 0, 0] },
+    { name: 'emissiveIntensity', type: 'f32', default: 0 },
+    { name: 'occlusionStrength', type: 'f32', default: 1 },
+    { name: 'alphaCutoff', type: 'f32', default: 0 },
+    { name: 'clearcoat', type: 'f32', default: 0 },
+    { name: 'clearcoatRoughness', type: 'f32', default: 0.5 },
+    { name: 'specularTint', type: 'vec3', default: [1, 1, 1] },
+  ];
+
+  describe('applyParamSnapshotToUbo: standard-pbr byte-identical via derive (M1 / w2)', () => {
+    it('derive(standard-pbr).uboLayout matches the 96 B authored numeric layout', () => {
+      const { uboLayout } = derive(STANDARD_PBR_SCHEMA);
+      expect(uboLayout.totalBytes).toBe(96);
+      const byName = new Map(uboLayout.entries.map((e) => [e.name, e]));
+      expect(byName.get('baseColor')?.offset).toBe(0);
+      expect(byName.get('metallic')?.offset).toBe(16);
+      expect(byName.get('roughness')?.offset).toBe(20);
+      expect(byName.get('metallicChannel')?.offset).toBe(24);
+      expect(byName.get('roughnessChannel')?.offset).toBe(28);
+      expect(byName.get('aoChannel')?.offset).toBe(32);
+      expect(byName.get('extraChannel')?.offset).toBe(36);
+      // vec3 aligns to 16: cursor at 40 rounds up to 48.
+      expect(byName.get('emissive')?.offset).toBe(48);
+      expect(byName.get('emissiveIntensity')?.offset).toBe(60);
+      expect(byName.get('occlusionStrength')?.offset).toBe(64);
+      expect(byName.get('alphaCutoff')?.offset).toBe(68);
+      expect(byName.get('clearcoat')?.offset).toBe(72);
+      expect(byName.get('clearcoatRoughness')?.offset).toBe(76);
+      expect(byName.get('specularTint')?.offset).toBe(80);
+    });
+
+    it('generic writer over standard-pbr snapshot equals buildPbrMaterialUboPayload bytes', () => {
+      if (typeof mod.applyParamSnapshotToUbo !== 'function') {
+        throw new Error('helper not exported yet (red phase)');
+      }
+      if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
+        throw new Error('buildPbrMaterialUboPayload missing -- baseline broken');
+      }
+      // Construct a snapshot equivalent to the explicit material fields the
+      // legacy helper consumes (baseColor / metallic / roughness / emissive /
+      // emissiveIntensity / occlusionStrength + the channelMap defaults the
+      // helper hard-codes).
+      const baseColor = [0.5, 0.6, 0.7, 1] as readonly number[];
+      const metallic = 0.1;
+      const roughness = 0.4;
+      const emissive = [0, 0, 0] as readonly number[];
+      const emissiveIntensity = 0;
+      const occlusionStrength = 1;
+      const material = {
+        baseColor,
+        metallic,
+        roughness,
+        materialShaderId: 'forgeax::default-standard-pbr',
+        paramSnapshot: undefined,
+        emissive,
+        emissiveIntensity,
+        occlusionStrength,
+        alphaCutoff: 0,
+        clearcoat: 0,
+        clearcoatRoughness: 0.5,
+        specularTint: [1, 1, 1],
+      } as unknown as MaterialSnapshot;
+      const baseline = mod.buildPbrMaterialUboPayload(material);
+      // Construct the generic-writer output: start from the same explicit
+      // PBR baseline, then apply the generic overlay over a paramSnapshot
+      // carrying the same values. The overlay must not perturb any byte
+      // the explicit baseline already wrote (charter P4 -- one writer, one
+      // byte layout).
+      const candidate = mod.buildPbrMaterialUboPayload(material);
+      const snapshot = {
+        baseColor,
+        metallic,
+        roughness,
+        metallicChannel: 2,
+        roughnessChannel: 1,
+        aoChannel: 0,
+        extraChannel: 0,
+        emissive,
+        emissiveIntensity,
+        occlusionStrength,
+        specularTint: [1, 1, 1],
+      };
+      mod.applyParamSnapshotToUbo(candidate, STANDARD_PBR_SCHEMA, snapshot);
+      expect(new Uint8Array(candidate)).toEqual(new Uint8Array(baseline));
+    });
+
+    it('overlays non-opaque standard-PBR baseColor alpha over the opaque baseline', () => {
+      if (typeof mod.applyParamSnapshotToUbo !== 'function') {
+        throw new Error('helper not exported yet (red phase)');
+      }
+      if (typeof mod.buildPbrMaterialUboPayload !== 'function') {
+        throw new Error('buildPbrMaterialUboPayload missing -- baseline broken');
+      }
+      const material = {
+        baseColor: [0.5, 0.6, 0.7, 0.5],
+        metallic: 0,
+        roughness: 0.5,
+        materialShaderId: 'forgeax::default-standard-pbr',
+        paramSnapshot: undefined,
+      } as unknown as MaterialSnapshot;
+      const payload = mod.buildPbrMaterialUboPayload(material);
+      // The explicit baseline is intentionally opaque; importer-supplied
+      // paramSnapshot values must overwrite all four baseColor components.
+      expect(new Float32Array(payload.buffer, payload.byteOffset, payload.byteLength / 4)[3]).toBe(
+        1,
+      );
+      mod.applyParamSnapshotToUbo(payload, STANDARD_PBR_SCHEMA, {
+        baseColor: [0.5, 0.6, 0.7, 0.5],
+      });
+      expect(new Float32Array(payload.buffer, payload.byteOffset, payload.byteLength / 4)[3]).toBe(
+        0.5,
+      );
+    });
+
+    it('honours f32 slot offsets independently (slot 1 width = 4 floats from metallic..extraChannel)', () => {
+      if (typeof mod.applyParamSnapshotToUbo !== 'function') {
+        throw new Error('helper not exported yet (red phase)');
+      }
+      const buf = new ArrayBuffer(80);
+      // f32-exact values (powers of 2 / sums) so we can assert toEqual on
+      // every slot; toBeCloseTo would let off-by-one-bit drifts hide.
+      const snapshot = {
+        baseColor: [0.125, 0.25, 0.5, 1] as readonly number[],
+        metallic: 0.5,
+        roughness: 0.25,
+        metallicChannel: 2,
+        roughnessChannel: 1,
+        aoChannel: 0,
+        extraChannel: 0,
+        emissive: [0.5, 0.5, 0.5] as readonly number[],
+        emissiveIntensity: 1.5,
+        occlusionStrength: 0.75,
+      };
+      mod.applyParamSnapshotToUbo(buf, STANDARD_PBR_SCHEMA, snapshot);
+      const f32 = new Float32Array(buf);
+      // baseColor occupies slot 0 (offset 0).
+      expect(Array.from(f32.slice(0, 4))).toEqual([0.125, 0.25, 0.5, 1]);
+      // 4 f32 channels packed at offset 16..36 -- distinct slots, not folded
+      // into one vec4 (regression against legacy "first two f32 only"
+      // overlay at render-system-record.ts:4334-4374).
+      expect(f32[4]).toBe(0.5);
+      expect(f32[5]).toBe(0.25);
+      expect(f32[6]).toBe(2);
+      expect(f32[7]).toBe(1);
+      expect(f32[8]).toBe(0);
+      expect(f32[9]).toBe(0);
+      // emissive vec3 at offset 48 (f32 index 12).
+      expect(Array.from(f32.slice(12, 15))).toEqual([0.5, 0.5, 0.5]);
+      expect(f32[15]).toBe(1.5);
+      expect(f32[16]).toBe(0.75);
+    });
+  });
+}
+
 // --- from feat-20260625-refactor-sprite-as-transparent-mesh M2 / w4 ---
 {
   // AC-05: a MaterialSnapshot carrying transparent:true on its source pass
@@ -927,11 +1251,13 @@ describe('derived material record stop-draw (w28)', () => {
     };
   };
 
-  const mod = recordModule as unknown as {
+  const spriteMod = spriteRecordModule as unknown as {
     computeSplitLdrSprite?: (
       validatedOrdered: readonly (DispatchEntryLike | undefined)[],
       tonemapActive: boolean,
     ) => boolean;
+  };
+  const mod = recordModule as unknown as {
     isEntityFullyTransparent?: (source: {
       material: MaterialSnapshot;
       materials?: readonly MaterialSnapshot[];
@@ -962,11 +1288,11 @@ describe('derived material record stop-draw (w28)', () => {
 
   describe('transparent decouples from sprite shader (M2 / w4, AC-05)', () => {
     it('export: computeSplitLdrSprite helper is exported from render-system-record', () => {
-      expect(typeof mod.computeSplitLdrSprite).toBe('function');
+      expect(typeof spriteMod.computeSplitLdrSprite).toBe('function');
     });
 
     it('non-sprite shader with transparent:true triggers LDR split', () => {
-      if (typeof mod.computeSplitLdrSprite !== 'function') {
+      if (typeof spriteMod.computeSplitLdrSprite !== 'function') {
         throw new Error('computeSplitLdrSprite helper not exported yet (red phase)');
       }
       const transparentSnap = makeTransparentSnap({
@@ -980,7 +1306,7 @@ describe('derived material record stop-draw (w28)', () => {
       // tonemapActive=false (LDR path) + a transparent entry in the
       // validated list -- the split decision must trip even though the
       // shader is not forgeax::sprite (AC-05 proves the decoupling).
-      const split = mod.computeSplitLdrSprite(
+      const split = spriteMod.computeSplitLdrSprite(
         [makeValidatedEntry(opaqueSnap), makeValidatedEntry(transparentSnap)],
         false,
       );
@@ -988,7 +1314,7 @@ describe('derived material record stop-draw (w28)', () => {
     });
 
     it('LDR split stays false on pure-opaque non-sprite list', () => {
-      if (typeof mod.computeSplitLdrSprite !== 'function') {
+      if (typeof spriteMod.computeSplitLdrSprite !== 'function') {
         throw new Error('computeSplitLdrSprite helper not exported yet (red phase)');
       }
       const opaqueA = makeTransparentSnap({
@@ -999,7 +1325,7 @@ describe('derived material record stop-draw (w28)', () => {
         transparent: false,
         materialShaderId: 'forgeax::default-standard-pbr',
       });
-      const split = mod.computeSplitLdrSprite(
+      const split = spriteMod.computeSplitLdrSprite(
         [makeValidatedEntry(opaqueA), makeValidatedEntry(opaqueB)],
         false,
       );
@@ -1007,19 +1333,19 @@ describe('derived material record stop-draw (w28)', () => {
     });
 
     it('HDR path (tonemapActive=true) suppresses split even with transparent entries', () => {
-      if (typeof mod.computeSplitLdrSprite !== 'function') {
+      if (typeof spriteMod.computeSplitLdrSprite !== 'function') {
         throw new Error('computeSplitLdrSprite helper not exported yet (red phase)');
       }
       const transparentSnap = makeTransparentSnap({
         transparent: true,
         materialShaderId: 'forgeax::unlit-test',
       });
-      const split = mod.computeSplitLdrSprite([makeValidatedEntry(transparentSnap)], true);
+      const split = spriteMod.computeSplitLdrSprite([makeValidatedEntry(transparentSnap)], true);
       expect(split).toBe(false);
     });
 
     it('M3 / w13: legacy sprite material without transparent:true does NOT trigger split (union arm deleted)', () => {
-      if (typeof mod.computeSplitLdrSprite !== 'function') {
+      if (typeof spriteMod.computeSplitLdrSprite !== 'function') {
         throw new Error('computeSplitLdrSprite helper not exported yet (red phase)');
       }
       // feat-20260625-refactor-sprite-as-transparent-mesh M3 / w13 (D-3):
@@ -1035,7 +1361,7 @@ describe('derived material record stop-draw (w28)', () => {
         materialShaderId: 'forgeax::sprite',
         paramSnapshot: {},
       } as unknown as MaterialSnapshot;
-      const splitWithoutTransparent = mod.computeSplitLdrSprite(
+      const splitWithoutTransparent = spriteMod.computeSplitLdrSprite(
         [makeValidatedEntry(legacySpriteNoTransparent)],
         false,
       );
@@ -1047,7 +1373,7 @@ describe('derived material record stop-draw (w28)', () => {
         ...legacySpriteNoTransparent,
         transparent: true,
       } as unknown as MaterialSnapshot;
-      const splitWithTransparent = mod.computeSplitLdrSprite(
+      const splitWithTransparent = spriteMod.computeSplitLdrSprite(
         [makeValidatedEntry(spriteTransparent)],
         false,
       );
@@ -1074,7 +1400,7 @@ describe('derived material record stop-draw (w28)', () => {
     // material[0] is opaque (the crosswalk case: opaque road submesh[0] +
     // BLEND decal submesh[1] on one multi-material mesh).
     it('per-submesh: split trips when only a non-zero submesh is transparent', () => {
-      if (typeof mod.computeSplitLdrSprite !== 'function') {
+      if (typeof spriteMod.computeSplitLdrSprite !== 'function') {
         throw new Error('computeSplitLdrSprite helper not exported yet');
       }
       const opaque0 = makeTransparentSnap({
@@ -1089,11 +1415,11 @@ describe('derived material record stop-draw (w28)', () => {
       const mixedEntry: DispatchEntryLike = {
         source: { material: opaque0, materials: [opaque0, transparent1] },
       };
-      expect(mod.computeSplitLdrSprite([mixedEntry], false)).toBe(true);
+      expect(spriteMod.computeSplitLdrSprite([mixedEntry], false)).toBe(true);
     });
 
     it('per-submesh: split stays false when every submesh material is opaque', () => {
-      if (typeof mod.computeSplitLdrSprite !== 'function') {
+      if (typeof spriteMod.computeSplitLdrSprite !== 'function') {
         throw new Error('computeSplitLdrSprite helper not exported yet');
       }
       const opaque0 = makeTransparentSnap({
@@ -1107,7 +1433,7 @@ describe('derived material record stop-draw (w28)', () => {
       const opaqueMixed: DispatchEntryLike = {
         source: { material: opaque0, materials: [opaque0, opaque1] },
       };
-      expect(mod.computeSplitLdrSprite([opaqueMixed], false)).toBe(false);
+      expect(spriteMod.computeSplitLdrSprite([opaqueMixed], false)).toBe(false);
     });
 
     it('isEntityFullyTransparent / entityHasTransparentSubmesh classify mixed meshes', () => {
@@ -1136,169 +1462,6 @@ describe('derived material record stop-draw (w28)', () => {
   });
 }
 
-// --- from feat-20260625-refactor-sprite-as-transparent-mesh M2 / w5 ---
-{
-  // AC-14: a transparent material whose target shader pipeline is not yet
-  // cached must surface a structured RhiError (.code / .expected / .hint),
-  // NOT silently fall back to the debug-pink placeholder. The generic
-  // materialShaderId path is the only resolver -- post feat-20260625 M3 / w14
-  // the dedicated sprite PSO fields are gone; sprite uses the same generic
-  // getMaterialShaderPipeline path every transparent material consumes.
-  //
-  // The helper signature added by w7:
-  //
-  //   selectMaterialPipelineForRender({
-  //     materialShaderId, isHdr, renderState, topology, indexFormat,
-  //     variantSet, sampleCount,
-  //     getMaterialShaderPipeline, // injected at call site (runtime.getMaterialShaderPipeline)
-  //   }): Result<RenderPipeline, RhiError>
-  //
-  // Plan anchors:
-  //   - requirements AC-14 (structured RhiError, no debug-pink fall-through)
-  //   - plan-strategy section 8.3 (error info AI users consume via property
-  //     access: .code / .expected / .hint; charter P3 explicit failure)
-  //   - plan-strategy section 2 D-3 (transparent flows through the generic
-  //     materialShaderId path; the resolver therefore never branches on
-  //     'forgeax::sprite' to recover)
-
-  type SelectArgs = {
-    readonly materialShaderId: string;
-    readonly isHdr: boolean;
-    readonly renderState: {
-      readonly blend?: {
-        readonly color: { readonly srcFactor: string; readonly dstFactor: string };
-        readonly alpha: { readonly srcFactor: string; readonly dstFactor: string };
-      };
-    };
-    readonly topology: 'triangle-list' | 'triangle-strip';
-    readonly indexFormat: 'uint16' | 'uint32';
-    readonly variantSet: string;
-    readonly sampleCount: number;
-    readonly getMaterialShaderPipeline: (
-      materialShaderId: string,
-      isHdr: boolean,
-    ) => unknown | null;
-  };
-
-  const mod = recordModule as unknown as {
-    selectMaterialPipelineForRender?: (
-      args: SelectArgs,
-    ) =>
-      | { readonly ok: true; readonly value: unknown }
-      | { readonly ok: false; readonly error: { code: string; expected: string; hint: string } };
-  };
-
-  function makeSelectArgs(overrides: {
-    materialShaderId?: string;
-    getter?: SelectArgs['getMaterialShaderPipeline'];
-  }): SelectArgs {
-    const pipelineStub = { __pipeline: true };
-    return {
-      materialShaderId: overrides.materialShaderId ?? 'forgeax::unlit-test',
-      isHdr: false,
-      renderState: {
-        blend: {
-          color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
-          alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha' },
-        },
-      },
-      topology: 'triangle-list',
-      indexFormat: 'uint16',
-      variantSet: '',
-      sampleCount: 1,
-      getMaterialShaderPipeline: overrides.getter ?? (() => pipelineStub),
-    };
-  }
-
-  describe('selectMaterialPipelineForRender pipeline-miss surfaces RhiError (M2 / w5, AC-14)', () => {
-    it('export: selectMaterialPipelineForRender helper is exported from render-system-record', () => {
-      expect(typeof mod.selectMaterialPipelineForRender).toBe('function');
-    });
-
-    it('cache miss returns ok=false with structured RhiError (.code/.expected/.hint)', () => {
-      if (typeof mod.selectMaterialPipelineForRender !== 'function') {
-        throw new Error('selectMaterialPipelineForRender helper not exported yet (red phase)');
-      }
-      const result = mod.selectMaterialPipelineForRender(
-        makeSelectArgs({
-          materialShaderId: 'forgeax::unlit-test',
-          getter: () => null, // simulate cache miss / async build pending
-        }),
-      );
-      expect(result.ok).toBe(false);
-      if (result.ok) throw new Error('unreachable -- result.ok asserted false above');
-      const err = result.error;
-      // charter P3 -- AI users branch on .code (string union member from
-      // RhiErrorCode) and consume .expected / .hint as property reads;
-      // they do NOT parse the human-facing .message string.
-      expect(typeof err.code).toBe('string');
-      expect(err.code.length).toBeGreaterThan(0);
-      expect(typeof err.expected).toBe('string');
-      expect(err.expected.length).toBeGreaterThan(0);
-      expect(typeof err.hint).toBe('string');
-      expect(err.hint.length).toBeGreaterThan(0);
-    });
-
-    it('cache miss .hint references the missing materialShaderId (AI users locate the cache key)', () => {
-      if (typeof mod.selectMaterialPipelineForRender !== 'function') {
-        throw new Error('selectMaterialPipelineForRender helper not exported yet (red phase)');
-      }
-      const result = mod.selectMaterialPipelineForRender(
-        makeSelectArgs({
-          materialShaderId: 'forgeax::missing-shader-id',
-          getter: () => null,
-        }),
-      );
-      expect(result.ok).toBe(false);
-      if (result.ok) throw new Error('unreachable -- result.ok asserted false above');
-      // The shader id must appear in .hint (or .expected) so AI users can
-      // grep the registry / pipeline cache straight from the structured
-      // error -- not from a human-prose substring of .message.
-      const exposed = `${result.error.hint} ${result.error.expected}`;
-      expect(exposed).toContain('forgeax::missing-shader-id');
-    });
-
-    it('cache hit returns ok=true with the pipeline (no error path on success)', () => {
-      if (typeof mod.selectMaterialPipelineForRender !== 'function') {
-        throw new Error('selectMaterialPipelineForRender helper not exported yet (red phase)');
-      }
-      const pipeline = { __pipeline: 'forgeax::unlit-test-pso' };
-      const result = mod.selectMaterialPipelineForRender(
-        makeSelectArgs({
-          materialShaderId: 'forgeax::unlit-test',
-          getter: () => pipeline,
-        }),
-      );
-      expect(result.ok).toBe(true);
-      if (!result.ok) throw new Error('unreachable -- result.ok asserted true above');
-      expect(result.value).toBe(pipeline);
-    });
-
-    it('cache miss does NOT silently substitute a debug-pink fallback pipeline', () => {
-      if (typeof mod.selectMaterialPipelineForRender !== 'function') {
-        throw new Error('selectMaterialPipelineForRender helper not exported yet (red phase)');
-      }
-      // Probe: the only branch the getter ever returns is the one passed in.
-      // A cache miss must surface ok=false, NOT a synthesized pipeline value
-      // that hides the miss (charter P3 -- the pre-M6 silent fallback to
-      // pipelineState.standardPipeline* was exactly this anti-pattern, see
-      // render-system-record.ts:5188-5198 commentary).
-      let getterCallCount = 0;
-      const result = mod.selectMaterialPipelineForRender(
-        makeSelectArgs({
-          materialShaderId: 'forgeax::unlit-test',
-          getter: () => {
-            getterCallCount += 1;
-            return null;
-          },
-        }),
-      );
-      expect(getterCallCount).toBeGreaterThanOrEqual(1);
-      expect(result.ok).toBe(false);
-    });
-  });
-}
-
 // ─── bug-20260622-tilemap-ysort-transparent-sort-modes-followup M2 m2-1 ───
 //
 // AC-04 (error signal SSOT) + AC-05 (LAYER_Y footY ordering) + R-2
@@ -1316,7 +1479,7 @@ describe('derived material record stop-draw (w28)', () => {
   describe('AC-04 setTransparentSortConfig mode=99 returns Result.err (KV untouched)', () => {
     it('Result.err carries code/expected/hint/detail + KV resource is NOT inserted', async () => {
       const { setTransparentSortConfig, TRANSPARENT_SORT_CONFIG_KEY } = await import(
-        '@forgeax/engine-render/internal'
+        '../../../render/src/systems/transparent-sort-config'
       );
       const world = new World();
       // Pre-check: resource MUST be absent before the rejected call.
@@ -1343,7 +1506,7 @@ describe('derived material record stop-draw (w28)', () => {
   describe('AC-05 LAYER_Y footY ordering (same layer, deeper foot draws later)', () => {
     it('footY=10/20/30 same layer -> output order footY=30/20/10 (back-to-front)', async () => {
       const { setTransparentSortConfig, TRANSPARENT_SORT_MODE_LAYER_Y } = await import(
-        '@forgeax/engine-render/internal'
+        '../../../render/src/systems/transparent-sort-config'
       );
       const { transparentSortEntries } = await import('../systems/transparent-sort');
       const world = new World();
@@ -1403,7 +1566,7 @@ describe('derived material record stop-draw (w28)', () => {
   describe('R-2 mode=DISTANCE + cameraPos absent preserves insertion order', () => {
     it('transparentSortEntries(entries, world) with mode=3 + no cameraPos = insertion order', async () => {
       const { setTransparentSortConfig, TRANSPARENT_SORT_MODE_DISTANCE } = await import(
-        '@forgeax/engine-render/internal'
+        '../../../render/src/systems/transparent-sort-config'
       );
       const { transparentSortEntries } = await import('../systems/transparent-sort');
       const world = new World();