synabun 1.3.0 → 2.0.0

package/neural-interface/public/shared/ui-whiteboard.js

@@ -11,12 +11,26 @@ import { state, emit, on } from './state.js';
 import { KEYS } from './constants.js';
 import { storage } from './storage.js';
 import { isGuest, hasPermission } from './ui-sync.js';
+import { openSettingsModal } from './ui-settings.js';
+import { fetchRulesStatus } from './api.js';
 
 // ── Helpers ──
 
 const $ = (id) => document.getElementById(id);
 const _genId = () => 'wb-' + Date.now() + '-' + Math.random().toString(36).slice(2, 5);
 
+// Stable per-tab id (survives reloads via sessionStorage). Sent with every
+// viewport/geometry/screenshot message so the server can tell windows apart
+// and pick the focus-active one for MCP coordinate math + screenshots.
+const _clientId = (() => {
+  const fresh = () => 'wbc-' + Math.random().toString(36).slice(2, 10);
+  try {
+    let id = sessionStorage.getItem('wb-client-id');
+    if (!id) { id = fresh(); sessionStorage.setItem('wb-client-id', id); }
+    return id;
+  } catch { return fresh(); }
+})();
+
 // ── Internal state ──
 
 let _elements = [];      // Array<{id, type, x, y, width, height, ...}>
@@ -79,19 +93,31 @@ const SECTION_TYPES = {
 
 // Persist debounce + cross-client sync
 let _persistTimer = null;
-let _isRemoteUpdate = false; // Suppress WS echo when receiving remote state
 const PERSIST_DELAY = 600;
 const MAX_UNDO = 50;
 const SNAP_DIST = 30;    // px for arrow anchor snapping
 const MAX_IMAGE_DIM = 1920;
 
-/** Cross-browser clipboard write with fallback for non-secure contexts. */
+// Rendered-size measurement for auto-sized text/list cards (see _runMeasurePass)
+let _measureScheduled = false;
+let _measurePending = false;        // a pass was skipped mid-gesture; run it at mouseup
+const _geometryDirty = new Map();   // id → { id, width, height } awaiting send to the server
+let _geometryTimer = null;
+const GEOMETRY_SEND_DELAY = 250;
+
+/**
+ * Cross-browser clipboard write with fallback for non-secure contexts.
+ * Returns a Promise that resolves true on success, false on failure — callers
+ * need this to show accurate feedback (a silent failure is how the "Copy image
+ * path" button used to claim success while the OS clipboard was empty).
+ */
 function _clipboardWrite(text) {
   if (navigator.clipboard?.writeText) {
-    navigator.clipboard.writeText(text).catch(() => _clipboardFallback(text));
-  } else {
-    _clipboardFallback(text);
+    return navigator.clipboard.writeText(text)
+      .then(() => true)
+      .catch(() => _clipboardFallback(text));
   }
+  return Promise.resolve(_clipboardFallback(text));
 }
 function _clipboardFallback(text) {
   const ta = document.createElement('textarea');
@@ -99,8 +125,10 @@ function _clipboardFallback(text) {
   ta.style.cssText = 'position:fixed;left:-9999px;top:-9999px;opacity:0';
   document.body.appendChild(ta);
   ta.select();
-  try { document.execCommand('copy'); } catch {}
+  let ok = false;
+  try { ok = document.execCommand('copy'); } catch {}
   ta.remove();
+  return ok;
 }
 
 /** Snap a value to grid if grid snapping is enabled. */
@@ -114,13 +142,93 @@ const IMAGE_QUALITY = 0.8;
 // DOM refs (set in init)
 let _root, _toolbar, _canvas, _arrowsSvg, _elementsDiv, _arrowPreview, _arrowHint;
 
+// The rules reminder beside the logo: shown only while a connected tool has no
+// SynaBun rules, an edited copy or damaged markers (GET /api/setup/rules).
+const RULES_REMINDER_STATES = ['not-installed', 'modified', 'conflict'];
+let _rulesReminderSections = []; // Settings > Setup sections of the tools that need attention
+
 
 // ═══════════════════════════════════════════
 // COORDINATE TRANSFORMS
 // ═══════════════════════════════════════════
 
+// Cached _root rect. Reading getBoundingClientRect() inside mousemove (60Hz)
+// forces a layout flush. We capture it once at drag/pen/marquee start and
+// reuse it for the rest of the gesture, then invalidate on mouseup/resize/scroll.
+let _rootRectCached = null;
+
+function _getRootRect() {
+  if (_rootRectCached) return _rootRectCached;
+  if (!_root) return { left: 0, top: 0, width: 0, height: 0, right: 0, bottom: 0 };
+  _rootRectCached = _root.getBoundingClientRect();
+  return _rootRectCached;
+}
+
+function _invalidateRootRect() {
+  _rootRectCached = null;
+}
+
+/**
+ * Abort any in-flight pointer gesture. Called whenever the board state is
+ * replaced under the user (state:full from another client, workspace restore,
+ * clear) and when a mouseup can no longer reach us (window blur / hidden tab),
+ * so a stale _drag/_marquee/_penPoints/_shapeCreating flag can never swallow
+ * every subsequent mousemove. `pointerOnly` keeps a multi-click arrow in
+ * progress (its waypoints survive an alt-tab; Escape still cancels it).
+ */
+function _cancelGesture({ pointerOnly = false } = {}) {
+  let needsRender = false;
+  if (_drag) {
+    // Positions already mutated by mousemove stay where they are — make sure
+    // they reach the server even though no mouseup will finalize them.
+    _drag = null;
+    persistDebounced();
+  }
+  if (_marquee) {
+    _marquee.rect?.remove();
+    _marquee = null;
+  }
+  if (_shapeCreating) {
+    _elements = _elements.filter(el => el.id !== _shapeCreating.id);
+    _shapeCreating = null;
+    needsRender = true;
+  }
+  if (_sectionCreating) {
+    _elements = _elements.filter(el => el.id !== _sectionCreating.id);
+    _sectionCreating = null;
+    needsRender = true;
+  }
+  if (_penLiveEl) _penLiveEl.remove();
+  _penLiveEl = null;
+  _penPoints = null;
+  if (!pointerOnly) {
+    _arrowCreating = null;
+    clearArrowPreview();
+    hideArrowHint();
+  }
+  document.body.classList.remove('ui-interacting');
+  _invalidateRootRect();
+  _invalidateElementMap();
+  if (needsRender) renderAll();
+}
+
+/**
+ * Prepare for a whole-board replacement (restore / clear / remote state:full):
+ * optionally commit + exit text/list editing, abort gestures, drop selection UI.
+ */
+function _beginStateReplace({ exitEdits = false } = {}) {
+  if (exitEdits) {
+    exitEditMode();
+    exitListEditMode();
+  }
+  _cancelGesture();
+  hideContextMenu();
+  _selectedId = null;
+  _selectedIds.clear();
+}
+
 function clientToCanvas(clientX, clientY) {
-  const rect = _root.getBoundingClientRect();
+  const rect = _getRootRect();
   return {
     x: clientX - rect.left,
     y: clientY - rect.top,
@@ -160,10 +268,22 @@ function undo() {
   } else if (entry.action === 'move' || entry.action === 'resize' || entry.action === 'edit') {
     const idx = _elements.findIndex(el => el.id === entry.before.id);
     if (idx >= 0) _elements[idx] = { ...entry.before };
+  } else if (entry.action === 'batch') {
+    // Reverse an external batch: restore removed, restore updated befores, drop added
+    for (const el of entry.before.removed) _elements.push({ ...el });
+    for (const snap of entry.before.updated) {
+      const idx = _elements.findIndex(el => el.id === snap.id);
+      if (idx >= 0) _elements[idx] = { ...snap, points: snap.points ? snap.points.map(p => [...p]) : undefined };
+    }
+    if (entry.before.added.length) {
+      const ids = new Set(entry.before.added);
+      _elements = _elements.filter(el => !ids.has(el.id));
+    }
   }
 
   _selectedId = null;
   _selectedIds.clear();
+  _invalidateElementMap();
   renderAll();
   persistDebounced();
   updateUndoButtons();
@@ -193,10 +313,22 @@ function redo() {
     const idx = _elements.findIndex(el => el.id === entry.after.id);
     if (idx >= 0) _elements[idx] = { ...entry.after };
     else _elements.push({ ...entry.after });
+  } else if (entry.action === 'batch') {
+    const removedIds = new Set(entry.before.removed.map(el => el.id));
+    if (removedIds.size) _elements = _elements.filter(el => !removedIds.has(el.id));
+    for (const snap of entry.after.updated) {
+      const idx = _elements.findIndex(el => el.id === snap.id);
+      const copy = { ...snap, points: snap.points ? snap.points.map(p => [...p]) : undefined };
+      if (idx >= 0) _elements[idx] = copy; else _elements.push(copy);
+    }
+    for (const el of entry.after.added) {
+      if (!_elements.some(e => e.id === el.id)) _elements.push({ ...el });
+    }
   }
 
   _selectedId = null;
   _selectedIds.clear();
+  _invalidateElementMap();
   renderAll();
   persistDebounced();
   updateUndoButtons();
@@ -209,6 +341,64 @@ function updateUndoButtons() {
   if (redoBtn) redoBtn.classList.toggle('disabled', !_redoStack.length);
 }
 
+function isRulesetAlertDismissed() {
+  return storage.getItem(KEYS.WHITEBOARD_RULESET_ALERT_DISMISSED) === '1';
+}
+
+function syncRulesetAlertVisibility() {
+  const alert = $('wb-ruleset-alert');
+  if (!alert) return;
+  const logo = document.querySelector('#static-bg .static-bg-logo');
+  const logoHidden = logo?.style.display === 'none';
+  alert.classList.toggle('hidden', isRulesetAlertDismissed() || logoHidden || _rulesReminderSections.length === 0);
+}
+
+// Which connected tools need their rules looked at. A tool the user opted out
+// of (managed === false) is not nagged about; an unknown status (no route, a
+// failed request, a guest) shows nothing.
+function applyRulesStatusToAlert(status) {
+  const hosts = status?.ok && status.hosts ? status.hosts : {};
+  _rulesReminderSections = Object.entries(hosts)
+    .filter(([, info]) => info?.mcp && RULES_REMINDER_STATES.includes(info.state) && !(info.state === 'not-installed' && info.managed === false))
+    .map(([host]) => `setup-${host}`);
+  syncRulesetAlertVisibility();
+}
+
+async function refreshRulesetAlert() {
+  if (isRulesetAlertDismissed()) return;
+  applyRulesStatusToAlert(await fetchRulesStatus());
+}
+
+function initRulesetAlert() {
+  const alert = $('wb-ruleset-alert');
+  if (!alert) return;
+
+  const setupBtn = $('wb-ruleset-settings');
+  const dismissBtn = $('wb-ruleset-dismiss');
+
+  setupBtn?.addEventListener('click', (e) => {
+    e.stopPropagation();
+    openSettingsModal({
+      tab: 'ai-connections',
+      expand: ['setup-rules', ..._rulesReminderSections],
+      highlight: _rulesReminderSections.length ? _rulesReminderSections : ['setup-rules'],
+      scrollTo: 'setup-rules',
+    });
+  });
+
+  dismissBtn?.addEventListener('click', (e) => {
+    e.stopPropagation();
+    storage.setItem(KEYS.WHITEBOARD_RULESET_ALERT_DISMISSED, '1');
+    syncRulesetAlertVisibility();
+  });
+
+  // Settings > Setup passes the fresh status on after every rules action.
+  on('rules:changed', applyRulesStatusToAlert);
+
+  syncRulesetAlertVisibility();
+  refreshRulesetAlert();
+}
+
 
 // ═══════════════════════════════════════════
 // PERSISTENCE
@@ -218,7 +408,7 @@ function updateUndoButtons() {
 function flushListEdits() {
   const dom = _root?.querySelector('.wb-list.editing');
   if (!dom) return;
-  const ul = dom.querySelector('ul');
+  const ul = dom.querySelector('ul, ol');
   const elId = dom.dataset.wbId;
   const el = _elements.find(e => e.id === elId);
   if (el && ul) {
@@ -244,22 +434,35 @@ function persistDebounced() {
     flushTextEdits();
     flushListEdits();
     const snapshot = { elements: _elements, nextZIndex: _nextZIndex };
-    storage.setItem(KEYS.WHITEBOARD, JSON.stringify(snapshot));
-    // Send to server for cross-client sync (skip if remote update or guest without whiteboard perm)
-    if (_ws && _ws.readyState === 1 && !_isRemoteUpdate && !(isGuest() && !hasPermission('whiteboard'))) {
+    // Guest edits without whiteboard permission never persist. (Remote-originated
+    // changes never reach here: the external command handlers don't persist.)
+    if (isGuest() && !hasPermission('whiteboard')) return;
+    if (_ws && _ws.readyState === 1) {
+      // Live cross-client relay + server persistence (saveWhiteboard) in one.
+      // The whiteboard no longer rides the ui-state PATCH cycle.
       _ws.send(JSON.stringify({ type: 'state:sync', snapshot }));
+    } else {
+      // Socket down — persist via REST so a reload doesn't lose the edit.
+      fetch('/api/whiteboard', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(snapshot),
+      }).catch(() => {});
     }
   }, PERSIST_DELAY);
 }
 
-function loadPersisted() {
+async function loadPersisted() {
+  // Board now lives in its own server store (data/whiteboard.json), not in the
+  // client storage / ui-state PATCH cycle. Fetch it on init.
   try {
-    const raw = storage.getItem(KEYS.WHITEBOARD);
-    if (!raw) return;
-    const data = JSON.parse(raw);
+    const res = await fetch('/api/whiteboard');
+    if (!res.ok) return;
+    const data = await res.json();
     if (Array.isArray(data.elements)) _elements = data.elements;
     if (data.nextZIndex) _nextZIndex = data.nextZIndex;
-  } catch { /* ignore corrupt data */ }
+    _invalidateElementMap();
+  } catch { /* server unreachable — start empty */ }
 }
 
 
@@ -290,14 +493,44 @@ function shortenPoints(pts, amount) {
   return result;
 }
 
+/** Box size for anchor/centre math. Prefers the stored size — for text/list
+ *  cards that is the browser-measured (or server-estimated) footprint — and
+ *  only falls back to the legacy 100x60 phantom when nothing is stored. */
+function _elBox(el) {
+  return {
+    w: el.width > 0 ? el.width : 100,
+    h: el.height > 0 ? el.height : 60,
+  };
+}
+
+/** Anchor-adjusted copy of an arrow's points — the exact geometry the DOM
+ *  renders. Shared by renderArrows, the drag fast path and the screenshot so
+ *  the three can never disagree. Resolution is progressive on the same copy
+ *  (a 2-point arrow's end is aimed at the resolved start); the server-side
+ *  port in mcp-server/src/services/whiteboard-geometry.ts mirrors this. */
+function resolveArrowPoints(el) {
+  const pts = (el.points || []).map(p => [...p]);
+  if (pts.length < 2) return pts;
+  if (el.startAnchor) {
+    const pt = getAnchorPoint(el.startAnchor, pts[1][0], pts[1][1]);
+    if (pt) pts[0] = [pt.x, pt.y];
+  }
+  if (el.endAnchor) {
+    const pt = getAnchorPoint(el.endAnchor, pts[pts.length - 2][0], pts[pts.length - 2][1]);
+    if (pt) pts[pts.length - 1] = [pt.x, pt.y];
+  }
+  return pts;
+}
+
 /** Get arrow endpoint from an anchored element. Returns edge intersection point. */
 function getAnchorPoint(anchorId, fromX, fromY) {
-  const el = _elements.find(e => e.id === anchorId);
+  const el = _findEl(anchorId);
   if (!el || el.type === 'arrow') return null;
-  const cx = el.x + (el.width || 100) / 2;
-  const cy = el.y + (el.height || 60) / 2;
-  const hw = (el.width || 100) / 2;
-  const hh = (el.height || 60) / 2;
+  const { w, h } = _elBox(el);
+  const cx = el.x + w / 2;
+  const cy = el.y + h / 2;
+  const hw = w / 2;
+  const hh = h / 2;
 
   const dx = fromX - cx;
   const dy = fromY - cy;
@@ -320,8 +553,9 @@ function findNearestAnchor(cx, cy, excludeId) {
   let bestDist = SNAP_DIST;
   for (const el of _elements) {
     if (el.type === 'arrow' || el.id === excludeId) continue;
-    const ecx = el.x + (el.width || 100) / 2;
-    const ecy = el.y + (el.height || 60) / 2;
+    const box = _elBox(el);
+    const ecx = el.x + box.w / 2;
+    const ecy = el.y + box.h / 2;
     const d = Math.sqrt((cx - ecx) ** 2 + (cy - ecy) ** 2);
     if (d < bestDist) {
       bestDist = d;
@@ -331,6 +565,19 @@ function findNearestAnchor(cx, cy, excludeId) {
   return best;
 }
 
+/** Ids of arrows anchored (start or end) to any element id in `movedIds`.
+ *  Precomputed at drag start so the per-frame fast path only re-routes the
+ *  handful of arrows actually pinned to the element(s) being moved. */
+function _anchoredArrowIds(movedIds) {
+  const set = movedIds instanceof Set ? movedIds : new Set(movedIds);
+  const out = [];
+  for (const a of _elements) {
+    if (a.type !== 'arrow') continue;
+    if (set.has(a.startAnchor) || set.has(a.endAnchor)) out.push(a.id);
+  }
+  return out;
+}
+
 
 // ═══════════════════════════════════════════
 // IMAGE COMPRESSION
@@ -366,13 +613,60 @@ function compressImage(blob) {
 // RENDERING
 // ═══════════════════════════════════════════
 
+// Element ID → element lookup cache. Rebuilt lazily; many mousemove paths
+// previously did O(n) Array.prototype.find on every event.
+//
+// The cache is SELF-VALIDATING. An earlier version keyed it on array length
+// only, so a same-count delete→add (or a whole-array replacement from a
+// workspace restore / another client's state:full) left it pointing at ghost
+// objects or missing new ids — drags silently no-op'd until the count changed
+// again (the "board is locked until I draw a pen stroke" bug). Every hit is now
+// checked against the live array by index and the map is rebuilt on any
+// mismatch, miss, identity change or length change.
+let _elementMap = null;      // Map<id, { el, idx }>
+let _elementMapSrc = null;   // the _elements array the map was built from
+let _elementMapLen = -1;
+
+function _rebuildElementMap() {
+  _elementMap = new Map();
+  for (let i = 0; i < _elements.length; i++) {
+    _elementMap.set(_elements[i].id, { el: _elements[i], idx: i });
+  }
+  _elementMapSrc = _elements;
+  _elementMapLen = _elements.length;
+}
+
+function _findEl(id) {
+  if (!id) return null;
+  if (!_elementMap || _elementMapSrc !== _elements || _elementMapLen !== _elements.length) {
+    _rebuildElementMap();
+  }
+  const hit = _elementMap.get(id);
+  if (hit && _elements[hit.idx] === hit.el) return hit.el;
+  // Stale entry (object replaced in place / same-length splice+push) or a
+  // brand-new id: rebuild once and retry.
+  _rebuildElementMap();
+  const again = _elementMap.get(id);
+  return again ? again.el : null;
+}
+
+function _invalidateElementMap() {
+  _elementMap = null;
+  _elementMapSrc = null;
+  _elementMapLen = -1;
+}
+
+// Synchronous render. Earlier perf pass tried rAF-batching this — that caused
+// visible drag lag because the move/resize/rotate mousemove paths each call
+// renderAll() once and rely on the DOM update completing before the next
+// pointer event. Keep the call synchronous; the real per-frame cost lives in
+// _findEl/_getRootRect (already optimized), not in scheduling.
 function renderAll() {
   renderElements();
   renderArrows();
-  // Reposition context menu if element(s) selected
   if (_ctxMenu && _selectedIds.size > 0) {
     if (_selectedIds.size === 1) {
-      const el = _elements.find(e => e.id === _selectedId);
+      const el = _findEl(_selectedId);
       if (el) positionContextMenu(el);
     } else {
       positionContextMenuMulti();
@@ -380,6 +674,8 @@ function renderAll() {
   }
 }
 
+function renderAllImmediate() { renderAll(); }
+
 function renderElements() {
   if (!_elementsDiv) return;
   const existing = new Map();
@@ -403,6 +699,79 @@ function renderElements() {
   for (const [id, dom] of existing) {
     if (!activeIds.has(id)) dom.remove();
   }
+
+  _scheduleMeasure();
+}
+
+// ── Rendered-size measurement (text/list auto-size) ──────────────────
+// Text and list cards size themselves from content (CSS width:max-content), so
+// their stored width/height used to be 0/undefined forever. That left the MCP
+// tools, the server's viewport clamp and arrow anchoring blind to their real
+// footprint. After every render we read the border-box size once (coalesced
+// into a single rAF pass, never during a gesture) and write it back into the
+// element, then ship it to the server as a `geometry` message. This pass never
+// pushes undo entries, never persists the board and never re-renders — no loops.
+
+function _scheduleMeasure() {
+  if (_measureScheduled) return;
+  _measureScheduled = true;
+  requestAnimationFrame(_runMeasurePass);
+}
+
+function _gestureActive() {
+  return !!(_drag || _marquee || _shapeCreating || _sectionCreating || _penPoints);
+}
+
+function _runMeasurePass() {
+  _measureScheduled = false;
+  if (!_elementsDiv) return;
+  if (_gestureActive()) { _measurePending = true; return; }
+
+  const domById = new Map();
+  for (const child of _elementsDiv.children) domById.set(child.dataset.wbId, child);
+
+  const changedIds = [];
+  for (const el of _elements) {
+    if (el.type !== 'text' && el.type !== 'list') continue;
+    const dom = domById.get(el.id);
+    if (!dom) continue;
+    if (dom.classList.contains('editing') || dom.contains(document.activeElement)) continue;
+    const w = dom.offsetWidth, h = dom.offsetHeight;   // border-box; immune to transform:rotate
+    if (!w || !h) continue;
+    if (el.measured && Math.abs((el.width || 0) - w) < 1 && Math.abs((el.height || 0) - h) < 1) continue;
+    el.width = w;
+    el.height = h;
+    el.measured = true;
+    delete el.estimated;
+    _geometryDirty.set(el.id, { id: el.id, width: w, height: h });
+    changedIds.push(el.id);
+  }
+  if (!changedIds.length) return;
+
+  // Arrows pinned to a re-measured card need re-routing (the edge intersection
+  // depends on the box) — touch only those paths, never the whole SVG.
+  for (const aid of _anchoredArrowIds(changedIds)) {
+    const a = _findEl(aid);
+    if (a) _renderOneArrowPaths(a);
+  }
+  if (_ctxMenu && _selectedIds.size === 1) {
+    const sel = _findEl(_selectedId);
+    if (sel) positionContextMenu(sel);
+  }
+  _queueGeometrySend();
+}
+
+function _queueGeometrySend() {
+  clearTimeout(_geometryTimer);
+  _geometryTimer = setTimeout(() => {
+    _geometryTimer = null;
+    if (!_geometryDirty.size) return;
+    if (isGuest() && !hasPermission('whiteboard')) { _geometryDirty.clear(); return; }
+    if (!_ws || _ws.readyState !== 1) return;   // stays dirty — flushed on the next open/pass
+    const items = [..._geometryDirty.values()];
+    _geometryDirty.clear();
+    _ws.send(JSON.stringify({ type: 'geometry', clientId: _clientId, items }));
+  }, GEOMETRY_SEND_DELAY);
 }
 
 function createElementDOM(el) {
@@ -410,11 +779,12 @@ function createElementDOM(el) {
   div.dataset.wbId = el.id;
 
   if (el.type === 'text') {
+    // No resize handle: text cards auto-size from content (width:max-content).
     div.className = 'wb-text';
-    div.innerHTML = `<div class="wb-text-content" contenteditable="false"></div><div class="wb-resize-handle"></div>`;
+    div.innerHTML = `<div class="wb-text-content" contenteditable="false"></div>`;
   } else if (el.type === 'list') {
     div.className = 'wb-list';
-    div.innerHTML = `<ul></ul><div class="wb-resize-handle"></div>`;
+    div.innerHTML = el.ordered ? '<ol></ol>' : '<ul></ul>';
   } else if (el.type === 'shape') {
     div.className = 'wb-shape';
     const ns = 'http://www.w3.org/2000/svg';
@@ -426,7 +796,8 @@ function createElementDOM(el) {
     div.appendChild(handle);
   } else if (el.type === 'image') {
     div.className = 'wb-image';
-    div.innerHTML = `<img src="" alt=""><span class="wb-copy-path" data-tooltip="Copy image path"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></span><div class="wb-resize-handle"></div>`;
+    div.setAttribute('draggable', 'false');
+    div.innerHTML = `<img src="" alt="" draggable="false"><span class="wb-copy-path" data-tooltip="Copy image path"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg></span><div class="wb-resize-handle"></div>`;
     // Wire click-to-copy-path
     const copyBtn = div.querySelector('.wb-copy-path');
     copyBtn.addEventListener('click', (e) => {
@@ -444,13 +815,21 @@ function createElementDOM(el) {
           const msg = JSON.parse(evt.data);
           if (msg.type === 'image_saved' && msg.path) {
             _ws.removeEventListener('message', handler);
-            _clipboardWrite(msg.path);
-            copyBtn.dataset.tooltip = 'Copied!';
-            copyBtn.classList.add('wb-copied');
-            setTimeout(() => {
-              copyBtn.dataset.tooltip = 'Copy image path';
-              copyBtn.classList.remove('wb-copied');
-            }, 1500);
+            Promise.resolve(_clipboardWrite(msg.path)).then((ok) => {
+              if (ok) {
+                copyBtn.dataset.tooltip = 'Copied!';
+                copyBtn.classList.add('wb-copied');
+              } else {
+                // Clipboard write silently failed (usually: page not focused,
+                // non-secure context, or browser permission). Surface it so
+                // the user doesn't paste an empty clipboard into the CLI.
+                copyBtn.dataset.tooltip = 'Copy blocked — focus page & retry';
+              }
+              setTimeout(() => {
+                copyBtn.dataset.tooltip = 'Copy image path';
+                copyBtn.classList.remove('wb-copied');
+              }, 1800);
+            });
           }
         } catch {}
       };
@@ -483,19 +862,34 @@ function updateElementDOM(dom, el) {
   if (el.type === 'text') {
     const content = dom.querySelector('.wb-text-content');
     if (content && !content.matches(':focus')) {
-      content.innerText = el.content || '';
+      // Skip the write when unchanged — this runs on every drag frame and
+      // setting innerText forces a layout.
+      const key = el.content || '';
+      if (dom._wbTextKey !== key) { content.innerText = key; dom._wbTextKey = key; }
     }
     if (el.fontSize) dom.style.fontSize = el.fontSize + 'px';
     dom.style.fontWeight = el.bold ? '700' : '400';
     dom.style.fontStyle = el.italic ? 'italic' : 'normal';
     if (el.color) dom.style.color = el.color;
   } else if (el.type === 'list') {
-    const ul = dom.querySelector('ul');
-    if (ul && !dom.classList.contains('editing')) {
+    let list = dom.querySelector('ul, ol');
+    if (list && !dom.classList.contains('editing')) {
       const items = el.items && el.items.length ? el.items : [''];
-      ul.innerHTML = items.map(item =>
-        `<li>${item.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')}</li>`
-      ).join('');
+      const wantTag = el.ordered ? 'OL' : 'UL';
+      if (list.tagName !== wantTag) {
+        // ordered flag changed — swap the container (never while editing)
+        const swapped = document.createElement(wantTag.toLowerCase());
+        list.replaceWith(swapped);
+        list = swapped;
+        dom._wbListKey = null;
+      }
+      const key = wantTag + '|' + JSON.stringify(items);
+      if (dom._wbListKey !== key) {
+        list.innerHTML = items.map(item =>
+          `<li>${item.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')}</li>`
+        ).join('');
+        dom._wbListKey = key;
+      }
     }
     if (el.fontSize) dom.style.fontSize = el.fontSize + 'px';
     if (el.color) dom.style.color = el.color;
@@ -537,6 +931,47 @@ function updateElementDOM(dom, el) {
   }
 }
 
+// ── Arrowhead markers ──
+// The static <defs> in html-shell.js only carry a white and a selected (blue)
+// head. Arrows honour el.color on the shaft, so the head must follow: one
+// <marker> per distinct colour, created on demand inside the persistent <defs>
+// (renderArrows re-appends that node, so generated markers survive rebuilds).
+const _markerIds = new Map();   // color → marker id
+
+function _arrowMarkerId(color) {
+  if (!color) return 'wb-arrowhead';
+  let id = _markerIds.get(color);
+  if (!id) {
+    id = 'wb-ah-' + color.replace(/[^a-zA-Z0-9]/g, '_');
+    _markerIds.set(color, id);
+  }
+  return id;
+}
+
+function _ensureArrowMarker(color) {
+  const id = _arrowMarkerId(color);
+  if (!color || !_arrowsSvg) return id;
+  const defs = _arrowsSvg.querySelector('defs');
+  if (!defs || defs.querySelector('#' + id)) return id;
+  const ns = 'http://www.w3.org/2000/svg';
+  const marker = document.createElementNS(ns, 'marker');
+  marker.setAttribute('id', id);
+  marker.setAttribute('markerWidth', '20');
+  marker.setAttribute('markerHeight', '20');
+  marker.setAttribute('refX', '2');
+  marker.setAttribute('refY', '10');
+  marker.setAttribute('orient', 'auto');
+  marker.setAttribute('markerUnits', 'userSpaceOnUse');
+  marker.setAttribute('overflow', 'visible');
+  const head = document.createElementNS(ns, 'path');
+  head.setAttribute('d', 'M 2 2 L 18 10 L 2 18 Z');
+  head.setAttribute('fill', color);
+  head.setAttribute('stroke', 'none');
+  marker.appendChild(head);
+  defs.appendChild(marker);
+  return id;
+}
+
 function renderArrows() {
   if (!_arrowsSvg) return;
   const defs = _arrowsSvg.querySelector('defs');
@@ -546,19 +981,9 @@ function renderArrows() {
   for (const el of _elements) {
     // ── Arrows ──
     if (el.type === 'arrow') {
-      const pts = (el.points || []).map(p => [...p]);
+      const pts = resolveArrowPoints(el);
       if (pts.length < 2) continue;
 
-      // Apply anchor offsets to first/last points
-      if (el.startAnchor) {
-        const pt = getAnchorPoint(el.startAnchor, pts[1][0], pts[1][1]);
-        if (pt) { pts[0] = [pt.x, pt.y]; }
-      }
-      if (el.endAnchor) {
-        const pt = getAnchorPoint(el.endAnchor, pts[pts.length - 2][0], pts[pts.length - 2][1]);
-        if (pt) { pts[pts.length - 1] = [pt.x, pt.y]; }
-      }
-
       const isSel = _selectedIds.has(el.id);
       const d = computeArrowPath(pts);
 
@@ -575,11 +1000,11 @@ function renderArrows() {
       const path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
       path.setAttribute('d', d);
       path.setAttribute('fill', 'none');
-      path.setAttribute('stroke', isSel ? 'var(--accent-blue, #60a5fa)' : 'rgba(255,255,255,0.8)');
+      path.setAttribute('stroke', isSel ? 'var(--accent-blue, #60a5fa)' : (el.color || 'rgba(255,255,255,0.8)'));
       path.setAttribute('stroke-width', isSel ? '3' : '2');
       path.setAttribute('stroke-linecap', 'butt');
       path.setAttribute('stroke-linejoin', 'round');
-      path.setAttribute('marker-end', isSel ? 'url(#wb-arrowhead-sel)' : 'url(#wb-arrowhead)');
+      path.setAttribute('marker-end', isSel ? 'url(#wb-arrowhead-sel)' : `url(#${_ensureArrowMarker(el.color)})`);
       path.dataset.wbId = el.id;
       path.style.pointerEvents = 'none';
       if (isSel) path.classList.add('selected');
@@ -616,13 +1041,92 @@ function renderArrows() {
   }
 }
 
+// ── Drag fast path ──────────────────────────────────────────
+// During a single/multi-element drag we update ONLY the affected DOM node(s)
+// and ONLY the arrows anchored to them, instead of the full renderAll()
+// (which restyles every element AND tears down/rebuilds the entire arrows SVG
+// every mousemove). All synchronous — the 2026-05-11 rAF-batching attempt was
+// reverted because deferring breaks pointer responsiveness; the win here is
+// eliminating per-frame work, not scheduling it. Each helper returns false if
+// a target node is missing so the caller can fall back to renderAll() once.
+
+/** Re-route one arrow/pen's existing <path> nodes in place (hit + visible),
+ *  recomputing `d` exactly as renderArrows() does. No innerHTML, no createElementNS. */
+function _renderOneArrowPaths(el) {
+  if (!_arrowsSvg) return false;
+  const nodes = _arrowsSvg.querySelectorAll(`path[data-wb-id="${el.id}"]`);
+  if (!nodes.length) return false;
+  let d;
+  if (el.type === 'arrow') {
+    const pts = resolveArrowPoints(el);
+    if (pts.length < 2) return true;
+    d = computeArrowPath(pts);
+  } else { // pen
+    d = el.pathD || pointsToSmoothPath(el.points || []);
+  }
+  for (const n of nodes) n.setAttribute('d', d);
+  return true;
+}
+
+/** Update a single element's DOM node via the existing updateElementDOM (which
+ *  handles position, size, rotation, shape inner-SVG redraw, section recolor). */
+function updateElementPosition(id) {
+  if (!_elementsDiv) return false;
+  const el = _findEl(id);
+  if (!el) return false;
+  const dom = _elementsDiv.querySelector(`[data-wb-id="${id}"]`);
+  if (!dom) return false;
+  updateElementDOM(dom, el);
+  return true;
+}
+
+/** Per-frame drag update. `ids` = moved element ids (Set|array);
+ *  `anchoredArrowIds` = arrows pinned to moved DOM elements (precomputed at
+ *  drag start). Returns false → caller does a one-shot renderAll() fallback. */
+function _fastDragUpdate(ids, anchoredArrowIds) {
+  const idSet = ids instanceof Set ? ids : new Set(ids);
+  let ok = true;
+  for (const id of idSet) {
+    const el = _findEl(id);
+    if (!el) { ok = false; continue; }
+    if (el.type === 'arrow' || el.type === 'pen') {
+      if (!_renderOneArrowPaths(el)) ok = false;
+    } else {
+      if (!updateElementPosition(id)) ok = false;
+    }
+  }
+  if (anchoredArrowIds) {
+    for (const aid of anchoredArrowIds) {
+      if (idSet.has(aid)) continue; // already updated above
+      const a = _findEl(aid);
+      if (a && !_renderOneArrowPaths(a)) ok = false;
+    }
+  }
+  // Keep selection chrome tracking the element. positionContextMenu* now read
+  // the cached gesture rect (_getRootRect), so this adds no per-frame layout.
+  if (_ctxMenu && _selectedIds.size > 0) {
+    if (_selectedIds.size === 1) {
+      const sel = _findEl(_selectedId);
+      if (sel) positionContextMenu(sel);
+    } else {
+      positionContextMenuMulti();
+    }
+  }
+  return ok;
+}
+
 
 // ═══════════════════════════════════════════
 // ELEMENT CRUD
 // ═══════════════════════════════════════════
 
-function addElement(el, { skipPersist = false } = {}) {
-  el.zIndex = _nextZIndex++;
+function addElement(el, { skipPersist = false, keepZIndex = false } = {}) {
+  if (keepZIndex && Number.isFinite(el.zIndex)) {
+    // Server-assigned z-order (MCP adds): honour it and keep our counter ahead.
+    _nextZIndex = Math.max(_nextZIndex, el.zIndex + 1);
+  } else {
+    el.zIndex = _nextZIndex++;
+  }
   _elements.push(el);
   pushUndo('add', null, { ...el });
   renderAll();
@@ -637,8 +1141,9 @@ function deleteElement(id) {
   _elements.splice(idx, 1);
 
   // Detach arrows anchored to deleted element
-  const cx = el.x + (el.width || 100) / 2;
-  const cy = el.y + (el.height || 60) / 2;
+  const box = _elBox(el);
+  const cx = el.x + box.w / 2;
+  const cy = el.y + box.h / 2;
   for (const a of _elements) {
     if (a.type !== 'arrow' || !a.points) continue;
     if (a.startAnchor === id) {
@@ -666,8 +1171,9 @@ function deleteMultipleElements(ids) {
     const el = { ..._elements[idx] };
     _elements.splice(idx, 1);
     // Detach arrows anchored to this element
-    const cx = el.x + (el.width || 100) / 2;
-    const cy = el.y + (el.height || 60) / 2;
+    const box = _elBox(el);
+    const cx = el.x + box.w / 2;
+    const cy = el.y + box.h / 2;
     for (const a of _elements) {
       if (a.type !== 'arrow' || !a.points) continue;
       if (a.startAnchor === id) { a.points[0] = [cx, cy]; a.startAnchor = null; }
@@ -917,6 +1423,7 @@ function showContextMenu(id) {
         startX: ev.clientX, startY: ev.clientY,
         origX: el2.x, origY: el2.y,
         before: { ...el2 },
+        anchoredArrows: _anchoredArrowIds([id]),
       };
     });
 
@@ -942,7 +1449,7 @@ function getElementCenter(el) {
 }
 
 function positionContextMenu(el) {
-  const rootRect = _root?.getBoundingClientRect();
+  const rootRect = _getRootRect(); // cached for the gesture — no per-frame layout flush
   if (!rootRect) return;
 
   let cx, topY, rightX, bottomY, leftX;
@@ -1060,7 +1567,7 @@ function showMultiContextMenu() {
 
 function positionContextMenuMulti() {
   if (!_ctxMenu || _selectedIds.size < 2) return;
-  const rootRect = _root?.getBoundingClientRect();
+  const rootRect = _getRootRect(); // cached for the gesture — no per-frame layout flush
   if (!rootRect) return;
 
   const bounds = getMultiSelectBounds();
@@ -1541,6 +2048,7 @@ function enterEditMode(dom, elId) {
       el.content = content.innerText.trimEnd() || '';
       pushUndo('edit', before, { ...el });
       persistDebounced();
+      _scheduleMeasure();   // content changed without a render — re-measure the card
     }
   };
   content.addEventListener('blur', onBlur);
@@ -1552,7 +2060,7 @@ function exitEditMode() {
 }
 
 function enterListEditMode(dom, elId) {
-  const ul = dom.querySelector('ul');
+  const ul = dom.querySelector('ul, ol');
   if (!ul) return;
   dom.classList.add('editing');
 
@@ -1575,7 +2083,7 @@ function enterListEditMode(dom, elId) {
 function exitListEditMode() {
   const dom = _root?.querySelector('.wb-list.editing');
   if (!dom) return;
-  const ul = dom.querySelector('ul');
+  const ul = dom.querySelector('ul, ol');
   const elId = dom.dataset.wbId;
 
   dom.classList.remove('editing');
@@ -1590,6 +2098,7 @@ function exitListEditMode() {
     el.items = rawItems.filter((t, i, arr) => t !== '' || arr.length === 1);
     if (!el.items.length) el.items = [''];
     pushUndo('edit', before, { ...el, items: [...el.items] });
+    dom._wbListKey = null;   // editing mutated the <li>s directly — force a clean rewrite
     renderElements();
     persistDebounced();
   }
@@ -1617,6 +2126,7 @@ function _startMultiDrag(e) {
     type: 'move-multi',
     startX: e.clientX, startY: e.clientY,
     snapshots,
+    anchoredArrows: _anchoredArrowIds(_selectedIds),
   };
 }
 
@@ -1680,13 +2190,16 @@ function onMouseDown(e) {
     // Resize handle? (only when single-selected)
     if (e.target.closest('.wb-resize-handle') && targetId) {
       const el = _elements.find(e2 => e2.id === targetId);
-      if (el) {
+      // Text/list cards auto-size — they have no handle; guard anyway so a
+      // stray hit falls through to a plain move.
+      if (el && el.type !== 'text' && el.type !== 'list') {
         selectElement(targetId);
         _drag = {
           type: 'resize', id: targetId,
           startX: e.clientX, startY: e.clientY,
           origW: el.width || 200, origH: el.height || 80,
           before: { ...el },
+          anchoredArrows: _anchoredArrowIds([targetId]),
         };
         e.preventDefault();
         return;
@@ -1713,6 +2226,7 @@ function onMouseDown(e) {
             startX: e.clientX, startY: e.clientY,
             origX: el.x, origY: el.y,
             before: { ...el },
+            anchoredArrows: _anchoredArrowIds([targetId]),
           };
         }
         e.preventDefault();
@@ -1908,6 +2422,13 @@ function onMouseDown(e) {
 function onMouseMove(e) {
   if (!_root) return;
 
+  // While actively dragging/drawing, suppress ambient transitions + glow/pulse
+  // animations (consumed by the body.ui-interacting CSS kill-switch at
+  // styles.css:7231). classList.add is idempotent — cheap to call each move.
+  if (_drag || _marquee || _shapeCreating || _sectionCreating || _penPoints) {
+    document.body.classList.add('ui-interacting');
+  }
+
   // Marquee selection drag
   if (_marquee) {
     const pt = clientToCanvas(e.clientX, e.clientY);
@@ -1919,6 +2440,8 @@ function onMouseMove(e) {
     if (!_marquee.rect && (w > 4 || h > 4)) {
       _marquee.rect = document.createElement('div');
       _marquee.rect.className = 'wb-marquee';
+      // Keep the marquee overlay above promoted images/elements with runtime zIndex values.
+      _marquee.rect.style.zIndex = String(_nextZIndex + 100);
       _root.appendChild(_marquee.rect);
     }
     if (_marquee.rect) {
@@ -1937,7 +2460,7 @@ function onMouseMove(e) {
     const dx = state.gridSnap ? (_snap(_drag.snapshots[0]?.origX + rawDx) - _drag.snapshots[0]?.origX) : rawDx;
     const dy = state.gridSnap ? (_snap(_drag.snapshots[0]?.origY + rawDy) - _drag.snapshots[0]?.origY) : rawDy;
     for (const snap of _drag.snapshots) {
-      const el = _elements.find(el2 => el2.id === snap.id);
+      const el = _findEl(snap.id);
       if (!el) continue;
       if (el.type === 'arrow') {
         el.points = snap.origPoints.map(([px, py]) => [px + dx, py + dy]);
@@ -1953,14 +2476,14 @@ function onMouseMove(e) {
         el.y = snap.origY + dy;
       }
     }
-    renderAll();
+    if (!_fastDragUpdate(_drag.snapshots.map(s => s.id), _drag.anchoredArrows)) renderAll();
     return;
   }
 
   // Shape drag-to-create
   if (_shapeCreating) {
     const pt = clientToCanvas(e.clientX, e.clientY);
-    const el = _elements.find(el2 => el2.id === _shapeCreating.id);
+    const el = _findEl(_shapeCreating.id);
     if (el) {
       const sx = _snap(Math.min(_shapeCreating.originX, pt.x));
       const sy = _snap(Math.min(_shapeCreating.originY, pt.y));
@@ -1976,7 +2499,7 @@ function onMouseMove(e) {
   // Section drag-to-create
   if (_sectionCreating) {
     const pt = clientToCanvas(e.clientX, e.clientY);
-    const el = _elements.find(el2 => el2.id === _sectionCreating.id);
+    const el = _findEl(_sectionCreating.id);
     if (el) {
       const sx = _snap(Math.min(_sectionCreating.originX, pt.x));
       const sy = _snap(Math.min(_sectionCreating.originY, pt.y));
@@ -1991,7 +2514,7 @@ function onMouseMove(e) {
 
   // Pen drawing
   if (_penPoints) {
-    const rect = _root.getBoundingClientRect();
+    const rect = _getRootRect();
     penMove(e.clientX - rect.left, e.clientY - rect.top);
     return;
   }
@@ -2000,11 +2523,11 @@ function onMouseMove(e) {
   if (_drag?.type === 'move') {
     const dx = e.clientX - _drag.startX;
     const dy = e.clientY - _drag.startY;
-    const el = _elements.find(el2 => el2.id === _drag.id);
+    const el = _findEl(_drag.id);
     if (el) {
       el.x = _snap(_drag.origX + dx);
       el.y = _snap(_drag.origY + dy);
-      renderAll();
+      if (!_fastDragUpdate([_drag.id], _drag.anchoredArrows)) renderAll();
     }
     return;
   }
@@ -2013,12 +2536,12 @@ function onMouseMove(e) {
   if (_drag?.type === 'move-arrow') {
     const dx = e.clientX - _drag.startX;
     const dy = e.clientY - _drag.startY;
-    const el = _elements.find(el2 => el2.id === _drag.id);
+    const el = _findEl(_drag.id);
     if (el && el.points) {
       el.points = _drag.origPoints.map(([px, py]) => [px + dx, py + dy]);
       el.startAnchor = null;
       el.endAnchor = null;
-      renderAll();
+      if (!_fastDragUpdate([_drag.id], null)) renderAll();
     }
     return;
   }
@@ -2027,13 +2550,13 @@ function onMouseMove(e) {
   if (_drag?.type === 'move-pen') {
     const dx = e.clientX - _drag.startX;
     const dy = e.clientY - _drag.startY;
-    const el = _elements.find(el2 => el2.id === _drag.id);
+    const el = _findEl(_drag.id);
     if (el) {
       el.x = _drag.origX + dx;
       el.y = _drag.origY + dy;
       el.points = _drag.origPoints.map(([px, py]) => [px + dx, py + dy]);
       el.pathD = pointsToSmoothPath(el.points);
-      renderAll();
+      if (!_fastDragUpdate([_drag.id], null)) renderAll();
     }
     return;
   }
@@ -2044,7 +2567,7 @@ function onMouseMove(e) {
     const angle = Math.atan2(pt2.y - _drag.centerY, pt2.x - _drag.centerX);
     const deltaRad = angle - _drag.startAngle;
     const deltaDeg = deltaRad * (180 / Math.PI);
-    const el = _elements.find(el2 => el2.id === _drag.id);
+    const el = _findEl(_drag.id);
     if (el) {
       // For arrows: rotate all points around centroid
       if (el.type === 'arrow' && _drag.origPoints) {
@@ -2087,7 +2610,7 @@ function onMouseMove(e) {
         }
         el.rotation = Math.round(newRot * 10) / 10;
       }
-      renderAll();
+      if (!_fastDragUpdate([_drag.id], _drag.anchoredArrows)) renderAll();
     }
     return;
   }
@@ -2096,11 +2619,11 @@ function onMouseMove(e) {
   if (_drag?.type === 'resize') {
     const dx = e.clientX - _drag.startX;
     const dy = e.clientY - _drag.startY;
-    const el = _elements.find(el2 => el2.id === _drag.id);
+    const el = _findEl(_drag.id);
     if (el) {
       el.width = _snap(Math.max(60, _drag.origW + dx));
       el.height = _snap(Math.max(30, _drag.origH + dy));
-      renderAll();
+      if (!_fastDragUpdate([_drag.id], _drag.anchoredArrows)) renderAll();
     }
     return;
   }
@@ -2114,6 +2637,12 @@ function onMouseMove(e) {
 }
 
 function onMouseUp(e) {
+  // Any interaction is ending — lift the transition/animation kill-switch and
+  // drop the gesture-cached root rect (both run first so they fire on every
+  // early-return finalize path below).
+  document.body.classList.remove('ui-interacting');
+  _invalidateRootRect();
+
   // Finalize marquee selection
   if (_marquee) {
     if (_marquee.rect) {
@@ -2251,6 +2780,8 @@ function onMouseUp(e) {
     _drag = null;
     persistDebounced();
   }
+  // A measurement pass skipped during the gesture runs now.
+  if (_measurePending) { _measurePending = false; _scheduleMeasure(); }
 }
 
 function onDblClick(e) {
@@ -2345,12 +2876,27 @@ function isWhiteboardActive() {
   return bg && bg.classList.contains('visible');
 }
 
+// A key pressed inside a side panel is the panel's: registerSidepanel marks every panel root
+// (Claude, Codex, OpenCode, Assistant) with data-sidepanel-provider.
+export function isSidepanelKeyTarget(el) {
+  return !!el?.closest?.('[data-sidepanel-provider]');
+}
+
 function onKeyDown(e) {
   if (!isWhiteboardActive()) return;
 
-  // Don't intercept keys when focus is in inputs outside the whiteboard (e.g. code editor)
-  const tag = document.activeElement?.tagName;
-  if ((tag === 'INPUT' || tag === 'TEXTAREA') && !document.activeElement.closest('#static-bg')) return;
+  // Don't intercept keys when focus is in inputs/contenteditables outside the whiteboard
+  // (e.g. code editor, floating CLI rename) — typing must produce characters, not trigger keybinds.
+  const ae = document.activeElement;
+  const tag = ae?.tagName;
+  const isTextField = tag === 'INPUT' || tag === 'TEXTAREA' || ae?.isContentEditable;
+  if (isTextField && !ae.closest('#static-bg')) return;
+  // Nor while the keyboard is inside the Settings panel: its rows, buttons and dialogs take their own keys
+  // (Escape empties its search, then closes it), and a board shortcut must not fire from a setting.
+  if (ae?.closest?.('#settings-panel')) return;
+  // Nor while it is inside a side panel: Escape there stops a turn, and Delete, Backspace or
+  // Ctrl+A/Z/C on one of its controls is not a board edit.
+  if (isSidepanelKeyTarget(e.target) || isSidepanelKeyTarget(ae)) return;
 
   const isEditingText = !!document.activeElement?.closest('.wb-text.editing');
   const editingListLi = document.activeElement?.closest('.wb-list.editing li') || null;
@@ -2417,11 +2963,13 @@ function onKeyDown(e) {
       if (_shapeCreating) {
         _elements = _elements.filter(el => el.id !== _shapeCreating.id);
         _shapeCreating = null;
+        _invalidateElementMap();
         renderAll();
       }
       if (_sectionCreating) {
         _elements = _elements.filter(el => el.id !== _sectionCreating.id);
         _sectionCreating = null;
+        _invalidateElementMap();
         renderAll();
       }
       if (_arrowCreating) { _arrowCreating = null; clearArrowPreview(); }
@@ -2737,6 +3285,7 @@ function onToolbarClick(e) {
     if (breathe) breathe.style.display = hidden ? 'none' : '';
     btn.classList.toggle('active', hidden);
     sessionStorage.setItem('wb-logo-hidden', hidden ? '1' : '');
+    syncRulesetAlertVisibility();
     return;
   }
 }
@@ -2771,6 +3320,7 @@ export function restoreWhiteboardSnapshot(snap) {
     clearWhiteboard();
     return;
   }
+  _beginStateReplace({ exitEdits: true });
   _elements = (snap.elements || []).map(el => {
     // Migrate legacy arrow format (startX/endX → points)
     if (el.type === 'arrow' && !el.points && el.startX != null) {
@@ -2788,11 +3338,13 @@ export function restoreWhiteboardSnapshot(snap) {
   _arrowCreating = null;
   _sectionCreating = null;
   _clipboard = null;
+  _invalidateElementMap();
   renderAll();
   persistDebounced();
 }
 
 export function clearWhiteboard() {
+  _beginStateReplace({ exitEdits: true });
   _elements = [];
   _nextZIndex = 1;
   _undoStack = [];
@@ -2802,6 +3354,7 @@ export function clearWhiteboard() {
   _arrowCreating = null;
   _sectionCreating = null;
   _clipboard = null;
+  _invalidateElementMap();
   renderAll();
   persistDebounced();
 }
@@ -2862,10 +3415,11 @@ export function initWhiteboard() {
 
   _root.appendChild(_arrowHint);
 
-  // Load persisted state
-  loadPersisted();
+  // Render immediately (likely empty) for an instant paint, then again once the
+  // server returns the saved board (loadPersisted is async — fetches /api/whiteboard).
   renderAll();
   updateUndoButtons();
+  loadPersisted().then(() => { renderAll(); updateUndoButtons(); });
 
   // Mouse events
   _root.addEventListener('mousedown', onMouseDown);
@@ -2873,13 +3427,32 @@ export function initWhiteboard() {
   window.addEventListener('mouseup', onMouseUp);
   _root.addEventListener('dblclick', onDblClick);
 
+  // Never let the browser start a native HTML5 drag inside the board (an <img>
+  // drag would swallow our mouseup and strand _drag). Nodes that opt in with
+  // draggable="true" (e.g. a future drag-to-terminal handle) are exempt.
+  _root.addEventListener('dragstart', (e) => {
+    if (e.target?.closest?.('[draggable="true"]')) return;
+    e.preventDefault();
+  });
+
   // Keyboard — capture phase so we fire before global keybinds
   document.addEventListener('keydown', onKeyDown, true);
 
   // Track Ctrl key for tool lock
   document.addEventListener('keydown', onCtrlTrack);
   document.addEventListener('keyup', onCtrlTrack);
-  window.addEventListener('blur', () => { _toolLocked = false; updateLockIndicator(); });
+  // A window blur or hidden tab means the matching mouseup may never arrive —
+  // drop the tool lock AND any in-flight pointer gesture so the board never
+  // ends up with a stale _drag/_marquee/_penPoints swallowing every mousemove.
+  window.addEventListener('blur', () => {
+    _toolLocked = false;
+    updateLockIndicator();
+    _cancelGesture({ pointerOnly: true });
+  });
+  document.addEventListener('visibilitychange', () => {
+    if (document.hidden) _cancelGesture({ pointerOnly: true });
+    _sendViewport();   // `visible` flag feeds the server's primary-client pick
+  });
 
   // Paste — listen on document (not _root) because _root can't receive focus
   // and paste events only fire on the focused element's ancestor chain.
@@ -2898,6 +3471,9 @@ export function initWhiteboard() {
   // Section picker
   initSectionPicker();
 
+  // Logo-adjacent ruleset reminder
+  initRulesetAlert();
+
   // Prevent context menu on whiteboard
   _root.addEventListener('contextmenu', e => e.preventDefault());
 
@@ -2907,6 +3483,7 @@ export function initWhiteboard() {
 
   // Auto-focus whiteboard when entering focus mode so Ctrl+V paste works immediately
   on('focus:enter', () => {
+    refreshRulesetAlert();
     setTimeout(() => _root.focus({ preventScroll: true }), 150);
     // Restore logo hidden state from session
     if (sessionStorage.getItem('wb-logo-hidden') === '1') {
@@ -2914,14 +3491,40 @@ export function initWhiteboard() {
       const breathe = document.querySelector('#static-bg .focus-breathe');
       if (logo) logo.style.display = 'none';
       if (breathe) breathe.style.display = 'none';
+      syncRulesetAlertVisibility();
       const btn = document.getElementById('wb-toggle-logo');
       if (btn) btn.classList.add('active');
+    } else {
+      syncRulesetAlertVisibility();
     }
   });
 
   // Connect to server for external commands (Claude MCP)
   _connectWhiteboardWS();
 
+  // Viewport truth: re-report the usable area whenever anything that bounds it
+  // changes — root size, the CSS variables the navbar/terminal/right panel
+  // publish on <html>, focus mode, panel visibility, tab visibility.
+  if (typeof ResizeObserver !== 'undefined') {
+    new ResizeObserver(() => _sendViewport()).observe(_root);
+  }
+  if (typeof MutationObserver !== 'undefined') {
+    new MutationObserver(() => _sendViewport())
+      .observe(document.documentElement, { attributes: true, attributeFilter: ['style'] });
+  }
+  // focus:enter/exit fire BEFORE ui-settings toggles #static-bg.visible (100 ms
+  // stagger), so report after the class has landed.
+  on('focus:enter', () => setTimeout(() => _sendViewport({ immediate: true }), 250));
+  on('focus:exit', () => setTimeout(() => _sendViewport({ immediate: true }), 250));
+  on('claude-panel:visibility', () => _sendViewport());
+
+  // First measurement of text/list cards once the real font is in (metrics
+  // taken with a fallback font would be wrong by a few px per glyph).
+  if (document.fonts?.ready) {
+    document.fonts.ready.then(_scheduleMeasure).catch(() => {});
+    document.fonts.addEventListener?.('loadingdone', _scheduleMeasure);
+  }
+
   // ── Guest permission: disable drawing tools when whiteboard perm is off ──
   function updateWbPermVisual() {
     if (!_toolbar || !_canvas) return;
@@ -2968,15 +3571,12 @@ function _connectWhiteboardWS() {
   _ws.onopen = () => {
     console.log('[whiteboard-ws] Connected');
     if (_wsReconnectTimer) { clearInterval(_wsReconnectTimer); _wsReconnectTimer = null; }
-    // Report usable viewport dimensions (excluding navbar, toolbar, terminal) for MCP coordinate mapping
-    if (_root) {
-      const rect = _root.getBoundingClientRect();
-      const titleBar = document.getElementById('title-bar');
-      const toolbar = document.getElementById('wb-toolbar');
-      const navH = titleBar ? titleBar.getBoundingClientRect().height : 0;
-      const tbW = toolbar ? toolbar.getBoundingClientRect().right - rect.left + 12 : 60;
-      _ws.send(JSON.stringify({ type: 'viewport', width: Math.round(rect.width - tbW), height: Math.round(rect.height - navH), yOffset: Math.round(navH), xOffset: Math.round(tbW) }));
-    }
+    // Report the usable viewport (excluding navbar, tool rail, right panel,
+    // terminal) for MCP coordinate mapping, then flush any measured sizes that
+    // were collected while the socket was down.
+    _lastViewportJson = '';
+    _sendViewport({ immediate: true });
+    _queueGeometrySend();
   };
 
   _ws.onmessage = (event) => {
@@ -2997,21 +3597,63 @@ function _connectWhiteboardWS() {
   _ws.onerror = () => {}; // onclose fires after
 }
 
-// Debounced viewport resize reporting
-let _viewportResizeTimer = null;
-window.addEventListener('resize', () => {
-  clearTimeout(_viewportResizeTimer);
-  _viewportResizeTimer = setTimeout(() => {
-    if (_ws && _ws.readyState === 1 && _root) {
-      const rect = _root.getBoundingClientRect();
-      const titleBar = document.getElementById('title-bar');
-      const toolbar = document.getElementById('wb-toolbar');
-      const navH = titleBar ? titleBar.getBoundingClientRect().height : 0;
-      const tbW = toolbar ? toolbar.getBoundingClientRect().right - rect.left + 12 : 60;
-      _ws.send(JSON.stringify({ type: 'viewport', width: Math.round(rect.width - tbW), height: Math.round(rect.height - navH), yOffset: Math.round(navH), xOffset: Math.round(tbW) }));
-    }
-  }, 300);
-});
+// ── Viewport reporting ──
+
+function _cssPx(name) {
+  const v = parseFloat(getComputedStyle(document.documentElement).getPropertyValue(name));
+  return Number.isFinite(v) ? v : 0;
+}
+
+/** Usable whiteboard viewport in CSS px relative to #wb-root's top-left: the
+ *  root minus the left tool rail, the navbar and the docked right-side agent
+ *  panel (its reserved width is published as --right-panel-width by
+ *  ui-sidepanel-layout.js; 0 when hidden or floating). #wb-root already ends
+ *  above a docked terminal (--terminal-height). Sent to the server so MCP
+ *  coordinate math and screenshots describe what the user can actually see. */
+function _computeViewport() {
+  const rect = _root.getBoundingClientRect();
+  const titleBar = document.getElementById('title-bar');
+  const toolbar = document.getElementById('wb-toolbar');
+  const navH = titleBar ? titleBar.getBoundingClientRect().height : _cssPx('--navbar-height');
+  const tbW = toolbar ? Math.max(0, toolbar.getBoundingClientRect().right - rect.left + 12) : 60;
+  const rightW = Math.max(0, _cssPx('--right-panel-width') || _cssPx('--claude-panel-width'));
+  return {
+    type: 'viewport',
+    clientId: _clientId,
+    focusActive: isWhiteboardActive(),
+    visible: document.visibilityState === 'visible',
+    width: Math.max(0, Math.round(rect.width - tbW - rightW)),
+    height: Math.max(0, Math.round(rect.height - navH)),
+    xOffset: Math.round(tbW),
+    yOffset: Math.round(navH),
+    rootWidth: Math.round(rect.width),
+    rootHeight: Math.round(rect.height),
+    rightPanelWidth: Math.round(rightW),
+    dpr: window.devicePixelRatio || 1,
+  };
+}
+
+let _viewportTimer = null;
+let _lastViewportJson = '';
+
+/** Debounced (150 ms), deduplicated viewport report. Every trigger also drops
+ *  the gesture-cached root rect since the layout just changed. */
+function _sendViewport({ immediate = false } = {}) {
+  _invalidateRootRect();
+  clearTimeout(_viewportTimer);
+  const send = () => {
+    _viewportTimer = null;
+    if (!_ws || _ws.readyState !== 1 || !_root) return;
+    const json = JSON.stringify(_computeViewport());
+    if (json === _lastViewportJson) return;
+    _lastViewportJson = json;
+    _ws.send(json);
+  };
+  if (immediate) send();
+  else _viewportTimer = setTimeout(send, 150);
+}
+
+window.addEventListener('resize', () => _sendViewport());
 
 function _handleExternalCommand(msg) {
   switch (msg.type) {
@@ -3020,7 +3662,17 @@ function _handleExternalCommand(msg) {
 
     case 'add':
       for (const el of (msg.elements || [])) {
-        addElement(el, { skipPersist: true });
+        const idx = _elements.findIndex(e => e.id === el.id);
+        if (idx >= 0) {
+          // The server re-sent an id we already hold — replace in place
+          // (no duplicate DOM node, no extra undo entry).
+          _elements[idx] = el;
+          if (Number.isFinite(el.zIndex)) _nextZIndex = Math.max(_nextZIndex, el.zIndex + 1);
+          _invalidateElementMap();
+          renderAll();
+          continue;
+        }
+        addElement(el, { skipPersist: true, keepZIndex: true });
       }
       break;
 
@@ -3049,30 +3701,79 @@ function _handleExternalCommand(msg) {
       break;
     }
 
-    case 'clear':
+    case 'clear': {
+      // External (MCP) clear is UNDOABLE: push a delete-multi entry (undo()
+      // pushes the copies back) instead of wiping the user's history.
+      _beginStateReplace({ exitEdits: true });
+      if (_elements.length) {
+        pushUndo('delete-multi', _elements.map(el => ({ ...el, points: el.points ? el.points.map(p => [...p]) : undefined })), null);
+      } else {
+        _nextZIndex = 1;
+      }
       _elements = [];
-      _nextZIndex = 1;
-      _undoStack = [];
-      _redoStack = [];
-      _selectedId = null;
-      _selectedIds.clear();
-      _arrowCreating = null;
-      _sectionCreating = null;
+      _invalidateElementMap();
       renderAll();
+      updateUndoButtons();
       break;
+    }
 
     case 'state:full':
-      // Full state sync from another client — replace local state, save to localStorage only (no WS echo)
+      // Full state sync relayed from another client. The server already
+      // persisted it (saveWhiteboard); just apply locally — no re-persist.
+      // Do NOT exit an in-progress text edit here (the user may be typing);
+      // gestures are cancelled so a drag can't continue on ghost objects.
+      _beginStateReplace({ exitEdits: false });
       _elements = msg.snapshot?.elements || [];
       _nextZIndex = msg.snapshot?.nextZIndex || 1;
-      _selectedId = null;
-      _selectedIds.clear();
+      _invalidateElementMap();
+      renderAll();
+      break;
+
+    case 'batch': {
+      // Several server-side ops (batch update/remove, delete cascades) applied
+      // atomically: one undo entry, one render, no persist (server already has it).
+      const ops = Array.isArray(msg.ops) ? msg.ops : [];
+      if (!ops.length) break;
+      const copyEl = (el) => ({ ...el, points: el.points ? el.points.map(p => [...p]) : undefined });
+      const befores = [], afters = [], removed = [], addedIds = [], addedCopies = [];
+      for (const op of ops) {
+        if (op.op === 'update') {
+          const el = _elements.find(e => e.id === op.id);
+          if (!el) continue;
+          befores.push(copyEl(el));
+          for (const [key, value] of Object.entries(op.updates || {})) {
+            if (key === 'id' || key === 'type') continue;
+            el[key] = value;
+          }
+          afters.push(copyEl(el));
+        } else if (op.op === 'remove') {
+          const idx = _elements.findIndex(e => e.id === op.id);
+          if (idx < 0) continue;
+          removed.push(copyEl(_elements[idx]));
+          _elements.splice(idx, 1);
+          _selectedIds.delete(op.id);
+          if (_selectedId === op.id) _selectedId = null;
+        } else if (op.op === 'add' && op.element?.id) {
+          if (_elements.some(e => e.id === op.element.id)) continue;
+          const el = op.element;
+          if (Number.isFinite(el.zIndex)) _nextZIndex = Math.max(_nextZIndex, el.zIndex + 1);
+          else el.zIndex = _nextZIndex++;
+          _elements.push(el);
+          addedIds.push(el.id);
+          addedCopies.push(copyEl(el));
+        }
+      }
+      if (befores.length || removed.length || addedIds.length) {
+        pushUndo('batch', { updated: befores, removed, added: addedIds }, { updated: afters, added: addedCopies });
+      }
+      if (_selectedIds.size === 0) hideContextMenu();
+      _invalidateElementMap();
       renderAll();
-      storage.setItem(KEYS.WHITEBOARD, JSON.stringify({ elements: _elements, nextZIndex: _nextZIndex }));
       break;
+    }
 
     case 'screenshot:request':
-      _captureScreenshot(msg.requestId);
+      _captureScreenshot(msg.requestId, { crop: msg.crop });
       break;
 
     case 'screenshot:auto': {
@@ -3112,138 +3813,267 @@ function _loadImage(src) {
   });
 }
 
-function _drawArrowhead(ctx, points) {
+function _roundRectPath(ctx, x, y, w, h, r) {
+  const rr = Math.max(0, Math.min(r, w / 2, h / 2));
+  ctx.moveTo(x + rr, y);
+  ctx.lineTo(x + w - rr, y);
+  ctx.arcTo(x + w, y, x + w, y + rr, rr);
+  ctx.lineTo(x + w, y + h - rr);
+  ctx.arcTo(x + w, y + h, x + w - rr, y + h, rr);
+  ctx.lineTo(x + rr, y + h);
+  ctx.arcTo(x, y + h, x, y + h - rr, rr);
+  ctx.lineTo(x, y + rr);
+  ctx.arcTo(x, y, x + rr, y, rr);
+  ctx.closePath();
+}
+
+/** `color` with an alpha byte applied (hex2 like '0d'). Handles #rgb/#rrggbb
+ *  and rgb()/rgba(); anything else is returned unchanged. */
+function _withAlpha(color, hex2) {
+  const a = parseInt(hex2, 16) / 255;
+  let m = /^#([0-9a-f]{6})$/i.exec(color);
+  if (m) return color + hex2;
+  m = /^#([0-9a-f])([0-9a-f])([0-9a-f])$/i.exec(color);
+  if (m) return `#${m[1]}${m[1]}${m[2]}${m[2]}${m[3]}${m[3]}${hex2}`;
+  m = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)/i.exec(color);
+  if (m) return `rgba(${m[1]},${m[2]},${m[3]},${a.toFixed(3)})`;
+  return color;
+}
+
+/** Arrowhead identical to the SVG marker (path M 2 2 L 18 10 L 2 18, refX 2,
+ *  refY 10): a 16px triangle extending past the last point along the end tangent. */
+function _drawArrowhead(ctx, points, fill) {
   if (points.length < 2) return;
   const last = points[points.length - 1];
   const prev = points[points.length - 2];
   const angle = Math.atan2(last[1] - prev[1], last[0] - prev[0]);
-  const size = 20;
-  ctx.fillStyle = ctx.strokeStyle;
+  ctx.save();
+  ctx.translate(last[0], last[1]);
+  ctx.rotate(angle);
+  ctx.fillStyle = fill;
   ctx.beginPath();
-  ctx.moveTo(last[0], last[1]);
-  ctx.lineTo(last[0] - size * Math.cos(angle - Math.PI / 6), last[1] - size * Math.sin(angle - Math.PI / 6));
-  ctx.lineTo(last[0] - size * Math.cos(angle + Math.PI / 6), last[1] - size * Math.sin(angle + Math.PI / 6));
+  ctx.moveTo(0, -8);
+  ctx.lineTo(16, 0);
+  ctx.lineTo(0, 8);
   ctx.closePath();
   ctx.fill();
+  ctx.restore();
+}
+
+/** Baseline offset from the top of a CSS line box of `lineH` px for the
+ *  current ctx.font (half-leading + ascent), with metric fallbacks. */
+function _lineBaseline(ctx, fs, lineH) {
+  const m = ctx.measureText('Mg');
+  const ascent = m.fontBoundingBoxAscent > 0 ? m.fontBoundingBoxAscent : fs * 1.02;
+  const descent = m.fontBoundingBoxDescent > 0 ? m.fontBoundingBoxDescent : fs * 0.3;
+  return (lineH - (ascent + descent)) / 2 + ascent;
 }
 
-async function _captureScreenshot(requestId) {
+/**
+ * Re-render the board to an offscreen canvas for the MCP whiteboard_screenshot
+ * tool. This is a RECONSTRUCTION, so every stroke reuses the generators and
+ * constants the DOM uses: JetBrains Mono with the CSS paddings, the seeded
+ * hand-drawn shape paths, anchor-resolved Catmull-Rom arrows with the
+ * marker-shaped head, section/image chrome. Output is scaled up to 2x (capped
+ * so the long edge stays ≤ 2000 px) and the response carries the coordinate
+ * mapping (image px ÷ scale = canvas px) plus the usable viewport.
+ */
+async function _captureScreenshot(requestId, { crop } = {}) {
   try {
-    const canvas = document.createElement('canvas');
+    flushTextEdits();
+    flushListEdits();
+    try {
+      if (document.fonts?.ready) await document.fonts.ready;
+      if (document.fonts?.load) {
+        await Promise.allSettled([
+          document.fonts.load('400 22px "JetBrains Mono"'),
+          document.fonts.load('700 22px "JetBrains Mono"'),
+          document.fonts.load('italic 400 22px "JetBrains Mono"'),
+        ]);
+      }
+    } catch { /* draw with whatever is loaded */ }
+
     const rootRect = _root.getBoundingClientRect();
-    canvas.width = rootRect.width;
-    canvas.height = rootRect.height;
+    const vp = _computeViewport();
+    const usable = { x: vp.xOffset, y: vp.yOffset, width: vp.width, height: vp.height };
+    const box = crop === 'usable'
+      ? usable
+      : { x: 0, y: 0, width: Math.round(rootRect.width), height: Math.round(rootRect.height) };
+    const outW = Math.max(1, Math.round(box.width));
+    const outH = Math.max(1, Math.round(box.height));
+    let scale = Math.min(2, window.devicePixelRatio || 1);
+    const longEdge = Math.max(outW, outH);
+    if (longEdge * scale > 2000) scale = 2000 / longEdge;
+
+    const canvas = document.createElement('canvas');
+    canvas.width = Math.max(1, Math.round(outW * scale));
+    canvas.height = Math.max(1, Math.round(outH * scale));
     const ctx = canvas.getContext('2d');
+    ctx.scale(scale, scale);
+    ctx.translate(-box.x, -box.y);
+    ctx.imageSmoothingQuality = 'high';
+
+    // Background — same as #static-bg
+    ctx.fillStyle = '#070709';
+    ctx.fillRect(box.x, box.y, outW, outH);
 
-    // Background
-    ctx.fillStyle = '#0a0a0f';
-    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    const mono = '"JetBrains Mono", monospace';
+    const bodyFont = getComputedStyle(document.body).fontFamily || 'sans-serif';
+    const tttActive = _root.classList.contains('ttt-active');
+    const domById = new Map();
+    if (_elementsDiv) for (const child of _elementsDiv.children) domById.set(child.dataset.wbId, child);
 
     // Sort by zIndex for correct layering
     const sorted = [..._elements].sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0));
 
     for (const el of sorted) {
       ctx.save();
-
-      if (el.rotation) {
-        const cx = el.x + (el.width || 0) / 2;
-        const cy = el.y + (el.height || 0) / 2;
-        ctx.translate(cx, cy);
-        ctx.rotate(el.rotation * Math.PI / 180);
-        ctx.translate(-cx, -cy);
-      }
-
-      if (el.type === 'text') {
-        const weight = el.bold ? '700' : '400';
-        const style = el.italic ? 'italic ' : '';
-        ctx.font = `${style}${weight} ${el.fontSize || 22}px Caveat, cursive`;
-        ctx.fillStyle = el.color || 'rgba(255,255,255,0.85)';
-        ctx.textBaseline = 'top';
-        const lines = (el.content || '').split('\n');
-        let lineY = el.y + 10;
-        for (const line of lines) {
-          ctx.fillText(line, el.x + 14, lineY);
-          lineY += (el.fontSize || 22) * 1.35;
+      try {
+        // Border-box size: measured for text/list (DOM fallback if unmeasured),
+        // explicit or default for the rest.
+        let bw = el.width || 0, bh = el.height || 0;
+        if ((el.type === 'text' || el.type === 'list') && (!bw || !bh)) {
+          const dom = domById.get(el.id);
+          if (dom) { bw = dom.offsetWidth; bh = dom.offsetHeight; }
+        } else if (el.type === 'shape') {
+          bw = el.width || 160; bh = el.height || 100;
+        } else if (el.type === 'section') {
+          const def = SECTION_TYPES[el.sectionType] || SECTION_TYPES.content;
+          bw = el.width || def.w; bh = el.height || def.h;
         }
-      } else if (el.type === 'list') {
-        const fs = el.fontSize || 18;
-        ctx.font = `400 ${fs}px JetBrains Mono, monospace`;
-        ctx.fillStyle = el.color || 'rgba(255,255,255,0.85)';
-        ctx.textBaseline = 'top';
-        const items = el.items && el.items.length ? el.items : [''];
-        let lineY = el.y + 10;
-        for (const item of items) {
-          ctx.fillText('• ' + item, el.x + 14, lineY);
-          lineY += fs * 1.5;
+
+        // CSS transform: rotate() about the rendered box centre (DOM elements
+        // only — arrows/pen bake rotation into their points)
+        if (el.rotation && el.type !== 'arrow' && el.type !== 'pen') {
+          const cx = el.x + bw / 2;
+          const cy = el.y + bh / 2;
+          ctx.translate(cx, cy);
+          ctx.rotate(el.rotation * Math.PI / 180);
+          ctx.translate(-cx, -cy);
         }
-      } else if (el.type === 'shape') {
-        ctx.strokeStyle = el.color || 'rgba(255,255,255,0.75)';
-        ctx.lineWidth = 3;
-        ctx.lineCap = 'round';
-        ctx.lineJoin = 'round';
-        const w = el.width || 160, h = el.height || 100;
-        if (el.shape === 'circle' || el.shape === 'drawn-circle') {
-          ctx.beginPath();
-          ctx.ellipse(el.x + w / 2, el.y + h / 2, w / 2, h / 2, 0, 0, Math.PI * 2);
-          ctx.stroke();
-        } else if (el.shape === 'pill') {
-          const r = Math.min(w, h) / 2;
+
+        if (el.type === 'text') {
+          // .wb-text: 1px border + 10px/14px padding, line-height 1.35
+          const fs = el.fontSize || 22;
+          ctx.font = `${el.italic ? 'italic ' : ''}${el.bold ? '700' : '400'} ${fs}px ${mono}`;
+          ctx.fillStyle = el.color || 'rgba(255,255,255,0.85)';
+          ctx.textBaseline = 'alphabetic';
+          ctx.textAlign = 'left';
+          const lineH = fs * 1.35;
+          const baseOff = _lineBaseline(ctx, fs, lineH);
+          let lineTop = el.y + 11;
+          for (const line of (el.content || '').split('\n')) {
+            if (line) ctx.fillText(line, el.x + 15, lineTop + baseOff);
+            lineTop += lineH;
+          }
+        } else if (el.type === 'list') {
+          // .wb-list: same box, line-height 1.5, <ul>/<ol> padding-left 1.4em
+          const fs = el.fontSize || 18;
+          ctx.font = `400 ${fs}px ${mono}`;
+          ctx.fillStyle = el.color || 'rgba(255,255,255,0.85)';
+          ctx.textBaseline = 'alphabetic';
+          const lineH = fs * 1.5;
+          const baseOff = _lineBaseline(ctx, fs, lineH);
+          const items = el.items && el.items.length ? el.items : [''];
+          const contentLeft = el.x + 15 + 1.4 * fs;
+          let lineTop = el.y + 11;
+          items.forEach((item, i) => {
+            const baseline = lineTop + baseOff;
+            ctx.textAlign = 'right';
+            ctx.fillText(el.ordered ? `${i + 1}.` : '•', contentLeft - 0.6 * fs, baseline);
+            ctx.textAlign = 'left';
+            if (item) ctx.fillText(item, contentLeft, baseline);
+            lineTop += lineH;
+          });
+        } else if (el.type === 'shape') {
+          // Same seeded hand-drawn path the DOM's inner SVG uses (stroke 4, 5px inset)
+          const shape = el.shape || 'rect';
+          const d = shape === 'drawn-circle'
+            ? generateDrawnCirclePath(bw, bh, el.id)
+            : generateHandDrawnShape(shape, bw, bh, el.id);
+          ctx.translate(el.x, el.y);
+          ctx.strokeStyle = el.color || 'rgba(255,255,255,0.8)';
+          ctx.lineWidth = 4;
+          ctx.lineCap = 'round';
+          ctx.lineJoin = 'round';
+          ctx.stroke(new Path2D(d));
+        } else if (el.type === 'image' && el.dataUrl) {
+          const img = await _loadImage(el.dataUrl).catch(() => null);
+          if (img && bw > 0 && bh > 0) {
+            // .wb-image: 2px border, radius 16 (img radius 14, object-fit: cover);
+            // during tic-tac-toe the chrome is stripped and cell markers are 20% opaque
+            const inset = tttActive ? 0 : 2;
+            const radius = tttActive ? 0 : 14;
+            const dx = el.x + inset, dy = el.y + inset;
+            const dw = Math.max(0, bw - inset * 2), dh = Math.max(0, bh - inset * 2);
+            const nw = img.naturalWidth || img.width || dw, nh = img.naturalHeight || img.height || dh;
+            const s = Math.max(dw / nw, dh / nh);
+            const sw = dw / s, sh = dh / s;
+            const sx = (nw - sw) / 2, sy = (nh - sh) / 2;
+            ctx.save();
+            if (tttActive && String(el.id).startsWith('ttt-cell-')) ctx.globalAlpha = 0.2;
+            ctx.beginPath();
+            _roundRectPath(ctx, dx, dy, dw, dh, radius);
+            ctx.clip();
+            ctx.drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh);
+            ctx.restore();
+            if (!tttActive) {
+              ctx.strokeStyle = 'rgba(255,255,255,0.08)';
+              ctx.lineWidth = 2;
+              ctx.beginPath();
+              _roundRectPath(ctx, el.x + 1, el.y + 1, bw - 2, bh - 2, 16);
+              ctx.stroke();
+            }
+          }
+        } else if (el.type === 'arrow' && el.points && el.points.length >= 2) {
+          // Anchor-resolved, Catmull-Rom smoothed — identical to renderArrows()
+          const pts = resolveArrowPoints(el);
+          ctx.strokeStyle = el.color || 'rgba(255,255,255,0.8)';
+          ctx.lineWidth = 2;
+          ctx.lineCap = 'butt';
+          ctx.lineJoin = 'round';
+          ctx.stroke(new Path2D(computeArrowPath(pts)));
+          _drawArrowhead(ctx, pts, el.color || 'rgba(255,255,255,0.9)');
+        } else if (el.type === 'pen' && el.points && el.points.length >= 2) {
+          ctx.strokeStyle = el.color || 'rgba(255,255,255,0.8)';
+          ctx.lineWidth = el.strokeWidth || 3;
+          ctx.lineCap = 'round';
+          ctx.lineJoin = 'round';
+          ctx.stroke(new Path2D(el.pathD || pointsToSmoothPath(el.points)));
+        } else if (el.type === 'section') {
+          // .wb-section: 1px dashed border in the section colour, radius 4,
+          // background colour@0d, centred 28px icon @15%, 11px mono label @70%
+          const def = SECTION_TYPES[el.sectionType] || SECTION_TYPES.content;
+          const color = el.color || def.color;
           ctx.beginPath();
-          ctx.roundRect(el.x, el.y, w, h, r);
+          _roundRectPath(ctx, el.x, el.y, bw, bh, 4);
+          ctx.fillStyle = _withAlpha(color, '0d');
+          ctx.fill();
+          ctx.setLineDash([3, 3]);
+          ctx.lineWidth = 1;
+          ctx.strokeStyle = color;
           ctx.stroke();
-        } else {
-          ctx.strokeRect(el.x, el.y, w, h);
+          ctx.setLineDash([]);
+          ctx.save();
+          ctx.globalAlpha = 0.15;
+          ctx.fillStyle = color;
+          ctx.font = `28px ${bodyFont}`;
+          ctx.textAlign = 'center';
+          ctx.textBaseline = 'middle';
+          ctx.fillText(def.icon, el.x + bw / 2, el.y + bh / 2);
+          ctx.restore();
+          ctx.save();
+          ctx.globalAlpha = 0.7;
+          ctx.fillStyle = color;
+          ctx.font = `11px ${mono}`;
+          ctx.textAlign = 'left';
+          ctx.textBaseline = 'top';
+          ctx.fillText(el.label || def.label, el.x + 8, el.y + 4);
+          ctx.restore();
         }
-      } else if (el.type === 'image' && el.dataUrl) {
-        try {
-          const img = await _loadImage(el.dataUrl);
-          ctx.drawImage(img, el.x, el.y, el.width, el.height);
-        } catch { /* skip broken images */ }
-      } else if (el.type === 'arrow' && el.points && el.points.length >= 2) {
-        ctx.strokeStyle = el.color || 'rgba(255,255,255,0.7)';
-        ctx.lineWidth = 3;
-        ctx.lineCap = 'round';
-        ctx.lineJoin = 'round';
-        ctx.beginPath();
-        ctx.moveTo(el.points[0][0], el.points[0][1]);
-        for (let i = 1; i < el.points.length; i++) {
-          ctx.lineTo(el.points[i][0], el.points[i][1]);
-        }
-        ctx.stroke();
-        _drawArrowhead(ctx, el.points);
-      } else if (el.type === 'pen' && el.points && el.points.length >= 2) {
-        ctx.strokeStyle = el.color || 'rgba(255,255,255,0.7)';
-        ctx.lineWidth = el.strokeWidth || 3;
-        ctx.lineCap = 'round';
-        ctx.lineJoin = 'round';
-        const pathD = el.pathD || pointsToSmoothPath(el.points);
-        const p2d = new Path2D(pathD);
-        ctx.stroke(p2d);
-      } else if (el.type === 'section') {
-        const def = SECTION_TYPES[el.sectionType] || SECTION_TYPES.content;
-        const color = el.color || def.color;
-        const w = el.width || def.w;
-        const h = el.height || def.h;
-        ctx.strokeStyle = color;
-        ctx.lineWidth = 1;
-        ctx.setLineDash([6, 4]);
-        ctx.strokeRect(el.x, el.y, w, h);
-        ctx.setLineDash([]);
-        ctx.fillStyle = color + '1a';
-        ctx.fillRect(el.x, el.y, w, h);
-        ctx.font = '28px sans-serif';
-        ctx.fillStyle = color + '33';
-        ctx.textAlign = 'center';
-        ctx.textBaseline = 'middle';
-        ctx.fillText(def.icon, el.x + w / 2, el.y + h / 2);
-        ctx.font = '12px JetBrains Mono, monospace';
-        ctx.fillStyle = color;
-        ctx.textAlign = 'left';
-        ctx.textBaseline = 'top';
-        ctx.fillText(el.label || def.label, el.x + 8, el.y + 6);
-        ctx.textAlign = 'start';
+      } catch (elErr) {
+        console.warn('[whiteboard] screenshot: skipped element', el.id, elErr);
       }
-
       ctx.restore();
     }
 
@@ -3251,12 +4081,25 @@ async function _captureScreenshot(requestId) {
     const base64 = dataUrl.split(',')[1];
 
     if (_ws && _ws.readyState === 1) {
-      _ws.send(JSON.stringify({ type: 'screenshot:response', requestId, data: base64 }));
+      _ws.send(JSON.stringify({
+        type: 'screenshot:response',
+        requestId,
+        data: base64,
+        clientId: _clientId,
+        focusActive: isWhiteboardActive(),
+        width: outW,
+        height: outH,
+        scale,
+        xOffset: vp.xOffset,
+        yOffset: vp.yOffset,
+        crop: crop === 'usable' ? 'usable' : 'full',
+        usable,
+      }));
     }
   } catch (err) {
     console.error('[whiteboard] Screenshot capture failed:', err);
     if (_ws && _ws.readyState === 1) {
-      _ws.send(JSON.stringify({ type: 'screenshot:error', requestId, error: err.message }));
+      _ws.send(JSON.stringify({ type: 'screenshot:error', requestId, error: err.message, clientId: _clientId }));
     }
   }
 }