@theoremjs/react 0.3.0 → 0.3.1

package/ui/ChatTranscript.js

@@ -1,32 +1,40 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { AspectRatio } from '@astryxdesign/core/AspectRatio';
-import { ChatMessage, ChatMessageBubble, ChatMessageList, ChatMessageMetadata, ChatToolCalls, } from '@astryxdesign/core/Chat';
+import { ChatMessage, ChatMessageBubble, ChatMessageList, ChatMessageMetadata, ChatSystemMessage, ChatToolCalls, } from '@astryxdesign/core/Chat';
 import { Citation } from '@astryxdesign/core/Citation';
 import { ClickableCard } from '@astryxdesign/core/ClickableCard';
 import { Collapsible } from '@astryxdesign/core/Collapsible';
 import { HStack } from '@astryxdesign/core/HStack';
+import { useStreamingText } from '@astryxdesign/core/hooks';
 import { Icon } from '@astryxdesign/core/Icon';
 import { IconButton } from '@astryxdesign/core/IconButton';
+import { useLocale } from '@astryxdesign/core/i18n';
 import { useLightbox } from '@astryxdesign/core/Lightbox';
-import { useStreamingText } from '@astryxdesign/core/hooks';
 import { Markdown } from '@astryxdesign/core/Markdown';
 import { Skeleton } from '@astryxdesign/core/Skeleton';
 import { Text } from '@astryxdesign/core/Text';
 import { Thumbnail } from '@astryxdesign/core/Thumbnail';
 import { Timestamp } from '@astryxdesign/core/Timestamp';
 import { Token } from '@astryxdesign/core/Token';
+import { Tooltip as HoverTip } from '@astryxdesign/core/Tooltip';
 import { VStack } from '@astryxdesign/core/VStack';
 import { IconCheck, IconCopy } from '@tabler/icons-react';
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { stopText } from '@theoremjs/agents/interface';
+import { createContext, useContext, useEffect, useMemo, useRef, useState, } from 'react';
 import { citationsFromBlock } from "../client/source-citations.js";
-import { assistantTurnCopyText, assistantTurnTiming, composeAssistantTurn, groupTranscriptBlocks, pendingPromptOf, promptReplyKey, replyKey, toolCallLabel, workStatus, } from "../client/transcript-groups.js";
+import { assistantTurnCopyText, assistantTurnTiming, composeAssistantTurn, groupTranscriptBlocks, pendingPromptOf, promptReplyKey, promptTime, replyKey, toolCallLabel, workStatus, } from "../client/transcript-groups.js";
+import { useSecondTicker } from "../hooks/use-second-ticker.js";
 import { useDisclosureMotion } from "./disclosure-motion.js";
-import { workDuration, workStatusLabel } from "./labels.js";
+import { usageLine, workDuration, workStatusLabel } from "./labels.js";
 import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { useMarkdownPlugins } from "./markdown-plugins.js";
+import { keyedByContent } from "./row-keys.js";
 import { ShapedData } from "./ShapedData.js";
-import { transcriptBlockCopyText } from "./transcript-copy-text.js";
 import { ApprovalCard, AuthChallengeCard } from "./ToolGateCard.js";
+import { transcriptBlockCopyText } from "./transcript-copy-text.js";
 import { VoiceNote } from "./VoiceNote.js";
+/** Whether the transcript shows usage (`ChatTranscriptProps.usage`). */
+const ShowUsage = createContext(false);
 /** Largest a generated image renders in the transcript. */
 const GENERATED_IMAGE_MAX_WIDTH = 512;
 /** First-seen time per group key, so timestamps don't jump while streaming. */
@@ -39,18 +47,6 @@ function useFirstSeen(keys) {
     }
     return (key) => times.current.get(key) ?? now;
 }
-/** `Date.now()`, refreshed every second while `isActive`. */
-function useSecondTicker(isActive) {
-    const [now, setNow] = useState(() => Date.now());
-    useEffect(() => {
-        if (!isActive)
-            return;
-        setNow(Date.now());
-        const timer = globalThis.setInterval(() => setNow(Date.now()), 1_000);
-        return () => globalThis.clearInterval(timer);
-    }, [isActive]);
-    return now;
-}
 /**
  * Each turn's span, keyed by the user group that started it. A turn stops at
  * a gate and streams again under the same prompt once it's answered; the wait
@@ -58,7 +54,7 @@ function useSecondTicker(isActive) {
  */
 function useTurnSpans(streaming, lastUserKey) {
     const spans = useRef(new Map());
-    // The first send mounts the transcript already streaming; that's the start.
+    // why: The first send mounts the transcript already streaming; that's the start.
     const wasStreaming = useRef(false);
     if (lastUserKey && streaming !== wasStreaming.current) {
         const now = Date.now();
@@ -106,13 +102,36 @@ function MessageTime({ at }) {
     }
     return _jsx(Timestamp, { value: at, format: "relative_short", isLive: true });
 }
-/** A message's time, copy button and status; a failure says why on the line beneath. */
+/** What a reply or a called agent used, in the viewer's locale. */
+function Usage({ tokens }) {
+    return usageLine(useLabels(), useLocale(), tokens);
+}
+/** Why a turn stopped short, drawn as the delivery statuses are. */
+function Stopped({ label }) {
+    return (_jsxs(HStack, { gap: 1, vAlign: "center", children: [_jsx(Icon, { icon: "stop", size: "xsm", color: "inherit" }), _jsx("span", { children: label })] }));
+}
+/** A failed message's status, drawn as Astryx draws its error status; the reason shows on hover. */
+function Failed({ reason }) {
+    const label = useLabels()('@theorem.transcript.failed');
+    return (_jsx(HoverTip, { content: reason, children: _jsxs(HStack, { gap: 1, vAlign: "center", style: { color: 'var(--color-error)' }, children: [_jsx(Icon, { icon: "error", size: "xsm", color: "inherit" }), _jsx("span", { children: label })] }) }));
+}
+/** A message's copy button and time, the button on the outside: right for the person, left for the agent. */
+function CopyAndTime(props) {
+    const copy = _jsx(CopyButton, { text: props.copyText });
+    const time = _jsx(MessageTime, { at: props.at });
+    return (_jsxs(HStack, { gap: 1, vAlign: "center", children: [props.sender === 'user' ? time : copy, props.sender === 'user' ? copy : time] }));
+}
+/** A message's copy button (outermost), time and status; a failure says why on hovering its status. */
 function MessageChrome(props) {
-    const failed = props.error !== undefined;
-    const metadata = (_jsx(ChatMessageMetadata, { timestamp: _jsx(MessageTime, { at: props.at }), footer: _jsx(CopyButton, { text: props.copyText }), status: failed ? 'error' : props.status }));
-    if (!failed)
-        return metadata;
-    return (_jsxs(VStack, { gap: 1, children: [metadata, _jsx(Text, { type: "supporting", color: "secondary", children: props.error })] }));
+    const usage = props.usage ? _jsx(Usage, { tokens: props.usage }) : undefined;
+    const aside = props.error !== undefined ? (_jsx(Failed, { reason: props.error })) : props.stopped !== undefined ? (_jsx(Stopped, { label: props.stopped })) : (usage);
+    return (_jsx(ChatMessageMetadata
+    // why: The row's first slot is the one nearest the margin.
+    , { 
+        // why: The row's first slot is the one nearest the margin.
+        timestamp: _jsx(CopyAndTime, { sender: props.sender, at: props.at, copyText: props.copyText }), 
+        // why: Astryx's statuses are a closed set, so these ride the footer.
+        footer: aside, status: props.error !== undefined || props.stopped !== undefined ? undefined : props.status }));
 }
 function dataUrl(mimeType, data) {
     return data === undefined ? undefined : `data:${mimeType};base64,${data}`;
@@ -184,7 +203,10 @@ function GeneratedGallery({ items, ratio }) {
     return (_jsxs(VStack, { gap: 2, width: "100%", children: [items.map((item, i) => item.media.type === 'image' ? (_jsx(GeneratedImage, { item: item, ratio: ratio, onOpen: () => lightbox.open(i) }, item.media.src)) : (_jsx(Thumbnail, { alt: item.media.alt, label: item.media.alt, onClick: () => lightbox.open(i) }, item.media.src))), lightbox.element] }));
 }
 /** An image takes seconds: a slow, smooth breath rather than the Skeleton's quick stepped blink. */
-const GENERATING_PULSE = { animationDuration: '1.8s', animationTimingFunction: 'ease-in-out' };
+const GENERATING_PULSE = {
+    animationDuration: '1.8s',
+    animationTimingFunction: 'ease-in-out',
+};
 /** Placeholder shaped like the image being generated. */
 function GeneratingImage({ ratio }) {
     const t = useLabels();
@@ -229,12 +251,13 @@ function StreamedMarkdown({ text, streaming, density, components, }) {
     const [revealing, setRevealing] = useState(streaming);
     if (streaming && !revealing)
         setRevealing(true);
+    const plugins = useMarkdownPlugins();
     const shown = useStreamingText(text, revealing);
     useEffect(() => {
         if (!streaming && shown.length >= text.length)
             setRevealing(false);
     }, [streaming, shown, text]);
-    return (_jsx(Markdown, { isStreaming: revealing, density: density, components: components, children: text }));
+    return (_jsx(Markdown, { isStreaming: revealing, density: density, components: components, plugins: plugins, children: text }));
 }
 function BodyBlock({ block, streaming }) {
     if (block.kind === 'text')
@@ -243,10 +266,9 @@ function BodyBlock({ block, streaming }) {
         return _jsx(ToolCall, { tool: block.tool });
     return _jsx(ResultBlock, { block: block });
 }
-/** Non-streaming answer rows: errors, sources, structured output and media. */
+/** Non-streaming answer rows: errors, sources, structured output, and media. */
 function ResultBlock({ block }) {
     switch (block.kind) {
-        // A failure shows on the message's metadata line (MessageChrome).
         case 'error':
             return null;
         case 'citation':
@@ -259,7 +281,7 @@ function ResultBlock({ block }) {
             return null;
     }
 }
-// Astryx sets a call's name in the code font; labels are sentences, so the row takes the body
+// why: Astryx sets a call's name in the code font; labels are sentences, so the row takes the body
 // font and the detail restores the code font kept on the wrapper.
 const CODE_FONT_KEPT = {
     display: 'contents',
@@ -281,16 +303,20 @@ function toolDuration(t, tool) {
         return {};
     return { duration: workDuration(t, tool.endedAt - tool.startedAt) };
 }
-function toolCallItem(t, id, tool) {
+/** What the agent an agent tool ran used, after the call's name. Only agent tools report it. */
+function toolUsageStats(state, showUsage) {
+    return showUsage && state.tokens ? { stats: _jsx(Usage, { tokens: state.tokens }) } : {};
+}
+function toolCallItem(t, id, tool, showUsage) {
     const base = { key: id, name: toolCallLabel(tool) };
     const { state } = tool;
     switch (state?.phase) {
         case 'error':
-            // What failed, as the tool reported it; the whole failure is in the detail.
             return {
                 ...base,
                 status: 'error',
                 target: state.failure.message,
+                ...toolUsageStats(state, showUsage),
                 errorMessage: state.failure.message,
                 resultDetail: toolDetail(t, tool, _jsx(ShapedData, { value: state.failure, title: t('@theorem.transcript.tool_error') })),
             };
@@ -299,6 +325,7 @@ function toolCallItem(t, id, tool) {
                 ...base,
                 status: 'complete',
                 ...toolDuration(t, tool),
+                ...toolUsageStats(state, showUsage),
                 resultDetail: toolDetail(t, tool, state.output === undefined ? undefined : (_jsx(ShapedData, { value: state.output, title: t('@theorem.transcript.tool_output') }))),
             };
         case 'running':
@@ -309,7 +336,8 @@ function toolCallItem(t, id, tool) {
 }
 function ToolCall({ tool }) {
     const t = useLabels();
-    return _jsx(ToolCalls, { calls: [toolCallItem(t, tool.name, tool)] });
+    const showUsage = useContext(ShowUsage);
+    return _jsx(ToolCalls, { calls: [toolCallItem(t, tool.name, tool, showUsage)] });
 }
 /**
  * Thinking reads as quieter text than the reply. Astryx has no reasoning
@@ -322,6 +350,7 @@ const THOUGHT_MARKDOWN = {
 };
 function TraceList({ items, streaming }) {
     const t = useLabels();
+    const showUsage = useContext(ShowUsage);
     const rows = [];
     let tools = [];
     const flush = () => {
@@ -332,7 +361,7 @@ function TraceList({ items, streaming }) {
     };
     for (const [i, item] of items.entries()) {
         if (item.kind === 'tool') {
-            tools.push(toolCallItem(t, item.id, item.block.tool));
+            tools.push(toolCallItem(t, item.id, item.block.tool, showUsage));
             continue;
         }
         flush();
@@ -341,17 +370,28 @@ function TraceList({ items, streaming }) {
     flush();
     return _jsx(VStack, { gap: 2, children: rows });
 }
-function GateCard({ block, handlers }) {
+/** The gate a person decides. The page answers a page gate, so it has none. */
+function personGate(tool) {
+    if (tool.state?.phase !== 'gate' || tool.state.gate.kind === 'page')
+        return null;
+    return tool.state.gate;
+}
+/** The answer on its way for this tool's gate, if the one being sent is this tool's. */
+function answerSent(answering, tool) {
+    const ours = answering?.callId === tool.callId && answering?.operationId === tool.operationId;
+    return ours ? answering.action : null;
+}
+function GateCard({ block, handle, handlers, }) {
     const { tool } = block;
-    if (tool.state?.phase !== 'gate')
+    const gate = personGate(tool);
+    if (!gate)
         return null;
-    const { gate } = tool.state;
     const index = handlers.indexOf(block);
-    const answer = handlers.answering?.callId === tool.callId ? handlers.answering.action : null;
+    const answer = answerSent(handlers.answering, tool);
     if (gate.kind === 'auth') {
         return (_jsx(AuthChallengeCard, { gate: gate, toolName: tool.name, submitted: answer === 'auth', onAuthenticated: (secret) => handlers.onAuthenticated?.(index, secret) }));
     }
-    return (_jsx(ApprovalCard, { gate: gate, toolName: tool.name, input: tool.arguments, decided: answer === 'auth' ? null : answer, onDecision: (action) => handlers.onToolDecision?.(index, action) }));
+    return (_jsx(ApprovalCard, { gate: gate, toolName: tool.name, agent: handle, input: tool.arguments, decided: answer === 'auth' ? null : answer, onDecision: (action) => handlers.onToolDecision?.(index, action) }));
 }
 /** Live elapsed time while the turn streams; its final duration once it ends. */
 /** Live: counted from the start. Stopped: the work its blocks record. */
@@ -381,7 +421,7 @@ function TurnStatus(props) {
         return label;
     return (_jsx(Collapsible, { trigger: label, isOpen: traceOpen, onOpenChange: setTraceOpen, children: _jsx(TraceList, { items: props.trace, streaming: streaming }) }));
 }
-function BodyRowView({ row, streaming, imageOutput }) {
+function BodyRowView({ row, streaming, imageOutput, }) {
     if (row.kind === 'block')
         return _jsx(BodyBlock, { block: row.block, streaming: streaming });
     if (imageOutput)
@@ -396,15 +436,16 @@ function PendingImage(props) {
 }
 function AssistantTurn(props) {
     const t = useLabels();
+    const showUsage = useContext(ShowUsage);
     const elapsedMs = useTurnElapsed(props.streaming, props.startedAt, props.workedMs);
     const { trace, gatedTools, body, hasTrace } = composeAssistantTurn(props.blocks);
     const rows = bodyRows(t, body);
     const status = workStatusLabel(t, workStatus({ streaming: props.streaming, hasTrace, elapsedMs }));
     const copyText = assistantTurnCopyText(body.length > 0 ? body : props.blocks);
-    return (_jsx(ChatMessage, { sender: "assistant", name: props.handle, metadata: props.streaming ? undefined : _jsx(MessageChrome, { at: props.at, copyText: copyText, error: props.error }), children: _jsxs(VStack, { gap: 3, width: "100%", children: [_jsx(TurnStatus, { status: status, trace: trace, hasTrace: hasTrace, streaming: props.streaming }), gatedTools.map((block) => (_jsx(GateCard, { block: block, handlers: props.handlers }, block.id))), rows.map((row, i) => (_jsx(BodyRowView
-                // By position: the committed turn re-mints block ids, and a
+    return (_jsx(ChatMessage, { sender: "assistant", name: props.handle, metadata: props.streaming ? undefined : (_jsx(MessageChrome, { sender: "assistant", at: props.at, copyText: copyText, error: props.error, stopped: props.stopped, usage: showUsage ? props.usage : undefined })), children: _jsxs(VStack, { gap: 3, width: "100%", children: [_jsx(TurnStatus, { status: status, trace: trace, hasTrace: hasTrace, streaming: props.streaming }), gatedTools.map((block) => (_jsx(GateCard, { block: block, handle: props.handle, handlers: props.handlers }, block.id))), keyedByContent(rows, (row) => (row.kind === 'gallery' ? 'gallery' : row.block.kind)).map(({ item: row, index: i, key }) => (_jsx(BodyRowView
+                // why: Not the block id: the committed turn re-mints ids, and a
                 // remount would cut the text reveal short.
-                , { row: row, streaming: props.streaming && i === rows.length - 1, imageOutput: props.imageOutput }, i))), _jsx(PendingImage, { imageOutput: props.imageOutput, streaming: props.streaming, rows: rows })] }) }));
+                , { row: row, streaming: props.streaming && i === rows.length - 1, imageOutput: props.imageOutput }, key))), _jsx(PendingImage, { imageOutput: props.imageOutput, streaming: props.streaming, rows: rows })] }) }));
 }
 function UserTurn(props) {
     const t = useLabels();
@@ -412,8 +453,8 @@ function UserTurn(props) {
         .map((block) => transcriptBlockCopyText(t, block))
         .filter(Boolean)
         .join('\n\n');
-    const chrome = _jsx(MessageChrome, { at: props.at, copyText: copyText, status: props.status, error: props.error });
-    // Astryx: metadata goes on the last bubble, or on the message when the last
+    const chrome = (_jsx(MessageChrome, { sender: "user", at: props.at, copyText: copyText, status: props.status, stopped: props.stopped, error: props.error }));
+    // why: Astryx: metadata goes on the last bubble, or on the message when the last
     // content is unbubbled (an attachment or voice note).
     const last = props.blocks.at(-1);
     const lastIsBubble = last?.kind === 'user-text';
@@ -429,15 +470,14 @@ function isBareFailure(group) {
 }
 /** Theorem transcript blocks rendered as Astryx chat messages. */
 export function ChatTranscript(props) {
-    return (_jsx(TheoremLabelsProvider, { children: _jsx(ChatTranscriptBody, { ...props }) }));
+    return (_jsx(TheoremLabelsProvider, { children: _jsx(ShowUsage.Provider, { value: props.usage === true, children: _jsx(ChatTranscriptBody, { ...props }) }) }));
 }
-function ChatTranscriptBody({ blocks, handle, streaming = false, delivery, onToolDecision, answering = null, onAuthenticated, emptyState, imageOutput, }) {
-    const groups = useMemo(() => groupTranscriptBlocks(blocks), [blocks]);
+function ChatTranscriptBody({ blocks, handle, streaming = false, delivery, onToolDecision, answering = null, onAuthenticated, emptyState, dividers, imageOutput, labels, }) {
+    const groups = useMemo(() => groupTranscriptBlocks(blocks, dividers && new Set(Object.keys(dividers))), [blocks, dividers]);
     const timeOf = useFirstSeen(groups.map((group, index) => (group.kind === 'user' ? group.key : replyKey(groups, index))));
     const spans = useTurnSpans(streaming, groups.findLast((group) => group.kind === 'user')?.key);
     const pendingPrompt = streaming ? pendingPromptOf(groups) : undefined;
     const listRef = useRef(null);
-    // Disclosures ease open and shut in place; opening one never moves the transcript.
     useDisclosureMotion(listRef);
     const handlers = {
         indexOf: (block) => blocks.findIndex((entry) => entry.id === block.id),
@@ -448,24 +488,37 @@ function ChatTranscriptBody({ blocks, handle, streaming = false, delivery, onToo
     const turn = { handle, handlers, imageOutput };
     const lastUser = groups.findLastIndex((group) => group.kind === 'user');
     const userTurn = (group, index) => {
-        // A turn that failed before any reply shows it on the message itself.
         const next = groups[index + 1];
         const error = isBareFailure(next) ? failureOf(next) : undefined;
         const status = index === lastUser ? (delivery ?? undefined) : undefined;
-        return _jsx(UserTurn, { blocks: group.blocks, at: timeOf(group.key), status: status, error: error }, group.key);
+        return (_jsx(UserTurn, { blocks: group.blocks, at: promptTime(groups, index, timeOf), status: status, stopped: stopText(group.stop, group.blocks, labels), error: error }, group.key));
     };
-    const turns = groups.flatMap((group, index) => {
+    const turnOf = (group, index) => {
         if (group.kind === 'user')
             return userTurn(group, index);
         if (isBareFailure(group) && groups[index - 1]?.kind === 'user')
             return [];
-        const { key, live, endedAt, ...timing } = assistantTurnTiming({ groups, index, streaming, timeOf, spans });
-        // A reply is dated when it last stopped: a reply that just finished reads "now".
+        const { key, live, endedAt, ...timing } = assistantTurnTiming({
+            groups,
+            index,
+            streaming,
+            timeOf,
+            spans,
+        });
+        // why: A reply is dated when it last stopped: a reply that just finished reads "now".
         const at = endedAt ?? timeOf(key);
-        return (_jsx(AssistantTurn, { ...turn, ...timing, blocks: group.blocks, streaming: live, at: at, error: failureOf(group) }, key));
+        return (_jsx(AssistantTurn, { ...turn, ...timing, blocks: group.blocks, streaming: live, at: at, error: failureOf(group), stopped: stopText(group.stop, group.blocks, labels), usage: group.usage }, key));
+    };
+    const turns = groups.flatMap((group, index) => {
+        const label = dividers?.[group.key];
+        if (label === undefined)
+            return turnOf(group, index);
+        return [
+            _jsx(ChatSystemMessage, { variant: "divider", children: label }, `divider:${group.key}`),
+            turnOf(group, index),
+        ].flat();
     });
-    // Nothing streamed back yet: show the reply's "Working…" status right away.
-    // It sits in the same keyed list as the streamed reply, so the reply stays
+    // why: It sits in the same keyed list as the streamed reply, so the reply stays
     // one message; a remount would read to the layout as a new message.
     if (pendingPrompt) {
         turns.push(_jsx(AssistantTurn, { ...turn, blocks: [], streaming: true, at: timeOf(pendingPrompt.key), startedAt: timeOf(pendingPrompt.key) }, promptReplyKey(pendingPrompt)));

package/ui/ConsoleFrame.d.ts

@@ -1,8 +1,53 @@
-import type { CSSProperties, ReactNode } from 'react';
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import { type CSSProperties, type ReactNode } from 'react';
+import type { HttpOptions } from '../client/transport.ts';
+import type { TheoremLabels } from './labels.ts';
 import { type TraceInspector } from './TraceInspectorPanel.tsx';
+/** The props a one-call console page shares: its look, its wording, its trace, and its layout. */
+export type ConsolePageProps = {
+    /** Extra fetch options for the default HTTP transport (auth headers, custom fetch). */
+    http?: HttpOptions;
+    theme?: DefinedTheme;
+    mode?: 'system' | 'light' | 'dark';
+    /** Replacement lines by locale, for any `@theorem.*` or `@astryx.*` key. */
+    labels?: TheoremLabels;
+    /** Widest the column may grow, as a CSS length. Default `960px`. */
+    maxWidth?: string;
+    /**
+     * Drive the trace from the host's own control. The built-in toggle hides.
+     * The open trace takes the result's place, unless this page is inside
+     * `TracePlacement value="panel"`, where it docks. Omit to keep the toggle.
+     * Needs a profile that records traces.
+     */
+    trace?: boolean;
+    /**
+     * The page is already a raised panel. The console sits in it instead of
+     * painting the ground it uses on a flat page.
+     */
+    flush?: boolean;
+    /** The request on the left and the result on the right. */
+    columns?: boolean;
+    className?: string;
+    style?: CSSProperties;
+};
 export type ConsoleFrameProps = {
     inspector: TraceInspector;
     maxWidth: string;
+    /**
+     * The page is already a raised panel. The console sits in that panel instead
+     * of painting the ground it uses when the page behind it is flat.
+     */
+    flush?: boolean;
+    /**
+     * The request and the response sit side by side. The request is a start
+     * panel at two fifths of that pair, so its handle is on the trailing edge
+     * and the response fills the other three fifths. Below the shell's drawer
+     * breakpoint they stack, request first. Two children: the request, then the
+     * response. One child keeps the single column.
+     */
+    columns?: boolean;
+    /** The request column's name, read by its scroll region and its resize handle. */
+    requestLabel?: string;
     className?: string;
     style?: CSSProperties;
     children: ReactNode;
@@ -11,7 +56,17 @@ export type ConsoleFrameProps = {
  * A console's page, for decisions and hosts alike: the trace's toggle in the
  * header, and one raised panel, flush with the host's, scrolling inside.
  */
-export declare function ConsoleFrame({ inspector, maxWidth, className, style, children }: ConsoleFrameProps): import("react").JSX.Element;
+export declare function ConsoleFrame({ inspector, maxWidth, flush, columns, requestLabel, className, style, children, }: ConsoleFrameProps): import("react").JSX.Element;
+/** One card of a response with several: its request and result sit in it without cards of their own. */
+export declare function ConsoleSection({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The response. Beside the request it scrolls in the panel; a centred state fills the card, as an empty trace does. */
+export declare function ResponseColumn({ label, fill, children, }: {
+    label: string;
+    fill?: boolean;
+    children: ReactNode;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null | undefined;
 export type ConsoleView = 'fields' | 'json';
 export type RequestCardProps = {
     title: string;
@@ -26,7 +81,7 @@ export type RequestCardProps = {
 /** The request's card: its heading with the Fields/JSON switch, then the request and its run bar. */
 export declare function RequestCard({ title, view, hasFields, onView, onRun, children }: RequestCardProps): import("react").JSX.Element;
 /** The request as JSON text, marked while it doesn't parse. */
-export declare function JsonRequest({ label, text, isInvalid, onChange }: {
+export declare function JsonRequest({ label, text, isInvalid, onChange, }: {
     label: string;
     text: string;
     isInvalid: boolean;
@@ -44,4 +99,6 @@ export type RunBarProps = {
     onStop: () => void;
 };
 /** A note on the request, Stop while it runs, and Run. */
-export declare function RunBar({ note, isReady, isRunning, runLabel, runningLabel, stopLabel, onRun, onStop }: RunBarProps): import("react").JSX.Element;
+export declare function RunBar({ note, isReady, isRunning, runLabel, runningLabel, stopLabel, onRun, onStop, }: RunBarProps): import("react").JSX.Element;
+/** A size in bytes as the reader's locale writes it: bytes under a kilobyte, else kilobytes. */
+export declare function useBytes(): (bytes: number) => string;

package/ui/ConsoleFrame.js

@@ -3,20 +3,102 @@ import { Button } from '@astryxdesign/core/Button';
 import { Card } from '@astryxdesign/core/Card';
 import { Center } from '@astryxdesign/core/Center';
 import { HStack } from '@astryxdesign/core/HStack';
+import { useLocale } from '@astryxdesign/core/i18n';
 import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
+import { useResizable } from '@astryxdesign/core/Resizable';
 import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
 import { Text } from '@astryxdesign/core/Text';
 import { TextArea } from '@astryxdesign/core/TextArea';
 import { VStack } from '@astryxdesign/core/VStack';
+import { Children, createContext, use, useMemo, useRef, useSyncExternalStore, } from 'react';
 import { useLabels } from "./labels-provider.js";
-import { RAISED, SidePanelHeader } from "./SidePanel.js";
+import { PanelBody, PanelScroll, RAISED, SidePanel, SidePanelHeader } from "./SidePanel.js";
+import { textRows } from "./StateFields.js";
 import { WithTrace } from "./TraceInspectorPanel.js";
+import { CONSOLE_CARD } from "./trace-patterns.js";
+/** Cards on a flush console. The flat page uses the surface; a raised page uses the card. */
+const FLUSH_CARD = {
+    '--theorem-console-card': 'var(--color-background-muted)',
+};
+/** Below the app shell's drawer breakpoint, where the two columns stack. */
+const NARROW = '(width < 768px)';
+/** Side by side, the panel card is the frame, so the request and response bring no card of their own. */
+const ConsoleChrome = createContext(true);
+function useNarrow() {
+    return useSyncExternalStore((change) => {
+        const query = globalThis.matchMedia(NARROW);
+        query.addEventListener('change', change);
+        return () => {
+            query.removeEventListener('change', change);
+        };
+    }, () => globalThis.matchMedia(NARROW).matches, () => false);
+}
+/**
+ * One column: the request, then the response under it, in the page's own card.
+ * `wide` is a pair stacked on a narrow page, which takes the page's width.
+ */
+function ConsoleSingle({ flush, wide, maxWidth, children, }) {
+    return (_jsx(VStack, { height: "100%", paddingInline: 3, style: flush ? FLUSH_CARD : undefined, children: _jsx(Card, { variant: "transparent", height: "100%", padding: 0, style: flush ? { overflowY: 'auto' } : { ...RAISED, overflowY: 'auto' }, children: _jsx(Center, { axis: "horizontal", width: "100%", minHeight: "100%", children: _jsx(VStack, { width: "100%", maxWidth: wide ? undefined : maxWidth, gap: 3, padding: 4, children: children }) }) }) }));
+}
 /**
  * A console's page, for decisions and hosts alike: the trace's toggle in the
  * header, and one raised panel, flush with the host's, scrolling inside.
  */
-export function ConsoleFrame({ inspector, maxWidth, className, style, children }) {
-    return (_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { height: "fill", className: className, style: style, header: inspector.toggle ? _jsx(SidePanelHeader, { children: inspector.toggle }) : undefined, 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, overflowY: 'auto' }, children: _jsx(Center, { axis: "horizontal", width: "100%", children: _jsx(VStack, { width: "100%", maxWidth: maxWidth, gap: 3, padding: 4, children: children }) }) }) }) }) }) }));
+export function ConsoleFrame({ inspector, maxWidth, flush = false, columns = false, requestLabel, className, style, children, }) {
+    const layoutRef = useRef(null);
+    return (_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { ref: layoutRef, height: "fill", className: className, style: style, header: inspector.toggle ? _jsx(SidePanelHeader, { children: inspector.toggle }) : undefined, content: _jsx(LayoutContent, { padding: 0, isScrollable: false, children: _jsx(ConsoleBody, { layoutRef: layoutRef, flush: flush, columns: columns, maxWidth: maxWidth, requestLabel: requestLabel, children: children }) }) }) }));
+}
+/** The console's panels: a request and response side by side when there is room, else one column. */
+function ConsoleBody({ layoutRef, flush, columns, maxWidth, requestLabel, children, }) {
+    const narrow = useNarrow();
+    // why: Children.count counts a null slot; toArray drops it, which is the child that is actually drawn.
+    const drawn = Children.toArray(children).length;
+    const paired = columns && drawn > 1;
+    if (paired && !narrow) {
+        return (_jsx(ConsoleColumns, { requestLabel: requestLabel, basisWidth: layoutRef.current?.clientWidth ?? 0, children: children }));
+    }
+    return (_jsx(ConsoleSingle, { flush: flush, wide: paired, maxWidth: maxWidth, children: children }));
+}
+/**
+ * The request is the sized panel and the response fills what it leaves, so
+ * one handle keeps the pair at two fifths / three fifths. The request sizes
+ * against this inner layout, not the page, so a trace docked outside the pair
+ * cannot take the request's share.
+ */
+function ConsoleColumns({ requestLabel = 'Request', basisWidth, children, }) {
+    const t = useLabels();
+    const pairRef = useRef(null);
+    // why: a percentage default resolves against a 1200px stand-in until the pair
+    // is measured, and the panel's width transition then eases between the two,
+    // reflowing the request. This layout is already on screen, so the first
+    // width is two fifths of it. 70% leaves the response a readable share, and a
+    // percentage maximum follows the pair when the trace opens.
+    const requestPanel = useResizable({
+        defaultSize: basisWidth > 0 ? Math.round(basisWidth * 0.4) : '40%',
+        minSize: 280,
+        maxSize: '70%',
+        containerRef: pairRef,
+    });
+    const [request, response] = Children.toArray(children);
+    const labels = {
+        name: requestLabel,
+        show: requestLabel,
+        hide: requestLabel,
+        resize: t('@theorem.panel.resize', { name: requestLabel }),
+    };
+    return (_jsx(ConsoleChrome, { value: false, children: _jsx(Layout, { ref: pairRef, height: "fill", start: _jsx(SidePanel, { side: "start", className: "theorem-console-request", labels: labels, resizable: requestPanel, open: true, children: _jsx(PanelScroll, { label: requestLabel, children: request }) }), content: _jsx(LayoutContent, { padding: 0, isScrollable: false, children: _jsx(PanelBody, { inset: "beside", className: "theorem-console-response", children: response }) }) }) }));
+}
+/** One card of a response with several: its request and result sit in it without cards of their own. */
+export function ConsoleSection({ children }) {
+    return (_jsx(Card, { variant: "muted", padding: 0, className: "theorem-console-card", style: CONSOLE_CARD, children: _jsx(ConsoleChrome, { value: false, children: children }) }));
+}
+/** The response. Beside the request it scrolls in the panel; a centred state fills the card, as an empty trace does. */
+export function ResponseColumn({ label, fill = false, children, }) {
+    const framed = use(ConsoleChrome);
+    if (!framed) {
+        return fill ? (children) : (_jsx(PanelScroll, { label: label, padding: 4, children: children }));
+    }
+    return (_jsx(Card, { variant: "muted", padding: fill ? 0 : 4, className: "theorem-console-card", style: CONSOLE_CARD, children: fill ? (children) : (_jsx(VStack, { height: "100%", gap: 3, children: children })) }));
 }
 /** ⌘/Ctrl+Enter runs the console's request. */
 function runShortcut(run) {
@@ -30,17 +112,35 @@ function runShortcut(run) {
 /** The request's card: its heading with the Fields/JSON switch, then the request and its run bar. */
 export function RequestCard({ title, view, hasFields, onView, onRun, children }) {
     const t = useLabels();
-    return (_jsx(Card, { variant: "muted", padding: 4, style: { background: 'var(--color-background-surface)' }, children: _jsxs(VStack, { gap: 3, onKeyDown: runShortcut(onRun), children: [_jsxs(HStack, { gap: 2, hAlign: "between", vAlign: "center", children: [_jsx(Text, { type: "supporting", color: "secondary", as: "h3", children: title }), _jsxs(SegmentedControl, { label: t('@theorem.decision.view'), size: "sm", value: view, onChange: (next) => {
-                                onView(next === 'json' ? 'json' : 'fields');
-                            }, children: [_jsx(SegmentedControlItem, { value: "fields", label: t('@theorem.decision.fields'), isDisabled: !hasFields }), _jsx(SegmentedControlItem, { value: "json", label: t('@theorem.data.json') })] })] }), children] }) }));
+    const framed = use(ConsoleChrome);
+    const body = (_jsxs(VStack, { gap: 3, padding: framed ? undefined : 4, onKeyDown: runShortcut(onRun), children: [_jsxs(HStack, { gap: 2, hAlign: "between", vAlign: "center", children: [_jsx(Text, { type: "supporting", color: "secondary", as: "h3", children: title }), _jsxs(SegmentedControl, { label: t('@theorem.decision.view'), size: "sm", value: view, onChange: (next) => {
+                            onView(next === 'json' ? 'json' : 'fields');
+                        }, children: [_jsx(SegmentedControlItem, { value: "fields", label: t('@theorem.decision.fields'), isDisabled: !hasFields }), _jsx(SegmentedControlItem, { value: "json", label: t('@theorem.data.json') })] })] }), children] }));
+    if (!framed)
+        return body;
+    return (_jsx(Card, { variant: "muted", padding: 4, className: "theorem-console-card", style: CONSOLE_CARD, children: body }));
 }
 /** The field reads as code: the body font is swapped for the code font inside it. */
 const CODE_FONT = { '--font-family-body': 'var(--font-family-code)' };
 /** The request as JSON text, marked while it doesn't parse. */
-export function JsonRequest({ label, text, isInvalid, onChange }) {
-    return (_jsx(TextArea, { label: label, isLabelHidden: true, value: text, onChange: onChange, rows: 8, hasSpellCheck: false, status: isInvalid ? { type: 'error' } : undefined, style: CODE_FONT }));
+export function JsonRequest({ label, text, isInvalid, onChange, }) {
+    return (_jsx(TextArea, { label: label, isLabelHidden: true, value: text, onChange: onChange, rows: textRows(text, 8, 24), hasSpellCheck: false, status: isInvalid ? { type: 'error' } : undefined, controlStyle: CODE_FONT }));
 }
 /** A note on the request, Stop while it runs, and Run. */
-export function RunBar({ note, isReady, isRunning, runLabel, runningLabel, stopLabel, onRun, onStop }) {
+export function RunBar({ note, isReady, isRunning, runLabel, runningLabel, stopLabel, onRun, onStop, }) {
     return (_jsxs(HStack, { gap: 3, hAlign: "between", vAlign: "center", children: [_jsx(Text, { type: "supporting", color: "secondary", style: isReady ? undefined : { color: 'var(--color-error)' }, hasTabularNumbers: true, children: note }), _jsxs(HStack, { gap: 2, vAlign: "center", children: [isRunning ? _jsx(Button, { label: stopLabel, variant: "ghost", onClick: onStop }) : null, _jsx(Button, { label: isRunning ? runningLabel : runLabel, variant: "primary", isLoading: isRunning, isDisabled: !isReady, onClick: onRun })] })] }));
 }
+/** A size in bytes as the reader's locale writes it: bytes under a kilobyte, else kilobytes. */
+export function useBytes() {
+    const locale = useLocale();
+    return useMemo(() => {
+        const b = new Intl.NumberFormat(locale, { style: 'unit', unit: 'byte', unitDisplay: 'narrow' });
+        const kb = new Intl.NumberFormat(locale, {
+            style: 'unit',
+            unit: 'kilobyte',
+            unitDisplay: 'narrow',
+            maximumFractionDigits: 1,
+        });
+        return (bytes) => (bytes < 1024 ? b.format(bytes) : kb.format(bytes / 1024));
+    }, [locale]);
+}