@ifc-lite/viewer 1.19.1 → 1.21.0

package/src/lib/geo/terrain-elevation.ts

@@ -0,0 +1,166 @@
+/* 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/. */
+
+/**
+ * Terrain elevation lookup pipeline.
+ *
+ * Multiple sources are tried fast-first with diagnostic logging and a
+ * sanity range check, so callers get a usable elevation regardless of
+ * whether the user has Cesium-ion terrain, Google Photorealistic 3D
+ * Tiles, or no Cesium-side terrain at all (Open-Meteo handles that).
+ */
+
+import { queryTerrainElevation } from './reproject';
+
+// Module-level cache so bridge rebuilds (georef edits, clamp toggles)
+// re-use values within the session instead of re-hitting the network.
+const terrainElevationCache = new Map<string, number>();
+
+function terrainCacheKey(lat: number, lon: number): string {
+  // 5 decimal places ≈ 1.1m precision — plenty for site-level elevation.
+  return `${lat.toFixed(5)},${lon.toFixed(5)}`;
+}
+
+// Earth's plausible terrestrial elevation range. Mariana Trench ≈ −11 km
+// (no buildings there) and Everest summit ≈ 8.85 km. Anything outside this
+// band is depth-buffer / uninitialised garbage and must be discarded.
+const ELEV_MIN = -1000;
+const ELEV_MAX = 9000;
+
+function isPlausibleElevation(h: number): boolean {
+  return Number.isFinite(h) && h > ELEV_MIN && h < ELEV_MAX;
+}
+
+/**
+ * Clear the session terrain cache. Call when switching terrain providers,
+ * data sources, or whenever a stale cached value would be misleading.
+ */
+export function clearTerrainElevationCache(): void {
+  terrainElevationCache.clear();
+}
+
+/**
+ * Resolve terrain elevation at a WGS84 lat/lon.
+ *
+ * Order:
+ *   1. Cache (instant — re-bridge after georef edit).
+ *   2. globe.getHeight (sync, terrain provider — exact-zero treated as
+ *      "no data" since the default ellipsoid provider returns 0 for every
+ *      lat/lon).
+ *   3. scene.sampleHeight (sync, queries 3D Tiles + terrain — only works
+ *      if tiles for the location are already rendered).
+ *   4. scene.sampleHeightMostDetailed with a bounded timeout — forces tile
+ *      load and returns the height of the actually-rendered surface (what
+ *      the user SEES in Google Photorealistic 3D Tiles). Tried before
+ *      Open-Meteo because the visible-tile elevation is what models need
+ *      to sit on; Open-Meteo's DEM ignores buildings/road surfaces.
+ *   5. Open-Meteo elevation API — bare-earth fallback when tiles can't be
+ *      sampled (offline, no 3D tileset, timeout, etc.).
+ */
+const SAMPLE_DETAILED_TIMEOUT_MS = 3500;
+
+export async function resolveTerrainElevation(
+  Cesium: typeof import('cesium'),
+  viewer: InstanceType<typeof import('cesium').Viewer>,
+  lat: number,
+  lon: number,
+): Promise<number | null> {
+  const cacheKey = terrainCacheKey(lat, lon);
+  const cached = terrainElevationCache.get(cacheKey);
+  if (cached !== undefined) {
+    console.debug(`[TerrainElevation] cached at ${cacheKey}: ${cached.toFixed(2)}m`);
+    return cached;
+  }
+
+  const position = Cesium.Cartographic.fromDegrees(lon, lat);
+  const accept = (h: number, source: string, ms?: number): number => {
+    terrainElevationCache.set(cacheKey, h);
+    const t = ms !== undefined ? ` (${ms.toFixed(0)}ms)` : '';
+    console.debug(`[TerrainElevation] via ${source}: ${h.toFixed(2)}m at ${cacheKey}${t}`);
+    return h;
+  };
+  const skip = (h: unknown, source: string) => {
+    console.debug(`[TerrainElevation] ${source} returned implausible value ${h}; skipping`);
+  };
+
+  // 1. Sync globe.getHeight. The default ellipsoid provider returns 0 for
+  //    every lat/lon, so when no real terrain provider is wired we'd lock
+  //    in 0 and never reach the network fallbacks. Treat exact-zero from
+  //    this source specifically as "no data" — Open-Meteo can still return
+  //    a true 0 elsewhere in the chain for legitimate sea-level sites.
+  try {
+    const h = viewer.scene.globe.getHeight(position);
+    if (h !== undefined && isPlausibleElevation(h) && Math.abs(h) > 1e-3) {
+      return accept(h, 'globe.getHeight');
+    }
+    if (h !== undefined && !isPlausibleElevation(h)) skip(h, 'globe.getHeight');
+  } catch (err) {
+    console.warn('[TerrainElevation] globe.getHeight threw:', err);
+  }
+
+  // 2. Sync scene.sampleHeight — works with 3D Tiles when tiles for this
+  //    location are already rendered.
+  if (viewer.scene.sampleHeightSupported) {
+    try {
+      const h = viewer.scene.sampleHeight(position);
+      if (h !== undefined && isPlausibleElevation(h)) {
+        return accept(h, 'scene.sampleHeight');
+      }
+      if (h !== undefined) skip(h, 'scene.sampleHeight');
+    } catch (err) {
+      console.warn('[TerrainElevation] scene.sampleHeight threw:', err);
+    }
+  }
+
+  // 3. Force-load the 3D-Tile tile at this location and sample the
+  //    rendered surface. This is what Google Photorealistic 3D Tiles
+  //    show on screen, so the model lands on the SAME surface the user
+  //    sees — no "below the visible ground" mismatch with Open-Meteo's
+  //    DEM. Bounded by a timeout so a slow tile fetch doesn't keep the
+  //    bridge waiting forever; Open-Meteo runs after as a backstop.
+  if (viewer.scene.sampleHeightSupported) {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const t0 = performance.now();
+      const detailed = viewer.scene.sampleHeightMostDetailed([position]);
+      const timeout = new Promise<null>((resolve) => {
+        timeoutId = setTimeout(() => resolve(null), SAMPLE_DETAILED_TIMEOUT_MS);
+      });
+      const winner = await Promise.race([detailed, timeout]);
+      const ms = performance.now() - t0;
+      if (winner !== null) {
+        const r0 = winner[0] as { height?: number } | undefined;
+        if (r0?.height !== undefined && isPlausibleElevation(r0.height)) {
+          return accept(r0.height, 'scene.sampleHeightMostDetailed', ms);
+        }
+        if (r0?.height !== undefined) skip(r0.height, 'scene.sampleHeightMostDetailed');
+      } else {
+        console.debug(`[TerrainElevation] sampleHeightMostDetailed timed out after ${ms.toFixed(0)}ms`);
+      }
+    } catch (err) {
+      console.warn('[TerrainElevation] sampleHeightMostDetailed threw:', err);
+    } finally {
+      // Cancel the timeout if the detailed sample resolved first, so the
+      // timer doesn't dangle and resolve to null after we've moved on.
+      if (timeoutId !== undefined) clearTimeout(timeoutId);
+    }
+  }
+
+  // 4. Open-Meteo bare-earth elevation. Used as a network fallback when
+  //    the visible-tile sample didn't resolve in time.
+  try {
+    const t0 = performance.now();
+    const elev = await queryTerrainElevation({ lat, lon });
+    const ms = performance.now() - t0;
+    if (elev !== null && isPlausibleElevation(elev)) {
+      return accept(elev, 'Open-Meteo', ms);
+    }
+    if (elev !== null) skip(elev, 'Open-Meteo');
+  } catch (err) {
+    console.warn('[TerrainElevation] Open-Meteo threw:', err);
+  }
+
+  console.warn(`[TerrainElevation] no source returned a plausible value at ${cacheKey}`);
+  return null;
+}

package/src/lib/lens/adapter.ts

@@ -236,7 +236,7 @@ export function createLensDataProvider(
       if (info.layers?.length) return info.layers[0].materialName;
       if (info.constituents?.length) return info.constituents[0].materialName;
       if (info.profiles?.length) return info.profiles[0].materialName;
-      if (info.materials?.length) return info.materials[0];
+      if (info.materials?.length) return info.materials[0]?.name;
       return undefined;
     },
   };

package/src/lib/llm/context-builder.ts

@@ -139,7 +139,7 @@ function collectSelectedEntities(state: ReturnType<typeof useViewerStore.getStat
     const propertySets = (selectionKind === 'type' ? ownTypePropertySets : instancePropertySets).slice(0, 6);
     const typePropertySets = (selectionKind === 'type' ? [] : inheritedTypePropertySets).slice(0, 6);
     const quantitySets = (rawQsets ?? []).map((qset) => qset.name ?? qset.Name).filter((value): value is string => Boolean(value)).slice(0, 6);
-    const materialName = rawMaterial?.name ?? rawMaterial?.materials?.[0];
+    const materialName = rawMaterial?.name ?? rawMaterial?.materials?.[0]?.name;
     const classifications = rawClassifications
       .map((classification) => classification.identification ?? classification.name ?? classification.system)
       .filter((value): value is string => Boolean(value))

package/src/lib/perf/memoryAccounting.test.ts

@@ -0,0 +1,92 @@
+/* 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/strict';
+import { MemoryAccounting } from './memoryAccounting.js';
+
+describe('MemoryAccounting', () => {
+  it('tracks peak JS heap and per-phase records', () => {
+    const acc = new MemoryAccounting();
+    acc.reset();
+    acc.setSourceBytes(50 * 1024 * 1024);
+    acc.recordPhase({ phase: 'upload', jsHeapBytes: 80_000_000 });
+    acc.recordPhase({ phase: 'parser-spawn', jsHeapBytes: 90_000_000 });
+    acc.recordPhase({ phase: 'parser-complete', jsHeapBytes: 120_000_000 });
+
+    const snap = acc.snapshot();
+    assert.equal(snap.length, 3);
+    assert.equal(snap[0].phase, 'upload');
+    assert.equal(snap[2].jsHeapBytes, 120_000_000);
+
+    const summary = acc.summary();
+    assert.equal(summary.peakJsHeapBytes, 120_000_000);
+    assert.equal(summary.sourceBytes, 50 * 1024 * 1024);
+  });
+
+  it('aggregates WASM heap across multiple workers using max value per worker', () => {
+    const acc = new MemoryAccounting();
+    acc.reset();
+    acc.recordWorkerMemory('w0', 200_000_000);
+    acc.recordWorkerMemory('w1', 180_000_000);
+    acc.recordWorkerMemory('w2', 160_000_000);
+    acc.recordPhase({ phase: 'geometry-complete' });
+
+    const snap = acc.snapshot();
+    // Sum of three workers (200 + 180 + 160) = 540 MB
+    assert.equal(snap[0].wasmHeapBytes, 540_000_000);
+  });
+
+  it('accumulates geometry bytes across batches', () => {
+    const acc = new MemoryAccounting();
+    acc.reset();
+    acc.addGeometryBytes(1_000_000);
+    acc.addGeometryBytes(2_000_000);
+    acc.addGeometryBytes(500_000);
+    acc.recordPhase({ phase: 'geometry-complete' });
+    assert.equal(acc.snapshot()[0].geometryBytes, 3_500_000);
+  });
+
+  it('computes parse/geometry overlap from phase ranges', async () => {
+    const acc = new MemoryAccounting();
+    acc.reset();
+    // Two phases overlap by ~10 ms (use sleeps small enough to be reliable)
+    acc.beginPhase('parser-worker');
+    await new Promise(r => setTimeout(r, 10));
+    acc.beginPhase('geometry');
+    await new Promise(r => setTimeout(r, 20));
+    acc.endPhase('parser-worker');
+    await new Promise(r => setTimeout(r, 10));
+    acc.endPhase('geometry');
+    acc.recordPhase({ phase: 'done' });
+
+    const summary = acc.summary();
+    assert.ok(summary.parseGeometryOverlapMs > 5, `expected overlap > 5, got ${summary.parseGeometryOverlapMs}`);
+    assert.ok(summary.parseGeometryOverlapMs < 200, `expected reasonable overlap, got ${summary.parseGeometryOverlapMs}`);
+  });
+
+  it('formatSummary produces a one-line summary', () => {
+    const acc = new MemoryAccounting();
+    acc.reset();
+    acc.setSourceBytes(10 * 1024 * 1024);
+    acc.recordPhase({ phase: 'done', jsHeapBytes: 50 * 1024 * 1024, geometryBytes: 5 * 1024 * 1024 });
+    const line = acc.formatSummary();
+    assert.match(line, /mem-summary/);
+    assert.match(line, /peakJs=50\.0MB/);
+    assert.match(line, /source=10\.0MB/);
+  });
+
+  it('reset() clears all state between loads', () => {
+    const acc = new MemoryAccounting();
+    acc.reset();
+    acc.setSourceBytes(100);
+    acc.recordPhase({ phase: 'first' });
+    acc.reset();
+    acc.recordPhase({ phase: 'second' });
+    const snap = acc.snapshot();
+    assert.equal(snap.length, 1);
+    assert.equal(snap[0].phase, 'second');
+    assert.equal(acc.summary().sourceBytes, 0);
+  });
+});

package/src/lib/perf/memoryAccounting.ts

@@ -0,0 +1,235 @@
+/* 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/. */
+
+/**
+ * Per-load memory accounting for the viewer.
+ *
+ * Records JS heap, WASM heap, source-buffer, geometry, and transport bytes
+ * across the parse + geometry pipeline so we can verify the parser-worker
+ * refactor doesn't double-buffer or leak. Surfaces results via console
+ * lines (in dev or with `?perfMem=1`) and exposes a programmatic snapshot
+ * API for the timing telemetry sink.
+ *
+ * The module is intentionally a singleton (one active load at a time
+ * matches the upload-driven viewer flow). `reset()` should be called at
+ * the start of each load.
+ */
+
+export interface MemoryPhaseRecord {
+  phase: string;
+  /** Wall-clock ms since the load started. */
+  tMs: number;
+  /** `performance.memory.usedJSHeapSize` on the main thread (Chromium). */
+  jsHeapBytes?: number;
+  /** WASM heap (sum across all geometry workers + parser worker if reported). */
+  wasmHeapBytes?: number;
+  /** Total bytes of geometry buffers received so far. */
+  geometryBytes?: number;
+  /** SAB byte length (the file source). */
+  sourceBytes?: number;
+  /** Bytes that crossed the worker→main transport (typed arrays + maps). */
+  transportBytes?: number;
+}
+
+export interface MemorySummary {
+  peakJsHeapBytes: number;
+  peakWasmHeapBytes: number;
+  totalGeometryBytes: number;
+  sourceBytes: number;
+  transportBytes: number;
+  /**
+   * Fraction of total wall-clock during which both parser and geometry
+   * workers ran concurrently. Computed from phase timestamps so it
+   * surfaces the actual overlap delivered by the refactor.
+   */
+  parseGeometryOverlapMs: number;
+  totalDurationMs: number;
+}
+
+interface PhaseRange {
+  start: number;
+  end: number;
+}
+
+interface JsHeapPerf {
+  memory?: { usedJSHeapSize: number };
+}
+
+function readMainJsHeapBytes(): number | undefined {
+  if (typeof performance === 'undefined') return undefined;
+  const perf = performance as unknown as JsHeapPerf;
+  return perf.memory?.usedJSHeapSize;
+}
+
+function bytesToMB(n: number | undefined): string {
+  if (n === undefined || !Number.isFinite(n)) return '?';
+  return (n / (1024 * 1024)).toFixed(1);
+}
+
+function isLogEnabled(): boolean {
+  if (typeof globalThis === 'undefined') return false;
+  // import.meta.env.DEV is replaced at build time by Vite. The check is
+  // wrapped so non-Vite consumers (tests, SSR) don't blow up.
+  const importMeta = (globalThis as unknown as { __VITE_DEV__?: boolean }).__VITE_DEV__;
+  if (importMeta === true) return true;
+  const win = (globalThis as unknown as { location?: { search: string } }).location;
+  if (win?.search && win.search.includes('perfMem=1')) return true;
+  return false;
+}
+
+export class MemoryAccounting {
+  private records: MemoryPhaseRecord[] = [];
+  private startedAt: number | null = null;
+  /** Tracks per-worker latest WASM heap reading so the aggregator can sum. */
+  private workerWasmHeap = new Map<string, number>();
+  /** Cumulative geometry bytes across all batches in this load. */
+  private cumulativeGeometryBytes = 0;
+  /** SAB size for this load. */
+  private currentSourceBytes = 0;
+  /** Captured during phase markers. */
+  private phaseRanges = new Map<string, PhaseRange>();
+
+  /** Reset state for a new load. Call at upload start. */
+  reset(): void {
+    this.records = [];
+    this.startedAt = performance.now();
+    this.workerWasmHeap.clear();
+    this.cumulativeGeometryBytes = 0;
+    this.currentSourceBytes = 0;
+    this.phaseRanges.clear();
+  }
+
+  /** Note the file size as soon as the SAB is allocated. */
+  setSourceBytes(bytes: number): void {
+    this.currentSourceBytes = bytes;
+  }
+
+  /** Record the start time of a named phase (used for overlap calculations). */
+  beginPhase(phase: string): void {
+    if (this.startedAt === null) this.startedAt = performance.now();
+    const range = this.phaseRanges.get(phase) ?? { start: -1, end: -1 };
+    range.start = performance.now() - this.startedAt;
+    this.phaseRanges.set(phase, range);
+  }
+
+  /** Record the end time of a named phase. */
+  endPhase(phase: string): void {
+    const range = this.phaseRanges.get(phase);
+    if (!range || this.startedAt === null) return;
+    range.end = performance.now() - this.startedAt;
+  }
+
+  /** Update the cumulative WASM heap reading for a specific worker. */
+  recordWorkerMemory(workerKey: string, wasmHeapBytes: number): void {
+    if (wasmHeapBytes > 0) this.workerWasmHeap.set(workerKey, wasmHeapBytes);
+  }
+
+  /** Add bytes received in a geometry batch (positions + normals + indices). */
+  addGeometryBytes(bytes: number): void {
+    this.cumulativeGeometryBytes += bytes;
+  }
+
+  /**
+   * Record a snapshot for the named phase. Pulls main-thread JS heap and
+   * the running WASM heap sum. Optional fields override the running totals.
+   */
+  recordPhase(input: { phase: string } & Partial<Omit<MemoryPhaseRecord, 'phase' | 'tMs'>>): void {
+    if (this.startedAt === null) this.startedAt = performance.now();
+    const tMs = performance.now() - this.startedAt;
+
+    let wasmHeapBytes = 0;
+    for (const v of this.workerWasmHeap.values()) wasmHeapBytes += v;
+
+    const record: MemoryPhaseRecord = {
+      phase: input.phase,
+      tMs,
+      jsHeapBytes: input.jsHeapBytes ?? readMainJsHeapBytes(),
+      wasmHeapBytes: input.wasmHeapBytes ?? (wasmHeapBytes > 0 ? wasmHeapBytes : undefined),
+      geometryBytes: input.geometryBytes ?? (this.cumulativeGeometryBytes > 0 ? this.cumulativeGeometryBytes : undefined),
+      sourceBytes: input.sourceBytes ?? (this.currentSourceBytes > 0 ? this.currentSourceBytes : undefined),
+      transportBytes: input.transportBytes,
+    };
+    this.records.push(record);
+
+    if (isLogEnabled()) {
+      console.log(
+        `[mem] phase=${record.phase} t=${Math.round(tMs)}ms ` +
+        `jsHeap=${bytesToMB(record.jsHeapBytes)}MB ` +
+        `wasmHeap=${bytesToMB(record.wasmHeapBytes)}MB ` +
+        `geom=${bytesToMB(record.geometryBytes)}MB ` +
+        `source=${bytesToMB(record.sourceBytes)}MB ` +
+        (record.transportBytes !== undefined ? `transport=${bytesToMB(record.transportBytes)}MB ` : ''),
+      );
+    }
+  }
+
+  /** Per-phase records in insertion order. */
+  snapshot(): MemoryPhaseRecord[] {
+    return this.records.slice();
+  }
+
+  /** Roll-up across the entire load. */
+  summary(): MemorySummary {
+    let peakJsHeapBytes = 0;
+    let peakWasmHeapBytes = 0;
+    let totalGeometryBytes = 0;
+    let transportBytes = 0;
+    let sourceBytes = this.currentSourceBytes;
+
+    for (const r of this.records) {
+      if (r.jsHeapBytes && r.jsHeapBytes > peakJsHeapBytes) peakJsHeapBytes = r.jsHeapBytes;
+      if (r.wasmHeapBytes && r.wasmHeapBytes > peakWasmHeapBytes) peakWasmHeapBytes = r.wasmHeapBytes;
+      if (r.geometryBytes && r.geometryBytes > totalGeometryBytes) totalGeometryBytes = r.geometryBytes;
+      if (r.transportBytes) transportBytes += r.transportBytes;
+      if (r.sourceBytes && r.sourceBytes > sourceBytes) sourceBytes = r.sourceBytes;
+    }
+
+    const parser = this.phaseRanges.get('parser-worker');
+    const geometry = this.phaseRanges.get('geometry');
+    const overlap = computeOverlapMs(parser, geometry);
+    const totalDurationMs = this.records.length > 0
+      ? this.records[this.records.length - 1].tMs
+      : 0;
+
+    return {
+      peakJsHeapBytes,
+      peakWasmHeapBytes,
+      totalGeometryBytes,
+      sourceBytes,
+      transportBytes,
+      parseGeometryOverlapMs: overlap,
+      totalDurationMs,
+    };
+  }
+
+  /**
+   * Format a one-line summary suitable for the console / telemetry sink.
+   * Designed to be greppable next to the existing `[useIfc]` lines.
+   */
+  formatSummary(): string {
+    const s = this.summary();
+    return (
+      `[mem-summary] peakJs=${bytesToMB(s.peakJsHeapBytes)}MB ` +
+      `peakWasm=${bytesToMB(s.peakWasmHeapBytes)}MB ` +
+      `geom=${bytesToMB(s.totalGeometryBytes)}MB ` +
+      `source=${bytesToMB(s.sourceBytes)}MB ` +
+      `transport=${bytesToMB(s.transportBytes)}MB ` +
+      `overlap=${Math.round(s.parseGeometryOverlapMs)}ms ` +
+      `total=${Math.round(s.totalDurationMs)}ms`
+    );
+  }
+}
+
+function computeOverlapMs(a?: PhaseRange, b?: PhaseRange): number {
+  if (!a || !b) return 0;
+  if (a.start < 0 || b.start < 0) return 0;
+  const aEnd = a.end >= 0 ? a.end : Infinity;
+  const bEnd = b.end >= 0 ? b.end : Infinity;
+  const overlapStart = Math.max(a.start, b.start);
+  const overlapEnd = Math.min(aEnd, bEnd);
+  return Math.max(0, overlapEnd - overlapStart);
+}
+
+/** Process-wide singleton used by the upload pipeline. */
+export const memoryAccounting = new MemoryAccounting();

package/src/sdk/adapters/mutation-view.ts

@@ -100,7 +100,7 @@ export function mergeAttributeMutations(
   const mutations = mutationView.getAttributeMutationsForEntity(expressId);
   if (mutations.length === 0) return baseAttributes;
 
-  const merged = new Map<string, string>();
+  const merged = new Map<string, string | number | boolean>();
   for (const attr of baseAttributes) {
     merged.set(attr.name, attr.value);
   }

package/src/store/constants.ts

@@ -26,8 +26,17 @@ export const SECTION_PLANE_DEFAULTS = {
   AXIS: 'down' as const,
   /** Default section plane position (percentage of model bounds) */
   POSITION: 50,
-  /** Default enabled state */
-  ENABLED: true,
+  /**
+   * Default enabled state.
+   *
+   * MUST be `false`: opening the section tool (button or `x` shortcut)
+   * should leave the model uncut and arm pick mode instead — the cut
+   * appears only after the user clicks a face (or moves the slider /
+   * picks an axis). With `enabled: true` here the user saw a Down cut
+   * appear immediately on tool open even though the panel's mount
+   * effect was about to arm pick mode (issue #243 follow-up).
+   */
+  ENABLED: false,
   /** Default flipped state */
   FLIPPED: false,
   /** Default: render filled/hatched cap surfaces at the cut */
@@ -77,6 +86,27 @@ function getInitialTheme(): 'light' | 'dark' | 'colorful' {
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 }
 
+/**
+ * localStorage key for the "Merge Multilayer Walls" load-time toggle
+ * (issue #540). Reading the same key both here and on application
+ * boot keeps the user's choice sticky between sessions.
+ */
+export const MERGE_LAYERS_STORAGE_KEY = 'ifc-lite-merge-layers';
+
+/**
+ * Resolve the initial value of the merge-layers toggle from
+ * localStorage. Default `false` matches the IFC-Lite WASM default
+ * — toggling the UI without ever loading a model is a no-op.
+ */
+function getInitialMergeLayers(): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return localStorage.getItem(MERGE_LAYERS_STORAGE_KEY) === 'true';
+  } catch {
+    return false;
+  }
+}
+
 export const UI_DEFAULTS = {
   /** Default active tool */
   ACTIVE_TOOL: 'select',
@@ -104,6 +134,13 @@ export const UI_DEFAULTS = {
   SEPARATION_LINES_INTENSITY: 0.38,
   /** Separation-line radius in pixels */
   SEPARATION_LINES_RADIUS: 1.0,
+  /**
+   * Issue #540: load-time toggle that asks the WASM geometry engine
+   * to merge Revit-style multilayer walls into a single solid. Read
+   * from localStorage on boot so the user's preference survives
+   * reloads. Default `false` keeps existing per-layer rendering.
+   */
+  MERGE_LAYERS: getInitialMergeLayers(),
 } as const;
 
 // ============================================================================

package/src/store/index.ts

@@ -19,6 +19,8 @@ import { createUISlice, type UISlice } from './slices/uiSlice.js';
 import { createHoverSlice, type HoverSlice } from './slices/hoverSlice.js';
 import { createCameraSlice, type CameraSlice } from './slices/cameraSlice.js';
 import { createSectionSlice, type SectionSlice } from './slices/sectionSlice.js';
+export { customPlaneCenter, loadLastSectionMode } from './slices/sectionSlice.js';
+export type { LastSectionMode } from './slices/sectionSlice.js';
 import { createMeasurementSlice, type MeasurementSlice } from './slices/measurementSlice.js';
 import { createDataSlice, type DataSlice } from './slices/dataSlice.js';
 import { createModelSlice, type ModelSlice } from './slices/modelSlice.js';
@@ -269,7 +271,10 @@ const createViewerStore = () => create<ViewerState>()((...args) => ({
       cesiumAvailable: false,
       cesiumEnabled: false,
       cesiumTerrainHeight: null,
-      cesiumTerrainClamp: false,
+      // Default the clamp toggle ON so models authored at sea-level
+      // OrthogonalHeight don't load buried below the 3D-tiles terrain on
+      // first activation. Users can still uncheck it manually.
+      cesiumTerrainClamp: true,
       cesiumSourceModelId: null,
       cesiumTerrainClipY: null,
       cesiumGlbLoaded: false,

package/src/store/slices/cesiumSlice.ts

@@ -101,7 +101,7 @@ export const createCesiumSlice: StateCreator<CesiumSlice, [], [], CesiumSlice> =
   cesiumDataSource: loadDataSource(),
   cesiumIonToken: resolveIonToken(),
   cesiumTerrainEnabled: true,
-  cesiumTerrainClamp: false,
+  cesiumTerrainClamp: true,
   cesiumTerrainHeight: null,
   cesiumSourceModelId: null,
   cesiumTerrainClipY: null,