@dfosco/storyboard-react 4.2.0-beta.4 → 4.2.1

package/src/canvas/CanvasPage.jsx

@@ -6,11 +6,16 @@ import { shouldPreventCanvasTextSelection } from './textSelection.js'
 import { getCanvasThemeVars, getCanvasPrimerAttrs } from './canvasTheme.js'
 import { getWidgetComponent } from './widgets/index.js'
 import { schemas, getDefaults } from './widgets/widgetProps.js'
-import { getFeatures, isResizable, getAnchorState, canAcceptConnection } from './widgets/widgetConfig.js'
+import { getFeatures, isResizable, isExpandable, getAnchorState, canAcceptConnection, isSplitScreenCapable } from './widgets/widgetConfig.js'
 import { createPasteContext, resolvePaste } from './widgets/pasteRules.js'
 import { getPasteRules } from '@dfosco/storyboard-core'
+import { isTerminalResizable, getTerminalDimensions } from '@dfosco/storyboard-core'
+import { getFlag } from '@dfosco/storyboard-core'
+import { getCanvasZoom } from '@dfosco/storyboard-core'
 import { registerSmoothCorners } from '@dfosco/storyboard-core/smooth-corners'
+import { registerHotPoolDevLogs } from './hotPoolDevLogs.js'
 import { isGitHubEmbedUrl } from './widgets/githubUrl.js'
+
 import WidgetChrome from './widgets/WidgetChrome.jsx'
 import ComponentWidget from './widgets/ComponentWidget.jsx'
 import useUndoRedo from './useUndoRedo.js'
@@ -19,6 +24,7 @@ import MarqueeOverlay from './MarqueeOverlay.jsx'
 import {
   addWidget as addWidgetApi,
   checkGitHubCliAvailable,
+  duplicateImage,
   fetchGitHubEmbed,
   getCanvas as getCanvasApi,
   removeWidget as removeWidgetApi,
@@ -27,6 +33,8 @@ import {
   uploadImage,
   addConnector as addConnectorApi,
   removeConnector as removeConnectorApi,
+  updateConnector as updateConnectorApi,
+  batchOperations,
 } from './canvasApi.js'
 import PageSelector from './PageSelector.jsx'
 import Icon from '../Icon.jsx'
@@ -34,8 +42,11 @@ import { stories as storyIndex } from 'virtual:storyboard-data-index'
 import styles from './CanvasPage.module.css'
 import ConnectorLayer from './ConnectorLayer.jsx'
 
-const ZOOM_MIN = 25
-const ZOOM_MAX = 200
+/** Canvas zoom limits — read from storyboard.config.json via canvasConfig. */
+function zoomLimits() {
+  const z = getCanvasZoom()
+  return { ZOOM_MIN: z.min, ZOOM_MAX: z.max, ZOOM_STEP: z.step }
+}
 
 /** Saved viewport state older than this is considered stale — zoom-to-fit instead. */
 const VIEWPORT_TTL_MS = 15 * 60 * 1000
@@ -44,9 +55,7 @@ const CANVAS_BRIDGE_STATE_KEY = '__storyboardCanvasBridgeState'
 const GH_INSTALL_URL = 'https://github.com/cli/cli'
 
 registerSmoothCorners()
-
-/** Matches branch-deploy base path prefixes like /branch--my-feature/ */
-const BRANCH_PREFIX_RE = /^\/branch--[^/]+/
+registerHotPoolDevLogs()
 
 // Build a reverse map from story route paths → { storyId, route }
 const storyRouteIndex = new Map()
@@ -132,16 +141,17 @@ function getViewportStorageKey(canvasId) {
 function loadViewportState(canvasId) {
   try {
     const raw = localStorage.getItem(getViewportStorageKey(canvasId))
-    if (!raw) { console.log('[viewport] no saved state for', canvasId); return null }
+    if (!raw) { if (getFlag('dev-logs')) console.log('[viewport] no saved state for', canvasId); return null }
     const state = JSON.parse(raw)
     const timestamp = typeof state.timestamp === 'number' ? state.timestamp : 0
     const age = Date.now() - timestamp
     if (age > VIEWPORT_TTL_MS) {
-      console.log('[viewport] stale state for', canvasId, '— age:', Math.round(age / 1000), 's')
+      if (getFlag('dev-logs')) console.log('[viewport] stale state for', canvasId, '— age:', Math.round(age / 1000), 's')
       localStorage.removeItem(getViewportStorageKey(canvasId))
       return null
     }
-    console.log('[viewport] loaded state for', canvasId, '— age:', Math.round(age / 1000), 's, zoom:', state.zoom, 'scroll:', state.scrollLeft, state.scrollTop)
+    if (getFlag('dev-logs')) console.log('[viewport] loaded state for', canvasId, '— age:', Math.round(age / 1000), 's, zoom:', state.zoom, 'scroll:', state.scrollLeft, state.scrollTop)
+    const { ZOOM_MIN, ZOOM_MAX } = zoomLimits()
     return {
       zoom: typeof state.zoom === 'number' ? Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, state.zoom)) : null,
       scrollLeft: typeof state.scrollLeft === 'number' ? state.scrollLeft : null,
@@ -271,13 +281,15 @@ function computeCanvasBounds(widgets, componentEntries) {
 }
 
 /** Renders a single JSON-defined widget by type lookup. */
-function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefreshGitHub }) {
+function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefreshGitHub, multiSelected }) {
   const Component = getWidgetComponent(widget.type)
   if (!Component) {
     console.warn(`[canvas] Unknown widget type: ${widget.type}`)
     return null
   }
-  const resizable = isResizable(widget.type) && !!onUpdate
+  const resizable = (widget.type === 'terminal' || widget.type === 'agent')
+    ? isTerminalResizable(widget.props?.agentId) && !!onUpdate
+    : isResizable(widget.type) && !!onUpdate
   // Only pass ref to forwardRef-wrapped components (e.g. PrototypeEmbed)
   const elementProps = {
     id: widget.id,
@@ -286,6 +298,7 @@ function WidgetRenderer({ widget, onUpdate, widgetRef, onRefreshGitHub, canRefre
     resizable,
     onRefreshGitHub,
     canRefreshGitHub,
+    multiSelected,
   }
   if (Component.$$typeof === Symbol.for('react.forward_ref')) {
     elementProps.ref = widgetRef
@@ -303,11 +316,14 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
   widget,
   selected,
   multiSelected,
+  connectorCount,
+  allWidgets,
   onSelect,
   onDeselect,
   onUpdate,
   onRemove,
   onCopy,
+  onCopyWithConnectors,
   onRefreshGitHub,
   canRefreshGitHub,
   onConnectorDragStart,
@@ -319,7 +335,7 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
   // Dynamically adjust features based on widget state
   const features = useMemo(() => {
     const isGitHub = !!widget.props?.github
-    return rawFeatures.map((f) => {
+    const adjusted = rawFeatures.map((f) => {
       // Toggle collapse label and hide when content is short (no github = no collapse)
       if (f.action === 'toggle-collapse') {
         if (widget.type === 'link-preview' && !isGitHub) return null
@@ -333,13 +349,79 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
       if (f.action === 'refresh-github' && !isGitHub) return null
       return f
     }).filter(Boolean)
-  }, [rawFeatures, widget.props?.github, widget.props?.collapsed])
 
-  const handleAction = useCallback((actionId) => {
+    // Add dynamic "Split Screen" action when a connected split target exists.
+    // Uses connectorCount/allWidgets props (reactive) instead of the global
+    // bridge state which may be stale during React render.
+    if (isExpandable(widget.type)) {
+      const hasConnected = (connectorCount || []).some((c) => {
+        const otherId = c.start?.widgetId === widget.id ? c.end?.widgetId : c.start?.widgetId
+        const otherWidget = (allWidgets || []).find((w) => w.id === otherId)
+        return otherWidget && isSplitScreenCapable(otherWidget.type)
+      })
+      if (hasConnected) {
+        // Insert before the first menu-only feature
+        const insertIdx = adjusted.findIndex((f) => f.menu)
+        const splitFeature = {
+          id: 'split-screen',
+          type: 'action',
+          action: 'split-screen',
+          label: 'Split Screen',
+          icon: 'columns',
+          prod: true,
+        }
+        if (insertIdx >= 0) adjusted.splice(insertIdx, 0, splitFeature)
+        else adjusted.push(splitFeature)
+      }
+    }
+
+    // Add dynamic "Broadcast" toggle for terminal/agent widgets with connected peers
+    if (widget.type === 'terminal' || widget.type === 'agent') {
+      const widgetConnectors = connectorCount || []
+      const widgetList = allWidgets || []
+      let hasBroadcastPeers = false
+      let allBroadcastActive = true
+      const broadcastConnectorIds = []
+
+      for (const conn of widgetConnectors) {
+        const peerId = conn.start?.widgetId === widget.id ? conn.end?.widgetId : conn.start?.widgetId
+        const peer = widgetList.find((w) => w.id === peerId)
+        if (peer && (peer.type === 'terminal' || peer.type === 'agent')) {
+          hasBroadcastPeers = true
+          broadcastConnectorIds.push(conn.id)
+          if (conn.meta?.messagingMode !== 'two-way') allBroadcastActive = false
+        }
+      }
+
+      if (hasBroadcastPeers) {
+        const isActive = allBroadcastActive
+        const insertIdx = adjusted.findIndex((f) => f.menu)
+        const broadcastFeature = {
+          id: 'broadcast',
+          type: 'action',
+          action: `broadcast-toggle:${broadcastConnectorIds.join(',')}:${isActive ? 'off' : 'on'}`,
+          label: isActive ? 'Broadcast On' : 'Broadcast',
+          icon: 'broadcast',
+          active: isActive,
+        }
+        if (insertIdx >= 0) adjusted.splice(insertIdx, 0, broadcastFeature)
+        else adjusted.push(broadcastFeature)
+      }
+    }
+
+    return adjusted
+  }, [rawFeatures, widget.props?.github, widget.props?.collapsed, widget.type, widget.id, connectorCount, allWidgets])
+
+  // eslint-disable-next-line react-hooks/preserve-manual-memoization
+  const handleAction = useCallback((actionId, opts) => {
     if (actionId === 'delete') {
       onRemove?.(widget.id)
     } else if (actionId === 'copy') {
-      onCopy?.(widget)
+      if (opts?.altKey && onCopyWithConnectors) {
+        onCopyWithConnectors(widget)
+      } else {
+        onCopy?.(widget)
+      }
     } else if (actionId === 'copy-text') {
       const title = widget.props?.title || ''
       const body = widget.props?.text || widget.props?.content || widget.props?.github?.body || ''
@@ -361,8 +443,20 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
           if (el) el.scrollIntoView({ behavior: 'smooth', block: 'center' })
         })
       }
+    } else if (actionId.startsWith('broadcast-toggle:')) {
+      // broadcast-toggle:<connectorId1,connectorId2,...>:<on|off>
+      const parts = actionId.split(':')
+      const connectorIds = parts[1].split(',')
+      const turnOn = parts[2] === 'on'
+      const bridge = window.__storyboardCanvasBridgeState
+      const canvasId = bridge?.canvasId || ''
+      const meta = turnOn ? { messagingMode: 'two-way' } : { messagingMode: null }
+      for (const cid of connectorIds) {
+        updateConnectorApi(canvasId, cid, meta)
+          .catch((err) => console.error('[canvas] Failed to toggle broadcast:', err))
+      }
     }
-  }, [widget, onRemove, onCopy, onRefreshGitHub])
+  }, [widget, onRemove, onCopy, onCopyWithConnectors, onRefreshGitHub])
 
   const handleWidgetFieldUpdate = useCallback((updates) => {
     onUpdate?.(widget.id, updates)
@@ -390,6 +484,7 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
         widgetRef={widgetRef}
         onRefreshGitHub={onRefreshGitHub}
         canRefreshGitHub={canRefreshGitHub}
+        multiSelected={multiSelected}
       />
     </WidgetChrome>
   )
@@ -398,6 +493,8 @@ const ChromeWrappedWidget = memo(function ChromeWrappedWidget({
     prev.widget === next.widget &&
     prev.selected === next.selected &&
     prev.multiSelected === next.multiSelected &&
+    prev.connectorCount === next.connectorCount &&
+    prev.allWidgets === next.allWidgets &&
     prev.readOnly === next.readOnly &&
     prev.onSelect === next.onSelect &&
     prev.onDeselect === next.onDeselect &&
@@ -532,6 +629,11 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   const [snapGridSize, setSnapGridSize] = useState(canvas?.gridSize || 40)
   const [showGhInstallBanner, setShowGhInstallBanner] = useState(false)
 
+  // Scroll lock: prevents focus-triggered scroll jumps when adding terminal/agent widgets.
+  // The lock captures the current scroll position and forces it back on every scroll event
+  // until unlocked by the widget's ready signal or a safety timeout.
+  // Visual UI (outline + banner) only appears after 1.5s if still locked.
+
   // Refs for snap settings (used by drop handler inside effect closure)
   const snapEnabledRef = useRef(snapEnabled)
   const snapGridSizeRef = useRef(snapGridSize)
@@ -571,12 +673,42 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     stateRef.current = { widgets: localWidgets, sources: localSources, connectors: localConnectors }
   }, [localWidgets, localSources, localConnectors])
 
+  // Dirty flag — true while optimistic edits haven't been persisted yet.
+  // Prevents HMR echoes from overwriting in-flight local state.
+  const dirtyRef = useRef(false)
+
+  // Counter of in-flight writes. dirtyRef is only cleared when this reaches 0,
+  // preventing early clears when multiple writes are queued in sequence.
+  const inflightWritesRef = useRef(0)
+
+  // Grace period timer — after all writes complete, dirtyRef stays true for a
+  // brief window to absorb delayed file-watcher HMR events that arrive after
+  // the server's immediate push. Defense-in-depth for the write guard.
+  const dirtyGraceTimerRef = useRef(null)
+
   // Serialized write queue — ensures JSONL events land in the right order
   const writeQueueRef = useRef(Promise.resolve())
   function queueWrite(fn) {
-    writeQueueRef.current = writeQueueRef.current.then(fn).catch((err) =>
-      console.error('[canvas] Write queue error:', err)
-    )
+    clearTimeout(dirtyGraceTimerRef.current)
+    inflightWritesRef.current += 1
+    writeQueueRef.current = writeQueueRef.current
+      .then(fn)
+      .catch((err) => console.error('[canvas] Write queue error:', err))
+      .finally(() => {
+        inflightWritesRef.current -= 1
+        if (inflightWritesRef.current < 0) {
+          console.warn('[canvas] Write queue counter underflow — resetting')
+          inflightWritesRef.current = 0
+        }
+        if (inflightWritesRef.current === 0) {
+          // Grace period — absorb delayed watcher HMR events before clearing
+          dirtyGraceTimerRef.current = setTimeout(() => {
+            if (inflightWritesRef.current === 0) {
+              dirtyRef.current = false
+            }
+          }, 600)
+        }
+      })
     return writeQueueRef.current
   }
 
@@ -663,14 +795,23 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
   if (canvas !== trackedCanvas) {
     const isCanvasSwitch = trackedCanvas && canvas && trackedCanvas._route !== canvas._route
-    console.log('[viewport] canvas changed —', isCanvasSwitch ? 'new canvas, resetting viewport' : 'same canvas, updating widgets only')
+    if (getFlag('dev-logs')) console.log('[viewport] canvas changed —', isCanvasSwitch ? 'new canvas, resetting viewport' : 'same canvas, updating widgets only')
     setTrackedCanvas(canvas)
-    setLocalWidgets(canvas?.widgets ?? null)
-    setLocalConnectors(canvas?.connectors ?? [])
-    setLocalSources(canvas?.sources ?? [])
+
+    // Skip replacing local state with server data when optimistic edits are
+    // pending — the local state is more recent. The next save will persist it
+    // and the subsequent server push (after dirty clears) will reconcile.
+    if (!dirtyRef.current || isCanvasSwitch) {
+      setLocalWidgets(canvas?.widgets ?? null)
+      setLocalConnectors(canvas?.connectors ?? [])
+      setLocalSources(canvas?.sources ?? [])
+    }
+
     setSnapEnabled(canvas?.snapToGrid ?? false)
     setSnapGridSize(canvas?.gridSize || 40)
-    undoRedo.reset()
+    if (isCanvasSwitch) {
+      undoRedo.reset()
+    }
     // Only reset viewport state when switching to a different canvas,
     // not when the same canvas refreshes with server data.
     if (isCanvasSwitch) {
@@ -683,11 +824,13 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
   }
 
-  // Debounced save to server
+  // Debounced save to server — routed through queueWrite to serialize
+  // with deletes and other writes, preventing stale data from overwriting.
   const debouncedSave = useRef(
     debounce((canvasId, widgets) => {
-      updateCanvas(canvasId, { widgets }).catch((err) =>
-        console.error('[canvas] Failed to save:', err)
+      queueWrite(() =>
+        updateCanvas(canvasId, { widgets })
+          .catch((err) => console.error('[canvas] Failed to save:', err))
       )
     }, 2000)
   ).current
@@ -705,12 +848,17 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       const next = prev.map((w) =>
         w.id === widgetId ? { ...w, props: { ...w.props, ...snapped } } : w
       )
+      dirtyRef.current = true
       debouncedSave(canvasId, next)
       return next
     })
   }, [canvasId, debouncedSave, undoRedo, snapEnabled, snapGridSize])
 
   const handleWidgetRemove = useCallback((widgetId) => {
+    // Cancel any pending debounced save — it may contain stale data
+    // that includes the widget we're about to delete
+    debouncedSave.cancel()
+
     undoRedo.snapshot(stateRef.current, 'remove', widgetId)
     setLocalWidgets((prev) => prev ? prev.filter((w) => w.id !== widgetId) : prev)
     // Cascade: remove connectors referencing this widget
@@ -726,12 +874,12 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       }
       return prev.filter((c) => c.start.widgetId !== widgetId && c.end.widgetId !== widgetId)
     })
+    dirtyRef.current = true
     queueWrite(() =>
-      removeWidgetApi(canvasId, widgetId).catch((err) =>
-        console.error('[canvas] Failed to remove widget:', err)
-      )
+      removeWidgetApi(canvasId, widgetId)
+        .catch((err) => console.error('[canvas] Failed to remove widget:', err))
     )
-  }, [canvasId, undoRedo])
+  }, [canvasId, undoRedo, debouncedSave])
 
   const handleConnectorAdd = useCallback(async ({ startWidgetId, startAnchor, endWidgetId, endAnchor }) => {
     try {
@@ -748,6 +896,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   const handleConnectorRemove = useCallback((connectorId) => {
     undoRedo.snapshot(stateRef.current, 'connector-remove')
     setLocalConnectors((prev) => prev.filter((c) => c.id !== connectorId))
+    dirtyRef.current = true
     queueWrite(() =>
       removeConnectorApi(canvasId, connectorId).catch((err) =>
         console.error('[canvas] Failed to remove connector:', err)
@@ -802,21 +951,52 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       y: (scrollEl.scrollTop + clientY - rect.top) / scale,
     })
 
-    // Find nearest anchor on any other widget within snap distance
-    const SNAP_DIST = 40
+    // Find nearest anchor on any other widget within a rectangular snap zone.
+    // Each anchor has a 30px-wide strip (15px each side) extending from the widget edge.
+    const SNAP_EXTEND = 15
+    const SNAP_DEPTH = 40
+    const SNAP_CROSS = 20 // perpendicular expansion so you can approach from any direction
     const sourceType = startWidget.type
     const findNearestAnchor = (canvasPt) => {
       const currentWidgets = stateRef.current.widgets ?? []
       let best = null
-      let bestDist = SNAP_DIST
+      let bestDist = Infinity
       for (const w of currentWidgets) {
         if (w.id === widgetId) continue
-        // Check if this widget type accepts connections from the source type
         if (!canAcceptConnection(w.type, sourceType)) continue
+
+        let ww, wh
+        const el = document.getElementById(w.id)
+        if (el) {
+          const inner = el.querySelector('[data-widget-id]') || el.firstElementChild
+          if (inner) { ww = inner.offsetWidth; wh = inner.offsetHeight }
+        }
+        if (!ww) ww = w.props?.width ?? w.bounds?.width ?? 270
+        if (!wh) wh = w.props?.height ?? w.bounds?.height ?? 170
+        const wx = w.position?.x ?? 0
+        const wy = w.position?.y ?? 0
+
         for (const anch of ['top', 'bottom', 'left', 'right']) {
-          // Skip unavailable or disabled anchors
           const anchorState = getAnchorState(w.type, anch)
           if (anchorState !== 'available') continue
+
+          // Build a rectangular hit zone for this anchor
+          let inZone = false
+          if (anch === 'top') {
+            inZone = canvasPt.x >= wx - SNAP_CROSS && canvasPt.x <= wx + ww + SNAP_CROSS &&
+                     canvasPt.y >= wy - SNAP_DEPTH && canvasPt.y <= wy + SNAP_EXTEND
+          } else if (anch === 'bottom') {
+            inZone = canvasPt.x >= wx - SNAP_CROSS && canvasPt.x <= wx + ww + SNAP_CROSS &&
+                     canvasPt.y >= wy + wh - SNAP_EXTEND && canvasPt.y <= wy + wh + SNAP_DEPTH
+          } else if (anch === 'left') {
+            inZone = canvasPt.x >= wx - SNAP_DEPTH && canvasPt.x <= wx + SNAP_EXTEND &&
+                     canvasPt.y >= wy - SNAP_CROSS && canvasPt.y <= wy + wh + SNAP_CROSS
+          } else if (anch === 'right') {
+            inZone = canvasPt.x >= wx + ww - SNAP_EXTEND && canvasPt.x <= wx + ww + SNAP_DEPTH &&
+                     canvasPt.y >= wy - SNAP_CROSS && canvasPt.y <= wy + wh + SNAP_CROSS
+          }
+          if (!inZone) continue
+
           const pt = computeAnchorPt(w, anch)
           const dist = Math.hypot(pt.x - canvasPt.x, pt.y - canvasPt.y)
           if (dist < bestDist) {
@@ -872,147 +1052,334 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     document.addEventListener('pointerup', handlePointerUp)
   }, [handleConnectorAdd])
 
-  // Drag an existing connector endpoint to reconnect or remove
-  const handleEndpointDrag = useCallback((connector, endpoint, e) => {
-    e.stopPropagation()
-    e.preventDefault()
-    const scrollEl = scrollRef.current
-    if (!scrollEl) return
-    const scale = zoomRef.current / 100
-    const rect = scrollEl.getBoundingClientRect()
-
-    // The fixed end stays put; the dragged end follows cursor
-    const fixedEnd = endpoint === 'start' ? 'end' : 'start'
-    const fixedSide = connector[fixedEnd]
-    const fixedWidget = (stateRef.current.widgets ?? []).find((w) => w.id === fixedSide.widgetId)
-    if (!fixedWidget) return
+  // Endpoint drag removed — dragging from a filled anchor now always
+  // creates a new connection via handleConnectorDragStart instead of
+  // repositioning the existing one.
 
-    const computeAnchorPtLocal = (widget, anch) => {
-      let ww, wh
-      const el = document.getElementById(widget.id)
-      if (el) {
-        const inner = el.querySelector('[data-widget-id]') || el.firstElementChild
-        if (inner) { ww = inner.offsetWidth; wh = inner.offsetHeight }
+  const handleWidgetCopy = useCallback(async (widget) => {
+    // Find the next free offset — check how many copies already exist at +n*40
+    const baseX = widget.position?.x ?? 0
+    const baseY = widget.position?.y ?? 0
+    const occupied = new Set(
+      (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
+    )
+    let n = 1
+    while (occupied.has(`${baseX + n * 40},${baseY + n * 40}`)) {
+      n++
+    }
+    const position = { x: baseX + n * 40, y: baseY + n * 40 }
+    const isTerminal = widget.type === 'terminal' || widget.type === 'agent'
+    try {
+      const copyProps = { ...widget.props }
+      // Terminal widgets must get unique names — strip prettyName so the server generates a fresh one
+      if (isTerminal) delete copyProps.prettyName
+      // Image widgets: duplicate the asset file so each widget owns its own copy
+      if (widget.type === 'image' && copyProps.src) {
+        const dupResult = await duplicateImage(copyProps.src)
+        if (dupResult.success) copyProps.src = dupResult.filename
       }
-      if (!ww) ww = widget.props?.width ?? widget.bounds?.width ?? 270
-      if (!wh) wh = widget.props?.height ?? widget.bounds?.height ?? 170
-      const px = widget.position?.x ?? 0
-      const py = widget.position?.y ?? 0
-      switch (anch) {
-        case 'top':    return { x: px + ww / 2, y: py }
-        case 'bottom': return { x: px + ww / 2, y: py + wh }
-        case 'left':   return { x: px, y: py + wh / 2 }
-        case 'right':  return { x: px + ww, y: py + wh / 2 }
-        default:       return { x: px + ww / 2, y: py + wh / 2 }
+
+      undoRedo.snapshot(stateRef.current, 'add')
+      const result = await addWidgetApi(canvasId, {
+        type: widget.type,
+        props: copyProps,
+        position,
+      })
+      if (result.success && result.widget) {
+        setLocalWidgets((prev) => [...(prev || []), result.widget])
+        setSelectedWidgetIds(new Set([result.widget.id]))
       }
+    } catch (err) {
+      console.error('[canvas] Failed to copy widget:', err)
     }
+  }, [canvasId, localWidgets, undoRedo])
 
-    const fixedPt = computeAnchorPtLocal(fixedWidget, fixedSide.anchor)
-    const fixedWidgetId = fixedSide.widgetId
+  // Duplicate a single widget WITH its connectors (Alt+click on duplicate button)
+  const handleWidgetCopyWithConnectors = useCallback(async (widget) => {
+    if (!widget) return
+    const widgets = [widget]
 
-    const toCanvasPoint = (clientX, clientY) => ({
-      x: (scrollEl.scrollLeft + clientX - rect.left) / scale,
-      y: (scrollEl.scrollTop + clientY - rect.top) / scale,
-    })
+    undoRedo.snapshot(stateRef.current, 'add')
 
-    const SNAP_DIST = 40
-    const sourceType = fixedWidget.type
-    const findNearestAnchorLocal = (canvasPt) => {
-      const currentWidgets = stateRef.current.widgets ?? []
-      let best = null
-      let bestDist = SNAP_DIST
-      for (const w of currentWidgets) {
-        if (w.id === fixedWidgetId) continue
-        if (!canAcceptConnection(w.type, sourceType)) continue
-        for (const anch of ['top', 'bottom', 'left', 'right']) {
-          const anchorState = getAnchorState(w.type, anch)
-          if (anchorState !== 'available') continue
-          const pt = computeAnchorPtLocal(w, anch)
-          const dist = Math.hypot(pt.x - canvasPt.x, pt.y - canvasPt.y)
-          if (dist < bestDist) {
-            bestDist = dist
-            best = { widgetId: w.id, anchor: anch, pt }
+    const occupied = new Set(
+      (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
+    )
+    let offset = 1
+    while (occupied.has(`${(widget.position?.x ?? 0) + offset * 40},${(widget.position?.y ?? 0) + offset * 40}`)) offset++
+
+    const imageOverrides = new Map()
+    if (widget.type === 'image' && widget.props?.src) {
+      try {
+        const dupResult = await duplicateImage(widget.props.src)
+        if (dupResult.success) imageOverrides.set(widget.id, dupResult.filename)
+      } catch { /* use original src as fallback */ }
+    }
+
+    const selectedIds = new Set([widget.id])
+    const relevantConnectors = (localConnectors ?? []).filter(
+      (c) => selectedIds.has(c.start?.widgetId) || selectedIds.has(c.end?.widgetId)
+    )
+
+    const ops = []
+    for (const w of widgets) {
+      const copyProps = { ...w.props }
+      const isTerminal = w.type === 'terminal' || w.type === 'agent'
+      if (isTerminal) delete copyProps.prettyName
+      if (imageOverrides.has(w.id)) copyProps.src = imageOverrides.get(w.id)
+      ops.push({
+        op: 'create-widget',
+        ref: `clone-${w.id}`,
+        type: w.type,
+        props: copyProps,
+        position: {
+          x: (w.position?.x ?? 0) + offset * 40,
+          y: (w.position?.y ?? 0) + offset * 40,
+        },
+      })
+    }
+
+    for (const conn of relevantConnectors) {
+      const startInSelection = selectedIds.has(conn.start?.widgetId)
+      const endInSelection = selectedIds.has(conn.end?.widgetId)
+      ops.push({
+        op: 'create-connector',
+        startWidgetId: startInSelection ? `$clone-${conn.start.widgetId}` : conn.start.widgetId,
+        startAnchor: conn.start.anchor,
+        endWidgetId: endInSelection ? `$clone-${conn.end.widgetId}` : conn.end.widgetId,
+        endAnchor: conn.end.anchor,
+        connectorType: conn.connectorType || 'default',
+      })
+    }
+
+    try {
+      const response = await batchOperations(canvasId, ops)
+      if (!response.success) {
+        console.error('[canvas] Batch duplicate failed:', response.error)
+        return
+      }
+
+      const newWidgets = []
+      const newConnectors = []
+      const refMap = response.refs || {}
+
+      for (const result of response.results) {
+        if (result.op === 'create-widget' && result.widget) {
+          newWidgets.push(result.widget)
+        }
+        if (result.op === 'create-connector' && result.connectorId) {
+          const origOp = ops[result.index]
+          const resolveId = (val) => {
+            if (typeof val === 'string' && val.startsWith('$')) {
+              return refMap[val.slice(1)] ?? val
+            }
+            return val
           }
+          newConnectors.push({
+            id: result.connectorId,
+            type: 'connector',
+            connectorType: origOp.connectorType || 'default',
+            start: { widgetId: resolveId(origOp.startWidgetId), anchor: origOp.startAnchor },
+            end: { widgetId: resolveId(origOp.endWidgetId), anchor: origOp.endAnchor },
+            meta: {},
+          })
         }
       }
-      return best
-    }
-
-    const cursorPt = toCanvasPoint(e.clientX, e.clientY)
-    const snap = findNearestAnchorLocal(cursorPt)
-    setConnectorDrag({
-      startWidgetId: fixedWidgetId,
-      startAnchor: fixedSide.anchor,
-      startPt: fixedPt,
-      endPt: snap ? snap.pt : cursorPt,
-      endAnchor: snap ? snap.anchor : fixedSide.anchor,
-      snapTarget: snap,
-    })
 
-    const handlePointerMove = (moveE) => {
-      const pt = toCanvasPoint(moveE.clientX, moveE.clientY)
-      const nearSnap = findNearestAnchorLocal(pt)
-      setConnectorDrag((prev) => prev ? {
-        ...prev,
-        endPt: nearSnap ? nearSnap.pt : pt,
-        endAnchor: nearSnap ? nearSnap.anchor : prev.startAnchor,
-        snapTarget: nearSnap,
-      } : null)
+      if (newWidgets.length > 0) {
+        setLocalWidgets((prev) => [...(prev || []), ...newWidgets])
+        setSelectedWidgetIds(new Set(newWidgets.map((w) => w.id)))
+      }
+      if (newConnectors.length > 0) {
+        setLocalConnectors((prev) => [...prev, ...newConnectors])
+      }
+    } catch (err) {
+      console.error('[canvas] Failed to duplicate with connectors:', err)
     }
+  }, [canvasId, localWidgets, localConnectors, undoRedo])
 
-    const handlePointerUp = (upE) => {
-      document.removeEventListener('pointermove', handlePointerMove)
-      document.removeEventListener('pointerup', handlePointerUp)
+  // Duplicate all selected widgets in one undo step (Cmd+D)
+  const handleDuplicateSelected = useCallback(async () => {
+    const widgets = (localWidgets ?? []).filter((w) => selectedWidgetIds.has(w.id))
+    if (widgets.length === 0) return
 
-      const pt = toCanvasPoint(upE.clientX, upE.clientY)
-      const nearSnap = findNearestAnchorLocal(pt)
+    // Single undo snapshot for the entire batch
+    undoRedo.snapshot(stateRef.current, 'add')
 
-      // Always remove the old connector
-      handleConnectorRemove(connector.id)
+    // Compute occupied positions to find free offset
+    const occupied = new Set(
+      (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
+    )
+    let offset = 1
+    const anyOccupied = () => widgets.some((w) => {
+      const bx = (w.position?.x ?? 0) + offset * 40
+      const by = (w.position?.y ?? 0) + offset * 40
+      return occupied.has(`${bx},${by}`)
+    })
+    while (anyOccupied()) offset++
 
-      // If snapped to a new anchor, create a new connector
-      if (nearSnap) {
-        handleConnectorAdd({
-          startWidgetId: fixedWidgetId,
-          startAnchor: fixedSide.anchor,
-          endWidgetId: nearSnap.widgetId,
-          endAnchor: nearSnap.anchor,
+    const newWidgets = []
+    for (const widget of widgets) {
+      const position = {
+        x: (widget.position?.x ?? 0) + offset * 40,
+        y: (widget.position?.y ?? 0) + offset * 40,
+      }
+      const isTerminal = widget.type === 'terminal' || widget.type === 'agent'
+      try {
+        const copyProps = { ...widget.props }
+        if (isTerminal) delete copyProps.prettyName
+        if (widget.type === 'image' && copyProps.src) {
+          try {
+            const dupResult = await duplicateImage(copyProps.src)
+            if (dupResult.success) copyProps.src = dupResult.filename
+          } catch { /* use original src as fallback */ }
+        }
+        const result = await addWidgetApi(canvasId, {
+          type: widget.type,
+          props: copyProps,
+          position,
         })
+        if (result.success && result.widget) {
+          newWidgets.push(result.widget)
+        }
+      } catch (err) {
+        console.error('[canvas] Failed to duplicate widget:', err)
       }
-      setConnectorDrag(null)
     }
 
-    document.addEventListener('pointermove', handlePointerMove)
-    document.addEventListener('pointerup', handlePointerUp)
-  }, [handleConnectorAdd, handleConnectorRemove])
+    if (newWidgets.length > 0) {
+      setLocalWidgets((prev) => [...(prev || []), ...newWidgets])
+      setSelectedWidgetIds(new Set(newWidgets.map((w) => w.id)))
+    }
+  }, [canvasId, localWidgets, selectedWidgetIds, undoRedo])
 
-  const handleWidgetCopy = useCallback(async (widget) => {
-    // Find the next free offset — check how many copies already exist at +n*40
-    const baseX = widget.position?.x ?? 0
-    const baseY = widget.position?.y ?? 0
+  // Duplicate selected widgets WITH connectors (Cmd+Shift+D)
+  // Uses the batch API for atomic operation — all widgets and connectors
+  // are created in a single request with $ref resolution.
+  const handleDuplicateWithConnectors = useCallback(async () => {
+    const widgets = (localWidgets ?? []).filter((w) => selectedWidgetIds.has(w.id))
+    if (widgets.length === 0) return
+
+    undoRedo.snapshot(stateRef.current, 'add')
+
+    // Compute offset — same logic as handleDuplicateSelected
     const occupied = new Set(
       (localWidgets ?? []).map((w) => `${w.position?.x ?? 0},${w.position?.y ?? 0}`)
     )
-    let n = 1
-    while (occupied.has(`${baseX + n * 40},${baseY + n * 40}`)) {
-      n++
+    let offset = 1
+    const anyOccupied = () => widgets.some((w) => {
+      const bx = (w.position?.x ?? 0) + offset * 40
+      const by = (w.position?.y ?? 0) + offset * 40
+      return occupied.has(`${bx},${by}`)
+    })
+    while (anyOccupied()) offset++
+
+    // Pre-process image widgets — duplicate asset files to get unique filenames
+    const imageOverrides = new Map()
+    for (const widget of widgets) {
+      if (widget.type === 'image' && widget.props?.src) {
+        try {
+          const dupResult = await duplicateImage(widget.props.src)
+          if (dupResult.success) imageOverrides.set(widget.id, dupResult.filename)
+        } catch { /* use original src as fallback */ }
+      }
     }
-    const position = { x: baseX + n * 40, y: baseY + n * 40 }
-    try {
-      undoRedo.snapshot(stateRef.current, 'add')
-      const result = await addWidgetApi(canvasId, {
+
+    // Find all connectors touching at least one selected widget
+    const selectedIds = new Set(widgets.map((w) => w.id))
+    const relevantConnectors = (localConnectors ?? []).filter(
+      (c) => selectedIds.has(c.start?.widgetId) || selectedIds.has(c.end?.widgetId)
+    )
+
+    // Build batch operations
+    const ops = []
+
+    // 1. Create-widget ops with ref names for $ref resolution
+    for (const widget of widgets) {
+      const copyProps = { ...widget.props }
+      const isTerminal = widget.type === 'terminal' || widget.type === 'agent'
+      if (isTerminal) delete copyProps.prettyName
+      if (imageOverrides.has(widget.id)) copyProps.src = imageOverrides.get(widget.id)
+
+      ops.push({
+        op: 'create-widget',
+        ref: `clone-${widget.id}`,
         type: widget.type,
-        props: { ...widget.props },
-        position,
+        props: copyProps,
+        position: {
+          x: (widget.position?.x ?? 0) + offset * 40,
+          y: (widget.position?.y ?? 0) + offset * 40,
+        },
       })
-      if (result.success && result.widget) {
-        setLocalWidgets((prev) => [...(prev || []), result.widget])
-        setSelectedWidgetIds(new Set([result.widget.id]))
+    }
+
+    // 2. Create-connector ops — remap selected endpoints to $ref clones
+    for (const conn of relevantConnectors) {
+      const startInSelection = selectedIds.has(conn.start?.widgetId)
+      const endInSelection = selectedIds.has(conn.end?.widgetId)
+
+      ops.push({
+        op: 'create-connector',
+        startWidgetId: startInSelection ? `$clone-${conn.start.widgetId}` : conn.start.widgetId,
+        startAnchor: conn.start.anchor,
+        endWidgetId: endInSelection ? `$clone-${conn.end.widgetId}` : conn.end.widgetId,
+        endAnchor: conn.end.anchor,
+        connectorType: conn.connectorType || 'default',
+      })
+    }
+
+    try {
+      const response = await batchOperations(canvasId, ops)
+      if (!response.success) {
+        console.error('[canvas] Batch duplicate failed:', response.error)
+        return
+      }
+
+      // Extract created widgets and connectors from results
+      const newWidgets = []
+      const newConnectors = []
+      const refMap = response.refs || {}
+
+      for (const result of response.results) {
+        if (result.op === 'create-widget' && result.widget) {
+          newWidgets.push(result.widget)
+        }
+        if (result.op === 'create-connector' && result.connectorId) {
+          // Reconstruct connector object from the operation + resolved refs
+          const origOp = ops[result.index]
+          const resolveId = (val) => {
+            if (typeof val === 'string' && val.startsWith('$')) {
+              return refMap[val.slice(1)] ?? val
+            }
+            return val
+          }
+          newConnectors.push({
+            id: result.connectorId,
+            type: 'connector',
+            connectorType: origOp.connectorType || 'default',
+            start: { widgetId: resolveId(origOp.startWidgetId), anchor: origOp.startAnchor },
+            end: { widgetId: resolveId(origOp.endWidgetId), anchor: origOp.endAnchor },
+            meta: {},
+          })
+        }
+      }
+
+      if (newWidgets.length > 0) {
+        setLocalWidgets((prev) => [...(prev || []), ...newWidgets])
+        setSelectedWidgetIds(new Set(newWidgets.map((w) => w.id)))
+      }
+      if (newConnectors.length > 0) {
+        setLocalConnectors((prev) => [...prev, ...newConnectors])
       }
     } catch (err) {
-      console.error('[canvas] Failed to copy widget:', err)
+      console.error('[canvas] Failed to duplicate with connectors:', err)
     }
-  }, [canvasId, localWidgets, undoRedo])
+  }, [canvasId, localWidgets, localConnectors, selectedWidgetIds, undoRedo])
+
+  // Select all widgets (Cmd+A)
+  const handleSelectAll = useCallback(() => {
+    const allIds = (localWidgets ?? []).map((w) => w.id)
+    if (allIds.length > 0) setSelectedWidgetIds(new Set(allIds))
+  }, [localWidgets])
 
   const showMissingGhBanner = useCallback(() => {
     setShowGhInstallBanner(true)
@@ -1068,8 +1435,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
   const debouncedSourceSave = useRef(
     debounce((canvasId, sources) => {
-      updateCanvas(canvasId, { sources }).catch((err) =>
-        console.error('[canvas] Failed to save sources:', err)
+      queueWrite(() =>
+        updateCanvas(canvasId, { sources }).catch((err) =>
+          console.error('[canvas] Failed to save sources:', err)
+        )
       )
     }, 2000)
   ).current
@@ -1086,6 +1455,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       const next = current.some((s) => s?.export === exportName)
         ? current.map((s) => (s?.export === exportName ? { ...s, ...snapped } : s))
         : [...current, { export: exportName, ...snapped }]
+      dirtyRef.current = true
       debouncedSourceSave(canvasId, next)
       return next
     })
@@ -1141,10 +1511,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           }
           return w
         })
+        dirtyRef.current = true
         queueWrite(() =>
-          updateCanvas(canvasId, { widgets: next }).catch((err) =>
-            console.error('[canvas] Failed to save multi-move:', err)
-          )
+          updateCanvas(canvasId, { widgets: next })
+            .catch((err) => console.error('[canvas] Failed to save multi-move:', err))
         )
         return next
       })
@@ -1173,10 +1543,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           return s
         })
         if (changed) {
+          dirtyRef.current = true
           queueWrite(() =>
-            updateCanvas(canvasId, { sources: next }).catch((err) =>
-              console.error('[canvas] Failed to save multi-move sources:', err)
-            )
+            updateCanvas(canvasId, { sources: next })
+              .catch((err) => console.error('[canvas] Failed to save multi-move sources:', err))
           )
         }
         return changed ? next : current
@@ -1192,10 +1562,10 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         const next = current.some((s) => s?.export === sourceExport)
           ? current.map((s) => (s?.export === sourceExport ? { ...s, position: rounded } : s))
           : [...current, { export: sourceExport, position: rounded }]
+        dirtyRef.current = true
         queueWrite(() =>
-          updateCanvas(canvasId, { sources: next }).catch((err) =>
-            console.error('[canvas] Failed to save source position:', err)
-          )
+          updateCanvas(canvasId, { sources: next })
+            .catch((err) => console.error('[canvas] Failed to save source position:', err))
         )
         return next
       })
@@ -1203,15 +1573,16 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
 
     undoRedo.snapshot(stateRef.current, 'move', dragId)
+    debouncedSave.cancel()
     setLocalWidgets((prev) => {
       if (!prev) return prev
       const next = prev.map((w) =>
         w.id === dragId ? { ...w, position: rounded } : w
       )
+      dirtyRef.current = true
       queueWrite(() =>
-        updateCanvas(canvasId, { widgets: next }).catch((err) =>
-          console.error('[canvas] Failed to save widget position:', err)
-        )
+        updateCanvas(canvasId, { widgets: next })
+          .catch((err) => console.error('[canvas] Failed to save widget position:', err))
       )
       return next
     })
@@ -1236,20 +1607,21 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     if (!el || loading) return
     const saved = pendingScrollRestore.current
     if (saved) {
-      console.log('[viewport] restoring saved viewport — zoom:', saved.zoom, 'scroll:', saved.scrollLeft, saved.scrollTop)
+      if (getFlag('dev-logs')) console.log('[viewport] restoring saved viewport — zoom:', saved.zoom, 'scroll:', saved.scrollLeft, saved.scrollTop)
       // Fresh saved viewport — restore exactly
       if (saved.scrollLeft != null) el.scrollLeft = saved.scrollLeft
       if (saved.scrollTop != null) el.scrollTop = saved.scrollTop
       pendingScrollRestore.current = null
     } else {
-      console.log('[viewport] no saved viewport — fitting to objects')
+      if (getFlag('dev-logs')) console.log('[viewport] no saved viewport — fitting to objects')
       // No saved state or stale — zoom-to-fit all objects
       const bounds = computeCanvasBounds(localWidgets, componentEntries)
       if (bounds && el.clientWidth > 0 && el.clientHeight > 0) {
         const boxW = bounds.maxX - bounds.minX + FIT_PADDING * 2
         const boxH = bounds.maxY - bounds.minY + FIT_PADDING * 2
         const fitScale = Math.min(el.clientWidth / boxW, el.clientHeight / boxH)
-        const fitZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Math.round(fitScale * 100)))
+        const { ZOOM_MIN: zMin, ZOOM_MAX: zMax } = zoomLimits()
+        const fitZoom = Math.min(zMax, Math.max(zMin, Math.round(fitScale * 100)))
         const newScale = fitZoom / 100
         zoomRef.current = fitZoom
         // Imperative DOM update for initial zoom-to-fit — same path as applyZoom
@@ -1326,7 +1698,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   useEffect(() => {
     if (viewportInitName.current !== canvasId) return
     const el = scrollRef.current
-    console.log('[viewport] saving — zoom:', zoom, 'scroll:', el?.scrollLeft, el?.scrollTop)
+    if (getFlag('dev-logs')) console.log('[viewport] saving — zoom:', zoom, 'scroll:', el?.scrollLeft, el?.scrollTop)
     // Read current scroll so the zoom entry doesn't zero-out position,
     // but the authoritative scroll save comes from the scroll handler.
     saveViewportState(canvasId, {
@@ -1371,6 +1743,56 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
   }, [canvasId, loading])
 
+  // Gather current viewport data from refs (safe for callbacks/timeouts)
+  const getViewportData = useCallback(() => {
+    const el = scrollRef.current
+    if (!el) return null
+    const scale = zoomRef.current / 100
+    const scrollLeft = el.scrollLeft
+    const scrollTop = el.scrollTop
+    const cw = el.clientWidth
+    const ch = el.clientHeight
+    return {
+      centerX: Math.round((scrollLeft + cw / 2) / scale),
+      centerY: Math.round((scrollTop + ch / 2) / scale),
+      zoom: zoomRef.current,
+      topLeftX: Math.round(scrollLeft / scale),
+      topLeftY: Math.round(scrollTop / scale),
+      width: Math.round(cw / scale),
+      height: Math.round(ch / scale),
+    }
+  }, [])
+
+  // Debounced viewport-changed HMR event — sends position/zoom to Vite server
+  // so the selected-widgets bridge can write it to disk for agents.
+  useEffect(() => {
+    if (!import.meta.hot) return
+    const el = scrollRef.current
+    if (!el) return
+
+    const tabId = selectionTabIdRef.current
+
+    function sendViewport() {
+      const viewport = getViewportData()
+      if (viewport) {
+        import.meta.hot.send('storyboard:viewport-changed', { tabId, canvasId, viewport })
+      }
+    }
+
+    const debouncedSend = debounce(sendViewport, 500)
+
+    function handleScroll() { debouncedSend() }
+    el.addEventListener('scroll', handleScroll, { passive: true })
+
+    // Also send on zoom commits (zoom state changes trigger this effect)
+    sendViewport()
+
+    return () => {
+      debouncedSend.cancel()
+      el.removeEventListener('scroll', handleScroll)
+    }
+  }, [canvasId, zoom, loading, getViewportData])
+
   /**
    * Zoom to a new level, anchoring on an optional client-space point.
    * When a cursor position is provided (e.g. from a wheel event), the
@@ -1385,6 +1807,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   function applyZoom(newZoom, clientX, clientY) {
     const el = scrollRef.current
     const zoomEl = zoomElRef.current
+    const { ZOOM_MIN, ZOOM_MAX } = zoomLimits()
     const clampedZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, newZoom))
 
     if (!el || !zoomEl) {
@@ -1431,7 +1854,11 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     if (!zoomEventTimer.current) {
       zoomEventTimer.current = setTimeout(() => {
         zoomEventTimer.current = null
-        window[CANVAS_BRIDGE_STATE_KEY] = { active: true, canvasId, zoom: zoomRef.current }
+        const bridge = window[CANVAS_BRIDGE_STATE_KEY] || {}
+        bridge.active = true
+        bridge.canvasId = canvasId
+        bridge.zoom = zoomRef.current
+        window[CANVAS_BRIDGE_STATE_KEY] = bridge
         document.dispatchEvent(new CustomEvent('storyboard:canvas:zoom-changed', {
           detail: { zoom: zoomRef.current }
         }))
@@ -1441,7 +1868,11 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
   // Signal canvas mount/unmount to CoreUIBar
   useEffect(() => {
-    window[CANVAS_BRIDGE_STATE_KEY] = { active: true, canvasId, zoom: zoomRef.current }
+    const bridge = window[CANVAS_BRIDGE_STATE_KEY] || {}
+    bridge.active = true
+    bridge.canvasId = canvasId
+    bridge.zoom = zoomRef.current
+    window[CANVAS_BRIDGE_STATE_KEY] = bridge
     document.dispatchEvent(new CustomEvent('storyboard:canvas:mounted', {
       detail: { canvasId, zoom: zoomRef.current }
     }))
@@ -1461,14 +1892,15 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   }, [canvasId])
 
   // Tell the Vite dev server to suppress full-reloads while this canvas is active.
-  // The ?canvas-hmr URL param opts out of the guard for canvas UI development.
+  // Controlled by the "canvas-auto-reload" feature flag (default: false = guard ON).
+  // When the flag is true, the guard is skipped so canvas pages receive HMR updates.
   // Sends a heartbeat every 3s so the guard auto-expires if the tab closes.
   useEffect(() => {
     if (!import.meta.hot) return
-    const hmrEnabled = new URLSearchParams(window.location.search).has('canvas-hmr')
-    if (hmrEnabled) return
+    const autoReload = getFlag('canvas-auto-reload')
+    if (autoReload) return
 
-    const msg = { active: true, hmrEnabled: false }
+    const msg = { active: true }
     import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
     const interval = setInterval(() => {
       import.meta.hot.send('storyboard:canvas-hmr-guard', msg)
@@ -1476,7 +1908,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
     return () => {
       clearInterval(interval)
-      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false, hmrEnabled: true })
+      import.meta.hot.send('storyboard:canvas-hmr-guard', { active: false })
     }
   }, [canvasId])
 
@@ -1510,7 +1942,8 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
     function sendFocus() {
       const { widgetIds, widgets } = getSelectedWidgetData()
-      import.meta.hot.send('storyboard:canvas-focused', { tabId, canvasId, widgetIds, widgets })
+      const viewport = getViewportData()
+      import.meta.hot.send('storyboard:canvas-focused', { tabId, canvasId, widgetIds, widgets, viewport })
     }
 
     sendFocus()
@@ -1537,21 +1970,29 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     const tabId = selectionTabIdRef.current
     const timer = setTimeout(() => {
       const { widgetIds, widgets } = getSelectedWidgetData()
-      import.meta.hot.send('storyboard:selection-changed', { tabId, canvasId, widgetIds: widgetIds, widgets })
+      const viewport = getViewportData()
+      import.meta.hot.send('storyboard:selection-changed', { tabId, canvasId, widgetIds: widgetIds, widgets, viewport })
     }, 500)
 
     return () => clearTimeout(timer)
   }, [selectedWidgetIds, canvasId, getSelectedWidgetData])
 
   // Add a widget by type — used by CanvasControls and CoreUIBar event
-  const addWidget = useCallback(async (type) => {
+  const addWidget = useCallback(async (type, extraProps = {}) => {
     const defaultProps = schemas[type] ? getDefaults(schemas[type]) : {}
+    // For terminal/agent, apply config-based dimension defaults over schema defaults
+    if (type === 'terminal' || type === 'agent') {
+      const dims = getTerminalDimensions(extraProps.agentId, { width: defaultProps.width ?? 800, height: defaultProps.height ?? 450 })
+      defaultProps.width = dims.width
+      defaultProps.height = dims.height
+    }
+    const mergedProps = { ...defaultProps, ...extraProps }
     const center = getViewportCenter(scrollRef.current, zoomRef.current / 100)
-    const pos = centerPositionForWidget(center, type, defaultProps)
+    const pos = centerPositionForWidget(center, type, mergedProps)
     try {
       const result = await addWidgetApi(canvasId, {
         type,
-        props: defaultProps,
+        props: mergedProps,
         position: pos,
       })
       if (result.success && result.widget) {
@@ -1585,21 +2026,27 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     }
   }, [canvasId, undoRedo])
 
-  // Listen for CoreUIBar add-widget events
+  // Listen for CoreUIBar add-widget and update-widget events
   useEffect(() => {
     function handleAddWidget(e) {
-      addWidget(e.detail.type)
+      addWidget(e.detail.type, e.detail.props)
     }
     function handleAddStoryWidget(e) {
       addStoryWidget(e.detail.storyId)
     }
+    function handleUpdateWidget(e) {
+      const { widgetId, updates } = e.detail || {}
+      if (widgetId && updates) handleWidgetUpdate(widgetId, updates)
+    }
     document.addEventListener('storyboard:canvas:add-widget', handleAddWidget)
     document.addEventListener('storyboard:canvas:add-story-widget', handleAddStoryWidget)
+    document.addEventListener('storyboard:canvas:update-widget', handleUpdateWidget)
     return () => {
       document.removeEventListener('storyboard:canvas:add-widget', handleAddWidget)
       document.removeEventListener('storyboard:canvas:add-story-widget', handleAddStoryWidget)
+      document.removeEventListener('storyboard:canvas:update-widget', handleUpdateWidget)
     }
-  }, [addWidget, addStoryWidget])
+  }, [addWidget, addStoryWidget, handleWidgetUpdate])
 
   // Listen for zoom changes from CoreUIBar
   useEffect(() => {
@@ -1679,7 +2126,8 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
       // Find the zoom level that fits the bounding box in the viewport
       const fitScale = Math.min(viewW / boxW, viewH / boxH)
-      const fitZoom = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Math.round(fitScale * 100)))
+      const { ZOOM_MIN: zMin, ZOOM_MAX: zMax } = zoomLimits()
+      const fitZoom = Math.min(zMax, Math.max(zMin, Math.round(fitScale * 100)))
       const newScale = fitZoom / 100
 
       // Imperative DOM update — same path as applyZoom
@@ -1722,12 +2170,26 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
   // Broadcast zoom level to CoreUIBar whenever it changes
   useEffect(() => {
-    window[CANVAS_BRIDGE_STATE_KEY] = { active: true, canvasId, zoom }
+    const bridge = window[CANVAS_BRIDGE_STATE_KEY] || {}
+    bridge.active = true
+    bridge.canvasId = canvasId
+    bridge.zoom = zoom
+    window[CANVAS_BRIDGE_STATE_KEY] = bridge
     document.dispatchEvent(new CustomEvent('storyboard:canvas:zoom-changed', {
       detail: { zoom }
     }))
   }, [canvasId, zoom])
 
+  // Keep bridge in sync with widgets/connectors for expand features.
+  // Child widgets now use props directly for split-screen gating, but
+  // FigmaEmbed/PrototypeEmbed/etc. still read this bridge at expand time.
+  useMemo(() => {
+    const bridge = window[CANVAS_BRIDGE_STATE_KEY] || {}
+    bridge.widgets = localWidgets
+    bridge.connectors = localConnectors
+    window[CANVAS_BRIDGE_STATE_KEY] = bridge
+  }, [localWidgets, localConnectors])
+
   // Delete selected widget on Delete/Backspace key
   useEffect(() => {
     function handleSelectStart(e) {
@@ -1765,6 +2227,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           // Multi-delete — snapshot once, remove all, persist via updateCanvas
           undoRedo.snapshot(stateRef.current, 'multi-remove')
           debouncedSave.cancel()
+          dirtyRef.current = true
           setLocalWidgets((prev) => {
             if (!prev) return prev
             const next = prev.filter(w => !selectedWidgetIds.has(w.id))
@@ -1857,6 +2320,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           undoRedo.snapshot(stateRef.current, 'add')
           setLocalWidgets((prev) => [...(prev || []), result.widget])
           setSelectedWidgetIds(new Set([result.widget.id]))
+          navigator.clipboard?.writeText(result.widget.id).catch(() => {})
         }
         return true
       } catch (err) {
@@ -1948,9 +2412,18 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           for (const w of sourceWidgets) {
             const relX = (w.position?.x ?? 0) - minX
             const relY = (w.position?.y ?? 0) - minY
+            const pasteProps = { ...w.props }
+            if (w.type === 'terminal' || w.type === 'agent') delete pasteProps.prettyName
+            // Image widgets: duplicate the asset so the paste owns its own copy
+            if (w.type === 'image' && pasteProps.src) {
+              try {
+                const dupResult = await duplicateImage(pasteProps.src)
+                if (dupResult.success) pasteProps.src = dupResult.filename
+              } catch { /* use original src as fallback */ }
+            }
             const result = await addWidgetApi(canvasId, {
               type: w.type,
-              props: { ...w.props },
+              props: pasteProps,
               position: { x: baseX + relX, y: baseY + relY },
             })
             if (result.success && result.widget) {
@@ -1970,11 +2443,34 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       }
 
       e.preventDefault()
+      await pasteTextAsWidget(text, pasteCtx)
+    }
+
+    // Shared helper: resolve pasted text into a widget and add it to the canvas.
+    // Used by both native paste and the programmatic paste-url event.
+    async function pasteTextAsWidget(text, pasteCtx) {
       const resolved = resolvePaste(text, pasteCtx, getPasteRules())
       if (!resolved) return
-      const { type } = resolved
+      let { type } = resolved
       let props = resolved.props
 
+      // Component/story URLs → story widget (instead of prototype embed)
+      if (type === 'prototype' && props?.src) {
+        const srcPath = props.src.replace(/[?#].*$/, '').replace(/\/+$/, '')
+        const storyId = storyRouteIndex.get(srcPath)
+        if (storyId) {
+          type = 'story'
+          const parsed = pasteCtx.parseUrl(text)
+          const searchParams = new URLSearchParams(parsed?.search || '')
+          props = {
+            storyId,
+            exportName: searchParams.get('export') || '',
+            width: 600,
+            height: 400,
+          }
+        }
+      }
+
       if (type === 'link-preview' && isGitHubEmbedUrl(props?.url || text)) {
         const githubUpdates = await buildGitHubPreviewUpdates(props?.url || text)
         if (githubUpdates) props = { ...props, ...githubUpdates }
@@ -1998,8 +2494,19 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
       }
     }
 
+    // Listen for programmatic paste-url events from the command palette
+    function handlePasteUrl(e) {
+      const text = e.detail?.url?.trim()
+      if (!text) return
+      pasteTextAsWidget(text, pasteCtx)
+    }
+
     document.addEventListener('paste', handlePaste)
-    return () => document.removeEventListener('paste', handlePaste)
+    document.addEventListener('storyboard:canvas:paste-url', handlePasteUrl)
+    return () => {
+      document.removeEventListener('paste', handlePaste)
+      document.removeEventListener('storyboard:canvas:paste-url', handlePasteUrl)
+    }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [canvasId, undoRedo, localWidgets])
 
@@ -2073,13 +2580,13 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     if (!previous) return
     debouncedSave.cancel()
     debouncedSourceSave.cancel()
+    dirtyRef.current = true
     setLocalWidgets(previous.widgets)
     setLocalSources(previous.sources)
     setLocalConnectors(previous.connectors ?? [])
     queueWrite(() =>
-      updateCanvas(canvasId, { widgets: previous.widgets, sources: previous.sources, connectors: previous.connectors }).catch((err) =>
-        console.error('[canvas] Failed to persist undo:', err)
-      )
+      updateCanvas(canvasId, { widgets: previous.widgets, sources: previous.sources, connectors: previous.connectors })
+        .catch((err) => console.error('[canvas] Failed to persist undo:', err))
     )
   }, [canvasId, debouncedSave, debouncedSourceSave, undoRedo])
 
@@ -2088,22 +2595,24 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     if (!next) return
     debouncedSave.cancel()
     debouncedSourceSave.cancel()
+    dirtyRef.current = true
     setLocalWidgets(next.widgets)
     setLocalSources(next.sources)
     setLocalConnectors(next.connectors ?? [])
     queueWrite(() =>
-      updateCanvas(canvasId, { widgets: next.widgets, sources: next.sources, connectors: next.connectors }).catch((err) =>
-        console.error('[canvas] Failed to persist redo:', err)
-      )
+      updateCanvas(canvasId, { widgets: next.widgets, sources: next.sources, connectors: next.connectors })
+        .catch((err) => console.error('[canvas] Failed to persist redo:', err))
     )
   }, [canvasId, debouncedSave, debouncedSourceSave, undoRedo])
 
-  // Keyboard shortcuts — dev-only (Cmd+Z / Cmd+Shift+Z)
+  // Keyboard shortcuts — dev-only (Cmd+Z / Cmd+Shift+Z / Cmd+D / Cmd+A)
   useEffect(() => {
     if (!import.meta.hot) return
     function handleKeyDown(e) {
       const tag = e.target.tagName
       if (tag === 'INPUT' || tag === 'TEXTAREA' || e.target.isContentEditable) return
+      // Don't intercept shortcuts when the command palette is open
+      if (e.target.closest?.('[cmdk-root]')) return
       const mod = e.metaKey || e.ctrlKey
       if (mod && e.key === 'z' && !e.shiftKey) {
         e.preventDefault()
@@ -2113,10 +2622,21 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         e.preventDefault()
         handleRedo()
       }
+      if (mod && e.key.toLowerCase() === 'd' && e.shiftKey) {
+        e.preventDefault()
+        handleDuplicateWithConnectors()
+      } else if (mod && e.key.toLowerCase() === 'd' && !e.shiftKey) {
+        e.preventDefault()
+        handleDuplicateSelected()
+      }
+      if (mod && e.key === 'a') {
+        e.preventDefault()
+        handleSelectAll()
+      }
     }
     document.addEventListener('keydown', handleKeyDown)
     return () => document.removeEventListener('keydown', handleKeyDown)
-  }, [handleUndo, handleRedo])
+  }, [handleUndo, handleRedo, handleDuplicateSelected, handleDuplicateWithConnectors, handleSelectAll])
 
   // Listen for undo/redo from CoreUIBar (Svelte toolbar)
   useEffect(() => {
@@ -2286,6 +2806,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
     zoomRef: zoomRef,
     setSelectedWidgetIds,
     widgets: localWidgets,
+    connectors: localConnectors,
     componentEntries,
     fallbackSizes: WIDGET_FALLBACK_SIZES,
     spaceHeld,
@@ -2343,6 +2864,7 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
         id={`jsx-${exportName}`}
         data-tc-x={sourcePosition.x}
         data-tc-y={sourcePosition.y}
+        data-widget-raised={selectedWidgetIds.has(`jsx-${exportName}`) || undefined}
         {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle, .tc-drag-surface' } : {})}
         {...canvasPrimerAttrs}
         style={canvasThemeVars}
@@ -2379,38 +2901,44 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
   }
 
   // 2. JSON-defined mutable widgets (selectable, wrapped in WidgetChrome)
-  // Sort so selected widgets render last (visually on top via DOM order)
-  const sortedWidgets = (localWidgets ?? []).slice().sort((a, b) => {
-    const aSelected = selectedWidgetIds.has(a.id) ? 1 : 0
-    const bSelected = selectedWidgetIds.has(b.id) ? 1 : 0
-    return aSelected - bSelected
-  })
-  for (const widget of sortedWidgets) {
-    if (!isLocalDev && widget.type === 'terminal') continue
+  // Stable DOM order — visual stacking is controlled by z-index on the
+  // wrapper div (data-widget-raised), NOT by re-sorting the array.
+  // Re-sorting caused iframe widgets (stories, embeds) to remount and
+  // reload every time selection changed, because moving an iframe node
+  // in the DOM destroys its browsing context.
+  for (const widget of (localWidgets ?? [])) {
+    // In production, render terminal widgets as read-only instead of hiding them
+    const effectiveWidget = (!isLocalDev && (widget.type === 'terminal' || widget.type === 'agent'))
+      ? { ...widget, type: 'terminal-read' }
+      : widget
     allChildren.push(
       <div
-        key={widget.id}
-        id={widget.id}
-        data-tc-x={widget?.position?.x ?? 0}
-        data-tc-y={widget?.position?.y ?? 0}
+        key={effectiveWidget.id}
+        id={effectiveWidget.id}
+        data-tc-x={effectiveWidget?.position?.x ?? 0}
+        data-tc-y={effectiveWidget?.position?.y ?? 0}
+        data-widget-raised={selectedWidgetIds.has(widget.id) || undefined}
         {...(isLocalDev ? { 'data-tc-handle': '.tc-drag-handle, .tc-drag-surface' } : {})}
         {...canvasPrimerAttrs}
         style={canvasThemeVars}
         onClick={isLocalDev ? (e) => {
           e.stopPropagation()
           if (!e.target.closest('.tc-drag-handle')) {
-            handleWidgetSelect(widget.id, e.shiftKey)
+            handleWidgetSelect(effectiveWidget.id, e.shiftKey)
           }
         } : undefined}
       >
         <ChromeWrappedWidget
-          widget={widget}
+          widget={effectiveWidget}
           selected={selectedWidgetIds.has(widget.id)}
           multiSelected={isMultiSelected && selectedWidgetIds.has(widget.id)}
+          connectorCount={localConnectors.filter((c) => c.start?.widgetId === widget.id || c.end?.widgetId === widget.id)}
+          allWidgets={localWidgets}
           onSelect={(shiftKey) => handleWidgetSelect(widget.id, shiftKey)}
           onDeselect={handleDeselectAll}
           onUpdate={isLocalDev ? handleWidgetUpdate : undefined}
           onCopy={isLocalDev ? handleWidgetCopy : undefined}
+          onCopyWithConnectors={isLocalDev ? handleWidgetCopyWithConnectors : undefined}
           onRemove={isLocalDev ? handleWidgetRemoveAndDeselect : undefined}
           onRefreshGitHub={isLocalDev ? handleRefreshGitHubWidget : undefined}
           canRefreshGitHub={isLocalDev}
@@ -2423,19 +2951,13 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
 
   const scale = zoom / 100
 
-  const terminalWidgetIds = !isLocalDev 
-    ? new Set((localWidgets ?? []).filter(w => w.type === 'terminal').map(w => w.id))
-    : null
-
-  const filteredConnectors = terminalWidgetIds?.size
-    ? localConnectors.filter(c => !terminalWidgetIds.has(c.startWidgetId) && !terminalWidgetIds.has(c.endWidgetId))
-    : localConnectors
+  const filteredConnectors = localConnectors
 
   return (
     <>
       <div className={styles.canvasTitle}>
         <a href={(import.meta.env?.BASE_URL || '/')} className={styles.canvasLogo} aria-label="Go to homepage">
-          <Icon name="iconoir/key-command" size={16} color="#fff" />
+          <Icon name="home" size={16} color="#fff" />
         </a>
         <CanvasTitleEditable
           canvasId={canvasId}
@@ -2444,9 +2966,6 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           isLocalDev={isLocalDev}
         />
         <PageSelector currentName={canvasId} pages={siblingPages} isLocalDev={isLocalDev} />
-        {isLocalDev && (
-          <span className={styles.localEditingLabel}>Local editing</span>
-        )}
       </div>
       <div
         ref={scrollRef}
@@ -2477,8 +2996,9 @@ export default function CanvasPage({ canvasId: canvasIdProp, name, siblingPages
           <ConnectorLayer
             connectors={filteredConnectors}
             widgets={localWidgets ?? []}
+            selectedWidgetIds={selectedWidgetIds}
             onRemove={isLocalDev ? handleConnectorRemove : undefined}
-            onEndpointDrag={isLocalDev ? handleEndpointDrag : undefined}
+            onEndpointDrag={undefined}
             dragPreview={connectorDrag}
             hidden={widgetDragging}
           />