@theoremjs/react 0.0.0-stage → 0.3.1

package/client/wire-line.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Every value that reaches the browser over a wire (NDJSON lines, live
+ * envelopes) is checked against its schema here. A line or event of a kind the
+ * client does not know is reported as `unsupported`, and one that fails its
+ * check (not JSON, no kind, or a known kind that fails its schema) as
+ * `malformed`; either way the reply goes on. A whole reply that fails its check
+ * (the profile description) is `bad_response`.
+ *
+ * @module
+ */
+import { TheoremError, z } from '@theoremjs/agents';
+/**
+ * A line or envelope of a kind the client does not know. The server never
+ * sends it; the client's parser makes it so the host sees what arrived. Theorem
+ * shows nothing for it.
+ */
+export type UnsupportedEvent = {
+    type: 'unsupported';
+    received: string;
+    raw: unknown;
+};
+/**
+ * A line or event that failed its wire check. The server never sends it; the
+ * client's reader makes it, leaves the line out, and the reply goes on. `error`
+ * is `bad_response`: its message names what broke, never the value, and the
+ * user reads `session.part_skipped`.
+ */
+export type MalformedEvent = {
+    type: 'malformed';
+    error: TheoremError;
+};
+/** Every kind a wire carries, and the schema a value of that kind must pass. */
+export type WireLines<Line extends {
+    type: string;
+}> = {
+    readonly [K in Line['type']]: z.ZodType<Extract<Line, {
+        type: K;
+    }>>;
+};
+/**
+ * Issue paths and codes only: a failure names what broke, never the value. A
+ * union that matched no branch lists each branch's issues.
+ */
+export declare function issueSummary(error: z.ZodError): string;
+/** `raw` as `schema` reads it; one that fails is `bad_response`, naming `what`. */
+export declare function checkWire<T>(schema: z.ZodType<T>, raw: unknown, what: string): T;
+/** One wire value: a known kind that passed its schema, `unsupported`, or `malformed`. */
+export declare function readWireValue<Line extends {
+    type: string;
+}>(lines: WireLines<Line>, raw: unknown): Line | UnsupportedEvent | MalformedEvent;
+/** One wire line's text: {@link readWireValue} of its JSON, or `malformed` when it is not JSON. */
+export declare function readWireLine<Line extends {
+    type: string;
+}>(lines: WireLines<Line>, text: string): Line | UnsupportedEvent | MalformedEvent;
+/** A whole reply's JSON text as a value; text that is not JSON is `bad_response`. */
+export declare function parseWireJson(text: string): unknown;

package/client/wire-line.js

@@ -0,0 +1,90 @@
+/**
+ * Every value that reaches the browser over a wire (NDJSON lines, live
+ * envelopes) is checked against its schema here. A line or event of a kind the
+ * client does not know is reported as `unsupported`, and one that fails its
+ * check (not JSON, no kind, or a known kind that fails its schema) as
+ * `malformed`; either way the reply goes on. A whole reply that fails its check
+ * (the profile description) is `bad_response`.
+ *
+ * @module
+ */
+import { TheoremError, z } from '@theoremjs/agents';
+const wireKind = z.object({ type: z.string() });
+function isKnown(lines, type) {
+    return Object.hasOwn(lines, type);
+}
+function issuesSummary(issues, at) {
+    return issues
+        .map((issue) => {
+        const path = [...at, ...issue.path];
+        const head = `${path.map(String).join('.') || '(root)'} ${issue.code}`;
+        if (issue.code !== 'invalid_union' || issue.errors.length === 0)
+            return head;
+        return `${head} [${issue.errors.map((branch) => issuesSummary(branch, path)).join(' | ')}]`;
+    })
+        .join('; ');
+}
+/**
+ * Issue paths and codes only: a failure names what broke, never the value. A
+ * union that matched no branch lists each branch's issues.
+ */
+export function issueSummary(error) {
+    return issuesSummary(error.issues, []);
+}
+function badResponse(what, error) {
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    return new TheoremError('bad_response', `${what} failed its wire check: ${issueSummary(error)}`);
+}
+/** `raw` as `schema` reads it; one that fails is `bad_response`, naming `what`. */
+export function checkWire(schema, raw, what) {
+    const parsed = schema.safeParse(raw);
+    if (!parsed.success)
+        throw badResponse(what, parsed.error);
+    return parsed.data;
+}
+function malformed(message) {
+    return {
+        type: 'malformed',
+        error: new TheoremError('bad_response', message, { copy: { key: 'session.part_skipped' } }),
+    };
+}
+/** One wire value: a known kind that passed its schema, `unsupported`, or `malformed`. */
+export function readWireValue(lines, raw) {
+    const kind = wireKind.safeParse(raw);
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
+    if (!kind.success)
+        return malformed(`a line without a kind failed its wire check: ${issueSummary(kind.error)}`);
+    const { type } = kind.data;
+    if (!isKnown(lines, type))
+        return { type: 'unsupported', received: type, raw };
+    const line = lines[type].safeParse(raw);
+    if (line.success)
+        return line.data;
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
+    return malformed(`a '${type}' line failed its wire check: ${issueSummary(line.error)}`);
+}
+/** JSON text as a value, or undefined when it is not JSON. The parser's own error quotes the text, so it is not kept. */
+function jsonValue(text) {
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return undefined;
+        throw err;
+    }
+}
+/** One wire line's text: {@link readWireValue} of its JSON, or `malformed` when it is not JSON. */
+export function readWireLine(lines, text) {
+    const json = jsonValue(text);
+    // labels-exempt: internal diagnostic; the user reads session.part_skipped
+    return json ? readWireValue(lines, json.value) : malformed('a line is not JSON');
+}
+/** A whole reply's JSON text as a value; text that is not JSON is `bad_response`. */
+export function parseWireJson(text) {
+    const json = jsonValue(text);
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    if (!json)
+        throw new TheoremError('bad_response', 'a line is not JSON');
+    return json.value;
+}

package/client/worklets/mic-capture.js

@@ -0,0 +1,16 @@
+/**
+ * AudioWorklet processor that forwards mono mic frames to the main thread.
+ * Plain JS: it runs in the AudioWorkletGlobalScope as its own module, loaded
+ * by URL (see `../mic-capture.ts`), so it imports nothing and ships as is.
+ */
+registerProcessor(
+  'mic-capture-processor',
+  class MicCaptureProcessor extends AudioWorkletProcessor {
+    process(inputs) {
+      const channel = inputs[0][0];
+      const copy = new Float32Array(channel);
+      this.port.postMessage(copy, [copy.buffer]);
+      return true;
+    }
+  },
+);

package/components/InkWaveform.d.ts

@@ -0,0 +1,21 @@
+import { type RefObject } from 'react';
+import { type InkWaveStatus } from '../client/ink-waveform.ts';
+/** Mic and speaker levels. A host on the audio clock writes this; the bars read it each frame. */
+export type InkWaveLevels = {
+    input: number;
+    output: number;
+};
+export type InkWaveformProps = {
+    status?: InkWaveStatus;
+    inputLevel?: number;
+    outputLevel?: number;
+    /**
+     * Latest levels, read each frame. When set, it wins over `inputLevel` and
+     * `outputLevel`, so a host can move the bars without rendering.
+     */
+    levelsRef?: RefObject<InkWaveLevels>;
+    toolActive?: boolean;
+    frozen?: boolean;
+    variant?: 'default' | 'hero' | 'pill' | 'strip';
+};
+export declare function InkWaveform({ status, inputLevel, outputLevel, levelsRef, toolActive, frozen, variant, }: InkWaveformProps): import("react").JSX.Element;

package/components/InkWaveform.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from 'react';
+import { computeInkBarTargets, INK_WAVE_BAR_COUNT, INK_WAVE_HERO_BAR_COUNT, inkWaveDriver, inkWavePhases, } from "../client/ink-waveform.js";
+const REST_HEIGHT = 0.06;
+const WAVE_CONFIG = {
+    hero: {
+        viewWidth: 960,
+        viewHeight: 720,
+        preserveAspect: 'xMidYMax slice',
+        strokeWidth: 2,
+        barCount: INK_WAVE_HERO_BAR_COUNT,
+    },
+    pill: {
+        viewWidth: 480,
+        viewHeight: 120,
+        preserveAspect: 'none',
+        strokeWidth: 3,
+        barCount: INK_WAVE_BAR_COUNT,
+    },
+    strip: {
+        viewWidth: 1600,
+        viewHeight: 48,
+        preserveAspect: 'none',
+        strokeWidth: 2,
+        barCount: 120,
+    },
+    default: {
+        viewWidth: 480,
+        viewHeight: 320,
+        preserveAspect: 'xMidYMax meet',
+        strokeWidth: 2,
+        barCount: INK_WAVE_BAR_COUNT,
+    },
+};
+function resolveWaveDimensions(variant) {
+    const cfg = WAVE_CONFIG[variant] ?? WAVE_CONFIG.default;
+    const gap = (cfg.viewWidth - cfg.strokeWidth * cfg.barCount) / (cfg.barCount + 1);
+    return { ...cfg, gap };
+}
+/** One frame's bar targets. The live ref's levels win over the last render's; a frozen wave moves to none. */
+function frameTargets(snap, phases, timeMs) {
+    const { input, output } = snap.levelsRef?.current ?? {
+        input: snap.inputLevel,
+        output: snap.outputLevel,
+    };
+    const heard = snap.frozen ? { input: 0, output: 0 } : { input, output };
+    return computeInkBarTargets({
+        phases,
+        timeMs,
+        driver: inkWaveDriver(snap.status, snap.toolActive, input, output, snap.frozen),
+        inputLevel: heard.input,
+        outputLevel: heard.output,
+        frozen: snap.frozen,
+    });
+}
+/**
+ * Paints bar heights onto the mounted lines. The motion is the same as
+ * `computeInkBarTargets` plus the per-frame ease; React never sees a frame,
+ * so a strip of bars does not reconcile on the audio clock.
+ */
+function usePaintedWave(svgRef, snapRef, phases, barCount, viewHeight) {
+    useEffect(() => {
+        const svg = svgRef.current;
+        if (!svg)
+            return;
+        const lines = svg.children;
+        const count = Math.min(barCount, lines.length);
+        const heights = new Float64Array(count);
+        heights.fill(REST_HEIGHT);
+        const restY = viewHeight - REST_HEIGHT * (viewHeight - 4);
+        for (let index = 0; index < count; index++) {
+            lines[index].y2.baseVal.value = restY;
+        }
+        let frame = 0;
+        const tick = (time) => {
+            const snap = snapRef.current;
+            const targets = frameTargets(snap, phases, time);
+            const alpha = snap.frozen ? 0.2 : 0.14;
+            for (let index = 0; index < count; index++) {
+                const height = heights[index] + (targets[index] - heights[index]) * alpha;
+                heights[index] = height;
+                lines[index].y2.baseVal.value = viewHeight - height * (viewHeight - 4);
+            }
+            frame = requestAnimationFrame(tick);
+        };
+        frame = requestAnimationFrame(tick);
+        return () => {
+            cancelAnimationFrame(frame);
+        };
+    }, [svgRef, snapRef, phases, barCount, viewHeight]);
+}
+export function InkWaveform({ status = 'disconnected', inputLevel = 0, outputLevel = 0, levelsRef, toolActive = false, frozen = false, variant = 'default', }) {
+    const { viewWidth, viewHeight, preserveAspect, strokeWidth, barCount, gap } = resolveWaveDimensions(variant);
+    const phases = useMemo(() => inkWavePhases(barCount), [barCount]);
+    const xs = useMemo(() => {
+        const next = new Array(barCount);
+        for (let index = 0; index < barCount; index++) {
+            next[index] = gap + index * (strokeWidth + gap) + strokeWidth / 2;
+        }
+        return next;
+    }, [barCount, gap, strokeWidth]);
+    const svgRef = useRef(null);
+    const snapRef = useRef({
+        status,
+        inputLevel,
+        outputLevel,
+        levelsRef,
+        toolActive,
+        frozen,
+    });
+    snapRef.current.status = status;
+    snapRef.current.inputLevel = inputLevel;
+    snapRef.current.outputLevel = outputLevel;
+    snapRef.current.levelsRef = levelsRef;
+    snapRef.current.toolActive = toolActive;
+    snapRef.current.frozen = frozen;
+    usePaintedWave(svgRef, snapRef, phases, barCount, viewHeight);
+    const className = [
+        'ink-wave',
+        variant === 'hero' ? 'ink-wave--hero' : '',
+        variant === 'pill' ? 'ink-wave--pill' : '',
+        variant === 'strip' ? 'ink-wave--strip' : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const restY = viewHeight - REST_HEIGHT * (viewHeight - 4);
+    return (_jsx("svg", { ref: svgRef, className: className, "aria-hidden": "true", viewBox: `0 0 ${String(viewWidth)} ${String(viewHeight)}`, preserveAspectRatio: preserveAspect, 
+        // why: Attribute defaults for hosts without ink-controls.css (the Astryx UI);
+        // the live stylesheet overrides them where it loads.
+        width: "100%", height: "100%", children: xs.map((x) => (_jsx("line", { className: "ink-wave__bar", x1: x, x2: x, y1: viewHeight, y2: restY, strokeWidth: strokeWidth, stroke: "currentColor", strokeLinecap: "square" }, x))) }));
+}

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

@@ -0,0 +1,47 @@
+import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
+import { type LiveCaptionState } from '../../client/live/live-captions.ts';
+import type { LiveConnectPhase, LiveSessionStatus } from '../../client/live/live-state.ts';
+import { type LiveFacingMode, type LiveVideoCapture } from '../../client/live/live-video.ts';
+import type { LiveConnection, LiveSessionClient } from '../../client/live-client.ts';
+/** Media + session lifecycle handlers for LiveRunner. */
+export declare function useLiveRunnerControls(args: {
+    clientRef: MutableRefObject<LiveSessionClient | null>;
+    videoCaptureRef: MutableRefObject<LiveVideoCapture | null>;
+    connectionRef: MutableRefObject<() => LiveConnection | Promise<LiveConnection>>;
+    statusRef: MutableRefObject<LiveSessionStatus>;
+    isMutedRef: MutableRefObject<boolean>;
+    sessionPermissionsRef: MutableRefObject<string[]>;
+    ensureClient: (connection: LiveConnection) => LiveSessionClient;
+    clearClient: () => void;
+    cancelGateDecision: (reason?: string) => void;
+    stopVideo: () => void;
+    resetCaptions: () => void;
+    sessionActive: boolean;
+    textAvailable: boolean;
+    videoAvailable: boolean;
+    voiceAvailable: boolean;
+    isVideoOn: boolean;
+    textDraft: string;
+    setTextDraft: Dispatch<SetStateAction<string>>;
+    setCaptions: Dispatch<SetStateAction<LiveCaptionState>>;
+    reportFailure: (err: unknown) => void;
+    clearFailure: () => void;
+    setIsMuted: Dispatch<SetStateAction<boolean>>;
+    setSessionActive: Dispatch<SetStateAction<boolean>>;
+    setSessionPermissions: Dispatch<SetStateAction<string[]>>;
+    setStatus: Dispatch<SetStateAction<LiveSessionStatus>>;
+    setConnectPhase: Dispatch<SetStateAction<LiveConnectPhase | null>>;
+    setInputLevel: Dispatch<SetStateAction<number>>;
+    setOutputLevel: Dispatch<SetStateAction<number>>;
+    setVideoPreview: Dispatch<SetStateAction<HTMLVideoElement | null>>;
+    setVideoFacingMode: Dispatch<SetStateAction<LiveFacingMode>>;
+    setIsVideoOn: Dispatch<SetStateAction<boolean>>;
+}): {
+    teardownSession: () => void;
+    startSession: () => Promise<void>;
+    handleSendText: (text?: string) => void;
+    handleToggleVideo: () => Promise<void>;
+    handleFlipCamera: () => Promise<void>;
+    handleToggleMic: () => void;
+    handleRestart: () => Promise<void>;
+};

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

@@ -0,0 +1,96 @@
+import { useCallback } from 'react';
+import { applyLiveTranscript } from "../../client/live/live-captions.js";
+import { startLiveVideoCapture, } from "../../client/live/live-video.js";
+/** Media + session lifecycle handlers for LiveRunner. */
+export function useLiveRunnerControls(args) {
+    const teardownSession = useCallback(() => {
+        args.cancelGateDecision();
+        args.clearClient();
+        args.stopVideo();
+        args.setIsMuted(false);
+        args.isMutedRef.current = false;
+        args.setSessionActive(false);
+        args.setSessionPermissions([]);
+        args.sessionPermissionsRef.current = [];
+        args.statusRef.current = 'disconnected';
+        args.setStatus('disconnected');
+        args.setConnectPhase(null);
+        args.setInputLevel(0);
+        args.setOutputLevel(0);
+    }, [args]);
+    const startSession = useCallback(async () => {
+        args.clearFailure();
+        args.resetCaptions();
+        try {
+            const liveClient = args.ensureClient(await args.connectionRef.current());
+            if (args.statusRef.current === 'disconnected' || args.statusRef.current === 'error') {
+                await liveClient.connect();
+            }
+        }
+        catch (err) {
+            args.reportFailure(err);
+        }
+    }, [args]);
+    const handleSendText = useCallback((text) => {
+        const message = (typeof text === 'string' ? text : args.textDraft).trim();
+        if (!message || !args.clientRef.current || !args.sessionActive || !args.textAvailable)
+            return;
+        args.clientRef.current.sendText(message);
+        args.setTextDraft('');
+        args.setCaptions((prev) => applyLiveTranscript(prev, message, true, false, { forceNew: true }));
+    }, [args]);
+    const handleToggleVideo = useCallback(async () => {
+        if (!args.clientRef.current || !args.sessionActive || !args.videoAvailable)
+            return;
+        if (args.isVideoOn) {
+            args.stopVideo();
+            return;
+        }
+        try {
+            const capture = await startLiveVideoCapture((base64) => {
+                args.clientRef.current?.sendVideo(base64);
+            });
+            args.videoCaptureRef.current = capture;
+            args.setVideoPreview(capture.video);
+            args.setVideoFacingMode(capture.facingMode());
+            args.setIsVideoOn(true);
+        }
+        catch (err) {
+            args.reportFailure(err);
+            args.stopVideo();
+        }
+    }, [args]);
+    const handleFlipCamera = useCallback(async () => {
+        const capture = args.videoCaptureRef.current;
+        if (!capture || !args.sessionActive || !args.isVideoOn)
+            return;
+        try {
+            const facing = await capture.flip();
+            args.setVideoFacingMode(facing);
+            args.setVideoPreview(capture.video);
+        }
+        catch (err) {
+            args.reportFailure(err);
+        }
+    }, [args]);
+    const handleToggleMic = useCallback(() => {
+        if (!args.clientRef.current || !args.sessionActive || !args.voiceAvailable)
+            return;
+        const muted = args.clientRef.current.toggleMute();
+        args.isMutedRef.current = muted;
+        args.setIsMuted(muted);
+    }, [args]);
+    const handleRestart = useCallback(async () => {
+        teardownSession();
+        await startSession();
+    }, [startSession, teardownSession]);
+    return {
+        teardownSession,
+        startSession,
+        handleSendText,
+        handleToggleVideo,
+        handleFlipCamera,
+        handleToggleMic,
+        handleRestart,
+    };
+}

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

@@ -0,0 +1,49 @@
+import type { LiveProfileInterface } from '@theoremjs/agents/interface';
+import { type LiveCaptionState, type LiveCaptionTurn } from '../../client/live/live-captions.ts';
+import type { LiveCallOptions } from '../../client/live/live-page-tool.ts';
+import type { LiveConnection } from '../../client/live-client.ts';
+/**
+ * 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.
+ */
+export declare function useLiveRunnerModel(iface: LiveProfileInterface, connection: () => LiveConnection | Promise<LiveConnection>, options?: LiveCallOptions): {
+    handle: string;
+    traces: import("../../index.ts").TraceFeed;
+    callStarted: boolean;
+    pastCalls: LiveCaptionTurn[][];
+    captions: LiveCaptionState;
+    failure: import("../../index.ts").ClientFailure | null;
+    sessionEnded: string | null;
+    levelsRef: import("react").RefObject<{
+        input: number;
+        output: number;
+    }>;
+    isMuted: boolean;
+    isVideoOn: boolean;
+    sessionActive: boolean;
+    liveState: import("../../index.ts").LiveState;
+    activeTool: string | null;
+    status: import("../../index.ts").LiveSessionStatus;
+    textAvailable: boolean;
+    textDraft: string;
+    toolActive: boolean;
+    videoAvailable: boolean;
+    videoFacingMode: import("../../client/live/live-video.ts").LiveFacingMode;
+    videoPreview: HTMLVideoElement | null;
+    voiceAvailable: boolean;
+    canRestart: boolean;
+    gatePrompt: import("../../index.ts").LiveToolGatePrompt | null;
+    setTextDraft: import("react").Dispatch<import("react").SetStateAction<string>>;
+    handleEnd: () => void;
+    startCall: (options: {
+        video: boolean;
+    }) => void;
+    handleRestart: () => Promise<void>;
+    handleSendText: (text?: string) => void;
+    handleToggleMic: () => void;
+    handleFlipCamera: () => Promise<void>;
+    handleToggleVideo: () => Promise<void>;
+    resolveGateDecision: (resolution: import("../../index.ts").ToolGateResolution) => void;
+};