@ifc-lite/viewer 1.17.4 → 1.18.0

package/src/hooks/useIfcFederation.ts

@@ -13,8 +13,15 @@
 import { useCallback } from 'react';
 import { useShallow } from 'zustand/react/shallow';
 import { useViewerStore, type FederatedModel, type SchemaVersion } from '../store.js';
-import { detectFormat, parseFederatedIfcx, type IfcDataStore, type FederatedIfcxParseResult } from '@ifc-lite/parser';
-import type { MeshData } from '@ifc-lite/geometry';
+import {
+  detectFormat,
+  parseFederatedIfcx,
+  type IfcDataStore,
+  type FederatedIfcxParseResult,
+  type MapConversion,
+  type ProjectedCRS,
+} from '@ifc-lite/parser';
+import type { CoordinateInfo, MeshData } from '@ifc-lite/geometry';
 import { IfcQuery } from '@ifc-lite/query';
 import { buildSpatialIndexGuarded } from '../utils/loadingUtils.js';
 import { getDynamicBatchConfig } from '../utils/ifcConfig.js';
@@ -27,6 +34,7 @@ import {
   parseStepBufferViewerModel,
 } from './ingest/viewerModelIngest.js';
 import { readNativeFile, type NativeFileHandle } from '../services/file-dialog.js';
+import { getEffectiveGeoreference, type GeorefMutationDataLike } from '../lib/geo/effective-georef.js';
 
 function isNativeFileHandle(file: File | NativeFileHandle): file is NativeFileHandle {
   return typeof (file as NativeFileHandle).path === 'string';
@@ -39,6 +47,271 @@ function toExactArrayBuffer(bytes: Uint8Array): ArrayBuffer {
   return bytes.slice().buffer;
 }
 
+type FederatedGeometryResult = NonNullable<FederatedModel['geometryResult']>;
+
+interface ModelGeoref {
+  mapConversion: MapConversion;
+  projectedCRS: ProjectedCRS;
+  lengthUnitScale: number;
+  coordinateInfo?: CoordinateInfo;
+}
+
+interface AffineTransform3D {
+  m00: number;
+  m01: number;
+  m02: number;
+  tx: number;
+  m10: number;
+  m11: number;
+  m12: number;
+  ty: number;
+  m20: number;
+  m21: number;
+  m22: number;
+  tz: number;
+}
+
+function getMapUnitScale(georef: ModelGeoref): number {
+  return georef.projectedCRS.mapUnitScale ?? georef.lengthUnitScale ?? 1;
+}
+
+function getAxis(conversion: MapConversion): { a: number; o: number; scale: number; denom: number } {
+  const a = conversion.xAxisAbscissa ?? 1;
+  const o = conversion.xAxisOrdinate ?? 0;
+  const scale = conversion.scale ?? 1;
+  const denom = Math.max(a * a + o * o, 1e-12);
+  return { a, o, scale, denom };
+}
+
+function extractModelGeoref(
+  dataStore: IfcDataStore,
+  coordinateInfo?: CoordinateInfo,
+  mutations?: GeorefMutationDataLike,
+): ModelGeoref | null {
+  const georef = getEffectiveGeoreference(dataStore, coordinateInfo, mutations);
+  if (!georef?.mapConversion || !georef.projectedCRS?.name) return null;
+  return {
+    mapConversion: georef.mapConversion,
+    projectedCRS: georef.projectedCRS,
+    lengthUnitScale: georef.lengthUnitScale,
+    coordinateInfo,
+  };
+}
+
+function crsKey(crs: ProjectedCRS): string {
+  return `${crs.name ?? ''}|${crs.geodeticDatum ?? ''}|${crs.mapProjection ?? ''}|${crs.mapZone ?? ''}`.toUpperCase();
+}
+
+function canAlignInSameProjectedCrs(a: ModelGeoref, b: ModelGeoref): boolean {
+  return crsKey(a.projectedCRS) === crsKey(b.projectedCRS);
+}
+
+function totalYupOffset(coordinateInfo?: CoordinateInfo): { x: number; y: number; z: number } {
+  const shift = coordinateInfo?.originShift ?? { x: 0, y: 0, z: 0 };
+  const rtc = coordinateInfo?.wasmRtcOffset;
+  const rtcYup = rtc ? { x: rtc.x, y: rtc.z, z: -rtc.y } : { x: 0, y: 0, z: 0 };
+  return {
+    x: shift.x + rtcYup.x,
+    y: shift.y + rtcYup.y,
+    z: shift.z + rtcYup.z,
+  };
+}
+
+function emptyBounds() {
+  return {
+    min: { x: Infinity, y: Infinity, z: Infinity },
+    max: { x: -Infinity, y: -Infinity, z: -Infinity },
+  };
+}
+
+function zeroBounds() {
+  return {
+    min: { x: 0, y: 0, z: 0 },
+    max: { x: 0, y: 0, z: 0 },
+  };
+}
+
+function updateBounds(bounds: ReturnType<typeof emptyBounds>, x: number, y: number, z: number): boolean {
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) return false;
+  bounds.min.x = Math.min(bounds.min.x, x);
+  bounds.min.y = Math.min(bounds.min.y, y);
+  bounds.min.z = Math.min(bounds.min.z, z);
+  bounds.max.x = Math.max(bounds.max.x, x);
+  bounds.max.y = Math.max(bounds.max.y, y);
+  bounds.max.z = Math.max(bounds.max.z, z);
+  return true;
+}
+
+function buildGeorefAlignmentTransform(source: ModelGeoref, reference: ModelGeoref): AffineTransform3D | null {
+  const sourceConv = source.mapConversion;
+  const refConv = reference.mapConversion;
+  const sourceAxis = getAxis(sourceConv);
+  const refAxis = getAxis(refConv);
+  const refDenom = refAxis.scale * refAxis.denom;
+  if (Math.abs(refDenom) < 1e-12) return null;
+
+  const sourceMapUnitScale = getMapUnitScale(source);
+  const refMapUnitScale = getMapUnitScale(reference);
+  const sourceOffset = totalYupOffset(source.coordinateInfo);
+  const refOffset = totalYupOffset(reference.coordinateInfo);
+
+  const eVx = sourceAxis.scale * sourceAxis.a;
+  const eVz = sourceAxis.scale * sourceAxis.o;
+  const eC = sourceConv.eastings * sourceMapUnitScale
+    + sourceAxis.scale * (sourceAxis.a * sourceOffset.x + sourceAxis.o * sourceOffset.z)
+    - refConv.eastings * refMapUnitScale;
+
+  const nVx = sourceAxis.scale * sourceAxis.o;
+  const nVz = -sourceAxis.scale * sourceAxis.a;
+  const nC = sourceConv.northings * sourceMapUnitScale
+    + sourceAxis.scale * (sourceAxis.o * sourceOffset.x - sourceAxis.a * sourceOffset.z)
+    - refConv.northings * refMapUnitScale;
+
+  const hC = sourceConv.orthogonalHeight * sourceMapUnitScale
+    + sourceOffset.y
+    - refConv.orthogonalHeight * refMapUnitScale;
+
+  const invRefDenom = 1 / refDenom;
+  const xVx = (refAxis.a * eVx + refAxis.o * nVx) * invRefDenom;
+  const xVz = (refAxis.a * eVz + refAxis.o * nVz) * invRefDenom;
+  const xC = (refAxis.a * eC + refAxis.o * nC) * invRefDenom - refOffset.x;
+
+  const yVx = (-refAxis.o * eVx + refAxis.a * nVx) * invRefDenom;
+  const yVz = (-refAxis.o * eVz + refAxis.a * nVz) * invRefDenom;
+  const yC = (-refAxis.o * eC + refAxis.a * nC) * invRefDenom;
+
+  return {
+    m00: xVx,
+    m01: 0,
+    m02: xVz,
+    tx: xC,
+    m10: 0,
+    m11: 1,
+    m12: 0,
+    ty: hC - refOffset.y,
+    m20: -yVx,
+    m21: 0,
+    m22: -yVz,
+    tz: -yC - refOffset.z,
+  };
+}
+
+function isIdentityTransform(transform: AffineTransform3D): boolean {
+  const eps = 1e-7;
+  return Math.abs(transform.m00 - 1) < eps
+    && Math.abs(transform.m01) < eps
+    && Math.abs(transform.m02) < eps
+    && Math.abs(transform.tx) < eps
+    && Math.abs(transform.m10) < eps
+    && Math.abs(transform.m11 - 1) < eps
+    && Math.abs(transform.m12) < eps
+    && Math.abs(transform.ty) < eps
+    && Math.abs(transform.m20) < eps
+    && Math.abs(transform.m21) < eps
+    && Math.abs(transform.m22 - 1) < eps
+    && Math.abs(transform.tz) < eps;
+}
+
+function applyAlignmentTransformAndUpdateBounds(
+  geometry: FederatedGeometryResult,
+  transform: AffineTransform3D,
+  referenceInfo?: CoordinateInfo,
+): void {
+  const bounds = emptyBounds();
+  let found = false;
+
+  for (const mesh of geometry.meshes) {
+    const positions = mesh.positions;
+    for (let i = 0; i < positions.length; i += 3) {
+      const x = positions[i];
+      const y = positions[i + 1];
+      const z = positions[i + 2];
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z)) {
+        continue;
+      }
+
+      const alignedX = transform.m00 * x + transform.m01 * y + transform.m02 * z + transform.tx;
+      const alignedY = transform.m10 * x + transform.m11 * y + transform.m12 * z + transform.ty;
+      const alignedZ = transform.m20 * x + transform.m21 * y + transform.m22 * z + transform.tz;
+      positions[i] = alignedX;
+      positions[i + 1] = alignedY;
+      positions[i + 2] = alignedZ;
+      found = updateBounds(bounds, alignedX, alignedY, alignedZ) || found;
+    }
+
+    // Rotate normals by the transform's 3×3 linear part (translation omitted)
+    // and renormalize. CRS alignment is a rigid rotation, so the linear part
+    // itself is the correct transform for normals; degenerate results from
+    // zero-length or non-finite inputs are left in place.
+    const normals = mesh.normals;
+    if (normals && normals.length >= 3) {
+      for (let i = 0; i < normals.length; i += 3) {
+        const nx = normals[i];
+        const ny = normals[i + 1];
+        const nz = normals[i + 2];
+        if (!Number.isFinite(nx) || !Number.isFinite(ny) || !Number.isFinite(nz)) {
+          continue;
+        }
+        const rx = transform.m00 * nx + transform.m01 * ny + transform.m02 * nz;
+        const ry = transform.m10 * nx + transform.m11 * ny + transform.m12 * nz;
+        const rz = transform.m20 * nx + transform.m21 * ny + transform.m22 * nz;
+        const len = Math.sqrt(rx * rx + ry * ry + rz * rz);
+        if (!Number.isFinite(len) || len < 1e-12) {
+          continue;
+        }
+        normals[i] = rx / len;
+        normals[i + 1] = ry / len;
+        normals[i + 2] = rz / len;
+      }
+    }
+  }
+
+  geometry.coordinateInfo = {
+    originShift: referenceInfo?.originShift ?? { x: 0, y: 0, z: 0 },
+    originalBounds: found ? bounds : zeroBounds(),
+    shiftedBounds: found ? bounds : zeroBounds(),
+    hasLargeCoordinates: referenceInfo?.hasLargeCoordinates ?? false,
+    wasmRtcOffset: referenceInfo?.wasmRtcOffset,
+    buildingRotation: referenceInfo?.buildingRotation,
+  };
+}
+
+function alignGeometryToReferenceGeoref(
+  geometry: FederatedGeometryResult,
+  source: ModelGeoref,
+  reference: ModelGeoref,
+): boolean {
+  if (!canAlignInSameProjectedCrs(source, reference)) {
+    return false;
+  }
+
+  const transform = buildGeorefAlignmentTransform(source, reference);
+  if (!transform) {
+    return false;
+  }
+
+  if (!isIdentityTransform(transform)) {
+    applyAlignmentTransformAndUpdateBounds(geometry, transform, reference.coordinateInfo);
+  }
+  return true;
+}
+
+function findReferenceGeorefModel(): ModelGeoref | null {
+  const state = useViewerStore.getState();
+  const modelEntries = Array.from(state.models.entries()) as Array<[string, FederatedModel]>;
+  const sorted = [...modelEntries].sort(([, a], [, b]) => (a.loadedAt ?? 0) - (b.loadedAt ?? 0));
+  for (const [modelId, model] of sorted) {
+    if (!model.ifcDataStore || !model.geometryResult) continue;
+    const georef = extractModelGeoref(
+      model.ifcDataStore,
+      model.geometryResult.coordinateInfo,
+      state.georefMutations.get(modelId),
+    );
+    if (georef) return georef;
+  }
+  return null;
+}
+
 /**
  * Extended data store type for IFCX (IFC5) files.
  * IFCX uses schemaVersion 'IFC5' and may include federated composition metadata.
@@ -100,9 +373,15 @@ export function useIfcFederation() {
    */
   const addModel = useCallback(async (
     file: File | NativeFileHandle,
-    options?: { name?: string }
+    options?: {
+      name?: string;
+      modelId?: string;
+      loadedAt?: number;
+      visible?: boolean;
+      collapsed?: boolean;
+    }
   ): Promise<string | null> => {
-    const modelId = crypto.randomUUID();
+    const modelId = options?.modelId ?? crypto.randomUUID();
     const addStart = performance.now();
     try {
       // IMPORTANT: Before adding a new model, check if there's a legacy model
@@ -143,6 +422,7 @@ export function useIfcFederation() {
           schemaVersion: 'IFC4',
           loadedAt: Date.now() - 1000,
           fileSize: 0,
+          sourceFile: undefined,
           idOffset: legacyOffset,
           maxExpressId: legacyMaxExpressId,
         };
@@ -190,12 +470,26 @@ export function useIfcFederation() {
         schemaVersion = result.schemaVersion;
       } else {
         setProgress({ phase: 'Starting geometry streaming', percent: 10 });
+
+        // For federated models: use the first model's RTC offset so all models
+        // share the same coordinate origin. This ensures pixel-perfect alignment
+        // without error-prone delta adjustments.
+        let sharedRtcOffset: { x: number; y: number; z: number } | undefined;
+        const existingModelsForRtc = Array.from(useViewerStore.getState().models.values()) as FederatedModel[];
+        if (existingModelsForRtc.length > 0) {
+          const sorted = [...existingModelsForRtc].sort((a, b) => (a.loadedAt ?? 0) - (b.loadedAt ?? 0));
+          sharedRtcOffset = sorted.find(
+            (model) => model.geometryResult?.coordinateInfo?.wasmRtcOffset != null,
+          )?.geometryResult?.coordinateInfo?.wasmRtcOffset;
+        }
+
         const result = await parseStepBufferViewerModel({
           fileName: file.name,
           buffer,
           fileSizeMB,
           getDynamicBatchSize: getDynamicBatchConfig,
           onProgress: setProgress,
+          sharedRtcOffset,
         });
         parsedDataStore = result.dataStore;
         parsedGeometry = result.geometryResult;
@@ -206,6 +500,27 @@ export function useIfcFederation() {
         throw new Error('Failed to parse file');
       }
 
+      const referenceGeoref = findReferenceGeorefModel();
+      // Include any georef edits the user has already saved for this model so
+      // that a reload after editing reflects the new placement. Without this,
+      // extractModelGeoref reads only the raw parsed metadata and mutations
+      // are silently ignored.
+      const parsedGeorefMutations = useViewerStore.getState().georefMutations.get(modelId);
+      const parsedGeoref = extractModelGeoref(
+        parsedDataStore,
+        parsedGeometry.coordinateInfo,
+        parsedGeorefMutations,
+      );
+      if (referenceGeoref && parsedGeoref) {
+        setProgress({ phase: 'Aligning georeferenced model', percent: 90 });
+        const aligned = alignGeometryToReferenceGeoref(parsedGeometry, parsedGeoref, referenceGeoref);
+        if (!aligned) {
+          console.warn(
+            `[ifc-lite] Skipped georeferenced federation alignment for "${file.name}" because CRS differs from the reference model.`,
+          );
+        }
+      }
+
       // =========================================================================
       // FEDERATION REGISTRY: Transform expressIds to globally unique IDs
       // This is the BULLETPROOF fix for multi-model ID collisions
@@ -229,71 +544,10 @@ export function useIfcFederation() {
       }
 
       // =========================================================================
-      // COORDINATE ALIGNMENT: Align new model with existing models using RTC delta
-      // WASM applies per-model RTC offsets. To align models from the same project,
-      // we calculate the difference in RTC offsets and apply it to the new model.
-      //
-      // RTC offset is in IFC coordinates (Z-up). After Z-up to Y-up conversion:
-      // - IFC X → WebGL X
-      // - IFC Y → WebGL -Z
-      // - IFC Z → WebGL Y (vertical)
+      // COORDINATE ALIGNMENT: All federated models use the same shared RTC offset
+      // (passed to WASM during parsing above), so no post-processing vertex
+      // adjustment is needed. All models are already in the same coordinate space.
       // =========================================================================
-      const existingModels = Array.from(useViewerStore.getState().models.values()) as FederatedModel[];
-      if (existingModels.length > 0) {
-        const firstModel = existingModels[0];
-        const firstRtc = firstModel.geometryResult?.coordinateInfo?.wasmRtcOffset;
-        const newRtc = parsedGeometry.coordinateInfo?.wasmRtcOffset;
-
-        // If both models have RTC offsets, use RTC delta for precise alignment
-        if (firstRtc && newRtc) {
-          // Calculate what adjustment is needed to align new model with first model
-          // First model: pos = original - firstRtc
-          // New model: pos = original - newRtc
-          // To align: newPos + adjustment = firstPos (assuming same original)
-          // adjustment = firstRtc - newRtc (add back new's RTC, subtract first's RTC)
-          const adjustX = firstRtc.x - newRtc.x;  // IFC X adjustment
-          const adjustY = firstRtc.y - newRtc.y;  // IFC Y adjustment
-          const adjustZ = firstRtc.z - newRtc.z;  // IFC Z adjustment (vertical)
-
-          // Convert to WebGL coordinates:
-          // IFC X → WebGL X (no change)
-          // IFC Y → WebGL -Z (swap and negate)
-          // IFC Z → WebGL Y (vertical)
-          const webglAdjustX = adjustX;
-          const webglAdjustY = adjustZ;   // IFC Z is WebGL Y (vertical)
-          const webglAdjustZ = -adjustY;  // IFC Y is WebGL -Z
-
-          const hasSignificantAdjust = Math.abs(webglAdjustX) > 0.01 ||
-                                        Math.abs(webglAdjustY) > 0.01 ||
-                                        Math.abs(webglAdjustZ) > 0.01;
-
-          if (hasSignificantAdjust) {
-            // Apply adjustment to all mesh vertices
-            // SUBTRACT adjustment: if firstRtc > newRtc, first was shifted MORE,
-            // so new model needs to be shifted in same direction (subtract more)
-            for (const mesh of parsedGeometry.meshes) {
-              const positions = mesh.positions;
-              for (let i = 0; i < positions.length; i += 3) {
-                positions[i] -= webglAdjustX;
-                positions[i + 1] -= webglAdjustY;
-                positions[i + 2] -= webglAdjustZ;
-              }
-            }
-
-            // Update coordinate info bounds
-            if (parsedGeometry.coordinateInfo) {
-              parsedGeometry.coordinateInfo.shiftedBounds.min.x -= webglAdjustX;
-              parsedGeometry.coordinateInfo.shiftedBounds.max.x -= webglAdjustX;
-              parsedGeometry.coordinateInfo.shiftedBounds.min.y -= webglAdjustY;
-              parsedGeometry.coordinateInfo.shiftedBounds.max.y -= webglAdjustY;
-              parsedGeometry.coordinateInfo.shiftedBounds.min.z -= webglAdjustZ;
-              parsedGeometry.coordinateInfo.shiftedBounds.max.z -= webglAdjustZ;
-            }
-          }
-        } else {
-          // No RTC info - can't align reliably. This happens with old cache entries.
-        }
-      }
 
       // Build spatial index AFTER ID offset + RTC alignment so it stores
       // correct globalIds and final world-space positions.
@@ -305,11 +559,12 @@ export function useIfcFederation() {
         name: options?.name ?? file.name,
         ifcDataStore: parsedDataStore,
         geometryResult: parsedGeometry,
-        visible: true,
-        collapsed: hasModels(), // Collapse if not first model
+        visible: options?.visible ?? true,
+        collapsed: options?.collapsed ?? hasModels(), // Collapse if not first model
         schemaVersion,
-        loadedAt: Date.now(),
+        loadedAt: options?.loadedAt ?? Date.now(),
         fileSize: buffer.byteLength,
+        sourceFile: file,
         idOffset,
         maxExpressId,
       };

package/src/hooks/useIfcLoader.ts

@@ -231,6 +231,7 @@ export function useIfcLoader() {
         schemaVersion: 'IFC4',
         loadedAt: Date.now(),
         fileSize,
+        sourceFile: file,
         idOffset: 0,
         maxExpressId: 0,
         loadState: 'pending',
@@ -280,15 +281,23 @@ export function useIfcLoader() {
         return 'IFC2X3';
       };
 
+      // Native renderer streaming path is currently disabled — the
+      // `huge native file` block further down handles real desktop
+      // streaming. This branch is retained as a scaffold for the future
+      // always-on native renderer integration.
+      const NATIVE_RENDERER_PATH_ENABLED = false as boolean;
       if (
+        NATIVE_RENDERER_PATH_ENABLED &&
         isNativeFileHandle(file) &&
-        fileName.toLowerCase().endsWith('.ifc') &&
-        false
+        fileName.toLowerCase().endsWith('.ifc')
       ) {
+        // Re-narrow `file` for the body — TS occasionally drops the
+        // type-predicate result inside a dead branch.
+        const nativeFile: NativeFileHandle = file;
         const harnessRequest = getActiveHarnessRequest();
-        const nativeCacheKey = computeNativeCacheKey(file);
-        const shouldUseNativeCache = file.size >= CACHE_SIZE_THRESHOLD;
-        const hugeNativeMode = file.size >= HUGE_NATIVE_FILE_THRESHOLD;
+        const nativeCacheKey = computeNativeCacheKey(nativeFile);
+        const shouldUseNativeCache = nativeFile.size >= CACHE_SIZE_THRESHOLD;
+        const hugeNativeMode = nativeFile.size >= HUGE_NATIVE_FILE_THRESHOLD;
         let firstBatchWaitMs: number | null = null;
         let firstVisibleGeometryMs: number | null = null;
         let modelOpenMs: number | null = null;
@@ -311,7 +320,7 @@ export function useIfcLoader() {
         let nativeGeometryCacheHit = false;
         let nativeMetadataSnapshotHit = false;
         let nativeMetadataSource: 'snapshot' | 'ifc-parse' = 'ifc-parse';
-        let nativeMetadataStartGate: 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete' = 'immediate';
+        let nativeMetadataStartGate = 'immediate' as 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete';
         let finalCoordinateInfo: CoordinateInfo | null = null;
 
         console.log(`[useIfc] Native renderer load: ${fileName}, size: ${fileSizeMB.toFixed(2)}MB`);
@@ -726,7 +735,7 @@ export function useIfcLoader() {
         let fullNativeDataStore: IfcDataStore | null = null;
         let nativeLoadStage: 'open' | 'streamGeometry' | 'finalizeGeometry' | 'hydrateMetadata' | 'complete' = 'open';
         let nativeMetadataSource: 'snapshot' | 'ifc-parse' = 'ifc-parse';
-        let nativeMetadataStartGate: 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete' = 'immediate';
+        let nativeMetadataStartGate = 'immediate' as 'immediate' | 'afterInteractiveGeometry' | 'afterGeometryComplete';
 
         setGeometryResult(null);
 
@@ -1637,8 +1646,10 @@ export function useIfcLoader() {
       }
 
       // Try server parsing first (enabled by default for multi-core performance)
-      // Only for IFC4 STEP files (server doesn't support IFCX)
-      if (format === 'ifc' && USE_SERVER && SERVER_URL && SERVER_URL !== '') {
+      // Only for IFC4 STEP files (server doesn't support IFCX). Native
+      // file handles (Tauri) don't have an HTTP-uploadable body, so skip
+      // the server path and fall through to the WASM loader.
+      if (format === 'ifc' && USE_SERVER && SERVER_URL && SERVER_URL !== '' && !isNativeFileHandle(file)) {
         // Pass buffer directly - server uses File object for parsing, buffer is only for size checks
         const serverSuccess = await loadFromServer(file, buffer, () => loadSessionRef.current !== currentSession);
         if (serverSuccess) {
@@ -1791,7 +1802,9 @@ export function useIfcLoader() {
           if (geometryIteratorClosed || typeof geometryIterator.return !== 'function') return;
           geometryIteratorClosed = true;
           try {
-            await geometryIterator.return();
+            // `AsyncIterator.return()` is signed as taking a value in
+            // current TS libs; callers conventionally pass `undefined`.
+            await geometryIterator.return(undefined);
           } catch {
             // Ignore iterator shutdown failures during recovery.
           }

package/src/hooks/useKeyboardShortcuts.ts

@@ -88,6 +88,10 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       e.preventDefault();
       setActiveTool('section');
     }
+    if (key === 'p' && !ctrl && !shift) {
+      e.preventDefault();
+      setActiveTool('annotate');
+    }
 
     // Basket controls (automatic context source)
     // I = Isolate from current context
@@ -150,6 +154,26 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       resetVisibilityForHomeFromStore();
     }
 
+    // Add-element tool shortcuts — Enter commits an in-progress slab
+    // polygon; Esc clears any pending points before falling through to
+    // the global Esc handler (which exits the tool).
+    if (activeTool === 'addElement') {
+      const state = useViewerStore.getState();
+      const polygonable = ['slab', 'roof', 'plate', 'space'].includes(state.addElementType);
+      if (key === 'enter' && polygonable && state.addElementSlabMode === 'polygon') {
+        e.preventDefault();
+        // Lazy import keeps this module out of the keyboard hook's
+        // synchronous bundle (the close handler pulls in toast).
+        import('@/components/viewer/selectionHandlers').then((mod) => mod.commitAddElementSlabPolygon());
+        return;
+      }
+      if (key === 'escape' && state.addElementPendingPoints.length > 0) {
+        e.preventDefault();
+        state.clearAddElementPending();
+        return;
+      }
+    }
+
     // Measure tool shortcuts
     if (activeTool === 'measure') {
       // Cancel active measurement with ESC
@@ -243,6 +267,7 @@ export const KEYBOARD_SHORTCUTS = [
   { key: 'V', description: 'Select tool', category: 'Tools' },
   { key: 'C', description: 'Walk mode', category: 'Tools' },
   { key: 'M', description: 'Measure tool', category: 'Tools' },
+  { key: 'P', description: 'Annotate tool — drop a pin with a note', category: 'Tools' },
   { key: 'X', description: 'Section tool', category: 'Tools' },
   { key: 'S', description: 'Toggle snapping (Measure tool)', category: 'Tools' },
   { key: 'Esc', description: 'Cancel measurement (Measure tool)', category: 'Tools' },

package/src/hooks/useSandbox.ts

@@ -165,7 +165,7 @@ export function useSandbox(config?: SandboxConfig) {
       // Create a fresh sandbox for every execution — full isolation
       const { createSandbox } = await import('@ifc-lite/sandbox');
       sandbox = await createSandbox(bim, {
-        permissions: { model: true, query: true, viewer: true, mutate: true, lens: true, export: true, files: true, ...config?.permissions },
+        permissions: { model: true, query: true, viewer: true, mutate: true, store: true, lens: true, export: true, files: true, ...config?.permissions },
         limits: { timeoutMs: 30_000, ...config?.limits },
       });
       activeSandboxRef.current = sandbox;