@ifc-lite/viewer 1.25.1 → 1.26.0

package/src/components/viewer/ViewportContainer.tsx

@@ -39,6 +39,26 @@ const DEFAULT_COORDINATE_INFO: CoordinateInfo = {
   hasLargeCoordinates: false,
 };
 
+type Vec3Bounds = { min: { x: number; y: number; z: number }; max: { x: number; y: number; z: number } };
+
+/** True for a real (non-placeholder, non-degenerate) bounds box. */
+function isUsableBounds(b: Vec3Bounds | undefined): b is Vec3Bounds {
+  if (!b) return false;
+  return (
+    b.max.x > b.min.x || b.max.y > b.min.y || b.max.z > b.min.z
+  );
+}
+
+/** Axis-aligned union of two bounds boxes (either may be undefined). */
+function unionBounds(acc: Vec3Bounds | undefined, b: Vec3Bounds | undefined): Vec3Bounds | undefined {
+  if (!isUsableBounds(b)) return acc;
+  if (!acc) return { min: { ...b.min }, max: { ...b.max } };
+  return {
+    min: { x: Math.min(acc.min.x, b.min.x), y: Math.min(acc.min.y, b.min.y), z: Math.min(acc.min.z, b.min.z) },
+    max: { x: Math.max(acc.max.x, b.max.x), y: Math.max(acc.max.y, b.max.y), z: Math.max(acc.max.z, b.max.z) },
+  };
+}
+
 export function ViewportContainer() {
   // Drive Stacked / Solo / Exploded level display from the slice.
   // Mount-once hook — it self-gates on mode + gap + model changes.
@@ -121,7 +141,16 @@ export function ViewportContainer() {
     if (storeModels.size > 1) {
       let totalVertices = 0;
       let totalTriangles = 0;
-      let mergedCoordinateInfo: CoordinateInfo | undefined;
+      // The merged coordinateInfo must cover ALL visible models, not just the
+      // first one — the renderer fits the camera to `shiftedBounds`, so a
+      // first-wins box left every model after the first off-screen (it only
+      // showed its 2D grid overlay). Union the bounds across visible models;
+      // keep the first model's frame metadata (originShift / RTC) since
+      // federated models share a coordinate frame.
+      let baseCoordInfo: CoordinateInfo | undefined;
+      let unionedShifted: Vec3Bounds | undefined;
+      let unionedOriginal: Vec3Bounds | undefined;
+      let anyLargeCoords = false;
       let shouldRebuild = false;
 
       if (mergedLengthsRef.current.size !== storeModels.size) {
@@ -142,8 +171,12 @@ export function ViewportContainer() {
         const meshCount = model.visible ? (modelGeometry?.meshes.length ?? 0) : 0;
         totalVertices += model.visible ? (modelGeometry?.totalVertices ?? 0) : 0;
         totalTriangles += model.visible ? (modelGeometry?.totalTriangles ?? 0) : 0;
-        if (!mergedCoordinateInfo && model.visible && modelGeometry?.coordinateInfo) {
-          mergedCoordinateInfo = modelGeometry.coordinateInfo;
+        if (model.visible && modelGeometry?.coordinateInfo) {
+          const ci = modelGeometry.coordinateInfo;
+          if (!baseCoordInfo) baseCoordInfo = ci;
+          anyLargeCoords = anyLargeCoords || !!ci.hasLargeCoordinates;
+          unionedShifted = unionBounds(unionedShifted, ci.shiftedBounds);
+          unionedOriginal = unionBounds(unionedOriginal, ci.originalBounds);
         }
 
         if (
@@ -187,6 +220,15 @@ export function ViewportContainer() {
         }
       }
 
+      const mergedCoordinateInfo: CoordinateInfo | undefined = baseCoordInfo
+        ? {
+            ...baseCoordInfo,
+            originalBounds: unionedOriginal ?? baseCoordInfo.originalBounds,
+            shiftedBounds: unionedShifted ?? baseCoordInfo.shiftedBounds,
+            hasLargeCoordinates: anyLargeCoords,
+          }
+        : undefined;
+
       return {
         meshes: mergedCacheRef.current,
         totalVertices,

package/src/components/viewer/bcf/BCFOverlay.tsx

@@ -128,7 +128,7 @@ export function BCFOverlay() {
   const bcfProject = useViewerStore((s) => s.bcfProject);
   const activeTopicId = useViewerStore((s) => s.activeTopicId);
   const setActiveTopic = useViewerStore((s) => s.setActiveTopic);
-  const setBcfPanelVisible = useViewerStore((s) => s.setBcfPanelVisible);
+  const openWorkspacePanel = useViewerStore((s) => s.openWorkspacePanel);
   const models = useViewerStore((s) => s.models);
   const loading = useViewerStore((s) => s.loading);
   const ifcDataStore = useViewerStore((s) => s.ifcDataStore);
@@ -239,10 +239,11 @@ export function BCFOverlay() {
     if (!overlay) return;
     return overlay.onMarkerClick((topicGuid) => {
       setActiveTopic(topicGuid);
-      const panelVisible = useViewerStore.getState().bcfPanelVisible;
-      if (!panelVisible) setBcfPanelVisible(true);
+      // Open BCF exclusively so clicking a marker brings it to the front over any
+      // other right panel (e.g. clash), instead of leaving it behind.
+      openWorkspacePanel('bcf');
     });
-  }, [overlayReady, setActiveTopic, setBcfPanelVisible]);
+  }, [overlayReady, setActiveTopic, openWorkspacePanel]);
 
   return (
     <div

package/src/components/viewer/hierarchy/ifc-icons.ts

@@ -17,6 +17,20 @@ export const IFC_ICON_CODEPOINTS: Record<string, string> = {
   IfcBuilding: '\uea40',
   IfcBuildingStorey: '\ue8fe',
   IfcSpace: '\ueff4',
+  // IFC4.3 facility containers \u2014 same family as IfcBuilding (multi-storey
+  // spatial root) but `domain` carries the "campus / infrastructure
+  // facility" reading; IfcFacilityPart follows the storey-line icon for
+  // consistency. (Issue #860 \u2014 user reported no icon on IfcFacility.)
+  IfcFacility: '\ue7ee', // "domain"
+  IfcFacilityPart: '\ue8fe', // "layers" \u2014 mirrors IfcBuildingStorey
+  IfcBridge: '\uebbf', // "directions_railway" \u2014 civil bridge icon
+  IfcBridgePart: '\ue8fe',
+  IfcRoad: '\uebbe', // "route"
+  IfcRoadPart: '\ue8fe',
+  IfcRailway: '\ue570', // "train"
+  IfcRailwayPart: '\ue8fe',
+  IfcMarineFacility: '\ue532', // "directions_boat"
+  IfcMarineFacilityPart: '\ue8fe',
 
   // Structural
   IfcBeam: '\uf108',
@@ -80,6 +94,52 @@ export const IFC_ICON_CODEPOINTS: Record<string, string> = {
   IfcGeographicElement: '\uea99',
   IfcLinearElement: '\uebaa',
 
+  // IFC4.3 alignment / positioning. IfcAlignment shares the linear-element
+  // glyph because that's exactly what it is at the geometry level (a
+  // parameterised curve). IfcReferent is a station marker along that
+  // alignment (mileposts, kilometre posts) \u2014 pin glyph. IfcPositioningElement
+  // is the abstract base.
+  IfcAlignment: '\uebaa', // "polyline" / linear scale
+  IfcPositioningElement: '\ue55f', // "place"
+  IfcReferent: '\ue55f', // "place" \u2014 station marker
+
+  // IFC4.3 transportation signage & signals (rail/road). Same traffic-light
+  // glyph for both since the spec treats signals as the trackside subtype of
+  // signs.
+  IfcSign: '\ue9b2', // "traffic"
+  IfcSignal: '\ue9b2',
+
+  // IFC4.3 road / rail wearing surface. Pavement is the assembly, courses
+  // are its layers, kerbs sit at the edge.
+  IfcPavement: '\ue4f4', // "texture"
+  IfcCourse: '\ue8fe', // "layers"
+  IfcKerb: '\uf108', // "horizontal_rule"
+
+  // IFC4.3 earthworks. Cut/Fill share the geotechnical "terrain" glyph
+  // since they're shape-of-ground operations on the same domain.
+  IfcEarthworksElement: '\ue564',
+  IfcEarthworksFill: '\ue564',
+  IfcEarthworksCut: '\ue564',
+
+  // Geotechnical strata (IFC4.3) \u2014 issue #860. The abstract base plus the
+  // three concrete leaves (IfcSolidStratum / IfcVoidStratum / IfcWaterStratum)
+  // all share the `terrain` glyph. The geometry pipeline routes the leaves
+  // through IfcGeotechnicalStratum via legacy_entities.rs, so the icon map
+  // covers both the leaf names (when entries land in the spatial tree with
+  // their original type string) and the base.
+  IfcGeotechnicalAssembly: '\ue564',
+  IfcGeotechnicalElement: '\ue564',
+  IfcGeotechnicalStratum: '\ue564',
+  IfcSolidStratum: '\ue564',
+  IfcVoidStratum: '\ue564',
+  IfcWaterStratum: '\ue564',
+
+  // IFC4.3 marine / navigation / track / vehicle leaves.
+  IfcMooringDevice: '\uf1cd', // "anchor"
+  IfcNavigationElement: '\ue55d', // "navigation"
+  IfcTrackElement: '\ue260', // "linear_scale"
+  IfcVehicle: '\ue531', // "directions_car"
+
   // Proxy / generic fallback
   IfcProduct: '\ue047',
   IfcBuildingElementProxy: '\ue047',

package/src/components/viewer/useGeometryStreaming.ts

@@ -22,6 +22,13 @@ import { useEffect, useRef, type MutableRefObject } from 'react';
 import type { Renderer } from '@ifc-lite/renderer';
 import type { MeshData, CoordinateInfo } from '@ifc-lite/geometry';
 import { logToDesktopTerminal } from '@/services/desktop-logger';
+import { toast } from '../ui/toast.js';
+
+// Session-scoped flag so the linear-infrastructure hint fires at most once
+// per page load (model swaps included). Stored at module scope rather than
+// in component state because federation re-mounts the streaming hook on
+// every model load — a useRef wouldn't survive.
+let linearFitHintShown = false;
 
 export interface UseGeometryStreamingParams {
   rendererRef: MutableRefObject<Renderer | null>;
@@ -39,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;
@@ -88,6 +99,7 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     geometryContentVersion,
     coordinateInfo,
     isStreaming,
+    modelCount = 0,
     geometryBoundsRef,
     pendingMeshColorUpdates,
     pendingColorUpdates,
@@ -109,8 +121,13 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
   const cameraFittedRef = useRef(false);
   const finalBoundsRefittedRef = useRef(false);
   const cameraSnapshotRef = useRef<{ px: number; py: number; pz: number; tx: number; ty: number; tz: number } | null>(null);
+  // Tracks which fit branch the post-load auto-fit took. Linear models get a
+  // one-time status-line hint via the viewer store; the home button can also
+  // mirror the same policy on re-press without re-deriving the bbox shape.
+  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
@@ -189,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).
@@ -244,7 +275,24 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
         geometryBoundsRef.current = { ...DEFAULT_BOUNDS };
       }
     } else if (currentLength === lastLength) {
-      return; // No change
+      // No mesh-count change, so the queueMeshes / appendToBatches block
+      // below would be a no-op. But we MUST still reach the camera-fit
+      // block — the streaming-complete re-render (isStreaming flips
+      // false, geometry array length stays at the final mesh count)
+      // arrives here, and that's the FIRST render where path 2
+      // (`computeBounds(geometry)` fallback when shiftedBounds is empty)
+      // is allowed to fire. Pre-fix the early return short-circuited
+      // the camera fit entirely; the user reported 33 meshes streamed
+      // with the viewport stuck at the default ±100 m bounds (issue
+      // #859 / PR #871 deploy preview, `linear-placement-of-signal.ifc`).
+      //
+      // Skip only when the camera is already fitted or there's nothing
+      // to fit to.
+      if (cameraFittedRef.current || currentLength === 0) {
+        return;
+      }
+      // Otherwise fall through so the camera-fit block at the bottom of
+      // the effect gets a chance to run.
     }
 
     // Visibility toggle while NOT streaming — array rebuilt from scratch
@@ -302,31 +350,77 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
     lastGeometryLengthRef.current = currentLength;
 
     // ── Fit camera ──
-    if (!cameraFittedRef.current && coordinateInfo?.shiftedBounds) {
-      const sb = coordinateInfo.shiftedBounds;
-      const maxSize = Math.max(sb.max.x - sb.min.x, sb.max.y - sb.min.y, sb.max.z - sb.min.z);
-      if (maxSize > 0 && Number.isFinite(maxSize)) {
-        renderer.getCamera().fitToBounds(sb.min, sb.max);
-        geometryBoundsRef.current = { min: { ...sb.min }, max: { ...sb.max } };
-        cameraFittedRef.current = true;
-        const pos = renderer.getCamera().getPosition();
-        const tgt = renderer.getCamera().getTarget();
-        cameraSnapshotRef.current = { px: pos.x, py: pos.y, pz: pos.z, tx: tgt.x, ty: tgt.y, tz: tgt.z };
+    //
+    // Pre-#871 the branching here was structured as
+    //   if (coordinateInfo?.shiftedBounds) { try to fit }
+    //   else if (geometry.length > 0) { fall back }
+    // but `coordinateInfo.shiftedBounds` is ALWAYS truthy — the wasm
+    // bridge ships a default `{ min: 0, max: 0 }` placeholder before
+    // any real bounds get computed. The outer `if` therefore won
+    // every time, the inner `maxSize > 0` failed, and the `else if`
+    // fallback NEVER fired. Result: the camera stayed at the default
+    // (0, 0, 0) framing while linearly-placed railway geometry sat at
+    // its MGA-territory world coords (~330, 123 after RTC), invisible
+    // to the user. Compute the size first so the branch reflects
+    // whether the data is actually usable, not just whether the
+    // property exists.
+    if (!cameraFittedRef.current) {
+      // The adaptive fit picks an SE-isometric pose for compact models
+      // (today's behaviour) but switches to a side-on-along-the-alignment
+      // pose for high-aspect-ratio bboxes (railway / road corridors).
+      // Without the switch, a 932 × 0.75 × 428 m alignment auto-fits to a
+      // ~1864 m distance where every 1 m signal projects to a sub-pixel
+      // dot — the user sees a blank viewport even though geometry is in
+      // the scene. See packages/renderer/src/camera-fit-policy.ts.
+      let fitted = false;
+      const sb = coordinateInfo?.shiftedBounds;
+      if (sb) {
+        const maxSize = Math.max(sb.max.x - sb.min.x, sb.max.y - sb.min.y, sb.max.z - sb.min.z);
+        if (maxSize > 0 && Number.isFinite(maxSize)) {
+          const canvas = renderer.getCanvas();
+          const canvasShort = Math.min(canvas?.height ?? 0, canvas?.width ?? 0);
+          const policy = renderer.getCamera().fitBoundsAdaptive(
+            { min: sb.min, max: sb.max },
+            { viewportShortPx: canvasShort > 0 ? canvasShort : undefined },
+          );
+          geometryBoundsRef.current = { min: { ...sb.min }, max: { ...sb.max } };
+          lastFitPolicyKindRef.current = policy.kind;
+          fitted = true;
+        }
       }
-    } else if (!cameraFittedRef.current && geometry.length > 0 && !isStreaming) {
-      const bounds = computeBounds(geometry);
-      if (bounds) {
-        renderer.getCamera().fitToBounds(bounds.min, bounds.max);
-        geometryBoundsRef.current = bounds;
+      if (!fitted && geometry.length > 0 && !isStreaming) {
+        const bounds = computeBounds(geometry);
+        if (bounds) {
+          const canvas = renderer.getCanvas();
+          const canvasShort = Math.min(canvas?.height ?? 0, canvas?.width ?? 0);
+          const policy = renderer.getCamera().fitBoundsAdaptive(
+            bounds,
+            { viewportShortPx: canvasShort > 0 ? canvasShort : undefined },
+          );
+          geometryBoundsRef.current = bounds;
+          lastFitPolicyKindRef.current = policy.kind;
+          fitted = true;
+        }
+      }
+      if (fitted) {
         cameraFittedRef.current = true;
         const pos = renderer.getCamera().getPosition();
         const tgt = renderer.getCamera().getTarget();
         cameraSnapshotRef.current = { px: pos.x, py: pos.y, pz: pos.z, tx: tgt.x, ty: tgt.y, tz: tgt.z };
+        // One-time hint for linear-infrastructure models. The side-on auto-fit
+        // shows a slice of the alignment at a useful zoom — but the FULL
+        // alignment is much longer than what fits on screen, so users need
+        // to know to pan / use Frame Selection to inspect remote stations.
+        // Hint is module-scoped so model swaps within one session don't spam.
+        if (lastFitPolicyKindRef.current === 'linear' && !linearFitHintShown) {
+          linearFitHintShown = true;
+          toast.info('Linear infrastructure — pan along the alignment, or select an element and press F to zoom in');
+        }
       }
     }
 
     renderer.requestRender();
-  }, [geometry, geometryVersion, geometryContentVersion, coordinateInfo, isInitialized, isStreaming]);
+  }, [geometry, geometryVersion, geometryContentVersion, coordinateInfo, isInitialized, isStreaming, modelCount]);
 
   useEffect(() => {
     return () => {
@@ -363,14 +457,35 @@ export function useGeometryStreaming(params: UseGeometryStreamingParams): void {
             `finalize start geometryLength=${capturedGeometry?.length ?? 0} releaseAfterFinalize=${releaseGeometryAfterFinalize}`
           );
 
-          // Compute exact bounds and refit camera (fast ~15ms scan)
+          // Compute exact bounds and refit camera (fast ~15ms scan). Use
+          // the adaptive policy so linear-infrastructure models keep the
+          // side-on pose chosen by the early-fit branch — without this,
+          // the streaming-complete refit reverts to the legacy
+          // `fitToBounds` (SE isometric at `maxSize * 2`), undoing the
+          // useful close-in framing and putting the camera back at the
+          // sub-pixel distance for railway / road corridors.
           if (cameraFittedRef.current && !finalBoundsRefittedRef.current && capturedGeometry && capturedGeometry.length > 0) {
             const t0 = performance.now();
             const exactBounds = computeBounds(capturedGeometry);
             console.log(`[GeomStream] computeBounds: ${(performance.now() - t0).toFixed(0)}ms`);
             if (exactBounds) {
               if (!userMovedCamera(r, cameraSnapshotRef.current)) {
-                r.getCamera().fitToBounds(exactBounds.min, exactBounds.max);
+                const canvas = r.getCanvas();
+                const canvasShort = Math.min(canvas?.height ?? 0, canvas?.width ?? 0);
+                const policy = r.getCamera().fitBoundsAdaptive(
+                  exactBounds,
+                  { viewportShortPx: canvasShort > 0 ? canvasShort : undefined },
+                );
+                lastFitPolicyKindRef.current = policy.kind;
+                // Update the snapshot so a subsequent userMovedCamera check
+                // doesn't fire against the new pose's own delta.
+                const pos = r.getCamera().getPosition();
+                const tgt = r.getCamera().getTarget();
+                cameraSnapshotRef.current = { px: pos.x, py: pos.y, pz: pos.z, tx: tgt.x, ty: tgt.y, tz: tgt.z };
+                if (policy.kind === 'linear' && !linearFitHintShown) {
+                  linearFitHintShown = true;
+                  toast.info('Linear infrastructure — pan along the alignment, or select an element and press F to zoom in');
+                }
               }
               geometryBoundsRef.current = exactBounds;
               finalBoundsRefittedRef.current = true;

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

@@ -0,0 +1,61 @@
+/* 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 { resolveDataStoreOrAbort } from './resolveDataStoreOrAbort.js';
+
+const isAbortError = (err: unknown): boolean =>
+  err instanceof DOMException && err.name === 'AbortError';
+
+describe('resolveDataStoreOrAbort', () => {
+  it('returns the parse result when not aborted', async () => {
+    const store = { id: 'store' };
+    const result = await resolveDataStoreOrAbort(Promise.resolve(store), { aborted: false });
+    assert.equal(result, store);
+  });
+
+  it('throws AbortError and terminates without awaiting a blocked parse', async () => {
+    let terminated = false;
+    // A promise that never settles — mirrors a worker parse blocked on
+    // waitForEntityIndex after the geometry loop was cancelled. The previous
+    // code awaited this directly and hung forever.
+    const neverSettles = new Promise<unknown>(() => {});
+
+    await assert.rejects(
+      resolveDataStoreOrAbort(neverSettles, {
+        aborted: true,
+        terminate: () => {
+          terminated = true;
+        },
+      }),
+      isAbortError,
+    );
+
+    assert.equal(terminated, true, 'the worker parser should be terminated on abort');
+  });
+
+  it('swallows the abandoned parse rejection on abort', async () => {
+    // A parse that rejects after we bail must not surface as an unhandled
+    // rejection (this test would fail the process if the .catch guard were
+    // removed from resolveDataStoreOrAbort).
+    const rejecting = Promise.reject(new Error('worker died after abort'));
+
+    await assert.rejects(
+      resolveDataStoreOrAbort(rejecting, { aborted: true }),
+      isAbortError,
+    );
+
+    // Give the swallowed rejection a tick to settle.
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  });
+
+  it('works without a terminate callback', async () => {
+    await assert.rejects(
+      resolveDataStoreOrAbort(new Promise<unknown>(() => {}), { aborted: true }),
+      isAbortError,
+    );
+  });
+});

package/src/hooks/ingest/resolveDataStoreOrAbort.ts

@@ -0,0 +1,28 @@
+/* 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/. */
+
+/**
+ * Resolve a parse promise, unless the load was cancelled.
+ *
+ * A worker parse started with `waitForEntityIndex` blocks until the streaming
+ * geometry pre-pass hands over the entity index. If the geometry loop is
+ * cancelled before that handoff, the index never arrives and the parse promise
+ * never settles — awaiting it would hang the whole ingest. On abort we instead
+ * terminate the worker, abandon (and swallow) the parse promise, and throw an
+ * `AbortError` so callers treat it as a clean cancellation (matching the
+ * federated loader's `err.name === 'AbortError'` convention).
+ */
+export async function resolveDataStoreOrAbort<T>(
+  parsePromise: Promise<T>,
+  opts: { aborted: boolean; terminate?: () => void },
+): Promise<T> {
+  if (opts.aborted) {
+    opts.terminate?.();
+    // Swallow the abandoned parse's eventual rejection so it doesn't surface
+    // as an unhandled rejection after we've already bailed out.
+    void parsePromise.catch(() => {});
+    throw new DOMException('Model load aborted', 'AbortError');
+  }
+  return parsePromise;
+}

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);
+  }
+}