@theoremjs/react 0.3.0 → 0.3.1

package/ui/TraceInspector.js

@@ -1,22 +1,22 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Badge } from '@astryxdesign/core/Badge';
 import { EmptyState } from '@astryxdesign/core/EmptyState';
+import { HStack } from '@astryxdesign/core/HStack';
 import { Icon } from '@astryxdesign/core/Icon';
 import { Item } from '@astryxdesign/core/Item';
 import { PowerSearch, } from '@astryxdesign/core/PowerSearch';
-import { HStack } from '@astryxdesign/core/HStack';
-import { ScrollableArea } from '@astryxdesign/core/ScrollableArea';
-import { StackItem } from '@astryxdesign/core/Stack';
 import { Text } from '@astryxdesign/core/Text';
 import { VStack } from '@astryxdesign/core/VStack';
-import { IconTimeline } from '@tabler/icons-react';
+import { IconActivity } from '@tabler/icons-react';
 import { useMemo, useState } from 'react';
 import { isCallTrace, traceGuardrails, traceLatency, traceStory, traceTurnRow, traceTurns, } from "../client/trace-story.js";
 import { TRACE_SEARCH_OPERATORS, TRACE_TEXT_FIELD, traceMatchIds, traceSearchFields, traceSpans, traceTotals, traceTree, } from "../client/trace-view.js";
 import { useTraceRecords } from "../hooks/use-trace-records.js";
+import { Stream, useArrive } from "./arrive.js";
+import { PaneLayout } from "./SidePanel.js";
 import { ConversationCharts, TraceCharts } from "./TraceCharts.js";
 import { TraceGuardrails } from "./TraceGuardrails.js";
-import { TurnPicker, TurnStats } from "./TraceOverview.js";
+import { GuardrailStats, TurnPicker, TurnStats } from "./TraceOverview.js";
 import { TraceSpanDetail } from "./TraceSpanDetail.js";
 import { ActorMark, TraceStory } from "./TraceStory.js";
 import { useTraceFormat } from "./TraceValues.js";
@@ -37,7 +37,10 @@ function unitOf(t, field) {
 function operatorValue(t, field) {
     switch (field.kind) {
         case 'options':
-            return { type: 'enum_list', values: (field.options ?? []).map(({ value, label }) => ({ value, label })) };
+            return {
+                type: 'enum_list',
+                values: (field.options ?? []).map(({ value, label }) => ({ value, label })),
+            };
         case 'number': {
             const units = unitOf(t, field);
             return units ? { type: 'float', units } : { type: 'float' };
@@ -55,7 +58,11 @@ function searchField(t, field) {
         label: field.label,
         description: field.doc,
         ...(field.group && { group: field.group }),
-        operators: TRACE_SEARCH_OPERATORS[field.kind].map((key) => ({ key, value, i18nKey: `@astryx.powersearch.operator.${key}` })),
+        operators: TRACE_SEARCH_OPERATORS[field.kind].map((key) => ({
+            key,
+            value,
+            i18nKey: `@astryx.powersearch.operator.${key}`,
+        })),
     };
 }
 /** The search over the spans shown: any text first, then the fields the spans recorded. */
@@ -97,20 +104,27 @@ function TurnRowTotals({ turn }) {
     return (_jsxs(VStack, { gap: 0, hAlign: "end", children: [_jsx(Text, { type: "supporting", hasTabularNumbers: true, children: format.duration(turn.totals.durationMs) }), turn.totals.cost ? (_jsx(Text, { type: "supporting", color: "secondary", hasTabularNumbers: true, children: format.sum(turn.totals.cost, format.usd) })) : null] }));
 }
 /** A row of the whole-trace list: a turn by what the person asked, a host's call by its tool. */
-function TurnRow({ turn, index, isCall, onOpen }) {
+function TurnRow({ turn, index, isCall, onOpen, }) {
     const { t } = useTraceFormat();
+    const arrive = useArrive();
     const row = useMemo(() => traceTurnRow(turn, isCall), [turn, isCall]);
-    return (_jsx(Item, { startContent: _jsx(ActorMark, { actor: row.actor }), label: _jsx(Text, { weight: "medium", maxLines: 1, children: row.title ?? t(isCall ? '@theorem.panel.trace.charts.hostCall' : '@theorem.panel.trace.charts.turn', { index: index + 1 }) }), description: turnRowNote(row), endContent: _jsx(TurnRowTotals, { turn: turn }), align: "start", density: "compact", onClick: onOpen }));
+    return (_jsx(Item, { className: arrive?.className, style: arrive?.style, startContent: _jsx(ActorMark, { actor: row.actor }), label: _jsx(Text, { weight: "medium", maxLines: 1, children: row.title ??
+                t(isCall ? '@theorem.panel.trace.charts.hostCall' : '@theorem.panel.trace.charts.turn', { index: index + 1 }) }), description: turnRowNote(row), endContent: _jsx(TurnRowTotals, { turn: turn }), align: "start", density: "compact", onClick: onOpen }));
 }
 /** Every turn at once: the conversation's totals, each turn's time and tokens, and the turns themselves. */
-function ConversationOverview({ turns, onPick }) {
+function ConversationOverview({ turns, onPick, }) {
     const { t } = useTraceFormat();
     const nodes = useMemo(() => turns.map((turn) => turn.node), [turns]);
-    // Time between turns is the person's, not the agent's: the duration sums the turns.
-    const totals = useMemo(() => ({ ...traceTotals(nodes), durationMs: turns.reduce((total, turn) => total + turn.totals.durationMs, 0) }), [nodes, turns]);
+    // why: Time between turns is the person's, not the agent's: the duration sums the turns.
+    const totals = useMemo(() => ({
+        ...traceTotals(nodes),
+        durationMs: turns.reduce((total, turn) => total + turn.totals.durationMs, 0),
+    }), [nodes, turns]);
     const tools = useMemo(() => traceSpans(nodes).filter((node) => node.meta.type === 'tool').length, [nodes]);
     const isCalls = isCallTrace(turns);
-    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(Text, { weight: "semibold", children: t(isCalls ? '@theorem.panel.trace.calls.count' : '@theorem.panel.trace.conversation', { count: turns.length }) }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: totals, tools: tools }), _jsx(ConversationCharts, { turns: turns, onPick: onPick })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t(isCalls ? '@theorem.panel.trace.calls' : '@theorem.panel.trace.turns') }), _jsx(VStack, { gap: 0, children: turns.map((turn, index) => (_jsx(TurnRow, { turn: turn, index: index, isCall: isCalls, onOpen: () => onPick(index) }, turn.node.id))) })] })] }));
+    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(Text, { weight: "semibold", children: t(isCalls ? '@theorem.panel.trace.calls.count' : '@theorem.panel.trace.conversation', {
+                    count: turns.length,
+                }) }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: totals, tools: tools }), _jsx(ConversationCharts, { turns: turns, onPick: onPick })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t(isCalls ? '@theorem.panel.trace.calls' : '@theorem.panel.trace.turns') }), _jsx(Stream, { children: _jsx(VStack, { gap: 0, children: turns.map((turn, index) => (_jsx(TurnRow, { turn: turn, index: index, isCall: isCalls, onOpen: () => onPick(index) }, turn.node.id))) }) })] })] }));
 }
 /** One turn at a glance, then its story, then its timeline under the search. */
 function TurnOverview({ turns, index, onPick, onBack, selectedId, onSelect, }) {
@@ -126,19 +140,11 @@ function TurnOverview({ turns, index, onPick, onBack, selectedId, onSelect, }) {
     if (!turn || !root)
         return null;
     const tools = traceSpans([root]).filter((node) => node.meta.type === 'tool').length;
-    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(TurnPicker, { turns: turns, index: index, onChange: onPick, onBack: onBack }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: turn.totals, tools: tools, latency: latency }), _jsx(TraceCharts, { root: root, split: turn.split, onSelect: onSelect })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.timeline') }), _jsx(PowerSearch, { config: config, filters: filters, onChange: setFilters, label: t('@theorem.panel.trace.search'), isLabelHidden: true, placeholder: t('@theorem.panel.trace.search.placeholder'), resultCount: matches?.size, size: "sm" }), _jsx(TraceWaterfall, { root: root, selectedId: selectedId, matches: matches, onSelect: onSelect })] }), story.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.story') }), _jsx(TraceStory, { steps: story, selectedId: selectedId, matches: matches, onSelect: onSelect })] })) : null, guardrails.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.guardrails') }), _jsx(TraceGuardrails, { checks: guardrails, onSelect: onSelect })] })) : null] }));
+    return (_jsxs(VStack, { gap: 5, padding: 4, children: [_jsx(TurnPicker, { turns: turns, index: index, onChange: onPick, onBack: onBack }), _jsxs(VStack, { gap: 3, children: [_jsx(TurnStats, { totals: turn.totals, tools: tools, latency: latency }), _jsx(TraceCharts, { root: root, split: turn.split, onSelect: onSelect })] }), _jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.timeline') }), _jsx(PowerSearch, { config: config, filters: filters, onChange: setFilters, label: t('@theorem.panel.trace.search'), isLabelHidden: true, placeholder: t('@theorem.panel.trace.search.placeholder'), resultCount: matches?.size, size: "sm" }), _jsx(TraceWaterfall, { root: root, selectedId: selectedId, matches: matches, onSelect: onSelect }, root.id)] }), story.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.story') }), _jsx(TraceStory, { steps: story, selectedId: selectedId, matches: matches, onSelect: onSelect })] })) : null, guardrails.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.guardrails') }), _jsx(TraceGuardrails, { checks: guardrails, onSelect: onSelect })] })) : null] }));
 }
 function EmptyTrace() {
     const { t } = useTraceFormat();
-    return (_jsx(VStack, { height: "100%", vAlign: "center", padding: 4, children: _jsx(EmptyState, { icon: _jsx(Icon, { icon: IconTimeline, size: "lg", color: "secondary" }), title: t('@theorem.panel.trace.empty.title'), description: t('@theorem.panel.trace.empty.description'), isCompact: true }) }));
-}
-/** Narrow, the open span takes the overview's place; wide, it sits beside it. */
-function TraceLayout({ isWide, overview, detail, detailLabel }) {
-    const { t } = useTraceFormat();
-    if (!isWide) {
-        return (_jsxs(ScrollableArea, { label: t('@theorem.panel.trace.name'), height: "100%", children: [_jsx(TracePatterns, {}), detail ?? overview] }));
-    }
-    return (_jsxs(HStack, { height: "100%", gap: 0, children: [_jsx(StackItem, { size: "fill", children: _jsxs(ScrollableArea, { label: t('@theorem.panel.trace.name'), height: "100%", children: [_jsx(TracePatterns, {}), overview] }) }), detail ? (_jsx("div", { style: { width: '48%', flexShrink: 0, height: '100%', borderInlineStart: '1px solid var(--color-border)' }, children: _jsx(ScrollableArea, { label: detailLabel, height: "100%", children: detail }) })) : null] }));
+    return (_jsx(VStack, { height: "100%", vAlign: "center", padding: 4, children: _jsx(EmptyState, { icon: _jsx(Icon, { icon: IconActivity, size: "lg", color: "secondary" }), title: t('@theorem.panel.trace.empty.title'), description: t('@theorem.panel.trace.empty.description'), isCompact: true }) }));
 }
 /** The open span of the open turn; opening another turn closes it. */
 function useOpenSpan(turns) {
@@ -159,7 +165,7 @@ function useOpenSpan(turns) {
     };
 }
 /** The open span beside or in place of the overview; nothing while none is open. */
-function SpanPane({ open, turnStartMs, isWide, onBack, onOpen }) {
+function SpanPane({ open, turnStartMs, isWide, onBack, onOpen, }) {
     if (!open)
         return null;
     return (_jsx(VStack, { padding: 4, children: _jsx(TraceSpanDetail, { node: open, turnStartMs: turnStartMs, isClose: isWide, onBack: onBack, onOpen: onOpen }) }));
@@ -174,16 +180,27 @@ function Overview({ turns, index, pick, selectedId, select, }) {
  * The panel's content. Narrow, the turn fills it and a span opens in its
  * place; wide, an open span sits beside the turn.
  */
-function TraceInspectorBody({ records, isWide }) {
+function TraceInspectorBody({ records, isWide, }) {
     const tree = useMemo(() => traceTree(records), [records]);
     const turns = useMemo(() => traceTurns(tree), [tree]);
+    const { t } = useTraceFormat();
     const { index, root, open, select, close, pick } = useOpenSpan(turns);
     if (turns.length === 0)
         return _jsx(EmptyTrace, {});
-    const overview = _jsx(Overview, { turns: turns, index: index, pick: pick, selectedId: open?.id, select: select });
-    return (_jsx(TraceLayout, { isWide: isWide, overview: overview, detail: open && _jsx(SpanPane, { open: open, turnStartMs: root?.startMs ?? 0, isWide: isWide, onBack: close, onOpen: select }), detailLabel: open?.meta.label ?? '' }));
+    const overview = (_jsx(Overview, { turns: turns, index: index, pick: pick, selectedId: open?.id, select: select }));
+    return (_jsx(PaneLayout, { isWide: isWide, label: t('@theorem.panel.trace.name'), detailLabel: open?.meta.label ?? '', lead: _jsx(TracePatterns, {}), overview: overview, detail: open && (_jsx(SpanPane, { open: open, turnStartMs: root?.startMs ?? 0, isWide: isWide, onBack: close, onOpen: select })) }));
 }
 /** The inspector over the records a feed has delivered; the panel loads this module when it first opens. */
-export function TraceFeedBody({ traces, isWide }) {
+export function TraceFeedBody({ traces, isWide, }) {
     return _jsx(TraceInspectorBody, { records: useTraceRecords(traces), isWide: isWide });
 }
+/**
+ * Only what the records say of guardrails: how long the checks took, how many
+ * ran and acted, then each check. `head` leads it.
+ */
+export function TraceGuardrailsBody({ records, head, }) {
+    const { t } = useTraceFormat();
+    const roots = useMemo(() => traceTurns(traceTree(records)).map((turn) => turn.node), [records]);
+    const checks = useMemo(() => roots.flatMap(traceGuardrails), [roots]);
+    return (_jsxs(VStack, { gap: 5, padding: 4, children: [head, roots.map((root) => (_jsx(GuardrailStats, { latency: traceLatency(root) }, root.id))), checks.length > 0 ? (_jsxs(VStack, { gap: 2, children: [_jsx(SectionTitle, { title: t('@theorem.panel.trace.guardrails') }), _jsx(TraceGuardrails, { checks: checks })] })) : null] }));
+}

package/ui/TraceInspectorPanel.d.ts

@@ -1,24 +1,46 @@
-import { type ReactNode } from 'react';
+import type { TraceRecord } from '@theoremjs/agents';
 import type { ProfileObservabilityView } from '@theoremjs/agents/interface';
+import { type ReactNode } from 'react';
 import type { TraceFeed } from '../client/trace-feed.ts';
+import { type SidePanelLabels } from './SidePanel.tsx';
 export type TraceInspector = {
     /** The header toggle; null when the host drives the trace or the profile records none. */
     toggle: ReactNode;
-    /** The trace, full size, while it's open; null otherwise. */
+    /** The trace, while it's open; null otherwise. */
     view: ReactNode;
+    /** Words for the docked panel. */
+    labels: SidePanelLabels;
+    /** The profile records traces, so a panel page can dock them even when the host drives the toggle. */
+    offered: boolean;
 };
+/** Where an open trace sits on this page. */
+export declare function TracePlacement({ value, children, }: {
+    value: 'replace' | 'panel';
+    children: ReactNode;
+}): import("react").JSX.Element;
 /**
- * The trace inspector, offered when the profile records traces. Open, the
- * trace takes the surface's place; the two never share the screen. 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 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 declare function useTraceInspector(iface: {
     observability?: Pick<ProfileObservabilityView, 'record'>;
 }, traces?: TraceFeed, open?: boolean): TraceInspector;
-/** The surface, or the trace in its place; the surface stays mounted underneath, so nothing it holds is lost. */
-export declare function WithTrace({ inspector, children }: {
+/** The surface, or the trace in its place — or, on a docked page, beside it. */
+export declare function WithTrace({ inspector, children, }: {
     inspector: TraceInspector;
     children: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * 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 declare function TraceGuardrailsView({ records, head, }: {
+    records: readonly TraceRecord[];
+    head?: ReactNode;
+}): import("react").JSX.Element;

package/ui/TraceInspectorPanel.js

@@ -1,57 +1,95 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { Card } from '@astryxdesign/core/Card';
+import { jsx as _jsx } from "react/jsx-runtime";
 import { Icon } from '@astryxdesign/core/Icon';
-import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
-import { VStack } from '@astryxdesign/core/VStack';
-import { IconTimeline } from '@tabler/icons-react';
-import { lazy, Suspense, useCallback, useId, useState } from 'react';
-import { useLabels } from "./labels-provider.js";
-import { isSidePanelWide, RAISED, SidePanelHeader, SidePanelToggle } from "./SidePanel.js";
-// The inspector and its charts are fetched when the trace first opens, not with the chat.
+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 })));
-/** The element's width, kept current. */
-function useWidth() {
-    const [width, setWidth] = useState(0);
-    const ref = useCallback((node) => {
-        if (!node)
-            return;
-        const observer = new ResizeObserver(([entry]) => setWidth(entry?.contentRect.width ?? 0));
-        observer.observe(node);
-        return () => observer.disconnect();
-    }, []);
-    return { ref, width };
+/** `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 }) {
-    const { ref, width } = useWidth();
-    return (_jsx(Layout, { height: "fill", header: header, content: _jsx(LayoutContent, { padding: 0, isScrollable: false, children: _jsx(VStack, { height: "100%", paddingInline: 3, children: _jsx(Card, { variant: "transparent", height: "100%", padding: 0, style: RAISED, children: _jsx("div", { id: id, ref: ref, style: { height: '100%' }, children: _jsx(Suspense, { fallback: null, children: _jsx(TraceFeedBody, { traces: traces, isWide: isSidePanelWide(width) }) }) }) }) }) }) }));
+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. Open, the
- * trace takes the surface's place; the two never share the screen. 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 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);
-    if (iface.observability?.record !== true)
-        return { toggle: null, view: null };
-    const isOpen = open ?? own;
+    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'),
     };
-    const toggle = open === undefined ? (_jsx(SidePanelToggle, { labels: labels, icon: _jsx(Icon, { icon: IconTimeline }), panelId: id, open: isOpen, onToggle: () => setOwn((value) => !value) })) : null;
-    return {
-        toggle,
-        view: isOpen ? _jsx(TraceView, { id: id, header: toggle ? _jsx(SidePanelHeader, { children: toggle }) : undefined, traces: traces }) : null,
-    };
+    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 surface, or the trace in its place; the surface stays mounted underneath, so nothing it holds is lost. */
-export function WithTrace({ inspector, children }) {
-    return (_jsxs(_Fragment, { children: [inspector.view, _jsx("div", { style: { display: inspector.view ? 'none' : 'contents' }, children: children })] }));
+/** 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

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+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. */
@@ -23,11 +23,15 @@ export declare function TurnPicker({ turns, index, onChange, onBack, }: {
     /** 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;
+ * 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 }: {
+export declare function TurnStats({ totals, tools, latency, }: {
     totals: TraceTotals;
     tools: number;
     latency?: TraceLatency;

package/ui/TraceOverview.js

@@ -9,9 +9,10 @@ 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 { TRACE_HUE } from "./trace-palette.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;
 /**
@@ -20,7 +21,15 @@ export const FIRST_WIDTH_PX = 280;
  * where it was. Clicks and pointer drags still reach the chart.
  */
 export function ChartFrame({ children }) {
-    return _jsx("div", { onMouseDown: (event) => event.preventDefault(), children: 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 }) {
@@ -40,9 +49,13 @@ export function TurnPicker({ turns, index, onChange, onBack, }) {
     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) })] })] })] }));
+    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 }) {
+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)
@@ -53,14 +66,18 @@ function FirstTextStat({ latency, format }) {
         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) }),
+            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) });
+    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) {
@@ -71,26 +88,39 @@ function TokensStat({ totals, format }) {
     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) }) }));
+    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 }) {
+function StepsStat({ totals, tools, format, }) {
     const { t } = format;
-    // With no model, every step is a tool call the heading already counts.
+    // 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 }) {
+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 }) }));
+    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;
+ * 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 }) {
+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 })] }));
 }