@forgeax/engine-render 0.1.4 → 0.1.7

package/src/assembly/host-contract.ts

@@ -0,0 +1,101 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { World } from '@forgeax/engine-ecs';
+import type { Result, RhiDevice, RhiError, ShaderModule } from '@forgeax/engine-rhi';
+import type { RecoverFailure } from '../errors/recover';
+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 {
+  DrawOwnerOptions,
+  FrameObservationRequest,
+  FrameReceipt,
+  FrameReceiptObservation,
+  HealthSnapshot,
+  RenderDebugOverlay,
+  RendererError,
+  RendererErrorListener,
+  RendererLostListener,
+  RenderFrameInput,
+  RenderInspection,
+  RenderProfile,
+  RenderResult,
+  RenderWorldLease,
+} from '../render-contract';
+import type { RenderSceneInspection } from '../render-system';
+
+type RenderShaderModuleFactory = (
+  device: RhiDevice,
+  desc: { readonly label?: string | undefined; readonly code: string },
+) => Promise<Result<ShaderModule, RhiError>>;
+
+/** Package-local source projected to the sole public Renderer.subscribe channel. */
+export type RendererHostEvent =
+  | { readonly kind: 'error'; readonly error: RendererError }
+  | { readonly kind: 'health'; readonly health: HealthSnapshot };
+
+export type RendererHostEventListener = (event: RendererHostEvent) => void;
+
+/**
+ * Narrow assembly contract consumed by exposeRenderer and constructRendererHost.
+ * Legacy diagnostics remain on RendererLegacyHostAdapter and cannot leak into
+ * the public Renderer type.
+ */
+export interface RendererHostImplementation {
+  attach(world: World): RenderResult<RenderWorldLease, RenderError>;
+  setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
+  inspect(): RenderInspection;
+  drawFrame(request: RenderFrameInput): RenderResult<FrameReceipt, RhiError | RenderError>;
+  observe(
+    receipt: FrameReceipt,
+    request: FrameObservationRequest,
+  ): Promise<RenderResult<FrameReceiptObservation, RenderError>>;
+  releaseSurface(): RenderResult<void, RhiError>;
+  restoreSurface(): RenderResult<void, RhiError>;
+  recover(): Promise<Result<void, RecoverFailure>>;
+  dispose(): RenderResult<void, RenderError>;
+  /** @internal Single event source used to construct public Renderer.subscribe. */
+  subscribeHostEvents(listener: RendererHostEventListener): () => void;
+
+  readonly device: RhiDevice;
+  /** @internal */
+  readonly _internal_createShaderModule: RenderShaderModuleFactory;
+  /** @internal */
+  readonly _internal_setRenderOverlay: (overlay: RenderDebugOverlay | undefined) => void;
+  readonly assetRegistry: AssetRegistry;
+  readonly initialization: Promise<RenderResult<void, RhiError>>;
+}
+
+/**
+ * @internal
+ * Temporary package-local compatibility surface for unmigrated render tests
+ * and producers. It is intentionally absent from RendererHostImplementation.
+ */
+export interface RendererLegacyHostAdapter {
+  attachScene(world: World): RenderResult<void, RhiError>;
+  detachScene(world: World): void;
+  draw(
+    worldsOrRequest: readonly World[] | RenderFrameInput,
+    options?: DrawOwnerOptions,
+  ): RenderResult<void | FrameReceipt, RhiError | RenderError>;
+  observeCurrentFrame(
+    options: FrameObservationOptions,
+  ): Promise<RenderResult<FrameObservation, ObservationUnavailableError>>;
+  onLost(listener: RendererLostListener): () => void;
+  onError(listener: RendererErrorListener): () => void;
+  health(): HealthSnapshot;
+  readonly frustumStats: { readonly culled: number; readonly total: number };
+  readonly visibilityStats: { readonly explicitlyHidden: number };
+  readonly renderScene: RenderSceneInspection;
+  readonly meshMaterialBindings: readonly MeshMaterialBindingObservation[];
+  readonly perFramePassNames: readonly string[];
+  renderFeatureDiagnostics(): readonly RenderFeatureDiagnostics[];
+  installRenderFeature(feature: RenderFeature<unknown>): Promise<RenderResult<void, RenderError>>;
+  uninstallRenderFeature(feature: RenderFeature<unknown>): Promise<RenderResult<void, RenderError>>;
+  readonly bindGroupCounts: { readonly createBindGroup: number; readonly keys: readonly string[] };
+}
+
+/** @internal Concrete factory object before it is narrowed by exposeRenderer. */
+export interface RendererAssemblyImplementation
+  extends RendererHostImplementation,
+    RendererLegacyHostAdapter {}

package/src/{renderer → assembly}/material/assembly.ts

@@ -15,7 +15,6 @@ export interface MaterialRenderProjection {
   readonly materialGuid: string;
   readonly specializationKey: string;
   readonly artifactHash: string;
-  readonly layoutIdentity: string;
   readonly passes: readonly MaterialRenderPassProjection[];
   readonly runtimeValues: Readonly<Record<string, MaterialValue | null>>;
   readonly staticSelection: readonly string[];
@@ -40,14 +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,
-    layoutIdentity: record.receipt.layoutIdentity,
     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/material/pipeline-projection.ts

@@ -0,0 +1,63 @@
+import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
+import type { MaterialValue } from '@forgeax/engine-types';
+import type { MaterialRenderProjection } from './assembly.js';
+
+export interface MaterialPipelineProjection {
+  readonly specializationKey: string;
+  readonly artifactHash: string;
+  readonly passes: MaterialRenderProjection['passes'];
+}
+
+export interface MaterialPipelineReady extends MaterialPipelineProjection {
+  readonly kind: 'ready';
+  readonly artifact: MaterialRuntimeArtifact;
+}
+
+export interface MaterialPipelineMiss {
+  readonly kind: 'error';
+  readonly error: {
+    readonly code: 'material-specialization-not-cooked';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: { readonly specializationKey: string };
+  };
+}
+
+export function projectMaterialPipeline(
+  projection: MaterialRenderProjection,
+): MaterialPipelineProjection {
+  return {
+    specializationKey: projection.specializationKey,
+    artifactHash: projection.artifactHash,
+    passes: projection.passes,
+  };
+}
+
+export function updateMaterialRuntimeValues(
+  projection: MaterialRenderProjection,
+  values: Readonly<Record<string, MaterialValue | null>>,
+): MaterialRenderProjection {
+  return {
+    ...projection,
+    runtimeValues: { ...projection.runtimeValues, ...values },
+  };
+}
+
+export function routeMaterialPipeline(args: {
+  readonly projection: MaterialRenderProjection;
+  readonly lookupArtifact: (key: string) => MaterialRuntimeArtifact | undefined;
+}): MaterialPipelineReady | MaterialPipelineMiss {
+  const artifact = args.lookupArtifact(args.projection.specializationKey);
+  if (artifact === undefined || artifact.digest !== args.projection.artifactHash) {
+    return {
+      kind: 'error',
+      error: {
+        code: 'material-specialization-not-cooked',
+        expected: 'a published artifact for the cooked specialization key',
+        hint: 'cook and publish the material specialization before rendering it',
+        detail: { specializationKey: args.projection.specializationKey },
+      },
+    };
+  }
+  return { kind: 'ready', ...projectMaterialPipeline(args.projection), artifact };
+}

package/src/authoring.ts

@@ -1,24 +1,17 @@
 // Optional authoring features intentionally live outside the base render vocabulary.
-export * from './components/glyph-text';
-export * from './components/sprite-animation';
-export * from './components/sprite-instances';
-export * from './components/sprite-playback-mode';
-export * from './components/sprite-region-override';
-export * from './components/tile-layer';
-export * from './components/tilemap';
-export { glyphTextLayoutSystem, resetGlyphBakeCache } from './glyph-text-layout-system';
+// Systems, asset resolution, and registry details remain owner-local.
+
+export { GlyphText } from './components/glyph-text';
+export { SpriteAnimation } from './components/sprite-animation';
+export { SpriteInstances, type SpriteInstancesData } from './components/sprite-instances';
+export { SpritePlayback, spritePlaybackModeFromU32 } from './components/sprite-playback-mode';
+export { SpriteRegionOverride } from './components/sprite-region-override';
+export { TileLayer, TilemapSort } from './components/tile-layer';
+export { Tilemap } from './components/tilemap';
 export {
-  Materials,
-  materialTextureValue,
-  SPRITE_PREMULTIPLIED_ALPHA_BLEND,
-} from './materials';
-export {
-  getTransparentSortConfig,
-  setTransparentSortConfig,
-  TRANSPARENT_SORT_MODE_DISTANCE,
-  TRANSPARENT_SORT_MODE_LAYER_Y,
-  TRANSPARENT_SORT_MODE_LAYER_YZ,
-  TRANSPARENT_SORT_MODE_LAYER_Z,
-  type TransparentSortConfig,
-} from './systems/transparent-sort-config';
-export { tilemapChunkExtractSystem } from './tilemap-chunk-extract-system';
+  createFullscreenRenderFeature,
+  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__/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

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { Camera, DirectionalLight, 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);
+  });
+});

package/src/components/glyph-text.ts

@@ -13,7 +13,7 @@
 // Schema vocab:
 //   - `fontHandle: 'shared<FontAsset>'` -> `Handle<'FontAsset', 'shared'>`
 //     (u32-stored; AssetRegistry owns the FontAsset lifecycle). AI users
-//     obtain the handle via `assets.load(guid, fontAssetKind)`.
+//     obtain the handle via `assets.loadByGuid<FontAsset>(guid)`.
 //   - `text: 'string'` -> native JS string (UniqueRefStore-backed, same
 //     dispatch as `Name.value`).
 //   - `fontSize: 'f32'` -> layout scale applied to the FontAsset metrics.
@@ -41,7 +41,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *
  * @example Spawn a world-space label:
  *   import { GlyphText } from '@forgeax/engine-render/authoring';
- *   const font = (await assets.load(fontGuid, fontAssetKind)).unwrap();
+ *   const font = (await assets.loadByGuid(fontGuid)).unwrap();
  *   world.spawn({
  *     component: GlyphText,
  *     data: { fontHandle: font, text: 'Hello', fontSize: 32,
@@ -54,6 +54,7 @@ export const GlyphText = defineComponent('GlyphText', {
   fontHandle: {
     type: 'shared<FontAsset>',
     default: 0 as never,
+    simulationTransient: true,
   },
   text: { type: 'string', default: '' },
   fontSize: { type: 'f32', default: 16 },

package/src/components/index.ts

@@ -1,26 +1,31 @@
-export { Atmosphere } from './atmosphere';
 export * from './camera';
 export * from './directional-light';
-export {
-  Fog,
-  SKYBOX_MODE_CUBEMAP,
-  SkyboxBackground,
-  type SkyboxMode,
-  Skylight,
-  skyboxModeFromF32,
-} from './environment';
 export { Instances, type InstancesData } from './instances';
 export { Layer } from './layer';
+export { Lines } from './lines';
 export * from './mesh-filter';
 export * from './mesh-renderer';
 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,
   type SceneInstanceOverrideRecord,
   type SceneInstanceState,
 } from './scene-instance';
+export {
+  SKYBOX_MODE_CUBEMAP,
+  SkyboxBackground,
+  type SkyboxMode,
+  skyboxModeFromF32,
+} from './skybox-background';
+export { Skylight } from './skylight';
 export { SortKey } from './sort-key';
 export { SpotLight } from './spot-light';
 export { SpriteAnimation } from './sprite-animation';

package/src/components/instances.ts

@@ -55,7 +55,7 @@
 // responsibility migration): the legacy component-level
 // stride-declaration option (`{ transforms: 16 }` keyed on the retired
 // per-component stride defineComponent option key) was retired because:
-//   - The ECS layer no longer carries any per-component stride schema (M2 /
+//   - The ECS layer no longer carries a per-component stride schema (M2 /
 //     w9 dropped the option from `DefineComponentOptions` -- the SSOT
 //     moved to the RenderSystem entry + AI user set site).
 //   - Centralising the check at the consumer (RenderSystem extract) rather
@@ -98,8 +98,7 @@
 // ===== (a) single-component import + spawn example =====
 //
 //   import {
-//     createRenderer,
-//     createPrimitiveMesh,
+//     createRenderer, HANDLE_CUBE,
 //     MeshFilter, MeshRenderer, Transform,
 //     Instances, type InstancesData,
 //   } from '@forgeax/engine-render';
@@ -108,7 +107,7 @@
 //   const transforms = new Float32Array(N * 16);
 //   // ... fill column-major mat4 columns per instance ...
 //   world.spawn(
-//     { component: MeshFilter,    data: { assetHandle: cubeMesh } },
+//     { component: MeshFilter,    data: { assetHandle: HANDLE_CUBE } },
 //     { component: MeshRenderer,  data: {} },
 //     { component: Instances,     data: { transforms } },
 //   );
@@ -181,7 +180,7 @@ import { defineComponent } from '@forgeax/engine-ecs';
  *   const transforms = new Float32Array(10000 * 16);
  *   // ... fill column-major mat4 columns ...
  *   world.spawn(
- *     { component: MeshFilter,   data: { assetHandle: cubeMesh } },
+ *     { component: MeshFilter,   data: { assetHandle: HANDLE_CUBE } },
  *     { component: MeshRenderer, data: { ... } },
  *     { component: Instances,    data: { transforms } },
  *   );

package/src/components/light-helpers.ts

@@ -15,7 +15,7 @@
 // invRangeSquared = 1e8 protects the 0 * Infinity = NaN intermediate).
 
 import { err, ok, type Result } from '@forgeax/engine-types';
-import { SpawnLightInvalidBoundsError } from '../errors';
+import { SpawnLightInvalidBoundsError } from '../errors/ecs-validation';
 import { ShadowInvalidConfigError } from '../errors/render';
 
 export type LightValidationError = SpawnLightInvalidBoundsError | ShadowInvalidConfigError;

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.',
+    },
+  },
+);