@forgeax/engine-render 0.1.4 → 0.1.7

package/src/points-lines/__tests__/lane-structural.integration.test.ts

@@ -0,0 +1,122 @@
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { PointsLinesExpansionCache } from '../expansion-cache';
+import {
+  createPointsLinesLaneAdapter,
+  createPointsLinesLaneContract,
+  createPointsLinesRecordPlan,
+} from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+function mesh(topology: 'point-list' | 'line-list', count: number): MeshAsset {
+  const vertices = new Float32Array(
+    Array.from({ length: count }, (_, index) => [index, index % 2, 0]).flat(),
+  );
+  return {
+    kind: 'mesh',
+    vertices,
+    indices: new Uint16Array(Array.from({ length: count }, (_, index) => index)),
+    attributes: { position: vertices },
+    aabb: new Float32Array([0, 0, 0, count, 1, 0]),
+    submeshes: [
+      { indexOffset: 0, indexCount: count, vertexCount: count, topology, materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: 'points-lines' }],
+  };
+}
+
+function snapshot(component: 'Points' | 'Lines' | undefined) {
+  return createPointsLinesSnapshot({
+    worldId: 1,
+    entityKey: 7,
+    component,
+    meshHandle: 11,
+    meshGeneration: 3,
+    materialHandle: 13,
+    materialGeneration: 2,
+    style:
+      component === 'Points'
+        ? { kind: 'points', sizePx: 16, shape: 'circle' }
+        : component === 'Lines'
+          ? { kind: 'lines', widthPx: 4 }
+          : undefined,
+    layer: 0,
+    visible: true,
+    sourceBounds: new Float32Array([0, 0, 0, 4, 1, 0]),
+    viewport: { width: 640, height: 480, dpr: 2 },
+    projection: new Float32Array(16),
+  });
+}
+
+describe('Points/Lines structural lane contract', () => {
+  it('marks RhiNull structural-only and preserves one shared lane contract', () => {
+    const adapter = createPointsLinesLaneAdapter('direct', 'null');
+    const geometry = new PointsLinesExpansionCache().getOrCreate(
+      snapshot('Points'),
+      mesh('point-list', 4),
+    );
+    const plan = adapter.createRecordPlan(snapshot('Points'), geometry);
+
+    expect(adapter.contract.evidence).toBe('structural-only');
+    expect(adapter.contract.authoring).toBe('shared');
+    expect(plan.drawCount).toBe(1);
+    expect(plan.shadowDrawCount).toBe(0);
+    expect(plan.graph).toEqual({ additionalAttachments: 0, additionalPasses: 0 });
+  });
+
+  it('keeps the component-off path exact-zero', () => {
+    const cache = new PointsLinesExpansionCache();
+    const offPath = snapshot(undefined);
+    const geometry = cache.getOrCreate(offPath, mesh('point-list', 4));
+    const plan = createPointsLinesRecordPlan(
+      offPath,
+      geometry,
+      createPointsLinesLaneContract('direct', 'webgpu'),
+    );
+
+    expect(offPath.dedicatedResourceBytes).toBe(0);
+    expect(geometry.sourceBytes).toBe(0);
+    expect(geometry.derivedBytes).toBe(0);
+    expect(plan.vertexCount).toBe(0);
+    expect(plan.indexCount).toBe(0);
+    expect(plan.drawCount).toBe(0);
+    expect(plan.graph).toEqual({ additionalAttachments: 0, additionalPasses: 0 });
+    expect(plan.shadowDrawCount).toBe(0);
+  });
+
+  it('reuses one expansion for 100 entities and stays within triangle bounds', () => {
+    const cache = new PointsLinesExpansionCache();
+    const authoring = snapshot('Points');
+    const source = mesh('point-list', 4);
+    const first = cache.getOrCreate(authoring, source);
+
+    for (let entity = 0; entity < 100; entity += 1) {
+      expect(cache.getOrCreate(authoring, source)).toBe(first);
+    }
+
+    const plan = createPointsLinesRecordPlan(
+      authoring,
+      first,
+      createPointsLinesLaneContract('clustered', 'webgpu'),
+    );
+    const primitiveCount = first.pointCount + first.segmentCount;
+    expect(cache.size).toBe(1);
+    expect(plan.vertexCount).toBeLessThanOrEqual(4 * primitiveCount);
+    expect(plan.indexCount).toBeLessThanOrEqual(6 * primitiveCount);
+    expect(plan.drawCount).toBe(1);
+  });
+
+  it('records WebGL2 capability provenance without compute storage or indirect', () => {
+    const contract = createPointsLinesLaneContract('cpu-webgl2', 'wgpu-webgl2');
+
+    expect(contract.capabilities).toEqual({ compute: false, storage: false, indirect: false });
+    expect(contract.material).toMatchObject({
+      source: 'MaterialAsset',
+      shadingModel: 'unlit',
+      clusteredLighting: false,
+      lit: false,
+    });
+    expect(contract.graph.additionalAttachments).toBe(0);
+    expect(contract.graph.additionalPasses).toBe(0);
+  });
+});

package/src/points-lines/__tests__/points-lines.bench.ts

@@ -0,0 +1,400 @@
+import { World } from '@forgeax/engine-ecs';
+import { buildMeshAttributeMapForUvSets } from '@forgeax/engine-geometry';
+import { buildProfileModel, createProfiler } from '@forgeax/engine-profiler';
+import {
+  Camera,
+  Lines,
+  Materials,
+  MeshFilter,
+  MeshRenderer,
+  PointShapeValue,
+  Points,
+  perspective,
+} from '@forgeax/engine-render';
+import type { RhiRenderPassEncoder } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { Transform } from '@forgeax/engine-scene';
+import { err, type MeshAsset, ok } from '@forgeax/engine-types';
+import { bench, describe } from 'vitest';
+import { createRenderer as constructRenderer } from '../../assembly/factory';
+import { recordPointsLinesDraw } from '../../record/main-pass-geometry';
+import { admitPointsLines } from '../admission';
+import { PointsLinesExpansionCache } from '../expansion-cache';
+import { type PointsLinesGpuResourceAdapter, PointsLinesPreparation } from '../prepare';
+import { createPointsLinesLaneContract, createPointsLinesRecordPlan } from '../record';
+import { createPointsLinesSnapshot } from '../snapshot';
+
+const POINT_COUNT = 10_000;
+const SEGMENT_COUNT = 10_000;
+const SAMPLE_COUNT = 30;
+const BENCH_OPTIONS = { iterations: SAMPLE_COUNT } as const;
+
+function buildMesh(topology: 'point-list' | 'line-list'): MeshAsset {
+  const vertexCount = topology === 'point-list' ? POINT_COUNT : SEGMENT_COUNT * 2;
+  const vertices = new Float32Array(vertexCount * 3);
+  const attributes = new Float32Array(vertices);
+  for (let index = 0; index < vertexCount; index += 1) {
+    const offset = index * 3;
+    vertices[offset] = (index % 100) / 50 - 1;
+    vertices[offset + 1] = Math.floor(index / 100) / 100 - 1;
+    vertices[offset + 2] = 0;
+  }
+  const indices = topology === 'line-list' ? new Uint32Array(vertexCount) : undefined;
+  if (indices !== undefined) {
+    for (let index = 0; index < indices.length; index += 1) indices[index] = index;
+  }
+  return {
+    kind: 'mesh',
+    vertices,
+    ...(indices === undefined ? {} : { indices }),
+    attributes: { ...buildMeshAttributeMapForUvSets(1), position: attributes },
+    aabb: new Float32Array([-1, -1, 0, 1, 1, 0]),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: topology === 'line-list' ? vertexCount : 0,
+        vertexCount,
+        topology,
+        materialSlot: 0,
+      },
+    ],
+    materialSlots: [{ slotName: 'points-lines-bench' }],
+  };
+}
+
+function snapshot(component: 'Points' | 'Lines') {
+  return createPointsLinesSnapshot({
+    worldId: 0,
+    entityKey: component === 'Points' ? 10 : 11,
+    component,
+    meshHandle: 99,
+    meshGeneration: 1,
+    materialHandle: 100,
+    materialGeneration: 1,
+    style:
+      component === 'Points'
+        ? { kind: 'points', sizePx: 8, shape: 'circle' }
+        : { kind: 'lines', widthPx: 3 },
+    layer: 0,
+    visible: true,
+    sourceBounds: [-1, -1, 0, 1, 1, 0],
+    viewport: { width: 1280, height: 720, dpr: 1 },
+    projection: new Float32Array(16),
+  });
+}
+
+const MATERIAL = Materials.unlit([0.1, 0.9, 1, 1], { castShadow: false });
+
+function manifestUrl(): string {
+  return `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+}
+
+function buildDirectMesh(): MeshAsset {
+  const vertices = new Float32Array(POINT_COUNT * 3);
+  for (let index = 0; index < POINT_COUNT; index += 1) {
+    const offset = index * 3;
+    vertices[offset] = (index % 100) / 50 - 1;
+    vertices[offset + 1] = Math.floor(index / 100) / 100 - 1;
+  }
+  const indices = new Uint32Array(Math.floor(POINT_COUNT / 3) * 3);
+  for (let index = 0; index < indices.length; index += 1) indices[index] = index;
+  return {
+    kind: 'mesh',
+    vertices,
+    indices,
+    attributes: { ...buildMeshAttributeMapForUvSets(1), position: new Float32Array(vertices) },
+    aabb: new Float32Array([-1, -1, 0, 1, 1, 0]),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indices.length,
+        vertexCount: POINT_COUNT,
+        topology: 'triangle-list',
+        materialSlot: 0,
+      },
+    ],
+    materialSlots: [{ slotName: 'points-lines-direct-baseline' }],
+  };
+}
+
+type RealRoute = {
+  readonly renderer: Awaited<ReturnType<typeof constructRenderer>>;
+  readonly profiler: ReturnType<typeof createProfiler>;
+  readonly pointsLines: {
+    readonly world: World;
+    readonly lease: import('../../render-contract').RenderWorldLease;
+  };
+  readonly direct: {
+    readonly world: World;
+    readonly lease: import('../../render-contract').RenderWorldLease;
+  };
+};
+
+function makeRealScene(
+  renderer: RealRoute['renderer'],
+  meshes: { readonly points: MeshAsset; readonly lines: MeshAsset },
+  component: 'points-lines' | 'direct',
+): RealRoute['pointsLines'] {
+  const world = new World();
+  const materialHandle = world.allocSharedRef('MaterialAsset', MATERIAL);
+  if (component === 'points-lines') {
+    const pointMeshHandle = world.allocSharedRef('MeshAsset', meshes.points);
+    const lineMeshHandle = world.allocSharedRef('MeshAsset', meshes.lines);
+    world
+      .spawn(
+        {
+          component: Transform,
+          data: { pos: [-0.5, 0, -2], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+        },
+        { component: MeshFilter, data: { assetHandle: pointMeshHandle } },
+        { component: MeshRenderer, data: { materials: [materialHandle] } },
+        { component: Points, data: { sizePx: 8, shape: PointShapeValue.circle } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: { pos: [0.5, 0, -2], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+        { component: MeshFilter, data: { assetHandle: lineMeshHandle } },
+        { component: MeshRenderer, data: { materials: [materialHandle] } },
+        { component: Lines, data: { widthPx: 3 } },
+      )
+      .unwrap();
+  } else {
+    const meshHandle = world.allocSharedRef('MeshAsset', meshes.points);
+    for (const x of [-0.5, 0.5]) {
+      world
+        .spawn(
+          { component: Transform, data: { pos: [x, 0, -2], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+          { component: MeshFilter, data: { assetHandle: meshHandle } },
+          { component: MeshRenderer, data: { materials: [materialHandle] } },
+        )
+        .unwrap();
+    }
+  }
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 3], quat: [0, 0, 0, 1], scale: [1, 1, 1] } },
+      { component: Camera, data: { ...perspective({ fov: Math.PI / 4, aspect: 16 / 9 }) } },
+    )
+    .unwrap();
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update().unwrap();
+  return { world, lease: attached.value };
+}
+
+async function createRealRoute(): Promise<RealRoute> {
+  const profiler = createProfiler();
+  const renderer = await constructRenderer(
+    { getContext: () => null },
+    { rhi, profiler },
+    { shaderManifestUrl: manifestUrl() },
+  );
+  return {
+    renderer,
+    profiler,
+    pointsLines: makeRealScene(renderer, { points: POINT_MESH, lines: LINE_MESH }, 'points-lines'),
+    direct: makeRealScene(
+      renderer,
+      { points: buildDirectMesh(), lines: buildDirectMesh() },
+      'direct',
+    ),
+  };
+}
+
+function drawRealFrame(route: RealRoute, scene: RealRoute['pointsLines']): void {
+  const drawn = route.renderer.draw({
+    leases: [scene.lease],
+    camera: { lease: scene.lease },
+    environment: { lease: scene.lease },
+  });
+  if (!drawn.ok) throw drawn.error;
+}
+
+async function captureProfile(route: RealRoute, scene: RealRoute['pointsLines']) {
+  const capture = route.profiler.startCapture({
+    frameLimit: 1,
+    eventLimit: 10_000,
+    detail: 'nested',
+  });
+  if (!capture.ok) throw capture.error;
+  drawRealFrame(route, scene);
+  const finished = capture.value.finish();
+  if (!finished.ok) throw finished.error;
+  const model = buildProfileModel(finished.value);
+  if (!model.ok) throw model.error;
+  return model.value;
+}
+
+type BenchResource = { readonly geometryKey: string; readonly bytes: number };
+
+const RESOURCE_ADAPTER: PointsLinesGpuResourceAdapter<BenchResource> = {
+  create: (geometry) => ok({ geometryKey: geometry.key, bytes: 0 }),
+  upload: (_resource, geometry) => ok(geometry.derivedBytes),
+  validate: (_resource, geometry) =>
+    geometry.expandedVertexCount > 0 && geometry.expandedIndexCount > 0
+      ? ok(undefined)
+      : err(new Error('benchmark expansion is not drawable')),
+  destroy: () => undefined,
+};
+
+function prepareWorkload(
+  component: 'Points' | 'Lines',
+  mesh: MeshAsset,
+  cache: PointsLinesExpansionCache,
+  preparation = new PointsLinesPreparation({ cache, adapter: RESOURCE_ADAPTER }),
+) {
+  const authored =
+    component === 'Points' ? { points: { sizePx: 8, shape: 1 } } : { lines: { widthPx: 3 } };
+  const admission = admitPointsLines({
+    entity: component === 'Points' ? 10 : 11,
+    mesh,
+    material: MATERIAL,
+    ...authored,
+  });
+  if (!admission.ok) throw admission.error;
+  const retained = snapshot(component);
+  const prepared = preparation.prepare(retained, mesh);
+  if (!prepared.ok) throw prepared.error;
+  const plan = createPointsLinesRecordPlan(
+    retained,
+    prepared.value.geometry,
+    createPointsLinesLaneContract('direct', 'webgpu'),
+  );
+  const draws: string[] = [];
+  const pass = {
+    draw: () => draws.push('draw'),
+    drawIndexed: () => draws.push('drawIndexed'),
+  } as unknown as RhiRenderPassEncoder;
+  recordPointsLinesDraw(pass, plan);
+  if (draws.length !== 1) throw new Error(`${component} record path emitted ${draws.length} draws`);
+  return { geometry: prepared.value.geometry, plan, preparation, draws };
+}
+
+function preparePair(
+  cache: PointsLinesExpansionCache,
+  pointMesh: MeshAsset,
+  lineMesh: MeshAsset,
+  preparations?: {
+    points?: PointsLinesPreparation<BenchResource>;
+    lines?: PointsLinesPreparation<BenchResource>;
+  },
+) {
+  const points = prepareWorkload('Points', pointMesh, cache, preparations?.points);
+  const lines = prepareWorkload('Lines', lineMesh, cache, preparations?.lines);
+  return { points, lines };
+}
+
+function validateWorkload(pointMesh: MeshAsset, lineMesh: MeshAsset): void {
+  const cache = new PointsLinesExpansionCache();
+  const pair = preparePair(cache, pointMesh, lineMesh);
+  const primitiveCount = POINT_COUNT + SEGMENT_COUNT;
+  if (pair.points.geometry === pair.lines.geometry) {
+    throw new Error('Points and Lines must not share an expansion cache entry');
+  }
+  if (pair.points.geometry.expandedVertexCount !== POINT_COUNT * 4) {
+    throw new Error('Points expansion vertex count mismatch');
+  }
+  if (pair.lines.geometry.expandedIndexCount !== SEGMENT_COUNT * 6) {
+    throw new Error('Lines expansion index count mismatch');
+  }
+  if (pair.points.plan.drawCount !== 1 || pair.lines.plan.drawCount !== 1) {
+    throw new Error('Visible Points and Lines must each record one draw');
+  }
+  if (
+    pair.points.geometry.expandedVertexCount + pair.lines.geometry.expandedVertexCount >
+    primitiveCount * 4
+  ) {
+    throw new Error('Expanded vertex bound exceeded');
+  }
+  if (
+    pair.points.geometry.expandedIndexCount + pair.lines.geometry.expandedIndexCount >
+    primitiveCount * 6
+  ) {
+    throw new Error('Expanded index bound exceeded');
+  }
+  const offPath = cache.getOrCreate(
+    { ...snapshot('Points'), component: undefined, style: undefined },
+    pointMesh,
+  );
+  if (offPath.derivedBytes !== 0 || offPath.expandedVertexCount !== 0) {
+    throw new Error('Off-path geometry must remain exact-zero');
+  }
+  if (offPath.derivedBytes !== 0) throw new Error('off-path derived bytes changed');
+}
+
+const POINT_MESH = buildMesh('point-list');
+const LINE_MESH = buildMesh('line-list');
+validateWorkload(POINT_MESH, LINE_MESH);
+const REAL_ROUTE = await createRealRoute();
+const REAL_PROFILE = await captureProfile(REAL_ROUTE, REAL_ROUTE.pointsLines);
+const DIRECT_PROFILE = await captureProfile(REAL_ROUTE, REAL_ROUTE.direct);
+
+function phaseDeltas(): Readonly<Record<string, number>> {
+  const direct = new Map(
+    DIRECT_PROFILE?.phases.map((phase) => [
+      `${phase.source}:${phase.phase}`,
+      phase.p95DurationMicros ?? 0,
+    ]) ?? [],
+  );
+  return Object.fromEntries(
+    REAL_PROFILE?.phases.map((phase) => {
+      const key = `${phase.source}:${phase.phase}`;
+      return [key, (phase.p95DurationMicros ?? 0) - (direct.get(key) ?? 0)];
+    }) ?? [],
+  );
+}
+
+// biome-ignore lint/suspicious/noConsole: benchmark emits machine-readable evidence
+console.info(
+  JSON.stringify({
+    workload: { points: POINT_COUNT, segments: SEGMENT_COUNT, samples: SAMPLE_COUNT },
+    route: 'Renderer.extract-prepare-record',
+    baseline: 'same-Renderer.direct-mesh',
+    phases: phaseDeltas(),
+    gpuTiming: {
+      status: 'blocked',
+      reason: 'no adapter-qualified timestamp owner exists for this RhiNull runner',
+    },
+  }),
+);
+let sink = 0;
+
+describe('Points/Lines 10k + 10k benchmark', () => {
+  bench(
+    'same-Renderer direct baseline',
+    () => {
+      drawRealFrame(REAL_ROUTE, REAL_ROUTE.direct);
+      sink ^= REAL_ROUTE.renderer.inspect().frame.frameId;
+    },
+    BENCH_OPTIONS,
+  );
+
+  bench(
+    'Renderer extract prepare record',
+    () => {
+      drawRealFrame(REAL_ROUTE, REAL_ROUTE.pointsLines);
+      sink ^= REAL_ROUTE.renderer.inspect().renderScene.pointsLines?.length ?? 0;
+    },
+    BENCH_OPTIONS,
+  );
+
+  bench(
+    'Renderer warm extract prepare record',
+    () => {
+      drawRealFrame(REAL_ROUTE, REAL_ROUTE.pointsLines);
+      sink ^= REAL_ROUTE.renderer.inspect().renderScene.pointsLines?.length ?? 0;
+    },
+    BENCH_OPTIONS,
+  );
+
+  bench(
+    'Renderer inspection after record',
+    () => {
+      sink ^= REAL_ROUTE.renderer.inspect().renderScene.pointsLines?.length ?? 0;
+    },
+    BENCH_OPTIONS,
+  );
+
+  void sink;
+});

package/src/points-lines/__tests__/raster-lane.integration.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import { createPointsLinesLaneContract, type PointsLinesLane } from '../record';
+
+const lanes: readonly PointsLinesLane[] = ['direct', 'clustered', 'cpu-webgl2'];
+
+describe('Points/Lines raster lane integration contract', () => {
+  it.each(lanes)('%s consumes one unlit material and the existing graph', (lane) => {
+    const contract = createPointsLinesLaneContract(lane, 'webgpu');
+
+    expect(contract.lane).toBe(lane);
+    expect(contract.material.shadingModel).toBe('unlit');
+    expect(contract.material.source).toBe('MaterialAsset');
+    expect(contract.graph.additionalAttachments).toBe(0);
+    expect(contract.graph.additionalPasses).toBe(0);
+    expect(contract.shadowDrawCount).toBe(0);
+  });
+
+  it('keeps clustered points and lines on the unlit route', () => {
+    const contract = createPointsLinesLaneContract('clustered', 'webgpu');
+
+    expect(contract.material.shadingModel).toBe('unlit');
+    expect(contract.material.clusteredLighting).toBe(false);
+    expect(contract.material.lit).toBe(false);
+  });
+
+  it('does not request compute, storage, or indirect features on CPU-WebGL2', () => {
+    const contract = createPointsLinesLaneContract('cpu-webgl2', 'wgpu-webgl2');
+
+    expect(contract.capabilities.compute).toBe(false);
+    expect(contract.capabilities.storage).toBe(false);
+    expect(contract.capabilities.indirect).toBe(false);
+    expect(contract.graph.additionalAttachments).toBe(0);
+    expect(contract.graph.additionalPasses).toBe(0);
+  });
+
+  it('labels RhiNull as structural-only and keeps the same authoring contract', () => {
+    const contract = createPointsLinesLaneContract('direct', 'null');
+
+    expect(contract.evidence).toBe('structural-only');
+    expect(contract.authoring).toBe('shared');
+    expect(contract.graph.additionalAttachments).toBe(0);
+    expect(contract.graph.additionalPasses).toBe(0);
+  });
+});

package/src/points-lines/__tests__/snapshot.unit.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+import {
+  comparePointsLinesSnapshots,
+  createPointsLinesSnapshot,
+  type PointsLinesRetainedSnapshot,
+} from '../snapshot';
+
+function snapshotInput(): Parameters<typeof createPointsLinesSnapshot>[0] {
+  return {
+    worldId: 3,
+    entityKey: 17,
+    component: 'Points',
+    meshHandle: 11,
+    meshGeneration: 4,
+    materialHandle: 23,
+    materialGeneration: 8,
+    style: { kind: 'points', sizePx: 6, shape: 'circle' },
+    layer: 12,
+    sortKey: -2,
+    visible: true,
+    sourceBounds: new Float32Array([-1, -2, -3, 1, 2, 3]),
+    viewport: { width: 800, height: 600, dpr: 2 },
+    projection: new Float32Array(16),
+  };
+}
+
+describe('Points/Lines retained snapshot', () => {
+  it('detaches ECS identity, owner generations, style, and view facts', () => {
+    const source = snapshotInput();
+    const snapshot = createPointsLinesSnapshot(source);
+
+    expect(snapshot).toEqual<PointsLinesRetainedSnapshot>({
+      worldId: 3,
+      entityKey: 17,
+      component: 'Points',
+      meshHandle: 11,
+      meshGeneration: 4,
+      materialHandle: 23,
+      materialGeneration: 8,
+      style: { kind: 'points', sizePx: 6, shape: 'circle' },
+      layer: 12,
+      sortKey: -2,
+      visible: true,
+      sourceBounds: new Float32Array([-1, -2, -3, 1, 2, 3]),
+      viewport: { width: 800, height: 600, dpr: 2 },
+      projection: new Float32Array(16),
+    });
+    expect(snapshot).not.toHaveProperty('world');
+    expect(snapshot.sourceBounds).not.toBe(source.sourceBounds);
+    expect(snapshot.projection).not.toBe(source.projection);
+  });
+
+  it('classifies only owner generations and style as geometry invalidation', () => {
+    const base = createPointsLinesSnapshot(snapshotInput());
+
+    expect(
+      comparePointsLinesSnapshots(
+        base,
+        createPointsLinesSnapshot({ ...snapshotInput(), meshGeneration: 5 }),
+      ),
+    ).toBe('mesh');
+    expect(
+      comparePointsLinesSnapshots(
+        base,
+        createPointsLinesSnapshot({ ...snapshotInput(), materialGeneration: 9 }),
+      ),
+    ).toBe('material');
+    expect(
+      comparePointsLinesSnapshots(
+        base,
+        createPointsLinesSnapshot({
+          ...snapshotInput(),
+          style: { kind: 'points', sizePx: 8, shape: 'square' },
+        }),
+      ),
+    ).toBe('style');
+    expect(
+      comparePointsLinesSnapshots(
+        base,
+        createPointsLinesSnapshot({
+          ...snapshotInput(),
+          viewport: { width: 1600, height: 1200, dpr: 2 },
+        }),
+      ),
+    ).toBe('view');
+    expect(
+      comparePointsLinesSnapshots(base, createPointsLinesSnapshot({ ...snapshotInput() })),
+    ).toBe('none');
+    expect(base).not.toHaveProperty('derived');
+  });
+
+  it('records a dedicated-resource zero when the style component is absent', () => {
+    const snapshot = createPointsLinesSnapshot({
+      ...snapshotInput(),
+      component: undefined,
+      style: undefined,
+    });
+
+    expect(snapshot).toMatchObject({ component: undefined, dedicatedResourceBytes: 0 });
+  });
+});