@forgeax/engine-render 0.1.2

package/src/components/light-helpers.ts

@@ -0,0 +1,188 @@
+// @forgeax/engine-render - host-side light helpers (M2 / w12).
+//
+// Pure-function single-shot conversion helpers for the SpotLight + PointLight
+// extract path. Host calls each helper once per light entity per frame; the
+// shader then sees only pre-computed `cos*` / `invRangeSquared` values. The
+// runtime range owner is the revision-pinned Three r184 squared window; KHR
+// values remain an import/reference boundary and are not substituted here.
+//
+// AC anchors: requirements AC-03 (deg -> rad -> cos host two-step
+// conversion) + AC-08 (a + b) (KHR quartic + range = 0 NaN protection
+// boundary).
+//
+// Plan-strategy anchors: D-S2 (cone unit deg API + cos shader optimization
+// transparent to AI users) + D-S5 (Layer 1 host-side range = 0 ->
+// invRangeSquared = 1e8 protects the 0 * Infinity = NaN intermediate).
+
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { SpawnLightInvalidBoundsError } from '../errors';
+import { ShadowInvalidConfigError } from '../errors/render';
+
+export type LightValidationError = SpawnLightInvalidBoundsError | ShadowInvalidConfigError;
+export type LightValidationResult = Result<void, LightValidationError>;
+
+const RANGE_ZERO_FALLBACK_INV_R2 = 1e8;
+const DEG_TO_RAD = Math.PI / 180;
+
+/**
+ * Convert SpotLight cone half-angle (degrees) to its cosine.
+ *
+ * Single-shot deg -> rad -> cos conversion executed once per spot light
+ * entity per frame on the host; the GPU shader sees only `cosInner` /
+ * `cosOuter` so its falloff path stays branch-free
+ * (`smoothstep(cosOuter, cosInner, dot(L, -lightDir))`).
+ *
+ * @param deg cone half-angle in degrees (component schema field
+ *            `innerConeDeg` / `outerConeDeg`)
+ * @returns `cos(deg * pi / 180)`
+ */
+export function degToCos(deg: number): number {
+  return Math.cos(deg * DEG_TO_RAD);
+}
+
+/**
+ * Convert PointLight / SpotLight `range` (meters) to `1 / range^2`.
+ *
+ * Three-branch fold supplies `1 / range^2` for the Three r184 finite-range
+ * window `clamp(1 - (d / range)^4, 0, 1)^2`:
+ *
+ *   - `range = +Infinity` -> `0` (no truncation; quartic factor collapses
+ *     to `1`, falloff reduces to plain `1 / d^2`).
+ *   - `range = 0` -> `1e8` (host safety boundary; glTF `range: 0` is mapped
+ *     to the no-cutoff `Infinity` value before this helper is called).
+ *   - `range > 0` -> `1 / (range * range)` (standard quartic factor).
+ *
+ * @param range meters (component schema field `range`); `+Infinity` is the
+ *              KHR no-truncation default
+ * @returns `1 / range^2` with three-branch NaN protection
+ */
+export function computeInvRangeSquared(range: number): number {
+  if (range === Number.POSITIVE_INFINITY) return 0;
+  if (range === 0) return RANGE_ZERO_FALLBACK_INV_R2;
+  return 1 / (range * range);
+}
+
+/**
+ * feat-20260709 M2 / D-1: shared zero/missing-direction validate for
+ * DirectionalLight + SpotLight. `direction` has no layer-2 default, so an
+ * omitted direction lands the array layer-3 all-zero -- the same illegal state
+ * as an explicit zero vector. SSOT for the rejection so the two lights cannot
+ * drift. Returns the structured error to reject, or `null` when the direction
+ * is a valid non-zero vector.
+ */
+export function validateDirection(
+  componentName: 'DirectionalLight' | 'SpotLight',
+  direction: ArrayLike<number> | undefined,
+): SpawnLightInvalidBoundsError | null {
+  const dir = direction;
+  if (dir === undefined || ((dir[0] ?? 0) === 0 && (dir[1] ?? 0) === 0 && (dir[2] ?? 0) === 0)) {
+    return new SpawnLightInvalidBoundsError(
+      componentName,
+      'direction',
+      dir === undefined ? [0, 0, 0] : [dir[0] ?? 0, dir[1] ?? 0, dir[2] ?? 0],
+    );
+  }
+  return null;
+}
+
+/** Validate directional-light payloads at the render owner boundary. */
+export function validateDirectionalLightData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const directionError = validateDirection(
+    'DirectionalLight',
+    data.direction as ArrayLike<number> | undefined,
+  );
+  if (directionError !== null) return err(directionError);
+  if (data.castShadow === false) return ok(undefined);
+
+  const mapSize = (data.mapSize as number | undefined) ?? 2048;
+  if (mapSize < 1) return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  const cascadeCount = (data.cascadeCount as number | undefined) ?? 4;
+  if (cascadeCount < 1 || cascadeCount > 4 || !Number.isInteger(cascadeCount)) {
+    return err(new ShadowInvalidConfigError('cascadeCount', cascadeCount, 1, 4));
+  }
+  const splitLambda = (data.splitLambda as number | undefined) ?? 0.75;
+  if (splitLambda < 0 || splitLambda > 1) {
+    return err(new ShadowInvalidConfigError('splitLambda', splitLambda, 0, 1));
+  }
+  const cascadeBlend = (data.cascadeBlend as number | undefined) ?? 0.2;
+  if (cascadeBlend < 0 || cascadeBlend > 0.5) {
+    return err(new ShadowInvalidConfigError('cascadeBlend', cascadeBlend, 0, 0.5));
+  }
+  const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
+  if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
+    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+  }
+  const shadowDistance = (data.shadowDistance as number | undefined) ?? 200;
+  if (shadowDistance <= 0) {
+    return err(new ShadowInvalidConfigError('shadowDistance', shadowDistance, 0, '>'));
+  }
+  return ok(undefined);
+}
+
+/** Validate spot-light payloads at the render owner boundary. */
+export function validateSpotLightData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const directionError = validateDirection(
+    'SpotLight',
+    data.direction as ArrayLike<number> | undefined,
+  );
+  if (directionError !== null) return err(directionError);
+  if (data.castShadow === false) return ok(undefined);
+
+  const range = (data.range as number | undefined) ?? 10;
+  if (typeof range !== 'number' || Number.isNaN(range) || range < 0) {
+    return err(new SpawnLightInvalidBoundsError('SpotLight', 'range', range));
+  }
+  const innerConeDeg = (data.innerConeDeg as number | undefined) ?? 0;
+  const outerConeDeg = (data.outerConeDeg as number | undefined) ?? 45;
+  if (outerConeDeg > 90) {
+    return err(new SpawnLightInvalidBoundsError('SpotLight', 'outerNinety', outerConeDeg));
+  }
+  if (outerConeDeg <= innerConeDeg) {
+    return err(new SpawnLightInvalidBoundsError('SpotLight', 'innerOuter', outerConeDeg));
+  }
+  const mapSize = (data.mapSize as number | undefined) ?? 2048;
+  if (mapSize < 1) return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  const nearPlane = data.nearPlane as number | undefined;
+  const farPlane = data.farPlane as number | undefined;
+  if (nearPlane !== undefined && farPlane !== undefined && farPlane <= nearPlane) {
+    return err(new ShadowInvalidConfigError('farPlane', farPlane, nearPlane));
+  }
+  const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
+  if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
+    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+  }
+  return ok(undefined);
+}
+
+/** Validate point-light payloads at the render owner boundary. */
+export function validatePointLightData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const range = (data.range as number | undefined) ?? 10;
+  if (typeof range !== 'number' || Number.isNaN(range) || range < 0) {
+    return err(new SpawnLightInvalidBoundsError('PointLight', 'range', range));
+  }
+  return ok(undefined);
+}
+
+/** Validate point-light shadow payloads at the render owner boundary. */
+export function validatePointLightShadowData(
+  data: Readonly<Record<string, unknown>>,
+): LightValidationResult {
+  const mapSize = (data.mapSize as number | undefined) ?? 512;
+  if (mapSize < 1) return err(new ShadowInvalidConfigError('mapSize', mapSize, 1));
+  const nearPlane = (data.nearPlane as number | undefined) ?? 0.1;
+  const farPlane = (data.farPlane as number | undefined) ?? 25;
+  if (farPlane <= nearPlane) {
+    return err(new ShadowInvalidConfigError('farPlane', farPlane, nearPlane));
+  }
+  const pcfKernelSize = (data.pcfKernelSize as number | undefined) ?? 3;
+  if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
+    return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
+  }
+  return ok(undefined);
+}

package/src/components/mesh-filter.ts

@@ -0,0 +1,59 @@
+// @forgeax/engine-render - MeshFilter (mesh asset reference).
+//
+// Schema: `{ assetHandle: 'shared<MeshAsset>' }`. The schema-vocab
+// `'shared<T>'` keyword stores a u32 column and type-derives to
+// `Handle<'MeshAsset', 'shared'>` (engine-ecs Handle<T,M> twoParam
+// phantom; `'shared'` mode = ref-counted retain on set / release on
+// clear, lifecycle owned by `SharedRefStore` per feat-20260614).
+// The brand prevents cross-asset assignment at compile time (e.g.
+// `Handle<'TextureAsset','shared'>` is not assignable to `assetHandle`).
+//
+// AI users create one `MeshAsset` payload through geometry's primitive
+// factory and intern it in the owning World; the returned shared reference
+// matches the schema-derived `Handle<'MeshAsset', 'shared'>` shape.
+//
+// Naming flavor: unity-style "MeshFilter / MeshRenderer" pair, but the forgeax
+// pair does NOT mirror Unity's filter-toggle semantics - MeshFilter only
+// carries the geometry ref, MeshRenderer only carries the material handle;
+// the pair is independently composable. D-Q7 default-material policy
+// (feat-20260517-merge-mesh-renderer-material-renderer plan-strategy §2.2):
+// case A (entity carries MeshFilter without MeshRenderer) -> archetype
+// query never matches -> entity is silently absent from the
+// RenderableSnapshot[] (NO default-material fallback, NO onError fire);
+// case B (MeshRenderer.material omitted at spawn) -> mid-grey
+// defaultMaterialSnapshot fallback (no onError); case C (material handle
+// unresolved) -> RhiError 'asset-not-registered' (mirrors the
+// MeshFilter.assetHandle dangling-ref path).
+//
+// charter mapping: proposition 1 (single import) + proposition 4 (explicit
+// failure: missing or unregistered handle fires onError 'asset-not-registered'
+// with .detail = { assetHandle } + cross-asset brand mismatch is a TS
+// compile-time error) + proposition 5 (consistent abstraction: the schema
+// vocab `'shared<T>'` is the SSOT for AssetRegistry-owned handles across
+// the engine).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Mesh filter (geometry asset reference).
+ *
+ * `assetHandle` carries a `Handle<'MeshAsset', 'shared'>` (u32-stored)
+ * pointing to a mesh interned by the owning World. Create that reference
+ * with `world.internSharedRef(createPrimitiveMesh('cube').unwrap())` or
+ * with a payload loaded from the App asset registry.
+ *
+ * Error path: if the handle is not registered at draw time, RenderSystem
+ * fires `Renderer.onError` with
+ * `RhiError({ code: 'asset-not-registered', detail: { assetHandle } })`
+ * and skips this entity (other entities continue rendering; charter
+ * proposition 9 graceful degradation).
+ *
+ * @example Spawn an entity referencing a geometry-owned cube mesh:
+ *   import { MeshFilter } from '@forgeax/engine-render';
+ *   import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+ *   const cube = world.internSharedRef(createPrimitiveMesh('cube').unwrap());
+ *   world.spawn({ component: MeshFilter, data: { assetHandle: cube } });
+ */
+export const MeshFilter = defineComponent('MeshFilter', {
+  assetHandle: { type: 'shared<MeshAsset>' },
+});

package/src/components/mesh-renderer.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - MeshRenderer (multi-material array slot).
+//
+// feat-20260608-mesh-multi-section-primitive-multi-material-slot M2 / w7:
+// the single `material` field is replaced with `materials` — an
+// `array<shared<MaterialAsset>>` indexed by MeshAsset.materialSlots. Entries
+// are sparse positional overrides: a missing/zero entry inherits the Mesh
+// slot default, while a defaultless slot inherits the neutral engine material.
+//
+// The schema-vocab keyword `'array<shared<MaterialAsset>>'` (feat-20260614
+// M5 -- migrated from `'array<handle<MaterialAsset>>'`) stores as a u32
+// column slot array; the brand prevents cross-asset assignment at compile
+// time. The `'shared<T>'` arm routes element retain/release through
+// SharedRefStore (M4 / w13) on overwrite / archetype migration.
+//
+// charter mapping: proposition 1 (single import — `MeshRenderer` is the
+// only material-binding component AI users see); proposition 3
+// (machine-readable schema > prose); proposition 4 (explicit failure: the
+// TS brand on `Handle<'MaterialAsset','shared'>` rejects cross-variant
+// assignment at compile time); proposition 5 (consistent abstraction:
+// shading model classification (`'unlit'` / `'standard'`) lives ONLY on
+// the asset discriminant, NOT on the component name).
+//
+// RenderSystem consumption: `render-system-extract.ts` runs ONE archetype
+// query (`world.query(MeshRenderer)`) and routes per entity by
+// `mat.materialShaderId` (shader identity) to the unlit.wgsl or pbr.wgsl
+// pipeline tag.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Mesh renderer (ECS component, multi-material array).
+ *
+ * Stores `materials: readonly Handle<'MaterialAsset','shared'>[]`
+ * (u32-stored array, indexed by MeshAsset.materialSlots). Submeshes point to
+ * those stable slots through `Submesh.materialSlot`. The asset's `passes[].shader`
+ * identity is the SSOT for which pipeline RenderSystem routes the entity
+ * to (record stage dispatches on `materialShaderId`).
+ *
+ * Defaults map carries `materials: []`: every slot inherits its Mesh-owned
+ * default, or the neutral engine material when that slot is intentionally
+ * defaultless.
+ *
+ * @example Spawn while inheriting every Mesh slot default:
+ *   world.spawn({ component: MeshRenderer, data: {} });
+ *
+ * @example Spawn an unlit-targeted entity:
+ *   import { MeshRenderer, Materials } from '@forgeax/engine-render';
+ *   const matPayload = engine.assets.catalog(matGuid, Materials.unlit([1, 0, 0, 1])).value;
+ *   const matHandle = world.allocSharedRef('MaterialAsset', matPayload);
+ *   world.spawn({ component: MeshRenderer, data: { materials: [matHandle] } });
+ *
+ * @example Spawn a standard (PBR) entity:
+ *   const matPayload = engine.assets.catalog(matGuid, Materials.standard({
+ *     baseColor: [0.5, 0.5, 0.5, 1], metallic: 0, roughness: 0.4,
+ *   })).value;
+ *   const matHandle = world.allocSharedRef('MaterialAsset', matPayload);
+ *   world.spawn({ component: MeshRenderer, data: { materials: [matHandle] } });
+ */
+export const MeshRenderer = defineComponent('MeshRenderer', {
+  materials: { type: 'array<shared<MaterialAsset>>', default: [] },
+});

package/src/components/point-light-shadow.ts

@@ -0,0 +1,43 @@
+// @forgeax/engine-runtime — PointLightShadow (omnidirectional point-light
+// shadow mapping parameters; cube-array atlas variant).
+//
+// Schema: 6 f32 columns — mapSize (u32, stored as f32), depthBias, normalBias,
+// nearPlane, farPlane, pcfKernelSize (u32, stored as f32). No fixed-extent
+// field — cube map uses fov=90 perspective, not ortho.
+//
+// Atlas capacity is a renderer policy; ECS does not enforce a component
+// cardinality bound.
+// Co-located with DirectionalLight in components/ (research L1.2).
+//
+// Naming convention: bare entity name (AGENTS.md §Component naming), no
+// Component suffix. Same defineComponent pattern and ShadowInvalidConfigError
+// surface as the shadow fields merged into DirectionalLight (feat-20260621 M1).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Omnidirectional point-light shadow mapping parameters.
+ *
+ * The renderer may batch this component into a bounded atlas, but the ECS
+ * component remains a plain storage schema and carries no cardinality policy.
+ *
+ * @example Spawn a point light with default shadow config:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 4, 0] } },
+ *     { component: PointLight, data: { range: 25 } },
+ *     { component: PointLightShadow, data: {} }, // 6 fields filled from defaults
+ *   );
+ *
+ * @example Spawn with explicit map size and bias:
+ *   world.spawn(
+ *     { component: PointLightShadow, data: { mapSize: 1024, depthBias: 0.01 } },
+ *   );
+ */
+export const PointLightShadow = defineComponent('PointLightShadow', {
+  mapSize: { type: 'f32', default: 512 },
+  depthBias: { type: 'f32', default: 0.005 },
+  normalBias: { type: 'f32', default: 0.05 },
+  nearPlane: { type: 'f32', default: 0.1 },
+  farPlane: { type: 'f32', default: 25 },
+  pcfKernelSize: { type: 'f32', default: 3 },
+});

package/src/components/point-light.ts

@@ -0,0 +1,65 @@
+// @forgeax/engine-render - PointLight (omnidirectional point-light parameters).
+//
+// Schema: color array<f32,3> + intensity f32 + range f32 (feat-20260709 M2:
+// color collapsed from 3 per-axis scalar columns to one inline array<f32,3>).
+// `position` comes from the Transform component; PointLight requires a
+// companion Transform on the same entity (ECS query: `[Transform, PointLight]`).
+// `range` units are meters; defaults to `10.0`. Runtime finite-range
+// attenuation is the Three r184 squared window; the KHR unsquared curve is an
+// import/reference boundary only. See `light-helpers.ts` for the host-side
+// range projection.
+//
+// 0 light + standard material -> physically correct black render
+// (feat-20260518-pbr-direct-lighting-mvp). The runtime once-warn channel
+// (M5 / w25) collapses to "directionalCount + pointCount + spotCount === 0";
+// see packages/runtime/README.md section Common pitfalls for the AI-user
+// guidance after the M5 docs land.
+//
+// Naming convention: bare entity name aligned with Bevy ECS conventions
+// (feat-20260513-component-naming-bevy-align). DirectionalLight / SpotLight
+// follow the same single-semantic-entity rule (charter proposition 5).
+//
+// charter mapping: proposition 1 (single import + IDE autocomplete on
+// payload.range) + proposition 3 (silent failure -> explicit failure;
+// spawn-time fail-fast on range<0 / NaN with structured EcsError) +
+// proposition 5 (consistent abstraction: shared payload shape with
+// SpotLight; `range` semantics aligned with KHR_lights_punctual).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Omnidirectional point light (KHR_lights_punctual `point` type).
+ *
+ * `position` source: the companion `Transform` component on the same entity.
+ * Spawn via `world.spawn({ component: Transform, data: ... }, { component: PointLight, data: ... })`
+ * so the render system extract path can join the two via the
+ * `[Transform, PointLight]` ECS query.
+ *
+ * `color` is linear-space rgb in `[0, 1]` per channel; `intensity` is candela;
+ * `range` is in meters and defaults to `10.0`
+ * (KHR convention; `+Infinity` is the KHR no-truncation value, retained
+ * for KHR_lights_punctual `range: 0` bridging via `light-helpers.ts`).
+ * The runtime window is `clamp(1 - (d / range)^4, 0, 1)^2`; its no-cutoff
+ * boundary uses inverse-square decay with the shader safety floor. Exposure is
+ * applied after lighting and never multiplied into intensity.
+ *
+ * @example Spawn a single point light at (5, 3, 5):
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [5, 3, 5] } },
+ *     { component: PointLight, data: { intensity: 8, range: 25 } },
+ *   );
+ *
+ * @example Minimal spawn -- defaults give neutral white at full strength, range 10m:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 1, 0] } },
+ *     { component: PointLight, data: {} },
+ *   );
+ *   // resolves to color=[1, 1, 1], intensity=1, range=10.0.
+ */
+export const PointLight = defineComponent('PointLight', {
+  // color carries an explicit layer-2 default [1,1,1] (white); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1 },
+  range: { type: 'f32', default: 10.0 },
+});

package/src/components/post-process-params.ts

@@ -0,0 +1,35 @@
+// @forgeax/engine-render - PostProcessParams component.
+//
+// Schema: { shader: 'string', data: 'buffer' }.
+//
+// `shader` identifies the fullscreen post-process shader (the same id as passed to
+// `renderer.postProcess.register(id, entry)`). `data` carries the per-frame params
+// bytes as a variable-byte ECS managed buffer slot. The write side (world.spawn /
+// world.set) accepts any AllowSharedBufferSource (Float32Array / ArrayBuffer /
+// Uint8Array / any TypedArray) and the ECS normalizes it to Uint8Array bytes
+// (feat-20260621 V2 / AC-A4); the read side (world.get) returns Uint8Array, which
+// satisfies AllowSharedBufferSource for GPU queue.writeBuffer ingestion.
+//
+// Single-semantic component — drops the `Component` suffix
+// (AGENTS.md §Component naming rule #1). The `data` field uses the ECS 'buffer'
+// vocab keyword (plan-strategy D-7) for variable-byte storage.
+//
+// Data flow (plan-strategy D-1):
+//   extract -> iterate PostProcessParams-bearing entities ->
+//   collect into Map<shaderId, AllowSharedBufferSource> snapshot ->
+//   dispatchFullscreenPass picks up per-shader data -> writeBuffer to eager UBO.
+//
+// Decision anchors:
+//   - requirements AC-A2 (data-driven, no imperative renderer.setParams mutator)
+//   - requirements AC-A4 (AllowSharedBufferSource type on the data field)
+//   - plan-strategy D-1 (new single-semantic ECS component for params)
+//   - plan-strategy D-7 (ECS 'buffer' vocab keyword for variable-byte storage)
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+const schema = {
+  shader: 'string',
+  data: 'buffer',
+} as const;
+
+export const PostProcessParams = defineComponent('PostProcessParams', schema);

package/src/components/scene-instance.ts

@@ -0,0 +1,193 @@
+// @forgeax/engine-runtime - SceneInstance component (feat-20260608-
+// scene-nesting-ecs-fication M2 / w16).
+//
+// Single ECS fat component carrying everything that used to live on the
+// old `SceneInstance` + `SceneInstanceContainer` pair (deleted
+// in M3). Schema fits the ECS schema vocab (3 single-identifier fields):
+//
+//   { source:  'shared<SceneAsset>',
+//     mapping: 'array<entity>',
+//     state:   'unique<SceneInstanceState>' }
+//
+// `source` carries the SceneAsset handle the synthetic root entity was
+// instantiated from (Tier-A AssetUnion handle, AGENTS.md §Assets submodule).
+// `mapping` is the LocalEntityId -> Entity table indexed positionally
+// (mapping[localId] = spawned Entity); the ECS variable-array column gives
+// us a SoA-friendly read path for query<SceneInstance> scans without
+// touching the dynamic Map/Set state.
+// `state` is a `ref<SceneInstanceState>` slot — World holds the live
+// SceneInstanceState payload in its UniqueRefStore and World despawn
+// auto-releases the ref u32 (the same path used by audio / physics
+// payloads, plan-strategy §D-2). Each instantiateScene call calls
+// `world.allocUniqueRef('SceneInstanceState', state)` once and stores the
+// returned u32 in this column.
+//
+// Decision anchors:
+//   - plan-strategy §D-2 (single ref wraps SceneInstanceState dynamic
+//     structure; ECS schema vocab `\w+` rejects `ref<Map<...>>`)
+//   - plan-strategy §3.2 sequence (sequence diagram step 'set ... state:
+//     {entityToLocalId, detached, overrides, rootEntities}')
+//   - AGENTS.md §Component naming rule #1 (single-semantic component drops
+//     `Component` suffix)
+//   - charter F1 (single-import barrel: SceneInstance lives in
+//     `@forgeax/engine-render` next to Transform / Camera / DirectionalLight)
+//   - charter P3 (machine-readable schema: 3 closed fields)
+//   - charter P4 (consistent abstraction: instance == entity carrying
+//     SceneInstance — same `world.query({ read: [SceneInstance] })` /
+//     `world.get(root, SceneInstance)` path as any other component)
+
+import { defineComponent, type EntityHandle } from '@forgeax/engine-ecs';
+import type { LocalEntityId, MountOverride } from '@forgeax/engine-types';
+
+/**
+ * Per-component, per-field override record carried in `SceneInstanceState`.
+ *
+ * Composite key `<componentName>:<fieldName>` keeps the override map flat
+ * (single Map nesting level) so AI users walking `state.overrides` see one
+ * iteration depth — D-2 prefers a single SSOT over multi-Map nesting that
+ * would make iteration order ambiguous (charter F1: single mental model).
+ *
+ * The value is `unknown` because the per-component schema vocab lives in the
+ * ECS layer; runtime fail-fast via `EcsErrorCode = 'scene-override-type-
+ * mismatch'` (plan-strategy §D-9) catches type drift on the apply path.
+ *
+ * @internal Surface from `state.overrides` only; AI users never construct a
+ *   record directly. Use `worldSetSceneOverride(world, root, member, comp,
+ *   field, value)` to write and `worldRemoveSceneOverride(world, root, member,
+ *   comp, field)` to roll back to the source SceneAsset value.
+ */
+export interface SceneInstanceOverrideRecord {
+  readonly comp: string;
+  /**
+   * Component-granular add-or-patch discriminant (feat-20260713 M1 / w4):
+   * present -> this record patches a single field; absent -> it adds/upserts
+   * the whole `comp` (M2 apply semantics). Mirrors `MountOverride.field`.
+   */
+  readonly field?: string;
+  readonly value: unknown;
+}
+
+/**
+ * Dynamic state payload for one SceneInstance — held in the World's
+ * UniqueRefStore behind a `ref<SceneInstanceState>` slot on the synthetic
+ * root entity. Mirrors the old class-based layout (plan-strategy §D-2 +
+ * design doc §11.2 internal-state-table) but flattened into plain JS Maps/Sets so
+ * AI users can iterate without indirection.
+ *
+ * Lifecycle:
+ *   - allocated by `worldInstantiateScene(world, handle, parent?)` — the W in
+ *     `world.allocUniqueRef('SceneInstanceState', state)` returns the u32
+ *     slot id stored in the SceneInstance.state column;
+ *   - released by `world.despawn(root)` (the standard `ref<T>` release loop)
+ *     or explicitly via `worldDespawnScene(world, root)` / `worldDespawnDescendants(world, root)`.
+ *
+ * AI users typically reach this struct only through the read path
+ * `world.get(root, SceneInstance).state.overrides.get(<comp>:<field>)` for
+ * inspection; mutation happens through the 8 World methods.
+ */
+export interface SceneInstanceState {
+  /**
+   * SceneAsset handle the instance was instantiated from. Mirrors the
+   * SceneInstance.source column for AI users who already have a
+   * SceneInstanceState in hand and want the source handle without a second
+   * `world.get` round-trip.
+   */
+  readonly source: import('@forgeax/engine-types').Handle<'SceneAsset', 'shared'>;
+
+  /**
+   * Reverse mapping (live `Entity` -> source `LocalEntityId`). Used by
+   * `worldSetSceneOverride` to validate the member entity belongs to this
+   * instance + by `worldDetachSceneMember` / `worldReattachSceneMember`
+   * to translate caller-side Entity values back to their authored localId.
+   */
+  readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+
+  /**
+   * LocalEntityIds of members the AI user marked detached via
+   * `worldDetachSceneMember(world, root, member)`. The member entities stay
+   * alive in the World; only the bookkeeping marker moves so
+   * `worldDespawnDescendants(world, root, { keepDetached: true })` can skip them.
+   * Detach is idempotent (set semantics).
+   */
+  readonly detachedLocalIds: Set<LocalEntityId>;
+
+  /**
+   * Per-member runtime overrides keyed by `<localId>` -> `<comp>:<field>`
+   * -> override record. mount-time overrides (authored on the SceneAsset's
+   * `mounts[].overrides`) populate this map at instantiate-time so AI
+   * users see them via the same read path as runtime
+   * `setSceneOverride` writes (single SSOT).
+   */
+  readonly overrides: Map<LocalEntityId, Map<string, SceneInstanceOverrideRecord>>;
+
+  /**
+   * Top-level root entities of the materialised tree (members without a
+   * ChildOf parent at instantiate time). The synthetic root entity that
+   * carries the SceneInstance component itself is NOT in this list — it is
+   * the parent of every member entity (plan-strategy §3.2 sequence step 7).
+   */
+  readonly rootEntities: EntityHandle[];
+
+  /** Synthetic roots of recursively mounted SceneAssets owned by this instance. */
+  readonly mountRoots: EntityHandle[];
+
+  /**
+   * Total slot count `entities.length + sum(mounts[].memberCount)` —
+   * captured at instantiate-time so cycle / count consistency checks
+   * (e.g. `worldGetSceneAssetForInstance(world, root)` symmetry) can compare
+   * against the live SceneInstance.mapping column without re-reading the
+   * SceneAsset.
+   */
+  readonly totalSlots: number;
+
+  /**
+   * Mount-time override authored on the parent SceneAsset's `mounts[]`
+   * record. Captured at instantiate-time so `worldRemoveSceneOverride`
+   * can fall back to the mount-time value before going to the source
+   * SceneAsset value (plan-strategy §D-2).
+   */
+  readonly mountTimeOverrides: readonly MountOverride[];
+}
+
+/**
+ * SceneInstance ECS component — synthetic root entity payload for one
+ * materialised SceneAsset (instance == entity carrying SceneInstance,
+ * charter P4).
+ *
+ * AI users discover the component via IDE autocomplete on
+ * `@forgeax/engine-render` (single-import barrel; AGENTS.md §Components):
+ *
+ * ```ts
+ * import { SceneInstance } from '@forgeax/engine-render';
+ * for (const row of world.query({ read: [SceneInstance] }).unwrap()) {
+ *   console.log(`root=${row.entity} source=${row.get(SceneInstance).source}`);
+ * }
+ *
+ * const inst = world.get(root, SceneInstance).value;
+ * const memberEntity = inst.mapping[localId]; // Uint32Array snapshot
+ * for (const detached of inst.state.detachedLocalIds) { /* ... *\/ }
+ * ```
+ *
+ * The component does not register a relationship — synthetic root +
+ * members are wired through the standard `ChildOf` (member -> root) so
+ * the existing `world.iterDescendants(root)` / Children mirror code paths
+ * apply unchanged (plan-strategy §D-5).
+ *
+ * @example Materialise + inspect a SceneAsset:
+ *   const { root, diagnostics } = worldInstantiateScene(world, handle).value;
+ *   const inst = world.get(root, SceneInstance).value;
+ *   // inst.source === handle, inst.mapping is Uint32Array(totalSlots)
+ *   // inst.state holds entityToLocalId / detachedLocalIds / overrides /
+ *   // rootEntities / mountRoots / totalSlots / mountTimeOverrides.
+ */
+export const SceneInstance = defineComponent(
+  'SceneInstance',
+  {
+    source: { type: 'shared<SceneAsset>' },
+    mapping: { type: 'array<entity>' },
+    // The unique slot is the ECS storage seam for the instance's structured
+    // runtime payload; keep the nested semantic visible to schema consumers.
+    state: { type: 'unique<SceneInstanceState>', shape: 'nested' },
+  },
+  { transient: true },
+);