@ifc-lite/viewer 1.26.0 → 1.28.0

package/src/hooks/ingest/viewerModelIngest.ts

@@ -2,16 +2,11 @@
  * 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 { IfcParser, parseIfcx, type IfcDataStore, type PointCloudExtraction } from '@ifc-lite/parser';
-import { WorkerParser } from '@ifc-lite/parser/browser';
-import { GeometryProcessor, GeometryQuality, type CoordinateInfo, type DynamicBatchConfig, type GeometryResult, type MeshData, type PointCloudAsset } from '@ifc-lite/geometry';
+import { parseIfcx, type IfcDataStore, type PointCloudExtraction } from '@ifc-lite/parser';
+import { type GeometryResult, type MeshData, type PointCloudAsset } from '@ifc-lite/geometry';
 import { loadGLBToMeshData } from '@ifc-lite/cache';
 import type { SchemaVersion } from '../../store/types.js';
-import { calculateMeshBounds, calculateStoreyHeights, createCoordinateInfo, normalizeColor } from '../../utils/localParsingUtils.js';
-import { resolveDataStoreOrAbort } from './resolveDataStoreOrAbort.js';
-import { watchedGeometryStream } from './watchedGeometryStream.js';
-
-type RgbaColor = [number, number, number, number];
+import { calculateMeshBounds, createCoordinateInfo, normalizeColor } from '../../utils/localParsingUtils.js';
 
 interface RawIfcxMesh {
   expressId?: number;
@@ -31,40 +26,6 @@ export interface ViewerModelPayload {
   schemaVersion: SchemaVersion;
 }
 
-export interface StepBatchEvent {
-  batchIndex: number;
-  estimatedTotal: number;
-  totalSoFar: number;
-  meshes: MeshData[];
-  coordinateInfo?: CoordinateInfo | null;
-}
-
-export interface StepRtcOffsetEvent {
-  rtcOffset: { x: number; y: number; z: number };
-}
-
-export interface StepBufferIngestOptions {
-  fileName: string;
-  buffer: ArrayBuffer;
-  fileSizeMB: number;
-  getDynamicBatchSize: (fileSizeMB: number) => number | DynamicBatchConfig;
-  onProgress?: (progress: { phase: string; percent: number }) => void;
-  onBatch?: (event: StepBatchEvent) => void;
-  onColorUpdate?: (updates: Map<number, RgbaColor>) => void;
-  onSpatialReady?: (dataStore: IfcDataStore) => void;
-  onRtcOffset?: (event: StepRtcOffsetEvent) => void;
-  shouldAbort?: () => boolean;
-  /** Shared RTC offset from first federated model (IFC Z-up coords).
-   *  When set, this model uses the same RTC as the first model instead of
-   *  computing its own, ensuring all models share the same coordinate space. */
-  sharedRtcOffset?: { x: number; y: number; z: number };
-}
-
-export interface StepBufferIngestResult extends ViewerModelPayload {
-  allMeshes: MeshData[];
-  cumulativeColorUpdates: Map<number, RgbaColor>;
-}
-
 export function convertIfcxMeshes(rawMeshes: RawIfcxMesh[]): MeshData[] {
   return rawMeshes.map((mesh) => {
     const positions = mesh.positions instanceof Float32Array ? mesh.positions : new Float32Array(mesh.positions || []);
@@ -99,16 +60,6 @@ export function createMinimalGlbDataStore(buffer: ArrayBuffer, meshCount: number
   } as unknown as IfcDataStore;
 }
 
-export function normalizeDataStoreStoreys(dataStore: IfcDataStore): IfcDataStore {
-  if (dataStore.spatialHierarchy && dataStore.spatialHierarchy.storeyHeights.size === 0 && dataStore.spatialHierarchy.storeyElevations.size > 1) {
-    const calculatedHeights = calculateStoreyHeights(dataStore.spatialHierarchy.storeyElevations);
-    for (const [storeyId, height] of calculatedHeights) {
-      dataStore.spatialHierarchy.storeyHeights.set(storeyId, height);
-    }
-  }
-  return dataStore;
-}
-
 export function getMaxExpressId(dataStore: IfcDataStore, meshes: MeshData[]): number {
   const maxExpressIdFromMeshes = meshes.reduce((max, mesh) => Math.max(max, mesh.expressId), 0);
   let maxExpressIdFromEntities = 0;
@@ -213,163 +164,3 @@ export async function parseGlbViewerModel(buffer: ArrayBuffer): Promise<ViewerMo
     schemaVersion: 'IFC4',
   };
 }
-
-export async function parseStepBufferViewerModel(options: StepBufferIngestOptions): Promise<StepBufferIngestResult> {
-  const geometryProcessor = new GeometryProcessor({ quality: GeometryQuality.Balanced });
-  await geometryProcessor.init();
-
-  const parser = new IfcParser();
-  const wasmApi = geometryProcessor.getApi();
-  const canShareSource = WorkerParser.isSupported();
-  const sharedSource = canShareSource ? new SharedArrayBuffer(options.buffer.byteLength) : null;
-  if (sharedSource) {
-    new Uint8Array(sharedSource).set(new Uint8Array(options.buffer));
-  }
-  const geometryWillEmitEntityIndex =
-    sharedSource !== null
-    && options.fileSizeMB >= 2
-    && typeof Worker !== 'undefined'
-    && typeof navigator !== 'undefined'
-    && (navigator.hardwareConcurrency ?? 1) > 1;
-  let workerParser: WorkerParser | null = null;
-  const allMeshes: MeshData[] = [];
-  const cumulativeColorUpdates = new Map<number, RgbaColor>();
-  let finalCoordinateInfo: CoordinateInfo | null = null;
-  let batchIndex = 0;
-  let estimatedTotal = 0;
-  let capturedRtcOffset: { x: number; y: number; z: number } | null = null;
-
-  const handleSpatialReady = (partialStore: IfcDataStore) => {
-    if (options.shouldAbort?.()) {
-      return;
-    }
-    options.onSpatialReady?.(normalizeDataStoreStoreys(partialStore));
-  };
-  const dataStorePromise = sharedSource
-    ? (() => {
-        workerParser = new WorkerParser();
-        return workerParser.parseColumnar(sharedSource, {
-          waitForEntityIndex: geometryWillEmitEntityIndex,
-          onSpatialReady: handleSpatialReady,
-        }).catch((error) => {
-          console.warn('[viewerModelIngest] Parser worker failed, falling back to main-thread parse:', error);
-          return parser.parseColumnar(options.buffer, {
-            wasmApi: wasmApi ?? undefined,
-            onSpatialReady: handleSpatialReady,
-          });
-        });
-      })()
-    : parser.parseColumnar(options.buffer, {
-        wasmApi: wasmApi ?? undefined,
-        onSpatialReady: handleSpatialReady,
-      });
-
-  const geometryView = sharedSource ? new Uint8Array(sharedSource) : new Uint8Array(options.buffer);
-  const geometryStream = geometryProcessor.processAdaptive(geometryView, {
-    sizeThreshold: 2 * 1024 * 1024,
-    batchSize: options.getDynamicBatchSize(options.fileSizeMB),
-    sharedRtcOffset: options.sharedRtcOffset,
-    existingSab: sharedSource ?? undefined,
-    onEntityIndex: (ids, starts, lengths) => {
-      workerParser?.setEntityIndex(ids, starts, lengths);
-    },
-  });
-  let lastTotalMeshes = 0;
-  // The federated/added-model path was missing the size-aware stream watchdog
-  // the single-model loader has, so a geometry worker that failed to spawn would
-  // hang the load forever on "Processing geometry (N meshes)" instead of
-  // surfacing a recoverable error. watchedGeometryStream re-yields each event
-  // under that watchdog and bounds iterator teardown on every exit path.
-  try {
-    for await (const event of watchedGeometryStream(geometryStream, {
-      fileName: options.fileName,
-      fileSizeMB: options.fileSizeMB,
-      shouldAbort: options.shouldAbort,
-      getBatchCount: () => batchIndex,
-      getLastTotalMeshes: () => lastTotalMeshes,
-    })) {
-      switch (event.type) {
-        case 'start':
-          estimatedTotal = event.totalEstimate;
-          break;
-        case 'colorUpdate':
-          for (const [expressId, color] of event.updates) {
-            cumulativeColorUpdates.set(expressId, color);
-          }
-          options.onColorUpdate?.(event.updates);
-          break;
-        case 'rtcOffset':
-          if (event.hasRtc) {
-            capturedRtcOffset = event.rtcOffset;
-            options.onRtcOffset?.({ rtcOffset: event.rtcOffset });
-          }
-          break;
-        case 'batch':
-          batchIndex += 1;
-          for (let i = 0; i < event.meshes.length; i++) {
-            allMeshes.push(event.meshes[i]);
-          }
-          finalCoordinateInfo = event.coordinateInfo ?? null;
-          lastTotalMeshes = event.totalSoFar;
-          options.onBatch?.({
-            batchIndex,
-            estimatedTotal,
-            totalSoFar: event.totalSoFar,
-            meshes: event.meshes,
-            coordinateInfo: event.coordinateInfo ?? null,
-          });
-          options.onProgress?.({
-            phase: `Processing geometry (${event.totalSoFar} meshes)`,
-            percent: 10 + Math.min(80, (allMeshes.length / 1000) * 0.8),
-          });
-          break;
-        case 'complete':
-          finalCoordinateInfo = event.coordinateInfo ?? null;
-          break;
-      }
-    }
-  } catch (err) {
-    // Watchdog stall (or other stream error): the parser worker may be
-    // blocked in `waitForEntityIndex`, which only the geometry pre-pass would
-    // unblock. Terminate it here so it doesn't leak — the normal path below
-    // still awaits it via resolveDataStoreOrAbort. watchedGeometryStream's
-    // finally has already bounded teardown of the geometry iterator itself.
-    workerParser?.terminate();
-    throw err;
-  }
-
-  // If the load was cancelled, don't await dataStorePromise: a worker parse
-  // started with waitForEntityIndex blocks until the geometry pre-pass hands
-  // over the entity index, which never happens once the geometry loop has been
-  // aborted above. resolveDataStoreOrAbort terminates the worker and throws an
-  // AbortError instead of hanging here.
-  const dataStore = normalizeDataStoreStoreys(
-    await resolveDataStoreOrAbort(dataStorePromise, {
-      aborted: options.shouldAbort?.() ?? false,
-      terminate: () => workerParser?.terminate(),
-    }),
-  );
-  if (!finalCoordinateInfo) {
-    finalCoordinateInfo = createCoordinateInfo(calculateMeshBounds(allMeshes).bounds);
-  }
-  if (capturedRtcOffset) {
-    finalCoordinateInfo.wasmRtcOffset = capturedRtcOffset;
-  }
-
-  return {
-    dataStore,
-    geometryResult: {
-      meshes: allMeshes,
-      totalVertices: allMeshes.reduce((sum, mesh) => sum + mesh.positions.length / 3, 0),
-      totalTriangles: allMeshes.reduce((sum, mesh) => sum + mesh.indices.length / 3, 0),
-      coordinateInfo: finalCoordinateInfo,
-    },
-    schemaVersion: dataStore.schemaVersion === 'IFC4X3'
-      ? 'IFC4X3'
-      : dataStore.schemaVersion === 'IFC4'
-        ? 'IFC4'
-        : 'IFC2X3',
-    allMeshes,
-    cumulativeColorUpdates,
-  };
-}

package/src/hooks/source-key.ts

@@ -0,0 +1,35 @@
+/* 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 type { IfcDataStore } from '@ifc-lite/parser';
+
+// Per-source-object memo so the full-content hash runs only once per loaded
+// buffer (the same Uint8Array instance is reused across re-renders).
+const SOURCE_KEY_CACHE = new WeakMap<Uint8Array, string>();
+
+/**
+ * Stable per-source cache key — a **full-content** FNV-1a hash (not sampled
+ * byte windows), so two distinct IFC binaries can't collide and reuse the wrong
+ * cache entry (which would render another model's overlay). The O(n) hash is
+ * memoised per source object via a WeakMap, so it runs once per loaded buffer.
+ *
+ * Shared by the per-source overlay hooks (alignment + grid lines) so they stay
+ * in lockstep — see #967 review (CodeRabbit aliasing finding applied to both).
+ */
+export function sourceKey(store: IfcDataStore | null | undefined): string | null {
+  const source = store?.source;
+  if (!source || source.byteLength === 0) return null;
+
+  const cached = SOURCE_KEY_CACHE.get(source);
+  if (cached) return cached;
+
+  let h = 0x811c9dc5;
+  for (let i = 0; i < source.length; i++) {
+    h ^= source[i];
+    h = Math.imul(h, 0x01000193);
+  }
+  const key = `b${source.byteLength}-${(h >>> 0).toString(16)}`;
+  SOURCE_KEY_CACHE.set(source, key);
+  return key;
+}

package/src/hooks/useAlignmentLines3D.ts

@@ -23,35 +23,10 @@ import { GeometryProcessor } from '@ifc-lite/geometry';
 import { useViewerStore } from '@/store';
 import { useShallow } from 'zustand/react/shallow';
 import type { IfcDataStore } from '@ifc-lite/parser';
+import { sourceKey } from './source-key.js';
 
 const EMPTY_F32 = new Float32Array(0);
 
-/**
- * Stable per-source cache key — FNV-1a over head/mid/tail byte windows folded
- * with the length, so two structurally distinct sources can't alias even when
- * they share an exact byte length (a real risk in federated views). Identical
- * scheme to `useSymbolicAnnotations`' `sourceKey`.
- */
-function sourceKey(store: IfcDataStore | null | undefined): string | null {
-  const source = store?.source;
-  if (!source || source.byteLength === 0) return null;
-  const len = source.byteLength;
-  const sampleLen = Math.min(32, len);
-  const head = source.subarray(0, sampleLen);
-  const tail = source.subarray(len - sampleLen, len);
-  const midOffset = Math.max(0, Math.floor(len / 2) - Math.floor(sampleLen / 2));
-  const mid = source.subarray(midOffset, Math.min(midOffset + sampleLen, len));
-  const hashOne = (bytes: Uint8Array): string => {
-    let h = 0x811c9dc5;
-    for (let i = 0; i < bytes.length; i++) {
-      h ^= bytes[i];
-      h = Math.imul(h, 0x01000193);
-    }
-    return (h >>> 0).toString(16);
-  };
-  return `b${len}-${hashOne(head)}-${hashOne(mid)}-${hashOne(tail)}`;
-}
-
 // ─── Shared parse cache ──────────────────────────────────────────────────────
 // One WASM walk per model source; cached so re-renders (and federated views
 // that share a source) don't re-parse.

package/src/hooks/useCompareOverlay.ts

@@ -0,0 +1,119 @@
+/* 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/. */
+
+/**
+ * Applies the model-comparison result to the 3D viewport (issue #924):
+ * per-entity colour overrides (added/modified/deleted/unchanged) plus a hidden
+ * set that suppresses the duplicated base-model geometry.
+ *
+ * Colours go through the same single overlay channel `useLens` uses
+ * (`setPendingColorUpdates` → `scene.setColorOverrides` — overlay batches drawn
+ * over the original geometry, instant to clear). The hidden set is reconciled
+ * with ownership tracking lifted from `useOverlayCompositor`: we remember which
+ * ids we hid and whether the user had already hidden them, so teardown only
+ * un-hides what we actually contributed.
+ *
+ * Mounted inside `ComparePanel`, so closing the panel (or clearing the result)
+ * restores the scene automatically.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useViewerStore } from '@/store';
+import { buildCompareOverlay } from '@/lib/compare/overlay';
+
+type ViewerStore = ReturnType<typeof useViewerStore.getState>;
+
+/** Hand the shared colour channel back to its prior owner when compare lets go:
+ *  if a lens is still active, restore its overlay; otherwise clear. Prevents the
+ *  compare panel from blanking lens colours on close (an active lens only has
+ *  its panel hidden, not deactivated). */
+function handBackColorChannel(store: ViewerStore): void {
+  const lensColors = store.lensAppliedColors;
+  store.setPendingColorUpdates(lensColors && lensColors.size > 0 ? new Map(lensColors) : new Map());
+}
+
+/** Re-show ids we hid that the user wasn't already hiding, then drop ownership. */
+function restoreOwnedHidden(owned: Map<number, boolean>, store: ViewerStore): void {
+  if (owned.size === 0) return;
+  const toShow: number[] = [];
+  for (const [id, wasHidden] of owned) {
+    if (wasHidden === false) toShow.push(id);
+  }
+  if (toShow.length > 0) store.showEntities(toShow);
+  owned.clear();
+}
+
+/** Reconcile the desired hidden set against what we previously contributed. */
+function reconcileHidden(
+  nextHidden: Set<number>,
+  ownedRef: { current: Map<number, boolean> },
+  store: ViewerStore,
+): void {
+  const prev = ownedRef.current;
+  const currentlyHidden = store.hiddenEntities ?? new Set<number>();
+
+  const toShow: number[] = [];
+  for (const [id, wasHidden] of prev) {
+    if (!nextHidden.has(id) && wasHidden === false) toShow.push(id);
+  }
+
+  const next = new Map<number, boolean>();
+  const toHide: number[] = [];
+  for (const id of nextHidden) {
+    if (prev.has(id)) {
+      next.set(id, prev.get(id)!);
+    } else {
+      const wasHidden = currentlyHidden.has(id);
+      next.set(id, wasHidden);
+      if (!wasHidden) toHide.push(id);
+    }
+  }
+
+  if (toShow.length > 0) store.showEntities(toShow);
+  if (toHide.length > 0) store.hideEntities(toHide);
+  ownedRef.current = next;
+}
+
+export function useCompareOverlay(): void {
+  // global id → "was the user already hiding this when we took over?"
+  const ownedHiddenRef = useRef<Map<number, boolean>>(new Map());
+  const colorActiveRef = useRef(false);
+
+  const compareResult = useViewerStore((s) => s.compareResult);
+  const showUnchanged = useViewerStore((s) => s.compareShowUnchanged);
+
+  useEffect(() => {
+    const store = useViewerStore.getState();
+
+    if (!compareResult) {
+      if (colorActiveRef.current) {
+        handBackColorChannel(store);
+        colorActiveRef.current = false;
+      }
+      restoreOwnedHidden(ownedHiddenRef.current, store);
+      return;
+    }
+
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(compareResult.diff, showUnchanged);
+    reconcileHidden(hiddenIds, ownedHiddenRef, store);
+    // Empty map signals the consumer to clear overlays (lens contract).
+    store.setPendingColorUpdates(colorOverrides);
+    // We own the colour channel whenever a comparison is shown — even an empty
+    // override map clobbered any prior lens colours — so teardown must hand the
+    // channel back regardless of the map size (don't gate on `.size`).
+    colorActiveRef.current = true;
+  }, [compareResult, showUnchanged]);
+
+  // Teardown on unmount (panel closed) — restore the scene we touched.
+  useEffect(() => {
+    return () => {
+      const store = useViewerStore.getState();
+      if (colorActiveRef.current) {
+        handBackColorChannel(store);
+        colorActiveRef.current = false;
+      }
+      restoreOwnedHidden(ownedHiddenRef.current, store);
+    };
+  }, []);
+}

package/src/hooks/useDrawingGeneration.ts

@@ -179,18 +179,29 @@ export function useDrawingGeneration({
           try {
             await processor.init();
 
+            // SymbolicRepresentationCollection and each getPolyline/getCircle
+            // item are wasm-bindgen handles owning WASM memory — free them
+            // deterministically (AGENTS.md §7). Leaking them to GC lets the
+            // FinalizationRegistry free them later against an already-grown/
+            // reused shared dlmalloc heap, corrupting the allocator free-list.
             const symbolicCollection = processor.parseSymbolicRepresentations(ifcDataStore!.source);
             // For single-model (legacy) mode, model index is always 0
             // Multi-model symbolic parsing would require iterating over each model separately
             const symbolicModelIndex = 0;
 
-            if (symbolicCollection && !symbolicCollection.isEmpty) {
+            if (symbolicCollection) {
+              try {
+                if (!symbolicCollection.isEmpty) {
               // Process polylines
               for (let i = 0; i < symbolicCollection.polylineCount; i++) {
                 const poly = symbolicCollection.getPolyline(i);
                 if (!poly) continue;
+                try {
 
                 entitiesWithSymbols.add(poly.expressId);
+                // poly.points is consumed synchronously within this iteration
+                // (centroid sum + segment pushes read scalar values out of it);
+                // the array itself is never stored, so no copy is needed.
                 const points = poly.points;
                 const pointCount = poly.pointCount;
                 // WASM exposes `worldY` on every symbolic primitive — the
@@ -249,12 +260,16 @@ export function useDrawingGeneration({
                     worldZ: polyWorldZ,
                   });
                 }
+                } finally {
+                  poly.free();
+                }
               }
 
               // Process circles/arcs
               for (let i = 0; i < symbolicCollection.circleCount; i++) {
                 const circle = symbolicCollection.getCircle(i);
                 if (!circle) continue;
+                try {
 
                 entitiesWithSymbols.add(circle.expressId);
                 const numSegments = circle.isFullCircle ? 32 : 16;
@@ -293,6 +308,13 @@ export function useDrawingGeneration({
                     worldZ: circleWorldZ,
                   });
                 }
+                } finally {
+                  circle.free();
+                }
+              }
+                }
+              } finally {
+                symbolicCollection.free();
               }
             }
           } finally {

package/src/hooks/useGridLines3D.ts

@@ -0,0 +1,140 @@
+/* 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/. */
+
+/**
+ * Extraction of IfcGrid / IfcGridAxis centerlines for the 3D viewport
+ * (issue #967, follow-up to #945/#966).
+ *
+ * IfcGrid carries its axes as IfcGridAxis curves (not a `Representation`), so
+ * they never produce a mesh in the streaming batch mesher. The WASM
+ * `parseGridLines` API resolves every axis through the same placement +
+ * unit-scale + RTC pipeline as the meshes and returns a flat 3D line-list in
+ * renderer Y-up world space, which we feed to `renderer.uploadGridLines3D`.
+ * This mirrors `useAlignmentLines3D`.
+ *
+ * Unlike alignment (always-on), grids are gated by the `ifcGrid` type-visibility
+ * toggle — but the parse itself is unconditional and cached; the Viewport only
+ * uploads/clears based on the toggle.
+ */
+
+import { useEffect, useMemo, useState } from 'react';
+import { GeometryProcessor } from '@ifc-lite/geometry';
+import { useViewerStore } from '@/store';
+import { useShallow } from 'zustand/react/shallow';
+import type { IfcDataStore } from '@ifc-lite/parser';
+import { sourceKey } from './source-key.js';
+
+const EMPTY_F32 = new Float32Array(0);
+
+// ─── Shared parse cache ──────────────────────────────────────────────────────
+// One WASM walk per model source; cached so re-renders (and federated views
+// that share a source) don't re-parse.
+const PARSE_CACHE = new Map<string, Float32Array>();
+const PARSE_INFLIGHT = new Map<string, Promise<void>>();
+
+type CacheListener = () => void;
+const CACHE_LISTENERS = new Set<CacheListener>();
+function notifyCacheChange(): void {
+  for (const fn of CACHE_LISTENERS) fn();
+}
+
+async function parseGridLinesFor(store: IfcDataStore): Promise<Float32Array> {
+  const source = store.source;
+  if (!source || source.byteLength === 0) return EMPTY_F32;
+  const processor = new GeometryProcessor();
+  try {
+    await processor.init();
+    const verts = processor.parseGridLines(source);
+    return verts && verts.length > 0 ? verts : EMPTY_F32;
+  } finally {
+    processor.dispose();
+  }
+}
+
+function ensureParseFor(stores: IfcDataStore[]): void {
+  for (const store of stores) {
+    const key = sourceKey(store);
+    if (!key) continue;
+    if (PARSE_CACHE.has(key)) continue;
+    if (PARSE_INFLIGHT.has(key)) continue;
+
+    const promise = (async () => {
+      try {
+        const verts = await parseGridLinesFor(store);
+        PARSE_CACHE.set(key, verts);
+        notifyCacheChange();
+      } catch (error) {
+        // Cache empty on failure so we don't retry a doomed parse every tick.
+        // eslint-disable-next-line no-console
+        console.warn('[useGridLines3D] parse failed:', error);
+        PARSE_CACHE.set(key, EMPTY_F32);
+        notifyCacheChange();
+      } finally {
+        PARSE_INFLIGHT.delete(key);
+      }
+    })();
+    PARSE_INFLIGHT.set(key, promise);
+  }
+}
+
+/** Read the active store set from the viewer store. Federation-aware. */
+function useActiveStores(): IfcDataStore[] {
+  const { models, ifcDataStore } = useViewerStore(
+    useShallow((s) => ({ models: s.models, ifcDataStore: s.ifcDataStore })),
+  );
+  return useMemo(() => {
+    const out: IfcDataStore[] = [];
+    if (models.size > 0) {
+      for (const [, m] of models) if (m.ifcDataStore) out.push(m.ifcDataStore);
+    } else if (ifcDataStore) {
+      out.push(ifcDataStore);
+    }
+    return out;
+  }, [models, ifcDataStore]);
+}
+
+/**
+ * Sample every loaded model's IfcGridAxis lines into a single flat
+ * `[x0,y0,z0, x1,y1,z1, …]` line-list in renderer world space (Y-up,
+ * RTC-subtracted, metres). Returns a stable empty array when no model carries a
+ * grid. Parsing is unconditional + cached; the Viewport gates rendering on the
+ * `ifcGrid` type-visibility toggle.
+ */
+export function useGridLines3D(): Float32Array {
+  const stores = useActiveStores();
+  const [version, setVersion] = useState(0);
+
+  useEffect(() => {
+    ensureParseFor(stores);
+    const listener: CacheListener = () => setVersion((v) => v + 1);
+    CACHE_LISTENERS.add(listener);
+    return () => {
+      CACHE_LISTENERS.delete(listener);
+    };
+  }, [stores]);
+
+  return useMemo(() => {
+    void version; // depend on parse-completion ticks
+    const arrays: Float32Array[] = [];
+    let total = 0;
+    for (const store of stores) {
+      const key = sourceKey(store);
+      if (!key) continue;
+      const cached = PARSE_CACHE.get(key);
+      if (cached && cached.length > 0) {
+        arrays.push(cached);
+        total += cached.length;
+      }
+    }
+    if (total === 0) return EMPTY_F32;
+    if (arrays.length === 1) return arrays[0];
+    const merged = new Float32Array(total);
+    let offset = 0;
+    for (const a of arrays) {
+      merged.set(a, offset);
+      offset += a.length;
+    }
+    return merged;
+  }, [stores, version]);
+}

package/src/hooks/useIfc.ts

@@ -82,7 +82,7 @@ export function useIfc() {
     findModelForEntity,
     resolveGlobalId,
     realignFederation,
-  } = useIfcFederation();
+  } = useIfcFederation(loadFile);
 
   // Memoize query to prevent recreation on every render
   // For single-model backward compatibility