@spunto/design-system 0.27.0 → 0.28.0

package/package.json

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

package/src/components/workers/index.ts

@@ -27,6 +27,9 @@ export type { SetupProgressProps, StepState } from "./setup-progress"
 export { WorkerSetupTimeline } from "./worker-setup-timeline"
 export { SetupWaterfall } from "./setup-waterfall"
 
+export { WorkerStatusHistory, statusHistorySpans } from "./worker-status-history"
+export type { WorkerStatusHistoryProps, WorkerStatusSpan } from "./worker-status-history"
+
 export { ResourceBars } from "./resource-bars"
 export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
 
@@ -40,8 +43,8 @@ export type { TagPalette } from "./tag-color"
 
 export { CreatorAvatar } from "./creator-avatar"
 
-export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus } from "./types"
+export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus, WorkerStatusEvent } 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"
+export { cn, formatDuration, formatElapsed, formatRelativeTime } from "../../utils"

package/src/components/workers/types.ts

@@ -68,3 +68,25 @@ export interface WorkerCockpitWorker extends WorkerCardWorker {
   branch?: string | null
   containerId?: string | null
 }
+
+/**
+ * One row of a worker's status history — a transition, as the control plane journaled it.
+ *
+ * Mirrors a `worker_status_events` row of the dashboard (`from`, `to`, `source`, `meta`, `at`),
+ * laxly: `to` and `at` are the only fields the history can't draw without. `source` is a free
+ * string on purpose — the package phrases the ones it knows and shows the others as they come.
+ */
+export interface WorkerStatusEvent {
+  /** Order within the worker. Falls back to `at` when absent. */
+  seq?: number | null
+  /** ISO 8601 — when the worker *entered* `to`. */
+  at: string
+  /** `null` for the very first transition (the worker's creation). */
+  from?: string | null
+  /** Lifecycle state entered — same vocabulary as `WorkerCardWorker.state`. */
+  to: string
+  /** Who wrote it: `spawn` | `agent-event` | `reconciliation` | `command` | `setup-monitor` | `boot-recovery` | `node-disconnect`. */
+  source?: string | null
+  /** The why, same shape as `WorkerCardWorker.statusMeta`. */
+  meta?: WorkerCardWorker["statusMeta"]
+}

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

@@ -1,7 +1,7 @@
 "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
+// control panel (setup, resources, repos, ports, tags, actions, history, 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.
 //
@@ -44,10 +44,11 @@ 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 { WorkerCockpitWorker, WorkerCreator, WorkerStatusEvent } from "./types"
 import { type LinkRender } from "./worker-card"
 import { WorkerSetupTimeline } from "./worker-setup-timeline"
 import { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus } from "./worker-status"
+import { WorkerStatusHistory } from "./worker-status-history"
 
 type CockpitTab = "logs" | "terminal"
 
@@ -104,6 +105,12 @@ export interface WorkerCockpitProps {
   /** 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>
 
+  /**
+   * The worker's status transitions, as journaled by the control plane. Omitted or empty → no
+   * History section. The current stay is measured up to `now` at render time.
+   */
+  statusHistory?: WorkerStatusEvent[]
+
   /** A failed mutation, typically. */
   error?: string | null
   onDismissError?: () => void
@@ -180,6 +187,7 @@ export function WorkerCockpit({
   onDelete,
   deleting = false,
   onCopySsh,
+  statusHistory,
   error,
   onDismissError,
   activeTab,
@@ -394,6 +402,13 @@ export function WorkerCockpit({
         </div>
       )}
 
+      {!!statusHistory?.length && (
+        <div>
+          <SectionLabel>History</SectionLabel>
+          <WorkerStatusHistory events={statusHistory} />
+        </div>
+      )}
+
       <div>
         <SectionLabel>Info</SectionLabel>
         <div className="divide-y divide-border/40 rounded-lg border border-border/50 bg-muted/20">

package/src/components/workers/worker-status-history.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import { formatElapsed } from "../../utils"
+import { statusHistorySpans } from "./worker-status-history"
+
+const T0 = Date.parse("2026-09-22T10:00:00Z")
+const at = (ms: number) => new Date(T0 + ms).toISOString()
+
+describe("statusHistorySpans", () => {
+  it("un séjour dure jusqu'à la transition suivante, le dernier jusqu'à now", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), from: null, to: "provisioning", source: "spawn" },
+        { seq: 2, at: at(800), from: "provisioning", to: "building", source: "spawn" },
+        { seq: 3, at: at(660_800), from: "building", to: "ready", source: "agent-event" },
+      ],
+      T0 + 3_600_000
+    )
+    expect(spans.map((s) => s.duration)).toEqual([800, 660_000, 3_600_000 - 660_800])
+    expect(spans.map((s) => s.current)).toEqual([false, false, true])
+  })
+
+  it("remet dans l'ordre un journal qui arrive dans le désordre", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 2, at: at(1000), to: "ready" },
+        { seq: 1, at: at(0), to: "starting" },
+      ],
+      T0 + 2000
+    )
+    expect(spans.map((s) => s.event.to)).toEqual(["starting", "ready"])
+  })
+
+  it("ignore une date illisible et ne produit jamais de durée négative", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: "pas une date", to: "starting" },
+        { seq: 2, at: at(5000), to: "ready" },
+      ],
+      T0 // horloge en retard sur le journal
+    )
+    expect(spans).toHaveLength(1)
+    expect(spans[0].duration).toBe(0)
+  })
+
+  it("ne fait battre que le séjour en cours", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), to: "ready" },
+        { seq: 2, at: at(1000), to: "stopping" },
+        { seq: 3, at: at(2000), to: "stopped" },
+        { seq: 4, at: at(3000), to: "ready" },
+      ],
+      T0 + 4000
+    )
+    expect(spans.map((s) => s.status.running)).toEqual([false, false, false, true])
+  })
+
+  it("dit pourquoi à partir du meta, et retire les points de suspension d'un séjour fini", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), to: "provisioning" },
+        { seq: 2, at: at(1000), to: "starting" },
+        { seq: 3, at: at(2000), to: "exited", meta: { reason: "oom-killed", exitCode: 137, oomKilled: true } },
+      ],
+      T0 + 3000
+    )
+    expect(spans.map((s) => s.label)).toEqual(["Provisioning", "Setting up", "Exited"])
+    expect(spans[2].status.detail).toBe("Ran out of memory (exit 137)")
+  })
+})
+
+describe("formatElapsed", () => {
+  it.each([
+    [800, "800ms"],
+    [40_000, "40s"],
+    [252_000, "4m 12s"],
+    [660_000, "11m"],
+    [11_520_000, "3h 12m"],
+    [7_200_000, "2h"],
+    [59_800, "1m"],
+    [273_600_000, "3d 4h"],
+  ])("%d ms → %s", (ms, out) => {
+    expect(formatElapsed(ms)).toBe(out)
+  })
+})

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

@@ -0,0 +1,166 @@
+"use client"
+
+// The life of a worker, as its status history tells it (RFC 0027, step 8).
+//
+// Two readings of the same journal, stacked:
+//
+// - a **strip** — one segment per stay, width proportional to how long it lasted. It answers
+//   "what did this worker mostly do" at a glance: a strip that is all green is a healthy worker, a
+//   strip with a grey tail is one that died, a strip striped yellow/grey is a node that flaps.
+// - a **list**, newest first — what each stay was, how long it lasted, who wrote it, and why when
+//   the control plane said why ("Ran out of memory (exit 137)"). This is the "why did it die on
+//   Tuesday" answer, without the logs of a container that no longer exists.
+//
+// Durations are *derived*, never sent: a stay lasts until the next transition, and the current one
+// lasts until `now`. Same rule as `SetupWaterfall` ("the next milestone minus this one"), for the
+// whole lifecycle instead of the setup.
+//
+// Colours and labels come from `workerStatusConfig`/`resolveWorkerStatus` — the history does not
+// get its own palette, so a stay in the strip is the colour the pill was while it lasted.
+
+import { useState } from "react"
+import { ChevronDownIcon } from "lucide-react"
+
+import { cn, formatElapsed, formatShortDate } from "../../utils"
+import type { WorkerStatusEvent } from "./types"
+import { WorkerStatusDot, resolveWorkerStatus, type WorkerStatus } from "./worker-status"
+
+/** Who wrote a transition, phrased. An unknown source is shown as sent rather than dropped. */
+const SOURCE_LABELS: Record<string, string> = {
+  spawn: "spawn",
+  "agent-event": "agent",
+  reconciliation: "reconciliation",
+  command: "user action",
+  "setup-monitor": "setup monitor",
+  "boot-recovery": "API restart",
+  "node-disconnect": "node disconnect",
+}
+
+/**
+ * Labels the status table can't give. In a pill, `provisioning` and `starting` both read
+ * "Setting up…" because a pill only says *that* something is in flight; in a history they are two
+ * consecutive rows, and two identical labels in a row read like a duplicate.
+ */
+const HISTORY_LABELS: Record<string, string> = {
+  provisioning: "Provisioning",
+}
+
+export interface WorkerStatusSpan {
+  event: WorkerStatusEvent
+  status: WorkerStatus
+  /** Label for a stay — the pill's, minus the trailing "…" once the stay is over. */
+  label: string
+  start: number
+  end: number
+  duration: number
+  /** The last span: the worker is still in it, and `end` is `now`. */
+  current: boolean
+}
+
+/**
+ * Journal → stays, oldest first. Pure, so the dashboard can derive the same numbers without
+ * drawing anything (a "time to ready" metric, a test).
+ *
+ * Tolerant like the rest of the package: rows are ordered by `seq` then `at` whatever order they
+ * arrive in, a row with an unparsable `at` is skipped rather than producing `NaN` widths, and a
+ * clock that went backwards yields a zero-length stay, not a negative one.
+ */
+export function statusHistorySpans(events: WorkerStatusEvent[], now: number = Date.now()): WorkerStatusSpan[] {
+  const rows = events
+    .map((event) => ({ event, start: Date.parse(event.at) }))
+    .filter((r) => Number.isFinite(r.start))
+    .sort((a, b) => (a.event.seq ?? 0) - (b.event.seq ?? 0) || a.start - b.start)
+
+  return rows.map(({ event, start }, i) => {
+    const current = i === rows.length - 1
+    const end = current ? Math.max(start, now) : rows[i + 1].start
+    const resolved = resolveWorkerStatus({ id: "", state: event.to, statusMeta: event.meta })
+    // Only the stay the worker is *still* in may pulse — a green dot that pings on a row from last
+    // Tuesday would claim a liveness nobody observed.
+    const status = current ? resolved : { ...resolved, running: false }
+    const label = HISTORY_LABELS[event.to] ?? (current ? status.label : status.label.replace(/…$/, ""))
+    return { event, status, label, start, end, duration: Math.max(0, end - start), current }
+  })
+}
+
+export interface WorkerStatusHistoryProps {
+  /** The journal, in any order. Empty → nothing is drawn. */
+  events: WorkerStatusEvent[]
+  /** Where the current stay ends. The component doesn't tick: the app re-renders on its poll. */
+  now?: number | Date
+  /** Rows shown before "Show N earlier". The strip always covers everything. */
+  limit?: number
+  className?: string
+}
+
+export function WorkerStatusHistory({ events, now, limit = 5, className }: WorkerStatusHistoryProps) {
+  const [expanded, setExpanded] = useState(false)
+  const nowMs = now instanceof Date ? now.getTime() : (now ?? Date.now())
+  const spans = statusHistorySpans(events, nowMs)
+  if (!spans.length) return null
+
+  const total = spans.reduce((sum, s) => sum + s.duration, 0)
+  const newestFirst = [...spans].reverse()
+  const hidden = expanded ? 0 : Math.max(0, newestFirst.length - limit)
+  const rows = hidden ? newestFirst.slice(0, limit) : newestFirst
+
+  return (
+    <div data-slot="worker-status-history" className={cn("rounded-lg border border-border/40 bg-muted/20 text-xs", className)}>
+      <div className="space-y-1.5 border-b border-border/40 px-3 py-2.5">
+        <div className="flex items-center justify-between">
+          <span className="font-mono text-[11px] font-medium text-muted-foreground">
+            {spans.length} {spans.length === 1 ? "state" : "states"}
+          </span>
+          <span className="font-mono text-[11px] tabular-nums text-foreground/80">{formatElapsed(total)}</span>
+        </div>
+        {/* flex-grow by duration, with a floor: a 0.8 s provisioning next to three days of Running
+            must still be a visible notch, or the strip would lie about what happened. */}
+        <div className="flex h-2.5 gap-px overflow-hidden rounded-sm" role="img" aria-label="Time spent in each state">
+          {spans.map((s, i) => (
+            <span
+              key={i}
+              className={cn("min-w-[3px] basis-0", s.status.dotClass)}
+              style={{ flexGrow: total > 0 ? s.duration : 1 }}
+              title={`${s.label}: ${formatElapsed(s.duration)}`}
+            />
+          ))}
+        </div>
+      </div>
+
+      <ol className="px-3 py-2.5">
+        {rows.map((s, i) => {
+          const source = s.event.source ? (SOURCE_LABELS[s.event.source] ?? s.event.source) : null
+          const last = i === rows.length - 1 && !hidden
+          return (
+            <li key={`${s.event.seq ?? ""}-${s.event.at}`} className="relative pb-2.5 pl-4 last:pb-0">
+              {/* The thread between two dots. Absent under the oldest row shown: nothing before it. */}
+              {!last && <span aria-hidden className="absolute top-3 bottom-0 left-[3px] w-px bg-border" />}
+              <WorkerStatusDot status={s.status} className="absolute top-[5px] left-0" />
+              <div className="flex items-baseline justify-between gap-2">
+                <span className={cn("truncate font-medium", s.current ? "text-foreground" : "text-foreground/80")}>{s.label}</span>
+                <span className="shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground/80">{formatElapsed(s.duration)}</span>
+              </div>
+              {s.status.detail && <p className="mt-0.5 text-[11px] leading-snug text-foreground/70">{s.status.detail}</p>}
+              <p className="mt-0.5 truncate text-[10px] text-muted-foreground/60">
+                {s.current ? "since " : ""}
+                {formatShortDate(s.start, { time: true })}
+                {source && <> · {source}</>}
+              </p>
+            </li>
+          )
+        })}
+      </ol>
+
+      {hidden > 0 && (
+        <button
+          type="button"
+          onClick={() => setExpanded(true)}
+          className="flex w-full cursor-pointer items-center justify-center gap-1 border-t border-border/40 py-1.5 text-[11px] text-muted-foreground transition-colors hover:text-foreground"
+        >
+          <ChevronDownIcon className="h-3 w-3" />
+          Show {hidden} earlier
+        </button>
+      )}
+    </div>
+  )
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 // @spunto/design-system — shared UI primitives, helpers, and color constants.
 // Tokens ship as a CSS file: `import "@spunto/design-system/styles.css"`.
 
-export { cn, formatDuration, formatRelativeTime } from "./utils"
+export { cn, formatDuration, formatElapsed, formatRelativeTime } from "./utils"
 export * from "./colors"
 
 // Domain (Spunto-specific) components live behind their own entry point —

package/src/utils.ts

@@ -50,3 +50,26 @@ 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`
 }
+
+/**
+ * A span that may last days: "40s", "4m 12s", "11m", "3h 12m", "3d 4h".
+ *
+ * `formatDuration` is for a setup phase and stops at seconds ("11520s"); this one is for how long
+ * a worker *stayed* somewhere, where the range is a second to a week. Two units at most, and the
+ * second is dropped once it stops carrying information (the seconds of an 11-minute build).
+ */
+export function formatElapsed(ms: number): string {
+  if (ms < 10_000) return formatDuration(ms)
+  // Rounded once, to the second, before splitting: 59.8 s is "1m", not "0m 59s" nor "60s".
+  const totalSeconds = Math.round(ms / 1000)
+  if (totalSeconds < 60) return `${totalSeconds}s`
+  const minutes = Math.floor(totalSeconds / 60)
+  if (minutes < 60) {
+    const seconds = totalSeconds % 60
+    return minutes < 10 && seconds ? `${minutes}m ${seconds}s` : `${minutes}m`
+  }
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`
+  const days = Math.floor(hours / 24)
+  return hours % 24 ? `${days}d ${hours % 24}h` : `${days}d`
+}