@forgeax/engine-render 0.1.7 → 0.1.20

package/src/assembly/host-contract.ts

@@ -6,6 +6,7 @@ import type { ObservationUnavailableError, RenderError } from '../errors/render'
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
+import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
 import type {
   DrawOwnerOptions,
   FrameObservationRequest,
@@ -81,6 +82,9 @@ export interface RendererLegacyHostAdapter {
   observeCurrentFrame(
     options: FrameObservationOptions,
   ): Promise<RenderResult<FrameObservation, ObservationUnavailableError>>;
+  /** @internal Test-only current compiled graph target diagnostic. */
+  getCurrentGraphTarget(name: string): CurrentGraphTarget | undefined;
+  requestGraphTargetCapture(request: GraphTargetCaptureRequest): void;
   onLost(listener: RendererLostListener): () => void;
   onError(listener: RendererErrorListener): () => void;
   health(): HealthSnapshot;

package/src/assembly/renderer-frame-transaction.ts

@@ -0,0 +1,75 @@
+/** Staged frame state committed only after the renderer submit barrier. */
+export interface RendererFrameTransaction<T> {
+  readonly candidate: T;
+  readonly commit: () => T;
+  readonly abort: () => void;
+}
+
+export function stageRendererFrame<T>(
+  candidate: T,
+  onAbort: () => void = () => undefined,
+): RendererFrameTransaction<T> {
+  let closed = false;
+  return {
+    candidate,
+    commit: () => {
+      if (closed) throw new Error('renderer frame transaction is closed');
+      closed = true;
+      return candidate;
+    },
+    abort: () => {
+      if (closed) return;
+      closed = true;
+      onAbort();
+    },
+  };
+}
+
+export type RendererFrameStage = 'build' | 'execute' | 'finish' | 'submit';
+
+export interface RendererFrameStageFailure {
+  readonly stage: RendererFrameStage;
+}
+
+export type RendererFrameStageResult<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly stage: RendererFrameStage };
+
+export interface RendererFrameTransactionSteps<T> {
+  readonly build: () => RendererFrameStageResult<T>;
+  readonly execute: (candidate: T) => RendererFrameStageResult<void>;
+  readonly finish: (candidate: T) => RendererFrameStageResult<void>;
+  readonly submit: (candidate: T) => RendererFrameStageResult<void>;
+  readonly commit: (candidate: T) => void;
+  readonly abort?: (failure: RendererFrameStageFailure) => void;
+}
+
+/**
+ * Run the four renderer stages behind one commit barrier. A stage can expose
+ * only a structured failure; the candidate is never published until submit
+ * has returned success, so a failed frame cannot advance last-known-good state.
+ */
+export function executeRendererFrameTransaction<T>(
+  steps: RendererFrameTransactionSteps<T>,
+):
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: RendererFrameStageFailure } {
+  const fail = (
+    stage: RendererFrameStage,
+  ): { readonly ok: false; readonly error: RendererFrameStageFailure } => {
+    const error = { stage } as const;
+    steps.abort?.(error);
+    return { ok: false, error };
+  };
+
+  const built = steps.build();
+  if (!built.ok) return fail('build');
+  const executed = steps.execute(built.value);
+  if (!executed.ok) return fail('execute');
+  const finished = steps.finish(built.value);
+  if (!finished.ok) return fail('finish');
+  const submitted = steps.submit(built.value);
+  if (!submitted.ok) return fail('submit');
+  steps.commit(built.value);
+  return { ok: true, value: built.value };
+}

package/src/assembly/renderer-inspection.ts

@@ -0,0 +1,112 @@
+import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
+import type { RhiCanvasSurfacePresentationProof, TextureFormat } from '@forgeax/engine-rhi';
+import {
+  type RenderOutputInspection,
+  type RenderStandardOutputColorInspection,
+  STANDARD_OUTPUT_TRANSFORM_FEATURE_ID,
+} from '../render-contract';
+
+/** Inputs owned by the renderer assembly for one detached output projection. */
+export interface RendererOutputInspectionInput {
+  readonly graph: CompiledRenderGraphInfo | undefined;
+  readonly surfaceAvailable: boolean;
+  readonly surfaceStorage: TextureFormat;
+  readonly surfaceDisplay: TextureFormat;
+  readonly surfaceProfile?: 'dual-view' | 'raw-only';
+  readonly rgba16floatRenderable: boolean;
+  readonly presentationProof?: RhiCanvasSurfacePresentationProof | undefined;
+}
+
+function isSrgbFormat(format: TextureFormat): boolean {
+  return format === 'rgba8unorm-srgb' || format === 'bgra8unorm-srgb';
+}
+
+function writesSurface(pass: CompiledRenderGraphInfo['passes'][number]): boolean {
+  return pass.accesses.some(
+    (access) =>
+      (access.resource === 'surface' || access.resource.startsWith('surface.')) &&
+      access.usage === 'color-attachment',
+  );
+}
+
+/**
+ * Project output facts from the committed graph and physical surface only.
+ * Profile fields are deliberately not consulted: a transform pass, a real
+ * intermediate target, and the final endpoint/domain are graph facts.
+ */
+export function projectRendererOutputInspection(
+  input: RendererOutputInspectionInput,
+): RenderOutputInspection {
+  const graph = input.graph;
+  const outputTransformPass = graph?.passes.find(
+    (pass) => pass.name === 'output-transform' || pass.name === 'present',
+  );
+  const surfaceResource = graph?.resources.find(
+    (resource) => resource.kind === 'texture' && resource.label === 'surface',
+  );
+  const writesFinalSurface = graph?.passes.some(writesSurface) === true;
+  const surfaceDomain =
+    surfaceResource?.descriptor?.kind === 'texture' ? surfaceResource.descriptor.domain : undefined;
+  const directEncodedSurface =
+    writesFinalSurface && surfaceDomain === 'display-encoded' && isSrgbFormat(input.surfaceDisplay);
+  const displayEncoded =
+    input.surfaceAvailable &&
+    writesFinalSurface &&
+    (outputTransformPass !== undefined || directEncodedSurface);
+  const intermediate = graph?.resources.find(
+    (resource) =>
+      resource.kind === 'texture' &&
+      resource.label === 'standard-output-color' &&
+      resource.descriptor?.kind === 'texture',
+  );
+  const standardOutputColor: RenderStandardOutputColorInspection | undefined =
+    intermediate?.descriptor?.kind === 'texture'
+      ? {
+          format: intermediate.descriptor.format,
+          ...(intermediate.descriptor.domain === undefined
+            ? {}
+            : { domain: intermediate.descriptor.domain }),
+          width: intermediate.descriptor.width,
+          height: intermediate.descriptor.height,
+          sampleCount: intermediate.descriptor.sampleCount,
+          usage: intermediate.derivedUsage,
+        }
+      : undefined;
+  const outputReady = input.surfaceAvailable && displayEncoded;
+
+  return {
+    ...(outputTransformPass === undefined
+      ? {}
+      : { outputTransform: STANDARD_OUTPUT_TRANSFORM_FEATURE_ID }),
+    displayEncoded,
+    ...(intermediate?.descriptor?.kind === 'texture'
+      ? { intermediateFormat: intermediate.descriptor.format }
+      : {}),
+    ...(input.surfaceProfile === undefined ? {} : { surfaceProfile: input.surfaceProfile }),
+    graphPassNames: graph?.passes.map((pass) => pass.name) ?? [],
+    ...(standardOutputColor === undefined ? {} : { standardOutputColor }),
+    surfaceStorage: input.surfaceStorage,
+    surfaceDisplay: input.surfaceDisplay,
+    endpoint: 'surface.storage.raw',
+    capability: outputReady
+      ? input.rgba16floatRenderable
+        ? 'rgba16float-renderable'
+        : 'surface-raw-endpoint'
+      : 'unavailable',
+    ...(input.presentationProof === undefined
+      ? {}
+      : { presentationProof: input.presentationProof }),
+    error: outputReady
+      ? undefined
+      : {
+          code: 'inspection-facts-unavailable',
+          expected: 'a committed graph writes an encoded surface endpoint',
+          hint: 'draw a frame before consuming output inspection facts',
+        },
+  };
+}
+
+/** Detached inspection projection helper; live renderer objects never cross this boundary. */
+export function detachRendererInspection<T extends object>(inspection: T): Readonly<T> {
+  return Object.freeze({ ...inspection });
+}

package/src/assembly/renderer-lifecycle.ts

@@ -0,0 +1,6 @@
+import type { RendererState } from '../render-contract';
+
+/** Lifecycle states that may accept a new frame operation. */
+export function isRendererStateOperational(state: RendererState): boolean {
+  return state === 'alive';
+}

package/src/components/__tests__/motion-blur.unit.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { MotionBlur } from '../motion-blur';
+
+describe('MotionBlur component schema', () => {
+  it('is a single-semantic component with bounded authoring fields', () => {
+    expect(MotionBlur.name).toBe('MotionBlur');
+    expect(MotionBlur.fields).toMatchObject({
+      shutterAngle: { type: 'f32', default: 180 },
+      maxRadiusPixels: { type: 'f32', default: 32 },
+      sampleCount: { type: 'f32', default: 8 },
+    });
+    expect(MotionBlur.fields).not.toHaveProperty('enabled');
+  });
+});

package/src/components/__tests__/schema-contract.unit.test.ts

@@ -1,10 +1,15 @@
 import { describe, expect, it } from 'vitest';
-import { Camera, DirectionalLight, MeshFilter } from '../index';
+import { ANTIALIAS_TAA, Atmosphere, Camera, DirectionalLight, Fog, MeshFilter } from '../index';
 
 describe('canonical render schema owners', () => {
   it('keeps mesh, light, and camera facts on their component owners', () => {
     expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
     expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
     expect(Camera.fields.projection.default).toBe(0);
+    expect(Camera.fields.antialias.default).toBe(0);
+    expect(Camera.fields.historyVersion.default).toBe(0);
+    expect(ANTIALIAS_TAA).toBe(3);
+    expect(Atmosphere.fields.turbidity.type).toBe('f32');
+    expect(Fog.fields.density.type).toBe('f32');
   });
 });

package/src/components/atmosphere.ts

@@ -0,0 +1,10 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Analytic atmosphere authoring facts; the directional light supplies the sun. */
+export const Atmosphere = defineComponent('Atmosphere', {
+  turbidity: { type: 'f32', default: 2 },
+  rayleigh: { type: 'f32', default: 1 },
+  mieCoefficient: { type: 'f32', default: 0.005 },
+  mieDirectionalG: { type: 'f32', default: 0.8 },
+  sunAngularRadius: { type: 'f32', default: 0.004675 },
+});

package/src/components/camera.ts

@@ -349,7 +349,8 @@ export const Camera = defineComponent('Camera', {
 // token's schema, which is itself derived from Camera.fields[k].type (D-A7).
 // This replaces the hand-maintained CameraDataPod interface — the field set
 // lives exclusively in the Camera component definition above.
-type CameraPod = ShapeOf<SchemaOf<typeof Camera>>;
+export type CameraData = ShapeOf<SchemaOf<typeof Camera>>;
+type CameraPod = CameraData;
 
 // ─── Camera factory functions (w13 SSOT refactoring) ─────────────────────
 //

package/src/components/fog.ts

@@ -0,0 +1,9 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Optional height-aware aerial fog, independent from environment source. */
+export const Fog = defineComponent('Fog', {
+  color: { type: 'array<f32, 3>', default: new Float32Array([0.5, 0.5, 0.5]) },
+  density: { type: 'f32', default: 0.01 },
+  heightFalloff: { type: 'f32', default: 0 },
+  maxOpacity: { type: 'f32', default: 1 },
+});

package/src/components/index.ts

@@ -1,10 +1,13 @@
+export * from './atmosphere';
 export * from './camera';
 export * from './directional-light';
+export * from './fog';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';
 export { Lines } from './lines';
 export * from './mesh-filter';
 export * from './mesh-renderer';
+export { MotionBlur } from './motion-blur';
 export { PointLight } from './point-light';
 export { PointLightShadow } from './point-light-shadow';
 export {

package/src/components/light-helpers.ts

@@ -155,6 +155,10 @@ export function validateSpotLightData(
   if (pcfKernelSize < 1 || pcfKernelSize % 2 === 0) {
     return err(new ShadowInvalidConfigError('pcfKernelSize', pcfKernelSize, 1));
   }
+  const shadowIntensity = (data.shadowIntensity as number | undefined) ?? 1;
+  if (!Number.isFinite(shadowIntensity) || shadowIntensity < 0 || shadowIntensity > 1) {
+    return err(new ShadowInvalidConfigError('shadowIntensity', shadowIntensity, 0, 1));
+  }
   return ok(undefined);
 }
 

package/src/components/motion-blur.ts

@@ -0,0 +1,8 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Active-camera motion blur authoring data; presence enables the feature. */
+export const MotionBlur = defineComponent('MotionBlur', {
+  shutterAngle: { type: 'f32', default: 180 },
+  maxRadiusPixels: { type: 'f32', default: 32 },
+  sampleCount: { type: 'f32', default: 8 },
+});

package/src/components/spot-light.ts

@@ -21,8 +21,8 @@
 // spotCount === 0" (M5 / w25).
 //
 // feat-20260625-spot-light-shadow-mapping M1 w4: embedded castShadow (default true)
-// + 6 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
-// pcfKernelSize) aligned with DirectionalLight vocabulary (plan-strategy D-6;
+// + 7 shadow fields (mapSize / depthBias / normalBias / nearPlane / farPlane /
+// pcfKernelSize / shadowIntensity) aligned with DirectionalLight vocabulary (plan-strategy D-6;
 // charter P4 consistent abstraction). Zero-config spawns cast spot shadows;
 // set castShadow:false to opt out (validate short-circuits on false, AC-03).
 // Shadow atlas cap of 4 is enforced at extract stage, not component layer (OOS-5).
@@ -37,6 +37,17 @@
 
 import { defineComponent } from '@forgeax/engine-ecs';
 
+export interface SpotLightProjector {
+  readonly guid: string;
+  readonly generation: number;
+  readonly revision: number;
+}
+
+export interface SpotLightAuthoring {
+  /** Optional GUID-backed TextureAsset projector; absent keeps the normal spot path. */
+  readonly projector?: SpotLightProjector;
+}
+
 /**
  * Cone-restricted spot light (KHR_lights_punctual `spot` type).  Casts shadows
  * by default (castShadow defaults to true) — zero-config spawns project hard
@@ -71,6 +82,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   nearPlane                        — shadow-camera near (default 0.1)
  *   farPlane                         — shadow-camera far (default 50)
  *   pcfKernelSize odd >= 1           — PCF kernel width (default 3)
+ *   shadowIntensity in [0,1]         — residual light in shadow (default 1)
  *
  * Atlas capacity is capped at 4 castShadow spot lights by the extract stage;
  * the 5th light onward keeps direct illumination but shadowAtlasTile = -1
@@ -114,11 +126,18 @@ export const SpotLight = defineComponent('SpotLight', {
   outerConeDeg: { type: 'f32', default: 45 },
   // Shadow opt-out gate: defaults to true so zero-config spawns cast shadows.
   castShadow: { type: 'bool', default: true },
-  // 6 shadow fields aligned with DirectionalLight (plan-strategy D-6).
+  // 7 shadow fields aligned with the shared light shadow vocabulary.
   mapSize: { type: 'f32', default: 2048 },
   depthBias: { type: 'f32', default: 0.005 },
   normalBias: { type: 'f32', default: 0.05 },
   nearPlane: { type: 'f32', default: 0.1 },
   farPlane: { type: 'f32', default: 50 },
   pcfKernelSize: { type: 'f32', default: 3 },
+  // Three's SpotLight.shadow.intensity is the fraction of visibility applied
+  // to a shadowed contribution. Keep it in the author-facing [0,1] domain;
+  // extract/record transport this one fact to surface and volume consumers.
+  shadowIntensity: { type: 'f32', default: 1 },
+  // Shared TextureAsset identity; publication and residency remain owned by
+  // the existing asset and GPU resource owners.
+  projector: { type: 'shared<TextureAsset>', simulationTransient: true },
 });

package/src/construct-renderer.ts

@@ -1,5 +1,5 @@
 import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
-import type { RhiBackendPack } from './assembly/backend-contract';
+import { EngineEnvironmentError, type RhiBackendPack } from './assembly/backend-contract';
 import type { BundlerOptions } from './assembly/factory';
 import { createRenderer, exposeRenderer } from './assembly/factory';
 import type {
@@ -30,12 +30,46 @@ export interface RendererHostAssembly {
   readonly assets: AssetRegistry;
 }
 
+function describeRendererInitializationFailure(error: unknown): string {
+  const candidate = error as unknown as {
+    readonly code?: unknown;
+    readonly hint?: unknown;
+    readonly detail?: unknown;
+  };
+  const detail = candidate.detail;
+  if (typeof detail === 'object' && detail !== null && 'compilerMessages' in detail) {
+    const messages = (detail as { readonly compilerMessages?: unknown }).compilerMessages;
+    if (Array.isArray(messages)) {
+      const compilerMessages = messages.map((message) => {
+        const value = message as {
+          readonly message?: unknown;
+          readonly type?: unknown;
+          readonly lineNum?: unknown;
+          readonly linePos?: unknown;
+          readonly offset?: unknown;
+          readonly length?: unknown;
+        };
+        return {
+          message: value.message,
+          type: value.type,
+          lineNum: value.lineNum,
+          linePos: value.linePos,
+          offset: value.offset,
+          length: value.length,
+        };
+      });
+      return `${String(candidate.code)}: ${String(candidate.hint)}; detail=${JSON.stringify({ compilerMessages })}`;
+    }
+  }
+  return `${String(candidate.code)}: ${String(candidate.hint)}; detail=${JSON.stringify(detail)}`;
+}
+
 export async function constructRendererHost(
   canvas: unknown,
   options?: RendererOptions,
   bundler?: BundlerOptions,
   backend?: RhiBackendPack,
-): Promise<RenderResult<RendererHostAssembly, RenderError>> {
+): Promise<RenderResult<RendererHostAssembly, RenderError | EngineEnvironmentError>> {
   try {
     const implementation = await createRenderer(canvas, options, bundler, backend);
     const ready = await implementation.initialization;
@@ -44,7 +78,7 @@ export async function constructRendererHost(
         ok: false,
         error: new RendererContractFailureError(
           'construct',
-          `${ready.error.code}: ${ready.error.hint}`,
+          describeRendererInitializationFailure(ready.error),
         ),
       };
     }
@@ -58,6 +92,9 @@ export async function constructRendererHost(
       },
     };
   } catch (cause) {
+    if (cause instanceof EngineEnvironmentError) {
+      return { ok: false, error: cause };
+    }
     const detail = cause instanceof Error ? cause.message : String(cause);
     return {
       ok: false,

package/src/device/device-scope.ts

@@ -77,6 +77,15 @@ export class DeviceScope {
     return [...this.children];
   }
 
+  /** Create a renderer-owned child scope without exposing a second device owner. */
+  createChild(owner: string): DeviceScope {
+    if (this.lifecycleState !== 'active') {
+      throw new Error('Cannot create a child DeviceScope from an inactive scope.');
+    }
+    if (owner.length === 0) throw new TypeError('DeviceScope child owner must not be empty.');
+    return new DeviceScope(this.generation, owner, this);
+  }
+
   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 });
@@ -128,8 +137,13 @@ export class DeviceScope {
     return resources;
   }
 
+  /** Mark an active child as retiring without releasing in-flight resources. */
+  beginRetire(): void {
+    if (this.lifecycleState === 'active') this.lifecycleState = 'retiring';
+  }
+
   retire(): void {
-    if (this.lifecycleState !== 'active') return;
+    if (this.lifecycleState !== 'active' && this.lifecycleState !== 'retiring') return;
     this.lifecycleState = 'retiring';
     this._clearResources();
     this.lifecycleState = 'retired';