synabun 2.0.0 → 2.0.7

package/neural-interface/public/shared/file-links.js

@@ -0,0 +1,339 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — File links in agent messages: the decisions
+// ═══════════════════════════════════════════
+//
+// A link in an agent's message can point at a file on this computer: a path,
+// a `file:` URL, with or without a place in the file (`:line[:column]`,
+// `#Lline[Ccolumn]`). This module reads such a target and says which paths to
+// try, and decides what a click on one does. ui-file-links.js gives that
+// decision the page (the bus, the server, the toast). The four side panels
+// share both.
+//
+// The text is a model's: nothing here trusts it. A target only ever becomes a
+// path handed to /api/file-content, which keeps its own checks.
+// No imports and no `document`: the click handler only touches the event and
+// the link it is handed. Loaded by `node --test` as it is, and by the Markdown
+// sanitiser.
+
+/** The English of `fileLinks.*` in i18n/en.json (a test keeps them equal). */
+export const FILE_LINK_COPY = Object.freeze({
+  open: 'Open in editor',
+  openAtLine: 'Open in editor at line {line}',
+  openAtLineColumn: 'Open in editor at line {line}, column {column}',
+  missing: '{name} was not found, or it is a folder.',
+  notText: '{name} is not a text file the editor can open.',
+  tooLarge: '{name} is too large to open in the editor.',
+  outside: '{name} is outside your registered projects. Add its folder as a project to open it here.',
+  failed: 'Could not reach SynaBun to open {name}. Check that the server is running.',
+});
+
+/** Longer than any path: a target past this is not read at all. */
+export const MAX_TARGET_LENGTH = 2048;
+
+const DRIVE_RE = /^[a-z]:[\\/]/i;
+const SCHEME_RE = /^([a-z][a-z0-9+.-]*):/i;
+// `name.ext:12` and `name.ext:12:3` read as a scheme to a URL parser; they are a file and a place in it.
+const PLACE_ONLY_RE = /^\d+(?::\d+)?(?:#.*)?$/;
+const LINE_SUFFIX_RE = /:(\d+)(?::(\d+))?$/;
+const LINE_HASH_RE = /^#L(\d+)(?:C(\d+))?(?:-L?\d+(?:C\d+)?)?$/i;
+
+const slashes = (path) => String(path ?? '').replace(/\\/g, '/');
+
+/** How a target reads: a `path`, a `file` URL, a `web` address (http, https), or null for anything else. */
+function kindOf(value) {
+  if (!value || value.length > MAX_TARGET_LENGTH) return null;
+  if (value.startsWith('#') || value.startsWith('?') || value.startsWith('//')) return null;
+  if (DRIVE_RE.test(value)) return 'path';
+  const scheme = SCHEME_RE.exec(value);
+  if (!scheme) return 'path';
+  const name = scheme[1].toLowerCase();
+  if (name === 'file') return 'file';
+  if (name === 'http' || name === 'https') return 'web';
+  const rest = value.slice(scheme[0].length);
+  if (rest.startsWith('//')) return null;
+  return PLACE_ONLY_RE.test(rest) ? 'path' : null;
+}
+
+/**
+ * A link target as written, when it reads as a file on this computer rather than an address.
+ * The Markdown sanitiser keeps it beside the link (`data-file-target`): the `href` it writes is resolved
+ * against the page, which loses a relative path, `~`, a `file:` URL and `name.ext:12`.
+ * @param {string} raw the `href` an agent wrote
+ * @returns {string | null}
+ */
+export function localFileHref(raw) {
+  const value = String(raw ?? '').trim();
+  const kind = kindOf(value);
+  return kind === 'path' || kind === 'file' ? value : null;
+}
+
+/** A path with `.`, `..` and doubled slashes resolved, and no slash at its end. */
+export function normalizeFilePath(path) {
+  const value = slashes(path);
+  const drive = /^[a-z]:/i.exec(value)?.[0] || '';
+  const rest = value.slice(drive.length);
+  const rooted = rest.startsWith('/');
+  const parts = [];
+  for (const part of rest.split('/')) {
+    if (!part || part === '.') continue;
+    if (part === '..') { if (parts.length && parts[parts.length - 1] !== '..') parts.pop(); else if (!rooted) parts.push('..'); continue; }
+    parts.push(part);
+  }
+  return `${drive}${rooted ? '/' : ''}${parts.join('/')}`;
+}
+
+const isAbsolute = (path) => path.startsWith('/') || DRIVE_RE.test(path);
+
+function decoded(text) {
+  try { return decodeURIComponent(text); } catch { return text; }
+}
+
+/**
+ * Read a link target.
+ * @param {string} raw the target as written (an `href`, or the text of a path a panel made clickable)
+ * @param {{ cwd?: string, home?: string, origin?: string }} [where] `cwd`: the working directory of the tab or
+ *   session the message belongs to (a relative path is resolved against it); `home`: the user's home folder
+ *   (for `~`); `origin`: the page's own origin (an address on it is read as the path it holds, which is how a
+ *   link sanitised before `data-file-target` existed looks)
+ * @returns {{ path: string, candidates: string[], line: number | null, column: number | null,
+ *   needsHome: boolean, sameOrigin: boolean } | null} null when the target is not a file's. `candidates` are
+ *   the paths to try, in order; `path` is the first. `needsHome`: the target starts with `~` and no home was
+ *   given, so there is nothing to try yet. `sameOrigin`: the target was an address of this app.
+ */
+export function parseFileLinkTarget(raw, { cwd = '', home = '', origin = '' } = {}) {
+  const value = String(raw ?? '').trim();
+  const kind = kindOf(value);
+  if (!kind) return null;
+
+  let written;
+  let hash = '';
+  let sameOrigin = false;
+  if (kind === 'path') {
+    const at = value.indexOf('#');
+    written = at < 0 ? value : value.slice(0, at);
+    hash = at < 0 ? '' : value.slice(at);
+  } else {
+    let url;
+    try { url = new URL(value); } catch { return null; }
+    if (kind === 'web') {
+      if (!origin || url.origin !== origin) return null;
+      sameOrigin = true;
+    } else if (url.host && url.host !== 'localhost') {
+      return null; // a file on another machine
+    }
+    written = url.pathname;
+    hash = url.hash;
+  }
+
+  // An agent may have escaped the path (a link with a space in it has to be); it may also hold a real "%".
+  const spellings = kind === 'path' ? [...new Set([decoded(written), written])] : [decoded(written)];
+  // A working directory that is not a whole path would be read from the server's own folder: it is not used.
+  const root = isAbsolute(slashes(cwd)) ? normalizeFilePath(cwd) : '';
+  const candidates = [];
+  let line = null;
+  let column = null;
+  let needsHome = false;
+  for (const spelling of spellings) {
+    let path = slashes(spelling);
+    const place = LINE_SUFFIX_RE.exec(path);
+    if (place) {
+      line ??= Number(place[1]) || null;
+      column ??= Number(place[2]) || null;
+      path = path.slice(0, place.index);
+    }
+    if (/^\/[a-z]:\//i.test(path)) path = path.slice(1); // file:///C:/…
+    if (path === '~' || path.startsWith('~/')) {
+      if (!home) { needsHome = true; continue; }
+      path = `${slashes(home).replace(/\/+$/, '')}${path.slice(1)}`;
+    }
+    if (!path) continue;
+    if (isAbsolute(path)) {
+      candidates.push(normalizeFilePath(path));
+      // The sanitiser used to turn `src/a.js` into `<origin>/src/a.js`: the same link, read from its project.
+      if (sameOrigin && root) candidates.push(normalizeFilePath(`${root}/${path}`));
+    } else if (root) {
+      candidates.push(normalizeFilePath(`${root}/${path}`));
+    }
+  }
+
+  const place = LINE_HASH_RE.exec(hash);
+  if (place) {
+    line = Number(place[1]) || line;
+    column = Number(place[2]) || (Number(place[1]) ? null : column);
+  }
+
+  const unique = [...new Set(candidates.filter((path) => path && path !== '/'))];
+  if (!unique.length && !needsHome) return null;
+  return { path: unique[0] || '', candidates: unique, line, column, needsHome: needsHome && !unique.length, sameOrigin };
+}
+
+/** Whether `path` is one of `roots` or inside one. */
+export function isInsideRoots(path, roots = []) {
+  const target = normalizeFilePath(path);
+  if (!isAbsolute(target)) return false;
+  for (const root of roots) {
+    const base = root ? normalizeFilePath(root) : '';
+    if (!base || !isAbsolute(base)) continue;
+    if (target === base || target.startsWith(base.endsWith('/') ? base : `${base}/`)) return true;
+  }
+  return false;
+}
+
+/** The last part of a path: the name a notice uses. */
+export function fileLinkName(path) {
+  const value = slashes(path).replace(/\/+$/, '');
+  return value.slice(value.lastIndexOf('/') + 1) || value;
+}
+
+/** A path as a panel copies it: without the place in the file. */
+export function withoutPlace(text) {
+  return String(text ?? '').trim().replace(/:\d+(?::\d+)?$/, '');
+}
+
+/**
+ * The tooltip of a link the editor may open.
+ * @param {{ line?: number | null, column?: number | null }} target from parseFileLinkTarget()
+ * @returns {{ key: 'open' | 'openAtLine' | 'openAtLineColumn', params: object }}
+ */
+export function fileLinkTitle(target) {
+  if (!target?.line) return { key: 'open', params: {} };
+  return target.column
+    ? { key: 'openAtLineColumn', params: { line: target.line, column: target.column } }
+    : { key: 'openAtLine', params: { line: target.line } };
+}
+
+/**
+ * What `GET /api/file-content` said about a path: the editor's own answer to "can this be opened".
+ * @param {{ status: number }} answer
+ * @returns {{ ok: true } | { ok: false, reason: 'missing' | 'notText' | 'tooLarge' | 'outside' | 'failed' }}
+ */
+export function describeProbe({ status } = {}) {
+  if (status === 200) return { ok: true };
+  if (status === 415) return { ok: false, reason: 'notText' };
+  if (status === 413) return { ok: false, reason: 'tooLarge' };
+  if (status === 403) return { ok: false, reason: 'outside' };
+  if (status === 400 || status === 404) return { ok: false, reason: 'missing' };
+  return { ok: false, reason: 'failed' };
+}
+
+// A file that is there but cannot be edited says more than one that is not there at all.
+const TELLING = ['failed', 'outside', 'missing', 'tooLarge', 'notText'];
+
+/** Of two reasons a path was not opened, the one worth telling the user. */
+export function moreTelling(a, b) {
+  return TELLING.indexOf(b) > TELLING.indexOf(a) ? b : a;
+}
+
+/** A `FILE_LINK_COPY` sentence with its `{params}` filled in. */
+export function fillFileLinkCopy(key, params = {}) {
+  return String(FILE_LINK_COPY[key] ?? key).replace(/\{(\w+)\}/g, (whole, name) => (params[name] != null ? params[name] : whole));
+}
+
+// ── The click ──
+
+/**
+ * What a link points at, as the agent wrote it.
+ * @param {Element} anchor
+ * @param {{ textLinks?: string }} [options] `textLinks`: the selector of the panel's own path links, the ones
+ *   it makes out of a path in plain text (their text is the target, their `href` is "#")
+ * @returns {{ raw: string, text: boolean } | null}
+ */
+export function readFileLink(anchor, { textLinks = '' } = {}) {
+  const kept = anchor.getAttribute('data-file-target');
+  if (kept) return { raw: kept, text: false };
+  const href = anchor.getAttribute('href');
+  if (textLinks && anchor.matches(textLinks) && (!href || href === '#')) return { raw: anchor.textContent || '', text: true };
+  return href ? { raw: href, text: false } : null;
+}
+
+/**
+ * The click and hover handlers of the links in a panel's messages.
+ * @param {object} page what the handlers need from the page
+ * @param {(event: string, data: object) => void} page.emit the bus (`open-file-editor`)
+ * @param {(path: string) => Promise<number>} page.probe the status GET /api/file-content answers for a path
+ * @param {() => Promise<string>} page.home the user's home folder ('' when it cannot be told)
+ * @param {() => string} page.origin the page's origin
+ * @param {(key: string, params?: object) => string} page.say a `fileLinks.*` sentence
+ * @param {(message: string) => void} page.notify shows a short message
+ * @param {(anchor: Element) => void} page.follow goes where a link of this app leads, as the browser would
+ */
+export function createFileLinkHandlers(page) {
+  const whereOf = (anchor, options) => {
+    let cwd = '';
+    try { cwd = options.cwd?.(anchor) || ''; } catch { cwd = ''; }
+    return { cwd, origin: page.origin() };
+  };
+
+  async function openOrFallBack(anchor, link, where, target, options) {
+    let found = target;
+    if (found.needsHome) found = parseFileLinkTarget(link.raw, { ...where, home: await page.home() });
+
+    let reason = null;
+    for (const path of found?.candidates || []) {
+      let answer;
+      try { answer = describeProbe({ status: await page.probe(path) }); } catch { answer = { ok: false, reason: 'failed' }; }
+      if (answer.ok) {
+        page.emit('open-file-editor', { filePath: path, line: found.line || undefined, column: found.column || undefined });
+        return 'opened';
+      }
+      reason = reason ? moreTelling(reason, answer.reason) : answer.reason;
+    }
+    reason ||= 'missing'; // nothing to try: `~` with no home folder to read it from
+
+    // Not a file the editor opens. The link keeps what it did before, or the reason is said.
+    if (link.text && typeof options.copyPath === 'function') {
+      try { await options.copyPath(anchor, withoutPlace(link.raw)); return 'copied'; } catch { /* could not copy: say why it did not open */ }
+    }
+    if (target.sameOrigin) { page.follow(anchor); return 'followed'; }
+    (options.notify || page.notify)(page.say(reason, { name: fileLinkName(found?.path || withoutPlace(link.raw)) }));
+    return reason;
+  }
+
+  /**
+   * Take a click on a link in an agent's message when the link points at a file.
+   * @param {MouseEvent} event
+   * @param {object} [options]
+   * @param {Element} [options.within] only links inside this element are taken
+   * @param {(anchor: Element) => string} [options.cwd] the working directory of the tab or session the link's
+   *   message belongs to: a relative path is a path in it
+   * @param {string} [options.textLinks] selector of the panel's own path links (see readFileLink)
+   * @param {(anchor: Element, path: string) => any} [options.copyPath] what a click on one of those did
+   *   before: it runs when the path is not a file the editor opens
+   * @param {(message: string) => void} [options.notify] shows the reason a link was not opened
+   * @returns {Promise<string> | null} null when the click is not this handler's (the browser follows the
+   *   link as before); else the click is taken and the promise says how it ended: 'opened', 'copied',
+   *   'followed', or the reason the user was told
+   */
+  function handleClick(event, options = {}) {
+    if (event.defaultPrevented || event.button > 0) return null;
+    const anchor = event.target?.closest?.('a');
+    if (!anchor || (options.within && !options.within.contains(anchor))) return null;
+    if (anchor.hasAttribute?.('download')) return null; // a file the app itself offers
+    const link = readFileLink(anchor, options);
+    if (!link) return null;
+    const where = whereOf(anchor, options);
+    const target = parseFileLinkTarget(link.raw, where);
+    if (!target) {
+      if (!link.text || typeof options.copyPath !== 'function') return null;
+      event.preventDefault();
+      try { options.copyPath(anchor, withoutPlace(link.raw)); } catch { /* nothing to copy to */ }
+      return Promise.resolve('copied');
+    }
+    event.preventDefault();
+    return openOrFallBack(anchor, link, where, target, options);
+  }
+
+  /** A link the editor may open says so when it is pointed at, unless it already says something. */
+  function label(event, options = {}) {
+    const anchor = event.target?.closest?.('a');
+    if (!anchor || anchor.title || (options.within && !options.within.contains(anchor))) return;
+    const link = readFileLink(anchor, options);
+    if (!link || link.text) return;
+    const target = parseFileLinkTarget(link.raw, whereOf(anchor, options));
+    if (!target || target.sameOrigin) return;
+    const { key, params } = fileLinkTitle(target);
+    anchor.title = page.say(key, params);
+  }
+
+  return { handleClick, label };
+}

package/neural-interface/public/shared/git-bash-view.js

@@ -0,0 +1,145 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Git Bash for Claude Code: what Settings says
+// ═══════════════════════════════════════════
+//
+// Settings → AI connections → Executable paths has a row for the Git Bash
+// that every Claude Code started by SynaBun gets on Windows (the server's
+// lib/git-bash/, GET /api/cli/git-bash): the one on the PC, SynaBun's own copy
+// of Git for Windows (installed with the app, or downloaded on an npm
+// install), its download while it runs, why it failed, and the button that
+// tries again. This module reads an answer of the server into what the row
+// shows; ui-git-bash.js draws it.
+//
+// No imports and no DOM: `node --test` loads this file as it is
+// (tests/git-bash-view.test.mjs). GIT_BASH_COPY is the English of every
+// sentence; `gitBash.*` in i18n/en.json must equal it and i18n/pt-BR.json must
+// have the same keys.
+//
+// macOS and Linux have nothing to show (Claude Code runs the system's shell
+// there): the row stays hidden, as it does for a server from before this,
+// which has no such route.
+
+export const GIT_BASH_COPY = Object.freeze({
+  label: 'Git Bash for Claude Code (Windows)',
+  help: 'Claude Code on Windows runs its Bash tool and its hooks in Git Bash. SynaBun uses the Git for Windows of this PC, or its own copy when the PC has none.',
+  badgeSystem: 'On this PC',
+  badgeReady: 'SynaBun\'s copy',
+  badgeMissing: 'Not found',
+  badgeDownloading: 'Downloading',
+  badgeFailed: 'Not installed',
+  badgeOff: 'Off',
+  sourceEnv: 'CLAUDE_CODE_GIT_BASH_PATH names {path}.',
+  sourceSettings: 'Your Claude Code settings name {path}.',
+  sourceSystem: 'Git for Windows on this PC: {path}',
+  sourceSystemPassed: 'Git for Windows on this PC: {path}. Claude Code would not find it by itself, so SynaBun names it.',
+  sourceBundled: 'Git for Windows {version}, installed with SynaBun: {path}',
+  sourceDownloaded: 'Git for Windows {version}, downloaded by SynaBun: {path}',
+  missing: 'No Git Bash on this PC. SynaBun downloads its own copy of Git for Windows {version} ({size} MB) and checks it against its published SHA-256.',
+  stepDownload: 'Downloading Git for Windows {version}: {done} of {total} MB',
+  stepExtract: 'Unpacking Git for Windows {version}: {percent}%',
+  stepVerify: 'Checking every file against the pinned release…',
+  stepPlace: 'Putting it in place…',
+  failed: 'Git for Windows could not be put in place. {reason}',
+  off: 'Turned off: SYNABUN_GIT_BASH=off is set, so SynaBun downloads nothing and names no Git Bash.',
+  unsupported: 'No Git for Windows release is pinned for this processor. Install Git for Windows from git-scm.com.',
+  settingsNamed: 'A claude you start in another terminal uses it too: your Claude Code settings name it.',
+  settingsKept: 'Your Claude Code settings name a Git Bash that is not there ({value}). SynaBun left that value as it is.',
+  settingsError: 'Your Claude Code settings could not be updated: {message}',
+  download: 'Download',
+  retry: 'Try again',
+  recheck: 'Re-check',
+  checking: 'Checking…',
+  errorOffline: 'The download server could not be reached. Check the connection and try again.',
+  errorHttp: 'The download server answered with an error. Try again in a moment.',
+  errorInterrupted: 'The download stopped before it was complete. Nothing was kept.',
+  errorTimeout: 'Nothing arrived from the download server for too long.',
+  errorChecksum: 'What arrived is not the published release, so it was removed and never run.',
+  errorUnpack: 'The download could not be unpacked, so it was removed.',
+  errorDisk: 'The files could not be written. Check free space (about 550 MB) and permissions.',
+  errorCancelled: 'The download was stopped.',
+  errorUnknown: 'The download did not finish.',
+  errorRequest: 'SynaBun did not answer: {message}',
+});
+
+const ERROR_COPY = Object.freeze({
+  offline: 'errorOffline', http: 'errorHttp', interrupted: 'errorInterrupted', timeout: 'errorTimeout',
+  checksum: 'errorChecksum', unpack: 'errorUnpack', disk: 'errorDisk', cancelled: 'errorCancelled',
+});
+
+const STEP_COPY = Object.freeze({ download: 'stepDownload', extract: 'stepExtract', verify: 'stepVerify', place: 'stepPlace' });
+
+/** A GIT_BASH_COPY sentence with its `{params}` filled in: the translator when the page gives none. */
+export function fillGitBashCopy(key, params = {}) {
+  return String(GIT_BASH_COPY[key] ?? key).replace(/\{(\w+)\}/g, (whole, name) => (params[name] != null ? params[name] : whole));
+}
+
+let _translate = null;
+
+/** The page's translator: `(key, params) => t('gitBash.' + key, params)`; an empty answer or the key itself falls back to the English. */
+export function setGitBashTranslator(fn) {
+  _translate = typeof fn === 'function' ? fn : null;
+}
+
+/** A sentence in the page's language. */
+export function gitBashText(key, params = {}) {
+  if (_translate) {
+    try {
+      const text = _translate(key, params);
+      if (typeof text === 'string' && text && text !== key && text !== `gitBash.${key}`) return text;
+    } catch { /* the English below */ }
+  }
+  return fillGitBashCopy(key, params);
+}
+
+/** Whole megabytes (the release file is about a hundred of them). */
+const mb = (bytes) => String(Number(bytes) > 0 ? Math.round(Number(bytes) / 1024 / 1024) : 0);
+
+/** What the user's settings note adds to a row that shows SynaBun's copy in use, or null. */
+function settingsNote(status) {
+  const result = status.settings;
+  if (!result || typeof result !== 'object') return null;
+  if (status.state === 'ready' && (result.state === 'written' || result.state === 'unchanged') && result.value === status.path) return gitBashText('settingsNamed');
+  if (result.state === 'kept-user-value' && result.value) return gitBashText('settingsKept', { value: result.value });
+  if (result.state === 'error') return gitBashText('settingsError', { message: result.message || '' });
+  return null;
+}
+
+/**
+ * The row for one answer of GET /api/cli/git-bash.
+ * @returns {{ visible: boolean, badge: { text: string, tone: 'detected' | 'not-found' | 'custom' | null } | null,
+ *   line: string, note: string | null, action: 'download' | 'retry' | null, busy: boolean, recheck: boolean }}
+ */
+export function gitBashView(status) {
+  const hidden = { visible: false, badge: null, line: '', note: null, action: null, busy: false, recheck: false };
+  if (!status || typeof status !== 'object' || status.supported !== true) return hidden;
+  const version = status.pinned?.version || '';
+  const path = status.path || '';
+  const row = (badge, tone, line, extra = {}) => ({ ...hidden, visible: true, badge: { text: gitBashText(badge), tone }, line, recheck: true, ...extra });
+  switch (status.state) {
+    case 'off':
+      return row('badgeOff', null, gitBashText('off'), { recheck: false });
+    case 'unsupported':
+      return row('badgeMissing', 'not-found', gitBashText('unsupported'));
+    case 'system': {
+      const key = status.source === 'env' ? 'sourceEnv' : status.source === 'settings' ? 'sourceSettings' : status.passToClaude ? 'sourceSystemPassed' : 'sourceSystem';
+      return row('badgeSystem', 'detected', gitBashText(key, { path }), { note: settingsNote(status) });
+    }
+    case 'ready':
+      return row('badgeReady', 'detected', gitBashText(status.source === 'bundled' ? 'sourceBundled' : 'sourceDownloaded', { version, path }), { note: settingsNote(status) });
+    case 'missing':
+      return row('badgeMissing', 'not-found', gitBashText('missing', { version, size: mb(status.pinned?.size) }), { action: 'download' });
+    case 'downloading': {
+      const step = STEP_COPY[status.step] || 'stepDownload';
+      const progress = status.progress || {};
+      const params = { version, done: mb(progress.done), total: mb(progress.total || status.pinned?.size), percent: Number(progress.percent) || 0 };
+      return row('badgeDownloading', 'custom', gitBashText(step, params), { busy: true, recheck: false });
+    }
+    case 'failed': {
+      const code = status.error?.code;
+      const reason = ERROR_COPY[code] ? gitBashText(ERROR_COPY[code]) : (status.error?.message || gitBashText('errorUnknown'));
+      return row('badgeFailed', 'not-found', gitBashText('failed', { reason }), { action: 'retry', note: settingsNote(status) });
+    }
+    default:
+      return hidden;
+  }
+}

package/neural-interface/public/shared/greeting/greeting-card.js

@@ -0,0 +1,178 @@
+// ═══════════════════════════════════════════
+// SynaBun — Greeting: the card every surface mounts
+// ═══════════════════════════════════════════
+//
+// One renderer for the greeting: the Assistant and the Claude Code, Codex and
+// OpenCode panels mount it inside the empty state they already have, Settings
+// shows the same card as its preview. greeting-view.js decides the words; this
+// file asks the server (`POST /api/greeting/open`) and draws.
+//
+// Everything is text (never markup): a greeting is built from records and may
+// have been written by a model. A server older than this page (404) or an
+// engine that did not start (503) simply shows nothing, and is asked again a
+// minute later at the earliest.
+
+import { greetingView, readGreetingResponse } from './greeting-view.js';
+
+const STYLE_ID = 'sb-greet-styles';
+const OPEN_URL = '/api/greeting/open';
+const RETRY_MS = 60_000;
+const TIMEOUT_MS = 4000;
+
+// The app's own tokens (styles.css), so the card reads like the panel it sits in; a panel with
+// tokens of its own maps them here.
+const STYLES = `
+.sb-greet { --sbg-text: var(--t-bright, rgba(255,255,255,0.9)); --sbg-2: var(--t-secondary, rgba(255,255,255,0.5)); --sbg-3: var(--t-muted, rgba(255,255,255,0.3)); --sbg-line: var(--b-subtle, rgba(255,255,255,0.06)); --sbg-fill: var(--s-subtle, rgba(255,255,255,0.04));
+  display: flex; flex-direction: column; align-items: center; gap: 4px; width: 100%; max-width: 440px; margin: 6px auto 0; padding: 0 12px; box-sizing: border-box; text-align: center; pointer-events: auto; }
+.asst-empty .sb-greet { --sbg-text: var(--asst-text, var(--t-bright)); --sbg-2: var(--asst-text-2, var(--t-secondary)); --sbg-3: var(--asst-text-3, var(--t-muted)); margin-top: 0; }
+.sb-greet[hidden] { display: none; }
+.sb-greet-when { font-size: 12px; line-height: 1.45; color: var(--sbg-3); }
+.sb-greet-text { margin: 0; font-size: 13px; line-height: 1.5; font-weight: 400; color: var(--sbg-text); overflow-wrap: anywhere; text-wrap: pretty; user-select: text; }
+.sb-greet-more { appearance: none; display: inline-flex; align-items: center; gap: 4px; margin-top: 2px; padding: 2px 6px; border: 0; border-radius: var(--r-small, 6px); background: none; color: var(--sbg-3); font: inherit; font-size: 12px; line-height: 1.45; cursor: pointer; }
+.sb-greet-more:is(:hover, :focus-visible) { color: var(--sbg-2); background: var(--sbg-fill); }
+.sb-greet-more:focus-visible { outline: 1px solid var(--b-visible, rgba(255,255,255,0.22)); outline-offset: 1px; }
+.sb-greet-chev { display: inline-block; transition: transform .12s ease; }
+.sb-greet-more[aria-expanded="true"] .sb-greet-chev { transform: rotate(90deg); }
+.sb-greet-basis { display: flex; flex-direction: column; gap: 4px; width: 100%; box-sizing: border-box; margin-top: 2px; padding: 8px 10px; border: 1px solid var(--sbg-line); border-radius: var(--r-card, 8px); background: var(--sbg-fill); text-align: left; }
+.sb-greet-basis[hidden] { display: none; }
+.sb-greet-row { display: grid; grid-template-columns: minmax(84px, 30%) minmax(0, 1fr) auto; gap: 8px; align-items: baseline; font-size: 12px; line-height: 1.45; }
+.sb-greet-kind { color: var(--sbg-3); }
+.sb-greet-label { color: var(--sbg-2); overflow-wrap: anywhere; user-select: text; }
+.sb-greet-link { appearance: none; padding: 0 2px; border: 0; background: none; color: var(--sbg-3); font-family: var(--ff-mono, ui-monospace, 'JetBrains Mono', monospace); font-size: 11px; text-decoration: underline dotted; text-underline-offset: 2px; cursor: pointer; }
+.sb-greet-link:is(:hover, :focus-visible) { color: var(--sbg-text); }
+.sb-greet-cost { margin-top: 2px; padding-top: 6px; border-top: 1px solid var(--sbg-line); font-size: 12px; line-height: 1.45; color: var(--sbg-3); }
+@media (prefers-reduced-motion: reduce) { .sb-greet-chev { transition: none; } }
+`;
+
+let uid = 0;
+const cache = new Map();   // `${surface}:${session}` → the greeting this conversation opened with (or null)
+let unavailableUntil = 0;  // an older server or an engine that did not start: not asked again before this
+
+/** The card's styles, once per document. */
+export function ensureGreetingStyles(doc = globalThis.document) {
+  if (!doc?.head || doc.getElementById(STYLE_ID)) return;
+  const style = doc.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = STYLES;
+  doc.head.appendChild(style);
+}
+
+function node(doc, tag, className, text) {
+  const el = doc.createElement(tag);
+  if (className) el.className = className;
+  if (text != null) el.textContent = text;
+  return el;
+}
+
+/**
+ * Draw a greeting inside `host` (a panel's empty state), replacing one already there.
+ * → the card element, or null when there is nothing to draw.
+ * opts: { t, now, onOpenMemory(id), open } (`open`: the disclosure starts open, Settings' preview)
+ */
+export function renderGreeting(host, greeting, { t = null, now = Date.now(), onOpenMemory = null, open = false } = {}) {
+  const doc = host?.ownerDocument || globalThis.document;
+  if (!host || !doc) return null;
+  for (const old of host.querySelectorAll(':scope > .sb-greet')) old.remove();
+  const view = greetingView(greeting, { now, t });
+  if (!view) return null;
+  ensureGreetingStyles(doc);
+  const card = node(doc, 'div', 'sb-greet');
+  card.setAttribute('role', 'note');
+  card.setAttribute('aria-label', view.label);
+  if (view.id) card.dataset.greetingId = view.id;
+  if (view.when) card.appendChild(node(doc, 'div', 'sb-greet-when', view.when));
+  card.appendChild(node(doc, 'p', 'sb-greet-text', view.text));
+
+  const basisId = `sb-greet-basis-${++uid}`;
+  const more = node(doc, 'button', 'sb-greet-more');
+  more.type = 'button';
+  more.setAttribute('aria-controls', basisId);
+  more.appendChild(node(doc, 'span', 'sb-greet-more-text', view.toggle));
+  const chev = node(doc, 'span', 'sb-greet-chev', '›');
+  chev.setAttribute('aria-hidden', 'true');
+  more.appendChild(chev);
+  const basis = node(doc, 'div', 'sb-greet-basis');
+  basis.id = basisId;
+  for (const row of view.rows) {
+    const line = node(doc, 'div', 'sb-greet-row');
+    line.dataset.kind = row.kind;
+    line.appendChild(node(doc, 'span', 'sb-greet-kind', row.kindLabel));
+    line.appendChild(node(doc, 'span', 'sb-greet-label', row.label));
+    if (row.id && typeof onOpenMemory === 'function') {
+      const link = node(doc, 'button', 'sb-greet-link', row.id.slice(0, 8));
+      link.type = 'button';
+      link.title = `${row.openLabel} ${row.id}`;
+      link.setAttribute('aria-label', link.title);
+      link.addEventListener('click', (event) => { event.stopPropagation(); try { onOpenMemory(row.id); } catch { /* the host decides */ } });
+      line.appendChild(link);
+    }
+    basis.appendChild(line);
+  }
+  basis.appendChild(node(doc, 'div', 'sb-greet-cost', view.cost));
+  const setOpen = (value) => { more.setAttribute('aria-expanded', value ? 'true' : 'false'); basis.hidden = !value; };
+  more.addEventListener('click', (event) => { event.stopPropagation(); setOpen(more.getAttribute('aria-expanded') !== 'true'); });
+  setOpen(open === true);
+  card.appendChild(more);
+  card.appendChild(basis);
+  host.appendChild(card);
+  return card;
+}
+
+/** Remove the card from a host. */
+export function clearGreeting(host) {
+  if (!host) return;
+  for (const old of host.querySelectorAll(':scope > .sb-greet')) old.remove();
+}
+
+/**
+ * Ask whether this fresh conversation is greeted. One request per conversation: the answer is
+ * kept, so a redraw of the empty state costs nothing. → the greeting, or null.
+ * `session`: the surface's own name for the conversation (the server gives the same one the same answer).
+ */
+export async function fetchGreeting({ surface, cwd = null, project = null, session = null, fetchImpl = globalThis.fetch, now = Date.now } = {}) {
+  if (!surface || typeof fetchImpl !== 'function') return null;
+  const key = session ? `${surface}:${session}` : null;
+  if (key && cache.has(key)) return cache.get(key);
+  if (now() < unavailableUntil) return null;
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timer = controller ? setTimeout(() => controller.abort(), TIMEOUT_MS) : null;
+  try {
+    const response = await fetchImpl(OPEN_URL, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' }, signal: controller?.signal,
+      body: JSON.stringify({ surface, ...(project ? { project } : {}), ...(cwd ? { cwd } : {}), ...(session ? { session } : {}) }),
+    });
+    let body = null;
+    try { body = await response.json(); } catch { body = null; }
+    const answer = readGreetingResponse(response.status, body);
+    if (answer.state === 'old-server' || answer.state === 'failed') { unavailableUntil = now() + RETRY_MS; return null; }
+    if (answer.state === 'unreadable') return null;
+    if (key) { cache.set(key, answer.greeting); while (cache.size > 200) cache.delete(cache.keys().next().value); }
+    return answer.greeting;
+  } catch { return null; } finally { if (timer) clearTimeout(timer); }
+}
+
+/** The greeting a conversation opened with, if it was asked already (no request). */
+export function knownGreeting(surface, session) {
+  return session ? cache.get(`${surface}:${session}`) || null : null;
+}
+
+/** The conversation sent its first message: its greeting is not drawn again. */
+export function forgetGreeting(surface, session) {
+  if (session) cache.set(`${surface}:${session}`, null);
+}
+
+/**
+ * Ask and draw. `host`: the empty state element; `isCurrent()`: false when the conversation is no
+ * longer the one on screen (the answer arrived late). → the greeting drawn, or null.
+ */
+export async function mountGreeting(host, { surface, cwd = null, project = null, session = null, t = null, onOpenMemory = null, isCurrent = null, fetchImpl = globalThis.fetch } = {}) {
+  if (!host) return null;
+  const greeting = await fetchGreeting({ surface, cwd, project, session, fetchImpl });
+  // (A host that is not in the document yet is fine: a panel may draw a tab before it shows it.)
+  if (!greeting) return null;
+  if (typeof isCurrent === 'function') { try { if (isCurrent() === false) return greeting; } catch { return greeting; } }
+  renderGreeting(host, greeting, { t, onOpenMemory });
+  return greeting;
+}
+
+export const _test = { reset() { cache.clear(); unavailableUntil = 0; } };