@ifc-lite/geometry 1.17.0 → 1.18.2

package/dist/geometry-parallel.js

@@ -1,106 +1,106 @@
 /* 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/. */
-/**
- * Run the full pre-pass in a dedicated worker, then fan geometry jobs
- * out to N workers and yield batches as they complete.
- *
- * @param buffer       Raw IFC file bytes
- * @param coordinator  CoordinateHandler used to accumulate bounds
- */
-export async function* processParallel(buffer, coordinator, sharedRtcOffset) {
+import { pickWorkerCount } from './worker-count.js';
+export async function* processParallel(buffer, coordinator, sharedRtcOffset, 
+/** Optional pre-allocated SAB the caller already shares with another worker. */
+existingSab, options) {
     coordinator.reset();
     yield { type: 'start', totalEstimate: buffer.length / 1000 };
     yield { type: 'model-open', modelID: 0 };
-    // Copy file bytes into SharedArrayBuffer for zero-copy sharing with workers
-    const sharedBuffer = new SharedArrayBuffer(buffer.byteLength);
-    new Uint8Array(sharedBuffer).set(buffer);
-    // ── PHASE 1: Full pre-pass in worker ──
-    const makeWorker = () => new Worker(new URL('./geometry.worker.ts', import.meta.url), { type: 'module' });
-    const prePassResult = await new Promise((resolve, reject) => {
-        const w = makeWorker();
-        w.onmessage = (e) => {
-            if (e.data.type === 'prepass-result') {
-                w.terminate();
-                resolve(e.data.result);
-            }
-            else if (e.data.type === 'error') {
-                w.terminate();
-                reject(new Error(e.data.message));
-            }
-        };
-        w.onerror = (e) => { w.terminate(); reject(new Error(e.message)); };
-        w.postMessage({ type: 'prepass', sharedBuffer });
-    });
-    if (!prePassResult || !prePassResult.jobs || prePassResult.totalJobs === 0) {
-        const coordinateInfo = coordinator.getFinalCoordinateInfo();
-        yield { type: 'complete', totalMeshes: 0, coordinateInfo };
-        return;
-    }
-    const { jobs: jobsFlat, totalJobs, unitScale, rtcOffset, needsShift, voidKeys, voidCounts, voidValues, styleIds, styleColors } = prePassResult;
-    // When a shared RTC offset is provided (2nd+ federated model), use it
-    // instead of the per-model RTC. This ensures all models share the same
-    // coordinate origin, giving pixel-perfect federation alignment.
-    const useSharedRtc = sharedRtcOffset != null;
-    const rtcX = useSharedRtc ? sharedRtcOffset.x : (rtcOffset?.[0] ?? 0);
-    const rtcY = useSharedRtc ? sharedRtcOffset.y : (rtcOffset?.[1] ?? 0);
-    const rtcZ = useSharedRtc ? sharedRtcOffset.z : (rtcOffset?.[2] ?? 0);
-    const effectiveNeedsShift = useSharedRtc ? true : needsShift;
-    yield {
-        type: 'rtcOffset',
-        rtcOffset: { x: rtcX, y: rtcY, z: rtcZ },
-        hasRtc: effectiveNeedsShift,
-    };
-    // ── PHASE 2: Dynamic worker provisioning based on device capability ──
-    const cores = typeof navigator !== 'undefined' ? (navigator.hardwareConcurrency ?? 2) : 2;
-    const deviceMemoryGB = typeof navigator !== 'undefined' ? (navigator.deviceMemory ?? 8) : 8;
-    const fileSizeGB = buffer.byteLength / (1024 * 1024 * 1024);
-    // Determine optimal workers:
-    // - Desktop (16+ cores, 16+ GB): up to 8 workers
-    // - Laptop (8 cores, 8 GB): 2-4 workers (avoid thermal throttling on fanless)
-    // - Low-end (4 cores, 4 GB): 1-2 workers
-    // - Large files need more memory per worker, so fewer workers
-    let maxWorkers;
-    if (cores >= 16 && deviceMemoryGB >= 16) {
-        maxWorkers = Math.min(8, Math.floor(cores / 2));
+    // SAB sharing — see Tier-1 / fix-RAM history. Three paths:
+    //   1. Caller-supplied SAB.
+    //   2. Input `buffer` already views a SAB.
+    //   3. Allocate fresh SAB and copy.
+    let sharedBuffer;
+    const inputBuffer = buffer.buffer;
+    if (existingSab && existingSab.byteLength === buffer.byteLength) {
+        sharedBuffer = existingSab;
     }
-    else if (cores >= 8 && deviceMemoryGB >= 8) {
-        // MacBook Air M-series: 8 cores but fanless → throttles with too many workers
-        // Use 3 workers: enough parallelism without severe throttling
-        maxWorkers = fileSizeGB > 0.5 ? 2 : 3;
+    else if (typeof SharedArrayBuffer !== 'undefined'
+        && inputBuffer instanceof SharedArrayBuffer
+        && buffer.byteOffset === 0
+        && buffer.byteLength === inputBuffer.byteLength) {
+        sharedBuffer = inputBuffer;
     }
     else {
-        maxWorkers = Math.max(1, Math.min(2, Math.floor(cores / 2)));
+        sharedBuffer = new SharedArrayBuffer(buffer.byteLength);
+        new Uint8Array(sharedBuffer).set(buffer);
     }
-    const workerCount = Math.min(maxWorkers, totalJobs);
-    const jobsPerWorker = Math.ceil(totalJobs / workerCount);
-    const chunks = [];
-    for (let i = 0; i < workerCount; i++) {
-        const start = i * jobsPerWorker;
-        const end = Math.min(start + jobsPerWorker, totalJobs);
-        if (start < end)
-            chunks.push([start, end]);
-    }
-    // Queue-based async generator: workers push batches, generator yields them
-    const batchQueue = [];
+    // Phase 2 controller path: ONE worker that does internal rayon
+    // parallelism, instead of N independent WASM-instance workers. The
+    // controller imports the threaded bundle (`@ifc-lite/wasm-threaded`)
+    // and calls processGeometryBatchParallel for each stream-chunk.
+    //
+    // The PRE-PASS worker always stays on the legacy bundle —
+    // `geometry.worker.js` handles `prepass-streaming` messages; the
+    // controller does not. The legacy bundle is also slimmer (no
+    // wasm-bindgen-rayon snippets) so the pre-pass pays no atomics tax.
+    const useController = options?.useSingleController === true;
+    const makeGeometryWorker = () => useController
+        ? new Worker(new URL('./geometry-controller.worker.js', import.meta.url), { type: 'module' })
+        : new Worker(new URL('./geometry.worker.js', import.meta.url), { type: 'module' });
+    const makePrepassWorker = () => new Worker(new URL('./geometry.worker.js', import.meta.url), { type: 'module' });
+    // Shared aggregator state used by every worker callback below.
+    const eventQueue = [];
     let resolveWaiting = null;
+    const wake = () => {
+        if (resolveWaiting) {
+            resolveWaiting();
+            resolveWaiting = null;
+        }
+    };
+    // Pre-pass worker drives the entire pipeline via streaming events.
+    let prepassMeta = null;
+    let prepassJobsTotal = 0;
+    let prepassDone = false;
+    let prepassError = null;
+    // Process-worker pool — spawned UP FRONT so their WASM modules compile
+    // in parallel with the pre-pass scan. By the time `meta` arrives the
+    // workers are usually hot and the first chunk's processing time is
+    // dominated by actual geometry work, not WASM startup.
+    let workerError = null;
     let workersCompleted = 0;
     let totalMeshes = 0;
-    let workerError = null;
-    const workers = [];
-    for (let i = 0; i < chunks.length; i++) {
-        const [jobStart, jobEnd] = chunks[i];
-        if (jobStart >= jobEnd) {
-            workersCompleted++;
-            continue;
-        }
-        const workerJobs = jobsFlat.slice(jobStart * 3, jobEnd * 3);
-        const worker = new Worker(new URL('./geometry.worker.ts', import.meta.url), { type: 'module' });
-        workers.push(worker);
+    let endSentToWorkers = false;
+    let streamStartSentToWorkers = false;
+    /**
+     * Chunks held until BOTH `meta` (workers spawned + initialised) AND
+     * `styles` (resolved colours from the pre-pass) have arrived. Workers
+     * process every chunk with non-empty styles, giving uniform colours
+     * across the entire stream — early chunks that were previously
+     * processed with empty styles + retroactive colorUpdate didn't recolour
+     * geometry-style meshes (geometry-IDs don't match the host's
+     * mesh.expressId; only element-material colours did).
+     */
+    const queuedChunks = [];
+    let stylesReceived = false;
+    let entityIndexReceived = false;
+    // Per-worker first-batch timestamps (filled lazily so we don't need
+    // workerCount at this point). The closure indexes by workerIndex.
+    const firstBatchByWorker = [];
+    const installWorkerHandlers = (worker, workerIndex) => {
         worker.onmessage = (e) => {
             const msg = e.data;
+            if (msg.type === 'ready') {
+                console.log(`[stream] worker[${workerIndex}] WASM ready @ ${elapsed()}ms`);
+                return;
+            }
+            if (msg.type === 'memory') {
+                eventQueue.push({
+                    type: 'workerMemory',
+                    workerIndex,
+                    wasmHeapBytes: msg.wasmHeapBytes,
+                    meshBytes: msg.meshBytes,
+                });
+                wake();
+                return;
+            }
             if (msg.type === 'batch') {
-                // Convert transferable data back to MeshData[]
+                if (firstBatchByWorker[workerIndex] === undefined) {
+                    firstBatchByWorker[workerIndex] = elapsed();
+                    console.log(`[stream] worker[${workerIndex}] first batch @ ${elapsed()}ms (${msg.meshes?.length ?? 0} meshes)`);
+                }
                 const meshes = msg.meshes.map((m) => ({
                     expressId: m.expressId,
                     ifcType: m.ifcType,
@@ -110,82 +110,455 @@ export async function* processParallel(buffer, coordinator, sharedRtcOffset) {
                     color: m.color,
                 }));
                 if (meshes.length > 0) {
-                    batchQueue.push(meshes);
-                    if (resolveWaiting) {
-                        resolveWaiting();
-                        resolveWaiting = null;
-                    }
+                    // Update totalMeshes per batch so consumers see a live
+                    // running count via `totalSoFar`. The `complete` event
+                    // below used to be the only updater, leaving streamed
+                    // batches reporting a stale total until the worker exited.
+                    totalMeshes += meshes.length;
+                    coordinator.processMeshesIncremental(meshes);
+                    const coordinateInfo = coordinator.getCurrentCoordinateInfo();
+                    eventQueue.push({
+                        type: 'batch',
+                        meshes,
+                        totalSoFar: totalMeshes,
+                        coordinateInfo: coordinateInfo || undefined,
+                    });
+                    wake();
                 }
+                return;
             }
-            else if (msg.type === 'complete') {
-                totalMeshes += msg.totalMeshes;
+            if (msg.type === 'complete') {
+                // Don't add msg.totalMeshes here — batches above already
+                // updated `totalMeshes += meshes.length` per batch, so the
+                // running sum is already correct. msg.totalMeshes is the
+                // worker's per-session count; if it disagrees with the sum
+                // of batch lengths we observed, a batch was lost — log but
+                // trust our observed count to keep totalSoFar consistent
+                // with what consumers actually rendered.
                 workersCompleted++;
                 worker.terminate();
-                if (resolveWaiting) {
-                    resolveWaiting();
-                    resolveWaiting = null;
-                }
+                wake();
+                return;
             }
-            else if (msg.type === 'error') {
+            if (msg.type === 'error') {
                 workerError = new Error(`Geometry worker error: ${msg.message}`);
                 workersCompleted++;
                 worker.terminate();
-                if (resolveWaiting) {
-                    resolveWaiting();
-                    resolveWaiting = null;
-                }
+                wake();
+                return;
             }
         };
-        worker.onerror = (e) => {
-            workerError = new Error(`Geometry worker failed: ${e.message}`);
+        worker.onerror = (err) => {
+            workerError = new Error(`Geometry worker failed: ${err.message}`);
             workersCompleted++;
             worker.terminate();
-            if (resolveWaiting) {
-                resolveWaiting();
-                resolveWaiting = null;
-            }
+            wake();
         };
-        // Send work — sharedBuffer is zero-copy, typed arrays are transferred
+    };
+    // Pick worker count and pre-spawn them now. `pickWorkerCount` needs a
+    // totalJobs estimate; use file-size proxy. The memory-budget cap in
+    // `pickWorkerCount` keeps an over-estimate harmless.
+    const cores = typeof navigator !== 'undefined' ? (navigator.hardwareConcurrency ?? 2) : 2;
+    const deviceMemoryGB = typeof navigator !== 'undefined'
+        ? (navigator.deviceMemory ?? 8) : 8;
+    const fileSizeMB = buffer.byteLength / (1024 * 1024);
+    const estimatedJobs = Math.max(1, Math.ceil(fileSizeMB * 100));
+    // Controller path: ONE worker. The worker spins up (cores - 1) rayon
+    // helpers internally; pickWorkerCount's per-worker budget no longer
+    // applies because we hold ONE WASM heap, not N. N-worker path
+    // unchanged.
+    const workerCount = useController
+        ? 1
+        : pickWorkerCount({ fileSizeMB, cores, deviceMemoryGB, totalJobs: estimatedJobs });
+    const workers = [];
+    for (let i = 0; i < workerCount; i++) {
+        const worker = makeGeometryWorker();
+        workers.push(worker);
+        installWorkerHandlers(worker, i);
+        // Kick off WASM compile concurrently with the pre-pass scan. The
+        // worker's tail-promise serialiser guarantees this `init` completes
+        // before any subsequent `stream-start`/`stream-chunk` runs.
+        worker.postMessage({ type: 'init' });
+        // 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: 'process',
-            sharedBuffer,
-            jobsFlat: workerJobs,
-            unitScale,
-            rtcX, rtcY, rtcZ,
-            needsShift: effectiveNeedsShift,
-            voidKeys, voidCounts, voidValues,
-            styleIds, styleColors,
+            type: 'set-merge-layers',
+            enabled: options?.mergeLayers === true,
+        });
+    }
+    const sendStreamEnd = () => {
+        if (endSentToWorkers)
+            return;
+        endSentToWorkers = true;
+        for (const w of workers) {
+            try {
+                w.postMessage({ type: 'stream-end' });
+            }
+            catch { /* worker terminated already — safe to ignore */ }
+        }
+    };
+    const sendStreamStartIfReady = () => {
+        if (streamStartSentToWorkers || !prepassMeta)
+            return;
+        streamStartSentToWorkers = true;
+        const useSharedRtc = sharedRtcOffset != null;
+        const rtcX = useSharedRtc ? sharedRtcOffset.x : prepassMeta.rtcOffset[0];
+        const rtcY = useSharedRtc ? sharedRtcOffset.y : prepassMeta.rtcOffset[1];
+        const rtcZ = useSharedRtc ? sharedRtcOffset.z : prepassMeta.rtcOffset[2];
+        const effectiveNeedsShift = useSharedRtc ? true : prepassMeta.needsShift;
+        eventQueue.push({
+            type: 'rtcOffset',
+            rtcOffset: { x: rtcX, y: rtcY, z: rtcZ },
+            hasRtc: effectiveNeedsShift,
         });
+        wake();
+        const emptyU32 = new Uint32Array(0);
+        const emptyU8 = new Uint8Array(0);
+        for (const worker of workers) {
+            worker.postMessage({
+                type: 'stream-start',
+                sharedBuffer,
+                unitScale: prepassMeta.unitScale,
+                rtcX, rtcY, rtcZ,
+                needsShift: effectiveNeedsShift,
+                voidKeys: emptyU32,
+                voidCounts: emptyU32,
+                voidValues: emptyU32,
+                styleIds: emptyU32,
+                styleColors: emptyU8,
+            });
+        }
+        // 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.
+    };
+    function dispatchJobsChunkInternal(jobs) {
+        if (workers.length === 0 || jobs.length === 0)
+            return;
+        // Round-robin sending whole chunks to single workers leaves N-1
+        // workers idle whenever the chunk count is small. Instead split each
+        // Rust chunk evenly across all workers so every worker processes a
+        // slice of every chunk in parallel — full pool utilisation from the
+        // very first chunk.
+        const totalSubJobs = Math.floor(jobs.length / 3);
+        if (totalSubJobs === 0)
+            return;
+        const subPerWorker = Math.ceil(totalSubJobs / workers.length);
+        try {
+            for (let i = 0; i < workers.length; i++) {
+                const start = i * subPerWorker * 3;
+                const end = Math.min(start + subPerWorker * 3, jobs.length);
+                if (start >= end)
+                    continue;
+                // `slice` allocates a new ArrayBuffer per piece so each can be in
+                // its own transfer list. Cheap relative to the WASM work that follows.
+                const sub = jobs.slice(start, end);
+                workers[i].postMessage({ type: 'stream-chunk', jobsFlat: sub }, [sub.buffer]);
+            }
+        }
+        catch (err) {
+            workerError = new Error(`Failed to dispatch jobs chunk: ${err instanceof Error ? err.message : String(err)}`);
+            wake();
+        }
     }
-    // Yield batches as they arrive from any worker
+    const dispatchJobsChunk = (jobs) => {
+        if (!streamStartSentToWorkers || !stylesReceived || !entityIndexReceived) {
+            // Hold until stream-start AND styles AND entity-index have all
+            // been posted to workers. Without styles the meshes would render
+            // with default per-type colours; without the pre-built entity
+            // index, the worker's first WASM call would re-scan the file
+            // (~5 s on 1 GB) to rebuild the index inside Rust.
+            queuedChunks.push(jobs);
+            return;
+        }
+        dispatchJobsChunkInternal(jobs);
+    };
+    /** Drain queued chunks once all gating conditions are met. */
+    const drainQueuedChunksIfReady = () => {
+        if (!streamStartSentToWorkers || !stylesReceived || !entityIndexReceived)
+            return;
+        while (queuedChunks.length > 0) {
+            dispatchJobsChunkInternal(queuedChunks.shift());
+        }
+    };
+    // Step-by-step timing so we can tell exactly where time goes.
+    const t0 = performance.now();
+    const elapsed = () => Math.round(performance.now() - t0);
+    console.log(`[stream] processParallel start, fileSizeMB=${fileSizeMB.toFixed(1)} workerCount=${workerCount}`);
+    const prepassWorker = makePrepassWorker();
+    let chunkArrivals = 0;
+    let totalDispatchedJobs = 0;
+    let firstChunkAt = -1;
+    prepassWorker.onmessage = (e) => {
+        const data = e.data;
+        if (data.type === 'prepass-progress') {
+            eventQueue.push({ type: 'progress', phase: 'prepass' });
+            wake();
+            return;
+        }
+        if (data.type === 'prepass-stream') {
+            const evt = data.event;
+            if (evt.type === 'meta') {
+                prepassMeta = {
+                    unitScale: evt.unitScale,
+                    rtcOffset: evt.rtcOffset,
+                    needsShift: evt.needsShift,
+                    buildingRotation: evt.buildingRotation ?? null,
+                };
+                console.log(`[stream] meta @ ${elapsed()}ms unitScale=${prepassMeta.unitScale} rtc=[${(prepassMeta.rtcOffset[0]).toFixed(0)},${(prepassMeta.rtcOffset[1]).toFixed(0)},${(prepassMeta.rtcOffset[2]).toFixed(0)}]`);
+                sendStreamStartIfReady();
+                wake();
+            }
+            else if (evt.type === 'jobs') {
+                const jobsArr = evt.jobs;
+                const jobCount = Math.floor(jobsArr.length / 3);
+                chunkArrivals++;
+                totalDispatchedJobs += jobCount;
+                if (firstChunkAt < 0) {
+                    firstChunkAt = elapsed();
+                    console.log(`[stream] first jobs chunk @ ${firstChunkAt}ms (${jobCount} jobs)`);
+                }
+                if (chunkArrivals % 10 === 1 || jobCount < 1000) {
+                    console.log(`[stream] chunk #${chunkArrivals} @ ${elapsed()}ms (+${jobCount} jobs, total ${totalDispatchedJobs})`);
+                }
+                dispatchJobsChunk(jobsArr);
+            }
+            else if (evt.type === 'styles') {
+                // Streaming pre-pass resolved styles + voids after its main scan.
+                // Push them into every worker, then drain any chunks that were
+                // held waiting for styles. Workers will process every chunk with
+                // resolved colors — uniform shading across the whole stream.
+                const styleIds = evt.styleIds;
+                const styleColors = evt.styleColors;
+                const voidKeys = evt.voidKeys;
+                const voidCounts = evt.voidCounts;
+                const voidValues = evt.voidValues;
+                console.log(`[stream] styles @ ${elapsed()}ms (${styleIds.length} styled, ${voidKeys.length} void hosts), draining ${queuedChunks.length} queued chunks`);
+                for (const w of workers) {
+                    // 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.
+                    try {
+                        const sIds = styleIds.slice();
+                        const sColors = styleColors.slice();
+                        const vKeys = voidKeys.slice();
+                        const vCounts = voidCounts.slice();
+                        const vValues = voidValues.slice();
+                        w.postMessage({
+                            type: 'set-styles',
+                            styleIds: sIds,
+                            styleColors: sColors,
+                            voidKeys: vKeys,
+                            voidCounts: vCounts,
+                            voidValues: vValues,
+                        }, [sIds.buffer, sColors.buffer, vKeys.buffer, vCounts.buffer, vValues.buffer]);
+                    }
+                    catch (err) {
+                        console.warn('[stream] set-styles dispatch failed:', err);
+                    }
+                }
+                stylesReceived = true;
+                // 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.
+                drainQueuedChunksIfReady();
+            }
+            else if (evt.type === 'entity-index') {
+                // Pre-pass exported its built entity_index. Forward to every
+                // worker so they skip the ~5 s file re-scan in Rust's lazy
+                // build path. SAB sharing for zero-copy distribution to N
+                // workers — each gets a Uint32Array view over the same buffer.
+                const ids = evt.ids;
+                const starts = evt.starts;
+                const lengths = evt.lengths;
+                console.log(`[stream] entity-index @ ${elapsed()}ms (${ids.length} entries)`);
+                if (typeof SharedArrayBuffer !== 'undefined') {
+                    // Allocate one SAB triple, copy data once, share across all
+                    // workers without postMessage clone cost.
+                    const idsBytes = ids.byteLength;
+                    const startsBytes = starts.byteLength;
+                    const lengthsBytes = lengths.byteLength;
+                    const sabIds = new SharedArrayBuffer(idsBytes);
+                    const sabStarts = new SharedArrayBuffer(startsBytes);
+                    const sabLengths = new SharedArrayBuffer(lengthsBytes);
+                    new Uint32Array(sabIds).set(ids);
+                    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);
+                        }
+                    }
+                    // Hand the same SAB triple to the parser worker (or any other
+                    // listener) so it can skip its own `scanEntitiesFastBytes` call.
+                    // Each consumer gets its own Uint32Array view over the shared
+                    // buffers — no extra copy.
+                    if (options?.onEntityIndex) {
+                        try {
+                            options.onEntityIndex(new Uint32Array(sabIds), new Uint32Array(sabStarts), new Uint32Array(sabLengths));
+                        }
+                        catch (err) {
+                            console.warn('[stream] onEntityIndex callback failed:', err);
+                        }
+                    }
+                }
+                else {
+                    // SAB unavailable — clone per worker via structured clone.
+                    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);
+                        }
+                    }
+                    if (options?.onEntityIndex) {
+                        try {
+                            options.onEntityIndex(ids.slice(), starts.slice(), lengths.slice());
+                        }
+                        catch (err) {
+                            console.warn('[stream] onEntityIndex callback failed:', err);
+                        }
+                    }
+                }
+                entityIndexReceived = true;
+                drainQueuedChunksIfReady();
+            }
+            else if (evt.type === 'complete') {
+                prepassJobsTotal = evt.totalJobs;
+                console.log(`[stream] prepass complete @ ${elapsed()}ms totalJobs=${prepassJobsTotal} chunks=${chunkArrivals}`);
+                // Unconditionally drive the prepass-complete handler here.
+                // The outer loop's `prepassJobsTotal > 0` gate would skip
+                // zero-geometry files (no IFC geometry entities), causing
+                // the generator to wait forever. Calling here ensures
+                // prepassDone flips even when totalJobs === 0.
+                if (!prepassCompleteSeen) {
+                    prepassCompleteSeen = true;
+                    onPrepassComplete();
+                }
+            }
+            return;
+        }
+        if (data.type === 'error') {
+            prepassError = new Error(data.message);
+            prepassDone = true;
+            prepassWorker.terminate();
+            wake();
+            return;
+        }
+        // The streaming variant doesn't emit `prepass-result` — the streaming
+        // worker exits naturally after the JS callback returns from
+        // `buildPrePassStreaming`. We treat unknown messages as no-ops.
+    };
+    prepassWorker.onerror = (e) => {
+        prepassError = new Error(`Pre-pass worker failed: ${e.message}`);
+        prepassDone = true;
+        prepassWorker.terminate();
+        wake();
+    };
+    // Track when the pre-pass worker finishes by listening for either a
+    // synthesized "complete" event from the Rust side OR a worker exit. The
+    // Rust side currently doesn't post anything after `complete` (it returns
+    // from JS), so we close the worker via terminate-on-complete in the host.
+    // After we see the Rust `complete` event we can sendStreamEnd.
+    const onPrepassComplete = () => {
+        prepassDone = true;
+        // 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
+        // needed. The dedicated zero-jobs branch in the outer loop
+        // handles their teardown.
+        if (streamStartSentToWorkers) {
+            sendStreamEnd();
+        }
+        prepassWorker.terminate();
+        wake();
+    };
+    // Dispatch the streaming pre-pass.
+    // chunk_size = 50K is a deliberate compromise:
+    //   • small enough that the FIRST chunk (always a tiny one — bounded by
+    //     RTC_SAMPLE_THRESHOLD ≈ 50 jobs from the Rust side) reaches workers
+    //     within ~1.5 s for fast TTFG;
+    //   • large enough that subsequent chunks make few Rust→JS callbacks
+    //     and few worker postMessages — each call into processGeometryBatch
+    //     has fixed setup cost that compounds badly when invoked 30+ times.
+    // Per-chunk fan-out (see `dispatchJobsChunkInternal`) splits each chunk
+    // evenly across all workers so parallelism is preserved at every chunk.
+    prepassWorker.postMessage({ type: 'prepass-streaming', sharedBuffer, chunkSize: 50_000 });
+    // Drain the event queue until the pre-pass and all process workers complete.
+    // The pre-pass `complete` event is captured inside the message handler
+    // (we set prepassJobsTotal there) but the worker stays alive briefly
+    // while the JS callback returns. Detect end-of-stream by:
+    //   a) `prepassJobsTotal > 0` (or zero-jobs file): pre-pass emitted complete
+    //   b) all workers reported `complete`
+    let prepassCompleteSeen = false;
     while (true) {
-        while (batchQueue.length > 0) {
-            const batch = batchQueue.shift();
-            coordinator.processMeshesIncremental(batch);
-            const coordinateInfo = coordinator.getCurrentCoordinateInfo();
-            yield {
-                type: 'batch',
-                meshes: batch,
-                totalSoFar: totalMeshes,
-                coordinateInfo: coordinateInfo || undefined,
-            };
+        while (eventQueue.length > 0) {
+            yield eventQueue.shift();
         }
         if (workerError) {
-            // Terminate remaining workers
             for (const w of workers) {
                 try {
                     w.terminate();
                 }
                 catch { /* cleanup — safe to ignore */ }
             }
+            try {
+                prepassWorker.terminate();
+            }
+            catch { /* cleanup — safe to ignore */ }
             throw workerError;
         }
-        if (workersCompleted >= chunks.length && batchQueue.length === 0) {
+        if (prepassError) {
+            for (const w of workers) {
+                try {
+                    w.terminate();
+                }
+                catch { /* cleanup — safe to ignore */ }
+            }
+            throw prepassError;
+        }
+        // Edge case: pre-pass for a file with zero geometry. The Rust side
+        // emits `complete { totalJobs: 0 }`; meta never fired so workers
+        // never received stream-start. Tear them down explicitly and yield
+        // `complete`. Workers were pre-spawned with `init` so they need an
+        // explicit terminate to exit.
+        if (prepassDone && !streamStartSentToWorkers && prepassJobsTotal === 0) {
+            for (const w of workers) {
+                try {
+                    w.terminate();
+                }
+                catch { /* cleanup — safe to ignore */ }
+            }
+            const coordinateInfo = coordinator.getFinalCoordinateInfo();
+            yield { type: 'complete', totalMeshes: 0, coordinateInfo };
+            return;
+        }
+        if (prepassDone
+            && streamStartSentToWorkers
+            && workersCompleted >= workers.length
+            && eventQueue.length === 0) {
             break;
         }
-        await new Promise((resolve) => {
-            resolveWaiting = resolve;
-        });
+        await new Promise((resolve) => { resolveWaiting = resolve; });
     }
     const coordinateInfo = coordinator.getFinalCoordinateInfo();
     yield { type: 'complete', totalMeshes, coordinateInfo };