@ifc-lite/viewer 1.22.0 → 1.23.0

package/src/lib/wall-opening-reassign.ts

@@ -0,0 +1,241 @@
+/* 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/. */
+
+/**
+ * When a wall is split, openings hosted on it (doors, windows,
+ * generic voids) need to move to whichever half they geometrically
+ * belong to — otherwise both halves carry the same void
+ * relationship and the export double-counts.
+ *
+ * IFC structure:
+ *
+ *   IfcWall ──IfcRelVoidsElement──► IfcOpeningElement
+ *                                    │
+ *                                    └── (optional) IfcRelFillsElement
+ *                                          ──► IfcDoor / IfcWindow
+ *
+ * The opening has its own `ObjectPlacement` whose `PlacementRelTo`
+ * points back at the wall's placement (per IFC convention). Its
+ * `RelativePlacement.Location.Coordinates` are in wall-local 3D,
+ * with X = distance along the wall axis. That distance is what
+ * decides the half:
+ *
+ *   if local-X < splitDistance ─► left half (no offset)
+ *   else                       ─► right half (subtract splitDistance from local-X
+ *                                              + repoint PlacementRelTo)
+ *
+ * Doors/windows hosted in an opening (via IfcRelFillsElement) are
+ * positioned relative to the opening, so they move along with it
+ * without any extra work.
+ *
+ * Source-wall openings whose placement does NOT match this
+ * canonical shape (e.g. world-absolute openings, openings with
+ * non-Cartesian placements, source-buffer entities with mapped
+ * representations) are skipped with a returned `skippedReasons`
+ * tally so the caller can surface a warning toast.
+ */
+
+import type { IfcDataStore } from '@ifc-lite/parser';
+import type { IfcAttributeValue, MutablePropertyView, StoreEditor } from '@ifc-lite/mutations';
+import { asExpressIdRef, asCoordinateTriple, readAttributes, resolvePlacementChain } from './placement-core.js';
+
+export interface OpeningReassignSummary {
+  /** Openings successfully moved onto the left half. */
+  toLeft: number;
+  /** Openings successfully moved onto the right half. */
+  toRight: number;
+  /** Openings whose placement we couldn't interpret; left attached
+   * to the (tombstoned) source. */
+  skipped: number;
+  /** Diagnostic reasons for the skips — small enum so the UI can
+   * group them in a single toast rather than one per opening. */
+  skipReasons: Map<string, number>;
+}
+
+function bumpReason(map: Map<string, number>, reason: string): void {
+  map.set(reason, (map.get(reason) ?? 0) + 1);
+}
+
+/**
+ * Rewrite `IfcRelVoidsElement.RelatingBuildingElement` to a new
+ * wall id, preserving the reference's form (`#X` strings vs bare
+ * numbers — the StoreEditor exports either; we don't want to
+ * accidentally normalise overlay refs into numbers).
+ */
+function rewriteRelTarget(
+  raw: unknown,
+  newTargetId: number,
+): IfcAttributeValue {
+  if (typeof raw === 'string' && raw.startsWith('#')) {
+    return `#${newTargetId}` as IfcAttributeValue;
+  }
+  return newTargetId as IfcAttributeValue;
+}
+
+/**
+ * Walk every `IfcRelVoidsElement` whose RelatingBuildingElement is
+ * `sourceWallId`. For each one:
+ *
+ *   1. Resolve the opening's wall-local X coord (= distance along
+ *      the wall axis).
+ *   2. Decide left / right by comparison to `splitDistance`.
+ *   3. Rewrite the rel's RelatingBuildingElement (attr 4) to the
+ *      chosen half.
+ *   4. Rewrite the opening's IfcLocalPlacement.PlacementRelTo
+ *      (attr 0) to the chosen half's placement.
+ *   5. For right-half openings, subtract `splitDistance` from the
+ *      opening's local-X coordinate so its world position stays
+ *      the same after the placement reparent.
+ *
+ * The split distance is in metres along the source wall's axis,
+ * measured from the source's start (matches
+ * `computeWallSplitGeometry`'s `distance` parameter).
+ */
+export function reassignWallOpenings(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  sourceWallId: number,
+  leftWallId: number,
+  rightWallId: number,
+  splitDistance: number,
+  /** `IfcLocalPlacement` ids for the two halves — needed because
+   * the opening's `PlacementRelTo` must point at the half's
+   * placement, not the half's IfcWall entity. */
+  leftPlacementId: number,
+  rightPlacementId: number,
+): OpeningReassignSummary {
+  const summary: OpeningReassignSummary = {
+    toLeft: 0,
+    toRight: 0,
+    skipped: 0,
+    skipReasons: new Map(),
+  };
+
+  // Resolve the source wall's IfcLocalPlacement so we can verify
+  // each opening was actually placed relative to it. Openings with
+  // world-absolute placements (PlacementRelTo = null) or placements
+  // relative to some other entity must NOT be reassigned — silently
+  // rewriting their PlacementRelTo would teleport them.
+  const sourceChain = resolvePlacementChain(dataStore, view, editor, sourceWallId);
+  if (!sourceChain) {
+    summary.skipped++;
+    bumpReason(summary.skipReasons, 'source wall placement unresolvable');
+    return summary;
+  }
+  const sourceWallPlacementId = sourceChain.localPlacementId;
+
+  const relIds = dataStore.entityIndex.byType.get('IFCRELVOIDSELEMENT') ?? [];
+  for (const relId of relIds) {
+    const relAttrs = readAttributes(dataStore, view, editor, relId);
+    if (!relAttrs) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'unreadable rel');
+      continue;
+    }
+    // IfcRelVoidsElement attrs (IFC4): [GlobalId, OwnerHistory,
+    // Name, Description, RelatingBuildingElement, RelatedOpeningElement]
+    const relatingBuilding = asExpressIdRef(relAttrs[4]);
+    if (relatingBuilding !== sourceWallId) continue;
+    const openingId = asExpressIdRef(relAttrs[5]);
+    if (openingId === null) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'missing opening ref');
+      continue;
+    }
+
+    // Walk the opening's placement chain to its local-X coord.
+    const openingAttrs = readAttributes(dataStore, view, editor, openingId);
+    if (!openingAttrs) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'unreadable opening');
+      continue;
+    }
+    const localPlacementId = asExpressIdRef(openingAttrs[5]); // ObjectPlacement
+    if (localPlacementId === null) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'no ObjectPlacement');
+      continue;
+    }
+    const localPlacementAttrs = readAttributes(dataStore, view, editor, localPlacementId);
+    if (!localPlacementAttrs) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'unreadable IfcLocalPlacement');
+      continue;
+    }
+    // Verify the opening's PlacementRelTo points at THIS source
+    // wall. Openings placed absolutely (PlacementRelTo === null)
+    // or relative to some other entity must be left alone —
+    // rewriting their parent placement would teleport them.
+    const placementRelTo = asExpressIdRef(localPlacementAttrs[0]);
+    if (placementRelTo !== sourceWallPlacementId) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'opening not placed relative to source wall');
+      continue;
+    }
+    const relativePlacementId = asExpressIdRef(localPlacementAttrs[1]);
+    if (relativePlacementId === null) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'no RelativePlacement');
+      continue;
+    }
+    const axisAttrs = readAttributes(dataStore, view, editor, relativePlacementId);
+    if (!axisAttrs) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'unreadable IfcAxis2Placement3D');
+      continue;
+    }
+    const cartesianId = asExpressIdRef(axisAttrs[0]);
+    if (cartesianId === null) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'no Location');
+      continue;
+    }
+    const pointAttrs = readAttributes(dataStore, view, editor, cartesianId);
+    if (!pointAttrs) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'unreadable IfcCartesianPoint');
+      continue;
+    }
+    const coords = asCoordinateTriple(pointAttrs[0]);
+    if (!coords) {
+      summary.skipped++;
+      bumpReason(summary.skipReasons, 'invalid Coordinates');
+      continue;
+    }
+
+    const localX = coords[0];
+    const onLeft = localX < splitDistance;
+    if (onLeft) {
+      // Reassign to left half. Left's placement coincides with
+      // source's, so the opening's local coords don't change.
+      editor.setPositionalAttribute(relId, 4, rewriteRelTarget(relAttrs[4], leftWallId));
+      editor.setPositionalAttribute(
+        localPlacementId,
+        0,
+        rewriteRelTarget(localPlacementAttrs[0], leftPlacementId),
+      );
+      summary.toLeft++;
+    } else {
+      // Reassign to right half. Right's placement is offset along
+      // the wall axis by `splitDistance` — so the opening's local-X
+      // shifts by `-splitDistance` to keep its world position fixed.
+      editor.setPositionalAttribute(relId, 4, rewriteRelTarget(relAttrs[4], rightWallId));
+      editor.setPositionalAttribute(
+        localPlacementId,
+        0,
+        rewriteRelTarget(localPlacementAttrs[0], rightPlacementId),
+      );
+      const newCoords: [number, number, number] = [
+        localX - splitDistance,
+        coords[1],
+        coords[2],
+      ];
+      editor.setPositionalAttribute(cartesianId, 0, newCoords);
+      summary.toRight++;
+    }
+  }
+
+  return summary;
+}

package/src/main.tsx

@@ -11,6 +11,10 @@ import ReactDOM from 'react-dom/client';
 import { App } from './App';
 import './index.css';
 import 'maplibre-gl/dist/maplibre-gl.css';
+// Wire the placement-edit helpers' parser-backed source reader. Pure
+// side-effect import; keeps `@ifc-lite/parser` out of placement-edit
+// itself so its overlay-path logic stays unit-testable.
+import './lib/placement-edit.boot';
 
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>

package/src/store/index.ts

@@ -42,6 +42,8 @@ import { createOverlaySlice, type OverlaySlice } from './slices/overlaySlice.js'
 import { createSearchSlice, type SearchSlice } from './slices/searchSlice.js';
 import { createAnnotationsSlice, type AnnotationsSlice } from './slices/annotationsSlice.js';
 import { createAddElementSlice, type AddElementSlice } from './slices/addElementSlice.js';
+import { createSplitToolSlice, type SplitToolSlice } from './slices/splitToolSlice.js';
+import { createLevelDisplaySlice, type LevelDisplaySlice } from './slices/levelDisplaySlice.js';
 import { createPointCloudSlice, type PointCloudSlice, POINT_CLOUD_DEFAULTS } from './slices/pointCloudSlice.js';
 import { invalidateVisibleBasketCache } from './basketVisibleSet.js';
 
@@ -136,6 +138,8 @@ export type ViewerState = LoadingSlice &
   SearchSlice &
   AnnotationsSlice &
   AddElementSlice &
+  SplitToolSlice &
+  LevelDisplaySlice &
   PointCloudSlice & {
     resetViewerState: () => void;
   };
@@ -173,6 +177,8 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
   ...createSearchSlice(...args),
   ...createAnnotationsSlice(...args),
   ...createAddElementSlice(...args),
+  ...createSplitToolSlice(...args),
+  ...createLevelDisplaySlice(...args),
   ...createPointCloudSlice(...args),
 
   // Reset all viewer state when loading new file
@@ -256,6 +262,7 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
 
       // UI
       activeTool: UI_DEFAULTS.ACTIVE_TOOL,
+      editEnabled: false,
       visualEnhancementsEnabled: UI_DEFAULTS.VISUAL_ENHANCEMENTS_ENABLED,
       edgeContrastEnabled: UI_DEFAULTS.EDGE_CONTRAST_ENABLED,
       edgeContrastIntensity: UI_DEFAULTS.EDGE_CONTRAST_INTENSITY,

package/src/store/slices/cesiumSlice.ts

@@ -45,6 +45,26 @@ export interface CesiumSlice {
   cesiumTerrainSource: string | null;
   /** Model ID that the Cesium overlay is currently displaying. */
   cesiumSourceModelId: string | null;
+  /**
+   * User-selected federation anchor model.
+   *
+   * When multiple georeferenced models are loaded, federation alignment rebakes
+   * every other model's geometry into this model's viewer-space frame so they
+   * land in the right relative real-world positions. The Cesium bridge also
+   * uses this model's IfcMapConversion to anchor the viewer→ECEF transform.
+   *
+   * `null` selects the default anchor (earliest `loadedAt` with a valid georef).
+   * Setting an override fires a `RECOMPUTE_FEDERATION_ALIGNMENT` re-bake.
+   */
+  anchorModelIdOverride: string | null;
+  /**
+   * When true, the viewport renders a small XYZ triad + label at each loaded
+   * model's true IFC (0,0,0) point — useful for debugging federation
+   * alignment. Origin positions are derived from each model's IfcMapConversion
+   * and the anchor's MapConversion, so the markers stay correct after re-aligns
+   * and across cross-CRS reprojections.
+   */
+  showModelBasepoints: boolean;
   /** Terrain clip Y position in viewer space. When set, fragments below this Y are discarded. */
   cesiumTerrainClipY: number | null;
   /** Whether the GLB model has been loaded into Cesium (hides WebGPU overlay). */
@@ -66,6 +86,9 @@ export interface CesiumSlice {
   setCesiumTerrainHeight: (height: number | null) => void;
   setCesiumTerrainSource: (source: string | null) => void;
   setCesiumSourceModelId: (modelId: string | null) => void;
+  setAnchorModelIdOverride: (modelId: string | null) => void;
+  setShowModelBasepoints: (show: boolean) => void;
+  toggleShowModelBasepoints: () => void;
   setCesiumTerrainClipY: (y: number | null) => void;
   setCesiumGlbLoaded: (loaded: boolean) => void;
   setCesiumPlacementEditMode: (enabled: boolean) => void;
@@ -113,7 +136,17 @@ function resolveIonToken(): string {
   return userToken || DEFAULT_ION_TOKEN;
 }
 
-export const createCesiumSlice: StateCreator<CesiumSlice, [], [], CesiumSlice> = (set) => ({
+/**
+ * Cross-slice surface CesiumSlice writes into. `editEnabled` lives on
+ * UISlice — turning on the placement editor implies global edit mode,
+ * so the slice writes it directly here to keep the toolbar pill in
+ * sync atomically.
+ */
+export interface CesiumCrossSliceState {
+  editEnabled: boolean;
+}
+
+export const createCesiumSlice: StateCreator<CesiumSlice & CesiumCrossSliceState, [], [], CesiumSlice> = (set) => ({
   cesiumAvailable: false,
   cesiumEnabled: false,
   cesiumDataSource: loadDataSource(),
@@ -122,6 +155,8 @@ export const createCesiumSlice: StateCreator<CesiumSlice, [], [], CesiumSlice> =
   cesiumTerrainHeight: null,
   cesiumTerrainSource: null,
   cesiumSourceModelId: null,
+  anchorModelIdOverride: null,
+  showModelBasepoints: false,
   cesiumTerrainClipY: null,
   cesiumGlbLoaded: false,
   cesiumPlacementEditMode: false,
@@ -172,18 +207,36 @@ export const createCesiumSlice: StateCreator<CesiumSlice, [], [], CesiumSlice> =
   setCesiumTerrainHeight: (height) => set({ cesiumTerrainHeight: height }),
   setCesiumTerrainSource: (source) => set({ cesiumTerrainSource: source }),
   setCesiumSourceModelId: (modelId) => set({ cesiumSourceModelId: modelId }),
+  setAnchorModelIdOverride: (modelId) => set({ anchorModelIdOverride: modelId }),
+  setShowModelBasepoints: (show) => set({ showModelBasepoints: show }),
+  toggleShowModelBasepoints: () => set((s) => ({ showModelBasepoints: !s.showModelBasepoints })),
   setCesiumTerrainClipY: (y) => set({ cesiumTerrainClipY: y }),
   setCesiumGlbLoaded: (loaded) => set({ cesiumGlbLoaded: loaded }),
-  setCesiumPlacementEditMode: (enabled) => set({ cesiumPlacementEditMode: enabled }),
-  toggleCesiumPlacementEditMode: () => set((s) => ({
-    cesiumPlacementEditMode: !s.cesiumPlacementEditMode,
-    ...(!s.cesiumPlacementEditMode
-      ? {}
+  setCesiumPlacementEditMode: (enabled) => set(
+    // Turning the placement editor on implies global edit mode — keeps
+    // the toolbar pill in sync so the user can't end up "moving the
+    // georef" while the rest of the UI claims it's read-only. Turning
+    // it off does *not* exit global edit; other sub-tools (properties,
+    // geometry) may still be in use — but we DO clear the placement
+    // draft so callers exiting via the setter don't leave stale draft
+    // state behind (matches the toggle's disable branch).
+    enabled
+      ? { cesiumPlacementEditMode: true, editEnabled: true }
       : {
+          cesiumPlacementEditMode: false,
           cesiumPlacementDraftModelId: null,
           cesiumPlacementDraft: null,
-        }),
-  })),
+        },
+  ),
+  toggleCesiumPlacementEditMode: () => set((s) => (
+    s.cesiumPlacementEditMode
+      ? {
+          cesiumPlacementEditMode: false,
+          cesiumPlacementDraftModelId: null,
+          cesiumPlacementDraft: null,
+        }
+      : { cesiumPlacementEditMode: true, editEnabled: true }
+  )),
   beginCesiumPlacementDraft: (modelId, conversion) => set({
     cesiumPlacementDraftModelId: modelId,
     cesiumPlacementDraft: {

package/src/store/slices/dataSlice.ts

@@ -30,6 +30,14 @@ export interface DataSlice {
   ifcDataStore: IfcDataStore | null;
   geometryResult: GeometryResult | null;
   geometryUpdateTick: number;
+  /**
+   * Monotonic counter bumped whenever existing mesh vertex/normal data has
+   * been mutated in-place (e.g. by `realignFederation`). Length/visibility
+   * triggers don't catch in-place mutation, so this is a separate signal that
+   * the merged-geometry cache and the renderer's GPU buffers both subscribe
+   * to in order to force a re-process.
+   */
+  geometryContentVersion: number;
   boundedGeometryMode: boolean;
   /** Transient overlay colors (lens/IDS/sdk overlays). */
   pendingColorUpdates: Map<number, [number, number, number, number]> | null;
@@ -41,9 +49,40 @@ export interface DataSlice {
   setGeometryResult: (result: GeometryResult | null) => void;
   setBoundedGeometryMode: (enabled: boolean) => void;
   appendGeometryBatch: (meshes: GeometryResult['meshes'], coordinateInfo?: CoordinateInfo) => void;
+  /** Signal that mesh positions/normals have been mutated in place — see
+   *  `geometryContentVersion` for why this is separate from setGeometryResult. */
+  bumpGeometryContentVersion: () => void;
   releaseGeometryMemory: () => void;
   /** Persist mesh color changes in geometryResult (used for IFC style/material updates). */
   updateMeshColors: (updates: Map<number, [number, number, number, number]>) => void;
+  /**
+   * Pending mesh removals for the renderer. Authoring actions
+   * (split, delete) push globalIds here; `useGeometryStreaming`
+   * flushes them on the next frame via
+   * `scene.removeMeshesForEntities` and then prunes the matching
+   * meshes out of `geometryResult.meshes` so picking + bounds
+   * recomputation stay consistent.
+   *
+   * Stored as a Set on the slice rather than a transient ref so
+   * tests + headless workflows can observe it directly.
+   */
+  pendingMeshRemovals: Set<number> | null;
+  setPendingMeshRemovals: (ids: Set<number>) => void;
+  clearPendingMeshRemovals: () => void;
+  /**
+   * Pending per-entity translations for the renderer. Authoring
+   * actions (translateEntity, setEntityPosition, gizmo drag) push
+   * `globalId → [dx, dy, dz]` in *renderer* frame (Y-up). The
+   * streaming hook drains via `scene.translateMeshesForEntities`
+   * on the next frame, which mutates vertex positions in place
+   * and marks the affected buckets for re-batch.
+   *
+   * The delta is renderer-frame; the IFC → renderer conversion
+   * lives in the action that produces the entry.
+   */
+  pendingMeshTranslations: Map<number, [number, number, number]> | null;
+  setPendingMeshTranslations: (updates: Map<number, [number, number, number]>) => void;
+  clearPendingMeshTranslations: () => void;
   /** Set pending color updates for the renderer without cloning mesh data.
    *  Use this for transient overlays (lens, IDS) where the source-of-truth
    *  mesh colors should remain unchanged. */
@@ -76,9 +115,12 @@ export const createDataSlice: StateCreator<DataSlice & DataCrossSliceState, [],
   ifcDataStore: null,
   geometryResult: null,
   geometryUpdateTick: 0,
+  geometryContentVersion: 0,
   boundedGeometryMode: false,
   pendingColorUpdates: null,
   pendingMeshColorUpdates: null,
+  pendingMeshRemovals: null,
+  pendingMeshTranslations: null,
 
   // Actions
   setIfcDataStore: (ifcDataStore) => set((state) => {
@@ -115,6 +157,10 @@ export const createDataSlice: StateCreator<DataSlice & DataCrossSliceState, [],
 
   setBoundedGeometryMode: (boundedGeometryMode) => set({ boundedGeometryMode }),
 
+  bumpGeometryContentVersion: () => set((state) => ({
+    geometryContentVersion: state.geometryContentVersion + 1,
+  })),
+
   appendGeometryBatch: (meshes, coordinateInfo) => set((state) => {
     // Incremental totals: O(batch_size) instead of O(total_accumulated) .reduce()
     let batchTriangles = 0;
@@ -236,6 +282,40 @@ export const createDataSlice: StateCreator<DataSlice & DataCrossSliceState, [],
 
   clearPendingMeshColorUpdates: () => set({ pendingMeshColorUpdates: null }),
 
+  setPendingMeshRemovals: (ids) => set((state) => {
+    // Accumulate across calls — the streaming loop drains in one
+    // pass per frame, but split / delete actions may fire several
+    // times between frames.
+    const merged = new Set<number>(state.pendingMeshRemovals ?? []);
+    for (const id of ids) merged.add(id);
+    return { pendingMeshRemovals: merged };
+  }),
+
+  clearPendingMeshRemovals: () => set({ pendingMeshRemovals: null }),
+
+  setPendingMeshTranslations: (updates) => set((state) => {
+    // Accumulate deltas across calls — a single drag-frame may
+    // bump translateEntity many times before the streaming hook
+    // drains. Existing entries get their delta summed; the
+    // renderer sees one combined translation per entity.
+    const merged = new Map<number, [number, number, number]>(state.pendingMeshTranslations ?? []);
+    for (const [id, delta] of updates) {
+      const existing = merged.get(id);
+      if (existing) {
+        merged.set(id, [
+          existing[0] + delta[0],
+          existing[1] + delta[1],
+          existing[2] + delta[2],
+        ]);
+      } else {
+        merged.set(id, [delta[0], delta[1], delta[2]]);
+      }
+    }
+    return { pendingMeshTranslations: merged };
+  }),
+
+  clearPendingMeshTranslations: () => set({ pendingMeshTranslations: null }),
+
   updateCoordinateInfo: (coordinateInfo) => set((state) => {
     if (!state.geometryResult) return {};
     const geometryResult = {

package/src/store/slices/levelDisplaySlice.ts

@@ -0,0 +1,105 @@
+/* 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/. */
+
+/**
+ * Level display mode — Pascal Editor's Stacked / Exploded / Solo
+ * pattern, adapted to ifc-lite's spatial hierarchy.
+ *
+ *   - Stacked   (default): every storey at its native elevation.
+ *   - Exploded            : each storey lifted along world +Y by
+ *                           `storey-index × explodedGap`, indexed
+ *                           after sorting storeys by elevation
+ *                           ascending. Index 0 stays at its
+ *                           native Y; subsequent storeys move up
+ *                           by `gap`.
+ *   - Solo                : only entities in the chosen `soloStorey`
+ *                           render. Driven by the existing
+ *                           visibilitySlice.setIsolatedEntities so
+ *                           we don't ship a second isolation
+ *                           channel.
+ *
+ * The slice owns mode + parameters only. The actual mesh
+ * translation (Exploded) and isolation (Solo) are applied by a
+ * separate hook in the viewer — `useLevelDisplayEffect` — which
+ * watches the slice and the active model's spatial hierarchy and
+ * flushes per-entity updates to the renderer via
+ * `pendingMeshTranslations` and `setIsolatedEntities`.
+ *
+ * Reversibility: the slice keeps the LAST APPLIED offset per
+ * storey so the effect can compute the delta between target and
+ * applied when the user toggles modes — no "remember the original
+ * positions" gymnastics. Switching Exploded → Stacked subtracts
+ * the applied offset; switching gap mid-Exploded shifts by the
+ * difference.
+ */
+
+import type { StateCreator } from 'zustand';
+
+export type LevelDisplayMode = 'stacked' | 'exploded' | 'solo';
+
+/** Per-model snapshot of the currently-applied storey offsets. */
+export type AppliedStoreyOffsets = Map<
+  string /* modelId */,
+  Map<number /* storey express id */, number /* applied Y offset (m, renderer frame) */>
+>;
+
+/**
+ * Solo target — must carry both modelId and expressId because
+ * express ids are scoped per model. In a federated session two
+ * different models often have storeys with overlapping ids, so a
+ * bare expressId would silently pick the wrong storey on the
+ * wrong model.
+ */
+export interface SoloStoreyRef {
+  modelId: string;
+  expressId: number;
+}
+
+export interface LevelDisplaySlice {
+  levelDisplayMode: LevelDisplayMode;
+  /** Storey for Solo. Null = effect picks the lowest storey on
+   * the active model on activation. */
+  soloStorey: SoloStoreyRef | null;
+  /** Per-storey gap in metres for Exploded. Default 4 m. */
+  explodedGap: number;
+  /**
+   * Bookkeeping — last applied Y offset per storey, per model.
+   * Read by the effect to compute deltas without re-doing the
+   * "what was the previous gap?" math; written by the effect
+   * after each successful flush. Tests can probe this directly.
+   */
+  appliedStoreyOffsets: AppliedStoreyOffsets;
+
+  setLevelDisplayMode: (mode: LevelDisplayMode) => void;
+  setSoloStorey: (ref: SoloStoreyRef | null) => void;
+  setExplodedGap: (metres: number) => void;
+  /** Effect-only: record the offsets that were just flushed to
+   * the renderer so the next toggle knows what to subtract. */
+  setAppliedStoreyOffsets: (next: AppliedStoreyOffsets) => void;
+}
+
+const LEVEL_DISPLAY_DEFAULTS = {
+  mode: 'stacked' as LevelDisplayMode,
+  gap: 4,
+  soloStorey: null as SoloStoreyRef | null,
+};
+
+export const createLevelDisplaySlice: StateCreator<LevelDisplaySlice, [], [], LevelDisplaySlice> = (set) => ({
+  levelDisplayMode: LEVEL_DISPLAY_DEFAULTS.mode,
+  soloStorey: LEVEL_DISPLAY_DEFAULTS.soloStorey,
+  explodedGap: LEVEL_DISPLAY_DEFAULTS.gap,
+  appliedStoreyOffsets: new Map(),
+
+  setLevelDisplayMode: (levelDisplayMode) => set({ levelDisplayMode }),
+  setSoloStorey: (soloStorey) => set({ soloStorey }),
+  setExplodedGap: (metres) => {
+    // Guard against non-finite / non-positive — UI lets the user
+    // type, but a 0 gap means "Exploded = Stacked" and a negative
+    // gap inverts the sort, which is rarely useful. Clamp to
+    // [0, 100] to keep behaviour sane.
+    const clamped = Math.max(0, Math.min(100, Number.isFinite(metres) ? metres : 0));
+    set({ explodedGap: clamped });
+  },
+  setAppliedStoreyOffsets: (appliedStoreyOffsets) => set({ appliedStoreyOffsets }),
+});

package/src/store/slices/modelSlice.test.ts

@@ -127,6 +127,25 @@ describe('ModelSlice', () => {
       state.addModel(model);
       assert.strictEqual(state.hasModels(), true);
     });
+
+    // Regression for issue #661.
+    it('keeps each model entry distinct when a second model is added', () => {
+      const firstStore = { tag: 'first' } as unknown as IfcDataStore;
+      const firstGeometry = { tag: 'first' } as unknown as GeometryResult;
+      const secondStore = { tag: 'second' } as unknown as IfcDataStore;
+      const secondGeometry = { tag: 'second' } as unknown as GeometryResult;
+
+      const model1 = { ...createMockModel('model-1', 'First'), ifcDataStore: firstStore, geometryResult: firstGeometry };
+      const model2 = { ...createMockModel('model-2', 'Second'), ifcDataStore: secondStore, geometryResult: secondGeometry };
+
+      state.addModel(model1);
+      state.addModel(model2);
+
+      assert.strictEqual(state.models.get('model-1')?.ifcDataStore, firstStore);
+      assert.strictEqual(state.models.get('model-1')?.geometryResult, firstGeometry);
+      assert.strictEqual(state.models.get('model-2')?.ifcDataStore, secondStore);
+      assert.strictEqual(state.models.get('model-2')?.geometryResult, secondGeometry);
+    });
   });
 
   describe('removeModel', () => {