@spunto/design-system 0.19.0 → 0.21.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`,
@@ -309,6 +332,29 @@ And the read-only twin of that form:
 - **Container queries** here too: the panel is 288 px in a sidebar on a 27" screen
   and full width on a phone — and the desktop case is the narrow one.
 
+And the build that configuration triggers, while it runs:
+
+- **`BuildSteps`** — an image build as the **list of blocks it is made of**
+  (base image, bootstrap, one per devcontainer feature, VS Code extensions,
+  finalize, DinD seed) rather than a wall of log. Each row lights up in turn and
+  carries its own duration, so "what is it doing, and for how long" reads at a
+  glance and a slow feature is visibly *the* slow one.
+- **The whole plan is drawn greyed out from the first frame**, instead of rows
+  appearing one by one: the list doubles as a table of contents for what the
+  image contains, the `done/total` counter has a denominator immediately, and
+  nothing shifts under the cursor for the four minutes of a build. A block
+  *absent* from the plan isn't `skipped` — `skipped` is a block that was reached
+  and had nothing to do.
+- **Presentational, so it isn't only about Docker**: it knows no WebSocket, no
+  marker, no daemon — hand it a snapshot of timestamped blocks and it draws.
+  Anything that can describe itself as ordered blocks (a CI pipeline, a
+  migration, a multi-phase command) can feed it.
+- **Timestamps in, durations out.** The running block counts from `startedAt`
+  itself, every second — a duration computed app-side freezes between two
+  snapshots and reads as a stuck build. Under a minute the package's
+  `formatDuration` is reused (one formatter, no drift); past it the format
+  switches to `2m 13s`.
+
 ## Marketing — `/marketing`
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

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/projects/build-steps.tsx

@@ -0,0 +1,213 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import {
+  BoxIcon,
+  CheckIcon,
+  CircleIcon,
+  LayersIcon,
+  Loader2Icon,
+  MinusIcon,
+  PuzzleIcon,
+  TerminalIcon,
+  XIcon,
+} from "lucide-react"
+
+import { cn, formatDuration } from "../../utils"
+
+export type BuildStepState = "pending" | "running" | "done" | "error" | "skipped"
+
+/** The family a block belongs to — an icon, not a status. */
+export type BuildStepKind = "image" | "runtime" | "feature" | "extensions" | "finalize"
+
+export interface BuildStepItem {
+  id: string
+  label: string
+  kind: BuildStepKind
+  /** Second line: the base image ref, a feature's OCI ref, "3 extensions"… */
+  detail?: string
+  state: BuildStepState
+  /** ISO timestamps — the elapsed time of the running block ticks from `startedAt`. */
+  startedAt?: string
+  completedAt?: string
+}
+
+export interface BuildStepsProps {
+  steps: BuildStepItem[]
+  title?: string
+  /** Shown instead of the list when there is nothing to draw yet. */
+  emptyLabel?: string
+  className?: string
+}
+
+const KIND_ICON: Record<BuildStepKind, typeof BoxIcon> = {
+  image: LayersIcon,
+  runtime: TerminalIcon,
+  feature: PuzzleIcon,
+  extensions: PuzzleIcon,
+  finalize: BoxIcon,
+}
+
+/**
+ * `formatDuration` with a minutes tier on top.
+ *
+ * The package's formatter stops at seconds, which is right where it is used
+ * (a command, a request) and wrong here: pulling a base image or compiling a
+ * feature routinely passes the minute, and "127s" is a number one has to
+ * convert before reading it. Below a minute it delegates, so the two never
+ * drift on the part they share.
+ */
+function formatStepDuration(ms: number): string {
+  if (ms < 60_000) return formatDuration(ms)
+  const s = Math.round(ms / 1000)
+  const m = Math.floor(s / 60)
+  const rest = s % 60
+  return rest ? `${m}m ${rest}s` : `${m}m`
+}
+
+/** Elapsed for a block: fixed once it ended, ticking while it runs. */
+function useStepDuration(step: BuildStepItem): string | null {
+  const running = step.state === "running" && !!step.startedAt
+  const [now, setNow] = useState(() => Date.now())
+
+  useEffect(() => {
+    if (!running) return
+    const id = setInterval(() => setNow(Date.now()), 1000)
+    return () => clearInterval(id)
+  }, [running])
+
+  if (!step.startedAt) return null
+  const start = new Date(step.startedAt).getTime()
+  if (Number.isNaN(start)) return null
+  const end = step.completedAt ? new Date(step.completedAt).getTime() : running ? now : null
+  if (end == null || Number.isNaN(end)) return null
+  return formatStepDuration(end - start)
+}
+
+function StepBullet({ state }: { state: BuildStepState }) {
+  const base = "flex h-5 w-5 shrink-0 items-center justify-center rounded-full border"
+  if (state === "running")
+    return (
+      <span className={cn(base, "border-primary/40 bg-primary/10 text-primary")}>
+        <Loader2Icon className="h-3 w-3 animate-spin motion-reduce:animate-none" />
+      </span>
+    )
+  if (state === "done")
+    return (
+      <span className={cn(base, "border-green-500/40 bg-green-500/10 text-green-600 dark:text-green-400")}>
+        <CheckIcon className="h-3 w-3" />
+      </span>
+    )
+  if (state === "error")
+    return (
+      <span className={cn(base, "border-destructive/40 bg-destructive/10 text-destructive")}>
+        <XIcon className="h-3 w-3" />
+      </span>
+    )
+  if (state === "skipped")
+    return (
+      <span className={cn(base, "border-border bg-muted/40 text-muted-foreground/60")}>
+        <MinusIcon className="h-3 w-3" />
+      </span>
+    )
+  return (
+    <span className={cn(base, "border-border bg-background text-muted-foreground/40")}>
+      <CircleIcon className="h-1.5 w-1.5 fill-current" />
+    </span>
+  )
+}
+
+function StepRow({ step, last }: { step: BuildStepItem; last: boolean }) {
+  const duration = useStepDuration(step)
+  const KindIcon = KIND_ICON[step.kind] ?? BoxIcon
+  const dim = step.state === "pending" || step.state === "skipped"
+
+  return (
+    <li className="relative flex gap-2.5 pb-2.5 last:pb-0">
+      {/* The rail joining the bullets — drawn behind them, stopped on the last row. */}
+      {!last && <span aria-hidden className="absolute left-[9px] top-5 h-full w-px bg-border" />}
+      <StepBullet state={step.state} />
+
+      <div className="min-w-0 flex-1">
+        <div className="flex items-baseline gap-2">
+          <span
+            className={cn(
+              "min-w-0 flex-1 truncate text-[12px] leading-5",
+              step.state === "running" && "font-medium text-foreground",
+              step.state === "done" && "text-foreground",
+              step.state === "error" && "font-medium text-destructive",
+              dim && "text-muted-foreground/70",
+            )}
+            title={step.label}
+          >
+            {step.label}
+          </span>
+          {duration && (
+            <span className="shrink-0 font-mono text-[10px] tabular-nums text-muted-foreground">{duration}</span>
+          )}
+        </div>
+        {step.detail && (
+          <div className="flex items-center gap-1 text-[10px] text-muted-foreground/70">
+            <KindIcon className="h-2.5 w-2.5 shrink-0" />
+            <span className="min-w-0 truncate" title={step.detail}>
+              {step.detail}
+            </span>
+          </div>
+        )}
+      </div>
+    </li>
+  )
+}
+
+/**
+ * An image build, as the list of blocks it is actually made of, instead of a wall of log.
+ *
+ * A project image build pulls a base image, creates the user, installs the editor and the terminal
+ * tooling, every devcontainer feature and every VS Code extension, then bakes the DinD seed — all of
+ * it, until now, indistinguishable from the outside: one terminal scrolling. Here each of those is a
+ * row that lights up in turn, with its own duration, so "what is it doing, and for how long" is
+ * readable at a glance and a slow feature is visibly *the* slow one.
+ *
+ * Purely presentational — it draws the snapshot it's given (the app streams it from the build's log
+ * socket, and owns every byte of that transport). The whole plan is known upfront, so the blocks
+ * that haven't run yet are drawn greyed out rather than appearing one by one: it doubles as a table
+ * of contents for what the image is made of, which is what these blocks are on their way to becoming
+ * (a checklist of what to include).
+ *
+ * Sized by its container, scrolls inside it: give it a height (`className="h-full"` in a panel) and
+ * only the list scrolls — the header with its `done/total` counter stays put.
+ */
+export function BuildSteps({ steps, title = "Build steps", emptyLabel = "No step reported", className }: BuildStepsProps) {
+  const done = steps.filter((s) => s.state === "done").length
+  const failed = steps.some((s) => s.state === "error")
+
+  return (
+    <div data-slot="build-steps" className={cn("flex min-h-0 flex-col", className)}>
+      <div className="flex shrink-0 items-baseline justify-between gap-2 px-3 py-2">
+        <span className="text-[11px] font-medium text-muted-foreground">{title}</span>
+        {steps.length > 0 && (
+          <span
+            className={cn(
+              "font-mono text-[10px] tabular-nums",
+              failed ? "text-destructive" : "text-muted-foreground",
+            )}
+          >
+            {done}/{steps.length}
+          </span>
+        )}
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto px-3 pb-3">
+        {steps.length === 0 ? (
+          <p className="text-[11px] text-muted-foreground/70">{emptyLabel}</p>
+        ) : (
+          <ol className="relative">
+            {steps.map((step, i) => (
+              <StepRow key={step.id} step={step} last={i === steps.length - 1} />
+            ))}
+          </ol>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/projects/index.ts

@@ -92,6 +92,13 @@ export type { ChipListProps, ChipItem, ChipTone } from "./chip-list"
 export { BuildCacheList, BuildStateLabel, PrebuildButton } from "./build-cache-list"
 export type { BuildCacheListProps, PrebuildButtonProps } from "./build-cache-list"
 
+// The build itself, while it runs: the blocks an image is made of, each lighting
+// up in turn. Same domain as the cache list it sits next to (a project's image),
+// hence this entry rather than one of its own — and domain it is, since the
+// blocks are Spunto's (a devcontainer feature, a VS Code extension).
+export { BuildSteps } from "./build-steps"
+export type { BuildStepsProps, BuildStepItem, BuildStepKind, BuildStepState } from "./build-steps"
+
 export { LifecycleCommands, LifecycleCommand } from "./lifecycle-commands"
 export type { LifecycleCommandsProps, LifecycleCommandProps } from "./lifecycle-commands"
 

package/src/components/workers/index.ts

@@ -9,6 +9,12 @@
 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"
 

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/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"