@forgeax/engine-render 0.1.4 → 0.1.7

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

@@ -1,6 +1,7 @@
 // @forgeax/engine-runtime - RenderSystem record stage: main-pass-material.
 // Extracted from render-system-record.ts (feat-20260704 M3/w17, pure move).
 
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import {
   VIDEO_ELEMENT_PROVIDER_KEY,
@@ -11,62 +12,68 @@ import {
   type BindGroupEntry,
   type BindGroupLayout,
   type Buffer,
-  err,
-  ok,
   type RenderPipeline,
-  type Result,
   RhiError,
   type Sampler,
+  type TextureView,
 } from '@forgeax/engine-rhi';
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import {
+  DEFAULT_MSDF_TEXT_PARAM_SCHEMA,
+  DEFAULT_SPRITE_PARAM_SCHEMA,
+  DEFAULT_UNLIT_PARAM_SCHEMA,
+} from '@forgeax/engine-shader';
 import type {
-  DerivedMaterialInterface,
   Handle,
   ImageError,
   MaterialRenderState,
-  PassKind,
+  ParamSchemaEntry,
   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 { derive, handleSlot, resolveMaterialTextureCoordinates } from '@forgeax/engine-types';
+import type { GpuResidencyCache } from '../device/gpu-residency';
 import { VideoUploadUnsupportedError } from '../errors/render';
-import type { GpuResourceStore } from '../gpu-resource-store';
 import {
   assembleMaterialWithSkylightEntries,
+  type EmissiveAoBindGroupResources,
   type SkylightBindGroupResources,
 } from '../ibl/skylight-bind-group';
-import type { PipelineState, RenderSystemRuntime } from '../render-system';
+import { isStandardPbrMaterialShader } from '../pbr-pipeline';
+import { deriveTextureExtent } from '../render-data';
 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);
+import { extractEntryResourceHandle, getOrCreatePerEntity } from './mesh-ssbo';
+import {
+  type PipelineState,
+  type RenderSystemRuntime,
+  STANDARD_PBR_UBO_SIZE,
+} from './render-context';
 
-export {
-  applyParamSnapshotToUbo,
-  writeMaterialSnapshotPayload,
-} from './material-payload';
+// Param schemas are immutable runtime contracts: the shader registry installs
+// them once and material snapshots only retain the same array reference. Keep
+// the expensive pure derivation on that identity so the per-submesh record
+// path does not rebuild the same UBO/texture maps for every visible material
+// on every frame. A WeakMap keeps this optimization bounded by the lifetime of
+// the schema owner and adds no global strong-reference lifetime.
+const DERIVED_PARAM_SCHEMA_CACHE = new WeakMap<
+  readonly ParamSchemaEntry[],
+  ReturnType<typeof derive>
+>();
 
-import { extractEntryResourceHandle, getOrCreatePerEntity } from './mesh-ssbo';
+function derivedParamSchema(schema: readonly ParamSchemaEntry[]): ReturnType<typeof derive> {
+  const cached = DERIVED_PARAM_SCHEMA_CACHE.get(schema);
+  if (cached !== undefined) return cached;
+  const derived = derive(schema);
+  DERIVED_PARAM_SCHEMA_CACHE.set(schema, derived);
+  return derived;
+}
 
 // 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
+// (defined in `render-system.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
@@ -84,6 +91,24 @@ import { extractEntryResourceHandle, getOrCreatePerEntity } from './mesh-ssbo';
 // the last-used views for bindgroup-invalidation self-checks (D-3 physical texture
 // identity), but the graph owns the create/destroy lifecycle.
 
+/**
+ * Keep line primitives visible when they share a depth plane with filled
+ * geometry. The same topology policy is consumed by the CPU and GPU-driven
+ * raster lanes so a mixed mesh does not change appearance when ownership
+ * moves between them.
+ */
+export function geometryRenderStateForTopology(
+  topology: PrimitiveTopology,
+  renderState: MaterialRenderState | undefined,
+): MaterialRenderState | undefined {
+  if (topology !== 'line-list' && topology !== 'line-strip') return renderState;
+  return {
+    ...renderState,
+    depthWriteEnabled: false,
+    depthCompare: 'less-equal',
+  };
+}
+
 /**
  * feat-20260604-learn-render-4.10-anti-aliasing-msaa M2 / w9: pick the static
  * unlit geometry pipeline handle for a (tonemapActive x msaaActive)
@@ -117,31 +142,6 @@ export function selectGeometryPipeline(
   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
@@ -189,79 +189,7 @@ export function entityHasTransparentSubmesh(source: {
 }
 
 /**
- * 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
+ * feat-20260601-device/gpu-residency-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)
@@ -281,13 +209,12 @@ function isImageError(error: unknown): error is ImageError {
 
 export function residentTextureView(
   world: World,
-  store: GpuResourceStore,
+  store: GpuResidencyCache,
   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);
+  worldId: World | number = world,
+): TextureView | undefined {
+  const podRes = resolveAssetHandle<TextureAsset>(world, handle);
   if (!podRes.ok) return undefined;
   const residentRes = store.ensureResident(handle, podRes.value, worldId);
   if (!residentRes.ok) {
@@ -304,13 +231,14 @@ export function residentTextureView(
 
 function residentSampler(
   world: World,
-  store: GpuResourceStore,
+  store: GpuResidencyCache,
   runtime: RenderSystemRuntime,
   handle: Handle<'SamplerAsset', 'shared'>,
+  worldId: World | number = world,
 ): Sampler | undefined {
-  const podRes = resolveRenderAsset<SamplerAsset>(world, handle);
+  const podRes = resolveAssetHandle<SamplerAsset>(world, handle);
   if (!podRes.ok) return undefined;
-  const residentRes = store.ensureSamplerResident(handle, podRes.value);
+  const residentRes = store.ensureSamplerResident(handle, podRes.value, worldId);
   if (!residentRes.ok) {
     runtime.errorRegistry.fire(residentRes.error);
     return undefined;
@@ -327,7 +255,7 @@ function residentSampler(
 // 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
+// decodable dimensions yet, fall back to a 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.
@@ -336,6 +264,8 @@ function residentSampler(
 // 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 DynamicTextureStore = import('@forgeax/engine-assets-runtime').DynamicTextureStore;
+
 type VideoUploadFailureEpisodes = Map<number, Set<number>>;
 
 // The store is renderer-owned, so this keeps one failure episode per
@@ -387,13 +317,12 @@ export function videoTextureView(
   entityKey: number,
   clip: Handle<'VideoAsset', 'shared'>,
   highPerfAvailable: boolean,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture-view return
-): any | undefined {
+): TextureView | 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);
+  const element = provider?.getElement(entityKey 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
@@ -436,18 +365,193 @@ export function videoTextureView(
   return uploaded.value;
 }
 
+// feat-20260621-learn-render-5-5-parallax M2 / w8 (D-3): the built-in
+// standard-PBR user-region texture field order, used when the shader is not
+// resolvable through getParamSchema (cross-worktree late-register). Mirrors
+// derive(default-standard-pbr).textureFieldNames.
+export const BUILTIN_USER_REGION_TEXTURE_FIELDS: readonly string[] = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+];
+
+const LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET = 80;
+const STANDARD_PBR_TEXTURE_SCALE_OFFSET = 96;
+const MATERIAL_TEXTURE_SCALE_FIELDS = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+] as const;
+const LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+] as const;
+const STANDARD_PBR_TEXTURE_COORDINATE_OFFSET = 96;
+const STANDARD_PBR_TEXTURE_COORDINATE_STRIDE = 8;
+const DEFAULT_LEGACY_TEXTURE_SCALES = new Float32Array([1, 1, 1, 1, 1, 1, 1, 1, 1, 1]);
+const DEFAULT_STANDARD_TEXTURE_COORDINATES = new Float32Array([
+  0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0,
+  0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1, 0, 0, 1, 1,
+]);
+
+/** Derives the logical-content UV scale for an uploaded material texture. */
+export function materialTextureUvScale(
+  texture: Pick<TextureAsset, 'width' | 'height' | 'format'> | undefined,
+): readonly [number, number] {
+  if (texture === undefined) return [1, 1];
+  return deriveTextureExtent(texture.format, texture.width, texture.height).uvScale;
+}
+
+function materialTextureForField(
+  material: MaterialSnapshot,
+  field: string,
+): Handle<'TextureAsset', 'shared'> | undefined {
+  if (field === 'emissiveTexture') return material.emissiveTexture;
+  if (field === 'occlusionTexture') return material.occlusionTexture;
+  return material.textureHandles?.get(field);
+}
+
+/**
+ * Appends the engine-owned scale for every built-in material texture binding.
+ * Asset dimensions remain logical; this is the sole record-stage projection
+ * from a bound texture asset to its shader sampling coordinates.
+ */
+type MaterialUboPayload = ArrayBuffer | Uint8Array | Float32Array;
+
+function materialUboFloatView(payload: MaterialUboPayload): Float32Array {
+  if (payload instanceof Float32Array) return payload;
+  return payload instanceof Uint8Array
+    ? new Float32Array(payload.buffer, payload.byteOffset, payload.byteLength / 4)
+    : new Float32Array(payload);
+}
+
+export function applyMaterialTextureUvScales(
+  payload: MaterialUboPayload,
+  material: MaterialSnapshot,
+  world: World,
+): void {
+  const f32 = materialUboFloatView(payload);
+  const coordinateSchema = materialCoordinateSchema(material);
+  if (coordinateSchema !== undefined) {
+    const coordinateRecords = derivedParamSchema(coordinateSchema).coordinateRecords;
+    for (const record of coordinateRecords) {
+      const field = record.parameter;
+      const handle = materialTextureForField(material, field);
+      const resolvedTexture =
+        handle === undefined ? undefined : resolveAssetHandle<TextureAsset>(world, handle);
+      const texture = resolvedTexture?.ok === true ? resolvedTexture.value : undefined;
+      const [u, v] = materialTextureUvScale(texture);
+      const coordinates = resolveMaterialTextureCoordinates(
+        material.textureCoordinates?.get(field),
+      );
+      const offset = record.offset / 4;
+      f32[offset] = coordinates.transform.offset[0];
+      f32[offset + 1] = coordinates.transform.offset[1];
+      f32[offset + 2] = coordinates.transform.scale[0];
+      f32[offset + 3] = coordinates.transform.scale[1];
+      f32[offset + 4] = coordinates.set;
+      f32[offset + 5] = coordinates.transform.rotation;
+      f32[offset + 6] = u;
+      f32[offset + 7] = v;
+    }
+    return;
+  }
+  // Standard PBR grew two authored coat fields before the engine-owned UV
+  // tail. Sprite, sprite-lit, unlit, and text keep their own 80-byte tail
+  // position because their WGSL layouts do not carry clearcoat.
+  const textureScaleOffset = isStandardPbrMaterialShader(material.materialShaderId)
+    ? STANDARD_PBR_TEXTURE_SCALE_OFFSET
+    : LEGACY_MATERIAL_TEXTURE_SCALE_OFFSET;
+  const isStandardPbr = textureScaleOffset === STANDARD_PBR_TEXTURE_SCALE_OFFSET;
+  const hasTextureMetadata =
+    material.textureCoordinates !== undefined ||
+    material.textureHandles !== undefined ||
+    material.videoTextureFields !== undefined ||
+    material.baseColorTexture !== undefined ||
+    material.metallicRoughnessTexture !== undefined ||
+    material.normalTexture !== undefined ||
+    material.emissiveTexture !== undefined ||
+    material.occlusionTexture !== undefined;
+  if (!hasTextureMetadata) {
+    f32.set(
+      isStandardPbr ? DEFAULT_STANDARD_TEXTURE_COORDINATES : DEFAULT_LEGACY_TEXTURE_SCALES,
+      textureScaleOffset / 4,
+    );
+    return;
+  }
+  const fields = isStandardPbr
+    ? MATERIAL_TEXTURE_SCALE_FIELDS
+    : LEGACY_MATERIAL_TEXTURE_SCALE_FIELDS;
+  for (let index = 0; index < fields.length; index++) {
+    const field = fields[index];
+    if (field === undefined) continue;
+    const handle = materialTextureForField(material, field);
+    const resolved =
+      handle === undefined ? undefined : resolveAssetHandle<TextureAsset>(world, handle);
+    const texture = resolved?.ok === true ? resolved.value : undefined;
+    const [u, v] = materialTextureUvScale(texture);
+    if (isStandardPbr) {
+      const coordinates = material.textureCoordinates?.get(field);
+      const transform = coordinates?.transform;
+      const offset =
+        STANDARD_PBR_TEXTURE_COORDINATE_OFFSET / 4 + index * STANDARD_PBR_TEXTURE_COORDINATE_STRIDE;
+      f32[offset] = transform?.offset?.[0] ?? 0;
+      f32[offset + 1] = transform?.offset?.[1] ?? 0;
+      f32[offset + 2] = transform?.scale?.[0] ?? 1;
+      f32[offset + 3] = transform?.scale?.[1] ?? 1;
+      f32[offset + 4] = coordinates?.set ?? 0;
+      f32[offset + 5] = transform?.rotation ?? 0;
+      f32[offset + 6] = u;
+      f32[offset + 7] = v;
+    } else {
+      const offset = textureScaleOffset / 4 + index * 2;
+      f32[offset] = u;
+      f32[offset + 1] = v;
+    }
+  }
+}
+
+function materialCoordinateSchema(
+  material: MaterialSnapshot,
+): readonly ParamSchemaEntry[] | undefined {
+  if (material.materialParamSchema !== undefined && material.materialParamSchema.length > 0) {
+    return material.materialParamSchema;
+  }
+  switch (material.materialShaderId) {
+    case 'forgeax::default-unlit':
+      return DEFAULT_UNLIT_PARAM_SCHEMA;
+    case 'forgeax::sprite':
+    case 'forgeax::sprite-lit':
+      return DEFAULT_SPRITE_PARAM_SCHEMA;
+    case 'forgeax::msdf-text':
+      return DEFAULT_MSDF_TEXT_PARAM_SCHEMA;
+    default:
+      return undefined;
+  }
+}
+
 /**
  * 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.
+ * texture pair order in derive().bglEntries). Falls back to the built-in 4
+ * fields when the schema is unavailable.
  */
 export function userRegionTextureFieldOrder(
-  projection: DerivedMaterialInterface | undefined,
+  schema: Parameters<typeof derive>[0] | undefined,
 ): readonly string[] {
-  if (projection === undefined) return [];
-  return [...projection.textureFieldNames];
+  if (schema === undefined || schema.length === 0) return BUILTIN_USER_REGION_TEXTURE_FIELDS;
+  const fields = [...derivedParamSchema(schema).textureFieldNames];
+  return fields.length === 0 ? BUILTIN_USER_REGION_TEXTURE_FIELDS : fields;
 }
 
 /**
@@ -459,8 +563,7 @@ export function userRegionTextureFieldOrder(
 export function defaultViewForUserRegionField(
   field: string,
   pipelineState: PipelineState,
-  // biome-ignore lint/suspicious/noExplicitAny: opaque GPU texture-view
-): any {
+): TextureView {
   if (field === 'normalTexture') return pipelineState.defaultNormalTextureView;
   if (field === 'baseColorTexture') return pipelineState.fallbackTextureView;
   return pipelineState.defaultWhiteTextureView;
@@ -485,7 +588,7 @@ export function defaultViewForUserRegionField(
  *                       (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.
+ * @param metrics        The owner-provided EngineMetrics counter.
  * @internal — exported for unit-test access (w17).
  */
 export function detectNineSliceScaleTooSmall(
@@ -509,6 +612,203 @@ export function detectNineSliceScaleTooSmall(
   }
 }
 
+/**
+ * Build the 128-byte Material UBO payload for a PBR / unlit material entry
+ * (feat-20260527-sprite-nineslice M2 / w11; D-7 regression-net helper).
+ *
+ * Byte-for-byte equivalent to the legacy hard-coded PBR write path; each
+ * deviation is caught by `render-system-record-pbr-ubo-stable.test.ts`.
+ * The schema-driven paramSnapshot overlay (feat-20260523 M9-T05; AC-14)
+ * positions vec4 / f32 slots onto std140 [slot0 vec4, slot1 f32 metallic,
+ * slot1 f32 roughness] mirroring the engine-shipped default-standard-pbr
+ * Material struct.
+ */
+export function buildPbrMaterialUboPayload(material: MaterialSnapshot): Uint8Array {
+  const buf = new Uint8Array(STANDARD_PBR_UBO_SIZE);
+  writePbrMaterialUboPayload(buf, material);
+  return buf;
+}
+
+/**
+ * Write the standard material payload into caller-owned storage.
+ *
+ * The allocating wrapper above remains the byte-stable test/helper surface,
+ * while the frame recorder reuses one scratch slot for all materials. A
+ * scene with thousands of submeshes otherwise allocates one 304-byte
+ * Uint8Array per material per frame, creating avoidable GC pressure without
+ * changing GPU-visible bytes.
+ */
+export function writePbrMaterialUboPayload(
+  buf: Uint8Array | Float32Array,
+  material: MaterialSnapshot,
+): void {
+  if (buf.byteLength < STANDARD_PBR_UBO_SIZE) {
+    throw new RangeError(
+      `writePbrMaterialUboPayload: expected at least ${STANDARD_PBR_UBO_SIZE} bytes, got ${buf.byteLength}`,
+    );
+  }
+  buf.fill(0);
+  const f32 = materialUboFloatView(buf);
+  // Layout (issue-1: channelMap split per D-8) -- byte-equivalent to the
+  // post-split sidecar paramSchema for default-standard-pbr (12 numeric
+  // entries packed std140 into one merged UBO at binding(0)).
+  //   f32[0..3]   baseColor          (offset 0,  vec4)
+  //   f32[4]      metallic           (offset 16)
+  //   f32[5]      roughness          (offset 20)
+  //   f32[6]      metallicChannel    (offset 24)  -- glTF 2.0 default = B = 2
+  //   f32[7]      roughnessChannel   (offset 28)  -- glTF 2.0 default = G = 1
+  //   f32[8]      aoChannel          (offset 32)  -- glTF 2.0 default = R = 0
+  //   f32[9]      extraChannel       (offset 36)  -- reserved = 0
+  //                                  (offset 40..47 implicit pad: vec3 align=16)
+  //   f32[12..14] emissive           (offset 48,  vec3)
+  //   f32[15]     emissiveIntensity  (offset 60)
+  //   f32[16]     occlusionStrength  (offset 64)
+  //   f32[17]     alphaCutoff        (offset 68)
+  //   f32[18]     clearcoat          (offset 72)
+  //   f32[19]     clearcoatRoughness (offset 76)
+  //   f32[20..22] specularTint       (offset 80, vec3)
+  //                                  (offset 92..95 alignment pad)
+  //   f32[24..71] engine-owned texture coordinate records (offset 96)
+  //   f32[72]     normalScale        (offset 288)
+  f32[0] = material.baseColor[0] ?? 0;
+  f32[1] = material.baseColor[1] ?? 0;
+  f32[2] = material.baseColor[2] ?? 0;
+  f32[3] = 1;
+  f32[4] = material.metallic;
+  f32[5] = material.roughness;
+  // channelMap default = (B, G, R, _) per AGENTS.md + glTF 2.0
+  // KHR_materials_pbrSpecularGlossiness ARM packing -- now 4 independent
+  // f32 selectors; fragment casts each to u32 at the pick site.
+  f32[6] = 2; // metallicChannel  <- B
+  f32[7] = 1; // roughnessChannel <- G
+  f32[8] = 0; // aoChannel        <- R
+  f32[9] = 0; // extraChannel     <- reserved
+  // emissive vec3 + emissiveIntensity (offset 48..63)
+  const em = material.emissive;
+  f32[12] = em?.[0] ?? 0;
+  f32[13] = em?.[1] ?? 0;
+  f32[14] = em?.[2] ?? 0;
+  f32[15] = material.emissiveIntensity ?? 0;
+  // occlusionStrength (offset 64)
+  f32[16] = material.occlusionStrength ?? 1;
+  // alphaCutoff (offset 68).
+  const alphaCutoff = material.paramSnapshot?.alphaCutoff;
+  f32[17] = typeof alphaCutoff === 'number' ? alphaCutoff : 0;
+  f32[18] = material.clearcoat ?? 0;
+  f32[19] = material.clearcoatRoughness ?? 0.5;
+  const specularTint = material.specularTint;
+  f32[20] = specularTint?.[0] ?? 1;
+  f32[21] = specularTint?.[1] ?? 1;
+  f32[22] = specularTint?.[2] ?? 1;
+  f32[72] = material.normalScale ?? 1;
+  // Schema-driven paramSnapshot overlay (feat-20260523 M9-T05, AC-14):
+  // for user-shaders with a paramSnapshot, project the first vec4/color
+  // entry onto slot 0 and the first two f32 entries onto slot 1's first
+  // two floats. The default-standard-pbr path lands on the same offsets
+  // via the explicit fields above, so the overlay is a no-op for the
+  // engine's stock PBR shader (charter P4 + R-H regression fence).
+  const paramSnap = material.paramSnapshot;
+  if (paramSnap !== undefined) {
+    const f32Snap = (name: string): number | undefined => {
+      const v = paramSnap[name];
+      return typeof v === 'number' ? v : undefined;
+    };
+    const colorSnap = (name: string): readonly number[] | undefined => {
+      const v = paramSnap[name];
+      return Array.isArray(v) && v.every((x) => typeof x === 'number')
+        ? (v as readonly number[])
+        : undefined;
+    };
+    // Walk schema in declared order, fill positional UBO slots.
+    const materialShaderId = material.materialShaderId;
+    // Note: schema lookup is the caller's job (it owns the runtime ref);
+    // when the helper has no access to runtime, paramSnap is consumed
+    // positionally without a schema walk. The inline caller (recordFrame)
+    // still performs the schema-driven walk and writes the overlay before
+    // queueing this payload, so this helper is only the byte-stable
+    // baseline. To preserve byte-for-byte equivalence in the helper-only
+    // unit-test path, the overlay pass is skipped when the helper is
+    // called without an external schema reference.
+    void materialShaderId;
+    void f32Snap;
+    void colorSnap;
+  }
+}
+
+/**
+ * Generic std140 UBO writer driven by `derive(paramSchema).uboLayout.entries`
+ * (feat-20260625-refactor-sprite-as-transparent-mesh M1 / w3, plan-strategy
+ * section 2 D-2).
+ *
+ * For each numeric entry in the schema, looks up the matching value in
+ * `paramSnapshot` and writes it at the std140 offset `derive` computed.
+ * Vec / color entries pull from `paramSnapshot[name]` as a `readonly number[]`
+ * (writes `min(size/4, value.length)` floats, padding with 0 if shorter for
+ * the field's declared width); scalar entries pull a single number.
+ *
+ * Behaviour:
+ *   - schema or snapshot `undefined` -> no writes (caller may keep payload
+ *     baseline).
+ *   - missing snapshot field -> that field's bytes are left untouched
+ *     (overlay semantics; same shape the legacy inline overlay had).
+ *   - field type the writer cannot interpret (texture / sampler / storage_
+ *     buffer / value-type mismatch) -> skipped silently; `derive` strips
+ *     non-numeric entries from `uboLayout.entries` so the loop only iterates
+ *     numeric fields.
+ *
+ * The writer reads `paramSnapshot` only -- it does NOT call
+ * `runtime.assets.get<MaterialAsset>` or cast `firstMaterial`. Gate R-H
+ * (plan-strategy section 5.6) bans those paths through
+ * `scripts/forgeax/check-render-record-no-material-asset-get.mjs`.
+ *
+ * standard-pbr remains byte-identical to `buildPbrMaterialUboPayload`: the
+ * engine's stock PBR material ships `paramSnapshot: undefined`, so this
+ * writer is a no-op on that path; the explicit field writes in the helper
+ * above cover every byte. User shaders (sprite-shaped 4 x vec4 or another
+ * paramSchema) get their fields written at the offsets declared by derive.
+ *
+ * @internal export-for-test (consumed inside `recordFrame` + render-system-
+ * record.test.ts; not part of the package's public surface).
+ */
+export function applyParamSnapshotToUbo(
+  payload: MaterialUboPayload,
+  paramSchema: readonly ParamSchemaEntry[] | undefined,
+  paramSnapshot:
+    | Readonly<Record<string, number | readonly number[] | string | undefined>>
+    | undefined,
+): void {
+  if (paramSchema === undefined) return;
+  if (paramSnapshot === undefined) return;
+  const f32 = materialUboFloatView(payload);
+  const { uboLayout } = derivedParamSchema(paramSchema);
+  for (const entry of uboLayout.entries) {
+    const value = paramSnapshot[entry.name];
+    if (value === undefined) continue;
+    const f32Offset = entry.offset / 4;
+    const f32Width = entry.size / 4;
+    if (typeof value === 'number') {
+      // Scalar f32 / i32 / u32 -- single-slot write. (i32 / u32 still arrive
+      // as a JS number; the GPU side reads the four bytes as the declared
+      // type, so an f32 write is the correct bit pattern when the caller
+      // already produced an integer value.)
+      if (f32Width >= 1) f32[f32Offset] = value;
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const arr = value as readonly number[];
+      const writeCount = Math.min(arr.length, f32Width);
+      for (let i = 0; i < writeCount; i++) {
+        const v = arr[i];
+        if (typeof v === 'number') f32[f32Offset + i] = v;
+      }
+    }
+    // string values (texture GUIDs) belong to texture bindings, not the
+    // UBO; derive's uboLayout.entries already strips non-numeric schema
+    // entries, so we will not see a uboLayout entry whose snapshot value
+    // is a string under normal flow. Skip defensively if we do.
+  }
+}
+
 /**
  * feat-20260704 M3/w19: shared per-submesh material bind-group assembly, hoisted
  * from the `buildPerSubmeshMaterialBg` closure inside recordMainPass so both the
@@ -530,13 +830,13 @@ export interface PerSubmeshMaterialBgDeps {
   readonly runtime: RenderSystemRuntime;
   readonly pipelineState: PipelineState;
   readonly world: World;
-  readonly store: GpuResourceStore;
+  readonly store: GpuResidencyCache;
   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 materialBgAssemblyCache: Map<string, MaterialBgAssemblyCacheEntry>;
   readonly bindGroupCounts: BindGroupCounts;
 }
 
@@ -568,11 +868,11 @@ export function buildPerSubmeshMaterialBg(
   deps: PerSubmeshMaterialBgDeps,
   submeshMaterial: MaterialSnapshot,
   entityKey: number,
+  materialWorld: World = deps.world,
 ): BindGroup {
   const {
     runtime,
     pipelineState,
-    world,
     store,
     materialSlice,
     videoHighPerfAvailable,
@@ -582,14 +882,16 @@ export function buildPerSubmeshMaterialBg(
     bindGroupCounts,
   } = deps;
   const smMaterialHandle = submeshMaterial.materialHandle;
+  const materialCacheKey =
+    smMaterialHandle === undefined ? undefined : `${materialWorld.identity}:${smMaterialHandle}`;
   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);
+    const cached =
+      materialCacheKey === undefined ? undefined : materialBgAssemblyCache.get(materialCacheKey);
     if (
       isMaterialBgAssemblyCacheHit(
         cached,
@@ -603,32 +905,24 @@ export function buildPerSubmeshMaterialBg(
       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);
+  const smSchema =
+    submeshMaterial.materialParamSchema ??
+    (smShaderId !== undefined ? runtime.getParamSchema?.(smShaderId) : undefined);
+  // The shipped PBR shaders always own the six texture pairs declared by the
+  // standard shader artifact. Authored material snapshots may intentionally
+  // carry a compact four-field schema because emissive/occlusion are engine
+  // injected values, but the runtime PBR BGL still exposes bindings 9..12 for
+  // those pairs. Keep the record projection on the shader-owned layout so IBL
+  // starts at binding 13 rather than colliding with emissiveSampler.
+  const smUserRegionFields =
+    smPerShaderBgl === undefined || isStandardPbrMaterialShader(smShaderId)
+      ? BUILTIN_USER_REGION_TEXTURE_FIELDS
+      : userRegionTextureFieldOrder(smSchema);
   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);
+    const sampler = residentSampler(materialWorld, store, runtime, handle);
     if (sampler === undefined) materialResourcesResident = false;
     return sampler ?? pipelineState.defaultSampler;
   };
@@ -640,7 +934,7 @@ export function buildPerSubmeshMaterialBg(
         value: {
           buffer: pipelineState.materialUniformBuffer.buffer,
           offset: 0,
-          size: smMaterialByteLength,
+          size: materialSlice,
         },
       },
     },
@@ -650,7 +944,7 @@ export function buildPerSubmeshMaterialBg(
     const field = smUserRegionFields[fi];
     const samplerBinding = 1 + fi * 2;
     const textureBinding = samplerBinding + 1;
-    let smView: unknown =
+    let smView: TextureView =
       field !== undefined
         ? defaultViewForUserRegionField(field, pipelineState)
         : pipelineState.defaultWhiteTextureView;
@@ -658,7 +952,7 @@ export function buildPerSubmeshMaterialBg(
       field !== undefined ? submeshMaterial.videoTextureFields?.get(field) : undefined;
     if (smVideoClip !== undefined) {
       const view = videoTextureView(
-        world,
+        materialWorld,
         runtime.dynamicTextureStore,
         runtime,
         entityKey,
@@ -667,9 +961,16 @@ export function buildPerSubmeshMaterialBg(
       );
       if (view !== undefined) smView = view;
     } else {
-      const smHandle = field !== undefined ? submeshMaterial.textureHandles?.get(field) : undefined;
+      const smHandle =
+        field === 'emissiveTexture'
+          ? submeshMaterial.emissiveTexture
+          : field === 'occlusionTexture'
+            ? submeshMaterial.occlusionTexture
+            : field !== undefined
+              ? submeshMaterial.textureHandles?.get(field)
+              : undefined;
       if (smHandle !== undefined) {
-        const view = residentTextureView(world, store, runtime, smHandle);
+        const view = residentTextureView(materialWorld, store, runtime, smHandle);
         if (view !== undefined) smView = view;
         else materialResourcesResident = false;
       }
@@ -681,11 +982,35 @@ export function buildPerSubmeshMaterialBg(
       },
       {
         binding: textureBinding,
-        resource: { kind: 'textureView' as const, value: smView as never },
+        resource: { kind: 'textureView' as const, value: smView },
       },
     );
   }
-  const smMergedEntries = assembleMaterialWithSkylightEntries(smBaseEntries, skylightResources);
+  let smEmissiveView: TextureView = pipelineState.defaultWhiteTextureView;
+  const smEmissiveHandle = submeshMaterial.emissiveTexture;
+  if (smEmissiveHandle !== undefined) {
+    const view = residentTextureView(materialWorld, store, runtime, smEmissiveHandle);
+    if (view !== undefined) smEmissiveView = view;
+    else materialResourcesResident = false;
+  }
+  let smOcclusionView: TextureView = pipelineState.defaultWhiteTextureView;
+  const smOcclusionHandle = submeshMaterial.occlusionTexture;
+  if (smOcclusionHandle !== undefined) {
+    const view = residentTextureView(materialWorld, store, runtime, smOcclusionHandle);
+    if (view !== undefined) smOcclusionView = view;
+    else materialResourcesResident = false;
+  }
+  const smEmissiveAo: EmissiveAoBindGroupResources = {
+    emissiveSampler: smSamplerForField('emissiveTexture'),
+    emissiveView: smEmissiveView,
+    occlusionSampler: smSamplerForField('occlusionTexture'),
+    occlusionView: smOcclusionView,
+  };
+  const smMergedEntries = assembleMaterialWithSkylightEntries(
+    smBaseEntries,
+    skylightResources,
+    smEmissiveAo,
+  );
   const smBindGroup = getOrCreatePerEntity(
     materialBgShared,
     smShaderId ?? '',
@@ -703,14 +1028,16 @@ export function buildPerSubmeshMaterialBg(
     bindGroupCounts,
   );
   if (smMaterialHandle !== undefined && !smHasVideoFields && materialResourcesResident) {
-    materialBgAssemblyCache.set(smMaterialHandle, {
-      material: submeshMaterial,
-      materialResourceEpoch: store.materialResourceEpoch,
-      materialBgl: smMaterialBgl,
-      materialBuffer: pipelineState.materialUniformBuffer.buffer,
-      skylightResources,
-      bindGroup: smBindGroup,
-    });
+    if (materialCacheKey !== undefined) {
+      materialBgAssemblyCache.set(materialCacheKey, {
+        material: submeshMaterial,
+        materialResourceEpoch: store.materialResourceEpoch,
+        materialBgl: smMaterialBgl,
+        materialBuffer: pipelineState.materialUniformBuffer.buffer,
+        skylightResources,
+        bindGroup: smBindGroup,
+      });
+    }
   }
   return smBindGroup;
 }