@ifc-lite/viewer 1.23.0 → 1.25.0

package/src/components/viewer/Section2DPanel.tsx

@@ -12,7 +12,7 @@
  */
 
 import React, { useCallback, useRef, useState, useEffect, useMemo } from 'react';
-import { X, Download, Eye, EyeOff, Maximize2, ZoomIn, ZoomOut, Loader2, Printer, GripVertical, MoreHorizontal, RefreshCw, Pin, PinOff, Palette, Ruler, Trash2, FileText, Shapes, Box, PenTool, Hexagon, Type, Cloud, MousePointer2 } from 'lucide-react';
+import { X, Download, Eye, EyeOff, Maximize2, ZoomIn, ZoomOut, Loader2, Printer, GripVertical, MoreHorizontal, RefreshCw, Pin, PinOff, Palette, Ruler, Trash2, FileText, Shapes, Box, PenTool, Hexagon, Type, Cloud, MousePointer2, Tag } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import {
   DropdownMenu,
@@ -31,11 +31,12 @@ import { SheetSetupPanel } from './SheetSetupPanel';
 import { TitleBlockEditor } from './TitleBlockEditor';
 import { TextAnnotationEditor } from './TextAnnotationEditor';
 import { Drawing2DCanvas } from './Drawing2DCanvas';
-import { useDrawingGeneration } from '@/hooks/useDrawingGeneration';
+import { useDrawingGeneration, AXIS_MAP } from '@/hooks/useDrawingGeneration';
 import { useMeasure2D } from '@/hooks/useMeasure2D';
 import { useAnnotation2D } from '@/hooks/useAnnotation2D';
 import { useViewControls } from '@/hooks/useViewControls';
 import { useDrawingExport } from '@/hooks/useDrawingExport';
+import { useSymbolicAnnotationsForDrawing } from '@/hooks/useSymbolicAnnotations';
 
 interface Section2DPanelProps {
   mergedGeometry?: GeometryResult | null;
@@ -279,6 +280,43 @@ export function Section2DPanel({
     setMeasure2DSnapPoint, cancelMeasure2D, completeMeasure2D,
   });
 
+  // ─── IFC annotation overlay (issue #812) ──────────────────────────────────
+  // Re-derive the section's world-coord cut position from the same bounds
+  // useDrawingGeneration uses, so the annotation filter stays in lockstep
+  // with the cut. Empty/missing bounds collapse to an inert range → hook
+  // returns empty, the overlay simply does nothing.
+  const ifcAnnotationsForDrawing = useMemo(() => {
+    const bounds = geometryResult?.coordinateInfo?.shiftedBounds;
+    if (!bounds) {
+      return { sectionPosWorld: 0, viewDepth: 0, fallbackY: 0 };
+    }
+    const axis = AXIS_MAP[sectionPlane.axis];
+    const axisMin = bounds.min[axis];
+    const axisMax = bounds.max[axis];
+    const sectionPosWorld = axisMin + (sectionPlane.position / 100) * (axisMax - axisMin);
+    const viewDepth = (axisMax - axisMin) * 0.5; // matches useDrawingGeneration's maxDepth
+    // For loose annotations (no resolvable storey), fall back to mid-Y like
+    // the 3D viewport does. This lets storeyless models still surface their
+    // annotations on the relevant section.
+    const yMin = bounds.min.y;
+    const yMax = bounds.max.y;
+    const fallbackY = Number.isFinite(yMin) && Number.isFinite(yMax) ? (yMin + yMax) * 0.5 : 0;
+    return { sectionPosWorld, viewDepth, fallbackY };
+  }, [geometryResult, sectionPlane.axis, sectionPlane.position]);
+
+  const ifcAnnotationData = useSymbolicAnnotationsForDrawing({
+    enabled: displayOptions.showIfcAnnotations && status === 'ready',
+    axis: sectionPlane.axis,
+    sectionPosWorld: ifcAnnotationsForDrawing.sectionPosWorld,
+    viewDepth: ifcAnnotationsForDrawing.viewDepth,
+    flipped: sectionPlane.flipped,
+    fallbackY: ifcAnnotationsForDrawing.fallbackY,
+  });
+
+  const toggleIfcAnnotations = useCallback(() => {
+    updateDisplayOptions({ showIfcAnnotations: !displayOptions.showIfcAnnotations });
+  }, [displayOptions.showIfcAnnotations, updateDisplayOptions]);
+
   const annotationHandlers = useAnnotation2D({
     drawing, viewTransform, sectionAxis: sectionPlane.axis, containerRef,
     activeTool: annotation2DActiveTool, setActiveTool: setAnnotation2DActiveTool,
@@ -536,6 +574,17 @@ export function Section2DPanel({
                 {displayOptions.useSymbolicRepresentations ? <Shapes className="h-4 w-4" /> : <Box className="h-4 w-4" />}
               </Button>
 
+              {/* IFC Annotations overlay toggle (issue #812) */}
+              <Button
+                variant={displayOptions.showIfcAnnotations ? 'default' : 'ghost'}
+                size="icon-sm"
+                onClick={toggleIfcAnnotations}
+                title={displayOptions.showIfcAnnotations ? 'Hide IFC annotations on this section' : 'Show IFC annotations on this section'}
+                disabled={sectionPlane.axis !== 'down'}
+              >
+                <Tag className="h-4 w-4" />
+              </Button>
+
               {/* Annotation Tools Dropdown */}
               <DropdownMenu>
                 <DropdownMenuTrigger asChild>
@@ -703,6 +752,10 @@ export function Section2DPanel({
                     {displayOptions.useSymbolicRepresentations ? <Shapes className="h-4 w-4 mr-2" /> : <Box className="h-4 w-4 mr-2" />}
                     {displayOptions.useSymbolicRepresentations ? 'Symbolic (Plan)' : 'Section Cut (Body)'}
                   </DropdownMenuItem>
+                  <DropdownMenuItem onClick={toggleIfcAnnotations} disabled={sectionPlane.axis !== 'down'}>
+                    <Tag className="h-4 w-4 mr-2" />
+                    IFC Annotations {displayOptions.showIfcAnnotations ? 'On' : 'Off'}
+                  </DropdownMenuItem>
                   <DropdownMenuItem onClick={() => setAnnotation2DActiveTool('none')}>
                     <MousePointer2 className="h-4 w-4 mr-2" />
                     Select / Pan {annotation2DActiveTool === 'none' ? '(On)' : ''}
@@ -849,6 +902,9 @@ export function Section2DPanel({
               cloudAnnotationPoints={cloudAnnotation2DPoints}
               cloudAnnotations={cloudAnnotations2D}
               selectedAnnotation={selectedAnnotation2D}
+              ifcAnnotationLines={ifcAnnotationData.lines}
+              ifcAnnotationTexts={ifcAnnotationData.texts}
+              ifcAnnotationFills={ifcAnnotationData.fills}
             />
             {/* Subtle updating indicator - shows while regenerating without hiding the drawing */}
             {isRegenerating && (

package/src/components/viewer/StatusBar.tsx

@@ -9,6 +9,8 @@ import { formatNumber, formatBytes } from '@/lib/utils';
 import { useViewerStore } from '@/store';
 import { useIfc } from '@/hooks/useIfc';
 import { useWebGPU } from '@/hooks/useWebGPU';
+import { FlavorIndicator } from '@/components/extensions/FlavorIndicator';
+import { FlavorDialog } from '@/components/extensions/FlavorDialog';
 
 export function StatusBar() {
   const { loading, geometryResult, ifcDataStore } = useIfc();
@@ -20,6 +22,16 @@ export function StatusBar() {
 
   const [fps, setFps] = useState(60);
   const [memory, setMemory] = useState(0);
+  const [flavorDialogOpen, setFlavorDialogOpen] = useState(false);
+  /** Deep-link from Command Palette → "Manage flavors…". */
+  const flavorDialogRequested = useViewerStore((s) => s.flavorDialogRequested);
+  const setFlavorDialogRequested = useViewerStore((s) => s.setFlavorDialogRequested);
+  useEffect(() => {
+    if (flavorDialogRequested) {
+      setFlavorDialogOpen(true);
+      setFlavorDialogRequested(false);
+    }
+  }, [flavorDialogRequested, setFlavorDialogRequested]);
 
   // FPS counter (simplified)
   useEffect(() => {
@@ -175,6 +187,10 @@ export function StatusBar() {
 
         <Separator orientation="vertical" className="h-3.5" />
 
+        <FlavorIndicator onClick={() => setFlavorDialogOpen(true)} />
+
+        <Separator orientation="vertical" className="h-3.5" />
+
         <span className="opacity-60">v{__APP_VERSION__}</span>
 
         <Separator orientation="vertical" className="h-3.5" />
@@ -189,6 +205,8 @@ export function StatusBar() {
           ifclite.dev →
         </a>
       </div>
+
+      <FlavorDialog open={flavorDialogOpen} onClose={() => setFlavorDialogOpen(false)} />
     </div>
   );
 }

package/src/components/viewer/ViewerLayout.tsx

@@ -15,6 +15,11 @@ import { StatusBar } from './StatusBar';
 import { ViewportContainer } from './ViewportContainer';
 import { KeyboardShortcutsDialog, useKeyboardShortcutsDialog } from './KeyboardShortcutsDialog';
 import { useKeyboardShortcuts } from '@/hooks/useKeyboardShortcuts';
+import { useActionLogger } from '@/hooks/useActionLogger';
+import { usePrivacyDisclosure } from '@/hooks/usePrivacyDisclosure';
+import { isSafeMode } from '@/lib/safe-mode';
+import { ShieldAlert } from 'lucide-react';
+import { ExtensionDockHost } from '@/components/extensions/ExtensionDockHost';
 import { useIfc } from '@/hooks/useIfc';
 import { useViewerStore } from '@/store';
 import { EntityContextMenu } from './EntityContextMenu';
@@ -26,6 +31,7 @@ import { LensPanel } from './LensPanel';
 import { ListPanel } from './lists/ListPanel';
 import { ScriptPanel } from './ScriptPanel';
 import { GanttPanel } from './schedule/GanttPanel';
+import { ExtensionsPanel } from '@/components/extensions/ExtensionsPanel';
 import { CommandPalette } from './CommandPalette';
 import { SearchModal } from './SearchModal';
 import { DesktopEntitlementBanner } from './DesktopEntitlementBanner';
@@ -45,6 +51,11 @@ export function ViewerLayout() {
   useKeyboardShortcuts();
   // ⌘D / Ctrl+D to duplicate the current selection.
   useDuplicateShortcut();
+  // Bridge viewer state transitions into the extension action log
+  // so the idle pattern miner can surface one-click tool suggestions.
+  useActionLogger();
+  // Show the RFC §06 §7 privacy disclosure on first launch.
+  usePrivacyDisclosure();
   const shortcutsDialog = useKeyboardShortcutsDialog();
 
   // Auto-load a model from ?model=<URL>. Used by the landing-page iframe to drop a
@@ -115,6 +126,8 @@ export function ViewerLayout() {
   const setActiveTool = useViewerStore((s) => s.setActiveTool);
   const idsPanelVisible = useViewerStore((s) => s.idsPanelVisible);
   const setIdsPanelVisible = useViewerStore((s) => s.setIdsPanelVisible);
+  const extensionsPanelVisible = useViewerStore((s) => s.extensionsPanelVisible);
+  const setExtensionsPanelVisible = useViewerStore((s) => s.setExtensionsPanelVisible);
   const listPanelVisible = useViewerStore((s) => s.listPanelVisible);
   const setListPanelVisible = useViewerStore((s) => s.setListPanelVisible);
   const lensPanelVisible = useViewerStore((s) => s.lensPanelVisible);
@@ -241,9 +254,21 @@ export function ViewerLayout() {
   }, [theme]);
 
 
+  const safeMode = isSafeMode();
+
   return (
     <TooltipProvider delayDuration={300}>
       <div className="flex flex-col h-screen h-[100dvh] w-screen overflow-hidden bg-background text-foreground">
+        {safeMode && (
+          <div className="flex items-center gap-2 border-b border-amber-500/40 bg-amber-500/10 px-3 py-1 text-[11px] text-amber-700 dark:text-amber-300">
+            <ShieldAlert className="h-3.5 w-3.5 shrink-0" />
+            <span>
+              Safe mode: extensions and the active flavor are not loaded for this
+              session. Append <code className="font-mono">?safe=0</code> or reload
+              without the flag to resume.
+            </span>
+          </div>
+        )}
         {/* Keyboard Shortcuts Dialog */}
         <KeyboardShortcutsDialog open={shortcutsDialog.open} onClose={shortcutsDialog.close} />
 
@@ -276,8 +301,13 @@ export function ViewerLayout() {
                     if (collapsed !== leftPanelCollapsed) setLeftPanelCollapsed(collapsed);
                   }}
                 >
-                  <div className="h-full w-full overflow-hidden panel-container">
-                    <HierarchyPanel />
+                  <div className="h-full w-full overflow-hidden panel-container flex flex-col">
+                    <div className="flex-1 min-h-0 overflow-hidden">
+                      <HierarchyPanel />
+                    </div>
+                    {/* Extension dock.left — collapses when no extension
+                        contributes. Sits beneath the hierarchy panel. */}
+                    <ExtensionDockHost slot="dock.left" className="max-h-[40%] border-t" />
                   </div>
                 </Panel>
 
@@ -316,8 +346,16 @@ export function ViewerLayout() {
                       <IDSPanel onClose={() => setIdsPanelVisible(false)} />
                     ) : bcfPanelVisible ? (
                       <BCFPanel onClose={() => setBcfPanelVisible(false)} />
+                    ) : extensionsPanelVisible ? (
+                      <ExtensionsPanel onClose={() => setExtensionsPanelVisible(false)} />
                     ) : (
-                      <PropertiesPanel />
+                      <div className="h-full flex flex-col">
+                        <div className="flex-1 min-h-0 overflow-hidden">
+                          <PropertiesPanel />
+                        </div>
+                        {/* Extension dock.right — collapses when empty. */}
+                        <ExtensionDockHost slot="dock.right" className="max-h-[40%] border-t" />
+                      </div>
                     )}
                   </div>
                 </Panel>
@@ -381,7 +419,7 @@ export function ViewerLayout() {
             {/* Mobile Bottom Sheet - Properties, BCF, IDS, or Lists */}
             {!rightPanelCollapsed && (
               <MobileBottomSheet
-                title={activeAnalysisExtension ? activeAnalysisExtension.label : ganttPanelVisible ? 'Schedule' : scriptPanelVisible ? 'Script' : listPanelVisible ? 'Lists' : activeTool === 'addElement' ? 'Add element' : lensPanelVisible ? 'Lens' : idsPanelVisible ? 'IDS Validation' : bcfPanelVisible ? 'BCF Issues' : 'Properties'}
+                title={activeAnalysisExtension ? activeAnalysisExtension.label : ganttPanelVisible ? 'Schedule' : scriptPanelVisible ? 'Script' : listPanelVisible ? 'Lists' : activeTool === 'addElement' ? 'Add element' : lensPanelVisible ? 'Lens' : idsPanelVisible ? 'IDS Validation' : bcfPanelVisible ? 'BCF Issues' : extensionsPanelVisible ? 'Extensions' : 'Properties'}
                 bottomInset={bottomViewportInset}
                 onClose={() => {
                   setRightPanelCollapsed(true);
@@ -391,6 +429,7 @@ export function ViewerLayout() {
                   if (bcfPanelVisible) setBcfPanelVisible(false);
                   if (lensPanelVisible) setLensPanelVisible(false);
                   if (idsPanelVisible) setIdsPanelVisible(false);
+                  if (extensionsPanelVisible) setExtensionsPanelVisible(false);
                   if (activeAnalysisExtension) closeActiveAnalysisExtension();
                   if (activeTool === 'addElement') setActiveTool('select');
                 }}
@@ -413,6 +452,8 @@ export function ViewerLayout() {
                   <IDSPanel onClose={() => setIdsPanelVisible(false)} />
                 ) : bcfPanelVisible ? (
                   <BCFPanel onClose={() => setBcfPanelVisible(false)} />
+                ) : extensionsPanelVisible ? (
+                  <ExtensionsPanel onClose={() => setExtensionsPanelVisible(false)} />
                 ) : (
                   <PropertiesPanel />
                 )}
@@ -455,6 +496,14 @@ export function ViewerLayout() {
           </div>
         )}
 
+        {/* Extension dock.bottom slot — collapses to nothing when no
+            extension contributes here. */}
+        {!isMobile && (
+          <div className="max-h-[40vh]">
+            <ExtensionDockHost slot="dock.bottom" />
+          </div>
+        )}
+
         {/* Status Bar — hidden on mobile to maximize viewport space */}
         {!isMobile && <StatusBar />}
       </div>

package/src/components/viewer/Viewport.tsx

@@ -40,6 +40,7 @@ import { useGeometryStreaming } from './useGeometryStreaming.js';
 import { usePointCloudSync } from './usePointCloudSync.js';
 import { usePointCloudLifecycle } from './usePointCloudLifecycle.js';
 import { useRenderUpdates } from './useRenderUpdates.js';
+import { useSymbolicAnnotations, useSymbolicAnnotationsRichData } from '../../hooks/useSymbolicAnnotations.js';
 
 interface ViewportProps {
   geometry: MeshData[] | null;
@@ -779,6 +780,77 @@ export function Viewport({
   const show3DOverlay = useViewerStore((s) => s.drawing2DDisplayOptions.show3DOverlay);
   const showHiddenLines = useViewerStore((s) => s.drawing2DDisplayOptions.showHiddenLines);
 
+  // ===== IfcAnnotation symbolic overlay =====
+  // Renders IfcAnnotation 2D drawing curves as a standalone 3D line overlay
+  // that's visible regardless of whether a section cut is active. Each
+  // segment is lifted to its containing storey's elevation, so a multi-
+  // storey model shows all storeys' annotations layered correctly in 3D
+  // (issue #653). Parsing is lazy and only runs while the toggle is on.
+  const ifcAnnotationsVisible = useViewerStore((s) => s.typeVisibility.ifcAnnotations);
+  // For annotations whose storey can't be resolved (or whose authored
+  // elevation is 0 because the storey Z lives on the placement instead),
+  // lift to the middle of the model's vertical span so they don't end up
+  // buried inside ground-floor geometry.
+  const annotationFallbackY = useMemo(() => {
+    const bounds = coordinateInfo?.shiftedBounds;
+    if (!bounds) return 0;
+    const min = bounds.min.y;
+    const max = bounds.max.y;
+    if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) return 0;
+    return (min + max) * 0.5;
+  }, [coordinateInfo]);
+  const annotationVertices3D = useSymbolicAnnotations({
+    enabled: ifcAnnotationsVisible,
+    fallbackY: annotationFallbackY,
+  });
+  const { texts: annotationTexts3D, fills: annotationFills3D } = useSymbolicAnnotationsRichData({
+    enabled: ifcAnnotationsVisible,
+    fallbackY: annotationFallbackY,
+  });
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !isInitialized) return;
+    if (annotationVertices3D.length === 0) {
+      renderer.clearAnnotationLines3D();
+    } else {
+      renderer.uploadAnnotationLines3D(annotationVertices3D);
+    }
+  }, [annotationVertices3D, isInitialized]);
+
+  // Upload IfcAnnotation text + fill data for the WebGPU symbolic overlay
+  // pipelines. Map the hook's per-annotation records into the SymbolicFillInput
+  // / SymbolicTextInput shape the renderer expects. Empty arrays clear cleanly.
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !isInitialized) return;
+    renderer.uploadAnnotationFills3D(
+      annotationFills3D.map((f) => ({
+        points: f.points,
+        holesOffsets: f.holesOffsets,
+        worldY: f.worldY,
+        color: f.color,
+      })),
+    );
+  }, [annotationFills3D, isInitialized]);
+
+  useEffect(() => {
+    const renderer = rendererRef.current;
+    if (!renderer || !isInitialized) return;
+    renderer.uploadAnnotationTexts3D(
+      annotationTexts3D.map((t) => ({
+        worldPos: t.worldPos,
+        dirX: t.dirX,
+        dirZ: t.dirZ,
+        height: t.height,
+        content: t.content,
+        alignment: t.alignment,
+        billboard: t.billboard,
+        color: t.color,
+        targetPx: t.targetPx,
+      })),
+    );
+  }, [annotationTexts3D, isInitialized]);
+
   // ===== Streaming progress =====
   const isStreaming = useViewerStore((state) => state.geometryStreamingActive);
 

package/src/hooks/useActionLogger.test.ts

@@ -0,0 +1,161 @@
+/* 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 assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  detectActions,
+  hashLensId,
+  type ActionLoggerStateShape,
+} from './useActionLogger.js';
+
+function makeState(over: Partial<ActionLoggerStateShape> = {}): ActionLoggerStateShape {
+  return {
+    models: over.models ?? new Map(),
+    activeLensId: over.activeLensId ?? null,
+    selectedEntities: over.selectedEntities ?? [],
+    sectionPlane: over.sectionPlane,
+    drawing2DPanelVisible: over.drawing2DPanelVisible,
+  };
+}
+
+describe('hashLensId', () => {
+  it('produces a stable 8-char hex token', () => {
+    const h1 = hashLensId('by-fire-rating');
+    const h2 = hashLensId('by-fire-rating');
+    assert.strictEqual(h1, h2);
+    assert.match(h1, /^lens-[0-9a-f]{8}$/);
+  });
+
+  it('distinguishes distinct ids', () => {
+    assert.notStrictEqual(hashLensId('foo'), hashLensId('bar'));
+  });
+
+  it('does not leak the original string', () => {
+    const h = hashLensId("John's basement check");
+    assert.ok(!h.includes('John'));
+    assert.ok(!h.includes('basement'));
+  });
+});
+
+describe('detectActions', () => {
+  it('emits model.load when a model is added', () => {
+    const prev = makeState();
+    const next = makeState({
+      models: new Map([['m1', { schemaVersion: 'IFC4', ifcDataStore: { entityCount: 100 }, fileSize: 5000 }]]),
+    });
+    const events = detectActions(prev, next);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual(events[0].intent, 'model.load');
+    if (events[0].intent === 'model.load') {
+      assert.strictEqual(events[0].params.schema, 'IFC4');
+      assert.strictEqual(events[0].params.entityCount, 100);
+      assert.strictEqual(events[0].params.sizeBytes, 5000);
+    }
+  });
+
+  it('emits model.unload when a model is removed', () => {
+    const prev = makeState({
+      models: new Map([['m1', { schemaVersion: 'IFC4', ifcDataStore: null, fileSize: 0 }]]),
+    });
+    const next = makeState();
+    const events = detectActions(prev, next);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual(events[0].intent, 'model.unload');
+  });
+
+  it('emits both load and unload on a same-size swap', () => {
+    const prev = makeState({
+      models: new Map([['old', { schemaVersion: 'IFC4', ifcDataStore: null, fileSize: 0 }]]),
+    });
+    const next = makeState({
+      models: new Map([['new', { schemaVersion: 'IFC4', ifcDataStore: null, fileSize: 0 }]]),
+    });
+    const events = detectActions(prev, next);
+    const intents = events.map((e) => e.intent).sort();
+    assert.deepStrictEqual(intents, ['model.load', 'model.unload']);
+  });
+
+  it('hashes lens ids before emitting lens.apply', () => {
+    const prev = makeState();
+    const next = makeState({ activeLensId: "John's basement" });
+    const events = detectActions(prev, next);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual(events[0].intent, 'lens.apply');
+    if (events[0].intent === 'lens.apply') {
+      assert.ok(!events[0].params.id?.includes('John'));
+      assert.match(events[0].params.id ?? '', /^lens-/);
+    }
+  });
+
+  it('emits lens.clear when lens is unset', () => {
+    const prev = makeState({ activeLensId: 'foo' });
+    const next = makeState({ activeLensId: null });
+    const events = detectActions(prev, next);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual(events[0].intent, 'lens.clear');
+  });
+
+  it('emits selection.change only on count delta', () => {
+    const prev = makeState({ selectedEntities: [1, 2, 3] });
+    const next = makeState({ selectedEntities: [1, 2, 3] }); // same count
+    assert.strictEqual(detectActions(prev, next).length, 0);
+
+    const next2 = makeState({ selectedEntities: [1, 2] });
+    const events = detectActions(prev, next2);
+    assert.strictEqual(events.length, 1);
+    if (events[0].intent === 'selection.change') {
+      assert.strictEqual(events[0].params.count, 2);
+    }
+  });
+
+  it('emits section.apply on enable transition only', () => {
+    // false → true emits.
+    const prev = makeState({ sectionPlane: { enabled: false } });
+    const next = makeState({ sectionPlane: { enabled: true } });
+    assert.strictEqual(detectActions(prev, next).length, 1);
+    // true → true does not emit.
+    const events = detectActions(next, next);
+    assert.strictEqual(events.length, 0);
+  });
+
+  it('emits view.change on 2d/3d mode flip', () => {
+    const prev = makeState({ drawing2DPanelVisible: false });
+    const next = makeState({ drawing2DPanelVisible: true });
+    const events = detectActions(prev, next);
+    assert.strictEqual(events.length, 1);
+    assert.strictEqual(events[0].intent, 'view.change');
+    if (events[0].intent === 'view.change') {
+      assert.strictEqual(events[0].params.mode, '2d');
+    }
+  });
+
+  it('emits exactly one event per unique transition (no duplicates)', () => {
+    const prev = makeState();
+    const next = makeState({
+      models: new Map([['m1', { schemaVersion: 'IFC4', ifcDataStore: null, fileSize: 0 }]]),
+      activeLensId: 'lens-1',
+      selectedEntities: [1],
+      sectionPlane: { enabled: true },
+      drawing2DPanelVisible: true,
+    });
+    const events = detectActions(prev, next);
+    const intents = events.map((e) => e.intent).sort();
+    assert.deepStrictEqual(
+      intents,
+      ['lens.apply', 'model.load', 'section.apply', 'selection.change', 'view.change'],
+    );
+  });
+
+  it('returns an empty array when state is identical', () => {
+    const state = makeState({
+      models: new Map([['m1', { schemaVersion: 'IFC4', ifcDataStore: null, fileSize: 0 }]]),
+      activeLensId: 'lens-1',
+      selectedEntities: [1],
+      sectionPlane: { enabled: true },
+      drawing2DPanelVisible: true,
+    });
+    assert.strictEqual(detectActions(state, state).length, 0);
+  });
+});

package/src/hooks/useActionLogger.ts

@@ -0,0 +1,141 @@
+/* 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/. */
+
+/**
+ * `useActionLogger` — bridge the viewer store to the extension action log.
+ *
+ * Subscribes to store transitions on a handful of key fields and emits
+ * content-free `ActionEvent`s through `host.emitAction(...)`. The
+ * miner consumes these to suggest one-click tools.
+ *
+ * Wired once at the top of the app (under `<ExtensionHostProvider>`).
+ * Intentionally selective — we only log intents the miner can act on,
+ * never raw payload content (no entity names, no chat text, no file
+ * names). Per spec §06 §7, the action log NEVER sees user content.
+ *
+ * Spec: docs/architecture/ai-customization/06-self-improvement.md §2.
+ */
+
+import { useEffect } from 'react';
+import type { ActionIntent, ActionParams } from '@ifc-lite/extensions';
+import { useOptionalExtensionHost } from '@/sdk/ExtensionHostProvider';
+import { useViewerStore } from '@/store';
+
+/**
+ * Shape we read from the viewer store. Narrowed to just the fields
+ * `detectActions` consumes so the function is unit-testable without
+ * importing the full store type.
+ */
+export interface ActionLoggerStateShape {
+  models: ReadonlyMap<string, { schemaVersion: string; ifcDataStore: { entityCount?: number } | null; fileSize: number }>;
+  activeLensId: string | null;
+  selectedEntities: readonly unknown[];
+  sectionPlane?: { enabled?: boolean };
+  drawing2DPanelVisible?: boolean;
+}
+
+export type EmittedAction = {
+  [K in ActionIntent]: { intent: K; params: ActionParams[K] };
+}[ActionIntent];
+
+/**
+ * Pure transition detector. Given the prior and next store states,
+ * returns the list of action events to emit. Extracted so the
+ * transition logic can be tested without a React renderer.
+ */
+export function detectActions(
+  prev: ActionLoggerStateShape,
+  state: ActionLoggerStateShape,
+): EmittedAction[] {
+  const out: EmittedAction[] = [];
+  // model.load / model.unload — compare by id so a swap (same size)
+  // still emits both events.
+  for (const [id, model] of state.models) {
+    if (!prev.models.has(id)) {
+      out.push({
+        intent: 'model.load',
+        params: {
+          schema: model.schemaVersion,
+          entityCount: model.ifcDataStore?.entityCount,
+          sizeBytes: model.fileSize,
+        },
+      });
+    }
+  }
+  for (const id of prev.models.keys()) {
+    if (!state.models.has(id)) {
+      out.push({ intent: 'model.unload', params: {} });
+    }
+  }
+  // lens.apply / lens.clear — hashed id only.
+  if (state.activeLensId !== prev.activeLensId) {
+    if (state.activeLensId) {
+      out.push({ intent: 'lens.apply', params: { id: hashLensId(state.activeLensId) } });
+    } else {
+      out.push({ intent: 'lens.clear', params: {} });
+    }
+  }
+  // selection.change — count delta only.
+  const prevCount = prev.selectedEntities?.length ?? 0;
+  const nextCount = state.selectedEntities?.length ?? 0;
+  if (prevCount !== nextCount) {
+    out.push({ intent: 'selection.change', params: { count: nextCount } });
+  }
+  // section.apply — enable transition only.
+  const prevSection = prev.sectionPlane?.enabled ?? false;
+  const nextSection = state.sectionPlane?.enabled ?? false;
+  if (!prevSection && nextSection) {
+    out.push({ intent: 'section.apply', params: {} });
+  }
+  // view.change — 2d/3d mode flip (proxied via drawing2D panel).
+  const prevMode = prev.drawing2DPanelVisible ? '2d' : '3d';
+  const nextMode = state.drawing2DPanelVisible ? '2d' : '3d';
+  if (prevMode !== nextMode) {
+    out.push({ intent: 'view.change', params: { mode: nextMode } });
+  }
+  return out;
+}
+
+export function useActionLogger(): void {
+  const host = useOptionalExtensionHost();
+
+  useEffect(() => {
+    if (!host) return;
+
+    // Snapshot the prior state per field so we can detect transitions
+    // rather than emit on every render. We use the public subscribe
+    // method since the store is a vanilla zustand instance.
+    let prev = useViewerStore.getState() as unknown as ActionLoggerStateShape;
+
+    const unsubscribe = useViewerStore.subscribe((state) => {
+      const next = state as unknown as ActionLoggerStateShape;
+      for (const event of detectActions(prev, next)) {
+        // TypeScript can't pair `event.intent` (discriminated union)
+        // with emitAction's `<K extends ActionIntent>` generic across
+        // an iterator. The pairing is provably correct — every
+        // EmittedAction is built from a matching `(intent, params)`
+        // pair in detectActions — so the runtime call is type-safe
+        // even though the inferencer can't see it.
+        host.emitAction(event.intent, event.params as never);
+      }
+      prev = next;
+    });
+
+    return unsubscribe;
+  }, [host]);
+}
+
+/**
+ * Project a lens id into a short stable token so the action log never
+ * carries the original string. We only need identity for the miner;
+ * djb2 is plenty for 30-50 distinct lenses per user.
+ */
+export function hashLensId(id: string): string {
+  let hash = 5381;
+  for (let i = 0; i < id.length; i++) {
+    hash = ((hash << 5) + hash + id.charCodeAt(i)) | 0;
+  }
+  // Unsigned 32-bit hex — 8 chars, stable, opaque.
+  return `lens-${(hash >>> 0).toString(16).padStart(8, '0')}`;
+}