@forgeax/engine-render 0.1.4 → 0.1.7

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),
       );

package/src/device/device-scope.ts

@@ -0,0 +1,306 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { LifecycleConstructionError } from '../errors/render';
+import type { DeviceResourceKind, DeviceScopeReceipt } from './resource-types';
+
+export {
+  DEVICE_RESOURCE_KINDS,
+  type DeviceResourceKind,
+  type DeviceScopeReceipt,
+} from './resource-types';
+
+export type DeviceScopeState = 'active' | 'retiring' | 'retired' | 'abandoned' | 'disposed';
+
+export interface ResourceRef<T> {
+  readonly kind: DeviceResourceKind;
+  readonly owner: string;
+  readonly generation: number;
+  readonly value: T;
+  isCurrent(scope: DeviceScope): boolean;
+  isStale(scope: DeviceScope): boolean;
+}
+
+export class DeviceResourceRef<T> implements ResourceRef<T> {
+  readonly kind: DeviceResourceKind;
+  readonly owner: string;
+  readonly generation: number;
+  readonly value: T;
+
+  constructor(kind: DeviceResourceKind, owner: string, generation: number, value: T) {
+    this.kind = kind;
+    this.owner = owner;
+    this.generation = generation;
+    this.value = value;
+  }
+
+  isCurrent(scope: DeviceScope): boolean {
+    return scope.accepts(this);
+  }
+
+  isStale(scope: DeviceScope): boolean {
+    return !this.isCurrent(scope);
+  }
+}
+
+interface OwnedResource {
+  readonly ref: DeviceResourceRef<unknown>;
+  readonly cleanup: (value: unknown) => void | Promise<void>;
+}
+
+export class DeviceScope {
+  readonly generation: number;
+  readonly owner: string;
+  readonly parent: DeviceScope | undefined;
+  private lifecycleState: DeviceScopeState = 'active';
+  private readonly resources: OwnedResource[] = [];
+  private readonly children: DeviceScope[] = [];
+
+  private constructor(generation: number, owner: string, parent?: DeviceScope) {
+    this.generation = generation;
+    this.owner = owner;
+    this.parent = parent;
+    parent?.children.push(this);
+  }
+
+  static create(generation: number, owner: string): DeviceScope {
+    if (!Number.isSafeInteger(generation) || generation < 0) {
+      throw new RangeError('DeviceScope generation must be a non-negative safe integer.');
+    }
+    if (owner.length === 0) throw new TypeError('DeviceScope owner must not be empty.');
+    return new DeviceScope(generation, owner);
+  }
+
+  get state(): DeviceScopeState {
+    return this.lifecycleState;
+  }
+
+  get childrenSnapshot(): readonly DeviceScope[] {
+    return [...this.children];
+  }
+
+  ref<T>(kind: DeviceResourceKind, value: T): ResourceRef<T> {
+    const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
+    this.resources.push({ ref: ref as DeviceResourceRef<unknown>, cleanup: () => undefined });
+    return ref;
+  }
+
+  accepts(ref: ResourceRef<unknown>): boolean {
+    return (
+      this.lifecycleState === 'active' &&
+      ref.owner === this.owner &&
+      ref.generation === this.generation
+    );
+  }
+
+  isAlive(): boolean {
+    return this.lifecycleState === 'active';
+  }
+
+  resourceDelta(): number {
+    return this.resources.length;
+  }
+
+  /** @internal */
+  _adopt<T>(
+    kind: DeviceResourceKind,
+    value: T,
+    cleanup: (value: T) => void | Promise<void>,
+  ): ResourceRef<T> {
+    const ref = new DeviceResourceRef(kind, this.owner, this.generation, value);
+    this.resources.push({
+      ref: ref as DeviceResourceRef<unknown>,
+      cleanup: cleanup as (resource: unknown) => void | Promise<void>,
+    });
+    return ref;
+  }
+
+  /** @internal */
+  _clearResources(): OwnedResource[] {
+    const resources = this.resources.splice(0);
+    for (const resource of resources.reverse()) {
+      try {
+        const pending = resource.cleanup(resource.ref.value);
+        if (pending instanceof Promise) void pending.catch(() => undefined);
+      } catch {
+        // Synchronous scope termination is bounded; transaction cleanup owns
+        // structured failure collection during construction and replacement.
+      }
+    }
+    return resources;
+  }
+
+  retire(): void {
+    if (this.lifecycleState !== 'active') return;
+    this.lifecycleState = 'retiring';
+    this._clearResources();
+    this.lifecycleState = 'retired';
+  }
+
+  abandon(): void {
+    if (this.lifecycleState !== 'active') return;
+    this.lifecycleState = 'abandoned';
+    this._clearResources();
+  }
+
+  dispose(): void {
+    if (this.lifecycleState === 'disposed') return;
+    this.lifecycleState = 'disposed';
+    this._clearResources();
+  }
+
+  async replace(
+    generation: number,
+    resources: readonly LifecycleResourceSpec<unknown>[],
+  ): Promise<LifecycleResult> {
+    const replacement = new DeviceScope(generation, this.owner, this);
+    const transaction = new LifecycleTransaction(replacement);
+    for (const resource of resources) transaction.add(resource);
+    const result = await transaction.commit();
+    if (!result.ok) {
+      replacement.abandon();
+      return result;
+    }
+    if (!this.isAlive()) {
+      replacement.dispose();
+      return transaction.failure('dispose');
+    }
+    this.retire();
+    return ok(replacement);
+  }
+
+  /** @internal */
+  _receipt(): DeviceScopeReceipt {
+    return {
+      owner: this.owner,
+      generation: this.generation,
+      resourceCount: this.resources.length,
+    };
+  }
+}
+
+export interface LifecycleResourceSpec<T> {
+  readonly kind: DeviceResourceKind;
+  readonly create: () => T | Promise<T>;
+  readonly cleanup: (value: T) => void | Promise<void>;
+}
+
+export interface LifecycleCleanupFailure {
+  readonly resourceKind: DeviceResourceKind;
+  readonly cause: unknown;
+}
+
+export interface LifecycleFailure {
+  readonly primary: LifecycleConstructionError;
+  readonly cleanupFailures: readonly LifecycleCleanupFailure[];
+  readonly receipt: DeviceScopeReceipt;
+}
+
+export type LifecycleResult = Result<DeviceScope, LifecycleFailure>;
+
+export interface LifecycleTransactionOptions {
+  readonly failureAt?: number;
+}
+
+interface CreatedResource {
+  readonly spec: LifecycleResourceSpec<unknown>;
+  readonly value: unknown;
+}
+
+export class LifecycleTransaction {
+  private readonly resources: LifecycleResourceSpec<unknown>[] = [];
+  private readonly options: LifecycleTransactionOptions;
+  private committed = false;
+
+  constructor(
+    private readonly scope: DeviceScope,
+    options: LifecycleTransactionOptions = {},
+  ) {
+    this.options = options;
+  }
+
+  add<T>(spec: LifecycleResourceSpec<T>): this {
+    if (this.committed) throw new Error('LifecycleTransaction is already committed.');
+    this.resources.push(spec as LifecycleResourceSpec<unknown>);
+    return this;
+  }
+
+  async commit(): Promise<LifecycleResult> {
+    if (this.committed) return this.failure('create');
+    this.committed = true;
+    const created: CreatedResource[] = [];
+    for (let index = 0; index < this.resources.length; index += 1) {
+      const spec = this.resources[index];
+      if (spec === undefined) continue;
+      try {
+        if (this.options.failureAt === index + 1) {
+          throw new Error(`injected lifecycle failure at ${index + 1}`);
+        }
+        const value = await spec.create();
+        if (!this.scope.isAlive()) {
+          await this.cleanupOne(spec, value, created);
+          return this.failure('dispose');
+        }
+        created.push({ spec, value });
+      } catch (cause) {
+        const cleanupFailures = await this.cleanupCreated(created);
+        return this.failure('create', spec.kind, cleanupFailures, cause);
+      }
+    }
+    if (!this.scope.isAlive()) {
+      const cleanupFailures = await this.cleanupCreated(created);
+      return this.failure('dispose', this.resources.at(-1)?.kind ?? 'listener', cleanupFailures);
+    }
+    for (const item of created) this.scope._adopt(item.spec.kind, item.value, item.spec.cleanup);
+    return ok(this.scope);
+  }
+
+  failure(
+    operation: 'create' | 'dispose',
+    resourceKind: DeviceResourceKind = this.resources.at(-1)?.kind ?? 'listener',
+    cleanupFailures: readonly LifecycleCleanupFailure[] = [],
+    cause: unknown = undefined,
+  ): LifecycleResult {
+    return err({
+      primary: new LifecycleConstructionError({
+        owner: this.scope.owner,
+        generation: this.scope.generation,
+        operation,
+        resourceKind,
+        cause,
+        cleanupFailures,
+        receipt: this.scope._receipt(),
+      }),
+      cleanupFailures,
+      receipt: this.scope._receipt(),
+    });
+  }
+
+  private async cleanupCreated(
+    created: readonly CreatedResource[],
+  ): Promise<LifecycleCleanupFailure[]> {
+    const failures: LifecycleCleanupFailure[] = [];
+    for (let index = created.length - 1; index >= 0; index -= 1) {
+      const item = created[index];
+      if (item === undefined) continue;
+      try {
+        await item.spec.cleanup(item.value);
+      } catch (cause) {
+        failures.push({ resourceKind: item.spec.kind, cause });
+      }
+    }
+    return failures;
+  }
+
+  private async cleanupOne(
+    spec: LifecycleResourceSpec<unknown>,
+    value: unknown,
+    created: readonly CreatedResource[],
+  ): Promise<void> {
+    await this.cleanupCreated(created);
+    try {
+      await spec.cleanup(value);
+    } catch {
+      // The terminal dispose result is intentionally bounded; prior cleanup
+      // evidence remains in the transaction failure shape.
+    }
+  }
+}