@forgeax/engine-render 0.1.28 → 0.1.30

package/src/assembly/webgpu-vertex-layouts.ts

@@ -1,108 +1,190 @@
-import type { GpuVertexBufferLayoutEntry } from '@forgeax/engine-geometry';
+import {
+  buildMeshAttributeMapForUvSets,
+  DEFAULT_VERTEX_ATTRIBUTE_MAP,
+  deriveVertexBufferLayout,
+  deriveVertexBufferLayoutFromProjection,
+  type GpuVertexBufferLayoutEntry,
+  SKIN_VERTEX_ATTRIBUTE_MAP,
+  type VertexLayoutProjection,
+} from '@forgeax/engine-geometry';
 import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 
-// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4): a single
-// shared empty ArrayBuffer used by the pipeline builder to synthesize the
-// pbr-skin attribute map when no caller-supplied attributes are available.
-// `deriveVertexBufferLayout` is the SSOT for the layout and reads only key
-// presence, so a zero-byte buffer per key preserves the six-attribute stride.
-export const PBR_SKIN_SENTINEL_ATTR_BUFFER = new ArrayBuffer(0);
-
-/** Default 4-attribute vertex layout used as fallback when meshAttributes is undefined. */
-export const DEFAULT_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-};
+type FeatureFloatVertexFormat = 'float32x2' | 'float32x3' | 'float32x4';
 
-export const PREPARED_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-  uv1: new Float32Array(0),
-};
+interface FeatureVertexAttribute {
+  readonly shaderLocation: number;
+  readonly format: FeatureFloatVertexFormat;
+}
 
-export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-  skinIndex: new Uint16Array(0),
-  skinWeight: new Float32Array(0),
+interface FeatureVertexBufferSpec {
+  readonly stepMode: 'vertex' | 'instance';
+  readonly attributes: readonly FeatureVertexAttribute[];
+}
+
+const FLOAT32_COMPONENT_COUNT: Readonly<Record<FeatureFloatVertexFormat, number>> = {
+  float32x2: 2,
+  float32x3: 3,
+  float32x4: 4,
 };
 
+/**
+ * Keep feature layouts as one declarative attribute table. The stride and
+ * byte offsets are derived from that table so an attribute edit cannot leave
+ * a stale `arrayStride` or byte offset behind.
+ */
+function defineFeatureVertexBuffer(spec: FeatureVertexBufferSpec): GPUVertexBufferLayout {
+  let offsetFloats = 0;
+  const attributes = spec.attributes.map(({ shaderLocation, format }) => {
+    const attribute = {
+      shaderLocation,
+      offset: offsetFloats * Float32Array.BYTES_PER_ELEMENT,
+      format,
+    };
+    offsetFloats += FLOAT32_COMPONENT_COUNT[format];
+    return attribute;
+  });
+  return {
+    arrayStride: offsetFloats * Float32Array.BYTES_PER_ELEMENT,
+    stepMode: spec.stepMode,
+    attributes,
+  };
+}
+
+const POSITION_SIZE_COLOR_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 0, format: 'float32x3' },
+    { shaderLocation: 1, format: 'float32x2' },
+    { shaderLocation: 2, format: 'float32x4' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+const BILLBOARD_MATERIAL_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 0, format: 'float32x3' },
+    { shaderLocation: 1, format: 'float32x2' },
+    { shaderLocation: 2, format: 'float32x2' },
+    { shaderLocation: 3, format: 'float32x4' },
+    { shaderLocation: 4, format: 'float32x4' },
+    { shaderLocation: 5, format: 'float32x4' },
+    { shaderLocation: 6, format: 'float32x4' },
+    { shaderLocation: 7, format: 'float32x4' },
+    { shaderLocation: 8, format: 'float32x4' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+const TOPOLOGY_SEGMENT_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 0, format: 'float32x3' },
+    { shaderLocation: 1, format: 'float32x3' },
+    { shaderLocation: 2, format: 'float32x4' },
+    { shaderLocation: 3, format: 'float32x2' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+const MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 4, format: 'float32x3' },
+    { shaderLocation: 5, format: 'float32x3' },
+    { shaderLocation: 6, format: 'float32x3' },
+    { shaderLocation: 7, format: 'float32x3' },
+    { shaderLocation: 8, format: 'float32x4' },
+    { shaderLocation: 9, format: 'float32x2' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+/** Geometry-owned maps retained here only as feature-pipeline aliases. */
+export const PREPARED_INSTANCE_VERTEX_ATTRS = buildMeshAttributeMapForUvSets(2);
+export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS = SKIN_VERTEX_ATTRIBUTE_MAP;
+
+function canonicalMeshVertexBufferLayout(): GPUVertexBufferLayout {
+  const [buffer] = toGpuVertexBufferLayouts(deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP));
+  if (buffer === undefined) {
+    throw new Error('The canonical mesh vertex layout must contain one vertex buffer');
+  }
+  return { ...buffer, stepMode: 'vertex' };
+}
+
 export const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 9 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
-      { shaderLocation: 2, offset: 5 * 4, format: 'float32x4' as const },
-    ],
-  },
+  defineFeatureVertexBuffer(POSITION_SIZE_COLOR_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
 export const BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 31 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
-      { shaderLocation: 2, offset: 5 * 4, format: 'float32x2' as const },
-      { shaderLocation: 3, offset: 7 * 4, format: 'float32x4' as const },
-      { shaderLocation: 4, offset: 11 * 4, format: 'float32x4' as const },
-      { shaderLocation: 5, offset: 15 * 4, format: 'float32x4' as const },
-      { shaderLocation: 6, offset: 19 * 4, format: 'float32x4' as const },
-      { shaderLocation: 7, offset: 23 * 4, format: 'float32x4' as const },
-      { shaderLocation: 8, offset: 27 * 4, format: 'float32x4' as const },
-    ],
-  },
+  defineFeatureVertexBuffer(BILLBOARD_MATERIAL_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
 export const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 12 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 2, offset: 6 * 4, format: 'float32x4' as const },
-      { shaderLocation: 3, offset: 10 * 4, format: 'float32x2' as const },
-    ],
-  },
+  defineFeatureVertexBuffer(TOPOLOGY_SEGMENT_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
+/**
+ * The mesh stream is derived from geometry's canonical attribute projection.
+ * The second stream remains a feature-owned instance ABI because it carries
+ * particle transform/material data rather than MeshAsset attributes.
+ */
 export const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 12 * 4,
-    stepMode: 'vertex' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 2, offset: 6 * 4, format: 'float32x2' as const },
-      { shaderLocation: 3, offset: 8 * 4, format: 'float32x4' as const },
-    ],
-  },
-  {
-    arrayStride: 28 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 4, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 5, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 6, offset: 6 * 4, format: 'float32x3' as const },
-      { shaderLocation: 7, offset: 9 * 4, format: 'float32x3' as const },
-      { shaderLocation: 8, offset: 12 * 4, format: 'float32x4' as const },
-      { shaderLocation: 9, offset: 16 * 4, format: 'float32x4' as const },
-      { shaderLocation: 10, offset: 20 * 4, format: 'float32x4' as const },
-      { shaderLocation: 11, offset: 24 * 4, format: 'float32x4' as const },
-    ],
-  },
+  canonicalMeshVertexBufferLayout(),
+  defineFeatureVertexBuffer(MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
+const PREPARED_MATERIAL_VERTEX_LAYOUTS: ReadonlySet<string> = new Set([
+  RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance,
+]);
+
+export function isPreparedMaterialVertexLayout(layout: string | undefined): boolean {
+  return layout !== undefined && PREPARED_MATERIAL_VERTEX_LAYOUTS.has(layout);
+}
+
+/**
+ * Derive the prepared particle layout that appends one to four material-input
+ * vec4 lanes to the instance stream. The base layouts stay shared with the
+ * no-input path; only the final stream stride and locations change, which
+ * keeps the vertex-data ABI and pipeline cache key in lockstep.
+ */
+export function particleMaterialInputVertexBuffers(
+  vertexLayout: string | undefined,
+  lanes?: number,
+): readonly GPUVertexBufferLayout[] | undefined {
+  const buffers =
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance
+      ? BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS
+      : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance
+        ? TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS
+        : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance
+          ? MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS
+          : undefined;
+  if (buffers === undefined || lanes === undefined) return undefined;
+  if (!Number.isInteger(lanes) || lanes < 1 || lanes > 4) {
+    throw new RangeError('Particle material input layouts require 1 through 4 lanes');
+  }
+  return buffers.map((buffer, index) => {
+    if (index !== buffers.length - 1) return buffer;
+    const attributes = [...buffer.attributes];
+    const firstLocation = Math.max(...attributes.map((attribute) => attribute.shaderLocation)) + 1;
+    return {
+      ...buffer,
+      arrayStride: buffer.arrayStride + lanes * 16,
+      attributes: [
+        ...attributes,
+        ...Array.from({ length: lanes }, (_, lane) => ({
+          shaderLocation: firstLocation + lane,
+          offset: buffer.arrayStride + lane * 16,
+          format: 'float32x4' as const,
+        })),
+      ],
+    };
+  });
+}
+
 function toGpuVertexFormat(
   format: GpuVertexBufferLayoutEntry['attributes'][number]['format'],
 ): GPUVertexFormat {
@@ -130,3 +212,67 @@ export function toGpuVertexBufferLayouts(
     })),
   }));
 }
+
+export function resolveWebGPUVertexBufferLayouts(options: {
+  vertexInputContract: 'none' | 'render-material';
+  vertexLayout: string | undefined;
+  vertexLayoutProjection: VertexLayoutProjection | undefined;
+  resolvedUvSetCount: number | undefined;
+  layoutKind: string;
+  meshAttributes: VertexAttributeMap | undefined;
+  particleInputLanes: number | undefined;
+}): readonly GPUVertexBufferLayout[] {
+  const {
+    vertexInputContract,
+    vertexLayout,
+    vertexLayoutProjection,
+    resolvedUvSetCount,
+    layoutKind,
+    meshAttributes,
+    particleInputLanes,
+  } = options;
+  const inputVertexBuffers = particleMaterialInputVertexBuffers(vertexLayout, particleInputLanes);
+  return vertexInputContract === 'none'
+    ? []
+    : inputVertexBuffers !== undefined
+      ? inputVertexBuffers
+      : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.positionSizeColorInstance
+        ? POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS
+        : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance
+          ? BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS
+          : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance
+            ? TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS
+            : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance
+              ? MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS
+              : vertexLayoutProjection !== undefined
+                ? toGpuVertexBufferLayouts(
+                    deriveVertexBufferLayoutFromProjection(
+                      vertexLayoutProjection,
+                      resolvedUvSetCount !== undefined
+                        ? { shaderUvSetCount: resolvedUvSetCount }
+                        : undefined,
+                    ),
+                  )
+                : layoutKind === 'pbr-skin'
+                  ? toGpuVertexBufferLayouts(
+                      deriveVertexBufferLayout(
+                        meshAttributes ?? SKIN_VERTEX_ATTRIBUTE_MAP,
+                        resolvedUvSetCount !== undefined
+                          ? { shaderUvSetCount: resolvedUvSetCount }
+                          : undefined,
+                      ),
+                    )
+                  : meshAttributes !== undefined ||
+                      (resolvedUvSetCount !== undefined && resolvedUvSetCount > 1)
+                    ? toGpuVertexBufferLayouts(
+                        deriveVertexBufferLayout(
+                          meshAttributes ?? DEFAULT_VERTEX_ATTRIBUTE_MAP,
+                          resolvedUvSetCount !== undefined && resolvedUvSetCount > 1
+                            ? { shaderUvSetCount: resolvedUvSetCount }
+                            : undefined,
+                        ),
+                      )
+                    : toGpuVertexBufferLayouts(
+                        deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP),
+                      );
+}

package/src/capture/scene-projection.ts

@@ -0,0 +1,37 @@
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+
+/** One retained index domain for auxiliary views and the display's selected draws. */
+export function projectCaptureScene(
+  retained: {
+    readonly renderables: readonly RenderableSnapshot[];
+    readonly dispatch: readonly DispatchEntry[];
+  },
+  visible: readonly RenderableSnapshot[],
+  displayDispatch: readonly DispatchEntry[],
+) {
+  const renderables: RenderableSnapshot[] = [];
+  const retainedIndices = new Map<number, number>();
+  const identityIndices = new Map<string, number>();
+  for (const [index, row] of retained.renderables.entries()) {
+    if (row.authorVisible === false) continue;
+    retainedIndices.set(index, renderables.length);
+    identityIndices.set(`${row.worldId}:${row.entityKey}`, renderables.length);
+    renderables.push(row);
+  }
+  const remap = (
+    entries: readonly DispatchEntry[],
+    indexFor: (index: number) => number | undefined,
+  ) =>
+    entries.flatMap((entry) => {
+      const index = indexFor(entry.renderableIndex);
+      return index === undefined ? [] : [{ ...entry, renderableIndex: index }];
+    });
+  return {
+    renderables,
+    captureDispatch: remap(retained.dispatch, (index) => retainedIndices.get(index)),
+    displayDispatch: remap(displayDispatch, (index) => {
+      const row = visible[index];
+      return row === undefined ? undefined : identityIndices.get(`${row.worldId}:${row.entityKey}`);
+    }),
+  };
+}

package/src/components/__tests__/camera-exposure.contract.unit.test.ts

@@ -0,0 +1,153 @@
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { extractCameraSnapshots } from '../../extract/camera';
+import {
+  CAMERA_EXPOSURE_MODE_AUTO,
+  CAMERA_EXPOSURE_MODE_MANUAL,
+  Camera,
+  CameraError,
+  type CameraExposure,
+  cameraExposureFromColumns,
+  orthographic,
+  perspective,
+  validateCameraColorGrading,
+  validateCameraExposure,
+} from '../index';
+
+function describeExposure(exposure: CameraExposure): string {
+  switch (exposure.kind) {
+    case 'manual':
+      return `manual:${exposure.multiplier}`;
+    case 'auto':
+      return `auto:${exposure.fallback}`;
+  }
+  const unreachable: never = exposure;
+  return unreachable;
+}
+
+describe('CameraExposure contract', () => {
+  it('keeps manual, auto, and defaults in the Camera schema', () => {
+    expect(Camera.fields.exposureMode.default).toBe(CAMERA_EXPOSURE_MODE_MANUAL);
+    expect(Camera.fields.exposure.default).toBe(1);
+    expect(Camera.fields.rangeEv.default).toEqual(new Float32Array([-8, 8]));
+    expect(Camera.fields.rates.default).toEqual(new Float32Array([3, 1]));
+    expect(Camera.fields.temperature.default).toBe(6504);
+    expect(Camera.fields.tint.default).toBe(0);
+    expect(Camera.fields.colorLut.type).toBe('shared<TextureAsset>');
+    expect(Camera.fields.colorLutStrength.default).toBe(0);
+  });
+
+  it('projects the same public output through both camera factories', () => {
+    const exposure: CameraExposure = {
+      kind: 'auto',
+      fallback: 1.25,
+      compensationEv: -0.5,
+      rangeEv: [-6, 6],
+      rates: [3, 1],
+    };
+    const perspectiveCamera = perspective({
+      fov: Math.PI / 3,
+      aspect: 16 / 9,
+      exposure,
+      temperature: 5000,
+      tint: 0.1,
+      colorLutStrength: 0.5,
+    });
+    const orthographicCamera = orthographic({
+      left: -10,
+      right: 10,
+      bottom: -10,
+      top: 10,
+      exposure,
+      temperature: 5000,
+      tint: 0.1,
+      colorLutStrength: 0.5,
+    });
+    expect(perspectiveCamera.exposureMode).toBe(CAMERA_EXPOSURE_MODE_AUTO);
+    expect(orthographicCamera.exposureMode).toBe(CAMERA_EXPOSURE_MODE_AUTO);
+    expect(perspectiveCamera.exposure).toBe(1.25);
+    expect(orthographicCamera.rangeEv).toEqual(new Float32Array([-6, 6]));
+    expect(describeExposure(cameraExposureFromColumns(perspectiveCamera))).toBe('auto:1.25');
+  });
+
+  it('rejects non-finite, reversed, and negative-rate authoring', () => {
+    expect(() => validateCameraExposure({ kind: 'manual', multiplier: 0 })).toThrow(CameraError);
+    try {
+      validateCameraExposure({ kind: 'manual', multiplier: 0 });
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'camera-exposure-invalid',
+        expected: 'a finite number greater than zero',
+        detail: { field: 'multiplier', actual: 0 },
+      });
+    }
+    expect(() =>
+      validateCameraExposure({
+        kind: 'auto',
+        fallback: Number.NaN,
+        compensationEv: 0,
+        rangeEv: [-8, 8],
+        rates: [3, 1],
+      }),
+    ).toThrow();
+    expect(() =>
+      validateCameraExposure({
+        kind: 'auto',
+        fallback: 1,
+        compensationEv: 0,
+        rangeEv: [8, -8],
+        rates: [3, 1],
+      }),
+    ).toThrow();
+    expect(() =>
+      validateCameraExposure({
+        kind: 'auto',
+        fallback: 1,
+        compensationEv: 0,
+        rangeEv: [-8, 8],
+        rates: [-1, 1],
+      }),
+    ).toThrow();
+  });
+
+  it('reports closed structured failures for Camera color fields and column modes', () => {
+    expect(() => validateCameraExposure({ kind: 'manual', multiplier: Number.NaN })).toThrow(
+      CameraError,
+    );
+    expect(() => validateCameraColorGrading(500, 0, 0)).toThrow(CameraError);
+    expect(() => validateCameraColorGrading(6504, 2, 0)).toThrow(CameraError);
+    expect(() =>
+      cameraExposureFromColumns({
+        exposureMode: 7,
+        exposure: 1,
+        compensationEv: 0,
+        rangeEv: new Float32Array([-8, 8]),
+        rates: new Float32Array([3, 1]),
+      }),
+    ).toThrow(CameraError);
+  });
+
+  it('closes the Camera -> SoA extract identity for perspective and orthographic', () => {
+    const world = new World();
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        {
+          component: Camera,
+          data: perspective({
+            fov: Math.PI / 3,
+            aspect: 1,
+            exposure: { kind: 'manual', multiplier: 2 },
+          }),
+        },
+      )
+      .unwrap();
+    const [snapshot] = extractCameraSnapshots(world);
+    expect(snapshot?.output?.exposure).toEqual({ kind: 'manual', multiplier: 2 });
+    expect(snapshot?.output?.temperature).toBe(6504);
+    expect(snapshot?.output?.tint).toBe(0);
+    expect(snapshot?.output?.colorLutStrength).toBe(0);
+    expect(snapshot?.projection).toBe('perspective');
+  });
+});

package/src/components/__tests__/dynamic-resolution-schema.unit.test.ts

@@ -0,0 +1,65 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import {
+  DynamicResolution,
+  type DynamicResolutionData,
+  validateDynamicResolutionParameters,
+} from '../dynamic-resolution';
+
+describe('DynamicResolution authoring schema', () => {
+  it('provides deterministic defaults through the real World component path', () => {
+    const world = new World();
+    const entity = world.spawn({ component: DynamicResolution, data: {} }).unwrap();
+
+    expect(DynamicResolution.name).toBe('DynamicResolution');
+    const defaults = world.get(entity, DynamicResolution).unwrap();
+    expect(defaults).toMatchObject({ maxScale: 1 });
+    // World stores f32 fields, so the authored decimal is represented by its
+    // nearest f32 value rather than the exact JS number.
+    expect(defaults.targetGpuMs).toBeCloseTo(16.67);
+    expect(defaults.minScale).toBeCloseTo(0.67);
+    expect(DynamicResolution.fields).toMatchObject({
+      targetGpuMs: { type: 'f32', default: 16.67 },
+      minScale: { type: 'f32', default: 0.67 },
+      maxScale: { type: 'f32', default: 1 },
+    });
+  });
+
+  it.each([
+    { targetGpuMs: 0, minScale: 0.67, maxScale: 1, field: 'targetGpuMs' },
+    { targetGpuMs: Number.NaN, minScale: 0.67, maxScale: 1, field: 'targetGpuMs' },
+    { targetGpuMs: 16.67, minScale: 0.49, maxScale: 1, field: 'minScale' },
+    { targetGpuMs: 16.67, minScale: 0.8, maxScale: 1.01, field: 'maxScale' },
+    { targetGpuMs: 16.67, minScale: 0.9, maxScale: 0.8, field: 'minScale' },
+  ])('rejects invalid $field before graph construction', (input) => {
+    const result = validateDynamicResolutionParameters(input);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('dynamic-resolution-invalid-parameter');
+      expect(result.error.expected).toContain(input.field);
+      expect(result.error.hint).toContain(input.field);
+      expect(result.error.detail.field).toBe(input.field);
+    }
+  });
+
+  it.each([
+    { targetGpuMs: 1, minScale: 0.5, maxScale: 0.5 },
+    { targetGpuMs: 16.67, minScale: 0.67, maxScale: 1 },
+    { targetGpuMs: 100, minScale: 0.5, maxScale: 1 },
+  ])('accepts boundary values $minScale..$maxScale', (input) => {
+    const result = validateDynamicResolutionParameters(input);
+    expect(result).toEqual({ ok: true, value: input });
+  });
+
+  it('keeps the detached authoring POD limited to the three resolution fields', () => {
+    expectTypeOf<DynamicResolutionData>().toEqualTypeOf<{
+      readonly targetGpuMs: number;
+      readonly minScale: number;
+      readonly maxScale: number;
+    }>();
+    expectTypeOf<keyof DynamicResolutionData>().toEqualTypeOf<
+      'targetGpuMs' | 'minScale' | 'maxScale'
+    >();
+  });
+});

package/src/components/__tests__/light-radius.integration.test.ts

@@ -0,0 +1,59 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { renderComponentsPlugin } from '../../plugin';
+import { DirectionalLight, DirectionalShadowFilterValue } from '../directional-light';
+import { validateDirectionalLightData } from '../light-helpers';
+
+function adjacentFloat32(value: number, direction: -1 | 1): number {
+  const floats = new Float32Array([value]);
+  const bits = new Uint32Array(floats.buffer);
+  bits[0] = (bits[0] ?? 0) + direction;
+  return floats[0] ?? NaN;
+}
+
+describe('PCSS angular radius storage boundary', () => {
+  for (const shadowFilter of [
+    DirectionalShadowFilterValue.pcssMedium,
+    DirectionalShadowFilterValue.pcssHigh,
+  ]) {
+    it(`accepts both authored endpoints after World spawn and set (${shadowFilter})`, async () => {
+      const world = new World();
+      const context = await createWorldContext(world, [renderComponentsPlugin()]);
+      try {
+        for (const radius of [0.0001, 0.05]) {
+          const data = { direction: [0, -1, 0], shadowFilter, shadowAngularRadius: radius };
+          expect(validateDirectionalLightData(data).ok).toBe(true);
+          const entity = world.spawn({ component: DirectionalLight, data }).unwrap();
+          const stored = world.get(entity, DirectionalLight).unwrap();
+          expect(stored.shadowAngularRadius).toBe(Math.fround(radius));
+          expect(validateDirectionalLightData(stored).ok).toBe(true);
+          world.set(entity, DirectionalLight, { shadowAngularRadius: 0.025 }).unwrap();
+          world.set(entity, DirectionalLight, { shadowAngularRadius: radius }).unwrap();
+          expect(
+            validateDirectionalLightData(world.get(entity, DirectionalLight).unwrap()).ok,
+          ).toBe(true);
+        }
+      } finally {
+        await context.fiber.dispose();
+      }
+    });
+  }
+
+  it.each([
+    adjacentFloat32(0.0001, -1),
+    adjacentFloat32(0.05, 1),
+    0,
+    -1,
+    NaN,
+    Infinity,
+    -Infinity,
+  ])('rejects a radius outside the float32 endpoints: %s', (shadowAngularRadius) => {
+    const result = validateDirectionalLightData({
+      direction: [0, -1, 0],
+      shadowFilter: DirectionalShadowFilterValue.pcssHigh,
+      shadowAngularRadius,
+    });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('shadow-invalid-config');
+  });
+});