@forgeax/engine-render 0.1.23 → 0.1.24

package/src/pbr-pipeline.ts

@@ -32,7 +32,11 @@ import type {
   TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
-import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA, type ShaderCatalog } from '@forgeax/engine-shader';
+import {
+  type ShaderCatalog,
+  STANDARD_PIPELINE_PARAM_SCHEMA,
+  standardPhysicalTextureFields,
+} from '@forgeax/engine-shader';
 import { derive, type ParamSchemaEntry } from '@forgeax/engine-types';
 import { GPU_SHADER_STAGE_FRAGMENT, GPU_SHADER_STAGE_VERTEX } from './gpu-stage';
 import type { PipelineSpec } from './pipeline-spec-types';
@@ -101,11 +105,13 @@ export function standardPbrColorFormats(
 /**
  * The built-in standard-PBR material paramSchema's texture/user-region shape,
  * used as the fallback when the material BGL is built without a registry
- * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the 8 Standard
- * user-region textures + a numeric UBO run; `derive()` collapses the numerics
- * into binding 0 and emits sampler/texture pairs at 1..6 — byte-equivalent to
- * the legacy fixed base-7. The shared PBR parameter contract comes from the
- * shader package; this module only derives the GPU layout.
+ * (the caps-driven `buildPbrPipelineLayouts` seam). Declares the canonical
+ * Standard user-region textures + a numeric UBO run; `derive()` collapses the
+ * numerics into binding 0 and emits one sampler/texture pair per declared
+ * texture. Physical map pairs stay outside this boot region and are appended
+ * only for an authored root that declares them. The shared PBR parameter
+ * contract comes from the shader package; this module only derives the GPU
+ * layout.
  */
 /**
  * Build the PBR material BGL **user-region** from a paramSchema via the
@@ -116,9 +122,10 @@ export function standardPbrColorFormats(
  * custom schema (e.g. parallax + heightTexture) shifts the injection region by
  * one sampler/texture pair automatically.
  *
- * The built-in `default-standard-pbr` paramSchema declares exactly 8 textures,
- * so this derives to binding 0 UBO + 8 pairs = 17 entries. Injection is appended
- * after that derived region.
+ * The canonical `STANDARD_PIPELINE_PARAM_SCHEMA` currently declares seven
+ * non-physical textures, so this derives to binding 0 UBO + seven pairs = 15
+ * entries. IBL and transmission injection are appended after that region;
+ * authored physical maps are appended after the engine-owned injections.
  *
  * One material-UBO convention is layered on top of the pure `derive()` output:
  * binding 0 is patched to `{ type: 'uniform', hasDynamicOffset: true }` with
@@ -132,9 +139,18 @@ export function standardPbrColorFormats(
  *   built-in standard-PBR shape when omitted, for the caps-driven seam).
  */
 export function buildPbrMaterialUserRegionEntries(
-  paramSchema: readonly ParamSchemaEntry[] = DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  paramSchema: readonly ParamSchemaEntry[] = STANDARD_PIPELINE_PARAM_SCHEMA,
+  excludedTextureFields: readonly string[] = [],
 ): GPUBindGroupLayoutEntry[] {
-  const derived = derive(paramSchema);
+  const excluded = new Set(excludedTextureFields);
+  for (const field of standardPhysicalTextureFields(paramSchema)) excluded.add(field);
+  const derived = derive(
+    excluded.size === 0
+      ? paramSchema
+      : paramSchema.filter(
+          (entry) => !excluded.has(entry.name) || !entry.type.startsWith('texture'),
+        ),
+  );
   // Project the engine-owned entry shape into the DOM WebGPU descriptor. Omit
   // absent optional members so exactOptionalPropertyTypes remains true at the
   // boundary instead of leaking an `undefined` property into the descriptor.
@@ -330,6 +346,68 @@ export const INJECTION_KIND_LENGTHS = {
   transmission: TRANSMISSION_INJECTION_LENGTH,
 };
 
+export function physicalTextureFields(paramSchema: readonly ParamSchemaEntry[]): readonly string[] {
+  return standardPhysicalTextureFields(paramSchema);
+}
+
+export function appendTextureInjection(
+  bgl: readonly GPUBindGroupLayoutEntry[],
+  fields: readonly string[],
+): GPUBindGroupLayoutEntry[] {
+  const start = bgl.length;
+  const fieldSet = new Set(fields);
+  return standardPhysicalTextureFields(
+    fields.map((name) => ({ name, type: 'texture2d' as const })),
+  ).flatMap((field, index) => {
+    if (!fieldSet.has(field)) return [];
+    const binding = start + index * 2;
+    return [
+      {
+        binding,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        sampler: { type: 'filtering' as const },
+      },
+      {
+        binding: binding + 1,
+        visibility: GPU_SHADER_STAGE_FRAGMENT,
+        texture: { sampleType: 'float' as const, viewDimension: '2d' as const },
+      },
+    ];
+  });
+}
+
+/**
+ * Return the stable identity of the merged material bind-group layout.
+ *
+ * This is deliberately derived from the same descriptor builder consumed by
+ * the device path. Callers use it to keep pipeline, bind-group, and
+ * frame-local lookup caches on one layout identity even when equivalent
+ * paramSchema arrays were allocated independently.
+ */
+export function materialBindGroupLayoutIdentity(
+  shaderId: string,
+  paramSchema: readonly ParamSchemaEntry[],
+): string {
+  const descriptor = buildBindGroupLayoutDescriptor(
+    {
+      shader: { id: shaderId, passKind: 'forward', variantSet: undefined },
+      attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+      geometry: { topology: 'triangle-list', vertexLayout: {} },
+      renderState: undefined,
+    },
+    { kind: 'pbr-material-merged', materialParamSchema: paramSchema },
+  );
+  // Descriptor shape alone cannot distinguish two Standard roots that expose
+  // the same number of physical texture pairs under different semantic names.
+  // The resource order is part of the admitted root contract, so include the
+  // canonical physical projection in the cache identity while keeping the
+  // actual WebGPU descriptor owned by the builder above.
+  return JSON.stringify({
+    entries: descriptor.entries,
+    physicalTextureFields: physicalTextureFields(paramSchema),
+  });
+}
+
 /**
  * Caps shape consumed by the BGL factory functions for storage-buffer vs
  * uniform-buffer branching. Mirrors the two fields the engine reads from
@@ -568,7 +646,7 @@ export function buildPbrPipelineLayouts(
 
   // Material BGL: derived user region + Skylight + transmission injection.
   // The transmission start binding is computed from the post-Skylight BGL
-  // length (= 24 for the built-in Standard schema) by appendInjection.
+  // length (= 22 for the canonical Standard schema) by appendInjection.
   const materialBglRes = device.createBindGroupLayout(
     buildBindGroupLayoutDescriptor(BGL_ONLY_SPEC_STUB, { kind: 'pbr-material-merged' }),
   );
@@ -658,6 +736,21 @@ export function buildPbrPipelineLayouts(
 export const SKIN_MATERIAL_SHADER_ID = 'forgeax::pbr-skin' as const;
 export const SHADOW_CASTER_SHADER_ID = 'forgeax::default-shadow-caster' as const;
 
+// Authored Standard templates are published under a unique module id for each
+// root contract.  Keep the family marker in the id so every downstream render
+// owner (extract, layout, and record) can make the same Standard-vs-custom and
+// rigid-vs-skinned decision without a second registry or a runtime shader
+// inspection pass.
+const AUTHORED_STANDARD_ID_RE = /::(?:standard|pbr-skin)(?:-|$)/;
+
+export function isStandardPbrSkinMaterialShader(shaderId: string | undefined): boolean {
+  return (
+    shaderId === SKIN_MATERIAL_SHADER_ID ||
+    shaderId === 'forgeax::default-standard-pbr-skin' ||
+    (shaderId !== undefined && /::pbr-skin(?:-|$)/.test(shaderId))
+  );
+}
+
 export function shadowCasterVariantSet(storageBuffer: boolean, skinned: boolean): string {
   const skinningDisabled = !skinned;
   if (storageBuffer && skinningDisabled) return '';
@@ -692,6 +785,22 @@ export function resolvePipelineGroup2Contract(source: string): PipelineGroup2Con
 
 /** Returns true for the engine-shipped standard-PBR material shader family. */
 export function isStandardPbrMaterialShader(shaderId: string | undefined): boolean {
+  return (
+    shaderId === 'forgeax::default-standard-pbr' ||
+    shaderId === SKIN_MATERIAL_SHADER_ID ||
+    shaderId === 'forgeax::default-standard-pbr-skin' ||
+    (shaderId !== undefined && AUTHORED_STANDARD_ID_RE.test(shaderId))
+  );
+}
+
+/**
+ * Return true only for the two engine-owned Standard roots. Authored Standard
+ * aliases intentionally remain outside this set: their cooked root schema may
+ * omit transmission or other optional resources, so their compact user-region
+ * layout must be derived from that artifact instead of borrowing the boot
+ * layout's reserved slots.
+ */
+export function isCanonicalStandardPbrMaterialShader(shaderId: string | undefined): boolean {
   return (
     shaderId === 'forgeax::default-standard-pbr' ||
     shaderId === SKIN_MATERIAL_SHADER_ID ||
@@ -1240,14 +1349,29 @@ export function buildBindGroupLayoutDescriptor(
       // + IBL injection (7) + transmission injection (2). The user-region
       // size is the only variable; injection start = userRegion.length so a
       // custom schema shifts IBL/transmission by its sampler/texture pairs.
-      // The built-in 8-texture standard-PBR schema is 17 + 7 + 2 = 26 entries.
+      // The built-in standard-PBR schema is 17 + 7 + 2 = 26 entries;
+      // clearcoat texture pairs are derived from the effective root schema.
       //
       // Schema source priority (D-1): explicit materialParamSchema option >
       // registry lookup of spec.shader.id > built-in standard-PBR fallback.
       const resolvedSchema = resolveMaterialParamSchema(spec, options);
-      const userRegion = buildPbrMaterialUserRegionEntries(resolvedSchema);
+      const effectiveSchema = resolvedSchema ?? STANDARD_PIPELINE_PARAM_SCHEMA;
+      const physicalFields = physicalTextureFields(effectiveSchema);
+      // Standard's built-in shader keeps the transmission user-region slots
+      // reserved even when a particular root omits those values.  Physical
+      // maps extend that canonical region; they must not compact the IBL
+      // bindings to the smaller authored subset.  A compact user region is
+      // still correct for authored (non-engine) material shaders.
+      const userRegionSchema = isCanonicalStandardPbrMaterialShader(spec.shader.id)
+        ? STANDARD_PIPELINE_PARAM_SCHEMA
+        : effectiveSchema;
+      const userRegion = buildPbrMaterialUserRegionEntries(userRegionSchema);
       const afterIbl = [...userRegion, ...appendInjection(userRegion, 'ibl')];
-      const merged = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const afterTransmission = [...afterIbl, ...appendInjection(afterIbl, 'transmission')];
+      const merged = [
+        ...afterTransmission,
+        ...appendTextureInjection(afterTransmission, physicalFields),
+      ];
       return {
         label: 'pbr-material-skylight-bgl',
         entries: merged,

package/src/points-lines/__tests__/cache-recovery.unit.test.ts

@@ -154,4 +154,26 @@ describe('Points/Lines expansion cache and LKG recovery', () => {
     expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
     expect(preparation.inspect()).toMatchObject({ status: 'resident', lastKnownGood: true });
   });
+
+  it('abandons lost-device handles without invoking the dead-device destroy path', () => {
+    let destroys = 0;
+    const preparation = new PointsLinesPreparation({
+      cache: new PointsLinesExpansionCache(),
+      adapter: {
+        create: () => ok('lost-device-resource'),
+        upload: () => ok(64),
+        validate: () => ok(undefined),
+        destroy: () => {
+          destroys += 1;
+        },
+      },
+    });
+
+    expect(preparation.prepare(snapshot(), mesh()).ok).toBe(true);
+    preparation.abandonForDeviceLoss();
+    preparation.abandonForDeviceLoss();
+
+    expect(destroys).toBe(0);
+    expect(preparation.inspect()).toMatchObject({ status: 'rebuild-pending', liveBytes: 0 });
+  });
 });

package/src/points-lines/prepare.ts

@@ -37,6 +37,8 @@ export interface PointsLinesLanePreparationAdapter<Resource> {
     mesh: MeshAsset,
   ): Result<PointsLinesPreparedResource<Resource>, PointsLinesPrepareFailedError>;
   resetForDeviceLoss(): void;
+  /** Drop lost-device handles without calling destroy on the dead device. */
+  abandonForDeviceLoss(): void;
   lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined;
   inspect(): PointsLinesPreparationInspection<Resource>;
 }
@@ -121,6 +123,12 @@ export class PointsLinesPreparation<Resource> {
     this.status = 'rebuild-pending';
   }
 
+  abandonForDeviceLoss(): void {
+    this.live = undefined;
+    this.pendingCandidateBytes = 0;
+    this.status = 'rebuild-pending';
+  }
+
   lastKnownGood(): PointsLinesPreparedResource<Resource> | undefined {
     return this.live;
   }
@@ -171,6 +179,7 @@ export function createPointsLinesLanePreparationAdapter<Resource>(
     contract: createPointsLinesLaneContract(lane, backend),
     prepare: (snapshot, mesh) => preparation.prepare(snapshot, mesh),
     resetForDeviceLoss: () => preparation.resetForDeviceLoss(),
+    abandonForDeviceLoss: () => preparation.abandonForDeviceLoss(),
     lastKnownGood: () => preparation.lastKnownGood(),
     inspect: () => preparation.inspect(),
   };

package/src/points-lines/standard-owner.ts

@@ -0,0 +1,403 @@
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
+import { err, ok } from '@forgeax/engine-rhi';
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { PointsLinesMaterialUnsupportedError } from '../errors/render';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_INDEX,
+  GPU_BUFFER_USAGE_VERTEX,
+} from '../gpu-usage';
+import type { ValidatedRenderable } from '../record/frame-snapshot';
+import type {
+  PointsLinesRecordOwner,
+  PointsLinesRecordSubmission,
+  RenderSystemInternals,
+} from '../record/render-context';
+import type { RecoveryPointsLinesCandidate } from '../render-system';
+import { admitPointsLines } from './admission';
+import { PointsLinesExpansionCache } from './expansion-cache';
+import type { PointsLinesInspection, PointsLinesSourceError } from './inspection';
+import { inspectPointsLines } from './inspection';
+import {
+  createPointsLinesLanePreparationAdapter,
+  type PointsLinesLanePreparationAdapter,
+} from './prepare';
+import {
+  createPointsLinesLaneAdapter,
+  type PointsLinesBackend,
+  type PointsLinesLane,
+} from './record';
+import type { PointsLinesRetainedSnapshot } from './snapshot';
+
+type PointsLinesGpuResources = {
+  readonly vertexBuffer: import('@forgeax/engine-rhi').Buffer;
+  readonly indexBuffer: import('@forgeax/engine-rhi').Buffer;
+};
+type PointsLinesPreparationAdapter = PointsLinesLanePreparationAdapter<PointsLinesGpuResources>;
+
+/**
+ * The Standard renderer's single Points/Lines prepare owner.
+ *
+ * The retained snapshot is the identity boundary; this owner only resolves
+ * the source assets, runs admission, and publishes the existing preparation
+ * and record contracts to the main geometry loop. The expansion cache is
+ * shared across lanes and this owner keeps the one prepared vertex/index
+ * resource pair for each retained identity.
+ */
+export class StandardPointsLinesOwner implements PointsLinesRecordOwner {
+  private readonly cache = new PointsLinesExpansionCache();
+  private readonly preparations = new Map<string, PointsLinesPreparationAdapter>();
+  private readonly active = new Map<string, PointsLinesInspection>();
+  private readonly layoutProjection = deriveVertexLayoutProjection({
+    position: new Float32Array(0),
+    normal: new Float32Array(0),
+    uv: new Float32Array(0),
+    tangent: new Float32Array(0),
+  });
+
+  constructor(private readonly internals: RenderSystemInternals) {}
+
+  beginFrame(): void {
+    this.active.clear();
+  }
+
+  prepare(entry: ValidatedRenderable, clustered: boolean): PointsLinesRecordSubmission | undefined {
+    return this.prepareWithMaps(entry, clustered, this.internals, this.preparations, this.active);
+  }
+
+  prepareRecoveryCandidate(
+    entries: readonly ValidatedRenderable[],
+    clustered: boolean,
+    runtime: RenderSystemInternals,
+  ): RecoveryPointsLinesCandidate | undefined {
+    const stagedPreparations = new Map<string, PointsLinesPreparationAdapter>();
+    const stagedInspections = new Map<string, PointsLinesInspection>();
+    let pointEntryCount = 0;
+    try {
+      for (const entry of entries) {
+        const snapshot = entry.source.pointsLines;
+        if (snapshot?.component === undefined) continue;
+        pointEntryCount += 1;
+        const prepared = this.prepareWithMaps(
+          entry,
+          clustered,
+          runtime,
+          stagedPreparations,
+          stagedInspections,
+        );
+        if (prepared === undefined) {
+          throw new Error(
+            `recovery Points/Lines preparation failed for ${snapshot.worldId}:${snapshot.entityKey}`,
+          );
+        }
+      }
+    } catch (cause) {
+      for (const preparation of stagedPreparations.values()) {
+        preparation.resetForDeviceLoss();
+      }
+      throw cause;
+    }
+    if (pointEntryCount === 0) return undefined;
+
+    let released = false;
+    let published = false;
+    const candidate: RecoveryPointsLinesCandidate = {
+      createRecoveryRoot: (scope) => ({
+        kind: 'buffer',
+        create: () => {
+          if (!scope.isAlive() || released) {
+            throw new Error('Points/Lines recovery candidate scope is not active.');
+          }
+          return candidate;
+        },
+        cleanup: () => candidate.release(),
+      }),
+      publish: () => {
+        if (released || published) return;
+        this.preparations.clear();
+        for (const [key, preparation] of stagedPreparations) {
+          this.preparations.set(key, preparation);
+        }
+        published = true;
+      },
+      release: () => {
+        if (released || published) return;
+        released = true;
+        for (const preparation of stagedPreparations.values()) {
+          preparation.resetForDeviceLoss();
+        }
+        stagedPreparations.clear();
+        stagedInspections.clear();
+      },
+    };
+    return candidate;
+  }
+
+  private prepareWithMaps(
+    entry: ValidatedRenderable,
+    clustered: boolean,
+    runtime: RenderSystemInternals,
+    preparations: Map<string, PointsLinesPreparationAdapter>,
+    inspections: Map<string, PointsLinesInspection>,
+  ): PointsLinesRecordSubmission | undefined {
+    const snapshot = entry.source.pointsLines;
+    if (snapshot === undefined || snapshot.component === undefined || entry.world === undefined) {
+      return undefined;
+    }
+    const key = `${snapshot.worldId}:${snapshot.entityKey}`;
+    const topology = snapshot.component === 'Points' ? 'point-list' : 'line-list';
+    const backend = this.backend(runtime);
+    const lane = backend === 'wgpu-webgl2' ? 'cpu-webgl2' : clustered ? 'clustered' : 'direct';
+    const meshResult = resolveAssetHandle<MeshAsset>(
+      entry.world,
+      toShared<'MeshAsset'>(entry.source.assetHandle),
+    );
+    const materialResult = resolveAssetHandle<MaterialAsset>(
+      entry.world,
+      toShared<'MaterialAsset'>(snapshot.materialHandle),
+    );
+    if (!meshResult.ok || !materialResult.ok) {
+      this.publishRefusal(
+        inspections,
+        snapshot,
+        new PointsLinesMaterialUnsupportedError({
+          entity: snapshot.entityKey,
+          material: 'unresolved',
+          pass: 'forward',
+          module: 'asset-resolution',
+          reason: 'source MeshAsset or MaterialAsset could not be resolved',
+        }),
+      );
+      return undefined;
+    }
+    const admission = admitPointsLines({
+      entity: snapshot.entityKey,
+      mesh: meshResult.value,
+      material: materialResult.value,
+      ...(snapshot.style?.kind === 'points'
+        ? {
+            points: {
+              sizePx: snapshot.style.sizePx,
+              shape: snapshot.style.shape === 'circle' ? 1 : 0,
+            },
+          }
+        : { lines: { widthPx: snapshot.style?.widthPx ?? 1 } }),
+    });
+    if (!admission.ok) {
+      this.publishRefusal(inspections, snapshot, admission.error);
+      return undefined;
+    }
+    const geometryKey = this.cache.getOrCreate(snapshot, meshResult.value).key;
+    const prepKey = `${geometryKey}:${lane}:${backend}`;
+    let preparation = preparations.get(prepKey);
+    if (preparation === undefined) {
+      // A new expansion is visible cold upload work. Candidate preparation
+      // uses an unarmed runtime and stages the result; the published runtime
+      // is armed, so a missing staged resource fails before any RHI create.
+      runtime.recoveryColdWorkGuard?.noteUploadColdWork();
+      preparation = this.createPreparation(runtime, geometryKey, lane, backend);
+      preparations.set(prepKey, preparation);
+    } else if (preparation.lastKnownGood()?.geometry.key !== geometryKey) {
+      runtime.recoveryColdWorkGuard?.noteUploadColdWork();
+    }
+    const prepared = preparation.prepare(snapshot, meshResult.value);
+    if (!prepared.ok) {
+      const lkg = preparation.lastKnownGood();
+      if (lkg !== undefined) {
+        const lkgPlan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+          lkg.snapshot,
+          lkg.geometry,
+        );
+        const state = preparation.inspect();
+        inspections.set(
+          key,
+          inspectPointsLines({
+            snapshot,
+            topology,
+            lane,
+            pointCount: lkg.geometry.pointCount,
+            segmentCount: lkg.geometry.segmentCount,
+            sourceBytes: lkg.geometry.sourceBytes,
+            derivedBytes: lkg.geometry.derivedBytes,
+            cache: { hit: true, rebuilds: state.rebuilds, evictions: 0 },
+            drawCount: lkgPlan.drawCount,
+            uploadBytes: 0,
+            lastKnownGood: true,
+            refusal: {
+              code: prepared.error.code,
+              expected: prepared.error.expected,
+              hint: prepared.error.hint,
+              detail: prepared.error.detail,
+              generation: prepared.error.detail.generation,
+              lastKnownGood: true,
+            },
+          }),
+        );
+        return {
+          plan: lkgPlan,
+          vertexBuffer: lkg.resource.vertexBuffer,
+          indexBuffer: lkg.resource.indexBuffer,
+          layoutProjection: this.layoutProjection,
+        };
+      }
+      this.publishRefusal(inspections, snapshot, prepared.error);
+      return undefined;
+    }
+    const plan = createPointsLinesLaneAdapter(lane, backend).createRecordPlan(
+      snapshot,
+      prepared.value.geometry,
+    );
+    const state = preparation.inspect();
+    inspections.set(
+      key,
+      inspectPointsLines({
+        snapshot,
+        topology,
+        lane,
+        pointCount: prepared.value.geometry.pointCount,
+        segmentCount: prepared.value.geometry.segmentCount,
+        sourceBytes: prepared.value.geometry.sourceBytes,
+        derivedBytes: prepared.value.geometry.derivedBytes,
+        cache: {
+          hit: prepared.value.uploadedBytes === 0,
+          rebuilds: state.rebuilds,
+          evictions: 0,
+        },
+        drawCount: plan.drawCount,
+        uploadBytes: prepared.value.uploadedBytes,
+        lastKnownGood: prepared.value.lastKnownGood,
+      }),
+    );
+    return {
+      plan,
+      vertexBuffer: prepared.value.resource.vertexBuffer,
+      indexBuffer: prepared.value.resource.indexBuffer,
+      layoutProjection: this.layoutProjection,
+    };
+  }
+
+  resetForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) preparation.resetForDeviceLoss();
+    this.active.clear();
+  }
+
+  abandonForDeviceLoss(): void {
+    for (const preparation of this.preparations.values()) {
+      preparation.abandonForDeviceLoss();
+    }
+    this.active.clear();
+  }
+
+  dispose(): void {
+    this.resetForDeviceLoss();
+    this.preparations.clear();
+  }
+
+  inspections(): readonly PointsLinesInspection[] {
+    return [...this.active.values()];
+  }
+
+  private backend(runtime: RenderSystemInternals): PointsLinesBackend {
+    switch (runtime.device.caps.backendKind) {
+      case 'wgpu-webgl2':
+        return 'wgpu-webgl2';
+      case 'null':
+        return 'null';
+      default:
+        return 'webgpu';
+    }
+  }
+
+  private publishRefusal(
+    inspections: Map<string, PointsLinesInspection>,
+    snapshot: PointsLinesRetainedSnapshot,
+    error: PointsLinesSourceError,
+  ): void {
+    inspections.set(
+      `${snapshot.worldId}:${snapshot.entityKey}`,
+      inspectPointsLines({
+        snapshot,
+        topology: snapshot.component === 'Points' ? 'point-list' : 'line-list',
+        lane: 'refused',
+        pointCount: 0,
+        segmentCount: 0,
+        sourceBytes: 0,
+        derivedBytes: 0,
+        cache: { hit: false, rebuilds: 0, evictions: 0 },
+        drawCount: 0,
+        uploadBytes: 0,
+        lastKnownGood: false,
+        refusal: {
+          code: error.code,
+          expected: error.expected,
+          hint: error.hint,
+          detail: error.detail,
+          generation: snapshot.meshGeneration,
+          lastKnownGood: false,
+        },
+      }),
+    );
+  }
+
+  private createPreparation(
+    runtime: RenderSystemInternals,
+    geometryKey: string,
+    lane: PointsLinesLane,
+    backend: PointsLinesBackend,
+  ): PointsLinesPreparationAdapter {
+    return createPointsLinesLanePreparationAdapter(lane, backend, {
+      cache: this.cache,
+      adapter: {
+        create: (geometry) => {
+          const vertex = runtime.device.createBuffer({
+            label: `points-lines-vertices:${geometryKey}`,
+            size: Math.max(4, geometry.vertices.byteLength),
+            usage: GPU_BUFFER_USAGE_VERTEX | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!vertex.ok) return err(vertex.error);
+          const index = runtime.device.createBuffer({
+            label: `points-lines-indices:${geometryKey}`,
+            size: Math.max(4, geometry.indices.byteLength),
+            usage: GPU_BUFFER_USAGE_INDEX | GPU_BUFFER_USAGE_COPY_DST,
+            mappedAtCreation: false,
+          });
+          if (!index.ok) {
+            runtime.device.destroyBuffer(vertex.value);
+            return err(index.error);
+          }
+          return ok({ vertexBuffer: vertex.value, indexBuffer: index.value });
+        },
+        upload: (resource, geometry) => {
+          if (geometry.vertices.byteLength > 0) {
+            const vertexWrite = runtime.device.queue.writeBuffer(
+              resource.vertexBuffer,
+              0,
+              geometry.vertices,
+            );
+            if (!vertexWrite.ok) return err(vertexWrite.error);
+          }
+          if (geometry.indices.byteLength > 0) {
+            const indexWrite = runtime.device.queue.writeBuffer(
+              resource.indexBuffer,
+              0,
+              geometry.indices,
+            );
+            if (!indexWrite.ok) return err(indexWrite.error);
+          }
+          return ok(geometry.derivedBytes);
+        },
+        validate: (_resource, geometry) =>
+          geometry.expandedVertexCount > 0 && geometry.expandedIndexCount > 0
+            ? ok(undefined)
+            : err(new Error('Points/Lines expansion contains no drawable triangles')),
+        destroy: (resource) => {
+          runtime.device.destroyBuffer(resource.vertexBuffer);
+          runtime.device.destroyBuffer(resource.indexBuffer);
+        },
+      },
+    });
+  }
+}