synabun 1.3.0 → 2.0.0

package/neural-interface/public/shared/ui-workspaces.js

@@ -20,6 +20,7 @@
 import { state, emit, on } from './state.js';
 import { KEYS } from './constants.js';
 import { storage } from './storage.js';
+import { posStore } from './node-positions-store.js';
 import { getVariant } from './registry.js';
 import {
   getOpenCardsSnapshot,
@@ -60,7 +61,7 @@ function saveWorkspacesToStorage(list) {
 
 function _readStoredPositions(key) {
   try {
-    return JSON.parse(storage.getItem(key) || '{}');
+    return JSON.parse(posStore.getItem(key) || '{}');
   } catch {
     return {};
   }

package/neural-interface/public/shared/utils.js

@@ -288,6 +288,9 @@ export function createFrameRenderer(canvas, ctx) {
 
   function flush() {
     if (destroyed || rendering || !pending) return;
+    // Tab hidden — skip decode entirely; the latest frame stays in `pending`
+    // and draws as soon as render() is called again on a visible tab
+    if (document.hidden) return;
     const now = performance.now();
     if (now - lastFrameTime < FRAME_INTERVAL) {
       // Drop frame — too soon since last render
@@ -358,3 +361,58 @@ export function createFrameRenderer(canvas, ctx) {
     destroy() { destroyed = true; pending = null; },
   };
 }
+
+/**
+ * Debounce — invoke `fn` only after `wait` ms have elapsed since the last call
+ * (trailing edge). Use for input-driven work that shouldn't run per keystroke
+ * (filter rebuilds, syntax highlight). The wrapper exposes `.cancel()` to drop a
+ * pending call (e.g. on teardown).
+ * @param {Function} fn
+ * @param {number} wait milliseconds
+ * @returns {Function & { cancel(): void }}
+ */
+export function debounce(fn, wait = 120) {
+  let timer = null;
+  function wrapped(...args) {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn.apply(this, args);
+    }, wait);
+  }
+  wrapped.cancel = () => {
+    if (timer) { clearTimeout(timer); timer = null; }
+  };
+  return wrapped;
+}
+
+/**
+ * rAF throttle — coalesce a burst of calls into a single invocation on the next
+ * animation frame, always running with the most recent arguments. Ideal for
+ * scroll handlers and "rebuild at most once per frame" render coalescing
+ * (vsync-aligned, drops redundant work without deferring the visible result by
+ * more than one frame). The wrapper exposes `.cancel()` to drop a pending frame.
+ * @param {Function} fn
+ * @returns {Function & { cancel(): void }}
+ */
+export function rafThrottle(fn) {
+  let rafId = null;
+  let lastArgs = null;
+  let lastThis = null;
+  function wrapped(...args) {
+    lastArgs = args;
+    lastThis = this;
+    if (rafId !== null) return;
+    rafId = requestAnimationFrame(() => {
+      rafId = null;
+      const a = lastArgs, t = lastThis;
+      lastArgs = lastThis = null;
+      fn.apply(t, a);
+    });
+  }
+  wrapped.cancel = () => {
+    if (rafId !== null) { cancelAnimationFrame(rafId); rafId = null; }
+    lastArgs = lastThis = null;
+  };
+  return wrapped;
+}

package/neural-interface/public/shared/vterm-buffer.js

@@ -114,7 +114,7 @@ export class VTermBuffer {
    * @param {number} cols
    * @param {number} rows
    */
-  constructor(cols, rows) {
+  constructor(cols, rows, maxScrollback = MAX_SCROLLBACK) {
     this.cols = cols;
     this.rows = rows;
 
@@ -130,7 +130,7 @@ export class VTermBuffer {
     this._buffer = this._mainBuffer;
 
     // Scrollback (main buffer only) — circular buffer for O(1) operations
-    this._scrollback = new CircularBuffer(MAX_SCROLLBACK);
+    this._scrollback = new CircularBuffer(maxScrollback);
 
     // Cursor state
     this._cursorX = 0;
@@ -182,9 +182,15 @@ export class VTermBuffer {
 
   /** Feed raw PTY data */
   write(data) {
+    this._writeGen = (this._writeGen || 0) + 1;
     this._parser.parse(data);
   }
 
+  /** Monotonic generation counter — bumps on every mutation (write/resize).
+   *  Lets the server memoize rendered snapshots: same generation ⇒ identical
+   *  buffer contents. Inert on the browser side. */
+  get writeGen() { return this._writeGen || 0; }
+
   /** Get a row from the visible buffer (0 = top of screen) */
   getRow(idx) {
     if (idx < 0 || idx >= this.rows) return null;
@@ -221,6 +227,7 @@ export class VTermBuffer {
   get cursorX() { return this._cursorX; }
   get cursorY() { return this._cursorY; }
   get cursorVisible() { return this._cursorVisible; }
+  get useAltBuffer() { return this._useAlt; }
   get title() { return this._title; }
   get bracketedPaste() { return this._bracketedPaste; }
   get appCursorKeys() { return this._appCursorKeys; }
@@ -228,6 +235,7 @@ export class VTermBuffer {
   /** Resize the terminal */
   resize(cols, rows) {
     if (cols === this.cols && rows === this.rows) return;
+    this._writeGen = (this._writeGen || 0) + 1;
     const oldCols = this.cols;
     const oldRows = this.rows;
     this.cols = cols;
@@ -265,11 +273,13 @@ export class VTermBuffer {
       if (!row) continue;
       const s = r === startRow ? startCol : 0;
       const e = r === endRow ? endCol : this.cols - 1;
-      let line = '';
+      // Array+join instead of += — string concat is O(n²) over wide rows and
+      // this runs over the full scrollback for snapshots
+      const chars = [];
       for (let c = s; c <= e; c++) {
-        line += row[c]?.char || ' ';
+        chars.push(row[c]?.char || ' ');
       }
-      lines.push(line.replace(/\s+$/, ''));
+      lines.push(chars.join('').replace(/\s+$/, ''));
     }
     return lines.join('\n');
   }

package/neural-interface/public/shared/whatsapp/wa-phone.js

@@ -0,0 +1,65 @@
+// Phone numbers for the WhatsApp Link. One normaliser shared by the Settings
+// UI (served as a static ES module: no Node imports, no DOM) and the server,
+// so the number the user sees accepted is the number the server stores.
+//
+// normalizePhone takes what people type or paste — spaces of any kind, the
+// invisible direction marks some apps wrap copied numbers in, dashes, dots,
+// brackets, slashes, the "+44 (0)20" optional trunk zero, a 00 international
+// prefix — and returns the bare digits with their country code, or a code the
+// UI turns into a sentence via PHONE_ERRORS. Digits that start with 0 carry no
+// country code (national format, or a "+0…" no country uses): refused, never
+// guessed into some other country's number.
+//
+// maskPhone must return exactly what maskNumber in lib/whatsapp/redact.js
+// returns (tests/whatsapp-phone.test.mjs pins the parity). It is duplicated,
+// not imported, because redact.js runs on Node only.
+
+/** Error code → one short sentence for the Settings UI. */
+export const PHONE_ERRORS = Object.freeze({
+  NEEDS_COUNTRY_CODE: 'Add your country code first, for example +44 for the UK or +1 for the US.',
+  INVALID_CHARS: 'Use digits only; spaces, dashes and brackets are fine.',
+  TOO_SHORT: 'That number is too short.',
+  TOO_LONG: 'That number is too long (15 digits at most).',
+});
+
+const MIN_DIGITS = 8;
+const MAX_DIGITS = 15; // E.164
+
+// "(0)" — or "( 0 )" — after a country code is the trunk zero dialled only inside the country.
+const TRUNK_ZERO_RE = /\(\s*0\s*\)/g;
+// Whitespace of every kind (NBSP, thin, narrow and ideographic spaces, BOM), zero-width and
+// bidi marks, typographic dashes and the minus sign, and . ( ) / -.
+const SEPARATORS_RE = /[\s؜​-‏‪-‮⁠⁦-⁩‐-―−.()/-]/g;
+const ASCII_DIGITS_RE = /^[0-9]*$/;
+
+function toText(input) {
+  try { return String(input ?? ''); } catch { return null; }
+}
+
+/**
+ * Normalise a phone number to international digits. Never throws.
+ * @returns {{ ok: true, digits: string, e164: string } | { ok: false, code: 'NEEDS_COUNTRY_CODE' | 'INVALID_CHARS' | 'TOO_SHORT' | 'TOO_LONG' }}
+ */
+export function normalizePhone(input) {
+  let text = toText(input);
+  if (text === null) return { ok: false, code: 'INVALID_CHARS' };
+  text = text.trim()
+    .replace(TRUNK_ZERO_RE, (match, offset, whole) => (/[0-9]/.test(whole.slice(0, offset)) ? '' : match))
+    .replace(SEPARATORS_RE, '');
+  if (text.startsWith('00')) text = `+${text.slice(2)}`;
+  if (text.startsWith('0')) return { ok: false, code: 'NEEDS_COUNTRY_CODE' };
+  const digits = text.startsWith('+') ? text.slice(1) : text;
+  if (!ASCII_DIGITS_RE.test(digits)) return { ok: false, code: 'INVALID_CHARS' };
+  if (digits.startsWith('0')) return { ok: false, code: 'NEEDS_COUNTRY_CODE' };
+  if (digits.length < MIN_DIGITS) return { ok: false, code: 'TOO_SHORT' };
+  if (digits.length > MAX_DIGITS) return { ok: false, code: 'TOO_LONG' };
+  return { ok: true, digits, e164: `+${digits}` };
+}
+
+/** A phone number for display: never more than the last four digits. */
+export function maskPhone(input) {
+  const d = (toText(input) ?? '').replace(/\D/g, '');
+  if (d.length >= 8) return `••••${d.slice(-4)}`;
+  if (d.length >= 5) return `••${d.slice(-2)}`;
+  return '••••';
+}

package/neural-interface/public/shared/whatsapp/wa-view.js

@@ -0,0 +1,411 @@
+// ═══════════════════════════════════════════
+// WA-VIEW — what Settings → WhatsApp shows for a status
+// ═══════════════════════════════════════════
+//
+// Pure (no DOM, no fetch): waView(status) turns GET /api/whatsapp/status into
+// the header and the setup pane — { dot, title, sub, primary, secondary, step,
+// pane, nav } — for every state the service reports, and this file holds every
+// sentence the tab shows, so tests can read them and ui-whatsapp.js only
+// places them. Strings are plain text; the tab escapes whatever it inserts.
+
+// ── Translation ──
+// The English in this file is the source text. Without a translator (tests, Node) every string reads as
+// written. Settings installs one with setTranslator((key, english, params) => string); the keys are
+// settings.redesign.wa.<path> (generated by docs/design/settings-redesign/tools/wa_keys.mjs) and `{name}`
+// marks a value filled in at run time.
+let translate = null;
+export function setTranslator(fn) { translate = typeof fn === 'function' ? fn : null; }
+const fill = (text, params) => (params ? String(text).replace(/\{(\w+)\}/g, (m, k) => (params[k] != null ? params[k] : m)) : text);
+const say = (key, english, params) => (translate ? translate(`settings.redesign.wa.${key}`, english, params) : fill(english, params));
+/** One entry of a table of sentences (STAGE_TEXT, ERROR_TEXT …), or its fallback entry. */
+const pick = (prefix, table, id, fallback) => {
+  const key = Object.prototype.hasOwnProperty.call(table, id) ? id : fallback;
+  return key == null ? '' : say(`${prefix}.${key}`, table[key]);
+};
+const NOT_COPY = new Set(['id', 'value', 'key', 'name']);
+const segment = (v) => String(v).replace(/[^A-Za-z0-9_-]+/g, '');
+/**
+ * A copy of a constant in the reader's language. Arrays of objects are keyed by their id / value / key / name,
+ * plain arrays by index; identifiers (id, value, key, name) are never translated.
+ */
+export function localize(prefix, data) {
+  if (typeof data === 'string') return data ? say(prefix, data) : data;
+  if (Array.isArray(data)) {
+    return data.map((item, i) => {
+      const named = item && typeof item === 'object' && !Array.isArray(item) ? (item.id ?? item.value ?? item.key ?? item.name) : undefined;
+      return localize(`${prefix}.${named != null ? segment(named) : i}`, item);
+    });
+  }
+  if (data && typeof data === 'object') return Object.fromEntries(Object.entries(data).map(([k, v]) => [k, NOT_COPY.has(k) ? v : localize(`${prefix}.${k}`, v)]));
+  return data;
+}
+
+export const TAB_STATES = Object.freeze(['unavailable', 'not_installed', 'installing', 'install_failed', 'ready', 'linking', 'link_expired', 'confirm_owner', 'connected', 'reconnecting', 'paused', 'logged_out', 'error']);
+
+export const STEPS = Object.freeze([
+  { id: 'choose', label: 'Choose' },
+  { id: 'install', label: 'Install' },
+  { id: 'link', label: 'Link' },
+  { id: 'confirm', label: 'Confirm' },
+]);
+
+export const MODE_CARDS = Object.freeze([
+  {
+    id: 'self',
+    title: 'Message yourself',
+    badge: 'free, one scan',
+    body: 'Talk to SynaBun in your own "Message yourself" chat. No second number, nothing to buy: scan one QR code and write.',
+    notes: ['SynaBun reads that one chat only; every other chat is ignored.', 'Only messages typed on your phone count: what you type into "Message yourself" from WhatsApp Web or Desktop is ignored.', 'Replies start with "SynaBun:". WhatsApp may not notify you of messages in your own chat.'],
+  },
+  {
+    id: 'dedicated',
+    title: 'A second number',
+    badge: 'Safer',
+    body: 'Link a spare WhatsApp account (a second SIM, or WhatsApp Business on another number) and chat with it like a contact. Your own account is never linked.',
+    notes: ['Replies arrive as normal notifications.', 'Needs a second number that can receive WhatsApp. You prove it is you with a one-time claim code.'],
+  },
+]);
+
+export const LEVEL_CARDS = Object.freeze([
+  { id: 'read-only', title: 'Read-only', body: 'SynaBun answers, researches and plans. It never changes files, runs commands or starts agents from WhatsApp; a plan can only be approved on this computer.' },
+  { id: 'ask', title: 'Ask on my phone', badge: 'Default', body: 'Before anything that would change your files, run a command or start an agent, SynaBun asks on WhatsApp and acts only on your yes. Any other message approves nothing: the conversation just carries on.' },
+  { id: 'autonomous', title: 'Autonomous', body: 'SynaBun acts without asking, like the Assistant on this computer. Turning it on takes a second click here and an ALLOW code sent from your phone within 5 minutes. It turns back to Ask after 8 hours. Autonomous can read any file your computer account can, including SynaBun\'s WhatsApp login. Use it only with a locked phone, ideally on a second number.' },
+]);
+
+/** Ask and Autonomous need a Claude brain: the Safety warning when the WhatsApp conversation runs on another one (status.brainLimit). */
+export function brainLimitText(status) {
+  const limit = status?.brainLimit;
+  if (!limit || !limit.provider) return '';
+  return say('brainLimit', 'This conversation runs read-only because its brain is {brain}; switch the WhatsApp brain to Claude for Ask/Autonomous.', { brain: limit.label || limit.provider });
+}
+
+// ── Which model runs the WhatsApp conversation (status.brainChoice; lib/whatsapp/brain.js) ──
+export const BRAIN_COPY = Object.freeze({
+  label: 'Model',
+  same: 'Same as the Assistant',
+  menuTitle: 'Model for WhatsApp',
+  hint: 'Which model answers you on WhatsApp. A change applies from your next message. A model from another provider carries on in the same conversation with a fresh context.',
+  effort: 'Thinking effort',
+  effortDefault: 'Default effort',
+  saved: 'WhatsApp model saved. It applies from your next message.',
+});
+const BRAIN_PROVIDER_LABELS = Object.freeze({ 'claude-code': 'Claude', codex: 'Codex', opencode: 'OpenCode' });
+export function brainProviderLabel(provider) { return BRAIN_PROVIDER_LABELS[provider] || String(provider || ''); }
+/**
+ * The stored choice of a status: { provider, model, effort } or null (same as
+ * the Assistant). A status without the field (an older server) reads as null.
+ */
+export function brainChoiceOf(status) {
+  const choice = status?.brainChoice?.choice ?? status?.config?.brain ?? null;
+  if (!choice || typeof choice !== 'object' || typeof choice.provider !== 'string' || typeof choice.model !== 'string' || !choice.model) return null;
+  return { provider: choice.provider, model: choice.model, effort: typeof choice.effort === 'string' && choice.effort ? choice.effort : null };
+}
+/** The choice in use: the stored one unless the server fell back to the default (a disabled or unknown model). */
+export function brainChoiceInUse(status) {
+  return status?.brainChoice?.fallback ? null : brainChoiceOf(status);
+}
+/**
+ * The model button's text: "Same as the Assistant" (with the brain that is, when
+ * the server says) or "Codex · GPT-6 Sol". `modelLabel`: the picker's own name for the model.
+ */
+export function brainChoiceLabel(status, { modelLabel = '' } = {}) {
+  const choice = brainChoiceInUse(status);
+  const effective = status?.brainChoice?.effective || null;
+  if (!choice) {
+    const same = say('brain.same', 'Same as the Assistant');
+    const now = effective?.provider ? [effective.providerLabel || brainProviderLabel(effective.provider), effective.modelLabel || effective.model].filter(Boolean).join(' · ') : '';
+    return now ? say('brain.sameNow', '{same} ({now})', { same, now }) : same;
+  }
+  return `${brainProviderLabel(choice.provider)} · ${modelLabel || effective?.modelLabel || choice.model}`;
+}
+/**
+ * The notes under the model: why a stored choice is not in use, and that a
+ * brain other than Claude runs the conversation read-only (the existing rule).
+ */
+export function brainChoiceNotes(status) {
+  const view = status?.brainChoice;
+  if (!view || typeof view !== 'object') return [];
+  const notes = [];
+  const fallback = view.fallback;
+  if (fallback?.model) {
+    notes.push(fallback.reason === 'disabled'
+      ? say('brain.fallbackDisabled', '{model} is switched off in the Assistant\'s Models list, so WhatsApp runs on the same brain as the Assistant. Pick another model here, or switch it back on.', { model: fallback.model })
+      : say('brain.fallbackUnknown', '{provider} no longer lists {model}, so WhatsApp runs on the same brain as the Assistant. Pick another model here.', { provider: fallback.providerLabel || brainProviderLabel(fallback.provider), model: fallback.model }));
+  }
+  if (view.readOnly?.provider) {
+    notes.push(say('brain.readOnly', 'On {brain}, a WhatsApp conversation runs read-only whatever the level: only a Claude model can ask on your phone before it acts. Pick a Claude model for Ask on my phone or Autonomous.', { brain: view.readOnly.label || brainProviderLabel(view.readOnly.provider) }));
+  }
+  return notes;
+}
+
+export const PROGRESS_OPTIONS = Object.freeze([
+  { value: 'off', label: 'Off', hint: 'Only the answer.' },
+  { value: 'key', label: 'Key moments', hint: '"On it…", agents starting, and a note when a task runs long.' },
+  { value: 'all', label: 'Everything', hint: 'Also what SynaBun is doing while it works (at most every 20 seconds).' },
+]);
+export const MAX_MESSAGE_OPTIONS = Object.freeze([
+  { value: 1, label: '1 message' },
+  { value: 3, label: 'Up to 3' },
+  { value: 5, label: 'Up to 5' },
+]);
+export const ROTATION_OPTIONS = Object.freeze([
+  { value: 'idle6h', label: 'After 6 idle hours' },
+  { value: 'daily', label: 'Every day at 04:00' },
+  { value: 'never', label: 'Never (send /new yourself)' },
+]);
+export const TRIGGER_OPTIONS = Object.freeze([
+  { value: 'all', label: 'Every message in "Message yourself"', hint: 'Everything you write in your own chat goes to SynaBun.' },
+  { value: 'prefix', label: 'Only messages that start with sb', hint: 'Keep using "Message yourself" for notes; start a message with sb (or sb:) to talk to SynaBun. Commands like /stop, the ALLOW code and replies to SynaBun\'s own messages always reach it.' },
+]);
+
+export const COMMANDS = Object.freeze([
+  { name: '/status', text: 'what SynaBun is doing, its spend and level' },
+  { name: '/stop', text: 'stop the current task, its agents and anything waiting for your answer' },
+  { name: '/new', text: 'start a fresh conversation' },
+  { name: '/pause', text: 'stop acting on messages until /resume' },
+  { name: '/resume', text: 'act on messages again (not after a pause from this computer)' },
+  { name: '/cards', text: 'ask again what is still waiting for your answer' },
+  { name: '/help', text: 'the list of commands' },
+  { name: '//text', text: 'send text that starts with a slash' },
+]);
+
+export const LIMITS = Object.freeze([
+  'Text and pictures (up to 4 per message, 5 MB each). Voice notes, videos, documents and stickers are not read yet.',
+  'At most 20 messages a minute and 300 a day; 5 messages can wait in line while SynaBun works.',
+  'Messages older than 10 minutes when SynaBun comes back online are skipped (it tells you how many).',
+  'Answers are split into messages of 3,500 characters; the rest stays in SynaBun.',
+  'Computer use from WhatsApp is off until you turn it on above. Then: never at Read-only or while paused, after one yes per task at Ask on my phone, and without asking while Autonomous is active. Agents started from WhatsApp never get it.',
+  'Levels, models and settings change only here, never from the phone.',
+]);
+
+export const PRIVACY_STAYS = Object.freeze([
+  { key: 'session', label: 'WhatsApp session keys', hint: 'The linked-device credentials. Outside the folder SynaBun backs up.' },
+  { key: 'connector', label: 'The connector', hint: 'Baileys and its dependencies, installed on demand.' },
+  { key: 'logs', label: 'Activity log', hint: 'whatsapp-YYYYMMDD.log, readable by you only, deleted after 7 days.' },
+]);
+export const PRIVACY_NEVER = Object.freeze([
+  'Never reads, stores or answers any chat except yours with SynaBun.',
+  'Never sends a message to anyone but you.',
+  'Never keeps phone numbers: settings and logs show the last four digits at most.',
+  'Never uploads your chats anywhere: no SynaBun server sits in between, messages go from WhatsApp to this computer.',
+  'Never keeps message text in the log unless you turn it on below.',
+]);
+
+export const HELP = Object.freeze({
+  how: 'SynaBun links to WhatsApp the same way WhatsApp Web does: as a linked device of an account. Messages you send in the chosen chat reach the SynaBun Assistant on this computer, and its answers come back as WhatsApp messages. Your computer has to be on and SynaBun running.',
+  compare: [
+    ['', 'Message yourself', 'A second number'],
+    ['Cost', 'Free', 'Free (needs a second number)'],
+    ['Setup', 'One QR scan', 'One QR scan + a claim code'],
+    ['Notifications', 'Often silent', 'Normal'],
+    ['Account linked to SynaBun', 'Yours', 'The second one'],
+    ['If WhatsApp restricts it', 'Your own account', 'Only the second account'],
+  ],
+  unofficial: 'This uses an unofficial connection (Baileys), not the WhatsApp Business API. WhatsApp\'s Help Center warns that using unofficial apps "may result in a temporary or permanent account ban". SynaBun keeps traffic low and only ever writes to you, but the risk is not zero; the second-number mode keeps it off your own account.',
+  linkedDevice: 'A linked device can see every chat of the account. SynaBun receives them from WhatsApp and ignores them: only your chat with SynaBun is read, and nothing else is stored.',
+  lostPhone: 'Lost your phone, or something looks wrong? Press Pause now here, or on any device open WhatsApp → Settings → Linked devices, tap SynaBun and Log out.',
+  downloads: 'The connector is downloaded from the npm registry the first time you set up WhatsApp (a few seconds), pinned to exact versions: baileys (MIT) and its dependencies, among them libsignal (GPL-3.0). It is installed in its own folder and runs as a separate process; it is not part of SynaBun\'s own code. The pin is baileys 7.0.0-rc14: older versions are deprecated for CVE-2026-48063.',
+  troubleshooting: [
+    'WhatsApp allows 4 linked devices. If linking fails, remove one under Linked devices on your phone.',
+    'If your phone is offline for 14 days, WhatsApp logs out every linked device. Link again when that happens.',
+    'Replies in "Message yourself" usually do not notify you; use the second-number mode if you need notifications.',
+    'In "Message yourself", only messages typed on the phone reach SynaBun. Messages typed into that chat from WhatsApp Web or Desktop are ignored.',
+    'With "Only messages that start with sb", a note without sb never reaches SynaBun and is not logged; commands, the ALLOW code and replies to SynaBun\'s messages always get through.',
+    'The QR code expires after about a minute. Press "Show a new code" and scan faster, or link with your phone number instead.',
+    'Stuck on "Reconnecting"? Check this computer\'s internet connection, then press Reconnect now.',
+  ],
+  browserTools: 'Not the same as the WhatsApp browser tools. The whatsapp MCP profile lets agents read WhatsApp Web in SynaBun\'s browser; this tab is you chatting with SynaBun from your phone. They do not share a session.',
+  uninstall: 'Uninstalling SynaBun does not unlink WhatsApp. Use Unlink or Remove here first, or log SynaBun out under WhatsApp → Settings → Linked devices.',
+});
+
+/** The connector's download size from its manifest (status.connector.approxSizeMB): "about 29 MB", or '' when unknown. */
+export function connectorSize(status) {
+  const mb = Number(status?.connector?.approxSizeMB);
+  return Number.isFinite(mb) && mb > 0 ? say('connectorSize', 'about {mb} MB', { mb: Math.round(mb) }) : '';
+}
+/** The note under the setup choices: the one-time download, sized from the manifest. */
+export function chooseNote(status) {
+  const size = connectorSize(status);
+  return size
+    ? say('chooseNoteSized', 'The first time, SynaBun downloads a small connector for WhatsApp ({size}, a few seconds) into its own folder.', { size })
+    : say('chooseNote', 'The first time, SynaBun downloads a small connector for WhatsApp (a few seconds) into its own folder.');
+}
+
+export const STAGE_TEXT = Object.freeze({
+  checking: 'Checking npm and free disk space…',
+  downloading: 'Downloading the connector…',
+  verifying: 'Verifying the download…',
+  activating: 'Activating…',
+});
+
+export const INSTALL_ERRORS = Object.freeze({
+  NPM_NOT_FOUND: 'npm was not found. Install Node.js (it comes with npm), then try again.',
+  OFFLINE: 'The npm registry could not be reached. Check the internet connection and try again.',
+  REGISTRY_REFUSED: 'The npm registry refused the download. A proxy or firewall may be in the way.',
+  DISK_FULL: 'Not enough free disk space (about 150 MB is needed).',
+  NO_PERMISSION: 'SynaBun could not write to its runtime folder.',
+  FILE_IN_USE: 'A file was in use. Close other SynaBun windows and try again.',
+  TIMEOUT: 'The download took longer than 5 minutes.',
+  VERIFY_FAILED: 'The downloaded connector did not pass verification, so it was not used.',
+  INSTALL_BUSY: 'Another install is already running.',
+  ABORTED: 'The install was cancelled.',
+  UNKNOWN: 'Something unexpected happened. The install log has the details.',
+});
+
+export const ERROR_TEXT = Object.freeze({
+  HOST_HELD: 'The WhatsApp connector kept crashing, so SynaBun stopped it. Reconnect to try again; the install log may help.',
+  HOST_UNAVAILABLE: 'The WhatsApp connector did not start.',
+  REPLACED: 'Another copy of this WhatsApp link connected from somewhere else and took over. Reconnect here to take it back.',
+  LOCKED: 'Another SynaBun is using the WhatsApp session files. Close it, then reconnect.',
+  SESSION_ERROR: 'WhatsApp closed the session. Reconnect, or unlink and link again if it keeps happening.',
+  RECONNECT_LIMIT: 'Too many reconnects in a short time, so SynaBun stopped trying. Check the internet connection, then reconnect.',
+  OWNER_ANOMALY: 'Sending is paused because a message did not look like it came from the owner. Confirm the owner again (second number), or unlink and link again (Message yourself).',
+  PAIRING_FAILED: 'WhatsApp did not give a pairing code for that number. Check the number, or use the QR code.',
+  RUNTIME_MISSING: 'The WhatsApp connector is missing. Install it again.',
+  AUTH_PERMS: 'SynaBun could not make the WhatsApp session files private (yours only). Fix the permissions of the folder under Data & privacy (700 for the folder, 600 for its files), then reconnect.',
+  CONNECT_FAILED: 'SynaBun could not connect to WhatsApp.',
+  FORBIDDEN: 'WhatsApp refused the connection.',
+  LINK_FAILED: 'Linking failed. Try again.',
+});
+
+export const LOGOUT_TEXT = Object.freeze({
+  removed: { title: 'Logged out from the phone', sub: 'SynaBun was removed under Linked devices, or WhatsApp ended the session. Link again to keep chatting.' },
+  inactive: { title: 'Logged out after a long time offline', sub: 'WhatsApp logs out linked devices that stay offline for a long time. Link again to keep chatting.' },
+  banned: { title: 'WhatsApp refused this account', sub: 'WhatsApp blocked the account from linking devices, possibly a temporary or permanent ban. Check the WhatsApp app on the phone.' },
+});
+
+export const ACTIVITY_KINDS = Object.freeze({
+  inbound: 'Received', reply: 'Sent', ignored: 'Ignored', state: 'Status', security: 'Security', error: 'Problem', settings: 'Settings',
+});
+
+export const PHONE_HINT = 'Your WhatsApp number with its country code, for example +44 7911 123456.';
+export const TEST_HINT = 'Sends "SynaBun test message. If you can read this, WhatsApp is working."';
+
+const LEVEL_LABELS = Object.freeze({ 'read-only': 'Read-only', ask: 'Ask on my phone', autonomous: 'Autonomous' });
+export function levelLabel(level) { return pick('levelLabel', LEVEL_LABELS, level, 'ask'); }
+export function modeLabel(mode) { return mode === 'dedicated' ? say('modeLabel.dedicated', 'Second number') : say('modeLabel.self', 'Message yourself'); }
+
+/** 125000 → "2:05"; negative → "0:00". */
+export function formatCountdown(ms) {
+  const total = Math.max(0, Math.ceil((Number(ms) || 0) / 1000));
+  const h = Math.floor(total / 3600);
+  const m = Math.floor((total % 3600) / 60);
+  const s = total % 60;
+  return h ? `${h}:${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}` : `${m}:${String(s).padStart(2, '0')}`;
+}
+/** A clock time for an epoch ms ("14:05"). */
+export function clockTime(ms) {
+  const d = new Date(Number(ms));
+  return Number.isFinite(d.getTime()) ? `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}` : '';
+}
+
+function accountLine(status) {
+  const account = status?.account;
+  if (!account) return '';
+  const name = typeof account.name === 'string' && account.name.trim() && account.name !== '~' ? account.name.trim() : '';
+  return [name, account.masked].filter(Boolean).join(' · ');
+}
+const view = (dot, title, sub, { primary = null, secondary = null, step = null, pane, nav = 'disconnected' } = {}) => ({ dot, title, sub, primary, secondary, step, pane, nav });
+const button = (id, label) => ({ id, label });
+
+/**
+ * @param {object} status  GET /api/whatsapp/status (or null while it loads)
+ * @param {{now?: number}} [opts]
+ * @returns {{dot:'ok'|'warn'|'err'|'dim', title:string, sub:string, primary:{id,label}|null, secondary:{id,label}|null, step:string|null, pane:string, nav:'connected'|'disconnected'}}
+ */
+export function waView(status, { now = Date.now() } = {}) {
+  const s = status && typeof status === 'object' ? status : {};
+  if (s.ok === false) {
+    return view('err', say('view.unavailable.title', 'WhatsApp settings are unavailable'), s.status === 404 ? say('view.unavailable.noSupport', 'This SynaBun server has no WhatsApp support yet. Restart it after updating.') : String(s.error || say('view.unavailable.noAnswer', 'No answer from SynaBun.')), { pane: 'unavailable' });
+  }
+  const level = levelLabel(s.level);
+  const mode = modeLabel(s.mode);
+  switch (s.state) {
+    case 'unavailable':
+      // reason: 'starting' (the server is still booting the Assistant), 'error' (the WhatsApp Link failed to load), 'env' (the kill switch).
+      if (s.reason === 'starting') return view('dim', say('view.starting.title', 'WhatsApp is starting'), say('view.starting.sub', 'SynaBun is still starting its Assistant. This updates by itself in a few seconds.'), { pane: 'unavailable' });
+      if (s.reason === 'error') return view('err', say('view.loadFailed.title', 'WhatsApp could not start'), say('view.loadFailed.sub', 'The WhatsApp Link failed to load on this computer. The SynaBun server log says why; restart SynaBun once it is fixed.'), { pane: 'unavailable' });
+      return view('dim', say('view.off.title', 'WhatsApp is turned off on this computer'), say('view.off.sub', 'SYNABUN_WHATSAPP=off is set where SynaBun runs. Remove it and restart SynaBun to use WhatsApp.'), { pane: 'unavailable' });
+    case 'not_installed':
+      return view('dim', say('view.notInstalled.title', 'Not set up'), say('view.notInstalled.sub', 'Chat with your SynaBun Assistant from WhatsApp. Choose how below; it takes about a minute.'), { primary: button('setup', say('button.setup', 'Set up WhatsApp')), step: 'choose', pane: 'choose' });
+    case 'ready':
+      return view('dim', say('view.ready.title', 'Ready to link'), say('view.ready.sub', 'The connector is installed. Choose how you want to chat, then scan one QR code.'), { primary: button('setup', say('button.link', 'Link WhatsApp')), step: 'choose', pane: 'choose' });
+    case 'installing': {
+      const size = connectorSize(s);
+      const downloading = size ? say('view.installing.downloadingSized', 'Downloading the connector ({size}, once)…', { size }) : say('view.installing.downloading', 'Downloading the connector…');
+      return view('warn', say('view.installing.title', 'Setting up the WhatsApp connector'), s.stage === 'downloading' ? downloading : pick('stage', STAGE_TEXT, s.stage, 'checking'), { secondary: button('cancel-install', say('button.cancel', 'Cancel')), step: 'install', pane: 'installing' });
+    }
+    case 'install_failed':
+      return view('err', say('view.installFailed.title', 'The connector could not be installed'), pick('installError', INSTALL_ERRORS, s.code, 'UNKNOWN'), { primary: button('retry-install', say('button.tryAgain', 'Try again')), secondary: button('show-log', say('button.showLog', 'Show install log')), step: 'install', pane: 'install_failed' });
+    case 'linking': {
+      if (s.phase === 'scanned') return view('warn', say('view.scanned.title', 'Phone accepted, finishing the link…'), say('view.scanned.sub', 'Keep WhatsApp open on the phone for a few seconds.'), { secondary: button('cancel-link', say('button.cancel', 'Cancel')), step: 'link', pane: s.method === 'code' ? 'code' : 'qr' });
+      if (s.method === 'code') return view('warn', say('view.code.title', 'Enter the code on your phone'), say('view.code.sub', 'WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead.'), { secondary: button('cancel-link', say('button.cancel', 'Cancel')), step: 'link', pane: 'code' });
+      return view('warn', say('view.qr.title', 'Scan the QR code with WhatsApp'), say('view.qr.sub', 'On the phone: WhatsApp → Settings → Linked devices → Link a device.'), { secondary: button('cancel-link', say('button.cancel', 'Cancel')), step: 'link', pane: 'qr' });
+    }
+    case 'link_expired':
+      return view('warn', say('view.expired.title', 'The code expired'), say('view.expired.sub', 'Nothing was linked. Try again when your phone is ready.'), { primary: button('relink', say('button.newCode', 'Show a new code')), secondary: button('change-setup', say('button.changeSetup', 'Change setup')), step: 'link', pane: 'expired' });
+    case 'confirm_owner': {
+      if (s.confirm?.kind === 'code' || (s.mode === 'dedicated' && s.confirm?.kind !== 'self')) {
+        return view('warn', say('view.claim.title', 'Claim the second number from your own WhatsApp'), say('view.claim.sub', 'Send the one-time code from your personal WhatsApp to the linked number. Only that account can then talk to SynaBun.'), { primary: button('claim', say('button.claim', 'Show the claim code')), secondary: button('unlink', say('button.unlink', 'Unlink')), step: 'confirm', pane: 'claim' });
+      }
+      const who = accountLine(s);
+      const linked = who ? say('view.confirm.linkedAs', 'Linked as {who}.', { who }) : say('view.confirm.linked', 'A WhatsApp account is linked.');
+      const left = s.confirm?.expiresAt ? ` ${say('view.confirm.within', 'Confirm within {time}, or it is logged out.', { time: formatCountdown(s.confirm.expiresAt - now) })}` : '';
+      return view('warn', say('view.confirm.title', 'Is this your WhatsApp?'), `${linked}${left}`, { primary: button('confirm', say('button.confirm', 'This is me — start')), secondary: button('reject', say('button.reject', 'Not me? Unlink')), step: 'confirm', pane: 'confirm_self' });
+    }
+    case 'connected': {
+      const who = accountLine(s);
+      const until = s.level === 'autonomous' && s.levelExpiresAt ? ` ${say('view.connected.until', 'until {time}', { time: clockTime(s.levelExpiresAt) })}` : '';
+      // A Codex / OpenCode brain holds the conversation at read-only whatever the level.
+      const applies = s.brainLimit?.provider ? say('view.connected.readOnlyBrain', 'Read-only ({brain} brain)', { brain: s.brainLimit.label || s.brainLimit.provider }) : `${level}${until}`;
+      return view('ok', say('view.connected.title', 'Connected'), [mode, who, applies].filter(Boolean).join(' · '), { primary: button('open-conversation', say('button.openConversation', 'Open conversation')), secondary: button('test', say('button.test', 'Send a test message')), step: 'done', pane: 'connected', nav: 'connected' });
+    }
+    case 'reconnecting': {
+      const next = s.connection?.nextRetryAt ? s.connection.nextRetryAt - now : null;
+      const sub = next !== null && next > 0
+        ? say('view.reconnecting.retry', 'Connection lost. Attempt {attempt}; trying again in {time}.', { attempt: Math.max(1, Number(s.connection.attempt) || 1), time: formatCountdown(next) })
+        : say('view.reconnecting.connecting', 'Connecting to WhatsApp…');
+      return view('warn', say('view.reconnecting.title', 'Reconnecting'), sub, { primary: button('reconnect', say('button.reconnectNow', 'Reconnect now')), step: 'done', pane: 'reconnecting' });
+    }
+    case 'paused': {
+      const sub = s.enabled === false ? say('view.paused.off', 'WhatsApp is linked but turned off. Resume to act on messages again.')
+        : s.pausedBy === 'phone' ? say('view.paused.phone', 'Paused from your phone with /pause. Resume here, or send /resume.')
+          : say('view.paused.computer', 'Paused from this computer. SynaBun does not act on WhatsApp messages until you resume (the phone cannot undo this).');
+      return view('warn', say('view.paused.title', 'Paused'), sub, { primary: button('resume', say('button.resume', 'Resume')), step: 'done', pane: 'paused' });
+    }
+    case 'logged_out': {
+      const reason = Object.prototype.hasOwnProperty.call(LOGOUT_TEXT, s.reason) ? s.reason : 'removed';
+      return view('err', say(`logout.${reason}.title`, LOGOUT_TEXT[reason].title), say(`logout.${reason}.sub`, LOGOUT_TEXT[reason].sub), { primary: s.reason === 'banned' ? null : button('relink', say('button.linkAgain', 'Link again')), secondary: s.reason === 'banned' ? button('change-setup', say('button.setupAgain', 'Set up again')) : null, step: 'link', pane: 'logged_out' });
+    }
+    case 'error': {
+      const canReconnect = !['RUNTIME_MISSING'].includes(s.code);
+      return view('err', say('view.error.title', 'WhatsApp needs attention'), ERROR_TEXT[s.code] ? pick('error', ERROR_TEXT, s.code) : say('view.error.stopped', 'The WhatsApp link stopped ({code}).', { code: String(s.code || say('view.error.unknown', 'unknown error')) }), {
+        primary: s.code === 'OWNER_ANOMALY' ? (s.mode === 'dedicated' ? button('reset-owner', say('button.resetOwner', 'Confirm the owner again')) : button('unlink', say('button.unlinkRelink', 'Unlink and link again'))) : s.code === 'RUNTIME_MISSING' ? button('retry-install', say('button.installAgain', 'Install again')) : canReconnect ? button('reconnect', say('button.reconnect', 'Reconnect')) : null,
+        secondary: button('show-log', say('button.showLog', 'Show install log')), pane: 'error',
+      });
+    }
+    default:
+      return view('dim', say('view.loading.title', 'Checking WhatsApp…'), say('view.loading.sub', 'Asking SynaBun for the WhatsApp status.'), { pane: 'loading' });
+  }
+}
+
+/** The masked account and owner lines for the confirm card ("Linked as Ana · ••••1234"). */
+export function confirmLine(status) {
+  const who = accountLine(status);
+  return who ? say('confirmLine.as', 'Linked as {who}', { who }) : say('confirmLine.plain', 'Linked');
+}
+
+/** Every constant above in the reader's language: what ui-whatsapp.js places on screen. */
+export function localizedCopy() {
+  return {
+    STEPS: localize('steps', STEPS), MODE_CARDS: localize('mode', MODE_CARDS), LEVEL_CARDS: localize('level', LEVEL_CARDS),
+    PROGRESS_OPTIONS: localize('progress', PROGRESS_OPTIONS), MAX_MESSAGE_OPTIONS: localize('maxMessages', MAX_MESSAGE_OPTIONS),
+    ROTATION_OPTIONS: localize('rotation', ROTATION_OPTIONS), TRIGGER_OPTIONS: localize('trigger', TRIGGER_OPTIONS),
+    COMMANDS: localize('commands', COMMANDS), LIMITS: localize('limits', LIMITS),
+    PRIVACY_STAYS: localize('privacyStays', PRIVACY_STAYS), PRIVACY_NEVER: localize('privacyNever', PRIVACY_NEVER),
+    HELP: localize('help', HELP), STAGE_TEXT: localize('stage', STAGE_TEXT), INSTALL_ERRORS: localize('installError', INSTALL_ERRORS),
+    ERROR_TEXT: localize('error', ERROR_TEXT), LOGOUT_TEXT: localize('logout', LOGOUT_TEXT), ACTIVITY_KINDS: localize('activity', ACTIVITY_KINDS),
+    LEVEL_LABELS: localize('levelLabel', LEVEL_LABELS), PHONE_HINT: localize('phoneHint', PHONE_HINT), TEST_HINT: localize('testHint', TEST_HINT),
+    BRAIN_COPY: localize('brainCopy', BRAIN_COPY),
+  };
+}