@forgeax/engine-render 0.1.32 → 0.1.34

package/src/cloud/temporal.ts

@@ -0,0 +1,226 @@
+import type { CloudQuality } from '../components/cloud-layer';
+
+export type CloudTemporalResetReason =
+  | 'authoring-generation'
+  | 'camera-cut'
+  | 'resize'
+  | 'recovery'
+  | 'time-discontinuity'
+  | 'cloud-shadow-revision'
+  | 'device-generation'
+  | 'history-missing'
+  | 'reprojection-outside'
+  | 'scene-depth-disocclusion';
+
+export interface CloudTemporalSignature {
+  readonly sourceKey: string;
+  readonly viewId: string;
+  readonly authoringGeneration: number;
+  readonly cloudShadowRevision: number;
+  readonly cameraRevision: number;
+  readonly deviceGeneration: number;
+  readonly width: number;
+  readonly height: number;
+  readonly timeSeconds: number;
+  readonly quality: CloudQuality;
+  /** Scene-depth producer revision used to reject disoccluded history. */
+  readonly sceneDepthVersion?: number;
+}
+
+export interface CloudHistory {
+  readonly width: number;
+  readonly height: number;
+  readonly signature: string;
+  readonly temporal: CloudTemporalSignature;
+  readonly generation: number;
+  readonly valid: boolean;
+}
+
+export interface CloudTemporalDecision {
+  readonly reset: boolean;
+  readonly reasons: readonly CloudTemporalResetReason[];
+  readonly signature: string;
+  readonly history: CloudHistory | undefined;
+}
+
+export interface CloudTemporalFrame {
+  readonly signature: CloudTemporalSignature;
+  readonly history: CloudHistory | undefined;
+  readonly reset: boolean;
+  readonly reasons: readonly CloudTemporalResetReason[];
+}
+
+export interface CloudHistoryReprojectionInput {
+  readonly currentDepth: number;
+  readonly historyDepth: number;
+  readonly motion: readonly [number, number];
+  readonly currentPixel: readonly [number, number];
+  readonly historySize: readonly [number, number];
+  readonly depthTolerance?: number;
+}
+
+export interface CloudHistoryReprojection {
+  readonly accepted: boolean;
+  readonly historyUv: readonly [number, number];
+  readonly weight: number;
+  readonly reason: 'accepted' | 'outside' | 'depth-disocclusion';
+}
+
+export function cloudTemporalSignature(input: CloudTemporalSignature): string {
+  return [
+    'cloud-temporal-v1',
+    input.viewId,
+    input.sourceKey,
+    input.authoringGeneration,
+    input.cloudShadowRevision,
+    input.cameraRevision,
+    input.deviceGeneration,
+    input.width,
+    input.height,
+    input.timeSeconds,
+    input.quality,
+    input.sceneDepthVersion ?? 0,
+  ].join(':');
+}
+
+function sameLayout(left: CloudTemporalSignature, right: CloudTemporalSignature): boolean {
+  return left.viewId === right.viewId && left.width === right.width && left.height === right.height;
+}
+
+/** Compare the facts that make a cloud history safe to reuse. */
+export function cloudTemporalResetReasons(
+  previous: CloudTemporalSignature | undefined,
+  next: CloudTemporalSignature,
+  options: { readonly cameraCut?: boolean; readonly recovery?: boolean } = {},
+): readonly CloudTemporalResetReason[] {
+  if (previous === undefined) return ['history-missing'];
+  const reasons: CloudTemporalResetReason[] = [];
+  if (
+    previous.sourceKey !== next.sourceKey ||
+    previous.authoringGeneration !== next.authoringGeneration
+  ) {
+    reasons.push('authoring-generation');
+  }
+  if (previous.cloudShadowRevision !== next.cloudShadowRevision)
+    reasons.push('cloud-shadow-revision');
+  if (previous.deviceGeneration !== next.deviceGeneration) reasons.push('device-generation');
+  if (
+    previous.sceneDepthVersion !== undefined &&
+    next.sceneDepthVersion !== undefined &&
+    previous.sceneDepthVersion !== next.sceneDepthVersion
+  ) {
+    reasons.push('scene-depth-disocclusion');
+  }
+  if (!sameLayout(previous, next)) reasons.push('resize');
+  if (options.cameraCut === true || previous.cameraRevision !== next.cameraRevision)
+    reasons.push('camera-cut');
+  const dt = next.timeSeconds - previous.timeSeconds;
+  if (!Number.isFinite(dt) || dt < 0 || dt > 0.5) reasons.push('time-discontinuity');
+  if (options.recovery === true) reasons.push('recovery');
+  return Object.freeze(reasons);
+}
+
+export function createCloudHistory(
+  signature: CloudTemporalSignature,
+  generation: number,
+  valid = false,
+): CloudHistory {
+  return Object.freeze({
+    width: Math.max(1, Math.floor(signature.width)),
+    height: Math.max(1, Math.floor(signature.height)),
+    signature: cloudTemporalSignature(signature),
+    temporal: Object.freeze({ ...signature }),
+    generation,
+    valid,
+  });
+}
+
+/** Per-view histories are keyed by the renderer's view identity. */
+export class CloudHistoryStore {
+  private readonly maxViews: number;
+  private readonly entries = new Map<
+    string,
+    { readonly history: CloudHistory; readonly signature: CloudTemporalSignature }
+  >();
+
+  constructor(maxViews = 4) {
+    this.maxViews = Math.max(1, Math.floor(maxViews));
+  }
+
+  begin(
+    signature: CloudTemporalSignature,
+    options: { readonly cameraCut?: boolean; readonly recovery?: boolean } = {},
+  ): CloudTemporalDecision {
+    const key = signature.viewId;
+    const previousEntry = this.entries.get(key);
+    const previous = previousEntry?.history;
+    const reasons = cloudTemporalResetReasons(previousEntry?.signature, signature, options);
+    const reset = reasons.length > 0;
+    return Object.freeze({
+      reset,
+      reasons,
+      signature: cloudTemporalSignature(signature),
+      history: reset ? undefined : previous,
+    });
+  }
+
+  commit(signature: CloudTemporalSignature, history: CloudHistory): void {
+    if (
+      history.width !== Math.max(1, Math.floor(signature.width)) ||
+      history.height !== Math.max(1, Math.floor(signature.height))
+    ) {
+      this.entries.delete(signature.viewId);
+      return;
+    }
+    this.entries.set(signature.viewId, { history, signature: Object.freeze({ ...signature }) });
+    while (this.entries.size > this.maxViews) {
+      const oldest = this.entries.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.entries.delete(oldest);
+    }
+  }
+
+  reset(viewId?: string): void {
+    if (viewId === undefined) this.entries.clear();
+    else this.entries.delete(viewId);
+  }
+
+  get(viewId: string): CloudHistory | undefined {
+    return this.entries.get(viewId)?.history;
+  }
+
+  dispose(): void {
+    this.entries.clear();
+  }
+}
+
+/** Project one current pixel into the previous cloud history. */
+export function reprojectCloudHistory(
+  input: CloudHistoryReprojectionInput,
+  historyWeight = 0.9,
+): CloudHistoryReprojection {
+  const width = Math.max(1, input.historySize[0] ?? 1);
+  const height = Math.max(1, input.historySize[1] ?? 1);
+  const uv: [number, number] = [
+    ((input.currentPixel[0] ?? 0) - (input.motion[0] ?? 0)) / width,
+    ((input.currentPixel[1] ?? 0) - (input.motion[1] ?? 0)) / height,
+  ];
+  if (uv[0] < 0 || uv[0] > 1 || uv[1] < 0 || uv[1] > 1) {
+    return { accepted: false, historyUv: uv, weight: 0, reason: 'outside' };
+  }
+  const depthTolerance =
+    input.depthTolerance ?? Math.max(0.01, Math.abs(input.currentDepth) * 0.02);
+  if (
+    !Number.isFinite(input.currentDepth) ||
+    !Number.isFinite(input.historyDepth) ||
+    Math.abs(input.currentDepth - input.historyDepth) > depthTolerance
+  ) {
+    return { accepted: false, historyUv: uv, weight: 0, reason: 'depth-disocclusion' };
+  }
+  return {
+    accepted: true,
+    historyUv: uv,
+    weight: Math.min(0.99, Math.max(0, historyWeight)),
+    reason: 'accepted',
+  };
+}

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

@@ -8,6 +8,7 @@ describe('MotionBlur component schema', () => {
       shutterAngle: { type: 'f32', default: 180 },
       maxRadiusPixels: { type: 'f32', default: 32 },
       sampleCount: { type: 'f32', default: 8 },
+      targetFps: { type: 'f32', default: 60 },
     });
     expect(MotionBlur.fields).not.toHaveProperty('enabled');
   });

package/src/components/atmosphere.ts

@@ -7,4 +7,8 @@ export const Atmosphere = defineComponent('Atmosphere', {
   mieCoefficient: { type: 'f32', default: 0.005 },
   mieDirectionalG: { type: 'f32', default: 0.8 },
   sunAngularRadius: { type: 'f32', default: 0.004675 },
+  /** Independent multiplier for the analytic circumsolar lobe. */
+  circumsolarStrength: { type: 'f32', default: 1 },
+  /** Relative angular width of the analytic circumsolar lobe. */
+  circumsolarWidth: { type: 'f32', default: 1 },
 });

package/src/components/barrel-distortion.ts

@@ -0,0 +1,46 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { BarrelDistortionInvalidParameterError } from '../errors/render';
+
+/** Camera companion that applies the bounded first-order barrel model. */
+export const BarrelDistortion = defineComponent('BarrelDistortion', {
+  strength: { type: 'f32', default: 0 },
+  centerX: { type: 'f32', default: 0.5 },
+  centerY: { type: 'f32', default: 0.5 },
+});
+
+export type BarrelDistortionData = ShapeOf<SchemaOf<typeof BarrelDistortion>>;
+
+const DEFAULT_BARREL_DISTORTION: BarrelDistortionData = Object.freeze({
+  strength: 0,
+  centerX: 0.5,
+  centerY: 0.5,
+});
+
+function invalid(
+  field: 'strength' | 'centerX' | 'centerY',
+  value: number,
+  expected: string,
+): BarrelDistortionInvalidParameterError {
+  return new BarrelDistortionInvalidParameterError({ field, value, expected });
+}
+
+/** Validate and detach camera-owned barrel authoring data. */
+export function validateBarrelDistortionParameters(
+  input: Partial<BarrelDistortionData> | undefined,
+): Result<BarrelDistortionData, BarrelDistortionInvalidParameterError> {
+  const value = input ?? {};
+  const strength = value.strength ?? DEFAULT_BARREL_DISTORTION.strength;
+  const centerX = value.centerX ?? DEFAULT_BARREL_DISTORTION.centerX;
+  const centerY = value.centerY ?? DEFAULT_BARREL_DISTORTION.centerY;
+  if (!Number.isFinite(strength) || strength < 0 || strength > 0.35) {
+    return err(invalid('strength', strength, 'finite and in [0, 0.35]'));
+  }
+  if (!Number.isFinite(centerX) || centerX < 0 || centerX > 1) {
+    return err(invalid('centerX', centerX, 'finite and in [0, 1]'));
+  }
+  if (!Number.isFinite(centerY) || centerY < 0 || centerY > 1) {
+    return err(invalid('centerY', centerY, 'finite and in [0, 1]'));
+  }
+  return ok(Object.freeze({ strength, centerX, centerY }));
+}

package/src/components/camera.ts

@@ -1,9 +1,7 @@
 // @forgeax/engine-render - Camera (projection variant + ortho extension).
 //
-// Schema: 9 f32 columns — perspective quartet (fov + aspect + near + far)
-// + projection discriminator (0 = perspective, 1 = orthographic) + ortho
-// quartet (left + right + bottom + top). The view matrix continues to be
-// derived from the entity's Transform (AC-06 case B fires
+// Schema: projection, output, Bloom, and lifecycle columns. The view matrix
+// continues to be derived from the entity's Transform (AC-06 case B fires
 // 'render-system-no-camera' when 0 such entities exist).
 //
 // Projection discriminator:
@@ -386,7 +384,7 @@ export function antialiasFromF32(value: number): Antialias {
  *
  * Two members:
  *   `'off'` - default; no bloom post-processing (zero-overhead opt-out path)
- *   `'on'`  - bloom bright-pass + separable blur + composite pipeline
+ *   `'on'`  - five-level HDR extraction/downsample/tent-upsample pipeline
  *
  * Bloom is a discrete enum (0/1) — illegal values fail-fast with the closed
  * CameraError contract (charter P3), matching antialiasFromF32 precedent.
@@ -398,6 +396,19 @@ export const BLOOM_DISABLED = 0;
 /** Numeric encoding of bloom enabled (schema value for `bloom`). */
 export const BLOOM_ENABLED = 1;
 
+/** Bloom intensity is a linear HDR add-back multiplier. */
+export const CAMERA_BLOOM_INTENSITY_MIN = 0;
+export const CAMERA_BLOOM_INTENSITY_MAX = 8;
+/** Bloom threshold is expressed in scene-linear Rec.709 luminance. */
+export const CAMERA_BLOOM_THRESHOLD_MIN = 0;
+export const CAMERA_BLOOM_THRESHOLD_MAX = 65504;
+/** Soft-knee transition width relative to the threshold. */
+export const CAMERA_BLOOM_SOFT_KNEE_MIN = 0;
+export const CAMERA_BLOOM_SOFT_KNEE_MAX = 1;
+/** Coarse pyramid contribution. This is a blend, not a blur radius. */
+export const CAMERA_BLOOM_SCATTER_MIN = 0;
+export const CAMERA_BLOOM_SCATTER_MAX = 0.95;
+
 /**
  * Map a `camera.bloom` numeric value to the closed `BloomEnabled` string-literal
  * union. Invalid values fail-fast with structured error (charter P3).
@@ -414,6 +425,49 @@ export function bloomEnabledFromF32(value: number): BloomEnabled {
   );
 }
 
+function validateBloomRange(field: string, value: number, min: number, max: number): void {
+  if (!Number.isFinite(value) || value < min || value > max) {
+    throw cameraError(
+      'camera-bloom-invalid',
+      field,
+      value,
+      `a finite value in [${min}, ${max}]`,
+      `set Camera.${field} to a finite value in [${min}, ${max}]`,
+    );
+  }
+}
+
+/** Validate the complete Camera-owned Bloom contract at the extract boundary. */
+export function validateCameraBloom(
+  bloom: number,
+  threshold: number,
+  intensity: number,
+  softKnee: number,
+  scatter: number,
+): BloomEnabled {
+  const enabled = bloomEnabledFromF32(bloom);
+  validateBloomRange(
+    'bloomThreshold',
+    threshold,
+    CAMERA_BLOOM_THRESHOLD_MIN,
+    CAMERA_BLOOM_THRESHOLD_MAX,
+  );
+  validateBloomRange(
+    'bloomIntensity',
+    intensity,
+    CAMERA_BLOOM_INTENSITY_MIN,
+    CAMERA_BLOOM_INTENSITY_MAX,
+  );
+  validateBloomRange(
+    'bloomSoftKnee',
+    softKnee,
+    CAMERA_BLOOM_SOFT_KNEE_MIN,
+    CAMERA_BLOOM_SOFT_KNEE_MAX,
+  );
+  validateBloomRange('bloomScatter', scatter, CAMERA_BLOOM_SCATTER_MIN, CAMERA_BLOOM_SCATTER_MAX);
+  return enabled;
+}
+
 /**
  * Camera projection parameters (perspective + orthographic variants) +
  * tonemap trio (mode + exposure + whitePoint).
@@ -447,8 +501,9 @@ export function bloomEnabledFromF32(value: number): BloomEnabled {
  * N>1 fires 'render-system-multi-camera' + uses first). Multi-viewport is
  * OOS (see feat-future-multi-viewport). The orthographic path reuses the
  * same near / far as the perspective path — both variants share the single
- * Camera archetype (17 scalar f32 columns + one historyVersion u32 column +
- * the `clearColor` array<f32,4> column + the `autoAspect` bool column).
+ * Camera archetype (30 schema fields, including the Bloom controls, one
+ * historyVersion u32 column, the `clearColor` array<f32,4> column, and the
+ * `autoAspect` bool column).
  *
  * @example Perspective camera at (0, 0, 3) looking down -Z (zero-config tonemap):
  *   world.spawn(
@@ -514,7 +569,8 @@ export const Camera = defineComponent('Camera', {
   bloom: { type: 'f32', default: 0 },
   bloomThreshold: { type: 'f32', default: 1.0 },
   bloomIntensity: { type: 'f32', default: 1.0 },
-  bloomBlurRadius: { type: 'f32', default: 4.0 },
+  bloomSoftKnee: { type: 'f32', default: 0.5 },
+  bloomScatter: { type: 'f32', default: 0.7 },
   // M1 target camera role: zero means this camera is eligible for display;
   // non-zero shared targets are auxiliary producers whose views and receipt
   // promotion remain owned by Renderer.
@@ -544,7 +600,7 @@ export const Camera = defineComponent('Camera', {
 
 // ─── Camera POD type (derived from Camera token — single source, AC-07) ─────
 //
-// ShapeOf<SchemaOf<typeof Camera>> resolves the 20-field POD from the Camera
+// ShapeOf<SchemaOf<typeof Camera>> resolves the 30-field POD from the 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.
@@ -626,7 +682,7 @@ function cameraColorGradingColumns(
 
 // ─── Camera factory functions (w13 SSOT refactoring) ─────────────────────
 //
-// Standalone factory functions that return 20-field CameraPod objects
+// Standalone factory functions that return 29-field CameraPod objects
 // matching the Camera component column shape. Not static methods because
 // TypeScript const-namespace merge is not supported, and Object.assign
 // would break the Camera token's reference identity (archetype columns /

package/src/components/cloud-layer.ts

@@ -0,0 +1,47 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/** Closed quality lane for the renderer-owned procedural cloud producer. */
+export type CloudQuality = 'low' | 'medium' | 'high';
+
+export const CloudQualityValue = Object.freeze({
+  low: 0,
+  medium: 1,
+  high: 2,
+} as const);
+
+/**
+ * A single World-authored cloud layer.
+ *
+ * The component contains only source facts. Cache resolution, optical step
+ * counts, temporal history and GPU handles are derived by Render and never
+ * written back into ECS.
+ */
+export const CloudLayer = defineComponent('CloudLayer', {
+  /** Stable integer seed for the periodic 3D density field. */
+  seed: { type: 'u32', default: 1337 },
+  /** World-space lower edge of the layer, in metres. */
+  baseHeight: { type: 'f32', default: 120 },
+  /** World-space thickness of the layer, in metres. */
+  thickness: { type: 'f32', default: 80 },
+  /** Horizontal noise scale, in cycles per metre. */
+  scale: { type: 'f32', default: 0.004 },
+  /** Coverage threshold in [0, 1]. */
+  coverage: { type: 'f32', default: 0.48 },
+  /** Extinction multiplier in inverse metres. */
+  density: { type: 'f32', default: 1 },
+  /** World-space wind velocity in metres per second. */
+  wind: { type: 'array<f32, 3>', default: new Float32Array([8, 0, 2]) },
+  /** Quality controls cache resolution and bounded ray steps. */
+  quality: { type: 'f32', default: CloudQualityValue.medium },
+  /** Maximum world-space distance represented by the light-space shadow map. */
+  shadowRange: { type: 'f32', default: 512 },
+});
+
+export type CloudLayerData = ShapeOf<SchemaOf<typeof CloudLayer>>;
+
+export function cloudQualityFromF32(value: number): CloudQuality | undefined {
+  if (value === CloudQualityValue.low) return 'low';
+  if (value === CloudQualityValue.medium) return 'medium';
+  if (value === CloudQualityValue.high) return 'high';
+  return undefined;
+}

package/src/components/index.ts

@@ -1,5 +1,7 @@
 export * from './atmosphere';
+export * from './barrel-distortion';
 export * from './camera';
+export * from './cloud-layer';
 export * from './cube-camera';
 export * from './depth-of-field';
 export * from './directional-light';

package/src/components/instances.ts

@@ -1,50 +1,23 @@
-// @forgeax/engine-render - renderer-owned large instance association.
-//
-// The ECS component deliberately carries only a stable collection identity.
-// Matrix bytes, revision, capacity, dirty ranges, GPU residency and fallback
-// policy belong to InstanceCollectionStore, exposed from the same Renderer.
-// This keeps large payloads out of the ECS managed BufferPool while retaining
-// ordinary query and entity-lifetime semantics.
-//
-// Authoring example:
-//
-//   const transforms = new Float32Array(instanceCount * 16);
-//   for (let index = 0; index < instanceCount; index += 1) {
-//     const offset = index * 16;
-//     transforms[offset] = 1;
-//     transforms[offset + 5] = 1;
-//     transforms[offset + 10] = 1;
-//     transforms[offset + 15] = 1;
-//   }
-//   const collection = renderer.instances.create({
-//     transforms,
-//   }).unwrap();
-//   world.spawn(
-//     { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
-//     { component: MeshRenderer, data: {} },
-//     { component: Instances, data: { collectionId: collection.collectionId } },
-//   );
-//
-// Updates stay on the renderer owner and publish one revision:
-//
-//   renderer.instances.update(collection.collectionId, {
-//     start: 12,
-//     transforms: patch,
-//   });
-//
-// Render extraction snapshots the validated packed column-major matrices once
-// per frame. Direct, GPU-driven and fallback lanes consume that same detached
-// projection; callers never split one logical collection into ECS chunks.
-
 import { defineComponent } from '@forgeax/engine-ecs';
-import type { InstanceCollectionData } from '../instances';
 
-/** Per-entity association with a renderer-owned instance collection. */
+/**
+ * World-owned local transforms for one explicit instanced renderable.
+ * Packed column-major mat4 values compose as entityWorld * instanceLocal.
+ * ECS owns copying, mutation and entity lifetime, including large arrays.
+ * Renderer extraction derives its own snapshot and GPU residency; neither
+ * authoring nor glTF SceneAsset lowering requires a Renderer identity.
+ *
+ * @example
+ * const transforms = new Float32Array(20_000 * 16);
+ * for (let i = 0; i < 20_000; i++) {
+ *   transforms[i * 16] = transforms[i * 16 + 5] =
+ *     transforms[i * 16 + 10] = transforms[i * 16 + 15] = 1;
+ * }
+ * const entity = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+ * world.set(entity, Instances, { transforms }).unwrap();
+ */
 export const Instances = defineComponent('Instances', {
-  collectionId: { type: 'u32', default: 0 },
+  transforms: { type: 'array<f32>' },
 });
 
-/** Type-level hint for the `data` object at the Instances spawn site. */
-export type InstancesData = InstanceCollectionData;
-
-export type { InstanceCollectionId } from '../instances';
+export type InstancesData = { readonly transforms: Float32Array };

package/src/components/mesh-filter.ts

@@ -10,8 +10,8 @@
 //
 // AI users spawn with the assets-runtime constants `HANDLE_CUBE` /
 // `HANDLE_TRIANGLE` (now branded `Handle<'MeshAsset','shared'>` to
-// match the schema-derived shape); custom mesh registration is owned by
-// feat-future-asset-system (this MVP only exposes builtin handles).
+// match the schema-derived shape). A loaded or custom MeshAsset payload is
+// bound by allocating a World shared reference before publishing this field.
 //
 // Naming flavor: unity-style "MeshFilter / MeshRenderer" pair, but the forgeax
 // pair does NOT mirror Unity's filter-toggle semantics - MeshFilter only
@@ -22,12 +22,13 @@
 // query never matches -> entity is silently absent from the
 // RenderableSnapshot[] (NO default-material fallback, NO onError fire);
 // case B (MeshRenderer.material omitted at spawn) -> mid-grey
-// defaultMaterialSnapshot fallback (no onError); case C (material handle
+// defaultMaterialSnapshot fallback (no onError); an unbound scalar shared<T>
+// field (slot 0) is also not a renderable; case C (non-zero material handle
 // unresolved) -> RhiError 'asset-not-registered' (mirrors the
 // MeshFilter.assetHandle dangling-ref path).
 //
 // charter mapping: proposition 1 (single import) + proposition 4 (explicit
-// failure: missing or unregistered handle fires onError 'asset-not-registered'
+// failure: a non-zero unregistered handle fires onError 'asset-not-registered'
 // with .detail = { assetHandle } + cross-asset brand mismatch is a TS
 // compile-time error) + proposition 5 (consistent abstraction: the schema
 // vocab `'shared<T>'` is the SSOT for AssetRegistry-owned handles across
@@ -39,12 +40,13 @@ import { defineComponent } from '@forgeax/engine-ecs';
  * Mesh filter (geometry asset reference).
  *
  * `assetHandle` carries a `Handle<'MeshAsset', 'shared'>` (u32-stored)
- * pointing into `engine.assets: AssetRegistry`. Use the predefined
- * constants `HANDLE_CUBE` / `HANDLE_TRIANGLE` exported from
- * `@forgeax/engine-render`; custom-mesh registration is OOS in MVP (see
- * feat-future-asset-system).
+ * pointing to a mesh payload in the current World shared-reference / builtin
+ * handle namespace. An omitted field defaults to slot `0`, the unbound
+ * sentinel; an entity with that value is not emitted as a renderable. Use the
+ * predefined constants `HANDLE_CUBE` / `HANDLE_TRIANGLE` for builtins and
+ * allocate a World shared reference for a loaded mesh payload.
  *
- * Error path: if the handle is not registered at draw time, RenderSystem
+ * Error path: if a non-zero handle is not registered at draw time, RenderSystem
  * fires `Renderer.onError` with
  * `RhiError({ code: 'asset-not-registered', detail: { assetHandle } })`
  * and skips this entity (other entities continue rendering; charter

package/src/components/motion-blur.ts

@@ -5,4 +5,5 @@ export const MotionBlur = defineComponent('MotionBlur', {
   shutterAngle: { type: 'f32', default: 180 },
   maxRadiusPixels: { type: 'f32', default: 32 },
   sampleCount: { type: 'f32', default: 8 },
+  targetFps: { type: 'f32', default: 60 },
 });

package/src/components/sprite-instances.ts

@@ -41,7 +41,7 @@
 //   composes per instance:
 //     world_position[i] = entity_world * instances_local[i] * vertex_position
 //   `SpriteInstances.transforms[i*16..i*16+15]` is interpreted as a local-
-//   space transform under the entity, matching the 3D collection projection.
+//   space transform under the entity, exactly like `Instances.transforms`.
 //   Set the entity's `Transform` to identity to make `instances_local[i]`
 //   directly world-space.
 //

package/src/construct-renderer.ts

@@ -14,7 +14,7 @@ export type {
   RhiBackendInstrumentation,
   RhiBackendPack,
 } from './assembly/backend-contract';
-export { EngineEnvironmentError } from './assembly/backend-contract';
+export { EngineEnvironmentError, loadRhiPack } from './assembly/backend-contract';
 export type { RendererLegacyHostAdapter } from './assembly/host-contract';
 export type { BundlerOptions };