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

package/src/components/mesh-renderer.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - MeshRenderer (multi-material array slot).
+//
+// feat-20260608-mesh-multi-section-primitive-multi-material-slot M2 / w7:
+// the single `material` field is replaced with `materials` — an
+// `array<shared<MaterialAsset>>` indexed by MeshAsset.materialSlots. Entries
+// are sparse positional overrides: a missing/zero entry inherits the Mesh
+// slot default, while a defaultless slot inherits the neutral engine material.
+//
+// The schema-vocab keyword `'array<shared<MaterialAsset>>'` (feat-20260614
+// M5 -- migrated from `'array<handle<MaterialAsset>>'`) stores as a u32
+// column slot array; the brand prevents cross-asset assignment at compile
+// time. The `'shared<T>'` arm routes element retain/release through
+// SharedRefStore (M4 / w13) on overwrite / archetype migration.
+//
+// charter mapping: proposition 1 (single import — `MeshRenderer` is the
+// only material-binding component AI users see); proposition 3
+// (machine-readable schema > prose); proposition 4 (explicit failure: the
+// TS brand on `Handle<'MaterialAsset','shared'>` rejects cross-variant
+// assignment at compile time); proposition 5 (consistent abstraction:
+// shading model classification (`'unlit'` / `'standard'`) lives ONLY on
+// the asset discriminant, NOT on the component name).
+//
+// RenderSystem consumption: `render-system-extract.ts` runs ONE archetype
+// query (`world.query(MeshRenderer)`) and routes per entity by
+// `mat.materialShaderId` (shader identity) to the unlit.wgsl or pbr.wgsl
+// pipeline tag.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * 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 const MeshRenderer = defineComponent('MeshRenderer', {
+  materials: { type: 'array<shared<MaterialAsset>>', default: [] },
+});

package/src/components/point-light-shadow.ts

@@ -0,0 +1,43 @@
+// @forgeax/engine-runtime — PointLightShadow (omnidirectional point-light
+// shadow mapping parameters; cube-array atlas variant).
+//
+// Schema: 6 f32 columns — mapSize (u32, stored as f32), depthBias, normalBias,
+// nearPlane, farPlane, pcfKernelSize (u32, stored as f32). No fixed-extent
+// field — cube map uses fov=90 perspective, not ortho.
+//
+// Atlas capacity is a renderer policy; ECS does not enforce a component
+// cardinality bound.
+// Co-located with DirectionalLight in components/ (research L1.2).
+//
+// Naming convention: bare entity name (AGENTS.md §Component naming), no
+// Component suffix. Same defineComponent pattern and ShadowInvalidConfigError
+// surface as the shadow fields merged into DirectionalLight (feat-20260621 M1).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * 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 const PointLightShadow = defineComponent('PointLightShadow', {
+  mapSize: { type: 'f32', default: 512 },
+  depthBias: { type: 'f32', default: 0.005 },
+  normalBias: { type: 'f32', default: 0.05 },
+  nearPlane: { type: 'f32', default: 0.1 },
+  farPlane: { type: 'f32', default: 25 },
+  pcfKernelSize: { type: 'f32', default: 3 },
+});

package/src/components/point-light.ts

@@ -0,0 +1,65 @@
+// @forgeax/engine-render - PointLight (omnidirectional point-light parameters).
+//
+// Schema: color array<f32,3> + intensity f32 + range f32 (feat-20260709 M2:
+// color collapsed from 3 per-axis scalar columns to one inline array<f32,3>).
+// `position` comes from the Transform component; PointLight requires a
+// companion Transform on the same entity (ECS query: `[Transform, PointLight]`).
+// `range` units are meters; defaults to `10.0`. Runtime finite-range
+// attenuation is the Three r184 squared window; the KHR unsquared curve is an
+// import/reference boundary only. See `light-helpers.ts` for the host-side
+// range projection.
+//
+// 0 light + standard material -> physically correct black render
+// (feat-20260518-pbr-direct-lighting-mvp). The runtime once-warn channel
+// (M5 / w25) collapses to "directionalCount + pointCount + spotCount === 0";
+// see packages/runtime/README.md section Common pitfalls for the AI-user
+// guidance after the M5 docs land.
+//
+// Naming convention: bare entity name aligned with Bevy ECS conventions
+// (feat-20260513-component-naming-bevy-align). DirectionalLight / SpotLight
+// follow the same single-semantic-entity rule (charter proposition 5).
+//
+// charter mapping: proposition 1 (single import + IDE autocomplete on
+// payload.range) + proposition 3 (silent failure -> explicit failure;
+// spawn-time fail-fast on range<0 / NaN with structured EcsError) +
+// proposition 5 (consistent abstraction: shared payload shape with
+// SpotLight; `range` semantics aligned with KHR_lights_punctual).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * 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 const PointLight = defineComponent('PointLight', {
+  // color carries an explicit layer-2 default [1,1,1] (white); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1 },
+  range: { type: 'f32', default: 10.0 },
+});

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

@@ -0,0 +1,35 @@
+// @forgeax/engine-render - PostProcessParams component.
+//
+// Schema: { shader: 'string', data: 'buffer' }.
+//
+// `shader` identifies the fullscreen post-process shader (the same id as passed to
+// 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 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.
+//
+// Single-semantic component — drops the `Component` suffix
+// (AGENTS.md §Component naming rule #1). The `data` field uses the ECS 'buffer'
+// vocab keyword (plan-strategy D-7) for variable-byte storage.
+//
+// Data flow (plan-strategy D-1):
+//   extract -> iterate PostProcessParams-bearing entities ->
+//   collect into Map<shaderId, AllowSharedBufferSource> snapshot ->
+//   dispatchFullscreenPass picks up per-shader data -> writeBuffer to eager UBO.
+//
+// Decision anchors:
+//   - requirements AC-A2 (data-driven, no imperative renderer.setParams mutator)
+//   - requirements AC-A4 (AllowSharedBufferSource type on the data field)
+//   - plan-strategy D-1 (new single-semantic ECS component for params)
+//   - plan-strategy D-7 (ECS 'buffer' vocab keyword for variable-byte storage)
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+const schema = {
+  shader: 'string',
+  data: 'buffer',
+} as const;
+
+export const PostProcessParams = defineComponent('PostProcessParams', schema);

package/src/components/scene-instance.ts

@@ -0,0 +1,193 @@
+// @forgeax/engine-runtime - SceneInstance component (feat-20260608-
+// scene-nesting-ecs-fication M2 / w16).
+//
+// Single ECS fat component carrying everything that used to live on the
+// old `SceneInstance` + `SceneInstanceContainer` pair (deleted
+// in M3). Schema fits the ECS schema vocab (3 single-identifier fields):
+//
+//   { source:  'shared<SceneAsset>',
+//     mapping: 'array<entity>',
+//     state:   'unique<SceneInstanceState>' }
+//
+// `source` carries the SceneAsset handle the synthetic root entity was
+// instantiated from (Tier-A AssetUnion handle, AGENTS.md §Assets submodule).
+// `mapping` is the LocalEntityId -> Entity table indexed positionally
+// (mapping[localId] = spawned Entity); the ECS variable-array column gives
+// us a SoA-friendly read path for query<SceneInstance> scans without
+// touching the dynamic Map/Set state.
+// `state` is a `ref<SceneInstanceState>` slot — World holds the live
+// SceneInstanceState payload in its UniqueRefStore and World despawn
+// auto-releases the ref u32 (the same path used by audio / physics
+// payloads, plan-strategy §D-2). Each instantiateScene call calls
+// `world.allocUniqueRef('SceneInstanceState', state)` once and stores the
+// returned u32 in this column.
+//
+// Decision anchors:
+//   - plan-strategy §D-2 (single ref wraps SceneInstanceState dynamic
+//     structure; ECS schema vocab `\w+` rejects `ref<Map<...>>`)
+//   - plan-strategy §3.2 sequence (sequence diagram step 'set ... state:
+//     {entityToLocalId, detached, overrides, rootEntities}')
+//   - AGENTS.md §Component naming rule #1 (single-semantic component drops
+//     `Component` suffix)
+//   - charter F1 (single-import barrel: SceneInstance lives in
+//     `@forgeax/engine-render` next to Transform / Camera / DirectionalLight)
+//   - 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 another component)
+
+import { defineComponent, 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 const SceneInstance = defineComponent(
+  'SceneInstance',
+  {
+    source: { type: 'shared<SceneAsset>' },
+    mapping: { type: 'array<entity>' },
+    // The unique slot is the ECS storage seam for the instance's structured
+    // runtime payload; keep the nested semantic visible to schema consumers.
+    state: { type: 'unique<SceneInstanceState>', shape: 'nested' },
+  },
+  { transient: true },
+);

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/skylight.ts

@@ -0,0 +1,97 @@
+// @forgeax/engine-runtime - Skylight (ambient environment light).
+//
+// Schema: 4 fields -- equirect (Handle<EquirectAsset>, u32-stored handle,
+// OPTIONAL) + color (array<f32,3>, default [1,1,1] = white) + intensity (f32,
+// default 1.0) + rotation (quaternion xyzw, default identity). feat-20260709 M2 collapsed colorR/G/B into one inline
+// array<f32,3> column. Naming convention follows the DirectionalLight / PointLight /
+// SpotLight family: no Component suffix (AGENTS.md rule #1).
+//
+// Plan-strategy D-6: Skylight component schema is registered but no
+// independent ECS system is created. All Skylight processing happens inside
+// RenderSystem's extract/record phases.
+//
+// AI user minimum spawn (AC-13, charter P4):
+//   world.spawn({ component: Skylight, data: {} });  // instant white ambient
+//
+// A single Skylight activates ambient lighting transparently. The `equirect`
+// field is OPTIONAL: omit it for a constant solid-color ambient that needs NO
+// async GPU precompute -- the engine binds a 1x1 white irradiance cube, so
+// ambient = color * intensity * albedo is live on the very first frame (this
+// is the fix for the downstream "scene is black until the async IBL cubemap
+// finishes uploading" gap). Supply an equirect to upgrade to full image-based
+// lighting (diffuse irradiance + specular prefilter); `color` * `intensity`
+// still scales the IBL result, so both are live dynamic dials either way.
+//
+// feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w16:
+// the field is `equirect: shared<EquirectAsset>` (the retired
+// `cubemap: shared<CubeTextureAsset>` is gone). AI users declare the equirect
+// source directly; the render-system record arm projects the cubemap + IBL
+// chain internally and lazily (no user upload call) -- there is no
+// uploadCubemapFromEquirect on the public surface.
+//
+// Edge cases handled by w18 / w19:
+//   - Multi-Skylight: first archetype hit wins, console.warn in dev+prod
+//   - intensity=0: ambient term = 0, mathematically valid, no warn
+//   - No equirect: solid-color ambient via the white fallback cube (no async)
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * 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 const Skylight = defineComponent('Skylight', {
+  // The GPU equirect-to-cubemap projection is render-owned presentation
+  // state. Record/restore preserves the portable lighting controls while the
+  // render owner resolves this asset again on the target world.
+  equirect: { type: 'shared<EquirectAsset>', simulationTransient: true },
+  // color carries an explicit layer-2 default [1,1,1] (white); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  color: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
+  intensity: { type: 'f32', default: 1.0 },
+  rotation: { type: 'array<f32, 4>', default: new Float32Array([0, 0, 0, 1]) },
+});