@theoremjs/react 0.0.0-stage → 0.3.1

package/client/transport.js

@@ -0,0 +1,330 @@
+import { gateReferenceSchema, TOOL_GATE_KINDS, } from '@theoremjs/agents';
+/**
+ * Transport contract between a Theorem chat UI and the host that runs turns.
+ *
+ * The browser never holds the profile: it asks the transport to `describe` the
+ * profile's client-safe interface, then streams turns / tool invokes through it.
+ * `createHttpTransport` speaks to `createTheoremHandler` (`@theoremjs/react/server`);
+ * hosts with their own wire format implement {@link TheoremTransport} directly.
+ *
+ * @module
+ */
+import { describeError, errorKindSchema, isAbortError, TheoremError, TURN_EVENT_SCHEMAS, throwIfAborted, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, z, } from '@theoremjs/agents';
+import { errorCopiesSchema, kindOfHttpStatus, } from '@theoremjs/agents/guardrails';
+import { profileInterfaceSchema, } from '@theoremjs/agents/interface';
+import { transcriptBlockSchema } from "./transcript-schema.js";
+import { checkWire, parseWireJson, readWireLine, } from "./wire-line.js";
+const encodedBlob = z.object({ name: z.string(), mimeType: z.string(), data: z.string() });
+true;
+const theoremTurnInput = z.object({
+    slots: z.record(z.string(), z.string()).optional(),
+    context: z.unknown().optional(),
+    text: z.string().optional(),
+    attachments: z.array(encodedBlob).optional(),
+    voice: z.array(encodedBlob).optional(),
+});
+true;
+const theoremReplay = z.object({
+    gateKind: z.enum(TOOL_GATE_KINDS).optional(),
+    sessionPermissions: z.array(z.string()).optional(),
+    name: z.string().optional(),
+    input: z.unknown().optional(),
+    snapshot: turnToolSnapshotSchema.optional(),
+    promoted: z.array(z.string()).optional(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+});
+true;
+/** For a host that reads the studio's client-held state. */
+export const theoremReplaySchema = theoremReplay;
+/** An id the client made: trimmed, never blank. */
+const clientId = z.string().trim().min(1);
+const theoremTurnRequest = z.object({
+    input: theoremTurnInput,
+    conversation: z.string().min(1).optional(),
+    model: z.string().optional(),
+    effort: z.string().optional(),
+    turnId: clientId.optional(),
+    abandon: z.array(gateReferenceSchema).min(1).optional(),
+    replay: theoremReplay.pick({ sessionPermissions: true }).optional(),
+    transcript: z.array(transcriptBlockSchema).optional(),
+});
+true;
+/** A `/turn` body as `createTheoremHandler` reads it. */
+export const theoremTurnRequestSchema = theoremTurnRequest;
+/** What the user answers a gate with; walking away rides on the next message (`TheoremTurnRequest.abandon`). */
+const INVOKE_DECISIONS = ['approve', 'deny'];
+const pagePart = z.union([
+    z.strictObject({ unanswered: z.literal(true) }),
+    z
+        .strictObject({ output: z.unknown() })
+        .refine((part) => 'output' in part)
+        .transform((part) => ({ output: part.output })),
+]);
+const theoremInvokeRequest = z.object({
+    gateId: z.string().min(1),
+    operationId: z.string().min(1).max(256),
+    decision: z.enum(INVOKE_DECISIONS),
+    input: z.unknown().optional(),
+    secret: z.string().optional(),
+    page: pagePart.optional(),
+    conversation: z.string().min(1).optional(),
+    turnId: clientId.optional(),
+    replay: theoremReplay.optional(),
+});
+true;
+/** An `/invoke` body as `createTheoremHandler` reads it. */
+export const theoremInvokeRequestSchema = theoremInvokeRequest;
+const theoremSteerRequest = z.object({
+    turnId: clientId,
+    id: clientId,
+    inject: z.array(turnHistoryMessageSchema).min(1),
+});
+true;
+/** A `/steer` body as `createTheoremHandler` reads it. */
+export const theoremSteerRequestSchema = theoremSteerRequest;
+const conversationLine = z.object({
+    type: z.literal('conversation'),
+    ref: z.string().min(1),
+    posted: z.literal(true).optional(),
+});
+true;
+/** The lines a chat's reply streams: turn events, and the conversation's ref. */
+export const CHAT_LINES = {
+    ...TURN_EVENT_SCHEMAS,
+    conversation: conversationLine,
+};
+const conversationView = z.object({
+    transcript: z.array(transcriptBlockSchema),
+    paused: z
+        .object({ events: z.array(turnEventSchema), blocks: z.array(transcriptBlockSchema) })
+        .optional(),
+});
+true;
+const theoremConversationRequest = z.object({ conversation: z.string().min(1) });
+true;
+/** A `/conversation` body as `createTheoremHandler` reads it. */
+export const theoremConversationRequestSchema = theoremConversationRequest;
+const theoremRewindRequest = z.object({
+    conversation: z.string().min(1),
+    at: z.number().int().min(-1),
+});
+true;
+/** A `/rewind` body as `createTheoremHandler` reads it. */
+export const theoremRewindRequestSchema = theoremRewindRequest;
+const theoremRewound = z.object({ conversation: z.string().min(1), view: conversationView });
+true;
+/**
+ * A failure the host reported: its kind, the host's wording when it sent one
+ * (the profile's labels, applied on the host), and raw detail when the host
+ * exposes it. `clientFailure` words it for the user.
+ */
+export class TheoremStreamError extends Error {
+    kind;
+    publicMessage;
+    internalMessage;
+    /** The labels key behind `publicMessage`, when the host gave one: what failed, more exactly than `kind`. */
+    copy;
+    constructor(kind, publicMessage, internalMessage, copy) {
+        super(internalMessage ?? publicMessage ?? kind);
+        this.name = 'TheoremStreamError';
+        this.kind = kind;
+        if (publicMessage)
+            this.publicMessage = publicMessage;
+        if (internalMessage)
+            this.internalMessage = internalMessage;
+        if (copy)
+            this.copy = copy;
+    }
+}
+export function isTheoremStreamError(err) {
+    return err instanceof TheoremStreamError;
+}
+/** The trimmed string, or undefined when absent or blank. */
+function textOf(value) {
+    return value?.trim() || undefined;
+}
+const hostErrorBody = z.object({
+    error: z.string().optional(),
+    errorKind: errorKindSchema.optional(),
+    errorCopy: errorCopiesSchema.optional(),
+    errorInternal: z.string().optional(),
+});
+true;
+/** A host's error body, as the transport and the live client read it. */
+export const hostErrorBodySchema = hostErrorBody;
+/** A host's error body as a failure: its kind (else `fallbackKind`), wording, and detail. */
+export function hostError(body, fallbackKind) {
+    const publicMessage = textOf(body.error);
+    const internal = textOf(body.errorInternal);
+    return new TheoremStreamError(body.errorKind ?? fallbackKind, publicMessage, internal && internal !== publicMessage ? internal : undefined, body.errorCopy);
+}
+/** The host could not open the message's conversation (`session.conversation_unknown`). */
+export function isUnknownConversation(err) {
+    if (!isTheoremStreamError(err) || err.copy === undefined)
+        return false;
+    const copies = Array.isArray(err.copy) ? err.copy : [err.copy];
+    return copies.some((copy) => copy.key === 'session.conversation_unknown');
+}
+/** One NDJSON line checked against `lines`; an `error` line ends the stream as a {@link TheoremStreamError}. */
+function parseStreamLine(lines, text) {
+    const line = readWireLine(lines, text);
+    // why: An `error` line passed the error event's schema, whose fields include the body's.
+    if (line.type === 'error')
+        throw hostError(hostErrorBody.parse(line), 'internal');
+    return line;
+}
+function flushNdjsonChunk(buffer, lines, onLine) {
+    const chunks = buffer.split('\n');
+    const rest = chunks.pop() ?? '';
+    for (const chunk of chunks) {
+        if (!chunk.trim())
+            continue;
+        onLine(parseStreamLine(lines, chunk));
+    }
+    return rest;
+}
+/**
+ * Read an NDJSON reply, checking each line against `lines`: a kind it doesn't
+ * list reaches `onLine` as `unsupported`, and a line that fails its check as
+ * `malformed`; the stream goes on. An `error` line ends it.
+ */
+export async function readNdjsonStream(response, lines, onLine, signal) {
+    if (!response.body)
+        throw new TheoremError('bad_response', 'stream reply has no body'); // labels-exempt: internal diagnostic
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    const onAbort = () => {
+        void reader.cancel();
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for (;;) {
+            throwIfAborted(signal);
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer = flushNdjsonChunk(buffer + decoder.decode(value, { stream: true }), lines, onLine);
+        }
+        const tail = buffer.trim();
+        if (tail)
+            onLine(parseStreamLine(lines, tail));
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+    }
+}
+async function resolveHeaders(options) {
+    const extra = typeof options.headers === 'function' ? await options.headers() : options.headers;
+    const headers = new Headers(extra);
+    headers.set('content-type', 'application/json');
+    return headers;
+}
+/**
+ * A non-OK reply as a failure: the host's kind and wording, else the status's
+ * kind. A body that is not JSON (a proxy's page) leaves the status to speak; a
+ * JSON body that fails the error body's schema is `bad_response`.
+ */
+async function failureFromResponse(response, failed) {
+    const text = await response.text();
+    let raw;
+    try {
+        raw = JSON.parse(text);
+        failed?.(raw);
+    }
+    catch {
+        return hostError({ errorInternal: `HTTP ${String(response.status)}` }, kindOfHttpStatus(response.status));
+    }
+    const body = hostErrorBody.safeParse(raw);
+    if (!body.success) {
+        // labels-exempt: internal diagnostic; the user reads error.bad_response
+        return new TheoremError('bad_response', `HTTP ${String(response.status)} error body failed its wire check`);
+    }
+    return hostError({ ...body.data, errorInternal: body.data.errorInternal ?? `HTTP ${String(response.status)}` }, kindOfHttpStatus(response.status));
+}
+async function request(url, init, options) {
+    const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    try {
+        return await doFetch(url, {
+            ...init,
+            headers: await resolveHeaders(options),
+            credentials: options.credentials ?? 'same-origin',
+        });
+    }
+    catch (err) {
+        if (isAbortError(err))
+            throw err;
+        throw new TheoremError('network', describeError(err), { cause: err });
+    }
+}
+/**
+ * POST JSON and stream NDJSON lines back, each checked against `lines`: turn
+ * events ({@link TURN_EVENT_SCHEMAS}), or a host's own schema beside them.
+ */
+export async function postNdjson(url, body, lines, onLine, options = {}) {
+    const response = await jsonPostResponse(url, body, options);
+    await readNdjsonStream(response, lines, onLine, options.signal);
+}
+async function jsonPostResponse(url, body, options) {
+    const response = await request(url, { method: 'POST', body: JSON.stringify(body), signal: options.signal }, options);
+    if (!response.ok)
+        throw await failureFromResponse(response);
+    return response;
+}
+/** POST JSON; a non-OK reply throws its failure. The OK reply's body is not read. */
+export async function postJson(url, body, options = {}) {
+    await jsonPostResponse(url, body, options);
+}
+/**
+ * GET, or POST `body` as JSON, and read the JSON reply; a non-OK reply throws its failure, after
+ * `failed` has read whatever else its JSON body carries.
+ */
+export async function fetchJson(url, init, options = {}) {
+    const method = init.body === undefined
+        ? { method: 'GET' }
+        : { method: 'POST', body: JSON.stringify(init.body) };
+    const response = await request(url, { ...method, signal: init.signal }, options);
+    if (!response.ok)
+        throw await failureFromResponse(response, init.failed);
+    return parseWireJson(await response.text());
+}
+/** POST a conversation's read to `url`, and check the view the host answers. */
+export async function fetchConversation(url, body, options = {}) {
+    const { signal, ...http } = options;
+    // labels-exempt: internal diagnostic; the user reads error.bad_response
+    return checkWire(conversationView, await fetchJson(url, { body, signal }, http), 'the conversation');
+}
+/** POST a rewind to `url`, and check the rewound conversation the host answers. */
+export async function fetchRewound(url, body, options = {}) {
+    const { signal, ...http } = options;
+    return checkWire(theoremRewound, await fetchJson(url, { body, signal }, http), 'the rewound conversation');
+}
+/** Drops trailing '/'s by scanning back, not with a regex (a `/\/+$/` scan is quadratic on long runs of '/'). */
+function withoutTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === '/')
+        end -= 1;
+    return url.slice(0, end);
+}
+/** The host's `describe` reply. */
+const describedSchema = z.object({ interface: profileInterfaceSchema });
+/** Transport for a host mounted with `createTheoremHandler`. */
+export function createHttpTransport(options = {}) {
+    const base = withoutTrailingSlashes(options.endpoint ?? '/api/theorem');
+    return {
+        async describe(signal) {
+            const response = await request(base, { method: 'GET', signal }, options);
+            if (!response.ok)
+                throw await failureFromResponse(response);
+            // labels-exempt: internal diagnostic; the user reads error.bad_response
+            return checkWire(describedSchema, parseWireJson(await response.text()), 'the profile description').interface;
+        },
+        turn: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/turn`, body, CHAT_LINES, onEvent, { ...options, signal }),
+        invoke: ({ replay: _replay, ...body }, onEvent, signal) => postNdjson(`${base}/invoke`, body, CHAT_LINES, onEvent, { ...options, signal }),
+        conversation: (body, signal) => fetchConversation(`${base}/conversation`, body, { ...options, signal }),
+        rewind: (body, signal) => fetchRewound(`${base}/rewind`, body, { ...options, signal }),
+        pageResult: (body, signal) => postJson(`${base}/page-result`, body, { ...options, signal }),
+        steer: (body) => postJson(`${base}/steer`, body, options),
+    };
+}

package/client/turn-client.d.ts

@@ -0,0 +1,44 @@
+import { type TurnEvent } from '@theoremjs/agents';
+import { type AttachmentValidationIssue, type ComposerProfileInterface, type GatedToolContext, type InterfaceTurnSession, type TranscriptBlock, type UserTurnDraft } from '@theoremjs/agents/interface';
+import type { PagePart } from './tool-resume.ts';
+import type { TheoremInvokeRequest, TheoremReplay, TheoremTurnInput, TheoremTurnRequest } from './transport.ts';
+export declare function issuedOperationId(call: {
+    operationId?: string;
+}): string;
+/** A gated call as the client holds it, for a host without a session (the studio). */
+export type HeldCall = {
+    name: string;
+    /** The model's input to the call. */
+    input: unknown;
+    gateKind?: TheoremReplay['gateKind'];
+    sessionPermissions?: string[];
+};
+/** The calls a paused reply waits on that a message walks away from. */
+export type WalkAway = {
+    calls: readonly GatedToolContext[];
+};
+/** Where a request goes on from: the ref of the conversation the host keeps, and the run's id for steers. */
+export type RunScope = {
+    conversation?: string;
+    turnId?: string;
+};
+export declare function buildTurnRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, input: TheoremTurnInput, options?: RunScope & {
+    walkAway?: WalkAway;
+}): TheoremTurnRequest;
+export declare function buildInvokeRequest(iface: ComposerProfileInterface, session: InterfaceTurnSession, args: HeldCall & {
+    gateId: string;
+    operationId: string;
+    decision: TheoremInvokeRequest['decision'];
+    secret?: string;
+    page?: PagePart;
+}, scope?: RunScope): TheoremInvokeRequest;
+export declare function projectUserTurn(iface: ComposerProfileInterface, draft: UserTurnDraft): {
+    ok: true;
+    blocks: TranscriptBlock[];
+    draft: UserTurnDraft;
+} | {
+    ok: false;
+    issues: AttachmentValidationIssue[];
+};
+export declare function prepareComposerTurn(iface: ComposerProfileInterface, text: string, pendingFiles: readonly File[], pendingVoice?: readonly File[]): ReturnType<typeof projectUserTurn>;
+export declare function foldAssistantTurn(iface: ComposerProfileInterface, events: readonly TurnEvent[]): TranscriptBlock[];

package/client/turn-client.js

@@ -0,0 +1,88 @@
+import { labelText, TheoremError } from '@theoremjs/agents';
+import { foldTurnEvents, prepareUserTurn, streamThoughtsEnabled, } from '@theoremjs/agents/interface';
+import { filesToPending } from "./encode-files.js";
+import { defaultModel } from "./generation-selection.js";
+export function issuedOperationId(call) {
+    if (!call.operationId)
+        throw new TheoremError('request', labelText('session.gate_expired'));
+    return call.operationId;
+}
+function resolveModelId(iface, session) {
+    return session.selectedModel ?? defaultModel(iface);
+}
+function resolveEffort(iface, session, modelId) {
+    if (!modelId || !Object.hasOwn(iface.models, modelId))
+        return undefined;
+    const binding = iface.models[modelId];
+    if (!binding.allowEffortSelect)
+        return undefined;
+    return session.selectedEffort ?? binding.defaultEffort;
+}
+/** Model / effort selection the host should honour for this session. */
+function generationFields(iface, session) {
+    const modelId = resolveModelId(iface, session);
+    const model = iface.allowModelSelect ? modelId : undefined;
+    const effort = resolveEffort(iface, session, modelId);
+    return { ...(model ? { model } : {}), ...(effort ? { effort } : {}) };
+}
+function gateReplay(iface, session, call) {
+    return {
+        name: call.name,
+        input: call.input,
+        ...(call.gateKind ? { gateKind: call.gateKind } : {}),
+        sessionPermissions: call.sessionPermissions ?? session.sessionPermissions,
+        ...(session.toolSnapshot ? { snapshot: session.toolSnapshot } : {}),
+        ...(session.promotedToolIds.length ? { promoted: [...session.promotedToolIds] } : {}),
+        ...generationFields(iface, session),
+    };
+}
+function scopeFields(scope) {
+    return {
+        ...(scope.conversation ? { conversation: scope.conversation } : {}),
+        ...(scope.turnId ? { turnId: scope.turnId } : {}),
+    };
+}
+export function buildTurnRequest(iface, session, input, options = {}) {
+    const abandon = (options.walkAway?.calls ?? []).map((call) => ({
+        callId: call.callId,
+        operationId: issuedOperationId(call),
+    }));
+    return {
+        ...scopeFields(options),
+        ...generationFields(iface, session),
+        input,
+        ...(abandon.length ? { abandon } : {}),
+        replay: { sessionPermissions: session.sessionPermissions },
+    };
+}
+export function buildInvokeRequest(iface, session, args, scope = {}) {
+    return {
+        ...scopeFields(scope),
+        gateId: args.gateId,
+        operationId: args.operationId,
+        decision: args.decision,
+        ...(args.secret === undefined ? {} : { secret: args.secret }),
+        ...(args.page === undefined ? {} : { page: args.page }),
+        replay: gateReplay(iface, session, {
+            ...args,
+            gateKind: args.gateKind ??
+                (session.gatedTool?.callId === args.gateId ? session.gatedTool.gateKind : undefined),
+        }),
+    };
+}
+export function projectUserTurn(iface, draft) {
+    return prepareUserTurn(iface.inputs, draft, iface.guardrails);
+}
+export function prepareComposerTurn(iface, text, pendingFiles, pendingVoice = []) {
+    return projectUserTurn(iface, {
+        ...(text.trim() ? { text } : {}),
+        ...(pendingFiles.length ? { attachments: filesToPending(pendingFiles) } : {}),
+        ...(pendingVoice.length ? { voice: filesToPending(pendingVoice) } : {}),
+    });
+}
+export function foldAssistantTurn(iface, events) {
+    // why: Its `turn-done` blocks stay: hidden in the view, they carry the reply's worked time.
+    return foldTurnEvents(events, {
+        showThoughts: streamThoughtsEnabled(iface.outputs),
+    });
+}

package/client/voice-label.d.ts

@@ -0,0 +1,2 @@
+/** A voice note's audio format (`webm`, `wav`, `mp3`, `m4a`, `ogg`) from its MIME type; undefined when unknown. */
+export declare function voiceFormatFromMime(mime: string): string | undefined;

package/client/voice-label.js

@@ -0,0 +1,15 @@
+/** A voice note's audio format (`webm`, `wav`, `mp3`, `m4a`, `ogg`) from its MIME type; undefined when unknown. */
+export function voiceFormatFromMime(mime) {
+    const lower = mime.toLowerCase();
+    if (lower.includes('webm'))
+        return 'webm';
+    if (lower.includes('wav'))
+        return 'wav';
+    if (lower.includes('mpeg') || lower.includes('mp3'))
+        return 'mp3';
+    if (lower.includes('mp4') || lower.includes('m4a') || lower.includes('aac'))
+        return 'm4a';
+    if (lower.includes('ogg'))
+        return 'ogg';
+    return undefined;
+}

package/client/voice-recorder.d.ts

@@ -0,0 +1,27 @@
+/** Why recording failed; the user reads labels `voice.<code>`. */
+export type VoiceRecorderFailureCode = 'unsupported' | 'permission' | 'unavailable' | 'failed' | 'empty';
+/** Headless MediaRecorder session for turn-composer voice notes. */
+export declare class ComposerVoiceRecorder {
+    private readonly accept;
+    private readonly onLevel?;
+    private stream;
+    private recorder;
+    private chunks;
+    private audioContext;
+    private analyser;
+    private source;
+    private rafId;
+    private mime;
+    private recording;
+    constructor(accept: string[], onLevel?: ((level: number) => void) | undefined);
+    start(): Promise<void>;
+    stop(): Promise<File>;
+    cancel(): void;
+    dispose(): void;
+    private startMeter;
+    private stopMeter;
+    private disposeTracks;
+}
+export declare function isVoiceRecorderFailure(value: unknown): value is Error & {
+    readonly code: VoiceRecorderFailureCode;
+};

package/client/voice-recorder.js

@@ -0,0 +1,162 @@
+import { describeError } from '@theoremjs/agents';
+import { pickMediaRecorderMime } from '@theoremjs/agents/interface';
+import { timeDomainBytesToLevel } from "./audio-level.js";
+class VoiceRecorderFailure extends Error {
+    code;
+    /** `detail` is raw diagnostic text for the builder, never shown to the user. */
+    constructor(code, detail) {
+        super(detail ?? code);
+        this.name = 'VoiceRecorderFailure';
+        this.code = code;
+    }
+}
+function extensionForMime(mime) {
+    if (mime.includes('webm'))
+        return 'webm';
+    if (mime.includes('mp4'))
+        return 'm4a';
+    if (mime.includes('wav'))
+        return 'wav';
+    if (mime.includes('mpeg'))
+        return 'mp3';
+    return 'bin';
+}
+function isPermissionDenied(err) {
+    return err instanceof DOMException && err.name === 'NotAllowedError';
+}
+/** Headless MediaRecorder session for turn-composer voice notes. */
+export class ComposerVoiceRecorder {
+    accept;
+    onLevel;
+    stream = null;
+    recorder = null;
+    chunks = [];
+    audioContext = null;
+    analyser = null;
+    source = null;
+    rafId = 0;
+    mime = '';
+    recording = false;
+    constructor(accept, onLevel) {
+        this.accept = accept;
+        this.onLevel = onLevel;
+    }
+    async start() {
+        this.disposeTracks();
+        const mime = pickMediaRecorderMime(this.accept);
+        if (!mime) {
+            throw new VoiceRecorderFailure('unsupported');
+        }
+        try {
+            this.stream = await navigator.mediaDevices.getUserMedia({
+                audio: {
+                    channelCount: 1,
+                    echoCancellation: true,
+                    noiseSuppression: true,
+                    autoGainControl: true,
+                },
+            });
+        }
+        catch (err) {
+            throw new VoiceRecorderFailure(isPermissionDenied(err) ? 'permission' : 'unavailable', describeError(err));
+        }
+        this.mime = mime;
+        this.chunks = [];
+        this.recorder = new MediaRecorder(this.stream, { mimeType: mime });
+        this.recorder.ondataavailable = (event) => {
+            if (event.data.size > 0)
+                this.chunks.push(event.data);
+        };
+        this.recorder.start(250);
+        this.recording = true;
+        this.startMeter();
+    }
+    async stop() {
+        if (!this.recorder || !this.recording) {
+            // labels-exempt: internal diagnostic; the user reads voice.empty
+            throw new VoiceRecorderFailure('empty', 'stop without a recording');
+        }
+        const recorder = this.recorder;
+        const blob = await new Promise((resolve, reject) => {
+            recorder.onerror = () => {
+                reject(new VoiceRecorderFailure('failed'));
+            };
+            recorder.onstop = () => {
+                const parts = this.chunks;
+                if (parts.length === 0) {
+                    reject(new VoiceRecorderFailure('empty'));
+                    return;
+                }
+                resolve(new Blob(parts, { type: this.mime }));
+            };
+            recorder.stop();
+        });
+        this.recording = false;
+        this.stopMeter();
+        this.disposeTracks();
+        if (blob.size === 0) {
+            throw new VoiceRecorderFailure('empty');
+        }
+        const ext = extensionForMime(this.mime);
+        return new File([blob], `voice-note.${ext}`, { type: this.mime });
+    }
+    cancel() {
+        this.recording = false;
+        this.stopMeter();
+        if (this.recorder && this.recorder.state !== 'inactive') {
+            try {
+                this.recorder.stop();
+            }
+            catch {
+                // why: stop() throws when the recorder stopped between the check and the call; it is stopped either way.
+            }
+        }
+        this.disposeTracks();
+        this.chunks = [];
+        this.recorder = null;
+    }
+    dispose() {
+        this.cancel();
+    }
+    startMeter() {
+        if (!this.stream)
+            return;
+        const AudioContextClass = globalThis.AudioContext;
+        this.audioContext = new AudioContextClass();
+        this.analyser = this.audioContext.createAnalyser();
+        this.analyser.fftSize = 2048;
+        this.source = this.audioContext.createMediaStreamSource(this.stream);
+        this.source.connect(this.analyser);
+        const tick = () => {
+            if (!this.analyser || !this.recording)
+                return;
+            const data = new Uint8Array(this.analyser.fftSize);
+            this.analyser.getByteTimeDomainData(data);
+            this.onLevel?.(timeDomainBytesToLevel(data));
+            this.rafId = requestAnimationFrame(tick);
+        };
+        this.rafId = requestAnimationFrame(tick);
+    }
+    stopMeter() {
+        cancelAnimationFrame(this.rafId);
+        this.rafId = 0;
+        this.onLevel?.(0);
+        this.source?.disconnect();
+        this.analyser?.disconnect();
+        this.source = null;
+        this.analyser = null;
+        if (this.audioContext && this.audioContext.state !== 'closed') {
+            void this.audioContext.close();
+        }
+        this.audioContext = null;
+    }
+    disposeTracks() {
+        for (const track of this.stream?.getTracks() ?? []) {
+            track.stop();
+        }
+        this.stream = null;
+    }
+}
+export function isVoiceRecorderFailure(value) {
+    return value instanceof VoiceRecorderFailure;
+}