@spunto/design-system 0.25.0 → 0.27.0

package/README.md

@@ -470,6 +470,34 @@ it, the navs and footers (they hard-code URLs and a session), the product logos
 and OG cards. The rule: *if it needs to know a product, a URL or a session, it's
 the site; if it only lays out or types, it's the system.*
 
+## Brand — `/brand`
+
+The Spunto logo, behind its own entry: the one sub-export that knows Spunto by
+construction, kept out of the root so a third-party consumer of the primitives
+never ships the company's mark.
+
+```tsx
+import { SpuntoLogo } from "@spunto/design-system/brand"
+
+<SpuntoLogo />                                   // the brand: flame tile, night ink
+<SpuntoLogo variant="mark" tone="night" />       // S + dot only, what survives 16 px
+<SpuntoLogo tone="ink" className="text-primary" /> // no tile, currentColor
+```
+
+The drawing is a 7 × 7 grid — blocks of 10 on a pitch of 14 — and it tells the
+product: the dot is your container, the two brackets are an S with the dot for
+its middle stroke, three blocks on the left are Build, three lights on the right
+are Run, the belt along the bottom is Ship, three squares on top are the
+machines you already own. `tone` picks a declension (`flame`, `build`,
+`ship`, `run`, `night`, `cream`, `pillars`, `ink`); `paint` overrides
+any role on top of it.
+
+The geometry lives as data in `src/brand/logo.ts`, React-free, so the same
+shapes come out as an element (`SpuntoLogo`) and as a file
+(`spuntoLogoSvg()`). `npm run brand:export -- <dir>` writes one `.svg` per
+declension — favicon, per-product tiles — which is how a site gets its static
+copies without ever hand-editing an SVG.
+
 ## Toasts — `SpuntoProvider` + `toast()`
 
 `SpuntoProvider` is the design system's client umbrella provider. Mount it once

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -49,6 +49,10 @@
       "types": "./src/components/marketing/index.ts",
       "import": "./src/components/marketing/index.ts"
     },
+    "./brand": {
+      "types": "./src/brand/index.ts",
+      "import": "./src/brand/index.ts"
+    },
     "./fonts": {
       "types": "./src/components/fonts.tsx",
       "import": "./src/components/fonts.tsx"
@@ -62,7 +66,8 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "brand:export": "node scripts/export-logo.ts"
   },
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",

package/src/brand/index.ts

@@ -0,0 +1,31 @@
+// @spunto/design-system/brand — the Spunto logo.
+//
+// Behind its own entry, like every domain sub-export: a `Button` knows nothing
+// about Spunto, and a third-party consumer of the primitives should not carry
+// the company's mark in their bundle. Here it *is* the point: the same drawing
+// for the console, for Spunto Lite, for the showcase, each in its own tone.
+//
+// `SpuntoLogo` is the React element. `spuntoLogoSvg` is the same drawing as a
+// static document — `scripts/export-logo.ts` uses it to write the favicon and
+// the per-product tiles a site serves as files.
+
+export { SpuntoLogo } from "./spunto-logo"
+export type { SpuntoLogoProps } from "./spunto-logo"
+
+export {
+  SPUNTO_LOGO_TONES,
+  SPUNTO_LOGO_VIEWBOX,
+  SPUNTO_LOGO_TILE_RADIUS,
+  spuntoLogoSvg,
+  spuntoLogoShapes,
+  spuntoLogoTile,
+  spuntoLogoFill,
+} from "./logo"
+export type {
+  SpuntoLogoPaint,
+  SpuntoLogoTone,
+  SpuntoLogoVariant,
+  SpuntoLogoRole,
+  SpuntoLogoShape,
+  SpuntoLogoSvgOptions,
+} from "./logo"

package/src/brand/logo.test.tsx

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest"
+import { renderToStaticMarkup } from "react-dom/server"
+
+import { SPUNTO_LOGO_TONES, spuntoLogoShapes, spuntoLogoSvg } from "./logo"
+import { SpuntoLogo } from "./spunto-logo"
+
+// The whole point of `logo.ts` being data is that the element and the file are
+// the same drawing. These pin that: same shapes, same fills, in the same order.
+// (React closes SVG elements with a tag, the file self-closes them — hence `/?>`.)
+const attrs = (svg: string) =>
+  [...svg.matchAll(/<(rect|circle|path)\b([^>]*?)\/?>/g)].map(([, tag, a]) => {
+    const kv = Object.fromEntries([...a.matchAll(/(\w+)="([^"]*)"/g)].map(([, k, v]) => [k, v]))
+    return { tag, ...kv }
+  })
+
+describe("SpuntoLogo", () => {
+  it("draws exactly what spuntoLogoSvg writes, for every tone", () => {
+    for (const tone of Object.keys(SPUNTO_LOGO_TONES) as Array<keyof typeof SPUNTO_LOGO_TONES>) {
+      const paint = SPUNTO_LOGO_TONES[tone]
+      expect(attrs(renderToStaticMarkup(<SpuntoLogo tone={tone} />))).toEqual(attrs(spuntoLogoSvg(paint)))
+      expect(attrs(renderToStaticMarkup(<SpuntoLogo tone={tone} variant="mark" />))).toEqual(
+        attrs(spuntoLogoSvg(paint, { variant: "mark" })),
+      )
+    }
+  })
+
+  it("has no tile and takes currentColor in the ink tone", () => {
+    const svg = renderToStaticMarkup(<SpuntoLogo tone="ink" />)
+    expect(svg).not.toContain('width="128"')
+    expect(svg.match(/fill="currentColor"/g)).toHaveLength(spuntoLogoShapes("glyph").length)
+  })
+
+  it("lets paint override a single role of a tone", () => {
+    const svg = renderToStaticMarkup(<SpuntoLogo tone="flame" paint={{ tile: "#be241f" }} />)
+    expect(svg).toContain('fill="#be241f"')
+    expect(svg).not.toContain('fill="#ec5100"')
+    expect(svg).toContain('fill="#0e0805"')
+  })
+
+  it("is hidden from assistive tech unless it is given a name", () => {
+    expect(renderToStaticMarkup(<SpuntoLogo />)).toContain('aria-hidden="true"')
+    const named = renderToStaticMarkup(<SpuntoLogo title="Spunto — home" />)
+    expect(named).toContain('role="img"')
+    expect(named).toContain("<title>Spunto — home</title>")
+  })
+
+  it("keeps the mark to the S and the dot, and the glyph to the full story", () => {
+    // 2 brackets + 1 dot; then 3 fleet + 3 build + 3 run + 4 ship.
+    expect(spuntoLogoShapes("mark")).toHaveLength(3)
+    expect(spuntoLogoShapes("glyph")).toHaveLength(3 + 3 + 3 + 3 + 4)
+  })
+})

package/src/brand/logo.ts

@@ -0,0 +1,238 @@
+// The Spunto logo, as data.
+//
+// This module is deliberately **pure**: no React, no DOM, no colour maths. It
+// describes the mark once — a list of shapes on a grid, and the named paints
+// that go on them — so that the same drawing can be emitted as a React element
+// (`SpuntoLogo`) and as a static `.svg` file (`spuntoLogoSvg`, used by
+// `scripts/export-logo.ts` to write the favicon and the per-product tiles). One
+// source, two outputs, nothing to keep in sync by eye.
+//
+// ─── The drawing ───────────────────────────────────────────────────────────
+//
+// A 7 × 7 grid: blocks of 10 on a pitch of 14, inset 17 from the edge of a
+// 128 × 128 tile. Everything snaps to it — the bars are blocks fused together,
+// the lights are blocks turned round. That grid is what the logo inherited
+// from its predecessor, and what keeps it in the family of the design system's
+// quasi-square 4 px radius: nothing here is drawn freehand.
+//
+// What it says, read from the centre outwards:
+//
+//   • the dot          — your container. The one thing the platform is about.
+//   • the two brackets — an S (for Spunto) whose middle stroke *is* the dot:
+//                        two L-shapes 180° apart, wrapping the container the
+//                        way the platform wraps a workspace.
+//   • three blocks, left  — Build. Layers stacked; an image being made.
+//   • three lights, right — Run. Round because they're alive: status lights.
+//   • the belt, bottom    — Ship. Square, round, square, round: what leaves
+//                           the build side and comes out running.
+//   • three squares, top  — the fleet. The machines you already own, the
+//                           roof everything else sits under.
+//
+// Each of those is a `role`, so a paint can colour the story (the `pillars`
+// tone lights Build / Ship / Run in their own tokens) or flatten it to one ink.
+
+export const SPUNTO_LOGO_VIEWBOX = 128
+
+/** Corner radius of the tile, in viewBox units — quasi-square, like the system. */
+export const SPUNTO_LOGO_TILE_RADIUS = 14
+
+/** Every part of the drawing that can be painted independently. */
+export type SpuntoLogoRole = "tile" | "core" | "build" | "run" | "ship" | "fleet"
+
+export type SpuntoLogoShape =
+  | { role: SpuntoLogoRole; kind: "rect"; x: number; y: number; w: number; h: number; rx?: number }
+  | { role: SpuntoLogoRole; kind: "circle"; cx: number; cy: number; r: number }
+  | { role: SpuntoLogoRole; kind: "path"; d: string }
+
+/**
+ * `glyph` is the whole story — the S, the container and its three pillars.
+ * `mark` is the S and the container alone, drawn larger: what survives at
+ * 16 px, so it is the favicon and the collapsed-sidebar icon.
+ */
+export type SpuntoLogoVariant = "glyph" | "mark"
+
+const PITCH = 14
+const BLOCK = 10
+const INSET = 17
+const CENTRE = SPUNTO_LOGO_VIEWBOX / 2
+
+/** Grid column/row `i` (0–6) → its top-left coordinate. */
+const at = (i: number) => INSET + PITCH * i
+
+const square = (role: SpuntoLogoRole, col: number, row: number): SpuntoLogoShape => ({
+  role,
+  kind: "rect",
+  x: at(col),
+  y: at(row),
+  w: BLOCK,
+  h: BLOCK,
+})
+
+const light = (role: SpuntoLogoRole, col: number, row: number): SpuntoLogoShape => ({
+  role,
+  kind: "circle",
+  cx: at(col) + BLOCK / 2,
+  cy: at(row) + BLOCK / 2,
+  r: BLOCK / 2,
+})
+
+/* The two brackets and the dot, in both sizes. Coordinates are spelled out
+   rather than computed so the paths read as what they are: an L, its 180°
+   twin, and the space between them. In the glyph the brackets are one block
+   thick, like every other bar on the grid; in the mark they are 14 — the
+   pitch — because at favicon size a 10-unit bar is a single blurred pixel. */
+const CORE = {
+  glyph: [
+    { role: "core", kind: "path", d: "M31 31h52v10H41v42H31z" }, // Γ — top bar, left stem
+    { role: "core", kind: "path", d: "M97 97H45V87h42V45h10z" }, // ⅃ — bottom bar, right stem
+    { role: "core", kind: "circle", cx: CENTRE, cy: CENTRE, r: 13 },
+  ],
+  mark: [
+    { role: "core", kind: "path", d: "M18 18h72v14H32v58H18z" },
+    { role: "core", kind: "path", d: "M110 110H38V96h58V38h14z" },
+    { role: "core", kind: "circle", cx: CENTRE, cy: CENTRE, r: 18 },
+  ],
+} satisfies Record<SpuntoLogoVariant, SpuntoLogoShape[]>
+
+const PILLARS: SpuntoLogoShape[] = [
+  // the fleet, on top
+  square("fleet", 2, 0),
+  square("fleet", 3, 0),
+  square("fleet", 4, 0),
+  // Build — blocks stacked on the left
+  square("build", 0, 2),
+  square("build", 0, 3),
+  square("build", 0, 4),
+  // Run — lights on the right
+  light("run", 6, 2),
+  light("run", 6, 3),
+  light("run", 6, 4),
+  // Ship — the belt along the bottom, build-side square to run-side round
+  square("ship", 1, 6),
+  light("ship", 2, 6),
+  square("ship", 3, 6),
+  light("ship", 4, 6),
+]
+
+/**
+ * The shapes of a variant, tile excluded (the tile is a paint decision, see
+ * `spuntoLogoTile`). Order is paint order.
+ */
+export function spuntoLogoShapes(variant: SpuntoLogoVariant = "glyph"): SpuntoLogoShape[] {
+  return variant === "mark" ? [...CORE.mark] : [...CORE.glyph, ...PILLARS]
+}
+
+/** The tile behind the drawing, when a paint asks for one. */
+export function spuntoLogoTile(): SpuntoLogoShape {
+  return {
+    role: "tile",
+    kind: "rect",
+    x: 0,
+    y: 0,
+    w: SPUNTO_LOGO_VIEWBOX,
+    h: SPUNTO_LOGO_VIEWBOX,
+    rx: SPUNTO_LOGO_TILE_RADIUS,
+  }
+}
+
+// ─── Paint ─────────────────────────────────────────────────────────────────
+
+/**
+ * What colour goes on what. `ink` is the fallback for every drawn role; a
+ * role named explicitly overrides it. No `tile` means a transparent
+ * background — the drawing alone, for a nav bar or a print.
+ */
+export interface SpuntoLogoPaint {
+  tile?: string
+  ink: string
+  core?: string
+  build?: string
+  run?: string
+  ship?: string
+  fleet?: string
+}
+
+/**
+ * The declensions. Each is a design-system token turned into a fixed value:
+ * a logo is an artefact, not a surface, so it does not follow the theme — the
+ * flame tile is the same flame at night. The values are the light-theme
+ * register of `styles.css` (`--flame`, `--build`, `--ship`, `--run`,
+ * `--night`, `--background`) and the sand the marketing pages use for ink on
+ * night, converted out of oklch.
+ *
+ * The idea is one tone per product: Spunto Cloud is the brand and wears
+ * `flame`; a product whose marketing accent is `build` wears `build`; the
+ * design system, whose accent is ink, wears `night`. `pillars` is the same
+ * drawing with its story lit — Build, Ship and Run each in their own token —
+ * for a hero or a social card, not for a 24 px header.
+ */
+export const SPUNTO_LOGO_TONES = {
+  /** The brand: flame tile, night ink. */
+  flame: { tile: "#ec5100", ink: "#0e0805" },
+  /** `--build` tile — amber. */
+  build: { tile: "#f9a733", ink: "#0e0805" },
+  /** `--ship` tile — orange. */
+  ship: { tile: "#fb7c01", ink: "#0e0805" },
+  /** `--run` tile — one step short of flame. */
+  run: { tile: "#f35800", ink: "#0e0805" },
+  /** `--night` tile, sand ink — what the design system itself wears. */
+  night: { tile: "#0e0805", ink: "#e0d3bb" },
+  /** Cream tile, night ink, the container lit in flame — for a light print. */
+  cream: { tile: "#fbf6ee", ink: "#0e0805", core: "#ec5100" },
+  /** Night, with the three pillars in their own tokens (night register). */
+  pillars: {
+    tile: "#0e0805",
+    ink: "#fbf6ee",
+    fleet: "#8b837d",
+    build: "#ffb649",
+    ship: "#ff8b27",
+    run: "#ff6917",
+  },
+} as const satisfies Record<string, SpuntoLogoPaint>
+
+export type SpuntoLogoTone = keyof typeof SPUNTO_LOGO_TONES
+
+/** The colour a role takes under a paint. `tile` returns `undefined` when there is none. */
+export function spuntoLogoFill(paint: SpuntoLogoPaint, role: SpuntoLogoRole): string | undefined {
+  if (role === "tile") return paint.tile
+  return paint[role] ?? paint.ink
+}
+
+// ─── Static SVG ────────────────────────────────────────────────────────────
+
+export interface SpuntoLogoSvgOptions {
+  variant?: SpuntoLogoVariant
+  /** `<title>` for the file; omitted, the SVG carries `aria-hidden`. */
+  title?: string
+}
+
+function shapeToSvg(shape: SpuntoLogoShape, fill: string): string {
+  switch (shape.kind) {
+    case "rect": {
+      const rx = shape.rx ? ` rx="${shape.rx}"` : ""
+      return `<rect x="${shape.x}" y="${shape.y}" width="${shape.w}" height="${shape.h}"${rx} fill="${fill}"/>`
+    }
+    case "circle":
+      return `<circle cx="${shape.cx}" cy="${shape.cy}" r="${shape.r}" fill="${fill}"/>`
+    case "path":
+      return `<path d="${shape.d}" fill="${fill}"/>`
+  }
+}
+
+/**
+ * The logo as a standalone SVG document — what goes on disk as a favicon, an
+ * `<img src>`, an `og:image` source. Same shapes, same paints as the React
+ * component; only the serialisation differs.
+ */
+export function spuntoLogoSvg(paint: SpuntoLogoPaint, options: SpuntoLogoSvgOptions = {}): string {
+  const { variant = "glyph", title } = options
+  const shapes = paint.tile ? [spuntoLogoTile(), ...spuntoLogoShapes(variant)] : spuntoLogoShapes(variant)
+  const body = shapes
+    .map((s) => shapeToSvg(s, spuntoLogoFill(paint, s.role) ?? paint.ink))
+    .map((line) => `  ${line}`)
+    .join("\n")
+  const head = title
+    ? `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SPUNTO_LOGO_VIEWBOX} ${SPUNTO_LOGO_VIEWBOX}" role="img" aria-labelledby="t">\n  <title id="t">${title}</title>`
+    : `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SPUNTO_LOGO_VIEWBOX} ${SPUNTO_LOGO_VIEWBOX}" aria-hidden="true">`
+  return `${head}\n${body}\n</svg>\n`
+}

package/src/brand/spunto-logo.tsx

@@ -0,0 +1,90 @@
+import type { SVGProps } from "react"
+
+import { cn } from "../utils"
+import {
+  SPUNTO_LOGO_TONES,
+  SPUNTO_LOGO_VIEWBOX,
+  spuntoLogoFill,
+  spuntoLogoShapes,
+  spuntoLogoTile,
+  type SpuntoLogoPaint,
+  type SpuntoLogoShape,
+  type SpuntoLogoTone,
+  type SpuntoLogoVariant,
+} from "./logo"
+
+/* ─── SpuntoLogo ────────────────────────────────────────────────────────────
+   The logo as a React element. Two axes:
+
+   `variant` — `glyph` (the whole story, from 24 px up) or `mark` (the S and
+   the container alone, for 16 px and collapsed sidebars).
+
+   `tone` — which declension. The seven named ones are fixed paints built
+   from the tokens (see `SPUNTO_LOGO_TONES`); `ink` is the odd one out: no
+   tile, and the drawing takes `currentColor`, so it follows the text colour
+   it sits in — the right choice for a header on a themed surface, where a
+   fixed flame tile would fight the page.
+
+   `paint` overrides any tone field by field. A product whose accent is not a
+   design-system token (the site's marketing `rust`, say) passes its own tile
+   here rather than getting a tone the package would then have to own. */
+
+export interface SpuntoLogoProps extends Omit<SVGProps<SVGSVGElement>, "children" | "viewBox"> {
+  variant?: SpuntoLogoVariant
+  /** @default "flame" */
+  tone?: SpuntoLogoTone | "ink"
+  /** Per-role overrides on top of the tone. */
+  paint?: Partial<SpuntoLogoPaint>
+  /** Width and height, in px. Leave it out to size with `className`. */
+  size?: number
+  /**
+   * Accessible name. Give one when the logo is the only content of a link
+   * ("Spunto — home"); leave it out when a wordmark sits next to it, and the
+   * SVG is hidden from assistive tech.
+   */
+  title?: string
+}
+
+const INK: SpuntoLogoPaint = { ink: "currentColor" }
+
+function Shape({ shape, fill }: { shape: SpuntoLogoShape; fill: string }) {
+  switch (shape.kind) {
+    case "rect":
+      return <rect x={shape.x} y={shape.y} width={shape.w} height={shape.h} rx={shape.rx} fill={fill} />
+    case "circle":
+      return <circle cx={shape.cx} cy={shape.cy} r={shape.r} fill={fill} />
+    case "path":
+      return <path d={shape.d} fill={fill} />
+  }
+}
+
+export function SpuntoLogo({
+  variant = "glyph",
+  tone = "flame",
+  paint: overrides,
+  size,
+  title,
+  className,
+  ...rest
+}: SpuntoLogoProps) {
+  const base: SpuntoLogoPaint = tone === "ink" ? INK : SPUNTO_LOGO_TONES[tone]
+  const paint: SpuntoLogoPaint = { ...base, ...overrides }
+  const shapes = paint.tile ? [spuntoLogoTile(), ...spuntoLogoShapes(variant)] : spuntoLogoShapes(variant)
+
+  return (
+    <svg
+      viewBox={`0 0 ${SPUNTO_LOGO_VIEWBOX} ${SPUNTO_LOGO_VIEWBOX}`}
+      width={size}
+      height={size}
+      className={cn("shrink-0", className)}
+      role={title ? "img" : undefined}
+      aria-hidden={title ? undefined : true}
+      {...rest}
+    >
+      {title && <title>{title}</title>}
+      {shapes.map((shape, i) => (
+        <Shape key={i} shape={shape} fill={spuntoLogoFill(paint, shape.role) ?? paint.ink} />
+      ))}
+    </svg>
+  )
+}

package/src/components/workers/types.ts

@@ -26,8 +26,23 @@ export interface WorkerCardWorker {
   name?: string | null
   /** Fallback identity when `name` is empty — renders as "Workspace #3". */
   index?: number | null
-  /** Lifecycle state: `provisioning` | `building` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `error`. */
+  /** Lifecycle state: `provisioning` | `building` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `exited` | `unknown` | `error`. */
   state?: string | null
+  /**
+   * Why the worker is in that state, when there is a why: an exit code, a reason, and the status
+   * it came from. Read laxly on purpose — every field optional, an unrecognised `reason` yields no
+   * detail instead of an invented one. The strict version of this shape lives in
+   * `@spunto/build` (`WorkerStatusMeta`), which is where a control plane *writing* it should look.
+   */
+  statusMeta?: {
+    reason?: string | null
+    message?: string | null
+    exitCode?: number | null
+    oomKilled?: boolean | null
+    /** What the worker was before it became `unknown` — the buttons to offer depend on it. */
+    previousStatus?: string | null
+    at?: string | null
+  } | null
   /** Docker-level state: `running` | `stopped` | `exited` | `created` | `not_found` | `error`. */
   dockerState?: string | null
   createdAt?: string | null

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

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest"
+import { resolveWorkerStatus, workerStatusConfig } from "./worker-status"
+
+describe("resolveWorkerStatus — le node injoignable", () => {
+  it("ne prétend rien, et ne prétend surtout pas qu'un setup est en cours", () => {
+    const status = resolveWorkerStatus({ id: "w", state: "unknown" })
+    expect(status.key).toBe("unknown")
+    expect(status.label).toBe("Unknown")
+    expect(status.settingUp).toBe(false)
+    expect(status.running).toBe(false)
+  })
+
+  it("prime sur un dockerState périmé", () => {
+    // Le cas réel : le dernier `inspect` réussi disait « running », puis le node est parti. La
+    // pastille doit dire qu'on ne sait pas, pas répéter une observation qu'on ne peut plus refaire.
+    const status = resolveWorkerStatus({ id: "w", state: "unknown", dockerState: "running" })
+    expect(status.key).toBe("unknown")
+  })
+
+  it("dit pourquoi, quand le plan de contrôle l'a dit", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "unknown",
+      statusMeta: { reason: "node-disconnected", previousStatus: "ready" },
+    })
+    expect(status.detail).toBe("The node is unreachable")
+  })
+})
+
+describe("resolveWorkerStatus — le conteneur mort tout seul", () => {
+  it("se résout sans dockerState, pour un produit qui n'a qu'un champ", () => {
+    // Spunto Lite n'a pas de second axe : avant, `exited` n'était atteignable que par la branche
+    // docker et un worker mort retombait sur le repli `pending`.
+    const status = resolveWorkerStatus({ id: "w", state: "exited" })
+    expect(status.key).toBe("exited")
+    expect(status.label).toBe("Exited")
+    expect(status.running).toBe(false)
+  })
+
+  it("porte le code de sortie quand il y en a un", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "oom-killed", exitCode: 137 },
+    })
+    expect(status.detail).toBe("Ran out of memory (exit 137)")
+  })
+
+  it("garde un code de sortie nul, qui est une valeur et pas une absence", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "completed", exitCode: 0 },
+    })
+    expect(status.detail).toBe("The container finished and exited cleanly (exit 0)")
+  })
+
+  it("préfère toujours le message du plan de contrôle à sa propre formulation", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "oom-killed", message: "Killed while compiling the kernel" },
+    })
+    expect(status.detail).toBe("Killed while compiling the kernel")
+  })
+})
+
+describe("resolveWorkerStatus — la tolérance qui fait vivre la table", () => {
+  it("n'invente pas de détail pour une raison qu'elle ne connaît pas", () => {
+    const status = resolveWorkerStatus({ id: "w", state: "ready", statusMeta: { reason: "sonar-storm" } })
+    expect(status.detail).toBeUndefined()
+    expect(status.key).toBe("running")
+  })
+
+  it("laisse les statuts connus intacts", () => {
+    expect(resolveWorkerStatus({ id: "w", state: "building" }).settingUp).toBe(true)
+    expect(resolveWorkerStatus({ id: "w", state: "ready", dockerState: "running" }).key).toBe("running")
+    expect(resolveWorkerStatus({ id: "w", state: "wat" }).key).toBe("pending")
+  })
+
+  it("donne une pastille à chaque clé, sans exception", () => {
+    for (const [key, config] of Object.entries(workerStatusConfig)) {
+      expect(config.label, `"${key}" has no label`).toBeTruthy()
+      expect(config.dotClass, `"${key}" has no dot`).toBeTruthy()
+    }
+  })
+})

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

@@ -6,13 +6,18 @@
 // 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.
 //
-// `building` is the odd one out: it is the state a *control plane* reports, and
-// the only one here that Spunto Lite names and the dashboard does not. Both wait
-// for a project image before a container exists — Cloud does it inside
-// `provisioning` and rebuilds the fact client-side by joining the project's image
-// builds, Lite says it in the field. It is deliberately not folded into
-// `pulling`: building an image and pulling one are different waits, and only one
-// of them has a log worth opening.
+// Three keys here are *control plane* states rather than docker ones, and they
+// are the reason this table is not just a mapping of `docker inspect`:
+//
+// - `building` — waiting for the project image, before any container exists. Not
+//   folded into `pulling`: building an image and pulling one are different waits,
+//   and only one of them has a log worth opening.
+// - `exited` — the container died without being asked to. It already existed as a
+//   *docker* state; it is now also a lifecycle one, so a product with a single
+//   `state` field resolves it without falling through to the fallback.
+// - `unknown` — the node is unreachable, so we do not know. It claims nothing on
+//   purpose: showing the last known status as though it were current is the lie
+//   this key exists to avoid. `statusMeta.previousStatus` keeps what it was.
 //
 // No "use client": pure functions and hookless components, so a React Server
 // Component can call them.
@@ -30,6 +35,7 @@ export type WorkerStatusKey =
   | "pending"
   | "setup"
   | "building"
+  | "unknown"
   | "pulling"
   | "stopping"
   | "deleting"
@@ -89,6 +95,9 @@ export const workerStatusConfig: Record<WorkerStatusKey, WorkerStatusConfig> = {
   pending: BUSY,
   setup: { ...BUSY, label: "Setting up…" },
   building: { ...BUSY, label: "Building image…" },
+  // Volontairement neutre : ni jaune (rien n'est en cours, on ne sait pas), ni rouge
+  // (rien n'a échoué). C'est l'absence d'information, et elle a le droit de se voir.
+  unknown: { ...IDLE, label: "Unknown" },
   pulling: { ...BUSY, label: "Pulling image…" },
   stopping: { ...BUSY, label: "Stopping…" },
   deleting: { ...BUSY, label: "Deleting…" },
@@ -100,16 +109,51 @@ export interface WorkerStatus extends WorkerStatusConfig {
   settingUp: boolean
   /** Container up and past its setup — stats, git chips and the pulsing dot apply. */
   running: boolean
+  /**
+   * One sentence for what `statusMeta` carries — "Container ran out of memory", "was ready" —
+   * or `undefined` when there is nothing to add. The pill says *what*; this says *why*, and a
+   * consumer renders it beside the pill or not at all.
+   */
+  detail?: string
 }
 
 /** Lifecycle states that mean "not usable yet, a setup is in flight". */
 const SETUP_STATES = new Set(["provisioning", "starting", "setup"])
 
+/**
+ * Fallback phrasing per reason, used only when the control plane sent no `message`.
+ *
+ * Deliberately short and deliberately incomplete: a reason this table has never heard of yields
+ * no detail rather than an invented one — same rule as the status table itself.
+ */
+const REASON_PHRASES: Record<string, string> = {
+  "oom-killed": "Ran out of memory",
+  exited: "The container exited on its own",
+  completed: "The container finished and exited cleanly",
+  "removed-externally": "The container is gone from the node",
+  "setup-failed": "Setup failed inside the container",
+  "build-failed": "The project image could not be built",
+  "spawn-orphaned": "Startup was interrupted and cannot resume",
+  "node-lost": "The node disconnected before the container existed",
+  "node-disconnected": "The node is unreachable",
+}
+
+/** What `statusMeta` has to say, if anything: the message it carried, else its reason. */
+function detailOf(meta: WorkerCardWorker["statusMeta"]): string | undefined {
+  if (!meta) return undefined
+  if (meta.message) return meta.message
+  const phrase = meta.reason ? REASON_PHRASES[meta.reason] : undefined
+  if (!phrase) return undefined
+  // `exitCode` is worth showing when it is there — `0` included, which is why this is not `||`.
+  return meta.exitCode != null ? `${phrase} (exit ${meta.exitCode})` : phrase
+}
+
 /**
  * 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, building, pulling, setting up), because docker still reports
+ * flight or already settled (deleting, stopping, unknown, exited, building, 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
@@ -120,16 +164,24 @@ export function resolveWorkerStatus(worker: WorkerCardWorker): WorkerStatus {
   const state = worker.state ?? null
   const docker = worker.dockerState ?? null
 
+  const detail = detailOf(worker.statusMeta)
   const of = (key: WorkerStatusKey, flags?: Partial<Pick<WorkerStatus, "settingUp" | "running">>): WorkerStatus => ({
     key,
     ...workerStatusConfig[key],
     settingUp: false,
     running: key === "running",
+    ...(detail ? { detail } : {}),
     ...flags,
   })
 
   if (state === "deleting") return of("deleting")
   if (state === "stopping") return of("stopping")
+  // Le node est injoignable : on ne sait pas. Surtout pas `settingUp` — annoncer une progression
+  // pour une machine qu'on ne voit plus est exactement ce que ce statut existe pour éviter.
+  if (state === "unknown") return of("unknown")
+  // Mort tout seul. Le statut de cycle de vie prime sur `dockerState`, qui dirait la même chose
+  // quand il est là — et ne dirait rien du tout chez un produit qui n'a qu'un champ.
+  if (state === "exited") return of("exited")
   if (state === "building") return of("building", { settingUp: true })
   if (state === "pulling") return of("pulling", { settingUp: true })
   if (state && SETUP_STATES.has(state)) return of("setup", { settingUp: true })