synabun 2.0.0-beta → 2.0.5

package/neural-interface/public/shared/start-bridge.js

@@ -0,0 +1,802 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Start Server bridge (page side)
+// A page cannot ask a server that is down to start itself. It hands the
+// operating system a synabun://start link instead; the launcher registered
+// for that link (lib/start-launcher.js) starts the server, and the page
+// watches for it. DOM-free and dependency-free.
+//
+// The page also cannot ask a stopped server how its start is going. The
+// launcher says so itself, on a loopback beacon (port + 10000) that lives only
+// while a launch does. Everything the page shows about a start comes from one
+// of three things: its own clock, what that beacon reported (each step with
+// the time it happened), and its own probe of the server. Nothing is guessed:
+// no percentages, and no step is named before the launch reported it.
+//
+// A restart the user asked for is shown by the same bridge (`restart()`): the
+// screen is drawn in the click, and what it says comes from the same three
+// things, plus the server's own word that it is shutting down. The supervisor
+// that brings the server back reports on the same beacon (`reason: 'restart'`).
+//
+// offline.html is shown when nothing can be fetched, so the server pastes this
+// file into it (lib/offline-page.js drops the `export` keywords). Keep every
+// export a plain `export function` / `export const` at the start of a line,
+// and never import anything here.
+// ═══════════════════════════════════════════
+
+export const START_LINK = 'synabun://start';
+
+// What the page remembers from the last time the server answered.
+export const START_STORAGE = {
+  projectDir: 'synabun-project-dir',
+  install: 'synabun-install-kind',       // 'npm' | 'git' | 'app' (a packaged application)
+  launcher: 'synabun-start-launcher',    // 'registered' | 'stale' | 'missing' | 'skipped'
+  entry: 'synabun-start-entry',          // a packaged application's entry executable
+};
+
+export const START_LIMITS = {
+  pollMs: 300,           // while a start is under way: is the server up, what does the launch say
+  idlePollMs: 3000,      // while nothing was asked for
+  hintAfterMs: 4000,     // nothing from the launcher yet: say what to look for
+  stallAfterMs: 60000,   // still nothing from anyone: offer the button and the command again
+  quietAfterMs: 15000,   // the launch has reported nothing new for this long: say so
+  lostAfterMs: 3000,     // a launch that was reporting went silent: stop repeating what it said
+  idleBeaconChecks: 2,   // on load, look for a start already under way (a reload in the middle of one)
+  reloadDelayMs: 150,    // the "it is up" frame before the page reloads
+  restartGraceMs: 15000, // a restart was asked and the server neither went away nor said it is going: stop waiting
+  beaconTimeoutMs: 1200,
+};
+
+export const START_BEACON_PATH = '/synabun-start-status';
+export const START_BEACON_VERSION = 1;
+
+export function isWindowsPlatform(nav) {
+  const platform = String(nav?.userAgentData?.platform || nav?.platform || '');
+  return /win/i.test(platform) || /Windows/i.test(String(nav?.userAgent || ''));
+}
+
+export function isMacPlatform(nav) {
+  const platform = String(nav?.userAgentData?.platform || nav?.platform || '');
+  return /mac/i.test(platform);
+}
+
+/**
+ * How to hand the link to the OS. Firefox replaces the page with an error when
+ * a top-level navigation has no handler, so it gets a hidden frame; every
+ * other engine asks the user from the top frame and ignores an unknown link.
+ */
+export function startLinkMode(userAgent) {
+  return /\bFirefox\//.test(String(userAgent || '')) ? 'frame' : 'top';
+}
+
+/**
+ * Hand START_LINK to the OS. Call it from the click itself: browsers only ask
+ * "open SynaBun?" for a navigation the user started.
+ */
+export function openStartLink({ document: doc, location: loc, userAgent } = {}) {
+  if (startLinkMode(userAgent) === 'frame') {
+    const frame = doc.createElement('iframe');
+    frame.style.display = 'none';
+    frame.src = START_LINK;
+    doc.body.appendChild(frame);
+    const tidy = setTimeout(() => { try { frame.remove(); } catch {} }, 5000);
+    if (typeof tidy === 'object') tidy?.unref?.(); // only outside a browser
+    return 'frame';
+  }
+  loc.href = START_LINK;
+  return 'top';
+}
+
+/** A path as one argument, in whatever shell the platform's terminal runs. */
+export function quoteShellPath(path, windows) {
+  const value = String(path || '');
+  // cmd.exe and PowerShell both take a double-quoted path; a Windows path cannot contain a quote.
+  if (windows) return `"${value}"`;
+  if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) return value;
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * How a packaged application is started by hand: its entry executable with
+ * `start`. A path that needs no quotes reads the same in every shell. One that
+ * does goes through `cmd /c` on Windows, because PowerShell does not run a
+ * quoted path by itself and cmd.exe does not know PowerShell's `&`.
+ */
+export function packagedStartCommand(entry) {
+  const value = String(entry || '');
+  if (/^[A-Za-z]:[\\/]|^\\\\/.test(value)) {
+    const path = value.replace(/\//g, '\\');
+    return /^[A-Za-z0-9_.:\\-]+$/.test(path) ? `${path} start` : `cmd /c "${path}" start`;
+  }
+  return `${quoteShellPath(value, false)} start`;
+}
+
+/**
+ * The commands a person can type instead. One line each, no `cd`, no `;` or
+ * `&` between commands: `npm --prefix <dir> start` reads the same in cmd.exe,
+ * PowerShell, bash, zsh and fish.
+ * Returns [{ id: 'npm' | 'git' | 'app', command }] — the one that matches the
+ * install when it is known, both npm and git when it is not. A packaged
+ * application (`install: 'app'`) is started through its `entry` executable.
+ */
+export function manualStartCommands({ projectDir, install, windows, entry } = {}) {
+  if (install === 'app' && entry) return [{ id: 'app', command: packagedStartCommand(entry) }];
+  const npm = { id: 'npm', command: 'synabun' };
+  const git = projectDir ? { id: 'git', command: `npm --prefix ${quoteShellPath(projectDir, windows)} start` } : null;
+  if (install === 'npm') return [npm];
+  if (install === 'git' && git) return [git];
+  return git ? [npm, git] : [npm];
+}
+
+/** Whether the button can work: only a registration known to be absent rules it out. */
+export function startButtonUsable(launcherState) {
+  return launcherState !== 'missing';
+}
+
+// ═══════════════════════════════════════════
+// The launch's own report (the beacon)
+// ═══════════════════════════════════════════
+
+/** The beacon's port for a server port: + 10000, − 10000 past the last port. As lib/start-launcher.js `startBeaconPort`. */
+export function startBeaconPort(port) {
+  const n = Number(port);
+  const p = Number.isInteger(n) && n >= 1 && n <= 65535 ? n : 3344;
+  return p + 10000 <= 65535 ? p + 10000 : p - 10000;
+}
+
+/**
+ * Where this page reads the beacon, or null when it cannot: the launcher runs
+ * on the machine the server runs on, so only a page opened from that machine's
+ * own loopback address (and over plain http, like the beacon) has one to read.
+ * Returns { url, port } with `port` the server's.
+ */
+export function startBeaconTarget(loc) {
+  const host = String(loc?.hostname || '').toLowerCase();
+  if (String(loc?.protocol || '') !== 'http:') return null;
+  if (host !== 'localhost' && host !== '127.0.0.1' && host !== '[::1]' && host !== '::1') return null;
+  const port = Number(loc?.port) || 80;
+  return { port, url: `http://127.0.0.1:${startBeaconPort(port)}${START_BEACON_PATH}` };
+}
+
+const START_LAUNCH_STATES = ['starting', 'started', 'failed', 'gave-up'];
+const START_LAUNCH_STEPS = ['received', 'locked', 'terminal', 'spawned', 'exited'];
+const START_SUPERVISOR_PHASES = ['checking', 'dependencies', 'browser', 'build', 'snapshot', 'server', 'listening', 'failed'];
+
+function startCleanError(error) {
+  if (!error || typeof error !== 'object') return null;
+  const exitCode = Number(error.exitCode);
+  return {
+    code: String(error.code || '').slice(0, 40),
+    message: String(error.message || '').slice(0, 300),
+    exitCode: Number.isInteger(exitCode) ? exitCode : null,
+  };
+}
+
+/**
+ * Read one beacon answer. Returns the launch as this page may show it, or
+ * null: not a beacon, another server's, or the end of a launch this page has
+ * nothing to do with (a failure still being reported from before the click).
+ * A launch that is still under way is this server's start whoever asked.
+ *   askedAt — when this page handed the link over (null: it did not)
+ *   following — the launch id this page is already showing
+ *   past — launch ids this page has moved on from (a retry was clicked)
+ */
+export function readStartBeacon(data, { port, askedAt = null, following = null, past = [] } = {}) {
+  if (!data || typeof data !== 'object' || data.synabun !== 'start-beacon' || data.v !== START_BEACON_VERSION) return null;
+  if (Number(data.port) !== Number(port)) return null;
+  if (!START_LAUNCH_STATES.includes(data.state)) return null;
+  const id = String(data.launchId || '');
+  const startedAt = Number(data.startedAt) || 0;
+  if (!id || !startedAt) return null;
+  if (data.state !== 'starting') {
+    if (past.includes(id)) return null;
+    const mine = id === following || (askedAt !== null && startedAt >= askedAt - 2000);
+    if (!mine) return null;
+  }
+
+  const steps = [];
+  for (const step of Array.isArray(data.steps) ? data.steps : []) {
+    const at = Number(step?.at);
+    if (START_LAUNCH_STEPS.includes(step?.id) && Number.isFinite(at)) steps.push({ id: step.id, at });
+  }
+  let supervisor = null;
+  const sup = data.supervisor;
+  if (sup && typeof sup === 'object' && START_SUPERVISOR_PHASES.includes(sup.phase)) {
+    const detail = sup.detail && typeof sup.detail === 'object' ? sup.detail : {};
+    const number = (value) => (Number.isFinite(Number(value)) && value !== null ? Number(value) : null);
+    supervisor = {
+      phase: sup.phase,
+      at: Number(sup.at) || 0,
+      startedAt: Number(sup.startedAt) || 0,
+      phases: (Array.isArray(sup.phases) ? sup.phases : [])
+        .filter(p => START_SUPERVISOR_PHASES.includes(p?.phase) && Number.isFinite(Number(p?.at)))
+        .map(p => ({ phase: p.phase, at: Number(p.at) })),
+      detail: {
+        name: typeof detail.name === 'string' ? detail.name.slice(0, 80) : '',
+        step: typeof detail.step === 'string' ? detail.step.slice(0, 40) : '',
+        files: number(detail.files),
+        bytes: number(detail.bytes),
+      },
+      error: startCleanError(sup.error),
+    };
+  }
+  const last = steps[steps.length - 1] || { id: 'received', at: startedAt };
+  const newest = Math.max(last.at, supervisor ? supervisor.at : 0, startedAt);
+  return {
+    id,
+    // 'restart': a supervisor bringing its server back, not a launcher starting one.
+    reason: data.reason === 'restart' ? 'restart' : 'start',
+    state: data.state,
+    startedAt,
+    step: last.id,
+    steps,
+    supervisor,
+    error: startCleanError(data.error) || (supervisor && supervisor.error) || null,
+    log: typeof data.log === 'string' ? data.log.slice(0, 400) : '',
+    // On the launcher's own clock: how long since it last saw something happen.
+    quietMs: Math.max(0, (Number(data.now) || newest) - newest),
+  };
+}
+
+/** Fetch the beacon once: its JSON, or null when nothing is there to answer. */
+export function fetchStartBeacon(target, { fetchImpl, timeoutMs = START_LIMITS.beaconTimeoutMs } = {}) {
+  const doFetch = fetchImpl || (typeof fetch === 'function' ? fetch : null);
+  if (!target || !doFetch) return Promise.resolve(null);
+  const options = { cache: 'no-store', credentials: 'omit', mode: 'cors' };
+  try {
+    if (typeof AbortSignal !== 'undefined' && typeof AbortSignal.timeout === 'function') options.signal = AbortSignal.timeout(timeoutMs);
+  } catch {}
+  return Promise.resolve()
+    .then(() => doFetch(target.url, options))
+    .then(res => (res && res.ok ? res.json() : null))
+    .catch(() => null);
+}
+
+// ═══════════════════════════════════════════
+// The button's life
+// ═══════════════════════════════════════════
+
+/**
+ * idle → launching → starting | waiting → stalled | failed, or online at any
+ * point. The page keeps probing in every state, so a server started by hand is
+ * noticed just the same.
+ *   probe()    → Promise<boolean | { up, boot, stopping }>   is the server
+ *                answering? `boot` names the server that answered and
+ *                `stopping` is its own word that it is shutting down for a
+ *                restart; a server that says neither is just `true`.
+ *   launch()   → hand START_LINK to the OS
+ *   beacon()   → Promise<object|null>  the launch's raw report (optional)
+ *   port       → the server's port (what a beacon must be about)
+ *   onState(state, detail)   on every change of state
+ *   onUpdate(snapshot)       whenever what there is to show changed: the
+ *                            state, what the launch reported, or the second
+ *
+ * States:
+ *   'idle'       nothing asked
+ *   'launching'  the link was handed to the OS; nothing has confirmed it
+ *   'starting'   the launcher itself reports a start under way (evidence)
+ *   'waiting'    hintAfterMs with no word from the launcher
+ *   'stalled'    stallAfterMs with no word, or the launcher gave up waiting
+ *   'failed'     the launcher reports that the start failed, and why
+ *   'online'     the server answers this page
+ *
+ * A restart (`restart()`) adds two:
+ *   'restarting' the server was asked to restart, or said it is restarting;
+ *                it has not come back and no supervisor reports on it yet
+ *   'refused'    the restart did not happen and the server still answers
+ * While one is under way `snapshot().restart` says what is known of it, and
+ * 'online' means a server other than the one that was asked answers.
+ */
+export function createStartBridge({
+  probe,
+  launch,
+  beacon = null,
+  port = 0,
+  onState = () => {},
+  onUpdate = () => {},
+  limits = START_LIMITS,
+  now = () => Date.now(),
+  setTimer = (fn, ms) => setTimeout(fn, ms),
+  clearTimer = (id) => clearTimeout(id),
+} = {}) {
+  const lim = { ...START_LIMITS, ...limits };
+  let state = 'idle';
+  let askedAt = null;   // when this page handed the link over (null: it has not)
+  let since = null;     // what the elapsed time counts from
+  let clicks = 0;
+  let timer = null;
+  let stopped = false;
+  let probing = false;
+  let launchInfo = null; // the launch as last reported
+  let launchSeenAt = 0;
+  let idleChecks = 0;
+  let shown = '';
+  // The restart under way, on this page's clock: when it was asked for (or
+  // this page was told), when the server said it is restarting, when it first
+  // did not answer, and the server that is being replaced.
+  let restart = null;
+  const past = [];
+
+  const busy = () => state === 'launching' || state === 'starting' || state === 'waiting' || state === 'restarting';
+
+  function snapshot() {
+    return {
+      state,
+      clicks,
+      askedAt,
+      since,
+      elapsedMs: since === null ? 0 : Math.max(0, now() - since),
+      launch: launchInfo,
+      restart: restart ? {
+        asked: restart.asked,
+        askedAt: restart.askedAt,
+        acceptedAt: restart.acceptedAt,
+        downAt: restart.downAt,
+        refused: restart.refused,
+      } : null,
+    };
+  }
+
+  function update() {
+    const snap = snapshot();
+    const l = snap.launch;
+    const r = snap.restart;
+    const key = [
+      snap.state, snap.clicks, busy() ? Math.floor(snap.elapsedMs / 1000) : '',
+      l ? [l.id, l.state, l.step, l.supervisor?.phase, l.supervisor?.detail?.step, l.supervisor?.detail?.files, l.quietMs >= lim.quietAfterMs, l.error?.message].join('|') : '',
+      r ? [r.acceptedAt !== null, r.downAt !== null, r.refused?.code].join('|') : '',
+    ].join('/');
+    if (key === shown) return;
+    shown = key;
+    try { onUpdate(snap); } catch {}
+  }
+
+  function set(next, detail = {}) {
+    if (state === next) return;
+    state = next;
+    try { onState(state, { clicks, ...detail }); } catch {}
+  }
+
+  function schedule(delay) {
+    if (stopped || state === 'online' || state === 'refused') return;
+    if (timer) clearTimer(timer);
+    timer = setTimer(tick, delay ?? (busy() ? lim.pollMs : lim.idlePollMs));
+  }
+
+  /** One probe answer as { up, boot, stopping }; a bare `true` is a server that says nothing about itself. */
+  function readProbe(value) {
+    if (value === true) return { up: true, boot: '', stopping: false };
+    if (value && typeof value === 'object' && value.up === true) {
+      return { up: true, boot: typeof value.boot === 'string' ? value.boot : '', stopping: value.stopping === true };
+    }
+    return { up: false, boot: '', stopping: false };
+  }
+
+  /** The restart did not happen and the server is still there: say why and stop. */
+  function refuse(why) {
+    restart.refused = why;
+    set('refused');
+  }
+
+  /**
+   * During a restart an answer is not yet the server being back: the one that
+   * was asked keeps answering while it shuts down. True only when the server
+   * that answers is another one. A server that names itself (`boot`) settles
+   * it; one that does not (an older server) is believed once it was seen gone.
+   */
+  function judgeRestart(seen) {
+    const r = restart;
+    if (!seen.up) {
+      if (r.downAt === null) r.downAt = now();
+      return false;
+    }
+    if (seen.stopping) {
+      // Its own word: it is the one being replaced, and it is on its way out.
+      if (r.acceptedAt === null) r.acceptedAt = now();
+      if (!r.boot && seen.boot) r.boot = seen.boot;
+      r.downAt = null; // an answer it missed was not it stopping
+      return false;
+    }
+    const named = !!r.boot && !!seen.boot;
+    if (named && seen.boot !== r.boot) return true;
+    if (!named && r.downAt !== null) return true;
+    // The same server (or one that cannot be told apart), not shutting down.
+    if (named) r.downAt = null;
+    if (r.pending) return false; // the request is still on its way
+    if (r.rejected) { refuse(r.rejected); return false; }
+    if (r.unanswered) { refuse({ code: 'unreachable', status: 0, message: '' }); return false; }
+    if (r.acceptedAt !== null && now() - r.acceptedAt >= lim.restartGraceMs) {
+      if (named) { refuse({ code: 'still-running', status: 0, message: '' }); return false; }
+      return true; // it tells nothing about itself: load it again and see
+    }
+    return false;
+  }
+
+  /** What the launch says, when there is one to listen to right now. */
+  async function listen() {
+    if (!beacon) return;
+    // A restart: nobody is starting anything while the old server still answers.
+    if (restart && restart.downAt === null) return;
+    // Idle: only just after load, for a start that was already under way.
+    if (state === 'idle' && idleChecks >= lim.idleBeaconChecks) return;
+    if (state === 'idle') idleChecks++;
+    // Failed: the launcher said how it ended, there is no more to hear. Stalled
+    // keeps listening: a prompt answered a minute late still starts a launch.
+    if (state === 'failed') return;
+    let raw = null;
+    try { raw = await beacon(); } catch {}
+    if (stopped || state === 'online') return;
+    const read = readStartBeacon(raw, { port, askedAt, following: launchInfo?.id || null, past });
+    if (read) {
+      launchInfo = read;
+      launchSeenAt = now();
+      if (since === null) since = read.startedAt; // a start this page did not ask for: count from its own beginning
+      if (read.state === 'failed') set('failed');
+      else if (read.state === 'gave-up') set('stalled');
+      else set('starting');
+      return;
+    }
+    // It was reporting and stopped: a launcher that ended without this page
+    // reading how. What it said last is no longer known to be true.
+    if (state === 'starting' && now() - launchSeenAt >= lim.lostAfterMs) {
+      launchInfo = null;
+      if (restart) set('restarting'); // back to what this page sees for itself
+      else if (askedAt === null) { since = null; set('idle'); } // a start this page never asked for: back to watching
+      else set(now() - askedAt >= lim.hintAfterMs ? 'waiting' : 'launching');
+    }
+  }
+
+  async function tick() {
+    timer = null;
+    if (stopped || probing) return;
+    probing = true;
+    let seen = readProbe(false);
+    try { seen = readProbe(await probe()); } catch {}
+    let up = seen.up && !seen.stopping; // a server on its way out is not one to connect to
+    if (restart && !stopped && state !== 'refused') up = judgeRestart(seen);
+    if (!up && !stopped && state !== 'refused') await listen();
+    probing = false;
+    if (stopped) return;
+    if (up) { set('online'); update(); return; }
+    if (state === 'refused') { update(); return; }
+    if (state === 'launching' || state === 'waiting') {
+      const waited = now() - askedAt;
+      if (waited >= lim.stallAfterMs) set('stalled');
+      else if (waited >= lim.hintAfterMs) set('waiting');
+    }
+    // Gone, and nobody reports bringing it back: the button and the command return.
+    if (state === 'restarting' && restart.downAt !== null && now() - restart.downAt >= lim.stallAfterMs) set('stalled');
+    update();
+    schedule();
+  }
+
+  return {
+    get state() { return state; },
+    snapshot,
+    /** Begin watching for the server (call once the page is up). */
+    watch() { schedule(0); },
+    /** The click. Ignored while a start is already under way. */
+    start() {
+      if (stopped || state === 'online' || state === 'refused' || busy()) return false;
+      clicks++;
+      askedAt = now();
+      since = askedAt;
+      // What the last try reported is over: a launcher still saying so is not this one.
+      if (launchInfo && !past.includes(launchInfo.id)) past.push(launchInfo.id);
+      launchInfo = null;
+      restart = null; // a restart that did not bring it back is over: this is a start
+      state = 'idle'; // a second try after 'stalled' announces 'launching' again
+      set('launching');
+      update();
+      try { launch(); } catch {}
+      schedule();
+      return true;
+    },
+    /**
+     * A restart of the server. Call it from the click itself: the first
+     * snapshot is handed to onUpdate before anything is asked of the network.
+     *   request()  → Promise<{ ok, boot, status, message }>  the asking (this
+     *                page's own click); leave it out when the page is only told
+     *   announced  → the server itself said it is restarting (`boot`: which one)
+     * A request that fails counts as refused only once the server is seen to
+     * be still there. Returns false when a restart is already being shown; an
+     * announcement then still counts as the server's word.
+     */
+    restart({ request = null, announced = false, boot = '' } = {}) {
+      if (stopped || state === 'online') return false;
+      if (restart) {
+        if (announced && !restart.refused) {
+          if (restart.acceptedAt === null) restart.acceptedAt = now();
+          if (!restart.boot && boot) restart.boot = String(boot);
+          update();
+        }
+        return false;
+      }
+      if (typeof request !== 'function' && !announced) return false;
+      askedAt = now();
+      since = askedAt;
+      if (launchInfo && !past.includes(launchInfo.id)) past.push(launchInfo.id);
+      launchInfo = null;
+      const mine = restart = {
+        asked: typeof request === 'function',
+        askedAt,
+        acceptedAt: announced ? askedAt : null,
+        downAt: null,
+        boot: announced && boot ? String(boot) : '',
+        pending: typeof request === 'function',
+        rejected: null,
+        unanswered: false,
+        refused: null,
+      };
+      state = 'idle';
+      set('restarting');
+      update();
+      if (mine.asked) {
+        Promise.resolve().then(() => request()).then((answer) => {
+          if (stopped || restart !== mine) return;
+          mine.pending = false;
+          if (answer && answer.ok === true) {
+            if (mine.acceptedAt === null) mine.acceptedAt = now();
+            if (answer.boot) mine.boot = String(answer.boot);
+          } else {
+            mine.rejected = { code: 'refused', status: Number(answer?.status) || 0, message: String(answer?.message || '').slice(0, 200) };
+          }
+          update();
+          schedule(0); // look at once: a refusal is only one when the server still answers
+        }, () => {
+          if (stopped || restart !== mine) return;
+          mine.pending = false;
+          mine.unanswered = true;
+          schedule(0);
+        });
+      }
+      schedule();
+      return true;
+    },
+    stop() {
+      stopped = true;
+      if (timer) clearTimer(timer);
+      timer = null;
+    },
+  };
+}
+
+// ═══════════════════════════════════════════
+// What to show
+// ═══════════════════════════════════════════
+
+// The sentences, in English. The offline page uses them as they are; the app
+// reads the same keys from its dictionary (`loading.start.<key>` in
+// i18n/*.json, kept equal to these by tests/start-bridge.test.mjs).
+export const START_COPY = {
+  asked: 'Asked your system to start SynaBun. If your browser shows a prompt, choose Open.',
+  unconfirmedMac: 'No word from the launcher yet. If your browser is asking for permission, choose Open: a Terminal window then opens with the server.',
+  unconfirmedWindows: 'No word from the launcher yet. If your browser is asking for permission, choose Open: a console window then opens with the server.',
+  unconfirmedLinux: 'No word from the launcher yet. If your browser is asking for permission, choose Open: the server then starts in the background.',
+  stalled: 'Nothing has answered. If no prompt or window appeared, run the command below once: it also repairs this button.',
+  launcherRunning: 'The launcher is running.',
+  terminalOpened: 'A Terminal window was opened for the server.',
+  terminalQuiet: 'A Terminal window was opened {seconds} s ago, but the server has not started in it. Look at that window.',
+  processStarted: 'The server\'s supervisor was started.',
+  checking: 'Checking the install.',
+  dependencies: 'Installing dependencies with npm. A first start, or the first after an update, takes a few minutes.',
+  browser: 'Downloading the automation browser. This happens once.',
+  build: 'Building the MCP server.',
+  snapshot: 'Backing up your data before the first start of this version.',
+  snapshotSized: 'Backing up your data before the first start of this version: {files} files, {megabytes} MB.',
+  server: 'The server process is running. Waiting for it to answer.',
+  listening: 'The server is listening. Connecting.',
+  answered: 'The server answered the launcher. Connecting.',
+  quiet: 'Nothing new from the start for {seconds} s.',
+  failed: 'The start failed: {reason}',
+  failedHint: 'Run the command below to see the full output, or try again.',
+  failedLog: 'Launcher log: {path}',
+  gaveUp: 'The server was started but has not answered. Check its window, or run the command below.',
+  online: 'The server is up. Loading SynaBun.',
+  trailLauncher: 'Launcher started',
+  trailTerminal: 'Terminal opened',
+  trailProcess: 'Supervisor started',
+  trailSupervisor: 'Supervisor running',
+  trailServer: 'Server process started',
+  trailListening: 'Server listening',
+  elapsedLabel: 'Time since Start was pressed',
+  headingStarting: 'Starting the server',
+  headingReady: 'Server is up',
+  headingFailed: 'The server did not start',
+  // A restart: each sentence is said only once the page holds what it says.
+  restartAsked: 'Asked the server to restart.',
+  restartStopping: 'The server accepted the restart and is shutting down.',
+  restartSlowStop: 'Still shutting down after {seconds} s.',
+  restartDown: 'The server stopped answering. Waiting for it to come back.',
+  restartRespawning: 'The supervisor is starting the server again.',
+  restartStalled: 'The server has not come back. Start it with the button, or run the command below.',
+  restartRefused: 'The server did not accept the restart: {reason}',
+  restartUnreachable: 'The server did not answer the restart request.',
+  restartStillRunning: 'The server accepted the restart but did not shut down.',
+  trailAccepted: 'Restart accepted',
+  trailNoAnswer: 'Server stopped answering',
+  trailStopped: 'Server process exited',
+  restartElapsedLabel: 'Time since the restart began',
+  headingRestarting: 'Restarting the server',
+  headingRestartFailed: 'The server did not restart',
+};
+
+/** `{name}` placeholders, like the app's t(). */
+export function formatStartText(template, params) {
+  return String(template ?? '').replace(/\{(\w+)\}/g, (all, key) => (params && params[key] != null ? String(params[key]) : all));
+}
+
+/** 7 s · 1 min 05 s. Whole seconds: the page's own clock, nothing finer is claimed. */
+export function formatStartElapsed(ms) {
+  const total = Math.max(0, Math.floor((Number(ms) || 0) / 1000));
+  if (total < 60) return `${total} s`;
+  return `${Math.floor(total / 60)} min ${String(total % 60).padStart(2, '0')} s`;
+}
+
+/** 0.4 s for a step's own time: these come with milliseconds. */
+function startStepSeconds(ms) {
+  const value = Math.max(0, Number(ms) || 0) / 1000;
+  return value < 10 ? `${value.toFixed(1)} s` : `${Math.round(value)} s`;
+}
+
+/**
+ * Everything a surface renders for one snapshot, as data:
+ *   reason    'start' | 'restart'      what is under way: a start, or a restart of a server that was up
+ *   mascot    'asleep' | 'waking' | 'working' | 'ready' | 'failed' | 'stalled'
+ *   busy      the button is disabled (a start is under way)
+ *   button    'start' | 'starting' | 'retry' | 'none' (a restart: nothing to press) | 'back' (it was refused)
+ *   heading   key | null               the title when it is not the surface's own for this mascot
+ *   headline  { key, params } | null   the status sentence (the live region)
+ *   hint      { key, params } | null   a second, quieter sentence
+ *   elapsed   '12 s' | ''              the page's clock since the click
+ *   elapsedLabel  key                  what that clock counts from
+ *   trail     [{ key, time }]          what was reported, with when
+ *   error     { message, log } | null
+ * A headline names a step only when the snapshot holds the report of it.
+ */
+export function startStatusView(snap, { platform = 'linux', limits = START_LIMITS } = {}) {
+  const state = snap?.state || 'idle';
+  const launchOf = snap?.launch || null;
+  const sup = launchOf?.supervisor || null;
+  // A restart this page asked for or was told of; or one it only reads the report of.
+  const restart = snap?.restart || null;
+  const restartReport = launchOf?.reason === 'restart';
+  const view = {
+    state,
+    reason: restart || restartReport ? 'restart' : 'start',
+    mascot: 'asleep',
+    busy: state === 'launching' || state === 'starting' || state === 'waiting' || state === 'restarting',
+    button: 'start',
+    heading: null,
+    headline: null,
+    hint: null,
+    elapsed: '',
+    elapsedLabel: restart || restartReport ? 'restartElapsedLabel' : 'elapsedLabel',
+    trail: [],
+    error: null,
+  };
+  if (view.busy) {
+    view.button = restart ? 'none' : 'starting';
+    view.elapsed = formatStartElapsed(snap.elapsedMs);
+    if (view.reason === 'restart') view.heading = 'headingRestarting';
+  }
+
+  // The reported steps, each at the time it was reported for, counted from the
+  // click (or from the launch's own start when another page asked for it).
+  const firstPhase = (phase) => (sup ? sup.phases.find(p => p.phase === phase)?.at || (sup.phase === phase ? sup.at : 0) : 0);
+  if (restart) {
+    // A restart this page follows from its beginning: what the server said to
+    // it, what its own probe saw, then what the supervisor reports.
+    const add = (key, at) => { if (at !== null && at !== undefined) view.trail.push({ key, time: startStepSeconds(at - restart.askedAt) }); };
+    add('trailAccepted', restart.acceptedAt);
+    const exited = launchOf ? launchOf.steps.find(step => step.id === 'exited')?.at : undefined;
+    if (exited !== undefined) add('trailStopped', exited);
+    else add('trailNoAnswer', restart.downAt);
+    add('trailServer', firstPhase('server') || null);
+    add('trailListening', firstPhase('listening') || null);
+  } else if (launchOf) {
+    const asked = snap.askedAt !== null && snap.askedAt !== undefined && launchOf.startedAt >= snap.askedAt - 2000;
+    const zero = asked ? snap.askedAt : launchOf.startedAt;
+    const add = (key, at) => { if (at) view.trail.push({ key, time: startStepSeconds(at - zero) }); };
+    if (!restartReport) add('trailLauncher', launchOf.startedAt); // a restart has no launcher
+    for (const step of launchOf.steps) {
+      if (step.id === 'terminal') add('trailTerminal', step.at);
+      if (step.id === 'spawned') add('trailProcess', step.at);
+      if (step.id === 'exited') add('trailStopped', step.at);
+    }
+    if (sup) {
+      // The supervisor of a restart was usually there long before it: listed only when it began with it.
+      if (!restartReport || sup.startedAt >= launchOf.startedAt - 2000) add('trailSupervisor', sup.startedAt);
+      add('trailServer', firstPhase('server'));
+      add('trailListening', firstPhase('listening'));
+    }
+  }
+
+  if (state === 'online') {
+    view.mascot = 'ready';
+    view.headline = { key: 'online', params: {} };
+    return view;
+  }
+  if (state === 'launching') {
+    view.mascot = 'waking';
+    view.headline = { key: 'asked', params: {} };
+    return view;
+  }
+  if (state === 'waiting') {
+    view.mascot = 'waking';
+    view.headline = { key: platform === 'mac' ? 'unconfirmedMac' : platform === 'windows' ? 'unconfirmedWindows' : 'unconfirmedLinux', params: {} };
+    return view;
+  }
+  if (state === 'stalled') {
+    view.mascot = 'stalled';
+    view.headline = launchOf?.state === 'gave-up' ? { key: 'gaveUp', params: {} }
+      : restart ? { key: 'restartStalled', params: {} } : { key: 'stalled', params: {} };
+    return view;
+  }
+  if (state === 'refused') {
+    // The server is still there: nothing to start, only the way back to the app.
+    const why = restart?.refused || {};
+    view.mascot = 'failed';
+    view.button = 'back';
+    view.heading = 'headingRestartFailed';
+    view.headline = why.code === 'unreachable' ? { key: 'restartUnreachable', params: {} }
+      : why.code === 'still-running' ? { key: 'restartStillRunning', params: {} }
+        : { key: 'restartRefused', params: { reason: why.message || `HTTP ${why.status || 0}` } };
+    return view;
+  }
+  if (state === 'restarting' && restart) {
+    if (restart.downAt !== null) {
+      view.mascot = 'working';
+      view.headline = { key: 'restartDown', params: {} };
+    } else if (restart.acceptedAt !== null) {
+      view.mascot = 'working';
+      view.headline = { key: 'restartStopping', params: {} };
+      const stoppingMs = snap.elapsedMs - (restart.acceptedAt - restart.askedAt);
+      if (stoppingMs >= limits.quietAfterMs) view.hint = { key: 'restartSlowStop', params: { seconds: Math.floor(stoppingMs / 1000) } };
+    } else {
+      view.mascot = 'waking';
+      view.headline = { key: 'restartAsked', params: {} };
+    }
+    return view;
+  }
+  if (state === 'failed') {
+    view.mascot = 'failed';
+    view.button = 'retry';
+    const reason = launchOf?.error?.message || '';
+    view.headline = { key: 'failed', params: { reason } };
+    view.hint = { key: 'failedHint', params: {} };
+    view.error = { message: reason, log: launchOf?.log || '' };
+    return view;
+  }
+  if (state === 'starting' && launchOf) {
+    view.mascot = 'working';
+    const quiet = Math.floor(launchOf.quietMs / 1000);
+    const isQuiet = launchOf.quietMs >= limits.quietAfterMs;
+    if (launchOf.state === 'started') {
+      view.headline = { key: 'answered', params: {} };
+    } else if (sup && sup.phase !== 'failed') {
+      const megabytes = sup.detail.bytes !== null ? Math.round(sup.detail.bytes / 1048576) : null;
+      if (sup.phase === 'snapshot' && sup.detail.files !== null && megabytes !== null) {
+        view.headline = { key: 'snapshotSized', params: { files: sup.detail.files, megabytes } };
+      } else {
+        view.headline = { key: sup.phase, params: {} };
+      }
+      // Slow on purpose (an install, a download, a backup): silence there is expected.
+      const slow = ['dependencies', 'browser', 'build', 'snapshot'].includes(sup.phase);
+      if (isQuiet && !slow) view.hint = { key: 'quiet', params: { seconds: quiet } };
+    } else if (restartReport) {
+      // The supervisor opened this report to bring the server back; it has named no step yet.
+      view.headline = { key: 'restartRespawning', params: {} };
+      if (isQuiet) view.hint = { key: 'quiet', params: { seconds: quiet } };
+    } else if (launchOf.step === 'terminal') {
+      view.headline = isQuiet ? { key: 'terminalQuiet', params: { seconds: quiet } } : { key: 'terminalOpened', params: {} };
+    } else if (launchOf.step === 'spawned') {
+      view.headline = { key: 'processStarted', params: {} };
+      if (isQuiet) view.hint = { key: 'quiet', params: { seconds: quiet } };
+    } else {
+      view.headline = { key: 'launcherRunning', params: {} };
+      if (isQuiet) view.hint = { key: 'quiet', params: { seconds: quiet } };
+    }
+    return view;
+  }
+  return view;
+}