{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "timeline-reasoning-rail",
  "title": "Timeline Reasoning Rail",
  "description": "Collapsible agent-reasoning timeline: status lives entirely in the node glyph on a 1px vertical rail, steps stream in over time, and completed steps fold to a single line so a long run stays readable.",
  "dependencies": [],
  "files": [
    {
      "path": "registry/core/timeline-reasoning-rail/component.tsx",
      "content": "\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\n\n// A collapsible agent-reasoning timeline. Status lives entirely in the node\n// glyph strung on a 1px vertical rail — no colored badges, no status pills:\n// a hollow ring is pending, a half-filled disc is running, a filled dot is\n// done, and a stroked diamond with a cross is failed (a distinct FORM, not a\n// color — --ns-accent stays reserved for the fold affordance and focus rings).\n// Steps stream in over time as the `steps` array grows; the currently\n// running step (or, once nothing is running, the most recent step) stays\n// expanded by default while every earlier step folds to a single line, so a\n// 40-step run reads as a scrollable log rather than a wall of open text.\n// Any step can be expanded or re-collapsed by hand — that choice is kept\n// per step id even as new steps arrive. New arrivals and status changes are\n// announced through a polite (not assertive) visually-hidden live region.\n// Pure DOM: the fold uses a CSS grid-rows transition (no JS height\n// measuring), the running glyph uses Tailwind's built-in ping keyframes.\n// Zero dependencies.\n\nexport type SoundingRailStatus = \"pending\" | \"running\" | \"done\" | \"failed\";\n\nexport interface SoundingRailEvidence {\n  /** short field name, e.g. \"tool\" or \"files\" */\n  label: string;\n  value: string;\n}\n\nexport interface SoundingRailStep {\n  /** stable id — used for the expand/collapse memory and the aria-live diff */\n  id: string;\n  label: string;\n  status: SoundingRailStatus;\n  /** short elapsed/absolute stamp shown beside the label, e.g. \"0:14\" */\n  time?: string;\n  /** longer explanation, only rendered once the step is expanded */\n  detail?: string;\n  /** flat bordered chips of tool output, only rendered once expanded */\n  evidence?: SoundingRailEvidence[];\n}\n\nexport interface SoundingRailProps {\n  /** the run, oldest first — append to stream new steps in */\n  steps: SoundingRailStep[];\n  /** accessible name for the timeline region */\n  label?: string;\n  /** extra classes merged onto the rendered root element */\n  className?: string;\n}\n\nfunction statusWord(status: SoundingRailStatus) {\n  switch (status) {\n    case \"pending\":\n      return \"pending\";\n    case \"running\":\n      return \"running\";\n    case \"done\":\n      return \"done\";\n    case \"failed\":\n      return \"failed\";\n  }\n}\n\nfunction StepGlyph({ status }: { status: SoundingRailStatus }) {\n  if (status === \"pending\") {\n    return (\n      <svg width=\"10\" height=\"10\" viewBox=\"0 0 10 10\" aria-hidden=\"true\">\n        <circle\n          cx=\"5\"\n          cy=\"5\"\n          r=\"3.25\"\n          fill=\"var(--surface)\"\n          stroke=\"var(--border)\"\n          strokeWidth=\"1.5\"\n        />\n      </svg>\n    );\n  }\n  if (status === \"running\") {\n    return (\n      // Running needs a resting FORM, not only a resting animation. The ping\n      // halo spends most of its cycle fully transparent, so a bare dot inside\n      // it screenshots as — and, glanced at, reads as — the plain solid dot\n      // that means \"done\". The resting signal is a HALF-FILLED disc (a 50%\n      // pie): a full --foreground ring with one half painted solid. It reads\n      // as \"in progress\" at any scale and is unmistakable against pending's\n      // empty ring, done's fully solid dot, and failed's crossed diamond,\n      // whether or not the ping halo happens to be mid-cycle.\n      <span className=\"relative inline-flex h-[10px] w-[10px] items-center justify-center\">\n        <span\n          aria-hidden=\"true\"\n          className=\"absolute inline-flex h-full w-full rounded-full border border-foreground/50 motion-safe:animate-ping\"\n        />\n        <svg\n          width=\"10\"\n          height=\"10\"\n          viewBox=\"0 0 10 10\"\n          aria-hidden=\"true\"\n          className=\"relative\"\n        >\n          <circle\n            cx=\"5\"\n            cy=\"5\"\n            r=\"4\"\n            fill=\"var(--surface)\"\n            stroke=\"var(--foreground)\"\n            strokeWidth=\"1.3\"\n          />\n          <path d=\"M5 1 A4 4 0 0 1 5 9 Z\" fill=\"var(--foreground)\" />\n        </svg>\n      </span>\n    );\n  }\n  if (status === \"failed\") {\n    return (\n      <svg width=\"10\" height=\"10\" viewBox=\"0 0 10 10\" aria-hidden=\"true\">\n        <rect\n          x=\"1.4\"\n          y=\"1.4\"\n          width=\"7.2\"\n          height=\"7.2\"\n          rx=\"1\"\n          transform=\"rotate(45 5 5)\"\n          fill=\"var(--surface)\"\n          stroke=\"var(--foreground)\"\n          strokeWidth=\"1.3\"\n        />\n        <path\n          d=\"M3.3 3.3l3.4 3.4M6.7 3.3l-3.4 3.4\"\n          stroke=\"var(--foreground)\"\n          strokeWidth=\"1.1\"\n          strokeLinecap=\"round\"\n        />\n      </svg>\n    );\n  }\n  // done\n  return (\n    <svg width=\"10\" height=\"10\" viewBox=\"0 0 10 10\" aria-hidden=\"true\">\n      <circle cx=\"5\" cy=\"5\" r=\"4\" fill=\"var(--foreground)\" />\n    </svg>\n  );\n}\n\nexport function SoundingRail({\n  steps,\n  label = \"Agent reasoning timeline\",\n  className = \"\",\n}: SoundingRailProps) {\n  // per-id manual expand/collapse override — survives new steps streaming in\n  const [overrides, setOverrides] = useState<Record<string, boolean>>({});\n  const [live, setLive] = useState(\"\");\n  const prevRef = useRef<Map<string, SoundingRailStatus>>(new Map());\n  const scrollRef = useRef<HTMLOListElement>(null);\n  const firstRun = useRef(true);\n\n  // the step that should be open with nothing asked of the user: the\n  // running one, or — once the run has nothing in flight — the last step\n  let autoId: string | null = null;\n  for (let i = steps.length - 1; i >= 0; i--) {\n    const s = steps[i];\n    if (s && s.status === \"running\") {\n      autoId = s.id;\n      break;\n    }\n  }\n  if (autoId === null && steps.length > 0) {\n    autoId = steps[steps.length - 1]!.id;\n  }\n\n  // announce arrivals and status flips politely, diffed against last render\n  useEffect(() => {\n    const prev = prevRef.current;\n    const next = new Map<string, SoundingRailStatus>();\n    const messages: string[] = [];\n    for (const s of steps) {\n      next.set(s.id, s.status);\n      const before = prev.get(s.id);\n      if (before === undefined) {\n        messages.push(\n          s.status === \"pending\" ? `Queued: ${s.label}` : s.label\n        );\n      } else if (before !== s.status) {\n        messages.push(`${s.label} ${statusWord(s.status)}`);\n      }\n    }\n    prevRef.current = next;\n    if (!firstRun.current && messages.length > 0) {\n      setLive(messages.join(\". \"));\n    }\n    firstRun.current = false;\n  }, [steps]);\n\n  // keep the current step in view as the run streams — only on new/changed\n  // steps, never on a manual expand/collapse, so exploring history doesn't\n  // get yanked back down\n  useEffect(() => {\n    const el = scrollRef.current;\n    if (!el) return;\n    const reduced = window.matchMedia(\n      \"(prefers-reduced-motion: reduce)\"\n    ).matches;\n    el.scrollTo({ top: el.scrollHeight, behavior: reduced ? \"auto\" : \"smooth\" });\n  }, [steps]);\n\n  return (\n    <div\n      role=\"region\"\n      aria-label={label}\n      className={`rounded-md border border-border bg-surface ${className}`}\n    >\n      <ol ref={scrollRef} className=\"max-h-[420px] overflow-y-auto p-4\">\n        {steps.map((step, i) => {\n          const expanded = overrides[step.id] ?? step.id === autoId;\n          const hasDetail = Boolean(\n            step.detail || (step.evidence && step.evidence.length > 0)\n          );\n          const detailId = `timeline-reasoning-rail-detail-${step.id}`;\n          const toggle = () =>\n            setOverrides((o) => ({ ...o, [step.id]: !expanded }));\n\n          return (\n            <li key={step.id} className=\"relative flex\">\n              {/* rail: a single continuous line, the glyph rides on top */}\n              <div className=\"relative mr-3 flex w-4 shrink-0 justify-center\">\n                {i > 0 && (\n                  <span className=\"absolute left-1/2 top-0 h-[7px] w-px -translate-x-1/2 bg-border\" />\n                )}\n                {i < steps.length - 1 && (\n                  <span className=\"absolute left-1/2 top-[17px] bottom-0 w-px -translate-x-1/2 bg-border\" />\n                )}\n                <span className=\"relative z-10 mt-[7px]\">\n                  <StepGlyph status={step.status} />\n                </span>\n              </div>\n\n              <div className=\"min-w-0 flex-1 pb-4 last:pb-0\">\n                {hasDetail ? (\n                  <button\n                    type=\"button\"\n                    onClick={toggle}\n                    aria-expanded={expanded}\n                    aria-controls={detailId}\n                    aria-label={`${expanded ? \"Collapse\" : \"Expand\"} ${step.label}`}\n                    className=\"group -mx-1 flex min-h-6 w-full items-center gap-2 rounded-sm px-1 text-left outline-none transition-colors duration-150 hover:bg-foreground/[0.04] focus-visible:ring-2 focus-visible:ring-ns-accent focus-visible:ring-offset-2 focus-visible:ring-offset-surface motion-reduce:transition-none\"\n                  >\n                    <span className=\"min-w-0 flex-1 truncate text-sm text-foreground\">\n                      {step.label}\n                    </span>\n                    {step.time ? (\n                      <span className=\"shrink-0 font-mono text-[10px] text-ns-muted\">\n                        {step.time}\n                      </span>\n                    ) : null}\n                    <svg\n                      width=\"10\"\n                      height=\"10\"\n                      viewBox=\"0 0 10 10\"\n                      aria-hidden=\"true\"\n                      className={`shrink-0 text-ns-muted transition-transform duration-200 motion-reduce:transition-none ${\n                        expanded ? \"rotate-90\" : \"\"\n                      } group-hover:text-foreground`}\n                    >\n                      <path\n                        d=\"M3 1.5l4 3.5-4 3.5\"\n                        fill=\"none\"\n                        stroke=\"currentColor\"\n                        strokeWidth=\"1.4\"\n                        strokeLinecap=\"round\"\n                        strokeLinejoin=\"round\"\n                      />\n                    </svg>\n                  </button>\n                ) : (\n                  <div className=\"flex min-h-6 w-full items-center gap-2\">\n                    <span className=\"min-w-0 flex-1 truncate text-sm text-foreground\">\n                      {step.label}\n                    </span>\n                    {step.time ? (\n                      <span className=\"shrink-0 font-mono text-[10px] text-ns-muted\">\n                        {step.time}\n                      </span>\n                    ) : null}\n                  </div>\n                )}\n\n                {hasDetail ? (\n                  <div\n                    className=\"grid transition-[grid-template-rows] duration-300 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none motion-reduce:duration-0\"\n                    style={{ gridTemplateRows: expanded ? \"1fr\" : \"0fr\" }}\n                  >\n                    <div className=\"overflow-hidden\">\n                      <div id={detailId} className=\"pt-1.5\">\n                        {step.detail ? (\n                          <p className=\"max-w-[60ch] text-sm leading-relaxed text-ns-muted\">\n                            {step.detail}\n                          </p>\n                        ) : null}\n                        {step.evidence && step.evidence.length > 0 ? (\n                          <div className=\"mt-2 flex flex-wrap gap-1.5\">\n                            {step.evidence.map((e, ei) => (\n                              <span\n                                key={ei}\n                                className=\"inline-flex items-center gap-1 rounded-sm border border-border bg-background px-1.5 py-0.5 font-mono text-[11px] text-ns-muted\"\n                              >\n                                <span className=\"text-foreground\">\n                                  {e.label}\n                                </span>\n                                <span aria-hidden=\"true\">·</span>\n                                <span>{e.value}</span>\n                              </span>\n                            ))}\n                          </div>\n                        ) : null}\n                      </div>\n                    </div>\n                  </div>\n                ) : null}\n              </div>\n            </li>\n          );\n        })}\n      </ol>\n\n      <div aria-live=\"polite\" aria-atomic=\"true\" className=\"sr-only\">\n        {live}\n      </div>\n    </div>\n  );\n}\n",
      "type": "registry:ui",
      "target": "components/ui/timeline-reasoning-rail.tsx"
    }
  ],
  "cssVars": {
    "theme": {
      "color-ns-muted": "var(--ns-muted)",
      "color-ns-accent": "var(--ns-accent)",
      "color-surface": "var(--surface)"
    },
    "light": {
      "ns-muted": "#4d4d4d",
      "ns-accent": "#006bff",
      "surface": "#fafafa"
    },
    "dark": {
      "ns-muted": "#8f8f8f",
      "surface": "#171717"
    }
  },
  "meta": {
    "collection": "core",
    "tags": [
      "timeline",
      "stepper",
      "agent",
      "log",
      "disclosure",
      "accordion",
      "streaming",
      "accessibility"
    ],
    "instruction": "Build a collapsible agent-reasoning timeline for streaming, open-ended step lists (not a fixed known-step wizard — see stepper-needle's spinbutton and any fixed-step form stepper for that case; this one has no notion of a total step count and steps arrive one at a time). DATA: the consumer owns a `steps` array (oldest first) they append to and mutate in place over time — each step is {id, label, status: pending|running|done|failed, time?, detail?, evidence?: {label,value}[]}; the component holds no timer or generation logic of its own, only fold/expand and announcement state. RENDER: a self-contained rounded-md border-border bg-surface panel around a role=region (aria-label from the `label` prop) scrollable ol (max-h-[420px] overflow-y-auto) so a 40-step run reads as a compact scrollable log, not a wall — every row folds to a single flex line (glyph + truncated label + optional mono time stamp + chevron) once its step is no longer the active one. STATUS GLYPH — the ONLY place status appears, no colored badges or pills anywhere: pending is a hollow ring (stroke --border, fill --surface), running is a HALF-FILLED disc — a full --foreground ring (fill --surface) with exactly one half painted solid --foreground, i.e. a 50% pie — with a motion-safe Tailwind `animate-ping` halo layered over it; the half-filled form is deliberately the resting signal, because the ping halo is fully transparent for most of its cycle and a bare dot inside it is indistinguishable from done's solid dot in any still frame, whereas a half-filled disc reads as 'in progress' at any scale, done is a solid 8px --foreground dot, failed is a distinct FORM — a stroked --foreground diamond (rotated square) with a crossing X, deliberately shaped rather than colored so the failure reads even in grayscale. Glyphs sit on a continuous 1px --border rail drawn per-row as two absolutely centered segments (above and below the glyph, skipped for the first/last row) so the connector reads as one unbroken line threaded through every node. FOLD LOGIC: the step currently running is expanded by default; once nothing is running, the most recently arrived step stays expanded — that is 'the current step is what you should see, with history collapsed above it'. Every other step folds. Clicking a folded row's header (the whole header is the hit target, not just the chevron) expands it and that per-id choice is kept in a Record<id,boolean> override that survives new steps streaming in, so a user reviewing history doesn't get overridden by the next arrival; folding a currently-auto-expanded step likewise sticks. Steps with neither `detail` nor `evidence` render as a plain non-interactive line (nothing to disclose, so no button is rendered for them — an inert row is not a broken control). EXPAND ANIMATION: pure CSS grid-template-rows 0fr/1fr transition (300ms, cubic-bezier(0.22,1,0.36,1)) on a wrapper around an overflow-hidden div — no JS height measurement, no layout thrash; the chevron rotates 90deg over 200ms in sync. DETAIL: a max-w-[60ch] text-sm text-ns-muted paragraph plus, if present, evidence rendered as flat bordered chips (rounded-sm border-border bg-background font-mono text-[11px], label in --foreground, value in --ns-muted, separated by a middot) — never colored badges, evidence is data, not a verdict. STREAMING + A11Y: a diff effect compares the previous `steps` array to the next by id, emitting one polite (never assertive — aria-live=polite, aria-atomic=true, visually-hidden) announcement per arrival (\"Queued: <label>\" for a step arriving pending, else the bare label) and per status flip (\"<label> running/done/failed\"), joined into a single live-region update per render so a burst of simultaneous changes announces once; a companion effect scrolls the ol to bottom on every `steps` change (instant under prefers-reduced-motion, smooth otherwise) so the newest arrival stays in view, but NEVER fires on a manual expand/collapse — exploring folded history must not get yanked back down. KEYBOARD/A11Y: every fold toggle is a real <button aria-expanded aria-controls> with an accessible name (\"Expand/Collapse <label>\"), reachable and operable by Tab/Enter/Space with no custom key handling needed; focus-visible ring is --ns-accent, --ns-accent's only appearance in the whole component. REDUCED MOTION: the grid-rows transition and chevron rotation both go to duration 0 (still expands/collapses, just instantly) and the running glyph's ping halo is dropped, leaving the half-filled disc that already carries the meaning — every state stays fully legible and operable, nothing is hidden. Zero dependencies, pure DOM + SVG + CSS, no canvas."
  },
  "type": "registry:ui"
}