@theoremjs/react 0.0.0-stage → 0.3.0

package/ui/SidePanel.d.ts

@@ -0,0 +1,57 @@
+import { type ResizableRegion } from '@astryxdesign/core/Resizable';
+import { type ReactNode, type RefObject } from 'react';
+/** Whether a side panel is wide enough for two readable columns: twice its minimum. */
+export declare function isSidePanelWide(size: number): boolean;
+/** A side panel's open state and size. `containerRef` is the Layout its percentages resolve against. */
+export declare function useSidePanel(containerRef: RefObject<HTMLDivElement | null>, initiallyOpen: boolean): {
+    id: string;
+    open: boolean;
+    toggle: () => void;
+    resizable: ResizableRegion;
+};
+/** The Layout header row: side panel toggles, at the end. */
+export declare function SidePanelHeader({ children }: {
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/** A side panel's words: its name, and its toggle and drag handle actions. */
+export type SidePanelLabels = {
+    name: string;
+    show: string;
+    hide: string;
+    resize: string;
+};
+/** Shows or hides one side panel (`panelId` from useSidePanel). */
+export declare function SidePanelToggle({ labels, icon, panelId, open, onToggle, }: {
+    labels: SidePanelLabels;
+    icon: ReactNode;
+    panelId: string;
+    open: boolean;
+    onToggle: () => void;
+}): import("react").JSX.Element;
+export type SidePanelProps = {
+    id?: string;
+    labels: SidePanelLabels;
+    /** From `useResizable`: the panel's width and its handle's drag state. */
+    resizable: ResizableRegion;
+    /**
+     * Closed panels stay mounted at zero width and inert, so the theme can ease
+     * their width; their content renders only while open, so it never reflows
+     * into the collapsing width.
+     */
+    open?: boolean;
+    /** Card padding; 0 for content that brings its own (e.g. ChatLayout). */
+    padding?: 0;
+    children?: ReactNode;
+};
+/** Page corners like the host's raised panels, no border or shadow; the card fill, so surface-filled cards read on it. */
+export declare const RAISED: {
+    background: string;
+    borderRadius: string;
+};
+/**
+ * A Layout `end` panel as Astryx's IDE template builds one (a reversed
+ * `ResizeHandle` before a `LayoutPanel` sized by `useResizable`), holding a
+ * raised section inset from the layout edge and bottom instead of a flat pane.
+ * For more than one panel, nest Layouts, one panel each, as the template does.
+ */
+export declare function SidePanel({ id, labels, resizable, open, padding, children }: SidePanelProps): import("react").JSX.Element;

package/ui/SidePanel.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card } from '@astryxdesign/core/Card';
+import { HStack } from '@astryxdesign/core/HStack';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { LayoutHeader, LayoutPanel } from '@astryxdesign/core/Layout';
+import { ResizeHandle, useResizable, } from '@astryxdesign/core/Resizable';
+import { VStack } from '@astryxdesign/core/VStack';
+import { useCallback, useId, useState } from 'react';
+/**
+ * `useResizable` sizing for side panels: a third of the layout (pass the
+ * Layout as `containerRef` so the percentages resolve), dragged between a
+ * readable minimum and half.
+ */
+const SIDE_PANEL_SIZING = {
+    defaultSize: '33%',
+    minSize: 280,
+    maxSize: '50%',
+};
+/** Whether a side panel is wide enough for two readable columns: twice its minimum. */
+export function isSidePanelWide(size) {
+    return size >= SIDE_PANEL_SIZING.minSize * 2;
+}
+/** A side panel's open state and size. `containerRef` is the Layout its percentages resolve against. */
+export function useSidePanel(containerRef, initiallyOpen) {
+    const id = useId();
+    const [open, setOpen] = useState(initiallyOpen);
+    const toggle = useCallback(() => setOpen((value) => !value), []);
+    const resizable = useResizable({ ...SIDE_PANEL_SIZING, containerRef });
+    return { id, open, toggle, resizable };
+}
+/** The Layout header row: side panel toggles, at the end. */
+export function SidePanelHeader({ children }) {
+    return (_jsx(LayoutHeader, { hasDivider: false, children: _jsx(HStack, { hAlign: "end", gap: 1, children: children }) }));
+}
+/** Shows or hides one side panel (`panelId` from useSidePanel). */
+export function SidePanelToggle({ labels, icon, panelId, open, onToggle, }) {
+    const action = open ? labels.hide : labels.show;
+    return (_jsx(IconButton, { label: action, tooltip: action, variant: "ghost", "aria-expanded": open, "aria-controls": panelId, icon: icon, onClick: onToggle }));
+}
+/** Page corners like the host's raised panels, no border or shadow; the card fill, so surface-filled cards read on it. */
+export const RAISED = { background: 'var(--color-background-card)', borderRadius: 'var(--radius-page)' };
+/**
+ * A Layout `end` panel as Astryx's IDE template builds one (a reversed
+ * `ResizeHandle` before a `LayoutPanel` sized by `useResizable`), holding a
+ * raised section inset from the layout edge and bottom instead of a flat pane.
+ * For more than one panel, nest Layouts, one panel each, as the template does.
+ */
+export function SidePanel({ id, labels, resizable, open = true, padding, children }) {
+    return (_jsxs(_Fragment, { children: [open ? (_jsx(ResizeHandle, { direction: "horizontal", isReversed: true, hasDivider: false, isAlwaysVisible: false, resizable: resizable.props, label: labels.resize })) : null, _jsx(LayoutPanel, { id: id, label: labels.name, role: "complementary", width: open ? resizable.size : 0, hasDivider: false, padding: 0, isScrollable: false, inert: !open, children: _jsx(VStack, { height: "100%", paddingInlineEnd: 3, paddingBlockEnd: 3, children: _jsx(Card, { variant: "transparent", height: "100%", padding: padding, style: RAISED, children: open ? children : null }) }) })] }));
+}

package/ui/StateFields.d.ts

@@ -0,0 +1,36 @@
+import type { DecisionJson } from '@theoremjs/agents';
+export type Edit<T = DecisionJson> = {
+    value: T;
+    onChange: (next: T) => void;
+};
+export type GroupLabel = {
+    label: string;
+    isRequired?: boolean;
+    description?: string;
+};
+/** Several fields under one name, in the same label a single field has. */
+export declare function Labelled({ label, isRequired, description, children }: GroupLabel & {
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+/** Nested fields sit under their name, set in by a rule. */
+export declare function Group({ children, ...label }: GroupLabel & {
+    children: React.ReactNode;
+}): import("react").JSX.Element;
+/** One more row at the end of a list. */
+export declare function AddRow({ field, onAdd }: {
+    field: string;
+    onAdd: () => void;
+}): import("react").JSX.Element;
+/** Removes a list's row, named by its place. */
+export declare function RemoveRow({ index, onRemove }: {
+    index: number;
+    onRemove: () => void;
+}): import("react").JSX.Element;
+/**
+ * A decision's state edited field by field: objects as labelled fields, lists
+ * of words as tokens, other lists as rows. The shape itself (new keys, other
+ * types) is edited as JSON.
+ */
+export declare function StateFields({ value, onChange, label }: Edit & {
+    label: string;
+}): import("react").JSX.Element;

package/ui/StateFields.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@astryxdesign/core/Button';
+import { FieldLabel } from '@astryxdesign/core/Field';
+import { HStack } from '@astryxdesign/core/HStack';
+import { IconButton } from '@astryxdesign/core/IconButton';
+import { NumberInput } from '@astryxdesign/core/NumberInput';
+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 { IconPlus, IconX } from '@tabler/icons-react';
+import { useId, useState } from 'react';
+import { humanize, isPlain } from "../client/shaped-data.js";
+import { blankLike, isWordList, tableColumns } from "../client/state-fields.js";
+import { useLabels } from "./labels-provider.js";
+const NO_SUGGESTIONS = { search: () => [], bootstrap: () => [] };
+/** Text this long, or on several lines, gets a text area. */
+const LONG_TEXT = 48;
+/** A string, number, true/false, or null, as its input. */
+function PlainField({ value, onChange, label, isLabelHidden }) {
+    // Decided once, so the field doesn't swap inputs (and lose focus) as the text grows.
+    const [isLong] = useState(() => typeof value === 'string' && (value.length > LONG_TEXT || value.includes('\n')));
+    if (typeof value === 'boolean')
+        return _jsx(Switch, { label: label, value: value, onChange: onChange });
+    if (typeof value === 'number') {
+        return _jsx(NumberInput, { label: label, isLabelHidden: isLabelHidden, size: "sm", value: value, isWheelEnabled: false, onChange: onChange });
+    }
+    if (value === null)
+        return _jsx(TextInput, { label: label, isLabelHidden: isLabelHidden, size: "sm", value: "", placeholder: "null", isDisabled: true, onChange: () => { } });
+    const text = String(value);
+    return isLong ? (_jsx(TextArea, { label: label, isLabelHidden: isLabelHidden, size: "sm", rows: 2, value: text, onChange: onChange })) : (_jsx(TextInput, { label: label, isLabelHidden: isLabelHidden, size: "sm", value: text, onChange: onChange }));
+}
+/** Several fields under one name, in the same label a single field has. */
+export function Labelled({ label, isRequired, description, children }) {
+    const id = useId();
+    return (_jsxs(VStack, { gap: 2, role: "group", "aria-labelledby": id, children: [_jsx(FieldLabel, { label: label, inputID: "", labelID: id, isGroupLabel: true, isRequired: isRequired, description: description }), children] }));
+}
+/** Nested fields sit under their name, set in by a rule. */
+export function Group({ children, ...label }) {
+    return (_jsx(Labelled, { ...label, children: _jsx("div", { style: { paddingInlineStart: 12, borderInlineStart: '1px solid var(--color-border)' }, children: children }) }));
+}
+/** One more row at the end of a list. */
+export function AddRow({ field, onAdd }) {
+    const t = useLabels();
+    return (_jsx(HStack, { children: _jsx(Button, { label: t('@theorem.decision.add_item', { field }), size: "sm", variant: "ghost", icon: _jsx(IconPlus, { size: 14 }), onClick: onAdd }) }));
+}
+/** Removes a list's row, named by its place. */
+export function RemoveRow({ index, onRemove }) {
+    const t = useLabels();
+    return (_jsx(IconButton, { label: t('@theorem.decision.remove_item', { item: t('@theorem.data.item', { index: String(index + 1) }) }), size: "sm", variant: "ghost", icon: _jsx(IconX, { size: 14 }), onClick: onRemove }));
+}
+function ObjectFields({ value, onChange }) {
+    return (_jsx(VStack, { gap: 3, children: Object.entries(value).map(([key, entry]) => (_jsx(Field, { label: humanize(key), value: entry, onChange: (next) => onChange({ ...value, [key]: next }) }, key))) }));
+}
+/** A list of words as tokens; any other list as rows, each removable, with one more shaped like the last. */
+function ListField({ value, onChange, label }) {
+    const t = useLabels();
+    if (isWordList(value)) {
+        return (_jsx(Tokenizer, { label: label, size: "sm", value: value.map((word, index) => ({ id: `${String(index)}:${word}`, label: word })), searchSource: NO_SUGGESTIONS, hasCreate: true, debounceMs: 0, placeholder: t('@theorem.decision.add_value'), onChange: (items) => onChange(items.map((item) => item.label)) }));
+    }
+    const columns = tableColumns(value);
+    const add = _jsx(AddRow, { field: label, onAdd: () => onChange([...value, blankLike(value.at(-1))]) });
+    const remove = (index) => _jsx(RemoveRow, { index: index, onRemove: () => onChange(value.filter((_, at) => at !== index)) });
+    if (columns) {
+        // Rows alike and flat, as ShapedData draws them: a table, one input per cell.
+        const grid = { display: 'grid', gap: 8, alignItems: 'start', gridTemplateColumns: `${columns.map((column) => `minmax(0, ${String(column.weight)}fr)`).join(' ')} auto` };
+        const rows = value;
+        return (_jsxs(Labelled, { label: label, children: [_jsxs("div", { style: grid, "aria-hidden": true, children: [columns.map((column) => (_jsx(Text, { type: "supporting", color: "secondary", maxLines: 1, children: humanize(column.key) }, column.key))), _jsx("span", { style: { width: 28 } })] }), rows.map((row, index) => (_jsxs("div", { style: grid, children: [columns.map((column) => (_jsx(PlainField, { label: `${humanize(column.key)} ${String(index + 1)}`, isLabelHidden: true, value: row[column.key] ?? null, onChange: (next) => onChange(rows.map((old, at) => (at === index ? { ...old, [column.key]: next } : old))) }, column.key))), remove(index)] }, index))), add] }));
+    }
+    return (_jsx(Group, { label: label, children: _jsxs(VStack, { gap: 3, children: [value.map((entry, index) => {
+                    const item = t('@theorem.data.item', { index: String(index + 1) });
+                    const set = (next) => onChange(value.map((old, at) => (at === index ? next : old)));
+                    return (_jsxs(HStack, { gap: 2, vAlign: "start", children: [_jsx(StackItem, { size: "fill", children: isPlain(entry) ? _jsx(PlainField, { label: item, isLabelHidden: true, value: entry, onChange: set }) : _jsx(Field, { label: item, value: entry, onChange: set }) }), remove(index)] }, index));
+                }), add] }) }));
+}
+function Field({ value, onChange, label }) {
+    if (Array.isArray(value))
+        return _jsx(ListField, { label: label, value: value, onChange: onChange });
+    if (value !== null && typeof value === 'object') {
+        return (_jsx(Group, { label: label, children: _jsx(ObjectFields, { value: value, onChange: onChange }) }));
+    }
+    return _jsx(PlainField, { label: label, value: value, onChange: onChange });
+}
+/**
+ * A decision's state edited field by field: objects as labelled fields, lists
+ * of words as tokens, other lists as rows. The shape itself (new keys, other
+ * types) is edited as JSON.
+ */
+export function StateFields({ value, onChange, label }) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value))
+        return _jsx(ObjectFields, { value: value, onChange: onChange });
+    return _jsx(Field, { label: label, value: value, onChange: onChange });
+}

package/ui/TheoremChat.d.ts

@@ -0,0 +1,71 @@
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import { type ReactNode, type Ref } from 'react';
+import { type HttpTransportOptions, type TheoremTransport } from '../client/transport.ts';
+import { type ChatSnapshot, type SentTurn } from '../hooks/use-theorem-chat.ts';
+import type { TheoremLabels } from './labels.ts';
+export type TheoremChatProps = {
+    /** Where `createTheoremHandler` is mounted. Default `/api/theorem`. Ignored when `transport` is set. */
+    endpoint?: string;
+    /** Extra fetch options for the default HTTP transport (auth headers, custom fetch). */
+    http?: Omit<HttpTransportOptions, 'endpoint'>;
+    /** Bring your own transport (tests, playgrounds, non-HTTP hosts). */
+    transport?: TheoremTransport;
+    /** Astryx theme. Omit to inherit the host's `<Theme>` or use `theoremTheme`. */
+    theme?: DefinedTheme;
+    mode?: 'system' | 'light' | 'dark';
+    /**
+     * Replacement lines by locale, for any `@theorem.*` key in
+     * `THEOREM_UI_CATALOG` or any of Astryx's `@astryx.*` keys. The locale is
+     * the host's Astryx `InternationalizationProvider` locale (default `en`).
+     */
+    labels?: TheoremLabels;
+    placeholder?: string;
+    /** Shown above the centred composer before the first message. Default: the agent's handle and a prompt. */
+    emptyState?: ReactNode;
+    density?: 'compact' | 'balanced' | 'spacious';
+    /**
+     * Widest the transcript and composer may grow, as a CSS length. Default
+     * {@link DEFAULT_CHAT_MAX_WIDTH}: 50% of the chat, or full width on narrow screens.
+     */
+    maxWidth?: string;
+    /** Page scroller when the chat is not its own scroll container (e.g. `document.documentElement`). */
+    scrollRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Show the trace in place of the chat, from the host's own control; the
+     * built-in trace toggle then hides. Omit to keep the toggle. Needs a profile
+     * that records traces.
+     */
+    trace?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    /** A conversation to resume, as `onChatChange` reported it. Read once, when the chat mounts. */
+    initialChat?: ChatSnapshot;
+    /**
+     * Called with the conversation each time it comes to rest: a turn finished, or a message was
+     * added or removed; never while a reply streams. Keep it to resume the chat later.
+     */
+    onChatChange?: (snapshot: ChatSnapshot) => void;
+    /** Lets the host send a message as the composer would; see {@link TheoremChatHandle}. */
+    chatRef?: Ref<TheoremChatHandle>;
+};
+/** What a host can do to a mounted {@link TheoremChat}. */
+export type TheoremChatHandle = {
+    /**
+     * Sends `text` as the user, and resolves with the blocks the turn added once the reply is done;
+     * `null` when the chat can't take a message now (a reply is streaming, or waits on a gate).
+     */
+    send: (text: string) => Promise<SentTurn | null>;
+};
+/**
+ * 50% of the chat's width, but never narrower than 640px (or the full width,
+ * whichever is smaller) — so phones and narrow panes get 100%.
+ */
+export declare const DEFAULT_CHAT_MAX_WIDTH = "max(50%, min(100%, 640px))";
+/**
+ * Drop-in chat for a profile served by `createTheoremHandler`:
+ *
+ * ```tsx
+ * <TheoremChat endpoint="/api/theorem" />
+ * ```
+ */
+export declare function TheoremChat({ endpoint, http, transport, theme, mode, labels, ...rest }: TheoremChatProps): import("react").JSX.Element;

package/ui/TheoremChat.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Banner } from '@astryxdesign/core/Banner';
+import { Center } from '@astryxdesign/core/Center';
+import { ChatLayout } from '@astryxdesign/core/Chat';
+import { Layout, LayoutContent } from '@astryxdesign/core/Layout';
+import { Spinner } from '@astryxdesign/core/Spinner';
+import { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { useImperativeHandle, useLayoutEffect, useMemo, useRef, } from 'react';
+import { moveComposerPendingWithinKind, removeComposerPendingMessage, } from '@theoremjs/agents/interface';
+import { createHttpTransport } from "../client/transport.js";
+import { useTheoremChat } from "../hooks/use-theorem-chat.js";
+import { useTheoremInterface } from "../hooks/use-theorem-interface.js";
+import { ChatComposerBar } from "./ChatComposerBar.js";
+import { parseAspectRatio } from "../client/image-output.js";
+import { ChatTranscript } from "./ChatTranscript.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { TheoremThemeProvider } from "./theme.js";
+import { SidePanelHeader } from "./SidePanel.js";
+import { useTraceInspector, WithTrace } from "./TraceInspectorPanel.js";
+/**
+ * 50% of the chat's width, but never narrower than 640px (or the full width,
+ * whichever is smaller) — so phones and narrow panes get 100%.
+ */
+export const DEFAULT_CHAT_MAX_WIDTH = 'max(50%, min(100%, 640px))';
+/** Centres content in a column no wider than `maxWidth`, using Astryx layout props. */
+function ChatColumn({ maxWidth, ref, children }) {
+    return (_jsx(Center, { axis: "horizontal", width: "100%", children: _jsx(VStack, { ref: ref, width: "100%", maxWidth: maxWidth, children: children }) }));
+}
+/** Reads an Astryx duration token ("410ms" / "0.4s") as milliseconds. */
+function tokenMs(value, fallback) {
+    const n = Number.parseFloat(value);
+    if (Number.isNaN(n))
+        return fallback;
+    return value.trim().endsWith('ms') ? n : n * 1_000;
+}
+/**
+ * The composer is centred until the first message, then lives in ChatLayout's
+ * dock. Astryx has no layout-transition helper, so this eases the jump (FLIP)
+ * with Astryx's `--duration-medium` / `--ease-standard` tokens and keeps focus.
+ */
+function useComposerGlide(landing, inputRef) {
+    const columnRef = useRef(null);
+    const landingTop = useRef(null);
+    useLayoutEffect(() => {
+        const el = columnRef.current;
+        if (!el)
+            return;
+        if (landing) {
+            landingTop.current = el.getBoundingClientRect().top;
+            return;
+        }
+        const from = landingTop.current;
+        if (from === null)
+            return;
+        landingTop.current = null;
+        inputRef.current?.focus();
+        const delta = from - el.getBoundingClientRect().top;
+        if (delta === 0 || globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches)
+            return;
+        const tokens = getComputedStyle(el);
+        el.animate([{ transform: `translateY(${String(delta)}px)` }, { transform: 'none' }], {
+            duration: tokenMs(tokens.getPropertyValue('--duration-medium'), 410),
+            easing: tokens.getPropertyValue('--ease-standard').trim() || 'ease-out',
+        });
+    });
+    return columnRef;
+}
+/** The composer bar wired to a `useTheoremChat` model. */
+function ChatComposerForChat({ chat, iface, placeholder, inputRef, }) {
+    return (_jsx(ChatComposerBar, { iface: iface, draftText: chat.draftText, pendingFiles: chat.pendingFiles, pendingVoice: chat.pendingVoice, pendingMessages: chat.pendingMessages, issues: chat.issues, phase: chat.phase, failure: chat.failure, selectedModel: chat.session.selectedModel, selectedEffort: chat.session.selectedEffort, placeholder: placeholder, inputRef: inputRef, onDraftTextChange: chat.setDraftText, onFilesSelected: (files) => {
+            chat.setPendingFiles((prev) => [...prev, ...files]);
+            chat.setIssues([]);
+        }, onAttachmentRemove: (index) => {
+            chat.setPendingFiles((prev) => prev.filter((_, i) => i !== index));
+        }, onVoiceStaged: (file) => {
+            chat.setPendingVoice([file]);
+            chat.setIssues([]);
+        }, onVoiceClear: () => chat.setPendingVoice([]), onSubmit: () => {
+            void chat.handleSubmit();
+        }, onStop: chat.handleStop, onMenuAction: chat.handleMenuAction, onGenerationChange: chat.handleGenerationChange, onPendingMove: (id, direction) => {
+            chat.setPendingMessages((prev) => moveComposerPendingWithinKind(prev, id, direction));
+        }, onPendingRemove: (id) => {
+            chat.setPendingMessages((prev) => removeComposerPendingMessage(prev, id));
+        }, onPendingQueue: chat.handlePendingQueue, onPendingRestore: (id) => {
+            void chat.handlePendingRestore(id);
+        }, onPendingSendNow: (id) => {
+            const message = chat.pendingMessages.find((m) => m.id === id);
+            if (message)
+                void chat.handleSendNow(message);
+        } }));
+}
+function ChatBody({ transport, iface, placeholder, emptyState, density, maxWidth = DEFAULT_CHAT_MAX_WIDTH, scrollRef, trace, className, style, initialChat, onChatChange, chatRef, }) {
+    const t = useLabels();
+    const chat = useTheoremChat({ transport, iface, initial: initialChat, onChange: onChatChange });
+    const sendText = chat.sendText;
+    useImperativeHandle(chatRef, () => ({ send: sendText }), [sendText]);
+    const blocks = useMemo(() => [...chat.blocks, ...chat.streamBlocks], [chat.blocks, chat.streamBlocks]);
+    const handle = t('@theorem.agent.handle', { handle: iface.identity.handle });
+    const landing = blocks.length === 0;
+    const inputRef = useRef(null);
+    const composerRef = useComposerGlide(landing, inputRef);
+    const inspector = useTraceInspector(iface, transport.traces, trace);
+    const header = _jsx(SidePanelHeader, { children: inspector.toggle });
+    const composer = (_jsx(ChatComposerForChat, { chat: chat, iface: iface, placeholder: placeholder, inputRef: inputRef }));
+    // Before the first message: the composer alone, centred (Astryx AI chat
+    // template landing). paddingInline={3} matches the dock's inset so the
+    // composer keeps its width when it moves.
+    if (landing) {
+        return (_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { height: "fill", className: className, style: style, header: header, content: _jsx(LayoutContent, { padding: 0, children: _jsxs(VStack, { minHeight: "100%", vAlign: "center", gap: 8, paddingInline: 3, children: [_jsx(ChatColumn, { maxWidth: maxWidth, children: emptyState ?? (_jsxs(VStack, { gap: 1, children: [_jsx(Text, { type: "large", as: "h2", children: handle }), _jsx(Text, { type: "display-2", as: "h1", children: t('@theorem.chat.greeting') })] })) }), _jsx(ChatColumn, { ref: composerRef, maxWidth: maxWidth, children: composer })] }) }) }) }));
+    }
+    // Structure from Astryx's AI chat template: Layout › LayoutContent › ChatLayout,
+    // with the composer in ChatLayout's own dock. The dock leaves 12px under the
+    // composer; paddingBlockEnd={3} adds 12px more for a 24px bottom margin.
+    return (_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { height: "fill", className: className, style: style, header: header, content: _jsx(LayoutContent, { padding: 0, children: _jsx(VStack, { height: "100%", children: _jsx(ChatLayout, { density: density, scrollRef: scrollRef, composer: _jsx(VStack, { paddingBlockEnd: 3, children: _jsx(ChatColumn, { ref: composerRef, maxWidth: maxWidth, children: composer }) }), children: _jsx(ChatColumn, { maxWidth: maxWidth, children: _jsx(ChatTranscript, { blocks: blocks, handle: handle, streaming: chat.streaming, delivery: chat.delivery, answering: chat.answering, imageOutput: iface.type === 'image' ? { ratio: parseAspectRatio(iface.image.aspectRatio) } : undefined, onToolDecision: (index, action) => {
+                                    void chat.handleToolDecision(index, action);
+                                }, onAuthenticated: (index, secret) => {
+                                    void chat.handleAuthenticated(index, secret);
+                                } }) }) }) }) }) }) }));
+}
+function ChatForTransport(props) {
+    const t = useLabels();
+    const described = useTheoremInterface(props.transport);
+    if (described.status === 'loading')
+        return _jsx(Spinner, { size: "lg", label: t('@theorem.chat.loading') });
+    if (described.status === 'error') {
+        return _jsx(Banner, { status: "error", title: described.failure.error });
+    }
+    if (described.iface.type === 'live') {
+        return (_jsx(Banner, { status: "warning", title: t('@theorem.chat.live_unsupported.title'), description: t('@theorem.chat.live_unsupported.description') }));
+    }
+    return _jsx(ChatBody, { ...props, transport: props.transport, iface: described.iface });
+}
+/**
+ * Drop-in chat for a profile served by `createTheoremHandler`:
+ *
+ * ```tsx
+ * <TheoremChat endpoint="/api/theorem" />
+ * ```
+ */
+export function TheoremChat({ endpoint, http, transport, theme, mode, labels, ...rest }) {
+    const resolved = useMemo(() => transport ?? createHttpTransport({ ...http, endpoint }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- `http` identity is caller-owned; endpoint drives reconnection.
+    [transport, endpoint]);
+    return (_jsx(TheoremThemeProvider, { theme: theme, mode: mode, children: _jsx(TheoremLabelsProvider, { labels: labels, children: _jsx(ChatForTransport, { ...rest, transport: resolved }) }) }));
+}

package/ui/TheoremDecision.d.ts

@@ -0,0 +1,38 @@
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import { type CSSProperties } from 'react';
+import { type DecisionTransport } from '../client/decision-transport.ts';
+import type { HttpOptions } from '../client/transport.ts';
+import type { TheoremLabels } from './labels.ts';
+export type TheoremDecisionProps = {
+    /** Where `createTheoremDecisionHandler` is mounted. Default `/api/decision`. Ignored when `transport` is set. */
+    endpoint?: string;
+    /** Extra fetch options for the default HTTP transport (auth headers, custom fetch). */
+    http?: HttpOptions;
+    /** Bring your own transport (tests, playgrounds, non-HTTP hosts). */
+    transport?: DecisionTransport;
+    /** The JSON the state field starts with. Default `{}`. */
+    defaultState?: string;
+    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;
+    /**
+     * Show the trace in place of the decision, from the host's own control; the
+     * built-in trace toggle then hides. Omit to keep the toggle. Needs a profile
+     * that records traces.
+     */
+    trace?: boolean;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * Drop-in surface for a decision profile served by `createTheoremDecisionHandler`:
+ * the state as fields or JSON, a Decide button (⌘/Ctrl+Enter), and the answers.
+ *
+ * ```tsx
+ * <TheoremDecision endpoint="/api/decision" />
+ * ```
+ */
+export declare function TheoremDecision({ endpoint, http, transport, theme, mode, labels, ...rest }: TheoremDecisionProps): import("react").JSX.Element;

package/ui/TheoremDecision.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Banner } from '@astryxdesign/core/Banner';
+import { Spinner } from '@astryxdesign/core/Spinner';
+import { useLocale } from '@astryxdesign/core/i18n';
+import { useMemo, useState } from 'react';
+import { createDecisionTransport, } from "../client/decision-transport.js";
+import { useTheoremDecision } from "../hooks/use-theorem-decision.js";
+import { TheoremDecisionAnswers } from "./DecisionAnswers.js";
+import { ConsoleFrame, JsonRequest, RequestCard, RunBar } from "./ConsoleFrame.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { StateFields } from "./StateFields.js";
+import { TheoremThemeProvider } from "./theme.js";
+import { useTraceInspector } from "./TraceInspectorPanel.js";
+/** The field's text as the state a decision sends, measured the way the kernel measures it. */
+function checkState(text, maxBytes) {
+    let state;
+    try {
+        state = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: 'invalid_json' };
+    }
+    if (state === null)
+        return { ok: false, reason: 'null_state', state };
+    const bytes = new TextEncoder().encode(JSON.stringify(state)).byteLength;
+    if (maxBytes !== undefined && bytes > maxBytes)
+        return { ok: false, reason: 'too_large', bytes, state };
+    return { ok: true, state, bytes };
+}
+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]);
+}
+function stateNote(t, check, maxBytes, bytes) {
+    if (!check.ok) {
+        if (check.reason === 'too_large')
+            return t('@theorem.decision.too_large', { limit: bytes(maxBytes ?? 0) });
+        return t(check.reason === 'invalid_json' ? '@theorem.decision.invalid_json' : '@theorem.decision.null_state');
+    }
+    return maxBytes === undefined ? bytes(check.bytes) : t('@theorem.decision.state_size', { size: bytes(check.bytes), limit: bytes(maxBytes) });
+}
+function DecisionBody({ transport, iface, decision, defaultState = '{}', maxWidth = '960px', trace, className, style }) {
+    const t = useLabels();
+    const bytes = useBytes();
+    const [text, setText] = useState(defaultState);
+    const check = checkState(text, iface.maxStateBytes);
+    const note = stateNote(t, check, iface.maxStateBytes, bytes);
+    // Fields while the text parses; JSON to change the shape, or to fix it.
+    const [view, setView] = useState(() => (check.state === undefined ? 'json' : 'fields'));
+    const shown = check.state === undefined ? 'json' : view;
+    const inspector = useTraceInspector(iface, transport.traces, trace);
+    const deciding = decision.status === 'deciding';
+    const decide = () => {
+        if (check.ok)
+            void decision.decide(check.state);
+    };
+    return (_jsxs(ConsoleFrame, { inspector: inspector, maxWidth: maxWidth, className: className, style: style, children: [_jsxs(RequestCard, { title: t('@theorem.decision.state'), view: shown, hasFields: check.state !== undefined, onView: setView, onRun: decide, children: [shown === 'fields' && check.state !== undefined ? (_jsx(StateFields, { label: t('@theorem.decision.state'), value: check.state, onChange: (next) => {
+                            setText(JSON.stringify(next, null, 2));
+                        } })) : (_jsx(JsonRequest, { label: t('@theorem.decision.state'), text: text, isInvalid: !check.ok, onChange: setText })), _jsx(RunBar, { note: note, isReady: check.ok, isRunning: deciding, runLabel: t('@theorem.decision.decide'), runningLabel: t('@theorem.decision.deciding'), stopLabel: t('@theorem.decision.stop'), onRun: decide, onStop: decision.cancel })] }), decision.failure ? _jsx(Banner, { status: "error", title: decision.failure.error }) : null, decision.result ? (_jsx(TheoremDecisionAnswers, { iface: iface, result: decision.result, elapsedMs: decision.elapsedMs, isStale: deciding })) : null] }));
+}
+function DecisionForTransport(props) {
+    const t = useLabels();
+    const decision = useTheoremDecision(props.transport);
+    if (decision.describeFailure)
+        return _jsx(Banner, { status: "error", title: decision.describeFailure.error });
+    if (!decision.iface)
+        return _jsx(Spinner, { size: "lg", label: t('@theorem.chat.loading') });
+    return _jsx(DecisionBody, { ...props, iface: decision.iface, decision: decision });
+}
+/**
+ * Drop-in surface for a decision profile served by `createTheoremDecisionHandler`:
+ * the state as fields or JSON, a Decide button (⌘/Ctrl+Enter), and the answers.
+ *
+ * ```tsx
+ * <TheoremDecision endpoint="/api/decision" />
+ * ```
+ */
+export function TheoremDecision({ endpoint, http, transport, theme, mode, labels, ...rest }) {
+    const resolved = useMemo(() => transport ?? createDecisionTransport({ ...http, endpoint }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- `http` identity is caller-owned; endpoint drives reconnection.
+    [transport, endpoint]);
+    return (_jsx(TheoremThemeProvider, { theme: theme, mode: mode, children: _jsx(TheoremLabelsProvider, { labels: labels, children: _jsx(DecisionForTransport, { ...rest, transport: resolved }) }) }));
+}

package/ui/TheoremHost.d.ts

@@ -0,0 +1,38 @@
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import { type CSSProperties } from 'react';
+import { type HostTransport } from '../client/host-transport.ts';
+import type { HttpOptions } from '../client/transport.ts';
+import { type TheoremLabels } from './labels.ts';
+export type TheoremHostProps = {
+    /** Where `createTheoremHostHandler` is mounted. Default `/api/host`. Ignored when `transport` is set. */
+    endpoint?: string;
+    /** Extra fetch options for the default HTTP transport (auth headers, custom fetch). */
+    http?: HttpOptions;
+    /** Bring your own transport (tests, playgrounds, non-HTTP hosts). */
+    transport?: HostTransport;
+    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;
+    /**
+     * Show the trace in place of the console, from the host's own control; the
+     * built-in trace toggle then hides. Omit to keep the toggle. Needs a profile
+     * that records traces.
+     */
+    trace?: boolean;
+    className?: string;
+    style?: CSSProperties;
+};
+/**
+ * Drop-in console for a host profile served by `createTheoremHostHandler`:
+ * pick a tool, fill in the request its input schema draws, Run (⌘/Ctrl+Enter),
+ * and read the response laid out from what it returned — figures, charts,
+ * images, and the data itself. Gates are answered in place.
+ *
+ * ```tsx
+ * <TheoremHost endpoint="/api/host" />
+ * ```
+ */
+export declare function TheoremHost({ endpoint, http, transport, theme, mode, labels, ...rest }: TheoremHostProps): import("react").JSX.Element;