@forgeax/engine-render 0.1.6 → 0.1.19

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/material/assembly.ts

@@ -39,13 +39,10 @@ function projectPass(
 export function assembleMaterialProjection(record: CookedMaterialRecord): MaterialRenderProjection {
   return {
     materialGuid: record.guid,
-    specializationKey: record.receipt.inputDigest,
+    specializationKey: record.specializationKey ?? record.receipt.identity.programIdentity,
     artifactHash: record.artifact.digest,
     passes: record.resolved.passes.map((pass) => projectPass(record, pass)),
     runtimeValues: record.resolved.values,
-    staticSelection: record.resolved.parameters
-      .filter((parameter) => parameter.static)
-      .map((parameter) => parameter.name)
-      .sort(),
+    staticSelection: [],
   };
 }

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/authoring.ts

@@ -13,4 +13,5 @@ export {
   type FullscreenRenderFeatureOptions,
 } from './features/fullscreen';
 export { SPRITE_PREMULTIPLIED_ALPHA_BLEND } from './materials';
+export { setActiveCamera } from './systems/active-camera';
 export { TransparentSort } from './systems/transparent-sort-config';

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__/points-lines-admission.unit.test.ts

@@ -0,0 +1,219 @@
+import type { MeshAsset, PrimitiveTopology } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  PointsLinesBudgetExceededError,
+  PointsLinesInvalidStyleError,
+  PointsLinesMaterialUnsupportedError,
+  PointsLinesPrepareFailedError,
+  PointsLinesStyleUnsupportedError,
+  PointsLinesTopologyMismatchError,
+} from '../../errors/render';
+import { Materials } from '../../materials';
+import { admitPointsLines, type PointsLinesAdmissionInput } from '../../points-lines/admission';
+
+const unlitMaterial = Materials.unlit([1, 0.5, 0.25, 1], { castShadow: false });
+
+function mesh(topology: PrimitiveTopology, count = 4, indexed = false): MeshAsset {
+  const vertices = new Float32Array(count * 3);
+  return {
+    kind: 'mesh',
+    vertices,
+    ...(indexed ? { indices: new Uint16Array(count) } : {}),
+    attributes: { position: vertices },
+    aabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indexed ? count : 0,
+        vertexCount: count,
+        topology,
+        materialSlot: 0,
+      },
+    ],
+    materialSlots: [{ slotName: 'default' }],
+  };
+}
+
+function pointsInput(
+  overrides: Partial<PointsLinesAdmissionInput> = {},
+): PointsLinesAdmissionInput {
+  return {
+    entity: 7,
+    points: { sizePx: 4, shape: 0 },
+    mesh: mesh('point-list', 3),
+    material: unlitMaterial,
+    ...overrides,
+  };
+}
+
+function linesInput(overrides: Partial<PointsLinesAdmissionInput> = {}): PointsLinesAdmissionInput {
+  return {
+    entity: 8,
+    lines: { widthPx: 1 },
+    mesh: mesh('line-list', 4),
+    material: unlitMaterial,
+    ...overrides,
+  };
+}
+
+function expectRefusal(
+  result: ReturnType<typeof admitPointsLines>,
+  code: string,
+  detail: Record<string, unknown>,
+): void {
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  if (!('detail' in result.error)) throw new Error('expected a detailed Points/Lines refusal');
+  expect(result.error.code).toBe(code);
+  expect(result.error.expected).toEqual(expect.any(String));
+  expect(result.error.hint).toEqual(expect.any(String));
+  expect(result.error.detail).toMatchObject(detail);
+}
+
+describe('Points and Lines admission', () => {
+  it('accepts indexed and non-indexed point and line-list geometry', () => {
+    const indexedPoints = admitPointsLines(pointsInput({ mesh: mesh('point-list', 3, true) }));
+    const nonIndexedLines = admitPointsLines(linesInput());
+
+    expect(indexedPoints.ok).toBe(true);
+    expect(nonIndexedLines.ok).toBe(true);
+    if (indexedPoints.ok) expect(indexedPoints.value.pointCount).toBe(3);
+    if (nonIndexedLines.ok) expect(nonIndexedLines.value.segmentCount).toBe(2);
+  });
+
+  it('rejects component conflicts and invalid numeric styles before topology', () => {
+    const conflict = admitPointsLines(pointsInput({ lines: { widthPx: 1 } }));
+    const invalidSize = admitPointsLines(pointsInput({ points: { sizePx: Number.NaN, shape: 0 } }));
+    const invalidWidth = admitPointsLines(linesInput({ lines: { widthPx: 0 } }));
+
+    expectRefusal(conflict, 'points-lines-invalid-style', {
+      entity: 7,
+      component: 'Points/Lines',
+      field: 'components',
+    });
+    expectRefusal(invalidSize, 'points-lines-invalid-style', {
+      entity: 7,
+      component: 'Points',
+      field: 'sizePx',
+      value: Number.NaN,
+    });
+    expectRefusal(invalidWidth, 'points-lines-invalid-style', {
+      entity: 8,
+      component: 'Lines',
+      field: 'widthPx',
+      value: 0,
+    });
+  });
+
+  it('rejects unsupported topologies, odd line tails, and mixed candidates atomically', () => {
+    const strip = admitPointsLines(linesInput({ mesh: mesh('line-strip', 4) }));
+    const triangles = admitPointsLines(pointsInput({ mesh: mesh('triangle-list', 3) }));
+    const odd = admitPointsLines(linesInput({ mesh: mesh('line-list', 3) }));
+    const baseMixedMesh = mesh('line-list', 2);
+    const mixedMesh: MeshAsset = {
+      ...baseMixedMesh,
+      submeshes: [
+        ...baseMixedMesh.submeshes,
+        {
+          indexOffset: 0,
+          indexCount: 0,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+    };
+    const mixed = admitPointsLines(linesInput({ mesh: mixedMesh }));
+
+    expectRefusal(strip, 'points-lines-style-unsupported', {
+      lane: 'admission',
+      field: 'topology',
+      member: 'line-strip',
+    });
+    expectRefusal(triangles, 'points-lines-topology-mismatch', {
+      entity: 7,
+      expected: 'point-list',
+      actual: 'triangle-list',
+      submesh: 0,
+    });
+    expectRefusal(odd, 'points-lines-topology-mismatch', {
+      entity: 8,
+      expected: 'line-list pairs',
+      actual: 'line-list odd tail',
+      submesh: 0,
+    });
+    expectRefusal(mixed, 'points-lines-topology-mismatch', {
+      entity: 8,
+      submesh: 1,
+    });
+  });
+
+  it('rejects non-unlit materials and explicit resource budgets', () => {
+    const lit = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const material = admitPointsLines(linesInput({ material: lit }));
+    const budget = admitPointsLines(pointsInput({ limits: { maxPoints: 2 } }));
+
+    expectRefusal(material, 'points-lines-material-unsupported', {
+      entity: 8,
+      pass: 'deferred',
+      reason: expect.any(String),
+    });
+    expectRefusal(budget, 'points-lines-budget-exceeded', {
+      lane: 'admission',
+      requested: 3,
+      limit: 2,
+      unit: 'points',
+    });
+  });
+
+  it('keeps every closed refusal detail constructible and code-correlated', () => {
+    const errors = [
+      new PointsLinesInvalidStyleError({
+        entity: 1,
+        component: 'Points',
+        field: 'sizePx',
+        value: -1,
+        expected: 'finite sizePx > 0',
+      }),
+      new PointsLinesTopologyMismatchError({
+        entity: 1,
+        submesh: 0,
+        expected: 'point-list',
+        actual: 'triangle-list',
+      }),
+      new PointsLinesStyleUnsupportedError({
+        lane: 'admission',
+        field: 'topology',
+        member: 'line-strip',
+        supported: ['line-list'],
+      }),
+      new PointsLinesMaterialUnsupportedError({
+        entity: 1,
+        material: 'mat-1',
+        pass: 'forward',
+        module: 'forgeax_material::standard',
+        reason: 'surface lighting is not supported',
+      }),
+      new PointsLinesBudgetExceededError({
+        lane: 'admission',
+        requested: 5,
+        limit: 4,
+        unit: 'points',
+      }),
+      new PointsLinesPrepareFailedError({
+        owner: 'points-lines',
+        generation: 2,
+        stage: 'prepare',
+        cause: 'candidate validation failed',
+        lastKnownGood: false,
+      }),
+    ];
+
+    for (const error of errors) {
+      expect(error.code).toMatch(/^points-lines-/);
+      expect(error.expected).toEqual(expect.any(String));
+      expect(error.hint).toEqual(expect.any(String));
+      expect(error.detail).toBeDefined();
+    }
+  });
+});

package/src/components/__tests__/points-lines-schema.unit.test.ts

@@ -0,0 +1,56 @@
+import { World } from '@forgeax/engine-ecs';
+import type { PointShape } from '@forgeax/engine-render';
+import { Lines, PointShapeValue, Points, pointShapeFromU32 } from '@forgeax/engine-render';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('Points and Lines public schema', () => {
+  it('creates both components through the public import and inserts them in World', () => {
+    const world = new World();
+    const pointEntity = world
+      .spawn({
+        component: Points,
+        data: { sizePx: 8, shape: PointShapeValue.circle },
+      })
+      .unwrap();
+    const lineEntity = world.spawn({ component: Lines, data: { widthPx: 4 } }).unwrap();
+
+    expect(world.get(pointEntity, Points).unwrap()).toMatchObject({
+      sizePx: 8,
+      shape: PointShapeValue.circle,
+    });
+    expect(world.get(lineEntity, Lines).unwrap()).toMatchObject({ widthPx: 4 });
+  });
+
+  it('keeps the frozen defaults and closed point shape decoder', () => {
+    const world = new World();
+    const pointEntity = world.spawn({ component: Points, data: {} }).unwrap();
+    const lineEntity = world.spawn({ component: Lines, data: {} }).unwrap();
+
+    expect(world.get(pointEntity, Points).unwrap()).toMatchObject({
+      sizePx: 4,
+      shape: PointShapeValue.square,
+    });
+    expect(world.get(lineEntity, Lines).unwrap().widthPx).toBe(1);
+    expect(Points.fields).toEqual({
+      sizePx: expect.objectContaining({ type: 'f32', default: 4 }),
+      shape: expect.objectContaining({
+        type: 'enum',
+        default: PointShapeValue.square,
+        labels: PointShapeValue,
+      }),
+    });
+    expect(Lines.fields).toEqual({
+      widthPx: expect.objectContaining({ type: 'f32', default: 1 }),
+    });
+    expect(pointShapeFromU32(PointShapeValue.square)).toBe('square');
+    expect(pointShapeFromU32(PointShapeValue.circle)).toBe('circle');
+    expect(pointShapeFromU32(99)).toBeUndefined();
+  });
+
+  it('exposes only the three first-release style fields', () => {
+    type PublicPointShape = PointShape;
+    expectTypeOf<PublicPointShape>().toEqualTypeOf<'square' | 'circle'>();
+    expectTypeOf<keyof typeof Points.fields>().toEqualTypeOf<'sizePx' | 'shape'>();
+    expectTypeOf<keyof typeof Lines.fields>().toEqualTypeOf<'widthPx'>();
+  });
+});

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,11 +1,21 @@
+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 {
+  type PointShape,
+  PointShapeValue,
+  Points,
+  pointShapeFromU32,
+} from './points';
 export { PostProcessParams } from './post-process-params';
 export {
   SceneInstance,

package/src/components/lines.ts

@@ -0,0 +1,18 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Screen-space independent line segment style. */
+export const Lines = defineComponent(
+  'Lines',
+  {
+    widthPx: { type: 'f32', default: 1 },
+  },
+  {
+    meta: {
+      quickStart: 'Attach Lines to render line-list MeshAsset pairs in screen pixels.',
+      diagnostics: 'Inspect widthPx at the points-lines admission boundary.',
+      recovery: 'Use points-lines-invalid-style for non-finite or non-positive widthPx values.',
+      boundaries:
+        'Lines owns raster width only; MeshFilter and MeshRenderer own geometry and material.',
+    },
+  },
+);

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/points.ts

@@ -0,0 +1,40 @@
+import { defineComponent } from '@forgeax/engine-ecs';
+
+/** Public point raster shapes backed by the ECS enum column. */
+export type PointShape = keyof typeof PointShapeValue;
+
+/** Numeric labels stored by the public Points shape enum field. */
+export const PointShapeValue = Object.freeze({
+  square: 0,
+  circle: 1,
+} as const);
+
+/** Decode the Points shape column without treating an unknown value as valid. */
+export function pointShapeFromU32(value: number): PointShape | undefined {
+  switch (value) {
+    case PointShapeValue.square:
+      return 'square';
+    case PointShapeValue.circle:
+      return 'circle';
+    default:
+      return undefined;
+  }
+}
+
+/** Screen-space point style. Geometry and material remain on their own owners. */
+export const Points = defineComponent(
+  'Points',
+  {
+    sizePx: { type: 'f32', default: 4 },
+    shape: { type: 'enum', default: PointShapeValue.square, labels: PointShapeValue },
+  },
+  {
+    meta: {
+      quickStart: 'Attach Points to render point-list MeshAsset vertices in screen pixels.',
+      diagnostics: 'Inspect sizePx and decode shape with pointShapeFromU32.',
+      recovery: 'Use points-lines-invalid-style for non-finite or non-positive sizePx values.',
+      boundaries:
+        'Points owns raster size and shape only; MeshFilter and MeshRenderer own geometry and material.',
+    },
+  },
+);