@worca/app 1.2.0-rc.3 → 1.3.0-rc.2

package/ui/public/getting-started.mjs

@@ -0,0 +1,261 @@
+// ui/public/getting-started.mjs
+// The Getting-started checklist (docs/getting-started.md): the tile shelf on the
+// New pipeline view, the sidebar pill that follows the user to other views, and
+// the welcome dialog's bindings. Pure DOM in, pure DOM out — no fetch, no app
+// state — so test/ui-getting-started.test.mjs drives it in jsdom without booting
+// app.js. Completion is never decided here: `status.steps` is the server's word
+// (GET /api/onboarding, src/core/onboarding.mjs), this module only paints it.
+
+/** Shelf order = the arc: prerequisite → first object → see the loop → talk to
+ *  it → know the workflows → real work → scale. Labels are outcomes, never settings. */
+export const GETTING_STARTED_STEPS = Object.freeze([
+  { id: 'claude',      label: 'Connect Claude Code',             vig: 'claude' },
+  { id: 'project',     label: 'Add your first project',          vig: 'project' },
+  { id: 'run',         label: 'Watch a run end to end',          vig: 'run' },
+  { id: 'ask',         label: 'Ask Worca about a run',           vig: 'ask' },
+  { id: 'workflows',   label: 'Explore the built-in workflows',  vig: 'workflow' },
+  { id: 'realRun',     label: 'Run a real pipeline',             vig: 'realRun' },
+  { id: 'workspace',   label: 'Group projects into a workspace', vig: 'workspace' },
+  { id: 'teamMetrics', label: 'Turn on team metrics',            vig: 'teamMetrics' },
+]);
+
+/** Seconds a tile holds the reveal sequence before the next arrives: an
+ *  unfinished tile paints its drawing first, a finished one arrives already
+ *  drawn and still, so it only needs its own fade. */
+const TILE_HOLD = 0.32;
+const DONE_HOLD = 0.1;
+
+export const doneCount = (status) => GETTING_STARTED_STEPS.filter((s) => !!status?.steps?.[s.id]).length;
+export const allStepsDone = (status) => doneCount(status) === GETTING_STARTED_STEPS.length;
+
+/* ---------------------------------------------------------------- artwork */
+// Each vignette is the app's own vocabulary — hollow nodes, wires, one accent
+// element per scene (the violet "Worca-authored" hue) — drawn at 120×70 on the
+// theme tokens so both schemes are right by construction. `--d` is the element's
+// slot in the tile's own sequence; the tile's `--tile-delay` offsets all of them.
+// Constant markup only (no user data reaches innerHTML).
+const el = (tag, cls, d, attrs) => `<${tag} class="${cls}" style="--d:${d}s" ${attrs}/>`;
+const node = (d, cx, cy, r = 6, extra = '') => el('circle', `gs-pop gs-node ${extra}`.trim(), d, `cx="${cx}" cy="${cy}" r="${r}"`);
+const wire = (d, path, extra = '') => el('path', `gs-draw gs-wire ${extra}`.trim(), d, `pathLength="1" d="${path}"`);
+const shape = (d, tag, cls, attrs) => el(tag, `gs-pop ${cls}`, d, attrs);
+
+const VIGNETTES = {
+  // The terminal prompt, then the once-node lights up: the CLI is reachable.
+  claude: () => [
+    shape(0.05, 'rect', 'gs-frame', 'x="12" y="14" width="56" height="42" rx="7"'),
+    shape(0.3, 'path', 'gs-glyph', 'd="M24 28l8 7-8 7M36 42h12"'),
+    wire(0.5, 'M68 35 C 80 35, 86 35, 96 35'),
+    node(0.8, 102, 35, 6, 'gs-accent'),
+  ],
+  // A folder, then a node grows out of it.
+  project: () => [
+    shape(0.05, 'path', 'gs-frame', 'd="M14 22a4 4 0 0 1 4-4h12l6 6h22a4 4 0 0 1 4 4v22a4 4 0 0 1-4 4H18a4 4 0 0 1-4-4z"'),
+    wire(0.35, 'M62 38 C 76 38, 84 30, 96 26'),
+    node(0.6, 102, 24, 6, 'gs-accent'),
+  ],
+  // The loop: plan → refine → implement → review, the review wire curling back.
+  run: () => [
+    node(0.05, 16, 35, 5),
+    wire(0.15, 'M22 35h18'),
+    node(0.3, 46, 35, 5),
+    wire(0.4, 'M52 35h18'),
+    node(0.55, 76, 35, 5),
+    wire(0.65, 'M82 35h18'),
+    node(0.8, 106, 35, 5, 'gs-accent'),
+    wire(0.9, 'M76 41 C 76 58, 46 58, 46 41'),
+  ],
+  // The same pipeline, but the last node carries a spark: real tokens spent.
+  realRun: () => [
+    node(0.05, 18, 35, 5),
+    wire(0.15, 'M24 35h16'),
+    node(0.3, 46, 35, 5),
+    wire(0.4, 'M52 35h16'),
+    node(0.55, 74, 35, 5),
+    wire(0.65, 'M80 35h14'),
+    shape(0.85, 'path', 'gs-spark gs-accent', 'd="M104 26l2.2 5.6 5.6 2.2-5.6 2.2-2.2 5.6-2.2-5.6-5.6-2.2 5.6-2.2z"'),
+  ],
+  // A speech bubble reaches a run's node.
+  ask: () => [
+    shape(0.05, 'path', 'gs-frame', 'd="M14 18h34a7 7 0 0 1 7 7v10a7 7 0 0 1-7 7H28l-9 9v-9h-5a7 7 0 0 1-7-7V25a7 7 0 0 1 7-7z"'),
+    shape(0.25, 'path', 'gs-glyph', 'd="M24 31h18"'),
+    wire(0.45, 'M55 34 C 72 34, 82 40, 96 40'),
+    node(0.7, 102, 40, 6, 'gs-accent'),
+  ],
+  // A canvas: three nodes being wired by hand, the new wire in accent.
+  workflow: () => [
+    node(0.05, 22, 22, 6),
+    node(0.15, 22, 50, 6),
+    node(0.25, 64, 36, 6),
+    wire(0.4, 'M28 24 C 44 28, 50 32, 58 34'),
+    wire(0.5, 'M28 48 C 44 44, 50 40, 58 38'),
+    wire(0.65, 'M70 36 C 82 36, 88 36, 96 36', 'gs-accent'),
+    node(0.85, 102, 36, 6, 'gs-accent'),
+  ],
+  // Two project folders under one roof.
+  workspace: () => [
+    shape(0.05, 'rect', 'gs-frame', 'x="14" y="26" width="26" height="22" rx="5"'),
+    shape(0.15, 'rect', 'gs-frame', 'x="48" y="26" width="26" height="22" rx="5"'),
+    wire(0.35, 'M27 26 C 27 12, 61 12, 61 26'),
+    wire(0.5, 'M74 37 C 84 37, 90 37, 96 37'),
+    node(0.75, 102, 37, 6, 'gs-accent'),
+  ],
+  // A shared branch: three teammates' nodes feeding one line.
+  teamMetrics: () => [
+    node(0.05, 18, 18, 5),
+    node(0.15, 18, 35, 5),
+    node(0.25, 18, 52, 5),
+    wire(0.35, 'M24 18 C 44 18, 50 35, 64 35'),
+    wire(0.45, 'M24 35h40'),
+    wire(0.55, 'M24 52 C 44 52, 50 35, 64 35'),
+    wire(0.65, 'M64 35h30'),
+    shape(0.85, 'path', 'gs-chart gs-accent', 'd="M84 46l6-8 5 4 7-10"'),
+  ],
+};
+
+/**
+ * One tile's artwork. `animate` false paints the FINISHED drawing with no
+ * motion — a step already done should not ask for attention again.
+ * @param {Document} doc
+ * @param {string} id  a GETTING_STARTED_STEPS vig key
+ * @param {{animate:boolean, delay:number}} o
+ */
+export function vignette(doc, id, { animate = true, delay = 0 } = {}) {
+  const svg = doc.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  svg.setAttribute('viewBox', '0 0 120 70');
+  svg.setAttribute('aria-hidden', 'true');
+  svg.setAttribute('class', `gs-vig-svg ${animate ? 'play' : 'static'}`);
+  svg.style.setProperty('--tile-delay', `${delay}s`);
+  const parts = (VIGNETTES[id] || (() => []))();
+  svg.innerHTML = parts.join('');
+  return svg;
+}
+
+/* ------------------------------------------------------------------ shelf */
+
+/**
+ * Paint the shelf into `host` (emptied first). Nothing is painted when the
+ * status is unusable or the user hid the checklist. Rows stay clickable after
+ * they are done, so any guide can be replayed.
+ * @param {Element} host
+ * @param {{steps?:Record<string,boolean>, hidden?:boolean}|null} status
+ * @param {{onStep?:(id:string)=>void, onHide?:()=>void, animate?:boolean, hideLabel?:string}} [handlers]
+ */
+export function renderGettingStarted(host, status, { onStep, onHide, animate = true, hideLabel = 'Hide' } = {}) {
+  if (!host) return;
+  const doc = host.ownerDocument;
+  host.replaceChildren();
+  if (!status || !status.steps || typeof status.steps !== 'object' || status.hidden) { host.hidden = true; return; }
+  host.hidden = false;
+  const done = doneCount(status);
+  const total = GETTING_STARTED_STEPS.length;
+
+  const card = doc.createElement('section');
+  card.className = 'card gs-card';
+  card.setAttribute('role', 'complementary');
+  card.setAttribute('aria-label', 'Getting started');
+
+  const head = doc.createElement('div');
+  head.className = 'gs-head';
+  const h2 = doc.createElement('h2');
+  h2.textContent = done === total ? 'All set' : 'Your progress';   // the page's topbar already says Getting started
+  const progress = doc.createElement('span');
+  progress.className = 'gs-progress';
+  progress.textContent = `${done} of ${total}`;
+  const hide = doc.createElement('button');
+  hide.type = 'button';
+  hide.className = 'gs-hide';
+  hide.textContent = hideLabel;
+  hide.title = 'The sidebar entry; Settings › General › Getting started also opens this page';
+  hide.addEventListener('click', () => onHide && onHide());
+  head.append(h2, progress, hide);
+  card.appendChild(head);
+
+  const tiles = doc.createElement('div');
+  tiles.className = 'gs-tiles';
+  // Tiles arrive one at a time IN ORDER, so a new user reads one idea at a
+  // time instead of eight at once. A finished tile takes its turn but arrives
+  // already drawn and still, so it holds the sequence only briefly.
+  let at = 0;
+  for (const s of GETTING_STARTED_STEPS) {
+    const isDone = !!status.steps[s.id];
+    const delay = at;
+    at += isDone ? DONE_HOLD : TILE_HOLD;
+    const tile = doc.createElement('button');
+    tile.type = 'button';
+    tile.className = `gs-tile${animate ? ' reveal' : ''}${isDone ? ' done' : ''}`;
+    tile.dataset.step = s.id;
+    tile.style.setProperty('--tile-delay', `${animate ? delay : 0}s`);
+    tile.setAttribute('aria-label', `${s.label} — ${isDone ? 'done' : 'not done yet'}`);
+    const mark = doc.createElement('span');
+    mark.className = 'gs-mark';
+    mark.setAttribute('aria-hidden', 'true');
+    mark.textContent = '✓';
+    const vig = doc.createElement('span');
+    vig.className = 'gs-vig';
+    vig.appendChild(vignette(doc, s.vig, { animate: animate && !isDone, delay }));
+    const label = doc.createElement('span');
+    label.className = 'gs-label';
+    label.textContent = s.label;
+    tile.append(mark, vig, label);
+    tile.addEventListener('click', () => onStep && onStep(s.id));
+    tiles.appendChild(tile);
+  }
+  card.appendChild(tiles);
+  host.appendChild(card);
+}
+
+/* ------------------------------------------------------------------- pill */
+
+/**
+ * The sidebar row under New pipeline: "Getting started · 2/8". It follows the
+ * user to every view (the guides leave the shelf behind) and vanishes once the
+ * checklist is hidden or complete — nothing left to nag about.
+ * @param {Element} host
+ * @param {object|null} status
+ * @param {() => void} onOpen
+ */
+export function renderGettingStartedPill(host, status, onOpen) {
+  if (!host) return;
+  const doc = host.ownerDocument;
+  host.replaceChildren();
+  if (!status || !status.steps || status.hidden || allStepsDone(status)) { host.hidden = true; return; }
+  host.hidden = false;
+  const done = doneCount(status);
+  const total = GETTING_STARTED_STEPS.length;
+  const btn = doc.createElement('button');
+  btn.type = 'button';
+  btn.className = 'gs-pill';
+  btn.setAttribute('aria-label', `Getting started — ${done} of ${total} done`);
+  btn.title = 'Getting started';
+  btn.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 12.5l4.5 4.5L20 6"></path></svg>';
+  const text = doc.createElement('span');
+  text.textContent = 'Getting started';
+  const count = doc.createElement('span');
+  count.className = 'nav-count n-grey gs-pill-count';
+  count.textContent = `${done}/${total}`;
+  btn.append(text, count);
+  btn.addEventListener('click', () => onOpen && onOpen());
+  host.appendChild(btn);
+}
+
+/* ---------------------------------------------------------------- welcome */
+
+/**
+ * Wire the static welcome dialog (#welcome-modal in index.html): each door
+ * hands its step id to `onDoor`, Skip / the backdrop / Esc call `onSkip`.
+ * Returns a function that unbinds the Esc listener (the modal itself is reused).
+ * @param {Element} modal
+ * @param {{onDoor:(step:string)=>void, onSkip:()=>void, win?:Window}} h
+ */
+export function bindWelcome(modal, { onDoor, onSkip, win }) {
+  if (!modal) return () => {};
+  const w = win || modal.ownerDocument.defaultView;
+  for (const door of modal.querySelectorAll('[data-door]')) {
+    door.addEventListener('click', () => onDoor(door.dataset.door));
+  }
+  modal.querySelector('.ob-skip')?.addEventListener('click', () => onSkip());
+  modal.addEventListener('click', (e) => { if (e.target === modal) onSkip(); });
+  const onKey = (e) => { if (e.key === 'Escape' && !modal.classList.contains('hidden')) onSkip(); };
+  w.document.addEventListener('keydown', onKey);
+  return () => w.document.removeEventListener('keydown', onKey);
+}

package/ui/public/graph/composer.mjs

@@ -14,7 +14,7 @@ import { createGraphView } from './view.mjs';
 import { renderPalette, applyFilter, FLOW_GROUP } from './palette.mjs';
 import { renderNodeInspector, renderWireInspector, renderEmptyInspector } from './inspector.mjs';
 import { renderSaveDialog, openDialog, closeDialog } from './save-dialog.mjs';
-import { PORT_HIT_R, SNAP, ZOOM_MIN, ZOOM_MAX, ZOOM_K, NODE_W, snap }
+import { PORT_HIT_R, SNAP, ZOOM_MIN, ZOOM_MAX, ZOOM_K, ZOOM_STEP, NODE_W, snap }
   from '../../../src/shared/graph/geometry.mjs';
 import { hitRoute } from '../../../src/shared/graph/route.mjs';
 import { canWire, newNode, newWire, normalizeTemplate, serializeTemplate }
@@ -28,6 +28,10 @@ export const UNDO_LIMIT = 50;
  *  the composer and app.js share one literal (the saved list hides the ×, the
  *  Save dialog prefills a copy name). */
 export const RESERVED_WORKFLOW_ID = 'wf_default';
+/** Every built-in the server lists and refuses to delete: wf_default + the Memory defragment
+ *  workflow. Both open read-only here (Save is Save-a-copy). wf_auto never reaches the composer. */
+export const RESERVED_WORKFLOW_IDS = new Set([RESERVED_WORKFLOW_ID, 'wf_memory_defrag']);
+export const isReservedWorkflowId = (id) => RESERVED_WORKFLOW_IDS.has(id);
 export const INSPECTOR_KEY = 'worca.composer.inspector';
 export const TAB_KEY = 'worca.composer.tab';
 export const TABS = Object.freeze(['agents', 'info']);
@@ -65,7 +69,7 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
 
   const view = createGraphView(hostEls.canvas, {
     doc, mode: 'edit', portsFn, agents, viewport,
-    zoomMin: ZOOM_MIN, zoomMax: ZOOM_MAX, wheelPan: 'always',
+    zoomMin: ZOOM_MIN, zoomMax: ZOOM_MAX,
   });
   const stage = view.stage;
 
@@ -369,11 +373,15 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
   const onRefresh = () => readRect();
   const onNewCanvas = () => composer.newCanvas();
   const onSaveClick = () => openSaveDialog();
+  const onZoomIn = () => zoomStep(ZOOM_STEP);
+  const onZoomOut = () => zoomStep(1 / ZOOM_STEP);
+  const onCenterClick = () => fit();
 
   function zoomAbout(zNext, sx, sy) {
     const t = T();
     const z2 = clamp(zNext, ZOOM_MIN, ZOOM_MAX);
     view.setTransform({ x: sx - ((sx - t.x) / t.z) * z2, y: sy - ((sy - t.y) / t.z) * z2, z: z2 });
+    paintNav();
   }
 
   function onWheel(ev) {
@@ -395,6 +403,27 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
   }
   function fit(opts = {}) {
     view.fit({ insetRight: opts.insetRight == null ? insetRight() : opts.insetRight, pad: 60 });
+    paintNav();
+  }
+  /** Stage-local centre of the band the rail leaves visible — the point the
+   *  buttons zoom about and centre to. Reads the rect itself: the rail may have
+   *  been collapsed since the last gesture. */
+  function bandCenter() {
+    readRect();
+    return { x: (R.width - insetRight()) / 2, y: R.height / 2 };
+  }
+  /** One discrete zoom press. zoomAbout owns the 0.4..1.6 clamp. */
+  function zoomStep(mult) {
+    const c = bandCenter();
+    zoomAbout(T().z * mult, c.x, c.y);
+  }
+  /** The cluster's only state: a button that cannot move is disabled. Guarded
+   *  per element — every headless caller (unit tests, the CDP probe) may hand us
+   *  hostEls without a cluster at all. */
+  function paintNav() {
+    const z = T().z;
+    if (hostEls.zoomIn) hostEls.zoomIn.disabled = z >= ZOOM_MAX - 1e-9;
+    if (hostEls.zoomOut) hostEls.zoomOut.disabled = z <= ZOOM_MIN + 1e-9;
   }
   // `autoLayout(tpl, portsFn)` returns a POSITION MAP `{ [nodeId]: {x, y} }` — not
   // a template, not `{nodes}` (verified 2026-08-27 against src/shared/graph/layout.mjs,
@@ -677,7 +706,7 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
    *  @returns {{copy: boolean, plugin: string}} */
   function saveMode(saveAs) {
     const plugin = pluginOriginName(tplOrigin);
-    return { copy: Boolean(saveAs) || tpl.id === RESERVED_WORKFLOW_ID || Boolean(plugin), plugin };
+    return { copy: Boolean(saveAs) || isReservedWorkflowId(tpl.id) || Boolean(plugin), plugin };
   }
 
   function openSaveDialog({ saveAs = false } = {}) {
@@ -713,7 +742,7 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
     // Save on a LOADED row sends its id; a copy omits it so the server mints
     // wf_${slugify(name)}. `dataset.saveAs` already carries saveMode()'s verdict,
     // so the reserved built-in and every plugin-owned row land here as copies.
-    if (!saveAs && tpl.id && tpl.id !== RESERVED_WORKFLOW_ID) body.id = tpl.id;
+    if (!saveAs && tpl.id && !isReservedWorkflowId(tpl.id)) body.id = tpl.id;
     else delete body.id;
     try {
       const res = await api.saveWorkflow(body);
@@ -786,6 +815,9 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
     hostEls.insToggle?.addEventListener('click', onRailToggle);
     hostEls.insTabs?.addEventListener('click', onTabClick);
     hostEls.saveBtn?.addEventListener('click', onSaveClick);
+    hostEls.zoomIn?.addEventListener('click', onZoomIn);
+    hostEls.zoomOut?.addEventListener('click', onZoomOut);
+    hostEls.centerBtn?.addEventListener('click', onCenterClick);
     setRail(readKey(INSPECTOR_KEY) !== 'collapsed');
     setTab(readKey(TAB_KEY) || TABS[0]);
     // The model/effort lists are chrome, not graph state: pull them once through
@@ -803,6 +835,7 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
       ro.observe(stage);
     }
     readRect();
+    paintNav();
     return composer;
   }
   let ro = null;
@@ -822,6 +855,9 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
     hostEls.insToggle?.removeEventListener('click', onRailToggle);
     hostEls.insTabs?.removeEventListener('click', onTabClick);
     hostEls.saveBtn?.removeEventListener('click', onSaveClick);
+    hostEls.zoomIn?.removeEventListener('click', onZoomIn);
+    hostEls.zoomOut?.removeEventListener('click', onZoomOut);
+    hostEls.centerBtn?.removeEventListener('click', onCenterClick);
     endPalDrag();
     stage.removeEventListener('pointermove', onMove);
     stage.removeEventListener('pointerup', onUp);
@@ -866,7 +902,7 @@ export function createComposer(hostEls, { doc = globalThis.document, api, raf =
   const composer = {
     view, stats, hooks,
     mount, destroy, resume, suspend, commit, loadTemplate,
-    fit, autoLayout: runAutoLayout, zoomAbout, undo, redo, undoDepth: () => undoStack.length, deleteSelection,
+    fit, autoLayout: runAutoLayout, zoomAbout, zoomStep, undo, redo, undoDepth: () => undoStack.length, deleteSelection,
     spawn, paintPalette, paintInspector,
     openSaveDialog, setSavedDomains(list) { savedDomains = list || []; },
     setModels(cfg) { modelsSet = true; applyModels(cfg || {}); },

package/ui/public/graph/inspector.mjs

@@ -31,7 +31,9 @@ function select(doc, cls, name, label, items, value, { disabled = false, title =
     if (opt.value === (value == null ? '' : String(value))) o.selected = true;
     sel.appendChild(o);
   }
-  wrap.appendChild(sel);
+  const shell = h(doc, 'span', 'ins-select-wrap');   // the product's .select-wrap idea: the chevron is a token-coloured ::after on a wrapper
+  shell.appendChild(sel);
+  wrap.appendChild(shell);
   return wrap;
 }
 function toggle(doc, cls, name, label, hint, { checked = false, disabled = false, title = '' } = {}) {

package/ui/public/graph/model.mjs

@@ -35,3 +35,4 @@ export {
   TEMPLATE_VERSION, KINDS, FLOW_KINDS, PORT_TYPES, AWAIT_PORT, TASK_PORTS, END_PORTS,
   gatePorts, DEFAULT_MAX_CYCLES, MAX_PORTS_PER_SIDE, LIMITS, NODE_ID_RE, WIRE_ID_RE, PORT_ID_RE,
 } from '../../../src/shared/graph/constants.mjs';
+export { flowOrder, flowPerRow, flowLayout, flowAnchors, routeFlow, simplifyOrtho, FLOW_SCALE, FLOW_DEFAULT_WIDTH, FLOW_RADIUS } from '../../../src/shared/graph/flow-layout.mjs';

package/ui/public/graph/run-hosts.mjs

@@ -12,12 +12,24 @@
 // with the footer rows the view actually painted (never a second band count).
 import { createGraphView } from './view.mjs';
 import { applyDecor, manifestAgents, manifestNodes, manifestPortsFn, manifestTemplate } from './run-decor.mjs';
-import { fitBounds } from '../../../src/shared/graph/geometry.mjs';
+import { fitBounds, ZOOM_STEP } from '../../../src/shared/graph/geometry.mjs';
 
 export const STATIC_HOST_H = 300;      // D5: the Running list card's graph height
 export const STATIC_INSET = 32;        // wrap padding allowance on both axes (16 each side)
 export const DETAIL_MIN_H = 360, DETAIL_MAX_H = 600, DETAIL_PAD_H = 48;
-export const HINT_TEXT = 'click to pan · ⌘+scroll to zoom';
+export const HINT_TEXT = 'drag to pan · ⌘/ctrl+scroll to zoom';
+/** px of monitor canvas the nav cluster owns: 30px button + 12px inset + 12px air.
+ *  The composer reserves `insetRight` for its rail for exactly this reason — the
+ *  cluster is opaque and clickable, and an auto-fit that ignores it parks the
+ *  bottom-right card's .xtoggle strip underneath. */
+export const NAV_INSET = 54;
+/** The cluster's three buttons: [data-nav, label, glyph]. The glyphs are the
+ *  composer's (ui/public/index.html #gv-nav) so both canvases read identically. */
+const NAV_BTNS = [
+  ['in', 'Zoom in', '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" aria-hidden="true"><path d="M12 5v14M5 12h14" stroke-linecap="round"></path></svg>'],
+  ['out', 'Zoom out', '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.4" aria-hidden="true"><path d="M5 12h14" stroke-linecap="round"></path></svg>'],
+  ['center', 'Fit graph to view', '<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="4.5" y="4.5" width="15" height="15" rx="2.5"></rect><circle cx="12" cy="12" r="2.6" fill="currentColor" stroke="none"></circle></svg>'],
+];
 const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
 
 /** Centre `b` (already padded) in a vw×vh viewport through the SHARED `fitBounds`;
@@ -39,7 +51,7 @@ export function mountRunGraph(hostEl, opts = {}) {
   const isStatic = mode === 'static';
   const zoomMin = 0.3, zoomMax = isStatic ? 1 : 1.6;
 
-  let view = null, stepper = null, decor = null, runId = null, expanded = null, ro = null, lastFit = null, bound = false;
+  let view = null, stepper = null, decor = null, runId = null, expanded = null, ro = null, lastFit = null, bound = false, nav = null;
   // The last width `view.readRect()` reported. A host inside a `display:none`
   // subtree (compact density, a closed detail) measures 0×0, and both fitters
   // BAIL on that rather than poison the transform / --run-host-h with it; the
@@ -92,17 +104,64 @@ export function mountRunGraph(hostEl, opts = {}) {
     if (!(r.width > 0)) return;                 // hidden host (0×0): a 0-width fit would
     const b = view.bounds(24);                  // pin --run-host-h at the 360px floor and
     if (!b) return;                             // zoom to the 0.3 clamp for good.
-    const vw = Math.max(1, r.width);
+    const vw = Math.max(1, r.width - NAV_INSET);   // the cluster is opaque and clickable
     const zw = clamp(Math.min(vw / b.w, 1), zoomMin, 1);
     const hostH = clamp(Math.round((b.h - 48) * zw + DETAIL_PAD_H), DETAIL_MIN_H, DETAIL_MAX_H);   // b is padded 24 each side
     wrap.style.setProperty('--run-host-h', `${hostH}px`);
     if (applyTransform) view.setTransform(fitInto(b, vw, hostH, { zoomMin }));
   }
 
+  /** Stage-local centre of the host box — the point the buttons zoom about.
+   *  Reads the rect itself: the host may have resized since the last fit. */
+  function hostCenter() {
+    const r = view.readRect();
+    return { x: (r.width || 0) / 2, y: (r.height || 0) / 2 };
+  }
+  /** One discrete zoom press; view.zoomAbout owns the zoomMin..zoomMax clamp. */
+  function zoomStep(mult) {
+    if (!view) return;
+    const c = hostCenter();
+    view.zoomAbout(view.getTransform().z * mult, c.x, c.y);
+    paintNav();
+  }
+  /** The cluster's only state: a button that cannot move is disabled. Guarded —
+   *  a static host never builds a cluster, and destroy() drops it. */
+  function paintNav() {
+    if (!nav || !view) return;
+    const z = view.getTransform().z;
+    nav.querySelector('[data-nav="in"]').disabled = z >= zoomMax - 1e-9;
+    nav.querySelector('[data-nav="out"]').disabled = z <= zoomMin + 1e-9;
+  }
+  function buildNav() {
+    nav = doc.createElement('div');
+    nav.className = 'gv-nav';
+    for (const [key, label, glyph] of NAV_BTNS) {
+      const b = doc.createElement('button');
+      b.type = 'button';
+      b.className = 'gv-nav-btn';
+      b.dataset.nav = key;
+      b.setAttribute('aria-label', label);
+      b.title = label;
+      b.innerHTML = glyph;                        // a literal from this module, never run data
+      nav.appendChild(b);
+    }
+    // A SIBLING of the stage, like .rg-hint: a press on a button can never reach
+    // the drag pipeline (the rule the composer's own cluster follows).
+    wrap.appendChild(nav);
+    on(nav, 'click', (e) => {
+      const btn = e.target.closest && e.target.closest('.gv-nav-btn');
+      if (!btn) return;
+      if (btn.dataset.nav === 'in') zoomStep(ZOOM_STEP);
+      else if (btn.dataset.nav === 'out') zoomStep(1 / ZOOM_STEP);
+      else fit();                                 // Center = zoom-to-fit, and it re-arms the auto re-fit
+    });
+  }
+
   function fit() {
     if (!view || !stepper) return;
     if (isStatic) fitStatic(); else fitMonitor(true);
     lastFit = view.getTransform();
+    paintNav();
   }
   /** The size pass without the transform (monitor only; static hosts never grow). */
   function sizeHost() {
@@ -124,12 +183,11 @@ export function mountRunGraph(hostEl, opts = {}) {
     hostEl.classList.add('gv-host');
     wrap.classList.add('gv-wrap', isStatic ? 'gv-wrap-static' : 'gv-wrap-monitor');
     view = createGraphView(hostEl, { mode, doc, raf, viewport,
-      portsFn: manifestPortsFn(stepper), agents: manifestAgents(stepper), zoomMin, zoomMax,
-      wheelPan: isStatic ? 'always' : 'engaged' });
-    // The view never auto-binds a nav: monitor hosts ask for one (D8 engaged-only)
-    // and learn engagement from it — run-hosts keeps NO engagement state of its own,
-    // and view.destroy() destroys every nav, so the handle is not kept.
-    if (!isStatic) view.createNav({ wheelPan: 'engaged', onEngaged: (engaged) => wrap.classList.toggle('rg-engaged', engaged) });
+      portsFn: manifestPortsFn(stepper), agents: manifestAgents(stepper), zoomMin, zoomMax });
+    // The view never auto-binds a nav: monitor hosts ask for one. There is no
+    // engagement state any more — a plain wheel is always the page's (D2) — and
+    // onTransform is how a wheel zoom or a drag repaints the cluster.
+    if (!isStatic) view.createNav({ onTransform: paintNav });
   }
 
   function update(nextRunId, nextStepper, nextDecor) {
@@ -158,7 +216,9 @@ export function mountRunGraph(hostEl, opts = {}) {
       hint.className = 'rg-hint';
       hint.textContent = HINT_TEXT;
       wrap.appendChild(hint);
-      // (engage/disengage listeners live in the view's nav — see mount() above)
+      buildNav();
+      paintNav();
+      // (the wheel + drag gestures live in the view's nav — see mount() above)
       on(hostEl, 'click', (e) => {
         const toggle = e.target.closest && e.target.closest('.xtoggle');
         if (toggle) { expanded = expanded === toggle.dataset.nodeId ? null : toggle.dataset.nodeId; paint(); refit(); return; }
@@ -183,9 +243,10 @@ export function mountRunGraph(hostEl, opts = {}) {
     if (ro) { try { ro.disconnect(); } catch { /* jsdom */ } ro = null; }
     const hint = wrap.querySelector(':scope > .rg-hint');
     if (hint) hint.remove();
+    if (nav) { nav.remove(); nav = null; }
     if (view) { view.destroy(); view = null; }   // view.destroy() tears every nav down
     hostEl.classList.remove('gv-host');
-    wrap.classList.remove('gv-wrap', 'gv-wrap-static', 'gv-wrap-monitor', 'rg-engaged');
+    wrap.classList.remove('gv-wrap', 'gv-wrap-static', 'gv-wrap-monitor');
     wrap.style.removeProperty('--run-host-h');
     hostEl.style.width = '';
     hostEl.innerHTML = '';