@gemboss/ui 0.1.0

package/src/assistant/host.tsx

@@ -0,0 +1,371 @@
+"use client";
+
+/**
+ * The assistant's popup / status bar / full-screen host — @gemboss/ui (28/09/2026).
+ *
+ * Moved from gemboss apps/admin/src/components/assistant/AssistantDockHost.tsx; the admin now renders
+ * its assistant through this, and gemwatcher's assistant wears the same one. What the admin had that
+ * nobody else has — the gemcare "Talk to a person" tab, the shop lookup, its router — comes in through
+ * props and slots. The chat itself is `children`.
+ *
+ * Mount it ONCE in the app shell, inside <AssistantProvider>, outside every route: a route-owned
+ * 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 { DOCK_MIN_HEIGHT, clampDockHeight } from "./dock";
+import { useAssistant } from "./provider";
+
+/** One literal class per presentation, not `gb-dock-${mode}`: a runtime-built class name is a stem the
+ *  admin's orphan gate (a-tap-target-rule-outlived-its-markup) has to exempt wholesale. */
+const MODE_CLASS = { hidden: "gb-dock-hidden", mini: "gb-dock-mini", dock: "gb-dock-dock", full: "gb-dock-full" } as const;
+
+/** mm:ss since a run started — the only honest thing the collapsed bar can say. */
+function elapsed(since: number): string {
+  const s = Math.max(0, Math.floor((Date.now() - since) / 1000));
+  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+}
+
+/** Every word the host says. English defaults are the admin's; a surface passes its own language. */
+export interface AssistantHostLabels {
+  ready: string; working: string; done: string;
+  answerWaiting: string; askAboutScreen: string;
+  reopen: string; hide: string; hideTitle: string; openInstead: string; openInsteadTitle: string;
+  grip: string; headerTitle: string;
+  newChat: string; openFull: string; minimize: string; minimizeTitle: string;
+  close: string; closeBusy: string; closeBusyTitle: string;
+  shrinkToPopup: string; tablist: string; primaryTab: string;
+}
+const EN: AssistantHostLabels = {
+  ready: "Ready", working: "Working", done: "Done — tap to see it",
+  answerWaiting: "An answer is waiting", askAboutScreen: "Ask about this screen",
+  reopen: "Reopen the {title}", hide: "Hide the assistant", hideTitle: "Hide the assistant",
+  openInstead: "Open the assistant", openInsteadTitle: "Still working — open it",
+  grip: "Drag to resize the assistant; left and right arrows move it sideways",
+  headerTitle: "Drag this bar to move the popup left or right",
+  newChat: "New chat", openFull: "Open full screen", minimize: "Minimise", minimizeTitle: "Shrink to a bar",
+  close: "Close the assistant", closeBusy: "Shrink to a bar", closeBusyTitle: "Still working — shrink it to a bar",
+  shrinkToPopup: "Shrink to popup", tablist: "Assistant or a person", primaryTab: "Assistant",
+};
+
+/** An optional second tab in the popup (the admin: a person on the Gem team, through gemcare). */
+export interface AssistantSecondTab {
+  label: ReactNode;
+  /** Unread count shown on the tab while it is not the one open. */
+  badge?: number;
+  /** Mounted once first opened, then kept mounted (hidden) so it keeps counting replies. */
+  content: ReactNode | null;
+}
+
+export function AssistantHost({
+  title, labels, onNewChat, onExpand, onShrink, fullActions, secondTab, view = "primary", onViewChange,
+  miniHint, children,
+}: {
+  /** "Gem assistant" in the admin. Names the region, the popup header and the status bar. */
+  title: string;
+  labels?: Partial<AssistantHostLabels>;
+  /** The popup header's ＋. Omit it and the button is not drawn. */
+  onNewChat?: () => void;
+  /** Popup → full screen. The surface decides what that means (the admin navigates to its page). */
+  onExpand: () => void;
+  /** Full screen → popup, e.g. open the dock and go back to the screen they came from. */
+  onShrink: () => void;
+  /** Extra buttons in the full-screen chrome, before "Shrink to popup". Give them `gb-dock-shrink`. */
+  fullActions?: ReactNode;
+  secondTab?: AssistantSecondTab;
+  /** Which tab the popup shows. Owned by the surface, because its full-screen actions may switch it. */
+  view?: "primary" | "secondary";
+  onViewChange?: (view: "primary" | "secondary") => void;
+  /** What the status bar says when idle and nothing is waiting, before the default "Ask about this screen". */
+  miniHint?: string;
+  children?: ReactNode;
+}) {
+  const dock = useAssistant();
+  const L = { ...EN, ...labels };
+  const [runStartedAt, setRunStartedAt] = useState<number | null>(null);
+  const [, setTick] = useState(0);
+  const shellRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => { setRunStartedAt(dock.busy ? Date.now() : null); }, [dock.busy]);
+
+  // Keep the collapsed bar's clock moving while a run is live (1s, only while collapsed).
+  useEffect(() => {
+    if (!runStartedAt || dock.presentation !== "mini") return;
+    const id = window.setInterval(() => setTick((n) => n + 1), 1000);
+    return () => window.clearInterval(id);
+  }, [runStartedAt, dock.presentation]);
+
+  // Hidden means "still running, just not on screen": the subtree stays in the DOM (that is what
+  // keeps the stream alive) but must not be reachable by Tab or a screen reader.
+  useEffect(() => {
+    const el = shellRef.current;
+    if (!el) return;
+    if (dock.presentation === "hidden") el.setAttribute("inert", "");
+    else el.removeAttribute("inert");
+  }, [dock.presentation]);
+
+  // ── Height drag (dock only) ───────────────────────────────────────────────
+  // Dragging the top edge grows the popup UPWARD, so the composer under the cursor never moves.
+  const dragRef = useRef<{ startY: number; startH: number } | null>(null);
+  const onHandleDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    e.preventDefault();
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    setDragging(true);
+    dragRef.current = { startY: e.clientY, startH: dock.dockHeight };
+  }, [dock.dockHeight]);
+  const onHandleMove = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    const drag = dragRef.current;
+    if (!drag) return;
+    dock.setDockHeight(drag.startH + (drag.startY - e.clientY));
+  }, [dock]);
+  const onHandleUp = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    dragRef.current = null;
+    setDragging(false);
+    try { (e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId); } catch { /* already released */ }
+  }, []);
+  // ── Slide sideways (dock only) ───────────────────────────────────────────
+  /**
+   * Drag the header to move the popup along the bottom edge.
+   *
+   * Sideways only, and still glued to the bottom, on purpose: the popup GROWS UPWARD when resized,
+   * so a free-floating window would fight its own resize handle, and one that leaves the bottom
+   * covers more of the page rather than less. Chris asked for "move được từ trái sang phải"; this is
+   * exactly that and nothing more.
+   */
+  const slideRef = useRef<{ startX: number; startOffset: number; moved: boolean } | null>(null);
+  /**
+   * True while the seller is dragging the edge or the header.
+   *
+   * The popup animates when it APPEARS. It must not animate while a finger is on it: a transition on
+   * a value the pointer is setting sixty times a second is exactly what "mượt" turns into "lag" — the
+   * box trails the cursor and every frame fights the last one.
+   */
+  const [dragging, setDragging] = useState(false);
+  /** How far the popup may travel: never under the rail, never past the right edge. */
+  const slideBounds = useCallback(() => {
+    const host = shellRef.current;
+    // Round UP: a fractional width rounded down leaves the popup a pixel or two over the line, which
+    // is exactly how the first version of this ended up 3px on top of the rail (measured, 1440px).
+    const width = Math.ceil(host?.getBoundingClientRect().width ?? 600);
+    // Both limits from ONE rect — `main`, the content area the popup floats over.
+    //
+    // The first version mixed sources: `window.innerWidth` (and `clientWidth`, which reported the
+    // same) for the right edge and `main.left` for the left. Both said 1440 while the real layout
+    // viewport was 1429, so full-left landed ~11px on top of the rail. Measuring the travel INSIDE
+    // one box cannot disagree with itself: `main.right` is where an offset of 0 would sit, and
+    // `main.left` is where the rail ends.
+    const main = document.querySelector(".gemboss-platform-main")?.getBoundingClientRect();
+    const track = main ? main.width : (document.documentElement.clientWidth || window.innerWidth);
+    return { min: 8, max: Math.max(8, Math.floor(track - width - 8)) };
+  }, []);
+  const onHeaderDown = useCallback((e: React.PointerEvent<HTMLElement>) => {
+    // Buttons in the header keep their clicks; only the bare strip drags.
+    if ((e.target as HTMLElement).closest("button")) return;
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    setDragging(true);
+    slideRef.current = { startX: e.clientX, startOffset: dock.dockOffsetRight, moved: false };
+  }, [dock.dockOffsetRight]);
+  const onHeaderMove = useCallback((e: React.PointerEvent<HTMLElement>) => {
+    const drag = slideRef.current;
+    if (!drag) return;
+    // A few pixels of slop, so a click that wobbles is still a click.
+    if (!drag.moved && Math.abs(e.clientX - drag.startX) < 4) return;
+    drag.moved = true;
+    const { min, max } = slideBounds();
+    dock.setDockOffsetRight(drag.startOffset - (e.clientX - drag.startX), min, max);
+  }, [dock, slideBounds]);
+  const onHeaderUp = useCallback((e: React.PointerEvent<HTMLElement>) => {
+    slideRef.current = null;
+    setDragging(false);
+    try { (e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId); } catch { /* already released */ }
+  }, []);
+
+  // A drag handle nobody can reach with a keyboard is a control only half the sellers have.
+  const onHandleKey = useCallback((e: React.KeyboardEvent) => {
+    const step = e.shiftKey ? 96 : 32;
+    const max = clampDockHeight(Number.MAX_SAFE_INTEGER, window.innerHeight);
+    if (e.key === "ArrowUp") { e.preventDefault(); dock.setDockHeight(dock.dockHeight + step); }
+    else if (e.key === "ArrowDown") { e.preventDefault(); dock.setDockHeight(dock.dockHeight - step); }
+    // Sideways from the same handle, so moving the popup is not mouse-only.
+    else if (e.key === "ArrowLeft") { const { min, max } = slideBounds(); e.preventDefault(); dock.setDockOffsetRight(dock.dockOffsetRight + step, min, max); }
+    else if (e.key === "ArrowRight") { const { min, max } = slideBounds(); e.preventDefault(); dock.setDockOffsetRight(dock.dockOffsetRight - step, min, max); }
+    else if (e.key === "Home") { e.preventDefault(); dock.setDockHeight(max); }
+    else if (e.key === "End") { e.preventDefault(); dock.setDockHeight(DOCK_MIN_HEIGHT); }
+  }, [dock, slideBounds]);
+
+  if (!dock.mounted) return null;
+
+  const mode = dock.presentation;
+  const isDock = mode === "dock";
+  // Announced on the grip. Read at render (not in the key handler) so assistive tech is told the
+  // real ceiling for this window, which changes when the window does.
+  const maxDockHeight = clampDockHeight(Number.MAX_SAFE_INTEGER, typeof window === "undefined" ? 900 : window.innerHeight);
+  const statusText = dock.busy ? L.working : dock.unread ? L.done : L.ready;
+  // Full screen is the assistant's own page and has no tab strip; the second tab lives in the popup.
+  const secondVisible = isDock && !!secondTab && view === "secondary";
+  const secondBadge = secondTab?.badge || 0;
+
+  return (
+    <div
+      ref={shellRef}
+      className={`gb-dock ${MODE_CLASS[mode]}${dragging ? " gb-dock-dragging" : ""}`}
+      style={isDock ? { height: dock.dockHeight, right: dock.dockOffsetRight } : undefined}
+      role={mode === "hidden" ? undefined : "region"}
+      aria-label={mode === "hidden" ? undefined : title}
+    >
+      {mode === "full" ? (
+        <div className="gb-dock-fullchrome">
+          {fullActions}
+          <button type="button" className="gb-dock-shrink" onClick={onShrink}>
+            {/* Two arrows pulled INTO the centre. The first attempt drew two corner brackets, which at 16px
+                reads as a plus sign — the opposite of "make this smaller". */}
+            <svg viewBox="0 0 20 20" aria-hidden>
+              <path d="M16 4l-5 5M11 9h3.5M11 9V5.5M4 16l5-5M9 11H5.5M9 11v3.5" stroke="currentColor" strokeWidth="1.6" fill="none" strokeLinecap="round" strokeLinejoin="round"/>
+            </svg>
+            <span>{L.shrinkToPopup}</span>
+          </button>
+        </div>
+      ) : null}
+
+      {mode === "mini" ? (
+        <div className="gb-dock-minirow">
+          <button type="button" className="gb-dock-minibar" onClick={dock.openDock} aria-label={L.reopen.replace("{title}", title)}>
+            <span className={`gb-dock-dot${dock.busy ? " gb-dock-dot-busy" : dock.unread ? " gb-dock-dot-unread" : ""}`} aria-hidden />
+            <strong>{title}</strong>
+            <span className="gb-dock-ministatus">
+              {dock.busy && runStartedAt ? `${L.working} · ${elapsed(runStartedAt)}` : dock.unread ? L.answerWaiting : miniHint || L.askAboutScreen}
+            </span>
+            <span className="gb-dock-minichevron" aria-hidden>▲</span>
+          </button>
+          {/* A bar that follows you onto every screen has to be closable from the bar itself. While a
+              run is live `dismiss` opens it instead — see ./dock. */}
+          <button
+            type="button"
+            className="gb-dock-icon"
+            onClick={dock.dismiss}
+            title={dock.busy ? L.openInsteadTitle : L.hideTitle}
+          >
+            <svg viewBox="0 0 20 20" aria-hidden><path d="M6 6l8 8M14 6l-8 8" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round"/></svg>
+            {/* The NAME follows the behaviour: while a run is live this button opens the popup rather
+                than hiding it, and `title` is not the accessible name. */}
+            <span className="gb-dock-sr">{dock.busy ? L.openInstead : L.hide}</span>
+          </button>
+        </div>
+      ) : null}
+
+      {isDock ? (
+        <>
+          <div
+            className="gb-dock-grip"
+            role="separator"
+            aria-orientation="horizontal"
+            aria-label={L.grip}
+            aria-valuenow={dock.dockHeight}
+            aria-valuemin={DOCK_MIN_HEIGHT}
+            aria-valuemax={maxDockHeight}
+            tabIndex={0}
+            onPointerDown={onHandleDown}
+            onPointerMove={onHandleMove}
+            onPointerUp={onHandleUp}
+            onPointerCancel={onHandleUp}
+            onKeyDown={onHandleKey}
+          >
+            <span aria-hidden />
+          </div>
+          <header
+            className="gb-dock-header"
+            onPointerDown={onHeaderDown}
+            onPointerMove={onHeaderMove}
+            onPointerUp={onHeaderUp}
+            onPointerCancel={onHeaderUp}
+            title={L.headerTitle}
+          >
+            <span className={`gb-dock-dot${dock.busy ? " gb-dock-dot-busy" : ""}`} aria-hidden />
+            <span className="gb-dock-title">{title}</span>
+            <span className="gb-dock-status">{statusText}</span>
+            <div className="gb-dock-actions">
+              {onNewChat ? (
+                <button
+                  type="button"
+                  className="gb-dock-icon gb-dock-action"
+                  title={L.newChat}
+                  onClick={onNewChat}
+                >
+                  <svg viewBox="0 0 20 20" aria-hidden><path d="M10 4.5v11M4.5 10h11" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round"/></svg>
+                  <span className="gb-dock-sr">{L.newChat}</span>
+                </button>
+              ) : null}
+              <button
+                type="button"
+                className="gb-dock-icon"
+                title={L.openFull}
+                onClick={onExpand}
+              >
+                {/* The exact mirror of "Shrink to popup": same top-right ↔ bottom-left axis, arrows
+                    pointing OUT instead of in. */}
+                <svg viewBox="0 0 20 20" aria-hidden>
+                  <path d="M11 9l5-5M16 4h-3.5M16 4v3.5M9 11l-5 5M4 16h3.5M4 16v-3.5" stroke="currentColor" strokeWidth="1.6" fill="none" strokeLinecap="round" strokeLinejoin="round"/>
+                </svg>
+                <span className="gb-dock-sr">{L.openFull}</span>
+              </button>
+              <button type="button" className="gb-dock-icon" title={L.minimizeTitle} onClick={dock.minimize}>
+                <svg viewBox="0 0 20 20" aria-hidden><path d="M5 13h10" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round"/></svg>
+                <span className="gb-dock-sr">{L.minimize}</span>
+              </button>
+              <button
+                type="button"
+                className="gb-dock-icon"
+                title={dock.busy ? L.closeBusyTitle : L.close}
+                onClick={dock.dismiss}
+              >
+                <svg viewBox="0 0 20 20" aria-hidden><path d="M6 6l8 8M14 6l-8 8" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round"/></svg>
+                <span className="gb-dock-sr">{dock.busy ? L.closeBusy : L.close}</span>
+              </button>
+            </div>
+          </header>
+          {secondTab ? (
+            <div className="gb-dock-tabs" role="tablist" aria-label={L.tablist}>
+              <button
+                type="button"
+                role="tab"
+                id="gem-dock-tab-assistant"
+                aria-controls="gem-dock-pane-assistant"
+                aria-selected={view === "primary"}
+                className="gb-dock-tab"
+                onClick={() => onViewChange?.("primary")}
+              >
+                {L.primaryTab}
+              </button>
+              <button
+                type="button"
+                role="tab"
+                id="gem-dock-tab-support"
+                aria-controls="gem-dock-pane-support"
+                aria-selected={view === "secondary"}
+                className="gb-dock-tab"
+                onClick={() => onViewChange?.("secondary")}
+              >
+                {secondTab.label}
+                {secondBadge && view !== "secondary" ? (
+                  <span className="gb-dock-badge" aria-label={`${secondBadge} unread`}>{secondBadge}</span>
+                ) : null}
+              </button>
+            </div>
+          ) : null}
+        </>
+      ) : null}
+
+      <div className="gb-dock-body">
+        <div className="gb-dock-pane" id="gem-dock-pane-assistant" role={isDock && secondTab ? "tabpanel" : undefined} aria-labelledby={isDock && secondTab ? "gem-dock-tab-assistant" : undefined} hidden={secondVisible}>
+          {children}
+        </div>
+        {secondTab?.content ? (
+          <div className="gb-dock-pane" id="gem-dock-pane-support" role="tabpanel" aria-labelledby="gem-dock-tab-support" hidden={!secondVisible}>
+            {secondTab.content}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/src/assistant/index.ts

@@ -0,0 +1,6 @@
+// The assistant's frame: popup, status bar, full screen — and the rules for when each shows.
+// A separate entry from the shell/auth barrel so a surface that never opens an assistant pays nothing for it.
+export { AssistantHost, type AssistantHostLabels, type AssistantSecondTab } from "./host";
+export { AssistantProvider, useAssistant, useAssistantPageFacts, type AssistantDockApi, type AssistantOptions } from "./provider";
+export * from "./dock";
+export { AssistantWorkspaceLayout, OpenChatTabs, SessionRail, SESSION_RAIL_EN, groupSessions, normalizeForSearch, relativeTime, type AssistantSession, type SessionGroup, type SessionRailIcons, type SessionRailLabels } from "./sessions";

package/src/assistant/provider.tsx

@@ -0,0 +1,269 @@
+"use client";
+
+/**
+ * WHERE the assistant is drawn, held above the routes so switching screens cannot unmount it —
+ * @gemboss/ui (28/09/2026), moved from gemboss apps/admin/src/contexts/AssistantDockContext.tsx.
+ *
+ * The admin's names are the defaults. A surface with its own routing passes `options`:
+ *   - `storagePrefix` — where the popup's height, offset and last shape are remembered
+ *   - `isFullLink` / `isOnFullPage` — which link opens the assistant full screen, and whether that is
+ *     the screen we are on (the admin: the path `/app/assistant`; a hash-routed SPA: `#/assistant`)
+ *   - `dockedEvent` — announced when a rail click opened the popup instead of the full screen, so the
+ *     shell can close its mobile drawer
+ *   - `bodyClassPrefix` — `<prefix>-busy` / `<prefix>-unread` on <body>, which the rail item reads
+ */
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useReducer, useRef, useState, type ReactNode } from "react";
+import {
+  assistantDockReducer,
+  initialAssistantDockState,
+  DOCK_DEFAULT_HEIGHT,
+  DOCK_DEFAULT_OFFSET_RIGHT,
+  type AssistantDockState,
+} from "./dock";
+
+export interface AssistantOptions {
+  storagePrefix?: string;
+  isFullLink?: (url: URL) => boolean;
+  isOnFullPage?: () => boolean;
+  dockedEvent?: string;
+  bodyClassPrefix?: string;
+}
+
+/** Storage keys. `lastMode` is the last shape the seller actually used: "full" or "dock" — nothing
+ *  else is worth reopening as. Module-level so the callbacks below stay identity-stable. */
+const storageKey = (prefix: string, k: "dockHeight" | "dockOffsetRight" | "lastMode") => `${prefix}.${k}`;
+
+const ADMIN_FULL_PATH = "/app/assistant";
+const DEFAULTS: Required<AssistantOptions> = {
+  storagePrefix: "gemboss.assistant",
+  isFullLink: (url) => url.pathname === ADMIN_FULL_PATH,
+  isOnFullPage: () => window.location.pathname.startsWith(ADMIN_FULL_PATH),
+  dockedEvent: "gemboss:assistant-docked",
+  bodyClassPrefix: "gemboss-assistant",
+};
+
+export interface AssistantDockApi extends AssistantDockState {
+  /** Specifics the CURRENT screen registered about itself, for the assistant to read. */
+  pageFacts: string[];
+  /** Screens call this through `useAssistantPageFacts`; the last screen to mount wins. */
+  publishPageFacts: (owner: string, facts: string[]) => void;
+  retractPageFacts: (owner: string) => void;
+  /** The /app/assistant route claims full mode on mount and releases it on unmount. */
+  enterFull: () => void;
+  leaveFull: () => void;
+  openDock: () => void;
+  minimize: () => void;
+  dismiss: () => void;
+  setBusy: (busy: boolean) => void;
+  setDockHeight: (height: number) => void;
+  /** Slide the popup along the bottom. `min`/`max` come from the caller, which is the only place
+   *  that knows how wide the popup is and where the rail ends. */
+  setDockOffsetRight: (offsetRight: number, min: number, max: number) => void;
+}
+
+const Ctx = createContext<AssistantDockApi | null>(null);
+
+/**
+ * Holds WHERE the assistant is drawn, above the routes, so switching menus cannot unmount it.
+ * See `./dock.ts` for the transition rules and why they exist.
+ */
+export function AssistantProvider({ options, children }: { options?: AssistantOptions; children: ReactNode }) {
+  const [state, dispatch] = useReducer(assistantDockReducer, initialAssistantDockState);
+  // Read through a ref: the options object is usually built inline, and the effects below must not
+  // re-subscribe (or re-read storage) every render because of it.
+  const opts = useRef<Required<AssistantOptions>>({ ...DEFAULTS, ...options });
+  opts.current = { ...DEFAULTS, ...options };
+
+  // Facts about the screen the seller is on, published by that screen. Keyed by owner so a screen
+  // unmounting cannot wipe facts the NEXT screen already published — during a route change both are
+  // briefly alive, and a blind "clear on unmount" would leave the assistant reading an empty screen.
+  const factsOwner = useRef<string>("");
+  const [pageFacts, setPageFacts] = useState<string[]>([]);
+  const publishPageFacts = useCallback((owner: string, facts: string[]) => {
+    factsOwner.current = owner;
+    setPageFacts(facts);
+  }, []);
+  const retractPageFacts = useCallback((owner: string) => {
+    if (factsOwner.current !== owner) return;
+    factsOwner.current = "";
+    setPageFacts([]);
+  }, []);
+
+  // Restore the seller's popup size + pin after mount (localStorage is unavailable during SSR).
+  useEffect(() => {
+    try {
+      const raw = Number(window.localStorage.getItem(storageKey(opts.current.storagePrefix, "dockHeight")));
+      const height = Number.isFinite(raw) && raw > 0 ? raw : DOCK_DEFAULT_HEIGHT;
+      requestedHeight.current = height;
+      dispatch({ type: "resize", height, 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"));
+      const rawOffset = Number(storedOffset);
+      if (storedOffset !== null && storedOffset !== "" && Number.isFinite(rawOffset) && rawOffset >= 0) {
+        requestedOffset.current = rawOffset;
+        // Clamped against THIS window, not the one it was saved in. A value from a 27" screen would
+        // otherwise put the popup on the rail — or off the left edge — on a laptop.
+        dispatch({ type: "slide", offsetRight: rawOffset, ...offsetBounds() });
+      }
+    } catch { /* private mode — defaults are fine */ }
+  }, []);
+
+  /**
+   * What the seller ASKED for, which is not what the popup currently measures.
+   *
+   * The resize listener used to re-dispatch `state.dockHeight` — already clamped — so shrinking the
+   * 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);
+  /** Same reasoning as `requestedHeight`: persist what the seller ASKED for, clamp only to draw. */
+  const requestedOffset = useRef(DOCK_DEFAULT_OFFSET_RIGHT);
+
+  /**
+   * How far the popup may travel in THIS window.
+   *
+   * Kept here as well as in the host because the restore and the resize listener both need it before
+   * the host exists — and a bound taken from the window that SAVED the value is not a bound at all.
+   * Measured from `main`, the content area the popup floats over, so one rect decides both edges.
+   */
+  const offsetBounds = useCallback(() => {
+    if (typeof window === "undefined") return { min: 8, max: 8 };
+    const main = document.querySelector(".gemboss-platform-main")?.getBoundingClientRect();
+    const track = main ? main.width : (document.documentElement.clientWidth || window.innerWidth);
+    // The popup's own width is not knowable here (it may not be mounted); its CSS cap is.
+    const popup = Math.min(460, Math.max(0, track - 48));
+    return { min: 8, max: Math.max(8, Math.floor(track - popup - 8)) };
+  }, []);
+
+  // A window that got shorter must not leave the popup taller than the screen — and a window that
+  // got taller again must give the seller their height back.
+  useEffect(() => {
+    const onResize = () => {
+      dispatch({ type: "resize", height: requestedHeight.current, 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() });
+    };
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, []);
+
+  const setDockHeight = useCallback((height: number) => {
+    const viewport = typeof window === "undefined" ? 900 : window.innerHeight;
+    requestedHeight.current = 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 */ }
+  }, []);
+
+  const setDockOffsetRight = useCallback((offsetRight: number, min: number, max: number) => {
+    requestedOffset.current = Math.round(offsetRight);
+    dispatch({ type: "slide", offsetRight, min, max });
+    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "dockOffsetRight"), String(Math.round(offsetRight))); } catch { /* best-effort */ }
+  }, []);
+
+  /**
+   * Remember which shape the seller last used, and reopen in it.
+   *
+   * The rail's Assistant item is a link to /app/assistant, so it always opened FULL — even for
+   * someone who had been working in the popup all morning and closed it. Chris: "nếu đang ở popup mà
+   * tắt đi, lần sau bấm vào menu assistant thì nó cũng nên là popup".
+   *
+   * Only `full` and `dock` 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(() => {
+    if (state.presentation !== "full" && state.presentation !== "dock") return;
+    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "lastMode"), state.presentation); } catch { /* best-effort */ }
+  }, [state.presentation]);
+
+  /**
+   * Intercept the rail's Assistant link when the popup is what they last used.
+   *
+   * Capture phase and on `document`, because the link lives in `IconNav` — a component this provider
+   * does not own and should not have to. A plain left-click only: ⌘-click, middle-click and a
+   * keyboard-modified click still open the page, because those mean "somewhere else", not "here".
+   */
+  useEffect(() => {
+    const onClick = (e: MouseEvent) => {
+      if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      const anchor = (e.target as HTMLElement | null)?.closest?.("a") as HTMLAnchorElement | null;
+      if (!anchor || anchor.target === "_blank") return;
+      let url: URL;
+      try { url = new URL(anchor.href, window.location.origin); } catch { return; }
+      if (!opts.current.isFullLink(url)) return;
+      // Already on the page it points at — let the click be the no-op it already is.
+      if (opts.current.isOnFullPage()) return;
+      let last = "";
+      try { last = window.localStorage.getItem(storageKey(opts.current.storagePrefix, "lastMode")) ?? ""; } catch { /* private mode */ }
+      if (last !== "dock") return;
+      e.preventDefault();
+      e.stopPropagation();
+      dispatch({ type: "dock" });
+      // 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
+      // instead of reaching into the shell's state.
+      window.dispatchEvent(new CustomEvent(opts.current.dockedEvent));
+    };
+    document.addEventListener("click", onClick, true);
+    return () => document.removeEventListener("click", onClick, true);
+  }, []);
+
+  // The rail's assistant icon shows a working dot without re-rendering IconNav (it is memoized and
+  // re-rendering the whole nav on every busy flip would cost more than the dot is worth).
+  useEffect(() => {
+    const p = opts.current.bodyClassPrefix;
+    document.body.classList.toggle(`${p}-busy`, state.busy);
+    document.body.classList.toggle(`${p}-unread`, state.unread && !state.busy);
+    return () => {
+      document.body.classList.remove(`${p}-busy`, `${p}-unread`);
+    };
+  }, [state.busy, state.unread]);
+
+  // Every action is identity-STABLE (dispatch is). Children register these as callbacks and one of
+  // them — the chat's busy reporter — is read in an unmount cleanup, where a changing identity would
+  // 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 minimize = useCallback(() => dispatch({ type: "minimize" }), []);
+  const dismiss = useCallback(() => dispatch({ type: "dismiss" }), []);
+  const setBusy = useCallback((busy: boolean) => dispatch({ type: "busy", busy }), []);
+
+  const api = useMemo<AssistantDockApi>(() => ({
+    ...state,
+    pageFacts, publishPageFacts, retractPageFacts,
+    enterFull, leaveFull, openDock, minimize, dismiss, setBusy, setDockHeight, setDockOffsetRight,
+  }), [state, pageFacts, publishPageFacts, retractPageFacts, enterFull, leaveFull, openDock, minimize, dismiss, setBusy, setDockHeight, setDockOffsetRight]);
+
+  return <Ctx.Provider value={api}>{children}</Ctx.Provider>;
+}
+
+export function useAssistant(): AssistantDockApi {
+  const ctx = useContext(Ctx);
+  if (!ctx) throw new Error("useAssistant must be used inside <AssistantProvider>");
+  return ctx;
+}
+
+/**
+ * A screen tells the assistant what is on it.
+ *
+ * Route-level context ("they are on Plugins") is free and automatic; this is for the part only the
+ * screen knows — which plugins are on, which page is open, what step the build is at. Pass a stable
+ * `owner` (the screen's name) and plain sentences a person would say.
+ *
+ * The facts are STRINGS on purpose: they end up in a prompt, and a shape nobody can read at the call
+ * site is a shape that drifts into nonsense without anyone noticing.
+ */
+export function useAssistantPageFacts(owner: string, facts: string[]): void {
+  const { publishPageFacts, retractPageFacts } = useAssistant();
+  // Compare by value: callers build this array inline, so a reference check would republish every render.
+  const key = facts.join("\u0000");
+  useEffect(() => {
+    publishPageFacts(owner, key ? key.split("\u0000") : []);
+    return () => retractPageFacts(owner);
+  }, [owner, key, publishPageFacts, retractPageFacts]);
+}