@ifc-lite/viewer 1.22.0 → 1.22.1

package/src/hooks/useKeyboardShortcuts.ts

@@ -48,6 +48,7 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
   const hideEntities = useViewerStore((s) => s.hideEntities);
   const toggleTheme = useViewerStore((s) => s.toggleTheme);
   const toggleBasketPresentationVisible = useViewerStore((s) => s.toggleBasketPresentationVisible);
+  const toggleEditEnabled = useViewerStore((s) => s.toggleEditEnabled);
 
   // Measure tool specific actions
   const activeMeasurement = useViewerStore((s) => s.activeMeasurement);
@@ -71,6 +72,19 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
     const shift = e.shiftKey;
     const key = e.key.toLowerCase();
 
+    // Undo / Redo — Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z, scoped to the
+    // active model's mutation stack. Always available regardless
+    // of edit mode so the user can recover from any change.
+    if (key === 'z' && ctrl) {
+      e.preventDefault();
+      const state = useViewerStore.getState();
+      const activeModelId = state.activeModelId;
+      if (!activeModelId) return;
+      if (shift) state.redo(activeModelId);
+      else state.undo(activeModelId);
+      return;
+    }
+
     // Navigation tools
     if (key === 'v' && !ctrl && !shift) {
       e.preventDefault();
@@ -93,6 +107,60 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       setActiveTool('annotate');
     }
 
+    // Global edit-mode pill — unlocks inline property/attribute
+    // editors, add-element draw tools, georeference placement, and
+    // future geometry manipulators. Toggle from anywhere outside an
+    // input field.
+    if (key === 'e' && !ctrl && !shift) {
+      e.preventDefault();
+      toggleEditEnabled();
+    }
+
+    // K = knife / Split. Operates only on the currently selected
+    // entity — there's no free-roam "hover anything and split" mode
+    // any more. If there's no selection, the keypress is a no-op
+    // (a toast would be noisy; the user can see no entity is
+    // selected). The action also pre-arms the splitTarget so the
+    // overlay knows what to draw the moment Split engages.
+    if (key === 'k' && !ctrl && !shift) {
+      e.preventDefault();
+      const state = useViewerStore.getState();
+      if (state.activeTool === 'split') {
+        state.clearSplitHover();
+        state.setActiveTool('select');
+        return;
+      }
+      const sel = state.selectedEntity;
+      if (!sel) return;
+      state.setSplitTarget(sel.modelId, sel.expressId);
+      state.setActiveTool('split');
+    }
+
+    // R / Shift+R = rotate selected entity ±15° about the storey-up
+    // Z axis. Only fires while edit mode is on and a single entity
+    // is selected. The rotateEntity action handles the placement
+    // chain walk + undo registration.
+    if (key === 'r' && !ctrl) {
+      const state = useViewerStore.getState();
+      if (state.editEnabled && state.selectedEntity) {
+        e.preventDefault();
+        const deltaDeg = shift ? -15 : 15;
+        const result = state.rotateEntity(
+          state.selectedEntity.modelId,
+          state.selectedEntity.expressId,
+          (deltaDeg * Math.PI) / 180,
+        );
+        if (!result.ok) {
+          // Surface the reason via the existing toast helper rather
+          // than a console warning — the user just pressed a key and
+          // deserves immediate feedback.
+          void import('@/components/ui/toast').then((m) => {
+            m.toast.error(`Couldn't rotate: ${result.reason}`);
+          });
+        }
+      }
+    }
+
     // Basket controls (automatic context source)
     // I = Isolate from current context
     if (key === 'i' && !ctrl && !shift) {
@@ -154,6 +222,18 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
       resetVisibilityForHomeFromStore();
     }
 
+    // Split tool — Esc exits Split and returns to Select. We catch
+    // it here before the global Esc handler so the user gets a
+    // gentle exit (clear hover, swap tool) rather than the global
+    // "clear all selection + visibility" cascade.
+    if (activeTool === 'split' && key === 'escape') {
+      e.preventDefault();
+      const state = useViewerStore.getState();
+      state.clearSplitHover();
+      state.setActiveTool('select');
+      return;
+    }
+
     // 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).
@@ -250,6 +330,7 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
     cancelMeasurement,
     clearMeasurements,
     toggleSnap,
+    toggleEditEnabled,
   ]);
 
   useEffect(() => {
@@ -264,11 +345,16 @@ export function useKeyboardShortcuts(options: KeyboardShortcutsOptions = {}) {
 
 // Export shortcut definitions for UI display
 export const KEYBOARD_SHORTCUTS = [
+  { key: 'Ctrl+Z / Cmd+Z', description: 'Undo last authoring change for the active model', category: 'Editing' },
+  { key: 'Ctrl+Shift+Z / Cmd+Shift+Z', description: 'Redo last undone change', category: 'Editing' },
   { 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: 'E', description: 'Toggle edit mode (unlocks property + geometry edits)', category: 'Tools' },
+  { key: 'K', description: 'Split the selected entity (requires a selection)', category: 'Tools' },
+  { key: 'R / Shift+R', description: 'Rotate selected entity ±15° about Z (requires edit mode)', category: 'Tools' },
   { key: 'S', description: 'Toggle snapping (Measure tool)', category: 'Tools' },
   { key: 'Esc', description: 'Cancel measurement (Measure tool)', category: 'Tools' },
   { key: 'Ctrl+C', description: 'Clear measurements (Measure tool)', category: 'Tools' },

package/src/hooks/useLevelDisplayEffect.ts

@@ -0,0 +1,160 @@
+/* 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/. */
+
+/**
+ * Drive Exploded / Solo level display modes from the slice state.
+ *
+ * Stacked:
+ *   - Subtract any previously-applied Exploded offsets so the
+ *     renderer's mesh positions revert to their loaded values.
+ *   - Clear isolation if we're coming out of Solo.
+ *
+ * Exploded:
+ *   - Compute per-storey offsets via `computeStoreyOffsets` for
+ *     each loaded model.
+ *   - Diff against the per-model `appliedStoreyOffsets` and push
+ *     the deltas into `pendingMeshTranslations` so the renderer
+ *     applies them on the next frame.
+ *   - Stash the new applied offsets on the slice so the next
+ *     toggle / gap change knows what to subtract.
+ *
+ * Solo:
+ *   - Use the existing `setIsolatedEntities` channel to gate
+ *     visibility to the chosen storey's entities (resolved to
+ *     federation global ids).
+ *
+ * The hook reads from a slim selector (`useViewerStore`) and only
+ * runs its work when `levelDisplayMode`, `explodedGap`, or the
+ * set of loaded models changes. No per-frame work.
+ */
+
+import { useEffect, useRef } from 'react';
+import { useViewerStore } from '@/store';
+import { toGlobalIdFromModels } from '@/store/globalId';
+import {
+  computeStoreyOffsets,
+  diffStoreyOffsets,
+  buildEntityTranslations,
+  entitiesInStorey,
+  type StoreyOffsets,
+} from '@/lib/level-offsets';
+
+export function useLevelDisplayEffect(): void {
+  const levelDisplayMode = useViewerStore((s) => s.levelDisplayMode);
+  const explodedGap = useViewerStore((s) => s.explodedGap);
+  const soloStorey = useViewerStore((s) => s.soloStorey);
+  const models = useViewerStore((s) => s.models);
+  const activeModelId = useViewerStore((s) => s.activeModelId);
+  const appliedStoreyOffsets = useViewerStore((s) => s.appliedStoreyOffsets);
+  const setAppliedStoreyOffsets = useViewerStore((s) => s.setAppliedStoreyOffsets);
+  const setPendingMeshTranslations = useViewerStore((s) => s.setPendingMeshTranslations);
+  const setIsolatedEntities = useViewerStore((s) => s.setIsolatedEntities);
+
+  // Track the last-applied mode so the cleanup logic can tell
+  // "user is exiting Exploded" from "user is changing gap inside
+  // Exploded". Without this, the diff math handles both, but
+  // having a discrete flag makes it cheap to skip Solo→Solo
+  // re-entry without touching translations.
+  const lastModeRef = useRef(levelDisplayMode);
+
+  useEffect(() => {
+    // Compute the target Exploded offsets per model. `target` is
+    // empty when Exploded isn't active — diff against the
+    // previously-applied offsets will revert any lifts.
+    const target: typeof appliedStoreyOffsets = new Map();
+    if (levelDisplayMode === 'exploded') {
+      for (const [modelId, model] of models) {
+        if (!model.ifcDataStore) continue;
+        const offsets = computeStoreyOffsets(model.ifcDataStore, explodedGap);
+        if (offsets.size > 0) target.set(modelId, offsets);
+      }
+    }
+
+    // Build the renderer-frame translation map by diffing the
+    // target against the slice's applied snapshot, per model. Sum
+    // into a single Map<globalId, [dx,dy,dz]> so one push covers
+    // the whole scene.
+    const aggregated = new Map<number, [number, number, number]>();
+    const modelIds = new Set<string>([
+      ...models.keys(),
+      ...appliedStoreyOffsets.keys(),
+    ]);
+    for (const modelId of modelIds) {
+      const targetMap: StoreyOffsets = target.get(modelId) ?? new Map();
+      const previousMap: StoreyOffsets = appliedStoreyOffsets.get(modelId) ?? new Map();
+      const diff = diffStoreyOffsets(targetMap, previousMap);
+      if (diff.size === 0) continue;
+      const dataStore = models.get(modelId)?.ifcDataStore;
+      if (!dataStore) continue;
+      const toGlobalId = (localExpressId: number): number =>
+        toGlobalIdFromModels(models, modelId, localExpressId);
+      const perEntity = buildEntityTranslations(dataStore, diff, toGlobalId);
+      for (const [id, delta] of perEntity) {
+        const existing = aggregated.get(id);
+        if (existing) {
+          aggregated.set(id, [existing[0] + delta[0], existing[1] + delta[1], existing[2] + delta[2]]);
+        } else {
+          aggregated.set(id, [delta[0], delta[1], delta[2]]);
+        }
+      }
+    }
+    if (aggregated.size > 0) {
+      setPendingMeshTranslations(aggregated);
+    }
+    setAppliedStoreyOffsets(target);
+
+    // Solo isolation. Resolve against the (modelId, expressId)
+    // pair the slice stores so federated scenes with overlapping
+    // storey express-ids isolate the right one. Slice default is
+    // null → pick the lowest-elevation storey of the active model.
+    if (levelDisplayMode === 'solo') {
+      let targetModelId: string | null = soloStorey?.modelId ?? null;
+      let storeyId: number | null = soloStorey?.expressId ?? null;
+      if (targetModelId === null || storeyId === null) {
+        // Cold-start default — fall back to the active model's
+        // lowest storey ONLY when the slice has no explicit pick.
+        const fallbackModelId = activeModelId ?? models.keys().next().value ?? null;
+        const fallbackStore = fallbackModelId ? models.get(fallbackModelId)?.ifcDataStore : undefined;
+        if (fallbackModelId && fallbackStore) {
+          const elevations = fallbackStore.spatialHierarchy?.storeyElevations;
+          if (elevations && elevations.size > 0) {
+            const lowest = [...elevations.entries()].sort((a, b) => a[1] - b[1])[0][0];
+            targetModelId = fallbackModelId;
+            storeyId = lowest;
+          }
+        }
+      }
+      const targetStore = targetModelId ? models.get(targetModelId)?.ifcDataStore : undefined;
+      if (targetModelId !== null && storeyId !== null && targetStore) {
+        const resolvedModelId = targetModelId;
+        const toGlobalId = (localExpressId: number): number =>
+          toGlobalIdFromModels(models, resolvedModelId, localExpressId);
+        const ids = entitiesInStorey(targetStore, storeyId, toGlobalId);
+        setIsolatedEntities(new Set(ids));
+      } else {
+        setIsolatedEntities(null);
+      }
+    } else if (lastModeRef.current === 'solo') {
+      // Leaving Solo → drop isolation. (User may have manually
+      // re-isolated via the basket; we still clear because the
+      // Solo cleanup should be predictable. Tradeoff documented.)
+      setIsolatedEntities(null);
+    }
+
+    lastModeRef.current = levelDisplayMode;
+    // appliedStoreyOffsets is intentionally NOT a dep — we write
+    // to it as a side effect; depending on it would loop. The
+    // ref-based last-mode check covers the Solo→other case.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    levelDisplayMode,
+    explodedGap,
+    soloStorey,
+    models,
+    activeModelId,
+    setPendingMeshTranslations,
+    setIsolatedEntities,
+    setAppliedStoreyOffsets,
+  ]);
+}

package/src/hooks/useViewerSelectors.ts

@@ -212,14 +212,22 @@ export function useContextMenuState() {
 export function useColorUpdateState() {
   const pendingColorUpdates = useViewerStore((state) => state.pendingColorUpdates);
   const pendingMeshColorUpdates = useViewerStore((state) => state.pendingMeshColorUpdates);
+  const pendingMeshRemovals = useViewerStore((state) => state.pendingMeshRemovals);
+  const pendingMeshTranslations = useViewerStore((state) => state.pendingMeshTranslations);
   const clearPendingColorUpdates = useViewerStore((state) => state.clearPendingColorUpdates);
   const clearPendingMeshColorUpdates = useViewerStore((state) => state.clearPendingMeshColorUpdates);
+  const clearPendingMeshRemovals = useViewerStore((state) => state.clearPendingMeshRemovals);
+  const clearPendingMeshTranslations = useViewerStore((state) => state.clearPendingMeshTranslations);
 
   return {
     pendingColorUpdates,
     pendingMeshColorUpdates,
+    pendingMeshRemovals,
+    pendingMeshTranslations,
     clearPendingColorUpdates,
     clearPendingMeshColorUpdates,
+    clearPendingMeshRemovals,
+    clearPendingMeshTranslations,
   };
 }
 

package/src/lib/__test__/stubs.ts

@@ -0,0 +1,110 @@
+/* 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/. */
+
+/**
+ * Test stubs shared across the lib/ helper test suites. Each
+ * helper that walks the IFC attribute graph
+ * (placement-core / wall-edit / slab-edit / linear-element-edit /
+ * metadata-clone / wall-opening-reassign) wants the same minimal
+ * mocks: an in-memory `StoreEditor` that returns overlay entities
+ * + records positional writes, a `MutablePropertyView` whose
+ * `getPositionalMutationsForEntity` is a no-op, and an
+ * `IfcDataStore` shim with a `entityIndex.byType` map for the
+ * helpers that scan by type. Centralising them here removes the
+ * five-way duplication and keeps the harness consistent when one
+ * helper's contract evolves.
+ *
+ * Production code never imports from this module — the lib/
+ * helpers take their dependencies via constructor / parameter so
+ * the real `@ifc-lite/mutations` + `@ifc-lite/parser` types slot
+ * in at runtime.
+ */
+
+import type { reassignWallOpenings } from '../wall-opening-reassign.js';
+
+export interface OverlayEntity {
+  expressId: number;
+  type: string;
+  attributes: unknown[];
+}
+
+/**
+ * Minimal `StoreEditor` stand-in. Records positional writes by
+ * mutating the matching overlay entity's `attributes` array (same
+ * effect the real editor has via the property view). `addEntity`
+ * mirrors the real editor for tests that exercise creation paths
+ * (rotation IfcDirection materialise, etc.).
+ */
+export class StubStoreEditor {
+  private overlay = new Map<number, OverlayEntity>();
+  private positional = new Map<number, Map<number, unknown>>();
+  private nextId: number;
+
+  constructor(initial: OverlayEntity[]) {
+    for (const e of initial) this.overlay.set(e.expressId, e);
+    this.nextId = Math.max(0, ...initial.map((e) => e.expressId)) + 1;
+  }
+
+  getNewEntity(id: number): OverlayEntity | null {
+    return this.overlay.get(id) ?? null;
+  }
+
+  setPositionalAttribute(id: number, index: number, value: unknown): void {
+    let entry = this.positional.get(id);
+    if (!entry) {
+      entry = new Map();
+      this.positional.set(id, entry);
+    }
+    entry.set(index, value);
+    const ent = this.overlay.get(id);
+    if (ent) ent.attributes[index] = value;
+  }
+
+  addEntity(type: string, attributes: unknown[]): { expressId: number } {
+    const id = this.nextId++;
+    this.overlay.set(id, { expressId: id, type, attributes: attributes.slice() });
+    return { expressId: id };
+  }
+}
+
+/**
+ * Minimal `MutablePropertyView` stand-in. Returns no positional
+ * overrides by default. Tests that need pre-mutation state can
+ * call `setPositionalForTest` to seed an override; the helper
+ * then reads it back via `getPositionalMutationsForEntity`.
+ */
+export class StubView {
+  private positional = new Map<number, Map<number, unknown>>();
+
+  getPositionalMutationsForEntity(id: number): Map<number, unknown> | null {
+    return this.positional.get(id) ?? null;
+  }
+
+  setPositionalForTest(id: number, index: number, value: unknown): void {
+    let entry = this.positional.get(id);
+    if (!entry) {
+      entry = new Map();
+      this.positional.set(id, entry);
+    }
+    entry.set(index, value);
+  }
+}
+
+/**
+ * Stub `IfcDataStore` — only the `entityIndex.byType` map is
+ * meaningfully populated. `source` is an empty buffer; `byId` is
+ * an empty map so the parser-backed source reader (registered via
+ * `setSourceAttrsReader` in production) never matches anything,
+ * which is correct for overlay-only test fixtures.
+ *
+ * Pass `byType: new Map([['IFCRELDEFINESBYPROPERTIES', [50]]])`
+ * to expose rels for `cloneElementMetadata` /
+ * `reassignWallOpenings` style tests.
+ */
+export function makeStubDataStore(byType: Map<string, number[]> = new Map()): Parameters<typeof reassignWallOpenings>[0] {
+  return {
+    source: new Uint8Array(),
+    entityIndex: { byId: new Map(), byType },
+  } as unknown as Parameters<typeof reassignWallOpenings>[0];
+}

package/src/lib/geo/cesium-bridge.ts

@@ -34,7 +34,7 @@ import {
   type ResolveTerrainElevationOptions,
   type TerrainElevationSample,
 } from './terrain-elevation';
-import { getEffectiveHorizontalScale } from './geo-scale';
+import { getEffectiveHorizontalScale, resolveMapUnitToMetreScale } from './geo-scale';
 
 export interface GeodesicPosition {
   longitude: number;
@@ -94,7 +94,7 @@ export async function computeCesiumModelOrigin(
   const absc = mapConversion.xAxisAbscissa ?? 1.0;
   const ordi = mapConversion.xAxisOrdinate ?? 0.0;
   const center = computeModelCenterInIfcMeters(coordinateInfo);
-  const mapScale = projectedCRS.mapUnitScale ?? lengthUnitScale;
+  const mapScale = resolveMapUnitToMetreScale(projectedCRS.mapUnitScale, lengthUnitScale);
   const horizontalScale = getEffectiveHorizontalScale(
     mapConversion.scale,
     mapScale,
@@ -169,7 +169,7 @@ export async function createCesiumBridge(
     height: origin.height,
   };
   const hScale = origin.horizontalScale;
-  const mapScale = projectedCRS.mapUnitScale ?? lengthUnitScale;
+  const mapScale = resolveMapUnitToMetreScale(projectedCRS.mapUnitScale, lengthUnitScale);
   const oHeight = origin.height;
   const originLon = origin.longitude;
   const originLat = origin.latitude;

package/src/lib/geo/cesium-placement.test.ts

@@ -20,9 +20,19 @@ import {
 } from './cesium-placement.js';
 
 describe('cesium placement helpers', () => {
-  it('falls back to the project length unit when mapUnitScale is absent', () => {
-    assert.strictEqual(getMapUnitScale(undefined, 0.001), 0.001);
+  it('defaults to METRES when MapUnit is absent (overrides project length unit)', () => {
+    // Per IFC4 spec, missing MapUnit falls back to the project's length unit.
+    // In practice (Bonsai/IfcOpenShell/Revit), MapConversion offsets are
+    // authored in METRES regardless of project unit. Honouring the spec
+    // pushes offsets thousands of km out of the CRS's valid range and lands
+    // models at the projection's antipode (Hans's IXAS_KW 018 file: mm
+    // project + MapConversion (126500, 480000) → South Pacific instead of
+    // Netherlands). See `resolveMapUnitToMetreScale` rationale.
+    assert.strictEqual(getMapUnitScale(undefined, 0.001), 1);
     assert.strictEqual(getMapUnitScale({ mapUnitScale: 1 }, 0.001), 1);
+    // Explicit non-metre MapUnit still wins — the heuristic only fires when
+    // MapUnit is unset.
+    assert.strictEqual(getMapUnitScale({ mapUnitScale: 0.3048006096 }, 1), 0.3048006096);
   });
 
   it('converts between metres and map units using ProjectedCRS.mapUnitScale', () => {
@@ -41,7 +51,9 @@ describe('cesium placement helpers', () => {
     assert.strictEqual(shouldPreferOrthometricTerrain(undefined), false);
   });
 
-  it('computes terrain-clamped placement and clip plane from storey anchor', () => {
+  it('places the model at its authored IFC height — no terrain/storey clamp', () => {
+    // Model placement is purely IfcMapConversion.OrthogonalHeight + the
+    // geometry origin. Terrain and storey data never move the model.
     const placement = computeCesiumPlacement({
       coordinateInfo: {
         originShift: { x: 0, y: 0, z: 0 },
@@ -61,21 +73,25 @@ describe('cesium placement helpers', () => {
       storeyElevations: new Map([[1, -3], [2, 0], [3, 3]]),
     });
 
+    // placementHeight == authored ifcOriginHeight, NOT terrain+anchorOffset.
+    assert.strictEqual(placement.placementHeight, 244);
+    // clampAnchorY / anchorOffset are still derived (gizmo + clip math use
+    // them) but no longer feed placementHeight.
     assert.strictEqual(placement.clampAnchorY, 0);
     assert.strictEqual(placement.anchorOffset, 3);
-    assert.strictEqual(placement.placementHeight, 248);
-    assert.strictEqual(placement.terrainClipY, 0);
     assert.strictEqual(placement.preferOrthometricTerrain, true);
   });
 
-  it('preserves authored OrthogonalHeight when it is already above terrain', () => {
-    const placement = computeCesiumPlacement({
-      ifcOriginHeight: 244,
-      terrainHeight: 195.4,
-    });
+  it('keeps the authored height whether it is above OR below terrain', () => {
+    // Above terrain — unchanged.
+    const above = computeCesiumPlacement({ ifcOriginHeight: 244, terrainHeight: 195.4 });
+    assert.strictEqual(above.placementHeight, 244);
 
-    assert.strictEqual(placement.placementHeight, 244);
-    assert.strictEqual(placement.terrainClipY, -48.599999999999994);
+    // Below terrain — the model stays sub-grade, NOT lifted to terrain.
+    // (Regression: the old Math.max floor pinned it to terrain, which froze
+    //  the vertical placement gizmo and lifted basements above ground.)
+    const below = computeCesiumPlacement({ ifcOriginHeight: -20, terrainHeight: 70.61 });
+    assert.strictEqual(below.placementHeight, -20);
   });
 
   it('computes OrthogonalHeight from target base altitude with shift and RTC', () => {

package/src/lib/geo/cesium-placement.ts

@@ -7,15 +7,13 @@ import type { MapConversion, ProjectedCRS } from '@ifc-lite/parser';
 
 import { findClampAnchorY } from './clamp-anchor';
 import { computeModelCenterInIfcMeters } from './reproject';
-import { getEffectiveHorizontalScale } from './geo-scale';
+import { getEffectiveHorizontalScale, resolveMapUnitToMetreScale } from './geo-scale';
 
 export function getMapUnitScale(
   projectedCRS: Pick<ProjectedCRS, 'mapUnitScale'> | undefined,
   lengthUnitScale: number,
 ): number {
-  const mapUnitScale = projectedCRS?.mapUnitScale;
-  if (typeof mapUnitScale === 'number' && mapUnitScale > 0) return mapUnitScale;
-  return lengthUnitScale > 0 ? lengthUnitScale : 1;
+  return resolveMapUnitToMetreScale(projectedCRS?.mapUnitScale, lengthUnitScale);
 }
 
 export function mapUnitsToMeters(
@@ -60,6 +58,18 @@ export interface CesiumPlacementResult {
   preferOrthometricTerrain: boolean;
 }
 
+/**
+ * Resolve where the model sits in Cesium.
+ *
+ * Placement is PURELY the IFC's authored altitude — `ifcOriginHeight`
+ * (IfcMapConversion.OrthogonalHeight + the geometry origin). There is NO
+ * automatic terrain or storey clamp: the model goes exactly where the file
+ * says, full stop. Terrain is queried only to inform the camera and the
+ * optional below-terrain clip plane; it never moves the model.
+ *
+ * `clampAnchorY` / `anchorOffset` are still derived (the placement gizmo and
+ * the clip-plane math consume them) but they no longer feed `placementHeight`.
+ */
 export function computeCesiumPlacement({
   coordinateInfo,
   projectedCRS,
@@ -72,12 +82,8 @@ export function computeCesiumPlacement({
   const minY = bounds?.min.y ?? 0;
   const clampAnchorY = findClampAnchorY(bounds, storeyElevations);
   const anchorOffset = modelCenterY - clampAnchorY;
-  const terrainPlacementHeight = terrainHeight !== null
-    ? terrainHeight + anchorOffset
-    : null;
-  const placementHeight = terrainPlacementHeight !== null
-    ? Math.max(ifcOriginHeight, terrainPlacementHeight)
-    : ifcOriginHeight;
+  // Model placement = authored IFC altitude. No clamp. No auto-adjust.
+  const placementHeight = ifcOriginHeight;
 
   return {
     clampAnchorY,

package/src/lib/geo/effective-georef.test.ts

@@ -166,13 +166,29 @@ describe('effective georeferencing', () => {
       assert.strictEqual(getEffectiveHorizontalScale(2, 1, 1), 2);
     });
 
-    it('defaults Scale to 1 when undefined', () => {
-      // Project mm, map m, Scale undefined (treated as 1):
-      //   effective = 1 * 1 / 0.001 = 1000 → model would appear 1000x too large.
-      // This matches the IFC spec; users who omit Scale in such files have an
-      // inconsistent file. Issue #595 reports that this happens to "work"
-      // because the workaround offsets a different bug — fixed here.
-      assert.strictEqual(getEffectiveHorizontalScale(undefined, 1, 0.001), 1000);
+    it('treats Scale=undefined + unit mismatch as author-meant-Scale=1/lus (Bonsai heuristic)', () => {
+      // Project mm, map m, Scale undefined. Spec-strict effective = 1 * 1 /
+      // 0.001 = 1000 would inflate metre-converted geometry 1000x, pushing
+      // proj4 inputs miles outside the CRS valid range — the model lands at
+      // the projection's antipode (Hans's IXAS_KW 018_georeffed.ifc bug).
+      // Bonsai/IfcOpenShell/Revit exports routinely omit Scale; the author's
+      // intent is "geometry and offsets share the same metric unit", which
+      // corresponds to Scale=lengthUnitScale/mapUnitScale per spec → effective 1.
+      assert.strictEqual(getEffectiveHorizontalScale(undefined, 1, 0.001), 1);
+    });
+
+    it('treats Scale=1 + unit mismatch the same as Scale=undefined (heuristic also fires)', () => {
+      // Same situation as above, but the file wrote Scale=1 explicitly (also
+      // common — Revit's IFC exporter does this). The heuristic must catch
+      // both the missing-Scale and the wrong-Scale=1 cases.
+      assert.strictEqual(getEffectiveHorizontalScale(1, 1, 0.001), 1);
+    });
+
+    it('preserves spec-strict math when Scale ≠ 1 (the author opted in to a real scaling)', () => {
+      // Scale=2 with mm project + m map says "multiply X_local by 2 when
+      // adding to map offsets" — deliberate, not a unit-bridging mistake.
+      // Effective = (2 * 1) / 0.001 = 2000.
+      assert.strictEqual(getEffectiveHorizontalScale(2, 1, 0.001), 2000);
     });
 
     it('falls back to 1 for non-positive lengthUnitScale or mapUnitScale', () => {