@forgeax/engine-render 0.1.2

package/dist/components/sort-key.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 declare const SortKey: import("@forgeax/engine-ecs").Component<"SortKey", {
+    readonly value: "f32";
+}>;
+//# sourceMappingURL=sort-key.d.ts.map

package/dist/components/sort-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort-key.d.ts","sourceRoot":"","sources":["../../src/components/sort-key.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,OAAO;;EAElB,CAAC"}

package/dist/components/spot-light.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 declare const SpotLight: import("@forgeax/engine-ecs").Component<"SpotLight", {
+    readonly direction: "array<f32, 3>";
+    readonly color: "array<f32, 3>";
+    readonly intensity: "f32";
+    readonly range: "f32";
+    readonly innerConeDeg: "f32";
+    readonly outerConeDeg: "f32";
+    readonly castShadow: "bool";
+    readonly mapSize: "f32";
+    readonly depthBias: "f32";
+    readonly normalBias: "f32";
+    readonly nearPlane: "f32";
+    readonly farPlane: "f32";
+    readonly pcfKernelSize: "f32";
+}>;
+//# sourceMappingURL=spot-light.d.ts.map

package/dist/components/spot-light.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spot-light.d.ts","sourceRoot":"","sources":["../../src/components/spot-light.ts"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;EAmBpB,CAAC"}

package/dist/components/sprite-animation.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 declare const SpriteAnimation: import("@forgeax/engine-ecs").Component<"SpriteAnimation", {
+    readonly frameCount: "u32";
+    readonly frameDuration: "f32";
+    readonly currentFrame: "u32";
+    readonly accumDt: "f32";
+    readonly regions: "array<f32>";
+    readonly playbackMode: "u32";
+}>;
+//# sourceMappingURL=sprite-animation.d.ts.map

package/dist/components/sprite-animation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-animation.d.ts","sourceRoot":"","sources":["../../src/components/sprite-animation.ts"],"names":[],"mappings":"AA+FA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH,eAAO,MAAM,eAAe;;;;;;;EAO1B,CAAC"}

package/dist/components/sprite-instances.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 declare const SpriteInstances: import("@forgeax/engine-ecs").Component<"SpriteInstances", {
+    readonly transforms: "array<f32>";
+    readonly regions: "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;
+};
+//# sourceMappingURL=sprite-instances.d.ts.map

package/dist/components/sprite-instances.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-instances.d.ts","sourceRoot":"","sources":["../../src/components/sprite-instances.ts"],"names":[],"mappings":"AAgIA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,eAAe;;;EAG1B,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;CAChC,CAAC"}

package/dist/components/sprite-playback-mode.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 declare const SPRITE_PLAYBACK_MODE_LOOP: 0;
+/** Numeric encoding of the clamp playback mode (schema value for `playbackMode`). */
+export declare const SPRITE_PLAYBACK_MODE_CLAMP: 1;
+/**
+ * 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 declare function spritePlaybackModeFromU32(value: number): SpritePlaybackMode;
+//# sourceMappingURL=sprite-playback-mode.d.ts.map

package/dist/components/sprite-playback-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-playback-mode.d.ts","sourceRoot":"","sources":["../../src/components/sprite-playback-mode.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,CAAC;AAElD,oFAAoF;AACpF,eAAO,MAAM,yBAAyB,EAAG,CAAU,CAAC;AAEpD,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,EAAG,CAAU,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAE3E"}

package/dist/components/sprite-region-override.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Per-entity sprite UV region override (sprite-only).
+ *
+ * Carries a fixed-length `Float32Array(4)` of `[uMin, vMin, uW, vH]` that
+ * `render-system-extract` reads in the sprite bucket branch and writes
+ * into `paramSnapshot.region`, replacing the asset-side region for
+ * this entity only (feat-20260625 M3 ablation: the prior per-entity POD
+ * indirection collapsed into the generic paramSchema-driven snapshot).
+ * Opaque buckets ignore this component; the AC-11 grep gate keeps the
+ * producer / consumer separation structural (this file never names the
+ * asset-side sprite discriminant identifier).
+ *
+ * Pair with `SpriteAnimation` to drive the override per frame
+ * (sprite-animation-tick system, M4 T-23). Standalone use (manual region
+ * override without animation) is also supported — set the column once and
+ * the next extract picks up the new value.
+ *
+ * Schema-vocab keyword `'array<f32, 4>'` (D-6) — fixed-length 4 is the
+ * compile-time enforcement axis. `Float32Array` payloads with length !== 4
+ * round-trip fewer / more bytes per the underlying BufferPool slot, but
+ * the slot is sized at schema registration time; AI users keep the
+ * payload exactly four-floats wide.
+ *
+ * @example Spawn a sprite entity that displays the right half of an atlas:
+ *   import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+ *   import { SpriteRegionOverride } from '@forgeax/engine-render/authoring';
+ *   import { Transform } from '@forgeax/engine-scene';
+ *   import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+ *   const quadMesh = world.internSharedRef(createPrimitiveMesh('quad').unwrap());
+ *
+ *   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: SpriteRegionOverride,
+ *       data: { region: new Float32Array([0.5, 0, 0.5, 1]) } },
+ *   );
+ *
+ * @example Update the override at runtime (e.g. flip-frame test):
+ *   world.set(entity, SpriteRegionOverride,
+ *     { region: new Float32Array([0, 0, 1, 1]) }).unwrap();
+ */
+export declare const SpriteRegionOverride: import("@forgeax/engine-ecs").Component<"SpriteRegionOverride", {
+    readonly region: "array<f32, 4>";
+}>;
+//# sourceMappingURL=sprite-region-override.d.ts.map

package/dist/components/sprite-region-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-region-override.d.ts","sourceRoot":"","sources":["../../src/components/sprite-region-override.ts"],"names":[],"mappings":"AA4DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,oBAAoB;;EAE/B,CAAC"}

package/dist/components/tile-layer.d.ts

@@ -0,0 +1,101 @@
+import { type EcsError, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { Result } from '@forgeax/engine-types';
+/**
+ * Closed string-literal union for the TileLayer.sortScope field. AI users
+ * grep `sortScope` and land on this single SSOT type alias; switch
+ * statements over this type are exhaustive without a default arm.
+ *
+ *   - 'layer'    - terrain semantics; whole layer shares one Layer.value
+ *                  bucket and Y-sorts together (chunkIndex is folded into 0).
+ *   - 'per-cell' - object semantics; each derived entity gets its own
+ *                  chunkIndex tiebreak so it can Y-interleave with
+ *                  sprite entities carrying the same Layer.value (e.g. a
+ *                  player sprite riding the same SPRITE_LAYER_VALUE).
+ */
+export type SortScope = 'layer' | 'per-cell';
+/**
+ * Bridge: `SortScope` -> on-disk u8. SSOT for the encoding (`'layer'` -> 0,
+ * `'per-cell'` -> 1). The compile-time exhaustive switch guards against
+ * silent drift if the union ever grows; adding a new literal here without
+ * adding its arm fails typecheck (charter P3 — closed unions never default).
+ */
+export declare function encodeSortScope(scope: SortScope): 0 | 1;
+/**
+ * Bridge: on-disk u8 -> `SortScope`. Defaults to `'layer'` for any value
+ * outside `{0, 1}` (defensive — the column is typed `u8` so out-of-range
+ * values can only appear if a future schema migration loosens the bound;
+ * the default preserves terrain semantics which is the safer of the two).
+ */
+export declare function decodeSortScope(raw: number | undefined): SortScope;
+/**
+ * Public TileLayer field shape (`world.spawn({ component: TileLayer, data:
+ * { ... } })` payload). `sortScope` is the closed string union surfaced to
+ * AI users; the runtime row encodes it as `u8` via `encodeSortScope` at
+ * spawn time so on-disk storage stays compact.
+ *
+ * Treat as the `TileLayer` data SSOT — `defineComponent` schema below
+ * mirrors it field-for-field with the bridge `sortScope: u8` in place of
+ * the union literal.
+ */
+export interface TileLayerData {
+    readonly tiles: Uint32Array;
+    readonly layerOrder?: number;
+    readonly dirty?: number;
+    readonly sortScope?: SortScope;
+}
+/**
+ * TileLayer component (M0 baseline rebuild + round-2 sortScope rename).
+ *
+ * AI users typically spawn a TileLayer + ChildOf pair pointing at an
+ * existing Tilemap entity:
+ *
+ * @example
+ *   const tilesArray = new Uint32Array(cols * rows);
+ *   tilesArray[5 * cols + 7] = 1; // tile id 1 at cell (7, 5)
+ *   world.spawn(
+ *     { component: TileLayer, data: { tiles: tilesArray, layerOrder: 0 } },
+ *     { component: ChildOf,  data: { parent: tilemapEntity } },
+ *   );
+ *
+ * Object-layer variant (Y-interleave with sprite entities):
+ *
+ * > NOTE: schema storage is `u8` (ECS schema does not support
+ * > string-literal-union column constraints; see R-NEW-2). The
+ * > AI-user surface is the closed `SortScope` string union, but
+ * > `world.spawn` requires the numeric encoding — pass through
+ * > `encodeSortScope('per-cell')` rather than the literal string.
+ *
+ * @example
+ *   world.spawn(
+ *     { component: TileLayer, data: {
+ *         tiles: objectTiles,
+ *         layerOrder: 1000,
+ *         sortScope: encodeSortScope('per-cell'),
+ *       } },
+ *     { component: ChildOf, data: { parent: tilemapEntity } },
+ *   );
+ *
+ * Defaults: `layerOrder = 0`, `dirty = 0`, `sortScope = 'layer'` (stored
+ * as `u8 = 0`, i.e. `encodeSortScope('layer')`). `tiles` has no default -
+ * AI users supply the per-cell array at spawn time. To trigger a re-build
+ * after mutating tiles in place, call `markTileLayerDirty(world, layer)`.
+ */
+export declare const TileLayer: import("@forgeax/engine-ecs").Component<"TileLayer", {
+    readonly tiles: "array<u32>";
+    readonly layerOrder: "i32";
+    readonly dirty: "u8";
+    readonly sortScope: "u8";
+}>;
+/**
+ * Mark a TileLayer entity dirty so the next `tilemapChunkExtractSystem`
+ * pass purges and re-spawns its derived per-cell entities. Use this after
+ * mutating `TileLayer.tiles` (e.g. an in-place patch via a column view).
+ *
+ * Returns the underlying ECS write result - on `err` branch the caller
+ * can read `.code` to recover (`'stale-entity'` if the layer was
+ * despawned, `'component-not-present'` if the entity is missing the
+ * TileLayer column; both kebab-case literals are members of the closed
+ * `EcsErrorCode` union).
+ */
+export declare function markTileLayerDirty(world: World, layerEntity: EntityHandle): Result<void, EcsError>;
+//# sourceMappingURL=tile-layer.d.ts.map

package/dist/components/tile-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tile-layer.d.ts","sourceRoot":"","sources":["../../src/components/tile-layer.ts"],"names":[],"mappings":"AAyCA,OAAO,EAAmB,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,CAAC,GAAG,CAAC,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAElE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,SAAS;;;;;EAKpB,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,EACZ,WAAW,EAAE,YAAY,GACxB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAExB"}

package/dist/components/tilemap.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tilemap component (M0 baseline rebuild).
+ *
+ * A Tilemap entity carries grid metadata + a single durable `tileset` GUID. The
+ * actual per-cell tile id array lives on attached `TileLayer` entities
+ * (one per render layer; ChildOf points back to the Tilemap entity).
+ *
+ * Defaults:
+ *   - `tileSize = [1, 1]` (unit-cell world coordinates).
+ *   - `chunkSize = 16` (tilemap-chunk-extract-system chunks 16x16 cells).
+ *
+ * @example Spawn a 32x32 unit-cell Tilemap referencing a TilesetAsset:
+ *   const tilemap = world.spawn(
+ *     { component: Tilemap, data: { cols: 32, rows: 32, tileset } },
+ *     { component: Transform, data: {} },
+ *   ).unwrap();
+ */
+export declare const Tilemap: import("@forgeax/engine-ecs").Component<"Tilemap", {
+    readonly cols: "u32";
+    readonly rows: "u32";
+    readonly tileSize: "array<f32, 2>";
+    readonly chunkSize: "u32";
+    readonly tileset: "string";
+}>;
+//# sourceMappingURL=tilemap.d.ts.map

package/dist/components/tilemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilemap.d.ts","sourceRoot":"","sources":["../../src/components/tilemap.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO;;;;;;EAQlB,CAAC"}

package/dist/components/visibility.d.ts

@@ -0,0 +1,22 @@
+/** Numeric labels stored by the public Visibility enum field. */
+export declare const VisibilityStateValue: Readonly<{
+    readonly inherited: 0;
+    readonly hidden: 1;
+    readonly visible: 2;
+}>;
+/** Author visibility intent accepted by the Visibility component. */
+export type VisibilityState = keyof typeof VisibilityStateValue;
+/**
+ * Decode the stored u32 without treating an unknown value as a valid state.
+ * Invalid values are rejected at ECS write boundaries; undefined remains an
+ * explicit signal for readers that inspect externally corrupted columns.
+ */
+export declare function visibilityStateFromU32(value: number): VisibilityState | undefined;
+/**
+ * Author intent for render participation. Omitted state is inherited and is
+ * therefore visible when no valid parent intent is available.
+ */
+export declare const Visibility: import("@forgeax/engine-ecs").Component<"Visibility", {
+    readonly state: "enum";
+}>;
+//# sourceMappingURL=visibility.d.ts.map

package/dist/components/visibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility.d.ts","sourceRoot":"","sources":["../../src/components/visibility.ts"],"names":[],"mappings":"AAEA,iEAAiE;AACjE,eAAO,MAAM,oBAAoB;;;;EAItB,CAAC;AAEZ,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAWjF;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU;;EAkBtB,CAAC"}

package/dist/construct-renderer.d.ts

@@ -0,0 +1,2 @@
+export { type BundlerOptions, createRenderer as constructRenderer, } from './renderer/renderer-factory';
+//# sourceMappingURL=construct-renderer.d.ts.map

package/dist/construct-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"construct-renderer.d.ts","sourceRoot":"","sources":["../src/construct-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,cAAc,IAAI,iBAAiB,GACpC,MAAM,6BAA6B,CAAC"}

package/dist/construct-renderer.mjs

@@ -0,0 +1,6 @@
+export { createRenderer as constructRenderer } from './chunk-33UF5SAO.mjs';
+import './chunk-QRXPSX4X.mjs';
+import './chunk-A5QCJSNL.mjs';
+import './chunk-YAKEQPWO.mjs';
+//# sourceMappingURL=construct-renderer.mjs.map
+//# sourceMappingURL=construct-renderer.mjs.map

package/dist/construct-renderer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"construct-renderer.mjs"}

package/dist/debug-draw-glue.d.ts

@@ -0,0 +1,56 @@
+import type { DebugDraw } from '@forgeax/engine-debug-draw';
+import { type Mat4 } from '@forgeax/engine-math';
+import type { RenderGraph, RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame } from './render-pipeline';
+import type { RenderPipelineContext } from './render-pipeline-context';
+import type { RenderPipelineTarget } from './render-pipeline-target';
+import type { Renderer } from './renderer';
+/**
+ * Create a DebugDraw instance once `renderer.ready` settles.
+ *
+ * Waits for the GPU device + shader manifest + builtin asset upload to
+ * complete before creating the DebugDraw PSO. Stores the instance in the
+ * package-internal registry so graph pass closures can reach it.
+ *
+ * Bug A fix (feat-20260626 m6-4): the PSO color format MUST equal the swap-chain
+ * LDR view the overlay pass draws into (`attachDebugOverlayPass` flushes to
+ * `ctx.view`), or the backend rejects the render pass with an attachment-state
+ * mismatch every frame. The view format is the SSOT
+ * `selectSwapChainFormat(caps.storageBuffer).view` -- `bgra8unorm-srgb` on
+ * native WebGPU (follows getPreferredCanvasFormat + the srgb-via-viewFormats
+ * route) and `rgba8unorm-srgb` on wgpu-wasm GLES -- the same derivation
+ * `PipelineState.colorAttachmentFormat` uses (memory
+ * offscreen-rt-format-must-follow-swapchain-not-hardcode-rgba). The hardcoded
+ * `'bgra8unorm'` default was latent until the overlay pass actually flushed
+ * (before the glue merge the pass was a no-op stub that never validated). A
+ * caller may still pass an explicit `format` to target a custom surface.
+ */
+export declare function createDebugDrawOnReady(renderer: Renderer, format?: TextureFormat): Promise<DebugDraw>;
+/** Release one app-owned DebugDraw and remove it from render-pass lookup. */
+export declare function releaseDebugDraw(debugDraw: DebugDraw): void;
+/**
+ * Attach a DebugOverlay pass to a render graph at the tonemap suffix.
+ *
+ * The pass is added with empty reads/writes (the swap-chain is not a
+ * graph-declared target). The execute closure reads `ctx.view` (the
+ * swap-chain TextureView) + `ctx.encoder` (the shared frame command
+ * encoder) and calls `dd.flush(encoder, view, viewProj)` using the
+ * registered DebugDraw instance.
+ *
+ * When no DebugDraw is registered (createDebugDrawOnReady not called,
+ * or tree-shaken), the pass is a silent no-op.
+ *
+ * Per plan D-8: URP and HDRP both call this helper with their respective
+ * tonemap-suffix graphs, keeping the wiring single-source.
+ *
+ * @param graph - The per-frame RenderGraph (URP forward-graph or HDRP tonemap-graph).
+ * @param getViewProj - Thunk that returns camera.viewProj from the pass context
+ *   at execute time (not at graph-build time).
+ */
+export declare function attachDebugOverlayPass(graph: RenderGraph<RenderPipelineContext>, getViewProj: (ctx: RenderPipelineContext) => Mat4, options?: {
+    readonly reads?: readonly string[];
+}): void;
+export declare function addTypedDebugOverlayPass(graph: RenderGraphBuilder<RenderPipelineFrame>, output: RenderPipelineTarget): Result<void, RenderGraphError>;
+//# sourceMappingURL=debug-draw-glue.d.ts.map

package/dist/debug-draw-glue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-draw-glue.d.ts","sourceRoot":"","sources":["../src/debug-draw-glue.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,KAAK,IAAI,EAAQ,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,SAAS,CAAC,CAkBpB;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAG3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,CAAC,qBAAqB,CAAC,EACzC,WAAW,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,EACjD,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACnD,IAAI,CAcN;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAuChC"}

package/dist/deferred-lighting.d.ts

@@ -0,0 +1,13 @@
+import type { GraphResourceResolver } from '@forgeax/engine-render-graph';
+import type { RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import type { RenderPipelineFrame } from './render-pipeline';
+import type { RenderPipelineTarget } from './render-pipeline-target';
+export declare const HDRP_DEFERRED_LIGHTING_POST_PROCESS_ID = "forgeax::hdrp-deferred-lighting";
+export declare function encodeDeferredLightingPass(frame: RenderPipelineFrame, pass: RhiRenderPassEncoder, resources: GraphResourceResolver, targets: {
+    readonly albedo: RenderPipelineTarget;
+    readonly normal: RenderPipelineTarget;
+    readonly emissive: RenderPipelineTarget;
+    readonly depth: RenderPipelineTarget;
+    readonly output: RenderPipelineTarget;
+}): void;
+//# sourceMappingURL=deferred-lighting.d.ts.map

package/dist/deferred-lighting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-lighting.d.ts","sourceRoot":"","sources":["../src/deferred-lighting.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAkB,MAAM,8BAA8B,CAAC;AAC1F,OAAO,KAAK,EAAE,oBAAoB,EAAe,MAAM,qBAAqB,CAAC;AAG7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGrE,eAAO,MAAM,sCAAsC,oCAAoC,CAAC;AA4BxF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,mBAAmB,EAC1B,IAAI,EAAE,oBAAoB,EAC1B,SAAS,EAAE,qBAAqB,EAChC,OAAO,EAAE;IACP,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;CACvC,GACA,IAAI,CA4CN"}