@distlang/timeline-viz

Reusable React and Chart.js timeline visualizations.

V1 supports two views:

• waterfall
• waterfall-with-edges

The package is intentionally generic. It does not know about Distlang Dashboard, AI Debugger, OpenCode, traces, builds, or agents. It renders timeline rows, bars, and optional causal edges.

Install

npm install @distlang/timeline-viz chart.js react-chartjs-2

react, react-dom, chart.js, and react-chartjs-2 are peer dependencies.

Local Demo

From this repository:

npm install
npm run dev

Open the Vite URL shown in the terminal. The demo includes:

• a basic waterfall timeline
• a waterfall timeline with causal edges
• bar selection
• light/dark theme toggle
• legend, time breakdown, and longest-task helpers

Quick Start

import {
  TimelineViz,
  TimelineLegend,
  calculateCategoryDurations,
  type TimelineEdge,
  type TimelineVizData,
} from "@distlang/timeline-viz";
import "@distlang/timeline-viz/styles.css";

const data: TimelineVizData = {
  rows: [
    {
      id: "agent",
      label: "Agent",
      bars: [
        {
          id: "llm-1",
          label: "Model call",
          category: "llm_call",
          startMs: 0,
          endMs: 4200,
        },
        {
          id: "tool-1",
          label: "Tool call",
          category: "tool_call",
          startMs: 4300,
          endMs: 6200,
        },
      ],
    },
  ],
};

const edges: TimelineEdge[] = [
  { from: "llm-1", to: "tool-1" },
];

export function Example() {
  return (
    <TimelineViz
      data={data}
      view="waterfall-with-edges"
      edges={edges}
      theme="light"
      onSelect={(id) => console.log(id)}
    />
  );
}

Views

waterfall

Shows bars across elapsed time. Overlapping bars in the same row are automatically assigned to lanes.

<TimelineViz data={data} view="waterfall" />

waterfall-with-edges

Shows the same waterfall timeline with causal connectors between bars.

<TimelineViz data={data} view="waterfall-with-edges" edges={edges} />

Advanced form:

<TimelineViz
  data={data}
  edges={edges}
  view={{
    type: "waterfall",
    preset: "with-edges",
    options: {
      edgeOpacity: 0.25,
      drawEdgesBehindBars: true,
    },
  }}
/>

Data Model

type TimelineVizData = {
  rows?: TimelineRowInput[];
  model?: TimelineModel;
  fallbackEndMs?: number;
};

type TimelineRowInput = {
  id: string;
  label: string;
  groupLabel?: string;
  bars: TimelineInputBar[];
};

type TimelineInputBar = {
  id: string;
  rowId?: string;
  label: string;
  category?: string;
  status?: string;
  startMs: number;
  endMs: number;
  durationMs?: number;
  tooltip?: Array<{ label: string; value: string }>;
  metadata?: unknown;
};

rowId is optional on input bars. If omitted, it defaults to the containing row's id.

Edges

type TimelineEdge = {
  from: string;
  to: string;
  status?: "default" | "active" | "muted" | "error";
  weight?: number;
};

Edges connect bar IDs. The renderer skips edges when either endpoint is missing.

Styling

Import the default CSS:

import "@distlang/timeline-viz/styles.css";

The CSS uses custom properties so host apps can theme it:

.my-timeline-shell {
  --timeline-viz-accent: rgb(99, 102, 241);
  --timeline-viz-border-color: rgba(148, 163, 184, 0.35);
  --timeline-viz-muted-text: rgba(71, 85, 105, 0.9);
  --timeline-viz-surface-muted: rgba(255, 255, 255, 0.78);
  --timeline-viz-text: rgb(15, 23, 42);
}

Exports

TimelineViz
WaterfallTimeline
TimelineLegend
TimeBreakdown
LongestTasks
buildTimelineModel
calculateCategoryDurations
calculateConcurrency
findLongestBars
type TimelineEdge
type TimelineVizData

Release Checklist

npm run build
npm run pack:check
npm publish --access public

Future Views

Future versions may add flame, tree, or collapsed interactive renderers. V1 only exposes waterfall and waterfall-with-edges as supported views.