@usetheo/ui 0.22.1 → 0.26.0

package/dist/lib/chart/histogram.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Pure histogram binning — distributes numeric values into `binCount`
+ * equal-width bins over [min, max] and counts how many fall in each.
+ *
+ * Zero-dependency, total, deterministic (M11 ADR D2 — binning is pure logic,
+ * distinct from the SVG scaling reused from TrendChart). Non-finite values
+ * (NaN / ±Infinity) are dropped, mirroring the trace-core `Number.isFinite`
+ * discipline. A degenerate range (all values equal) collapses to a single
+ * populated bin so no count is lost.
+ */
+/** One histogram bucket: half-open [lo, hi) except the final bin, which is [lo, hi] (max-inclusive). */
+export interface HistogramBin {
+    lo: number;
+    hi: number;
+    count: number;
+}
+/**
+ * Bin `values` into `binCount` equal-width buckets.
+ * Returns `[]` for an empty input or a non-positive `binCount`.
+ */
+export declare function computeHistogram(values: number[], binCount: number): HistogramBin[];

package/dist/lib/chart/index.d.ts

@@ -0,0 +1 @@
+export * from "./histogram.js";

package/dist/lib/session/aggregate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure, total session-metric aggregation. Never throws, never does I/O. Honest sums: absent
+ * cost/tokens count as 0 (never NaN); the window is max(end) − min(start) over parseable timestamps
+ * (an unparseable start is skipped from the window, never a crash).
+ */
+import type { SessionMetrics, SessionTraceItem } from "./types.js";
+/**
+ * The session's wall-clock window in ns: [min start, max effective end] over the parseable
+ * timestamps. An unparseable start is skipped (never a crash); a clock-skewed/absent end falls back
+ * to its own start. A session with no parseable timestamps yields 0/0. This is the SINGLE definition
+ * of "a session's time window" — both `aggregateSession` (for `windowMs`) and `SessionTimeline` (for
+ * the per-trace bar denominator) consume it, so the window semantics live in one place.
+ */
+export declare function sessionBounds(items: SessionTraceItem[]): {
+    startNs: bigint;
+    endNs: bigint;
+};
+export declare function aggregateSession(items: SessionTraceItem[]): SessionMetrics;

package/dist/lib/session/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./aggregate.js";

package/dist/lib/session/types.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Data contracts for the session-level components (M9). A session groups traces that share a
+ * `session.id`; `SessionTraceItem` is the trace-level shape both `SessionSummary` and
+ * `SessionTimeline` consume — the intersection of the theo-lens traces-list row and the peer
+ * session views (phoenix numTraces+latency+cost, langfuse timestamp+name+latency). Timestamps
+ * accept unix-ns (bigint | numeric string) or ISO — normalized by the trace-core `toNs`.
+ */
+export interface SessionTraceItem {
+    id: string;
+    name?: string;
+    /** Unix ns (bigint | numeric string) or ISO-8601 string. */
+    startTime?: bigint | string;
+    /** Absent/null = in-flight (renders unbounded on the timeline). */
+    endTime?: bigint | string | null;
+    status?: "OK" | "ERROR";
+    model?: string;
+    costUsd?: number;
+    totalTokens?: number;
+}
+/** Aggregate metrics over a session's traces. All numeric fields are 0 (never NaN) when absent. */
+export interface SessionMetrics {
+    traceCount: number;
+    /** Session wall-clock window in ms: max(end) − min(start) across all traces. */
+    windowMs: number;
+    totalCostUsd: number;
+    totalTokens: number;
+    errorCount: number;
+    /** Distinct models seen, sorted. */
+    models: string[];
+}

package/dist/lib/trace/align.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure, total structural alignment + metric aggregation for comparing two
+ * traces. Never throws (cycle-guarded), never does I/O. Deltas are honest: a
+ * span present in only one trace has NO delta (never a fabricated 1:1 diff).
+ */
+import type { TraceSpan } from "./types.js";
+export interface TraceMetrics {
+    durationMs: number | null;
+    totalTokens: number;
+    costUsd: number;
+    hasError: boolean;
+    spanCount: number;
+}
+/** Aggregate whole-trace metrics: root duration, summed tokens/cost, any-error flag. Total. */
+export declare function traceMetrics(root: TraceSpan): TraceMetrics;
+export interface NumericDelta {
+    from: number | null;
+    to: number | null;
+    deltaPct: number | null;
+}
+export interface AlignDelta {
+    durationMs?: NumericDelta;
+    tokens?: NumericDelta;
+    costUsd?: NumericDelta;
+}
+export interface AlignRow {
+    key: string;
+    depth: number;
+    a?: TraceSpan;
+    b?: TraceSpan;
+    status: "matched" | "only-in-a" | "only-in-b";
+    /** Present ONLY when status === "matched" — an unpaired span has no honest delta. */
+    delta?: AlignDelta;
+}
+/**
+ * Align two span trees structurally, matching children by name (greedy,
+ * first-unused). Produces a flat, depth-annotated row list: matched pairs
+ * carry a delta; only-in-a / only-in-b rows do not. Cycle-safe via a visited
+ * set on span ids (a malformed self-referential tree cannot loop).
+ */
+export declare function alignSpanTrees(a: TraceSpan, b: TraceSpan): AlignRow[];

package/dist/lib/trace/attributes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure grouping of OTel span attributes by namespace (the prefix before the
+ * first `.`). Keys without a dot fall into the `general` namespace. Total —
+ * never throws; deterministic insertion order preserved within a group.
+ */
+export interface AttributeGroup {
+    namespace: string;
+    entries: Array<[string, unknown]>;
+}
+/** Group attribute entries by their dotted-key namespace, sorted by namespace name. */
+export declare function groupByNamespace(attrs: Record<string, unknown>): AttributeGroup[];

package/dist/lib/trace/bar-layout.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Waterfall-layout math: trace time envelope, per-span bar geometry, a
+ * human-friendly time axis, overlapping-span row packing, and ∑-cost
+ * aggregation. Every function is pure and total — it NEVER throws and NEVER
+ * does I/O — so skew / missing-timestamp / overlap / degenerate-bounds
+ * negative cases are provable without rendering.
+ */
+import type { TraceSpan } from "./types.js";
+/**
+ * Trace time bounds — min start / max end across ALL spans (ns, bigint-safe):
+ * the honest envelope for the waterfall denominator (not root-only, which
+ * would let a child overflow). Unparseable timestamps are skipped; a trace
+ * with no timestamps returns 0/0.
+ */
+export declare function computeTraceBounds(root: TraceSpan): {
+    startNs: bigint;
+    endNs: bigint;
+};
+export interface BarLayout {
+    leftPct: number;
+    widthPct: number;
+    unbounded: boolean;
+}
+/**
+ * Map a span's [start, end] against the trace bounds → clamped {leftPct,
+ * widthPct} in [0,100] with `leftPct + widthPct ≤ 100`. Missing end and
+ * clock-skew (end < start) are flagged `unbounded` with zero width — never a
+ * throw. Percentages carry 2 decimals via integer bigint math.
+ */
+export declare function computeBarLayout(spanStart: bigint | string | undefined, spanEnd: bigint | string | null | undefined, traceStartNs: bigint, traceEndNs: bigint): BarLayout;
+/** One tick on the waterfall time axis. */
+export interface AxisTick {
+    offsetNs: bigint;
+    label: string;
+    leftPct: number;
+}
+/**
+ * Human-friendly time axis: pick a step from the 1/2/5×10ⁿ ladder so ticks
+ * sit ≥70px apart, then emit ticks at 0, step, 2·step, … across the span.
+ * Total: a degenerate window or non-positive width yields an empty axis.
+ */
+export declare function niceAxisTicks(startNs: bigint, endNs: bigint, pxWidth: number): AxisTick[];
+/**
+ * Greedy single-pass row packing for overlapping spans: sort by start, then
+ * assign each span the lowest row whose last-placed span ended at/before this
+ * span's start. Returns `Map<id, rowIndex>`. Total: `[]` → empty map.
+ */
+export declare function packRows(spans: Array<{
+    id: string;
+    startNs: bigint;
+    endNs: bigint;
+}>): Map<string, number>;

package/dist/lib/trace/chat.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ChatML detection + payload pretty-print. Pure and total. Output is ALWAYS
+ * plain text/data — nothing here interprets HTML (the transcript/IO renderers
+ * inherit the no-dangerouslySetInnerHTML invariant from these totals).
+ */
+import type { ChatMessage } from "./types.js";
+/** Parse a value as a chat-message array (`[{role, content}, …]`) or null when it is not one. */
+export declare function asChat(value: string): ChatMessage[] | null;
+/** Pretty-print a stringified value as JSON when parseable, else leave it raw. Always plain text. */
+export declare function prettyValue(value: string): string;
+/** True when a message's content is redacted OR is/contains redacted thinking/reasoning. Pure, total. */
+export declare function isRedactedThinking(m: ChatMessage): boolean;
+/** Extract a plain-text body from a message's content (string, or joined text/thinking blocks). Total. */
+export declare function contentText(content: unknown): string;

package/dist/lib/trace/cost.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-span and subtree USD cost. Pure and total — missing/non-numeric costs
+ * collapse to 0 (never NaN) so `∑` badges stay honest.
+ */
+import type { TraceSpan } from "./types.js";
+/**
+ * A single span's own USD cost: the promoted `costUsd` field, else the first
+ * parseable cost attribute. Total: missing/non-numeric → 0 (never NaN);
+ * negative costs floor to 0.
+ */
+export declare function spanCostUsd(span: TraceSpan): number;
+/**
+ * Sum a span's own cost + all descendants' (`∑`). Total: missing cost counts as 0, never NaN.
+ * Cycle-safe: a repeated/self-referential child is counted at most once (no stack overflow).
+ */
+export declare function aggregateCost(span: TraceSpan): number;

package/dist/lib/trace/duration.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Timestamp normalization + duration math. Pure and total — never throws,
+ * never does I/O. All internal math is bigint ns (ADR D2 of the plan): no
+ * float precision loss on unix-ns timestamps.
+ */
+import type { SpanStatus, TraceSpan } from "./types.js";
+/**
+ * Normalize a timestamp to unix ns. Accepts bigint ns, a numeric string
+ * (treated as ns), or an ISO-8601 string (ms precision → ns). Returns null
+ * for anything unparseable — callers treat null as "cannot place this span".
+ */
+export declare function toNs(value: bigint | string | null | undefined): bigint | null;
+/** Span duration in ms; null when unavailable or clock-skewed (end < start). */
+export declare function durationMs(span: Pick<TraceSpan, "startTime" | "endTime">): number | null;
+/** Whether a span status counts as an error. Total: unknown statuses are not errors. */
+export declare function isSpanError(status: SpanStatus | string | undefined): boolean;
+/** Compact ms/s/min duration label (`1500 → "1.5s"`). Null → "in-flight". Pure, no locale. */
+export declare function formatDurationMs(ms: number | null): string;

package/dist/lib/trace/flatten.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tree flattening + the reader-mode transcript row model. Pure and total.
+ * `flattenVisible` order is the contract every renderer (tree, waterfall,
+ * transcript) shares, so selection/keyboard indices agree across views.
+ */
+import type { FlatSpan, TraceSpan, TranscriptRow } from "./types.js";
+/**
+ * Above this many visible rows, renderers switch from the recursive path to
+ * the react-virtual flat-list (blueprint Corner 2 Q9; langfuse uses 350, the
+ * lens origin uses 200 — virtualization only when it earns its complexity).
+ */
+export declare const VIRTUALIZE_THRESHOLD = 200;
+/**
+ * Depth-first flatten of ALL spans (ignores collapse) — resolve-by-id / envelope input. Cycle-safe:
+ * a self-referential or repeated child is visited at most once (a malformed trace cannot stack-overflow).
+ */
+export declare function flattenAll(root: TraceSpan): TraceSpan[];
+/**
+ * Depth-first flatten of VISIBLE spans (a node in `collapsed` contributes no descendants). Cycle-safe:
+ * each span id is emitted at most once.
+ */
+export declare function flattenVisible(root: TraceSpan, collapsed: Set<string>): FlatSpan[];
+/**
+ * Flatten a span tree into the ordered reader-mode transcript feed. Pre-order
+ * walk so `span`-row order matches `flattenVisible`. A fan-out node emits a
+ * `group-header` row BEFORE its child rows so the view can collapse the group.
+ */
+export declare function toTranscriptRows(root: TraceSpan): TranscriptRow[];

package/dist/lib/trace/graph-layout.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PURE, deterministic layered layout for the agent-graph view. No I/O, no
+ * React: derives each span's semantic kind, lays the trace out as a layered
+ * node-edge graph (depth = distance from root, order = index within depth),
+ * flags the root→selected execution path, and caps huge traces — so the SVG
+ * renderer stays thin. SVG-pure by ADR D4 of the blueprint (no elkjs/d3).
+ */
+import type { SpanKind, TraceSpan } from "./types.js";
+/**
+ * Derive a span's semantic kind from OTel GenAI signals (the raw `.kind`
+ * field is often the OTLP numeric — useless as agent/tool/LLM). Precedence:
+ * tool > retriever > embedding > llm > chain(has children) > unknown.
+ */
+export declare function deriveSpanKind(span: TraceSpan): SpanKind;
+/** Above this span count the graph renders an honest "too large" state. */
+export declare const GRAPH_NODE_CAP = 200;
+export interface GraphNode {
+    spanId: string;
+    name: string;
+    kind: SpanKind;
+    depth: number;
+    order: number;
+    x: number;
+    y: number;
+    error: boolean;
+    selected: boolean;
+    onPath: boolean;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    onPath: boolean;
+}
+export interface LayeredGraph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    width: number;
+    height: number;
+    truncated: boolean;
+    count: number;
+}
+/**
+ * Build the deterministic layered graph. Edges come from parent/call order
+ * (`parentId`), NOT the nested `children[]`, so malformed inputs are honest:
+ * a self-loop or cycle is broken by a visited set; a span whose `parentId`
+ * is absent from the trace is attached under the root, never dropped.
+ * `onPath` = root→selected ancestor chain; with no selection, root→deepest
+ * leaf. Over `cap` spans → `{ truncated: true, nodes: [], edges: [] }`.
+ */
+export declare function buildLayeredGraph(root: TraceSpan, selectedId?: string, cap?: number): LayeredGraph;
+/** Kind → display label. */
+export declare const KIND_LABEL: Record<SpanKind, string>;

package/dist/lib/trace/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./duration.js";
+export * from "./chat.js";
+export * from "./attributes.js";
+export * from "./align.js";
+export * from "./flatten.js";
+export * from "./bar-layout.js";
+export * from "./cost.js";
+export * from "./graph-layout.js";

package/dist/lib/trace/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared data contracts for the trace-native component family (M8).
+ *
+ * `TraceSpan` is the intersection of three real shapes (phoenix ISpanItem,
+ * langfuse observation, theo-lens TraceSpanNode — blueprint Corner 2): the
+ * smallest type every kit component consumes. Transport fields (tRPC/GraphQL)
+ * are deliberately absent. Timestamps accept unix-ns (bigint or numeric
+ * string) or an ISO-8601 string — `toNs()` normalizes at the boundary.
+ *
+ * Note: `bigint` values do not JSON-serialize — story/args tooling must use
+ * fixtures directly (EC-2 of the plan).
+ */
+/** OpenInference / OTel GenAI span-kind vocabulary (subset the kit renders). */
+export type SpanKind = "llm" | "tool" | "retriever" | "embedding" | "agent" | "chain" | "reranker" | "evaluator" | "guardrail" | "unknown";
+export type SpanStatus = "OK" | "ERROR" | "UNSET";
+export interface TraceSpan {
+    id: string;
+    parentId: string | null;
+    name: string;
+    /** Raw kind hint; semantic kind is derived via `deriveSpanKind` when absent. */
+    kind?: string;
+    /** Unix ns (bigint | numeric string) or ISO-8601 string. */
+    startTime?: bigint | string;
+    /** Absent/null = in-flight span (renders unbounded). */
+    endTime?: bigint | string | null;
+    status?: SpanStatus;
+    model?: string;
+    provider?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheCreationTokens?: number;
+    ttftMs?: number;
+    costUsd?: number;
+    /** Raw input/output payloads (JSON string, chat array JSON, or plain text). */
+    inputValue?: string;
+    outputValue?: string;
+    attributes?: Record<string, unknown>;
+    events?: Array<{
+        name: string;
+        time?: bigint | string;
+        attributes?: Record<string, unknown>;
+    }>;
+    children?: TraceSpan[];
+}
+/** One OpenAI-shaped tool call attached to an assistant message. */
+export interface ToolCall {
+    id: string;
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+/** ChatML message — the role vocabulary common to phoenix/langfuse/lens. */
+export interface ChatMessage {
+    role: string;
+    content: unknown;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+export interface FlatSpan {
+    span: TraceSpan;
+    depth: number;
+}
+/** Per-row micro-stats surfaced by the transcript feed. Missing inputs collapse to 0/null, never NaN. */
+export interface TranscriptRowStats {
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    durationMs: number | null;
+}
+/** One row in the reader-mode transcript feed. */
+export interface TranscriptRow {
+    kind: "span" | "group-header";
+    spanId: string;
+    role?: string;
+    preview?: string;
+    stats?: TranscriptRowStats;
+    groupId?: string;
+}

package/dist/test/fixtures/trace.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared trace fixtures for the trace-native component family (M8 T1.1).
+ * Modeled after real agent traces from the theo-lens suite: branching,
+ * a retried tool call, an errored span, an orphan (malformed parent) and a
+ * clock-skewed span. Deterministic — no Date.now(), no randomness.
+ */
+import type { TraceSpan } from "../../lib/trace/types.js";
+/**
+ * Nested agent trace: root agent → llm plan → 2 tool branches (one retried,
+ * one errored) → final llm answer. 7 spans, depth 3.
+ */
+export declare const NESTED_TRACE: TraceSpan;
+/** Trace with an orphan (parent missing from the tree) and a clock-skewed span. */
+export declare const MALFORMED_TRACE: TraceSpan;
+/**
+ * Deterministic wide trace generator for virtualization paths: `n` children
+ * under one root, timings derived from the index (no randomness).
+ */
+export declare function makeTrace(n: number): TraceSpan;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usetheo/ui",
-  "version": "0.22.1",
+  "version": "0.26.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Violet Forge design system — generic React components + primitives (the non-AI foundation of @theokit/ui).",
@@ -51,6 +51,7 @@
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@ladle/react": "^4.1.2",
+    "@tailwindcss/vite": "^4.3.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",
@@ -71,6 +72,7 @@
   },
   "_provenance": "seeded from theo-ui @ 2b46eca (2026-07-03, pivot M-B)",
   "scripts": {
+    "dev": "ladle serve",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src",
     "lint:ci": "biome check src",