@forgeax/engine-render 0.1.34 → 0.1.35

package/dist/chunk-ELJFJ2BU.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/sprite-animation.ts","../src/components/sprite-instances.ts","../src/components/sprite-region-override.ts","../src/components/tile-layer.ts","../src/components/tilemap.ts","../src/systems/active-camera.ts"],"names":["defineComponent"],"mappings":";;;AAgKO,IAAM,eAAA,GAAkB,gBAAgB,iBAAA,EAAmB;AAAA,EAChE,UAAA,EAAY,EAAE,IAAA,EAAM,KAAA,EAAM;AAAA,EAC1B,aAAA,EAAe,EAAE,IAAA,EAAM,KAAA,EAAM;AAAA,EAC7B,YAAA,EAAc,EAAE,IAAA,EAAM,KAAA,EAAO,WAAW,IAAA,EAAK;AAAA,EAC7C,OAAA,EAAS,EAAE,IAAA,EAAM,KAAA,EAAO,WAAW,IAAA,EAAK;AAAA,EACxC,OAAA,EAAS,EAAE,IAAA,EAAM,YAAA,EAAa;AAAA,EAC9B,YAAA,EAAc,EAAE,IAAA,EAAM,KAAA;AACxB,CAAC;ACdM,IAAM,eAAA,GAAkBA,gBAAgB,iBAAA,EAAmB;AAAA,EAChE,UAAA,EAAY,EAAE,IAAA,EAAM,YAAA,EAAa;AAAA,EACjC,OAAA,EAAS,EAAE,IAAA,EAAM,YAAA;AACnB,CAAC;ACtDM,IAAM,oBAAA,GAAuBA,gBAAgB,sBAAA,EAAwB;AAAA,EAC1E,MAAA,EAAQ,EAAE,IAAA,EAAM,eAAA;AAClB,CAAC;AC7CM,IAAM,WAAA,GAAc,OAAO,MAAA,CAAO;AAAA,EACvC,KAAA,EAAO,CAAA;AAAA,EACP,OAAA,EAAS;AACX,CAAC;AAuBM,SAAS,gBAAgB,GAAA,EAAoC;AAClE,EAAA,OAAO,GAAA,KAAQ,IAAI,UAAA,GAAa,OAAA;AAClC;AAwDO,IAAM,SAAA,GAAYA,gBAAgB,WAAA,EAAa;AAAA,EACpD,KAAA,EAAO,EAAE,IAAA,EAAM,YAAA,EAAa;AAAA,EAC5B,UAAA,EAAY,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,CAAA,EAAE;AAAA,EACtC,KAAA,EAAO,EAAE,IAAA,EAAM,IAAA,EAAM,SAAS,CAAA,EAAE;AAAA,EAChC,SAAA,EAAW,EAAE,IAAA,EAAM,IAAA,EAAM,SAAS,CAAA;AACpC,CAAC;AC7GM,IAAM,OAAA,GAAUA,gBAAgB,SAAA,EAAW;AAAA,EAChD,IAAA,EAAM,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,CAAA,EAAE;AAAA,EAChC,IAAA,EAAM,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,CAAA,EAAE;AAAA;AAAA;AAAA,EAGhC,QAAA,EAAU,EAAE,IAAA,EAAM,eAAA,EAAiB,OAAA,EAAS,IAAI,YAAA,CAAa,CAAC,CAAA,EAAG,CAAC,CAAC,CAAA,EAAE;AAAA,EACrE,SAAA,EAAW,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,EAAA,EAAG;AAAA,EACtC,OAAA,EAAS,EAAE,IAAA,EAAM,QAAA;AACnB,CAAC;;;ACYM,IAAM,iBAAA,GAAoB,cAAA;AAkB1B,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,IAAI,CAAC,KAAA,CAAM,WAAA,CAAY,iBAAiB,GAAG,OAAO,MAAA;AAClD,EAAA,OAAO,KAAA,CAAM,YAA0B,iBAAiB,CAAA;AAC1D;AAUO,SAAS,eAAA,CAAgB,OAAc,MAAA,EAAsB;AAClE,EAAA,KAAA,CAAM,cAAA,CAA6B,iBAAA,EAAmB,EAAE,MAAA,EAAQ,CAAA;AAClE;AAiBO,SAAS,uBAAA,CACd,gBACA,YAAA,EACQ;AACR,EAAA,IAAI,YAAA,KAAiB,QAAW,OAAO,EAAA;AACvC,EAAA,OAAO,cAAA,CAAe,QAAQ,YAAY,CAAA;AAC5C","file":"chunk-ELJFJ2BU.mjs","sourcesContent":["// @forgeax/engine-runtime - SpriteAnimation (per-entity frame-tick clock).\n//\n// 6-field schema (1:1 with requirements section 2.3 table; D-5 + D-6\n// vocab keywords locked):\n//\n//   frameCount    : 'u32'         total frames in the cycle (>= 1).\n//   frameDuration : 'f32'         per-frame seconds (> 0).\n//   currentFrame  : 'u32'         live frame index, in [0, frameCount).\n//   accumDt       : 'f32'         dt accumulator (research F-3 carries\n//                                  fractional residue across ticks).\n//   regions       : 'array<f32>'  flat per-frame UV rectangles\n//                                  [uMin, vMin, uW, vH]; the M4 tick\n//                                  system enforces\n//                                  `regions.length === frameCount * 4`\n//                                  on first observation (AC-09 fail-fast,\n//                                  D-1 path).\n//   playbackMode  : 'u32'         numeric encoding of `SpritePlaybackMode`\n//                                  (0 = SPRITE_PLAYBACK_MODE_LOOP,\n//                                   1 = SPRITE_PLAYBACK_MODE_CLAMP).\n//\n// Why u32 for playbackMode? research F-2 + F-5: the ECS schema whitelist\n// rejects string-literal unions. The M1 SSOT\n// `packages/runtime/src/components/sprite-playback-mode.ts` carries the\n// numeric constants + the `spritePlaybackModeFromU32` mapper that turns\n// the column value back into a string-literal union at the M4 tick-system\n// seam — same shape as the M1 Tonemap encoding (`tonemap: 'f32'` +\n// TONEMAP_NONE / TONEMAP_REINHARD_EXTENDED + tonemapFromF32). One mental\n// model across all closed-union schema columns; charter P4 consistent\n// abstraction.\n//\n// Why array<f32> (variable) and not array<f32, N> (fixed) for regions?\n// The length `frameCount * 4` is data-dependent: `frameCount` is itself a\n// per-entity column read at runtime, not a schema-time literal. Same\n// shape as the renderer-owned 3D instance collection snapshot whose length\n// depends on the live instance count; the owners remain separate.\n//\n// dt accumulator clock model (requirements section 2.5 q6 + plan-strategy\n// section 2 D-5):\n//   accumDt += Time.delta\n//   while (accumDt >= frameDuration) { advance currentFrame; accumDt -= frameDuration }\n// The carry-over `accumDt` survives across ticks so frame timing stays\n// stable under jittery dt; M4 T-23 implements the loop. Per-frame UV\n// is materialised by writing the slice\n// `regions[currentFrame*4 .. currentFrame*4 + 4]` into the entity's\n// `SpriteRegionOverride.region` column (T-11 + M4 T-23).\n//\n// Sprite-only consumption (requirements section 5 constraint #2): the\n// M4 tick system + the M3 extract branch read this component only when\n// the entity routes through the sprite bucket. Opaque buckets ignore\n// the component even when present. Naming keeps the `Sprite` prefix per\n// OOS-01 (no premature 3D generalisation); 3D UV animation lands in a\n// separate component in a future feat.\n//\n// 4-step recipe (charter F1 progressive disclosure — minimum walk-cycle\n// host code; full demo lands in M6 hello-sprite-atlas):\n//   1. Build atlas via `forgeax asset atlas --input <glob> --name <prefix> --output <dir> --root <project>`\n//      (M5 build-time hook); load the emitted `<name>.atlas.png` plus\n//      `<name>.atlas.meta.json` sidecar.\n//   2. Register the sprite material referencing the atlas\n//      `TextureAsset` with the initial frame's `region` rectangle (the\n//      runtime tick system overrides this region per entity per frame).\n//   3. `world.spawn` an entity with `MeshFilter(HANDLE_QUAD)` +\n//      `MeshRenderer(spriteMaterial)` + `Instances(...)` plus this\n//      `SpriteAnimation` (frameCount / frameDuration / regions /\n//      playbackMode) and `SpriteRegionOverride { region }` (the tick\n//      system writes per-frame UV).\n//   4. Add `spriteAnimationTickSystem` (M4 T-23) to the schedule between\n//      input/time and `RenderSystem.extract`.\n//\n// @derives `defineComponent` factory (packages/ecs/src/component.ts) —\n//   `'u32'` / `'f32'` are scalar tier-1 keywords; `'array<f32>'` is a\n//   tier-2 schema-vocab keyword (variable-capacity; M1 feat-20260515\n//   buffer-array vocab). Layer-3 default fallback fills missing\n//   `currentFrame` / `accumDt` / `playbackMode` with 0\n//   (component-default-fallback typeDefault table).\n// @consumes M4 T-23 (`spriteAnimationTickSystem` reads all 6 fields and\n//   writes per-frame slice into SpriteRegionOverride).\n//\n// charter mapping: F1 (single-import barrel discovery + 4-step recipe\n// at the JSDoc head); P3 (4 explicit error fields surface via the M4\n// tick-system fail-fast — `regions.length` mismatch / `frameDuration`\n// non-positive routes through SpriteAnimationInvalidError, M1 T-05);\n// P4 (consistent abstraction — same numeric closed-union encoding as\n// Tonemap / TransparentSortConfig.mode); P5 (producer / consumer\n// separation — atlas regions are produced build-time by\n// vite-plugin-image and consumed runtime as a flat Float32Array; AI\n// users never call a packer at runtime).\n//\n// Anchors: plan-strategy section 2 D-5 + D-6 + section 3.1 SAC + section\n// 4 risks R-SCHEMA-1 + R-SCHEMA-2 + R-TIME-1 reaction; plan-tasks.json\n// T-12; research F-2 + F-3 + F-5; requirements section AC-02 + section\n// 2.3 + section 2.5 + section 7 boundary table.\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\n/**\n * Per-entity sprite frame-tick clock.\n *\n * Schema (6 fields, 1:1 with requirements section 2.3):\n * - `frameCount: u32` — total frames (>= 1).\n * - `frameDuration: f32` — seconds per frame (> 0).\n * - `currentFrame: u32` — live frame index (0..frameCount). Layer-3\n *   default `0` when omitted at spawn.\n * - `accumDt: f32` — dt residue carried across ticks. Layer-3 default\n *   `0` when omitted; lives on the component (not on a system-side\n *   resource) so the system stays stateless and AI-user setFrame paths\n *   can reset both `currentFrame` and `accumDt` atomically.\n * - `regions: array<f32>` — flat per-frame UV rectangles\n *   `[uMin, vMin, uW, vH]`; runtime invariant\n *   `regions.length === frameCount * 4` (enforced by the M4 tick system).\n * - `playbackMode: u32` — numeric encoding of `SpritePlaybackMode`;\n *   `SPRITE_PLAYBACK_MODE_LOOP = 0` (default) /\n *   `SPRITE_PLAYBACK_MODE_CLAMP = 1`.\n *\n * Pair with `SpriteRegionOverride` (T-11) — the tick system writes the\n * per-frame UV slice into the override column, which `render-system-\n * extract` then reads in the sprite bucket branch.\n *\n * @example Spawn a 4-frame walk cycle that loops:\n *   import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';\n *   import {\n *     SpriteAnimation, SpriteRegionOverride, SPRITE_PLAYBACK_MODE_LOOP,\n *   } from '@forgeax/engine-render/authoring';\n *   import { Transform } from '@forgeax/engine-scene';\n *   import { HANDLE_QUAD } from '@forgeax/engine-assets-runtime';\n *\n *   // 4 frames packed in an atlas, each 64x64 inside a 256x64 row:\n *   const regions = new Float32Array([\n *     0.00, 0, 0.25, 1,  // walk-0\n *     0.25, 0, 0.25, 1,  // walk-1\n *     0.50, 0, 0.25, 1,  // walk-2\n *     0.75, 0, 0.25, 1,  // walk-3\n *   ]);\n *   world.spawn(\n *     { component: Transform, data: { pos: [0, 0, 0],\n *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },\n *     { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },\n *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },\n *     { component: SpriteAnimation,\n *       data: {\n *         frameCount: 4,\n *         frameDuration: 0.1,\n *         regions,\n *         playbackMode: SPRITE_PLAYBACK_MODE_LOOP,\n *       } },\n *     { component: SpriteRegionOverride,\n *       data: { region: new Float32Array([0, 0, 0.25, 1]) } },\n *   );\n *\n * @example Manual setFrame — jump to frame 2 atomically:\n *   world.set(entity, SpriteAnimation,\n *     { currentFrame: 2, accumDt: 0 }).unwrap();\n *\n * Error path (M4 T-23 routes through `SpriteAnimationInvalidError`,\n * `EcsErrorCode === 'sprite-animation-invalid'`; charter P3):\n * - `regions.length !== frameCount * 4` -> detail.field = 'regions-length',\n *   detail carries `regionsLength` + `frameCount`.\n * - `frameDuration <= 0` -> detail.field = 'frame-duration', detail carries\n *   `frameDuration`.\n */\nexport const SpriteAnimation = defineComponent('SpriteAnimation', {\n  frameCount: { type: 'u32' },\n  frameDuration: { type: 'f32' },\n  currentFrame: { type: 'u32', transient: true },\n  accumDt: { type: 'f32', transient: true },\n  regions: { type: 'array<f32>' },\n  playbackMode: { type: 'u32' },\n});\n","// @forgeax/engine-runtime - SpriteInstances component (per-entity 2D\n// instanced-draw transforms + per-instance UV region).\n//\n// Schema: 2 array<f32> fields. `transforms` carries packed column-major mat4\n// instance transforms (16 f32 per instance, stride = 16). `regions` carries\n// packed per-instance UV vec4 (4 f32 per instance, stride = 4; layout\n// [uMin, vMin, uW, vH] mirroring SpriteAnimation.regions). The pair share\n// the same instance count; the SSOT invariant is\n//   transforms.length / 16 === regions.length / 4\n// enforced through a TWO-LAYER contract:\n//\n//   1. AI user set-site: spawn / `world.set` / `world.push` callers pass two\n//      Float32Arrays whose lengths satisfy the stride pair. The set site is\n//      the AI user's responsibility — the engine cannot prove column-major\n//      mat4 packing or per-instance UV intent without caller declaration.\n//   2. RenderSystem extract entry: `render-system-extract.ts` performs a\n//      defensive `transforms.length / 16 === regions.length / 4` check on\n//      every `world.get(e, SpriteInstances)` snapshot at frame extract time;\n//      violations route a structured `SpriteInstancesCountMismatchError`\n//      (`code: 'sprite-instances-count-mismatch'`,\n//      `detail: { transformsLength, regionsLength, expectedStride: { transforms: 16, regions: 4 } }`)\n//      through the World Layer-3 ErrorHandler and the renderable is skipped.\n//      Two further extract-entry checks fire:\n//        - `'sprite-instances-requires-sprite-shader'` — MaterialAsset's\n//          first pass `shader` must be `'forgeax::sprite'`.\n//        - `'sprite-instances-mutually-exclusive-with-instances'` — same\n//          entity must not carry both Instances + SpriteInstances.\n//      (Error class declarations live in `@forgeax/engine-ecs` errors.ts; the\n//      extract-entry fire path is owned by feat M3 w12 / w13.)\n//\n// Peer relation to Instances (charter P4 consistent abstraction):\n//   - Instances : 3D scene primitive — per-instance mat4 only (stride 16).\n//   - SpriteInstances : 2D scene primitive — per-instance mat4 + per-instance\n//     UV region (interleaved 80B per instance: 64B mat4 + 16B region).\n// AI users pick by data shape (does the per-instance carry UV?). Both ride\n// the array-vocab path and route through the same Layer-3 error envelope.\n//\n// Group transform chained semantics (charter proposition 5 mental migration):\n//   When the same entity carries both `Transform` (entity_world) and\n//   `SpriteInstances` (per-instance local transforms), the vertex shader\n//   composes per instance:\n//     world_position[i] = entity_world * instances_local[i] * vertex_position\n//   `SpriteInstances.transforms[i*16..i*16+15]` is interpreted as a local-\n//   space transform under the entity, exactly like `Instances.transforms`.\n//   Set the entity's `Transform` to identity to make `instances_local[i]`\n//   directly world-space.\n//\n// Uniform / storage buffer cap (research D-R-4 + AC-04): 80B per instance\n// * 128-cap fallback = 10240 B < 16384 B uniform max; the storage-buffer\n// path is uncapped and used by capable backends (RenderSystem record-stage\n// cap-gate).\n//\n// 4-segment minimum contract (read this header before reaching for the\n// source body):\n//\n// ===== (a) single-component import + spawn example =====\n//\n//   import {\n//     createRenderer,\n//     MeshFilter, MeshRenderer, Transform,\n//     SpriteInstances, type SpriteInstancesData,\n//   } from '@forgeax/engine-render';\n//\n//   // 1 entity rendering N instanced sprites (16N transforms f32 + 4N regions f32):\n//   const transforms = new Float32Array(N * 16);\n//   const regions    = new Float32Array(N * 4);\n//   // ... fill column-major mat4 columns + [uMin, vMin, uW, vH] per instance ...\n//   world.spawn(\n//     { component: MeshFilter,      data: { assetHandle: HANDLE_QUAD } },\n//     { component: MeshRenderer,    data: { /* sprite-shaded MaterialAsset */ } },\n//     { component: SpriteInstances, data: { transforms, regions } },\n//   );\n//\n// ===== (b) packed mat4 + region layout =====\n//\n//   const transforms = new Float32Array(N * 16); // column-major mat4 per instance\n//   const regions    = new Float32Array(N * 4);  // [uMin, vMin, uW, vH] per instance\n//   // instance i occupies floats:\n//   //   transforms[i*16 .. i*16+15] — column-major mat4 (translation in m03/m13/m23)\n//   //   regions   [i* 4 .. i* 4+ 3] — uMin, vMin, uW, vH (atlas-normalized UV rect)\n//\n// `transforms.length` MUST be a non-zero multiple of 16; `regions.length`\n// MUST be a non-zero multiple of 4; the per-instance count derived from\n// both MUST agree. AI users gate at the set / push site; the RenderSystem\n// extract entry holds the second defensive (see error path 1 below).\n//\n// ===== (c) error code consumption (typed property access, no message regex) =====\n//\n//   // Stride / mutual-exclusion / sprite-shader violations surface through\n//   // the engine-ecs Layer-3 ErrorHandler when extract reads a malformed\n//   // snapshot:\n//   //   on('error', (err) => {\n//   //     switch (err.code) {\n//   //       case 'sprite-instances-count-mismatch':\n//   //         // err.detail.transformsLength / regionsLength / expectedStride\n//   //         break;\n//   //       case 'sprite-instances-requires-sprite-shader':\n//   //         // err.detail.entityId / observedMaterialShaderId\n//   //         break;\n//   //       case 'sprite-instances-mutually-exclusive-with-instances':\n//   //         // err.detail.entityId\n//   //         break;\n//   //     }\n//   //   });\n//\n// charter mapping (charter v2 numbering, with round-1 v1 aliases retained\n// in parentheses so reviewers tracking the v1 spec can cross-reference;\n// SSOT for the v2 -> v1 alias map is the AI User Charter — see\n// .claude/skills/forgeax-closed-loop/agents/ai-user-charter.md):\n//   F1 (alias: proposition 1) — single import surface\n//      `import { SpriteInstances, type SpriteInstancesData } from\n//      '@forgeax/engine-render'`;\n//   P2 (alias: proposition 3) — machine-readable schema > prose:\n//      `{ transforms: 'array<f32>', regions: 'array<f32>' }` is the SSOT,\n//      stride pair documented here + enforced at the RenderSystem entry;\n//   P3 (alias: proposition 4) — explicit failure: 3 structured EcsError\n//      codes route per failure shape, not silent half-row;\n//   P4 (alias: proposition 5) — consistent abstraction: SpriteInstances\n//      mirrors Instances — both ride the array-vocab path; pick by data\n//      shape, not by API.\n//\n// Anchors: requirements AC-01 (component schema), AC-03 (3 error codes),\n// AC-09 (IDE autocomplete + type inference); plan-strategy D-1 (interleaved\n// single binding slot), D-6 (3 codes declared in M1 ecs, fired in M3 render),\n// D-7 (type export location), D-8 (barrel re-export at runtime, not ecs).\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\n/**\n * Per-entity 2D instanced-draw primitive (ECS component).\n *\n * Carries two variable-length `array<f32>` fields:\n *   - `transforms` — column-major mat4 per instance (16 f32, stride 16);\n *   - `regions`    — UV vec4 per instance ([uMin, vMin, uW, vH], 4 f32,\n *     stride 4).\n *\n * The pair share the same instance count; the invariant\n * `transforms.length / 16 === regions.length / 4` is enforced at the\n * RenderSystem extract entry (NOT at ECS write paths). The runtime\n * RenderSystem consumer materialises a fresh `Float32Array` snapshot on\n * every `world.get(e, SpriteInstances)` access and uploads an interleaved\n * 80B-per-instance buffer to the GPU in the record stage.\n *\n * @example Spawn an entity rendering 10000 instanced sprites:\n *   const transforms = new Float32Array(10000 * 16);\n *   const regions    = new Float32Array(10000 * 4);\n *   // ... fill mat4 columns + [uMin, vMin, uW, vH] ...\n *   world.spawn(\n *     { component: MeshFilter,      data: { assetHandle: HANDLE_QUAD } },\n *     { component: MeshRenderer,    data: { ... } },\n *     { component: SpriteInstances, data: { transforms, regions } },\n *   );\n */\nexport const SpriteInstances = defineComponent('SpriteInstances', {\n  transforms: { type: 'array<f32>' },\n  regions: { type: 'array<f32>' },\n});\n\n/**\n * Type-level hint for `data` at the `SpriteInstances` spawn site.\n *\n * The runtime ECS column shape for `array<f32>` accepts a `Float32Array`\n * payload at spawn / set time (the bytes are copied into the BufferPool\n * slot). Both fields are typed as `Float32Array` so AI-user IDE\n * autocomplete picks up the typed-array shape and the AC-09 inference\n * surfaces without `as` casts inside `world.get(e, SpriteInstances)` and\n * QueryRow access paths.\n *\n * @example\n *   import type { SpriteInstancesData } from '@forgeax/engine-render/authoring';\n *   const data: SpriteInstancesData = {\n *     transforms: new Float32Array(N * 16),\n *     regions:    new Float32Array(N * 4),\n *   };\n */\nexport type SpriteInstancesData = {\n  readonly transforms: Float32Array;\n  readonly regions: Float32Array;\n};\n","// @forgeax/engine-runtime - SpriteRegionOverride (per-entity UV region\n// override, sprite-only).\n//\n// Schema: 1 fixed-length array column `region: 'array<f32, 4>'` carrying a\n// packed UV sub-rectangle `[uMin, vMin, uW, vH]`. The fixed `4` length is\n// enforced at compile time by the ECS schema-vocab keyword\n// `'array<T, N>'` (D-6: prefer compile-time enforcement over runtime\n// fail-fast for length-bound contracts).\n//\n// Why an entity-side override component instead of a render parameter on\n// MaterialRenderer? Plan-strategy section 1 / requirements section 5\n// constraint #1 (Pipeline Isolation R1, M1 ssot): `AssetRegistry` stays\n// append-only / read-only and `MaterialRenderer` schema is frozen.\n// Per-entity render-parameter overrides ride the same rail as Layer /\n// SortKey — one ECS column per entity, read at extract time, never\n// flowing back to the asset.\n//\n// Sprite-only consumption (requirements section 5 constraint #2 + section\n// 7 boundary line 1): `render-system-extract` reads this component ONLY\n// inside the sprite bucket branch (`pipelineTag === 'sprite'` plus the\n// asset-side sprite discriminant). Opaque (`unlit` / `standard`) buckets\n// ignore the column even when the entity happens to carry it; the M3\n// T-15 grep gate\n// (`packages/runtime/src/__tests__/sprite-only-isolation-grep-gate.test.ts`)\n// asserts this file contains zero substring matches against the asset\n// discriminant identifier as a structural lock (charter P5 producer /\n// consumer separation: the component owner never names the asset\n// discriminant directly).\n//\n// Naming: bare `SpriteRegionOverride` (no `Component` suffix per\n// AGENTS.md section Component naming \"Single-semantic components drop\n// the Component suffix\"). The `Sprite` prefix is intentional — 3D UV\n// region animation lands in a separate component (e.g. future\n// `MaterialRegionOverride`) per OOS-01 to avoid premature 3D\n// generalisation. Plan-strategy section 8 naming convention pins the\n// prefix to make the AC-11 grep gate trivially decidable.\n//\n// @derives `defineComponent` factory (packages/ecs/src/component.ts) —\n//   `'array<f32, 4>'` is on the `SchemaVocabKeyword` whitelist (line ~94\n//   `array<${ManagedArrayElementType}, ${number}>`).\n// @consumes M3 T-16 (`render-system-extract.ts` sprite bucket branch\n//   reads override into `paramSnapshot.region`, post-M3 feat-20260625\n//   ablation -- the pre-ablation per-entity hop through the snapshot\n//   POD layer collapsed into the generic paramSchema-driven path).\n// @produces M4 T-23 (`spriteAnimationTickSystem` writes per-frame UV\n//   slice into `region`).\n//\n// charter mapping: F1 (single-import barrel discovery — joins Layer /\n// SortKey / Transform / SpriteAnimation under a single\n// `from '@forgeax/engine-render'`); P3 (compile-time length=4 lock\n// surfaces mismatched payloads at the TS edge before the column write\n// path observes them); P4 (consistent abstraction — same per-entity\n// override shape AI users already learned for Layer / SortKey).\n//\n// Anchors: plan-strategy section 2 D-6 + section 3.1 SRO + section 4\n// risk R-SCHEMA-2 reaction; plan-tasks.json T-11; research F-5;\n// requirements section AC-01 + section 2.4 + section 5 constraint #2.\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\n/**\n * Per-entity sprite UV region override (sprite-only).\n *\n * Carries a fixed-length `Float32Array(4)` of `[uMin, vMin, uW, vH]` that\n * `render-system-extract` reads in the sprite bucket branch and writes\n * into `paramSnapshot.region`, replacing the asset-side region for\n * this entity only (feat-20260625 M3 ablation: the prior per-entity POD\n * indirection collapsed into the generic paramSchema-driven snapshot).\n * Opaque buckets ignore this component; the AC-11 grep gate keeps the\n * producer / consumer separation structural (this file never names the\n * asset-side sprite discriminant identifier).\n *\n * Pair with `SpriteAnimation` to drive the override per frame\n * (sprite-animation-tick system, M4 T-23). Standalone use (manual region\n * override without animation) is also supported — set the column once and\n * the next extract picks up the new value.\n *\n * Schema-vocab keyword `'array<f32, 4>'` (D-6) — fixed-length 4 is the\n * compile-time enforcement axis. `Float32Array` payloads with length !== 4\n * round-trip fewer / more bytes per the underlying BufferPool slot, but\n * the slot is sized at schema registration time; AI users keep the\n * payload exactly four-floats wide.\n *\n * @example Spawn a sprite entity that displays the right half of an atlas:\n *   import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';\n *   import { SpriteRegionOverride } from '@forgeax/engine-render/authoring';\n *   import { Transform } from '@forgeax/engine-scene';\n *   import { HANDLE_QUAD } from '@forgeax/engine-assets-runtime';\n *\n *   world.spawn(\n *     { component: Transform, data: { pos: [0, 0, 0],\n *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },\n *     { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },\n *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },\n *     { component: SpriteRegionOverride,\n *       data: { region: new Float32Array([0.5, 0, 0.5, 1]) } },\n *   );\n *\n * @example Update the override at runtime (e.g. flip-frame test):\n *   world.set(entity, SpriteRegionOverride,\n *     { region: new Float32Array([0, 0, 1, 1]) }).unwrap();\n */\nexport const SpriteRegionOverride = defineComponent('SpriteRegionOverride', {\n  region: { type: 'array<f32, 4>' },\n});\n","// @forgeax/engine-runtime - TileLayer (one render layer of a Tilemap).\n//\n// Schema (4 fields):\n//   tiles       array<u32>  per-cell tile id (packed Tiled .tmj wire form);\n//                           length == parent.Tilemap.cols * rows.\n//   layerOrder  i32         render-order key (higher = drawn on top).\n//   dirty       u8          0 means clean, non-zero means dirty - the next\n//                           tilemap-chunk-extract-system pass rebuilds derived\n//                           per-cell entities for this layer.\n//   sortScope   u8 (TS:     0 = 'layer'    (default) - terrain semantics:\n//               closed                       every derived entity in this\n//               'layer' |                    layer shares one Layer.value\n//               'per-cell'                   (layerOrder << 20), so the\n//               union)                       whole layer Y-sorts as a single\n//                                            bucket. AI users grep\n//                                            `sortScope: 'layer'` to confirm.\n//                           1 = 'per-cell' - object semantics: each derived\n//                                            entity carries its own foot-Y\n//                                            key; preserves per-cell entity\n//                                            derivation for Y-interleave\n//                                            with sprite entities sharing\n//                                            the same Layer.value.\n//\n//   Storage rationale (D-V-3 R-NEW-1 fallback / round-2): ECS schema does not\n//   yet support `values: ['layer', 'per-cell']` literal-union constraints\n//   on a `'string'` column, so the on-disk shape is `u8` (0/1) but every\n//   AI-facing TS surface (`TileLayerData.sortScope`) is the closed\n//   `'layer' | 'per-cell'` string union. The bridge functions\n//   `encodeSortScope` / `decodeSortScope` are the SSOT for the two-way\n//   mapping (charter F1 — single grep target).\n//\n// Each TileLayer entity attaches to a Tilemap entity via ChildOf (the parent\n// field carries the Tilemap entity). M0 supports multiple TileLayer entities\n// per Tilemap (each rendered as an independent z-ordered layer).\n//\n// charter mapping: F1 (single-import barrel + single grep target for\n// `sortScope`), P1 (progressive disclosure — `'layer'` / `'per-cell'`\n// reads directly without a magic-number table), P3 (dirty flag is\n// explicit - silent re-extraction is forbidden), P4 (handle-free row\n// schema mirrors MeshFilter / MeshRenderer conventions).\n\nimport { defineComponent, type EcsError, type EntityHandle, type World } from '@forgeax/engine-ecs';\nimport type { Result } from '@forgeax/engine-types';\n\n/**\n * Closed string-literal union for the TileLayer.sortScope field. AI users\n * grep `sortScope` and land on this single SSOT type alias; switch\n * statements over this type are exhaustive without a default arm.\n *\n *   - 'layer'    - terrain semantics; whole layer shares one Layer.value\n *                  bucket and Y-sorts together (chunkIndex is folded into 0).\n *   - 'per-cell' - object semantics; each derived entity gets its own\n *                  chunkIndex tiebreak so it can Y-interleave with\n *                  sprite entities carrying the same Layer.value (e.g. a\n *                  player sprite riding the same SPRITE_LAYER_VALUE).\n */\nexport type SortScope = 'layer' | 'per-cell';\n\n/** Compact authoring values for the stored u8 sort-scope field. */\nexport const TilemapSort = Object.freeze({\n  layer: 0 as const,\n  perCell: 1 as const,\n});\n\n/**\n * Bridge: `SortScope` -> on-disk u8. SSOT for the encoding (`'layer'` -> 0,\n * `'per-cell'` -> 1). The compile-time exhaustive switch guards against\n * silent drift if the union ever grows; adding a new literal here without\n * adding its arm fails typecheck (charter P3 — closed unions never default).\n */\nexport function encodeSortScope(scope: SortScope): 0 | 1 {\n  switch (scope) {\n    case 'layer':\n      return TilemapSort.layer;\n    case 'per-cell':\n      return TilemapSort.perCell;\n  }\n}\n\n/**\n * Bridge: on-disk u8 -> `SortScope`. Defaults to `'layer'` for any value\n * outside `{0, 1}` (defensive — the column is typed `u8` so out-of-range\n * values can only appear if a future schema migration loosens the bound;\n * the default preserves terrain semantics which is the safer of the two).\n */\nexport function decodeSortScope(raw: number | undefined): SortScope {\n  return raw === 1 ? 'per-cell' : 'layer';\n}\n\n/**\n * Public TileLayer field shape (`world.spawn({ component: TileLayer, data:\n * { ... } })` payload). `sortScope` is the closed string union surfaced to\n * AI users; the runtime row encodes it as `u8` via `encodeSortScope` at\n * spawn time so on-disk storage stays compact.\n *\n * Treat as the `TileLayer` data SSOT — `defineComponent` schema below\n * mirrors it field-for-field with the bridge `sortScope: u8` in place of\n * the union literal.\n */\nexport interface TileLayerData {\n  readonly tiles: Uint32Array;\n  readonly layerOrder?: number;\n  readonly dirty?: number;\n  readonly sortScope?: SortScope;\n}\n\n/**\n * TileLayer component (M0 baseline rebuild + round-2 sortScope rename).\n *\n * AI users typically spawn a TileLayer + ChildOf pair pointing at an\n * existing Tilemap entity:\n *\n * @example\n *   const tilesArray = new Uint32Array(cols * rows);\n *   tilesArray[5 * cols + 7] = 1; // tile id 1 at cell (7, 5)\n *   world.spawn(\n *     { component: TileLayer, data: { tiles: tilesArray, layerOrder: 0 } },\n *     { component: ChildOf,  data: { parent: tilemapEntity } },\n *   );\n *\n * Object-layer variant (Y-interleave with sprite entities):\n *\n * > NOTE: schema storage is `u8` (ECS schema does not support\n * > string-literal-union column constraints; see R-NEW-2). The\n * > AI-user surface is the closed `SortScope` string union, but\n * > `world.spawn` requires the numeric encoding — pass through\n * > `encodeSortScope('per-cell')` rather than the literal string.\n *\n * @example\n *   world.spawn(\n *     { component: TileLayer, data: {\n *         tiles: objectTiles,\n *         layerOrder: 1000,\n *         sortScope: encodeSortScope('per-cell'),\n *       } },\n *     { component: ChildOf, data: { parent: tilemapEntity } },\n *   );\n *\n * Defaults: `layerOrder = 0`, `dirty = 0`, `sortScope = 'layer'` (stored\n * as `u8 = 0`, i.e. `encodeSortScope('layer')`). `tiles` has no default -\n * AI users supply the per-cell array at spawn time. To trigger a re-build\n * after mutating tiles in place, call `markTileLayerDirty(world, layer)`.\n */\nexport const TileLayer = defineComponent('TileLayer', {\n  tiles: { type: 'array<u32>' },\n  layerOrder: { type: 'i32', default: 0 },\n  dirty: { type: 'u8', default: 0 },\n  sortScope: { type: 'u8', default: 0 },\n});\n\n/**\n * Mark a TileLayer entity dirty so the next `tilemapChunkExtractSystem`\n * pass purges and re-spawns its derived per-cell entities. Use this after\n * mutating `TileLayer.tiles` (e.g. an in-place patch via a column view).\n *\n * Returns the underlying ECS write result - on `err` branch the caller\n * can read `.code` to recover (`'stale-entity'` if the layer was\n * despawned, `'component-not-present'` if the entity is missing the\n * TileLayer column; both kebab-case literals are members of the closed\n * `EcsErrorCode` union).\n */\nexport function markTileLayerDirty(\n  world: World,\n  layerEntity: EntityHandle,\n): Result<void, EcsError> {\n  return world.set(layerEntity, TileLayer, { dirty: 1 });\n}\n","// @forgeax/engine-runtime - Tilemap (grid + tileset reference).\n//\n// Schema (5 fields):\n//   cols       u32               total grid columns\n//   rows       u32               total grid rows\n//   tileSize   array<f32, 2>     per-cell world [width, height] (default [1, 1];\n//                                feat-20260709 M3: collapsed from the tileSizeX\n//                                / tileSizeY scalar pair into one inline column)\n//   chunkSize  u32               per-chunk axis-length in cells (default 16)\n//   tileset    string                durable TilesetAsset GUID\n//\n// Naming: single-semantic Tilemap (AGENTS.md §Component naming drops\n// `Component` suffix). One Tilemap entity per grid; TileLayer entities\n// attach via ChildOf relationship and supply the per-cell tile id array\n// for a single render-layer.\n//\n// charter mapping: F1 (single-import barrel from `@forgeax/engine-runtime`),\n// P1 (progressive disclosure - defaults cover the common case), P4 (durable\n// asset identity stays separate from World-local handles).\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\n/**\n * Tilemap component (M0 baseline rebuild).\n *\n * A Tilemap entity carries grid metadata + a single durable `tileset` GUID. The\n * actual per-cell tile id array lives on attached `TileLayer` entities\n * (one per render layer; ChildOf points back to the Tilemap entity).\n *\n * Defaults:\n *   - `tileSize = [1, 1]` (unit-cell world coordinates).\n *   - `chunkSize = 16` (tilemap-chunk-extract-system chunks 16x16 cells).\n *\n * @example Spawn a 32x32 unit-cell Tilemap referencing a TilesetAsset:\n *   const tilemap = world.spawn(\n *     { component: Tilemap, data: { cols: 32, rows: 32, tileset } },\n *     { component: Transform, data: {} },\n *   ).unwrap();\n */\nexport const Tilemap = defineComponent('Tilemap', {\n  cols: { type: 'u32', default: 0 },\n  rows: { type: 'u32', default: 0 },\n  // tileSize carries an explicit layer-2 default [1,1] (unit cell); the array\n  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).\n  tileSize: { type: 'array<f32, 2>', default: new Float32Array([1, 1]) },\n  chunkSize: { type: 'u32', default: 16 },\n  tileset: { type: 'string' },\n});\n","// @forgeax/engine-runtime - ActiveCamera KV resource + selection helper.\n//\n// feat-20260630-viewport-2x2-run-x-display-redesign M2 w12 / plan-strategy D-2.\n//\n// PROBLEM (research Finding 4): the render extract stage selects the camera by\n// archetype-query FIRST-HIT (`cameras[0]`) and fires `render-system-multi-camera`\n// when more than one [Camera, Transform, Entity] entity exists. A single engine\n// world that carries BOTH an editor orbit camera AND a game camera therefore\n// cannot pick which one renders. This module adds the minimum neutral mechanism:\n// an `ActiveCamera { entity }` resource naming the entity to render through.\n//\n// ENGINE-NEUTRAL (requirements OOS-4 / AC-16): the engine knows only entity IDs.\n// It does NOT know which entity is \"editor\" or \"game\" -- the caller (editor side)\n// decides what `ActiveCamera.entity` points at. No editor concept enters this\n// file or the engine layer.\n//\n// BACKWARD COMPATIBLE (plan-strategy D-2): when the resource is ABSENT, or the\n// named entity is not among the queried cameras, selection falls back to the\n// existing first-hit behavior unchanged. Single-camera scenes are unaffected.\n//\n// Surface:\n//   - interface  ActiveCamera { entity: number }\n//   - constant   ACTIVE_CAMERA_KEY = 'ActiveCamera'\n//   - helper     getActiveCamera(world): ActiveCamera | undefined\n//   - helper     setActiveCamera(world, entity): void\n//   - pure       selectActiveCameraIndex(cameraEntities, activeEntity): number\n//\n// @new-surface KV resource: ECS has no defineResource factory; the TS POD\n//   interface + string KV key form is the minimum-new-surface route, mirroring\n//   TransparentSortConfig. The world resource store\n//   (insertResource / getResource / hasResource) is reused unchanged.\n// @derives world.hasResource / world.insertResource / world.getResource KV API.\n// @fallback getActiveCamera KV missing returns undefined; no warn; no throw\n//   (absent ActiveCamera is a legal state -> first-hit fallback in extract).\n//\n// charter mapping: F1 (single-import barrel + single entity pointer, smallest\n// concept face vs a multi-field priority/enabled scheme) + P4 (consistent\n// abstraction -- same world.{has,get,insert}Resource KV API as every other\n// engine resource consumer).\n\nimport type { World } from '@forgeax/engine-ecs';\n\n// ────────────────────────────────────────────────────────────────────────────\n// POD interface + KV key\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Active-camera pointer (plain-data POD). Lives as a world-level resource keyed\n * by `ACTIVE_CAMERA_KEY`. `entity` is the packed entity id (engine `EntityHandle`\n * is a branded number) of the camera the renderer should use.\n *\n * The engine treats `entity` as an opaque id; whether it names an editor camera\n * or a game camera is a caller-side decision (OOS-4 — engine stays neutral).\n */\nexport interface ActiveCamera {\n  readonly entity: number;\n}\n\n/** World resource key for the `ActiveCamera` KV entry. */\nexport const ACTIVE_CAMERA_KEY = 'ActiveCamera' as const;\n\n// ────────────────────────────────────────────────────────────────────────────\n// Helpers\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Read the world's `ActiveCamera` resource.\n *\n * @fallback KV missing returns `undefined` — absent ActiveCamera is a legal\n * state (the renderer falls back to archetype first-hit). NO warn, NO throw.\n * The `hasResource` guard precedes the read so this helper never trips\n * `ResourceNotFoundError` from `world.getResource`.\n *\n * @example\n *   const a = getActiveCamera(world);   // undefined when not set\n *   if (a) { ... a.entity ... }\n */\nexport function getActiveCamera(world: World): ActiveCamera | undefined {\n  if (!world.hasResource(ACTIVE_CAMERA_KEY)) return undefined;\n  return world.getResource<ActiveCamera>(ACTIVE_CAMERA_KEY);\n}\n\n/**\n * Write the world's `ActiveCamera` resource (idempotent last-write-wins via\n * `world.insertResource`). The renderer will use the camera whose entity id\n * equals `entity`, or fall back to first-hit if that id is not a queried camera.\n *\n * @example\n *   setActiveCamera(world, gameCameraEntity);  // render through the game camera\n */\nexport function setActiveCamera(world: World, entity: number): void {\n  world.insertResource<ActiveCamera>(ACTIVE_CAMERA_KEY, { entity });\n}\n\n/**\n * Pure selection: given the entity ids of every camera surfaced by the extract\n * archetype query (in query order) and the optional active-camera entity id,\n * return the index of the active camera in `cameraEntities`, or `-1` to signal\n * \"no selection — use first-hit fallback\".\n *\n * `-1` is returned when `activeEntity` is `undefined` (resource absent) OR when\n * the id is not present among `cameraEntities` (stale / non-camera entity).\n * Both cases preserve the existing first-hit behavior (plan-strategy D-2).\n *\n * @example\n *   selectActiveCameraIndex([10, 20, 30], 20) === 1   // pick the 2nd camera\n *   selectActiveCameraIndex([10, 20, 30], undefined) === -1  // first-hit\n *   selectActiveCameraIndex([10, 20, 30], 999) === -1        // first-hit\n */\nexport function selectActiveCameraIndex(\n  cameraEntities: readonly number[],\n  activeEntity: number | undefined,\n): number {\n  if (activeEntity === undefined) return -1;\n  return cameraEntities.indexOf(activeEntity);\n}\n"]}

package/dist/chunk-ILQ5MEZF.mjs

@@ -1,32 +0,0 @@
-import { defineComponent } from '@forgeax/engine-ecs';
-
-// src/components/glyph-text.ts
-var 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,
-    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]) }
-});
-
-// src/components/sprite-playback-mode.ts
-var SPRITE_PLAYBACK_MODE_LOOP = 0;
-var SPRITE_PLAYBACK_MODE_CLAMP = 1;
-var SpritePlayback = Object.freeze({
-  loop: SPRITE_PLAYBACK_MODE_LOOP,
-  clamp: SPRITE_PLAYBACK_MODE_CLAMP
-});
-function spritePlaybackModeFromU32(value) {
-  return value === SPRITE_PLAYBACK_MODE_CLAMP ? "clamp" : "loop";
-}
-
-export { GlyphText, SpritePlayback, spritePlaybackModeFromU32 };
-//# sourceMappingURL=chunk-ILQ5MEZF.mjs.map
-//# sourceMappingURL=chunk-ILQ5MEZF.mjs.map

package/dist/chunk-ILQ5MEZF.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/glyph-text.ts","../src/components/sprite-playback-mode.ts"],"names":[],"mappings":";;;AAkDO,IAAM,SAAA,GAAY,gBAAgB,WAAA,EAAa;AAAA;AAAA;AAAA,EAGpD,UAAA,EAAY;AAAA,IACV,IAAA,EAAM,mBAAA;AAAA,IACN,OAAA,EAAS,CAAA;AAAA,IACT,mBAAA,EAAqB;AAAA,GACvB;AAAA,EACA,IAAA,EAAM,EAAE,IAAA,EAAM,QAAA,EAAU,SAAS,EAAA,EAAG;AAAA,EACpC,QAAA,EAAU,EAAE,IAAA,EAAM,KAAA,EAAO,SAAS,EAAA,EAAG;AAAA;AAAA;AAAA,EAGrC,KAAA,EAAO,EAAE,IAAA,EAAM,eAAA,EAAiB,OAAA,EAAS,IAAI,YAAA,CAAa,CAAC,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAC,CAAC,CAAA;AACxE,CAAC;;;ACXM,IAAM,yBAAA,GAA4B,CAAA;AAGlC,IAAM,0BAAA,GAA6B,CAAA;AAGnC,IAAM,cAAA,GAAiB,OAAO,MAAA,CAAO;AAAA,EAC1C,IAAA,EAAM,yBAAA;AAAA,EACN,KAAA,EAAO;AACT,CAAU;AAeH,SAAS,0BAA0B,KAAA,EAAmC;AAC3E,EAAA,OAAO,KAAA,KAAU,6BAA6B,OAAA,GAAU,MAAA;AAC1D","file":"chunk-ILQ5MEZF.mjs","sourcesContent":["// @forgeax/engine-runtime - GlyphText component (feat-20260531-world-space-msdf-text-rendering M4 / w14).\n//\n// `GlyphText` is the authoring source component for world-space MSDF text\n// (requirements AC-06 / §domain model). It carries ONLY authoring data; the\n// glyph quad baking + MeshFilter / MeshRenderer attachment is the job of the\n// `glyphTextLayoutSystem` (plan-strategy D-2: GlyphText is pure authoring\n// data, baking is a system responsibility). There is NO `TextLayoutAsset`\n// intermediate (OOS-5) -- layout output lives directly in a baked MeshAsset.\n//\n// Naming: single-semantic component drops the `Component` suffix\n// (AGENTS.md §Component naming rule #1 -- Transform / Camera / GlyphText).\n//\n// Schema vocab:\n//   - `fontHandle: 'shared<FontAsset>'` -> `Handle<'FontAsset', 'shared'>`\n//     (u32-stored; AssetRegistry owns the FontAsset lifecycle). AI users\n//     obtain the handle via `assets.loadByGuid<FontAsset>(guid)`.\n//   - `text: 'string'` -> native JS string (UniqueRefStore-backed, same\n//     dispatch as `Name.value`).\n//   - `fontSize: 'f32'` -> layout scale applied to the FontAsset metrics.\n//   - `color: 'array<f32, 4>'` -> linear-space rgba tint (feat-20260709 M3:\n//     collapsed from four `colorR/G/B/A` scalar columns into one inline\n//     stride-4 SoA column, mirroring the DirectionalLight direction/color\n//     idiom). Explicit layer-2 default [1,1,1,1] (opaque white).\n//\n// charter mapping: P1 (single import surface from `@forgeax/engine-render`,\n// co-located with `glyphTextLayoutSystem` that consumes it) + P3\n// (machine-readable schema literal) + P5 (consistent abstraction: same\n// `'shared<T>'` idiom as MeshFilter.assetHandle / MeshRenderer.materials).\n\nimport { defineComponent } from '@forgeax/engine-ecs';\n\n/**\n * Glyph text authoring component (world-space MSDF text).\n *\n * Spawn an entity with a `GlyphText` and the `glyphTextLayoutSystem`\n * (auto-wired by `createRenderer` / `createApp`) lays out the glyph quads,\n * bakes a `MeshAsset`, and attaches `MeshFilter` + `MeshRenderer` on the\n * next frame (Commands-deferred). Mutating `text` / `fontSize` / `color`\n * re-bakes the mesh in place (plan-strategy D-1 updateMesh; registry size\n * unchanged, AC-08).\n *\n * @example Spawn a world-space label:\n *   import { GlyphText } from '@forgeax/engine-render/authoring';\n *   const font = (await assets.loadByGuid(fontGuid)).unwrap();\n *   world.spawn({\n *     component: GlyphText,\n *     data: { fontHandle: font, text: 'Hello', fontSize: 32,\n *             color: [1, 1, 1, 1] },\n *   });\n */\nexport const GlyphText = defineComponent('GlyphText', {\n  // The layout/render owner re-resolves the font asset on the target world;\n  // authoring text and style remain portable simulation state.\n  fontHandle: {\n    type: 'shared<FontAsset>',\n    default: 0 as never,\n    simulationTransient: true,\n  },\n  text: { type: 'string', default: '' },\n  fontSize: { type: 'f32', default: 16 },\n  // color carries an explicit layer-2 default [1,1,1,1] (opaque white); the\n  // array layer-3 fallback is all-zero, so the default MUST be explicit (D-5).\n  color: { type: 'array<f32, 4>', default: new Float32Array([1, 1, 1, 1]) },\n});\n","// @forgeax/engine-runtime - SpritePlaybackMode (u32 column encoding + mapper).\n//\n// SSOT for the SpriteAnimation.playbackMode ECS column (M2 T-12) and the\n// runtime tick-system branch selector (M4 T-23). The shape mirrors the M1\n// `Tonemap` block in `./camera.ts:72-90` (TONEMAP_NONE = 0 /\n// TONEMAP_REINHARD_EXTENDED = 1 + `type Tonemap = 'none' |\n// 'reinhard-extended'` + `tonemapFromF32`) for charter P4 consistent\n// abstraction — AI users keep one mental model across all u32-encoded\n// closed-union schema columns.\n//\n// Why `'u32'` + constant + mapper instead of a string-literal column?\n// ECS schema whitelist `SchemaFieldType` (packages/ecs/src/component.ts\n// section schema-field-type) does not accept string-literal unions\n// (research F-2 + F-5). Storing a u32 + translating to a closed\n// `'loop' | 'clamp'` literal union at the tick-system seam preserves\n// AI-user-facing narrowing (`switch (mode) { case 'loop': ... }`)\n// without forcing the ECS column to learn a new field-type vocabulary.\n//\n// Naming convention (plan-strategy section 8.command naming):\n//   SPRITE_PLAYBACK_MODE_LOOP / SPRITE_PLAYBACK_MODE_CLAMP mirror M1\n//   TONEMAP_* / TRANSPARENT_SORT_MODE_*. `spritePlaybackModeFromU32`\n//   mirrors `tonemapFromF32` / `cameraProjectionFromF32`. AI users\n//   discover the trio via single-import barrel re-export from\n//   `@forgeax/engine-runtime` (wired in by M2 T-13).\n//\n// Anchors: plan-strategy section 2 D-5 + section 3.1 PR block SPM +\n//          section 4 risk R-SCHEMA-1 reaction; research F-2 + F-5;\n//          requirements section AC-02 + section 2.3 playbackMode row;\n//          plan-tasks.json T-07 acceptanceCheck (rg\n//          \"SPRITE_PLAYBACK_MODE_LOOP|SPRITE_PLAYBACK_MODE_CLAMP|\n//          spritePlaybackModeFromU32\" >= 3 hits in this file).\n\n/**\n * Playback mode discriminator literal union (requirements section AC-02 +\n * section 2.3). Two members for the MVP:\n *\n *   `'loop'`  — `currentFrame = (currentFrame + 1) % frameCount`; the\n *               sprite-animation-tick system wraps the index when\n *               `accumDt >= frameDuration` (default for hello-sprite-\n *               atlas demo \"100 sprites synchronised walk cycle\").\n *   `'clamp'` — `currentFrame = min(currentFrame + 1, frameCount - 1)`;\n *               holds the last frame for death / terminator-animation\n *               style sequences (requirements section 2.5 q8 lock).\n *\n * Future modes (`'pingpong'`, reverse playback, arbitrary frame index\n * jumps) are deferred per requirements OOS-03. The closed union shape\n * leaves room for additive growth without breaking the u32 enum encoding\n * (plan-strategy section 2 D-5).\n */\nexport type SpritePlaybackMode = 'loop' | 'clamp';\n\n/** Numeric encoding of the loop playback mode (schema value for `playbackMode`). */\nexport const SPRITE_PLAYBACK_MODE_LOOP = 0 as const;\n\n/** Numeric encoding of the clamp playback mode (schema value for `playbackMode`). */\nexport const SPRITE_PLAYBACK_MODE_CLAMP = 1 as const;\n\n/** Grouped authoring values; the numeric ECS encoding stays owner-local. */\nexport const SpritePlayback = Object.freeze({\n  loop: SPRITE_PLAYBACK_MODE_LOOP,\n  clamp: SPRITE_PLAYBACK_MODE_CLAMP,\n} as const);\n\n/**\n * Map a `SpriteAnimation.playbackMode` numeric column value to the closed\n * `SpritePlaybackMode` string-literal union. The defensive fallback mirrors\n * `cameraProjectionFromF32` / `tonemapFromF32` precedent — a value other\n * than `SPRITE_PLAYBACK_MODE_CLAMP` (1) maps to `'loop'`, so stale or\n * uninitialised entities surface a predictable playback shape through the\n * tick-system query (rather than throwing or returning `undefined`).\n * Validation of `playbackMode` happens at schema-write time, not here.\n *\n * The tick-system in M4 T-23 (`spriteAnimationTickSystem`) consumes the\n * return value via `switch (mode) { case 'loop': ...; case 'clamp': ... }`\n * to pick the per-branch frame-advance arithmetic.\n */\nexport function spritePlaybackModeFromU32(value: number): SpritePlaybackMode {\n  return value === SPRITE_PLAYBACK_MODE_CLAMP ? 'clamp' : 'loop';\n}\n"]}