assistant-ui--assistant-ui/packages/react-o11y/README.md

@assistant-ui/react-o11y

Headless React primitives for rendering span and trace UIs (waterfalls, timelines, run inspectors) on top of @assistant-ui/store. Ships a tap-based SpanResource that owns the data and a set of unstyled SpanPrimitive.* components for laying it out.

Installation

npm install @assistant-ui/react-o11y

Usage

"use client";

import { AuiProvider, useAui } from "@assistant-ui/store";
import { SpanPrimitive, SpanResource } from "@assistant-ui/react-o11y";

const spans = [
  { id: "a", parentSpanId: null, name: "request", type: "http", status: "completed", startedAt: 0, endedAt: 120, latencyMs: 120 },
  { id: "b", parentSpanId: "a", name: "db query", type: "db", status: "completed", startedAt: 10, endedAt: 80, latencyMs: 70 },
];

export function Waterfall() {
  const aui = useAui({ span: SpanResource({ spans }) });
  return (
    <AuiProvider value={aui}>
      <SpanPrimitive.Timeline>
        <SpanPrimitive.Children>
          {() => (
            <div className="relative h-8">
              <SpanPrimitive.TimelineBar className="top-1 h-6 rounded bg-blue-500" />
            </div>
          )}
        </SpanPrimitive.Children>
      </SpanPrimitive.Timeline>
    </AuiProvider>
  );
}

SpanPrimitive.* components rendered inside <AuiProvider> cover rows, indentation, names, status, collapse controls, and timeline bars. SpanPrimitive.Timeline provides the time range for its children; SpanPrimitive.TimelineBar positions each current span with CSS variables such as --span-timeline-left and --span-timeline-width. Running bars use the timeline range max unless you pass an explicit now timestamp from your own effect or animation loop.

See examples/waterfall for a complete waterfall implementation.