@protolabsai/ui 0.5.0 → 0.7.0

package/package.json

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

package/src/AppShell.full.stories.tsx

@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { AppShell, Button, MobileNav, PanelHeader, SurfaceRail } from "./index";
+import type { MobileItem, RailItem } from "./index";
+
+const meta: Meta = { title: "Components/AppShell" };
+export default meta;
+type Story = StoryObj;
+
+const G = () => (
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5">
+    <rect x="2.5" y="2.5" width="11" height="11" rx="2" />
+  </svg>
+);
+
+const LEFT: RailItem[] = [
+  { id: "chat", label: "Chat", icon: <G />, dot: true },
+  { id: "activity", label: "Activity", icon: <G />, badge: 12 },
+  { id: "flows", label: "Flows", icon: <G /> },
+  { id: "knowledge", label: "Know", icon: <G /> },
+];
+const RIGHT: RailItem[] = [
+  { id: "inbox", label: "Inbox", icon: <G />, badge: 3 },
+  { id: "telemetry", label: "Stats", icon: <G /> },
+];
+
+const surfaceBody = (label: string) => (
+  <div style={{ flex: 1, padding: 16, color: "var(--pl-color-fg-muted)", fontSize: 13, fontFamily: "var(--pl-font-mono)" }}>
+    {label} surface content…
+  </div>
+);
+
+export const Full: Story = {
+  render: () => {
+    function Demo() {
+      const [activeLeft, setActiveLeft] = useState("chat");
+      const [activeRight, setActiveRight] = useState("inbox");
+      const [rightWidth, setRightWidth] = useState(360);
+      const [collapsed, setCollapsed] = useState(false);
+      const mobile: MobileItem[] = [...LEFT, ...RIGHT].map((i) => ({ id: i.id, label: i.label, icon: i.icon }));
+      return (
+        <div style={{ height: 480, border: "1px solid var(--pl-color-border)", borderRadius: 4, overflow: "hidden" }}>
+          <AppShell
+            leftItems={LEFT}
+            rightItems={RIGHT}
+            activeLeft={activeLeft}
+            activeRight={activeRight}
+            onSelect={(side, id) => {
+              if (side === "left") setActiveLeft(id);
+              else {
+                setActiveRight(id);
+                setCollapsed(false);
+              }
+            }}
+            rightWidth={rightWidth}
+            onRightWidthChange={setRightWidth}
+            rightCollapsed={collapsed}
+            onCollapse={setCollapsed}
+            leftContent={
+              <>
+                <PanelHeader title={activeLeft} actions={<Button size="sm">Action</Button>} />
+                {surfaceBody(activeLeft)}
+              </>
+            }
+            rightContent={
+              <>
+                <PanelHeader
+                  compact
+                  title={activeRight}
+                  actions={
+                    <Button size="sm" variant="ghost" onClick={() => setCollapsed(true)}>
+                      Collapse
+                    </Button>
+                  }
+                />
+                {surfaceBody(activeRight)}
+              </>
+            }
+            mobileItems={mobile}
+            mobileActiveId={activeLeft}
+            onMobileSelect={setActiveLeft}
+            quickBarIds={["chat", "activity", "flows", "inbox", "telemetry"]}
+          />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const Rail: Story = {
+  render: () => {
+    function Demo() {
+      const [active, setActive] = useState("activity");
+      return (
+        <div style={{ height: 320, width: 64, border: "1px solid var(--pl-color-border)", borderRadius: 4 }}>
+          <SurfaceRail
+            side="left"
+            ariaLabel="Surfaces"
+            items={LEFT}
+            activeId={active}
+            onSelect={setActive}
+            onContextMenu={(e) => e.preventDefault()}
+          />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+export const Mobile: Story = {
+  render: () => {
+    function Demo() {
+      const [active, setActive] = useState("chat");
+      const mobile: MobileItem[] = [...LEFT, ...RIGHT].map((i) => ({ id: i.id, label: i.label, icon: i.icon }));
+      return (
+        <div style={{ width: 360, border: "1px solid var(--pl-color-border)", borderRadius: 4 }}>
+          <div style={{ height: 220, padding: 16, color: "var(--pl-color-fg-muted)", fontFamily: "var(--pl-font-mono)", fontSize: 13 }}>
+            {active} surface — tap “More” for the full list
+          </div>
+          <MobileNav items={mobile} activeId={active} onSelect={setActive} quickBarIds={["chat", "activity", "flows", "inbox"]} />
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};

package/src/Button.stories.tsx

@@ -5,7 +5,7 @@ const meta: Meta<typeof Button> = {
   title: "Components/Button",
   component: Button,
   args: { children: "Breakdowns" },
-  argTypes: { variant: { control: "inline-radio", options: ["default", "primary"] } },
+  argTypes: { variant: { control: "inline-radio", options: ["default", "primary", "ghost", "danger"] } },
 };
 export default meta;
 type Story = StoryObj<typeof Button>;
@@ -13,3 +13,48 @@ type Story = StoryObj<typeof Button>;
 export const Default: Story = {};
 export const Primary: Story = { args: { variant: "primary", children: "Get started" } };
 export const Disabled: Story = { args: { disabled: true, children: "Disabled" } };
+
+const Sq = () => (
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5">
+    <path d="M8 3v10M3 8h10" strokeLinecap="round" />
+  </svg>
+);
+
+export const Variants: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 8, flexWrap: "wrap", alignItems: "center" }}>
+      <Button>default</Button>
+      <Button variant="primary">primary</Button>
+      <Button variant="ghost">ghost</Button>
+      <Button variant="danger">danger</Button>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
+      <Button size="sm">small</Button>
+      <Button>medium</Button>
+      <Button size="sm" variant="primary">
+        small primary
+      </Button>
+    </div>
+  ),
+};
+
+export const IconOnly: Story = {
+  render: () => (
+    <div style={{ display: "flex", gap: 8, alignItems: "center" }}>
+      <Button icon aria-label="Add">
+        <Sq />
+      </Button>
+      <Button icon variant="ghost" aria-label="Add">
+        <Sq />
+      </Button>
+      <Button icon size="sm" aria-label="Add">
+        <Sq />
+      </Button>
+    </div>
+  ),
+};

package/src/Skeleton.stories.tsx

@@ -0,0 +1,37 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Skeleton, SkeletonGroup } from "./index";
+
+const meta: Meta = { title: "Components/Skeleton" };
+export default meta;
+type Story = StoryObj;
+
+export const Bars: Story = {
+  render: () => (
+    <div style={{ display: "grid", gap: 12, maxWidth: 360 }}>
+      <Skeleton />
+      <Skeleton width={200} />
+      <Skeleton width={120} height={28} />
+    </div>
+  ),
+};
+
+export const TextLines: Story = {
+  render: () => (
+    <div style={{ maxWidth: 360 }}>
+      <Skeleton lines={4} />
+    </div>
+  ),
+};
+
+export const PanelSkeleton: Story = {
+  render: () => (
+    <SkeletonGroup style={{ maxWidth: 420, padding: 16, border: "1px solid var(--pl-color-border)", borderRadius: 4 }}>
+      <Skeleton width={140} height={16} />
+      <Skeleton lines={3} />
+      <div style={{ display: "flex", gap: 8 }}>
+        <Skeleton width={80} height={28} />
+        <Skeleton width={80} height={28} />
+      </div>
+    </SkeletonGroup>
+  ),
+};

package/src/index.tsx

@@ -7,6 +7,9 @@ import type {
   ButtonHTMLAttributes,
   HTMLAttributes,
   InputHTMLAttributes,
+  KeyboardEvent as ReactKeyboardEvent,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
   ReactNode,
   RefObject,
   SelectHTMLAttributes,
@@ -32,11 +35,26 @@ import "./styles.css";
 const cx = (...parts: Array<string | false | undefined>) => parts.filter(Boolean).join(" ");
 
 export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
-  /** "primary" reads as a stronger border, not a fill (brand restraint). */
-  variant?: "default" | "primary";
+  /** "primary"/"danger" read as a stronger border, not a fill (brand restraint);
+   *  "ghost" is transparent until hover. */
+  variant?: "default" | "primary" | "ghost" | "danger";
+  size?: "sm" | "md";
+  /** Icon-only: square, centered glyph. Pass `aria-label` for a11y. */
+  icon?: boolean;
 };
-export function Button({ variant = "default", className, ...rest }: ButtonProps) {
-  return <button className={cx("pl-btn", variant === "primary" && "pl-btn--primary", className)} {...rest} />;
+export function Button({ variant = "default", size = "md", icon, className, ...rest }: ButtonProps) {
+  return (
+    <button
+      className={cx(
+        "pl-btn",
+        variant !== "default" && `pl-btn--${variant}`,
+        size === "sm" && "pl-btn--sm",
+        icon && "pl-btn--icon",
+        className,
+      )}
+      {...rest}
+    />
+  );
 }
 
 export type Status = "neutral" | "success" | "warning" | "error" | "info";
@@ -515,11 +533,7 @@ export function ConfirmDialog({
       footer={
         <>
           <Button onClick={onClose}>{cancelLabel}</Button>
-          <Button
-            variant="primary"
-            className={cx(destructive && "pl-btn--danger")}
-            onClick={() => onConfirm?.()}
-          >
+          <Button variant={destructive ? "danger" : "primary"} onClick={() => onConfirm?.()}>
             {confirmLabel}
           </Button>
         </>
@@ -745,9 +759,16 @@ export function Spinner({ size = 16, className }: { size?: number; className?: s
   );
 }
 
-/** Scroll container with brand-styled thin scrollbars. */
-export function ScrollArea({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
-  return <div className={cx("pl-scroll", className)} {...rest} />;
+/** Scroll container with brand-styled thin scrollbars. Carries `min-height:0`
+ *  (so it scrolls inside flex/grid parents) + overscroll containment. Pass
+ *  `ariaLabel` to make it a keyboard-focusable, labelled scroll region. */
+export function ScrollArea({
+  ariaLabel,
+  className,
+  ...rest
+}: HTMLAttributes<HTMLDivElement> & { ariaLabel?: string }) {
+  const a11y = ariaLabel != null ? { role: "region", "aria-label": ariaLabel, tabIndex: 0 } : {};
+  return <div className={cx("pl-scroll", className)} {...a11y} {...rest} />;
 }
 
 // ── Form controls (compose with Field, or use standalone) ────────────────────
@@ -964,3 +985,345 @@ export function MenuSub({
     </RDropdown.Sub>
   );
 }
+
+// ── Skeleton (loading placeholder) ───────────────────────────────────────────
+
+/** Shimmering content-shaped loading placeholder. `lines>1` stacks text bars
+ *  (last one short). Token-driven; static fill under reduced-motion. */
+export function Skeleton({
+  width,
+  height = 14,
+  lines,
+  className,
+  style,
+  ...rest
+}: HTMLAttributes<HTMLDivElement> & {
+  width?: number | string;
+  height?: number | string;
+  /** Stack N text-line bars instead of a single bar. */
+  lines?: number;
+}) {
+  if (lines != null && lines > 1) {
+    return (
+      <div className={cx("pl-skel-lines", className)} style={style} {...rest}>
+        {Array.from({ length: lines }, (_, i) => (
+          <div
+            key={i}
+            className="pl-skel"
+            style={{ height, width: i === lines - 1 ? "65%" : (width ?? "100%") }}
+          />
+        ))}
+      </div>
+    );
+  }
+  return (
+    <div className={cx("pl-skel", className)} style={{ width: width ?? "100%", height, ...style }} {...rest} />
+  );
+}
+
+/** Optional wrapper to group related skeletons (shared layout gap). */
+export function SkeletonGroup({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return <div className={cx("pl-skel-group", className)} {...rest} />;
+}
+
+// ── App shell (SurfaceRail · MobileNav · AppShell) ───────────────────────────
+// The operator-console shell, converged from protoAgent's production ADR 0035
+// dual-rail layout. All three are dumb + props-driven; persistence (rail order,
+// widths, active surfaces) stays app-side — AppShell is controlled.
+
+export type RailItem = {
+  id: string;
+  label: string;
+  icon: ReactNode;
+  /** Count badge (caps at "9+"). Mutually exclusive with `dot`. */
+  badge?: number;
+  /** Pulsing indicator, no count (e.g. a background stream). */
+  dot?: boolean;
+};
+
+/** Vertical icon rail — both the left and right rails render through this.
+ *  `onContextMenu` is the integration point for the DS `Menu` (right-click →
+ *  host calls menuRef.open({x,y})); the menu's registry/keying stays app-side. */
+export function SurfaceRail({
+  side,
+  ariaLabel,
+  items,
+  activeId,
+  onSelect,
+  onContextMenu,
+}: {
+  side: "left" | "right";
+  ariaLabel: string;
+  items: RailItem[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  onContextMenu?: (e: ReactMouseEvent, id: string) => void;
+}) {
+  return (
+    <aside className={cx("pl-rail", side === "right" && "pl-rail--right")} aria-label={ariaLabel}>
+      {items.map((it) => (
+        <button
+          key={it.id}
+          type="button"
+          className={cx("pl-rail__btn", it.id === activeId && "pl-rail__btn--active")}
+          title={it.label}
+          aria-label={it.label}
+          aria-current={it.id === activeId ? "page" : undefined}
+          onClick={() => onSelect(it.id)}
+          onContextMenu={onContextMenu ? (e) => onContextMenu(e, it.id) : undefined}
+        >
+          <span className="pl-rail__icon" aria-hidden>
+            {it.icon}
+          </span>
+          <span className="pl-rail__label">{it.label}</span>
+          {it.badge ? (
+            <span className="pl-rail__badge">{it.badge > 9 ? "9+" : it.badge}</span>
+          ) : it.dot ? (
+            <span className="pl-rail__dot" aria-label="active" />
+          ) : null}
+        </button>
+      ))}
+    </aside>
+  );
+}
+
+export type MobileItem = { id: string; label: string; icon: ReactNode };
+
+/** Mobile shell (<768px): a bottom quick-bar (first 5 pinned surfaces) + a
+ *  "More" button that opens the full surface list in a DS `Drawer`. */
+export function MobileNav({
+  items,
+  activeId,
+  onSelect,
+  quickBarIds,
+}: {
+  items: MobileItem[];
+  activeId: string;
+  onSelect: (id: string) => void;
+  /** Surfaces pinned to the bottom bar (first 5 used). */
+  quickBarIds: string[];
+}) {
+  const [open, setOpen] = useState(false);
+  const byId = new Map(items.map((i) => [i.id, i] as const));
+  const quick = quickBarIds
+    .map((id) => byId.get(id))
+    .filter((i): i is MobileItem => Boolean(i))
+    .slice(0, 5);
+  const pick = (id: string) => {
+    onSelect(id);
+    setOpen(false);
+  };
+  return (
+    <>
+      <nav className="pl-mobilenav" aria-label="Quick surfaces">
+        {quick.map((it) => (
+          <button
+            key={it.id}
+            type="button"
+            className={cx("pl-mobilenav__tab", it.id === activeId && "pl-mobilenav__tab--active")}
+            onClick={() => pick(it.id)}
+          >
+            <span className="pl-mobilenav__icon" aria-hidden>
+              {it.icon}
+            </span>
+            <span>{it.label}</span>
+          </button>
+        ))}
+        <button type="button" className="pl-mobilenav__tab" onClick={() => setOpen(true)} aria-label="All surfaces">
+          <span className="pl-mobilenav__icon" aria-hidden>
+            <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
+              <path d="M3 6h18M3 12h18M3 18h18" />
+            </svg>
+          </span>
+          <span>More</span>
+        </button>
+      </nav>
+      <Drawer open={open} onClose={() => setOpen(false)} side="right" title="Surfaces" width={280}>
+        <div className="pl-mobilenav__list">
+          {items.map((it) => (
+            <button
+              key={it.id}
+              type="button"
+              className={cx("pl-mobilenav__list-item", it.id === activeId && "pl-mobilenav__list-item--active")}
+              onClick={() => pick(it.id)}
+            >
+              <span className="pl-mobilenav__icon" aria-hidden>
+                {it.icon}
+              </span>
+              <span>{it.label}</span>
+            </button>
+          ))}
+        </div>
+      </Drawer>
+    </>
+  );
+}
+
+/** True below `breakpoint` px (client-only; false on first paint). */
+function useIsMobile(breakpoint: number) {
+  const [mobile, setMobile] = useState(false);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const mq = window.matchMedia(`(max-width: ${breakpoint - 1}px)`);
+    const update = () => setMobile(mq.matches);
+    update();
+    mq.addEventListener("change", update);
+    return () => mq.removeEventListener("change", update);
+  }, [breakpoint]);
+  return mobile;
+}
+
+export type AppShellProps = {
+  leftItems: RailItem[];
+  rightItems: RailItem[];
+  activeLeft: string;
+  activeRight: string;
+  onSelect: (side: "left" | "right", id: string) => void;
+  /** Right-click on a rail icon — wire to a DS `Menu` for move/reorder etc. */
+  onRailContextMenu?: (side: "left" | "right", e: ReactMouseEvent, id: string) => void;
+  leftContent: ReactNode;
+  rightContent: ReactNode;
+  /** Controlled right-column width (px). */
+  rightWidth: number;
+  onRightWidthChange: (width: number) => void;
+  rightCollapsed?: boolean;
+  onCollapse?: (collapsed: boolean) => void;
+  minRightWidth?: number;
+  maxRightWidth?: number;
+  /** Mobile (<breakpoint) config. Omit to disable the mobile shell. */
+  mobileItems?: MobileItem[];
+  mobileActiveId?: string;
+  onMobileSelect?: (id: string) => void;
+  quickBarIds?: string[];
+  mobileBreakpoint?: number;
+  className?: string;
+};
+
+/** The full dual-rail operator shell:
+ *  `[left rail][left column][resize handle][right column][right rail]`,
+ *  collapsing to `MobileNav` below `mobileBreakpoint`. Controlled — the host
+ *  owns the surface registry and persists rail order / widths / active state. */
+export function AppShell({
+  leftItems,
+  rightItems,
+  activeLeft,
+  activeRight,
+  onSelect,
+  onRailContextMenu,
+  leftContent,
+  rightContent,
+  rightWidth,
+  onRightWidthChange,
+  rightCollapsed = false,
+  onCollapse,
+  minRightWidth = 280,
+  maxRightWidth = 720,
+  mobileItems,
+  mobileActiveId,
+  onMobileSelect,
+  quickBarIds,
+  mobileBreakpoint = 768,
+  className,
+}: AppShellProps) {
+  const isMobile = useIsMobile(mobileBreakpoint);
+  const drag = useRef<{ startX: number; startW: number } | null>(null);
+  const clamp = useCallback(
+    (w: number) => Math.min(maxRightWidth, Math.max(minRightWidth, w)),
+    [minRightWidth, maxRightWidth],
+  );
+
+  const onPointerDown = useCallback(
+    (e: ReactPointerEvent<HTMLDivElement>) => {
+      e.preventDefault();
+      drag.current = { startX: e.clientX, startW: rightWidth };
+      e.currentTarget.setPointerCapture(e.pointerId);
+    },
+    [rightWidth],
+  );
+  const onPointerMove = useCallback(
+    (e: ReactPointerEvent<HTMLDivElement>) => {
+      if (!drag.current) return;
+      onRightWidthChange(clamp(drag.current.startW + (drag.current.startX - e.clientX)));
+    },
+    [clamp, onRightWidthChange],
+  );
+  const onPointerUp = useCallback((e: ReactPointerEvent<HTMLDivElement>) => {
+    drag.current = null;
+    e.currentTarget.releasePointerCapture?.(e.pointerId);
+  }, []);
+  const onKeyDown = useCallback(
+    (e: ReactKeyboardEvent<HTMLDivElement>) => {
+      const step = e.shiftKey ? 48 : 16;
+      if (e.key === "ArrowLeft") {
+        e.preventDefault();
+        onRightWidthChange(clamp(rightWidth + step));
+      } else if (e.key === "ArrowRight") {
+        e.preventDefault();
+        onRightWidthChange(clamp(rightWidth - step));
+      }
+    },
+    [rightWidth, clamp, onRightWidthChange],
+  );
+
+  if (isMobile && mobileItems && onMobileSelect && quickBarIds) {
+    return (
+      <div className={cx("pl-appshell", "pl-appshell--mobile", className)}>
+        <div className="pl-appshell__mobile-stage">{leftContent}</div>
+        <MobileNav
+          items={mobileItems}
+          activeId={mobileActiveId ?? activeLeft}
+          onSelect={onMobileSelect}
+          quickBarIds={quickBarIds}
+        />
+      </div>
+    );
+  }
+
+  const showRight = !rightCollapsed && rightItems.length > 0;
+  return (
+    <div className={cx("pl-appshell", className)}>
+      <SurfaceRail
+        side="left"
+        ariaLabel="Left surfaces"
+        items={leftItems}
+        activeId={activeLeft}
+        onSelect={(id) => onSelect("left", id)}
+        onContextMenu={onRailContextMenu ? (e, id) => onRailContextMenu("left", e, id) : undefined}
+      />
+      <main className="pl-appshell__col pl-appshell__col--left">{leftContent}</main>
+      {showRight && (
+        <div
+          className="pl-appshell__handle"
+          role="separator"
+          aria-orientation="vertical"
+          aria-label="Resize right panel"
+          aria-valuenow={rightWidth}
+          aria-valuemin={minRightWidth}
+          aria-valuemax={maxRightWidth}
+          tabIndex={0}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onKeyDown={onKeyDown}
+          onDoubleClick={() => onCollapse?.(true)}
+        />
+      )}
+      {showRight && (
+        <aside
+          className="pl-appshell__col pl-appshell__col--right"
+          style={{ flex: `0 0 ${rightWidth}px`, width: rightWidth }}
+        >
+          {rightContent}
+        </aside>
+      )}
+      <SurfaceRail
+        side="right"
+        ariaLabel="Right surfaces"
+        items={rightItems}
+        activeId={activeRight}
+        onSelect={(id) => onSelect("right", id)}
+        onContextMenu={onRailContextMenu ? (e, id) => onRailContextMenu("right", e, id) : undefined}
+      />
+    </div>
+  );
+}

package/src/styles.css

@@ -734,6 +734,33 @@ a.pl-row:hover {
   border-color: var(--pl-color-status-error);
   color: var(--pl-color-bg);
 }
+/* Ghost — transparent until hover, for toolbars / inline actions. */
+.pl-btn--ghost {
+  border-color: transparent;
+}
+.pl-btn--ghost:hover {
+  border-color: var(--pl-color-border-strong);
+  background: var(--pl-color-bg-hover);
+}
+.pl-btn--sm {
+  padding: 0.3rem 0.6rem;
+  font-size: 12px;
+}
+/* Icon-only — square, centered glyph. */
+.pl-btn--icon {
+  padding: 0;
+  width: 30px;
+  height: 30px;
+  justify-content: center;
+}
+.pl-btn--icon.pl-btn--sm {
+  width: 26px;
+  height: 26px;
+}
+.pl-btn--icon svg {
+  width: 16px;
+  height: 16px;
+}
 
 /* ── Drawer (slide-in sheet) ─────────────────────────────────────────────────── */
 .pl-drawer {
@@ -1007,9 +1034,18 @@ a.pl-row:hover {
 /* ── ScrollArea (thin brand scrollbars) ──────────────────────────────────────── */
 .pl-scroll {
   overflow: auto;
+  /* min-height:0 lets the region actually scroll inside a flex/grid parent
+     (the classic min-size trap) instead of overflowing it. */
+  min-height: 0;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
   scrollbar-width: thin;
   scrollbar-color: var(--pl-color-border-strong) transparent;
 }
+.pl-scroll:focus-visible {
+  outline: 1px solid var(--pl-color-fg);
+  outline-offset: -2px;
+}
 .pl-scroll::-webkit-scrollbar {
   width: 8px;
   height: 8px;
@@ -1239,12 +1275,236 @@ a.pl-row:hover {
   color: var(--pl-color-fg-muted);
 }
 
+/* ── SurfaceRail (icon rail) ─────────────────────────────────────────────────── */
+.pl-rail {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 2px;
+  width: 64px;
+  flex-shrink: 0;
+  padding: 6px;
+  background: var(--pl-color-bg-raised);
+  border-right: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-rail--right {
+  border-right: none;
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-rail__btn {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+  padding: 8px 2px;
+  background: none;
+  border: none;
+  border-radius: var(--pl-radius);
+  color: var(--pl-color-fg-muted);
+  cursor: pointer;
+  font: inherit;
+  transition:
+    background var(--pl-motion-fast) var(--pl-motion-ease),
+    color var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-rail__btn:hover {
+  background: var(--pl-color-bg-hover);
+  color: var(--pl-color-fg);
+}
+.pl-rail__btn--active {
+  background: var(--pl-color-bg-subtle);
+  color: var(--pl-color-fg);
+}
+.pl-rail__icon {
+  display: inline-flex;
+}
+.pl-rail__icon svg {
+  width: 18px;
+  height: 18px;
+}
+.pl-rail__label {
+  max-width: 100%;
+  overflow: hidden;
+  font-size: 9px;
+  line-height: 1.1;
+  text-align: center;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.pl-rail__badge {
+  position: absolute;
+  top: 4px;
+  right: 9px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 15px;
+  height: 15px;
+  padding: 0 4px;
+  font-family: var(--pl-font-mono);
+  font-size: 9px;
+  color: var(--pl-color-fg);
+  background: var(--pl-color-bg-subtle);
+  border: var(--pl-border-width) solid var(--pl-color-border-strong);
+  border-radius: 999px;
+}
+.pl-rail__dot {
+  position: absolute;
+  top: 6px;
+  right: 14px;
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--pl-color-status-info);
+  animation: pl-dot-pulse var(--pl-motion-status) var(--pl-motion-ease-in-out) infinite;
+}
+
+/* ── MobileNav (bottom bar + drawer list) ────────────────────────────────────── */
+.pl-mobilenav {
+  display: flex;
+  align-items: stretch;
+  background: var(--pl-color-bg-raised);
+  border-top: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-mobilenav__tab {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 3px;
+  padding: 8px 2px;
+  background: none;
+  border: none;
+  color: var(--pl-color-fg-muted);
+  font: inherit;
+  font-size: 10px;
+  cursor: pointer;
+}
+.pl-mobilenav__tab--active {
+  color: var(--pl-color-fg);
+}
+.pl-mobilenav__icon {
+  display: inline-flex;
+}
+.pl-mobilenav__icon svg {
+  width: 18px;
+  height: 18px;
+}
+.pl-mobilenav__list {
+  display: grid;
+  gap: 2px;
+}
+.pl-mobilenav__list-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 10px 8px;
+  background: none;
+  border: none;
+  border-radius: var(--pl-radius);
+  color: var(--pl-color-fg);
+  font: inherit;
+  font-size: 14px;
+  text-align: left;
+  cursor: pointer;
+}
+.pl-mobilenav__list-item:hover {
+  background: var(--pl-color-bg-hover);
+}
+.pl-mobilenav__list-item--active {
+  background: var(--pl-color-bg-subtle);
+}
+
+/* ── AppShell (dual-rail + 3-column) ─────────────────────────────────────────── */
+.pl-appshell {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+  min-height: 0;
+  background: var(--pl-color-bg);
+  color: var(--pl-color-fg);
+}
+.pl-appshell__col {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+.pl-appshell__col--left {
+  flex: 1 1 auto;
+}
+.pl-appshell__col--right {
+  flex: 0 0 auto;
+  border-left: var(--pl-border-width) solid var(--pl-color-border);
+}
+.pl-appshell__handle {
+  flex: 0 0 auto;
+  width: 5px;
+  cursor: col-resize;
+  background: transparent;
+  touch-action: none;
+  transition: background var(--pl-motion-fast) var(--pl-motion-ease);
+}
+.pl-appshell__handle:hover,
+.pl-appshell__handle:focus-visible {
+  background: var(--pl-color-border-strong);
+  outline: none;
+}
+.pl-appshell--mobile {
+  flex-direction: column;
+}
+.pl-appshell__mobile-stage {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+}
+
+/* ── Skeleton (loading placeholder) ──────────────────────────────────────────── */
+.pl-skel {
+  display: block;
+  border-radius: var(--pl-radius);
+  background-color: var(--pl-color-bg-subtle);
+  background-image: linear-gradient(
+    90deg,
+    var(--pl-color-bg-subtle) 25%,
+    var(--pl-color-bg-hover) 50%,
+    var(--pl-color-bg-subtle) 75%
+  );
+  background-size: 200% 100%;
+  animation: pl-skel-shimmer 1.4s var(--pl-motion-ease-in-out) infinite;
+}
+@keyframes pl-skel-shimmer {
+  from {
+    background-position: 200% 0;
+  }
+  to {
+    background-position: -200% 0;
+  }
+}
+.pl-skel-lines {
+  display: grid;
+  gap: 8px;
+}
+.pl-skel-group {
+  display: grid;
+  gap: var(--pl-space-3);
+}
+
 /* Respect reduced-motion for every animation this package introduces. */
 @media (prefers-reduced-motion: reduce) {
   .pl-drawer,
   .pl-toast,
   .pl-dot--pulse,
+  .pl-rail__dot,
   .pl-spinner {
     animation: none;
   }
+  /* Skeletons go static (solid fill, no shimmer). */
+  .pl-skel {
+    animation: none;
+    background-image: none;
+  }
 }