@spunto/design-system 0.18.1 → 0.20.0

package/README.md

@@ -66,6 +66,21 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     (a confirmation variant, non-dismissible), `Sheet`, `Tooltip`. Their portals render
     into the provider's overlay container; `Tooltip`'s shared delay group is mounted by
     the provider too.
+  - _ActionMenu_ — `ActionMenu` (+`ActionMenuItem`, `ActionMenuEntry`), the `⋯` menu
+    **described instead of assembled**: `items` is a list of `{ label, icon?, onClick }`
+    (or `href`, for a real `<a>` via Base UI's `Menu.LinkItem`) and the component builds
+    the trigger, the portal, the popup, the items and their states — `loading` swaps the
+    icon for a spinner and disarms the entry, `destructive` turns it red, `shortcut`
+    right-aligns a `Kbd`. A menu is the one place an app brings nothing but data, and
+    every app was re-typing the same twenty lines of Base UI markup around it. Two things
+    the data form gets right that hand-written menus don't: entries may be
+    `false`/`null`/`undefined`, so a conditional menu stays one flat array; and
+    `"separator"` is an entry like any other, **normalized** — a rule left leading,
+    trailing or doubled by a missing neighbour disappears instead of floating at the top
+    of the popup. Empty after that pass → nothing renders, not even the `⋯`. Still
+    presentational: it never knows what an entry *does*. For what a list can't say (a
+    submenu, a checkbox item), compose Base UI directly — that's what `WorkerCard`'s
+    `actions` slot is for.
   - _Sheet_ — `Sheet` (+`SheetTrigger`/`SheetClose`/`SheetContent`/`SheetHeader`/
     `SheetFooter`/`SheetTitle`/`SheetDescription`), the same Base UI dialog entering from
     an edge. `side` (4) decides the edge, `size` (`sm`…`full`) how far it comes in — two
@@ -167,10 +182,18 @@ opinions a dashboard doesn't want, so it gets an entry too.
 - **`WorkerCard`** — a Spunto worker as a card: state, author, node, setup
   progress, git branches, resources, banners, actions. **Purely presentational** —
   hand it a snapshot plus slots and it draws. The rule that keeps it that way:
-  *everything that CALLS the API is a slot or a callback; everything that DRAWS is
-  in the component.* So the `⋯` menu (`actions`), the footer (`footer`), the link
-  (`href` + `render.link`, never `next/link`), the rebuild (`onRebuild`) and the
-  tag persistence (`onAddTag`/`onRemoveTag`) all stay in the app.
+  *everything that CALLS the API is data, a slot or a callback; everything that
+  DRAWS is in the component.* So what the `⋯` entries **do** (`menu`), the footer
+  (`footer`), the link (`href` + `render.link`, never `next/link`), the rebuild
+  (`onRebuild`) and the tag persistence (`onAddTag`/`onRemoveTag`) all stay in the
+  app.
+- **The `⋯` menu is a prop, not markup.** `menu` takes the `ActionMenuEntry[]` of
+  the `ActionMenu` primitive — `{ label, icon?, onClick }`, falsy entries allowed,
+  `"separator"` normalized — and the card draws the whole menu. Before, every app
+  handed the card a fully-built menu through the `actions` slot and re-typed the
+  same Base UI markup to do it. `actions` stays as the escape hatch (a submenu, a
+  checkbox item) and wins over `menu` when both are given; `render.menuLink` is
+  the link slot for an entry with an `href`.
 - **Its bricks, exported individually** because the table view assembles them
   differently: `WorkerStatusDot`/`WorkerStatusPill` (+`resolveWorkerStatus`,
   `workerStatusConfig`), `SetupProgress` (+`setupProgress`, `phaseLabel`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,8 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.7.0",
-    "tailwind-merge": "^3.6.0"
+    "tailwind-merge": "^3.6.0",
+    "vaul": "^1.1.2"
   },
   "peerDependencies": {
     "@base-ui/react": "^1.6.0",

package/src/components/action-menu.tsx

@@ -0,0 +1,225 @@
+"use client"
+
+import type { ComponentType, ReactElement, ReactNode } from "react"
+import { Menu as MenuPrimitive } from "@base-ui/react/menu"
+import { ExternalLinkIcon, MoreVerticalIcon } from "lucide-react"
+
+import { cn } from "../utils"
+import { Spinner } from "./spinner"
+import { useOverlayContainer } from "./spunto-provider"
+
+/** One entry of an `ActionMenu`, described rather than rendered. */
+export interface ActionMenuItem {
+  /** What the entry says. */
+  label: ReactNode
+  /**
+   * React key. Defaults to the label when it's a string — give one explicitly if
+   * the label is a node, or if two entries share a label.
+   */
+  key?: string
+  /** Leading icon — any component taking a `className` (lucide-react, a local SVG…). */
+  icon?: ComponentType<{ className?: string }>
+  /** What the entry does. Omitted (and no `href`) → the entry is inert. */
+  onClick?: () => void
+  /** Navigates instead of acting: the entry renders as a real `<a>` (middle-click, ⌘-click…). */
+  href?: string
+  /** `"_blank"` implies the trailing ↗ unless `external` says otherwise. */
+  target?: string
+  /** Trailing ↗. Defaults to `target === "_blank"`. */
+  external?: boolean
+  disabled?: boolean
+  /**
+   * Action in flight: a spinner takes the icon's place and the entry is
+   * disabled. Kept apart from `disabled` so the caller doesn't have to swap the
+   * icon itself — the pending flag of a mutation goes straight in here.
+   */
+  loading?: boolean
+  /** Red, and pushed below a separator by convention (the caller still places it). */
+  destructive?: boolean
+  /** Trailing hint, right-aligned — a `Kbd`, a shortcut, a count. */
+  shortcut?: ReactNode
+  /** Keeps the popup open after a click (a toggle, typically). */
+  closeOnClick?: boolean
+}
+
+/**
+ * An entry, a rule between groups, or nothing.
+ *
+ * The falsy members are the point: a menu is almost always conditional
+ * (`isRunning && { label: "Stop", … }`), and allowing `false`/`null`/`undefined`
+ * keeps that written as one flat array instead of a `filter(Boolean)` dance.
+ * Separators are normalized afterwards — see `normalizeEntries`.
+ */
+export type ActionMenuEntry = ActionMenuItem | "separator" | false | null | undefined
+
+/** Renders an `href` entry with the app's link component (`next/link`, a router link…). */
+export type ActionMenuLinkRender = (props: {
+  href: string
+  target?: string
+  children?: ReactNode
+}) => ReactElement
+
+export interface ActionMenuProps {
+  /** The menu, as data. Falsy entries are dropped; empty → nothing renders at all. */
+  items: ActionMenuEntry[]
+  /** Accessible name of the default `⋯` trigger. */
+  label?: string
+  /** Replaces the `⋯` button. Base UI merges its trigger props into this element. */
+  trigger?: ReactElement
+  triggerClassName?: string
+  /** Classes for the popup (its width, typically). */
+  className?: string
+  align?: "start" | "center" | "end"
+  side?: "top" | "bottom" | "left" | "right"
+  sideOffset?: number
+  /** Escape hatch for `href` entries; without it they render as a plain `<a>`. */
+  render?: { link?: ActionMenuLinkRender }
+}
+
+/**
+ * The `⋯` menu, described instead of assembled: give it a list of
+ * `{ label, icon, onClick }` and it builds the trigger, the popup, the items,
+ * the separators and their states.
+ *
+ * Every app was rebuilding the same twenty lines of Base UI markup around the
+ * same five shapes of entry (an action, a link, a destructive one, one with a
+ * mutation in flight, a rule between groups) — and drifting: different paddings,
+ * different red, a spinner here and not there. The data form is what the callers
+ * actually have anyway; the markup is ours.
+ *
+ * Two things it does that hand-written menus keep getting wrong:
+ *
+ * - **Conditional entries.** `false`/`null`/`undefined` are legal entries, so a
+ *   menu stays one flat array (`isRunning && { label: "Stop", … }`).
+ * - **Separators are normalized.** Leading, trailing and consecutive rules are
+ *   dropped, so a `"separator"` next to an entry that just disappeared doesn't
+ *   leave a stray line floating at the top of the popup. That's the bug you get
+ *   every time a conditional item sits next to a conditional separator.
+ *
+ * It stays presentational: it never knows what an entry *does*. `onClick` and
+ * `href` come from the caller, like everywhere else in this package.
+ */
+export function ActionMenu({
+  items,
+  label = "Actions",
+  trigger,
+  triggerClassName,
+  className,
+  align = "end",
+  side = "bottom",
+  sideOffset = 4,
+  render,
+}: ActionMenuProps) {
+  const container = useOverlayContainer()
+  const entries = normalizeEntries(items)
+
+  // No action → no affordance. A `⋯` that opens an empty popup is worse than no
+  // `⋯` at all, and callers build these lists conditionally: an empty one is the
+  // normal outcome for, say, a worker on an offline node.
+  if (entries.length === 0) return null
+
+  return (
+    <MenuPrimitive.Root>
+      {trigger ? (
+        <MenuPrimitive.Trigger render={trigger} />
+      ) : (
+        <MenuPrimitive.Trigger aria-label={label} className={cn(triggerButton, triggerClassName)}>
+          <MoreVerticalIcon className="h-4 w-4" />
+        </MenuPrimitive.Trigger>
+      )}
+
+      <MenuPrimitive.Portal container={container ?? undefined}>
+        <MenuPrimitive.Positioner className="isolate z-50 outline-none" align={align} side={side} sideOffset={sideOffset}>
+          <MenuPrimitive.Popup
+            data-slot="action-menu"
+            className={cn(
+              // `max-h-(--available-height)` + scroll: a menu of twenty actions
+              // opened from a card at the bottom of the page must scroll inside
+              // the viewport, never spill past its edge.
+              "max-h-(--available-height) min-w-52 origin-(--transform-origin) overflow-x-hidden overflow-y-auto rounded-lg border border-border bg-popover p-1 text-popover-foreground shadow-lg shadow-black/[0.06] outline-none",
+              "transition-[transform,opacity] duration-150 data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              className
+            )}
+          >
+            {entries.map((entry, i) =>
+              entry === "separator" ? (
+                <div key={`sep-${i}`} role="separator" className="-mx-1 my-1 h-px bg-border" />
+              ) : (
+                <Item key={entry.key ?? (typeof entry.label === "string" ? entry.label : `item-${i}`)} item={entry} render={render} />
+              )
+            )}
+          </MenuPrimitive.Popup>
+        </MenuPrimitive.Positioner>
+      </MenuPrimitive.Portal>
+    </MenuPrimitive.Root>
+  )
+}
+
+const triggerButton =
+  "flex h-7 w-7 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground/50 transition-colors outline-none hover:bg-accent hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50 data-popup-open:bg-accent data-popup-open:text-foreground"
+
+const itemClass =
+  "flex cursor-default items-center gap-2 rounded-md px-1.5 py-1 text-sm no-underline outline-none select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-3.5 [&_svg]:shrink-0"
+
+const destructiveClass =
+  "text-destructive data-highlighted:bg-destructive/10 data-highlighted:text-destructive dark:data-highlighted:bg-destructive/20"
+
+function Item({ item, render }: { item: ActionMenuItem; render?: { link?: ActionMenuLinkRender } }) {
+  const { label, icon: Icon, href, target, external, disabled, loading, destructive, shortcut, closeOnClick, onClick } = item
+  const className = cn(itemClass, destructive && destructiveClass)
+  const showExternal = external ?? target === "_blank"
+
+  const content = (
+    <>
+      {loading ? <Spinner className="size-3.5" /> : Icon ? <Icon /> : null}
+      <span className="min-w-0 flex-1 truncate">{label}</span>
+      {shortcut != null && <span className="text-xs text-muted-foreground">{shortcut}</span>}
+      {showExternal && <ExternalLinkIcon className="opacity-50" />}
+    </>
+  )
+
+  // A navigation is an `<a>` — Base UI's `LinkItem` renders one, so ⌘-click and
+  // "open in new tab" work like anywhere else. `render.link` swaps in the app's
+  // router link; without it, a plain anchor (the package never imports `next/link`).
+  if (href) {
+    return (
+      <MenuPrimitive.LinkItem
+        className={className}
+        closeOnClick
+        render={render?.link?.({ href, target }) ?? <a href={href} target={target} rel={target === "_blank" ? "noopener noreferrer" : undefined} />}
+      >
+        {content}
+      </MenuPrimitive.LinkItem>
+    )
+  }
+
+  return (
+    <MenuPrimitive.Item className={className} disabled={disabled || loading} closeOnClick={closeOnClick ?? true} onClick={onClick}>
+      {content}
+    </MenuPrimitive.Item>
+  )
+}
+
+/**
+ * Drops falsy entries, then every separator that would end up alone: leading,
+ * trailing, or next to another one.
+ *
+ * This is the whole reason separators are data here. Written by hand, a rule
+ * between two conditional groups needs its own condition — the union of the
+ * conditions below it — and that condition is what goes stale when an entry is
+ * added. Here the rule simply disappears when nothing follows it.
+ */
+export function normalizeEntries(entries: ActionMenuEntry[]): (ActionMenuItem | "separator")[] {
+  const out: (ActionMenuItem | "separator")[] = []
+  for (const entry of entries) {
+    if (!entry) continue
+    if (entry === "separator") {
+      if (out.length === 0 || out[out.length - 1] === "separator") continue
+      out.push("separator")
+      continue
+    }
+    out.push(entry)
+  }
+  while (out.length > 0 && out[out.length - 1] === "separator") out.pop()
+  return out
+}

package/src/components/workers/index.ts

@@ -9,12 +9,24 @@
 export { WorkerCard } from "./worker-card"
 export type { WorkerCardProps, LinkRender } from "./worker-card"
 
+// The card's `menu` prop is a list of these. Re-exported here (they also ship
+// from the root entry) so an app can type its worker menu without importing the
+// primitives entry just for that.
+export { ActionMenu } from "../action-menu"
+export type { ActionMenuProps, ActionMenuItem, ActionMenuEntry, ActionMenuLinkRender } from "../action-menu"
+
+export { WorkerCockpit } from "./worker-cockpit"
+export type { WorkerCockpitProps } from "./worker-cockpit"
+
 export { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus, workerStatusConfig } from "./worker-status"
 export type { WorkerStatus, WorkerStatusConfig, WorkerStatusKey } from "./worker-status"
 
 export { SetupProgress, StepIndicator, phaseLabel, setupProgress, setupTotalMs } from "./setup-progress"
 export type { SetupProgressProps, StepState } from "./setup-progress"
 
+export { WorkerSetupTimeline } from "./worker-setup-timeline"
+export { SetupWaterfall } from "./setup-waterfall"
+
 export { ResourceBars } from "./resource-bars"
 export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
 
@@ -28,7 +40,7 @@ export type { TagPalette } from "./tag-color"
 
 export { CreatorAvatar } from "./creator-avatar"
 
-export type { WorkerCardWorker, WorkerCreator, WorkerSetupStatus } from "./types"
+export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus } from "./types"
 
 // Re-exported here too so a consumer of the worker surface doesn't have to
 // import the root entry just to format the timestamps it feeds these components.

package/src/components/workers/setup-waterfall.tsx

@@ -0,0 +1,68 @@
+"use client"
+
+import { formatDuration } from "../../utils"
+
+// ── Startup timing waterfall ──────────────────────────────────────────────
+// Renders the per-phase startup durations captured container-side in a
+// worker's setup status (`timings`: ms-epoch per milestone). Each milestone
+// marks the *start* of its phase, so a phase's duration is the gap to the
+// next present milestone; `ready` is the terminal marker.
+const TIMING_PHASES: { key: string; label: string; color: string }[] = [
+  { key: "initializing", label: "Initialize", color: "var(--muted-foreground)" },
+  { key: "credentials", label: "Credentials", color: "var(--build)" },
+  { key: "shell", label: "Shell", color: "var(--build)" },
+  { key: "dotfiles", label: "Dotfiles", color: "var(--build)" },
+  { key: "cloning", label: "Clone repos", color: "var(--primary)" },
+  { key: "postCreate", label: "postCreate", color: "var(--run)" },
+  { key: "postStart", label: "postStart", color: "var(--run)" },
+  { key: "ready", label: "Ready", color: "var(--run)" },
+]
+
+export function SetupWaterfall({ timings, className = "" }: { timings?: Record<string, number> | null; className?: string }) {
+  // Present milestones, in canonical order, as [key,label,color,ts].
+  const points = TIMING_PHASES
+    .map((p) => ({ ...p, ts: timings?.[p.key] }))
+    .filter((p): p is typeof p & { ts: number } => typeof p.ts === "number")
+  if (points.length < 2) return null
+  const t0 = points[0].ts
+  const tEnd = points[points.length - 1].ts
+  const total = Math.max(1, tEnd - t0)
+  // A segment spans from a milestone to the next present one; the last milestone is
+  // the endpoint, so it has no bar of its own.
+  const segments = points.slice(0, -1).map((p, i) => ({
+    key: p.key,
+    label: p.label,
+    color: p.color,
+    offset: ((p.ts - t0) / total) * 100,
+    width: (((points[i + 1].ts - p.ts) / total) * 100),
+    duration: points[i + 1].ts - p.ts,
+  }))
+  const complete = points[points.length - 1].key === "ready"
+  return (
+    <div className={`rounded-lg border border-border/40 bg-muted/20 text-xs ${className}`}>
+      <div className="flex items-center justify-between px-3 py-2 border-b border-border/40">
+        <span className="font-mono text-[11px] font-medium text-muted-foreground">
+          {complete ? "Startup breakdown" : "Startup so far"}
+        </span>
+        <span className="font-mono text-[11px] tabular-nums text-foreground/80">{formatDuration(total)}</span>
+      </div>
+      <div className="px-3 py-2.5 space-y-1.5">
+        {segments.map((s) => (
+          <div key={s.key} className="grid items-center gap-2" style={{ gridTemplateColumns: "5.5rem 1fr 3rem" }}>
+            <span className="truncate font-mono text-[11px] text-muted-foreground">{s.label}</span>
+            <span className="relative h-2.5 rounded-sm bg-muted/60">
+              <span
+                className="absolute inset-y-0 min-w-[2px] rounded-sm"
+                style={{ left: `${s.offset}%`, width: `${Math.max(1.5, s.width)}%`, background: s.color }}
+                title={`${s.label}: ${formatDuration(s.duration)}`}
+              />
+            </span>
+            <span className="text-right font-mono text-[11px] tabular-nums text-muted-foreground/80">
+              {formatDuration(s.duration)}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/components/workers/types.ts

@@ -42,3 +42,14 @@ export interface WorkerCreator {
   login?: string
   avatarUrl?: string | null
 }
+
+/**
+ * The snapshot a `WorkerCockpit` draws — `WorkerCardWorker` plus the fields a
+ * full page needs and a card doesn't: the checkout it was asked to start on,
+ * and whether a container exists at all (a worker can be `WorkerCardWorker`-
+ * complete before it ever gets one).
+ */
+export interface WorkerCockpitWorker extends WorkerCardWorker {
+  branch?: string | null
+  containerId?: string | null
+}

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

@@ -12,6 +12,7 @@ import {
 } from "lucide-react"
 
 import { cn, formatDuration, formatRelativeTime } from "../../utils"
+import { ActionMenu, type ActionMenuEntry, type ActionMenuLinkRender } from "../action-menu"
 import { buttonVariants } from "../button-variants"
 import { CreatorAvatar } from "./creator-avatar"
 import { GitBranchChips, type GitRepoStatus } from "./git-branch-chips"
@@ -33,8 +34,12 @@ export interface WorkerCardProps {
    * Escape hatches for app-specific rendering. `link` receives `{ href, className,
    * children }` and must return an anchor-ish node (`next/link`, a router link…);
    * without it the card falls back to a plain `<a>`.
+   *
+   * `menuLink` does the same for a `menu` entry carrying an `href`, but with the
+   * other contract: it returns an *element* that Base UI merges its own props
+   * and children into, so it takes no `children` of its own.
    */
-  render?: { link?: LinkRender }
+  render?: { link?: LinkRender; menuLink?: ActionMenuLinkRender }
 
   creator?: WorkerCreator
   nodeName?: string
@@ -71,7 +76,33 @@ export interface WorkerCardProps {
   error?: string | null
   onDismissError?: () => void
 
-  /** The `⋯` menu, top-right. A slot: every entry in it calls the API. */
+  /**
+   * The `⋯` menu, top-right, **as data**: one entry is a `label`, optionally an
+   * `icon`, and an `onClick` (or an `href`) — the card builds the trigger, the
+   * popup and the items. Entries may be `false`/`null` (a menu is always
+   * conditional) and `"separator"` is an entry like any other; rules left alone
+   * by a missing neighbour are dropped. Empty or all-falsy → no `⋯` at all.
+   *
+   * What an entry *does* still belongs to the app: `onClick` is where the API
+   * call lives. What it *looks like* is ours — that's the difference with the
+   * `actions` slot below, which each app used to fill with its own twenty lines
+   * of menu markup.
+   *
+   * ```tsx
+   * menu={[
+   *   codeUrl && { label: "Open in VS Code", icon: Code2Icon, href: codeUrl, target: "_blank" },
+   *   "separator",
+   *   isRunning && { label: "Stop", icon: SquareIcon, onClick: () => stop.mutate(), loading: stop.isPending },
+   *   "separator",
+   *   { label: "Delete", icon: Trash2Icon, destructive: true, onClick: () => del.mutate() },
+   * ]}
+   * ```
+   */
+  menu?: ActionMenuEntry[]
+  /**
+   * Escape hatch for a menu the data form can't express (a submenu, a checkbox
+   * item, a dialog opened from an entry). Takes precedence over `menu`.
+   */
   actions?: ReactNode
   /** Replaces the default "View" footer entirely (extra buttons, a VS Code link…). */
   footer?: ReactNode
@@ -86,10 +117,10 @@ export interface WorkerCardProps {
  * on, and what you can do with it.
  *
  * **Purely presentational.** It receives a snapshot and draws it — no query, no
- * mutation, no router. Everything that would talk to an API is a slot
- * (`actions`, `footer`) or a callback (`onAddTag`, `onRebuild`…). That rule is
- * what makes the same card renderable by the dashboard, by Spunto Lite, and by
- * the showcase with hand-written fixtures. The card is the assembly; each brick
+ * mutation, no router. Everything that would talk to an API is data (`menu`), a
+ * slot (`actions`, `footer`) or a callback (`onAddTag`, `onRebuild`…). That rule
+ * is what makes the same card renderable by the dashboard, by Spunto Lite, and
+ * by the showcase with hand-written fixtures. The card is the assembly; each brick
  * (`WorkerStatusDot`, `SetupProgress`, `ResourceBars`, `GitBranchChips`,
  * `TagChips`) is exported on its own because the table view needs them without
  * the card.
@@ -116,6 +147,7 @@ export function WorkerCard({
   rebuilding = false,
   error,
   onDismissError,
+  menu,
   actions,
   footer,
   viewLabel = "View",
@@ -215,7 +247,7 @@ export function WorkerCard({
           </div>
         </div>
 
-        {actions}
+        {actions ?? (menu && <ActionMenu items={menu} render={{ link: render?.menuLink }} />)}
       </div>
 
       {status.settingUp && (

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

@@ -0,0 +1,555 @@
+"use client"
+
+// The full worker page, as one component. Top bar, logs/terminal tabs, and a
+// control panel (setup, resources, repos, ports, tags, actions, info) that
+// lives in a sidebar on desktop and a bottom sheet on mobile — same content,
+// because a phone doesn't need less of it, just a different place to put it.
+//
+// Purely presentational, same rule as `WorkerCard`: everything that would
+// talk to an API is a slot (`logsContent`, `terminalContent`, `statsChart`,
+// `actions`-style render props) or a callback (`onStop`, `onAddTag`…). No
+// `useQuery`, no mutation, no router, no `next/link` — that's what lets the
+// same cockpit be driven by the dashboard's react-query hooks today and by
+// hand-written fixtures in the showcase.
+
+import { useState, type ComponentType, type ReactNode } from "react"
+import { Drawer as DrawerPrimitive } from "vaul"
+import {
+  AlertTriangleIcon,
+  AlignLeftIcon,
+  ArrowLeftIcon,
+  CheckIcon,
+  Code2Icon,
+  CopyIcon,
+  ExternalLinkIcon,
+  GitBranchIcon,
+  LoaderIcon,
+  Maximize2Icon,
+  PanelRightOpenIcon,
+  PlayIcon,
+  RefreshCwIcon,
+  SquareIcon,
+  TerminalIcon,
+  Trash2Icon,
+  WifiOffIcon,
+  XIcon,
+} from "lucide-react"
+
+import { cn, formatRelativeTime } from "../../utils"
+import { Button } from "../button"
+import { buttonVariants } from "../button-variants"
+import { useOverlayContainer } from "../spunto-provider"
+import { CreatorAvatar } from "./creator-avatar"
+import { type GitRepoStatus, repoName } from "./git-branch-chips"
+import { ResourceBars, type WorkerStats } from "./resource-bars"
+import { SetupWaterfall } from "./setup-waterfall"
+import { TagChips } from "./tag-chips"
+import type { WorkerCockpitWorker, WorkerCreator } from "./types"
+import { type LinkRender } from "./worker-card"
+import { WorkerSetupTimeline } from "./worker-setup-timeline"
+import { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus } from "./worker-status"
+
+type CockpitTab = "logs" | "terminal"
+
+export interface WorkerCockpitProps {
+  worker: WorkerCockpitWorker
+  /** Above the worker name, e.g. "my-project /". Omitted → no breadcrumb. */
+  projectName?: string
+  /** Project's current config version — a worker below it gets the "Rebuild" banner. */
+  currentProjectVersion?: number
+
+  /** Target of the back button, top-left. Omitted → no back button. */
+  backHref?: string
+  render?: { link?: LinkRender }
+
+  creator?: WorkerCreator
+  nodeName?: string
+  /** `false` draws the "Node offline" banner. `undefined` = unknown, no banner. */
+  nodeOnline?: boolean
+
+  /**
+   * Live container stats. `undefined` → no Resources section at all (the
+   * worker isn't running). `null` → the section shows with its loading state
+   * (container is up, first sample hasn't arrived). An object → bars + chart.
+   */
+  stats?: WorkerStats | null
+  /** App-drawn chart under the bars (recharts, sparkline…) — kept out of the
+   * package so it doesn't drag a charting library into every consumer. */
+  statsChart?: ReactNode
+
+  /** What this worker is working on. Empty/omitted → no Repositories section. */
+  repos?: GitRepoStatus[]
+  /** Chip → URL (e.g. code-server at that folder). Returning undefined renders a static row. */
+  repoHref?: (repo: GitRepoStatus) => string | undefined
+
+  /** Ports detected inside the container. Only pass these while relevant (running, past setup). */
+  ports?: { port: number; process?: string }[]
+  portHref?: (port: number) => string | undefined
+
+  onAddTag?: (tag: string, next: string[]) => void
+  onRemoveTag?: (tag: string, next: string[]) => void
+
+  /** "Open VS Code", top-right. Omitted → the button doesn't show. */
+  editorHref?: string
+
+  onStop?: () => void
+  stopping?: boolean
+  onStart?: () => void
+  starting?: boolean
+  onRebuild?: () => void
+  rebuilding?: boolean
+  onDelete?: () => void
+  deleting?: boolean
+
+  /** Fetches the one-shot SSH command; the cockpit copies it to the clipboard and owns the button's own idle/loading/copied state. */
+  onCopySsh?: () => Promise<string>
+
+  /** A failed mutation, typically. */
+  error?: string | null
+  onDismissError?: () => void
+
+  activeTab: CockpitTab
+  onTabChange: (tab: CockpitTab) => void
+  /** What to draw for each tab — the app decides which panel applies (a log stream, a build in progress, a "no container yet" placeholder…). */
+  logsContent: ReactNode
+  terminalContent: ReactNode
+  /** Shown next to the tabs when on the terminal tab. Omitted → no reconnect button. */
+  onReconnectTerminal?: () => void
+  /** Opens a fullscreen terminal overlay. Omitted → no fullscreen button. */
+  onOpenFullscreen?: () => void
+
+  className?: string
+}
+
+function SectionLabel({ children }: { children: ReactNode }) {
+  return <p className="mb-2 text-[10px] font-semibold tracking-widest text-muted-foreground/50 uppercase">{children}</p>
+}
+
+const BANNER_TONES = {
+  offline: "border-orange-500/25 bg-orange-500/5 text-orange-600 dark:text-orange-400",
+  warn: "border-amber-500/25 bg-amber-500/5 text-amber-600 dark:text-amber-400",
+  error: "border-destructive/25 bg-destructive/5 text-destructive",
+} as const
+
+function Banner({ tone, children }: { tone: keyof typeof BANNER_TONES; children: ReactNode }) {
+  return (
+    <div className={cn("flex items-center justify-between gap-2 rounded-lg border px-3 py-2 text-xs", BANNER_TONES[tone])}>
+      {children}
+    </div>
+  )
+}
+
+function InfoRow({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <div className="flex items-center justify-between px-3 py-2">
+      <span className="text-[11px] text-muted-foreground">{label}</span>
+      {children}
+    </div>
+  )
+}
+
+/**
+ * The full worker page: top bar, logs/terminal tabs, and a control panel —
+ * one component, driven entirely by props. See the file header for the
+ * present/callback/slot split.
+ */
+export function WorkerCockpit({
+  worker,
+  projectName,
+  currentProjectVersion,
+  backHref,
+  render,
+  creator,
+  nodeName,
+  nodeOnline,
+  stats,
+  statsChart,
+  repos = [],
+  repoHref,
+  ports = [],
+  portHref,
+  onAddTag,
+  onRemoveTag,
+  editorHref,
+  onStop,
+  stopping = false,
+  onStart,
+  starting = false,
+  onRebuild,
+  rebuilding = false,
+  onDelete,
+  deleting = false,
+  onCopySsh,
+  error,
+  onDismissError,
+  activeTab,
+  onTabChange,
+  logsContent,
+  terminalContent,
+  onReconnectTerminal,
+  onOpenFullscreen,
+  className,
+}: WorkerCockpitProps) {
+  const [mobileOpen, setMobileOpen] = useState(false)
+  const [sshState, setSshState] = useState<"idle" | "loading" | "copied" | "error">("idle")
+  const overlayContainer = useOverlayContainer()
+
+  const status = resolveWorkerStatus(worker)
+  const settled = status.running && !status.settingUp
+  const isStopped = worker.dockerState === "stopped" || worker.dockerState === "exited"
+  const isDeleting = status.key === "deleting"
+  const hasContainer = worker.containerId != null
+  const title = worker.name || (worker.index != null ? `Workspace #${worker.index}` : worker.id)
+  const outdated =
+    !status.settingUp &&
+    worker.projectVersion != null &&
+    currentProjectVersion != null &&
+    worker.projectVersion < currentProjectVersion
+  const needsAttention = !!error || nodeOnline === false || outdated
+
+  const Link: LinkRender = render?.link ?? (({ href: to, className: cls, children }) => <a href={to} className={cls}>{children}</a>)
+
+  async function handleCopySsh() {
+    if (!onCopySsh) return
+    setSshState("loading")
+    try {
+      const command = await onCopySsh()
+      await navigator.clipboard.writeText(command)
+      setSshState("copied")
+      setTimeout(() => setSshState("idle"), 2500)
+    } catch {
+      setSshState("error")
+      setTimeout(() => setSshState("idle"), 2500)
+    }
+  }
+
+  const showActions = !!((settled && onCopySsh) || (hasContainer && !status.settingUp && !isDeleting && onRebuild) || ((hasContainer || isDeleting) && nodeOnline !== false && onDelete))
+  const showTags = (worker.tags?.length ?? 0) > 0 || !!onAddTag
+
+  const controlPanel = (
+    <>
+      {error && (
+        <Banner tone="error">
+          <span className="line-clamp-2 min-w-0 flex-1 font-mono break-words">{error}</span>
+          {onDismissError && (
+            <button type="button" onClick={onDismissError} aria-label="Dismiss error" className="shrink-0 cursor-pointer opacity-60 transition-opacity hover:opacity-100">
+              <XIcon className="h-3.5 w-3.5" />
+            </button>
+          )}
+        </Banner>
+      )}
+      {nodeOnline === false && (
+        <Banner tone="offline">
+          <span className="flex min-w-0 items-center gap-2">
+            <WifiOffIcon className="h-3.5 w-3.5 shrink-0" />Node offline — actions unavailable
+          </span>
+        </Banner>
+      )}
+      {outdated && (
+        <Banner tone="warn">
+          <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>
+          </span>
+          {onRebuild && (
+            <button type="button" disabled={rebuilding} onClick={onRebuild} className="shrink-0 cursor-pointer text-[11px] font-medium hover:underline disabled:opacity-50">
+              {rebuilding ? "Rebuilding…" : "Rebuild now"}
+            </button>
+          )}
+        </Banner>
+      )}
+
+      {(status.settingUp || worker.setupStatus) && (
+        <div className="space-y-2">
+          <SectionLabel>Setup</SectionLabel>
+          <WorkerSetupTimeline status={worker.setupStatus ?? null} settingUp={status.settingUp} />
+          <SetupWaterfall timings={worker.setupStatus?.timings} />
+        </div>
+      )}
+
+      {stats !== undefined && (
+        <div>
+          <SectionLabel>Resources</SectionLabel>
+          {stats ? (
+            // `@container`: `ResourceBars` decides to go two-column via a
+            // container query, so it needs a container ancestor — here, this
+            // panel. Without it the bars stay stacked (they lose their own
+            // card once pulled into a sidebar).
+            <div className="@container space-y-3 rounded-lg border border-border/40 bg-muted/20 px-3 py-3">
+              <ResourceBars stats={stats} compact />
+              {statsChart && <div className="pt-1">{statsChart}</div>}
+            </div>
+          ) : (
+            <div className="flex items-center gap-2 py-2 font-mono text-xs text-muted-foreground">
+              <LoaderIcon className="h-3 w-3 animate-spin" /> Loading stats…
+            </div>
+          )}
+        </div>
+      )}
+
+      {repos.length > 0 && (
+        <div>
+          <SectionLabel>Repositories</SectionLabel>
+          <div className="space-y-1.5">
+            {repos.map((repo) => {
+              const href = repoHref?.(repo)
+              return (
+                <div key={repo.path} className="rounded-lg border border-border/50 bg-muted/20 px-3 py-2">
+                  <div className="flex items-center justify-between gap-2">
+                    <div className="flex min-w-0 items-center gap-1.5">
+                      <GitBranchIcon className="h-3 w-3 shrink-0 text-muted-foreground" />
+                      <span className="truncate font-mono text-xs font-medium">{repoName(repo)}</span>
+                    </div>
+                    {href && (
+                      <Link href={href} className={cn(buttonVariants({ variant: "ghost", size: "sm" }), "h-6 shrink-0 gap-1 px-2 text-[11px] text-muted-foreground")}>
+                        <Code2Icon className="h-3 w-3" />Open
+                      </Link>
+                    )}
+                  </div>
+                  {repo.branch && (
+                    <div className="mt-1.5 flex items-center gap-2 pl-[18px] text-[11px] text-muted-foreground">
+                      <span className="font-mono">{repo.branch}</span>
+                      {!!repo.modified && <span className="rounded-full bg-amber-500/10 px-1.5 py-0.5 text-[10px] font-semibold text-amber-600 dark:text-amber-400">{repo.modified} modified</span>}
+                      {!!repo.ahead && <span className="text-primary">↑{repo.ahead}</span>}
+                      {!!repo.behind && <span className="text-orange-400">↓{repo.behind}</span>}
+                    </div>
+                  )}
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {ports.length > 0 && (
+        <div>
+          <SectionLabel>Open ports</SectionLabel>
+          <div className="space-y-1.5">
+            {ports.map((p) => {
+              const href = portHref?.(p.port)
+              return (
+                <div key={p.port} className="flex items-center justify-between rounded-lg border border-border/50 bg-muted/20 px-3 py-2">
+                  <div className="flex min-w-0 items-center gap-2">
+                    <span className="font-mono text-xs text-foreground">:{p.port}</span>
+                    {p.process && <span className="truncate text-[11px] text-muted-foreground">{p.process}</span>}
+                  </div>
+                  {href && (
+                    <Link href={href} className={cn(buttonVariants({ variant: "ghost", size: "sm" }), "h-6 shrink-0 gap-1 px-2 text-[11px] text-muted-foreground")}>
+                      <ExternalLinkIcon className="h-3 w-3" />Open
+                    </Link>
+                  )}
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+
+      {showTags && (
+        <div>
+          <SectionLabel>Tags</SectionLabel>
+          <TagChips tags={worker.tags ?? []} onAdd={onAddTag} onRemove={onRemoveTag} />
+        </div>
+      )}
+
+      {showActions && (
+        <div>
+          <SectionLabel>Actions</SectionLabel>
+          <div className="space-y-1.5">
+            {settled && onCopySsh && (
+              <button
+                type="button"
+                onClick={handleCopySsh}
+                disabled={sshState === "loading"}
+                className={cn(
+                  "flex w-full items-center justify-between gap-3 rounded-lg border border-border/50 bg-muted/20 px-3 py-2.5 text-xs transition-colors hover:bg-muted/40",
+                  sshState === "copied" ? "border-green-500/30 text-green-600 dark:text-green-400" : "text-foreground"
+                )}
+              >
+                <div className="flex items-center gap-2">
+                  {sshState === "copied" ? <CheckIcon className="h-3.5 w-3.5" /> : <CopyIcon className="h-3.5 w-3.5 text-muted-foreground" />}
+                  <span className="font-medium">
+                    {sshState === "copied" ? "SSH command copied!" : sshState === "error" ? "Failed to copy — try again" : "Copy SSH command"}
+                  </span>
+                </div>
+                <span className="text-[10px] text-muted-foreground/50">5 min token</span>
+              </button>
+            )}
+            {hasContainer && !status.settingUp && !isDeleting && onRebuild && (
+              <button type="button" disabled={rebuilding} onClick={onRebuild} className="flex w-full items-center gap-2 rounded-lg border border-border/50 bg-muted/20 px-3 py-2.5 text-xs text-foreground transition-colors hover:bg-muted/40 disabled:opacity-50">
+                <RefreshCwIcon className={cn("h-3.5 w-3.5 text-muted-foreground", rebuilding && "animate-spin")} />
+                <span className="font-medium">Rebuild container</span>
+                <span className="ml-auto text-[10px] text-muted-foreground/50">keeps workspace</span>
+              </button>
+            )}
+            {(hasContainer || isDeleting) && nodeOnline !== false && onDelete && (
+              <button type="button" disabled={deleting || isDeleting} onClick={onDelete} className="flex w-full items-center gap-2 rounded-lg border border-destructive/20 bg-destructive/5 px-3 py-2.5 text-xs text-destructive transition-colors hover:bg-destructive/10 disabled:opacity-50">
+                {isDeleting ? <LoaderIcon className="h-3.5 w-3.5 animate-spin" /> : <Trash2Icon className="h-3.5 w-3.5" />}
+                <span className="font-medium">Delete workspace</span>
+                <span className="ml-auto text-[10px] opacity-60">permanent</span>
+              </button>
+            )}
+          </div>
+        </div>
+      )}
+
+      <div>
+        <SectionLabel>Info</SectionLabel>
+        <div className="divide-y divide-border/40 rounded-lg border border-border/50 bg-muted/20">
+          {creator && (
+            <InfoRow label="Owner">
+              <div className="flex items-center gap-1.5"><CreatorAvatar creator={creator} /><span className="text-[11px] font-medium">{creator.name}</span></div>
+            </InfoRow>
+          )}
+          {nodeName && (
+            <InfoRow label="Node">
+              <div className="flex items-center gap-1.5">
+                <div className={cn("h-1.5 w-1.5 rounded-full", nodeOnline === false ? "bg-zinc-400" : "bg-green-500")} />
+                <span className="font-mono text-[11px] font-medium">{nodeName}</span>
+              </div>
+            </InfoRow>
+          )}
+          {worker.projectVersion != null && (
+            <InfoRow label="Config version"><span className="font-mono text-[11px] font-medium">v{worker.projectVersion}</span></InfoRow>
+          )}
+          {worker.branch && (
+            <InfoRow label="Branch">
+              <div className="flex min-w-0 items-center gap-1.5">
+                <GitBranchIcon className="h-3 w-3 shrink-0 text-muted-foreground" />
+                <span className="truncate font-mono text-[11px] font-medium">{worker.branch}</span>
+              </div>
+            </InfoRow>
+          )}
+          {worker.createdAt && <InfoRow label="Created"><span className="text-[11px] text-muted-foreground">{formatRelativeTime(worker.createdAt)}</span></InfoRow>}
+          {worker.containerId && <InfoRow label="Container"><span className="font-mono text-[11px] text-muted-foreground">{worker.containerId.slice(0, 12)}</span></InfoRow>}
+        </div>
+      </div>
+    </>
+  )
+
+  return (
+    // `@container`: every breakpoint below queries THIS element's own width,
+    // never the viewport — the same cockpit is a 1150px page in the dashboard
+    // and a 380px frame in the showcase, and a viewport media query can't tell
+    // those apart (see docs/design-system.md's ResourceBars gotcha).
+    <div data-slot="worker-cockpit" className={cn("@container flex flex-col overflow-hidden", className)}>
+      {/* ── Top bar ── */}
+      <div className="flex shrink-0 items-center justify-between gap-3 border-b border-border bg-card/60 px-5 py-3 backdrop-blur-sm @min-[48rem]:px-6">
+        <div className="flex min-w-0 items-center gap-2">
+          {backHref && (
+            <Link href={backHref} className={cn(buttonVariants({ variant: "ghost", size: "icon" }), "h-8 w-8 shrink-0")}>
+              <ArrowLeftIcon className="h-4 w-4" />
+            </Link>
+          )}
+          <div className="h-4 w-px bg-border" />
+          {projectName && (
+            <>
+              <span className="hidden truncate text-sm text-muted-foreground @min-[40rem]:block">{projectName}</span>
+              <span className="hidden text-muted-foreground/40 @min-[40rem]:block">/</span>
+            </>
+          )}
+          <div className="flex min-w-0 items-center gap-2">
+            <WorkerStatusDot status={status} />
+            <span className="truncate text-sm font-semibold">{title}</span>
+            <WorkerStatusPill status={status} />
+          </div>
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          {settled && editorHref && (
+            <Link href={editorHref} className={cn(buttonVariants({ variant: "default", size: "sm" }), "h-8 gap-1.5 px-3 text-xs")}>
+              <Code2Icon className="h-3.5 w-3.5" />Open VS Code<ExternalLinkIcon className="h-2.5 w-2.5 opacity-70" />
+            </Link>
+          )}
+          {settled && onStop && (
+            <Button variant="ghost" size="sm" className="h-8 gap-1.5 px-3 text-xs text-muted-foreground hover:bg-destructive/10 hover:text-destructive" disabled={stopping} onClick={onStop}>
+              <SquareIcon className="h-3.5 w-3.5" />Stop
+            </Button>
+          )}
+          {(isStopped || worker.dockerState === "error") && nodeOnline !== false && onStart && (
+            <Button variant="outline" size="sm" className="h-8 gap-1.5 px-3 text-xs" disabled={starting} onClick={onStart}>
+              <PlayIcon className="h-3.5 w-3.5" />Start
+            </Button>
+          )}
+        </div>
+      </div>
+
+      {/* ── Body ── */}
+      <div className="flex min-h-0 flex-1 flex-col overflow-hidden @min-[64rem]:flex-row">
+        {/* Plain buttons, not the design system's `Tabs` — this bar matches the
+            worker page's existing look (bg-accent on the active tab) rather than
+            the segmented-control style `Tabs` draws elsewhere, so adopting this
+            component doesn't change how the page looks. */}
+        <div className="flex min-h-0 flex-1 flex-col border-border @min-[64rem]:border-r" style={{ minHeight: 320 }}>
+          <div className="flex shrink-0 items-center justify-between gap-2 border-b border-border bg-card px-3 py-1.5">
+            <div className="flex items-center gap-0.5 overflow-x-auto">
+              {(
+                [
+                  { id: "logs" as CockpitTab, label: "Logs", icon: AlignLeftIcon },
+                  { id: "terminal" as CockpitTab, label: "Terminal", icon: TerminalIcon },
+                ] satisfies { id: CockpitTab; label: string; icon: ComponentType<{ className?: string }> }[]
+              ).map(({ id, label, icon: Icon }) => (
+                <button
+                  key={id}
+                  onClick={() => onTabChange(id)}
+                  className={cn(
+                    "flex shrink-0 items-center gap-1.5 rounded-md px-3 py-1.5 text-xs font-medium transition-colors",
+                    activeTab === id ? "bg-accent text-foreground" : "text-muted-foreground hover:bg-accent/50 hover:text-foreground"
+                  )}
+                >
+                  <Icon className="h-3.5 w-3.5" />{label}
+                </button>
+              ))}
+            </div>
+            <div className="flex shrink-0 items-center gap-1.5">
+              {settled && onOpenFullscreen && (
+                <button onClick={onOpenFullscreen} className="flex shrink-0 items-center gap-1.5 rounded-md border border-primary/30 bg-primary/10 px-2.5 py-1.5 text-xs font-medium text-primary transition-colors hover:bg-primary/20" title="Open fullscreen terminal">
+                  <Maximize2Icon className="h-3.5 w-3.5" />
+                  <span className="hidden @min-[40rem]:inline">Fullscreen</span>
+                </button>
+              )}
+              <span className="hidden font-mono text-[10px] text-muted-foreground/50 @min-[40rem]:inline">{title}</span>
+              {activeTab === "terminal" && onReconnectTerminal && (
+                <button onClick={onReconnectTerminal} className="flex h-6 w-6 items-center justify-center rounded text-muted-foreground/50 transition-colors hover:bg-accent hover:text-muted-foreground" title="Reconnect">
+                  <RefreshCwIcon className="h-3 w-3" />
+                </button>
+              )}
+              <button onClick={() => setMobileOpen(true)} className="relative flex h-6 w-6 items-center justify-center rounded text-muted-foreground/50 transition-colors hover:bg-accent hover:text-muted-foreground @min-[64rem]:hidden" title="Workspace details">
+                <PanelRightOpenIcon className="h-3.5 w-3.5" />
+                {needsAttention && <span className="absolute top-0.5 right-0.5 h-1.5 w-1.5 rounded-full bg-amber-500" />}
+              </button>
+            </div>
+          </div>
+          <div className="min-h-0 flex-1">
+            {activeTab === "logs" ? logsContent : terminalContent}
+          </div>
+        </div>
+
+        {/* Desktop: always-visible sidebar. Mobile gets the same content in a
+            swipeable bottom drawer (below) so the terminal can own the full
+            screen. */}
+        <div className="hidden shrink-0 overflow-y-auto bg-card @min-[64rem]:block @min-[64rem]:w-80 @min-[80rem]:w-96">
+          <div className="space-y-5 p-4">{controlPanel}</div>
+        </div>
+      </div>
+
+      {/* Mobile: the same `vaul` drawer apps/next uses (drag handle,
+          swipe-to-dismiss) — not the design system's `Sheet`, which has
+          neither. `Sheet` is the right choice for the rest of the package
+          (right/left/top panels with no drag gesture); this one thing a
+          worker page needs that `Sheet` doesn't do. */}
+      <DrawerPrimitive.Root open={mobileOpen} onOpenChange={setMobileOpen} container={overlayContainer ?? undefined}>
+        <DrawerPrimitive.Portal>
+          <DrawerPrimitive.Overlay className="fixed inset-0 z-50 bg-black/40 backdrop-blur-[2px]" />
+          <DrawerPrimitive.Content className="fixed inset-x-0 bottom-0 z-50 mt-24 flex max-h-[80vh] flex-col rounded-t-xl border-t border-border bg-background @min-[64rem]:hidden">
+            <div className="mx-auto mt-4 h-1 w-[100px] shrink-0 rounded-full bg-muted" />
+            <DrawerPrimitive.Title className="px-4 pt-3 text-base font-semibold text-foreground">
+              Workspace details
+            </DrawerPrimitive.Title>
+            <div className="min-h-0 space-y-5 overflow-y-auto px-4 pt-3 pb-6">{controlPanel}</div>
+          </DrawerPrimitive.Content>
+        </DrawerPrimitive.Portal>
+      </DrawerPrimitive.Root>
+    </div>
+  )
+}

package/src/components/workers/worker-setup-timeline.tsx

@@ -0,0 +1,181 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { CheckIcon, GitBranchIcon, LoaderIcon, TerminalIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { StepIndicator, phaseLabel, setupProgress, type StepState } from "./setup-progress"
+import type { WorkerSetupStatus } from "./types"
+
+/**
+ * A worker's setup, step by step: the phase, the bar, and one line per thing being done — a
+ * repository cloned, a lifecycle command running.
+ *
+ * `SetupProgress` answers "how far along?" in one bar, which is what a card or a table row
+ * wants. This answers "what is it doing *right now*?", which is the question anyone staring at
+ * a machine that isn't ready yet actually has. Hookless and presentational: give it a status
+ * snapshot, it draws it.
+ */
+
+type Step = { key: string; icon: ReactNode; label: string; state: StepState; suffix?: string }
+
+/** `cloning` is the repo-level spelling of `running`; the other states line up already. */
+function stepState(value: string | null | undefined): StepState {
+  if (value === "cloning" || value === "running") return "running"
+  if (value === "done" || value === "error" || value === "pending") return value
+  return "pending"
+}
+
+function steps(status: WorkerSetupStatus | null): Step[] {
+  if (!status) return []
+  const out: Step[] = []
+
+  for (const repo of status.repos ?? []) {
+    const name = repo.name ?? ""
+    const state = stepState(repo.state)
+    out.push({
+      key: `repo:${name}`,
+      icon: <GitBranchIcon className="h-3 w-3 shrink-0 opacity-70" />,
+      label: name.split("/").pop() || name,
+      state,
+      suffix: state === "running" ? "cloning…" : undefined,
+    })
+  }
+
+  // `null` means the project has no such command — not that it is pending.
+  for (const [key, value] of [
+    ["postCreate", status.postCreate],
+    ["postStart", status.postStart],
+  ] as const) {
+    if (value == null) continue
+    const state = stepState(value)
+    out.push({
+      key,
+      icon: <TerminalIcon className="h-3 w-3 shrink-0 opacity-70" />,
+      label: key,
+      state,
+      suffix: state === "running" ? "running…" : undefined,
+    })
+  }
+
+  return out
+}
+
+export function WorkerSetupTimeline({
+  status,
+  settingUp = false,
+  className,
+}: {
+  status: WorkerSetupStatus | null
+  /** The machine is still being provisioned — drives the bar and the amber framing. */
+  settingUp?: boolean
+  className?: string
+}) {
+  if (!status && !settingUp) return null
+
+  const pct = setupProgress(status)
+  const failed = status?.phase === "error"
+  const done = status?.phase === "ready"
+  const rows = steps(status)
+
+  return (
+    <div
+      className={cn(
+        "rounded-lg border text-xs",
+        failed
+          ? "border-destructive/20 bg-destructive/5"
+          : settingUp
+            ? "border-yellow-500/20 bg-yellow-500/5"
+            : "border-border/40 bg-muted/20",
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between border-b border-inherit px-3 py-2">
+        <span
+          className={cn(
+            "font-mono text-[11px] font-medium",
+            failed
+              ? "text-destructive"
+              : settingUp
+                ? "text-yellow-500 dark:text-yellow-400"
+                : done
+                  ? "text-green-600 dark:text-green-400"
+                  : "text-muted-foreground",
+          )}
+        >
+          {settingUp ? phaseLabel(status) : done ? "Setup complete" : failed ? "Setup failed" : "Setup"}
+        </span>
+        {settingUp && <span className="font-mono text-[11px] tabular-nums text-muted-foreground">{pct}%</span>}
+        {done && <CheckIcon className="h-3 w-3 text-green-500" />}
+      </div>
+
+      {settingUp && (
+        <div className="px-3 pb-1 pt-2.5">
+          <div className="h-1 overflow-hidden rounded-full bg-muted">
+            <div
+              className={cn(
+                "h-full rounded-full transition-all duration-700 motion-reduce:transition-none",
+                failed ? "bg-destructive" : "bg-yellow-400",
+              )}
+              style={{ width: `${pct}%` }}
+            />
+          </div>
+        </div>
+      )}
+
+      {(rows.length > 0 || settingUp || failed) && (
+        <div className="space-y-2 px-3 py-2.5">
+          {rows.length > 0 ? (
+            rows.map((step) => (
+              <div key={step.key} className="flex items-center gap-2">
+                <StepIndicator state={step.state} />
+                <span
+                  className={cn(
+                    "shrink-0",
+                    step.state === "done"
+                      ? "text-muted-foreground/50"
+                      : step.state === "running"
+                        ? "text-foreground/80"
+                        : step.state === "error"
+                          ? "text-destructive/70"
+                          : "text-muted-foreground/30",
+                  )}
+                >
+                  {step.icon}
+                </span>
+                <span
+                  className={cn(
+                    "min-w-0 truncate font-mono leading-none",
+                    step.state === "done"
+                      ? "text-muted-foreground/70"
+                      : step.state === "running"
+                        ? "font-medium text-foreground"
+                        : step.state === "error"
+                          ? "text-destructive"
+                          : "text-muted-foreground/40",
+                  )}
+                >
+                  {step.label}
+                </span>
+                {step.suffix && <span className="font-mono text-muted-foreground/50">{step.suffix}</span>}
+              </div>
+            ))
+          ) : settingUp ? (
+            // No step yet: the container exists but its agent hasn't reported a phase — which is
+            // most of the wait on a cold start, so it gets a line rather than an empty box.
+            <div className="flex items-center gap-2 text-muted-foreground">
+              <LoaderIcon className="h-3 w-3 shrink-0 animate-spin motion-reduce:animate-none" />
+              <span className="font-mono">Waiting for container…</span>
+            </div>
+          ) : null}
+
+          {failed && status?.error && (
+            <div className="mt-1 break-all rounded bg-destructive/10 px-2 py-1.5 font-mono text-[11px] leading-4 text-destructive">
+              {status.error}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/index.ts

@@ -208,6 +208,13 @@ export type {
   OAuthProvider,
 } from "./components/auth"
 
+// ActionMenu — the `⋯` menu described as data (`{ label, icon, onClick }[]`)
+// rather than assembled from parts: the caller owns what an entry does, the
+// package owns the markup, the states, and the separators (which are normalized,
+// so a conditional entry can't leave a stray rule behind).
+export { ActionMenu } from "./components/action-menu"
+export type { ActionMenuProps, ActionMenuItem, ActionMenuEntry, ActionMenuLinkRender } from "./components/action-menu"
+
 // Kbd — one keyboard cap, or a whole shortcut (`keys="mod+k"` → ⌘ K). Used by the
 // palette, exported on its own for anywhere else a shortcut needs drawing.
 export { Kbd } from "./components/kbd"