@spunto/design-system 0.9.2 → 0.9.3

package/README.md

@@ -73,6 +73,36 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
   provider is also the umbrella that mounts the tooltip delay group and the overlay
   portal container the dialogs/selects render into.
 
+## Domain components — `@spunto/design-system/workers`
+
+Everything above is domain-free: a `Button` knows nothing about Spunto. Components
+that **do** know a Spunto concept live behind their own entry point, so the root
+export stays primitives-only and a third-party consumer never carries the notion
+of a worker. **The rule for what comes next: any new component that knows a domain
+concept goes behind a domain sub-export, never in the root entry.**
+
+```tsx
+import { Button, Card } from "@spunto/design-system"        // primitives
+import { WorkerCard } from "@spunto/design-system/workers"  // domain
+```
+
+- **`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.
+- **Its bricks, exported individually** because the table view assembles them
+  differently: `WorkerStatusDot`/`WorkerStatusPill` (+`resolveWorkerStatus`,
+  `workerStatusConfig`), `SetupProgress` (+`setupProgress`, `phaseLabel`,
+  `setupTotalMs`), `StepIndicator`, `ResourceBars`, `GitBranchChips`/
+  `GitStatusSummary`, `TagChips` (+`tagColor`), `CreatorAvatar`.
+- **Types are structural**, never the apps' OpenAPI types: the dashboard and
+  Spunto Lite model a worker differently, so `WorkerCardWorker` asks for the
+  minimum, everything optional but `id`, and an unknown state falls back to
+  `pending` instead of throwing.
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once
@@ -145,3 +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.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.2",
+  "version": "0.9.3",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,10 @@
       "types": "./src/colors.ts",
       "import": "./src/colors.ts"
     },
+    "./workers": {
+      "types": "./src/components/workers/index.ts",
+      "import": "./src/components/workers/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"
@@ -54,6 +58,7 @@
     "@xterm/xterm": "^6.0.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "lucide-react": "^1.7.0",
     "tailwind-merge": "^3.6.0"
   },
   "peerDependencies": {

package/src/components/workers/creator-avatar.tsx

@@ -0,0 +1,38 @@
+// Who spawned the worker, in 20 px.
+//
+// A plain <img>, deliberately: the design system is consumed by two Next apps
+// *and* by a Vite showcase, so it can't reach for `next/image`. Avatars come
+// from GitHub/Google CDNs already sized for this.
+
+import { cn } from "../../utils"
+import type { WorkerCreator } from "./types"
+
+export function CreatorAvatar({ creator, className }: { creator: WorkerCreator; className?: string }) {
+  if (creator.avatarUrl) {
+    return (
+      <img
+        src={creator.avatarUrl}
+        alt={creator.name}
+        className={cn("h-5 w-5 shrink-0 rounded-full object-cover ring-1 ring-border", className)}
+      />
+    )
+  }
+
+  const initials = creator.name
+    .split(" ")
+    .map((n) => n[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2)
+
+  return (
+    <span
+      className={cn(
+        "flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-muted text-[9px] font-semibold text-muted-foreground ring-1 ring-border",
+        className
+      )}
+    >
+      {initials}
+    </span>
+  )
+}

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

@@ -0,0 +1,128 @@
+// "repo · branch +3" chips — what a worker is actually working on.
+//
+// The dashboard's version shows the modified count; Lite's also shows ahead /
+// behind. This is the union: every counter is rendered only when the caller
+// supplies it, so neither app has to send a field it doesn't have.
+
+import { ArrowDownIcon, ArrowUpIcon, ExternalLinkIcon, GitBranchIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+
+export interface GitRepoStatus {
+  /** Absolute path of the checkout inside the worker — also the React key. */
+  path: string
+  branch?: string | null
+  /** Display name; defaults to the last segment of `path`. */
+  name?: string
+  /** Uncommitted files. */
+  modified?: number
+  /** Commits ahead of / behind the upstream branch. */
+  ahead?: number
+  behind?: number
+}
+
+export interface GitBranchChipsProps {
+  repos: GitRepoStatus[]
+  /**
+   * Chip → URL. A slot, not a link component: the design system knows nothing
+   * about code-server URLs, and returning `undefined` renders a plain span.
+   */
+  repoHref?: (repo: GitRepoStatus) => string | undefined
+  className?: string
+}
+
+export function repoName(repo: GitRepoStatus): string {
+  return repo.name ?? repo.path.split("/").filter(Boolean).pop() ?? repo.path
+}
+
+/** One chip per checked-out repository, wrapping onto as many lines as needed. */
+export function GitBranchChips({ repos, repoHref, className }: GitBranchChipsProps) {
+  if (!repos.length) return null
+
+  return (
+    // `@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"
+        return (
+          <Tag
+            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 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="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" />
+            {/* 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 shrink-0 opacity-40" />}
+          </Tag>
+        )
+      })}
+    </div>
+  )
+}
+
+/** Amber for local work not yet committed/pushed, muted for what's merely behind. */
+function RepoCounters({ repo }: { repo: GitRepoStatus }) {
+  return (
+    <>
+      {!!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 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 shrink-0 items-center text-muted-foreground/70">
+          <ArrowDownIcon className="h-2.5 w-2.5" />
+          {repo.behind}
+        </span>
+      )}
+    </>
+  )
+}
+
+export interface GitStatusSummaryProps {
+  repos: GitRepoStatus[]
+  /** Heading above the list — e.g. "Open in VS Code" inside a tooltip. */
+  title?: string
+  className?: string
+}
+
+/**
+ * The same information as the chips, stacked one repo per line. Meant for the
+ * inside of a tooltip or a popover, where chips would wrap badly — the tooltip
+ * itself stays the app's business (the design system doesn't decide what opens
+ * it).
+ */
+export function GitStatusSummary({ repos, title, className }: GitStatusSummaryProps) {
+  if (!repos.length) return null
+
+  return (
+    <span data-slot="git-status-summary" className={cn("flex flex-col gap-1", className)}>
+      {title && <span className="text-[10px] uppercase tracking-wide opacity-60">{title}</span>}
+      {repos.map((repo) => (
+        <span key={repo.path} className="flex items-center gap-1.5">
+          <span className="font-medium">{repoName(repo)}</span>
+          <GitBranchIcon className="h-3 w-3 opacity-60" />
+          <span className="font-mono">{repo.branch || "—"}</span>
+          <RepoCounters repo={repo} />
+        </span>
+      ))}
+    </span>
+  )
+}

package/src/components/workers/index.ts

@@ -0,0 +1,35 @@
+// @spunto/design-system/workers — Spunto's *domain* components.
+//
+// Deliberately a sub-export rather than part of the main entry: the root of the
+// package stays "primitives with no domain" (a Button knows nothing about a
+// worker), and a third party consuming the design system never has to carry the
+// notion of a worker. New business components go here — see the README's
+// "Domain components" section for the rule.
+
+export { WorkerCard } from "./worker-card"
+export type { WorkerCardProps, LinkRender } from "./worker-card"
+
+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 { ResourceBars } from "./resource-bars"
+export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
+
+export { GitBranchChips, GitStatusSummary, repoName } from "./git-branch-chips"
+export type { GitBranchChipsProps, GitRepoStatus, GitStatusSummaryProps } from "./git-branch-chips"
+
+export { TagChips } from "./tag-chips"
+export type { TagChipsProps } from "./tag-chips"
+export { tagColor } from "./tag-color"
+export type { TagPalette } from "./tag-color"
+
+export { CreatorAvatar } from "./creator-avatar"
+
+export type { WorkerCardWorker, 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.
+export { cn, formatDuration, formatRelativeTime } from "../../utils"

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

@@ -0,0 +1,104 @@
+// CPU + memory of a running container, as two thin bars.
+//
+// Written identically in the dashboard's card and its table row — the `compact`
+// flag is the only thing that ever differed between the two copies.
+
+import type { ReactNode } from "react"
+import { CpuIcon, MemoryStickIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+
+export interface WorkerStats {
+  cpuPercent: number
+  memUsageMb: number
+  memLimitMb?: number
+  memPercent?: number
+}
+
+export interface ResourceBarsProps {
+  stats: WorkerStats
+  /** Drops the framed panel — just the two bars, for a table cell or a tooltip. */
+  compact?: boolean
+  className?: string
+}
+
+/** Past this, the bar turns red: the container is about to be the problem. */
+const DANGER = 80
+
+export function ResourceBars({ stats, compact = false, className }: ResourceBarsProps) {
+  const cpu = stats.cpuPercent ?? 0
+  const mem = stats.memPercent ?? 0
+
+  return (
+    <div
+      data-slot="resource-bars"
+      className={cn(
+        // 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
+      )}
+    >
+      <Metric
+        icon={<CpuIcon className="h-3 w-3" />}
+        label="CPU"
+        value={`${cpu.toFixed(1)}%`}
+        valueClass={cpu > DANGER ? "text-orange-500 dark:text-orange-400" : "text-foreground/70"}
+        percent={cpu}
+        // Flame for CPU, Build amber for memory: two bars side by side need to be
+        // told apart at a glance, and both hues already mean "compute" here.
+        barClass={cpu > DANGER ? "bg-destructive" : "bg-primary"}
+      />
+      <Metric
+        icon={<MemoryStickIcon className="h-3 w-3" />}
+        label="Memory"
+        value={
+          <>
+            {(stats.memUsageMb ?? 0).toFixed(0)}
+            <span className="text-muted-foreground/50"> MB</span>
+          </>
+        }
+        valueClass="text-foreground/70"
+        percent={mem}
+        barClass={mem > DANGER ? "bg-destructive" : "bg-build"}
+      />
+    </div>
+  )
+}
+
+function Metric({
+  icon,
+  label,
+  value,
+  valueClass,
+  percent,
+  barClass,
+}: {
+  icon: ReactNode
+  label: string
+  value: ReactNode
+  valueClass: string
+  percent: number
+  barClass: string
+}) {
+  return (
+    <div>
+      <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("shrink-0 font-mono text-[11px] tabular-nums", valueClass)}>{value}</span>
+      </div>
+      <div className="h-1 overflow-hidden rounded-full bg-muted">
+        <div
+          className={cn("h-full rounded-full transition-all duration-500 motion-reduce:transition-none", barClass)}
+          style={{ width: `${Math.min(Math.max(percent, 0), 100)}%` }}
+        />
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,130 @@
+// Worker setup, as a percentage and a sentence.
+//
+// The phase → percentage switch and the phase → label switch were written twice,
+// by hand, in two apps — and are the kind of thing that drifts silently (a phase
+// added on the agent side lands in one app's switch and not the other's). One
+// copy, here, plus the bar itself.
+//
+// Hookless, so it stays callable from a React Server Component.
+
+import { CheckIcon, CircleIcon, LoaderIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import type { WorkerSetupStatus } from "./types"
+
+/**
+ * Setup completion, 0-100.
+ *
+ * The numbers are deliberately uneven: they're calibrated on how long each phase
+ * actually takes, not on how many phases there are. Cloning gets a 30-point
+ * span sub-divided by repository, because it's the phase where a user watches
+ * the longest and the only one with real sub-progress to report.
+ */
+export function setupProgress(status: WorkerSetupStatus | null | undefined): number {
+  if (!status) return 5
+  switch (status.phase) {
+    case "initializing": return 10
+    case "credentials": return 25
+    case "dotfiles": return 35
+    case "cloning": {
+      const repos = status.repos ?? []
+      const done = repos.filter((r) => r.state === "done").length
+      const total = repos.length || 1
+      return 40 + Math.round((done / total) * 30)
+    }
+    case "lifecycle": {
+      if (status.postCreate === "running") return 75
+      if (status.postCreate === "done" && status.postStart === "running") return 88
+      return 80
+    }
+    case "ready": return 100
+    case "error": return 100
+    default: return 5
+  }
+}
+
+/** Human phase label — the line printed above the bar. */
+export function phaseLabel(status: WorkerSetupStatus | null | undefined): string {
+  if (!status) return "Starting up…"
+  switch (status.phase) {
+    case "initializing": return "Starting up…"
+    case "credentials": return "Configuring credentials…"
+    case "dotfiles": return "Installing dotfiles…"
+    case "cloning": return "Cloning repositories…"
+    case "lifecycle":
+      if (status.postCreate === "running") return "Running post-create command…"
+      if (status.postStart === "running") return "Running post-start command…"
+      return "Running setup commands…"
+    case "ready": return "Ready"
+    case "error": return "Setup failed"
+    default: return "Setting up…"
+  }
+}
+
+/**
+ * Total startup duration (ms) from the container-side phase timings, or null
+ * when we can't bracket it — old or crashed workers have no `ready` stamp, and
+ * an invented duration would be worse than no duration.
+ */
+export function setupTotalMs(status: WorkerSetupStatus | null | undefined): number | null {
+  const t = status?.timings
+  if (!t || t.initializing == null || t.ready == null) return null
+  const d = t.ready - t.initializing
+  return d > 0 ? d : null
+}
+
+export interface SetupProgressProps {
+  status?: WorkerSetupStatus | null
+  /** Hides the phase line + percentage, keeping only the bar (table rows). */
+  barOnly?: boolean
+  className?: string
+}
+
+/** Phase label + percentage + the bar itself. Red as soon as the setup failed. */
+export function SetupProgress({ status, barOnly = false, className }: SetupProgressProps) {
+  const pct = setupProgress(status)
+  const failed = status?.phase === "error"
+
+  return (
+    <div className={cn("w-full", className)}>
+      {!barOnly && (
+        <div className="mb-1.5 flex items-center justify-between gap-2">
+          <span
+            className={cn(
+              "min-w-0 truncate font-mono text-[11px]",
+              failed ? "text-destructive" : "text-yellow-500 dark:text-yellow-400"
+            )}
+          >
+            {phaseLabel(status)}
+          </span>
+          <span className="shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground">{pct}%</span>
+        </div>
+      )}
+      <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>
+  )
+}
+
+export type StepState = "pending" | "running" | "done" | "error"
+
+/**
+ * The per-step bullet of a detailed setup view (one repository being cloned, a
+ * lifecycle command running). Same four states, same four colours, everywhere.
+ */
+export function StepIndicator({ state, className }: { state: StepState; className?: string }) {
+  const common = cn("h-3 w-3 shrink-0", className)
+
+  if (state === "running")
+    return <LoaderIcon className={cn(common, "animate-spin text-yellow-400 motion-reduce:animate-none")} />
+  if (state === "done") return <CheckIcon className={cn(common, "text-green-500")} />
+  if (state === "error") return <CircleIcon className={cn(common, "fill-destructive text-destructive")} />
+  return <CircleIcon className={cn(common, "text-muted-foreground/30")} />
+}

package/src/components/workers/tag-chips.tsx

@@ -0,0 +1,139 @@
+"use client"
+
+// Free-form worker tags, coloured by hash.
+//
+// Read-only by default (Spunto Lite's case). Pass `onAdd`/`onRemove` and the
+// chips grow a cross and a "+" button — the *persistence* stays with the caller,
+// this component only reports intent.
+
+import { useEffect, useRef, useState } from "react"
+import { PlusIcon, XIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { tagColor } from "./tag-color"
+
+export interface TagChipsProps {
+  tags: string[]
+  /**
+   * Both callbacks receive the tag *and* the resulting list. Persist `next` —
+   * recomputing it caller-side from a polled `worker.tags` silently drops any
+   * edit made since the last refetch (two tags added in a row, then one removed,
+   * and the second one disappears with it).
+   */
+  onAdd?: (tag: string, next: string[]) => void
+  onRemove?: (tag: string, next: string[]) => void
+  /** Longest accepted tag; anything past it is truncated on commit. */
+  maxLength?: number
+  className?: string
+}
+
+export function TagChips({ tags, onAdd, onRemove, maxLength = 32, className }: TagChipsProps) {
+  const editable = !!(onAdd || onRemove)
+  // Local echo so a freshly typed tag appears instantly, resynced whenever the
+  // caller's list changes — the server's answer always wins in the end.
+  const [local, setLocal] = useState<string[]>(tags)
+  const [input, setInput] = useState("")
+  const [adding, setAdding] = useState(false)
+  const inputRef = useRef<HTMLInputElement>(null)
+
+  // Compared by content, not by reference: callers routinely pass
+  // `worker.tags ?? []`, a fresh array on every poll, and swapping state for an
+  // identical list would re-render the whole card every few seconds.
+  useEffect(() => {
+    setLocal((prev) => (prev.length === tags.length && prev.every((t, i) => t === tags[i]) ? prev : tags))
+  }, [tags])
+
+  function commit() {
+    // Spaces and commas are the separators a user reflexively types; swallowing
+    // them here keeps "one chip = one word" true without an error message.
+    const raw = input.trim().replace(/,/g, "").slice(0, maxLength)
+    if (raw && !local.includes(raw)) {
+      const next = [...local, raw]
+      setLocal(next)
+      onAdd?.(raw, next)
+    }
+    setInput("")
+    setAdding(false)
+  }
+
+  function remove(tag: string) {
+    const next = local.filter((t) => t !== tag)
+    setLocal(next)
+    onRemove?.(tag, next)
+  }
+
+  const shown = editable ? local : tags
+  if (!shown.length && !editable) return null
+
+  return (
+    <>
+      {shown.map((tag) => {
+        const c = tagColor(tag)
+        return (
+          <span
+            key={tag}
+            className={cn(
+              "inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-[10px] font-medium leading-none",
+              c.bg,
+              c.text,
+              c.border,
+              className
+            )}
+          >
+            {tag}
+            {onRemove && (
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  remove(tag)
+                }}
+                className="ml-0.5 cursor-pointer opacity-50 transition-opacity hover:opacity-100"
+                aria-label={`Remove tag ${tag}`}
+              >
+                <XIcon className="h-2.5 w-2.5" />
+              </button>
+            )}
+          </span>
+        )
+      })}
+
+      {onAdd &&
+        (adding ? (
+          <input
+            ref={inputRef}
+            autoFocus
+            value={input}
+            onChange={(e) => setInput(e.target.value.replace(/[\s,]/g, ""))}
+            onKeyDown={(e) => {
+              if (e.key === "Enter") {
+                e.preventDefault()
+                commit()
+              }
+              if (e.key === "Escape") {
+                setInput("")
+                setAdding(false)
+              }
+            }}
+            // Blur-commits rather than discards: clicking away after typing a
+            // tag reads as "done", never as "cancel".
+            onBlur={commit}
+            placeholder="tag…"
+            className="h-4 w-20 rounded-full border border-primary/40 bg-primary/5 px-2 text-[10px] text-primary outline-none focus:border-primary/60"
+          />
+        ) : (
+          <button
+            type="button"
+            onClick={(e) => {
+              e.stopPropagation()
+              setAdding(true)
+            }}
+            className="inline-flex cursor-pointer items-center rounded-full border border-dashed border-border px-1.5 py-0.5 text-[10px] text-muted-foreground/50 transition-colors hover:border-border/80 hover:text-muted-foreground"
+            aria-label="Add tag"
+          >
+            <PlusIcon className="h-2.5 w-2.5" />
+          </button>
+        ))}
+    </>
+  )
+}

package/src/components/workers/tag-color.ts

@@ -0,0 +1,28 @@
+// Deterministic tag → pastel palette, split out of `tag-chips.tsx` (a "use client"
+// module) so it stays callable from a React Server Component and from plain
+// helpers — same reason `buttonVariants` has its own file.
+
+const TAG_PALETTES = [
+  { bg: "bg-orange-500/12", text: "text-orange-700 dark:text-orange-300", border: "border-orange-400/30" },
+  { bg: "bg-amber-500/12",  text: "text-amber-700 dark:text-amber-300",   border: "border-amber-400/30"  },
+  { bg: "bg-lime-500/12",   text: "text-lime-700 dark:text-lime-300",     border: "border-lime-400/30"   },
+  { bg: "bg-green-500/12",  text: "text-green-700 dark:text-green-300",   border: "border-green-400/30"  },
+  { bg: "bg-teal-500/12",   text: "text-teal-700 dark:text-teal-300",     border: "border-teal-400/30"   },
+  { bg: "bg-sky-500/12",    text: "text-sky-700 dark:text-sky-300",       border: "border-sky-400/30"    },
+  { bg: "bg-violet-500/12", text: "text-violet-700 dark:text-violet-300", border: "border-violet-400/30" },
+  { bg: "bg-pink-500/12",   text: "text-pink-700 dark:text-pink-300",     border: "border-pink-400/30"   },
+] as const
+
+export type TagPalette = (typeof TAG_PALETTES)[number]
+
+/**
+ * Notion-style pastel picked from the tag's own characters, so the same tag is
+ * the same colour on every card, in every app, forever — no palette state, no
+ * assignment to persist. The classes are written out in full (never built by
+ * string concatenation) so Tailwind's scanner can see them.
+ */
+export function tagColor(tag: string): TagPalette {
+  let h = 0
+  for (let i = 0; i < tag.length; i++) h = (Math.imul(31, h) + tag.charCodeAt(i)) | 0
+  return TAG_PALETTES[Math.abs(h) % TAG_PALETTES.length]
+}

package/src/components/workers/types.ts

@@ -0,0 +1,44 @@
+// Structural, deliberately laxist shapes for everything worker-related.
+//
+// The design system must NOT import the OpenAPI-generated types of the Spunto
+// dashboard (nor Spunto Lite's): the two apps model a worker differently — the
+// dashboard has both a lifecycle `state` and a docker-level `dockerState`, Lite
+// has a single `state`; the dashboard's `name` is nullable and backed by an
+// `index`, Lite's is guaranteed. So the types below describe the *minimum* these
+// components read, every field optional, and the state resolution tolerates an
+// unknown value instead of crashing on it (see `resolveWorkerStatus`).
+
+/** Container-side setup progress, as reported by the worker agent. */
+export interface WorkerSetupStatus {
+  /** `initializing` | `credentials` | `dotfiles` | `cloning` | `lifecycle` | `ready` | `error`. */
+  phase?: string | null
+  repos?: { name?: string; state?: string | null }[] | null
+  postCreate?: string | null
+  postStart?: string | null
+  error?: string | null
+  /** Per-milestone start timestamps (epoch ms) — `initializing` → `ready` brackets the startup. */
+  timings?: Record<string, number> | null
+}
+
+/** The snapshot a `WorkerCard` draws. Everything but `id` is optional. */
+export interface WorkerCardWorker {
+  id: string
+  name?: string | null
+  /** Fallback identity when `name` is empty — renders as "Workspace #3". */
+  index?: number | null
+  /** Lifecycle state: `provisioning` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `error`. */
+  state?: string | null
+  /** Docker-level state: `running` | `stopped` | `exited` | `created` | `not_found` | `error`. */
+  dockerState?: string | null
+  createdAt?: string | null
+  projectVersion?: number | null
+  tags?: string[] | null
+  setupStatus?: WorkerSetupStatus | null
+}
+
+/** Author of a worker — avatar + name, nothing else. */
+export interface WorkerCreator {
+  name: string
+  login?: string
+  avatarUrl?: string | null
+}

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

@@ -0,0 +1,345 @@
+"use client"
+
+import type { ReactNode } from "react"
+import {
+  AlertTriangleIcon,
+  ChevronRightIcon,
+  ClockIcon,
+  ServerIcon,
+  TimerIcon,
+  WifiOffIcon,
+  XIcon,
+} from "lucide-react"
+
+import { cn, formatDuration, formatRelativeTime } from "../../utils"
+import { buttonVariants } from "../button-variants"
+import { CreatorAvatar } from "./creator-avatar"
+import { GitBranchChips, type GitRepoStatus } from "./git-branch-chips"
+import { ResourceBars, type WorkerStats } from "./resource-bars"
+import { SetupProgress, setupTotalMs } from "./setup-progress"
+import { TagChips } from "./tag-chips"
+import type { WorkerCardWorker, WorkerCreator } from "./types"
+import { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus } from "./worker-status"
+
+/** Renders the "View" affordance. A slot, so the package never imports `next/link`. */
+export type LinkRender = (props: { href: string; className?: string; children: ReactNode }) => ReactNode
+
+export interface WorkerCardProps {
+  worker: WorkerCardWorker
+
+  /** Target of the title + footer button. Omitted → the card isn't a link. */
+  href?: string
+  /**
+   * 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>`.
+   */
+  render?: { link?: LinkRender }
+
+  creator?: WorkerCreator
+  nodeName?: string
+  /** `false` draws the "Node offline" banner. `undefined` = unknown, no banner. */
+  nodeOnline?: boolean
+  /** Live container stats. Absent → no resource bars (the usual case for a stopped worker). */
+  stats?: WorkerStats | null
+  /** Checked-out repositories. Absent/empty → no chips. */
+  gitStatus?: GitRepoStatus[] | null
+  /** Chip → URL (e.g. code-server at that folder). Returning undefined renders a static chip. */
+  repoHref?: (repo: GitRepoStatus) => string | undefined
+
+  /**
+   * Tags are read-only unless at least one of these is given. Both receive the
+   * tag *and* the resulting list — persist the list, don't recompute it from a
+   * polled `worker.tags` (see `TagChips`).
+   */
+  onAddTag?: (tag: string, next: string[]) => void
+  onRemoveTag?: (tag: string, next: string[]) => void
+
+  /** Project's current config version — a worker below it gets the "Rebuild" banner. */
+  currentProjectVersion?: number
+  onRebuild?: () => void
+  rebuilding?: boolean
+
+  /** Error banner inside the card (a failed mutation, typically). */
+  error?: string | null
+  onDismissError?: () => void
+
+  /** The `⋯` menu, top-right. A slot: every entry in it calls the API. */
+  actions?: ReactNode
+  /** Replaces the default "View" footer entirely (extra buttons, a VS Code link…). */
+  footer?: ReactNode
+  /** Label of the default footer button. */
+  viewLabel?: string
+
+  className?: string
+}
+
+/**
+ * One worker, as a card: state, who spawned it, where it runs, what it's working
+ * 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
+ * (`WorkerStatusDot`, `SetupProgress`, `ResourceBars`, `GitBranchChips`,
+ * `TagChips`) is exported on its own because the table view needs them without
+ * the card.
+ *
+ * The layout is a fixed sequence of optional bands — header, setup bar, git
+ * chips, resource bars, banners, footer — and each band disappears when its data
+ * is absent, so a stopped worker collapses to a two-line card without any
+ * caller-side conditional.
+ */
+export function WorkerCard({
+  worker,
+  href,
+  render,
+  creator,
+  nodeName,
+  nodeOnline,
+  stats,
+  gitStatus,
+  repoHref,
+  onAddTag,
+  onRemoveTag,
+  currentProjectVersion,
+  onRebuild,
+  rebuilding = false,
+  error,
+  onDismissError,
+  actions,
+  footer,
+  viewLabel = "View",
+  className,
+}: WorkerCardProps) {
+  const status = resolveWorkerStatus(worker)
+  const setup = worker.setupStatus ?? null
+  const startupMs = setupTotalMs(setup)
+  const title = worker.name || (worker.index != null ? `Workspace #${worker.index}` : worker.id)
+
+  // Live detail is only meaningful once the container is up *and* done setting
+  // up: mid-setup a stale "running" from docker would show stats for a worker
+  // that isn't usable yet.
+  const settled = status.running && !status.settingUp
+  const repos = settled ? (gitStatus ?? []) : []
+  const outdated =
+    !status.settingUp &&
+    worker.projectVersion != null &&
+    currentProjectVersion != null &&
+    worker.projectVersion < currentProjectVersion
+
+  const Link: LinkRender =
+    render?.link ?? (({ href: to, className: cls, children }) => <a href={to} className={cls}>{children}</a>)
+
+  return (
+    <div
+      data-slot="worker-card"
+      // `@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">
+        <div className="flex min-w-0 items-start gap-3">
+          <WorkerStatusDot status={status} className="mt-1" />
+
+          <div className="min-w-0 flex-1">
+            <div className="flex flex-wrap items-center gap-2">
+              {/* 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">
+                  v{worker.projectVersion}
+                </span>
+              )}
+              <TagChips tags={worker.tags ?? []} onAdd={onAddTag} onRemove={onRemoveTag} />
+            </div>
+
+            {/* 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 && (
+                <MetaItem first>
+                  <CreatorAvatar creator={creator} />
+                  <span className="text-muted-foreground">{creator.name}</span>
+                </MetaItem>
+              )}
+              {nodeName && (
+                <MetaItem first={!creator}>
+                  <ServerIcon className="h-3 w-3 shrink-0" />
+                  <span className="truncate">{nodeName}</span>
+                </MetaItem>
+              )}
+              {worker.createdAt && (
+                <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 && (
+                <MetaItem title="Worker startup time (clone, features, postCreate…)">
+                  <TimerIcon className="h-3 w-3 shrink-0" />
+                  started in {formatDuration(startupMs)}
+                </MetaItem>
+              )}
+            </div>
+          </div>
+        </div>
+
+        {actions}
+      </div>
+
+      {status.settingUp && (
+        <div className="px-4 pb-3">
+          <SetupProgress status={setup} />
+        </div>
+      )}
+
+      {repos.length > 0 && (
+        <div className="px-4 pb-3">
+          <GitBranchChips repos={repos} repoHref={repoHref} />
+        </div>
+      )}
+
+      {settled && stats && (
+        <div className="px-4 pb-3">
+          <ResourceBars stats={stats} />
+        </div>
+      )}
+
+      {nodeOnline === false && (
+        <Banner tone="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 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"}
+            </button>
+          )}
+        </Banner>
+      )}
+
+      {error && (
+        <Banner tone="error">
+          {/* 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"
+              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>
+      )}
+
+      {(footer ?? href) && (
+        <div className="border-t border-border/50 bg-muted/20 px-3 py-2">
+          {footer ?? (
+            <Link href={href!} className={cn(buttonVariants({ variant: "default", size: "sm" }), "h-7 w-full gap-1.5 text-xs")}>
+              {viewLabel}
+              <ChevronRightIcon className="h-3.5 w-3.5" />
+            </Link>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * 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>
+  )
+}
+
+/**
+ * The card's inline bands. Warm tones = something to know (an unreachable node,
+ * a stale config), red = something went wrong. They keep the card's horizontal
+ * margin so they read as *inside* the card, not as a strip glued across it.
+ */
+const BANNER_TONES = {
+  /** Infrastructure problem — orange, one notch louder than a stale config. */
+  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(
+        // 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]
+      )}
+    >
+      {children}
+    </div>
+  )
+}

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

@@ -0,0 +1,181 @@
+// The single state → colours/label table both worker views read from.
+//
+// It used to live twice — `STATUS_CONFIG` in the dashboard and its hand-copied
+// twin in Spunto Lite — and the two had already drifted (different labels for
+// the same docker state, transient states handled in one and not the other).
+// This module is the union of both, plus the transient states (`pulling`,
+// `stopping`, `deleting`) that only ever existed as ad-hoc `if`s above the table.
+//
+// No "use client": pure functions and hookless components, so a React Server
+// Component can call them.
+
+import { cn } from "../../utils"
+import type { WorkerCardWorker } from "./types"
+
+export type WorkerStatusKey =
+  | "running"
+  | "stopped"
+  | "exited"
+  | "created"
+  | "not_found"
+  | "error"
+  | "pending"
+  | "setup"
+  | "pulling"
+  | "stopping"
+  | "deleting"
+
+export interface WorkerStatusConfig {
+  label: string
+  /** Class for the 8 px dot. */
+  dotClass: string
+  /** Classes for the rounded state pill (background + text + border). */
+  pillClass: string
+  /** Left border accent, for surfaces that stripe the card by state. */
+  accent: string
+}
+
+// Status semantics follow docs/design-system.md: green = running/healthy,
+// amber/yellow = in progress or warning, red = failure, neutral = idle. Errors
+// go through the `destructive` token rather than a raw red so they track the
+// theme; green/yellow have no token, so the Tailwind palette stays.
+const RUNNING: WorkerStatusConfig = {
+  label: "Running",
+  dotClass: "bg-green-500",
+  pillClass: "bg-green-500/10 text-green-600 dark:text-green-400 border-green-500/20",
+  accent: "border-l-green-500",
+}
+
+const IDLE: WorkerStatusConfig = {
+  label: "Stopped",
+  dotClass: "bg-muted-foreground/50",
+  pillClass: "bg-muted text-muted-foreground border-border",
+  accent: "border-l-border",
+}
+
+const BUSY: WorkerStatusConfig = {
+  label: "Starting…",
+  dotClass: "bg-yellow-400",
+  pillClass: "bg-yellow-500/10 text-yellow-600 dark:text-yellow-400 border-yellow-500/20",
+  accent: "border-l-yellow-400",
+}
+
+export const workerStatusConfig: Record<WorkerStatusKey, WorkerStatusConfig> = {
+  running: RUNNING,
+  stopped: IDLE,
+  exited: { ...IDLE, label: "Exited" },
+  created: { ...BUSY, label: "Created" },
+  not_found: {
+    label: "Not found",
+    dotClass: "bg-orange-400",
+    pillClass: "bg-orange-500/10 text-orange-600 dark:text-orange-400 border-orange-500/20",
+    accent: "border-l-orange-400",
+  },
+  error: {
+    label: "Error",
+    dotClass: "bg-destructive",
+    pillClass: "bg-destructive/10 text-destructive border-destructive/20",
+    accent: "border-l-destructive",
+  },
+  pending: BUSY,
+  setup: { ...BUSY, label: "Setting up…" },
+  pulling: { ...BUSY, label: "Pulling image…" },
+  stopping: { ...BUSY, label: "Stopping…" },
+  deleting: { ...BUSY, label: "Deleting…" },
+}
+
+export interface WorkerStatus extends WorkerStatusConfig {
+  key: WorkerStatusKey
+  /** The worker is still being provisioned — the setup bar is the interesting part. */
+  settingUp: boolean
+  /** Container up and past its setup — stats, git chips and the pulsing dot apply. */
+  running: boolean
+}
+
+/** Lifecycle states that mean "not usable yet, a setup is in flight". */
+const SETUP_STATES = new Set(["provisioning", "starting", "setup"])
+
+/**
+ * Worker snapshot → one status, tolerant of shapes it has never seen.
+ *
+ * Order matters: the *lifecycle* state wins whenever it describes an action in
+ * flight (deleting, stopping, pulling, setting up), because docker still reports
+ * the container as `running` throughout — showing "Running" while a worker is
+ * being deleted is the bug this ordering exists to prevent. Past that, the
+ * docker state is the truth. Apps with a single `state` field (Spunto Lite) fall
+ * through to the last block, and anything unknown lands on `pending` rather than
+ * throwing.
+ */
+export function resolveWorkerStatus(worker: WorkerCardWorker): WorkerStatus {
+  const state = worker.state ?? null
+  const docker = worker.dockerState ?? null
+
+  const of = (key: WorkerStatusKey, flags?: Partial<Pick<WorkerStatus, "settingUp" | "running">>): WorkerStatus => ({
+    key,
+    ...workerStatusConfig[key],
+    settingUp: false,
+    running: key === "running",
+    ...flags,
+  })
+
+  if (state === "deleting") return of("deleting")
+  if (state === "stopping") return of("stopping")
+  if (state === "pulling") return of("pulling", { settingUp: true })
+  if (state && SETUP_STATES.has(state)) return of("setup", { settingUp: true })
+
+  if (docker && docker in workerStatusConfig) return of(docker as WorkerStatusKey)
+  if (docker) return of("pending")
+
+  // Single-`state` apps (Lite): no docker level to consult.
+  if (state === "ready") return of("running")
+  if (state === "error") return of("error")
+  if (state === "stopped") return of("stopped")
+  return of("pending")
+}
+
+/**
+ * The 8 px state dot. It pings while the worker runs — the one animation on the
+ * card, reserved for the one state where "it is alive right now" is the message.
+ */
+export function WorkerStatusDot({
+  status,
+  className,
+}: {
+  status: WorkerStatus | WorkerStatusKey
+  className?: string
+}) {
+  const cfg = typeof status === "string" ? { ...workerStatusConfig[status], running: status === "running" } : status
+  return (
+    <span className={cn("relative flex h-2 w-2 shrink-0", className)}>
+      <span className={cn("h-2 w-2 rounded-full", cfg.dotClass)} />
+      {cfg.running && (
+        <span className="absolute inset-0 h-2 w-2 animate-ping rounded-full bg-green-500 opacity-50 motion-reduce:animate-none" />
+      )}
+    </span>
+  )
+}
+
+/** The state chip that sits next to the worker name. */
+export function WorkerStatusPill({
+  status,
+  label,
+  className,
+}: {
+  status: WorkerStatus | WorkerStatusKey
+  /** Overrides the table's label — e.g. a live setup phase instead of "Setting up…". */
+  label?: string
+  className?: string
+}) {
+  const cfg = typeof status === "string" ? workerStatusConfig[status] : status
+  return (
+    <span
+      className={cn(
+        "inline-flex items-center rounded-full border px-2 py-0.5 text-[10px] font-medium leading-none",
+        cfg.pillClass,
+        className
+      )}
+    >
+      {label ?? cfg.label}
+    </span>
+  )
+}

package/src/index.ts

@@ -1,9 +1,13 @@
 // @spunto/design-system — shared UI primitives, helpers, and color constants.
 // Tokens ship as a CSS file: `import "@spunto/design-system/styles.css"`.
 
-export { cn } from "./utils"
+export { cn, formatDuration, formatRelativeTime } from "./utils"
 export * from "./colors"
 
+// Domain (Spunto-specific) components live behind their own entry point —
+// `@spunto/design-system/workers` — so this root stays domain-free primitives.
+// See README § "Domain components".
+
 export { Button } from "./components/button"
 // `buttonVariants` is exported from its own directive-free module (not through the
 // "use client" button.tsx) so it stays callable from React Server Components.

package/src/utils.ts

@@ -5,3 +5,26 @@ import { twMerge } from "tailwind-merge"
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
+
+/**
+ * Coarse "3h ago" stamp — minutes, then hours, then days. Deliberately not a
+ * live-ticking relative time: every surface using it (worker cards, tables)
+ * already re-renders on its own polling cadence, and a second timer per row
+ * would cost more than the precision is worth.
+ */
+export function formatRelativeTime(date: string | number | Date): string {
+  const ms = date instanceof Date ? date.getTime() : new Date(date).getTime()
+  if (!Number.isFinite(ms)) return ""
+  const minutes = Math.floor((Date.now() - ms) / 60_000)
+  if (minutes < 1) return "just now"
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  return `${Math.floor(hours / 24)}d ago`
+}
+
+/** Short duration, one significant decimal under 10 s ("840ms", "4.2s", "38s"). */
+export function formatDuration(ms: number): string {
+  if (ms >= 1000) return `${(ms / 1000).toFixed(ms >= 10_000 ? 0 : 1)}s`
+  return `${Math.max(0, Math.round(ms))}ms`
+}