@ifc-lite/viewer 1.22.0 → 1.23.0

package/src/lib/geo/reproject.ts

@@ -18,8 +18,9 @@
 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';
-import { getEffectiveHorizontalScale } from './geo-scale';
+import { lookupEpsgByCode } from '@ifc-lite/data';
+import { getEffectiveHorizontalScale, resolveMapUnitToMetreScale } from './geo-scale';
+import { resolvePrecisionDef } from './precision-grids';
 
 export interface LatLon {
   lat: number;
@@ -29,6 +30,9 @@ export interface LatLon {
 // Cache resolved projection definitions (from any source).
 const projDefCache = new Map<string, string | null>();
 const approxDatumWarningCache = new Set<string>();
+// Track datums where the bundled proj4 lacked any datum-shift parameters and we
+// couldn't supply a fallback — surfaced via diagnostics, warned once per datum.
+const unknownDatumWarningCache = new Set<string>();
 
 /**
  * Extract EPSG numeric code from a CRS name like "EPSG:32632" or "EPSG 2056".
@@ -40,9 +44,14 @@ function extractEpsgCode(crs: ProjectedCRS): string | null {
 
 /**
  * Well-known CRS names that IFC authoring tools set without an EPSG: prefix.
- * Maps normalised name → EPSG code.
+ * Maps normalised name → EPSG code. Keys are lowercased before lookup.
+ *
+ * Authoring tools across regions emit different local conventions for the same
+ * national grid; covering the common ones lets ifc-lite resolve a projection
+ * for files that omit the "EPSG:" prefix entirely.
  */
 const WELL_KNOWN_CRS: Record<string, string> = {
+  // Global / generic
   'wgs 84': '4326',
   'wgs84': '4326',
   'wgs-84': '4326',
@@ -51,6 +60,53 @@ const WELL_KNOWN_CRS: Record<string, string> = {
   'etrs89': '4258',
   'gcs_wgs_1984': '4326',        // ArcGIS / Revit export alias
   'gcs_north_american_1983': '4269',
+
+  // Netherlands — Rijksdriehoeksmeting (RD New, EPSG:28992)
+  'rd': '28992',
+  'rd new': '28992',
+  'amersfoort / rd new': '28992',
+  'amersfoort rd new': '28992',
+  'stelsel van de rijksdriehoeksmeting': '28992',
+  'rijksdriehoeksmeting': '28992',
+  'nl_rd': '28992',
+  // RD/NAP compound (horizontal RD + vertical NAP)
+  'rd new + nap height': '7415',
+  'amersfoort / rd new + nap height': '7415',
+
+  // United Kingdom — Ordnance Survey GB (BNG, EPSG:27700)
+  'osgb 1936 / british national grid': '27700',
+  'osgb36 / british national grid': '27700',
+  'british national grid': '27700',
+  'bng': '27700',
+
+  // Germany — DHDN / Gauss-Kruger zones + ETRS89 / UTM (most common)
+  'dhdn / gauss-kruger zone 2': '31466',
+  'dhdn / gauss-kruger zone 3': '31467',
+  'dhdn / gauss-kruger zone 4': '31468',
+  'dhdn / gauss-kruger zone 5': '31469',
+  'etrs89 / utm zone 32n': '25832',
+  'etrs89 / utm zone 33n': '25833',
+
+  // Austria — MGI Lambert / Austrian Grid (EPSG:31287)
+  'mgi / austria lambert': '31287',
+  'austria lambert': '31287',
+
+  // Switzerland — CH1903+ / LV95 (EPSG:2056) and legacy LV03 (EPSG:21781)
+  'ch1903+ / lv95': '2056',
+  'lv95': '2056',
+  'ch1903 / lv03': '21781',
+  'lv03': '21781',
+
+  // Belgium — Lambert 2008 (EPSG:3812) and legacy Lambert 72 (EPSG:31370)
+  'belge 1972 / belgian lambert 72': '31370',
+  'belgian lambert 72': '31370',
+  'etrs89 / belgian lambert 2008': '3812',
+
+  // France — RGF93 / Lambert-93 (EPSG:2154)
+  'rgf93 / lambert-93': '2154',
+  'rgf93 v1 / lambert-93': '2154',
+  'lambert-93': '2154',
+  'lambert 93': '2154',
 };
 
 /**
@@ -74,41 +130,92 @@ function utmProj4String(zone: string): string | null {
 }
 
 /**
- * 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.
+ * Datum-keyed +towgs84 approximations for CRSs whose canonical definition
+ * relies on browser-unavailable grid files (NTv2, NADCON, etc.). Each entry
+ * is the published Bursa-Wolf 7-parameter set for that specific datum, in
+ * the Position Vector convention proj4 expects, with rotations in arc-seconds.
+ *
+ * Keys are lowercased datum names as they appear in EpsgIndexEntry.datum. A
+ * lookup miss is intentional — it forces sanitizeProj4 to emit a diagnostic
+ * rather than silently substitute parameters for the wrong region (an earlier
+ * version of this table was keyed by ellipsoid alone, which caused every
+ * Bessel-1841 CRS — RD/NL, Hermannskogel/AT, S-JTSK/CZ — to inherit Germany's
+ * DHDN shift). Accuracy is typically ~1-5 m, sufficient for map display.
  */
 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)
+  // United Kingdom — OSGB36 (Airy 1830)
+  'osgb 1936': '+towgs84=446.448,-125.157,542.06,0.15,0.247,0.842,-20.489',
+  // North America — NAD27 (Clarke 1866)
+  'north american datum 1927': '+towgs84=-8,160,176,0,0,0,0',
+  'nad27': '+towgs84=-8,160,176,0,0,0,0',
+  // NAD83 ≈ WGS84 to within ~1 m; identity is the standard browser approximation.
+  'north american datum 1983': '+towgs84=0,0,0,0,0,0,0',
+  'nad83': '+towgs84=0,0,0,0,0,0,0',
+  // Germany — DHDN (Bessel 1841)
+  'deutsches hauptdreiecksnetz': '+towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7',
+  'dhdn': '+towgs84=598.1,73.7,418.2,0.202,0.045,-2.455,6.7',
+  // Netherlands — Amersfoort (Bessel 1841). The bundled EPSG:28992 already
+  // ships with the higher-precision Kadaster +towgs84, so this fires only
+  // when a derived/compound CRS lacks it (e.g. some compound RD/NAP cases).
+  'amersfoort': '+towgs84=565.4171,50.3319,465.5524,1.9342,-1.6677,9.1019,4.0725',
+  // Austria — MGI (Bessel 1841)
+  'militar-geographische institut': '+towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232',
+  'mgi': '+towgs84=577.326,90.129,463.919,5.137,1.474,5.297,2.4232',
+  // Czech Republic — S-JTSK (Bessel 1841)
+  'system of the unified trigonometrical cadastral network': '+towgs84=570.8,85.7,462.8,4.998,1.587,5.261,3.56',
+  's-jtsk': '+towgs84=570.8,85.7,462.8,4.998,1.587,5.261,3.56',
+  // New Zealand — NZGD49 (International 1924)
+  'new zealand geodetic datum 1949': '+towgs84=59.47,-5.04,187.44,0.47,-0.1,1.024,-4.5993',
+  'nzgd49': '+towgs84=59.47,-5.04,187.44,0.47,-0.1,1.024,-4.5993',
+  // Australia — AGD84 (Australian National Spheroid)
+  'australian geodetic datum 1984': '+towgs84=-117.763,-51.51,139.061,0.292,0.443,0.277,-0.191',
+  'agd84': '+towgs84=-117.763,-51.51,139.061,0.292,0.443,0.277,-0.191',
 };
 
 /**
  * Strip +nadgrids=... from a proj4 string and add a +towgs84 approximation
- * based on the ellipsoid. Grid files cannot be loaded in the browser.
+ * keyed by the datum name from the bundled EPSG index. Grid files cannot be
+ * loaded in the browser; +towgs84 is the standard fallback.
+ *
+ * Skipped (returns input verbatim) when:
+ *   - No +nadgrids reference (or it's the no-op `@null`)
+ *   - A +towgs84 is already present (proj4 will honour it)
  */
-function sanitizeProj4(def: string, code?: string | null): string {
+function sanitizeProj4(def: string, code?: string | null, datumName?: string | null): string {
   if (!def.includes('+nadgrids') || def.includes('+nadgrids=@null')) return def;
+  if (/\+towgs84=/.test(def)) {
+    // Strip the unusable grid reference but keep the existing datum shift.
+    return def.replace(/\+nadgrids=\S+/g, '').replace(/\s+/g, ' ').trim();
+  }
 
-  // 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';
+  const datumKey = datumName?.trim().toLowerCase() ?? '';
+  const towgs84 = datumKey ? DATUM_TOWGS84[datumKey] : undefined;
+
+  if (!towgs84) {
+    if (datumKey && !unknownDatumWarningCache.has(datumKey)) {
+      unknownDatumWarningCache.add(datumKey);
+      console.warn(
+        `[reproject] EPSG:${code ?? '?'} ("${datumName}") needs browser-unavailable `
+        + 'datum grids and has no known +towgs84 fallback for its datum. '
+        + 'Positions will be aligned to the source CRS but may be tens of metres '
+        + 'off relative to WGS84/basemaps. Consider adding the datum to '
+        + 'DATUM_TOWGS84 in apps/viewer/src/lib/geo/reproject.ts.',
+      );
+    }
+    // Strip the grid reference; let proj4 fall through with no datum shift
+    // rather than silently substitute a wrong-region transform.
+    return def.replace(/\+nadgrids=\S+/g, '').replace(/\s+/g, ' ').trim();
+  }
 
   if (code && !approxDatumWarningCache.has(code)) {
     approxDatumWarningCache.add(code);
     console.warn(
       `[reproject] EPSG:${code} requires browser-unavailable datum grids; `
-      + 'using an approximate +towgs84 transform instead. '
+      + `using approximate +towgs84 for "${datumName}" instead. `
       + 'Expect metre-level XY differences for some locations.',
     );
   }
 
-  // Remove +nadgrids=... and add +towgs84
   return def.replace(/\+nadgrids=\S+/g, '').replace(/\s+/g, ' ').trim() + ' ' + towgs84;
 }
 
@@ -134,10 +241,13 @@ async function fetchProj4Def(epsgCode: string): Promise<string | null> {
  *
  * Resolution order:
  *   1. Cache hit
- *   2. Bundled EPSG index (7000+ codes with proj4 strings)
- *   3. Well-known CRS name lookup (e.g. "WGS 84" → EPSG:4326)
- *   4. UTM zone heuristic (from CRS metadata — mapZone, name, description, mapProjection)
- *   5. Fetch from epsg.io (network fallback)
+ *   2. Precision grid (NTv2/GeoTIFF) for codes where +towgs84 is too coarse
+ *      (RD/NL, OSGB/UK, BD72/BE) — fetched once from cdn.proj.org, gives
+ *      sub-decimeter accuracy. Falls through to (3) if the fetch fails.
+ *   3. Bundled EPSG index (7000+ codes with proj4 strings)
+ *   4. Well-known CRS name lookup (e.g. "WGS 84" → EPSG:4326)
+ *   5. UTM zone heuristic (from CRS metadata — mapZone, name, description, mapProjection)
+ *   6. Fetch from epsg.io (network fallback)
  */
 export async function resolveProjection(crs: ProjectedCRS): Promise<string | null> {
   let code = extractEpsgCode(crs);
@@ -147,12 +257,29 @@ export async function resolveProjection(crs: ProjectedCRS): Promise<string | nul
     return projDefCache.get(code) ?? null;
   }
 
-  // 2. Bundled EPSG index (primary source — all 7000+ codes)
+  // 2. Precision grid (NTv2/GeoTIFF). For Bessel-based national grids
+  // (RD/NL, BD72/BE, OSGB/UK), the +towgs84 approximation that the bundled
+  // entries carry is off by 80-200 m. proj4js can consume PROJ's GeoTIFF
+  // datum-shift grids — load and register, then use a +nadgrids-based
+  // proj4 string for sub-decimeter accuracy.
+  if (code) {
+    try {
+      const precisionDef = await resolvePrecisionDef(code);
+      if (precisionDef) {
+        projDefCache.set(code, precisionDef);
+        return precisionDef;
+      }
+    } catch (error) {
+      console.warn(`[reproject] precision grid resolution failed for EPSG:${code}, falling back`, error);
+    }
+  }
+
+  // 3. Bundled EPSG index (primary source — all 7000+ codes)
   if (code) {
     try {
-      const bundled = await lookupProj4(code);
-      if (bundled) {
-        const sanitized = sanitizeProj4(bundled, code);
+      const entry = await lookupEpsgByCode(code);
+      if (entry?.proj4) {
+        const sanitized = sanitizeProj4(entry.proj4, code, entry.datum);
         projDefCache.set(code, sanitized);
         return sanitized;
       }
@@ -161,7 +288,7 @@ export async function resolveProjection(crs: ProjectedCRS): Promise<string | nul
     }
   }
 
-  // 3. Well-known CRS name → EPSG code (handles "WGS 84", "NAD83", etc.)
+  // 3. Well-known CRS name → EPSG code (handles "WGS 84", "NAD83", "RD New", etc.)
   if (!code) {
     const normalised = crs.name?.trim().toLowerCase() ?? '';
     const wellKnownCode = WELL_KNOWN_CRS[normalised];
@@ -171,9 +298,9 @@ export async function resolveProjection(crs: ProjectedCRS): Promise<string | nul
         return projDefCache.get(code) ?? null;
       }
       try {
-        const bundled = await lookupProj4(code);
-        if (bundled) {
-          const sanitized = sanitizeProj4(bundled, code);
+        const entry = await lookupEpsgByCode(code);
+        if (entry?.proj4) {
+          const sanitized = sanitizeProj4(entry.proj4, code, entry.datum);
           projDefCache.set(code, sanitized);
           // For geographic CRS (longlat), check if we can infer a projected CRS
           // from the UTM zone metadata — a projected CRS is much more useful.
@@ -215,7 +342,12 @@ export async function resolveProjection(crs: ProjectedCRS): Promise<string | nul
   // 5. Network fallback — fetch from epsg.io
   if (code) {
     const raw = await fetchProj4Def(code);
-    const fetched = raw ? sanitizeProj4(raw, code) : null;
+    // We don't have a bundled EpsgIndexEntry here (otherwise we'd have hit
+    // step 2), so fall back to parsing the datum name out of the proj4
+    // string itself when possible. `+datum=` is rare in modern proj4 output;
+    // the typical hint is `+ellps=` which we already accept as a weak signal
+    // inside DATUM_TOWGS84 keys above.
+    const fetched = raw ? sanitizeProj4(raw, code, null) : null;
     projDefCache.set(code, fetched);
     return fetched;
   }
@@ -295,7 +427,7 @@ export async function reprojectToLatLon(
 
   // MapConversion values use the unit from IfcProjectedCRS.MapUnit. If MapUnit
   // is not specified, the IFC spec defaults to the project's length unit.
-  const mapScale = crs.mapUnitScale ?? lengthUnitScale;
+  const mapScale = resolveMapUnitToMetreScale(crs.mapUnitScale, lengthUnitScale);
   const { easting, northing } = computeProjectedCenter(conversion, coordinateInfo, mapScale, lengthUnitScale);
 
   try {
@@ -369,7 +501,7 @@ export async function reprojectFromLatLon(
 
     // Convert projected metres back to MapConversion's unit.
     // Geometry offsets (ifcX/Y) are already in metres.
-    const mapScale = crs.mapUnitScale ?? lengthUnitScale;
+    const mapScale = resolveMapUnitToMetreScale(crs.mapUnitScale, lengthUnitScale);
     const invScale = mapScale !== 0 ? 1 / mapScale : 1;
     const { ifcX, ifcY } = computeModelCenterInIfcMeters(coordinateInfo);
     // Effective horizontal scale for metre-converted geometry — see issue #595.
@@ -419,7 +551,7 @@ export async function computeFootprintGeoJSON(
   }
 
   // Effective horizontal scale for metre-converted geometry — see issue #595.
-  const mapScale = crs.mapUnitScale ?? lengthUnitScale;
+  const mapScale = resolveMapUnitToMetreScale(crs.mapUnitScale, lengthUnitScale);
   const scale = getEffectiveHorizontalScale(conversion.scale, mapScale, lengthUnitScale);
   const abscissa = conversion.xAxisAbscissa ?? 1.0;
   const ordinate = conversion.xAxisOrdinate ?? 0.0;

package/src/lib/level-offsets.test.ts

@@ -0,0 +1,153 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  computeStoreyOffsets,
+  diffStoreyOffsets,
+  entitiesInStorey,
+  buildEntityTranslations,
+} from './level-offsets.js';
+
+/**
+ * Build a stub IfcDataStore with just the spatialHierarchy bits
+ * the offset helpers read. Other fields are typed as `unknown` so
+ * the cast doesn't pollute production code with test shims.
+ */
+function makeStore(
+  storeyElevations: Map<number, number>,
+  elementToStorey?: Map<number, number>,
+): Parameters<typeof computeStoreyOffsets>[0] {
+  return {
+    spatialHierarchy: {
+      storeyElevations,
+      elementToStorey: elementToStorey ?? new Map(),
+    },
+  } as unknown as Parameters<typeof computeStoreyOffsets>[0];
+}
+
+describe('level-offsets', () => {
+  describe('computeStoreyOffsets', () => {
+    it('returns empty for a missing data store', () => {
+      assert.strictEqual(computeStoreyOffsets(undefined, 4).size, 0);
+    });
+
+    it('returns empty when gap is zero', () => {
+      const store = makeStore(new Map([[1, 0], [2, 3]]));
+      assert.strictEqual(computeStoreyOffsets(store, 0).size, 0);
+    });
+
+    it('lifts higher storeys to index * gap', () => {
+      // Three storeys at elevations 0, 3, 6; with gap=5 they
+      // should land at 0, 5, 10 (offsets 0, +2, +4).
+      const store = makeStore(new Map([[10, 0], [20, 3], [30, 6]]));
+      const offsets = computeStoreyOffsets(store, 5);
+      assert.strictEqual(offsets.get(10), undefined); // zero — omitted
+      assert.strictEqual(offsets.get(20), 2);
+      assert.strictEqual(offsets.get(30), 4);
+    });
+
+    it('handles basement-style negative elevations', () => {
+      // Storeys at -3, 0, 3 with gap=4 → indices 0,1,2 → targets
+      // -3, 1, 5. Offsets 0, +1, +2.
+      const store = makeStore(new Map([[1, -3], [2, 0], [3, 3]]));
+      const offsets = computeStoreyOffsets(store, 4);
+      assert.strictEqual(offsets.get(1), undefined);
+      assert.strictEqual(offsets.get(2), 1);
+      assert.strictEqual(offsets.get(3), 2);
+    });
+
+    it('preserves elevation ordering with equal gaps', () => {
+      // Storeys with non-uniform original spacing should still
+      // become uniformly spaced under Exploded.
+      const store = makeStore(new Map([[1, 0], [2, 4], [3, 5], [4, 12]]));
+      const offsets = computeStoreyOffsets(store, 3);
+      // Targets: 0, 3, 6, 9. Deltas: 0, -1, +1, -3.
+      assert.strictEqual(offsets.get(1), undefined);
+      assert.strictEqual(offsets.get(2), -1);
+      assert.strictEqual(offsets.get(3), 1);
+      assert.strictEqual(offsets.get(4), -3);
+    });
+  });
+
+  describe('diffStoreyOffsets', () => {
+    it('returns the per-storey delta between target and previous', () => {
+      const target = new Map([[1, 2], [2, 5]]);
+      const previous = new Map([[1, 1], [2, 6]]);
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.get(1), 1); // 2 - 1
+      assert.strictEqual(diff.get(2), -1); // 5 - 6
+    });
+
+    it('treats missing target as revert to zero', () => {
+      const target = new Map<number, number>();
+      const previous = new Map([[1, 3], [2, 4]]);
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.get(1), -3);
+      assert.strictEqual(diff.get(2), -4);
+    });
+
+    it('treats new target with no previous as full lift', () => {
+      const target = new Map([[1, 5]]);
+      const previous = new Map<number, number>();
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.get(1), 5);
+    });
+
+    it('omits zero-delta entries', () => {
+      const target = new Map([[1, 3]]);
+      const previous = new Map([[1, 3]]);
+      const diff = diffStoreyOffsets(target, previous);
+      assert.strictEqual(diff.size, 0);
+    });
+  });
+
+  describe('entitiesInStorey', () => {
+    it('returns globalIds of every entity in the storey', () => {
+      const store = makeStore(
+        new Map(),
+        new Map([
+          [100, 1],
+          [101, 1],
+          [200, 2],
+        ]),
+      );
+      const ids = entitiesInStorey(store, 1, (id) => id + 10000);
+      ids.sort();
+      assert.deepStrictEqual(ids, [10100, 10101]);
+    });
+
+    it('returns empty when the storey has no children', () => {
+      const store = makeStore(new Map(), new Map([[100, 2]]));
+      assert.deepStrictEqual(entitiesInStorey(store, 1, (id) => id), []);
+    });
+  });
+
+  describe('buildEntityTranslations', () => {
+    it('emits per-entity Y deltas for every entity in an offset-bearing storey', () => {
+      const store = makeStore(
+        new Map(),
+        new Map([
+          [100, 1], // storey 1, dy=2
+          [101, 1],
+          [200, 2], // storey 2, dy=5
+          [300, 3], // storey 3, no offset → skipped
+        ]),
+      );
+      const offsets = new Map([[1, 2], [2, 5]]);
+      const translations = buildEntityTranslations(store, offsets, (id) => id + 1000);
+      assert.deepStrictEqual(translations.get(1100), [0, 2, 0]);
+      assert.deepStrictEqual(translations.get(1101), [0, 2, 0]);
+      assert.deepStrictEqual(translations.get(1200), [0, 5, 0]);
+      assert.strictEqual(translations.get(1300), undefined);
+    });
+
+    it('omits zero offsets', () => {
+      const store = makeStore(new Map(), new Map([[100, 1]]));
+      const offsets = new Map([[1, 0]]);
+      assert.strictEqual(buildEntityTranslations(store, offsets, (id) => id).size, 0);
+    });
+  });
+});

package/src/lib/level-offsets.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/. */
+
+/**
+ * Pure offset math for the Exploded level-display mode.
+ *
+ * Given a model's spatial hierarchy, computes the Y offset (in
+ * world / renderer frame) each storey should receive at a given
+ * `gap`. Index 0 stays at its native elevation; subsequent
+ * storeys (sorted by elevation ascending) lift by
+ * `(index - 0) × gap - elevationDelta` so they end up at
+ * `index × gap` relative to the lowest storey's Y.
+ *
+ * The output is `Map<storeyId, deltaY>` — pure data, no
+ * side-effects — so callers can:
+ *
+ *   1. Compute the target offsets
+ *   2. Subtract the previously-applied offsets
+ *   3. Push the delta into `pendingMeshTranslations`
+ *
+ * That subtraction is what makes mode toggles + gap changes
+ * reversible without re-loading geometry.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+
+export type StoreyOffsets = Map<number /* storey express id */, number /* renderer Y offset, m */>;
+
+/**
+ * Compute target offsets for `gap` based on the model's spatial
+ * hierarchy. Returns an empty map for models with no storeys, or
+ * with `gap = 0` (which is Stacked semantics).
+ *
+ * IFC convention: storey elevations are in the model's storey-
+ * local frame (Z-up). The renderer is Y-up, so an IFC elevation
+ * `e` translates to renderer Y `e` (the geometry pipeline already
+ * applies the swap when meshes are built).
+ */
+export function computeStoreyOffsets(
+  dataStore: IfcDataStore | undefined,
+  gap: number,
+): StoreyOffsets {
+  if (!dataStore || !Number.isFinite(gap) || gap <= 0) return new Map();
+  const elevations = dataStore.spatialHierarchy?.storeyElevations;
+  if (!elevations || elevations.size === 0) return new Map();
+
+  // Sort storeys by elevation ascending so the lowest storey
+  // keeps its native Y and everything above lifts.
+  const sorted = [...elevations.entries()].sort((a, b) => a[1] - b[1]);
+  const baseElevation = sorted[0][1];
+  const out: StoreyOffsets = new Map();
+  for (let i = 0; i < sorted.length; i++) {
+    const [storeyId, elevation] = sorted[i];
+    const targetY = baseElevation + i * gap;
+    const offset = targetY - elevation;
+    if (offset !== 0) out.set(storeyId, offset);
+  }
+  return out;
+}
+
+/**
+ * Diff a target offset map against the previously-applied map.
+ * Result: `Map<storeyId, deltaY>` such that
+ *
+ *   newAppliedY = oldAppliedY + delta = targetY
+ *
+ * Storeys present in `previous` but not `target` get a delta of
+ * `-previous[storeyId]` (they're reverting to Stacked). Storeys
+ * in `target` but not `previous` get `+target[storeyId]` (they're
+ * lifting fresh). Storeys in both get the difference.
+ *
+ * Zero deltas are omitted so the caller doesn't push no-ops.
+ */
+export function diffStoreyOffsets(
+  target: StoreyOffsets,
+  previous: StoreyOffsets,
+): StoreyOffsets {
+  const out: StoreyOffsets = new Map();
+  for (const [storeyId, prev] of previous) {
+    const next = target.get(storeyId) ?? 0;
+    const delta = next - prev;
+    if (delta !== 0) out.set(storeyId, delta);
+  }
+  for (const [storeyId, next] of target) {
+    if (previous.has(storeyId)) continue;
+    if (next !== 0) out.set(storeyId, next);
+  }
+  return out;
+}
+
+/**
+ * Resolve every entity in a storey to its globalId for the given
+ * model index. Walks `spatialHierarchy.elementToStorey` and
+ * filters to entries matching `storeyExpressId`. Returns an empty
+ * array when the hierarchy is missing.
+ *
+ * `toGlobalId` is injected so the helper stays free of
+ * FederationRegistry imports (keeps it test-friendly).
+ */
+export function entitiesInStorey(
+  dataStore: IfcDataStore | undefined,
+  storeyExpressId: number,
+  toGlobalId: (localExpressId: number) => number,
+): number[] {
+  if (!dataStore) return [];
+  const map = dataStore.spatialHierarchy?.elementToStorey;
+  if (!map) return [];
+  const out: number[] = [];
+  for (const [elementId, sid] of map) {
+    if (sid !== storeyExpressId) continue;
+    out.push(toGlobalId(elementId));
+  }
+  return out;
+}
+
+/**
+ * Build a per-entity-globalId translation map for a model from a
+ * storey-offset map. Used by the level-display effect to push
+ * into `pendingMeshTranslations`. The translation is along world
+ * +Y only (storey lift) so the X/Z components are zero.
+ *
+ * `toGlobalId` is injected for the same reason as above.
+ */
+export function buildEntityTranslations(
+  dataStore: IfcDataStore | undefined,
+  offsetsByStorey: StoreyOffsets,
+  toGlobalId: (localExpressId: number) => number,
+): Map<number, [number, number, number]> {
+  const out = new Map<number, [number, number, number]>();
+  if (!dataStore || offsetsByStorey.size === 0) return out;
+  const elementToStorey = dataStore.spatialHierarchy?.elementToStorey;
+  if (!elementToStorey) return out;
+  for (const [elementId, storeyId] of elementToStorey) {
+    const dy = offsetsByStorey.get(storeyId);
+    if (dy === undefined || dy === 0) continue;
+    out.set(toGlobalId(elementId), [0, dy, 0]);
+  }
+  return out;
+}