hop2 0.11.1 → 0.11.3

package/.github/workflows/publish.yml

@@ -64,8 +64,12 @@ jobs:
           node-version: 22
           registry-url: https://registry.npmjs.org
 
-      # Trusted publishing needs npm >= 11.5.1; the runner's bundled npm is older.
-      - run: npm install -g npm@latest
+      # Trusted publishing needs npm >= 11.5.1 and the runner ships older.
+      # Pinned to the 11.x line rather than @latest: npm 12 requires Node
+      # >= 22.22, so `npm@latest` breaks the moment npm raises its engine
+      # floor above whatever Node this workflow pins — which is exactly how
+      # the first nebula-notebook publish failed.
+      - run: npm install -g npm@^11
 
       # Nothing new since the last nightly? Then there is nothing to publish —
       # quiet days should not mint versions. npm records the commit each

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/server/src/rooms.ts

@@ -28,6 +28,12 @@ export type ClientInfo = {
   // Optional per-connection cap for the join snapshot (clamped to the
   // room-level bound). Monitors request ~64KB.
   replayBytes?: number;
+  // False = skip the equal-size attach "wiggle" (the −1/+1 column repaint
+  // nudge). Wall tiles decline it: they arrive already showing the current
+  // grid (the daemon's headless screen, complete — not a raw byte tail), so
+  // the nudge's two SIGWINCHes only produce a visible reflow of the running
+  // app at the exact moment the tile goes live — the "twitch".
+  nudge?: boolean;
 };
 
 export type RoomCreateOptions = {
@@ -371,6 +377,7 @@ export class Room extends EventEmitter {
     // anyway; when sizes are EQUAL nothing would repaint, so nudge: a one-
     // column wiggle (tmux's redraw trick) makes full-screen apps repaint.
     if (
+      info.nudge !== false &&
       client.cols === this.activeCols &&
       client.rows === this.activeRows &&
       this.activeCols > 4 &&

package/hay/apps/server/test/rooms.test.ts

@@ -100,6 +100,27 @@ describe("Room", () => {
     expect(capturedOptions?.shell).toBe("/bin/zsh");
   });
 
+  it("an equal-size attach nudges a repaint unless the client declines", () => {
+    let ptyInstance: FakePty | null = null;
+    const factory: PtyFactory = () => {
+      ptyInstance = new FakePty() as unknown as FakePty;
+      return ptyInstance as any;
+    };
+    const manager = new RoomManager(factory);
+    const room = manager.getRoom("wiggle", { cols: 80, rows: 24 }, "/tmp");
+
+    // Default attach at the PTY's exact size: the −1 wiggle fires (the
+    // bounce-back half is on a timer; the first resize is the evidence).
+    room.attachClient({ id: "a", name: "Alex", colorIndex: 0, cols: 80, rows: 24 }, new FakeSocket());
+    expect(ptyInstance!.resizes.some((r: { cols: number }) => r.cols === 79)).toBe(true);
+
+    // A wall tile declines (nudge: false): it already shows the current
+    // grid, and the wiggle's SIGWINCH reflow is the click-twitch. No resize.
+    const before = ptyInstance!.resizes.length;
+    room.attachClient({ id: "b", name: "Tile", colorIndex: 1, cols: 80, rows: 24, nudge: false }, new FakeSocket());
+    expect(ptyInstance!.resizes.length).toBe(before);
+  });
+
   it("broadcasts pty output to all clients", () => {
     let ptyInstance: FakePty | null = null;
     const factory: PtyFactory = () => {

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";
@@ -375,6 +376,9 @@ const App = () => {
   const [sessions, setSessions] = useState<SessionInfo[]>([]);
   const [loadingSessions, setLoadingSessions] = useState(false);
   const [sessionsError, setSessionsError] = useState(false);
+  // Server-owned folders (Manual mode). Kept in App because the sessions
+  // fetch already carries them.
+  const [folders, setFolders] = useState<Array<{ id: string; name: string }>>([]);
   // Attention plumbing: tab-title alert for a bell in the attached session
   // while the tab is hidden; inline editors for display name / rename / create.
   const [titleAlert, setTitleAlert] = useState(false);
@@ -515,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);
@@ -559,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);
@@ -720,6 +759,7 @@ const App = () => {
     }, 3000);
   };
 
+  pushNoticeRef.current = pushNotice;
   const showToast = (message: string, durationMs = 2000) => {
     setToast(message);
     if (toastTimeout.current) {
@@ -950,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
@@ -1102,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);
@@ -1132,6 +1113,16 @@ const App = () => {
   // Rooms the user asked full history for: their next connect replays the
   // server maximum instead of the fast bounded snapshot.
   const deepReplayRoomsRef = useRef(new Set<string>());
+  // Guards for the automatic deep-history load. The buffer sits at viewport
+  // 0 during every attach write (the terminal is reset before the snapshot
+  // lands), so "y === 0" alone misfired the reload DURING attach on any
+  // session busy enough to have a capped snapshot — which then restored the
+  // viewport to old-top with follow-mode off: terminal parked above the
+  // bottom, new output invisible until a manual scroll. The trigger now
+  // requires a real gesture: a transition from scrolled-up to top, after the
+  // snapshot has settled.
+  const lastViewportYRef = useRef(0);
+  const snapshotSettledAtRef = useRef(0);
   const snapshotWasCappedRef = useRef(false);
   // Set while an automatic deep-history reload is in flight: carries the old
   // buffer length so the post-reload snapshot can restore the reading
@@ -1309,7 +1300,14 @@ const App = () => {
             && (termRef.current.cols !== cols || termRef.current.rows !== rows)) {
           try { termRef.current.resize(cols, rows); } catch { /* keep local size */ }
         }
-        termRef.current.write(screen.data, () => termRef.current?.refresh(0, (termRef.current?.rows ?? 1) - 1));
+        termRef.current.write(screen.data, () => {
+          const t = termRef.current;
+          if (!t) return;
+          // Pin to the newest line — the fast paint is a stand-in for the
+          // snapshot and must land where the snapshot would.
+          t.scrollToBottom();
+          t.refresh(0, t.rows - 1);
+        });
       })
       .catch(() => { /* fast paint is best-effort */ });
 
@@ -1454,13 +1452,21 @@ const App = () => {
               if (pendingRestore) {
                 // The user was reading at the top of the OLD buffer; that
                 // content now sits newLen - oldLen lines down. Land there,
-                // not at the bottom — the reload should be invisible.
+                // not at the bottom — the reload should be invisible. (This
+                // used to fall through to scrollToBottom anyway, yanking the
+                // view away from the spot it had just restored.)
                 const line = Math.max(0, t.buffer.active.length - pendingRestore.oldLen);
                 t.scrollToLine(line);
-                userScrolledUpRef.current = true;
+                userScrolledUpRef.current = line < Math.max(0, t.buffer.active.length - t.rows);
+              } else {
+                t.scrollToBottom();
+                userScrolledUpRef.current = false;
               }
-              t.scrollToBottom();
               t.refresh(0, t.rows - 1);
+              // The snapshot has fully landed: only from here on can a
+              // viewport-top event mean a user gesture.
+              lastViewportYRef.current = t.buffer.active.viewportY;
+              snapshotSettledAtRef.current = performance.now();
             });
           } else {
             writeToTerminal(message.data);
@@ -1735,32 +1741,19 @@ const App = () => {
 
     // Prevent browser from intercepting common terminal shortcuts
     terminal.attachCustomKeyEventHandler((event) => {
-      // 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()) {
+      // ⌘⏎ leaves full screen for the wall — the mirror of ⌘⏎ on a wall
+      // tile entering it. One chord toggles the mode from either side.
+      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey) && !event.altKey && !event.shiftKey) {
         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;
+          event.preventDefault();
+          setSwitcherOpen(true);
         }
+        return false;
       }
-      // 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
@@ -1865,12 +1858,14 @@ const App = () => {
     const onBufferScroll = () => {
       const { y, base } = scrollState();
       userScrolledUpRef.current = y < base;
-      // Hitting the very TOP of a bounded-replay buffer means the user wants
-      // more history than the fast snapshot carried — offer the full reload.
       // Top of a capped snapshot: the user wants more history than the fast
-      // snapshot carried. Load it AUTOMATICALLY — a "load full history"
-      // button was chrome for something the scroll gesture already said.
-      if (y === 0 && snapshotWasCappedRef.current) {
+      // snapshot carried — load it automatically. "The user wants" must mean
+      // a real gesture: arriving at 0 FROM above, on a settled snapshot.
+      const cameFromAbove = lastViewportYRef.current > 0;
+      const settled = snapshotSettledAtRef.current > 0
+        && performance.now() - snapshotSettledAtRef.current > 600;
+      lastViewportYRef.current = y;
+      if (y === 0 && cameFromAbove && settled && snapshotWasCappedRef.current) {
         const room = activeSessionRoomRef.current;
         if (room && !deepReplayRoomsRef.current.has(room)) {
           deepReplayRoomsRef.current.add(room);
@@ -2337,7 +2332,7 @@ const App = () => {
           const row = Math.floor(((tapStartY - rect.top) / rect.height) * term.rows);
           if (col >= 0 && col < term.cols && row >= 0 && row < term.rows) {
             const url = extractUrlAtCell(term.buffer.active.viewportY + row, col);
-            if (url) setLinkPrompt(url);
+            if (url) setLinkPrompt({ url, x: tapStartX, y: tapStartY });
           }
         }
       }
@@ -2512,6 +2507,32 @@ const App = () => {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [switcherOpen]);
 
+  // THE RENDER INVARIANT, enforced continuously instead of per-transition.
+  // Three rounds of patching individual transitions (wall close, tab
+  // visibility, context loss, attach paths) each fixed the reproduced case
+  // and missed a sibling — the class kept coming back as "renders only
+  // after I scroll". Scrolling "fixed" it because a viewport move repaints
+  // everything; so enforce what scrolling incidentally provides:
+  //   while following, the newest line is on screen — and the screen is
+  //   repainted from the buffer every tick, no matter which code path
+  //   forgot to.
+  // A full refresh of ~50 rows at 0.7Hz is microseconds on the GPU renderer
+  // and cheap on the DOM one; correctness beats elegance here.
+  useEffect(() => {
+    if (!session) return;
+    const id = window.setInterval(() => {
+      if (document.hidden || switcherOpenRef.current) return;
+      const t = termRef.current;
+      if (!t) return;
+      try {
+        const buf = t.buffer.active;
+        if (!userScrolledUpRef.current && buf.viewportY < buf.baseY) t.scrollToBottom();
+        t.refresh(0, t.rows - 1);
+      } catch { /* disposed mid-tick */ }
+    }, 1400);
+    return () => window.clearInterval(id);
+  }, [session]);
+
   // Tab or window coming back to the foreground: same stale-frame risk as
   // the wall closing, from browser throttling rather than our own hiding.
   useEffect(() => {
@@ -2629,7 +2650,8 @@ const App = () => {
           tagline: typeof s.tagline === "string" ? s.tagline : undefined,
           parked: s.parked === true,
           archived: s.archived === true,
-          hasLocalCli: s.hasLocalCli === true
+          hasLocalCli: s.hasLocalCli === true,
+          folderId: typeof s.folderId === "string" ? s.folderId : null
         });
       }
 
@@ -2701,6 +2723,11 @@ const App = () => {
       // Drop a response superseded by a newer fetch started while this was
       // in flight (see the sequence-guard note above).
       if (seq !== fetchSeqRef.current) return;
+      setFolders(Array.isArray(data.folders)
+        ? data.folders
+            .filter((f: { id?: string; name?: string }) => f && f.id && f.name)
+            .map((f: { id: string; name: string }) => ({ id: String(f.id), name: String(f.name) }))
+        : []);
       setSessions(list);
       setSessionsError(false);
       sessionListLoadedRef.current = true;
@@ -3151,7 +3178,7 @@ const App = () => {
   // layer disables native pointer events on terminal text, and remote apps
   // can't open the phone's browser — claude login prints a URL that was
   // otherwise un-tappable.)
-  const [linkPrompt, setLinkPrompt] = useState<string | null>(null);
+  const [linkPrompt, setLinkPrompt] = useState<{ url: string; x: number; y: number } | null>(null);
   // Passkey nudge: biometric sign-in works but is invisible — the login page
   // only offers Touch ID / Face ID once a credential exists for this
   // hostname, so a user who never opened the settings drawer never learns it
@@ -3421,6 +3448,7 @@ const App = () => {
             sessions={sessions}
             currentRoom={null}
             dismissable={false}
+            folders={folders}
             onClose={() => {}}
             onSwitch={(next) => {
               window.location.href = buildSessionPath(next.displayName || next.name);
@@ -4075,6 +4103,7 @@ const App = () => {
             onNotice={showToast}
             tileWsBase={resolveWsUrl()}
             onFocusSession={focusSessionInPlace}
+            folders={folders}
             userName={name}
             terminalTheme={resolveTerminalTheme(themeMode)}
             onOpenSettings={() => {
@@ -4145,23 +4174,34 @@ const App = () => {
             </div>
           )}
           {linkPrompt && (
-            <div className="link-prompt" role="dialog" aria-label="Open link">
-              <span className="link-prompt-url">{linkPrompt}</span>
+            <div
+              className="context-menu link-menu"
+              role="menu"
+              aria-label="Open link"
+              style={{
+                left: Math.max(8, Math.min(linkPrompt.x, window.innerWidth - 268)),
+                top: Math.max(8, Math.min(linkPrompt.y + 10, window.innerHeight - 150))
+              }}
+            >
+              <span className="context-menu-title">{linkPrompt.url}</span>
               <button
                 type="button"
-                className="link-prompt-open"
+                role="menuitem"
+                className="context-menu-item"
                 onClick={() => {
-                  window.open(linkPrompt, "_blank", "noopener");
+                  window.open(linkPrompt.url, "_blank", "noopener");
                   setLinkPrompt(null);
                 }}
               >
-                Open
+                <span>Open link</span>
               </button>
               <button
                 type="button"
+                role="menuitem"
+                className="context-menu-item"
                 onClick={async () => {
                   try {
-                    await navigator.clipboard.writeText(linkPrompt);
+                    await navigator.clipboard.writeText(linkPrompt.url);
                     showToast("Link copied");
                   } catch {
                     showToast("Clipboard denied — long-press the URL text instead");
@@ -4169,9 +4209,18 @@ const App = () => {
                   setLinkPrompt(null);
                 }}
               >
-                Copy
+                <span>Copy link</span>
+              </button>
+              <div className="context-menu-separator" role="separator" />
+              <button
+                type="button"
+                role="menuitem"
+                className="context-menu-item"
+                onClick={() => setLinkPrompt(null)}
+              >
+                <span>Cancel</span>
+                <kbd>esc</kbd>
               </button>
-              <button type="button" aria-label="Dismiss" onClick={() => setLinkPrompt(null)}>✕</button>
             </div>
           )}
           {isMobile && (

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

@@ -0,0 +1,109 @@
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+
+// One context menu for the whole app.
+//
+// Right-click is a shortcut to the actions a surface already has — it must
+// never be the ONLY way to reach something, and it must never invent a
+// different vocabulary from the buttons beside it. So this renders the same
+// items a surface's visible affordances expose, in the same order, with the
+// same words.
+//
+// Deliberately NOT applied to the terminal: there, right-click already means
+// something (paste on Linux/Windows, the native copy/paste menu everywhere),
+// and mouse-reporting apps — Claude, vim, less — receive button events the
+// moment tracking is on. Overriding it would either steal a click the app
+// asked for or replace a menu people rely on with a worse one.
+
+export type MenuItem =
+  | { kind?: "item"; label: string; onSelect: () => void; danger?: boolean; hint?: string; disabled?: boolean }
+  | { kind: "separator" };
+
+export type MenuRequest = { x: number; y: number; items: MenuItem[] } | null;
+
+const isItem = (i: MenuItem): i is Extract<MenuItem, { kind?: "item" }> => i.kind !== "separator";
+
+export const ContextMenu = ({ request, onClose }: { request: MenuRequest; onClose: () => void }) => {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [pos, setPos] = useState<{ left: number; top: number } | null>(null);
+  const [active, setActive] = useState(0);
+
+  // Clamp into the viewport BEFORE paint: a menu opened near an edge would
+  // otherwise flash off-screen and jump.
+  useLayoutEffect(() => {
+    if (!request) { setPos(null); return; }
+    const el = ref.current;
+    const w = el?.offsetWidth || 200;
+    const h = el?.offsetHeight || 200;
+    const pad = 8;
+    setPos({
+      left: Math.max(pad, Math.min(request.x, window.innerWidth - w - pad)),
+      top: Math.max(pad, Math.min(request.y, window.innerHeight - h - pad))
+    });
+    setActive(request.items.findIndex(isItem));
+  }, [request]);
+
+  useEffect(() => {
+    if (!request) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") { e.preventDefault(); onClose(); return; }
+      const idxs = request.items.map((it, i) => (isItem(it) && !it.disabled ? i : -1)).filter((i) => i >= 0);
+      if (idxs.length === 0) return;
+      if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+        e.preventDefault();
+        const at = idxs.indexOf(active);
+        const next = e.key === "ArrowDown"
+          ? idxs[(at + 1 + idxs.length) % idxs.length]
+          : idxs[(at - 1 + idxs.length) % idxs.length];
+        setActive(next);
+      } else if (e.key === "Enter") {
+        e.preventDefault();
+        const item = request.items[active];
+        if (item && isItem(item) && !item.disabled) { onClose(); item.onSelect(); }
+      }
+    };
+    // Capture so a menu click never also reaches the surface underneath.
+    const onDown = (e: MouseEvent) => {
+      if (!ref.current?.contains(e.target as Node)) onClose();
+    };
+    window.addEventListener("keydown", onKey, true);
+    window.addEventListener("mousedown", onDown, true);
+    window.addEventListener("resize", onClose);
+    window.addEventListener("blur", onClose);
+    return () => {
+      window.removeEventListener("keydown", onKey, true);
+      window.removeEventListener("mousedown", onDown, true);
+      window.removeEventListener("resize", onClose);
+      window.removeEventListener("blur", onClose);
+    };
+  }, [request, active, onClose]);
+
+  if (!request) return null;
+  return (
+    <div
+      ref={ref}
+      className="context-menu"
+      role="menu"
+      style={pos ? { left: pos.left, top: pos.top } : { left: -9999, top: -9999 }}
+      onContextMenu={(e) => e.preventDefault()}
+    >
+      {request.items.map((item, i) =>
+        isItem(item) ? (
+          <button
+            key={item.label + i}
+            type="button"
+            role="menuitem"
+            className={"context-menu-item" + (item.danger ? " danger" : "") + (i === active ? " active" : "")}
+            disabled={item.disabled}
+            onMouseEnter={() => setActive(i)}
+            onClick={() => { onClose(); item.onSelect(); }}
+          >
+            <span>{item.label}</span>
+            {item.hint && <kbd>{item.hint}</kbd>}
+          </button>
+        ) : (
+          <div key={"sep" + i} className="context-menu-separator" role="separator" />
+        )
+      )}
+    </div>
+  );
+};