@gemboss/ui 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# @gemboss/ui changelog
+
+Versions up to 0.9.0 are described in the README, each in the section that introduced it.
+
+## 0.10.0 (05/10/2026)
+
+Navigation pending: a click on a menu item answers on the first frame, and a page is fetched while the pointer rests on
+its link (Chris, 05/10/2026, from content-radar's rail). README "Navigation pending".
+
+Added
+- `@gemboss/ui/next`, a new entry: `NavLink` (next/link that prefetches only on intent: pointer at rest 120 ms,
+  touchstart, focus; while its page loads it carries a `role="status"` mark that turns a rail item's icon into the
+  spinner), `PendingLink` (a link in the page with a small spinner, `mark="inline" | "corner"`), `PendingIcon`,
+  `NAV_DWELL_MS`. `next` >= 15.3 is an optional peer dependency; the main entry does not import it.
+- `RailItem` and `RailSubItem` take `pending` (sets `aria-busy="true"`).
+- `RouteHolding` (main entry, plain component): the one loading boundary a route group renders in its `loading.jsx`
+  (title bar + four lines in the content column, `role="status"`). Required wherever links are `NavLink`: without a
+  boundary, intent prefetch has nothing to fetch (content-radar 05/10/2026: new screen at 350-780 ms).
+- `RouteCover` (main entry): the same frame over the content area from the click until the navigation commits, shown
+  by `html[data-gb-navigating]`, which the `@gemboss/ui/next` links set while pending (no delay, 80 ms fade).
+- `app-shell.css`: the pending look. `.gnav-item` icon becomes a 20px spinner in the same box (the label does not
+  move), `.gnav-subitem` gets a 12px spinner in its indent before the label (out of the flow), `cursor: progress`, slower spin under reduced motion;
+  `a[data-gb-pending]` + `.gb-pending-mark` for page links; `.gnav-pending` status text.
+- `kit-plain.js`: `initNav()`, which runs by itself when the script loads. Followed rail links (and
+  `a[data-gb-pending]`) are marked; links are prefetched (speculation rules where supported, else `<link rel="prefetch">`) after a 120 ms rest of the
+  pointer or of keyboard focus, or on touchstart, once per URL; not at all once a client router took a rail click over. Skips modifier clicks, `target`, `download`, same-page hashes, other origins, clicks a handler
+  already took; clears on `pageshow`, Escape, `navigateerror`, after 15 s. Opt out: `data-gb-nav="off"`,
+  `data-gb-prefetch="off"`. No prefetch inside a Next app or with Save-Data.
+- Catalog section "Chờ điều hướng".
+
+Measured, and why the prefetch is a speculation rule (05/10/2026, `_local/fleet/nav-pending/prefetch-reuse.txt`): a
+`<link rel="prefetch">` of a page is reused by the click only when the page is cacheable (max-age > 0). Server-rendered
+fleet pages send max-age=0 / no-cache, so the click fetched the page again, and a prefetch still in flight made the
+click slower (1121 ms to the new page against 737 ms without one, through a 280 ms proxy). A speculation-rules prefetch
+was reused under every Cache-Control tried; `nav-pending.test.tsx` holds both (one server request vs two).
+
+Not changed
+- The admin: it keeps its own holding screen and hover prefetch (`NavPending.tsx`, `AppShell.tsx`); none of the new
+  CSS or code is in its first load. Moving it over is a later change (README).
+
+Number: 0.9.0 is the editor kit (gemboss #3770, merged 05/10/2026, not yet published), so this is 0.10.0 (new API =
+minor). Publish 0.9.0 first or together; check `npm view @gemboss/ui versions` and main before publishing either.

package/README.md

@@ -40,6 +40,55 @@ 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.
 
+## 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
+service, not edge to edge. The tiers are the admin's (`gemboss-shell.css`, `.gemboss-w-*` around a Polaris Page),
+same numbers; `page-width.test.tsx` fails if the admin and the package disagree.
+
+| Tier | Class | Max width | For | Admin |
+|---|---|---|---|---|
+| `default` | `ui-page` | `--ui-content-max` (900px) | lists, tables, card grids, dashboards, detail pages | bare Page, `.gemboss-w-gallery`, `.gemboss-w-dashboard` |
+| `feed` | `ui-page ui-page--feed` | 720px | read top to bottom: activity, logs, timelines, a thread | `.gemboss-w-feed` |
+| `form` | `ui-page ui-page--form` | 662px | one column of fields: settings, a create form | `.gemboss-w-form` (Polaris narrowWidth) |
+| `canvas` | `ui-page ui-page--canvas` | 1440px | content measured to be wider than a column of text: a horizontal path, a wide comparison table | `.gemboss-w-canvas` (funnel path, 864px needed) |
+| `full` | `ui-page ui-page--full` | none | a board or an editor that IS the screen. Write the reason next to it. | the editor (fixed, its own frame) |
+
+React: one `PageContainer` directly inside `AppShell` caps every screen. Pass the CURRENT route's tier; a page
+cannot widen a cap its parent set, so a screen that needs `canvas` or `full` gets it here, not from a second
+wrapper of its own.
+
+```tsx
+<AppShell rail={rail}>
+  <PageContainer width={route === "settings" ? "form" : route === "board" ? "full" : "default"}>{page}</PageContainer>
+</AppShell>
+```
+
+`as="section"` changes the tag. `pageWidthClass("form")` returns the class string for a server template.
+`PageContainer` lives in its own plain module (`packages/ui/src/page.tsx`), not in `shell.tsx`, and `AppShell` has no width
+prop: the admin imports the shell pieces from `shell.tsx`, a client module its bundler keeps whole, and the
+admin's first-load shell budget had no room for even this much JS (240.0 / 240 KB, 04/10/2026).
+
+Plain HTML (GemFactory, gemcare, gempress): one wrapper as the first child of main.
+
+```html
+<main class="gemboss-platform-main">
+  <div class="ui-page ui-page--form">…</div>
+</main>
+```
+
+Delete the surface's own cap when it moves onto a tier (`maxWidth: 1160` on each gemwatcher screen, a
+`max-width` on a `.container`): two caps on one column means the narrower one wins and nobody can tell which.
+
+**A cap only exists where it is SMALLER than the room it sits in.** Right of the 240px rail, inside main's 24px
+padding, the room is `viewport − 288`: 992 at 1280, 1152 at 1440, 1632 at 1920. So 900 bites at all three, and
+1440 (`canvas`) bites only from about 1730px; below that the column is just the room. Before you quote a width,
+check `cap < viewport − rail − padding` at the width people actually use (the admin shipped two caps, 1040 then
+998, that were wider than the room at 1277 and did nothing there, 10/09/2026). The column is never wider than
+the room, so no tier makes a page scroll sideways; at ≤760px there is no rail and the column is `viewport − 32`.
+
+The page must reset `body { margin: 0 }` itself: `gemboss-ui.css` does not (the admin gets it from Polaris).
+
 ## The sign-in screen
 
 ```tsx
@@ -157,11 +206,46 @@ the admin `@import`s it, so it is the same file the admin's own chat is drawn wi
 The toolbar row, the one-row layout, the engine picker's layout and Stop are in a second sheet,
 `chat-composer.css` (also inside `gemboss-ui.css`): the admin imports it from its chat components rather than its
 layout, so screens without a chat never load it. The catalog's "Thân chat" section is the markup to copy. NOT here, on purpose: the panel's own geometry
-(`.gemboss-ec` width, editor columns), attachments, action cards, the engine picker and work mode — those
+(`.gemboss-ec` width; the editor columns are in `editor.css` since 0.9.0), attachments, action cards, the engine picker and work mode — those
 are still the admin's. The one exception is the chat panel's touch / mouse target blocks: one rule per pointer
 kind names every control of the panel, admin-only ones included (they match nothing elsewhere). The behaviour (streaming, Stop, Enter to send, IME, scroll-to-bottom) belongs to
 the surface.
 
+## Editor CSS (0.9.x)
+
+The admin's three editors (theme, page, section) are drawn with `editor.css`, moved verbatim out of the admin's
+`gemboss-shell.css` on 04/10/2026: the same file the admin loads, so a surface that writes the same markup gets the
+same editor. It is a SEPARATE entry, not part of `gemboss-ui.css`: a surface with no editor does not download it.
+
+```ts
+import "@gemboss/ui/gemboss-ui.css";
+import "@gemboss/ui/editor.css";   // only on the screens that show an editor
+```
+
+```html
+<link rel="stylesheet" href="…/gemboss-ui.css"><link rel="stylesheet" href="…/editor.css">
+```
+
+| Piece | Classes |
+|---|---|
+| Frame | `.gemboss-editor` (fixed, full screen; `--embedded` fills its container) › `header.gemboss-editor-topbar` + `.gemboss-editor-body` › `.gemboss-ec` (left column, width `--gemboss-chat-w`) + `.gemboss-editor-resizer.ui-resizer` + `.gemboss-editor-preview-pane`. `--gemboss-editor-inset` (5px) is the gap and the outer padding. Toast `.gemboss-editor-toast`, status line `.gemboss-editor-statusbar`, phone pane switch `.gemboss-editor-mobile-tabs › .gemboss-editor-mobile-tab` |
+| Top bar | `.gemboss-editor-topbar` (`--theme`, `--guest`) › `.gemboss-editor-tb-left` (`.gemboss-editor-back`, `.gemboss-editor-tb-name`) · `.gemboss-editor-tb-center` · `.gemboss-editor-tb-right` (`.gemboss-editor-tb-tools`, `.gemboss-editor-tb-ghost`, `.gemboss-editor-tb-undo`, `.gemboss-editor-chat-toggle`, `.gemboss-editor-savestate`). Publish split button `.gemboss-editor-tb-publish` / `.gemboss-editor-publish` (`-main`, `-caret`). Overflow `.gemboss-editor-overflow` (`-trigger`) › `.gemboss-editor-menu` › `.gemboss-editor-menu-item` (`-label`, `-val`, `-check`, `-ext`), `.gemboss-editor-menu-sep` |
+| Page picker | `.gemboss-pagepicker` › `-trigger` (`-trigger-icon`, `-trigger-label`, `-caret`) + `-menu` › `-search` (`-search-icon`, `-search-input`), `-list` › `-item` (`-item-icon`, `-item-label`, `-check`, `-drill`, `-thumb`), `-back`, `-empty`, `-note` |
+| Preview | `.gemboss-pv` › `.gemboss-pv-stage` › `.gemboss-pv-frame` (`.desktop` / `.tablet` / `.mobile`, `.gemboss-pv-fit` for scale-to-fit) › `iframe.gemboss-pv-iframe`; `.gemboss-pv-spin`; empty state `.gemboss-pv-empty` (`-art`, `-title`, `-sub`, `-cta`). Device toggle `.gemboss-pv-devices › button.gemboss-pv-device` |
+| Left column | tab row `div.gemboss-ec-tabs[role=tablist] › button[role=tab][aria-selected]` (add `.gemboss-ec-tab` for the 44px pointer floors); Configure pane `.gemboss-ec-dock-body` |
+| Inspector | `.gemboss-ei` (`--docked` inside the Configure pane) › `.gemboss-ei-head` (`-title`, `-x`, `-savedot`), `.gemboss-ei-tabs › .gemboss-ei-tab`, `.gemboss-ei-body`, `.gemboss-ei-foot`. Groups `.gemboss-ei-group › .gemboss-ei-grouphead` (collapsible) and `.gemboss-ei-gh` / `.gemboss-ei-grp`. Field `.gemboss-ei-fld › label + control + .gemboss-ei-hint` |
+| Controls | text / select `.gemboss-field.gemboss-ei-inp` (+ `.gemboss-ei-suffix`, `.gemboss-ei-mono`), segmented `.gemboss-ei-seg`, colour `.gemboss-ei-color` / `.gemboss-ei-swatches › .gemboss-ei-sw` / `.gemboss-ei-swatch`, range `.gemboss-ei-range` + `.gemboss-ei-rangeval`, spacing box `.gemboss-ei-edgebox › .gemboss-ei-edge`, image `.gemboss-ei-img` (`-thumb`, `-ctl`, `-actions`, `-grid`, `-cell`), repeater `.gemboss-ei-rep-item` (`-head`, `-acts`, `-add`), blocks `.gemboss-ei-block` (`-head`, `-x`), add `.gemboss-ei-addrow` / `.gemboss-ei-addchip`, element tree `.gemboss-ei-tree › .gemboss-ei-tnode` (`-tname`, `-tacts`, `-tadd`), notes `.gemboss-ei-note`, `.gemboss-ei-oos` (`-h`), `.gemboss-ei-empty`, drag `.gemboss-ei-drag` / `.gemboss-ei-dragmask` |
+| Layers | `.gemboss-layers` › `.gemboss-layer-head` + `.gemboss-layers-list` › `.gemboss-layer` (`.is-sel`) › `.gemboss-layer-main` (`.gemboss-layer-type`) + `.gemboss-layer-acts` (`.gemboss-layer-del`) |
+| Settings drawer | `.gemboss-settings` › `.gemboss-picker-head` + `.gemboss-settings-body` › `.gemboss-settings-field`, `-grouphead`, `-gen`, `-note`, `-error`, `-handle`; `.gemboss-settings-foot` (`-save`, `-cancel`); backdrop `.gemboss-picker-backdrop`, empty `.gemboss-picker-empty` |
+| Page / section editor bar | `.gemboss-pageedit` (`-top`, `-title`, `-kind`, `-status`, `-standing`, `-scope`, `-modes`, `-notice`, `-chip`, `-pv`), `.gemboss-sec-type`, section insert `.gemboss-sec-insert-*`, draft preview `.gemboss-page-draft-stage` / `-status`, `.gemboss-page-section-content`, global styles bundle `.gemboss-bundle-look` |
+| Try door bar | `.gemboss-editor-topbar--guest` › `.gemboss-guest-brand` (`.gemboss-guest-mark`), `-note`, `-keep`, `-signin` |
+
+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.
+
 ## 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
@@ -202,6 +286,98 @@ false to keep the popup open (it gets the close value, and a guard that throws k
 asserted in Chromium by `packages/ui/src/kit-plain.test.ts` (`npm run test:ui-browser`, run by the CI job that has
 Chromium; `test:packages` excludes it); the catalog's "Hộp thoại" section runs it live.
 
+## Navigation pending (0.10.0): a click answers on the first frame
+
+Chris, 05/10/2026: content-radar's rail (click a menu item and its icon turns into a spinner, sub items too; rest the
+pointer on one and its page is fetched ahead) is the standard for every surface. Measured 04/10 on content-radar with a
+server ~280 ms away: a rail click left the screen unchanged for 321-503 ms; with this, 6-8 ms. The rule: **something
+on screen changes within 100 ms of every navigation click.** A skeleton is optional (see below); this is not.
+
+One state, drawn by `app-shell.css` (inside `gemboss-ui.css`), set three ways:
+
+| Surface | What you write | What you get |
+|---|---|---|
+| Next.js App Router | `import { NavLink, PendingLink } from "@gemboss/ui/next"` then `<RailItem as={NavLink} href="/x" icon={…} label="X" />`, `<RailSubItem as={NavLink} href="/x/y">Y</RailSubItem>` | prefetch when the pointer or keyboard focus rests 120 ms, or on touchstart (never on sight, never on a sweep or a Tab run); while the page loads, the icon becomes the spinner (sub item: 12px in its indent, before the label), wait cursor, a `role="status"` "Loading" for screen readers |
+| React without Next | `<RailItem pending={loadingHref === href} … />`, `RailSubItem pending` | the same look (`aria-busy="true"`); prefetch is your router's |
+| Plain HTML (GemFactory, taskdesk, gemcare, gempress) | load `kit-plain.js`; nothing else | it attaches itself: a followed `.gnav-item` / `.gnav-subitem` link gets `aria-busy="true"`; a link the pointer or keyboard focus rests on for 120 ms, or a finger touches, is prefetched once: a speculation rule in Chromium (the click reuses it whatever the Cache-Control), else `<link rel="prefetch">` (reused only for a cacheable page) |
+
+Links in the page (a list row, a card, a tab): `PendingLink` in Next (`mark="corner"` for a link that wraps a whole
+card), or `data-gb-pending` (`"inline"` / `"corner"`) on an `<a>` with kit-plain.js. `PendingIcon` (Next) swaps the icon of a
+NavLink outside the rail (a tab with an icon) for the spinner; not inside PendingLink (it has its own) and not in a rail
+item (already swapped).
+
+kit-plain.js, exactly: same origin; a plain left click (no Cmd / Ctrl / Shift / Alt, not the middle button); no
+`target` other than `_self`; no `download`; not a `#hash` (or `href="#"`) on the same page; nothing already called
+`preventDefault` (a client router, a popup; the kit listens on the window, so it sees the page's own delegated handlers). The mark comes off on `pageshow` (back/forward cache), Escape, the browser's stop
+(`navigateerror`), the next followed link, and after 15 s at the latest. Opt out with `data-gb-nav="off"` on the link
+or any ancestor (`<html>` for a whole page); `data-gb-prefetch="off"` keeps the spinner and skips the prefetch: put it
+on any GET link that DOES something (sign out, export). It never prefetches in a Next app (`window.next`), nor once a
+client router has taken a rail click over (any SPA): the router owns its links, and a document prefetch there is a
+server request the click never uses. A PendingLink to the page already shown (`?tab=b`) gets its spinner but not the
+RouteCover. Links NavLink renders carry
+`data-gb-nav="next"` and are left to it.
+
+`@gemboss/ui/next` is its own entry, and `next` (>= 15.3, for `useLinkStatus`) is an OPTIONAL peer: the main entry never
+imports it (`kit-plain-bundles.test.ts` bundles it without next), so Vite and plain-HTML surfaces are unaffected. With
+Next's prefetch on intent you also want `experimental.staleTimes` (`{ dynamic: 30, static: 180 }`, as the admin and
+content-radar) so going back to a page is served from the router cache, and the loading boundary below is NOT optional;
+a navigation that is not a link
+(`router.push` from a select) is not covered: give that control its own pending state.
+
+The admin is not on this yet: it answers a click with its own holding screen (`NavPending.tsx`: the clicked item takes
+the selected pill at once, the content area is covered after 90 ms) and does its own hover prefetch, and its shell CSS
+has under 1 KB of first-load headroom. Its rail already sets `aria-busy` on the pending hub, so moving it over is the
+`app-shell.css` rules into `shell.css` plus `RailSubItem pending`.
+
+### The loading boundary: REQUIRED with NavLink
+
+**Every route group whose links are `NavLink` / `PendingLink` must have a `loading.jsx`, and it renders `RouteHolding`.**
+Next prefetches a dynamic route only down to its nearest loading boundary. Without one, intent prefetch fetches
+nothing useful and the click waits a whole server round trip with the old page on screen, spinner or not. Measured
+05/10/2026 on content-radar (no `loading.*` file, server ~280 ms away): hover prefetches returned 0.3-1.2 KB, none
+finished before the click, and the new screen took 350-780 ms although the rail spinner showed at 5-38 ms. gemwatcher
+(a SPA that draws the new screen's frame first and fills it after) "jumps at once": 8-30 ms. The admin measured the same
+from the other side: deleting `app/app/loading.tsx` cost 60-270 ms per click.
+
+```jsx
+// app/v2/loading.jsx: ONE file for the group, not one per page
+import { RouteHolding } from "@gemboss/ui";
+export default function Loading() { return <RouteHolding />; }
+
+// app/v2/layout.jsx: ONE RouteCover beside the page, inside the shell
+import { RouteCover } from "@gemboss/ui";
+<AppShell …><PageContainer width={…}>{children}</PageContainer><RouteCover /></AppShell>
+```
+
+The boundary alone is not enough for `t_route`: Next paints it only once a prefetch or the click's own request has come
+back, one server round trip, and a 120 ms hover rarely lets the prefetch finish (content-radar through a 280 ms
+proxy, 05/10/2026: ~300-350 ms with the boundary). `RouteCover` is the same frame already in the page: the
+`@gemboss/ui/next` links set `html[data-gb-navigating]` while pending, and the cover shows over the content area (below
+the topbar, right of the rail) from the click (80 ms fade) until the navigation commits, where the boundary or the page
+takes over in the same place. It is the admin's holding screen (`.gemboss-route-shell`), minus the destination's name.
+
+`RouteHolding` (and `RouteCover`) is one frame for every route: a title bar and four lines in the content column (`width` takes the
+PageContainer tiers; `"none"` when the shell already caps the column; `title` when the boundary knows its one
+destination), `role="status"` with a "Loading" label, no card edges. It is a plain component (no hooks), so a server
+`loading.jsx` renders it, and the admin's first load does not carry it. Two numbers to check per surface (visual-gate
+`--clicks`, or the PR's Playwright script): `t_feedback` (something changes) and `t_route` (the new screen, holding
+frame included, is up), both within 100 ms of the click.
+
+### Page skeletons: where a page has the conditions, not everywhere
+
+A skeleton shaped like one page is optional (Chris: "cái có cái không tuỳ điều kiện nhưng dần sẽ áp dụng hết"). Use the
+kit's `.ui-skeleton` inside a page (a `<Suspense>` fallback around one slow block) when its shape is known before its
+data (a list, a table, a card grid), and keep it to that shape: one that does not match the page is a layout jump of its
+own. Always with the screen reader line:
+
+```jsx
+<div className="ui-skeleton" aria-busy="true">
+  <span className="ui-sr-only">Loading</span>
+  <span className="ui-skeleton__line" style={{ width: "40%" }} />
+  <span className="ui-skeleton__line" />
+</div>
+```
+
 ## Polaris parity (0.5.0)
 
 The admin is Polaris; this package is how the rest of the fleet looks like it. Measured on 02/10/2026 across the six
@@ -226,6 +402,7 @@ New primitives, Polaris' shapes on GemBoss tokens (`kit-plain.css`; the admin us
 | Help / error under a field | `ui-help`, `ui-error`; `aria-invalid="true"` paints the field | Labelled help text, InlineError |
 | Radio group | `fieldset.ui-choices` + `label.ui-check > input[type=radio]` | ChoiceList |
 | On / off that applies at once | `label.ui-check.ui-switch > input[role=switch]` | (admin toggle) |
+| (0.9.0) Long label text | put the text in an element: `label.ui-check > input + span`. A long unbroken run (URL, `a/b/c/d`) then breaks inside the label in a block, a column, `ui-choices` or a switch. Not covered: bare text after the input (anonymous flex item), and a label in a flex ROW (it keeps its min-content so short labels are never split): let that row wrap | |
 | Label for an icon button | `.ui-tooltip > button + .ui-tooltip__bubble[role=tooltip]` | Tooltip |
 | Waiting | `ui-spinner` (20px), `--lg` (44px) | Spinner |
 | Progress | `progress.ui-progress`, `--success|--critical` | ProgressBar small |
@@ -547,9 +724,11 @@ something the base cannot express, add a token or a prop here, and every surface
 | `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). |
 | `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/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. All inside `gemboss-ui.css`; the admin @imports `chat.css` and `chat-composer.css` itself. |
+| `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). |
 | `packages/ui/src/**/*.tsx` | the components, as TypeScript source. Next: add `@gemboss/ui` to `transpilePackages`. Vite compiles it as is. |
+| `packages/ui/src/next/` | 0.10.0, `@gemboss/ui/next`: `NavLink`, `PendingLink`, `PendingIcon`, `NAV_DWELL_MS`. Needs `next` >= 15.3 (optional peer; only this entry imports it). See "Navigation pending". |
 
 `gemboss-ui.css` is never committed and never edited. To change a colour or a radius, change
 `packages/ui/src/gemboss-tokens.css` / `packages/ui/src/ui.css`; to change the rail, the topbar or the thread rail,