@forgeax/engine-render 0.1.33 → 0.1.35

package/src/assembly/webgpu-renderer.ts

@@ -6,7 +6,7 @@ import {
   DynamicTextureStore,
 } from '@forgeax/engine-assets-runtime';
 import { audioLoader } from '@forgeax/engine-audio-webaudio';
-import { Update, type World } from '@forgeax/engine-ecs';
+import type { World } from '@forgeax/engine-ecs';
 import { createRenderReadLease, type RenderReadLease } from '@forgeax/engine-ecs/projection';
 import {
   DEFAULT_VERTEX_ATTRIBUTE_MAP,
@@ -14,7 +14,6 @@ import {
 } from '@forgeax/engine-geometry';
 import type {
   BindGroupLayout,
-  Buffer,
   PipelineLayout,
   RenderPipeline,
   Result,
@@ -22,12 +21,14 @@ import type {
   RhiDevice,
 } from '@forgeax/engine-rhi';
 import { err, ok, RhiError, validateDrawArgs } from '@forgeax/engine-rhi';
-import { registerPropagateTransforms } from '@forgeax/engine-scene';
 import {
   findVariantByKey,
   type MaterialShaderEntry,
   type MaterialShaderManifestEntry,
   ShaderCatalog,
+  SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_WGSL,
+  SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_WGSL,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
   standardPhysicalTextureFields,
 } from '@forgeax/engine-shader';
 import type {
@@ -37,6 +38,11 @@ import type {
   PrimitiveTopology,
   VertexAttributeMap,
 } from '@forgeax/engine-types';
+import { type PublishedRenderFrameInput, RenderPublicationError } from '../publication/contract';
+import { installPublicationPrograms } from '../publication/programs';
+import { type PreparedRenderPublication, RenderPublicationReceiver } from '../publication/receiver';
+import { RenderPublicationTargetReceiver } from '../publication/targets';
+import { registerRenderSourceSystems } from '../scene/source-systems';
 import { transmissionBackdropAvailable } from './device-feature-admission';
 
 export type { MaterialShaderManifestEntry } from '@forgeax/engine-shader';
@@ -53,6 +59,10 @@ import {
   RenderFeatureCapabilityMissingError,
   RenderFeatureStageFailedError,
 } from '../errors/render';
+import {
+  BARREL_DISTORTION_FEATURE_IDENTITY,
+  createBarrelDistortionRenderFeature,
+} from '../features/barrel-distortion';
 import {
   dofInspection,
   registerDepthOfFieldBuiltins,
@@ -65,7 +75,6 @@ import {
   type PostProcessShaderEntry,
   postProcessShaderModuleLabel,
 } from '../fullscreen-post-process-pass';
-import { glyphTextLayoutSystem } from '../glyph-text-layout-system';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from '../gpu-stage';
 import { type BloomInspection, emptyBloomInspection } from '../inspection-types';
 import { DeviceScope } from '../lifecycle';
@@ -74,9 +83,13 @@ import {
   isCanonicalStandardPbrMaterialShader,
   isStandardPbrMaterialShader,
   type PipelineGroup2Contract,
-  resolvePipelineGroup2Contract,
   SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
+import {
+  SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID,
+  SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID,
+  SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID,
+} from '../pipeline/single-layer-medium-passes';
 import { standardPipeline } from '../pipeline/standard-pipeline';
 import { DEFAULT_STANDARD_PROFILE } from '../pipeline/standard-profile';
 import { buildPipelineForMaterialShader } from '../pipeline-builder';
@@ -132,7 +145,7 @@ import type {
   SsrShaderSources,
   VolumetricFogShaderSources,
 } from '../render-contract';
-import { STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
+import { FXAA_POST_PROCESS_ID, STANDARD_OUTPUT_TRANSFORM_FEATURE_ID } from '../render-contract';
 import {
   attachGpuPassTimingSession,
   createRenderSystem,
@@ -145,11 +158,12 @@ import {
 import { createGpuPassTimingObservationStore, observeGpuPassTimingDisabled } from '../renderer.js';
 import { postSpawnResolveJoints } from '../scene-instances/post-spawn-resolve-joints';
 import type { RenderTarget } from '../targets/contracts';
-import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
 import type { TypedFrameObservationCapture } from '../typed-render-graph-primitives';
 import { registerAnalyticFogPostProcess } from './analytic-fog-registration';
 import type { RhiBackendPack } from './backend-contract';
+import { inspectBarrelDistortion } from './barrel-distortion-inspection';
 import type { BundlerOptions } from './bundler-contract';
+import { rejectZeroCanvasSize } from './canvas-draw-guard';
 import { createRendererDynamicGeometryController } from './dynamic-geometry-host';
 import { registerFxaaPostProcess } from './fxaa-registration';
 import type { RendererAssemblyImplementation } from './host-contract';
@@ -157,6 +171,7 @@ import { observeLodOcclusionForReceipt } from './lod-observation';
 import {
   isEngineOwnedMaterialShader,
   resolveMaterialPipelineBindGroups,
+  resolveMaterialPipelineGroup2Contract,
   resolveMaterialPipelineShaderId,
   resolveMaterialPipelineVertexEntry,
   resolveRendererMaterialShaderArtifact,
@@ -169,6 +184,7 @@ import {
   type MaterialShaderBindingContract,
   makeShaderDeviceAdapter,
   normalizeMaterialShaderVariantSet,
+  prepareLowLimitMaterialShaderEntry,
   prepareMaterialShaders,
   resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
@@ -188,6 +204,7 @@ import {
   publishGeneration,
 } from './recovery/generation';
 import { createRendererRecovery, type RendererRecovery } from './recovery/renderer-recover';
+import { collectRequiredFullscreenPostProcesses } from './render-feature-post-processes';
 import { createRenderTargetHost } from './render-target-host';
 import {
   freezeRenderProfile,
@@ -198,6 +215,7 @@ import { projectRendererFeatureInspection } from './renderer-feature-inspection'
 import {
   type ContinuationTerminator,
   createContinuationTerminator,
+  guardFrameCompletion,
 } from './renderer-frame-transaction';
 import {
   ensureContextConfigured,
@@ -205,7 +223,7 @@ import {
   rendererInitializationPipelineError,
   wrapDisposeError,
 } from './renderer-helpers';
-import { projectRendererOutputInspection } from './renderer-inspection';
+import { projectRendererOutputInspectionFromSurface } from './renderer-inspection';
 import {
   createRecoveryContinuation,
   createRecoveryDeadline,
@@ -229,7 +247,10 @@ import {
   type WebGPURendererInternals,
 } from './webgpu-renderer-bootstrap';
 import type { WebGPUOutcome } from './webgpu-renderer-contract';
-import { disposeObservationCaptureSet } from './webgpu-renderer-observation';
+import {
+  createRendererObservationCaptureOwner,
+  type ObservationCaptureRead,
+} from './webgpu-renderer-observation-owner';
 import {
   isPreparedMaterialVertexLayout,
   PREPARED_INSTANCE_VERTEX_ATTRS,
@@ -257,6 +278,7 @@ export {
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,
   shouldDeferMissingPreparedMaterialShader,
+  stripCloudShadowBindingsForLowLimit,
 } from './material-shader-policy';
 export {
   createMeshSsboGrowController,
@@ -283,7 +305,6 @@ export type { WebGPUOutcome, WebGPURendererInternals } from './webgpu-renderer-c
 export { disposeObservationCaptureSet } from './webgpu-renderer-observation';
 
 /** Bundler injection and the WebGPU renderer construction entry points. */
-let nextDerivedSystemId = 0;
 export async function tryCreateWebGPURenderer(
   canvas: HTMLCanvasElement | OffscreenCanvas,
   options: RendererOptions | undefined,
@@ -295,7 +316,12 @@ export async function tryCreateWebGPURenderer(
 async function makeWebGPURenderer(
   internals: WebGPURendererInternals,
 ): Promise<RendererAssemblyImplementation> {
+  let publicationTargets: RenderPublicationTargetReceiver | undefined;
   let disposed = false;
+  const publicationReceiver =
+    internals.options?.publicationSource === undefined
+      ? undefined
+      : new RenderPublicationReceiver(internals.options.publicationSource);
   const observeTiming = observeGpuPassTimingDisabled;
   const frameContinuations = new Set<ContinuationTerminator>();
   type RecoveryInspection = RenderInspection['recovery'];
@@ -333,7 +359,13 @@ async function makeWebGPURenderer(
   let renderTargetDevice = internals.device;
   let renderTargetGeneration = 0;
   let renderSystemForTargetPromotion: RenderSystem | undefined;
-  const featureHostResult = createRenderFeatureHost(internals.options?.features ?? []);
+  const requestedFeatures = internals.options?.features ?? [];
+  const featureHostFeatures = requestedFeatures.some(
+    (f) => f.identity === BARREL_DISTORTION_FEATURE_IDENTITY,
+  )
+    ? requestedFeatures
+    : [...requestedFeatures, createBarrelDistortionRenderFeature()];
+  const featureHostResult = createRenderFeatureHost(featureHostFeatures);
   if (!featureHostResult.ok) throw featureHostResult.error;
   internals.featureHost = featureHostResult.value;
   let rendererRecovery: RendererRecovery | undefined;
@@ -466,27 +498,8 @@ async function makeWebGPURenderer(
     featureHostResult.value.features.flatMap((feature) => feature.requiredMaterialShaders ?? []),
   );
   let requiredMaterialShaders = Object.freeze([...requiredMaterialShaderSet]);
-  const collectRequiredFullscreenPostProcesses = (
-    features: readonly RenderFeature<unknown>[],
-  ): readonly { readonly identity: string; readonly source: string }[] => {
-    const entries = new Map<string, { readonly identity: string; readonly source: string }>();
-    for (const feature of features) {
-      for (const entry of feature.requiredFullscreenPostProcesses ?? []) {
-        const existing = entries.get(entry.identity);
-        if (existing !== undefined && existing.source !== entry.source) {
-          throw new RhiError({
-            code: 'internal-error',
-            expected: `fullscreen identity '${entry.identity}' has one source across render features`,
-            hint: 'rename the conflicting fullscreen identity or make its WGSL source identical',
-          });
-        }
-        entries.set(entry.identity, entry);
-      }
-    }
-    return Object.freeze([...entries.values()]);
-  };
-  let requiredFullscreenPostProcesses = collectRequiredFullscreenPostProcesses(
-    featureHostResult.value.features,
+  let requiredFullscreenPostProcesses = Object.freeze(
+    collectRequiredFullscreenPostProcesses(featureHostResult.value.features),
   );
   // Lazy ShaderCatalog instance (plan-strategy section S-10 / D-R10 / OQ-5
   // close): constructed on first access; subsequent accesses return the
@@ -536,7 +549,7 @@ async function makeWebGPURenderer(
     feature: RenderFeature<unknown>,
   ): Promise<Result<void, RhiError>> => {
     for (const postProcess of feature.requiredFullscreenPostProcesses ?? []) {
-      const label = postProcessShaderModuleLabel(postProcess.identity, postProcess.source);
+      const label = postProcessShaderModuleLabel(postProcess.source);
       const shaderResult = internals.pack.createShaderModule
         ? await internals.pack.createShaderModule(internals.device, {
             code: postProcess.source,
@@ -577,27 +590,7 @@ async function makeWebGPURenderer(
     }
     return state.shaderInstance;
   };
-  // D-S9: AssetRegistry instance shared with RenderSystem. RenderSystem
-  // looks up MeshFilter.assetHandle here per frame; buildReadyWebGPU step 3
-  // uploads the registry's builtin mesh geometry to GPU buffers so the
-  // RenderSystem can route MeshFilter.assetHandle to a real (vbo, ibo) pair.
-  // feat-20260527 M1 / w1: ShaderCatalog is now eager-constructed and
-  // constructor-injected into AssetRegistry (plan-strategy D-1). The
-  // ShaderCatalogDevice adapter (shared between the catalog and per-MaterialShader
-  // pipeline cache) is already available at this point.
   const shaderCatalog = getShader();
-  // bug-20260601-hello-tonemap-material-register M1 (plan-strategy D-1):
-  // All material-shader entries are now registered from the manifest
-  // BEFORE the renderer is returned, so `register<MaterialAsset>` referencing
-  // an engine shader succeeds without waiting for `renderer.initialization`.
-  // Host-injected ImportTransport remains a constructor-only dependency.
-  // feat-20260705-runtime-tier2-decomposition M1 / w10 (D-1 / D-2): the sole
-  // production assembly point injects (a) the post-spawn hook
-  // `postSpawnResolveJoints` (auto-wire Skin.joints; D-1) and the audio
-  // catalog-entry loader. The latter stays at this assembly boundary so
-  // assets-runtime remains independent of the concrete Web Audio backend.
-  // videoLoader is wired internally from graphics-extras; the full registry has
-  // 11 engine kinds. This is the only `new AssetRegistry(...)` call in the repo.
   const assets = new AssetRegistry(
     shaderCatalog,
     internals.importTransport,
@@ -728,7 +721,9 @@ async function makeWebGPURenderer(
   gpuStore.configureGpuDevice(
     internals.device,
     packShaderFactory,
-    (world, pod) => {
+    (world, pod, source) => {
+      // The accepted equirect identity already owns this renderer-local GPU projection.
+      if ('resolveAsset' in world) return ok(source);
       const handle = world.allocSharedRef('EquirectAsset', pod);
       return ok(handle);
     },
@@ -1137,6 +1132,9 @@ async function makeWebGPURenderer(
     const lookup = getShader().findMaterialArtifact(materialShaderId);
     const source = lookup.ok ? lookup.value.source : '';
     const paramSchema = lookup.ok ? lookup.value.paramSchema : explicitParamSchema;
+    const singleLayerMedium =
+      materialShaderId === 'forgeax::single-layer-medium' ||
+      (lookup.ok && lookup.value.receipt?.surface?.model === 'single-layer-medium');
     if (paramSchema === undefined) return null;
     const cacheKey = `${materialShaderId}:${layoutKind}:${clustered}`;
     const cached = cacheState.perShaderMaterialLayoutCache.get(cacheKey);
@@ -1155,7 +1153,12 @@ async function makeWebGPURenderer(
       isStandardPbrMaterialShader(materialShaderId) ||
       standardPhysicalTextureFields(paramSchema).length > 0;
     const isStandardMapLayout = requiresStandardMapLayout;
-    if (!clustered && !isStandardMapLayout && isSharedMaterialUserRegionCompatible(paramSchema)) {
+    if (
+      !clustered &&
+      !singleLayerMedium &&
+      !isStandardMapLayout &&
+      isSharedMaterialUserRegionCompatible(paramSchema)
+    ) {
       cacheState.perShaderMaterialLayoutCache.set(cacheKey, {
         source,
         paramSchema,
@@ -1165,7 +1168,11 @@ async function makeWebGPURenderer(
       return null;
     }
     const spec: PipelineSpec = {
-      shader: { id: materialShaderId, passKind: 'forward', variantSet: undefined },
+      shader: {
+        id: singleLayerMedium ? 'forgeax::single-layer-medium' : materialShaderId,
+        passKind: 'forward',
+        variantSet: undefined,
+      },
       attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
       geometry: { topology: 'triangle-list', vertexLayout: {} },
       renderState: undefined,
@@ -1552,7 +1559,11 @@ async function makeWebGPURenderer(
           : getShaderModuleAdapter(),
       pipelineLayout,
       vertexBuffers,
-      ...(layoutKind === 'pbr-skin' || layoutKind === 'gpu-driven-skin' ? { layoutKind } : {}),
+      ...(layoutKind === 'pbr-skin' ||
+      layoutKind === 'gpu-driven-skin' ||
+      layoutKind === 'gpu-driven-cluster-skin'
+        ? { layoutKind }
+        : {}),
     };
   };
   /**
@@ -1619,7 +1630,10 @@ async function makeWebGPURenderer(
     particleInputLanes?: number,
     coverageOnly = false,
   ): RenderPipeline | null => {
-    const declaredGroup2Contract = resolvePipelineGroup2Contract(entry.source);
+    const declaredGroup2Contract = resolveMaterialPipelineGroup2Contract(
+      entry.source,
+      layoutKindOverride,
+    );
     const group2Contract =
       declaredGroup2Contract === 'mesh' &&
       (materialShaderId === 'forgeax::vfx-render.particles.mesh' ||
@@ -2048,6 +2062,10 @@ async function makeWebGPURenderer(
         }
       }
     }
+    shaderEntry = prepareLowLimitMaterialShaderEntry(
+      shaderEntry,
+      currentBuildDevice().limits.maxSampledTexturesPerShaderStage,
+    );
     // feat-20260609 M4 / R3-fixup: append `-${passKind}` to the PSO label so
     // GPU debug captures (and the shadow-caster branch in the builder)
     // make the cache variant visible. The fallback path above keeps the
@@ -2115,10 +2133,50 @@ async function makeWebGPURenderer(
   ) => {
     const pipeline = getMaterialShaderPipeline(...args);
     if (pipeline === null) return null;
+    const materialShaderId = args[0];
+    const variantSet = args[5];
+    const passKind = args[6] ?? 'forward';
+    const vertexLayoutProjection = args[13];
+    const layoutKind = args[15];
+    const sceneIndexAddress =
+      layoutKind === 'gpu-driven-pbr' ||
+      layoutKind === 'gpu-driven-skin' ||
+      layoutKind === 'gpu-driven-cluster-pbr' ||
+      layoutKind === 'gpu-driven-cluster-skin';
+    const artifact = resolveRendererMaterialShaderArtifact(
+      materialShaderId,
+      getShader(),
+      pipelineState?.gpuDrivenPbrPrograms,
+      {
+        ...(vertexLayoutProjection === undefined
+          ? {}
+          : {
+              vertexColorAvailable: vertexLayoutProjection.attributes.some(
+                (attribute) => attribute.key === 'color',
+              ),
+            }),
+        ...(layoutKind === 'pbr-skin' ||
+        layoutKind === 'gpu-driven-skin' ||
+        layoutKind === 'gpu-driven-cluster-skin'
+          ? { deformation: 'skin' as const }
+          : {}),
+        ...(variantSet === undefined ? {} : { variantSet }),
+        address: sceneIndexAddress ? 'scene-index' : 'direct',
+        pass: passKind === 'shadow-caster' ? 'shadow' : 'forward',
+      },
+    );
     return {
       pipeline,
       group2Contract:
         materialShaderPipelineGroup2Contracts.get(pipeline as object) ?? ('mesh' as const),
+      ...(artifact?.receipt === undefined
+        ? {}
+        : {
+            receipt: {
+              identity: artifact.receipt.receiptIdentity,
+              generation: artifact.receipt.generation,
+            },
+          }),
     };
   };
   const getParamSchema = (materialShaderId: string) => {
@@ -2172,10 +2230,11 @@ async function makeWebGPURenderer(
     colorFormats: readonly GPUTextureFormat[],
     label: string,
   ): RenderPipeline | null => {
+    const isFxaaPipeline = label.startsWith(`post-process-${FXAA_POST_PROCESS_ID}-pso-`);
     const moduleFactory = getShaderModuleAdapter();
     const moduleResult = moduleFactory.createShaderModule({
       code: entry.source,
-      label: `${label}-module`,
+      label: postProcessShaderModuleLabel(entry.source),
     });
     if (!moduleResult.ok) {
       // 'rhi-not-available' = async compile in flight: caller falls back one frame.
@@ -2186,7 +2245,7 @@ async function makeWebGPURenderer(
       }
       return null;
     }
-    if (currentEmptyPostProcessBgl() === null) {
+    if (!isFxaaPipeline && entry.usesView !== true && currentEmptyPostProcessBgl() === null) {
       const bglRes = currentBuildDevice().createBindGroupLayout({ entries: [] });
       if (!bglRes.ok) {
         internals.errorRegistry.fire(bglRes.error);
@@ -2199,9 +2258,18 @@ async function makeWebGPURenderer(
         emptyPostProcessBgl = bglRes.value;
       }
     }
+    const viewLayout =
+      entry.usesView === true ? currentPipelineState()?.viewBindGroupLayout : undefined;
+    const group0Layout = viewLayout ?? currentEmptyPostProcessBgl();
+    if (group0Layout === null || group0Layout === undefined) {
+      internals.errorRegistry.fire(
+        new Error('fullscreen post-process View layout is unavailable') as never,
+      );
+      return null;
+    }
     const layoutRes = currentBuildDevice().createPipelineLayout({
       label: `${label}-layout`,
-      bindGroupLayouts: [currentEmptyPostProcessBgl() as BindGroupLayout, bgl],
+      bindGroupLayouts: isFxaaPipeline ? [bgl] : [group0Layout as BindGroupLayout, bgl],
     });
     if (!layoutRes.ok) {
       internals.errorRegistry.fire(layoutRes.error);
@@ -2439,6 +2507,22 @@ async function makeWebGPURenderer(
   });
   attachGpuPassTimingSession(internals, gpuPassTimingSession);
   renderSystemForTargetPromotion = renderSystem;
+  renderSystem.registerBuiltinPostProcess(SINGLE_LAYER_MEDIUM_RAW_DEPTH_POST_PROCESS_ID, {
+    source: SINGLE_LAYER_MEDIUM_RAW_DEPTH_WGSL,
+    reads: ['input', { key: 'scene-depth', sampleType: 'depth' }],
+  });
+  const pairedMsaaReads = [
+    { key: 'input', sampleType: 'multisampled-float' as const },
+    { key: 'scene-depth', sampleType: 'depth' as const },
+  ];
+  renderSystem.registerBuiltinPostProcess(SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_POST_PROCESS_ID, {
+    source: SINGLE_LAYER_MEDIUM_MSAA_PAIRED_COLOR_WGSL,
+    reads: pairedMsaaReads,
+  });
+  renderSystem.registerBuiltinPostProcess(SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_POST_PROCESS_ID, {
+    source: SINGLE_LAYER_MEDIUM_MSAA_RAW_DEPTH_WGSL,
+    reads: pairedMsaaReads,
+  });
   if (
     internals.device.caps.backendKind === 'null' &&
     Array.from(getShader().entries()).length === 0
@@ -2466,7 +2550,6 @@ async function makeWebGPURenderer(
       currentGeneration: () => activeDeviceScope.generation,
       renderSystem,
     });
-  const derivedSystemNames = new Map<World, string>();
   const transformReleases = new Map<World, () => void>();
   const attachmentOwner = {};
   let frameId = 0;
@@ -2475,184 +2558,41 @@ async function makeWebGPURenderer(
   const receiptTimings = new WeakMap<FrameReceipt, Promise<VolumeTimingObservation>>();
   let latestReceipt: FrameReceipt | undefined;
   let pendingObservationDomains: readonly FrameObservationDomain[] | undefined;
-  let observationAllocationCount = 0;
-  let observationLiveCount = 0;
-  let observationPeakLiveCount = 0;
-  let observationMapCount = 0;
-  let observationReadbackCount = 0;
-  let observationLiveByteLength = 0;
-  const observationCaptureOwner = (() => {
-    const capturesByFrame = new Map<number, TypedFrameObservationCapture[]>();
-    return {
-      register(capture: TypedFrameObservationCapture): void {
-        const captures = capturesByFrame.get(capture.frameNumber) ?? [];
-        captures.push(capture);
-        capturesByFrame.set(capture.frameNumber, captures);
-        observationAllocationCount += 1;
-        observationLiveCount += 1;
-        observationPeakLiveCount = Math.max(observationPeakLiveCount, observationLiveCount);
-        observationLiveByteLength += capture.bytesPerRow * capture.height;
-      },
-      consume(frameNumber: number): readonly TypedFrameObservationCapture[] {
-        const captures = capturesByFrame.get(frameNumber) ?? [];
-        capturesByFrame.delete(frameNumber);
-        return Object.freeze(captures);
-      },
-      drain(): readonly TypedFrameObservationCapture[] {
-        const captures = [...capturesByFrame.values()].flat();
-        capturesByFrame.clear();
-        return Object.freeze(captures);
-      },
-    };
-  })();
+  const observationOwner = createRendererObservationCaptureOwner((error) => {
+    internals.errorRegistry.fire(error);
+  });
+  const {
+    observationCaptureOwner,
+    stats: observationStats,
+    receiptObservationCaptures,
+    receiptObservationBuffers,
+    destroyedObservationBuffers,
+    disposeObservationCaptures,
+    disposeOwnedObservationCaptures,
+    readObservationCapture,
+    disposeReceiptObservationCaptures,
+  } = observationOwner;
   Object.assign(internals, { observationCaptureOwner });
-  let expectedObservationGraphGeneration: number | undefined;
   Object.defineProperty(internals, 'observationGraphGeneration', {
     configurable: true,
-    get: () => expectedObservationGraphGeneration,
+    get: () => observationOwner.expectedGraphGeneration,
     set: (generation: number | undefined) => {
-      expectedObservationGraphGeneration = generation;
+      observationOwner.expectedGraphGeneration = generation;
     },
   });
-  type ObservationCaptureRead = () => Promise<
-    RenderResult<
-      readonly {
-        readonly capture: TypedFrameObservationCapture;
-        readonly bytes: Uint8Array;
-      }[],
-      RenderError
-    >
-  >;
-  const receiptObservationCaptures = new Map<FrameReceipt, ObservationCaptureRead>();
-  const receiptObservationBuffers = new Map<
-    FrameReceipt,
-    readonly TypedFrameObservationCapture[]
-  >();
-  const destroyedObservationBuffers = new WeakSet<Buffer>();
-  const observationBufferCleanupFailures = new WeakMap<Buffer, RendererContractFailureError>();
-  const failedObservationCaptures = new Map<Buffer, TypedFrameObservationCapture>();
-  const disposeObservationCaptures = (
-    captures: readonly TypedFrameObservationCapture[],
-  ): RendererContractFailureError | undefined => {
-    const wasDestroyed = new Set(
-      captures
-        .filter((capture) => destroyedObservationBuffers.has(capture.buffer))
-        .map((capture) => capture.buffer),
-    );
-    const result = disposeObservationCaptureSet(
-      captures,
-      destroyedObservationBuffers,
-      observationBufferCleanupFailures,
-      (failure) => internals.errorRegistry.fire(failure),
-    );
-    for (const capture of captures) {
-      if (!wasDestroyed.has(capture.buffer) && destroyedObservationBuffers.has(capture.buffer)) {
-        observationLiveCount = Math.max(0, observationLiveCount - 1);
-        observationLiveByteLength = Math.max(
-          0,
-          observationLiveByteLength - capture.bytesPerRow * capture.height,
-        );
-      }
-    }
-    return result;
-  };
-  const disposeOwnedObservationCaptures = (
-    captures: readonly TypedFrameObservationCapture[],
-  ): RendererContractFailureError | undefined => {
-    const failure = disposeObservationCaptures(captures);
-    if (failure !== undefined) {
-      for (const capture of captures) {
-        if (!destroyedObservationBuffers.has(capture.buffer)) {
-          failedObservationCaptures.set(capture.buffer, capture);
-        }
-      }
-    }
-    return failure;
-  };
-  const readObservationCapture = async (
-    capture: TypedFrameObservationCapture,
-  ): Promise<RenderResult<Uint8Array, RenderError>> => {
-    try {
-      if (typeof capture.buffer.mapAsync !== 'function') {
-        const cleanupFailure = disposeObservationCaptures([capture]);
-        return err(
-          cleanupFailure ??
-            new RendererContractFailureError(
-              'observe',
-              `the ${capture.domain} receipt-bound readback backend has no mapAsync capability`,
-            ),
-        );
-      }
-      observationMapCount += 1;
-      const mapped = await capture.buffer.mapAsync(1);
-      if (!mapped.ok) {
-        const cleanupFailure = disposeObservationCaptures([capture]);
-        return err(
-          cleanupFailure ??
-            new RendererContractFailureError(
-              'observe',
-              `mapping ${capture.domain} receipt-bound readback failed: ${mapped.error.code}`,
-            ),
-        );
-      }
-      const range = mapped.value.getMappedRange();
-      if (!range.ok) {
-        mapped.value.unmap();
-        const cleanupFailure = disposeObservationCaptures([capture]);
-        return err(
-          cleanupFailure ??
-            new RendererContractFailureError(
-              'observe',
-              `reading ${capture.domain} receipt-bound readback failed: ${range.error.code}`,
-            ),
-        );
-      }
-      const bytes = new Uint8Array(range.value.slice(0));
-      mapped.value.unmap();
-      observationReadbackCount += 1;
-      const cleanupFailure = disposeObservationCaptures([capture]);
-      if (cleanupFailure !== undefined) return err(cleanupFailure);
-      return ok(bytes);
-    } catch (cause) {
-      const cleanupFailure = disposeObservationCaptures([capture]);
-      return err(
-        cleanupFailure ??
-          new RendererContractFailureError(
-            'observe',
-            `reading ${capture.domain} receipt-bound readback threw: ${
-              cause instanceof Error ? cause.message : String(cause)
-            }`,
-          ),
-      );
-    }
-  };
-
-  const disposeReceiptObservationCaptures = (): RendererContractFailureError | undefined => {
-    let firstFailure: RendererContractFailureError | undefined;
-    for (const [receipt, captures] of receiptObservationBuffers) {
-      const failure = disposeObservationCaptures(captures);
-      firstFailure ??= failure;
-      if (captures.every((capture) => destroyedObservationBuffers.has(capture.buffer))) {
-        receiptObservationBuffers.delete(receipt);
-      }
-    }
-    receiptObservationCaptures.clear();
-    const retryCaptures = [...failedObservationCaptures.values()];
-    const retryFailure = disposeObservationCaptures(retryCaptures);
-    firstFailure ??= retryFailure;
-    for (const capture of retryCaptures) {
-      if (destroyedObservationBuffers.has(capture.buffer)) {
-        failedObservationCaptures.delete(capture.buffer);
-      }
-    }
-    const ownedFailure = disposeOwnedObservationCaptures(observationCaptureOwner.drain());
-    firstFailure ??= ownedFailure;
-    return firstFailure;
-  };
   let surfaceReleased = false;
   const renderer: RendererAssemblyImplementation = {
-    instances: renderSystem.instances,
+    setSurfaceDynamicInput(frame) {
+      renderSystem.setSurfaceDynamicInput(frame);
+    },
     attach(world: World): RenderResult<RenderWorldLease, RenderError> {
+      if (publicationReceiver !== undefined)
+        return err(
+          new RenderPublicationError({
+            reason: 'identity',
+            subject: 'publication Renderer has no World attachment',
+          }),
+        );
       const attached = this.attachScene(world);
       if (!attached.ok) {
         return err(new RendererContractFailureError('attach', attached.error.hint));
@@ -2714,25 +2654,29 @@ async function makeWebGPURenderer(
             ? 'faulted'
             : 'alive';
       const graph = deviceLost ? undefined : renderSystem.perFrameGraphInfo;
+      const graphResourceAllocation = graph?.resourceAllocation;
+      const graphGenerationAllocation = deviceLost
+        ? undefined
+        : renderSystem.renderGraphGenerationAllocation;
       const standardLighting = deviceLost ? undefined : renderSystem.standardLightingInspection;
+      const barrelDistortion = inspectBarrelDistortion(
+        disposed,
+        deviceLost,
+        surfaceReleased,
+        frameId,
+        activeDeviceScope.generation,
+        renderSystem.barrelDistortionInspection,
+      );
       const bloom: BloomInspection = deviceLost ? emptyBloomInspection() : renderSystem.bloom;
-      const surfaceStorage = pipelineState?.format ?? 'rgba8unorm';
-      const surfaceDisplay = pipelineState?.colorAttachmentFormat ?? 'rgba8unorm';
       const observationId = `${STANDARD_OUTPUT_TRANSFORM_FEATURE_ID}:frame-${frameId}`;
-      const outputInspection = projectRendererOutputInspection({
+      const outputInspection = projectRendererOutputInspectionFromSurface({
         graph,
-        surfaceAvailable: !surfaceReleased && pipelineState !== null,
-        surfaceStorage,
-        surfaceDisplay,
-        ...(pipelineState?.surfaceProfile === undefined
-          ? {}
-          : { surfaceProfile: pipelineState.surfaceProfile }),
+        surfaceReleased,
+        pipelineState,
         rgba16floatRenderable: internals.device.caps.rgba16floatRenderable,
         autoExposure: renderSystem.autoExposure,
         standardLut: renderSystem.standardLut,
-        ...(internals.context?.presentationProof === undefined
-          ? {}
-          : { presentationProof: internals.context.presentationProof }),
+        presentationProof: internals.context?.presentationProof,
       });
       const volumetricFog = renderSystem.volumetricFog;
       const directionalShadow = renderSystem.directionalShadow;
@@ -2747,6 +2691,7 @@ async function makeWebGPURenderer(
           frameId,
           deviceGeneration: activeDeviceScope.generation,
         }),
+        barrelDistortion,
         ...projectRendererFeatureInspection(internals.featureHost),
         featureGraph: renderSystem.featureGraphInspection,
         materialTextureSources: renderSystem.materialTextureSources,
@@ -2756,9 +2701,6 @@ async function makeWebGPURenderer(
           renderSystem.instanceCollectionsInspection.map((collection) =>
             Object.freeze({
               ...collection,
-              dirtyRanges: Object.freeze(
-                collection.dirtyRanges.map((range) => Object.freeze({ ...range })),
-              ),
               uploadRanges: Object.freeze(
                 collection.uploadRanges.map((range) => Object.freeze({ ...range })),
               ),
@@ -2775,6 +2717,12 @@ async function makeWebGPURenderer(
         ),
         dynamicGeometry: dynamicGeometry.inspect(),
         renderScene: renderSystem.renderScene,
+        ...(graphResourceAllocation === undefined
+          ? {}
+          : { renderGraphResourceAllocation: graphResourceAllocation }),
+        ...(graphGenerationAllocation === undefined
+          ? {}
+          : { renderGraphGenerationAllocation: graphGenerationAllocation }),
         ...(renderSystem.iblBinding === undefined ? {} : { iblBinding: renderSystem.iblBinding }),
         reflectionProbes: renderSystem.reflectionProbes,
         ssrDependencies: renderSystem.ssrDependencies,
@@ -2855,12 +2803,12 @@ async function makeWebGPURenderer(
             ? {}
             : { standardOutputColor: Object.freeze({ ...outputInspection.standardOutputColor }) }),
           resourceStats: Object.freeze({
-            allocationCount: observationAllocationCount,
-            liveCount: observationLiveCount,
-            peakLiveCount: observationPeakLiveCount,
-            mapCount: observationMapCount,
-            readbackCount: observationReadbackCount,
-            liveByteLength: observationLiveByteLength,
+            allocationCount: observationStats.allocationCount,
+            liveCount: observationStats.liveCount,
+            peakLiveCount: observationStats.peakLiveCount,
+            mapCount: observationStats.mapCount,
+            readbackCount: observationStats.readbackCount,
+            liveByteLength: observationStats.liveByteLength,
           }),
         }),
       });
@@ -2896,23 +2844,7 @@ async function makeWebGPURenderer(
       }
       if (attachedWorlds.has(world)) return ok(undefined);
       try {
-        const releaseTransforms = registerPropagateTransforms(world);
-        const derivedSystemName = `renderDerived:${++nextDerivedSystemId}`;
-        const derived = world.addSystem(Update, {
-          name: derivedSystemName,
-          queries: [],
-          fn: (world) => {
-            tilemapChunkExtractSystem(world, (guid) => assets.lookup(guid));
-            const glyphResult = glyphTextLayoutSystem(world, gpuStore);
-            if (!glyphResult.ok) throw glyphResult.error;
-          },
-        });
-        if (!derived.ok) {
-          releaseTransforms();
-          throw new Error(`failed to register ${derivedSystemName}: ${derived.error.code}`);
-        }
-        transformReleases.set(world, releaseTransforms);
-        derivedSystemNames.set(world, derivedSystemName);
+        transformReleases.set(world, registerRenderSourceSystems(world, assets, gpuStore));
         attachedWorlds.add(world);
         return ok(undefined);
       } catch (cause) {
@@ -2943,11 +2875,6 @@ async function makeWebGPURenderer(
         }
       }
       renderSystem.detachScene(world);
-      const derivedSystemName = derivedSystemNames.get(world);
-      if (derivedSystemName !== undefined) {
-        world.removeSystem(Update, derivedSystemName);
-        derivedSystemNames.delete(world);
-      }
       transformReleases.get(world)?.();
       transformReleases.delete(world);
     },
@@ -3151,17 +3078,43 @@ async function makeWebGPURenderer(
         : ok(result.value);
     },
     draw(
-      worldsOrRequest: readonly World[] | RenderFrameInput,
+      worldsOrRequest: readonly World[] | RenderFrameInput | PublishedRenderFrameInput,
       options?: DrawOwnerOptions,
     ): Result<void | FrameReceipt, RhiError | RenderError> {
       const isFrameRequest = !Array.isArray(worldsOrRequest);
-      const frameRequest = isFrameRequest ? (worldsOrRequest as RenderFrameInput) : undefined;
+      const publicationRequest =
+        isFrameRequest && 'publication' in worldsOrRequest
+          ? (worldsOrRequest as PublishedRenderFrameInput)
+          : undefined;
+      const frameRequest =
+        isFrameRequest && publicationRequest === undefined
+          ? (worldsOrRequest as RenderFrameInput)
+          : undefined;
+      let publication: PreparedRenderPublication | undefined;
+      if (publicationRequest !== undefined) {
+        if (publicationReceiver === undefined)
+          return err(
+            new RenderPublicationError({
+              reason: 'identity',
+              subject: 'RendererOptions.publicationSource',
+            }),
+          );
+      } else if (publicationReceiver !== undefined) {
+        return err(
+          new RenderPublicationError({
+            reason: 'identity',
+            subject: 'a publication-bound renderer cannot consume local World leases',
+          }),
+        );
+      }
       const worlds: readonly World[] =
         frameRequest !== undefined
           ? frameRequest.leases
               .map((lease) => attachedLeases.get(lease))
               .filter((world): world is World => world !== undefined)
-          : (worldsOrRequest as readonly World[]);
+          : publicationRequest === undefined
+            ? (worldsOrRequest as readonly World[])
+            : [];
       const readLeases: readonly RenderReadLease[] | undefined =
         frameRequest !== undefined
           ? frameRequest.leases
@@ -3212,8 +3165,18 @@ async function makeWebGPURenderer(
               ...(frameRequest.profileFrame === undefined
                 ? {}
                 : { profileFrame: frameRequest.profileFrame }),
+              ...(frameRequest.geometryLane === undefined
+                ? {}
+                : { geometryLane: frameRequest.geometryLane }),
             }
-          : (options ?? { cameraOwner: 0, resourceOwner: 0 });
+          : publicationRequest === undefined
+            ? (options ?? { cameraOwner: 0, resourceOwner: 0 })
+            : {
+                cameraOwner: 0,
+                resourceOwner: 0,
+                sampleTimeSeconds: publicationRequest.publication.sampleTimeSeconds,
+                temporalReset: publicationRequest.publication.temporalReset,
+              };
       // feat-20260612-rhi-destroy-renderer-dispose-gpu-lifecycle / M5 / w21
       // (plan-strategy D-1, D-8): post-dispose the renderer is dead. AI
       // users observing `result.ok === false && err.code === 'rhi-not-
@@ -3239,6 +3202,8 @@ async function makeWebGPURenderer(
           }),
         );
       }
+      const canvasSizeError = rejectZeroCanvasSize(internals.canvas.width, internals.canvas.height);
+      if (canvasSizeError !== undefined) return err(canvasSizeError);
       // M2 / w9 (A-IN-5): device-lost guard — draw() silently returns err
       // without firing onError each frame. The device-lost channel fires once
       // through the dual-channel fan-out (:750-797); draw() does not repeat it
@@ -3287,7 +3252,8 @@ async function makeWebGPURenderer(
       // are non-exclusive: an empty array short-circuits to empty-worlds. The
       // check is defensive against JS callers passing a non-array despite the
       // compile-time World[] type (red-window migration safety).
-      const worldCount = Array.isArray(worlds) ? worlds.length : 0;
+      const worldCount =
+        publicationRequest === undefined ? (Array.isArray(worlds) ? worlds.length : 0) : 1;
       if (worldCount === 0 && internals.device.caps.backendKind === 'null') {
         return ok(undefined);
       }
@@ -3309,12 +3275,27 @@ async function makeWebGPURenderer(
         internals.errorRegistry,
       );
       if (!contextConfigured.ok) return contextConfigured;
-      renderTargetHost.beginFrame();
       // w24 — facade-level try/catch produces Result.err on unexpected throw
       // (D-P6 dual-channel preserved: per-stage RhiError continues to fan out
       // through onError separately; the facade Result is the synchronous
       // summary AI users can ignore or branch on).
       try {
+        if (publicationRequest !== undefined && publicationReceiver !== undefined) {
+          const accepted = publicationReceiver.accept(publicationRequest.publication);
+          if (!accepted.ok) return accepted;
+          publicationTargets ??= new RenderPublicationTargetReceiver(renderTargetHost);
+          publication = {
+            ...publicationTargets.apply(accepted.value),
+            ...(publicationRequest.onFeatureSourceSubmitted === undefined
+              ? {}
+              : {
+                  onFeatureSourceSubmitted: publicationRequest.onFeatureSourceSubmitted,
+                }),
+          };
+          installPublicationPrograms(assets, publicationRequest.publication.programs);
+        }
+        renderTargetHost.beginFrame();
+
         const timingHost = internals as WebGPURendererInternals & {
           gpuPassTimingFrameIdentity?:
             | {
@@ -3352,7 +3333,13 @@ async function makeWebGPURenderer(
             graphGeneration: 0,
           };
         }
-        const submitted = renderSystem.draw(worlds, drawOptions, readLeases, volumeTimingCapture);
+        const submitted = renderSystem.draw(
+          worlds,
+          drawOptions,
+          readLeases,
+          volumeTimingCapture,
+          publication,
+        );
         timingHost.observationFrameId = undefined;
         timingHost.observationCaptureDomains = undefined;
         timingHost.gpuPassTimingFrameIdentity = undefined;
@@ -3400,34 +3387,30 @@ async function makeWebGPURenderer(
           );
         const continuation = createContinuationTerminator();
         frameContinuations.add(continuation);
-        const guardedCompletion = completion.then(
+        const guardedCompletion = guardFrameCompletion(
+          completion,
+          () => continuation.guard('queue-completion'),
           () =>
-            continuation.guard('queue-completion')
-              ? ok(undefined)
-              : err(
-                  new RendererOperationError('device-operation-failed', {
-                    operation: 'complete-frame',
-                    frameId: receiptFrameId,
-                    deviceGeneration: receiptGeneration,
-                    cause: structuredRendererCause(
-                      {
-                        code: 'stale-generation',
-                        expected: 'frame completion belongs to its device generation',
-                        hint: 'discard the stale receipt',
-                      },
-                      'complete-frame',
-                    ),
-                  }),
-                ),
+            new RendererOperationError('device-operation-failed', {
+              operation: 'complete-frame',
+              frameId: receiptFrameId,
+              deviceGeneration: receiptGeneration,
+              cause: structuredRendererCause(
+                {
+                  code: 'stale-generation',
+                  expected: 'frame completion belongs to its device generation',
+                  hint: 'discard the stale receipt',
+                },
+                'complete-frame',
+              ),
+            }),
           (cause: unknown) =>
-            err(
-              new RendererOperationError('device-operation-failed', {
-                operation: 'complete-frame',
-                frameId: receiptFrameId,
-                deviceGeneration: receiptGeneration,
-                cause: structuredRendererCause(cause, 'complete-frame'),
-              }),
-            ),
+            new RendererOperationError('device-operation-failed', {
+              operation: 'complete-frame',
+              frameId: receiptFrameId,
+              deviceGeneration: receiptGeneration,
+              cause: structuredRendererCause(cause, 'complete-frame'),
+            }),
         );
         const terminated = continuation.promise().then((reason) =>
           err(
@@ -3455,12 +3438,17 @@ async function makeWebGPURenderer(
         });
         const captures = observationCaptureOwner.consume(receiptFrameId);
         pendingObservationDomains = undefined;
-        const receiptGraphGeneration = timingHost.observationGraphGeneration ?? 0;
+        const receiptGraphGeneration =
+          timingHost.observationGraphGeneration ?? renderSystem.perFrameGraphInfo?.generation ?? 0;
         const receipt = Object.freeze({
           frameId: receiptFrameId,
           deviceGeneration: receiptGeneration,
+          presentation: renderSystem.presentation,
           backendId: internals.device.caps.backendKind,
           graphGeneration: receiptGraphGeneration,
+          ...(renderSystem.lastSuccessfulBarrelDistortion === undefined
+            ? {}
+            : { barrelDistortion: renderSystem.lastSuccessfulBarrelDistortion }),
           completed,
         });
         renderTargetHost.onFrameSubmitted(completed);
@@ -3550,6 +3538,10 @@ async function makeWebGPURenderer(
         });
         internals.errorRegistry.fire(e);
         return err(e);
+      } finally {
+        // Native video pixels have been consumed by synchronous queue copy calls.
+        // Release them on every success/failure path, including direct publication users.
+        publicationReceiver?.releaseVideoFrames();
       }
     },
     async observe(
@@ -3792,6 +3784,7 @@ async function makeWebGPURenderer(
       disposed = true;
       for (const world of attachedWorlds) dynamicGeometryHost.invalidateDynamicGeometryWorld(world);
       dynamicGeometry.dispose();
+      publicationReceiver?.dispose();
       for (const continuation of frameContinuations) {
         continuation.terminate({ code: 'disposed' });
       }
@@ -3802,11 +3795,6 @@ async function makeWebGPURenderer(
       }
       for (const world of attachedWorlds) {
         try {
-          const derivedSystemName = derivedSystemNames.get(world);
-          if (derivedSystemName !== undefined) {
-            world.removeSystem(Update, derivedSystemName);
-            derivedSystemNames.delete(world);
-          }
           transformReleases.get(world)?.();
           transformReleases.delete(world);
         } catch (cause) {
@@ -4055,6 +4043,8 @@ async function makeWebGPURenderer(
     setCandidateEmptyPostProcessBgl(layout) {
       candidateEmptyPostProcessBgl = layout;
     },
+    getShaderModuleAdapter,
+    getImmediateShaderModuleAdapter,
     getShader,
     assets,
     adaptMipmapShaderModuleFactory,