@forgeax/engine-render 0.1.2

package/src/record/main-pass-material.ts

@@ -0,0 +1,716 @@
+// @forgeax/engine-runtime - RenderSystem record stage: main-pass-material.
+// Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
+
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import {
+  VIDEO_ELEMENT_PROVIDER_KEY,
+  type VideoElementProvider,
+} from '@forgeax/engine-graphics-extras';
+import {
+  type BindGroup,
+  type BindGroupEntry,
+  type BindGroupLayout,
+  type Buffer,
+  err,
+  ok,
+  type RenderPipeline,
+  type Result,
+  RhiError,
+  type Sampler,
+} from '@forgeax/engine-rhi';
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import type {
+  DerivedMaterialInterface,
+  Handle,
+  ImageError,
+  MaterialRenderState,
+  PassKind,
+  PrimitiveTopology,
+  SamplerAsset,
+  TextureAsset,
+} from '@forgeax/engine-types';
+import { derive, handleSlot } from '@forgeax/engine-types';
+import { resolveRenderAsset } from '../assets/resolve-render-asset';
+import type { DynamicTextureStore } from '../dynamic-texture-store';
+import { VideoUploadUnsupportedError } from '../errors/render';
+import type { GpuResourceStore } from '../gpu-resource-store';
+import {
+  assembleMaterialWithSkylightEntries,
+  type SkylightBindGroupResources,
+} from '../ibl/skylight-bind-group';
+import type { PipelineState, RenderSystemRuntime } from '../render-system';
+import type { MaterialSnapshot } from '../render-system-extract';
+import type { MaterialRenderProjection } from '../renderer/material/assembly.js';
+import {
+  type MaterialDrawRoute,
+  type MaterialPipelineMiss,
+  type MaterialPipelineReady,
+  type MaterialReadiness,
+  type MaterialRenderReady,
+  routeMaterialDraw,
+  routeMaterialPipeline,
+} from '../renderer/material/pipeline-projection.js';
+import type { BindGroupCounts, MaterialBgAssemblyCacheEntry } from './frame-snapshot';
+import { derivedParamSchema } from './material-payload';
+
+const DEFAULT_STANDARD_PBR_DERIVED_INTERFACE = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
+
+export {
+  applyParamSnapshotToUbo,
+  writeMaterialSnapshotPayload,
+} from './material-payload';
+
+import { extractEntryResourceHandle, getOrCreatePerEntity } from './mesh-ssbo';
+
+// feat-20260601-customizable-render-pipeline-seam M2 / w12: the former
+// `RecordPassContext` (26-field full surface, including the `internals` kitchen-sink and
+// the 0-consumed `skyboxCount` residual) is DELETED. The per-frame shared state injected
+// into the render-graph pass execute closures is now the clean `RenderPipelineContext`
+// (defined in `render-pipeline-context.ts`): `internals` is gone (replaced by the named
+// `assets` / `store` / `pipelineState` / `runtime` surfaces) so a pipeline author cannot
+// reach the runtime kitchen-sink through the public ctx (AC-08). The graph is
+// `RenderGraph<RenderPipelineContext>` so `execute(ctx)` forwards the object to each
+// closure with no `as` assertion.
+//
+// Encoder ownership (RD-4): `ctx.encoder` is the SHARED frame encoder used by the main /
+// tonemap / FXAA passes (finished + submitted once at frame end); the shadow pass opens
+// its OWN encoder internally + submits independently (the runtime-side manual barrier for
+// the depth write -> sample hazard).
+
+// M1 / w7: ensureLazyTexture DELETED — GPU texture ownership moved to render-graph
+// via addColorTarget + compile(device). The graph allocates transient/persistent
+// render targets during the compile allocation phase; pass execute closures resolve
+// TextureViews through resolve(name). PerPassResources texture slots still hold
+// the last-used views for bindgroup-invalidation self-checks (D-3 physical texture
+// identity), but the graph owns the create/destroy lifecycle.
+
+/**
+ * feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w9: pick the static
+ * unlit geometry pipeline handle for a (tonemapActive x msaaActive)
+ * combination. The four mode axes (LDR/HDR x single/MSAA) map to the 14 static
+ * pipeline handles built in createRenderer (7 base + 7 count=4 variants). A
+ * pipeline's `multisample.count` must match the colour-attachment sampleCount,
+ * so the count=4 variant is required whenever the camera carries
+ * `antialias === 'msaa'`. Returns null when the requested pipeline was not
+ * built (empty-manifest path / MSAA variant build failure) -- the caller fires
+ * a structured `shader-compile-failed` on the null-narrow.
+ */
+// feat-20260615-pipeline-spec-ssot M6-T1: the standard-shading fallback
+// selector was deleted. The pre-M6 selector silently substituted the
+// boot-time URP `pipelineState.standardPipeline*` whenever the per-
+// MaterialShader cache returned null and HDRP was inactive -- masking
+// real PipelineSpecError build failures behind a layout-compatible-but-
+// wrong PSO. Charter P3 explicit-failure now governs: a missing cache
+// entry surfaces as null, and the per-submesh
+// `if (smPipelineHandle === null) continue` skip-draw (which already
+// covered the HDRP-active and skin-shader miss-skip paths) is the single
+// uniform recovery shape across URP / HDRP / skin.
+
+export function selectGeometryPipeline(
+  pipelineState: PipelineState,
+  tonemapActive: boolean,
+  msaaActive: boolean,
+): RenderPipeline | null {
+  if (tonemapActive) {
+    return msaaActive ? pipelineState.unlitPipelineHdrMsaa : pipelineState.unlitPipelineHdr;
+  }
+  return msaaActive ? pipelineState.unlitPipelineMsaa : pipelineState.unlitPipeline;
+}
+
+/**
+ * Resolve a cooked material projection for record. The record stage receives
+ * the already-resolved projection and an immutable artifact lookup; it never
+ * follows parent GUIDs, reads authored material state, or invokes a compiler.
+ * A missing or mismatched artifact is an explicit route miss so callers cannot
+ * silently substitute a default shader.
+ */
+export function selectCookedMaterialPipelineForRender(args: {
+  readonly projection: MaterialRenderProjection;
+  readonly lookupArtifact: (
+    key: string,
+  ) => import('@forgeax/engine-shader').MaterialRuntimeArtifact | undefined;
+}): MaterialPipelineReady | MaterialPipelineMiss {
+  return routeMaterialPipeline(args);
+}
+
+/** Route a record-stage draw through the canonical readiness result. */
+export function selectMaterialDrawForRender<TPipeline>(args: {
+  readonly readiness: MaterialReadiness;
+  readonly buildPipeline: (ready: MaterialRenderReady) => TPipeline;
+  readonly reportedDiagnosticKeys: Set<string>;
+}): MaterialDrawRoute<TPipeline> {
+  return routeMaterialDraw(args);
+}
+
+/**
+ * feat-city-glb Bug 5 (per-submesh transparency): true when EVERY submesh
+ * material of the entity is transparent (blend). Used by the geometry pass to
+ * decide whether to skip the whole entity (fully transparent → deferred to the
+ * blend sub-pass) vs. draw its opaque submeshes and skip only the transparent
+ * ones per-submesh.
+ *
+ * Falls back to the entity-level `material.transparent` when `materials` is
+ * absent (single-material entities / test fixtures), byte-identical to the
+ * pre-fix whole-entity gate.
+ *
+ * @internal
+ */
+export function isEntityFullyTransparent(source: {
+  readonly material: MaterialSnapshot;
+  readonly materials?: readonly MaterialSnapshot[];
+}): boolean {
+  const mats = source.materials;
+  if (mats === undefined || mats.length === 0) return source.material.transparent === true;
+  for (let j = 0; j < mats.length; j++) {
+    if (mats[j]?.transparent !== true) return false;
+  }
+  return true;
+}
+
+/**
+ * feat-city-glb Bug 5: true when the entity has at least one transparent AND at
+ * least one opaque submesh — i.e. it must be drawn in BOTH the geometry pass
+ * (opaque submeshes) and the blend sub-pass (transparent submeshes). A pure-
+ * opaque or pure-transparent entity returns false (handled by the whole-entity
+ * fast paths).
+ *
+ * @internal
+ */
+export function entityHasTransparentSubmesh(source: {
+  readonly material: MaterialSnapshot;
+  readonly materials?: readonly MaterialSnapshot[];
+}): boolean {
+  const mats = source.materials;
+  if (mats === undefined) return source.material.transparent === true;
+  for (let j = 0; j < mats.length; j++) {
+    if (mats[j]?.transparent === true) return true;
+  }
+  return false;
+}
+
+/**
+ * Selects the PSO for a transparent (or any generic materialShaderId) draw
+ * via the runtime's per-MaterialShader pipeline cache. Returns a
+ * structured RhiError on cache miss / pending build -- the caller MUST
+ * surface this via the error registry rather than substituting a silent
+ * fallback (charter P3 explicit failure).
+ *
+ * The `getMaterialShaderPipeline` argument mirrors
+ * {@link RenderSystemRuntime.getMaterialShaderPipeline}'s 9-arg signature
+ * but is injected so the helper is unit-testable with a plain
+ * `() => null` stand-in. The helper threads only the inputs the caller
+ * already has on the dispatch entry -- it never reads from
+ * MaterialAsset internals (plan-strategy section 5.6 gate R-H).
+ *
+ * @internal
+ */
+export function selectMaterialPipelineForRender(args: {
+  readonly materialShaderId: string;
+  readonly isHdr: boolean;
+  readonly renderState?: MaterialRenderState | undefined;
+  readonly topology?: PrimitiveTopology | undefined;
+  readonly indexFormat?: 'uint16' | 'uint32' | undefined;
+  readonly variantSet?: string | undefined;
+  readonly sampleCount?: number | undefined;
+  readonly getMaterialShaderPipeline:
+    | ((
+        materialShaderId: string,
+        isHdr: boolean,
+        renderState?: MaterialRenderState,
+        topology?: PrimitiveTopology,
+        indexFormat?: 'uint16' | 'uint32',
+        variantSet?: string,
+        passKind?: PassKind,
+        meshAttributes?: import('@forgeax/engine-types').VertexAttributeMap,
+        sampleCount?: number,
+      ) => RenderPipeline | null)
+    | undefined;
+}): Result<RenderPipeline, RhiError> {
+  if (args.getMaterialShaderPipeline === undefined) {
+    return err(
+      new RhiError({
+        code: 'internal-error',
+        expected: `runtime.getMaterialShaderPipeline registered before draw of ${args.materialShaderId}`,
+        hint: `material shader ${args.materialShaderId} has no resolver; the renderer was not initialised with a pipeline cache`,
+      }),
+    );
+  }
+  const pipeline = args.getMaterialShaderPipeline(
+    args.materialShaderId,
+    args.isHdr,
+    args.renderState,
+    args.topology,
+    args.indexFormat,
+    args.variantSet,
+    undefined, // passKind defaults to 'forward'
+    undefined, // meshAttributes -- transparent path uses the default vertex layout
+    args.sampleCount,
+  );
+  if (pipeline === null) {
+    return err(
+      new RhiError({
+        code: 'internal-error',
+        expected: `pipeline cache hit for ${args.materialShaderId} (renderState=${args.renderState ? 'set' : 'unset'}, isHdr=${args.isHdr})`,
+        hint: `material shader pipeline ${args.materialShaderId} missed the runtime cache; the underlying shader-module build may still be pending, or the id is not registered in ShaderRegistry`,
+      }),
+    );
+  }
+  return ok(pipeline);
+}
+
+// === end feat-20260625 M2 / w7 transparent-aware helpers ========================
+
+/**
+ * feat-20260601-gpu-resource-store-extraction M1 / D-9: resolve a texture's
+ * GPU view through the pull-model residency store. The three steps replace the
+ * pre-extraction single-call accessor on the registry:
+ *   1. fetch the TextureAsset POD off the registry (CPU; registry keeps PODs)
+ *   2. synchronously `ensureResident(handle, pod)` (first access builds the
+ *      GPU texture + prewarmed mipmap blit; subsequent access is O(1))
+ *   3. return the GPU view (or undefined on POD miss / ensureResident err)
+ *
+ * Returns `undefined` when the POD is absent (handle never registered) or the
+ * upload fails (a structured error is fired). Callers then fall back to their
+ * existing placeholder view, preserving the pre-extraction fallback semantics.
+ */
+function isImageError(error: unknown): error is ImageError {
+  if (typeof error !== 'object' || error === null) return false;
+  const code = (error as { readonly code?: unknown }).code;
+  return typeof code === 'string' && code.startsWith('image-');
+}
+
+export function residentTextureView(
+  world: World,
+  store: GpuResourceStore,
+  runtime: RenderSystemRuntime,
+  handle: Handle<'TextureAsset', 'shared'>,
+  worldId: number = 0,
+  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture-view return
+): any | undefined {
+  const podRes = resolveRenderAsset<TextureAsset>(world, handle);
+  if (!podRes.ok) return undefined;
+  const residentRes = store.ensureResident(handle, podRes.value, worldId);
+  if (!residentRes.ok) {
+    // Preserve the concrete asset-capability boundary on the renderer error
+    // channel. In particular, WebGL2 texture-dimension refusal must not
+    // collapse into the later debug-pink asset-not-registered fallback.
+    if (residentRes.error instanceof RhiError || isImageError(residentRes.error)) {
+      runtime.errorRegistry.fire(residentRes.error);
+    }
+    return undefined;
+  }
+  return store.getTextureGpuView(handle, worldId);
+}
+
+function residentSampler(
+  world: World,
+  store: GpuResourceStore,
+  runtime: RenderSystemRuntime,
+  handle: Handle<'SamplerAsset', 'shared'>,
+): Sampler | undefined {
+  const podRes = resolveRenderAsset<SamplerAsset>(world, handle);
+  if (!podRes.ok) return undefined;
+  const residentRes = store.ensureSamplerResident(handle, podRes.value);
+  if (!residentRes.ok) {
+    runtime.errorRegistry.fire(residentRes.error);
+    return undefined;
+  }
+  return residentRes.value;
+}
+
+// feat-20260623-world-space-video-asset M4 / w16 (D-3): resolve the
+// current-frame GPU view for a video-sourced texture field through the
+// transient DynamicTextureStore, NOT the static `residentTextureView` /
+// `ensureResident` cache (video never enters that switch; AC-08).
+//
+// Per frame: ask the host-registered VideoElementProvider (World Resource,
+// D-1) for this entity's HTMLVideoElement, upload its current frame via
+// `store.uploadFrame` (copyExternalImageToTexture), and return the resulting
+// view. When the provider is absent / returns no element / the element has no
+// decodable dimensions yet, fall back to any previously-uploaded view and
+// finally to `undefined` (caller binds the default view this frame — charter
+// P3 graceful, no garbage sampling). A failed GPU upload fires the structured
+// RhiError on the engine channel and degrades to the default view.
+//
+// `highPerfAvailable` is the w17 capability probe; the high-perf
+// GPUExternalTexture branch is a reserved hook (OOS-5) — when it ever becomes
+// available the upload would route there. Today it is always false so the
+// general copyExternalImageToTexture path is the only one taken.
+type VideoUploadFailureEpisodes = Map<number, Set<number>>;
+
+// The store is renderer-owned, so this keeps one failure episode per
+// renderer/entity/clip without creating a second video system or leaking
+// state across a replacement renderer.
+const VIDEO_UPLOAD_FAILURE_EPISODES = new WeakMap<
+  DynamicTextureStore,
+  VideoUploadFailureEpisodes
+>();
+
+function markVideoUploadFailureEpisode(
+  store: DynamicTextureStore,
+  entityKey: number,
+  clip: Handle<'VideoAsset', 'shared'>,
+): boolean {
+  let clips = VIDEO_UPLOAD_FAILURE_EPISODES.get(store);
+  if (clips === undefined) {
+    clips = new Map();
+    VIDEO_UPLOAD_FAILURE_EPISODES.set(store, clips);
+  }
+  let episodes = clips.get(entityKey);
+  if (episodes === undefined) {
+    episodes = new Set();
+    clips.set(entityKey, episodes);
+  }
+  const clipId = handleSlot(clip);
+  if (episodes.has(clipId)) return false;
+  episodes.add(clipId);
+  return true;
+}
+
+function clearVideoUploadFailureEpisode(
+  store: DynamicTextureStore,
+  entityKey: number,
+  clip: Handle<'VideoAsset', 'shared'>,
+): void {
+  const clips = VIDEO_UPLOAD_FAILURE_EPISODES.get(store);
+  const episodes = clips?.get(entityKey);
+  if (episodes === undefined) return;
+  episodes.delete(handleSlot(clip));
+  if (episodes.size === 0) clips?.delete(entityKey);
+  if (clips?.size === 0) VIDEO_UPLOAD_FAILURE_EPISODES.delete(store);
+}
+
+export function videoTextureView(
+  world: World,
+  store: DynamicTextureStore | undefined,
+  runtime: RenderSystemRuntime,
+  entityKey: number,
+  clip: Handle<'VideoAsset', 'shared'>,
+  highPerfAvailable: boolean,
+  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture-view return
+): any | undefined {
+  if (store === undefined) return undefined;
+  const provider = world.hasResource(VIDEO_ELEMENT_PROVIDER_KEY)
+    ? world.getResource<VideoElementProvider>(VIDEO_ELEMENT_PROVIDER_KEY)
+    : undefined;
+  const element = provider?.getElement(entityKey as unknown as EntityHandle, clip);
+  // AC-10 double-miss: a VideoPlayer entity can reach NEITHER upload path this
+  // frame — no host HTMLVideoElement (general copyExternalImageToTexture path)
+  // AND no high-perf GPUExternalTexture path. This is the genuine "this backend
+  // exposes no usable video upload path" case (no provider registered, or the
+  // provider yields nothing while the high-perf reserved hook is unavailable —
+  // OOS-5 keeps it always false today). Rather than silently binding the
+  // default view, fire the structured VideoUploadUnsupportedError on the engine
+  // error channel so an AI user can detect the dead path via `.code` / `.hint`
+  // (charter P3; AC-10 signal lives on the REAL per-frame upload path, not an
+  // orphan system). The default view is still bound this frame so the draw
+  // does not crash (graceful degradation), but the failure is no longer silent.
+  if (element === undefined && !highPerfAvailable) {
+    if (markVideoUploadFailureEpisode(store, entityKey, clip)) {
+      runtime.errorRegistry.fire(new VideoUploadUnsupportedError());
+    }
+    return store.getView(clip);
+  }
+  // D-2 / w17 high-perf reserved hook: a future GPUExternalTexture import path
+  // would key off `highPerfAvailable` here. It is always false today
+  // (importExternalTexture absent), so the general copyExternalImageToTexture
+  // path below is the sole route end-to-end.
+  if (element === undefined) {
+    clearVideoUploadFailureEpisode(store, entityKey, clip);
+    return store.getView(clip);
+  }
+  const width = element.videoWidth;
+  const height = element.videoHeight;
+  // Metadata dimensions can be non-zero before the decoder has produced a
+  // current frame. WebGPU rejects copyExternalImageToTexture in that window
+  // because the video element has no back resource yet; keep the previous
+  // frame/default view until HAVE_CURRENT_DATA (2) is reached.
+  if (width <= 0 || height <= 0 || element.readyState < 2) return store.getView(clip);
+  const uploaded = store.uploadFrame(clip, element, width, height);
+  if (uploaded === undefined) return store.getView(clip);
+  if (!uploaded.ok) {
+    runtime.errorRegistry.fire(uploaded.error);
+    return store.getView(clip);
+  }
+  clearVideoUploadFailureEpisode(store, entityKey, clip);
+  return uploaded.value;
+}
+
+/**
+ * feat-20260621-learn-render-5-5-parallax M2 / w8 (D-3): ordered user-region
+ * texture field names for a material's bind-group assembly, derived from the
+ * shader's paramSchema via the `derive()` SSOT (insertion order = sampler/
+ * texture pair order in derive().bglEntries). An unavailable schema yields no
+ * inferred layout fields.
+ */
+export function userRegionTextureFieldOrder(
+  projection: DerivedMaterialInterface | undefined,
+): readonly string[] {
+  if (projection === undefined) return [];
+  return [...projection.textureFieldNames];
+}
+
+/**
+ * feat-20260621-learn-render-5-5-parallax M2 / w8: the fallback texture view
+ * for a user-region field when no handle is provided (graceful, charter P3).
+ * normalTexture decodes to a flat tangent normal; everything else (baseColor,
+ * MR, height, ...) uses the 1x1 white default (height white -> zero displacement).
+ */
+export function defaultViewForUserRegionField(
+  field: string,
+  pipelineState: PipelineState,
+  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture-view
+): any {
+  if (field === 'normalTexture') return pipelineState.defaultNormalTextureView;
+  if (field === 'baseColorTexture') return pipelineState.fallbackTextureView;
+  return pipelineState.defaultWhiteTextureView;
+}
+
+/**
+ * feat-20260527-sprite-nineslice M4 / w17 (AC-16): once-per-renderable
+ * detection of "Transform.scale below the four 9-slice corner anchors". Pure
+ * helper extracted out of recordFrame so unit tests can drive it without a
+ * GPU device — the recordFrame loop calls this with its `transformWorld` /
+ * `slices` / `renderableIndex` / `seenIndices` / `metrics` arguments.
+ *
+ * The scale-vs-anchor formula mirrors plan-strategy §D-3 — the world x scale must
+ * accommodate `|slices.x| + |slices.z|`, and `scaleY` must accommodate
+ * `|slices.y| + |slices.w|`. Slices ≡ all zero is a no-op (legacy quad
+ * path); a breach increments `nineslice.scale-too-small` exactly once per
+ * `renderableIndex` per RenderSystem lifetime via the `seenIndices` Set
+ * (the same warn-once anchor pattern used for missing-texture sprites).
+ *
+ * @param transformWorld The entity's resolved Transform.world mat4 (16 floats column-major).
+ * @param slices         The four anchor distances `[left, top, right, bottom]`
+ *                       (sentinel `bottom < 0` for tile mode is consumed via abs()).
+ * @param renderableIndex The entity index into the validated renderables list.
+ * @param seenIndices    The per-frame-state guard Set; entries are added on increment.
+ * @param metrics        The per-Renderer EngineMetrics counter.
+ * @internal — exported for unit-test access (w17).
+ */
+export function detectNineSliceScaleTooSmall(
+  transformWorld: Float32Array,
+  slices: readonly [number, number, number, number],
+  renderableIndex: number,
+  seenIndices: Set<number>,
+  metrics: { increment(name: string): void },
+): void {
+  const anyNonZero = slices[0] !== 0 || slices[1] !== 0 || slices[2] !== 0 || slices[3] !== 0;
+  if (!anyNonZero) return;
+  const sx = Math.hypot(transformWorld[0] ?? 1, transformWorld[1] ?? 0, transformWorld[2] ?? 0);
+  const sy = Math.hypot(transformWorld[4] ?? 0, transformWorld[5] ?? 1, transformWorld[6] ?? 0);
+  const horizontalAnchor = Math.abs(slices[0]) + Math.abs(slices[2]);
+  const verticalAnchor = Math.abs(slices[1]) + Math.abs(slices[3]);
+  if (sx < horizontalAnchor || sy < verticalAnchor) {
+    if (!seenIndices.has(renderableIndex)) {
+      seenIndices.add(renderableIndex);
+      metrics.increment('nineslice.scale-too-small');
+    }
+  }
+}
+
+/**
+ * feat-20260704 M3/w19: shared per-submesh material bind-group assembly, hoisted
+ * from the `buildPerSubmeshMaterialBg` closure inside recordMainPass so both the
+ * geometry pass and the LDR blend sub-pass (extracted to separate functions)
+ * call the identical layout.
+ *
+ * feat-city-glb Bug 5 (per-submesh transparency): a transparent PBR submesh
+ * binds the identical metallic/roughness/normal/emissive/occlusion +
+ * Skylight layout the geometry pass uses (the sub-pass previously bound a
+ * sprite-only BG, which cannot render a PBR decal). The per-frame closure state
+ * (runtime / pipelineState / world / store / skylightResources / the shared
+ * material BG cache + counters) is threaded through `deps`; the caller passes
+ * the per-submesh material snapshot + entityKey (video texture routing) and sets
+ * the dynamic UBO offset itself.
+ *
+ * @internal
+ */
+export interface PerSubmeshMaterialBgDeps {
+  readonly runtime: RenderSystemRuntime;
+  readonly pipelineState: PipelineState;
+  readonly world: World;
+  readonly store: GpuResourceStore;
+  readonly materialSlice: number;
+  readonly videoHighPerfAvailable: boolean;
+  readonly skylightResources: SkylightBindGroupResources;
+  readonly materialBgShared: Map<string, WeakMap<object, unknown>>;
+  /** Cross-frame final BG reuse keyed by the stable source material handle. */
+  readonly materialBgAssemblyCache: Map<number, MaterialBgAssemblyCacheEntry>;
+  readonly bindGroupCounts: BindGroupCounts;
+}
+
+/** @internal Exported only so buffer-generation invalidation stays regression-tested. */
+export function isMaterialBgAssemblyCacheHit(
+  cached: MaterialBgAssemblyCacheEntry | undefined,
+  material: MaterialSnapshot,
+  materialBgl: BindGroupLayout,
+  materialBuffer: Buffer,
+  skylightResources: SkylightBindGroupResources,
+  materialResourceEpoch: number,
+): cached is MaterialBgAssemblyCacheEntry {
+  return (
+    cached?.material === material &&
+    cached.materialResourceEpoch === materialResourceEpoch &&
+    cached.materialBgl === materialBgl &&
+    cached.materialBuffer === materialBuffer &&
+    cached.skylightResources.irradianceView === skylightResources.irradianceView &&
+    cached.skylightResources.irradianceSampler === skylightResources.irradianceSampler &&
+    cached.skylightResources.prefilterView === skylightResources.prefilterView &&
+    cached.skylightResources.prefilterSampler === skylightResources.prefilterSampler &&
+    cached.skylightResources.brdfLutView === skylightResources.brdfLutView &&
+    cached.skylightResources.brdfLutSampler === skylightResources.brdfLutSampler &&
+    cached.skylightResources.intensityBuffer === skylightResources.intensityBuffer
+  );
+}
+
+export function buildPerSubmeshMaterialBg(
+  deps: PerSubmeshMaterialBgDeps,
+  submeshMaterial: MaterialSnapshot,
+  entityKey: number,
+): BindGroup {
+  const {
+    runtime,
+    pipelineState,
+    world,
+    store,
+    materialSlice,
+    videoHighPerfAvailable,
+    skylightResources,
+    materialBgShared,
+    materialBgAssemblyCache,
+    bindGroupCounts,
+  } = deps;
+  const smMaterialHandle = submeshMaterial.materialHandle;
+  const smHasVideoFields = (submeshMaterial.videoTextureFields?.size ?? 0) > 0;
+  const smShaderId = submeshMaterial.materialShaderId;
+  const smPerShaderBgl =
+    smShaderId !== undefined ? runtime.getMaterialBindGroupLayout?.(smShaderId) : undefined;
+  const usesSharedPbrMaterialLayout = smPerShaderBgl === undefined;
+  const smMaterialBgl = smPerShaderBgl ?? pipelineState.materialBindGroupLayout;
+  if (smMaterialHandle !== undefined && !smHasVideoFields) {
+    const cached = materialBgAssemblyCache.get(smMaterialHandle);
+    if (
+      isMaterialBgAssemblyCacheHit(
+        cached,
+        submeshMaterial,
+        smMaterialBgl,
+        pipelineState.materialUniformBuffer.buffer,
+        skylightResources,
+        store.materialResourceEpoch,
+      )
+    ) {
+      return cached.bindGroup;
+    }
+  }
+  const smRegisteredProjection =
+    !usesSharedPbrMaterialLayout && smShaderId !== undefined
+      ? runtime.getParamSchemaProjection?.(smShaderId)
+      : undefined;
+  const smSchema = usesSharedPbrMaterialLayout
+    ? DEFAULT_STANDARD_PBR_PARAM_SCHEMA
+    : (smRegisteredProjection?.schema ??
+      (smShaderId !== undefined ? runtime.getParamSchema?.(smShaderId) : undefined) ??
+      submeshMaterial.materialParamSchema);
+  // The bind-group layout and its uniform range must share one schema owner.
+  // Authored built-in materials may declare only a compact subset, while the
+  // shared PBR pipeline still consumes the full standard schema.
+  const smProjection = usesSharedPbrMaterialLayout
+    ? DEFAULT_STANDARD_PBR_DERIVED_INTERFACE
+    : (submeshMaterial.derivedMaterialSlot?.derivedInterface ??
+      smRegisteredProjection?.derivedInterface ??
+      (smSchema === undefined
+        ? undefined
+        : derivedParamSchema(smSchema, runtime.paramSchemaProjectionCensus)));
+  const smMaterialByteLength = smProjection?.totalBytes || materialSlice;
+  const smUserRegionFields = userRegionTextureFieldOrder(smProjection);
+  let materialResourcesResident = true;
+  const smSamplerForField = (field: string | undefined): Sampler => {
+    const handle = field === undefined ? undefined : submeshMaterial.samplerHandles?.get(field);
+    if (handle === undefined) return pipelineState.defaultSampler;
+    const sampler = residentSampler(world, store, runtime, handle);
+    if (sampler === undefined) materialResourcesResident = false;
+    return sampler ?? pipelineState.defaultSampler;
+  };
+  const smBaseEntries: BindGroupEntry[] = [
+    {
+      binding: 0,
+      resource: {
+        kind: 'buffer' as const,
+        value: {
+          buffer: pipelineState.materialUniformBuffer.buffer,
+          offset: 0,
+          size: smMaterialByteLength,
+        },
+      },
+    },
+  ];
+  const smBglPairCount = smUserRegionFields.length;
+  for (let fi = 0; fi < smBglPairCount; fi++) {
+    const field = smUserRegionFields[fi];
+    const samplerBinding = 1 + fi * 2;
+    const textureBinding = samplerBinding + 1;
+    let smView: unknown =
+      field !== undefined
+        ? defaultViewForUserRegionField(field, pipelineState)
+        : pipelineState.defaultWhiteTextureView;
+    const smVideoClip =
+      field !== undefined ? submeshMaterial.videoTextureFields?.get(field) : undefined;
+    if (smVideoClip !== undefined) {
+      const view = videoTextureView(
+        world,
+        runtime.dynamicTextureStore,
+        runtime,
+        entityKey,
+        smVideoClip,
+        videoHighPerfAvailable,
+      );
+      if (view !== undefined) smView = view;
+    } else {
+      const smHandle = field !== undefined ? submeshMaterial.textureHandles?.get(field) : undefined;
+      if (smHandle !== undefined) {
+        const view = residentTextureView(world, store, runtime, smHandle);
+        if (view !== undefined) smView = view;
+        else materialResourcesResident = false;
+      }
+    }
+    smBaseEntries.push(
+      {
+        binding: samplerBinding,
+        resource: { kind: 'sampler' as const, value: smSamplerForField(field) },
+      },
+      {
+        binding: textureBinding,
+        resource: { kind: 'textureView' as const, value: smView as never },
+      },
+    );
+  }
+  const smMergedEntries = assembleMaterialWithSkylightEntries(smBaseEntries, skylightResources);
+  const smBindGroup = getOrCreatePerEntity(
+    materialBgShared,
+    smShaderId ?? '',
+    smMergedEntries.map((e) => extractEntryResourceHandle(e)),
+    'material-shared',
+    () => {
+      const result = runtime.device.createBindGroup({
+        label: 'pbr-material-skylight-bg',
+        layout: smMaterialBgl,
+        entries: smMergedEntries,
+      });
+      if (!result.ok) throw result.error;
+      return result.value;
+    },
+    bindGroupCounts,
+  );
+  if (smMaterialHandle !== undefined && !smHasVideoFields && materialResourcesResident) {
+    materialBgAssemblyCache.set(smMaterialHandle, {
+      material: submeshMaterial,
+      materialResourceEpoch: store.materialResourceEpoch,
+      materialBgl: smMaterialBgl,
+      materialBuffer: pipelineState.materialUniformBuffer.buffer,
+      skylightResources,
+      bindGroup: smBindGroup,
+    });
+  }
+  return smBindGroup;
+}