@theoremjs/react 0.3.4-next.677.g14b70fe → 0.3.4-next.693.g4ab1526

package/README.md

@@ -369,6 +369,8 @@ Three more props give the call values from the page. The profile declares each o
 | `context` | `inputs.context` with `from: ['client']` | Any JSON the agent should know, such as the page the person is on. |
 | `pageTools` | A function tool with `answeredBy: 'page'` | A function for each page tool, by name. It returns `{ output }`. |
 
+`stated` is a fourth prop, for a page you trust as yourself. It says the `path` and `conditions` that choose the call's prompt lines, and the server reads it only with `pageStatesTurn` set. A change during a call takes the call up again, as a slot does. `TheoremChat` takes the same prop, on each turn.
+
 ```tsx
 <LiveRunner
   iface={iface}

package/client/trace-view.js

@@ -311,6 +311,9 @@ const STORED_FORMATS = new Set([
 function isStringList(value) {
     return Array.isArray(value) && value.every((item) => typeof item === 'string');
 }
+function isNumberList(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'number');
+}
 /** An object, or a list of objects, as items to read by a catalog entry's fields. */
 function fieldItems(value) {
     if (isRecord(value))
@@ -326,6 +329,9 @@ export function traceValueShape(meta, value) {
         return { kind: 'scalar', value };
     if (isStringList(value))
         return { kind: 'list', value };
+    if (meta?.format === 'list' && isNumberList(value)) {
+        return { kind: 'list', value: value.map(String) };
+    }
     const items = meta?.fields ? fieldItems(value) : undefined;
     return meta?.fields && items
         ? { kind: 'fields', fields: meta.fields, items }

package/components/live/use-live-runner-model.d.ts

@@ -5,7 +5,7 @@ import { type LiveCaptionState, type LiveCaptionTurn } from '../../client/live/l
  * Owns LiveRunner state, session client, and stage callbacks.
  * `connection` resolves what the call opens: a host with a fixed profile returns
  * its id; the studio returns its draft as the relay's open message. `options`
- * are the host's part in the call: its slots, the page's context, and its page tools.
+ * are the host's part in the call: its slots, its stated turn, the page's context, and its page tools.
  */
 export declare function useLiveRunnerModel(iface: LiveProfileInterface, connection: () => LiveConnection | Promise<LiveConnection>, options?: LiveCallOptions): {
     handle: string;

package/components/live/use-live-runner-model.js

@@ -53,7 +53,7 @@ function useLiveCallLifecycle(controls, captionsRef, sessionActive, videoAvailab
  * Owns LiveRunner state, session client, and stage callbacks.
  * `connection` resolves what the call opens: a host with a fixed profile returns
  * its id; the studio returns its draft as the relay's open message. `options`
- * are the host's part in the call: its slots, the page's context, and its page tools.
+ * are the host's part in the call: its slots, its stated turn, the page's context, and its page tools.
  */
 export function useLiveRunnerModel(iface, connection, options = {}) {
     const ui = useLiveRunnerUiState(iface.labels);
@@ -78,6 +78,7 @@ export function useLiveRunnerModel(iface, connection, options = {}) {
     const traces = useMemo(createTraceFeed, []);
     const { clientRef, ensureClient, clearClient } = useLiveSessionClient({
         slots: options.slots,
+        stated: options.stated,
         context: options.context,
         pageTools: options.pageTools,
         voiceAvailable,
@@ -148,6 +149,11 @@ export function useLiveRunnerModel(iface, connection, options = {}) {
     useEffect(() => {
         clientRef.current?.setSlots(slotsJson === undefined ? undefined : JSON.parse(slotsJson));
     }, [clientRef, slotsJson]);
+    // why: As slots: a changed pick takes an open call up again with the lines it chooses.
+    const statedJson = JSON.stringify(options.stated);
+    useEffect(() => {
+        clientRef.current?.setStated(statedJson === undefined ? undefined : JSON.parse(statedJson));
+    }, [clientRef, statedJson]);
     usePageToolWarnings(iface.tools.page, options.pageTools);
     return {
         handle: iface.identity.handle,

package/components/live/use-live-session-client.js

@@ -53,6 +53,7 @@ export function useLiveSessionClient(bindings) {
         const client = new LiveSessionClient({
             ...connection,
             slots: b.slots,
+            stated: b.stated,
             context: b.context,
             voiceIngress: b.voiceAvailable,
             onConnectPhase: (phase) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.4-next.677.g14b70fe",
+  "version": "0.3.4-next.693.g4ab1526",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -60,8 +60,8 @@
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.4-next.677.g14b70fe",
-    "@theoremjs/web": "^0.3.4-next.677.g14b70fe"
+    "@theoremjs/agents": "^0.3.4-next.693.g4ab1526",
+    "@theoremjs/web": "^0.3.4-next.693.g4ab1526"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/ui/LiveRunner.js

@@ -38,9 +38,9 @@ const WAVE_HEIGHT = 320;
 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, }) {
+function LiveRunnerBody({ iface, connection, trace, slots, stated, context, pageTools, }) {
     const t = useLabels();
-    const model = useLiveRunnerModel(iface, connection, { slots, context, pageTools });
+    const model = useLiveRunnerModel(iface, connection, { slots, stated, 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);

package/ui/TheoremChat.d.ts

@@ -1,6 +1,6 @@
 import type { DefinedTheme } from '@astryxdesign/core/theme';
 import { type ComposerPendingMessage } from '@theoremjs/agents/interface';
-import type { ChatController, PageTools } from '@theoremjs/web/client';
+import type { ChatController, PageTools, StatedTurn } from '@theoremjs/web/client';
 import { type ConversationView, type HttpTransportOptions, type TheoremTransport } from '@theoremjs/web/client';
 import { type ReactNode, type Ref } from 'react';
 import { type SendTextOptions, type SentTurn, type UseTheoremChatOptions } from '../hooks/use-theorem-chat.ts';
@@ -35,6 +35,8 @@ export type TheoremChatProps = {
     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;
+    /** Which prompt lines each turn gets, for a host that lets its page choose (`pageStatesTurn`). */
+    stated?: StatedTurn;
     /**
      * 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`.
@@ -48,7 +50,7 @@ export type TheoremChatProps = {
     /** 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. */
+    /** Shown above the centred composer before the first message. Default: the agent's handle and a prompt; `null` shows nothing. */
     emptyState?: ReactNode;
     density?: 'compact' | 'balanced' | 'spacious';
     /**

package/ui/TheoremChat.js

@@ -51,7 +51,7 @@ function ChatComposerForChat({ chat, iface, placeholder, inputRef, }) {
                 void chat.handleSendNow(message);
         } }));
 }
-function ChatBody({ transport, iface, placeholder, emptyState, density, maxWidth = DEFAULT_CHAT_MAX_WIDTH, scrollRef, trace, usage, className, style, conversation, conversationView, initialText, initialFiles, initialVoice, initialPending, onConversationChange, chatRef, composer: hasComposer = true, slots, onSlotsChange, context, pageTools, onTurnEvent, }) {
+function ChatBody({ transport, iface, placeholder, emptyState, density, maxWidth = DEFAULT_CHAT_MAX_WIDTH, scrollRef, trace, usage, className, style, conversation, conversationView, initialText, initialFiles, initialVoice, initialPending, onConversationChange, chatRef, composer: hasComposer = true, slots, onSlotsChange, stated, context, pageTools, onTurnEvent, }) {
     const t = useLabels();
     const chat = useTheoremChat({
         transport,
@@ -65,6 +65,7 @@ function ChatBody({ transport, iface, placeholder, emptyState, density, maxWidth
         onConversationChange,
         slots,
         onSlotsChange,
+        stated,
         context,
         pageTools,
         onTurnEvent,
@@ -97,7 +98,7 @@ const CHAT_SCROLL = { overscrollBehavior: 'none' };
  */
 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 }))] }));
+    return (_jsxs(VStack, { minHeight: "100%", vAlign: "center", gap: 8, paddingInline: 3, children: [_jsx(ChatColumn, { maxWidth: maxWidth, children: emptyState === undefined ? (_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') })] })) : (emptyState) }), 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.
@@ -105,15 +106,15 @@ function ChatLanding({ composer, composerRef, maxWidth, handle, emptyState, }) {
  * 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, 
-            // why: Scrolling past either end does not bounce the transcript and its docked composer.
-            style: CHAT_SCROLL, 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);
-                    } }) }) }) }));
+    return (_jsxs(VStack, { height: "100%", children: [_jsx("style", { href: "theorem-chat-thread", precedence: "default", children: '.theorem-chat-thread > :last-child > div:empty { display: none; }' }), _jsx(ChatLayout, { className: "theorem-chat-thread", density: density, scrollRef: scrollRef, 
+                // why: Scrolling past either end does not bounce the transcript and its docked composer.
+                style: CHAT_SCROLL, 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();