@forgeax/engine-render 0.1.3 → 0.1.6

package/src/assembly/host-contract.ts

@@ -0,0 +1,101 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import type { Result, RhiDevice, RhiError, ShaderModule } from '@forgeax/engine-rhi';
+import type { RecoverFailure } from '../errors/recover';
+import type { ObservationUnavailableError, RenderError } from '../errors/render';
+import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
+import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
+import type { FrameObservation, FrameObservationOptions } from '../record/frame';
+import type {
+  DrawOwnerOptions,
+  FrameObservationRequest,
+  FrameReceipt,
+  FrameReceiptObservation,
+  HealthSnapshot,
+  RenderDebugOverlay,
+  RendererError,
+  RendererErrorListener,
+  RendererLostListener,
+  RenderFrameInput,
+  RenderInspection,
+  RenderProfile,
+  RenderResult,
+  RenderWorldLease,
+} from '../render-contract';
+import type { RenderSceneInspection } from '../render-system';
+
+type RenderShaderModuleFactory = (
+  device: RhiDevice,
+  desc: { readonly label?: string | undefined; readonly code: string },
+) => Promise<Result<ShaderModule, RhiError>>;
+
+/** Package-local source projected to the sole public Renderer.subscribe channel. */
+export type RendererHostEvent =
+  | { readonly kind: 'error'; readonly error: RendererError }
+  | { readonly kind: 'health'; readonly health: HealthSnapshot };
+
+export type RendererHostEventListener = (event: RendererHostEvent) => void;
+
+/**
+ * Narrow assembly contract consumed by exposeRenderer and constructRendererHost.
+ * Legacy diagnostics remain on RendererLegacyHostAdapter and cannot leak into
+ * the public Renderer type.
+ */
+export interface RendererHostImplementation {
+  attach(world: World): RenderResult<RenderWorldLease, RenderError>;
+  setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
+  inspect(): RenderInspection;
+  drawFrame(request: RenderFrameInput): RenderResult<FrameReceipt, RhiError | RenderError>;
+  observe(
+    receipt: FrameReceipt,
+    request: FrameObservationRequest,
+  ): Promise<RenderResult<FrameReceiptObservation, RenderError>>;
+  releaseSurface(): RenderResult<void, RhiError>;
+  restoreSurface(): RenderResult<void, RhiError>;
+  recover(): Promise<Result<void, RecoverFailure>>;
+  dispose(): RenderResult<void, RenderError>;
+  /** @internal Single event source used to construct public Renderer.subscribe. */
+  subscribeHostEvents(listener: RendererHostEventListener): () => void;
+
+  readonly device: RhiDevice;
+  /** @internal */
+  readonly _internal_createShaderModule: RenderShaderModuleFactory;
+  /** @internal */
+  readonly _internal_setRenderOverlay: (overlay: RenderDebugOverlay | undefined) => void;
+  readonly assetRegistry: AssetRegistry;
+  readonly initialization: Promise<RenderResult<void, RhiError>>;
+}
+
+/**
+ * @internal
+ * Temporary package-local compatibility surface for unmigrated render tests
+ * and producers. It is intentionally absent from RendererHostImplementation.
+ */
+export interface RendererLegacyHostAdapter {
+  attachScene(world: World): RenderResult<void, RhiError>;
+  detachScene(world: World): void;
+  draw(
+    worldsOrRequest: readonly World[] | RenderFrameInput,
+    options?: DrawOwnerOptions,
+  ): RenderResult<void | FrameReceipt, RhiError | RenderError>;
+  observeCurrentFrame(
+    options: FrameObservationOptions,
+  ): Promise<RenderResult<FrameObservation, ObservationUnavailableError>>;
+  onLost(listener: RendererLostListener): () => void;
+  onError(listener: RendererErrorListener): () => void;
+  health(): HealthSnapshot;
+  readonly frustumStats: { readonly culled: number; readonly total: number };
+  readonly visibilityStats: { readonly explicitlyHidden: number };
+  readonly renderScene: RenderSceneInspection;
+  readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
+  readonly perFramePassNames: readonly string[];
+  renderFeatureDiagnostics(): readonly RenderFeatureDiagnostics[];
+  installRenderFeature(feature: RenderFeature<unknown>): Promise<RenderResult<void, RenderError>>;
+  uninstallRenderFeature(feature: RenderFeature<unknown>): Promise<RenderResult<void, RenderError>>;
+  readonly bindGroupCounts: { readonly createBindGroup: number; readonly keys: readonly string[] };
+}
+
+/** @internal Concrete factory object before it is narrowed by exposeRenderer. */
+export interface RendererAssemblyImplementation
+  extends RendererHostImplementation,
+    RendererLegacyHostAdapter {}

package/src/{renderer → assembly}/material/assembly.ts

@@ -1,4 +1,4 @@
-import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import type { CookedMaterialRecord } from '@forgeax/engine-pack/material-cook';
 import type { MaterialValue } from '@forgeax/engine-types';
 
 export interface MaterialRenderPassProjection {
@@ -15,7 +15,6 @@ export interface MaterialRenderProjection {
   readonly materialGuid: string;
   readonly specializationKey: string;
   readonly artifactHash: string;
-  readonly layoutIdentity: string;
   readonly passes: readonly MaterialRenderPassProjection[];
   readonly runtimeValues: Readonly<Record<string, MaterialValue | null>>;
   readonly staticSelection: readonly string[];
@@ -42,7 +41,6 @@ export function assembleMaterialProjection(record: CookedMaterialRecord): Materi
     materialGuid: record.guid,
     specializationKey: record.receipt.inputDigest,
     artifactHash: record.artifact.digest,
-    layoutIdentity: record.receipt.layoutIdentity,
     passes: record.resolved.passes.map((pass) => projectPass(record, pass)),
     runtimeValues: record.resolved.values,
     staticSelection: record.resolved.parameters

package/src/assembly/material/pipeline-projection.ts

@@ -0,0 +1,63 @@
+import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
+import type { MaterialValue } from '@forgeax/engine-types';
+import type { MaterialRenderProjection } from './assembly.js';
+
+export interface MaterialPipelineProjection {
+  readonly specializationKey: string;
+  readonly artifactHash: string;
+  readonly passes: MaterialRenderProjection['passes'];
+}
+
+export interface MaterialPipelineReady extends MaterialPipelineProjection {
+  readonly kind: 'ready';
+  readonly artifact: MaterialRuntimeArtifact;
+}
+
+export interface MaterialPipelineMiss {
+  readonly kind: 'error';
+  readonly error: {
+    readonly code: 'material-specialization-not-cooked';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: { readonly specializationKey: string };
+  };
+}
+
+export function projectMaterialPipeline(
+  projection: MaterialRenderProjection,
+): MaterialPipelineProjection {
+  return {
+    specializationKey: projection.specializationKey,
+    artifactHash: projection.artifactHash,
+    passes: projection.passes,
+  };
+}
+
+export function updateMaterialRuntimeValues(
+  projection: MaterialRenderProjection,
+  values: Readonly<Record<string, MaterialValue | null>>,
+): MaterialRenderProjection {
+  return {
+    ...projection,
+    runtimeValues: { ...projection.runtimeValues, ...values },
+  };
+}
+
+export function routeMaterialPipeline(args: {
+  readonly projection: MaterialRenderProjection;
+  readonly lookupArtifact: (key: string) => MaterialRuntimeArtifact | undefined;
+}): MaterialPipelineReady | MaterialPipelineMiss {
+  const artifact = args.lookupArtifact(args.projection.specializationKey);
+  if (artifact === undefined || artifact.digest !== args.projection.artifactHash) {
+    return {
+      kind: 'error',
+      error: {
+        code: 'material-specialization-not-cooked',
+        expected: 'a published artifact for the cooked specialization key',
+        hint: 'cook and publish the material specialization before rendering it',
+        detail: { specializationKey: args.projection.specializationKey },
+      },
+    };
+  }
+  return { kind: 'ready', ...projectMaterialPipeline(args.projection), artifact };
+}

package/src/authoring.ts

@@ -1,24 +1,16 @@
 // Optional authoring features intentionally live outside the base render vocabulary.
-export * from './components/glyph-text';
-export * from './components/sprite-animation';
-export * from './components/sprite-instances';
-export * from './components/sprite-playback-mode';
-export * from './components/sprite-region-override';
-export * from './components/tile-layer';
-export * from './components/tilemap';
-export { glyphTextLayoutSystem, resetGlyphBakeCache } from './glyph-text-layout-system';
+// Systems, asset resolution, and registry details remain owner-local.
+
+export { GlyphText } from './components/glyph-text';
+export { SpriteAnimation } from './components/sprite-animation';
+export { SpriteInstances, type SpriteInstancesData } from './components/sprite-instances';
+export { SpritePlayback, spritePlaybackModeFromU32 } from './components/sprite-playback-mode';
+export { SpriteRegionOverride } from './components/sprite-region-override';
+export { TileLayer, TilemapSort } from './components/tile-layer';
+export { Tilemap } from './components/tilemap';
 export {
-  Materials,
-  materialTextureValue,
-  SPRITE_PREMULTIPLIED_ALPHA_BLEND,
-} from './materials';
-export {
-  getTransparentSortConfig,
-  setTransparentSortConfig,
-  TRANSPARENT_SORT_MODE_DISTANCE,
-  TRANSPARENT_SORT_MODE_LAYER_Y,
-  TRANSPARENT_SORT_MODE_LAYER_YZ,
-  TRANSPARENT_SORT_MODE_LAYER_Z,
-  type TransparentSortConfig,
-} from './systems/transparent-sort-config';
-export { tilemapChunkExtractSystem } from './tilemap-chunk-extract-system';
+  createFullscreenRenderFeature,
+  type FullscreenRenderFeatureOptions,
+} from './features/fullscreen';
+export { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from './materials';
+export { TransparentSort } from './systems/transparent-sort-config';

package/src/components/__tests__/schema-contract.unit.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { Camera, DirectionalLight, MeshFilter } from '../index';
+
+describe('canonical render schema owners', () => {
+  it('keeps mesh, light, and camera facts on their component owners', () => {
+    expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
+    expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
+    expect(Camera.fields.projection.default).toBe(0);
+  });
+});

package/src/components/glyph-text.ts

@@ -13,7 +13,7 @@
 // Schema vocab:
 //   - `fontHandle: 'shared<FontAsset>'` -> `Handle<'FontAsset', 'shared'>`
 //     (u32-stored; AssetRegistry owns the FontAsset lifecycle). AI users
-//     obtain the handle via `assets.load(guid, fontAssetKind)`.
+//     obtain the handle via `assets.loadByGuid<FontAsset>(guid)`.
 //   - `text: 'string'` -> native JS string (UniqueRefStore-backed, same
 //     dispatch as `Name.value`).
 //   - `fontSize: 'f32'` -> layout scale applied to the FontAsset metrics.
@@ -41,7 +41,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *
  * @example Spawn a world-space label:
  *   import { GlyphText } from '@forgeax/engine-render/authoring';
- *   const font = (await assets.load(fontGuid, fontAssetKind)).unwrap();
+ *   const font = (await assets.loadByGuid(fontGuid)).unwrap();
  *   world.spawn({
  *     component: GlyphText,
  *     data: { fontHandle: font, text: 'Hello', fontSize: 32,
@@ -54,6 +54,7 @@ export const GlyphText = defineComponent('GlyphText', {
   fontHandle: {
     type: 'shared<FontAsset>',
     default: 0 as never,
+    simulationTransient: true,
   },
   text: { type: 'string', default: '' },
   fontSize: { type: 'f32', default: 16 },

package/src/components/index.ts

@@ -1,14 +1,5 @@
-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 * from './mesh-filter';
@@ -21,6 +12,13 @@ export {
   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/src/components/instances.ts

@@ -55,7 +55,7 @@
 // responsibility migration): the legacy component-level
 // stride-declaration option (`{ transforms: 16 }` keyed on the retired
 // per-component stride defineComponent option key) was retired because:
-//   - The ECS layer no longer carries any per-component stride schema (M2 /
+//   - The ECS layer no longer carries a per-component stride schema (M2 /
 //     w9 dropped the option from `DefineComponentOptions` -- the SSOT
 //     moved to the RenderSystem entry + AI user set site).
 //   - Centralising the check at the consumer (RenderSystem extract) rather
@@ -98,8 +98,7 @@
 // ===== (a) single-component import + spawn example =====
 //
 //   import {
-//     createRenderer,
-//     createPrimitiveMesh,
+//     createRenderer, HANDLE_CUBE,
 //     MeshFilter, MeshRenderer, Transform,
 //     Instances, type InstancesData,
 //   } from '@forgeax/engine-render';
@@ -108,7 +107,7 @@
 //   const transforms = new Float32Array(N * 16);
 //   // ... fill column-major mat4 columns per instance ...
 //   world.spawn(
-//     { component: MeshFilter,    data: { assetHandle: cubeMesh } },
+//     { component: MeshFilter,    data: { assetHandle: HANDLE_CUBE } },
 //     { component: MeshRenderer,  data: {} },
 //     { component: Instances,     data: { transforms } },
 //   );
@@ -181,7 +180,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   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/src/components/light-helpers.ts

@@ -15,7 +15,7 @@
 // invRangeSquared = 1e8 protects the 0 * Infinity = NaN intermediate).
 
 import { err, ok, 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;

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/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]) },
+});