hop2 0.11.2 → 0.11.3

package/README.md

@@ -199,7 +199,13 @@ The attached-terminal UI adapts light/dark themes to your terminal and puts the
 
 ### Use Hop on Mobile
 
-Hop’s mobile UI includes:
+**Native iOS app**: [hop-ios](https://github.com/jzthree/hop-ios) — a SwiftUI
+client for iPhone with a real terminal (SwiftTerm), optimistic-echo typing,
+bell notifications with lock-screen reply, Siri/Shortcuts/Spotlight/Handoff
+integration, and a fixed-height terminal keyboard. It consumes hop's public
+HTTP + WebSocket API and needs no changes to hop.
+
+Hop’s mobile **web** UI includes:
 
 - a terminal-oriented accessory row with `Esc`, `Tab`, `Ctrl`, `Alt`, and arrows
 - a native keyboard button for dictation, spellcheck, and autocomplete

package/hay/apps/web/src/App.tsx

@@ -13,6 +13,7 @@ import { activityLabel, sortPresence } from "./utils/presence";
 import { createOptimisticEcho } from "./utils/optimisticEcho";
 import { attachScrollFlywheel } from "./utils/scrollFlywheel";
 import { collectTerminalMatches, selectTerminalMatch } from "./utils/terminalSearch";
+import { createVoiceHold, speechRecognitionCtor } from "./utils/voiceHold";
 import { scanKeyboardProtocol } from "./utils/keyboardProtocol";
 import { originalPathHint } from "./utils/fileDrop";
 import { MobileKeyboard } from "./components/MobileKeyboard";
@@ -518,6 +519,10 @@ const App = () => {
   const shouldReconnectRef = useRef(true);
   const connectNonceRef = useRef(0);
   const userScrolledUpRef = useRef(false);
+  // Late-bound hooks for the voice controller (created before these exist).
+  const handleUserInputRef = useRef<((data: string) => void) | null>(null);
+  const pushNoticeRef = useRef<((m: string) => void) | null>(null);
+  const foregroundIsClaudeRef = useRef<(() => boolean) | null>(null);
   // Custom overlay scrollbar (native overlay bars can't be styled, and styled
   // webkit bars reserve layout width): a floating semi-transparent thumb.
   const termScrollbarRef = useRef<HTMLDivElement | null>(null);
@@ -562,13 +567,44 @@ const App = () => {
   // Claude Code titles its process with a bare version number; hop's session
   // poll surfaces it as foregroundProcess. Used to unlock claude-specific key
   // encodings (Shift+Enter) without protocol negotiation.
+  // Is Claude Code the thing on screen? The foreground PROCESS cannot answer
+  // alone: a session relaunched by `hop restore` runs
+  // `shell -lc "claude ...; exec shell -l"`, so the room reports the WRAPPER
+  // SHELL for claude's whole life. Everything gated on this — Shift+Enter as
+  // a newline, hold-space voice — silently stopped working in exactly the
+  // sessions a restore brought back, which is why voice "does not always
+  // work". The screen is the honest witness, so fall back to claude's own
+  // chrome in the buffer (cached ~1s, since key handlers ask per keystroke).
+  const claudeScreenRef = useRef<{ at: number; value: boolean }>({ at: 0, value: false });
+  const screenLooksLikeClaude = () => {
+    const now = performance.now();
+    if (now - claudeScreenRef.current.at < 1000) return claudeScreenRef.current.value;
+    let value = false;
+    const t = termRef.current;
+    if (t) {
+      try {
+        const buf = t.buffer.active;
+        const end = buf.baseY + t.rows;
+        let text = "";
+        for (let i = Math.max(0, end - 30); i < end; i++) {
+          text += (buf.getLine(i)?.translateToString(true) ?? "") + "\n";
+        }
+        value = /bypass permissions on|shift\+tab to cycle|esc to interrupt|\? for shortcuts/i.test(text);
+      } catch { /* disposed mid-read */ }
+    }
+    claudeScreenRef.current = { at: now, value };
+    return value;
+  };
   const foregroundIsClaude = () => {
     const room = activeSessionRoomRef.current;
-    if (!room) return false;
-    const s = sessionsRef.current.find((x) => (x.internalName || x.name) === room);
-    const proc = (s?.foregroundProcess || "").trim();
-    return proc === "claude" || /^\d+\.\d+\.\d+$/.test(proc);
+    if (room) {
+      const s = sessionsRef.current.find((x) => (x.internalName || x.name) === room);
+      const proc = (s?.foregroundProcess || "").trim();
+      if (proc === "claude" || /^\d+\.\d+\.\d+$/.test(proc)) return true;
+    }
+    return screenLooksLikeClaude();
   };
+  foregroundIsClaudeRef.current = foregroundIsClaude;
   const drawerOpenRef = useRef(drawerOpen);
   drawerOpenRef.current = drawerOpen;
   const shortcutHelpRef = useRef(shortcutHelpOpen);
@@ -723,6 +759,7 @@ const App = () => {
     }, 3000);
   };
 
+  pushNoticeRef.current = pushNotice;
   const showToast = (message: string, durationMs = 2000) => {
     setToast(message);
     if (toastTimeout.current) {
@@ -953,78 +990,18 @@ const App = () => {
   };
 
   // ── Voice input: hold SPACE in a Claude session to dictate. ──
-  // Browser SpeechRecognition (Chrome + Safari; where absent, space behaves
-  // normally). The first press types its space instantly — no latency on the
-  // most common key; crossing the hold threshold erases that space and
-  // listens until release. The transcript is TYPED, not submitted: you can
-  // edit before Enter. Auto-repeat spaces are swallowed while held, which in
-  // a Claude composer is noise nobody wants anyway.
-  const voiceTimerRef = useRef(0);
-  const voiceActiveRef = useRef(false);
-  const voiceRecRef = useRef<{ stop: () => void } | null>(null);
-  const voiceFinalRef = useRef("");
-  const voiceInterimRef = useRef("");
+  // Shared controller (utils/voiceHold) — the live wall tiles run the same
+  // machine, so dictation exists on every surface a Claude composer does.
   const [voiceOverlay, setVoiceOverlay] = useState<{ interim: string } | null>(null);
-  const speechRecognitionCtor = () =>
-    (window as unknown as { SpeechRecognition?: unknown; webkitSpeechRecognition?: unknown }).SpeechRecognition
-    || (window as unknown as { webkitSpeechRecognition?: unknown }).webkitSpeechRecognition;
-  const finishVoiceInput = (send: boolean) => {
-    if (!voiceActiveRef.current) return;
-    voiceActiveRef.current = false;
-    voiceRecRef.current = null;
-    setVoiceOverlay(null);
-    // Engines usually finalize pending speech on stop(); if only an interim
-    // result ever arrived, it is still what the user said — use it.
-    const text = (voiceFinalRef.current || voiceInterimRef.current).trim();
-    voiceFinalRef.current = "";
-    voiceInterimRef.current = "";
-    if (send && text) handleUserInput(text);
-  };
-  const startVoiceInput = () => {
-    if (voiceActiveRef.current) return;
-    const Ctor = speechRecognitionCtor() as (new () => never) | undefined;
-    if (!Ctor) return;
-    let rec: never;
-    try { rec = new Ctor(); } catch { return; }
-    const r = rec as {
-      lang: string; continuous: boolean; interimResults: boolean;
-      onresult: (ev: { resultIndex: number; results: ArrayLike<{ isFinal: boolean; 0: { transcript: string } }> }) => void;
-      onerror: (ev: { error?: string }) => void; onend: () => void;
-      start: () => void; stop: () => void;
-    };
-    voiceActiveRef.current = true;
-    voiceFinalRef.current = "";
-    voiceInterimRef.current = "";
-    handleUserInput(""); // erase the space the initial press typed
-    r.lang = navigator.language || "en-US";
-    r.continuous = true;
-    r.interimResults = true;
-    r.onresult = (ev) => {
-      let interim = "";
-      for (let i = ev.resultIndex; i < ev.results.length; i++) {
-        const res = ev.results[i];
-        if (res.isFinal) voiceFinalRef.current += res[0].transcript;
-        else interim += res[0].transcript;
-      }
-      voiceInterimRef.current = interim;
-      setVoiceOverlay({ interim: (voiceFinalRef.current + interim).trim() });
-    };
-    r.onerror = (ev) => {
-      if (ev?.error === "not-allowed" || ev?.error === "service-not-allowed") {
-        pushNotice("Microphone permission needed for voice input");
-      }
-      finishVoiceInput(false);
-    };
-    r.onend = () => finishVoiceInput(true);
-    voiceRecRef.current = r;
-    setVoiceOverlay({ interim: "" });
-    try { r.start(); } catch { finishVoiceInput(false); }
-  };
-  const stopVoiceInput = () => {
-    const rec = voiceRecRef.current;
-    if (rec) { try { rec.stop(); } catch { finishVoiceInput(true); } }
-    else finishVoiceInput(true);
-  };
+  const voiceHoldRef = useRef<ReturnType<typeof createVoiceHold> | null>(null);
+  if (!voiceHoldRef.current) {
+    voiceHoldRef.current = createVoiceHold({
+      send: (data) => handleUserInputRef.current?.(data),
+      notify: (m) => pushNoticeRef.current?.(m),
+      setOverlay: (interim) => setVoiceOverlay(interim === null ? null : { interim }),
+      eligible: () => foregroundIsClaudeRef.current?.() ?? false
+    });
+  }
 
   const handleUserInput = (data: string) => {
     // Typing is "I am at the prompt": any earlier scroll-up turned
@@ -1105,6 +1082,7 @@ const App = () => {
 
   // One-shot: armed when a snapshot loads (fresh session open/switch), consumed
   // by the next resize so it goes out as an attach claim.
+  handleUserInputRef.current = handleUserInput;
   const attachClaimPendingRef = useRef(false);
   // Throttle gate for fit-on-type (one fit per typing burst, not per key).
   const lastTypeFitAtRef = useRef(0);
@@ -1772,32 +1750,10 @@ const App = () => {
         }
         return false;
       }
-      // Long-press SPACE = voice input (Claude sessions, when the browser has
-      // SpeechRecognition). First press types its space with zero latency;
-      // holding past the threshold erases it and dictates until release.
-      if (event.code === 'Space' && !event.metaKey && !event.ctrlKey && !event.altKey && !event.shiftKey
-          && foregroundIsClaude() && !!speechRecognitionCtor()) {
-        if (event.type === 'keydown') {
-          if (!event.repeat) {
-            window.clearTimeout(voiceTimerRef.current);
-            voiceTimerRef.current = window.setTimeout(startVoiceInput, 550);
-            return true;
-          }
-          return false; // swallow auto-repeat while held
-        }
-        if (event.type === 'keyup') {
-          window.clearTimeout(voiceTimerRef.current);
-          if (voiceActiveRef.current) {
-            stopVoiceInput();
-            return false;
-          }
-          return true;
-        }
-      }
-      // Any other keydown cancels a pending (not yet active) voice hold —
-      // normal typing must never trip the mic.
-      if (event.type === 'keydown' && event.code !== 'Space') {
-        window.clearTimeout(voiceTimerRef.current);
+      // Long-press SPACE = voice input — shared controller; see voiceHold.ts.
+      {
+        const verdict = voiceHoldRef.current?.handleKey(event);
+        if (verdict !== undefined) return verdict;
       }
       // Shift+Enter: xterm.js would emit a plain \r (indistinguishable from
       // Enter), which apps like Claude Code treat as "submit". Synthesize the

package/hay/apps/web/src/components/SessionSwitcher.tsx

@@ -15,6 +15,7 @@ import { WebglAddon } from "@xterm/addon-webgl";
 import { attachScrollFlywheel } from "../utils/scrollFlywheel";
 import { ContextMenu, type MenuRequest } from "./ContextMenu";
 import { collectTerminalMatches, selectTerminalMatch } from "../utils/terminalSearch";
+import { bufferLooksLikeClaude, createVoiceHold } from "../utils/voiceHold";
 import {
   buildSwitcherModel,
   filterSessionsByOrigin,
@@ -270,10 +271,10 @@ const runningApp = (s: SwitcherSession) => {
 // responsiveness and whether keystrokes are accepted. The old design — an
 // HTML preview swapped for a fresh xterm + socket behind a veil — is gone.
 const LIVETILE_POLL_MS = 5000;
-const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, activeCols, activeRows, onFullscreen, onUnfocus }: {
+const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, activeCols, activeRows, onFullscreen, onUnfocus, onNotice }: {
   wsBase: string; room: string; userName: string; theme: object | undefined;
   live: boolean; claudeApp: boolean; claimSize: boolean; activeCols?: number; activeRows?: number;
-  onFullscreen: () => void; onUnfocus: () => void;
+  onFullscreen: () => void; onUnfocus: () => void; onNotice: (m: string) => void;
 }) => {
   const boxRef = useRef<HTMLDivElement | null>(null);
   const termRef = useRef<Terminal | null>(null);
@@ -284,6 +285,24 @@ const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, a
   const kbdEnhancedRef = useRef(false);
   // null = watching; "live"/"down" = connected state for the chrome.
   const [conn, setConn] = useState<"live" | "down" | null>(null);
+  // Hold-space voice, same controller as the full screen — the tile is where
+  // typing mostly happens now, and dictation not existing here was most of
+  // "voice doesn't always work".
+  const [voiceInterim, setVoiceInterim] = useState<string | null>(null);
+  const voiceHoldRef = useRef<ReturnType<typeof createVoiceHold> | null>(null);
+  if (!voiceHoldRef.current) {
+    voiceHoldRef.current = createVoiceHold({
+      send: (data) => sendInputRef.current?.(data),
+      notify: (m) => onNoticeRef.current?.(m),
+      setOverlay: setVoiceInterim,
+      eligible: () => {
+        if (claudeAppRef.current) return true;
+        const t = termRef.current;
+        return !!t && bufferLooksLikeClaude(t as never);
+      }
+    });
+  }
+
   // In-tile find (⌘F while the tile is live): same engine as the full-screen
   // find bar. Scope follows focus — ⌘F in a live tile searches THIS session;
   // ⌘F anywhere else is the wall filter, which finds sessions.
@@ -319,6 +338,8 @@ const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, a
   const myIdRef = useRef<string | null>(null);
   const [viewers, setViewers] = useState<Array<{ name: string }>>([]);
   const [driver, setDriver] = useState<{ name: string; color: string } | null>(null);
+  const onNoticeRef = useRef(onNotice);
+  onNoticeRef.current = onNotice;
   const claudeAppRef = useRef(claudeApp);
   claudeAppRef.current = claudeApp;
   const liveRef = useRef(live);
@@ -407,6 +428,10 @@ const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, a
     // Keys route through refs so the handler survives mode flips untouched.
     term.attachCustomKeyEventHandler((ev) => {
       if (!liveRef.current) return false; // watching: the terminal takes no keys
+      {
+        const verdict = voiceHoldRef.current?.handleKey(ev);
+        if (verdict !== undefined) return verdict;
+      }
       if ((ev.metaKey || ev.ctrlKey) && !ev.altKey && !ev.shiftKey && ev.key.toLowerCase() === "f") {
         // Scope follows focus: find in THIS terminal. (The wall filter stays
         // one ⌘K away; ⌘. still unfocuses the tile.)
@@ -752,6 +777,7 @@ const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, a
       setConn(null);
       setViewers([]);
       setDriver(null);
+      voiceHoldRef.current?.dispose();
       setFind(null);
       findIndexRef.current = -1;
       term.blur();
@@ -770,6 +796,14 @@ const LiveTile = ({ wsBase, room, userName, theme, live, claudeApp, claimSize, a
       onPointerDown={live ? (e) => e.stopPropagation() : undefined}
     >
       <div className="switcher-focus-term" ref={boxRef} />
+      {voiceInterim !== null && (
+        <div className="voice-overlay" aria-hidden="true">
+          <span className="voice-dot" />
+          <span className={voiceInterim ? "voice-text" : "voice-text muted"}>
+            {voiceInterim || "Listening… release Space to insert"}
+          </span>
+        </div>
+      )}
       {live && (
         <div className="switcher-live-chrome" onClick={(e) => e.stopPropagation()}>
           <span className={"switcher-focus-label" + (conn === "down" ? " down" : "")}>
@@ -1495,6 +1529,30 @@ export const SessionSwitcher = ({
         body: JSON.stringify({ internalName: sessionKey(session), parked: false })
       }).catch(() => { /* daemon will still show it parked; harmless */ });
     }
+    // A DEAD terminal session starts IN PLACE instead of falling through to
+    // full screen — the last accidental door into the mode. Attaching is what
+    // starts a known session, so a claim-free throwaway socket kicks it
+    // alive; the tile is pre-focused and goes live the moment the session
+    // reports active. Ports still open full screen (they are web pages), and
+    // without live tiles (no wsBase / small zoom) the old switch stands.
+    if (session.type !== "port" && !session.active && interactiveTiles && tileWsBase) {
+      const key = sessionKey(session);
+      try {
+        const sep = tileWsBase.includes("?") ? "&" : "?";
+        const kick = new WebSocket(
+          tileWsBase + sep + "room=" + encodeURIComponent(key)
+          + "&name=" + encodeURIComponent((userName || "user") + " (start)")
+          + "&replay=0&nudge=0&cols=80&rows=24"
+        );
+        kick.onopen = () => { window.setTimeout(() => { try { kick.close(); } catch { /* done */ } }, 400); };
+        kick.onerror = () => { try { kick.close(); } catch { /* refused */ } };
+      } catch { /* daemon will surface it as starting on the next poll */ }
+      onNotice("Starting " + (session.displayName || session.name) + "…");
+      setFocusedKey(key);
+      onFocusSession?.(session);
+      onRefresh();
+      return;
+    }
     onSwitch(session);
   };
 
@@ -1840,8 +1898,8 @@ export const SessionSwitcher = ({
       setCreating(false);
       setCreateDraft("");
       if (createInFolder) {
-        // File it before switching: reuses the move endpoint, which is the
-        // one place membership is persisted durably.
+        // File it first: the move endpoint is the one place membership is
+        // persisted durably.
         await fetch("/api/sessions/move", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
@@ -1849,7 +1907,13 @@ export const SessionSwitcher = ({
         }).catch(() => { /* filing is best-effort; the session exists */ });
         setCreateInFolder(null);
       }
-      onSwitch({ name: data.name, displayName: data.name, active: false, starting: true, internalName: data.name });
+      // Stay on the wall. Creating used to jump straight to full screen —
+      // the exact accidental mode-entry the hotkey inversion removed from
+      // clicks. The new tile becomes current and goes live in place as soon
+      // as the session reports active.
+      onFocusSession?.({ name: data.name, displayName: data.name, active: false, starting: true, internalName: data.name });
+      setFocusedKey(data.name);
+      onRefresh();
     } catch {
       onNotice("Failed to create session");
     }
@@ -2016,6 +2080,7 @@ export const SessionSwitcher = ({
               activeRows={preview?.rows}
               onFullscreen={() => onSwitch(s)}
               onUnfocus={() => setFocusedKey(null)}
+              onNotice={onNotice}
             />
           </div>
         ) : (
@@ -2235,10 +2300,10 @@ export const SessionSwitcher = ({
         </div>
         {/* Create form lives in the top bar so the header ＋ works from EVERY
             mode — the dashed grid card only exists in recent mode. */}
-        {creating && (
+        {creating && !createInFolder && (
           <form className="switcher-create-row inline-edit" onSubmit={submitCreate}>
             <input
-              placeholder={createInFolder ? "new session in " + createInFolder.name : "session-name"}
+              placeholder="session-name"
               value={createDraft}
               onChange={(e) => setCreateDraft(e.target.value)}
               maxLength={64}
@@ -2331,8 +2396,22 @@ export const SessionSwitcher = ({
                       <button type="button" onClick={() => renameFolder(folder)} title="Rename folder">✎</button>
                       <button type="button" onClick={() => deleteFolder(folder)} title="Delete folder">🗑</button>
                     </h3>
+                    {creating && createInFolder?.id === folder.id && (
+                      <form className="switcher-create-row inline-edit switcher-create-infolder" onSubmit={submitCreate}>
+                        <input
+                          placeholder={"new session in " + folder.name}
+                          value={createDraft}
+                          onChange={(e) => setCreateDraft(e.target.value)}
+                          maxLength={64}
+                          autoFocus
+                          aria-label={"New session name in " + folder.name}
+                        />
+                        <button type="submit">Create</button>
+                        <button type="button" onClick={() => { setCreating(false); setCreateDraft(""); setCreateInFolder(null); }}>✕</button>
+                      </form>
+                    )}
                     {rows.length === 0 ? (
-                      <p className="switcher-folder-empty">Drag a session here</p>
+                      creating && createInFolder?.id === folder.id ? null : <p className="switcher-folder-empty">Drag a session here, or ＋ to create one</p>
                     ) : (
                       <div className="switcher-grid">{rows.map((s) => renderCard(s))}</div>
                     )}

package/hay/apps/web/src/styles.css

@@ -3892,3 +3892,16 @@ button.primary {
     opacity: 1;
   }
 }
+
+/* Create-in-folder: the input appears INSIDE the folder, where the session
+   will land — not up in the header bar two scrolls away from the + that
+   asked for it. */
+.switcher-folder .switcher-create-infolder {
+  margin: 4px 0 8px;
+}
+
+/* Voice overlay inside a live tile: same pill, tile-scaled. */
+.switcher-live-tile .voice-overlay {
+  bottom: 30px;
+  max-width: 86%;
+}

package/hay/apps/web/src/utils/voiceHold.ts

@@ -0,0 +1,170 @@
+// Hold-space voice dictation — ONE controller for every terminal surface.
+//
+// It lived only in the full-screen terminal, but the wall's live tiles are
+// where typing mostly happens now, so "voice doesn't always work" was often
+// simply "voice does not exist on this surface". Both surfaces now share
+// this state machine; each provides its own send/overlay/eligibility.
+//
+// Contract (unchanged from the original):
+// - the first Space keydown types its space with zero latency
+// - holding past the threshold erases the typed space(s) and listens
+// - releasing stops; the transcript is TYPED, never submitted
+// - auto-repeat spaces are swallowed; any other key cancels a pending hold
+// - while listening, every space is eaten
+
+type RecognitionLike = {
+  lang: string;
+  continuous: boolean;
+  interimResults: boolean;
+  onresult: ((ev: { resultIndex: number; results: ArrayLike<{ isFinal: boolean; 0: { transcript: string } }> }) => void) | null;
+  onerror: ((ev: { error?: string }) => void) | null;
+  onend: (() => void) | null;
+  start: () => void;
+  stop: () => void;
+};
+
+export const speechRecognitionCtor = (): (new () => RecognitionLike) | undefined =>
+  (window as unknown as { SpeechRecognition?: new () => RecognitionLike }).SpeechRecognition
+  || (window as unknown as { webkitSpeechRecognition?: new () => RecognitionLike }).webkitSpeechRecognition;
+
+export type VoiceHoldOptions = {
+  send: (data: string) => void;
+  notify: (message: string) => void;
+  /** null = hidden; string = the interim transcript ("" while warming up). */
+  setOverlay: (interim: string | null) => void;
+  /** Is the surface a Claude-ish composer right now? Checked at keydown. */
+  eligible: () => boolean;
+  thresholdMs?: number;
+};
+
+export const createVoiceHold = (opts: VoiceHoldOptions) => {
+  const threshold = opts.thresholdMs ?? 550;
+  let timer = 0;
+  let active = false;
+  let spacesTyped = 0;
+  let finalText = "";
+  let interimText = "";
+  let rec: RecognitionLike | null = null;
+
+  const finish = (sendText: boolean) => {
+    if (!active) return;
+    active = false;
+    rec = null;
+    opts.setOverlay(null);
+    const text = (finalText || interimText).trim();
+    finalText = "";
+    interimText = "";
+    if (sendText && text) opts.send(text);
+  };
+
+  const start = () => {
+    if (active) return;
+    const Ctor = speechRecognitionCtor();
+    if (!Ctor) return;
+    let r: RecognitionLike;
+    try { r = new Ctor(); } catch { return; }
+    active = true;
+    finalText = "";
+    interimText = "";
+    // Erase every space that reached the app during this hold.
+    for (let i = 0; i < Math.max(1, spacesTyped); i++) opts.send("\x7f");
+    spacesTyped = 0;
+    r.lang = navigator.language || "en-US";
+    r.continuous = true;
+    r.interimResults = true;
+    r.onresult = (ev) => {
+      let interim = "";
+      for (let i = ev.resultIndex; i < ev.results.length; i++) {
+        const res = ev.results[i];
+        if (res.isFinal) finalText += res[0].transcript;
+        else interim += res[0].transcript;
+      }
+      interimText = interim;
+      opts.setOverlay((finalText + interim).trim());
+    };
+    r.onerror = (ev) => {
+      // EVERY failure explains itself. Only mic-denial was surfaced before;
+      // Chrome's cloud recognizer routinely fails with "network", and that
+      // silent death read as "voice randomly doesn't work".
+      const code = ev?.error || "unknown";
+      if (code === "not-allowed" || code === "service-not-allowed") {
+        opts.notify("Microphone permission needed for voice input");
+      } else if (code === "network") {
+        opts.notify("Voice recognition unreachable (browser speech service) — try again");
+      } else if (code === "no-speech") {
+        opts.notify("No speech detected");
+      } else if (code !== "aborted") {
+        opts.notify(`Voice input failed: ${code}`);
+      }
+      finish(false);
+    };
+    r.onend = () => finish(true);
+    rec = r;
+    opts.setOverlay("");
+    try { r.start(); } catch { finish(false); }
+  };
+
+  const stop = () => {
+    const r = rec;
+    if (r) { try { r.stop(); } catch { finish(true); } }
+    else finish(true);
+  };
+
+  /**
+   * Feed every key event here first. Returns:
+   *  false — consumed (swallow), true — let the terminal process it,
+   *  undefined — not a voice-relevant event; continue with other branches.
+   */
+  const handleKey = (ev: { type: string; code: string; key: string; repeat?: boolean; metaKey?: boolean; ctrlKey?: boolean; altKey?: boolean; shiftKey?: boolean }): boolean | undefined => {
+    if (ev.code === "Space" && !ev.metaKey && !ev.ctrlKey && !ev.altKey && !ev.shiftKey
+        && !!speechRecognitionCtor() && (active || opts.eligible())) {
+      if (ev.type === "keydown") {
+        if (active) return false; // listening: eat every space
+        if (!ev.repeat) {
+          window.clearTimeout(timer);
+          spacesTyped = 1; // this one goes through, for zero latency
+          timer = window.setTimeout(start, threshold);
+          return true;
+        }
+        return false; // swallow auto-repeat while held
+      }
+      if (ev.type === "keyup") {
+        window.clearTimeout(timer);
+        spacesTyped = 0;
+        if (active) { stop(); return false; }
+        return true;
+      }
+      return undefined;
+    }
+    // Any other keydown cancels a pending (not yet active) hold.
+    if (ev.type === "keydown" && ev.code !== "Space") window.clearTimeout(timer);
+    return undefined;
+  };
+
+  const dispose = () => {
+    window.clearTimeout(timer);
+    if (active) { try { rec?.stop(); } catch { /* gone */ } }
+    active = false;
+    rec = null;
+    opts.setOverlay(null);
+  };
+
+  return { handleKey, dispose, isActive: () => active };
+};
+
+/** Claude chrome scan over a terminal's visible rows — shared eligibility. */
+export const bufferLooksLikeClaude = (t: {
+  rows: number;
+  buffer: { active: { baseY: number; getLine: (row: number) => { translateToString: (trim: boolean) => string } | undefined } };
+}): boolean => {
+  try {
+    const end = t.buffer.active.baseY + t.rows;
+    let text = "";
+    for (let i = Math.max(0, end - 30); i < end; i++) {
+      text += (t.buffer.active.getLine(i)?.translateToString(true) ?? "") + "\n";
+    }
+    return /bypass permissions on|shift\+tab to cycle|esc to interrupt|\? for shortcuts/i.test(text);
+  } catch {
+    return false;
+  }
+};