@spunto/design-system 0.7.2 → 0.9.0

package/src/components/image-pull.tsx

@@ -0,0 +1,642 @@
+"use client"
+
+import { useEffect, useMemo, useRef, useState } from "react"
+
+import { cn } from "../utils"
+
+// Same surface as `Terminal` (#09090b) and the same ANSI accent hues, so an
+// ImagePull dropped right above a Terminal reads as *one* object — a build view
+// becomes two stacked bricks rather than two unrelated widgets.
+const pullTheme = {
+  background: "#09090b",
+  border: "#27272a",
+  /** Unfilled part of a segment / of a layer's thin bar. */
+  track: "#1f1f23",
+  text: "#e4e4e7",
+  dim: "#a1a1aa",
+  faint: "#71717a",
+  /** Tag of the image reference — the part that actually varies, so it's the bright one. */
+  tag: "#fdba74",
+  // Phase colors. Flame is the brand accent and downloading is the main event;
+  // yellow/green/red come straight from the Terminal's shared ANSI palette so
+  // both surfaces agree on what "in progress" / "done" / "failed" look like.
+  waiting: "#3f3f46",
+  downloading: "#ea5400",
+  verifying: "#fb923c",
+  extracting: "#facc15",
+  done: "#4ade80",
+  error: "#f87171",
+} as const
+
+export type PullLayerStatus = "waiting" | "downloading" | "verifying" | "extracting" | "done"
+
+export interface PullLayer {
+  /** Docker layer id (full sha or short form) — the list shows the first 12 chars. */
+  id: string
+  status: PullLayerStatus
+  /** Bytes transferred (while downloading) or extracted (while extracting). */
+  current?: number
+  /** Layer size. Often unknown for the first moments of a layer's life — that's expected. */
+  total?: number
+}
+
+export type ImagePullState = "starting" | "pulling" | "done" | "cached" | "error"
+
+export interface ImagePullProps {
+  /** Full image reference, e.g. `registry.spunto.net/spunto/worker-base:0.7.2`. */
+  image: string
+  layers: PullLayer[]
+  state?: ImagePullState
+  /** Failure message, shown in the red band when `state="error"`. */
+  error?: string
+  /** Epoch ms — drives the elapsed clock and the final "Pullée en 42 s". */
+  startedAt?: number
+  defaultExpanded?: boolean
+  className?: string
+}
+
+const STATUS_LABEL: Record<PullLayerStatus, string> = {
+  waiting: "en attente",
+  downloading: "téléchargement",
+  verifying: "vérification",
+  extracting: "extraction",
+  done: "terminé",
+}
+
+const STATUS_COLOR: Record<PullLayerStatus, string> = {
+  waiting: pullTheme.waiting,
+  downloading: pullTheme.downloading,
+  verifying: pullTheme.verifying,
+  extracting: pullTheme.extracting,
+  done: pullTheme.done,
+}
+
+const KIB = 1024
+const MIB = 1024 * 1024
+const GIB = 1024 * 1024 * 1024
+
+/** French, base-1024 byte sizes ("148 Mo"). Fixed-width friendly: at most one decimal. */
+function formatBytes(n: number): string {
+  if (!Number.isFinite(n) || n <= 0) return "0 o"
+  if (n < KIB) return `${Math.round(n)} o`
+  if (n < MIB) return `${Math.round(n / KIB)} Ko`
+  if (n < GIB) return `${(n / MIB).toFixed(n < 10 * MIB ? 1 : 0).replace(".", ",")} Mo`
+  return `${(n / GIB).toFixed(1).replace(".", ",")} Go`
+}
+
+function formatRate(bytesPerSecond: number): string {
+  return `${formatBytes(bytesPerSecond)}/s`
+}
+
+function formatDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000))
+  if (s < 60) return `${s} s`
+  const m = Math.floor(s / 60)
+  const rest = s % 60
+  return rest ? `${m} min ${rest} s` : `${m} min`
+}
+
+/**
+ * Splits an image reference into a *truncatable* head and a head-on tail, which
+ * is how the header gets middle-truncation with plain CSS: the head gets
+ * `truncate`, the tail never shrinks. The tag stays readable no matter how
+ * narrow the container gets — it's the part that actually tells you *what* is
+ * being pulled.
+ */
+function splitImageRef(image: string): { head: string; name: string; tag: string } {
+  const slash = image.lastIndexOf("/")
+  const head = slash >= 0 ? image.slice(0, slash + 1) : ""
+  const rest = slash >= 0 ? image.slice(slash + 1) : image
+
+  const at = rest.indexOf("@")
+  if (at >= 0) {
+    // Digest pin — keep it recognisable but don't let 71 chars of sha eat the row.
+    const digest = rest.slice(at)
+    return { head, name: rest.slice(0, at), tag: digest.length > 20 ? `${digest.slice(0, 20)}…` : digest }
+  }
+  const colon = rest.lastIndexOf(":")
+  if (colon > 0) return { head, name: rest.slice(0, colon), tag: rest.slice(colon) }
+  return { head, name: rest, tag: "" }
+}
+
+/** Bytes actually transferred for a layer: past the download, the transfer is complete. */
+function downloadedBytes(layer: PullLayer): number {
+  if (layer.status === "waiting") return 0
+  if (layer.status === "downloading") {
+    const current = layer.current ?? 0
+    return layer.total ? Math.min(current, layer.total) : current
+  }
+  return layer.total ?? layer.current ?? 0
+}
+
+/** Bytes unpacked for a layer — the second half of the work, after the transfer. */
+function extractedBytes(layer: PullLayer): number {
+  if (layer.status === "done") return layer.total ?? layer.current ?? 0
+  if (layer.status === "extracting") {
+    const current = layer.current ?? 0
+    return layer.total ? Math.min(current, layer.total) : current
+  }
+  return 0
+}
+
+function clamp01(n: number): number {
+  return Math.min(1, Math.max(0, n))
+}
+
+/**
+ * Docker image pull, rendered as a real UI instead of ANSI art redrawn in a
+ * terminal. Purely presentational: it takes a snapshot (`image` + `layers` +
+ * `state`) and draws it — no WebSocket, no docker, no polling. Throughput and
+ * ETA are derived internally from successive snapshots, so callers only have to
+ * forward what the daemon already tells them.
+ *
+ * The centrepiece is a *single* overall bar whose colour follows the phase:
+ * flame as bytes come down, amber growing over it as layers unpack, solid green
+ * at the end. It was segmented per layer at first — one block per layer, sized
+ * by weight — and the segments were arithmetically right but unreadable: the
+ * filled parts end up scattered across five or six blocks, so the eye can't add
+ * them up to the announced percentage, and a 148 kB layer next to a 75 MB one is
+ * a 2 px sliver that just looks like a glitch. Per-layer detail lives in the
+ * expandable list below, where each layer gets a full line to itself.
+ *
+ * Two rendering traps this component exists to avoid:
+ *
+ *  1. **Stable order.** Layer sizes arrive late; sorting by weight would make
+ *     the list reshuffle for the entire pull. Order is first-appearance and
+ *     frozen for good (see `orderRef`).
+ *  2. **Growing denominator.** The total is unknown at the start and grows as
+ *     layers announce themselves, so the *percentage can go down*. Hence the
+ *     absolute byte count printed next to it (that one never lies), a `~` marker
+ *     while sizes are still missing, and damped width transitions so the bar
+ *     never snaps backwards.
+ */
+function ImagePull({
+  image,
+  layers,
+  state = "pulling",
+  error,
+  startedAt,
+  defaultExpanded = false,
+  className,
+}: ImagePullProps) {
+  const [expanded, setExpanded] = useState(defaultExpanded)
+
+  // First-appearance order, frozen. Mutating the ref during render is safe here
+  // because it's idempotent — re-running with the same `layers` yields the same
+  // map — and it has to happen before the sort below, not in an effect.
+  const orderRef = useRef<Map<string, number>>(new Map())
+  const ordered = useMemo(() => {
+    const order = orderRef.current
+    for (const layer of layers) if (!order.has(layer.id)) order.set(layer.id, order.size)
+    return [...layers].sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0))
+  }, [layers])
+
+  const stats = useMemo(() => {
+    const known = ordered.filter((l) => l.total && l.total > 0)
+    const knownBytes = known.reduce((sum, l) => sum + (l.total ?? 0), 0)
+    // Layers whose size is still unknown count for an equal share, estimated
+    // from the ones we do know. Without it the total would jump every time a
+    // size lands, and the percentage would fall off a cliff each time.
+    const estimate = known.length ? knownBytes / known.length : MIB
+    const downloaded = ordered.reduce((sum, l) => sum + downloadedBytes(l), 0)
+    const extracted = ordered.reduce((sum, l) => sum + extractedBytes(l), 0)
+    const total = ordered.reduce((sum, l) => sum + (l.total && l.total > 0 ? l.total : estimate), 0)
+    return {
+      downloaded,
+      extracted,
+      total,
+      /** True while at least one layer hasn't announced its size — the total is a guess. */
+      estimated: known.length !== ordered.length,
+    }
+  }, [ordered])
+
+  const rate = useThroughput(stats.downloaded, state)
+  const elapsed = useElapsed(startedAt, state)
+
+  // Failures are the one case where the layer list is the answer, not a detail.
+  useEffect(() => {
+    if (state === "error") setExpanded(true)
+    if (state === "done") setExpanded(false)
+  }, [state])
+
+  const isTerminal = state === "done" || state === "cached"
+  const hasLayers = ordered.length > 0
+  const percent = stats.total > 0 ? clamp01(stats.downloaded / stats.total) : 0
+  const extractPercent = stats.total > 0 ? clamp01(stats.extracted / stats.total) : 0
+  // Both phases overlap for most of a pull (layer 1 unpacks while layer 3 still
+  // downloads), so the headline number stays the download until every byte is
+  // in — only then does the unpacking become the thing you're waiting on.
+  const unpacking = hasLayers && percent >= 1 && extractPercent < 1
+  const remaining = Math.max(0, stats.total - stats.downloaded)
+  // Under a second there's nothing useful to announce — "0 s restantes" is noise.
+  const etaSeconds = rate && rate > 0 && remaining > 0 ? remaining / rate : 0
+  const eta = etaSeconds >= 1 ? etaSeconds : null
+
+  return (
+    <div
+      data-slot="image-pull"
+      className={cn(
+        // Square by default, like `Terminal`: this is a primitive, it doesn't
+        // impose a corner style. Consumers add `rounded-*` via className.
+        //
+        // `@container`, and every responsive rule below is a container query
+        // (`@sm:`, `@md:`…), never a viewport one: what has to fit is this box,
+        // and a 380 px-wide panel on a desktop is exactly as cramped as a phone.
+        "@container w-full min-w-0 overflow-hidden border font-mono text-xs leading-none",
+        className
+      )}
+      style={{
+        backgroundColor: pullTheme.background,
+        borderColor: state === "error" ? "#7f1d1d" : pullTheme.border,
+        color: pullTheme.text,
+      }}
+    >
+      {/* Narrow: image reference and chevron on one line, the figures on their
+          own line underneath (the `w-full` is what forces that wrap). Wide: all
+          four on a single line, figures back to their usual spot before the
+          chevron — hence the `order-*` swap rather than a second copy of the
+          markup. */}
+      <div className="flex min-w-0 flex-wrap items-center gap-x-2.5 gap-y-1.5 px-3 py-2.5">
+        <StateIcon state={state} />
+        <ImageRef image={image} />
+        {hasLayers && (
+          <button
+            type="button"
+            onClick={() => setExpanded((v) => !v)}
+            aria-expanded={expanded}
+            aria-label={expanded ? "Masquer les couches" : "Afficher les couches"}
+            className="order-3 -mr-1 shrink-0 cursor-pointer rounded p-1 transition-colors hover:bg-white/5 @sm:order-4"
+            style={{ color: pullTheme.faint }}
+          >
+            <Chevron open={expanded} />
+          </button>
+        )}
+        <span className="order-4 w-full min-w-0 @sm:order-3 @sm:w-auto">
+          <Aggregate
+            state={state}
+            percent={percent}
+            extractPercent={extractPercent}
+            unpacking={unpacking}
+            stats={stats}
+            rate={rate}
+            eta={eta}
+            elapsed={elapsed}
+            layerCount={ordered.length}
+          />
+        </span>
+      </div>
+
+      {/* The bar itself. Skipped in the two terminal states that have nothing to
+          show: `done` collapses to the single success line above, and `cached`
+          must never draw a 100 % bar for a download that never happened. */}
+      {!isTerminal && (
+        <div className="px-3 pb-3">
+          {hasLayers ? (
+            <OverallBar percent={percent} extractPercent={extractPercent} state={state} />
+          ) : (
+            <IndeterminateBar />
+          )}
+        </div>
+      )}
+
+      {state === "error" && error && (
+        <div
+          className="flex items-start gap-2 border-t px-3 py-2 leading-relaxed"
+          style={{ borderColor: "#7f1d1d", backgroundColor: "rgba(127,29,29,0.15)", color: pullTheme.error }}
+        >
+          <span className="shrink-0 pt-px">✕</span>
+          <span className="min-w-0 break-words">{error}</span>
+        </div>
+      )}
+
+      {expanded && hasLayers && (
+        <div className="max-h-64 overflow-y-auto border-t" style={{ borderColor: pullTheme.border }}>
+          {ordered.map((layer) => (
+            <LayerRow key={layer.id} layer={layer} failed={state === "error" && layer.status !== "done"} />
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * The overall bar: one fill for the whole image, colour by phase.
+ *
+ * Two stacked fills rather than one, because a pull is two jobs: bytes come down
+ * (flame) and layers unpack (amber). The amber grows *over* the flame instead of
+ * replacing it, so the bar only ever moves forward — resetting to zero for the
+ * unpack phase would read as a regression, and sitting frozen at 100 % through a
+ * long extraction would read as a hang.
+ */
+function OverallBar({
+  percent,
+  extractPercent,
+  state,
+}: {
+  percent: number
+  extractPercent: number
+  state: ImagePullState
+}) {
+  const failed = state === "error"
+  return (
+    <div className="relative h-2 w-full overflow-hidden rounded-full" style={{ backgroundColor: pullTheme.track }}>
+      <div
+        className="absolute inset-y-0 left-0 rounded-full transition-[width] duration-500 ease-out motion-reduce:transition-none"
+        style={{ width: `${percent * 100}%`, backgroundColor: failed ? pullTheme.error : pullTheme.downloading }}
+      />
+      {!failed && extractPercent > 0 && (
+        <div
+          className="absolute inset-y-0 left-0 rounded-full transition-[width] duration-500 ease-out motion-reduce:transition-none"
+          style={{
+            width: `${extractPercent * 100}%`,
+            // Green once everything is unpacked: the last colour change is the
+            // signal that the image is actually usable, not merely downloaded.
+            backgroundColor: extractPercent >= 1 ? pullTheme.done : pullTheme.extracting,
+          }}
+        />
+      )}
+    </div>
+  )
+}
+
+/** Registry contacted, not a single layer announced yet — nothing to segment. */
+function IndeterminateBar() {
+  return (
+    <div className="relative h-2 w-full overflow-hidden rounded-full" style={{ backgroundColor: pullTheme.track }}>
+      <Sweep />
+    </div>
+  )
+}
+
+/** The moving highlight used by every indeterminate surface here. */
+function Sweep() {
+  return (
+    <div
+      data-slot="image-pull-sweep"
+      className="absolute inset-y-0 w-1/3"
+      style={{
+        background: `linear-gradient(90deg, transparent, ${pullTheme.downloading}, transparent)`,
+      }}
+    />
+  )
+}
+
+function ImageRef({ image }: { image: string }) {
+  const { head, name, tag } = splitImageRef(image)
+  return (
+    // `overflow-hidden` is the safety net: whatever happens to the widths below,
+    // the reference gets clipped, never painted on top of the figures.
+    <div className="flex min-w-[6rem] flex-1 items-baseline overflow-hidden" title={image}>
+      {/* The registry/path head is the least useful part of a reference, so it's
+          the first thing to go: truncated when space gets tight, dropped
+          entirely on a narrow container. The name truncates too (long names
+          exist), the tag never does — it's the part that says *what* is being
+          pulled. */}
+      {head && (
+        // The head is the *only* shrinkable part, so it absorbs the whole
+        // squeeze on its own. Letting the name shrink too gives you
+        // "registry.spunt…worker-ba… :2.4.0" — two ellipses and no information;
+        // one ellipsis on the registry path reads fine.
+        <span className="hidden min-w-0 truncate @sm:inline" style={{ color: pullTheme.faint }}>
+          {head}
+        </span>
+      )}
+      <span className="shrink-0 whitespace-nowrap" style={{ color: pullTheme.dim }}>
+        {name}
+      </span>
+      {tag && (
+        <span className="shrink-0 whitespace-nowrap font-medium" style={{ color: pullTheme.tag }}>
+          {tag}
+        </span>
+      )}
+    </div>
+  )
+}
+
+function Aggregate({
+  state,
+  percent,
+  extractPercent,
+  unpacking,
+  stats,
+  rate,
+  eta,
+  elapsed,
+  layerCount,
+}: {
+  state: ImagePullState
+  percent: number
+  extractPercent: number
+  unpacking: boolean
+  stats: { downloaded: number; extracted: number; total: number; estimated: boolean }
+  rate: number | null
+  eta: number | null
+  elapsed: number | null
+  layerCount: number
+}) {
+  if (state === "cached") {
+    return (
+      <span className="shrink-0 whitespace-nowrap" style={{ color: pullTheme.faint }}>
+        déjà présente localement
+      </span>
+    )
+  }
+
+  if (state === "done") {
+    return (
+      <span className="shrink-0 whitespace-nowrap tabular-nums" style={{ color: pullTheme.done }}>
+        {elapsed != null ? `Pullée en ${formatDuration(elapsed)} · ` : ""}
+        {formatBytes(stats.total)}
+      </span>
+    )
+  }
+
+  if (state === "starting" || layerCount === 0) {
+    return (
+      <span className="shrink-0 whitespace-nowrap" style={{ color: pullTheme.faint }}>
+        contact du registre…
+      </span>
+    )
+  }
+
+  // Once every byte is down, the number that matters is the unpacking — quoting
+  // "100 %" while the image still isn't usable is the same lie as `cached`.
+  const shown = unpacking ? extractPercent : percent
+  const shownBytes = unpacking ? stats.extracted : stats.downloaded
+
+  return (
+    <span className="flex shrink-0 items-baseline gap-2 whitespace-nowrap tabular-nums">
+      <span style={{ color: state === "error" ? pullTheme.error : pullTheme.text }}>
+        {unpacking && <span style={{ color: pullTheme.extracting }}>extraction · </span>}
+        {Math.round(shown * 100)} %
+        <span style={{ color: pullTheme.faint }}>
+          {" · "}
+          {/* The absolute count is the honest number: unlike the percentage, it
+              can't be pushed backwards by a total that keeps growing. */}
+          {formatBytes(shownBytes)} / {stats.estimated ? "~" : ""}
+          {formatBytes(stats.total)}
+        </span>
+      </span>
+      {state === "pulling" && (rate || eta) && (
+        // Débit et ETA sont du confort : les premiers sacrifiés quand la place manque.
+        <span className="hidden @md:inline" style={{ color: pullTheme.faint }}>
+          {"· "}
+          {rate ? formatRate(rate) : ""}
+          {rate && eta ? " · " : ""}
+          {eta ? formatDuration(eta * 1000) : ""}
+        </span>
+      )}
+    </span>
+  )
+}
+
+/** `failed` = the pull errored and this layer never finished — the same red the bar uses. */
+function LayerRow({ layer, failed }: { layer: PullLayer; failed?: boolean }) {
+  const known = !!(layer.total && layer.total > 0)
+  const fraction = known ? clamp01((layer.current ?? 0) / layer.total!) : 0
+  const done = layer.status === "done"
+  const color = failed ? pullTheme.error : STATUS_COLOR[layer.status]
+
+  return (
+    <div className="flex items-center gap-2.5 px-3 py-1.5">
+      <span className="w-3 shrink-0 text-center" style={{ color }}>
+        {done ? "✓" : layer.status === "waiting" ? "·" : "↓"}
+      </span>
+      <span className="w-[5.5rem] shrink-0 truncate @sm:w-[6.5rem]" style={{ color: done ? pullTheme.done : pullTheme.dim }}>
+        {layer.id.replace(/^sha256:/, "").slice(0, 12)}
+      </span>
+      <div className="relative h-1 min-w-0 flex-1 overflow-hidden rounded-full" style={{ backgroundColor: pullTheme.track }}>
+        {known || done ? (
+          <div
+            className="absolute inset-y-0 left-0 transition-[width] duration-500 ease-out motion-reduce:transition-none"
+            style={{ width: `${(done ? 1 : fraction) * 100}%`, backgroundColor: color }}
+          />
+        ) : layer.status !== "waiting" ? (
+          <Sweep />
+        ) : null}
+      </div>
+      {/* Narrow: only the bytes already in — the row's own bar carries the
+          fraction, so repeating "/ total" just squeezes that bar to nothing. */}
+      <span className="w-[4.5rem] shrink-0 text-right tabular-nums @sm:hidden" style={{ color: pullTheme.faint }}>
+        {known || done ? formatBytes(layer.current ?? 0) : "—"}
+      </span>
+      <span className="hidden w-[7.5rem] shrink-0 text-right tabular-nums @sm:inline" style={{ color: pullTheme.faint }}>
+        {known ? `${formatBytes(layer.current ?? 0)} / ${formatBytes(layer.total!)}` : done ? formatBytes(layer.current ?? 0) : "—"}
+      </span>
+      {/* The status dot already encodes the phase — the word is a wide-container bonus. */}
+      <span className="hidden w-24 shrink-0 text-right @lg:inline" style={{ color: done ? pullTheme.done : pullTheme.faint }}>
+        {STATUS_LABEL[layer.status]}
+      </span>
+    </div>
+  )
+}
+
+function StateIcon({ state }: { state: ImagePullState }) {
+  const common = "size-3.5 shrink-0"
+  if (state === "done")
+    return (
+      <svg viewBox="0 0 16 16" fill="none" className={common} style={{ color: pullTheme.done }} aria-hidden>
+        <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="1.5" />
+        <path d="m5 8.2 2.1 2.1L11 6.4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+      </svg>
+    )
+  if (state === "cached")
+    return (
+      // A disk, not a checkmark: nothing was downloaded, and the icon shouldn't
+      // suggest otherwise.
+      <svg viewBox="0 0 16 16" fill="none" className={common} style={{ color: pullTheme.faint }} aria-hidden>
+        <ellipse cx="8" cy="4" rx="5.5" ry="2.2" stroke="currentColor" strokeWidth="1.4" />
+        <path d="M2.5 4v8c0 1.2 2.5 2.2 5.5 2.2s5.5-1 5.5-2.2V4" stroke="currentColor" strokeWidth="1.4" />
+        <path d="M2.5 8c0 1.2 2.5 2.2 5.5 2.2s5.5-1 5.5-2.2" stroke="currentColor" strokeWidth="1.4" />
+      </svg>
+    )
+  if (state === "error")
+    return (
+      <svg viewBox="0 0 16 16" fill="none" className={common} style={{ color: pullTheme.error }} aria-hidden>
+        <circle cx="8" cy="8" r="7" stroke="currentColor" strokeWidth="1.5" />
+        <path d="M8 4.5v4.2M8 11.2v.6" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      </svg>
+    )
+  return (
+    <svg viewBox="0 0 16 16" fill="none" className={common} style={{ color: pullTheme.downloading }} aria-hidden>
+      <path d="M8 2.5v7.5m0 0L5 7.2M8 10l3-2.8" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+      <path d="M2.8 12.2h10.4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+    </svg>
+  )
+}
+
+function Chevron({ open }: { open: boolean }) {
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      fill="none"
+      className={cn("size-3.5 transition-transform duration-200 motion-reduce:transition-none", open && "rotate-180")}
+      aria-hidden
+    >
+      <path d="m4 6.5 4 4 4-4" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+/**
+ * Bytes/second over a short sliding window of successive snapshots. Derived
+ * here rather than asked of the caller: the component already sees every
+ * snapshot, and a plain `current/elapsed` average would keep quoting a stale
+ * number long after the connection changed pace.
+ */
+function useThroughput(downloaded: number, state: ImagePullState): number | null {
+  const samplesRef = useRef<Array<{ t: number; b: number }>>([])
+  const [rate, setRate] = useState<number | null>(null)
+
+  useEffect(() => {
+    if (state !== "pulling" && state !== "starting") {
+      samplesRef.current = []
+      setRate(null)
+      return
+    }
+    const now = Date.now()
+    const samples = samplesRef.current
+    samples.push({ t: now, b: downloaded })
+    while (samples.length > 2 && now - samples[0].t > 5000) samples.shift()
+
+    const first = samples[0]
+    const seconds = (now - first.t) / 1000
+    // Under half a second of window the number is noise — keep the previous one
+    // rather than flashing a wildly wrong rate.
+    if (seconds >= 0.5 && downloaded > first.b) setRate((downloaded - first.b) / seconds)
+  }, [downloaded, state])
+
+  return rate
+}
+
+/**
+ * Milliseconds since `startedAt`, ticking while the pull runs and frozen the
+ * moment it reaches a terminal state — that frozen value is what the collapsed
+ * "Pullée en 42 s" line reports. Returns null until mounted, so server and
+ * client render the same thing.
+ */
+function useElapsed(startedAt: number | undefined, state: ImagePullState): number | null {
+  const [now, setNow] = useState<number | null>(null)
+  const [endedAt, setEndedAt] = useState<number | null>(null)
+  const settled = state === "done" || state === "cached" || state === "error"
+
+  useEffect(() => {
+    if (settled) {
+      // Stamped here, not on the last tick, so "Pullée en 42 s" isn't off by
+      // up to a second of interval slack.
+      setEndedAt(Date.now())
+      return
+    }
+    setEndedAt(null)
+    setNow(Date.now())
+    const id = setInterval(() => setNow(Date.now()), 1000)
+    return () => clearInterval(id)
+  }, [settled])
+
+  const reference = endedAt ?? now
+  if (startedAt == null || reference == null) return null
+  return Math.max(0, reference - startedAt)
+}
+
+export { ImagePull }

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>
+  )
+}