@forgeax/engine-render 0.1.4 → 0.1.7

package/src/components/mesh-filter.ts

@@ -8,9 +8,10 @@
 // The brand prevents cross-asset assignment at compile time (e.g.
 // `Handle<'TextureAsset','shared'>` is not assignable to `assetHandle`).
 //
-// AI users create one `MeshAsset` payload through geometry's primitive
-// factory and intern it in the owning World; the returned shared reference
-// matches the schema-derived `Handle<'MeshAsset', 'shared'>` shape.
+// AI users spawn with the assets-runtime constants `HANDLE_CUBE` /
+// `HANDLE_TRIANGLE` (now branded `Handle<'MeshAsset','shared'>` to
+// match the schema-derived shape); custom mesh registration is owned by
+// feat-future-asset-system (this MVP only exposes builtin handles).
 //
 // Naming flavor: unity-style "MeshFilter / MeshRenderer" pair, but the forgeax
 // pair does NOT mirror Unity's filter-toggle semantics - MeshFilter only
@@ -38,9 +39,10 @@ import { defineComponent } from '@forgeax/engine-ecs';
  * 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
@@ -48,11 +50,10 @@ import { defineComponent } from '@forgeax/engine-ecs';
  * 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 const MeshFilter = defineComponent('MeshFilter', {
   assetHandle: { type: 'shared<MeshAsset>' },

package/src/components/points.ts

@@ -0,0 +1,40 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** 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 const PointShapeValue = Object.freeze({
+  square: 0,
+  circle: 1,
+} as const);
+
+/** Decode the Points shape column without treating an unknown value as valid. */
+export function pointShapeFromU32(value: number): PointShape | undefined {
+  switch (value) {
+    case PointShapeValue.square:
+      return 'square';
+    case PointShapeValue.circle:
+      return 'circle';
+    default:
+      return undefined;
+  }
+}
+
+/** Screen-space point style. Geometry and material remain on their own owners. */
+export const Points = defineComponent(
+  'Points',
+  {
+    sizePx: { type: 'f32', default: 4 },
+    shape: { type: 'enum', default: PointShapeValue.square, labels: PointShapeValue },
+  },
+  {
+    meta: {
+      quickStart: 'Attach Points to render point-list MeshAsset vertices in screen pixels.',
+      diagnostics: 'Inspect sizePx and decode shape with pointShapeFromU32.',
+      recovery: 'Use points-lines-invalid-style for non-finite or non-positive sizePx values.',
+      boundaries:
+        'Points owns raster size and shape only; MeshFilter and MeshRenderer own geometry and material.',
+    },
+  },
+);

package/src/components/post-process-params.ts

@@ -3,10 +3,10 @@
 // Schema: { shader: 'string', data: 'buffer' }.
 //
 // `shader` identifies the fullscreen post-process shader (the same id as passed to
-// `renderer.postProcess.register(id, entry)`). `data` carries the per-frame params
+// the feature host registers for `id`). `data` carries the per-frame params
 // bytes as a variable-byte ECS managed buffer slot. The write side (world.spawn /
-// world.set) accepts any AllowSharedBufferSource (Float32Array / ArrayBuffer /
-// Uint8Array / any TypedArray) and the ECS normalizes it to Uint8Array bytes
+// world.set) accepts every AllowSharedBufferSource (Float32Array / ArrayBuffer /
+// Uint8Array / typed array) and the ECS normalizes it to Uint8Array bytes
 // (feat-20260621 V2 / AC-A4); the read side (world.get) returns Uint8Array, which
 // satisfies AllowSharedBufferSource for GPU queue.writeBuffer ingestion.
 //

package/src/components/scene-instance.ts

@@ -34,7 +34,7 @@
 //   - charter P3 (machine-readable schema: 3 closed fields)
 //   - charter P4 (consistent abstraction: instance == entity carrying
 //     SceneInstance — same `world.query({ read: [SceneInstance] })` /
-//     `world.get(root, SceneInstance)` path as any other component)
+//     `world.get(root, SceneInstance)` path as another component)
 
 import { defineComponent, type EntityHandle } from '@forgeax/engine-ecs';
 import type { LocalEntityId, MountOverride } from '@forgeax/engine-types';
@@ -52,8 +52,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 {
@@ -75,11 +75,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
@@ -96,17 +96,17 @@ export interface SceneInstanceState {
 
   /**
    * 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>;
@@ -134,7 +134,7 @@ 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.
    */
@@ -142,7 +142,7 @@ export interface SceneInstanceState {
 
   /**
    * 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).
    */
@@ -174,7 +174,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/src/components/skybox-background.ts

@@ -0,0 +1,103 @@
+// @forgeax/engine-runtime - SkyboxBackground (environment cubemap render background).
+//
+// Schema: 3 fields -- equirect (Handle<EquirectAsset>, u32-stored handle)
+// + mode (f32 enum column, discriminator) + rotation (quaternion xyzw,
+// default identity). Naming convention follows the
+// single-semantic component rule: no Component suffix (AGENTS.md rule #1).
+//
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w16:
+// the field is `equirect: shared<EquirectAsset>` (the retired
+// `cubemap: shared<CubeTextureAsset>` is gone). The skybox reuses the same
+// equirect handle as the Skylight; the cubemap projection is internal and
+// driven by the render-system record arm (no user upload call).
+//
+// Plan-strategy D-5: mode is a f32 enum column (ECS columns are POD, no
+// string unions in archetype storage). Consumer-facing type safety is
+// provided by the `SkyboxMode` literal union + `skyboxModeFromF32` mapper
+// (same pattern as cameraProjectionFromF32 in camera.ts:51,105,145,221-237).
+//
+// OOS-1: `mode: 'atmosphere'` implementation is deferred -- the union
+// shape leaves room for additive growth without breaking the f32 enum
+// encoding.
+//
+// AI user minimum spawn (charter P4):
+//   world.spawn({ component: SkyboxBackground, data: { equirect, mode: 0 } });
+//
+// Single component activates the skybox render pass transparently when a
+// Skylight + tonemap active camera is present (skybox reuses the same
+// equirect handle as Skylight).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * 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 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 function skyboxModeFromF32(value: number): SkyboxMode {
+  switch (value) {
+    case SKYBOX_MODE_CUBEMAP:
+      return 'cubemap';
+    // Future: case SKYBOX_MODE_ATMOSPHERE: return 'atmosphere';
+  }
+  // Unrecognised value: fall back to 'cubemap' (charter P3 -- no silent
+  // exception; the fallback preserves rendering on stale numerics while
+  // the exhaustive switch shape ensures AI users catch new members at
+  // compile time when a mode is added).
+  return 'cubemap';
+}
+
+/**
+ * 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 const SkyboxBackground = defineComponent('SkyboxBackground', {
+  // The GPU skybox projection is render-owned presentation state; restore
+  // keeps the portable mode/rotation controls and lets the owner re-resolve
+  // the environment asset on the target world.
+  equirect: { type: 'shared<EquirectAsset>', simulationTransient: true },
+  mode: { type: 'f32', default: SKYBOX_MODE_CUBEMAP },
+  rotation: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+});

package/src/components/{environment.ts → skylight.ts}

@@ -54,7 +54,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   `color` * `intensity` then scale the IBL ambient.
  *
  * `equirect` is an OPTIONAL `Handle<EquirectAsset>` resolved from a vite
- * pack-index GUID via `assets.load(guid, equirectAssetKind)`. The
+ * 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).
  *
@@ -78,7 +78,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   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 assets.load(guidRes.value, equirectAssetKind);
+ *   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.
@@ -95,111 +95,3 @@ export const Skylight = defineComponent('Skylight', {
   intensity: { type: 'f32', default: 1.0 },
   rotation: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
 });
-
-export const Fog = defineComponent('Fog', {
-  color: { type: 'array<f32, 3>', default: new Float32Array([0.5, 0.5, 0.5]) },
-  density: { type: 'f32', default: 0.01 },
-  heightFalloff: { type: 'f32', default: 0 },
-  maxOpacity: { type: 'f32', default: 1 },
-});
-
-// @forgeax/engine-runtime - SkyboxBackground (environment cubemap render background).
-//
-// Schema: 3 fields -- equirect (Handle<EquirectAsset>, u32-stored handle)
-// + mode (f32 enum column, discriminator) + rotation (quaternion xyzw,
-// default identity). Naming convention follows the
-// single-semantic component rule: no Component suffix (AGENTS.md rule #1).
-//
-// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w16:
-// the field is `equirect: shared<EquirectAsset>` (the retired
-// `cubemap: shared<CubeTextureAsset>` is gone). The skybox reuses the same
-// equirect handle as the Skylight; the cubemap projection is internal and
-// driven by the render-system record arm (no user upload call).
-//
-// Plan-strategy D-5: mode is a f32 enum column (ECS columns are POD, no
-// string unions in archetype storage). Consumer-facing type safety is
-// provided by the `SkyboxMode` literal union + `skyboxModeFromF32` mapper
-// (same pattern as cameraProjectionFromF32 in camera.ts:51,105,145,221-237).
-//
-// OOS-1: `mode: 'atmosphere'` implementation is deferred -- the union
-// shape leaves room for additive growth without breaking the f32 enum
-// encoding.
-//
-// AI user minimum spawn (charter P4):
-//   world.spawn({ component: SkyboxBackground, data: { equirect, mode: 0 } });
-//
-// Single component activates the skybox render pass transparently when a
-// Skylight + tonemap active camera is present (skybox reuses the same
-// equirect handle as Skylight).
-
-/**
- * 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 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 function skyboxModeFromF32(value: number): SkyboxMode {
-  switch (value) {
-    case SKYBOX_MODE_CUBEMAP:
-      return 'cubemap';
-    // Future: case SKYBOX_MODE_ATMOSPHERE: return 'atmosphere';
-  }
-  // Unrecognised value: fall back to 'cubemap' (charter P3 -- no silent
-  // exception; the fallback preserves rendering on stale numerics while the
-  // exhaustive switch shape ensures AI users catch new members at compile
-  // time when a mode is added).
-  return 'cubemap';
-}
-
-/**
- * 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 resolved from a Vite pack-index GUID through the App-owned
- * AssetRegistry (`AssetRegistry.load(guid, 'equirect')`). 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):
- *   // Resolve the equirect payload through the App AssetRegistry.
- *   world.spawn({ component: SkyboxBackground, data: { equirect: equirectHandle } });
- *
- * @example Single handle shared between Skylight (IBL) and SkyboxBackground:
- *   const hdrRes = await assets.load(guid, 'equirect');
- *   if (!hdrRes.ok) throw hdrRes.error;
- *   world.spawn({ component: Skylight, data: { equirect: hdrRes.value } });
- *   world.spawn({ component: SkyboxBackground, data: { equirect: hdrRes.value } });
- */
-export const SkyboxBackground = defineComponent('SkyboxBackground', {
-  // The GPU skybox projection is render-owned presentation state; restore
-  // keeps the portable mode/rotation controls and lets the owner re-resolve
-  // the environment asset on the target world.
-  equirect: { type: 'shared<EquirectAsset>', simulationTransient: true },
-  mode: { type: 'f32', default: SKYBOX_MODE_CUBEMAP },
-  rotation: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
-});

package/src/components/sprite-animation.ts

@@ -59,7 +59,7 @@
 //   2. Register the sprite material referencing the atlas
 //      `TextureAsset` with the initial frame's `region` rectangle (the
 //      runtime tick system overrides this region per entity per frame).
-//   3. `world.spawn` an entity with a quad mesh reference +
+//   3. `world.spawn` an entity with `MeshFilter(HANDLE_QUAD)` +
 //      `MeshRenderer(spriteMaterial)` + `Instances(...)` plus this
 //      `SpriteAnimation` (frameCount / frameDuration / regions /
 //      playbackMode) and `SpriteRegionOverride { region }` (the tick
@@ -122,8 +122,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *     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([
@@ -135,7 +134,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   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/src/components/sprite-instances.ts

@@ -66,7 +66,7 @@
 //   const regions    = new Float32Array(N * 4);
 //   // ... fill column-major mat4 columns + [uMin, vMin, uW, vH] per instance ...
 //   world.spawn(
-//     { component: MeshFilter,      data: { assetHandle: quadMesh } },
+//     { component: MeshFilter,      data: { assetHandle: HANDLE_QUAD } },
 //     { component: MeshRenderer,    data: { /* sprite-shaded MaterialAsset */ } },
 //     { component: SpriteInstances, data: { transforms, regions } },
 //   );
@@ -146,7 +146,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   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/src/components/sprite-playback-mode.ts

@@ -55,10 +55,16 @@ export const SPRITE_PLAYBACK_MODE_LOOP = 0 as const;
 /** Numeric encoding of the clamp playback mode (schema value for `playbackMode`). */
 export const SPRITE_PLAYBACK_MODE_CLAMP = 1 as const;
 
+/** Grouped authoring values; the numeric ECS encoding stays owner-local. */
+export const SpritePlayback = Object.freeze({
+  loop: SPRITE_PLAYBACK_MODE_LOOP,
+  clamp: SPRITE_PLAYBACK_MODE_CLAMP,
+} as const);
+
 /**
  * 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/src/components/sprite-region-override.ts

@@ -85,13 +85,12 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   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/src/components/tile-layer.ts

@@ -56,6 +56,12 @@ import type { Result } from '@forgeax/engine-types';
  */
 export type SortScope = 'layer' | 'per-cell';
 
+/** Compact authoring values for the stored u8 sort-scope field. */
+export const TilemapSort = Object.freeze({
+  layer: 0 as const,
+  perCell: 1 as const,
+});
+
 /**
  * Bridge: `SortScope` -> on-disk u8. SSOT for the encoding (`'layer'` -> 0,
  * `'per-cell'` -> 1). The compile-time exhaustive switch guards against
@@ -65,9 +71,9 @@ export type SortScope = 'layer' | 'per-cell';
 export function encodeSortScope(scope: SortScope): 0 | 1 {
   switch (scope) {
     case 'layer':
-      return 0;
+      return TilemapSort.layer;
     case 'per-cell':
-      return 1;
+      return TilemapSort.perCell;
   }
 }
 

package/src/construct-renderer.ts

@@ -1,4 +1,67 @@
-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 { createRenderer, exposeRenderer } from './assembly/factory';
+import type {
+  RendererHostImplementation,
+  RendererLegacyHostAdapter,
+} from './assembly/host-contract';
+import { type RenderError, RendererContractFailureError } 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 async function constructRendererHost(
+  canvas: unknown,
+  options?: RendererOptions,
+  bundler?: BundlerOptions,
+  backend?: RhiBackendPack,
+): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+  try {
+    const implementation = await createRenderer(canvas, options, bundler, backend);
+    const ready = await implementation.initialization;
+    if (!ready.ok) {
+      return {
+        ok: false,
+        error: new RendererContractFailureError(
+          'construct',
+          `${ready.error.code}: ${ready.error.hint}`,
+        ),
+      };
+    }
+    return {
+      ok: true,
+      value: {
+        renderer: exposeRenderer(implementation),
+        debugDrawHost: implementation,
+        featureHost: implementation,
+        assets: implementation.assetRegistry,
+      },
+    };
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    return {
+      ok: false,
+      error: new RendererContractFailureError('construct', detail),
+    };
+  }
+}