@forgeax/engine-render 0.1.6 → 0.1.7

package/src/assembly/factory.ts

@@ -153,9 +153,10 @@ import {
   type PipelineSpec,
   PipelineSpecError,
 } from '../pipeline-spec';
+import { POINTS_LINES_MATERIAL_SHADER_ID } from '../points-lines/record';
 import type { FrameObservationOptions } from '../record/frame';
 import { SHADOW_CASTER_BUFFER_SIZE } from '../record/shadow-pass';
-import { VIEW_UNIFORM_BUFFER_SIZE } from '../record/view-ubo';
+import { POINTS_LINES_VIEW_BUFFER_SIZE, VIEW_UNIFORM_BUFFER_SIZE } from '../record/view-ubo';
 import type {
   DrawOwnerOptions,
   FrameObservationRequest,
@@ -501,7 +502,7 @@ export function selectNoColorPbrVariant(
   variantSet: string | undefined,
 ): MaterialShaderManifestEntry['variants'][number] | undefined {
   const hdrpRequested =
-    variantSet === '' || variantSet?.includes('CLUSTER_FORWARD_AVAILABLE=true') === true;
+    variantSet === '' || (variantSet?.includes('CLUSTER_FORWARD_AVAILABLE=true') ?? false);
   return manifestEntry?.variants.find(
     (variant) =>
       variant.defines.STORAGE_BUFFER_AVAILABLE === storageBufferCapable &&
@@ -694,6 +695,21 @@ export function resolveMaterialShaderVariantSet(
     : sorted.map(([name, value]) => `${name}=${value}`).join('+');
 }
 
+/**
+ * Keep a single-source material on its canonical module identity. A manifest
+ * entry with no variants cannot consume a synthesized capability or geometry
+ * axis, so carrying one into the pipeline cache only creates an uncached lazy
+ * compile beside the prewarmed source module.
+ */
+export function normalizeMaterialShaderVariantSet(
+  requestedVariantSet: string | undefined,
+  manifestEntry: MaterialShaderManifestEntry | undefined,
+): string | undefined {
+  return manifestEntry !== undefined && manifestEntry.variants.length === 0
+    ? undefined
+    : requestedVariantSet;
+}
+
 export async function createRenderer(
   canvas: unknown,
   options?: RendererOptions,
@@ -2073,7 +2089,9 @@ async function makeWebGPURenderer(
     // canonical HDRP variant key and would pair an HDRP PSO with the URP mesh
     // bind group. Builtin forgeax:: shaders keep the compatibility request
     // when a reduced test/legacy manifest omits variant metadata.
-    let effectiveVariantSet = resolvedVariantSet;
+    // A single-source manifest entry must stay on its canonical module key;
+    // otherwise a synthesized capability axis races the prewarmed module.
+    let effectiveVariantSet = normalizeMaterialShaderVariantSet(resolvedVariantSet, manifestEntry);
     if (
       vertexLayoutProjection === undefined &&
       manifestEntry?.variants.some((variant) => 'VERTEX_COLOR_AVAILABLE' in variant.defines)
@@ -2590,6 +2608,7 @@ async function makeWebGPURenderer(
         features: Object.freeze(
           (internals.featureHost?.features ?? []).map((feature) => feature.identity),
         ),
+        featureDiagnostics: internals.featureHost?.diagnostics() ?? Object.freeze([]),
         frustumStats: Object.freeze({ ...renderSystem.frustumStats }),
         visibilityStats: Object.freeze({ ...renderSystem.visibilityStats }),
         renderScene: renderSystem.renderScene,
@@ -3569,6 +3588,13 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
     draw: (request) => {
       const result = renderer.drawFrame(request);
       if (!result.ok) return err(drawError(result.error));
+      emit(
+        Object.freeze({
+          kind: 'frame-submitted',
+          frameId: result.value.frameId,
+          deviceGeneration: result.value.deviceGeneration,
+        }),
+      );
       return ok(result.value);
     },
     inspect: () => renderer.inspect(),
@@ -5082,6 +5108,34 @@ async function buildReadyWebGPU(
         brdfLut: iblBrdfLutEntry.wgsl,
       });
     }
+    // Points/Lines are an engine-owned record path rather than a producer
+    // RenderFeature, so they cannot declare `requiredMaterialShaders`. Their
+    // material pipeline still goes through the same lazy shader-module adapter
+    // as producer features. Prewarm the optional manifest artifact here so a
+    // first frame cannot race async module compilation and silently skip its
+    // draw while the adapter is still pending. Older/minimal manifests may not
+    // carry the optional entry; those hosts retain their existing behavior.
+    const pointsLinesLookup = registry.findMaterialArtifact(POINTS_LINES_MATERIAL_SHADER_ID);
+    if (pointsLinesLookup.ok) {
+      const pointsLinesLabel = `module-${POINTS_LINES_MATERIAL_SHADER_ID}`;
+      const pointsLinesShaderResult = await runShimStep(
+        () =>
+          asyncCreateShaderModule
+            ? asyncCreateShaderModule(rhiDevice, {
+                code: pointsLinesLookup.value.source,
+                label: pointsLinesLabel,
+              })
+            : invokeDeviceCreateShaderModule(rhiDevice, {
+                code: pointsLinesLookup.value.source,
+                label: pointsLinesLabel,
+              }),
+        'shader-compile-failed',
+        `engine material shader '${POINTS_LINES_MATERIAL_SHADER_ID}' compiled`,
+        `inspect the composed WGSL for '${POINTS_LINES_MATERIAL_SHADER_ID}' and check device.features`,
+      );
+      if (!pointsLinesShaderResult.ok) throw pointsLinesShaderResult.error;
+      seedShaderModule(pointsLinesLabel, pointsLinesShaderResult.value);
+    }
     // Producer-declared material shader modules use the same source and module
     // label as getMaterialShaderPipeline. Prewarming them here keeps the
     // renderer.initialization barrier meaningful for prepared graphics: the first draw
@@ -5899,6 +5953,20 @@ async function buildReadyWebGPU(
   );
   if (!viewUboResult.ok) throw viewUboResult.error;
 
+  const pointsLinesViewBufferResult = runShimSyncStep(
+    () =>
+      rhiDevice.createBuffer({
+        label: 'points-lines-view-ubo',
+        size: POINTS_LINES_VIEW_BUFFER_SIZE,
+        usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+        mappedAtCreation: false,
+      }),
+    'webgpu-runtime-error',
+    'createBuffer (points-lines view ubo) succeeded',
+    'check device.limits.maxUniformBufferBindingSize',
+  );
+  if (!pointsLinesViewBufferResult.ok) throw pointsLinesViewBufferResult.error;
+
   // feat-20260613-csm-cascaded-shadow-maps M5 / w28: per-pass cascade-index
   // UBO consumed by shadow_caster.wgsl. Stable singleton; the record stage
   // queue.writeBuffer-overwrites the fields immediately before each pass's
@@ -7817,6 +7885,7 @@ async function buildReadyWebGPU(
     materialBindGroupLayout: materialBglResult.value,
     meshBindGroupLayout: meshArrayBglResult.value,
     viewUniformBuffer: viewUboResult.value,
+    pointsLinesViewBuffer: pointsLinesViewBufferResult.value,
     shadowCasterCascadeBuffer: shadowCasterCascadeUboResult.value,
     // feat-20260608-mesh-ssbo-dynamic-grow-l1-lift-1024-entity-cap M2 /
     // T-M2-05: PipelineState now references the wrapper objects owned by

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/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__/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/index.ts

@@ -2,10 +2,17 @@ export * from './camera';
 export * from './directional-light';
 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,

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

package/src/errors/render.ts

@@ -1101,6 +1101,143 @@ export type RendererExpectedOperationError = {
   readonly [Code in RendererOperationErrorCode]: RendererOperationError<Code>;
 }[RendererOperationErrorCode];
 
+// -- Points/Lines admission errors -------------------------------------------
+
+export interface PointsLinesInvalidStyleDetail {
+  readonly entity: number;
+  readonly component: 'Points' | 'Lines' | 'Points/Lines';
+  readonly field: string;
+  readonly value: number | string | undefined;
+  readonly expected: string;
+}
+
+export class PointsLinesInvalidStyleError extends Error {
+  readonly code = 'points-lines-invalid-style' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesInvalidStyleDetail;
+
+  constructor(detail: PointsLinesInvalidStyleDetail) {
+    super(`invalid ${detail.component} style at ${detail.field}`);
+    this.name = 'PointsLinesInvalidStyleError';
+    this.expected = detail.expected;
+    this.hint = `repair entity ${detail.entity} ${detail.component}.${detail.field} and retry admission`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesTopologyMismatchDetail {
+  readonly entity: number;
+  readonly submesh: number;
+  readonly expected: string;
+  readonly actual: string;
+}
+
+export class PointsLinesTopologyMismatchError extends Error {
+  readonly code = 'points-lines-topology-mismatch' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesTopologyMismatchDetail;
+
+  constructor(detail: PointsLinesTopologyMismatchDetail) {
+    super(`Points/Lines topology mismatch at submesh ${detail.submesh}`);
+    this.name = 'PointsLinesTopologyMismatchError';
+    this.expected = `submesh ${detail.submesh} topology is ${detail.expected}`;
+    this.hint = `rebuild entity ${detail.entity} with ${detail.expected} geometry before retrying Points/Lines admission`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesStyleUnsupportedDetail {
+  readonly lane: string;
+  readonly field: string;
+  readonly member: string;
+  readonly supported: readonly string[];
+}
+
+export class PointsLinesStyleUnsupportedError extends Error {
+  readonly code = 'points-lines-style-unsupported' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesStyleUnsupportedDetail;
+
+  constructor(detail: PointsLinesStyleUnsupportedDetail) {
+    super(`unsupported Points/Lines ${detail.field} member ${detail.member}`);
+    this.name = 'PointsLinesStyleUnsupportedError';
+    this.expected = `${detail.field} is one of ${detail.supported.join(', ')}`;
+    this.hint = `use a supported Points/Lines ${detail.field} member or wait for a later milestone`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesMaterialUnsupportedDetail {
+  readonly entity: number;
+  readonly material: string;
+  readonly pass: string;
+  readonly module: string;
+  readonly reason: string;
+}
+
+export class PointsLinesMaterialUnsupportedError extends Error {
+  readonly code = 'points-lines-material-unsupported' as const;
+  readonly expected = 'one engine-owned unlit forward MaterialAsset pass';
+  readonly hint: string;
+  readonly detail: PointsLinesMaterialUnsupportedDetail;
+
+  constructor(detail: PointsLinesMaterialUnsupportedDetail) {
+    super(`Points/Lines material is unsupported on entity ${detail.entity}`);
+    this.name = 'PointsLinesMaterialUnsupportedError';
+    this.hint = `use Materials.unlit without a shadow-caster pass for entity ${detail.entity}`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesBudgetExceededDetail {
+  readonly lane: string;
+  readonly requested: number;
+  readonly limit: number;
+  readonly unit: 'points' | 'segments' | 'vertices' | 'indices' | 'bytes' | 'draws';
+}
+
+export class PointsLinesBudgetExceededError extends Error {
+  readonly code = 'points-lines-budget-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: PointsLinesBudgetExceededDetail;
+
+  constructor(detail: PointsLinesBudgetExceededDetail) {
+    super(`Points/Lines ${detail.unit} budget exceeded`);
+    this.name = 'PointsLinesBudgetExceededError';
+    this.expected = `${detail.unit} <= ${detail.limit}`;
+    this.hint = `reduce Points/Lines ${detail.unit} or split the entity into bounded equivalent batches`;
+    this.detail = detail;
+  }
+}
+
+export interface PointsLinesPrepareFailedDetail {
+  readonly owner: string;
+  readonly generation: number;
+  readonly stage: 'prepare';
+  readonly cause: string;
+  readonly lastKnownGood: boolean;
+}
+
+export class PointsLinesPrepareFailedError extends Error {
+  readonly code = 'points-lines-prepare-failed' as const;
+  readonly expected = 'the complete Points/Lines candidate validates before publication';
+  readonly hint: string;
+  readonly detail: PointsLinesPrepareFailedDetail;
+
+  constructor(detail: PointsLinesPrepareFailedDetail) {
+    super(`Points/Lines prepare failed at generation ${detail.generation}`);
+    this.name = 'PointsLinesPrepareFailedError';
+    this.hint = detail.lastKnownGood
+      ? 'retain the last known good candidate, repair the producer, and retry prepare'
+      : 'repair the producer and retry prepare; the failed first candidate produces zero draw';
+    this.detail = detail;
+  }
+}
+
 // -- RenderErrorCode / RenderError closed unions --------------------------------
 
 /**
@@ -1138,4 +1275,10 @@ export type RenderError =
   | RenderFeaturePassOrderConflictError
   | RenderFeaturePreparationFailedError
   | RenderFeaturePreparedStateMismatchError
-  | RenderFeatureDrawRecordingFailedError;
+  | RenderFeatureDrawRecordingFailedError
+  | PointsLinesInvalidStyleError
+  | PointsLinesTopologyMismatchError
+  | PointsLinesStyleUnsupportedError
+  | PointsLinesMaterialUnsupportedError
+  | PointsLinesBudgetExceededError
+  | PointsLinesPrepareFailedError;