@gemboss/ui 0.13.0 → 0.25.0

package/README.md

@@ -11,7 +11,10 @@ npm install @gemboss/ui
 ```
 
 ```tsx
-import "@gemboss/ui/gemboss-ui.css";
+// The core, once, in the root layout, FIRST and in this order (0.23.0; "Load only what you use" below):
+import "@gemboss/ui/core.css";
+import "@gemboss/ui/components.css";
+import "@gemboss/ui/shell.css";
 import { AppShell, RailItem, RailGroup, RailHeading, BrandLockup } from "@gemboss/ui";
 
 <AppShell
@@ -40,6 +43,88 @@ Surfaces with no React (gemcare, gempress) use the CSS alone and write the same
 `nav.icon-nav > .gnav-scroll > .gnav-group > a.gnav-item > span.gnav-ico + span.gnav-label`.
 `packages/ui/src/shell.tsx` is the reference.
 
+## Load only what you use: the core and the entries (0.23.0)
+
+Every surface used to load `gemboss-ui.css` whole and use 14–21% of it (measured 06/10/2026 on twelve surfaces). Since
+0.23.0 the CSS comes in parts (`packages/ui/scripts/parts.mjs` is the list): a CORE every surface loads once, and ENTRIES that
+come with the component that draws them. A React component imports its own entry (`auth.tsx` imports `auth.css`), so
+a Next or Vite surface downloads an entry only on the routes that render it, and a component it never imports takes
+its CSS out of the build with it (`sideEffects`). gzip of the minified file, as published:
+
+| Part | Import (Node / bundler) | File in the tarball | What | gzip | Who loads it |
+|---|---|---|---|---:|---|
+| core | `@gemboss/ui/core.css` | `parts/core.css` | the box-sizing reset + the tokens | 1.0 KB | every surface, first |
+| components | `@gemboss/ui/components.css` | `parts/components.css` | the kit (`ui.css`), the field look, the plain-HTML primitives (`kit-plain.css`: menu, chips, report pieces, popup body) | 8.2 KB | every surface, second |
+| shell | `@gemboss/ui/shell.css` | `parts/shell.css` | rail, topbar, main, mobile drawer, the thread rail, topbar slots, base text, page widths (`app-shell.css`) | 5.5 KB | every surface, third |
+| auth | `@gemboss/ui/auth.css` | `packages/ui/src/auth.css` | the sign-in screen | 2.6 KB | `AuthLayout` & co. import it |
+| assistant | `@gemboss/ui/assistant.css` | `packages/ui/src/assistant.css` | the dock and the launcher | 2.2 KB | `AssistantHost`, the launcher import it |
+| portal | `@gemboss/ui/portal.css` | `packages/ui/src/portal.css` | `TopbarNav`, `SearchDialog`, `Avatar`, `Leaderboard`, `Podium`, the `ThemeToggle` button | 2.1 KB | those components import it |
+| theme-dark | `@gemboss/ui/theme-dark.css` | `packages/ui/src/theme-dark.css` | the dark palette | 0.6 KB | `ThemeToggle` and `themeScript` (`theme-script.ts`, without portal.css) import it |
+| collections | `@gemboss/ui/collections.css` | `packages/ui/src/collections.css` | tables, lists, grids, boards | 4.6 KB | `IndexTable`, `ResourceList`, `Board`… import it |
+| editor | `@gemboss/ui/editor.css` | `packages/ui/src/editor.css` | the editors | 7.9 KB | the `@gemboss/ui/editor` components import it |
+| reactions | `@gemboss/ui/reactions.css` | `packages/ui/src/reactions.css` | the emoji reactions and their picker | 0.8 KB | `Reactions` / `ReactionPicker` import it |
+| 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 |
+| 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 surface (no package component draws it) |
+| bundle | `@gemboss/ui/gemboss-ui.css` | `gemboss-ui.css` | core + components + shell + auth + assistant + chat + portal + theme-dark | 21.7 KB | compatibility only (see CHANGELOG 0.23.0) |
+
+The core alone is 14.7 KB against 21.7 for the bundle (each part opens with a short header naming the gemboss commit, kept through minify, so a surface serving the parts can still say which commit its CSS is); a list page adds collections (4.6), a sign-in page auth (2.6).
+
+**Next.js / Vite.** The core's three imports go at the top of the root layout, above any component import, in the
+order above. Entries need nothing: the components bring them. A page that writes chat markup itself imports
+`@gemboss/ui/chat.css`. Drop `gemboss-ui.css` IN THE SAME BUMP: kept beside the parts, the entries a component brings
+load a second time, after your own CSS, and a second copy of a rule you override wins again.
+
+```tsx
+// app/layout.tsx
+import "@gemboss/ui/core.css";
+import "@gemboss/ui/components.css";
+import "@gemboss/ui/shell.css";
+import "./globals.css";            // your own CSS after the core
+```
+
+Add `"@gemboss/ui"` to `experimental.optimizePackageImports` in `next.config` (the admin does, 0.23.0): a SERVER
+component that imports from the index otherwise collects the CSS of every module the index re-exports (the admin's
+`/login`, which imports `AuthHelp` in its server page, picked up portal.css and collections.css under webpack until it did).
+
+Which bundler drops what (measured 06/10/2026): Next 16 (Turbopack) leaves out the entry of a component a route does
+not render. content-radar on 0.23.0 with the core: `/v2` 38.5 → 32.3 KB gzip of CSS, `/login` 31.2 → 25.4 (auth.css
+only there, portal.css nowhere). esbuild keeps the CSS of every module the index reaches even when it drops their JS, so
+through `@gemboss/ui` it ships every entry the index re-exports; and esbuild with no CSS loader now stops at a
+component's `import "./x.css"`: give it `loader: { ".css": "empty" }` (you link the CSS yourself, as GemFactory's
+gbui.mjs and this package's tests do) or `"css"`.
+
+**Plain HTML** (a server that serves the files out of `node_modules`): link the core, then only the entries the page
+draws.
+
+```html
+<link rel="stylesheet" href="/ui/core.css">        <!-- require.resolve("@gemboss/ui/core.css") -->
+<link rel="stylesheet" href="/ui/components.css">  <!-- require.resolve("@gemboss/ui/components.css") -->
+<link rel="stylesheet" href="/ui/shell.css">       <!-- require.resolve("@gemboss/ui/shell.css") -->
+<link rel="stylesheet" href="/ui/auth.css">        <!-- the sign-in page only -->
+<link rel="stylesheet" href="/ui/collections.css"> <!-- list pages only -->
+```
+
+**Order.** The core loads FIRST, and its three parts in that order: the top lines of the root layout, or the first three
+`<link>`s. `shell.css` restyles the field look at phone width, and entries restyle the kit with BEM modifiers at the
+kit's own weight (`.ui-empty--no-match` after `.ui-empty`): both are written to follow what they modify, which keeps
+every rule at the weight your own CSS can override. After the core, the entries may land in any order:
+`packages/ui/scripts/cascade-check.mjs` loads the catalog with the entries (collections.css and editor.css included) after the core,
+in order and reversed, and holds every element's computed style to the bundle's at 1280 and 390 (`parts-cascade.test.ts`,
+CI; negative control: two entries that only agree by order). An entry loaded BEFORE the core is not supported: measured,
+`.ui-empty--no-match` loses its 32px padding to `.ui-empty`. Two kit-plain.css rules that overrode shell.css by coming
+after it (the menu row's flex, the thread rail's 44px buttons at phone width) moved to the end of app-shell.css, same
+weight, so they still follow it.
+
+**A new component** gets its own entry: a file in `src/`, listed in `ENTRIES` in `packages/ui/scripts/parts.mjs`, exported,
+imported by the component that draws it, with a ceiling in `weight-budget.json`. It never goes into the core or into
+`gemboss-ui.css`: `packages/ui/scripts/parts-gate.mjs` (CI) holds both frozen, fails on a stylesheet nobody classified, and on a
+component that draws an entry's class without importing it.
+
+**The admin** is unchanged: it has Polaris and its own order, so it imports the sources one by one
+(`gemboss-tokens.css`, `ui.css`, and `shell-source.css` from its `gemboss-shell.css`; `@gemboss/ui/shell.css` is the
+built part now). Its editor, assistant and sign-in modules already imported the same entry files the components now
+import, so nothing moves.
+
 ## Page width (0.8.1)
 
 Chris, 04/10/2026: the rail on the left, and on the right a content column with the same max width on every
@@ -187,6 +272,44 @@ 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 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
+(Chris 07/10/2026: content-radar's assistant spent close to half its frame on an ENGINE / MODEL / EFFORT row, an
+"outdated bridge" block and the install command). The admin's shape: a chip in the composer row opens a popup.
+
+```tsx
+import { EnginePicker, BridgeNotice, useEnginePicker } from "@gemboss/ui/assistant"; // brings assistant-engine.css
+
+const picker = useEnginePicker();          // open + tab, shared with the notice
+<EnginePicker {...picker.props}
+  engines={[{ id: "claude", label: "Claude Code", note: "Your Claude subscription" }, { id: "server", label: "Server" }]}
+  engine={engine} onEngineChange={setEngine}
+  models={[{ id: "", label: "Default" }, { id: "opus", label: "Opus" }]} model={model} onModelChange={setModel}
+  efforts={[{ id: "", label: "Default" }, { id: "high", label: "High" }]} effort={effort} onEffortChange={setEffort}
+  bridge={{ state: "outdated", version: "8", latest: "10", autostart: true, detail: "Codex cannot see the radar tools." }}
+  setup={{ command: installCommand, pairingCode, note: "The panel reconnects in a few seconds." }}
+  statusActions={<button className="ui-btn" onClick={recheck}>Check again</button>} />
+
+// Only when a turn FAILED because of the bridge, one line in the stream:
+<BridgeNotice onOpenSetup={() => picker.openTab("setup")}>The bridge on your machine is not responding.</BridgeNotice>
+```
+
+- **Chip**: engine name, the model when it is not the default (`id: ""`), a dot for `bridge.state`: green `running`,
+  amber `outdated`, red `offline` / `unpaired`, hollow `checking`. Its accessible name says the state in words.
+- **Popup**: a non-modal dialog in the top layer (placed like the kit's menus, `placeFloating`), so the assistant's frame
+  cannot cut it. Tabs: Engine always; Setup when `setup` is given; Status when `bridge` is given. ←/→/Home/End move
+  between tabs; ↑/↓ move between engines (one Tab stop). Escape with focus in the panel, or a model / effort pick from
+  the buttons, closes it and gives focus back to the chip; an outside click closes. An engine pick and a pick from a
+  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.
+- **Not in the chat**: no standing warning, no command in the conversation. The amber dot on the chip and on the Setup
+  tab is the warning. `BridgeNotice` is for a turn that actually failed, once.
+- 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).
+
+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).
+
 ## The chat body
 
 What an answer looks like, on any surface that puts a chat somewhere: `chat.css` (inside `gemboss-ui.css`;
@@ -242,9 +365,10 @@ import "@gemboss/ui/editor.css";   // only on the screens that show an editor
 
 Not here, on purpose: the body modes that hide the admin's own topbar and rail while an editor is open
 (`gemboss-editor-fullscreen`, `-just-exited`, `-layer-open`) and admin-only extensions such as the product studio's
-resizer. The behaviour (resizing, tabs, menus, the inspector's writes) belongs to the surface for now: the React
-components come in steps 2 to 4 (`EditorFrame` + `EditorTopbar`; `PanelTabs`, `PanelHeader`, `InspectorGroup`, `Field`
-and the controls; `LayerList`, `EditorDrawer`). Step 5 moves GemFactory's Builder onto them.
+resizer. The frame and its top bar are React components since 0.14.0 ("Editor frame" below), with their behaviour for
+plain HTML in `editor-plain.js`; the panel and its controls are components since 0.17.0 ("Settings panel" below, step 3); the
+layers, the element outline and the drawer since 0.22.0 ("Layers and drawer" below, step 4). Step 5 moves GemFactory's
+Builder onto them.
 
 Changes since the verbatim move, in 0.10.1 (05/10/2026, step 1b, the only ones that change what the admin shows; CHANGELOG):
 
@@ -257,6 +381,185 @@ Changes since the verbatim move, in 0.10.1 (05/10/2026, step 1b, the only ones t
 - `gemboss-flyout-in` is defined (fade + 4px drop, as the page picker), so `.gemboss-editor-menu` animates; `none`
   under `prefers-reduced-motion`.
 
+## Editor frame (0.14.0): `EditorFrame`, `EditorTopbar`
+
+The frame every editor is drawn in: the admin's theme, page and section editors render these components since 0.14.0
+(measured on a production build before and after: the same DOM and the same computed style, see CHANGELOG), and
+GemFactory's Builder is next. FRAME ONLY: the chat, the Configure dock, the canvas, the page picker, the menus and Publish
+belong to the editor and arrive as slots; the package holds no data logic and no state.
+
+```tsx
+import "@gemboss/ui/editor.css";
+import { DeviceToggle, EditorBack, EditorChatToggle, EditorFrame, EditorPaneTabs, EditorSaveState, EditorTopbar } from "@gemboss/ui/editor";
+
+<EditorFrame
+  top={<EditorTopbar variant="theme" back={<EditorBack as={Link} href="/" />} title="Builder"
+         chatToggle={<EditorChatToggle collapsed={collapsed} onToggle={toggle} />}
+         left={<EditorSaveState state={saveState} />}
+         center={<DeviceToggle device={device} onChange={setDevice} />}
+         right={<>{tools}{moreMenu}{publish}</>}
+         status={message ? { state: "error", message } : null} />}
+  split={{ width, min: 300, max, collapsed, onPointerDown, onKeyDown }}
+  left={<div className="gemboss-ec">…</div>}
+  preview={<Canvas />}
+  right={presetsOpen ? <Presets /> : null}
+  mobilePane={pane}
+>
+  <EditorPaneTabs value={pane} onChange={setPane} />
+  {drawersAndPopups}
+</EditorFrame>
+```
+
+| Component | Draws | Notes |
+|---|---|---|
+| `EditorFrame` | `div.gemboss-editor` › `top` · `.gemboss-editor-body` (`left` · seam · `.gemboss-editor-preview-pane`) · `children` | `split` writes `--gemboss-chat-w` (0 while `collapsed`, plus `.is-chat-collapsed`) and draws the seam (`role=separator`, `aria-valuenow/min/max`, `tabIndex 0`); the drag and the keys are the caller's (`onPointerDown`, `onKeyDown`). `right` is the right column: `.gemboss-editor-dock`, docked over the preview's right edge, 320px (max 90%), first in the pane. `mobilePane` is `data-mobile-pane` on the body. `embedded` fills a container instead of the viewport. Refs and extra classes for body and pane. |
+| `EditorPaneTabs` | `.gemboss-editor-mobile-tabs` › two `[role=tab]` | The phone's Chat / Preview switch (shown at 760px and below). Put it first in the frame's `children`. `labels` renames them. |
+| `EditorTopbar` | `header.gemboss-editor-topbar` › `-tb-left` (`back`, `chatToggle`, `title`, `left`) · `-tb-center` · `-tb-right`; then the status line | `variant`: `theme` (page picker + split Publish), `page` (`.gemboss-pageedit-top`: a title, a type chip, a status), `guest` (the try door). `status` draws `.gemboss-editor-statusbar.<state>` under the bar while its message is not empty. |
+| `EditorBack` | `.gemboss-editor-back` ← | A `<button type="button">`, or `as={Link}` / `as="a"` with `href`. Named "Back" for a screen reader (`label`). |
+| `EditorChatToggle` | `.gemboss-editor-chat-toggle` | Shows / hides the left column; filled while open, pressed when collapsed. |
+| `EditorSaveState` | `.gemboss-editor-savestate` (`.is-saving` with the spinner, `.is-saved`) | `idle` draws nothing, or `idleText` dimmed (the section editor's "Autosaves"). Texts and titles are props. |
+| `DeviceToggle`, `MonitorGlyph`, `PhoneGlyph` | `.gemboss-pv-devices` › `.gemboss-pv-device` | Desktop / tablet / mobile. Moved from the admin unchanged. |
+
+One module per piece behind one entry, so a bundler gives each editor only what it draws (measured: one module for all
+of it cost the page and section editors about 1 KB of code they never ran). Not in `@gemboss/ui` itself: like
+`editor.css`, only a screen with an editor pays for it.
+
+The geometry comes from `editor.css`. What the admin got from its own sheet (the left column sized by `--gemboss-chat-w`,
+stacked above the preview at 1000px and below, the preview taking the rest) is in `editor.css` as ZERO-specificity
+`:where(…)` rules since 0.14.0: anything more specific wins (the admin's own rules do, so its look did not move), and a
+page that has only the package still lays out.
+
+### Plain HTML: `editor-plain.js`
+
+Write the markup the components render (copy it from `catalog/editor.html`, where it is rendered from the components and
+runs), load the behaviour AFTER `kit-plain.js`, and call `gembossUI.initEditorFrame()`:
+
+```html
+<link rel="stylesheet" href="…/@gemboss/ui/gemboss-ui.css"><link rel="stylesheet" href="…/@gemboss/ui/src/editor.css">
+…
+<script src="…/@gemboss/ui/src/kit-plain.js"></script>
+<script src="…/@gemboss/ui/src/editor-plain.js"></script>
+<script>
+  gembossUI.initEditorFrame();                       // every .gemboss-editor, or initEditorFrame(root)
+  addEventListener("gemboss:editor-device", (e) => setCanvas(e.detail.device));
+</script>
+```
+
+| Wires | Markup | Event on the editor (bubbles) |
+|---|---|---|
+| The seam: pointer drag (main button of the primary pointer: mouse, touch, pen), ←/→ 16px (Shift 64), Home / End; clamped to the BOX, `min(aria-valuemax, body width − 360 − 5)`, never below `aria-valuemin`; the CHOSEN width is kept apart, so a box that narrows clamps it and widening gives it back, and reopening the column clamps to the box as it is then; `ui-resizing` on `<body>` while dragging; remembered when the body has `data-gb-storage="<key>"` | `.gemboss-editor-resizer` (the frame's) | `gemboss:editor-split` `{ width }` |
+| Hide / show the left column | `.gemboss-editor-chat-toggle` | `gemboss:editor-chat` `{ collapsed }` |
+| Device | `.gemboss-pv-devices .gemboss-pv-device` (`data-device`, or the `title`) | `gemboss:editor-device` `{ device }` |
+| Phone pane | `.gemboss-editor-mobile-tab` (`data-pane`, or Chat first / Preview second) | `gemboss:editor-pane` `{ pane }` |
+| ⋯ / Publish ▾ menus | a trigger with `aria-haspopup="menu"`, then a `.gemboss-editor-menu[hidden]` right after it: opens 6px under the trigger, right edges aligned, at least 8px inside the window; one at a time; a press outside, an item, the window losing focus (a press in the canvas iframe) and a resize close or re-place it; Escape closes the menu only (capture phase, like `initMenus`; a popup behind it stays open; not while an IME composes) | `gemboss:editor-menu` `{ open, menu }` |
+
+Without `kit-plain.js` it logs what is missing and defines nothing (`kit-plain.js` owns `gembossUI`). Its own file for
+the same reason as `editor.css`: a page with no editor does not load it.
+
+
+## Settings panel (0.17.0): `PanelTabs`, `PanelHeader`, `InspectorGroup`, `Field` and the controls
+
+Step 3 of the editor kit. The pieces every editor's settings panel is made of: the admin's Configure column, its element
+inspector and its schema form render these since 0.17.0 (measured on a production build before and after: the same DOM
+and the same computed style, see CHANGELOG). Same entry as the frame (`@gemboss/ui/editor`), look from `editor.css`.
+Controls take a value and give one back; nothing in the package knows what is edited, what schema a value came from or
+where it is saved.
+
+```tsx
+import "@gemboss/ui/editor.css";
+import { ColorControl, EdgeBox, Field, ImageControl, InspectorGroup, PanelAction, PanelHeader, PanelTabs, RangeControl, Seg } from "@gemboss/ui/editor";
+
+<PanelHeader title="Hero" subtitle="hero-banner" actions={<PanelAction label="Duplicate section" onClick={dup}>⧉</PanelAction>} />
+<PanelTabs variant="inspector" value={tab} onChange={setTab} tabs={[{ id: "content", label: "Content" }, { id: "design", label: "Design" }]} />
+<InspectorGroup title="Layout" note="all screens">
+  <Field label="Width"><Seg label="Width" value={width} onChange={setWidth} options={[{ value: "full", label: "Full" }, { value: "contained", label: "Contained" }]} /></Field>
+  <Field label="Background" htmlFor="bg"><ColorControl id="bg" label="Background" value={bg} onChange={setBg} /></Field>
+  <Field label="Opacity" htmlFor="op" labelValue={`${op}%`}><RangeControl id="op" min={0} max={100} value={op} onChange={setOp} /></Field>
+  <Field label="Padding"><EdgeBox label="Padding" values={pad} onChange={(side, raw) => setPad({ ...pad, [side]: raw })} onCommit={save} /></Field>
+  <Field label="Image" htmlFor="img"><ImageControl id="img" value={url} onChange={setUrl} actions={<ChipButton onClick={openLibrary}>Library</ChipButton>} /></Field>
+</InspectorGroup>
+```
+
+| Component | Draws | Behaviour |
+|---|---|---|
+| `PanelTabs` | `variant="column"`: `.gemboss-ec-tabs` › `.gemboss-ec-tab` (Configure · Chat, `icon` before the label). `variant="inspector"`: `.gemboss-ei-tabs` › `.gemboss-ei-tab(.on)` | `role=tablist` / `tab`, `aria-selected`, `data-value` (the tab's id, for plain HTML), `aria-controls` from a tab's `controls`. `roving` (default on): only the selected tab is a Tab stop, ←/→ move the selection and the focus, wrapping. The admin's Configure · Chat row passes `roving={false}` (both tabs Tab stops, no arrows: how it always behaved). |
+| `PanelHeader`, `PanelAction` | `header.gemboss-ei-head` › `.gemboss-ei-title` (+ `small` subtitle) · `.gemboss-ei-act` buttons · `.gemboss-ei-x` ✕ | ✕ only with `onClose` (a docked panel has none); `onDragStart` adds `.gemboss-ei-drag` and takes the mouse-down of a floating panel. |
+| `InspectorGroup` | `.gemboss-ei-grp` › `button.gemboss-ei-gh` (▾ / ▸, 11px / 700 uppercase, `note` as `.gemboss-ei-gh-note`) + the body | `aria-expanded`, `data-open`; closed, CSS hides everything after the header (the body stays mounted). Controlled (`open` + `onOpenChange`, which receives the NEXT state) or not (`defaultOpen`). `collapsible={false}`: the schema form's static group, `section.gemboss-ei-group` › `h4.gemboss-ei-grouphead` + `hint`. |
+| `Field` | `.gemboss-ei-fld` › `label` (13px / 500; `htmlFor`; `labelValue` as `.gemboss-ei-rangeval` at its right edge) · control · `hint` | No label when `label` is undefined / null. `className` (the admin's `togrow`), `style`. |
+| `Seg` | `.gemboss-ei-seg[role=group]` › `button[aria-pressed][data-value]` (`.on`) | A click hands back the option's value; `label` names the group; `style` on the group. |
+| `ColorControl` | `.gemboss-ei-color` › `input[type=color].gemboss-ei-swatch` + text box | The swatch commits on every change; the text box keeps a draft and commits on blur (every blur) or Enter. Anything but a 6-digit hex disables the swatch, with a title saying why (`swatchState`). |
+| `RangeControl` | `input[type=range].gemboss-ei-range` | Every change, as a number (drag, arrows, Home / End). Show the value with `Field`'s `labelValue`. |
+| `EdgeBox` | `.gemboss-ei-edgebox` › four `.gemboss-ei-edge` (box + T / R / B / L) | `onChange(side, raw)` per keystroke, `onCommit()` on blur; Enter blurs. Boxes named "<label> top / right / bottom / left". `narrow` (default) adds `gemboss-field--narrow`; `placeholders`, `ids` per side. What an empty edge means is the caller's. |
+| `ImageControl`, `ChipButton` | `.gemboss-ei-img` › 52px thumbnail (— when empty) · URL box · `.gemboss-ei-img-actions` (`actions`, then Clear while there is a value) | Commits on blur / Enter only when the box changed; Clear commits "". The box's text can be the caller's (`draft` + `onDraftChange`) to put a picked URL in it at once. The thumbnail's `url()` is quoted (`cssUrl`, 0.20.1), so a URL with ")" or a space still shows. |
+| `cssUrl` | | `url("…")` for any URL: quoted, `"` and `\` escaped, a control character as a CSS hex escape. Plain TypeScript (also `@gemboss/ui/editor/css-url`), so a server component can call it; `gembossUI.cssUrl` in editor-plain.js writes the same. Use it for your own image cells (the admin's library grid does). |
+| `swatchState` | | The one rule for what `<input type="color">` can show. Also `@gemboss/ui/editor/swatch` (plain TypeScript, for node). |
+
+Two modules behind the entry (`panel`, `controls`), both `"use client"`. Kept in the admin, on purpose: the schema
+(`FieldSpec`), value shapes and clamping (FieldRenderer), the theme job's media library and image generation, the
+per-breakpoint spacing model. Since 0.20.0 (#3846) the schema's On / Off toggles and the inspector's Visibility (Show /
+Hide) rows are `Seg` too, so they say `aria-pressed` like every other segmented row.
+
+### Plain HTML: `initEditorPanel()`
+
+The same markup (copy it from `catalog/editor.html`), then `gembossUI.initEditorPanel()` (editor-plain.js, after
+`kit-plain.js`; the whole document, or `initEditorPanel(element)`). By delegation, each with an event on the element
+named (it bubbles):
+
+| Wires | Markup | Event |
+|---|---|---|
+| Tabs: select (`aria-selected`, `.on`, the tab's `aria-controls` panel shown and its siblings' hidden); ←/→ when the row is roving (its tabs carry `tabindex`) | `.gemboss-ec-tabs` / `.gemboss-ei-tabs` › `[role=tab]` (`data-value`, or the text) | `gemboss:editor-tab` `{ tab, index }` on the tab |
+| Fold / unfold a group | `.gemboss-ei-gh` | `gemboss:editor-group` `{ open }` on the header |
+| Press a Seg option | `.gemboss-ei-seg button` (`data-value`, or the text) | `gemboss:editor-seg` `{ value }` on the group |
+| Colour: the swatch writes the box; the box commits on blur / Enter and the swatch follows (off for a non-hex) | `.gemboss-ei-color` | `gemboss:editor-color` `{ value }` |
+| Range: the label's `.gemboss-ei-rangeval` follows, with its `data-suffix` | `input.gemboss-ei-range` with an `id` and a `label[for]` | `gemboss:editor-range` `{ value }` on the input |
+| Edges: Enter blurs; a box that loses focus sends all four | `.gemboss-ei-edgebox` | `gemboss:editor-edges` `{ t, r, b, l }` |
+| Image: commits on blur / Enter when changed; the thumbnail follows; a chip with `data-gb-image-clear` empties it | `.gemboss-ei-img` | `gemboss:editor-image` `{ value }` |
+
+## Layers and drawer (0.22.0): `LayerList`, `SortableLayerList`, `LayerTree`, `EditorDrawer`
+
+The page editor's Layers, Page settings and Edit content drawers and the element inspector's Elements outline, as
+components (`@gemboss/ui/editor`). The admin draws those four with them since 0.22.0, measured before and after on a
+production build: the same computed style and box, the markup differing only in `data-id` on each row, `type="button"`
+on the buttons the components draw, and `aria-current` on the selected layer (CHANGELOG has the numbers).
+
+```tsx
+import { EditorDrawer, LayerList, LayerTree, SortableLayerList } from "@gemboss/ui/editor";
+
+{layersOpen ? (
+  <EditorDrawer side="left" label="Page layers" title="Layers" onClose={() => setLayersOpen(false)}>
+    <SortableLayerList items={sections.map((s) => ({ id: s.id, title: s.type, subtitle: s.heading, hidden: s.hidden }))}
+      selectedId={picked} onSelect={(it) => setPicked(it.id)}
+      onMove={(it, to) => moveSection(it.id, to)} onToggleHidden={(it, hidden) => setHidden(it.id, hidden)}
+      actions={(it) => <button aria-label="Delete" onClick={() => remove(it.id)}>✕</button>} empty="No sections yet" />
+  </EditorDrawer>
+) : null}
+```
+
+| Component | Markup | Behaviour |
+|---|---|---|
+| `LayerList` | `.gemboss-layers-list` › `.gemboss-layer[data-id]` (`.is-sel`) › `button.gemboss-layer-main` (`.gemboss-layer-type` · `.gemboss-layer-head`) · `.gemboss-layer-acts` | A click selects (`onSelect`; the selected button says `aria-current`). Rows are 34px, 50px with a subtitle. `empty` shows in `.gemboss-picker-empty`. `onToggleHidden`: an eye first among the actions (named "Hide <name>", `aria-pressed` = hidden, the row faded). `depth` per item indents it (`indent` px per level, default 14). Stateless. |
+| `SortableLayerList` | the same, each row `draggable` with a `.gemboss-layer-grip` | `onMove(item, to)` (`to` = the index after the move): drag a row (faded while dragged, a 2px line where it lands), or Alt+↑ / Alt+↓ on its button (the focus stays on the moved row, also when `onMove` answers later). The drag is kept by id. Its own module (`"use client"`): a list that does not reorder does not carry it. |
+| `LayerTree` | `ul.gemboss-ei-tree[role=tree]` › `li.gemboss-ei-tnode[role=treeitem][data-id]` (`.on`, level / position / selection) › `button.gemboss-ei-tname` (+ `small`) · `.gemboss-ei-tacts` · `below` | A click on the name calls `onSelect`; toggling it off is the caller's. Actions show on hover, on the selected row and on focus. 27px rows, 14px per level. |
+| `EditorDrawer` | `.gemboss-picker-backdrop` + `aside.gemboss-settings` (`side="right"`, min(380px, 100%)) or `aside.gemboss-layers` (`side="left"`, 300px) › `before` · `.gemboss-picker-head` (title, ✕) · children · `.gemboss-settings-foot` (`footer`) | ✕ and the backdrop call `onClose`. Mounted while open. The body is the caller's: `.gemboss-settings-body` › `label.gemboss-settings-field` (`span`, control, `small`). |
+
+Drag to reorder is pointer only (HTML drag and drop does not start from touch); a list that must reorder on a phone
+keeps ↑ / ↓ buttons in its `actions`, as the admin's does. Kept as the admin had them: the drawer has no Escape and
+does not move the focus into itself or back; the admin's Layers do not drag and have no eye (they move with ↑ / ↓).
+
+### Plain HTML: `initEditorLayers()`
+
+The same markup (copy it from `catalog/editor.html`), then `gembossUI.initEditorLayers()` (`editor-layers-plain.js`, its own file:
+load it only where layers or drawers are, after `kit-plain.js`; the whole document, or `initEditorLayers(element)`). A drawer stays in the document while closed:
+`hidden` on the aside and on the backdrop before it, an `id` on the aside.
+
+| Wires | Markup | Event |
+|---|---|---|
+| Select a layer (`.is-sel`, `aria-current`) | `.gemboss-layer-main` | `gemboss:editor-layer` `{ id, index }` on the row |
+| Hide / show (`aria-pressed`, `.is-hidden`, the eye's slash) | `.gemboss-layer-eye` | `gemboss:editor-layer-hidden` `{ id, hidden }` |
+| Reorder: drag a row, or Alt+↑ / Alt+↓ on its button; the row moves in the document and keeps the focus | `.gemboss-layer[draggable=true]` | `gemboss:editor-layer-move` `{ id, from, to }` |
+| Select an outline node; a second click clears it | `.gemboss-ei-tree .gemboss-ei-tname` | `gemboss:editor-tree` `{ id }` (`null` when cleared) |
+| Open a drawer (closing any other open one) / close it (✕ in its head, `data-gb-drawer-close`, the backdrop) | `[data-gb-drawer="<aside id>"]` | `gemboss:editor-drawer` `{ id, open }` on the aside |
+
 ## Plain-HTML behaviour: `kit-plain.js` (0.3.0)
 
 Surfaces without React (GemFactory, gemcare, gempress, partner-radar) render the kit's markup on the server and need
@@ -461,6 +764,7 @@ both looks like the admin and passes Gems/CLAUDE.md §9.1.
 |---|---|---|
 | `ui-btn` (every variant), `ui-btn--icon` | 28px, padding 0 12, 12px/550 (`--ui-btn-h`) | 44px |
 | `ui-seg` group, `.is-text` label | 28px, 12px/550 | 44px |
+| `ui-seg--fill` (0.20.0): the row's width, segments equal; `ui-seg-n` a count inside a segment. EVERY "pick one" switch in the admin is a `ui-seg`, drawn by `Segmented` (`@gemboss/ui/segmented`); the editor kit's `Seg` and `DeviceToggle` too | same | same |
 | `ui-tabs` | 28px, padding 0 12, 12px/550 selected or not, 8px apart | 44px |
 | `ui-page-head h1` | 20px / 24px / 700 (Polaris headingLg) | same |
 | `ui-card`, `ui-table-wrap` | Polaris' shadow-100 under it (`--ui-card-shadow`), one 1px `--ui-border` edge, radius 12, padding 16 | same |
@@ -712,6 +1016,23 @@ import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeSc
   (after the name, e.g. a level) and `id` (a `#me` anchor). `title` may be left out on a page whose own
   `<h1>` names the board; pass `label` then. Screen-reader text uses `.gb-sr-only`, styled in portal.css.
 
+## Reactions (0.21.0): one emoji set and one chip for the fleet
+
+Chris 06/10/2026: "reaction các thứ comment nên chuẩn hoá một kiểu, bên gemcare cũng có, nên đưa vào gemboss ui". GemCare's
+team chat built them first (`public/assets/inbox.js`); this is that, moved here so GemFeedback's requests and comments,
+and GemCare's chat, draw and accept the same thing.
+
+| Piece | What |
+|---|---|
+| `@gemboss/ui/reactions-data` (plain TS, also re-exported from the root) | `REACTION_GROUPS` (GemCare's 137 emoji in 4 groups, each with search words), `REACTION_EMOJI`, `isReactionEmoji` (the server's check: refuse anything else), `searchReactions`, `reactionLabel` (names, two then `+n`), `toggleReaction` (the optimistic guess drawn before the server answers), `QUICK_REACTIONS` (👍 ✅), type `Reaction` = `{ emoji, names, mine }` |
+| `Reactions` (React, client) | the chips (emoji + NAMES of who put it; yours outlined + filled, `aria-pressed`) and "Add reaction", which opens `ReactionPicker` in flow under the row. `canReact={false}`: chips only; no chips and no right to react: nothing |
+| `ReactionPicker` | search, "Frequently used" (this browser's last 9, `localStorage`, else the quick pair), the groups; arrows move in the grid, Enter in the search picks the first, Escape closes and returns focus |
+| `reactions.css` (its own entry, NOT inside `gemboss-ui.css`: link it where reactions are drawn, as `collections.css`) | `ui-reactions`, `ui-reactions__row`, `ui-reaction` (+ `is-mine`), `__emoji`, `__names`, `ui-reaction-add`, `ui-reaction-picker` (`__search`, `__body`, `__head`, `__grid`, `__btn`, `__empty`) |
+
+Every target is 44px (a control, CLAUDE.md §9.1); the pill you see is 26px, transparent padding carries the rest, so a
+message with reactions does not grow by a full line. A plain-HTML surface writes the same classes (markup at the top of
+`reactions.css`, and the catalog's "Reactions" section).
+
 ## Report pages (0.4.0)
 
 Plain CSS in `kit-plain.css` for a numbers page written by hand (first user: gemnews `/admin`, 03/10/2026; that page moved to GemCommunity the same day, so gemnews no longer takes the package). The
@@ -759,14 +1080,14 @@ silently: a `slice` prints "+N more" or "See all N". A table renders at most 100
 |---|---|---|---|---|
 | 1 | Data table | `DataTable` | `ui-table-wrap > table.ui-table(.ui-table--sticky-first, --compact)`; `tfoot.ui-table__totals`, `.ui-table__footer` | DataTable |
 | 2 | Index table | `IndexTable` (client) | `div.ui-index > [div.ui-index__sortbar] + [div.ui-bulkbar] + ui-table-wrap > table.ui-table.ui-table--index`; `tr[data-href]`, `td.ui-table__check`, `td.ui-table__primary > a.ui-table__title + span.ui-sub`, `td.ui-table__actions` | IndexTable |
-| 3 | Resource list | `ResourceList` + `ResourceItem` | `ul.ui-list > li.ui-list__item > .ui-list__media + .ui-list__body(a.ui-list__title, p.ui-list__sub, p.ui-list__meta, .ui-list__badges) + .ui-list__aside + .ui-list__actions` | ResourceList |
-| 4 | Compact list | `CompactList` (`variant="activity"`) | `ul.ui-list.ui-list--compact > li.ui-list__item > a/button/div.ui-list__row`; timeline: `ui-list--activity`, `.ui-list__dot(--tone)`, `.ui-list__detail`, `time` | ActionList |
+| 3 | Resource list | `ResourceList` + `ResourceItem`; with selection `SelectableResourceList` (client, 0.16.0) | `ul.ui-list > li.ui-list__item > .ui-list__media + .ui-list__body(a.ui-list__title, p.ui-list__sub, p.ui-list__meta, .ui-list__badges) + .ui-list__aside + .ui-list__actions`; selectable: `div.ui-resource > div.ui-bulkbar + ul.ui-list`, `label.ui-list__check > input[data-gb-select]` first in `__media` | ResourceList |
+| 4 | Compact list | `CompactList` (`variant="activity"`, `wrap`) | `ul.ui-list.ui-list--compact > li.ui-list__item > a/button/div.ui-list__row`; timeline: `ui-list--activity`, `.ui-list__dot(--tone)`, `.ui-list__detail`, `.ui-list__content` (0.15.0), `time`; `ui-list--wrap` (0.15.0) | ActionList |
 | 5 | Card grid | `CardGrid min={200 \| 240 \| 320}` + `MediaCard` | `div.ui-cardgrid[data-min] > article.ui-card.ui-card--media > a.ui-card__media + .ui-card__menu + .ui-card__body > a.ui-card__link` | InlineGrid + Card |
-| 6 | Board | `Board` | `div.ui-board > section.ui-board__col > header.ui-board__head + ol.ui-board__list + details.ui-board__more` | none |
+| 6 | Board | `Board` (`onMove`, `hasMore` / `moreHref` / `onLoadMore`: 0.18.0) | `div.ui-board > section.ui-board__col[data-col] > header.ui-board__head + ol.ui-board__list > li[data-id]` + `details.ui-board__more` (client paging) or `div.ui-more.ui-board__next > a[data-gb-more]` (server paging) | none |
 | | States | `CollectionState kind="empty \| no-match \| error"`, `CollectionSkeleton pattern=…`, `state="busy"` | `ui-empty(--no-match)`, `ui-coll-error`, `ui-skeleton--table/--list/--compact/--grid/--board`, `aria-busy="true"` | EmptyState, EmptySearchResult |
 
-`./collections` is a plain module (a server component renders it, render functions and all); `IndexTable` is a client
-module. Its props are plain data (rows of rendered cells, `sortHref` strings) so a server page can still render it;
+`./collections` is a plain module (a server component renders it, render functions and all); `IndexTable` and
+`SelectableResourceList` (0.16.0) are client modules. Their props are plain data (rows of rendered cells, `sortHref` strings) so a server page can still render them;
 the callbacks (`onSort`, `onSelectionChange`, a bulk action's `onAction`) need a client parent. Neither module reaches
 the admin's first load (`kit-plain-bundles.test.ts` checks the shell import carries none of their code).
 
@@ -777,9 +1098,56 @@ the admin's first load (`kit-plain-bundles.test.ts` checks the shell import carr
   two or more in-place editors is not linked (only its title is). HTML: `tr[data-href]` + kit-plain.js; React:
   `IndexTable` rows with `href`; a resource list's title link covers its row (no script).
 - **One visible button per row at most**, the rest in the ⋯ menu (`ui-menu`). **Never shown only on hover.**
+- **An open ⋯ menu is never cut by its frame (0.18.0).** It floats in the browser's top layer (`popover="manual"`,
+  `position: fixed` against its button): below the button, above it when the room below is short and the room above is
+  larger, 8px from the viewport's edges, scrolling inside when taller than the room. It closes when a scroll moves its
+  button (the page, or a frame around the menu) or the window resizes; a scroll inside the list or elsewhere (a log
+  following its output) does not count. Tab order, Escape (focus back on ⋯) and "a click in the
+  menu is not a click on the row" are unchanged: the list is still the details' child. React `Menu` does it itself;
+  plain HTML gets it from kit-plain.js (`initMenuLayer()`, runs by itself). No popover API (Safari < 17) or no script:
+  the absolute list, as before. GemFactory Members (#197) is the case: at 820 / 900 / 1280 the last rows' menus were
+  half hidden inside the table's scrolling frame.
+- **A resource list in a frame of 400 or less (0.15.0)** keeps the body beside the media, with all the width right of
+  it; the aside and the actions share ONE line under the body (aside left, actions right, from the body's edge); the
+  media spans both lines; a row without media gives the body the whole width; a body that is only its title keeps
+  them on its line. The row's direct children are the four slots (a checkbox goes in `__media`). So a long
+  subtitle and a body of many meta lines both get shorter than in 0.13.0 (`collections.test.ts` checks the geometry
+  at 320 / 390 / 768 for both, with the 0.13.0 rule and the `flex: 1 1 0` patch as negative controls).
+- **A compact list wraps when its labels carry data (0.15.0).** `CompactList wrap` (`ui-list--wrap`): the label and an
+  activity's detail wrap instead of ending in "…", because the cut text's `title` is mouse-only. A side rail of short
+  labels keeps one line. `CompactItem.body` (activity only) is the event's own text under them (`.ui-list__content`,
+  body size, never cut; paragraphs as `<p>`); `labelText` puts the full label in `title`.
 - **Below 768 of its container an index table becomes a list** (title line; the other cells on one caption line,
   `data-label` prefixes, `data-condensed="hide"` drops; checkbox and actions kept; rows ≥ 44); sort moves to the chips
   of `ui-index__sortbar`. **A data table never folds:** it scrolls in its frame with `--sticky-first`.
+- **A data table reads from the top of its rows (0.16.0)**, as Polaris DataTable (`verticalAlign` "top"): one-line
+  cells sit on the first line of a three-line row, and a 24px cell link is pulled up by half its extra height so its
+  text lines up (`calc((1lh - 24px) / 2)`). The index table keeps `middle`. The row header (`th.ui-table__rowhead`)
+  wraps like any cell (Polaris `firstColumn`) with Polaris's first-column width as a floor (9.0625rem; the frame
+  scrolls rather than squeezing it to a word a line); `truncate` or `ui-clamp-2` when it must stay short. A column's
+  `minWidth` (DataTable) is the floor of a column whose cells wrap, and replaces the row header's (`0` for a row
+  header that is always short: a date, an id). A link alone on its
+  line is 24px in the row header and in a list inside a cell (`li > a`), as `td > a` already was.
+- **A media card is 16:10, 4:3 or 1:1 (0.18.0)** (`MediaCard ratio`, `data-ratio="4/3" | "1/1"`): 1:1 for a square
+  picture (a moodboard, a product shot, a social post). No other ratio: any other value draws 16:10.
+- **A board column of more than a few dozen cards pages on the SERVER (0.18.0).** The 0.13.0 board puts every card in
+  the HTML behind nested `<details>` (content-radar ideas reaches 2,000). With `hasMore` the column shows the cards the
+  server sent (`boardShown(page)`: 12, then 24 more a page, Chris 05/10/2026) and ends in ONE "Show 24 more":
+  `moreHref` is this page with the column one page further (`?col=ideas&page=2`, cumulative, so no script, Back and a
+  sent link all work; `moreHref` alone means there is more, `hasMore: false` is the last page). On a plain-HTML page
+  (`fetchMore`, i.e. `a[data-gb-more]`) kit-plain.js fetches it, appends the cards whose `data-id` are not on the board
+  yet, takes the next link and the count, puts the URL in the address bar, says "24 more cards in <column>" and focuses
+  the first new card ("Couldn't load." + Try again on failure); never on a board React owns. React: `linkAs` (a Next `Link` with `moreLinkProps={{ scroll: false }}`) or
+  `onLoadMore(columnId)` + `loading`. Cards need ids: `items: [{ id, card, name? }]` instead of `cards`.
+- **Moving cards between columns is optional (0.18.0)** (`Board onMove(cardId, toColumn, toIndex)`; plain HTML
+  `.ui-board[data-gb-move]` + `li[data-id][tabindex="0"][draggable="true"]`, event `gb:move` { id, from, to, index },
+  cancelable: not cancelled, kit-plain.js moves the `li` and the counts). Drag with a mouse, or Tab to a card, Space,
+  arrows (↑ ↓ in the column, ← → to the next one), Space or Enter to drop, Escape to put it back, each step said in the
+  board's live region. While held, the card has `data-gb-lifted="key"` or `"drag"` (a surface may change its layout for a
+  keyboard hold, never inside dragstart: Chrome cancels the drag), the target column `data-gb-over`, the landing line
+  `data-gb-drop="before|after"` on a card. Nothing moves in the DOM until the drop, and a drop where it was reports nothing. Without
+  `onMove` the board stays read-only (no tab stops, no drag). A phone cannot drag: keep a way that is not dragging (a
+  select, a ⋯ "Move to").
 - **At 1280 a table fits its page frame.** Fix in this order: a `canvas` page if the content really is wide; move
   low-priority columns to the detail page; fold attributes into the `ui-sub` line.
 - **No zebra, no uppercase header, no card per row, no grid that changes its column count per viewport** (auto-fill
@@ -787,7 +1155,22 @@ the admin's first load (`kit-plain-bundles.test.ts` checks the shell import carr
 - **A checkbox column only with bulk actions.** The bulk bar covers the header (the table does not move), carries its
   own select-all, Shift+click takes a range, Escape clears. HTML: `input[data-gb-select]` / `[data-gb-select-all]`,
   `gembossUI.selection(root)`, event `gb:selection`.
-- **Sort lives in the URL** (`th[aria-sort] > a.ui-table__sort`); `button.ui-table__sort` sorts a small table in place
+- **A resource list selects the same way (0.16.0):** `SelectableResourceList` (`items`, `bulkActions`, optional
+  controlled `selected` + `onSelectionChange`, `selectedLabel`, `linkAs`). The checkbox is first in the media slot
+  (`label.ui-list__check`: 24, 44 under a finger, pulled into the row's padding so a 64px row stays 64). One
+  difference from the table: the bar is the list's header from the start ("0 selected", actions disabled), because a
+  list has no header to cover and a bar that appears on the first check pushes the rows under the finger (talent-radar
+  /pool measured 74px at 1280, 194px at 390). The whole row still opens the item. HTML: the same `data-gb-select`
+  hooks in a `.ui-resource` (kit-plain.js enables the action buttons from 1 instead of showing the bar; an action with
+  its own rule sets its button on `gb:selection`, which fires after). collections-gate reports a list with selection
+  boxes and no bar (`select-without-bulk`). An open ⋯ menu or dialog takes Escape first; a closed one kept in a row
+  does not.
+- **A sort control is 44 × 44 under a finger (0.18.0)**: the header button grows to 44 tall under `pointer: coarse`
+  and to 44 wide under `pointer: coarse` or at 768 and below (a short label like "ID" was 44 × 30 on an iPad); the
+  chips below 768 have the same floor. Under a mouse the header keeps its Polaris size.
+- **Sort lives in the URL** (`th[aria-sort] > a.ui-table__sort`); in React the sort links (header and the chips below
+  768) are `linkAs`, the same element as the row titles (0.16.0), so a Next `Link` sorts without reloading the page;
+  `sortLinkProps={{ scroll: false }}` keeps the scroll position (a sort is the same page in another order); `button.ui-table__sort` sorts a small table in place
   (`table[data-gb-sort="client"]`, by `data-sort-value`) or fires `gb:sort` for the page (`data-gb-sort="event"`); a React table owns its buttons and kit-plain.js leaves them alone.
 - **States** (Gems/CLAUDE.md 9.2): empty (one main action) · no match (filters and header stay, "Clear filters") ·
   loading (a skeleton in the pattern's shape: a table keeps its real header, rows keep their height) · reloading
@@ -872,11 +1255,16 @@ something the base cannot express, add a token or a prop here, and every surface
 
 | Path | What |
 |---|---|
-| `gemboss-ui.css` | built at pack time: `apps/admin/scripts/export-ui-css.mjs` (tokens + kit + field + `packages/ui/src/shell.css`, with Polaris `--p-*` resolved to their fallbacks) + `packages/ui/src/app-shell.css` + `auth.css` + `assistant.css` + `kit-plain.css` + `chat.css` + `chat-composer.css` (`packages/ui/scripts/build-css.mjs`) |
-| `packages/ui/src/shell.css` | the SHARED SHELL (rail, topbar, main, mobile drawer, the assistant's thread rail, popover surface, account chip). The admin's `gemboss-shell.css` @imports it on line 2; the export refuses a shared-shell rule in the admin's sheet or an admin-only rule here (one owner). |
+| `parts/core.css`, `parts/components.css`, `parts/shell.css` | 0.23.0: the core, built by `packages/ui/scripts/build-css.mjs` from the same sections as `gemboss-ui.css` (see "Load only what you use"). |
+| `gemboss-ui.css` | built at stage time and shipped minified (0.19.0); since 0.23.0 the COMPATIBILITY BUNDLE, frozen: `apps/admin/scripts/export-ui-css.mjs` (tokens + kit + field + `packages/ui/src/shell.css`, with Polaris `--p-*` resolved to their fallbacks) + `packages/ui/src/app-shell.css` + `auth.css` + `assistant.css` + `kit-plain.css` + `chat.css` + `chat-composer.css` (`packages/ui/scripts/build-css.mjs`) |
+| `packages/ui/src/shell.css` | the SHARED SHELL (rail, topbar, main, mobile drawer, the assistant's thread rail, popover surface, account chip). Exported as `@gemboss/ui/shell-source.css` since 0.23.0 (`@gemboss/ui/shell.css` is the built part). The admin's `gemboss-shell.css` @imports it on line 2; the export refuses a shared-shell rule in the admin's sheet or an admin-only rule here (one owner). |
 | `packages/ui/src/kit-plain.css` | primitives for surfaces that render plain HTML, not React (0.2.1): menu, key/value list, icon button; 0.3.0 adds `ui-link` / `ui-prose`, the media card (`ui-card--media`, `__media`, `__body`, `__foot`) and the popup's `ui-modal__body` / `__foot`. Shipped inside `gemboss-ui.css`; the admin does not import it (its first-load CSS budget has ~0.1 KB headroom).; (0.4.0) report pages: delta, large KPI grid, bar list, column chart, legend, funnel, card grid, section head. |
 | `packages/ui/src/kit-plain.js` | 0.3.0: the behaviour those surfaces each wrote by hand: `gembossUI.openModal` (Escape, backdrop, Tab trap, stacking, ask-before-close, focus back), `toast` (text, error tone), `initMenus` (outside click, item, blur, Escape closes the menu before the popup); 0.5.0: `confirm`, `initShell`, `initPasswordFields` / `resetPasswordFields`. A classic script: inline it or `<script src>`; see "Plain-HTML behaviour" above. |
 | `packages/ui/src/collections.css` | 0.13.0: tables, lists, grids, boards and their states (see "Collections"). A separate entry, NOT inside `gemboss-ui.css`; the admin does not load it. |
+| `packages/ui/src/editor/` | 0.14.0, `@gemboss/ui/editor`: `EditorFrame`, `EditorPaneTabs`, `EditorTopbar`, `EditorBack`, `EditorChatToggle`, `EditorSaveState`, `DeviceToggle`. See "Editor frame". 0.17.0: `PanelTabs`, `PanelHeader`, `PanelAction`, `InspectorGroup`, `Field`, `Seg`, `ColorControl`, `RangeControl`, `EdgeBox`, `ImageControl`, `ChipButton`, `swatchState` (`./editor/swatch` too); 0.20.1 `cssUrl`. See "Settings panel". 0.22.0: `LayerList`, `SortableLayerList`, `LayerTree`, `EditorDrawer`. See "Layers and drawer". |
+| `packages/ui/src/editor-plain.js` | 0.14.0: `gembossUI.initEditorFrame()`, the frame's behaviour for plain HTML; 0.17.0: `gembossUI.initEditorPanel()`, the settings panel's. Load after `kit-plain.js`. |
+| `packages/ui/src/editor-layers-plain.js` | 0.22.0: `gembossUI.initEditorLayers()`, the layers', the outline's and the drawers' behaviour for plain HTML. Load after `kit-plain.js`. |
+| `catalog/editor.html` | 0.14.0: the frame rendered from the components and running (`packages/ui/scripts/build-catalog-editor.mjs`), linked from `catalog/index.html`. |
 | `packages/ui/src/editor.css` | 0.9.0: the editors (frame, top bar, preview, Configure dock, inspector and controls, Layers, settings drawer, page picker, menus). A separate entry, NOT inside `gemboss-ui.css`; the admin imports it from the editor components, never from a layout. See "Editor CSS" above. |
 | `packages/ui/src/chat.css`, `chat-composer.css`, `assistant.css`, `auth.css`, `app-shell.css` | the chat body, the composer, the assistant frame, the sign-in screen, the topbar slots + base text + the page width tiers (`ui-page`, 0.8.1). All inside `gemboss-ui.css`; the admin @imports `chat.css` and `chat-composer.css` itself. |
 | `packages/ui/src/icon.svg` | 0.5.0: the GemBoss app icon, for `<link rel="icon" type="image/svg+xml">`. Must stay byte-identical to `apps/admin/src/app/icon.svg` (`kit-look.test.ts` checks). |
@@ -888,12 +1276,36 @@ something the base cannot express, add a token or a prop here, and every surface
 change `packages/ui/src/shell.css` (since 29/09/2026: before that it lived in the admin's stylesheet and was extracted).
 The admin and the next published version both carry it.
 
+## Minified on publish, weighed per file (0.19.0)
+
+The published tarball carries every stylesheet (`gemboss-ui.css`, `src/*.css`) and the two plain scripts
+(`packages/ui/src/kit-plain.js`, `packages/ui/src/editor-plain.js`) MINIFIED; the comments stay here in the sources. `gemboss-ui.css` keeps its
+generated header (the gemboss commit; GemFactory's `/api/health` reads it). Next and Vite minify what they bundle anyway;
+the surfaces that serve the files as they come out of `node_modules` (GemFactory, taskdesk, gemcare, gempress) did not.
+Measured on this change: `gemboss-ui.css` 78.1 KB gzip as written, 21.9 KB minified; `kit-plain.js` 17.8 → 8.5 KB.
+
+`npm publish` cannot minify in place (`exports` points at `src/`, which the admin compiles from), so the release goes
+through a staged copy: `packages/ui/scripts/stage.mjs` copies exactly what npm would pack into `.pack/`, minifying with esbuild
+(`legalComments: none`, no target: rewrites that compute the same style only). `npm pack` / `npm publish` run straight
+in `packages/ui` are refused by `prepack`.
+
+The weight gate, `packages/ui/scripts/weight-gate.mjs`, reads the staged copy: gzip (level 6) of each minified file against its
+ceiling in `weight-budget.json` (measured + 512 bytes). Red when a file is over its ceiling, more than 1 KB under it
+(lower it: a ceiling above the truth constrains nothing), still carries comments or indentation (not minified; measured by esbuild, so a `/*` in a string does not count), or is shipped without
+a ceiling. CI runs `node packages/ui/scripts/weight-gate.mjs --ci`: build, stage into a temp dir, gate, then the
+negative controls (+5 KB of real rules in `ui.css` red; +20 KB of comment green; the unminified sources red; one
+unminified `kit-plain.js` red; a stylesheet with no ceiling red; a ceiling for a file not shipped red; a stale ceiling
+red; a `/*` inside a string is not a comment, green). Ceilings go down by themselves; raising one is not how a PR
+gets green (CLAUDE.md §9.4: shared weight only shrinks): it takes the reason in the PR and Chris's OK, and a new
+component goes in its own entry. `packages/ui/scripts/pack-lib.mjs` holds what the three scripts share (pack list, minifier, staging).
+
 ## Release
 
 ```bash
 cd packages/ui
-npm version patch        # or minor / major
-npm publish              # prepack builds gemboss-ui.css first
+npm version minor                    # or patch / major
+npm run stage                        # builds gemboss-ui.css + catalogs, minifies into .pack/, runs the weight gate
+npm publish .pack --auth-type=web    # publish the STAGED copy (npm pack .pack for a local tarball)
 ```
 
 Publish from a worktree at the MERGED commit on `main`, not from a branch, so the registry and