@ifc-lite/viewer 1.25.1 → 1.25.2

package/src/hooks/useIfcCache.ts

@@ -13,10 +13,11 @@ import { useCallback } from 'react';
 import {
   BinaryCacheWriter,
   BinaryCacheReader,
+  type CachedEntityIndexColumns,
   type IfcDataStore as CacheDataStore,
   type GeometryData,
 } from '@ifc-lite/cache';
-import { SpatialHierarchyBuilder, StepTokenizer, CompactEntityIndexBuilder, extractLengthUnitScale, type IfcDataStore } from '@ifc-lite/parser';
+import { SpatialHierarchyBuilder, StepTokenizer, CompactEntityIndex, CompactEntityIndexBuilder, extractLengthUnitScale, type IfcDataStore } from '@ifc-lite/parser';
 import { buildSpatialIndexGuarded } from '../utils/loadingUtils.js';
 import type { MeshData } from '@ifc-lite/geometry';
 
@@ -30,6 +31,27 @@ import { calculateStoreyHeights } from '../utils/localParsingUtils.js';
 export type { CacheResult } from '../services/cacheService.js';
 export { getCached, setCached, deleteCached } from '../services/cacheService.js';
 
+function buildEntityIndexFromCachedColumns(columns: CachedEntityIndexColumns): IfcDataStore['entityIndex'] {
+  const byId = new CompactEntityIndex(
+    columns.ids,
+    columns.byteOffsets,
+    columns.byteLengths,
+    columns.typeIndices,
+    columns.typeNames,
+  );
+  const byType = new Map<string, number[]>();
+  for (let i = 0; i < columns.ids.length; i++) {
+    const type = columns.typeNames[columns.typeIndices[i]];
+    let ids = byType.get(type);
+    if (!ids) {
+      ids = [];
+      byType.set(type, ids);
+    }
+    ids.push(columns.ids[i]);
+  }
+  return { byId, byType };
+}
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -107,25 +129,28 @@ export function useIfcCache() {
       if (cacheResult.sourceBuffer) {
         dataStore.source = new Uint8Array(cacheResult.sourceBuffer);
 
-        // Quick scan to rebuild entity index with byte offsets (needed for on-demand extraction).
-        // Uses CompactEntityIndexBuilder to fill typed arrays directly during the scan,
-        // avoiding a temporary array of 4.4M+ objects (~350MB for large files).
-        const tokenizer = new StepTokenizer(dataStore.source);
-        const estimatedCount = dataStore.entities?.count ?? 100_000;
-        const indexBuilder = new CompactEntityIndexBuilder(estimatedCount);
-        const byType = new Map<string, number[]>();
-
-        for (const ref of tokenizer.scanEntitiesFast()) {
-          indexBuilder.add(ref.expressId, ref.type, ref.offset, ref.length);
-          let typeList = byType.get(ref.type);
-          if (!typeList) {
-            typeList = [];
-            byType.set(ref.type, typeList);
+        if (result.entityIndex) {
+          dataStore.entityIndex = buildEntityIndexFromCachedColumns(result.entityIndex);
+        } else {
+          // Backward compatibility for v3 caches: rebuild byte offsets from the
+          // source once, then future v4 writes persist this section.
+          const tokenizer = new StepTokenizer(dataStore.source);
+          const estimatedCount = dataStore.entities?.count ?? 100_000;
+          const indexBuilder = new CompactEntityIndexBuilder(estimatedCount);
+          const byType = new Map<string, number[]>();
+
+          for (const ref of tokenizer.scanEntitiesFast()) {
+            indexBuilder.add(ref.expressId, ref.type, ref.offset, ref.length);
+            let typeList = byType.get(ref.type);
+            if (!typeList) {
+              typeList = [];
+              byType.set(ref.type, typeList);
+            }
+            typeList.push(ref.expressId);
           }
-          typeList.push(ref.expressId);
+          const compactByIdIndex = indexBuilder.build();
+          dataStore.entityIndex = { byId: compactByIdIndex, byType };
         }
-        const compactByIdIndex = indexBuilder.build();
-        dataStore.entityIndex = { byId: compactByIdIndex, byType };
 
         // Rebuild on-demand maps from relationships
         // Pass entityIndex which contains ALL entity types including IfcPropertySet/IfcElementQuantity
@@ -254,6 +279,7 @@ export function useIfcCache() {
         quantities: dataStore.quantities,
         relationships: dataStore.relationships,
         spatialHierarchy: dataStore.spatialHierarchy,
+        entityIndex: dataStore.entityIndex,
       };
 
       console.log('[useIfcCache] Writing cache buffer...');

package/src/hooks/useIfcLoader.ts

@@ -1905,7 +1905,7 @@ export function useIfcLoader() {
         // risking corruption.
         const parserWasmApi = isNativeFileHandle(file) ? undefined : geometryProcessor.getApi();
         return new IfcParser().parseColumnar(buffer, {
-          wasmApi: parserWasmApi,
+          wasmApi: parserWasmApi ?? undefined,
           onSpatialReady: onPartialDataStore,
         });
       };
@@ -2032,34 +2032,12 @@ export function useIfcLoader() {
         // When the parser worker is in use, hand the geometry workers the
         // same SAB so we don't pay the file-bytes copy twice.
         const geometryView = sharedSource ? new Uint8Array(sharedSource) : new Uint8Array(buffer);
-        // Phase 2 of single-controller-rayon-design.md — opt-in via
-        // localStorage so we can A/B compare against the N-worker
-        // baseline without rolling out for everyone. Users (and the
-        // benchmark harness) flip this with:
-        //   localStorage.setItem('ifc-lite:single-controller', '1')
-        // and reload. Set to anything else (or unset) for the legacy
-        // N-worker path. Safe: if the threaded WASM bundle fails to
-        // load (no COI, Safari, etc.) the controller worker falls back
-        // to per-task serial execution within the controller itself
-        // (par_iter without an initialized pool).
-        const useSingleController = (() => {
-          try {
-            return typeof localStorage !== 'undefined'
-              && localStorage.getItem('ifc-lite:single-controller') === '1';
-          } catch {
-            return false;
-          }
-        })();
-        if (useSingleController) {
-          console.log('[useIfc] single-controller path enabled (Phase 2)');
-        }
         const geometryEvents = shouldUseDesktopStableWasmGeometry
           ? geometryProcessor.processStreaming(geometryView, undefined, dynamicBatchConfig)
           : geometryProcessor.processAdaptive(geometryView, {
               sizeThreshold: 2 * 1024 * 1024, // 2MB threshold
               batchSize: dynamicBatchConfig, // Dynamic batches: small first, then large
               existingSab: sharedSource ?? undefined,
-              useSingleController,
               // Hand the streaming pre-pass's entity index to the parser
               // worker so it skips a duplicate ~10 s WASM scan. Safe even
               // when the parser falls back to main-thread (instance is

package/src/hooks/useSymbolicAnnotations.ts

@@ -91,13 +91,31 @@ export interface AnnotationFill2D {
   };
 }
 
-/** Cached parse result keyed by source identity. */
+/** Cached parse result keyed by source identity.
+ *
+ * IfcAnnotation and IfcGridAxis primitives are stored in PARALLEL bucket
+ * collections (issue #862). They share the same parse pass and the same
+ * storey-resolution logic, but the renderer treats them differently:
+ *
+ *   - Annotation buckets always lift every storey (memory
+ *     `feedback_3d_annotation_overlay_no_section_filter.md`: the user
+ *     expects every storey's dimensions to be visible in 3D).
+ *   - Grid buckets get optional section-plane filtering and an
+ *     independent visibility toggle, so dense-grid models can hide
+ *     grids per storey without losing dimensions.
+ */
 interface ParseResult {
+  // IfcAnnotation buckets
   byStorey: Map<number, AnnotationsForStorey>;
-  /** Annotations with no resolvable storey — shown on every floor as a fallback. */
   loose: DrawingLine2D[];
   looseTexts: AnnotationText2D[];
   looseFills: AnnotationFill2D[];
+
+  // IfcGridAxis buckets (issue #862)
+  gridByStorey: Map<number, AnnotationsForStorey>;
+  gridLoose: DrawingLine2D[];
+  gridLooseTexts: AnnotationText2D[];
+  gridLooseFills: AnnotationFill2D[];
 }
 
 const CIRCLE_SEGMENTS_FULL = 32;
@@ -212,6 +230,10 @@ async function parseAnnotations(
     loose: [],
     looseTexts: [],
     looseFills: [],
+    gridByStorey: new Map(),
+    gridLoose: [],
+    gridLooseTexts: [],
+    gridLooseFills: [],
   };
   const source = store.source;
   if (!source || source.byteLength === 0) {
@@ -256,6 +278,7 @@ async function parseAnnotations(
     const ensureBucket = (
       expressId: number,
       primitiveWorldY: number,
+      ifcType: string,
     ): AnnotationsForStorey | null => {
       let effectiveY: number | null = null;
       if (Number.isFinite(primitiveWorldY) && primitiveWorldY !== 0) {
@@ -269,7 +292,11 @@ async function parseAnnotations(
       }
       if (effectiveY === null) return null;
       const key = Math.round(effectiveY * 1000);
-      let bucket = result.byStorey.get(key);
+      // Issue #862: IfcGridAxis primitives land in a parallel bucket
+      // collection so the renderer can section-clip + visibility-toggle
+      // them independently of IfcAnnotation (text/dimension symbols).
+      const storeyMap = ifcType === 'IfcGridAxis' ? result.gridByStorey : result.byStorey;
+      let bucket = storeyMap.get(key);
       if (!bucket) {
         bucket = {
           storeyId: key,
@@ -278,7 +305,7 @@ async function parseAnnotations(
           texts: [],
           fills: [],
         };
-        result.byStorey.set(key, bucket);
+        storeyMap.set(key, bucket);
       }
       return bucket;
     };
@@ -287,8 +314,9 @@ async function parseAnnotations(
       const poly = collection.getPolyline(i);
       if (!poly) continue;
       if (poly.ifcType !== 'IfcAnnotation' && poly.ifcType !== 'IfcGridAxis') continue;
-      const bucket = ensureBucket(poly.expressId, poly.worldY);
-      const out = bucket ? bucket.lines : result.loose;
+      const bucket = ensureBucket(poly.expressId, poly.worldY, poly.ifcType);
+      const looseTarget = poly.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
+      const out = bucket ? bucket.lines : looseTarget;
       polylineToSegments(poly.points, poly.pointCount, poly.isClosed, out);
     }
 
@@ -296,8 +324,9 @@ async function parseAnnotations(
       const circle = collection.getCircle(i);
       if (!circle) continue;
       if (circle.ifcType !== 'IfcAnnotation' && circle.ifcType !== 'IfcGridAxis') continue;
-      const bucket = ensureBucket(circle.expressId, circle.worldY);
-      const out = bucket ? bucket.lines : result.loose;
+      const bucket = ensureBucket(circle.expressId, circle.worldY, circle.ifcType);
+      const looseTarget = circle.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
+      const out = bucket ? bucket.lines : looseTarget;
       circleToSegments(
         circle.centerX,
         circle.centerY,
@@ -335,7 +364,8 @@ async function parseAnnotations(
       // Industry-standard line-spacing (CSS line-height ≈ 1.2). Picks up
       // a little air between rows so descenders don't kiss the next cap.
       const lineSpacing = perLineHeight * 1.2;
-      const bucket = ensureBucket(text.expressId, text.worldY);
+      const bucket = ensureBucket(text.expressId, text.worldY, text.ifcType);
+      const looseTextTarget = text.ifcType === 'IfcGridAxis' ? result.gridLooseTexts : result.looseTexts;
       // All annotation text — grid bubbles, dimension callouts, leader labels —
       // billboards to the camera so it stays legible in any view orientation
       // (top-down, eye-level, oblique). The shader rebuilds the quad in the
@@ -366,7 +396,7 @@ async function parseAnnotations(
           color: textColor,
           targetPx,
         };
-        (bucket ? bucket.texts : result.looseTexts).push(t2d);
+        (bucket ? bucket.texts : looseTextTarget).push(t2d);
       }
     }
 
@@ -389,8 +419,9 @@ async function parseAnnotations(
             }
           : undefined,
       };
-      const bucket = ensureBucket(fill.expressId, fill.worldY);
-      (bucket ? bucket.fills : result.looseFills).push(f2d);
+      const bucket = ensureBucket(fill.expressId, fill.worldY, fill.ifcType);
+      const looseFillTarget = fill.ifcType === 'IfcGridAxis' ? result.gridLooseFills : result.looseFills;
+      (bucket ? bucket.fills : looseFillTarget).push(f2d);
     }
   } finally {
     processor.dispose();
@@ -521,17 +552,48 @@ function resolveBucketY(elevation: number | null, fallbackY: number): number {
   return elevation === null ? fallbackY : elevation;
 }
 
+/** Section-clip parameters for grid lines (issue #862). Grids ARE clipped
+ *  by the active section plane; IfcAnnotation overlays are NOT (per the
+ *  feedback_3d_annotation_overlay_no_section_filter memory). When
+ *  `enabled === false` no clipping happens — grids lift to every storey
+ *  same as annotations.
+ */
+export interface SectionClipForGrid {
+  enabled: boolean;
+  /** World coord on the cut axis (e.g. world-Y for axis='down'). */
+  posWorld: number;
+  /** Half-thickness of the visible band around the cut, world units. */
+  viewDepth: number;
+  /** Cut axis. Only `'down'` performs vertical clipping; other axes pass through unfiltered (grid lines are vertical and don't project meaningfully onto elevation cuts). */
+  axis: 'down' | 'front' | 'side';
+}
+
 export function useSymbolicAnnotations(params: {
+  /** Enable IfcAnnotation lift (the existing default behaviour). */
   enabled: boolean;
+  /**
+   * Enable IfcGrid lift. Independent of `enabled` so a user can hide
+   * annotations while keeping grids, or vice versa (issue #862).
+   * Defaults to `enabled` so existing call sites that don't set it
+   * keep the legacy combined behaviour.
+   */
+  gridEnabled?: boolean;
+  /** Section clipping for grids only — see [`SectionClipForGrid`]. */
+  gridSectionClip?: SectionClipForGrid;
   /** World Y to use for annotations with no resolvable storey. Defaults to 0. */
   fallbackY?: number;
 }): Float32Array {
-  const { enabled, fallbackY = 0 } = params;
+  const { enabled, gridEnabled, gridSectionClip, fallbackY = 0 } = params;
+  const effectiveGridEnabled = gridEnabled ?? enabled;
   const stores = useActiveStores();
-  const version = useAnnotationParseTrigger(enabled, stores);
+  // Trigger parse if EITHER subset is enabled — the parse pass is shared.
+  const version = useAnnotationParseTrigger(enabled || effectiveGridEnabled, stores);
+  const clipEnabled = !!gridSectionClip && gridSectionClip.enabled && gridSectionClip.axis === 'down';
+  const clipPos = clipEnabled ? gridSectionClip!.posWorld : 0;
+  const clipDepth = clipEnabled ? gridSectionClip!.viewDepth : 0;
 
   return useMemo(() => {
-    if (!enabled) return EMPTY_F32;
+    if (!enabled && !effectiveGridEnabled) return EMPTY_F32;
     void version; // depend on parse-completion ticks
 
     const verts: number[] = [];
@@ -546,22 +608,49 @@ export function useSymbolicAnnotations(params: {
         continue;
       }
       if (debugEnabled()) {
-        const buckets = cached.byStorey.size;
-        const looseLines = cached.loose.length;
-        console.log(`[annotations] store ${storeIdx}: lifting ${buckets} storey buckets + ${looseLines} loose lines (key=${key}, fallbackY=${fallbackY})`);
+        console.log(
+          `[annotations] store ${storeIdx}: annotation buckets=${cached.byStorey.size}+${cached.loose.length}loose, grid buckets=${cached.gridByStorey.size}+${cached.gridLoose.length}loose (annot=${enabled}, grid=${effectiveGridEnabled}, clip=${clipEnabled})`,
+        );
+      }
+
+      if (enabled) {
+        for (const bucket of cached.byStorey.values()) {
+          liftTo3DLineList(bucket.lines, resolveBucketY(bucket.storeyElevation, fallbackY), verts);
+        }
+        liftTo3DLineList(cached.loose, fallbackY, verts);
       }
 
-      for (const bucket of cached.byStorey.values()) {
-        liftTo3DLineList(bucket.lines, resolveBucketY(bucket.storeyElevation, fallbackY), verts);
+      if (effectiveGridEnabled) {
+        // Issue #862: section-clip grid buckets only — IfcAnnotation
+        // intentionally bypasses this per the feedback memory ("the
+        // user expects every storey's dimensions/grid bubbles to lift
+        // into the viewport when [the annotation toggle is] on, even
+        // while a section cut is active").
+        if (clipEnabled) {
+          const lo = clipPos - clipDepth;
+          const hi = clipPos + clipDepth;
+          for (const bucket of cached.gridByStorey.values()) {
+            const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+            if (y < lo || y > hi) continue;
+            liftTo3DLineList(bucket.lines, y, verts);
+          }
+          if (fallbackY >= lo && fallbackY <= hi) {
+            liftTo3DLineList(cached.gridLoose, fallbackY, verts);
+          }
+        } else {
+          for (const bucket of cached.gridByStorey.values()) {
+            liftTo3DLineList(bucket.lines, resolveBucketY(bucket.storeyElevation, fallbackY), verts);
+          }
+          liftTo3DLineList(cached.gridLoose, fallbackY, verts);
+        }
       }
-      liftTo3DLineList(cached.loose, fallbackY, verts);
       storeIdx++;
     }
 
     if (debugEnabled()) console.log(`[annotations] total 3D line vertices: ${verts.length / 3} from ${stores.length} stores`);
     if (verts.length === 0) return EMPTY_F32;
     return new Float32Array(verts);
-  }, [enabled, stores, version, fallbackY]);
+  }, [enabled, effectiveGridEnabled, clipEnabled, clipPos, clipDepth, stores, version, fallbackY]);
 }
 
 /**
@@ -723,13 +812,19 @@ export function useSymbolicAnnotationsForDrawing(params: {
       const cached = PARSE_CACHE.get(key);
       if (!cached) continue;
 
-      for (const bucket of cached.byStorey.values()) {
+      // Drawing-2D pulls BOTH annotation and grid buckets (issue #862
+      // split them at parse time so the 3D viewport can clip them
+      // separately — the 2D Section panel still wants the combined
+      // overlay).
+      const collectBucket = (bucket: AnnotationsForStorey) => {
         const bucketY = resolveBucketY(bucket.storeyElevation, fallbackY);
-        if (bucketY < rangeMin || bucketY > rangeMax) continue;
+        if (bucketY < rangeMin || bucketY > rangeMax) return;
         for (const ln of bucket.lines) pushLine(ln);
         for (const t of bucket.texts) pushText(t);
         for (const f of bucket.fills) pushFill(f);
-      }
+      };
+      for (const bucket of cached.byStorey.values()) collectBucket(bucket);
+      for (const bucket of cached.gridByStorey.values()) collectBucket(bucket);
 
       // Loose annotations have no resolvable storey — include them if the
       // fallback Y lands in the view range. That keeps malformed exports
@@ -739,6 +834,9 @@ export function useSymbolicAnnotationsForDrawing(params: {
         for (const ln of cached.loose) pushLine(ln);
         for (const t of cached.looseTexts) pushText(t);
         for (const f of cached.looseFills) pushFill(f);
+        for (const ln of cached.gridLoose) pushLine(ln);
+        for (const t of cached.gridLooseTexts) pushText(t);
+        for (const f of cached.gridLooseFills) pushFill(f);
       }
     }
 
@@ -757,14 +855,24 @@ export function useSymbolicAnnotationsForDrawing(params: {
  */
 export function useSymbolicAnnotationsRichData(params: {
   enabled: boolean;
+  /** Lift grid-bubble texts + fills. Independent of `enabled` (issue #862).
+   *  Defaults to `enabled` for legacy callers. */
+  gridEnabled?: boolean;
+  /** Section clipping for grid texts/fills only — same semantics as
+   *  [`useSymbolicAnnotations`]. */
+  gridSectionClip?: SectionClipForGrid;
   fallbackY?: number;
 }): { texts: readonly AnnotationText3D[]; fills: readonly AnnotationFill3D[] } {
-  const { enabled, fallbackY = 0 } = params;
+  const { enabled, gridEnabled, gridSectionClip, fallbackY = 0 } = params;
+  const effectiveGridEnabled = gridEnabled ?? enabled;
   const stores = useActiveStores();
-  const version = useAnnotationParseTrigger(enabled, stores);
+  const version = useAnnotationParseTrigger(enabled || effectiveGridEnabled, stores);
+  const clipEnabled = !!gridSectionClip && gridSectionClip.enabled && gridSectionClip.axis === 'down';
+  const clipPos = clipEnabled ? gridSectionClip!.posWorld : 0;
+  const clipDepth = clipEnabled ? gridSectionClip!.viewDepth : 0;
 
   return useMemo(() => {
-    if (!enabled) return { texts: EMPTY_TEXTS, fills: EMPTY_FILLS };
+    if (!enabled && !effectiveGridEnabled) return { texts: EMPTY_TEXTS, fills: EMPTY_FILLS };
     void version;
 
     const texts: AnnotationText3D[] = [];
@@ -803,18 +911,45 @@ export function useSymbolicAnnotationsRichData(params: {
         });
       };
 
-      for (const bucket of cached.byStorey.values()) {
-        const y = resolveBucketY(bucket.storeyElevation, fallbackY);
-        for (const t of bucket.texts) pushText(t, y);
-        for (const f of bucket.fills) pushFill(f, y);
+      if (enabled) {
+        for (const bucket of cached.byStorey.values()) {
+          const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+          for (const t of bucket.texts) pushText(t, y);
+          for (const f of bucket.fills) pushFill(f, y);
+        }
+        for (const t of cached.looseTexts) pushText(t, fallbackY);
+        for (const f of cached.looseFills) pushFill(f, fallbackY);
+      }
+
+      if (effectiveGridEnabled) {
+        if (clipEnabled) {
+          const lo = clipPos - clipDepth;
+          const hi = clipPos + clipDepth;
+          for (const bucket of cached.gridByStorey.values()) {
+            const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+            if (y < lo || y > hi) continue;
+            for (const t of bucket.texts) pushText(t, y);
+            for (const f of bucket.fills) pushFill(f, y);
+          }
+          if (fallbackY >= lo && fallbackY <= hi) {
+            for (const t of cached.gridLooseTexts) pushText(t, fallbackY);
+            for (const f of cached.gridLooseFills) pushFill(f, fallbackY);
+          }
+        } else {
+          for (const bucket of cached.gridByStorey.values()) {
+            const y = resolveBucketY(bucket.storeyElevation, fallbackY);
+            for (const t of bucket.texts) pushText(t, y);
+            for (const f of bucket.fills) pushFill(f, y);
+          }
+          for (const t of cached.gridLooseTexts) pushText(t, fallbackY);
+          for (const f of cached.gridLooseFills) pushFill(f, fallbackY);
+        }
       }
-      for (const t of cached.looseTexts) pushText(t, fallbackY);
-      for (const f of cached.looseFills) pushFill(f, fallbackY);
     }
 
     return {
       texts: texts.length ? texts : EMPTY_TEXTS,
       fills: fills.length ? fills : EMPTY_FILLS,
     };
-  }, [enabled, stores, version, fallbackY]);
+  }, [enabled, effectiveGridEnabled, clipEnabled, clipPos, clipDepth, stores, version, fallbackY]);
 }

package/src/store/constants.ts

@@ -159,6 +159,7 @@ export const TYPE_VISIBILITY_STORAGE_KEYS = {
   openings:       'ifc-lite-ifc-openings-visible',
   site:           'ifc-lite-ifc-site-visible',
   ifcAnnotations: 'ifc-lite-ifc-annotations-visible',
+  ifcGrid:        'ifc-lite-ifc-grid-visible',
 } as const;
 
 /** Legacy alias — kept until external callers migrate. */
@@ -178,13 +179,16 @@ function readPersistedBool(key: string, fallback: boolean): boolean {
 
 // Semantic defaults applied when no localStorage preference is set.
 // IfcSpace / IfcOpeningElement off — they cover walls and confuse novices
-// on first load. IfcSite + IfcAnnotation/IfcGrid on — both convey
-// design intent users expect to see by default.
+// on first load. IfcSite + IfcAnnotation + IfcGrid on — all three convey
+// design intent users expect to see by default. (Issue #862 split grid
+// into its own toggle so dense-grid models can hide grids without losing
+// dimensions/labels.)
 const SEMANTIC_DEFAULTS = {
   spaces: false,
   openings: false,
   site: true,
   ifcAnnotations: true,
+  ifcGrid: true,
 } as const;
 
 export const TYPE_VISIBILITY_DEFAULTS = {
@@ -194,8 +198,20 @@ export const TYPE_VISIBILITY_DEFAULTS = {
   OPENINGS:        readPersistedBool(TYPE_VISIBILITY_STORAGE_KEYS.openings, SEMANTIC_DEFAULTS.openings),
   /** IfcSite visibility — persisted across reloads. */
   SITE:            readPersistedBool(TYPE_VISIBILITY_STORAGE_KEYS.site, SEMANTIC_DEFAULTS.site),
-  /** IfcAnnotation + IfcGrid visibility — persisted across reloads. */
+  /** IfcAnnotation visibility (text, dimensions, leaders) — persisted. */
   IFC_ANNOTATIONS: readPersistedBool(TYPE_VISIBILITY_STORAGE_KEYS.ifcAnnotations, SEMANTIC_DEFAULTS.ifcAnnotations),
+  /**
+   * IfcGrid visibility (axis lines + bubble tags) — persisted. Issue
+   * #862. Migration: if the new key isn't set yet, fall back to the
+   * legacy combined `ifcAnnotations` preference. That way a user who
+   * previously turned the combined "Annotations & Grids" toggle off
+   * keeps grids hidden after upgrade, instead of grids silently
+   * reappearing (PR #868 review, chatgpt-codex P2).
+   */
+  IFC_GRID:        readPersistedBool(
+    TYPE_VISIBILITY_STORAGE_KEYS.ifcGrid,
+    readPersistedBool(TYPE_VISIBILITY_STORAGE_KEYS.ifcAnnotations, SEMANTIC_DEFAULTS.ifcGrid),
+  ),
 } as const;
 
 // ============================================================================

package/src/store/index.ts

@@ -208,6 +208,7 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
         openings: TYPE_VISIBILITY_DEFAULTS.OPENINGS,
         site: TYPE_VISIBILITY_DEFAULTS.SITE,
         ifcAnnotations: TYPE_VISIBILITY_DEFAULTS.IFC_ANNOTATIONS,
+        ifcGrid: TYPE_VISIBILITY_DEFAULTS.IFC_GRID,
       },
 
       // Visibility (multi-model)

package/src/store/slices/visibilitySlice.ts

@@ -43,7 +43,7 @@ export interface VisibilitySlice {
   clearAllFilters: () => void;
   showAll: () => void;
   isEntityVisible: (id: number) => boolean;
-  toggleTypeVisibility: (type: 'spaces' | 'openings' | 'site' | 'ifcAnnotations') => void;
+  toggleTypeVisibility: (type: 'spaces' | 'openings' | 'site' | 'ifcAnnotations' | 'ifcGrid') => void;
   /** Set all hidden entities at once (for BCF viewpoint application) */
   setHiddenEntities: (ids: Set<number>) => void;
   /** Set all isolated entities at once (for BCF viewpoint with defaultVisibility=false) */
@@ -80,6 +80,7 @@ export const createVisibilitySlice: StateCreator<VisibilitySlice, [], [], Visibi
     openings: TYPE_VISIBILITY_DEFAULTS.OPENINGS,
     site: TYPE_VISIBILITY_DEFAULTS.SITE,
     ifcAnnotations: TYPE_VISIBILITY_DEFAULTS.IFC_ANNOTATIONS,
+    ifcGrid: TYPE_VISIBILITY_DEFAULTS.IFC_GRID,
   },
 
   // Initial state (multi-model)

package/src/store/types.ts

@@ -199,6 +199,15 @@ export interface TypeVisibility {
   site: boolean;
   /** IfcAnnotation (2D symbolic curves) - on by default when present */
   ifcAnnotations: boolean;
+  /**
+   * IfcGrid axis lines + bubble tags — split from `ifcAnnotations`
+   * (issue #862). Default true to match the legacy combined behaviour;
+   * users with dense grids that obscure components can hide grids while
+   * keeping annotations on. Unlike `ifcAnnotations`, grids are also
+   * section-clipped when a 3D section plane is active so each storey's
+   * grid lines only show for storeys near the cut.
+   */
+  ifcGrid: boolean;
 }
 
 // ============================================================================

package/src/utils/serverDataModel.test.ts

@@ -5,7 +5,7 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import type { DataModel } from '@ifc-lite/server-client';
-import { IfcTypeEnum } from '@ifc-lite/data';
+import { IfcTypeEnum, RelationshipType } from '@ifc-lite/data';
 import { convertServerDataModel, type ServerParseResult } from './serverDataModel';
 
 const parseResult: ServerParseResult = {
@@ -87,4 +87,54 @@ describe('convertServerDataModel', () => {
     assert.deepEqual(dataStore.spatialHierarchy?.getPath(4).map((node) => node.expressId), [1, 2, 3]);
     assert.deepEqual(dataStore.spatialHierarchy?.byBuilding.get(2), []);
   });
+
+  it('uses the canonical parser relationship map for server relationships', () => {
+    const dataModel: DataModel = {
+      entities: new Map([
+        [1, { entity_id: 1, type_name: 'IFCPROJECT', global_id: '0', name: 'Project', has_geometry: false }],
+        [2, { entity_id: 2, type_name: 'IFCBUILDING', global_id: '1', name: 'Building', has_geometry: false }],
+        [3, { entity_id: 3, type_name: 'IFCDOCUMENTREFERENCE', global_id: '', name: 'Spec', has_geometry: false }],
+      ]),
+      propertySets: new Map(),
+      quantitySets: new Map(),
+      relationships: [
+        { rel_type: 'IFCRELNESTS', relating_id: 1, related_id: 2 },
+        { rel_type: 'IFCRELASSOCIATESDOCUMENT', relating_id: 3, related_id: 2 },
+      ],
+      spatialHierarchy: {
+        nodes: [
+          {
+            entity_id: 1,
+            parent_id: 0,
+            level: 0,
+            path: 'Project',
+            type_name: 'IFCPROJECT',
+            name: 'Project',
+            children_ids: [2],
+            element_ids: [],
+          },
+          {
+            entity_id: 2,
+            parent_id: 1,
+            level: 1,
+            path: 'Project/Building',
+            type_name: 'IFCBUILDING',
+            name: 'Building',
+            children_ids: [],
+            element_ids: [],
+          },
+        ],
+        project_id: 1,
+        element_to_storey: new Map(),
+        element_to_building: new Map(),
+        element_to_site: new Map(),
+        element_to_space: new Map(),
+      },
+    };
+
+    const dataStore = convertServerDataModel(dataModel, parseResult, { size: 1 }, []);
+
+    assert.deepEqual(dataStore.relationships.getRelated(1, RelationshipType.Aggregates, 'forward'), [2]);
+    assert.deepEqual(dataStore.relationships.getRelated(3, RelationshipType.AssociatesDocument, 'forward'), [2]);
+  });
 });