@ifc-lite/viewer 1.27.0 → 1.28.1

package/src/hooks/useIfcServer.ts

@@ -386,6 +386,9 @@ export function useIfcServer() {
 
           buildSpatialIndexGuarded(allMeshes, dataStore, setIfcDataStore);
         } catch (err) {
+          if (!isStale?.()) {
+            console.warn('[useIfc] Server data model fetch/decode failed; geometry shown without properties:', err);
+          }
         }
       })(); // End of async data model fetch block - runs in background, doesn't block
 

package/src/hooks/useLens.ts

@@ -56,6 +56,7 @@ export function useLens() {
       useViewerStore.getState().setLensRuleCounts(new Map());
       useViewerStore.getState().setLensRuleEntityIds(new Map());
       useViewerStore.getState().setLensAutoColorLegend([]);
+      useViewerStore.getState().setLensAppliedColors(null);
 
       // Send empty map to signal "clear overlays" to useGeometryStreaming
       useViewerStore.getState().setPendingColorUpdates(new Map());
@@ -101,7 +102,10 @@ export function useLens() {
       useViewerStore.getState().setLensAutoColorLegend([]);
     }
 
-    // Apply colors via overlay system — original batches are never modified
+    // Apply colors via overlay system — original batches are never modified.
+    // Remember the exact overlay so the compare overlay can restore it on
+    // teardown instead of blanking the channel the lens still owns.
+    useViewerStore.getState().setLensAppliedColors(colorMap.size > 0 ? colorMap : null);
     if (colorMap.size > 0) {
       useViewerStore.getState().setPendingColorUpdates(colorMap);
     }

package/src/hooks/useSymbolicAnnotations.ts

@@ -248,6 +248,11 @@ async function parseAnnotations(
   const processor = new GeometryProcessor();
   try {
     await processor.init();
+    // SymbolicRepresentationCollection and each getPolyline/getCircle/getText/
+    // getFill item are wasm-bindgen handles owning WASM memory — free them
+    // deterministically (AGENTS.md §7). Leaking them to GC lets the
+    // FinalizationRegistry free them later against an already-grown/reused
+    // shared dlmalloc heap, corrupting the allocator free-list.
     const collection = processor.parseSymbolicRepresentations(source);
     if (debugEnabled()) {
       console.log(
@@ -257,7 +262,9 @@ async function parseAnnotations(
           : 'null',
       );
     }
-    if (!collection || collection.isEmpty) return result;
+    if (!collection) return result;
+    try {
+    if (collection.isEmpty) return result;
 
     // Resolve a bucket by elevation rather than by storey id.
     //
@@ -313,34 +320,44 @@ async function parseAnnotations(
     for (let i = 0; i < collection.polylineCount; i++) {
       const poly = collection.getPolyline(i);
       if (!poly) continue;
-      if (poly.ifcType !== 'IfcAnnotation' && poly.ifcType !== 'IfcGridAxis') continue;
-      const bucket = ensureBucket(poly.expressId, poly.worldY, poly.ifcType);
-      const looseTarget = poly.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
-      const out = bucket ? bucket.lines : looseTarget;
-      polylineToSegments(poly.points, poly.pointCount, poly.isClosed, out);
+      try {
+        if (poly.ifcType !== 'IfcAnnotation' && poly.ifcType !== 'IfcGridAxis') continue;
+        const bucket = ensureBucket(poly.expressId, poly.worldY, poly.ifcType);
+        const looseTarget = poly.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
+        const out = bucket ? bucket.lines : looseTarget;
+        // poly.points is consumed synchronously here (not stored), so no copy needed.
+        polylineToSegments(poly.points, poly.pointCount, poly.isClosed, out);
+      } finally {
+        poly.free();
+      }
     }
 
     for (let i = 0; i < collection.circleCount; i++) {
       const circle = collection.getCircle(i);
       if (!circle) continue;
-      if (circle.ifcType !== 'IfcAnnotation' && circle.ifcType !== 'IfcGridAxis') continue;
-      const bucket = ensureBucket(circle.expressId, circle.worldY, circle.ifcType);
-      const looseTarget = circle.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
-      const out = bucket ? bucket.lines : looseTarget;
-      circleToSegments(
-        circle.centerX,
-        circle.centerY,
-        circle.radius,
-        circle.startAngle,
-        circle.endAngle,
-        circle.isFullCircle,
-        out,
-      );
+      try {
+        if (circle.ifcType !== 'IfcAnnotation' && circle.ifcType !== 'IfcGridAxis') continue;
+        const bucket = ensureBucket(circle.expressId, circle.worldY, circle.ifcType);
+        const looseTarget = circle.ifcType === 'IfcGridAxis' ? result.gridLoose : result.loose;
+        const out = bucket ? bucket.lines : looseTarget;
+        circleToSegments(
+          circle.centerX,
+          circle.centerY,
+          circle.radius,
+          circle.startAngle,
+          circle.endAngle,
+          circle.isFullCircle,
+          out,
+        );
+      } finally {
+        circle.free();
+      }
     }
 
     for (let i = 0; i < collection.textCount; i++) {
       const text = collection.getText(i);
       if (!text) continue;
+      try {
       if (text.ifcType !== 'IfcAnnotation' && text.ifcType !== 'IfcGridAxis') continue;
       // Skip empty literals so the renderer doesn't waste an instance slot.
       // Decode STEP escapes — `\X2\NNNN\X0\` (UTF-16 hex code units) and
@@ -398,30 +415,45 @@ async function parseAnnotations(
         };
         (bucket ? bucket.texts : looseTextTarget).push(t2d);
       }
+      } finally {
+        text.free();
+      }
     }
 
     for (let i = 0; i < collection.fillCount; i++) {
       const fill = collection.getFill(i);
       if (!fill) continue;
-      if (fill.ifcType !== 'IfcAnnotation' && fill.ifcType !== 'IfcGridAxis') continue;
-      const points = fill.points;
-      if (points.length < 6) continue; // <3 vertices = no polygon
-      const f2d: AnnotationFill2D = {
-        points,
-        holesOffsets: fill.holesOffsets,
-        color: [fill.fillR, fill.fillG, fill.fillB, fill.fillA],
-        hatching: fill.hasHatching
-          ? {
-              spacing: fill.hatchSpacing,
-              angle: fill.hatchAngle,
-              angleSecondary: Number.isNaN(fill.hatchAngleSecondary) ? null : fill.hatchAngleSecondary,
-              lineWidth: fill.hatchLineWidth,
-            }
-          : undefined,
-      };
-      const bucket = ensureBucket(fill.expressId, fill.worldY, fill.ifcType);
-      const looseFillTarget = fill.ifcType === 'IfcGridAxis' ? result.gridLooseFills : result.looseFills;
-      (bucket ? bucket.fills : looseFillTarget).push(f2d);
+      try {
+        if (fill.ifcType !== 'IfcAnnotation' && fill.ifcType !== 'IfcGridAxis') continue;
+        // fill.points / fill.holesOffsets are getter results that may be views
+        // into WASM memory; they're STORED into f2d (outlive this iteration),
+        // so copy them before the handle is freed below. Element types match
+        // the AnnotationFill2D fields (Float32Array / Uint32Array).
+        const points = new Float32Array(fill.points);
+        if (points.length < 6) continue; // <3 vertices = no polygon
+        const holesOffsets = new Uint32Array(fill.holesOffsets);
+        const f2d: AnnotationFill2D = {
+          points,
+          holesOffsets,
+          color: [fill.fillR, fill.fillG, fill.fillB, fill.fillA],
+          hatching: fill.hasHatching
+            ? {
+                spacing: fill.hatchSpacing,
+                angle: fill.hatchAngle,
+                angleSecondary: Number.isNaN(fill.hatchAngleSecondary) ? null : fill.hatchAngleSecondary,
+                lineWidth: fill.hatchLineWidth,
+              }
+            : undefined,
+        };
+        const bucket = ensureBucket(fill.expressId, fill.worldY, fill.ifcType);
+        const looseFillTarget = fill.ifcType === 'IfcGridAxis' ? result.gridLooseFills : result.looseFills;
+        (bucket ? bucket.fills : looseFillTarget).push(f2d);
+      } finally {
+        fill.free();
+      }
+    }
+    } finally {
+      collection.free();
     }
   } finally {
     processor.dispose();

package/src/lib/compare/buildFingerprints.ts

@@ -0,0 +1,173 @@
+/* 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/. */
+
+/**
+ * Viewer adapter for the `@ifc-lite/diff` engine (issue #924).
+ *
+ * Turns a loaded model — its `IfcDataStore` plus the tessellated meshes from
+ * the geometry pass — into the per-entity {@link EntityFingerprint}s the
+ * store-agnostic engine matches and classifies. This is the viewer's
+ * counterpart to the CLI adapter; the canonical data fingerprint comes from
+ * `@ifc-lite/diff`'s {@link buildDataFingerprint} (the same hash the threejs
+ * compare example pioneered) and the geometry fingerprint is the RTC-invariant
+ * WASM hash riding on each `MeshData.geometryHash`.
+ *
+ * Scope: only entities that produced at least one mesh are fingerprinted —
+ * the engine needs a geometry hash to detect geometry changes, and the
+ * compare UI colours meshed elements in 3D. Data-only edits on those meshed
+ * entities are still detected via the data hash.
+ */
+
+import {
+  buildDataFingerprint,
+  type DataFingerprintInput,
+  type EntityFingerprint,
+} from '@ifc-lite/diff';
+import { RelationshipType } from '@ifc-lite/data';
+import {
+  extractAllEntityAttributes,
+  extractPropertiesOnDemand,
+  type IfcDataStore,
+} from '@ifc-lite/parser';
+import type { MeshData } from '@ifc-lite/geometry';
+import { isGeometricDataName } from './geometricData.js';
+
+/**
+ * Adapter handle threaded through the diff onto each {@link CompareDiffEntry}.
+ * Carries everything the compare UI needs downstream without re-deriving it:
+ * `globalId` colours the entity in the federated renderer, while `modelId` +
+ * `localId` drive selection / property lookup.
+ */
+export interface CompareRef {
+  /** Federation model id this entity belongs to. */
+  modelId: string;
+  /** Original (pre-offset) express id — the key for `IfcDataStore` lookups. */
+  localId: number;
+  /** Federation global id (`localId + idOffset`) — the renderer mesh id. */
+  globalId: number;
+}
+
+export interface BuildFingerprintsModel {
+  /** Federation model id. */
+  modelId: string;
+  /** Parsed data store (local express ids). */
+  store: IfcDataStore;
+  /** Tessellated meshes. Express ids are federation-global (`local + idOffset`). */
+  meshes: readonly MeshData[];
+  /** This model's federation id offset (0 for the anchor / single-model load). */
+  idOffset: number;
+}
+
+/**
+ * Build one {@link EntityFingerprint} per meshed entity in a model.
+ *
+ * Entities are de-duplicated by express id (an entity emits several
+ * submeshes); the first mesh carrying a `geometryHash` wins (all submeshes of
+ * an entity share the whole-entity hash). The fingerprint `key` is the IFC
+ * `GlobalId` so the engine matches the same element across revisions; entities
+ * without a resolvable GlobalId fall back to a per-model synthetic key so they
+ * never collide across A/B and simply read as added/deleted.
+ */
+export async function buildEntityFingerprints(
+  model: BuildFingerprintsModel,
+): Promise<EntityFingerprint<CompareRef>[]> {
+  const { store, meshes, idOffset, modelId } = model;
+
+  // local express id → first geometry hash seen for it (may be undefined when
+  // hashing was disabled or the WASM build predates it — data diff still works)
+  const geometryByLocalId = new Map<number, bigint | undefined>();
+  for (const mesh of meshes) {
+    const localId = mesh.expressId - idOffset;
+    if (!geometryByLocalId.has(localId)) {
+      geometryByLocalId.set(localId, mesh.geometryHash);
+    } else if (geometryByLocalId.get(localId) === undefined && mesh.geometryHash !== undefined) {
+      geometryByLocalId.set(localId, mesh.geometryHash);
+    }
+  }
+
+  const fingerprints: EntityFingerprint<CompareRef>[] = [];
+  let processed = 0;
+  for (const [localId, geometryHash] of geometryByLocalId) {
+    const ifcType = store.entities.getTypeName(localId) || 'IfcProduct';
+    const globalId = store.entities.getGlobalId(localId);
+    const key = globalId || `missing:${modelId}:${localId}`;
+
+    fingerprints.push({
+      key,
+      ifcType,
+      dataHash: buildDataFingerprint(buildDataInput(store, localId, ifcType)),
+      geometryHash,
+      ref: { modelId, localId, globalId: localId + idOffset },
+    });
+
+    // Per-entity property extraction reparses from the source buffer, so on a
+    // large model this loop is heavy; yield to the main thread periodically so
+    // the viewport stays responsive and the "Comparing…" spinner keeps
+    // animating instead of the UI freezing (#924).
+    if (++processed % 1500 === 0) {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+
+  return fingerprints;
+}
+
+/** Does this side carry at least one usable geometry hash? Compares run on
+ *  models loaded outside the WASM mesh path (e.g. huge native desktop loads)
+ *  produce no hashes, which would make geometry diffs silently read every
+ *  element as unchanged — callers warn when this is false. */
+export function hasGeometryHashes(side: readonly EntityFingerprint<CompareRef>[]): boolean {
+  return side.some((fingerprint) => fingerprint.geometryHash !== undefined);
+}
+
+/**
+ * Assemble the canonical {@link DataFingerprintInput} for one entity from the
+ * store's on-demand extractors. Mirrors the extraction in
+ * `examples/threejs-viewer/src/compare.ts`; `@ifc-lite/diff` does the sorting
+ * + hashing so base and head produce byte-identical hashes for an unchanged
+ * entity.
+ */
+function buildDataInput(
+  store: IfcDataStore,
+  localId: number,
+  ifcType: string,
+): DataFingerprintInput {
+  const predefinedType = extractAllEntityAttributes(store, localId).find(
+    (attribute) => attribute.name === 'PredefinedType',
+  )?.value;
+
+  // Data vs geometry: placement/coordinate data (elevation, level offsets, …)
+  // is owned by the geometry hash, so strip it from the data fingerprint — a
+  // pure move must read as a geometry change only, never "data · geometry"
+  // (see geometricData.ts). Quantities (Volume/Area/Length/…) are
+  // geometry-derived measurements and are excluded wholesale for the same
+  // reason: a reshape already shows up as a geometry change.
+  const propertySets = extractPropertiesOnDemand(store, localId)
+    .filter((set) => !isGeometricDataName(set.name))
+    .map((set) => ({
+      name: set.name,
+      properties: set.properties
+        .filter((property) => !isGeometricDataName(property.name))
+        .map((property) => ({ name: property.name, value: property.value })),
+    }))
+    .filter((set) => set.properties.length > 0);
+
+  const typeAssignments = store.relationships
+    .getRelated(localId, RelationshipType.DefinesByType, 'inverse')
+    .map((typeId) => ({
+      globalId: store.entities.getGlobalId(typeId) || undefined,
+      name: store.entities.getName(typeId) || undefined,
+      type: store.entities.getTypeName(typeId) || undefined,
+    }));
+
+  return {
+    ifcType,
+    name: store.entities.getName(localId) || undefined,
+    description: store.entities.getDescription(localId) || undefined,
+    objectType: store.entities.getObjectType(localId) || undefined,
+    predefinedType: predefinedType != null ? String(predefinedType) : undefined,
+    propertySets,
+    typeAssignments,
+  };
+}

package/src/lib/compare/geometricData.test.ts

@@ -0,0 +1,54 @@
+/* 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 { isGeometricDataName } from './geometricData.js';
+
+describe('isGeometricDataName — data/geometry boundary', () => {
+  it('flags placement/position data that authoring tools leak into property sets', () => {
+    for (const name of [
+      'Elevation',
+      'Elevation at Bottom',
+      'Elevation at Top',
+      'Height Offset From Level',
+      'Base Offset',
+      'Top Offset',
+      'Bottom Offset',
+      'Reference Level',
+      'Z Coordinate',
+      'Z Offset',
+      'Placement',
+      'ObjectPlacement',
+    ]) {
+      assert.equal(isGeometricDataName(name), true, `${name} should be geometric`);
+    }
+  });
+
+  it('does NOT flag semantic data — a move must not strip real attributes/properties', () => {
+    for (const name of [
+      'Name',
+      'Description',
+      'ObjectType',
+      'FireRating',
+      'IsExternal',
+      'LoadBearing',
+      'Reference',
+      'Pset_SlabCommon',
+      'AcousticRating',
+      'Combustible',
+      'ThermalTransmittance',
+      'Status',
+      'Mark',
+      'Material',
+      // Generic terms that are just as often semantic — must NOT be excluded.
+      'Location',
+      'Position',
+      'Datum',
+      'Offset',
+    ]) {
+      assert.equal(isGeometricDataName(name), false, `${name} should be semantic data`);
+    }
+  });
+});

package/src/lib/compare/geometricData.ts

@@ -0,0 +1,37 @@
+/* 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/. */
+
+/**
+ * The single boundary between **data** and **geometry** for model compare
+ * (issue #924).
+ *
+ * A change to where/how an element sits in space — placement, coordinates,
+ * elevation, level offsets — is a *geometry* change, fully captured by the
+ * per-entity geometry hash (world-space mesh). It must NOT also flip the data
+ * fingerprint, or a pure move reads as "data · geometry" instead of geometry
+ * only. Authoring tools leak placement into property sets (Revit's "Elevation",
+ * "Height Offset From Level", "Base/Top Offset", level references), so we filter
+ * those out of the data side by name.
+ *
+ * Used by both `buildFingerprints` (so the data hash ignores them) and
+ * `describeChange` (so the "what changed" panel doesn't list them as data).
+ * Quantities (Volume/Area/Length/…) are excluded wholesale at the call site —
+ * they are geometry-derived measurements, not in scope here.
+ */
+
+// Deliberately narrow: only names that are *specifically* placement (elevation,
+// (object)placement, coordinate) or a qualified level/axis offset. Generic
+// `Location` / `Position` / `Datum` / bare `Offset` are NOT excluded — they are
+// just as often ordinary semantic data (a custom "Location" string, a "Position"
+// label), and wrongly dropping them from the data diff would hide real edits.
+const GEOMETRIC_NAME =
+  /elevation|placement|coordinate|reference\s*level|(height|base|top|bottom|level|z)\s*offset/i;
+
+/**
+ * True when an attribute / property / property-set name denotes geometric
+ * placement data that belongs to the geometry diff, not the data diff.
+ */
+export function isGeometricDataName(name: string): boolean {
+  return GEOMETRIC_NAME.test(name);
+}

package/src/lib/compare/overlay.test.ts

@@ -0,0 +1,99 @@
+/* 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 type { DiffEntry, DiffState, ModelDiff } from '@ifc-lite/diff';
+import { buildCompareOverlay, COMPARE_COLORS } from './overlay.js';
+import type { CompareRef } from './buildFingerprints.js';
+
+function ref(globalId: number): CompareRef {
+  // modelId/localId are irrelevant to the overlay (it keys on globalId).
+  return { modelId: 'm', localId: globalId, globalId };
+}
+
+function entry(
+  state: DiffState,
+  opts: { base?: number; head?: number; changeKinds?: ('data' | 'geometry')[] } = {},
+): DiffEntry<CompareRef> {
+  return {
+    key: `${state}:${opts.base ?? ''}:${opts.head ?? ''}`,
+    state,
+    changeKinds: opts.changeKinds ?? [],
+    base: opts.base !== undefined ? ({ key: '', ifcType: '', dataHash: '', ref: ref(opts.base) }) : undefined,
+    head: opts.head !== undefined ? ({ key: '', ifcType: '', dataHash: '', ref: ref(opts.head) }) : undefined,
+  };
+}
+
+function diffOf(entries: DiffEntry<CompareRef>[]): ModelDiff<CompareRef> {
+  // buildCompareOverlay only reads `entries`; the rest satisfies the type.
+  return { scope: 'both', entries, byKey: new Map(), counts: { added: 0, modified: 0, deleted: 0, unchanged: 0 } };
+}
+
+describe('buildCompareOverlay', () => {
+  it('colours added on the head, with nothing hidden', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(diffOf([entry('added', { head: 10 })]), false);
+    assert.deepStrictEqual(colorOverrides.get(10), COMPARE_COLORS.added);
+    assert.strictEqual(hiddenIds.size, 0);
+  });
+
+  it('colours deleted on the base (it only exists in A)', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(diffOf([entry('deleted', { base: 5 })]), false);
+    assert.deepStrictEqual(colorOverrides.get(5), COMPARE_COLORS.deleted);
+    assert.strictEqual(hiddenIds.size, 0);
+  });
+
+  it('colours modified on the head and hides the base copy', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(
+      diffOf([entry('modified', { base: 5, head: 1005, changeKinds: ['geometry'] })]),
+      false,
+    );
+    assert.deepStrictEqual(colorOverrides.get(1005), COMPARE_COLORS.modified);
+    assert.ok(!colorOverrides.has(5), 'base copy is not coloured');
+    assert.ok(hiddenIds.has(5), 'base copy is hidden to avoid double geometry');
+    assert.ok(!hiddenIds.has(1005), 'head copy stays visible');
+  });
+
+  it('hides both copies of an unchanged element when not showing unchanged', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(
+      diffOf([entry('unchanged', { base: 5, head: 1005 })]),
+      false,
+    );
+    assert.strictEqual(colorOverrides.size, 0);
+    assert.deepStrictEqual([...hiddenIds].sort((a, b) => a - b), [5, 1005]);
+  });
+
+  it('ghosts the head and hides the base for unchanged when showing unchanged', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(
+      diffOf([entry('unchanged', { base: 5, head: 1005 })]),
+      true,
+    );
+    assert.deepStrictEqual(colorOverrides.get(1005), COMPARE_COLORS.unchanged);
+    assert.ok(hiddenIds.has(5), 'base duplicate hidden');
+    assert.ok(!hiddenIds.has(1005), 'ghosted head stays visible');
+  });
+
+  it('composes a mixed diff without cross-contaminating colours/visibility', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(
+      diffOf([
+        entry('added', { head: 1001 }),
+        entry('deleted', { base: 2 }),
+        entry('modified', { base: 3, head: 1003 }),
+        entry('unchanged', { base: 4, head: 1004 }),
+      ]),
+      false,
+    );
+    assert.deepStrictEqual(colorOverrides.get(1001), COMPARE_COLORS.added);
+    assert.deepStrictEqual(colorOverrides.get(2), COMPARE_COLORS.deleted);
+    assert.deepStrictEqual(colorOverrides.get(1003), COMPARE_COLORS.modified);
+    // modified base + both unchanged copies are hidden; added/deleted are not.
+    assert.deepStrictEqual([...hiddenIds].sort((a, b) => a - b), [3, 4, 1004]);
+  });
+
+  it('skips entries that carry no usable ref', () => {
+    const { colorOverrides, hiddenIds } = buildCompareOverlay(diffOf([entry('added', {})]), false);
+    assert.strictEqual(colorOverrides.size, 0);
+    assert.strictEqual(hiddenIds.size, 0);
+  });
+});

package/src/lib/compare/overlay.ts

@@ -0,0 +1,91 @@
+/* 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 mapping from a model-diff to the renderer's colour + visibility
+ * channels (issue #924). Kept side-effect-free so it can be unit-tested in
+ * isolation; the `useCompareOverlay` hook wires the result into the store.
+ *
+ * Both models (A = base, B = head) are loaded in the federated scene at once,
+ * so an unchanged element exists twice at the same place. We therefore drive
+ * the comparison entirely from model B and suppress B-duplicated copies in
+ * model A:
+ *
+ *   - added    (B only) → green   on B
+ *   - modified (A and B) → yellow  on B, **hide** the A copy
+ *   - deleted  (A only) → red     on A
+ *   - unchanged          → ghost grey on B + hide A  (when "show unchanged"),
+ *                          otherwise hide both
+ *
+ * Colours match the threejs compare example's palette. Keys are federation
+ * **global** ids (`CompareRef.globalId`) — exactly what the renderer's
+ * `setColorOverrides` / hidden set consume.
+ */
+
+import type { ModelDiff } from '@ifc-lite/diff';
+import type { CompareRef } from './buildFingerprints';
+
+export type RGBA = [number, number, number, number];
+
+/** Diff-state colour conventions. `unchanged` is a translucent ghost. */
+export const COMPARE_COLORS = {
+  added: [0.22, 0.78, 0.44, 1] as RGBA,
+  modified: [1.0, 0.6, 0.18, 1] as RGBA,
+  deleted: [0.95, 0.3, 0.3, 1] as RGBA,
+  unchanged: [0.45, 0.52, 0.58, 0.32] as RGBA,
+} as const;
+
+export interface CompareOverlay {
+  /** Per global-id colour override fed to `scene.setColorOverrides`. */
+  colorOverrides: Map<number, RGBA>;
+  /** Global ids to hide (suppresses duplicated base-model geometry). */
+  hiddenIds: Set<number>;
+}
+
+/**
+ * Build the colour + hidden maps for a comparison.
+ *
+ * @param diff           engine output (refs carry the federation global id)
+ * @param showUnchanged  draw unchanged elements ghosted (true) or hide them
+ */
+export function buildCompareOverlay(
+  diff: ModelDiff<CompareRef>,
+  showUnchanged: boolean,
+): CompareOverlay {
+  const colorOverrides = new Map<number, RGBA>();
+  const hiddenIds = new Set<number>();
+
+  for (const entry of diff.entries) {
+    const baseGlobal = entry.base?.ref.globalId;
+    const headGlobal = entry.head?.ref.globalId;
+
+    switch (entry.state) {
+      case 'added':
+        if (headGlobal !== undefined) colorOverrides.set(headGlobal, COMPARE_COLORS.added);
+        break;
+
+      case 'deleted':
+        if (baseGlobal !== undefined) colorOverrides.set(baseGlobal, COMPARE_COLORS.deleted);
+        break;
+
+      case 'modified':
+        if (headGlobal !== undefined) colorOverrides.set(headGlobal, COMPARE_COLORS.modified);
+        // Hide the old (base) copy so the yellow head reads cleanly.
+        if (baseGlobal !== undefined) hiddenIds.add(baseGlobal);
+        break;
+
+      case 'unchanged':
+        if (showUnchanged) {
+          if (headGlobal !== undefined) colorOverrides.set(headGlobal, COMPARE_COLORS.unchanged);
+          if (baseGlobal !== undefined) hiddenIds.add(baseGlobal);
+        } else {
+          if (headGlobal !== undefined) hiddenIds.add(headGlobal);
+          if (baseGlobal !== undefined) hiddenIds.add(baseGlobal);
+        }
+        break;
+    }
+  }
+
+  return { colorOverrides, hiddenIds };
+}

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

@@ -41,7 +41,7 @@ export function shouldPreferOrthometricTerrain(
 
 export interface CesiumPlacementInput {
   coordinateInfo?: CoordinateInfo;
-  projectedCRS?: Pick<ProjectedCRS, 'verticalDatum'> | Pick<ProjectedCRS, 'mapUnitScale'> & Pick<ProjectedCRS, 'verticalDatum'>;
+  projectedCRS?: Pick<ProjectedCRS, 'verticalDatum'> | Pick<ProjectedCRS, 'mapUnitScale' | 'verticalDatum'>;
   ifcOriginHeight: number;
   terrainHeight: number | null;
   storeyElevations?: Map<number, number>;

package/src/lib/geo/reproject.ts

@@ -347,8 +347,11 @@ export async function resolveProjection(crs: ProjectedCRS): Promise<string | nul
     // 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.
+    // Only positive-cache a successful result, so a transient network
+    // failure (offline/CDN hiccup/timeout) can be retried later instead of
+    // permanently poisoning this EPSG code for the rest of the session.
     const fetched = raw ? sanitizeProj4(raw, code, null) : null;
-    projDefCache.set(code, fetched);
+    if (fetched) projDefCache.set(code, fetched);
     return fetched;
   }