fix(parser): prevent Firefox spatial-metadata publication stalls (#3984)

* fix(parser): avoid Firefox stalls when spatial metadata reaches the viewer

* chore(viewer): remove unused hierarchy subscriptions

* chore(lint): tighten unused hierarchy selector budgets

* fix(viewer): distinguish completed geometry-only hierarchy state

* chore(parser): clear touched-module lint warnings

Author: louistrue

.changeset/quick-spatial-firefox.md

@@ -0,0 +1,5 @@
+---
+"@ifc-lite/parser": patch
+---
+
+Avoid Firefox stalls while publishing large-model metadata by keeping entity-cache eviction linear across scans and preparing georeferencing and source fingerprints in the parser worker.

apps/viewer/src/components/viewer/HierarchyPanel.federation.test.tsx

@@ -127,6 +127,20 @@ describe('HierarchyPanel — federated unified-storey selection', () => {
     resetStore();
   });
 
+  it('distinguishes pending IFC metadata from completed geometry-only models (#3984)', () => {
+    const model = federatedModel('m1', makeStore(5, 0, 'Level 1'));
+    model.ifcDataStore = null;
+    model.loadState = 'hydrating-metadata';
+    useViewerStore.setState({ models: new Map([['m1', model]]) });
+    const container = renderPanel();
+    assert.match(container.textContent ?? '', /Building the hierarchy/);
+    act(() => {
+      useViewerStore.setState({ models: new Map([['m1', { ...model, loadState: 'complete' }]]) });
+    });
+    assert.match(container.textContent ?? '', /No hierarchy available for this model/);
+    assert.doesNotMatch(container.textContent ?? '', /Building the hierarchy/);
+  });
+
   it('selecting Level 1 (model m1, local id 5) does not cross-highlight Level 2 (model m2, same local id 5)', () => {
     const m1 = federatedModel('m1', makeStore(5, 0, 'Level 1'));
     const m2 = federatedModel('m2', makeStore(5, 10, 'Level 2'));

apps/viewer/src/components/viewer/HierarchyPanel.tsx

@@ -58,7 +58,6 @@ export function HierarchyPanel() {
   const setSelectedModelId = useViewerStore((s) => s.setSelectedModelId);
   const selectedStoreys = useViewerStore((s) => s.selectedStoreys);
   const activeStorey = useViewerStore((s) => s.activeStorey);
-  const setStoreySelection = useViewerStore((s) => s.setStoreySelection);
   const setStoreysSelection = useViewerStore((s) => s.setStoreysSelection);
   const clearStoreySelection = useViewerStore((s) => s.clearStoreySelection);
   const setActiveStorey = useViewerStore((s) => s.setActiveStorey);
@@ -87,7 +86,6 @@ export function HierarchyPanel() {
   const hiddenEntities = useViewerStore((s) => s.hiddenEntities);
   const hideEntities = useViewerStore((s) => s.hideEntities);
   const showEntities = useViewerStore((s) => s.showEntities);
-  const toggleEntityVisibility = useViewerStore((s) => s.toggleEntityVisibility);
   const clearSelection = useViewerStore((s) => s.clearSelection);
 
   // Derive label for type isolation (from the Type tab, or any other
@@ -802,10 +800,9 @@ export function HierarchyPanel() {
   if (!ifcDataStore && singleModel) {
     const metadataState = singleModel.metadataLoadState;
     const message = metadataState === 'error'
-      ? (singleModel.loadError || 'Native metadata failed to load.')
-      : metadataState === 'bootstrapping'
-        ? 'Native spatial metadata is loading.'
-        : 'Spatial metadata will appear once bootstrap completes.';
+      ? (singleModel.loadError || 'Model details failed to load.')
+      : singleModel.loadState === 'complete' ? 'No hierarchy available for this model.'
+      : 'Building the hierarchy. You can explore the geometry while model details load.';
     return (
       <div className="h-full flex flex-col border-r-2 border-zinc-200 dark:border-zinc-800 bg-white dark:bg-black">
         <div className="p-3 border-b-2 border-zinc-200 dark:border-zinc-800 bg-zinc-50 dark:bg-black">

apps/viewer/src/hooks/useIfcLoader.ts

@@ -1354,10 +1354,8 @@ export function useIfcLoader() {
       // the geometry workers read the same memory zero-copy. When
       // `acquireFileBuffer` already streamed the file directly into a SAB
       // (large-file entry path, issue #600), reuse it — no second copy.
-      // `WorkerParser.isSupported()` rolls together: COI enabled, SAB
-      // available, AND TextDecoder accepts SAB-backed views (Firefox fails
-      // the third check; we skip the worker path entirely there so the
-      // SAB allocation isn't wasted).
+      // `WorkerParser.isSupported()` checks COI, SAB and Worker availability.
+      // The parser's UTF-8 reader handles SAB-backed views in Firefox too.
       const useParserWorker = WorkerParser.isSupported();
       let sharedSource: SharedArrayBuffer | null = null;
       if (useParserWorker) {

packages/parser/src/compact-entity-index-cache.test.ts

@@ -0,0 +1,42 @@
+/* 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, expect, it } from 'vitest';
+import { CompactEntityIndex } from './compact-entity-index.js';
+
+function index(capacity: number, count = 20_000): CompactEntityIndex {
+  const ids = Uint32Array.from({ length: count }, (_, i) => i + 1);
+  return new CompactEntityIndex(ids, ids.map(id => id * 80), new Uint32Array(count).fill(80),
+    new Uint16Array(count), ['IFCWALL'], capacity);
+}
+
+describe('entity cache eviction after long scans (#3983)', () => {
+  it('preserves reference contents and hot entries across eviction and clearing', () => {
+    const data = index(3);
+    const hot = data.get(1);
+    data.get(2);
+    const cold = data.get(3);
+    for (let id = 4; id <= 20_000; id++) {
+      expect(data.get(1)).toBe(hot);
+      expect(data.get(id)).toEqual({ expressId: id, type: 'IFCWALL', byteOffset: id * 80, byteLength: 80, lineNumber: 0 });
+    }
+    expect(data.get(3)).not.toBe(cold);
+    data.clearCache();
+    const renewed = data.get(1);
+    expect(renewed).toEqual(hot);
+    expect(renewed).not.toBe(hot);
+    for (let id = 4; id < 100; id++) { data.get(1); data.get(id); }
+    expect(data.get(1)).toBe(renewed);
+    expect(data.get(99)?.byteOffset).toBe(7920);
+  });
+
+  it('supports zero-capacity caches and invalid lookups without exhausting eviction', () => {
+    const data = index(0, 100);
+    for (let id = 1; id <= 100; id++) {
+      const first = data.get(id);
+      expect(data.get(id)).toEqual(first);
+      expect(data.get(id)).not.toBe(first);
+      expect(data.get(-1)).toBeUndefined();
+    }
+  });
+});

packages/parser/src/compact-entity-index.ts

@@ -2,16 +2,8 @@
  * 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/. */
 
-/**
- * CompactEntityIndex - Memory-efficient entity index using typed arrays
- *
- * Replaces Map<number, EntityRef> with sorted typed arrays for O(log n) lookup.
- * For 8.4M entities, this saves ~400MB of Map overhead:
- *   - Map: ~56 bytes/entry overhead (key + value + hash table) = ~470MB
- *   - Typed arrays: ~16 bytes/entry (4 Uint32Arrays) = ~134MB
- *
- * Provides the same Map-like interface via get()/has() for drop-in compatibility.
- */
+/** Sorted entity columns avoid the per-entry overhead of Map<number, EntityRef>.
+ * Lookups use binary search with a bounded LRU for recently read references. */
 
 import { checkedExpressId } from './express-id.js';
 import type { EntityRef } from './types.js';
@@ -51,6 +43,7 @@ export class CompactEntityIndex {
 
   /** LRU cache for recently accessed EntityRefs */
   private lruCache: Map<number, EntityRef>;
+  private lruKeys: MapIterator<number> | undefined;
   private readonly lruMaxSize: number;
 
   constructor(
@@ -125,8 +118,10 @@ export class CompactEntityIndex {
     // Add to LRU cache
     this.lruCache.set(expressId, ref);
     if (this.lruCache.size > this.lruMaxSize) {
-      // Delete oldest entry (first key in insertion order)
-      const firstKey = this.lruCache.keys().next().value;
+      // #3983: keep a live cursor. Restarting at the Map's deleted prefix for
+      // every eviction makes a large sequential scan quadratic in Firefox.
+      this.lruKeys ??= this.lruCache.keys();
+      const firstKey = this.lruKeys.next().value;
       if (firstKey !== undefined) {
         this.lruCache.delete(firstKey);
       }
@@ -234,6 +229,7 @@ export class CompactEntityIndex {
    */
   clearCache(): void {
     this.lruCache.clear();
+    this.lruKeys = undefined;
   }
 
   /**

packages/parser/src/data-store-transport.ts

@@ -3,20 +3,9 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
 /**
- * Worker-boundary transport for `IfcDataStore`.
- *
- * `IfcDataStore` carries closures (`entities.getName`, `relationships.getRelated`,
- * `spatialHierarchy.getPath`, …) that the structured-clone algorithm strips
- * silently. This module separates the clone-safe column data from the
- * closures: `toTransport` returns a POJO + transferable list to ship across
- * a `postMessage` boundary; `fromTransport` reconstructs a live `IfcDataStore`
- * with closures rebuilt on the receiving thread.
- *
- * The `source` buffer is intentionally NOT included in the transferable list
- * because both the parser worker and the geometry workers read from the same
- * `SharedArrayBuffer` upstream of the parser. Callers are responsible for
- * keeping a `Uint8Array` view of that SAB on the main thread and supplying
- * it to `fromTransport`.
+ * Worker transport splits clone-safe columns from live store accessors.
+ * toTransport serializes columns; fromTransport rebuilds their closures.
+ * Source bytes stay in the shared buffer, supplied separately by the receiver.
  */
 
 import {
@@ -54,6 +43,8 @@ import type { EntityRef } from './types.js';
 import { asSourceBytes, type IfcSourceBytes } from './source-bytes.js';
 import type { IfcDataStore, EntityByIdIndex } from './columnar-parser.js';
 import { attachDataStoreAccessors } from './data-store-accessors.js';
+import type { GeoreferenceInfo } from './georef-extractor.js';
+import { oncePerStore } from './on-demand-cache.js';
 
 export type { CompactEntityIndexColumns };
 
@@ -213,6 +204,9 @@ export interface ParserMemorySnapshot {
 // ────────────────────────────────────────────────────────────────────────────
 
 export interface DataStoreTransport {
+  /** Worker-prepared render data (#3983); absent on older transports. */
+  sourceContentKey?: string | null;
+  georeferencing?: GeoreferenceInfo | null;
   fileSize: number;
   schemaVersion: IfcDataStore['schemaVersion'];
   sourceHeader?: IfcDataStore['sourceHeader'];
@@ -447,7 +441,7 @@ export function fromTransport(
   const onDemandQuantityMap = new Map(payload.onDemandQuantityMap.map(([k, v]) => [k, [...v]]));
   // Lazy accessors are wired by the shared helper so the fresh-parse, transport,
   // and cache-restore paths can never drift (see data-store-accessors.ts).
-  return attachDataStoreAccessors({
+  const store = attachDataStoreAccessors({
     fileSize: payload.fileSize,
     schemaVersion: payload.schemaVersion,
     sourceHeader: payload.sourceHeader,
@@ -472,6 +466,10 @@ export function fromTransport(
     onDemandMaterialMap: new Map(payload.onDemandMaterialMap),
     onDemandDocumentMap: new Map(payload.onDemandDocumentMap.map(([k, v]) => [k, [...v]])),
   });
+  if (payload.georeferencing !== undefined) {
+    oncePerStore(store, 'georef', () => payload.georeferencing);
+  }
+  return store;
 }
 
 /**

packages/parser/src/parser-worker-malformed-handoff.test.ts

@@ -23,7 +23,11 @@
  * per-test and why the hook timeout is generous.
  */
 
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { fromTransport, type DataStoreTransport } from './data-store-transport.js';
+import { extractGeoreferencingOnDemand } from './on-demand-georeferencing.js';
+import { contiguousSourceBytes } from './source-bytes.js';
 
 const postedMessages: unknown[] = [];
 let originalSelf: unknown;
@@ -44,6 +48,7 @@ const IFC = [
   'DATA;',
   "#1=IFCPROJECT('0000000000000000000001',$,'P',$,$,$,$,$,$);",
   "#2=IFCWALL('0000000000000000000002',$,'Wall2',$,$,$,$,$,$);",
+  "#3=IFCSITE('0000000000000000000003',$,'Site',$,$,$,$,$,.ELEMENT.,(47,0,0),(8,0,0),0.,$,$);",
   'ENDSEC;',
   'END-ISO-10303-21;',
   '',
@@ -120,7 +125,8 @@ beforeEach(async () => {
   originalPostMessage = g.postMessage;
   g.self = globalThis;
   g.postMessage = (msg: unknown) => postedMessages.push(msg);
-  await import('./parser.worker.js?t=' + ++importCounter);
+  importCounter += 1;
+  await import('./parser.worker.js?t=' + importCounter);
 }, WORKER_IMPORT_HOOK_TIMEOUT_MS);
 
 afterEach(() => {
@@ -176,3 +182,34 @@ describe('parser.worker.ts and the #3790 set-entity-index handoff', () => {
     expect(diagnostics().some((m) => m.includes('stopped early'))).toBe(false);
   }, 30_000);
 });
+
+// #3983: execute the real worker handler; verify the receiver needs no entity
+// lookups for its first georeference read (including the early spatial store).
+it('prepares render metadata before publishing partial and complete stores (#3983)', async () => {
+  const records = [...IFC.matchAll(/#(\d+)=[^;]+;/g)];
+  post({ type: 'set-entity-index',
+    ids: Uint32Array.from(records, r => Number(r[1])),
+    starts: Uint32Array.from(records, r => r.index!),
+    lengths: Uint32Array.from(records, r => r[0].length),
+  });
+  startParse();
+  await settle();
+  assertParsed();
+  const messages = postedMessages.filter((m): m is { type: string; payload: DataStoreTransport } =>
+    ['partial-store', 'complete'].includes((m as { type: string }).type));
+  expect(messages).toHaveLength(2);
+  for (const { payload } of messages) {
+    const source = contiguousSourceBytes(new Uint8Array(sharedSource()), payload.sourceContentKey ?? undefined);
+    // Full-fixture FNV-1a, independently calculated with Python integer arithmetic.
+    expect(payload.sourceContentKey).toBe('16b-6d79a917');
+    // toTransferable does not compute a key: this proves it arrived pre-seeded.
+    expect(source.toTransferable().contentKey).toBe(payload.sourceContentKey);
+    const store = fromTransport(structuredClone(payload), source);
+    const lookups = vi.spyOn(store.entityIndex.byId, 'get');
+    const georef = extractGeoreferencingOnDemand(store);
+    expect(georef?.source).toBe('siteLocation');
+    expect(georef?.projectedCRS?.name).toBe('EPSG:4326');
+    expect(lookups).not.toHaveBeenCalled();
+    lookups.mockRestore();
+  }
+}, 30_000);

packages/parser/src/parser.worker.ts

@@ -18,10 +18,10 @@
 import init, { IfcAPI } from '@ifc-lite/wasm';
 import { initWasmWithRetry } from './wasm-init-retry.js';
 import { IfcParser } from './index.js';
+import { extractGeoreferencingOnDemand } from './on-demand-georeferencing.js';
 import type { IfcDataStore } from './columnar-parser.js';
 import type { WasmScanApi } from './entity-scanner.js';
 import {
-  collectTransferables,
   toTransport,
   transportByteSize,
   type DataStoreTransport,
@@ -244,9 +244,8 @@ self.onmessage = async (event: MessageEvent<ParserInbound>) => {
   try {
     // The SAB itself is shared by reference — both this worker and the
     // main thread (and the geometry workers) hold views of the same bytes.
-    // We never transfer or clone it. Runtimes that reject TextDecoder over
-    // SAB views (e.g. Firefox's timing-attack mitigation) are filtered out
-    // by the wrapper before this worker is even spawned.
+    // We never transfer or clone it. The parser's UTF-8 reader also supports
+    // runtimes that reject TextDecoder over SAB-backed views.
     //
     // Initialise the WASM scanner. `parseColumnar` prefers the WASM scan when
     // `wasmApi` is supplied (5–10× faster on huge files — a 14 M-entity, 986 MB
@@ -293,6 +292,7 @@ self.onmessage = async (event: MessageEvent<ParserInbound>) => {
     // index were somehow empty, the scanner falls through to the JS tokeniser.
     const wasmApi = wasmApiPromise ? await wasmApiPromise : undefined;
     const parser = new IfcParser();
+    let georeferencing: ReturnType<typeof extractGeoreferencingOnDemand> | undefined;
     // `source` is the SAB-backed payload — `parseColumnar` accepts
     // `ArrayBuffer | SharedArrayBuffer` so no cast is needed.
     const dataStore: IfcDataStore = await parser.parseColumnar(source, {
@@ -311,6 +311,13 @@ self.onmessage = async (event: MessageEvent<ParserInbound>) => {
       onSpatialReady: (partialStore) => {
         try {
           const { payload } = toTransport(partialStore);
+          // #3983: overlays and Cesium availability read these during React
+          // rendering. Do the full-source/hash and property-set walks here.
+          payload.sourceContentKey = partialStore.source.contentKey;
+          if (!deferPropertyAtomIndex) {
+            georeferencing = extractGeoreferencingOnDemand(partialStore);
+            payload.georeferencing = georeferencing;
+          }
           // We intentionally do NOT transfer the partial typed-array
           // buffers. The worker keeps using them for the rest of the parse
           // (entityIndex.byId.get(...) etc. all read from these arrays).
@@ -327,6 +334,9 @@ self.onmessage = async (event: MessageEvent<ParserInbound>) => {
       },
     });
     const { payload, transfers } = toTransport(dataStore);
+    payload.sourceContentKey = dataStore.source.contentKey;
+    payload.georeferencing = georeferencing === undefined
+      ? extractGeoreferencingOnDemand(dataStore) : georeferencing;
     // CRITICAL: every field here MUST be synchronous. Do NOT await on this path —
     // it gates the 'complete' message (the full data store) reaching the main thread.
     // This previously `await`ed performance.measureUserAgentSpecificMemory(); in a

packages/parser/src/worker-parser.ts

@@ -26,7 +26,7 @@ import {
   type DataStoreTransport,
   type ParserMemorySnapshot,
 } from './data-store-transport.js';
-import { contiguousSourceBytes } from './source-bytes.js';
+import { contiguousSourceBytes, type IfcSourceBytes } from './source-bytes.js';
 import type {
   ParserWorkerInputMessage,
   ParserWorkerOutputMessage,
@@ -119,7 +119,13 @@ export class WorkerParser {
       // on exactly the models #2183 is about. The previous code got one hash by
       // memoising on the shared Uint8Array; sharing the accessor is the same
       // guarantee without the side table.
-      const sourceBytes = contiguousSourceBytes(new Uint8Array(source));
+      let sourceBytes: IfcSourceBytes | undefined;
+      const hydrate = (payload: DataStoreTransport) => {
+        // #3983: the worker hashes the source before the first UI publication.
+        // Retain one accessor across partial/full stores and compression swaps.
+        sourceBytes ??= contiguousSourceBytes(new Uint8Array(source), payload.sourceContentKey ?? undefined);
+        return fromTransport(payload, sourceBytes);
+      };
 
       const settle = (cleanup: () => void) => {
         worker.onmessage = null;
@@ -144,7 +150,7 @@ export class WorkerParser {
           case 'partial-store': {
             if (!options.onSpatialReady) return;
             try {
-              const partial = fromTransport(msg.payload as DataStoreTransport, sourceBytes);
+              const partial = hydrate(msg.payload);
               options.onSpatialReady(partial);
             } catch (err) {
               // Don't fail the whole parse on partial deserialization
@@ -156,7 +162,7 @@ export class WorkerParser {
 
           case 'complete': {
             try {
-              const dataStore = fromTransport(msg.payload as DataStoreTransport, sourceBytes);
+              const dataStore = hydrate(msg.payload);
               options.onMemorySnapshot?.(msg.memory);
               settle(() => {
                 worker.terminate();