@opengeni/react 0.3.1 → 0.4.0

package/src/components/sandbox-terminal.tsx

@@ -0,0 +1,425 @@
+import type { TerminalCapability } from "@opengeni/sdk";
+import { type ReactNode, useEffect, useRef, useState } from "react";
+import { cn } from "../lib/cn";
+import { useTerminalStream } from "../hooks/use-terminal-stream";
+import type { UseSandboxTerminalResult } from "../hooks/use-sandbox-terminal";
+
+/** A subset of xterm.js's ITheme — the tokens worth themeing from a host app. */
+export type XtermTheme = {
+  background?: string;
+  foreground?: string;
+  cursor?: string;
+  cursorAccent?: string;
+  selectionBackground?: string;
+};
+
+export type SandboxTerminalProps = {
+  /** From `useSandboxTerminal(...)`. */
+  result: UseSandboxTerminalResult;
+  /**
+   * The negotiated Terminal capability cell. When it advertises `transport:
+   * "pty-ws"` + a live `url` (a warm box with a viewer attached), the terminal is
+   * driven by a REAL bidirectional PTY over the Modal tunnel (ttyd-over-websocket)
+   * INSTEAD of the broken ptyWrite-over-HTTP path: xterm input → the socket, the
+   * socket's output → xterm, xterm resize → the socket. On a cold box / no url
+   * (`transport: "sse-events"`) it stays on the read-only Channel-A firehose
+   * (`result.chunks`). Omit to force the legacy firehose-only behavior.
+   */
+  terminalCapability?: TerminalCapability | null | undefined;
+  theme?: XtermTheme | undefined;
+  fontFamily?: string | undefined;
+  fontSize?: number | undefined;
+  /**
+   * Force read-only even when the PTY accepts stdin. Default: interactive
+   * whenever a live pty-ws stream is connected OR `result.write !== null` (the box
+   * advertises an interactive PTY); otherwise the read-only agent firehose.
+   */
+  readOnly?: boolean | undefined;
+  /** Shown on the server / before xterm hydrates (SSR-safe placeholder). */
+  placeholder?: ReactNode | undefined;
+  /** Render the small status header (pty/shell + running dot + read-only pill). */
+  showHeader?: boolean | undefined;
+  /** Shell label for the header (e.g. `/bin/bash`). */
+  shell?: string | undefined;
+  /**
+   * Fired the first time the user engages the terminal surface (focus or click).
+   * The host wires this to warm the box for the REAL pty-ws terminal (the viewer
+   * attach), so a cold box upgrades from the read-only firehose to a live PTY ON
+   * INTERACT — never on mere mount (which would force a box spin-up and regress
+   * the firehose-only default).
+   */
+  onActivate?: (() => void) | undefined;
+  className?: string | undefined;
+};
+
+// The xterm.js handle the effect owns. `any`-free structural shape so we can
+// drive it without a hard type dep on the lazily-imported lib.
+type XtermLike = {
+  open: (el: HTMLElement) => void;
+  write: (data: string) => void;
+  clear: () => void;
+  onData: (cb: (data: string) => void) => { dispose: () => void };
+  onResize: (cb: (size: { cols: number; rows: number }) => void) => { dispose: () => void };
+  loadAddon: (addon: unknown) => void;
+  dispose: () => void;
+  cols: number;
+  rows: number;
+  options: { theme?: XtermTheme; disableStdin?: boolean };
+};
+type FitAddonLike = { fit: () => void };
+
+/**
+ * An xterm.js terminal fed by the Channel-A event projection
+ * (`useSandboxTerminal`). xterm + the fit + web-links addons are lazy-imported
+ * inside an effect, so SSR renders the placeholder and the terminal mounts on
+ * hydration. Output chunks are written incrementally (tracking a written-cursor
+ * by chunk id so a re-render never re-writes). When `result.write` is non-null
+ * and not forced read-only, keystrokes pipe back through the PTY.
+ *
+ * Resizes are tracked with a `ResizeObserver` on the container (not just
+ * `window.resize`) so dragging the dock handle refits the grid instead of
+ * leaving the terminal mis-sized.
+ */
+export function SandboxTerminal({
+  result,
+  terminalCapability,
+  theme,
+  fontFamily,
+  fontSize,
+  readOnly,
+  placeholder,
+  showHeader,
+  shell,
+  onActivate,
+  className,
+}: SandboxTerminalProps) {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const termRef = useRef<XtermLike | null>(null);
+  const fitRef = useRef<FitAddonLike | null>(null);
+  const writtenRef = useRef<Set<string>>(new Set());
+  const [ready, setReady] = useState(false);
+
+  // ── Interactive transport switch ─────────────────────────────────────────────
+  // The interactive terminal is a REAL bidirectional PTY (ttyd over the Modal
+  // tunnel) WHENEVER the Terminal cell advertises `transport: "pty-ws"` + a live
+  // `url`; the ttyd socket then OWNS the screen (input + output both ride it). On
+  // a cold box / sse-events cell, `useTerminalStream` stays idle and we fall back
+  // to the read-only Channel-A command-output firehose (`result.chunks`) — with
+  // the legacy `result.write` (ptyWrite-over-HTTP) as the only stdin path there.
+  const ptyWs = terminalCapability?.transport === "pty-ws" && Boolean(terminalCapability?.url);
+  // Output frames buffer here until xterm has mounted; the write effect drains it.
+  const ptyOutputQueueRef = useRef<string[]>([]);
+  const ptyStream = useTerminalStream({
+    capability: ptyWs
+      ? {
+          transport: terminalCapability!.transport,
+          url: terminalCapability!.url,
+          token: terminalCapability!.token,
+        }
+      : null,
+    onOutput: (data) => {
+      const term = termRef.current;
+      if (term) term.write(data);
+      else ptyOutputQueueRef.current.push(data);
+    },
+  });
+
+  // PTY mode = a live ttyd socket drives the screen. In PTY mode the screen is
+  // owned by the websocket (we must NOT replay the SSE firehose into it — that
+  // double-writes the agent's command output on top of the live PTY). Firehose
+  // mode = the read-only projection (or the legacy HTTP-write fallback).
+  const ptyMode = ptyWs && ptyStream.status !== "closed";
+  // Interactive (stdin enabled) when a live PTY socket is connected, OR (legacy
+  // fallback) the projection exposed an HTTP write fn. `readOnly` forces off.
+  const interactive = !readOnly && (ptyMode || result.write !== null);
+
+  // Mount xterm once (client-only). Re-mounts only when the interactive flag
+  // flips (stdin enable/disable is a construction param on xterm).
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const el = containerRef.current;
+    if (!el) return;
+    let disposed = false;
+
+    // Wait for the container to have a real measured size before opening xterm.
+    // If `term.open()` runs while the panel is 0-wide (tab still mounting, dock
+    // mid-resize), xterm renders at its 80×24 fallback and the first frame's
+    // grid is rasterized into the canvas; a later fit reflows the text but the
+    // stale first paint lingers as a `]]]bbb` smear on the top row. Gating the
+    // open on a non-zero size removes that first wrong-width render entirely.
+    const waitForSize = (el: HTMLElement) =>
+      new Promise<void>((resolve) => {
+        if (el.clientWidth > 0 && el.clientHeight > 0) return resolve();
+        const ro = new ResizeObserver(() => {
+          if (el.clientWidth > 0 && el.clientHeight > 0) {
+            ro.disconnect();
+            resolve();
+          }
+        });
+        ro.observe(el);
+        // Safety: never hang if the observer somehow never fires.
+        setTimeout(() => {
+          ro.disconnect();
+          resolve();
+        }, 1000);
+      });
+
+    // Inject xterm's structural CSS before the first open so the helper-textarea
+    // ghost is clipped from frame one (no top-left input box flash).
+    ensureXtermBaseCss();
+
+    void (async () => {
+      const [{ Terminal }, { FitAddon }, { WebLinksAddon }] = await Promise.all([
+        import("@xterm/xterm"),
+        import("@xterm/addon-fit"),
+        import("@xterm/addon-web-links"),
+      ]);
+      if (disposed) return;
+      await waitForSize(el);
+      if (disposed) return;
+      const term = new Terminal({
+        convertEol: true,
+        disableStdin: !interactive,
+        cursorBlink: interactive,
+        fontFamily: fontFamily ?? "var(--og-font-mono, var(--font-mono, monospace))",
+        fontSize: fontSize ?? 13,
+        lineHeight: 1.25,
+        // A little breathing room from the panel edge so output isn't flush to
+        // the border (matches a real terminal app's inner gutter).
+        ...({ padding: 8 } as Record<string, unknown>),
+        ...(theme ? { theme } : {}),
+      }) as unknown as XtermLike;
+      const fit = new FitAddon() as unknown as FitAddonLike;
+      term.loadAddon(fit);
+      // Clickable URLs in agent output (open in a new tab).
+      term.loadAddon(
+        new WebLinksAddon((_e: MouseEvent, uri: string) => window.open(uri, "_blank", "noopener,noreferrer")) as unknown,
+      );
+      term.open(el);
+      termRef.current = term;
+      fitRef.current = fit;
+      // Critical: the column count must be settled BEFORE any output is written,
+      // or seeded transcript lines reflow/garble against the default 80×24 grid
+      // (the trailing prompt's escape codes smear into `]]]bbb` artifacts). Fit
+      // once now, then again on the next frame after layout has measured the
+      // real container width, and only then unblock the write effect.
+      const settle = () => {
+        try {
+          fit.fit();
+        } catch {
+          // ignore fit before layout
+        }
+      };
+      settle();
+      requestAnimationFrame(() => {
+        if (disposed) return;
+        settle();
+        // Drain any ttyd OUTPUT that arrived before xterm finished mounting.
+        if (ptyOutputQueueRef.current.length > 0) {
+          for (const data of ptyOutputQueueRef.current) term.write(data);
+          ptyOutputQueueRef.current = [];
+        }
+        setReady(true);
+      });
+    })();
+
+    return () => {
+      disposed = true;
+      termRef.current?.dispose();
+      termRef.current = null;
+      fitRef.current = null;
+      writtenRef.current = new Set();
+      setReady(false);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [interactive]);
+
+  // Re-theme live (e.g. dark↔light flip) without re-mounting / losing scrollback.
+  useEffect(() => {
+    const term = termRef.current;
+    if (!ready || !term || !theme) return;
+    term.options.theme = theme;
+  }, [ready, theme]);
+
+  // On the firehose → PTY transition (the box warmed and the ttyd socket came
+  // up), clear the stale read-only transcript so the live shell starts on a clean
+  // screen instead of below the agent's projected command output.
+  const enteredPtyRef = useRef(false);
+  useEffect(() => {
+    const term = termRef.current;
+    if (!ready || !term) return;
+    if (ptyMode && !enteredPtyRef.current) {
+      enteredPtyRef.current = true;
+      term.clear();
+    } else if (!ptyMode) {
+      enteredPtyRef.current = false;
+    }
+  }, [ready, ptyMode]);
+
+  // Write new firehose chunks incrementally — but ONLY in firehose mode. In PTY
+  // mode the ttyd socket owns the screen; replaying the SSE command-output
+  // projection on top of it would double-render the agent's output.
+  useEffect(() => {
+    const term = termRef.current;
+    if (!ready || !term || ptyMode) return;
+    for (const chunk of result.chunks) {
+      if (writtenRef.current.has(chunk.id)) continue;
+      writtenRef.current.add(chunk.id);
+      term.write(chunk.text);
+    }
+  }, [ready, result.chunks, ptyMode]);
+
+  // Wire interactive input when allowed. PTY mode pipes keystrokes to the ttyd
+  // socket (the real PTY); firehose mode uses the legacy ptyWrite-over-HTTP fn.
+  useEffect(() => {
+    const term = termRef.current;
+    if (!ready || !term || !interactive) return;
+    const sink = ptyMode ? ptyStream.write : result.write;
+    if (!sink) return;
+    const sub = term.onData((data) => sink(data));
+    return () => sub.dispose();
+  }, [ready, interactive, ptyMode, ptyStream.write, result.write]);
+
+  // In PTY mode, tell ttyd the window size on the xterm resize event (the fit
+  // addon reflows the grid; ttyd resizes the remote PTY to match), and push the
+  // initial geometry once the socket is open.
+  useEffect(() => {
+    const term = termRef.current;
+    if (!ready || !term || !ptyMode) return;
+    ptyStream.resize(term.cols, term.rows);
+    const sub = term.onResize(({ cols, rows }) => ptyStream.resize(cols, rows));
+    return () => sub.dispose();
+  }, [ready, ptyMode, ptyStream.connected, ptyStream.resize]);
+
+  // Refit on container resize (dock drag) AND window resize. The fit addon
+  // mutates xterm's cols/rows → the onResize handler above forwards to ttyd.
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const refit = () => {
+      try {
+        fitRef.current?.fit();
+      } catch {
+        // ignore
+      }
+    };
+    window.addEventListener("resize", refit);
+    let observer: ResizeObserver | null = null;
+    const el = containerRef.current;
+    if (el && typeof ResizeObserver !== "undefined") {
+      observer = new ResizeObserver(() => refit());
+      observer.observe(el);
+    }
+    return () => {
+      window.removeEventListener("resize", refit);
+      observer?.disconnect();
+    };
+  }, [ready]);
+
+  return (
+    <div className={cn("relative flex h-full w-full flex-col overflow-hidden", className)}>
+      {showHeader && (
+        <div className="flex shrink-0 items-center justify-between gap-2 border-b border-[color:var(--og-color-border,var(--color-border,#2a2a2a))] px-2 py-1 text-[11px] text-[color:var(--og-color-fg-subtle,var(--color-fg-subtle,#888))]">
+          <span className="flex min-w-0 items-center gap-1.5">
+            <span
+              className={cn(
+                "size-1.5 shrink-0 rounded-full",
+                result.running
+                  ? "bg-[color:var(--og-color-status-running,var(--color-status-running,#d29922))]"
+                  : "bg-[color:var(--og-color-fg-subtle,var(--color-fg-subtle,#888))]",
+              )}
+            />
+            <span className="truncate font-[family-name:var(--og-font-mono,var(--font-mono,monospace))]">
+              pty: {shell ?? "shell"}
+            </span>
+          </span>
+          <span className="flex shrink-0 items-center gap-2">
+            {!interactive && (
+              <span className="rounded-[var(--og-radius-sm,4px)] bg-[color:var(--og-color-surface-2,var(--color-surface-2,#161616))] px-1.5 py-0.5 text-[10px] uppercase tracking-wide">
+                read-only
+              </span>
+            )}
+            <button
+              type="button"
+              onClick={() => {
+                termRef.current?.clear();
+                writtenRef.current = new Set();
+              }}
+              className="rounded-[var(--og-radius-sm,4px)] px-1.5 py-0.5 text-[10px] hover:text-[color:var(--og-color-fg,var(--color-fg,#e6e6e6))]"
+            >
+              Clear
+            </button>
+          </span>
+        </div>
+      )}
+      {/* `onPointerDownCapture`/`onFocusCapture` fire on the FIRST user engagement
+          with the terminal surface (capture so they win even though xterm's own
+          listeners stop propagation). The host warms the box for pty-ws here. */}
+      <div
+        className="relative min-h-0 flex-1 bg-[color:var(--og-color-bg,var(--color-bg,#0d0d0d))] px-2 py-1.5"
+        onPointerDownCapture={onActivate}
+        onFocusCapture={onActivate}
+      >
+        {!ready && (placeholder ?? <TerminalPlaceholder />)}
+        <div ref={containerRef} className="h-full w-full" data-opengeni-terminal />
+      </div>
+    </div>
+  );
+}
+
+// xterm.js ships a stylesheet (`@xterm/xterm/css/xterm.css`) that is REQUIRED for
+// correct layout — without it the `.xterm-helper-textarea` (an off-screen input
+// xterm uses for IME/keystrokes) is NOT clipped and renders as a visible 1-line
+// box in the top-left (the "weird input box" bug), and the viewport/screen aren't
+// positioned. The host app never imports that CSS (no global stylesheet here), so
+// we inject the structural rules once, idempotently (keyed by id), the first time
+// any terminal mounts. Scoped under `.xterm` so it can't leak into host styles.
+const XTERM_STYLE_ID = "opengeni-xterm-base-css";
+const XTERM_BASE_CSS = `
+.xterm{cursor:text;position:relative;user-select:none;-ms-user-select:none;-webkit-user-select:none}
+.xterm.focus,.xterm:focus{outline:none}
+.xterm .xterm-helpers{position:absolute;top:0;z-index:5}
+.xterm .xterm-helper-textarea{padding:0;border:0;margin:0;position:absolute;opacity:0;left:-9999em;top:0;width:0;height:0;z-index:-5;white-space:nowrap;overflow:hidden;resize:none}
+.xterm .composition-view{background:#000;color:#FFF;display:none;position:absolute;white-space:nowrap;z-index:1}
+.xterm .composition-view.active{display:block}
+.xterm .xterm-viewport{background-color:transparent;overflow-y:scroll;cursor:default;position:absolute;right:0;left:0;top:0;bottom:0}
+.xterm .xterm-screen{position:relative}
+.xterm .xterm-screen canvas{position:absolute;left:0;top:0}
+.xterm .xterm-scroll-area{visibility:hidden}
+.xterm-char-measure-element{display:inline-block;visibility:hidden;position:absolute;top:0;left:-9999em;line-height:normal}
+.xterm.enable-mouse-events{cursor:default}
+.xterm.xterm-cursor-pointer,.xterm .xterm-cursor-pointer{cursor:pointer}
+.xterm.column-select.focus{cursor:crosshair}
+.xterm .xterm-accessibility:not(.debug),.xterm .xterm-message{position:absolute;left:0;top:0;bottom:0;right:0;z-index:10;color:transparent;pointer-events:none}
+.xterm .xterm-accessibility-tree:not(.debug) *::selection{color:transparent}
+.xterm .xterm-accessibility-tree{user-select:text;white-space:pre}
+.xterm .live-region{position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden}
+.xterm-dim{opacity:1!important}
+.xterm-underline-1{text-decoration:underline}
+.xterm-underline-2{text-decoration:double underline}
+.xterm-underline-3{text-decoration:wavy underline}
+.xterm-underline-4{text-decoration:dotted underline}
+.xterm-underline-5{text-decoration:dashed underline}
+.xterm-overline{text-decoration:overline}
+.xterm-strikethrough{text-decoration:line-through}
+.xterm-screen .xterm-decoration-container .xterm-decoration{z-index:6;position:absolute}
+.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer{z-index:7}
+.xterm-decoration-overview-ruler{z-index:8;position:absolute;top:0;right:0;pointer-events:none}
+.xterm-decoration-top{z-index:2;position:relative}
+`;
+
+function ensureXtermBaseCss(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(XTERM_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = XTERM_STYLE_ID;
+  style.textContent = XTERM_BASE_CSS;
+  document.head.appendChild(style);
+}
+
+function TerminalPlaceholder() {
+  return (
+    <div className="absolute inset-0 flex items-center justify-center text-xs text-[color:var(--og-color-fg-subtle,var(--color-fg-subtle,#888))]">
+      Loading terminal…
+    </div>
+  );
+}

package/src/components/workspace-dock.tsx

@@ -0,0 +1,247 @@
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react";
+import {
+  ChevronsLeftRightIcon,
+  Maximize2Icon,
+  Minimize2Icon,
+  PanelRightCloseIcon,
+} from "lucide-react";
+import {
+  Group,
+  Panel,
+  Separator,
+  useDefaultLayout,
+  usePanelRef,
+} from "react-resizable-panels";
+import { cn } from "../lib/cn";
+
+export type WorkspaceTab = {
+  id: string;
+  label: ReactNode;
+  /** Rendered as the active surface. */
+  content: ReactNode;
+  /** A small badge after the label (e.g. dirty count, live pill). */
+  badge?: ReactNode | undefined;
+};
+
+export type WorkspaceDockProps = {
+  /** The chat / primary pane shown beside the dock. */
+  primary: ReactNode;
+  tabs: WorkspaceTab[];
+  /** Controlled active tab. Falls back to the first tab. */
+  activeTab?: string | undefined;
+  onActiveTabChange?: ((id: string) => void) | undefined;
+  /** Persisted layout id (localStorage key) for react-resizable-panels. */
+  autoSaveId?: string | undefined;
+  /** Default dock width as a percent of the session area. */
+  defaultSize?: number | undefined;
+  minSize?: number | undefined;
+  maxSize?: number | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * The resizable / collapsible / maximizable right-hand Workspace dock. Replaces
+ * a fixed grid column: drag the separator to set width, collapse to a thin rail
+ * that re-opens on click, and maximize to a full-workspace overlay (Esc /
+ * restore button returns). Layout persists via `useDefaultLayout` keyed on
+ * `autoSaveId`. Maximize is a mode ABOVE the Group (a `fixed inset-0` overlay) —
+ * pushing a Panel to ~100% still fights min sizes and leaves a chat sliver.
+ */
+export function WorkspaceDock({
+  primary,
+  tabs,
+  activeTab,
+  onActiveTabChange,
+  autoSaveId = "og.session.dock",
+  defaultSize = 34,
+  minSize = 22,
+  maxSize = 70,
+  className,
+}: WorkspaceDockProps) {
+  const dockPanelRef = usePanelRef();
+  const [collapsed, setCollapsed] = useState(false);
+  const [maximized, setMaximized] = useState(false);
+  const [internalTab, setInternalTab] = useState(tabs[0]?.id ?? "");
+
+  // Persisted layout (width split) keyed by autoSaveId.
+  const { defaultLayout, onLayoutChanged } = useDefaultLayout({
+    panelIds: ["primary", "dock"],
+    storage: typeof window !== "undefined" ? window.localStorage : undefined,
+    id: autoSaveId,
+  } as Parameters<typeof useDefaultLayout>[0]);
+
+  const current = activeTab ?? internalTab;
+  const setTab = useCallback(
+    (id: string) => {
+      setInternalTab(id);
+      onActiveTabChange?.(id);
+    },
+    [onActiveTabChange],
+  );
+
+  // Keep the active tab valid if the available tabs change.
+  useEffect(() => {
+    if (tabs.length > 0 && !tabs.some((t) => t.id === current)) {
+      setTab(tabs[0]!.id);
+    }
+  }, [tabs, current, setTab]);
+
+  // Esc restores from maximize.
+  useEffect(() => {
+    if (!maximized) return;
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setMaximized(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [maximized]);
+
+  const collapse = useCallback(() => {
+    dockPanelRef.current?.collapse();
+    setCollapsed(true);
+  }, [dockPanelRef]);
+  const expand = useCallback(() => {
+    dockPanelRef.current?.expand();
+    setCollapsed(false);
+  }, [dockPanelRef]);
+
+  const dockChrome = (
+    <DockChrome
+      tabs={tabs}
+      current={current}
+      onTab={setTab}
+      maximized={maximized}
+      onToggleMaximize={() => setMaximized((m) => !m)}
+      onCollapse={maximized ? () => setMaximized(false) : collapse}
+    />
+  );
+
+  return (
+    <div className={cn("relative flex h-full min-h-0 w-full min-w-0", className)}>
+      <Group
+        orientation="horizontal"
+        className="min-h-0 flex-1"
+        {...(defaultLayout ? { defaultLayout } : {})}
+        onLayoutChanged={onLayoutChanged}
+      >
+        <Panel id="primary" minSize="30%" className="min-h-0 min-w-0">
+          {primary}
+        </Panel>
+
+        {!collapsed && (
+          <Separator className="group relative w-1.5 shrink-0 outline-none">
+            <span className="absolute inset-y-0 left-1/2 w-px -translate-x-1/2 bg-[color:var(--og-color-border,var(--color-border,#2a2a2a))] transition-colors group-hover:bg-[color:var(--og-color-accent,var(--color-brand,#3b82f6))] group-data-[separator-state=dragging]:bg-[color:var(--og-color-accent,var(--color-brand,#3b82f6))]" />
+          </Separator>
+        )}
+
+        <Panel
+          id="dock"
+          panelRef={dockPanelRef}
+          collapsible
+          collapsedSize="0%"
+          defaultSize={`${defaultSize}%`}
+          minSize={`${minSize}%`}
+          maxSize={`${maxSize}%`}
+          onResize={(size) => {
+            // `asPercentage` is 0..100; treat a near-zero panel as collapsed.
+            const isCollapsed = size.asPercentage <= 1;
+            setCollapsed((prev) => (prev !== isCollapsed ? isCollapsed : prev));
+          }}
+          className="min-h-0 min-w-0"
+        >
+          {/* Hidden behind the overlay while maximized (avoids double-mounting
+              the surfaces). */}
+          {!maximized && (
+            <div className="flex h-full min-h-0 min-w-0 flex-col border-l border-[color:var(--og-color-border,var(--color-border,#2a2a2a))] bg-[color:var(--og-color-bg,var(--color-bg,#0d0d0d))]">
+              {dockChrome}
+            </div>
+          )}
+        </Panel>
+      </Group>
+
+      {/* Collapsed rail: a thin tab on the right edge that re-opens the dock. */}
+      {collapsed && !maximized && (
+        <button
+          type="button"
+          onClick={expand}
+          title="Open workspace"
+          className="absolute inset-y-0 right-0 flex w-6 shrink-0 items-center justify-center border-l border-[color:var(--og-color-border,var(--color-border,#2a2a2a))] bg-[color:var(--og-color-surface-1,var(--color-surface,#161616))] text-[color:var(--og-color-fg-subtle,var(--color-fg-subtle,#888))] hover:text-[color:var(--og-color-fg,var(--color-fg,#e6e6e6))]"
+        >
+          <ChevronsLeftRightIcon className="size-3.5" />
+        </button>
+      )}
+
+      {/* Maximize overlay: full-workspace surface above everything. */}
+      {maximized && (
+        <div className="fixed inset-0 z-40 flex flex-col bg-[color:var(--og-color-bg,var(--color-bg,#0d0d0d))]">
+          {dockChrome}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function DockChrome({
+  tabs,
+  current,
+  onTab,
+  maximized,
+  onToggleMaximize,
+  onCollapse,
+}: {
+  tabs: WorkspaceTab[];
+  current: string;
+  onTab: (id: string) => void;
+  maximized: boolean;
+  onToggleMaximize: () => void;
+  onCollapse: () => void;
+}) {
+  const active = tabs.find((t) => t.id === current) ?? tabs[0];
+  return (
+    <>
+      <div className="flex shrink-0 items-center justify-between gap-2 border-b border-[color:var(--og-color-border,var(--color-border,#2a2a2a))] px-1.5 py-1">
+        <div className="flex min-w-0 items-center gap-0.5" role="tablist">
+          {tabs.map((tab) => (
+            <button
+              key={tab.id}
+              type="button"
+              role="tab"
+              aria-selected={tab.id === current}
+              onClick={() => onTab(tab.id)}
+              className={cn(
+                "flex items-center gap-1 rounded-[var(--og-radius-sm,4px)] px-2 py-1 text-[11px] font-medium transition-colors",
+                tab.id === current
+                  ? "bg-[color:var(--og-color-accent-soft,var(--color-surface-2,#222))] text-[color:var(--og-color-fg,var(--color-fg,#e6e6e6))]"
+                  : "text-[color:var(--og-color-fg-subtle,var(--color-fg-subtle,#888))] hover:text-[color:var(--og-color-fg,var(--color-fg,#e6e6e6))]",
+              )}
+            >
+              <span className="truncate">{tab.label}</span>
+              {tab.badge}
+            </button>
+          ))}
+        </div>
+        <div className="flex shrink-0 items-center gap-0.5 text-[color:var(--og-color-fg-subtle,var(--color-fg-subtle,#888))]">
+          <button
+            type="button"
+            onClick={onToggleMaximize}
+            title={maximized ? "Restore (Esc)" : "Maximize"}
+            className="rounded-[var(--og-radius-sm,4px)] p-1 hover:bg-[color:var(--og-color-surface-2,var(--color-surface-2,#222))] hover:text-[color:var(--og-color-fg,var(--color-fg,#e6e6e6))]"
+          >
+            {maximized ? <Minimize2Icon className="size-3.5" /> : <Maximize2Icon className="size-3.5" />}
+          </button>
+          <button
+            type="button"
+            onClick={onCollapse}
+            title={maximized ? "Restore" : "Collapse"}
+            className="rounded-[var(--og-radius-sm,4px)] p-1 hover:bg-[color:var(--og-color-surface-2,var(--color-surface-2,#222))] hover:text-[color:var(--og-color-fg,var(--color-fg,#e6e6e6))]"
+          >
+            <PanelRightCloseIcon className="size-3.5" />
+          </button>
+        </div>
+      </div>
+      <div className="min-h-0 min-w-0 flex-1 overflow-hidden" role="tabpanel">
+        {active?.content}
+      </div>
+    </>
+  );
+}