@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/EmbeddingSpace.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from '@astryxdesign/core/Text';
+import { useEffect, useRef, useState } from 'react';
+import { createSpaceRenderer } from "./embedding-space-gl.js";
+/** Times the GPU may drop the space before it is listed instead. */
+const LOSSES = 2;
+/** Pixels a press moves before it counts as turning the sphere, not pointing. */
+const DRAG_PX = 3;
+function isStill() {
+    return globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
+}
+function SpaceCanvas({ space, query, matches, hovered, onHover, nameOf, label, onUnavailable, onLost, }) {
+    const canvasRef = useRef(null);
+    const rendererRef = useRef(null);
+    const press = useRef(null);
+    const failed = useRef(onUnavailable);
+    failed.current = onUnavailable;
+    const lost = useRef(onLost);
+    lost.current = onLost;
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return;
+        try {
+            rendererRef.current = createSpaceRenderer(canvas, { still: isStill() });
+        }
+        catch {
+            failed.current();
+            return;
+        }
+        const onContextLost = (event) => {
+            event.preventDefault();
+            lost.current();
+        };
+        canvas.addEventListener('webglcontextlost', onContextLost);
+        return () => {
+            canvas.removeEventListener('webglcontextlost', onContextLost);
+            rendererRef.current?.destroy();
+            rendererRef.current = null;
+        };
+    }, []);
+    useEffect(() => {
+        rendererRef.current?.setSpace(space);
+    }, [space]);
+    useEffect(() => {
+        rendererRef.current?.setFocus({ query, matches, hovered });
+    }, [query, matches, hovered]);
+    const at = (event) => {
+        const box = event.currentTarget.getBoundingClientRect();
+        return { x: event.clientX - box.left, y: event.clientY - box.top };
+    };
+    return (_jsxs("div", { style: { position: 'relative', width: '100%', aspectRatio: '1 / 1', maxHeight: 460 }, children: [_jsx("canvas", { ref: canvasRef, role: "img", "aria-label": label, style: {
+                    display: 'block',
+                    width: '100%',
+                    height: '100%',
+                    cursor: hovered === null ? 'grab' : 'pointer',
+                    // why: a vertical swipe still scrolls the page; only a sideways one turns the sphere.
+                    touchAction: 'pan-y',
+                }, onPointerDown: (event) => {
+                    event.currentTarget.setPointerCapture(event.pointerId);
+                    press.current = { ...at(event), moved: false };
+                }, onPointerMove: (event) => {
+                    const point = at(event);
+                    const held = press.current;
+                    if (held) {
+                        const dx = point.x - held.x;
+                        const dy = point.y - held.y;
+                        if (!held.moved && Math.hypot(dx, dy) < DRAG_PX)
+                            return;
+                        held.moved = true;
+                        rendererRef.current?.drag(dx, dy);
+                        press.current = { ...point, moved: true };
+                        return;
+                    }
+                    onHover(rendererRef.current?.pick(point.x, point.y) ?? null);
+                }, onPointerUp: () => {
+                    press.current = null;
+                    rendererRef.current?.release();
+                }, onPointerCancel: () => {
+                    press.current = null;
+                    rendererRef.current?.release();
+                }, onPointerLeave: () => {
+                    if (!press.current)
+                        onHover(null);
+                } }), hovered !== null ? (_jsx("div", { style: { position: 'absolute', left: 0, right: 0, bottom: 0, pointerEvents: 'none' }, children: _jsx(Text, { type: "supporting", maxLines: 1, children: nameOf(hovered) }) })) : null] }));
+}
+/**
+ * The index drawn as a space: each document a dot in a ball, placed by the
+ * three directions the vectors differ most along, with a circle round the rim
+ * in each plane two of them span. Each document is joined to its nearest
+ * neighbour by cosine similarity when that pair stands out from the index's
+ * typical pair; documents the lines connect share a colour, and a query's
+ * white dot has a line to each match that stands out the same way. Drag to turn
+ * it; point at a dot to name its document.
+ */
+export function EmbeddingSpaceView(props) {
+    // why: a lost GPU context does not come back on the same canvas; a new one asks again.
+    const [generation, setGeneration] = useState(0);
+    const onLost = () => {
+        if (generation >= LOSSES)
+            props.onUnavailable();
+        else
+            setGeneration(generation + 1);
+    };
+    return _jsx(SpaceCanvas, { ...props, onLost: onLost }, generation);
+}

package/ui/LiveCaptionsPanel.d.ts

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react';
+import { type LiveCaptionState, type LiveCaptionTurn } from '../client/live/live-captions.ts';
+export type LiveCaptionsPanelProps = {
+    /** Profile handle. The transcript shows it as the agent's name. */
+    handle: string;
+    captions: LiveCaptionState;
+    pastCalls: readonly (readonly LiveCaptionTurn[])[];
+    draftText: string;
+    onDraftTextChange: (text: string) => void;
+    onSubmit: (text: string) => void;
+    /** Off while no call is connected. */
+    isDisabled: boolean;
+    /** Omit the text field when the profile takes no text. */
+    showComposer?: boolean;
+    /** Drawn above the transcript. The live runner puts the camera here. */
+    leading?: ReactNode;
+};
+/**
+ * The live call's captions: the chat transcript, an empty state, and the text
+ * composer. The same panel the live runner docks on the right.
+ */
+export declare function LiveCaptionsPanel(props: LiveCaptionsPanelProps): import("react").JSX.Element;

package/ui/LiveCaptionsPanel.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { EmptyState } from '@astryxdesign/core/EmptyState';
+import { Icon } from '@astryxdesign/core/Icon';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconSubtitles } from '@tabler/icons-react';
+import { liveCaptionStreaming, liveCaptionTranscript, } from "../client/live/live-captions.js";
+import { ChatComposerBar } from "./ChatComposerBar.js";
+import { ChatTranscript } from "./ChatTranscript.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { PanelScroll } from "./SidePanel.js";
+/**
+ * The live call's captions: the chat transcript, an empty state, and the text
+ * composer. The same panel the live runner docks on the right.
+ */
+export function LiveCaptionsPanel(props) {
+    return (_jsx(TheoremLabelsProvider, { children: _jsx(LiveCaptionsBody, { ...props }) }));
+}
+function LiveCaptionsBody({ handle, captions, pastCalls, draftText, onDraftTextChange, onSubmit, isDisabled, showComposer = true, leading, }) {
+    const t = useLabels();
+    const agentName = t('@theorem.agent.handle', { handle });
+    const { blocks, callStarts } = liveCaptionTranscript(pastCalls, captions);
+    const newSession = t('@theorem.live.new_session');
+    const dividers = Object.fromEntries(callStarts.map((id) => [id, newSession]));
+    const composer = showComposer ? (_jsx(ChatComposerBar, { handle: handle, draftText: draftText, onDraftTextChange: onDraftTextChange, onSubmit: onSubmit, isDisabled: isDisabled })) : null;
+    return (_jsxs(VStack, { height: "100%", children: [leading, _jsx(StackItem, { size: "fill", children: blocks.length > 0 ? (_jsx(PanelScroll, { label: t('@theorem.panel.captions.name'), children: _jsx(ChatTranscript, { blocks: blocks, dividers: dividers, handle: agentName, streaming: liveCaptionStreaming(captions) }) })) : (_jsx(VStack, { height: "100%", vAlign: "center", padding: 4, children: _jsx(EmptyState, { icon: _jsx(Icon, { icon: IconSubtitles, size: "lg", color: "secondary" }), title: t('@theorem.panel.captions.empty.title'), description: t('@theorem.panel.captions.empty.description'), isCompact: true }) })) }), composer] }));
+}

package/ui/LiveRunner.d.ts

@@ -0,0 +1,30 @@
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import type { LiveProfileInterface } from '@theoremjs/agents/interface';
+import type { LiveCallOptions } from '../client/live/live-page-tool.ts';
+import type { LiveConnection } from '../client/live-client.ts';
+import { type TheoremLabels } from './labels.ts';
+export type LiveRunnerProps = {
+    iface: LiveProfileInterface;
+    /** What the call opens: a profile the host registered, or an open message for the relay. */
+    connection: () => LiveConnection | Promise<LiveConnection>;
+    /** Astryx theme, as on `TheoremChat`. Omit to inherit the host's `<Theme>` or use `theoremTheme`. */
+    theme?: DefinedTheme;
+    mode?: 'system' | 'light' | 'dark';
+    /** Replacement lines by locale, as on `TheoremChat`. */
+    labels?: TheoremLabels;
+    /**
+     * Drive the trace from the host's own control. The built-in toggle hides.
+     * The open trace takes the call'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;
+} & LiveCallOptions;
+/**
+ * Live (voice / video) runner on Astryx. Before a call: a landing like the
+ * chat's, offering a voice or video call. In a call: the agent tag and state
+ * over the ink waveform, captions in a right-hand chat column, call controls
+ * in a toolbar, and tool gates in a dialog. Offers the trace inspector when
+ * the profile records traces.
+ */
+export declare function LiveRunner({ theme, mode, labels, ...props }: LiveRunnerProps): import("react").JSX.Element;

package/ui/LiveRunner.js

@@ -0,0 +1,180 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { AspectRatio } from '@astryxdesign/core/AspectRatio';
+import { Banner } from '@astryxdesign/core/Banner';
+import { Button } from '@astryxdesign/core/Button';
+import { Center } from '@astryxdesign/core/Center';
+import { Dialog } from '@astryxdesign/core/Dialog';
+import { HStack } from '@astryxdesign/core/HStack';
+import { Icon } from '@astryxdesign/core/Icon';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Text } from '@astryxdesign/core/Text';
+import { ToggleButton } from '@astryxdesign/core/ToggleButton';
+import { Toolbar } from '@astryxdesign/core/Toolbar';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconCameraRotate, IconMessage, IconMicrophone, IconMicrophoneOff, IconPhone, IconPhoneOff, IconVideo, IconVideoOff, } from '@tabler/icons-react';
+import { Fragment, useEffect, useLayoutEffect, useRef, } from 'react';
+import { InkWaveform } from "../components/InkWaveform.js";
+import { useLiveRunnerModel } from "../components/live/use-live-runner-model.js";
+import { LiveCaptionsPanel } from "./LiveCaptionsPanel.js";
+import { liveStateLabel } from "./labels.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { PANEL_BOTTOM, PANEL_EDGE, SidePanel, SidePanelHeader, SidePanelToggle, useSidePanel, } from "./SidePanel.js";
+import { DEFAULT_CHAT_MAX_WIDTH } from "./TheoremChat.js";
+import { ApprovalCard, AuthChallengeCard, GATE_CARD_WIDTH } from "./ToolGateCard.js";
+import { useTraceInspector, WithTrace } from "./TraceInspectorPanel.js";
+import { TheoremThemeProvider } from "./theme.js";
+/** The waveform's box: it rests on the stage floor rather than filling the stage. */
+const WAVE_MAX_WIDTH = 720;
+const WAVE_HEIGHT = 320;
+/**
+ * Live (voice / video) runner on Astryx. Before a call: a landing like the
+ * chat's, offering a voice or video call. In a call: the agent tag and state
+ * over the ink waveform, captions in a right-hand chat column, call controls
+ * in a toolbar, and tool gates in a dialog. Offers the trace inspector when
+ * the profile records traces.
+ */
+export function LiveRunner({ theme, mode, labels, ...props }) {
+    return (_jsx(TheoremThemeProvider, { theme: theme, mode: mode, children: _jsx(TheoremLabelsProvider, { labels: labels, children: _jsx(LiveRunnerBody, { ...props }) }) }));
+}
+function LiveRunnerBody({ iface, connection, trace, slots, context, pageTools, }) {
+    const t = useLabels();
+    const model = useLiveRunnerModel(iface, connection, { slots, context, pageTools });
+    // why: Both panels size against the whole live layout, so a third means the same for each.
+    const layoutRef = useRef(null);
+    const inspector = useTraceInspector(iface, model.traces, trace);
+    const captions = useSidePanel(layoutRef, true);
+    const captionLabels = {
+        name: t('@theorem.panel.captions.name'),
+        show: t('@theorem.panel.captions.show'),
+        hide: t('@theorem.panel.captions.hide'),
+        resize: t('@theorem.panel.captions.resize'),
+    };
+    const captionsToggle = (_jsx(SidePanelToggle, { labels: captionLabels, icon: _jsx(Icon, { icon: IconMessage }), panelId: captions.id, open: captions.open, onToggle: captions.toggle }));
+    if (!model.callStarted) {
+        return (_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { ref: layoutRef, height: "fill", header: _jsx(SidePanelHeader, { children: inspector.toggle }), content: _jsx(LayoutContent, { padding: 0, children: _jsx(LiveLanding, { model: model }) }) }) }));
+    }
+    return (_jsxs(_Fragment, { children: [_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { ref: layoutRef, height: "fill", header: _jsx(SidePanelHeader, { children: inspector.toggle }), content: _jsx(LayoutContent, { padding: 0, children: _jsx(Layout, { height: "fill", end: _jsx(SidePanel, { id: captions.id, labels: captionLabels, resizable: captions.resizable, open: captions.open, children: _jsx(LiveCaptions, { model: model }) }), content: _jsx(LayoutContent, { padding: 0, children: _jsx(VStack, { height: "100%", paddingInline: PANEL_EDGE, paddingBlockEnd: PANEL_BOTTOM, children: _jsx(LiveStage, { model: model, captionsToggle: captionsToggle }) }) }) }) }) }) }), _jsx(LiveToolGateDialog, { prompt: model.gatePrompt, agent: t('@theorem.agent.handle', { handle: model.handle }), onResolve: model.resolveGateDecision })] }));
+}
+/**
+ * Before a call: the chat landing's greeting, with call buttons where the
+ * composer would be. Video starts camera and mic together.
+ */
+function LiveLanding({ model }) {
+    const t = useLabels();
+    return (_jsx(VStack, { minHeight: "100%", vAlign: "center", gap: 8, paddingInline: 3, children: _jsx(Center, { axis: "horizontal", width: "100%", children: _jsxs(VStack, { width: "100%", maxWidth: DEFAULT_CHAT_MAX_WIDTH, gap: 8, children: [_jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "large", as: "h2", children: t('@theorem.agent.handle', { handle: model.handle }) }), _jsx(Text, { type: "display-2", as: "h1", children: t('@theorem.live.greeting') })] }), _jsxs(HStack, { gap: 2, wrap: "wrap", children: [_jsx(Button, { label: t(model.voiceAvailable
+                                    ? '@theorem.live.start_voice_call'
+                                    : '@theorem.live.start_call'), variant: "primary", icon: _jsx(Icon, { icon: IconPhone }), onClick: () => model.startCall({ video: false }) }), model.videoAvailable ? (_jsx(Button, { label: t('@theorem.live.start_video_call'), variant: "secondary", icon: _jsx(Icon, { icon: IconVideo }), onClick: () => model.startCall({ video: true }) })) : null] })] }) }) }));
+}
+/**
+ * The agent tag and state over the resting waveform, then the call controls,
+ * all in one column the waveform's width.
+ */
+function LiveStage({ model, captionsToggle }) {
+    const t = useLabels();
+    const ref = useEnterMotion();
+    return (_jsx(VStack, { ref: ref, height: "100%", hAlign: "center", children: _jsxs(VStack, { width: "100%", maxWidth: WAVE_MAX_WIDTH, height: "100%", gap: 3, children: [_jsxs(VStack, { gap: 0.5, children: [_jsx(Text, { type: "label", color: "secondary", children: t('@theorem.agent.handle', { handle: model.handle }) }), _jsx(Text, { size: "sm", color: "secondary", children: liveStateLabel(t, model.liveState, model.activeTool) })] }), model.failure ? _jsx(Banner, { status: "error", role: "alert", title: model.failure.error }) : null, model.sessionEnded ? (_jsx(Banner, { status: "info", role: "status", title: model.sessionEnded })) : null, _jsx(StackItem, { size: "fill", children: _jsx(VStack, { height: "100%", vAlign: "end", children: _jsx(VStack, { width: "100%", height: WAVE_HEIGHT, style: { color: 'var(--color-icon-primary)' }, "aria-hidden": "true", children: _jsx(InkWaveform, { status: model.status, levelsRef: model.levelsRef, toolActive: model.toolActive, variant: "hero" }) }) }) }), _jsx(LiveControls, { model: model, captionsToggle: captionsToggle })] }) }));
+}
+/**
+ * Eases the call view in from the landing: Astryx has no enter-transition
+ * helper, so this animates with its `--duration-medium` / `--ease-standard`.
+ */
+function useEnterMotion() {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el || globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches)
+            return;
+        const tokens = getComputedStyle(el);
+        const duration = Number.parseFloat(tokens.getPropertyValue('--duration-medium')) || 410;
+        el.animate([
+            { opacity: 0, transform: 'translateY(8px)' },
+            { opacity: 1, transform: 'none' },
+        ], { duration, easing: tokens.getPropertyValue('--ease-standard').trim() || 'ease-out' });
+    }, []);
+    return ref;
+}
+/**
+ * Mic, camera, captions, and call controls, centred under the stage. Icons show
+ * what a click does, as End call does: a slash means "turn this off".
+ */
+function LiveControls({ model, captionsToggle }) {
+    const t = useLabels();
+    const inactive = !model.sessionActive;
+    const controls = [];
+    if (model.voiceAvailable) {
+        controls.push(_jsx(ToggleButton, { label: t('@theorem.live.microphone'), tooltip: t(model.isMuted ? '@theorem.live.unmute' : '@theorem.live.mute'), isIconOnly: true, isPressed: !model.isMuted, isDisabled: inactive, icon: _jsx(Icon, { icon: IconMicrophone }), pressedIcon: _jsx(Icon, { icon: IconMicrophoneOff }), onPressedChange: model.handleToggleMic }, "mic"));
+    }
+    if (model.videoAvailable) {
+        controls.push(_jsx(ToggleButton, { label: t('@theorem.live.camera'), tooltip: t(model.isVideoOn ? '@theorem.live.camera_off' : '@theorem.live.camera_on'), isIconOnly: true, isPressed: model.isVideoOn, isDisabled: inactive, icon: _jsx(Icon, { icon: IconVideo }), pressedIcon: _jsx(Icon, { icon: IconVideoOff }), onPressedChange: () => {
+                void model.handleToggleVideo();
+            } }, "video"));
+        if (model.isVideoOn) {
+            controls.push(_jsx(IconButton, { label: t('@theorem.live.flip_camera'), tooltip: t('@theorem.live.flip_camera'), variant: "ghost", isDisabled: inactive, icon: _jsx(Icon, { icon: IconCameraRotate }), onClick: () => {
+                    void model.handleFlipCamera();
+                } }, "flip"));
+        }
+    }
+    controls.push(_jsx(Fragment, { children: captionsToggle }, "captions"), model.canRestart ? (_jsx(IconButton, { label: t('@theorem.live.start_call'), tooltip: t('@theorem.live.start_call'), variant: "primary", icon: _jsx(Icon, { icon: IconPhone }), onClick: () => {
+            void model.handleRestart();
+        } }, "call")) : (_jsx(IconButton, { label: t('@theorem.live.end_call'), tooltip: t('@theorem.live.end_call'), variant: "destructive", isDisabled: inactive, icon: _jsx(Icon, { icon: IconPhoneOff }), onClick: model.handleEnd }, "call")));
+    return (_jsx(Toolbar, { label: t('@theorem.live.controls'), dividers: ['top'], centerContent: _jsx(HStack, { gap: 2, vAlign: "center", children: controls }) }));
+}
+/**
+ * Captions drawn by the chat's own transcript, with the text composer in its
+ * dock when the profile takes text.
+ */
+function LiveCaptions({ model }) {
+    return (_jsx(LiveCaptionsPanel, { handle: model.handle, captions: model.captions, pastCalls: model.pastCalls, draftText: model.textDraft, onDraftTextChange: model.setTextDraft, onSubmit: model.handleSendText, isDisabled: !model.sessionActive, showComposer: model.textAvailable, leading: model.videoPreview ? (_jsx(LiveVideoPreview, { video: model.videoPreview, facingMode: model.videoFacingMode })) : null }));
+}
+/**
+ * The camera preview, at the top of the captions panel. The capture element comes
+ * from the session client, so it is mounted imperatively; it sits one level
+ * below AspectRatio, so it carries its own fill and mirror styles.
+ */
+function LiveVideoPreview({ video, facingMode, }) {
+    const t = useLabels();
+    const hostRef = useRef(null);
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host)
+            return;
+        Object.assign(video.style, {
+            width: '100%',
+            height: '100%',
+            objectFit: 'cover',
+            display: 'block',
+        });
+        host.replaceChildren(video);
+        return () => {
+            if (video.parentElement === host)
+                host.removeChild(video);
+        };
+    }, [video]);
+    useEffect(() => {
+        video.style.transform = facingMode === 'user' ? 'scaleX(-1)' : '';
+    }, [video, facingMode]);
+    return (_jsx(AspectRatio, { ratio: 4 / 3, fit: "cover", children: _jsx("div", { ref: hostRef, "aria-label": t('@theorem.live.camera_preview'), role: "img" }) }));
+}
+/** Room around the gate card for its shadow. */
+const GATE_DIALOG_PADDING = 4;
+const GATE_DIALOG_WIDTH = GATE_CARD_WIDTH + 2 * GATE_DIALOG_PADDING * 4;
+/** The dialog draws no surface of its own: the card is the one chat shows, alone. */
+const GATE_DIALOG_BARE = { background: 'transparent', boxShadow: 'none' };
+/**
+ * Tool approvals and credential prompts, as a dialog that must be answered. It shows the card
+ * chat shows inline and nothing else, and closes on the answer.
+ */
+function LiveToolGateDialog({ prompt, agent, onResolve, }) {
+    return (_jsx(Dialog, { isOpen: prompt !== null, purpose: "required", width: GATE_DIALOG_WIDTH, padding: GATE_DIALOG_PADDING, style: GATE_DIALOG_BARE, 
+        // why: "required" disables dismissal; should one slip through, it denies.
+        onOpenChange: (open) => {
+            if (!open)
+                onResolve({ action: 'deny' });
+        }, children: prompt ? (prompt.gate.kind === 'auth' ? (_jsx(AuthChallengeCard, { gate: prompt.gate, toolName: prompt.gate.tool, onAuthenticated: (secret) => {
+                onResolve({ action: 'auth', secret });
+            } })) : (_jsx(ApprovalCard, { gate: prompt.gate, toolName: prompt.gate.tool, agent: agent, input: prompt.input, onDecision: (action) => {
+                onResolve({ action });
+            } }))) : null }));
+}

package/ui/PaneState.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from 'react';
+/**
+ * What a pane says when it has nothing of its own to show: centred both ways
+ * in the room it is given. Loading, a failure, and an empty pane are this one
+ * component, so they sit in the same place.
+ */
+export declare function PaneState({ icon, title, description, actions, children, }: {
+    /** Every pane state has one: it is what the eye finds first. */
+    icon: ReactNode;
+    title: string;
+    description?: string;
+    /** The buttons that lead out of the state. */
+    actions?: ReactNode;
+    /** What goes under the words: the detail of a failure, or the way out of it. */
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A pane that is waiting: the spinner where an empty pane's icon would be,
+ * once the wait has gone on a moment; blank and busy before then. Given when
+ * the work began, it counts the seconds under the label.
+ */
+export declare function PaneLoading({ label, since }: {
+    label: string;
+    since?: number | null;
+}): import("react").JSX.Element;
+/** A pane that could not show what it is for, and why. */
+export declare function PaneFailure({ title, description, actions, children, }: {
+    title: string;
+    description?: string;
+    /** The buttons that lead out of the failure. */
+    actions?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;

package/ui/PaneState.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { EmptyState } from '@astryxdesign/core/EmptyState';
+import { Icon } from '@astryxdesign/core/Icon';
+import { Spinner } from '@astryxdesign/core/Spinner';
+import { VStack } from '@astryxdesign/core/VStack';
+import { IconAlertTriangle } from '@tabler/icons-react';
+import { useEffect, useState } from 'react';
+import { useSecondTicker } from "../hooks/use-second-ticker.js";
+import { liveDuration } from "./labels.js";
+import { useLabels } from "./labels-provider.js";
+/**
+ * What a pane says when it has nothing of its own to show: centred both ways
+ * in the room it is given. Loading, a failure, and an empty pane are this one
+ * component, so they sit in the same place.
+ */
+export function PaneState({ icon, title, description, actions, children, }) {
+    return (_jsxs(VStack, { height: "100%", vAlign: "center", hAlign: "center", gap: 3, padding: 4, children: [_jsx(EmptyState, { icon: icon, title: title, description: description, actions: actions, isCompact: true }), children] }));
+}
+/**
+ * A pane that is waiting: the spinner where an empty pane's icon would be,
+ * once the wait has gone on a moment; blank and busy before then. Given when
+ * the work began, it counts the seconds under the label.
+ */
+export function PaneLoading({ label, since }) {
+    const t = useLabels();
+    const now = useSecondTicker(since != null);
+    const long = useLongWait();
+    if (!long)
+        return _jsx("div", { "aria-busy": "true", style: { height: '100%' } });
+    return (_jsx(PaneState, { icon: _jsx(Spinner, { size: "lg" }), title: label, description: since == null ? undefined : liveDuration(t, now - since) }));
+}
+/**
+ * How long a wait stays blank before its spinner shows. Most waits (a profile
+ * describing itself, a switch to another agent) end sooner, and the pane
+ * changes straight to what it waited for instead of flashing a spinner.
+ */
+const QUIET_WAIT_MS = 300;
+/** Whether a wait has gone on long enough to say so. */
+function useLongWait() {
+    const [long, setLong] = useState(false);
+    useEffect(() => {
+        const timer = globalThis.setTimeout(() => setLong(true), QUIET_WAIT_MS);
+        return () => globalThis.clearTimeout(timer);
+    }, []);
+    return long;
+}
+/** A pane that could not show what it is for, and why. */
+export function PaneFailure({ title, description, actions, children, }) {
+    return (_jsx(PaneState, { icon: _jsx(Icon, { icon: IconAlertTriangle, size: "lg", color: "secondary" }), title: title, description: description, actions: actions, children: children }));
+}

package/ui/SchemaFields.d.ts

@@ -0,0 +1,10 @@
+import { type JsonSchema } from '../client/schema-fields.ts';
+import { type Edit as StateEdit } from './StateFields.tsx';
+/**
+ * A tool's request as a form drawn from its input schema: each field the
+ * input its type asks for, labelled by its title or key and described by its
+ * description. Optional fields left empty aren't sent.
+ */
+export declare function SchemaFields({ schema, value, onChange, }: StateEdit<Record<string, unknown>> & {
+    schema: JsonSchema;
+}): import("react").JSX.Element;

package/ui/SchemaFields.js

@@ -0,0 +1,150 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { CheckboxList, CheckboxListItem } from '@astryxdesign/core/CheckboxList';
+import { DateInput } from '@astryxdesign/core/DateInput';
+import { Grid } from '@astryxdesign/core/Grid';
+import { HStack } from '@astryxdesign/core/HStack';
+import { NumberInput } from '@astryxdesign/core/NumberInput';
+import { SegmentedControl, SegmentedControlItem } from '@astryxdesign/core/SegmentedControl';
+import { Selector } from '@astryxdesign/core/Selector';
+import { Slider } from '@astryxdesign/core/Slider';
+import { StackItem } from '@astryxdesign/core/Stack';
+import { Switch } from '@astryxdesign/core/Switch';
+import { Text } from '@astryxdesign/core/Text';
+import { TextArea } from '@astryxdesign/core/TextArea';
+import { TextInput } from '@astryxdesign/core/TextInput';
+import { Tokenizer } from '@astryxdesign/core/Tokenizer';
+import { VStack } from '@astryxdesign/core/VStack';
+import { useState } from 'react';
+import { blankRow, schemaFields, withField, } from "../client/schema-fields.js";
+import { isRow, json } from "../client/shaped-data.js";
+import { useLabels } from "./labels-provider.js";
+import { useKeyedRows } from "./row-keys.js";
+import { AddRow, Group, Labelled, RemoveRow } from "./StateFields.js";
+const NO_SUGGESTIONS = { search: () => [], bootstrap: () => [] };
+const CODE_FONT = { '--font-family-body': 'var(--font-family-code)' };
+/** Lines a description shows before it is cut short. */
+const DESCRIPTION_LINES = 2;
+/** What a field is for, cut to a couple of lines. Hovering a cut one shows all of it. */
+function Description({ text }) {
+    return (_jsx(Text, { type: "supporting", color: "secondary", maxLines: DESCRIPTION_LINES, children: text }));
+}
+/** A field whose input carries no label of its own, labelled as one. */
+function Described({ field, children }) {
+    return (_jsx(Labelled, { label: field.label, isRequired: field.isRequired, children: children }));
+}
+/** A field the schema doesn't shape (no type, a union, a free object), as its JSON. */
+function JsonField({ field, value, onChange }) {
+    const t = useLabels();
+    const [text, setText] = useState(() => (value === undefined ? '' : json(value)));
+    const [isValid, setValid] = useState(true);
+    return (_jsx(TextArea, { label: field.label, isRequired: field.isRequired, size: "sm", rows: 3, value: text, hasSpellCheck: false, status: isValid ? undefined : { type: 'error', message: t('@theorem.decision.invalid_json') }, controlStyle: CODE_FONT, onChange: (next) => {
+            setText(next);
+            if (next.trim() === '') {
+                setValid(true);
+                onChange(undefined);
+                return;
+            }
+            try {
+                onChange(JSON.parse(next));
+                setValid(true);
+            }
+            catch {
+                setValid(false);
+            }
+        } }));
+}
+/** A list of objects: each row its own fields, removable, and one more at the end. */
+function RowsField({ field, item, value, onChange, }) {
+    const rows = Array.isArray(value) ? value : [];
+    const keyed = useKeyedRows(rows);
+    return (_jsx(Group, { label: field.label, isRequired: field.isRequired, description: field.description && _jsx(Description, { text: field.description }), children: _jsxs(VStack, { gap: 3, children: [keyed.rows.map(({ item: row, index, key }) => (_jsxs(HStack, { gap: 2, vAlign: "start", children: [_jsx(StackItem, { size: "fill", children: _jsx(ObjectFields, { schema: item, value: isRow(row) ? row : {}, onChange: (next) => onChange(rows.map((old, at) => (at === index ? next : old))) }) }), _jsx(RemoveRow, { index: index, onRemove: () => {
+                                keyed.drop(index);
+                                onChange(rows.filter((_, at) => at !== index));
+                            } })] }, key))), _jsx(AddRow, { field: field.label, onAdd: () => onChange([...rows, blankRow(item)]) })] }) }));
+}
+function common(field) {
+    return {
+        label: field.label,
+        isRequired: field.isRequired,
+        size: 'sm',
+    };
+}
+/** One of a few options as segments; more as a menu. */
+function ChoiceField({ field, options, isMenu, value, onChange, }) {
+    if (isMenu) {
+        return (_jsx(Selector, { ...common(field), options: options, value: typeof value === 'string' ? value : undefined, hasSearch: options.length > 10, onChange: onChange }));
+    }
+    return (_jsx(Described, { field: field, children: _jsx(HStack, { children: _jsx(SegmentedControl, { label: field.label, size: "sm", value: typeof value === 'string' ? value : '', onChange: onChange, children: options.map((option) => (_jsx(SegmentedControlItem, { value: option, label: option }, option))) }) }) }));
+}
+function TextField({ field, isLong, type, value, onChange, }) {
+    const text = typeof value === 'string' ? value : '';
+    return isLong ? (_jsx(TextArea, { ...common(field), rows: 3, value: text, onChange: onChange })) : (_jsx(TextInput, { ...common(field), type: type, value: text, onChange: onChange }));
+}
+/** A list of words or numbers as tokens. */
+function WordsField({ field, value, onChange }) {
+    const t = useLabels();
+    const words = Array.isArray(value) ? value : [];
+    return (_jsx(Tokenizer, { ...common(field), value: words.map((word, index) => ({
+            id: `${String(index)}:${String(word)}`,
+            label: String(word),
+        })), searchSource: NO_SUGGESTIONS, hasCreate: true, debounceMs: 0, placeholder: t('@theorem.decision.add_value'), onChange: (items) => onChange(items.map((item) => typeof words[0] === 'number' && Number.isFinite(Number(item.label))
+            ? Number(item.label)
+            : item.label)) }));
+}
+/** Each control's input, as the schema asks for it. */
+const CONTROLS = {
+    choice: ({ field, control, value, onChange }) => (_jsx(ChoiceField, { field: field, options: control.options, isMenu: control.isMenu, value: value, onChange: onChange })),
+    range: ({ field, control, value, onChange }) => (_jsx(Slider, { label: field.label, isRequired: field.isRequired, min: control.min, max: control.max, step: 1, value: typeof value === 'number' ? value : control.min, valueDisplay: "text", onChange: onChange })),
+    number: ({ field, control, value, onChange }) => (_jsx(NumberInput, { ...common(field), value: typeof value === 'number' ? value : undefined, min: control.min, max: control.max, isIntegerOnly: control.isInteger, isWheelEnabled: false, onChange: (next) => onChange(next ?? undefined) })),
+    switch: ({ field, value, onChange }) => (_jsx(Switch, { label: field.label, value: value === true, onChange: onChange })),
+    date: ({ field, value, onChange }) => (_jsx(DateInput, { ...common(field), value: typeof value === 'string' ? value : undefined, onChange: onChange })),
+    text: ({ field, control, value, onChange }) => (_jsx(TextField, { field: field, isLong: control.isLong, type: control.type, value: value, onChange: onChange })),
+    choices: ({ field, control, value, onChange }) => (_jsx(CheckboxList, { label: field.label, value: Array.isArray(value)
+            ? value.filter((entry) => typeof entry === 'string')
+            : [], onChange: onChange, children: control.options.map((option) => (_jsx(CheckboxListItem, { label: option, value: option }, option))) })),
+    words: ({ field, value, onChange }) => (_jsx(WordsField, { field: field, value: value, onChange: onChange })),
+    rows: ({ field, control, value, onChange }) => (_jsx(RowsField, { field: field, item: control.item, value: value, onChange: onChange })),
+    group: ({ field, control, value, onChange }) => (_jsx(Group, { label: field.label, isRequired: field.isRequired, description: field.description && _jsx(Description, { text: field.description }), children: _jsx(ObjectFields, { schema: control.schema, value: isRow(value) ? value : {}, onChange: onChange }) })),
+    json: ({ field, value, onChange }) => (_jsx(JsonField, { field: field, value: value, onChange: onChange })),
+};
+function Field({ field, value, onChange }) {
+    const control = CONTROLS[field.control.kind];
+    const input = control({ field, control: field.control, value, onChange });
+    // why: A group already says its description under its name.
+    const isGroup = field.control.kind === 'rows' || field.control.kind === 'group';
+    if (!field.description || isGroup)
+        return input;
+    return (_jsxs(VStack, { gap: 1, children: [input, _jsx(Description, { text: field.description })] }));
+}
+/** Room a short field takes: numbers, dates, menus, and one-line text sit side by side. */
+const SHORT_FIELD_PX = 200;
+/** Segments whose labels run this long in all still fit a short field's width. */
+const SHORT_SEGMENT_CHARS = 18;
+/** A field that reads in a column's width; the rest take the whole row. */
+function isShort({ control }) {
+    switch (control.kind) {
+        case 'number':
+        case 'switch':
+        case 'date':
+            return true;
+        case 'choice':
+            return control.isMenu || control.options.join('').length <= SHORT_SEGMENT_CHARS;
+        case 'text':
+            return !control.isLong;
+        default:
+            return false;
+    }
+}
+function ObjectFields({ schema, value, onChange, }) {
+    return (_jsx(Grid, { columns: { minWidth: SHORT_FIELD_PX, repeat: 'fill' }, gap: 3, children: schemaFields(schema).map((field) => (_jsx("div", { style: isShort(field)
+                ? { minWidth: 0, alignSelf: 'start' }
+                : { gridColumn: '1 / -1', minWidth: 0 }, children: _jsx(Field, { field: field, value: value[field.key], onChange: (next) => onChange(withField(value, field.key, next)) }) }, field.key))) }));
+}
+/**
+ * A tool's request as a form drawn from its input schema: each field the
+ * input its type asks for, labelled by its title or key and described by its
+ * description. Optional fields left empty aren't sent.
+ */
+export function SchemaFields({ schema, value, onChange, }) {
+    return _jsx(ObjectFields, { schema: schema, value: value, onChange: onChange });
+}

package/ui/ShapedData.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+export type ShapedDataProps = {
+    value: unknown;
+    title?: string;
+    /** Drawn above the data in its data view (a tool result's figures and charts); a render that throws falls back to the JSON with it. */
+    lead?: ReactNode;
+    /** Top-level fields the lead already shows: the data view leaves them out, the JSON keeps them. */
+    ledKeys?: readonly string[];
+};
+/** A tool call's input, output or failure, or a structured reply, with a switch to its JSON. */
+export declare function ShapedData({ value: raw, title, lead, ledKeys }: ShapedDataProps): import("react").JSX.Element;