@gemboss/ui 0.52.0 → 0.55.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.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,72 @@ Versions up to 0.9.0 are described in the README, each in the section that intro
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 0.55.0 (25/10/2026)
8
+
9
+ **Settings › AI & engines, cleaner** (25/10/2026, Chris: the chip's old popup "design khá đẹp", bring that look into Settings
10
+ with pictures; then "clean và thẩm mỹ… phương án đầu an toàn nhất", so the layout stays and only the details change).
11
+
12
+ Changed
13
+ - Each engine row starts with a small picture: its mark (`EngineChoice.mark`, else an id the kit has artwork for), else
14
+ its initial by code point (`EngineRowMark`). Never another engine's logo. Monochrome, as the chip's mark. The admin's grouped
15
+ engines too. The chip and the row pick the picture by ONE rule, `engineMarkOf` (new export): an engine with the id `claude`
16
+ and no `mark` now has its mark on the chip as well, when the composer is narrow. Rows stay 44px.
17
+ - The bridge card's state is a dotted badge in its head (`BridgeStateBadge`, classes `gb-engine-state--ok|warn|down|idle`
18
+ in assistant-engine.css itself: the kit's ui-badge tones are in kit-plain.css, which the admin does not load); the "State"
19
+ row is gone. The callout carries the
20
+ surface's `detail` only (it no longer opens with "Bridge on your machine: outdated.", which the badge says), and there is no
21
+ callout without a detail. Label `state` is optional and deprecated (nothing draws it).
22
+ - `.gb-engine-settings` packs its cards at the top (`align-content: start`) and owns their margins and its paragraphs'
23
+ margins: in the catalog, a page's own `section` and `section > p` margins had opened 64px between the cards.
24
+ - `engine-plain.js`: the same, its marks drawn with `gembossUI.engineMark` (chat-plain.js, which every page with the chip loads).
25
+
26
+ ## 0.54.0 (25/10/2026)
27
+
28
+ **A product's own GemBoss door on the kit's button** (25/10/2026). GemCommunity's sign-in drew "Continue with GemBoss" by
29
+ hand in the kit's classes, because `AuthContinueWithGemBoss` only linked to the fleet door (Chris, 24/10/2026: "signup signin
30
+ phải cùng ui kit với các page login").
31
+
32
+ Added
33
+ - `AuthContinueWithGemBoss` `href`, in place of `service`: a door the product runs itself (GemCommunity's handoff through
34
+ admin.gemboss.ai/api/community/sso). The link goes there as given and nothing of the fleet door applies: it never goes by
35
+ itself on `gb_sso=1` (the fleet's cookie), and a `?sso=` reason is the product's to say in its own words.
36
+ - `label`, `goingLabel` and `or` (null for none: a page that says "or" itself, above several doors), in the page's language.
37
+ Left out, they are the words the button had.
38
+ - `PickerList` `pinned`: rows that do not come from the source (an empty value that is a choice), first and pickable in every state,
39
+ with the source's state said under them. Before, the product picker put such a row in `items`: an empty catalogue behind it said
40
+ nothing (the kit's empty state shows only for an empty list), and a failed read hid it (gemboss #5415). In `reloading` only the
41
+ source's rows dim (`.gemboss-ei-pick-row.is-stale`).
42
+
43
+ Unchanged: `auth-sso-plain.js` keeps the fleet door only. No page without React draws a product's door.
44
+
45
+ ## 0.53.0 (25/10/2026)
46
+
47
+ **The engine chip's popup is gone: Settings › AI & engines is the only place the engine is chosen** (Chris's condition for the
48
+ 0.52.0 `engine-plain.js` ceiling, 24/10/2026: "gỡ chế độ popup khi mọi bề mặt đã chuyển"). Every surface on the kit moved to
49
+ Settings in 0.52.0 (partner-radar, content-radar, search-radar, talent-radar, gemwatcher, GemFeedback, gemfactory, gemcare, and the
50
+ admin), so the 0.25 popup had no reader left. Checked 25/10: gemfactory's builder has no engine chip (its chat runs on the
51
+ server only, no bridge), and gemcommunity, gemplugin and gemform draw none.
52
+
53
+ Removed (breaking)
54
+ - `EnginePanel`, and the chip's popup with it: the top-layer dialog, its tabs, its Escape handling and its placement.
55
+ - `EnginePicker` props `open`, `tab`, `onTabChange`, `end`; `onOpenSettings` is now REQUIRED (on `useEnginePicker` too). Labels
56
+ `dialog`, `tabs`, `engineTab`, `setupTab`, `statusTab`, `updateDue`, `close`.
57
+ - `engine-plain.js`: the popup, its tabs, Escape and placement. Without `onOpenSettings` the chip logs a `console.error` and
58
+ opens nothing. `picker.close()` stays and does nothing (as `useEnginePicker().close()` since 0.52.0).
59
+ - CSS: `.gb-engine-panel`, `.gb-engine-tabs`, `.gb-engine-pane` and their rules; `.gb-engine-cmd` no longer caps its height
60
+ (that was the popup's 360px). A surface rule scoped to `.gb-engine-panel` no longer matches: scope it to `.gb-engine-settings`.
61
+ - `EngineSettings` / `EngineSettingsSection` no longer require `onOpenSettings` (`EngineCardProps`): the cards never call it.
62
+
63
+ Fixed
64
+ - The pairing code (`.gb-engine-code code`) resets a surface's own `code` look, as the command already did: content-radar tinted
65
+ it as an inline-code pill in Settings (its exemption named `.gb-engine-panel`).
66
+ - The chip asked the section to focus twice per click (its own request, then `openTab`'s): `openTab` alone asks now.
67
+ - `engine-plain.js` Settings section: a poll that changed the bridge between running and outdated (the callout above Install or
68
+ update came or went) tore the setup block out and put a new one back, so a pairing-code field in `setup.steps` lost its focus
69
+ mid-typing (0.52.0). A keyed block that only shifted now stays in place.
70
+
71
+ Weight: `engine-plain.js` 4979 B gzip, ceiling 6723 → 5491 B (under 0.51's 5959).
72
+
7
73
  ## 0.52.0 (25/10/2026)
8
74
 
9
75
  **The assistant's engine in Settings › AI & engines; the composer chip opens it** (24/10/2026, Chris: "đưa hết về nằm trong
@@ -103,6 +169,18 @@ Added
103
169
  - `auth-standard-browser.test.ts` in Chromium (1280 x 800 and 390 x 844, light and dark), each layout claim beside a
104
170
  negative control; the catalog's "Đăng nhập" section draws the standard sign-in (light and dark) and two sign-up steps.
105
171
 
172
+ **`Dialog` gives the focus back to a clicked opener that dropped it** (24/10/2026). Polaris' buttons blur themselves on mouseup, so
173
+ a popup opened by a click on one found `<body>` focused and gave the focus back to `<body>` on Escape or ✕ (the catalogue picker's
174
+ Change, measured). When the focus is on `<body>` as it opens, the opener is the control the last press landed on (in the last 2 s,
175
+ still in the page); an opener that kept its focus is unchanged.
176
+ Also: `onClose`'s updates are applied (`flushSync`) before the focus goes back, so a close that replaces its opener (a picker's
177
+ typed handle saved as it closes) hands the focus to what replaced it, not to the button an instant before it left; and `Dialog`
178
+ takes `returnFocusTo` (useModalDialog's selector, for an opener gone by then).
179
+ Its Escape is its own: the browser closes the `<dialog>` and neither the keydown nor the keyup goes further out. A Polaris Modal it
180
+ was opened from closes on the Escape KEYUP (its keydown only marks it closing), so stopping the keydown was not enough. One helper,
181
+ `consumeEscape` (escape.ts), does both for every kit part that acts on Escape: Dialog, PickerList's and PickerGrid's box (clearing
182
+ its words), Popover (back or close).
183
+
106
184
  **The public site layer is deprecated** (24/10/2026). Public websites use `@gemboss/website-ui` (gemboss-www
107
185
  [packages/website-ui](https://github.com/chriskoh26/gemboss-www/tree/main/packages/website-ui), on npm), the full site kit with its rules and CLI; Chris chose one kit for every GemCommerce
108
186
  website. `SiteHeader`, `SiteBrand` and `site.css` stay, unchanged, until news.gemboss.ai and the community home move;
package/README.md CHANGED
@@ -72,7 +72,7 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
72
72
  | editor-tiles | `@gemboss/ui/editor-tiles.css` | `packages/ui/src/editor-tiles.css` | `ChoiceTiles`: a closed choice of shapes as picture tiles | 0.5 KB | `ChoiceTiles` imports it |
73
73
  | editor-insert | `@gemboss/ui/editor-insert.css` | `packages/ui/src/editor-insert.css` | the page editor's insert menu (the + on a picked element) | 0.6 KB | admin `InsertElementMenu` imports it |
74
74
  | reactions | `@gemboss/ui/reactions.css` | `packages/ui/src/reactions.css` | the emoji reactions and their picker | 0.8 KB | `Reactions` / `ReactionPicker` import it |
75
- | assistant-engine | `@gemboss/ui/assistant-engine.css` | `packages/ui/src/assistant-engine.css` | the engine picker (chip + Engine/Setup/Status popup) and the bridge notice | 1.9 KB | `EnginePicker` / `EnginePanel` / `BridgeNotice` import it |
75
+ | assistant-engine | `@gemboss/ui/assistant-engine.css` | `packages/ui/src/assistant-engine.css` | the engine picker (chip + Settings › AI & engines) and the bridge notice | 1.9 KB | `EnginePicker` / `EngineSettings` / `BridgeNotice` import it |
76
76
  | chat | `@gemboss/ui/chat.css` + `chat-composer.css` | `packages/ui/src/chat.css`, `packages/ui/src/chat-composer.css` | the chat body, the composer | 3.0 + 0.9 KB | the chat components (0.29.0); a page writing the markup links them |
77
77
  | assistant-chat | `@gemboss/ui/assistant-chat.css` | `packages/ui/src/assistant-chat.css` | the chat pieces the package draws (0.29.0): column, starters that wrap, meta, errors, notes, paperclip | 0.9 KB | `AssistantChat` and its pieces import it |
78
78
  | minichart | `@gemboss/ui/minichart.css` | `packages/ui/src/minichart.css` | `Sparkline`, `ShareBar` (0.30.0) | 0.5 KB | those components import it |
@@ -447,16 +447,20 @@ the menu, rename, pin, delete, collapse, an empty list) and the framed layout to
447
447
  </script>
448
448
  ```
449
449
 
450
- ## The engine picker (0.25.0): `EnginePicker`, `BridgeNotice`
450
+ ## The engine picker: `EnginePicker` (0.25.0), Settings › AI & engines (0.52.0), `BridgeNotice`
451
451
 
452
452
  Which engine answers the assistant, and the bridge on the user's machine, without spending the chat's space on it
453
453
  (Chris 07/10/2026: content-radar's assistant spent close to half its frame on an ENGINE / MODEL / EFFORT row, an
454
- "outdated bridge" block and the install command). The admin's shape: a chip in the composer row opens a popup.
454
+ "outdated bridge" block and the install command). A chip in the composer row says the engine; the choice itself lives in
455
+ the surface's Settings, in an "AI & engines" section (Chris 24/10/2026: "đưa hết về nằm trong popup settings để có nhiều
456
+ không gian hơn"). That is the admin's shape: its top-bar "AI: GemBoss AI" opens Settings › AI & engines. Until 0.52.0 the
457
+ chip opened a 360px popup with three tabs; 0.53.0 removed it.
455
458
 
456
459
  ```tsx
457
- import { EnginePicker, BridgeNotice, useEnginePicker } from "@gemboss/ui/assistant"; // brings assistant-engine.css
460
+ import { BridgeNotice, EnginePicker, EngineSettingsSection, useEnginePicker } from "@gemboss/ui/assistant"; // brings assistant-engine.css
458
461
 
459
- const picker = useEnginePicker(); // open + tab, shared with the notice
462
+ // The chip: a door to the surface's Settings, opened on its AI & engines section.
463
+ const picker = useEnginePicker({ onOpenSettings: () => openSettings("ai") });
460
464
  <EnginePicker {...picker.props}
461
465
  engines={[{ id: "claude", label: "Claude Code", note: "Your Claude subscription" }, { id: "server", label: "Server" }]}
462
466
  engine={engine} onEngineChange={setEngine}
@@ -466,47 +470,55 @@ const picker = useEnginePicker(); // open + tab, shared with the notice
466
470
  setup={{ command: installCommand, pairingCode, note: "The panel reconnects in a few seconds." }}
467
471
  statusActions={<button className="ui-btn" onClick={recheck}>Check again</button>} />
468
472
 
473
+ // In the surface's Settings (the kit's SettingsDialog: { id: "ai", label: "AI & engines", icon: "sparkle" }):
474
+ <EngineSettingsSection />
475
+
469
476
  // Only when a turn FAILED because of the bridge, one line in the stream:
470
477
  <BridgeNotice onOpenSetup={() => picker.openTab("setup")}>The bridge on your machine is not responding.</BridgeNotice>
471
478
  ```
472
479
 
473
480
  - **Chip**: engine name, the model when it is not the default (`id: ""`), a dot for `bridge.state`: green `running`,
474
- amber `outdated`, red `offline` / `unpaired`, hollow `checking`. Its accessible name says the state in words.
475
- - **Popup**: a non-modal dialog in the top layer (placed like the kit's menus, `placeFloating`), so the assistant's frame
476
- cannot cut it. Tabs: Engine always; Setup when `setup` is given; Status when `bridge` is given. ←/→/Home/End move
477
- between tabs; ↑/↓ move between engines (one Tab stop). Escape with focus in the panel, or a model / effort pick from
478
- the buttons, closes it and gives focus back to the chip; an outside click closes. An engine pick and a pick from a
479
- select (more than six models, or grouped ones) keep it open. Closing goes back to the Engine tab. 44px targets under a coarse pointer and at phone width.
480
- - **Not in the chat**: no standing warning, no command in the conversation. The amber dot on the chip and on the Setup
481
- tab is the warning. `BridgeNotice` is for a turn that actually failed, once.
481
+ amber `outdated`, red `offline` / `unpaired`, hollow `checking`. Its accessible name says the state in words. A click
482
+ calls `onOpenSettings("engine")`; there is no popup and no `aria-expanded`. 28px under a mouse, 44px under a coarse
483
+ pointer.
484
+ - **The section**: `EngineSettingsSection` draws what the chip on the page was given (`engine-settings-store.ts`: the chip
485
+ publishes its props, the section reads them), so the surface hands its engine props to the chip only and changes
486
+ nothing else. Two cards, one under the other: **Engine** (the engines as radios, or each with its own models; model;
487
+ effort; `notes`) and **Bridge on your machine** (its state as a dotted badge in the card's head; one callout with the
488
+ surface's `detail` for outdated / offline / unpaired, none without a detail; the Version / Starts at sign-in rows,
489
+ `statusActions`, then "Install or update": the steps, the command with Copy, the pairing code, the note).
490
+ Since 0.55.0 each engine row starts with a small picture: its mark (`EngineChoice.mark`, else an id the kit has
491
+ artwork for: `claude`, `codex`), else its initial. Never another engine's logo: "Claude via API" with the id `api` gets a
492
+ "C", not Claude's mark. `engine-plain.js` draws the marks with `gembossUI.engineMark` from `chat-plain.js`, which every
493
+ page with the chip loads. With no chip on the page it says the assistant has not loaded yet (`empty` replaces that line).
494
+ `EngineSettings` takes the props itself, for a surface that holds them where its settings are drawn, and the catalog.
495
+ - **`picker.open`** is the section being SEEN (an IntersectionObserver), not mounted: the kit's SettingsDialog keeps its
496
+ sections mounted while it is closed, and a surface that probes the bridge while `picker.open` would poll for ever.
497
+ - **`picker.openTab("setup" | "status" | "engine")`** asks the section to scroll that part to the top and focus its first
498
+ control (Copy, for Install or update), then calls `onOpenSettings(tab)`. That is `BridgeNotice`'s Open setup.
499
+ - **Keys and picks**: ↑/↓ move between engines and pick (one Tab stop; one that cannot be picked is skipped). A pick
500
+ calls back at once and the chip follows; nothing closes Settings.
501
+ - **Not in the chat**: no standing warning, no command in the conversation. The amber dot on the chip is the warning.
502
+ `BridgeNotice` is for a turn that actually failed, once.
482
503
  - **For the admin (0.29.0)**: `EngineChoice.mark` ("claude", "codex") is shown on the chip in place of the name when the
483
504
  composer is too narrow (`ChatComposer` density icon); `EngineChoice.models` on every engine + `onPick(engine, model)`
484
- lists each engine with its own models at once, and one click picks both and closes (the admin's Polaris popup);
485
- `problem` is a red line on the Engine tab ("Wait for the current answer to finish"); `disabled` disables the chip while
486
- a switch is in flight.
505
+ lists each engine with its own models at once, and one click picks both; `problem` is a red line on the Engine card
506
+ ("Wait for the current answer to finish"); `disabled` disables the chip while a switch is in flight.
487
507
  - The picker itself knows no bridge: the surface hands in its state, the command and the callbacks. Since 0.32.0 the
488
- surface usually gets all three from `useBridge` + `bridgePickerProps` (next section). `EnginePanel` is the same tabs
489
- without the chip (catalog, a settings page).
490
- - **Closing from inside (0.32.0)**: a button in the panel that acts and then shuts it (Stop bridge, Remove, before a
491
- confirm opens) calls `picker.close()`: it closes and puts focus on the chip at once, so the confirm records the chip as
492
- where to return. `picker.props.onOpenChange(false)` (an outside click) closes without moving focus; the button that had
493
- it is gone with the panel, so focus would fall to `<body>`. `picker.focusChip()` / `picker.chipRef` for the rest;
494
- `EnginePicker chipRef` takes your own ref.
495
-
496
- Tests: `packages/ui/src/assistant/engine.test.tsx` (markup, styles, its own entry), `packages/ui/src/assistant/engine-browser.test.tsx`
497
- (Chromium: top layer through a clipping frame, keys, focus, copy, Open setup, 44px; with negative controls).
498
-
499
- **Escape (0.27.0).** An Escape that closes the panel is marked handled (`preventDefault`) also when focus is outside it
500
- (the composer): a surface whose own Escape hides the assistant and checks `defaultPrevented` leaves that key alone, and the
501
- next Escape is its own again. Before, the key went on unmarked and React re-renders between the picker's listener and the
502
- surface's, so each surface needed a window-capture marker to tell the two apart (gemlabs #922, gemfeedback #66). With
503
- 0.27.0 the surface's `!e.defaultPrevented` is enough.
508
+ surface usually gets all three from `useBridge` + `bridgePickerProps` (next section).
509
+ - **Gone in 0.53.0** with the popup: `EnginePanel`; the props `open`, `tab`, `onTabChange`, `end`; the labels `dialog`,
510
+ `tabs`, `engineTab`, `setupTab`, `statusTab`, `updateDue`, `close`. `picker.close()` stays and does nothing, so a Stop /
511
+ Remove handler written for the popup still runs; `picker.focusChip()` / `picker.chipRef` are unchanged.
512
+
513
+ Tests: `packages/ui/src/assistant/engine.test.tsx` (markup, styles, its own entry, and that the popup's classes are no
514
+ longer styled), `packages/ui/src/assistant/engine-settings-browser.test.tsx` (Chromium: the chip opens Settings, picks,
515
+ keys, Copy, Open setup lands on Install or update, seen vs mounted, 44px; with negative controls).
504
516
 
505
517
  ### Plain HTML: `gembossUI.enginePicker()` (0.27.0)
506
518
 
507
- `engine-plain.js`, after `kit-plain.js`, for a page with no React (gemcare). The same markup and classes as the component
508
- (asserted: same class set for the same options), so `assistant-engine.css` draws it, and the same behaviour (top layer,
509
- tabs and keys, focus back to the chip, closing goes back to Engine, Copy, 44px under a coarse pointer, Escape marked):
519
+ `engine-plain.js`, after `kit-plain.js`, for a page with no React (gemcare, gemfactory). The same markup and classes as
520
+ the components (asserted: the same class set as `EnginePicker` for the chip and as `EngineSettings` for the section), so
521
+ `assistant-engine.css` draws it:
510
522
 
511
523
  ```html
512
524
  <link rel="stylesheet" href="/ui/assistant-engine.css"> <!-- require.resolve("@gemboss/ui/assistant-engine.css") -->
@@ -521,31 +533,35 @@ const picker = gembossUI.enginePicker(document.querySelector(".gemboss-ec-toolba
521
533
  models, model, onModelChange, efforts, effort, onEffortChange, effortDisabled, notes, modelControl,
522
534
  bridge: { state: "outdated", version: "8", latest: "10", autostart: true, detail: "…" }, showBridgeDot: true,
523
535
  setup: { command, pairingCode, steps, note }, statusActions: [checkAgainButton],
524
- onOpenChange, onTabChange, locked, end, labels,
536
+ onOpenSettings: (tab) => openSettings("ai"), // required: the chip's click (no popup to fall back to)
537
+ onOpenChange, locked, labels,
525
538
  });
539
+ // The surface's Settings, when it draws its AI & engines section:
540
+ picker.mountSettings(sectionElement); // two cards: Engine · Bridge on your machine (with Install or update)
541
+ picker.unmountSettings(); // when the section goes away
526
542
  picker.update({ bridge: { state: "running" } }); // a poll: bridge / setup / labels merge one level; patched in place
527
- picker.openTab("setup"); picker.close(); picker.isOpen(); picker.destroy();
543
+ picker.openTab("setup"); picker.isOpen(); picker.destroy();
528
544
  log.append(gembossUI.bridgeNotice({ text: "The bridge on your machine is not responding.", onOpenSetup: () => picker.openTab("setup") }));
529
545
  ```
530
546
 
531
547
  Strings are text; `steps`, `notes`, `detail`, `statusActions` and `modelControl` may also be a Node, an array of Nodes or a
532
548
  DocumentFragment: placed once and left where they are, so a field in them keeps focus, caret and events across redraws.
533
- A redraw PATCHES the panel in place (the same elements, only what changed, as React does): focus on a tab, an engine row
534
- or the model select stays, and a clamped panel keeps its scroll; behaviour is delegated from the panel (`data-*`).
535
- A pick from the engine list, the model or the effort updates the picker at once and calls back (no callback: that row is
536
- disabled, as in the component); `update()` is how the page says anything else changed. An Escape it does not own is left
537
- alone: an IME composition, or one in a modal opened from the panel; and focus entering such a modal closes the panel,
538
- which would otherwise sit above it in the top layer (the component does the same since 0.27.0). Tests:
539
- `packages/ui/src/engine-plain.test.ts` (Chromium: the component's class set on all three tabs, top layer through a
540
- clipping frame with its negative control, no popover API, keys, Escape, Copy, redraws that keep focus / scroll / a
541
- caller's field without a blur or change, merge rules, 44px).
549
+ A redraw PATCHES the chip and the section in place (the same elements, only what changed, as React does): focus on an
550
+ engine row or the model select stays, and a keyed block that only shifted (the callout came or went above Install or
551
+ update) is kept, not torn out and put back (0.53.0: that blurred a pairing-code field on a poll). Behaviour is delegated
552
+ from the section (`data-*`). A pick from the engine list, the model or the effort updates the picker at once and calls back
553
+ (no callback: that row is disabled, as in the component); `update()` is how the page says anything else changed.
554
+ `isOpen()` is the section being seen, as in the component; `onOpenChange` says when that changes. Without
555
+ `onOpenSettings` the chip logs a `console.error` and opens nothing. Tests: `packages/ui/src/engine-plain.test.ts`
556
+ (Chromium: the components' class sets, picks, keys, Copy, redraws that keep focus and a caller's field without a blur or
557
+ change, merge rules, seen vs mounted, Open setup, 44px; each with its negative control).
542
558
 
543
559
  ## The bridge (0.32.0): `useBridge`, `createBridgeClient`, `bridgePickerProps`
544
560
 
545
561
  The bridge is the small server a teammate installs on their machine so the assistant can run Claude Code / Codex on their
546
562
  own subscription; the page talks to it at `http://127.0.0.1:<port>`, and the surface's server never sees that call.
547
563
  content-radar, partner-radar and search-radar carried the same ~300 lines for it each (find it behind Chrome's Local Network
548
- Access permission, pair, a data token, a turn and its stream, polls, "it went away", the Setup / Status tabs), and a
564
+ Access permission, pair, a data token, a turn and its stream, polls, "it went away", the setup and status of the bridge), and a
549
565
  review fixed one copy at a time. Once, here:
550
566
 
551
567
  ```tsx
@@ -554,7 +570,7 @@ import { bridgePickerProps, bridgeControlNote, createBridgeClient, postTurn, rea
554
570
  // Module level (one per page): its data token is cached on it.
555
571
  const bridgeClient = createBridgeClient({ port: 8789, codeKey: "pr-bridge-code", app: "partner-radar" });
556
572
 
557
- const picker = useEnginePicker();
573
+ const picker = useEnginePicker({ onOpenSettings: () => openSettings("ai") });
558
574
  const b = useBridge(bridgeClient, { open, wantsLocal: engine !== "api", pickerOpen: picker.open,
559
575
  // An engine that cannot run here (not on the server, and not "your machine only": the bridge may come) → the API one.
560
576
  onDetected: (eng) => setEngine((cur) => (eng[cur] && !eng[cur].installed && !eng[cur].localOnly && eng.api?.installed ? "api" : cur)) });
@@ -574,8 +590,7 @@ async function send(text) {
574
590
  }
575
591
  }
576
592
 
577
- async function onControl(kind) { // Stop / Remove on Status
578
- picker.close(); // closes, focus on the chip (the confirm returns there)
593
+ async function onControl(kind) { // Stop / Remove on the bridge card in Settings
579
594
  if (kind === "remove" && !(await confirm(…))) return;
580
595
  try { turns.note(bridgeControlNote(kind, await b.control(kind)), { bridge: true }); }
581
596
  catch (e) { turns.note(`Couldn't ${kind} the bridge: ${e.message}`); }
@@ -607,8 +622,8 @@ async function onControl(kind) { // Stop / Remove on Status
607
622
  with the Pair form; another HTTP error leaves the state), `recheck()`. On the dev machine (`local`, default: the page is
608
623
  on localhost) it probes nothing; `b.local` switches after mount, so the server's markup and the first render agree. The
609
624
  client is the first render's for the hook's life (make it at module level: its data token is cached on it).
610
- - **`bridgePickerProps(b, { latest, … })`** → `bridge`, `setup`, `statusActions` for `EnginePicker`: the dot and Status
611
- rows, Setup per case (Allow / unblock / the Pair form + command / install / update), Check again, Stop and Remove
625
+ - **`bridgePickerProps(b, { latest, … })`** → `bridge`, `setup`, `statusActions` for `EnginePicker`: the dot and the state
626
+ rows, Install or update per case (Allow / unblock / the Pair form + command / install / update), Check again, Stop and Remove
612
627
  (`controls`). The words are `BRIDGE_SETUP_EN` (`labels` overrides); `outdatedDetail` and `installNote` are the surface's.
613
628
  - What stays the surface's: which engines exist and what they cost, the request body, what each event does to its
614
629
  messages, its confirm dialog.
@@ -633,14 +648,14 @@ streaming, bridge and sessions. Each piece is the better of the two surfaces tha
633
648
  | Starters | `ChatStarters` | partner-radar | they wrap (radius 12): a long question as a nowrap pill is cut in a 400px panel; a fill-in example |
634
649
  | Under an answer | `ChatMeta` | partner-radar | Copy · engine · seconds · cost |
635
650
  | Errors | `ChatError`, `BridgeNotice` | partner-radar | a fix the user can take (sentence, command, Copy, the original folded); a bridge failure is one line |
636
- | Engine | `EnginePicker` | partner-radar (Setup / Status tabs) + admin (mark, models per engine) | see "The engine picker" |
651
+ | Engine | `EnginePicker` + `EngineSettingsSection` | partner-radar (bridge setup and status) + admin (mark, models per engine) | see "The engine picker" |
637
652
  | Frame, sessions | `AssistantHost`, `SessionRail` | (already the package's) | |
638
653
 
639
654
  ```tsx
640
655
  import { AssistantChat, ChatAttach, EnginePicker, useChatTurns, useEnginePicker } from "@gemboss/ui/assistant"; // brings its CSS
641
656
 
642
657
  const turns = useChatTurns(); // messages with ids; a turn is written BY ID
643
- const picker = useEnginePicker();
658
+ const picker = useEnginePicker({ onOpenSettings: () => openSettings("ai") });
644
659
  async function send(text: string) {
645
660
  turns.say(text);
646
661
  const id = turns.start();
@@ -1725,12 +1740,16 @@ an icon) · `.gemboss-ei-pick-text` › `.gemboss-ei-pick-head` (`.gemboss-ei-pi
1725
1740
  `[data-autofocus]`, which both containers focus as they open (a `Dialog` without one gives the focus to its ✕). Under a finger
1726
1741
  (`(pointer: coarse)`) the box does not take the focus by itself: the on-screen keyboard would cover the list. Escape in a box
1727
1742
  with words clears them; in a list inside a list (the Popover's `onBack`) it steps back, as ← Back; otherwise the container
1728
- closes and the focus goes back to what opened it.
1743
+ closes and the focus goes back to what opened it (a `Dialog` opened by a click on a button that blurred itself, as Polaris'
1744
+ do, still finds it: the control the press landed on).
1729
1745
  - Keys: ↑ ↓ move the highlight past locked rows, Enter picks; in the box Escape clears the words before the popup closes;
1730
1746
  with no box the list is one tab stop and Home / End work too. One click picks.
1731
1747
  - States: `loading` (skeleton rows, a first read), `reloading` (the last answer's rows kept, dimmed and `aria-busy`, nothing
1732
1748
  pickable from them while the next search is read), `error` (the kit's danger notice, Try again with `onRetry`), no match
1733
1749
  (Clear search, the focus back in the box), `empty`, `more` (Show more, after the list).
1750
+ - `pinned` (25/10/2026): rows that do not come from the source, such as an empty value that is a choice ("This page's product"):
1751
+ first and pickable in every state, with the source's own state under them (its skeleton, error, empty or no-match words). In
1752
+ `reloading` only the source's rows dim (`.is-stale`). Leave them out while words are typed if they are no match for words.
1734
1753
 
1735
1754
  Its own part (`editor-picker.css`, 1.0 KB gzip).
1736
1755
 
@@ -8,7 +8,7 @@
8
8
  .cat-code summary{padding:10px 16px;font-size:13px;cursor:pointer;color:var(--gemboss-text-muted);border-top:1px solid var(--gemboss-divider);min-height:24px}
9
9
  .cat-code pre,.cat-api{margin:0;padding:12px 16px;overflow:auto;background:#0f1012;color:#e8e8e6;font-size:12px;line-height:1.5;border-radius:0}
10
10
  .cat-api{border-radius:12px;margin:0 0 16px}</style></head><body><div class="cat">
11
- <h1>@gemboss/ui 0.52.0 · Editor</h1>
11
+ <h1>@gemboss/ui 0.55.0 · Editor</h1>
12
12
  <p>Khung của mọi editor: <code>EditorFrame</code> (cột trái · khe kéo · preview · cột phải dock trên mép phải preview) và <code>EditorTopbar</code> (← · tiêu đề · cụm giữa · cụm phải · dòng trạng thái). Là đúng khung của theme / page / section editor trong admin. Gói chỉ vẽ KHUNG; chat, Configure, canvas, page picker, menu, Publish là của editor, đi vào bằng slot. Trang HTML thuần nạp <code>editor.css</code> + <code>editor-plain.js</code> rồi gọi <code>gembossUI.initEditorFrame()</code>: kéo khe (chuột, chạm, phím mũi tên / Home / End), đổi thiết bị, mở ⋯ và Publish ▾, ẩn cột trái, Chat | Preview trên điện thoại. <a href="index.html">← Catalog</a></p>
13
13
  <h2>React</h2><pre class="cat-api"><code>import &quot;@gemboss/ui/editor.css&quot;;
14
14
  import { EditorFrame, EditorTopbar, EditorBack, EditorChatToggle, EditorPaneTabs, EditorSaveState, DeviceToggle } from &quot;@gemboss/ui/editor&quot;;