@gemboss/ui 0.51.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,41 +1,36 @@
1
1
  "use client";
2
2
 
3
3
  /**
4
- * The assistant's ENGINE PICKER — @gemboss/ui (0.25.0, Chris 07/10/2026).
4
+ * The assistant's ENGINE PICKER — @gemboss/ui (0.25.0, Chris 07/10/2026; a door to Settings since 0.52.0, only that since 0.53.0).
5
5
  *
6
6
  * 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
7
- * user's machine (green running, amber outdated, red not connected). A click opens a panel with up to three tabs:
8
- * Engine — which engine answers, its model and its effort;
9
- * Setup — install or update the bridge: the command with a Copy button, the pairing code, a few lines of how;
10
- * Status — the bridge's state, its version against the latest, whether it starts at sign-in.
7
+ * user's machine (green running, amber outdated, red not connected). A click opens the surface's SETTINGS on its
8
+ * "AI & engines" section (`onOpenSettings`), which draws what the chip publishes (`EngineSettingsSection`,
9
+ * engine-settings.tsx): Engine (which engine answers, its model, its effort) and Bridge on your machine (what is wrong, its
10
+ * state, its actions, then Install or update: the command with Copy, the pairing code).
11
11
  *
12
- * Why it exists: content-radar's Radar Assistant spent close to half of its frame on an ENGINE / MODEL / EFFORT row, a
13
- * yellow "The bridge on your machine is outdated…" block, the install command and a "Bridge on your machine: running"
14
- * 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
15
- * had the shape — a chip in the composer that opens a popup to pick Claude Code (apps/admin EnginePicker) — so this is
16
- * that chip, with the setup and the status moved off the chat and into the same popup. A turn that FAILS because of the
17
- * bridge says so in one line in the stream (`BridgeNotice`), whose "Open setup" opens this panel on the Setup tab.
12
+ * Why: content-radar's Radar Assistant once spent close to half of its frame on an ENGINE / MODEL / EFFORT row and the
13
+ * bridge's install block above the conversation (Chris 07/10: "chèn hết vào không gian chat tốn không gian quá"); 0.25.0 put
14
+ * them in a 360px popup of the chip, Engine · Setup · Status tabs over the chat; 0.52.0 moved them into Settings (Chris
15
+ * 24/10: "đưa hết về nằm trong popup settings để có nhiều không gian hơn… bấm vào đó mở settings"), and 0.53.0 removed the
16
+ * popup once every surface had moved (the condition Chris set for the weight of engine-plain.js). A turn that FAILS because
17
+ * of the bridge says so in one line in the stream (`BridgeNotice`), whose "Open setup" opens Settings on Install or update.
18
18
  *
19
19
  * The package knows nothing about any bridge. The surface hands in the engines, the models, the efforts, the bridge's
20
- * status, the command and the code, and hears every change through callbacks.
21
- *
22
- * The panel is a non-modal dialog in the browser's TOP LAYER (`popover="manual"`, placed like the kit's menus by
23
- * `placeFloating`): no scrolling frame cuts it, it stays in the React tree (tokens resolve, events bubble). Escape and an
24
- * outside click close it; Escape and every close from inside it give focus back to the chip. Tabs are a roving tablist
25
- * (←/→/Home/End). Its look is `assistant-engine.css`, imported here: a surface that never draws the picker never loads it.
20
+ * status, the command and the code, and hears every change through callbacks. Its look is `assistant-engine.css`, imported
21
+ * here: a surface that never draws the picker never loads it.
26
22
  */
27
23
  import "../assistant-engine.css"; // its own entry (0.25.0): not in gemboss-ui.css, not in the assistant frame's sheet
28
- import React, { useCallback, useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
29
- import { createPortal } from "react-dom";
30
- import { canFloatMenus, placeFloating } from "../menu-layer";
24
+ import React, { useCallback, useEffect, useId, useRef, useState, type ReactNode } from "react";
31
25
  import { EngineMark, isEngineMarkId } from "./engine-mark";
26
+ import { requestEngineSettingsFocus, usePublishEngineSettings } from "./engine-settings-store";
32
27
 
33
28
  const cx = (...p: Array<string | false | null | undefined>) => p.filter(Boolean).join(" ");
34
- const useBeforePaint = typeof window === "undefined" ? useEffect : useLayoutEffect;
35
29
 
36
30
  /** running = answers now · outdated = answers, but an update is due · offline = paired, not reachable · unpaired = never
37
31
  * set up on this account · checking = not known yet (first poll in flight). */
38
32
  export type BridgeState = "running" | "outdated" | "offline" | "unpaired" | "checking";
33
+ /** The part of Settings › AI & engines to bring into view: the top (engine), the bridge's state, its install or update. */
39
34
  export type EnginePickerTab = "engine" | "setup" | "status";
40
35
 
41
36
  export interface EngineChoice {
@@ -51,8 +46,8 @@ export interface EngineChoice {
51
46
  /** The engine's mark ("claude", "codex": `ENGINE_MARK_ART`). The chip shows it in place of the name when the composer row
52
47
  * is too narrow for the name (`ChatComposer` density "icon"); an engine without one keeps its (cut) name. 0.29.0. */
53
48
  mark?: string;
54
- /** THIS engine's models. Give them on every engine and the Engine tab lists each engine with its own models, all at
55
- * once, and one click picks the engine and the model together (`onPick`): the admin's popup. 0.29.0. */
49
+ /** THIS engine's models. Give them on every engine and the Engine card lists each engine with its own models, all at
50
+ * once, and one click picks the engine and the model together (`onPick`): the admin's shape. 0.29.0. */
56
51
  models?: readonly Choice[];
57
52
  }
58
53
 
@@ -87,32 +82,31 @@ export interface BridgeSetup {
87
82
  pairingCode?: string;
88
83
  /** A few lines of how (an <ol>, a sentence). Default: "Paste the command into Terminal, then press Enter." */
89
84
  steps?: ReactNode;
90
- /** Quiet text under the command ("The pairing code stays the same: the panel reconnects in a few seconds."). */
85
+ /** Quiet text under the command ("The pairing code stays the same: the assistant reconnects in a few seconds."). */
91
86
  note?: ReactNode;
92
87
  }
93
88
 
94
89
  /** Every word the picker says. English, like every surface's chrome (Chris 03/10/2026). */
95
90
  export interface EnginePickerLabels {
96
- chip: string; dialog: string; tabs: string;
97
- engineTab: string; setupTab: string; statusTab: string;
91
+ chip: string;
98
92
  engine: string; model: string; effort: string;
99
93
  defaultChoice: string;
100
94
  copy: string; copied: string; copyFailed: string; pairingCode: string; steps: string;
101
95
  bridge: string; version: string; latest: string; startsAtSignIn: string; machine: string; lastSeen: string;
102
96
  yes: string; no: string; unknown: string;
103
97
  running: string; outdated: string; offline: string; unpaired: string; checking: string;
104
- updateDue: string; close: string;
98
+ /** The bridge card's first row (the card is titled `bridge`) and the heading of its install / update part. */
99
+ state: string; setupTitle: string;
105
100
  }
106
101
  export const ENGINE_PICKER_EN: EnginePickerLabels = {
107
- chip: "Engine", dialog: "Assistant engine", tabs: "Engine, setup and status",
108
- engineTab: "Engine", setupTab: "Setup", statusTab: "Status",
102
+ chip: "Engine",
109
103
  engine: "Engine", model: "Model", effort: "Effort",
110
104
  defaultChoice: "Default",
111
105
  copy: "Copy command", copied: "Copied", copyFailed: "Select the command and copy it", pairingCode: "Pairing code", steps: "Paste the command into Terminal, then press Enter.",
112
106
  bridge: "Bridge on your machine", version: "Version", latest: "Latest", startsAtSignIn: "Starts at sign-in", machine: "Machine", lastSeen: "Last seen",
113
107
  yes: "Yes", no: "No", unknown: "Not known",
114
108
  running: "Running", outdated: "Outdated", offline: "Not connected", unpaired: "Not set up", checking: "Checking",
115
- updateDue: "Update available", close: "Close",
109
+ state: "State", setupTitle: "Install or update",
116
110
  };
117
111
 
118
112
  /** The dot's tone per state: one word each, so the CSS has one rule per tone and a test can read it. */
@@ -144,76 +138,63 @@ export interface EnginePickerProps {
144
138
  onEffortChange?: (id: string) => void;
145
139
  /** Effort cannot be set right now; a string says why (its tooltip). */
146
140
  effortDisabled?: boolean | string;
147
- /** Quiet lines under the Engine tab's fields: who pays, what this bridge version cannot do yet. */
141
+ /** Quiet lines under the Engine card's fields: who pays, what this bridge version cannot do yet. */
148
142
  notes?: ReactNode;
149
- /** With models per engine (`EngineChoice.models`): one click on a model picks both, and closes the panel. Without it the
150
- * picker calls `onEngineChange` (when the engine changes) then `onModelChange`. 0.29.0. */
143
+ /** With models per engine (`EngineChoice.models`): one click on a model picks both. Without it the picker calls
144
+ * `onEngineChange` (when the engine changes) then `onModelChange`. 0.29.0. */
151
145
  onPick?: (engine: string, model: string) => void;
152
- /** A switch that did not go through ("Wait for the current answer to finish"): one red line on the Engine tab. 0.29.0. */
146
+ /** A switch that did not go through ("Wait for the current answer to finish"): one red line on the Engine card. 0.29.0. */
153
147
  problem?: ReactNode;
154
148
  /** The chip itself is disabled (a switch in flight). `locked` keeps the chip and disables the choices. 0.29.0. */
155
149
  disabled?: boolean;
156
- /** The bridge on the user's machine. Omit for an engine set that runs on the server only: no dot, no Status tab. */
150
+ /** The bridge on the user's machine. Omit for an engine set that runs on the server only: no dot, no bridge card. */
157
151
  bridge?: BridgeStatus;
158
152
  /** The dot on the chip (default true when `bridge` is given). False when the current engine does not go through the
159
153
  * bridge (a server engine): a red dot would say "broken" about something this engine does not use. */
160
154
  showBridgeDot?: boolean;
161
- /** Omit and there is no Setup tab. */
155
+ /** Omit and the bridge card has no Install or update part. */
162
156
  setup?: BridgeSetup;
163
157
  /** Buttons under the status rows ("Forget this machine", "Restart"). */
164
158
  statusActions?: ReactNode;
165
- /** Controlled open state and tab (a `BridgeNotice` opens Setup through these: see `useEnginePicker`). */
166
- open?: boolean;
159
+ /** Called with true while Settings › AI & engines is SEEN, false when it goes: a surface polls its bridge on it. */
167
160
  onOpenChange?: (open: boolean) => void;
168
- tab?: EnginePickerTab;
169
- onTabChange?: (tab: EnginePickerTab) => void;
170
161
  /** While a turn runs the surface may refuse a switch: the chip stays readable, the choices are disabled. */
171
162
  locked?: boolean;
172
- /** Align the panel's right edge with the chip's (a chip near the right edge of a narrow frame). */
173
- end?: boolean;
174
- /** The chip button, for the surface (`useEnginePicker` passes its own: `close()` puts focus back on it). 0.32.0. */
163
+ /** The chip button, for the surface. 0.32.0. */
175
164
  chipRef?: React.Ref<HTMLButtonElement>;
165
+ /** The chip opens the surface's SETTINGS on its "AI & engines" section (0.52.0; the only way since 0.53.0, which removed
166
+ * the chip's own popup). Called with "engine" from the chip, with "setup" from `useEnginePicker().openTab("setup")` (a
167
+ * failed turn's Open setup). See engine-settings.tsx. */
168
+ onOpenSettings: (tab: EnginePickerTab) => void;
176
169
  labels?: Partial<EnginePickerLabels>;
177
170
  className?: string;
178
171
  }
179
172
 
180
- /** The open state and tab of one picker, for a surface that also renders a `BridgeNotice`:
181
- * `const p = useEnginePicker(); <EnginePicker {...p.props} …/> <BridgeNotice onOpenSetup={() => p.openTab("setup")} …/>`
173
+ /** One picker's door and its "on screen" state, for a surface that also renders a `BridgeNotice`:
174
+ * `const p = useEnginePicker({ onOpenSettings: () => openSettings("ai") });`
175
+ * `<EnginePicker {...p.props} …/> <BridgeNotice onOpenSetup={() => p.openTab("setup")} …/>`
182
176
  *
183
- * `close()` (0.32.0) is the surface's close: a button inside the panel that acts and then shuts it (Stop bridge, Remove
184
- * from this machine, before a confirm opens). The button that had focus goes away with the panel, so focus would fall to
185
- * <body> and the confirm would record <body> as where to return; `close()` puts it on the chip first. Every surface
186
- * wrote that by hand (`querySelector(".gb-engine-chip").focus()`: partner-radar, search-radar, gemwatcher #922). An
187
- * outside click still closes without moving focus (`props.onOpenChange(false)`). */
188
- export function useEnginePicker(initial: EnginePickerTab = "engine") {
177
+ * `openTab("setup")` opens Settings with Install or update in view; `open` is true while Settings › AI & engines is SEEN
178
+ * (what a surface polls its bridge on); `close()` does nothing and stays for the surfaces that called it before a confirm
179
+ * (0.32.0, when the chip had a popup): the button is in Settings now, and focus stays on it. */
180
+ export function useEnginePicker(options: { onOpenSettings: (tab: EnginePickerTab) => void }) {
181
+ // The latest opener (a surface passes a new arrow each render), behind one stable function.
182
+ const toSettingsRef = useRef(options.onOpenSettings);
183
+ toSettingsRef.current = options.onOpenSettings;
189
184
  const [open, setOpen] = useState(false);
190
- const [tab, setTab] = useState<EnginePickerTab>(initial);
191
185
  const chipRef = useRef<HTMLButtonElement | null>(null);
192
- const openTab = useCallback((t: EnginePickerTab) => { setTab(t); setOpen(true); }, []);
193
- // Closing goes back to Engine: after "Open setup" the next click on the chip is about the engine again (review #3885).
194
- const onOpenChange = useCallback((v: boolean) => { setOpen(v); if (!v) setTab(initial); }, [initial]);
186
+ const openTab = useCallback((t: EnginePickerTab) => {
187
+ requestEngineSettingsFocus(t);
188
+ toSettingsRef.current(t);
189
+ }, []);
190
+ /** @deprecated 0.53.0: does nothing (the chip has no popup to close); kept so a Stop / Remove handler from 0.32.0 still runs. */
191
+ const close = useCallback(() => {}, []);
195
192
  const focusChip = useCallback(() => { chipRef.current?.focus(); }, []);
196
- const close = useCallback(() => { onOpenChange(false); focusChip(); }, [onOpenChange, focusChip]);
197
- return { open, tab, setOpen, setTab, openTab, close, focusChip, chipRef, props: { open, onOpenChange, tab, onTabChange: setTab, chipRef } };
198
- }
199
-
200
- function availableTabs(p: Pick<EnginePickerProps, "bridge" | "setup">): EnginePickerTab[] {
201
- return ["engine", ...(p.setup ? ["setup" as const] : []), ...(p.bridge ? ["status" as const] : [])];
193
+ return { open, openTab, close, focusChip, chipRef, props: { onOpenChange: setOpen, chipRef, onOpenSettings: openTab } };
202
194
  }
203
195
 
204
- /** The tab shown (controlled by `tab` or held here) among the tabs the props offer; one copy for the picker and the panel. */
205
- function useTabs(p: Pick<EnginePickerProps, "bridge" | "setup" | "tab" | "onTabChange">) {
206
- const tabs = availableTabs(p);
207
- const [own, setOwn] = useState<EnginePickerTab>("engine");
208
- const wanted = p.tab ?? own;
209
- const tab = tabs.includes(wanted) ? wanted : "engine";
210
- const { tab: controlled, onTabChange } = p;
211
- const setTab = useCallback((t: EnginePickerTab) => {
212
- if (controlled === undefined) setOwn(t);
213
- onTabChange?.(t);
214
- }, [controlled, onTabChange]);
215
- return { tabs, tab, setTab, resetOwn: () => setOwn("engine") };
216
- }
196
+ /** What the Settings section's cards take: the chip's props without its door (`onOpenSettings`), which they never call. */
197
+ export type EngineCardProps = Omit<EnginePickerProps, "onOpenSettings"> & { onOpenSettings?: EnginePickerProps["onOpenSettings"] };
217
198
 
218
199
  /** What the chip says out loud: the engine, the model, and the bridge when it is not fine. */
219
200
  export function engineChipName(p: Pick<EnginePickerProps, "engines" | "engine" | "models" | "model" | "bridge">, L: EnginePickerLabels = ENGINE_PICKER_EN): string {
@@ -225,150 +206,21 @@ export function engineChipName(p: Pick<EnginePickerProps, "engines" | "engine" |
225
206
  }
226
207
 
227
208
  export function EnginePicker(props: EnginePickerProps) {
228
- const { engines, engine, models, model, bridge, end = false, className } = props;
209
+ const { engines, engine, models, model, bridge, className, onOpenSettings } = props;
229
210
  const L = { ...ENGINE_PICKER_EN, ...props.labels };
230
- const [ownOpen, setOwnOpen] = useState(false);
231
- const open = props.open ?? ownOpen;
232
- const { tabs, tab, setTab, resetOwn } = useTabs(props);
233
- // Without the popover API (Safari < 17) a fixed layer inside the assistant's frame is cut by it (overflow, and in the
234
- // popup and mini modes the frame's backdrop-filter makes it the containing block; full and side have none since
235
- // 21/10/2026): there the panel goes to <body> through a portal instead.
236
- // Decided after mount, so the server and the first client render agree.
237
- const [portal, setPortal] = useState(false);
238
- useEffect(() => { setPortal(!canFloatMenus()); }, []);
239
- const chipRef = useRef<HTMLButtonElement | null>(null);
240
- const outerChipRef = props.chipRef;
241
- const setChip = useCallback((el: HTMLButtonElement | null) => {
242
- chipRef.current = el;
243
- if (typeof outerChipRef === "function") outerChipRef(el);
244
- else if (outerChipRef) (outerChipRef as { current: HTMLButtonElement | null }).current = el;
245
- }, [outerChipRef]);
246
- const panelRef = useRef<HTMLDivElement>(null);
247
- const panelId = useId();
248
-
249
- const setOpen = useCallback((v: boolean) => {
250
- if (props.open === undefined) setOwnOpen(v);
251
- if (!v) resetOwn();
252
- props.onOpenChange?.(v);
253
- // eslint-disable-next-line react-hooks/exhaustive-deps
254
- }, [props.open, props.onOpenChange]);
255
- /** Close and put focus back on the chip: Escape, a pick, the close button. An outside click closes without it (the
256
- * click already moved focus where the user wanted it). */
257
- const closeToChip = useCallback(() => { setOpen(false); chipRef.current?.focus(); }, [setOpen]);
258
-
259
- // Float / sink with `open`, before paint, so the panel is never drawn unplaced.
260
- useBeforePaint(() => {
261
- const panel = panelRef.current, chip = chipRef.current;
262
- if (!panel || !chip) return;
263
- if (!open) {
264
- if (canFloatMenus() && panel.matches(":popover-open")) panel.hidePopover();
265
- return;
266
- }
267
- if (canFloatMenus() && !panel.matches(":popover-open")) panel.showPopover();
268
- placeFloating(panel, chip, end);
269
- }, [open, end, tab]);
270
-
271
- // While open: Escape, outside pointer, and keep it against the chip when the window or a frame around the chip moves.
272
- useEffect(() => {
273
- if (!open) return undefined;
274
- const panel = panelRef.current, chip = chipRef.current;
275
- if (!panel || !chip) return undefined;
276
- // Escape with focus in the panel or on the chip closes the panel only: captured first and stopped, so the surface's
277
- // own Escape (hide the assistant) does not fire on the same key. With focus elsewhere (the composer), it closes the
278
- // panel and leaves focus alone, and marks the key handled (0.27.0): a surface whose "Escape hides the assistant"
279
- // checks `defaultPrevented` waits for the next Escape. Before 0.27.0 the key went on unmarked, and React re-renders
280
- // between this listener and the surface's, so every surface (gemlabs #922, gemfeedback #66) needed a window-capture
281
- // marker to tell "this Escape closed the picker" from "this one is mine".
282
- const onKey = (e: KeyboardEvent) => {
283
- if (e.key !== "Escape" || e.defaultPrevented) return;
284
- // Not ours: an IME composition (Escape cancels it; the kit's rule, kit-plain.js), or a modal opened from the panel.
285
- if (e.isComposing || e.keyCode === 229) return;
286
- const a = document.activeElement;
287
- const modal = a?.closest?.('dialog[open], [aria-modal="true"]');
288
- if (modal && !panel.contains(modal)) return;
289
- e.preventDefault();
290
- if (a && (panel.contains(a) || chip.contains(a))) { e.stopPropagation(); closeToChip(); }
291
- else setOpen(false);
292
- };
293
- const onDown = (e: PointerEvent) => {
294
- const t = e.target as Node;
295
- if (!panel.contains(t) && !chip.contains(t)) setOpen(false);
296
- };
297
- // A modal opened from the panel (a confirm behind a Status action) takes the screen: the panel would stay above it in
298
- // the top layer, over its buttons (review #3903). Close the panel when focus enters a modal that is not the panel.
299
- const onFocusIn = (e: FocusEvent) => {
300
- const m = (e.target as Element | null)?.closest?.('dialog[open], [aria-modal="true"]');
301
- if (m && !panel.contains(m)) setOpen(false);
302
- };
303
- const replace = () => placeFloating(panel, chip, end);
304
- // A scroll moves the panel's anchor only when it scrolls something that holds the chip (the page, a frame around the
305
- // composer): a chat log streaming beside it does not. One placement per frame at most.
306
- let frame = 0;
307
- const onScroll = (e: Event) => {
308
- const t = e.target as Node | null;
309
- if (!t || panel.contains(t)) return;
310
- if (t !== document && (t as Node).nodeType !== 9 && !t.contains(chip)) return;
311
- if (!frame) frame = requestAnimationFrame(() => { frame = 0; replace(); });
312
- };
313
- // Its content changes while open (a poll turns "Allow connection" into the command): re-place on its own resize, or a
314
- // taller panel runs off the bottom of the screen. placeFloating writes max-height, which the observer ignores (it
315
- // only fires when the box changes size, and a clamp to the same room settles at once).
316
- let lastH = -1;
317
- const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
318
- if (panel.scrollHeight === lastH) return;
319
- lastH = panel.scrollHeight;
320
- replace();
321
- });
322
- // The panel (it grows while it fits) and its pane (content that grows past a clamped panel).
323
- ro?.observe(panel);
324
- const pane = panel.querySelector(".gb-engine-pane");
325
- if (pane) ro?.observe(pane);
326
- document.addEventListener("keydown", onKey, true);
327
- document.addEventListener("pointerdown", onDown, true);
328
- document.addEventListener("focusin", onFocusIn, true);
329
- document.addEventListener("scroll", onScroll, true);
330
- window.addEventListener("resize", replace);
331
- return () => {
332
- document.removeEventListener("keydown", onKey, true);
333
- cancelAnimationFrame(frame);
334
- document.removeEventListener("pointerdown", onDown, true);
335
- document.removeEventListener("focusin", onFocusIn, true);
336
- document.removeEventListener("scroll", onScroll, true);
337
- window.removeEventListener("resize", replace);
338
- ro?.disconnect();
339
- };
340
- }, [open, end, closeToChip, setOpen]);
341
-
342
- // Focus goes INTO the panel on open (the selected tab), so a keyboard user lands where the choices are.
343
- useEffect(() => {
344
- if (!open) return;
345
- const t = panelRef.current?.querySelector<HTMLElement>('[role="tab"][aria-selected="true"]')
346
- ?? panelRef.current?.querySelector<HTMLElement>("button:not([disabled])");
347
- t?.focus();
348
- // Only on opening: a tab change moves focus by itself (the roving keys), a pick closes.
349
- // eslint-disable-next-line react-hooks/exhaustive-deps
350
- }, [open]);
351
-
211
+ // The chip hands its props to the "AI & engines" section and hears when that section is on screen (engine-settings-store).
212
+ usePublishEngineSettings(props);
352
213
  const current = engines.find((e) => e.id === engine);
353
214
  const modelLabel = model ? (current?.models ?? models)?.find((m) => m.id === model)?.label : undefined;
354
215
  const mark = current?.mark && isEngineMarkId(current.mark) ? current.mark : null;
355
216
  const tone = bridge && props.showBridgeDot !== false ? BRIDGE_TONE[bridge.state] : null;
356
217
  const name = engineChipName(props.showBridgeDot === false ? { ...props, bridge: undefined } : props, L);
357
-
218
+ // A door to the surface's Settings: it opens a dialog (the surface's), so no expanded state or panel id of its own.
358
219
  return (
359
220
  <span className={cx("gb-engine", className)}>
360
- <button
361
- ref={setChip}
362
- type="button"
363
- className={mark ? "gb-engine-chip has-mark" : "gb-engine-chip"}
364
- disabled={props.disabled || undefined}
365
- aria-haspopup="dialog"
366
- aria-expanded={open}
367
- aria-controls={panelId}
368
- aria-label={name}
369
- title={name}
370
- onClick={() => setOpen(!open)}
371
- >
221
+ <button ref={props.chipRef} type="button" className={mark ? "gb-engine-chip has-mark" : "gb-engine-chip"}
222
+ disabled={props.disabled || undefined} aria-haspopup="dialog" aria-label={name} title={name}
223
+ onClick={() => onOpenSettings("engine")}>
372
224
  {tone ? <span className={DOT_CLASS[tone]} aria-hidden /> : null}
373
225
  <span className="gb-engine-chiplabel">
374
226
  {current?.label ?? engine}
@@ -377,93 +229,12 @@ export function EnginePicker(props: EnginePickerProps) {
377
229
  {/* Shown instead of the name when the composer is too narrow for it (assistant-engine.css, ChatComposer density). */}
378
230
  {mark ? <span className="gb-engine-chipmark"><EngineMark engine={mark} decorative /></span> : null}
379
231
  </button>
380
- {(() => { const panelEl = (<div
381
- ref={panelRef}
382
- id={panelId}
383
- className="gb-engine-panel gemboss-popover-surface"
384
- role="dialog"
385
- aria-label={L.dialog}
386
- // The top layer where the browser has one; otherwise a fixed layer in the tree (assistant-engine.css).
387
- {...(portal ? {} : { popover: "manual" })}
388
- hidden={!open}
389
- data-open={open ? "" : undefined}
390
- >
391
- {open ? <PanelBody {...props} L={L} tab={tab} tabs={tabs} setTab={setTab} onPicked={closeToChip} /> : null}
392
- </div>);
393
- return portal && typeof document !== "undefined" ? createPortal(panelEl, document.body) : panelEl; })()}
394
232
  </span>
395
233
  );
396
234
  }
397
235
 
398
- /** The panel's content, also exported on its own (`EnginePanel`) for the catalog and for a settings page that shows it
399
- * in place, without a chip. */
400
- function PanelBody({ L, tab, tabs, setTab, onPicked, ...p }: EnginePickerProps & {
401
- L: EnginePickerLabels; tab: EnginePickerTab; tabs: EnginePickerTab[]; setTab: (t: EnginePickerTab) => void; onPicked?: () => void;
402
- }) {
403
- const base = useId();
404
- const tabRefs = useRef<Partial<Record<EnginePickerTab, HTMLButtonElement | null>>>({});
405
- const tabLabel: Record<EnginePickerTab, string> = { engine: L.engineTab, setup: L.setupTab, status: L.statusTab };
406
- const needsUpdate = p.bridge?.state === "outdated";
407
- const onTabKey = (e: React.KeyboardEvent) => {
408
- const i = tabs.indexOf(tab);
409
- const to = e.key === "ArrowRight" ? tabs[(i + 1) % tabs.length]
410
- : e.key === "ArrowLeft" ? tabs[(i - 1 + tabs.length) % tabs.length]
411
- : e.key === "Home" ? tabs[0] : e.key === "End" ? tabs[tabs.length - 1] : null;
412
- if (!to) return;
413
- e.preventDefault();
414
- setTab(to);
415
- tabRefs.current[to]?.focus();
416
- };
417
- return (
418
- <>
419
- {tabs.length > 1 ? (
420
- <div className="ui-tabs gb-engine-tabs" role="tablist" aria-label={L.tabs} onKeyDown={onTabKey}>
421
- {tabs.map((t) => (
422
- <button
423
- key={t}
424
- ref={(el) => { tabRefs.current[t] = el; }}
425
- type="button"
426
- role="tab"
427
- id={`${base}-tab-${t}`}
428
- aria-controls={`${base}-pane-${t}`}
429
- aria-selected={tab === t}
430
- tabIndex={tab === t ? 0 : -1}
431
- onClick={() => setTab(t)}
432
- >
433
- {tabLabel[t]}
434
- {/* The same warning the chip's dot gives, on the tab that fixes it. */}
435
- {t === "setup" && needsUpdate ? <span className="gb-engine-dot gb-engine-dot--warn" role="img" aria-label={L.updateDue} /> : null}
436
- </button>
437
- ))}
438
- </div>
439
- ) : null}
440
- <div
441
- className="gb-engine-pane"
442
- role={tabs.length > 1 ? "tabpanel" : undefined}
443
- id={`${base}-pane-${tab}`}
444
- aria-labelledby={tabs.length > 1 ? `${base}-tab-${tab}` : undefined}
445
- >
446
- {tab === "engine" ? <EngineTab {...p} L={L} onPicked={onPicked} /> : null}
447
- {tab === "setup" ? <SetupTab setup={p.setup!} bridge={p.bridge} L={L} /> : null}
448
- {tab === "status" ? <StatusTab bridge={p.bridge!} actions={p.statusActions} L={L} /> : null}
449
- </div>
450
- </>
451
- );
452
- }
453
-
454
- /** The panel without the chip: the catalog, or a settings page that shows the same three tabs in place. */
455
- export function EnginePanel(props: EnginePickerProps) {
456
- const L = { ...ENGINE_PICKER_EN, ...props.labels };
457
- const { tabs, tab, setTab } = useTabs(props);
458
- return (
459
- <div className={cx("gb-engine-panel gb-engine-panel--inline gemboss-popover-surface", props.className)} role="group" aria-label={L.dialog}>
460
- <PanelBody {...props} L={L} tab={tab} tabs={tabs} setTab={setTab} />
461
- </div>
462
- );
463
- }
464
-
465
- function Options({ label, items, value, onChange, locked, onPicked, disabledReason }: {
466
- label: string; items: readonly Choice[]; value: string | undefined; onChange?: (id: string) => void; locked?: boolean; onPicked?: () => void;
236
+ function Options({ label, items, value, onChange, locked, disabledReason }: {
237
+ label: string; items: readonly Choice[]; value: string | undefined; onChange?: (id: string) => void; locked?: boolean;
467
238
  disabledReason?: boolean | string;
468
239
  }) {
469
240
  const id = useId();
@@ -499,7 +270,7 @@ function Options({ label, items, value, onChange, locked, onPicked, disabledReas
499
270
  aria-pressed={(value ?? "") === m.id}
500
271
  disabled={off}
501
272
  title={why ?? m.title}
502
- onClick={() => { if ((value ?? "") !== m.id) onChange?.(m.id); onPicked?.(); }}
273
+ onClick={() => { if ((value ?? "") !== m.id) onChange?.(m.id); }}
503
274
  >
504
275
  {m.label}
505
276
  </button>
@@ -509,21 +280,18 @@ function Options({ label, items, value, onChange, locked, onPicked, disabledReas
509
280
  );
510
281
  }
511
282
 
512
- /** Every engine with its own models, all at once; one click picks both (the admin's popup, 0.29.0). */
513
- function EngineGroups({ engines, engine, model, onPick, onEngineChange, onModelChange, locked, L, onPicked }: EnginePickerProps & { L: EnginePickerLabels; onPicked?: () => void }) {
514
- const id = useId();
283
+ /** Every engine with its own models, all at once; one click picks both (the admin's shape, 0.29.0). */
284
+ function EngineGroups({ engines, engine, model, onPick, onEngineChange, onModelChange, locked, L, labelledBy }: EngineCardProps & { L: EnginePickerLabels; labelledBy: string }) {
515
285
  const choose = (e: EngineChoice, m: Choice) => {
516
- // The pick already in force: close, change nothing (a surface that starts a new conversation on a switch must not).
517
- if (e.id === engine && (model ?? "") === m.id) { onPicked?.(); return; }
286
+ // The pick already in force: change nothing (a surface that starts a new conversation on a switch must not).
287
+ if (e.id === engine && (model ?? "") === m.id) return;
518
288
  if (onPick) onPick(e.id, m.id);
519
289
  else { if (e.id !== engine) onEngineChange?.(e.id); onModelChange?.(m.id); }
520
- onPicked?.();
521
290
  };
522
291
  const canChoose = Boolean(onPick || onEngineChange || onModelChange);
523
292
  return (
524
293
  <div className="gb-engine-field">
525
- <span className="gb-engine-label" id={id}>{L.engine}</span>
526
- <div className="gb-engine-groups" role="group" aria-labelledby={id}>
294
+ <div className="gb-engine-groups" role="group" aria-labelledby={labelledBy}>
527
295
  {engines.map((e) => {
528
296
  const chosen = e.id === engine;
529
297
  const items = e.models && e.models.length ? e.models : [{ id: "", label: L.defaultChoice }];
@@ -552,14 +320,15 @@ function EngineGroups({ engines, engine, model, onPick, onEngineChange, onModelC
552
320
  );
553
321
  }
554
322
 
555
- function EngineTab(props: EnginePickerProps & { L: EnginePickerLabels; onPicked?: () => void }) {
556
- const { engines, engine, onEngineChange, models, model, onModelChange, modelControl, efforts, effort, onEffortChange, effortDisabled, notes, locked, L, onPicked } = props;
557
- const id = useId();
323
+ /** The Engine card's content. `labelledBy`: the card's heading names the engine list, so its own "Engine" label is not
324
+ * drawn a second time under it. */
325
+ export function EngineTab(props: EngineCardProps & { L: EnginePickerLabels; labelledBy: string }) {
326
+ const { engines, engine, onEngineChange, models, model, onModelChange, modelControl, efforts, effort, onEffortChange, effortDisabled, notes, locked, L, labelledBy } = props;
558
327
  if (engines.some((e) => e.models && e.models.length)) {
559
328
  return (
560
329
  <>
561
330
  <EngineGroups {...props} />
562
- {efforts && efforts.length ? <Options label={L.effort} items={efforts} value={effort} onChange={onEffortChange} locked={locked} onPicked={onPicked} disabledReason={effortDisabled} /> : null}
331
+ {efforts && efforts.length ? <Options label={L.effort} items={efforts} value={effort} onChange={onEffortChange} locked={locked} disabledReason={effortDisabled} /> : null}
563
332
  {props.problem ? <p className="gb-engine-problem" role="alert">{props.problem}</p> : null}
564
333
  {notes ? <div className="gb-engine-notes">{notes}</div> : null}
565
334
  </>
@@ -582,8 +351,7 @@ function EngineTab(props: EnginePickerProps & { L: EnginePickerLabels; onPicked?
582
351
  return (
583
352
  <>
584
353
  <div className="gb-engine-field">
585
- <span className="gb-engine-label" id={id}>{L.engine}</span>
586
- <div className="gb-engine-list" role="radiogroup" aria-labelledby={id} onKeyDown={onKey}>
354
+ <div className="gb-engine-list" role="radiogroup" aria-labelledby={labelledBy} onKeyDown={onKey}>
587
355
  {engines.map((e) => (
588
356
  <button
589
357
  key={e.id}
@@ -594,7 +362,6 @@ function EngineTab(props: EnginePickerProps & { L: EnginePickerLabels; onPicked?
594
362
  tabIndex={e.id === stop ? 0 : -1}
595
363
  className="gb-engine-row"
596
364
  disabled={!can(e)}
597
- // A new engine keeps the panel open: its models and efforts are the next thing to look at.
598
365
  onClick={() => { if (e.id !== engine) onEngineChange?.(e.id); }}
599
366
  >
600
367
  <span className="gb-engine-rowhead">
@@ -608,8 +375,8 @@ function EngineTab(props: EnginePickerProps & { L: EnginePickerLabels; onPicked?
608
375
  </div>
609
376
  {modelControl ? (
610
377
  <div className="gb-engine-field"><span className="gb-engine-label">{L.model}</span>{modelControl}</div>
611
- ) : models && models.length ? <Options label={L.model} items={models} value={model} onChange={onModelChange} locked={locked} onPicked={onPicked} /> : null}
612
- {efforts && efforts.length ? <Options label={L.effort} items={efforts} value={effort} onChange={onEffortChange} locked={locked} onPicked={onPicked} disabledReason={effortDisabled} /> : null}
378
+ ) : models && models.length ? <Options label={L.model} items={models} value={model} onChange={onModelChange} locked={locked} /> : null}
379
+ {efforts && efforts.length ? <Options label={L.effort} items={efforts} value={effort} onChange={onEffortChange} locked={locked} disabledReason={effortDisabled} /> : null}
613
380
  {props.problem ? <p className="gb-engine-problem" role="alert">{props.problem}</p> : null}
614
381
  {notes ? <div className="gb-engine-notes">{notes}</div> : null}
615
382
  </>
@@ -635,7 +402,20 @@ export async function copyText(text: string): Promise<boolean> {
635
402
  } catch { return false; }
636
403
  }
637
404
 
638
- function SetupTab({ setup, bridge, L }: { setup: BridgeSetup; bridge?: BridgeStatus; L: EnginePickerLabels }) {
405
+ /** What is wrong with the bridge, in one callout at the top of the bridge card. */
406
+ export function BridgeCallout({ bridge, L }: { bridge?: BridgeStatus; L: EnginePickerLabels }) {
407
+ if (!(bridge?.state === "outdated" || bridge?.state === "offline" || bridge?.state === "unpaired")) return null;
408
+ return (
409
+ <p className={cx("gb-engine-callout", bridge.state === "outdated" ? "gb-engine-callout--warn" : "gb-engine-callout--down")}>
410
+ <strong>{L.bridge}: {L[STATE_LABEL[bridge.state]]!.toLowerCase()}.</strong>
411
+ {bridge.detail ? <> {bridge.detail}</> : null}
412
+ </p>
413
+ );
414
+ }
415
+
416
+ /** The bridge card's Install or update part: the steps, the command with Copy, the pairing code. (What is wrong is the
417
+ * card's callout, above it.) */
418
+ export function SetupTab({ setup, L }: { setup: BridgeSetup; L: EnginePickerLabels }) {
639
419
  const [said, setSaid] = useState<"" | "copied" | "failed">("");
640
420
  const timer = useRef<number | undefined>(undefined);
641
421
  useEffect(() => () => window.clearTimeout(timer.current), []);
@@ -648,13 +428,7 @@ function SetupTab({ setup, bridge, L }: { setup: BridgeSetup; bridge?: BridgeSta
648
428
  };
649
429
  return (
650
430
  <>
651
- {bridge?.state === "outdated" || bridge?.state === "offline" || bridge?.state === "unpaired" ? (
652
- <p className={cx("gb-engine-callout", bridge.state === "outdated" ? "gb-engine-callout--warn" : "gb-engine-callout--down")}>
653
- <strong>{L.bridge}: {L[STATE_LABEL[bridge.state]].toLowerCase()}.</strong>
654
- {bridge.detail ? <> {bridge.detail}</> : null}
655
- </p>
656
- ) : null}
657
- {setup.steps || setup.command ? <div className="gb-engine-steps">{setup.steps ?? <p>{L.steps}</p>}</div> : null}
431
+ {setup.steps || setup.command ?<div className="gb-engine-steps">{setup.steps ?? <p>{L.steps}</p>}</div> : null}
658
432
  {setup.command ? (
659
433
  <>
660
434
  <pre className="gb-engine-cmd"><code>{setup.command}</code></pre>
@@ -674,20 +448,23 @@ function SetupTab({ setup, bridge, L }: { setup: BridgeSetup; bridge?: BridgeSta
674
448
  );
675
449
  }
676
450
 
677
- function StatusTab({ bridge, actions, L }: { bridge: BridgeStatus; actions?: ReactNode; L: EnginePickerLabels }) {
451
+ /** The bridge card's state rows and actions. The card is titled with the bridge, so the first row says "State", and the
452
+ * callout above it already carries `detail`. */
453
+ export function StatusTab({ bridge, actions, L }: { bridge: BridgeStatus; actions?: ReactNode; L: EnginePickerLabels }) {
678
454
  const tone = BRIDGE_TONE[bridge.state];
679
455
  const yesNo = (v: boolean | undefined) => (v === undefined ? L.unknown : v ? L.yes : L.no);
456
+ const calledOut = bridge.state === "outdated" || bridge.state === "offline" || bridge.state === "unpaired";
680
457
  return (
681
458
  <>
682
459
  <dl className="gb-engine-rows">
683
- <dt>{L.bridge}</dt>
460
+ <dt>{L.state}</dt>
684
461
  <dd><span className={DOT_CLASS[tone]} aria-hidden /> {L[STATE_LABEL[bridge.state]]}</dd>
685
462
  {bridge.version ? <><dt>{L.version}</dt><dd>{bridge.version}{bridge.latest && bridge.latest !== bridge.version ? ` · ${L.latest} ${bridge.latest}` : ""}</dd></> : null}
686
463
  <dt>{L.startsAtSignIn}</dt><dd>{yesNo(bridge.autostart)}</dd>
687
464
  {bridge.machine ? <><dt>{L.machine}</dt><dd>{bridge.machine}</dd></> : null}
688
465
  {bridge.lastSeen ? <><dt>{L.lastSeen}</dt><dd>{bridge.lastSeen}</dd></> : null}
689
466
  </dl>
690
- {bridge.detail && bridge.state !== "running" ? <p className="gb-engine-note">{bridge.detail}</p> : null}
467
+ {bridge.detail && bridge.state !== "running" && !calledOut ? <p className="gb-engine-note">{bridge.detail}</p> : null}
691
468
  {actions ? <div className="gb-engine-actions">{actions}</div> : null}
692
469
  </>
693
470
  );
@@ -695,8 +472,8 @@ function StatusTab({ bridge, actions, L }: { bridge: BridgeStatus; actions?: Rea
695
472
 
696
473
  /**
697
474
  * ONE line in the chat stream, for a turn that actually failed because of the bridge ("The bridge on your machine is
698
- * not connected."), with "Open setup" that opens the picker on its Setup tab. Never a standing block: the chip's dot says
699
- * "outdated" all the time, this says "this turn failed, here is why" once.
475
+ * not connected."), with "Open setup" that opens Settings › AI & engines on Install or update (`useEnginePicker().openTab`).
476
+ * Never a standing block: the chip's dot says "outdated" all the time, this says "this turn failed, here is why" once.
700
477
  */
701
478
  export function BridgeNotice({ children, onOpenSetup, action = "Open setup", tone = "down", className }: {
702
479
  children: ReactNode;