@forgeax/engine-render 0.1.4 → 0.1.7

package/src/points-lines/prepare.ts

@@ -0,0 +1,177 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { PointsLinesPrepareFailedError } from '../errors/render';
+import type { PointsLinesExpandedGeometry, PointsLinesExpansionCache } from './expansion-cache';
+import {
+  createPointsLinesLaneContract,
+  type PointsLinesBackend,
+  type PointsLinesLane,
+  type PointsLinesLaneContract,
+} from './record';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export interface PointsLinesGpuResourceAdapter<Resource> {
+  create(geometry: PointsLinesExpandedGeometry): Result<Resource, Error>;
+  upload(resource: Resource, geometry: PointsLinesExpandedGeometry): Result<number, Error>;
+  validate(resource: Resource, geometry: PointsLinesExpandedGeometry): Result<void, Error>;
+  destroy(resource: Resource): void;
+}
+
+export interface PointsLinesPreparedResource<Resource> {
+  readonly resource: Resource;
+  readonly geometry: PointsLinesExpandedGeometry;
+  readonly snapshot: PointsLinesRetainedSnapshot;
+  readonly uploadedBytes: number;
+  readonly lastKnownGood: true;
+}
+
+export interface PointsLinesPreparationOptions<Resource> {
+  readonly cache: PointsLinesExpansionCache;
+  readonly adapter: PointsLinesGpuResourceAdapter<Resource>;
+}
+
+export interface PointsLinesLanePreparationAdapter<Resource> {
+  readonly contract: PointsLinesLaneContract;
+  prepare(
+    snapshot: PointsLinesRetainedSnapshot,
+    mesh: MeshAsset,
+  ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError>;
+  resetForDeviceLoss(): void;
+  lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined;
+  inspect(): PointsLinesPreparationInspection<Resource>;
+}
+
+export interface PointsLinesPreparationInspection<Resource> {
+  readonly status: 'empty' | 'resident' | 'rebuild-pending';
+  readonly lastKnownGood: boolean;
+  readonly liveResource: Resource | undefined;
+  readonly liveBytes: number;
+  readonly candidateBytes: number;
+  readonly cacheEntries: number;
+  readonly uploads: number;
+  readonly rebuilds: number;
+  readonly failures: number;
+}
+
+/**
+ * Owns one atomic candidate/LKG pair for a Points/Lines render projection.
+ * GPU resources are supplied by the existing DeviceScope adapter; this class
+ * keeps no backend handle or second resource ledger.
+ */
+export class PointsLinesPreparation<Resource> {
+  private live: PointsLinesPreparedResource<Resource> | undefined;
+  private pendingCandidateBytes = 0;
+  private status: 'empty' | 'resident' | 'rebuild-pending' = 'empty';
+  private uploads = 0;
+  private rebuilds = 0;
+  private failures = 0;
+
+  constructor(private readonly options: PointsLinesPreparationOptions<Resource>) {}
+
+  prepare(
+    snapshot: PointsLinesRetainedSnapshot,
+    mesh: MeshAsset,
+  ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError> {
+    const geometry = this.options.cache.getOrCreate(snapshot, mesh);
+    if (this.live?.geometry.key === geometry.key) {
+      this.live = {
+        ...this.live,
+        snapshot,
+        uploadedBytes: 0,
+      };
+      this.status = 'resident';
+      return ok(this.live);
+    }
+
+    this.pendingCandidateBytes = geometry.derivedBytes;
+    const created = this.options.adapter.create(geometry);
+    if (!created.ok) return this.fail(snapshot, created.error);
+    const candidate = created.value;
+    const uploaded = this.options.adapter.upload(candidate, geometry);
+    if (!uploaded.ok) {
+      this.options.adapter.destroy(candidate);
+      return this.fail(snapshot, uploaded.error);
+    }
+    this.uploads += 1;
+    const validated = this.options.adapter.validate(candidate, geometry);
+    if (!validated.ok) {
+      this.options.adapter.destroy(candidate);
+      return this.fail(snapshot, validated.error);
+    }
+
+    const previous = this.live;
+    this.live = {
+      resource: candidate,
+      geometry,
+      snapshot,
+      uploadedBytes: uploaded.value,
+      lastKnownGood: true,
+    };
+    this.pendingCandidateBytes = 0;
+    this.status = 'resident';
+    this.rebuilds += 1;
+    if (previous !== undefined) this.options.adapter.destroy(previous.resource);
+    return ok(this.live);
+  }
+
+  resetForDeviceLoss(): void {
+    if (this.live !== undefined) this.options.adapter.destroy(this.live.resource);
+    this.live = undefined;
+    this.pendingCandidateBytes = 0;
+    this.status = 'rebuild-pending';
+  }
+
+  lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined {
+    return this.live;
+  }
+
+  inspect(): PointsLinesPreparationInspection<Resource> {
+    return {
+      status: this.status,
+      lastKnownGood: this.live?.lastKnownGood ?? false,
+      liveResource: this.live?.resource,
+      liveBytes: this.live?.geometry.derivedBytes ?? 0,
+      candidateBytes: this.pendingCandidateBytes,
+      cacheEntries: this.options.cache.size,
+      uploads: this.uploads,
+      rebuilds: this.rebuilds,
+      failures: this.failures,
+    };
+  }
+
+  private fail(
+    snapshot: PointsLinesRetainedSnapshot,
+    cause: Error,
+  ): Result<never, PointsLinesPrepareFailedError> {
+    this.pendingCandidateBytes = 0;
+    this.failures += 1;
+    return err(
+      new PointsLinesPrepareFailedError({
+        owner: 'points-lines',
+        generation: snapshot.meshGeneration,
+        stage: 'prepare',
+        cause: cause.message,
+        lastKnownGood: this.live !== undefined,
+      }),
+    );
+  }
+}
+
+/**
+ * Binds the existing atomic preparation owner to a lane contract. It carries
+ * no RHI handle and does not add a second cache or recovery owner.
+ */
+export function createPointsLinesLanePreparationAdapter<Resource>(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+  options: PointsLinesPreparationOptions<Resource>,
+): PointsLinesLanePreparationAdapter<Resource> {
+  const preparation = new PointsLinesPreparation(options);
+  return {
+    contract: createPointsLinesLaneContract(lane, backend),
+    prepare: (snapshot, mesh) => preparation.prepare(snapshot, mesh),
+    resetForDeviceLoss: () => preparation.resetForDeviceLoss(),
+    lastKnownGood: () => preparation.lastKnownGood(),
+    inspect: () => preparation.inspect(),
+  };
+}

package/src/points-lines/record.ts

@@ -0,0 +1,125 @@
+import type { PointsLinesExpandedGeometry } from './expansion-cache';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+export const POINTS_LINES_MATERIAL_SHADER_ID = 'forgeax::points-lines';
+
+export type PointsLinesLane = 'direct' | 'clustered' | 'cpu-webgl2';
+export type PointsLinesBackend = 'webgpu' | 'wgpu-webgl2' | 'null';
+
+export interface PointsLinesLaneContract {
+  readonly lane: PointsLinesLane;
+  readonly backend: PointsLinesBackend;
+  readonly authoring: 'shared';
+  readonly evidence: 'runtime' | 'structural-only';
+  readonly material: {
+    readonly source: 'MaterialAsset';
+    readonly shaderId: typeof POINTS_LINES_MATERIAL_SHADER_ID;
+    readonly shadingModel: 'unlit';
+    readonly clusteredLighting: false;
+    readonly lit: false;
+  };
+  readonly graph: {
+    readonly additionalAttachments: 0;
+    readonly additionalPasses: 0;
+  };
+  readonly shadowDrawCount: 0;
+  readonly capabilities: {
+    readonly compute: false;
+    readonly storage: false;
+    readonly indirect: false;
+  };
+}
+
+export interface PointsLinesRecordPlan {
+  readonly lane: PointsLinesLane;
+  readonly backend: PointsLinesBackend;
+  readonly materialShaderId: typeof POINTS_LINES_MATERIAL_SHADER_ID;
+  readonly component: 'Points' | 'Lines';
+  readonly meshGeneration: number;
+  readonly materialGeneration: number;
+  readonly vertexCount: number;
+  readonly indexCount: number;
+  readonly drawCount: 0 | 1;
+  readonly shadowDrawCount: 0;
+  readonly conservativeMarginPx: number;
+  readonly graph: PointsLinesLaneContract['graph'];
+}
+
+/**
+ * Describes the shared lane boundary without selecting a backend in authoring.
+ * Every lane uses CPU-uploaded triangle expansion; capability flags therefore
+ * stay false, including on WebGPU, and the graph remains the existing pass.
+ */
+export function createPointsLinesLaneContract(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+): PointsLinesLaneContract {
+  return {
+    lane,
+    backend,
+    authoring: 'shared',
+    evidence: backend === 'null' ? 'structural-only' : 'runtime',
+    material: {
+      source: 'MaterialAsset',
+      shaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+      shadingModel: 'unlit',
+      clusteredLighting: false,
+      lit: false,
+    },
+    graph: { additionalAttachments: 0, additionalPasses: 0 },
+    shadowDrawCount: 0,
+    capabilities: { compute: false, storage: false, indirect: false },
+  };
+}
+
+/**
+ * Turns one retained expansion into the bounded draw facts consumed by the
+ * existing record pass. The shader expands one quad per point or segment,
+ * so the limits are exactly four vertices and six indices per primitive.
+ */
+export function createPointsLinesRecordPlan(
+  snapshot: PointsLinesRetainedSnapshot,
+  geometry: PointsLinesExpandedGeometry,
+  contract: PointsLinesLaneContract,
+): PointsLinesRecordPlan {
+  const primitiveCount = geometry.pointCount + geometry.segmentCount;
+  const visible = snapshot.visible && primitiveCount > 0;
+  const conservativeMarginPx =
+    snapshot.style?.kind === 'points'
+      ? snapshot.style.sizePx * 0.5
+      : (snapshot.style?.widthPx ?? 0) * 0.5;
+  return {
+    lane: contract.lane,
+    backend: contract.backend,
+    materialShaderId: POINTS_LINES_MATERIAL_SHADER_ID,
+    component: geometry.component,
+    meshGeneration: snapshot.meshGeneration,
+    materialGeneration: snapshot.materialGeneration,
+    vertexCount: primitiveCount * 4,
+    indexCount: primitiveCount * 6,
+    drawCount: visible ? 1 : 0,
+    shadowDrawCount: 0,
+    conservativeMarginPx,
+    graph: contract.graph,
+  };
+}
+
+export interface PointsLinesLaneAdapter {
+  readonly contract: PointsLinesLaneContract;
+  createRecordPlan(
+    snapshot: PointsLinesRetainedSnapshot,
+    geometry: PointsLinesExpandedGeometry,
+  ): PointsLinesRecordPlan;
+}
+
+export function createPointsLinesLaneAdapter(
+  lane: PointsLinesLane,
+  backend: PointsLinesBackend,
+): PointsLinesLaneAdapter {
+  const contract = createPointsLinesLaneContract(lane, backend);
+  return {
+    contract,
+    createRecordPlan: (snapshot, geometry) =>
+      createPointsLinesRecordPlan(snapshot, geometry, contract),
+  };
+}

package/src/points-lines/snapshot.ts

@@ -0,0 +1,130 @@
+import type { PointShape } from '../components/points';
+
+export interface PointsLinesViewport {
+  readonly width: number;
+  readonly height: number;
+  readonly dpr: number;
+}
+
+export type PointsLinesStyle =
+  | { readonly kind: 'points'; readonly sizePx: number; readonly shape: PointShape }
+  | { readonly kind: 'lines'; readonly widthPx: number };
+
+export type PointsLinesInvalidation = 'none' | 'mesh' | 'material' | 'style' | 'view' | 'scene';
+
+/**
+ * Detached facts retained between frames for the Points/Lines owner.
+ *
+ * The snapshot deliberately contains no World, ECS row, AssetRegistry, GPU
+ * handle, or derived triangle data. Mesh and material generations are the
+ * producer-owned fences used by prepare; viewport and projection are the
+ * only camera-owned facts in this projection.
+ */
+export interface PointsLinesRetainedSnapshot {
+  readonly worldId: number;
+  readonly entityKey: number;
+  readonly component: 'Points' | 'Lines' | undefined;
+  readonly meshHandle: number;
+  readonly meshGeneration: number;
+  readonly materialHandle: number;
+  readonly materialGeneration: number;
+  readonly style: PointsLinesStyle | undefined;
+  readonly layer: number;
+  readonly sortKey: number | undefined;
+  readonly visible: boolean;
+  readonly sourceBounds: Float32Array;
+  readonly viewport: PointsLinesViewport;
+  readonly projection: Float32Array;
+  readonly dedicatedResourceBytes?: number;
+}
+
+export interface PointsLinesSnapshotInput
+  extends Omit<
+    PointsLinesRetainedSnapshot,
+    'sourceBounds' | 'viewport' | 'projection' | 'sortKey'
+  > {
+  readonly sortKey?: number | undefined;
+  readonly sourceBounds: ArrayLike<number>;
+  readonly viewport: PointsLinesViewport;
+  readonly projection: ArrayLike<number>;
+}
+
+export function createPointsLinesSnapshot(
+  input: PointsLinesSnapshotInput,
+): PointsLinesRetainedSnapshot {
+  return {
+    worldId: input.worldId,
+    entityKey: input.entityKey,
+    component: input.component,
+    meshHandle: input.meshHandle,
+    meshGeneration: input.meshGeneration,
+    materialHandle: input.materialHandle,
+    materialGeneration: input.materialGeneration,
+    style: input.style === undefined ? undefined : { ...input.style },
+    layer: input.layer,
+    sortKey: input.sortKey,
+    visible: input.visible,
+    sourceBounds: new Float32Array(input.sourceBounds),
+    viewport: { ...input.viewport },
+    projection: new Float32Array(input.projection),
+    ...(input.component === undefined ? { dedicatedResourceBytes: 0 } : {}),
+  };
+}
+
+export function comparePointsLinesSnapshots(
+  previous: PointsLinesRetainedSnapshot,
+  next: PointsLinesRetainedSnapshot,
+): PointsLinesInvalidation {
+  if (
+    previous.meshHandle !== next.meshHandle ||
+    previous.meshGeneration !== next.meshGeneration ||
+    !sameArray(previous.sourceBounds, next.sourceBounds)
+  ) {
+    return 'mesh';
+  }
+  if (
+    previous.materialHandle !== next.materialHandle ||
+    previous.materialGeneration !== next.materialGeneration
+  ) {
+    return 'material';
+  }
+  if (!sameValue(previous.style, next.style)) return 'style';
+  if (
+    previous.viewport.width !== next.viewport.width ||
+    previous.viewport.height !== next.viewport.height ||
+    previous.viewport.dpr !== next.viewport.dpr ||
+    !sameArray(previous.projection, next.projection)
+  ) {
+    return 'view';
+  }
+  if (
+    previous.worldId !== next.worldId ||
+    previous.entityKey !== next.entityKey ||
+    previous.layer !== next.layer ||
+    previous.sortKey !== next.sortKey ||
+    previous.visible !== next.visible
+  ) {
+    return 'scene';
+  }
+  return 'none';
+}
+
+function sameArray(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
+  if (left.length !== right.length) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    if (left[index] !== right[index]) return false;
+  }
+  return true;
+}
+
+function sameValue(
+  left: PointsLinesStyle | undefined,
+  right: PointsLinesStyle | undefined,
+): boolean {
+  if (left?.kind !== right?.kind) return false;
+  if (left === undefined || right === undefined) return left === right;
+  if (left.kind === 'points' && right.kind === 'points') {
+    return left.sizePx === right.sizePx && left.shape === right.shape;
+  }
+  return left.kind === 'lines' && right.kind === 'lines' && left.widthPx === right.widthPx;
+}

package/src/post-process-errors.ts

@@ -4,28 +4,27 @@
 //  added 'fullscreen-input-not-found').
 //
 // Closed 7-member PostProcessErrorCode union + PostProcessError discriminated-union class.
-//   - 'post-process-already-registered' (programmer error) -> postProcess.register THROWS a
-//     PostProcessError, mirroring ShaderRegistry.installMaterialArtifact's Map.has -> throw
+//   - 'post-process-already-registered' (programmer error) -> fullscreen effect registration THROWS a
+//     PostProcessError, mirroring ShaderCatalog.installMaterialArtifact's Map.has -> throw
 //     fail-fast (research Finding M2-4). A second register under the same id is a coding
 //     mistake that must surface immediately.
-//   - 'post-process-not-found' (runtime path) -> addFullscreenPass returns Result.err with
+//   - 'post-process-not-found' (runtime path) -> the typed fullscreen plan returns Result.err with
 //     this code when the supplied id resolves to no registered post-process (stale / wrong
 //     id). AI users branch on `err.code === 'post-process-not-found'` by property access.
 //   - 'fullscreen-input-not-found' (runtime path, feat-20260609 M1 / D-2) -> the
 //     dispatchFullscreenPass generic branch THROWS this when reads[0] references a
 //     graph resource key that the per-pass resolve context cannot resolve (typo /
-//     unregistered colorTarget / mis-ordered addColorTarget vs addFullscreenPass).
+//     an unregistered colorTarget / mis-ordered color-target declaration vs the typed fullscreen pass).
 //   - 'ssao-radius-non-positive' (runtime path, feat-20260612-hdrp-ssao M2 / w10) ->
 //     SSAO radius parameter <= 0; fires when config.ssao.radius value is non-positive.
 //   - 'ssao-bias-negative' (runtime path, feat-20260612-hdrp-ssao M2 / w10) ->
 //     SSAO bias parameter < 0; fires when config.ssao.bias value is negative.
 //
 // D-1: a NEW independent union rather than folding into RuntimeErrorCode /
-// PipelineErrorCode (plan-strategy D-9). RuntimeErrorCode's members are render / skin /
-// shadow domain; a separate union keeps the post-process error surface cohesive and
-// additively evolvable (mirrors pipeline-errors.ts D-1 reasoning verbatim).
+// RuntimeErrorCode's members are render / skin / shadow domain; a separate union
+// keeps the post-process error surface cohesive and additively evolvable.
 //
-// Also per D-4: the postProcess.register channel is parallel to installMaterialArtifact;
+// Also per D-4: the fullscreen effect channel is parallel to installMaterialArtifact;
 // material shader errors carry 4-BGL / 12-float-vertex / depth / triangle-list semantics,
 // while post-process errors carry 0-vertex-buffer / no-depth / input-texture-BGL semantics.
 // Mixing the two error spaces would confuse AI users who branch on code for diagnostics.
@@ -44,12 +43,12 @@
  *
  * | code | channel | trigger |
  * |:--|:--|:--|
- * | `'post-process-already-registered'` | throw | a second `postProcess.register(id, entry)` under an already-registered `id` |
- * | `'post-process-not-found'` | throw / `Result.err` | `addFullscreenPass({shader: id})` where `id` resolves to no registered post-process |
- * | `'fullscreen-input-not-found'` | throw | `addFullscreenPass({reads: [key]})` where `key` is not a graph-declared color target, or a depth key missing TEXTURE_BINDING (D-4) |
+ * | `'post-process-already-registered'` | throw | a second fullscreen effect registration under an already-registered `id` |
+ * | `'post-process-not-found'` | throw / `Result.err` | a typed fullscreen plan whose `shader` id resolves to no registered post-process |
+ * | `'fullscreen-input-not-found'` | throw | a typed fullscreen plan whose `reads` key is not a graph-declared color target, or a depth key missing TEXTURE_BINDING (D-4) |
  * | `'ssao-radius-non-positive'` | throw | SSAO `radius <= 0` |
  * | `'ssao-bias-negative'` | throw | SSAO `bias < 0` |
- * | `'params-size-mismatch'` | throw | `postProcess.register({params})` with `byteSize < 16` or `defaultValue.length !== byteSize` (feat-20260621 M-A4 / D-4) |
+ * | `'params-size-mismatch'` | throw | a fullscreen effect declaration with `params.byteSize < 16` or `defaultValue.length !== byteSize` (feat-20260621 M-A4 / D-4) |
  * | `'params-update-size-mismatch'` | throw | per-frame data-driven write where `PostProcessParams.data` byteLength !== registered `params.byteSize` (feat-20260621 M-A4 / D-4) |
  */
 export type PostProcessErrorCode = keyof typeof POST_PROCESS_POLICY;
@@ -80,7 +79,7 @@ export interface PostProcessNotFoundDetail {
 export interface FullscreenInputNotFoundDetail {
   /** The reads[0] key that resolved to undefined (e.g. 'offscreenColor' / 'hdrColor'). */
   readonly readsKey: string;
-  /** The pass name passed to addFullscreenPass (the 2nd argument; e.g. 'pp' / 'post'). */
+  /** The name assigned to the typed fullscreen pass (e.g. 'pp' / 'post'). */
   readonly passName: string;
 }
 
@@ -168,11 +167,11 @@ const POST_PROCESS_POLICY = {
       '(engine builtins use the forgeax:: prefix; user passes use <package>::<id>).',
   },
   'post-process-not-found': {
-    expected: 'addFullscreenPass references a registered post-process id',
+    expected: 'typed fullscreen plan references a registered post-process id',
     hint: (detail) =>
       `no post-process is registered for id '${(detail as PostProcessNotFoundDetail).id}'. ` +
-      `First call renderer.postProcess.register('${(detail as PostProcessNotFoundDetail).id}', {source, reads?}), ` +
-      'then reference it via addFullscreenPass({shader: id}).',
+      `Register '${(detail as PostProcessNotFoundDetail).id}' with the feature host ({source, reads?}), ` +
+      'then reference it from a typed fullscreen RenderFeaturePlan.',
   },
   'fullscreen-input-not-found': {
     expected: 'reads key must be a graph-declared colorTarget with TEXTURE_BINDING',
@@ -181,8 +180,8 @@ const POST_PROCESS_POLICY = {
       return (
         `fullscreen pass '${d.passName}' references reads key '${d.readsKey}' but that key is not ` +
         `declared as a graph color target, or the target is not sampleable as a texture. ` +
-        `First call graph.addColorTarget('${d.readsKey}', {format, size}) ` +
-        `(or check spelling) before addFullscreenPass(g, '${d.passName}', { shader, color, reads: ['${d.readsKey}'] }). ` +
+        `First declare graph color target '${d.readsKey}' with its format and size ` +
+        `(or check spelling) before the typed fullscreen pass '${d.passName}' reads it. ` +
         `If '${d.readsKey}' is a depth target, ensure it has TEXTURE_BINDING usage (0x04) ` +
         `and is declared via graph.addColorTarget. Consider switching pipeline if your pipeline does not expose a sampleable depth target.`
       );
@@ -238,13 +237,13 @@ const POST_PROCESS_POLICY = {
   }
 >;
 
-class PostProcessErrorClass extends Error {
-  readonly code: PostProcessErrorCode;
+class PostProcessErrorClass<C extends PostProcessErrorCode> extends Error {
+  readonly code: C;
   readonly expected: string;
   readonly hint: string;
-  readonly detail: PostProcessErrorDetail;
+  readonly detail: PostProcessErrorDetailFor<C>;
 
-  constructor(args: { code: PostProcessErrorCode; detail: PostProcessErrorDetail }) {
+  constructor(args: { code: C; detail: PostProcessErrorDetailFor<C> }) {
     const policy = POST_PROCESS_POLICY[args.code];
     const hint = policy.hint(args.detail);
     super(`post-process: ${args.code} (${hint})`);
@@ -261,11 +260,19 @@ class PostProcessErrorClass extends Error {
  * `C` and whose `detail` narrows to `PostProcessErrorDetailFor<C>`, so `if (err.code === 'X')`
  * simultaneously narrows `err.detail` (charter P3 + P4 discriminated union).
  */
-type PostProcessErrorVariant<C extends PostProcessErrorCode> = PostProcessErrorClass & {
+type PostProcessErrorVariant<C extends PostProcessErrorCode> = PostProcessErrorClass<C> & {
   readonly code: C;
   readonly detail: PostProcessErrorDetailFor<C>;
 };
 
+interface PostProcessErrorConstructor {
+  new <C extends PostProcessErrorCode>(args: {
+    code: C;
+    detail: PostProcessErrorDetailFor<C>;
+  }): PostProcessErrorVariant<C>;
+  readonly prototype: PostProcessErrorClass<PostProcessErrorCode>;
+}
+
 /**
  * Public PostProcessError type - mapped from the authoritative code union.
  *
@@ -283,14 +290,6 @@ export type PostProcessError = {
   [C in PostProcessErrorCode]: PostProcessErrorVariant<C>;
 }[PostProcessErrorCode];
 
-interface PostProcessErrorConstructor {
-  new <C extends PostProcessErrorCode>(args: {
-    code: C;
-    detail: PostProcessErrorDetailFor<C>;
-  }): PostProcessErrorVariant<C>;
-  readonly prototype: PostProcessErrorClass;
-}
-
 /**
  * PostProcessError constructor - `new PostProcessError({ code, detail })`.
  *
@@ -300,5 +299,4 @@ interface PostProcessErrorConstructor {
  * without manual cast (AppError pattern; TS class declarations cannot directly express
  * `<C> ... PostProcessErrorVariant<C>` polymorphism, hence the typed-cast affordance).
  */
-export const PostProcessError: PostProcessErrorConstructor =
-  PostProcessErrorClass as unknown as PostProcessErrorConstructor;
+export const PostProcessError: PostProcessErrorConstructor = PostProcessErrorClass;

package/src/prepare/prepared-graphics-resolver.ts

@@ -6,7 +6,10 @@ import {
   RenderFeaturePreparedStateMismatchError,
   RenderFeatureStageFailedError,
 } from '../errors/render';
-import type { RenderFeatureResolvedGpuBuffer } from '../features/prepared-gpu-work';
+import type {
+  PreparedGraphicsResourceLease,
+  RenderFeatureResolvedGpuBuffer,
+} from '../features/prepared-gpu-work';
 import type {
   RenderFeatureBindingsDescriptor,
   RenderFeaturePreparedRef,
@@ -96,9 +99,7 @@ export interface PreparedGraphicsResolver {
   release(): Result<void, RenderError>;
 }
 
-export interface PreparedGraphicsResourceLease {
-  release(): Result<void, RenderError>;
-}
+export type { PreparedGraphicsResourceLease } from '../features/prepared-gpu-work';
 
 export interface PreparedGraphicsResolvedSnapshot {
   readonly generation: number;

package/src/record/__tests__/material-slot-plan.unit.test.ts

@@ -1,11 +1,9 @@
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
 import { describe, expect, it } from 'vitest';
-import { createDerivedMaterialSlotPlan, materialBindingByteLength } from '../material-payload.js';
 import {
   buildMaterialSlotPlan,
   findRenderablePrefixForSlotCapacity,
   materialSlotCountForPrefix,
-} from '../material-slot-plan';
+} from '../frame';
 
 describe('material slot plan', () => {
   it('interns repeated snapshot identities across renderables', () => {
@@ -44,33 +42,3 @@ describe('material slot plan', () => {
     expect(materialSlotCountForPrefix(indices, 3)).toBe(5);
   });
 });
-
-describe('derived material slot plan', () => {
-  it('exposes one exact owner plan for numeric and texture entries', () => {
-    const plan = createDerivedMaterialSlotPlan([
-      { name: 'roughness', type: 'f32' },
-      { name: 'color', type: 'vec4' },
-      { name: 'albedo', type: 'texture2d' },
-    ]);
-    expect(plan.totalBytes).toBe(plan.layout.totalBytes);
-    expect(plan.numericMembers.map((member) => member.name)).toEqual(['roughness', 'color']);
-    expect(plan.coordinateRecords.map((record) => record.parameter)).toEqual(['albedo']);
-    expect(plan.layoutIdentity).toMatch(/^sha256-/);
-  });
-
-  it('uses the selected shared-PBR schema for the bind range, not a compact authored slot', () => {
-    expect(materialBindingByteLength(DEFAULT_STANDARD_PBR_PARAM_SCHEMA, 512)).toBe(288);
-    expect(
-      materialBindingByteLength(
-        [
-          { name: 'baseColor', type: 'color' },
-          { name: 'metallic', type: 'f32' },
-          { name: 'roughness', type: 'f32' },
-        ],
-        512,
-      ),
-    ).toBe(32);
-    expect(materialBindingByteLength([], 512)).toBe(512);
-    expect(materialBindingByteLength(undefined, 512)).toBe(512);
-  });
-});