@ifc-lite/viewer 1.25.1 → 1.26.0

package/src/hooks/useClash.ts

@@ -0,0 +1,420 @@
+/* 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/. */
+
+/**
+ * Clash detection orchestration (Phase 1). Gathers `ClashElement`s from every
+ * loaded model via the STEP adapter, runs the (robust, in-process) TypeScript
+ * engine, and drives the viewer: selecting + framing a clash pair, highlighting
+ * all, and exporting a *grouped* BCF. Coloring/identity flow through the
+ * renderer's selection channel and the federation registry.
+ */
+
+import { useCallback } from 'react';
+import { useViewerStore } from '@/store';
+import {
+  createClashEngine,
+  rulesFromPresets,
+  groupClashes,
+  type Clash,
+  type ClashElement,
+  type ClashElementRef,
+  type ClashGroup,
+  type ClashResult,
+  type ClashRule,
+  type ClashSeverity,
+  type ExclusionSet,
+} from '@ifc-lite/clash';
+import { elementsFromStep } from '@ifc-lite/clash/step';
+import { createBCFFromClashResult } from '@ifc-lite/clash/bcf';
+import { writeBCF } from '@ifc-lite/bcf';
+import { getGlobalRenderer } from '@/hooks/useBCF';
+
+interface SelectionRef {
+  modelId: string;
+  expressId: number;
+}
+
+/** How clashes collapse into BCF topics. `storey` is omitted — Clash has no
+ *  storey, so it degrades to `rule` (see grouping.ts) and would only confuse. */
+export type ClashBcfGroupBy = 'cluster' | 'rule' | 'typePair' | 'element';
+
+/** User-controllable settings for a BCF export — "what gets created". */
+export interface ClashBcfConfig {
+  /** Grouping dimension → one BCF topic per group. */
+  groupBy: ClashBcfGroupBy;
+  /** Only clashes of these severities become topics. */
+  severities: ClashSeverity[];
+  /** Render each topic's viewpoint offscreen and embed a PNG snapshot. */
+  includeSnapshots: boolean;
+  /** Initial BCF topic status (Open / In Progress / ...). */
+  status: string;
+  /** Safety cap on topic count; overflow is recorded in one marker topic. */
+  maxTopics: number;
+}
+
+/** Dark, neutral background for offscreen snapshot captures (Tokyo Night base). */
+const SNAPSHOT_CLEAR_COLOR: [number, number, number, number] = [0.04, 0.05, 0.1, 1];
+
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement('a');
+  anchor.href = url;
+  anchor.download = filename;
+  anchor.click();
+  URL.revokeObjectURL(url);
+}
+
+/** Decode a `data:image/png;base64,...` URL into raw PNG bytes for the BCF zip. */
+function dataUrlToBytes(dataUrl: string): Uint8Array | undefined {
+  const comma = dataUrl.indexOf(',');
+  if (comma < 0) return undefined;
+  try {
+    const binary = atob(dataUrl.slice(comma + 1));
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+    return bytes;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Drop clashes whose severity is not selected; total is kept consistent. */
+function filterResultBySeverity(result: ClashResult, severities: Set<ClashSeverity>): ClashResult {
+  const clashes = result.clashes.filter((c) => severities.has(c.severity));
+  return { ...result, clashes, summary: { ...result.summary, total: clashes.length } };
+}
+
+export function useClash() {
+  const result = useViewerStore((s) => s.clashResult);
+  const groups = useViewerStore((s) => s.clashGroups);
+  const running = useViewerStore((s) => s.clashRunning);
+  const error = useViewerStore((s) => s.clashError);
+  const progress = useViewerStore((s) => s.clashProgress);
+  const mode = useViewerStore((s) => s.clashMode);
+  const tolerance = useViewerStore((s) => s.clashTolerance);
+  const clearance = useViewerStore((s) => s.clashClearance);
+  const groupBy = useViewerStore((s) => s.clashGroupBy);
+  const clusterEpsilon = useViewerStore((s) => s.clashClusterEpsilon);
+  const reportTouch = useViewerStore((s) => s.clashReportTouch);
+  const clashPresets = useViewerStore((s) => s.clashPresets);
+  const selectedId = useViewerStore((s) => s.clashSelectedId);
+  const panelVisible = useViewerStore((s) => s.clashPanelVisible);
+
+  const setMode = useViewerStore((s) => s.setClashMode);
+  const setTolerance = useViewerStore((s) => s.setClashTolerance);
+  const setClearance = useViewerStore((s) => s.setClashClearance);
+  const setGroupBy = useViewerStore((s) => s.setClashGroupBy);
+  const setSelectedId = useViewerStore((s) => s.setClashSelectedId);
+  const setPanelVisible = useViewerStore((s) => s.setClashPanelVisible);
+  const clear = useViewerStore((s) => s.clearClash);
+
+  /** Build clash elements + merged exclusions from every loaded model. */
+  const gatherElements = useCallback((): { elements: ClashElement[]; exclusions: ExclusionSet } => {
+    const state = useViewerStore.getState();
+    const elements: ClashElement[] = [];
+    const exclusions: ExclusionSet = new Set<string>();
+    const federation = { toGlobalId: (modelId: string, expressId: number) => state.toGlobalId(modelId, expressId) };
+
+    for (const [modelId, model] of state.models) {
+      const store = model.ifcDataStore;
+      const meshes = model.geometryResult?.meshes;
+      if (!store || !meshes || meshes.length === 0) continue;
+      const built = elementsFromStep({ store, meshes, modelId, federation });
+      elements.push(...built.elements);
+      for (const key of built.exclusions) exclusions.add(key);
+    }
+    return { elements, exclusions };
+  }, []);
+
+  const run = useCallback(
+    async (rules: ClashRule[]): Promise<void> => {
+      const state = useViewerStore.getState();
+      state.setClashRunning(true);
+      state.setClashError(null);
+      // Indeterminate "preparing" state until the engine reports candidate counts.
+      state.setClashProgress({ phase: 'broad', rule: '', done: 0, total: 0 });
+      try {
+        // Let the panel paint the running state before the heavy work.
+        await new Promise((resolve) => requestAnimationFrame(resolve));
+        const { elements, exclusions } = gatherElements();
+        if (elements.length === 0) {
+          state.setClashError('No model geometry is loaded. Load an IFC model first.');
+          return;
+        }
+        const engine = createClashEngine({ backend: 'ts' });
+        const res = await engine.run(elements, rules, {
+          exclusions,
+          tolerance: state.clashTolerance,
+          // The TS engine yields between chunks, so these updates actually paint.
+          onProgress: (p) => useViewerStore.getState().setClashProgress(p),
+        });
+        state.setClashResult(res);
+        // Spatial clustering is the sensible BCF unit; the panel list groups by
+        // its own dimension separately. Radius is the user's cluster epsilon.
+        state.setClashGroups(groupClashes(res, { by: 'cluster', epsilon: state.clashClusterEpsilon }));
+        state.setClashSelectedId(null);
+      } catch (err) {
+        console.error('[clash] detection run failed', err);
+        state.setClashError(err instanceof Error ? err.message : String(err));
+      } finally {
+        state.setClashRunning(false);
+        state.setClashProgress(null);
+      }
+    },
+    [gatherElements],
+  );
+
+  /**
+   * Run the user's ENABLED rule set (built-in discipline rules they've kept on,
+   * plus any custom presets). With no enabled rules, surface a clear message
+   * instead of silently finding nothing.
+   */
+  const runMatrix = useCallback((): Promise<void> => {
+    const enabled = clashPresets.filter((p) => p.enabled);
+    if (enabled.length === 0) {
+      useViewerStore.getState().setClashError('All rules are disabled — enable at least one in Clash settings (⚙).');
+      return Promise.resolve();
+    }
+    return run(rulesFromPresets(enabled, mode, mode === 'clearance' ? clearance : undefined, reportTouch));
+  }, [run, mode, clearance, reportTouch, clashPresets]);
+
+  /**
+   * Detect ALL clashes in the loaded geometry — a single self-clash rule over
+   * every element (every element vs every other), no discipline matrix or
+   * A/B selectors needed. For a single loaded model this is "all clashes inside
+   * the model".
+   */
+  const runAll = useCallback(
+    (): Promise<void> =>
+      run([
+        {
+          id: 'all-clashes',
+          name: 'All elements',
+          a: '*',
+          mode,
+          ...(mode === 'clearance' ? { clearance } : {}),
+          ...(reportTouch ? { reportTouch: true } : {}),
+        },
+      ]),
+    [run, mode, clearance, reportTouch],
+  );
+
+  const runPreset = useCallback(
+    (presetId: string): Promise<void> => {
+      const preset = useViewerStore.getState().clashPresets.find((p) => p.id === presetId);
+      if (!preset) return Promise.resolve();
+      return run(rulesFromPresets([preset], mode, mode === 'clearance' ? clearance : undefined, reportTouch));
+    },
+    [run, mode, clearance, reportTouch],
+  );
+
+  const refOf = useCallback((ref: ClashElementRef): SelectionRef | null => {
+    return useViewerStore.getState().fromGlobalId(ref.ref);
+  }, []);
+
+  /** Select both elements of a clash, highlight them, and frame the camera. */
+  const focusClash = useCallback(
+    (clash: Clash): void => {
+      const state = useViewerStore.getState();
+      const a = refOf(clash.a);
+      const b = refOf(clash.b);
+      const refs = [a, b].filter((r): r is SelectionRef => r !== null);
+      if (refs.length === 0) return;
+      // The renderer highlights the GLOBAL-id set (`selectedEntityIds`) and
+      // `frameSelection` frames it — `clash.X.ref` IS the federated global id
+      // (see gatherElements), so drive those, not just the model-aware set.
+      const globalIds: number[] = [];
+      if (a) globalIds.push(clash.a.ref);
+      if (b) globalIds.push(clash.b.ref);
+      // Replace any existing selection so the camera frames only this clash pair.
+      state.clearEntitySelection();
+      state.setSelectedEntityIds(globalIds); // highlight BOTH elements + frame target
+      state.addEntitiesToSelection(refs); // model-aware context for the properties panel
+      state.setClashSelectedId(clash.id);
+      requestAnimationFrame(() => state.cameraCallbacks.frameSelection?.());
+    },
+    [refOf],
+  );
+
+  /** Highlight every element involved in any clash. */
+  const highlightAll = useCallback((): void => {
+    const state = useViewerStore.getState();
+    const current = state.clashResult;
+    if (!current) return;
+    // Drive the renderer's global-id highlight set (`selectedEntityIds`); the
+    // model-aware set is added alongside for properties / federation context.
+    const globalIds = new Set<number>();
+    const refs: SelectionRef[] = [];
+    for (const clash of current.clashes) {
+      for (const el of [clash.a, clash.b]) {
+        const ref = refOf(el);
+        if (ref) {
+          globalIds.add(el.ref);
+          refs.push(ref);
+        }
+      }
+    }
+    if (globalIds.size === 0) return;
+    state.setSelectedEntityIds([...globalIds]);
+    state.addEntitiesToSelection(refs);
+  }, [refOf]);
+
+  const clearHighlight = useCallback((): void => {
+    useViewerStore.getState().clearEntitySelection();
+    setSelectedId(null);
+  }, [setSelectedId]);
+
+  /**
+   * Preview what a given export config would produce, WITHOUT building anything:
+   * how many clashes survive the severity filter and how many BCF topics they
+   * collapse into under the chosen grouping (incl. the overflow marker topic).
+   * Cheap (pure grouping) so the dialog can call it on every keystroke.
+   */
+  const bcfPreview = useCallback((config: ClashBcfConfig): { clashes: number; topics: number } => {
+    const state = useViewerStore.getState();
+    const current = state.clashResult;
+    if (!current) return { clashes: 0, topics: 0 };
+    const filtered = filterResultBySeverity(current, new Set(config.severities));
+    if (filtered.clashes.length === 0) return { clashes: 0, topics: 0 };
+    const groups = groupClashes(filtered, { by: config.groupBy, epsilon: state.clashClusterEpsilon });
+    const capped = Math.min(groups.length, config.maxTopics);
+    const overflow = groups.length > config.maxTopics ? 1 : 0;
+    return { clashes: filtered.clashes.length, topics: capped + overflow };
+  }, []);
+
+  /**
+   * Export the current clash result to a BCF 2.1 archive under `config`.
+   *
+   * Filters by severity, groups along the chosen dimension (one topic per
+   * group), and — when `includeSnapshots` is on and a renderer is live —
+   * renders each topic's framing viewpoint offscreen and embeds a PNG. The
+   * snapshot pass mirrors the IDS batch path: save viewer state, then per group
+   * frame the bounds + isolate the members + capture, and restore at the end.
+   * `onProgress(done, total)` ticks once per captured snapshot.
+   */
+  const exportBcf = useCallback(
+    async (config: ClashBcfConfig, onProgress?: (done: number, total: number) => void): Promise<void> => {
+      const state = useViewerStore.getState();
+      const current = state.clashResult;
+      if (!current) return;
+      const filtered = filterResultBySeverity(current, new Set(config.severities));
+      if (filtered.clashes.length === 0) return;
+      const groups = groupClashes(filtered, { by: config.groupBy, epsilon: state.clashClusterEpsilon });
+
+      let restore: (() => void) | undefined;
+      let snapshotProvider: ((group: ClashGroup) => Promise<Uint8Array | undefined>) | undefined;
+
+      if (config.includeSnapshots) {
+        const renderer = getGlobalRenderer();
+        if (renderer) {
+          const saved = {
+            selectedEntityId: state.selectedEntityId,
+            selectedEntityIds: state.selectedEntityIds,
+            isolatedEntities: state.isolatedEntities,
+            hiddenEntities: state.hiddenEntities,
+          };
+          restore = () => {
+            useViewerStore.setState({
+              selectedEntityId: saved.selectedEntityId,
+              selectedEntityIds: saved.selectedEntityIds,
+              isolatedEntities: saved.isolatedEntities,
+              hiddenEntities: saved.hiddenEntities,
+            });
+            renderer.render({
+              hiddenIds: saved.hiddenEntities,
+              isolatedIds: saved.isolatedEntities,
+              selectedId: saved.selectedEntityId,
+              // Repaint the full multi-selection too — the snapshot loop drove the
+              // renderer directly without touching the store, so the store's
+              // selectedEntityIds reference never changed and useRenderUpdates
+              // won't re-fire. Without this the clash highlight vanishes post-export.
+              selectedIds: saved.selectedEntityIds,
+            });
+          };
+          const total = Math.min(groups.length, config.maxTopics);
+          const camera = renderer.getCamera();
+          let done = 0;
+          snapshotProvider = async (group: ClashGroup): Promise<Uint8Array | undefined> => {
+            const b = group.bounds;
+            await camera.frameBounds(
+              { x: b.min[0], y: b.min[1], z: b.min[2] },
+              { x: b.max[0], y: b.max[1], z: b.max[2] },
+              1,
+            );
+            // Isolate just this topic's members so the snapshot is unambiguous;
+            // no selection highlight so the captured colours read true.
+            const isolation = new Set<number>();
+            for (const m of group.members) {
+              isolation.add(m.a.ref);
+              isolation.add(m.b.ref);
+            }
+            renderer.render({ isolatedIds: isolation, selectedId: null, clearColor: SNAPSHOT_CLEAR_COLOR });
+            const device = renderer.getGPUDevice();
+            if (device) await device.queue.onSubmittedWorkDone();
+            // Let the compositor present the frame before reading the canvas.
+            await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+            const dataUrl = await renderer.captureScreenshot();
+            done += 1;
+            onProgress?.(done, total);
+            return dataUrl ? dataUrlToBytes(dataUrl) : undefined;
+          };
+        }
+      }
+
+      try {
+        const project = await createBCFFromClashResult(filtered, groups, {
+          author: 'clash@ifc-lite',
+          projectName: 'Clash report',
+          status: config.status,
+          maxTopics: config.maxTopics,
+          ...(snapshotProvider ? { snapshotProvider } : {}),
+        });
+        const blob = await writeBCF(project);
+        downloadBlob(blob, 'clashes.bcfzip');
+      } finally {
+        restore?.();
+      }
+    },
+    [],
+  );
+
+  const clearAll = useCallback((): void => {
+    useViewerStore.getState().clearEntitySelection();
+    clear();
+  }, [clear]);
+
+  return {
+    // state
+    result,
+    groups,
+    running,
+    error,
+    progress,
+    mode,
+    tolerance,
+    clearance,
+    groupBy,
+    selectedId,
+    panelVisible,
+    // Only enabled presets show as run chips; the settings dialog manages the full set.
+    presets: clashPresets.filter((p) => p.enabled),
+    // settings
+    setMode,
+    setTolerance,
+    setClearance,
+    setGroupBy,
+    setPanelVisible,
+    // actions
+    run,
+    runAll,
+    runMatrix,
+    runPreset,
+    focusClash,
+    highlightAll,
+    clearHighlight,
+    exportBcf,
+    bcfPreview,
+    clearAll,
+  };
+}

package/src/hooks/useIfcCache.ts

@@ -13,10 +13,11 @@ import { useCallback } from 'react';
 import {
   BinaryCacheWriter,
   BinaryCacheReader,
+  type CachedEntityIndexColumns,
   type IfcDataStore as CacheDataStore,
   type GeometryData,
 } from '@ifc-lite/cache';
-import { SpatialHierarchyBuilder, StepTokenizer, CompactEntityIndexBuilder, extractLengthUnitScale, type IfcDataStore } from '@ifc-lite/parser';
+import { SpatialHierarchyBuilder, StepTokenizer, CompactEntityIndex, CompactEntityIndexBuilder, extractLengthUnitScale, type IfcDataStore } from '@ifc-lite/parser';
 import { buildSpatialIndexGuarded } from '../utils/loadingUtils.js';
 import type { MeshData } from '@ifc-lite/geometry';
 
@@ -30,6 +31,27 @@ import { calculateStoreyHeights } from '../utils/localParsingUtils.js';
 export type { CacheResult } from '../services/cacheService.js';
 export { getCached, setCached, deleteCached } from '../services/cacheService.js';
 
+function buildEntityIndexFromCachedColumns(columns: CachedEntityIndexColumns): IfcDataStore['entityIndex'] {
+  const byId = new CompactEntityIndex(
+    columns.ids,
+    columns.byteOffsets,
+    columns.byteLengths,
+    columns.typeIndices,
+    columns.typeNames,
+  );
+  const byType = new Map<string, number[]>();
+  for (let i = 0; i < columns.ids.length; i++) {
+    const type = columns.typeNames[columns.typeIndices[i]];
+    let ids = byType.get(type);
+    if (!ids) {
+      ids = [];
+      byType.set(type, ids);
+    }
+    ids.push(columns.ids[i]);
+  }
+  return { byId, byType };
+}
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -107,25 +129,28 @@ export function useIfcCache() {
       if (cacheResult.sourceBuffer) {
         dataStore.source = new Uint8Array(cacheResult.sourceBuffer);
 
-        // Quick scan to rebuild entity index with byte offsets (needed for on-demand extraction).
-        // Uses CompactEntityIndexBuilder to fill typed arrays directly during the scan,
-        // avoiding a temporary array of 4.4M+ objects (~350MB for large files).
-        const tokenizer = new StepTokenizer(dataStore.source);
-        const estimatedCount = dataStore.entities?.count ?? 100_000;
-        const indexBuilder = new CompactEntityIndexBuilder(estimatedCount);
-        const byType = new Map<string, number[]>();
-
-        for (const ref of tokenizer.scanEntitiesFast()) {
-          indexBuilder.add(ref.expressId, ref.type, ref.offset, ref.length);
-          let typeList = byType.get(ref.type);
-          if (!typeList) {
-            typeList = [];
-            byType.set(ref.type, typeList);
+        if (result.entityIndex) {
+          dataStore.entityIndex = buildEntityIndexFromCachedColumns(result.entityIndex);
+        } else {
+          // Backward compatibility for v3 caches: rebuild byte offsets from the
+          // source once, then future v4 writes persist this section.
+          const tokenizer = new StepTokenizer(dataStore.source);
+          const estimatedCount = dataStore.entities?.count ?? 100_000;
+          const indexBuilder = new CompactEntityIndexBuilder(estimatedCount);
+          const byType = new Map<string, number[]>();
+
+          for (const ref of tokenizer.scanEntitiesFast()) {
+            indexBuilder.add(ref.expressId, ref.type, ref.offset, ref.length);
+            let typeList = byType.get(ref.type);
+            if (!typeList) {
+              typeList = [];
+              byType.set(ref.type, typeList);
+            }
+            typeList.push(ref.expressId);
           }
-          typeList.push(ref.expressId);
+          const compactByIdIndex = indexBuilder.build();
+          dataStore.entityIndex = { byId: compactByIdIndex, byType };
         }
-        const compactByIdIndex = indexBuilder.build();
-        dataStore.entityIndex = { byId: compactByIdIndex, byType };
 
         // Rebuild on-demand maps from relationships
         // Pass entityIndex which contains ALL entity types including IfcPropertySet/IfcElementQuantity
@@ -254,6 +279,7 @@ export function useIfcCache() {
         quantities: dataStore.quantities,
         relationships: dataStore.relationships,
         spatialHierarchy: dataStore.spatialHierarchy,
+        entityIndex: dataStore.entityIndex,
       };
 
       console.log('[useIfcCache] Writing cache buffer...');

package/src/hooks/useIfcFederation.ts

@@ -40,7 +40,7 @@ import {
 } from './ingest/pointCloudIngest.js';
 import { getGlobalRenderer } from './useBCF.js';
 import { readNativeFile, type NativeFileHandle } from '../services/file-dialog.js';
-import { getEffectiveGeoreference, getEffectiveHorizontalScale, type GeorefMutationDataLike } from '../lib/geo/effective-georef.js';
+import { getEffectiveGeoreference, getEffectiveHorizontalScale, hasStandardGeoreferencing, type GeorefMutationDataLike } from '../lib/geo/effective-georef.js';
 import { resolveMapUnitToMetreScale } from '../lib/geo/geo-scale.js';
 import { resolveProjection } from '../lib/geo/reproject.js';
 import { toast } from '../components/ui/toast.js';
@@ -105,7 +105,21 @@ function extractModelGeoref(
   mutations?: GeorefMutationDataLike,
 ): ModelGeoref | null {
   const georef = getEffectiveGeoreference(dataStore, coordinateInfo, mutations);
-  if (!georef?.mapConversion || !georef.projectedCRS?.name) return null;
+  // Only TRUE georeferencing (real IfcMapConversion + IfcProjectedCRS) may drive
+  // federation alignment. A file with no IfcMapConversion gets a synthesised
+  // `source: 'siteLocation'` georef (EPSG:4326 from IfcSite RefLatitude/Longitude/
+  // Elevation) so it can still be pinned on the location map — but those are
+  // geographic degrees plus a raw, un-unit-scaled site elevation, not a projected
+  // metric frame. buildGeorefAlignmentTransform assumes projected eastings/
+  // northings/height in metres, so feeding it site data places the second model
+  // kilometres away: the BIMcollab ARC/STR pair share a site GUID but carry
+  // RefElevation 0 vs 20000 mm, and the height term lands ARC ~20 km below STR.
+  // Such models have no real georef relationship, so leave them in their own local
+  // frames where they overlay correctly. hasStandardGeoreferencing() excludes
+  // 'siteLocation' (see effective-georef.test.ts). (Regression from #658.)
+  if (!hasStandardGeoreferencing(georef) || !georef?.mapConversion || !georef.projectedCRS?.name) {
+    return null;
+  }
   return {
     mapConversion: georef.mapConversion,
     projectedCRS: georef.projectedCRS,

package/src/hooks/useIfcLoader.ts

@@ -55,6 +55,7 @@ import { useIfcCache, getCached } from './useIfcCache.js';
 import { useIfcServer } from './useIfcServer.js';
 
 import { getMaxExpressId, parseGlbViewerModel, parseIfcxViewerModel } from './ingest/viewerModelIngest.js';
+import { boundedIteratorReturn } from './ingest/streamCleanup.js';
 import { detectPointCloudFormat, ingestPointCloud } from './ingest/pointCloudIngest.js';
 import { getGlobalRenderer } from './useBCF.js';
 
@@ -1905,7 +1906,7 @@ export function useIfcLoader() {
         // risking corruption.
         const parserWasmApi = isNativeFileHandle(file) ? undefined : geometryProcessor.getApi();
         return new IfcParser().parseColumnar(buffer, {
-          wasmApi: parserWasmApi,
+          wasmApi: parserWasmApi ?? undefined,
           onSpatialReady: onPartialDataStore,
         });
       };
@@ -2032,34 +2033,12 @@ export function useIfcLoader() {
         // When the parser worker is in use, hand the geometry workers the
         // same SAB so we don't pay the file-bytes copy twice.
         const geometryView = sharedSource ? new Uint8Array(sharedSource) : new Uint8Array(buffer);
-        // Phase 2 of single-controller-rayon-design.md — opt-in via
-        // localStorage so we can A/B compare against the N-worker
-        // baseline without rolling out for everyone. Users (and the
-        // benchmark harness) flip this with:
-        //   localStorage.setItem('ifc-lite:single-controller', '1')
-        // and reload. Set to anything else (or unset) for the legacy
-        // N-worker path. Safe: if the threaded WASM bundle fails to
-        // load (no COI, Safari, etc.) the controller worker falls back
-        // to per-task serial execution within the controller itself
-        // (par_iter without an initialized pool).
-        const useSingleController = (() => {
-          try {
-            return typeof localStorage !== 'undefined'
-              && localStorage.getItem('ifc-lite:single-controller') === '1';
-          } catch {
-            return false;
-          }
-        })();
-        if (useSingleController) {
-          console.log('[useIfc] single-controller path enabled (Phase 2)');
-        }
         const geometryEvents = shouldUseDesktopStableWasmGeometry
           ? geometryProcessor.processStreaming(geometryView, undefined, dynamicBatchConfig)
           : geometryProcessor.processAdaptive(geometryView, {
               sizeThreshold: 2 * 1024 * 1024, // 2MB threshold
               batchSize: dynamicBatchConfig, // Dynamic batches: small first, then large
               existingSab: sharedSource ?? undefined,
-              useSingleController,
               // Hand the streaming pre-pass's entity index to the parser
               // worker so it skips a duplicate ~10 s WASM scan. Safe even
               // when the parser falls back to main-thread (instance is
@@ -2075,13 +2054,10 @@ export function useIfcLoader() {
         closeGeometryIterator = async () => {
           if (geometryIteratorClosed || typeof geometryIterator.return !== 'function') return;
           geometryIteratorClosed = true;
-          try {
-            // `AsyncIterator.return()` is signed as taking a value in
-            // current TS libs; callers conventionally pass `undefined`.
-            await geometryIterator.return(undefined);
-          } catch {
-            // Ignore iterator shutdown failures during recovery.
-          }
+          // Bound the shutdown: `return()` cannot interrupt a generator parked
+          // on a stalled worker await, so an unbounded await would re-wedge on
+          // the very stall the watchdog escaped. See boundedIteratorReturn.
+          await boundedIteratorReturn(geometryIterator);
         };
 
         while (true) {