@ifc-lite/viewer 1.17.1 → 1.17.3

package/src/lib/geo/kmz-exporter.ts

@@ -0,0 +1,112 @@
+/* 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/. */
+
+/**
+ * KMZ Exporter — packages a GLB model with a KML file into a KMZ archive
+ * so Google Earth can display the 3D model at its correct geolocation.
+ *
+ * KMZ is just a ZIP archive containing:
+ *   doc.kml   — KML document with a <Model> positioned at lat/lon/alt
+ *   model.glb — the 3D model in glTF binary format
+ *
+ * The KML <Model> element uses:
+ *   <Location>    — latitude, longitude, altitude from reprojected georef
+ *   <Orientation> — heading derived from the angle-to-grid-north
+ *   <Scale>       — uniform scale (1:1)
+ *   <Link>        — relative path to the GLB inside the archive
+ */
+
+import { zipSync } from 'fflate';
+import type { LatLon } from './reproject';
+
+export interface KmzOptions {
+  /** WGS84 coordinates of the model origin */
+  latLon: LatLon;
+  /** Orthogonal height (elevation) in metres */
+  altitude: number;
+  /** Heading in degrees clockwise from north (0 = north, 90 = east) */
+  heading: number;
+  /** GLB model binary data */
+  glb: Uint8Array;
+  /** Display name for the placemark */
+  name?: string;
+}
+
+/**
+ * Convert the IFC angle-to-grid-north (counterclockwise from east) into
+ * a KML heading (clockwise from north).
+ *
+ * IFC convention: atan2(XAxisOrdinate, XAxisAbscissa) gives the CCW angle
+ * from the map east axis to the local X axis.
+ *
+ * KML convention: heading is CW from north (0=N, 90=E, 180=S, 270=W).
+ */
+export function ifcAngleToKmlHeading(
+  xAxisAbscissa?: number,
+  xAxisOrdinate?: number,
+): number {
+  if (xAxisAbscissa === undefined || xAxisOrdinate === undefined) return 0;
+  const angleFromEastCcw = Math.atan2(xAxisOrdinate, xAxisAbscissa) * (180 / Math.PI);
+  // Convert: heading = 90 - angle (CCW from east → CW from north)
+  const heading = 90 - angleFromEastCcw;
+  // Normalize to [0, 360)
+  return ((heading % 360) + 360) % 360;
+}
+
+function buildKml(opts: KmzOptions): string {
+  const name = escapeXml(opts.name ?? 'IFC Model');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://www.opengis.net/kml/2.2">
+  <Document>
+    <name>${name}</name>
+    <Placemark>
+      <name>${name}</name>
+      <Model id="model">
+        <altitudeMode>relativeToGround</altitudeMode>
+        <Location>
+          <longitude>${opts.latLon.lon}</longitude>
+          <latitude>${opts.latLon.lat}</latitude>
+          <altitude>${opts.altitude}</altitude>
+        </Location>
+        <Orientation>
+          <heading>${opts.heading}</heading>
+          <tilt>0</tilt>
+          <roll>0</roll>
+        </Orientation>
+        <Scale>
+          <x>1</x>
+          <y>1</y>
+          <z>1</z>
+        </Scale>
+        <Link>
+          <href>model.glb</href>
+        </Link>
+      </Model>
+    </Placemark>
+  </Document>
+</kml>`;
+}
+
+function escapeXml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Build a KMZ file (ZIP archive) containing doc.kml + model.glb.
+ * Returns the KMZ as a Uint8Array ready for download.
+ */
+export function buildKmz(opts: KmzOptions): Uint8Array {
+  const kml = buildKml(opts);
+  const kmlBytes = new TextEncoder().encode(kml);
+
+  return zipSync({
+    'doc.kml': kmlBytes,
+    'model.glb': opts.glb,
+  });
+}

package/src/lib/geo/reproject.ts

@@ -0,0 +1,244 @@
+/* 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/. */
+
+/**
+ * Coordinate reprojection utilities.
+ *
+ * Converts projected coordinates (e.g. UTM eastings/northings) from an
+ * IfcMapConversion + IfcProjectedCRS pair into WGS84 longitude/latitude
+ * so they can be displayed on a web map.
+ *
+ * proj4 definitions are resolved from:
+ *   1. The bundled EPSG index (@ifc-lite/data) — covers all 7000+ codes
+ *   2. Programmatically constructed (UTM zones, well-known codes)
+ *   3. Fetched from epsg.io at runtime as last resort
+ */
+
+import proj4 from 'proj4';
+import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
+import type { CoordinateInfo } from '@ifc-lite/geometry';
+import { lookupProj4 } from '@ifc-lite/data';
+
+export interface LatLon {
+  lat: number;
+  lon: number;
+}
+
+// Cache resolved projection definitions (from any source).
+const projDefCache = new Map<string, string | null>();
+
+/**
+ * Extract EPSG numeric code from a CRS name like "EPSG:32632" or "EPSG 2056".
+ */
+function extractEpsgCode(crs: ProjectedCRS): string | null {
+  const match = crs.name?.match(/EPSG[:\s]*(\d+)/i);
+  return match ? match[1] : null;
+}
+
+/**
+ * Build a proj4 definition string for a UTM zone.
+ */
+function utmProj4String(zone: string): string | null {
+  const match = zone.match(/^(\d{1,2})([NS])$/i);
+  if (!match) return null;
+  const zoneNum = parseInt(match[1], 10);
+  const isNorth = match[2].toUpperCase() === 'N';
+  if (zoneNum < 1 || zoneNum > 60) return null;
+  return `+proj=utm +zone=${zoneNum}${isNorth ? '' : ' +south'} +datum=WGS84 +units=m +no_defs`;
+}
+
+/**
+ * Well-known +towgs84 approximations for datums that normally use grid files.
+ * These are accurate to ~1-5m, which is sufficient for map display.
+ * Grid files (like OSTN15_NTv2_OSGBtoETRS.gsb) cannot run in the browser.
+ */
+const DATUM_TOWGS84: Record<string, string> = {
+  'airy': '+towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489',      // OSGB36 (UK)
+  'clrk66': '+towgs84=-8,160,176,0,0,0,0',                                   // NAD27 (approx)
+  'GRS80': '+towgs84=0,0,0,0,0,0,0',                                          // GRS80-based (NAD83≈WGS84)
+  'bessel': '+towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7',              // DHDN (Germany)
+  'intl': '+towgs84=-87,-98,-121,0,0,0,0',                                    // NZGD49 (NZ)
+  'aust_SA': '+towgs84=-134,-48,149,0,0,0,0',                                 // AGD84 (Australia)
+};
+
+/**
+ * Strip +nadgrids=... from a proj4 string and add a +towgs84 approximation
+ * based on the ellipsoid. Grid files cannot be loaded in the browser.
+ */
+function sanitizeProj4(def: string): string {
+  if (!def.includes('+nadgrids') || def.includes('+nadgrids=@null')) return def;
+
+  // Extract the ellipsoid to find the right towgs84 approximation
+  const ellpsMatch = def.match(/\+ellps=(\S+)/);
+  const ellps = ellpsMatch?.[1] ?? '';
+  const towgs84 = DATUM_TOWGS84[ellps] ?? '+towgs84=0,0,0,0,0,0,0';
+
+  // Remove +nadgrids=... and add +towgs84
+  return def.replace(/\+nadgrids=\S+/g, '').replace(/\s+/g, ' ').trim() + ' ' + towgs84;
+}
+
+/**
+ * Fetch a proj4 definition string from epsg.io (last-resort fallback).
+ */
+async function fetchProj4Def(epsgCode: string): Promise<string | null> {
+  try {
+    const resp = await fetch(`https://epsg.io/${epsgCode}.proj4`);
+    if (!resp.ok) return null;
+    const text = (await resp.text()).trim();
+    if (!text || text.startsWith('<') || text.startsWith('{') || !text.includes('+')) {
+      return null;
+    }
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a proj4 definition for the given ProjectedCRS.
+ *
+ * Resolution order:
+ *   1. Cache hit
+ *   2. Bundled EPSG index (7000+ codes with proj4 strings)
+ *   3. UTM zone heuristic (from CRS metadata)
+ *   4. Fetch from epsg.io (network fallback)
+ */
+export async function resolveProjection(crs: ProjectedCRS): Promise<string | null> {
+  const code = extractEpsgCode(crs);
+
+  // 1. Check cache
+  if (code && projDefCache.has(code)) {
+    return projDefCache.get(code) ?? null;
+  }
+
+  // 2. Bundled EPSG index (primary source — all 7000+ codes)
+  if (code) {
+    try {
+      const bundled = await lookupProj4(code);
+      if (bundled) {
+        const sanitized = sanitizeProj4(bundled);
+        projDefCache.set(code, sanitized);
+        return sanitized;
+      }
+    } catch {
+      // EPSG index not loaded yet, continue to fallbacks
+    }
+  }
+
+  // 3. UTM zone heuristic
+  if (crs.mapZone) {
+    const def = utmProj4String(crs.mapZone);
+    if (def) {
+      if (code) projDefCache.set(code, def);
+      return def;
+    }
+  }
+  const name = crs.name?.toUpperCase() ?? '';
+  const utmMatch = name.match(/UTM\s+ZONE\s+(\d{1,2}[NS])/i)
+    ?? crs.description?.match(/UTM\s+zone\s+(\d{1,2}[NS])/i);
+  if (utmMatch) {
+    const def = utmProj4String(utmMatch[1]);
+    if (def) {
+      if (code) projDefCache.set(code, def);
+      return def;
+    }
+  }
+
+  // 4. Network fallback — fetch from epsg.io
+  if (code) {
+    const raw = await fetchProj4Def(code);
+    const fetched = raw ? sanitizeProj4(raw) : null;
+    projDefCache.set(code, fetched);
+    return fetched;
+  }
+
+  return null;
+}
+
+/**
+ * Compute the model center in the projected CRS (easting, northing).
+ *
+ * The coordinate pipeline is:
+ *   1. WASM extracts IFC positions (Z-up) and may apply RTC offset (wasmRtcOffset, Z-up)
+ *   2. Mesh collector converts Z-up → Y-up: viewerX = ifcX, viewerY = ifcZ, viewerZ = -ifcY
+ *   3. CoordinateHandler may apply originShift (Y-up)
+ *
+ * To recover IFC world coordinates (Z-up) from the viewer bounds:
+ *   world_yup = bounds_center + originShift + wasmRtcOffset_as_yup
+ *   ifc_x = world_yup.x,  ifc_y = -world_yup.z,  ifc_z = world_yup.y
+ *
+ * Then the projected CRS coordinates are:
+ *   easting  = mapConversion.eastings + scale * (cos*ifc_x - sin*ifc_y)
+ *   northing = mapConversion.northings + scale * (sin*ifc_x + cos*ifc_y)
+ */
+function computeProjectedCenter(
+  conversion: MapConversion,
+  coordinateInfo?: CoordinateInfo,
+): { easting: number; northing: number } {
+  let ifcX = 0;
+  let ifcY = 0;
+
+  if (coordinateInfo) {
+    const bounds = coordinateInfo.originalBounds;
+    const shift = coordinateInfo.originShift;
+    const rtc = coordinateInfo.wasmRtcOffset;
+
+    // Convert WASM RTC offset from IFC Z-up to viewer Y-up
+    const rtcYup = rtc
+      ? { x: rtc.x, y: rtc.z, z: -rtc.y }
+      : { x: 0, y: 0, z: 0 };
+
+    // Bounds center in viewer Y-up (scene-local)
+    const cx = (bounds.min.x + bounds.max.x) / 2;
+    const cz = (bounds.min.z + bounds.max.z) / 2;
+
+    // World Y-up = scene_local + originShift + wasmRtcOffset_yup
+    const worldYupX = cx + shift.x + rtcYup.x;
+    const worldYupZ = cz + shift.z + rtcYup.z;
+
+    // Convert Y-up to IFC Z-up: ifc_x = viewer_x, ifc_y = -viewer_z
+    ifcX = worldYupX;
+    ifcY = -worldYupZ;
+  }
+
+  // Apply MapConversion rotation + scale + offset
+  const scale = conversion.scale ?? 1.0;
+  const abscissa = conversion.xAxisAbscissa ?? 1.0;
+  const ordinate = conversion.xAxisOrdinate ?? 0.0;
+
+  const easting = conversion.eastings + scale * (abscissa * ifcX - ordinate * ifcY);
+  const northing = conversion.northings + scale * (ordinate * ifcX + abscissa * ifcY);
+
+  return { easting, northing };
+}
+
+/**
+ * Reproject the model center from the projected CRS to WGS84 lat/lon.
+ *
+ * Uses the model's actual geometry bounds + RTC offset to determine where
+ * the model sits in the projected coordinate system, then reprojects to WGS84.
+ *
+ * @param conversion  IfcMapConversion (offset, rotation, scale)
+ * @param crs         IfcProjectedCRS (EPSG code)
+ * @param coordinateInfo  Geometry coordinate info with bounds and RTC offset
+ */
+export async function reprojectToLatLon(
+  conversion: MapConversion,
+  crs: ProjectedCRS,
+  coordinateInfo?: CoordinateInfo,
+): Promise<LatLon | null> {
+  const projDef = await resolveProjection(crs);
+  if (!projDef) return null;
+
+  const { easting, northing } = computeProjectedCenter(conversion, coordinateInfo);
+
+  try {
+    const [lon, lat] = proj4(projDef, 'WGS84', [easting, northing]);
+    if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+    if (lat < -90 || lat > 90 || lon < -180 || lon > 180) return null;
+    return { lat, lon };
+  } catch {
+    return null;
+  }
+}

package/src/lib/lens/adapter.ts

@@ -18,6 +18,7 @@ import {
   extractClassificationsOnDemand,
   extractMaterialsOnDemand,
 } from '@ifc-lite/parser';
+import { toGlobalIdFromModels } from '@/store/globalId';
 import type { FederatedModel } from '@/store/types';
 
 interface ModelEntry {
@@ -80,12 +81,13 @@ export function createLensDataProvider(
     },
 
     forEachEntity(callback: (globalId: number, modelId: string) => void): void {
+      const models = new Map(entries.map((entry) => [entry.id, { idOffset: entry.idOffset }]));
       for (const entry of entries) {
         const entities = entry.ifcDataStore.entities;
         if (!entities) continue;
         for (let i = 0; i < entities.count; i++) {
           const expressId = entities.expressId[i];
-          callback(expressId + entry.idOffset, entry.id);
+          callback(toGlobalIdFromModels(models, entry.id, expressId), entry.id);
         }
       }
     },

package/src/main.tsx

@@ -11,6 +11,7 @@ import ReactDOM from 'react-dom/client';
 import { ClerkProvider } from '@clerk/clerk-react';
 import { App } from './App';
 import './index.css';
+import 'maplibre-gl/dist/maplibre-gl.css';
 
 const clerkPublishableKey = (import.meta.env.VITE_CLERK_PUBLISHABLE_KEY as string | undefined)?.trim();
 

package/src/sdk/adapters/export-adapter.ts

@@ -119,6 +119,13 @@ function escapeCsv(value: string, sep: string): string {
  * on the same LocalBackend, providing full export support for both
  * direct dispatch calls and SDK namespace usage.
  */
+function toBlobPart(content: string | Uint8Array): BlobPart {
+  if (typeof content === 'string') return content;
+  const bytes = new Uint8Array(content.byteLength);
+  bytes.set(content);
+  return bytes;
+}
+
 export function createExportAdapter(store: StoreApi): ExportBackendMethods {
   /** Resolve entity data via the query subsystem */
   function getEntityData(ref: EntityRef): EntityData | null {
@@ -354,6 +361,11 @@ export function createExportAdapter(store: StoreApi): ExportBackendMethods {
         model.ifcDataStore,
         options.includeMutations === false ? undefined : getMutationViewForModel(store, modelId) ?? undefined,
       );
+      // Include georeferencing mutations if present
+      const georefMutations = options.includeMutations !== false
+        ? state.georefMutations?.get(modelId) ?? undefined
+        : undefined;
+
       const exportOptions: StepExportOptions = {
         schema: options.schema ?? model.ifcDataStore.schemaVersion,
         includeGeometry: true,
@@ -364,6 +376,7 @@ export function createExportAdapter(store: StoreApi): ExportBackendMethods {
         visibleOnly,
         hiddenEntityIds,
         isolatedEntityIds,
+        georefMutations,
       };
 
       return exporter.export(exportOptions).content;
@@ -381,7 +394,7 @@ function triggerDownload(content: string | Uint8Array, filename: string, mimeTyp
   if (typeof document === 'undefined') {
     throw new Error('download() requires a browser environment (document is unavailable)');
   }
-  const blob = new Blob([content], { type: mimeType });
+  const blob = new Blob([toBlobPart(content)], { type: mimeType });
   const url = URL.createObjectURL(blob);
   const a = document.createElement('a');
   a.href = url;

package/src/sdk/adapters/viewer-adapter.ts

@@ -5,6 +5,7 @@
 import type { EntityRef, SectionPlane, CameraState, ViewerBackendMethods } from '@ifc-lite/sdk';
 import type { StoreApi } from './types.js';
 import { getModelForRef } from './model-compat.js';
+import { toGlobalIdForRef } from '../../store/globalId.js';
 
 const AXIS_TO_STORE: Record<string, 'down' | 'front' | 'side'> = {
   x: 'side',
@@ -25,11 +26,8 @@ export function createViewerAdapter(store: StoreApi): ViewerBackendMethods {
       const existing = state.pendingColorUpdates;
       const colorMap = existing ? new Map(existing) : new Map<number, [number, number, number, number]>();
       for (const ref of refs) {
-        const model = getModelForRef(state, ref.modelId);
-        if (model) {
-          const globalId = ref.expressId + model.idOffset;
-          colorMap.set(globalId, color);
-        }
+        if (!getModelForRef(state, ref.modelId)) continue;
+        colorMap.set(toGlobalIdForRef(state.models, ref), color);
       }
       state.setPendingColorUpdates(colorMap);
       return undefined;
@@ -41,10 +39,8 @@ export function createViewerAdapter(store: StoreApi): ViewerBackendMethods {
       const batchMap = new Map<number, [number, number, number, number]>();
       for (const batch of batches) {
         for (const ref of batch.refs) {
-          const model = getModelForRef(state, ref.modelId);
-          if (model) {
-            batchMap.set(ref.expressId + model.idOffset, batch.color);
-          }
+          if (!getModelForRef(state, ref.modelId)) continue;
+          batchMap.set(toGlobalIdForRef(state.models, ref), batch.color);
         }
       }
       state.setPendingColorUpdates(batchMap);

package/src/sdk/adapters/visibility-adapter.ts

@@ -6,6 +6,7 @@ import type { EntityRef, VisibilityBackendMethods } from '@ifc-lite/sdk';
 import type { StoreApi } from './types.js';
 import { getModelForRef, type ModelLike } from './model-compat.js';
 import { collectSpatialSubtreeElementsWithIfcSpace } from '../../store/basketVisibleSet.js';
+import { toGlobalIdForRef, toGlobalIdFromModels } from '../../store/globalId.js';
 import { isSpaceLikeSpatialTypeName, isSpatialStructureTypeName, type SpatialNode } from '@ifc-lite/data';
 
 function findDescendantNode(root: SpatialNode, expressId: number): SpatialNode | null {
@@ -49,10 +50,8 @@ export function createVisibilityAdapter(store: StoreApi): VisibilityBackendMetho
       // hiddenEntities set (global IDs), not hiddenEntitiesByModel.
       const globalIds: number[] = [];
       for (const ref of refs) {
-        const model = getModelForRef(state, ref.modelId);
-        if (model) {
-          globalIds.push(ref.expressId + model.idOffset);
-        }
+        if (!getModelForRef(state, ref.modelId)) continue;
+        globalIds.push(toGlobalIdForRef(state.models, ref));
       }
       if (globalIds.length > 0) {
         state.hideEntities(globalIds);
@@ -63,10 +62,8 @@ export function createVisibilityAdapter(store: StoreApi): VisibilityBackendMetho
       const state = store.getState();
       const globalIds: number[] = [];
       for (const ref of refs) {
-        const model = getModelForRef(state, ref.modelId);
-        if (model) {
-          globalIds.push(ref.expressId + model.idOffset);
-        }
+        if (!getModelForRef(state, ref.modelId)) continue;
+        globalIds.push(toGlobalIdForRef(state.models, ref));
       }
       if (globalIds.length > 0) {
         state.showEntities(globalIds);
@@ -81,7 +78,7 @@ export function createVisibilityAdapter(store: StoreApi): VisibilityBackendMetho
         if (model) {
           const expanded = expandSpatialRef(ref, model);
           for (const id of expanded) {
-            globalIds.push(id + model.idOffset);
+            globalIds.push(toGlobalIdFromModels(state.models, ref.modelId, id));
           }
         }
       }

package/src/store/basketVisibleSet.ts

@@ -14,6 +14,7 @@ import type { IfcDataStore } from '@ifc-lite/parser';
 import type { EntityRef } from './types.js';
 import { entityRefToString, stringToEntityRef } from './types.js';
 import { useViewerStore } from './index.js';
+import { toGlobalIdFromModels } from './globalId.js';
 
 type ViewerStateSnapshot = ReturnType<typeof useViewerStore.getState>;
 
@@ -159,9 +160,7 @@ function expandRefToElements(state: ViewerStateSnapshot, ref: EntityRef): Entity
 }
 
 function toGlobalId(modelId: string, expressId: number, state: ViewerStateSnapshot): number {
-  if (modelId === 'legacy') return expressId;
-  const model = state.models.get(modelId);
-  return expressId + (model?.idOffset ?? 0);
+  return toGlobalIdFromModels(state.models, modelId, expressId);
 }
 
 function globalIdToRef(state: ViewerStateSnapshot, globalId: number): EntityRef | null {
@@ -318,7 +317,7 @@ function computeStoreyIsolation(state: ViewerStateSnapshot): Set<number> | null
         const storeyElementIds = collectIfcBuildingStoreyElementsWithIfcSpace(hierarchy, localStoreyId);
         if (!storeyElementIds) continue;
         for (const localId of storeyElementIds) {
-          ids.add(localId + offset);
+          ids.add(toGlobalIdFromModels(state.models, model.id, localId));
         }
       }
     }

package/src/store/globalId.ts

@@ -0,0 +1,79 @@
+/* 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 { EntityRef, FederatedModel } from './types.js';
+
+type ForwardModelMapLike = ReadonlyMap<string, { idOffset?: number }>;
+type ReverseModelMapLike = ReadonlyMap<string, Pick<FederatedModel, 'idOffset' | 'maxExpressId'>>;
+
+/**
+ * Convert a local expressId to the renderer/global ID space.
+ *
+ * This is the viewer-level single source of truth for modelId + expressId →
+ * globalId conversion outside Zustand hooks. It preserves single-model legacy
+ * behavior by falling back to the original expressId when no federated model
+ * entry exists.
+ */
+export function toGlobalIdFromModels(
+  models: ForwardModelMapLike,
+  modelId: string,
+  expressId: number,
+): number {
+  if (modelId === 'legacy' || modelId === 'default' || modelId === '__legacy__') {
+    return expressId;
+  }
+
+  const model = models.get(modelId);
+  if (!model) {
+    return expressId;
+  }
+
+  return expressId + (model.idOffset ?? 0);
+}
+
+/**
+ * Resolve a renderer/global ID back to the source model and local expressId.
+ *
+ * This mirrors toGlobalIdFromModels and preserves legacy single-model behavior.
+ */
+export function fromGlobalIdFromModels(
+  models: ReverseModelMapLike,
+  globalId: number,
+): EntityRef | undefined {
+  if (models.size <= 1) {
+    const firstModelId = models.keys().next().value;
+    if (firstModelId) {
+      return {
+        modelId: firstModelId,
+        expressId: globalId,
+      };
+    }
+    return {
+      modelId: 'legacy',
+      expressId: globalId,
+    };
+  }
+
+  for (const [modelId, model] of models.entries()) {
+    const localExpressId = globalId - model.idOffset;
+    if (localExpressId > 0 && localExpressId <= model.maxExpressId) {
+      return {
+        modelId,
+        expressId: localExpressId,
+      };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Convert an EntityRef to the renderer/global ID space.
+ */
+export function toGlobalIdForRef(
+  models: ForwardModelMapLike,
+  ref: EntityRef,
+): number {
+  return toGlobalIdFromModels(models, ref.modelId, ref.expressId);
+}

package/src/store/index.ts

@@ -48,6 +48,7 @@ export { entityRefToString, stringToEntityRef, entityRefEquals, isIfcxDataStore
 
 // Re-export single source of truth for globalId → EntityRef resolution
 export { resolveEntityRef } from './resolveEntityRef.js';
+export { fromGlobalIdFromModels, toGlobalIdFromModels, toGlobalIdForRef } from './globalId.js';
 
 // Re-export Drawing2D types
 export type { Drawing2DState, Drawing2DStatus, Annotation2DTool, PolygonArea2DResult, TextAnnotation2D, CloudAnnotation2D, SelectedAnnotation2D } from './slices/drawing2DSlice.js';