@spunto/design-system 0.9.1 → 0.9.3

package/README.md

@@ -54,7 +54,15 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   - _Terminal_ — `Terminal` (+`TerminalHandle`, `TerminalOptions`), a transport-agnostic
     xterm.js surface: mount, shared dark ANSI theme, fit-on-resize. No opinion on where
     bytes come from (WebSocket, SSE, a static string) — feed it via the `write`/`writeln`
-    ref handle. Opt-in addons through `options` (currently `webLinks`, clickable URLs).
+    ref handle. Opt-in addons through `options` (`webLinks` for clickable URLs, `search`
+    for the find API). The handle also reads the buffer back (`getContent`, for copy/
+    download) and reports viewport movement (`onViewportChange`, for tail following).
+  - _TerminalPanel_ — `TerminalPanel` (+`TerminalPanelStatus`), the **frame** around a
+    `Terminal`: a composable bar (title, mono subtitle, status dot, reconnect, free
+    `actions` slot) and the states pages used to re-improvise — `placeholder`/`loading`
+    instead of an ad-hoc empty box, `status` instead of `[connection closed]` written in
+    ANSI into the log. Opt-in bar tools, all off by default: `search`, `followTail`,
+    `copy`, `download`. Its ref *is* the wrapped `TerminalHandle`.
   - _ImagePull_ — `ImagePull` (+`PullLayer`, `PullLayerStatus`, `ImagePullState`), a Docker
     image pull drawn as a real UI instead of ANSI art redrawn in a terminal: **one** overall
     bar whose colour follows the phase (flame downloading → amber unpacking over it → solid
@@ -167,7 +175,7 @@ automatically (see `showcase/vite-plugin-llms.ts`).
 ## Peer requirements
 
 - React 19+, and a **Tailwind CSS v4** pipeline in the consuming app.
-- `lucide-react` is a **regular dependency** (since `0.9.0`): the worker
+- `lucide-react` is a **regular dependency** (since `0.9.3`): the worker
   components use ~15 icons, and inlining them as SVG or passing them all as props
   would have been worse than the dependency. It's tree-shakable and both apps
   already ship it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -53,6 +53,7 @@
   },
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-search": "^0.16.0",
     "@xterm/addon-web-links": "^0.12.0",
     "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",

package/src/components/terminal-panel.tsx

@@ -0,0 +1,695 @@
+"use client"
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react"
+
+import { cn } from "../utils"
+import { Spinner } from "./spinner"
+import { Terminal, type TerminalHandle, type TerminalOptions, type TerminalViewportState } from "./terminal"
+
+// Same surface as `Terminal` and `ImagePull` (#09090b), on purpose: an ImagePull
+// stacked on a TerminalPanel has to read as *one* object — that's the build view.
+// The bar is not a lighter "chrome" strip; it's the same surface, separated by a
+// single hairline, so the eye sees one panel rather than a widget with a header.
+const panelTheme = {
+  background: "#09090b",
+  border: "#27272a",
+  /** Hairline between the bar and the terminal — dimmer than the outer border. */
+  divider: "#1f1f23",
+  text: "#e4e4e7",
+  dim: "#a1a1aa",
+  faint: "#71717a",
+  // Status hues, taken from the Terminal's shared ANSI palette so a green dot up
+  // here and a green line down there are the same green.
+  live: "#4ade80",
+  pending: "#facc15",
+  error: "#f87171",
+  idle: "#52525b",
+  accent: "#ea5400",
+} as const
+
+/**
+ * Connection/lifecycle state of whatever feeds the terminal.
+ *
+ * The first four are the stream states every log panel already tracked by hand;
+ * the last three are build/job states (the worker page draws its own pulsing
+ * yellow/green/red dot for exactly this). They share one prop because they share
+ * one slot in the bar — a panel is never both connecting *and* building.
+ */
+export type TerminalPanelStatus =
+  | "idle"
+  | "connecting"
+  | "live"
+  | "closed"
+  | "error"
+  | "running"
+  | "success"
+  | "failed"
+
+export interface TerminalPanelProps {
+  /** Left of the bar. Sans-serif, the human name of what you're looking at. */
+  title?: ReactNode
+  /** Next to the title, mono and dimmed — `stdout / stderr`, a service name, a session. */
+  subtitle?: ReactNode
+  status?: TerminalPanelStatus
+  /** Overrides the default wording of `status` (which is French, like the rest of the DS). */
+  statusLabel?: string
+  /**
+   * Shows the reconnect button. This is the one action the DS knows about,
+   * because every panel already had its own copy of it.
+   */
+  onReconnect?: () => void
+  /** Free slot at the right of the bar — fullscreen, details, whatever the page owns. */
+  actions?: ReactNode
+  /**
+   * Replaces the terminal surface entirely: "aucun conteneur", "Pulling image…".
+   * The terminal is *unmounted* while it shows, so anything written meanwhile is
+   * dropped — which is the point: there is nothing to write to yet.
+   */
+  placeholder?: ReactNode
+  /** Puts a spinner above `placeholder` — the "…en cours" flavour of empty. */
+  loading?: boolean
+  /** Red band under the bar. Unlike `placeholder`, it keeps the log visible underneath. */
+  error?: string
+
+  // ── Bar options. All off by default: the bar starts sober, each page opts in. ──
+  /** Ctrl/⌘+F search bar over the scrollback (`@xterm/addon-search`). */
+  search?: boolean
+  /** Sticks to the tail and surfaces a "N nouvelles lignes ↓" pill once the user scrolls up. */
+  followTail?: boolean
+  /** Copies the whole buffer to the clipboard. */
+  copy?: boolean
+  /** Downloads the whole buffer as a `.log` file. */
+  download?: boolean
+  /** File name used by `download`. Defaults to the title/subtitle, else `terminal.log`. */
+  downloadFileName?: string
+
+  // ── Forwarded to the underlying `Terminal`. ──
+  fontSize?: number
+  scrollback?: number
+  onData?: (data: string) => void
+  onResize?: (size: { cols: number; rows: number }) => void
+  options?: TerminalOptions
+  className?: string
+}
+
+const STATUS_LABEL: Record<TerminalPanelStatus, string> = {
+  idle: "",
+  connecting: "connexion…",
+  live: "en direct",
+  closed: "déconnecté",
+  error: "erreur",
+  running: "en cours",
+  success: "terminé",
+  failed: "échec",
+}
+
+const STATUS_COLOR: Record<TerminalPanelStatus, string> = {
+  idle: panelTheme.idle,
+  connecting: panelTheme.pending,
+  live: panelTheme.live,
+  closed: panelTheme.idle,
+  error: panelTheme.error,
+  running: panelTheme.pending,
+  success: panelTheme.live,
+  failed: panelTheme.error,
+}
+
+/** The states where something is still happening — the dot pulses for those only. */
+const PULSING: TerminalPanelStatus[] = ["connecting", "running"]
+
+/**
+ * The frame around a `Terminal`: a bar on top, the terminal surface below, and
+ * the states (connecting, empty, loading, error) held by the component instead of
+ * re-improvised on every page.
+ *
+ * It exists because the frame *was* the duplicated part. The primitive is fine —
+ * every page kept it and rebuilt the same header around it: a title, a status
+ * dot, a reconnect button, an "aucun conteneur" placeholder, each with its own
+ * hardcoded hex and padding. Two pages, two looks, one intention.
+ *
+ * Two design decisions worth knowing before extending it:
+ *
+ *  1. **The bar is composable, not a fixed list.** Title/subtitle/status are the
+ *     sober default; everything else (search, follow, copy, download) is opt-in,
+ *     and `actions` is an open slot so a page can push its own buttons without
+ *     the DS having to know about them.
+ *  2. **Connection status is a prop, not log content.** Panels used to write
+ *     `[connection closed]` in ANSI straight into the buffer — which pollutes the
+ *     log, travels with a copy/paste, and stacks up one line per reconnect since
+ *     nothing ever erases it. `status` puts that in the bar, where it can be
+ *     *replaced* instead of appended.
+ *
+ * The ref is the `TerminalHandle` of the terminal it wraps, so migrating a panel
+ * is a one-line swap: `<Terminal ref={r} …/>` → `<TerminalPanel ref={r} …/>`.
+ */
+const TerminalPanel = forwardRef<TerminalHandle, TerminalPanelProps>(function TerminalPanel(
+  {
+    title,
+    subtitle,
+    status = "idle",
+    statusLabel,
+    onReconnect,
+    actions,
+    placeholder,
+    loading,
+    error,
+    search,
+    followTail,
+    copy,
+    download,
+    downloadFileName,
+    fontSize,
+    scrollback,
+    onData,
+    onResize,
+    options,
+    className,
+  },
+  ref
+) {
+  const termRef = useRef<TerminalHandle>(null)
+  const rootRef = useRef<HTMLDivElement>(null)
+
+  // Everything the ref exposes goes through the inner terminal — including while
+  // it's replaced by a placeholder, where the calls simply no-op.
+  useImperativeHandle(ref, () => ({
+    write: (data) => termRef.current?.write(data),
+    writeln: (data) => termRef.current?.writeln(data),
+    clear: () => termRef.current?.clear(),
+    focus: () => termRef.current?.focus(),
+    getContent: () => termRef.current?.getContent() ?? "",
+    scrollToBottom: () => termRef.current?.scrollToBottom(),
+    rowsBelow: () => termRef.current?.rowsBelow() ?? 0,
+    findNext: (query, opts) => termRef.current?.findNext(query, opts) ?? false,
+    findPrevious: (query, opts) => termRef.current?.findPrevious(query, opts) ?? false,
+    clearSearch: () => termRef.current?.clearSearch(),
+  }))
+
+  const searchUi = useSearch(termRef, !!search, rootRef)
+  const tail = useFollowTail(termRef, !!followTail)
+
+  const showPlaceholder = placeholder != null || loading
+  const hasBar = title != null || subtitle != null || status !== "idle" || !!actions || !!onReconnect || !!search || !!copy || !!download
+
+  return (
+    <div
+      ref={rootRef}
+      data-slot="terminal-panel"
+      className={cn(
+        // Square by default like `Terminal`/`ImagePull` — consumers add
+        // `rounded-*` (with the `overflow-hidden` already here) when they want it.
+        // `@container`: what has to fit is this box, not the viewport — a 380 px
+        // panel on a desktop is exactly as cramped as a phone.
+        "@container flex h-full w-full min-h-0 min-w-0 flex-col overflow-hidden border",
+        className
+      )}
+      style={{
+        backgroundColor: panelTheme.background,
+        borderColor: error ? "#7f1d1d" : panelTheme.border,
+        // Sets the default for everything inline (icons draw with currentColor) —
+        // without it they'd inherit the *page's* foreground, which is near-black
+        // in the light theme this dark panel sits in.
+        color: panelTheme.text,
+      }}
+    >
+      {hasBar && (
+        <div
+          className="flex shrink-0 items-center gap-2 border-b px-3 py-1.5 text-xs"
+          style={{ borderColor: panelTheme.divider }}
+        >
+          {status !== "idle" && <StatusChip status={status} label={statusLabel} />}
+          {title != null && (
+            <span className="min-w-0 truncate font-medium" style={{ color: panelTheme.text }}>
+              {title}
+            </span>
+          )}
+          {subtitle != null && (
+            <span className="hidden min-w-0 truncate font-mono @sm:inline" style={{ color: panelTheme.faint }}>
+              {subtitle}
+            </span>
+          )}
+
+          <div className="ml-auto flex shrink-0 items-center gap-0.5">
+            {actions}
+            {search && (
+              <BarButton label="Rechercher (Ctrl+F)" active={searchUi.open} onClick={searchUi.toggle}>
+                <SearchIcon />
+              </BarButton>
+            )}
+            {copy && <CopyButton getContent={() => termRef.current?.getContent() ?? ""} />}
+            {download && (
+              <BarButton
+                label="Télécharger le log"
+                onClick={() =>
+                  downloadText(termRef.current?.getContent() ?? "", downloadFileName ?? defaultFileName(title, subtitle))
+                }
+              >
+                <DownloadIcon />
+              </BarButton>
+            )}
+            {onReconnect && (
+              <BarButton label="Reconnecter" onClick={onReconnect}>
+                <RefreshIcon />
+              </BarButton>
+            )}
+          </div>
+        </div>
+      )}
+
+      {search && searchUi.open && <SearchBar {...searchUi} />}
+
+      {error && (
+        <div
+          className="flex shrink-0 items-start gap-2 border-b px-3 py-2 font-mono text-xs leading-relaxed"
+          style={{ borderColor: "#7f1d1d", backgroundColor: "rgba(127,29,29,0.15)", color: panelTheme.error }}
+        >
+          <span className="shrink-0 pt-px">✕</span>
+          <span className="min-w-0 break-words">{error}</span>
+        </div>
+      )}
+
+      <div className="relative min-h-0 flex-1">
+        {showPlaceholder ? (
+          <div className="flex h-full flex-col items-center justify-center gap-3 px-4 text-center">
+            {loading && <Spinner size="sm" style={{ color: panelTheme.faint }} />}
+            <p className="font-mono text-xs" style={{ color: panelTheme.faint }}>
+              {placeholder}
+            </p>
+          </div>
+        ) : (
+          <>
+            <Terminal
+              ref={termRef}
+              // The panel already draws the border and owns the corners.
+              className="border-0"
+              fontSize={fontSize}
+              scrollback={scrollback}
+              onData={onData}
+              onResize={onResize}
+              options={search ? { ...options, search: true } : options}
+              onViewportChange={followTail ? tail.onViewportChange : undefined}
+              onSearchResults={search ? searchUi.onResults : undefined}
+            />
+            {followTail && tail.detached && (
+              <button
+                type="button"
+                onClick={() => {
+                  termRef.current?.scrollToBottom()
+                  termRef.current?.focus()
+                }}
+                // Right-aligned but clear of xterm's scrollbar, and floating over
+                // the log rather than reserving a row — it's a transient hint.
+                className="absolute bottom-3 right-5 flex items-center gap-1.5 rounded-full border px-2.5 py-1 font-mono text-[11px] shadow-lg transition-colors"
+                style={{
+                  backgroundColor: "#18181b",
+                  borderColor: panelTheme.border,
+                  color: tail.missed > 0 ? panelTheme.text : panelTheme.dim,
+                }}
+              >
+                {tail.missed > 0 ? `${tail.missed} nouvelle${tail.missed > 1 ? "s" : ""} ligne${tail.missed > 1 ? "s" : ""}` : "Revenir en bas"}
+                <ArrowDownIcon />
+              </button>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  )
+})
+
+/** Dot + word. The dot alone carries the state when the container is narrow. */
+function StatusChip({ status, label }: { status: TerminalPanelStatus; label?: string }) {
+  const color = STATUS_COLOR[status]
+  const text = label ?? STATUS_LABEL[status]
+  return (
+    <span className="flex shrink-0 items-center gap-1.5" title={text}>
+      <span
+        // `motion-reduce`: the dot keeps its colour, it just stops breathing —
+        // the state is still readable without the animation.
+        className={cn("size-1.5 shrink-0 rounded-full", PULSING.includes(status) && "animate-pulse motion-reduce:animate-none")}
+        style={{ backgroundColor: color }}
+      />
+      <span className="hidden font-mono @md:inline" style={{ color }}>
+        {text}
+      </span>
+    </span>
+  )
+}
+
+function BarButton({
+  label,
+  active,
+  onClick,
+  children,
+}: {
+  label: string
+  active?: boolean
+  onClick: () => void
+  children: ReactNode
+}) {
+  return (
+    <button
+      type="button"
+      title={label}
+      aria-label={label}
+      onClick={onClick}
+      className="flex size-6 cursor-pointer items-center justify-center rounded transition-colors hover:bg-white/5"
+      style={{ color: active ? panelTheme.accent : panelTheme.faint }}
+    >
+      {children}
+    </button>
+  )
+}
+
+/** Copy with its own "done" beat — a clipboard write is invisible otherwise. */
+function CopyButton({ getContent }: { getContent: () => string }) {
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (!copied) return
+    const id = setTimeout(() => setCopied(false), 1500)
+    return () => clearTimeout(id)
+  }, [copied])
+
+  return (
+    <BarButton
+      label={copied ? "Copié" : "Copier tout le log"}
+      onClick={async () => {
+        if (await copyText(getContent())) setCopied(true)
+      }}
+    >
+      <span style={copied ? { color: panelTheme.live } : undefined}>{copied ? <CheckIcon /> : <CopyIcon />}</span>
+    </BarButton>
+  )
+}
+
+interface SearchUi {
+  open: boolean
+  toggle: () => void
+  close: () => void
+  query: string
+  setQuery: (q: string) => void
+  results: { resultIndex: number; resultCount: number }
+  onResults: (r: { resultIndex: number; resultCount: number }) => void
+  next: () => void
+  previous: () => void
+  inputRef: React.RefObject<HTMLInputElement | null>
+}
+
+/** Its own row under the bar rather than an overlay — a log is dense, and floating
+ *  search boxes end up hiding the match they just found. */
+function SearchBar({ query, setQuery, results, next, previous, close, inputRef }: SearchUi) {
+  const empty = query.length > 0 && results.resultCount === 0
+  return (
+    <div
+      className="flex shrink-0 items-center gap-2 border-b px-3 py-1.5"
+      style={{ borderColor: panelTheme.divider, backgroundColor: "#0c0c10", color: panelTheme.faint }}
+    >
+      <SearchIcon />
+      <input
+        ref={inputRef}
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter") {
+            e.preventDefault()
+            if (e.shiftKey) previous()
+            else next()
+          } else if (e.key === "Escape") {
+            e.preventDefault()
+            close()
+          }
+        }}
+        placeholder="Rechercher dans le log…"
+        spellCheck={false}
+        className="min-w-0 flex-1 bg-transparent font-mono text-xs outline-none placeholder:opacity-60"
+        style={{ color: empty ? panelTheme.error : panelTheme.text }}
+      />
+      <span className="shrink-0 font-mono text-[11px] tabular-nums" style={{ color: empty ? panelTheme.error : panelTheme.faint }}>
+        {query.length === 0 ? "" : results.resultCount === 0 ? "aucun résultat" : `${results.resultIndex + 1}/${results.resultCount}`}
+      </span>
+      <BarButton label="Résultat précédent (Maj+Entrée)" onClick={previous}>
+        <ChevronIcon up />
+      </BarButton>
+      <BarButton label="Résultat suivant (Entrée)" onClick={next}>
+        <ChevronIcon />
+      </BarButton>
+      <BarButton label="Fermer la recherche (Échap)" onClick={close}>
+        <CloseIcon />
+      </BarButton>
+    </div>
+  )
+}
+
+/**
+ * Search state + the Ctrl/⌘+F binding. The shortcut is bound on the panel root in
+ * the capture phase: xterm owns the keyboard once focused, so waiting for the
+ * event to bubble means never seeing it.
+ */
+function useSearch(termRef: React.RefObject<TerminalHandle | null>, enabled: boolean, rootRef: React.RefObject<HTMLDivElement | null>): SearchUi {
+  const [open, setOpen] = useState(false)
+  const [query, setQueryState] = useState("")
+  const [results, setResults] = useState({ resultIndex: -1, resultCount: 0 })
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  const close = useCallback(() => {
+    setOpen(false)
+    setQueryState("")
+    setResults({ resultIndex: -1, resultCount: 0 })
+    termRef.current?.clearSearch()
+    termRef.current?.focus()
+  }, [termRef])
+
+  const toggle = useCallback(() => {
+    setOpen((v) => {
+      if (v) {
+        termRef.current?.clearSearch()
+        return false
+      }
+      return true
+    })
+  }, [termRef])
+
+  useEffect(() => {
+    if (open) inputRef.current?.focus()
+  }, [open])
+
+  useEffect(() => {
+    const root = rootRef.current
+    if (!enabled || !root) return
+    function onKeyDown(e: KeyboardEvent) {
+      if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "f") {
+        e.preventDefault()
+        e.stopPropagation()
+        setOpen(true)
+        // Already open: re-select so a second Ctrl+F starts a new query.
+        inputRef.current?.select()
+      }
+    }
+    root.addEventListener("keydown", onKeyDown, true)
+    return () => root.removeEventListener("keydown", onKeyDown, true)
+  }, [enabled, rootRef])
+
+  const setQuery = useCallback(
+    (q: string) => {
+      setQueryState(q)
+      if (q) {
+        // `incremental` keeps the match anchored where you are while you type,
+        // instead of walking forward one match per keystroke.
+        termRef.current?.findNext(q, { incremental: true })
+      } else {
+        termRef.current?.clearSearch()
+        setResults({ resultIndex: -1, resultCount: 0 })
+      }
+    },
+    [termRef]
+  )
+
+  return {
+    open,
+    toggle,
+    close,
+    query,
+    setQuery,
+    results,
+    onResults: setResults,
+    next: () => query && termRef.current?.findNext(query),
+    previous: () => query && termRef.current?.findPrevious(query),
+    inputRef,
+  }
+}
+
+/**
+ * "Am I still at the tail, and how much have I missed?"
+ *
+ * The counter is *lines since the viewport last touched the bottom* — the reason
+ * flag from the terminal is what makes that computable: output events increment,
+ * and any moment spent at the bottom (scrolled back, or never left) resets. A busy
+ * stream fires this per line, so the count accumulates in a ref and only lands in
+ * state once per frame.
+ */
+function useFollowTail(termRef: React.RefObject<TerminalHandle | null>, enabled: boolean) {
+  const [state, setState] = useState({ detached: false, missed: 0 })
+  const pending = useRef({ detached: false, missed: 0 })
+  const frame = useRef<number | null>(null)
+
+  useEffect(
+    () => () => {
+      if (frame.current != null) cancelAnimationFrame(frame.current)
+    },
+    []
+  )
+
+  const onViewportChange = useCallback((v: TerminalViewportState) => {
+    const p = pending.current
+    if (v.rowsBelow === 0) p.missed = 0
+    else if (v.reason === "output") p.missed += 1
+    p.detached = v.rowsBelow > 0
+
+    if (frame.current != null) return
+    frame.current = requestAnimationFrame(() => {
+      frame.current = null
+      setState((prev) =>
+        prev.detached === pending.current.detached && prev.missed === pending.current.missed
+          ? prev
+          : { ...pending.current }
+      )
+    })
+  }, [])
+
+  return useMemo(
+    () => ({ ...state, onViewportChange: enabled ? onViewportChange : undefined }),
+    [state, enabled, onViewportChange]
+  )
+}
+
+/** Clipboard API, with the `execCommand` fallback for non-secure contexts. */
+async function copyText(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text)
+    return true
+  } catch {
+    try {
+      const area = document.createElement("textarea")
+      area.value = text
+      area.style.position = "fixed"
+      area.style.opacity = "0"
+      document.body.appendChild(area)
+      area.select()
+      const ok = document.execCommand("copy")
+      document.body.removeChild(area)
+      return ok
+    } catch {
+      return false
+    }
+  }
+}
+
+function downloadText(text: string, fileName: string) {
+  const url = URL.createObjectURL(new Blob([text], { type: "text/plain;charset=utf-8" }))
+  const link = document.createElement("a")
+  link.href = url
+  link.download = fileName
+  link.click()
+  URL.revokeObjectURL(url)
+}
+
+/** `service api — stdout / stderr` → `service-api-stdout-stderr.log`. */
+function defaultFileName(title: ReactNode, subtitle: ReactNode): string {
+  const parts = [title, subtitle].filter((p) => typeof p === "string") as string[]
+  const slug = parts
+    .join("-")
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+  return `${slug || "terminal"}.log`
+}
+
+// ── Icons. Inlined like `ImagePull`'s: the design system doesn't take an icon
+// dependency, and these five never leave this file. ──
+
+function SearchIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3.5 shrink-0" aria-hidden>
+      <circle cx="7" cy="7" r="4.5" stroke="currentColor" strokeWidth="1.5" />
+      <path d="m10.5 10.5 3 3" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function CopyIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3.5 shrink-0" aria-hidden>
+      <rect x="5.5" y="5.5" width="8" height="8" rx="1.5" stroke="currentColor" strokeWidth="1.4" />
+      <path d="M10.5 2.5h-8v8" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+function CheckIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3.5 shrink-0" aria-hidden>
+      <path d="m3.5 8.5 3 3 6-7" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+function DownloadIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3.5 shrink-0" aria-hidden>
+      <path d="M8 2.5v7m0 0L5 6.7M8 9.5l3-2.8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M2.8 12.5h10.4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function RefreshIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3.5 shrink-0" aria-hidden>
+      <path
+        d="M13 8a5 5 0 1 1-1.6-3.7"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+      <path d="M13.2 2v3h-3" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+function ChevronIcon({ up }: { up?: boolean }) {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className={cn("size-3.5 shrink-0", up && "rotate-180")} aria-hidden>
+      <path d="m4 6.5 4 4 4-4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+function ArrowDownIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3 shrink-0" aria-hidden>
+      <path d="M8 3v9m0 0 3.5-3.5M8 12 4.5 8.5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+function CloseIcon() {
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className="size-3.5 shrink-0" aria-hidden>
+      <path d="m4.5 4.5 7 7m0-7-7 7" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+export { TerminalPanel }

package/src/components/terminal.tsx

@@ -2,6 +2,7 @@
 
 import { forwardRef, useEffect, useImperativeHandle, useRef } from "react"
 import type { Terminal as XTerm } from "@xterm/xterm"
+import type { SearchAddon } from "@xterm/addon-search"
 // xterm.js's own stylesheet — hides its input-capture textarea and glyph
 // measurement helpers. A JS-side import (not a CSS `@import`) so it loads
 // regardless of the consuming app's stylesheet pipeline/ordering.
@@ -34,17 +35,55 @@ const terminalTheme = {
   brightWhite: "#f4f4f5",
 }
 
+export interface TerminalSearchOptions {
+  caseSensitive?: boolean
+  wholeWord?: boolean
+  regex?: boolean
+  /** Re-runs from the current match rather than the next one — for search-as-you-type. */
+  incremental?: boolean
+}
+
+/** What `onViewportChange` reports. See that prop for why both fields are needed. */
+export interface TerminalViewportState {
+  /** Rows between the bottom of the viewport and the end of the buffer. 0 = stuck to the tail. */
+  rowsBelow: number
+  /** `"output"` = a new line was printed · `"scroll"` = the viewport itself moved. */
+  reason: "output" | "scroll"
+}
+
 export interface TerminalHandle {
   /** Writes raw bytes/text (ANSI sequences included) to the terminal. */
   write: (data: string | Uint8Array) => void
   writeln: (data: string) => void
   clear: () => void
   focus: () => void
+  /**
+   * The whole scrollback as plain text — ANSI stripped, rows that xterm split at
+   * the viewport width rejoined into the single line they were written as. This
+   * is what "copy everything" / "download the log" need, and neither can be done
+   * from outside: only xterm holds the buffer.
+   */
+  getContent: () => string
+  /** Jumps the viewport back to the tail of the buffer (the "follow" button). */
+  scrollToBottom: () => void
+  /** Same number as `TerminalViewportState.rowsBelow`, polled instead of pushed. */
+  rowsBelow: () => number
+  /**
+   * Search, delegated to `@xterm/addon-search`. No-ops (returns false) unless
+   * `options.search` was set at mount — the addon isn't loaded otherwise.
+   * Match highlighting/colors are handled inside; callers only pass the query.
+   */
+  findNext: (query: string, options?: TerminalSearchOptions) => boolean
+  findPrevious: (query: string, options?: TerminalSearchOptions) => boolean
+  /** Drops the highlights — call it when the search UI closes. */
+  clearSearch: () => void
 }
 
 export interface TerminalOptions {
   /** Turns URLs in terminal output into clickable links (`@xterm/addon-web-links`). */
   webLinks?: boolean
+  /** Loads `@xterm/addon-search`, which powers the `findNext`/`findPrevious` handle. */
+  search?: boolean
 }
 
 export interface TerminalProps {
@@ -63,6 +102,27 @@ export interface TerminalProps {
    * props here.
    */
   options?: TerminalOptions
+  /**
+   * Fires whenever the buffer grows or the viewport moves. Exists for one job:
+   * letting a wrapper (`TerminalPanel`) answer "is the user still watching the
+   * tail, and how much have they missed?" — xterm never scrolls the user down by
+   * force, but it also never tells them lines are piling up below.
+   *
+   * `reason` is what makes the count possible: an `"output"` event means one more
+   * missed line, a `"scroll"` event means the user moved on purpose and the count
+   * should re-baseline. It fires per line feed on a busy stream, so coalesce
+   * (rAF/ref) rather than calling `setState` straight from it.
+   */
+  onViewportChange?: (state: TerminalViewportState) => void
+  /**
+   * New grid size after a fit — i.e. after the container resized. An interactive
+   * consumer has to forward this to whatever is on the other end (a PTY sizes its
+   * output to the client's grid), and `fit()` happens in here, so nowhere else can
+   * observe it. Also fires once at mount with the initial size.
+   */
+  onResize?: (size: { cols: number; rows: number }) => void
+  /** Match count/position of the running search — only fires when `options.search` is on. */
+  onSearchResults?: (results: { resultIndex: number; resultCount: number }) => void
 }
 
 /**
@@ -72,12 +132,22 @@ export interface TerminalProps {
  * plug in on top.
  */
 const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
-  { className, fontSize = 13, scrollback = 5000, onData, options },
+  { className, fontSize = 13, scrollback = 5000, onData, options, onViewportChange, onResize, onSearchResults },
   ref
 ) {
   const outerRef = useRef<HTMLDivElement>(null)
   const mountRef = useRef<HTMLDivElement>(null)
   const termRef = useRef<XTerm | null>(null)
+  const searchRef = useRef<SearchAddon | null>(null)
+  // xterm's event handlers are wired once at mount, but these two callbacks come
+  // from a consumer that re-renders — read them through refs so a new closure
+  // doesn't require tearing the terminal down.
+  const viewportCbRef = useRef(onViewportChange)
+  const resizeCbRef = useRef(onResize)
+  const searchCbRef = useRef(onSearchResults)
+  viewportCbRef.current = onViewportChange
+  resizeCbRef.current = onResize
+  searchCbRef.current = onSearchResults
   // xterm mounts asynchronously (dynamic import); a consumer wiring up a
   // transport (WebSocket, SSE...) in its own effect can easily win that race
   // and call write() before termRef exists. Queue those calls instead of
@@ -97,6 +167,12 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
       },
       clear: () => termRef.current?.clear(),
       focus: () => termRef.current?.focus(),
+      getContent: () => (termRef.current ? bufferToText(termRef.current) : ""),
+      scrollToBottom: () => termRef.current?.scrollToBottom(),
+      rowsBelow: () => (termRef.current ? rowsBelowViewport(termRef.current) : 0),
+      findNext: (query, opts) => searchRef.current?.findNext(query, searchOptions(opts)) ?? false,
+      findPrevious: (query, opts) => searchRef.current?.findPrevious(query, searchOptions(opts)) ?? false,
+      clearSearch: () => searchRef.current?.clearDecorations(),
     }),
     []
   )
@@ -133,6 +209,9 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
         lineHeight: 1.2,
         scrollback,
         theme: terminalTheme,
+        // Only the search addon needs it (its match highlighting goes through
+        // the decoration API), so it stays off for everyone else.
+        allowProposedApi: !!options?.search,
       })
 
       const fitAddon = new FitAddon()
@@ -141,6 +220,13 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
         const { WebLinksAddon } = await import("@xterm/addon-web-links")
         term.loadAddon(new WebLinksAddon())
       }
+      if (options?.search) {
+        const { SearchAddon } = await import("@xterm/addon-search")
+        const searchAddon = new SearchAddon()
+        term.loadAddon(searchAddon)
+        searchAddon.onDidChangeResults((results) => searchCbRef.current?.(results))
+        searchRef.current = searchAddon
+      }
       // FitAddon computes available space from *this* element's parent minus
       // this element's own padding — it has no idea about an outer wrapper's
       // padding/border. Mounting on a padding-less, border-less inner div (see
@@ -159,6 +245,16 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
 
       if (onData) term.onData(onData)
 
+      // Two events rather than one because they mean opposite things to a tail
+      // follower: a line feed is output the user may be missing, a scroll is the
+      // user deciding where to look.
+      term.onLineFeed(() => viewportCbRef.current?.({ rowsBelow: rowsBelowViewport(term), reason: "output" }))
+      term.onScroll(() => viewportCbRef.current?.({ rowsBelow: rowsBelowViewport(term), reason: "scroll" }))
+      term.onResize((size) => resizeCbRef.current?.(size))
+      // xterm only emits onResize on *changes*, and the first fit() above already
+      // happened — so announce the initial grid explicitly.
+      resizeCbRef.current?.({ cols: term.cols, rows: term.rows })
+
       resizeObserver = new ResizeObserver(() => fitAddon.fit())
       resizeObserver.observe(mountRef.current)
     }
@@ -170,6 +266,7 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
       resizeObserver?.disconnect()
       termRef.current?.dispose()
       termRef.current = null
+      searchRef.current = null
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
@@ -201,4 +298,58 @@ const Terminal = forwardRef<TerminalHandle, TerminalProps>(function Terminal(
   )
 })
 
+/**
+ * Rows between the bottom of the viewport and the end of the buffer. `baseY` is
+ * where the tail starts, `viewportY` where the user is looking — equal means
+ * "stuck to the bottom", which is the state a follow-tail affordance cares about.
+ */
+function rowsBelowViewport(term: XTerm): number {
+  const buffer = term.buffer.active
+  return Math.max(0, buffer.baseY - buffer.viewportY)
+}
+
+/**
+ * The buffer as plain text. Two things xterm won't do for you:
+ *
+ *  - **Rejoin wrapped rows.** A 300-char line is stored as three rows once the
+ *    viewport is 100 columns wide; copying it as three lines would make the
+ *    exported log depend on the window width it was read at.
+ *  - **Drop the empty tail.** The scrollback is pre-allocated, so the last rows
+ *    are blank filler, not log content.
+ */
+function bufferToText(term: XTerm): string {
+  const buffer = term.buffer.active
+  const lines: string[] = []
+
+  for (let i = 0; i < buffer.length; i++) {
+    const line = buffer.getLine(i)
+    if (!line) continue
+    const text = line.translateToString(true)
+    if (line.isWrapped && lines.length > 0) lines[lines.length - 1] += text
+    else lines.push(text)
+  }
+
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop()
+  return lines.join("\n")
+}
+
+/**
+ * Match colors live here, not at the call site: search is a design-system
+ * affordance and every terminal in the product should highlight the same way —
+ * zinc for the other matches, flame for the one you're on.
+ */
+function searchOptions(options?: TerminalSearchOptions) {
+  return {
+    ...options,
+    decorations: {
+      matchBackground: "#3f3f46",
+      matchBorder: "#71717a",
+      matchOverviewRuler: "#a1a1aa",
+      activeMatchBackground: "#ea5400",
+      activeMatchBorder: "#fb923c",
+      activeMatchColorOverviewRuler: "#ea5400",
+    },
+  }
+}
+
 export { Terminal }

package/src/components/workers/git-branch-chips.tsx

@@ -40,7 +40,10 @@ export function GitBranchChips({ repos, repoHref, className }: GitBranchChipsPro
   if (!repos.length) return null
 
   return (
-    <div data-slot="git-branch-chips" className={cn("flex flex-wrap gap-1.5", className)}>
+    // `@container` so the branch cap below reads *this row's* width: the same
+    // chips sit in a 600 px card on a desktop and in a 290 px one on a phone,
+    // and a viewport media query can't tell those apart.
+    <div data-slot="git-branch-chips" className={cn("@container flex flex-wrap gap-1.5", className)}>
       {repos.map((repo) => {
         const href = repoHref?.(repo)
         const Tag = href ? "a" : "span"
@@ -49,17 +52,22 @@ export function GitBranchChips({ repos, repoHref, className }: GitBranchChipsPro
             key={repo.path}
             {...(href ? { href, target: "_blank", rel: "noopener noreferrer" } : {})}
             title={repo.path}
+            // `max-w-full` is what keeps a chip inside the card: without it a
+            // long "repo · branch" is a single unbreakable row that runs under
+            // the card's rounded edge and gets clipped.
             className={cn(
-              "inline-flex items-center gap-1 rounded-md border border-border bg-muted/40 px-2 py-0.5 font-mono text-[11px] text-muted-foreground",
+              "inline-flex min-w-0 max-w-full items-center gap-1 rounded-md border border-border bg-muted/40 px-2 py-0.5 font-mono text-[11px] text-muted-foreground",
               href && "transition-colors hover:border-border/80 hover:bg-muted/70"
             )}
           >
-            <span className="font-medium text-foreground/70">{repoName(repo)}</span>
-            <span className="mx-0.5 text-muted-foreground/40">·</span>
+            <span className="shrink-0 font-medium text-foreground/70">{repoName(repo)}</span>
+            <span className="mx-0.5 shrink-0 text-muted-foreground/40">·</span>
             <GitBranchIcon className="h-2.5 w-2.5 shrink-0" />
-            <span className="max-w-[120px] truncate">{repo.branch || "—"}</span>
+            {/* The branch is the only part allowed to give up room — the repo
+                name and the counters are short and carry more meaning. */}
+            <span className="min-w-0 max-w-[6rem] truncate @min-[20rem]:max-w-[120px]">{repo.branch || "—"}</span>
             <RepoCounters repo={repo} />
-            {href && <ExternalLinkIcon className="ml-0.5 h-2.5 w-2.5 opacity-40" />}
+            {href && <ExternalLinkIcon className="ml-0.5 h-2.5 w-2.5 shrink-0 opacity-40" />}
           </Tag>
         )
       })}
@@ -71,15 +79,15 @@ export function GitBranchChips({ repos, repoHref, className }: GitBranchChipsPro
 function RepoCounters({ repo }: { repo: GitRepoStatus }) {
   return (
     <>
-      {!!repo.modified && <span className="ml-0.5 text-amber-500 dark:text-amber-400">+{repo.modified}</span>}
+      {!!repo.modified && <span className="ml-0.5 shrink-0 text-amber-500 dark:text-amber-400">+{repo.modified}</span>}
       {!!repo.ahead && (
-        <span className="ml-0.5 inline-flex items-center text-amber-500 dark:text-amber-400">
+        <span className="ml-0.5 inline-flex shrink-0 items-center text-amber-500 dark:text-amber-400">
           <ArrowUpIcon className="h-2.5 w-2.5" />
           {repo.ahead}
         </span>
       )}
       {!!repo.behind && (
-        <span className="ml-0.5 inline-flex items-center text-muted-foreground/70">
+        <span className="ml-0.5 inline-flex shrink-0 items-center text-muted-foreground/70">
           <ArrowDownIcon className="h-2.5 w-2.5" />
           {repo.behind}
         </span>

package/src/components/workers/resource-bars.tsx

@@ -33,7 +33,11 @@ export function ResourceBars({ stats, compact = false, className }: ResourceBars
     <div
       data-slot="resource-bars"
       className={cn(
-        "grid grid-cols-2 gap-3",
+        // Side by side as soon as there's room for it, stacked below ~240 px —
+        // under that the label and its figure end up touching. Container query,
+        // not a media query: these bars live in a card, a table cell and a
+        // sidebar, and only their own width tells them what to do.
+        "@container grid grid-cols-1 gap-3 @min-[15rem]:grid-cols-2",
         !compact && "rounded-lg border border-border/40 bg-muted/20 px-3 py-2.5",
         className
       )}
@@ -82,12 +86,12 @@ function Metric({
 }) {
   return (
     <div>
-      <div className="mb-1.5 flex items-center justify-between">
-        <span className="flex items-center gap-1 text-[11px] text-muted-foreground">
+      <div className="mb-1.5 flex items-center justify-between gap-2">
+        <span className="flex min-w-0 items-center gap-1 truncate text-[11px] text-muted-foreground">
           {icon}
           {label}
         </span>
-        <span className={cn("font-mono text-[11px] tabular-nums", valueClass)}>{value}</span>
+        <span className={cn("shrink-0 font-mono text-[11px] tabular-nums", valueClass)}>{value}</span>
       </div>
       <div className="h-1 overflow-hidden rounded-full bg-muted">
         <div

package/src/components/workers/worker-card.tsx

@@ -136,7 +136,14 @@ export function WorkerCard({
   return (
     <div
       data-slot="worker-card"
-      className={cn("overflow-hidden rounded-xl border border-border bg-card transition-colors hover:shadow-sm", className)}
+      // `@container`: every responsive rule below is a container query, never a
+      // viewport one. The same card is a half-width tile on a desktop grid and a
+      // full-width row on a phone — and a 290 px card in a sidebar on a 27"
+      // screen is exactly as cramped as a phone.
+      className={cn(
+        "@container overflow-hidden rounded-xl border border-border bg-card transition-colors hover:shadow-sm",
+        className
+      )}
     >
       {/* ── Header : état, nom, pills, tags, méta ── */}
       <div className="flex items-start justify-between gap-3 px-4 pt-3.5 pb-3">
@@ -145,7 +152,9 @@ export function WorkerCard({
 
           <div className="min-w-0 flex-1">
             <div className="flex flex-wrap items-center gap-2">
-              <span className="text-sm leading-none font-semibold">{title}</span>
+              {/* A worker name is one unbreakable token ("spunto-fix-tunnel-42"):
+                  without the cap it pushes the card wider than its column. */}
+              <span className="max-w-full truncate text-sm leading-none font-semibold">{title}</span>
               <WorkerStatusPill status={status} />
               {worker.projectVersion != null && (
                 <span className="inline-flex items-center rounded-full border border-border bg-muted px-2 py-0.5 font-mono text-[10px] leading-none text-muted-foreground">
@@ -155,46 +164,37 @@ export function WorkerCard({
               <TagChips tags={worker.tags ?? []} onAdd={onAddTag} onRemove={onRemoveTag} />
             </div>
 
-            <div className="mt-1.5 flex flex-wrap items-center gap-2">
+            {/* Meta line. Each item carries its own leading separator instead of
+                the separators being siblings: this row wraps onto two lines as
+                soon as the card is narrow, and a sibling "·" then ends up
+                stranded at the end of a line, pointing at nothing. Attached to
+                the item, the worst case is a line that *starts* with "·", which
+                reads as a continuation. */}
+            <div className="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1">
               {creator && (
-                <span className="flex items-center gap-1.5">
+                <MetaItem first>
                   <CreatorAvatar creator={creator} />
-                  <span className="text-[11px] text-muted-foreground">{creator.name}</span>
-                </span>
+                  <span className="text-muted-foreground">{creator.name}</span>
+                </MetaItem>
               )}
               {nodeName && (
-                <>
-                  <Dot />
-                  <span className="flex items-center gap-1 text-[11px] text-muted-foreground/60">
-                    <ServerIcon className="h-3 w-3" />
-                    {nodeName}
-                  </span>
-                </>
+                <MetaItem first={!creator}>
+                  <ServerIcon className="h-3 w-3 shrink-0" />
+                  <span className="truncate">{nodeName}</span>
+                </MetaItem>
               )}
               {worker.createdAt && (
-                <>
-                  {creator || nodeName ? <Dot /> : null}
-                  <span
-                    className="flex items-center gap-1 text-[11px] text-muted-foreground/60"
-                    title={new Date(worker.createdAt).toLocaleString()}
-                  >
-                    <ClockIcon className="h-3 w-3" />
-                    {formatRelativeTime(worker.createdAt)}
-                  </span>
-                </>
+                <MetaItem first={!creator && !nodeName} title={new Date(worker.createdAt).toLocaleString()}>
+                  <ClockIcon className="h-3 w-3 shrink-0" />
+                  {formatRelativeTime(worker.createdAt)}
+                </MetaItem>
               )}
               {/* Only worth showing once it's over — during setup the live bar says it better. */}
               {!status.settingUp && startupMs != null && (
-                <>
-                  <Dot />
-                  <span
-                    className="flex items-center gap-1 text-[11px] text-muted-foreground/60"
-                    title="Worker startup time (clone, features, postCreate…)"
-                  >
-                    <TimerIcon className="h-3 w-3" />
-                    started in {formatDuration(startupMs)}
-                  </span>
-                </>
+                <MetaItem title="Worker startup time (clone, features, postCreate…)">
+                  <TimerIcon className="h-3 w-3 shrink-0" />
+                  started in {formatDuration(startupMs)}
+                </MetaItem>
               )}
             </div>
           </div>
@@ -223,14 +223,19 @@ export function WorkerCard({
 
       {nodeOnline === false && (
         <Banner tone="offline">
-          <WifiOffIcon className="h-3.5 w-3.5 shrink-0" />
-          Node offline
+          {/* One span, not two children: the banner spreads its children apart,
+              and an icon pinned left with its own label pinned right reads as
+              two unrelated things. */}
+          <span className="flex min-w-0 items-center gap-2">
+            <WifiOffIcon className="h-3.5 w-3.5 shrink-0" />
+            Node offline
+          </span>
         </Banner>
       )}
 
       {outdated && (
         <Banner tone="warn">
-          <span className="flex min-w-0 items-center gap-1.5">
+          <span className="flex min-w-0 flex-1 flex-wrap items-center gap-x-1.5">
             <AlertTriangleIcon className="h-3.5 w-3.5 shrink-0" />
             Config <span className="font-mono font-semibold">v{worker.projectVersion}</span> → project at{" "}
             <span className="font-mono font-semibold">v{currentProjectVersion}</span>
@@ -250,7 +255,9 @@ export function WorkerCard({
 
       {error && (
         <Banner tone="error">
-          <span className="truncate font-mono">{error}</span>
+          {/* Two lines then ellipsis: on a phone a single truncated line of a
+              docker error is almost always cut before the useful part. */}
+          <span className="line-clamp-2 min-w-0 flex-1 font-mono break-words">{error}</span>
           {onDismissError && (
             <button
               type="button"
@@ -278,9 +285,35 @@ export function WorkerCard({
   )
 }
 
-/** The faint separator between two meta items. */
-function Dot() {
-  return <span className="text-[11px] text-muted-foreground/30">·</span>
+/**
+ * One item of the meta line: creator, node, age, startup time.
+ *
+ * The separator is a `::before` on the item rather than a sibling element, so
+ * it can never be left behind at a line break. Below ~22 rem it disappears
+ * entirely: under ~26 rem the row is two lines deep anyway and the icons already tell
+ * the items apart, so the dots are pure noise there.
+ */
+function MetaItem({
+  first = false,
+  title,
+  children,
+}: {
+  first?: boolean
+  title?: string
+  children: ReactNode
+}) {
+  return (
+    <span
+      title={title}
+      className={cn(
+        "flex min-w-0 items-center gap-1 text-[11px] text-muted-foreground/60",
+        !first &&
+          "before:hidden before:text-muted-foreground/30 before:content-['·'] @min-[26rem]:before:mr-1 @min-[26rem]:before:inline"
+      )}
+    >
+      {children}
+    </span>
+  )
 }
 
 /**
@@ -299,6 +332,9 @@ function Banner({ tone, children }: { tone: keyof typeof BANNER_TONES; children:
   return (
     <div
       className={cn(
+        // No `flex-wrap`: the action (Rebuild, ✕) stays on the message's line
+        // whatever happens — wrapping it underneath reads as a second, unrelated
+        // control. The message shrinks and wraps internally instead.
         "mx-4 mb-3 flex items-center justify-between gap-2 rounded-lg border px-3 py-2 text-xs",
         BANNER_TONES[tone]
       )}

package/src/index.ts

@@ -28,7 +28,18 @@ export { Avatar, AvatarImage, AvatarFallback } from "./components/avatar"
 // xterm.js surface — theme + fit-on-resize, transport-agnostic (feed it via
 // the write/writeln ref handle).
 export { Terminal } from "./components/terminal"
-export type { TerminalHandle, TerminalProps, TerminalOptions } from "./components/terminal"
+export type {
+  TerminalHandle,
+  TerminalProps,
+  TerminalOptions,
+  TerminalSearchOptions,
+  TerminalViewportState,
+} from "./components/terminal"
+
+// The frame around a Terminal — bar (title/status/actions) + surface + the
+// connection/empty/loading/error states. Its ref *is* a TerminalHandle.
+export { TerminalPanel } from "./components/terminal-panel"
+export type { TerminalPanelProps, TerminalPanelStatus } from "./components/terminal-panel"
 
 // Docker image pull as a real UI (one segmented bar, one block per layer) —
 // presentational only: give it a snapshot, it draws it.