@nwire/studio 0.12.1 → 0.13.1

package/src/components/RcaPanel.vue

@@ -0,0 +1,223 @@
+<script setup lang="ts">
+/**
+ * `RcaPanel` — the root-cause workbench for one incident. Four tabs:
+ *
+ *   • What happened — the friendly title/summary + the suggested fix, the
+ *     failing unit, its source, and the retry/dead-letter state.
+ *   • Timeline     — every record on the chain in order, with ms offsets and
+ *     failures flagged, so you see the cascade that led to the root cause.
+ *   • Impact       — the blast radius: tenant, user, apps, records, retries.
+ *   • Evidence     — the raw error (message + stack) and a flat, copyable
+ *     inspector over the root record (envelope + payload).
+ *
+ * Data comes pre-shaped from `lib/rca` (incident, timeline, impact); this is a
+ * presentational shell. The source pill emits up so the page opens the drawer.
+ */
+import { computed, ref } from "vue";
+import { Wrench, ListTree, Radius, FileSearch, Lightbulb } from "lucide-vue-next";
+import type { Incident } from "@/lib/rca";
+import { buildTimeline, computeImpact } from "@/lib/rca";
+import { kindColor, recordColorKey } from "@/lib/kind-colors";
+import { retryNarrative } from "@/lib/error-friendly";
+import MetadataInspector from "./MetadataInspector.vue";
+import SourcePill from "./SourcePill.vue";
+import KindBadge from "./KindBadge.vue";
+
+const props = defineProps<{
+  incident: Incident;
+  /** Source location of the failing unit, resolved from the manifest. */
+  source?: { file: string; line?: number; column?: number };
+}>();
+
+const emit = defineEmits<{
+  (e: "open-source", source: { file: string; line?: number; column?: number }): void;
+}>();
+
+type Tab = "what" | "timeline" | "impact" | "evidence";
+const tab = ref<Tab>("what");
+const tabs: { id: Tab; label: string; icon: typeof Wrench }[] = [
+  { id: "what", label: "What happened", icon: Wrench },
+  { id: "timeline", label: "Timeline", icon: ListTree },
+  { id: "impact", label: "Impact", icon: Radius },
+  { id: "evidence", label: "Evidence", icon: FileSearch },
+];
+
+const friendly = computed(() => props.incident.friendly);
+const timeline = computed(() => buildTimeline(props.incident));
+const impact = computed(() => computeImpact(props.incident));
+const retry = computed(() => retryNarrative(props.incident.root));
+// The terminal record (dead-letter) often drops the stack; prefer whichever
+// failure on the chain carries one, falling back to the headline error.
+const rootError = computed(
+  () => props.incident.failures.find((f) => f.error?.stack)?.error ?? props.incident.root.error,
+);
+
+function recordLabel(r: Record<string, unknown>): string {
+  return (
+    (r.action as string) ??
+    (r.projection as string) ??
+    (r.workflow as string) ??
+    (r.call as string) ??
+    (r.query as string) ??
+    (r.sourceEvent as string) ??
+    (r.event as string) ??
+    ""
+  );
+}
+
+function fmtOffset(ms?: number): string {
+  if (ms === undefined) return "";
+  if (ms < 1000) return `+${ms}ms`;
+  return `+${(ms / 1000).toFixed(2)}s`;
+}
+</script>
+
+<template>
+  <div class="flex flex-col h-full min-h-0" data-testid="rca-panel">
+    <!-- tabs -->
+    <div class="flex border-b border-zinc-800 shrink-0">
+      <button
+        v-for="t in tabs"
+        :key="t.id"
+        class="flex items-center gap-1.5 px-3 py-2.5 text-xs border-b-2 -mb-px transition-colors"
+        :class="
+          tab === t.id
+            ? 'border-orange-400 text-zinc-100'
+            : 'border-transparent text-zinc-500 hover:text-zinc-300'
+        "
+        :data-testid="`rca-tab-${t.id}`"
+        @click="tab = t.id"
+      >
+        <component :is="t.icon" class="w-3.5 h-3.5" />
+        {{ t.label }}
+      </button>
+    </div>
+
+    <div class="flex-1 overflow-auto min-h-0">
+      <!-- ── What happened ──────────────────────────────────────────── -->
+      <section v-if="tab === 'what'" class="p-4 space-y-4" data-testid="rca-what">
+        <div>
+          <h3 class="text-base font-medium text-zinc-100">{{ friendly.title }}</h3>
+          <p class="mt-1 text-sm text-zinc-400 leading-relaxed">{{ friendly.summary }}</p>
+        </div>
+
+        <div
+          class="flex items-start gap-2.5 rounded-lg border border-emerald-900/50 bg-emerald-950/20 p-3"
+          data-testid="rca-suggestion"
+        >
+          <Lightbulb class="w-4 h-4 mt-0.5 shrink-0 text-emerald-400" />
+          <p class="text-xs text-emerald-200/90 leading-relaxed">{{ friendly.suggestion }}</p>
+        </div>
+
+        <dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2 text-xs">
+          <dt class="text-zinc-500">Failing unit</dt>
+          <dd class="flex items-center gap-2 min-w-0">
+            <KindBadge variant="neutral">{{ friendly.subject.kind }}</KindBadge>
+            <span class="font-mono text-zinc-300 truncate">{{ friendly.subject.name }}</span>
+          </dd>
+
+          <template v-if="retry">
+            <dt class="text-zinc-500">Retries</dt>
+            <dd class="text-zinc-300">{{ retry }}</dd>
+          </template>
+
+          <template v-if="source">
+            <dt class="text-zinc-500">Source</dt>
+            <dd>
+              <SourcePill :source="source" compact @click="emit('open-source', source!)" />
+            </dd>
+          </template>
+        </dl>
+      </section>
+
+      <!-- ── Timeline ───────────────────────────────────────────────── -->
+      <section v-else-if="tab === 'timeline'" class="p-3" data-testid="rca-timeline">
+        <ol class="relative">
+          <li
+            v-for="(entry, i) in timeline"
+            :key="i"
+            class="flex items-center gap-3 px-1 py-1.5 rounded"
+            :class="entry.failure ? 'bg-rose-950/20' : ''"
+            data-testid="rca-timeline-row"
+            :data-failure="entry.failure"
+          >
+            <span class="text-[10px] tabular-nums text-zinc-600 w-14 text-right shrink-0">
+              {{ fmtOffset(entry.offsetMs) }}
+            </span>
+            <span
+              class="w-2 h-2 rounded-full shrink-0"
+              :style="{ backgroundColor: kindColor(recordColorKey(entry.record.kind)) }"
+            />
+            <span class="text-xs text-zinc-300 font-mono shrink-0">{{ entry.record.kind }}</span>
+            <span class="text-xs text-zinc-500 truncate">{{ recordLabel(entry.record) }}</span>
+            <span
+              v-if="entry.record.durationMs !== undefined"
+              class="ml-auto text-[10px] tabular-nums text-zinc-600 shrink-0"
+            >
+              {{ (entry.record.durationMs as number).toFixed(1) }}ms
+            </span>
+          </li>
+        </ol>
+      </section>
+
+      <!-- ── Impact ─────────────────────────────────────────────────── -->
+      <section v-else-if="tab === 'impact'" class="p-4 space-y-4" data-testid="rca-impact">
+        <div class="grid grid-cols-2 gap-2">
+          <div class="rounded-lg border border-zinc-800 bg-zinc-950 px-3 py-2">
+            <div class="text-[10px] uppercase tracking-wide text-zinc-500">Records on chain</div>
+            <div class="text-xl font-semibold tabular-nums text-zinc-100">{{ impact.records }}</div>
+          </div>
+          <div class="rounded-lg border border-zinc-800 bg-zinc-950 px-3 py-2">
+            <div class="text-[10px] uppercase tracking-wide text-zinc-500">Failures</div>
+            <div class="text-xl font-semibold tabular-nums text-rose-300">
+              {{ impact.failures }}
+            </div>
+          </div>
+          <div class="rounded-lg border border-zinc-800 bg-zinc-950 px-3 py-2">
+            <div class="text-[10px] uppercase tracking-wide text-zinc-500">Retries</div>
+            <div class="text-xl font-semibold tabular-nums text-zinc-100">{{ impact.retries }}</div>
+          </div>
+          <div class="rounded-lg border border-zinc-800 bg-zinc-950 px-3 py-2">
+            <div class="text-[10px] uppercase tracking-wide text-zinc-500">Dead-lettered</div>
+            <div
+              class="text-xl font-semibold"
+              :class="impact.deadLettered ? 'text-rose-300' : 'text-emerald-300'"
+            >
+              {{ impact.deadLettered ? "Yes" : "No" }}
+            </div>
+          </div>
+        </div>
+
+        <dl class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2 text-xs">
+          <template v-if="impact.tenant">
+            <dt class="text-zinc-500">Tenant</dt>
+            <dd class="font-mono text-zinc-300">{{ impact.tenant }}</dd>
+          </template>
+          <template v-if="impact.userId">
+            <dt class="text-zinc-500">User</dt>
+            <dd class="font-mono text-zinc-300">{{ impact.userId }}</dd>
+          </template>
+          <dt class="text-zinc-500">Apps</dt>
+          <dd class="text-zinc-300">{{ impact.apps.length ? impact.apps.join(", ") : "—" }}</dd>
+        </dl>
+      </section>
+
+      <!-- ── Evidence ───────────────────────────────────────────────── -->
+      <section v-else class="flex flex-col min-h-0" data-testid="rca-evidence">
+        <div v-if="rootError" class="p-4 border-b border-zinc-800">
+          <div class="text-[10px] uppercase tracking-wide text-zinc-500 mb-1">Root error</div>
+          <div class="font-mono text-xs text-rose-300">
+            {{ rootError.name }}: {{ rootError.message }}
+          </div>
+          <pre
+            v-if="rootError.stack"
+            class="mt-2 text-[10px] text-zinc-500 whitespace-pre-wrap break-all max-h-40 overflow-auto"
+            data-testid="rca-stack"
+            >{{ rootError.stack }}</pre
+          >
+        </div>
+        <MetadataInspector :data="incident.root" label="Root record" class="flex-1 min-h-0" />
+      </section>
+    </div>
+  </div>
+</template>

package/src/components/ServiceNode.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+/**
+ * `ServiceNode` — one node on the Topology service map: a rounded service card
+ * with a kind icon, title, kind subtitle, a status dot, and a live metric row
+ * (throughput · errors · p50). Accent-coloured by kind. Before any run the
+ * metrics show a dim "—" (neutral placeholder, never a misleading zero); once
+ * telemetry flows they fill in and the status dot turns live/error.
+ *
+ * Pure presentational — it takes a resolved `ServiceNodeData` and the canvas
+ * decides selection + click. Used as a VueFlow custom node and standalone.
+ */
+import { computed } from "vue";
+import * as icons from "lucide-vue-next";
+import { kindColor, kindIcon } from "@/lib/kind-colors";
+import type { NodeMetrics } from "@/lib/node-metrics";
+import { fmtCount, fmtLatency } from "@/lib/node-metrics";
+
+const props = defineProps<{
+  id: string;
+  kind: string;
+  name: string;
+  /** Short kind subtitle (defaults to the kind). */
+  subtitle?: string;
+  public?: boolean;
+  selected?: boolean;
+  /** Live metrics, or undefined before any run (neutral placeholders). */
+  metrics?: NodeMetrics;
+}>();
+
+const color = computed(() => kindColor(props.kind));
+const IconComp = computed(
+  () => (icons as Record<string, unknown>)[kindIcon(props.kind)] ?? icons.Circle,
+);
+
+/** Status: error if any failures, live if any throughput, else idle. */
+const status = computed<"idle" | "live" | "error">(() => {
+  const m = props.metrics;
+  if (!m || m.count === 0) return "idle";
+  return m.errors > 0 ? "error" : "live";
+});
+
+const statusDot = computed(
+  () =>
+    ({
+      idle: "bg-zinc-600",
+      live: "bg-emerald-400",
+      error: "bg-rose-400",
+    })[status.value],
+);
+
+/** Strip the `${app}.` head so the title reads short inside its card. */
+const title = computed(() => {
+  const dot = props.name.indexOf(".");
+  return dot > 0 ? props.name.slice(dot + 1) : props.name;
+});
+</script>
+
+<template>
+  <div
+    class="group relative w-full rounded-xl border bg-zinc-900/95 px-3 py-2.5 shadow-sm transition-all cursor-pointer backdrop-blur"
+    :class="
+      selected
+        ? 'border-transparent ring-2 shadow-lg'
+        : 'border-zinc-800 hover:border-zinc-700 hover:shadow-md'
+    "
+    :style="selected ? { '--tw-ring-color': color } : undefined"
+    :data-testid="`service-node-${id}`"
+  >
+    <!-- accent rail -->
+    <span
+      class="absolute left-0 top-2 bottom-2 w-1 rounded-full"
+      :style="{ background: color }"
+      aria-hidden="true"
+    />
+
+    <!-- header: icon + title + status -->
+    <div class="flex items-center gap-2 pl-1.5">
+      <span
+        class="grid h-7 w-7 shrink-0 place-items-center rounded-lg"
+        :style="{ background: `${color}1f`, color }"
+      >
+        <component :is="IconComp" class="h-4 w-4" />
+      </span>
+      <div class="min-w-0 flex-1">
+        <div class="flex items-center gap-1.5">
+          <span class="truncate font-medium text-[13px] text-zinc-100" :title="name">{{
+            title
+          }}</span>
+          <span
+            v-if="public"
+            class="rounded bg-emerald-500/15 px-1 text-[8px] font-semibold uppercase tracking-wide text-emerald-300"
+            data-testid="service-node-public"
+            >pub</span
+          >
+        </div>
+        <div class="text-[10px] uppercase tracking-wide text-zinc-500">{{ subtitle ?? kind }}</div>
+      </div>
+      <span
+        class="h-2 w-2 shrink-0 rounded-full"
+        :class="[statusDot, status === 'live' ? 'animate-pulse' : '']"
+        :data-status="status"
+        :data-testid="`service-node-status-${id}`"
+      />
+    </div>
+
+    <!-- metric row -->
+    <div
+      class="mt-2 grid grid-cols-3 gap-1 border-t border-zinc-800/70 pt-1.5 pl-1.5"
+      data-testid="service-node-metrics"
+    >
+      <div class="flex flex-col">
+        <span class="font-mono text-[12px] tabular-nums text-zinc-200" data-testid="metric-count">{{
+          fmtCount(metrics?.count)
+        }}</span>
+        <span class="text-[8px] uppercase tracking-wide text-zinc-600">runs</span>
+      </div>
+      <div class="flex flex-col">
+        <span
+          class="font-mono text-[12px] tabular-nums"
+          :class="metrics && metrics.errors > 0 ? 'text-rose-300' : 'text-zinc-200'"
+          data-testid="metric-errors"
+          >{{ fmtCount(metrics?.errors) }}</span
+        >
+        <span class="text-[8px] uppercase tracking-wide text-zinc-600">errors</span>
+      </div>
+      <div class="flex flex-col">
+        <span class="font-mono text-[12px] tabular-nums text-zinc-200" data-testid="metric-p50">{{
+          fmtLatency(metrics?.p50)
+        }}</span>
+        <span class="text-[8px] uppercase tracking-wide text-zinc-600">p50</span>
+      </div>
+    </div>
+  </div>
+</template>

package/src/components/SourceDrawer.vue

@@ -17,7 +17,7 @@ import MonacoViewer from "./MonacoViewer.vue";
 import SourcePill from "./SourcePill.vue";
 
 const props = defineProps<{
-  source?: { file: string; line: number; column?: number } | null;
+  source?: { file: string; line?: number; column?: number } | null;
 }>();
 
 const emit = defineEmits<{ (e: "close"): void }>();
@@ -43,10 +43,12 @@ const ideHref = computed(() => {
   if (!props.source) return undefined;
   const { file, line, column } = props.source;
   const prefix = idePrefix();
+  const lineSuffix = line !== undefined ? `:${line}` : "";
   if (prefix.includes("?path=")) {
-    return `${prefix}${encodeURIComponent(file)}:${line}`;
+    return `${prefix}${encodeURIComponent(file)}${lineSuffix}`;
   }
-  return `${prefix}${file}:${line}${column ? `:${column}` : ""}`;
+  const colSuffix = line !== undefined && column ? `:${column}` : "";
+  return `${prefix}${file}${lineSuffix}${colSuffix}`;
 });
 
 const content = ref<string>("");
@@ -137,7 +139,7 @@ watch(
               The file is outside the Studio process's working directory, or the path doesn't exist
               on this machine. Try the
               <a
-                :href="`vscode://file${source.file}:${source.line}`"
+                :href="`vscode://file${source.file}${source.line !== undefined ? `:${source.line}` : ''}`"
                 class="text-orange-400 underline"
               >
                 IDE link

package/src/components/SourcePill.vue

@@ -14,7 +14,7 @@ import { Copy, Check } from "lucide-vue-next";
 import { useCopy } from "../composables/useCopy";
 
 const props = defineProps<{
-  source?: { file: string; line: number; column?: number };
+  source?: { file: string; line?: number; column?: number };
   /** Compact mode — no label, just the path:line. Default false. */
   compact?: boolean;
 }>();
@@ -31,7 +31,10 @@ const fileSegment = computed(() => {
 
 const copyText = computed(() => {
   if (!props.source) return "";
-  return `${props.source.file}:${props.source.line}${props.source.column ? `:${props.source.column}` : ""}`;
+  const line = props.source.line !== undefined ? `:${props.source.line}` : "";
+  const col =
+    props.source.line !== undefined && props.source.column ? `:${props.source.column}` : "";
+  return `${props.source.file}${line}${col}`;
 });
 
 const onCopy = (e: Event) => {
@@ -47,6 +50,7 @@ const onCopy = (e: Event) => {
     type="button"
     class="inline-flex items-center gap-1.5 rounded-md border border-zinc-800 bg-zinc-900/50 px-2 py-1 text-xs font-mono text-zinc-400 hover:border-zinc-700 hover:text-zinc-100 hover:bg-zinc-900 transition-colors"
     :title="`Open ${copyText} in Studio's source panel`"
+    data-testid="source-pill"
     @click="$emit('click')"
   >
     <span
@@ -55,7 +59,10 @@ const onCopy = (e: Event) => {
     >
       source
     </span>
-    <span>{{ fileSegment }}:{{ source.line }}</span>
+    <span
+      >{{ fileSegment
+      }}<template v-if="source.line !== undefined">:{{ source.line }}</template></span
+    >
     <span
       :title="copied ? 'Copied!' : `Copy ${copyText}`"
       class="ml-1 inline-flex items-center text-zinc-500 hover:text-zinc-300"

package/src/components/StatusBadge.stories.ts

@@ -0,0 +1,33 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+import StatusBadge from "./StatusBadge.vue";
+
+const meta: Meta<typeof StatusBadge> = {
+  title: "Map/StatusBadge",
+  component: StatusBadge,
+  tags: ["autodocs"],
+  argTypes: {
+    status: { control: { type: "select" }, options: ["ok", "warn", "error", "idle", "live"] },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof StatusBadge>;
+
+export const Default: Story = {
+  args: { status: "ok", label: "Healthy" },
+};
+
+export const All: Story = {
+  render: () => ({
+    components: { StatusBadge },
+    template: `
+      <div class="flex flex-col gap-2 bg-zinc-900 p-4">
+        <StatusBadge status="ok" label="Healthy" />
+        <StatusBadge status="live" label="Streaming" pulse />
+        <StatusBadge status="warn" label="Degraded" />
+        <StatusBadge status="error" label="Unreachable" />
+        <StatusBadge status="idle" label="Idle" />
+      </div>
+    `,
+  }),
+};

package/src/components/StatusBadge.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+/**
+ * `StatusBadge` — a coloured dot + label for a health/liveness state.
+ * `pulse` animates the dot (use for "live"/streaming states). Kept tiny and
+ * presentational so Map, Streams and Errors all read status the same way.
+ */
+import { computed } from "vue";
+
+const props = withDefaults(
+  defineProps<{
+    status: "ok" | "warn" | "error" | "idle" | "live";
+    label?: string;
+    pulse?: boolean;
+  }>(),
+  { label: undefined, pulse: false },
+);
+
+const dot = computed(
+  () =>
+    ({
+      ok: "bg-emerald-400",
+      live: "bg-emerald-400",
+      warn: "bg-amber-400",
+      error: "bg-rose-400",
+      idle: "bg-zinc-600",
+    })[props.status],
+);
+
+const text = computed(
+  () =>
+    ({
+      ok: "text-emerald-300",
+      live: "text-emerald-300",
+      warn: "text-amber-300",
+      error: "text-rose-300",
+      idle: "text-zinc-500",
+    })[props.status],
+);
+</script>
+
+<template>
+  <span class="inline-flex items-center gap-1.5 text-xs" :class="text" data-testid="status-badge">
+    <span class="relative flex h-2 w-2">
+      <span
+        v-if="pulse"
+        class="absolute inline-flex h-full w-full rounded-full opacity-60 animate-ping"
+        :class="dot"
+        data-testid="status-pulse"
+      />
+      <span class="relative inline-flex h-2 w-2 rounded-full" :class="dot" />
+    </span>
+    <span v-if="label">{{ label }}</span>
+  </span>
+</template>

package/src/components/Waterfall.stories.ts

@@ -0,0 +1,85 @@
+import type { Meta, StoryObj } from "@storybook/vue3-vite";
+import { expect, userEvent, within } from "storybook/test";
+import Waterfall from "./Waterfall.vue";
+import type { TelemetryRecord, TraceNode } from "@/lib/telemetry";
+
+const env = (messageId: string, causationId: string) => ({
+  messageId,
+  causationId,
+  correlationId: "c-9f8e",
+});
+const t = (ms: number) => new Date(Date.UTC(2026, 0, 1, 0, 0, 0, ms)).toISOString();
+function node(record: TelemetryRecord, children: TraceNode[] = []): TraceNode {
+  return { record, children };
+}
+
+const forest: TraceNode[] = [
+  node(
+    {
+      kind: "action.dispatched",
+      name: "orders.place",
+      ts: t(0),
+      durationMs: 8,
+      envelope: env("m1", "m1"),
+    },
+    [
+      node(
+        {
+          kind: "query.executed",
+          name: "orders.lookup",
+          ts: t(8),
+          durationMs: 120,
+          envelope: env("m2", "m1"),
+        },
+        [
+          node({
+            kind: "event.published",
+            name: "orders.looked-up",
+            ts: t(128),
+            durationMs: 2,
+            envelope: env("m4", "m2"),
+          }),
+        ],
+      ),
+      node({
+        kind: "action.failed",
+        name: "orders.charge",
+        ts: t(10),
+        durationMs: 40,
+        error: { name: "E", message: "declined" },
+        envelope: env("m3", "m1"),
+      }),
+    ],
+  ),
+];
+
+const meta: Meta<typeof Waterfall> = {
+  title: "Flow/Waterfall",
+  component: Waterfall,
+  tags: ["autodocs"],
+  render: (args) => ({
+    components: { Waterfall },
+    setup: () => ({ args }),
+    template: `<div class="bg-zinc-950 w-[640px]"><Waterfall v-bind="args" /></div>`,
+  }),
+};
+export default meta;
+
+type Story = StoryObj<typeof Waterfall>;
+
+export const Default: Story = {
+  args: { forest },
+  play: async ({ canvasElement }) => {
+    const c = within(canvasElement);
+    await expect(c.getAllByTestId("waterfall-row")).toHaveLength(4);
+    // The failed span is present and the critical path is highlighted.
+    await expect(canvasElement.querySelector('[data-failed="true"]')).toBeTruthy();
+    await expect(canvasElement.querySelector('[data-critical="true"]')).toBeTruthy();
+    // Clicking a row selects it.
+    await userEvent.click(c.getAllByTestId("waterfall-row")[1]!);
+  },
+};
+
+export const Replaying: Story = {
+  args: { forest, reveal: 2 },
+};

package/src/components/Waterfall.vue

@@ -0,0 +1,53 @@
+<script setup lang="ts">
+/**
+ * `Waterfall` — renders a causation forest as a time-positioned waterfall:
+ * a span-relative axis on top, then one `WaterfallRow` per node (depth-indented,
+ * critical path highlighted, failures red). Layout geometry comes from
+ * `buildWaterfall`; this component is the chrome + selection wiring + an
+ * optional replay cursor (`reveal`) that dims rows past the cursor.
+ *
+ *   <Waterfall :forest="forest" :selected-key="key" @select="..." />
+ */
+import { computed } from "vue";
+import { buildWaterfall, type WaterfallRow } from "@/lib/waterfall";
+import type { TraceNode } from "@/lib/telemetry";
+import WaterfallRowItem from "./WaterfallRow.vue";
+
+const props = withDefaults(
+  defineProps<{
+    forest: readonly TraceNode[];
+    /** `key` of the selected row. */
+    selectedKey?: string;
+    /** Replay cursor — rows from this index on are dimmed. Default: all shown. */
+    reveal?: number;
+  }>(),
+  { selectedKey: undefined, reveal: undefined },
+);
+
+const emit = defineEmits<{ (e: "select", row: WaterfallRow): void }>();
+
+const layout = computed(() => buildWaterfall(props.forest));
+const revealCount = computed(() => props.reveal ?? layout.value.rows.length);
+</script>
+
+<template>
+  <div class="flex flex-col min-h-0" data-testid="waterfall">
+    <!-- Axis: 0 → total span -->
+    <div class="flex items-center text-[10px] text-zinc-600 px-2 pb-1 border-b border-zinc-800/70">
+      <span class="w-1/2">{{ layout.rows.length }} spans</span>
+      <span class="flex-1 text-left">0ms</span>
+      <span class="w-14 text-right tabular-nums">{{ layout.spanMs.toFixed(0) }}ms</span>
+    </div>
+
+    <div class="overflow-auto divide-y divide-zinc-900/50">
+      <WaterfallRowItem
+        v-for="(row, i) in layout.rows"
+        :key="row.key"
+        :row="row"
+        :selected="row.key === selectedKey"
+        :dimmed="i >= revealCount"
+        @select="emit('select', $event)"
+      />
+    </div>
+  </div>
+</template>