@forgeax/engine-render 0.1.35 → 0.1.36

package/src/__tests__/device-scope-lifecycle.unit.test.ts

@@ -188,3 +188,29 @@ describe('DeviceScope lifecycle transaction', () => {
     expect(cleanupCount).toBe(1);
   });
 });
+
+it('detaches terminal child scopes while retaining pending ownership', () => {
+  const parent = DeviceScope.create(1, 'renderer');
+  const pending = parent.createChild('pending');
+  let cleaned = 0;
+  pending._adopt('buffer', {}, () => {
+    cleaned += 1;
+  });
+  pending.beginRetire();
+  for (let index = 0; index < 300; index += 1) {
+    for (const action of ['retire', 'abandon', 'dispose'] as const) {
+      const child = parent.createChild(action);
+      child._adopt('buffer', {}, () => {
+        cleaned += 1;
+      });
+      child[action]();
+      child[action]();
+    }
+  }
+  expect(parent.childrenSnapshot).toEqual([pending]);
+  expect(cleaned).toBe(900);
+  pending.retire();
+  expect(parent.childrenSnapshot).toEqual([]);
+  parent.dispose();
+  expect(cleaned).toBe(901);
+});

package/src/__tests__/gpu-driven-production.integration.test.ts

@@ -1,7 +1,7 @@
 import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
-import { vec3 } from '@forgeax/engine-math';
+import { frustum, mat4, vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import {
   type BindGroup,
@@ -2426,6 +2426,23 @@ describe('GPU-driven production projection', () => {
     expect(authored?.[2]).toEqual({ cullMode: 'none', frontFace: 'cw' });
     expect(authored?.[15]).toBe(skinned ? 'pbr-skin' : 'pbr');
     if (skinned) expect(authored?.[5]).toContain('SKINNING_DISABLED=false');
+
+    sourceForRecord.transform.world[12] = 100;
+    indexedDraws.length = 0;
+    const culled = recordShadowCasterDraws(
+      context,
+      pass,
+      {} as never,
+      {} as never,
+      new Set([0]),
+      new Map([[0, new Set([20, 21, 22])]]),
+      shadowDispatches,
+      new Set([claimedKey]),
+      false,
+      frustum.fromViewProjection(frustum.create(), mat4.identity(mat4.create())),
+    );
+    expect(indexedDraws).toHaveLength(skinned ? 3 : 0);
+    expect(culled).toEqual(skinned ? residualKeys : new Set());
   });
 
   it('fails closed at every shadow front door when expected casters lack bind groups', () => {

package/src/__tests__/gpu-driven-shadow-views.unit.test.ts

@@ -13,6 +13,7 @@ import { RenderScene } from '../scene/render-scene';
 
 const shadowViewsPath = new URL('../gpu-driven/shadow-views.ts', import.meta.url);
 const shadowViewsSource = existsSync(shadowViewsPath) ? readFileSync(shadowViewsPath, 'utf8') : '';
+const recordFrameSource = readFileSync(new URL('../record/frame.ts', import.meta.url), 'utf8');
 const viewSource = readFileSync(new URL('../gpu-driven/view-gpu.ts', import.meta.url), 'utf8');
 
 const shadowKinds = [
@@ -83,6 +84,23 @@ describe('GPU-driven shadow view owner contract', () => {
     expect(viewSource).toMatch(/labelPrefix|viewPrefix|viewId/);
   });
 
+  it('fences shadow view cache identity at accepted graph generations', () => {
+    const cacheTokens = [
+      ...recordFrameSource.matchAll(/cacheToken:\s*shadowViewToken\(([^)]*)\)/g),
+    ].map(([, argumentsSource]) => argumentsSource ?? '');
+
+    expect(cacheTokens).toHaveLength(3);
+    expect(
+      cacheTokens.every((argumentsSource) => argumentsSource.includes('graphShadowMapSize')),
+    ).toBe(true);
+    expect(
+      cacheTokens.every((argumentsSource) =>
+        argumentsSource.includes('frameState.graphGeneration'),
+      ),
+    ).toBe(true);
+    expect(recordFrameSource).toMatch(/shadowViewToken[\s\S]*graphGeneration/);
+  });
+
   it('reuses each view on a cache hit and invalidates only that view', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
@@ -140,6 +158,11 @@ describe('GPU-driven shadow view owner contract', () => {
           .inspect().passes,
       ).toHaveLength(0);
 
+      const replacementGraph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+      const forced = pool.project(replacementGraph, identity, true).unwrap();
+      expect(forced.cache).toBe('hit');
+      expect(forced.passNames.length).toBeGreaterThan(0);
+
       const changedMaterial = {
         ...material,
         baseColor: new Float32Array([0.25, 1, 1]),

package/src/__tests__/material-vertex-texture.browser.test.ts

@@ -0,0 +1,7 @@
+import { it } from 'vitest';
+import { verifyMaterialVertexTexture } from './material-vertex-texture.fixture';
+
+it(
+  'admits explicit-LOD vertex sampling in the native material user layout',
+  verifyMaterialVertexTexture,
+);

package/src/__tests__/material-vertex-texture.dawn.test.ts

@@ -0,0 +1,7 @@
+import { it } from 'vitest';
+import { verifyMaterialVertexTexture } from './material-vertex-texture.fixture';
+
+it(
+  'admits explicit-LOD vertex sampling in the native material user layout',
+  verifyMaterialVertexTexture,
+);

package/src/__tests__/material-vertex-texture.fixture.ts

@@ -0,0 +1,31 @@
+import { expect } from 'vitest';
+import { appendInjection, buildPbrMaterialUserRegionEntries } from '../pbr-pipeline';
+
+export async function verifyMaterialVertexTexture(): Promise<void> {
+  const adapter = await navigator.gpu.requestAdapter();
+  if (!adapter) throw new Error('WebGPU adapter unavailable');
+  const device = await adapter.requestDevice();
+  try {
+    const entries = buildPbrMaterialUserRegionEntries([
+      { name: 'displacement', type: 'texture2d' },
+    ]);
+    for (const entry of appendInjection(entries, 'ibl')) expect(entry.visibility).toBe(2);
+    device.pushErrorScope('validation');
+    const module = device.createShaderModule({
+      code: `@group(0) @binding(1) var s: sampler;
+@group(0) @binding(2) var t: texture_2d<f32>;
+@vertex fn vs() -> @builtin(position) vec4<f32> { return vec4<f32>(textureSampleLevel(t,s,vec2<f32>(0.5),0.0).xyz,1.0); }
+@fragment fn fs() -> @location(0) vec4<f32> { return vec4<f32>(1.0); }`,
+    });
+    device.createRenderPipeline({
+      layout: device.createPipelineLayout({
+        bindGroupLayouts: [device.createBindGroupLayout({ entries })],
+      }),
+      vertex: { module, entryPoint: 'vs' },
+      fragment: { module, entryPoint: 'fs', targets: [{ format: 'rgba8unorm' }] },
+    });
+    expect(await device.popErrorScope()).toBeNull();
+  } finally {
+    device.destroy();
+  }
+}

package/src/__tests__/recovery-candidate-prepare.contract.test.ts

@@ -139,6 +139,11 @@ describe('recovery candidate preparation contract', () => {
     expect(rendererSource).not.toMatch(/\n\s*materialShaderPipelineCache\.(get|set|has)\(/);
   });
 
+  it('forks the validated shader catalog onto a recovery device', () => {
+    expect(rendererSource).toContain('activeCatalog.forkForDevice(getShaderModuleAdapter())');
+    expect(rendererSource).toContain('state === candidateShaderState && activeCatalog !== null');
+  });
+
   it('resolves recovery variants from the candidate device capabilities', () => {
     const start = rendererSource.indexOf('const resolveCachedMaterialShaderVariantSet');
     const end = rendererSource.indexOf('const findMaterialShaderManifestEntry', start);

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -1,10 +1,14 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { type RhiDevice, RhiError } from '@forgeax/engine-rhi';
-import type {
-  MaterialShaderManifestEntry,
-  MaterialShaderManifestVariant,
-  ShaderCatalog,
+import {
+  createMaterialProgramArtifactReceipt,
+  type MaterialShaderManifestEntry,
+  type MaterialShaderManifestVariant,
+  type ShaderCatalog,
+  ShaderRegistry,
+  type ShaderRegistryDevice,
 } from '@forgeax/engine-shader';
 import { describe, expect, it, vi } from 'vitest';
 import { deviceOptionsForAdapter } from '../assembly/device-feature-admission';
@@ -128,6 +132,104 @@ fn cloud_direct_solar_factorX() -> f32 {
     });
   });
 
+  it('selects the replacement device capability variant after a metadata-only fork', async () => {
+    const uniformReceipt = createMaterialProgramArtifactReceipt({
+      schema: [],
+      directEntry: 'vs_uniform',
+      sceneIndexEntry: 'vs_scene_uniform',
+      vertexInputs: [],
+      layoutIdentity: 'uniform',
+    });
+    const storageReceipt = createMaterialProgramArtifactReceipt({
+      schema: [],
+      directEntry: 'vs_storage',
+      sceneIndexEntry: 'vs_scene_storage',
+      vertexInputs: [],
+      layoutIdentity: 'storage',
+    });
+    const entry: MaterialShaderManifestEntry = {
+      identifier: 'game::variant',
+      sourcePath: 'variant.wgsl',
+      composedWgsl: 'fallback',
+      paramSchema: '[]',
+      uvSetCount: 3,
+      variants: [
+        {
+          definesKey: 'STORAGE_BUFFER_AVAILABLE=false',
+          defines: { STORAGE_BUFFER_AVAILABLE: false },
+          composedWgsl: 'uniform-variant',
+          receipt: uniformReceipt,
+        },
+        {
+          definesKey: '',
+          defines: { STORAGE_BUFFER_AVAILABLE: true },
+          composedWgsl: 'storage-variant',
+          receipt: storageReceipt,
+        },
+      ],
+    };
+    const manifestUrl = URL.createObjectURL(
+      new Blob([JSON.stringify({ entries: [], materialShaders: [entry] })]),
+    );
+    const registryDevice = (): ShaderRegistryDevice => ({
+      createShaderModule: () => ({ ok: true, value: {} as never }),
+    });
+    const device = (storageBuffer: boolean): RhiDevice =>
+      ({
+        caps: {
+          backendKind: 'webgpu',
+          storageBuffer,
+          rgba16floatRenderable: true,
+          samplerAliasing: true,
+        },
+        limits: {
+          maxStorageBuffersPerShaderStage: storageBuffer ? 8 : 0,
+          maxSampledTexturesPerShaderStage: 32,
+          maxTextureArrayLayers: 64,
+          maxUniformBuffersPerShaderStage: 4,
+        },
+      }) as unknown as RhiDevice;
+
+    try {
+      const active = new ShaderRegistry({ device: registryDevice(), manifestUrl });
+      const activeAssets = new AssetRegistry(active);
+      await prepareMaterialShaders(device(false), () => active, activeAssets, new Map());
+      active.installMaterialArtifact('game::custom', {
+        source: 'custom-variant',
+        paramSchema: [],
+        receipt: uniformReceipt,
+      });
+      const activeArtifact = active.findMaterialArtifact('game::variant');
+      expect(activeArtifact.ok).toBe(true);
+      if (!activeArtifact.ok) return;
+      expect(activeArtifact.value.source).toBe('uniform-variant');
+      expect(activeArtifact.value.receipt).toEqual(uniformReceipt);
+
+      URL.revokeObjectURL(manifestUrl);
+      const candidate = active.forkForDevice(registryDevice());
+      const candidateAssets = new AssetRegistry(candidate);
+      const uvSetCounts = new Map<string, number>();
+      await prepareMaterialShaders(device(true), () => candidate, candidateAssets, uvSetCounts);
+      const candidateArtifact = candidate.findMaterialArtifact('game::variant');
+      expect(candidateArtifact.ok).toBe(true);
+      if (!candidateArtifact.ok) return;
+      expect(candidateArtifact.value.source).toBe('storage-variant');
+      expect(candidateArtifact.value.receipt).toEqual(storageReceipt);
+      expect(uvSetCounts.get('game::variant')).toBe(3);
+      expect(candidate.findMaterialArtifact('game::custom').ok).toBe(false);
+
+      const customArtifact = active.findMaterialArtifact('game::custom');
+      expect(customArtifact.ok).toBe(true);
+      if (!customArtifact.ok) return;
+      candidate.installMaterialArtifact('game::custom', customArtifact.value);
+      const candidateCustom = candidate.findMaterialArtifact('game::custom');
+      expect(candidateCustom.ok && candidateCustom.value.source).toBe('custom-variant');
+      expect(activeArtifact.value.source).toBe('uniform-variant');
+    } finally {
+      URL.revokeObjectURL(manifestUrl);
+    }
+  });
+
   it('requests the extended-lighting sampled-texture limit when the adapter supports it', () => {
     const features = new Set<GPUFeatureName>();
     expect(

package/src/__tests__/runtime-material-program.integration.test.ts

@@ -0,0 +1,79 @@
+import { AssetRegistry, HANDLE_CUBE, RuntimeMaterialValue } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { expect, it } from 'vitest';
+import {
+  MATERIAL_CONTEXT,
+  materialRecordFixture,
+} from '../../../assets-runtime/src/__tests__/fixtures/material-publication';
+import { MeshFilter, MeshRenderer } from '../components';
+import { extractFrames, resolveMaterialSnapshot } from '../render-system-extract';
+
+it('keeps cooked Forward and ShadowCaster programs when World values change or a catalogue entry is replaced', () => {
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  const world = new World();
+  const record = materialRecordFixture({
+    parameters: [{ name: 'roughness', type: 'f32' }],
+    values: { roughness: 0.8 },
+    passes: [
+      { name: 'Forward', program: { module: 'game::material' } },
+      { name: 'ShadowCaster', program: { module: 'game::shadow' } },
+    ],
+  });
+  const base: MaterialAsset = { kind: 'material', ...record.resolved };
+  assets.catalog(record.guid, base).unwrap();
+  if (!record.sourceClosure || !record.parameterContract)
+    throw new Error('Missing cooked metadata');
+  assets.recordMaterialReadiness(record.guid, {
+    status: 'Ready',
+    guid: record.guid,
+    materialGuid: record.guid,
+    publicationGeneration: record.publicationGeneration,
+    specializationKey: record.specializationKey,
+    artifactDigest: record.artifactDigest,
+    sourceClosure: record.sourceClosure,
+    parameterContract: record.parameterContract,
+    record,
+    programs: record.programs,
+  });
+  const handle = world.internSharedRef('MaterialAsset', base);
+  world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [handle] } },
+    )
+    .unwrap();
+  world.update(0).unwrap();
+  const frameRead = () =>
+    extractFrames([world], 0, assets, undefined, undefined, {
+      materialContext: MATERIAL_CONTEXT,
+      cull: 'none',
+    }).renderables[0]?.materials[0];
+  const read = () =>
+    resolveMaterialSnapshot(handle, world, assets, undefined, undefined, MATERIAL_CONTEXT);
+  const before = read();
+  expect(frameRead()?.materialProgramKeys).toEqual(before.materialProgramKeys);
+  expect(Object.keys(before.materialProgramKeys ?? {})).toEqual(['Forward', 'ShadowCaster']);
+  const content = world
+    .spawn({
+      component: RuntimeMaterialValue,
+      data: {
+        asset: handle,
+        parameter: 'roughness',
+        kind: 0,
+        value: [0.25],
+      },
+    })
+    .unwrap();
+  expect(read().roughness).toBe(0.25);
+  expect(frameRead()?.materialProgramKeys).toEqual(before.materialProgramKeys);
+  expect(read().materialProgramKeys).toEqual(before.materialProgramKeys);
+  assets.catalog(record.guid, { ...base, values: { roughness: 0.6 } }).unwrap();
+  expect(read().materialProgramKeys).toEqual(before.materialProgramKeys);
+  world.despawn(content).unwrap();
+  expect(read().roughness).toBeCloseTo(0.8);
+  expect(read().materialProgramKeys).toEqual(before.materialProgramKeys);
+});

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

@@ -1,4 +1,4 @@
-import { DEFAULT_VERTEX_ATTRIBUTE_MAP, deriveVertexBufferLayout } from '@forgeax/engine-geometry';
+import { deriveVertexBufferLayout } from '@forgeax/engine-geometry';
 import { describe, expect, it } from 'vitest';
 import {
   BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS,
@@ -17,11 +17,31 @@ const FLOAT32_COMPONENT_COUNT = {
 describe('prepared feature vertex layout SSOT', () => {
   it('derives the mesh vertex stream from geometry layout ownership', () => {
     const [expected] = toGpuVertexBufferLayouts(
-      deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP),
+      deriveVertexBufferLayout({
+        position: new Float32Array(),
+        normal: new Float32Array(),
+        uv: new Float32Array(),
+        tangent: new Float32Array(),
+        uv1: new Float32Array(),
+        color: new Float32Array(),
+      }),
     );
     const [actual] = MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS;
 
-    expect(actual).toEqual({ ...expected, stepMode: 'vertex' });
+    if (expected === undefined) throw new Error('Missing geometry descriptor');
+    expect(actual).toEqual({
+      ...expected,
+      stepMode: 'vertex',
+      attributes: expected.attributes.map((attribute) => ({
+        ...attribute,
+        shaderLocation:
+          attribute.shaderLocation === 6
+            ? 15
+            : attribute.shaderLocation === 13
+              ? 14
+              : attribute.shaderLocation,
+      })),
+    });
   });
 
   it.each([

package/src/assembly/webgpu-renderer.ts

@@ -570,6 +570,8 @@ async function makeWebGPURenderer(
   const getShader = (): ShaderCatalog => {
     const state = candidateShaderState ?? activeShaderState;
     if (state.shaderInstance === null) {
+      const activeCatalog = activeShaderState.shaderInstance;
+      // Reuse validated manifest CPU rows; candidate preparation selects variants.
       // feat-20260608-create-app-param-surface-trim / M2 / D-2 q5-A:
       // shaderManifestUrl moved to BundlerOptions (third arg). The fallback
       // literal '/shaders/manifest.json' stays here so the LO 1.1
@@ -578,15 +580,16 @@ async function makeWebGPURenderer(
       // the zero-entry opt-in: explicitly passing
       // `bundler: { shaderManifestUrl: undefined }` retains the
       // old "no manifest fetched" mode used by tests / camera-only worlds.
-      const bundler = internals.bundler;
-      const explicitUrl = bundler?.shaderManifestUrl;
-      state.shaderInstance = new ShaderCatalog({
-        device: getShaderModuleAdapter(),
-        manifestUrl:
-          bundler !== undefined && 'shaderManifestUrl' in bundler
-            ? explicitUrl
-            : '/shaders/manifest.json',
-      });
+      state.shaderInstance =
+        state === candidateShaderState && activeCatalog !== null
+          ? activeCatalog.forkForDevice(getShaderModuleAdapter())
+          : new ShaderCatalog({
+              device: getShaderModuleAdapter(),
+              manifestUrl:
+                internals.bundler !== undefined && 'shaderManifestUrl' in internals.bundler
+                  ? internals.bundler.shaderManifestUrl
+                  : '/shaders/manifest.json',
+            });
     }
     return state.shaderInstance;
   };

package/src/assembly/webgpu-vertex-layouts.ts

@@ -8,6 +8,7 @@ import {
   type VertexLayoutProjection,
 } from '@forgeax/engine-geometry';
 import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { PARTICLE_MESH_VERTEX_BUFFER } from '../features/particle-mesh-layout';
 import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 
 type FeatureFloatVertexFormat = 'float32x2' | 'float32x3' | 'float32x4';
@@ -101,14 +102,6 @@ const MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC = {
 export const PREPARED_INSTANCE_VERTEX_ATTRS = buildMeshAttributeMapForUvSets(2);
 export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS = SKIN_VERTEX_ATTRIBUTE_MAP;
 
-function canonicalMeshVertexBufferLayout(): GPUVertexBufferLayout {
-  const [buffer] = toGpuVertexBufferLayouts(deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP));
-  if (buffer === undefined) {
-    throw new Error('The canonical mesh vertex layout must contain one vertex buffer');
-  }
-  return { ...buffer, stepMode: 'vertex' };
-}
-
 export const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
   defineFeatureVertexBuffer(POSITION_SIZE_COLOR_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
@@ -127,7 +120,7 @@ export const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
  * particle transform/material data rather than MeshAsset attributes.
  */
 export const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  canonicalMeshVertexBufferLayout(),
+  PARTICLE_MESH_VERTEX_BUFFER,
   defineFeatureVertexBuffer(MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 

package/src/device/device-scope.ts

@@ -176,6 +176,7 @@ export class DeviceScope {
     this.clearChildren();
     this._clearResources();
     this.lifecycleState = 'retired';
+    this.parent?.detachChild(this);
   }
 
   abandon(): void {
@@ -183,6 +184,7 @@ export class DeviceScope {
     this.lifecycleState = 'abandoned';
     this.clearChildren();
     this._clearResources();
+    this.parent?.detachChild(this);
   }
 
   dispose(): void {
@@ -190,6 +192,7 @@ export class DeviceScope {
     this.lifecycleState = 'disposed';
     this.clearChildren();
     this._clearResources();
+    this.parent?.detachChild(this);
   }
 
   async replace(

package/src/features/particle-mesh-layout.ts

@@ -0,0 +1,25 @@
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+
+// Mesh attributes keep geometry's canonical packing. Only locations change:
+// the particle instance occupies 4..9 and custom material inputs occupy 10..13.
+export const PARTICLE_MESH_DEFAULTS = {
+  position: [0, 0, 0],
+  normal: [0, 0, 1],
+  uv: [0, 0],
+  tangent: [1, 0, 0, 1],
+  uv1: [0, 0],
+  color: [1, 1, 1, 1],
+} as const;
+export const PARTICLE_MESH_GEOMETRY = deriveVertexLayoutProjection(
+  Object.fromEntries(Object.keys(PARTICLE_MESH_DEFAULTS).map((key) => [key, new Float32Array()])),
+);
+
+export const PARTICLE_MESH_VERTEX_BUFFER = {
+  arrayStride: PARTICLE_MESH_GEOMETRY.arrayStride,
+  stepMode: 'vertex' as const,
+  attributes: PARTICLE_MESH_GEOMETRY.attributes.map(({ key, shaderLocation, offset, format }) => ({
+    shaderLocation: key === 'color' ? 14 : key === 'uv1' ? 15 : shaderLocation,
+    offset,
+    format,
+  })),
+};

package/src/features/types.ts

@@ -180,7 +180,11 @@ export interface RenderFeature<FrameData> {
    * extracted frame and never during declarative planning.
    */
   onFrameSubmitted?(data: FrameData, submission?: RenderFeatureSubmission): void;
-  /** Consume source-owned intents after submission; feedback must be structured-cloneable. */
+  /**
+   * Consume source-owned intents after submission; feedback must be structured-cloneable.
+   * A sealed successor may have been extracted before this acknowledgment. Ordered
+   * intent producers must identify already-submitted work instead of replaying it.
+   */
   onSourceFrameSubmitted?(data: FrameData, feedback: unknown): void;
   /**
    * Discard frame-owned producer state when graph admission or submission is

package/src/gpu-driven/production-raster.ts

@@ -1359,6 +1359,7 @@ export interface PreparedGpuDrivenFrame {
   readonly projectShadow?: (
     graph: RenderGraphBuilder<RenderPipelineFrame>,
     identity: ShadowViewIdentity,
+    forceCompute?: boolean,
   ) => Result<ShadowViewProjection | undefined, RenderGraphError>;
   readonly updateShadowViews?: (
     views: readonly Omit<ShadowViewUpdateInput, 'sourcePlan' | 'scene'>[],
@@ -2572,7 +2573,12 @@ export class GpuDrivenProduction {
         ?.inspect()
         .map(
           (entry) =>
-            `${shadowViewIdentityKey(entry.identity)}:${entry.cache}:${entry.generation}:${entry.sourceRevision}:${entry.resourceGeneration}`,
+            // Cache decisions and logical update generations are frame-local
+            // producer state. They must not feed the compiled graph key: a
+            // graph replacement may intentionally invalidate a shadow view
+            // once without creating a graph-rebuild feedback loop. Resource
+            // and source-plan generations remain real graph dependencies.
+            `${shadowViewIdentityKey(entry.identity)}:${entry.sourceRevision}:${entry.resourceGeneration}`,
         )
         .join('|') ?? '';
     const production = this;
@@ -2689,10 +2695,10 @@ export class GpuDrivenProduction {
                 frameNumber,
               ),
           }),
-      projectShadow: (graph, identity) => {
+      projectShadow: (graph, identity, forceCompute = false) => {
         if (!shadowViewPool.isActive(identity) || shadowViewPool.submission(identity) === undefined)
           return ok(undefined);
-        return shadowViewPool.project(graph, identity);
+        return shadowViewPool.project(graph, identity, forceCompute);
       },
       updateShadowViews: (views) =>
         shadowFiltered.plan.batches.length > 0

package/src/gpu-driven/shadow-views.ts

@@ -395,14 +395,39 @@ export class ShadowViewStatePool {
   project<FrameCtx extends RenderGraphFrame>(
     builder: RenderGraphBuilder<FrameCtx>,
     identity: ShadowViewIdentity,
+    forceCompute = false,
   ): Result<ShadowViewProjection, RenderGraphError> {
     const record = this.records.get(identityKey(identity));
     if (record === undefined) return err(graphStateError(identity));
     const cacheHit = record.cache === 'hit' && !record.invalidated;
+    // A graph replacement must carry the shadow compute passes even when the
+    // view itself is a cache hit. The graph owns the pass list, so omitting
+    // compute work while importing a replacement graph would leave its
+    // indirect arguments stale. The normal pool contract still skips work on
+    // a cache hit; graph projection opts in explicitly at that boundary.
+    const includeCompute = forceCompute || !cacheHit;
+    let forceComputePending = forceCompute;
+    let lastFrame: FrameCtx | undefined;
+    let executeForFrame = false;
+    const executeCompute = (frame: FrameCtx): boolean => {
+      if (frame !== lastFrame) {
+        lastFrame = frame;
+        const currentRecord = this.records.get(identityKey(record.identity));
+        executeForFrame =
+          forceComputePending ||
+          currentRecord === undefined ||
+          currentRecord.cache !== 'hit' ||
+          currentRecord.invalidated;
+        forceComputePending = false;
+      }
+      return executeForFrame;
+    };
     const projected = record.view.addPasses(
       builder,
       shadowViewLabelPrefix(record.identity),
-      !cacheHit,
+      includeCompute,
+      undefined,
+      includeCompute ? executeCompute : undefined,
     );
     if (!projected.ok) return projected;
     return ok({
@@ -411,7 +436,7 @@ export class ShadowViewStatePool {
       generation: record.generation,
       plan: record.plan,
       view: record.view,
-      passNames: cacheHit ? Object.freeze([]) : passNames(record.identity),
+      passNames: includeCompute ? passNames(record.identity) : Object.freeze([]),
       graphResources: projected.value,
     });
   }