@durablex/react-ui 0.1.0-beta.3

package/src/index.ts

@@ -0,0 +1,165 @@
+export { AppShell } from "./shell/AppShell";
+export { Sidebar } from "./shell/Sidebar";
+export type { NavGroup, NavItem } from "./shell/Sidebar";
+export { Topbar } from "./shell/Topbar";
+
+export { RunInspector } from "./components/RunInspector";
+export type { RunInspectorProps } from "./components/RunInspector";
+export { RunInspectorActions } from "./components/RunInspectorActions";
+export { RunsView } from "./components/RunsView";
+export type { RunsViewProps, RunsViewState } from "./components/RunsView";
+export { Meta } from "./components/Meta";
+export { JsonBlock } from "./components/JsonBlock";
+export { LogList } from "./components/LogList";
+export { RunsTable } from "./components/RunsTable";
+export { RunsTableHead } from "./components/RunsTableHead";
+export { RunsTableRow } from "./components/RunsTableRow";
+export { RunsTableLoader } from "./components/RunsTableLoader";
+export { RunsTablePlaceholder } from "./components/RunsTablePlaceholder";
+export { RunsFilterBar } from "./components/RunsFilterBar";
+export { CursorPager } from "./components/CursorPager";
+export { BulkReplayButton } from "./components/BulkReplayButton";
+export { RunPauseButton } from "./components/RunPauseButton";
+export { RunCancelButton } from "./components/RunCancelButton";
+export { RetryFromStepButton } from "./components/RetryFromStepButton";
+export { RunControlHistory } from "./components/RunControlHistory";
+export { AppFilter } from "./components/filters/AppFilter";
+export { TimeRangeFilter } from "./components/filters/TimeRangeFilter";
+export { TimeZoneFilter } from "./components/filters/TimeZoneFilter";
+export { FilterDropdown } from "./components/filters/FilterDropdown";
+export { FilterDropdownButton } from "./components/filters/FilterDropdownButton";
+export { FilterDropdownItem } from "./components/filters/FilterDropdownItem";
+export { StatsTiles } from "./components/StatsTiles";
+export { StatTileGrid } from "./components/StatTileGrid";
+export type { StatTile } from "./components/StatTileGrid";
+
+export { StatusBadge } from "./components/StatusBadge";
+export { AppTag } from "./components/AppTag";
+export { ScheduledBadge } from "./components/ScheduledBadge";
+export { GlyphBadge } from "./components/GlyphBadge";
+export { ResumeMark } from "./components/ResumeMark";
+export { AnimatedDurablexMark } from "./components/AnimatedDurablexMark";
+export { DurablexLogo } from "./components/DurablexLogo";
+export { MARK_BARS, RESUME_TRIANGLE } from "./components/marks-geometry";
+
+export { Button, buttonVariants } from "./ui/button";
+export { Input } from "./ui/input";
+export { Separator } from "./ui/separator";
+export {
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogOverlay,
+  DialogPortal,
+  DialogTitle,
+  DialogTrigger,
+} from "./ui/dialog";
+export { JsonEditor } from "./components/JsonEditor";
+export { SectionHeader } from "./components/SectionHeader";
+export { ReplayRunDialog } from "./components/ReplayRunDialog";
+export { RunCharts } from "./components/charts/RunCharts";
+export { WorkflowsView } from "./components/WorkflowsView";
+export { WorkflowDetail } from "./components/WorkflowDetail";
+export { FlowControlSection } from "./components/FlowControlSection";
+export { FlowControlBadge } from "./components/FlowControlBadge";
+export { RunnerLiveBadge } from "./components/RunnerLiveBadge";
+export { AppsView } from "./components/AppsView";
+export { AppStatusBadge } from "./components/AppStatusBadge";
+export { EventsView } from "./components/EventsView";
+export { EventsList } from "./components/EventsList";
+export { TriggerEventDialog } from "./components/TriggerEventDialog";
+export { TriggerEventResult } from "./components/TriggerEventResult";
+export { WorkflowRunAction } from "./components/WorkflowRunAction";
+export { WorkflowRunDialog } from "./components/WorkflowRunDialog";
+export { TableStatusRows } from "./components/TableStatusRows";
+export { WebhooksView } from "./components/WebhooksView";
+export { Facts } from "./components/Facts";
+export { OverviewView } from "./components/OverviewView";
+export { FlowSummary } from "./components/FlowSummary";
+export {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  TableFooter,
+  TableCaption,
+} from "./ui/table";
+export { TABLE_HEAD_CLASS } from "./lib/table";
+export { workflowRunPlan } from "./lib/workflow-run";
+export type { EventRunOption, WorkflowRunPlan } from "./lib/workflow-run";
+export { ResizableHandle, ResizablePanel, ResizablePanelGroup } from "./ui/resizable";
+export { useKeysetPager } from "./hooks/use-keyset-pager";
+export { FLOW_ADAPTERS, hasFlowControl, flowControlRows } from "./lib/flow-control";
+export type { FlowAdapter, FlowRow } from "./lib/flow-control";
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+} from "./ui/sheet";
+export { Skeleton } from "./ui/skeleton";
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./ui/tooltip";
+export { Toaster } from "./ui/sonner";
+
+export { useIsMobile } from "./hooks/use-mobile";
+export { useCopyToClipboard } from "./hooks/use-copy";
+export { useConfirmAction } from "./hooks/use-confirm-action";
+export { useClickOutside } from "./components/filters/use-click-outside";
+
+export { cn } from "./lib/utils";
+export {
+  THEME_PREFS,
+  getThemePref,
+  setThemePref,
+  applyThemePref,
+  watchSystemTheme,
+} from "./lib/theme";
+export type { ThemePref } from "./lib/theme";
+export {
+  highlightedJsonSpans,
+  parseJson,
+  tokenizeJson,
+  JSON_TOKEN_COLOR,
+} from "./lib/json-highlight";
+export type { JsonTokenKind, ParsedJson } from "./lib/json-highlight";
+export {
+  formatError,
+  formatDuration,
+  formatTime,
+  formatNextFire,
+  formatRelative,
+} from "./lib/format";
+export { STATUS_LABELS } from "./lib/status-label";
+export {
+  currentStepNumber,
+  expectedStepTotals,
+  stepCellLabel,
+  stepProgress,
+} from "./lib/run-progress";
+export { RUN_SORT_KEYS, SORT_DIRS, DEFAULT_RUN_SORT, toggleRunSort } from "./lib/run-sort";
+export type { RunSort, RunSortKey, SortDir } from "./lib/run-sort";
+export { RUN_TYPE_FILTERS, ALL_FILTER } from "./lib/run-filters";
+export type { RunTypeFilter, StatusFilter } from "./lib/run-filters";
+export { appHue } from "./lib/app-color";
+export {
+  DEFAULT_TIME_RANGE,
+  TIME_OPTIONS,
+  TIME_ZONES,
+  timeLabel,
+  windowSince,
+  parseWindowMs,
+  seriesBucketSeconds,
+  bucketTickLabel,
+  localTimeZone,
+} from "./lib/time-range";
+export type { TimeZoneMode } from "./lib/time-range";
+export { ACTION_LABELS, actorLabel, describeControlDetail } from "./lib/control-action";

package/src/lib/app-color.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { appHue } from "./app-color";
+
+const OKLCH = /^oklch\(0\.62 0\.15 (\d+(?:\.\d+)?)\)$/;
+
+describe("appHue", () => {
+  it("produces a well-formed oklch color with fixed lightness and chroma", () => {
+    const match = OKLCH.exec(appHue("checkout"));
+    expect(match).not.toBeNull();
+  });
+
+  it("keeps the hue within 0-359", () => {
+    for (const name of ["a", "billing", "orders", "a-very-long-app-name"]) {
+      const match = OKLCH.exec(appHue(name));
+      const hue = Number(match?.[1]);
+      expect(hue).toBeGreaterThanOrEqual(0);
+      expect(hue).toBeLessThan(360);
+    }
+  });
+
+  it("is deterministic for the same name", () => {
+    expect(appHue("checkout")).toBe(appHue("checkout"));
+  });
+
+  it("gives different names different hues", () => {
+    expect(appHue("checkout")).not.toBe(appHue("refund"));
+  });
+
+  it("handles the empty name as a hue of 0", () => {
+    expect(appHue("")).toBe("oklch(0.62 0.15 0)");
+  });
+});

package/src/lib/app-color.ts

@@ -0,0 +1,8 @@
+// Deterministic per-app accent. The engine does not persist an app color yet, so we
+// derive a stable hue from the name. All app colors share the same lightness/chroma
+// and vary only by hue, per the design brief.
+export function appHue(name: string): string {
+  let h = 0;
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) | 0;
+  return `oklch(0.62 0.15 ${((h % 360) + 360) % 360})`;
+}

package/src/lib/control-action.ts

@@ -0,0 +1,36 @@
+import type { ControlAction, ControlActionKind } from "@durablex/react";
+
+export const ACTION_LABELS: Record<ControlActionKind, string> = {
+  cancel: "Cancelled",
+  pause: "Paused",
+  resume: "Resumed",
+  replay: "Replayed",
+  retry_from_step: "Retried from step",
+  bulk_replay: "Bulk replay",
+};
+
+// An action recorded with no API-key label was driven by an unauthenticated (self-hosted) engine.
+export function actorLabel(actor?: string): string {
+  return actor || "self-hosted";
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function asNum(v: unknown): number {
+  return typeof v === "number" ? v : 0;
+}
+
+export function describeControlDetail(a: ControlAction): string {
+  const d = a.detail;
+  if (!isRecord(d)) return "";
+  if (a.action === "retry_from_step" && typeof d.step === "string") {
+    return `from "${d.step}"`;
+  }
+  if (a.action === "bulk_replay") {
+    const summary = `${asNum(d.replayed)}/${asNum(d.matched)} replayed`;
+    return d.capped ? `${summary}, capped` : summary;
+  }
+  return "";
+}

package/src/lib/flow-control.ts

@@ -0,0 +1,77 @@
+import type { FlowControl } from "@durablex/react";
+import { formatDuration } from "./format";
+
+export const FLOW_ADAPTERS = [
+  "concurrency",
+  "throttle",
+  "rateLimit",
+  "debounce",
+  "batch",
+  "priority",
+  "singleton",
+  "idempotency",
+] as const;
+export type FlowAdapter = (typeof FLOW_ADAPTERS)[number];
+
+const LABELS: Record<FlowAdapter, string> = {
+  concurrency: "Concurrency",
+  throttle: "Throttle",
+  rateLimit: "Rate limit",
+  debounce: "Debounce",
+  batch: "Batch",
+  priority: "Priority",
+  singleton: "Singleton",
+  idempotency: "Idempotency",
+};
+
+export function hasFlowControl(fc?: FlowControl): boolean {
+  return !!fc && FLOW_ADAPTERS.some((a) => fc[a] != null);
+}
+
+export interface FlowRow {
+  adapter: FlowAdapter;
+  label: string;
+  value: string;
+  scopeKey?: string;
+}
+
+// One display row per configured adapter, in FLOW_ADAPTERS order. value is the
+// human-readable policy; scopeKey (when set) is the event field the policy is
+// keyed on.
+export function flowControlRows(fc: FlowControl): FlowRow[] {
+  const rows: FlowRow[] = [];
+  const push = (adapter: FlowAdapter, value: string, scopeKey?: string) =>
+    rows.push({ adapter, label: LABELS[adapter], value, scopeKey });
+
+  if (fc.concurrency) push("concurrency", `limit ${fc.concurrency.limit}`, fc.concurrency.key);
+  if (fc.throttle)
+    push(
+      "throttle",
+      `${fc.throttle.limit} per ${formatDuration(fc.throttle.perMs)}`,
+      fc.throttle.key,
+    );
+  if (fc.rateLimit)
+    push(
+      "rateLimit",
+      `${fc.rateLimit.limit} per ${formatDuration(fc.rateLimit.perMs)}`,
+      fc.rateLimit.key,
+    );
+  if (fc.debounce)
+    push("debounce", `${formatDuration(fc.debounce.periodMs)} window`, fc.debounce.key);
+  if (fc.batch)
+    push("batch", `up to ${fc.batch.maxSize}, ${formatDuration(fc.batch.timeoutMs)}`, fc.batch.key);
+  if (fc.priority) {
+    // A positive shift moves the run earlier in the queue (higher priority); negative defers it.
+    const { shiftMs } = fc.priority;
+    push("priority", `${formatDuration(Math.abs(shiftMs))} ${shiftMs < 0 ? "later" : "earlier"}`);
+  }
+  if (fc.singleton) push("singleton", fc.singleton.mode || "-", fc.singleton.key);
+  if (fc.idempotency) {
+    push(
+      "idempotency",
+      fc.idempotency.periodMs ? `${formatDuration(fc.idempotency.periodMs)} window` : "on",
+      fc.idempotency.key,
+    );
+  }
+  return rows;
+}

package/src/lib/format.test.ts

@@ -0,0 +1,102 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { formatDuration, formatError, formatNextFire, formatRelative, formatTime } from "./format";
+
+describe("formatError", () => {
+  it("returns the message alone when there is no stack", () => {
+    expect(formatError({ message: "boom" })).toBe("boom");
+  });
+
+  it("joins message and stack with a blank line", () => {
+    expect(formatError({ message: "boom", stack: "at f()" })).toBe("boom\n\nat f()");
+  });
+});
+
+describe("formatDuration", () => {
+  it("renders a placeholder for null or undefined", () => {
+    expect(formatDuration(null)).toBe("-");
+    expect(formatDuration(undefined)).toBe("-");
+  });
+
+  it("renders sub-second durations in milliseconds", () => {
+    expect(formatDuration(0)).toBe("0ms");
+    expect(formatDuration(999)).toBe("999ms");
+  });
+
+  it("crosses into seconds at exactly 1000ms", () => {
+    expect(formatDuration(1000)).toBe("1.0s");
+    expect(formatDuration(1500)).toBe("1.5s");
+    expect(formatDuration(59_000)).toBe("59.0s");
+  });
+
+  it("crosses into minutes at 60 seconds", () => {
+    expect(formatDuration(60_000)).toBe("1.0m");
+    expect(formatDuration(90_000)).toBe("1.5m");
+  });
+
+  it("crosses into hours at 60 minutes", () => {
+    expect(formatDuration(3_600_000)).toBe("1.0h");
+    expect(formatDuration(5_400_000)).toBe("1.5h");
+  });
+});
+
+describe("formatTime", () => {
+  it("renders a placeholder for empty input", () => {
+    expect(formatTime(null)).toBe("-");
+    expect(formatTime(undefined)).toBe("-");
+    expect(formatTime("")).toBe("-");
+  });
+
+  it("renders a 24-hour time for a valid instant", () => {
+    expect(formatTime("2026-07-01T13:45:07.000Z")).toMatch(/^\d{2}:\d{2}:\d{2}$/);
+  });
+});
+
+describe("time-relative formatters", () => {
+  const NOW = new Date("2026-07-01T12:00:00.000Z");
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(NOW);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe("formatNextFire", () => {
+    it("renders a placeholder for empty input", () => {
+      expect(formatNextFire(null)).toBe("-");
+      expect(formatNextFire(undefined)).toBe("-");
+    });
+
+    it("reads a non-positive delta as due", () => {
+      expect(formatNextFire("2026-07-01T12:00:00.000Z")).toBe("due");
+      expect(formatNextFire("2026-07-01T11:59:00.000Z")).toBe("due");
+    });
+
+    it("floors sub-minute, sub-hour, sub-day and multi-day horizons", () => {
+      expect(formatNextFire("2026-07-01T12:00:30.000Z")).toBe("in 30s");
+      expect(formatNextFire("2026-07-01T12:03:00.000Z")).toBe("in 3m");
+      expect(formatNextFire("2026-07-01T15:00:00.000Z")).toBe("in 3h");
+      expect(formatNextFire("2026-07-03T12:00:00.000Z")).toBe("in 2d");
+    });
+  });
+
+  describe("formatRelative", () => {
+    it("renders a placeholder for empty input", () => {
+      expect(formatRelative(null)).toBe("-");
+      expect(formatRelative(undefined)).toBe("-");
+    });
+
+    it("clamps a future instant to 0s ago", () => {
+      expect(formatRelative("2026-07-01T12:05:00.000Z")).toBe("0s ago");
+    });
+
+    it("floors sub-minute, sub-hour, sub-day and multi-day ages", () => {
+      expect(formatRelative("2026-07-01T11:59:30.000Z")).toBe("30s ago");
+      expect(formatRelative("2026-07-01T11:57:00.000Z")).toBe("3m ago");
+      expect(formatRelative("2026-07-01T09:00:00.000Z")).toBe("3h ago");
+      expect(formatRelative("2026-06-29T12:00:00.000Z")).toBe("2d ago");
+    });
+  });
+});

package/src/lib/format.ts

@@ -0,0 +1,45 @@
+import type { StepErrorInfo } from "@durablex/react";
+
+export function formatError(error: StepErrorInfo): string {
+  return error.stack ? `${error.message}\n\n${error.stack}` : error.message;
+}
+
+export function formatDuration(ms?: number | null): string {
+  if (ms === null || ms === undefined) return "-";
+  if (ms < 1000) return `${ms}ms`;
+  const s = ms / 1000;
+  if (s < 60) return `${s.toFixed(1)}s`;
+  const m = s / 60;
+  if (m < 60) return `${m.toFixed(1)}m`;
+  return `${(m / 60).toFixed(1)}h`;
+}
+
+export function formatTime(iso?: string | null): string {
+  if (!iso) return "-";
+  return new Date(iso).toLocaleTimeString([], { hour12: false });
+}
+
+// Time until a scheduled fire, as "in 3m". A non-positive delta reads as "due"
+// (the sweep runs on an interval, so a just-passed tick has not fired yet).
+export function formatNextFire(iso?: string | null): string {
+  if (!iso) return "-";
+  const sec = (new Date(iso).getTime() - Date.now()) / 1000;
+  if (sec <= 0) return "due";
+  if (sec < 60) return `in ${Math.floor(sec)}s`;
+  const min = sec / 60;
+  if (min < 60) return `in ${Math.floor(min)}m`;
+  const hr = min / 60;
+  if (hr < 24) return `in ${Math.floor(hr)}h`;
+  return `in ${Math.floor(hr / 24)}d`;
+}
+
+export function formatRelative(iso?: string | null): string {
+  if (!iso) return "-";
+  const sec = Math.max(0, (Date.now() - new Date(iso).getTime()) / 1000);
+  if (sec < 60) return `${Math.floor(sec)}s ago`;
+  const min = sec / 60;
+  if (min < 60) return `${Math.floor(min)}m ago`;
+  const hr = min / 60;
+  if (hr < 24) return `${Math.floor(hr)}h ago`;
+  return `${Math.floor(hr / 24)}d ago`;
+}

package/src/lib/json-highlight.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { parseJson, tokenizeJson } from "./json-highlight";
+
+describe("parseJson", () => {
+  it("treats blank input as an empty object (the form default)", () => {
+    expect(parseJson("   ")).toEqual({ ok: true, value: {} });
+  });
+  it("parses valid JSON", () => {
+    expect(parseJson('{"a":1}')).toEqual({ ok: true, value: { a: 1 } });
+  });
+  it("reports invalid JSON without throwing", () => {
+    const r = parseJson("{not json}");
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error).toMatch(/valid JSON/);
+  });
+});
+
+describe("tokenizeJson", () => {
+  it("classifies keys, strings, numbers, booleans, and null", () => {
+    const kinds = (src: string) => tokenizeJson(src).map((t) => t.kind);
+    expect(kinds('{"k":"v"}')).toContain("key");
+    expect(kinds('{"k":"v"}')).toContain("str");
+    expect(kinds('{"n":42}')).toContain("num");
+    expect(kinds('{"b":true}')).toContain("bool");
+    expect(kinds('{"z":null}')).toContain("null");
+  });
+
+  it("round-trips the exact source text when tokens are concatenated", () => {
+    const src = '{\n  "amount": 12.5,\n  "ok": false,\n  "note": null\n}';
+    expect(
+      tokenizeJson(src)
+        .map((t) => t.text)
+        .join(""),
+    ).toBe(src);
+  });
+});

package/src/lib/json-highlight.ts

@@ -0,0 +1,64 @@
+export type JsonTokenKind = "key" | "str" | "num" | "bool" | "null" | "punc";
+
+export const JSON_TOKEN_COLOR: Record<JsonTokenKind, string> = {
+  key: "var(--foreground)",
+  str: "var(--st-succeeded-fg)",
+  num: "var(--st-running-fg)",
+  bool: "var(--primary)",
+  null: "var(--muted-foreground)",
+  punc: "color-mix(in oklch, var(--muted-foreground) 70%, transparent)",
+};
+
+const TOKEN =
+  /"(?:\\.|[^"\\])*"(\s*:)?|\b(?:true|false)\b|\bnull\b|-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/g;
+
+export function tokenizeJson(src: string): { text: string; kind: JsonTokenKind }[] {
+  const out: { text: string; kind: JsonTokenKind }[] = [];
+  let last = 0;
+  let m: RegExpExecArray | null;
+  TOKEN.lastIndex = 0;
+  while ((m = TOKEN.exec(src)) !== null) {
+    if (m.index > last) out.push({ text: src.slice(last, m.index), kind: "punc" });
+    const s = m[0];
+    if (s[0] === '"') {
+      if (m[1]) {
+        const q = s.lastIndexOf('"') + 1;
+        out.push({ text: s.slice(0, q), kind: "key" });
+        out.push({ text: s.slice(q), kind: "punc" });
+      } else {
+        out.push({ text: s, kind: "str" });
+      }
+    } else if (s === "true" || s === "false") {
+      out.push({ text: s, kind: "bool" });
+    } else if (s === "null") {
+      out.push({ text: s, kind: "null" });
+    } else {
+      out.push({ text: s, kind: "num" });
+    }
+    last = TOKEN.lastIndex;
+  }
+  if (last < src.length) out.push({ text: src.slice(last), kind: "punc" });
+  return out;
+}
+
+export type ParsedJson = { ok: true; value: unknown } | { ok: false; error: string };
+
+export function parseJson(raw: string): ParsedJson {
+  const text = raw.trim();
+  if (text === "") return { ok: true, value: {} };
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false, error: "Payload must be valid JSON" };
+  }
+}
+
+export function highlightedJsonSpans(text: string) {
+  return tokenizeJson(text).map((tok, i) => ({
+    key: i,
+    text: tok.text,
+    color: JSON_TOKEN_COLOR[tok.kind],
+    bold: tok.kind === "bool",
+    italic: tok.kind === "null",
+  }));
+}

package/src/lib/run-filters.ts

@@ -0,0 +1,8 @@
+import type { RunStatus } from "@durablex/react";
+
+export const ALL_FILTER = "all" as const;
+
+export type StatusFilter = typeof ALL_FILTER | Exclude<RunStatus, "waiting">;
+
+export const RUN_TYPE_FILTERS = [ALL_FILTER, "triggered", "scheduled"] as const;
+export type RunTypeFilter = (typeof RUN_TYPE_FILTERS)[number];

package/src/lib/run-logs.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+import type { LogFrame, LogLevel, StepStatusFrame, TimelineFrame } from "@durablex/react";
+import { groupLogs, NO_LOGS, ROOT_SCOPE, stepLogKey } from "./run-logs";
+
+function log(scope: string, attempt: number, message: string): LogFrame {
+  return {
+    kind: "log",
+    seq: 1,
+    ts: "2026-07-01T00:00:00.000Z",
+    runId: "run-1",
+    level: "info" as LogLevel,
+    message,
+    scope,
+    attempt,
+  };
+}
+
+describe("stepLogKey", () => {
+  it("joins name and attempt with a colon", () => {
+    expect(stepLogKey("charge", 0)).toBe("charge:0");
+    expect(stepLogKey("charge", 2)).toBe("charge:2");
+  });
+});
+
+describe("NO_LOGS", () => {
+  it("is an empty array reused by reference", () => {
+    expect(NO_LOGS).toEqual([]);
+    expect(NO_LOGS).toBe(NO_LOGS);
+  });
+});
+
+describe("groupLogs", () => {
+  it("returns empty groups for empty input", () => {
+    const { byStep, root } = groupLogs([]);
+    expect(root).toEqual([]);
+    expect(byStep.size).toBe(0);
+  });
+
+  it("routes @root-scoped logs to root and step-scoped logs to byStep", () => {
+    const frames: TimelineFrame[] = [
+      log(ROOT_SCOPE, 0, "handler start"),
+      log("charge", 0, "charging"),
+      log(ROOT_SCOPE, 0, "handler done"),
+    ];
+    const { byStep, root } = groupLogs(frames);
+    expect(root.map((f) => f.message)).toEqual(["handler start", "handler done"]);
+    expect(byStep.get("charge:0")?.map((f) => f.message)).toEqual(["charging"]);
+  });
+
+  it("keys step logs by name:attempt and preserves order within a key", () => {
+    const frames: TimelineFrame[] = [log("charge", 0, "first"), log("charge", 0, "second")];
+    const { byStep } = groupLogs(frames);
+    expect(byStep.get("charge:0")?.map((f) => f.message)).toEqual(["first", "second"]);
+  });
+
+  it("separates the same step name across different attempts into distinct keys", () => {
+    const frames: TimelineFrame[] = [log("charge", 0, "attempt 0"), log("charge", 1, "attempt 1")];
+    const { byStep } = groupLogs(frames);
+    expect(byStep.get("charge:0")?.map((f) => f.message)).toEqual(["attempt 0"]);
+    expect(byStep.get("charge:1")?.map((f) => f.message)).toEqual(["attempt 1"]);
+    expect(byStep.size).toBe(2);
+  });
+
+  it("ignores non-log frames", () => {
+    const stepFrame: StepStatusFrame = {
+      kind: "step_status",
+      seq: 2,
+      ts: "2026-07-01T00:00:00.000Z",
+      runId: "run-1",
+      name: "charge",
+      status: "succeeded",
+      attempt: 0,
+    };
+    const frames: TimelineFrame[] = [stepFrame, log("charge", 0, "kept")];
+    const { byStep, root } = groupLogs(frames);
+    expect(root).toEqual([]);
+    expect(byStep.get("charge:0")?.map((f) => f.message)).toEqual(["kept"]);
+    expect(byStep.size).toBe(1);
+  });
+});