@usetheo/ui 0.23.0 → 0.26.0

package/dist/components/composites/annotation-input/annotation-input.d.ts

@@ -0,0 +1,38 @@
+import type { AnnotationCategoricalConfig, AnnotationContinuousConfig, AnnotationFreeformConfig } from "./types.js";
+/**
+ * AnnotationInput — a controlled, config-driven human annotation input (M12).
+ * Dispatches on `config.type` (Phoenix's three-type model): categorical →
+ * RadioGroup over named options; continuous → number input bounded by the
+ * config; freeform → textarea. Fully controlled (`value` + `onValueChange`);
+ * the consumer owns the config (fixture or backend store) and the submission.
+ * Composes the DS form primitives — zero new dependency (M12 ADR D2).
+ *
+ *   <AnnotationInput name="Quality" config={qualityConfig}
+ *                    value={v} onValueChange={setV} />
+ */
+interface AnnotationInputCommon {
+    /** The score name — rendered as the field label / radiogroup accessible name. */
+    name: string;
+    /** Overrides the generated control id (for external label association). */
+    id?: string;
+    /** Optional helper text, wired via aria-describedby. */
+    description?: string;
+    required?: boolean;
+    disabled?: boolean;
+    className?: string;
+}
+export type AnnotationInputProps = (AnnotationInputCommon & {
+    config: AnnotationCategoricalConfig;
+    value: string | null;
+    onValueChange: (value: string | null) => void;
+}) | (AnnotationInputCommon & {
+    config: AnnotationContinuousConfig;
+    value: number | null;
+    onValueChange: (value: number | null) => void;
+}) | (AnnotationInputCommon & {
+    config: AnnotationFreeformConfig;
+    value: string | null;
+    onValueChange: (value: string | null) => void;
+});
+declare function AnnotationInput(props: AnnotationInputProps): import("react").JSX.Element;
+export { AnnotationInput };

package/dist/components/composites/annotation-input/index.d.ts

@@ -0,0 +1,4 @@
+export { AnnotationInput } from "./annotation-input.js";
+export type { AnnotationInputProps } from "./annotation-input.js";
+export type { CategoricalOption, AnnotationCategoricalConfig, AnnotationContinuousConfig, AnnotationFreeformConfig, AnnotationConfig, } from "./types.js";
+export { isCategoricalConfig, isContinuousConfig, isFreeformConfig } from "./types.js";

package/dist/components/composites/annotation-input/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Annotation config types — the named-score-type contract for AnnotationInput
+ * (M12). Follows Phoenix's three-type model (categorical / continuous /
+ * freeform); Langfuse's BOOLEAN is categorical-of-two and CORRECTION is
+ * system-only, so neither adds to a controlled human input. The config is a
+ * plain descriptor the consumer owns (fixture or backend store) — the DS
+ * component is config-driven and stateless.
+ */
+/** One named categorical choice; `score` optionally maps the label to a numeric value on submit. */
+export interface CategoricalOption {
+    label: string;
+    score?: number | null;
+}
+export interface AnnotationCategoricalConfig {
+    type: "categorical";
+    options: CategoricalOption[];
+}
+export interface AnnotationContinuousConfig {
+    type: "continuous";
+    min: number;
+    max: number;
+    step?: number;
+}
+export interface AnnotationFreeformConfig {
+    type: "freeform";
+    maxLength?: number;
+}
+export type AnnotationConfig = AnnotationCategoricalConfig | AnnotationContinuousConfig | AnnotationFreeformConfig;
+export declare function isCategoricalConfig(c: AnnotationConfig): c is AnnotationCategoricalConfig;
+export declare function isContinuousConfig(c: AnnotationConfig): c is AnnotationContinuousConfig;
+export declare function isFreeformConfig(c: AnnotationConfig): c is AnnotationFreeformConfig;

package/dist/components/composites/histogram/histogram.d.ts

@@ -0,0 +1,19 @@
+import type { HTMLAttributes } from "react";
+import { type HistogramBin } from "../../../lib/chart/histogram.js";
+type HistogramData = {
+    bins: HistogramBin[];
+    values?: never;
+    binCount?: never;
+} | {
+    values: number[];
+    binCount: number;
+    bins?: never;
+};
+export type HistogramProps = HTMLAttributes<HTMLElement> & {
+    title: string;
+    height?: number;
+    /** Formats the count axis label and the bin bounds in the a11y table. */
+    valueFormatter?: (v: number) => string;
+} & HistogramData;
+declare const Histogram: import("react").ForwardRefExoticComponent<HistogramProps & import("react").RefAttributes<HTMLElement>>;
+export { Histogram };

package/dist/components/composites/histogram/index.d.ts

@@ -0,0 +1,2 @@
+export { Histogram } from "./histogram.js";
+export type { HistogramProps } from "./histogram.js";

package/dist/components/composites/percentile-chart/index.d.ts

@@ -0,0 +1,2 @@
+export { PercentileChart } from "./percentile-chart.js";
+export type { PercentileBucket, PercentileChartProps } from "./percentile-chart.js";

package/dist/components/composites/percentile-chart/percentile-chart.d.ts

@@ -0,0 +1,37 @@
+import type { HTMLAttributes } from "react";
+/**
+ * PercentileChart — p50/p95/p99 over time as shaded BANDS (not three flat
+ * lines), pure-SVG (M3 anti-chart-lib ADR upheld, M11 ADR D1). The p50–p95 and
+ * p95–p99 spans render as filled areas + a p50 reference line, so the spread is
+ * read at a glance (phoenix `TraceLatencyPercentilesTimeSeries` pattern, M11
+ * ADR D2 — the upgrade over the lens' current three-line overlay). Reuses
+ * `linScale`/`niceMax`/`seriesPath` from TrendChart — zero new chart dep.
+ *
+ *   <PercentileChart title="Latency" buckets={latencyBuckets}
+ *                    valueFormatter={(v) => `${v}ms`} />
+ */
+export interface PercentileBucket {
+    /** p50 value for this time bucket. */
+    p50: number;
+    /** p95 value for this time bucket. */
+    p95: number;
+    /** p99 value for this time bucket. */
+    p99: number;
+    /** Optional bucket label (read in the a11y table). */
+    label?: string;
+}
+export type PercentileChartProps = HTMLAttributes<HTMLElement> & {
+    title: string;
+    buckets: PercentileBucket[];
+    height?: number;
+    /** Formats the y-axis label and the a11y table cells. */
+    valueFormatter?: (v: number) => string;
+};
+declare const PercentileChart: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & {
+    title: string;
+    buckets: PercentileBucket[];
+    height?: number;
+    /** Formats the y-axis label and the a11y table cells. */
+    valueFormatter?: (v: number) => string;
+} & import("react").RefAttributes<HTMLElement>>;
+export { PercentileChart };

package/dist/components/composites/session-summary/index.d.ts

@@ -0,0 +1 @@
+export { SessionSummary, type SessionSummaryProps } from "./session-summary.js";

package/dist/components/composites/session-summary/session-summary.d.ts

@@ -0,0 +1,18 @@
+import type { SessionMetrics, SessionTraceItem } from "../../../lib/session/types.js";
+export interface SessionSummaryProps {
+    /** The session's traces — aggregated internally. Supply `metrics` instead to pass a pre-aggregate. */
+    items?: SessionTraceItem[];
+    /** Pre-computed metrics (overrides `items`). */
+    metrics?: SessionMetrics;
+    /** USD cost formatter. Default `$0.0000`. */
+    formatCostUsd?: (usd: number) => string;
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * SessionSummary — a `<dl>` of honest aggregate metrics over a session's traces: trace count, the
+ * session wall-clock window, ∑ cost, ∑ tokens, error count (highlighted destructive when > 0), and
+ * the distinct models. Sums of zero are honest (`$0.0000`, `0`), never an em-dash. Pass `items` (it
+ * aggregates via `aggregateSession`) or a pre-computed `metrics`.
+ */
+export declare function SessionSummary({ items, metrics, formatCostUsd, className, "aria-label": ariaLabel, }: SessionSummaryProps): import("react").JSX.Element;

package/dist/components/composites/session-timeline/index.d.ts

@@ -0,0 +1 @@
+export { SessionTimeline, type SessionTimelineProps } from "./session-timeline.js";

package/dist/components/composites/session-timeline/session-timeline.d.ts

@@ -0,0 +1,22 @@
+import type { SessionTraceItem } from "../../../lib/session/types.js";
+export interface SessionTimelineProps {
+    /** The session's traces (rendered in start-time order regardless of input order). */
+    items: SessionTraceItem[];
+    selectedId: string | null;
+    onSelect: (id: string) => void;
+    /** ns → label for the row timestamp. Default ISO datetime. */
+    formatTimestamp?: (ns: bigint) => string;
+    /** USD cost formatter. Default `$0.0000`. */
+    formatCostUsd?: (usd: number) => string;
+    /** Row count at/above which the virtualized path engages. Default 200. */
+    virtualizeThreshold?: number;
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * SessionTimeline — a temporal replay of a session: one row per trace, sorted by start time, each
+ * showing the timestamp, name, a duration bar relative to the session window (via the trace-core
+ * `computeBarLayout`), status, and cost. Controlled selection; virtualizes above the threshold.
+ * Escaped text only.
+ */
+export declare function SessionTimeline({ items, selectedId, onSelect, formatTimestamp, formatCostUsd, virtualizeThreshold, className, "aria-label": ariaLabel, }: SessionTimelineProps): import("react").JSX.Element;

package/dist/index.d.ts

@@ -77,3 +77,17 @@ export { SpanGraph } from "./components/composites/span-graph/index.js";
 export type { SpanGraphProps } from "./components/composites/span-graph/index.js";
 export { TraceCompare } from "./components/composites/trace-compare/index.js";
 export type { TraceCompareProps, CompareLane, } from "./components/composites/trace-compare/index.js";
+export { aggregateSession, sessionBounds } from "./lib/session/index.js";
+export type { SessionTraceItem, SessionMetrics } from "./lib/session/index.js";
+export { SessionSummary } from "./components/composites/session-summary/index.js";
+export type { SessionSummaryProps } from "./components/composites/session-summary/index.js";
+export { SessionTimeline } from "./components/composites/session-timeline/index.js";
+export type { SessionTimelineProps } from "./components/composites/session-timeline/index.js";
+export { computeHistogram } from "./lib/chart/index.js";
+export type { HistogramBin } from "./lib/chart/index.js";
+export { Histogram } from "./components/composites/histogram/index.js";
+export type { HistogramProps } from "./components/composites/histogram/index.js";
+export { PercentileChart } from "./components/composites/percentile-chart/index.js";
+export type { PercentileBucket, PercentileChartProps, } from "./components/composites/percentile-chart/index.js";
+export { AnnotationInput, isCategoricalConfig, isContinuousConfig, isFreeformConfig, } from "./components/composites/annotation-input/index.js";
+export type { AnnotationInputProps, CategoricalOption, AnnotationCategoricalConfig, AnnotationContinuousConfig, AnnotationFreeformConfig, AnnotationConfig, } from "./components/composites/annotation-input/index.js";

package/dist/index.js

@@ -7535,4 +7535,617 @@ function DeltaCell({
   ] });
 }
 
-export { AccountMenu, ActionBar, Alert, AttributesTable, Avatar, BadgeWithDot as Badge, Breadcrumb, Button, Card, Checkbox, CodeBlock, Combobox, CommandPalette, ConfirmDialog, CopyButton, DangerZone, DataTable, DeploymentRow, DescriptionList, Dialog, DomainConfig, DropdownMenu, EmptyState, EnvVarEditor, FileDropzone, FormField, GRAPH_NODE_CAP, IOCards, Input, JsonViewer, KIND_LABEL, Label, LoginSplit, MessageCard, MessageItem, MetricCard, MetricsPanel, PageShell, Pagination, PinInput, PlanBadge, PreviewEnvCard, Progress, ProjectCard, RadioGroup, RollbackUI, ScrollArea, Select, Sheet, Sidebar, Skeleton, Slider, SocialAuthRow, SpanGraph, SpanTree, SpanTreeRow, SpanWaterfall, StatTile, StatusDot, StatusIndicator, Stepper, Switch, Table, Tabs, TaskHeader, Textarea, Timestamp, Toast, Toaster, TooltipWithStatics as Tooltip, TopNav, TraceCompare, TraceTranscript, TrendChart, UpdateBanner, VIRTUALIZE_THRESHOLD, aggregateCost, alignSpanTrees, asChat, avatarVariants, badgeVariants, buildLayeredGraph, buttonVariants, cn, computeBarLayout, computePageRange, computeTraceBounds, contentText, deriveSpanKind, deriveSteps, durationMs, flattenAll, flattenVisible, groupByNamespace, isNearBottom, isRedactedThinking, isSpanError, linScale, matchesAccept, niceAxisTicks, niceMax, packRows, prettyValue, seriesPath, sheetVariants, spanCostUsd, toNs, toTranscriptRows, traceMetrics, useStickToBottom, useToast, validateFiles };
+// src/lib/session/aggregate.ts
+function sessionBounds(items) {
+  let minStart = null;
+  let maxEnd = null;
+  for (const it of items) {
+    const start = toNs(it.startTime);
+    if (start === null) continue;
+    if (minStart === null || start < minStart) minStart = start;
+    const end = toNs(it.endTime ?? null) ?? start;
+    const eff = end >= start ? end : start;
+    if (maxEnd === null || eff > maxEnd) maxEnd = eff;
+  }
+  const s = minStart ?? 0n;
+  return { startNs: s, endNs: maxEnd ?? s };
+}
+function aggregateSession(items) {
+  let totalCostUsd = 0;
+  let totalTokens = 0;
+  let errorCount = 0;
+  const models = /* @__PURE__ */ new Set();
+  for (const it of items) {
+    if (typeof it.costUsd === "number" && Number.isFinite(it.costUsd) && it.costUsd > 0) {
+      totalCostUsd += it.costUsd;
+    }
+    if (typeof it.totalTokens === "number" && Number.isFinite(it.totalTokens) && it.totalTokens > 0) {
+      totalTokens += it.totalTokens;
+    }
+    if (it.status === "ERROR") errorCount++;
+    if (it.model) models.add(it.model);
+  }
+  const { startNs, endNs } = sessionBounds(items);
+  const windowMs = Number((endNs - startNs) / 1000000n);
+  return {
+    traceCount: items.length,
+    windowMs,
+    totalCostUsd,
+    totalTokens,
+    errorCount,
+    models: [...models].sort()
+  };
+}
+var defaultCost4 = (usd) => `$${usd.toFixed(4)}`;
+function SessionSummary({
+  items,
+  metrics,
+  formatCostUsd = defaultCost4,
+  className,
+  "aria-label": ariaLabel = "Session summary"
+}) {
+  const m = useMemo(() => metrics ?? aggregateSession(items ?? []), [metrics, items]);
+  return /* @__PURE__ */ jsxs(
+    "dl",
+    {
+      "data-slot": "session-summary",
+      "aria-label": ariaLabel,
+      className: cn(
+        "grid grid-cols-2 gap-3 rounded-md border border-border bg-muted/20 p-3 text-xs sm:grid-cols-3 lg:grid-cols-6",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ jsx(Stat2, { label: "Traces", value: String(m.traceCount) }),
+        /* @__PURE__ */ jsx(
+          Stat2,
+          {
+            label: "Duration",
+            value: m.windowMs > 0 ? formatDurationMs(m.windowMs) : "\u2014",
+            testId: "session-duration"
+          }
+        ),
+        /* @__PURE__ */ jsx(Stat2, { label: "Cost", value: formatCostUsd(m.totalCostUsd), testId: "session-cost" }),
+        /* @__PURE__ */ jsx(Stat2, { label: "Tokens", value: String(m.totalTokens), testId: "session-tokens" }),
+        /* @__PURE__ */ jsxs("div", { children: [
+          /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: "Errors" }),
+          /* @__PURE__ */ jsx(
+            "dd",
+            {
+              "data-slot": "session-error",
+              "data-error": m.errorCount > 0 ? "true" : void 0,
+              className: cn(
+                "font-medium font-mono tabular-nums",
+                m.errorCount > 0 && "text-destructive"
+              ),
+              children: m.errorCount
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsxs("div", { className: "min-w-0", children: [
+          /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: "Models" }),
+          /* @__PURE__ */ jsx("dd", { "data-testid": "session-models", className: "flex flex-wrap gap-1", children: m.models.length > 0 ? m.models.map((model) => /* @__PURE__ */ jsx(BadgeWithDot, { variant: "outline", className: "font-mono", children: model }, model)) : /* @__PURE__ */ jsx("span", { className: "text-muted-foreground", children: "\u2014" }) })
+        ] })
+      ]
+    }
+  );
+}
+function Stat2({ label, value, testId }) {
+  return /* @__PURE__ */ jsxs("div", { children: [
+    /* @__PURE__ */ jsx("dt", { className: "text-muted-foreground", children: label }),
+    /* @__PURE__ */ jsx("dd", { "data-testid": testId, className: "font-medium font-mono tabular-nums", children: value })
+  ] });
+}
+var defaultTimestamp2 = (ns) => new Date(Number(ns / 1000000n)).toISOString();
+var defaultCost5 = (usd) => `$${usd.toFixed(4)}`;
+function SessionTimeline({
+  items,
+  selectedId,
+  onSelect,
+  formatTimestamp = defaultTimestamp2,
+  formatCostUsd = defaultCost5,
+  virtualizeThreshold = 200,
+  className,
+  "aria-label": ariaLabel = "Session timeline"
+}) {
+  const sorted = useMemo(() => {
+    const withNs = items.map((it) => ({ it, ns: toNs(it.startTime) ?? 0n }));
+    withNs.sort((a, b) => a.ns < b.ns ? -1 : a.ns > b.ns ? 1 : a.it.id < b.it.id ? -1 : 1);
+    return withNs.map((w) => w.it);
+  }, [items]);
+  const bounds = useMemo(() => sessionBounds(sorted), [sorted]);
+  if (sorted.length === 0) {
+    return /* @__PURE__ */ jsx(EmptyState, { title: "No traces", description: "This session has no traces to replay." });
+  }
+  const virtualized = sorted.length >= virtualizeThreshold;
+  const ctx = { bounds, selectedId, onSelect, formatTimestamp, formatCostUsd };
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: role="list" keeps the virtualized wrapper divs valid (a <div> cannot be an <li>)
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        role: "list",
+        "data-slot": "session-timeline",
+        "aria-label": ariaLabel,
+        className: cn("space-y-1", className),
+        children: virtualized ? /* @__PURE__ */ jsx(VirtualRows, { items: sorted, ...ctx }) : sorted.map((it) => /* @__PURE__ */ jsx(Row4, { item: it, ...ctx }, it.id))
+      }
+    )
+  );
+}
+function Row4({ item, ...ctx }) {
+  const { leftPct, widthPct, unbounded } = computeBarLayout(
+    item.startTime,
+    item.endTime,
+    ctx.bounds.startNs,
+    ctx.bounds.endNs
+  );
+  const error = isSpanError(item.status);
+  const selected = item.id === ctx.selectedId;
+  const startNs = toNs(item.startTime);
+  const dur = durationMs({ startTime: item.startTime, endTime: item.endTime });
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: pairs with the role="list" container (virtualized wrappers forbid <li>)
+    /* @__PURE__ */ jsx("div", { role: "listitem", children: /* @__PURE__ */ jsxs(
+      "button",
+      {
+        type: "button",
+        "data-slot": "session-timeline-row",
+        "aria-current": selected ? "true" : void 0,
+        onClick: () => ctx.onSelect(item.id),
+        className: cn(
+          "flex w-full items-center gap-3 rounded-md p-2 text-left hover:bg-muted/40",
+          selected && "bg-muted ring-1 ring-primary"
+        ),
+        children: [
+          /* @__PURE__ */ jsx("span", { className: "w-32 shrink-0 font-mono text-[10px] text-muted-foreground", children: startNs !== null ? ctx.formatTimestamp(startNs) : "\u2014" }),
+          /* @__PURE__ */ jsx("span", { "data-testid": "session-trace-name", className: "w-40 shrink-0 truncate font-mono text-xs", children: item.name ?? item.id }),
+          /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: "relative block h-4 flex-1 overflow-hidden rounded-sm bg-muted/30",
+              "aria-hidden": "true",
+              children: /* @__PURE__ */ jsx(
+                "span",
+                {
+                  "data-slot": "session-timeline-bar",
+                  "data-error": error ? "true" : void 0,
+                  "data-unbounded": unbounded ? "true" : void 0,
+                  style: { left: `${leftPct}%`, width: `${widthPct}%`, minWidth: "2px" },
+                  className: cn(
+                    "absolute top-0.5 bottom-0.5 rounded-sm",
+                    error ? "bg-destructive" : "bg-primary/60",
+                    unbounded && "border border-primary/60 border-dashed bg-transparent"
+                  )
+                }
+              )
+            }
+          ),
+          /* @__PURE__ */ jsx("span", { className: "shrink-0 text-[10px] text-muted-foreground tabular-nums", children: dur !== null ? formatDurationMs(dur) : "\u2014" }),
+          item.costUsd !== void 0 ? /* @__PURE__ */ jsx(BadgeWithDot, { variant: "outline", className: "shrink-0 font-mono text-[10px]", children: ctx.formatCostUsd(item.costUsd) }) : null,
+          error ? /* @__PURE__ */ jsx(BadgeWithDot, { variant: "destructive", className: "shrink-0", children: "error" }) : null
+        ]
+      }
+    ) })
+  );
+}
+function VirtualRows({ items, ...ctx }) {
+  const parentRef = useRef(null);
+  const virtualizer = useVirtualizer({
+    count: items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 44,
+    overscan: 12,
+    initialRect: { width: 640, height: 640 }
+  });
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ref: parentRef,
+      "data-slot": "session-timeline-virtual",
+      className: "max-h-[70vh] overflow-auto",
+      children: /* @__PURE__ */ jsx("div", { style: { height: virtualizer.getTotalSize(), position: "relative", width: "100%" }, children: virtualizer.getVirtualItems().map((vi) => {
+        const item = items[vi.index];
+        if (!item) return null;
+        return /* @__PURE__ */ jsx(
+          "div",
+          {
+            "data-index": vi.index,
+            ref: virtualizer.measureElement,
+            style: {
+              position: "absolute",
+              top: 0,
+              left: 0,
+              width: "100%",
+              transform: `translateY(${vi.start}px)`
+            },
+            children: /* @__PURE__ */ jsx(Row4, { item, ...ctx })
+          },
+          `${vi.index}-${item.id}`
+        );
+      }) })
+    }
+  );
+}
+
+// src/lib/chart/histogram.ts
+function computeHistogram(values, binCount) {
+  if (!Number.isFinite(binCount) || binCount <= 0) return [];
+  const finite = values.filter((v) => Number.isFinite(v));
+  if (finite.length === 0) return [];
+  const n = Math.floor(binCount);
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const v of finite) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  const span = max - min;
+  const width = span / n;
+  const bins = Array.from({ length: n }, (_, i) => ({
+    lo: span === 0 ? min : min + i * width,
+    hi: span === 0 ? min : min + (i + 1) * width,
+    count: 0
+  }));
+  for (const v of finite) {
+    const idx = span === 0 ? 0 : Math.min(n - 1, Math.floor((v - min) / width));
+    const bin = bins[idx];
+    if (bin) bin.count += 1;
+  }
+  return bins;
+}
+var VIEW_W2 = 600;
+var PAD3 = { top: 8, right: 8, bottom: 4, left: 40 };
+var BAR_GAP = 2;
+var Histogram = forwardRef((props, ref) => {
+  const {
+    title,
+    height = 180,
+    valueFormatter = (v) => String(v),
+    className,
+    bins: binsProp,
+    values,
+    binCount,
+    ...rest
+  } = props;
+  const bins = binsProp ?? computeHistogram(values ?? [], binCount ?? 0);
+  const hasData = bins.length > 0 && bins.some((b) => b.count > 0);
+  if (!hasData) {
+    return /* @__PURE__ */ jsxs(
+      "figure",
+      {
+        "data-slot": "histogram",
+        ref,
+        className: cn("space-y-1", className),
+        "aria-label": `${title} \u2014 no data`,
+        ...rest,
+        children: [
+          /* @__PURE__ */ jsx("figcaption", { className: "font-semibold text-label-caps text-muted-foreground uppercase", children: title }),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-slot": "histogram-empty",
+              className: "flex items-center justify-center rounded-md border border-dashed text-body-sm text-muted-foreground",
+              style: { height },
+              children: "No data to distribute."
+            }
+          )
+        ]
+      }
+    );
+  }
+  const countMax = niceMax(bins.map((b) => b.count)) || 1;
+  const yScale = linScale([0, countMax], [height - PAD3.bottom, PAD3.top]);
+  const plotW = VIEW_W2 - PAD3.left - PAD3.right;
+  const slotW = plotW / bins.length;
+  const barW = Math.max(1, slotW - BAR_GAP);
+  return /* @__PURE__ */ jsxs("figure", { "data-slot": "histogram", ref, className: cn("space-y-1", className), ...rest, children: [
+    /* @__PURE__ */ jsx("figcaption", { className: "font-semibold text-label-caps text-muted-foreground uppercase", children: title }),
+    /* @__PURE__ */ jsxs(
+      "svg",
+      {
+        viewBox: `0 0 ${VIEW_W2} ${height}`,
+        preserveAspectRatio: "none",
+        role: "img",
+        "aria-label": `${title} distribution`,
+        className: "w-full",
+        style: { height },
+        children: [
+          /* @__PURE__ */ jsx(
+            "line",
+            {
+              x1: PAD3.left,
+              y1: height - PAD3.bottom,
+              x2: VIEW_W2 - PAD3.right,
+              y2: height - PAD3.bottom,
+              className: "stroke-border",
+              strokeWidth: 1
+            }
+          ),
+          /* @__PURE__ */ jsx("text", { x: 4, y: PAD3.top + 8, className: "fill-muted-foreground text-[10px]", children: valueFormatter(countMax) }),
+          /* @__PURE__ */ jsx("text", { x: 4, y: height - PAD3.bottom, className: "fill-muted-foreground text-[10px]", children: "0" }),
+          bins.map((b, i) => {
+            const y = yScale(b.count);
+            const barH = Math.max(0, height - PAD3.bottom - y);
+            return /* @__PURE__ */ jsx(
+              "rect",
+              {
+                "data-slot": "histogram-bar",
+                "data-count": b.count,
+                x: PAD3.left + i * slotW + BAR_GAP / 2,
+                y,
+                width: barW,
+                height: barH,
+                className: "fill-primary",
+                children: /* @__PURE__ */ jsx("title", { children: `${valueFormatter(b.lo)}\u2013${valueFormatter(b.hi)}: ${b.count}` })
+              },
+              i
+            );
+          })
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs("table", { "data-slot": "histogram-table", className: "sr-only", children: [
+      /* @__PURE__ */ jsxs("caption", { children: [
+        title,
+        " \u2014 data table"
+      ] }),
+      /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+        /* @__PURE__ */ jsx("th", { children: "Range" }),
+        /* @__PURE__ */ jsx("th", { children: "Count" })
+      ] }) }),
+      /* @__PURE__ */ jsx("tbody", { children: bins.map((b, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: bins are positional buckets — index IS the identity
+        /* @__PURE__ */ jsxs("tr", { children: [
+          /* @__PURE__ */ jsx("td", { children: `${valueFormatter(b.lo)}\u2013${valueFormatter(b.hi)}` }),
+          /* @__PURE__ */ jsx("td", { children: b.count })
+        ] }, i)
+      )) })
+    ] })
+  ] });
+});
+Histogram.displayName = "Histogram";
+var VIEW_W3 = 600;
+var PAD4 = { top: 8, right: 8, bottom: 4, left: 40 };
+function bandPath(upper, lower, xScale, yScale) {
+  const runs = [];
+  let run = [];
+  for (let i = 0; i < upper.length; i++) {
+    const u = upper[i];
+    const l = lower[i];
+    if (u !== void 0 && l !== void 0 && Number.isFinite(u) && Number.isFinite(l)) {
+      run.push(i);
+    } else if (run.length > 0) {
+      runs.push(run);
+      run = [];
+    }
+  }
+  if (run.length > 0) runs.push(run);
+  return runs.map((idxs) => {
+    const top = idxs.map(
+      (i, k) => `${k === 0 ? "M" : "L"}${xScale(i).toFixed(2)},${yScale(upper[i]).toFixed(2)}`
+    );
+    const bottom = idxs.slice().reverse().map((i) => `L${xScale(i).toFixed(2)},${yScale(lower[i]).toFixed(2)}`);
+    return `${top.join(" ")} ${bottom.join(" ")} Z`;
+  }).join(" ");
+}
+var PercentileChart = forwardRef((props, ref) => {
+  const {
+    title,
+    buckets,
+    height = 180,
+    valueFormatter = (v) => String(v),
+    className,
+    ...rest
+  } = props;
+  const hasData = buckets.length > 0;
+  if (!hasData) {
+    return /* @__PURE__ */ jsxs(
+      "figure",
+      {
+        "data-slot": "percentile-chart",
+        ref,
+        className: cn("space-y-1", className),
+        "aria-label": `${title} \u2014 no data`,
+        ...rest,
+        children: [
+          /* @__PURE__ */ jsx("figcaption", { className: "font-semibold text-label-caps text-muted-foreground uppercase", children: title }),
+          /* @__PURE__ */ jsx(
+            "div",
+            {
+              "data-slot": "percentile-empty",
+              className: "flex items-center justify-center rounded-md border border-dashed text-body-sm text-muted-foreground",
+              style: { height },
+              children: "No data in this time range."
+            }
+          )
+        ]
+      }
+    );
+  }
+  const p50 = buckets.map((b) => b.p50);
+  const p95 = buckets.map((b) => b.p95);
+  const p99 = buckets.map((b) => b.p99);
+  const yMax = niceMax([...p99]) || 1;
+  const xScale = linScale([0, Math.max(1, buckets.length - 1)], [PAD4.left, VIEW_W3 - PAD4.right]);
+  const yScale = linScale([0, yMax], [height - PAD4.bottom, PAD4.top]);
+  const p50Points = p50.map((y, x) => ({ x, y }));
+  return /* @__PURE__ */ jsxs("figure", { "data-slot": "percentile-chart", ref, className: cn("space-y-1", className), ...rest, children: [
+    /* @__PURE__ */ jsx("figcaption", { className: "font-semibold text-label-caps text-muted-foreground uppercase", children: title }),
+    /* @__PURE__ */ jsxs(
+      "svg",
+      {
+        viewBox: `0 0 ${VIEW_W3} ${height}`,
+        preserveAspectRatio: "none",
+        role: "img",
+        "aria-label": `${title} percentiles`,
+        className: "w-full",
+        style: { height },
+        children: [
+          /* @__PURE__ */ jsx(
+            "line",
+            {
+              x1: PAD4.left,
+              y1: height - PAD4.bottom,
+              x2: VIEW_W3 - PAD4.right,
+              y2: height - PAD4.bottom,
+              className: "stroke-border",
+              strokeWidth: 1
+            }
+          ),
+          /* @__PURE__ */ jsx("text", { x: 4, y: PAD4.top + 8, className: "fill-muted-foreground text-[10px]", children: valueFormatter(yMax) }),
+          /* @__PURE__ */ jsx("text", { x: 4, y: height - PAD4.bottom, className: "fill-muted-foreground text-[10px]", children: "0" }),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              "data-slot": "percentile-band",
+              "data-band": "p95-p99",
+              d: bandPath(p99, p95, xScale, yScale),
+              className: "fill-primary",
+              fillOpacity: 0.15,
+              children: /* @__PURE__ */ jsx("title", { children: "p95\u2013p99" })
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              "data-slot": "percentile-band",
+              "data-band": "p50-p95",
+              d: bandPath(p95, p50, xScale, yScale),
+              className: "fill-primary",
+              fillOpacity: 0.3,
+              children: /* @__PURE__ */ jsx("title", { children: "p50\u2013p95" })
+            }
+          ),
+          /* @__PURE__ */ jsx(
+            "path",
+            {
+              "data-slot": "percentile-p50-line",
+              d: seriesPath(p50Points, xScale, yScale),
+              fill: "none",
+              className: "stroke-primary",
+              strokeWidth: 1.5,
+              children: /* @__PURE__ */ jsx("title", { children: "p50" })
+            }
+          )
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsxs("table", { "data-slot": "percentile-table", className: "sr-only", children: [
+      /* @__PURE__ */ jsxs("caption", { children: [
+        title,
+        " \u2014 data table"
+      ] }),
+      /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+        /* @__PURE__ */ jsx("th", { children: "Bucket" }),
+        /* @__PURE__ */ jsx("th", { children: "p50" }),
+        /* @__PURE__ */ jsx("th", { children: "p95" }),
+        /* @__PURE__ */ jsx("th", { children: "p99" })
+      ] }) }),
+      /* @__PURE__ */ jsx("tbody", { children: buckets.map((b, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: buckets are positional time slots — index IS the identity
+        /* @__PURE__ */ jsxs("tr", { children: [
+          /* @__PURE__ */ jsx("td", { children: b.label ?? i + 1 }),
+          /* @__PURE__ */ jsx("td", { children: Number.isFinite(b.p50) ? valueFormatter(b.p50) : "\u2014" }),
+          /* @__PURE__ */ jsx("td", { children: Number.isFinite(b.p95) ? valueFormatter(b.p95) : "\u2014" }),
+          /* @__PURE__ */ jsx("td", { children: Number.isFinite(b.p99) ? valueFormatter(b.p99) : "\u2014" })
+        ] }, i)
+      )) })
+    ] })
+  ] });
+});
+PercentileChart.displayName = "PercentileChart";
+function AnnotationInput(props) {
+  const { name, description, required, disabled, className } = props;
+  const generatedId = useId();
+  const controlId = props.id ?? generatedId;
+  const descId = description ? `${controlId}-desc` : void 0;
+  const isCategorical = props.config.type === "categorical";
+  const labelId = isCategorical ? `${controlId}-label` : void 0;
+  const label = /* @__PURE__ */ jsx(Label, { id: labelId, htmlFor: isCategorical ? void 0 : controlId, required, children: name });
+  const a11y = {
+    "aria-required": required || void 0,
+    "aria-describedby": descId,
+    disabled
+  };
+  let control = null;
+  if (props.config.type === "categorical") {
+    const { config, value, onValueChange } = props;
+    control = /* @__PURE__ */ jsx(
+      RadioGroup,
+      {
+        value: value ?? "",
+        onValueChange: (v) => onValueChange(v === "" ? null : v),
+        "aria-labelledby": labelId,
+        className: "gap-1.5",
+        ...a11y,
+        children: config.options.map((opt) => {
+          const optId = `${controlId}-${opt.label}`;
+          return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+            /* @__PURE__ */ jsx(RadioGroup.Item, { value: opt.label, id: optId, disabled }),
+            /* @__PURE__ */ jsx(Label, { htmlFor: optId, className: "font-normal", children: opt.label })
+          ] }, opt.label);
+        })
+      }
+    );
+  } else if (props.config.type === "continuous") {
+    const { config, value, onValueChange } = props;
+    const onNumber = (e) => {
+      const raw = e.target.value;
+      if (raw === "") return onValueChange(null);
+      const n = Number(raw);
+      onValueChange(Number.isFinite(n) ? n : null);
+    };
+    control = /* @__PURE__ */ jsx(
+      Input,
+      {
+        ...a11y,
+        id: controlId,
+        type: "number",
+        min: config.min,
+        max: config.max,
+        step: config.step,
+        value: value ?? "",
+        onChange: onNumber
+      }
+    );
+  } else if (props.config.type === "freeform") {
+    const { config, value, onValueChange } = props;
+    const onText = (e) => onValueChange(e.target.value === "" ? null : e.target.value);
+    control = /* @__PURE__ */ jsx(
+      Textarea,
+      {
+        ...a11y,
+        id: controlId,
+        maxLength: config.maxLength,
+        value: value ?? "",
+        onChange: onText
+      }
+    );
+  }
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      "data-slot": "annotation-input",
+      "data-type": props.config.type,
+      className: cn("space-y-1.5", className),
+      children: [
+        label,
+        description ? /* @__PURE__ */ jsx("p", { id: descId, className: "text-body-sm text-muted-foreground", children: description }) : null,
+        control
+      ]
+    }
+  );
+}
+
+// src/components/composites/annotation-input/types.ts
+function isCategoricalConfig(c) {
+  return c.type === "categorical";
+}
+function isContinuousConfig(c) {
+  return c.type === "continuous";
+}
+function isFreeformConfig(c) {
+  return c.type === "freeform";
+}
+
+export { AccountMenu, ActionBar, Alert, AnnotationInput, AttributesTable, Avatar, BadgeWithDot as Badge, Breadcrumb, Button, Card, Checkbox, CodeBlock, Combobox, CommandPalette, ConfirmDialog, CopyButton, DangerZone, DataTable, DeploymentRow, DescriptionList, Dialog, DomainConfig, DropdownMenu, EmptyState, EnvVarEditor, FileDropzone, FormField, GRAPH_NODE_CAP, Histogram, IOCards, Input, JsonViewer, KIND_LABEL, Label, LoginSplit, MessageCard, MessageItem, MetricCard, MetricsPanel, PageShell, Pagination, PercentileChart, PinInput, PlanBadge, PreviewEnvCard, Progress, ProjectCard, RadioGroup, RollbackUI, ScrollArea, Select, SessionSummary, SessionTimeline, Sheet, Sidebar, Skeleton, Slider, SocialAuthRow, SpanGraph, SpanTree, SpanTreeRow, SpanWaterfall, StatTile, StatusDot, StatusIndicator, Stepper, Switch, Table, Tabs, TaskHeader, Textarea, Timestamp, Toast, Toaster, TooltipWithStatics as Tooltip, TopNav, TraceCompare, TraceTranscript, TrendChart, UpdateBanner, VIRTUALIZE_THRESHOLD, aggregateCost, aggregateSession, alignSpanTrees, asChat, avatarVariants, badgeVariants, buildLayeredGraph, buttonVariants, cn, computeBarLayout, computeHistogram, computePageRange, computeTraceBounds, contentText, deriveSpanKind, deriveSteps, durationMs, flattenAll, flattenVisible, groupByNamespace, isCategoricalConfig, isContinuousConfig, isFreeformConfig, isNearBottom, isRedactedThinking, isSpanError, linScale, matchesAccept, niceAxisTicks, niceMax, packRows, prettyValue, seriesPath, sessionBounds, sheetVariants, spanCostUsd, toNs, toTranscriptRows, traceMetrics, useStickToBottom, useToast, validateFiles };

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usetheo/ui",
-  "version": "0.23.0",
+  "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).",