@forgeax/engine-render 0.1.28 → 0.1.30

package/src/components/camera.ts

@@ -43,6 +43,179 @@ export const CAMERA_PROJECTION_PERSPECTIVE = 0;
 /** Numeric encoding of orthographic projection (schema value for `projection`). */
 export const CAMERA_PROJECTION_ORTHOGRAPHIC = 1;
 
+/** Closed public exposure authoring contract shared by all camera routes. */
+export type CameraExposure =
+  | { readonly kind: 'manual'; readonly multiplier: number }
+  | {
+      readonly kind: 'auto';
+      readonly fallback: number;
+      readonly compensationEv: number;
+      readonly rangeEv: readonly [min: number, max: number];
+      readonly rates: readonly [up: number, down: number];
+    };
+
+/** Numeric encoding of manual exposure in the Camera SoA column. */
+export const CAMERA_EXPOSURE_MODE_MANUAL = 0;
+/** Numeric encoding of GPU-adapted exposure in the Camera SoA column. */
+export const CAMERA_EXPOSURE_MODE_AUTO = 1;
+
+/** Product-supported white-balance temperature range in Kelvin. */
+export const CAMERA_TEMPERATURE_MIN = 1000;
+export const CAMERA_TEMPERATURE_MAX = 40000;
+/** Product-supported normalized tint range. */
+export const CAMERA_TINT_MIN = -1;
+export const CAMERA_TINT_MAX = 1;
+
+/** Closed validation failures for the Camera authoring/column boundary. */
+export type CameraErrorCode =
+  | 'camera-exposure-invalid'
+  | 'camera-color-grading-invalid'
+  | 'camera-exposure-mode-invalid'
+  | 'camera-tonemap-invalid'
+  | 'camera-antialias-invalid'
+  | 'camera-bloom-invalid';
+
+export interface CameraErrorDetail {
+  readonly field: string;
+  readonly actual: number | string;
+  readonly expected: string;
+}
+
+/** Structured Camera error; callers can branch on the closed `code` union. */
+export class CameraError<Code extends CameraErrorCode = CameraErrorCode> extends Error {
+  readonly code: Code;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: CameraErrorDetail;
+
+  constructor(code: Code, field: string, actual: number | string, expected: string, hint: string) {
+    super(`${code}: ${field}=${String(actual)}; expected ${expected}`);
+    this.name = 'CameraError';
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = Object.freeze({ field, actual, expected });
+  }
+}
+
+function actualValue(value: unknown): number | string {
+  if (typeof value === 'number' || typeof value === 'string') return value;
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function cameraError<Code extends CameraErrorCode>(
+  code: Code,
+  field: string,
+  actual: unknown,
+  expected: string,
+  hint: string,
+): CameraError<Code> {
+  return new CameraError(code, field, actualValue(actual), expected, hint);
+}
+
+function finitePositive(value: number): boolean {
+  return Number.isFinite(value) && value > 0;
+}
+
+/** Validate the closed exposure union before it is projected into columns. */
+export function validateCameraExposure(exposure: CameraExposure): CameraExposure {
+  if (typeof exposure !== 'object' || exposure === null) {
+    throw cameraError(
+      'camera-exposure-invalid',
+      'value',
+      exposure,
+      'an object with kind manual or auto',
+      'choose one member of the CameraExposure union',
+    );
+  }
+  if (exposure.kind === 'manual') {
+    if (!finitePositive(exposure.multiplier)) {
+      throw cameraError(
+        'camera-exposure-invalid',
+        'multiplier',
+        exposure.multiplier,
+        'a finite number greater than zero',
+        'set Camera.exposure to a positive finite manual multiplier',
+      );
+    }
+    return exposure;
+  }
+  if (exposure.kind === 'auto') {
+    const [min, max] = exposure.rangeEv;
+    const [up, down] = exposure.rates;
+    if (
+      !finitePositive(exposure.fallback) ||
+      !Number.isFinite(exposure.compensationEv) ||
+      !Number.isFinite(min) ||
+      !Number.isFinite(max) ||
+      min > max ||
+      !Number.isFinite(up) ||
+      !Number.isFinite(down) ||
+      up < 0 ||
+      down < 0
+    ) {
+      throw cameraError(
+        'camera-exposure-invalid',
+        'auto',
+        JSON.stringify(exposure),
+        'finite fallback/compensation, an ordered range, and non-negative rates',
+        'inspect fallback, compensationEv, rangeEv, and rates before rebuilding the camera',
+      );
+    }
+    return exposure;
+  }
+  throw cameraError(
+    'camera-exposure-invalid',
+    'kind',
+    (exposure as { readonly kind?: unknown }).kind,
+    "'manual' or 'auto'",
+    'choose one member of the CameraExposure union',
+  );
+}
+
+/** Validate the Camera-owned white-balance and LUT authoring fields. */
+export function validateCameraColorGrading(
+  temperature: number,
+  tint: number,
+  colorLutStrength: number,
+): void {
+  if (
+    !Number.isFinite(temperature) ||
+    temperature < CAMERA_TEMPERATURE_MIN ||
+    temperature > CAMERA_TEMPERATURE_MAX
+  ) {
+    throw cameraError(
+      'camera-color-grading-invalid',
+      'temperature',
+      temperature,
+      `a finite value in [${CAMERA_TEMPERATURE_MIN}, ${CAMERA_TEMPERATURE_MAX}]`,
+      'set Camera.temperature to a supported Kelvin value',
+    );
+  }
+  if (!Number.isFinite(tint) || tint < CAMERA_TINT_MIN || tint > CAMERA_TINT_MAX) {
+    throw cameraError(
+      'camera-color-grading-invalid',
+      'tint',
+      tint,
+      `a finite value in [${CAMERA_TINT_MIN}, ${CAMERA_TINT_MAX}]`,
+      'set Camera.tint to a normalized value between -1 and 1',
+    );
+  }
+  if (!Number.isFinite(colorLutStrength) || colorLutStrength < 0 || colorLutStrength > 1) {
+    throw cameraError(
+      'camera-color-grading-invalid',
+      'colorLutStrength',
+      colorLutStrength,
+      'a finite value in [0, 1]',
+      'set Camera.colorLutStrength to zero to disable the LUT or a blend in [0, 1]',
+    );
+  }
+}
+
 /**
  * Map a `camera.projection` numeric value to the closed `CameraProjection`
  * string-literal union. Values other than 0 / 1 fall back to `'perspective'`
@@ -152,7 +325,13 @@ export function tonemapToU32(mode: Tonemap): number {
     case 'none':
       return TONEMAP_NONE;
   }
-  throw new RangeError(`Invalid tonemap mode: ${String(mode)}.`);
+  throw cameraError(
+    'camera-tonemap-invalid',
+    'tonemap',
+    mode,
+    'one of the closed Tonemap values',
+    'select a supported Camera tonemap mode',
+  );
 }
 
 /**
@@ -192,8 +371,12 @@ export function antialiasFromF32(value: number): Antialias {
   if (value === ANTIALIAS_FXAA) return 'fxaa';
   if (value === ANTIALIAS_MSAA) return 'msaa';
   if (value === ANTIALIAS_TAA) return 'taa';
-  throw new RangeError(
-    `Invalid antialias value: ${value}. Expected ${ANTIALIAS_NONE} (none), ${ANTIALIAS_FXAA} (fxaa), ${ANTIALIAS_MSAA} (msaa), or ${ANTIALIAS_TAA} (taa).`,
+  throw cameraError(
+    'camera-antialias-invalid',
+    'antialias',
+    value,
+    `${ANTIALIAS_NONE}, ${ANTIALIAS_FXAA}, ${ANTIALIAS_MSAA}, or ${ANTIALIAS_TAA}`,
+    'select a supported Camera antialias mode',
   );
 }
 
@@ -205,8 +388,8 @@ export function antialiasFromF32(value: number): Antialias {
  *   `'off'` - default; no bloom post-processing (zero-overhead opt-out path)
  *   `'on'`  - bloom bright-pass + separable blur + composite pipeline
  *
- * Bloom is a discrete enum (0/1) — illegal values fail-fast with RangeError
- * (charter P3), matching antialiasFromF32 precedent.
+ * Bloom is a discrete enum (0/1) — illegal values fail-fast with the closed
+ * CameraError contract (charter P3), matching antialiasFromF32 precedent.
  */
 export type BloomEnabled = 'off' | 'on';
 
@@ -222,8 +405,12 @@ export const BLOOM_ENABLED = 1;
 export function bloomEnabledFromF32(value: number): BloomEnabled {
   if (value === BLOOM_DISABLED) return 'off';
   if (value === BLOOM_ENABLED) return 'on';
-  throw new RangeError(
-    `Invalid bloom value: ${value}. Expected ${BLOOM_DISABLED} (off) or ${BLOOM_ENABLED} (on).`,
+  throw cameraError(
+    'camera-bloom-invalid',
+    'bloom',
+    value,
+    `${BLOOM_DISABLED} or ${BLOOM_ENABLED}`,
+    'select Camera bloom off or on',
   );
 }
 
@@ -313,7 +500,15 @@ export const Camera = defineComponent('Camera', {
   top: { type: 'f32', default: 1 },
   tonemap: { type: 'f32', default: 0 },
   exposure: { type: 'f32', default: 1.0 },
+  exposureMode: { type: 'f32', default: CAMERA_EXPOSURE_MODE_MANUAL },
+  compensationEv: { type: 'f32', default: 0 },
+  rangeEv: { type: 'array<f32, 2>', default: new Float32Array([-8, 8]) },
+  rates: { type: 'array<f32, 2>', default: new Float32Array([3, 1]) },
   whitePoint: { type: 'f32', default: 4.0 },
+  temperature: { type: 'f32', default: 6504 },
+  tint: { type: 'f32', default: 0 },
+  colorLut: { type: 'shared<TextureAsset>', default: 0 as never },
+  colorLutStrength: { type: 'f32', default: 0 },
   antialias: { type: 'f32', default: 0 },
   historyVersion: { type: 'u32', default: 0 },
   bloom: { type: 'f32', default: 0 },
@@ -356,6 +551,79 @@ export const Camera = defineComponent('Camera', {
 export type CameraData = ShapeOf<SchemaOf<typeof Camera>>;
 type CameraPod = CameraData;
 
+/** Project the Camera SoA columns back into the public closed union. */
+export function cameraExposureFromColumns(
+  input: Pick<CameraData, 'exposureMode' | 'exposure' | 'compensationEv' | 'rangeEv' | 'rates'>,
+): CameraExposure {
+  if (input.exposureMode === CAMERA_EXPOSURE_MODE_MANUAL) {
+    return validateCameraExposure({ kind: 'manual', multiplier: input.exposure });
+  }
+  if (input.exposureMode === CAMERA_EXPOSURE_MODE_AUTO) {
+    return validateCameraExposure({
+      kind: 'auto',
+      fallback: input.exposure,
+      compensationEv: input.compensationEv,
+      rangeEv: [input.rangeEv[0] ?? -8, input.rangeEv[1] ?? 8],
+      rates: [input.rates[0] ?? 3, input.rates[1] ?? 1],
+    });
+  }
+  throw cameraError(
+    'camera-exposure-mode-invalid',
+    'exposureMode',
+    input.exposureMode,
+    `${CAMERA_EXPOSURE_MODE_MANUAL} or ${CAMERA_EXPOSURE_MODE_AUTO}`,
+    'set Camera.exposureMode to the manual or auto encoding',
+  );
+}
+
+function cameraExposureColumns(
+  exposure: CameraExposure,
+): Pick<CameraData, 'exposureMode' | 'exposure' | 'compensationEv' | 'rangeEv' | 'rates'> {
+  const checked = validateCameraExposure(exposure);
+  if (checked.kind === 'manual') {
+    return {
+      exposureMode: CAMERA_EXPOSURE_MODE_MANUAL,
+      exposure: checked.multiplier,
+      compensationEv: 0,
+      rangeEv: new Float32Array([-8, 8]),
+      rates: new Float32Array([3, 1]),
+    };
+  }
+  return {
+    exposureMode: CAMERA_EXPOSURE_MODE_AUTO,
+    exposure: checked.fallback,
+    compensationEv: checked.compensationEv,
+    rangeEv: new Float32Array(checked.rangeEv),
+    rates: new Float32Array(checked.rates),
+  };
+}
+
+interface CameraColorGradingOpts {
+  exposure?: CameraExposure;
+  temperature?: number;
+  tint?: number;
+  colorLut?: CameraPod['colorLut'];
+  colorLutStrength?: number;
+}
+
+function cameraColorGradingColumns(
+  opts: CameraColorGradingOpts,
+): ReturnType<typeof cameraExposureColumns> &
+  Pick<CameraData, 'temperature' | 'tint' | 'colorLut' | 'colorLutStrength'> {
+  const exposure = opts.exposure ?? { kind: 'manual', multiplier: 1 };
+  const temperature = opts.temperature ?? 6504;
+  const tint = opts.tint ?? 0;
+  const colorLutStrength = opts.colorLutStrength ?? 0;
+  validateCameraColorGrading(temperature, tint, colorLutStrength);
+  return {
+    ...cameraExposureColumns(exposure),
+    temperature,
+    tint,
+    colorLut: opts.colorLut ?? (0 as CameraPod['colorLut']),
+    colorLutStrength,
+  };
+}
+
 // ─── Camera factory functions (w13 SSOT refactoring) ─────────────────────
 //
 // Standalone factory functions that return 20-field CameraPod objects
@@ -396,6 +664,11 @@ interface CameraPerspectiveOpts {
    * receive aspect-sync regardless of this flag.
    */
   autoAspect?: boolean;
+  exposure?: CameraExposure;
+  temperature?: number;
+  tint?: number;
+  colorLut?: CameraPod['colorLut'];
+  colorLutStrength?: number;
 }
 
 interface CameraOrthographicOpts {
@@ -405,6 +678,11 @@ interface CameraOrthographicOpts {
   top: number;
   near?: number;
   far?: number;
+  exposure?: CameraExposure;
+  temperature?: number;
+  tint?: number;
+  colorLut?: CameraPod['colorLut'];
+  colorLutStrength?: number;
 }
 
 /**
@@ -474,6 +752,7 @@ export function perspective(opts: CameraPerspectiveOpts): CameraPod {
     far: opts.far ?? 100,
     projection: CAMERA_PROJECTION_PERSPECTIVE,
     ...(opts.autoAspect !== undefined ? { autoAspect: opts.autoAspect } : {}),
+    ...cameraColorGradingColumns(opts),
   };
 }
 
@@ -513,5 +792,6 @@ export function orthographic(opts: CameraOrthographicOpts): CameraPod {
     right: opts.right,
     bottom: opts.bottom,
     top: opts.top,
+    ...cameraColorGradingColumns(opts),
   };
 }

package/src/components/directional-light.ts

@@ -60,8 +60,8 @@ export {
  *   splitLambda    ∈ [0,1]      — PSSM split weight (default 0.75)
  *   cascadeBlend   ∈ [0,0.5]    — blend width between cascades (default 0.2)
  *   mapSize        >= 1         — shadow map resolution (default 2048)
- *   depthBias                    — shadow acne bias (default 0.005)
- *   normalBias                   — shadow acne normal offset (default 0.05)
+ *   depthBias                    — normalized receiver depth subtraction (default 0.00001)
+ *   normalBias                   — world-space receiver normal offset (default 0.05)
  *   shadowDistance > 0           — how far shadows reach in front of the camera,
  *                                  in world units (default 200). This is the sole
  *                                  coverage knob: the CSM cascades are PSSM-split
@@ -123,7 +123,7 @@ export const DirectionalLight = defineComponent('DirectionalLight', {
   splitLambda: { type: 'f32', default: 0.75 },
   cascadeBlend: { type: 'f32', default: 0.2 },
   mapSize: { type: 'f32', default: 2048 },
-  depthBias: { type: 'f32', default: 0.005 },
+  depthBias: { type: 'f32', default: 0.00001 },
   normalBias: { type: 'f32', default: 0.05 },
   // Sole shadow coverage knob (feat replaces nearPlane/farPlane). The PSSM
   // near end derives from the active camera near; shadowDistance is the far

package/src/components/dynamic-resolution.ts

@@ -0,0 +1,67 @@
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import {
+  type DynamicResolutionError,
+  DynamicResolutionInvalidParameterError,
+  DynamicResolutionRequiresTaaError,
+} from '../errors/render';
+
+/** Optional Camera companion that enables fixed or adaptive internal scaling. */
+export const DynamicResolution = defineComponent('DynamicResolution', {
+  targetGpuMs: { type: 'f32', default: 16.67 },
+  minScale: { type: 'f32', default: 0.67 },
+  maxScale: { type: 'f32', default: 1.0 },
+});
+
+export type DynamicResolutionData = ShapeOf<SchemaOf<typeof DynamicResolution>>;
+
+const DEFAULT_DYNAMIC_RESOLUTION: DynamicResolutionData = Object.freeze({
+  targetGpuMs: 16.67,
+  minScale: 0.67,
+  maxScale: 1,
+});
+
+function invalid(
+  field: 'targetGpuMs' | 'minScale' | 'maxScale',
+  value: number,
+  expected: string,
+): DynamicResolutionInvalidParameterError {
+  return new DynamicResolutionInvalidParameterError({ field, value, expected });
+}
+
+/** Validate one detached DynamicResolution authoring POD before graph work. */
+export function validateDynamicResolutionParameters(
+  input: Partial<DynamicResolutionData> | undefined,
+): Result<DynamicResolutionData, DynamicResolutionInvalidParameterError> {
+  const value = input ?? {};
+  const targetGpuMs = value.targetGpuMs ?? DEFAULT_DYNAMIC_RESOLUTION.targetGpuMs;
+  const minScale = value.minScale ?? DEFAULT_DYNAMIC_RESOLUTION.minScale;
+  const maxScale = value.maxScale ?? DEFAULT_DYNAMIC_RESOLUTION.maxScale;
+  if (!Number.isFinite(targetGpuMs) || targetGpuMs <= 0) {
+    return err(invalid('targetGpuMs', targetGpuMs, 'finite and greater than 0'));
+  }
+  if (!Number.isFinite(minScale) || minScale < 0.5 || minScale > 1) {
+    return err(invalid('minScale', minScale, 'finite and in [0.5, 1.0]'));
+  }
+  if (!Number.isFinite(maxScale) || maxScale < 0.5 || maxScale > 1) {
+    return err(invalid('maxScale', maxScale, 'finite and in [0.5, 1.0]'));
+  }
+  if (minScale > maxScale) {
+    return err(invalid('minScale', minScale, 'less than or equal to maxScale'));
+  }
+  return ok(Object.freeze({ targetGpuMs, minScale, maxScale }));
+}
+
+/** Validate the Camera companion relationship at the extraction boundary. */
+export function validateDynamicResolutionCamera(
+  input: Partial<DynamicResolutionData> | undefined,
+  antialias: 'none' | 'fxaa' | 'msaa' | 'taa',
+): Result<DynamicResolutionData | undefined, DynamicResolutionError> {
+  if (input === undefined) return ok(undefined);
+  const parameters = validateDynamicResolutionParameters(input);
+  if (!parameters.ok) return parameters;
+  if (antialias !== 'taa') {
+    return err(new DynamicResolutionRequiresTaaError({ antialias }));
+  }
+  return parameters;
+}

package/src/components/index.ts

@@ -2,6 +2,7 @@ export * from './atmosphere';
 export * from './camera';
 export * from './cube-camera';
 export * from './directional-light';
+export * from './dynamic-resolution';
 export * from './fog';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';
@@ -27,6 +28,7 @@ export {
   type SceneInstanceOverrideRecord,
   type SceneInstanceState,
 } from './scene-instance';
+export * from './screen-space-reflection';
 export {
   SKYBOX_MODE_CUBEMAP,
   SkyboxBackground,

package/src/components/instances.ts

@@ -1,23 +1,50 @@
+// @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';
 
-/**
- * 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();
- */
+/** Per-entity association with a renderer-owned instance collection. */
 export const Instances = defineComponent('Instances', {
-  transforms: { type: 'array<f32>' },
+  collectionId: { type: 'u32', default: 0 },
 });
 
-export type InstancesData = { readonly transforms: Float32Array };
+/** Type-level hint for the `data` object at the Instances spawn site. */
+export type InstancesData = InstanceCollectionData;
+
+export type { InstanceCollectionId } from '../instances';

package/src/components/light-helpers.ts

@@ -149,7 +149,12 @@ export function validateDirectionalLightData(
         }),
       );
     }
-    if (shadowAngularRadius < PCSS_RADIUS_MIN || shadowAngularRadius > PCSS_RADIUS_MAX) {
+    // ECS stores this field as f32; both authored endpoints round outward.
+    // Accept their stored representations, but not the adjacent out-of-range f32.
+    if (
+      shadowAngularRadius < Math.fround(PCSS_RADIUS_MIN) ||
+      shadowAngularRadius > Math.fround(PCSS_RADIUS_MAX)
+    ) {
       return err(
         new ShadowInvalidConfigError('shadowAngularRadius', shadowAngularRadius, {
           kind: 'range',

package/src/components/reflection-probe.ts

@@ -40,6 +40,7 @@ export function reflectionProbeUpdateIntentToF32(intent: ReflectionProbeUpdateIn
 export const ReflectionProbe = defineComponent('ReflectionProbe', {
   halfExtents: { type: 'array<f32, 3>', default: new Float32Array([1, 1, 1]) },
   priority: { type: 'f32', default: 0 },
+  boxProjection: { type: 'bool', default: false },
   intensity: { type: 'f32', default: 1 },
   resolution: { type: 'u32', default: 256 },
   updateIntent: { type: 'f32', default: REFLECTION_PROBE_UPDATE_ONCE },

package/src/components/scene-instance.ts

@@ -37,7 +37,8 @@
 //     `world.get(root, SceneInstance)` path as another component)
 
 import { defineComponent, type EntityHandle } from '@forgeax/engine-ecs';
-import type { LocalEntityId, MountOverride } from '@forgeax/engine-types';
+import type { MountOverride } from '@forgeax/engine-scene';
+import type { LocalEntityId } from '@forgeax/engine-types';
 
 /**
  * Per-component, per-field override record carried in `SceneInstanceState`.

package/src/components/screen-space-reflection.ts

@@ -0,0 +1,21 @@
+// @forgeax/engine-render - ScreenSpaceReflection authoring component.
+//
+// The component is an opt-in camera effect. It carries only the three
+// bounded authoring values; all graph, resource, history, and backend state
+// remains renderer-owned.
+
+import { defineComponent, type SchemaOf, type ShapeOf } from '@forgeax/engine-ecs';
+
+/**
+ * Schema-derived ScreenSpaceReflection authoring data.
+ *
+ * The defaults are conservative and are validated against the active camera
+ * view range before a spatial candidate is admitted.
+ */
+export const ScreenSpaceReflection = defineComponent('ScreenSpaceReflection', {
+  maxDistance: { type: 'f32', default: 40 },
+  thickness: { type: 'f32', default: 0.2 },
+  maxRoughness: { type: 'f32', default: 0.6 },
+});
+
+export type ScreenSpaceReflectionData = ShapeOf<SchemaOf<typeof ScreenSpaceReflection>>;

package/src/components/skylight.ts

@@ -40,7 +40,10 @@ import { defineComponent } from '@forgeax/engine-ecs';
  * Skylight ambient environment light.
  *
  * A single Skylight entity provides ambient lighting for all StandardMaterial
- * surfaces. Two modes share one component:
+ * surfaces. When Atmosphere is selected and equirect is omitted, the same sky
+ * cube supplies diffuse and roughness-filtered specular IBL. Color/intensity
+ * still scale the result; without Atmosphere the solid-color behavior applies.
+ * Two authored inputs share one component:
  *
  * - **Solid-color ambient (no equirect).** Omit `equirect` for a constant
  *   ambient = `color` * `intensity` applied immediately, with no async GPU

package/src/components/sprite-animation.ts

@@ -31,8 +31,8 @@
 // Why array<f32> (variable) and not array<f32, N> (fixed) for regions?
 // The length `frameCount * 4` is data-dependent: `frameCount` is itself a
 // per-entity column read at runtime, not a schema-time literal. Same
-// shape as M1 `Instances.transforms: 'array<f32>'` whose length depends
-// on the live instance count; D-6 codifies the precedent.
+// shape as the renderer-owned 3D instance collection snapshot whose length
+// depends on the live instance count; the owners remain separate.
 //
 // dt accumulator clock model (requirements section 2.5 q6 + plan-strategy
 // section 2 D-5):

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, exactly like `Instances.transforms`.
+//   space transform under the entity, matching the 3D collection projection.
 //   Set the entity's `Transform` to identity to make `instances_local[i]`
 //   directly world-space.
 //