@forgeax/engine-render 0.1.2

package/src/components/sprite-region-override.ts

@@ -0,0 +1,106 @@
+// @forgeax/engine-runtime - SpriteRegionOverride (per-entity UV region
+// override, sprite-only).
+//
+// Schema: 1 fixed-length array column `region: 'array<f32, 4>'` carrying a
+// packed UV sub-rectangle `[uMin, vMin, uW, vH]`. The fixed `4` length is
+// enforced at compile time by the ECS schema-vocab keyword
+// `'array<T, N>'` (D-6: prefer compile-time enforcement over runtime
+// fail-fast for length-bound contracts).
+//
+// Why an entity-side override component instead of a render parameter on
+// MaterialRenderer? Plan-strategy section 1 / requirements section 5
+// constraint #1 (Pipeline Isolation R1, M1 ssot): `AssetRegistry` stays
+// append-only / read-only and `MaterialRenderer` schema is frozen.
+// Per-entity render-parameter overrides ride the same rail as Layer /
+// SortKey — one ECS column per entity, read at extract time, never
+// flowing back to the asset.
+//
+// Sprite-only consumption (requirements section 5 constraint #2 + section
+// 7 boundary line 1): `render-system-extract` reads this component ONLY
+// inside the sprite bucket branch (`pipelineTag === 'sprite'` plus the
+// asset-side sprite discriminant). Opaque (`unlit` / `standard`) buckets
+// ignore the column even when the entity happens to carry it; the M3
+// T-15 grep gate
+// (`packages/runtime/src/__tests__/sprite-only-isolation-grep-gate.test.ts`)
+// asserts this file contains zero substring matches against the asset
+// discriminant identifier as a structural lock (charter P5 producer /
+// consumer separation: the component owner never names the asset
+// discriminant directly).
+//
+// Naming: bare `SpriteRegionOverride` (no `Component` suffix per
+// AGENTS.md section Component naming "Single-semantic components drop
+// the Component suffix"). The `Sprite` prefix is intentional — 3D UV
+// region animation lands in a separate component (e.g. future
+// `MaterialRegionOverride`) per OOS-01 to avoid premature 3D
+// generalisation. Plan-strategy section 8 naming convention pins the
+// prefix to make the AC-11 grep gate trivially decidable.
+//
+// @derives `defineComponent` factory (packages/ecs/src/component.ts) —
+//   `'array<f32, 4>'` is on the `SchemaVocabKeyword` whitelist (line ~94
+//   `array<${ManagedArrayElementType}, ${number}>`).
+// @consumes M3 T-16 (`render-system-extract.ts` sprite bucket branch
+//   reads override into `paramSnapshot.region`, post-M3 feat-20260625
+//   ablation -- the pre-ablation per-entity hop through the snapshot
+//   POD layer collapsed into the generic paramSchema-driven path).
+// @produces M4 T-23 (`spriteAnimationTickSystem` writes per-frame UV
+//   slice into `region`).
+//
+// charter mapping: F1 (single-import barrel discovery — joins Layer /
+// SortKey / Transform / SpriteAnimation under a single
+// `from '@forgeax/engine-render'`); P3 (compile-time length=4 lock
+// surfaces mismatched payloads at the TS edge before the column write
+// path observes them); P4 (consistent abstraction — same per-entity
+// override shape AI users already learned for Layer / SortKey).
+//
+// Anchors: plan-strategy section 2 D-6 + section 3.1 SRO + section 4
+// risk R-SCHEMA-2 reaction; plan-tasks.json T-11; research F-5;
+// requirements section AC-01 + section 2.4 + section 5 constraint #2.
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Per-entity sprite UV region override (sprite-only).
+ *
+ * Carries a fixed-length `Float32Array(4)` of `[uMin, vMin, uW, vH]` that
+ * `render-system-extract` reads in the sprite bucket branch and writes
+ * into `paramSnapshot.region`, replacing the asset-side region for
+ * this entity only (feat-20260625 M3 ablation: the prior per-entity POD
+ * indirection collapsed into the generic paramSchema-driven snapshot).
+ * Opaque buckets ignore this component; the AC-11 grep gate keeps the
+ * producer / consumer separation structural (this file never names the
+ * asset-side sprite discriminant identifier).
+ *
+ * Pair with `SpriteAnimation` to drive the override per frame
+ * (sprite-animation-tick system, M4 T-23). Standalone use (manual region
+ * override without animation) is also supported — set the column once and
+ * the next extract picks up the new value.
+ *
+ * Schema-vocab keyword `'array<f32, 4>'` (D-6) — fixed-length 4 is the
+ * compile-time enforcement axis. `Float32Array` payloads with length !== 4
+ * round-trip fewer / more bytes per the underlying BufferPool slot, but
+ * the slot is sized at schema registration time; AI users keep the
+ * payload exactly four-floats wide.
+ *
+ * @example Spawn a sprite entity that displays the right half of an atlas:
+ *   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());
+ *
+ *   world.spawn(
+ *     { component: Transform, data: { pos: [0, 0, 0],
+ *       quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+ *     { component: MeshFilter, data: { assetHandle: quadMesh } },
+ *     { component: MeshRenderer, data: { materials: [spriteMaterial] } },
+ *     { component: SpriteRegionOverride,
+ *       data: { region: new Float32Array([0.5, 0, 0.5, 1]) } },
+ *   );
+ *
+ * @example Update the override at runtime (e.g. flip-frame test):
+ *   world.set(entity, SpriteRegionOverride,
+ *     { region: new Float32Array([0, 0, 1, 1]) }).unwrap();
+ */
+export const SpriteRegionOverride = defineComponent('SpriteRegionOverride', {
+  region: { type: 'array<f32, 4>' },
+});

package/src/components/tile-layer.ts

@@ -0,0 +1,161 @@
+// @forgeax/engine-runtime - TileLayer (one render layer of a Tilemap).
+//
+// Schema (4 fields):
+//   tiles       array<u32>  per-cell tile id (packed Tiled .tmj wire form);
+//                           length == parent.Tilemap.cols * rows.
+//   layerOrder  i32         render-order key (higher = drawn on top).
+//   dirty       u8          0 means clean, non-zero means dirty - the next
+//                           tilemap-chunk-extract-system pass rebuilds derived
+//                           per-cell entities for this layer.
+//   sortScope   u8 (TS:     0 = 'layer'    (default) - terrain semantics:
+//               closed                       every derived entity in this
+//               'layer' |                    layer shares one Layer.value
+//               'per-cell'                   (layerOrder << 20), so the
+//               union)                       whole layer Y-sorts as a single
+//                                            bucket. AI users grep
+//                                            `sortScope: 'layer'` to confirm.
+//                           1 = 'per-cell' - object semantics: each derived
+//                                            entity carries its own foot-Y
+//                                            key; preserves per-cell entity
+//                                            derivation for Y-interleave
+//                                            with sprite entities sharing
+//                                            the same Layer.value.
+//
+//   Storage rationale (D-V-3 R-NEW-1 fallback / round-2): ECS schema does not
+//   yet support `values: ['layer', 'per-cell']` literal-union constraints
+//   on a `'string'` column, so the on-disk shape is `u8` (0/1) but every
+//   AI-facing TS surface (`TileLayerData.sortScope`) is the closed
+//   `'layer' | 'per-cell'` string union. The bridge functions
+//   `encodeSortScope` / `decodeSortScope` are the SSOT for the two-way
+//   mapping (charter F1 — single grep target).
+//
+// Each TileLayer entity attaches to a Tilemap entity via ChildOf (the parent
+// field carries the Tilemap entity). M0 supports multiple TileLayer entities
+// per Tilemap (each rendered as an independent z-ordered layer).
+//
+// charter mapping: F1 (single-import barrel + single grep target for
+// `sortScope`), P1 (progressive disclosure — `'layer'` / `'per-cell'`
+// reads directly without a magic-number table), P3 (dirty flag is
+// explicit - silent re-extraction is forbidden), P4 (handle-free row
+// schema mirrors MeshFilter / MeshRenderer conventions).
+
+import { defineComponent, type EcsError, type EntityHandle, type World } from '@forgeax/engine-ecs';
+import type { Result } from '@forgeax/engine-types';
+
+/**
+ * Closed string-literal union for the TileLayer.sortScope field. AI users
+ * grep `sortScope` and land on this single SSOT type alias; switch
+ * statements over this type are exhaustive without a default arm.
+ *
+ *   - 'layer'    - terrain semantics; whole layer shares one Layer.value
+ *                  bucket and Y-sorts together (chunkIndex is folded into 0).
+ *   - 'per-cell' - object semantics; each derived entity gets its own
+ *                  chunkIndex tiebreak so it can Y-interleave with
+ *                  sprite entities carrying the same Layer.value (e.g. a
+ *                  player sprite riding the same SPRITE_LAYER_VALUE).
+ */
+export type SortScope = 'layer' | 'per-cell';
+
+/**
+ * Bridge: `SortScope` -> on-disk u8. SSOT for the encoding (`'layer'` -> 0,
+ * `'per-cell'` -> 1). The compile-time exhaustive switch guards against
+ * silent drift if the union ever grows; adding a new literal here without
+ * adding its arm fails typecheck (charter P3 — closed unions never default).
+ */
+export function encodeSortScope(scope: SortScope): 0 | 1 {
+  switch (scope) {
+    case 'layer':
+      return 0;
+    case 'per-cell':
+      return 1;
+  }
+}
+
+/**
+ * Bridge: on-disk u8 -> `SortScope`. Defaults to `'layer'` for any value
+ * outside `{0, 1}` (defensive — the column is typed `u8` so out-of-range
+ * values can only appear if a future schema migration loosens the bound;
+ * the default preserves terrain semantics which is the safer of the two).
+ */
+export function decodeSortScope(raw: number | undefined): SortScope {
+  return raw === 1 ? 'per-cell' : 'layer';
+}
+
+/**
+ * Public TileLayer field shape (`world.spawn({ component: TileLayer, data:
+ * { ... } })` payload). `sortScope` is the closed string union surfaced to
+ * AI users; the runtime row encodes it as `u8` via `encodeSortScope` at
+ * spawn time so on-disk storage stays compact.
+ *
+ * Treat as the `TileLayer` data SSOT — `defineComponent` schema below
+ * mirrors it field-for-field with the bridge `sortScope: u8` in place of
+ * the union literal.
+ */
+export interface TileLayerData {
+  readonly tiles: Uint32Array;
+  readonly layerOrder?: number;
+  readonly dirty?: number;
+  readonly sortScope?: SortScope;
+}
+
+/**
+ * TileLayer component (M0 baseline rebuild + round-2 sortScope rename).
+ *
+ * AI users typically spawn a TileLayer + ChildOf pair pointing at an
+ * existing Tilemap entity:
+ *
+ * @example
+ *   const tilesArray = new Uint32Array(cols * rows);
+ *   tilesArray[5 * cols + 7] = 1; // tile id 1 at cell (7, 5)
+ *   world.spawn(
+ *     { component: TileLayer, data: { tiles: tilesArray, layerOrder: 0 } },
+ *     { component: ChildOf,  data: { parent: tilemapEntity } },
+ *   );
+ *
+ * Object-layer variant (Y-interleave with sprite entities):
+ *
+ * > NOTE: schema storage is `u8` (ECS schema does not support
+ * > string-literal-union column constraints; see R-NEW-2). The
+ * > AI-user surface is the closed `SortScope` string union, but
+ * > `world.spawn` requires the numeric encoding — pass through
+ * > `encodeSortScope('per-cell')` rather than the literal string.
+ *
+ * @example
+ *   world.spawn(
+ *     { component: TileLayer, data: {
+ *         tiles: objectTiles,
+ *         layerOrder: 1000,
+ *         sortScope: encodeSortScope('per-cell'),
+ *       } },
+ *     { component: ChildOf, data: { parent: tilemapEntity } },
+ *   );
+ *
+ * Defaults: `layerOrder = 0`, `dirty = 0`, `sortScope = 'layer'` (stored
+ * as `u8 = 0`, i.e. `encodeSortScope('layer')`). `tiles` has no default -
+ * AI users supply the per-cell array at spawn time. To trigger a re-build
+ * after mutating tiles in place, call `markTileLayerDirty(world, layer)`.
+ */
+export const TileLayer = defineComponent('TileLayer', {
+  tiles: { type: 'array<u32>' },
+  layerOrder: { type: 'i32', default: 0 },
+  dirty: { type: 'u8', default: 0 },
+  sortScope: { type: 'u8', default: 0 },
+});
+
+/**
+ * Mark a TileLayer entity dirty so the next `tilemapChunkExtractSystem`
+ * pass purges and re-spawns its derived per-cell entities. Use this after
+ * mutating `TileLayer.tiles` (e.g. an in-place patch via a column view).
+ *
+ * Returns the underlying ECS write result - on `err` branch the caller
+ * can read `.code` to recover (`'stale-entity'` if the layer was
+ * despawned, `'component-not-present'` if the entity is missing the
+ * TileLayer column; both kebab-case literals are members of the closed
+ * `EcsErrorCode` union).
+ */
+export function markTileLayerDirty(
+  world: World,
+  layerEntity: EntityHandle,
+): Result<void, EcsError> {
+  return world.set(layerEntity, TileLayer, { dirty: 1 });
+}

package/src/components/tilemap.ts

@@ -0,0 +1,48 @@
+// @forgeax/engine-runtime - Tilemap (grid + tileset reference).
+//
+// Schema (5 fields):
+//   cols       u32               total grid columns
+//   rows       u32               total grid rows
+//   tileSize   array<f32, 2>     per-cell world [width, height] (default [1, 1];
+//                                feat-20260709 M3: collapsed from the tileSizeX
+//                                / tileSizeY scalar pair into one inline column)
+//   chunkSize  u32               per-chunk axis-length in cells (default 16)
+//   tileset    string                durable TilesetAsset GUID
+//
+// Naming: single-semantic Tilemap (AGENTS.md §Component naming drops
+// `Component` suffix). One Tilemap entity per grid; TileLayer entities
+// attach via ChildOf relationship and supply the per-cell tile id array
+// for a single render-layer.
+//
+// charter mapping: F1 (single-import barrel from `@forgeax/engine-runtime`),
+// P1 (progressive disclosure - defaults cover the common case), P4 (durable
+// asset identity stays separate from World-local handles).
+
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/**
+ * Tilemap component (M0 baseline rebuild).
+ *
+ * A Tilemap entity carries grid metadata + a single durable `tileset` GUID. The
+ * actual per-cell tile id array lives on attached `TileLayer` entities
+ * (one per render layer; ChildOf points back to the Tilemap entity).
+ *
+ * Defaults:
+ *   - `tileSize = [1, 1]` (unit-cell world coordinates).
+ *   - `chunkSize = 16` (tilemap-chunk-extract-system chunks 16x16 cells).
+ *
+ * @example Spawn a 32x32 unit-cell Tilemap referencing a TilesetAsset:
+ *   const tilemap = world.spawn(
+ *     { component: Tilemap, data: { cols: 32, rows: 32, tileset } },
+ *     { component: Transform, data: {} },
+ *   ).unwrap();
+ */
+export const Tilemap = defineComponent('Tilemap', {
+  cols: { type: 'u32', default: 0 },
+  rows: { type: 'u32', default: 0 },
+  // tileSize carries an explicit layer-2 default [1,1] (unit cell); the array
+  // layer-3 fallback is all-zero, so the default MUST be explicit (D-5).
+  tileSize: { type: 'array<f32, 2>', default: new Float32Array([1, 1]) },
+  chunkSize: { type: 'u32', default: 16 },
+  tileset: { type: 'string' },
+});

package/src/components/visibility.ts

@@ -0,0 +1,53 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Numeric labels stored by the public Visibility enum field. */
+export const VisibilityStateValue = Object.freeze({
+  inherited: 0,
+  hidden: 1,
+  visible: 2,
+} as const);
+
+/** Author visibility intent accepted by the Visibility component. */
+export type VisibilityState = keyof typeof VisibilityStateValue;
+
+/**
+ * Decode the stored u32 without treating an unknown value as a valid state.
+ * Invalid values are rejected at ECS write boundaries; undefined remains an
+ * explicit signal for readers that inspect externally corrupted columns.
+ */
+export function visibilityStateFromU32(value: number): VisibilityState | undefined {
+  switch (value) {
+    case VisibilityStateValue.inherited:
+      return 'inherited';
+    case VisibilityStateValue.hidden:
+      return 'hidden';
+    case VisibilityStateValue.visible:
+      return 'visible';
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Author intent for render participation. Omitted state is inherited and is
+ * therefore visible when no valid parent intent is available.
+ */
+export const Visibility = defineComponent(
+  'Visibility',
+  {
+    state: {
+      type: 'enum',
+      default: VisibilityStateValue.inherited,
+      labels: VisibilityStateValue,
+    },
+  },
+  {
+    meta: {
+      quickStart: 'Attach Visibility to author render participation intent.',
+      diagnostics: 'Compare the ECS state with resolveVisibility and renderer.visibilityStats.',
+      recovery: 'Use structured ECS write errors and repair the owning scene relation.',
+      boundaries:
+        'Visibility does not own camera, picking, lifecycle, assets, or VFX shadow policy.',
+    },
+  },
+);

package/src/construct-renderer.ts

@@ -0,0 +1,4 @@
+export {
+  type BundlerOptions,
+  createRenderer as constructRenderer,
+} from './renderer/renderer-factory';

package/src/debug-draw-glue.ts

@@ -0,0 +1,169 @@
+// @forgeax/engine-runtime — debug-draw auto-attach SSOT (feat-20260615-debug-draw M5 / w28)
+//
+// 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).
+
+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 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);
+    },
+  });
+}
+
+export function addTypedDebugOverlayPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  output: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  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') {
+        mat4.orthographic(
+          projection,
+          frame.camera.orthoLeft,
+          frame.camera.orthoRight,
+          frame.camera.orthoBottom,
+          frame.camera.orthoTop,
+          frame.camera.near,
+          frame.camera.far,
+        );
+      } else {
+        mat4.perspective(
+          projection,
+          frame.camera.fov,
+          frame.camera.aspect,
+          frame.camera.near,
+          frame.camera.far,
+        );
+      }
+      const view = mat4.invert(mat4.create(), frame.camera.world);
+      const result = registeredDebugDraw?.encode(
+        pass,
+        mat4.multiply(mat4.create(), projection, view),
+      );
+      if (result !== undefined && !result.ok) throw result.error;
+    },
+  });
+}

package/src/deferred-lighting.ts

@@ -0,0 +1,92 @@
+import type { GraphResourceResolver, ResolveContext } from '@forgeax/engine-render-graph';
+import type { RhiRenderPassEncoder, TextureView } from '@forgeax/engine-rhi';
+import { buildPerFrameBindGroups } from './record/frame-lighting';
+import { encodeFullscreenPass } from './render-graph-primitives';
+import type { RenderPipelineFrame } from './render-pipeline';
+import type { RenderPipelineTarget } from './render-pipeline-target';
+import type { RenderSystemInternals } from './render-system';
+
+export const HDRP_DEFERRED_LIGHTING_POST_PROCESS_ID = 'forgeax::hdrp-deferred-lighting';
+
+function resolveView(resources: GraphResourceResolver, target: RenderPipelineTarget): TextureView {
+  const result = resources.textureView(target.view);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+function resolveDepthView(
+  frame: RenderPipelineFrame,
+  resources: GraphResourceResolver,
+  target: RenderPipelineTarget,
+): TextureView {
+  const texture = resources.texture(target.texture);
+  if (!texture.ok) throw texture.error;
+  const view = frame.runtime.device.createTextureView(texture.value, {
+    label: 'hdrp-deferred-lighting-depth-only-view',
+    dimension: '2d',
+    aspect: 'depth-only',
+    baseMipLevel: 0,
+    mipLevelCount: 1,
+    baseArrayLayer: 0,
+    arrayLayerCount: 1,
+  });
+  if (!view.ok) throw view.error;
+  return view.value;
+}
+
+export function encodeDeferredLightingPass(
+  frame: RenderPipelineFrame,
+  pass: RhiRenderPassEncoder,
+  resources: GraphResourceResolver,
+  targets: {
+    readonly albedo: RenderPipelineTarget;
+    readonly normal: RenderPipelineTarget;
+    readonly emissive: RenderPipelineTarget;
+    readonly depth: RenderPipelineTarget;
+    readonly output: RenderPipelineTarget;
+  },
+): void {
+  const views: ResolveContext = {
+    resolve: (name) => {
+      switch (name) {
+        case 'gbuffer-albedo-metallic':
+          return resolveView(resources, targets.albedo);
+        case 'gbuffer-normal-roughness':
+          return resolveView(resources, targets.normal);
+        case 'gbuffer-emissive-ao':
+          return resolveView(resources, targets.emissive);
+        case 'depth':
+          return resolveView(resources, targets.depth);
+        case 'hdrp-scene-color':
+          return resolveView(resources, targets.output);
+        default:
+          return undefined;
+      }
+    },
+  };
+  // The deferred lighting shader owns a group(0) View UBO, but this pass is
+  // not a scene pass and therefore cannot inherit the main-pass context's
+  // bind group. Resolve the same graph-backed shadow views used by the main
+  // pass so the cache has one canonical view-main entry for the frame.
+  const viewBindGroup = buildPerFrameBindGroups(
+    frame.runtime as RenderSystemInternals,
+    frame.frameState,
+    frame.pipelineState,
+    true,
+    frame.bindGroupCounts,
+    {
+      directionalShadow: frame.frameState.currentDirectionalShadowView ?? undefined,
+      spotShadow: frame.frameState.currentSpotShadowView ?? undefined,
+    },
+  ).viewBindGroup;
+  if (viewBindGroup !== null) pass.setBindGroup(0, viewBindGroup);
+  encodeFullscreenPass(frame, pass, {
+    name: 'lighting',
+    shader: HDRP_DEFERRED_LIGHTING_POST_PROCESS_ID,
+    color: 'hdrp-scene-color',
+    reads: ['gbuffer-albedo-metallic', 'gbuffer-normal-roughness', 'gbuffer-emissive-ao', 'depth'],
+    resolve: views,
+    outputFormat: targets.output.format as GPUTextureFormat,
+    depthView: resolveDepthView(frame, resources, targets.depth),
+  });
+}