@forgeax/engine-render 0.1.2

package/src/plugin.ts

@@ -0,0 +1,137 @@
+import type { Component, World } from '@forgeax/engine-ecs';
+import type { Plugin } from '@forgeax/engine-plugin';
+import {
+  SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY,
+  type SceneAssetSkinResolver,
+  worldSetSceneInstantiateHook,
+} from '@forgeax/engine-scene';
+
+import { Camera } from './components/camera';
+import { DirectionalLight } from './components/directional-light';
+import { SkyboxBackground, Skylight } from './components/environment';
+import { GlyphText } from './components/glyph-text';
+import { Instances } from './components/instances';
+import { Layer } from './components/layer';
+import { MeshFilter } from './components/mesh-filter';
+import { MeshRenderer } from './components/mesh-renderer';
+import { PointLight } from './components/point-light';
+import { PointLightShadow } from './components/point-light-shadow';
+import { PostProcessParams } from './components/post-process-params';
+import { SceneInstance } from './components/scene-instance';
+import { SortKey } from './components/sort-key';
+import { SpotLight } from './components/spot-light';
+import { SpriteAnimation } from './components/sprite-animation';
+import { SpriteInstances } from './components/sprite-instances';
+import { SpriteRegionOverride } from './components/sprite-region-override';
+import { TileLayer } from './components/tile-layer';
+import { Tilemap } from './components/tilemap';
+import { Visibility } from './components/visibility';
+import type { RenderFeature } from './features';
+import type { Renderer } from './renderer';
+import { postSpawnResolveJoints } from './scene-instances/post-spawn-resolve-joints';
+
+const RENDER_COMPONENTS: readonly Component[] = [
+  Camera,
+  DirectionalLight,
+  GlyphText,
+  Instances,
+  Layer,
+  MeshFilter,
+  MeshRenderer,
+  PointLight,
+  PointLightShadow,
+  PostProcessParams,
+  SceneInstance,
+  SkyboxBackground,
+  Skylight,
+  SortKey,
+  SpotLight,
+  SpriteAnimation,
+  SpriteInstances,
+  SpriteRegionOverride,
+  TileLayer,
+  Tilemap,
+  Visibility,
+];
+
+function registerRenderComponents(world: World): () => void {
+  const leases = RENDER_COMPONENTS.map((component) =>
+    world.components.register(component).unwrap(),
+  );
+  return () => {
+    for (let index = leases.length - 1; index >= 0; index -= 1) leases[index]?.dispose();
+  };
+}
+
+function installSceneInstantiateHook(world: World): () => void {
+  worldSetSceneInstantiateHook(world, (currentWorld, root) => {
+    if (!currentWorld.hasResource(SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY)) {
+      return { ok: true };
+    }
+    const resolver = currentWorld.getResource<SceneAssetSkinResolver>(
+      SCENE_ASSET_SKIN_RESOLVER_RESOURCE_KEY,
+    );
+    return postSpawnResolveJoints(currentWorld, resolver, root);
+  });
+  return () => worldSetSceneInstantiateHook(world, null);
+}
+
+declare module '@forgeax/engine-plugin' {
+  interface EngineContextServices {
+    renderer?: Renderer;
+  }
+}
+
+/** Install the built-in render and authoring component vocabulary in one World. */
+export function renderComponentsPlugin(): Plugin {
+  return {
+    name: 'render-components',
+    inject: ['world'],
+    apply(ctx) {
+      ctx.effect(() => registerRenderComponents(ctx.world), 'render/components');
+      ctx.effect(() => installSceneInstantiateHook(ctx.world), 'render/scene-instantiate-hook');
+    },
+  };
+}
+
+/** Provide the renderer without transferring its host-owned lifetime. */
+export function rendererPlugin(renderer: Renderer): Plugin {
+  return {
+    name: 'renderer',
+    provide: 'renderer',
+    apply(ctx) {
+      ctx.provide('renderer', renderer);
+    },
+  };
+}
+
+/** Provide an App/Worker-owned Renderer and release it after dependent Fibers. */
+export function ownedRendererPlugin(renderer: Renderer): Plugin {
+  return {
+    name: 'renderer',
+    provide: 'renderer',
+    apply(ctx) {
+      ctx.provide('renderer', renderer);
+      ctx.effect(() => () => renderer.dispose(), 'render/renderer');
+    },
+  };
+}
+
+/** Install a producer at Renderer safe points and remove it with the owning Fiber. */
+export function renderFeaturePlugin(feature: RenderFeature<unknown>): Plugin {
+  return {
+    name: `render-feature:${feature.identity}`,
+    inject: ['renderer'],
+    async apply(ctx) {
+      const renderer = ctx.renderer;
+      if (renderer === undefined)
+        throw new Error('render feature plugin requires the renderer service');
+      const installed = await renderer.installRenderFeature(feature);
+      if (!installed.ok) throw installed.error;
+      return async () => {
+        const removed = await renderer.uninstallRenderFeature(feature);
+        if (!removed.ok) throw removed.error;
+      };
+    },
+  };
+}

package/src/post-process-errors.ts

@@ -0,0 +1,304 @@
+// @forgeax/engine-runtime - fullscreen post-process error model
+// (feat-20260604-resource-owning-render-graph-and-fullscreen-postpr M2 / w12;
+//  feat-20260609-learn-render-4-5-framebuffers-demo-offscreen-rt-an M1 / T-2
+//  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
+//     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
+//     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).
+//   - '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).
+//
+// Also per D-4: the postProcess.register 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.
+//
+// PostProcessError is exposed as a discriminated union (variant per code, AppError pattern)
+// so `if (err.code === 'X')` simultaneously narrows `err.detail` to the per-code payload.
+//
+// Related: requirements M2 AC-08 + AC-19; plan-strategy D-4 / D-9; charter P3 / P4;
+// feat-20260609 M1 plan-decisions D-2 (L-1 lock to scheme B - new closed-set member).
+
+/**
+ * Closed union of fullscreen post-process error codes.
+ *
+ * Exactly 7 members; AI users perform exhaustive `switch (err.code)` without a default
+ * and TS guards completeness (AC-08).
+ *
+ * | 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) |
+ * | `'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-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;
+
+/**
+ * Detail for `'post-process-already-registered'`: the post-process id that was already taken.
+ * AI consumers read `.detail.id` by property access (charter P4), no message parsing.
+ */
+export interface PostProcessPreviouslyRegisteredDetail {
+  readonly id: string;
+}
+
+/**
+ * Detail for `'post-process-not-found'`: the post-process id that resolved to no
+ * registered entry. Read via `.detail.id` after the code guard.
+ */
+export interface PostProcessNotFoundDetail {
+  readonly id: string;
+}
+
+/**
+ * Detail for `'fullscreen-input-not-found'`: the graph resource key that the
+ * per-pass resolve context could not resolve, plus the pass name that referenced
+ * it. Both fields are read via property access after `if (err.code === 'fullscreen-input-not-found')`
+ * (charter P4); the AI user immediately knows WHICH key to declare and WHICH
+ * pass needs wiring.
+ */
+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'). */
+  readonly passName: string;
+}
+
+/**
+ * Detail for `'ssao-radius-non-positive'`: the SSAO radius parameter was zero or negative.
+ * AI consumers read `.detail.paramName` / `.detail.value` by property access (charter P4).
+ */
+export interface SsaoRadiusNonPositiveDetail {
+  readonly paramName: string;
+  readonly value: number;
+}
+
+/**
+ * Detail for `'ssao-bias-negative'`: the SSAO bias parameter was negative.
+ * AI consumers read `.detail.paramName` / `.detail.value` by property access.
+ */
+export interface SsaoBiasNegativeDetail {
+  readonly paramName: string;
+  readonly value: number;
+}
+
+/**
+ * Detail for `'params-size-mismatch'`: the register call's byteSize / defaultValue.length
+ * is invalid. Carries `byteSize` (the declared size) and `actualLength` (defaultValue.length).
+ * AI consumers read `.detail.byteSize` / `.detail.actualLength` after the code guard.
+ */
+export interface PostProcessParamsSizeMismatchDetail {
+  readonly byteSize: number;
+  readonly actualLength: number;
+}
+
+/**
+ * Detail for `'params-update-size-mismatch'`: the per-frame data-driven write
+ * (PostProcessParams.data) had a byteLength that did not equal the registered
+ * `params.byteSize`. Carries `byteSize` (registered) + `actualLength` (the
+ * supplied data byteLength). AI consumers read `.detail.byteSize` /
+ * `.detail.actualLength` after the code guard.
+ *
+ * NOTE (feat-20260621 M-A2): this code is wired here so dispatchFullscreenPass
+ * can fail-fast on a mismatched per-frame write; the full error-model
+ * formalization (expected/hint refinement, JSDoc member count, public
+ * PostProcessError union variant) is finished in M-A4.
+ */
+export interface PostProcessParamsUpdateSizeMismatchDetail {
+  readonly byteSize: number;
+  readonly actualLength: number;
+}
+
+/**
+ * Conditional resolver from `PostProcessErrorCode` to its detail payload type. Used by the
+ * constructor signature so `new PostProcessError({ code: 'X', detail })` narrows the
+ * `detail` parameter to the variant payload at compile time.
+ */
+export type PostProcessErrorDetailFor<C extends PostProcessErrorCode> =
+  C extends 'post-process-already-registered'
+    ? PostProcessPreviouslyRegisteredDetail
+    : C extends 'post-process-not-found'
+      ? PostProcessNotFoundDetail
+      : C extends 'fullscreen-input-not-found'
+        ? FullscreenInputNotFoundDetail
+        : C extends 'ssao-radius-non-positive'
+          ? SsaoRadiusNonPositiveDetail
+          : C extends 'ssao-bias-negative'
+            ? SsaoBiasNegativeDetail
+            : C extends 'params-size-mismatch'
+              ? PostProcessParamsSizeMismatchDetail
+              : C extends 'params-update-size-mismatch'
+                ? PostProcessParamsUpdateSizeMismatchDetail
+                : never;
+
+/**
+ * Tagged union of `.detail` payloads. The variants are unique by structural fields
+ * (`{ id }` for the two id-by-string variants vs `{ readsKey, passName }` for the
+ * graph-resource-miss variant); the code discriminator narrows the intent across
+ * the two id-shaped variants.
+ */
+export type PostProcessErrorDetail = PostProcessErrorDetailFor<PostProcessErrorCode>;
+
+const POST_PROCESS_POLICY = {
+  'post-process-already-registered': {
+    expected: 'each post-process id is registered at most once',
+    hint: (detail) =>
+      `post-process id '${(detail as PostProcessPreviouslyRegisteredDetail).id}' is already ` +
+      'registered; same-id re-register is forbidden. Pick a distinct id ' +
+      '(engine builtins use the forgeax:: prefix; user passes use <package>::<id>).',
+  },
+  'post-process-not-found': {
+    expected: 'addFullscreenPass 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}).',
+  },
+  'fullscreen-input-not-found': {
+    expected: 'reads key must be a graph-declared colorTarget with TEXTURE_BINDING',
+    hint: (detail) => {
+      const d = detail as FullscreenInputNotFoundDetail;
+      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}'] }). ` +
+        `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.`
+      );
+    },
+  },
+  'ssao-radius-non-positive': {
+    expected: 'SSAO radius must be > 0',
+    hint: (detail) => {
+      const d = detail as SsaoRadiusNonPositiveDetail;
+      return (
+        `SSAO parameter '${d.paramName}' is ${d.value}, must be greater than 0. ` +
+        `Set config.ssao.${d.paramName} to a positive value (default 0.5) or disable SSAO with config.ssao.enabled = false.`
+      );
+    },
+  },
+  'ssao-bias-negative': {
+    expected: 'SSAO bias must be >= 0',
+    hint: (detail) => {
+      const d = detail as SsaoBiasNegativeDetail;
+      return (
+        `SSAO parameter '${d.paramName}' is ${d.value}, must be >= 0. ` +
+        `Set config.ssao.${d.paramName} to a non-negative value (default 0.025) or disable SSAO.`
+      );
+    },
+  },
+  'params-size-mismatch': {
+    expected: 'params.byteSize >= 16 and defaultValue.length === byteSize',
+    hint: (detail) => {
+      const d = detail as PostProcessParamsSizeMismatchDetail;
+      return (
+        `params.byteSize is ${d.byteSize} but defaultValue.length is ${d.actualLength}. ` +
+        'The UBO byteSize must be >= 16 B and defaultValue.length must equal byteSize. ' +
+        'Pass a defaultValue Uint8Array whose .length matches byteSize exactly.'
+      );
+    },
+  },
+  'params-update-size-mismatch': {
+    expected: 'PostProcessParams.data byteLength === registered params.byteSize',
+    hint: (detail) => {
+      const d = detail as PostProcessParamsUpdateSizeMismatchDetail;
+      return (
+        `PostProcessParams.data byteLength is ${d.actualLength} but the registered ` +
+        `params.byteSize is ${d.byteSize}. The per-frame data-driven write must match ` +
+        'the registered byteSize exactly; check the PostProcessParams.data you assign each frame.'
+      );
+    },
+  },
+} satisfies Record<
+  string,
+  {
+    readonly expected: string;
+    readonly hint: (detail: unknown) => string;
+  }
+>;
+
+class PostProcessErrorClass extends Error {
+  readonly code: PostProcessErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PostProcessErrorDetail;
+
+  constructor(args: { code: PostProcessErrorCode; detail: PostProcessErrorDetail }) {
+    const policy = POST_PROCESS_POLICY[args.code];
+    const hint = policy.hint(args.detail);
+    super(`post-process: ${args.code} (${hint})`);
+    this.name = 'PostProcessError';
+    this.code = args.code;
+    this.expected = policy.expected;
+    this.hint = hint;
+    this.detail = args.detail;
+  }
+}
+
+/**
+ * Variant intersection: a `PostProcessErrorClass` instance whose `code` literal narrows to
+ * `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 & {
+  readonly code: C;
+  readonly detail: PostProcessErrorDetailFor<C>;
+};
+
+/**
+ * Public PostProcessError type - mapped from the authoritative code union.
+ *
+ * ```ts
+ * function recover(err: PostProcessError): string {
+ *   switch (err.code) {
+ *     case 'post-process-already-registered': return `id taken: ${err.detail.id}`;
+ *     case 'post-process-not-found':          return `bad id: ${err.detail.id}`;
+ *     case 'fullscreen-input-not-found':      return `bad reads key: ${err.detail.readsKey} on pass ${err.detail.passName}`;
+ *   }
+ * }
+ * ```
+ */
+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 })`.
+ *
+ * The generic `C` is inferred from the literal `code` argument, which narrows `detail` to
+ * the per-code payload (`PostProcessErrorDetailFor<C>`) and narrows the return type to the
+ * corresponding `PostProcessErrorVariant<C>` so the call site walks the discriminated union
+ * 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;

package/src/prepare/__tests__/schema-readers.unit.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { prepareRenderSchemas } from '../schema-readers';
+
+describe('prepare schema readers', () => {
+  it('retains branded handles and projection bounds', () => {
+    const direction = new Float32Array([1, 0, 0]);
+    const prepared = prepareRenderSchemas({
+      mesh: { assetHandle: 11 },
+      light: { direction, intensity: 1 },
+      camera: { projection: 1, near: 0.1, far: 100 },
+    });
+    expect(prepared.meshAssetHandle).toBe(11);
+    expect(prepared.lightDirection).toBe(direction);
+    expect(prepared.cameraProjection).toBe(1);
+  });
+});

package/src/prepare/index.ts

@@ -0,0 +1,8 @@
+export type { PreparedFrame } from '../frame-chain';
+export { prepareFrame } from '../frame-chain';
+export {
+  createPreparedGraphicsResolver,
+  type PreparedGraphicsResolvedResource,
+  type PreparedGraphicsResolver,
+  type PreparedGraphicsResolverInput,
+} from './prepared-graphics-resolver';