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

package/dist/systems/active-camera.d.ts

@@ -0,0 +1,53 @@
+import type { World } from '@forgeax/engine-ecs';
+/**
+ * Active-camera pointer (plain-data POD). Lives as a world-level resource keyed
+ * by `ACTIVE_CAMERA_KEY`. `entity` is the packed entity id (engine `EntityHandle`
+ * is a branded number) of the camera the renderer should use.
+ *
+ * The engine treats `entity` as an opaque id; whether it names an editor camera
+ * or a game camera is a caller-side decision (OOS-4 — engine stays neutral).
+ */
+export interface ActiveCamera {
+    readonly entity: number;
+}
+/** World resource key for the `ActiveCamera` KV entry. */
+export declare const ACTIVE_CAMERA_KEY: "ActiveCamera";
+/**
+ * Read the world's `ActiveCamera` resource.
+ *
+ * @fallback KV missing returns `undefined` — absent ActiveCamera is a legal
+ * state (the renderer falls back to archetype first-hit). NO warn, NO throw.
+ * The `hasResource` guard precedes the read so this helper never trips
+ * `ResourceNotFoundError` from `world.getResource`.
+ *
+ * @example
+ *   const a = getActiveCamera(world);   // undefined when not set
+ *   if (a) { ... a.entity ... }
+ */
+export declare function getActiveCamera(world: World): ActiveCamera | undefined;
+/**
+ * Write the world's `ActiveCamera` resource (idempotent last-write-wins via
+ * `world.insertResource`). The renderer will use the camera whose entity id
+ * equals `entity`, or fall back to first-hit if that id is not a queried camera.
+ *
+ * @example
+ *   setActiveCamera(world, gameCameraEntity);  // render through the game camera
+ */
+export declare function setActiveCamera(world: World, entity: number): void;
+/**
+ * Pure selection: given the entity ids of every camera surfaced by the extract
+ * archetype query (in query order) and the optional active-camera entity id,
+ * return the index of the active camera in `cameraEntities`, or `-1` to signal
+ * "no selection — use first-hit fallback".
+ *
+ * `-1` is returned when `activeEntity` is `undefined` (resource absent) OR when
+ * the id is not present among `cameraEntities` (stale / non-camera entity).
+ * Both cases preserve the existing first-hit behavior (plan-strategy D-2).
+ *
+ * @example
+ *   selectActiveCameraIndex([10, 20, 30], 20) === 1   // pick the 2nd camera
+ *   selectActiveCameraIndex([10, 20, 30], undefined) === -1  // first-hit
+ *   selectActiveCameraIndex([10, 20, 30], 999) === -1        // first-hit
+ */
+export declare function selectActiveCameraIndex(cameraEntities: readonly number[], activeEntity: number | undefined): number;
+//# sourceMappingURL=active-camera.d.ts.map

package/dist/systems/active-camera.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-camera.d.ts","sourceRoot":"","sources":["../../src/systems/active-camera.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAMjD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,EAAG,cAAuB,CAAC;AAMzD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,GAAG,SAAS,CAGtE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAElE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,YAAY,EAAE,MAAM,GAAG,SAAS,GAC/B,MAAM,CAGR"}

package/dist/systems/pass-selector.d.ts

@@ -0,0 +1,24 @@
+import type { MaterialPass, PassSelector } from '@forgeax/engine-types';
+/**
+ * Test whether a pass's tags match a {@link PassSelector}.
+ *
+ * Matching rule (AC-05): every key in the selector must exist in the pass's
+ * `tags` and the pass's tag value must be in the selector's value list for
+ * that key. An empty selector matches every pass.
+ *
+ * @param tags The pass-level tags (free key-value pairs)
+ * @param selector The selector to match against
+ */
+export declare function matchPass(tags: Record<string, string>, selector: PassSelector): boolean;
+/**
+ * Filter passes whose tags match the given {@link PassSelector}.
+ *
+ * An empty selector matches all passes (returns the input array reference).
+ * Otherwise each pass is checked via {@link matchPass}.
+ *
+ * @param passes The material's pass descriptors
+ * @param selector The pass selector
+ * @returns Filtered array of matching passes
+ */
+export declare function selectPasses(passes: readonly MaterialPass[], selector: PassSelector): readonly MaterialPass[];
+//# sourceMappingURL=pass-selector.d.ts.map

package/dist/systems/pass-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass-selector.d.ts","sourceRoot":"","sources":["../../src/systems/pass-selector.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAExE;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CASvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,QAAQ,EAAE,YAAY,GACrB,SAAS,YAAY,EAAE,CAKzB"}

package/dist/systems/skin-palette-allocator.d.ts

@@ -0,0 +1,49 @@
+import type { Mat4 } from '@forgeax/engine-math';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import type { SkinPaletteSlice } from './skin-palette-types';
+export interface SkinPaletteAllocator {
+    /**
+     * Static BG entry size for `pbr-skin-mesh-array-bgl @binding(1)`. Always
+     * `MAX_JOINTS * 64 = 16320`; consumers (record stage) bind this size
+     * when building the BG. Path-independent.
+     */
+    readonly bindingWindowBytes: number;
+    /**
+     * True when this allocator is in storage-path mode (single shared
+     * buffer + dynOffset). False on the uniform fallback (per-entity
+     * buffer + dynOffset always 0). Record-stage reads this only for
+     * shape assertions in tests; production code branches via
+     * `slice.buffer` identity (shared vs per-entity), not this flag.
+     */
+    readonly useStorageBuffer: boolean;
+    /**
+     * Allocate a slice for `jointCount` joints. Returns the buffer + byte
+     * offset the record stage should bind. Storage path returns the same
+     * shared buffer for every call; uniform path mints (or pool-reuses) a
+     * per-entity buffer and returns it with `byteOffset: 0`. Both paths
+     * guarantee BG validation: storage extends the shared buffer's size,
+     * uniform sizes the per-entity buffer to exactly `bindingWindowBytes`.
+     *
+     * @throws if storage path buffer would exceed
+     *         `device.limits.maxStorageBufferBindingSize`
+     */
+    allocateSlice(jointCount: number): SkinPaletteSlice;
+    /**
+     * Write joint matrices into the slice's buffer at the slice's offset.
+     * Computes M_i = jointWorldTransforms[i] * ibm[i] per joint.
+     *
+     * `jointWorlds[i]` is taken straight from `Skin.joints[i]` entity's
+     * `Transform.world` view (a 16-float column-major Float32Array
+     * written by propagateTransforms); zero recompose, premultiplies
+     * directly against the IBM.
+     */
+    writeJointPalette(slice: SkinPaletteSlice, ibms: readonly Float32Array[], jointWorlds: readonly Mat4[]): void;
+    /**
+     * Reset for next frame. Storage path: cursor rewinds, shared buffer
+     * stays. Uniform path: per-entity buffer cursor rewinds (pool entries
+     * stay allocated and round-robin to the next frame's first entity).
+     */
+    resetForFrame(): void;
+}
+export declare function createSkinPaletteAllocator(device: RhiDevice, maxBindingSize: number, useStorageBuffer?: boolean): SkinPaletteAllocator;
+//# sourceMappingURL=skin-palette-allocator.d.ts.map

package/dist/systems/skin-palette-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin-palette-allocator.d.ts","sourceRoot":"","sources":["../../src/systems/skin-palette-allocator.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAO7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAmB7D,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACpD;;;;;;;;OAQG;IACH,iBAAiB,CACf,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,SAAS,YAAY,EAAE,EAC7B,WAAW,EAAE,SAAS,IAAI,EAAE,GAC3B,IAAI,CAAC;IACR;;;;OAIG;IACH,aAAa,IAAI,IAAI,CAAC;CACvB;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,SAAS,EACjB,cAAc,EAAE,MAAM,EACtB,gBAAgB,UAAO,GACtB,oBAAoB,CA4HtB"}

package/dist/systems/skin-palette-types.d.ts

@@ -0,0 +1,14 @@
+import type { Buffer } from '@forgeax/engine-rhi';
+/**
+ * Per-draw palette slice metadata shared by the extract producer and the
+ * palette allocator. The slice carries the buffer identity so storage and
+ * uniform fallback paths converge at the record binding owner.
+ */
+export interface SkinPaletteSlice {
+    readonly jointCount: number;
+    /** Byte offset into buffer; uniform fallback slices always use zero. */
+    readonly byteOffset: number;
+    /** GPU buffer containing the slice's joint matrices. */
+    readonly buffer: Buffer;
+}
+//# sourceMappingURL=skin-palette-types.d.ts.map

package/dist/systems/skin-palette-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skin-palette-types.d.ts","sourceRoot":"","sources":["../../src/systems/skin-palette-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/dist/systems/transparent-sort-config.d.ts

@@ -0,0 +1,112 @@
+import type { World } from '@forgeax/engine-ecs';
+import { ResourceInvalidValueError } from '@forgeax/engine-ecs/projection';
+import { type Result } from '@forgeax/engine-types';
+/**
+ * Transparent-bucket sort configuration (plain-data POD). Lives as a
+ * world-level resource keyed by `TRANSPARENT_SORT_CONFIG_KEY`.
+ *
+ * Fields:
+ *   - `mode \u2208 {0, 1, 2, 3}` selects the sort formula
+ *     (`TRANSPARENT_SORT_MODE_LAYER_Z` / `_LAYER_Y` / `_LAYER_YZ` / `_DISTANCE`).
+ *   - `yzAlpha` (mode=2 only) blends Y-axis into Z-axis: 1.0 weights
+ *     posZ equally with `posY - pivot.y * size.y` (Don't-Starve style),
+ *     0.5 weights posZ at half (isometric). mode=0 / mode=1 ignore the
+ *     field (documented charter P3 legal-default boundary).
+ */
+export interface TransparentSortConfig {
+    readonly mode: number;
+    readonly yzAlpha: number;
+}
+/** Extract-stage POD consumed by the transparent-sort owner. */
+export interface TransparentEntry {
+    readonly entityIndex: number;
+    readonly materialHandle: number;
+    readonly layer: number;
+    readonly posX: number;
+    readonly posY: number;
+    readonly posZ: number;
+    readonly pivotY: number;
+    readonly sizeY: number;
+    readonly sortKey?: number | undefined;
+    readonly renderableIndex?: number | undefined;
+}
+/** World resource key for `TransparentSortConfig` KV entry. */
+export declare const TRANSPARENT_SORT_CONFIG_KEY: "TransparentSortConfig";
+/** horizontal / side-scroller: sortValue = posZ. */
+export declare const TRANSPARENT_SORT_MODE_LAYER_Z = 0;
+/** top-down / JRPG: sortValue = -(posY - pivot.y * size.y) (foot pivot Y-sort). */
+export declare const TRANSPARENT_SORT_MODE_LAYER_Y = 1;
+/** Don't-Starve / isometric: sortValue = (posY - pivot.y * size.y) + yzAlpha * posZ. */
+export declare const TRANSPARENT_SORT_MODE_LAYER_YZ = 2;
+/** 3D distance: sortValue = -(dist^2) to cameraPos, back-to-front (far first). */
+export declare const TRANSPARENT_SORT_MODE_DISTANCE = 3;
+/** Grouped authoring values and the single configuration operation. */
+export declare const TransparentSort: Readonly<{
+    readonly layerZ: 0;
+    readonly layerY: 1;
+    readonly layerYZ: 2;
+    readonly distance: 3;
+    readonly configure: typeof setTransparentSortConfig;
+}>;
+/**
+ * Read the world's `TransparentSortConfig` resource.
+ *
+ * @fallback KV missing returns `{ mode: 0, yzAlpha: 1.0 }`
+ * (`TRANSPARENT_SORT_MODE_LAYER_Z`, horizontal-z safe default).
+ * NO warn, NO throw — KV missing is a legal state (not an error state),
+ * mirroring how a sprite-free scene is a legal state for the renderer
+ * even though render-system has a transparent bucket. plan-strategy D-2:
+ * `hasResource` guard precedes the read so this helper never trips
+ * `ResourceNotFoundError` from `world.getResource`.
+ *
+ * @example
+ *   const cfg = getTransparentSortConfig(world);
+ *   // cfg.mode === 0, cfg.yzAlpha === 1.0 when no resource inserted.
+ *
+ * @example
+ *   world.insertResource(TRANSPARENT_SORT_CONFIG_KEY,
+ *     { mode: TRANSPARENT_SORT_MODE_LAYER_Y, yzAlpha: 1.0 });
+ *   const cfg = getTransparentSortConfig(world);
+ *   // cfg.mode === 1, cfg.yzAlpha === 1.0 (yzAlpha ignored by mode=1).
+ */
+export declare function getTransparentSortConfig(world: World): TransparentSortConfig;
+/**
+ * Write the world's `TransparentSortConfig` resource, validating `mode`.
+ *
+ * Returns `Result<void, ResourceInvalidValueError>`:
+ *
+ *   - `ok` — mode is in `{0, 1, 2, 3}`; the resource is inserted /
+ *     overwritten via `world.insertResource`.
+ *   - `err` — mode is out of range; the resource is NOT mutated;
+ *     `err.error` is a `ResourceInvalidValueError` instance carrying:
+ *       `.code === 'resource-invalid-value'`
+ *       `.expected === 'mode \u2208 {0, 1, 2, 3}'`
+ *       `.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'`
+ *       `.detail.receivedMode === <the rejected mode>`
+ *
+ * @fallback mode out-of-range is NEVER silently coerced to mode=0 —
+ * `Result.err` is the only fail-mode (charter P3 structured failure).
+ * AI users read `.code / .expected / .hint / .detail` properties to
+ * self-repair, NOT the human-readable `.message` string.
+ *
+ * @fallback yzAlpha range is intentionally not validated; mode=0 / mode=1
+ * ignore the field, mode=2 reads it. The silent-ignore is the
+ * documented charter P3 "legal default" boundary (plan-strategy D-4 +
+ * AC-18 path (3) carve-out).
+ *
+ * @example success path:
+ *   const r = setTransparentSortConfig(world,
+ *     { mode: TRANSPARENT_SORT_MODE_LAYER_YZ, yzAlpha: 0.5 });
+ *   if (!r.ok) return r;
+ *
+ * @example failure path:
+ *   const r = setTransparentSortConfig(world, { mode: 99, yzAlpha: 1.0 });
+ *   if (!r.ok) {
+ *     // r.error.code === 'resource-invalid-value'
+ *     // r.error.expected === 'mode \u2208 {0, 1, 2, 3}'
+ *     // r.error.hint === '0=layer-z, 1=layer-y, 2=layer-yz, 3=distance'
+ *     // r.error.detail.receivedMode === 99
+ *   }
+ */
+export declare function setTransparentSortConfig(world: World, cfg: TransparentSortConfig): Result<void, ResourceInvalidValueError>;
+//# sourceMappingURL=transparent-sort-config.d.ts.map

package/dist/systems/transparent-sort-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transparent-sort-config.d.ts","sourceRoot":"","sources":["../../src/systems/transparent-sort-config.ts"],"names":[],"mappings":"AA0DA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAM7D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED,+DAA+D;AAC/D,eAAO,MAAM,2BAA2B,EAAG,uBAAgC,CAAC;AAE5E,oDAAoD;AACpD,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,mFAAmF;AACnF,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C,wFAAwF;AACxF,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,uEAAuE;AACvE,eAAO,MAAM,eAAe;;;;;;EAMjB,CAAC;AA8BZ;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,qBAAqB,CAK5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,qBAAqB,GACzB,MAAM,CAAC,IAAI,EAAE,yBAAyB,CAAC,CAczC"}

package/dist/tilemap-chunk-extract-system.d.ts

@@ -0,0 +1,143 @@
+import { type TilesetAtlasLookup } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import { type box3 } from '@forgeax/engine-math';
+import { type Handle } from '@forgeax/engine-types';
+import { type SortScope } from './components';
+/**
+ * Flush both material caches. Useful in test harnesses + after a
+ * TilesetAsset reload.
+ */
+export declare function resetTilemapChunkExtractCache(): void;
+/**
+ * Flush the per-cell streaming caches. Useful in test harnesses + when
+ * the World is re-created.
+ *
+ * Signature preserved (AC-08 hard constraint) after tweak-20260714 M3
+ * retired the terrain-side tracker Map + first-frame heuristic Set:
+ * terrain layers now derive their "already-built" state from
+ * `Children.entities` on the TileLayer (mirror of ChildOf, engine-
+ * maintained), so the tracker only needs to clear the 3 streaming
+ * caches (plan-strategy §2 D-3 + §2 D-5).
+ */
+export declare function resetTilemapDerivedEntityTracker(): void;
+/**
+ * @internal Test-only helper for AC-11 (tweak-20260714 M4). Returns the
+ * union of `layerKey`s currently referenced by the three per-cell
+ * streaming caches. Post-diff-cleanup, an evicted layerKey MUST NOT
+ * appear here; a slot subsequently reused for a fresh TileLayer sees
+ * empty caches and rebuilds from zero (plan-strategy §2 D-4).
+ *
+ * Parsing the per-World `chunkEntities` key format `${entity}:${chunkIdx}`
+ * is intentional so callers observe cleanup on all three maps without
+ * depending on the invariant `activeSet ↔ chunkEntities
+ * keys are paired` — the test then also cross-checks that invariant.
+ */
+export declare function _peekPerCellStreamingLayerKeys(world: World): readonly number[];
+/**
+ * Compute the per-layer / per-chunk packed value carried in `Layer.value`
+ * on derived entities. `sortScope` is the closed string union from
+ * `TileLayer.sortScope`:
+ *   - `'layer'`    (default): `(layerOrder << 20) | (chunkIndex & 0xFFFFF)` —
+ *                  terrain semantics, layerOrder dominates with chunkIndex
+ *                  tiebreak within the layer.
+ *   - `'per-cell'`: returns `(layerOrder << 20)` (chunkIndex folded to 0)
+ *                  so every derived entity in the layer shares one
+ *                  Layer.value and can Y-interleave with sprite entities
+ *                  carrying the same value (e.g. a player sprite riding
+ *                  `SPRITE_LAYER_VALUE = layerOrder << 20`).
+ *
+ * Round-2 rename (D-V-3): the third arg was `ySort: boolean` before the
+ * sortScope union landed; it is now the closed `SortScope` union with
+ * default `'layer'`. The 0x200000 / chunked-bits semantics for the two
+ * arms are preserved exactly so existing pixel-parity baselines stay
+ * stable (only the AI-user surface widens to a self-documenting literal).
+ */
+export declare function encodeTilemapLayerValue(layerOrder: number, chunkIndex: number, sortScope?: SortScope): number;
+interface DerivedSpawnSpec {
+    readonly cellX: number;
+    readonly cellY: number;
+    readonly tileId: number;
+    readonly packedTile: number;
+    readonly materialHandle: Handle<'MaterialAsset', 'shared'>;
+    readonly chunkIndex: number;
+    readonly widthCells: number;
+    readonly heightCells: number;
+    readonly pivotX: number;
+    readonly pivotY: number;
+    readonly atlasIndex: number;
+    readonly regionIndex: number;
+}
+/**
+ * Compute the post-flip "effective pivot Y" for a tilemap tile entry.
+ *
+ * Mirrors the D-2 first-line composition used by `spawnDerivedRenderEntities`:
+ *
+ *   basePivotForY = flipDiagonal ? pivotX : pivotY
+ *   effectivePivotY = flipV ? (1 - basePivotForY) : basePivotForY
+ *
+ * Exported so the render-system-extract sprite-bucket sort key path can
+ * reproduce the *same* per-entity pivot value that landed on
+ * `Transform.posY` -- otherwise the foot-Y formula
+ * `posY - effectivePivotY * |scaleY|` would drift on flipped tiles
+ * (charter P4 single-source pivot SSOT; plan-strategy §D-1 + §D-2 +
+ * requirements §AC-12 / §AC-13).
+ */
+export declare function effectivePivotYForTilemapFlip(pivotY: number, pivotX: number, flipV: boolean, flipDiagonal: boolean): number;
+/**
+ * bug-20260703-tilemap-chunk-stale-frustum-and-cull-overhang (D2): compute
+ * the world-space AABB that tightly encloses every tile inside a chunk
+ * after post-TRS placement (`computeTileTrs` applied per spec, SSOT shared
+ * with the per-cell spawn path and SpriteInstances batched path). This is
+ * the SSOT the streaming visibility test uses to decide whether a chunk's
+ * tiles could still be visible; using it instead of the tile-aligned grid
+ * box makes multi-cell / non-central-pivot overhang round-trip correctly,
+ * so an overhanging tile no longer disappears when its anchor chunk goes
+ * off-screen (plan-strategy §2 D-2).
+ *
+ * Empty spec list -> inverted `Number.MAX_VALUE` sentinel (plan-strategy
+ * §2 D-4). `bucketTileLayer` filters empty cells before the byChunk map
+ * is built, so this branch should never trigger in production; the
+ * sentinel is an explicit "no visible pixels" value that
+ * `frustum.intersectsBox` rejects immediately, avoiding a silent NaN
+ * propagation path (charter P3 explicit failure).
+ *
+ * Note: `frustum.intersectsBox` picks a p-vertex per plane and computes
+ * `dot(normal, p) + d`. When normal has a zero component, multiplying by
+ * `Infinity` yields `NaN` (`NaN < 0 === false` -> false positive
+ * intersection). The sentinel uses finite `Number.MAX_VALUE` on the axes
+ * we want inverted so `0 * MAX_VALUE === 0` and the non-zero-normal axis
+ * dominates, driving `dot` to `-Infinity` and correctly rejecting.
+ *
+ * Z is expanded to +/- 1 so flat sprite geometry (`pos_local.z === 0`) is
+ * never degenerate against the frustum's near/far planes.
+ *
+ * @internal exported for M2 overhang / empty-chunk sentinel unit tests
+ * (plan-strategy §5.3); not part of the AI user surface.
+ */
+export declare function computeChunkStreamBounds(tilemap: {
+    tileSize: ArrayLike<number>;
+}, specs: readonly DerivedSpawnSpec[]): box3.Box3Like;
+/**
+ * Walk every TileLayer ChildOf-ing a Tilemap, extract its non-zero cells
+ * into derived render entities. A Renderer attaches this system to FrameEnd;
+ * World's final publication then resolves newly-created Transform.world values before the
+ * read-only render walk begins.
+ *
+ * Two paths based on `TileLayer.sortScope`:
+ *
+ *   `'layer'` (terrain, default):
+ *     Batched SpriteInstances path — spawned once, reused until dirty. Each
+ *     (chunk, atlas) pair becomes one SpriteInstances entity whose Transform
+ *     covers the chunk footprint, so the frustum culler rejects off-screen
+ *     chunks at entity granularity.
+ *
+ *   `'per-cell'` (object layers):
+ *     Chunk-streaming path — specs are bucketed by chunkIndex once (rebuilt
+ *     on dirty) and the live entity set is updated every frame to match the
+ *     camera frustum. Only chunks whose world AABB intersects the frustum
+ *     have ECS entities alive, keeping `extractFrame` iteration proportional
+ *     to visible tile count rather than total map tile count.
+ */
+export declare function tilemapChunkExtractSystem(world: World, lookup?: (guid: string) => TilesetAtlasLookup): void;
+export {};
+//# sourceMappingURL=tilemap-chunk-extract-system.d.ts.map

package/dist/tilemap-chunk-extract-system.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tilemap-chunk-extract-system.d.ts","sourceRoot":"","sources":["../src/tilemap-chunk-extract-system.ts"],"names":[],"mappings":"AAmDA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAgB,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,EAAE,KAAK,IAAI,EAAiB,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EACL,KAAK,MAAM,EAOZ,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAOL,KAAK,SAAS,EAIf,MAAM,cAAc,CAAC;AA8FtB;;;GAGG;AACH,wBAAgB,6BAA6B,IAAI,IAAI,CAGpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,MAAM,EAAE,CAgB9E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,SAAmB,GAC7B,MAAM,CAGR;AAqMD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAIxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,OAAO,GACpB,MAAM,CAGR;AAmbD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,CAAC,CAAA;CAAE,EACxC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GACjC,IAAI,CAAC,QAAQ,CAmBf;AAiGD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,kBAAoC,GAC7D,IAAI,CAyLN"}

package/dist/typed-render-graph-primitives.d.ts

@@ -0,0 +1,57 @@
+import type { GraphAccess, RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { type PassKind, type PassSelector, type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineGpuDrivenProjection } from './render-pipeline';
+import { type RenderPipelineTarget } from './render-pipeline';
+export declare function typedFrameClearColor(frame: RenderPipelineFrame): GPUColor;
+export declare function addTypedSkyboxPass(graph: RenderGraphBuilder<RenderPipelineFrame>, color: RenderPipelineTarget): Result<void, RenderGraphError>;
+export interface TypedScenePassOptions {
+    readonly name: string;
+    readonly color: RenderPipelineTarget;
+    readonly depth: RenderPipelineTarget;
+    readonly resolve?: RenderPipelineTarget | undefined;
+    readonly sampled?: readonly RenderPipelineTarget[] | undefined;
+    readonly directionalShadow?: RenderPipelineTarget | undefined;
+    readonly spotShadow?: RenderPipelineTarget | undefined;
+    readonly ssao?: RenderPipelineTarget | undefined;
+    readonly selector: PassSelector;
+    readonly passKind?: PassKind | undefined;
+    readonly colorTargets?: readonly RenderPipelineTarget[] | undefined;
+    readonly clearColor?: readonly [number, number, number, number] | undefined;
+    readonly colorLoadOp?: GPULoadOp | undefined;
+    readonly depthLoadOp?: GPULoadOp | undefined;
+    readonly extraAccesses?: readonly GraphAccess[] | undefined;
+    readonly gpuDriven?: RenderPipelineGpuDrivenProjection | undefined;
+}
+export declare function addTypedScenePass(graph: RenderGraphBuilder<RenderPipelineFrame>, options: TypedScenePassOptions): Result<void, RenderGraphError>;
+export declare function addTypedFrameObservationPass(graph: RenderGraphBuilder<RenderPipelineFrame>, target: RenderPipelineTarget, pipelineId: 'forgeax::standard'): Result<void, RenderGraphError>;
+export interface TypedBloomTargets {
+    readonly scene: RenderPipelineTarget;
+    readonly composited: RenderPipelineTarget;
+    readonly bright: RenderPipelineTarget;
+    readonly blurH: RenderPipelineTarget;
+    readonly blurV: RenderPipelineTarget;
+}
+export declare function addTypedBloomPasses(graph: RenderGraphBuilder<RenderPipelineFrame>, targets: TypedBloomTargets): Result<void, RenderGraphError>;
+export interface TypedSsaoTargets {
+    readonly normal: RenderPipelineTarget;
+    readonly depth: RenderPipelineTarget;
+    readonly raw: RenderPipelineTarget;
+    readonly blurred: RenderPipelineTarget;
+}
+export declare function addTypedSsaoPasses(graph: RenderGraphBuilder<RenderPipelineFrame>, targets: TypedSsaoTargets): Result<void, RenderGraphError>;
+export interface TypedFullscreenPassOptions {
+    readonly name: string;
+    readonly shader: string;
+    readonly input: RenderPipelineTarget;
+    readonly output: RenderPipelineTarget;
+    readonly outputOnly?: boolean | undefined;
+    readonly rawSwapchainOutput?: boolean | undefined;
+    readonly depth?: RenderPipelineTarget | undefined;
+}
+export declare function addTypedFullscreenPass(graph: RenderGraphBuilder<RenderPipelineFrame>, options: TypedFullscreenPassOptions): Result<void, RenderGraphError>;
+export declare function addTypedCompositePostEffects(graph: RenderGraphBuilder<RenderPipelineFrame>, effects: readonly string[], input: RenderPipelineTarget, output: RenderPipelineTarget, depth: RenderPipelineTarget, size: {
+    readonly width: number;
+    readonly height: number;
+}): Result<void, RenderGraphError>;
+export declare function addTypedTonemapPass(graph: RenderGraphBuilder<RenderPipelineFrame>, input: RenderPipelineTarget, output: RenderPipelineTarget, outputOnly?: boolean): Result<void, RenderGraphError>;
+//# sourceMappingURL=typed-render-graph-primitives.d.ts.map

package/dist/typed-render-graph-primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-render-graph-primitives.d.ts","sourceRoot":"","sources":["../src/typed-render-graph-primitives.ts"],"names":[],"mappings":"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"}

package/dist/typed-shadow-passes.d.ts

@@ -0,0 +1,11 @@
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineTopology } from './render-pipeline';
+import { type RenderPipelineTarget } from './render-pipeline';
+export interface TypedShadowTargets {
+    readonly directional: RenderPipelineTarget;
+    readonly spot: RenderPipelineTarget;
+    readonly point?: RenderPipelineTarget | undefined;
+}
+export declare function addTypedShadowPasses(graph: RenderGraphBuilder<RenderPipelineFrame>, topology: RenderPipelineTopology): Result<TypedShadowTargets, RenderGraphError>;
+//# sourceMappingURL=typed-shadow-passes.d.ts.map

package/dist/typed-shadow-passes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typed-shadow-passes.d.ts","sourceRoot":"","sources":["../src/typed-shadow-passes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACzF,OAAO,EAAM,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AASxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAA8B,KAAK,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE1F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACnD;AAwBD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,QAAQ,EAAE,sBAAsB,GAC/B,MAAM,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAwH9C"}

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@forgeax/engine-render",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "description": "Canonical ECS render schemas and renderer boundary.",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./authoring": {
+      "types": "./dist/authoring.d.ts",
+      "import": "./dist/authoring.mjs"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.mjs"
+    },
+    "./package.json": "./package.json",
+    "./internal/construct-renderer": {
+      "types": "./dist/construct-renderer.d.ts",
+      "import": "./dist/construct-renderer.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-assets-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-audio-webaudio": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-codec": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-geometry": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-graphics-extras": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-plugin": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-profiler": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-render-graph": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-scene": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-shader": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-skinning": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "devDependencies": {
+    "@forgeax/engine-rhi-null": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-rhi-webgpu": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip",
+        "expected": 10000
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "render package has no host loop"
+      },
+      "bench": {
+        "enabled": true,
+        "reportPath": "bench-result.json",
+        "suite": "@forgeax/engine-render",
+        "baseline": {
+          "source": "inline",
+          "threshold": 15000000
+        }
+      },
+      "gate": {
+        "enabled": true,
+        "reason": "render boundary checks"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "bench": "vitest bench --run",
+    "bench:json": "FORGEAX_BENCH=fast vitest bench --run --outputJson bench-result.json"
+  }
+}

package/src/__tests__/authoring-path.unit.test.ts

@@ -0,0 +1,23 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { setActiveCamera } from '../authoring';
+import { Camera, perspective } from '../components/camera';
+import { getActiveCamera } from '../systems/active-camera';
+
+describe('authoring path', () => {
+  it('does not require authoring tokens in the render base surface', () => {
+    expect(true).toBe(true);
+  });
+
+  it('uses a transparent clear alpha by default and exposes opaque as an opt-in field', () => {
+    expect(Camera.fields.clearColor.default).toEqual(new Float32Array([0, 0, 0, 0]));
+    expect(perspective({ fov: 1, aspect: 1 }).clearColor).toEqual(new Float32Array([0, 0, 0, 0]));
+    expect({ alphaMode: 'opaque' }).not.toEqual({ alphaMode: 'premultiplied' });
+  });
+
+  it('owns active-camera authoring without requiring the internal entrypoint', () => {
+    const world = new World();
+    setActiveCamera(world, 42);
+    expect(getActiveCamera(world)).toEqual({ entity: 42 });
+  });
+});

package/src/__tests__/backend-selection-rhi-capture.test-d.ts

@@ -0,0 +1,21 @@
+import type { RhiInstance } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import type { RhiBackendInstrumentation, RhiBackendPack } from '../assembly/backend-contract';
+
+declare const instrumentation: RhiBackendInstrumentation;
+
+const pack: RhiBackendPack = {
+  rhi: rhi as RhiBackendPack['rhi'],
+  instrumentation,
+};
+
+const preserved = pack.instrumentation;
+const instance: RhiInstance = pack.rhi;
+void preserved;
+void instance;
+
+// The instrumentation seam is the only capture hook exposed by the pack.
+// @ts-expect-error pseudo-private raw-device escape hatches are not part of the pack.
+pack._realDevice;
+// @ts-expect-error capture capabilities are attached by App, not backend selection.
+pack.rhiCapture;