@forgeax/engine-render 0.1.3 → 0.1.6

package/src/plugin.ts

@@ -1,15 +1,7 @@
 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';
@@ -18,6 +10,8 @@ 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 { SkyboxBackground } from './components/skybox-background';
+import { Skylight } from './components/skylight';
 import { SortKey } from './components/sort-key';
 import { SpotLight } from './components/spot-light';
 import { SpriteAnimation } from './components/sprite-animation';
@@ -26,14 +20,10 @@ 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,
@@ -63,75 +53,13 @@ function registerRenderComponents(world: World): () => void {
   };
 }
 
-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. */
+/** Install the built-in render ECS 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

@@ -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);
-  });
-});

package/src/record/__tests__/typed-frame-graph-plan.unit.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderFeaturePlannedFrame } from '../../features/plan';
+import {
+  type RenderFeatureGraphCandidate,
+  renderFeatureGraphPlanSignature,
+} from '../typed-frame-graph';
+
+function planned(generation: number, signature: string): RenderFeaturePlannedFrame {
+  return {
+    featureIdentity: 'synthetic.feature',
+    generation,
+    signature,
+    plan: { resources: [], passes: [] },
+  };
+}
+
+describe('typed frame graph feature plan authority', () => {
+  it('keys topology and last-known-good candidates by stable plan signature and generation', () => {
+    const first = renderFeatureGraphPlanSignature([planned(1, 'plan-a')]);
+    expect(renderFeatureGraphPlanSignature([planned(1, 'plan-a')])).toBe(first);
+    expect(renderFeatureGraphPlanSignature([planned(1, 'plan-b')])).not.toBe(first);
+    expect(renderFeatureGraphPlanSignature([planned(2, 'plan-a')])).not.toBe(first);
+  });
+
+  it('keys candidates only by producer plans', () => {
+    const candidate: RenderFeatureGraphCandidate = {
+      plans: [planned(1, 'plan-a')],
+      fullscreenEffects: new Map(),
+    };
+    expect(candidate.plans).toHaveLength(1);
+  });
+
+  it('keeps execution projection out of the public planned-frame vocabulary', () => {
+    const invalid: RenderFeaturePlannedFrame = {
+      ...planned(1, 'plan-a'),
+      // @ts-expect-error execution belongs to the graph candidate adapter, not the producer plan.
+      execution: {},
+    };
+    void invalid;
+  });
+});

package/src/record/__tests__/video-texture-view.unit.test.ts

@@ -1,3 +1,4 @@
+import { type DynamicTextureDevice, DynamicTextureStore } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import {
   VIDEO_ELEMENT_PROVIDER_KEY,
@@ -8,7 +9,6 @@ import { ok } from '@forgeax/engine-rhi';
 import type { Handle } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
-import { type DynamicTextureDevice, DynamicTextureStore } from '../../dynamic-texture-store';
 import type { RenderSystemRuntime } from '../../render-system';
 import { videoTextureView } from '../main-pass-material';