@gemboss/ui 0.21.0 → 0.30.2

package/src/assistant/engine.tsx

@@ -0,0 +1,697 @@
+"use client";
+
+/**
+ * The assistant's ENGINE PICKER — @gemboss/ui (0.25.0, Chris 07/10/2026).
+ *
+ * One chip in the composer row: the engine's name, the model when it is not the default, and a dot for the bridge on the
+ * user's machine (green running, amber outdated, red not connected). A click opens a panel with up to three tabs:
+ *   Engine — which engine answers, its model and its effort;
+ *   Setup  — install or update the bridge: the command with a Copy button, the pairing code, a few lines of how;
+ *   Status — the bridge's state, its version against the latest, whether it starts at sign-in.
+ *
+ * Why it exists: content-radar's Radar Assistant spent close to half of its frame on an ENGINE / MODEL / EFFORT row, a
+ * yellow "The bridge on your machine is outdated…" block, the install command and a "Bridge on your machine: running"
+ * line, all above the conversation (Chris 07/10: "chèn hết vào không gian chat tốn không gian quá"). The admin already
+ * had the shape — a chip in the composer that opens a popup to pick Claude Code (apps/admin EnginePicker) — so this is
+ * that chip, with the setup and the status moved off the chat and into the same popup. A turn that FAILS because of the
+ * bridge says so in one line in the stream (`BridgeNotice`), whose "Open setup" opens this panel on the Setup tab.
+ *
+ * The package knows nothing about any bridge. The surface hands in the engines, the models, the efforts, the bridge's
+ * status, the command and the code, and hears every change through callbacks.
+ *
+ * The panel is a non-modal dialog in the browser's TOP LAYER (`popover="manual"`, placed like the kit's menus by
+ * `placeFloating`): no scrolling frame cuts it, it stays in the React tree (tokens resolve, events bubble). Escape and an
+ * outside click close it; Escape and every close from inside it give focus back to the chip. Tabs are a roving tablist
+ * (←/→/Home/End). Its look is `assistant-engine.css`, imported here: a surface that never draws the picker never loads it.
+ */
+import "../assistant-engine.css"; // its own entry (0.25.0): not in gemboss-ui.css, not in the assistant frame's sheet
+import React, { useCallback, useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { canFloatMenus, placeFloating } from "../menu-layer";
+import { EngineMark, isEngineMarkId } from "./engine-mark";
+
+const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
+const useBeforePaint = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/** running = answers now · outdated = answers, but an update is due · offline = paired, not reachable · unpaired = never
+ *  set up on this account · checking = not known yet (first poll in flight). */
+export type BridgeState = "running" | "outdated" | "offline" | "unpaired" | "checking";
+export type EnginePickerTab = "engine" | "setup" | "status";
+
+export interface EngineChoice {
+  id: string;
+  label: string;
+  /** One quiet line under the name: who pays, or why it cannot be picked ("Install Codex on that machine"). */
+  note?: ReactNode;
+  /** A short badge beside the name ("not signed in", "your plan"). */
+  badge?: string;
+  badgeTone?: "success" | "warning" | "critical" | "info";
+  /** Cannot be picked right now. Say why in `note`. */
+  disabled?: boolean;
+  /** The engine's mark ("claude", "codex": `ENGINE_MARK_ART`). The chip shows it in place of the name when the composer row
+   *  is too narrow for the name (`ChatComposer` density "icon"); an engine without one keeps its (cut) name. 0.29.0. */
+  mark?: string;
+  /** THIS engine's models. Give them on every engine and the Engine tab lists each engine with its own models, all at
+   *  once, and one click picks the engine and the model together (`onPick`): the admin's popup. 0.29.0. */
+  models?: readonly Choice[];
+}
+
+export interface Choice {
+  id: string;
+  label: string;
+  /** Tooltip: what this model or effort means. */
+  title?: string;
+  /** A heading the choice sits under ("Opus", "Sonnet"). A list with groups, or more than six choices, is a select. */
+  group?: string;
+}
+
+export interface BridgeStatus {
+  state: BridgeState;
+  /** The bridge on the machine, and the one the server would install today. */
+  version?: string;
+  latest?: string;
+  /** Starts by itself when the user signs in to that machine. Undefined: not known. */
+  autostart?: boolean;
+  /** Which machine ("Iris's MacBook"). */
+  machine?: string;
+  /** Already formatted ("2 min ago"). */
+  lastSeen?: string;
+  /** One or two sentences: what is wrong and what it costs ("Codex cannot see the radar tools"). Shown on Status and Setup. */
+  detail?: ReactNode;
+}
+
+export interface BridgeSetup {
+  /** The install / update command, pasted into a terminal. */
+  command?: string;
+  /** The pairing code the command or the bridge asks for, when it is not already in the command. */
+  pairingCode?: string;
+  /** A few lines of how (an <ol>, a sentence). Default: "Paste the command into Terminal, then press Enter." */
+  steps?: ReactNode;
+  /** Quiet text under the command ("The pairing code stays the same: the panel reconnects in a few seconds."). */
+  note?: ReactNode;
+}
+
+/** Every word the picker says. English, like every surface's chrome (Chris 03/10/2026). */
+export interface EnginePickerLabels {
+  chip: string; dialog: string; tabs: string;
+  engineTab: string; setupTab: string; statusTab: string;
+  engine: string; model: string; effort: string;
+  defaultChoice: string;
+  copy: string; copied: string; copyFailed: string; pairingCode: string; steps: string;
+  bridge: string; version: string; latest: string; startsAtSignIn: string; machine: string; lastSeen: string;
+  yes: string; no: string; unknown: string;
+  running: string; outdated: string; offline: string; unpaired: string; checking: string;
+  updateDue: string; close: string;
+}
+export const ENGINE_PICKER_EN: EnginePickerLabels = {
+  chip: "Engine", dialog: "Assistant engine", tabs: "Engine, setup and status",
+  engineTab: "Engine", setupTab: "Setup", statusTab: "Status",
+  engine: "Engine", model: "Model", effort: "Effort",
+  defaultChoice: "Default",
+  copy: "Copy command", copied: "Copied", copyFailed: "Select the command and copy it", pairingCode: "Pairing code", steps: "Paste the command into Terminal, then press Enter.",
+  bridge: "Bridge on your machine", version: "Version", latest: "Latest", startsAtSignIn: "Starts at sign-in", machine: "Machine", lastSeen: "Last seen",
+  yes: "Yes", no: "No", unknown: "Not known",
+  running: "Running", outdated: "Outdated", offline: "Not connected", unpaired: "Not set up", checking: "Checking",
+  updateDue: "Update available", close: "Close",
+};
+
+/** The dot's tone per state: one word each, so the CSS has one rule per tone and a test can read it. */
+export const BRIDGE_TONE: Record<BridgeState, "ok" | "warn" | "down" | "idle"> = {
+  running: "ok", outdated: "warn", offline: "down", unpaired: "down", checking: "idle",
+};
+/** Literal class names, never a template like `gb-engine-dot--` + tone: a runtime-built class is a stem the admin's orphan
+ *  gate (a-tap-target-rule-outlived-its-markup) would have to exempt wholesale, as host.tsx says of MODE_CLASS. */
+const DOT_CLASS = { ok: "gb-engine-dot gb-engine-dot--ok", warn: "gb-engine-dot gb-engine-dot--warn", down: "gb-engine-dot gb-engine-dot--down", idle: "gb-engine-dot gb-engine-dot--idle" } as const;
+const BADGE_CLASS = { success: "ui-badge ui-badge--success", warning: "ui-badge ui-badge--warning", critical: "ui-badge ui-badge--critical", info: "ui-badge ui-badge--info" } as const;
+const NOTICE_CLASS = { warn: "gb-engine-notice gb-engine-notice--warn", down: "gb-engine-notice gb-engine-notice--down" } as const;
+const STATE_LABEL: Record<BridgeState, keyof EnginePickerLabels> = {
+  running: "running", outdated: "outdated", offline: "offline", unpaired: "unpaired", checking: "checking",
+};
+
+export interface EnginePickerProps {
+  engines: readonly EngineChoice[];
+  engine: string;
+  onEngineChange?: (id: string) => void;
+  /** The models of the CURRENT engine. Omit (or pass []) and the row is not drawn. An id "" is "leave the CLI's own
+   *  setting in charge" and reads as "Default" on the chip (it is not shown there). */
+  models?: readonly Choice[];
+  model?: string;
+  onModelChange?: (id: string) => void;
+  /** In place of the model choices: the surface's own control (Codex takes a typed model name). */
+  modelControl?: ReactNode;
+  efforts?: readonly Choice[];
+  effort?: string;
+  onEffortChange?: (id: string) => void;
+  /** Effort cannot be set right now; a string says why (its tooltip). */
+  effortDisabled?: boolean | string;
+  /** Quiet lines under the Engine tab's fields: who pays, what this bridge version cannot do yet. */
+  notes?: ReactNode;
+  /** With models per engine (`EngineChoice.models`): one click on a model picks both, and closes the panel. Without it the
+   *  picker calls `onEngineChange` (when the engine changes) then `onModelChange`. 0.29.0. */
+  onPick?: (engine: string, model: string) => void;
+  /** A switch that did not go through ("Wait for the current answer to finish"): one red line on the Engine tab. 0.29.0. */
+  problem?: ReactNode;
+  /** The chip itself is disabled (a switch in flight). `locked` keeps the chip and disables the choices. 0.29.0. */
+  disabled?: boolean;
+  /** The bridge on the user's machine. Omit for an engine set that runs on the server only: no dot, no Status tab. */
+  bridge?: BridgeStatus;
+  /** The dot on the chip (default true when `bridge` is given). False when the current engine does not go through the
+   *  bridge (a server engine): a red dot would say "broken" about something this engine does not use. */
+  showBridgeDot?: boolean;
+  /** Omit and there is no Setup tab. */
+  setup?: BridgeSetup;
+  /** Buttons under the status rows ("Forget this machine", "Restart"). */
+  statusActions?: ReactNode;
+  /** Controlled open state and tab (a `BridgeNotice` opens Setup through these: see `useEnginePicker`). */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  tab?: EnginePickerTab;
+  onTabChange?: (tab: EnginePickerTab) => void;
+  /** While a turn runs the surface may refuse a switch: the chip stays readable, the choices are disabled. */
+  locked?: boolean;
+  /** Align the panel's right edge with the chip's (a chip near the right edge of a narrow frame). */
+  end?: boolean;
+  labels?: Partial<EnginePickerLabels>;
+  className?: string;
+}
+
+/** The open state and tab of one picker, for a surface that also renders a `BridgeNotice`:
+ *  `const p = useEnginePicker(); <EnginePicker {...p.props} …/> <BridgeNotice onOpenSetup={() => p.openTab("setup")} …/>` */
+export function useEnginePicker(initial: EnginePickerTab = "engine") {
+  const [open, setOpen] = useState(false);
+  const [tab, setTab] = useState<EnginePickerTab>(initial);
+  const openTab = useCallback((t: EnginePickerTab) => { setTab(t); setOpen(true); }, []);
+  // Closing goes back to Engine: after "Open setup" the next click on the chip is about the engine again (review #3885).
+  const onOpenChange = useCallback((v: boolean) => { setOpen(v); if (!v) setTab(initial); }, [initial]);
+  return { open, tab, setOpen, setTab, openTab, props: { open, onOpenChange, tab, onTabChange: setTab } };
+}
+
+function availableTabs(p: Pick<EnginePickerProps, "bridge" | "setup">): EnginePickerTab[] {
+  return ["engine", ...(p.setup ? ["setup" as const] : []), ...(p.bridge ? ["status" as const] : [])];
+}
+
+/** The tab shown (controlled by `tab` or held here) among the tabs the props offer; one copy for the picker and the panel. */
+function useTabs(p: Pick<EnginePickerProps, "bridge" | "setup" | "tab" | "onTabChange">) {
+  const tabs = availableTabs(p);
+  const [own, setOwn] = useState<EnginePickerTab>("engine");
+  const wanted = p.tab ?? own;
+  const tab = tabs.includes(wanted) ? wanted : "engine";
+  const { tab: controlled, onTabChange } = p;
+  const setTab = useCallback((t: EnginePickerTab) => {
+    if (controlled === undefined) setOwn(t);
+    onTabChange?.(t);
+  }, [controlled, onTabChange]);
+  return { tabs, tab, setTab, resetOwn: () => setOwn("engine") };
+}
+
+/** What the chip says out loud: the engine, the model, and the bridge when it is not fine. */
+export function engineChipName(p: Pick<EnginePickerProps, "engines" | "engine" | "models" | "model" | "bridge">, L: EnginePickerLabels = ENGINE_PICKER_EN): string {
+  const cur = p.engines.find((e) => e.id === p.engine);
+  const eng = cur?.label ?? p.engine;
+  const model = p.model ? (cur?.models ?? p.models)?.find((m) => m.id === p.model)?.label : undefined;
+  const bridge = p.bridge && p.bridge.state !== "running" ? `. ${L.bridge}: ${L[STATE_LABEL[p.bridge.state]]}` : "";
+  return `${L.chip}: ${eng}${model ? ` · ${model}` : ""}${bridge}`;
+}
+
+export function EnginePicker(props: EnginePickerProps) {
+  const { engines, engine, models, model, bridge, end = false, className } = props;
+  const L = { ...ENGINE_PICKER_EN, ...props.labels };
+  const [ownOpen, setOwnOpen] = useState(false);
+  const open = props.open ?? ownOpen;
+  const { tabs, tab, setTab, resetOwn } = useTabs(props);
+  // Without the popover API (Safari < 17) a fixed layer inside the assistant's frame is cut by it (overflow, and the
+  // frame's backdrop-filter makes it the containing block): there the panel goes to <body> through a portal instead.
+  // Decided after mount, so the server and the first client render agree.
+  const [portal, setPortal] = useState(false);
+  useEffect(() => { setPortal(!canFloatMenus()); }, []);
+  const chipRef = useRef<HTMLButtonElement>(null);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const panelId = useId();
+
+  const setOpen = useCallback((v: boolean) => {
+    if (props.open === undefined) setOwnOpen(v);
+    if (!v) resetOwn();
+    props.onOpenChange?.(v);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [props.open, props.onOpenChange]);
+  /** Close and put focus back on the chip: Escape, a pick, the close button. An outside click closes without it (the
+   *  click already moved focus where the user wanted it). */
+  const closeToChip = useCallback(() => { setOpen(false); chipRef.current?.focus(); }, [setOpen]);
+
+  // Float / sink with `open`, before paint, so the panel is never drawn unplaced.
+  useBeforePaint(() => {
+    const panel = panelRef.current, chip = chipRef.current;
+    if (!panel || !chip) return;
+    if (!open) {
+      if (canFloatMenus() && panel.matches(":popover-open")) panel.hidePopover();
+      return;
+    }
+    if (canFloatMenus() && !panel.matches(":popover-open")) panel.showPopover();
+    placeFloating(panel, chip, end);
+  }, [open, end, tab]);
+
+  // While open: Escape, outside pointer, and keep it against the chip when the window or a frame around the chip moves.
+  useEffect(() => {
+    if (!open) return undefined;
+    const panel = panelRef.current, chip = chipRef.current;
+    if (!panel || !chip) return undefined;
+    // Escape with focus in the panel or on the chip closes the panel only: captured first and stopped, so the surface's
+    // own Escape (hide the assistant) does not fire on the same key. With focus elsewhere (the composer), it closes the
+    // panel and leaves focus alone, and marks the key handled (0.27.0): a surface whose "Escape hides the assistant"
+    // checks `defaultPrevented` waits for the next Escape. Before 0.27.0 the key went on unmarked, and React re-renders
+    // between this listener and the surface's, so every surface (gemlabs #922, gemfeedback #66) needed a window-capture
+    // marker to tell "this Escape closed the picker" from "this one is mine".
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || e.defaultPrevented) return;
+      // Not ours: an IME composition (Escape cancels it; the kit's rule, kit-plain.js), or a modal opened from the panel.
+      if (e.isComposing || e.keyCode === 229) return;
+      const a = document.activeElement;
+      const modal = a?.closest?.('dialog[open], [aria-modal="true"]');
+      if (modal && !panel.contains(modal)) return;
+      e.preventDefault();
+      if (a && (panel.contains(a) || chip.contains(a))) { e.stopPropagation(); closeToChip(); }
+      else setOpen(false);
+    };
+    const onDown = (e: PointerEvent) => {
+      const t = e.target as Node;
+      if (!panel.contains(t) && !chip.contains(t)) setOpen(false);
+    };
+    // A modal opened from the panel (a confirm behind a Status action) takes the screen: the panel would stay above it in
+    // the top layer, over its buttons (review #3903). Close the panel when focus enters a modal that is not the panel.
+    const onFocusIn = (e: FocusEvent) => {
+      const m = (e.target as Element | null)?.closest?.('dialog[open], [aria-modal="true"]');
+      if (m && !panel.contains(m)) setOpen(false);
+    };
+    const replace = () => placeFloating(panel, chip, end);
+    // A scroll moves the panel's anchor only when it scrolls something that holds the chip (the page, a frame around the
+    // composer): a chat log streaming beside it does not. One placement per frame at most.
+    let frame = 0;
+    const onScroll = (e: Event) => {
+      const t = e.target as Node | null;
+      if (!t || panel.contains(t)) return;
+      if (t !== document && (t as Node).nodeType !== 9 && !t.contains(chip)) return;
+      if (!frame) frame = requestAnimationFrame(() => { frame = 0; replace(); });
+    };
+    // Its content changes while open (a poll turns "Allow connection" into the command): re-place on its own resize, or a
+    // taller panel runs off the bottom of the screen. placeFloating writes max-height, which the observer ignores (it
+    // only fires when the box changes size, and a clamp to the same room settles at once).
+    let lastH = -1;
+    const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
+      if (panel.scrollHeight === lastH) return;
+      lastH = panel.scrollHeight;
+      replace();
+    });
+    // The panel (it grows while it fits) and its pane (content that grows past a clamped panel).
+    ro?.observe(panel);
+    const pane = panel.querySelector(".gb-engine-pane");
+    if (pane) ro?.observe(pane);
+    document.addEventListener("keydown", onKey, true);
+    document.addEventListener("pointerdown", onDown, true);
+    document.addEventListener("focusin", onFocusIn, true);
+    document.addEventListener("scroll", onScroll, true);
+    window.addEventListener("resize", replace);
+    return () => {
+      document.removeEventListener("keydown", onKey, true);
+      cancelAnimationFrame(frame);
+      document.removeEventListener("pointerdown", onDown, true);
+      document.removeEventListener("focusin", onFocusIn, true);
+      document.removeEventListener("scroll", onScroll, true);
+      window.removeEventListener("resize", replace);
+      ro?.disconnect();
+    };
+  }, [open, end, closeToChip, setOpen]);
+
+  // Focus goes INTO the panel on open (the selected tab), so a keyboard user lands where the choices are.
+  useEffect(() => {
+    if (!open) return;
+    const t = panelRef.current?.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
+      ?? panelRef.current?.querySelector<HTMLElement>("button:not([disabled])");
+    t?.focus();
+    // Only on opening: a tab change moves focus by itself (the roving keys), a pick closes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  const current = engines.find((e) => e.id === engine);
+  const modelLabel = model ? (current?.models ?? models)?.find((m) => m.id === model)?.label : undefined;
+  const mark = current?.mark && isEngineMarkId(current.mark) ? current.mark : null;
+  const tone = bridge && props.showBridgeDot !== false ? BRIDGE_TONE[bridge.state] : null;
+  const name = engineChipName(props.showBridgeDot === false ? { ...props, bridge: undefined } : props, L);
+
+  return (
+    <span className={cx("gb-engine", className)}>
+      <button
+        ref={chipRef}
+        type="button"
+        className={mark ? "gb-engine-chip has-mark" : "gb-engine-chip"}
+        disabled={props.disabled || undefined}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-controls={panelId}
+        aria-label={name}
+        title={name}
+        onClick={() => setOpen(!open)}
+      >
+        {tone ? <span className={DOT_CLASS[tone]} aria-hidden /> : null}
+        <span className="gb-engine-chiplabel">
+          {current?.label ?? engine}
+          {modelLabel ? <span className="gb-engine-chipsub"> · {modelLabel}</span> : null}
+        </span>
+        {/* Shown instead of the name when the composer is too narrow for it (assistant-engine.css, ChatComposer density). */}
+        {mark ? <span className="gb-engine-chipmark"><EngineMark engine={mark} decorative /></span> : null}
+      </button>
+      {(() => { const panelEl = (<div
+        ref={panelRef}
+        id={panelId}
+        className="gb-engine-panel gemboss-popover-surface"
+        role="dialog"
+        aria-label={L.dialog}
+        // The top layer where the browser has one; otherwise a fixed layer in the tree (assistant-engine.css).
+        {...(portal ? {} : { popover: "manual" })}
+        hidden={!open}
+        data-open={open ? "" : undefined}
+      >
+        {open ? <PanelBody {...props} L={L} tab={tab} tabs={tabs} setTab={setTab} onPicked={closeToChip} /> : null}
+      </div>);
+      return portal && typeof document !== "undefined" ? createPortal(panelEl, document.body) : panelEl; })()}
+    </span>
+  );
+}
+
+/** The panel's content, also exported on its own (`EnginePanel`) for the catalog and for a settings page that shows it
+ *  in place, without a chip. */
+function PanelBody({ L, tab, tabs, setTab, onPicked, ...p }: EnginePickerProps & {
+  L: EnginePickerLabels; tab: EnginePickerTab; tabs: EnginePickerTab[]; setTab: (t: EnginePickerTab) => void; onPicked?: () => void;
+}) {
+  const base = useId();
+  const tabRefs = useRef<Partial<Record<EnginePickerTab, HTMLButtonElement | null>>>({});
+  const tabLabel: Record<EnginePickerTab, string> = { engine: L.engineTab, setup: L.setupTab, status: L.statusTab };
+  const needsUpdate = p.bridge?.state === "outdated";
+  const onTabKey = (e: React.KeyboardEvent) => {
+    const i = tabs.indexOf(tab);
+    const to = e.key === "ArrowRight" ? tabs[(i + 1) % tabs.length]
+      : e.key === "ArrowLeft" ? tabs[(i - 1 + tabs.length) % tabs.length]
+      : e.key === "Home" ? tabs[0] : e.key === "End" ? tabs[tabs.length - 1] : null;
+    if (!to) return;
+    e.preventDefault();
+    setTab(to);
+    tabRefs.current[to]?.focus();
+  };
+  return (
+    <>
+      {tabs.length > 1 ? (
+        <div className="ui-tabs gb-engine-tabs" role="tablist" aria-label={L.tabs} onKeyDown={onTabKey}>
+          {tabs.map((t) => (
+            <button
+              key={t}
+              ref={(el) => { tabRefs.current[t] = el; }}
+              type="button"
+              role="tab"
+              id={`${base}-tab-${t}`}
+              aria-controls={`${base}-pane-${t}`}
+              aria-selected={tab === t}
+              tabIndex={tab === t ? 0 : -1}
+              onClick={() => setTab(t)}
+            >
+              {tabLabel[t]}
+              {/* The same warning the chip's dot gives, on the tab that fixes it. */}
+              {t === "setup" && needsUpdate ? <span className="gb-engine-dot gb-engine-dot--warn" role="img" aria-label={L.updateDue} /> : null}
+            </button>
+          ))}
+        </div>
+      ) : null}
+      <div
+        className="gb-engine-pane"
+        role={tabs.length > 1 ? "tabpanel" : undefined}
+        id={`${base}-pane-${tab}`}
+        aria-labelledby={tabs.length > 1 ? `${base}-tab-${tab}` : undefined}
+      >
+        {tab === "engine" ? <EngineTab {...p} L={L} onPicked={onPicked} /> : null}
+        {tab === "setup" ? <SetupTab setup={p.setup!} bridge={p.bridge} L={L} /> : null}
+        {tab === "status" ? <StatusTab bridge={p.bridge!} actions={p.statusActions} L={L} /> : null}
+      </div>
+    </>
+  );
+}
+
+/** The panel without the chip: the catalog, or a settings page that shows the same three tabs in place. */
+export function EnginePanel(props: EnginePickerProps) {
+  const L = { ...ENGINE_PICKER_EN, ...props.labels };
+  const { tabs, tab, setTab } = useTabs(props);
+  return (
+    <div className={cx("gb-engine-panel gb-engine-panel--inline gemboss-popover-surface", props.className)} role="group" aria-label={L.dialog}>
+      <PanelBody {...props} L={L} tab={tab} tabs={tabs} setTab={setTab} />
+    </div>
+  );
+}
+
+function Options({ label, items, value, onChange, locked, onPicked, disabledReason }: {
+  label: string; items: readonly Choice[]; value: string | undefined; onChange?: (id: string) => void; locked?: boolean; onPicked?: () => void;
+  disabledReason?: boolean | string;
+}) {
+  const id = useId();
+  const off = locked || !onChange || Boolean(disabledReason);
+  const why = typeof disabledReason === "string" ? disabledReason : undefined;
+  // Many choices (Claude Code knows ~20 models) or grouped ones: a select, not a wall of buttons.
+  if (items.length > 6 || items.some((m) => m.group)) {
+    const groups: Array<{ label?: string; items: Choice[] }> = [];
+    for (const m of items) {
+      const last = groups[groups.length - 1];
+      if (last && last.label === m.group) last.items.push(m); else groups.push({ label: m.group, items: [m] });
+    }
+    const opt = (m: Choice) => <option key={m.id || "default"} value={m.id} title={m.title}>{m.label}</option>;
+    return (
+      <label className="gb-engine-field">
+        <span className="gb-engine-label">{label}</span>
+        <select className="ui-select ui-select--slim gb-engine-select" value={value ?? ""} disabled={off} title={why}
+          onChange={(e) => { onChange?.(e.target.value); }}>
+          {groups.map((g, i) => (g.label ? <optgroup key={g.label + i} label={g.label}>{g.items.map(opt)}</optgroup> : g.items.map(opt)))}
+        </select>
+      </label>
+    );
+  }
+  return (
+    <div className="gb-engine-field">
+      <span className="gb-engine-label" id={id}>{label}</span>
+      <div className="gb-engine-opts" role="group" aria-labelledby={id}>
+        {items.map((m) => (
+          <button
+            key={m.id || "default"}
+            type="button"
+            className="gb-engine-opt"
+            aria-pressed={(value ?? "") === m.id}
+            disabled={off}
+            title={why ?? m.title}
+            onClick={() => { if ((value ?? "") !== m.id) onChange?.(m.id); onPicked?.(); }}
+          >
+            {m.label}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/** Every engine with its own models, all at once; one click picks both (the admin's popup, 0.29.0). */
+function EngineGroups({ engines, engine, model, onPick, onEngineChange, onModelChange, locked, L, onPicked }: EnginePickerProps & { L: EnginePickerLabels; onPicked?: () => void }) {
+  const id = useId();
+  const choose = (e: EngineChoice, m: Choice) => {
+    // The pick already in force: close, change nothing (a surface that starts a new conversation on a switch must not).
+    if (e.id === engine && (model ?? "") === m.id) { onPicked?.(); return; }
+    if (onPick) onPick(e.id, m.id);
+    else { if (e.id !== engine) onEngineChange?.(e.id); onModelChange?.(m.id); }
+    onPicked?.();
+  };
+  const canChoose = Boolean(onPick || onEngineChange || onModelChange);
+  return (
+    <div className="gb-engine-field">
+      <span className="gb-engine-label" id={id}>{L.engine}</span>
+      <div className="gb-engine-groups" role="group" aria-labelledby={id}>
+        {engines.map((e) => {
+          const chosen = e.id === engine;
+          const items = e.models && e.models.length ? e.models : [{ id: "", label: L.defaultChoice }];
+          return (
+            <div key={e.id} className="gb-engine-group" data-current={chosen ? "" : undefined}>
+              <span className="gb-engine-rowhead">
+                <span className="gb-engine-rowname">{e.label}</span>
+                {e.badge ? <span className={e.badgeTone ? BADGE_CLASS[e.badgeTone] : "ui-badge"}>{e.badge}</span> : null}
+              </span>
+              {e.note ? <span className="gb-engine-note">{e.note}</span> : null}
+              <div className="gb-engine-opts" role="group" aria-label={e.label}>
+                {items.map((m) => (
+                  <button key={m.id || "default"} type="button" className="gb-engine-opt" title={m.title}
+                    aria-pressed={chosen && (model ?? "") === m.id}
+                    disabled={locked || e.disabled || !canChoose}
+                    onClick={() => choose(e, m)}>
+                    {m.label}
+                  </button>
+                ))}
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+function EngineTab(props: EnginePickerProps & { L: EnginePickerLabels; onPicked?: () => void }) {
+  const { engines, engine, onEngineChange, models, model, onModelChange, modelControl, efforts, effort, onEffortChange, effortDisabled, notes, locked, L, onPicked } = props;
+  const id = useId();
+  if (engines.some((e) => e.models && e.models.length)) {
+    return (
+      <>
+        <EngineGroups {...props} />
+        {efforts && efforts.length ? <Options label={L.effort} items={efforts} value={effort} onChange={onEffortChange} locked={locked} onPicked={onPicked} disabledReason={effortDisabled} /> : null}
+        {props.problem ? <p className="gb-engine-problem" role="alert">{props.problem}</p> : null}
+        {notes ? <div className="gb-engine-notes">{notes}</div> : null}
+      </>
+    );
+  }
+  // The ARIA radio pattern: one Tab stop (the checked engine, else the first that can be picked); arrows move AND pick.
+  const can = (e: EngineChoice) => !(locked || e.disabled || !onEngineChange);
+  const stop = engines.find((e) => e.id === engine && can(e))?.id ?? engines.find(can)?.id;
+  const onKey = (ev: React.KeyboardEvent<HTMLDivElement>) => {
+    const dir = ev.key === "ArrowDown" || ev.key === "ArrowRight" ? 1 : ev.key === "ArrowUp" || ev.key === "ArrowLeft" ? -1 : 0;
+    if (!dir) return;
+    const open = engines.filter(can);
+    if (!open.length) return;
+    ev.preventDefault();
+    const from = open.findIndex((e) => e.id === (ev.target as HTMLElement).dataset.engine);
+    const next = open[(from + dir + open.length) % open.length];
+    if (next.id !== engine) onEngineChange?.(next.id);
+    ev.currentTarget.querySelector<HTMLElement>(`[data-engine="${CSS.escape(next.id)}"]`)?.focus();
+  };
+  return (
+    <>
+      <div className="gb-engine-field">
+        <span className="gb-engine-label" id={id}>{L.engine}</span>
+        <div className="gb-engine-list" role="radiogroup" aria-labelledby={id} onKeyDown={onKey}>
+          {engines.map((e) => (
+            <button
+              key={e.id}
+              type="button"
+              role="radio"
+              aria-checked={e.id === engine}
+              data-engine={e.id}
+              tabIndex={e.id === stop ? 0 : -1}
+              className="gb-engine-row"
+              disabled={!can(e)}
+              // A new engine keeps the panel open: its models and efforts are the next thing to look at.
+              onClick={() => { if (e.id !== engine) onEngineChange?.(e.id); }}
+            >
+              <span className="gb-engine-rowhead">
+                <span className="gb-engine-rowname">{e.label}</span>
+                {e.badge ? <span className={e.badgeTone ? BADGE_CLASS[e.badgeTone] : "ui-badge"}>{e.badge}</span> : null}
+              </span>
+              {e.note ? <span className="gb-engine-note">{e.note}</span> : null}
+            </button>
+          ))}
+        </div>
+      </div>
+      {modelControl ? (
+        <div className="gb-engine-field"><span className="gb-engine-label">{L.model}</span>{modelControl}</div>
+      ) : models && models.length ? <Options label={L.model} items={models} value={model} onChange={onModelChange} locked={locked} onPicked={onPicked} /> : null}
+      {efforts && efforts.length ? <Options label={L.effort} items={efforts} value={effort} onChange={onEffortChange} locked={locked} onPicked={onPicked} disabledReason={effortDisabled} /> : null}
+      {props.problem ? <p className="gb-engine-problem" role="alert">{props.problem}</p> : null}
+      {notes ? <div className="gb-engine-notes">{notes}</div> : null}
+    </>
+  );
+}
+
+/** Copies through the async clipboard, else through a selected textarea (an http:// page, an old Safari). */
+export async function copyText(text: string): Promise<boolean> {
+  try {
+    if (navigator.clipboard?.writeText) { await navigator.clipboard.writeText(text); return true; }
+  } catch { /* permission refused: try the old way */ }
+  try {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.setAttribute("readonly", "");
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    const ok = document.execCommand("copy");
+    ta.remove();
+    return ok;
+  } catch { return false; }
+}
+
+function SetupTab({ setup, bridge, L }: { setup: BridgeSetup; bridge?: BridgeStatus; L: EnginePickerLabels }) {
+  const [said, setSaid] = useState<"" | "copied" | "failed">("");
+  const timer = useRef<number | undefined>(undefined);
+  useEffect(() => () => window.clearTimeout(timer.current), []);
+  const copy = async () => {
+    if (!setup.command) return;
+    const ok = await copyText(setup.command);
+    setSaid(ok ? "copied" : "failed");
+    window.clearTimeout(timer.current);
+    timer.current = window.setTimeout(() => setSaid(""), 2000);
+  };
+  return (
+    <>
+      {bridge?.state === "outdated" || bridge?.state === "offline" || bridge?.state === "unpaired" ? (
+        <p className={cx("gb-engine-callout", bridge.state === "outdated" ? "gb-engine-callout--warn" : "gb-engine-callout--down")}>
+          <strong>{L.bridge}: {L[STATE_LABEL[bridge.state]].toLowerCase()}.</strong>
+          {bridge.detail ? <> {bridge.detail}</> : null}
+        </p>
+      ) : null}
+      {setup.steps || setup.command ? <div className="gb-engine-steps">{setup.steps ?? <p>{L.steps}</p>}</div> : null}
+      {setup.command ? (
+        <>
+          <pre className="gb-engine-cmd"><code>{setup.command}</code></pre>
+          <div className="gb-engine-actions">
+            <button type="button" className="ui-btn ui-btn--primary" onClick={() => void copy()}>
+              {said === "copied" ? L.copied : L.copy}
+            </button>
+            <span className="gb-engine-said" role="status">{said === "failed" ? L.copyFailed : said === "copied" ? L.copied : ""}</span>
+          </div>
+        </>
+      ) : null}
+      {setup.pairingCode ? (
+        <p className="gb-engine-code">{L.pairingCode}: <code>{setup.pairingCode}</code></p>
+      ) : null}
+      {setup.note ? <p className="gb-engine-note">{setup.note}</p> : null}
+    </>
+  );
+}
+
+function StatusTab({ bridge, actions, L }: { bridge: BridgeStatus; actions?: ReactNode; L: EnginePickerLabels }) {
+  const tone = BRIDGE_TONE[bridge.state];
+  const yesNo = (v: boolean | undefined) => (v === undefined ? L.unknown : v ? L.yes : L.no);
+  return (
+    <>
+      <dl className="gb-engine-rows">
+        <dt>{L.bridge}</dt>
+        <dd><span className={DOT_CLASS[tone]} aria-hidden /> {L[STATE_LABEL[bridge.state]]}</dd>
+        {bridge.version ? <><dt>{L.version}</dt><dd>{bridge.version}{bridge.latest && bridge.latest !== bridge.version ? ` · ${L.latest} ${bridge.latest}` : ""}</dd></> : null}
+        <dt>{L.startsAtSignIn}</dt><dd>{yesNo(bridge.autostart)}</dd>
+        {bridge.machine ? <><dt>{L.machine}</dt><dd>{bridge.machine}</dd></> : null}
+        {bridge.lastSeen ? <><dt>{L.lastSeen}</dt><dd>{bridge.lastSeen}</dd></> : null}
+      </dl>
+      {bridge.detail && bridge.state !== "running" ? <p className="gb-engine-note">{bridge.detail}</p> : null}
+      {actions ? <div className="gb-engine-actions">{actions}</div> : null}
+    </>
+  );
+}
+
+/**
+ * ONE line in the chat stream, for a turn that actually failed because of the bridge ("The bridge on your machine is
+ * not connected."), with "Open setup" that opens the picker on its Setup tab. Never a standing block: the chip's dot says
+ * "outdated" all the time, this says "this turn failed, here is why" once.
+ */
+export function BridgeNotice({ children, onOpenSetup, action = "Open setup", tone = "down", className }: {
+  children: ReactNode;
+  onOpenSetup?: () => void;
+  action?: string;
+  tone?: "warn" | "down";
+  className?: string;
+}) {
+  return (
+    <p className={cx(NOTICE_CLASS[tone], className)} role="status">
+      <span className={DOT_CLASS[tone]} aria-hidden />
+      <span className="gb-engine-notice-text">{children}</span>
+      {onOpenSetup ? <button type="button" className="gb-engine-notice-link" onClick={onOpenSetup}>{action}</button> : null}
+    </p>
+  );
+}