@forgeax/engine-render 0.1.4 → 0.1.6

package/src/renderer.ts

@@ -1,940 +0,0 @@
-// @forgeax/engine-runtime — Renderer public-surface types + class.
-//
-// K-4 contract:
-//   - `Renderer.backend` is an opaque marker (`'webgpu'`); callers never
-//     branch on the underlying backend type, only on this string.
-//   - `Renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` runs one frame for the supplied worlds.
-//   - `Renderer.onLost(cb)` registers a notify-only listener for device loss.
-//   - `Renderer.onError(cb)` registers a listener for RHI creation-time errors.
-//   - `Renderer.dispose()` releases GPU resources + detaches all listeners.
-//
-// AC-15 source-level guarantee: this file does NOT touch `window` or
-// `document` at import time; canvas is supplied by the caller.
-
-import type { CreateShaderModule } from '@forgeax/engine-debug-draw';
-import type { World } from '@forgeax/engine-ecs';
-import type { InputSnapshot } from '@forgeax/engine-input';
-import type { ProfileFrameToken, Profiler } from '@forgeax/engine-profiler';
-import type { RenderGraphError } from '@forgeax/engine-render-graph';
-import type { Result, RhiDevice, RhiError, RhiInstance } from '@forgeax/engine-rhi';
-import type { ShaderError, ShaderRegistry } from '@forgeax/engine-shader';
-import type { SkinError } from '@forgeax/engine-skinning';
-import type { Handle, ImageError, RenderPipelineAsset, Submesh } from '@forgeax/engine-types';
-import type { RenderAssetPort } from './assets/render-asset-port';
-import type { RenderAssetResolutionError } from './assets/resolve-render-asset';
-import type { EngineMetrics } from './engine-metrics';
-import type { RecoverError } 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 { MeshUpdateError } from './mesh-update-errors';
-import type { PipelineError } from './pipeline-errors';
-import type { PostProcessError } from './post-process-errors';
-import type { FrameObservation, FrameObservationOptions } from './record/frame-observation';
-import type {
-  MembershipTimingController,
-  MembershipTimingOptions,
-} from './record/membership-timing';
-import type { RenderPipeline } from './render-pipeline';
-import type { RenderSceneInspection } from './render-system';
-
-export type RenderResult<T, E> =
-  | { readonly ok: true; readonly value: T }
-  | { readonly ok: false; readonly error: E };
-
-export interface RendererInstallError {
-  readonly code: string;
-  readonly hint: string;
-}
-
-/** Backend marker — single-element union preserved for future extensibility (D-2). */
-export type RendererBackend = 'webgpu';
-
-/**
- * `renderer.draw(worlds, options)` owner options
- * (feat-20260709-editor-world-partition M1 / w6, plan-strategy §2 D-3).
- *
- * The single `owner` index that previously served BOTH the surfaced cameras
- * and the singleton render resources (skylight / skybox / postProcessParams) is
- * split into two independent indices:
- *   - `cameraOwner`   — the world whose cameras are surfaced.
- *   - `resourceOwner` — the world whose skylight / skybox / postProcessParams
- *                       are surfaced.
- *
- * Both owners are always explicit. Single-world callers pass zero for both;
- * composite callers may select different worlds.
- */
-export type DrawOwnerOptions = {
-  readonly cameraOwner: number;
-  readonly resourceOwner: number;
-  readonly profileFrame?: ProfileFrameToken;
-};
-
-/** Information attached to a device-loss notification. */
-export interface RendererLostInfo {
-  /** Concise machine-readable cause, mapped to a single vocabulary. */
-  reason: string;
-  /** Free-form description (UA / extension / driver text). */
-  message: string;
-}
-
-/** Listener registered through `Renderer.onLost`. */
-export type RendererLostListener = (info: RendererLostInfo) => void;
-
-/**
- * Composite error type reachable through the `Renderer.onError` fan-out channel
- * (D-4). This is the fan-out channel's *wire contract* — it does NOT define any
- * error; it only references the cluster unions whose members can arrive here.
- * As such it is an external wire alias (AGENTS.md Change stance add-only wire
- * exception), NOT the eliminated cross-cluster `RuntimeError` SSOT (D-3).
- *
- * Composition = `RhiError | ShaderError | RenderError | RenderAssetResolutionError |
- * SkinError | PostProcessError`. This equals the pre-decomposition
- * `RhiError | RuntimeError | PostProcessError` exactly: `RuntimeError` was
- * `RenderError | RenderAssetResolutionError | SkinError` (27 classes). `RecoverError`
- * and `EngineEnvironmentError` are intentionally excluded — neither is ever
- * fired through `onError` (`RecoverError` returns from `recover()`,
- * `EngineEnvironmentError` throws at construction), matching the original
- * `RuntimeError` union which excluded both (OOS-3 behavior equivalence).
- *
- * AI consumers do `switch (err.code)` over the union: the disjoint
- * `RhiErrorCode` / `RenderErrorCode` / `RenderAssetResolutionErrorCode` / `SkinErrorCode`
- * / `PostProcessErrorCode` literal sets let TS narrow each arm to the concrete
- * class (charter P3 union discoverability — every fan-out member is reachable
- * in an exhaustive switch, no `as any` escape). Example:
- *
- * ```ts
- * renderer.onError((err) => {
- *   switch (err.code) {
- *     case 'asset-not-found': // RenderAssetResolutionError arm, err narrowed here
- *       return report(err.hint);
- *     // ...one arm per RhiErrorCode | RenderErrorCode | RenderAssetResolutionErrorCode
- *     //    | SkinErrorCode | PostProcessErrorCode member; no default needed,
- *     //    TS flags any unhandled code at compile time.
- *   }
- * });
- * ```
- */
-export type RendererError =
-  | RhiError
-  | ShaderError
-  | RenderGraphError
-  | ImageError
-  | RenderError
-  | RenderAssetResolutionError
-  | SkinError
-  | PostProcessError
-  | PipelineError;
-
-/**
- * Listener registered through `Renderer.onError` (fix-f2). Receives any
- * {@link RendererError} fanned out through the channel.
- */
-export type RendererErrorListener = (error: RendererError) => void;
-
-/**
- * Built-in graph pass owners used as nested children of `record/graph-execute`.
- * Unknown extension pass names use the explicit `other` bucket so custom
- * pipelines retain a bounded catalog while the default render workload gets
- * actionable owner attribution.
- */
-export const RENDER_GRAPH_EXECUTION_PHASE_CATALOG = [
-  'record/graph-execute/point-shadow',
-  'record/graph-execute/cluster-binner-upload',
-  'record/graph-execute/g-buffer',
-  'record/graph-execute/g-buffer/geometry-loop',
-  'record/graph-execute/g-buffer/material-bind-groups',
-  'record/graph-execute/g-buffer/pipeline-selection',
-  'record/graph-execute/g-buffer/draw-submit',
-  'record/graph-execute/ssao-calc',
-  'record/graph-execute/ssao-blur',
-  'record/graph-execute/lighting',
-  'record/graph-execute/forward',
-  'record/graph-execute/forward/geometry-loop',
-  'record/graph-execute/forward/material-bind-groups',
-  'record/graph-execute/forward/pipeline-selection',
-  'record/graph-execute/forward/draw-submit',
-  'record/graph-execute/scene-temporal',
-  'record/graph-execute/scene-temporal/geometry-loop',
-  'record/graph-execute/scene-temporal/material-bind-groups',
-  'record/graph-execute/scene-temporal/pipeline-selection',
-  'record/graph-execute/scene-temporal/draw-submit',
-  'record/graph-execute/tonemap',
-  'record/graph-execute/debug-overlay',
-  'record/graph-execute/shadow',
-  'record/graph-execute/spot-shadow',
-  'record/graph-execute/skybox',
-  'record/graph-execute/main',
-  'record/graph-execute/fxaa',
-  'record/graph-execute/bloom-bright',
-  'record/graph-execute/bloom-blur-h',
-  'record/graph-execute/bloom-blur-v',
-  'record/graph-execute/bloom-composite',
-  'record/graph-execute/other',
-] as const;
-
-export type RenderGraphExecutionPhase = (typeof RENDER_GRAPH_EXECUTION_PHASE_CATALOG)[number];
-
-/** Bounded producer-owned children of the scene-state record owner. */
-export const RENDER_HDRP_BINNER_PHASE_CATALOG = [
-  'record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy',
-  'record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/light-aabb',
-  'record/scene-state/hdrp-cluster/binner/light-bounds-and-occupancy/cluster-occupancy',
-  'record/scene-state/hdrp-cluster/binner/cluster-reserve',
-  'record/scene-state/hdrp-cluster/binner/input-preparation',
-  'record/scene-state/hdrp-cluster/binner/bin-core',
-  'record/scene-state/hdrp-cluster/binner/light-index-write',
-  'record/scene-state/hdrp-cluster/binner/light-index-write/bounds-read',
-  'record/scene-state/hdrp-cluster/binner/light-index-write/cluster-write',
-] as const;
-
-export type RenderHdrpBinnerPhase = (typeof RENDER_HDRP_BINNER_PHASE_CATALOG)[number];
-
-export const RENDER_HDRP_CLUSTER_PHASE_CATALOG = [
-  'record/scene-state/hdrp-cluster/binner',
-  ...RENDER_HDRP_BINNER_PHASE_CATALOG,
-  'record/scene-state/hdrp-cluster/payload-packing',
-  'record/scene-state/hdrp-cluster/buffer-upload',
-] as const;
-
-export type RenderHdrpClusterPhase = (typeof RENDER_HDRP_CLUSTER_PHASE_CATALOG)[number];
-
-export const RENDER_SCENE_STATE_PHASE_CATALOG = [
-  'record/scene-state/fold-buckets',
-  'record/scene-state/lighting-prep',
-  'record/scene-state/ambient-resolution',
-  'record/scene-state/directional-shadow-cache',
-  'record/scene-state/hdrp-cluster',
-  ...RENDER_HDRP_CLUSTER_PHASE_CATALOG,
-] as const;
-
-export type RenderSceneStatePhase = (typeof RENDER_SCENE_STATE_PHASE_CATALOG)[number];
-
-/**
- * Opt-in boundaries inside one `Renderer.draw` call. The observer is a
- * diagnostics seam only: it receives wall-time boundaries and must never be
- * required for rendering correctness. The stage names mirror the existing
- * engine-owned Extract / Prepare / Record orchestration so a host can measure
- * attribution without guessing from RHI command counts.
- */
-export const RENDER_RECORD_PHASE_CATALOG = [
-  'record/scene-state',
-  ...RENDER_SCENE_STATE_PHASE_CATALOG,
-  'record/swapchain',
-  'record/render-graph',
-  'record/target-views',
-  'record/validation',
-  'record/dispatch-plan',
-  'record/uploads',
-  'record/bind-groups',
-  'record/graph-execute',
-  ...RENDER_GRAPH_EXECUTION_PHASE_CATALOG,
-] as const;
-
-export type RenderRecordPhase = (typeof RENDER_RECORD_PHASE_CATALOG)[number];
-
-export const RENDER_PHASE_CATALOG = [
-  'extract',
-  'bind-groups',
-  'features',
-  'sort',
-  'record',
-  ...RENDER_RECORD_PHASE_CATALOG,
-] as const;
-
-export type RenderPhase = (typeof RENDER_PHASE_CATALOG)[number];
-
-export type RenderPhaseSkipReason =
-  | 'feature-host-unavailable'
-  | 'feature-host-empty'
-  | 'pipeline-state-unavailable'
-  | 'camera-unavailable';
-
-/** First-version options bag (intentionally empty; reserved for v0.1). */
-export interface RendererOptions {
-  /** Producer-owned features installed by the renderer host. */
-  readonly features?: readonly RenderFeature<unknown>[] | undefined;
-  /** Explicit profiler capability shared by App and Render. */
-  readonly profiler?: Profiler | undefined;
-  /** Explicit, Render-owned membership timing capability. Omitted means zero timing work. */
-  readonly membershipTiming?: MembershipTimingOptions | undefined;
-  /** @internal Enables producer-owned shadow markers for an active RHI capture. */
-  readonly debugShadowObservation?: boolean | undefined;
-  // feat-20260608-create-app-param-surface-trim / M1 / AC-02: `clearColor`
-  // was deleted as a one-cut breaking change (AGENTS.md Change stance +
-  // requirements constraint #1: no deprecation window, no shim). Scene
-  // clear color now lives on the Camera entity (`clearColor`, an inline
-  // array<f32,4> column as of feat-20260709 M3); zero-Camera fallback uses
-  // `ZERO_CAMERA_CLEAR_FALLBACK = [0, 0, 0, 1]` from
-  // `render-system-record`. AI users that pass `{ clearColor: [...] }` on
-  // RendererOptions still get a TS2353 excess-property error at compile time.
-  //
-  // feat-20260608-create-app-param-surface-trim / M2 / AC-06 + D-3:
-  // `shaderManifestUrl` was deleted from RendererOptions and moved to
-  // the third-arg `BundlerOptions` (build-tool injection channel). The
-  // fallback literal '/shaders/manifest.json' stays at the createRenderer
-  // body site (D-2 q5-A) so the LO 1.1 zero-config takeoff path keeps
-  // working without any explicit injection. AI users that pass
-  // `{ shaderManifestUrl: '...' }` to RendererOptions get a TS2353
-  // excess-property error at compile time pointing them to the third
-  // arg (charter P1 progressive disclosure -- the message names
-  // BundlerOptions, not a free-form string).
-  /**
-   * D-S1 single-point exemption channel (feat-20260508-rhi-surface-completion
-   * / w9): raw GPUDevice used by the GPUCanvasContext.configure({device})
-   * path. GPUCanvasContext is outside the RHI surface (spec couples context
-   * to canvas, not GPUDevice), so the raw GPUDevice is injected through
-   * RendererOptions.rawDeviceForContextConfigure. apps/hello/triangle/src/main.ts:96
-   * captures the raw device via _internal_getRawDevice and passes it in;
-   * every other engine path goes through the RHI interface.
-   *
-   * Accepted forms:
-   *   - direct value (unknown)              - raw GPUDevice already captured
-   *   - thunk `() => unknown | undefined`   - lazy capture, evaluated AFTER
-   *     createRenderer's internal rhi.requestDevice settles (lets callers
-   *     wrap requestDevice to capture the raw device transparently)
-   *
-   * Type intentionally unknown: keeps the RHI surface free of raw GPUDevice
-   * typing; webgpu-backend internally casts to GPUDevice.
-   */
-  readonly rawDeviceForContextConfigure?: unknown | (() => unknown | undefined);
-  /**
-   * M3 D-P4 escape hatch (feat-20260511-rhi-wgpu-impl): explicit
-   * `RhiInstance` injection bypasses the dynamic-import auto-select
-   * facade. When set, `createRenderer` uses this instance verbatim and
-   * neither `@forgeax/engine-rhi-webgpu` nor `@forgeax/engine-rhi-wgpu` is imported
-   * dynamically (charter proposition 5 discoverable opt-in /
-   * plan-strategy §6 M3 + §7.4 escape hatch + Bevy
-   * `RenderCreation::Manual` partial equivalent).
-   *
-   * Typical use cases:
-   *   - Testing / debugging — inject a deterministic stub.
-   *   - Pinning a specific backend (e.g. `@forgeax/engine-rhi-wgpu` even when
-   *     `navigator.gpu` is present, for cross-shim regression tests).
-   *   - Advanced AI users implementing their own `RhiInstance` shim.
-   *
-   * AI users who want the default behaviour leave this field omitted;
-   * `navigator.gpu` presence/absence drives the dynamic import (see the
-   * `createRenderer` JSDoc for the full auto-select decision tree).
-   */
-  readonly rhi?: RhiInstance | undefined;
-  /** Runtime-owned typed instrumentation callbacks for optional RHI capture. */
-  readonly rhiInstrumentation?:
-    | import('./renderer/backend-selection').RhiBackendInstrumentation
-    | undefined;
-}
-
-/**
- * Public Renderer surface. The concrete class is constructed by
- * `createRenderer(canvas, options?)`; callers never instantiate this directly.
- *
- * ECS render bridge error tier table (D-S3 / D-S4 / D-S6 / D-S7 / D-S8):
- *
- * | Path | Behaviour | onError fired? |
- * |:--|:--|:--|
- * | `ready` step 1 manifest load fails | settles err (`ShaderError 'manifest-malformed'` / `'shader-not-found'`) | no — surfaced through `await renderer.ready` |
- * | `ready` step 2 pipeline compile fails | settles err (`RhiError 'shader-compile-failed'` / `'feature-not-enabled'` / `'limit-exceeded'`) | no — surfaced through ready |
- * | `ready` step 3 asset upload fails | settles err (`RhiError 'limit-exceeded'` / `'webgpu-runtime-error'`) | no — surfaced through ready |
- * | `draw([world], { cameraOwner: 0, resourceOwner: 0 })` before `ready` settles (D-S4) | frame skipped | yes — `'rhi-not-available'` |
- * | RenderSystem 0 Camera | frame skipped | yes — `'render-system-no-camera'` |
- * | RenderSystem N>1 Camera | first archetype hit rendered | yes — `'render-system-multi-camera'` |
- * | RenderSystem N>1 DirectionalLight | first archetype hit used | yes — `'render-system-multi-light'` |
- * | RenderSystem 0 DirectionalLight | unlit fallback (intensity = 0) | no — D-Q7 softening |
- * | RenderSystem 0 renderables (Camera entity only) | clear pass executed; canvas painted with `Camera.clearColor`; no geometry submitted | no — D-Q7 softening |
- * | RenderSystem all renderables fail asset-not-found | clear pass executed; per-entity `'asset-not-found'` fires for each unregistered handle | yes — per entity |
- * | RenderSystem entity missing Transform / MeshRenderer | default value used | no — D-Q7 softening |
- * | RenderSystem unregistered `MeshFilter.assetHandle` | entity skipped | yes — `'asset-not-found'` (`detail = { assetHandle }`) |
- * | RenderSystem internal exception (mat4 NaN / GPU bounds) | frame skipped + retry next frame | yes — `'webgpu-runtime-error'` (`detail = { error }`) |
- */
-export interface Renderer {
-  /** Opaque backend marker (K-4). */
-  readonly backend: RendererBackend;
-  /**
-   * Captured RhiDevice handle. The forgeax RhiDevice the engine created
-   * internally via `rhi.requestAdapter() -> adapter.requestDevice()`.
-   * AI users read through this accessor instead of monkey-patching
-   * `rhi.requestAdapter` to capture the device handle.
-   */
-  readonly device: RhiDevice;
-  /**
-   * @internal
-   *
-   * Shader-module creation must stay on the backend pack selected while the
-   * renderer was assembled. Engine-owned extensions (debug-draw is the
-   * current consumer) use this seam instead of importing a concrete RHI
-   * module again; a second bundled rhi-webgpu copy cannot recognize the
-   * renderer's opaque device handle.
-   */
-  readonly _internal_createShaderModule: CreateShaderModule;
-  /**
-   * Instance-per-engine ShaderRegistry: on first access this lazy property
-   * constructs a `ShaderRegistry({ device, manifestUrl })` instance;
-   * subsequent accesses return the same instance. Callers must
-   * `await shader.loadManifest()` before they can call `shader.get(hash)`.
-   */
-  readonly shader: ShaderRegistry;
-  /**
-   * App-owned `AssetRegistry` for GUID loads. Geometry payloads become
-   * World shared references at the consumer boundary.
-   * or register custom meshes via `renderer.assets.register(asset).unwrap()`.
-   */
-  readonly assets: RenderAssetPort;
-  /**
-   * feat-20260527-sprite-nineslice M4 / w16 (D-5 + AC-16): per-Renderer
-   * metrics counter for runtime-time soft signals.
-   *
-   * AI users read `renderer.metrics.snapshot()['<feature>.<event>']` to observe
-   * events the engine surfaces without a `console.warn` flood (charter P3:
-   * machine-readable counters over text). Two methods compose the surface:
-   *
-   *   | Method                  | Purpose                                  |
-   *   |:------------------------|:-----------------------------------------|
-   *   | `increment(name)`       | Engine-internal: bump counter for `name`.|
-   *   | `snapshot()`            | AI-user-facing: read all counters.       |
-   *   | `reset()`               | Test isolation: drop every counter.      |
-   *
-   * Currently surfaced counters (closed namespace, see `EngineMetrics`
-   * JSDoc):
-   *
-   *   - `nineslice.scale-too-small`            (AC-16, w17 end-to-end)
-   *   - `nineslice.tile-needs-repeat-sampler`  (D-9, w18 register-time soft-warn)
-   *
-   * Multi-Renderer isolation: each Renderer instance owns its own EngineMetrics
-   * (D-5 candidate 1) so per-test counters never bleed across renderers.
-   */
-  readonly metrics: EngineMetrics;
-  /**
-   * feat-20260601-gpu-resource-store-extraction M1: the GPU residency store.
-   * `renderer.assets` keeps the CPU POD registry; `renderer.store` owns the
-   * GPU resource lifecycle. Render-path texture / mesh residency is pulled
-   * lazily via `store.ensureResident`. The equirect-to-cubemap IBL projection
-   * is engine internals (feat-20260630 D-3): AI users declare
-   * `Skylight{equirect}` and the record arm drives the projection; there is no
-   * user-facing upload call. The store holds no AssetRegistry reference (D-2);
-   * callers pass the source POD fetched from `renderer.assets`.
-   */
-  // biome-ignore lint/suspicious/noExplicitAny: GPU store is runtime-owned and opaque at the public seam.
-  readonly store: any;
-  /**
-   * Replace bytes in a resident dynamic mesh while preserving its layout,
-   * index format, counts, topology, submeshes, and allocation sizes.
-   */
-  updateMesh(
-    handle: Handle<'MeshAsset', 'shared'>,
-    vertices: Float32Array,
-    indices: Uint16Array | Uint32Array | undefined,
-    worldId?: number,
-    submeshes?: readonly Submesh[],
-  ): Result<void, MeshUpdateError | RhiError>;
-  /**
-   * Replace one contiguous vertex range. The range size is expressed in
-   * vertices; the resident mesh metadata supplies the byte stride.
-   */
-  updateMeshVertexRange(
-    handle: Handle<'MeshAsset', 'shared'>,
-    vertices: Float32Array,
-    firstVertex: number,
-    vertexCount: number,
-    worldId?: number,
-  ): Result<void, MeshUpdateError | RhiError>;
-  /**
-   * V-2 first-class input shim (plan-strategy D-2 + AC-09 — feat-20260519).
-   *
-   * Curried `(world: World) => InputSnapshot | undefined` reader: a thin
-   * facade over `world.getResource<InputSnapshot>('InputSnapshot')`.
-   *
-   * Charter P5 producer/consumer split: the renderer never holds a World
-   * reference; the World is supplied per call so the renderer lifecycle
-   * remains decoupled from the World lifecycle.
-   *
-   * Returns `undefined` when no InputSnapshot Resource is registered on
-   * the World (charter P3: empty signal is the signal).
-   */
-  readonly input: {
-    snapshot(world: World): InputSnapshot | undefined;
-  };
-  /**
-   * Initialization barrier (D-S3 — feat-20260509-ecs-render-bridge-mvp).
-   *
-   * Resolves only after three steps complete, in strict serial order:
-   *   1. `shader.loadManifest()` — fetch + parse manifest.json.
-   *   2. PBR pipeline compile — `createShaderModule` + 3x
-   *      `createBindGroupLayout` (view / material / mesh-array) +
-   *      `createPipelineLayout` + `createRenderPipeline`.
-   *   3. Render-owned builtin mesh upload — `createBuffer` +
-   *      `queue.writeBuffer` for cube + triangle vertex / index buffers.
-   * Any step failure settles with `Result.err(RhiError)`.
-   *
-   * Calling `draw([world], { cameraOwner: 0, resourceOwner: 0 })` before `ready` settles fires
-   * `onError` with `'rhi-not-available'` and skips the frame (D-S4).
-   *
-   * @example
-   *   const renderer = await createRenderer(canvas);
-   *   const ready = await renderer.ready;
-   *   if (!ready.ok) throw ready.error;
-   *   const attached = renderer.attachWorld(world);
-   *   if (!attached.ok) throw attached.error;
-   *   const updated = world.update(1 / 60);
-   *   if (!updated.ok) throw updated.error;
-   *   const r = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-   *   if (!r.ok) console.error(r.error);
-   */
-  readonly ready: Promise<RenderResult<void, RhiError>>;
-  /** Backend-aware membership timing, present only when explicitly requested. */
-  readonly membershipTiming?: MembershipTimingController;
-  /**
-   * Attach renderer-required derived-state systems to a World once.
-   *
-   * The systems run inside `World.update()`; `draw()` and its extract stage
-   * remain read-only consumers of the resulting World state. Reattaching the
-   * same World to this Renderer is a no-op.
-   */
-  attachWorld(world: World): RenderResult<void, RhiError>;
-  /**
-   * Release this Renderer's derived-state ownership of one World.
-   * Idempotent; after detach, draw rejects the World until it is attached and
-   * successfully updated again.
-   */
-  detachWorld(world: World): void;
-  /**
-   * Draw one frame for the supplied World (D-S2 + K-4 rewrite).
-   *
-   * RenderSystem (engine-internal phase) walks the World query graph
-   * across three stages — Extract / Prepare / Record — and submits a
-   * single GPU command buffer per call. Per-call behaviour is governed by
-   * the error tier table on `Renderer` (D-S4..D-S8); AI users observe
-   * fan-out through `onError` and frame-skip semantics through the same
-   * structured RhiError closed union.
-   *
-   * @example Spawn-then-draw:
-   *   const world = new World();
-   *   world.spawn(
-   *     { component: Transform, data: cameraTransform },
-   *     { component: Camera, data: cameraParams },
-   *   );
-   *   world.spawn({
-   *     component: MeshFilter,
-   *     data: { assetHandle: cubeMesh },
-   *   });
-   *   const ready = await renderer.ready;
-   *   if (!ready.ok) throw ready.error;
-   *   const attached = renderer.attachWorld(world);
-   *   if (!attached.ok) throw attached.error;
-   *   const updated = world.update(1 / 60);
-   *   if (!updated.ok) throw updated.error;
-   *   const r = renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-   *   if (!r.ok) handleError(r.error);
-   *
-   * w24 — Result<void, RhiError> shape: returns Result.ok(undefined) on
-   * success; Result.err(rhiError) on facade-level catch (transient runtime
-   * exception). Per-stage RhiError continues to fan out through `onError`
-   * (charter proposition 5; D-P6 dual-channel preserved). The Result return
-   * is the synchronous facade-level summary; AI users can ignore it or
-   * branch on `.ok` (biome lint warns on unhandled return).
-   *
-   * feat-20260708-composited-multi-world-rendering M3 (AC-01 / AC-02 / D-5),
-   * extended by feat-20260709-editor-world-partition M1 / w6: `worlds` is
-   * composited into one frame — renderables + lights merge from every world,
-   * while cameras come from the `cameraOwner` world and singleton resources
-   * (skylight / skybox / postProcessParams) come from the `resourceOwner`
-   * world. {@link DrawOwnerOptions} requires both authorities explicitly as
-   * `{ cameraOwner, resourceOwner }`.
-   * Single-world users pass `draw([world], { cameraOwner: 0, resourceOwner: 0 })` (the app frame-loop
-   * does this wrapping transparently). Entry validation returns `Result.err`
-   * before any extract on:
-   *   - empty `worlds`               -> `'render-system-empty-worlds'`
-   *   - `cameraOwner` out of range   -> `'render-system-owner-out-of-range'`
-   *     (`.detail = { role: 'camera', owner, worldCount }`)
-   *   - `resourceOwner` out of range -> `'render-system-owner-out-of-range'`
-   *     (`.detail = { role: 'resource', owner, worldCount }`)
-   * cameraOwner is validated before resourceOwner (first offender wins).
-   *
-   * @example Composite two worlds (owner supplies both camera + resources):
-   *   const scene = new World();   // camera + lights + geometry
-   *   const overlay = new World(); // extra geometry, no camera
-   *   const r = renderer.draw([scene, overlay], { cameraOwner: 0, resourceOwner: 0 });
-   *   if (!r.ok) handleError(r.error);
-   *
-   * @example Split owners (scene camera, editor-overlay resources):
-   *   const r = renderer.draw([scene, editor], { cameraOwner: 0, resourceOwner: 1 });
-   */
-  draw(worlds: readonly World[], options: DrawOwnerOptions): RenderResult<void, RhiError>;
-  /**
-   * Observe the producer-owned linear HDR attachment from the most recently
-   * completed frame. This never reads the final display canvas.
-   */
-  observeCurrentFrame(
-    options: FrameObservationOptions,
-  ): Promise<RenderResult<FrameObservation, ObservationUnavailableError>>;
-  /**
-   * Read the canvas's current pixel contents back into an RGBA Uint8Array.
-   *
-   * Reads the WebGPU canvas's backing image via the lowest-common-
-   * denominator browser path: `createImageBitmap → OffscreenCanvas 2D
-   * drawImage → getImageData`. The WebGPU canvas's GPUTexture is not
-   * directly readable via `getImageData`, so this OffscreenCanvas bounce
-   * is the canonical browser path; AI users avoid hand-rolling the
-   * recipe (charter proposition 5 consistent abstraction).
-   *
-   * Returns top-left origin RGBA (the natural getImageData convention).
-   * Apps that need bottom-left origin (parity comparisons against
-   * `gl.readPixels`) Y-flip the result locally.
-   *
-   * AI users typically: `renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 })` to update the canvas,
-   * then `await renderer.readPixels()` to sample. Output buffer length
-   * is `canvas.width * canvas.height * 4`.
-   *
-   * | Path | Behavior |
-   * |:--|:--|
-   * | OffscreenCanvas + 2D ctx all available | `Result.ok(Uint8Array)` |
-   * | OffscreenCanvas / 2D ctx unavailable | `Result.err(RhiError 'webgpu-runtime-error')` (`detail.error: string`) |
-   * | `createImageBitmap` throws | `Result.err(RhiError 'webgpu-runtime-error')` (`detail.error: string`) |
-   *
-   * dawn-node smoke harness path uses raw RHI (`device.queue.copyTexture
-   * ToBuffer + mapAsync`) directly against an offscreen `GPUTexture` —
-   * that path has no canvas and does not collapse with this method.
-   * Future RHI-level readback abstraction tracked separately.
-   */
-  readPixels(): Promise<RenderResult<Uint8Array, RhiError>>;
-  /**
-   * Relinquish the canvas presentation surface while preserving the Renderer,
-   * AssetRegistry, and CPU-side render declarations. Idempotent. Draws fail
-   * closed until restoreSurface() succeeds.
-   */
-  releaseSurface(): RenderResult<void, RhiError>;
-  /** Re-enable presentation on the same canvas/device after releaseSurface(). */
-  restoreSurface(): RenderResult<void, RhiError>;
-  /**
-   * Release renderer-owned resources + detach listeners. Idempotent.
-   *
-   * @placeholder fix-f6: M2/M3 placeholder form — the `RhiDevice` interface
-   * does not yet expose a `destroy()` entry, so the current implementation
-   * only detaches the listener registry + blocks subsequent `draw()` calls;
-   * the underlying GPU resources are reclaimed naturally via the spec
-   * pass-through layer (`device.lost` pass-through + browser GC). The
-   * explicit `device.destroy()` path will be closed out in a later RHI
-   * interface extension. See the `Renderer.dispose` row of the "API index"
-   * in `packages/engine/README.md` plus plan-strategy §6 NOTE on M3 scope.
-   */
-  dispose(): void;
-  /** Register a notify-only listener for device-loss. Returns unsubscribe fn. */
-  onLost(listener: RendererLostListener): () => void;
-  /**
-   * Register an RHI creation-time error listener (fix-f2 / charter
-   * proposition 4 explicit-failure delivery).
-   *
-   * @returns unsubscribe fn
-   */
-  onError(listener: RendererErrorListener): () => void;
-  /**
-   * Pull-style health snapshot. Returns the canonical `HealthSnapshot` from the
-   * registry's last-fired state, or the alive baseline when never fired. No
-   * second store — derived from `HealthListenerRegistry.getLastSnapshot()` per
-   * D-4 SSOT.
-   *
-   * AI users consume via `switch (snap.reason)`; TS narrows `snap.detail` to
-   * the per-reason detail type without `as` casts.
-   */
-  health(): HealthSnapshot;
-  /**
-   * Attempt a single idempotent device rebuild (feat-20260622-s5 M3).
-   *
-   * Only acts in the `device-lost` health state; `alive` returns
-   * `recover-not-needed` (also returned after a successful rebuild — the
-   * renderer is alive again, so a second recover() is a no-op signal).
-   * Rebuild sequence: `gpuStore.destroyAll()` + `context.unconfigure()` ->
-   * clear the render-graph pendingDestroy queue (B-2) -> re-acquire device via
-   * the same backend pack (`requestAdapter` -> `requestDevice`) -> rebuild
-   * Shader/Pipeline -> re-attach the device.lost fan-out -> `fire('alive')`.
-   * CPU POD caches (AssetRegistry catalog/payload, pack cache) survive; only
-   * GPU resources are released and re-uploaded on the next draw via
-   * `ensureResident` (A-AC-12).
-   *
-   * Async because device acquisition is async (`requestAdapter` /
-   * `requestDevice`). A single attempt: no retry loop, no backoff, no timer
-   * (A-OOS-1). On failure resolves `Result.err` (`recover-adapter-unavailable`
-   * / `recover-device-unavailable`) and leaves `health().reason ===
-   * 'device-lost'` — recover() never fakes the renderer back to `alive`
-   * (A-AC-07). The host owns the retry cadence (call recover() again after a
-   * host-chosen delay).
-   */
-  recover(): Promise<Result<void, RecoverError>>;
-  /**
-   * Push-style health subscription with unsubscribe.
-   *
-   * Delegates to `HealthListenerRegistry.add(cb)` — late-attach replay fires
-   * the callback immediately when a snapshot has already been emitted, so
-   * late-subscribing callers still see the current state (AC-07).
-   *
-   * @returns unsubscribe function
-   */
-  onHealthChange(cb: HealthChangeListener): () => void;
-  /**
-   * feat-20260520-directional-light-shadow-mapping M1c / w8:
-   * debugReadback reads the shadow depth texture (depth32float) into a 5-
-   * pixel POD { center, corners: {tl,tr,bl,br}, mapSize }. Uses
-   * copyTextureToBuffer + mapAsync + Float32Array direct read. Returns null
-   * when no shadow RT is allocated (shadow pass hasn't run yet, or no
-   * DirectionalLight with castShadow).
-   * With cascaded shadows, if the legacy center/corner sentinels are all
-   * clear, `center` is the nearest written texel in cascade 0 so the POD
-   * still exposes the owner that populated the atlas.
-   *
-   * AI users consume per-pixel depth values as [0,1] floats; no 24-in-32
-   * unorm decode needed (depth32float, D-2 round-3).
-   */
-  debugReadback?(): Promise<{
-    readonly center: number;
-    readonly corners: {
-      readonly tl: number;
-      readonly tr: number;
-      readonly bl: number;
-      readonly br: number;
-    };
-    readonly mapSize: number;
-  } | null>;
-  /**
-   * feat-20260520-directional-light-shadow-mapping M1c / w8:
-   * lights.directionalShadow exposes shadow configuration (mapSize,
-   * lightSpaceMatrix) for Inspector consumption. Null when the renderer
-   * has no active shadow system (shader manifest empty or no
-   * DirectionalLight with castShadow).
-   */
-  readonly directionalShadow?: {
-    readonly mapSize: number;
-    readonly lightSpaceMatrix: readonly number[] | null;
-  } | null;
-  /**
-   * feat-20260520-directional-light-shadow-mapping M2 / w14 (AC-12):
-   * debugSampleShadowFactor runs a producer-owned GPU probe for world-space
-   * positions. It reads the same shadow atlas and PCF path as the directional
-   * receiver, then returns the factor plus the selected cascade and the center
-   * atlas texel's raw depth. The extra fields keep the forensic readback tied
-   * to the actual sampled resource rather than a CPU reconstruction.
-   *
-   * Returns null when the probe pipeline is not compiled (empty shader
-   * manifest). When no shadow caster is active (lightSpaceMatrix absent),
-   * returns all-1.0 (fully lit) — the caller can distinguish "no shadow
-   * data" from "probe unavailable".
-   * Each result carries `shadowFactor` (1 = lit, 0 = fully shadowed),
-   * `sampledDepth` (the center texel loaded from the active atlas),
-   * `cascadeIndex` (0..3, or -1 when no cascade contains the position), and
-   * `receiverDepth` (the projected depth used by the probe comparison), and
-   * `bias` (the exact depth bias used by the probe comparison).
-   */
-  debugSampleShadowFactor?(
-    worldPositions: ReadonlyArray<readonly [number, number, number]>,
-    options?: {
-      /** Surface normals for the supplied receiver positions. Defaults to floor-up. */
-      readonly surfaceNormals?: ReadonlyArray<readonly [number, number, number]>;
-    },
-  ): Promise<ReadonlyArray<{
-    readonly shadowFactor: number;
-    readonly sampledDepth: number;
-    readonly cascadeIndex: number;
-    readonly receiverDepth: number;
-    readonly bias: number;
-  }> | null>;
-  /**
-   * feat-20260528-frustum-culling M5 / w14: per-frame frustum-culling
-   * statistics collected during the extract stage. `culled` is the count
-   * of entities removed from renderables by frustum culling; `total` is
-   * the count that reached the culling decision point. Both are zero
-   * before the first `draw([world], { cameraOwner: 0, resourceOwner: 0 })` or when no `MeshRenderer` entities
-   * are in the world.
-   */
-  readonly frustumStats: { readonly culled: number; readonly total: number };
-  /**
-   * Per-frame candidate entities rejected by author visibility before resource
-   * parsing. Zero before the first draw or when no candidates are hidden.
-   */
-  readonly visibilityStats: { readonly explicitlyHidden: number };
-  /** Persistent CPU scene cursor, rebuild, and delta counters. */
-  readonly renderScene: RenderSceneInspection;
-  /** Mesh-slot provenance and active structured diagnostics from the last frame. */
-  readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
-  /**
-   * feat-20260531-bloom-first-declarative-render-graph-pass M4 fix-up w19:
-   * per-frame render-graph pass names in declaration order. Empty array
-   * before the first `draw([world], { cameraOwner: 0, resourceOwner: 0 })` call; populated lazily when the
-   * per-frame graph is built. Read-only introspection surface so smoke
-   * tests can assert the declarative pass chain is wired without reaching
-   * into engine internals.
-   */
-  readonly perFramePassNames: readonly string[];
-  /**
-   * Return the host-owned lifecycle snapshot for every registered feature.
-   *
-   * Consumers branch on `status` and `latestError?.code`; they do not parse
-   * log text or reach into the feature host. A failed feature retries on the
-   * next eligible frame, a disabled feature waits for `recover()`, and a
-   * disposed feature is terminal. Pipeline switches preserve registrations
-   * while rebuilding the active graph.
-   */
-  renderFeatureDiagnostics(): readonly RenderFeatureDiagnostics[];
-  /** Subscribe to feature lifecycle changes without polling every render frame. */
-  subscribeRenderFeatureDiagnostics(listener: () => void): () => void;
-  /** Subscribe after a `draw()` invocation reaches queue submission. */
-  subscribeFrameEnd(listener: () => void): () => void;
-  /**
-   * Install a feature after the renderer is ready. The renderer keeps feature
-   * identity and lifecycle ownership in the same host as boot-time features;
-   * installing the same object twice is a no-op, while a different object with
-   * the same identity returns `render-feature-registration-conflict`.
-   */
-  installRenderFeature(feature: RenderFeature<unknown>): Promise<RenderResult<void, RenderError>>;
-  /** Wait for submitted GPU work, then reversibly remove one installed feature. */
-  uninstallRenderFeature(feature: RenderFeature<unknown>): Promise<RenderResult<void, RenderError>>;
-  /**
-   * feat-20260531-per-frame-bind-group-cache M1 / w4: per-frame
-   * createBindGroup counter. Reset to 0 on every `draw([world], { cameraOwner: 0, resourceOwner: 0 })` call,
-   * bumped per cache-miss in the record stage. Stable-frame AC-03
-   * asserts `createBindGroup === 0` when all bind groups are cached.
-   * AI users read this getter to verify cache effectiveness without
-   * inspecting internal cache state.
-   */
-  readonly bindGroupCounts: { readonly createBindGroup: number; readonly keys: readonly string[] };
-  /**
-   * feat-20260601-customizable-render-pipeline-seam M1 / w8: register a render-pipeline
-   * logic under `id` (engine builtins use the `forgeax::` prefix; user pipelines use
-   * `<package>::<id>`). Same-id re-register throws `PipelineError`
-   * (`'pipeline-already-registered'`) - programmer-error fail-fast. Sits alongside
-   * `shader` / `assets` / `store` as a public capability surface (charter F1 IDE
-   * autocomplete on `renderer.`). Forwards 1:1 to the RenderSystem layer.
-   */
-  registerPipeline(id: string, impl: RenderPipeline): void;
-  /**
-   * feat-20260601-customizable-render-pipeline-seam M1 / w8 (D-19): install the pipeline
-   * described by a `RenderPipelineAsset` POD (built inline, no registration step). On an
-   * unregistered `pipelineId` returns `Result.err(PipelineError{code:'pipeline-not-found'})`;
-   * AI users consume `err.code` by property access. On success the next `draw` rebuilds the
-   * per-frame graph through the newly installed pipeline (runtime hot-swap).
-   */
-  installPipeline(asset: RenderPipelineAsset): Result<() => void, PipelineError>;
-  /**
-   * feat-20260604-resource-owning-render-graph-and-fullscreen-postpr M2 / F-2 fix-up:
-   * fullscreen post-process registration channel. `postProcess.register(id, entry)`
-   * registers a `PostProcessShaderEntry` under `id`; the dispatcher in
-   * `addFullscreenPass({shader: id})` looks it up via `runtime.lookupPostProcess`.
-   * Same-id re-register throws `PostProcessError({code:'post-process-already-registered'})`
-   * (programmer-error fail-fast, mirrors `registerPipeline`). An unregistered id
-   * referenced by `addFullscreenPass` throws `PostProcessError({code:'post-process-not-found'})`
-   * from the dispatcher. Sits alongside `registerPipeline` / `installPipeline` as a
-   * public capability surface (charter F1: IDE autocomplete on `renderer.postProcess.`).
-   * Forwards 1:1 to the RenderSystem layer (plan-strategy D-D).
-   */
-  readonly postProcess: {
-    register(
-      id: string,
-      entry: import('./fullscreen-post-process-pass').PostProcessShaderEntry,
-    ): () => void;
-  };
-  /**
-   * feat-20260612-skin-palette-per-frame-upload M1 / m1-1: test-only access
-   * hatch returning the internal `PipelineState` closure variable (or `null`
-   * before `await renderer.ready` settles). Mirrors the existing
-   * `_internal_getRawDevice` pattern so unit tests can assert PipelineState
-   * field shape (e.g. `skinPaletteAllocator` presence after stub retirement)
-   * without re-routing through `RenderSystem`. Public surface stays opaque:
-   * the return is widened to `unknown`, callers cast at the test boundary.
-   * @internal
-   */
-  _internal_getPipelineState(): unknown;
-}
-
-// ────────────────────────────────────────────────────────────────────────────
-// Renderer health / recover surface (feat-20260621-renderer-health-recover-skeleton M1)
-// ────────────────────────────────────────────────────────────────────────────
-
-/**
- * Closed union of renderer health states.
- *
- * 3 members per plan-strategy D-1:
- *   - `'alive'` — healthy baseline (registry not yet fired)
- *   - `'device-lost'` — device loss detected
- *   - `'internal-fault'` — internal renderer fault
- *
- * AI users exhaustively switch on `HealthReason` without default; TS guards
- * completeness.
- */
-export type HealthReason = 'alive' | 'device-lost' | 'internal-fault';
-
-/** Detail for `HealthReason 'device-lost'`. */
-export interface HealthDetailDeviceLost {
-  readonly lostReason: 'unknown' | 'destroyed';
-  readonly message: string;
-}
-
-/** Detail for `HealthReason 'internal-fault'`. */
-export interface HealthDetailInternalFault {
-  readonly message: string;
-}
-
-/**
- * Pull-style health snapshot — discriminated union by `reason`.
- *
- * Per plan-strategy D-2: `switch(snap.reason)` narrows `snap.detail` to the
- * per-reason detail type automatically, with zero `as` casts. `alive` has no
- * `.detail` field; `device-lost` / `internal-fault` have a required `.detail`
- * of the respective variant.
- *
- *   - `recoverable` — derived from `reason` via `deriveRecoverable`
- */
-export type HealthSnapshot =
-  | { readonly reason: 'alive'; readonly recoverable: boolean }
-  | {
-      readonly reason: 'device-lost';
-      readonly detail: HealthDetailDeviceLost;
-      readonly recoverable: boolean;
-    }
-  | {
-      readonly reason: 'internal-fault';
-      readonly detail: HealthDetailInternalFault;
-      readonly recoverable: boolean;
-    };
-
-/**
- * Maps `HealthReason` to recoverable boolean per the derive table
- * (requirements section "range"):
- *
- *   | reason         | recoverable |
- *   |:---------------|:-----------|
- *   | `'alive'`      | false       |
- *   | `'device-lost'`| true        |
- *   | `'internal-fault'` | false   |
- */
-/** Callback type for `Renderer.onHealthChange`. */
-export type HealthChangeListener = (snapshot: HealthSnapshot) => void;
-
-// ────────────────────────────────────────────────────────────────────────────
-// Internal — shared listener-registry helper (used by both backends).
-// ────────────────────────────────────────────────────────────────────────────
-
-/**
- * Internal helper: a tiny notify-only event registry. Not exported on the
- * public surface (the explicit `./internal` export is locked in package.json).
- */
-/**
- * Internal helper: fan-out registry for the `Renderer.onError` channel (fix-f2
- * delivers the charter proposition 4 explicit-failure red line).
- *
- * Difference from `LostListenerRegistry`: this registry fans out structured
- * structured error objects from the fan-out families composed in
- * `RendererError` — both carrying the `.code` closed-union discriminant + the
- * three fields `.expected` / `.hint` + optional `.detail`. Late-attach replay
- * behavior is identical — errors that fired before dispose are immediately
- * replayed to any subsequent `add`.
- */
-/**
- * Internal helper: fan-out registry for the `Renderer.onHealthChange` channel
- * (feat-20260621-renderer-health-recover-skeleton M1).
- *
- * 3rd isomorph of the `LostListenerRegistry` / `RhiErrorListenerRegistry` pattern
- * (plan-strategy D-5 / OOS-5: do not extract a generic base class). Replicates:
- *   - `fired` / `lastSnapshot` for late-attach replay
- *   - `add(listener)` returns unsubscribe function
- *   - `fire(snapshot)` with try/catch isolation (console.error on throw)
- *   - `clear()` detaches listeners, does not reset `fired` / `lastSnapshot`
- *   - `getLastSnapshot()` — public getter returning last fired snapshot or
- *     `{ reason: 'alive', recoverable: false }` baseline
- */