@ifc-lite/viewer 1.7.0 → 1.9.0

package/src/sdk/useBimHost.ts

@@ -0,0 +1,69 @@
+/* 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/. */
+
+/**
+ * useBimHost — React hook that initializes the SDK and BimHost.
+ *
+ * This hook:
+ * 1. Creates a LocalBackend backed by the Zustand store
+ * 2. Creates a BimContext (the `bim` object)
+ * 3. Starts a BimHost listening on BroadcastChannel 'ifc-lite'
+ * 4. External tools (ifc-scripts, ifc-flow) can connect to control the viewer
+ *
+ * Usage:
+ *   function App() {
+ *     const bim = useBimHost();
+ *     // bim is available for internal use
+ *     // External tools can connect via BroadcastChannel 'ifc-lite'
+ *   }
+ */
+
+import { useRef, useEffect, useMemo } from 'react';
+import { createBimContext, BimHost, type BimContext } from '@ifc-lite/sdk';
+import { useViewerStore } from '../store/index.js';
+import { LocalBackend } from './local-backend.js';
+
+const BROADCAST_CHANNEL = 'ifc-lite';
+
+/**
+ * Initialize the SDK with a local backend and start the BimHost.
+ * Returns the BimContext for internal use.
+ */
+export function useBimHost(): BimContext {
+  const hostRef = useRef<BimHost | null>(null);
+  const backendRef = useRef<LocalBackend | null>(null);
+
+  // Create local backend and BimContext once — single shared backend
+  const bim = useMemo(() => {
+    const storeApi = {
+      getState: useViewerStore.getState,
+      subscribe: useViewerStore.subscribe,
+    };
+    const backend = new LocalBackend(storeApi);
+    backendRef.current = backend;
+    return createBimContext({ backend });
+  }, []);
+
+  // Start BimHost for external connections — reuse the same backend
+  useEffect(() => {
+    const backend = backendRef.current;
+    if (!backend) return;
+    const host = new BimHost(backend);
+
+    try {
+      host.listenBroadcast(BROADCAST_CHANNEL);
+    } catch {
+      // BroadcastChannel not available (e.g., in some test environments)
+    }
+
+    hostRef.current = host;
+
+    return () => {
+      host.close();
+      hostRef.current = null;
+    };
+  }, []);
+
+  return bim;
+}

package/src/store/constants.ts

@@ -51,11 +51,19 @@ export const EDGE_LOCK_DEFAULTS = {
 // UI Defaults
 // ============================================================================
 
+/** Resolve the initial theme: localStorage override > system preference > dark fallback */
+function getInitialTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'dark';
+  const saved = localStorage.getItem('ifc-lite-theme');
+  if (saved === 'light' || saved === 'dark') return saved;
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
 export const UI_DEFAULTS = {
   /** Default active tool */
   ACTIVE_TOOL: 'select',
-  /** Default theme */
-  THEME: 'dark' as const,
+  /** Default theme – respects user's OS colour-scheme preference */
+  THEME: getInitialTheme(),
   /** Default hover tooltips state */
   HOVER_TOOLTIPS_ENABLED: false,
 } as const;

package/src/store/index.ts

@@ -30,6 +30,7 @@ import { createIdsSlice, type IDSSlice } from './slices/idsSlice.js';
 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 { createScriptSlice, type ScriptSlice } from './slices/scriptSlice.js';
 
 // Import constants for reset function
 import { CAMERA_DEFAULTS, SECTION_PLANE_DEFAULTS, UI_DEFAULTS, TYPE_VISIBILITY_DEFAULTS } from './constants.js';
@@ -43,8 +44,11 @@ export type { EntityRef, SchemaVersion, FederatedModel, MeasurementConstraintEdg
 // Re-export utility functions for entity references
 export { entityRefToString, stringToEntityRef, entityRefEquals, isIfcxDataStore } from './types.js';
 
+// Re-export single source of truth for globalId → EntityRef resolution
+export { resolveEntityRef } from './resolveEntityRef.js';
+
 // Re-export Drawing2D types
-export type { Drawing2DState, Drawing2DStatus } from './slices/drawing2DSlice.js';
+export type { Drawing2DState, Drawing2DStatus, Annotation2DTool, PolygonArea2DResult, TextAnnotation2D, CloudAnnotation2D, SelectedAnnotation2D } from './slices/drawing2DSlice.js';
 
 // Re-export Sheet types
 export type { SheetState } from './slices/sheetSlice.js';
@@ -64,6 +68,9 @@ export type { PinboardSlice } from './slices/pinboardSlice.js';
 // Re-export Lens types
 export type { LensSlice, Lens, LensRule, LensCriteria } from './slices/lensSlice.js';
 
+// Re-export Script types
+export type { ScriptSlice } from './slices/scriptSlice.js';
+
 // Combined store type
 export type ViewerState = LoadingSlice &
   SelectionSlice &
@@ -82,7 +89,8 @@ export type ViewerState = LoadingSlice &
   IDSSlice &
   ListSlice &
   PinboardSlice &
-  LensSlice & {
+  LensSlice &
+  ScriptSlice & {
     resetViewerState: () => void;
   };
 
@@ -109,6 +117,7 @@ export const useViewerStore = create<ViewerState>()((...args) => ({
   ...createListSlice(...args),
   ...createPinboardSlice(...args),
   ...createLensSlice(...args),
+  ...createScriptSlice(...args),
 
   // Reset all viewer state when loading new file
   // Note: Does NOT clear models - use clearAllModels() for that
@@ -205,6 +214,16 @@ export const useViewerStore = create<ViewerState>()((...args) => ({
       measure2DLockedAxis: null,
       measure2DResults: [],
       measure2DSnapPoint: null,
+      // Annotation tools
+      annotation2DActiveTool: 'none' as const,
+      annotation2DCursorPos: null,
+      polygonArea2DPoints: [],
+      polygonArea2DResults: [],
+      textAnnotations2D: [],
+      textAnnotation2DEditing: null,
+      cloudAnnotation2DPoints: [],
+      cloudAnnotations2D: [],
+      selectedAnnotation2D: null,
       // Drawing Sheet
       activeSheet: null,
       sheetEnabled: false,
@@ -238,6 +257,13 @@ export const useViewerStore = create<ViewerState>()((...args) => ({
       // Pinboard - clear pinned entities on new file
       pinboardEntities: new Set<string>(),
 
+      // Script - reset execution state but keep saved scripts and editor content
+      scriptPanelVisible: false,
+      scriptExecutionState: 'idle' as const,
+      scriptLastResult: null,
+      scriptLastError: null,
+      scriptDeleteConfirmId: null,
+
       // Lens - deactivate but keep saved lenses
       activeLensId: null,
       lensPanelVisible: false,

package/src/store/resolveEntityRef.ts

@@ -0,0 +1,44 @@
+/* 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/. */
+
+/**
+ * Single source of truth for resolving a globalId to an EntityRef.
+ *
+ * Every code path that needs an EntityRef from a globalId MUST use this
+ * function.  It guarantees consistent modelId values so that basket
+ * add/remove keys always match, regardless of which UI surface triggered
+ * the selection.
+ */
+
+import type { EntityRef } from './types.js';
+import { useViewerStore } from './index.js';
+
+/**
+ * Resolve a globalId (renderer-space) to an EntityRef (model-space).
+ *
+ * Resolution order:
+ *  1. resolveGlobalIdFromModels (offset-based range check — the canonical path)
+ *  2. First loaded model as fallback (single-model, offset 0)
+ *  3. 'legacy' sentinel for truly legacy single-model mode (no federation map)
+ *
+ * ALWAYS returns an EntityRef — never null.  This ensures all callers
+ * (multi-select, basket, context menu) can proceed without null-guards.
+ */
+export function resolveEntityRef(globalId: number): EntityRef {
+  const state = useViewerStore.getState();
+  const resolved = state.resolveGlobalIdFromModels(globalId);
+  if (resolved) {
+    return { modelId: resolved.modelId, expressId: resolved.expressId };
+  }
+
+  // Fallback: single-model mode where offset is 0 → globalId === expressId
+  if (state.models.size > 0) {
+    const firstModelId = state.models.keys().next().value as string;
+    return { modelId: firstModelId, expressId: globalId };
+  }
+
+  // Legacy single-model mode: no models in federation map yet.
+  // 'legacy' is recognized by PropertiesPanel for fallback to legacy ifcDataStore.
+  return { modelId: 'legacy', expressId: globalId };
+}

package/src/store/slices/drawing2DSlice.ts

@@ -15,6 +15,9 @@ import { BUILT_IN_PRESETS } from '@ifc-lite/drawing-2d';
 
 export type Drawing2DStatus = 'idle' | 'generating' | 'ready' | 'error';
 
+/** Active 2D annotation tool */
+export type Annotation2DTool = 'none' | 'measure' | 'polygon-area' | 'text' | 'cloud';
+
 /** Point in 2D drawing coordinates */
 export interface Point2D {
   x: number;
@@ -29,6 +32,39 @@ export interface Measure2DResult {
   distance: number; // in drawing units (typically meters)
 }
 
+/** Polygon area measurement result */
+export interface PolygonArea2DResult {
+  id: string;
+  points: Point2D[];  // Closed polygon vertices (drawing coords)
+  area: number;       // Computed area in m²
+  perimeter: number;  // Computed perimeter in m
+}
+
+/** Text box annotation */
+export interface TextAnnotation2D {
+  id: string;
+  position: Point2D;       // Top-left corner (drawing coords)
+  text: string;
+  fontSize: number;        // Font size in screen px (default 14)
+  color: string;           // Text color (default '#000000')
+  backgroundColor: string; // Background fill
+  borderColor: string;     // Border color
+}
+
+/** Cloud (revision cloud) annotation */
+export interface CloudAnnotation2D {
+  id: string;
+  points: Point2D[];  // Rectangle corners (drawing coords, 2 points: topLeft, bottomRight)
+  color: string;      // Cloud stroke color (default '#E53935')
+  label: string;      // Optional label text inside cloud
+}
+
+/** Reference to a selected annotation */
+export interface SelectedAnnotation2D {
+  type: 'measure' | 'polygon' | 'text' | 'cloud';
+  id: string;
+}
+
 export interface Drawing2DState {
   /** Current drawing data (null when not generated) */
   drawing2D: Drawing2D | null;
@@ -80,6 +116,34 @@ export interface Drawing2DState {
   measure2DResults: Measure2DResult[];
   /** Current snap point (if snapping to geometry) */
   measure2DSnapPoint: Point2D | null;
+
+  // Annotation Tool System
+  /** Active annotation tool (none = pan mode) */
+  annotation2DActiveTool: Annotation2DTool;
+  /** Current cursor position in drawing coords for preview rendering */
+  annotation2DCursorPos: Point2D | null;
+
+  // Polygon Area Measurement
+  /** Points being placed for in-progress polygon */
+  polygonArea2DPoints: Point2D[];
+  /** Completed polygon area measurements */
+  polygonArea2DResults: PolygonArea2DResult[];
+
+  // Text Annotations
+  /** Placed text annotations */
+  textAnnotations2D: TextAnnotation2D[];
+  /** ID of text annotation currently being edited (null = none) */
+  textAnnotation2DEditing: string | null;
+
+  // Cloud Annotations
+  /** Rectangle corners being placed for in-progress cloud (0-2 points) */
+  cloudAnnotation2DPoints: Point2D[];
+  /** Completed cloud annotations */
+  cloudAnnotations2D: CloudAnnotation2D[];
+
+  // Selection
+  /** Currently selected annotation (null = none) */
+  selectedAnnotation2D: SelectedAnnotation2D | null;
 }
 
 export interface Drawing2DSlice extends Drawing2DState {
@@ -121,6 +185,45 @@ export interface Drawing2DSlice extends Drawing2DState {
   completeMeasure2D: () => void;
   /** Cancel current measurement */
   cancelMeasure2D: () => void;
+
+  // Annotation Tool Actions
+  /** Set active annotation tool (also manages measure2DMode for backward compat) */
+  setAnnotation2DActiveTool: (tool: Annotation2DTool) => void;
+  /** Update cursor position for annotation previews */
+  setAnnotation2DCursorPos: (pos: Point2D | null) => void;
+
+  // Polygon Area Actions
+  addPolygonArea2DPoint: (point: Point2D) => void;
+  completePolygonArea2D: (area: number, perimeter: number) => void;
+  cancelPolygonArea2D: () => void;
+  removePolygonArea2DResult: (id: string) => void;
+  clearPolygonArea2DResults: () => void;
+
+  // Text Annotation Actions
+  addTextAnnotation2D: (annotation: TextAnnotation2D) => void;
+  updateTextAnnotation2D: (id: string, updates: Partial<TextAnnotation2D>) => void;
+  removeTextAnnotation2D: (id: string) => void;
+  setTextAnnotation2DEditing: (id: string | null) => void;
+  clearTextAnnotations2D: () => void;
+
+  // Cloud Annotation Actions
+  addCloudAnnotation2DPoint: (point: Point2D) => void;
+  completeCloudAnnotation2D: (label?: string) => void;
+  cancelCloudAnnotation2D: () => void;
+  removeCloudAnnotation2D: (id: string) => void;
+  clearCloudAnnotations2D: () => void;
+
+  // Selection Actions
+  /** Set the selected annotation (null to deselect) */
+  setSelectedAnnotation2D: (sel: SelectedAnnotation2D | null) => void;
+  /** Delete the currently selected annotation */
+  deleteSelectedAnnotation2D: () => void;
+  /** Move an annotation to a new origin position (used during drag) */
+  moveAnnotation2D: (sel: SelectedAnnotation2D, newOrigin: Point2D) => void;
+
+  // Bulk Actions
+  /** Clear all annotations (measurements, polygons, text, clouds) */
+  clearAllAnnotations2D: () => void;
 }
 
 const getDefaultDisplayOptions = (): Drawing2DState['drawing2DDisplayOptions'] => ({
@@ -155,6 +258,17 @@ const getDefaultState = (): Drawing2DState => ({
   measure2DLockedAxis: null,
   measure2DResults: [],
   measure2DSnapPoint: null,
+  // Annotation tools
+  annotation2DActiveTool: 'none',
+  annotation2DCursorPos: null,
+  polygonArea2DPoints: [],
+  polygonArea2DResults: [],
+  textAnnotations2D: [],
+  textAnnotation2DEditing: null,
+  cloudAnnotation2DPoints: [],
+  cloudAnnotations2D: [],
+  // Selection
+  selectedAnnotation2D: null,
 });
 
 export const createDrawing2DSlice: StateCreator<Drawing2DSlice, [], [], Drawing2DSlice> = (set, get) => ({
@@ -337,4 +451,211 @@ export const createDrawing2DSlice: StateCreator<Drawing2DSlice, [], [], Drawing2
     measure2DLockedAxis: null,
     measure2DSnapPoint: null,
   }),
+
+  // ═══════════════════════════════════════════════════════════════════════
+  // ANNOTATION TOOL ACTIONS
+  // ═══════════════════════════════════════════════════════════════════════
+
+  setAnnotation2DActiveTool: (tool) => {
+    const state = get();
+    // Cancel any in-progress work from previous tool
+    const resetState: Partial<Drawing2DState> = {
+      annotation2DActiveTool: tool,
+      annotation2DCursorPos: null,
+      // Keep measure2DMode in sync for backward compatibility
+      measure2DMode: tool === 'measure',
+      // Clear in-progress state from all tools
+      measure2DStart: null,
+      measure2DCurrent: null,
+      measure2DShiftLocked: false,
+      measure2DLockedAxis: null,
+      measure2DSnapPoint: null,
+      polygonArea2DPoints: [],
+      cloudAnnotation2DPoints: [],
+      textAnnotation2DEditing: null,
+      selectedAnnotation2D: null,
+    };
+    set(resetState);
+  },
+
+  setAnnotation2DCursorPos: (pos) => set({ annotation2DCursorPos: pos }),
+
+  // Polygon Area Actions
+  addPolygonArea2DPoint: (point) => set((state) => ({
+    polygonArea2DPoints: [...state.polygonArea2DPoints, point],
+  })),
+
+  completePolygonArea2D: (area, perimeter) => {
+    const state = get();
+    if (state.polygonArea2DPoints.length < 3) return;
+
+    const result: PolygonArea2DResult = {
+      id: `poly-area-${Date.now()}`,
+      points: [...state.polygonArea2DPoints],
+      area,
+      perimeter,
+    };
+
+    set({
+      polygonArea2DResults: [...state.polygonArea2DResults, result],
+      polygonArea2DPoints: [],
+      annotation2DCursorPos: null,
+    });
+  },
+
+  cancelPolygonArea2D: () => set({
+    polygonArea2DPoints: [],
+    annotation2DCursorPos: null,
+  }),
+
+  removePolygonArea2DResult: (id) => set((state) => ({
+    polygonArea2DResults: state.polygonArea2DResults.filter((r) => r.id !== id),
+  })),
+
+  clearPolygonArea2DResults: () => set({ polygonArea2DResults: [] }),
+
+  // Text Annotation Actions
+  addTextAnnotation2D: (annotation) => set((state) => ({
+    textAnnotations2D: [...state.textAnnotations2D, annotation],
+  })),
+
+  updateTextAnnotation2D: (id, updates) => set((state) => ({
+    textAnnotations2D: state.textAnnotations2D.map((a) =>
+      a.id === id ? { ...a, ...updates } : a
+    ),
+  })),
+
+  removeTextAnnotation2D: (id) => set((state) => ({
+    textAnnotations2D: state.textAnnotations2D.filter((a) => a.id !== id),
+    textAnnotation2DEditing: state.textAnnotation2DEditing === id ? null : state.textAnnotation2DEditing,
+  })),
+
+  setTextAnnotation2DEditing: (id) => set({ textAnnotation2DEditing: id }),
+
+  clearTextAnnotations2D: () => set({
+    textAnnotations2D: [],
+    textAnnotation2DEditing: null,
+  }),
+
+  // Cloud Annotation Actions
+  addCloudAnnotation2DPoint: (point) => set((state) => ({
+    cloudAnnotation2DPoints: [...state.cloudAnnotation2DPoints, point],
+  })),
+
+  completeCloudAnnotation2D: (label = '') => {
+    const state = get();
+    if (state.cloudAnnotation2DPoints.length < 2) return;
+
+    const result: CloudAnnotation2D = {
+      id: `cloud-${Date.now()}`,
+      points: [...state.cloudAnnotation2DPoints],
+      color: '#E53935',
+      label,
+    };
+
+    set({
+      cloudAnnotations2D: [...state.cloudAnnotations2D, result],
+      cloudAnnotation2DPoints: [],
+      annotation2DCursorPos: null,
+    });
+  },
+
+  cancelCloudAnnotation2D: () => set({
+    cloudAnnotation2DPoints: [],
+    annotation2DCursorPos: null,
+  }),
+
+  removeCloudAnnotation2D: (id) => set((state) => ({
+    cloudAnnotations2D: state.cloudAnnotations2D.filter((a) => a.id !== id),
+  })),
+
+  clearCloudAnnotations2D: () => set({ cloudAnnotations2D: [] }),
+
+  // Selection Actions
+  setSelectedAnnotation2D: (sel) => set({ selectedAnnotation2D: sel }),
+
+  deleteSelectedAnnotation2D: () => {
+    const state = get();
+    const sel = state.selectedAnnotation2D;
+    if (!sel) return;
+
+    switch (sel.type) {
+      case 'measure':
+        set({ measure2DResults: state.measure2DResults.filter((r) => r.id !== sel.id), selectedAnnotation2D: null });
+        break;
+      case 'polygon':
+        set({ polygonArea2DResults: state.polygonArea2DResults.filter((r) => r.id !== sel.id), selectedAnnotation2D: null });
+        break;
+      case 'text':
+        set({
+          textAnnotations2D: state.textAnnotations2D.filter((a) => a.id !== sel.id),
+          selectedAnnotation2D: null,
+          textAnnotation2DEditing: state.textAnnotation2DEditing === sel.id ? null : state.textAnnotation2DEditing,
+        });
+        break;
+      case 'cloud':
+        set({ cloudAnnotations2D: state.cloudAnnotations2D.filter((a) => a.id !== sel.id), selectedAnnotation2D: null });
+        break;
+    }
+  },
+
+  moveAnnotation2D: (sel, newOrigin) => {
+    const state = get();
+    switch (sel.type) {
+      case 'measure': {
+        const result = state.measure2DResults.find((r) => r.id === sel.id);
+        if (!result) return;
+        const dx = newOrigin.x - result.start.x;
+        const dy = newOrigin.y - result.start.y;
+        set({ measure2DResults: state.measure2DResults.map((r) =>
+          r.id === sel.id ? { ...r, start: { x: r.start.x + dx, y: r.start.y + dy }, end: { x: r.end.x + dx, y: r.end.y + dy } } : r
+        ) });
+        break;
+      }
+      case 'polygon': {
+        const result = state.polygonArea2DResults.find((r) => r.id === sel.id);
+        if (!result) return;
+        const dx = newOrigin.x - result.points[0].x;
+        const dy = newOrigin.y - result.points[0].y;
+        set({ polygonArea2DResults: state.polygonArea2DResults.map((r) =>
+          r.id === sel.id ? { ...r, points: r.points.map((p) => ({ x: p.x + dx, y: p.y + dy })) } : r
+        ) });
+        break;
+      }
+      case 'text': {
+        set({ textAnnotations2D: state.textAnnotations2D.map((a) =>
+          a.id === sel.id ? { ...a, position: newOrigin } : a
+        ) });
+        break;
+      }
+      case 'cloud': {
+        const cloud = state.cloudAnnotations2D.find((a) => a.id === sel.id);
+        if (!cloud || cloud.points.length < 2) return;
+        const dx = newOrigin.x - cloud.points[0].x;
+        const dy = newOrigin.y - cloud.points[0].y;
+        set({ cloudAnnotations2D: state.cloudAnnotations2D.map((a) =>
+          a.id === sel.id ? { ...a, points: a.points.map((p) => ({ x: p.x + dx, y: p.y + dy })) } : a
+        ) });
+        break;
+      }
+    }
+  },
+
+  // Bulk Actions
+  clearAllAnnotations2D: () => set({
+    measure2DResults: [],
+    measure2DStart: null,
+    measure2DCurrent: null,
+    measure2DShiftLocked: false,
+    measure2DLockedAxis: null,
+    measure2DSnapPoint: null,
+    polygonArea2DPoints: [],
+    polygonArea2DResults: [],
+    textAnnotations2D: [],
+    textAnnotation2DEditing: null,
+    cloudAnnotation2DPoints: [],
+    cloudAnnotations2D: [],
+    annotation2DCursorPos: null,
+    selectedAnnotation2D: null,
+  }),
 });

package/src/store/slices/lensSlice.ts

@@ -11,18 +11,24 @@
  */
 
 import type { StateCreator } from 'zustand';
-import type { Lens, LensRule, LensCriteria } from '@ifc-lite/lens';
+import type { Lens, LensRule, LensCriteria, AutoColorSpec, AutoColorLegendEntry, DiscoveredLensData } from '@ifc-lite/lens';
 import { BUILTIN_LENSES } from '@ifc-lite/lens';
 
 // Re-export types so existing consumer imports from this file still work
-export type { Lens, LensRule, LensCriteria };
+export type { Lens, LensRule, LensCriteria, AutoColorSpec, AutoColorLegendEntry, DiscoveredLensData };
 
 // Re-export constants for consumers that import from this file
-export { COMMON_IFC_CLASSES, COMMON_IFC_TYPES, LENS_PALETTE } from '@ifc-lite/lens';
+export {
+  COMMON_IFC_CLASSES, COMMON_IFC_TYPES, LENS_PALETTE,
+  LENS_CRITERIA_TYPES, AUTO_COLOR_SOURCES, ENTITY_ATTRIBUTE_NAMES,
+} from '@ifc-lite/lens';
 
 /** localStorage key for persisting custom lenses */
 const STORAGE_KEY = 'ifc-lite-custom-lenses';
 
+/** Ephemeral lens ID created when coloring from list column headers */
+export const AUTO_COLOR_FROM_LIST_ID = 'auto-color-from-list';
+
 /** Built-in lens IDs — used to detect overrides */
 const BUILTIN_IDS = new Set(BUILTIN_LENSES.map(l => l.id));
 
@@ -98,6 +104,10 @@ export interface LensSlice {
   lensRuleCounts: Map<string, number>;
   /** Computed: ruleId → matched entity global IDs for the active lens */
   lensRuleEntityIds: Map<string, number[]>;
+  /** Auto-color legend entries (one per distinct value) for UI display */
+  lensAutoColorLegend: AutoColorLegendEntry[];
+  /** Discovered data from loaded models (classes instant, rest lazy) */
+  discoveredLensData: DiscoveredLensData | null;
 
   // Actions
   createLens: (lens: Lens) => void;
@@ -110,12 +120,18 @@ export interface LensSlice {
   setLensHiddenIds: (ids: Set<number>) => void;
   setLensRuleCounts: (counts: Map<string, number>) => void;
   setLensRuleEntityIds: (ids: Map<string, number[]>) => void;
+  setLensAutoColorLegend: (legend: AutoColorLegendEntry[]) => void;
+  setDiscoveredLensData: (data: DiscoveredLensData | null) => void;
+  /** Merge lazy-discovered data sources (psets, quantities, etc.) into existing discovered data */
+  mergeDiscoveredData: (patch: Partial<DiscoveredLensData>) => void;
   /** Get the active lens configuration */
   getActiveLens: () => Lens | null;
   /** Import lenses from parsed JSON array */
   importLenses: (lenses: Lens[]) => void;
   /** Export all lenses (builtins + custom) as serializable array */
   exportLenses: () => Lens[];
+  /** Create and activate an auto-color lens from a data column spec */
+  activateAutoColorFromColumn: (spec: AutoColorSpec, label: string) => void;
 }
 
 export const createLensSlice: StateCreator<LensSlice, [], [], LensSlice> = (set, get) => ({
@@ -127,6 +143,8 @@ export const createLensSlice: StateCreator<LensSlice, [], [], LensSlice> = (set,
   lensHiddenIds: new Set(),
   lensRuleCounts: new Map(),
   lensRuleEntityIds: new Map(),
+  lensAutoColorLegend: [],
+  discoveredLensData: null,
 
   // Actions
   createLens: (lens) => set((state) => {
@@ -161,6 +179,12 @@ export const createLensSlice: StateCreator<LensSlice, [], [], LensSlice> = (set,
   setLensHiddenIds: (lensHiddenIds) => set({ lensHiddenIds }),
   setLensRuleCounts: (lensRuleCounts) => set({ lensRuleCounts }),
   setLensRuleEntityIds: (lensRuleEntityIds) => set({ lensRuleEntityIds }),
+  setLensAutoColorLegend: (lensAutoColorLegend) => set({ lensAutoColorLegend }),
+  setDiscoveredLensData: (discoveredLensData) => set({ discoveredLensData }),
+  mergeDiscoveredData: (patch) => set((state) => {
+    if (!state.discoveredLensData) return {};
+    return { discoveredLensData: { ...state.discoveredLensData, ...patch } };
+  }),
 
   getActiveLens: () => {
     const { savedLenses, activeLensId } = get();
@@ -179,6 +203,24 @@ export const createLensSlice: StateCreator<LensSlice, [], [], LensSlice> = (set,
   }),
 
   exportLenses: () => {
-    return get().savedLenses.map(({ id, name, rules }) => ({ id, name, rules }));
+    return get().savedLenses.map(({ id, name, rules, autoColor }) => {
+      const out: Lens = { id, name, rules };
+      if (autoColor) out.autoColor = autoColor;
+      return out;
+    });
   },
+
+  activateAutoColorFromColumn: (spec, label) => set((state) => {
+    const lensId = AUTO_COLOR_FROM_LIST_ID;
+    const lens: Lens = {
+      id: lensId,
+      name: `Color by ${label}`,
+      rules: [],
+      autoColor: spec,
+    };
+    // Replace existing ephemeral lens or add new
+    const filtered = state.savedLenses.filter(l => l.id !== lensId);
+    const next = [...filtered, lens];
+    return { savedLenses: next, activeLensId: lensId, lensPanelVisible: true };
+  }),
 });