@forgeax/engine-render 0.1.4 → 0.1.7

package/dist/components/index.d.ts

@@ -1,15 +1,17 @@
-export { Atmosphere } from './atmosphere';
 export * from './camera';
 export * from './directional-light';
-export { Fog, SKYBOX_MODE_CUBEMAP, SkyboxBackground, type SkyboxMode, Skylight, skyboxModeFromF32, } from './environment';
 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';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,GAAG,EACH,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,UAAU,EACf,QAAQ,EACR,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5D,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,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EACL,aAAa,EACb,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,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"}
+{"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"}

package/dist/components/instances.d.ts

@@ -15,7 +15,7 @@
  *   const transforms = new Float32Array(10000 * 16);
  *   // ... fill column-major mat4 columns ...
  *   world.spawn(
- *     { component: MeshFilter,   data: { assetHandle: cubeMesh } },
+ *     { component: MeshFilter,   data: { assetHandle: HANDLE_CUBE } },
  *     { component: MeshRenderer, data: { ... } },
  *     { component: Instances,    data: { transforms } },
  *   );

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

@@ -1 +1 @@
-{"version":3,"file":"instances.d.ts","sourceRoot":"","sources":["../../src/components/instances.ts"],"names":[],"mappings":"AAsKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,SAAS;;EAEpB,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;CACnC,CAAC"}
+{"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/light-helpers.d.ts

@@ -1,5 +1,5 @@
 import { type Result } from '@forgeax/engine-types';
-import { SpawnLightInvalidBoundsError } from '../errors';
+import { SpawnLightInvalidBoundsError } from '../errors/ecs-validation';
 import { ShadowInvalidConfigError } from '../errors/render';
 export type LightValidationError = SpawnLightInvalidBoundsError | ShadowInvalidConfigError;
 export type LightValidationResult = Result<void, LightValidationError>;

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

@@ -1 +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,WAAW,CAAC;AACzD,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"}
+{"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

@@ -2,9 +2,10 @@
  * Mesh filter (geometry asset reference).
  *
  * `assetHandle` carries a `Handle<'MeshAsset', 'shared'>` (u32-stored)
- * pointing to a mesh interned by the owning World. Create that reference
- * with `world.internSharedRef(createPrimitiveMesh('cube').unwrap())` or
- * with a payload loaded from the App asset registry.
+ * 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
@@ -12,11 +13,10 @@
  * and skips this entity (other entities continue rendering; charter
  * proposition 9 graceful degradation).
  *
- * @example Spawn an entity referencing a geometry-owned cube mesh:
+ * @example Spawn an entity referencing the builtin cube mesh:
  *   import { MeshFilter } from '@forgeax/engine-render';
- *   import { createPrimitiveMesh } from '@forgeax/engine-geometry';
- *   const cube = world.internSharedRef(createPrimitiveMesh('cube').unwrap());
- *   world.spawn({ component: MeshFilter, data: { assetHandle: cube } });
+ *   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>";

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

@@ -1 +1 @@
-{"version":3,"file":"mesh-filter.d.ts","sourceRoot":"","sources":["../../src/components/mesh-filter.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,UAAU;;EAErB,CAAC"}
+{"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/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/scene-instance.d.ts

@@ -13,8 +13,8 @@ import type { LocalEntityId, MountOverride } from '@forgeax/engine-types';
  * 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 `worldSetSceneOverride(world, root, member, comp,
- *   field, value)` to write and `worldRemoveSceneOverride(world, root, member,
+ *   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 {
@@ -35,11 +35,11 @@ export interface SceneInstanceOverrideRecord {
  * AI users can iterate without indirection.
  *
  * Lifecycle:
- *   - allocated by `worldInstantiateScene(world, handle, parent?)` — the W in
+ *   - 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 `worldDespawnScene(world, root)` / `worldDespawnDescendants(world, root)`.
+ *     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
@@ -55,16 +55,16 @@ export interface SceneInstanceState {
     readonly source: import('@forgeax/engine-types').Handle<'SceneAsset', 'shared'>;
     /**
      * Reverse mapping (live `Entity` -> source `LocalEntityId`). Used by
-     * `worldSetSceneOverride` to validate the member entity belongs to this
-     * instance + by `worldDetachSceneMember` / `worldReattachSceneMember`
+     * `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
-     * `worldDetachSceneMember(world, root, member)`. The member entities stay
+     * `world.detachSceneMember(root, member)`. The member entities stay
      * alive in the World; only the bookkeeping marker moves so
-     * `worldDespawnDescendants(world, root, { keepDetached: true })` can skip them.
+     * `world.despawnDescendants(root, { keepDetached: true })` can skip them.
      * Detach is idempotent (set semantics).
      */
     readonly detachedLocalIds: Set<LocalEntityId>;
@@ -88,14 +88,14 @@ export interface SceneInstanceState {
     /**
      * Total slot count `entities.length + sum(mounts[].memberCount)` —
      * captured at instantiate-time so cycle / count consistency checks
-     * (e.g. `worldGetSceneAssetForInstance(world, root)` symmetry) can compare
+     * (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 `worldRemoveSceneOverride`
+     * 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).
      */
@@ -126,7 +126,7 @@ export interface SceneInstanceState {
  * apply unchanged (plan-strategy §D-5).
  *
  * @example Materialise + inspect a SceneAsset:
- *   const { root, diagnostics } = worldInstantiateScene(world, handle).value;
+ *   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 /

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/sprite-animation.d.ts

@@ -27,8 +27,7 @@
  *     SpriteAnimation, SpriteRegionOverride, SPRITE_PLAYBACK_MODE_LOOP,
  *   } from '@forgeax/engine-render/authoring';
  *   import { Transform } from '@forgeax/engine-scene';
- *   import { createPrimitiveMesh } from '@forgeax/engine-geometry';
- *   const quadMesh = world.internSharedRef(createPrimitiveMesh('quad').unwrap());
+ *   import { HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
  *
  *   // 4 frames packed in an atlas, each 64x64 inside a 256x64 row:
  *   const regions = new Float32Array([
@@ -40,7 +39,7 @@
  *   world.spawn(
  *     { component: Transform, data: { pos: [0, 0, 0],
  *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
- *     { component: MeshFilter, data: { assetHandle: quadMesh } },
+ *     { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
  *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },
  *     { component: SpriteAnimation,
  *       data: {

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

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

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

@@ -18,7 +18,7 @@
  *   const regions    = new Float32Array(10000 * 4);
  *   // ... fill mat4 columns + [uMin, vMin, uW, vH] ...
  *   world.spawn(
- *     { component: MeshFilter,      data: { assetHandle: quadMesh } },
+ *     { component: MeshFilter,      data: { assetHandle: HANDLE_QUAD } },
  *     { component: MeshRenderer,    data: { ... } },
  *     { component: SpriteInstances, data: { transforms, regions } },
  *   );

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

@@ -20,10 +20,15 @@ export type SpritePlaybackMode = 'loop' | 'clamp';
 export declare const SPRITE_PLAYBACK_MODE_LOOP: 0;
 /** Numeric encoding of the clamp playback mode (schema value for `playbackMode`). */
 export declare const SPRITE_PLAYBACK_MODE_CLAMP: 1;
+/** Grouped authoring values; the numeric ECS encoding stays owner-local. */
+export declare const SpritePlayback: Readonly<{
+    readonly loop: 0;
+    readonly clamp: 1;
+}>;
 /**
  * Map a `SpriteAnimation.playbackMode` numeric column value to the closed
  * `SpritePlaybackMode` string-literal union. The defensive fallback mirrors
- * `cameraProjectionFromF32` / `tonemapFromF32` precedent — any value other
+ * `cameraProjectionFromF32` / `tonemapFromF32` precedent — a value other
  * than `SPRITE_PLAYBACK_MODE_CLAMP` (1) maps to `'loop'`, so stale or
  * uninitialised entities surface a predictable playback shape through the
  * tick-system query (rather than throwing or returning `undefined`).

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

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

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

@@ -25,13 +25,12 @@
  *   import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
  *   import { SpriteRegionOverride } from '@forgeax/engine-render/authoring';
  *   import { Transform } from '@forgeax/engine-scene';
- *   import { createPrimitiveMesh } from '@forgeax/engine-geometry';
- *   const quadMesh = world.internSharedRef(createPrimitiveMesh('quad').unwrap());
+ *   import { HANDLE_QUAD } from '@forgeax/engine-assets-runtime';
  *
  *   world.spawn(
  *     { component: Transform, data: { pos: [0, 0, 0],
  *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
- *     { component: MeshFilter, data: { assetHandle: quadMesh } },
+ *     { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
  *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },
  *     { component: SpriteRegionOverride,
  *       data: { region: new Float32Array([0.5, 0, 0.5, 1]) } },

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

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

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

@@ -13,6 +13,11 @@ import type { Result } from '@forgeax/engine-types';
  *                  player sprite riding the same SPRITE_LAYER_VALUE).
  */
 export type SortScope = 'layer' | 'per-cell';
+/** Compact authoring values for the stored u8 sort-scope field. */
+export declare const TilemapSort: Readonly<{
+    layer: 0;
+    perCell: 1;
+}>;
 /**
  * Bridge: `SortScope` -> on-disk u8. SSOT for the encoding (`'layer'` -> 0,
  * `'per-cell'` -> 1). The compile-time exhaustive switch guards against

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

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

package/dist/construct-renderer.d.ts

@@ -1,2 +1,19 @@
-export { type BundlerOptions, createRenderer as constructRenderer, } from './renderer/renderer-factory';
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { RhiBackendPack } from './assembly/backend-contract';
+import type { BundlerOptions } from './assembly/factory';
+import type { RendererHostImplementation, RendererLegacyHostAdapter } from './assembly/host-contract';
+import { type RenderError } from './errors/render';
+import type { Renderer, RendererOptions, RenderResult } from './render-contract';
+export type { EngineEnvironmentErrorDetail, RhiBackendInstrumentation, RhiBackendPack, } from './assembly/backend-contract';
+export { EngineEnvironmentError } from './assembly/backend-contract';
+export type { RendererLegacyHostAdapter } from './assembly/host-contract';
+export type { BundlerOptions };
+export type RendererFeatureAssemblyHost = Pick<RendererLegacyHostAdapter, 'installRenderFeature' | 'uninstallRenderFeature'>;
+export interface RendererHostAssembly {
+    readonly renderer: Renderer;
+    readonly debugDrawHost: RendererHostImplementation;
+    readonly featureHost: RendererFeatureAssemblyHost;
+    readonly assets: AssetRegistry;
+}
+export declare function constructRendererHost(canvas: unknown, options?: RendererOptions, bundler?: BundlerOptions, backend?: RhiBackendPack): Promise<RenderResult<RendererHostAssembly, RenderError>>;
 //# sourceMappingURL=construct-renderer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"construct-renderer.d.ts","sourceRoot":"","sources":["../src/construct-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,cAAc,EACnB,cAAc,IAAI,iBAAiB,GACpC,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"construct-renderer.d.ts","sourceRoot":"","sources":["../src/construct-renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EACV,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,KAAK,WAAW,EAAgC,MAAM,iBAAiB,CAAC;AACjF,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjF,YAAY,EACV,4BAA4B,EAC5B,yBAAyB,EACzB,cAAc,GACf,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,yBAAyB,EACzB,sBAAsB,GAAG,wBAAwB,CAClD,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,0BAA0B,CAAC;IACnD,QAAQ,CAAC,WAAW,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,YAAY,CAAC,oBAAoB,EAAE,WAAW,CAAC,CAAC,CA6B1D"}