@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/TraceInspectorPanel.js

@@ -0,0 +1,95 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconActivity } from '@tabler/icons-react';
+import { cloneElement, createContext, isValidElement, lazy, Suspense, use, useCallback, useId, useRef, useState, } from 'react';
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { InPlace, isSidePanelWide, RaisedPane, SidePanel, SidePanelHeader, SidePanelToggle, useSidePanel, useWidth, } from "./SidePanel.js";
+// why: The inspector and its charts are fetched when the trace first opens, not with the chat.
+const TraceGuardrailsBody = lazy(() => import("./TraceInspector.js").then((module) => ({ default: module.TraceGuardrailsBody })));
+const TraceFeedBody = lazy(() => import("./TraceInspector.js").then((module) => ({ default: module.TraceFeedBody })));
+/** `replace` takes the surface's place. `panel` docks at the inline end; its width eases with the theme. */
+const TracePlacementContext = createContext('replace');
+/** Where an open trace sits on this page. */
+export function TracePlacement({ value, children, }) {
+    return _jsx(TracePlacementContext, { value: value, children: children });
+}
+function TraceView({ id, header, traces, }) {
+    return (_jsx(RaisedPane, { id: id, header: header, children: (isWide) => (_jsx(Suspense, { fallback: null, children: _jsx(TraceFeedBody, { traces: traces, isWide: isWide }) })) }));
+}
+/**
+ * The trace inspector, offered when the profile records traces. By default the
+ * open trace takes the surface's place. Inside `TracePlacement value="panel"`
+ * it docks at the inline end instead, and the theme eases that panel's width.
+ * It reads the records the host delivers on `traces`; a host that delivers none
+ * shows the empty state. Pass `open` to drive it from the host's own control,
+ * which hides the built-in toggle. The open trace takes the surface's place,
+ * unless this page is inside `TracePlacement value="panel"`, where it docks.
+ */
+export function useTraceInspector(iface, traces, open) {
+    const t = useLabels();
+    const id = useId();
+    const [own, setOwn] = useState(false);
+    const placement = use(TracePlacementContext);
+    const labels = {
+        name: t('@theorem.panel.trace.name'),
+        show: t('@theorem.panel.trace.show'),
+        hide: t('@theorem.panel.trace.hide'),
+        resize: t('@theorem.panel.trace.resize'),
+    };
+    if (iface.observability?.record !== true)
+        return { toggle: null, view: null, labels, offered: false };
+    const isOpen = open ?? own;
+    const toggle = open === undefined ? (_jsx(SidePanelToggle, { labels: labels, icon: _jsx(Icon, { icon: IconActivity }), panelId: id, open: isOpen, onToggle: () => setOwn((value) => !value) })) : null;
+    const view = isOpen ? openTrace(placement === 'panel', id, traces, toggle) : null;
+    return { toggle, view, labels, offered: true };
+}
+/** The open trace: filling the host's docked panel, or as its own panel with the toggle on top. */
+function openTrace(docked, id, traces, toggle) {
+    if (docked)
+        return _jsx(TraceFill, { id: id, traces: traces });
+    return (_jsx(TraceView, { id: id, header: toggle ? _jsx(SidePanelHeader, { floating: true, children: toggle }) : undefined, traces: traces }));
+}
+/** The trace body, filling the docked panel. The panel supplies the raised card. */
+function TraceFill({ id, traces }) {
+    const { ref, width } = useWidth();
+    return (_jsx("div", { id: id, ref: ref, style: { height: '100%' }, children: _jsx(Suspense, { fallback: null, children: _jsx(TraceFeedBody, { traces: traces, isWide: isSidePanelWide(width) }) }) }));
+}
+/** The surface, with the trace docked at its inline end. A host-driven trace stays in place. */
+function TraceDock({ inspector, children }) {
+    const layoutRef = useRef(null);
+    const side = useSidePanel(layoutRef, false);
+    const childRef = useRef(undefined);
+    const setLayout = useCallback((node) => {
+        layoutRef.current = node;
+        const ref = childRef.current;
+        if (typeof ref === 'function')
+            ref(node);
+        else if (ref != null)
+            ref.current = node;
+    }, []);
+    if (!isValidElement(children)) {
+        return _jsx(InPlace, { view: inspector.view, children: children });
+    }
+    childRef.current = children.props.ref;
+    const open = inspector.view != null;
+    return cloneElement(children, {
+        ref: setLayout,
+        end: (_jsx(SidePanel, { labels: inspector.labels, resizable: side.resizable, open: open, children: inspector.view })),
+    });
+}
+/** The surface, or the trace in its place — or, on a docked page, beside it. */
+export function WithTrace({ inspector, children, }) {
+    const placement = use(TracePlacementContext);
+    if (placement === 'panel' && inspector.offered) {
+        return _jsx(TraceDock, { inspector: inspector, children: children });
+    }
+    return _jsx(InPlace, { view: inspector.view, children: children });
+}
+/**
+ * What `records` say of guardrails, for a host that holds a trace of its own
+ * (the studio's guardrail test): the checks' time and count, then each
+ * check, laid out as the trace lays them out. `head` leads it.
+ */
+export function TraceGuardrailsView({ records, head, }) {
+    return (_jsx(TheoremLabelsProvider, { children: _jsx(Suspense, { fallback: null, children: _jsx(TraceGuardrailsBody, { records: records, head: head }) }) }));
+}

package/ui/TraceOverview.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from 'react';
+import { type TraceLatency, type TraceTurn } from '../client/trace-story.ts';
+import type { TraceTotals } from '../client/trace-view.ts';
+/** Width a chart draws at before it has measured its column: the panel's narrowest. */
+export declare const FIRST_WIDTH_PX = 280;
+/**
+ * Holds a chart. Recharts makes its layers focusable, so a click would move
+ * focus into the SVG and draw the browser's ring; a press here keeps focus
+ * where it was. Clicks and pointer drags still reach the chart.
+ */
+export declare function ChartFrame({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** A chart's hover card, drawn like Astryx's own tooltip. */
+export declare function ChartTip({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Which turn is open: its name, and the previous and next turn. */
+export declare function TurnPicker({ turns, index, onChange, onBack, }: {
+    turns: readonly TraceTurn[];
+    index: number;
+    onChange: (index: number) => void;
+    /** Leaves the turn for the whole conversation; absent when there is only the one turn. */
+    onBack?: (() => void) | undefined;
+}): import("react").JSX.Element | null;
+/** A turn's guardrail figures alone, as {@link TurnStats} lays them out. */
+export declare function GuardrailStats({ latency }: {
+    latency: TraceLatency;
+}): import("react").JSX.Element | null;
+/**
+ * Duration, first text, cost, tokens, steps, and guardrails of the open turn;
+ * a total the trace did not record is left out.
+ */
+export declare function TurnStats({ totals, tools, latency, }: {
+    totals: TraceTotals;
+    tools: number;
+    latency?: TraceLatency;
+}): import("react").JSX.Element;

package/ui/TraceOverview.js

@@ -0,0 +1,126 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { Card } from '@astryxdesign/core/Card';
+import { Grid } from '@astryxdesign/core/Grid';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconArrowLeft, IconChevronLeft, IconChevronRight } from '@tabler/icons-react';
+import { TRACE_FIELDS, traceAttributeMeta } from '@theoremjs/agents';
+import { useEffect, useRef } from 'react';
+import { isCallTrace } from "../client/trace-story.js";
+import { useTraceFormat } from "./TraceValues.js";
+import { TRACE_HUE } from "./trace-palette.js";
+/** Width a chart draws at before it has measured its column: the panel's narrowest. */
+export const FIRST_WIDTH_PX = 280;
+/**
+ * Holds a chart. Recharts makes its layers focusable, so a click would move
+ * focus into the SVG and draw the browser's ring; a press here keeps focus
+ * where it was. Clicks and pointer drags still reach the chart.
+ */
+export function ChartFrame({ children }) {
+    const frame = useRef(null);
+    useEffect(() => {
+        const node = frame.current;
+        // why: A native listener keeps the frame a plain element; it is not a control, so it takes no role.
+        const keepFocus = (event) => event.preventDefault();
+        node?.addEventListener('mousedown', keepFocus);
+        return () => node?.removeEventListener('mousedown', keepFocus);
+    }, []);
+    return _jsx("div", { ref: frame, children: children });
+}
+/** A chart's hover card, drawn like Astryx's own tooltip. */
+export function ChartTip({ children }) {
+    return (_jsx("div", { style: {
+            background: 'var(--color-background-popover)',
+            border: '1px solid var(--color-border)',
+            borderRadius: 'var(--radius-element)',
+            padding: '6px 8px',
+            boxShadow: 'var(--shadow-med)',
+            pointerEvents: 'none',
+        }, children: children }));
+}
+/** Which turn is open: its name, and the previous and next turn. */
+export function TurnPicker({ turns, index, onChange, onBack, }) {
+    const { t } = useTraceFormat();
+    const turn = turns[index];
+    if (!turn)
+        return null;
+    const isCalls = isCallTrace(turns);
+    return (_jsxs(VStack, { gap: 1, hAlign: "start", children: [onBack ? (_jsx(Button, { label: t(isCalls ? '@theorem.panel.trace.calls.back' : '@theorem.panel.trace.conversation.back'), variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: IconArrowLeft }), onClick: onBack })) : null, _jsxs(HStack, { gap: 1, align: "center", justify: "between", width: "100%", children: [_jsxs(HStack, { gap: 2, align: "center", children: [_jsx(Text, { weight: "semibold", children: t('@theorem.panel.trace.turn', {
+                                    label: turn.node.meta.label,
+                                    index: index + 1,
+                                    count: turns.length,
+                                }) }), turn.node.meta.subject ? (_jsx(Text, { color: "secondary", maxLines: 1, children: turn.node.meta.subject })) : null] }), _jsxs(HStack, { gap: 0, children: [_jsx(IconButton, { label: t(isCalls ? '@theorem.panel.trace.calls.previous' : '@theorem.panel.trace.previous'), icon: _jsx(Icon, { icon: IconChevronLeft }), variant: "ghost", size: "sm", isDisabled: index === 0, onClick: () => onChange(index - 1) }), _jsx(IconButton, { label: t(isCalls ? '@theorem.panel.trace.calls.next' : '@theorem.panel.trace.next'), icon: _jsx(Icon, { icon: IconChevronRight }), variant: "ghost", size: "sm", isDisabled: index === turns.length - 1, onClick: () => onChange(index + 1) })] })] })] }));
+}
+function Stat({ label, value, detail, }) {
+    return (_jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: _jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "supporting", color: "secondary", children: label }), _jsx(Text, { type: "large", weight: "semibold", hasTabularNumbers: true, children: value }), _jsx(VStack, { gap: 0, children: [detail]
+                        .flat()
+                        .filter(Boolean)
+                        .map((line) => (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: line }, String(line)))) })] }) }));
+}
+function FirstTextStat({ latency, format }) {
+    if (latency?.firstTextMs === undefined)
+        return null;
+    const { t } = format;
+    return (_jsx(Stat, { label: t('@theorem.panel.trace.firstText'), value: format.duration(latency.firstTextMs), detail: [
+            latency.tokensPerSecond !== undefined &&
+                t('@theorem.panel.trace.rate', {
+                    rate: format.number(Math.round(latency.tokensPerSecond)),
+                }),
+            latency.heldMs &&
+                t('@theorem.panel.trace.held', { duration: format.duration(latency.heldMs) }),
+        ] }));
+}
+function CostStat({ totals, format }) {
+    if (!totals.cost)
+        return null;
+    return (_jsx(Stat, { label: traceAttributeMeta('theorem.usage.cost_usd')?.label ?? '', value: format.sum(totals.cost, format.usd) }));
+}
+/** A token total as its card reads it: "–" when no call reported it. */
+function tokenSide(total, format) {
+    return total ? format.sum(total, format.number) : '–';
+}
+function TokensStat({ totals, format }) {
+    const { input, output } = totals;
+    if (!input && !output)
+        return null;
+    const all = [input, output].reduce((sum, total) => sum + (total?.value ?? 0), 0);
+    return (_jsx(Stat, { label: format.t('@theorem.panel.trace.tokens'), value: format.number(all), detail: format.t('@theorem.panel.trace.tokens.detail', {
+            input: tokenSide(input, format),
+            output: tokenSide(output, format),
+        }) }));
+}
+function StepsStat({ totals, tools, format, }) {
+    const { t } = format;
+    // why: With no model, every step is a tool call the heading already counts.
+    if (totals.calls === 0 && totals.errors === 0)
+        return null;
+    return (_jsx(Stat, { label: t('@theorem.panel.trace.steps'), value: format.number(totals.calls + tools), detail: totals.errors > 0 ? (_jsx("span", { style: { color: TRACE_HUE.oxblood }, children: t('@theorem.panel.trace.failed', { count: totals.errors }) })) : (t('@theorem.panel.trace.steps.detail', { calls: totals.calls, tools })) }));
+}
+function GuardrailsStat({ latency, format, }) {
+    const guardrails = latency?.guardrails;
+    if (!guardrails)
+        return null;
+    return (_jsx(Stat, { label: format.t('@theorem.panel.trace.guardrails'), value: format.duration(guardrails.ms), detail: format.t('@theorem.panel.trace.guardrails.detail', {
+            checks: guardrails.checks,
+            flagged: guardrails.flagged,
+        }) }));
+}
+/** A turn's guardrail figures alone, as {@link TurnStats} lays them out. */
+export function GuardrailStats({ latency }) {
+    const format = useTraceFormat();
+    if (!latency.guardrails)
+        return null;
+    return (_jsx(Grid, { columns: { minWidth: 120, repeat: 'fit' }, gap: 2, children: _jsx(GuardrailsStat, { latency: latency, format: format }) }));
+}
+/**
+ * Duration, first text, cost, tokens, steps, and guardrails of the open turn;
+ * a total the trace did not record is left out.
+ */
+export function TurnStats({ totals, tools, latency, }) {
+    const format = useTraceFormat();
+    return (_jsxs(Grid, { columns: { minWidth: 120, repeat: 'fit' }, gap: 2, children: [_jsx(Stat, { label: TRACE_FIELDS.duration.label, value: format.duration(totals.durationMs) }), _jsx(FirstTextStat, { latency: latency, format: format }), _jsx(CostStat, { totals: totals, format: format }), _jsx(TokensStat, { totals: totals, format: format }), _jsx(StepsStat, { totals: totals, tools: tools, format: format }), _jsx(GuardrailsStat, { latency: latency, format: format })] }));
+}

package/ui/TraceSpanDetail.d.ts

@@ -0,0 +1,10 @@
+import { type TraceNode } from '../client/trace-view.ts';
+/** One span in full: who acted and how it ended, what went in and came out, its tokens, then every detail it recorded. */
+export declare function TraceSpanDetail({ node, turnStartMs, isClose, onBack, onOpen, }: {
+    node: TraceNode;
+    turnStartMs: number;
+    /** In the wide panel the span sits beside the turn: close, not back. */
+    isClose?: boolean;
+    onBack: () => void;
+    onOpen: (node: TraceNode) => void;
+}): import("react").JSX.Element;

package/ui/TraceSpanDetail.js

@@ -0,0 +1,190 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Badge } from '@astryxdesign/core/Badge';
+import { Button } from '@astryxdesign/core/Button';
+import { Card } from '@astryxdesign/core/Card';
+import { Collapsible } from '@astryxdesign/core/Collapsible';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { Item } from '@astryxdesign/core/Item';
+import { MetadataList, MetadataListItem } from '@astryxdesign/core/MetadataList';
+import { Text } from '@astryxdesign/core/Text';
+import { Token } from '@astryxdesign/core/Token';
+import { Tooltip as HoverTip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconArrowLeft, IconX } from '@tabler/icons-react';
+import { inlineContent, TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, traceAttributeMeta, traceEventAttributeMeta, traceEventMeta, } from '@theoremjs/agents';
+import { messageText, storedValue, traceActor, traceOutcome } from "../client/trace-story.js";
+import { nanosToMs } from "../client/trace-view.js";
+import { keyedByContent } from "./row-keys.js";
+import { ShapedData } from "./ShapedData.js";
+import { PanePanel, Prose } from "./SidePanel.js";
+import { ActorMark } from "./TraceStory.js";
+import { attributeSections, TRACE_LABEL_PX, TraceAttributeList, TraceValue, useTraceFormat, } from "./TraceValues.js";
+/** A span's own field, read as an attribute of that format. */
+function fieldMeta(field, format) {
+    return { ...field, format, group: 'record' };
+}
+const SPAN_FIELD_META = {
+    type: { ...fieldMeta(TRACE_FIELDS.type, 'text'), options: TRACE_SPAN_TYPES },
+    status: { ...fieldMeta(TRACE_FIELDS.status, 'text'), options: TRACE_STATUS },
+    start: fieldMeta(TRACE_FIELDS.start, 'time'),
+    traceId: fieldMeta(TRACE_FIELDS.traceId, 'id'),
+    spanId: fieldMeta(TRACE_FIELDS.spanId, 'id'),
+};
+function spanFieldMeta(key) {
+    return key in SPAN_FIELD_META ? SPAN_FIELD_META[key] : undefined;
+}
+function Section({ title, children }) {
+    return (_jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: title }), children: children }));
+}
+function EventList({ node }) {
+    const format = useTraceFormat();
+    return (_jsx(VStack, { gap: 3, children: keyedByContent(node.span.events, (event) => `${event.name}:${event.timeUnixNano}`).map(({ item: event, key }) => {
+            const offset = format.t('@theorem.panel.trace.offset', {
+                duration: format.duration(nanosToMs(event.timeUnixNano) - node.startMs),
+            });
+            const label = traceEventMeta(event.name)?.label ?? event.name;
+            return (_jsxs(VStack, { gap: 1, children: [_jsxs(HStack, { gap: 2, align: "center", children: [_jsx(Text, { weight: "medium", children: label }), _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: offset })] }), _jsx(TraceAttributeList, { record: node.record, attributes: event.attributes, metaOf: (key) => traceEventAttributeMeta(event.name, key) })] }, key));
+        }) }));
+}
+function LinkList({ node }) {
+    return (_jsx(VStack, { gap: 3, children: node.span.links.map((link) => (_jsx(TraceAttributeList, { record: node.record, attributes: { traceId: link.traceId, spanId: link.spanId, ...link.attributes }, metaOf: (key) => spanFieldMeta(key) ?? traceAttributeMeta(key) }, `${link.traceId}:${link.spanId}`))) }));
+}
+const SPAN_FIELD_VALUES = {
+    type: (node) => node.meta.type,
+    start: (node) => node.span.startTimeUnixNano,
+    traceId: (node) => node.span.traceId,
+    spanId: (node) => node.span.spanId,
+};
+/** What the span was, how long it took, what it cost, and when it started. */
+function spanFacts(node, turnStartMs, format) {
+    const cost = node.span.attributes['theorem.usage.cost_usd'];
+    return [
+        node.meta.label,
+        format.duration(node.durationMs),
+        ...(typeof cost === 'number' ? [format.usd(cost)] : []),
+        format.t('@theorem.panel.trace.offset', {
+            duration: format.duration(node.startMs - turnStartMs),
+        }),
+    ].join(format.t('@theorem.panel.trace.separator'));
+}
+function OutcomeBadge({ outcome }) {
+    if (!outcome)
+        return null;
+    return (_jsx(HoverTip, { content: outcome.doc ?? outcome.label, children: _jsx(Badge, { variant: outcome.tone, label: outcome.label }) }));
+}
+/** The span's status message, unless the outcome badge already says it. */
+function StatusMessage({ node, outcome, }) {
+    const message = node.span.status.message;
+    if (!message || message.toLowerCase() === outcome?.label.toLowerCase())
+        return null;
+    return _jsx(Text, { color: "secondary", children: message });
+}
+/** Back (or close), then who acted, what it was, how it ended, how long it took, and what it cost. */
+function SpanHeader({ node, turnStartMs, onBack, isClose, }) {
+    const format = useTraceFormat();
+    const outcome = traceOutcome(node);
+    return (_jsxs(VStack, { gap: 2, children: [_jsx(HStack, { children: _jsx(Button, { label: format.t(isClose ? '@theorem.panel.trace.close' : '@theorem.panel.trace.back'), variant: "ghost", size: "sm", icon: _jsx(Icon, { icon: isClose ? IconX : IconArrowLeft }), onClick: onBack }) }), _jsx(Item, { startContent: _jsx(ActorMark, { actor: traceActor(node) }), label: _jsx(Text, { weight: "semibold", children: node.meta.subject ?? node.meta.label }), description: spanFacts(node, turnStartMs, format), endContent: _jsx(OutcomeBadge, { outcome: outcome }), align: "start" }), _jsx(StatusMessage, { node: node, outcome: outcome })] }));
+}
+function parsed(value) {
+    if (typeof value !== 'string')
+        return value;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function ToolCallPart({ part }) {
+    return (_jsxs(VStack, { gap: 1, children: [_jsx(Text, { weight: "medium", children: String(part.name ?? '') }), _jsx(ShapedData, { value: parsed(part.arguments) })] }));
+}
+/** One message part: its text, or a tool call's name and arguments, or what a tool returned. */
+function PartView({ part }) {
+    if (part.type === 'text' && typeof part.content === 'string')
+        return _jsx(Prose, { text: part.content });
+    if (part.type === 'tool_call')
+        return _jsx(ToolCallPart, { part: part });
+    const body = part.response ?? part.result ?? part.content;
+    return body === undefined ? null : _jsx(ShapedData, { value: parsed(body) });
+}
+/** Messages as the model saw them: each one's role, then its parts. */
+function MessageList({ messages }) {
+    return (_jsx(VStack, { gap: 3, children: keyedByContent(messages, (message) => JSON.stringify(message)).map(({ item: message, key }) => (_jsxs(VStack, { gap: 1, children: [_jsx(HStack, { children: _jsx(Token, { label: String(message.role ?? ''), size: "sm", color: "gray" }) }), Array.isArray(message.parts)
+                    ? keyedByContent(message.parts.filter(isObject), (part) => JSON.stringify(part)).map(({ item: part, key: partKey }) => _jsx(PartView, { part: part }, partKey))
+                    : null] }, key))) }));
+}
+function messagesOf(node, key) {
+    const value = inlineContent(node.record, node.span.attributes[key]);
+    return Array.isArray(value) ? value.filter(isObject) : [];
+}
+function label(key) {
+    const meta = traceAttributeMeta(key);
+    return meta ? { title: meta.label, doc: meta.doc } : { title: key };
+}
+/** A stored value under its attribute's name; nothing when the span has none. */
+function DataPanel({ attribute, value }) {
+    if (value === undefined)
+        return null;
+    return (_jsx(PanePanel, { ...label(attribute), children: _jsx(ShapedData, { value: value }) }));
+}
+/** Text under its attribute's name; nothing when there is none. */
+function ProsePanel({ attribute, text }) {
+    if (typeof text !== 'string' || !text)
+        return null;
+    return (_jsx(PanePanel, { ...label(attribute), children: _jsx(Prose, { text: text }) }));
+}
+function TurnIO({ node }) {
+    return (_jsxs(_Fragment, { children: [_jsx(ProsePanel, { attribute: "gen_ai.input.messages", text: messageText(node, 'gen_ai.input.messages', 'user') }), _jsx(ProsePanel, { attribute: "gen_ai.output.messages", text: messageText(node, 'gen_ai.output.messages', 'assistant') })] }));
+}
+function CallIO({ node }) {
+    const input = messagesOf(node, 'gen_ai.input.messages');
+    const output = messagesOf(node, 'gen_ai.output.messages');
+    return (_jsxs(_Fragment, { children: [output.length > 0 ? (_jsx(PanePanel, { ...label('gen_ai.output.messages'), children: _jsx(MessageList, { messages: output }) })) : null, input.length > 0 ? (_jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: `${label('gen_ai.input.messages').title} · ${input.length}` }), children: _jsx(Card, { padding: 3, variant: "muted", style: { background: 'var(--color-background-surface)' }, children: _jsx(MessageList, { messages: input }) }) })) : null] }));
+}
+function ToolIO({ node }) {
+    const { attributes } = node.span;
+    const result = 'theorem.tool.data' in attributes ? 'theorem.tool.data' : 'gen_ai.tool.call.result';
+    return (_jsxs(_Fragment, { children: [_jsx(DataPanel, { attribute: "gen_ai.tool.call.arguments", value: storedValue(node, 'gen_ai.tool.call.arguments') }), _jsx(DataPanel, { attribute: result, value: storedValue(node, result) }), _jsx(ProsePanel, { attribute: "exception.message", text: 'exception.message' in attributes ? storedValue(node, 'exception.message') : undefined })] }));
+}
+/** What went in and what came out, read the way a person would: text, messages, or a tool's data. */
+function SpanIO({ node }) {
+    switch (node.meta.type) {
+        case 'turn':
+            return _jsx(TurnIO, { node: node });
+        case 'call':
+        case 'response':
+            return _jsx(CallIO, { node: node });
+        case 'tool':
+            return _jsx(ToolIO, { node: node });
+        default:
+            return null;
+    }
+}
+/** The span's own fields: its type, start, and IDs. */
+function SpanFields({ node }) {
+    return (_jsx(MetadataList, { columns: "single", label: { position: 'start', width: TRACE_LABEL_PX }, children: Object.keys(SPAN_FIELD_VALUES).map((key) => (_jsx(MetadataListItem, { label: SPAN_FIELD_META[key].label, children: _jsx(TraceValue, { record: node.record, meta: SPAN_FIELD_META[key], value: SPAN_FIELD_VALUES[key](node) }) }, key))) }));
+}
+/** The record's host resource and request metadata, shown on the span that roots the record. */
+function RecordSections({ node }) {
+    const { record } = node;
+    if (record.spans[0]?.spanId !== node.span.spanId)
+        return null;
+    return (_jsxs(_Fragment, { children: [Object.keys(record.resource).length > 0 ? (_jsx(Section, { title: TRACE_FIELDS.resource.label, children: _jsx(TraceAttributeList, { record: record, attributes: record.resource, metaOf: traceAttributeMeta }) })) : null, record.metadata ? (_jsx(Section, { title: TRACE_FIELDS.metadata.label, children: _jsx(TraceAttributeList, { record: record, attributes: record.metadata, metaOf: () => undefined }) })) : null] }));
+}
+/** One span in full: who acted and how it ended, what went in and came out, its tokens, then every detail it recorded. */
+export function TraceSpanDetail({ node, turnStartMs, isClose = false, onBack, onOpen, }) {
+    const format = useTraceFormat();
+    const { t } = format;
+    const { span, record } = node;
+    const sections = attributeSections(span.attributes);
+    const usage = sections.find((section) => section.key === 'usage');
+    return (_jsxs(VStack, { gap: 4, children: [_jsx(SpanHeader, { node: node, turnStartMs: turnStartMs, onBack: onBack, isClose: isClose }), _jsx(SpanIO, { node: node }), usage ? (_jsx(PanePanel, { title: TRACE_ATTRIBUTE_GROUPS.usage.label, doc: TRACE_ATTRIBUTE_GROUPS.usage.doc, children: _jsx(TraceAttributeList, { record: record, attributes: usage.attributes, metaOf: traceAttributeMeta }) })) : null, node.children.length > 0 ? (_jsx(PanePanel, { title: TRACE_FIELDS.children.label, doc: TRACE_FIELDS.children.doc, children: _jsx(VStack, { gap: 0, children: node.children.map((child) => (_jsx(Item, { startContent: _jsx(ActorMark, { actor: traceActor(child) }), label: child.meta.subject ?? child.meta.label, description: child.meta.label, endContent: _jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(child.durationMs) }), density: "compact", onClick: () => onOpen(child) }, child.id))) }) })) : null, _jsx(Collapsible, { defaultIsOpen: false, trigger: _jsx(Text, { weight: "medium", children: t('@theorem.panel.trace.details') }), children: _jsxs(VStack, { gap: 3, children: [_jsx(SpanFields, { node: node }), sections
+                            .filter((section) => section !== usage)
+                            .map((section) => (_jsx(Section, { title: section.key === 'other'
+                                ? t('@theorem.panel.trace.other')
+                                : TRACE_ATTRIBUTE_GROUPS[section.key].label, children: _jsx(TraceAttributeList, { record: record, attributes: section.attributes, metaOf: traceAttributeMeta }) }, section.key))), span.events.length > 0 ? (_jsx(Section, { title: TRACE_FIELDS.events.label, children: _jsx(EventList, { node: node }) })) : null, span.links.length > 0 ? (_jsx(Section, { title: TRACE_FIELDS.links.label, children: _jsx(LinkList, { node: node }) })) : null, _jsx(RecordSections, { node: node })] }) })] }));
+}

package/ui/TraceStory.d.ts

@@ -0,0 +1,20 @@
+import { IconUser } from '@tabler/icons-react';
+import { type TraceActor, type TraceStep } from '../client/trace-story.ts';
+import type { TraceNode } from '../client/trace-view.ts';
+/** An actor's icon, in the text's own colour. */
+export declare function ActorMark({ actor, icon }: {
+    actor: TraceActor;
+    icon?: typeof IconUser;
+}): import("react").JSX.Element;
+/**
+ * The turn, told in order: what the user asked, each model call with the tool
+ * calls it asked for set in under it, what changed course, and how it ended.
+ * A line opens its span.
+ */
+export declare function TraceStory({ steps, selectedId, matches, onSelect, }: {
+    steps: readonly TraceStep[];
+    selectedId: string | undefined;
+    /** Spans the search matched; the others dim. Absent when nothing is searched. */
+    matches: ReadonlySet<string> | undefined;
+    onSelect: (node: TraceNode) => void;
+}): import("react").JSX.Element;

package/ui/TraceStory.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge } from '@astryxdesign/core/Badge';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { Item } from '@astryxdesign/core/Item';
+import { Text } from '@astryxdesign/core/Text';
+import { Tooltip } from '@astryxdesign/core/Tooltip';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconAlertTriangle, IconBolt, IconInputAi, IconMessageCircle, IconServer, IconTool, IconUser, } from '@tabler/icons-react';
+import { toolArguments, traceActor, traceOutcome, } from "../client/trace-story.js";
+import { Arrive, Stream } from "./arrive.js";
+import { useTraceFormat } from "./TraceValues.js";
+/** Each actor's mark, shared by the story and the turn list. */
+const ACTOR_ICON = {
+    user: IconUser,
+    model: IconInputAi,
+    tool: IconTool,
+    host: IconServer,
+    theorem: IconBolt,
+    error: IconAlertTriangle,
+};
+/** An actor's icon, in the text's own colour. */
+export function ActorMark({ actor, icon }) {
+    return _jsx(Icon, { icon: icon ?? ACTOR_ICON[actor], size: "sm", color: "secondary" });
+}
+/** "city: Lisbon · to: USD": a tool call's plain arguments on one line. */
+function argumentsLine(node, separator) {
+    return toolArguments(node)
+        .map(([key, value]) => (key ? `${key}: ${value}` : value))
+        .join(separator);
+}
+/** Duration, then cost when the span reported one. */
+function StepMeasure({ node }) {
+    const format = useTraceFormat();
+    const cost = node.span.attributes['theorem.usage.cost_usd'];
+    return (_jsxs(VStack, { gap: 0, hAlign: "end", children: [_jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(node.durationMs) }), typeof cost === 'number' ? (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.usd(cost) })) : null] }));
+}
+function Offset({ ms }) {
+    const format = useTraceFormat();
+    return (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.t('@theorem.panel.trace.offset', { duration: format.duration(ms) }) }));
+}
+/** A span step's line: the tools a call asked for or that it wrote, a tool's arguments, else the span's own label. */
+function spanLine(step, format) {
+    const { node } = step;
+    if (node.meta.type === 'tool')
+        return argumentsLine(node, format.t('@theorem.panel.trace.separator'));
+    if (node.meta.type !== 'call' && node.meta.type !== 'response')
+        return node.meta.label;
+    return step.requested > 0
+        ? format.t('@theorem.panel.trace.story.requested', { count: step.requested })
+        : format.t('@theorem.panel.trace.story.wrote');
+}
+/** What a span step says under its name: how it ended when that is news, then its line. */
+function spanDescription(step, format) {
+    const outcome = traceOutcome(step.node);
+    const line = spanLine(step, format);
+    if (!outcome)
+        return line;
+    return (_jsxs(HStack, { gap: 1, align: "center", wrap: "wrap", children: [_jsx(Tooltip, { content: outcome.doc ?? outcome.label, children: _jsx(Badge, { variant: outcome.tone, label: outcome.label }) }), line ? _jsx(Text, { type: "supporting", children: line }) : null] }));
+}
+function Quote({ text }) {
+    return (_jsx(Text, { color: "secondary", maxLines: 3, hasTruncateTooltip: false, children: text }));
+}
+function AskItem({ step, isSelected, select }) {
+    const { t } = useTraceFormat();
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: "user" }), label: _jsx(Text, { weight: "medium", children: t('@theorem.panel.trace.story.asked') }), description: _jsx(Quote, { text: step.text }), endContent: _jsx(Offset, { ms: 0 }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function SpanItem({ step, isSelected, select }) {
+    const format = useTraceFormat();
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: traceActor(step.node) }), label: _jsx(Text, { weight: "medium", maxLines: 1, children: step.node.meta.subject ?? step.node.meta.label }), description: spanDescription(step, format), endContent: _jsx(StepMeasure, { node: step.node }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function EventItem({ step, isSelected, select }) {
+    const { t } = useTraceFormat();
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: "theorem" }), label: _jsx(Tooltip, { content: step.doc, children: _jsx(Text, { weight: "medium", children: step.label }) }), description: step.detail.join(t('@theorem.panel.trace.separator')), endContent: _jsx(Offset, { ms: step.offsetMs }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function AnswerItem({ step, isSelected, select }) {
+    const { t } = useTraceFormat();
+    const failed = step.node.span.status.code === 'ERROR';
+    const answer = step.text ? _jsx(Quote, { text: step.text }) : undefined;
+    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: failed ? 'error' : 'model', icon: failed ? undefined : IconMessageCircle }), label: _jsx(Text, { weight: "medium", children: t(failed ? '@theorem.panel.trace.story.failed' : '@theorem.panel.trace.story.answered') }), description: failed ? traceOutcome(step.node)?.label : answer, endContent: _jsx(Offset, { ms: step.offsetMs }), align: "start", density: "compact", onClick: select, isSelected: isSelected }));
+}
+function StepBody({ step, isSelected, select, }) {
+    switch (step.kind) {
+        case 'ask':
+            return _jsx(AskItem, { step: step, isSelected: isSelected, select: select });
+        case 'span':
+            return _jsx(SpanItem, { step: step, isSelected: isSelected, select: select });
+        case 'event':
+            return _jsx(EventItem, { step: step, isSelected: isSelected, select: select });
+        case 'answer':
+            return _jsx(AnswerItem, { step: step, isSelected: isSelected, select: select });
+    }
+}
+function StepItem({ step, isSelected, isDimmed, onSelect, }) {
+    return (_jsx(Arrive, { children: _jsx("div", { style: {
+                paddingInlineStart: step.kind === 'span' && step.nested ? 20 : 0,
+                opacity: isDimmed ? 0.35 : 1,
+                transition: 'opacity 120ms ease',
+            }, children: _jsx(StepBody, { step: step, isSelected: isSelected, select: () => onSelect(step.node) }) }) }));
+}
+/**
+ * The turn, told in order: what the user asked, each model call with the tool
+ * calls it asked for set in under it, what changed course, and how it ended.
+ * A line opens its span.
+ */
+export function TraceStory({ steps, selectedId, matches, onSelect, }) {
+    return (_jsx(Stream, { children: _jsx(VStack, { gap: 0, children: steps.map((step) => (_jsx(StepItem, { step: step, isSelected: step.kind === 'span' ? step.node.id === selectedId : false, isDimmed: matches !== undefined && !matches.has(step.node.id), onSelect: onSelect }, step.id))) }) }));
+}

package/ui/TraceValues.d.ts

@@ -0,0 +1,36 @@
+import { type TraceAttributeGroup, type TraceAttributeMeta, type TraceRecord } from '@theoremjs/agents';
+import { type TraceSum, type TraceTokenSum } from '../client/trace-view.ts';
+import { type LabelText } from './labels.ts';
+/** Width of every label column in the panel's lists, so they line up. */
+export declare const TRACE_LABEL_PX = 120;
+export type AttributeSection = {
+    key: TraceAttributeGroup | 'other';
+    attributes: Record<string, unknown>;
+};
+/** A span's attributes by catalog group, in the catalog's order; keys it does not name last. */
+export declare function attributeSections(attributes: Readonly<Record<string, unknown>>): AttributeSection[];
+/** Formats for trace values, in the viewer's locale. */
+export interface TraceFormat {
+    t: LabelText;
+    number(value: number): string;
+    usd(value: number): string;
+    duration(ms: number): string;
+    list(items: readonly string[]): string;
+    /** A total, worded as partial or estimated when it is. */
+    sum(sum: TraceSum | TraceTokenSum, format: (value: number) => string): string;
+}
+export declare function useTraceFormat(): TraceFormat;
+/** One attribute value, read by its catalog entry; a key the catalog does not name reads by its shape. */
+export declare function TraceValue({ record, meta, value, }: {
+    record: TraceRecord;
+    meta: TraceAttributeMeta | undefined;
+    value: unknown;
+}): import("react").JSX.Element;
+/** Attributes as label and value rows, worded by `metaOf`; a key it does not name shows as recorded. */
+export declare function TraceAttributeList({ record, attributes, metaOf, maxNumOfItems, title, }: {
+    record: TraceRecord;
+    attributes: Readonly<Record<string, unknown>>;
+    metaOf: (key: string) => TraceAttributeMeta | undefined;
+    maxNumOfItems?: number;
+    title?: string;
+}): import("react").JSX.Element | null;