@ifc-lite/viewer 1.26.0 → 1.28.0

package/src/lib/slab-edit.test.ts

@@ -99,6 +99,78 @@ describe('slab-edit', () => {
     assert.deepStrictEqual(chain.footprint[2], [11, 22]);
   });
 
+  it('applies the IfcExtrudedAreaSolid.Position transform (offset + axis flip)', () => {
+    // Real authoring tools bake the slab's plan offset/rotation into the
+    // solid Position rather than the IfcLocalPlacement. Here the solid is
+    // placed at (100, 50) with RefDirection (-1,0,0) + Axis (0,0,-1) — the
+    // 180°-about-the-vertical flip seen in the BIMcollab fixture (#90).
+    const entities = makePolygonSlabFixture();
+    entities.push(
+      { expressId: 70, type: 'IFCCARTESIANPOINT', attributes: [[100, 50, 0]] },
+      { expressId: 71, type: 'IFCDIRECTION', attributes: [[0, 0, -1]] }, // Axis (Z)
+      { expressId: 72, type: 'IFCDIRECTION', attributes: [[-1, 0, 0]] }, // RefDirection (X)
+      { expressId: 73, type: 'IFCAXIS2PLACEMENT3D', attributes: [70, 71, 72] },
+    );
+    // Point the solid's Position slot (attr 1) at the new placement.
+    entities.find((e) => e.expressId === 93)!.attributes = [92, 73, null, 0.25];
+
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveSlabEditChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveSlabEditChain>[1];
+    const chain = resolveSlabEditChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    // X = (-1,0,0), Y = Z×X = (0,1,0) → solidXform(p) = (100 - p.x, 50 + p.y).
+    // Then + placement origin (10, 20).
+    //   (0,0) → (100,50) → (110,70)
+    //   (2,0) → (98,50)  → (108,70)
+    //   (1,2) → (99,52)  → (109,72)
+    assert.deepStrictEqual(chain.footprint[0], [110, 70]);
+    assert.deepStrictEqual(chain.footprint[1], [108, 70]);
+    assert.deepStrictEqual(chain.footprint[2], [109, 72]);
+  });
+
+  it('normalizes a non-unit-length Axis/RefDirection in the solid Position', () => {
+    // IfcDirection.DirectionRatios are ratios, not guaranteed unit
+    // vectors. A valid Axis=(0,0,2) must not leak its length into the
+    // Y basis (Y = Z×X) or skew the Gram-Schmidt projection — otherwise
+    // the footprint disagrees with the (normalizing) renderer. With
+    // proper normalization the result matches an identity-rotation
+    // placement: solidXform(p) = (100 + p.x, 50 + p.y).
+    const entities = makePolygonSlabFixture();
+    entities.push(
+      { expressId: 70, type: 'IFCCARTESIANPOINT', attributes: [[100, 50, 0]] },
+      { expressId: 71, type: 'IFCDIRECTION', attributes: [[0, 0, 2]] }, // non-unit Axis (Z)
+      { expressId: 72, type: 'IFCDIRECTION', attributes: [[3, 0, 0]] }, // non-unit RefDirection (X)
+      { expressId: 73, type: 'IFCAXIS2PLACEMENT3D', attributes: [70, 71, 72] },
+    );
+    entities.find((e) => e.expressId === 93)!.attributes = [92, 73, null, 0.25];
+
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveSlabEditChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveSlabEditChain>[1];
+    const chain = resolveSlabEditChain(dataStoreStub, view, editor, 100);
+    assert.ok(chain);
+    //   (0,0) → (100,50) → +placement(10,20) → (110,70)
+    //   (2,0) → (102,50) → (112,70)
+    //   (1,2) → (101,52) → (111,72)   [buggy raw-Axis would give y=74]
+    assert.deepStrictEqual(chain.footprint[0], [110, 70]);
+    assert.deepStrictEqual(chain.footprint[1], [112, 70]);
+    assert.deepStrictEqual(chain.footprint[2], [111, 72]);
+  });
+
+  it('ignores lengthUnitScale for authored (overlay) entities', () => {
+    // The in-store builders already emit metres, so a freshly-authored
+    // slab must NOT be re-scaled even on a millimetre model — otherwise
+    // re-splitting a just-cut half would shrink it 1000×. The stub serves
+    // overlay entities, so the footprint stays in its given units despite
+    // the 0.001 scale.
+    const entities = makePolygonSlabFixture();
+    const editor = new StubStoreEditor(entities) as unknown as Parameters<typeof resolveSlabEditChain>[2];
+    const view = new StubView() as unknown as Parameters<typeof resolveSlabEditChain>[1];
+    const chain = resolveSlabEditChain(dataStoreStub, view, editor, 100, 0.001);
+    assert.ok(chain);
+    assert.deepStrictEqual(chain.footprint[0], [10, 20]);
+    assert.strictEqual(chain.thickness, 0.25);
+  });
+
   it('strips the redundant closing vertex from an IfcPolyline', () => {
     const entities = makePolygonSlabFixture();
     // Append a duplicate of the first vertex to the polyline.

package/src/lib/slab-edit.ts

@@ -35,6 +35,7 @@ import type { MutablePropertyView, StoreEditor } from '@ifc-lite/mutations';
 import {
   asExpressIdRef,
   asCoordinateTriple,
+  asDirectionRatios,
   readAttributes,
   resolvePlacementChain,
 } from './placement-core.js';
@@ -61,6 +62,93 @@ function stepTypeToSlabLike(stepType: string): SlabLikeType | null {
   return SLAB_LIKE_STEP_TYPES[stepType.toUpperCase()] ?? null;
 }
 
+/**
+ * A 2D rigid transform mapping a profile-coordinate point into the
+ * solid's local plan (XY). Built from the `IfcExtrudedAreaSolid`'s
+ * `Position` (an `IfcAxis2Placement3D`), it folds in the in-place
+ * translation + rotation that real-world authoring tools bake there.
+ * In-store-built slabs carry an identity Position, so the resolver
+ * defaults to the identity transform for them.
+ */
+type Xform2D = (p: [number, number]) => [number, number];
+
+const IDENTITY_XFORM2D: Xform2D = (p) => [p[0], p[1]];
+
+function readDirection(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  id: number | null,
+): [number, number, number] | null {
+  if (id === null) return null;
+  const attrs = readAttributes(dataStore, view, editor, id);
+  return attrs ? asDirectionRatios(attrs[0]) : null;
+}
+
+/**
+ * Build the plan-space transform for an `IfcExtrudedAreaSolid.Position`.
+ * The profile lives in the placement's local XY plane; we map a profile
+ * point `(px, py)` to `origin + px·X + py·Y` and keep the XY components
+ * (the footprint is the plan). X comes from RefDirection (orthonormalised
+ * against the Axis/Z), Y = Z × X — matching the IFC placement convention,
+ * including axis flips (e.g. Axis `(0,0,-1)`, RefDirection `(-1,0,0)`).
+ * Returns identity when the placement is absent or degenerate.
+ */
+function resolveSolidPositionXform(
+  dataStore: IfcDataStore,
+  view: MutablePropertyView,
+  editor: StoreEditor,
+  placementId: number | null,
+): Xform2D {
+  if (placementId === null) return IDENTITY_XFORM2D;
+  const attrs = readAttributes(dataStore, view, editor, placementId);
+  if (!attrs) return IDENTITY_XFORM2D;
+
+  // IfcAxis2Placement3D: [0] Location · [1] Axis (Z) · [2] RefDirection (X).
+  const locId = asExpressIdRef(attrs[0]);
+  let ox = 0;
+  let oy = 0;
+  if (locId !== null) {
+    const locAttrs = readAttributes(dataStore, view, editor, locId);
+    const c = locAttrs ? asCoordinateTriple(locAttrs[0]) : null;
+    if (c) {
+      ox = c[0];
+      oy = c[1];
+    }
+  }
+
+  // IfcDirection ratios are NOT guaranteed unit length, so normalise Z
+  // before using it as a basis vector — otherwise the Gram-Schmidt
+  // projection (which assumes |Z|=1) and Y = Z × X both pick up |Z| as a
+  // stray scale factor, skewing the footprint away from the rendered mesh
+  // for files with e.g. Axis=(0,0,2). The Rust profile extractor
+  // normalises the same placement.
+  const rawZ = readDirection(dataStore, view, editor, asExpressIdRef(attrs[1])) ?? [0, 0, 1];
+  const zlen = Math.hypot(rawZ[0], rawZ[1], rawZ[2]);
+  if (zlen < 1e-9) return IDENTITY_XFORM2D;
+  const z: [number, number, number] = [rawZ[0] / zlen, rawZ[1] / zlen, rawZ[2] / zlen];
+  const refX = readDirection(dataStore, view, editor, asExpressIdRef(attrs[2])) ?? [1, 0, 0];
+
+  // Orthonormalise X against the unit Z (Gram-Schmidt), then Y = Z × X.
+  const dot = refX[0] * z[0] + refX[1] * z[1] + refX[2] * z[2];
+  let xv: [number, number, number] = [
+    refX[0] - dot * z[0],
+    refX[1] - dot * z[1],
+    refX[2] - dot * z[2],
+  ];
+  const xlen = Math.hypot(xv[0], xv[1], xv[2]);
+  if (xlen < 1e-9) return IDENTITY_XFORM2D;
+  xv = [xv[0] / xlen, xv[1] / xlen, xv[2] / xlen];
+  // Z and X are now orthonormal, so Y = Z × X is already unit length.
+  const yv: [number, number, number] = [
+    z[1] * xv[2] - z[2] * xv[1],
+    z[2] * xv[0] - z[0] * xv[2],
+    z[0] * xv[1] - z[1] * xv[0],
+  ];
+
+  return (p) => [ox + p[0] * xv[0] + p[1] * yv[0], oy + p[0] * xv[1] + p[1] * yv[1]];
+}
+
 export interface SlabEditChain {
   /** STEP type name, for the slice's dispatch. */
   elementType: SlabLikeType;
@@ -106,22 +194,23 @@ function rectangleFootprint(
   profileOrigin2D: [number, number],
   xdim: number,
   ydim: number,
+  solidXform: Xform2D,
 ): Point2D[] {
-  // The profile's local frame maps directly to storey-local XY for
-  // a slab (no in-plane rotation; the builder writes Position +
-  // null Axis + null RefDirection so the placement is axis-aligned).
+  // Rectangle corners in the profile coordinate system (centred on the
+  // profile origin), mapped through the solid Position into plan space,
+  // then offset by the slab's placement origin.
   const [px, py] = placementOrigin;
   const [cx, cy] = profileOrigin2D;
-  const xMin = px + cx - xdim / 2;
-  const xMax = px + cx + xdim / 2;
-  const yMin = py + cy - ydim / 2;
-  const yMax = py + cy + ydim / 2;
-  return [
-    [xMin, yMin],
-    [xMax, yMin],
-    [xMax, yMax],
-    [xMin, yMax],
+  const corners: Point2D[] = [
+    [cx - xdim / 2, cy - ydim / 2],
+    [cx + xdim / 2, cy - ydim / 2],
+    [cx + xdim / 2, cy + ydim / 2],
+    [cx - xdim / 2, cy + ydim / 2],
   ];
+  return corners.map((c) => {
+    const [wx, wy] = solidXform(c);
+    return [px + wx, py + wy] as Point2D;
+  });
 }
 
 /**
@@ -136,6 +225,7 @@ function polylineFootprint(
   polylineId: number,
   placementOrigin: [number, number, number],
   profileOrigin2D: [number, number],
+  solidXform: Xform2D,
 ): Point2D[] | null {
   const attrs = readAttributes(dataStore, view, editor, polylineId);
   if (!attrs) return null;
@@ -155,7 +245,10 @@ function polylineFootprint(
     // tolerantly — IFC files in the wild sometimes pad with Z=0.
     const coords = asCoordinateTriple(ptAttrs[0]);
     if (!coords) return null;
-    out.push([px + cx + coords[0], py + cy + coords[1]]);
+    // Point in profile CS → solid plan (Position translation + rotation)
+    // → slab placement origin.
+    const [wx, wy] = solidXform([cx + coords[0], cy + coords[1]]);
+    out.push([px + wx, py + wy]);
   }
   // IfcPolyline for a closed profile may or may not repeat the
   // first vertex at the end — strip if present, our clip API
@@ -170,22 +263,57 @@ function polylineFootprint(
   return out.length >= 3 ? out : null;
 }
 
+/**
+ * Scale a chain's coordinate-bearing fields (footprint, placement
+ * origin, thickness) by `scale`. Identity when `scale === 1`. Used to
+ * lift a native-unit (e.g. millimetre) STEP read into the viewer's
+ * metre working space — see `resolveSlabEditChain`'s `lengthUnitScale`.
+ */
+function scaleSlabChain(chain: SlabEditChain, scale: number): SlabEditChain {
+  if (scale === 1) return chain;
+  return {
+    ...chain,
+    placementOrigin: [
+      chain.placementOrigin[0] * scale,
+      chain.placementOrigin[1] * scale,
+      chain.placementOrigin[2] * scale,
+    ],
+    footprint: chain.footprint.map(([x, y]) => [x * scale, y * scale] as Point2D),
+    thickness: chain.thickness * scale,
+  };
+}
+
 /**
  * Resolve the slab chain (placement + footprint + extrusion). Works
  * for IfcSlab / IfcRoof / IfcPlate / IfcSpace whose representation
  * matches the in-store builder shape; null otherwise.
+ *
+ * `lengthUnitScale` is the model's native-unit → metre factor (e.g.
+ * `0.001` for a millimetre file). Raw STEP coordinate reads are in
+ * native units, but the rest of the split flow — raycast cut points,
+ * preview meshes, selection hit-tests — lives in metres, so the
+ * resolved footprint/thickness are scaled to match. Authored overlay
+ * entities are skipped: the in-store builders already emit metres, so
+ * scaling them would double-apply (re-splitting a freshly-cut half).
  */
 export function resolveSlabEditChain(
   dataStore: IfcDataStore,
   view: MutablePropertyView,
   editor: StoreEditor,
   expressId: number,
+  lengthUnitScale = 1,
 ): SlabEditChain | null {
   const rawType = readEntityType(dataStore, view, editor, expressId);
   if (!rawType) return null;
   const elementType = stepTypeToSlabLike(rawType);
   if (!elementType) return null;
 
+  // Overlay (authored) entities are stored in metres by the in-store
+  // builders; only native STEP reads need the unit scale applied.
+  // `getNewEntity` returns null (not undefined) for source entities.
+  const isAuthored = editor.getNewEntity(expressId) != null;
+  const scale = isAuthored ? 1 : lengthUnitScale;
+
   const chain = resolvePlacementChain(dataStore, view, editor, expressId);
   if (!chain) return null;
   const placementOrigin = chain.coordinates;
@@ -212,6 +340,18 @@ export function resolveSlabEditChain(
   const thicknessRaw = solidAttrs[3];
   if (profileId === null || typeof thicknessRaw !== 'number') return null;
 
+  // IfcExtrudedAreaSolid.Position (attr 1) is an IfcAxis2Placement3D that
+  // places the profile in the solid's frame — real authoring tools bake
+  // the slab's plan offset + rotation here (in-store-built slabs leave it
+  // identity). Fold it into the footprint so the preview, cut line, and
+  // resulting halves land where the rendered mesh actually is.
+  const solidXform = resolveSolidPositionXform(
+    dataStore,
+    view,
+    editor,
+    asExpressIdRef(solidAttrs[1]),
+  );
+
   // Profile dispatch — rectangle vs polygon, both produced by
   // addSlabToStore. Source-buffer slabs with mapped representations,
   // I-shape profiles, etc. land in `null` here and the slice
@@ -244,29 +384,29 @@ export function resolveSlabEditChain(
     const xdim = profileAttrs[3];
     const ydim = profileAttrs[4];
     if (typeof xdim !== 'number' || typeof ydim !== 'number') return null;
-    return {
+    return scaleSlabChain({
       elementType,
       placementOrigin,
-      footprint: rectangleFootprint(placementOrigin, profileOrigin2D, xdim, ydim),
+      footprint: rectangleFootprint(placementOrigin, profileOrigin2D, xdim, ydim, solidXform),
       extrudedSolidId: solidId,
       thickness: thicknessRaw,
       profileKind: 'rectangle',
-    };
+    }, scale);
   }
   if (profileType && profileType.toUpperCase() === 'IFCARBITRARYCLOSEDPROFILEDEF') {
     // OuterCurve at attr 2.
     const polylineId = asExpressIdRef(profileAttrs[2]);
     if (polylineId === null) return null;
-    const fp = polylineFootprint(dataStore, view, editor, polylineId, placementOrigin, profileOrigin2D);
+    const fp = polylineFootprint(dataStore, view, editor, polylineId, placementOrigin, profileOrigin2D, solidXform);
     if (!fp) return null;
-    return {
+    return scaleSlabChain({
       elementType,
       placementOrigin,
       footprint: fp,
       extrudedSolidId: solidId,
       thickness: thicknessRaw,
       profileKind: 'polygon',
-    };
+    }, scale);
   }
   return null;
 }

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

@@ -108,7 +108,12 @@ export function resolveVisibilityFilterSets(
  * double-quotes, or newlines.
  */
 function escapeCsv(value: string, sep: string): string {
-  if (value.includes(sep) || value.includes('"') || value.includes('\n')) {
+  // Neutralize spreadsheet formula injection (CWE-1236): a leading
+  // =, +, -, @, TAB or CR makes a cell execute as a formula in Excel/
+  // LibreOffice/Sheets. IFC values are attacker-controllable, so prefix
+  // such cells with an apostrophe.
+  if (/^[=+\-@\t\r]/.test(value)) value = `'${value}`;
+  if (value.includes(sep) || value.includes('"') || value.includes('\n') || value.includes('\r')) {
     return `"${value.replace(/"/g, '""')}"`;
   }
   return value;
@@ -153,13 +158,13 @@ export function createExportAdapter(store: StoreApi): ExportBackendMethods {
     if (!model?.ifcDataStore) return [];
 
     const node = new EntityNode(model.ifcDataStore, ref.expressId);
-    return node.properties().map((pset: { name: string; globalId?: string; properties: Array<{ name: string; type: number; value: string | number | boolean | null }> }) => ({
+    return node.properties().map((pset) => ({
       name: pset.name,
       globalId: pset.globalId,
-      properties: pset.properties.map((p: { name: string; type: number; value: string | number | boolean | null }) => ({
+      properties: pset.properties.map((p) => ({
         name: p.name,
         type: p.type,
-        value: p.value,
+        value: p.value as string | number | boolean | null,
       })),
     }));
   }

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

@@ -136,13 +136,13 @@ export function createQueryAdapter(store: StoreApi): QueryBackendMethods {
     if (!model?.ifcDataStore) return [];
 
     const node = new EntityNode(model.ifcDataStore, ref.expressId);
-    return node.properties().map((pset: { name: string; globalId?: string; properties: Array<{ name: string; type: number; value: string | number | boolean | null }> }) => ({
+    return node.properties().map((pset) => ({
       name: pset.name,
       globalId: pset.globalId,
-      properties: pset.properties.map((p: { name: string; type: number; value: string | number | boolean | null }) => ({
+      properties: pset.properties.map((p) => ({
         name: p.name,
         type: p.type,
-        value: p.value,
+        value: p.value as string | number | boolean | null,
       })),
     }));
   }

package/src/store/globalId.ts

@@ -44,23 +44,17 @@ 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,
-    };
+  // No models loaded — legacy single-store fallback (expressId === globalId).
+  if (models.size === 0) {
+    return { modelId: 'legacy', expressId: globalId };
   }
 
+  // Resolve through every model by its offset range, regardless of count.
+  // For a true single model with idOffset 0 this still yields expressId === globalId.
+  // The `>= 0` boundary matches the canonical resolveGlobalIdFromModels (modelSlice.ts).
   for (const [modelId, model] of models.entries()) {
     const localExpressId = globalId - model.idOffset;
-    if (localExpressId > 0 && localExpressId <= model.maxExpressId) {
+    if (localExpressId >= 0 && localExpressId <= model.maxExpressId) {
       return {
         modelId,
         expressId: localExpressId,
@@ -68,6 +62,14 @@ export function fromGlobalIdFromModels(
     }
   }
 
+  // Single-model graceful fallback: if exactly one model and the offset
+  // range check missed (e.g. overlay-allocated id above maxExpressId),
+  // still return that model with the offset-corrected id rather than undefined.
+  if (models.size === 1) {
+    const [modelId, model] = models.entries().next().value!;
+    return { modelId, expressId: globalId - model.idOffset };
+  }
+
   return undefined;
 }
 

package/src/store/index.ts

@@ -34,6 +34,7 @@ import { createListSlice, type ListSlice } from './slices/listSlice.js';
 import { createPinboardSlice, type PinboardSlice } from './slices/pinboardSlice.js';
 import { createLensSlice, type LensSlice } from './slices/lensSlice.js';
 import { createClashSlice, type ClashSlice } from './slices/clashSlice.js';
+import { createCompareSlice, type CompareSlice } from './slices/compareSlice.js';
 import { createScriptSlice, type ScriptSlice } from './slices/scriptSlice.js';
 import { createChatSlice, type ChatSlice } from './slices/chatSlice.js';
 import { createCesiumSlice, type CesiumSlice } from './slices/cesiumSlice.js';
@@ -85,6 +86,7 @@ export type { PinboardSlice } from './slices/pinboardSlice.js';
 
 // Re-export Lens types
 export type { LensSlice, Lens, LensRule, LensCriteria } from './slices/lensSlice.js';
+export type { CompareSlice, CompareResult } from './slices/compareSlice.js';
 
 // Re-export Script types
 export type { ScriptSlice } from './slices/scriptSlice.js';
@@ -131,6 +133,7 @@ export type ViewerState = LoadingSlice &
   PinboardSlice &
   LensSlice &
   ClashSlice &
+  CompareSlice &
   ScriptSlice &
   ChatSlice &
   CesiumSlice &
@@ -155,7 +158,7 @@ export type ViewerState = LoadingSlice &
      * the right panel. Routed through by the toolbar, command palette, and the
      * BCF overlay so every entry point behaves identically.
      */
-    openWorkspacePanel: (panel: 'bcf' | 'ids' | 'lens' | 'clash' | 'extensions') => void;
+    openWorkspacePanel: (panel: 'bcf' | 'ids' | 'lens' | 'clash' | 'compare' | 'extensions') => void;
   };
 
 /**
@@ -182,6 +185,7 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
   ...createPinboardSlice(...args),
   ...createLensSlice(...args),
   ...createClashSlice(...args),
+  ...createCompareSlice(...args),
   ...createScriptSlice(...args),
   ...createChatSlice(...args),
   ...createCesiumSlice(...args),
@@ -211,6 +215,8 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
       // Selection (multi-model)
       selectedEntity: null,
       selectedEntitiesSet: new Set(),
+      selectedEntities: [],
+      selectedModelId: null,
 
       // Visibility (legacy)
       hiddenEntities: new Set(),
@@ -235,6 +241,14 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
       pendingColorUpdates: null,
       pendingMeshColorUpdates: null,
 
+      // Compare (#924): drop any stale diff result — it references models by
+      // id and the loaded set is changing. Keep panel visibility + A/B/scope
+      // choices (UI prefs); the user re-runs against the new set.
+      compareResult: null,
+      compareSelectedKey: null,
+      compareRunning: false,
+      compareError: null,
+
       // Hover/Context
       hoverState: { entityId: null, screenX: 0, screenY: 0 },
       contextMenu: { isOpen: false, entityId: null, screenX: 0, screenY: 0 },
@@ -460,6 +474,7 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
       idsPanelVisible: panel === 'ids',
       lensPanelVisible: panel === 'lens',
       clashPanelVisible: panel === 'clash',
+      comparePanelVisible: panel === 'compare',
       extensionsPanelVisible: panel === 'extensions',
       rightPanelCollapsed: false,
     });

package/src/store/slices/cesiumSlice.ts

@@ -108,8 +108,15 @@ const STORAGE_KEY_DATA_SOURCE = 'ifc-lite:cesium-data-source';
  * Default Cesium ion token provided at build time.
  * Set via VITE_CESIUM_ION_TOKEN in .env or CI environment.
  * This means users never need to configure a token manually.
+ *
+ * NOTE: `import.meta.env` is undefined under the Vitest/Node test runner (the
+ * Vite define plugin doesn't run there), so this module-top-level read would
+ * crash with "Cannot read properties of undefined" — every viewer test imports
+ * the store, which imports this slice. The optional chaining on `.env` keeps the
+ * read safe in that environment. `import.meta.env` is typed via vite-env.d.ts so
+ * no `as any` cast is needed. Do NOT drop the optional chaining.
  */
-const DEFAULT_ION_TOKEN: string = (import.meta as any).env?.VITE_CESIUM_ION_TOKEN ?? '';
+const DEFAULT_ION_TOKEN: string = import.meta.env?.VITE_CESIUM_ION_TOKEN ?? '';
 
 function loadFromStorage(key: string, fallback: string): string {
   try {

package/src/store/slices/compareSlice.ts

@@ -0,0 +1,96 @@
+/* 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/. */
+
+/**
+ * Model-comparison panel state (issue #924). Holds the panel's UI state, the
+ * A/B model selection, the data-vs-geometry scope, and the last `@ifc-lite/diff`
+ * result. The orchestration (building per-entity fingerprints from each model's
+ * `IfcDataStore` + geometry hashes, running `diffModels`, applying the 3D
+ * colour/visibility overlay) lives in the `useCompare` hook — this slice is
+ * deliberately dumb, mirroring `clashSlice` + `useClash`.
+ */
+
+import type { StateCreator } from 'zustand';
+import type { DiffScope, ModelDiff } from '@ifc-lite/diff';
+import type { CompareRef } from '@/lib/compare/buildFingerprints';
+
+/** A completed comparison: the engine result plus the A/B context it ran on. */
+export interface CompareResult {
+  /** Federation model id chosen as the base (version A). */
+  baseModelId: string;
+  /** Federation model id chosen as the head (version B). */
+  headModelId: string;
+  /** Display name of the base model. */
+  baseName: string;
+  /** Display name of the head model. */
+  headName: string;
+  /** The scope the diff was computed with. */
+  scope: DiffScope;
+  /** True when a compared model carries no geometry hashes (loaded outside the
+   *  WASM mesh path), so geometry-scope changes can't be detected. */
+  geometryUnavailable: boolean;
+  /** The engine output — entries keyed by GlobalId, with per-entity refs. */
+  diff: ModelDiff<CompareRef>;
+}
+
+export interface CompareSlice {
+  comparePanelVisible: boolean;
+  /** Selected base (A) / head (B) federation model ids. */
+  compareBaseModelId: string | null;
+  compareHeadModelId: string | null;
+  /** What counts as a change: data, geometry, or both. */
+  compareScope: DiffScope;
+  /** Whether unchanged elements are drawn (ghosted) or hidden. */
+  compareShowUnchanged: boolean;
+  /** Last comparison result (null when idle / not yet run). */
+  compareResult: CompareResult | null;
+  compareRunning: boolean;
+  compareError: string | null;
+  /** GlobalId of the entry focused in the list (for highlight). */
+  compareSelectedKey: string | null;
+
+  setComparePanelVisible: (visible: boolean) => void;
+  toggleComparePanel: () => void;
+  setCompareBaseModelId: (id: string | null) => void;
+  setCompareHeadModelId: (id: string | null) => void;
+  setCompareScope: (scope: DiffScope) => void;
+  setCompareShowUnchanged: (show: boolean) => void;
+  setCompareResult: (result: CompareResult | null) => void;
+  setCompareRunning: (running: boolean) => void;
+  setCompareError: (error: string | null) => void;
+  setCompareSelectedKey: (key: string | null) => void;
+  /** Clear the run result + selection; keeps the A/B + scope choices. */
+  clearCompare: () => void;
+}
+
+export const createCompareSlice: StateCreator<CompareSlice, [], [], CompareSlice> = (set) => ({
+  comparePanelVisible: false,
+  compareBaseModelId: null,
+  compareHeadModelId: null,
+  compareScope: 'both',
+  compareShowUnchanged: false,
+  compareResult: null,
+  compareRunning: false,
+  compareError: null,
+  compareSelectedKey: null,
+
+  setComparePanelVisible: (comparePanelVisible) => set({ comparePanelVisible }),
+  toggleComparePanel: () => set((s) => ({ comparePanelVisible: !s.comparePanelVisible })),
+  setCompareBaseModelId: (compareBaseModelId) => set({ compareBaseModelId }),
+  setCompareHeadModelId: (compareHeadModelId) => set({ compareHeadModelId }),
+  setCompareScope: (compareScope) => set({ compareScope }),
+  setCompareShowUnchanged: (compareShowUnchanged) => set({ compareShowUnchanged }),
+  setCompareResult: (compareResult) => set({ compareResult }),
+  setCompareRunning: (compareRunning) => set({ compareRunning }),
+  setCompareError: (compareError) => set({ compareError }),
+  setCompareSelectedKey: (compareSelectedKey) => set({ compareSelectedKey }),
+
+  clearCompare: () =>
+    set({
+      compareResult: null,
+      compareRunning: false,
+      compareError: null,
+      compareSelectedKey: null,
+    }),
+});

package/src/store/slices/lensSlice.ts

@@ -98,6 +98,11 @@ export interface LensSlice {
   lensPanelVisible: boolean;
   /** Computed: globalId → hex color for entities matched by active lens */
   lensColorMap: Map<number, string>;
+  /** The exact RGBA overlay the active lens last pushed to the shared color
+   *  channel, or null when no lens is active. Lets another channel owner
+   *  (e.g. the compare overlay) hand control back to the lens on teardown
+   *  instead of clearing it. */
+  lensAppliedColors: Map<number, [number, number, number, number]> | null;
   /** Computed: globalIds to hide via lens rules */
   lensHiddenIds: Set<number>;
   /** Computed: ruleId → matched entity count for the active lens */
@@ -117,6 +122,7 @@ export interface LensSlice {
   toggleLensPanel: () => void;
   setLensPanelVisible: (visible: boolean) => void;
   setLensColorMap: (map: Map<number, string>) => void;
+  setLensAppliedColors: (map: Map<number, [number, number, number, number]> | null) => void;
   setLensHiddenIds: (ids: Set<number>) => void;
   setLensRuleCounts: (counts: Map<string, number>) => void;
   setLensRuleEntityIds: (ids: Map<string, number[]>) => void;
@@ -147,6 +153,7 @@ export const createLensSlice: StateCreator<LensSlice, [], [], LensSlice> = (set,
   activeLensId: null,
   lensPanelVisible: false,
   lensColorMap: new Map(),
+  lensAppliedColors: null,
   lensHiddenIds: new Set(),
   lensRuleCounts: new Map(),
   lensRuleEntityIds: new Map(),
@@ -183,6 +190,7 @@ export const createLensSlice: StateCreator<LensSlice, [], [], LensSlice> = (set,
   setLensPanelVisible: (lensPanelVisible) => set({ lensPanelVisible }),
 
   setLensColorMap: (lensColorMap) => set({ lensColorMap }),
+  setLensAppliedColors: (lensAppliedColors) => set({ lensAppliedColors }),
   setLensHiddenIds: (lensHiddenIds) => set({ lensHiddenIds }),
   setLensRuleCounts: (lensRuleCounts) => set({ lensRuleCounts }),
   setLensRuleEntityIds: (lensRuleEntityIds) => set({ lensRuleEntityIds }),