@spunto/design-system 0.33.0 → 0.35.0

package/README.md

@@ -188,7 +188,7 @@ 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 — `/workers`, `/devcontainer`, `/projects`, `/tasks`
+## Domain components — `/workers`, `/devcontainer`, `/projects`, `/tasks`, `/observability`
 
 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
@@ -202,6 +202,7 @@ import { WorkerCard } from "@spunto/design-system/workers"
 import { ImageCard, FeatureCard, ExtensionCard } from "@spunto/design-system/devcontainer"  // domain
 import { ProjectForm, ProjectPanel } from "@spunto/design-system/projects"                   // domain
 import { TaskList, TaskCockpit, TaskEventStream } from "@spunto/design-system/tasks"         // domain
+import { SpanWaterfall, TracesOverview } from "@spunto/design-system/observability"         // domain
 import { Section, ProductHeader } from "@spunto/design-system/marketing"                     // not a domain — see below
 ```
 
@@ -330,6 +331,36 @@ review. Every surface that shows one:
 Same rules as `/workers`: nothing fetches, types are structural and lax
 (`TaskItem`, `TaskEvent`, `TaskDiff`…), links go through `render.link`.
 
+### `@spunto/design-system/observability`
+
+Traces — what an OpenTelemetry backend hands back, drawn. Every surface that shows one:
+
+- **`SpanWaterfall`** — a trace as a tree of spans on a shared time axis (children under
+  their parent, not the backend's start-time order), colour by nature (http → build, db →
+  ship, agent RPC / job → run, error → destructive), attributes of the clicked span. Any
+  span with children folds (chevron, Collapse/Expand all, ←/→; a folded row shows `+N`, red
+  when an error is hidden under it; `defaultCollapsedDepth`, or controlled
+  `collapsedSpanIds`). Hand it `logs` and a Logs section appears underneath, linked by the
+  span id the logger stamped: a line selects its span, unfolding its ancestors if needed.
+  `SpanWaterfallSkeleton` for the fetch.
+- **`TraceList`** — one row per request (method, route, latency bar, when), or
+  `variant="compact"` for root spans that aren't necessarily HTTP. **`TraceFiltersBar`** next
+  to it: window and min latency are meant for the backend query, status / method / route are
+  applied client-side by `filterTraces`; `traceFilterOptions` derives the select options.
+- **`TracesOverview`** — stat tiles, requests and p95 over time, per-service cards
+  (`showServices`), slowest routes. **`TraceRouteDetail`** — one route's stats and example
+  traces. Both are *derived* from the traces they're handed, so a list and its dashboard
+  can't disagree and no aggregation endpoint is needed.
+- **`LogLines`** — log records with severity and trace/span ids: under a waterfall
+  (`origin`, `onSelectSpan`) or as a service's feed (`onOpenTrace`).
+- Pure helpers: `computeStats`, `byRoute`, `byService`, `timeBuckets`, `exampleTraces`,
+  `percentile`, `methodOf`/`routeOf`, `orderSpans`, `spanColor`; and **one** latency scale —
+  `formatLatency` (sub-millisecond precise), `latencyTone`/`latencyColor`/`latencyTextClass`.
+
+Same rules as `/workers`: nothing fetches (no URL, no query client — the org's traces view,
+a deployment's Observability tab and the admin each pass their own data), types are
+structural and lax (`TraceItem`, `TraceSpan`, `TelemetryLogLine`).
+
 ### `@spunto/design-system/projects`
 
 - **`ProjectForm`** — the whole "compose a dev environment" screen: identity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",
@@ -45,6 +45,10 @@
       "types": "./src/components/tasks/index.ts",
       "import": "./src/components/tasks/index.ts"
     },
+    "./observability": {
+      "types": "./src/components/observability/index.ts",
+      "import": "./src/components/observability/index.ts"
+    },
     "./projects": {
       "types": "./src/components/projects/index.ts",
       "import": "./src/components/projects/index.ts"

package/src/components/observability/analytics.ts

@@ -0,0 +1,153 @@
+// Client-side aggregations over a set of traces. Everything is derived from the list a backend
+// already returned, so a list and its dashboard stay driven by exactly the same filters — and the
+// dashboard never needs an endpoint of its own. Pure functions: no Date.now() unless defaulted.
+
+import type { TraceItem } from "./types"
+
+const METHODS = ["GET", "POST", "PATCH", "PUT", "DELETE", "HEAD", "OPTIONS"]
+
+/** HTTP method of a root span name ("GET /x" → "GET"), "—" when it isn't one. */
+export function methodOf(name: string): string {
+  const m = name.split(" ")[0]
+  return METHODS.includes(m) ? m : "—"
+}
+
+/** Route template of a root span name ("GET /x" → "/x"); non-HTTP names come back whole. */
+export function routeOf(name: string): string {
+  const m = name.split(" ")[0]
+  return METHODS.includes(m) ? name.slice(m.length + 1) || name : name
+}
+
+/** Percentile, linear interpolation, over an ascending-sorted array. */
+export function percentile(sortedAsc: number[], p: number): number {
+  if (sortedAsc.length === 0) return 0
+  if (sortedAsc.length === 1) return sortedAsc[0]
+  const idx = (p / 100) * (sortedAsc.length - 1)
+  const lo = Math.floor(idx)
+  const hi = Math.ceil(idx)
+  if (lo === hi) return sortedAsc[lo]
+  return sortedAsc[lo] + (sortedAsc[hi] - sortedAsc[lo]) * (idx - lo)
+}
+
+export interface TraceStats {
+  count: number
+  errorCount: number
+  errorRate: number
+  p50: number
+  p95: number
+  p99: number
+  max: number
+}
+
+export function computeStats(traces: TraceItem[]): TraceStats {
+  const durations = traces.map((t) => t.durationMs).sort((a, b) => a - b)
+  const errorCount = traces.filter((t) => t.error).length
+  return {
+    count: traces.length,
+    errorCount,
+    errorRate: traces.length ? errorCount / traces.length : 0,
+    p50: percentile(durations, 50),
+    p95: percentile(durations, 95),
+    p99: percentile(durations, 99),
+    max: durations.length ? durations[durations.length - 1] : 0,
+  }
+}
+
+function groupBy(traces: TraceItem[], key: (t: TraceItem) => string): Map<string, TraceItem[]> {
+  const groups = new Map<string, TraceItem[]>()
+  for (const t of traces) {
+    const k = key(t)
+    const arr = groups.get(k)
+    if (arr) arr.push(t)
+    else groups.set(k, [t])
+  }
+  return groups
+}
+
+export interface RouteStat {
+  /** Full root span name ("GET /api/orgs/:orgId/…") — the grouping key. */
+  name: string
+  route: string
+  method: string
+  count: number
+  p50: number
+  p95: number
+  p99: number
+  errorRate: number
+}
+
+/** Per route (method + template), slowest p95 first. */
+export function byRoute(traces: TraceItem[]): RouteStat[] {
+  const rows: RouteStat[] = []
+  for (const [name, items] of groupBy(traces, (t) => t.name)) {
+    const s = computeStats(items)
+    rows.push({ name, route: routeOf(name), method: methodOf(name), count: s.count, p50: s.p50, p95: s.p95, p99: s.p99, errorRate: s.errorRate })
+  }
+  return rows.sort((a, b) => b.p95 - a.p95)
+}
+
+export interface ServiceStat {
+  service: string
+  count: number
+  errorRate: number
+  p95: number
+}
+
+/** Per emitting service, busiest first. A trace without a service lands in "(unknown)". */
+export function byService(traces: TraceItem[]): ServiceStat[] {
+  const rows: ServiceStat[] = []
+  for (const [service, items] of groupBy(traces, (t) => t.service || "(unknown)")) {
+    const s = computeStats(items)
+    rows.push({ service, count: s.count, errorRate: s.errorRate, p95: s.p95 })
+  }
+  return rows.sort((a, b) => b.count - a.count)
+}
+
+export interface TimeBucket {
+  start: number
+  total: number
+  errors: number
+  p95: number
+}
+
+/**
+ * Splits the traces into `bucketCount` equal intervals over the last `lookbackMinutes`, ending at
+ * `now`. A trace outside the window is clamped into the first/last bucket rather than dropped:
+ * the list next to the chart shows it, so the chart must count it.
+ */
+export function timeBuckets(
+  traces: TraceItem[],
+  lookbackMinutes: number,
+  bucketCount = 24,
+  now: number = Date.now()
+): TimeBucket[] {
+  const windowMs = lookbackMinutes * 60_000
+  const start = now - windowMs
+  const size = windowMs / bucketCount
+  const buckets = Array.from({ length: bucketCount }, (_, i) => ({ start: start + i * size, items: [] as TraceItem[] }))
+  for (const t of traces) {
+    const i = Math.min(bucketCount - 1, Math.max(0, Math.floor((t.startTimeMs - start) / size)))
+    buckets[i].items.push(t)
+  }
+  return buckets.map((b) => {
+    const s = computeStats(b.items)
+    return { start: b.start, total: s.count, errors: s.errorCount, p95: s.p95 }
+  })
+}
+
+/**
+ * Up to `limit` example traces for a set: errors first, then the slowest, then the most recent,
+ * de-duplicated. What a route's detail shows to click into.
+ */
+export function exampleTraces(traces: TraceItem[], limit = 12): TraceItem[] {
+  const slowest = [...traces].sort((a, b) => b.durationMs - a.durationMs).slice(0, Math.ceil(limit / 2))
+  const recent = [...traces].sort((a, b) => b.startTimeMs - a.startTimeMs).slice(0, Math.ceil(limit / 2))
+  const seen = new Set<string>()
+  return [...traces.filter((t) => t.error), ...slowest, ...recent]
+    .filter((t) => {
+      if (seen.has(t.traceId)) return false
+      seen.add(t.traceId)
+      return true
+    })
+    .slice(0, limit)
+}

package/src/components/observability/index.ts

@@ -0,0 +1,39 @@
+// @spunto/design-system/observability — traces: span waterfall, list, filters, overview dashboard.
+//
+// Domain sub-export (see the README's "Domain components" rule): these know what a trace, a span
+// and a route are. They know nothing of a backend — every component takes the traces or spans the
+// app already fetched (Cloud's per-org `/traces`, the admin's global Cloud Trace view, Jaeger…),
+// and the aggregations are pure functions exported alongside, so a number can be derived without
+// drawing anything.
+
+export type { TraceItem, TraceSpan } from "./types"
+
+export { SpanWaterfall, SpanWaterfallSkeleton, orderSpans, spanColor, spanTree } from "./span-waterfall"
+export type { SpanTreeInfo, SpanWaterfallProps } from "./span-waterfall"
+
+export { LogLines, severityClass, stripAnsi } from "./log-lines"
+export type { LogLinesProps, TelemetryLogLine } from "./log-lines"
+
+export { TracesOverview, TraceStatTile, RequestsOverTime, LatencyOverTime } from "./traces-overview"
+export type { TracesOverviewProps } from "./traces-overview"
+
+export { TraceList, TraceListSkeleton, TraceRouteDetail } from "./trace-list"
+export type { TraceListProps, TraceRouteDetailProps } from "./trace-list"
+
+export { TraceFiltersBar, DEFAULT_TRACE_FILTERS, filterTraces, traceFilterOptions } from "./trace-filters"
+export type { TraceFilters, TraceFiltersBarProps } from "./trace-filters"
+
+export {
+  byRoute,
+  byService,
+  computeStats,
+  exampleTraces,
+  methodOf,
+  percentile,
+  routeOf,
+  timeBuckets,
+} from "./analytics"
+export type { RouteStat, ServiceStat, TimeBucket, TraceStats } from "./analytics"
+
+export { formatLatency, latencyColor, latencyTextClass, latencyTone } from "./latency"
+export type { LatencyTone } from "./latency"

package/src/components/observability/latency.ts

@@ -0,0 +1,47 @@
+// Latency formatting and tone — the one place that decides what "slow" looks like. The dashboard
+// had this threshold copied four times (overview, route sheet, list bar, list text) across two
+// apps, in two notations (a CSS colour and a Tailwind class).
+
+/**
+ * A latency, precise enough for a span: "1.24s", "38ms", "0.42ms". `formatDuration` (root entry)
+ * stops at whole milliseconds and one decimal of a second — right for a setup phase, too coarse
+ * for a 0.3 ms database call next to a 1.2 s request.
+ */
+export function formatLatency(ms: number): string {
+  if (ms >= 1000) return `${(ms / 1000).toFixed(2)}s`
+  if (ms >= 1) return `${Math.round(ms)}ms`
+  return `${Math.max(0, ms).toFixed(2)}ms`
+}
+
+export type LatencyTone = "fast" | "slow" | "critical"
+
+/** ≥ 1 s is critical, ≥ 300 ms is slow. The thresholds of an interactive HTTP request. */
+export function latencyTone(ms: number): LatencyTone {
+  if (ms >= 1000) return "critical"
+  if (ms >= 300) return "slow"
+  return "fast"
+}
+
+// Inline colours (SVG fills, bar widths set by style) — amber-600 / emerald-600, the same the
+// Tailwind classes below resolve to in light mode.
+const TONE_COLOR: Record<LatencyTone, string> = {
+  critical: "var(--destructive)",
+  slow: "#d97706",
+  fast: "#059669",
+}
+
+const TONE_TEXT: Record<LatencyTone, string> = {
+  critical: "text-destructive",
+  slow: "text-amber-600 dark:text-amber-400",
+  fast: "text-emerald-600 dark:text-emerald-400",
+}
+
+/** CSS colour of a latency, for a `style` or an SVG `fill`. */
+export function latencyColor(ms: number): string {
+  return TONE_COLOR[latencyTone(ms)]
+}
+
+/** Tailwind text classes of a latency, dark mode included. */
+export function latencyTextClass(ms: number): string {
+  return TONE_TEXT[latencyTone(ms)]
+}

package/src/components/observability/log-lines.tsx

@@ -0,0 +1,117 @@
+"use client"
+
+import { cn } from "../../utils"
+import { formatLatency } from "./latency"
+
+// ── Log lines ─────────────────────────────────────────────────────────────
+// Log records as an OTLP pipeline stores them: a body, a severity, and — when the logger wrote
+// them inside a span — the exact trace/span ids. That id is the whole point: a line is tied to a
+// span by what the logger stamped, not by "same container, same second".
+
+/** One log record. Structural and lax: only `timestamp` and `body` are required. */
+export interface TelemetryLogLine {
+  /** ISO timestamp (or anything `Date.parse` reads). */
+  timestamp: string
+  body: string
+  service?: string | null
+  severity?: string | null
+  traceId?: string | null
+  spanId?: string | null
+  attributes?: Record<string, string>
+}
+
+/** Tailwind text classes of an OTel severity text ("ERROR", "WARN", "INFO2"…). */
+export function severityClass(severity: string | null | undefined): string {
+  const s = (severity ?? "").toUpperCase()
+  if (s.startsWith("ERROR") || s.startsWith("FATAL")) return "text-destructive"
+  if (s.startsWith("WARN")) return "text-amber-600 dark:text-amber-400"
+  return "text-muted-foreground"
+}
+
+/** Drops ANSI colour codes a logger meant for a terminal. */
+export function stripAnsi(text: string): string {
+  // eslint-disable-next-line no-control-regex
+  return text.replace(/\u001b\[[0-9;]*[A-Za-z]/g, "")
+}
+
+function clock(ms: number): string {
+  return new Date(ms).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit", second: "2-digit" })
+}
+
+export interface LogLinesProps {
+  lines: TelemetryLogLine[]
+  /**
+   * Time column. A number is the start of a trace: each line shows "+12ms" from it — what
+   * `SpanWaterfall` does when handed `logs`. Omitted: wall-clock time.
+   */
+  origin?: number
+  /**
+   * Makes a line whose `spanId` is in this set a button that selects that span, and highlights
+   * the lines of `selectedSpanId`. For the logs under a waterfall.
+   */
+  spanIds?: Set<string>
+  selectedSpanId?: string | null
+  onSelectSpan?: (spanId: string | null) => void
+  /** A "trace" link at the end of each line that carries a trace id. For a service's log feed. */
+  onOpenTrace?: (traceId: string) => void
+  /** Service name when a line has none (e.g. resolved from a resource attribute). */
+  serviceOf?: (line: TelemetryLogLine) => string | null | undefined
+  className?: string
+}
+
+export function LogLines({
+  lines,
+  origin,
+  spanIds,
+  selectedSpanId,
+  onSelectSpan,
+  onOpenTrace,
+  serviceOf,
+  className,
+}: LogLinesProps) {
+  const cols = onOpenTrace ? "grid-cols-[5.5rem_7rem_3.5rem_1fr_auto]" : "grid-cols-[5.5rem_7rem_3.5rem_1fr]"
+  return (
+    <div className={cn("max-h-96 overflow-auto rounded-lg border border-border", className)}>
+      {lines.map((l, i) => {
+        const at = Date.parse(l.timestamp)
+        // A row holding a "trace" button can't itself be a button: the two uses don't mix.
+        const linked = !onOpenTrace && !!onSelectSpan && !!l.spanId && (!spanIds || spanIds.has(l.spanId))
+        const isSel = linked && l.spanId === selectedSpanId
+        const cells = (
+          <>
+            <span className="tabular-nums text-muted-foreground">
+              {origin !== undefined ? `+${formatLatency(Math.max(0, at - origin))}` : clock(at)}
+            </span>
+            <span className="truncate text-muted-foreground">{l.service ?? serviceOf?.(l) ?? "—"}</span>
+            <span className={cn("truncate", severityClass(l.severity))}>{l.severity ?? ""}</span>
+            <span className="whitespace-pre-wrap break-all text-foreground">{stripAnsi(l.body)}</span>
+            {onOpenTrace &&
+              (l.traceId ? (
+                <button type="button" onClick={() => onOpenTrace(l.traceId!)} className="text-primary hover:underline">
+                  trace
+                </button>
+              ) : (
+                <span />
+              ))}
+          </>
+        )
+        const rowClass = cn("grid w-full items-start gap-3 border-b border-border/60 px-3 py-1 text-left font-mono text-[11px] last:border-b-0", cols)
+        return linked ? (
+          <button
+            key={i}
+            type="button"
+            aria-pressed={isSel}
+            onClick={() => onSelectSpan!(isSel ? null : l.spanId!)}
+            className={cn(rowClass, "hover:bg-muted/50", isSel && "bg-primary/10")}
+          >
+            {cells}
+          </button>
+        ) : (
+          <div key={i} className={rowClass}>
+            {cells}
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/components/observability/observability.test.tsx

@@ -0,0 +1,244 @@
+import { describe, it, expect } from "vitest"
+import { fireEvent, render, screen } from "@testing-library/react"
+import {
+  byRoute,
+  byService,
+  computeStats,
+  exampleTraces,
+  filterTraces,
+  formatLatency,
+  latencyTone,
+  methodOf,
+  orderSpans,
+  percentile,
+  routeOf,
+  SpanWaterfall,
+  spanTree,
+  timeBuckets,
+  TracesOverview,
+  type TraceItem,
+  type TraceSpan,
+} from "./index"
+
+const NOW = Date.parse("2026-09-28T12:00:00Z")
+const MIN = 60_000
+
+function trace(id: string, name: string, durationMs: number, agoMs: number, extra: Partial<TraceItem> = {}): TraceItem {
+  return { traceId: id, name, service: "spunto-api", startTimeMs: NOW - agoMs, durationMs, ...extra }
+}
+
+describe("analytics", () => {
+  it("sépare méthode et route, et laisse entier un nom qui n'est pas HTTP", () => {
+    expect(methodOf("GET /api/orgs/:orgId")).toBe("GET")
+    expect(routeOf("GET /api/orgs/:orgId")).toBe("/api/orgs/:orgId")
+    expect(methodOf("job.worker.create")).toBe("—")
+    expect(routeOf("job.worker.create")).toBe("job.worker.create")
+  })
+
+  it("interpole les percentiles", () => {
+    expect(percentile([], 95)).toBe(0)
+    expect(percentile([10], 95)).toBe(10)
+    expect(percentile([0, 100], 50)).toBe(50)
+    expect(percentile([1, 2, 3, 4, 5], 100)).toBe(5)
+  })
+
+  it("compte les erreurs et le max", () => {
+    const s = computeStats([trace("a", "GET /x", 10, 0), trace("b", "GET /x", 30, 0, { error: true })])
+    expect(s).toMatchObject({ count: 2, errorCount: 1, errorRate: 0.5, max: 30 })
+  })
+
+  it("trie les routes par p95 décroissant, les services par volume", () => {
+    const set = [
+      trace("a", "GET /fast", 5, 0),
+      trace("b", "GET /fast", 7, 0),
+      trace("c", "POST /slow", 900, 0, { service: "spunto-proxy" }),
+    ]
+    expect(byRoute(set).map((r) => r.name)).toEqual(["POST /slow", "GET /fast"])
+    expect(byService(set).map((s) => s.service)).toEqual(["spunto-api", "spunto-proxy"])
+    expect(byService([trace("x", "GET /", 1, 0, { service: null })])[0].service).toBe("(unknown)")
+  })
+
+  it("répartit dans la fenêtre, et ramène au bord ce qui en déborde au lieu de le perdre", () => {
+    const b = timeBuckets([trace("old", "GET /", 1, 90 * MIN), trace("new", "GET /", 1, 1 * MIN)], 60, 6, NOW)
+    expect(b).toHaveLength(6)
+    expect(b[0].total).toBe(1)
+    expect(b[5].total).toBe(1)
+    expect(b.reduce((n, x) => n + x.total, 0)).toBe(2)
+  })
+
+  it("choisit les exemples : erreurs, puis lentes, puis récentes, sans doublon", () => {
+    const set = [trace("e", "GET /", 1, 5, { error: true }), trace("slow", "GET /", 500, 10), trace("recent", "GET /", 2, 0)]
+    const ids = exampleTraces(set, 4).map((t) => t.traceId)
+    expect(ids[0]).toBe("e")
+    expect(new Set(ids).size).toBe(ids.length)
+    expect(ids).toContain("slow")
+    expect(ids).toContain("recent")
+  })
+
+  it("filtre côté client sur statut, méthode et route", () => {
+    const set = [trace("a", "GET /x", 1, 0), trace("b", "POST /x", 1, 0, { error: true }), trace("c", "GET /y", 1, 0)]
+    expect(filterTraces(set, { status: "errors", method: "all", route: "all" }).map((t) => t.traceId)).toEqual(["b"])
+    expect(filterTraces(set, { status: "all", method: "GET", route: "/x" }).map((t) => t.traceId)).toEqual(["a"])
+  })
+})
+
+describe("latence", () => {
+  it("garde la précision d'un span sous la milliseconde", () => {
+    expect(formatLatency(0.42)).toBe("0.42ms")
+    expect(formatLatency(38.4)).toBe("38ms")
+    expect(formatLatency(1234)).toBe("1.23s")
+  })
+
+  it("a un seul jeu de seuils", () => {
+    expect(latencyTone(299)).toBe("fast")
+    expect(latencyTone(300)).toBe("slow")
+    expect(latencyTone(1000)).toBe("critical")
+  })
+})
+
+const SPANS: TraceSpan[] = [
+  { spanId: "db", parentSpanId: "root", name: "pg.query", startTimeMs: 20, durationMs: 5, attributes: { "db.system": "postgresql" } },
+  { spanId: "root", parentSpanId: null, name: "GET /api/x", startTimeMs: 0, durationMs: 100, service: "spunto-api" },
+  { spanId: "rpc", parentSpanId: "root", name: "agent.cmd spawn", startTimeMs: 10, durationMs: 50 },
+  { spanId: "leaf", parentSpanId: "rpc", name: "docker.create", startTimeMs: 12, durationMs: 30 },
+  { spanId: "orphan", parentSpanId: "not-in-trace", name: "late", startTimeMs: 90, durationMs: 1 },
+]
+
+describe("orderSpans", () => {
+  it("met chaque enfant sous son parent, les frères par heure de début", () => {
+    expect(orderSpans(SPANS).map((o) => `${o.span.spanId}:${o.depth}`)).toEqual([
+      "root:0",
+      "rpc:1",
+      "leaf:2",
+      "db:1",
+      "orphan:0",
+    ])
+  })
+
+  it("ne boucle pas sur un span qui est son propre parent", () => {
+    const loop: TraceSpan[] = [{ spanId: "a", parentSpanId: "a", name: "a", startTimeMs: 0, durationMs: 1 }]
+    // Son parent est dans le jeu, donc ce n'est pas une racine : rien à dessiner, mais pas de boucle.
+    expect(orderSpans(loop)).toEqual([])
+  })
+})
+
+describe("SpanWaterfall", () => {
+  it("dessine les spans, et montre les attributs d'un span cliqué", () => {
+    render(<SpanWaterfall traceId="abc123" spans={SPANS} />)
+    expect(screen.getByText("abc123")).toBeTruthy()
+    expect(screen.getByText("5 spans")).toBeTruthy()
+    expect(screen.queryByText("postgresql")).toBeNull()
+    fireEvent.click(screen.getByText("pg.query"))
+    expect(screen.getByText("postgresql")).toBeTruthy()
+  })
+
+  it("relie une ligne de log à son span", () => {
+    render(
+      <SpanWaterfall
+        spans={SPANS}
+        logs={[{ timestamp: new Date(25).toISOString(), body: "\u001b[31mslow query\u001b[0m", spanId: "db", severity: "WARN" }]}
+      />
+    )
+    expect(screen.getByText("1 line with this trace id")).toBeTruthy()
+    fireEvent.click(screen.getByText("slow query"))
+    // La ligne a sélectionné le span : son détail est ouvert.
+    expect(screen.getByText("postgresql")).toBeTruthy()
+  })
+
+  it("dit quand aucun log ne porte ce trace id", () => {
+    render(<SpanWaterfall spans={SPANS} logs={[]} />)
+    expect(screen.getByText(/No log line carries this trace id/)).toBeTruthy()
+  })
+})
+
+describe("TracesOverview", () => {
+  it("n'a de lignes cliquables que si on lui donne onRouteClick", () => {
+    const set = [trace("a", "GET /x", 10, MIN)]
+    const { rerender } = render(<TracesOverview traces={set} lookbackMinutes={60} now={NOW} />)
+    expect(screen.getByText("/x").closest("button")).toBeNull()
+    let clicked = ""
+    rerender(<TracesOverview traces={set} lookbackMinutes={60} now={NOW} onRouteClick={(n) => (clicked = n)} />)
+    fireEvent.click(screen.getByText("/x"))
+    expect(clicked).toBe("GET /x")
+  })
+
+  it("n'affiche les services que sur demande", () => {
+    const set = [trace("a", "GET /x", 10, MIN, { service: "spunto-proxy" })]
+    const { rerender } = render(<TracesOverview traces={set} lookbackMinutes={60} now={NOW} />)
+    expect(screen.queryByText("spunto-proxy")).toBeNull()
+    rerender(<TracesOverview traces={set} lookbackMinutes={60} now={NOW} showServices />)
+    expect(screen.getByText("spunto-proxy")).toBeTruthy()
+  })
+})
+
+describe("SpanWaterfall — repli", () => {
+  it("sait ce que replier cacherait, erreurs comprises", () => {
+    const t = spanTree(orderSpans([...SPANS, { spanId: "boom", parentSpanId: "leaf", name: "x", startTimeMs: 13, durationMs: 1, error: true }]))
+    expect(t.get("root")).toMatchObject({ parentId: null, descendants: 4, descendantError: true })
+    expect(t.get("rpc")).toMatchObject({ parentId: "root", descendants: 2, descendantError: true })
+    expect(t.get("db")).toMatchObject({ parentId: "root", descendants: 0, descendantError: false })
+  })
+
+  it("replie un sous-arbre au chevron, sans sélectionner le span", () => {
+    render(<SpanWaterfall spans={SPANS} />)
+    expect(screen.getByText("docker.create")).toBeTruthy()
+    fireEvent.click(screen.getByLabelText("Collapse agent.cmd spawn"))
+    expect(screen.queryByText("docker.create")).toBeNull()
+    expect(screen.getByText("+1")).toBeTruthy()
+    // Le clic sur le chevron n'a pas ouvert le détail du span.
+    expect(screen.queryByText("kind")).toBeNull()
+    fireEvent.click(screen.getByLabelText("Expand agent.cmd spawn"))
+    expect(screen.getByText("docker.create")).toBeTruthy()
+  })
+
+  it("replie et déplie tout", () => {
+    render(<SpanWaterfall spans={SPANS} />)
+    fireEvent.click(screen.getByText("Collapse all"))
+    expect(screen.queryByText("pg.query")).toBeNull()
+    expect(screen.getByText("GET /api/x")).toBeTruthy()
+    expect(screen.getByText("late")).toBeTruthy()
+    fireEvent.click(screen.getByText("Expand all"))
+    expect(screen.getByText("docker.create")).toBeTruthy()
+  })
+
+  it("part replié à partir d'une profondeur", () => {
+    render(<SpanWaterfall spans={SPANS} defaultCollapsedDepth={1} />)
+    expect(screen.getByText("agent.cmd spawn")).toBeTruthy()
+    expect(screen.queryByText("docker.create")).toBeNull()
+  })
+
+  it("se replie au clavier", () => {
+    render(<SpanWaterfall spans={SPANS} />)
+    const row = screen.getByText("agent.cmd spawn").closest("[role=button]") as HTMLElement
+    fireEvent.keyDown(row, { key: "ArrowLeft" })
+    expect(screen.queryByText("docker.create")).toBeNull()
+    fireEvent.keyDown(row, { key: "ArrowRight" })
+    expect(screen.getByText("docker.create")).toBeTruthy()
+    fireEvent.keyDown(row, { key: "Enter" })
+    expect(row.getAttribute("aria-pressed")).toBe("true")
+  })
+
+  it("déplie les ancêtres d'un span choisi depuis une ligne de log", () => {
+    render(
+      <SpanWaterfall
+        spans={SPANS}
+        defaultCollapsedDepth={0}
+        logs={[{ timestamp: new Date(20).toISOString(), body: "creating container", spanId: "leaf" }]}
+      />
+    )
+    expect(screen.queryByText("docker.create")).toBeNull()
+    fireEvent.click(screen.getByText("creating container"))
+    expect(screen.getAllByText("docker.create").length).toBeGreaterThan(0)
+    expect(screen.getByText("agent.cmd spawn")).toBeTruthy()
+  })
+
+  it("se laisse contrôler", () => {
+    let last: string[] = []
+    render(<SpanWaterfall spans={SPANS} collapsedSpanIds={["root"]} onCollapsedSpanIdsChange={(ids) => (last = ids)} />)
+    expect(screen.queryByText("agent.cmd spawn")).toBeNull()
+    fireEvent.click(screen.getByLabelText("Expand GET /api/x"))
+    expect(last).toEqual([])
+    // Contrôlé : tant que le parent ne change pas la prop, rien ne bouge.
+    expect(screen.queryByText("agent.cmd spawn")).toBeNull()
+  })
+})