@gemboss/ui 0.25.0 → 0.32.0

package/src/assistant/bridge.tsx

@@ -0,0 +1,636 @@
+"use client";
+
+/**
+ * The BRIDGE on the user's machine, seen from the browser — @gemboss/ui (0.32.0).
+ *
+ * A surface whose assistant can run Claude Code / Codex on the user's own subscription installs a small server on their
+ * machine (`scripts/assistant-bridge.mjs` in each toolkit) and talks to it at http://127.0.0.1:<port> straight from the
+ * page: the surface's server never sees that call. content-radar (8787), partner-radar (8789) and search-radar (8790)
+ * each carried the same ~300 lines for it, copied one from the other: find the bridge (behind Chrome's Local Network
+ * Access permission), pair this browser with it (a code the page makes and puts in the install command), hand it a short
+ * data token from the server, send a turn and read its stream, tell a bridge failure from a turn failure, poll while a
+ * teammate is installing, notice when it goes away, and say all of that in the engine picker's Setup and Status tabs.
+ * Every review fixed one copy and the next review found the same bug in the other two. This is that code, once:
+ *
+ *   createBridgeClient({ port, codeKey, app })  the calls (no React): probe, detect, pair code, data token, turn, stop
+ *   readTurnEvents(res, onEvent, { atBridge })  the turn's server-sent events, the bridge's or the server's
+ *   useBridge(client, { open, wantsLocal })     the state: probes on open, the 3 s poll, focus / permission re-checks
+ *   bridgePickerProps(b, { latest, … })         → EnginePicker's `bridge`, `setup` and `statusActions`
+ *
+ * What stays the surface's: which engines exist and what they cost, the request body, what each event does to its
+ * messages, its confirm dialog. Behaviour carried over as measured in the radars (each line names where):
+ *   - the permission is asked from a click only (Chrome shows its dialog then); a fetch to loopback without it fails
+ *     like "no bridge", so the permission is read before any conclusion about the bridge (content-radar 22/09);
+ *   - a probe from that click waits 60 s: the fetch's clock runs while the dialog is open (review #393);
+ *   - a state the user is in the middle of ("asking", a wrong code) is not overwritten by a background probe (#393);
+ *   - probes continue once paired, so a bridge that stops is noticed (23/09);
+ *   - only the call to the bridge is marked `atBridge`: a data token the server refused is the turn's error (#922).
+ */
+import React, { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import { atBridge } from "./chat-turns";
+import type { BridgeSetup, BridgeStatus } from "./engine";
+
+// ── The calls ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** What a probe found. `absent` = nothing answers · `unpaired` = a bridge answers, with another pairing code · `paired` =
+ *  ours · `needs-permission` = the browser has not been allowed to call this machine yet (ask from a click) · `asking` =
+ *  its dialog is open · `blocked` = the user said no (only the site settings can undo it). */
+export type BridgeProbeState = "absent" | "unpaired" | "paired" | "needs-permission" | "asking" | "blocked";
+
+/** One engine as the server or the bridge reports it. Surfaces add their own fields (`paid`, `capUsd`, `effort`). */
+export interface BridgeEngineStatus {
+  label?: string;
+  installed?: boolean;
+  /** null: could not tell (the engine is still offered). */
+  loggedIn?: boolean | null;
+  account?: string | null;
+  /** Runs on the user's machine only: not found on the server is not an install problem. */
+  localOnly?: boolean;
+  /** Where it would run from this browser: "bridge" once merged with a paired bridge. */
+  via?: string;
+  [extra: string]: unknown;
+}
+export type BridgeEngines = Record<string, BridgeEngineStatus>;
+
+export interface BridgeProbe {
+  state: BridgeProbeState;
+  engines?: BridgeEngines;
+  /** The bridge's own version (`/status`); 1 when it does not say. */
+  version?: number;
+  /** Installed under ~/.<app>-bridge (not run from a checkout). */
+  installed?: boolean;
+  /** Starts at sign-in (a LaunchAgent). */
+  autostart?: boolean;
+  dataToken?: unknown;
+  /** It was paired and stopped answering a call: said until a probe finds it again. */
+  lost?: boolean;
+  /** Stopped or removed from the panel. */
+  off?: "stop" | "remove";
+  /** The code typed in Setup is not the bridge's. */
+  wrong?: boolean;
+  /** The permission dialog was closed without a choice. */
+  dismissed?: boolean;
+}
+
+export interface BridgeClientOptions {
+  /** Its port on 127.0.0.1. One per surface, so several bridges run side by side. */
+  port: number;
+  /** localStorage key of this browser's pairing code ("pr-bridge-code"). */
+  codeKey: string;
+  /** The surface's name in what the user reads ("Sign in to partner-radar again"). */
+  app: string;
+  /** Where the server hands out a short-lived data token (POST). Default "/api/assistant/bridge-token"; null: none. */
+  tokenPath?: string | null;
+  /** The first bridge version that accepts the `x-data-token` header (content-radar: 2; an older bridge's CORS rejects
+   *  it, and every turn would fail "Failed to fetch"). Default 0. */
+  tokenSince?: number;
+  /** Default "127.0.0.1". */
+  host?: string;
+}
+
+export interface BridgeClient {
+  readonly url: string;
+  readonly app: string;
+  readCode(): string;
+  writeCode(code: string): void;
+  /** This browser's code, made (8 characters, no 0/O/1/I) and kept the first time. */
+  ensureCode(): string;
+  /** The line a teammate pastes into Terminal: installs the bridge with this browser's code, starting at sign-in. */
+  installCommand(code: string, origin?: string): string;
+  /** A data token from the server, reused until it has less than an hour left. Errors are the server's, not the bridge's. */
+  dataToken(): Promise<string>;
+  /** One call to /status. Never throws. */
+  probe(code?: string, timeoutMs?: number): Promise<BridgeProbe>;
+  /** A probe that reads the browser's permission first. `fromClick`: may open Chrome's dialog, and waits for it. */
+  detect(opts?: { fromClick?: boolean }): Promise<BridgeProbe>;
+  /** Stop the bridge or remove it from the machine (bridge v3+). Throws (marked `atBridge`) when it does not answer. */
+  control(kind: "stop" | "remove"): Promise<{ autostart: boolean }>;
+  /**
+   * POST a turn to the bridge; the response is its event stream (read it with `readTurnEvents(res, fn, { atBridge: true })`).
+   * Adds the pairing code and a data token (`version`: the paired bridge's, for `tokenSince`). Throws marked `atBridge` when
+   * the bridge does not answer or answers an error (with its status: 401 is "another pairing code"); a data token the
+   * server refused is thrown unmarked. Do not wrap it in `atBridge` again.
+   */
+  turn(body: Record<string, unknown>, opts?: { signal?: AbortSignal; version?: number }): Promise<Response>;
+}
+
+const CODE_ABC = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/** Chrome's hint for a public page calling loopback (Local Network Access). Browsers that do not know it ignore it. */
+const LOOPBACK = { targetAddressSpace: "loopback" } as unknown as RequestInit;
+
+function storage(): Storage | null {
+  try { return typeof localStorage === "undefined" ? null : localStorage; } catch { return null; }
+}
+
+/** granted | prompt | denied | unsupported. The permission's name is `local-network-access` (measured 22/09/2026,
+ *  Chromium 148 / Chrome 152). A browser without it: probe straight away. */
+export async function localNetworkPermission(): Promise<string> {
+  try {
+    const p = await navigator.permissions.query({ name: "local-network-access" as PermissionName });
+    return p.state;
+  } catch { return "unsupported"; }
+}
+
+export function createBridgeClient(o: BridgeClientOptions): BridgeClient {
+  const url = `http://${o.host ?? "127.0.0.1"}:${o.port}`;
+  const tokenPath = o.tokenPath === undefined ? "/api/assistant/bridge-token" : o.tokenPath;
+  let tok: { token: string; exp: number } | null = null;
+  // Storage that refuses writes (blocked site data, a sandboxed frame): the code lives in memory for this page, so the
+  // command in Setup and the turns carry the SAME code (review #3952: a new code on every open, and turns sending "").
+  let memCode = "";
+  const client: BridgeClient = {
+    url,
+    app: o.app,
+    readCode: () => { let v = ""; try { v = storage()?.getItem(o.codeKey) || ""; } catch { /* blocked */ } return v || memCode; },
+    writeCode: (c) => { memCode = c; try { storage()?.setItem(o.codeKey, c); } catch { /* private mode */ } },
+    ensureCode() {
+      const have = client.readCode();
+      if (/^[A-Z0-9]{8}$/.test(have)) return have;
+      const bytes = crypto.getRandomValues(new Uint8Array(8));
+      const code = Array.from(bytes, (b) => CODE_ABC[b % CODE_ABC.length]).join("");
+      client.writeCode(code);
+      return code;
+    },
+    installCommand: (code, origin = typeof window === "undefined" ? "" : window.location.origin) =>
+      `curl -fsSL ${origin}/bridge/install.sh | sh -s -- --code ${code} --autostart`,
+    async dataToken() {
+      if (!tokenPath) return "";
+      // Under an hour left: ask again. One turn (an article) uses ONE token throughout, and 10 minutes was too close for a
+      // long one (content-radar review #394).
+      if (tok && tok.exp - Date.now() > 3_600_000) return tok.token;
+      const r = await fetch(tokenPath, { method: "POST" });
+      if (!r.ok) throw new Error(`Couldn't get a data token (HTTP ${r.status}). Sign in to ${o.app} again`);
+      tok = await r.json();
+      return (tok as { token: string }).token;
+    },
+    // Short when only asking "is anything there" (nothing there fails at once; 1.5 s covers a slow machine), longer with a
+    // code: a bridge's first /status may still be running `auth status`.
+    async probe(code, timeoutMs = code ? 8000 : 1500) {
+      try {
+        const r = await fetch(`${url}/status`, { headers: code ? { "x-bridge-code": code } : {}, signal: AbortSignal.timeout(timeoutMs), ...LOOPBACK });
+        if (r.status === 401) return { state: "unpaired" };
+        if (!r.ok) return { state: "absent" };
+        const j = await r.json();
+        return { state: "paired", engines: j.engines || {}, dataToken: j.dataToken, version: Number(j.version) || 1, installed: !!j.installed, autostart: !!j.autostart };
+      } catch { return { state: "absent" }; }
+    },
+    async detect({ fromClick = false } = {}) {
+      const perm = await localNetworkPermission();
+      if (perm === "denied") return { state: "blocked" };
+      // Not asked yet: wait for the user's click, so Chrome's dialog comes when they want it.
+      if (perm === "prompt" && !fromClick) return { state: "needs-permission" };
+      // From the click the fetch waits up to 60 s: its clock runs while the dialog is open, and cancelling it can close
+      // the dialog (review #393).
+      const br = await client.probe(client.readCode(), fromClick ? 60_000 : undefined);
+      if (br.state === "absent") {
+        const after = await localNetworkPermission(); // the dialog: "Block", or closed
+        if (after === "denied") return { state: "blocked" };
+        if (after === "prompt") return { state: "needs-permission", dismissed: fromClick };
+      }
+      return br;
+    },
+    async control(kind) {
+      let r: Response;
+      try {
+        r = await fetch(`${url}/${kind}`, { method: "POST", headers: { "x-bridge-code": client.readCode() }, signal: AbortSignal.timeout(8000), ...LOOPBACK });
+      } catch (e) { throw atBridge(e); }
+      if (!r.ok) throw atBridge(new Error(`HTTP ${r.status}`), r.status);
+      const j = await r.json().catch(() => ({}));
+      return { autostart: !!j.autostart };
+    },
+    async turn(body, { signal, version } = {}) {
+      const token = tokenPath && (version ?? Number.POSITIVE_INFINITY) >= (o.tokenSince ?? 0) ? await client.dataToken() : "";
+      let res: Response;
+      try {
+        res = await fetch(`${url}/turn`, {
+          method: "POST",
+          headers: { "content-type": "application/json", "x-bridge-code": client.readCode(), ...(token ? { "x-data-token": token } : {}) },
+          body: JSON.stringify(body),
+          signal,
+          ...LOOPBACK,
+        });
+      } catch (e) { throw atBridge(e); }
+      if (!res.ok || !res.body) {
+        const j = await res.json().catch(() => ({}));
+        throw atBridge(new Error(j.error || `HTTP ${res.status}`), res.status);
+      }
+      return res;
+    },
+  };
+  return client;
+}
+
+/** POST a turn to the surface's own server route; the response is its event stream. An error is the turn's (unmarked). */
+export async function postTurn(url: string, body: Record<string, unknown>, { signal }: { signal?: AbortSignal } = {}): Promise<Response> {
+  const res = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body), signal });
+  if (!res.ok || !res.body) {
+    const j = await res.json().catch(() => ({}));
+    throw Object.assign(new Error(j.error || `HTTP ${res.status}`), { status: res.status });
+  }
+  return res;
+}
+
+/** One event of a turn's stream (`data: {…}` blocks): session / text / tool / tool_result / done, and the surface's own. */
+export interface TurnEvent { type: string; [k: string]: unknown }
+
+export const BRIDGE_CLOSED_EARLY = "The bridge closed the connection before the turn finished";
+export const SERVER_CLOSED_EARLY = "The server closed the connection before the turn finished";
+
+/**
+ * Read a turn's server-sent events to its `done`, calling `onEvent` with each JSON event. A line that is not JSON (": ping",
+ * a heartbeat) is skipped. `atBridge`: the stream comes from the bridge, so a read that throws (the bridge died mid-turn,
+ * the machine slept) is the bridge's failure; the user's Stop (AbortError) stays a Stop either way.
+ * A stream that ENDS without `done` is a turn cut short, never a finished answer (both the bridge and the radars' routes
+ * always end with `done`, an error one included): it throws, the bridge's failure for the bridge's stream (content-radar's
+ * runBridgeTurn said so; the radars' panels showed half an answer as done, review #3952). On any early exit (`onEvent`
+ * threw, the stream broke) the reader is cancelled, so the bridge sees the client go and stops the engine.
+ */
+export async function readTurnEvents(res: Response, onEvent: (ev: TurnEvent) => void, { atBridge: fromBridge = false }: { atBridge?: boolean } = {}): Promise<void> {
+  const cut = () => (fromBridge ? atBridge(new TypeError(BRIDGE_CLOSED_EARLY)) : new Error(SERVER_CLOSED_EARLY));
+  if (!res.body) throw cut();
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  let done = false;
+  try {
+    for (;;) {
+      let chunk: ReadableStreamReadResult<Uint8Array>;
+      try { chunk = await reader.read(); } catch (e) {
+        if (done) break; // the turn is whole: a connection that drops after its `done` changes nothing
+        throw fromBridge ? atBridge(e) : e;
+      }
+      if (chunk.done) break;
+      buf += dec.decode(chunk.value, { stream: true });
+      const parts = buf.split("\n\n");
+      buf = parts.pop() ?? "";
+      for (const part of parts) {
+        let ev: TurnEvent;
+        try { ev = JSON.parse(part.replace(/^data: /, "")); } catch { continue; }
+        if (!ev || typeof ev !== "object") continue;
+        if (ev.type === "done") done = true;
+        onEvent(ev);
+      }
+    }
+  } finally {
+    if (!done) reader.cancel().catch(() => {});
+  }
+  if (!done) throw cut();
+}
+
+/** The engines usable FROM THIS BROWSER: a paired bridge's engines replace the server's "runs on your machine only". */
+export function mergeBridgeEngines(status: BridgeEngines | null, bridge: BridgeProbe | null | undefined): BridgeEngines | null {
+  if (!status) return status;
+  if (bridge?.state !== "paired") return status;
+  const out: BridgeEngines = { ...status };
+  // `localOnly` goes: through the bridge and still missing means NOT INSTALLED on your machine, and "run the bridge" would
+  // point the wrong way (content-radar review #392).
+  for (const e of ["claude", "codex"]) if (bridge.engines?.[e]) out[e] = { ...bridge.engines[e], localOnly: false, via: "bridge" };
+  return out;
+}
+
+/** The page is served from the dev machine: the app runs the engines itself, there is no bridge to find. */
+export const isLocalPage = () => typeof window !== "undefined" && /^(localhost|127\.0\.0\.1)$/.test(window.location.hostname);
+
+// ── The state ──────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface UseBridgeOptions {
+  /** The assistant is open (popup, side, full screen): probes run only then. */
+  open: boolean;
+  /** The selected engine runs on the user's machine (not a server engine): while no bridge is found, poll every 3 s so
+   *  the panel connects by itself once a teammate's install finishes. */
+  wantsLocal: boolean;
+  /** The engine picker is open: the pairing code is read again (another tab may have paired with another one), so the
+   *  command in Setup carries the code the next turn will send. */
+  pickerOpen?: boolean;
+  /** GET for the server's own engines (`{ engines }`), probed with the bridge. Default "/api/assistant"; null: none. */
+  statusUrl?: string | null;
+  /** After each full check (open, Check again), with the merged engines: move off an engine that cannot run here. */
+  onDetected?: (engines: BridgeEngines, bridge: BridgeProbe) => void;
+  /** The page runs on the dev machine: no bridge, no probes. Default `isLocalPage()`. */
+  local?: boolean;
+}
+
+export interface BridgeApi {
+  client: BridgeClient;
+  bridge: BridgeProbe;
+  /** The server's engines; null until the first check answers (and again after `recheck`). */
+  status: BridgeEngines | null;
+  /** `status` with a paired bridge's engines merged in (`mergeBridgeEngines`). */
+  engines: BridgeEngines | null;
+  /** The page runs on the dev machine: no dot, no Setup / Status. Decided after mount (false in the server's markup). */
+  local: boolean;
+  paired: boolean;
+  /** The paired bridge's version (1 when it does not say), 0 when not paired: pass it to `turn` for `tokenSince`. */
+  version: number;
+  /** This browser's pairing code ("" until the assistant first opens on a page that is not local). */
+  pairCode: string;
+  /** Probe the server and the bridge again (Status › Check again). */
+  recheck(): void;
+  /** A call to the bridge failed: say "not responding" at once and probe again, instead of sending the next turn into
+   *  the void. Call it when `turns.fail(...)` says `bridge`. */
+  lost(): void;
+  /** Pair with the code the terminal printed. True when it matched. */
+  pair(code: string): Promise<boolean>;
+  /** From the "Allow" click: lets Chrome show its permission dialog, then probes. */
+  allowAccess(): Promise<void>;
+  /** Stop / remove the bridge. Resolves with `autostart` (the note to show); on failure it probes again and throws. */
+  control(kind: "stop" | "remove"): Promise<{ autostart: boolean }>;
+  /** Replace the state (a surface's own case). */
+  setBridge: React.Dispatch<React.SetStateAction<BridgeProbe>>;
+}
+
+/** Keep `cur` when the user is in the middle of it ("asking") or a probe found the same state (it may carry a note). */
+const keepUnlessNew = (res: BridgeProbe) => (cur: BridgeProbe) => (cur.state === "asking" || cur.state === res.state ? cur : res);
+
+export function useBridge(clientArg: BridgeClient, o: UseBridgeOptions): BridgeApi {
+  // The client of the FIRST render, for the hook's life: one built in render (`useBridge(createBridgeClient(…))`) would
+  // otherwise restart every effect on each streamed token (the 3 s poll never fires) and lose its token cache.
+  const client = useRef(clientArg).current;
+  // On the dev machine there is no bridge. The effects read it where they run (the browser); what is DRAWN switches after
+  // mount, so the server's markup (no window: "not local") and the first client render agree (no hydration mismatch).
+  const localNow = o.local ?? isLocalPage();
+  const [localDrawn, setLocalDrawn] = useState(o.local ?? false);
+  useEffect(() => { setLocalDrawn(o.local ?? isLocalPage()); }, [o.local]);
+  const statusUrl = o.statusUrl === undefined ? "/api/assistant" : o.statusUrl;
+  const [bridge, setBridgeRaw] = useState<BridgeProbe>({ state: "absent" });
+  const [status, setStatus] = useState<BridgeEngines | null>(null);
+  const [pairCode, setPairCode] = useState("");
+  const onDetected = useRef(o.onDetected);
+  onDetected.current = o.onDetected;
+  const { open, wantsLocal, pickerOpen } = o;
+  // Every user action (pair, Stop, Allow, a lost bridge) starts a new epoch. A background probe (the poll, focus, the
+  // permission) that began in an older epoch is dropped when it answers: a /status that left before Stop must not bring
+  // "running" back after it, nor a poll with the old code undo a pairing (review #3952).
+  const epoch = useRef(0);
+  const setBridge = useCallback<React.Dispatch<React.SetStateAction<BridgeProbe>>>((v) => { epoch.current += 1; setBridgeRaw(v); }, []);
+  const inflight = useRef(false);
+  const background = useCallback(() => {
+    if (inflight.current) return; // a probe with a code may wait 8 s: one at a time, not one per tick
+    inflight.current = true;
+    const at = epoch.current;
+    client.detect().then((res) => { if (at === epoch.current) setBridgeRaw(keepUnlessNew(res)); }).finally(() => { inflight.current = false; });
+  }, [client]);
+
+  // The server's engines and the bridge, when the assistant opens and after Check again (status → null).
+  useEffect(() => {
+    if (!open || status) return undefined;
+    let cancelled = false;
+    const at = epoch.current;
+    Promise.all([
+      statusUrl ? fetch(statusUrl).then((r) => r.json()).then((j) => (j && j.engines) || {}).catch(() => ({})) : Promise.resolve({}),
+      localNow ? Promise.resolve<BridgeProbe>({ state: "absent" }) : client.detect(),
+    ]).then(([st, br]) => {
+      if (cancelled) return;
+      setStatus(st);
+      // The user acted while it was out (paired, pressed Stop): keep what they did, the engines still arrive.
+      const now = at === epoch.current ? br : null;
+      if (now) setBridgeRaw(now);
+      onDetected.current?.(mergeBridgeEngines(st, now ?? br) ?? {}, now ?? br);
+    });
+    return () => { cancelled = true; };
+  }, [open, status, statusUrl, localNow, client]);
+
+  // The code is made when the assistant first opens on a public page (not on every page of everyone: the panel sits in
+  // the layout), and read again whenever the picker opens.
+  useEffect(() => { if (open && !localNow) setPairCode(client.ensureCode()); }, [open, pickerOpen, localNow, client]);
+
+  // A teammate is pasting the install command: probe every 3 s, so the panel switches to "through the bridge" as soon as
+  // it runs, with no click and no reload.
+  const polling = open && wantsLocal && !localNow && (bridge.state === "absent" || bridge.state === "unpaired");
+  useEffect(() => {
+    if (!polling) return undefined;
+    const t = setInterval(background, 3000);
+    return () => clearInterval(t);
+  }, [polling, background]);
+
+  // Back to the tab, and a permission changed in the site settings: probe again. ALSO WHEN PAIRED: a bridge that stops
+  // (closed, the machine slept) must be noticed; probing stopped once paired, so one drop meant "connected" forever (23/09).
+  const asking = bridge.state === "asking";
+  useEffect(() => {
+    if (!open || localNow || asking) return undefined;
+    let cancelled = false;
+    const again = () => {
+      if (cancelled || document.visibilityState !== "visible") return;
+      background();
+    };
+    window.addEventListener("focus", again);
+    document.addEventListener("visibilitychange", again);
+    let perm: PermissionStatus | null = null;
+    navigator.permissions?.query({ name: "local-network-access" as PermissionName }).then((p) => {
+      if (cancelled) return; // cleaned up before the query answered: no orphan listener
+      perm = p; p.onchange = again;
+    }).catch(() => {});
+    return () => {
+      cancelled = true;
+      window.removeEventListener("focus", again);
+      document.removeEventListener("visibilitychange", again);
+      if (perm) perm.onchange = null;
+    };
+  }, [open, localNow, asking, background]);
+
+  const lost = useCallback(() => {
+    setBridge({ state: "absent", lost: true });
+    const at = epoch.current;
+    client.detect().then((res) => { if (at === epoch.current) setBridgeRaw((cur) => (cur.state === "asking" ? cur : res.state === "absent" ? { ...res, lost: true } : res)); });
+  }, [client, setBridge]);
+
+  const pair = useCallback(async (raw: string) => {
+    const code = raw.trim().toUpperCase();
+    if (!code) return false;
+    epoch.current += 1; // a poll still holding the old code must not answer over this
+    const at = epoch.current;
+    const br = await client.probe(code);
+    if (br.state === "paired") { client.writeCode(code); setPairCode(code); }
+    if (at === epoch.current) setBridge(br.state === "unpaired" ? { state: "unpaired", wrong: true } : br);
+    return br.state === "paired";
+  }, [client, setBridge]);
+
+  const allowAccess = useCallback(async () => {
+    setBridge({ state: "asking" });
+    const at = epoch.current;
+    const res = await client.detect({ fromClick: true });
+    if (at === epoch.current) setBridge(res);
+  }, [client, setBridge]);
+
+  const control = useCallback(async (kind: "stop" | "remove") => {
+    epoch.current += 1;
+    try {
+      const r = await client.control(kind);
+      setBridge({ state: "absent", off: kind });
+      return r;
+    } catch (e) {
+      // It did not answer: gone. It answered 401: running, with another code (Setup's Pair form, not "stopped
+      // responding"). Another HTTP error (an old bridge without /stop): still there, the state stays (review #3952).
+      const status = (e as { status?: number } | null)?.status;
+      if (status === undefined) lost();
+      else if (status === 401) setBridge({ state: "unpaired" });
+      throw e;
+    }
+  }, [client, lost, setBridge]);
+
+  const recheck = useCallback(() => setStatus(null), []);
+  const engines = mergeBridgeEngines(status, bridge);
+  return {
+    client, bridge, status, engines, local: localDrawn, pairCode,
+    // The same version everywhere (turn's tokenSince, the picker's outdated): a paired bridge that does not say is v1.
+    paired: bridge.state === "paired", version: bridge.state === "paired" ? bridge.version ?? 1 : 0,
+    recheck, lost, pair, allowAccess, control, setBridge,
+  };
+}
+
+// ── What the engine picker shows ───────────────────────────────────────────────────────────────────────────────────────
+
+/** Every sentence the Setup / Status tabs say about the bridge. English, like every surface's chrome. */
+export interface BridgeSetupLabels {
+  outdated: string; permission: string; blocked: string; unpaired: string; lost: string; stopped: string; removed: string;
+  allowHint: string; allowDismissed: string; allow: string; waiting: string;
+  blockedStep1: ReactNode; blockedStep2: ReactNode; blockedStep3: string; checkAgain: string;
+  pastePairing: ReactNode; pairingCode: string; pairingExample: string; pair: string; pairing: string; wrongCode: string; orReinstall: string;
+  update: string; reinstall: string; installStep1: ReactNode; installStep2: string;
+  pairedNote: string; installNote: string; stop: string; remove: string;
+}
+export const BRIDGE_SETUP_EN: BridgeSetupLabels = {
+  outdated: "This bridge is older than the one the panel expects: update it once (Setup).",
+  permission: "The browser needs permission to connect to this computer (localhost).",
+  blocked: "Chrome is blocking this page from connecting to your computer.",
+  unpaired: "The bridge is running on your machine but is not paired with this browser.",
+  lost: "The bridge stopped responding. If it autostarts on login it usually comes back in a few seconds; otherwise rerun the command.",
+  stopped: "Bridge stopped.", removed: "Bridge removed.",
+  allowHint: "Chrome will ask to “access devices on your local network”: choose Allow.",
+  allowDismissed: " (The dialog was closed; click the button again.)",
+  allow: "Allow connecting to this computer", waiting: "Waiting for your choice in the dialog…",
+  blockedStep1: <>Click the <strong>⚙︎ / ⓘ</strong> icon to the left of the address bar.</>,
+  blockedStep2: <>Find <strong>Local network access</strong> and choose <strong>Allow</strong>.</>,
+  blockedStep3: "Come back to this tab. The panel picks it up without a reload.",
+  checkAgain: "Check again",
+  pastePairing: <>Paste the <strong>pairing code</strong> shown in the terminal:</>,
+  pairingCode: "Pairing code", pairingExample: "e.g. 7KQ2M9XA", pair: "Pair", pairing: "Pairing\u2026",
+  wrongCode: "Wrong code. Check the pairing code line in the terminal.",
+  orReinstall: "Or reinstall with this command, which includes this browser’s code:",
+  update: "Update once: paste this command into Terminal and press Enter.",
+  reinstall: "Reinstall or update: paste this command into Terminal and press Enter.",
+  installStep1: <>Open <strong>Terminal</strong> (⌘ + Space, type Terminal).</>,
+  installStep2: "Paste this command and press Enter (about 1 minute).",
+  pairedNote: "The pairing code stays the same: the panel reconnects in a few seconds.",
+  installNote: "The panel connects as soon as the bridge starts, and the bridge starts with your computer after that. Requires macOS, Node.js, and Claude Code or Codex signed in.",
+  stop: "Stop bridge", remove: "Remove from this machine",
+};
+
+/** The line a Stop / Remove leaves in the chat (`turns.note(…, { bridge: true })`). */
+export function bridgeControlNote(kind: "stop" | "remove", { autostart }: { autostart: boolean }): string {
+  return kind === "remove"
+    ? "Bridge removed from this machine. To use it again, run the install command in Setup."
+    : `Bridge stopped.${autostart ? " It starts again the next time you log in to your computer." : ""} To start it now, rerun the install command in Setup.`;
+}
+
+/** The pairing form on Setup: one field, Enter pairs (a one-field form submits by itself). The button is
+ *  `type="button"`: the picker sits in the composer, and chat.css draws a submit button there as the round send button. */
+export function BridgePairForm({ onPair, wrong, labels }: { onPair: (code: string) => Promise<boolean> | void; wrong?: boolean; labels?: Partial<BridgeSetupLabels> }) {
+  const L = { ...BRIDGE_SETUP_EN, ...labels };
+  const [code, setCode] = useState("");
+  // The probe with a code can take up to 8 s (a first /status runs `auth status`): one at a time, and it says so.
+  const [pending, setPending] = useState(false);
+  const go = async () => {
+    if (!code.trim() || pending) return;
+    setPending(true);
+    try { if (await onPair(code)) setCode(""); } finally { setPending(false); }
+  };
+  return (
+    <>
+      <form className="ui-toolbar" onSubmit={(e) => { e.preventDefault(); void go(); }} aria-busy={pending || undefined}>
+        <input className="gemboss-field" style={{ flex: "1 1 140px", minWidth: 0, textTransform: "uppercase", letterSpacing: ".08em" }}
+          value={code} onChange={(e) => setCode(e.target.value)} placeholder={L.pairingExample} aria-label={L.pairingCode} autoComplete="off" spellCheck={false} />
+        <button type="button" className="ui-btn ui-btn--primary" disabled={pending} onClick={() => void go()}>{pending ? L.pairing : L.pair}</button>
+      </form>
+      {wrong && !pending ? <p role="status">{L.wrongCode}</p> : null}
+    </>
+  );
+}
+
+export interface BridgePickerOptions {
+  /** The bridge version the server installs today: an older paired one is "outdated". */
+  latest: number;
+  /** A turn is running: Stop / Remove wait for it. */
+  busy?: boolean;
+  /** Offer Stop / Remove on Status (when the selected engine goes through the bridge, and the bridge has them: v3+). */
+  controls?: boolean;
+  /** Stop / Remove pressed: close the picker (`picker.close()`), confirm a removal, then `b.control(kind)`. */
+  onControl?: (kind: "stop" | "remove") => void;
+  /** What an old bridge gets wrong on this surface (default: `labels.outdated`). */
+  outdatedDetail?: ReactNode;
+  /** Setup's note under the install command (default: `labels.installNote`): the surface adds its own lines (another
+   *  surface's bridge does not count; a server engine to pick instead). */
+  installNote?: ReactNode;
+  labels?: Partial<BridgeSetupLabels>;
+}
+
+/** The bridge state of `useBridge`, in the words of `EnginePicker` (`BridgeStatus.state`). A bridge that answers with
+ *  another code is "Not connected", not "Not set up": that label is for a machine with no bridge found (review #920). */
+export function pickerBridgeState(b: Pick<BridgeApi, "bridge" | "status">, latest: number): BridgeStatus["state"] {
+  const br = b.bridge;
+  if (br.state === "paired") return (br.version ?? 1) < latest ? "outdated" : "running";
+  if (br.state === "needs-permission" || br.state === "asking" || br.state === "blocked" || br.state === "unpaired" || br.lost || br.off) return "offline";
+  return b.status === null ? "checking" : "unpaired";
+}
+
+/**
+ * `EnginePicker`'s `bridge`, `setup` and `statusActions` for the state `useBridge` holds: the dot, the Status rows, the
+ * Setup steps for each case (allow the permission, unblock it, pair, install, update) with the command carrying this
+ * browser's code, and Check again / Stop / Remove. Nothing on the dev machine (`local`): no dot, no Setup, no Status.
+ */
+export function bridgePickerProps(b: BridgeApi, o: BridgePickerOptions): { bridge?: BridgeStatus; setup?: BridgeSetup; statusActions?: ReactNode } {
+  if (b.local) return {};
+  const L = { ...BRIDGE_SETUP_EN, ...o.labels };
+  const br = b.bridge;
+  const outdated = br.state === "paired" && (br.version ?? 1) < o.latest;
+  const permission = br.state === "needs-permission" || br.state === "asking";
+  const detail = br.state === "paired" ? (outdated ? (o.outdatedDetail ?? L.outdated) : null)
+    : permission ? L.permission
+    : br.state === "blocked" ? L.blocked
+    : br.state === "unpaired" ? L.unpaired
+    : br.lost ? L.lost
+    : br.off ? (br.off === "remove" ? L.removed : L.stopped) : null;
+  const bridge: BridgeStatus = {
+    state: pickerBridgeState(b, o.latest), detail,
+    ...(br.state === "paired" ? { version: String(br.version ?? 1), latest: String(o.latest), autostart: br.autostart } : {}),
+  };
+  const steps = permission ? (
+    <>
+      <p>{L.allowHint}{br.dismissed ? L.allowDismissed : ""}</p>
+      <div><button type="button" className="ui-btn ui-btn--primary" onClick={() => void b.allowAccess()} disabled={br.state === "asking"}>
+        {br.state === "asking" ? L.waiting : L.allow}</button></div>
+    </>
+  ) : br.state === "blocked" ? (
+    <>
+      <ol><li>{L.blockedStep1}</li><li>{L.blockedStep2}</li><li>{L.blockedStep3}</li></ol>
+      <div><button type="button" className="ui-btn" onClick={b.recheck}>{L.checkAgain}</button></div>
+    </>
+  ) : br.state === "unpaired" ? (
+    <>
+      <p>{L.pastePairing}</p>
+      <BridgePairForm onPair={b.pair} wrong={br.wrong} labels={o.labels} />
+      <p>{L.orReinstall}</p>
+    </>
+  ) : br.state === "paired" ? (
+    <p>{outdated ? L.update : L.reinstall}</p>
+  ) : (
+    <ol><li>{L.installStep1}</li><li>{L.installStep2}</li></ol>
+  );
+  // Waiting on the browser's permission: localhost cannot be called yet, so there is no command to run.
+  const needsCommand = !permission && br.state !== "blocked";
+  const setup: BridgeSetup = {
+    steps,
+    ...(needsCommand && b.pairCode ? { command: b.client.installCommand(b.pairCode) } : {}),
+    note: br.state === "paired" ? L.pairedNote : needsCommand ? (o.installNote ?? L.installNote) : undefined,
+  };
+  const statusActions = (
+    <>
+      <button type="button" className="ui-btn" onClick={b.recheck}>{L.checkAgain}</button>
+      {o.controls && br.state === "paired" ? <>
+        <button type="button" className="ui-btn" disabled={o.busy} onClick={() => o.onControl?.("stop")}>{L.stop}</button>
+        <button type="button" className="ui-btn ui-btn--critical" disabled={o.busy} onClick={() => o.onControl?.("remove")}>{L.remove}</button>
+      </> : null}
+    </>
+  );
+  return { bridge, setup, statusActions };
+}