@andorra-labs/code 0.0.0-stage → 0.1.5

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

@@ -0,0 +1,720 @@
+/* Graph Studio productivity, authoring, safe preview, and run-inspection surfaces. */
+(() => {
+  'use strict';
+  const $studio = id => document.getElementById(id);
+  const element = (tag, content, className) => {
+    const node = document.createElement(tag);
+    if (content !== undefined) node.textContent = String(content);
+    if (className) node.className = className;
+    return node;
+  };
+  const action = (label, handler, className) => {
+    const button = element('button', label, className || '');
+    button.type = 'button';
+    button.onclick = async () => {
+      button.disabled = true;
+      try { await handler(); }
+      catch (error) { status(error instanceof Error ? error.message : String(error), true); }
+      finally { button.disabled = false; }
+    };
+    return button;
+  };
+  function modal(title, build, wide = false) {
+    const dialog = element('dialog', undefined, 'studio-dialog' + (wide ? ' wide' : ''));
+    const head = element('header', undefined, 'studio-dialog-head');
+    head.append(element('strong', title), action('Close', () => dialog.close()));
+    const body = element('div', undefined, 'studio-dialog-body');
+    dialog.append(head, body);
+    document.body.append(dialog);
+    dialog.onclose = () => dialog.remove();
+    build(body, dialog);
+    dialog.showModal();
+    return dialog;
+  }
+  // The app's own dialogs (controls.js); the platform's where that layer is absent (the test harness).
+  const askConfirm = options => typeof globalThis.AndorraControls?.confirm === 'function'
+    ? globalThis.AndorraControls.confirm(options)
+    : Promise.resolve(confirm([options.title, options.message].filter(Boolean).join('\n\n')));
+  const askText = options => typeof globalThis.AndorraControls?.prompt === 'function'
+    ? globalThis.AndorraControls.prompt(options)
+    : Promise.resolve(prompt(options.title, options.value ?? ''));
+  const paragraph = (parent, text, cls = 'help') => { const p = element('p', text, cls); parent.append(p); return p; };
+  const setText = (parent, text) => { parent.replaceChildren(element('pre', text, 'studio-code')); };
+  const currentId = () => state.graph?.id;
+  let liveEvents = [], debuggerOpen = false, selectedRun = '', pollHandle, lastGraph = '', runRefreshEpoch = 0;
+  let inspectedGraphId = '', inspectedRevision = null;
+  let preview = null, previewFingerprint = '';
+  const graphFingerprint = () => state.graph ? JSON.stringify(state.graph) : '';
+  const previewMatchesDraft = () => !!preview && previewFingerprint === graphFingerprint();
+  function acceptPreviewIfCurrent(candidate, fingerprint) {
+    if (fingerprint !== graphFingerprint()) return false;
+    preview = candidate; previewFingerprint = fingerprint;
+    return true;
+  }
+  const runMatchesCanvas = () => debuggerOpen && !!selectedRun && inspectedGraphId === currentId()
+    && Number.isInteger(inspectedRevision) && inspectedRevision === state.graph?.revision && !state.dirty;
+  function nodeActivityTotals(events) {
+    const sum = { input: 0, output: 0, tools: 0, failures: 0 };
+    // Real agent.model.completed events report CUMULATIVE executor usage.
+    // Difference snapshots within each invocation (which can interleave with
+    // parallel executions), never sum graph-wide or terminal usage snapshots.
+    const modelSnapshots = new Map();
+    let legacyVisit = 0;
+    for (const event of events) {
+      if (event.type === 'graph.node.started') legacyVisit++;
+      if (event.type === 'node.tool.completed' || event.type === 'node.tool.failed') sum.tools++;
+      if (event.type === 'node.tool.failed') sum.failures++;
+      if (!event.usage) continue;
+      if (event.type === 'agent.model.completed') {
+        const key = event.invocationId || 'unstamped-visit-' + legacyVisit;
+        const previous = modelSnapshots.get(key) || { inputTokens: 0, outputTokens: 0 };
+        const current = event.usage;
+        const increment = (now, before) => now >= before ? now - before : now; // Reset on a new invocation.
+        sum.input += increment(current.inputTokens || 0, previous.inputTokens);
+        sum.output += increment(current.outputTokens || 0, previous.outputTokens);
+        modelSnapshots.set(key, { inputTokens: current.inputTokens || 0, outputTokens: current.outputTokens || 0 });
+      } else if (event.type === 'node.model.response') {
+        // Legacy node.model.response events are individual request snapshots.
+        sum.input += event.usage.inputTokens || 0;
+        sum.output += event.usage.outputTokens || 0;
+      }
+    }
+    return sum;
+  }
+  let inspectorContextId = '';
+
+  function diffGraph(before, after) {
+    const a = before.nodes || {}, b = after.nodes || {};
+    const add = Object.keys(b).filter(id => !Object.hasOwn(a, id));
+    const remove = Object.keys(a).filter(id => !Object.hasOwn(b, id));
+    const change = Object.keys(b).filter(id => Object.hasOwn(a, id) && JSON.stringify(a[id]) !== JSON.stringify(b[id]));
+    // Revision comparisons must include every routing-semantic field, especially
+    // bootstrap (initial Join-all bypass) and toInput. Include edge identity too.
+    const edges = graph => new Set((graph.edges || []).map(e => JSON.stringify([
+      e.id, e.source, e.outcome || 'completed', e.target, e.toInput, e.inputMapping, e.bootstrap === true
+    ])));
+    const oldEdges = edges(before), newEdges = edges(after);
+    return {
+      added: add, removed: remove, changed: change,
+      edgesAdded: [...newEdges].filter(edge => !oldEdges.has(edge)).length,
+      edgesRemoved: [...oldEdges].filter(edge => !newEdges.has(edge)).length,
+    };
+  }
+  function describeDiff(before, after) {
+    const delta = diffGraph(before, after);
+    return 'Added nodes: ' + (delta.added.join(', ') || 'none') +
+      '\nRemoved nodes: ' + (delta.removed.join(', ') || 'none') +
+      '\nChanged nodes: ' + (delta.changed.join(', ') || 'none') +
+      '\nConnections added: ' + delta.edgesAdded +
+      '\nConnections removed: ' + delta.edgesRemoved +
+      '\nGraph settings changed: ' + (JSON.stringify({
+        name: before.name, entry: before.entry, limits: before.limits, widgets: before.widgets,
+        inputSchema: before.inputSchema, stateSchema: before.stateSchema, metadata: before.metadata
+      }) !== JSON.stringify({
+        name: after.name, entry: after.entry, limits: after.limits, widgets: after.widgets,
+        inputSchema: after.inputSchema, stateSchema: after.stateSchema, metadata: after.metadata
+      }) ? 'yes' : 'no');
+  }
+  async function applyDraft(next, message, install) {
+    if (state.dirty && !await askConfirm({ title: 'Replace your unsaved edits?', message: 'Recoverable drafts are saved separately.', confirmLabel: 'Replace', tone: 'danger' })) return false;
+    clearSelection();
+    state.graph = dropLegacyTokenFields(copy(next));
+    state.dirty = true;
+    state.undo = [];
+    state.redo = [];
+    preview = null;
+    // Provider requirements are graph-specific: a replacement (template, restored revision)
+    // starts without them, and an import installs its own through the callback below. A
+    // cancelled confirm leaves the previously open graph's own requirements in place.
+    state.pendingProviderNodes = null;
+    install?.();
+    render(); fit();
+    status(message || 'Draft loaded. Save a revision to publish it.');
+    return true;
+  }
+
+  // Every import entry point (file dialog, Plus menu, canvas drop, desktop host handoff)
+  // funnels through this one pipeline, so validation, id minting and provider reconciliation
+  // have a single owner.
+  async function importGraphJson(data) {
+    if (typeof canCreateGraph === 'function' && !canCreateGraph()) throw new Error(FREE_CREATE_TIP);
+    if (!data || typeof data !== 'object' || Array.isArray(data) || !data.nodes || typeof data.nodes !== 'object'
+      || Array.isArray(data.nodes) || !Array.isArray(data.edges)) throw new Error('The file is not an Andorra graph.');
+    const next = { ...data, id: newId(), revision: 0 };
+    delete next.editorMigration;
+    delete next.pendingProviderNodes; // a shared file never carries this editor's draft marker
+    // A graph shared from another machine can name providers this one does not configure.
+    // Null those rather than letting the draft silently run on an endpoint its author never
+    // chose; save then stays blocked until each such node is assigned a provider explicitly.
+    for (const node of Object.values(next.nodes)) {
+      if (node?.type !== 'agent' || typeof node.provider !== 'string' || !node.provider.trim()) continue;
+      if (!state.providers.some(provider => idFor(provider) === node.provider)) node.provider = undefined;
+    }
+    const validated = await api('/api/validate', { graph: next });
+    const pending = Object.values(validated.graph.nodes)
+      .filter(node => node.type === 'agent' && !node.provider).map(node => node.id);
+    if (await applyDraft(validated.graph, pending.length
+      ? 'Imported graph. Assign a model profile to every outlined node, then save.'
+      : 'Imported graph validated. Save its first revision.',
+      // The install runs after applyDraft's marker-stripping copy, so the requirements are
+      // mirrored onto the live draft here — that mirror is what an autosave persists and a
+      // later draft recovery restores.
+      () => { state.pendingProviderNodes = new Set(pending); if (typeof syncImportRequirementsMarker === 'function') syncImportRequirementsMarker(); })) return true;
+    return false;
+  }
+  async function importGraphFile(file) {
+    if (!file) throw new Error('Choose a JSON file first.');
+    if (file.size > 450 * 1024) throw new Error('The JSON file exceeds the graph size limit.');
+    return importGraphJson(JSON.parse(await file.text()));
+  }
+
+  function openImport() {
+    modal('Import graph JSON', body => {
+      paragraph(body, 'Import creates a new graph ID and never overwrites the original graph. Only validated graph JSON is accepted.');
+      // The app's drop zone and Browse button; the platform's bare file input only where that
+      // layer is absent.
+      const picker = typeof globalThis.AndorraControls?.filePicker === 'function'
+        ? globalThis.AndorraControls.filePicker({ accept: '.json,application/json', label: 'Choose a graph JSON file', hint: 'or drop it here · up to 450 KB' })
+        : (() => {
+          const input = element('input');
+          input.type = 'file';
+          input.accept = '.json,application/json';
+          input.setAttribute('aria-label', 'Choose graph JSON');
+          return { element: input, file: () => input.files?.[0] };
+        })();
+      const feedback = element('p', '', 'help');
+      feedback.setAttribute('role', 'status');
+      body.append(picker.element, feedback);
+      body.append(action('Import as new graph', async () => {
+        const chosen = picker.file();
+        if (!chosen) throw new Error('Choose a JSON file first.');
+        if (await importGraphFile(chosen)) {
+          feedback.textContent = 'Import complete: new unsaved graph ready.';
+        }
+      }, 'primary'));
+    });
+  }
+
+  async function newTemplate(kind) {
+    if (typeof canCreateGraph === 'function' && !canCreateGraph()) { status(FREE_CREATE_TIP, true); return; }
+    const base = copy(await api('/api/graphs/default'));
+    base.id = newId();
+    base.revision = 0;
+    delete base.metadata?.updatedAt;
+    const engineer = base.nodes.engineer;
+    const end = base.nodes.done;
+    if (kind === 'fast') {
+      base.name = 'Fast Fix';
+      base.entry = 'engineer';
+      delete base.nodes.orchestrator;
+      base.edges = [{ id: 'engineer-done', source: 'engineer', target: 'done', outcome: 'completed' }];
+      engineer.position = { x: 120, y: 120 };
+      end.position = { x: 440, y: 120 };
+      engineer.instruction = 'Inspect the task, make the smallest correct change, run the relevant verification and report the outcome.';
+    } else {
+      const qa = {
+        id: 'reviewer', name: kind === 'review' ? 'PR Reviewer' : 'QA Reviewer',
+        type: 'agent', executor: 'react-basic',
+        instruction: kind === 'review' ?
+          'Inspect the implementation and tests. Return pass only if requirements are satisfied; otherwise return fail with concrete fixes required.' :
+          'Review the implementation and run permitted read-only quality checks. Report any reproducible defect before completing.',
+        completion: kind === 'review' ?
+          { mode: 'outcomes', outcomes: ['pass', 'fail'], requireRoutes: true,
+            criteria: { pass: 'Changes meet the acceptance criteria.', fail: 'A reproducible defect or unmet requirement remains.' } } :
+          { mode: 'single', outcome: 'completed' },
+        capabilities: { filesystem: 'read', shell: 'disabled', git: 'read', github: 'none', browser: 'playwright', deployment: 'none' },
+        contextPolicy: { history: true, predecessors: 'direct' },
+        position: { x: 660, y: 120 },
+      };
+      base.nodes.reviewer = qa;
+      end.position = { x: 980, y: 120 };
+      base.edges = base.edges.filter(edge => !(edge.source === 'engineer' && edge.target === 'done'));
+      base.edges.push({ id: 'engineer-reviewer', source: 'engineer', target: 'reviewer', outcome: 'completed' });
+      base.edges.push({ id: 'reviewer-done', source: 'reviewer', target: 'done', outcome: kind === 'review' ? 'pass' : 'completed' });
+      if (kind === 'review') {
+        base.name = 'Review and Repair';
+        // The review can send the work back as often as it needs, so the visits are unlimited and
+        // the run's clock is what ends the cycle.
+        const { maxNodeVisits: _visits, ...rest } = base.limits ?? {};
+        base.limits = { ...rest, wallTimeMs: 30 * 60_000 };
+        base.edges.push({ id: 'reviewer-engineer', source: 'reviewer', target: 'engineer', outcome: 'fail' });
+      } else base.name = 'QA Gate';
+    }
+    const validated = await api('/api/validate', { graph: base });
+    await applyDraft(validated.graph, 'Template created. Review permissions and save a revision.');
+  }
+
+  function openTemplates() {
+    modal('Start from a workflow template', body => {
+      paragraph(body, 'Templates are editable local drafts. They never run or save automatically.');
+      for (const [id, name, desc] of [
+        ['fast', 'Fast Fix', 'Direct coding-agent flow without an intake Orchestrator'],
+        ['review', 'Review and Repair', 'Implement, review, then retry defects for as long as the run clock allows'],
+        ['qa', 'QA Gate', 'Research, implement, and pass through an independent read-only QA Agent'],
+      ]) {
+        const row = element('div', undefined, 'studio-template');
+        row.append(action(name, () => newTemplate(id), 'primary'));
+        paragraph(row, desc);
+        body.append(row);
+      }
+    });
+  }
+
+  async function openHistory() {
+    if (!state.graph) return;
+    const graphId = state.graph.id;
+    const graphAtOpen = state.graph;
+    const baseRevision = graphAtOpen.revision;
+    const fingerprint = graphFingerprint();
+    const rows = await api('/api/graphs/' + encodeURIComponent(graphId) + '/revisions');
+    // A different graph may have been opened before the revision list loaded.
+    if (state.graph !== graphAtOpen || graphFingerprint() !== fingerprint) return;
+    modal('Saved revision history', (body, dialog) => {
+      const controller = new AbortController();
+      dialog.addEventListener('close', () => controller.abort(), { once: true });
+      const current = () => !controller.signal.aborted && dialog.open &&
+        state.graph === graphAtOpen && graphFingerprint() === fingerprint;
+      paragraph(body, 'Snapshots are immutable. Restoring a past revision opens a draft; saving creates a new revision.');
+      if (!rows.length) { paragraph(body, 'No saved revisions. Save this graph first.'); return; }
+      for (const row of rows) {
+        const item = element('section', undefined, 'studio-history-row');
+        item.append(element('strong', 'Revision ' + row.revision + ' · ' + row.name));
+        paragraph(item, row.nodeCount + ' nodes · ' + row.edgeCount + ' connections' +
+          (row.updatedAt ? ' · ' + new Date(row.updatedAt).toLocaleString() : ''));
+        const detail = element('pre', '', 'studio-code');
+        const fetchRevision = async () => {
+          try { return await api('/api/graphs/' + encodeURIComponent(graphId) + '/revisions/' + row.revision, undefined, { signal: controller.signal }); }
+          catch (error) { if (controller.signal.aborted || !current()) return null; throw error; }
+        };
+        item.append(action('Compare', async () => {
+          if (!current()) return;
+          const snapshot = await fetchRevision();
+          if (!snapshot || !current()) return;
+          detail.textContent = describeDiff(snapshot, graphAtOpen);
+        }));
+        item.append(action('Restore as draft', async () => {
+          if (!current()) return;
+          const snapshot = await fetchRevision();
+          if (!snapshot || !current()) return;
+          const next = { ...snapshot, id: graphId === 'default' ? newId() : graphId,
+            revision: graphId === 'default' ? 0 : baseRevision };
+          if (await applyDraft(next, 'Restored revision ' + row.revision + ' into a draft. Save to publish it.')) {
+            dialog.close();
+          }
+        }, 'primary'));
+        item.append(detail);
+        body.append(item);
+      }
+    }, true);
+  }
+
+  function openTest() {
+    if (!state.graph) return;
+    modal('Dry-run route preview', body => {
+      paragraph(body, 'No model calls, shell commands, file writes, or approvals are executed. Choose mock outcomes to explore possible paths. This is not a full runtime simulation.');
+      const inputs = new Map();
+      const mockOutputs = new Map();
+      for (const node of Object.values(state.graph.nodes)) {
+        const decisions = outcomes(node);
+        const canMockOutput = node.type === 'agent' || node.type === 'action';
+        if (decisions.length < 2 && !canMockOutput) continue;
+        const row = element('label', undefined, 'studio-test-row');
+        row.append(element('span', node.name + (decisions.length > 1 ? ' — outcome' : ' — mock output')));
+        if (decisions.length > 1) {
+          const selector = element('select');
+          selector.append(new Option('Choose an outcome…', ''));
+          for (const name of decisions) selector.append(new Option(name, name));
+          row.append(selector); inputs.set(node.id, selector);
+        }
+        if (canMockOutput) {
+          const mock = element('input');
+          mock.placeholder = 'Mock output JSON (optional; e.g. {"approved":true})';
+          mock.setAttribute('aria-label', node.name + ' mock output');
+          row.append(mock); mockOutputs.set(node.id, mock);
+        }
+        body.append(row);
+      }
+      const results = element('pre', '', 'studio-code');
+      body.append(action('Preview routing', async () => {
+        const choices = {};
+        for (const [id, select] of inputs) choices[id] = select.value ? { outcome: select.value } : {};
+        for (const [id, input] of mockOutputs) {
+          const value = input.value.trim();
+          if (!value) continue;
+          const parsed = JSON.parse(value);
+          if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('Mock output for ' + id + ' must be a JSON object.');
+          choices[id] ||= {};
+          choices[id].output = parsed;
+        }
+        const fingerprint = graphFingerprint();
+        const candidate = await api('/api/preview', { graph: state.graph, choices });
+        if (!acceptPreviewIfCurrent(candidate, fingerprint)) {
+          results.textContent = 'Graph changed during preview. Run the preview again against the updated draft.';
+          return;
+        }
+        const steps = preview.steps.map((step, i) => (i + 1) + '. ' + step.nodeName + ' → ' + step.outcome +
+          ' → ' + (step.targetIds.join(', ') || 'end')).join('\n');
+        const blocked = preview.blocked.map(item => item.nodeId + ': ' + item.reason).join('\n');
+        results.textContent = (steps || 'No transitions simulated.') +
+          (blocked ? '\n\nUnresolved mock decisions:\n' + blocked : '') +
+          (preview.truncated ? '\n\nPreview stopped at the bounded safety limit.' : '') +
+          '\n\nCompleted paths: ' + preview.completed.length;
+        renderCanvas();
+      }, 'primary'));
+      body.append(results);
+      body.append(action('How to run live', () => {
+        paragraph(body, 'Open Andorra Code in your project, select the saved graph using /graph, then enter your task. The CLI retains its normal permission and approval gates. Save the draft first.');
+      }));
+    }, true);
+  }
+
+  function contextPreview(node) {
+    const effective = {
+      name: node.name, kind: node.agentRole || node.type,
+      provider: node.provider || state.defaultProvider || 'configured default',
+      model: node.model || (state.providers.find(p => p.id === (node.provider || state.defaultProvider))?.model || 'provider default'),
+      instruction: node.instruction ?? node.prompt ?? '',
+      systemPrompt: node.systemPrompt || '(runtime defaults)',
+      contextPolicy: node.contextPolicy || {},
+      inputMappings: node.inputs || {},
+      allowedTools: node.tools || '(default toolset)', capabilities: node.capabilities || '(runtime defaults)',
+      subagents: node.subagents || { enabled: false },
+    };
+    const chars = effective.instruction.length + (node.systemPrompt || '').length + JSON.stringify(effective.inputMappings).length;
+    return 'Approximate configured prompt/mapping size: ~' + Math.ceil(chars / 4) + ' tokens (characters ÷ 4 heuristic)\n' +
+      'Actual runtime history, tool outputs and provider tokenization are not included.\n\n' + JSON.stringify(effective, null, 2);
+  }
+  // Dot-separated value expressions cannot address literal dotted schema keys.
+  function representableSourceField(key) {
+    return /^[a-zA-Z0-9_-]+$/.test(key) && !['__proto__', 'constructor', 'prototype'].includes(key);
+  }
+  function enhanceInspector(parent, node) {
+    if (node?.type === 'agent') {
+      const region = section(parent, 'Context preview');
+      paragraph(region, 'Inspect configured instructions, context sharing, permissions, and approximate prompt size. Runtime messages may differ.');
+      region.append(action('Preview effective settings', () => {
+        const pre = element('pre', contextPreview(node), 'studio-code');
+        region.replaceChildren(pre);
+        region.prepend(action('Refresh preview', () => { pre.textContent = contextPreview(node); }));
+      }));
+    }
+    if (node && liveEvents.length && runMatchesCanvas()) {
+      const events = liveEvents.filter(event => event.nodeId === node.id);
+      if (events.length) {
+        const region = section(parent, 'Selected run — node activity');
+        const totals = nodeActivityTotals(events);
+        const completion = events.filter(event => event.type === 'graph.node.completed').at(-1);
+        paragraph(region, 'Latest outcome: ' + (completion?.outcome || 'pending') +
+          ' · Tool calls: ' + totals.tools + ' · Tool failures: ' + totals.failures +
+          ' · Input tokens: ' + totals.input + ' · Output tokens: ' + totals.output +
+          ' (from available run events)');
+      }
+    }
+    if (state.selectedEdge) {
+      const edge = state.selectedEdge;
+      const from = state.graph.nodes[edge.source], to = state.graph.nodes[edge.target];
+      const targets = Object.keys(to?.inputSchema?.properties || {});
+      // Dot-path expressions cannot address literal schema keys containing a dot.
+      const sources = Object.keys(from?.outputSchema?.properties || {}).filter(representableSourceField);
+      const region = section(parent, 'Visual field mapping');
+      paragraph(region, 'Map a declared output field to a destination input without typing a mapping expression.');
+      if (!targets.length || !sources.length) {
+        paragraph(region, 'Declare input/output JSON schemas with representable source fields (letters, digits, underscore or hyphen). Fields containing dots require manual mapping or schema changes.');
+      } else {
+        const dest = element('select'); const source = element('select');
+        for (const key of targets) { const opt = element('option', key); opt.value = key; dest.append(opt); }
+        for (const key of sources) { const opt = element('option', key); opt.value = key; source.append(opt); }
+        region.append(element('span', 'Destination field'), dest, element('span', 'Source output field'), source);
+        region.append(action('Create mapping', () => {
+          mutate(() => { edge.inputMapping ||= {}; edge.inputMapping[dest.value] = '$source.output.' + source.value; }, true);
+          renderInspector();
+        }, 'primary'));
+      }
+    }
+    if (selectedNodes().length > 1) {
+      const region = section(parent, 'Layout group');
+      region.append(action('Group selected nodes (Ctrl/Cmd+G)', createGroup));
+    }
+  }
+
+  function canCreateLayoutGroup(groups, selectedIds) {
+    // Re-grouping can remove existing groups whose last member is selected.
+    // Count the survivors rather than blindly rejecting whenever there are 50.
+    return groups.filter(group => group.nodeIds.some(id => !selectedIds.has(id))).length < 50;
+  }
+
+  async function createGroup() {
+    const nodes = selectedNodes().filter(node => node.agentRole !== 'orchestrator');
+    if (nodes.length < 2) { status('Select at least two nodes to group.', true); return; }
+    const ids = new Set(nodes.map(node => node.id));
+    if (!canCreateLayoutGroup(state.graph?.metadata?.studioLayoutGroupsV1 || [], ids)) {
+      status('A graph supports at most 50 layout groups. Remove or merge a group before creating another.', true);
+      return;
+    }
+    const name = await askText({ title: 'Name this layout group', label: 'Layout group name', value: 'New group', confirmLabel: 'Create group', maxLength: 80 });
+    if (!name) return;
+    if (!name.trim() || name.length > 80) { status('Group names must contain 1–80 characters.', true); return; }
+    mutate(() => {
+      state.graph.metadata ||= {};
+      const groups = state.graph.metadata.studioLayoutGroupsV1 || [];
+      for (const group of groups) group.nodeIds = group.nodeIds.filter(id => !ids.has(id));
+      state.graph.metadata.studioLayoutGroupsV1 = [...groups.filter(group => group.nodeIds.length), {
+        id: 'group-' + crypto.randomUUID().slice(0, 8), name: name.trim(), nodeIds: [...ids],
+      }];
+    }, true);
+    status('Layout group created. Groups are saved with the graph.');
+  }
+
+  function renderDebugger() {
+    const box = $studio('studio-run-panel');
+    if (!box) return;
+    box.hidden = !debuggerOpen;
+    const log = $studio('studio-run-log');
+    if (!debuggerOpen || !log) return;
+    log.replaceChildren();
+    if (!selectedRun) { paragraph(log, 'Select a saved run to inspect its node transitions.'); return; }
+    const matchesCanvas = runMatchesCanvas();
+    if (!matchesCanvas && liveEvents.length) {
+      paragraph(log, 'Historical run differs from the current graph revision or unsaved draft. Canvas overlays and node navigation are disabled.');
+    }
+    for (const event of liveEvents.slice(-100).reverse()) {
+      const item = element('button', undefined, 'studio-run-event');
+      const focusId = event.nodeId || event.source;
+      const name = (matchesCanvas ? state.graph?.nodes[focusId]?.name : undefined)
+        || focusId || 'Graph';
+      item.textContent = (event.time ? new Date(event.time).toLocaleTimeString() + ' · ' : '') +
+        name + ' · ' + event.type +
+        (event.outcome ? ' (' + event.outcome + ')' : '') +
+        (event.durationMs !== null ? ' · ' + event.durationMs + 'ms' : '') +
+        (event.usage ? ' · ' + event.usage.inputTokens + ' in / ' + event.usage.outputTokens + ' out' : '');
+      item.disabled = !matchesCanvas || !state.graph?.nodes[focusId];
+      item.onclick = () => {
+        if (runMatchesCanvas() && focusId && state.graph?.nodes[focusId]) {
+          clearSelection(); state.selected = focusId; state.selectedIds = [focusId];
+          renderCanvas(); renderInspector(); showInspector();
+        }
+      };
+      log.append(item);
+    }
+    renderCanvas();
+  }
+  async function refreshRunList() {
+    if (!state.graph || !debuggerOpen) return;
+    const graphId = state.graph.id;
+    const epoch = ++runRefreshEpoch;
+    // A response for a different graph or a superseded run must never paint
+    // over the current editor, even if a previous request completes last.
+    const current = () => debuggerOpen && currentId() === graphId && epoch === runRefreshEpoch;
+    const runs = await api('/api/runs?graph=' + encodeURIComponent(graphId));
+    if (!current()) return;
+    const select = $studio('studio-run-select');
+    if (!select) return;
+    select.replaceChildren(new Option('Choose a run…', ''));
+    for (const run of runs) {
+      const option = new Option((run.startedAt ? new Date(run.startedAt).toLocaleString() + ' · ' : '') +
+        run.status + (run.graphRevision !== null ? ' · r' + run.graphRevision : ''), run.id);
+      select.append(option);
+    }
+    if (!runs.some(run => run.id === selectedRun)) selectedRun = runs[0]?.id || '';
+    select.value = selectedRun;
+    const note = $studio('studio-run-info');
+    if (selectedRun) {
+      const runId = selectedRun;
+      const response = await api('/api/runs/' + encodeURIComponent(runId) + '/events?graph=' + encodeURIComponent(graphId));
+      if (!current() || selectedRun !== runId) return;
+      liveEvents = response.events;
+      inspectedGraphId = graphId;
+      const summary = runs.find(run => run.id === runId);
+      // A pre-upgrade open record might have no pinned revision yet; the
+      // sanitized graph.started event can recover it without exposing the graph.
+      const startedRevision = response.events.find(event =>
+        event.type === 'graph.started' && Number.isInteger(event.graphRevision))?.graphRevision;
+      inspectedRevision = Number.isInteger(summary?.graphRevision) ? summary.graphRevision
+        : (Number.isInteger(startedRevision) ? startedRevision : null);
+      if (note) note.textContent = 'Status: ' + response.status +
+        (response.truncated ? ' · Showing recent events only' : '');
+    } else {
+      liveEvents = [];
+      inspectedGraphId = ''; inspectedRevision = null;
+      if (note) note.textContent = '';
+    }
+    renderDebugger();
+    // Polling replaces the accepted event projection; selected-node activity
+    // totals are derived from that projection, not just from selection changes.
+    if (state.selected && state.graph?.nodes[state.selected]) renderInspector();
+  }
+  function scheduleRunPoll() {
+    clearTimeout(pollHandle);
+    if (!debuggerOpen) return;
+    pollHandle = setTimeout(async () => {
+      try { await refreshRunList(); } catch (error) { status('Run inspector: ' + error.message, true); }
+      scheduleRunPoll();
+    }, 3500);
+  }
+  async function toggleDebugger() {
+    debuggerOpen = !debuggerOpen;
+    runRefreshEpoch++;
+    if (!debuggerOpen) {
+      liveEvents = [];
+      inspectedGraphId = ''; inspectedRevision = null;
+      renderCanvas(); renderInspector();
+    } else await refreshRunList();
+    renderDebugger();
+    scheduleRunPoll();
+  }
+
+  const glyph = (name, size) => window.AndorraIcons?.icon?.(name, size) || null;
+  let runsButton, hostMenuGroup;
+
+  // The toolbar's overflow menu: the actions used now and then, behind one "More actions" button.
+  // It follows the menu-button pattern: arrows move between items, Escape and Tab close it, and
+  // a click outside dismisses it.
+  function installMenu() {
+    const more = $studio('more'), menu = $studio('more-menu'), wrap = $studio('more-wrap');
+    if (!more || !menu) return;
+    const items = () => [...menu.querySelectorAll('[role="menuitem"]')].filter(item => !item.disabled && !item.hidden);
+    const close = (focus = false) => {
+      if (menu.hidden) return;
+      menu.hidden = true; more.setAttribute('aria-expanded', 'false');
+      if (focus) more.focus();
+    };
+    const open = () => { menu.hidden = false; more.setAttribute('aria-expanded', 'true'); items()[0]?.focus(); };
+    more.onclick = event => { event.stopPropagation(); if (menu.hidden) open(); else close(); };
+    more.addEventListener('keydown', event => {
+      if (event.key === 'ArrowDown' || event.key === 'Enter' || event.key === ' ') { event.preventDefault(); open(); }
+    });
+    menu.addEventListener('keydown', event => {
+      const list = items(), index = list.indexOf(document.activeElement);
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+        event.preventDefault();
+        list[(index + (event.key === 'ArrowDown' ? 1 : -1) + list.length) % list.length]?.focus();
+      } else if (event.key === 'Home') { event.preventDefault(); list[0]?.focus(); }
+      else if (event.key === 'End') { event.preventDefault(); list.at(-1)?.focus(); }
+      else if (event.key === 'Escape') { event.preventDefault(); close(true); }
+      else if (event.key === 'Tab') close();
+    });
+    // Choosing an item closes the menu before the item's own work begins.
+    menu.addEventListener('click', event => { if (event.target.closest?.('[role="menuitem"]')) close(); });
+    document.addEventListener('pointerdown', event => { if (!wrap?.contains(event.target)) close(); });
+  }
+  function menuItem(label, icon, handler) {
+    const item = action(label, handler);
+    item.setAttribute('role', 'menuitem');
+    const mark = glyph(icon); if (mark) item.prepend(mark);
+    return item;
+  }
+  // The desktop app's own actions (Reload, notifications) join the menu when it hosts the editor.
+  function setHostMenu(entries) {
+    const menu = $studio('more-menu');
+    if (!menu) return;
+    hostMenuGroup?.forEach(node => node.remove());
+    hostMenuGroup = [];
+    if (!entries?.length) return;
+    const rule = element('hr'); rule.setAttribute('role', 'separator');
+    hostMenuGroup.push(rule); menu.append(rule);
+    for (const entry of entries) {
+      const item = menuItem(entry.label, entry.icon, entry.run);
+      item.disabled = !!entry.disabled;
+      hostMenuGroup.push(item); menu.append(item);
+    }
+  }
+  function refreshRunsButton() {
+    if (runsButton) runsButton.setAttribute('aria-pressed', String(debuggerOpen));
+  }
+
+  function initialize() {
+    const chrome = document.querySelector('.chrome');
+    if (!chrome) return;
+    const actions = $studio('chrome-actions'), toggle = $studio('toggle-inspector'), menu = $studio('more-menu');
+    // Test and Runs stay one click away as secondary buttons; the rest live in the menu.
+    for (const [name, icon, handler, title] of [
+      ['Test', 'flask', openTest, 'Preview routes with mock outcomes. Nothing runs.'],
+      ['Runs', 'activity', async () => { await toggleDebugger(); refreshRunsButton(); }, 'Show or hide the run timeline'],
+    ]) {
+      const button = action(name, handler, 'btn-small studio-secondary');
+      button.title = title;
+      button.replaceChildren(element('span', name));
+      const mark = glyph(icon); if (mark) button.prepend(mark);
+      if (name === 'Runs') { runsButton = button; refreshRunsButton(); }
+      if (actions && toggle) actions.insertBefore(button, toggle); else chrome.append(button);
+    }
+    if (menu) {
+      for (const [name, icon, handler] of [
+        ['Templates', 'template', openTemplates], ['Import', 'upload', openImport],
+        ['History', 'history', openHistory],
+      ]) menu.append(menuItem(name, icon, handler));
+      installMenu();
+    }
+
+    const main = document.querySelector('main');
+    const panel = element('section', undefined, 'studio-run-panel');
+    panel.id = 'studio-run-panel'; panel.hidden = true;
+    const head = element('div', undefined, 'studio-run-head');
+    head.append(element('strong', 'Graph execution timeline'));
+    const select = element('select'); select.id = 'studio-run-select';
+    select.setAttribute('aria-label', 'Choose saved run');
+    select.onchange = async () => {
+      selectedRun = select.value; liveEvents = [];
+      await refreshRunList();
+    };
+    const info = element('span', '', 'help'); info.id = 'studio-run-info';
+    head.append(select, action('Refresh', refreshRunList, 'btn-small'), action('Close', async () => { await toggleDebugger(); refreshRunsButton(); }, 'btn-small'), info);
+    const log = element('div', undefined, 'studio-run-log'); log.id = 'studio-run-log';
+    panel.append(head, log);
+    main.insertBefore(panel, main.querySelector('.status'));
+  }
+  function heading() {
+    if (currentId() !== lastGraph) {
+      lastGraph = currentId();
+      runRefreshEpoch++;
+      preview = null; previewFingerprint = '';
+      liveEvents = []; selectedRun = ''; inspectedGraphId = ''; inspectedRevision = null;
+      if (debuggerOpen) void refreshRunList().catch(() => {});
+    }
+    if (preview && !previewMatchesDraft()) {
+      preview = null; previewFingerprint = '';
+    }
+  }
+  function nodeStatuses(events) {
+    const result = new Map();
+    for (const event of events) {
+      if (!event.nodeId) continue;
+      if (event.type === 'graph.node.started') result.set(event.nodeId, 'studio-node-running');
+      if (event.type === 'graph.node.completed') result.set(event.nodeId, 'studio-node-complete');
+      // The runtime emits tool failures and terminal graph.stopped, not graph.node.failed.
+      if (event.type === 'node.tool.failed') result.set(event.nodeId, 'studio-node-failed');
+      if (event.type === 'graph.stopped' || event.type === 'graph.completed') {
+        // Parallel branches can have graph.node.started emitted ahead of their
+        // completion. A terminal run event ends ALL pending branches, not only
+        // the one named in graph.stopped.nodeId.
+        for (const [nodeId, status] of result) {
+          if (status === 'studio-node-running') result.set(nodeId, 'studio-node-cancelled');
+        }
+      }
+      if (event.type === 'graph.stopped') {
+        if (event.status === 'cancelled') result.set(event.nodeId, 'studio-node-cancelled');
+        else if (event.status !== 'succeeded') result.set(event.nodeId, 'studio-node-failed');
+        else result.set(event.nodeId, 'studio-node-complete');
+      }
+    }
+    return result;
+  }
+  function canvas() {
+    const success = new Set(previewMatchesDraft() ? preview.steps.map(step => step.nodeId) : []);
+    const executed = nodeStatuses(runMatchesCanvas() ? liveEvents : []);
+    const activeRoutes = new Set((runMatchesCanvas() ? liveEvents : []).filter(event => event.type === 'graph.edge.activated')
+      .map(event => JSON.stringify([event.source, event.outcome || 'completed', event.target])));
+    for (const route of $studio('edges')?.querySelectorAll('path[data-route]') || []) {
+      route.classList.toggle('studio-route-visited', activeRoutes.has(route.getAttribute('data-route')));
+    }
+    for (const node of $studio('nodes')?.children || []) {
+      const id = node.getAttribute('data-node-id');
+      node.classList.toggle('studio-node-preview', success.has(id));
+      for (const name of ['studio-node-running', 'studio-node-complete', 'studio-node-failed', 'studio-node-cancelled'])
+        node.classList.toggle(name, executed.get(id) === name);
+    }
+  }
+
+  window.AndorraStudio = { heading, canvas, inspector: enhanceInspector, createGroup, canCreateLayoutGroup, describeDiff, nodeStatuses, nodeActivityTotals, representableSourceField, refreshRunList, toggleDebugger, runMatchesCanvas, setHostMenu, previewMatchesDraft, acceptPreviewIfCurrent, openHistory, openImport, importGraphJson, importGraphFile };
+  initialize();
+})();