@theoremjs/react 0.0.0-stage → 0.3.1

package/ui/TheoremChat.d.ts

@@ -0,0 +1,122 @@
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import { type ReactNode, type Ref } from 'react';
+import type { PageTools } from '../client/live/live-page-tool.ts';
+import { type ConversationView, type HttpTransportOptions, type TheoremTransport } from '../client/transport.ts';
+import { type SentTurn, type UseTheoremChatOptions } 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, studios, 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;
+    /**
+     * Colour code the reply left untagged: a fence with no language is read and, when it is plainly
+     * one of JavaScript, TypeScript, Python, shell, JSON, CSS, HTML, XML, YAML, or Markdown, shown as it.
+     * A fence with a language is never changed. Off by default.
+     */
+    detectCodeLanguage?: boolean;
+    /**
+     * The value chosen for each of the profile's `inputs.slots`, sent with every turn. A slot you
+     * name is fixed to that value; one you leave out gets a selector in the composer bar, beside
+     * the model's, starting at its first allowed value.
+     */
+    slots?: Record<string, string>;
+    /** Told each time the visitor chooses a slot in the composer, with every slot's value. */
+    onSlotsChange?: (slots: Record<string, string>) => void;
+    /**
+     * What the page wants the agent to know: any JSON. The latest value goes with every
+     * turn, and the profile's `inputs.context.from` must list `client`.
+     */
+    context?: unknown;
+    /**
+     * The page's tools, by name: each answers a tool the profile declares with
+     * `answeredBy: 'page'`. The reply waits while the page answers; no one is asked.
+     */
+    pageTools?: PageTools;
+    /** Every event of every turn, as it arrives: also the ones the chat shows nothing for. */
+    onTurnEvent?: UseTheoremChatOptions['onTurnEvent'];
+    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>;
+    /**
+     * Drive the trace from the host's own control. The built-in toggle hides.
+     * The open trace takes the chat'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;
+    /**
+     * Show what was used, as tokens and cost: each reply's total under it, and
+     * on an agent tool's call row what the agent it ran used. Off by default.
+     */
+    usage?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * The ref of a conversation to resume, as `onConversationChange` reported it. Read once, when
+     * the chat mounts: the chat draws the conversation as the host keeps it.
+     */
+    conversation?: string;
+    /**
+     * The conversation under `conversation` as the host showed it with the ref, as
+     * `startConversation` returns it. Read once, when the chat mounts: the chat draws it at once,
+     * and does not read it from the host again.
+     */
+    conversationView?: ConversationView;
+    /** The text the composer starts with, for the user to send or change. Read once, when the chat mounts. */
+    initialText?: string;
+    /**
+     * Called with each new ref the host issues for the conversation: once the message posts, and
+     * again as the reply's runs are saved. Keep the latest to resume the chat later.
+     */
+    onConversationChange?: (ref: string) => void;
+    /** Lets the host send a message as the composer would; see {@link TheoremChatHandle}. */
+    chatRef?: Ref<TheoremChatHandle>;
+    /**
+     * `false` leaves the composer out: the chat is the transcript alone, and your own control sends
+     * through `chatRef`. Gates are still answered in the transcript. Default `true`.
+     */
+    composer?: boolean;
+};
+/** What a host can do to a mounted {@link TheoremChat}. */
+export type TheoremChatHandle = {
+    /**
+     * Sends `text` and optional `files` 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, files?: readonly File[]) => Promise<SentTurn | null>;
+    /** Stops the reply that is streaming, as the composer's stop button does. */
+    stop: () => void;
+};
+/**
+ * 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, detectCodeLanguage, ...rest }: TheoremChatProps): import("react").JSX.Element;

package/ui/TheoremChat.js

@@ -0,0 +1,134 @@
+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 { Text } from '@astryxdesign/core/Text';
+import { VStack } from '@astryxdesign/core/VStack';
+import { moveComposerPendingWithinKind, removeComposerPendingMessage, } from '@theoremjs/agents/interface';
+import { useImperativeHandle, useMemo, useRef, } from 'react';
+import { parseAspectRatio } from "../client/image-output.js";
+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 { ChatTranscript } from "./ChatTranscript.js";
+import { useGlide } from "./glide.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { MarkdownPluginsProvider } from "./markdown-plugins.js";
+import { PaneFailure, PaneLoading } from "./PaneState.js";
+import { SidePanelHeader } from "./SidePanel.js";
+import { useTraceInspector, WithTrace } from "./TraceInspectorPanel.js";
+import { TheoremThemeProvider } from "./theme.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 }) }));
+}
+/** 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, slotChoices: chat.slotChoices, 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, usage, className, style, conversation, conversationView, initialText, onConversationChange, chatRef, composer: hasComposer = true, slots, onSlotsChange, context, pageTools, onTurnEvent, }) {
+    const t = useLabels();
+    const chat = useTheoremChat({
+        transport,
+        iface,
+        conversation,
+        conversationView,
+        initialText,
+        onConversationChange,
+        slots,
+        onSlotsChange,
+        context,
+        pageTools,
+        onTurnEvent,
+    });
+    const { sendText, handleStop } = chat;
+    useImperativeHandle(chatRef, () => ({ send: sendText, stop: handleStop }), [
+        sendText,
+        handleStop,
+    ]);
+    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 = useGlide(landing, () => inputRef.current?.focus());
+    const inspector = useTraceInspector(iface, transport.traces, trace);
+    const header = _jsx(SidePanelHeader, { floating: true, children: inspector.toggle });
+    // why: the composer says when a turn failed. Without one, the chat says it where the composer was.
+    const composer = hasComposer ? (_jsx(ChatComposerForChat, { chat: chat, iface: iface, placeholder: placeholder, inputRef: inputRef })) : (chat.failure && _jsx(Banner, { status: "error", role: "alert", title: chat.failure.error }));
+    const docked = { composer, composerRef, maxWidth };
+    return (_jsx(WithTrace, { inspector: inspector, children: _jsx(Layout, { height: "fill", className: className, style: { position: 'relative', ...style }, header: header, content: _jsx(LayoutContent, { padding: 0, children: landing ? (_jsx(ChatLanding, { ...docked, handle: handle, emptyState: emptyState })) : (_jsx(ChatThread, { ...docked, chat: chat, iface: iface, blocks: blocks, handle: handle, density: density, scrollRef: scrollRef, usage: usage })) }) }) }));
+}
+/**
+ * The chat before its first message: the greeting, and the composer under it.
+ * why: paddingInline={3} matches the dock's inset so the composer keeps its width when it moves.
+ */
+function ChatLanding({ composer, composerRef, maxWidth, handle, emptyState, }) {
+    const t = useLabels();
+    return (_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: "supporting", as: "h2", children: handle }), _jsx(Text, { type: "display-2", as: "h1", children: t('@theorem.chat.greeting') })] })) }), composer && (_jsx(ChatColumn, { ref: composerRef, maxWidth: maxWidth, children: composer }))] }));
+}
+/**
+ * The chat once it has messages: the transcript, with the composer in ChatLayout's own dock.
+ * why: the dock leaves 12px under the composer; paddingBlockEnd={3} adds 12px more for a 24px
+ * bottom margin.
+ */
+function ChatThread({ composer, composerRef, maxWidth, chat, iface, blocks, handle, density, scrollRef, usage, }) {
+    return (_jsx(VStack, { height: "100%", children: _jsx(ChatLayout, { density: density, scrollRef: scrollRef, composer: 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, usage: usage, labels: iface.labels, 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(PaneLoading, { label: t('@theorem.chat.loading') });
+    if (described.status === 'error')
+        return _jsx(PaneFailure, { title: described.failure.error });
+    if (described.iface.type === 'live') {
+        return (_jsx(PaneFailure, { 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, detectCodeLanguage, ...rest }) {
+    const httpRef = useRef(http);
+    httpRef.current = http;
+    const resolved = useMemo(() => transport ?? createHttpTransport({ ...httpRef.current, endpoint }), [transport, endpoint]);
+    return (_jsx(TheoremThemeProvider, { theme: theme, mode: mode, children: _jsx(TheoremLabelsProvider, { labels: labels, children: _jsx(MarkdownPluginsProvider, { detectCodeLanguage: detectCodeLanguage, children: _jsx(ChatForTransport, { ...rest, transport: resolved }) }) }) }));
+}

package/ui/TheoremDecision.d.ts

@@ -0,0 +1,30 @@
+import { type DecisionImages } from '../client/decision-images.ts';
+import { type DecisionTransport } from '../client/decision-transport.ts';
+import { type ConsolePageProps } from './ConsoleFrame.tsx';
+import { type TheoremDecisionAnswersProps } from './DecisionAnswers.tsx';
+export type TheoremDecisionProps = ConsolePageProps & {
+    /** Where `createTheoremDecisionHandler` is mounted. Default `/api/decision`. Ignored when `transport` is set. */
+    endpoint?: string;
+    /** Bring your own transport (tests, studios, non-HTTP hosts). */
+    transport?: DecisionTransport;
+    /** The JSON the state field starts with. Default `{}`. */
+    defaultState?: string;
+    /**
+     * Images attached when the page opens, by the name the state refers to them by. The visitor
+     * can add and remove more; they travel with each decision.
+     */
+    defaultImages?: DecisionImages;
+    /** Opens a question where it is set up, such as an editor. Each answer then has a button for it. */
+    onQuestion?: (id: string) => void;
+    /** Each question's text by its id, shown under its answer's title. The page is never sent a question's instructions, so it shows only what it is given here. */
+    questionText?: TheoremDecisionAnswersProps['questionText'];
+};
+/**
+ * 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,130 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Banner } from '@astryxdesign/core/Banner';
+import { useMemo, useRef, useState } from 'react';
+import { droppedImages, namedImages, stateFields, } from "../client/decision-images.js";
+import { createDecisionTransport, } from "../client/decision-transport.js";
+import { useTheoremDecision } from "../hooks/use-theorem-decision.js";
+import { ConsoleFrame, JsonRequest, RequestCard, ResponseColumn, RunBar, useBytes, } from "./ConsoleFrame.js";
+import { TheoremDecisionAnswers } from "./DecisionAnswers.js";
+import { ImageDrop } from "./DecisionImages.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { PaneFailure, PaneLoading } from "./PaneState.js";
+import { StateFields, StateImages } from "./StateFields.js";
+import { useTraceInspector } from "./TraceInspectorPanel.js";
+import { TheoremThemeProvider } from "./theme.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 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
+        ? null
+        : t('@theorem.decision.state_size', { size: bytes(check.bytes), limit: bytes(maxBytes) });
+}
+/** Where a decision stands: nothing asked, asked with nothing back yet, or answered or failed. */
+function decisionPhase(decision) {
+    if (decision.failure || decision.result)
+        return 'settled';
+    return decision.status === 'deciding' ? 'waiting' : 'idle';
+}
+/** The state a decision is asked about, held as text, and the view it is edited in. */
+function useDecisionState(defaultState, maxStateBytes) {
+    const [text, setText] = useState(defaultState);
+    const check = checkState(text, maxStateBytes);
+    const [view, setView] = useState(() => check.state === undefined ? 'json' : 'fields');
+    const shown = check.state === undefined ? 'json' : view;
+    return { text, setText, check, shown, setView };
+}
+/** The state, as fields or JSON, and Decide. */
+function DecisionRequest({ form, iface, images, onImages, note, isRunning, onRun, onStop, }) {
+    const t = useLabels();
+    const { text, setText, check, shown, setView } = form;
+    const withImages = iface.questions.some((question) => question.type === 'box') || Object.keys(images).length > 0;
+    const fields = shown === 'fields' ? check.state : undefined;
+    const named = stateFields(fields);
+    return (_jsxs(RequestCard, { title: t('@theorem.decision.state'), view: shown, hasFields: check.state !== undefined, onView: setView, onRun: onRun, children: [fields !== undefined ? (_jsx(StateImages, { value: { images, onImages }, children: _jsx(StateFields, { label: t('@theorem.decision.state'), value: fields, onChange: (next) => {
+                        setText(JSON.stringify(next, null, 2));
+                    } }) })) : (_jsx(JsonRequest, { label: t('@theorem.decision.state'), text: text, isInvalid: !check.ok, onChange: setText })), withImages && named ? (_jsx(ImageDrop, { onImages: (dropped) => {
+                    const next = droppedImages(dropped, { images, host: iface.images, state: named });
+                    onImages(next.images);
+                    setText(JSON.stringify(next.state, null, 2));
+                } })) : null, _jsx(RunBar, { note: note, isReady: check.ok, isRunning: isRunning, runLabel: t('@theorem.decision.decide'), runningLabel: t('@theorem.decision.deciding'), stopLabel: t('@theorem.decision.stop'), onRun: onRun, onStop: onStop })] }));
+}
+/** What came back: the failure, the answers, or a spinner until the first of either. */
+function DecisionAnswered({ iface, decision, asked, onQuestion, questionText, }) {
+    const t = useLabels();
+    const deciding = decision.status === 'deciding';
+    return (_jsxs(_Fragment, { children: [decision.failure ? (_jsx(Banner, { status: "error", role: "alert", title: decision.failure.error })) : null, deciding && !decision.result ? (_jsx(PaneLoading, { label: t('@theorem.decision.deciding'), since: decision.startedAt })) : null, decision.result ? (_jsx(TheoremDecisionAnswers, { iface: iface, result: decision.result, asked: asked, onQuestion: onQuestion, questionText: questionText, elapsedMs: decision.elapsedMs, isStale: deciding })) : null] }));
+}
+/**
+ * The frame's second child. A call, not a component: the frame counts its
+ * children to choose a layout, and no response yet has to count as none.
+ */
+function decisionResponse(columns, phase, labels, since, answers) {
+    if (phase === 'idle')
+        return null;
+    if (!columns)
+        return answers;
+    const waiting = phase === 'waiting';
+    return (_jsx(ResponseColumn, { label: labels.answers, fill: waiting, children: waiting ? _jsx(PaneLoading, { label: labels.deciding, since: since }) : answers }));
+}
+function DecisionBody({ transport, iface, decision, defaultState = '{}', defaultImages, onQuestion, questionText, maxWidth = '960px', trace, flush, columns = false, className, style, }) {
+    const t = useLabels();
+    const bytes = useBytes();
+    const form = useDecisionState(defaultState, iface.maxStateBytes);
+    const { check } = form;
+    const [images, setImages] = useState(defaultImages ?? {});
+    /** The images and state the answers were asked about, kept with them: later edits don't redraw them. */
+    const [asked, setAsked] = useState();
+    const inspector = useTraceInspector(iface, transport.traces, trace);
+    const decide = () => {
+        if (!check.ok)
+            return;
+        const sent = namedImages(images, check.state);
+        setAsked({ images: { ...iface.images, ...sent }, state: check.state });
+        void decision.decide(check.state, Object.keys(sent).length > 0 ? sent : undefined);
+    };
+    return (_jsxs(ConsoleFrame, { inspector: inspector, maxWidth: maxWidth, flush: flush, columns: columns, requestLabel: t('@theorem.decision.state'), className: className, style: style, children: [_jsx(DecisionRequest, { form: form, iface: iface, images: images, onImages: setImages, note: stateNote(t, check, iface.maxStateBytes, bytes), isRunning: decision.status === 'deciding', onRun: decide, onStop: decision.cancel }), decisionResponse(columns, decisionPhase(decision), { answers: t('@theorem.decision.answers'), deciding: t('@theorem.decision.deciding') }, decision.startedAt, _jsx(DecisionAnswered, { iface: iface, decision: decision, asked: asked, onQuestion: onQuestion, questionText: questionText }))] }));
+}
+function DecisionForTransport(props) {
+    const t = useLabels();
+    const decision = useTheoremDecision(props.transport);
+    if (decision.describeFailure)
+        return _jsx(PaneFailure, { title: decision.describeFailure.error });
+    if (!decision.iface)
+        return _jsx(PaneLoading, { 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 httpRef = useRef(http);
+    httpRef.current = http;
+    const resolved = useMemo(() => transport ?? createDecisionTransport({ ...httpRef.current, endpoint }), [transport, endpoint]);
+    return (_jsx(TheoremThemeProvider, { theme: theme, mode: mode, children: _jsx(TheoremLabelsProvider, { labels: labels, children: _jsx(DecisionForTransport, { ...rest, transport: resolved }) }) }));
+}

package/ui/TheoremEmbedding.d.ts

@@ -0,0 +1,27 @@
+import { type EmbeddingTransport } from '../client/embedding-transport.ts';
+import { type ConsolePageProps } from './ConsoleFrame.tsx';
+import { type EmbeddingDocument } from './EmbeddingDocuments.tsx';
+export type TheoremEmbeddingProps = ConsolePageProps & {
+    /** Where `createTheoremEmbeddingHandler` is mounted. Default `/api/embedding`. Ignored when `transport` is set. */
+    endpoint?: string;
+    /** Bring your own transport (tests, studios, non-HTTP hosts). */
+    transport?: EmbeddingTransport;
+    /** The text the documents card starts with, split into paragraphs. Default none. */
+    defaultText?: string;
+    /** Documents the card starts with beside the text, each with the file it came from. Default none. */
+    defaultDocuments?: readonly EmbeddingDocument[];
+    /** The query the search starts with. Default none. */
+    defaultQuery?: string;
+};
+/**
+ * Drop-in search over an embedding profile served by `createTheoremEmbeddingHandler`:
+ * paste text and split it, or drop files, and Index embeds them as documents
+ * in as many requests as the profile's limits need. Then Search embeds a query
+ * and ranks the documents by cosine similarity. Every request is shown as
+ * JSON, and in the trace.
+ *
+ * ```tsx
+ * <TheoremEmbedding endpoint="/api/embedding" />
+ * ```
+ */
+export declare function TheoremEmbedding({ endpoint, http, transport, theme, mode, labels, ...rest }: TheoremEmbeddingProps): import("react").JSX.Element;

package/ui/TheoremEmbedding.js

@@ -0,0 +1,122 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { VStack } from '@astryxdesign/core/VStack';
+import { useMemo, useRef, useState } from 'react';
+import { rankMatches } from "../client/embedding-input.js";
+import { createEmbeddingTransport, } from "../client/embedding-transport.js";
+import { useEmbeddingIndex } from "../hooks/use-embedding-index.js";
+import { useTheoremEmbedding } from "../hooks/use-theorem-embedding.js";
+import { ConsoleFrame, ConsoleSection, ResponseColumn, } from "./ConsoleFrame.js";
+import { EmbeddingDocuments, useEmbeddingDocuments, } from "./EmbeddingDocuments.js";
+import { EmbeddingQuery, useEmbeddingQuery } from "./EmbeddingQuery.js";
+import { EmbeddingResults, IndexCard } from "./EmbeddingResults.js";
+import { TheoremLabelsProvider, useLabels } from "./labels-provider.js";
+import { PaneFailure, PaneLoading } from "./PaneState.js";
+import { useTraceInspector } from "./TraceInspectorPanel.js";
+import { TheoremThemeProvider } from "./theme.js";
+/** The same documents: the same texts, and the very same files. */
+function sameInputs(a, b) {
+    return a.length === b.length && a.every((input, at) => input === b[at]);
+}
+/** Where the documents stand for the last query: embedded, changed since, or embedded by another model. */
+function indexStateOf(indexed, queried, inputs) {
+    if (!indexed)
+        return 'fresh';
+    // why: A query from another model than the index's is in another space; no score between them means anything.
+    if (queried && queried.model !== indexed.model)
+        return 'model';
+    return sameInputs(indexed.inputs, inputs) ? 'fresh' : 'stale';
+}
+function indexPhase(index) {
+    if (index.status === 'indexing')
+        return 'indexing';
+    return index.result !== null || index.failure !== null ? 'indexed' : 'idle';
+}
+/**
+ * The frame's second child. A call, not a component: the frame counts its
+ * children to choose a layout, and nothing indexed yet has to count as none.
+ */
+function embeddingResponse(columns, label, phase, results) {
+    if (phase === 'idle')
+        return null;
+    return columns ? (_jsx(ResponseColumn, { label: label, fill: phase === 'indexing', children: results })) : (results);
+}
+/** The spinner while the documents embed, counting the requests once there is more than one. */
+function IndexingPane({ index }) {
+    const t = useLabels();
+    const { progress } = index;
+    return (_jsx(PaneLoading, { label: progress
+            ? t('@theorem.embedding.indexing_progress', {
+                done: Math.min(progress.done + 1, progress.total),
+                total: progress.total,
+            })
+            : t('@theorem.embedding.indexing'), since: index.startedAt }));
+}
+/** Where the last query stands against the index: whether it searched, and its vector while both share a model. */
+function searchOf(index, search, inputs) {
+    const state = indexStateOf(index.result, search.result, inputs);
+    if (state === 'model')
+        return { state, searched: false, queried: null };
+    return {
+        state,
+        searched: search.status !== 'idle' || search.result !== null,
+        queried: search.result?.embeddings[0]?.values ?? null,
+    };
+}
+/** The query against the index, and once it ran, what it found. */
+function IndexSearch({ iface, index, search, query, indexed, state, searched, matches, pointing, }) {
+    return (_jsxs(ConsoleSection, { children: [_jsx(EmbeddingQuery, { form: query, rules: iface.inputs, index: state, isRunning: search.status === 'embedding', onRun: (input) => {
+                    void search.embed([input], { task: 'query' });
+                }, onStop: search.cancel }), searched ? (_jsx(VStack, { padding: 4, children: _jsx(EmbeddingResults, { index: index, search: search, documents: indexed, matches: matches, pointing: pointing }) })) : null] }));
+}
+/** The index, and once it holds vectors, the search over them. */
+function EmbeddingIndexed({ inputs, ...props }) {
+    const { index, indexed } = props;
+    const { state, searched, queried } = searchOf(index, props.search, inputs);
+    const vectors = index.result?.vectors;
+    const matches = useMemo(() => (queried && vectors ? rankMatches(queried, vectors) : []), [queried, vectors]);
+    const [hovered, setHovered] = useState(null);
+    const pointing = useMemo(() => ({ hovered, onHover: setHovered }), [hovered]);
+    return (_jsxs(VStack, { gap: 3, children: [_jsx(IndexCard, { run: index, documents: indexed, query: queried, matches: matches, pointing: pointing }), index.result ? (_jsx(IndexSearch, { ...props, state: state, searched: searched, matches: matches, pointing: pointing })) : null] }));
+}
+function EmbeddingBody({ transport, iface, search, defaultText = '', defaultDocuments, defaultQuery = '', maxWidth = '960px', trace, flush, columns = false, className, style, }) {
+    const t = useLabels();
+    const documents = useEmbeddingDocuments(defaultText, iface.inputs, defaultDocuments);
+    const query = useEmbeddingQuery(defaultQuery, iface.inputs);
+    const index = useEmbeddingIndex(transport);
+    const [indexed, setIndexed] = useState([]);
+    const inspector = useTraceInspector(iface, transport.traces, trace);
+    const runIndex = () => {
+        if (documents.jsonInvalid || documents.issue || documents.inputs.length === 0)
+            return;
+        setIndexed(documents.documents);
+        void index.index(documents.inputs, iface.inputs);
+    };
+    const phase = indexPhase(index);
+    return (_jsxs(ConsoleFrame, { inspector: inspector, maxWidth: maxWidth, flush: flush, columns: columns, requestLabel: t('@theorem.embedding.documents'), className: className, style: style, children: [_jsx(EmbeddingDocuments, { form: documents, rules: iface.inputs, isRunning: phase === 'indexing', onRun: runIndex, onStop: index.cancel }), embeddingResponse(columns, t('@theorem.embedding.results'), phase, phase === 'indexing' ? (_jsx(IndexingPane, { index: index })) : (_jsx(EmbeddingIndexed, { iface: iface, index: index, search: search, query: query, indexed: indexed, inputs: documents.inputs })))] }));
+}
+function EmbeddingForTransport(props) {
+    const t = useLabels();
+    const search = useTheoremEmbedding(props.transport);
+    if (search.describeFailure)
+        return _jsx(PaneFailure, { title: search.describeFailure.error });
+    if (!search.iface)
+        return _jsx(PaneLoading, { label: t('@theorem.chat.loading') });
+    return _jsx(EmbeddingBody, { ...props, iface: search.iface, search: search });
+}
+/**
+ * Drop-in search over an embedding profile served by `createTheoremEmbeddingHandler`:
+ * paste text and split it, or drop files, and Index embeds them as documents
+ * in as many requests as the profile's limits need. Then Search embeds a query
+ * and ranks the documents by cosine similarity. Every request is shown as
+ * JSON, and in the trace.
+ *
+ * ```tsx
+ * <TheoremEmbedding endpoint="/api/embedding" />
+ * ```
+ */
+export function TheoremEmbedding({ endpoint, http, transport, theme, mode, labels, ...rest }) {
+    const httpRef = useRef(http);
+    httpRef.current = http;
+    const resolved = useMemo(() => transport ?? createEmbeddingTransport({ ...httpRef.current, endpoint }), [transport, endpoint]);
+    return (_jsx(TheoremThemeProvider, { theme: theme, mode: mode, children: _jsx(TheoremLabelsProvider, { labels: labels, children: _jsx(EmbeddingForTransport, { ...rest, transport: resolved }) }) }));
+}

package/ui/TheoremHost.d.ts

@@ -0,0 +1,55 @@
+import type { DefinedTheme } from '@astryxdesign/core/theme';
+import { type CSSProperties } from 'react';
+import { type HostTransport } from '../client/host-transport.ts';
+import type { PageTools } from '../client/live/live-page-tool.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, studios, non-HTTP hosts). */
+    transport?: HostTransport;
+    /** why: Page callbacks run only after the server saves a dispatch grant. */
+    pageTools?: PageTools;
+    theme?: DefinedTheme;
+    mode?: 'system' | 'light' | 'dark';
+    /** Replacement lines by locale, for any `@theorem.*` or `@astryx.*` key. */
+    labels?: TheoremLabels;
+    /**
+     * Colour code the reply left untagged: a fence with no language is read and, when it is plainly
+     * one of JavaScript, TypeScript, Python, shell, JSON, CSS, HTML, XML, YAML, or Markdown, shown as it.
+     * A fence with a language is never changed. Off by default.
+     */
+    detectCodeLanguage?: boolean;
+    /** 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 console'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 response on the right. */
+    columns?: 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, detectCodeLanguage, ...rest }: TheoremHostProps): import("react").JSX.Element;