@ifc-lite/viewer 1.7.0 → 1.9.0

package/src/components/viewer/Viewport.tsx

@@ -9,7 +9,7 @@
 import { useCallback, useEffect, useRef, useState, useMemo } from 'react';
 import { Renderer } from '@ifc-lite/renderer';
 import type { MeshData, CoordinateInfo } from '@ifc-lite/geometry';
-import { useViewerStore, type MeasurePoint, type SnapVisualization } from '@/store';
+import { useViewerStore, resolveEntityRef, type MeasurePoint, type SnapVisualization } from '@/store';
 import {
   useSelectionState,
   useVisibilityState,
@@ -53,8 +53,8 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
   // Selection state
   const { selectedEntityId, selectedEntityIds, setSelectedEntityId, setSelectedEntity, toggleSelection, models } = useSelectionState();
   const selectedEntity = useViewerStore((s) => s.selectedEntity);
-  // Get the bulletproof store-based resolver (more reliable than singleton)
-  const resolveGlobalIdFromModels = useViewerStore((s) => s.resolveGlobalIdFromModels);
+  const addEntityToSelection = useViewerStore((s) => s.addEntityToSelection);
+  const toggleEntitySelection = useViewerStore((s) => s.toggleEntitySelection);
 
   // Sync selectedEntityId with model-aware selectedEntity for PropertiesPanel
   useModelSelection();
@@ -76,9 +76,14 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
 
   // Helper to handle pick result and set selection properly
   // IMPORTANT: pickResult.expressId is now a globalId (transformed at load time)
-  // We use the store-based resolver to find (modelId, originalExpressId)
-  // This is more reliable than the singleton registry which can have bundling issues
+  // resolveEntityRef is the single source of truth for globalId → EntityRef
   const handlePickForSelection = useCallback((pickResult: import('@ifc-lite/renderer').PickResult | null) => {
+    // Normal click clears multi-select set (fresh single-selection)
+    const currentState = useViewerStore.getState();
+    if (currentState.selectedEntitiesSet.size > 0) {
+      useViewerStore.setState({ selectedEntitiesSet: new Set(), selectedEntityIds: new Set() });
+    }
+
     if (!pickResult) {
       setSelectedEntityId(null);
       return;
@@ -89,29 +94,58 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
     // Set globalId for renderer (highlighting uses globalIds directly)
     setSelectedEntityId(globalId);
 
-    // Resolve globalId -> (modelId, originalExpressId) for property panel
-    // Use store-based resolver instead of singleton for reliability
-    const resolved = resolveGlobalIdFromModels(globalId);
-    if (resolved) {
-      // Set the EntityRef with ORIGINAL expressId (for property lookup in IfcDataStore)
-      setSelectedEntity({ modelId: resolved.modelId, expressId: resolved.expressId });
-    } else {
-      // Fallback for single-model mode (offset = 0, globalId = expressId)
-      // Try to find model from the old modelIndex if available
-      if (pickResult.modelIndex !== undefined && modelIndexToId) {
-        const modelId = modelIndexToId.get(pickResult.modelIndex);
-        if (modelId) {
-          setSelectedEntity({ modelId, expressId: globalId });
-        }
-      }
-    }
-  }, [setSelectedEntityId, setSelectedEntity, resolveGlobalIdFromModels, modelIndexToId]);
+    // Resolve globalId → EntityRef for property panel (single source of truth, never null)
+    setSelectedEntity(resolveEntityRef(globalId));
+  }, [setSelectedEntityId, setSelectedEntity]);
 
   // Ref to always access latest handlePickForSelection from event handlers
   // (useMouseControls/useTouchControls capture this at effect setup time)
   const handlePickForSelectionRef = useRef(handlePickForSelection);
   useEffect(() => { handlePickForSelectionRef.current = handlePickForSelection; }, [handlePickForSelection]);
 
+  // Multi-select handler: Ctrl+Click adds/removes from multi-selection
+  // Properly populates both selectedEntitiesSet (multi-model) and selectedEntityIds (legacy)
+  const handleMultiSelect = useCallback((globalId: number) => {
+    // Resolve globalId → EntityRef (single source of truth, never null)
+    const entityRef = resolveEntityRef(globalId);
+
+    // If this is the first Ctrl+click and there's already a single-selected entity,
+    // add it to the multi-select set first (so it's not lost)
+    const state = useViewerStore.getState();
+    if (state.selectedEntitiesSet.size === 0 && state.selectedEntity) {
+      addEntityToSelection(state.selectedEntity);
+      // Also seed legacy selectedEntityIds with previous entity's globalId
+      // so the renderer highlights both the old and new entity
+      if (state.selectedEntityId !== null) {
+        toggleSelection(state.selectedEntityId);
+      }
+    }
+
+    // Toggle the clicked entity in multi-select
+    toggleEntitySelection(entityRef);
+
+    // Also sync legacy selectedEntityIds and selectedEntityId
+    toggleSelection(globalId);
+
+    // Read post-toggle state to keep renderer highlighting in sync:
+    // If the entity was toggled OFF, don't force-highlight it.
+    const updated = useViewerStore.getState();
+    if (updated.selectedEntityIds.has(globalId)) {
+      // Entity was toggled ON — highlight it
+      setSelectedEntityId(globalId);
+    } else if (updated.selectedEntityIds.size > 0) {
+      // Entity was toggled OFF but others remain — highlight the last remaining
+      const remaining = Array.from(updated.selectedEntityIds);
+      setSelectedEntityId(remaining[remaining.length - 1]);
+    } else {
+      // Nothing left selected
+      setSelectedEntityId(null);
+    }
+  }, [addEntityToSelection, toggleEntitySelection, toggleSelection, setSelectedEntityId]);
+
+  const handleMultiSelectRef = useRef(handleMultiSelect);
+  useEffect(() => { handleMultiSelectRef.current = handleMultiSelect; }, [handleMultiSelect]);
+
   // Visibility state - use computedIsolatedIds from parent (includes storey selection)
   // Fall back to store isolation if computedIsolatedIds is not provided
   const { hiddenEntities, isolatedEntities: storeIsolatedEntities } = useVisibilityState();
@@ -668,7 +702,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
     updateConstraintActiveAxis,
     updateMeasurementScreenCoords,
     updateCameraRotationRealtime,
-    toggleSelection,
+    toggleSelection: (entityId: number) => handleMultiSelectRef.current(entityId),
     calculateScale,
     getPickOptions,
     hasPendingMeasurements,
@@ -749,6 +783,7 @@ export function Viewport({ geometry, coordinateInfo, computedIsolatedIds, modelI
     geometryBoundsRef,
     pendingColorUpdates,
     clearPendingColorUpdates,
+    clearColorRef,
   });
 
   useRenderUpdates({

package/src/components/viewer/ViewportContainer.tsx

@@ -317,6 +317,7 @@ export function ViewportContainer() {
     return (
       <div
         className="relative h-full w-full bg-white dark:bg-black text-zinc-900 dark:text-zinc-50 overflow-hidden"
+        data-viewport
         onDragOver={handleDragOver}
         onDragLeave={handleDragLeave}
         onDrop={handleDrop}
@@ -556,6 +557,7 @@ export function ViewportContainer() {
   return (
     <div
       className="relative h-full w-full bg-zinc-50 dark:bg-black overflow-hidden"
+      data-viewport
       onDragOver={handleDragOver}
       onDragLeave={handleDragLeave}
       onDrop={handleDrop}

package/src/components/viewer/hierarchy/HierarchyNode.tsx

@@ -267,7 +267,7 @@ export function HierarchyNode({
         {/* Name */}
         <span className={cn(
           'flex-1 text-sm truncate ml-1.5',
-          isSpatialContainer(node.type)
+          isSpatialContainer(node.type) || node.type === 'IfcBuildingStorey' || node.type === 'unified-storey' || node.type === 'type-group'
             ? 'font-medium text-zinc-900 dark:text-zinc-100'
             : 'text-zinc-700 dark:text-zinc-300',
           nodeHidden && 'line-through decoration-zinc-400 dark:decoration-zinc-600'

package/src/components/viewer/hierarchy/types.ts

@@ -10,7 +10,7 @@ export type NodeType =
   | 'IfcSite'             // Site node
   | 'IfcBuilding'         // Building node
   | 'IfcBuildingStorey'   // Storey node
-  | 'type-group'          // IFC type grouping header (e.g., "IfcWall (47)")
+  | 'type-group'          // IFC class grouping header (e.g., "IfcWall (47)")
   | 'element';            // Individual element
 
 export interface TreeNode {

package/src/components/viewer/lists/ListResultsTable.tsx

@@ -12,11 +12,13 @@
 
 import React, { useCallback, useMemo, useRef, useState } from 'react';
 import { useVirtualizer } from '@tanstack/react-virtual';
-import { ArrowUp, ArrowDown, Search } from 'lucide-react';
+import { ArrowUp, ArrowDown, Search, Palette } from 'lucide-react';
 import { Input } from '@/components/ui/input';
 import { useViewerStore } from '@/store';
-import type { ListResult, ListRow, CellValue } from '@ifc-lite/lists';
+import type { ListResult, ListRow, CellValue, ColumnDefinition } from '@ifc-lite/lists';
 import { cn } from '@/lib/utils';
+import { columnToAutoColor } from '@/lib/lists/columnToAutoColor';
+import { AUTO_COLOR_FROM_LIST_ID } from '@/store/slices/lensSlice';
 
 interface ListResultsTableProps {
   result: ListResult;
@@ -31,6 +33,9 @@ export function ListResultsTable({ result }: ListResultsTableProps) {
   const setSelectedEntityId = useViewerStore((s) => s.setSelectedEntityId);
   const setSelectedEntity = useViewerStore((s) => s.setSelectedEntity);
   const selectedEntityId = useViewerStore((s) => s.selectedEntityId);
+  const activateAutoColorFromColumn = useViewerStore((s) => s.activateAutoColorFromColumn);
+  const activeLensId = useViewerStore((s) => s.activeLensId);
+  const [colorByColIdx, setColorByColIdx] = useState<number | null>(null);
 
   // Filter rows by search query
   const filteredRows = useMemo(() => {
@@ -62,6 +67,13 @@ export function ListResultsTable({ result }: ListResultsTableProps) {
     }
   }, [sortCol]);
 
+  const handleColorByColumn = useCallback((col: ColumnDefinition, colIdx: number) => {
+    const spec = columnToAutoColor(col);
+    const label = col.label ?? col.propertyName;
+    activateAutoColorFromColumn(spec, label);
+    setColorByColIdx(colIdx);
+  }, [activateAutoColorFromColumn]);
+
   const handleRowClick = useCallback((row: ListRow) => {
     setSelectedEntity({ modelId: row.modelId, expressId: row.entityId });
     // For single-model, selectedEntityId is the expressId
@@ -108,23 +120,45 @@ export function ListResultsTable({ result }: ListResultsTableProps) {
         <div style={{ minWidth: totalWidth }}>
           {/* Header */}
           <div className="flex sticky top-0 bg-muted/80 backdrop-blur-sm border-b z-10">
-            {result.columns.map((col, colIdx) => (
-              <button
-                key={col.id}
-                className="flex items-center gap-1 px-2 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground border-r border-border/50 shrink-0"
-                style={{ width: columnWidths[colIdx] }}
-                onClick={() => handleHeaderClick(colIdx)}
-              >
-                <span className="truncate">
-                  {col.label ?? col.propertyName}
-                </span>
-                {sortCol === colIdx && (
-                  sortDir === 'asc'
-                    ? <ArrowUp className="h-3 w-3 shrink-0" />
-                    : <ArrowDown className="h-3 w-3 shrink-0" />
-                )}
-              </button>
-            ))}
+            {result.columns.map((col, colIdx) => {
+              const isColoredCol = activeLensId === AUTO_COLOR_FROM_LIST_ID && colorByColIdx === colIdx;
+              return (
+                <div
+                  key={col.id}
+                  className={cn(
+                    'flex items-center gap-0.5 px-2 py-1.5 text-xs font-medium text-muted-foreground border-r border-border/50 shrink-0 group/col',
+                    isColoredCol && 'bg-primary/10',
+                  )}
+                  style={{ width: columnWidths[colIdx] }}
+                >
+                  <button
+                    className="flex items-center gap-1 flex-1 min-w-0 hover:text-foreground"
+                    onClick={() => handleHeaderClick(colIdx)}
+                  >
+                    <span className="truncate">
+                      {col.label ?? col.propertyName}
+                    </span>
+                    {sortCol === colIdx && (
+                      sortDir === 'asc'
+                        ? <ArrowUp className="h-3 w-3 shrink-0" />
+                        : <ArrowDown className="h-3 w-3 shrink-0" />
+                    )}
+                  </button>
+                  <button
+                    className={cn(
+                      'shrink-0 p-0.5 rounded-sm transition-opacity',
+                      isColoredCol
+                        ? 'text-primary opacity-100'
+                        : 'opacity-0 group-hover/col:opacity-100 text-muted-foreground hover:text-primary',
+                    )}
+                    onClick={(e) => { e.stopPropagation(); handleColorByColumn(col, colIdx); }}
+                    title={`Color by ${col.label ?? col.propertyName}`}
+                  >
+                    <Palette className="h-3 w-3" />
+                  </button>
+                </div>
+              );
+            })}
           </div>
 
           {/* Virtualized rows */}

package/src/components/viewer/tools/cloudPathGenerator.test.ts

@@ -0,0 +1,118 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { generateCloudArcs, generateCloudSVGPath } from './cloudPathGenerator.js';
+
+describe('generateCloudArcs', () => {
+  it('generates arcs for a simple rectangle', () => {
+    const arcs = generateCloudArcs(
+      { x: 0, y: 0 },
+      { x: 4, y: 2 },
+      0.5 // arcRadius
+    );
+    // Should produce arcs along all 4 edges
+    assert.ok(arcs.length > 0, 'Should generate at least some arcs');
+  });
+
+  it('produces arcs proportional to edge length', () => {
+    // A 4x2 rectangle with arcRadius=1 (diameter=2)
+    // Top edge (4 units): ~2 arcs
+    // Right edge (2 units): ~1 arc
+    // Bottom edge (4 units): ~2 arcs
+    // Left edge (2 units): ~1 arc
+    // Total: ~6 arcs
+    const arcs = generateCloudArcs(
+      { x: 0, y: 0 },
+      { x: 4, y: 2 },
+      1.0
+    );
+    assert.strictEqual(arcs.length, 6);
+  });
+
+  it('handles equal corners (zero-size rectangle) gracefully', () => {
+    const arcs = generateCloudArcs(
+      { x: 1, y: 1 },
+      { x: 1, y: 1 },
+      0.5
+    );
+    // All edges are zero-length, should skip them
+    assert.strictEqual(arcs.length, 0);
+  });
+
+  it('handles reversed corner order', () => {
+    const arcs1 = generateCloudArcs({ x: 0, y: 0 }, { x: 4, y: 2 }, 1.0);
+    const arcs2 = generateCloudArcs({ x: 4, y: 2 }, { x: 0, y: 0 }, 1.0);
+    // Should produce same number of arcs regardless of corner order
+    assert.strictEqual(arcs1.length, arcs2.length);
+  });
+
+  it('each arc has valid start, end, center, and radius', () => {
+    const arcs = generateCloudArcs({ x: 0, y: 0 }, { x: 2, y: 2 }, 0.5);
+    for (const arc of arcs) {
+      assert.ok(isFinite(arc.start.x) && isFinite(arc.start.y), 'Start should be finite');
+      assert.ok(isFinite(arc.end.x) && isFinite(arc.end.y), 'End should be finite');
+      assert.ok(isFinite(arc.center.x) && isFinite(arc.center.y), 'Center should be finite');
+      assert.ok(arc.radius > 0, 'Radius should be positive');
+      assert.ok(isFinite(arc.startAngle), 'Start angle should be finite');
+      assert.ok(isFinite(arc.endAngle), 'End angle should be finite');
+    }
+  });
+});
+
+describe('generateCloudSVGPath', () => {
+  it('generates a valid SVG path string', () => {
+    const path = generateCloudSVGPath(
+      { x: 0, y: 0 },
+      { x: 4, y: 2 },
+      1.0,
+      (x) => x,
+      (y) => y,
+    );
+    assert.ok(path.startsWith('M'), 'Path should start with M command');
+    assert.ok(path.includes('A'), 'Path should contain arc commands');
+    assert.ok(path.endsWith('Z'), 'Path should end with Z (close)');
+  });
+
+  it('uses clockwise sweep flag (1) for outward-bulging arcs', () => {
+    const path = generateCloudSVGPath(
+      { x: 0, y: 0 },
+      { x: 4, y: 2 },
+      1.0,
+      (x) => x,
+      (y) => y,
+    );
+    // All arcs should use sweep-flag=1 (clockwise = outward bulge)
+    const arcMatches = path.match(/A\s+[\d.]+\s+[\d.]+\s+0\s+0\s+(\d)/g);
+    assert.ok(arcMatches && arcMatches.length > 0, 'Should have arc commands');
+    for (const match of arcMatches!) {
+      assert.ok(match.endsWith('1'), `Arc sweep flag should be 1 (clockwise/outward), got: ${match}`);
+    }
+  });
+
+  it('applies coordinate transforms', () => {
+    // Flip X
+    const path = generateCloudSVGPath(
+      { x: 1, y: 0 },
+      { x: 3, y: 2 },
+      0.5,
+      (x) => -x,
+      (y) => y,
+    );
+    assert.ok(path.includes('-'), 'Flipped X should produce negative coordinates');
+  });
+
+  it('handles small rectangles', () => {
+    const path = generateCloudSVGPath(
+      { x: 0, y: 0 },
+      { x: 0.1, y: 0.1 },
+      0.02,
+      (x) => x,
+      (y) => y,
+    );
+    assert.ok(path.length > 0, 'Should produce a non-empty path');
+    assert.ok(path.endsWith('Z'), 'Path should be closed');
+  });
+});

package/src/components/viewer/tools/cloudPathGenerator.ts

@@ -0,0 +1,275 @@
+/* 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/. */
+
+/**
+ * Revision cloud (scalloped border) path generation.
+ * Generates arc data for drawing cloud annotations on a canvas or SVG.
+ */
+
+interface Point2D {
+  x: number;
+  y: number;
+}
+
+/** A single arc segment in the cloud border */
+export interface CloudArc {
+  /** Start point of the arc */
+  start: Point2D;
+  /** End point of the arc */
+  end: Point2D;
+  /** Center of the arc circle */
+  center: Point2D;
+  /** Radius of the arc */
+  radius: number;
+  /** Start angle in radians */
+  startAngle: number;
+  /** End angle in radians */
+  endAngle: number;
+}
+
+/**
+ * Generate cloud arc data from two rectangle corner points.
+ * The two points define opposite corners of the rectangle.
+ * Arcs bulge outward from the rectangle edges.
+ *
+ * @param p1 First corner (e.g. top-left)
+ * @param p2 Second corner (e.g. bottom-right)
+ * @param arcRadius Radius of each scallop arc in drawing coords
+ * @returns Array of arc segments forming the cloud border
+ */
+export function generateCloudArcs(
+  p1: Point2D,
+  p2: Point2D,
+  arcRadius: number
+): CloudArc[] {
+  // Build rectangle corners in clockwise order
+  const minX = Math.min(p1.x, p2.x);
+  const maxX = Math.max(p1.x, p2.x);
+  const minY = Math.min(p1.y, p2.y);
+  const maxY = Math.max(p1.y, p2.y);
+
+  const corners: Point2D[] = [
+    { x: minX, y: minY }, // top-left (in drawing coords, Y increases downward on screen)
+    { x: maxX, y: minY }, // top-right
+    { x: maxX, y: maxY }, // bottom-right
+    { x: minX, y: maxY }, // bottom-left
+  ];
+
+  const arcs: CloudArc[] = [];
+
+  // For each edge, generate scallop arcs
+  for (let i = 0; i < corners.length; i++) {
+    const edgeStart = corners[i];
+    const edgeEnd = corners[(i + 1) % corners.length];
+
+    const dx = edgeEnd.x - edgeStart.x;
+    const dy = edgeEnd.y - edgeStart.y;
+    const edgeLength = Math.sqrt(dx * dx + dy * dy);
+
+    if (edgeLength < 0.001) continue;
+
+    // Number of arcs along this edge
+    const arcDiameter = arcRadius * 2;
+    const arcCount = Math.max(1, Math.round(edgeLength / arcDiameter));
+    const segmentLength = edgeLength / arcCount;
+    const actualRadius = segmentLength / 2;
+
+    // Unit direction along edge
+    const ux = dx / edgeLength;
+    const uy = dy / edgeLength;
+
+    // Outward normal (perpendicular, pointing outward from rectangle)
+    // For clockwise winding, outward normal is to the right of the edge direction
+    const nx = uy;
+    const ny = -ux;
+
+    for (let j = 0; j < arcCount; j++) {
+      const t0 = j / arcCount;
+      const t1 = (j + 1) / arcCount;
+
+      const arcStart: Point2D = {
+        x: edgeStart.x + dx * t0,
+        y: edgeStart.y + dy * t0,
+      };
+      const arcEnd: Point2D = {
+        x: edgeStart.x + dx * t1,
+        y: edgeStart.y + dy * t1,
+      };
+
+      // Center of the arc is offset outward from the midpoint
+      const midX = (arcStart.x + arcEnd.x) / 2;
+      const midY = (arcStart.y + arcEnd.y) / 2;
+
+      // The arc center is at the midpoint of the segment (on the edge)
+      // The arc bulges outward by the radius amount
+      const center: Point2D = {
+        x: midX,
+        y: midY,
+      };
+
+      // Compute angles from center to start and end
+      const startAngle = Math.atan2(arcStart.y - center.y, arcStart.x - center.x);
+      const endAngle = Math.atan2(arcEnd.y - center.y, arcEnd.x - center.x);
+
+      arcs.push({
+        start: arcStart,
+        end: arcEnd,
+        center,
+        radius: actualRadius,
+        startAngle,
+        endAngle,
+      });
+    }
+  }
+
+  return arcs;
+}
+
+/**
+ * Draw cloud arcs on a Canvas 2D context.
+ * Arcs are drawn as semicircular bumps bulging outward.
+ */
+export function drawCloudOnCanvas(
+  ctx: CanvasRenderingContext2D,
+  p1: Point2D,
+  p2: Point2D,
+  arcRadius: number,
+  toScreenX: (x: number) => number,
+  toScreenY: (y: number) => number,
+  screenScale: number
+): void {
+  const minX = Math.min(p1.x, p2.x);
+  const maxX = Math.max(p1.x, p2.x);
+  const minY = Math.min(p1.y, p2.y);
+  const maxY = Math.max(p1.y, p2.y);
+
+  const corners: Point2D[] = [
+    { x: minX, y: minY },
+    { x: maxX, y: minY },
+    { x: maxX, y: maxY },
+    { x: minX, y: maxY },
+  ];
+
+  ctx.beginPath();
+
+  for (let i = 0; i < corners.length; i++) {
+    const edgeStart = corners[i];
+    const edgeEnd = corners[(i + 1) % corners.length];
+
+    const dx = edgeEnd.x - edgeStart.x;
+    const dy = edgeEnd.y - edgeStart.y;
+    const edgeLength = Math.sqrt(dx * dx + dy * dy);
+
+    if (edgeLength < 0.001) continue;
+
+    const arcDiameter = arcRadius * 2;
+    const arcCount = Math.max(1, Math.round(edgeLength / arcDiameter));
+    const actualRadius = (edgeLength / arcCount) / 2;
+
+    // Unit direction along edge
+    const ux = dx / edgeLength;
+    const uy = dy / edgeLength;
+
+    // Outward normal for clockwise winding
+    const nx = uy;
+    const ny = -ux;
+
+    for (let j = 0; j < arcCount; j++) {
+      const t0 = j / arcCount;
+      const t1 = (j + 1) / arcCount;
+
+      const sx = edgeStart.x + dx * t0;
+      const sy = edgeStart.y + dy * t0;
+      const ex = edgeStart.x + dx * t1;
+      const ey = edgeStart.y + dy * t1;
+
+      // Arc center is on the edge at midpoint
+      const cx = (sx + ex) / 2;
+      const cy = (sy + ey) / 2;
+
+      // Convert to screen coords
+      const scx = toScreenX(cx);
+      const scy = toScreenY(cy);
+      const screenRadius = actualRadius * screenScale;
+
+      // Angles in screen space (Y may be flipped)
+      const ssx = toScreenX(sx);
+      const ssy = toScreenY(sy);
+      const sex = toScreenX(ex);
+      const sey = toScreenY(ey);
+
+      const startAngle = Math.atan2(ssy - scy, ssx - scx);
+      const endAngle = Math.atan2(sey - scy, sex - scx);
+
+      // Draw arc clockwise (false) so the semicircle bulges outward from the rectangle
+      ctx.arc(scx, scy, screenRadius, startAngle, endAngle, false);
+    }
+  }
+
+  ctx.closePath();
+}
+
+/**
+ * Generate SVG path data for a cloud annotation.
+ */
+export function generateCloudSVGPath(
+  p1: Point2D,
+  p2: Point2D,
+  arcRadius: number,
+  transformX: (x: number) => number,
+  transformY: (y: number) => number,
+): string {
+  const minX = Math.min(p1.x, p2.x);
+  const maxX = Math.max(p1.x, p2.x);
+  const minY = Math.min(p1.y, p2.y);
+  const maxY = Math.max(p1.y, p2.y);
+
+  const corners: Point2D[] = [
+    { x: minX, y: minY },
+    { x: maxX, y: minY },
+    { x: maxX, y: maxY },
+    { x: minX, y: maxY },
+  ];
+
+  let path = '';
+
+  for (let i = 0; i < corners.length; i++) {
+    const edgeStart = corners[i];
+    const edgeEnd = corners[(i + 1) % corners.length];
+
+    const dx = edgeEnd.x - edgeStart.x;
+    const dy = edgeEnd.y - edgeStart.y;
+    const edgeLength = Math.sqrt(dx * dx + dy * dy);
+
+    if (edgeLength < 0.001) continue;
+
+    const arcDiameter = arcRadius * 2;
+    const arcCount = Math.max(1, Math.round(edgeLength / arcDiameter));
+    const segmentLength = edgeLength / arcCount;
+    const r = segmentLength / 2;
+
+    for (let j = 0; j < arcCount; j++) {
+      const t0 = j / arcCount;
+      const t1 = (j + 1) / arcCount;
+
+      const sx = transformX(edgeStart.x + (edgeEnd.x - edgeStart.x) * t0);
+      const sy = transformY(edgeStart.y + (edgeEnd.y - edgeStart.y) * t0);
+      const ex = transformX(edgeStart.x + (edgeEnd.x - edgeStart.x) * t1);
+      const ey = transformY(edgeStart.y + (edgeEnd.y - edgeStart.y) * t1);
+
+      // Move to start of first arc
+      if (i === 0 && j === 0) {
+        path += `M ${sx.toFixed(4)} ${sy.toFixed(4)}`;
+      }
+
+      // SVG arc: A rx ry x-rotation large-arc-flag sweep-flag x y
+      // sweep-flag=1 for clockwise (outward bulge from rectangle)
+      const trR = Math.sqrt((ex - sx) ** 2 + (ey - sy) ** 2) / 2;
+      path += ` A ${trR.toFixed(4)} ${trR.toFixed(4)} 0 0 1 ${ex.toFixed(4)} ${ey.toFixed(4)}`;
+    }
+  }
+
+  path += ' Z';
+  return path;
+}