synabun 2.0.0 → 2.0.5

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/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; } };

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

@@ -0,0 +1,148 @@
+// ═══════════════════════════════════════════
+// SynaBun — Greeting: what a surface shows (DOM-free)
+// ═══════════════════════════════════════════
+//
+// The one greeting every surface shows (the Assistant, the Claude Code, Codex
+// and OpenCode panels, Settings' preview): the sentence SynaBun wrote, how long
+// the person was away, and a disclosure of what it was based on and what it
+// cost. This module decides every word; greeting-card.js draws it.
+//
+// GREETING_COPY is the English; `greeting.*` in i18n/*.json must equal it
+// (tests/greeting-view.test.mjs). Elapsed time is computed here, at display:
+// the sentence itself never says how long it has been, so one written hours
+// ago is still true.
+
+export const GREETING_COPY = Object.freeze({
+  label: 'Greeting from SynaBun',
+  back: 'Back after {time}',
+  'time.minute': '1 minute',
+  'time.minutes': '{n} minutes',
+  'time.hour': '1 hour',
+  'time.hours': '{n} hours',
+  'time.day': '1 day',
+  'time.days': '{n} days',
+  'time.week': '1 week',
+  'time.weeks': '{n} weeks',
+  'time.month': '1 month',
+  'time.months': '{n} months',
+  'basis.one': 'Based on 1 record',
+  'basis.many': 'Based on {n} records',
+  'basis.none': 'What this is based on',
+  'kind.thread': 'Last conversation',
+  'kind.session': 'Last session',
+  'kind.open': 'Open',
+  'kind.memory': 'Noted',
+  'kind.run': 'Run',
+  'kind.schedule': 'Schedule',
+  'kind.elsewhere': 'Elsewhere',
+  'kind.git': 'Working tree',
+  'kind.owner': 'About you',
+  'agent.assistant': 'Assistant',
+  'agent.claude-code': 'Claude Code',
+  'agent.codex': 'Codex',
+  'agent.opencode': 'OpenCode',
+  open: 'Open memory',
+  'source.writer': 'Written ahead by {model}',
+  'source.fallback': 'Put together from the records, no model',
+  'why.not-prepared': 'nothing was written ahead yet',
+  'why.out-of-date': 'what was written ahead was older than the news',
+  'why.no-writer': 'no Claude sign-in to write with',
+  'why.daily-cap': 'the daily limit of writer calls was reached',
+  'why.other': 'the writer gave no usable sentence',
+  tokens: '{n} tokens',
+  prepared: 'written {time} ago',
+  free: 'no tokens spent',
+});
+
+const num = (value) => (Number.isFinite(Number(value)) && Number(value) > 0 ? Math.round(Number(value)) : 0);
+
+/** A string of the greeting, through the app's translator when it has one. */
+export function greetingText(key, params = null, t = null) {
+  const full = `greeting.${key}`;
+  let value;
+  try { value = typeof t === 'function' ? t(full, params || undefined) : undefined; } catch { value = undefined; }
+  if (typeof value === 'string' && value && value !== full) return value;
+  const fallback = GREETING_COPY[key];
+  if (typeof fallback !== 'string') return key;
+  return params ? fallback.replace(/\{(\w+)\}/g, (_, name) => (params[name] != null ? String(params[name]) : `{${name}}`)) : fallback;
+}
+
+/** "40 minutes" · "3 hours" · "2 days" · "3 weeks" · "4 months", in the app's language. '' for no time. */
+export function formatAway(ms, t = null) {
+  if (!Number.isFinite(Number(ms)) || Number(ms) < 0) return '';
+  const minutes = Math.round(Number(ms) / 60_000);
+  const unit = (one, many, n) => (n === 1 ? greetingText(`time.${one}`, null, t) : greetingText(`time.${many}`, { n }, t));
+  if (minutes < 60) return unit('minute', 'minutes', Math.max(1, minutes));
+  const hours = Math.round(minutes / 60);
+  if (hours < 36) return unit('hour', 'hours', hours);
+  const days = Math.round(hours / 24);
+  if (days < 21) return unit('day', 'days', days);
+  if (days < 75) return unit('week', 'weeks', Math.round(days / 7));
+  return unit('month', 'months', Math.round(days / 30));
+}
+
+/** "$0.0006" · "<$0.0001" · '' when unknown or nothing. */
+export function formatGreetingCost(value) {
+  const usd = Number(value);
+  if (!Number.isFinite(usd) || usd <= 0) return '';
+  if (usd < 0.0001) return '<$0.0001';
+  return `$${usd < 0.01 ? usd.toFixed(4) : usd.toFixed(2)}`;
+}
+
+/**
+ * Everything a surface draws for one greeting (the engine's view: lib/greeting/engine.js).
+ * → { id, label, when, text, toggle, rows:[{ kind, kindLabel, label, id, openLabel }], cost } | null
+ * `when` is '' when the person was not away (a preview): the caller hides the line.
+ */
+export function greetingView(greeting, { now = Date.now(), t = null } = {}) {
+  const text = typeof greeting?.text === 'string' ? greeting.text.trim() : '';
+  if (!text) return null;
+  const since = Date.parse(greeting.awaySince ?? '');
+  const away = Number.isFinite(since) ? formatAway(Math.max(0, now - since), t) : '';
+  const basis = Array.isArray(greeting.basis) ? greeting.basis : [];
+  const rows = basis.filter((row) => row && typeof row.label === 'string' && row.label.trim()).map((row) => {
+    const kind = GREETING_COPY[`kind.${row.kind}`] ? row.kind : 'memory';
+    const agent = (kind === 'thread' || kind === 'session') && row.agent && GREETING_COPY[`agent.${row.agent}`] ? greetingText(`agent.${row.agent}`, null, t) : '';
+    return {
+      kind, kindLabel: agent ? `${greetingText(`kind.${kind}`, null, t)} · ${agent}` : greetingText(`kind.${kind}`, null, t),
+      label: row.label.trim(), id: typeof row.id === 'string' && row.id ? row.id : null,
+      openLabel: greetingText('open', null, t),
+    };
+  });
+  const cost = [];
+  if (greeting.source === 'writer') {
+    cost.push(greetingText('source.writer', { model: greeting.model || 'Claude' }, t));
+    const tokens = greeting.tokens && typeof greeting.tokens === 'object' ? num(greeting.tokens.input) + num(greeting.tokens.cacheWrite) + num(greeting.tokens.cacheRead) + num(greeting.tokens.output) : 0;
+    if (tokens) cost.push(greetingText('tokens', { n: tokens }, t));
+    const usd = formatGreetingCost(greeting.costUsd);
+    if (usd) cost.push(usd);
+    const prepared = Date.parse(greeting.preparedAt ?? '');
+    if (Number.isFinite(prepared) && now - prepared >= 60_000) cost.push(greetingText('prepared', { time: formatAway(now - prepared, t) }, t));
+  } else {
+    const why = greeting.error && GREETING_COPY[`why.${greeting.error}`] ? greeting.error : (greeting.error ? 'other' : null);
+    cost.push(why ? `${greetingText('source.fallback', null, t)}: ${greetingText(`why.${why}`, null, t)}` : greetingText('source.fallback', null, t));
+    cost.push(greetingText('free', null, t));
+  }
+  return {
+    id: typeof greeting.id === 'string' ? greeting.id : null,
+    label: greetingText('label', null, t),
+    when: away ? greetingText('back', { time: away }, t) : '',
+    text,
+    toggle: rows.length === 0 ? greetingText('basis.none', null, t) : rows.length === 1 ? greetingText('basis.one', null, t) : greetingText('basis.many', { n: rows.length }, t),
+    rows,
+    cost: cost.join(' · '),
+  };
+}
+
+/**
+ * What /api/greeting/open answered. → { state, greeting, reason }
+ * state: 'ok' (a greeting) · 'none' (nothing to say now) · 'old-server' (404: the page is newer than the
+ * server) · 'failed' (503: the engine did not start) · 'unreadable'
+ */
+export function readGreetingResponse(status, body) {
+  if (status === 404) return { state: 'old-server', greeting: null, reason: null };
+  if (status === 503) return { state: 'failed', greeting: null, reason: typeof body?.reason === 'string' ? body.reason : null };
+  if (status !== 200 || !body || body.ok !== true) return { state: 'unreadable', greeting: null, reason: null };
+  const greeting = body.greeting && typeof body.greeting === 'object' && typeof body.greeting.text === 'string' && body.greeting.text.trim() ? body.greeting : null;
+  return { state: greeting ? 'ok' : 'none', greeting, reason: typeof body.reason === 'string' ? body.reason : null };
+}