@gemboss/ui 0.30.2 → 0.32.0

package/CHANGELOG.md

@@ -2,6 +2,104 @@
 
 Versions up to 0.9.0 are described in the README, each in the section that introduced it.
 
+## 0.32.0 (09/10/2026)
+
+**The bridge, once** (assistant sync, Chris 08/10/2026: "mọi service có panel này đồng bộ style + code dùng gemboss ui").
+content-radar, partner-radar and search-radar each carried ~300 lines for the bridge on the user's machine, copied one
+from the other, and reviews fixed one copy at a time. README "The bridge".
+
+Added
+- `createBridgeClient({ port, codeKey, app, tokenPath?, tokenSince? })`: `probe`, `detect` (Chrome's Local Network Access
+  permission read first; asked from a click only), `ensureCode`, `installCommand`, `dataToken` (reused until under an hour
+  is left; its error is the turn's), `turn(body, { signal, version })` (code + token; errors marked `atBridge` with the
+  status, so `bridgeTurnError` reads 401 as "another code" and a dead connection as "gone"), `control("stop" | "remove")`.
+- `readTurnEvents(res, onEvent, { atBridge })` (the turn's `data:` events, whole across chunks, heartbeats skipped; a
+  read that dies is the bridge's only for the bridge's stream; a stream that ends without `done` throws
+  `BRIDGE_CLOSED_EARLY` / `SERVER_CLOSED_EARLY` instead of showing half an answer as done; an early exit cancels the
+  reader) and `postTurn(url, body)` for the surface's own route.
+- `useBridge(client, { open, wantsLocal, pickerOpen, statusUrl, onDetected })`: probes while open, the server's engines
+  and the bridge together, merged (`engines`); a 3 s poll while a teammate installs; again on focus / tab / permission
+  change, also once paired, one at a time, and dropped when the user acted while it was out (an epoch); `lost()`,
+  `pair(code)`, `allowAccess()`, `control(kind)` (401 → Not connected, no answer → lost), `recheck()`. `local` is decided
+  after mount (no hydration mismatch on the dev machine); the client is pinned to the first render; a pairing code that
+  storage refuses lives in memory, so the command and the turns carry the same one.
+- `bridgePickerProps(b, { latest, busy, controls, onControl, outdatedDetail, installNote, labels })` → `EnginePicker`'s
+  `bridge`, `setup` (per case: Allow / unblock / `BridgePairForm` + command / install / update) and `statusActions`
+  (Check again, Stop, Remove). `BRIDGE_SETUP_EN`, `bridgeControlNote`, `pickerBridgeState`, `mergeBridgeEngines`.
+- `useEnginePicker().close()`: closes and puts focus on the chip at once (Stop / Remove before a confirm opens); also
+  `focusChip()`, `chipRef`, and `EnginePicker chipRef`. Every surface did it with `querySelector(".gb-engine-chip")`.
+- `AssistantChat` / `ChatMarkdown` `linkPolicy(href, label, target)`: one prop for every link in an answer (written, bare,
+  a picture from another host): `true` = the kit's link, `false` = its words, a node = drawn as given; `target` is what
+  the kit would link (normalised) or null, for a policy that draws its own link. Replaces the
+  `ownLink` + `renderLink` pair used to turn links into text (kept; `linkPolicy` wins when both are given). A claimed
+  token carries `own: true`. React only (`chat-plain.js` is at its weight ceiling; gemcare keeps the pair).
+
+Changed
+- `AssistantChat` goes back to the end when a user message is ADDED, wherever it was sent from (a page's button, the
+  📎 upload): before, only a send from its own composer did, and partner-radar scrolled by hand (#968). A note or an
+  answer arriving while the reader is up leaves them there, and so does an edit that drops a user message or swaps its id
+  (negative controls in chat-browser.test.tsx; the 0.31.0 pinKey fails the new test: 1717px from the end).
+- `BridgePairForm` says "Pairing…" and takes one press at a time while the probe runs (up to 8 s).
+- `chat-plain.js`: a token its `ownLink` claims carries `own: true`, like the React parser's.
+
+No stylesheet changed; chat-plain.js stays under its weight ceiling. New tests: bridge.test.tsx (14),
+bridge-browser.test.tsx (8, Chromium, fake bridge on test port 8797 answered by the router: open, poll, lost, pair,
+permission, Stop, a stale probe after Stop, Stop answered 401), chat.test.tsx (+2), chat-browser.test.tsx (+1),
+engine-browser.test.tsx (+1). Review #3952 (in this version): probes ordered by an epoch and one at a time, a stream
+without `done` is an error, the reader is cancelled on an early exit, `linkPolicy` gets the checked target, the
+README's `onDetected` keeps a "your machine only" engine, a stored-code fallback in memory, `local` after mount, the
+client pinned, Stop's 401 is Not connected, the pinKey counts additions only.
+
+## 0.31.0 (09/10/2026)
+
+The assistant header groups its controls (Chris 08/10/2026: "cái button clear history cần đưa lên topbar để tiết kiệm
+không gian nhưng trên đó nhiều icon rồi nên cần gom nhóm"). One change in the package, every surface follows.
+
+- `AssistantHost` header: four controls, ＋ New chat, ⤢ Open full screen, ⋯ More, × Close. "Pin to the side" /
+  "Float as a popup" and "Shrink to a bar" (minimise) are rows of ⋯ now, not icons. At 1440 the header held five.
+- `onClearHistory` (+ `canClearHistory`): a "Clear history" row (danger) in ⋯, in the panel header and in full screen's
+  chrome. The surface confirms (it knows what is cleared). Before this, content-radar spent a 44px row of its body on it.
+- `menuItems` + `AssistantMenuItem`: a surface's own rows at the top of ⋯.
+- ⋯ wears the fleet's row (`ui-menu__item`) and surface (`gemboss-popover-surface`) from shell.css, which the admin
+  loads; its placement is in assistant.css (`.gb-dock-menu*`), because the kit's `.ui-menu` rules are in kit-plain.css,
+  which the admin does not load. Escape closes ⋯ only (focus back on ⋯; the surface's "Escape hides the assistant" does
+  not fire on the same key; an Escape meant for a modal elsewhere is left to it); a press outside or the window losing
+  focus closes it; pressing ⋯ does not drag the popup. A row closes ⋯ and focuses it BEFORE its handler, so a confirm
+  the handler opens returns focus to ⋯, not to <body>. No `menu` / `menuitem` roles (no arrow keys, like the kit's Menu);
+  the rows do not inherit the popup header's "Drag this bar…" tooltip.
+- Labels `more`, `clearHistory`. Tests: `assistant/header-menu.browser.test.ts` (Chromium, the admin's stylesheets only).
+
+`SearchDialog` for a surface whose topbar centre IS the search (content-radar, 08/10/2026: "click opens a popup like
+other surfaces"):
+
+- `trigger="field"`: the door is the topbar's search box (TopbarSearch's `gemboss-topbar-search`: 36px, 44px under a
+  finger or at phone width, the hint at the right, `hint` prop, ⌘K by default), a link that opens the popup. `icon`
+  (default) is the 36px magnifier as before.
+- `SearchItem.external`: a result outside the surface opens in a new tab (link or Enter) and the popup closes behind it,
+  marked ↗. Before, every result navigated the tab, so a collected post took the person off the surface.
+- A search that throws says "Search failed: <message>" instead of "Nothing matches.".
+- `onNavigate(href)`: a result inside the surface (Enter, plain click) goes through it instead of a full reload, so a
+  Next surface keeps a running assistant answer (content-radar passes `router.push`). ⌘ / Ctrl / Shift / Alt-click is
+  left to the browser and keeps the popup open.
+- `minChars`: fewer characters say "Type at least N characters." instead of "Nothing matches.".
+- Escape closes the popup in one press and is marked handled: a surface's own window listener ("Escape hides the
+  assistant") no longer fired on the same key, and the search box's clear-the-words Escape no longer took the first press.
+- The `field` door has no aria-label: its name is the words on it (WCAG 2.5.3).
+- Closing forgets the answer, and an answer still on its way when it closed: reopened, the popup drew the previous results
+  and highlight for a frame, and Enter in that frame opened the previous highlight. Tests: `search-dialog.browser.test.ts` (with a negative control: the reopen case
+  goes red without the reset).
+
+`.ui-btn--on` (ui.css): the ON look for a plain button (accent-soft fill, accent border, accent-strong text, the kit's
+selected look), for a CTA whose thing is already in effect ("Scheduled · Fri 09:00").
+
+## 0.30.3 (09/10/2026)
+
+- The inspector under a finger (`pointer: coarse`): its tabs (`.gemboss-ei-tab`, were 27px) and group heads
+  (`.gemboss-ei-gh`, were 13px) are at least 44px tall, and its colour swatches (`.gemboss-ei-sw`) are 44x44 (were 30x30)
+  and wrap in a narrow column. Measured on the funnel canvas's theme Settings tab at 320 / 390 / 768 with touch; the theme
+  editor's inspector is the same component. Mouse sizes are unchanged. (The lockfile's entry for the package was still
+  0.30.1; it now says 0.30.3.)
+
 ## 0.30.2 (09/10/2026)
 
 The admin's chat moves onto the package's composer and engine picker (gemboss admin, assistant sync).

package/README.md

@@ -290,6 +290,17 @@ Its styles are the `gemboss-assistant-*` rules in `packages/ui/src/shell.css` (t
 @imports too), and they reach you through `gemboss-ui.css` together with `gemboss-field.css`. The admin passes a second tab ("Talk to a person", gemcare) through `secondTab` and its button
 through `fullActions`; a surface without those leaves them out.
 
+**The header's ⋯ menu (0.31.0).** The header shows four controls: ＋ (`onNewChat`), full screen, ⋯ and ×. ⋯ holds
+what is used once in a while: your rows (`menuItems`, as `AssistantMenuItem`s), "Clear history" when you pass
+`onClearHistory` (greyed out with `canClearHistory={false}`; confirm inside your handler), then pin / float and
+minimise. Full screen's chrome shows ⋯ too when you pass either. Do not draw a Clear button of your own in the body.
+
+```tsx
+<AssistantHost title="Radar Assistant" onNewChat={reset} onExpand={expand} onShrink={shrink}
+  onClearHistory={clearHistory} canClearHistory={messages.length > 0}
+  menuItems={<AssistantMenuItem onClick={exportChat}>Export chat</AssistantMenuItem>}>
+```
+
 ## The engine picker (0.25.0): `EnginePicker`, `BridgeNotice`
 
 Which engine answers the assistant, and the bridge on the user's machine, without spending the chat's space on it
@@ -327,8 +338,14 @@ const picker = useEnginePicker();          // open + tab, shared with the notice
   lists each engine with its own models at once, and one click picks both and closes (the admin's Polaris popup);
   `problem` is a red line on the Engine tab ("Wait for the current answer to finish"); `disabled` disables the chip while
   a switch is in flight.
-- The package knows no bridge: the surface polls its own, computes `outdated`, builds the command, and owns the
-  behaviour of every callback. `EnginePanel` is the same tabs without the chip (catalog, a settings page).
+- The picker itself knows no bridge: the surface hands in its state, the command and the callbacks. Since 0.32.0 the
+  surface usually gets all three from `useBridge` + `bridgePickerProps` (next section). `EnginePanel` is the same tabs
+  without the chip (catalog, a settings page).
+- **Closing from inside (0.32.0)**: a button in the panel that acts and then shuts it (Stop bridge, Remove, before a
+  confirm opens) calls `picker.close()`: it closes and puts focus on the chip at once, so the confirm records the chip as
+  where to return. `picker.props.onOpenChange(false)` (an outside click) closes without moving focus; the button that had
+  it is gone with the panel, so focus would fall to `<body>`. `picker.focusChip()` / `picker.chipRef` for the rest;
+  `EnginePicker chipRef` takes your own ref.
 
 Tests: `packages/ui/src/assistant/engine.test.tsx` (markup, styles, its own entry), `packages/ui/src/assistant/engine-browser.test.tsx`
 (Chromium: top layer through a clipping frame, keys, focus, copy, Open setup, 44px; with negative controls).
@@ -377,6 +394,83 @@ which would otherwise sit above it in the top layer (the component does the same
 clipping frame with its negative control, no popover API, keys, Escape, Copy, redraws that keep focus / scroll / a
 caller's field without a blur or change, merge rules, 44px).
 
+## The bridge (0.32.0): `useBridge`, `createBridgeClient`, `bridgePickerProps`
+
+The bridge is the small server a teammate installs on their machine so the assistant can run Claude Code / Codex on their
+own subscription; the page talks to it at `http://127.0.0.1:<port>`, and the surface's server never sees that call.
+content-radar, partner-radar and search-radar carried the same ~300 lines for it each (find it behind Chrome's Local Network
+Access permission, pair, a data token, a turn and its stream, polls, "it went away", the Setup / Status tabs), and a
+review fixed one copy at a time. Once, here:
+
+```tsx
+import { bridgePickerProps, bridgeControlNote, createBridgeClient, postTurn, readTurnEvents, useBridge } from "@gemboss/ui/assistant";
+
+// Module level (one per page): its data token is cached on it.
+const bridgeClient = createBridgeClient({ port: 8789, codeKey: "pr-bridge-code", app: "partner-radar" });
+
+const picker = useEnginePicker();
+const b = useBridge(bridgeClient, { open, wantsLocal: engine !== "api", pickerOpen: picker.open,
+  // An engine that cannot run here (not on the server, and not "your machine only": the bridge may come) → the API one.
+  onDetected: (eng) => setEngine((cur) => (eng[cur] && !eng[cur].installed && !eng[cur].localOnly && eng.api?.installed ? "api" : cur)) });
+// b.bridge (absent | unpaired | paired | needs-permission | asking | blocked, + lost / off / wrong), b.status (the
+// server's engines), b.engines (merged: a paired bridge's engines replace "runs on your machine only"), b.pairCode.
+
+async function send(text) {
+  const viaBridge = engine !== "api" && b.paired;
+  const body = { message: text, engine, sessionId, page };
+  const id = turns.start();
+  try {
+    const res = viaBridge ? await bridgeClient.turn(body, { signal, version: b.version }) : await postTurn("/api/assistant", body, { signal });
+    await readTurnEvents(res, (ev) => { if (ev.type === "text") turns.write(id, ev.delta); /* … */ }, { atBridge: viaBridge });
+    turns.finish(id);
+  } catch (e) {
+    if (turns.fail(id, e).bridge) b.lost();       // gone / 401 → BridgeNotice + probe again; anything else is the turn's
+  }
+}
+
+async function onControl(kind) {                  // Stop / Remove on Status
+  picker.close();                                  // closes, focus on the chip (the confirm returns there)
+  if (kind === "remove" && !(await confirm(…))) return;
+  try { turns.note(bridgeControlNote(kind, await b.control(kind)), { bridge: true }); }
+  catch (e) { turns.note(`Couldn't ${kind} the bridge: ${e.message}`); }
+}
+
+<EnginePicker {...picker.props} engines={…} engine={engine} onEngineChange={setEngine}
+  {...bridgePickerProps(b, { latest: BRIDGE_LATEST, busy, controls: engine !== "api", onControl,
+    installNote: "… A bridge installed for content-radar does not count: this one uses another port." })}
+  showBridgeDot={engine !== "api"} />
+```
+
+- **`createBridgeClient`** (no React): `probe(code)` (401 = another code → `unpaired`; any failure → `absent`; never
+  throws), `detect({ fromClick })` (reads the permission first: `denied` → `blocked`; not asked → `needs-permission`
+  and no call at all; from a click it waits 60 s, the dialog's time), `ensureCode()` (8 characters, no 0/O/1/I, kept in
+  `codeKey`), `installCommand(code)`, `dataToken()` (POST `tokenPath`, reused until under an hour is left; its error is the
+  turn's, never the bridge's), `turn(body, { signal, version })` (adds the code and the token; `tokenSince` keeps the
+  header off an older bridge whose CORS refuses it; throws marked `atBridge`, with the status), `control("stop" | "remove")`.
+- **`readTurnEvents(res, onEvent, { atBridge })`**: the turn's `data: {…}` events, whole across chunks, `: ping` skipped. A
+  read that throws is the bridge's only for the bridge's stream; the user's Stop stays a Stop. A stream that ends WITHOUT
+  `done` throws (`BRIDGE_CLOSED_EARLY`, the bridge's; `SERVER_CLOSED_EARLY`, the turn's): half an answer is not a finished
+  one. Any early exit cancels the reader, so the bridge sees the client go. `postTurn(url, body)` is the same POST to the
+  surface's own route (errors unmarked, with `status`).
+- **`useBridge`**: probes only while `open`, the server's engines and the bridge together (`statusUrl`, default
+  `/api/assistant`); every 3 s while `wantsLocal` and nothing is found (a teammate is installing); again on focus, on
+  return to the tab and on a permission change, also once paired (a bridge that stops is noticed); never over a state the
+  user is in the middle of (`asking`, a wrong code), and never over a user action that happened while it was out (an
+  epoch: a `/status` that left before Stop does not bring "running" back); one background probe at a time. `lost()` after
+  a failed turn, `pair(code)`, `allowAccess()` from the Allow click, `control(kind)` (no answer → lost; 401 → Not connected
+  with the Pair form; another HTTP error leaves the state), `recheck()`. On the dev machine (`local`, default: the page is
+  on localhost) it probes nothing; `b.local` switches after mount, so the server's markup and the first render agree. The
+  client is the first render's for the hook's life (make it at module level: its data token is cached on it).
+- **`bridgePickerProps(b, { latest, … })`** → `bridge`, `setup`, `statusActions` for `EnginePicker`: the dot and Status
+  rows, Setup per case (Allow / unblock / the Pair form + command / install / update), Check again, Stop and Remove
+  (`controls`). The words are `BRIDGE_SETUP_EN` (`labels` overrides); `outdatedDetail` and `installNote` are the surface's.
+- What stays the surface's: which engines exist and what they cost, the request body, what each event does to its
+  messages, its confirm dialog.
+
+Tests: `bridge.test.tsx` (the client, the stream and the picker's props, with fetch and the permission faked),
+`bridge-browser.test.tsx` (Chromium, a fake bridge on a test port answered by the router: open, poll, lost, pair,
+permission, Stop; each with its negative control).
+
 ## The chat body (components since 0.29.0)
 
 Chris 08/10/2026: "đồng bộ hết giao diện của AI assistant… mọi service có panel này đồng bộ style + code dùng gemboss ui".
@@ -440,7 +534,16 @@ async function send(text: string) {
   bridge's); an `AbortController` you abort yourself throws an `AbortError`, which reads as the user's Stop.
 - **Following the end**: the log follows while the reader is at the end, and stops at their first move up (wheel, finger,
   ArrowUp / PageUp / Home), not 24px later. A send, or another conversation shown, brings it back (`ChatThread pinKey`;
-  `AssistantChat` does both).
+  `AssistantChat` does both). Since 0.32.0 so does a NEW user message from anywhere: a page's "Ask about this partner", the
+  📎 upload, a surface's own starter (no `requestAnimationFrame(() => thread.scrollTop = …)` in the surface any more). A
+  note or an answer arriving while the reader is up leaves them where they are.
+- **Links** (0.32.0): `linkPolicy={(href, label, target) => …}` decides for EVERY link in an answer (written, bare, a
+  picture from another host), asked with the href as written and `target`, what the kit would link (`linkTarget`,
+  normalised) or null when it refuses it: `true` / undefined = the kit's link (in-app through `onNavigate`, https in a new
+  tab, words when `target` is null); `false` / null = its words; any other node is drawn as given (a router link, a
+  `customer:12` button). Drawing your own link for an ordinary URL: build it from `target.href`, never the raw `href`. The radars' "this path is text" is `linkPolicy={(h) => !keepAsText(h)}`.
+  `ownLink` + `renderLink` still work; `linkPolicy` wins when both are given. React only: `chat-plain.js` keeps the pair
+  (it sits at its weight ceiling, and gemcare, its one user, draws only its own scheme).
 - **Full screen**: `AssistantChat` measures how far the frame's floated buttons (`fullActions`, Back) reach into it and
   gives its heading (or, without one, its log) that much room (`useFullChromeRoom`, for your own column); a `fullActions`
   button with no icon keeps its words on a phone. Measured in the child because only the child knows where its column is
@@ -1169,7 +1272,12 @@ import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeSc
 - `SearchDialog`: the topbar search button opening a 640px popup (Featurebase's, the admin's ⌘K).
   `initial` before typing, `search(q)` while typing (150 ms debounce, latest answer wins); ↑ ↓ Enter
   Esc; ⌘K / Ctrl+K and "/" open it. Results are links; without JavaScript the button goes to
-  `fallbackHref`.
+  `fallbackHref`. 0.31.0: `trigger="field"` draws the door as the topbar's search box (TopbarSearch's look, `hint`
+  at its right edge) for a surface whose topbar centre is the search; `external: true` on a result opens it in a new
+  tab (↗) and closes the popup; a `search` that throws shows "Search failed: …"; `onNavigate(href)` takes results inside
+  the surface without a full reload (pass `router.push`); `minChars` asks for more characters before searching. Escape
+  closes it in one press and is marked handled (`defaultPrevented`); a surface listening for Escape in the CAPTURE phase
+  runs before it, so check `document.querySelector("dialog[open]")` there.
 - `Dialog`: the kit's native `<dialog class="ui-modal">` (see kit-plain.css) driven by `open`; a
   backdrop click closes it, focus returns to the opener.
 - `ThemeToggle` + `themeScript`: `data-theme="dark|light"` on <html>, remembered in localStorage

package/catalog/editor.html

@@ -8,7 +8,7 @@
 .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}
 .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}
 .cat-api{border-radius:12px;margin:0 0 16px}</style></head><body><div class="cat">
-<h1>@gemboss/ui 0.30.2 · Editor</h1>
+<h1>@gemboss/ui 0.32.0 · Editor</h1>
 <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>
 <h2>React</h2><pre class="cat-api"><code>import &quot;@gemboss/ui/editor.css&quot;;
 import { EditorFrame, EditorTopbar, EditorBack, EditorChatToggle, EditorPaneTabs, EditorSaveState, DeviceToggle } from &quot;@gemboss/ui/editor&quot;;