claude-code-hub 1.26.0 → 1.27.1

package/public/app.js

@@ -42,6 +42,13 @@ const MAX_EVENT_CHARS = 16 * 1024;
 let defaultConfigDir = null;
 // What Ctrl+Alt+W does: 'palette' opens the config-dir palette, 'swap' switches to the previous dir.
 let configDirSwitch = 'palette';
+// config.json voice.enabled; hub.voice has no default key without it.
+let voiceOn = false;
+// 'hex' or 'browser', which the hub picked for voice.provider 'auto'.
+let voiceProvider = null;
+// The grammar's commands, {action, label, param, say, help}, for the voice help panel.
+let voiceCommands = [];
+const voiceInBrowser = () => voiceProvider === 'browser';
 // The app launcher's footer: the hub version from /api/config and its plugin from /api/apps/stats.
 const hubInfo = { version: null, plugin: null };
 // mode: 'project' (Ctrl+Alt+P), 'configDir' (Ctrl+Alt+W) or 'app' (Ctrl+Alt+A). One widget, three row sources.
@@ -280,6 +287,9 @@ async function init() {
   defaultConfigDir = config.defaultConfigDir ?? null;
   activeConfigDir = config.activeConfigDir ?? null;
   configDirSwitch = config.configDirSwitch ?? 'palette';
+  voiceOn = !!config.voice;
+  voiceProvider = config.voice?.provider ?? null;
+  voiceCommands = config.voice?.commands ?? [];
   applyTitle(config.activeConfigDir);
   themeVars = config.themeVars ?? {};
   hubThemes = config.themes ?? [];
@@ -291,6 +301,8 @@ async function init() {
   switchTab(tabs.includes(saved) ? saved : (tabs[0] ?? Object.keys(apps)[0]));
   listenMessages();
   listenKeys();
+  if (voiceOn) listenVoiceRelease();
+  if (config.voice?.auto && voiceInBrowser()) noteBrowserVoice();
   bindPalette();
   bindSettings();
   registerSW();
@@ -405,6 +417,505 @@ function showErrorToast(action, err) {
   if (!unauthorized) errorToastTimer = setTimeout(hideErrorToast, ERROR_TOAST_MS);
 }
 
+// voice.provider 'auto' fell back to the browser, whose speech service is online: say so once.
+const VOICE_NOTE_KEY = 'hub-voice-browser-noted';
+
+function noteBrowserVoice() {
+  try {
+    if (localStorage.getItem(VOICE_NOTE_KEY)) return;
+  } catch {}
+  const toast = document.getElementById('voice-note');
+  document.getElementById('voice-note-ok').addEventListener('click', () => {
+    try {
+      localStorage.setItem(VOICE_NOTE_KEY, '1');
+    } catch {}
+    hideToast(toast);
+  });
+  showToast(toast);
+}
+
+// Hold to talk. Frames forward keydown only, so the press moves focus to the pill on the hub page:
+// the release lands there, and focus goes back to the frame after it.
+const voice = {
+  state: 'idle',
+  send: false,
+  app: null,
+  drafts: false,
+  frame: null,
+  started: null,
+  live: null,
+  cancelling: null,
+  dictating: null,
+  pillTimer: 0,
+  helpTimer: 0,
+};
+
+function voicePill(text, listening = false) {
+  const pill = document.getElementById('voice-pill');
+  clearTimeout(voice.pillTimer);
+  pill.textContent = text;
+  pill.classList.toggle('listening', listening);
+  pill.hidden = false;
+  return pill;
+}
+
+function hideVoicePill(afterMs = 0) {
+  clearTimeout(voice.pillTimer);
+  voice.pillTimer = setTimeout(() => {
+    document.getElementById('voice-pill').hidden = true;
+  }, afterMs);
+}
+
+const VOICE_HELP_LINGER_MS = 6000;
+
+function helpRow(action, say, hint, what, kind = '') {
+  const row = el('div', `voice-help-row ${kind}`.trim());
+  row.dataset.action = action;
+  const line = el('div', 'say', say);
+  if (hint) line.append(' ', el('i', '', hint));
+  row.append(line, el('div', 'what', what));
+  return row;
+}
+
+// Voice runs only what the app on screen handles, so a hold never switches tabs.
+const handledHere = (action) => actions[action]?.app === activeApp;
+const voiceRowsHere = () => voiceCommands.filter((c) => handledHere(c.action));
+const tabName = () => apps[activeApp]?.name ?? 'this tab';
+
+// Open for the whole hold: what the user can say on this tab, with the row the words match lit.
+function showVoiceHelp() {
+  const panel = document.getElementById('voice-help');
+  clearTimeout(voice.helpTimer);
+  const rows = voiceRowsHere().map((c) => helpRow(c.action, `Hub, ${c.say}`, `<${c.param}>`, c.help));
+  if (voice.drafts)
+    rows.push(helpRow('session.paste', 'anything else', '', 'Typed into the session as a draft', 'other'));
+  document.getElementById('voice-help-rows').replaceChildren(...rows);
+  document.getElementById('voice-help-title').textContent = `What you can say on ${tabName()}`;
+  document.getElementById('voice-help-tip').textContent = voice.drafts
+    ? 'Enter during the hold sends · Backspace cancels'
+    : 'Backspace cancels';
+  panel.hidden = false;
+}
+
+function hideVoiceHelp(afterMs = 0) {
+  clearTimeout(voice.helpTimer);
+  voice.helpTimer = setTimeout(() => {
+    document.getElementById('voice-help').hidden = true;
+  }, afterMs);
+}
+
+function markVoiceHelp(action) {
+  for (const row of document.getElementById('voice-help-rows').children) {
+    row.classList.toggle('on', row.dataset.action === action);
+  }
+}
+
+// Live speech: the page records the mic and the hub relays it to the provider, which answers with
+// the text so far. False after the hub answers 501 or the mic is refused: then the provider records.
+let voiceStream = true;
+const VOICE_RATE = 16000;
+const VOICE_CHUNK = VOICE_RATE / 5;
+const VOICE_TAP = `registerProcessor('voice-tap', class extends AudioWorkletProcessor {
+  process(inputs) { const ch = inputs[0] && inputs[0][0]; if (ch) this.port.postMessage(ch.slice(0)); return true; }
+});`;
+
+async function openMic(onSamples) {
+  const media = await navigator.mediaDevices.getUserMedia({
+    audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true },
+  });
+  const ctx = new AudioContext({ sampleRate: VOICE_RATE });
+  try {
+    const url = URL.createObjectURL(new Blob([VOICE_TAP], { type: 'text/javascript' }));
+    await ctx.audioWorklet.addModule(url);
+    URL.revokeObjectURL(url);
+    const tap = new AudioWorkletNode(ctx, 'voice-tap');
+    tap.port.onmessage = (e) => onSamples(e.data);
+    ctx.createMediaStreamSource(media).connect(tap).connect(ctx.destination);
+  } catch (err) {
+    for (const t of media.getTracks()) t.stop();
+    ctx.close();
+    throw err;
+  }
+  return () => {
+    for (const t of media.getTracks()) t.stop();
+    ctx.close();
+  };
+}
+
+function startLive() {
+  const live = { buf: [], len: 0, queue: Promise.resolve(), close: null, opened: false, sent: '' };
+  live.ready = Promise.allSettled([
+    sendJson('POST', '/api/voice/stream/start'),
+    openMic((samples) => {
+      live.buf.push(samples);
+      live.len += samples.length;
+      if (live.close && live.len >= VOICE_CHUNK) sendAudio(live);
+    }),
+  ]).then(([started, mic]) => {
+    if (started.status === 'fulfilled' && mic.status === 'fulfilled') {
+      live.close = mic.value;
+      return true;
+    }
+    if (mic.status === 'fulfilled') mic.value();
+    if (started.status === 'fulfilled') sendJson('POST', '/api/voice/stream/cancel').catch(() => {});
+    if (started.status === 'rejected' && started.reason.status !== 501) throw started.reason;
+    voiceStream = false;
+    return false;
+  });
+  live.finish = async () => {
+    live.close();
+    sendAudio(live);
+    await live.queue;
+    return sendJson('POST', heard('/api/voice/stream/finish'));
+  };
+  live.cancel = async () => {
+    live.close();
+    await live.queue;
+    await sendJson('POST', '/api/voice/stream/cancel');
+  };
+  return live;
+}
+
+const SpeechRec = window.SpeechRecognition || window.webkitSpeechRecognition;
+
+// voice.provider 'browser': the browser's speech recognition hears the mic, and the hub gets only
+// the text. One text post in flight at a time; a newer result waits for it and replaces older ones.
+function startBrowserLive() {
+  if (!SpeechRec) throw new Error('This browser has no speech recognition. Use Chrome or Edge, or install Hex.');
+  const rec = new SpeechRec();
+  const live = { opened: false, sent: '', text: '', error: null, posting: null, ready: Promise.resolve(true) };
+  rec.lang = navigator.language;
+  rec.interimResults = true;
+  rec.continuous = true;
+  live.ended = new Promise((resolve) => (rec.onend = resolve));
+  rec.onerror = (e) => (live.error = e.error);
+  rec.onresult = (e) => {
+    live.text = Array.from(e.results, (r) => r[0].transcript).join('');
+    postText(live);
+  };
+  const settle = async () => {
+    while (live.posting) await live.posting;
+  };
+  live.finish = async () => {
+    rec.stop();
+    await live.ended;
+    await settle();
+    if (!live.text && ['not-allowed', 'service-not-allowed', 'network', 'audio-capture'].includes(live.error)) {
+      throw new Error(`Speech recognition: ${live.error}`);
+    }
+    return sendJson('POST', heard('/api/voice/text'), { text: live.text, final: true });
+  };
+  live.cancel = async () => {
+    rec.abort();
+    await settle();
+  };
+  rec.start();
+  return live;
+}
+
+function postText(live) {
+  if (live.posting) return;
+  const text = live.text;
+  live.posting = sendJson('POST', heard('/api/voice/text'), { text })
+    .then((r) => showLive(live, r))
+    .catch(() => {})
+    .finally(() => {
+      live.posting = null;
+      if (live.text !== text) postText(live);
+    });
+}
+
+// Posts run one at a time, so the provider gets the audio in order.
+function sendAudio(live) {
+  if (!live.len) return;
+  const pcm = new Float32Array(live.len);
+  let at = 0;
+  for (const b of live.buf) {
+    pcm.set(b, at);
+    at += b.length;
+  }
+  live.buf = [];
+  live.len = 0;
+  live.queue = live.queue
+    .then(() =>
+      fetch(heard('/api/voice/stream/audio'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/octet-stream' },
+        body: pcm.buffer,
+      }),
+    )
+    .then((res) => res.json())
+    .then((r) => r.ok && showLive(live, r))
+    .catch(() => {});
+}
+
+function invokeVoice(action, params) {
+  onInvoke({ id: 'voice', action, params }, (r) => {
+    if (!r.ok) showErrorToast('Voice', new Error(`${action} failed: ${r.reason}`));
+  });
+}
+
+const canLive = () => Object.hasOwn(actions, 'session.live');
+// The server matches only the actions of the tab the hold started on.
+const heard = (path) => `${path}?app=${encodeURIComponent(voice.app)}`;
+const isDraft = (command) => command?.action === 'session.paste';
+
+// Words typed into the terminal before a phrase was heard come back out of its input box.
+function clearTyped(live) {
+  if (live.sent) invokeVoice('session.live', { text: '', final: 'true', cancel: 'true' });
+  live.sent = '';
+}
+
+// "new session" opens the dialog at once; the words after it, or any other words, show in Kanban as they come.
+function openOnce(live, newSession) {
+  if (!newSession || live.opened) return;
+  live.opened = true;
+  clearTyped(live);
+  invokeVoice('session.new', {});
+}
+
+// A command row with `live` names a dialog its app fills as the user speaks: the dialog opens on the
+// phrase and takes the command's params live, and the last call carries the final params.
+const dialogFor = (action) => {
+  const dialog = voiceCommands.find((c) => c.action === action)?.live?.action;
+  return dialog && Object.hasOwn(actions, dialog) ? dialog : null;
+};
+
+function fillDialog(live, dialog, params = {}) {
+  const sent = JSON.stringify(params);
+  if (live.dialogSent === sent) return;
+  live.dialog = dialog;
+  live.dialogSent = sent;
+  invokeVoice(dialog, params);
+}
+
+function showLive(live, { text, newSession, command, action, params }) {
+  if (!canLive() || voice.live !== live || voice.state !== 'listening') return;
+  openOnce(live, newSession);
+  live.helpOnly = command === 'Hub' && !text;
+  const marked = newSession ? 'session.new' : command ? action : text && 'session.paste';
+  if (marked !== live.marked) markVoiceHelp(marked);
+  live.marked = marked;
+  if (command) {
+    clearTyped(live);
+    const dialog = dialogFor(action);
+    if (dialog) fillDialog(live, dialog, params);
+    const pill = text && !dialog ? `${command}: ${text}` : command;
+    if (pill !== live.pill) voicePill(pill, true);
+    live.pill = pill;
+    return;
+  }
+  if (!live.opened && !voice.drafts) return;
+  if (text === live.sent) return;
+  live.sent = text;
+  invokeVoice('session.live', { text });
+}
+
+async function finishLive(live) {
+  // The final params can wait on a model (a task title), so the dialog shows it is busy.
+  if (live.dialog) invokeVoice(live.dialog, { pending: 'true' });
+  const r = await live.finish();
+  if (!canLive()) return runVoiceCommand(r);
+  if (live.dialog) return finishDialog(live, r);
+  openOnce(live, r.newSession);
+  if (!live.opened && !isDraft(r.command)) {
+    clearTyped(live);
+    return runVoiceCommand(r);
+  }
+  hideVoiceHelp();
+  invokeVoice('session.live', { text: r.text, final: 'true', submit: String(voice.send && !live.opened) });
+  if (live.opened) flashPill('New session');
+  else hideVoicePill();
+}
+
+// The dialog stays open with the final params for the user to review; Enter during the hold saves it.
+function finishDialog(live, r) {
+  const c = r.command;
+  if (c?.kind === 'invoke' && dialogFor(c.action) === live.dialog) {
+    hideVoiceHelp();
+    invokeVoice(live.dialog, { ...c.params, final: 'true', submit: String(voice.send) });
+    return flashPill(c.label);
+  }
+  invokeVoice(live.dialog, { final: 'true', cancel: 'true' });
+  return runVoiceCommand(r);
+}
+
+function flashPill(text) {
+  voicePill(text);
+  hideVoicePill(1500);
+}
+
+function voiceDown() {
+  if (voice.state !== 'idle') return;
+  voice.drafts = handledHere('session.paste');
+  if (!voice.drafts && !voiceRowsHere().length) return flashPill(`No voice commands on ${tabName()}`);
+  voice.state = 'listening';
+  voice.send = false;
+  voice.app = activeApp;
+  showVoiceHelp();
+  const active = document.activeElement;
+  voice.frame = active?.tagName === 'IFRAME' ? active : null;
+  voicePill('Listening', true).focus();
+  if (voiceInBrowser()) {
+    voice.started = null;
+    try {
+      voice.live = startBrowserLive();
+    } catch (err) {
+      voice.started = err;
+    }
+    return;
+  }
+  voice.live = voiceStream ? startLive() : null;
+  const cli = () => {
+    voice.started = sendJson('POST', '/api/voice/start').catch((err) => err);
+  };
+  if (voice.live)
+    voice.live.ready.then(
+      (ok) => ok || cli(),
+      () => {},
+    );
+  else cli();
+}
+
+async function voiceUp() {
+  if (voice.state !== 'listening') return;
+  voice.state = 'working';
+  voice.frame?.focus();
+  voice.frame = null;
+  voicePill('…');
+  const live = voice.live;
+  try {
+    if (live && (await live.ready)) return await finishLive(live);
+    const started = await voice.started;
+    if (started instanceof Error) throw started;
+    runVoiceCommand(await sendJson('POST', heard('/api/voice/stop')));
+  } catch (err) {
+    hideVoicePill();
+    hideVoiceHelp();
+    showErrorToast('Voice', err);
+    // Ends Kanban's live text, keeping the words, so the next hold does not erase from a stale start.
+    if (live?.sent && canLive()) invokeVoice('session.live', { text: live.sent, final: 'true', submit: 'false' });
+    if (live?.dialog) invokeVoice(live.dialog, { final: 'true' });
+  } finally {
+    voice.live = null;
+    voice.state = 'idle';
+  }
+}
+
+function runVoiceCommand({ text, command = {} }) {
+  hideVoiceHelp();
+  if (command.kind === 'none') return flashPill('No speech');
+  if (command.kind === 'invoke') {
+    const draft = isDraft(command);
+    invokeVoice(command.action, draft ? { ...command.params, submit: String(voice.send) } : command.params);
+    // A paste shows in the session, or in Kanban's copy toast, so the pill does not repeat the text.
+    return command.label ? flashPill(command.label) : hideVoicePill();
+  }
+  hideVoicePill();
+  // "Hub" alone asks what to say: the panel stays a while in place of the toast.
+  if (voice.live?.helpOnly) return hideVoiceHelp(VOICE_HELP_LINGER_MS);
+  showErrorToast("Didn't get that", new Error(`“${text}”`));
+}
+
+// `voice.dictate`, the one action the hub handles itself: an app's mic gets the provider's text with no command.
+const DICTATE = 'voice.dictate';
+// With the browser provider an app's mic runs its own browser speech, so the hub does not offer it.
+const hubDictates = () => voiceOn && !voiceInBrowser();
+
+async function dictate(op, reply) {
+  const busy = op === 'start' ? voice.state !== 'idle' : voice.state !== 'dictating';
+  if (busy || !['start', 'stop', 'cancel'].includes(op)) return reply({ ok: false, reason: 'busy' });
+  try {
+    if (op === 'start') {
+      voice.state = 'dictating';
+      voicePill('Dictating', true);
+      voice.dictating = sendJson('POST', '/api/voice/start');
+      await voice.dictating;
+      return reply({ ok: true });
+    }
+    voice.state = 'idle';
+    hideVoicePill();
+    await voice.dictating?.catch(() => {});
+    const r = await sendJson('POST', `/api/voice/${op === 'stop' ? 'dictate' : 'cancel'}`);
+    reply({ ok: true, text: r.text ?? '' });
+  } catch (err) {
+    voice.state = 'idle';
+    hideVoicePill();
+    reply({ ok: false, reason: err.message });
+  }
+}
+
+// Backspace mid-hold drops the recording and what it typed. The state stays 'cancelled' until the
+// release, so the held key's auto-repeat does not start a new hold.
+async function voiceCancel() {
+  voice.state = 'cancelled';
+  const live = voice.live;
+  voice.live = null;
+  flashPill('Cancelled');
+  hideVoiceHelp();
+  try {
+    if (live && (await live.ready)) {
+      await live.cancel();
+      if (canLive() && (live.sent || live.opened)) {
+        invokeVoice('session.live', { text: '', final: 'true', cancel: live.opened ? 'close' : 'true' });
+      }
+      if (live.dialog) invokeVoice(live.dialog, { final: 'true', cancel: 'true' });
+    } else {
+      await voice.started;
+      await sendJson('POST', '/api/voice/cancel');
+    }
+  } catch {}
+}
+
+// The hold ends when any key of the hub.voice combo comes up, the user's combo included.
+function releasesVoice(e) {
+  const combo = Object.values(bindings()).find((b) => b.id === 'hub.voice')?.combo ?? 'ctrl+shift+Space';
+  const parts = combo.split('+');
+  const mod = { Control: 'ctrl', Alt: 'alt', Shift: 'shift', Meta: 'meta' }[e.key];
+  return mod ? parts.includes(mod) : comboOf({ key: e.key, code: e.code }) === parts.at(-1);
+}
+
+function listenVoiceRelease() {
+  document.addEventListener('keydown', (e) => {
+    if (voice.state !== 'listening') return;
+    if (e.key === 'Enter') {
+      e.preventDefault();
+      voice.send = true;
+      voicePill('Listening · sends on release', true);
+      return;
+    }
+    if (e.key !== 'Backspace') return;
+    e.preventDefault();
+    voice.cancelling = voiceCancel();
+  });
+  document.addEventListener('keyup', (e) => {
+    if (!releasesVoice(e)) return;
+    if (voice.state === 'cancelled') endCancelledHold();
+    else voiceUp();
+  });
+  window.addEventListener('blur', () => {
+    // A frame that takes focus mid-hold (Kanban's New session dialog) would get the release.
+    const held = voice.state === 'listening' || voice.state === 'cancelled';
+    if (held && document.activeElement?.tagName === 'IFRAME') {
+      setTimeout(() => document.getElementById('voice-pill').focus());
+      return;
+    }
+    if (voice.state === 'cancelled') return endCancelledHold();
+    voiceUp();
+  });
+}
+
+// A new hold waits for the cancel to finish, or its late stream/cancel would end the new stream.
+// Idle before the frame takes focus, so the blur handler does not treat the hold as still held.
+async function endCancelledHold() {
+  const frame = voice.frame;
+  voice.frame = null;
+  await voice.cancelling;
+  if (voice.state !== 'cancelled') return;
+  voice.state = 'idle';
+  frame?.focus();
+}
+
 function bindErrorToast() {
   document.getElementById('error-close').addEventListener('click', hideErrorToast);
   document.getElementById('error-reload').addEventListener('click', () => location.reload());
@@ -558,7 +1069,7 @@ function welcomeFor(data, appId) {
     forward: Object.keys(bindings()),
     keys: actionKeys(),
     themes: hubThemes,
-    actions: Object.keys(actions),
+    actions: [...Object.keys(actions), ...(hubDictates() ? [DICTATE] : [])],
     origins: Object.keys(apps).map(originOf),
     settings: apps[appId]?.settings ?? {},
   };
@@ -621,6 +1132,7 @@ function fillUrl(template, params) {
 function onInvoke({ id, action, params = {}, open }, send) {
   if (typeof id !== 'string') return;
   const reply = (result) => send({ type: 'hub:result', id, ...result });
+  if (action === DICTATE && hubDictates()) return dictate(params.op, reply);
   const spec = typeof action === 'string' && Object.hasOwn(actions, action) ? actions[action] : null;
   if (!spec) return reply({ ok: false, reason: 'unhandled' });
   if (badParams(spec.params, params)) return reply({ ok: false, reason: 'bad-params' });
@@ -628,7 +1140,10 @@ function onInvoke({ id, action, params = {}, open }, send) {
   const url = template && fillUrl(template, params);
   const paneSrc = open === 'pane' && url && srcOnOrigin(handler, apps[handler].url + url);
   if (paneSrc) return reply({ ok: true, handledBy: handler, url: paneSrc });
-  switchTab(handler);
+  // Not again for the app on screen: switchTab focuses the frame and tells the app it is active,
+  // which repaints Kanban's terminal, and voice sends several actions a second.
+  if (handler !== activeApp) switchTab(handler);
+  else if (id !== 'voice') iframes[handler]?.focus();
   if (mode === 'message' && liveApps.has(handler)) {
     postTo(handler, { type: 'hub:action', id, action, params });
   } else if (url && !guardedApps.has(handler)) {
@@ -768,6 +1283,7 @@ function hubActions() {
       run: (i) => switchTab(tabIds()[i]),
       count: 9,
     },
+    { id: 'hub.voice', combo: 'ctrl+shift+Space', off: !voiceOn, run: () => voiceDown() },
   ];
 }
 
@@ -781,7 +1297,7 @@ function bindings() {
   const own = (b) => Object.hasOwn(userKeys, b.id);
   const expand = (action) => {
     const combo = comboFor(action);
-    if (!combo) return [];
+    if (!combo || action.off) return [];
     if (!action.count) return [[combo, { ...action, combo }]];
     return Array.from({ length: Math.min(action.count, tabs) }, (_, i) => {
       const c = combo.replace('{n}', i + 1);

package/public/index.html

@@ -524,6 +524,78 @@
     }
 
     .update-toast[hidden] { display: none; }
+    .voice-pill {
+      position: fixed;
+      left: 50%;
+      bottom: 16px;
+      z-index: 30;
+      transform: translateX(-50%);
+      padding: 6px 14px;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 999px;
+      box-shadow: 0 6px 20px var(--shadow);
+      color: var(--text);
+      font: 13px ui-monospace, SFMono-Regular, Menlo, monospace;
+      outline: none;
+    }
+    .voice-pill[hidden] { display: none; }
+    .voice-pill.listening::before { content: '● '; color: #e5484d; }
+    .voice-help {
+      position: fixed;
+      right: 16px;
+      bottom: 16px;
+      z-index: 30;
+      width: min(360px, calc(100vw - 32px));
+      overflow: hidden;
+      background: var(--surface);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      box-shadow: 0 12px 36px var(--shadow);
+      color: var(--text);
+      font: 13px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
+      animation: voice-help-in 0.16s ease-out;
+    }
+    @keyframes voice-help-in { from { opacity: 0; transform: translateX(12px); } }
+    .voice-help[hidden] { display: none; }
+    .voice-help-title {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 10px 14px;
+      border-bottom: 1px solid var(--border);
+      font-weight: 600;
+    }
+    .voice-help-title::before {
+      content: '';
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+      background: #e5484d;
+      animation: voice-help-dot 1.4s ease-in-out infinite;
+    }
+    @keyframes voice-help-dot { 50% { opacity: 0.35; } }
+    .voice-help-rows { display: grid; padding: 4px 0; }
+    .voice-help-row {
+      display: grid;
+      padding: 8px 14px;
+      transition: background-color 0.15s, box-shadow 0.15s;
+    }
+    .voice-help-row + .voice-help-row { border-top: 1px dashed var(--border); }
+    .voice-help-row.on {
+      background: color-mix(in srgb, var(--accent) 12%, transparent);
+      box-shadow: inset 3px 0 0 var(--accent);
+    }
+    .voice-help-row > *, .voice-help-tip { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+    .voice-help-row .say { color: var(--accent); }
+    .voice-help-row.other .say { color: var(--text); }
+    .voice-help-row .say i { color: var(--text-dim); font-style: normal; }
+    .voice-help-row .what { color: var(--text-dim); font-size: 12px; }
+    .voice-help-tip { padding: 8px 14px; background: var(--bg); border-top: 1px solid var(--border); color: var(--text-dim); font-size: 12px; }
+    @media (prefers-reduced-motion: reduce) {
+      .voice-help, .voice-help-title::before { animation: none; }
+      .voice-help-row { transition: none; }
+    }
     .update-toast.leaving { opacity: 0; transform: translateY(8px); }
     .update-toast-body { flex: 1; min-width: 0; }
     .update-toast-title { font-weight: 600; font-size: 15px; }
@@ -649,6 +721,23 @@
     <button class="update-toast-close" id="error-close" type="button" aria-label="Close">×</button>
   </div>
 
+  <div class="update-toast" id="voice-note" role="status" hidden>
+    <div class="update-toast-body">
+      <div class="update-toast-title">Voice uses the browser's speech recognition</div>
+      <div class="update-toast-meta">Hex is not installed, so the browser turns your speech into text. It sends the audio to an online service while you hold the keys. Install <a href="https://anoma.ly/hex" target="_blank" rel="noopener">Hex</a> to keep it on your machine.</div>
+      <div class="update-toast-actions">
+        <button class="update-toast-skip" id="voice-note-ok" type="button">Got it</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="voice-pill" id="voice-pill" tabindex="-1" role="status" hidden></div>
+  <div class="voice-help" id="voice-help" role="status" hidden>
+    <div class="voice-help-title" id="voice-help-title">What you can say</div>
+    <div class="voice-help-rows" id="voice-help-rows"></div>
+    <div class="voice-help-tip" id="voice-help-tip"></div>
+  </div>
+
   <script src="/sdk/keys.js"></script>
   <script src="/app.js"></script>
 </body>