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

package/dist/components/instances.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Per-entity instanced-draw transforms (ECS component).
+ *
+ * Carries a variable-length `array<f32>` of column-major mat4 instance
+ * transforms (16 f32 per instance, stride = 16; documented above and
+ * enforced at the RenderSystem extract entry, NOT at the ECS write paths).
+ *
+ * The runtime RenderSystem consumer materialises a fresh `Float32Array`
+ * snapshot on every `world.get(e, Instances).transforms` access (D-4
+ * no-cache), reads the live count from the snapshot's `length`, and
+ * uploads the bytes to a per-entity GPU storage buffer in the record stage
+ * (`render-system-record.ts`).
+ *
+ * @example Spawn an entity rendering 10000 instanced cubes:
+ *   const transforms = new Float32Array(10000 * 16);
+ *   // ... fill column-major mat4 columns ...
+ *   world.spawn(
+ *     { component: MeshFilter,   data: { assetHandle: HANDLE_CUBE } },
+ *     { component: MeshRenderer, data: { ... } },
+ *     { component: Instances,    data: { transforms } },
+ *   );
+ */
+export declare const Instances: import("@forgeax/engine-ecs").Component<"Instances", {
+    readonly transforms: "array<f32>";
+}>;
+/**
+ * Type-level hint for `data` at the `Instances` 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). The `transforms` field is documented as `Float32Array` here so
+ * AI-user IDE autocomplete picks up the typed-array shape.
+ *
+ * @example
+ *   import type { InstancesData } from '@forgeax/engine-render';
+ *   const data: InstancesData = { transforms: new Float32Array(N * 16) };
+ */
+export type InstancesData = {
+    readonly transforms: Float32Array;
+};
+//# sourceMappingURL=instances.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../src/components/instances.ts"],"names":[],"mappings":"AAqKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS;;EAEpB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;CACnC,CAAC"}

package/dist/components/layer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Render-order layer index.
+ *
+ * Convention (non-binding; conveys intent, not enforced):
+ *   - negative (e.g. -100): background layers (sky / parallax tiles).
+ *   - 0: default game layer.
+ *   - positive (e.g. 100): foreground layers (overlays, FX).
+ *   - 1000+: UI / HUD.
+ *
+ * Signed i32 (two's complement, range \u00b12\u00b3\u00b9). Negatives round-trip
+ * through the spawn payload unchanged — no schema-layer mutate. i32 lives in
+ * the CPU sort path (transparent-sort.ts M-3 w23); no GPU-side stride
+ * compatibility risk.
+ *
+ * @example Minimal spawn (defaults to game layer 0):
+ *   world.spawn({ component: Layer, data: {} }); // yields value=0
+ *
+ * @example Spawn 4 sprites across the conventional layer band:
+ *   world.spawn({ component: Layer, data: { value: -100 } }); // background
+ *   world.spawn({ component: Layer, data: { value: 0 } });    // default
+ *   world.spawn({ component: Layer, data: { value: 100 } });  // foreground
+ *   world.spawn({ component: Layer, data: { value: 1000 } }); // UI
+ *
+ * @example Spawn payload omitting Layer — the 4-layer fallback fills 0:
+ *   const e = world.spawn(
+ *     { component: Transform, data: { pos: [0, 0, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *   );
+ *   // Layer is not on the entity; query joins must check membership.
+ */
+export declare const Layer: import("@forgeax/engine-ecs").Component<"Layer", {
+    readonly value: "i32";
+}>;
+//# sourceMappingURL=layer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"layer.d.ts","sourceRoot":"","sources":["../../src/components/layer.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,KAAK;;EAEhB,CAAC"}

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

@@ -0,0 +1,53 @@
+import { type Result } from '@forgeax/engine-types';
+import { SpawnLightInvalidBoundsError } from '../errors/ecs-validation';
+import { ShadowInvalidConfigError } from '../errors/render';
+export type LightValidationError = SpawnLightInvalidBoundsError | ShadowInvalidConfigError;
+export type LightValidationResult = Result<void, LightValidationError>;
+/**
+ * Convert SpotLight cone half-angle (degrees) to its cosine.
+ *
+ * Single-shot deg -> rad -> cos conversion executed once per spot light
+ * entity per frame on the host; the GPU shader sees only `cosInner` /
+ * `cosOuter` so its falloff path stays branch-free
+ * (`smoothstep(cosOuter, cosInner, dot(L, -lightDir))`).
+ *
+ * @param deg cone half-angle in degrees (component schema field
+ *            `innerConeDeg` / `outerConeDeg`)
+ * @returns `cos(deg * pi / 180)`
+ */
+export declare function degToCos(deg: number): number;
+/**
+ * Convert PointLight / SpotLight `range` (meters) to `1 / range^2`.
+ *
+ * Three-branch fold supplies `1 / range^2` for the Three r184 finite-range
+ * window `clamp(1 - (d / range)^4, 0, 1)^2`:
+ *
+ *   - `range = +Infinity` -> `0` (no truncation; quartic factor collapses
+ *     to `1`, falloff reduces to plain `1 / d^2`).
+ *   - `range = 0` -> `1e8` (host safety boundary; glTF `range: 0` is mapped
+ *     to the no-cutoff `Infinity` value before this helper is called).
+ *   - `range > 0` -> `1 / (range * range)` (standard quartic factor).
+ *
+ * @param range meters (component schema field `range`); `+Infinity` is the
+ *              KHR no-truncation default
+ * @returns `1 / range^2` with three-branch NaN protection
+ */
+export declare function computeInvRangeSquared(range: number): number;
+/**
+ * feat-20260709 M2 / D-1: shared zero/missing-direction validate for
+ * DirectionalLight + SpotLight. `direction` has no layer-2 default, so an
+ * omitted direction lands the array layer-3 all-zero -- the same illegal state
+ * as an explicit zero vector. SSOT for the rejection so the two lights cannot
+ * drift. Returns the structured error to reject, or `null` when the direction
+ * is a valid non-zero vector.
+ */
+export declare function validateDirection(componentName: 'DirectionalLight' | 'SpotLight', direction: ArrayLike<number> | undefined): SpawnLightInvalidBoundsError | null;
+/** Validate directional-light payloads at the render owner boundary. */
+export declare function validateDirectionalLightData(data: Readonly<Record<string, unknown>>): LightValidationResult;
+/** Validate spot-light payloads at the render owner boundary. */
+export declare function validateSpotLightData(data: Readonly<Record<string, unknown>>): LightValidationResult;
+/** Validate point-light payloads at the render owner boundary. */
+export declare function validatePointLightData(data: Readonly<Record<string, unknown>>): LightValidationResult;
+/** Validate point-light shadow payloads at the render owner boundary. */
+export declare function validatePointLightShadowData(data: Readonly<Record<string, unknown>>): LightValidationResult;
+//# sourceMappingURL=light-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"light-helpers.d.ts","sourceRoot":"","sources":["../../src/components/light-helpers.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAE5D,MAAM,MAAM,oBAAoB,GAAG,4BAA4B,GAAG,wBAAwB,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;AAKvE;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI5D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,kBAAkB,GAAG,WAAW,EAC/C,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,SAAS,GACvC,4BAA4B,GAAG,IAAI,CAUrC;AAED,wEAAwE;AACxE,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,qBAAqB,CA+BvB;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,qBAAqB,CAgCvB;AAED,kEAAkE;AAClE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,qBAAqB,CAMvB;AAED,yEAAyE;AACzE,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,qBAAqB,CAavB"}

package/dist/components/lines.d.ts

@@ -0,0 +1,5 @@
+/** Screen-space independent line segment style. */
+export declare const Lines: import("@forgeax/engine-ecs").Component<"Lines", {
+    readonly widthPx: "f32";
+}>;
+//# sourceMappingURL=lines.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lines.d.ts","sourceRoot":"","sources":["../../src/components/lines.ts"],"names":[],"mappings":"AAEA,mDAAmD;AACnD,eAAO,MAAM,KAAK;;EAcjB,CAAC"}

package/dist/components/mesh-filter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Mesh filter (geometry asset reference).
+ *
+ * `assetHandle` carries a `Handle<'MeshAsset', 'shared'>` (u32-stored)
+ * pointing into `engine.assets: AssetRegistry`. Use the predefined
+ * constants `HANDLE_CUBE` / `HANDLE_TRIANGLE` exported from
+ * `@forgeax/engine-render`; custom-mesh registration is OOS in MVP (see
+ * feat-future-asset-system).
+ *
+ * Error path: if the handle is not registered at draw time, RenderSystem
+ * fires `Renderer.onError` with
+ * `RhiError({ code: 'asset-not-registered', detail: { assetHandle } })`
+ * and skips this entity (other entities continue rendering; charter
+ * proposition 9 graceful degradation).
+ *
+ * @example Spawn an entity referencing the builtin cube mesh:
+ *   import { MeshFilter } from '@forgeax/engine-render';
+ *   import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+ *   world.spawn({ component: MeshFilter, data: { assetHandle: HANDLE_CUBE } });
+ */
+export declare const MeshFilter: import("@forgeax/engine-ecs").Component<"MeshFilter", {
+    readonly assetHandle: "shared<MeshAsset>";
+}>;
+//# sourceMappingURL=mesh-filter.d.ts.map

package/dist/components/mesh-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-filter.d.ts","sourceRoot":"","sources":["../../src/components/mesh-filter.ts"],"names":[],"mappings":"AAqCA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU;;EAErB,CAAC"}

package/dist/components/mesh-renderer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mesh renderer (ECS component, multi-material array).
+ *
+ * Stores `materials: readonly Handle<'MaterialAsset','shared'>[]`
+ * (u32-stored array, indexed by MeshAsset.materialSlots). Submeshes point to
+ * those stable slots through `Submesh.materialSlot`. The asset's `passes[].shader`
+ * identity is the SSOT for which pipeline RenderSystem routes the entity
+ * to (record stage dispatches on `materialShaderId`).
+ *
+ * Defaults map carries `materials: []`: every slot inherits its Mesh-owned
+ * default, or the neutral engine material when that slot is intentionally
+ * defaultless.
+ *
+ * @example Spawn while inheriting every Mesh slot default:
+ *   world.spawn({ component: MeshRenderer, data: {} });
+ *
+ * @example Spawn an unlit-targeted entity:
+ *   import { MeshRenderer, Materials } from '@forgeax/engine-render';
+ *   const matPayload = engine.assets.catalog(matGuid, Materials.unlit([1, 0, 0, 1])).value;
+ *   const matHandle = world.allocSharedRef('MaterialAsset', matPayload);
+ *   world.spawn({ component: MeshRenderer, data: { materials: [matHandle] } });
+ *
+ * @example Spawn a standard (PBR) entity:
+ *   const matPayload = engine.assets.catalog(matGuid, Materials.standard({
+ *     baseColor: [0.5, 0.5, 0.5, 1], metallic: 0, roughness: 0.4,
+ *   })).value;
+ *   const matHandle = world.allocSharedRef('MaterialAsset', matPayload);
+ *   world.spawn({ component: MeshRenderer, data: { materials: [matHandle] } });
+ */
+export declare const MeshRenderer: import("@forgeax/engine-ecs").Component<"MeshRenderer", {
+    readonly materials: "array<shared<MaterialAsset>>";
+}>;
+//# sourceMappingURL=mesh-renderer.d.ts.map

package/dist/components/mesh-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh-renderer.d.ts","sourceRoot":"","sources":["../../src/components/mesh-renderer.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY;;EAEvB,CAAC"}

package/dist/components/point-light-shadow.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Omnidirectional point-light shadow mapping parameters.
+ *
+ * The renderer may batch this component into a bounded atlas, but the ECS
+ * component remains a plain storage schema and carries no cardinality policy.
+ *
+ * @example Spawn a point light with default shadow config:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 4, 0] } },
+ *     { component: PointLight, data: { range: 25 } },
+ *     { component: PointLightShadow, data: {} }, // 6 fields filled from defaults
+ *   );
+ *
+ * @example Spawn with explicit map size and bias:
+ *   world.spawn(
+ *     { component: PointLightShadow, data: { mapSize: 1024, depthBias: 0.01 } },
+ *   );
+ */
+export declare const PointLightShadow: import("@forgeax/engine-ecs").Component<"PointLightShadow", {
+    readonly mapSize: "f32";
+    readonly depthBias: "f32";
+    readonly normalBias: "f32";
+    readonly nearPlane: "f32";
+    readonly farPlane: "f32";
+    readonly pcfKernelSize: "f32";
+}>;
+//# sourceMappingURL=point-light-shadow.d.ts.map

package/dist/components/point-light-shadow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"point-light-shadow.d.ts","sourceRoot":"","sources":["../../src/components/point-light-shadow.ts"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;EAO3B,CAAC"}

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

@@ -0,0 +1,35 @@
+/**
+ * Omnidirectional point light (KHR_lights_punctual `point` type).
+ *
+ * `position` source: the companion `Transform` component on the same entity.
+ * Spawn via `world.spawn({ component: Transform, data: ... }, { component: PointLight, data: ... })`
+ * so the render system extract path can join the two via the
+ * `[Transform, PointLight]` ECS query.
+ *
+ * `color` is linear-space rgb in `[0, 1]` per channel; `intensity` is candela;
+ * `range` is in meters and defaults to `10.0`
+ * (KHR convention; `+Infinity` is the KHR no-truncation value, retained
+ * for KHR_lights_punctual `range: 0` bridging via `light-helpers.ts`).
+ * The runtime window is `clamp(1 - (d / range)^4, 0, 1)^2`; its no-cutoff
+ * boundary uses inverse-square decay with the shader safety floor. Exposure is
+ * applied after lighting and never multiplied into intensity.
+ *
+ * @example Spawn a single point light at (5, 3, 5):
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [5, 3, 5] } },
+ *     { component: PointLight, data: { intensity: 8, range: 25 } },
+ *   );
+ *
+ * @example Minimal spawn -- defaults give neutral white at full strength, range 10m:
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 1, 0] } },
+ *     { component: PointLight, data: {} },
+ *   );
+ *   // resolves to color=[1, 1, 1], intensity=1, range=10.0.
+ */
+export declare const PointLight: import("@forgeax/engine-ecs").Component<"PointLight", {
+    readonly color: "array<f32, 3>";
+    readonly intensity: "f32";
+    readonly range: "f32";
+}>;
+//# sourceMappingURL=point-light.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"point-light.d.ts","sourceRoot":"","sources":["../../src/components/point-light.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,UAAU;;;;EAMrB,CAAC"}

package/dist/components/points.d.ts

@@ -0,0 +1,15 @@
+/** Public point raster shapes backed by the ECS enum column. */
+export type PointShape = keyof typeof PointShapeValue;
+/** Numeric labels stored by the public Points shape enum field. */
+export declare const PointShapeValue: Readonly<{
+    readonly square: 0;
+    readonly circle: 1;
+}>;
+/** Decode the Points shape column without treating an unknown value as valid. */
+export declare function pointShapeFromU32(value: number): PointShape | undefined;
+/** Screen-space point style. Geometry and material remain on their own owners. */
+export declare const Points: import("@forgeax/engine-ecs").Component<"Points", {
+    readonly sizePx: "f32";
+    readonly shape: "enum";
+}>;
+//# sourceMappingURL=points.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"points.d.ts","sourceRoot":"","sources":["../../src/components/points.ts"],"names":[],"mappings":"AAEA,gEAAgE;AAChE,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,eAAe,CAAC;AAEtD,mEAAmE;AACnE,eAAO,MAAM,eAAe;;;EAGjB,CAAC;AAEZ,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CASvE;AAED,kFAAkF;AAClF,eAAO,MAAM,MAAM;;;EAelB,CAAC"}

package/dist/components/post-process-params.d.ts

@@ -0,0 +1,5 @@
+export declare const PostProcessParams: import("@forgeax/engine-ecs").Component<"PostProcessParams", {
+    readonly shader: "string";
+    readonly data: "buffer";
+}>;
+//# sourceMappingURL=post-process-params.d.ts.map

package/dist/components/post-process-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-process-params.d.ts","sourceRoot":"","sources":["../../src/components/post-process-params.ts"],"names":[],"mappings":"AAkCA,eAAO,MAAM,iBAAiB;;;EAA+C,CAAC"}

package/dist/components/scene-instance.d.ts

@@ -0,0 +1,140 @@
+import { type EntityHandle } from '@forgeax/engine-ecs';
+import type { LocalEntityId, MountOverride } from '@forgeax/engine-types';
+/**
+ * Per-component, per-field override record carried in `SceneInstanceState`.
+ *
+ * Composite key `<componentName>:<fieldName>` keeps the override map flat
+ * (single Map nesting level) so AI users walking `state.overrides` see one
+ * iteration depth — D-2 prefers a single SSOT over multi-Map nesting that
+ * would make iteration order ambiguous (charter F1: single mental model).
+ *
+ * The value is `unknown` because the per-component schema vocab lives in the
+ * ECS layer; runtime fail-fast via `EcsErrorCode = 'scene-override-type-
+ * mismatch'` (plan-strategy §D-9) catches type drift on the apply path.
+ *
+ * @internal Surface from `state.overrides` only; AI users never construct a
+ *   record directly. Use `world.setSceneOverride(root, member, comp,
+ *   field, value)` to write and `world.removeSceneOverride(root, member,
+ *   comp, field)` to roll back to the source SceneAsset value.
+ */
+export interface SceneInstanceOverrideRecord {
+    readonly comp: string;
+    /**
+     * Component-granular add-or-patch discriminant (feat-20260713 M1 / w4):
+     * present -> this record patches a single field; absent -> it adds/upserts
+     * the whole `comp` (M2 apply semantics). Mirrors `MountOverride.field`.
+     */
+    readonly field?: string;
+    readonly value: unknown;
+}
+/**
+ * Dynamic state payload for one SceneInstance — held in the World's
+ * UniqueRefStore behind a `ref<SceneInstanceState>` slot on the synthetic
+ * root entity. Mirrors the old class-based layout (plan-strategy §D-2 +
+ * design doc §11.2 internal-state-table) but flattened into plain JS Maps/Sets so
+ * AI users can iterate without indirection.
+ *
+ * Lifecycle:
+ *   - allocated by `world.instantiateScene(handle, parent?)` — the W in
+ *     `world.allocUniqueRef('SceneInstanceState', state)` returns the u32
+ *     slot id stored in the SceneInstance.state column;
+ *   - released by `world.despawn(root)` (the standard `ref<T>` release loop)
+ *     or explicitly via `world.despawnScene(root)` / `world.despawnDescendants(root)`.
+ *
+ * AI users typically reach this struct only through the read path
+ * `world.get(root, SceneInstance).state.overrides.get(<comp>:<field>)` for
+ * inspection; mutation happens through the 8 World methods.
+ */
+export interface SceneInstanceState {
+    /**
+     * SceneAsset handle the instance was instantiated from. Mirrors the
+     * SceneInstance.source column for AI users who already have a
+     * SceneInstanceState in hand and want the source handle without a second
+     * `world.get` round-trip.
+     */
+    readonly source: import('@forgeax/engine-types').Handle<'SceneAsset', 'shared'>;
+    /**
+     * Reverse mapping (live `Entity` -> source `LocalEntityId`). Used by
+     * `world.setSceneOverride` to validate the member entity belongs to this
+     * instance + by `world.detachSceneMember` / `world.reattachSceneMember`
+     * to translate caller-side Entity values back to their authored localId.
+     */
+    readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
+    /**
+     * LocalEntityIds of members the AI user marked detached via
+     * `world.detachSceneMember(root, member)`. The member entities stay
+     * alive in the World; only the bookkeeping marker moves so
+     * `world.despawnDescendants(root, { keepDetached: true })` can skip them.
+     * Detach is idempotent (set semantics).
+     */
+    readonly detachedLocalIds: Set<LocalEntityId>;
+    /**
+     * Per-member runtime overrides keyed by `<localId>` -> `<comp>:<field>`
+     * -> override record. mount-time overrides (authored on the SceneAsset's
+     * `mounts[].overrides`) populate this map at instantiate-time so AI
+     * users see them via the same read path as runtime
+     * `setSceneOverride` writes (single SSOT).
+     */
+    readonly overrides: Map<LocalEntityId, Map<string, SceneInstanceOverrideRecord>>;
+    /**
+     * Top-level root entities of the materialised tree (members without a
+     * ChildOf parent at instantiate time). The synthetic root entity that
+     * carries the SceneInstance component itself is NOT in this list — it is
+     * the parent of every member entity (plan-strategy §3.2 sequence step 7).
+     */
+    readonly rootEntities: EntityHandle[];
+    /** Synthetic roots of recursively mounted SceneAssets owned by this instance. */
+    readonly mountRoots: EntityHandle[];
+    /**
+     * Total slot count `entities.length + sum(mounts[].memberCount)` —
+     * captured at instantiate-time so cycle / count consistency checks
+     * (e.g. `world.getSceneAssetForInstance(root)` symmetry) can compare
+     * against the live SceneInstance.mapping column without re-reading the
+     * SceneAsset.
+     */
+    readonly totalSlots: number;
+    /**
+     * Mount-time override authored on the parent SceneAsset's `mounts[]`
+     * record. Captured at instantiate-time so `world.removeSceneOverride`
+     * can fall back to the mount-time value before going to the source
+     * SceneAsset value (plan-strategy §D-2).
+     */
+    readonly mountTimeOverrides: readonly MountOverride[];
+}
+/**
+ * SceneInstance ECS component — synthetic root entity payload for one
+ * materialised SceneAsset (instance == entity carrying SceneInstance,
+ * charter P4).
+ *
+ * AI users discover the component via IDE autocomplete on
+ * `@forgeax/engine-render` (single-import barrel; AGENTS.md §Components):
+ *
+ * ```ts
+ * import { SceneInstance } from '@forgeax/engine-render';
+ * for (const row of world.query({ read: [SceneInstance] }).unwrap()) {
+ *   console.log(`root=${row.entity} source=${row.get(SceneInstance).source}`);
+ * }
+ *
+ * const inst = world.get(root, SceneInstance).value;
+ * const memberEntity = inst.mapping[localId]; // Uint32Array snapshot
+ * for (const detached of inst.state.detachedLocalIds) { /* ... *\/ }
+ * ```
+ *
+ * The component does not register a relationship — synthetic root +
+ * members are wired through the standard `ChildOf` (member -> root) so
+ * the existing `world.iterDescendants(root)` / Children mirror code paths
+ * apply unchanged (plan-strategy §D-5).
+ *
+ * @example Materialise + inspect a SceneAsset:
+ *   const { root, diagnostics } = world.instantiateScene(handle).value;
+ *   const inst = world.get(root, SceneInstance).value;
+ *   // inst.source === handle, inst.mapping is Uint32Array(totalSlots)
+ *   // inst.state holds entityToLocalId / detachedLocalIds / overrides /
+ *   // rootEntities / mountRoots / totalSlots / mountTimeOverrides.
+ */
+export declare const SceneInstance: import("@forgeax/engine-ecs").Component<"SceneInstance", {
+    readonly source: "shared<SceneAsset>";
+    readonly mapping: "array<entity>";
+    readonly state: "unique<SceneInstanceState>";
+}>;
+//# sourceMappingURL=scene-instance.d.ts.map

package/dist/components/scene-instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-instance.d.ts","sourceRoot":"","sources":["../../src/components/scene-instance.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE1E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,uBAAuB,EAAE,MAAM,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;IAEhF;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC;IAE3D;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;IAE9C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAEjF;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,EAAE,CAAC;IAEtC,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC;IAEpC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,SAAS,aAAa,EAAE,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,aAAa;;;;EAUzB,CAAC"}

package/dist/components/skybox-background.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Skybox mode literal union (AC-02 narrowing surface).
+ * Currently only 'cubemap' -- future 'atmosphere' deferred per OOS-1.
+ */
+export type SkyboxMode = 'cubemap';
+/** Numeric encoding of cubemap skybox mode (schema value for `mode`). */
+export declare const SKYBOX_MODE_CUBEMAP = 0;
+/**
+ * Map a `SkyboxBackground.mode` numeric value to the closed `SkyboxMode`
+ * string-literal union. Only member currently is 'cubemap'; the exhaustive
+ * switch is ready for future mode additions (e.g. 'atmosphere', OOS-1).
+ */
+export declare function skyboxModeFromF32(value: number): SkyboxMode;
+/**
+ * SkyboxBackground: full-screen environment cubemap background.
+ *
+ * Renders a fullscreen triangle that reconstructs world-space view
+ * direction from the camera's inverseViewProj matrix (View UBO),
+ * samples a cubemap with the view direction, and writes an HDR color
+ * to the hdrColor render target (before the main geometry pass).
+ *
+ * The skybox pass is automatically activated when a SkyboxBackground
+ * entity exists, a Skylight entity provides the equirect source, and the
+ * active Camera has tonemap active. The skybox reuses the same equirect
+ * handle as the Skylight entity -- two independent components sharing the
+ * same GPU resource (the internally-projected cubemap).
+ *
+ * `equirect` is a `Handle<EquirectAsset>` resolved from a vite pack-index
+ * GUID via `engine.assets.loadByGuid<EquirectAsset>(guid)`. The cubemap
+ * projection is internal and driven by the render-system record arm; there
+ * is no user upload call.
+ *
+ * `mode` is a numeric discriminator column (`'f32'`). Use
+ * `SKYBOX_MODE_CUBEMAP` for the cubemap render path.
+ *
+ * `rotation` is an environment-space quaternion in `[x, y, z, w]` order.
+ * It rotates the sampled cubemap without changing the camera or rebaking the
+ * source equirectangular asset.
+ *
+ * @example Minimum spawn (defaults mode=0):
+ *   // equirectHandle resolved from loadByGuid<EquirectAsset> (same handle as
+ *   // the Skylight).
+ *   world.spawn({ component: SkyboxBackground, data: { equirect: equirectHandle } });
+ *
+ * @example Single handle shared between Skylight (IBL) and SkyboxBackground:
+ *   const hdrRes = await engine.assets.loadByGuid<EquirectAsset>(guid);
+ *   if (!hdrRes.ok) throw hdrRes.error;
+ *   world.spawn({ component: Skylight,     data: { equirect: hdrRes.value } });
+ *   world.spawn({ component: SkyboxBackground, data: { equirect: hdrRes.value } });
+ */
+export declare const SkyboxBackground: import("@forgeax/engine-ecs").Component<"SkyboxBackground", {
+    readonly equirect: "shared<EquirectAsset>";
+    readonly mode: "f32";
+    readonly rotation: "array<f32, 4>";
+}>;
+//# sourceMappingURL=skybox-background.d.ts.map

package/dist/components/skybox-background.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skybox-background.d.ts","sourceRoot":"","sources":["../../src/components/skybox-background.ts"],"names":[],"mappings":"AA+BA;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,CAAC;AAEnC,yEAAyE;AACzE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAW3D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,gBAAgB;;;;EAO3B,CAAC"}

package/dist/components/skylight.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Skylight ambient environment light.
+ *
+ * A single Skylight entity provides ambient lighting for all StandardMaterial
+ * surfaces. Two modes share one component:
+ *
+ * - **Solid-color ambient (no equirect).** Omit `equirect` for a constant
+ *   ambient = `color` * `intensity` applied immediately, with no async GPU
+ *   precompute. The engine samples a built-in 1x1 white irradiance cube, so a
+ *   freshly-loaded scene is lit on its first frame instead of being black
+ *   until an IBL upload finishes.
+ * - **Image-based lighting (with equirect).** Supply `equirect` to upgrade to
+ *   diffuse irradiance + specular prefilter IBL. The engine runs the full
+ *   precompute (equirect->cubemap, irradiance convolution, prefilter mip
+ *   chain, BRDF LUT) transparently inside the render-system record arm;
+ *   `color` * `intensity` then scale the IBL ambient.
+ *
+ * `equirect` is an OPTIONAL `Handle<EquirectAsset>` resolved from a vite
+ * pack-index GUID via `engine.assets.loadByGuid<EquirectAsset>(guid)`. The
+ * cubemap projection is internal and idempotent: the same equirect source
+ * always resolves to the same GPU cubemap (no user upload call).
+ *
+ * `color` is the linear-space ambient tint (default white [1, 1, 1]).
+ * `intensity` is a linear multiplier (default 1.0; 0 disables ambient). Both
+ * are read every frame, so they are live dynamic dials.
+ *
+ * `rotation` is an environment-space quaternion in `[x, y, z, w]` order.
+ * The default identity quaternion leaves the source orientation unchanged;
+ * changing it rotates the IBL at sample time without rebaking the source.
+ *
+ * @example Instant white ambient (no asset, no async):
+ *   world.spawn({ component: Skylight, data: {} });
+ *
+ * @example Dim warm ambient:
+ *   world.spawn({ component: Skylight, data: { color: [1, 0.9, 0.8], intensity: 0.3 } }); // color is [r, g, b]
+ *
+ * @example Full IBL from an HDR equirect (declarative -- no upload call):
+ *   // 1. resolve GUID from vite pack-index (see forgeax-engine-vite-plugin-pack)
+ *   import { AssetGuid } from '@forgeax/engine-pack/guid';
+ *   const guidRes = AssetGuid.parse('019e4a26-3c29-7420-af5d-20f2724a16b0');
+ *   if (!guidRes.ok) throw guidRes.error;
+ *   // 2. load the HDR equirect via the GUID-addressed pack route
+ *   const hdrRes = await engine.assets.loadByGuid<EquirectAsset>(guidRes.value);
+ *   if (!hdrRes.ok) throw hdrRes.error;
+ *   // 3. spawn the Skylight — the equirect handle activates the full IBL path;
+ *   //    the cubemap + IBL precompute happen lazily inside the record arm.
+ *   world.spawn({ component: Skylight, data: { equirect: hdrRes.value } });
+ */
+export declare const Skylight: import("@forgeax/engine-ecs").Component<"Skylight", {
+    readonly equirect: "shared<EquirectAsset>";
+    readonly color: "array<f32, 3>";
+    readonly intensity: "f32";
+    readonly rotation: "array<f32, 4>";
+}>;
+//# sourceMappingURL=skylight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"skylight.d.ts","sourceRoot":"","sources":["../../src/components/skylight.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,QAAQ;;;;;EAUnB,CAAC"}

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"}