@forgeax/engine-render 0.1.6 → 0.1.19

package/src/index.ts

@@ -1,8 +1,8 @@
 // @forgeax/engine-render — AI-facing render vocabulary.
 //
 // The root is deliberately small: ECS render components, grouped closed
-// values, the renderer lifecycle/receipt contract, and the declarative
-// RenderFeature plan. Graph builders, prepared GPU state, pipeline
+// values, immutable frame facts, the renderer lifecycle/receipt contract, and
+// the declarative RenderFeature plan. Graph builders, prepared GPU state, pipeline
 // implementations, builtin feature factories, and diagnostic class names are
 // owner-local implementation details.
 
@@ -11,13 +11,20 @@ export {
   renderPipelineContribution,
   samplerContribution,
 } from './assets/asset-decoders';
-
+export { Atmosphere } from './components/atmosphere';
 // ECS render vocabulary and grouped closed values.
-export type { Antialias, BloomEnabled, CameraProjection, Tonemap } from './components/camera';
+export type {
+  Antialias,
+  BloomEnabled,
+  CameraData,
+  CameraProjection,
+  Tonemap,
+} from './components/camera';
 export {
   ANTIALIAS_FXAA,
   ANTIALIAS_MSAA,
   ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
   BLOOM_DISABLED,
   BLOOM_ENABLED,
   CAMERA_PROJECTION_ORTHOGRAPHIC,
@@ -36,12 +43,21 @@ export {
   TONEMAP_REINHARD_EXTENDED,
 } from './components/camera';
 export * from './components/directional-light';
+export { Fog } from './components/fog';
 export { Instances, type InstancesData } from './components/instances';
 export { Layer } from './components/layer';
+export { Lines } from './components/lines';
 export * from './components/mesh-filter';
 export * from './components/mesh-renderer';
+export { MotionBlur } from './components/motion-blur';
 export { PointLight } from './components/point-light';
 export { PointLightShadow } from './components/point-light-shadow';
+export {
+  type PointShape,
+  PointShapeValue,
+  Points,
+  pointShapeFromU32,
+} from './components/points';
 export { PostProcessParams } from './components/post-process-params';
 export { SceneInstance } from './components/scene-instance';
 export {
@@ -58,9 +74,35 @@ export {
   VisibilityStateValue,
   visibilityStateFromU32,
 } from './components/visibility';
+export type {
+  EnvironmentInspection,
+  EnvironmentInspectionFailure,
+  EnvironmentInspectionGeneration,
+  EnvironmentInspectionStatus,
+} from './environment/inspection';
 // Public structured operation failure union. Concrete error classes stay
 // behind the Renderer Result/event boundary.
-export type { RenderError, RenderErrorCode } from './errors/render';
+export type {
+  RenderError,
+  RenderErrorCode,
+  SceneDataUnavailableDetail,
+  SceneDataUnavailableReason,
+} from './errors/render';
+export {
+  AtmosphereInvalidParameterError,
+  EnvironmentGenerationFailedError,
+  EnvironmentSourceConflictError,
+  FogCardinalityError,
+  OwnerStageFailedError,
+  SceneDataUnavailableError,
+  TaaCapsInsufficientError,
+} from './errors/render';
+export type {
+  EnvironmentFrame,
+  EnvironmentSource,
+  FogFrame,
+  FramePlan,
+} from './extract/environment';
 export {
   resolveVisibility,
   type VisibilityResolution,
@@ -68,6 +110,7 @@ export {
 } from './extract/visibility';
 export type {
   RenderFeatureLogicalTarget,
+  RenderFeatureMaterialShaderBindingContract,
   RenderFeaturePassDeclaration,
   RenderFeaturePlan,
   RenderFeaturePlanContext,
@@ -83,14 +126,31 @@ export type {
   RenderFeatureErrorDescriptor,
   RenderFeatureExtractContext,
   RenderFeatureHiddenEntityReport,
+  RenderFeatureShaderModuleMode,
   RenderFeatureStatus,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
-export { Materials } from './materials';
+export type {
+  BloomInspection,
+  MotionBlurInspection,
+  MotionBlurInspectionStatus,
+  TransmissionInspection,
+} from './inspection-types';
+export { Materials, MaterialTransmissionContractError } from './materials';
 // The host-facing default is a stable profile value; implementation-only
 // pipeline helpers remain behind the package boundary.
 export { DEFAULT_STANDARD_PROFILE } from './pipeline/standard-profile';
 export { renderComponentsPlugin } from './plugin';
+export {
+  admitPointsLines,
+  type LinesStyleInput,
+  type PointsLinesAdmission,
+  type PointsLinesAdmissionError,
+  type PointsLinesAdmissionInput,
+  type PointsLinesAdmissionLimits,
+  type PointsStyleInput,
+} from './points-lines/admission';
+export type { PointsLinesInspection } from './points-lines/inspection';
 // Runtime contract: leases, frame receipts, detached inspection, profile,
 // lifecycle state, and the single renderer event stream.
 export type {
@@ -110,3 +170,20 @@ export type {
   RenderWorldLease,
 } from './render-contract';
 export { RENDER_PHASE_CATALOG } from './render-contract';
+export type { TemporalInspection, TemporalResourceInspection } from './temporal/inspection';
+export {
+  SCENE_DATA_TEMPORAL_V1_DESCRIPTOR,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+  type SceneDataLane,
+  type SceneDataSchemaId,
+  type SceneDataTarget,
+  type SceneDataTemporalV1Descriptor,
+} from './temporal/scene-data';
+export {
+  createSceneDataCatalog,
+  type SceneDataAvailability,
+  type SceneDataCatalog,
+  type SceneDataCatalogOptions,
+  type SceneDataInspection,
+} from './temporal/scene-data-catalog';
+export type { TemporalView } from './temporal/view';

package/src/inspection-types.ts

@@ -4,6 +4,26 @@
  * extract/record dependency graph.
  */
 
+import type { PointsLinesInspection } from './points-lines/inspection';
+
+export type BloomGraphStatus = 'empty' | 'valid' | 'invalid';
+
+export interface BloomInspection {
+  readonly graphStatus: BloomGraphStatus;
+  readonly enabled: boolean;
+  readonly targetCount: number;
+  readonly targetBytes: number;
+  readonly resourceCount: number;
+  readonly passCount: number;
+  readonly encodeCount: number;
+  readonly bindGroupCount: number;
+  readonly uploadCount: number;
+  readonly residentChildBytes: number;
+  readonly generation: number;
+  readonly state: 'off' | 'active' | 'retiring';
+}
+export type { TransmissionInspection } from './transmission/inspection';
+
 export interface BatchTopologyInspection {
   readonly revision: number;
   readonly batchCount: number;
@@ -45,6 +65,36 @@ export interface GpuDrivenProductionInspection {
   readonly cpuFallbackDrawItems: number;
 }
 
+/** Detached semantic descriptor for the Standard scene-temporal producer. */
+export interface TemporalTargetInspection {
+  readonly identity: 'standard-scene-temporal';
+  readonly producerId: 'forgeax::standard::scene-data';
+  readonly schema: 'forgeax::scene-data::temporal-v1';
+  readonly targetCount: 1;
+  readonly descriptor: {
+    readonly format: 'rgba16float';
+    readonly width: number;
+    readonly height: number;
+    readonly sampleCount: 1;
+    readonly bytes: number;
+  };
+}
+
+/** Detached, bounded Motion Blur facts; no graph, device, target, or history handle. */
+export type MotionBlurInspectionStatus = 'off' | 'active' | 'reset' | 'invalid';
+
+export interface MotionBlurInspection {
+  readonly enabled: boolean;
+  readonly status: MotionBlurInspectionStatus;
+  readonly shutterAngle: number;
+  readonly maxRadiusPixels: number;
+  readonly sampleCount: number;
+  readonly temporalDemand: 'none' | 'scene-data-temporal-v1';
+  readonly passName: 'motion-blur';
+  readonly historyWrites: 0;
+  readonly lastFailure?: 'invalid-params' | 'scene-data-unavailable';
+}
+
 export type RenderSceneResyncReason =
   | 'attach'
   | 'asset-catalog-changed'
@@ -69,6 +119,8 @@ export interface PersistentRenderSceneInspection {
     | ({ readonly status: 'resident' } & GpuSceneInspection)
     | { readonly status: 'rebuild-pending' }
     | { readonly status: 'error' };
+  /** Bounded retained authoring observations; no graph or backend handles. */
+  readonly pointsLines: readonly PointsLinesInspection[];
 }
 
 export type RenderSceneInspection = PersistentRenderSceneInspection & {

package/src/internal.ts

@@ -7,3 +7,8 @@ export {
   type TilesetRuntimeError,
   type TilesetRuntimeErrorCode,
 } from '@forgeax/engine-assets-runtime';
+export {
+  type GraphTargetCaptureReadbackValidation,
+  validateGraphTargetCaptureReadback,
+} from './record/frame-snapshot';
+export { TemporalFrameCoordinator } from './temporal/frame-coordinator';

package/src/materials.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import type {
   MaterialAsset,
   MaterialColorSpace,
@@ -7,6 +8,49 @@ import type {
   MaterialValue,
 } from '@forgeax/engine-types';
 
+export type MaterialTransmissionValidationReason =
+  | 'non-finite'
+  | 'range'
+  | 'shape'
+  | 'blend'
+  | 'depth-write';
+
+/** Structured authoring failure for the Standard transmission contract. */
+export class MaterialTransmissionContractError extends Error {
+  readonly code = 'material-transmission-contract-invalid' as const;
+  readonly expected = 'transmission material values satisfy finite ranges and Forward depth rules';
+  readonly hint =
+    'repair the named transmission value or pass state before publishing the material';
+  readonly detail: {
+    readonly code: 'material-transmission-contract-invalid';
+    readonly material: 'Standard';
+    readonly parameter:
+      | 'transmission'
+      | 'ior'
+      | 'thickness'
+      | 'attenuationColor'
+      | 'attenuationDistance';
+    readonly reason: MaterialTransmissionValidationReason;
+    readonly actual?: unknown;
+  };
+
+  constructor(
+    parameter: (typeof MaterialTransmissionContractError.prototype.detail)['parameter'],
+    reason: MaterialTransmissionValidationReason,
+    actual?: unknown,
+  ) {
+    super(`Materials.standard: ${parameter} violates the transmission contract (${reason})`);
+    this.name = 'MaterialTransmissionContractError';
+    this.detail = {
+      code: 'material-transmission-contract-invalid',
+      material: 'Standard',
+      parameter,
+      reason,
+      ...(actual === undefined ? {} : { actual }),
+    };
+  }
+}
+
 export const SPRITE_PREMULTIPLIED_ALPHA_BLEND: GPUBlendState = {
   color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
   alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
@@ -31,28 +75,26 @@ function authoredColorParameter(
 }
 
 function standardParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {
-  return [
-    authoredColorParameter('baseColor', 'color', colorSpace),
-    { name: 'metallic', type: 'f32' },
-    { name: 'roughness', type: 'f32' },
-    { name: 'metallicChannel', type: 'f32', optional: true },
-    { name: 'roughnessChannel', type: 'f32', optional: true },
-    { name: 'aoChannel', type: 'f32', optional: true },
-    { name: 'extraChannel', type: 'f32', optional: true },
-    authoredColorParameter('emissive', 'vec3', colorSpace, true),
-    { name: 'emissiveIntensity', type: 'f32', optional: true },
-    { name: 'occlusionStrength', type: 'f32', optional: true },
-    { name: 'alphaCutoff', type: 'f32', optional: true },
-    { name: 'clearcoat', type: 'f32', optional: true },
-    { name: 'clearcoatRoughness', type: 'f32', optional: true },
-    authoredColorParameter('specularTint', 'vec3', colorSpace, true),
-    { name: 'baseColorTexture', type: 'texture', optional: true },
-    { name: 'metallicRoughnessTexture', type: 'texture', optional: true },
-    { name: 'normalTexture', type: 'texture', optional: true },
-    { name: 'specularTintTexture', type: 'texture', optional: true },
-    { name: 'emissiveTexture', type: 'texture', optional: true },
-    { name: 'occlusionTexture', type: 'texture', optional: true },
-  ];
+  return DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => {
+    const type = entry.type.startsWith('texture') ? 'texture' : entry.type;
+    const isRequired =
+      entry.name === 'baseColor' || entry.name === 'metallic' || entry.name === 'roughness';
+    const authoredColor =
+      entry.type === 'color' || (entry.type === 'vec3' && entry.name !== 'attenuationColor');
+    const schemaColorSpace = 'colorSpace' in entry ? entry.colorSpace : undefined;
+    const colorSpaceProjection: { colorSpace?: MaterialColorSpace } = {};
+    if (authoredColor && !(type === 'color' && colorSpace === 'srgb')) {
+      colorSpaceProjection.colorSpace = colorSpace;
+    } else if (!authoredColor && schemaColorSpace !== undefined) {
+      colorSpaceProjection.colorSpace = schemaColorSpace;
+    }
+    return {
+      name: entry.name,
+      type,
+      ...colorSpaceProjection,
+      ...(isRequired ? {} : { optional: true }),
+    } as MaterialParameter;
+  });
 }
 
 function unlitParameters(colorSpace: MaterialColorSpace): readonly MaterialParameter[] {
@@ -143,6 +185,13 @@ interface StandardOpts {
   readonly occlusionTexture?: MaterialValue;
   readonly occlusionStrength?: number;
   readonly alphaCutoff?: number;
+  readonly transmission?: number;
+  readonly transmissionTexture?: MaterialValue;
+  readonly ior?: number;
+  readonly thickness?: number;
+  readonly thicknessTexture?: MaterialValue;
+  readonly attenuationColor?: readonly [number, number, number];
+  readonly attenuationDistance?: number;
   readonly renderState?: MaterialRenderState;
   readonly castShadow?: boolean;
   readonly queue?: number;
@@ -157,6 +206,21 @@ function validateChannel(
   }
 }
 
+function validateFiniteRange(
+  name: 'transmission' | 'ior' | 'thickness' | 'attenuationDistance',
+  value: number | undefined,
+  minimum: number,
+  maximum?: number,
+): void {
+  if (value === undefined || !Number.isFinite(value)) {
+    if (value === undefined) return;
+    throw new MaterialTransmissionContractError(name, 'non-finite', value);
+  }
+  if (value < minimum || (maximum !== undefined && value > maximum)) {
+    throw new MaterialTransmissionContractError(name, 'range', value);
+  }
+}
+
 function standard(opts: StandardOpts): MaterialAsset {
   const occlusionStrength = opts.occlusionStrength ?? 1;
   if (occlusionStrength < 0 || occlusionStrength > 1) {
@@ -169,12 +233,36 @@ function standard(opts: StandardOpts): MaterialAsset {
   }
   validateChannel('metallicChannel', opts.metallicChannel);
   validateChannel('roughnessChannel', opts.roughnessChannel);
+  const transmission = opts.transmission ?? 0;
+  const ior = opts.ior ?? 1.5;
+  const thickness = opts.thickness ?? 0;
+  const attenuationColor = opts.attenuationColor ?? [1, 1, 1];
+  validateFiniteRange('transmission', transmission, 0, 1);
+  validateFiniteRange('ior', ior, 1);
+  validateFiniteRange('thickness', thickness, 0);
+  validateFiniteRange('attenuationDistance', opts.attenuationDistance, Number.MIN_VALUE);
+  if (
+    attenuationColor.length !== 3 ||
+    attenuationColor.some((value) => !Number.isFinite(value) || value < 0 || value > 1)
+  ) {
+    throw new MaterialTransmissionContractError('attenuationColor', 'shape', attenuationColor);
+  }
+  if (transmission > 0 && opts.renderState?.blend !== undefined) {
+    throw new MaterialTransmissionContractError('transmission', 'blend', opts.renderState.blend);
+  }
+  if (transmission > 0 && opts.renderState?.depthWriteEnabled === true) {
+    throw new MaterialTransmissionContractError('transmission', 'depth-write', true);
+  }
   const values: Record<string, MaterialValue> = {
     baseColor: opts.baseColor,
     metallic: opts.metallic ?? 0,
     roughness: opts.roughness ?? 0.5,
     occlusionStrength,
     specularTint: opts.specularTint ?? [1, 1, 1],
+    transmission,
+    ior,
+    thickness,
+    attenuationColor,
   };
   if (opts.metallicChannel !== undefined) values.metallicChannel = opts.metallicChannel;
   if (opts.roughnessChannel !== undefined) values.roughnessChannel = opts.roughnessChannel;
@@ -193,10 +281,17 @@ function standard(opts: StandardOpts): MaterialAsset {
     values.specularTintTexture = opts.specularTintTexture;
   }
   if (opts.alphaCutoff !== undefined) values.alphaCutoff = opts.alphaCutoff;
+  if (opts.transmissionTexture !== undefined) values.transmissionTexture = opts.transmissionTexture;
+  if (opts.thicknessTexture !== undefined) values.thicknessTexture = opts.thicknessTexture;
+  if (opts.attenuationDistance !== undefined) values.attenuationDistance = opts.attenuationDistance;
+  const forwardRenderState =
+    transmission > 0 ? { ...(opts.renderState ?? {}), depthWriteEnabled: false } : opts.renderState;
   const passes: [MaterialPass, ...MaterialPass[]] = [
-    pass('forward', STANDARD_MODULE, opts.renderState, 'fs_main', opts.queue),
-    pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue),
+    pass('forward', STANDARD_MODULE, forwardRenderState, 'fs_main', opts.queue),
   ];
+  if (transmission === 0) {
+    passes.push(pass('deferred', STANDARD_MODULE, opts.renderState, 'fs_gbuffer', opts.queue));
+  }
   if (opts.castShadow !== false) passes.push(pass('shadow-caster', STANDARD_MODULE, undefined));
   return {
     kind: 'material',

package/src/pbr-pipeline.ts

@@ -65,7 +65,7 @@ export interface PbrPipelineLayoutBundle {
   readonly viewBgl: BindGroupLayout;
   /**
    * PBR material BindGroupLayout (slot 1) -- derived user-region entries plus
-   * Skylight and lightmap injection.
+   * Skylight and transmission injection.
    */
   readonly materialBgl: BindGroupLayout;
   /** Per-entity mesh BindGroupLayout (slot 2). */
@@ -89,7 +89,7 @@ export interface PbrPipelineLayoutBundle {
 /**
  * The built-in standard-PBR material paramSchema's texture/user-region shape,
  * used as the fallback when the material BGL is built without a registry
- * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 3 standard
+ * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 8 Standard
  * user-region textures + a numeric UBO run; `derive()` collapses the numerics
  * into binding 0 and emits sampler/texture pairs at 1..6 — byte-equivalent to
  * the legacy fixed base-7. The shared PBR parameter contract comes from the
@@ -99,13 +99,13 @@ export interface PbrPipelineLayoutBundle {
  * Build the PBR material BGL **user-region** from a paramSchema via the
  * `derive()` SSOT (D-1). The user-region is binding 0 (the run-merged material
  * UBO) followed by one sampler/texture pair per declared texture. Engine
- * injection (IBL + lightmap) is appended AFTER this region by the caller via
+ * injection (IBL + transmission) is appended AFTER this region by the caller via
  * `appendInjection`, with start binding = `userRegion.length` — so a 4-texture
  * custom schema (e.g. parallax + heightTexture) shifts the injection region by
  * one sampler/texture pair automatically.
  *
- * The built-in `default-standard-pbr` paramSchema declares exactly 4 textures,
- * so this derives to binding 0 UBO + 4 pairs = 9 entries. Injection is appended
+ * The built-in `default-standard-pbr` paramSchema declares exactly 8 textures,
+ * so this derives to binding 0 UBO + 8 pairs = 17 entries. Injection is appended
  * after that derived region.
  *
  * One material-UBO convention is layered on top of the pure `derive()` output:
@@ -178,11 +178,16 @@ export function buildPbrMaterialUserRegionEntries(
 //                keep that meaning under the generic 'lightmap' label
 //                (per-surface secondary-lighting injection) so future
 //                lightmap support lands without renaming the kind.
+//   - 'transmission' the engine-owned sampler + backdrop texture pair. The
+//                record stage supplies a real backdrop only for the active
+//                transmission pass; all other variants bind layout-safe
+//                placeholders because their shaders do not read these slots.
 export type InjectionKind = keyof typeof INJECTION_KIND_LENGTHS;
 
 const IBL_INJECTION_LENGTH = 7;
 const LIGHTMAP_INJECTION_LENGTH = 4;
 const SHADOW_INJECTION_LENGTH = 2;
+const TRANSMISSION_INJECTION_LENGTH = 2;
 
 /**
  * Append the engine-injection BGL entries for the given `kind` after the
@@ -289,6 +294,19 @@ export function appendInjection(
           texture: { sampleType: 'depth', viewDimension: '2d' },
         },
       ];
+    case 'transmission':
+      return [
+        {
+          binding: start,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          sampler: { type: 'filtering' },
+        },
+        {
+          binding: start + 1,
+          visibility: GPU_SHADER_STAGE_FRAGMENT,
+          texture: { sampleType: 'float', viewDimension: '2d' },
+        },
+      ];
   }
 }
 
@@ -297,6 +315,7 @@ export const INJECTION_KIND_LENGTHS = {
   shadow: SHADOW_INJECTION_LENGTH,
   ibl: IBL_INJECTION_LENGTH,
   lightmap: LIGHTMAP_INJECTION_LENGTH,
+  transmission: TRANSMISSION_INJECTION_LENGTH,
 };
 
 /**
@@ -347,6 +366,8 @@ export interface PbrCaps {
  * (always-on bindings 5/6 paired with the unconditional `POINT_SHADOW_AVAILABLE`
  * define registered in vite-plugin-shader) +
  * feat-20260613-csm-cascaded-shadow-maps M5 / w28 (binding 7 cascade UBO).
+ *   binding 10 (Points/Lines viewport UBO; always bound for the shared view
+ *   layout and consumed only by the dedicated points-lines shader).
  * Isolated here so M4 round-4 tests can recreate the layout.
  *
  * feat-20260526-pbr-uniform-fallback-no-storage-buffer M3 / w9:
@@ -448,6 +469,11 @@ export function buildPbrViewBglEntries(caps: PbrCaps): GPUBindGroupLayoutEntry[]
       visibility: GPU_SHADER_STAGE_FRAGMENT,
       texture: { sampleType: 'depth', viewDimension: '2d' },
     },
+    {
+      binding: 10,
+      visibility: GPU_SHADER_STAGE_VERTEX,
+      buffer: { type: 'uniform', hasDynamicOffset: true },
+    },
   ];
 }
 
@@ -472,17 +498,16 @@ export function buildPbrPipelineLayouts(
   // D-13 round-2: 4 BGLs route through buildBindGroupLayoutDescriptor.
   // The dispatcher reads kind + caps; spec content is unused without a
   // registry (no shader-axis reflection at this seam — the 4 BGLs are
-  // caps-driven literals + the deterministic Skylight + lightmap merge
+  // caps-driven literals + the deterministic Skylight + transmission merge
   // sequence that has no dependency on shader.id).
   const viewBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-view', caps }),
   );
   if (!viewBglRes.ok) throw viewBglRes.error;
 
-  // Material BGL: derived user region + Skylight + lightmap injection.
-  // feat-20260613 fix-issue-5: drop the buildPbrMaterialEmissiveAoEntries
-  // shim. The lightmap injection start binding is computed from the post-
-  // skylight BGL length (= 14) directly inside appendInjection.
+  // Material BGL: derived user region + Skylight + transmission injection.
+  // The transmission start binding is computed from the post-Skylight BGL
+  // length (= 24 for the built-in Standard schema) by appendInjection.
   const materialBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-material-merged' }),
   );
@@ -535,6 +560,23 @@ export function buildPbrPipelineLayouts(
  * `LayoutKind = 'pbr-skin'` upstream.
  */
 export const SKIN_MATERIAL_SHADER_ID = 'forgeax::pbr-skin' as const;
+export const SHADOW_CASTER_SHADER_ID = 'forgeax::default-shadow-caster' as const;
+
+export function shadowCasterVariantSet(storageBuffer: boolean, skinned: boolean): string {
+  const skinningDisabled = !skinned;
+  if (storageBuffer && skinningDisabled) return '';
+  return `SKINNING_DISABLED=${String(skinningDisabled)}+STORAGE_BUFFER_AVAILABLE=${String(storageBuffer)}`;
+}
+
+export function isSkinnedShadowCasterVariant(
+  materialShaderId: string | undefined,
+  variantSet: string | undefined,
+): boolean {
+  return (
+    materialShaderId === SHADOW_CASTER_SHADER_ID &&
+    variantSet?.includes('SKINNING_DISABLED=false') === true
+  );
+}
 
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
@@ -738,7 +780,7 @@ export const SPRITE_PASS_PER_INSTANCE_REGION_VARIANT_SET = '';
  *
  * Three groups by derivation source:
  * 1. Shader-derived (paramSchema reflection + injection chain):
- *    - `'pbr-material-merged'` — derived user region + Skylight 7 + lightmap 4
+ *    - `'pbr-material-merged'` — derived user region + Skylight 7 + transmission 2
  *    - `'unlit-material'` — 7 entries: base PBR material only (no inject)
  *    - `'hdrp-7-slot'` — 7 entries (binding 0 + 3..8): HDRP cluster + SSAO group(2) BGL
  * 2. Caps-driven literal shapes (no shader):
@@ -845,7 +887,7 @@ export function createHdrpBindGroupLayoutDescriptor(
  * Shader-derived kinds (`'pbr-material-merged'` / `'unlit-material'` /
  * `'hdrp-7-slot'`) require `options.registry` to look up the shader entry
  * and reflect its `paramSchema` via {@link deriveBglShapeFromShader}; they
- * compose the per-entry injection chain (Skylight + lightmap for material;
+ * compose the per-entry injection chain (Skylight + transmission for material;
  * HDRP variantSet for cluster-forward).
  *
  * Caps-driven kinds (`'pbr-view'` / `'pbr-mesh-array'` / `'pbr-instances'` /
@@ -944,7 +986,11 @@ export function buildBindGroupLayoutDescriptor(
         entries: [
           {
             binding: 0,
-            visibility: GPU_SHADER_STAGE_VERTEX,
+            // Standard transmission reads the same per-instance transform in
+            // fs_main to convert glTF unit-space thickness into world metres.
+            // Keep one shared instances BGL and widen its visibility instead
+            // of introducing a second transform upload or six new varyings.
+            visibility: GPU_SHADER_STAGE_VERTEX | GPU_SHADER_STAGE_FRAGMENT,
             buffer: { type: meshBufType, hasDynamicOffset: false },
           },
         ],
@@ -973,24 +1019,24 @@ export function buildBindGroupLayoutDescriptor(
     }
     case 'pbr-material-merged': {
       // Material BGL: per-shader user-region (derive(paramSchema).bglEntries)
-      // + IBL injection (7) + lightmap injection (4). The user-region size is
-      // the only variable; injection start = userRegion.length so a 4-texture
-      // custom schema shifts IBL/lightmap by one sampler/texture pair (D-1).
-      // For the built-in 4-texture standard-PBR schema this is 9 + 7 + 4 = 20.
+      // + IBL injection (7) + transmission injection (2). The user-region
+      // size is the only variable; injection start = userRegion.length so a
+      // custom schema shifts IBL/transmission by its sampler/texture pairs.
+      // The built-in 8-texture standard-PBR schema is 17 + 7 + 2 = 26 entries.
       //
       // Schema source priority (D-1): explicit materialParamSchema option >
       // registry lookup of spec.shader.id > built-in standard-PBR fallback.
       const resolvedSchema = resolveMaterialParamSchema(spec, options);
       const userRegion = buildPbrMaterialUserRegionEntries(resolvedSchema);
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
-      const merged = [...afterIbl, ...appendInjection(afterIbl, 'lightmap')];
+      const merged = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
       return {
         label: 'pbr-material-skylight-bgl',
         entries: merged,
       };
     }
     case 'unlit-material': {
-      // Unlit material BGL: per-shader user-region only. No IBL/lightmap
+      // Unlit material BGL: per-shader user-region only. No IBL/transmission
       // injection (D-5 round-4: unlit demos do not pay for IBL state).
       const resolvedSchema = resolveMaterialParamSchema(spec, options);
       return {
@@ -1005,7 +1051,7 @@ export function buildBindGroupLayoutDescriptor(
       const desc = createHdrpBindGroupLayoutDescriptor(caps.storageBuffer);
       return {
         label: desc.label ?? 'hdrp-unified-bgl-group2',
-        entries: desc.entries ?? [],
+        entries: [...(desc.entries ?? [])],
       };
     }
     case 'fullscreen-post': {