@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/components/glyph-text.ts

@@ -0,0 +1,64 @@
+// @forgeax/engine-runtime - GlyphText component (feat-20260531-world-space-msdf-text-rendering M4 / w14).
+//
+// `GlyphText` is the authoring source component for world-space MSDF text
+// (requirements AC-06 / §domain model). It carries ONLY authoring data; the
+// glyph quad baking + MeshFilter / MeshRenderer attachment is the job of the
+// `glyphTextLayoutSystem` (plan-strategy D-2: GlyphText is pure authoring
+// data, baking is a system responsibility). There is NO `TextLayoutAsset`
+// intermediate (OOS-5) -- layout output lives directly in a baked MeshAsset.
+//
+// Naming: single-semantic component drops the `Component` suffix
+// (AGENTS.md §Component naming rule #1 -- Transform / Camera / GlyphText).
+//
+// Schema vocab:
+//   - `fontHandle: 'shared<FontAsset>'` -> `Handle<'FontAsset', 'shared'>`
+//     (u32-stored; AssetRegistry owns the FontAsset lifecycle). AI users
+//     obtain the handle via `assets.loadByGuid<FontAsset>(guid)`.
+//   - `text: 'string'` -> native JS string (UniqueRefStore-backed, same
+//     dispatch as `Name.value`).
+//   - `fontSize: 'f32'` -> layout scale applied to the FontAsset metrics.
+//   - `color: 'array<f32, 4>'` -> linear-space rgba tint (feat-20260709 M3:
+//     collapsed from four `colorR/G/B/A` scalar columns into one inline
+//     stride-4 SoA column, mirroring the DirectionalLight direction/color
+//     idiom). Explicit layer-2 default [1,1,1,1] (opaque white).
+//
+// charter mapping: P1 (single import surface from `@forgeax/engine-render`,
+// co-located with `glyphTextLayoutSystem` that consumes it) + P3
+// (machine-readable schema literal) + P5 (consistent abstraction: same
+// `'shared<T>'` idiom as MeshFilter.assetHandle / MeshRenderer.materials).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Glyph text authoring component (world-space MSDF text).
+ *
+ * Spawn an entity with a `GlyphText` and the `glyphTextLayoutSystem`
+ * (auto-wired by `createRenderer` / `createApp`) lays out the glyph quads,
+ * bakes a `MeshAsset`, and attaches `MeshFilter` + `MeshRenderer` on the
+ * next frame (Commands-deferred). Mutating `text` / `fontSize` / `color`
+ * re-bakes the mesh in place (plan-strategy D-1 updateMesh; registry size
+ * unchanged, AC-08).
+ *
+ * @example Spawn a world-space label:
+ *   import { GlyphText } from '@forgeax/engine-render/authoring';
+ *   const font = (await assets.loadByGuid(fontGuid)).unwrap();
+ *   world.spawn({
+ *     component: GlyphText,
+ *     data: { fontHandle: font, text: 'Hello', fontSize: 32,
+ *             color: [1, 1, 1, 1] },
+ *   });
+ */
+export const GlyphText = defineComponent('GlyphText', {
+  // The layout/render owner re-resolves the font asset on the target world;
+  // authoring text and style remain portable simulation state.
+  fontHandle: {
+    type: 'shared<FontAsset>',
+    default: 0 as never,
+    simulationTransient: true,
+  },
+  text: { type: 'string', default: '' },
+  fontSize: { type: 'f32', default: 16 },
+  // color carries an explicit layer-2 default [1,1,1,1] (opaque white); the
+  // array layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: 'array<f32, 4>', default: new Float32Array([1, 1, 1, 1]) },
+});

package/src/components/index.ts

@@ -0,0 +1,54 @@
+export * from './camera';
+export * from './directional-light';
+export { Instances, type InstancesData } from './instances';
+export { Layer } from './layer';
+export { Lines } from './lines';
+export * from './mesh-filter';
+export * from './mesh-renderer';
+export { PointLight } from './point-light';
+export { PointLightShadow } from './point-light-shadow';
+export {
+  type PointShape,
+  PointShapeValue,
+  Points,
+  pointShapeFromU32,
+} from './points';
+export { PostProcessParams } from './post-process-params';
+export {
+  SceneInstance,
+  type SceneInstanceOverrideRecord,
+  type SceneInstanceState,
+} from './scene-instance';
+export {
+  SKYBOX_MODE_CUBEMAP,
+  SkyboxBackground,
+  type SkyboxMode,
+  skyboxModeFromF32,
+} from './skybox-background';
+export { Skylight } from './skylight';
+export { SortKey } from './sort-key';
+export { SpotLight } from './spot-light';
+export { SpriteAnimation } from './sprite-animation';
+export { SpriteInstances, type SpriteInstancesData } from './sprite-instances';
+export {
+  SPRITE_PLAYBACK_MODE_CLAMP,
+  SPRITE_PLAYBACK_MODE_LOOP,
+  type SpritePlaybackMode,
+  spritePlaybackModeFromU32,
+} from './sprite-playback-mode';
+export { SpriteRegionOverride } from './sprite-region-override';
+export {
+  decodeSortScope,
+  encodeSortScope,
+  markTileLayerDirty,
+  type SortScope,
+  TileLayer,
+  type TileLayerData,
+} from './tile-layer';
+export { Tilemap } from './tilemap';
+export {
+  Visibility,
+  type VisibilityState,
+  VisibilityStateValue,
+  visibilityStateFromU32,
+} from './visibility';

package/src/components/instances.ts

@@ -0,0 +1,206 @@
+// @forgeax/engine-render - Instances component (per-entity instanced-draw transforms).
+//
+// Two sources, one component (feat-20260622-chunk-gpu-instancing-sprite-tilemap
+// / AC-09; charter P4 consistent abstraction + charter P1 progressive disclosure).
+// The `Instances` ECS component has exactly TWO sources of `transforms` data, and
+// AI users should hold the boundary explicitly to avoid misreading the ECS view:
+//
+//   Source 1 (EXPLICIT, the only source that lands in ECS) — AI user opt-in.
+//     The AI user hand-attaches `Instances { transforms }` onto an entity at
+//     spawn / set time for high-performance instanced draw. `world.get(e,
+//     Instances)` returns the AI user's payload verbatim (a `Float32Array`
+//     snapshot of column-major mat4 instances; stride = 16). This is the sole
+//     code path through which `Instances` ever appears on an entity.
+//
+//   Source 2 (TRANSPARENT, never written back into ECS) — engine record-stage
+//     fold. When the AI user spawns N independent sprite / tilemap-cell
+//     entities sharing the same (Layer.value, posZ, materialHandle) sort
+//     equivalence class, the engine record stage transparently folds the
+//     equivalent run into ONE `drawIndexed(indexCount, count)` using an
+//     INTERNAL transient buffer (see `render-system-record.ts` fold operator
+//     + `render.instancing.foldedDraws` metric, and the `RhiError
+//     'instancing-exceeds-uniform-cap'` fallback). The fold operator does
+//     NOT auto-inject `Instances` onto those entities — `world.get(e,
+//     Instances)` on a folded entity returns `Result.err` exactly as before.
+//     The ECS view is preserved bit-for-bit (per-cell / per-sprite entity
+//     retained, query / despawn / picking unchanged); the optimisation is
+//     invisible at the component layer (charter P4: consistent abstraction —
+//     the high-performance path is opt-in via Source 1, the default spawn
+//     shape stays untouched).
+//
+// AI user reading this header: do NOT expect engine-side fold to materialise
+// as an `Instances` row on your entity. Read the metric (foldedDraws) or the
+// RhiError code to observe fold behaviour; never gate logic on a runtime
+// `world.get(e, Instances)` lookup after spawn.
+//
+// Schema: 1 array<f32> field `transforms` carrying packed column-major mat4
+// instance transforms (16 f32 per instance, stride = 16). Stride is enforced
+// through a TWO-LAYER contract:
+//
+//   1. AI user set-site: spawn / `world.set` / `world.push` callers pass a
+//      `Float32Array` (or numeric array) whose `length` is a non-zero
+//      multiple of 16. The set site is the AI user's responsibility -- the
+//      engine cannot prove the column-major mat4 packing without the
+//      caller's intent.
+//   2. RenderSystem extract entry: `render-system-extract.ts` performs a
+//      defensive `transforms.length % 16 === 0` check on every
+//      `world.get(e, Instances).transforms` snapshot at frame extract time;
+//      violations route a structured `InstanceTransformsStrideMismatchError`
+//      (`code: 'instance-transforms-stride-mismatch'`,
+//      `detail: { actualLength, expectedStride: 16 }`) through the World
+//      Layer-3 ErrorHandler and the renderable is skipped (fail-fast: the
+//      malformed length never reaches the GPU upload path).
+//
+// feat-20260515-buffer-array-vocab-collapse M3 / w16 (decision §2.3 stride
+// responsibility migration): the legacy component-level
+// stride-declaration option (`{ transforms: 16 }` keyed on the retired
+// per-component stride defineComponent option key) was retired because:
+//   - The ECS layer no longer carries a per-component stride schema (M2 /
+//     w9 dropped the option from `DefineComponentOptions` -- the SSOT
+//     moved to the RenderSystem entry + AI user set site).
+//   - Centralising the check at the consumer (RenderSystem extract) rather
+//     than the producer (ECS write paths) lets the GPU upload path stay
+//     trust-the-snapshot; AI users get one structured error per offending
+//     frame rather than one per write.
+//
+// feat-20260514-ecs-children-instances-managed-buffer-array M3 / w14:
+// migrated from the legacy `{ buffer: 'ref', count: 'u32' }` pair (which
+// cross-coupled with the now-deleted `AssetRegistry.createInstancedBuffer`
+// pipeline + the `InstancedBufferAsset` POD) to the ECS-managed array path.
+// Resize is a `world.push(e, Instances, 'transforms', value)` away (one f32
+// at a time) plus a future `world.grow` if a bulk-resize affordance is
+// added.
+//
+// Storage buffer cap-gate (D-5 OOS-08 follow-up):
+//   - The runtime RenderSystem consumer (`render-system-record.ts`) checks
+//     `device.caps.storageBuffer` before binding the per-entity transforms;
+//     `caps.storageBuffer === false` (backend lacking storage buffer support,
+//     e.g. rhi-wgpu webgl backend) routes a `RhiError` ('feature-not-enabled').
+//     A future loop owns the per-draw fallback path.
+//
+// Group transform chained semantics (charter proposition 5 mental migration):
+//   - When the same entity carries both `Transform` (entity_world) and
+//     `Instances` (per-instance local transforms), the vertex shader
+//     composes per instance:
+//
+//       world_position[i] = entity_world * instances_local[i] * vertex_position
+//
+//   - `Instances.transforms[i*16..i*16+15]` is interpreted as a local-space
+//     transform under the entity, exactly like a child entity's `Transform`
+//     under `ChildOf { parent }` in the hierarchy system. AI users reuse
+//     the `parent x local` intuition without a new concept. Set the
+//     entity's `Transform` to identity to make `instances_local[i]`
+//     directly world-space.
+//
+// 4-segment minimum contract (read this header before reaching for
+// the source body):
+//
+// ===== (a) single-component import + spawn example =====
+//
+//   import {
+//     createRenderer, HANDLE_CUBE,
+//     MeshFilter, MeshRenderer, Transform,
+//     Instances, type InstancesData,
+//   } from '@forgeax/engine-render';
+//
+//   // 1 entity rendering N instanced cubes (16N packed f32, column-major mat4):
+//   const transforms = new Float32Array(N * 16);
+//   // ... fill column-major mat4 columns per instance ...
+//   world.spawn(
+//     { component: MeshFilter,    data: { assetHandle: HANDLE_CUBE } },
+//     { component: MeshRenderer,  data: {} },
+//     { component: Instances,     data: { transforms } },
+//   );
+//
+// ===== (b) packed mat4 layout =====
+//
+//   const transforms = new Float32Array(N * 16); // column-major mat4 per instance
+//   // instance i occupies floats [i*16 .. i*16+15]:
+//   //   [m00 m10 m20 m30   <- column 0
+//   //    m01 m11 m21 m31   <- column 1
+//   //    m02 m12 m22 m32   <- column 2
+//   //    m03 m13 m23 m33]  <- column 3 (translation in m03/m13/m23)
+//
+// `transforms.length` MUST be a non-zero multiple of 16. AI users gate at
+// the set / push site; the RenderSystem extract entry holds the second
+// defensive (AC-06: detail carries `{ expectedStride: 16, actualLength }`).
+// The instance count is the live snapshot length / 16.
+//
+// ===== (c) error code consumption (typed property access, no message regex) =====
+//
+//   // Stride violation surfaces through the engine-ecs Layer-3 ErrorHandler
+//   // when extract reads a malformed snapshot:
+//   //   on('error', (err) => {
+//   //     if (err.code === 'instance-transforms-stride-mismatch') {
+//   //       // err.detail.expectedStride === 16
+//   //       // err.detail.actualLength === <user-supplied length>
+//   //     }
+//   //   });
+//   //
+//   // RenderSystem cap-gate (D-5) -> RhiError 'feature-not-enabled' on the
+//   // RhiErrorListenerRegistry channel:
+//   //   on('error', (err) => {
+//   //     if (err.code === 'feature-not-enabled') {
+//   //       console.warn(err.expected, err.hint);
+//   //     }
+//   //   });
+//
+// charter mapping: proposition 1 (single import surface
+// `import { Instances, type InstancesData } from '@forgeax/engine-render'`);
+// proposition 3 (machine-readable schema > prose:
+// `{ transforms: 'array<f32>' }` is the SSOT, stride 16 documented here +
+// enforced at the RenderSystem entry);
+// proposition 4 (explicit failure: stride violation routes a structured
+// EcsError, not a silent half-row); proposition 5 (consistent abstraction:
+// Instances mirrors Children -- both ride the array-vocab path).
+//
+// Anchors: requirements §AC-06 (stride 16 + RenderSystem upload path);
+// plan-strategy §2.3 (stride responsibility migration to RenderSystem entry
+// defensive + AI user set site) + §3.3 stride error path; plan-decisions
+// D-1 / D-5.
+// OOS-09 (no addChild Commands API) does not apply here; OOS-01 (no
+// dangling-entity sweep) does not apply (Instances stores f32 not entity).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity instanced-draw transforms (ECS component).
+ *
+ * Carries a variable-length `array<f32>` of column-major mat4 instance
+ * transforms (16 f32 per instance, stride = 16; documented above and
+ * enforced at the RenderSystem extract entry, NOT at the ECS write paths).
+ *
+ * The runtime RenderSystem consumer materialises a fresh `Float32Array`
+ * snapshot on every `world.get(e, Instances).transforms` access (D-4
+ * no-cache), reads the live count from the snapshot's `length`, and
+ * uploads the bytes to a per-entity GPU storage buffer in the record stage
+ * (`render-system-record.ts`).
+ *
+ * @example Spawn an entity rendering 10000 instanced cubes:
+ *   const transforms = new Float32Array(10000 * 16);
+ *   // ... fill column-major mat4 columns ...
+ *   world.spawn(
+ *     { component: MeshFilter,   data: { assetHandle: HANDLE_CUBE } },
+ *     { component: MeshRenderer, data: { ... } },
+ *     { component: Instances,    data: { transforms } },
+ *   );
+ */
+export const Instances = defineComponent('Instances', {
+  transforms: { type: 'array<f32>' },
+});
+
+/**
+ * Type-level hint for `data` at the `Instances` spawn site.
+ *
+ * The runtime ECS column shape for `array<f32>` accepts a `Float32Array`
+ * payload at spawn / set time (the bytes are copied into the BufferPool
+ * slot). The `transforms` field is documented as `Float32Array` here so
+ * AI-user IDE autocomplete picks up the typed-array shape.
+ *
+ * @example
+ *   import type { InstancesData } from '@forgeax/engine-render';
+ *   const data: InstancesData = { transforms: new Float32Array(N * 16) };
+ */
+export type InstancesData = {
+  readonly transforms: Float32Array;
+};

package/src/components/layer.ts

@@ -0,0 +1,69 @@
+// @forgeax/engine-render - Layer (render-order layer index, signed 32-bit).
+//
+// Schema: 1 i32 column (value). Signed two's complement so negatives travel
+// through the spawn payload unchanged — background sprites live at negative
+// values (e.g. -100), the default game layer at 0, foreground at 100, UI at
+// 1000. Layer is consumed at sort time by `transparent-sort.ts` (M-3 w23)
+// as the primary key in the (layer asc, sortValue asc) composite ordering.
+//
+// Naming convention: bare entity name (no Component suffix; single-semantic
+// component idiom aligned with Bevy ECS conventions — Transform / Camera /
+// DirectionalLight follow the same shape, see AGENTS.md §Component naming).
+//
+// Layer is a generic ECS renderer component — NOT a 2D-only special. 3D
+// entities may also carry Layer to bias their bucket placement (charter
+// P4 consistent abstraction: same component drives both pipelines).
+//
+// AC-18 path (1): an entity spawned without an explicit Layer reads back
+// 0 via the existing 4-layer spawn fallback chain
+// (feat-20260517-spawn-default-fallback). This feat does NOT introduce a
+// fifth fallback layer; the silent default flows through layer-3
+// `typeDefault('i32') === 0`.
+//
+// @derives defineComponent factory (packages/ecs/src/component.ts) — i32
+//   is a legacy scalar type; its intrinsic properties (byteSize / viewCtor
+//   / storage) live in TYPE_METADATA['i32'] (feat-20260602 M1).
+// @reuses spawn 4-layer fallback chain (feat-20260517-spawn-default-fallback)
+//   — layer-3 typeDefault('i32') returns 0, no fifth layer.
+//
+// charter mapping: F1 (single-import barrel discovery — Layer joins
+// Transform / MeshFilter / MeshRenderer / Camera / DirectionalLight)
+// + P3 (explicit default — 0 surfaces as a read-back value, not undefined)
+// + P4 (consistent abstraction — Layer is a generic render component, not
+// a 2D-only special).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Render-order layer index.
+ *
+ * Convention (non-binding; conveys intent, not enforced):
+ *   - negative (e.g. -100): background layers (sky / parallax tiles).
+ *   - 0: default game layer.
+ *   - positive (e.g. 100): foreground layers (overlays, FX).
+ *   - 1000+: UI / HUD.
+ *
+ * Signed i32 (two's complement, range \u00b12\u00b3\u00b9). Negatives round-trip
+ * through the spawn payload unchanged — no schema-layer mutate. i32 lives in
+ * the CPU sort path (transparent-sort.ts M-3 w23); no GPU-side stride
+ * compatibility risk.
+ *
+ * @example Minimal spawn (defaults to game layer 0):
+ *   world.spawn({ component: Layer, data: {} }); // yields value=0
+ *
+ * @example Spawn 4 sprites across the conventional layer band:
+ *   world.spawn({ component: Layer, data: { value: -100 } }); // background
+ *   world.spawn({ component: Layer, data: { value: 0 } });    // default
+ *   world.spawn({ component: Layer, data: { value: 100 } });  // foreground
+ *   world.spawn({ component: Layer, data: { value: 1000 } }); // UI
+ *
+ * @example Spawn payload omitting Layer — the 4-layer fallback fills 0:
+ *   const e = world.spawn(
+ *     { component: Transform, data: { pos: [0, 0, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *   );
+ *   // Layer is not on the entity; query joins must check membership.
+ */
+export const Layer = defineComponent('Layer', {
+  value: { type: 'i32', default: 0 },
+});

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/ecs-validation';
+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/lines.ts

@@ -0,0 +1,18 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Screen-space independent line segment style. */
+export const Lines = defineComponent(
+  'Lines',
+  {
+    widthPx: { type: 'f32', default: 1 },
+  },
+  {
+    meta: {
+      quickStart: 'Attach Lines to render line-list MeshAsset pairs in screen pixels.',
+      diagnostics: 'Inspect widthPx at the points-lines admission boundary.',
+      recovery: 'Use points-lines-invalid-style for non-finite or non-positive widthPx values.',
+      boundaries:
+        'Lines owns raster width only; MeshFilter and MeshRenderer own geometry and material.',
+    },
+  },
+);

package/src/components/mesh-filter.ts

@@ -0,0 +1,60 @@
+// @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 spawn with the assets-runtime constants `HANDLE_CUBE` /
+// `HANDLE_TRIANGLE` (now branded `Handle<'MeshAsset','shared'>` to
+// match the schema-derived shape); custom mesh registration is owned by
+// feat-future-asset-system (this MVP only exposes builtin handles).
+//
+// 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 into `engine.assets: AssetRegistry`. Use the predefined
+ * constants `HANDLE_CUBE` / `HANDLE_TRIANGLE` exported from
+ * `@forgeax/engine-render`; custom-mesh registration is OOS in MVP (see
+ * feat-future-asset-system).
+ *
+ * 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 the builtin cube mesh:
+ *   import { MeshFilter } from '@forgeax/engine-render';
+ *   import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+ *   world.spawn({ component: MeshFilter, data: { assetHandle: HANDLE_CUBE } });
+ */
+export const MeshFilter = defineComponent('MeshFilter', {
+  assetHandle: { type: 'shared<MeshAsset>' },
+});