@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/typed-pipeline-topology.unit.test.ts

@@ -27,6 +27,7 @@ import type {
   RenderPipelineTopology,
 } from '../render-pipeline';
 import { resolveOutputDither } from '../render-pipeline';
+import { admitSsrSpatial } from '../ssr/admission';
 import { standardTemporalPostOrder } from '../temporal/standard-scene-data';
 
 let device: RhiDevice;
@@ -178,10 +179,10 @@ function disabledDirectionalVolumeTopology(lightKind: 'point' | 'spot'): RenderP
 }
 
 function createImportedHistory(graph: RenderGraphBuilder<RenderPipelineFrame>) {
-  const target = (label: string) => {
+  const target = (label: string, format: 'rgba16float' | 'r8unorm' = 'rgba16float') => {
     const texture = graph.importTexture(
       label,
-      { format: 'rgba16float', size: 'surface', usage: 0x17 },
+      { format, size: 'surface', usage: 0x17 },
       (frame) => frame.currentTexture,
     );
     if (!texture.ok) throw texture.error;
@@ -190,7 +191,7 @@ function createImportedHistory(graph: RenderGraphBuilder<RenderPipelineFrame>) {
     return {
       texture: texture.value,
       view: view.value,
-      format: 'rgba16float' as const,
+      format,
       sampleCount: 1 as const,
     };
   };
@@ -199,12 +200,15 @@ function createImportedHistory(graph: RenderGraphBuilder<RenderPipelineFrame>) {
     previousColor: target('taa-history-previous-color'),
     currentTemporal: target('taa-history-current-temporal'),
     previousTemporal: target('taa-history-previous-temporal'),
+    currentStability: target('taa-history-current-stability', 'r8unorm'),
+    previousStability: target('taa-history-previous-stability', 'r8unorm'),
   };
 }
 
 describe('typed built-in pipeline topology', () => {
   it('defaults final output dither on and accepts an asset-level opt-out', () => {
     expect(resolveOutputDither(undefined)).toBe(true);
+    expect(resolveOutputDither({})).toBe(true);
     expect(resolveOutputDither({ outputDither: true })).toBe(true);
     expect(resolveOutputDither({ outputDither: false })).toBe(false);
   });
@@ -466,6 +470,14 @@ describe('typed built-in pipeline topology', () => {
       new URL('../render-graph-primitives.ts', import.meta.url),
       'utf8',
     );
+    const fxaaOwnerSource = readFileSync(
+      new URL('../record/skybox-post-pass.ts', import.meta.url),
+      'utf8',
+    );
+    const standardPostSource = readFileSync(
+      new URL('../pipeline/standard-post.ts', import.meta.url),
+      'utf8',
+    );
     expect(typedSource).toContain(
       'paramsOverride: options.paramsTransform(frame.postProcessParams.get(options.shader))',
     );
@@ -474,6 +486,28 @@ describe('typed built-in pipeline topology', () => {
       'const data = paramsOverride ?? ctx.postProcessParams.get(shader);',
     );
     expect(dispatcherSource).toContain('input.paramsOverride,');
+    expect(fxaaOwnerSource).toContain('paramsOverride?.byteLength === 16');
+    expect(fxaaOwnerSource).toContain(
+      'resolveOutputDither(c.frameState.installedPipelineConfig) ? 1 : 0',
+    );
+    expect(standardPostSource).toContain('paramsTransform: (): Uint8Array => new Uint8Array(16)');
+    expect(standardPostSource).toContain('dither: outputDither');
+  });
+
+  it('keeps the admitted LUT topology linear until the single encoding writer', () => {
+    const source = readFileSync(new URL('../pipeline/standard-post.ts', import.meta.url), 'utf8');
+    const tone = source.indexOf("name: 'standard-tone'");
+    const lut = source.indexOf("'standard-color-lut'");
+    const fxaa = source.indexOf("name: 'fxaa'");
+    const encoding = source.indexOf("name: 'standard-output-encoding'");
+    expect(tone).toBeGreaterThanOrEqual(0);
+    expect(lut).toBeGreaterThan(tone);
+    expect(fxaa).toBeGreaterThan(lut);
+    expect(encoding).toBeGreaterThan(fxaa);
+    expect(source).toContain("fragmentEntryPoint: 'fs_tone_only'");
+    expect(source).toContain("fragmentEntryPoint: 'fs_encode_only'");
+    expect(source).toContain("domain: 'linear-ldr'");
+    expect(source).toContain('{ dither: false }');
   });
 
   it('declares stable JSON-safe output and observation inspection facts', () => {
@@ -491,6 +525,7 @@ describe('typed built-in pipeline topology', () => {
     ]) {
       expect(source).toContain(field);
     }
+    expect(source).toContain('readonly output: RenderOutputInspection;');
     expect(source).not.toContain('pixelPayload');
   });
 
@@ -537,7 +572,7 @@ describe('typed built-in pipeline topology', () => {
       expect.arrayContaining([
         { resource: 'gbuffer-normal-roughness', usage: 'sampled-read' },
         { resource: 'gbuffer-albedo-metallic', usage: 'sampled-read' },
-        { resource: 'gbuffer-emissive-ao', usage: 'sampled-read' },
+        { resource: 'gbuffer-specular-response-ao', usage: 'sampled-read' },
         { resource: 'ssao-blurred', usage: 'sampled-read' },
         { resource: 'hdrp-scene-color', usage: 'color-attachment' },
       ]),
@@ -676,6 +711,76 @@ describe('typed built-in pipeline topology', () => {
     );
   });
 
+  it('feeds the SSR source-reactivity producer to final TAA without a second mask resource', () => {
+    const ssr = admitSsrSpatial({
+      camera: {
+        projection: 'perspective',
+        near: 0.1,
+        far: 100,
+        screenSpaceReflection: { maxDistance: 12, thickness: 0.2, maxRoughness: 0.65 },
+      },
+      environment: {
+        lane: 'deferred',
+        m0: { status: 'admitted' },
+        sceneInputs: true,
+        temporal: true,
+        reflectionFallback: true,
+        capabilities: {
+          compute: true,
+          storageTexture: true,
+          rgba16floatRenderable: true,
+          r32floatSampledStorage: true,
+        },
+      },
+    });
+    const compiled = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        standardProfile: { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred' },
+        camera: { tonemap: 'aces-filmic', antialias: 'taa', bloom: 'off' },
+        reflectionFallback: { enabled: true },
+        ssr,
+      }),
+    ).unwrap();
+    const info = compiled.inspect();
+    expect(info.resources.filter((r) => r.label === 'ssr-hit-reactivity')).toHaveLength(1);
+    expect(info.passes.find((p) => p.name === 'ssr-trace')?.accesses).toContainEqual({
+      resource: 'ssr-hit-reactivity',
+      usage: 'storage-write',
+    });
+    expect(info.passes.find((p) => p.name === 'taa-resolve')?.accesses).toContainEqual({
+      resource: 'ssr-hit-reactivity',
+      usage: 'sampled-read',
+    });
+    const names = info.passes.map((p) => p.name);
+    expect(names.indexOf('ssr-trace')).toBeLessThan(names.indexOf('taa-resolve'));
+  });
+
+  it('pairs post-TAA Motion Blur color with resolved temporal coverage', () => {
+    const compiled = compile(
+      standardPipeline,
+      topology('forgeax::standard', {
+        camera: { tonemap: 'aces-filmic', antialias: 'taa', bloom: 'off' },
+        temporal: { taa: true, motionBlur: true },
+      }),
+    );
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+    const accesses = compiled.value
+      .inspect()
+      .passes.find((pass) => pass.name === 'motion-blur')?.accesses;
+    expect(accesses).toEqual(
+      expect.arrayContaining([
+        { resource: 'taa-history-current-color', usage: 'sampled-read' },
+        { resource: 'taa-history-current-temporal', usage: 'sampled-read' },
+      ]),
+    );
+    expect(accesses).not.toContainEqual({
+      resource: 'standard-scene-temporal',
+      usage: 'sampled-read',
+    });
+  });
+
   it('fails closed when TAA history imports are missing', () => {
     const graph = new RenderGraphBuilder<RenderPipelineFrame>();
     const standardLighting = zeroStandardLighting({ compute: true, storageBuffer: true });

package/src/__tests__/typed-scene-pass-material-cache.integration.test.ts

@@ -0,0 +1,126 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import type { PassSelector } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import { createRenderPipelineTarget } from '../render-pipeline';
+
+const { encodeMainPass, buildPerFrameBindGroups } = vi.hoisted(() => ({
+  encodeMainPass: vi.fn(),
+  buildPerFrameBindGroups: vi.fn(),
+}));
+
+vi.mock('../record/main-pass', () => ({ encodeMainPass }));
+vi.mock('../record/frame-lighting', () => ({ buildPerFrameBindGroups }));
+
+import { addTypedScenePass } from '../typed-render-graph-primitives';
+
+function targetDescriptor(format: 'rgba8unorm' | 'depth24plus-stencil8') {
+  return { format, size: { width: 1, height: 1 } };
+}
+
+function frameFor(device: RhiDevice, materialSlots: readonly object[]): RenderPipelineFrame {
+  return {
+    encoder: device.createCommandEncoder({ label: 'material-cache-test' }).unwrap(),
+    runtime: {
+      device,
+      errorRegistry: { fire: vi.fn() },
+    },
+    frameState: {},
+    pipelineState: { colorAttachmentFormat: 'rgba8unorm' },
+    validated: [],
+    validatedOrdered: [],
+    materialSlots,
+    materialSlotCount: materialSlots.length,
+    bindGroupCounts: {},
+  } as unknown as RenderPipelineFrame;
+}
+
+describe('typed scene pass material payload cache', () => {
+  it('reuses one frame owner cache across scene passes and refreshes on a new frame', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    buildPerFrameBindGroups.mockReturnValue({
+      viewBindGroup: null,
+      meshBindGroup: null,
+      hdrpClusterBindGroup: null,
+      hdrpClusterMembershipBindGroup: null,
+    });
+
+    const materialA = [{ id: 'A' }];
+    const materialB = [{ id: 'B' }];
+    const payloadA = new Uint8Array([1]);
+    const payloadB = new Uint8Array([2]);
+    const seenCacheInputs: Array<unknown> = [];
+    encodeMainPass.mockImplementation(
+      (
+        context: {
+          materialSlots: readonly object[];
+          materialSlotCount: number;
+          materialUboPayloadCache?: {
+            materialSlots: readonly object[];
+            materialSlotCount: number;
+            payload: Uint8Array;
+          };
+        },
+        _pass: { end(): void },
+      ) => {
+        seenCacheInputs.push(context.materialUboPayloadCache);
+        const payload = context.materialSlots === materialA ? payloadA : payloadB;
+        if (
+          context.materialUboPayloadCache?.materialSlots !== context.materialSlots ||
+          context.materialUboPayloadCache?.materialSlotCount !== context.materialSlotCount
+        ) {
+          context.materialUboPayloadCache = {
+            materialSlots: context.materialSlots,
+            materialSlotCount: context.materialSlotCount,
+            payload,
+          };
+        }
+      },
+    );
+
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    const color = createRenderPipelineTarget(
+      graph,
+      'material-cache-color',
+      targetDescriptor('rgba8unorm'),
+    ).unwrap();
+    const depth = createRenderPipelineTarget(
+      graph,
+      'material-cache-depth',
+      targetDescriptor('depth24plus-stencil8'),
+    ).unwrap();
+    const options = {
+      name: 'material-cache-scene',
+      color,
+      depth,
+      selector: {} as PassSelector,
+    };
+    expect(addTypedScenePass(graph, options).ok).toBe(true);
+    expect(addTypedScenePass(graph, { ...options, name: 'material-cache-scene-2' }).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+
+    const firstFrame = frameFor(device, materialA);
+    const firstExecution = compiled.execute(firstFrame);
+    expect(firstExecution.ok).toBe(true);
+    expect(encodeMainPass).toHaveBeenCalledTimes(2);
+    expect(seenCacheInputs).toEqual([undefined, expect.objectContaining({ payload: payloadA })]);
+    const firstCache = (firstFrame as unknown as { materialUboPayloadCache?: unknown })
+      .materialUboPayloadCache;
+    expect(seenCacheInputs[1]).toBe(firstCache);
+    expect((firstCache as { payload: Uint8Array }).payload).toBe(payloadA);
+
+    encodeMainPass.mockClear();
+    seenCacheInputs.length = 0;
+    const nextFrame = frameFor(device, materialB);
+    const nextExecution = compiled.execute(nextFrame);
+    expect(nextExecution.ok).toBe(true);
+    expect(seenCacheInputs).toEqual([undefined, expect.objectContaining({ payload: payloadB })]);
+    const nextCache = (nextFrame as unknown as { materialUboPayloadCache?: unknown })
+      .materialUboPayloadCache;
+    expect(seenCacheInputs[1]).toBe(nextCache);
+    expect((nextCache as { payload: Uint8Array }).payload).toBe(payloadB);
+  });
+});

package/src/__tests__/vertex-layouts-ssot.unit.test.ts

@@ -0,0 +1,47 @@
+import { DEFAULT_VERTEX_ATTRIBUTE_MAP, deriveVertexBufferLayout } from '@forgeax/engine-geometry';
+import { describe, expect, it } from 'vitest';
+import {
+  BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS,
+  MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS,
+  POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS,
+  TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS,
+  toGpuVertexBufferLayouts,
+} from '../assembly/webgpu-vertex-layouts';
+
+const FLOAT32_COMPONENT_COUNT = {
+  float32x2: 2,
+  float32x3: 3,
+  float32x4: 4,
+} as const;
+
+describe('prepared feature vertex layout SSOT', () => {
+  it('derives the mesh vertex stream from geometry layout ownership', () => {
+    const [expected] = toGpuVertexBufferLayouts(
+      deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP),
+    );
+    const [actual] = MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS;
+
+    expect(actual).toEqual({ ...expected, stepMode: 'vertex' });
+  });
+
+  it.each([
+    ['position-size-color', POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS],
+    ['billboard-material', BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS],
+    ['topology-segment', TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS],
+    ['mesh-material-instance', [MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS[1]]],
+  ] as const)('%s derives stride from its declared attributes', (_name, buffers) => {
+    for (const buffer of buffers) {
+      if (buffer === undefined) {
+        throw new Error('vertex layout fixture is missing its buffer declaration');
+      }
+      const end = Math.max(
+        ...buffer.attributes.map(
+          (attribute) =>
+            attribute.offset +
+            FLOAT32_COMPONENT_COUNT[attribute.format as keyof typeof FLOAT32_COMPONENT_COUNT] * 4,
+        ),
+      );
+      expect(buffer.arrayStride).toBe(end);
+    }
+  });
+});

package/src/__tests__/visibility-extract.perf.test.ts

@@ -11,6 +11,12 @@ import { RenderScene } from '../scene/render-scene';
 
 const ENTITY_COUNT = 10_000;
 const SAMPLE_COUNT = 101;
+const LIGHTWEIGHT_RENDER_SCENE_PERF = process.env.FORGEAX_RENDER_PERF_LIGHTWEIGHT === '1';
+// The full 100k scene remains the local/nightly scaling check.  CI keeps the
+// same delta/no-change assertions at a bounded 10k population so a standard
+// runner does not spend its memory budget constructing a second large graph.
+const RENDER_SCENE_ENTITY_COUNT = LIGHTWEIGHT_RENDER_SCENE_PERF ? 10_000 : 100_000;
+const RENDER_SCENE_DELTA_COUNT = LIGHTWEIGHT_RENDER_SCENE_PERF ? 1_000 : 10_000;
 
 const sceneMaterial = {} as MaterialSnapshot;
 
@@ -88,7 +94,7 @@ function measureWorlds(worlds: readonly World[]): number[] {
   return measureWorldSamples(worlds).map((values) => median(values));
 }
 
-describe('visibility extraction performance (10k)', () => {
+describe(`visibility extraction performance (10k + RenderScene ${RENDER_SCENE_ENTITY_COUNT / 1_000}k)`, () => {
   it('keeps inherited hierarchy extraction within the 10 percent budget', () => {
     const flat = buildWorld(false, false);
     const hierarchy = buildWorld(false, true);
@@ -104,27 +110,33 @@ describe('visibility extraction performance (10k)', () => {
     expect(overhead).toBeLessThanOrEqual(0.1);
   }, 60_000);
 
-  it('keeps RenderScene delta and no-change evidence on the 100k workload', () => {
+  it(`keeps RenderScene delta and no-change evidence on the ${RENDER_SCENE_ENTITY_COUNT / 1_000}k workload`, () => {
     const scene = new RenderScene();
-    scene.reset(Array.from({ length: 100_000 }, (_, entityKey) => sceneSnapshot(entityKey)));
+    scene.reset(
+      Array.from({ length: RENDER_SCENE_ENTITY_COUNT }, (_, entityKey) => sceneSnapshot(entityKey)),
+    );
     const stable = scene.materialize();
     const noChange = scene.apply([]);
     const delta = scene.apply(
-      Array.from({ length: 10_000 }, (_, entityKey) => {
+      Array.from({ length: RENDER_SCENE_DELTA_COUNT }, (_, entityKey) => {
         const previous = stable[entityKey];
         const world =
           previous === undefined
             ? new Float32Array(16)
             : new Float32Array(previous.transform.world);
         world[12] = (world[12] ?? 0) + 1;
-        return { kind: 'update-transform' as const, worldId: 0, entityKey, world };
+        return { kind: 'update' as const, worldId: 0, entityKey, world };
       }),
     );
 
     expect(noChange).toMatchObject({ updated: 0, resynced: 0 });
-    expect(delta).toMatchObject({ updated: 10_000, resynced: 0 });
-    expect(scene.inspect()).toMatchObject({ renderableScans: 10_000 });
-    expect(scene.materialize()).not.toBe(stable);
+    expect(delta).toMatchObject({ updated: RENDER_SCENE_DELTA_COUNT, resynced: 0 });
+    expect(scene.inspect()).toMatchObject({ renderableScans: RENDER_SCENE_DELTA_COUNT });
+    // Transform-only updates patch the retained snapshot in place so the
+    // unified scene flow does not allocate a second large publication.
+    expect(scene.materialize()).toBe(stable);
+    expect(stable[0]?.transform.world[12]).toBe(1);
+    expect(stable[RENDER_SCENE_DELTA_COUNT - 1]?.transform.world[12]).toBe(1_000);
     expect(scene.querySpatial({ min: [-1, -1, -1], max: [1, 1, 1] }).length).toBeGreaterThan(0);
   }, 60_000);
 });

package/src/__tests__/visibility-instances.integration.test.ts

@@ -6,17 +6,23 @@ import { Instances } from '../components/instances';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { InstanceCollectionStore } from '../instances';
 import { extractFrames } from '../render-system-extract';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
-function spawnInstance(world: World, state: keyof typeof VisibilityStateValue) {
+function spawnInstance(
+  world: World,
+  instanceCollections: InstanceCollectionStore,
+  state: keyof typeof VisibilityStateValue,
+) {
+  const collectionId = instanceCollections.create({ transforms: IDENTITY }).unwrap().collectionId;
   return world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { transforms: new Float32Array(IDENTITY) } },
+      { component: Instances, data: { collectionId } },
       { component: Visibility, data: { state: VisibilityStateValue[state] } },
     )
     .unwrap();
@@ -25,9 +31,12 @@ function spawnInstance(world: World, state: keyof typeof VisibilityStateValue) {
 describe('visibility instance producer gate', () => {
   it('gates an explicit Instances owner before producing a renderable', () => {
     const world = new World();
-    const entity = spawnInstance(world, 'hidden');
+    const instanceCollections = new InstanceCollectionStore();
+    const entity = spawnInstance(world, instanceCollections, 'hidden');
 
-    const frame = extractFrames([world], 0);
+    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
+      instanceCollections,
+    });
 
     expect(frame.renderables.some((item) => item.entityKey === entity)).toBe(false);
     expect(frame.dispatch.some((item) => item.entityIndex === 0)).toBe(false);
@@ -35,10 +44,13 @@ describe('visibility instance producer gate', () => {
 
   it('keeps visible members of a mixed batch independent from hidden members', () => {
     const world = new World();
-    spawnInstance(world, 'hidden');
-    const visible = spawnInstance(world, 'visible');
+    const instanceCollections = new InstanceCollectionStore();
+    spawnInstance(world, instanceCollections, 'hidden');
+    const visible = spawnInstance(world, instanceCollections, 'visible');
 
-    const frame = extractFrames([world], 0);
+    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
+      instanceCollections,
+    });
 
     expect(frame.renderables.map((item) => item.entityKey)).toEqual([visible]);
     expect(frame.dispatch.length).toBe(2);

package/src/__tests__/visibility-producer-matrix.integration.test.ts

@@ -11,6 +11,7 @@ import { SpriteInstances } from '../components/sprite-instances';
 import { TileLayer } from '../components/tile-layer';
 import { Tilemap } from '../components/tilemap';
 import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { InstanceCollectionStore } from '../instances';
 import { extractFrames } from '../render-system-extract';
 import { classifySceneDataCoverage } from '../temporal/coverage';
 import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
@@ -19,7 +20,7 @@ const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0,
 
 type ProducerCase = {
   readonly name: string;
-  readonly setup: (world: World) => EntityHandle;
+  readonly setup: (world: World, instanceCollections: InstanceCollectionStore) => EntityHandle;
 };
 
 function staticMesh(world: World): EntityHandle {
@@ -60,25 +61,33 @@ function spriteMesh(world: World): EntityHandle {
     .unwrap();
 }
 
-function autoFoldInstances(world: World): EntityHandle {
+function autoFoldInstances(
+  world: World,
+  instanceCollections: InstanceCollectionStore,
+): EntityHandle {
+  const collectionId = instanceCollections.create({ transforms: IDENTITY }).unwrap().collectionId;
   return world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { transforms: IDENTITY } },
+      { component: Instances, data: { collectionId } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
     .unwrap();
 }
 
-function explicitInstances(world: World): EntityHandle {
+function explicitInstances(
+  world: World,
+  instanceCollections: InstanceCollectionStore,
+): EntityHandle {
+  const collectionId = instanceCollections.create({ transforms: IDENTITY }).unwrap().collectionId;
   return world
     .spawn(
       { component: Transform, data: {} },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { transforms: IDENTITY } },
+      { component: Instances, data: { collectionId } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
     .unwrap();
@@ -132,18 +141,20 @@ describe('visibility built-in producer matrix', () => {
 
   it.each(PRODUCERS)('$name is hidden, visible, then restorable', ({ setup }) => {
     const world = new World();
-    const entity = setup(world);
+    const instanceCollections = new InstanceCollectionStore();
+    const entity = setup(world, instanceCollections);
 
-    const hidden = extractFrames([world], 0);
+    const options = { instanceCollections };
+    const hidden = extractFrames([world], 0, undefined, undefined, undefined, options);
     expect(hidden.renderables).toHaveLength(0);
     expect(hidden.dispatch).toHaveLength(0);
 
     world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
-    const visible = extractFrames([world], 0);
+    const visible = extractFrames([world], 0, undefined, undefined, undefined, options);
     expect(visible.visibilitySnapshots[0]?.get(entity)?.effective).toBe('visible');
 
     world.set(entity, Visibility, { state: VisibilityStateValue.hidden }).unwrap();
-    const restored = extractFrames([world], 0);
+    const restored = extractFrames([world], 0, undefined, undefined, undefined, options);
     expect(restored.renderables).toHaveLength(0);
     expect(restored.dispatch).toHaveLength(0);
   });

package/src/assembly/atmosphere-shader-prewarm.ts

@@ -0,0 +1,38 @@
+import { RhiError, type ShaderModule } from '@forgeax/engine-rhi';
+import type { ManifestEntry } from '@forgeax/engine-types';
+import type { AtmosphereShaderSources } from '../render-contract';
+
+/** Admit and compile the complete analytic-atmosphere shader pair atomically. */
+export async function prewarmAtmosphereShaders(
+  entries: readonly ManifestEntry[],
+  compile: (label: string, source: string) => Promise<ShaderModule>,
+  seed: (label: string, module: ShaderModule) => void,
+): Promise<AtmosphereShaderSources | undefined> {
+  const stages = [
+    ['cube', 'atmosphere_cube', 'atmosphere_cubemap_vs'],
+    ['background', 'atmosphere_background', 'atmosphere_background_vs'],
+  ] as const;
+  const resolved = stages.map(([stage, label, entryPoint]) => ({
+    stage,
+    label,
+    entry: entries.find((entry) => entry.wgsl.includes(`fn ${entryPoint}(`)),
+  }));
+  if (resolved.every(({ entry }) => entry === undefined)) return undefined;
+  const missing = resolved.find(({ entry }) => entry === undefined);
+  if (missing !== undefined) {
+    throw new RhiError({
+      code: 'shader-compile-failed',
+      expected: 'shader manifest contains both analytic-atmosphere utility entries',
+      hint: `add the package-owned WGSL entry for '${missing.label}' to the engine shader manifest`,
+    });
+  }
+  const compiled: Array<{ label: string; module: ShaderModule }> = [];
+  const sources = {} as Record<keyof AtmosphereShaderSources, string>;
+  for (const { stage, label, entry } of resolved) {
+    if (entry === undefined) throw new Error(`missing atmosphere shader ${label}`);
+    compiled.push({ label, module: await compile(label, entry.wgsl) });
+    sources[stage] = entry.wgsl;
+  }
+  for (const { label, module } of compiled) seed(label, module);
+  return sources;
+}