@gemboss/ui 0.21.0 → 0.25.0

package/src/assistant/engine.tsx

@@ -0,0 +1,607 @@
+"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";
+
+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;
+}
+
+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;
+  /** 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 eng = p.engines.find((e) => e.id === p.engine)?.label ?? p.engine;
+  const model = p.model ? 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 and the key alone.
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape" || e.defaultPrevented) return;
+      const a = document.activeElement;
+      if (a && (panel.contains(a) || chip.contains(a))) { e.preventDefault(); 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);
+    };
+    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("scroll", onScroll, true);
+    window.addEventListener("resize", replace);
+    return () => {
+      document.removeEventListener("keydown", onKey, true);
+      cancelAnimationFrame(frame);
+      document.removeEventListener("pointerdown", onDown, 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 ? models?.find((m) => m.id === model)?.label : undefined;
+  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="gb-engine-chip"
+        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>
+      </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>
+  );
+}
+
+function EngineTab({ engines, engine, onEngineChange, models, model, onModelChange, modelControl, efforts, effort, onEffortChange, effortDisabled, notes, locked, L, onPicked }: EnginePickerProps & { L: EnginePickerLabels; onPicked?: () => void }) {
+  const id = useId();
+  // 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}
+      {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). */
+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>
+  );
+}

package/src/assistant/host.tsx

@@ -12,6 +12,7 @@
  * assistant is unmounted by the next menu click, and unmounting aborts the run. Geometry only changes
  * class names; the subtree is never re-parented (that would remount the chat and abort the run too).
  */
+import "../assistant.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
 import React, { useCallback, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
 
 import { DOCK_MIN_HEIGHT, SIDE_MIN_WIDTH, clampDockHeight, clampSideWidth } from "./dock";

package/src/assistant/index.ts

@@ -4,3 +4,4 @@ export { AssistantHost, type AssistantHostLabels, type AssistantSecondTab } from
 export { AssistantProvider, SIDE_WIDTH_VAR, useAssistant, useAssistantPageFacts, type AssistantDockApi, type AssistantOptions } from "./provider";
 export * from "./dock";
 export { AssistantWorkspaceLayout, OpenChatTabs, SessionRail, SESSION_RAIL_EN, groupSessions, normalizeForSearch, relativeTime, type AssistantSession, type SessionGroup, type SessionRailIcons, type SessionRailLabels } from "./sessions";
+export { BRIDGE_TONE, BridgeNotice, ENGINE_PICKER_EN, EnginePanel, EnginePicker, engineChipName, useEnginePicker, type BridgeSetup, type BridgeState, type BridgeStatus, type Choice, type EngineChoice, type EnginePickerLabels, type EnginePickerProps, type EnginePickerTab } from "./engine";

package/src/assistant-engine.css

@@ -0,0 +1 @@
+.gb-engine{display:inline-flex;min-width:0;max-width:100%}.gb-engine-chip{display:inline-flex;align-items:center;gap:6px;min-width:0;max-width:100%;box-sizing:border-box;height:var(--ui-btn-h, 28px);padding:0 24px 0 8px;font:inherit;font-size:var(--ui-fs-caption, 12px);font-weight:500;line-height:20px;white-space:nowrap;color:var(--ui-text-muted);background-color:transparent;border:1px solid transparent;border-radius:var(--ui-radius-md, 8px);cursor:pointer;background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'%3E%3Cpath d='M1 1l4 4 4-4' fill='none' stroke='%23686b71' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");background-repeat:no-repeat;background-position:right 8px center}@media (hover: hover){.gb-engine-chip:hover{color:var(--ui-text);background-color:var(--gemboss-hover, rgba(0,0,0,.05))}}@media (hover: none){.gb-engine-chip{color:var(--ui-text)}}.gb-engine-chip[aria-expanded=true]{color:var(--ui-text);background-color:var(--gemboss-hover, rgba(0,0,0,.05))}.gb-engine-chip:focus-visible{color:var(--ui-text);outline:2px solid var(--ui-focus);outline-offset:2px}.gb-engine-chiplabel{min-width:0;overflow:hidden;text-overflow:ellipsis}.gb-engine-chipsub{font-weight:450}.gb-engine-dot{flex:none;display:inline-block;width:8px;height:8px;border-radius:50%;background:var(--ui-text-muted);vertical-align:middle}.gb-engine-dot--ok{background:var(--gemboss-success, #007f5f)}.gb-engine-dot--warn{background:#e8a10a;box-shadow:0 0 0 1px var(--gemboss-warning, #9a6700) inset}.gb-engine-dot--down{background:var(--gemboss-danger, #d72c0d)}.gb-engine-dot--idle{background:transparent;box-shadow:0 0 0 1.5px var(--ui-text-muted) inset}.gb-engine-panel{position:fixed;z-index:1000;inset:auto;margin:0;width:min(360px,calc(100vw - 16px));box-sizing:border-box;overflow:auto;overscroll-behavior:contain;padding:0 0 var(--ui-space-3, 12px);color:var(--ui-text);font-size:var(--ui-fs-caption, 12px);line-height:16px}.gb-engine-panel[hidden],.gb-engine-panel[popover]:not(:popover-open):not([data-open]){display:none}:where(.gb-engine-panel[popover]){border:0;background:none;color:inherit}.gb-engine-panel--inline{position:static;z-index:auto;overflow:visible}.gb-engine-tabs{padding:0 var(--ui-space-2, 8px)}.gb-engine-tabs>button{gap:6px}.gb-engine-pane{display:grid;gap:var(--ui-space-3, 12px);padding:var(--ui-space-3, 12px) var(--ui-space-3, 12px) 0}.gb-engine-pane p{margin:0}.gb-engine-field{display:grid;gap:6px}.gb-engine-label{font-weight:550;color:var(--ui-text-strong, var(--ui-text))}.gb-engine-note{color:var(--ui-text-muted)}.gb-engine-list{display:grid;border:1px solid var(--ui-border);border-radius:var(--ui-radius-md, 8px);overflow:hidden}.gb-engine-row{display:grid;gap:2px;min-height:44px;padding:6px 10px 6px 32px;box-sizing:border-box;position:relative;font:inherit;text-align:left;color:inherit;background:transparent;border:0;cursor:pointer}.gb-engine-row+.gb-engine-row{border-top:1px solid var(--ui-border)}.gb-engine-row:before{content:"";position:absolute;left:10px;top:50%;width:14px;height:14px;margin-top:-7px;box-sizing:border-box;border:1.5px solid var(--ui-text-muted);border-radius:50%}.gb-engine-row[aria-checked=true]{background:var(--gemboss-active-bg, #f0f1f4)}.gb-engine-row[aria-checked=true]:before{border:4.5px solid var(--ui-accent)}.gb-engine-row[aria-checked=true] .gb-engine-rowname{font-weight:600}@media (hover: hover){.gb-engine-row:hover:not(:disabled){background:var(--ui-surface-2)}}.gb-engine-row:focus-visible{outline:2px solid var(--ui-focus);outline-offset:-2px}.gb-engine-row:disabled{cursor:not-allowed}.gb-engine-row:disabled .gb-engine-rowname{color:var(--ui-text-muted)}.gb-engine-rowhead{display:flex;align-items:center;gap:var(--ui-space-2, 8px);min-width:0}.gb-engine-rowname{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-weight:450}.gb-engine-opts{display:flex;flex-wrap:wrap;gap:var(--ui-space-2, 8px)}.gb-engine-opt{height:var(--ui-btn-h, 28px);padding:0 10px;box-sizing:border-box;font:inherit;font-weight:500;color:var(--ui-text);background:transparent;border:1px solid var(--ui-border);border-radius:var(--ui-radius-md, 8px);cursor:pointer}@media (hover: hover){.gb-engine-opt:hover:not(:disabled){background:var(--ui-surface-2)}}.gb-engine-opt[aria-pressed=true]{background:var(--gemboss-active-bg, #f0f1f4);border-color:var(--ui-text);font-weight:600}.gb-engine-opt:focus-visible{outline:2px solid var(--ui-focus);outline-offset:2px}.gb-engine-opt:disabled{opacity:.5;cursor:not-allowed}.gb-engine-select{width:100%}.gb-engine-notes{display:grid;gap:4px;color:var(--ui-text-muted)}.gb-engine-notes p{margin:0}.gb-engine-callout{padding:8px 10px;border-radius:var(--ui-radius-md, 8px);border:1px solid}.gb-engine-callout--warn{background:var(--gemboss-warning-soft, #fff8e0);border-color:var(--gemboss-warning-border, #f5d569);color:var(--gemboss-warning, #9a6700)}.gb-engine-callout--down{background:var(--gemboss-danger-soft, #fff0e9);border-color:var(--gemboss-danger-border, #f5c9bc);color:var(--gemboss-danger-strong, #b42318)}.gb-engine-steps ol,.gb-engine-steps ul{margin:0;padding-left:18px;display:grid;gap:4px}.gb-engine-cmd{margin:0;padding:8px 10px;border-radius:var(--ui-radius-md, 8px);background:var(--ui-surface-2);border:1px solid var(--ui-border);font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11.5px;line-height:16px;white-space:pre-wrap;word-break:break-all;user-select:all;max-height:96px;overflow:auto}.gb-engine-cmd code{padding:0;border:0;background:none;font:inherit;color:inherit}.gb-engine-actions{display:flex;flex-wrap:wrap;align-items:center;gap:var(--ui-space-2, 8px)}.gb-engine-said{color:var(--ui-text-muted)}.gb-engine-said:empty{display:none}.gb-engine-code code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-weight:600;letter-spacing:.04em;user-select:all}.gb-engine-rows{display:grid;grid-template-columns:auto 1fr;gap:6px 12px;margin:0}.gb-engine-rows dt{color:var(--ui-text-muted)}.gb-engine-rows dd{margin:0;display:flex;align-items:center;gap:6px;min-width:0;overflow-wrap:anywhere}.gb-engine-notice{display:flex;flex-wrap:wrap;align-items:center;gap:4px 8px;margin:0;padding:4px 0;font-size:var(--ui-fs-caption, 12px);line-height:16px;color:var(--ui-text-muted)}.gb-engine-notice>.gb-engine-dot{margin-right:-2px}.gb-engine-notice--down .gb-engine-notice-text,.gb-engine-notice--warn .gb-engine-notice-text{color:var(--ui-text)}.gb-engine-notice-text{min-width:0;flex:0 1 auto}.gb-engine-notice-link{flex:none;position:relative;padding:0;border:0;background:none;font:inherit;font-weight:550;color:var(--ui-accent);text-decoration:underline;text-underline-offset:2px;cursor:pointer}.gb-engine-notice-link:after{content:"";position:absolute;inset:-4px}.gb-engine-notice-link:focus-visible{outline:2px solid var(--ui-focus);outline-offset:2px;border-radius:2px}@media (pointer: coarse),(max-width: 47.9975em){.gb-engine-chip{min-height:44px}.gb-engine-opt{min-height:44px;min-width:44px}.gb-engine-notice-link:after{inset:-14px -8px}}@media (prefers-reduced-motion: no-preference){.gb-engine-chip,.gb-engine-opt,.gb-engine-row{transition:background-color .12s ease,color .12s ease}}

package/src/auth.tsx

@@ -13,6 +13,7 @@
  * the dark theme. Re-theme it by redefining the `--gb-*` tokens on `.gb-auth` (see auth.css), never
  * by restyling its classes.
  */
+import "./auth.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
 import React, { useEffect, useRef, useState } from "react";
 
 import { GemMark } from "./GemMark";

package/src/collections.tsx

@@ -15,6 +15,7 @@
  * Polaris; same reasoning as ./page). The markup is the same as the plain-HTML contract in the catalog, so a surface
  * without React writes these classes by hand and gets the same thing.
  */
+import "./collections.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
 import React from "react";
 import { attachBoardMove } from "./board-move";