@theoremjs/react 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ORCHID AI LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,247 @@
-# Temporary Holding Version
+# `@theoremjs/react`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React projection of the headless interface (`@theoremjs/agents/interface`) — runners, transcript, composer, live stage.
+
+## Install
+
+```bash
+npm install @theoremjs/react @theoremjs/agents zod react react-dom
+# for the chat and live UI (`/ui`, `/live`):
+npm install @astryxdesign/core@0.6.3 @stylexjs/stylex@0.19.0
+# only to build your own theme from the Theorem one (`/ui/theme`):
+npm install @astryxdesign/theme-neutral@0.6.3
+```
+
+Published to npm only: the package ships built JavaScript, declarations and
+stylesheets. `@theoremjs/agents` is a peer, so the host and the UI share one
+kernel. The Astryx peers are optional: the hooks, client and server entry
+points run without them. The declarations need TypeScript 5.7 or later.
+
+`@theoremjs/react/ui` and `@theoremjs/react/live` import their stylesheets
+themselves, so a bundler that handles CSS imports (Vite does) needs no extra
+step. The theme's type is Figtree with a system-font fallback;
+the package does not ship the font, so load it yourself if you want it.
+
+The live UI loads its microphone worklet as an asset
+(`new URL('./worklets/mic-capture.js', import.meta.url)`); Vite ships it
+without configuration, and any bundler that resolves that pattern does too.
+
+No Svelte. The playground site (`theoremai-frontend`) hosts a thin Vite SPA at `apps/run` that imports this package; the info-site graph stays Svelte and only writes a `PlaygroundRunPayload` handoff.
+
+## Imports
+
+```ts
+import { useTheoremChat, useTheoremInterface } from '@theoremjs/react'; // headless hooks + transport
+import { TheoremChat } from '@theoremjs/react/ui'; // Astryx chat UI
+import { LiveRunner } from '@theoremjs/react/live'; // Astryx voice / video UI
+import { createTheoremHandler } from '@theoremjs/react/server'; // host side
+```
+
+A `host` profile runs no model: the page calls its tools directly. Serve it
+with `createTheoremHostHandler({ profile })` and render `<TheoremHost
+endpoint="/api/host" />` (`createHostTransport` and `useTheoremHost` for a UI
+of your own). `GET` describes each allowed tool with its input and output JSON
+Schema, never its endpoint or credentials; `POST /call` `{ name, input }`
+streams the call's events, and `POST /invoke` answers a gate it paused on, as
+in chat. The console draws the form from the input schema and lays the result
+out from its value: figures, charts, tables, images, audio and Markdown, with
+the raw JSON beside them.
+
+The playground's run-tab handoff (`savePlaygroundRunPayload`,
+`readPlaygroundRunIdFromUrl`, …) lives in `@theoremjs/playground`; see
+[`playground/README.md`](../playground/README.md).
+
+## The wire
+
+Turn lines, live envelopes, request bodies, live messages and the profile
+interface `describe` returns are each checked against their schema, both ways:
+
+- **Browser → host.** `createTheoremHandler` reads `/turn`, `/invoke` and
+  `/steer` bodies with `theoremTurnRequestSchema`, `theoremInvokeRequestSchema`
+  and `theoremSteerRequestSchema`; a missing or malformed field is a `request`
+  error (400). `/invoke` answers a paused call by its `gateId` with a
+  `decision`: `approve` (with `input` when the user edited it, `secret` at a
+  sign-in gate) or `deny`; the host settles each one. An answer whose request
+  ends before its call settles (the network drops, the host fails) puts the
+  call back to wait, to be answered again; once it settled, the session keeps
+  the settle (`TheoremSessionState.settled`, pruned with the gates): a second
+  answer is refused with `session.gate_expired`, and a walk-away naming the
+  call reads its result. A message sent while
+  its reply waits walks away in its own `/turn`: `abandon` names the waiting
+  calls, its history leaves exactly those open, and the host settles each
+  cancelled ahead of the message's reply (`checkWalkAway` and `walkAway` for a
+  host with routes of its own). A relay reads the live client's messages with
+  `parseLiveClientMessage`. A host with routes of its own reads a body with
+  `checkRequest(schema, body, what)`, and answers a paused call with
+  `answerGatedCall` (`@theoremjs/agents/kernel`), the rule the handler uses.
+- **Host → browser.** `describe` returns the profile interface as
+  `profileInterfaceSchema` names it: tool ids, never a tool's definition, and
+  no host functions. The transport and the live client read each line or
+  envelope against its kind's schema, and `describe` against
+  `profileInterfaceSchema`. A kind the client does not know reaches
+  the event handler as `unsupported`, and one that fails its check (not JSON,
+  no kind, or a known kind that fails its schema) as `malformed`: a
+  `bad_response` naming what broke, never the value. Either way the reply or
+  call goes on without it. The chat names a skipped part in the composer and
+  the live call in its failure banner, both with the lexicon's
+  `session.part_skipped`; a run built on `streamInterfaceTurn` hears of it
+  through its `view.skipped`. A `describe` reply that fails its schema is
+  `bad_response`.
+
+## Local layout
+
+```text
+Development/
+  theoremai/           # kernel + this package
+    react/
+  theoremai-frontend/  # site; apps/run consumes file:../../../theoremai/react
+```
+
+## Tool credentials
+
+Tool credentials live on the server, never in the browser. `createTheoremHandler`
+keeps them in a `credentialStore` keyed by session id (default: process memory;
+use a vault or an encrypted row in production) and loads them into every turn
+and every resumed call.
+
+- **Typed keys** — at a bearer or API-key gate, the user types the key into the
+  gate card. It goes up once as `secret` on the resume request, and the server
+  saves it under the gate's slot; the card keeps no copy and no event carries it.
+  The server decides the credential's kind and header from the tool, not the
+  request.
+- **OAuth** — pass `authorizationUrl`: begin the flow with `createOAuthPkceFlow`,
+  binding it to the `sessionId` you're given, and return its URL; the gate card
+  opens it in a popup. Your callback route exchanges the code, saves the
+  credential under that session, then its page calls `notifyOAuthComplete(slot)`.
+  The card takes that message only from its own popup and origin, and resumes the
+  gate with its id alone.
+- **Refresh** — a refreshed OAuth token is saved to the store before the call
+  goes on, so a rotated refresh token is never lost.
+
+```ts
+const credentialStore = createMemoryCredentialStore();
+const secret = secrets.oauthStateSecret;
+const redirectUri = 'https://app.example/oauth/callback';
+
+export const theorem = createTheoremHandler({
+	profile,
+	provider,
+	credentialStore,
+	authorizationUrl: async (challenge, { sessionId }) =>
+		(
+			await createOAuthPkceFlow({
+				resourceServerUrl: challenge.resource ?? 'https://api.tracker.example',
+				clientId: 'https://app.example/oauth/client.json',
+				redirectUri,
+				scopes: challenge.requiredScopes,
+				signingSecret: secret,
+				sessionBinding: sessionId,
+			})
+		).authorizationUrl,
+});
+
+// The callback route: the handler's session cookie comes with the redirect.
+export async function oauthCallback(request: Request): Promise<Response> {
+	const sessionId = theoremSessionId(request);
+	if (!sessionId) return new Response(null, { status: 401 });
+	const params = new URL(request.url).searchParams;
+	const { credential } = await exchangeOAuthPkce({
+		code: params.get('code') ?? '',
+		state: params.get('state') ?? '',
+		iss: params.get('iss') ?? undefined,
+		redirectUri,
+		signingSecret: secret,
+		sessionBinding: sessionId,
+	});
+	const saved = (await credentialStore.load(sessionId)) ?? {};
+	await credentialStore.save(sessionId, { ...saved, tracker: credential });
+	// That page runs `notifyOAuthComplete('tracker')` from `@theoremjs/react`.
+	return Response.redirect(new URL('/oauth/done?slot=tracker', request.url), 303);
+}
+```
+
+A host with its own `session` resolver passes its own session id instead of
+`theoremSessionId`. For voice, the relay you host receives a typed key as `secret`
+on the `executeTool` message: save it with `credentialFromTypedSecret` (from
+`@theoremjs/agents/kernel`) under the gate's slot, and pass a
+`ToolCredentialSource` over your store as `credentials` on every `executeTool`.
+
+## Composer pending intents
+
+`src/interface/` owns stash / queue / steer list ops and the action matrix.
+This package wires AbortSignal, the pending bar, and playground turn/steer HTTP.
+
+| Phase | Empty composer | Filled composer |
+| --- | --- | --- |
+| idle | disabled | Send (+ Stash menu) |
+| streaming | Stop | Queue (+ Steer / Send now / Stash) |
+| gated | disabled | Queue (+ Send now / Stash; no Steer) |
+
+Enter matches the primary action. No keyboard shortcuts for stash/steer.
+
+Send now while gated walks away from every waiting gate in the message's own request
+(`walkAway` on `streamInterfaceDraftTurn`): the host settles each call cancelled, the
+paused reply commits, and the message's reply follows in the same stream. The message
+leaves the composer only once it posts; if the request fails first, the reply still waits.
+An answer at a gate that fails before its call settles leaves the gate to answer again,
+the failure in the composer; one that fails after keeps the call's result. The gate cards
+show the answer on its way from their owner (`useTheoremChat().answering`, passed as
+`ChatTranscript`'s `answering`, `ApprovalCard`'s `decided`, `AuthChallengeCard`'s
+`submitted`), so a failed answer brings the gate's actions back. Steer POSTs use the Cache API
+on Cloudflare (process Map locally) so mid-turn injects work across isolates.
+Live sessions key the same inbox by `sessionId` from relay `ready`.
+
+A chat can be kept and resumed: `onChatChange` (or `useTheoremChat`'s `onChange`) reports the
+`{ blocks, session }` each time the conversation comes to rest (a turn finished, a message
+added or removed; never while a reply streams or waits on a gate), and `initialChat` (`initial`)
+resumes from one, the session carrying what the next turn is sent with. `chatRef` (`sendText`
+on the hook) sends a message as the composer would and resolves with the blocks the turn added
+once its reply is done, or `null` while a reply streams or waits on a gate.
+
+Pending rows show attachment / voice previews, text, **Queue** (stash → queue),
+and **Send now**. Clicking the text restores the full draft (text + files + voice)
+into the composer; if the composer already had a payload, that payload is re-stashed.
+
+## Wording
+
+The headless layer (hooks, client, components, server handler) writes no
+English. It hands the builder kinds, codes, and states:
+
+- Failures are `ClientFailure` (`{ error, errorKind, errorInternal? }`). `error`
+  is the profile's wording (`iface.lexicon`, resolved on the host); show it to
+  the user. `errorKind` and `errorInternal` are for the builder.
+- Attachment problems are `AttachmentValidationIssue`s; word one with
+  `attachmentIssueText(issue, iface.lexicon)` from `@theoremjs/agents`.
+- A Live call the provider ended after warning it would is not a failure:
+  `LiveSessionClient`'s `onSessionEnded(session)` gives `session.message`, the
+  profile's `live.session_ended` wording, and `session.ended` (close code,
+  timing, the code's kind) for the builder.
+- Chrome is semantic: `liveState`, `workStatus`, drawer `parts`, hint `id`.
+
+`@theoremjs/react/ui` is the default UI. Every line it shows is an Astryx i18n
+message: Theorem's under `@theorem.*` keys (`THEOREM_UI_CATALOG`, each with a
+description and the ICU values it takes), Astryx's own under `@astryx.*`. The
+builder owns all of them; `labels` replaces any line, per locale:
+
+```tsx
+<TheoremChat
+  labels={{
+    en: {
+      '@theorem.chat.greeting': 'What shall we plan?',
+      '@theorem.composer.placeholder': 'Write to @{handle}',
+      '@astryx.chatSendButton.send': 'Go',
+    },
+    de: { '@theorem.chat.greeting': 'Woran arbeiten wir?' },
+  }}
+/>
+```
+
+`LiveRunner` takes the same prop. The locale is the host's Astryx
+`InternationalizationProvider` locale (`en` without one); a host's own Astryx
+`messages` and `overrides` also apply, and win over the defaults. Labels are
+checked on mount: an unknown `@theorem.*` key, a message that is not valid ICU,
+a value the line is not given, or a key outside `@theorem.*` / `@astryx.*`
+throws, naming the locale and key. Label values render as text, never HTML.
+
+A builder with their own UI replaces all of it.
+`scripts/docs-truth/copy-lint.mjs` keeps prose out of the headless directories.

package/client/attachment-hover-preview.d.ts

@@ -0,0 +1,11 @@
+/** Hover-card geometry for composer attachment pills (model-sculpt agent_chat parity). */
+export type AttachPreviewStyle = {
+    left: number;
+    top?: number;
+    bottom?: number;
+};
+export declare function formatAttachmentSize(bytes?: number): string;
+export declare function resolveAttachPreviewStyle(anchor: Pick<DOMRect, 'left' | 'top' | 'bottom'>, viewport?: {
+    width: number;
+    height: number;
+}): AttachPreviewStyle;

package/client/attachment-hover-preview.js

@@ -0,0 +1,36 @@
+/** Hover-card geometry for composer attachment pills (model-sculpt agent_chat parity). */
+const ATTACH_PREVIEW_WIDTH_PX = 240;
+const ATTACH_PREVIEW_OFFSET_PX = 6;
+const ATTACH_PREVIEW_VIEWPORT_PAD_PX = 8;
+/** Prefer anchoring above the chip when this much space exists. */
+const ATTACH_PREVIEW_ABOVE_THRESHOLD_PX = 190;
+export function formatAttachmentSize(bytes) {
+    if (!bytes || bytes <= 0)
+        return '';
+    if (bytes < 1024)
+        return `${String(bytes)} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function clampAttachPreviewLeft(anchorLeft, viewportWidth) {
+    const maxLeft = Math.max(ATTACH_PREVIEW_VIEWPORT_PAD_PX, viewportWidth - ATTACH_PREVIEW_WIDTH_PX - ATTACH_PREVIEW_VIEWPORT_PAD_PX);
+    return Math.min(Math.max(ATTACH_PREVIEW_VIEWPORT_PAD_PX, anchorLeft), maxLeft);
+}
+export function resolveAttachPreviewStyle(anchor, viewport = {
+    width: globalThis.innerWidth ?? 0,
+    height: globalThis.innerHeight ?? 0,
+}) {
+    const left = clampAttachPreviewLeft(anchor.left, viewport.width);
+    const hasRoomAbove = anchor.top > ATTACH_PREVIEW_ABOVE_THRESHOLD_PX;
+    if (hasRoomAbove) {
+        return {
+            left,
+            bottom: Math.max(ATTACH_PREVIEW_VIEWPORT_PAD_PX, viewport.height - anchor.top + ATTACH_PREVIEW_OFFSET_PX),
+        };
+    }
+    return {
+        left,
+        top: Math.min(viewport.height - ATTACH_PREVIEW_VIEWPORT_PAD_PX, anchor.bottom + ATTACH_PREVIEW_OFFSET_PX),
+    };
+}

package/client/audio-level.d.ts

@@ -0,0 +1,5 @@
+/** Shared mic RMS → waveform level scaling for live and turn-composer paths. */
+export declare const INPUT_LEVEL_GAIN = 4;
+export declare function float32Rms(samples: Float32Array): number;
+export declare function float32RmsToLevel(samples: Float32Array): number;
+export declare function timeDomainBytesToLevel(samples: Uint8Array<ArrayBufferLike>): number;

package/client/audio-level.js

@@ -0,0 +1,24 @@
+/** Shared mic RMS → waveform level scaling for live and turn-composer paths. */
+export const INPUT_LEVEL_GAIN = 4;
+export function float32Rms(samples) {
+    let sum = 0;
+    for (const sample of samples) {
+        sum += sample * sample;
+    }
+    if (samples.length === 0)
+        return 0;
+    return Math.sqrt(sum / samples.length);
+}
+export function float32RmsToLevel(samples) {
+    return Math.min(1, float32Rms(samples) * INPUT_LEVEL_GAIN);
+}
+export function timeDomainBytesToLevel(samples) {
+    let sum = 0;
+    for (const sample of samples) {
+        const normalized = (sample - 128) / 128;
+        sum += normalized * normalized;
+    }
+    if (samples.length === 0)
+        return 0;
+    return Math.min(1, Math.sqrt(sum / samples.length) * INPUT_LEVEL_GAIN);
+}

package/client/composer-attachments.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stage file picks against profile `maxFiles` (shared with voice). Excess
+ * incoming files are dropped; the limit hit is an issue the caller words
+ * (`attachmentIssueText`).
+ */
+import type { AttachmentValidationIssue } from '@theoremjs/agents/interface';
+export type StageComposerFilesArgs = {
+    existing: readonly File[];
+    incoming: readonly File[];
+    /** Profile `inputs.maxFiles`. When omitted, no cap. */
+    maxFiles?: number;
+    /** Staged voice notes that share the same maxFiles budget. */
+    voiceCount?: number;
+};
+export type StageComposerFilesResult = {
+    files: File[];
+    dropped: number;
+    /** `too_many_files` when the cap dropped a file. */
+    issues: AttachmentValidationIssue[];
+};
+/** Append `incoming` to `existing`, dropping overflow past maxFiles − voice. */
+export declare function stageComposerFiles(args: StageComposerFilesArgs): StageComposerFilesResult;
+/**
+ * Whether a new voice note fits under maxFiles.
+ * Recording clears any prior staged voice first, so only `fileCount` matters.
+ */
+export declare function canStageVoice(args: {
+    fileCount: number;
+    maxFiles?: number;
+}): boolean;

package/client/composer-attachments.js

@@ -0,0 +1,33 @@
+/**
+ * Stage file picks against profile `maxFiles` (shared with voice). Excess
+ * incoming files are dropped; the limit hit is an issue the caller words
+ * (`attachmentIssueText`).
+ */
+/** Append `incoming` to `existing`, dropping overflow past maxFiles − voice. */
+export function stageComposerFiles(args) {
+    const { existing, incoming, maxFiles } = args;
+    const voiceCount = Math.max(0, args.voiceCount ?? 0);
+    if (maxFiles === undefined || !Number.isFinite(maxFiles) || maxFiles < 0) {
+        return { files: [...existing, ...incoming], dropped: 0, issues: [] };
+    }
+    const room = Math.max(0, maxFiles - voiceCount - existing.length);
+    if (incoming.length <= room) {
+        return { files: [...existing, ...incoming], dropped: 0, issues: [] };
+    }
+    const kept = room === 0 ? [] : incoming.slice(0, room);
+    return {
+        files: [...existing, ...kept],
+        dropped: incoming.length - kept.length,
+        issues: [{ code: 'too_many_files', params: { maxFiles } }],
+    };
+}
+/**
+ * Whether a new voice note fits under maxFiles.
+ * Recording clears any prior staged voice first, so only `fileCount` matters.
+ */
+export function canStageVoice(args) {
+    const maxFiles = args.maxFiles;
+    if (maxFiles === undefined || !Number.isFinite(maxFiles))
+        return true;
+    return args.fileCount < maxFiles;
+}

package/client/composer-drawer.d.ts

@@ -0,0 +1,19 @@
+import type { ComposerPendingMessage } from '@theoremjs/agents/interface';
+/** What waits in the composer, by kind; the UI words each kind. */
+export type ComposerDrawerKind = 'steer' | 'queue' | 'stash' | 'attached';
+/** Collapsed-drawer header: the total, then each waiting kind's count, in display order. */
+export type ComposerDrawerSummary = {
+    count: number;
+    parts: {
+        kind: ComposerDrawerKind;
+        n: number;
+    }[];
+};
+/**
+ * What's waiting in the composer, by kind: steering, queued, stashed, attached
+ * (files and voice notes). Null when nothing waits.
+ */
+export declare function composerDrawerSummary(args: {
+    pendingMessages: readonly Pick<ComposerPendingMessage, 'kind'>[];
+    attachmentCount: number;
+}): ComposerDrawerSummary | null;

package/client/composer-drawer.js

@@ -0,0 +1,15 @@
+/**
+ * What's waiting in the composer, by kind: steering, queued, stashed, attached
+ * (files and voice notes). Null when nothing waits.
+ */
+export function composerDrawerSummary(args) {
+    const countOf = (kind) => args.pendingMessages.filter((message) => message.kind === kind).length;
+    const parts = [
+        { kind: 'steer', n: countOf('steer') },
+        { kind: 'queue', n: countOf('queue') },
+        { kind: 'stash', n: countOf('stash') },
+        { kind: 'attached', n: args.attachmentCount },
+    ].filter((part) => part.n > 0);
+    const count = parts.reduce((sum, part) => sum + part.n, 0);
+    return count === 0 ? null : { count, parts };
+}

package/client/composer-hints.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Composer hints — ephemeral guidance about the current composer interaction
+ * (not pending-message state). Mirrors seance's `stash-selected-draft` hint.
+ */
+/** Stash shortcut in Astryx `Kbd` notation (`mod` is ⌘ on macOS, Ctrl elsewhere). */
+export declare const STASH_SHORTCUT = "mod+shift+s";
+/** Which hint applies, and its shortcut; the UI words it. */
+export type ComposerHint = {
+    id: 'stash-selected-draft';
+    shortcut: string;
+};
+/** Whether a keydown is the stash shortcut (⌘⇧S / Ctrl+Shift+S). */
+export declare function isStashShortcut(event: {
+    code: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+}): boolean;
+/** The stash hint — shown while the whole draft is selected in the focused input and it can be stashed. */
+export declare function resolveComposerHint(args: {
+    draftText: string;
+    selectedText: string;
+    canStash: boolean;
+}): ComposerHint | null;

package/client/composer-hints.js

@@ -0,0 +1,20 @@
+/**
+ * Composer hints — ephemeral guidance about the current composer interaction
+ * (not pending-message state). Mirrors seance's `stash-selected-draft` hint.
+ */
+/** Stash shortcut in Astryx `Kbd` notation (`mod` is ⌘ on macOS, Ctrl elsewhere). */
+export const STASH_SHORTCUT = 'mod+shift+s';
+/** Whether a keydown is the stash shortcut (⌘⇧S / Ctrl+Shift+S). */
+export function isStashShortcut(event) {
+    return event.code === 'KeyS' && event.shiftKey && !event.altKey && (event.metaKey || event.ctrlKey);
+}
+/** The stash hint — shown while the whole draft is selected in the focused input and it can be stashed. */
+export function resolveComposerHint(args) {
+    const draft = args.draftText.trim();
+    if (!args.canStash || !draft || args.selectedText.trim() !== draft)
+        return null;
+    return {
+        id: 'stash-selected-draft',
+        shortcut: STASH_SHORTCUT,
+    };
+}

package/client/composer-primary.d.ts

@@ -0,0 +1,16 @@
+import { type ComposerMenuAction, type ComposerPrimaryAction, type ComposerProfileInterface, type ComposerRunPhase } from '@theoremjs/agents/interface';
+export type ComposerActionState = {
+    primary: ComposerPrimaryAction;
+    menuActions: ComposerMenuAction[];
+    /** Send is off while recording, with nothing to act on, or with an empty draft to send or queue. */
+    primaryDisabled: boolean;
+};
+/** The composer's primary button and send menu for the current draft and run phase. */
+export declare function composerActionState(args: {
+    iface: ComposerProfileInterface;
+    phase: ComposerRunPhase;
+    draftText: string;
+    pendingFiles: readonly File[];
+    pendingVoice: readonly File[];
+    recording: boolean;
+}): ComposerActionState;

package/client/composer-primary.js

@@ -0,0 +1,25 @@
+import { resolveComposerMenuActions, resolveComposerPrimary, userDraftHasPayload, } from '@theoremjs/agents/interface';
+function fileSpecs(files) {
+    return files.map((file) => ({
+        name: file.name,
+        mimeType: file.type || 'application/octet-stream',
+        sizeBytes: file.size,
+    }));
+}
+/** The composer's primary button and send menu for the current draft and run phase. */
+export function composerActionState(args) {
+    const allowSteering = 'allowSteering' in args.iface && Boolean(args.iface.allowSteering);
+    const hasPayload = userDraftHasPayload({
+        ...(args.draftText.trim() ? { text: args.draftText } : {}),
+        ...(args.pendingFiles.length ? { attachments: fileSpecs(args.pendingFiles) } : {}),
+        ...(args.pendingVoice.length ? { voice: fileSpecs(args.pendingVoice) } : {}),
+    });
+    const context = { phase: args.phase, hasPayload, allowSteering };
+    const primary = resolveComposerPrimary(context);
+    const needsPayload = primary === 'send' || primary === 'queue';
+    return {
+        primary,
+        menuActions: resolveComposerMenuActions(context),
+        primaryDisabled: args.recording || primary === 'none' || (needsPayload && !hasPayload),
+    };
+}

package/client/decision-transport.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The browser side of a decision profile: what the host lets the page see of
+ * it, and the one call that asks its questions about some state.
+ *
+ * @module
+ */
+import { type DecisionJson, type DecisionProfile, type DecisionQuestion, type DecisionResult, type TraceRecord } from '@theoremjs/agents';
+import type { TraceFeed } from './trace-feed.ts';
+import { type HttpOptions } from './transport.ts';
+/** One question as the page sees it: its answer type and the names of its options or levels. Instructions stay on the host. */
+export type DecisionQuestionView = {
+    id: string;
+    type: DecisionQuestion['type'];
+    /** A choice's labels, a score's levels from 0 up; empty for a number. */
+    labels: string[];
+};
+/** What a decision profile shows the page. */
+export type DecisionInterface = {
+    type: 'decision';
+    identity: {
+        handle: string;
+    };
+    contract: string;
+    maxStateBytes?: number;
+    questions: DecisionQuestionView[];
+    observability?: {
+        record: boolean;
+    };
+};
+/** The page's view of a decision profile and the questions its host asks. */
+export declare function decisionInterface(profile: Pick<DecisionProfile, 'identity' | 'decision' | 'inputs' | 'observability'>, questions: Record<string, DecisionQuestion>): DecisionInterface;
+/** A decision's reply: the answers, and the trace records a host that delivers them sent back. */
+export type DecisionReply = {
+    result: DecisionResult;
+    traces?: TraceRecord[];
+};
+export interface DecisionTransport {
+    describe(signal?: AbortSignal): Promise<DecisionInterface>;
+    decide(state: Exclude<DecisionJson, null>, signal?: AbortSignal): Promise<DecisionReply>;
+    /** Where the host's trace records land, for the inspector. */
+    traces?: TraceFeed;
+}
+/** A host's decide reply, checked: the answers, and any trace records it delivers. */
+export declare function readDecisionReply(raw: unknown): DecisionReply;
+/** Transport for a host mounted with `createTheoremDecisionHandler`. Default endpoint `/api/decision`. */
+export declare function createDecisionTransport(options?: HttpOptions & {
+    endpoint?: string;
+}): DecisionTransport;