synabun 2.0.0 → 2.0.7

package/neural-interface/public/shared/synabun-mascot.js

@@ -8,11 +8,13 @@
 // the face, plus one prop drawn in the face's own pill geometry. Rigs draw
 // from the shared ticker (shared/synabun-ticker.js): 30 fps while a pose
 // loops, 60 fps for blends and reactions, no frames at all while still. One
-// pointermove listener and one IntersectionObserver serve every rig, and only
-// one rig at a time plays a pose loop (the one posed most recently); the
-// others hold their pose's still frame. Under prefers-reduced-motion every
-// pose is its still frame and changes are instant. A rig tears itself down
-// once its SVG leaves the document.
+// loop, one pointermove listener and one IntersectionObserver serve every rig,
+// and every rig that is active and on screen plays its own pose: N rigs move
+// at once, each on its own clock. No rig waits for another; a host that wants
+// one moving character among several of its own (an Assistant panel's hero,
+// stage and "Thinking" row) says so with setActive(). Under
+// prefers-reduced-motion every pose is its still frame and changes are
+// instant. A rig tears itself down once its SVG leaves the document.
 //
 // v1 callers are unchanged: createMascot(container, opts) → { el, destroy,
 // look, blink }, idle, blinking every 3-7 s and following the cursor.
@@ -35,7 +37,8 @@
  *   `opts.count` 1-3 (subagent minis), `opts.mode` 'recall' | 'remember'
  *   (memory), `opts.ticks` 0-3 (plan), `opts.then` a pose to blend to once a
  *   one-shot (success, error, blocked) has played and held. The same pose with
- *   a new count or ticks keeps its loop running.
+ *   a new count or ticks keeps its loop running. `opts.unlimited` selects the
+ *   budget pose's relaxed infinity variant; project peeks into a folder.
  * - `react(name)` — `MASCOT_REACTIONS`: hop (spring, at most one per 600 ms),
  *   wince, nod, pop (plan: pops the newest tick; ticks the next box too
  *   unless setPose passed `ticks`), startle, pulse, click
@@ -79,7 +82,7 @@ export const MASCOT_VIEWBOX = '0 0 280 140';
 /** One pose per tool kind (shared with the activity rack's kind ids). */
 export const MASCOT_KINDS = Object.freeze(['shell', 'read', 'edit', 'search', 'web', 'subagent', 'plan', 'memory', 'runs', 'computer', 'think', 'mcp']);
 export const MASCOT_STATES = Object.freeze(['idle', 'sleep', 'watch', 'wait', 'success', 'error', 'blocked', 'offline']);
-export const MASCOT_POSES = Object.freeze([...MASCOT_KINDS, ...MASCOT_STATES]);
+export const MASCOT_POSES = Object.freeze([...MASCOT_KINDS, ...MASCOT_STATES, 'project', 'budget']);
 export const MASCOT_REACTIONS = Object.freeze(['hop', 'wince', 'nod', 'pop', 'startle', 'pulse', 'click']);
 
 /** The character's SVG. Colour comes from `currentColor` (the mouth at 25 %). */
@@ -143,6 +146,8 @@ export function mascotCameoSvg({ className = '' } = {}) {
 
 /** Each prop's own box in face units, to draw it alone (a ledger row's glyph, a suggestion's). */
 const PROP_BOX = Object.freeze({
+  project: [204, 77, 62, 48],
+  budget: [212, 65, 54, 60],
   shell: [144, 116, 42, 26], // the last keycap and the caret
   read: [65, 20, 150, 88],
   edit: [188, 93, 56, 44],
@@ -307,12 +312,37 @@ const MINIS = [
 ];
 
 /**
- * motion: 'loop' (30 fps while it leads), 'blink' (still between slow blinks),
+ * motion: 'loop' (30 fps), 'blink' (still between slow blinks),
  * 'once' (plays `settle` ms, then still; `hold` before opts.then), 'still'.
  * blinks: random blinks every 3-7 s. tracks: follows the cursor.
  * look: follows look(), easing with this time constant (ms).
  */
 const POSES = {
+  // Empty-state controls: host-directed gaze, the same ticker and prop painter as tool kinds.
+  project: {
+    motion: 'loop', blinks: true, look: 70,
+    frame(t, o) {
+      const f = blankFrame();
+      const peek = o.still ? 0.5 : (1 + Math.sin(TAU * t / 2400)) / 2;
+      f.eyes = [eye(0, 2 + 2 * peek, 1, 0.92, -2), eye(0, 2 + 2 * peek, 1, 0.96, 2)];
+      f.mouth = mouth(34, 11);
+      gaze(f, o.look, { x: 16, y: 10 });
+      f.prop = { name: 'project', peek };
+      return f;
+    },
+  },
+  budget: {
+    motion: 'loop', blinks: true, look: 70,
+    frame(t, o) {
+      const f = blankFrame();
+      const lift = o.still ? 0 : Math.sin(TAU * t / 2200);
+      f.eyes = [eye(0, 0, 1, o.unlimited ? 0.65 : 0.93, -3), eye(0, 0, 1, o.unlimited ? 0.65 : 1, 3)];
+      f.mouth = mouth(o.unlimited ? 48 : 34, o.unlimited ? 20 : 11);
+      gaze(f, o.look, { x: 16, y: 10 });
+      f.prop = { name: 'budget', lift, unlimited: o.unlimited };
+      return f;
+    },
+  },
   // ── States ──
   idle: {
     motion: 'still', blinks: true, tracks: true,
@@ -596,6 +626,7 @@ function poseOptions(opts) {
     count: intIn(o.count, 1, 3, 1),
     mode: o.mode === 'remember' ? 'remember' : 'recall',
     ticks: intIn(o.ticks, 0, 3, 1),
+    unlimited: !!o.unlimited,
     still: !!o.still,
   };
 }
@@ -739,6 +770,23 @@ export function reactionFrame(frame, name, p) {
 // ── Props: small, currentColor, in the face's pill geometry ──
 
 const PROPS = {
+  project: {
+    markup: () => '<g fill="none" stroke="currentColor" stroke-opacity=".7" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="M208 117V84q0-4 4-4h15l7 8h25v29z"/><path class="syna-folder-front" d="M208 117l5-23h49l-5 23z"/><path class="syna-folder-paper" d="M223 93V85h22v8M229 89h10"/></g>',
+    refs: g => ({ front: g.querySelector('.syna-folder-front'), paper: g.querySelector('.syna-folder-paper') }),
+    update(r, p, put) {
+      put(r.front, 'transform', `translate(0,${n(2 * p.peek)})`);
+      put(r.paper, 'transform', `translate(0,${n(-4 * p.peek)})`);
+    },
+  },
+  budget: {
+    markup: () => '<g fill="none" stroke="currentColor" stroke-opacity=".7" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><rect x="216" y="96" width="46" height="25" rx="4"/><path d="M250 103h12v10h-12z"/><g class="syna-budget-coin"><circle cx="236" cy="80" r="12"/><path d="M236 73v14M232 76h6q4 0 0 4h-4q-4 4 0 4h6"/></g><path class="syna-budget-infinity" d="M235 80c-16-19-25 15-8 7l17-14c17-8 8 26-9 7"/></g>',
+    refs: g => ({ coin: g.querySelector('.syna-budget-coin'), infinity: g.querySelector('.syna-budget-infinity') }),
+    update(r, p, put) {
+      put(r.coin, 'display', p.unlimited ? 'none' : null);
+      put(r.infinity, 'display', p.unlimited ? null : 'none');
+      put(p.unlimited ? r.infinity : r.coin, 'transform', `translate(0,${n(-3 * p.lift)})`);
+    },
+  },
   shell: { // three keycaps and a block caret under the chin
     markup: () => [0, 1, 2].map(i => `<rect class="syna-key" x="${100 + i * 24}" y="127" width="20" height="9" rx="4.5" fill="currentColor" fill-opacity=".4"/>`).join('')
       + '<rect class="syna-caret" x="174" y="125" width="7" height="12" rx="2" fill="currentColor" fill-opacity=".75"/>',
@@ -994,26 +1042,15 @@ export function paintMascot(svg, frame) {
   painter.paint(frame);
 }
 
-// ── Shared runtime: one observer, one motion listener, one lead ──
+// ── Shared runtime: one observer and one motion listener for every rig ──
+// Nothing here picks a rig: each one decides from its own state (active, on
+// screen, motion allowed) whether it moves.
 
 const rigs = new Set();
-let leadRig = null;
-let promoteSeq = 0;
 let stopMotionWatch = null;
 let io = null;
 const ioRigs = new WeakMap();
 
-/** Only one rig plays a pose loop: the most recently posed one that wants to. */
-function elect() {
-  let best = null;
-  for (const rig of rigs) if (rig.wantsLead() && (!best || rig.promotedAt() > best.promotedAt())) best = rig;
-  if (best === leadRig) return;
-  const prev = leadRig;
-  leadRig = best;
-  prev?.leadChanged();
-  best?.leadChanged();
-}
-
 function observe(el, rig) {
   if (typeof IntersectionObserver !== 'function') return;
   try {
@@ -1034,13 +1071,11 @@ function register(rig) {
   rigs.add(rig);
   stopMotionWatch ||= onReducedMotionChange(() => {
     for (const r of Array.from(rigs)) r.motionChanged();
-    elect();
   });
 }
 
 function unregister(rig) {
   rigs.delete(rig);
-  if (leadRig === rig) { leadRig = null; elect(); }
   if (!rigs.size && stopMotionWatch) { stopMotionWatch(); stopMotionWatch = null; }
 }
 
@@ -1088,14 +1123,12 @@ export function createMascot(container, options) {
   let active = startActive !== false;
   let visible = true;
   let seenConnected = svg.isConnected;
-  let promotedAt = (promoteSeq += 1);
   let clock = 0; // rig time in ms: the ticker's dt while drawing, real time while still
   let frozenAt = tickerNow(); // while not drawing: when the clock was last brought up to date; -1 while drawing
   let pose = { name: 'idle', raw: {}, start: 0, then: null };
   let settled = false; // a one-shot's opts.then has fired
   let blend = null; // { from, start, dur }
   let lastFrame = null; // the last frame before blinks and reactions
-  let drawn = false; // has drawn a live frame (a never-drawn rig has nothing to blend from)
   let look = { x: 0, y: 0 }; // eased gaze
   let track = { x: 0, y: 0 }; // idle: where the cursor (or look()) points
   let hostLook = { x: 0, y: 0 };
@@ -1119,10 +1152,10 @@ export function createMascot(container, options) {
 
   const def = () => POSES[pose.name];
   const animating = () => !destroyed && active && visible && !isReducedMotion();
-  const isLead = () => leadRig === rig;
   const poseTime = () => clock - pose.start;
 
-  function wantsLead() {
+  /** This pose moves on its own right now: a loop, a patient pose, a one-shot still playing. */
+  function playing() {
     if (!animating()) return false;
     const { motion, settle } = def();
     if (motion === 'loop' || motion === 'blink') return true;
@@ -1186,7 +1219,6 @@ export function createMascot(container, options) {
   function nextRate() {
     if (!animating()) return 0;
     if (blend || blinkStart >= 0 || reactions.length || aim || easing() || miniPopping()) return 60;
-    if (!isLead()) return 0;
     const d = def();
     const t = poseTime();
     if (d.motion === 'loop') return 30;
@@ -1208,9 +1240,9 @@ export function createMascot(container, options) {
     const d = def();
     const at0 = tickerNow();
     let at = Infinity;
-    if (d.blinks && (d.motion === 'still' || isLead())) at = Math.min(at, nextBlinkAt);
+    if (d.blinks) at = Math.min(at, nextBlinkAt);
     if (d.tracks) at = Math.min(at, nextGlanceAt, nextFidgetAt, glance ? glance.until : Infinity);
-    if (d.motion === 'blink' && isLead()) at = Math.min(at, at0 + d.idleFor(poseTime()));
+    if (d.motion === 'blink') at = Math.min(at, at0 + d.idleFor(poseTime()));
     if (d.motion === 'once' && pose.then && !settled) at = Math.min(at, at0 + Math.max(0, d.settle + (d.hold || 0) - poseTime()));
     if (!Number.isFinite(at)) return;
     wakeTimer = setTimeout(() => {
@@ -1243,15 +1275,15 @@ export function createMascot(container, options) {
   function handleDue() {
     const d = def();
     const t = tickerNow();
-    if (d.blinks && (d.motion === 'still' || isLead()) && t >= nextBlinkAt) {
+    if (d.blinks && t >= nextBlinkAt) {
       nextBlinkAt = t + rand(3000, 7000);
       startBlink();
     }
     if (d.tracks) {
       if (glance && t >= glance.until) glance = null;
       if (t >= nextGlanceAt) {
-        // Only while the cursor is still and no other rig is busy.
-        if (t - pointerAt < 2500 || leadRig) nextGlanceAt = t + 3000;
+        // Only while the cursor is still.
+        if (t - pointerAt < 2500) nextGlanceAt = t + 3000;
         else {
           const [x, y] = GLANCES[Math.floor(Math.random() * GLANCES.length)];
           glance = { x, y, until: t + rand(700, 1000) };
@@ -1261,7 +1293,6 @@ export function createMascot(container, options) {
       if (t >= nextFidgetAt) {
         const quietFor = t - Math.max(lastInputAt(), pointerAt);
         if (quietFor < 20000) nextFidgetAt = t + (20000 - quietFor) + rand(0, 5000);
-        else if (leadRig) nextFidgetAt = t + 10000;
         else {
           nextFidgetAt = t + rand(45000, 75000);
           startReaction(Math.random() < 0.5 ? 'hop' : 'wiggle');
@@ -1303,8 +1334,7 @@ export function createMascot(container, options) {
 
   /** The pose frame this rig would draw now, before blends and overlays. */
   function frameNow() {
-    const loopOn = isLead() && def().motion !== 'still';
-    return poseFrame(pose.name, poseTime(), { ...pose.raw, look, range, ticks, still: !loopOn });
+    return poseFrame(pose.name, poseTime(), { ...pose.raw, look, range, ticks, still: !playing() });
   }
 
   /** Ease from what is on screen to what comes next, unless they already match. */
@@ -1400,10 +1430,7 @@ export function createMascot(container, options) {
     handleDue();
     if (aim) { aimAt(aim); aim = null; }
     easeLook(dt);
-    const wasLead = isLead();
     painter.paint(compose());
-    drawn = true;
-    if (wasLead && def().motion === 'once' && poseTime() >= def().settle) elect();
     const rate = nextRate();
     setRate(rate);
     if (!rate) armWake();
@@ -1497,9 +1524,7 @@ export function createMascot(container, options) {
       }
       scheduleIdle();
     }
-    promotedAt = (promoteSeq += 1);
     if (animating()) requestFrames(BLEND_MS);
-    elect();
     refresh();
     return api;
   }
@@ -1537,8 +1562,7 @@ export function createMascot(container, options) {
     const next = !!on;
     if (destroyed || next === active) return api;
     active = next;
-    if (active) { promotedAt = (promoteSeq += 1); revive(); }
-    elect();
+    if (active) revive();
     refresh();
     return api;
   }
@@ -1560,18 +1584,6 @@ export function createMascot(container, options) {
   }
 
   const rig = {
-    promotedAt: () => promotedAt,
-    wantsLead,
-    leadChanged() {
-      if (destroyed) return;
-      // Gaining or losing the loop swaps the still frame for the live one: blend
-      // when they differ (a patient pose between blinks, a settled one-shot: no).
-      if (drawn && animating()) {
-        syncClock();
-        blendIn();
-      }
-      refresh();
-    },
     visibilityChanged(inView) {
       if (destroyed) return;
       if (svg.isConnected) seenConnected = true;
@@ -1579,7 +1591,6 @@ export function createMascot(container, options) {
       const was = visible;
       visible = inView;
       if (visible && !was) revive();
-      elect();
       refresh(); // also wakes a rig that was built before it was attached
     },
     motionChanged() {
@@ -1619,7 +1630,6 @@ export function createMascot(container, options) {
       if (p) aim = p;
     }
   }
-  elect();
   refresh();
   return api;
 }

package/neural-interface/public/shared/tunnel-view.js

@@ -0,0 +1,167 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — the public address: what the cards say
+// ═══════════════════════════════════════════
+//
+// What the two places that start the Cloudflare tunnel show for an answer of
+// GET /api/tunnel/status: the Share menu's Connection block (ui-invite.js) and
+// Settings → Automations → Online access (ui-settings.js). One reading for
+// both, so they never disagree: the state as a word, one sentence about it,
+// the progress of a download, the action that fits, and whether to ask again.
+//
+// No imports and no DOM: `node --test` loads this file as it is
+// (tests/tunnel-view.test.mjs). TUNNEL_COPY is the English of every sentence;
+// `tunnel.*` in i18n/en.json must equal it and i18n/pt-BR.json must have the
+// same keys (the test checks both). The page side is ui-tunnel.js.
+//
+// A server that was started before SynaBun brought its own tunnel program
+// answers without the `cloudflared` part: the cards then work as they did (a
+// tunnel starts when a cloudflared is installed), and where none is, they say
+// that a restart is what is missing. Nothing here ever tells the user to
+// install anything, except on a system Cloudflare publishes no file for.
+
+export const TUNNEL_COPY = Object.freeze({
+  stateOff: 'Off',
+  stateDownloading: 'Getting the tunnel program',
+  stateStarting: 'Starting',
+  stateRunning: 'On',
+  stateFailed: 'Did not start',
+  stateUnsupported: 'Not available',
+  stateRestart: 'Restart needed',
+  idle: 'A public address through Cloudflare, for invite links and remote MCP.',
+  idleDownload: 'A public address through Cloudflare, for invite links and remote MCP. The first start downloads the tunnel program ({size} MB).',
+  downloading: 'Downloading the tunnel program: {received} of {total} MB',
+  starting: 'Waiting for Cloudflare to give an address…',
+  restart: 'Restart SynaBun to use the public address: the server that is running was started before it could download the tunnel program.',
+  unsupported: 'Cloudflare publishes no tunnel program for this system. If you install cloudflared yourself, SynaBun uses it.',
+  errorOffline: 'The tunnel program could not be downloaded: the download server was not reached. Check the connection and try again.',
+  errorHttp: 'The tunnel program could not be downloaded: the download server answered with an error. Try again in a moment.',
+  errorInterrupted: 'The download stopped before it was complete. Nothing was kept. Try again.',
+  errorTimeout: 'The download stalled. Nothing was kept. Try again.',
+  errorChecksum: 'The download was not the file SynaBun expects, so it was removed and never run. Try again; if it happens again, something on the network is changing the file.',
+  errorUnpack: 'The downloaded file could not be unpacked, so it was removed. Try again.',
+  errorDisk: 'The tunnel program could not be saved in SynaBun\'s data folder. Check free space and permissions, then try again.',
+  errorLaunch: 'The tunnel program could not be started on this computer. Try again.',
+  errorExited: 'Cloudflare gave no address. The tunnel program said: {reason}',
+  errorExitedNoReason: 'The tunnel program stopped before Cloudflare gave an address. Try again.',
+  errorNoAddress: 'Cloudflare gave no address in time. Try again.',
+  errorEnded: 'The tunnel stopped. Start it again for a new address.',
+  errorRefused: 'SynaBun refused this request. Start the tunnel from SynaBun on this computer.',
+  errorUnknown: 'The tunnel did not start: {reason}',
+  errorUnknownNoReason: 'The tunnel did not start. Try again.',
+  start: 'Start tunnel',
+  stop: 'Stop',
+  cancel: 'Cancel',
+  retry: 'Try again',
+  copyBundled: 'cloudflared {version}, included with SynaBun',
+  copyDownloaded: 'cloudflared {version}, downloaded by SynaBun',
+  copySystem: 'cloudflared {version}, installed on this computer',
+  copySystemWhy: 'SynaBun could not download its own copy, so the one installed on this computer is used.',
+  mcpKeyNeeded: 'Remote MCP needs an access key. Create one below; the address to connect is then this one followed by /mcp/ and the key.',
+});
+
+const ERROR_COPY = Object.freeze({
+  offline: 'errorOffline', http: 'errorHttp', interrupted: 'errorInterrupted', timeout: 'errorTimeout', checksum: 'errorChecksum',
+  unpack: 'errorUnpack', disk: 'errorDisk', launch: 'errorLaunch', no_address: 'errorNoAddress', ended: 'errorEnded',
+  unsupported: 'unsupported', refused: 'errorRefused',
+});
+
+/** A TUNNEL_COPY sentence with its `{params}` filled in: the translator when the page gives none. */
+export function fillTunnelCopy(key, params = {}) {
+  return String(TUNNEL_COPY[key] ?? key).replace(/\{(\w+)\}/g, (whole, name) => (params[name] != null ? params[name] : whole));
+}
+
+const megabytes = (bytes) => Math.max(0, Number(bytes) || 0) / (1024 * 1024);
+
+/**
+ * What a card shows for a status.
+ *
+ * @param {object | null} status the answer of GET /api/tunnel/status (or of the start / stop that came last)
+ * @param {object} [o]
+ * @param {(key: string, params?: object) => string} [o.t] a key of TUNNEL_COPY → the sentence in the page's language
+ * @param {(value: number, digits: number) => string} [o.number] a number as the page's language writes it
+ * @returns {{
+ *   kind: 'restart' | 'unsupported' | 'idle' | 'downloading' | 'starting' | 'running' | 'failed',
+ *   tone: 'off' | 'busy' | 'ok' | 'warn' | 'err',
+ *   on: boolean,
+ *   label: string, detail: string,
+ *   progress: { percent: number, text: string } | null,
+ *   url: string | null,
+ *   action: 'start' | 'stop' | 'cancel' | 'retry' | null, actionLabel: string,
+ *   copy: string, copyNote: string,
+ *   poll: boolean,
+ * }}
+ *   `on`: the switch stands on (something runs or is on its way). `action`: what a press does ("cancel" and
+ *   "stop" are both POST /api/tunnel/stop; "start" and "retry" both POST /api/tunnel/start). `copy`: which
+ *   cloudflared runs, when one does. `poll`: the state will change by itself, ask again.
+ */
+export function tunnelView(status, { t = fillTunnelCopy, number = (value, digits) => value.toFixed(digits) } = {}) {
+  const s = status && typeof status === 'object' ? status : {};
+  const tool = s.cloudflared && typeof s.cloudflared === 'object' ? s.cloudflared : null;
+  const view = {
+    kind: 'idle', tone: 'off', on: false, label: t('stateOff'), detail: t('idle'), progress: null,
+    url: typeof s.url === 'string' && s.url ? s.url : null,
+    action: 'start', actionLabel: t('start'), copy: '', copyNote: '', poll: false,
+  };
+  const as = (kind, tone, labelKey, detail, action) => Object.assign(view, {
+    kind, tone, label: t(labelKey), detail, action, actionLabel: action ? t(action) : '',
+    on: kind === 'downloading' || kind === 'starting' || kind === 'running', poll: kind === 'downloading' || kind === 'starting',
+  });
+  const running = () => {
+    as('running', 'ok', 'stateRunning', view.url, 'stop');
+    const source = { bundled: 'copyBundled', downloaded: 'copyDownloaded', system: 'copySystem' }[tool?.source];
+    if (source && tool.version) {
+      view.copy = t(source, { version: tool.version });
+      if (tool.source === 'system' && tool.fallback && tool.fallback.code !== 'unsupported') view.copyNote = t('copySystemWhy');
+    }
+    return view;
+  };
+
+  // Nothing is known yet (the answer has not arrived): the card as it stands before a first start.
+  if (!status || typeof status !== 'object') return view;
+
+  // A server from before the tunnel program came with SynaBun: no `cloudflared` part in its answer.
+  if (!tool) {
+    if (view.url) return running();
+    if (s.starting || s.running) return as('starting', 'busy', 'stateStarting', t('starting'), 'cancel');
+    if (s.available) return as('idle', 'off', 'stateOff', t('idle'), 'start');
+    return as('restart', 'warn', 'stateRestart', t('restart'), null);
+  }
+
+  const state = typeof s.state === 'string' ? s.state : 'idle';
+  if (state === 'running' && view.url) return running();
+  if (state === 'downloading') {
+    const total = Number(tool.progress?.total) || Number(tool.download?.size) || 0;
+    const received = Math.min(Number(tool.progress?.received) || 0, total || Infinity);
+    const percent = total ? Math.max(0, Math.min(100, Math.floor((received / total) * 100))) : 0;
+    as('downloading', 'busy', 'stateDownloading', t('downloading', { received: number(megabytes(received), 1), total: number(megabytes(total), 1) }), 'cancel');
+    view.progress = { percent, text: `${percent}%` };
+    return view;
+  }
+  if (state === 'starting' || state === 'running') return as('starting', 'busy', 'stateStarting', t('starting'), 'cancel');
+  if (state === 'failed') {
+    const error = s.error && typeof s.error === 'object' ? s.error : {};
+    if (error.code === 'unsupported') return as('unsupported', 'off', 'stateUnsupported', t('unsupported'), null);
+    const reason = typeof error.reason === 'string' && error.reason.trim() ? error.reason.trim() : '';
+    let detail;
+    if (error.code === 'exited') detail = reason ? t('errorExited', { reason }) : t('errorExitedNoReason');
+    else if (ERROR_COPY[error.code]) detail = t(ERROR_COPY[error.code]);
+    else detail = typeof error.message === 'string' && error.message.trim() ? t('errorUnknown', { reason: error.message.trim() }) : t('errorUnknownNoReason');
+    return as('failed', 'err', 'stateFailed', detail, 'retry');
+  }
+  // idle
+  if (tool.state === 'unsupported') return as('unsupported', 'off', 'stateUnsupported', t('unsupported'), null);
+  if (tool.state === 'ready') return as('idle', 'off', 'stateOff', t('idle'), 'start');
+  const size = Number(tool.download?.size) || 0;
+  return as('idle', 'off', 'stateOff', size ? t('idleDownload', { size: number(megabytes(size), 0) }) : t('idle'), 'start');
+}
+
+/**
+ * The address an assistant outside connects to, or null while there is none to give: the public address
+ * followed by /mcp/ and the access key. Without a key there is no such address: the server refuses /mcp from
+ * outside (lib/request-gate.js mcpWithoutKey), so the cards offer nothing to copy and say what is missing.
+ */
+export function remoteMcpAddress(url, key) {
+  const base = typeof url === 'string' ? url.trim().replace(/\/+$/, '') : '';
+  const secret = typeof key === 'string' ? key.trim() : '';
+  return base && secret ? `${base}/mcp/${secret}` : null;
+}