@gemboss/ui 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemboss/ui",
-  "version": "0.2.1",
+  "version": "0.3.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",
@@ -17,8 +17,11 @@
     "./gemboss-field.css": "./src/gemboss-field.css",
     "./app-shell.css": "./src/app-shell.css",
     "./shell.css": "./src/shell.css",
+    "./chat.css": "./src/chat.css",
+    "./chat-composer.css": "./src/chat-composer.css",
     "./auth.css": "./src/auth.css",
     "./kit-plain.css": "./src/kit-plain.css",
+    "./kit-plain.js": "./src/kit-plain.js",
     "./assistant": "./src/assistant/index.ts",
     "./assistant/dock": "./src/assistant/dock.ts",
     "./assistant.css": "./src/assistant.css"
@@ -27,6 +30,7 @@
     "src/**/*.ts",
     "src/**/*.tsx",
     "src/*.css",
+    "src/kit-plain.js",
     "!src/**/*.test.*",
     "gemboss-ui.css",
     "catalog/index.html",

package/src/assistant/dock.ts

@@ -16,8 +16,17 @@
  * being spread over three components' effects.
  */
 
-/** Where the assistant is drawn. `hidden` still means MOUNTED — the run keeps going. */
-export type AssistantPresentation = "hidden" | "mini" | "dock" | "full";
+/**
+ * Where the assistant is drawn. `hidden` still means MOUNTED — the run keeps going.
+ *
+ * `side` (01/10/2026): a full-height panel on the right, under the topbar, that the page makes room for instead of
+ * being covered by. Chris asked for one set of shapes across every surface's assistant — "full height right sidebar,
+ * popup, full width height" — and content-radar / partner-radar / GemCommunity each built their own right-side panel.
+ * A surface opts in (`AssistantHost allowSide`); without it nothing here ever produces `side`.
+ */
+export type AssistantPresentation = "hidden" | "mini" | "dock" | "side" | "full";
+/** The two shapes a seller WORKS in on top of a screen. The status bar reopens into whichever they last used. */
+export type AssistantFloatShape = "dock" | "side";
 
 export interface AssistantDockState {
   presentation: AssistantPresentation;
@@ -35,6 +44,21 @@ export interface AssistantDockState {
   /** Bumped every time the assistant is brought back on screen. Lets a mount that already exists
    *  pick up a question handed over from ⌘K, which a mount-time read would only ever see once. */
   openNonce: number;
+  /** Width of the `side` panel in px (seller-resizable, persisted). */
+  sideWidth: number;
+  /**
+   * The last shape the seller worked in over a screen. The status bar's "reopen", × on a busy bar and leaving full
+   * screen mid-run all go back to it — a seller who keeps the assistant pinned to the side must not have it pop back
+   * as a floating window every time it comes back.
+   */
+  floatShape: AssistantFloatShape;
+  /**
+   * Whether the mounted host offers the side panel (`AssistantHost allowSide`, registered on mount). Every way INTO
+   * `side` goes through it — the pin, the status bar, a busy ×, leaving full, a stored "last used" — so a surface
+   * that has not laid out for the panel never meets it, whatever is in storage from another surface or an older
+   * build. Review of #(this PR): the rail link dispatched a stored "side" straight past the host's opt-in.
+   */
+  sideAllowed: boolean;
 }
 
 export type AssistantDockEvent =
@@ -48,6 +72,16 @@ export type AssistantDockEvent =
   | { type: "minimize" }
   /** the popup's × */
   | { type: "dismiss" }
+  /** pin to the side panel (only surfaces that allow it send this) */
+  | { type: "side" }
+  /** bring it back in the last working shape (`floatShape`) — the status bar's click */
+  | { type: "reopen" }
+  /** `available` = the width of the content area the panel sits in (window minus the rail) */
+  | { type: "side-resize"; width: number; available: number }
+  /** the host says whether it offers the side panel */
+  | { type: "side-allowed"; allowed: boolean }
+  /** the last working shape, read back from storage on load */
+  | { type: "restore-float"; shape: AssistantFloatShape }
   | { type: "busy"; busy: boolean }
   | { type: "resize"; height: number; viewport: number }
   | { type: "slide"; offsetRight: number; min: number; max: number };
@@ -68,6 +102,24 @@ export const DOCK_VIEWPORT_RESERVE = DOCK_TOPBAR_HEIGHT + DOCK_TOPBAR_GAP;
 /** Matches the CSS `right: 24px` the popup starts at. */
 export const DOCK_DEFAULT_OFFSET_RIGHT = 24;
 
+/** The side panel: narrow enough to leave the page usable, wide enough for a chat with a table in it. */
+// 380, not 320 (02/10/2026, measured on admin.gemboss.ai): the header's fixed parts — padding, dot, gaps, five
+// 44px controls — take 280px, so at 320 the title got 40px ("G…") and at 400 with the status word it got 74 of 90.
+// 380 leaves 100px for a title, with the status word standing down in the panel (assistant.css).
+export const SIDE_MIN_WIDTH = 380;
+export const SIDE_DEFAULT_WIDTH = 400;
+export const SIDE_MAX_WIDTH = 720;
+/** The page beside the panel never gets narrower than this — a cap only exists when it is smaller than the room
+ *  there really is (§9.1), so the ceiling is taken from the content area, not from SIDE_MAX_WIDTH alone. */
+export const SIDE_PAGE_MIN = 480;
+
+export function clampSideWidth(width: number, available: number): number {
+  const max = Number.isFinite(available) && available > 0
+    ? Math.max(SIDE_MIN_WIDTH, Math.min(SIDE_MAX_WIDTH, available - SIDE_PAGE_MIN))
+    : SIDE_MAX_WIDTH;   // not measured yet (SSR, first paint): the plain cap, never a guessed-narrow one
+  return Math.min(Math.max(Math.round(width), SIDE_MIN_WIDTH), max);
+}
+
 /** Keep the popup inside the usable area: never under the rail, never off the right edge. */
 export function clampDockOffset(offsetRight: number, min: number, max: number): number {
   if (max < min) return min;
@@ -87,8 +139,16 @@ export const initialAssistantDockState: AssistantDockState = {
   dockHeight: DOCK_DEFAULT_HEIGHT,
   dockOffsetRight: DOCK_DEFAULT_OFFSET_RIGHT,
   openNonce: 0,
+  sideWidth: SIDE_DEFAULT_WIDTH,
+  floatShape: "dock",
+  sideAllowed: false,
 };
 
+/** The shape to come back to: the last one worked in, unless this host does not offer the side panel. */
+function backTo(state: AssistantDockState): AssistantFloatShape {
+  return state.sideAllowed ? state.floatShape : "dock";
+}
+
 export function assistantDockReducer(state: AssistantDockState, event: AssistantDockEvent): AssistantDockState {
   switch (event.type) {
     case "enter-full":
@@ -107,10 +167,25 @@ export function assistantDockReducer(state: AssistantDockState, event: Assistant
       // There used to be a `pinned` flag here, and a 📌 in the header to set it. Two later changes
       // ate its job: the bar already follows the seller, and the shell now reopens in whichever
       // shape they last used. A control that no longer decides anything is worse than no control.
-      return { ...state, presentation: state.busy ? "dock" : "mini" };
+      return { ...state, presentation: state.busy ? backTo(state) : "mini" };
 
     case "dock":
-      return { ...state, presentation: "dock", mounted: true, unread: false, openNonce: state.openNonce + 1 };
+      return { ...state, presentation: "dock", floatShape: "dock", mounted: true, unread: false, openNonce: state.openNonce + 1 };
+
+    case "side":
+      if (!state.sideAllowed) return { ...state, presentation: "dock", floatShape: "dock", mounted: true, unread: false, openNonce: state.openNonce + 1 };
+      return { ...state, presentation: "side", floatShape: "side", mounted: true, unread: false, openNonce: state.openNonce + 1 };
+
+    case "reopen":
+      return { ...state, presentation: backTo(state), mounted: true, unread: false, openNonce: state.openNonce + 1 };
+
+    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 };
+
+    case "restore-float":
+      return { ...state, floatShape: event.shape };
 
     case "minimize":
       return { ...state, presentation: "mini" };
@@ -122,7 +197,7 @@ export function assistantDockReducer(state: AssistantDockState, event: Assistant
       // Pressing it AGAIN on that bar opens the popup rather than doing nothing twice — a button that
       // visibly changes nothing is read as broken.
       if (!state.busy) return { ...state, presentation: "hidden" };
-      return { ...state, presentation: state.presentation === "mini" ? "dock" : "mini" };
+      return { ...state, presentation: state.presentation === "mini" ? backTo(state) : "mini" };
 
     case "busy": {
       if (event.busy === state.busy) return state;
@@ -136,6 +211,9 @@ export function assistantDockReducer(state: AssistantDockState, event: Assistant
     case "slide":
       return { ...state, dockOffsetRight: clampDockOffset(event.offsetRight, event.min, event.max) };
 
+    case "side-resize":
+      return { ...state, sideWidth: clampSideWidth(event.width, event.available) };
+
     default:
       return state;
   }

package/src/assistant/host.tsx

@@ -14,12 +14,13 @@
  */
 import React, { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
 
-import { DOCK_MIN_HEIGHT, clampDockHeight } from "./dock";
-import { useAssistant } from "./provider";
+import { DOCK_MIN_HEIGHT, SIDE_MIN_WIDTH, clampDockHeight, clampSideWidth } from "./dock";
+import { sideAvailable, 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;
+const MODE_CLASS = { hidden: "gb-dock-hidden", mini: "gb-dock-mini", dock: "gb-dock-dock", side: "gb-dock-side", 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 {
@@ -36,6 +37,7 @@ export interface AssistantHostLabels {
   newChat: string; openFull: string; minimize: string; minimizeTitle: string;
   close: string; closeBusy: string; closeBusyTitle: string;
   shrinkToPopup: string; tablist: string; primaryTab: string;
+  pinSide: string; floatPopup: string; sideGrip: string; backToSide: string;
 }
 const EN: AssistantHostLabels = {
   ready: "Ready", working: "Working", done: "Done — tap to see it",
@@ -47,6 +49,8 @@ const EN: AssistantHostLabels = {
   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",
+  pinSide: "Pin to the side", floatPopup: "Float as a popup", sideGrip: "Drag to resize the assistant; left and right arrows work too",
+  backToSide: "Back to the side panel",
 };
 
 /** An optional second tab in the popup (the admin: a person on the Gem team, through gemcare). */
@@ -60,7 +64,7 @@ export interface AssistantSecondTab {
 
 export function AssistantHost({
   title, labels, onNewChat, onExpand, onShrink, fullActions, secondTab, view = "primary", onViewChange,
-  miniHint, children,
+  miniHint, allowSide = false, children,
 }: {
   /** "Gem assistant" in the admin. Names the region, the popup header and the status bar. */
   title: string;
@@ -79,6 +83,12 @@ export function AssistantHost({
   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;
+  /**
+   * 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.
+   */
+  allowSide?: boolean;
   children?: ReactNode;
 }) {
   const dock = useAssistant();
@@ -181,6 +191,47 @@ export function AssistantHost({
     try { (e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId); } catch { /* already released */ }
   }, []);
 
+  // The provider gates every way into the side panel on this, so a host that never offers it never draws it.
+  const { setSideAllowed } = dock;
+  useEffect(() => { setSideAllowed(allowSide); }, [allowSide, 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
+  // panel. Pointer capture keeps the drag on the seam; `ui-resizing` on <body> gives the col-resize cursor and the
+  // shield over iframes that every other seam in the fleet shows.
+  const sideDragRef = useRef<{ startX: number; startW: number; id: number } | null>(null);
+  const endSideDrag = useCallback((e?: React.PointerEvent<HTMLDivElement>) => {
+    sideDragRef.current = null;
+    setDragging(false);
+    document.body.classList.remove("ui-resizing");
+    if (e) { try { (e.currentTarget as HTMLElement).releasePointerCapture(e.pointerId); } catch { /* already released */ } }
+  }, []);
+  const onSideGripDown = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    if (e.button !== 0 || (e.pointerType === "mouse" && e.ctrlKey)) return;
+    e.preventDefault();
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    setDragging(true);
+    document.body.classList.add("ui-resizing");
+    sideDragRef.current = { startX: e.clientX, startW: dock.sideWidth, id: e.pointerId };
+  }, [dock.sideWidth]);
+  const onSideGripMove = useCallback((e: React.PointerEvent<HTMLDivElement>) => {
+    const drag = sideDragRef.current;
+    if (!drag || e.pointerId !== drag.id) return;
+    // A lost release (a context menu took it) leaves a mouse with no button down: treat it as the release.
+    if (e.pointerType === "mouse" && e.buttons === 0) { endSideDrag(e); return; }
+    dock.setSideWidth(drag.startW + (drag.startX - e.clientX));
+  }, [dock, endSideDrag]);
+  const onSideGripKey = useCallback((e: React.KeyboardEvent) => {
+    if (e.altKey || e.metaKey || e.ctrlKey) return;   // Back / Forward belong to the browser
+    const step = e.shiftKey ? 64 : 16;
+    if (e.key === "ArrowLeft") { e.preventDefault(); dock.setSideWidth(dock.sideWidth + step); }
+    else if (e.key === "ArrowRight") { e.preventDefault(); dock.setSideWidth(dock.sideWidth - step); }
+    else if (e.key === "Home") { e.preventDefault(); dock.setSideWidth(SIDE_MIN_WIDTH); }
+    else if (e.key === "End") { e.preventDefault(); dock.setSideWidth(Number.MAX_SAFE_INTEGER); }
+  }, [dock]);
+  // A drag that is still running when the panel goes away must not leave the shield over the page.
+  useEffect(() => { if (dock.presentation !== "side" && sideDragRef.current) endSideDrag(); }, [dock.presentation, endSideDrag]);
+
   // 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;
@@ -198,19 +249,24 @@ export function AssistantHost({
 
   const mode = dock.presentation;
   const isDock = mode === "dock";
+  const isSide = mode === "side";
+  /** The two working shapes over a screen share the header, the tabs and the body. */
+  const isPanel = isDock || isSide;
+  const maxSideWidth = clampSideWidth(Number.MAX_SAFE_INTEGER, sideAvailable());
   // 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 secondVisible = isPanel && !!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}
+      style={isDock ? { height: dock.dockHeight, right: dock.dockOffsetRight }
+        : isSide ? ({ "--gb-dock-side-w": `${dock.sideWidth}px` } as React.CSSProperties) : undefined}
       role={mode === "hidden" ? undefined : "region"}
       aria-label={mode === "hidden" ? undefined : title}
     >
@@ -223,14 +279,14 @@ export function AssistantHost({
             <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>
+            <span>{dock.sideAllowed && dock.floatShape === "side" ? L.backToSide : 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)}>
+          <button type="button" className="gb-dock-minibar" onClick={dock.reopen} 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">
@@ -254,9 +310,28 @@ export function AssistantHost({
         </div>
       ) : null}
 
-      {isDock ? (
+      {isSide ? (
+        <div
+          className="ui-resizer gb-dock-sidegrip"
+          role="separator"
+          aria-orientation="vertical"
+          aria-label={L.sideGrip}
+          aria-valuenow={dock.sideWidth}
+          aria-valuemin={SIDE_MIN_WIDTH}
+          aria-valuemax={maxSideWidth}
+          tabIndex={0}
+          onPointerDown={onSideGripDown}
+          onPointerMove={onSideGripMove}
+          onPointerUp={endSideDrag}
+          onPointerCancel={endSideDrag}
+          onLostPointerCapture={() => { if (sideDragRef.current) endSideDrag(); }}
+          onKeyDown={onSideGripKey}
+        />
+      ) : null}
+
+      {isPanel ? (
         <>
-          <div
+          {isDock ? <div
             className="gb-dock-grip"
             role="separator"
             aria-orientation="horizontal"
@@ -272,14 +347,14 @@ export function AssistantHost({
             onKeyDown={onHandleKey}
           >
             <span aria-hidden />
-          </div>
+          </div> : null}
           <header
             className="gb-dock-header"
-            onPointerDown={onHeaderDown}
-            onPointerMove={onHeaderMove}
-            onPointerUp={onHeaderUp}
-            onPointerCancel={onHeaderUp}
-            title={L.headerTitle}
+            onPointerDown={isDock ? onHeaderDown : undefined}
+            onPointerMove={isDock ? onHeaderMove : undefined}
+            onPointerUp={isDock ? onHeaderUp : undefined}
+            onPointerCancel={isDock ? onHeaderUp : undefined}
+            title={isDock ? L.headerTitle : undefined}
           >
             <span className={`gb-dock-dot${dock.busy ? " gb-dock-dot-busy" : ""}`} aria-hidden />
             <span className="gb-dock-title">{title}</span>
@@ -296,6 +371,27 @@ export function AssistantHost({
                   <span className="gb-dock-sr">{L.newChat}</span>
                 </button>
               ) : null}
+              {isDock && allowSide ? (
+                <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>
+                    <rect x="3.5" y="4.5" width="13" height="11" rx="1.5" stroke="currentColor" strokeWidth="1.5" fill="none"/>
+                    <path d="M12 4.5v11" stroke="currentColor" strokeWidth="1.5"/>
+                    <path d="M12.75 5.25h3v9.5h-3z" fill="currentColor"/>
+                  </svg>
+                  <span className="gb-dock-sr">{L.pinSide}</span>
+                </button>
+              ) : null}
+              {isSide ? (
+                <button type="button" className="gb-dock-icon gb-dock-action" title={L.floatPopup} onClick={dock.openDock}>
+                  {/* The same window with a small box floating in its bottom-right corner: the popup. */}
+                  <svg viewBox="0 0 20 20" aria-hidden>
+                    <rect x="3.5" y="4.5" width="13" height="11" rx="1.5" stroke="currentColor" strokeWidth="1.5" fill="none"/>
+                    <rect x="10" y="10" width="5" height="4" rx="0.75" fill="currentColor"/>
+                  </svg>
+                  <span className="gb-dock-sr">{L.floatPopup}</span>
+                </button>
+              ) : null}
               <button
                 type="button"
                 className="gb-dock-icon"
@@ -357,7 +453,7 @@ export function AssistantHost({
       ) : 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}>
+        <div className="gb-dock-pane" id="gem-dock-pane-assistant" role={isPanel && secondTab ? "tabpanel" : undefined} aria-labelledby={isPanel && secondTab ? "gem-dock-tab-assistant" : undefined} hidden={secondVisible}>
           {children}
         </div>
         {secondTab?.content ? (

package/src/assistant/index.ts

@@ -1,6 +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 { AssistantProvider, SIDE_WIDTH_VAR, 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

@@ -18,6 +18,7 @@ import {
   initialAssistantDockState,
   DOCK_DEFAULT_HEIGHT,
   DOCK_DEFAULT_OFFSET_RIGHT,
+  SIDE_DEFAULT_WIDTH,
   type AssistantDockState,
 } from "./dock";
 
@@ -29,9 +30,23 @@ export interface AssistantOptions {
   bodyClassPrefix?: string;
 }
 
-/** Storage keys. `lastMode` is the last shape the seller actually used: "full" or "dock" — nothing
+/** 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") => `${prefix}.${k}`;
+const storageKey = (prefix: string, k: "dockHeight" | "dockOffsetRight" | "lastMode" | "sideWidth" | "floatShape") => `${prefix}.${k}`;
+
+/**
+ * The width of the content area the side panel sits in: the window minus the rail. Measured from `main`'s LEFT
+ * edge (where the rail ends), never from main's width — with the panel open, main is already narrower by the panel.
+ */
+export function sideAvailable(): number {
+  if (typeof window === "undefined") return 0;
+  const left = document.querySelector(".gemboss-platform-main")?.getBoundingClientRect().left ?? 0;
+  return (document.documentElement.clientWidth || window.innerWidth) - left;
+}
+
+/** The custom property the page reads to make room for the side panel (`.gemboss-platform-main` does it itself;
+ *  a surface with its own layout reads the same variable). */
+export const SIDE_WIDTH_VAR = "--gb-assistant-side-w";
 
 const ADMIN_FULL_PATH = "/app/assistant";
 const DEFAULTS: Required<AssistantOptions> = {
@@ -52,6 +67,10 @@ export interface AssistantDockApi extends AssistantDockState {
   enterFull: () => void;
   leaveFull: () => void;
   openDock: () => void;
+  /** Pin to the full-height side panel. Only a host that allows it (`allowSide`) offers the button. */
+  openSide: () => void;
+  /** Back on screen in the last working shape — popup or side panel (`floatShape`). */
+  reopen: () => void;
   minimize: () => void;
   dismiss: () => void;
   setBusy: (busy: boolean) => void;
@@ -59,6 +78,10 @@ export interface AssistantDockApi extends AssistantDockState {
   /** 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;
+  /** Resize the side panel; clamped so the page beside it keeps SIDE_PAGE_MIN. */
+  setSideWidth: (width: number) => void;
+  /** The host registers whether it offers the side panel (`allowSide`). */
+  setSideAllowed: (allowed: boolean) => void;
 }
 
 const Ctx = createContext<AssistantDockApi | null>(null);
@@ -106,6 +129,13 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
         // otherwise put the popup on the rail — or off the left edge — on a laptop.
         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 storedSide = Number(window.localStorage.getItem(storageKey(opts.current.storagePrefix, "sideWidth")));
+      if (Number.isFinite(storedSide) && storedSide > 0) {
+        requestedSide.current = storedSide;
+        dispatch({ type: "side-resize", width: storedSide, available: sideAvailable() });
+      }
     } catch { /* private mode — defaults are fine */ }
   }, []);
 
@@ -119,6 +149,8 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
   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);
+  /** …and the same for the side panel's width: a width chosen on a 27" screen comes back there. */
+  const requestedSide = useRef(SIDE_DEFAULT_WIDTH);
 
   /**
    * How far the popup may travel in THIS window.
@@ -144,6 +176,7 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
       // …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() });
+      dispatch({ type: "side-resize", width: requestedSide.current, available: sideAvailable() });
     };
     window.addEventListener("resize", onResize);
     return () => window.removeEventListener("resize", onResize);
@@ -158,6 +191,12 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
     try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "dockHeight"), String(Math.round(height))); } catch { /* best-effort */ }
   }, []);
 
+  const setSideWidth = useCallback((width: number) => {
+    requestedSide.current = Math.round(width);
+    dispatch({ type: "side-resize", width, available: sideAvailable() });
+    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "sideWidth"), String(Math.round(width))); } catch { /* best-effort */ }
+  }, []);
+
   const setDockOffsetRight = useCallback((offsetRight: number, min: number, max: number) => {
     requestedOffset.current = Math.round(offsetRight);
     dispatch({ type: "slide", offsetRight, min, max });
@@ -171,11 +210,15 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
    * 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
+   * 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(() => {
-    if (state.presentation !== "full" && state.presentation !== "dock") return;
+    try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "floatShape"), state.floatShape); } catch { /* best-effort */ }
+  }, [state.floatShape]);
+
+  useEffect(() => {
+    if (state.presentation !== "full" && state.presentation !== "dock" && state.presentation !== "side") return;
     try { window.localStorage.setItem(storageKey(opts.current.storagePrefix, "lastMode"), state.presentation); } catch { /* best-effort */ }
   }, [state.presentation]);
 
@@ -198,10 +241,10 @@ 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") return;
+      if (last !== "dock" && last !== "side") return;
       e.preventDefault();
       e.stopPropagation();
-      dispatch({ type: "dock" });
+      dispatch({ type: last });
       // 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
@@ -223,12 +266,36 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
     };
   }, [state.busy, state.unread]);
 
+  // The page makes room for the side panel: a body class plus the panel's width as a custom property, so the shell
+  // (and any surface with its own layout) can pad its content by exactly that much instead of being covered.
+  // Entering the side panel draws it at the width the seller ASKED for, clamped to THIS window — the stored width
+  // was clamped against whatever window it was last drawn in (or never, on a first open), and a resize is the only
+  // other moment that re-clamps.
+  useEffect(() => {
+    if (state.presentation === "side") dispatch({ type: "side-resize", width: requestedSide.current, available: sideAvailable() });
+  }, [state.presentation]);
+
+  useEffect(() => {
+    const p = opts.current.bodyClassPrefix;
+    const on = state.presentation === "side";
+    document.body.classList.toggle(`${p}-side`, on);
+    if (on) document.body.style.setProperty(SIDE_WIDTH_VAR, `${state.sideWidth}px`);
+    else document.body.style.removeProperty(SIDE_WIDTH_VAR);
+    return () => {
+      document.body.classList.remove(`${p}-side`);
+      document.body.style.removeProperty(SIDE_WIDTH_VAR);
+    };
+  }, [state.presentation, state.sideWidth]);
+
   // 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 openSide = useCallback(() => dispatch({ type: "side" }), []);
+  const reopen = useCallback(() => dispatch({ type: "reopen" }), []);
+  const setSideAllowed = useCallback((allowed: boolean) => dispatch({ type: "side-allowed", allowed }), []);
   const minimize = useCallback(() => dispatch({ type: "minimize" }), []);
   const dismiss = useCallback(() => dispatch({ type: "dismiss" }), []);
   const setBusy = useCallback((busy: boolean) => dispatch({ type: "busy", busy }), []);
@@ -236,8 +303,8 @@ export function AssistantProvider({ options, children }: { options?: AssistantOp
   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]);
+    enterFull, leaveFull, openDock, openSide, reopen, minimize, dismiss, setBusy, setDockHeight, setDockOffsetRight, setSideWidth, setSideAllowed,
+  }), [state, pageFacts, publishPageFacts, retractPageFacts, enterFull, leaveFull, openDock, openSide, reopen, minimize, dismiss, setBusy, setDockHeight, setDockOffsetRight, setSideWidth, setSideAllowed]);
 
   return <Ctx.Provider value={api}>{children}</Ctx.Provider>;
 }