@theoremjs/react 0.0.0-stage → 0.3.1

package/components/use-composer-voice.js

@@ -0,0 +1,90 @@
+import { attachmentIssueText, describeError, labelText, } from '@theoremjs/agents';
+import { useCallback, useRef, useState } from 'react';
+import { canStageVoice } from "../client/composer-attachments.js";
+import { ComposerVoiceRecorder, isVoiceRecorderFailure, } from "../client/voice-recorder.js";
+function voiceFailure(err, fallback, labels) {
+    const code = isVoiceRecorderFailure(err) ? err.code : fallback;
+    const internal = describeError(err);
+    return {
+        code,
+        error: labelText(`voice.${code}`, {}, labels),
+        ...(internal && internal !== code ? { errorInternal: internal } : {}),
+    };
+}
+export function useComposerVoice(args) {
+    const [recording, setRecording] = useState(false);
+    const [inputLevel, setInputLevel] = useState(0);
+    const [failure, setFailure] = useState(null);
+    const recorderRef = useRef(null);
+    const onVoiceStagedRef = useRef(args.onVoiceStaged);
+    const onVoiceClearRef = useRef(args.onVoiceClear);
+    onVoiceStagedRef.current = args.onVoiceStaged;
+    onVoiceClearRef.current = args.onVoiceClear;
+    const ensureRecorder = useCallback(() => {
+        recorderRef.current ??= new ComposerVoiceRecorder(args.inputs.voice?.accept ?? [], (level) => {
+            setInputLevel(level);
+        });
+        return recorderRef.current;
+    }, [args.inputs.voice?.accept]);
+    const startRecording = useCallback(async () => {
+        setFailure(null);
+        const maxFiles = args.inputs.maxFiles;
+        if (!canStageVoice({ fileCount: args.pendingFiles.length, maxFiles })) {
+            setFailure({
+                code: 'too_many_files',
+                error: attachmentIssueText({ code: 'too_many_files', params: { maxFiles } }, args.labels),
+            });
+            return;
+        }
+        onVoiceClearRef.current?.();
+        try {
+            await ensureRecorder().start();
+            setRecording(true);
+        }
+        catch (err) {
+            setRecording(false);
+            setFailure(voiceFailure(err, 'unavailable', args.labels));
+        }
+    }, [args.inputs.maxFiles, args.labels, args.pendingFiles.length, ensureRecorder]);
+    const stopRecording = useCallback(async () => {
+        setFailure(null);
+        try {
+            const file = await ensureRecorder().stop();
+            setRecording(false);
+            setInputLevel(0);
+            onVoiceStagedRef.current?.(file);
+        }
+        catch (err) {
+            setRecording(false);
+            setInputLevel(0);
+            setFailure(voiceFailure(err, 'failed', args.labels));
+        }
+    }, [args.labels, ensureRecorder]);
+    const toggleRecording = useCallback(async () => {
+        if (recording) {
+            await stopRecording();
+            return;
+        }
+        await startRecording();
+    }, [recording, startRecording, stopRecording]);
+    const discardRecordingOrVoice = useCallback(() => {
+        if (recording) {
+            ensureRecorder().cancel();
+            setRecording(false);
+            setInputLevel(0);
+        }
+        onVoiceClearRef.current?.();
+    }, [ensureRecorder, recording]);
+    const disposeRecorder = useCallback(() => {
+        recorderRef.current?.dispose();
+    }, []);
+    return {
+        recording,
+        inputLevel,
+        failure,
+        setFailure,
+        toggleRecording,
+        discardRecordingOrVoice,
+        disposeRecorder,
+    };
+}

package/components/use-editor-selection.d.ts

@@ -0,0 +1,3 @@
+import { type RefObject } from 'react';
+/** Text currently selected inside `ref` (a contenteditable), or '' when the selection is elsewhere. */
+export declare function useEditorSelection(ref: RefObject<HTMLElement | null>): string;

package/components/use-editor-selection.js

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+/** Text currently selected inside `ref` (a contenteditable), or '' when the selection is elsewhere. */
+export function useEditorSelection(ref) {
+    const [selected, setSelected] = useState('');
+    useEffect(() => {
+        const read = () => {
+            const root = ref.current;
+            const selection = document.getSelection();
+            const inside = root &&
+                selection &&
+                selection.rangeCount > 0 &&
+                root.contains(selection.getRangeAt(0).commonAncestorContainer);
+            setSelected(inside ? selection.toString() : '');
+        };
+        document.addEventListener('selectionchange', read);
+        return () => document.removeEventListener('selectionchange', read);
+    }, [ref]);
+    return selected;
+}

package/components/use-voice-playback.d.ts

@@ -0,0 +1,17 @@
+import type { InkWaveLevels } from './InkWaveform.tsx';
+/**
+ * Click-to-play state for a voice note: an `<audio>` ref, whether it plays,
+ * and a gentle output level that drives the ink waveform while it does.
+ */
+export declare function useVoicePlayback(): {
+    playing: boolean;
+    levelsRef: import("react").RefObject<InkWaveLevels>;
+    toggle: () => Promise<void>;
+    audioProps: {
+        ref: import("react").RefObject<HTMLAudioElement | null>;
+        preload: "metadata";
+        onPlay: () => void;
+        onPause: () => void;
+        onEnded: () => void;
+    };
+};

package/components/use-voice-playback.js

@@ -0,0 +1,68 @@
+import { useEffect, useRef, useState } from 'react';
+/**
+ * Click-to-play state for a voice note: an `<audio>` ref, whether it plays,
+ * and a gentle output level that drives the ink waveform while it does.
+ */
+export function useVoicePlayback() {
+    const audioRef = useRef(null);
+    const [playing, setPlaying] = useState(false);
+    const playingRef = useRef(false);
+    const levelsRef = useRef({ input: 0, output: 0 });
+    const rafIdRef = useRef(0);
+    function stopMeter() {
+        cancelAnimationFrame(rafIdRef.current);
+        rafIdRef.current = 0;
+        levelsRef.current.output = 0;
+    }
+    function startMeter() {
+        stopMeter();
+        const tick = (time) => {
+            if (!playingRef.current)
+                return;
+            levelsRef.current.output = 0.28 + 0.22 * (0.5 + 0.5 * Math.sin(time * 0.008));
+            rafIdRef.current = requestAnimationFrame(tick);
+        };
+        rafIdRef.current = requestAnimationFrame(tick);
+    }
+    useEffect(() => {
+        return () => {
+            cancelAnimationFrame(rafIdRef.current);
+        };
+    }, []);
+    function settle(isPlaying) {
+        playingRef.current = isPlaying;
+        setPlaying(isPlaying);
+        if (isPlaying)
+            startMeter();
+        else
+            stopMeter();
+    }
+    async function toggle() {
+        const audio = audioRef.current;
+        if (!audio)
+            return;
+        if (!audio.paused) {
+            audio.pause();
+            return;
+        }
+        try {
+            await audio.play();
+        }
+        catch {
+            settle(false);
+        }
+    }
+    /** Spread onto the `<audio>` element. */
+    const audioProps = {
+        ref: audioRef,
+        preload: 'metadata',
+        onPlay: () => settle(true),
+        onPause: () => settle(false),
+        onEnded: () => {
+            settle(false);
+            if (audioRef.current)
+                audioRef.current.currentTime = 0;
+        },
+    };
+    return { playing, levelsRef, toggle, audioProps };
+}

package/hooks/use-described.d.ts

@@ -0,0 +1,12 @@
+import { type ClientFailure } from '../client/failure.ts';
+/**
+ * What a transport describes, read once per transport; a failure when it can't be read. A new
+ * transport keeps the last description up until it describes itself, so swapping one in (a
+ * recompiled profile) changes the page in place instead of blanking it to a spinner.
+ */
+export declare function useDescribed<T>(transport: {
+    describe: (signal?: AbortSignal) => Promise<T>;
+}): {
+    iface: T | null;
+    describeFailure: ClientFailure | null;
+};

package/hooks/use-described.js

@@ -0,0 +1,25 @@
+import { useEffect, useState } from 'react';
+import { clientFailure } from "../client/failure.js";
+/**
+ * What a transport describes, read once per transport; a failure when it can't be read. A new
+ * transport keeps the last description up until it describes itself, so swapping one in (a
+ * recompiled profile) changes the page in place instead of blanking it to a spinner.
+ */
+export function useDescribed(transport) {
+    const [description, setDescription] = useState(NOT_DESCRIBED);
+    useEffect(() => {
+        const controller = new AbortController();
+        transport.describe(controller.signal).then((described) => {
+            if (!controller.signal.aborted)
+                setDescription({ iface: described, describeFailure: null });
+        }, (err) => {
+            if (!controller.signal.aborted)
+                setDescription({ iface: null, describeFailure: clientFailure(err) });
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [transport]);
+    return description;
+}
+const NOT_DESCRIBED = { iface: null, describeFailure: null };

package/hooks/use-embedding-index.d.ts

@@ -0,0 +1,27 @@
+import type { EmbeddingInput, EmbeddingUsage } from '@theoremjs/agents';
+import type { EmbeddingInterface, EmbeddingTransport } from '../client/embedding-transport.ts';
+import { type OneCallState } from './use-one-call.ts';
+/** Documents embedded for search: each one's vector, in the order given. */
+export type EmbeddingIndex = {
+    inputs: readonly EmbeddingInput[];
+    vectors: readonly (readonly number[])[];
+    model: string;
+    usage?: EmbeddingUsage;
+    /** How many requests it took. */
+    requests: number;
+};
+/** How far an indexing has come, in requests. */
+export type IndexProgress = {
+    done: number;
+    total: number;
+};
+/**
+ * Documents embedded for search with `task: 'document'`, as many requests as
+ * the profile's limits need, one after another. A new index aborts the one
+ * still running; a request that fails stops it.
+ */
+export declare function useEmbeddingIndex(transport: EmbeddingTransport): OneCallState<'indexing', EmbeddingIndex> & {
+    progress: IndexProgress | null;
+    index: (inputs: readonly EmbeddingInput[], rules: EmbeddingInterface['inputs']) => Promise<void>;
+    cancel: () => void;
+};

package/hooks/use-embedding-index.js

@@ -0,0 +1,43 @@
+import { useState } from 'react';
+import { addUsage, embeddingBatches } from "../client/embedding-input.js";
+import { useOneCall } from "./use-one-call.js";
+async function indexWith(transport, signal, inputs, rules, onProgress) {
+    const batches = embeddingBatches(inputs, rules);
+    const vectors = [];
+    let model = '';
+    let usage;
+    onProgress({ done: 0, total: batches.length });
+    for (const [at, batch] of batches.entries()) {
+        const reply = await transport.embed(batch, { task: 'document' }, signal);
+        // why: Each request's records go to the trace as it lands, so a long index shows its calls one by one.
+        for (const record of reply.traces ?? [])
+            transport.traces?.push(record);
+        vectors.push(...reply.result.embeddings.map((vector) => vector.values));
+        model = reply.result.model;
+        usage = addUsage(usage, reply.result.usage);
+        onProgress({ done: at + 1, total: batches.length });
+    }
+    return {
+        result: {
+            inputs,
+            vectors,
+            model,
+            ...(usage ? { usage } : {}),
+            requests: batches.length,
+        },
+    };
+}
+/**
+ * Documents embedded for search with `task: 'document'`, as many requests as
+ * the profile's limits need, one after another. A new index aborts the one
+ * still running; a request that fails stops it.
+ */
+export function useEmbeddingIndex(transport) {
+    const [progress, setProgress] = useState(null);
+    const { call, ...run } = useOneCall(transport, 'indexing', indexWith);
+    return {
+        ...run,
+        progress: run.status === 'indexing' ? progress : null,
+        index: (inputs, rules) => call(inputs, rules, setProgress),
+    };
+}

package/hooks/use-one-call.d.ts

@@ -0,0 +1,31 @@
+import type { TraceRecord } from '@theoremjs/agents';
+import { type ClientFailure } from '../client/failure.ts';
+import type { TraceFeed } from '../client/trace-feed.ts';
+/** A profile that answers in one call: a decision or an embedding. */
+export type OneCallTransport = {
+    traces?: TraceFeed;
+};
+/** The last call's state: its result is kept while the next one runs and when it fails. */
+export type OneCallState<Busy extends string, Result> = {
+    status: 'idle' | Busy | 'done' | 'error';
+    result: Result | null;
+    /** How long the last call took, round trip, in milliseconds. */
+    elapsedMs: number | null;
+    /** When the call now running began, as `Date.now()`; null while none runs. */
+    startedAt: number | null;
+    failure: ClientFailure | null;
+};
+/**
+ * One call at a time to `transport`, through `send`: a new call aborts the one
+ * still running, and the last result stays on screen while the next one runs.
+ * A new transport (a recompiled profile) keeps the result and any call still
+ * running, as a chat keeps its transcript; give the component a new `key` to
+ * start over. `send` must not change between renders.
+ */
+export declare function useOneCall<T extends OneCallTransport, Busy extends string, Args extends unknown[], Result>(transport: T, busy: Busy, send: (transport: T, signal: AbortSignal, ...args: Args) => Promise<{
+    result: Result;
+    traces?: readonly TraceRecord[];
+}>): OneCallState<Busy, Result> & {
+    call: (...args: Args) => Promise<void>;
+    cancel: () => void;
+};

package/hooks/use-one-call.js

@@ -0,0 +1,76 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { failedTraces } from "../client/decision-transport.js";
+import { clientFailure } from "../client/failure.js";
+const IDLE = {
+    status: 'idle',
+    result: null,
+    elapsedMs: null,
+    startedAt: null,
+    failure: null,
+};
+/** Hands a call's trace records to the transport's feed, when it has one. */
+function feed(transport, records) {
+    for (const record of records ?? [])
+        transport.traces?.push(record);
+}
+/**
+ * One call at a time to `transport`, through `send`: a new call aborts the one
+ * still running, and the last result stays on screen while the next one runs.
+ * A new transport (a recompiled profile) keeps the result and any call still
+ * running, as a chat keeps its transcript; give the component a new `key` to
+ * start over. `send` must not change between renders.
+ */
+export function useOneCall(transport, busy, send) {
+    const [run, setRun] = useState(IDLE);
+    const running = useRef(null);
+    useEffect(() => () => running.current?.abort(), []);
+    const cancel = useCallback(() => {
+        running.current?.abort();
+        running.current = null;
+        setRun((previous) => previous.status === busy
+            ? { ...previous, status: previous.result ? 'done' : 'idle', startedAt: null }
+            : previous);
+    }, [busy]);
+    const call = useCallback(async (...args) => {
+        running.current?.abort();
+        const controller = new AbortController();
+        running.current = controller;
+        setRun((previous) => ({
+            status: busy,
+            result: previous.result,
+            elapsedMs: previous.elapsedMs,
+            startedAt: Date.now(),
+            failure: null,
+        }));
+        const started = performance.now();
+        try {
+            const reply = await send(transport, controller.signal, ...args);
+            if (controller.signal.aborted)
+                return;
+            feed(transport, reply.traces);
+            setRun({
+                status: 'done',
+                result: reply.result,
+                elapsedMs: performance.now() - started,
+                startedAt: null,
+                failure: null,
+            });
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return;
+            feed(transport, failedTraces(err));
+            setRun((previous) => ({
+                ...previous,
+                status: 'error',
+                startedAt: null,
+                failure: clientFailure(err),
+            }));
+        }
+        finally {
+            if (running.current === controller)
+                running.current = null;
+        }
+    }, [transport, busy, send]);
+    return { ...run, call, cancel };
+}

package/hooks/use-page-tool-warnings.d.ts

@@ -0,0 +1,6 @@
+import { type PageTools } from '../client/live/live-page-tool.ts';
+/**
+ * Says in the console, once, where the page's tools and the profile's disagree. A wrong name is
+ * the builder's to fix, so it is never said to the visitor.
+ */
+export declare function usePageToolWarnings(declared: readonly string[] | undefined, pageTools: PageTools | undefined): void;

package/hooks/use-page-tool-warnings.js

@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+import { pageToolMismatch } from "../client/live/live-page-tool.js";
+/**
+ * Says in the console, once, where the page's tools and the profile's disagree. A wrong name is
+ * the builder's to fix, so it is never said to the visitor.
+ */
+export function usePageToolWarnings(declared, pageTools) {
+    const handled = Object.keys(pageTools ?? {})
+        .sort()
+        .join('\n');
+    const named = declared?.join('\n');
+    useEffect(() => {
+        if (named === undefined)
+            return;
+        const { unanswered, unused } = pageToolMismatch(named ? named.split('\n') : [], handled ? handled.split('\n') : []);
+        for (const name of unanswered) {
+            // labels-exempt: builder diagnostic
+            console.warn(`Theorem: page tool '${name}' has no handler in pageTools; the agent gets no answer.`);
+        }
+        for (const name of unused) {
+            // labels-exempt: builder diagnostic
+            console.warn(`Theorem: pageTools has '${name}', which the profile does not declare answeredBy: 'page'.`);
+        }
+    }, [named, handled]);
+}

package/hooks/use-second-ticker.d.ts

@@ -0,0 +1,2 @@
+/** `Date.now()`, refreshed every second while `active`. */
+export declare function useSecondTicker(active: boolean): number;

package/hooks/use-second-ticker.js

@@ -0,0 +1,13 @@
+import { useEffect, useState } from 'react';
+/** `Date.now()`, refreshed every second while `active`. */
+export function useSecondTicker(active) {
+    const [now, setNow] = useState(() => Date.now());
+    useEffect(() => {
+        if (!active)
+            return;
+        setNow(Date.now());
+        const timer = globalThis.setInterval(() => setNow(Date.now()), 1_000);
+        return () => globalThis.clearInterval(timer);
+    }, [active]);
+    return now;
+}

package/hooks/use-theorem-chat-actions.d.ts

@@ -0,0 +1,79 @@
+import type { AttachmentValidationIssue, ComposerMenuAction, ComposerPendingMessage, ComposerProfileInterface, ComposerRunPhase, InterfaceTurnSession, TranscriptBlock } from '@theoremjs/agents/interface';
+import { type MutableRefObject } from 'react';
+import { type ClientFailure } from '../client/failure.ts';
+import { type AnsweringGate, type StreamView, type ToolDecisionAction, type ToolGateResolution } from '../client/index.ts';
+import type { RunOutcome } from '../client/run-session.ts';
+import type { TheoremTransport } from '../client/transport.ts';
+import type { MessageDelivery } from './use-theorem-chat-state.ts';
+export type RunTurnStream = (run: (view: StreamView) => Promise<RunOutcome>, options?: {
+    /** The run sends a message: one that never posts goes back in the composer with its failure. */
+    message?: {
+        restore(): Promise<void>;
+    };
+}) => Promise<void>;
+export type TheoremChatActionArgs = {
+    iface: ComposerProfileInterface | null;
+    transport: TheoremTransport;
+    phase: ComposerRunPhase;
+    gated: boolean;
+    draftText: string;
+    pendingFiles: File[];
+    pendingVoice: File[];
+    /** The composer as it is now, for a run that ends after it changed. */
+    composerRef: MutableRefObject<{
+        draftText: string;
+        pendingFiles: File[];
+        pendingVoice: File[];
+    }>;
+    /** The ref of the conversation the chat continues; none before its first message posts. */
+    conversationRef: MutableRefObject<string | undefined>;
+    clearComposer: () => void;
+    runTurnStream: RunTurnStream;
+    sessionRef: MutableRefObject<InterfaceTurnSession>;
+    blocksRef: MutableRefObject<TranscriptBlock[]>;
+    abortRef: MutableRefObject<AbortController | null>;
+    turnIdRef: MutableRefObject<string | null>;
+    busyRef: MutableRefObject<boolean>;
+    runPromiseRef: MutableRefObject<Promise<void> | null>;
+    allowQueueDrainRef: MutableRefObject<boolean>;
+    setBlocks: (value: TranscriptBlock[] | ((prev: TranscriptBlock[]) => TranscriptBlock[])) => void;
+    setStreamBlocks: (value: TranscriptBlock[]) => void;
+    setSession: (value: InterfaceTurnSession) => void;
+    setChatStarted: (value: boolean) => void;
+    setStreaming: (value: boolean) => void;
+    setPendingMessages: (value: ComposerPendingMessage[] | ((prev: ComposerPendingMessage[]) => ComposerPendingMessage[])) => void;
+    setDraftText: (value: string) => void;
+    setPendingFiles: (value: File[]) => void;
+    setPendingVoice: (value: File[]) => void;
+    setIssues: (value: AttachmentValidationIssue[]) => void;
+    setFailure: (value: ClientFailure | null) => void;
+    setAnswering: (value: AnsweringGate | null) => void;
+    setDelivery: (value: {
+        status: MessageDelivery;
+    } | null) => void;
+    pendingRef: MutableRefObject<ComposerPendingMessage[]>;
+};
+type ComposerFields = {
+    text: string;
+    files: File[];
+    voice: File[];
+};
+export declare function useTheoremChatActions(args: TheoremChatActionArgs): {
+    startTurnFromFields: (fields: ComposerFields) => Promise<void>;
+    startTurnFromDraft: (draft: ComposerPendingMessage["draft"], options?: {
+        /** Send while the reply waits on gates: the message walks away from them. */
+        walkAway?: boolean;
+        /** Once the message posts: it leaves wherever it was waiting to be sent. */
+        onPosted?: () => void;
+    }) => Promise<void>;
+    handleStop: () => void;
+    handleSubmit: () => Promise<void>;
+    handleSendNow: (draftSource?: ComposerPendingMessage) => Promise<void>;
+    handleMenuAction: (action: ComposerMenuAction) => void;
+    handleToolDecision: (_index: number, action: ToolDecisionAction) => Promise<void>;
+    handleAuthenticated: (_index: number, secret?: string) => Promise<void>;
+    resumeGatedTool: (resolution: ToolGateResolution) => Promise<void>;
+    handlePendingRestore: (id: string) => Promise<void>;
+    enqueuePending: (kind: "queue" | "steer" | "stash") => Promise<void>;
+};
+export {};