@forgeax/engine-render 0.1.2

package/src/components/sort-key.ts

@@ -0,0 +1,75 @@
+// @forgeax/engine-render - SortKey (per-entity transparent sort override, f32).
+//
+// Schema: 1 f32 column (value). Entity-level sort override consumed by
+// `transparent-sort.ts` (M-3 w23): when present, SortKey.value REPLACES
+// the mode-formula result for this entity in the (layer, sortValue)
+// composite ordering. Override priority is higher than every
+// TransparentSortConfig mode computation (horizontal-z / Y-sort /
+// Y-Z-blend) so AI users can pin a single entity above / below the
+// procedural ordering without reshaping the entire scene.
+//
+// Like Layer, SortKey is a generic ECS renderer component — NOT a
+// 2D-only special. 3D entities may also carry SortKey to bias their
+// position inside the transparent bucket (charter P4 consistent
+// abstraction: same component drives both pipelines).
+//
+// AC-19 derivation audit row (4) names this file as the
+// `defineComponent` factory derivation. JSDoc surfaces the override
+// priority via @derives (ECS factory) annotation; the consumer side
+// of the override behaviour is implemented + verified in M-3 w16 +
+// w23, not here.
+//
+// @derives defineComponent factory (packages/ecs/src/component.ts) —
+//   f32 is a legacy scalar type; its intrinsic properties (byteSize / viewCtor
+//   / storage) live in TYPE_METADATA['f32'] (feat-20260602 M1).
+//
+// charter mapping: F1 (single-import barrel - joins Layer / Transform
+// / MeshFilter / MeshRenderer / Camera / DirectionalLight) +
+// P3 (explicit default 0.0 surfaces via the 4-layer fallback chain) +
+// P4 (consistent abstraction — generic render component, not 2D-only).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity transparent-sort override.
+ *
+ * When attached to an entity inside the transparent bucket (M-3 w22),
+ * `SortKey.value` REPLACES the result of `TransparentSortConfig.mode`
+ * formula evaluation for this entity. Sort key range is the host's
+ * choice — typical use is small (e.g. -10 ... +10) to keep the
+ * composite (layer asc, sortValue asc) ordering predictable; large
+ * magnitudes work but cross-layer biasing should usually go through
+ * `Layer` instead.
+ *
+ * Override priority (M-3 w23 transparent-sort algorithm):
+ *
+ *   if (world.has(entity, SortKey)) {
+ *     sortValue = world.get(entity, SortKey).value;
+ *   } else {
+ *     sortValue = modeFormula(mode, transform, sprite);
+ *   }
+ *
+ * SortKey lives alongside Layer in the (layer, sortValue) composite
+ * key — Layer remains the primary key, SortKey replaces the secondary
+ * key. This means a `Layer { value: 100 }` foreground entity with
+ * `SortKey { value: -99 }` still draws AFTER a `Layer { value: 0 }`
+ * background entity; SortKey biases WITHIN a layer, not ACROSS layers.
+ *
+ * @example Minimal spawn (no override, use mode formula):
+ *   world.spawn({ component: SortKey, data: {} }); // yields value=0
+ *
+ * @example Bias one sprite above the JRPG Y-sort formula:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 1, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *     { component: Layer, data: { value: 0 } },
+ *     { component: SortKey, data: { value: -100 } },
+ *   );
+ *
+ * @example Spawn payload omitting SortKey — the 4-layer fallback fills 0:
+ *   // entity reads back SortKey only if explicitly attached;
+ *   // otherwise the mode-formula path is taken by transparent-sort.ts.
+ */
+export const SortKey = defineComponent('SortKey', {
+  value: { type: 'f32', default: 0 },
+});

package/src/components/spot-light.ts

@@ -0,0 +1,124 @@
+// @forgeax/engine-render - SpotLight (cone-restricted spot-light parameters).
+//
+// Schema: direction array<f32,3> + color array<f32,3> + intensity + range +
+// innerConeDeg + outerConeDeg (feat-20260709 M2: direction/color collapsed from
+// 6 per-axis scalar columns to two inline array<f32,3> columns). `position`
+// comes from the
+// Transform component; SpotLight requires a companion Transform on the same
+// entity (ECS query: `[Transform, SpotLight]`). Cone units are degrees on
+// the Component API surface (charter F1 prior-knowledge alignment with
+// Three.js); the host-side extract step pre-converts to `cosInner` /
+// `cosOuter` before GPU upload (plan-strategy section 8.2 naming convention
+// + D-3 host-side cone conversion).
+//
+// `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. The cone falloff is layered on top with
+// `smoothstep(cosOuter, cosInner, dot(L, -direction))` (plan-strategy D-S4).
+//
+// 0 light + standard material -> physically correct black render. The
+// once-warn channel collapses to "directionalCount + pointCount +
+// spotCount === 0" (M5 / w25).
+//
+// feat-20260625-spot-light-shadow-mapping M1 w4: embedded castShadow (default true)
+// + 6 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
+// pcfKernelSize) aligned with DirectionalLight vocabulary (plan-strategy D-6;
+// charter P4 consistent abstraction). Zero-config spawns cast spot shadows;
+// set castShadow:false to opt out (validate short-circuits on false, AC-03).
+// Shadow atlas cap of 4 is enforced at extract stage, not component layer (OOS-5).
+//
+// charter mapping: proposition 1 (single import + IDE autocomplete on
+// payload.outerConeDeg with no `as` cast) + proposition 3 (silent failure
+// -> explicit failure; spawn-time fail-fast on three bound violations) +
+// proposition 5 (consistent abstraction: outgoing direction semantics
+// shared with DirectionalLight; cone deg API + cos shader uniform
+// pre-conversion mirrors directional path's host-side `lightDir x intensity`
+// pre-multiplication).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Cone-restricted spot light (KHR_lights_punctual `spot` type).  Casts shadows
+ * by default (castShadow defaults to true) — zero-config spawns project hard
+ * PCF shadows through an independent spot depth atlas.
+ *
+ * `direction` @semantics outgoing -- points FROM light source TO the
+ * scene (consistent with `DirectionalLight`; the shader internally negates
+ * this vector to obtain the L vector for BRDF evaluation:
+ * `let l = normalize(-light.direction)`). Extract owns the single
+ * normalization step for the snapshot; URP and HDRP consume that normalized
+ * value without re-normalizing. `position` source: the companion
+ * `Transform` component on the same entity.
+ *
+ * `innerConeDeg` is the half-angle of the saturated bright region (cone
+ * fully bright at the axis); `outerConeDeg` is the half-angle of the
+ * falloff edge (cone fully dark beyond). Unit is **degrees**;
+ * `outerConeDeg in (innerConeDeg, 90]` (KHR upper bound; spawn-time
+ * validation rejects `outer > 90` and `outer <= inner`). The host-side
+ * extract step converts both to `cos*` before GPU upload so the shader
+ * only sees pre-computed cosines (plan-strategy D-S2 byte freeze; charter
+ * P4 host pre-multiplication parity).
+ *
+ * `color` is linear-space rgb in `[0, 1]` per channel; `intensity` is candela;
+ * `range` is in meters and defaults to `10.0`. Exposure is a camera output
+ * operation and does not change the stored intensity.
+ *
+ * Shadow fields (embedded, aligned with DirectionalLight):
+ *   castShadow    ∈ {true, false}    — shadow opt-out gate (default true)
+ *   mapSize       >= 1               — shadow map resolution per tile (default 2048)
+ *   depthBias                        — shadow acne bias (default 0.005)
+ *   normalBias                       — shadow acne normal offset (default 0.05)
+ *   nearPlane                        — shadow-camera near (default 0.1)
+ *   farPlane                         — shadow-camera far (default 50)
+ *   pcfKernelSize odd >= 1           — PCF kernel width (default 3)
+ *
+ * Atlas capacity is capped at 4 castShadow spot lights by the extract stage;
+ * the 5th light onward keeps direct illumination but shadowAtlasTile = -1
+ * (AC-05: clip is programmatically detectable, light stays visible).
+ *
+ * @example Spawn a single spot light casting shadows (zero-config):
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 5, 0] } },
+ *     { component: SpotLight, data: { direction: [0, -1, 0] } }, // [x, y, z]
+ *   );
+ *
+ * @example Opt out of shadows:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 5, 0] } },
+ *     { component: SpotLight, data: { direction: [0, -1, 0], castShadow: false } },
+ *   );
+ *
+ * @example Explicit shadow config:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 5, 0] } },
+ *     { component: SpotLight, data: { direction: [0, -1, 0], depthBias: 0.01, normalBias: 0.08, mapSize: 1024 } },
+ *   );
+ *
+ * @example Minimal spawn -- defaults give neutral white at full strength, range 10m, KHR pi/4 cone:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 5, 0] } },
+ *     { component: SpotLight, data: { direction: [0, -1, 0] } }, // [x, y, z]
+ *   );
+ *   // resolves to color=[1,1,1], intensity=1, range=10.0,
+ *   // innerConeDeg=0, outerConeDeg=45 (KHR pi/4 equivalent).
+ */
+export const SpotLight = defineComponent('SpotLight', {
+  // direction has no default (D-5): omitting it lands the array layer-3
+  // all-zero, which validate() rejects. color carries an explicit layer-2
+  // default [1,1,1] (white); the array layer-3 fallback is all-zero.
+  direction: { type: 'array<f32, 3>' },
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1 },
+  range: { type: 'f32', default: 10.0 },
+  innerConeDeg: { type: 'f32', default: 0 },
+  outerConeDeg: { type: 'f32', default: 45 },
+  // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
+  castShadow: { type: 'bool', default: true },
+  // 6 shadow fields aligned with DirectionalLight (plan-strategy D-6).
+  mapSize: { type: 'f32', default: 2048 },
+  depthBias: { type: 'f32', default: 0.005 },
+  normalBias: { type: 'f32', default: 0.05 },
+  nearPlane: { type: 'f32', default: 0.1 },
+  farPlane: { type: 'f32', default: 50 },
+  pcfKernelSize: { type: 'f32', default: 3 },
+});

package/src/components/sprite-animation.ts

@@ -0,0 +1,169 @@
+// @forgeax/engine-runtime - SpriteAnimation (per-entity frame-tick clock).
+//
+// 6-field schema (1:1 with requirements section 2.3 table; D-5 + D-6
+// vocab keywords locked):
+//
+//   frameCount    : 'u32'         total frames in the cycle (>= 1).
+//   frameDuration : 'f32'         per-frame seconds (> 0).
+//   currentFrame  : 'u32'         live frame index, in [0, frameCount).
+//   accumDt       : 'f32'         dt accumulator (research F-3 carries
+//                                  fractional residue across ticks).
+//   regions       : 'array<f32>'  flat per-frame UV rectangles
+//                                  [uMin, vMin, uW, vH]; the M4 tick
+//                                  system enforces
+//                                  `regions.length === frameCount * 4`
+//                                  on first observation (AC-09 fail-fast,
+//                                  D-1 path).
+//   playbackMode  : 'u32'         numeric encoding of `SpritePlaybackMode`
+//                                  (0 = SPRITE_PLAYBACK_MODE_LOOP,
+//                                   1 = SPRITE_PLAYBACK_MODE_CLAMP).
+//
+// Why u32 for playbackMode? research F-2 + F-5: the ECS schema whitelist
+// rejects string-literal unions. The M1 SSOT
+// `packages/runtime/src/components/sprite-playback-mode.ts` carries the
+// numeric constants + the `spritePlaybackModeFromU32` mapper that turns
+// the column value back into a string-literal union at the M4 tick-system
+// seam — same shape as the M1 Tonemap encoding (`tonemap: 'f32'` +
+// TONEMAP_NONE / TONEMAP_REINHARD_EXTENDED + tonemapFromF32). One mental
+// model across all closed-union schema columns; charter P4 consistent
+// abstraction.
+//
+// Why array<f32> (variable) and not array<f32, N> (fixed) for regions?
+// The length `frameCount * 4` is data-dependent: `frameCount` is itself a
+// per-entity column read at runtime, not a schema-time literal. Same
+// shape as M1 `Instances.transforms: 'array<f32>'` whose length depends
+// on the live instance count; D-6 codifies the precedent.
+//
+// dt accumulator clock model (requirements section 2.5 q6 + plan-strategy
+// section 2 D-5):
+//   accumDt += Time.delta
+//   while (accumDt >= frameDuration) { advance currentFrame; accumDt -= frameDuration }
+// The carry-over `accumDt` survives across ticks so frame timing stays
+// stable under jittery dt; M4 T-23 implements the loop. Per-frame UV
+// is materialised by writing the slice
+// `regions[currentFrame*4 .. currentFrame*4 + 4]` into the entity's
+// `SpriteRegionOverride.region` column (T-11 + M4 T-23).
+//
+// Sprite-only consumption (requirements section 5 constraint #2): the
+// M4 tick system + the M3 extract branch read this component only when
+// the entity routes through the sprite bucket. Opaque buckets ignore
+// the component even when present. Naming keeps the `Sprite` prefix per
+// OOS-01 (no premature 3D generalisation); 3D UV animation lands in a
+// separate component in a future feat.
+//
+// 4-step recipe (charter F1 progressive disclosure — minimum walk-cycle
+// host code; full demo lands in M6 hello-sprite-atlas):
+//   1. Build atlas via `forgeax-engine-remote-asset atlas --input <glob> --name <prefix> --output <dir>`
+//      (M5 build-time hook); load the emitted `<name>.atlas.png` plus
+//      `<name>.atlas.meta.json` sidecar.
+//   2. Register the sprite material referencing the atlas
+//      `TextureAsset` with the initial frame's `region` rectangle (the
+//      runtime tick system overrides this region per entity per frame).
+//   3. `world.spawn` an entity with a quad mesh reference +
+//      `MeshRenderer(spriteMaterial)` + `Instances(...)` plus this
+//      `SpriteAnimation` (frameCount / frameDuration / regions /
+//      playbackMode) and `SpriteRegionOverride { region }` (the tick
+//      system writes per-frame UV).
+//   4. Add `spriteAnimationTickSystem` (M4 T-23) to the schedule between
+//      input/time and `RenderSystem.extract`.
+//
+// @derives `defineComponent` factory (packages/ecs/src/component.ts) —
+//   `'u32'` / `'f32'` are scalar tier-1 keywords; `'array<f32>'` is a
+//   tier-2 schema-vocab keyword (variable-capacity; M1 feat-20260515
+//   buffer-array vocab). Layer-3 default fallback fills missing
+//   `currentFrame` / `accumDt` / `playbackMode` with 0
+//   (component-default-fallback typeDefault table).
+// @consumes M4 T-23 (`spriteAnimationTickSystem` reads all 6 fields and
+//   writes per-frame slice into SpriteRegionOverride).
+//
+// charter mapping: F1 (single-import barrel discovery + 4-step recipe
+// at the JSDoc head); P3 (4 explicit error fields surface via the M4
+// tick-system fail-fast — `regions.length` mismatch / `frameDuration`
+// non-positive routes through SpriteAnimationInvalidError, M1 T-05);
+// P4 (consistent abstraction — same numeric closed-union encoding as
+// Tonemap / TransparentSortConfig.mode); P5 (producer / consumer
+// separation — atlas regions are produced build-time by
+// vite-plugin-image and consumed runtime as a flat Float32Array; AI
+// users never call a packer at runtime).
+//
+// Anchors: plan-strategy section 2 D-5 + D-6 + section 3.1 SAC + section
+// 4 risks R-SCHEMA-1 + R-SCHEMA-2 + R-TIME-1 reaction; plan-tasks.json
+// T-12; research F-2 + F-3 + F-5; requirements section AC-02 + section
+// 2.3 + section 2.5 + section 7 boundary table.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity sprite frame-tick clock.
+ *
+ * Schema (6 fields, 1:1 with requirements section 2.3):
+ * - `frameCount: u32` — total frames (>= 1).
+ * - `frameDuration: f32` — seconds per frame (> 0).
+ * - `currentFrame: u32` — live frame index (0..frameCount). Layer-3
+ *   default `0` when omitted at spawn.
+ * - `accumDt: f32` — dt residue carried across ticks. Layer-3 default
+ *   `0` when omitted; lives on the component (not on a system-side
+ *   resource) so the system stays stateless and AI-user setFrame paths
+ *   can reset both `currentFrame` and `accumDt` atomically.
+ * - `regions: array<f32>` — flat per-frame UV rectangles
+ *   `[uMin, vMin, uW, vH]`; runtime invariant
+ *   `regions.length === frameCount * 4` (enforced by the M4 tick system).
+ * - `playbackMode: u32` — numeric encoding of `SpritePlaybackMode`;
+ *   `SPRITE_PLAYBACK_MODE_LOOP = 0` (default) /
+ *   `SPRITE_PLAYBACK_MODE_CLAMP = 1`.
+ *
+ * Pair with `SpriteRegionOverride` (T-11) — the tick system writes the
+ * per-frame UV slice into the override column, which `render-system-
+ * extract` then reads in the sprite bucket branch.
+ *
+ * @example Spawn a 4-frame walk cycle that loops:
+ *   import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+ *   import {
+ *     SpriteAnimation, SpriteRegionOverride, SPRITE_PLAYBACK_MODE_LOOP,
+ *   } from '@forgeax/engine-render/authoring';
+ *   import { Transform } from '@forgeax/engine-scene';
+ *   import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+ *   const quadMesh = world.internSharedRef(createPrimitiveMesh('quad').unwrap());
+ *
+ *   // 4 frames packed in an atlas, each 64x64 inside a 256x64 row:
+ *   const regions = new Float32Array([
+ *     0.00, 0, 0.25, 1,  // walk-0
+ *     0.25, 0, 0.25, 1,  // walk-1
+ *     0.50, 0, 0.25, 1,  // walk-2
+ *     0.75, 0, 0.25, 1,  // walk-3
+ *   ]);
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 0, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *     { component: MeshFilter, data: { assetHandle: quadMesh } },
+ *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },
+ *     { component: SpriteAnimation,
+ *       data: {
+ *         frameCount: 4,
+ *         frameDuration: 0.1,
+ *         regions,
+ *         playbackMode: SPRITE_PLAYBACK_MODE_LOOP,
+ *       } },
+ *     { component: SpriteRegionOverride,
+ *       data: { region: new Float32Array([0, 0, 0.25, 1]) } },
+ *   );
+ *
+ * @example Manual setFrame — jump to frame 2 atomically:
+ *   world.set(entity, SpriteAnimation,
+ *     { currentFrame: 2, accumDt: 0 }).unwrap();
+ *
+ * Error path (M4 T-23 routes through `SpriteAnimationInvalidError`,
+ * `EcsErrorCode === 'sprite-animation-invalid'`; charter P3):
+ * - `regions.length !== frameCount * 4` -> detail.field = 'regions-length',
+ *   detail carries `regionsLength` + `frameCount`.
+ * - `frameDuration <= 0` -> detail.field = 'frame-duration', detail carries
+ *   `frameDuration`.
+ */
+export const SpriteAnimation = defineComponent('SpriteAnimation', {
+  frameCount: { type: 'u32' },
+  frameDuration: { type: 'f32' },
+  currentFrame: { type: 'u32', transient: true },
+  accumDt: { type: 'f32', transient: true },
+  regions: { type: 'array<f32>' },
+  playbackMode: { type: 'u32' },
+});

package/src/components/sprite-instances.ts

@@ -0,0 +1,179 @@
+// @forgeax/engine-runtime - SpriteInstances component (per-entity 2D
+// instanced-draw transforms + per-instance UV region).
+//
+// Schema: 2 array<f32> fields. `transforms` carries packed column-major mat4
+// instance transforms (16 f32 per instance, stride = 16). `regions` carries
+// packed per-instance UV vec4 (4 f32 per instance, stride = 4; layout
+// [uMin, vMin, uW, vH] mirroring SpriteAnimation.regions). The pair share
+// the same instance count; the SSOT invariant is
+//   transforms.length / 16 === regions.length / 4
+// enforced through a TWO-LAYER contract:
+//
+//   1. AI user set-site: spawn / `world.set` / `world.push` callers pass two
+//      Float32Arrays whose lengths satisfy the stride pair. The set site is
+//      the AI user's responsibility — the engine cannot prove column-major
+//      mat4 packing or per-instance UV intent without caller declaration.
+//   2. RenderSystem extract entry: `render-system-extract.ts` performs a
+//      defensive `transforms.length / 16 === regions.length / 4` check on
+//      every `world.get(e, SpriteInstances)` snapshot at frame extract time;
+//      violations route a structured `SpriteInstancesCountMismatchError`
+//      (`code: 'sprite-instances-count-mismatch'`,
+//      `detail: { transformsLength, regionsLength, expectedStride: { transforms: 16, regions: 4 } }`)
+//      through the World Layer-3 ErrorHandler and the renderable is skipped.
+//      Two further extract-entry checks fire:
+//        - `'sprite-instances-requires-sprite-shader'` — MaterialAsset's
+//          first pass `shader` must be `'forgeax::sprite'`.
+//        - `'sprite-instances-mutually-exclusive-with-instances'` — same
+//          entity must not carry both Instances + SpriteInstances.
+//      (Error class declarations live in `@forgeax/engine-ecs` errors.ts; the
+//      extract-entry fire path is owned by feat M3 w12 / w13.)
+//
+// Peer relation to Instances (charter P4 consistent abstraction):
+//   - Instances : 3D scene primitive — per-instance mat4 only (stride 16).
+//   - SpriteInstances : 2D scene primitive — per-instance mat4 + per-instance
+//     UV region (interleaved 80B per instance: 64B mat4 + 16B region).
+// AI users pick by data shape (does the per-instance carry UV?). Both ride
+// the array-vocab path and route through the same Layer-3 error envelope.
+//
+// Group transform chained semantics (charter proposition 5 mental migration):
+//   When the same entity carries both `Transform` (entity_world) and
+//   `SpriteInstances` (per-instance local transforms), the vertex shader
+//   composes per instance:
+//     world_position[i] = entity_world * instances_local[i] * vertex_position
+//   `SpriteInstances.transforms[i*16..i*16+15]` is interpreted as a local-
+//   space transform under the entity, exactly like `Instances.transforms`.
+//   Set the entity's `Transform` to identity to make `instances_local[i]`
+//   directly world-space.
+//
+// Uniform / storage buffer cap (research D-R-4 + AC-04): 80B per instance
+// * 128-cap fallback = 10240 B < 16384 B uniform max; the storage-buffer
+// path is uncapped and used by capable backends (RenderSystem record-stage
+// cap-gate).
+//
+// 4-segment minimum contract (read this header before reaching for the
+// source body):
+//
+// ===== (a) single-component import + spawn example =====
+//
+//   import {
+//     createRenderer,
+//     MeshFilter, MeshRenderer, Transform,
+//     SpriteInstances, type SpriteInstancesData,
+//   } from '@forgeax/engine-render';
+//
+//   // 1 entity rendering N instanced sprites (16N transforms f32 + 4N regions f32):
+//   const transforms = new Float32Array(N * 16);
+//   const regions    = new Float32Array(N * 4);
+//   // ... fill column-major mat4 columns + [uMin, vMin, uW, vH] per instance ...
+//   world.spawn(
+//     { component: MeshFilter,      data: { assetHandle: quadMesh } },
+//     { component: MeshRenderer,    data: { /* sprite-shaded MaterialAsset */ } },
+//     { component: SpriteInstances, data: { transforms, regions } },
+//   );
+//
+// ===== (b) packed mat4 + region layout =====
+//
+//   const transforms = new Float32Array(N * 16); // column-major mat4 per instance
+//   const regions    = new Float32Array(N * 4);  // [uMin, vMin, uW, vH] per instance
+//   // instance i occupies floats:
+//   //   transforms[i*16 .. i*16+15] — column-major mat4 (translation in m03/m13/m23)
+//   //   regions   [i* 4 .. i* 4+ 3] — uMin, vMin, uW, vH (atlas-normalized UV rect)
+//
+// `transforms.length` MUST be a non-zero multiple of 16; `regions.length`
+// MUST be a non-zero multiple of 4; the per-instance count derived from
+// both MUST agree. AI users gate at the set / push site; the RenderSystem
+// extract entry holds the second defensive (see error path 1 below).
+//
+// ===== (c) error code consumption (typed property access, no message regex) =====
+//
+//   // Stride / mutual-exclusion / sprite-shader violations surface through
+//   // the engine-ecs Layer-3 ErrorHandler when extract reads a malformed
+//   // snapshot:
+//   //   on('error', (err) => {
+//   //     switch (err.code) {
+//   //       case 'sprite-instances-count-mismatch':
+//   //         // err.detail.transformsLength / regionsLength / expectedStride
+//   //         break;
+//   //       case 'sprite-instances-requires-sprite-shader':
+//   //         // err.detail.entityId / observedMaterialShaderId
+//   //         break;
+//   //       case 'sprite-instances-mutually-exclusive-with-instances':
+//   //         // err.detail.entityId
+//   //         break;
+//   //     }
+//   //   });
+//
+// charter mapping (charter v2 numbering, with round-1 v1 aliases retained
+// in parentheses so reviewers tracking the v1 spec can cross-reference;
+// SSOT for the v2 -> v1 alias map is the AI User Charter — see
+// .claude/skills/forgeax-closed-loop/agents/ai-user-charter.md):
+//   F1 (alias: proposition 1) — single import surface
+//      `import { SpriteInstances, type SpriteInstancesData } from
+//      '@forgeax/engine-render'`;
+//   P2 (alias: proposition 3) — machine-readable schema > prose:
+//      `{ transforms: 'array<f32>', regions: 'array<f32>' }` is the SSOT,
+//      stride pair documented here + enforced at the RenderSystem entry;
+//   P3 (alias: proposition 4) — explicit failure: 3 structured EcsError
+//      codes route per failure shape, not silent half-row;
+//   P4 (alias: proposition 5) — consistent abstraction: SpriteInstances
+//      mirrors Instances — both ride the array-vocab path; pick by data
+//      shape, not by API.
+//
+// Anchors: requirements AC-01 (component schema), AC-03 (3 error codes),
+// AC-09 (IDE autocomplete + type inference); plan-strategy D-1 (interleaved
+// single binding slot), D-6 (3 codes declared in M1 ecs, fired in M3 render),
+// D-7 (type export location), D-8 (barrel re-export at runtime, not ecs).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity 2D instanced-draw primitive (ECS component).
+ *
+ * Carries two variable-length `array<f32>` fields:
+ *   - `transforms` — column-major mat4 per instance (16 f32, stride 16);
+ *   - `regions`    — UV vec4 per instance ([uMin, vMin, uW, vH], 4 f32,
+ *     stride 4).
+ *
+ * The pair share the same instance count; the invariant
+ * `transforms.length / 16 === regions.length / 4` is enforced at the
+ * RenderSystem extract entry (NOT at ECS write paths). The runtime
+ * RenderSystem consumer materialises a fresh `Float32Array` snapshot on
+ * every `world.get(e, SpriteInstances)` access and uploads an interleaved
+ * 80B-per-instance buffer to the GPU in the record stage.
+ *
+ * @example Spawn an entity rendering 10000 instanced sprites:
+ *   const transforms = new Float32Array(10000 * 16);
+ *   const regions    = new Float32Array(10000 * 4);
+ *   // ... fill mat4 columns + [uMin, vMin, uW, vH] ...
+ *   world.spawn(
+ *     { component: MeshFilter,      data: { assetHandle: quadMesh } },
+ *     { component: MeshRenderer,    data: { ... } },
+ *     { component: SpriteInstances, data: { transforms, regions } },
+ *   );
+ */
+export const SpriteInstances = defineComponent('SpriteInstances', {
+  transforms: { type: 'array<f32>' },
+  regions: { type: 'array<f32>' },
+});
+
+/**
+ * Type-level hint for `data` at the `SpriteInstances` 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). Both fields are typed as `Float32Array` so AI-user IDE
+ * autocomplete picks up the typed-array shape and the AC-09 inference
+ * surfaces without `as` casts inside `world.get(e, SpriteInstances)` and
+ * QueryRow access paths.
+ *
+ * @example
+ *   import type { SpriteInstancesData } from '@forgeax/engine-render/authoring';
+ *   const data: SpriteInstancesData = {
+ *     transforms: new Float32Array(N * 16),
+ *     regions:    new Float32Array(N * 4),
+ *   };
+ */
+export type SpriteInstancesData = {
+  readonly transforms: Float32Array;
+  readonly regions: Float32Array;
+};

package/src/components/sprite-playback-mode.ts

@@ -0,0 +1,73 @@
+// @forgeax/engine-runtime - SpritePlaybackMode (u32 column encoding + mapper).
+//
+// SSOT for the SpriteAnimation.playbackMode ECS column (M2 T-12) and the
+// runtime tick-system branch selector (M4 T-23). The shape mirrors the M1
+// `Tonemap` block in `./camera.ts:72-90` (TONEMAP_NONE = 0 /
+// TONEMAP_REINHARD_EXTENDED = 1 + `type Tonemap = 'none' |
+// 'reinhard-extended'` + `tonemapFromF32`) for charter P4 consistent
+// abstraction — AI users keep one mental model across all u32-encoded
+// closed-union schema columns.
+//
+// Why `'u32'` + constant + mapper instead of a string-literal column?
+// ECS schema whitelist `SchemaFieldType` (packages/ecs/src/component.ts
+// section schema-field-type) does not accept string-literal unions
+// (research F-2 + F-5). Storing a u32 + translating to a closed
+// `'loop' | 'clamp'` literal union at the tick-system seam preserves
+// AI-user-facing narrowing (`switch (mode) { case 'loop': ... }`)
+// without forcing the ECS column to learn a new field-type vocabulary.
+//
+// Naming convention (plan-strategy section 8.command naming):
+//   SPRITE_PLAYBACK_MODE_LOOP / SPRITE_PLAYBACK_MODE_CLAMP mirror M1
+//   TONEMAP_* / TRANSPARENT_SORT_MODE_*. `spritePlaybackModeFromU32`
+//   mirrors `tonemapFromF32` / `cameraProjectionFromF32`. AI users
+//   discover the trio via single-import barrel re-export from
+//   `@forgeax/engine-runtime` (wired in by M2 T-13).
+//
+// Anchors: plan-strategy section 2 D-5 + section 3.1 PR block SPM +
+//          section 4 risk R-SCHEMA-1 reaction; research F-2 + F-5;
+//          requirements section AC-02 + section 2.3 playbackMode row;
+//          plan-tasks.json T-07 acceptanceCheck (rg
+//          "SPRITE_PLAYBACK_MODE_LOOP|SPRITE_PLAYBACK_MODE_CLAMP|
+//          spritePlaybackModeFromU32" >= 3 hits in this file).
+
+/**
+ * Playback mode discriminator literal union (requirements section AC-02 +
+ * section 2.3). Two members for the MVP:
+ *
+ *   `'loop'`  — `currentFrame = (currentFrame + 1) % frameCount`; the
+ *               sprite-animation-tick system wraps the index when
+ *               `accumDt >= frameDuration` (default for hello-sprite-
+ *               atlas demo "100 sprites synchronised walk cycle").
+ *   `'clamp'` — `currentFrame = min(currentFrame + 1, frameCount - 1)`;
+ *               holds the last frame for death / terminator-animation
+ *               style sequences (requirements section 2.5 q8 lock).
+ *
+ * Future modes (`'pingpong'`, reverse playback, arbitrary frame index
+ * jumps) are deferred per requirements OOS-03. The closed union shape
+ * leaves room for additive growth without breaking the u32 enum encoding
+ * (plan-strategy section 2 D-5).
+ */
+export type SpritePlaybackMode = 'loop' | 'clamp';
+
+/** Numeric encoding of the loop playback mode (schema value for `playbackMode`). */
+export const SPRITE_PLAYBACK_MODE_LOOP = 0 as const;
+
+/** Numeric encoding of the clamp playback mode (schema value for `playbackMode`). */
+export const SPRITE_PLAYBACK_MODE_CLAMP = 1 as const;
+
+/**
+ * Map a `SpriteAnimation.playbackMode` numeric column value to the closed
+ * `SpritePlaybackMode` string-literal union. The defensive fallback mirrors
+ * `cameraProjectionFromF32` / `tonemapFromF32` precedent — any value other
+ * than `SPRITE_PLAYBACK_MODE_CLAMP` (1) maps to `'loop'`, so stale or
+ * uninitialised entities surface a predictable playback shape through the
+ * tick-system query (rather than throwing or returning `undefined`).
+ * Validation of `playbackMode` happens at schema-write time, not here.
+ *
+ * The tick-system in M4 T-23 (`spriteAnimationTickSystem`) consumes the
+ * return value via `switch (mode) { case 'loop': ...; case 'clamp': ... }`
+ * to pick the per-branch frame-advance arithmetic.
+ */
+export function spritePlaybackModeFromU32(value: number): SpritePlaybackMode {
+  return value === SPRITE_PLAYBACK_MODE_CLAMP ? 'clamp' : 'loop';
+}