@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/graph-ui/sidebar.js

@@ -0,0 +1,61 @@
+/* Sidebar layout preferences are local to this browser, separate from graph data. */
+(() => {
+  const rail = document.getElementById('library-rail');
+  const handle = document.getElementById('rail-resize');
+  if (!rail || !handle) return;
+  const key = 'andorra-graph-sidebar-width';
+  const limits = () => {
+    const min = Math.min(180, Math.max(100, innerWidth - 160));
+    return {min, max:Math.max(min, Math.min(480, innerWidth - 320))};
+  };
+  let preferred = innerWidth <= 760 ? 180 : 238;
+  try { const saved = Number(localStorage.getItem(key)); if (Number.isFinite(saved) && saved >= 100 && saved <= 480) preferred = saved; } catch { /* Storage can be unavailable. */ }
+  const apply = (width, remember = false) => {
+    const {min, max} = limits();
+    const value = Math.round(Math.max(min, Math.min(max, width)));
+    rail.style.setProperty('--rail-width', `${value}px`);
+    handle.setAttribute('aria-valuemin', String(min));
+    handle.setAttribute('aria-valuemax', String(max));
+    handle.setAttribute('aria-valuenow', String(value));
+    if (remember) {
+      preferred = value;
+      try { localStorage.setItem(key, String(value)); } catch { /* Resizing still works. */ }
+    }
+  };
+  let drag;
+  const finish = event => {
+    if (!drag || event.pointerId !== drag.id) return;
+    drag = undefined;
+    rail.classList.remove('is-resizing');
+    if (handle.hasPointerCapture(event.pointerId)) handle.releasePointerCapture(event.pointerId);
+  };
+  handle.addEventListener('pointerdown', event => {
+    if (event.button !== 0 || drag) return;
+    event.preventDefault();
+    drag = {id:event.pointerId, x:event.clientX, width:rail.getBoundingClientRect().width};
+    handle.setPointerCapture(event.pointerId);
+    rail.classList.add('is-resizing');
+  });
+  handle.addEventListener('pointermove', event => {
+    if (drag && event.pointerId === drag.id) apply(drag.width + event.clientX - drag.x, true);
+  });
+  for (const type of ['pointerup','pointercancel','lostpointercapture']) handle.addEventListener(type, finish);
+  handle.addEventListener('keydown', event => {
+    if (!['ArrowLeft','ArrowRight','Home','End'].includes(event.key)) return;
+    event.preventDefault();
+    const {min,max} = limits();
+    apply(event.key === 'Home' ? min : event.key === 'End' ? max : rail.getBoundingClientRect().width + (event.key === 'ArrowRight' ? 20 : -20), true);
+  });
+  window.addEventListener('resize', () => apply(preferred));
+  apply(preferred);
+  for (const region of rail.querySelectorAll('.rail-body, #graphs')) {
+    let idle;
+    const reveal = () => {
+      region.classList.add('is-scrolling');
+      clearTimeout(idle);
+      idle = setTimeout(() => region.classList.remove('is-scrolling'), 800);
+    };
+    region.addEventListener('scroll', reveal, {passive:true});
+    region.addEventListener('wheel', reveal, {passive:true});
+  }
+})();

package/dist/src/graph-ui/studio-canvas.js

@@ -0,0 +1,454 @@
+/* Canvas extensions: draggable connections, marquee, persisted groups, minimap, copy/paste and shortcuts. */
+(() => {
+  'use strict';
+  const studio = window.AndorraStudio;
+  if (!studio) return;
+  const byId = id => document.getElementById(id);
+  const make = (tag, text, css) => {
+    const e = document.createElement(tag);
+    if (text !== undefined) e.textContent = text;
+    if (css) e.className = css;
+    return e;
+  };
+  const svg = tag => document.createElementNS('http://www.w3.org/2000/svg', tag);
+  let copied = null, pasteOffset = 0, viewport;
+  let snapButton;
+  try { state.studioSnap = localStorage.getItem('andorra-studio-snap') === 'true'; }
+  catch { state.studioSnap = false; }
+
+  function makeGroups() {
+    const scene = byId('scene'), edges = byId('edges');
+    if (!scene || !edges) return;
+    let layer = byId('studio-group-layer');
+    if (!layer) {
+      layer = make('div', undefined, 'studio-group-layer');
+      layer.id = 'studio-group-layer';
+      scene.insertBefore(layer, edges);
+    }
+    layer.replaceChildren();
+    const groups = state.graph?.metadata?.studioLayoutGroupsV1 || [];
+    for (const group of groups) {
+      const nodes = group.nodeIds.map(id => state.graph.nodes[id]).filter(Boolean);
+      if (!nodes.length) continue;
+      const positions = nodes.map(node => position(node, Object.keys(state.graph.nodes).indexOf(node.id)));
+      const x = Math.min(...positions.map(p => p.x)) - 20;
+      const y = Math.min(...positions.map(p => p.y)) - 37;
+      const w = Math.max(...positions.map(p => p.x + 210)) - x + 20;
+      const h = Math.max(...nodes.map((node, i) => positions[i].y + 94 + outcomes(node).length * 25)) - y + 20;
+      const box = make('div', undefined, 'studio-group');
+      Object.assign(box.style, { left: x + 'px', top: y + 'px', width: w + 'px', height: h + 'px' });
+      const title = make('button', group.name, 'studio-group-title');
+      title.type = 'button';
+      title.title = 'Select the nodes in this layout group';
+      title.onclick = event => {
+        event.stopPropagation();
+        clearSelection(); state.selectedIds = nodes.map(node => node.id); state.selected = state.selectedIds.at(-1);
+        renderCanvas(); renderInspector(); showInspector();
+      };
+      const remove = make('button', '×', 'studio-group-remove');
+      remove.type = 'button';
+      remove.title = 'Remove group, keeping its nodes';
+      remove.onclick = event => {
+        event.stopPropagation();
+        mutate(() => { state.graph.metadata.studioLayoutGroupsV1 = state.graph.metadata.studioLayoutGroupsV1.filter(item => item.id !== group.id); }, true);
+      };
+      box.append(title, remove);
+      layer.append(box);
+    }
+  }
+
+  function minimap() {
+    const map = byId('studio-minimap');
+    if (!map) return;
+    map.replaceChildren();
+    const nodes = Object.values(state.graph?.nodes || {});
+    if (!nodes.length) return;
+    const points = nodes.map((n, i) => ({ ...position(n, i), h: 94 + outcomes(n).length * 25 }));
+    const minX = Math.min(...points.map(p => p.x)) - 100, maxX = Math.max(...points.map(p => p.x + 210)) + 100;
+    const minY = Math.min(...points.map(p => p.y)) - 100, maxY = Math.max(...points.map(p => p.y + p.h)) + 100;
+    const width = Math.max(1, maxX - minX), height = Math.max(1, maxY - minY);
+    const scale = Math.min(160 / width, 100 / height);
+    const startX = (160 - width * scale) / 2, startY = (100 - height * scale) / 2;
+    const toMap = (x, y) => ({ x: startX + (x - minX) * scale, y: startY + (y - minY) * scale });
+    for (const [i, node] of nodes.entries()) {
+      const p = toMap(points[i].x, points[i].y);
+      const rect = svg('rect');
+      for (const [key, value] of Object.entries({
+        x: p.x, y: p.y, width: Math.max(4, 210 * scale),
+        height: Math.max(3, points[i].h * scale), rx: 2,
+      })) rect.setAttribute(key, String(value));
+      rect.setAttribute('class', node.type === 'end' ? 'studio-minimap-end' : 'studio-minimap-node');
+      map.append(rect);
+    }
+    viewport = svg('rect');
+    viewport.setAttribute('class', 'studio-minimap-viewport');
+    map.append(viewport);
+    studio.viewport = () => {
+      if (!viewport) return;
+      const canvas = byId('canvas');
+      const left = -state.x / state.zoom, top = -state.y / state.zoom;
+      const start = toMap(left, top);
+      for (const [key, value] of Object.entries({
+        x: start.x, y: start.y,
+        width: canvas.clientWidth / state.zoom * scale,
+        height: canvas.clientHeight / state.zoom * scale,
+      })) viewport.setAttribute(key, String(value));
+    };
+    studio.viewport();
+    map.onclick = event => {
+      event.preventDefault(); event.stopPropagation();
+      const rect = map.getBoundingClientRect();
+      const centerX = minX + ((event.clientX - rect.left) * (160 / rect.width) - startX) / scale;
+      const centerY = minY + ((event.clientY - rect.top) * (100 / rect.height) - startY) / scale;
+      state.x = byId('canvas').clientWidth / 2 - centerX * state.zoom;
+      state.y = byId('canvas').clientHeight / 2 - centerY * state.zoom;
+      transform();
+    };
+  }
+
+  function previewWire(startX, startY) {
+    const canvas = byId('canvas');
+    const bounds = canvas.getBoundingClientRect();
+    const layer = svg('svg'); const path = svg('path');
+    layer.setAttribute('class', 'studio-wire-preview');
+    layer.setAttribute('width', String(bounds.width));
+    layer.setAttribute('height', String(bounds.height));
+    path.setAttribute('fill', 'none');
+    // The accent is a token, and an SVG attribute cannot name one: its value is read from the
+    // page instead. A harness that loads this file on its own falls back to the register's value.
+    path.setAttribute('stroke', typeof themeColor === 'function' ? themeColor('--accent', '#dedee3') : '#dedee3');
+    path.setAttribute('stroke-width', '2.5');
+    path.setAttribute('stroke-dasharray', '6 4');
+    layer.append(path); canvas.append(layer);
+    const x1 = startX - bounds.left, y1 = startY - bounds.top;
+    return {
+      move(x, y) {
+        const x2 = x - bounds.left, y2 = y - bounds.top;
+        path.setAttribute('d', 'M ' + x1 + ',' + y1 + ' C ' +
+          (x1 + 55) + ',' + y1 + ' ' + (x2 - 55) + ',' + y2 + ' ' + x2 + ',' + y2);
+      },
+      remove() { layer.remove(); }
+    };
+  }
+
+  function installPortDragging() {
+    for (const node of byId('nodes')?.children || []) {
+      const sourceId = node.getAttribute('data-node-id');
+      const source = state.graph?.nodes[sourceId];
+      if (!source) continue;
+      const ports = [...node.querySelectorAll('.output-port')];
+      for (const [index, port] of ports.entries()) {
+        const outcome = outcomes(source)[index];
+        const oldClick = port.onclick;
+        let consumeClick = false;
+        port.onclick = event => {
+          if (consumeClick) { event.preventDefault(); event.stopPropagation(); consumeClick = false; return; }
+          oldClick?.(event);
+        };
+        port.addEventListener('pointerdown', event => {
+          if (event.button !== 0 || event.ctrlKey || event.metaKey) return;
+          // The base editor already stops port pointerdowns; keep the invariant
+          // here as well so wire gestures never start the parent node's drag.
+          event.stopPropagation();
+          const startX = event.clientX, startY = event.clientY;
+          const pointerId = event.pointerId;
+          let line, dragging = false, active = true;
+          const matchesPointer = e => pointerId === undefined || e.pointerId === pointerId;
+          const cleanup = () => {
+            active = false;
+            window.removeEventListener('pointermove', move);
+            window.removeEventListener('pointerup', finish);
+            window.removeEventListener('pointercancel', cancel);
+            line?.remove(); line = null;
+          };
+          const move = e => {
+            if (!active || !matchesPointer(e)) return;
+            if (!dragging && Math.hypot(e.clientX - startX, e.clientY - startY) < 6) return;
+            if (!dragging) { dragging = true; line = previewWire(startX, startY); }
+            line.move(e.clientX, e.clientY);
+          };
+          const finish = e => {
+            if (!active || !matchesPointer(e)) return;
+            cleanup();
+            if (!dragging) return;
+            consumeClick = true;
+            const targetNode = document.elementFromPoint(e.clientX, e.clientY)?.closest('.node');
+            const targetId = targetNode?.getAttribute('data-node-id');
+            if (!targetId || targetId === sourceId || state.graph?.nodes[targetId]?.agentRole === 'orchestrator') {
+              status('Drop a connection on a different destination node (not the Orchestrator).', true); return;
+            }
+            if (!state.graph?.nodes[sourceId] || !outcomes(state.graph.nodes[sourceId]).includes(outcome)) return;
+            if (state.graph.edges.some(edge => edge.source === sourceId && edge.target === targetId && (edge.outcome || 'completed') === outcome)) {
+              status('This connection already exists. Click its line to configure the handoff.'); return;
+            }
+            mutate(() => {
+              const edge = { id: 'edge-' + crypto.randomUUID().slice(0, 8), source: sourceId, target: targetId, outcome };
+              state.graph.edges.push(edge);
+              clearSelection(); state.selectedEdge = edge;
+            }, true);
+            showInspector();
+            status('Connection added. Configure its input handoff and save the graph.');
+          };
+          const cancel = e => {
+            if (!active || !matchesPointer(e)) return;
+            // Cancellation is terminal; no stale pointerup may finish this gesture.
+            cleanup();
+            dragging = false;
+          };
+          window.addEventListener('pointermove', move);
+          // Do not use once:true: an unrelated pointer's release/cancel would
+          // consume the listener before this pointer finishes. cleanup() removes
+          // both listeners after the matching gesture terminates.
+          window.addEventListener('pointerup', finish);
+          window.addEventListener('pointercancel', cancel);
+        });
+      }
+    }
+  }
+
+  function marquee() {
+    const canvas = byId('canvas');
+    if (!canvas) return;
+    canvas.addEventListener('pointerdown', event => {
+      if (!event.shiftKey || event.button !== 0 || event.target.closest('.node,button,svg')) return;
+      event.stopImmediatePropagation(); event.preventDefault();
+      const bounds = canvas.getBoundingClientRect();
+      const start = { x: event.clientX - bounds.left, y: event.clientY - bounds.top };
+      const selection = make('div', undefined, 'studio-marquee'); canvas.append(selection);
+      let last = { ...start };
+      const pointerId = event.pointerId;
+      const matchesPointer = e => pointerId === undefined || e.pointerId === pointerId;
+      const cleanup = () => {
+        window.removeEventListener('pointermove', move);
+        window.removeEventListener('pointerup', up);
+        window.removeEventListener('pointercancel', cancel);
+        selection.remove();
+      };
+      const move = e => {
+        if (!matchesPointer(e)) return;
+        last = { x: e.clientX - bounds.left, y: e.clientY - bounds.top };
+        const left = Math.min(start.x, last.x), top = Math.min(start.y, last.y);
+        Object.assign(selection.style, { left: left + 'px', top: top + 'px',
+          width: Math.abs(last.x - start.x) + 'px', height: Math.abs(last.y - start.y) + 'px' });
+      };
+      const up = e => {
+        if (!matchesPointer(e)) return;
+        cleanup();
+        const left = (Math.min(start.x, last.x) - state.x) / state.zoom;
+        const top = (Math.min(start.y, last.y) - state.y) / state.zoom;
+        const right = (Math.max(start.x, last.x) - state.x) / state.zoom;
+        const bottom = (Math.max(start.y, last.y) - state.y) / state.zoom;
+        if (Math.abs(last.x - start.x) < 5 && Math.abs(last.y - start.y) < 5) return;
+        const picked = Object.values(state.graph?.nodes || {}).filter(node => {
+          const p = position(node, Object.keys(state.graph.nodes).indexOf(node.id));
+          return p.x < right && p.x + 210 > left && p.y < bottom && p.y + 94 + outcomes(node).length * 25 > top;
+        });
+        clearSelection();
+        state.selectedIds = picked.map(node => node.id); state.selected = state.selectedIds.at(-1) || null;
+        renderCanvas(); renderInspector(); if (picked.length) showInspector();
+        status('Selected ' + picked.length + ' nodes.');
+      };
+      const cancel = e => {
+        if (matchesPointer(e)) cleanup(); // Aborted gestures never alter the selection.
+      };
+      window.addEventListener('pointermove', move);
+      window.addEventListener('pointerup', up);
+      window.addEventListener('pointercancel', cancel);
+    }, true);
+  }
+
+  function copyNodes() {
+    const chosen = selectedNodes();
+    if (!chosen.length) return false;
+    // An Orchestrator is a singleton entrypoint, never duplicated by clipboard operations.
+    const selected = chosen.filter(node => node.agentRole !== 'orchestrator');
+    if (!selected.length) { status('The Orchestrator cannot be duplicated.', true); return false; }
+    const ids = new Set(selected.map(node => node.id));
+    const order = Object.keys(state.graph.nodes);
+    // Legacy/imported nodes can have no stored position. The base canvas renders
+    // those using their graph index; capture that exact visible position rather
+    // than collapsing copied nodes to the same 120,120 clipboard fallback.
+    const snapshots = selected.map(node => {
+      const snapshot = copy(node);
+      if (!snapshot.position) snapshot.position = copy(position(node, order.indexOf(node.id)));
+      return snapshot;
+    });
+    // An imported node's unmet provider requirement travels with its clipboard snapshot, so a
+    // pasted copy asks for assignment exactly like the node it came from.
+    copied = { graphId: state.graph.id, nodes: snapshots, edges: copy(state.graph.edges.filter(edge => ids.has(edge.source) && ids.has(edge.target))),
+      pendingProviderIds: selected.filter(node => state.pendingProviderNodes?.has(node.id)).map(node => node.id) };
+    pasteOffset = 0;
+    status('Copied ' + selected.length + ' nodes. Ctrl/Cmd+V pastes them.');
+    return true;
+  }
+  function pasteNodes() {
+    if (!copied || !state.graph) return;
+    const copiedIds = new Set(copied.nodes.map(node => node.id));
+    const externalSources = copied.nodes
+      .map(node => node.condition?.source)
+      .filter(source => source && !copiedIds.has(source));
+    // An external Condition source is meaningful only in its original graph.
+    // Reject the entire paste across graphs (even if an unrelated node reuses
+    // the same ID), or if the source was removed in the current graph.
+    if (externalSources.length && (copied.graphId !== state.graph.id ||
+      externalSources.some(source => !Object.hasOwn(state.graph.nodes, source)))) {
+      status('Copy Condition nodes with their source nodes before pasting into another graph.', true);
+      return;
+    }
+    // The free-tier rules live in app.js; a page or harness without them has no allowance to apply.
+    const freeRefusal = typeof freeNodeRefusal === 'function' ? freeNodeRefusal(copied.nodes) : undefined;
+    if (freeRefusal) { status(freeRefusal, true); return; }
+    if (Object.keys(state.graph.nodes).length + copied.nodes.length > nodeLimit(state.graph)) {
+      status('Graph node limit reached. Remove nodes before pasting.', true); return;
+    }
+    pasteOffset += 40;
+    const positions = copied.nodes.map(node => node.position || { x: 120, y: 120 });
+    const shift = axis => {
+      // Apply one shared translation to the selection, preserving relative layout
+      // while keeping every cloned coordinate within the validator's ±100000 range.
+      const lower = Math.max(...positions.map(p => -100000 - p[axis]));
+      const upper = Math.min(...positions.map(p => 100000 - p[axis]));
+      if (lower > upper) return null; // Invalid draft: no shared valid translation exists.
+      if (pasteOffset >= lower && pasteOffset <= upper) return pasteOffset;
+      if (-pasteOffset >= lower && -pasteOffset <= upper) return -pasteOffset;
+      return Math.max(lower, Math.min(upper, pasteOffset));
+    };
+    const dx = shift('x'), dy = shift('y');
+    if (dx === null || dy === null) {
+      status('The selected node positions are outside the supported canvas bounds.', true); return;
+    }
+    mutate(() => {
+      const ids = new Map();
+      for (const original of copied.nodes) ids.set(original.id, original.type + '-' + crypto.randomUUID().slice(0, 8));
+      for (const original of copied.nodes) {
+        const node = copy(original);
+        node.id = ids.get(original.id);
+        // A copied Condition must read its copied predecessor, not the original Agent.
+        // Preserve external references only for existing sources in this same graph.
+        if (node.condition?.source && ids.has(node.condition.source)) {
+          node.condition.source = ids.get(node.condition.source);
+        }
+        // Node names are limited to 200 characters by the graph validator. Keep
+        // duplication usable for nodes already at that limit (including repeat copies).
+        node.name = node.name.slice(0, 195).trimEnd() + ' copy';
+        const p = original.position || { x: 120, y: 120 };
+        node.position = { x: p.x + dx, y: p.y + dy };
+        state.graph.nodes[node.id] = node;
+      }
+      for (const original of copied.edges) state.graph.edges.push({
+        ...copy(original), id: 'edge-' + crypto.randomUUID().slice(0, 8),
+        source: ids.get(original.source), target: ids.get(original.target)
+      });
+      // A pasted copy of a node that still owes its provider assignment owes it too, whether it
+      // lands back in this graph or in another one.
+      for (const originalId of copied.pendingProviderIds ?? []) {
+        state.pendingProviderNodes ||= new Set();
+        state.pendingProviderNodes.add(ids.get(originalId));
+      }
+      clearSelection();
+      state.selectedIds = [...ids.values()]; state.selected = state.selectedIds.at(-1);
+    }, true);
+    showInspector(); status('Pasted ' + copied.nodes.length + ' nodes and their internal connections.');
+  }
+  function installKeyboard() {
+    window.addEventListener('keydown', event => {
+      if (document.querySelector('dialog[open]')) return;
+      if (event.target?.closest('input,textarea,select,[contenteditable]')) return;
+      const mod = event.ctrlKey || event.metaKey;
+      const key = event.key.toLowerCase();
+      if (mod && key === 'c') {
+        // Preserve browser copy for selected diagnostics, context previews and
+        // timeline text. A non-collapsed text selection takes precedence over
+        // the graph's node clipboard, even outside form fields.
+        const selection = window.getSelection?.();
+        if (selection && !selection.isCollapsed) return;
+        event.preventDefault(); copyNodes();
+      }
+      else if (mod && key === 'v') { event.preventDefault(); pasteNodes(); }
+      else if (mod && key === 'd') { event.preventDefault(); if (copyNodes()) pasteNodes(); }
+      else if (mod && key === 'a') {
+        event.preventDefault();
+        state.selectedIds = Object.keys(state.graph?.nodes || {});
+        state.selected = state.selectedIds.at(-1) || null; state.selectedEdge = null;
+        renderCanvas(); renderInspector(); showInspector();
+      }
+      else if (mod && key === 'z') { event.preventDefault(); byId(event.shiftKey ? 'redo' : 'undo')?.click(); }
+      else if (mod && key === 'y') { event.preventDefault(); byId('redo')?.click(); }
+      else if (mod && key === 'g') { event.preventDefault(); studio.createGroup(); }
+      else if (event.key === '?') {
+        showShortcuts();
+      }
+    });
+  }
+
+  /**
+   * The keyboard reference, as the app's dialog: each shortcut a row of keys and what it does.
+   * Keys are drawn as keycaps; a pointer gesture is said in words beside them.
+   */
+  const SHORTCUTS = [
+    { keys: ['Ctrl/Cmd', 'C'], action: 'Copy nodes' }, { keys: ['Ctrl/Cmd', 'V'], action: 'Paste nodes' },
+    { keys: ['Ctrl/Cmd', 'D'], action: 'Duplicate' }, { keys: ['Ctrl/Cmd', 'A'], action: 'Select all' },
+    { keys: ['Ctrl/Cmd', 'G'], action: 'Group' }, { keys: ['Ctrl/Cmd', 'Z'], action: 'Undo' }, { keys: ['Ctrl/Cmd', 'Y'], action: 'Redo' },
+    { keys: ['Shift'], gesture: 'drag the background', action: 'Marquee select' },
+    { keys: [], gesture: 'Drag an output port to a node', action: 'Connect' },
+    { keys: ['Delete'], action: 'Remove selection' },
+  ];
+  const shortcutText = item => [item.keys.join('+'), item.gesture].filter(Boolean).join(item.keys.length ? ' + ' : '');
+  function showShortcuts() {
+    const controls = globalThis.AndorraControls;
+    if (typeof controls?.alert !== 'function') {
+      alert('Graph Studio shortcuts:\n' + SHORTCUTS.map(item => shortcutText(item) + ': ' + item.action).join('\n'));
+      return;
+    }
+    const list = document.createElement('dl');
+    list.className = 'shortcut-list';
+    for (const item of SHORTCUTS) {
+      const term = document.createElement('dt');
+      item.keys.forEach((part, index) => {
+        if (index) term.append('+');
+        const key = document.createElement('kbd');
+        key.textContent = part;
+        term.append(key);
+      });
+      if (item.gesture) term.append(item.keys.length ? ` + ${item.gesture}` : item.gesture);
+      const description = document.createElement('dd');
+      description.textContent = item.action;
+      list.append(term, description);
+    }
+    void controls.alert({ title: 'Graph Studio shortcuts', content: list });
+  }
+
+  function installToolbar() {
+    const toolbar = document.querySelector('.canvas-toolbar');
+    if (!toolbar) return;
+    snapButton = make('button', undefined, 'studio-snap-btn');
+    snapButton.type = 'button';
+    snapButton.setAttribute('aria-label', 'Snap to grid');
+    const magnet = window.AndorraIcons?.icon?.('magnet');
+    if (magnet) snapButton.append(magnet); else snapButton.textContent = 'Snap';
+    snapButton.onclick = () => {
+      state.studioSnap = !state.studioSnap;
+      try { localStorage.setItem('andorra-studio-snap', String(state.studioSnap)); } catch { /* Ephemeral preference is fine. */ }
+      refreshSnap();
+    };
+    toolbar.append(snapButton);
+    refreshSnap();
+    const canvas = byId('canvas');
+    const map = svg('svg');
+    map.id = 'studio-minimap'; map.setAttribute('viewBox', '0 0 160 100');
+    map.setAttribute('role', 'img'); map.setAttribute('aria-label', 'Graph minimap. Click to center on an area.');
+    canvas.append(map);
+  }
+  function refreshSnap() {
+    if (snapButton) {
+      snapButton.title = state.studioSnap ? 'Snap to grid: on' : 'Snap to grid: off';
+      snapButton.setAttribute('aria-pressed', String(state.studioSnap));
+    }
+  }
+  const previous = studio.canvas;
+  studio.canvas = () => { previous?.(); makeGroups(); installPortDragging(); minimap(); };
+  installToolbar();
+  marquee();
+  installKeyboard();
+  studio.canvas();
+})();

package/dist/src/graph-ui/studio.css

@@ -0,0 +1,110 @@
+/*
+ * The authoring studio's secondary controls: the revision dialogs, the run panel, the minimap and
+ * the node state rings. Everything is drawn from `tokens.css`, so the studio follows the same
+ * register in both appearances.
+ */
+
+/* Test and Runs: the two secondary actions that stay in the toolbar. */
+.studio-secondary[aria-pressed="true"] { background: var(--accent-soft); }
+
+.studio-dialog {
+  width: min(620px, calc(100vw - 40px)); max-height: min(84dvh, 860px);
+  border: 1px solid var(--border); border-radius: var(--card-radius); padding: 0;
+  background: var(--bg-input); color: var(--text); box-shadow: var(--shadow-menu);
+}
+.studio-dialog.wide { width: min(840px, calc(100vw - 40px)); }
+.studio-dialog::backdrop { background: var(--overlay); }
+.studio-dialog-head {
+  display: flex; align-items: center; justify-content: space-between; gap: 12px;
+  padding: var(--space-3) var(--space-5); border-bottom: 1px solid var(--border); font-size: var(--type-section); font-weight: var(--weight-strong);
+}
+.studio-dialog-body { padding: var(--space-5); max-height: calc(min(84dvh, 860px) - 65px); overflow: auto; display: flex; flex-direction: column; gap: 10px; }
+.studio-dialog-body > .help { margin: 0 0 8px; line-height: 1.5; }
+.studio-dialog-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin: 10px 0; }
+
+.studio-code {
+  margin: 8px 0 0; width: 100%; padding: 12px; border: 1px solid var(--border);
+  background: var(--bg-card); border-radius: 8px; color: var(--text);
+  font-size: var(--type-xs); line-height: 1.5; font-family: var(--font-mono); white-space: pre-wrap; overflow: auto; overflow-wrap: anywhere; max-height: 380px;
+}
+
+.studio-template { display: flex; align-items: center; gap: 12px; padding: 10px 0; border-bottom: 1px solid var(--border); }
+.studio-template > button { min-width: 132px; text-align: left; }
+.studio-template p { margin: 0; color: var(--text-2); line-height: 1.45; }
+.studio-history-row { padding: 12px; border: 1px solid var(--border); border-radius: 8px; }
+.studio-history-row > strong { display: block; margin-bottom: 4px; }
+.studio-history-row .help { margin: 4px 0 10px; }
+.studio-history-row > button { margin-right: 8px; }
+.studio-test-row { display: grid; gap: 5px; margin: 4px 0; }
+.studio-test-row > span { font-weight: var(--weight-strong); font-size: var(--type-xs); }
+
+.studio-run-panel {
+  flex: 0 0 215px; height: 215px; min-height: 140px; display: flex; flex-direction: column;
+  border-top: 1px solid var(--border); background: var(--bg-surface);
+}
+.studio-run-panel[hidden] { display: none; }
+.studio-run-head { display: flex; align-items: center; gap: 8px; min-height: 44px; padding: 7px 14px; border-bottom: 1px solid var(--border); }
+.studio-run-head strong { font-size: var(--type-xs); white-space: nowrap; }
+.studio-run-head select { width: min(310px, 40%); padding: 5px 8px; }
+.studio-run-head button { padding: 0 var(--space-2); font-size: var(--type-xs); }
+.studio-run-head span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.studio-run-log { flex: 1; overflow: auto; display: flex; flex-direction: column; align-items: stretch; padding: 5px 14px 12px; }
+.studio-run-event {
+  border: 0; border-bottom: 1px solid var(--border); border-radius: 0; text-align: left; padding: 6px 8px;
+  font-family: var(--font-mono); font-size: var(--type-xs); line-height: 1.4; white-space: normal; background: transparent; color: var(--text-2);
+}
+.studio-run-event:hover { background: var(--bg-card); }
+
+#canvas .studio-group-layer { position: absolute; left: 0; top: 0; width: 0; height: 0; pointer-events: none; z-index: 0; }
+#canvas .studio-group {
+  position: absolute; background: var(--accent-soft); border: 1px dashed var(--border-strong);
+  border-radius: 14px; pointer-events: none;
+}
+#canvas .studio-group-title {
+  position: absolute; top: 5px; left: 8px; border: 0; background: var(--bg-input);
+  color: var(--text-2); padding: 2px var(--space-2); min-height: 0; border-radius: var(--row-radius); font-size: var(--type-label); pointer-events: auto;
+}
+#canvas .studio-group-remove {
+  position: absolute; top: 5px; right: 8px; border: 0; background: var(--bg-input);
+  color: var(--text-2); padding: 1px var(--space-2); min-height: 0; border-radius: var(--row-radius); pointer-events: auto;
+}
+#canvas .studio-wire-preview { position: absolute; top: 0; left: 0; pointer-events: none; z-index: 7; }
+#canvas .studio-marquee { position: absolute; border: 1px solid var(--accent); background: var(--accent-soft); pointer-events: none; z-index: 7; }
+
+#studio-minimap {
+  position: absolute; bottom: var(--space-4); right: var(--space-4); width: 160px; height: 100px;
+  border: 1px solid var(--border); background: var(--bg-input); border-radius: 8px;
+  box-shadow: var(--shadow-menu); z-index: 4; cursor: crosshair;
+}
+#studio-minimap .studio-minimap-node { fill: var(--text-3); stroke: var(--border-strong); }
+#studio-minimap .studio-minimap-end { fill: var(--ok); }
+/* The viewport is a faint wash. A webview without `color-mix()` keeps the fallback, which leaves
+   the rectangle unfilled rather than drawing it as a solid block. */
+#studio-minimap .studio-minimap-viewport { fill: transparent; fill: color-mix(in srgb, var(--accent) 10%, transparent); stroke: var(--text-3); stroke-width: 1; pointer-events: none; }
+
+/* Node run states. The live state is the register's own "alive" colour; the settled states are
+   the two colours the chrome allows, done and error. */
+.node.studio-node-preview { box-shadow: 0 0 0 2px var(--warn); }
+.node.studio-node-running { box-shadow: 0 0 0 2px var(--accent); animation: studio-pulse 1.5s ease-in-out infinite; }
+.node.studio-node-complete { box-shadow: 0 0 0 2px var(--ok); }
+.node.studio-node-failed { box-shadow: 0 0 0 2px var(--err); }
+.node.studio-node-cancelled { box-shadow: 0 0 0 2px var(--text-3); }
+@keyframes studio-pulse { 50% { box-shadow: 0 0 0 4px var(--accent-soft); } }
+
+#inspector .studio-code { max-height: 280px; }
+#inspector-body > .section button { white-space: normal; }
+#validation li { cursor: pointer; }
+#validation li:hover { text-decoration: underline; }
+
+@media (max-width: 1060px) {
+  .studio-run-head strong { display: none; }
+}
+@media (max-width: 760px) {
+  #studio-minimap { width: 115px; height: 72px; right: 8px; bottom: 8px; }
+  .studio-run-panel { flex-basis: 180px; height: 180px; }
+  .studio-dialog-body { padding: var(--space-3); }
+}
+@media (prefers-reduced-motion: reduce) { .node.studio-node-running, .node.node-error-pulse { animation: none; } }
+
+/* The route a run has already taken is drawn in the accent, like the traced connection. */
+#edges path.studio-route-visited { stroke: var(--accent); stroke-width: 3; opacity: 1; }