@ifc-lite/geometry 7.2.0 → 7.4.0

package/dist/geometry-parallel.js

@@ -1,6 +1,7 @@
 /* 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 { postGeometryWorkerInit } from './geometry-worker-init.js';
 import { mergeGeometryDiagnostics } from './diagnostics.js';
 import { computeWorkerCount } from './worker-count.js';
 import { notifyIfWasmAssetUnavailable, notifyIfWorkerScriptUnavailable } from './wasm-asset-error.js';
@@ -11,6 +12,8 @@ import { restashWasmPanicLocation } from './wasm-panic-forward.js';
 import { compileSharedWasmModule } from './wasm-shared-module.js';
 import { stitchShards } from './shard-stitch.js';
 import { resolveRtcFrame } from './rtc-frame.js';
+import { emptyStylesPrepassEvent, frozenStallPhase, GateTracker, PhaseBoundTimers, preWorkerPhaseFailureDiagnostics, } from './stall-phase.js';
+import { SkippedHungElementsCollector, startHungJobMonitor, WorkerJobLedger, } from './hung-job-recovery.js';
 /**
  * Prepass class-byte layout, mirroring the `PREPASS_CLASS_*` definitions in
  * `rust/processing/src/shard_classes.rs` (the source of truth — these are
@@ -160,6 +163,23 @@ function terminateWorkerQuietly(worker, label) {
         console.warn(`[stream] ${label} terminate failed:`, err);
     }
 }
+/**
+ * A recorded `set-entity-index` setup (#4884). Built OUTSIDE `deliverEntityIndex`
+ * on purpose: a replay closure created in that scope would keep the pre-pass's
+ * transferred id/start/length columns (12 B per entity, ~180 MB on a 1 GB file)
+ * alive for the whole load, where before they were collectable right after the
+ * copy into the shared buffers. This one captures only its `columns` factory.
+ */
+function entityIndexSetup(columns) {
+    return (w) => {
+        try {
+            w.postMessage({ type: 'set-entity-index', ...columns() });
+        }
+        catch (err) {
+            console.warn('[stream] set-entity-index dispatch failed:', err);
+        }
+    };
+}
 let nextSourceSessionId = 0;
 export async function* processParallel(buffer, coordinator, sharedRtcOffset, 
 /** Optional pre-allocated SAB the caller already shares with another worker. */
@@ -204,6 +224,13 @@ existingSab, options) {
             resolveWaiting = null;
         }
     };
+    // Which pre-worker gate is still open (#4902) — see stall-phase.ts.
+    const gateTracker = new GateTracker();
+    if (options?.stallPhaseHandle)
+        options.stallPhaseHandle.getStallPhase = () => gateTracker.getStallPhase();
+    // Bounded waits for those gates (#4902); cleared in the `finally` below so
+    // none outlives this load's teardown — see stall-phase.ts.
+    const phaseBoundTimers = new PhaseBoundTimers();
     // Pre-pass worker drives the entire pipeline via streaming events.
     let prepassMeta = null;
     let prepassJobsTotal = 0;
@@ -247,6 +274,10 @@ existingSab, options) {
     const shardResults = [];
     let shardResultsRemaining = 0;
     let shardScanDispatchedAt = -1;
+    // #4902: settles once, normally or via the bounded-wait timeout below.
+    let shardScanSettled = false;
+    let stylesSlicesSettled = false;
+    let finalizeSettled = false;
     const stylesSliceResults = [];
     let stylesSlicesRemaining = 0;
     // Support spans extracted from the shard classes (sharded mode only).
@@ -277,7 +308,11 @@ existingSab, options) {
         // crash from the worker SCRIPT failing to load (stale-deploy 404, #1251).
         let workerSpoke = false;
         worker.onmessage = (e) => {
+            // A worker replaced after a hang (#4884) may still flush queued messages.
+            if (workers[workerIndex] !== worker)
+                return;
             workerSpoke = true;
+            ledger.onHeard(workerIndex, performance.now());
             const msg = e.data;
             if (msg.type === 'ready') {
                 console.log(`[stream] worker[${workerIndex}] WASM ready @ ${elapsed()}ms`);
@@ -307,6 +342,10 @@ existingSab, options) {
                 return;
             }
             if (msg.type === 'styles-final') {
+                // A late reply after the #4902 finalize bound already drained with
+                // default colours must not reopen that gate.
+                if (finalizeSettled)
+                    return;
                 // Finalized styles payload from worker 0 — feed it through the SAME
                 // prepass styles-event path (gates, logging, distribution) by
                 // synthesizing a prepass-stream message. The handler is a plain
@@ -347,10 +386,19 @@ existingSab, options) {
                 // Forward it so the consumer's stall watchdog measures "one WASM
                 // call went silent", not "no meshes lately" — a CSG-heavy stretch
                 // can keep every worker busy past the watchdog with nothing to show.
+                if (typeof msg.seq === 'number') {
+                    ledger.onCallStart(workerIndex, msg.seq, msg.processedJobs, msg.callJobs ?? 1, performance.now());
+                }
+                if (msg.diagnostics)
+                    diagnostics = mergeGeometryDiagnostics(diagnostics, msg.diagnostics);
                 eventQueue.push({ type: 'progress', phase: 'workers' });
                 wake();
                 return;
             }
+            if (msg.type === 'slice-done') {
+                ledger.onSliceDone(workerIndex, msg.seq, performance.now());
+                return;
+            }
             if (msg.type === 'batch') {
                 if (firstBatchByWorker[workerIndex] === undefined) {
                     firstBatchByWorker[workerIndex] = elapsed();
@@ -444,6 +492,8 @@ existingSab, options) {
             }
         };
         worker.onerror = (err) => {
+            if (workers[workerIndex] !== worker)
+                return;
             // A hard worker crash (e.g. the wasm thread aborting under memory
             // pressure) fires an ErrorEvent with an empty `message`. Emitting the
             // literal "undefined" produced a cryptic, unclassifiable error in tracking
@@ -489,8 +539,25 @@ existingSab, options) {
         console.log('[stream] shared wasm module compiled once — workers initSync (no per-worker recompile)');
     }
     const workers = [];
+    // Hung-call recovery (#4884): unfinished slices per worker, and every per-load
+    // state message in order (never per-worker work) to rebuild a replacement.
+    // Opt-in: without a budget nothing is recorded, so the pool costs what it did.
+    const hungJobTimeoutMs = Math.max(0, options?.hungJobTimeoutMs ?? 0);
+    const ledger = new WorkerJobLedger(workerCount, performance.now(), hungJobTimeoutMs > 0);
+    // Always recorded (#4902 review): a pre-worker phase bound below may need
+    // to replace a worker regardless of whether #4884's in-call recovery is
+    // enabled, and replaying this log is how a replacement reaches the same
+    // state every other worker is in.
+    const workerSetup = [];
+    const broadcastSetup = (setup) => {
+        workerSetup.push(setup);
+        for (const w of workers)
+            setup(w);
+    };
+    const postInitMessages = (worker) => postGeometryWorkerInit(worker, options, sharedWasmModule);
+    workerSetup.push(postInitMessages);
     // This loop runs BEFORE the try/finally below (which owns teardown for the
-    // rest of the pipeline), so it needs its own: `postMessage` below can throw
+    // rest of the pipeline), so it needs its own: `postInitMessages` can throw
     // (e.g. a `wasmModule` structured-clone failure — the same class of error
     // `dispatchJobsChunkInternal` already guards against further down), and
     // without this try/catch any worker already pushed to `workers` before the
@@ -500,58 +567,7 @@ existingSab, options) {
             const worker = makeGeometryWorker();
             workers.push(worker);
             installWorkerHandlers(worker, i);
-            // Instantiate WASM. When the host compiled the module once (above), each
-            // worker `initSync`s it (cheap); otherwise it falls back to compiling from
-            // bytes. The worker's tail-promise serialiser guarantees this `init`
-            // completes before any subsequent `stream-start`/`stream-chunk` runs.
-            //
-            // `wasmUrl` is forwarded only when the consumer explicitly provided one AND
-            // no shared module is available — undefined leaves the worker on
-            // wasm-bindgen's default `import.meta.url`-based resolution (Vite + webpack).
-            const wasmUrlForWorker = options?.wasmUrls?.wasm;
-            worker.postMessage({
-                type: 'init',
-                ...(sharedWasmModule
-                    ? { wasmModule: sharedWasmModule }
-                    : wasmUrlForWorker
-                        ? { wasmUrl: wasmUrlForWorker }
-                        : {}),
-            });
-            // Issue #540: forward the user's "Merge Multilayer Walls" toggle
-            // BEFORE any stream-start so the worker's IfcAPI has the flag set
-            // before its first parse call. The tail-promise serialiser inside
-            // each worker preserves this order even though the messages are
-            // posted back-to-back. We always send the message so the controller
-            // path doesn't have to remember whether the host called it — the
-            // default `false` is a cheap no-op.
-            worker.postMessage({
-                type: 'set-merge-layers',
-                enabled: options?.mergeLayers === true,
-            });
-            // GPU-instancing partition toggle — default ON; the host sets false for federated
-            // loads so a federated model's geometry stays flat (instancing is primary-only).
-            worker.postMessage({
-                type: 'set-instancing-enabled',
-                enabled: options?.enableInstancing !== false,
-            });
-            // Issue #924: forward the geometry-hash tolerance the same way — always
-            // sent so the controller path stays uniform; null is a cheap no-op.
-            worker.postMessage({
-                type: 'set-compute-geometry-hashes',
-                tolerance: options?.geometryHashTolerance ?? null,
-            });
-            // Issue #976: forward the tessellation-quality level the same way —
-            // null keeps the Rust default (Medium / historical densities).
-            worker.postMessage({
-                type: 'set-tessellation-quality',
-                level: options?.tessellationQuality ?? null,
-            });
-            // Issue #1286: forward the small-cut skip the same way — always sent so a
-            // worker reused by a later export (which omits it) resets to false.
-            worker.postMessage({
-                type: 'set-skip-small-cuts',
-                enabled: options?.skipSmallCuts === true,
-            });
+            postInitMessages(worker);
         }
     }
     catch (err) {
@@ -559,6 +575,31 @@ existingSab, options) {
             terminateWorkerQuietly(w, 'process worker (init)');
         throw err;
     }
+    /**
+     * Terminate and replace pool worker `index` (#4902 review). A silent
+     * `scan-shard` / `resolve-styles-shard` / `finalize-styles` reply means
+     * that worker is wedged inside ONE synchronous WASM call —
+     * `geometry.worker.js` serializes every message behind its tail promise, so
+     * continuing the fallback without replacing it would queue the fallback's
+     * own `stream-start`/chunks/`stream-end` forever behind the stuck call, and
+     * `workersCompleted` would never reach `workers.length`. None of the three
+     * bounds fires after any `stream-chunk` has reached a worker (they all sit
+     * strictly before `dispatchJobsChunk`'s gate can open), so there is no
+     * in-flight slice to replay — replaying `workerSetup` alone brings the
+     * replacement to the same state every other worker is in.
+     */
+    function replacePreWorkerPhaseWorker(index, reason) {
+        const hung = workers[index];
+        const replacement = makeGeometryWorker();
+        workers[index] = replacement; // swap first — the stale-worker guard then drops anything the hung one flushes
+        terminateWorkerQuietly(hung, `process worker (${reason})`);
+        installWorkerHandlers(replacement, index);
+        for (const setup of workerSetup)
+            setup(replacement);
+        if (endSentToWorkers)
+            replacement.postMessage({ type: 'stream-end' });
+        console.warn(`[stream] worker[${index}] replaced: silent past its #4902 ${reason} bound`);
+    }
     const sendStreamEnd = () => {
         if (endSentToWorkers)
             return;
@@ -607,12 +648,13 @@ existingSab, options) {
         const emptyU32 = new Uint32Array(0);
         const emptyU8 = new Uint8Array(0);
         const batchSizing = options?.batchSizing ?? readBatchSizingOverride();
-        for (const worker of workers) {
+        const frameMeta = prepassMeta;
+        broadcastSetup((worker) => {
             worker.postMessage({
                 type: 'stream-start', sourceSessionId,
                 sharedBuffer,
-                unitScale: prepassMeta.unitScale,
-                planeAngleToRadians: prepassMeta.planeAngleToRadians,
+                unitScale: frameMeta.unitScale,
+                planeAngleToRadians: frameMeta.planeAngleToRadians,
                 rtcX, rtcY, rtcZ,
                 needsShift: effectiveNeedsShift,
                 voidKeys: emptyU32,
@@ -622,7 +664,7 @@ existingSab, options) {
                 styleColors: emptyU8,
                 ...(batchSizing ? { batchSizing } : {}),
             });
-        }
+        });
         // Don't drain queued chunks here — wait for the `styles` event so
         // every chunk gets processed with resolved colours. The styles
         // handler does the drain after posting set-styles.
@@ -649,9 +691,14 @@ existingSab, options) {
                 sub[o + 1] = jobs[src + 1];
                 sub[o + 2] = jobs[src + 2];
             }
-            workers[i].postMessage({ type: 'stream-chunk', jobsFlat: sub }, [sub.buffer]);
+            postChunk(i, sub);
         }
     }
+    /** Record a slice in the ledger, then transfer it to worker `i` (#4884). */
+    function postChunk(i, jobs, maxBatchJobs) {
+        const seq = ledger.recordDispatch(i, jobs, maxBatchJobs);
+        workers[i].postMessage({ type: 'stream-chunk', jobsFlat: jobs, seq, ...(maxBatchJobs !== undefined ? { maxBatchJobs } : {}) }, [jobs.buffer]);
+    }
     function dispatchJobsChunkInternal(jobs, affinity) {
         if (workers.length === 0 || jobs.length === 0)
             return;
@@ -681,7 +728,7 @@ existingSab, options) {
                     sub[j + 1] = jobs[src + 1];
                     sub[j + 2] = jobs[src + 2];
                 }
-                workers[i].postMessage({ type: 'stream-chunk', jobsFlat: sub }, [sub.buffer]);
+                postChunk(i, sub);
             }
         }
         catch (err) {
@@ -725,6 +772,15 @@ existingSab, options) {
             streamEndPendingQueueDrain = false;
             sendStreamEnd();
         }
+        // Every pre-worker gate is open, so no #4902 phase-bound timeout can still
+        // need `workerSetup` to replace a worker (each of the three settles at or
+        // before this point — see stall-phase.ts). With #4884 in-call recovery
+        // OFF, nothing else ever replays it either: release the closures (styles/
+        // prepass-columns retain the large prepass arrays) instead of holding them
+        // for the rest of the load. Recovery ON still needs the full log to bring
+        // a LATER in-call replacement up to date, so it is left alone.
+        if (!(hungJobTimeoutMs > 0))
+            workerSetup.length = 0;
     };
     // Step-by-step timing so we can tell exactly where time goes.
     const t0 = performance.now();
@@ -771,19 +827,9 @@ existingSab, options) {
                 new Uint32Array(sabStarts).set(starts);
                 new Uint32Array(sabLengths).set(lengths);
             }
-            for (const w of workers) {
-                try {
-                    w.postMessage({
-                        type: 'set-entity-index',
-                        ids: new Uint32Array(sabIds),
-                        starts: new Uint32Array(sabStarts),
-                        lengths: new Uint32Array(sabLengths),
-                    });
-                }
-                catch (err) {
-                    console.warn('[stream] set-entity-index dispatch failed:', err);
-                }
-            }
+            broadcastSetup(entityIndexSetup(() => ({
+                ids: new Uint32Array(sabIds), starts: new Uint32Array(sabStarts), lengths: new Uint32Array(sabLengths),
+            })));
             if (options?.onEntityIndex) {
                 try {
                     options.onEntityIndex(new Uint32Array(sabIds), new Uint32Array(sabStarts), new Uint32Array(sabLengths), oversizedIdCount, malformedRecordCount);
@@ -794,17 +840,10 @@ existingSab, options) {
             }
         }
         else {
-            for (const w of workers) {
-                try {
-                    w.postMessage({
-                        type: 'set-entity-index',
-                        ids: ids.slice(), starts: starts.slice(), lengths: lengths.slice(),
-                    });
-                }
-                catch (err) {
-                    console.warn('[stream] set-entity-index dispatch failed:', err);
-                }
-            }
+            const copyIds = ids, copyStarts = starts, copyLengths = lengths;
+            broadcastSetup(entityIndexSetup(() => ({
+                ids: copyIds.slice(), starts: copyStarts.slice(), lengths: copyLengths.slice(),
+            })));
             if (options?.onEntityIndex) {
                 try {
                     options.onEntityIndex(ids.slice(), starts.slice(), lengths.slice(), oversizedIdCount, malformedRecordCount);
@@ -815,6 +854,7 @@ existingSab, options) {
             }
         }
         entityIndexReceived = true;
+        gateTracker.markEntityIndexReceived();
         drainQueuedChunksIfReady();
     };
     /**
@@ -826,6 +866,11 @@ existingSab, options) {
      * the serial pre-pass path — identical to flag-off behaviour.
      */
     const onAllShardsReceived = () => {
+        // A late straggler shard result may land after the #4902 bound already fell back.
+        if (shardScanSettled)
+            return;
+        shardScanSettled = true;
+        gateTracker.markShardScanDone();
         const shards = shardResults;
         const stitched = stitchShards(shards);
         if (!stitched) {
@@ -880,6 +925,24 @@ existingSab, options) {
             const slice = styledSpans.slice(from, to);
             workers[i % workers.length].postMessage({ type: 'resolve-styles-shard', sourceSessionId, sharedBuffer, sliceIndex: i, spans: slice }, [slice.buffer]);
         }
+        // #4902 bound: a missing slice at the deadline is treated as empty
+        // (`onAllStyleSlicesReceived` already skips a `null` entry) — see stall-phase.ts.
+        phaseBoundTimers.arm(fileSizeMB, () => stylesSlicesSettled, () => {
+            console.warn(`[stream][shard] ${stylesSlicesRemaining}/${sliceCount} style slice(s) silent — proceeding with the slices that answered (#4902)`);
+            diagnostics = mergeGeometryDiagnostics(diagnostics, preWorkerPhaseFailureDiagnostics('style-slice-timeout'));
+            // Replace every worker owning a still-silent slice BEFORE continuing —
+            // same reasoning as the shard-scan bound above: `resolve-styles-shard`
+            // is synchronous WASM work on that worker's own FIFO queue.
+            const hungWorkers = new Set();
+            for (let i = 0; i < sliceCount; i++) {
+                if (!stylesSliceResults[i])
+                    hungWorkers.add(i % workers.length);
+            }
+            for (const idx of hungWorkers)
+                replacePreWorkerPhaseWorker(idx, 'style-slice-timeout');
+            stylesSlicesRemaining = 0;
+            onAllStyleSlicesReceived();
+        });
         // Start the sharded pre-pass with the stitched index columns + classes
         // (stage 2: the pre-pass discovers jobs/spans from the class column and
         // never byte-scans the file).
@@ -895,6 +958,10 @@ existingSab, options) {
      * canonical flatten emits the styles event through the same channel.
      */
     const onAllStyleSlicesReceived = () => {
+        // A late straggler slice may land after the #4902 bound already merged.
+        if (stylesSlicesSettled)
+            return;
+        stylesSlicesSettled = true;
         const orphan = new Map(); // id -> base float index (slice,i)
         const geom = new Map();
         // First pass: count winners to size the merged columns.
@@ -959,6 +1026,18 @@ existingSab, options) {
             planeAngleToRadians: prepassMeta.planeAngleToRadians ?? 1,
         }, [m.orphanIds.buffer, m.orphanColors.buffer, m.geomIds.buffer, m.geomColors.buffer]);
         console.log(`[stream][shard] styles finalize dispatched to worker[0] @ ${elapsed()}ms`);
+        // #4902 bound: replay the empty-styles event (stall-phase.ts) so every
+        // held chunk drains with default colours instead of never draining.
+        phaseBoundTimers.arm(fileSizeMB, () => finalizeSettled, () => {
+            finalizeSettled = true;
+            console.warn('[stream][shard] styles finalize silent — draining with default colours (#4902)');
+            diagnostics = mergeGeometryDiagnostics(diagnostics, preWorkerPhaseFailureDiagnostics('styles-finalize-timeout'));
+            // worker[0] is the sole target of `finalize-styles`; replace it before
+            // the fallback drains chunks, or its still-wedged FIFO queue would
+            // never consume the `stream-chunk`/`stream-end` the drain sends it.
+            replacePreWorkerPhaseWorker(0, 'styles-finalize-timeout');
+            prepassWorker.onmessage({ data: emptyStylesPrepassEvent() });
+        });
     };
     // SPIKE: kick off the shard scans on the idle workers NOW (before the pre-pass
     // worker's single scan). Gated: flag on, SAB available, file big enough, ≥2
@@ -974,6 +1053,7 @@ existingSab, options) {
         shardResults.length = n;
         shardResultsRemaining = n;
         shardScanDispatchedAt = elapsed();
+        gateTracker.markShardScanStarted();
         console.log(`[stream][shard] dispatching ${n} shard scans over ${(len / (1024 * 1024)).toFixed(1)}MB @ ${shardScanDispatchedAt}ms`);
         for (let i = 0; i < n; i++) {
             const rangeStart = Math.floor((i * len) / n);
@@ -986,6 +1066,23 @@ existingSab, options) {
                 rangeEnd,
             });
         }
+        // #4902 bound: falls back to the serial pre-pass, same as an unresolved
+        // stitch (`onAllShardsReceived`'s `!stitched` branch) — see stall-phase.ts.
+        phaseBoundTimers.arm(fileSizeMB, () => shardScanSettled, () => {
+            shardScanSettled = true;
+            gateTracker.markShardScanDone();
+            console.warn(`[stream][shard] ${shardResultsRemaining}/${n} shard scan(s) silent — falling back to the serial pre-pass (#4902)`);
+            diagnostics = mergeGeometryDiagnostics(diagnostics, preWorkerPhaseFailureDiagnostics('shard-scan-timeout'));
+            // Replace every worker still silent on scan-shard BEFORE continuing:
+            // `scan-shard` is a synchronous WASM call, so a missing reply means
+            // that worker is wedged, not just slow — and the fallback's own
+            // stream-start/chunks/stream-end would queue forever behind it.
+            for (let i = 0; i < n; i++) {
+                if (!shardResults[i])
+                    replacePreWorkerPhaseWorker(i, 'shard-scan-timeout');
+            }
+            startPrepass(false);
+        });
     }
     const prepassWorker = makePrepassWorker();
     // Wrap the rest of the pipeline so worker teardown runs not only on
@@ -994,7 +1091,32 @@ existingSab, options) {
     // is suspended at a `yield` or the `resolveWaiting` await. The viewer's
     // `watchedGeometryStream` relies on this `finally` to tear down workers
     // on break / abort / watchdog (see boundedIteratorReturn). The existing
+    // Abandonment and hung-call recovery (#4884). `return()` cannot reach this
+    // `finally` while the loop is parked on a silent worker, so a stalled load
+    // leaked its pool (hung worker included) into the retry: abort terminates it.
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+        for (const w of workers)
+            terminateWorkerQuietly(w, 'process worker (abort)');
+        terminateWorkerQuietly(prepassWorker, 'pre-pass worker (abort)');
+        wake();
+    };
+    const skippedHungElements = new SkippedHungElementsCollector();
+    let stopHungJobMonitor = () => { };
     try {
+        if (options?.signal?.aborted)
+            onAbort();
+        else
+            options?.signal?.addEventListener('abort', onAbort, { once: true });
+        stopHungJobMonitor = startHungJobMonitor({
+            workers, ledger, makeWorker: makeGeometryWorker, installHandlers: installWorkerHandlers,
+            setup: workerSetup, postChunk, streamEndSent: () => endSentToWorkers,
+            terminate: terminateWorkerQuietly, source: new Uint8Array(sharedBuffer), skipped: skippedHungElements,
+            isLive: () => !aborted && !workerError && !prepassError,
+            onLiveness: () => { eventQueue.push({ type: 'progress', phase: 'workers' }); wake(); },
+            onFailed: (error) => { workerError ??= error; wake(); },
+        }, hungJobTimeoutMs);
         // Forward the consumer-supplied wasm URL to the pre-pass worker so it
         // doesn't fall back to wasm-bindgen's `import.meta.url` default. The
         // pre-pass worker uses the same `geometry.worker.js` bundle and the
@@ -1073,7 +1195,7 @@ existingSab, options) {
                     const materialColorCounts = evt.materialColorCounts ?? new Uint32Array(0);
                     const materialColors = evt.materialColors ?? new Uint8Array(0);
                     console.log(`[stream] styles @ ${elapsed()}ms (${styleIds.length} styled, ${voidKeys.length} void hosts), draining ${queuedChunks.length} queued chunks`);
-                    for (const w of workers) {
+                    broadcastSetup((w) => {
                         // Slice each typed array per-worker so each can be in its own
                         // transfer list without conflict. The slice cost is bounded by
                         // `styleIds.length * 4` bytes — under 1 MB for ~250K styles.
@@ -1104,8 +1226,10 @@ existingSab, options) {
                         catch (err) {
                             console.warn('[stream] set-styles dispatch failed:', err);
                         }
-                    }
+                    });
                     stylesReceived = true;
+                    finalizeSettled = true; // reached via the real path — the #4902 bound is moot now
+                    gateTracker.markStylesReceived();
                     // Drain only when ALL gates are open (entity-index too). The
                     // worker's tail-promise serialiser ensures any set-* runs
                     // before any subsequent stream-chunk.
@@ -1154,7 +1278,7 @@ existingSab, options) {
                     const mliLayerMaterialIds = evt.mliLayerMaterialIds;
                     const mliLayerThicknesses = evt.mliLayerThicknesses;
                     console.log(`[stream] prepass-columns @ ${elapsed()}ms (${referencedRepmaps.length} repmaps, ${instantiatedTypeIds.length} inst-types, ${mliElementIds.length} layer-elems)`);
-                    for (const w of workers) {
+                    broadcastSetup((w) => {
                         try {
                             const rRepmaps = referencedRepmaps.slice();
                             const rTypeIds = instantiatedTypeIds.slice();
@@ -1186,7 +1310,7 @@ existingSab, options) {
                         catch (err) {
                             console.warn('[stream] set-prepass-columns dispatch failed:', err);
                         }
-                    }
+                    });
                     // Not a dispatch gate (see dispatchJobsChunk); the pre-pass emits this
                     // before the first jobs chunk, so drain here only for symmetry with the
                     // other post-scan events in case chunks were queued behind styles/index.
@@ -1252,6 +1376,7 @@ existingSab, options) {
         // After we see the Rust `complete` event we can sendStreamEnd.
         const onPrepassComplete = () => {
             prepassDone = true;
+            gateTracker.markPrepassDone();
             // Only signal stream-end to workers if they actually got
             // stream-start (which gates on `meta`). Zero-geometry files
             // never trigger meta → workers never start → no stream-end
@@ -1342,9 +1467,13 @@ existingSab, options) {
         //   b) all workers reported `complete`
         let prepassCompleteSeen = false;
         while (true) {
+            if (aborted)
+                return;
             while (eventQueue.length > 0) {
                 yield eventQueue.shift();
             }
+            if (aborted)
+                return;
             if (workerError) {
                 for (const w of workers) {
                     terminateWorkerQuietly(w, 'process worker');
@@ -1391,14 +1520,26 @@ existingSab, options) {
                 `${loadDiagnostics.productsWithFailures} product(s) this load - see ` +
                 `diagnostics.failuresByReason; not every reason leaves an opening/void uncut`);
         }
+        const skippedReport = skippedHungElements.report();
         yield {
             type: 'complete',
             totalMeshes,
             coordinateInfo,
             ...(loadDiagnostics ? { diagnostics: loadDiagnostics } : {}),
+            ...(skippedReport ? { skippedHungElements: skippedReport } : {}),
         };
     }
     finally {
+        phaseBoundTimers.clearAll();
+        // Re-seat the caller's handle to a frozen snapshot (#4979 review): the
+        // live reader closes over `gateTracker`, and transitively this whole
+        // generator's scope (including `sharedBuffer`) — the caller may still
+        // hold the handle long after this teardown runs.
+        if (options?.stallPhaseHandle) {
+            options.stallPhaseHandle.getStallPhase = frozenStallPhase(gateTracker.getStallPhase());
+        }
+        stopHungJobMonitor();
+        options?.signal?.removeEventListener('abort', onAbort);
         for (const w of workers) {
             terminateWorkerQuietly(w, 'process worker');
         }