@forgeax/engine-render 0.1.3 → 0.1.6

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

package/src/debug-draw-glue.ts

@@ -1,128 +1,13 @@
-// @forgeax/engine-runtime — debug-draw auto-attach SSOT (feat-20260615-debug-draw M5 / w28)
+// @forgeax/engine-render - typed debug overlay graph contribution.
 //
-// Plan D-1: wiring lives in packages/runtime/, not in packages/debug-draw/
-// Plan D-5: single-file SSOT for createApp hook + attachDebugOverlayPass helper
-// Plan D-8: both URP and HDRP share the same attachDebugOverlayPass helper (SSOT)
-//
-// Two exports:
-//   (a) createDebugDrawOnReady(renderer, format?) — creates a DebugDraw instance
-//       once renderer.ready settles. Sets the package-internal registry so the
-//       graph pass closures can reach it. Called from createApp to populate
-//       app.debugDraw.
-//   (b) attachDebugOverlayPass(graph, getViewProj) — adds a tonemap-suffix
-//       overlay pass to a render-graph. The pass execute closure reads the
-//       internally-registered DebugDraw instance (set by createDebugDrawOnReady).
+// App owns the concrete DebugDraw instance and injects its declaration-only
+// capability through the Renderer host. Render owns graph ordering and pass
+// encoding without depending on the debug-draw package.
 
-import type { DebugDraw } from '@forgeax/engine-debug-draw';
-import { createDebugDraw } from '@forgeax/engine-debug-draw';
-import { type Mat4, mat4 } from '@forgeax/engine-math';
-import type {
-  RenderGraph,
-  RenderGraphBuilder,
-  RenderGraphError,
-} from '@forgeax/engine-render-graph';
-import type { TextureFormat, TextureView } from '@forgeax/engine-rhi';
+import { mat4 } from '@forgeax/engine-math';
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
 import type { Result } from '@forgeax/engine-types';
-import type { RenderPipelineFrame } from './render-pipeline';
-import type { RenderPipelineContext } from './render-pipeline-context';
-import type { RenderPipelineTarget } from './render-pipeline-target';
-import type { Renderer } from './renderer';
-import { selectSwapChainFormat } from './surface-format';
-
-/**
- * Package-internal registry: the active DebugDraw instance for the current
- * renderer. Set by createDebugDrawOnReady, read by attachDebugOverlayPass
- * execute closures. A single renderer has one DebugDraw instance.
- */
-let registeredDebugDraw: DebugDraw | null = null;
-
-/**
- * Create a DebugDraw instance once `renderer.ready` settles.
- *
- * Waits for the GPU device + shader manifest + builtin asset upload to
- * complete before creating the DebugDraw PSO. Stores the instance in the
- * package-internal registry so graph pass closures can reach it.
- *
- * Bug A fix (feat-20260626 m6-4): the PSO color format MUST equal the swap-chain
- * LDR view the overlay pass draws into (`attachDebugOverlayPass` flushes to
- * `ctx.view`), or the backend rejects the render pass with an attachment-state
- * mismatch every frame. The view format is the SSOT
- * `selectSwapChainFormat(caps.storageBuffer).view` -- `bgra8unorm-srgb` on
- * native WebGPU (follows getPreferredCanvasFormat + the srgb-via-viewFormats
- * route) and `rgba8unorm-srgb` on wgpu-wasm GLES -- the same derivation
- * `PipelineState.colorAttachmentFormat` uses (memory
- * offscreen-rt-format-must-follow-swapchain-not-hardcode-rgba). The hardcoded
- * `'bgra8unorm'` default was latent until the overlay pass actually flushed
- * (before the glue merge the pass was a no-op stub that never validated). A
- * caller may still pass an explicit `format` to target a custom surface.
- */
-export async function createDebugDrawOnReady(
-  renderer: Renderer,
-  format?: TextureFormat,
-): Promise<DebugDraw> {
-  const ready = await renderer.ready;
-  if (!ready.ok) throw ready.error;
-
-  const resolvedFormat =
-    format ??
-    (selectSwapChainFormat(renderer.device.caps.storageBuffer).view as unknown as TextureFormat);
-
-  const ddResult = await createDebugDraw({
-    device: renderer.device,
-    queue: renderer.device.queue,
-    createShaderModule: renderer._internal_createShaderModule,
-    format: resolvedFormat,
-  });
-  if (!ddResult.ok) throw ddResult.error;
-
-  registeredDebugDraw = ddResult.value;
-  return ddResult.value;
-}
-
-/** Release one app-owned DebugDraw and remove it from render-pass lookup. */
-export function releaseDebugDraw(debugDraw: DebugDraw): void {
-  if (registeredDebugDraw === debugDraw) registeredDebugDraw = null;
-  debugDraw.destroy();
-}
-
-/**
- * Attach a DebugOverlay pass to a render graph at the tonemap suffix.
- *
- * The pass is added with empty reads/writes (the swap-chain is not a
- * graph-declared target). The execute closure reads `ctx.view` (the
- * swap-chain TextureView) + `ctx.encoder` (the shared frame command
- * encoder) and calls `dd.flush(encoder, view, viewProj)` using the
- * registered DebugDraw instance.
- *
- * When no DebugDraw is registered (createDebugDrawOnReady not called,
- * or tree-shaken), the pass is a silent no-op.
- *
- * Per plan D-8: URP and HDRP both call this helper with their respective
- * tonemap-suffix graphs, keeping the wiring single-source.
- *
- * @param graph - The per-frame RenderGraph (URP forward-graph or HDRP tonemap-graph).
- * @param getViewProj - Thunk that returns camera.viewProj from the pass context
- *   at execute time (not at graph-build time).
- */
-export function attachDebugOverlayPass(
-  graph: RenderGraph<RenderPipelineContext>,
-  getViewProj: (ctx: RenderPipelineContext) => Mat4,
-  options: { readonly reads?: readonly string[] } = {},
-): void {
-  graph.addPass('debug-overlay', {
-    // The overlay draws to ctx.view, but it still needs a graph edge so a
-    // producer that targets the scene color cannot be appended after it.
-    // The caller supplies the active pipeline's final scene-color token.
-    reads: options.reads ?? [],
-    writes: [],
-    execute: (ctx: RenderPipelineContext) => {
-      const dd = registeredDebugDraw;
-      if (!dd) return; // not registered (no debug-draw in this runtime)
-      const viewProj = getViewProj(ctx);
-      dd.flush(ctx.encoder, ctx.view as unknown as TextureView, viewProj);
-    },
-  });
-}
+import type { RenderPipelineFrame, RenderPipelineTarget } from './render-pipeline';
 
 export function addTypedDebugOverlayPass(
   graph: RenderGraphBuilder<RenderPipelineFrame>,
@@ -131,12 +16,6 @@ export function addTypedDebugOverlayPass(
   return graph.addRasterPass('debug-overlay', {
     accesses: [{ resource: output.view, usage: 'color-attachment' }],
     colorAttachments: [{ view: output.view, loadOp: 'load', storeOp: 'store' }],
-    // The graph topology is stable, but debug geometry is immediate-mode state.
-    // Evaluate admission for every frame so an empty overlay does not open a
-    // color-attachment render pass. This must stay here, before `encode` and
-    // therefore before beginRenderPass; a no-op encode still pays the pass
-    // begin/end cost and can perturb timestamp/pass accounting.
-    executeIf: () => registeredDebugDraw?.hasPendingWork() ?? false,
     encode: ({ pass, frame }) => {
       const projection = mat4.create();
       if (frame.camera.projection === 'orthographic') {
@@ -159,7 +38,7 @@ export function addTypedDebugOverlayPass(
         );
       }
       const view = mat4.invert(mat4.create(), frame.camera.world);
-      const result = registeredDebugDraw?.encode(
+      const result = frame.runtime.debugOverlay?.encode(
         pass,
         mat4.multiply(mat4.create(), projection, view),
       );