@ifc-lite/viewer 1.19.0 → 1.21.0

package/src/store/slices/sectionSlice.ts

@@ -7,8 +7,37 @@
  */
 
 import type { StateCreator } from 'zustand';
-import type { SectionPlane, SectionPlaneAxis, SectionCapStyle, SectionCapHatchId } from '../types.js';
+import type { SectionPlane, SectionPlaneAxis, SectionCapStyle, SectionCapHatchId, CustomSectionPlane } from '../types.js';
 import { SECTION_PLANE_DEFAULTS, SECTION_CAP_DEFAULTS } from '../constants.js';
+import { planeBasis, nearestCardinalAxis } from '@ifc-lite/renderer';
+
+/**
+ * Project `pickedAt` onto the current cut plane and return that point as
+ * the "anchor on the live plane".
+ *
+ * The plane equation is `dot(p, normal) = distance`. As the user drags
+ * the gizmo (or moves the slider) only `distance` changes — `pickedAt`
+ * stays at the original face-pick location, which sits OFF the live
+ * plane. Any visual that needs a "point on the current plane" (cap
+ * polygon basis origin, 3D drag gizmo position, hatch UV anchor) must
+ * use the projected point instead, otherwise it freezes at the original
+ * pick location while the actual cut slides along the normal.
+ *
+ * Derivation: the projection of `pickedAt` onto the plane is
+ * `pickedAt + (distance − dot(pickedAt, normal)) · normal`, which moves
+ * `pickedAt` along the unit normal by exactly the offset required to
+ * satisfy `dot(out, normal) = distance`.
+ *
+ * Round-trip note: when `distance == dot(pickedAt, normal)` (i.e. just
+ * after a fresh face-pick) the result equals `pickedAt`, so the legacy
+ * code path that fed `pickedAt` directly is preserved at pick-time.
+ */
+export function customPlaneCenter(plane: CustomSectionPlane): [number, number, number] {
+  const { pickedAt: p, normal: n, distance: d } = plane;
+  const dotPicked = p[0] * n[0] + p[1] * n[1] + p[2] * n[2];
+  const k = d - dotPicked;
+  return [p[0] + k * n[0], p[1] + k * n[1], p[2] + k * n[2]];
+}
 
 // ─── Persistence ─────────────────────────────────────────────────────────
 // Cap appearance (hatch pattern, colours, spacing, angle, whether the cap is
@@ -21,6 +50,72 @@ const CAP_STYLE_STORAGE_KEY     = 'ifc-lite:section-cap-style';
 const CAP_SHOW_STORAGE_KEY      = 'ifc-lite:section-cap-show';
 const OUTLINES_SHOW_STORAGE_KEY = 'ifc-lite:section-outlines-show';
 
+// Last-used section mode (issue #243 follow-up). When the user reopens
+// the section tool we restore whichever mode they used last:
+//   • 'pick'     — face-pick is rearmed (default for first-time users
+//                  and anyone whose last action was a face pick).
+//   • 'cardinal' — restore the previous axis + position + flipped so the
+//                  cut appears exactly where they left it.
+// Custom (face-picked) planes are NOT persisted: they're tied to the
+// loaded model's world coordinates and would land somewhere meaningless
+// on a different model. Re-arming pick mode lets the user re-cut the
+// equivalent face on the new model with one click.
+const SECTION_MODE_STORAGE_KEY  = 'ifc-lite:section-last-mode';
+
+export type LastSectionMode =
+  | { kind: 'pick' }
+  | { kind: 'cardinal'; axis: SectionPlaneAxis; position: number; flipped: boolean };
+
+const DEFAULT_LAST_MODE: LastSectionMode = { kind: 'pick' };
+
+function isSectionPlaneAxis(v: unknown): v is SectionPlaneAxis {
+  return v === 'down' || v === 'front' || v === 'side';
+}
+
+export function loadLastSectionMode(): LastSectionMode {
+  if (typeof window === 'undefined') return DEFAULT_LAST_MODE;
+  try {
+    const raw = window.localStorage.getItem(SECTION_MODE_STORAGE_KEY);
+    if (!raw) return DEFAULT_LAST_MODE;
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    if (parsed?.kind === 'pick') return { kind: 'pick' };
+    if (
+      parsed?.kind === 'cardinal' &&
+      isSectionPlaneAxis(parsed.axis) &&
+      typeof parsed.position === 'number' && Number.isFinite(parsed.position) &&
+      typeof parsed.flipped === 'boolean'
+    ) {
+      // Clamp position to the same [0, 100] range the slice enforces so
+      // a tampered or stale value can't poison the slider on restore.
+      const position = Math.min(100, Math.max(0, parsed.position));
+      return { kind: 'cardinal', axis: parsed.axis, position, flipped: parsed.flipped };
+    }
+    return DEFAULT_LAST_MODE;
+  } catch {
+    // Corrupted JSON or storage exception — fall back to the default
+    // pick mode silently. We don't warn here because this runs on every
+    // panel mount and would spam the console for any user with bad data.
+    return DEFAULT_LAST_MODE;
+  }
+}
+
+function saveLastSectionMode(mode: LastSectionMode): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.setItem(SECTION_MODE_STORAGE_KEY, JSON.stringify(mode));
+  } catch {
+    // Quota exceeded / private mode — best effort, the preference just
+    // doesn't survive this session.
+  }
+}
+
+function clearLastSectionMode(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    window.localStorage.removeItem(SECTION_MODE_STORAGE_KEY);
+  } catch { /* best-effort */ }
+}
+
 const HATCH_IDS: readonly SectionCapHatchId[] = [
   'solid', 'diagonal', 'crossHatch', 'horizontal',
   'vertical', 'concrete', 'brick', 'insulation',
@@ -105,9 +200,43 @@ const saveShowCap      = (v: boolean) => saveBoolean(CAP_SHOW_STORAGE_KEY,
 const loadShowOutlines = () => loadBoolean(OUTLINES_SHOW_STORAGE_KEY, SECTION_PLANE_DEFAULTS.SHOW_OUTLINES);
 const saveShowOutlines = (v: boolean) => saveBoolean(OUTLINES_SHOW_STORAGE_KEY, v);
 
+/**
+ * Live "where will I cut if you click here?" preview, set by the hover
+ * dwell handler in `useMouseControls.ts` while `sectionPickMode` is on.
+ *
+ * `normal` is camera-oriented (matches the face-pick commit policy in
+ * `selectionHandlers.ts`) so the preview's arrow points in the same
+ * direction the actual cut will keep, and the user sees a visually
+ * continuous transition on click. `point` is the world-space hit
+ * location. `faceKey` is used by the hover handler to detect "still on
+ * the same face" so cursor wobble within a flat surface doesn't
+ * retrigger the dwell timer or repaint the overlay.
+ */
+export interface SectionPickPreview {
+  normal:  [number, number, number];
+  point:   [number, number, number];
+  faceKey: string;
+}
+
 export interface SectionSlice {
   // State
   sectionPlane: SectionPlane;
+  /**
+   * When true, the next click on the canvas picks a face and sets the
+   * section plane through it (world-space normal + point). Cleared after
+   * one pick, a missed click, or a tool change. See
+   * `selectionHandlers.ts` for the consumer.
+   */
+  sectionPickMode: boolean;
+  /**
+   * Hover preview for the face-pick gesture (issue #243 follow-up).
+   * Populated by the dwell handler when the cursor pauses ~200ms over a
+   * surface; consumed by `SectionVisualization.tsx` to paint a
+   * translucent violet quad + a tiny normal arrow on the hovered face.
+   * Cleared on cursor leaving the canvas, moving to a different face,
+   * disarming pick mode, or successful commit.
+   */
+  sectionPickPreview: SectionPickPreview | null;
 
   // Actions
   setSectionPlaneAxis: (axis: SectionPlaneAxis) => void;
@@ -119,6 +248,33 @@ export interface SectionSlice {
   setSectionShowOutlines: (show: boolean) => void;
   setSectionCapStyle: (style: Partial<SectionCapStyle>) => void;
   resetSectionPlane: () => void;
+  /**
+   * Set the section plane from a face pick. `normal` is the face's world-
+   * space unit normal; `point` is any point on the face (typically the
+   * raycast hit). The derived plane equation is
+   * `dot(worldPos, normal) = dot(point, normal)`.
+   *
+   * Also writes the nearest cardinal `axis` + `flipped` and a percentage-
+   * along-that-axis `position` so legacy consumers (drawings, BCF,
+   * tooltips) still see a reasonable axis-aligned approximation.
+   */
+  setSectionPlaneFromFace: (
+    normal: [number, number, number],
+    point: [number, number, number],
+    bounds?: { min: [number, number, number]; max: [number, number, number] },
+  ) => void;
+  /** Update only the custom plane's signed distance (drag gizmo / numeric input). */
+  setSectionCustomDistance: (distance: number) => void;
+  /** Arm/disarm the "next click picks a face" mode. Disarming clears any active hover preview. */
+  setSectionPickMode: (enabled: boolean) => void;
+  /**
+   * Set or clear the live face-pick hover preview. `null` hides the
+   * overlay (cursor left the canvas, moved to a new face, or the pick
+   * mode was disarmed). Only the dwell-aware hover handler should set
+   * this — it is purely a visual hint and does not change `sectionPlane`
+   * (commit happens via `setSectionPlaneFromFace` on click).
+   */
+  setSectionPickPreview: (preview: SectionPickPreview | null) => void;
 }
 
 const getDefaultCapStyle = (): SectionCapStyle => loadCapStyle();
@@ -140,23 +296,73 @@ const getDefaultSectionPlane = (): SectionPlane => ({
 export const createSectionSlice: StateCreator<SectionSlice, [], [], SectionSlice> = (set) => ({
   // Initial state
   sectionPlane: getDefaultSectionPlane(),
+  sectionPickMode: false,
+  sectionPickPreview: null,
 
   // Actions
-  setSectionPlaneAxis: (axis) => set((state) => ({
-    // Changing the axis implicitly means "I want to cut now" — enable the clip
-    // so users don't get stuck in a confusing no-op preview.
-    sectionPlane: { ...state.sectionPlane, axis, enabled: true },
-  })),
+  setSectionPlaneAxis: (axis) => set((state) => {
+    // Persist the cardinal choice so reopening the section tool restores
+    // axis + position + flipped (issue #243 follow-up). Position and
+    // flipped come from current state — picking an axis doesn't reset
+    // either, it just switches which axis the slider walks along.
+    saveLastSectionMode({
+      kind: 'cardinal',
+      axis,
+      position: state.sectionPlane.position,
+      flipped:  state.sectionPlane.flipped,
+    });
+    return {
+      // Changing the axis implicitly means "I want to cut now" — enable the clip
+      // so users don't get stuck in a confusing no-op preview. Also drop any
+      // custom (face-picked) plane so the cardinal preset takes over cleanly.
+      sectionPlane: { ...state.sectionPlane, axis, enabled: true, custom: undefined },
+    };
+  }),
 
   setSectionPlanePosition: (position) => set((state) => {
     // Clamp position to valid range [0, 100]
     const clampedPosition = Math.min(100, Math.max(0, Number(position) || 0));
-    return {
-      // Moving the slider also enables the cut — previously you had to press
-      // "Cutting" separately, which led to the "it just jitters, doesn't cut"
-      // feedback from users.
-      sectionPlane: { ...state.sectionPlane, position: clampedPosition, enabled: true },
-    };
+    // Slider semantics differ between cardinal and custom modes:
+    //   • cardinal: percentage along the axis between bounds extents.
+    //   • custom: percentage along the picked normal between the bounds-
+    //     diagonal extents centred on `pickedAt`. The renderer translates
+    //     that to a signed `distance`; the action below just stores the
+    //     percentage and updates `custom.distance` to match.
+    const next: SectionPlane = { ...state.sectionPlane, position: clampedPosition, enabled: true };
+    // Persist the cardinal slider position so the user gets the same cut
+    // back on reopen (issue #243 follow-up). Custom-mode position drives
+    // a face-anchored distance which we deliberately don't persist —
+    // those coordinates are model-relative and meaningless across files.
+    if (!state.sectionPlane.custom) {
+      saveLastSectionMode({
+        kind: 'cardinal',
+        axis:     state.sectionPlane.axis,
+        position: clampedPosition,
+        flipped:  state.sectionPlane.flipped,
+      });
+    }
+    if (state.sectionPlane.custom) {
+      const c = state.sectionPlane.custom;
+      // Re-anchor distance from percentage. The half-extent is derived
+      // from the renderer-supplied bounds when we have them — at this
+      // point in the slice we don't, so we use the existing distance as
+      // the anchor and shift it by the percentage delta. This keeps the
+      // slider responsive without the slice needing a bounds dependency.
+      // The renderer cap path uses `custom.distance` verbatim regardless,
+      // so the visual stays accurate.
+      const dPct = (clampedPosition - state.sectionPlane.position) / 100;
+      const dot = c.pickedAt[0] * c.normal[0] + c.pickedAt[1] * c.normal[1] + c.pickedAt[2] * c.normal[2];
+      // 100% of slider span = ~bounds-diagonal; without bounds, fall
+      // back to a generous fixed step (10 world units per 100%). The
+      // SectionPanel updates this with the real bounds via
+      // `setSectionCustomDistance` once they're known.
+      const fallbackSpan = 10;
+      next.custom = { ...c, distance: c.distance + dPct * fallbackSpan };
+      // Keep `pickedAt` so future deltas remain anchored to the original
+      // pick — only `distance` (and on flip, `normal`) ever change.
+      void dot;
+    }
+    return { sectionPlane: next };
   }),
 
   toggleSectionPlane: () => set((state) => ({
@@ -167,9 +373,30 @@ export const createSectionSlice: StateCreator<SectionSlice, [], [], SectionSlice
     sectionPlane: { ...state.sectionPlane, enabled },
   })),
 
-  flipSectionPlane: () => set((state) => ({
-    sectionPlane: { ...state.sectionPlane, flipped: !state.sectionPlane.flipped },
-  })),
+  flipSectionPlane: () => set((state) => {
+    // A plane is geometrically defined by `(normal, distance)`. Which
+    // half-space is kept is a separate choice expressed by `flipped`.
+    // The renderer's clip shader applies `flipped` independently
+    // (`side = flipped ? -1 : 1`, then `distToPlane * side`), so toggling
+    // the boolean alone is sufficient to swap the visible half-space —
+    // for both cardinal and custom planes. Mutating `custom.normal` /
+    // `custom.distance` here as well would double-cancel the shader's
+    // own flip (negate-and-negate-again leaves the same half-space
+    // clipped) and the flip button would have no visible effect.
+    const flipped = !state.sectionPlane.flipped;
+    // Persist the flipped state alongside axis + position for cardinal
+    // mode (issue #243 follow-up). Custom-mode flips aren't persisted
+    // because the whole custom plane (anchored at a model point) isn't.
+    if (!state.sectionPlane.custom) {
+      saveLastSectionMode({
+        kind: 'cardinal',
+        axis:     state.sectionPlane.axis,
+        position: state.sectionPlane.position,
+        flipped,
+      });
+    }
+    return { sectionPlane: { ...state.sectionPlane, flipped } };
+  }),
 
   setSectionShowCap: (showCap) => set((state) => {
     saveShowCap(showCap);
@@ -189,7 +416,9 @@ export const createSectionSlice: StateCreator<SectionSlice, [], [], SectionSlice
 
   resetSectionPlane: () => set(() => {
     // Reset clears persisted cap style too — users asking for defaults expect
-    // the defaults to stick on the next reload.
+    // the defaults to stick on the next reload. Same goes for the
+    // last-used-mode preference (issue #243 follow-up): a reset should
+    // bring everyone back to the default pick mode on next reopen.
     try {
       if (typeof window !== 'undefined') {
         window.localStorage.removeItem(CAP_STYLE_STORAGE_KEY);
@@ -199,6 +428,104 @@ export const createSectionSlice: StateCreator<SectionSlice, [], [], SectionSlice
     } catch (error) {
       console.warn('[section] failed to clear persisted cap preferences', error);
     }
-    return { sectionPlane: getDefaultSectionPlane() };
+    clearLastSectionMode();
+    return { sectionPlane: getDefaultSectionPlane(), sectionPickMode: false, sectionPickPreview: null };
+  }),
+
+  setSectionPlaneFromFace: (normal, point, bounds) => set((state) => {
+    const nx = normal[0]; const ny = normal[1]; const nz = normal[2];
+    const len = Math.hypot(nx, ny, nz);
+    if (!Number.isFinite(len) || len < 1e-6) {
+      // Degenerate normal — disarm pick mode but don't poison the
+      // renderer with NaNs. Also clear any in-flight hover preview so
+      // the violet quad doesn't linger after a bogus pick attempt.
+      console.warn('[section] face-pick received a degenerate normal; ignoring');
+      return { sectionPickMode: false, sectionPickPreview: null };
+    }
+    const unit: [number, number, number] = [nx / len, ny / len, nz / len];
+    const distance = point[0] * unit[0] + point[1] * unit[1] + point[2] * unit[2];
+    const basis = planeBasis(unit);
+    const cardinal = nearestCardinalAxis(unit);
+
+    // Re-compute `position` along the chosen cardinal so legacy axis-aligned
+    // consumers (drawings export, BCF) get a percentage that lines up with
+    // the picked plane rather than whatever slider value was set before.
+    // Without `bounds` we keep the previous value (P2 CR comment on PR
+    // #581) — the SectionPanel passes bounds when available.
+    let position = state.sectionPlane.position;
+    if (bounds) {
+      const axisIdx = cardinal.axis === 'side' ? 0 : cardinal.axis === 'down' ? 1 : 2;
+      const axisMin = bounds.min[axisIdx];
+      const axisMax = bounds.max[axisIdx];
+      const range = axisMax - axisMin;
+      if (range > 1e-6) {
+        const along = point[axisIdx];
+        position = Math.min(100, Math.max(0,
+          ((along - axisMin) / range) * 100,
+        ));
+      }
+    }
+
+    const custom: CustomSectionPlane = {
+      normal:    unit,
+      distance,
+      pickedAt:  [point[0], point[1], point[2]],
+      tangent:   basis.tangent,
+      bitangent: basis.bitangent,
+    };
+
+    // Last-used mode is "pick" — reopening the panel rearms face-pick
+    // rather than restoring a cardinal cut. We deliberately don't store
+    // the custom plane itself (model-relative coords).
+    saveLastSectionMode({ kind: 'pick' });
+
+    return {
+      sectionPlane: {
+        ...state.sectionPlane,
+        axis:    cardinal.axis,
+        flipped: cardinal.flipped,
+        position,
+        enabled: true,
+        custom,
+      },
+      sectionPickMode: false,
+      // Commit consumes the preview — the violet quad transitions
+      // visually into the actual cap on the next render. Clearing here
+      // (rather than waiting for the hover handler) avoids a frame of
+      // double-render where both preview and cap paint the same face.
+      sectionPickPreview: null,
+    };
+  }),
+
+  setSectionCustomDistance: (distance) => set((state) => {
+    if (!state.sectionPlane.custom || !Number.isFinite(distance)) {
+      return state;
+    }
+    return {
+      sectionPlane: {
+        ...state.sectionPlane,
+        custom: { ...state.sectionPlane.custom, distance },
+      },
+    };
+  }),
+
+  setSectionPickMode: (enabled) => set(() => (
+    // Disarming pick mode also drops any hovering preview overlay so
+    // it doesn't linger after the user toggles off (Esc, second toggle
+    // press, tool change). Re-arming starts fresh.
+    enabled
+      ? { sectionPickMode: true }
+      : { sectionPickMode: false, sectionPickPreview: null }
+  )),
+
+  setSectionPickPreview: (preview) => set((state) => {
+    // Setting a preview while pick mode is OFF would put the violet
+    // quad on screen with no way to commit it — guard against that so
+    // a stale hover event firing after disarm doesn't reintroduce the
+    // overlay.
+    if (preview !== null && !state.sectionPickMode) {
+      return state;
+    }
+    return { sectionPickPreview: preview };
   }),
 });

package/src/store/slices/uiSlice.merge-layers.test.ts

@@ -0,0 +1,217 @@
+/* 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, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert';
+
+// Stand-up an in-memory localStorage shim before importing the slice
+// — the constants module reads `localStorage` at import-time to seed
+// the initial `mergeLayers` value, and we want each test case to
+// control that seed deterministically.
+//
+// The shim is also what the slice's `setMergeLayers` writes back to.
+interface MutableStorage {
+  store: Record<string, string>;
+}
+
+const STORAGE_KEY = 'ifc-lite-merge-layers';
+
+function installLocalStorage(initial: Record<string, string> = {}): MutableStorage {
+  const handle: MutableStorage = { store: { ...initial } };
+  const storage = {
+    getItem: (key: string) => (key in handle.store ? handle.store[key] : null),
+    setItem: (key: string, value: string) => {
+      handle.store[key] = String(value);
+    },
+    removeItem: (key: string) => {
+      delete handle.store[key];
+    },
+    clear: () => {
+      handle.store = {};
+    },
+    key: (i: number) => Object.keys(handle.store)[i] ?? null,
+    get length() {
+      return Object.keys(handle.store).length;
+    },
+  };
+  Object.defineProperty(globalThis, 'localStorage', {
+    value: storage,
+    configurable: true,
+    writable: true,
+  });
+  // `window` is referenced by both `getInitialMergeLayers` (as a
+  // browser-environment guard) and `getInitialTheme` (which calls
+  // `matchMedia`). Both are evaluated at module-import time inside
+  // `constants.ts`, so the shim must answer both before we import the
+  // slice. A minimal `matchMedia` stub returning `{matches: false}`
+  // is enough to drive `getInitialTheme` down the light-mode branch.
+  Object.defineProperty(globalThis, 'window', {
+    value: globalThis,
+    configurable: true,
+    writable: true,
+  });
+  Object.defineProperty(globalThis, 'matchMedia', {
+    value: () => ({
+      matches: false,
+      media: '',
+      onchange: null,
+      addListener: () => {},
+      removeListener: () => {},
+      addEventListener: () => {},
+      removeEventListener: () => {},
+      dispatchEvent: () => false,
+    }),
+    configurable: true,
+    writable: true,
+  });
+  // `document` is touched by uiSlice's `applyThemeClasses` — provide
+  // a minimal `documentElement.classList.toggle` stub so the slice
+  // can be constructed without DOM globals.
+  Object.defineProperty(globalThis, 'document', {
+    value: {
+      documentElement: {
+        classList: {
+          toggle: () => {},
+          add: () => {},
+          remove: () => {},
+          contains: () => false,
+        },
+      },
+    },
+    configurable: true,
+    writable: true,
+  });
+  return handle;
+}
+
+function uninstallLocalStorage(): void {
+  Reflect.deleteProperty(globalThis as Record<string, unknown>, 'localStorage');
+  Reflect.deleteProperty(globalThis as Record<string, unknown>, 'window');
+  Reflect.deleteProperty(globalThis as Record<string, unknown>, 'matchMedia');
+  Reflect.deleteProperty(globalThis as Record<string, unknown>, 'document');
+}
+
+/**
+ * Build a fresh slice instance with whatever cross-slice fields the
+ * setter needs to read. The viewer store wires this slice on top of
+ * the federated model map + the legacy single-model `geometryResult`;
+ * we mirror the same shape so the test exercises the production
+ * branch verbatim.
+ *
+ * NOTE on module caching: Node's ESM loader caches modules by URL.
+ * `getInitialMergeLayers` (in `constants.ts`) reads localStorage at
+ * import-time, so the first test in this file determines the seed
+ * baked into `UI_DEFAULTS.MERGE_LAYERS`. We expose `initialFromUiDefaults`
+ * so the "reads from localStorage on construction" test can probe the
+ * value directly without relying on a re-import (which Node 22's ESM
+ * loader rejects with `ERR_UNKNOWN_BUILTIN_MODULE` for relative paths).
+ */
+async function buildSlice(crossSlice: { models?: Map<string, unknown>; geometryResult?: { meshes: unknown[] } | null } = {}) {
+  const mod = await import('./uiSlice.js');
+  const createUISlice = (mod as { createUISlice: (...args: unknown[]) => unknown }).createUISlice;
+  let state: Record<string, unknown> = {
+    models: crossSlice.models ?? new Map(),
+    geometryResult: crossSlice.geometryResult ?? null,
+  };
+  const setState = (partial: unknown) => {
+    if (typeof partial === 'function') {
+      const updates = (partial as (s: Record<string, unknown>) => Record<string, unknown>)(state);
+      state = { ...state, ...updates };
+    } else {
+      state = { ...state, ...(partial as Record<string, unknown>) };
+    }
+  };
+  const get = () => state;
+  state = {
+    ...state,
+    ...(createUISlice as (set: unknown, get: unknown, api: unknown) => Record<string, unknown>)(setState, get, {}),
+  };
+  return {
+    get state() {
+      return state;
+    },
+  };
+}
+
+describe('UISlice — merge-layers', () => {
+  let storage: MutableStorage | null = null;
+
+  beforeEach(() => {
+    storage = installLocalStorage();
+  });
+
+  afterEach(() => {
+    storage = null;
+    uninstallLocalStorage();
+  });
+
+  it('defaults mergeLayers to false when localStorage is empty', async () => {
+    const slice = await buildSlice();
+    assert.strictEqual(slice.state.mergeLayers, false);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, false);
+  });
+
+  it('reads the seeded value from localStorage via UI_DEFAULTS', async () => {
+    // The slice seeds `mergeLayers` from `UI_DEFAULTS.MERGE_LAYERS`,
+    // which is evaluated at module-import time. Because ESM modules
+    // load once per process, this assertion proves the slice respects
+    // whatever value `UI_DEFAULTS` carried at startup — and confirms
+    // that the slice's initial state matches the defaults table.
+    const constantsMod = await import('../constants.js');
+    const slice = await buildSlice();
+    assert.strictEqual(slice.state.mergeLayers, constantsMod.UI_DEFAULTS.MERGE_LAYERS);
+  });
+
+  it('writes mergeLayers to localStorage on setMergeLayers', async () => {
+    const slice = await buildSlice();
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(storage!.store[STORAGE_KEY], 'true');
+    (slice.state.setMergeLayers as (v: boolean) => void)(false);
+    assert.strictEqual(storage!.store[STORAGE_KEY], 'false');
+  });
+
+  it('does NOT set pendingReload when no model is loaded', async () => {
+    const slice = await buildSlice({ models: new Map(), geometryResult: null });
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(slice.state.mergeLayers, true);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, false);
+  });
+
+  it('sets pendingReload when a federated model is loaded', async () => {
+    const models = new Map();
+    models.set('m1', { id: 'm1' });
+    const slice = await buildSlice({ models });
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, true);
+  });
+
+  it('sets pendingReload when legacy geometryResult has meshes', async () => {
+    const slice = await buildSlice({ geometryResult: { meshes: [{}] } });
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, true);
+  });
+
+  it('is a no-op when the value matches the current flag', async () => {
+    const slice = await buildSlice({ geometryResult: { meshes: [{}] } });
+    // First flip: false → true, pending reload because a model is loaded
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, true);
+    // Second flip to the same value should not toggle pending again
+    // after a manual clear.
+    (slice.state.clearMergeLayersPendingReload as () => void)();
+    assert.strictEqual(slice.state.mergeLayersPendingReload, false);
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, false);
+  });
+
+  it('clearMergeLayersPendingReload flips the flag back to false', async () => {
+    const slice = await buildSlice({ geometryResult: { meshes: [{}] } });
+    (slice.state.setMergeLayers as (v: boolean) => void)(true);
+    assert.strictEqual(slice.state.mergeLayersPendingReload, true);
+    (slice.state.clearMergeLayersPendingReload as () => void)();
+    assert.strictEqual(slice.state.mergeLayersPendingReload, false);
+    // mergeLayers itself is unaffected by the dismiss.
+    assert.strictEqual(slice.state.mergeLayers, true);
+  });
+});