@ifc-lite/viewer 1.25.2 → 1.27.0

package/src/components/viewer/lists/list-table-utils.ts

@@ -0,0 +1,123 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Pure helpers for the Lists results table — value formatting, comparison,
+ * numeric-column detection, content-aware column widths, and the grouping /
+ * aggregation that powers the in-table (settings-free) grouped view.
+ */
+
+import type { CellValue, ColumnDefinition, ListRow, ListGrouping } from '@ifc-lite/lists';
+
+export function formatCellValue(value: CellValue): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'boolean') return value ? 'Yes' : 'No';
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) return value.toLocaleString();
+    return value.toFixed(4).replace(/\.?0+$/, '');
+  }
+  return String(value);
+}
+
+export function compareCells(a: CellValue, b: CellValue): number {
+  if (a === null && b === null) return 0;
+  if (a === null) return -1;
+  if (b === null) return 1;
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return String(a).localeCompare(String(b));
+}
+
+/** A column is numeric (summable) when every sampled non-empty value is a
+ *  finite number and at least one such value exists. */
+export function detectNumericColumns(columns: ColumnDefinition[], rows: ListRow[]): boolean[] {
+  const sample = rows.slice(0, 120);
+  return columns.map((_, i) => {
+    let sawNumber = false;
+    for (const r of sample) {
+      const v = r.values[i];
+      if (v === null || v === undefined || v === '') continue;
+      if (typeof v === 'number' && Number.isFinite(v)) { sawNumber = true; continue; }
+      return false;
+    }
+    return sawNumber;
+  });
+}
+
+/** Content-aware default width: fits the header + the widest sampled value
+ *  (≈7px/char), clamped to a readable range. */
+export function autoColumnWidth(label: string, rows: ListRow[], colIdx: number): number {
+  let maxLen = label.length;
+  const sample = rows.slice(0, 200);
+  for (const r of sample) {
+    const v = r.values[colIdx];
+    if (v === null || v === undefined) continue;
+    const len = (typeof v === 'number' ? formatCellValue(v) : String(v)).length;
+    if (len > maxLen) maxLen = len;
+  }
+  return Math.max(80, Math.min(460, maxLen * 7 + 34));
+}
+
+export type DisplayItem =
+  | { kind: 'group'; key: string; label: string; count: number; sums: Record<string, number> }
+  | { kind: 'row'; row: ListRow };
+
+export interface Totals { count: number; sums: Record<string, number> }
+export interface GroupedView { items: DisplayItem[]; groupCount: number; totals: Totals }
+
+function sumIndices(columns: ColumnDefinition[], sumColumnIds: string[]) {
+  return sumColumnIds
+    .map((id) => ({ id, idx: columns.findIndex((c) => c.id === id) }))
+    .filter((s) => s.idx >= 0);
+}
+
+/** Bucket already-filtered/sorted rows by the group-by column, accumulate
+ *  per-group + grand count/sums, and flatten into a virtualizable list
+ *  (group header followed by its rows when the group is expanded). */
+export function buildGroupedView(
+  rows: ListRow[],
+  columns: ColumnDefinition[],
+  grouping: ListGrouping,
+  expanded: Set<string>,
+): GroupedView {
+  const groupIdx = columns.findIndex((c) => c.id === grouping.columnId);
+  const sums = sumIndices(columns, grouping.sumColumnIds);
+  const zero = (): Record<string, number> => Object.fromEntries(sums.map((s) => [s.id, 0]));
+
+  const totals: Totals = { count: rows.length, sums: zero() };
+  const byKey = new Map<string, { key: string; label: string; count: number; sums: Record<string, number>; rows: ListRow[] }>();
+
+  for (const row of rows) {
+    const raw = groupIdx >= 0 ? row.values[groupIdx] : null;
+    const label = raw === null || raw === undefined || raw === '' ? '(none)' : formatCellValue(raw);
+    let g = byKey.get(label);
+    if (!g) { g = { key: label, label, count: 0, sums: zero(), rows: [] }; byKey.set(label, g); }
+    g.count++;
+    g.rows.push(row);
+    for (const s of sums) {
+      const v = row.values[s.idx];
+      if (typeof v === 'number' && Number.isFinite(v)) { g.sums[s.id] += v; totals.sums[s.id] += v; }
+    }
+  }
+
+  const groups = Array.from(byKey.values()).sort((a, b) => b.count - a.count || a.label.localeCompare(b.label));
+  const items: DisplayItem[] = [];
+  for (const g of groups) {
+    items.push({ kind: 'group', key: g.key, label: g.label, count: g.count, sums: g.sums });
+    if (expanded.has(g.key)) for (const r of g.rows) items.push({ kind: 'row', row: r });
+  }
+  return { items, groupCount: groups.length, totals };
+}
+
+/** Grand totals for the flat (ungrouped) view when sum columns are active. */
+export function flatTotals(rows: ListRow[], columns: ColumnDefinition[], sumColumnIds: string[]): Totals {
+  const sums = sumIndices(columns, sumColumnIds);
+  const acc: Record<string, number> = Object.fromEntries(sums.map((s) => [s.id, 0]));
+  for (const r of rows) {
+    for (const s of sums) {
+      const v = r.values[s.idx];
+      if (typeof v === 'number' && Number.isFinite(v)) acc[s.id] += v;
+    }
+  }
+  return { count: rows.length, sums: acc };
+}

package/src/components/viewer/useGeometryStreaming.ts

@@ -46,6 +46,10 @@ export interface UseGeometryStreamingParams {
   geometryContentVersion?: number;
   coordinateInfo?: CoordinateInfo;
   isStreaming: boolean;
+  /** Number of loaded models. When this increases (a model was added to the
+   *  federation) the camera must refit to the new combined bounds — otherwise
+   *  it stays framed on the first model and the newly-added one is off-screen. */
+  modelCount?: number;
   geometryBoundsRef: MutableRefObject<{ min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number } }>;
   pendingMeshColorUpdates: Map<number, [number, number, number, number]> | null;
   pendingColorUpdates: Map<number, [number, number, number, number]> | null;
@@ -95,6 +99,7 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     geometryContentVersion,
     coordinateInfo,
     isStreaming,
+    modelCount = 0,
     geometryBoundsRef,
     pendingMeshColorUpdates,
     pendingColorUpdates,
@@ -122,6 +127,7 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
   const lastFitPolicyKindRef = useRef<'compact' | 'linear' | null>(null);
   const prevIsStreamingRef = useRef(isStreaming);
   const lastContentVersionRef = useRef(geometryContentVersion ?? 0);
+  const prevModelCountRef = useRef(modelCount);
   const queuePumpTimerRef = useRef<ReturnType<typeof globalThis.setTimeout> | null>(null);
 
   // Only activate the timer-based queue pump when the tab is background-throttled
@@ -200,6 +206,20 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
       }
     }
 
+    // A model was added to the federation — refit the camera to the new
+    // combined bounds. Without this, `cameraFittedRef` stays true from the
+    // first model's fit, so the newly-added model renders off-screen and only
+    // its 2D grid overlay shows. Refit only on an INCREASE (a model added),
+    // and never mid-stream (the streaming first-fit + finalize refit handle
+    // the active model). The combined bounds come from the merged
+    // coordinateInfo (union of all visible models).
+    if (modelCount > prevModelCountRef.current && !isStreaming) {
+      traceGeometrySync(`model added (${prevModelCountRef.current}→${modelCount}) — refitting camera to combined bounds`);
+      cameraFittedRef.current = false;
+      finalBoundsRefittedRef.current = false;
+    }
+    prevModelCountRef.current = modelCount;
+
     // Read AFTER the optional reset above so the classification below reflects
     // the post-reset state (otherwise an in-place update gets misclassified as
     // "no change" and returns early at currentLength === lastLength).
@@ -400,7 +420,7 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     }
 
     renderer.requestRender();
-  }, [geometry, geometryVersion, geometryContentVersion, coordinateInfo, isInitialized, isStreaming]);
+  }, [geometry, geometryVersion, geometryContentVersion, coordinateInfo, isInitialized, isStreaming, modelCount]);
 
   useEffect(() => {
     return () => {

package/src/generated/mcp-catalog.json

@@ -25,6 +25,10 @@
     { "name": "geometry_volume",     "category": "Geometry",   "scope": "read",   "description": "Net/gross volume in m³ for a single entity or a type aggregate.", "inputSchema": { "type": "object", "required": ["global_id"] } },
     { "name": "geometry_area",       "category": "Geometry",   "scope": "read",   "description": "Surface area for an entity (front/side/footprint depending on what the IFC carries).", "inputSchema": { "type": "object", "required": ["global_id"] } },
 
+    { "name": "clash_check",         "category": "Clash",      "scope": "read",   "description": "Find clashes in a single model — the DEFAULT for any 'find/run clashes' request. Omit BOTH a and b to check every element vs every other (all clashes in the model). Give a TYPE selector for a to self-clash within a group, or both a and b for a pairwise check (a=\"IfcDuct*\", b=\"IfcWall*\"). Meshes the model in-browser; returns a summary plus the worst clashes by penetration depth.", "inputSchema": { "type": "object", "properties": { "a": { "type": "string", "description": "Type selector for set A. Defaults to \"*\" (all elements). e.g. \"IfcDuct*|IfcPipe*\", \"!IfcSpace\"." }, "b": { "type": "string", "description": "Type selector for set B. OMIT for a self-clash within A (every element vs every other in the group)." }, "mode": { "type": "string", "enum": ["hard", "clearance"] }, "tolerance": { "type": "number", "description": "Touching band (m). Defaults to the engine tolerance." }, "clearance": { "type": "number", "description": "Required gap (m) for mode=\"clearance\"." }, "model_id": { "type": "string", "description": "Optional; defaults to the only loaded model." } } } },
+    { "name": "clash_matrix",        "category": "Clash",      "scope": "read",   "description": "Run the standard discipline clash matrix (MEP×STR, HVAC×ARCH, ...) — INTER-discipline pairs ONLY. Returns NOTHING on a single-discipline or architectural model (no cross-discipline pairs exist to test). For a general 'find all clashes' request use clash_check instead; use this only when the user explicitly asks for the discipline matrix. Returns per-rule and per-severity breakdowns plus a sample of the worst clashes.", "inputSchema": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["hard", "clearance"] }, "clearance": { "type": "number", "description": "Required gap (m) applied to every matrix rule when mode=\"clearance\". Without it a clearance matrix reports nothing." }, "model_id": { "type": "string", "description": "Optional; defaults to the only loaded model." } } } },
+    { "name": "clash_bcf_export",    "category": "Clash",      "scope": "export", "description": "Turn the last clash run (clash_check / clash_matrix) into a rich .bcfzip: one BCF topic per clash group, each with a framed 3D viewpoint, the clashing elements as components, and severity/status/distance metadata. Runs a default all-vs-all clash_check first if you haven't clashed yet. Use THIS for 'create/export BCF from clashes' — not bcf_topic_create. (Snapshots are omitted: the inline viewer can't render frames headlessly; BCF viewpoints are valid without an image.)", "inputSchema": { "type": "object", "properties": { "group_by": { "type": "string", "enum": ["cluster", "rule", "typePair", "element"], "description": "How clashes collapse into topics. Default \"cluster\" (spatially-near clashes merge into one topic)." }, "cluster_epsilon": { "type": "number", "description": "Cluster radius (m) for group_by=\"cluster\". Default 1.5." }, "status": { "type": "string", "description": "BCF topic status, e.g. \"Open\"." }, "max_topics": { "type": "integer", "description": "Cap the number of topics. Default 1000." }, "file_path": { "type": "string", "description": "Output .bcfzip name." } } } },
+
     { "name": "model_audit",         "category": "Validation", "scope": "read",   "description": "Out-of-the-box health score + a list of issues (missing GlobalIds, broken refs, orphan entities).", "inputSchema": { "type": "object" } },
     { "name": "ids_validate",        "category": "Validation", "scope": "read",   "description": "Run a buildingSMART IDS spec against the loaded model. Per-spec pass/fail with offending entities.", "inputSchema": { "type": "object", "required": ["ids_path"], "properties": { "ids_path": { "type": "string" } } } },
     { "name": "ids_explain",         "category": "Validation", "scope": "read",   "description": "Parse + summarize an IDS file in plain language — what each spec asks for, in what order.", "inputSchema": { "type": "object", "required": ["ids_path"] } },

package/src/hooks/ingest/streamCleanup.test.ts

@@ -0,0 +1,41 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { boundedIteratorReturn } from './streamCleanup.js';
+
+describe('boundedIteratorReturn', () => {
+  it('resolves promptly even when return() never settles (the stalled-worker case)', async () => {
+    // Mirrors a geometry generator parked on an unresolved await: its return()
+    // can never settle, so an unbounded await would re-wedge the caller.
+    const iterator = { return: () => new Promise<never>(() => { /* never settles */ }) };
+    const start = Date.now();
+    await boundedIteratorReturn(iterator, 50);
+    const elapsed = Date.now() - start;
+    assert.ok(elapsed < 1000, `expected bounded (<1000ms), took ${elapsed}ms`);
+  });
+
+  it('awaits a fast return() to completion (lets the generator finally run)', async () => {
+    let returned = false;
+    const iterator = {
+      return: async () => {
+        returned = true;
+        return { done: true, value: undefined };
+      },
+    };
+    await boundedIteratorReturn(iterator, 1000);
+    assert.strictEqual(returned, true);
+  });
+
+  it('swallows a rejecting return() without throwing', async () => {
+    const iterator = { return: () => Promise.reject(new Error('teardown blew up')) };
+    await assert.doesNotReject(() => boundedIteratorReturn(iterator, 1000));
+  });
+
+  it('is a no-op when the iterator has no return()', async () => {
+    await assert.doesNotReject(() => boundedIteratorReturn({}, 1000));
+  });
+});

package/src/hooks/ingest/streamCleanup.ts

@@ -0,0 +1,45 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/** How long to wait for an abandoned geometry iterator to shut down before
+ *  giving up on it. Generous enough for a healthy generator to run its
+ *  `finally` (freeing WASM handles, terminating workers), short enough that a
+ *  wedged one never holds the caller hostage. */
+export const GEOMETRY_ITERATOR_CLEANUP_MS = 2000;
+
+interface ClosableAsyncIterator {
+  return?: (value?: unknown) => Promise<unknown> | unknown;
+}
+
+/**
+ * Abandon an async iterator without letting its shutdown wedge the caller.
+ *
+ * `AsyncIterator.return()` cannot interrupt a generator parked on an unresolved
+ * `await` — e.g. the geometry drain loop suspended waiting on a worker that
+ * failed to instantiate ("Worker from an empty source") and therefore never
+ * resolves the promise. Awaiting `return()` unbounded would re-block on the
+ * exact stall the stream watchdog just escaped, swallowing the timeout error so
+ * the load hangs in cleanup instead of surfacing a recoverable failure. Racing
+ * it against a deadline guarantees the caller always proceeds; a healthy
+ * generator still resolves well within the deadline so its `finally` runs.
+ */
+export async function boundedIteratorReturn(
+  iterator: ClosableAsyncIterator,
+  cleanupMs: number = GEOMETRY_ITERATOR_CLEANUP_MS,
+): Promise<void> {
+  if (typeof iterator.return !== 'function') return;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  try {
+    await Promise.race([
+      Promise.resolve(iterator.return(undefined)).catch(() => {
+        /* cleanup — safe to ignore */
+      }),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, cleanupMs);
+      }),
+    ]);
+  } finally {
+    if (timer !== null) clearTimeout(timer);
+  }
+}

package/src/hooks/ingest/viewerModelIngest.ts

@@ -9,6 +9,7 @@ import { loadGLBToMeshData } from '@ifc-lite/cache';
 import type { SchemaVersion } from '../../store/types.js';
 import { calculateMeshBounds, calculateStoreyHeights, createCoordinateInfo, normalizeColor } from '../../utils/localParsingUtils.js';
 import { resolveDataStoreOrAbort } from './resolveDataStoreOrAbort.js';
+import { watchedGeometryStream } from './watchedGeometryStream.js';
 
 type RgbaColor = [number, number, number, number];
 
@@ -264,7 +265,7 @@ export async function parseStepBufferViewerModel(options: StepBufferIngestOption
       });
 
   const geometryView = sharedSource ? new Uint8Array(sharedSource) : new Uint8Array(options.buffer);
-  for await (const event of geometryProcessor.processAdaptive(geometryView, {
+  const geometryStream = geometryProcessor.processAdaptive(geometryView, {
     sizeThreshold: 2 * 1024 * 1024,
     batchSize: options.getDynamicBatchSize(options.fileSizeMB),
     sharedRtcOffset: options.sharedRtcOffset,
@@ -272,48 +273,69 @@ export async function parseStepBufferViewerModel(options: StepBufferIngestOption
     onEntityIndex: (ids, starts, lengths) => {
       workerParser?.setEntityIndex(ids, starts, lengths);
     },
-  })) {
-    if (options.shouldAbort?.()) {
-      break;
-    }
-    switch (event.type) {
-      case 'start':
-        estimatedTotal = event.totalEstimate;
-        break;
-      case 'colorUpdate':
-        for (const [expressId, color] of event.updates) {
-          cumulativeColorUpdates.set(expressId, color);
-        }
-        options.onColorUpdate?.(event.updates);
-        break;
-      case 'rtcOffset':
-        if (event.hasRtc) {
-          capturedRtcOffset = event.rtcOffset;
-          options.onRtcOffset?.({ rtcOffset: event.rtcOffset });
-        }
-        break;
-      case 'batch':
-        batchIndex += 1;
-        for (let i = 0; i < event.meshes.length; i++) {
-          allMeshes.push(event.meshes[i]);
-        }
-        finalCoordinateInfo = event.coordinateInfo ?? null;
-        options.onBatch?.({
-          batchIndex,
-          estimatedTotal,
-          totalSoFar: event.totalSoFar,
-          meshes: event.meshes,
-          coordinateInfo: event.coordinateInfo ?? null,
-        });
-        options.onProgress?.({
-          phase: `Processing geometry (${event.totalSoFar} meshes)`,
-          percent: 10 + Math.min(80, (allMeshes.length / 1000) * 0.8),
-        });
-        break;
-      case 'complete':
-        finalCoordinateInfo = event.coordinateInfo ?? null;
-        break;
+  });
+  let lastTotalMeshes = 0;
+  // The federated/added-model path was missing the size-aware stream watchdog
+  // the single-model loader has, so a geometry worker that failed to spawn would
+  // hang the load forever on "Processing geometry (N meshes)" instead of
+  // surfacing a recoverable error. watchedGeometryStream re-yields each event
+  // under that watchdog and bounds iterator teardown on every exit path.
+  try {
+    for await (const event of watchedGeometryStream(geometryStream, {
+      fileName: options.fileName,
+      fileSizeMB: options.fileSizeMB,
+      shouldAbort: options.shouldAbort,
+      getBatchCount: () => batchIndex,
+      getLastTotalMeshes: () => lastTotalMeshes,
+    })) {
+      switch (event.type) {
+        case 'start':
+          estimatedTotal = event.totalEstimate;
+          break;
+        case 'colorUpdate':
+          for (const [expressId, color] of event.updates) {
+            cumulativeColorUpdates.set(expressId, color);
+          }
+          options.onColorUpdate?.(event.updates);
+          break;
+        case 'rtcOffset':
+          if (event.hasRtc) {
+            capturedRtcOffset = event.rtcOffset;
+            options.onRtcOffset?.({ rtcOffset: event.rtcOffset });
+          }
+          break;
+        case 'batch':
+          batchIndex += 1;
+          for (let i = 0; i < event.meshes.length; i++) {
+            allMeshes.push(event.meshes[i]);
+          }
+          finalCoordinateInfo = event.coordinateInfo ?? null;
+          lastTotalMeshes = event.totalSoFar;
+          options.onBatch?.({
+            batchIndex,
+            estimatedTotal,
+            totalSoFar: event.totalSoFar,
+            meshes: event.meshes,
+            coordinateInfo: event.coordinateInfo ?? null,
+          });
+          options.onProgress?.({
+            phase: `Processing geometry (${event.totalSoFar} meshes)`,
+            percent: 10 + Math.min(80, (allMeshes.length / 1000) * 0.8),
+          });
+          break;
+        case 'complete':
+          finalCoordinateInfo = event.coordinateInfo ?? null;
+          break;
+      }
     }
+  } catch (err) {
+    // Watchdog stall (or other stream error): the parser worker may be
+    // blocked in `waitForEntityIndex`, which only the geometry pre-pass would
+    // unblock. Terminate it here so it doesn't leak — the normal path below
+    // still awaits it via resolveDataStoreOrAbort. watchedGeometryStream's
+    // finally has already bounded teardown of the geometry iterator itself.
+    workerParser?.terminate();
+    throw err;
   }
 
   // If the load was cancelled, don't await dataStorePromise: a worker parse

package/src/hooks/ingest/watchedGeometryStream.test.ts

@@ -0,0 +1,78 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+import { watchedGeometryStream } from './watchedGeometryStream.js';
+
+/** Build a controllable async source that records when return() is called. */
+function makeSource<T>(values: T[]): { source: AsyncIterable<T>; returned: () => boolean } {
+  let didReturn = false;
+  const source: AsyncIterable<T> = {
+    [Symbol.asyncIterator]() {
+      let i = 0;
+      return {
+        next: async () => (i < values.length
+          ? { done: false, value: values[i++] }
+          : { done: true, value: undefined as unknown as T }),
+        return: async () => {
+          didReturn = true;
+          return { done: true, value: undefined as unknown as T };
+        },
+      };
+    },
+  };
+  return { source, returned: () => didReturn };
+}
+
+const baseOpts = {
+  fileName: 'test.ifc',
+  fileSizeMB: 1,
+  getBatchCount: () => 0,
+  getLastTotalMeshes: () => 0,
+  cleanupMs: 50,
+};
+
+describe('watchedGeometryStream', () => {
+  it('re-yields every event in order then completes', async () => {
+    const { source } = makeSource([1, 2, 3]);
+    const seen: number[] = [];
+    for await (const v of watchedGeometryStream(source, baseOpts)) seen.push(v);
+    assert.deepStrictEqual(seen, [1, 2, 3]);
+  });
+
+  it('stops early when shouldAbort() turns true', async () => {
+    const { source } = makeSource([1, 2, 3, 4]);
+    const seen: number[] = [];
+    let calls = 0;
+    for await (const v of watchedGeometryStream(source, {
+      ...baseOpts,
+      // Abort after the second event has been consumed.
+      shouldAbort: () => (++calls > 2),
+    })) {
+      seen.push(v);
+    }
+    assert.deepStrictEqual(seen, [1, 2]);
+  });
+
+  it('tears down the underlying iterator on normal completion', async () => {
+    const { source, returned } = makeSource([1]);
+    let count = 0;
+    for await (const v of watchedGeometryStream(source, baseOpts)) count += v;
+    assert.strictEqual(count, 1);
+    assert.strictEqual(returned(), true);
+  });
+
+  it('tears down the underlying iterator when the consumer breaks early', async () => {
+    const { source, returned } = makeSource([1, 2, 3]);
+    const seen: number[] = [];
+    for await (const v of watchedGeometryStream(source, baseOpts)) {
+      seen.push(v);
+      break;
+    }
+    assert.deepStrictEqual(seen, [1]);
+    assert.strictEqual(returned(), true);
+  });
+});

package/src/hooks/ingest/watchedGeometryStream.ts

@@ -0,0 +1,76 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { getGeometryStreamWatchdogMs } from '@ifc-lite/geometry';
+import { boundedIteratorReturn } from './streamCleanup.js';
+
+export interface WatchedGeometryStreamOptions {
+  /** File name, for the stall error message. */
+  fileName: string;
+  /** File size in MB, feeds the size-aware watchdog deadline. */
+  fileSizeMB: number;
+  /** Abort the stream cooperatively (e.g. user cancelled the load). */
+  shouldAbort?: () => boolean;
+  /** Current batch index — feeds the size-aware watchdog deadline. */
+  getBatchCount: () => number;
+  /** Meshes rendered so far, for the stall error message. */
+  getLastTotalMeshes: () => number;
+  /** Override the abandon-cleanup deadline (mostly for tests). */
+  cleanupMs?: number;
+}
+
+/**
+ * Drive a geometry stream under a size-aware watchdog, re-yielding every event.
+ *
+ * The parallel pipeline only ends once EVERY spawned geometry worker reports
+ * `complete`; if the browser fails to instantiate a worker (the "Attempting to
+ * create a Worker from an empty source" warning) that worker never reports
+ * `ready`/`complete` and never fires `onerror`, so the underlying generator can
+ * wedge forever, stranding the load on "Processing geometry (N meshes)". Racing
+ * each `next()` against a deadline converts that silent wedge into a thrown,
+ * recoverable error. On ANY exit — normal completion, abort, consumer `break`,
+ * or a watchdog throw — the `finally` bounds the underlying iterator's shutdown
+ * so cleanup (the generator's own `finally`: freeing WASM handles, tearing down
+ * workers) runs without re-blocking on the very stall the watchdog just escaped.
+ *
+ * Generic over the event type so the consumer keeps full type-narrowing in its
+ * own `switch`.
+ */
+export async function* watchedGeometryStream<T>(
+  source: AsyncIterable<T>,
+  options: WatchedGeometryStreamOptions,
+): AsyncGenerator<T> {
+  const iterator = source[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      const watchdogMs = getGeometryStreamWatchdogMs({
+        desktopStableWasm: false,
+        batchCount: options.getBatchCount(),
+        fileSizeMB: options.fileSizeMB,
+      });
+      let watchdogId: ReturnType<typeof setTimeout> | null = null;
+      let result: IteratorResult<T>;
+      try {
+        result = await Promise.race([
+          iterator.next(),
+          new Promise<never>((_, reject) => {
+            watchdogId = setTimeout(() => {
+              reject(new Error(
+                `Geometry stream stalled after ${watchdogMs}ms while loading ${options.fileName}. `
+                + `Last rendered meshes: ${options.getLastTotalMeshes()}. A geometry worker likely failed to start.`,
+              ));
+            }, watchdogMs);
+          }),
+        ]);
+      } finally {
+        if (watchdogId !== null) clearTimeout(watchdogId);
+      }
+      if (result.done) return;
+      if (options.shouldAbort?.()) return;
+      yield result.value;
+    }
+  } finally {
+    await boundedIteratorReturn(iterator, options.cleanupMs);
+  }
+}

package/src/hooks/source-key.ts

@@ -0,0 +1,35 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+
+// Per-source-object memo so the full-content hash runs only once per loaded
+// buffer (the same Uint8Array instance is reused across re-renders).
+const SOURCE_KEY_CACHE = new WeakMap<Uint8Array, string>();
+
+/**
+ * Stable per-source cache key — a **full-content** FNV-1a hash (not sampled
+ * byte windows), so two distinct IFC binaries can't collide and reuse the wrong
+ * cache entry (which would render another model's overlay). The O(n) hash is
+ * memoised per source object via a WeakMap, so it runs once per loaded buffer.
+ *
+ * Shared by the per-source overlay hooks (alignment + grid lines) so they stay
+ * in lockstep — see #967 review (CodeRabbit aliasing finding applied to both).
+ */
+export function sourceKey(store: IfcDataStore | null | undefined): string | null {
+  const source = store?.source;
+  if (!source || source.byteLength === 0) return null;
+
+  const cached = SOURCE_KEY_CACHE.get(source);
+  if (cached) return cached;
+
+  let h = 0x811c9dc5;
+  for (let i = 0; i < source.length; i++) {
+    h ^= source[i];
+    h = Math.imul(h, 0x01000193);
+  }
+  const key = `b${source.byteLength}-${(h >>> 0).toString(16)}`;
+  SOURCE_KEY_CACHE.set(source, key);
+  return key;
+}