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

package/dist/cluster-binner.d.ts

@@ -0,0 +1,152 @@
+import { type Mat4, type Vec3 } from '@forgeax/engine-math';
+import { type Result } from '@forgeax/engine-rhi';
+export type ClusterBinErrorCode = 'index-overflow';
+export interface ClusterBinError {
+    readonly code: ClusterBinErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: IndexOverflowDetail;
+}
+export interface IndexOverflowDetail {
+    readonly actual: number;
+    readonly capacity: number;
+}
+/**
+ * View-space NDC axis-aligned bounding box.
+ * `min` and `max` are NDC coordinates clamped to [-1, 1] for XY;
+ * Z may extend to projection-space depth values.
+ */
+export interface ClusterAabb {
+    readonly min: Vec3;
+    readonly max: Vec3;
+}
+/** Unsigned integer 3D cluster cell coordinate. */
+export interface Uvec3 {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** Cluster cell range in the unsigned grid. */
+export interface ClusterBounds {
+    readonly min: Uvec3;
+    readonly max: Uvec3;
+}
+type MutableClusterBounds = {
+    min: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};
+/**
+ * Reusable typed scratch for cluster-major output. The binner must emit one
+ * contiguous light-index run per cluster, so counts and cursors replace the
+ * per-frame `number[][]` staging lists without changing output order.
+ */
+export interface ClusterBinScratch {
+    clusterCounts: Uint32Array;
+    clusterCursors: Uint32Array;
+    lightBounds: Int32Array;
+    clusterDeltas: Int32Array;
+    aabbOutput: ClusterAabb;
+    boundsOutput: MutableClusterBounds;
+}
+/**
+ * Selects the membership materialization owner after bounds and occupancy are
+ * derived. The default keeps the existing CPU list writer; the WebGPU
+ * producer uses the same CPU-owned scratch and leaves the ordered list to a
+ * later compute pass.
+ */
+export interface ClusterBinOptions {
+    readonly writeMembership?: boolean;
+}
+export type ClusterBinProfilePhase = 'light-bounds-and-occupancy' | 'light-bounds-and-occupancy/light-aabb' | 'light-bounds-and-occupancy/cluster-occupancy' | 'cluster-reserve' | 'light-index-write' | 'light-index-write/bounds-read' | 'light-index-write/cluster-write';
+export type ClusterBinProfileRunner = <T>(phase: ClusterBinProfilePhase, action: () => T) => T;
+export declare function createClusterBinScratch(): ClusterBinScratch;
+/**
+ * Compute a culling radius for a punctual light.
+ *
+ * If `range` is finite, returns it verbatim (D-8 sphere proxy).
+ * If `range === +Infinity`, derives a finite radius from the distance at which
+ * the light's perceptible contribution drops below `threshold`.
+ *
+ * Formula: `sqrt(intensity / threshold)` gives the distance at which attenuation
+ * = threshold (assuming E=1/r^2 falloff for point lights).
+ * Cap to a conservative 1000 units to prevent overly large bounds.
+ */
+export declare function deriveCullingRadius(range: number, intensity: number, threshold?: number): number;
+/**
+ * Map view-space z (negative, camera-forward) to a cluster Z slice index.
+ *
+ * Implements the idTech6 inverse log-z formula (research §2):
+ *   slice = floor(log(-view_z / near) / log(far / near) * gridZ)
+ *
+ * Clamped to [0, gridZ - 1].
+ */
+export declare function viewZToZSlice(viewZ: number, gridZ: number, near: number, far: number): number;
+/**
+ * Compute view-space NDC AABB for a sphere (light culling proxy).
+ *
+ * Ported from Bevy `cluster_space_object_aabb` (cluster.wgsl lines 75-140).
+ *
+ * Steps:
+ *   1. Transform sphere center to view space via view matrix.
+ *   2. Expand by radius to get view-AABB corners.
+ *   3. Project 4 key corners to NDC.
+ *   4. Clamp to [-1, 1] for XY ; Z is kept as projected depth.
+ */
+export declare function clusterSpaceObjectAabb(center: Vec3, radius: number, view: Mat4, proj: Mat4, output?: ClusterAabb): ClusterAabb;
+/**
+ * Map an NDC point to its cluster cell index (XY + Z).
+ *
+ * XY: floor((ndc.xy * 0.5 + 0.5) * gridXy) clamped to [0, gridXy - 1].
+ * Z: delegated to view_z_to_z_slice with the given view-space z.
+ */
+export declare function ndcPositionToCluster(ndc: Vec3, viewZ: number, gridX: number, gridY: number, gridZ: number, near: number, far: number): Uvec3;
+/**
+ * Convert an NDC AABB to a range of cluster cell indices.
+ *
+ * Computes cluster indices for AABB min and max, then clamps and
+ * orders the result so `min <= max` in each axis.
+ *
+ * If the sphere is entirely behind the camera, returns min > max
+ * in at least one axis (cull signal).
+ */
+export declare function calculateSphereClusterBounds(aabb: ClusterAabb, gridX: number, gridY: number, gridZ: number, near: number, far: number, output?: MutableClusterBounds): ClusterBounds;
+/**
+ * Main entry point: assign punctual lights to cluster cells.
+ *
+ * Light-major loop: for each light, compute its sphere-AABB and iterate the
+ * intersecting cluster cells, appending the light index to the light_index_list
+ * and updating cluster_grid offsets.
+ *
+ * @param lights — array of { position: Vec3, range: number }
+ * @param view — view matrix (column-major 16 floats)
+ * @param proj — projection matrix (column-major 16 floats)
+ * @param grid — cluster grid dimensions { x, y, z }
+ * @param near — near plane distance
+ * @param far — far plane distance
+ * @param clusterGrid — caller-owned Uint32Array, length = grid.x * grid.y * grid.z * 2.
+ *   Format: [offset, count] pairs. offset = start index in lightIndexList; count = number of lights.
+ * @param lightIndexList — caller-owned Uint32Array for light index storage.
+ * @param capacity — max entries in lightIndexList (hard cap, typically 65536).
+ * @param scratch — optional per-render-system typed scratch reused across frames.
+ *
+ * @returns `ok(written light-index entry count)` on success; `err(ClusterBinError)` with code
+ *   'index-overflow' on overflow. The count lets the upload owner avoid copying unused capacity.
+ */
+export declare function bin(lights: ReadonlyArray<{
+    readonly position: Vec3;
+    readonly range: number;
+}>, view: Mat4, proj: Mat4, grid: {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}, near: number, far: number, clusterGrid: Uint32Array, lightIndexList: Uint32Array, capacity: number, scratch?: ClusterBinScratch, profile?: ClusterBinProfileRunner, options?: ClusterBinOptions): Result<number, ClusterBinError>;
+export {};
+//# sourceMappingURL=cluster-binner.d.ts.map

package/dist/cluster-binner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-binner.d.ts","sourceRoot":"","sources":["../src/cluster-binner.ts"],"names":[],"mappings":"AA2BA,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,IAAI,EAAQ,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAI3D,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+CAA+C;AAC/C,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;IACpB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC;CACrB;AAED,KAAK,oBAAoB,GAAG;IAC1B,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1C,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,WAAW,CAAC;IAC3B,cAAc,EAAE,WAAW,CAAC;IAC5B,WAAW,EAAE,UAAU,CAAC;IACxB,aAAa,EAAE,UAAU,CAAC;IAC1B,UAAU,EAAE,WAAW,CAAC;IACxB,YAAY,EAAE,oBAAoB,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,MAAM,MAAM,sBAAsB,GAC9B,4BAA4B,GAC5B,uCAAuC,GACvC,8CAA8C,GAC9C,iBAAiB,GACjB,mBAAmB,GACnB,+BAA+B,GAC/B,iCAAiC,CAAC;AAEtC,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,sBAAsB,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;AAU/F,wBAAgB,uBAAuB,IAAI,iBAAiB,CAe3D;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,SAAQ,GAAG,MAAM,CAM/F;AAID;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAS7F;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,IAAI,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,MAAM,CAAC,EAAE,WAAW,GACnB,WAAW,CA0Jb;AAuCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,IAAI,EACT,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,KAAK,CAeP;AAID;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,oBAAoB,GAC5B,aAAa,CAoBf;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,GAAG,CACjB,MAAM,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1E,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,IAAI,EAAE;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAA;CAAE,EACpE,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,WAAW,EAC3B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE,uBAAuB,EACjC,OAAO,GAAE,iBAAsB,GAC9B,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAqLjC"}

package/dist/components/__tests__/points-lines-admission.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=points-lines-admission.unit.test.d.ts.map

package/dist/components/__tests__/points-lines-admission.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"points-lines-admission.unit.test.d.ts","sourceRoot":"","sources":["../../../src/components/__tests__/points-lines-admission.unit.test.ts"],"names":[],"mappings":""}

package/dist/components/__tests__/points-lines-schema.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=points-lines-schema.unit.test.d.ts.map

package/dist/components/__tests__/points-lines-schema.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"points-lines-schema.unit.test.d.ts","sourceRoot":"","sources":["../../../src/components/__tests__/points-lines-schema.unit.test.ts"],"names":[],"mappings":""}

package/dist/components/__tests__/schema-contract.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-contract.unit.test.d.ts.map

package/dist/components/__tests__/schema-contract.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-contract.unit.test.d.ts","sourceRoot":"","sources":["../../../src/components/__tests__/schema-contract.unit.test.ts"],"names":[],"mappings":""}

package/dist/components/__tests__/schema-parity.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-parity.unit.test.d.ts.map

package/dist/components/__tests__/schema-parity.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-parity.unit.test.d.ts","sourceRoot":"","sources":["../../../src/components/__tests__/schema-parity.unit.test.ts"],"names":[],"mappings":""}

package/dist/components/__tests__/visibility-schema.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=visibility-schema.unit.test.d.ts.map

package/dist/components/__tests__/visibility-schema.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visibility-schema.unit.test.d.ts","sourceRoot":"","sources":["../../../src/components/__tests__/visibility-schema.unit.test.ts"],"names":[],"mappings":""}

package/dist/components/camera.d.ts

@@ -0,0 +1,311 @@
+import { type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+/**
+ * Projection discriminator literal union (AC-16 narrowing surface).
+ * Exposed for consumer code that maps `camera.projection` numeric values back
+ * to a switch-able string literal (e.g. RenderSystem dispatch / inspector
+ * snapshot rendering).
+ */
+export type CameraProjection = 'perspective' | 'orthographic';
+/** Numeric encoding of perspective projection (schema value for `projection`). */
+export declare const CAMERA_PROJECTION_PERSPECTIVE = 0;
+/** Numeric encoding of orthographic projection (schema value for `projection`). */
+export declare const CAMERA_PROJECTION_ORTHOGRAPHIC = 1;
+/**
+ * Map a `camera.projection` numeric value to the closed `CameraProjection`
+ * string-literal union. Values other than 0 / 1 fall back to `'perspective'`
+ * (defensive for defaulted / uninitialised entities; charter proposition 4
+ * no silent exception).
+ */
+export declare function cameraProjectionFromF32(value: number): CameraProjection;
+/**
+ * Tone-mapping mode discriminator literal union (AC-01 narrowing surface;
+ * feat-20260519-tonemap-reinhard-mvp / M1).
+ *
+ * Two members for the MVP:
+ *   `'none'`              - default; render-target stays `bgra8unorm-srgb`
+ *                            and the geometry pass writes directly to the
+ *                            swap-chain (zero-overhead opt-out path).
+ *   `'reinhard-extended'` - Forgeax Reinhard 2002 extended (luminance-domain)
+ *                            opt-in;
+ *   `'reinhard'`          - Three r184 per-channel Reinhard opt-in;
+ *                            geometry pass routes through an `rgba16float`
+ *                            HDR target and a fullscreen tonemap pass
+ *                            (`packages/shader/src/tonemap.wgsl`).
+ *
+ * The remaining members mirror the Three r184 public names and formulas.
+ */
+export type Tonemap = 'none' | 'reinhard-extended' | 'reinhard' | 'linear' | 'cineon' | 'aces-filmic' | 'agx' | 'neutral';
+/** Numeric encoding of the no-op tonemap path (schema value for `tonemap`). */
+export declare const TONEMAP_NONE: 0;
+/**
+ * Numeric encoding of the Reinhard-extended tonemap path
+ * (schema value for `tonemap`).
+ */
+export declare const TONEMAP_REINHARD_EXTENDED: 1;
+/** Numeric encoding of the Three r184 per-channel Reinhard path. */
+export declare const TONEMAP_REINHARD: 7;
+/** Numeric encoding of the linear (identity after exposure) tonemap path. */
+export declare const TONEMAP_LINEAR: 2;
+/** Numeric encoding of the Cineon (Kodak log) tonemap path. */
+export declare const TONEMAP_CINEON: 3;
+/** Numeric encoding of the ACES filmic (Narkowicz 2015) tonemap path. */
+export declare const TONEMAP_ACES_FILMIC: 4;
+/** Numeric encoding of the AgX (Troy Sobotka / Blender 3.x) tonemap path. */
+export declare const TONEMAP_AGX: 5;
+/** Numeric encoding of the Khronos PBR neutral tonemap path. */
+export declare const TONEMAP_NEUTRAL: 6;
+/**
+ * Map a `camera.tonemap` numeric value to the closed `Tonemap` string-literal
+ * union. Unknown values fall back to `'none'` for defensive schema decoding.
+ */
+export declare function tonemapFromF32(value: number): Tonemap;
+/**
+ * Inverse of {@link tonemapFromF32}: map the closed `Tonemap` string-literal
+ * union to the u32 mode the tonemap WGSL `params.mode` switch reads. SSOT for
+ * the mode encoding shared by the extract-stage built-in tonemap provider
+ * (feat-20260621 M-A3 / w13: `Camera.tonemap` -> `forgeax::tonemap` 16B data)
+ * and any other consumer. `'none'` maps to 0 (the tonemap pass never dispatches
+ * on the LDR path, so 0 is only ever a placeholder).
+ */
+export declare function tonemapToU32(mode: Tonemap): number;
+/**
+ * Anti-alias mode discriminator literal union
+ * (feat-20260528-fxaa-post-processing / w2;
+ *  feat-20260604-learn-render-4-10-anti-aliasing-msaa adds `'msaa'`).
+ *
+ * Four members:
+ *   `'none'` - default; no anti-aliasing (zero-overhead opt-out path)
+ *   `'fxaa'` - FXAA 3.11 fullscreen post-processing pass (screen-space, shading-aliasing)
+ *   `'msaa'` - 4x hardware multi-sample anti-aliasing (geometry-edge coverage).
+ *              Active on both HDR and LDR-swap-chain paths, so a default Camera
+ *              (`tonemap='none'`) with `antialias='msaa'` is NOT a silent no-op.
+ *   `'taa'`  - temporal anti-aliasing; renderer temporal projection owns its
+ *              jitter and successful-submit history contract.
+ *
+ * MSAA and FXAA are orthogonal: MSAA resolves geometry-edge aliasing, FXAA
+ * resolves shading/high-frequency aliasing. TAA is mutually exclusive with both.
+ */
+export type Antialias = 'none' | 'fxaa' | 'msaa' | 'taa';
+/** Numeric encoding of anti-alias disabled (schema value for `antialias`). */
+export declare const ANTIALIAS_NONE = 0;
+/** Numeric encoding of FXAA anti-aliasing (schema value for `antialias`). */
+export declare const ANTIALIAS_FXAA = 1;
+/** Numeric encoding of MSAA multi-sample anti-aliasing (schema value for `antialias`). */
+export declare const ANTIALIAS_MSAA = 2;
+/** Numeric encoding of temporal anti-aliasing (schema value for `antialias`). */
+export declare const ANTIALIAS_TAA = 3;
+/**
+ * Map a `camera.antialias` numeric value to the closed `Antialias`
+ * string-literal union. Invalid values fail-fast with structured error (charter P3).
+ */
+export declare function antialiasFromF32(value: number): Antialias;
+/**
+ * Bloom enabled discriminator literal union
+ * (feat-20260531-bloom-first-declarative-render-graph-pass / w2).
+ *
+ * Two members:
+ *   `'off'` - default; no bloom post-processing (zero-overhead opt-out path)
+ *   `'on'`  - bloom bright-pass + separable blur + composite pipeline
+ *
+ * Bloom is a discrete enum (0/1) — illegal values fail-fast with RangeError
+ * (charter P3), matching antialiasFromF32 precedent.
+ */
+export type BloomEnabled = 'off' | 'on';
+/** Numeric encoding of bloom disabled (schema value for `bloom`). */
+export declare const BLOOM_DISABLED = 0;
+/** Numeric encoding of bloom enabled (schema value for `bloom`). */
+export declare const BLOOM_ENABLED = 1;
+/**
+ * Map a `camera.bloom` numeric value to the closed `BloomEnabled` string-literal
+ * union. Invalid values fail-fast with structured error (charter P3).
+ */
+export declare function bloomEnabledFromF32(value: number): BloomEnabled;
+/**
+ * Camera projection parameters (perspective + orthographic variants) +
+ * tonemap trio (mode + exposure + whitePoint).
+ *
+ * Camera transform comes from the entity's `Transform` (AI users
+ * spawn camera entities with both components: see example below).
+ *
+ * Defaults (do not auto-apply; spawn explicitly for the perspective quartet):
+ *   fov        = pi/4       - 45-degree vertical field of view
+ *   aspect     = 16/9       - widescreen aspect (use canvas.width / canvas.height)
+ *   near       = 0.1
+ *   far        = 100
+ *   projection = 0          - CAMERA_PROJECTION_PERSPECTIVE (layer-2)
+ *   left       = -1, right  = 1, bottom = -1, top = 1  (orthographic; layer-2)
+ *   tonemap    = 0          - TONEMAP_NONE (layer-2; opt-in path stays
+ *                              0-overhead by default)
+ *   exposure   = 1.0        - layer-2 default for the Reinhard-extended path
+ *                              @applicableWhen tonemap === 'reinhard-extended'
+ *   whitePoint = 4.0        - layer-2 default for the Reinhard-extended path
+ *                              @applicableWhen tonemap === 'reinhard-extended'
+ *                              @minimum 0 (shader floor `max(Y, 1e-5)` keeps
+ *                              the divisor finite even at 0; D-O3)
+ *   clearColor = [0, 0, 0, 0]
+ *                            - feat-20260709 M3 / D-3: clear-color is one
+ *                              inline `array<f32,4>` column (collapsed from the
+ *                              feat-20260608 clearR/G/B/A quartet). Defaults to
+ *                              transparent black; an explicit alpha remains
+ *                              visible through this public field.
+ *
+ * MVP supports a single active camera (the first archetype iteration hit;
+ * N>1 fires 'render-system-multi-camera' + uses first). Multi-viewport is
+ * OOS (see feat-future-multi-viewport). The orthographic path reuses the
+ * same near / far as the perspective path — both variants share the single
+ * Camera archetype (17 scalar f32 columns + one historyVersion u32 column +
+ * the `clearColor` array<f32,4> column + the `autoAspect` bool column).
+ *
+ * @example Perspective camera at (0, 0, 3) looking down -Z (zero-config tonemap):
+ *   world.spawn(
+ *     { component: Transform, data: {
+ *       pos: [0, 0, 3],
+ *       quat: [0, 0, 0, 1],
+ *       scale: [1, 1, 1],
+ *     } },
+ *     { component: Camera, data: {
+ *       fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100,
+ *     } },
+ *   );
+ *   // tonemap defaults to 0 (TONEMAP_NONE) - 0-overhead path.
+ *
+ * @example Opt-in Reinhard-extended tonemap (high-intensity HDR scene):
+ *   world.spawn(
+ *     { component: Transform, data: { ... } },
+ *     { component: Camera, data: {
+ *       fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100,
+ *       tonemap: TONEMAP_REINHARD_EXTENDED,
+ *       exposure: 1.0,
+ *       whitePoint: 4.0,
+ *     } },
+ *   );
+ *
+ * @example Orthographic camera spanning [-10, 10]^2 on the near plane:
+ *   world.spawn(
+ *     { component: Transform, data: {
+ *       pos: [0, 0, 5],
+ *       quat: [0, 0, 0, 1],
+ *       scale: [1, 1, 1],
+ *     } },
+ *     { component: Camera, data: {
+ *       fov: 0, aspect: 1, near: 0.1, far: 100,
+ *       projection: CAMERA_PROJECTION_ORTHOGRAPHIC,
+ *       left: -10, right: 10, bottom: -10, top: 10,
+ *     } },
+ *   );
+ */
+export declare const Camera: import("@forgeax/engine-ecs").Component<"Camera", {
+    readonly fov: "f32";
+    readonly aspect: "f32";
+    readonly near: "f32";
+    readonly far: "f32";
+    readonly projection: "f32";
+    readonly left: "f32";
+    readonly right: "f32";
+    readonly bottom: "f32";
+    readonly top: "f32";
+    readonly tonemap: "f32";
+    readonly exposure: "f32";
+    readonly whitePoint: "f32";
+    readonly antialias: "f32";
+    readonly historyVersion: "u32";
+    readonly bloom: "f32";
+    readonly bloomThreshold: "f32";
+    readonly bloomIntensity: "f32";
+    readonly bloomBlurRadius: "f32";
+    readonly clearColor: "array<f32, 4>";
+    readonly autoAspect: "bool";
+}>;
+type CameraPod = ShapeOf<SchemaOf<typeof Camera>>;
+interface CameraPerspectiveOpts {
+    fov: number;
+    aspect: number;
+    near?: number;
+    far?: number;
+    /**
+     * feat-20260617-host-engine-contract-and-video-cutscene / M3: when true
+     * (the schema default), the aspect-sync sidecar on the createApp(canvas)
+     * path overwrites `aspect` with `canvas.width / canvas.height` every frame.
+     * Omit it for the default-correct behaviour; set `false` to opt out (the
+     * factory then leaves `aspect` under your control -- render-to-texture,
+     * split-screen). Cameras built on the bare `createRenderer` path never
+     * receive aspect-sync regardless of this flag.
+     */
+    autoAspect?: boolean;
+}
+interface CameraOrthographicOpts {
+    left: number;
+    right: number;
+    bottom: number;
+    top: number;
+    near?: number;
+    far?: number;
+}
+/**
+ * Convenience factory: perspective CameraData POD.
+ *
+ * `fov` and `aspect` are required (no sensible universal default).
+ * `near` defaults to 0.1, `far` defaults to 100.
+ * Orthographic quartet defaults to [-1, 1]x[-1, 1]; tonemap defaults to
+ * TONEMAP_NONE (0-overhead path).
+ *
+ * When `autoAspect` is `true` (the default once shipped in M3), the
+ * aspect-sync sidecar on the `createApp(canvas)` path automatically writes
+ * `canvas.width / canvas.height` into `Camera.aspect` every frame. Set
+ * `autoAspect = false` to opt out (render-to-texture, split-screen).
+ * Cameras on the `createRenderer` path do not receive aspect-sync.
+ *
+ * @see {@link https://github.com/Ubpa/forgeax-engine/blob/main/docs/how-to/2026-06-18-host-engine-contract.md | Host-engine contract SSOT}
+ *
+ * @example
+ * ```ts
+ * import { Camera, perspective } from '@forgeax/engine-render';
+ * world.spawn(
+ *   { component: Camera, data: perspective({ fov: Math.PI / 3, aspect: 4 / 3 }) }
+ * ).unwrap();
+ * ```
+ *
+ * @example With explicit near/far:
+ * ```ts
+ * const camData = perspective({ fov: Math.PI / 4, aspect: 16 / 9, near: 0.01, far: 1000 });
+ * world.spawn({ component: Camera, data: camData }).unwrap();
+ * ```
+ *
+ * @example With non-default clear color (default is `[0, 0, 0, 0]`).
+ * `clearColor` is an inline `array<f32,4>` field on `Camera`; spread the
+ * factory then override:
+ * ```ts
+ * world.spawn({
+ *   component: Camera,
+ *   data: { ...perspective({ fov: Math.PI / 3, aspect: 4 / 3 }), clearColor: [0, 1, 0, 1] },
+ * }).unwrap();
+ * ```
+ */
+export declare function perspective(opts: CameraPerspectiveOpts): CameraPod;
+/**
+ * Convenience factory: orthographic CameraData POD.
+ *
+ * All four ortho bounds (`left` / `right` / `bottom` / `top`) are required.
+ * `near` defaults to 0.1, `far` defaults to 100.
+ * Perspective fields get sentinel defaults (fov=0, aspect=1) for column
+ * alignment with the 12-field schema.
+ *
+ * @example
+ * ```ts
+ * import { Camera, orthographic } from '@forgeax/engine-render';
+ * world.spawn(
+ *   { component: Camera, data: orthographic({
+ *     left: -10, right: 10, bottom: -10, top: 10,
+ *   }) }
+ * ).unwrap();
+ * ```
+ *
+ * @example Screen-aligned orthographic for pixel-unit rendering:
+ * ```ts
+ * const camData = orthographic({ left: 0, right: 800, bottom: 600, top: 0 });
+ * world.spawn({ component: Camera, data: camData }).unwrap();
+ * ```
+ */
+export declare function orthographic(opts: CameraOrthographicOpts): CameraPod;
+export {};
+//# sourceMappingURL=camera.d.ts.map

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * Directional light (sun-like infinite light source) with merged shadow
+ * parameters.
+ *
+ * `direction` @semantics outgoing — points FROM light source TO surface
+ * (opposite of Three.js convention; the shader internally negates this
+ * vector to obtain the L vector for BRDF evaluation). `color` is
+ * linear-space rgb in [0, 1] per channel and `intensity` is lux. Exposure is
+ * applied after lighting by the camera output stage; no hidden light
+ * multiplier is applied here.
+ *
+ * castShadow defaults to true — zero-config spawns cast cascaded shadow maps.
+ * Set castShadow: false to opt out (shadow fields are still stored but their
+ * validation is skipped).
+ *
+ * Shadow fields (migrated from DirectionalLightShadow, feat-20260621 M1):
+ *   cascadeCount   ∈ {1,2,3,4}  — number of cascades (default 4)
+ *   splitLambda    ∈ [0,1]      — PSSM split weight (default 0.75)
+ *   cascadeBlend   ∈ [0,0.5]    — blend width between cascades (default 0.2)
+ *   mapSize        >= 1         — shadow map resolution (default 2048)
+ *   depthBias                    — shadow acne bias (default 0.005)
+ *   normalBias                   — shadow acne normal offset (default 0.05)
+ *   shadowDistance > 0           — how far shadows reach in front of the camera,
+ *                                  in world units (default 200). This is the sole
+ *                                  coverage knob: the CSM cascades are PSSM-split
+ *                                  across [camera near, shadowDistance] and each
+ *                                  cascade's orthographic bounds are fit to the
+ *                                  camera frustum slice automatically. The near
+ *                                  end is derived from the active camera's near
+ *                                  plane (no separate near knob — any value other
+ *                                  than the camera near either drops near shadows
+ *                                  or wastes cascade-0 resolution).
+ *   pcfKernelSize  odd >= 1     — PCF kernel width (default 3)
+ *
+ * @example Spawn a single directional light with default shadows:
+ *   world.spawn({ component: DirectionalLight, data: {
+ *     direction: [-0.5, -1, -0.3], // [x, y, z]
+ *     color: [1, 1, 1], // [r, g, b]
+ *     intensity: 1,
+ *   } });
+ *
+ * @example Opt out of shadows:
+ *   world.spawn({ component: DirectionalLight, data: {
+ *     direction: [0, -1, 0], // [x, y, z]
+ *     castShadow: false,
+ *   } });
+ *
+ * @example Explicit shadow config (single-component spawn):
+ *   world.spawn({ component: DirectionalLight, data: {
+ *     direction: [0.2, -0.98, 0], // [x, y, z]
+ *     color: [1, 1, 1], intensity: 1, // color is [r, g, b]
+ *     cascadeCount: 4, splitLambda: 0.75, cascadeBlend: 0.2,
+ *     mapSize: 2048, shadowDistance: 200,
+ *   } });
+ *
+ * @example 0-light scene must use an unlit shader (standard 0 light = physically correct black):
+ *   const world = new World();
+ *   // ... spawn cube + camera, no light ...
+ *   await renderer.ready;
+ *   renderer.draw(world); // standard material renders black; switch to an unlit shader (Materials.unlit(...)) for an unlit display
+ */
+export declare const DirectionalLight: import("@forgeax/engine-ecs").Component<"DirectionalLight", {
+    readonly direction: "array<f32, 3>";
+    readonly color: "array<f32, 3>";
+    readonly intensity: "f32";
+    readonly castShadow: "bool";
+    readonly cascadeCount: "f32";
+    readonly splitLambda: "f32";
+    readonly cascadeBlend: "f32";
+    readonly mapSize: "f32";
+    readonly depthBias: "f32";
+    readonly normalBias: "f32";
+    readonly shadowDistance: "f32";
+    readonly pcfKernelSize: "f32";
+}>;
+//# sourceMappingURL=directional-light.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"directional-light.d.ts","sourceRoot":"","sources":["../../src/components/directional-light.ts"],"names":[],"mappings":"AAkCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;EAwB3B,CAAC"}

package/dist/components/glyph-text.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Glyph text authoring component (world-space MSDF text).
+ *
+ * Spawn an entity with a `GlyphText` and the `glyphTextLayoutSystem`
+ * (auto-wired by `createRenderer` / `createApp`) lays out the glyph quads,
+ * bakes a `MeshAsset`, and attaches `MeshFilter` + `MeshRenderer` on the
+ * next frame (Commands-deferred). Mutating `text` / `fontSize` / `color`
+ * re-bakes the mesh in place (plan-strategy D-1 updateMesh; registry size
+ * unchanged, AC-08).
+ *
+ * @example Spawn a world-space label:
+ *   import { GlyphText } from '@forgeax/engine-render/authoring';
+ *   const font = (await assets.loadByGuid(fontGuid)).unwrap();
+ *   world.spawn({
+ *     component: GlyphText,
+ *     data: { fontHandle: font, text: 'Hello', fontSize: 32,
+ *             color: [1, 1, 1, 1] },
+ *   });
+ */
+export declare const GlyphText: import("@forgeax/engine-ecs").Component<"GlyphText", {
+    readonly fontHandle: "shared<FontAsset>";
+    readonly text: "string";
+    readonly fontSize: "f32";
+    readonly color: "array<f32, 4>";
+}>;
+//# sourceMappingURL=glyph-text.d.ts.map

package/dist/components/glyph-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyph-text.d.ts","sourceRoot":"","sources":["../../src/components/glyph-text.ts"],"names":[],"mappings":"AA+BA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS;;;;;EAapB,CAAC"}

package/dist/components/index.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EACL,KAAK,UAAU,EACf,eAAe,EACf,MAAM,EACN,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,UAAU,EACf,iBAAiB,GAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EACL,0BAA0B,EAC1B,yBAAyB,EACzB,KAAK,kBAAkB,EACvB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EACL,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,KAAK,SAAS,EACd,SAAS,EACT,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,cAAc,CAAC"}