@forgeax/engine-render 0.1.3 → 0.1.6

package/src/pipeline/index.ts

@@ -1,40 +0,0 @@
-import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
-import { err, ok, type Result } from '@forgeax/engine-types';
-import { PipelineError } from '../pipeline-errors';
-
-export const pipelineStages = ['extract', 'prepare', 'record'] as const;
-export type PipelineStage = (typeof pipelineStages)[number];
-
-/**
- * Compose the renderer-owned vertex-color axis from geometry projection facts.
- * Authored material definitions never participate in this decision.
- */
-export function variantSetFromVertexLayoutProjection(
-  projection: VertexLayoutProjection | undefined,
-  variantSet: string | undefined,
-): Result<string | undefined, PipelineError> {
-  const authoredColor = variantSet
-    ?.split('+')
-    .find((part) => part.startsWith('VERTEX_COLOR_AVAILABLE='));
-  if (authoredColor !== undefined) {
-    const authoredValue = authoredColor.slice('VERTEX_COLOR_AVAILABLE='.length);
-    const authored = authoredValue === 'true';
-    const hasColor = projection?.attributes.some((attribute) => attribute.key === 'color') ?? false;
-    if ((authoredValue !== 'true' && authoredValue !== 'false') || authored !== hasColor) {
-      return err(
-        new PipelineError({
-          code: 'vertex-color-variant-conflict',
-          detail: { authored, authoredValue, projected: hasColor, variantSet: variantSet ?? '' },
-        }),
-      );
-    }
-  }
-  if (projection === undefined) return ok(variantSet);
-  const hasColor = projection.attributes.some((attribute) => attribute.key === 'color');
-  if (hasColor && variantSet === '') return ok('');
-  const parts = (variantSet ?? '')
-    .split('+')
-    .filter((part) => part.length > 0 && !part.startsWith('VERTEX_COLOR_AVAILABLE='));
-  parts.push(`VERTEX_COLOR_AVAILABLE=${hasColor}`);
-  return ok(parts.sort().join('+'));
-}

package/src/pipeline-errors.ts

@@ -1,172 +0,0 @@
-// @forgeax/engine-runtime - render-pipeline error model
-// (feat-20260601-customizable-render-pipeline-seam-and-dogfood-rend M1 / w4).
-//
-// Closed PipelineErrorCode union + PipelineError discriminated-union class.
-// failure channels split by error nature (charter P3 + plan-strategy D-E):
-//   - 'pipeline-already-registered' (programmer error) -> registerPipeline THROWS a
-//     PipelineError, mirroring ShaderRegistry.installMaterialArtifact's Map.has -> throw
-//     fail-fast (research Finding 3). A second register under the same id is a coding
-//     mistake that must surface immediately.
-//   - 'pipeline-not-found' (runtime path) -> installPipeline returns Result.err with this
-//     code when the supplied handle resolves to no registered pipeline (stale / wrong
-//     handle). AI users branch on `err.code === 'pipeline-not-found'` by property access.
-//
-// D-1: a NEW independent union rather than folding into RuntimeErrorCode /
-// RenderGraphErrorCode (requirements OOS-6). RuntimeErrorCode's members are render / skin
-// / shadow domain; a separate union keeps the pipeline error surface cohesive and
-// additively evolvable (mirrors pick-errors.ts D-1 reasoning verbatim).
-//
-// PipelineError 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 M1 item 8 + AC-05 / AC-06; plan-strategy D-E; charter P3 / P4.
-
-/**
- * Closed union of render-pipeline error codes.
- *
- * AI users perform exhaustive `switch (err.code)` without a default and TS guards
- * completeness (AC-05).
- *
- * | code | channel | trigger |
- * |:--|:--|:--|
- * | `'pipeline-already-registered'` | throw | a second `registerPipeline(id, impl)` under an already-registered `id` |
- * | `'pipeline-not-found'` | `Result.err` | `installPipeline(handle)` where the handle resolves to no registered pipeline |
- */
-export type PipelineErrorCode = keyof typeof PIPELINE_POLICY;
-
-/**
- * Detail for `'pipeline-already-registered'`: the pipeline id that was already taken.
- * AI consumers read `.detail.id` by property access (charter P4), no message parsing.
- */
-export interface PipelinePreviouslyRegisteredDetail {
-  readonly id: string;
-}
-
-/**
- * Detail for `'pipeline-not-found'`: the raw u32 handle value that resolved to no
- * registered pipeline. Read via `.detail.handle` after the code guard.
- */
-export interface PipelineNotFoundDetail {
-  readonly handle: number;
-}
-
-export interface VertexColorVariantConflictDetail {
-  readonly authored: boolean;
-  readonly authoredValue: string;
-  readonly projected: boolean;
-  readonly variantSet: string;
-}
-
-/**
- * Conditional resolver from `PipelineErrorCode` to its detail payload type. Used by the
- * constructor signature so `new PipelineError({ code: 'X', detail })` narrows the
- * `detail` parameter to the variant payload at compile time.
- */
-export type PipelineErrorDetailFor<C extends PipelineErrorCode> =
-  C extends 'pipeline-already-registered'
-    ? PipelinePreviouslyRegisteredDetail
-    : C extends 'pipeline-not-found'
-      ? PipelineNotFoundDetail
-      : C extends 'vertex-color-variant-conflict'
-        ? VertexColorVariantConflictDetail
-        : never;
-
-/**
- * Tagged union of `.detail` payloads. The variants are unique by structural fields
- * (`{ id }` vs `{ handle }`).
- */
-export type PipelineErrorDetail = PipelineErrorDetailFor<PipelineErrorCode>;
-
-const PIPELINE_POLICY = {
-  'pipeline-already-registered': {
-    expected: 'each pipeline id is registered at most once',
-    hint: (detail) =>
-      `pipeline id '${(detail as PipelinePreviouslyRegisteredDetail).id}' is already ` +
-      'registered; same-id re-register is forbidden. Pick a distinct id ' +
-      '(engine builtins use the forgeax:: prefix; user pipelines use <package>::<id>).',
-  },
-  'pipeline-not-found': {
-    expected: 'installPipeline receives a handle to a registered pipeline',
-    hint: (detail) =>
-      `no pipeline is registered for handle ${(detail as PipelineNotFoundDetail).handle}. ` +
-      'First registerPipeline(id, impl), then register a RenderPipelineAsset ' +
-      '{ kind:"render-pipeline", pipelineId: id } and install the returned handle.',
-  },
-  'vertex-color-variant-conflict': {
-    expected: 'geometry projection and material variant agree on VERTEX_COLOR_AVAILABLE',
-    hint: (detail) =>
-      `authored VERTEX_COLOR_AVAILABLE=${(detail as VertexColorVariantConflictDetail).authoredValue} conflicts with ` +
-      `geometry projection=${(detail as VertexColorVariantConflictDetail).projected} in variant set '${(detail as VertexColorVariantConflictDetail).variantSet}'. ` +
-      'Remove the authored vertex-color axis and let geometry projection derive it.',
-  },
-} satisfies Record<
-  string,
-  {
-    readonly expected: string;
-    readonly hint: (detail: unknown) => string;
-  }
->;
-
-class PipelineErrorClass extends Error {
-  readonly code: PipelineErrorCode;
-  readonly expected: string;
-  readonly hint: string;
-  readonly detail: PipelineErrorDetail;
-
-  constructor(args: { code: PipelineErrorCode; detail: PipelineErrorDetail }) {
-    const policy = PIPELINE_POLICY[args.code];
-    const hint = policy.hint(args.detail);
-    super(`pipeline: ${args.code} (${hint})`);
-    this.name = 'PipelineError';
-    this.code = args.code;
-    this.expected = policy.expected;
-    this.hint = hint;
-    this.detail = args.detail;
-  }
-}
-
-/**
- * Variant intersection: a `PipelineErrorClass` instance whose `code` literal narrows to
- * `C` and whose `detail` narrows to `PipelineErrorDetailFor<C>`, so `if (err.code === 'X')`
- * simultaneously narrows `err.detail` (charter P3 + P4 discriminated union).
- */
-type PipelineErrorVariant<C extends PipelineErrorCode> = PipelineErrorClass & {
-  readonly code: C;
-  readonly detail: PipelineErrorDetailFor<C>;
-};
-
-/**
- * Public PipelineError type - discriminated union of the 2 variants.
- *
- * ```ts
- * function recover(err: PipelineError): string {
- *   switch (err.code) {
- *     case 'pipeline-already-registered': return `id taken: ${err.detail.id}`;
- *     case 'pipeline-not-found':          return `bad handle: ${err.detail.handle}`;
- *   }
- * }
- * ```
- */
-export type PipelineError = {
-  [C in PipelineErrorCode]: PipelineErrorVariant<C>;
-}[PipelineErrorCode];
-
-interface PipelineErrorConstructor {
-  new <C extends PipelineErrorCode>(args: {
-    code: C;
-    detail: PipelineErrorDetailFor<C>;
-  }): PipelineErrorVariant<C>;
-  readonly prototype: PipelineErrorClass;
-}
-
-/**
- * PipelineError constructor - `new PipelineError({ code, detail })`.
- *
- * The generic `C` is inferred from the literal `code` argument, which narrows `detail` to
- * the per-code payload (`PipelineErrorDetailFor<C>`) and narrows the return type to the
- * corresponding `PipelineErrorVariant<C>` so the call site walks the discriminated union
- * without manual cast (AppError pattern; TS class declarations cannot directly express
- * `<C> ... PipelineErrorVariant<C>` polymorphism, hence the typed-cast affordance).
- */
-export const PipelineError: PipelineErrorConstructor =
-  PipelineErrorClass as unknown as PipelineErrorConstructor;

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

@@ -1,16 +0,0 @@
-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

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

package/src/prepare/schema-readers.ts

@@ -1,20 +0,0 @@
-import type { RenderExtract } from '../extract/schema-readers';
-
-export interface PreparedRenderSchemas {
-  readonly meshAssetHandle: unknown;
-  readonly lightDirection: unknown;
-  readonly cameraProjection: number;
-  readonly cameraNear: number;
-  readonly cameraFar: number;
-}
-
-/** Prepare the extracted fields for record without substituting provisional defaults. */
-export function prepareRenderSchemas(frame: RenderExtract): PreparedRenderSchemas {
-  return {
-    meshAssetHandle: frame.mesh.assetHandle,
-    lightDirection: frame.light.direction,
-    cameraProjection: frame.camera.projection,
-    cameraNear: frame.camera.near,
-    cameraFar: frame.camera.far,
-  };
-}

package/src/record/__tests__/environment-record.test.ts

@@ -1,35 +0,0 @@
-import { World } from '@forgeax/engine-ecs';
-import { describe, expect, it } from 'vitest';
-import { Atmosphere, DirectionalLight, Skylight } from '../../index';
-import { extractFrames } from '../../render-system-extract';
-
-describe('ExtractedEnvironment record cutover', () => {
-  it('carries one atmosphere source and one co-located normalized Sun snapshot', () => {
-    const world = new World();
-    world
-      .spawn(
-        { component: Atmosphere, data: {} },
-        { component: DirectionalLight, data: { direction: [0, -1, 0], intensity: 2 } },
-      )
-      .unwrap();
-
-    const frame = extractFrames([world], 0);
-    expect(frame.environment.kind).toBe('atmosphere');
-    if (frame.environment.kind === 'atmosphere') {
-      expect(frame.environment.atmosphere.entity).toBe(frame.environment.atmosphere.sun.entity);
-      expect([...frame.environment.atmosphere.sun.direction]).toEqual([0, 1, 0]);
-      expect(frame.environment.atmosphere.sun.illuminance).toBe(2);
-    }
-  });
-
-  it('keeps solid-color ambient facts in none without entering the image lane', () => {
-    const world = new World();
-    world.spawn({ component: Skylight, data: { intensity: 0.25 } }).unwrap();
-
-    const frame = extractFrames([world], 0);
-    expect(frame.environment.kind).toBe('none');
-    if (frame.environment.kind === 'none') {
-      expect(frame.environment.skylight?.equirectHandle).toBe(0);
-    }
-  });
-});

package/src/record/__tests__/frame-targets.unit.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type { RenderSystemInternals } from '../../render-system';
-import type { ExtractedLights } from '../../render-system-extract';
-import { resolveSpotShadowMapSize } from '../frame-targets';
-
-function spotLights(mapSize: number, shadowAtlasTile = 0): ExtractedLights {
-  return {
-    directional: undefined,
-    directionalCount: 0,
-    point: [],
-    spot: [
-      {
-        kind: 'spot',
-        entity: 1,
-        position: new Float32Array([0, 4, 0]),
-        direction: new Float32Array([0, -1, 0]),
-        color: new Float32Array([1, 1, 1]),
-        intensity: 1,
-        invRangeSquared: 1,
-        cosInner: 1,
-        cosOuter: 0.5,
-        castShadow: true,
-        lightViewProj: new Float32Array(16),
-        mapSize,
-        nearPlane: 0.1,
-        farPlane: 50,
-        shadowAtlasTile,
-      },
-    ],
-    lightViewProj: undefined,
-    splitPlanes: undefined,
-    cascadeCount: undefined,
-    cascadeBlend: undefined,
-    shadowMapSize: undefined,
-    depthBias: undefined,
-    normalBias: undefined,
-    pcfKernelSize: undefined,
-    pointShadow: [],
-    directionalCsmConfig: undefined,
-    directionalCsmDirection: undefined,
-  } as unknown as ExtractedLights;
-}
-
-function internals(maxTextureDimension2D: number): RenderSystemInternals {
-  return { device: { limits: { maxTextureDimension2D } } } as unknown as RenderSystemInternals;
-}
-
-describe('spot-only shadow target sizing', () => {
-  it('resolves a non-zero per-tile viewport without a directional light', () => {
-    expect(resolveSpotShadowMapSize(internals(4096), spotLights(2048))).toBe(2048);
-    expect(resolveSpotShadowMapSize(internals(4096), spotLights(8192))).toBe(2048);
-    expect(resolveSpotShadowMapSize(internals(4096), spotLights(2048, -1))).toBeUndefined();
-  });
-});