@gemboss/ui 0.7.1 → 0.8.0

package/gemboss-ui.css

@@ -1,8 +1,8 @@
 /*
  * GemBoss admin design system — GENERATED — do not edit; regenerate from gemboss:
  *   node apps/admin/scripts/export-ui-css.mjs --out <path>   (npm run export:ui-css)
- * gemboss commit: fef56e0d93ce96cce6e59613fc62f8f68a739cd2
- * sources sha256: 518302cf7e7a5abd3c1c2157f2b0993b9578c9e030d25ee90cd5ef36b898eec2
+ * gemboss commit: 680adcf8cd1434698a6e1facafcd52d0a642ce96
+ * sources sha256: 2d75fe13397758ceeb8de58a7418337dafd3cb1aa573e5c4c9f3438ba8099347
  * contents: 1 allow-listed rule from apps/admin/src/app/globals.css + packages/ui/src/gemboss-tokens.css
  *   (verbatim) + packages/ui/src/ui.css (verbatim) + packages/ui/src/gemboss-field.css (verbatim)
  *   + 181 rules from packages/ui/src/shell.css (the shared shell)
@@ -457,10 +457,11 @@ a.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-offset:
 
 /* ── Modal ────────────────────────────────────────────────────────────────────
    Rendered INLINE (not portaled): a portal escapes the .gemboss-admin-shell token
-   scope and would render light. Kept in-tree so --ui-* resolves to the surface. */
+   scope and would render light. Kept in-tree so --ui-* resolves to the surface.
+   0.7.3: Polaris Modal's density (#1099, README "Popup density"). Popup only: --ui-control-h stays 32. */
 .ui-overlay {
   position: fixed; inset: 0; z-index: 500;
-  background: rgba(0, 0, 0, 0.6); backdrop-filter: blur(2px);
+  background: rgba(0, 0, 0, 0.5);
   display: grid; place-items: center; padding: 20px;
 }
 .ui-modal {
@@ -470,30 +471,39 @@ a.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-offset:
 }
 /* Head = title + the one close button every modal used to draw for itself. */
 .ui-modal__head {
-  display: flex; align-items: flex-start; gap: 16px;
-  padding: 16px 20px; border-bottom: 1px solid var(--ui-border);
-  font-size: 15px; font-weight: 620; color: var(--ui-text);
+  display: flex; align-items: center; gap: 12px;
+  padding: 12px 16px; border-bottom: 1px solid var(--ui-border);
+  font-size: 14px; line-height: 20px; font-weight: 650; color: var(--ui-text);
 }
 .ui-modal__title { min-width: 0; flex: 1 1 auto; }
 .ui-modal__close {
   flex: 0 0 auto; display: inline-flex; align-items: center; justify-content: center;
-  width: 44px; height: 44px; margin: -8px -8px -8px 0;   /* a 44px target that does not grow the head */
+  width: 28px; height: 28px; padding: 0;
   border: 0; border-radius: var(--ui-radius-md, 8px); background: transparent;
   color: var(--ui-text-muted); cursor: pointer;
 }
 .ui-modal__close svg { width: 20px; height: 20px; }
 .ui-modal__close:hover { background: var(--ui-surface-2); color: var(--ui-text); }
 .ui-modal__close:focus-visible { outline: 2px solid var(--ui-focus); outline-offset: -2px; }
+/* Here, not in kit-plain.css: the admin loads only this file (0.7.3). */
+.ui-modal__body { padding: 16px; }
+.ui-modal__foot {
+  display: flex; flex-wrap: wrap; gap: 8px; justify-content: flex-end;
+  padding: 12px 16px; border-top: 1px solid var(--ui-border);
+}
+:is(.ui-modal__head, .ui-modal__foot) .ui-btn { height: 28px; padding: 0 12px; font-size: var(--ui-fs-caption); }
+/* 44px under a thumb or at phone width; -8px keeps the head 53. */
+@media (pointer: coarse), (max-width: 47.9975em) {
+  .ui-modal__close { width: 44px; height: 44px; margin: -8px -8px -8px 0; }
+  :is(.ui-modal__head, .ui-modal__foot) .ui-btn { min-height: 44px; }
+}
 
-/* `size="lg"` — the screen-shaped dialog. Only the HOOK lives here: this sheet is imported by the
-   root layout, so every rule in it is paid on every screen, and the geometry of a dialog with one
-   consumer belongs in that consumer's chunk (see SettingsDialog.module.css). */
+/* `size="lg"`: only the HOOK here (this sheet is paid on every screen); its geometry is in
+   SettingsDialog.module.css, the one consumer's chunk. */
 .ui-modal--lg { position: relative; }
 
-/* The kit's multi-line field joins the ONE field family (01/10/2026, Chris: "form control đồng bộ"):
-   same input-border token, hover and focus ring as `gemboss-field` and `.ui-select`. Before, it drew a
-   lighter --ui-border box at 14px with no focus ring, so on GemFactory's compose form a textarea sat
-   beside selects of a darker border and text fields of a third look (measured on prod). */
+/* The kit's multi-line field is the ONE field family (01/10/2026, Chris: "form control đồng bộ"): same
+   border token, hover and focus ring as `gemboss-field` / `.ui-select` (it drew a third look on GemFactory). */
 .ui-textarea {
   width: 100%; min-height: 96px; resize: vertical; box-sizing: border-box;
   background: var(--gemboss-field-bg);
@@ -3376,23 +3386,24 @@ body.gemboss-assistant-unread .gnav-item.gnav-assistant::after {
    Link: `<a class="ui-link" href>` for a link inside text. Iris (--gemboss-accent-strong, 6.2:1 on white), underlined
    so it is not told by colour alone (WCAG 1.4.1); visited looks the same (these are tools, not articles). Markdown or
    other generated HTML you cannot add classes to: wrap it in `.ui-prose` and its bare `<a>` get the same look.
+   `.ui-prose` links sit at :where() specificity (0.7.3), so any component's own link rule wins inside it.
 
    Media card: `<article class="ui-card ui-card--media"><a|button class="ui-card__media"><img alt=""></…>
    <div class="ui-card__body">…</div><div class="ui-card__foot">…</div></article>`. The picture is 16:10 and
    cropped to fill; the card has no padding of its own, the body and foot do. */
 .ui-link,
-.ui-prose a:not([class]) {
+.ui-prose :where(a:not([class])) {
   color: var(--gemboss-accent-strong, #3a44de);
   text-decoration: underline;
   text-decoration-thickness: from-font;
   text-underline-offset: 2px;
 }
 .ui-link:visited,
-.ui-prose a:not([class]):visited { color: var(--gemboss-accent-strong, #3a44de); }
+.ui-prose :where(a:not([class])):visited { color: var(--gemboss-accent-strong, #3a44de); }
 .ui-link:hover,
-.ui-prose a:not([class]):hover { color: var(--gemboss-accent, #5661f5); text-decoration-thickness: 2px; }
+.ui-prose :where(a:not([class])):hover { color: var(--gemboss-accent, #5661f5); text-decoration-thickness: 2px; }
 .ui-link:focus-visible,
-.ui-prose a:not([class]):focus-visible { outline: 2px solid var(--ui-focus, #5661f5); outline-offset: 2px; border-radius: 2px; }
+.ui-prose :where(a:not([class])):focus-visible { outline: 2px solid var(--ui-focus, #5661f5); outline-offset: 2px; border-radius: 2px; }
 
 .ui-card--media { padding: 0; overflow: hidden; display: flex; flex-direction: column; }
 .ui-card__media {
@@ -3411,13 +3422,16 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
 }
 
 /* Popup body and foot: `<div class="ui-modal__body">…</div><div class="ui-modal__foot"><button class="ui-btn">…</button></div>`.
-   ui.css never styled these, and the admin does not load this file: its Modal.tsx children carry their own padding
-   (or none). Every non-React surface padded them by hand (GemFactory: 16/20 and a hairline above the actions). kit-plain.js's openModal writes exactly this shape. */
-.ui-modal__body { padding: 16px 20px; }
-.ui-modal__foot {
-  display: flex; flex-wrap: wrap; gap: 8px; justify-content: flex-end;
-  padding: 12px 20px; border-top: 1px solid var(--ui-border);
-}
+   Their padding moved to ui.css in 0.7.3 (the admin loads that file, not this one). kit-plain.js's openModal writes
+   exactly this shape. What stays here is what only the plain-HTML popups use:
+
+   A head that carries more than a title (a large popup's subtitle and its own actions, GemFactory's detail popup):
+   `<div class="ui-modal__head"><div class="ui-modal__title">Mega menu<span class="ui-modal__subtitle">chrome/header</span>
+   </div><div class="ui-modal__actions"><button class="ui-btn">Copy</button></div><button class="ui-modal__close">…` */
+.ui-modal__subtitle { display: block; margin-top: 2px; font-size: var(--ui-fs-caption); line-height: 16px; font-weight: 450; color: var(--ui-text-muted); overflow-wrap: anywhere; }
+.ui-modal__actions { flex: none; display: flex; flex-wrap: wrap; align-items: center; gap: var(--ui-space-2); }
+/* An icon button in the popup's head or foot is square at the popup's 28 (ui.css gives those buttons 0/12 padding). */
+:is(.ui-modal__head, .ui-modal__foot) .ui-btn--icon { width: 28px; padding: 0; }
 /* A popup taller than the screen: the body scrolls, the head and foot stay, so the actions are always reachable
    (320×568 with a long form put Huỷ/Xoá below the fold, unreachable under the locked page; review #3633). */
 .ui-overlay > .ui-modal { display: flex; flex-direction: column; max-height: calc(100dvh - 40px); }
@@ -3689,7 +3703,7 @@ button.ui-card__media, a.ui-card__media { cursor: pointer; }
    <div class="ui-modal__foot">…</div></dialog>` */
 dialog.ui-modal { padding: 0; max-width: calc(100% - 40px); max-height: calc(100dvh - 40px); color: var(--ui-text); }
 dialog.ui-modal[open] { display: flex; flex-direction: column; }
-dialog.ui-modal::backdrop { background: rgba(0, 0, 0, 0.6); backdrop-filter: blur(2px); }
+dialog.ui-modal::backdrop { background: rgba(0, 0, 0, 0.5); } /* the overlay's own scrim (0.7.3: Polaris' .5, no blur) */
 
 /* ── 0.5.1: what the first surfaces on 0.5.0 still drew themselves (GemFactory, content-radar, 03/10/2026) ─────────── */
 
@@ -3751,6 +3765,21 @@ button.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-off
    repaint its edge grey the moment it is clicked (measured on gemwatcher Radar). */
 .ui-metric.ui-metric:is([aria-pressed="true"], [aria-current="page"]) { border-color: var(--gemboss-accent); box-shadow: inset 0 0 0 1px var(--gemboss-accent); }
 
+/* 0.7.3: numbered pager + ui-more, for the plain surfaces (the admin uses Polaris Pagination). Markup and rationale:
+   README "Long lists". Here, not in ui.css: ui.css is exported verbatim into the admin, under a 90 KB budget. */
+.ui-pager > a, .ui-pager > [aria-disabled="true"] { min-width: 32px; justify-content: center; box-sizing: border-box; gap: 4px; }
+.ui-pager > a[aria-current="page"] { background: var(--ui-text); border-color: var(--ui-text); color: var(--ui-surface); font-size: var(--ui-fs-body); font-weight: 600; }
+.ui-pager > a[aria-current="page"]:hover { background: var(--ui-text); }
+.ui-pager > [aria-disabled="true"] { display: inline-flex; align-items: center; min-height: 32px; padding: 0 12px; border: 1px solid var(--ui-border); border-radius: var(--ui-radius-md); color: var(--ui-text-muted); font-size: var(--ui-fs-body); opacity: .55; cursor: default; }
+.ui-pager > [aria-disabled="true"]:hover { background: none; }
+.ui-pager__gap { min-width: 16px; text-align: center; color: var(--ui-text-muted); }
+.ui-pager__range { margin-left: auto; color: var(--ui-text-muted); font-size: var(--ui-fs-body); font-variant-numeric: tabular-nums; }
+.ui-more { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 12px; padding: 16px 0; color: var(--ui-text-muted); font-size: var(--ui-fs-body); text-align: center; }
+.ui-more[hidden] { display: none; }
+@media (pointer: coarse), (max-width: 47.9975em) { .ui-pager > a, .ui-pager > [aria-disabled="true"] { min-width: 44px; min-height: 44px; } }
+/* Phone: 11 targets of 44px wrapped into 3-4 rows at 320 (measured). Keep Previous · current · Next; the range wraps under. */
+@media (max-width: 35.9975em) { .ui-pager > a:not([rel]):not([aria-current]):not([aria-disabled]), .ui-pager__gap { display: none; } }
+
 /* ═══ @gemboss/ui src/chat.css ═══ */
 /*
  * The chat BODY — what an answer looks like, wherever a GemBoss surface puts a chat (01/10/2026).
@@ -4299,9 +4328,9 @@ button.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-off
 
 /* ═══ @gemboss/ui src/portal.css ═══ */
 /* ═══ Portal pieces — @gemboss/ui 0.7.0 (04/10/2026) ════════════════════════════════════════════
-   TopbarNav, Avatar, Leaderboard, Podium (portal.tsx), SearchDialog (dialog.tsx), ThemeToggle and the
-   dark palette (theme.tsx). Tokens only: every colour comes from --gemboss-* / --ui-*, so the dark
-   palette at the end reaches these too. */
+   TopbarNav, Avatar, Leaderboard, Podium (portal.tsx), SearchDialog (dialog.tsx), ThemeToggle (theme.tsx).
+   Component rules only, no rule on :root, html or body (a test holds that): a surface with its own skin
+   can take this file with gemboss-tokens.css alone. The dark palette is theme-dark.css. */
 
 /* ── TopbarNav: section tabs in the topbar, after the brand (Featurebase's "Feedback · Roadmap"). The
    active tab is underlined on the topbar's bottom edge. 44px targets under a finger, 36 under a mouse
@@ -4347,6 +4376,11 @@ button.ui-metric:focus-visible { outline: 2px solid var(--ui-focus); outline-off
 }
 @media (prefers-reduced-motion: reduce) { .gb-topnav-chevron { transition: none; } }
 
+/* Text for screen readers only ("Rank 1:", ", you"). Its own rule, not ui.css's .ui-sr-only: a surface that
+   takes portal.css without the rest of the kit (GemCommunity) would otherwise print it on the page. */
+.gb-sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0 0 0 0);
+  white-space: nowrap; border: 0; }
+
 /* ── Avatar: picture or initials on one of eight tones picked from the name. */
 .gb-avatar { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; border-radius: 50%; overflow: hidden;
   font-weight: 700; line-height: 1; letter-spacing: .01em; user-select: none; }
@@ -4383,6 +4417,9 @@ a.gb-leaderboard-link:focus-visible { outline: 2px solid var(--gemboss-accent);
 .gb-leaderboard-name { flex: 1 1 auto; min-width: 0; font-size: 13px; font-weight: 560; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .gb-leaderboard-value { flex: 0 0 auto; font-size: 13px; font-weight: 650; color: var(--gemboss-text-muted); font-variant-numeric: tabular-nums; }
 .gb-leaderboard-row.is-first .gb-leaderboard-value { color: #8a5a00; font-weight: 750; }
+/* The viewer's own row and podium slot: the selected tint, never a colour of its own. */
+.gb-leaderboard-row.is-current > .gb-leaderboard-link { background: var(--gemboss-active-bg); }
+.gb-leaderboard-badge { flex: 0 1 auto; min-width: 0; overflow: hidden; }
 .gb-leaderboard-all { justify-self: center; display: inline-flex; align-items: center; min-height: 24px; font-size: 12px; font-weight: 600;
   color: var(--gemboss-text-muted); text-decoration: none; }
 .gb-leaderboard-all:hover { color: var(--gemboss-text-strong); text-decoration: underline; }
@@ -4393,6 +4430,8 @@ a.gb-leaderboard-link:focus-visible { outline: 2px solid var(--gemboss-accent);
   background: var(--gemboss-surface); color: var(--gemboss-text); text-decoration: none; text-align: center; }
 a.gb-podium-link:hover { background: var(--gemboss-hover); }
 .gb-podium-slot { min-width: 0; }
+/* A podium with fewer than three people keeps its place: second and third stay empty columns. */
+.gb-podium-slot.is-empty { visibility: hidden; }
 .gb-podium-slot--1 .gb-podium-link { padding-top: 22px; padding-bottom: 20px; border-color: color-mix(in srgb, #d4a017 45%, var(--gemboss-divider)); }
 .gb-podium-slot--2 .gb-podium-link { padding-bottom: 12px; }
 .gb-podium-slot--3 .gb-podium-link { padding-bottom: 8px; }
@@ -4401,6 +4440,7 @@ a.gb-podium-link:hover { background: var(--gemboss-hover); }
 .gb-podium-value { font-size: 15px; font-weight: 750; font-variant-numeric: tabular-nums; }
 .gb-podium-slot--1 .gb-podium-value { color: #8a5a00; }
 .gb-podium-unit { font-size: 11px; font-weight: 500; color: var(--gemboss-text-muted); }
+.gb-podium-slot.is-current .gb-podium-link { border-color: var(--gemboss-text-strong); background: var(--gemboss-active-bg); }
 
 /* ── SearchDialog: the topbar's search button, and the popup (640 wide, near the top, like Featurebase's). */
 .gb-search-trigger, .gb-theme-toggle { display: inline-flex; align-items: center; justify-content: center; width: 36px; height: 36px; flex: 0 0 auto;
@@ -4427,7 +4467,15 @@ dialog.ui-modal.gb-search { width: min(640px, 100%); margin-top: 8vh; max-height
   font-size: 12px; color: var(--ui-text-muted); }
 @media (max-width: 760px) { dialog.ui-modal.gb-search { margin-top: 12px; } .gb-search-foot { display: none; } }
 
-/* ── Dark palette. `ThemeToggle` / `themeScript` set data-theme on <html>; a surface without them stays
+/* ═══ @gemboss/ui src/theme-dark.css ═══ */
+/* ═══ Dark palette — @gemboss/ui 0.7.2 ═══════════════════════════════════════════════════════════════
+   Split out of portal.css (04/10/2026). `ThemeToggle` / `themeScript` set data-theme on <html>, and this
+   file turns every --gemboss-* colour dark under it. It lives apart so that a surface which takes only
+   the leaderboard (gemboss-tokens.css + portal.css) does not inherit it: GemCommunity sets
+   data-theme="dark" for its own sign-in pages and remembers it, and the rule
+   `:root[data-theme="dark"] body` here outranks its body rule, so a member who once picked dark there
+   would get a dark page behind light cards. gemboss-ui.css still carries this file. */
+/* Dark palette. `ThemeToggle` / `themeScript` set data-theme on <html>; a surface without them stays
    light. Only colours change: the components above and every kit class read these tokens. */
 :root[data-theme="dark"] {
   color-scheme: dark;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemboss/ui",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "GemBoss design system for every surface in the fleet: the admin shell (topbar + rail + drawer) as React components, and the admin stylesheet exported as one CSS file.",
   "license": "UNLICENSED",
   "type": "module",
@@ -26,6 +26,8 @@
     "./assistant": "./src/assistant/index.ts",
     "./assistant/dock": "./src/assistant/dock.ts",
     "./assistant.css": "./src/assistant.css",
+    "./portal.css": "./src/portal.css",
+    "./theme-dark.css": "./src/theme-dark.css",
     "./icon.svg": "./src/icon.svg"
   },
   "files": [

package/src/assistant/dock.ts

@@ -132,25 +132,18 @@ export function clampDockHeight(height: number, viewport: number): number {
 }
 
 /**
- * How far below the topbar a popup that has just OPENED starts (03/10/2026).
+ * The height a popup opens at: what the seller dragged it to, else AS TALL AS THE WINDOW ALLOWS — the same 12px under
+ * the topbar a drag can reach (`clampDockHeight`).
  *
- * The 12px ceiling above is where a popup the seller DRAGS can reach. It is not where one should open.
- * Chris, 03/10: "default height cao hơn sát vào topbar". Measured on his browser (window 620px tall):
- * gemwatcher had a dragged 599 saved, every reopen clamped it to 552, and the popup opened 12px under
- * the topbar; a flat 480 default also leaves only 84px on a 620 window and ~0 on a 560 one.
+ * 04/10/2026, Chris chose "gần hết màn" over min(480, viewport − 176) (03/10's 120px opening gap). Measured on
+ * gemwatcher at 1440×900 before: the popup was 480 tall, the engine card took ~190px of its 431px body and the
+ * conversation got ~90px. `null` means "no drag saved" and is resolved against the CURRENT window every time — the
+ * provider keeps it as null rather than freezing the mount-time ceiling (review #3744: a window made taller after load
+ * kept the old, shorter popup).
  */
-export const DOCK_OPEN_GAP = 120;
-
-/** The tallest a popup OPENS at in this window: a quarter-ish band of page stays visible above it. */
-export function dockOpenCeiling(viewport: number): number {
-  return Math.max(DOCK_MIN_HEIGHT, Math.round(viewport) - DOCK_TOPBAR_HEIGHT - DOCK_OPEN_GAP);
-}
-
-/** The height a popup opens at: what the seller asked for (or the default), never closer to the topbar
- *  than DOCK_OPEN_GAP. Dragging in-session can still go up to the 12px ceiling of `clampDockHeight`. */
 export function openingDockHeight(requested: number | null, viewport: number): number {
-  const want = requested !== null && Number.isFinite(requested) && requested > 0 ? requested : DOCK_DEFAULT_HEIGHT;
-  return clampDockHeight(Math.min(want, dockOpenCeiling(viewport)), viewport);
+  const want = requested !== null && Number.isFinite(requested) && requested > 0 ? requested : Infinity;
+  return clampDockHeight(want, viewport);
 }
 
 export const initialAssistantDockState: AssistantDockState = {
@@ -162,7 +155,10 @@ export const initialAssistantDockState: AssistantDockState = {
   dockOffsetRight: DOCK_DEFAULT_OFFSET_RIGHT,
   openNonce: 0,
   sideWidth: SIDE_DEFAULT_WIDTH,
-  floatShape: "dock",
+  // The side panel is where every surface opens by default (Chris, 04/10/2026: "Dính cạnh phải"): it takes the full
+  // height and the page moves over instead of being covered. A host that does not offer it still gets the popup
+  // (`backTo`), and a seller who floats it as a popup is remembered as such.
+  floatShape: "side",
   sideAllowed: false,
 };
 
@@ -204,7 +200,12 @@ export function assistantDockReducer(state: AssistantDockState, event: Assistant
     case "side-allowed":
       if (event.allowed === state.sideAllowed) return state;
       // Withdrawn while the panel is up: it becomes the popup rather than a shape the host no longer draws for.
-      return { ...state, sideAllowed: event.allowed, presentation: !event.allowed && state.presentation === "side" ? "dock" : state.presentation };
+      if (!event.allowed) return { ...state, sideAllowed: false, presentation: state.presentation === "side" ? "dock" : state.presentation };
+      // Allowed (again): a popup that is only there because the panel was not allowed a moment ago — the working shape
+      // is still "side" — goes back to the panel. Two ways that happens (review #3744): the admin mounts its host only
+      // after the first open, so that first open arrived before the host said yes; and a window that dipped below
+      // 1100px (DevTools docked, a snap) and came back. A popup the person CHOSE has floatShape "dock" and stays.
+      return { ...state, sideAllowed: true, presentation: state.presentation === "dock" && state.floatShape === "side" ? "side" : state.presentation };
 
     case "restore-float":
       return { ...state, floatShape: event.shape };

package/src/assistant/host.tsx

@@ -12,7 +12,7 @@
  * assistant is unmounted by the next menu click, and unmounting aborts the run. Geometry only changes
  * class names; the subtree is never re-parented (that would remount the chat and abort the run too).
  */
-import React, { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import React, { useCallback, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
 
 import { DOCK_MIN_HEIGHT, SIDE_MIN_WIDTH, clampDockHeight, clampSideWidth } from "./dock";
 import { sideAvailable, useAssistant } from "./provider";
@@ -62,9 +62,33 @@ export interface AssistantSecondTab {
   content: ReactNode | null;
 }
 
+/** Where the side panel stands BESIDE the page (assistant.css). Below it the panel would cover the page — the whole
+ *  content area at 761–1099px, the whole screen on a phone — so the default there stays the popup (review #3744: on a
+ *  phone a fresh open became a full-screen sheet over the very screen the question is about). */
+export const SIDE_FITS_QUERY = "(min-width: 1100px)";
+
+/** Before paint in the browser, a plain effect on the server (where a layout effect only warns). */
+const useBeforePaint = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+function useSideFits(): boolean {
+  const [fits, setFits] = useState(() => typeof window === "undefined" || !window.matchMedia
+    ? true : window.matchMedia(SIDE_FITS_QUERY).matches);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia(SIDE_FITS_QUERY);
+    const on = () => setFits(mq.matches);
+    on();
+    // Safari < 14 has only the old listener API on MediaQueryList.
+    if (mq.addEventListener) mq.addEventListener("change", on);
+    else mq.addListener(on);
+    return () => { if (mq.removeEventListener) mq.removeEventListener("change", on); else mq.removeListener(on); };
+  }, []);
+  return fits;
+}
+
 export function AssistantHost({
   title, labels, onNewChat, onExpand, onShrink, fullActions, secondTab, view = "primary", onViewChange,
-  miniHint, allowSide = false, children,
+  miniHint, allowSide = true, children,
 }: {
   /** "Gem assistant" in the admin. Names the region, the popup header and the status bar. */
   title: string;
@@ -86,7 +110,8 @@ export function AssistantHost({
   /**
    * Offer the full-height SIDE panel (01/10/2026): a "Pin to the side" button in the popup, "Float as a popup" in the
    * panel. The page makes room for it — `.gemboss-platform-main` pads by `--gb-assistant-side-w`; a surface with its
-   * own layout reads the same variable. Off by default, so a surface that has not laid out for it never meets it.
+   * own layout reads the same variable. ON by default since 04/10/2026 (Chris: the side panel is every surface's default
+   * shape); a surface whose layout cannot make room passes `allowSide={false}` and gets the popup instead.
    */
   allowSide?: boolean;
   children?: ReactNode;
@@ -192,8 +217,16 @@ export function AssistantHost({
   }, []);
 
   // The provider gates every way into the side panel on this, so a host that never offers it never draws it.
+  // …and neither does a window where the panel cannot stand beside the page (04/10/2026). Below 1100 it covers the
+  // content area (or the screen) and the popup hides its pin (assistant.css); with the side panel now the DEFAULT shape,
+  // a first open at 768 went straight into that covering panel (measured on gemwatcher: 528px wide over the whole
+  // page). There the person gets the popup; the reducer puts the panel back when the window is wide again.
   const { setSideAllowed } = dock;
-  useEffect(() => { setSideAllowed(allowSide); }, [allowSide, setSideAllowed]);
+  const sideFits = useSideFits();
+  // Before paint: the admin mounts this host only after the first open, so that open was decided while the panel was
+  // not yet allowed; registering after paint drew the stand-in popup for a frame before the reducer swapped in the
+  // panel (review #3744).
+  useBeforePaint(() => { setSideAllowed(allowSide && sideFits); }, [allowSide, sideFits, setSideAllowed]);
 
   // ── Width drag (side only) ───────────────────────────────────────────────
   // The panel's LEFT edge is a `.ui-resizer` (the fleet's one seam, @gemboss/ui ui.css): dragging it left widens the
@@ -371,7 +404,9 @@ export function AssistantHost({
                   <span className="gb-dock-sr">{L.newChat}</span>
                 </button>
               ) : null}
-              {isDock && allowSide ? (
+              {/* On `dock.sideAllowed`, not the prop: it already folds in the window width (SIDE_FITS_QUERY), so the pin
+                  never shows where pressing it would only drop the working shape to "dock" (review #3744). */}
+              {isDock && dock.sideAllowed ? (
                 <button type="button" className="gb-dock-icon gb-dock-action gb-dock-pinside" title={L.pinSide} onClick={dock.openSide}>
                   {/* A window with its right third filled: the panel it will become. */}
                   <svg viewBox="0 0 20 20" aria-hidden>

package/src/assistant/provider.tsx

@@ -16,9 +16,9 @@ import React, { createContext, useCallback, useContext, useEffect, useMemo, useR
 import {
   assistantDockReducer,
   initialAssistantDockState,
-  DOCK_DEFAULT_HEIGHT,
   DOCK_DEFAULT_OFFSET_RIGHT,
   openingDockHeight,
+  type AssistantFloatShape,
   SIDE_DEFAULT_WIDTH,
   type AssistantDockState,
 } from "./dock";
@@ -33,7 +33,9 @@ export interface AssistantOptions {
 
 /** Storage keys. `lastMode` is the last shape the seller actually used: "full", "dock" or "side" — nothing
  *  else is worth reopening as. Module-level so the callbacks below stay identity-stable. */
-const storageKey = (prefix: string, k: "dockHeight" | "dockOffsetRight" | "lastMode" | "sideWidth" | "floatShape") => `${prefix}.${k}`;
+// `shape`, not the old `floatShape` key (04/10/2026): that one was written on every mount with the then-default "dock",
+// so it records what every browser was GIVEN, not what anyone chose — reading it would keep the old default forever.
+const storageKey = (prefix: string, k: "dockHeight" | "dockOffsetRight" | "lastMode" | "sideWidth" | "shape") => `${prefix}.${k}`;
 
 /**
  * The width of the content area the side panel sits in: the window minus the rail. Measured from `main`'s LEFT
@@ -117,11 +119,10 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
   useEffect(() => {
     try {
       const stored = window.localStorage.getItem(storageKey(opts.current.storagePrefix, "dockHeight"));
-      // Opens no closer to the topbar than DOCK_OPEN_GAP, even when a past drag saved the ceiling
-      // (dock.ts, 03/10/2026). The stored number is left as it was: a drag rewrites it.
-      const height = openingDockHeight(stored === null || stored === "" ? null : Number(stored), window.innerHeight);
-      requestedHeight.current = height;
-      dispatch({ type: "resize", height, viewport: window.innerHeight });
+      // No drag saved: null, resolved against the CURRENT window on every resize (dock.ts `openingDockHeight`).
+      const raw = stored === null || stored === "" ? NaN : Number(stored);
+      requestedHeight.current = Number.isFinite(raw) && raw > 0 ? raw : null;
+      dispatch({ type: "resize", height: openingDockHeight(requestedHeight.current, window.innerHeight), viewport: window.innerHeight });
       // `Number(null)` is 0, not NaN — so reading a key that was never written used to slide the
       // popup flush against the window edge on every fresh browser. Measured: inline `right: 0px`.
       const storedOffset = window.localStorage.getItem(storageKey(opts.current.storagePrefix, "dockOffsetRight"));
@@ -133,7 +134,10 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
         dispatch({ type: "slide", offsetRight: rawOffset, ...offsetBounds() });
       }
       // The working shape outlives a reload: `lastMode` cannot stand in for it, since opening full screen overwrites it.
-      if (window.localStorage.getItem(storageKey(opts.current.storagePrefix, "floatShape")) === "side") dispatch({ type: "restore-float", shape: "side" });
+      const shape = window.localStorage.getItem(storageKey(opts.current.storagePrefix, "shape"));
+      if (shape === "side" || shape === "dock") dispatch({ type: "restore-float", shape });
+      // The pre-0.8.0 key: never read again (it holds the old default, not a choice) — drop it so storage has one answer.
+      window.localStorage.removeItem(`${opts.current.storagePrefix}.floatShape`);
       const storedSide = Number(window.localStorage.getItem(storageKey(opts.current.storagePrefix, "sideWidth")));
       if (Number.isFinite(storedSide) && storedSide > 0) {
         requestedSide.current = storedSide;
@@ -149,7 +153,7 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
    * window baked the smaller number in and growing it back never recovered. Measured 2026-09-12:
    * 800 → window 600 → 512 → window 1200 → still 512. Same trap the persisted value already avoids.
    */
-  const requestedHeight = useRef(DOCK_DEFAULT_HEIGHT);
+  const requestedHeight = useRef<number | null>(null);
   /** Same reasoning as `requestedHeight`: persist what the seller ASKED for, clamp only to draw. */
   const requestedOffset = useRef(DOCK_DEFAULT_OFFSET_RIGHT);
   /** …and the same for the side panel's width: a width chosen on a 27" screen comes back there. */
@@ -175,7 +179,7 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
   // got taller again must give the seller their height back.
   useEffect(() => {
     const onResize = () => {
-      dispatch({ type: "resize", height: requestedHeight.current, viewport: window.innerHeight });
+      dispatch({ type: "resize", height: openingDockHeight(requestedHeight.current, window.innerHeight), viewport: window.innerHeight });
       // …and sideways too. `requestedOffset` was being written and never read, so a window that got
       // narrower left the popup where a wider one had allowed it: on the rail, or past the edge.
       dispatch({ type: "slide", offsetRight: requestedOffset.current, ...offsetBounds() });
@@ -187,11 +191,18 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
 
   const setDockHeight = useCallback((height: number) => {
     const viewport = typeof window === "undefined" ? 900 : window.innerHeight;
-    requestedHeight.current = Math.round(height);
+    // Dragged (or Home) to the ceiling = "as tall as the window allows": back to AUTO, not this window's number — a
+    // saved ceiling kept the popup at 632 after a 700px window was maximised (review #3744).
+    const auto = Math.round(height) >= openingDockHeight(null, viewport);
+    requestedHeight.current = auto ? null : Math.round(height);
     dispatch({ type: "resize", height, viewport });
     // The RAW request, not the clamped result: dragging to the ceiling in a short window used to
     // save that ceiling, so the popup came back permanently smaller on a tall screen.
-    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "dockHeight"), String(Math.round(height))); } catch { /* best-effort */ }
+    try {
+      const k = storageKey(opts.current.storagePrefix, "dockHeight");
+      if (auto) window.localStorage.removeItem(k);
+      else window.localStorage.setItem(k, String(Math.round(height)));
+    } catch { /* best-effort */ }
   }, []);
 
   const setSideWidth = useCallback((width: number) => {
@@ -216,9 +227,15 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
    * Only `full`, `dock` and `side` are recorded. `mini` and `hidden` are ways of putting something away, not
    * ways of working in it; reopening into a collapsed bar would answer a click with almost nothing.
    */
-  useEffect(() => {
-    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "floatShape"), state.floatShape); } catch { /* best-effort */ }
-  }, [state.floatShape]);
+  // The working shape is written ONLY when the person picks it (`openDock` / `openSide` below — the popup's pin and the
+  // panel's "Float as a popup"). An effect on `floatShape` wrote the initial default on every mount, i.e. what each
+  // browser was GIVEN (the flaw that retired the old `floatShape` key), and under StrictMode's double effect run that
+  // write landed between two restores and turned a saved "dock" back into "side" on every reload (review #3744).
+  const sideAllowedNow = useRef(false);
+  sideAllowedNow.current = state.sideAllowed;
+  const saveShape = useCallback((shape: AssistantFloatShape) => {
+    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "shape"), shape); } catch { /* best-effort */ }
+  }, []);
 
   useEffect(() => {
     if (state.presentation !== "full" && state.presentation !== "dock" && state.presentation !== "side") return;
@@ -244,10 +261,16 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
       if (opts.current.isOnFullPage()) return;
       let last = "";
       try { last = window.localStorage.getItem(storageKey(opts.current.storagePrefix, "lastMode")) ?? ""; } catch { /* private mode */ }
-      if (last !== "dock" && last !== "side") return;
+      // The RAIL's Assistant item (`.gnav-assistant`): only someone who last worked FULL screen follows it. Everyone
+      // else — including a browser that never opened it — gets the working shape back (`floatShape`, the side panel by
+      // default since 04/10/2026), not the `lastMode` "dock" the old default wrote for everybody.
+      // Any OTHER link to the full chat ("Open in chat" in a page's content) keeps the old rule: it navigates unless
+      // the person last worked in the popup or the panel (review #3744: it was swallowed for every fresh browser).
+      const rail = !!anchor.closest(".gnav-assistant");
+      if (rail ? last === "full" : last !== "dock" && last !== "side") return;
       e.preventDefault();
       e.stopPropagation();
-      dispatch({ type: last });
+      dispatch({ type: "reopen" });
       // The shell closes its mobile nav drawer when the ROUTE changes. This click deliberately does
       // not change the route, so on a phone the drawer stayed open on top of the popup it had just
       // opened — measured at 390px, `.gnav-scroll` sitting over the composer. Say it out loud
@@ -295,8 +318,9 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
   // fire a spurious "the run ended" on every state change.
   const enterFull = useCallback(() => dispatch({ type: "enter-full" }), []);
   const leaveFull = useCallback(() => dispatch({ type: "leave-full" }), []);
-  const openDock = useCallback(() => dispatch({ type: "dock" }), []);
-  const openSide = useCallback(() => dispatch({ type: "side" }), []);
+  const openDock = useCallback(() => { dispatch({ type: "dock" }); saveShape("dock"); }, [saveShape]);
+  // Not offered here (narrow window, host without the panel): the reducer gives the popup and nothing is recorded.
+  const openSide = useCallback(() => { dispatch({ type: "side" }); if (sideAllowedNow.current) saveShape("side"); }, [saveShape]);
   const reopen = useCallback(() => dispatch({ type: "reopen" }), []);
   const setSideAllowed = useCallback((allowed: boolean) => dispatch({ type: "side-allowed", allowed }), []);
   const minimize = useCallback(() => dispatch({ type: "minimize" }), []);