@protolabsai/ui 0.19.0 → 0.20.0

package/dist/plugin-kit.css

@@ -2515,6 +2515,56 @@ a.pl-changelog__version:hover {
   outline: none;
 }
 
+/* Reopen handle — the grab strip a collapsed side leaves at its edge. Drag it in to
+   size the panel open (VS Code style), or tap/Enter to pop it to its min width. */
+.pl-appshell__reopen {
+  position: relative;
+  flex: 0 0 6px;
+  align-self: stretch;
+  padding: 0;
+  background: transparent;
+  border: none;
+  cursor: col-resize;
+  touch-action: none;
+  transition: background var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-appshell__reopen--right {
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-appshell__reopen--left {
+  border-right: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-appshell__reopen:hover,
+.pl-appshell__reopen:focus-visible {
+  background: var(--pl-color-bg-hover);
+  outline: none;
+}
+/* a centered grip that surfaces on hover/focus so the affordance is discoverable */
+.pl-appshell__reopen::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 2px;
+  height: 24px;
+  transform: translate(-50%, -50%);
+  border-radius: 2px;
+  background: var(--pl-color-border-strong);
+  opacity: 0;
+  transition: opacity var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-appshell__reopen:hover::after,
+.pl-appshell__reopen:focus-visible::after {
+  opacity: 1;
+}
+
+/* While a divider/reopen gesture is live, kill text selection + force the resize
+   cursor everywhere (the pointer roams the whole window during the drag). */
+.pl-appshell-frame--dragging {
+  cursor: col-resize;
+  user-select: none;
+}
+
 .pl-appshell--mobile {
   flex-direction: column;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protolabsai/ui",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/src/app-shell.tsx

@@ -253,6 +253,11 @@ function useIsMobile(breakpoint: number) {
 
 type RailOrder = { left: string[]; right: string[] };
 
+// An active divider/reopen gesture. `move`/`up` are the window listeners for this
+// gesture (stored so they can be detached) — see the drag block in AppShell.
+type DragKind = "divider" | "reopen-right" | "reopen-left";
+type DragSession = { kind: DragKind; move: (e: PointerEvent) => void; up: (e: PointerEvent) => void };
+
 export type AppShellProps = {
   leftItems: RailItem[];
   rightItems: RailItem[];
@@ -331,70 +336,107 @@ export function AppShell({
 }: AppShellProps) {
   const isMobile = useIsMobile(mobileBreakpoint);
 
-  // ── resize handle ──
-  // One divider, zero-sum: the right column is width-controlled and the left
-  // flexes to fill, so dragging grows one column as it shrinks the other. Each
-  // side is held at its min on the way in; OVERDRAG px past that min snaps that
-  // side closed (collapse is controlled — the host restores it).
-  const OVERDRAG = 64;
+  // ── divider + collapse/reopen drag ──
+  // One divider, zero-sum: the right column is width-controlled and the left flexes,
+  // so dragging grows one column as it shrinks the other. The gesture runs on WINDOW
+  // listeners so it survives the layout change when a side closes — collapse is only
+  // COMMITTED on pointer-up (drag back out before releasing to recover an accidental
+  // close), the panel can shrink past its min toward the edge, and a collapsed side
+  // exposes a reopen handle you can drag (or tap) back open. Collapse fires once the
+  // side is dragged below half its min — you have to bring it well in, not just nudge.
+  const COLLAPSE_RIGHT = Math.round(minRightWidth * 0.5);
+  const COLLAPSE_LEFT = Math.round(minLeftWidth * 0.5);
+  const REOPEN_TAP = 6; // movement under this on a reopen handle counts as a tap (open at min)
   const leftColRef = useRef<HTMLElement | null>(null);
-  const drag = useRef<{ startX: number; startW: number; startLeftW: number } | null>(null);
-  /** Resize `rightWidth` to `raw` px, holding both columns at their minimums. */
-  const commit = useCallback(
-    (raw: number, startLeftW: number, startW: number) => {
-      const upper = Math.max(minRightWidth, Math.min(maxRightWidth, startLeftW + startW - minLeftWidth));
-      onRightWidthChange(Math.min(upper, Math.max(minRightWidth, raw)));
+  const drag = useRef<DragSession | null>(null);
+  const [dragging, setDragging] = useState(false);
+
+  /** rightWidth snapped back into the valid open range (left keeps its min). */
+  const clampOpen = useCallback(
+    (w: number, spanW: number) => {
+      const upper = Math.max(minRightWidth, Math.min(maxRightWidth, spanW - minLeftWidth));
+      return Math.min(upper, Math.max(minRightWidth, w));
     },
-    [minRightWidth, maxRightWidth, minLeftWidth, onRightWidthChange],
+    [minRightWidth, maxRightWidth, minLeftWidth],
   );
-  const onPointerDown = useCallback(
-    (e: ReactPointerEvent<HTMLDivElement>) => {
+
+  const endGesture = useCallback(() => {
+    const d = drag.current;
+    if (d) {
+      window.removeEventListener("pointermove", d.move);
+      window.removeEventListener("pointerup", d.up);
+      window.removeEventListener("pointercancel", d.up);
+    }
+    drag.current = null;
+    setDragging(false);
+  }, []);
+
+  const beginDrag = useCallback(
+    (kind: DragKind, e: ReactPointerEvent<HTMLElement>) => {
       e.preventDefault();
-      drag.current = { startX: e.clientX, startW: rightWidth, startLeftW: leftColRef.current?.clientWidth ?? 0 };
-      e.currentTarget.setPointerCapture(e.pointerId);
-    },
-    [rightWidth],
-  );
-  const onPointerMove = useCallback(
-    (e: ReactPointerEvent<HTMLDivElement>) => {
-      const d = drag.current;
-      if (!d) return;
-      const raw = d.startW + (d.startX - e.clientX);
-      const predictedLeft = d.startLeftW - (raw - d.startW);
-      const endDrag = () => {
-        drag.current = null;
-        e.currentTarget.releasePointerCapture?.(e.pointerId);
-      };
-      // Overdrag toward the right rail → snap the right column closed.
-      if (onCollapse && raw < minRightWidth - OVERDRAG) {
-        endDrag();
-        onCollapse(true);
-        return;
-      }
-      // Overdrag toward the left rail → snap the left column closed.
-      if (onLeftCollapse && predictedLeft < minLeftWidth - OVERDRAG) {
-        endDrag();
-        onLeftCollapse(true);
-        return;
+      const leftW = leftColRef.current?.clientWidth ?? 0;
+      // Reopen reveals the side first so it can grow from the edge under the pointer.
+      const startW = kind === "reopen-right" ? 0 : rightWidth;
+      if (kind === "reopen-right") {
+        onCollapse?.(false);
+        onRightWidthChange(0);
+      } else if (kind === "reopen-left") {
+        onLeftCollapse?.(false);
       }
-      commit(raw, d.startLeftW, d.startW);
+      const startX = e.clientX;
+      // The two columns share a fixed span during the gesture (zero-sum divider).
+      const spanW = startW + leftW;
+      const rightFromPointer = (clientX: number) =>
+        Math.max(0, Math.min(spanW || maxRightWidth, startW + (startX - clientX)));
+
+      const move = (ev: PointerEvent) => {
+        if (kind === "reopen-left") return; // left is the flex column — reopening is binary
+        onRightWidthChange(rightFromPointer(ev.clientX));
+      };
+      const up = (ev: PointerEvent) => {
+        if (kind === "reopen-left") {
+          endGesture();
+          return;
+        }
+        const moved = Math.abs(ev.clientX - startX);
+        const raw = rightFromPointer(ev.clientX);
+        const span = spanW || raw + minLeftWidth;
+        const leftAtRaw = span - raw;
+        if (kind === "reopen-right" && moved < REOPEN_TAP) {
+          onCollapse?.(false); // a tap on the reopen handle → just open at min
+          onRightWidthChange(clampOpen(minRightWidth, span));
+        } else if (onCollapse && raw < COLLAPSE_RIGHT) {
+          onCollapse(true);
+          onRightWidthChange(clampOpen(startW || minRightWidth, span)); // sane width for next open
+        } else if (onLeftCollapse && spanW > 0 && leftAtRaw < COLLAPSE_LEFT) {
+          onLeftCollapse(true);
+          onRightWidthChange(clampOpen(startW || minRightWidth, span)); // restore right for when left reopens
+        } else {
+          onCollapse?.(false);
+          onRightWidthChange(clampOpen(raw, span));
+        }
+        endGesture();
+      };
+
+      drag.current = { kind, move, up };
+      window.addEventListener("pointermove", move);
+      window.addEventListener("pointerup", up);
+      window.addEventListener("pointercancel", up);
+      setDragging(true);
     },
-    [minRightWidth, minLeftWidth, onCollapse, onLeftCollapse, commit],
+    [rightWidth, minRightWidth, minLeftWidth, maxRightWidth, onRightWidthChange, onCollapse, onLeftCollapse, clampOpen, endGesture, COLLAPSE_RIGHT, COLLAPSE_LEFT],
   );
-  const onPointerUp = useCallback((e: ReactPointerEvent<HTMLDivElement>) => {
-    drag.current = null;
-    e.currentTarget.releasePointerCapture?.(e.pointerId);
-  }, []);
+
   const onKeyDown = useCallback(
     (e: ReactKeyboardEvent<HTMLDivElement>) => {
       if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
       e.preventDefault();
       const step = e.shiftKey ? 48 : 16;
-      const startLeftW = leftColRef.current?.clientWidth ?? 0;
+      const spanW = rightWidth + (leftColRef.current?.clientWidth ?? minLeftWidth);
       // ArrowLeft grows the right column (shrinks the left); ArrowRight reverses.
-      commit(rightWidth + (e.key === "ArrowLeft" ? step : -step), startLeftW, rightWidth);
+      onRightWidthChange(clampOpen(rightWidth + (e.key === "ArrowLeft" ? step : -step), spanW));
     },
-    [rightWidth, commit],
+    [rightWidth, onRightWidthChange, clampOpen],
   );
 
   // ── rail drag-and-drop (only when onRailReorder is provided) ──
@@ -493,11 +535,30 @@ export function AppShell({
   const ctxLeft = onRailContextMenu ? (e: ReactMouseEvent, id: string) => onRailContextMenu("left", e, id) : undefined;
   const ctxRight = onRailContextMenu ? (e: ReactMouseEvent, id: string) => onRailContextMenu("right", e, id) : undefined;
 
+  // Collapsed-but-present sides expose a reopen handle (drag in to size it open, or
+  // tap to pop it to min) — VS Code style.
+  const canReopenRight = !showRight && rightItems.length > 0 && showLeft;
+  const canReopenLeft = leftCollapsed && showRight;
+
   const renderShell = (leftRail: ReactNode, rightRail: ReactNode) => (
-    <div className={cx("pl-appshell-frame", className)}>
+    <div className={cx("pl-appshell-frame", dragging && "pl-appshell-frame--dragging", className)}>
       {header != null && <div className="pl-appshell__header">{header}</div>}
       <div className="pl-appshell">
         {leftRail}
+        {canReopenLeft && (
+          <button
+            type="button"
+            className="pl-appshell__reopen pl-appshell__reopen--left"
+            aria-label="Open left panel"
+            onPointerDown={(e) => beginDrag("reopen-left", e)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onLeftCollapse?.(false);
+              }
+            }}
+          />
+        )}
         {showLeft && (
           <main ref={leftColRef} className="pl-appshell__col pl-appshell__col--left">
             {leftContent}
@@ -514,9 +575,7 @@ export function AppShell({
             aria-valuemax={maxRightWidth}
             aria-valuetext={`Right panel ${rightWidth}px`}
             tabIndex={0}
-            onPointerDown={onPointerDown}
-            onPointerMove={onPointerMove}
-            onPointerUp={onPointerUp}
+            onPointerDown={(e) => beginDrag("divider", e)}
             onKeyDown={onKeyDown}
             onDoubleClick={() => onCollapse?.(true)}
           />
@@ -529,6 +588,20 @@ export function AppShell({
             {rightContent}
           </aside>
         )}
+        {canReopenRight && (
+          <button
+            type="button"
+            className="pl-appshell__reopen pl-appshell__reopen--right"
+            aria-label="Open right panel"
+            onPointerDown={(e) => beginDrag("reopen-right", e)}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onCollapse?.(false);
+              }
+            }}
+          />
+        )}
         {rightRail}
       </div>
       {utilityBar != null && <div className="pl-appshell__utility">{utilityBar}</div>}

package/src/plugin-kit.js

@@ -1,32 +1,62 @@
-// @protolabsai/ui/plugin-kit — the ADR 0026 console handshake for protoAgent
-// plugin iframe pages. Replaces the broken substring stub that shipped copy-pasted
-// across plugins (it only mapped bg/accent onto private vars and dropped every other
-// token). This applies the console's FULL --pl-* theme bundle to :root and captures
-// the bearer token for same-origin API calls.
+// @protolabsai/ui/plugin-kit — the protoAgent console handshake for plugin iframe
+// pages, wired to the DS. The console (protoAgent ADR 0038 theming bridge) posts a
+// CURATED theme — `{ bg, bgPanel, fg, fgMuted, brand, border }`, read from the
+// console's own CSS vars — NOT the full --pl-* set. This bridges those six keys onto
+// the --pl-* tokens that plugin-kit.css components consume, so the DS components
+// re-skin to the operator's live theme. The rest of the --pl-* tokens keep the kit's
+// (coherent dark) defaults. See protoAgent docs/guides/plugin-views.md +
+// examples/plugins/chat_example.
 //
-// Two ways to use it (no build step required for either):
+// Two ways to use it (no build step for either):
 //   1. <script type="module">: import { initPluginView } from ".../plugin-kit.js"
 //   2. classic <script src=".../plugin-kit.js">: use the window.protoPluginView global
-// Or just inline the snippet from docs/how-to/build-a-plugin-view.md.
+// Or inline the snippet from docs/how-to/build-a-plugin-view.md.
+
+// Curated console key → the --pl-* token(s) the DS components actually read.
+const TOKEN_MAP = {
+  bg: ["--pl-color-bg"],
+  bgPanel: ["--pl-color-bg-raised", "--pl-color-bg-subtle"],
+  fg: ["--pl-color-fg"],
+  fgMuted: ["--pl-color-fg-muted"],
+  brand: ["--pl-color-accent"], // components key off --pl-color-accent (== brand lavender)
+  border: ["--pl-color-border"],
+};
 
 let token = null;
 const listeners = new Set();
 
-/** Apply only DS custom properties from a theme map to :root — a stray key can
- *  never set an arbitrary CSS property. */
+/** Map the console's curated theme onto the DS --pl-* tokens on :root. Also passes
+ *  through any key already in --pl-* form, so a future console that sends raw tokens
+ *  Just Works. Unknown keys are ignored — a plugin page can never set an arbitrary
+ *  CSS property this way. */
 function applyTheme(theme) {
   if (!theme || typeof theme !== "object") return;
   const root = document.documentElement;
-  for (const [k, v] of Object.entries(theme)) {
-    if (k.startsWith("--pl-")) root.style.setProperty(k, String(v));
+  for (const [key, value] of Object.entries(theme)) {
+    if (value == null || value === "") continue;
+    const v = String(value);
+    if (key.startsWith("--pl-")) {
+      root.style.setProperty(key, v);
+      continue;
+    }
+    const targets = TOKEN_MAP[key];
+    if (targets) for (const cssVar of targets) root.style.setProperty(cssVar, v);
   }
 }
 
 function onMessage(e) {
   const d = e && e.data;
-  if (!d || d.type !== "protoagent:init") return;
-  if (d.token) token = d.token;
-  applyTheme(d.theme);
+  if (!d) return;
+  // `protoagent:init` carries token + theme (after iframe load); `protoagent:theme`
+  // is the live re-theme on an operator theme switch.
+  if (d.type === "protoagent:init") {
+    if (d.token) token = d.token;
+    applyTheme(d.theme);
+  } else if (d.type === "protoagent:theme") {
+    applyTheme(d.theme);
+  } else {
+    return;
+  }
   for (const fn of listeners) {
     try {
       fn({ token, theme: d.theme });
@@ -37,17 +67,11 @@ function onMessage(e) {
 }
 
 /** Start listening for the console handshake. Call once on load. `onInit` (optional)
- *  fires every time the console (re)sends tokens/theme — e.g. on a live theme switch.
- *  Returns a small handle with the current token. */
+ *  fires on the initial bearer+theme AND on every live re-theme. Returns a handle
+ *  with the current token. */
 export function initPluginView(onInit) {
   if (typeof onInit === "function") listeners.add(onInit);
   window.addEventListener("message", onMessage);
-  // Announce readiness so a console that waits for it sends the init eagerly.
-  try {
-    window.parent && window.parent.postMessage({ type: "protoagent:ready" }, "*");
-  } catch (_) {
-    /* sandboxed / no parent */
-  }
   return { getToken };
 }
 

package/src/styles/app-shell.css

@@ -244,6 +244,56 @@
   outline: none;
 }
 
+/* Reopen handle — the grab strip a collapsed side leaves at its edge. Drag it in to
+   size the panel open (VS Code style), or tap/Enter to pop it to its min width. */
+.pl-appshell__reopen {
+  position: relative;
+  flex: 0 0 6px;
+  align-self: stretch;
+  padding: 0;
+  background: transparent;
+  border: none;
+  cursor: col-resize;
+  touch-action: none;
+  transition: background var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-appshell__reopen--right {
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-appshell__reopen--left {
+  border-right: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-appshell__reopen:hover,
+.pl-appshell__reopen:focus-visible {
+  background: var(--pl-color-bg-hover);
+  outline: none;
+}
+/* a centered grip that surfaces on hover/focus so the affordance is discoverable */
+.pl-appshell__reopen::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 2px;
+  height: 24px;
+  transform: translate(-50%, -50%);
+  border-radius: 2px;
+  background: var(--pl-color-border-strong);
+  opacity: 0;
+  transition: opacity var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-appshell__reopen:hover::after,
+.pl-appshell__reopen:focus-visible::after {
+  opacity: 1;
+}
+
+/* While a divider/reopen gesture is live, kill text selection + force the resize
+   cursor everywhere (the pointer roams the whole window during the drag). */
+.pl-appshell-frame--dragging {
+  cursor: col-resize;
+  user-select: none;
+}
+
 .pl-appshell--mobile {
   flex-direction: column;
 }