@forgeax/engine-render 0.1.35 → 0.1.37

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/host-contract.ts

@@ -14,7 +14,7 @@ import type { ObservationUnavailableError, RenderError } from '../errors/render'
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
 import type { GpuDrivenProductionInspection, LodOcclusionInspection } from '../inspection-types';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
-import type { PublishedRenderFrameInput } from '../publication/contract';
+import type { PublishedRenderFrameInput, RenderPublicationIdentity } from '../publication/contract';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
 import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
 import type {
@@ -110,7 +110,7 @@ export interface RendererHostImplementation {
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
   /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
-  bounds(world: World, entity: number): RenderSceneBounds | undefined;
+  bounds(world: World | RenderPublicationIdentity, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   /**
    * Internal bounded inspection for high-cardinality producers. The public

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'>[],
@@ -1404,7 +1405,7 @@ interface GpuDrivenResidencyValidationCache extends GpuDrivenResidencyValidation
 
 interface GpuDrivenCpuValidationTelemetryCache {
   readonly cacheKey: string;
-  readonly validated: readonly { readonly source: RenderableSnapshot }[];
+  readonly validatedSources: readonly RenderableSnapshot[];
   readonly gpuOwnedDrawKeys: ReadonlySet<string>;
   readonly worldKeys: readonly number[] | undefined;
   readonly gpuOwnedDrawCount: number;
@@ -1420,6 +1421,17 @@ interface GpuDrivenCpuValidationTelemetryCache {
   readonly blockedDrawItems: number;
 }
 
+function sameValidatedSourceSequence(
+  expected: readonly RenderableSnapshot[],
+  actual: readonly { readonly source: RenderableSnapshot }[],
+): boolean {
+  if (expected.length !== actual.length) return false;
+  for (let index = 0; index < expected.length; index += 1) {
+    if (expected[index] !== actual[index]?.source) return false;
+  }
+  return true;
+}
+
 function sameIdentitySequence<T extends object>(
   expected: readonly T[],
   actual: readonly T[],
@@ -2572,7 +2584,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 +2706,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
@@ -3828,7 +3845,7 @@ export class GpuDrivenProduction {
       cacheKey !== undefined &&
       cached !== undefined &&
       cached.cacheKey === cacheKey &&
-      cached.validated === validated &&
+      sameValidatedSourceSequence(cached.validatedSources, validated) &&
       cached.gpuOwnedDrawKeys === gpuOwnedDrawKeys &&
       cached.worldKeys === worldKeys
     ) {
@@ -3914,7 +3931,7 @@ export class GpuDrivenProduction {
     if (cacheKey !== undefined) {
       this.cpuValidationTelemetryCache = {
         cacheKey,
-        validated,
+        validatedSources: validated.map((row) => row.source),
         gpuOwnedDrawKeys,
         worldKeys,
         gpuOwnedDrawCount: this.gpuOwnedDrawItems,

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,
     });
   }

package/src/gpu-driven/view-gpu.ts

@@ -982,6 +982,7 @@ export class GpuDrivenView {
     labelPrefix = 'gpu-driven',
     includeCompute = true,
     surfaceSubmissionObservation?: () => SurfaceSubmissionCandidate | undefined,
+    executeIf?: (frame: FrameCtx) => boolean,
   ): Result<GpuDrivenViewGraphResources, RenderGraphError> {
     const buffers = this.buffers;
     const bindGroup = this.bindGroup;
@@ -1099,6 +1100,7 @@ export class GpuDrivenView {
         { resource: view.value, usage: 'uniform-read' },
         { resource: counters.value, usage: 'storage-read-write' },
       ],
+      ...(executeIf === undefined ? {} : { executeIf }),
       encode: ({ pass }) => {
         pass.setPipeline(this.resetPipeline);
         pass.setBindGroup(0, bindGroup);
@@ -1116,6 +1118,7 @@ export class GpuDrivenView {
         { resource: counters.value, usage: 'storage-read-write' },
         { resource: visible.value, usage: 'storage-read-write' },
       ],
+      ...(executeIf === undefined ? {} : { executeIf }),
       encode: ({ pass }) => {
         pass.setPipeline(this.cullPipeline);
         pass.setBindGroup(0, bindGroup);
@@ -1130,6 +1133,7 @@ export class GpuDrivenView {
         { resource: counters.value, usage: 'storage-read' },
         { resource: indirect.value, usage: 'storage-read-write' },
       ],
+      ...(executeIf === undefined ? {} : { executeIf }),
       encode: ({ pass }) => {
         pass.setPipeline(this.finalizePipeline);
         pass.setBindGroup(0, bindGroup);
@@ -1148,6 +1152,7 @@ export class GpuDrivenView {
         { resource: indirect.value, usage: 'copy-src' },
         { resource: lodReadback.value, usage: 'copy-dst' },
       ],
+      ...(executeIf === undefined ? {} : { executeIf }),
       encode: ({ encoder, resources }) => {
         // A cached graph may run while an observer is awaiting mapAsync on the
         // previous copy. WebGPU forbids submitting a copy into a

package/src/ibl/IblPipelineCache.ts

@@ -1031,12 +1031,13 @@ export async function runIblPrecompute(
       pass.setVertexBuffer(0, opts.cubeVertexBuffer);
       pass.draw(6, 1, face * 6, 0);
       pass.end();
+
+      // Bound software-GPU work just as for irradiance; preserve every sample.
+      const faceStage = await submitStage(`prefilter-mip-${mip}-face-${face}`, true);
+      if (!faceStage.ok) return err(faceStage.error);
     }
   }
 
-  const prefilterStage = await submitStage('prefilter', true);
-  if (!prefilterStage.ok) return err(prefilterStage.error);
-
   // (d) brdf-lut: fullscreen triangle.
   {
     const pass: RhiRenderPassEncoder = encoder.beginRenderPass({

package/src/pbr-pipeline.ts

@@ -158,7 +158,10 @@ export function buildPbrMaterialUserRegionEntries(
   let entries = derived.bglEntries.map(
     (entry): GPUBindGroupLayoutEntry => ({
       binding: entry.binding,
-      visibility: entry.visibility,
+      visibility:
+        entry.texture !== undefined || entry.sampler !== undefined
+          ? GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT
+          : entry.visibility,
       ...(entry.buffer === undefined ? {} : { buffer: entry.buffer }),
       ...(entry.sampler === undefined ? {} : { sampler: entry.sampler }),
       ...(entry.texture === undefined ? {} : { texture: entry.texture }),

package/src/publication/__tests__/features.integration.test.ts

@@ -120,3 +120,54 @@ it('publishes LOD GUID dependencies and rejects a missing lower-detail asset bef
   candidate.discard();
   publisher.dispose();
 });
+
+it('keeps two sealed publications and their feedback independent of later source mutation', async () => {
+  const world = new World();
+  const assets = new AssetRegistry(new ShaderRegistry({ manifestUrl: undefined }));
+  let value = 1;
+  const consumed: unknown[] = [];
+  const feature: RenderFeature<unknown> = {
+    identity: 'sealed-events',
+    extract: () => ok({ value }),
+    plan: () => ok({ resources: [], passes: [] }),
+    onSourceFrameSubmitted: (data) => consumed.push(data),
+  };
+  const publisher = createRenderPublisher(
+    world,
+    assets,
+    { source: 'sealed', epoch: 1 },
+    undefined,
+    [feature],
+  );
+  const seal = () => {
+    const candidate = publisher.prepare(value).unwrap();
+    const packet = structuredClone(candidate.packet, {
+      transfer: renderPublicationTransfers(candidate.packet),
+    });
+    candidate.accept();
+    return packet;
+  };
+  try {
+    const first = seal();
+    value = 2;
+    const second = seal();
+    await Promise.resolve();
+    value = 99;
+    expect(second.features[0]?.data).toEqual({ value: 2 });
+    expect(publisher.prepare(3).ok).toBe(false);
+    expect(publisher.recycle(2, renderPublicationTransfers(second)).ok).toBe(false);
+    publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: null }]).unwrap();
+    publisher.recycle(1, renderPublicationTransfers(first)).unwrap();
+    expect(
+      publisher.acknowledgeFeatures(1, [{ identity: feature.identity, feedback: null }]).ok,
+    ).toBe(false);
+    publisher.acknowledgeFeatures(2, [{ identity: feature.identity, feedback: null }]).unwrap();
+    expect(consumed).toEqual([{ value: 1 }, { value: 2 }]);
+    publisher.recycle(2, renderPublicationTransfers(second)).unwrap();
+    const third = seal();
+    expect(third.base).toBe(2);
+    expect(third.features[0]?.data).toEqual({ value: 99 });
+  } finally {
+    publisher.dispose();
+  }
+});