@durablex/react-ui 0.1.0-beta.3

package/src/lib/run-logs.ts

@@ -0,0 +1,34 @@
+import type { LogFrame, TimelineFrame } from "@durablex/react";
+
+export const ROOT_SCOPE = "@root";
+
+// Stable empty array so a step with no logs passes the same reference every render.
+export const NO_LOGS: LogFrame[] = [];
+
+export interface RunLogs {
+  // Step-scoped logs keyed by `${name}:${attempt}`, matching one step-attempt row.
+  byStep: Map<string, LogFrame[]>;
+  // Handler-level logs (scope '@root'), which belong to the run, not a step.
+  root: LogFrame[];
+}
+
+export function stepLogKey(name: string, attempt: number): string {
+  return `${name}:${attempt}`;
+}
+
+export function groupLogs(frames: TimelineFrame[]): RunLogs {
+  const byStep = new Map<string, LogFrame[]>();
+  const root: LogFrame[] = [];
+  for (const f of frames) {
+    if (f.kind !== "log") continue;
+    if (f.scope === ROOT_SCOPE) {
+      root.push(f);
+      continue;
+    }
+    const key = stepLogKey(f.scope, f.attempt);
+    const list = byStep.get(key);
+    if (list) list.push(f);
+    else byStep.set(key, [f]);
+  }
+  return { byStep, root };
+}

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

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import type { Run, Step } from "@durablex/react";
+import { currentStepNumber, expectedStepTotals, stepCellLabel, stepProgress } from "./run-progress";
+
+function run(overrides: Partial<Run> = {}): Run {
+  return {
+    id: "run-1",
+    workflowName: "checkout",
+    app: "default",
+    status: "running",
+    errorCount: 0,
+    attempt: 0,
+    triggerKind: "event",
+    stepCount: 0,
+    currentStepIndex: -1,
+    startedAt: "2026-07-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+function step(overrides: Partial<Step> = {}): Step {
+  return {
+    name: "charge",
+    index: 0,
+    attempt: 0,
+    status: "succeeded",
+    ...overrides,
+  };
+}
+
+describe("currentStepNumber", () => {
+  it("is the 1-based current index when a step is live", () => {
+    expect(currentStepNumber(run({ currentStepIndex: 2, stepCount: 5 }))).toBe(3);
+  });
+
+  it("falls back to the step count when there is no live step", () => {
+    expect(currentStepNumber(run({ currentStepIndex: -1, stepCount: 4 }))).toBe(4);
+  });
+});
+
+describe("expectedStepTotals", () => {
+  it("ignores runs that have not ended", () => {
+    const totals = expectedStepTotals([run({ stepCount: 9, endedAt: undefined })]);
+    expect(totals.size).toBe(0);
+  });
+
+  it("records the largest finished step count per workflow", () => {
+    const runs = [
+      run({ workflowName: "checkout", stepCount: 3, endedAt: "2026-07-01T00:01:00.000Z" }),
+      run({ workflowName: "checkout", stepCount: 5, endedAt: "2026-07-01T00:02:00.000Z" }),
+      run({ workflowName: "checkout", stepCount: 2, endedAt: "2026-07-01T00:03:00.000Z" }),
+      run({ workflowName: "refund", stepCount: 4, endedAt: "2026-07-01T00:04:00.000Z" }),
+    ];
+    const totals = expectedStepTotals(runs);
+    expect(totals.get("checkout")).toBe(5);
+    expect(totals.get("refund")).toBe(4);
+  });
+});
+
+describe("stepCellLabel", () => {
+  it("shows the real total for a finished run", () => {
+    const finished = run({
+      currentStepIndex: -1,
+      stepCount: 4,
+      endedAt: "2026-07-01T00:01:00.000Z",
+    });
+    expect(stepCellLabel(finished, 9)).toBe("4/4");
+  });
+
+  it("uses the estimate as the denominator for a live run", () => {
+    const live = run({ currentStepIndex: 1, stepCount: 2 });
+    expect(stepCellLabel(live, 5)).toBe("2/5");
+  });
+
+  it("never reads below the steps a live run has already reached", () => {
+    const live = run({ currentStepIndex: 4, stepCount: 5 });
+    expect(stepCellLabel(live, 3)).toBe("5/5");
+  });
+
+  it("treats a missing estimate as zero for a live run", () => {
+    const live = run({ currentStepIndex: 1, stepCount: 2 });
+    expect(stepCellLabel(live)).toBe("2/2");
+  });
+});
+
+describe("stepProgress", () => {
+  it("reports 0/0 when there are no steps", () => {
+    expect(stepProgress(run(), [])).toEqual({ ix: 0, total: 0 });
+  });
+
+  it("anchors the index on the matched current step name", () => {
+    const steps = [step({ name: "a" }), step({ name: "b" }), step({ name: "c" })];
+    expect(stepProgress(run({ currentStepName: "b" }), steps)).toEqual({ ix: 2, total: 3 });
+  });
+
+  it("falls back to the count of finished steps when no current step matches", () => {
+    const steps = [
+      step({ name: "a", status: "succeeded" }),
+      step({ name: "b", status: "skipped" }),
+      step({ name: "c", status: "running" }),
+    ];
+    expect(stepProgress(run({ currentStepName: undefined }), steps)).toEqual({ ix: 2, total: 3 });
+  });
+
+  it("reads a terminal run as total/total via finished-step count", () => {
+    const steps = [step({ name: "a", status: "succeeded" }), step({ name: "b", status: "failed" })];
+    expect(stepProgress(run({ currentStepName: "missing" }), steps)).toEqual({ ix: 2, total: 2 });
+  });
+});

package/src/lib/run-progress.ts

@@ -0,0 +1,44 @@
+import type { Run, Step, StepStatus } from "@durablex/react";
+
+// 1-based ordinal of the run's current step, from the counts the runs list carries.
+// A terminal run has no live current step, so it reads as total/total.
+export function currentStepNumber(run: Run): number {
+  return run.currentStepIndex >= 0 ? run.currentStepIndex + 1 : run.stepCount;
+}
+
+// expectedStepTotals maps a workflow to the largest step count seen among its
+// finished runs - the denominator estimate for a run still discovering its steps.
+// A workflow's total isn't known up front (steps are discovered as the handler
+// executes, and can branch), so the dashboard estimates it from prior runs.
+export function expectedStepTotals(runs: Run[]): Map<string, number> {
+  const totals = new Map<string, number>();
+  for (const r of runs) {
+    if (!r.endedAt) continue;
+    if (r.stepCount > (totals.get(r.workflowName) ?? 0)) {
+      totals.set(r.workflowName, r.stepCount);
+    }
+  }
+  return totals;
+}
+
+// The runs-table step label as "{ix}/{total}". A finished run shows its real
+// total; a live one uses the estimate from prior runs of the same workflow, never
+// below the steps it has already reached (so it never reads as e.g. 5/3).
+export function stepCellLabel(run: Run, expectedTotal?: number): string {
+  const ix = currentStepNumber(run);
+  const total = run.endedAt ? run.stepCount : Math.max(run.stepCount, expectedTotal ?? 0);
+  return `${ix}/${total}`;
+}
+
+const FINISHED: ReadonlySet<StepStatus> = new Set(["succeeded", "failed", "cancelled", "skipped"]);
+
+// Position of the run within its step list, as "{ix}/{total}". The current step
+// (matched by name) anchors the index; otherwise it falls back to the count of
+// finished steps so terminal runs read as total/total.
+export function stepProgress(run: Run, steps: Step[]): { ix: number; total: number } {
+  const total = steps.length;
+  if (total === 0) return { ix: 0, total: 0 };
+  const cur = run.currentStepName ? steps.findIndex((s) => s.name === run.currentStepName) : -1;
+  if (cur >= 0) return { ix: cur + 1, total };
+  return { ix: steps.filter((s) => FINISHED.has(s.status)).length, total };
+}

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

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_RUN_SORT, RUN_SORT_KEYS, SORT_DIRS, toggleRunSort } from "./run-sort";
+
+describe("run-sort constants", () => {
+  it("lists the sortable columns", () => {
+    expect(RUN_SORT_KEYS).toEqual(["workflow", "status", "app", "started", "duration"]);
+  });
+
+  it("lists the two directions", () => {
+    expect(SORT_DIRS).toEqual(["asc", "desc"]);
+  });
+
+  it("defaults to newest-started first", () => {
+    expect(DEFAULT_RUN_SORT).toEqual({ key: "started", dir: "desc" });
+  });
+});
+
+describe("toggleRunSort", () => {
+  it("flips direction when the same key is toggled", () => {
+    expect(toggleRunSort({ key: "started", dir: "asc" }, "started")).toEqual({
+      key: "started",
+      dir: "desc",
+    });
+    expect(toggleRunSort({ key: "started", dir: "desc" }, "started")).toEqual({
+      key: "started",
+      dir: "asc",
+    });
+  });
+
+  it("switches to the new key and resets direction to ascending", () => {
+    expect(toggleRunSort({ key: "started", dir: "desc" }, "duration")).toEqual({
+      key: "duration",
+      dir: "asc",
+    });
+    expect(toggleRunSort({ key: "app", dir: "asc" }, "workflow")).toEqual({
+      key: "workflow",
+      dir: "asc",
+    });
+  });
+});

package/src/lib/run-sort.ts

@@ -0,0 +1,19 @@
+export const RUN_SORT_KEYS = ["workflow", "status", "app", "started", "duration"] as const;
+export type RunSortKey = (typeof RUN_SORT_KEYS)[number];
+
+export const SORT_DIRS = ["asc", "desc"] as const;
+export type SortDir = (typeof SORT_DIRS)[number];
+
+export interface RunSort {
+  key: RunSortKey;
+  dir: SortDir;
+}
+
+export const DEFAULT_RUN_SORT: RunSort = { key: "started", dir: "desc" };
+
+export function toggleRunSort(prev: RunSort, key: RunSortKey): RunSort {
+  if (prev.key === key) {
+    return { key, dir: prev.dir === "asc" ? "desc" : "asc" };
+  }
+  return { key, dir: "asc" };
+}

package/src/lib/status-label.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import type { RunStatus, StepStatus } from "@durablex/react";
+import { STATUS_LABELS } from "./status-label";
+
+describe("STATUS_LABELS", () => {
+  it("presents waiting as Running so it reads as in progress", () => {
+    expect(STATUS_LABELS.waiting).toBe("Running");
+    expect(STATUS_LABELS.running).toBe("Running");
+  });
+
+  it("title-cases every other status", () => {
+    expect(STATUS_LABELS.queued).toBe("Queued");
+    expect(STATUS_LABELS.paused).toBe("Paused");
+    expect(STATUS_LABELS.succeeded).toBe("Succeeded");
+    expect(STATUS_LABELS.failed).toBe("Failed");
+    expect(STATUS_LABELS.cancelled).toBe("Cancelled");
+    expect(STATUS_LABELS.skipped).toBe("Skipped");
+  });
+
+  it("covers every run and step status", () => {
+    const statuses: (RunStatus | StepStatus)[] = [
+      "queued",
+      "running",
+      "waiting",
+      "paused",
+      "succeeded",
+      "failed",
+      "cancelled",
+      "skipped",
+    ];
+    for (const status of statuses) {
+      expect(STATUS_LABELS[status]).toBeTruthy();
+    }
+  });
+});

package/src/lib/status-label.ts

@@ -0,0 +1,13 @@
+import type { RunStatus, StepStatus } from "@durablex/react";
+
+// "waiting" reads as "in progress" to users, so it displays as "Running".
+export const STATUS_LABELS: Record<RunStatus | StepStatus, string> = {
+  queued: "Queued",
+  running: "Running",
+  waiting: "Running",
+  paused: "Paused",
+  succeeded: "Succeeded",
+  failed: "Failed",
+  cancelled: "Cancelled",
+  skipped: "Skipped",
+};

package/src/lib/step-detail.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+import type { Step, StepStatus } from "@durablex/react";
+import { initialStepSelection, stepErrorText, stepTabs, STEP_TAB_LABEL } from "./step-detail";
+
+function step(overrides: Partial<Step> = {}): Step {
+  return {
+    name: "charge",
+    index: 0,
+    attempt: 0,
+    status: "succeeded",
+    ...overrides,
+  };
+}
+
+describe("STEP_TAB_LABEL", () => {
+  it("maps every tab to a human label", () => {
+    expect(STEP_TAB_LABEL).toEqual({
+      error: "Error",
+      input: "Input",
+      output: "Output",
+      logs: "Logs",
+    });
+  });
+});
+
+describe("stepTabs", () => {
+  it("returns no tabs when the step has no content and no logs", () => {
+    expect(stepTabs(step({ input: null, output: null }), false)).toEqual([]);
+  });
+
+  it("includes error only when the step failed with an error", () => {
+    const failed = step({
+      status: "failed",
+      error: { message: "boom" },
+      input: null,
+      output: null,
+    });
+    expect(stepTabs(failed, false)).toEqual(["error"]);
+    expect(stepTabs(step({ input: null, output: null }), false)).toEqual([]);
+  });
+
+  it("includes input only when input is neither null nor undefined", () => {
+    expect(stepTabs(step({ input: { amount: 5 }, output: null }), false)).toEqual(["input"]);
+    expect(stepTabs(step({ input: null, output: null }), false)).toEqual([]);
+    expect(stepTabs(step({ input: undefined, output: null }), false)).toEqual([]);
+  });
+
+  it("treats falsy-but-present input and output as content", () => {
+    expect(stepTabs(step({ input: 0, output: false }), false)).toEqual(["input", "output"]);
+    expect(stepTabs(step({ input: "", output: null }), false)).toEqual(["input"]);
+  });
+
+  it("includes logs only when hasLogs is true", () => {
+    expect(stepTabs(step({ input: null, output: null }), true)).toEqual(["logs"]);
+    expect(stepTabs(step({ input: null, output: null }), false)).toEqual([]);
+  });
+
+  it("orders tabs error, input, output, logs when all are present", () => {
+    const full = step({
+      status: "failed",
+      error: { message: "boom" },
+      input: { a: 1 },
+      output: { b: 2 },
+    });
+    expect(stepTabs(full, true)).toEqual(["error", "input", "output", "logs"]);
+  });
+});
+
+describe("stepErrorText", () => {
+  it("returns an empty string when the step has no error", () => {
+    expect(stepErrorText(step())).toBe("");
+  });
+
+  it("returns the message alone when there is no stack", () => {
+    expect(stepErrorText(step({ error: { message: "boom" } }))).toBe("boom");
+  });
+
+  it("joins message and stack with a blank line", () => {
+    const text = stepErrorText(step({ error: { message: "boom", stack: "at f()\nat g()" } }));
+    expect(text).toBe("boom\n\nat f()\nat g()");
+  });
+});
+
+describe("initialStepSelection", () => {
+  it("returns 0 for an empty list", () => {
+    expect(initialStepSelection([])).toBe(0);
+  });
+
+  it("prefers the first failed step", () => {
+    const steps = [
+      step({ name: "a", status: "succeeded" }),
+      step({ name: "b", status: "running" }),
+      step({ name: "c", status: "failed" }),
+    ];
+    expect(initialStepSelection(steps)).toBe(2);
+  });
+
+  it("picks failed over an earlier running step", () => {
+    const steps = [step({ name: "a", status: "running" }), step({ name: "b", status: "failed" })];
+    expect(initialStepSelection(steps)).toBe(1);
+  });
+
+  it("falls back to the first running or waiting step when none failed", () => {
+    const running = [
+      step({ name: "a", status: "succeeded" }),
+      step({ name: "b", status: "running" }),
+    ];
+    expect(initialStepSelection(running)).toBe(1);
+
+    const waiting = [
+      step({ name: "a", status: "succeeded" }),
+      step({ name: "b", status: "waiting" }),
+    ];
+    expect(initialStepSelection(waiting)).toBe(1);
+  });
+
+  it("falls back to 0 when every step is settled and none failed", () => {
+    const settled: StepStatus[] = ["succeeded", "succeeded", "skipped"];
+    const steps = settled.map((status, i) => step({ name: `s${i}`, status }));
+    expect(initialStepSelection(steps)).toBe(0);
+  });
+});

package/src/lib/step-detail.ts

@@ -0,0 +1,35 @@
+import type { Step } from "@durablex/react";
+import { formatError } from "./format";
+
+// A step's expandable panes: Error first when it failed, then Input, Output, and
+// the ctx.log lines it emitted. Each is shown only when the step has that content.
+export type StepTab = "error" | "input" | "output" | "logs";
+
+export const STEP_TAB_LABEL: Record<StepTab, string> = {
+  error: "Error",
+  input: "Input",
+  output: "Output",
+  logs: "Logs",
+};
+
+export function stepTabs(step: Step, hasLogs: boolean): StepTab[] {
+  const tabs: StepTab[] = [];
+  if (step.error) tabs.push("error");
+  if (step.input !== null && step.input !== undefined) tabs.push("input");
+  if (step.output !== null && step.output !== undefined) tabs.push("output");
+  if (hasLogs) tabs.push("logs");
+  return tabs;
+}
+
+export function stepErrorText(step: Step): string {
+  return step.error ? formatError(step.error) : "";
+}
+
+// The step a steps view selects by default: the failed step, else the
+// running/waiting one, else the first. Shared by the flow and timeline views.
+export function initialStepSelection(steps: Step[]): number {
+  const failed = steps.findIndex((s) => s.status === "failed");
+  if (failed >= 0) return failed;
+  const active = steps.findIndex((s) => s.status === "running" || s.status === "waiting");
+  return active >= 0 ? active : 0;
+}

package/src/lib/step-display.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { stepDisplayStatus } from "./step-display";
+
+describe("stepDisplayStatus", () => {
+  it("shows an in-flight step as paused when the run is paused", () => {
+    expect(stepDisplayStatus("running", true)).toBe("paused");
+    expect(stepDisplayStatus("waiting", true)).toBe("paused");
+  });
+
+  it("leaves a settled step untouched even under a paused run", () => {
+    expect(stepDisplayStatus("succeeded", true)).toBe("succeeded");
+    expect(stepDisplayStatus("failed", true)).toBe("failed");
+  });
+
+  it("never overrides when the run is not paused", () => {
+    expect(stepDisplayStatus("running", false)).toBe("running");
+    expect(stepDisplayStatus("waiting", false)).toBe("waiting");
+  });
+});

package/src/lib/step-display.ts

@@ -0,0 +1,13 @@
+import type { StepStatus } from "@durablex/react";
+
+// A paused run leaves its in-flight step recorded as running/waiting in the engine
+// (pause only flips the run's status), so the inspector would otherwise show a
+// "Running" step under a "Paused" run. This derives a display-only status so that
+// step reads as paused too; it never changes the stored step status.
+export type StepDisplayStatus = StepStatus | "paused";
+
+const IN_FLIGHT: ReadonlySet<StepStatus> = new Set(["running", "waiting"]);
+
+export function stepDisplayStatus(status: StepStatus, runPaused: boolean): StepDisplayStatus {
+  return runPaused && IN_FLIGHT.has(status) ? "paused" : status;
+}

package/src/lib/step-timeline.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import type { Step } from "@durablex/react";
+import type { TimelineLane } from "./step-timeline";
+import { buildTimelineLayout } from "./step-timeline";
+
+function step(overrides: Partial<Step> = {}): Step {
+  return {
+    name: "charge",
+    index: 0,
+    attempt: 0,
+    status: "succeeded",
+    ...overrides,
+  };
+}
+
+function bar(lane: TimelineLane): { leftPct: number | null; widthPct: number } {
+  return { leftPct: lane.leftPct, widthPct: lane.widthPct };
+}
+
+const T0 = "2026-07-01T00:00:00.000Z";
+const T0_MS = Date.parse(T0);
+
+describe("buildTimelineLayout", () => {
+  it("keeps totalMs at least 1 for an empty step list", () => {
+    const { lanes, totalMs } = buildTimelineLayout([], T0_MS);
+    expect(lanes).toEqual([]);
+    expect(totalMs).toBe(1);
+  });
+
+  it("places a lone finished step at the start spanning the full axis", () => {
+    const steps = [step({ startedAt: T0, endedAt: "2026-07-01T00:00:01.000Z" })];
+    const { lanes, totalMs } = buildTimelineLayout(steps, T0_MS);
+    expect(totalMs).toBe(1000);
+    expect(lanes.map(bar)).toEqual([{ leftPct: 0, widthPct: 100 }]);
+  });
+
+  it("offsets lanes by their start and end relative to the earliest start", () => {
+    const steps = [
+      step({ name: "a", startedAt: T0, endedAt: "2026-07-01T00:00:01.000Z" }),
+      step({
+        name: "b",
+        startedAt: "2026-07-01T00:00:01.000Z",
+        endedAt: "2026-07-01T00:00:02.000Z",
+      }),
+    ];
+    const { lanes, totalMs } = buildTimelineLayout(steps, T0_MS);
+    expect(totalMs).toBe(2000);
+    expect(lanes.map(bar)).toEqual([
+      { leftPct: 0, widthPct: 50 },
+      { leftPct: 50, widthPct: 50 },
+    ]);
+  });
+
+  it("marks a step that never started with leftPct null and zero width", () => {
+    const steps = [step({ status: "skipped" })];
+    const { lanes } = buildTimelineLayout(steps, T0_MS);
+    expect(lanes.map(bar)).toEqual([{ leftPct: null, widthPct: 0 }]);
+  });
+
+  it("does not let a not-started step shift the axis origin", () => {
+    const steps = [
+      step({ name: "queued", status: "skipped" }),
+      step({ name: "ran", startedAt: T0, endedAt: "2026-07-01T00:00:01.000Z" }),
+    ];
+    const { lanes, totalMs } = buildTimelineLayout(steps, T0_MS);
+    expect(totalMs).toBe(1000);
+    expect(lanes.map(bar)).toEqual([
+      { leftPct: null, widthPct: 0 },
+      { leftPct: 0, widthPct: 100 },
+    ]);
+  });
+
+  it("clamps a sub-millisecond bar to the minimum visible width", () => {
+    const steps = [
+      step({ name: "blip", startedAt: T0, endedAt: T0 }),
+      step({ name: "long", startedAt: T0, endedAt: "2026-07-01T00:00:10.000Z" }),
+    ];
+    const { lanes } = buildTimelineLayout(steps, T0_MS);
+    expect(lanes.map((l) => l.widthPct)).toEqual([1.5, 100]);
+  });
+
+  it("extends an unfinished step to now", () => {
+    const now = T0_MS + 4000;
+    const steps = [step({ status: "running", startedAt: T0 })];
+    const { lanes, totalMs } = buildTimelineLayout(steps, now);
+    expect(totalMs).toBe(4000);
+    expect(lanes.map(bar)).toEqual([{ leftPct: 0, widthPct: 100 }]);
+  });
+});

package/src/lib/step-timeline.ts

@@ -0,0 +1,50 @@
+import type { Step } from "@durablex/react";
+
+export interface TimelineLane {
+  step: Step;
+  // Percentage offsets along the run's span; leftPct is null when the step never
+  // started (queued/skipped), so the view renders a placeholder instead of a bar.
+  leftPct: number | null;
+  widthPct: number;
+}
+
+export interface TimelineLayout {
+  lanes: TimelineLane[];
+  totalMs: number;
+}
+
+// A bar narrower than this is widened to stay visible (a sub-millisecond step on a
+// multi-second span would otherwise render as a hairline).
+const MIN_BAR_PCT = 1.5;
+
+// buildTimelineLayout places each step on a shared axis running from the earliest
+// step start to the latest end. An unfinished step (running/waiting) extends to
+// `now`, so its bar grows until it completes.
+export function buildTimelineLayout(steps: Step[], now: number): TimelineLayout {
+  // Parse each step's timestamps once; a not-started step has start === null and
+  // does not extend the axis (its placeholder bar carries no span).
+  const spans = steps.map((step) => ({
+    step,
+    start: step.startedAt ? Date.parse(step.startedAt) : null,
+    end: step.endedAt ? Date.parse(step.endedAt) : now,
+  }));
+
+  let min = Infinity;
+  let max = 0;
+  for (const s of spans) {
+    if (s.start === null) continue;
+    if (s.start < min) min = s.start;
+    if (s.end > max) max = s.end;
+  }
+  if (min === Infinity) min = 0;
+  const totalMs = Math.max(max - min, 1);
+
+  const lanes = spans.map<TimelineLane>(({ step, start, end }) => {
+    if (start === null) return { step, leftPct: null, widthPct: 0 };
+    const leftPct = ((start - min) / totalMs) * 100;
+    const widthPct = Math.max(((end - start) / totalMs) * 100, MIN_BAR_PCT);
+    return { step, leftPct, widthPct };
+  });
+
+  return { lanes, totalMs };
+}

package/src/lib/table.ts

@@ -0,0 +1,2 @@
+export const TABLE_HEAD_CLASS =
+  "text-muted-foreground/70 h-7 px-2 text-[10px] tracking-wider uppercase";

package/src/lib/theme.ts

@@ -0,0 +1,35 @@
+export const THEME_PREFS = ["light", "system", "dark"] as const;
+export type ThemePref = (typeof THEME_PREFS)[number];
+
+const KEY = "dx.theme";
+const query = "(prefers-color-scheme: dark)";
+
+export function getThemePref(): ThemePref {
+  const v = localStorage.getItem(KEY);
+  return v === "light" || v === "dark" ? v : "system";
+}
+
+function resolveDark(pref: ThemePref): boolean {
+  return pref === "system" ? window.matchMedia(query).matches : pref === "dark";
+}
+
+export function applyThemePref(pref: ThemePref): void {
+  const dark = resolveDark(pref);
+  document.documentElement.classList.toggle("dark", dark);
+  document.documentElement.style.colorScheme = dark ? "dark" : "light";
+}
+
+export function setThemePref(pref: ThemePref): void {
+  localStorage.setItem(KEY, pref);
+  applyThemePref(pref);
+}
+
+// Re-apply on OS change so the "system" preference stays live.
+export function watchSystemTheme(getPref: () => ThemePref): () => void {
+  const mq = window.matchMedia(query);
+  const onChange = () => {
+    if (getPref() === "system") applyThemePref("system");
+  };
+  mq.addEventListener("change", onChange);
+  return () => mq.removeEventListener("change", onChange);
+}