@alexkroman1/aai-ui 0.16.0 → 0.17.0

package/dist/types.d.ts

@@ -56,9 +56,13 @@ export declare const VOICE_CAPTURE_CONSTRAINTS: MediaTrackConstraints;
  *   until the next completed handshake, so a later frame cannot quietly paint
  *   over the banner explaining a dead call.
  *
+ * The set is OPEN (`| (string & {})`): a later release may add a state, so a
+ * `switch` over it needs a `default`, and a lookup keyed by it needs a
+ * fallback for a state it has no entry for.
+ *
  * @public
  */
-export type AgentState = "disconnected" | "connecting" | "ready" | "listening" | "thinking" | "speaking" | "error";
+export type AgentState = "disconnected" | "connecting" | "ready" | "listening" | "thinking" | "speaking" | "error" | (string & {});
 /**
  * A chat message exchanged between user and assistant.
  *
@@ -67,6 +71,7 @@ export type AgentState = "disconnected" | "connecting" | "ready" | "listening" |
  * surfaced via `SessionSnapshot.toolCalls` (or `useEvent` for `ctx.send`
  * events).
  *
+ * @sealed
  * @public
  */
 export type ChatMessage = {
@@ -76,14 +81,19 @@ export type ChatMessage = {
      * render key.
      */
     id: number;
-    /** The sender of the message. */
-    role: "user" | "assistant";
+    /**
+     * The sender of the message. Open (`| (string & {})`) so a later sender is
+     * not a break: render anything that is not `"user"` the way you render
+     * `"assistant"`, or skip it.
+     */
+    role: "user" | "assistant" | (string & {});
     /** The text content of the message. */
     content: string;
 };
 /**
  * Info about a tool call for display in the UI.
  *
+ * @sealed
  * @public
  */
 export type ToolCallInfo = {
@@ -105,7 +115,13 @@ export type ToolCallInfo = {
      * now actually compiles.
      */
     args: Record<string, DefaultToolResult>;
-    status: "pending" | "done";
+    /**
+     * `"pending"` until the tool returns, then `"done"`. A tool that FAILED is
+     * `"done"` too: the wire reports a failure as a completion whose `result` is
+     * the error text the model read. Open (`| (string & {})`) so a later status
+     * is not a break — treat anything but `"pending"` as settled.
+     */
+    status: "pending" | "done" | (string & {});
     result?: string | undefined;
     /**
      * Monotonically increasing, session-unique insertion sequence number.
@@ -128,6 +144,7 @@ export type { SessionErrorCode } from "@alexkroman1/aai/protocol";
 /**
  * Error reported by the voice session.
  *
+ * @sealed
  * @public
  */
 export type SessionError = {
@@ -157,6 +174,7 @@ export type SessionError = {
  * defaults `platformUrl` from `location.href`, while `createBrowserSession`
  * requires it.
  *
+ * @input
  * @public
  */
 export type VoiceSessionOptions = {
@@ -314,6 +332,7 @@ export type VoiceSessionOptions = {
 /**
  * Minimal WebSocket constructor type accepted by {@link VoiceSessionOptions}.
  *
+ * @input
  * @public
  */
 export type WebSocketConstructor = {
@@ -323,6 +342,7 @@ export type WebSocketConstructor = {
 /**
  * Theme color overrides for the AAI UI components.
  *
+ * @input
  * @public
  */
 export type ClientTheme = {
@@ -337,3 +357,27 @@ export type ClientTheme = {
     /** Border color. Default: `#E4E4E7`. */
     border?: string;
 };
+/**
+ * The theme a component reads back from `useTheme()`: every
+ * {@link ClientTheme} field, filled with its default where the client set
+ * none.
+ *
+ * Its own type rather than `Required<ClientTheme>`, because the two travel in
+ * opposite directions — an author BUILDS a `ClientTheme` and only READS this —
+ * so a token added later can be optional on one and present on the other.
+ *
+ * @sealed
+ * @public
+ */
+export type ResolvedClientTheme = {
+    /** Background color, also painted on `html`/`body`. */
+    readonly bg: string;
+    /** Primary accent color. */
+    readonly primary: string;
+    /** Main text color. */
+    readonly text: string;
+    /** Surface/card color. */
+    readonly surface: string;
+    /** Border color. */
+    readonly border: string;
+};

package/dist/use-client-runs.d.ts

@@ -15,6 +15,7 @@ import type { ClientRun } from "@alexkroman1/aai";
 /**
  * Options for {@link useClientRuns}.
  *
+ * @input
  * @public
  */
 export type UseClientRunsOptions = {
@@ -29,6 +30,7 @@ export type UseClientRunsOptions = {
 /**
  * What {@link useClientRuns} returns.
  *
+ * @sealed
  * @public
  */
 export type UseClientRunsResult = {

package/dist/use-conversation-log.d.ts

@@ -23,6 +23,7 @@ import type { InboxEvent } from "./inbox-protocol.ts";
 /**
  * Options for {@link useConversationLog}.
  *
+ * @input
  * @public
  */
 export type UseConversationLogOptions = {
@@ -37,6 +38,7 @@ export type UseConversationLogOptions = {
 /**
  * What {@link useConversationLog} returns.
  *
+ * @sealed
  * @public
  */
 export type UseConversationLogResult = {

package/dist/use-conversation.d.ts

@@ -33,6 +33,12 @@ import { type UseUserTranscriptResult } from "./use-user-transcript.ts";
  * is the thing this hook computes — handing back two lists would hand back the
  * problem. `kind` is what a `switch` in a custom renderer narrows on.
  *
+ * `"other"` is the row this version cannot describe — today, an item a newer
+ * page wrote into a stored conversation log (`type` is the `kind` it was
+ * stored under). It is a member from the start so that a row kind added
+ * later is a value an existing `switch` already has a branch for, not a
+ * compile error: render nothing for it, or a placeholder.
+ *
  * @public
  */
 export type ConversationItem = {
@@ -41,10 +47,14 @@ export type ConversationItem = {
 } | {
     kind: "tool";
     toolCall: ToolCallInfo;
+} | {
+    kind: "other";
+    type: string;
 };
 /**
  * What {@link useConversation} returns.
  *
+ * @sealed
  * @public
  */
 export type UseConversationResult = {
@@ -107,15 +117,20 @@ export declare function interleave(messages: readonly ChatMessage[], toolCalls:
  *   const { items, streaming, transcript, thinking } = useConversation();
  *   return (
  *     <div>
- *       {items.map((item) =>
- *         item.kind === "message" ? (
- *           <p key={item.message.id} data-role={item.message.role}>
- *             {item.message.content}
- *           </p>
- *         ) : (
- *           <code key={item.toolCall.callId}>{item.toolCall.name}</code>
- *         ),
- *       )}
+ *       {items.map((item) => {
+ *         switch (item.kind) {
+ *           case "message":
+ *             return (
+ *               <p key={item.message.id} data-role={item.message.role}>
+ *                 {item.message.content}
+ *               </p>
+ *             );
+ *           case "tool":
+ *             return <code key={item.toolCall.callId}>{item.toolCall.name}</code>;
+ *           default:
+ *             return null;
+ *         }
+ *       })}
  *       {streaming !== null && <p data-role="assistant">{streaming}</p>}
  *       {transcript.speaking && <p data-role="user">{transcript.text}</p>}
  *       {thinking && <p>…</p>}

package/dist/use-copy.d.ts

@@ -17,6 +17,7 @@
  * What {@link useCopy} hands back — the click handler and the two readings a
  * button needs off one shared flash.
  *
+ * @sealed
  * @public
  */
 export type UseCopyResult = {

package/dist/use-download-url.d.ts

@@ -23,7 +23,11 @@
  * "downloading" as the same thing — so this reports it.
  */
 import type { WorkflowApi } from "./workflow-client.ts";
-/** Options for {@link useDownloadUrl}. */
+/**
+ * Options for {@link useDownloadUrl}.
+ *
+ * @input
+ */
 export type UseDownloadUrlOptions = {
     /** The client to read the bytes with. Defaults to one for the page's own agent. */
     api?: WorkflowApi;
@@ -31,6 +35,7 @@ export type UseDownloadUrlOptions = {
 /**
  * What {@link useDownloadUrl} reports.
  *
+ * @sealed
  * @public
  */
 export type UseDownloadUrlResult = {

package/dist/use-flash.d.ts

@@ -15,6 +15,7 @@
  * @typeParam T - What is being flashed. A `string` for a label; a record for a
  *   flash that has to say WHICH thing it belongs to, as `useCopy` does.
  *
+ * @sealed
  * @public
  */
 export type UseFlashResult<T> = {

package/dist/use-inbox.d.ts

@@ -33,6 +33,7 @@ import type { InboxEvent, InboxNotice } from "./inbox-protocol.ts";
 /**
  * Options for {@link useInbox}.
  *
+ * @input
  * @public
  */
 export type UseInboxOptions = {
@@ -63,6 +64,7 @@ export type UseInboxOptions = {
 /**
  * What {@link useInbox} returns.
  *
+ * @sealed
  * @public
  */
 export type UseInboxResult = {

package/dist/use-push-to-talk.d.ts

@@ -21,7 +21,11 @@
  * And one that is a nuisance rather than a stuck turn: the hold key is ignored
  * while focus is in a text field, where Space is a character.
  */
-/** Options for {@link usePushToTalk}. */
+/**
+ * Options for {@link usePushToTalk}.
+ *
+ * @input
+ */
 export type UsePushToTalkOptions = {
     /**
      * The keyboard key that holds the turn open, as a `KeyboardEvent.code` —
@@ -34,6 +38,7 @@ export type UsePushToTalkOptions = {
 /**
  * What {@link usePushToTalk} returns.
  *
+ * @sealed
  * @public
  */
 export type UsePushToTalkResult = {

package/dist/use-route-mutation.d.ts

@@ -26,6 +26,7 @@ import { type RouteMethod } from "./route-fetch.ts";
 /**
  * Options for {@link useRouteMutation}.
  *
+ * @input
  * @public
  */
 export type UseRouteMutationOptions = {
@@ -45,6 +46,7 @@ export type UseRouteMutationOptions = {
 /**
  * Options for one {@link UseRouteMutationResult.run} call.
  *
+ * @input
  * @public
  */
 export type RouteMutationRunOptions = {
@@ -58,6 +60,7 @@ export type RouteMutationRunOptions = {
 /**
  * What {@link useRouteMutation} returns.
  *
+ * @sealed
  * @public
  */
 export type UseRouteMutationResult = {

package/dist/use-route.d.ts

@@ -13,6 +13,7 @@
 /**
  * Options for {@link useRoute}.
  *
+ * @input
  * @public
  */
 export type UseRouteOptions = {
@@ -28,6 +29,7 @@ export type UseRouteOptions = {
 /**
  * What {@link useRoute} returns.
  *
+ * @sealed
  * @public
  */
 export type UseRouteResult<T> = {

package/dist/use-session-controls.d.ts

@@ -14,6 +14,7 @@
 /**
  * What {@link useSessionControls} returns.
  *
+ * @sealed
  * @public
  */
 export type UseSessionControlsResult = {

package/dist/use-tap-to-talk.d.ts

@@ -31,6 +31,7 @@
 /**
  * Options for {@link useTapToTalk}.
  *
+ * @input
  * @public
  */
 export type UseTapToTalkOptions = {
@@ -56,14 +57,16 @@ export type UseTapToTalkOptions = {
 /**
  * What {@link useTapToTalk} returns.
  *
+ * @sealed
  * @public
  */
 export type UseTapToTalkResult = {
     /**
      * The call: `"idle"` (not meant to be running), `"connecting"`, or
-     * `"active"` — up, whatever the agent is doing.
+     * `"active"` — up, whatever the agent is doing. Open (`| (string & {})`) so
+     * a phase added later is not a break.
      */
-    phase: "idle" | "connecting" | "active";
+    phase: "idle" | "connecting" | "active" | (string & {});
     /** Whether the caller is live — mic open, in a realtime conversation. The button is ON. */
     live: boolean;
     /**

package/dist/use-user-transcript.d.ts

@@ -33,7 +33,11 @@
  * @internal
  */
 export declare const TRANSCRIBING_PLACEHOLDER = "\u2026";
-/** What {@link useUserTranscript} returns. */
+/**
+ * What {@link useUserTranscript} returns.
+ *
+ * @sealed
+ */
 export interface UseUserTranscriptResult {
     /**
      * True while the caller holds the turn — from speech detection to the final

package/dist/use-workflow-form.d.ts

@@ -42,6 +42,7 @@ import type { SubmitInputOf } from "./workflow-def-types.ts";
  * because a form is allowed more than one and a bar over "the upload" would
  * restart at zero partway through with nothing to say why.
  *
+ * @sealed
  * @public
  */
 export type UploadStatus = UploadProgress & {
@@ -72,6 +73,8 @@ export type UploadStatus = UploadProgress & {
  * the run is accepted, and `run` is non-`undefined` from before the bytes are
  * in, so a page can render `<WorkflowProgress>` beside the upload bar instead
  * of after it. Here the run does not exist until the last byte lands.
+ *
+ * @sealed
  */
 export type WorkflowSubmission<R = unknown, I = unknown> = {
     /**
@@ -190,7 +193,11 @@ export type WorkflowSubmission<R = unknown, I = unknown> = {
     /** The submit's own failure (a rejected input), or the watch's. */
     error: string | undefined;
 };
-/** Options for {@link useWorkflowSubmit}. */
+/**
+ * Options for {@link useWorkflowSubmit}.
+ *
+ * @input
+ */
 export type UseWorkflowSubmitOptions = {
     /** The client to start runs with. Defaults to one for the page's own agent. */
     api?: WorkflowApi;

package/dist/use-workflow-progress.d.ts

@@ -53,6 +53,11 @@
 import type { WorkflowApi } from "./workflow-client.ts";
 /** The slice of the client this needs: one method. */
 export type RunProgressReader = Pick<WorkflowApi, "streamOutput">;
+/**
+ * What {@link useWorkflowProgress} reports.
+ *
+ * @public @sealed
+ */
 export type UseWorkflowProgressResult<T = string> = {
     /** Every chunk the run has written, oldest first. */
     progress: T[];

package/dist/use-workflow-run.d.ts

@@ -23,6 +23,11 @@ export declare const DEFAULT_WORKFLOW_POLL_MS = 2000;
  * tab is open.
  */
 export declare const MAX_MISSING_READS = 3;
+/**
+ * What {@link useWorkflowRun} reports.
+ *
+ * @public @sealed
+ */
 export type UseWorkflowRunResult<R = unknown> = {
     /** Latest snapshot, or undefined before the first read lands. */
     run: WorkflowRun<R> | undefined;

package/dist/use-workflow-runs.d.ts

@@ -21,7 +21,11 @@
  * stale.
  */
 import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
-/** Options for {@link useWorkflowRuns}. */
+/**
+ * Options for {@link useWorkflowRuns}.
+ *
+ * @input
+ */
 export type UseWorkflowRunsOptions = {
     /** The client to read with. Defaults to one for the page's own agent. */
     api?: WorkflowApi;
@@ -39,7 +43,11 @@ export type UseWorkflowRunsOptions = {
     /** Skip the read entirely — for a page that does not know its workflow yet. */
     skip?: boolean;
 };
-/** What {@link useWorkflowRuns} reports. */
+/**
+ * What {@link useWorkflowRuns} reports.
+ *
+ * @sealed
+ */
 export type UseWorkflowRunsResult<R = unknown> = {
     /** The runs, newest first. Empty until the first read lands. */
     runs: WorkflowRun<R>[];

package/dist/use-workflow-stream.d.ts

@@ -76,8 +76,9 @@
  * `stream.ts`'s idle bound (five minutes of no new bytes) is what decides that a
  * pause has become an abandonment.
  */
-import type { AnyWorkflowDef, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
-import type { UseWorkflowSubmitOptions, WorkflowSubmission } from "./use-workflow-form.ts";
+import type { AnyWorkflowDef, UploadParallelOption, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import type { WorkflowSubmission } from "./use-workflow-form.ts";
+import type { WorkflowApi } from "./workflow-client.ts";
 import type { SubmitInputOf } from "./workflow-def-types.ts";
 /**
  * Options for {@link useWorkflowStream}.
@@ -103,8 +104,29 @@ import type { SubmitInputOf } from "./workflow-def-types.ts";
  * the file is readable — that number is the CONTIGUOUS prefix, so a run reading
  * ahead of the uplink sees the same growing file whether one connection or four
  * are filling it. What changes is only how fast it grows.
+ *
+ * Declared on its own rather than `Omit`ted from the submit options, so an
+ * option added to one hook is a decision about the other, not a side effect.
+ *
+ * @input
  */
-export type UseWorkflowStreamOptions = Omit<UseWorkflowSubmitOptions, "wait" | "recover">;
+export type UseWorkflowStreamOptions = {
+    /** The client to start runs with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /**
+     * Correlation key recorded with the run, for finding it again without the
+     * id. Not defaulted here — see above.
+     */
+    key?: string;
+    /** How often the fallback poll re-reads a live run. */
+    intervalMs?: number;
+    /**
+     * Send the file as concurrent parts instead of in one request — on by
+     * default, `false` opts out, `{ partBytes, concurrency }` tunes it. See
+     * `UploadOptions.parallel`.
+     */
+    parallel?: UploadParallelOption;
+};
 /**
  * What {@link useWorkflowStream} returns: a {@link WorkflowSubmission}, exactly.
  *

package/dist/use-workflows.d.ts

@@ -9,7 +9,11 @@
  */
 import type { WorkflowSummary } from "@alexkroman1/aai/workflow-api";
 import type { WorkflowApi } from "./workflow-client.ts";
-/** Options for {@link useWorkflows}. */
+/**
+ * Options for {@link useWorkflows}.
+ *
+ * @input
+ */
 export type UseWorkflowsOptions = {
     /** The client to read the listing with. Defaults to one for the page's own agent. */
     api?: WorkflowApi;
@@ -23,7 +27,11 @@ export type UseWorkflowsOptions = {
      */
     skip?: boolean;
 };
-/** What {@link useWorkflows} reports. */
+/**
+ * What {@link useWorkflows} reports.
+ *
+ * @sealed
+ */
 export type UseWorkflowsResult = {
     /** The agent's declared workflows, each with the JSON Schema of its input. */
     workflows: WorkflowSummary[];

package/dist/workflow-client.d.ts

@@ -68,6 +68,11 @@ export type { AgentClient, WorkflowApi, WorkflowInputOf, WorkflowOutputOf, Workf
  * status predicate beside the status union cannot have.
  */
 export { isTerminal } from "@alexkroman1/aai/workflow-api";
+/**
+ * Options for {@link createWorkflowApi}.
+ *
+ * @public @input
+ */
 export type WorkflowApiOptions = {
     /**
      * Base URL of the agent. Defaults to the page's own origin + path, which is

package/dist/workflow-field-kind.d.ts

@@ -18,9 +18,10 @@
  * studio's SDK-subpath list: mirroring "would just move the drift somewhere
  * new".
  *
- * So a NEW control added to `<WorkflowFields>` is a new member of
- * {@link WorkflowFieldKind}, and every reader of the rule finds out from the
- * type rather than from a table somebody remembered to edit.
+ * So a NEW control added to `<WorkflowFields>` is a new value of
+ * {@link WorkflowFieldKind}. The set is open, so that addition is not a break:
+ * a reader's `switch` keeps a `default` and treats a kind it does not know the
+ * way it treats `"none"`.
  */
 /**
  * The control a schema property renders as inside `<WorkflowFields>`.
@@ -37,9 +38,12 @@
  * text field is — the same value over the wire — so it is a hand-written swap
  * rather than a shape the schema can ask for.
  *
+ * Open (`| (string & {})`): a control added later is a new value, so read an
+ * unknown kind as `"none"`.
+ *
  * @public
  */
-export type WorkflowFieldKind = "text" | "number" | "select" | "checkbox" | "file" | "none";
+export type WorkflowFieldKind = "text" | "number" | "select" | "checkbox" | "file" | "none" | (string & {});
 /**
  * A property's declared type, taking the first non-null member of a union.
  *

package/dist/worklets/capture-processor.d.ts

@@ -1,4 +1,4 @@
 /** Raw worklet source — exported so tests can evaluate the processor directly. */
-export declare const captureProcessorSource = "\nclass CaptureProcessor extends AudioWorkletProcessor {\n  constructor(options) {\n    super();\n    this.recording = false;\n    const opts = options.processorOptions || {};\n    // The context runs at the STT rate, so this is both the input and the\n    // output rate \u2014 there is nothing to convert.\n    this.rate = opts.sampleRate || sampleRate;\n    // Int16 accumulation buffer: flushed to the main thread as one transferred\n    // ArrayBuffer once ~bufferSeconds of samples are batched. Sized 2x the\n    // flush target so a whole render quantum always fits before flushing.\n    this.targetSamples = Math.max(1, Math.round(this.rate * (opts.bufferSeconds || 0.1)));\n    this.pending = new Int16Array(this.targetSamples * 2);\n    this.pendingLen = 0;\n    // Dead-mic probe: samples left to inspect before concluding the device\n    // delivers nothing but digital silence. Only consumed while recording, so\n    // the cost disappears after the window (or after the first real sample).\n    this.probeSamplesLeft = Math.round(\n      (this.rate * (opts.silenceProbeMs ?? 1500)) / 1000,\n    );\n    this.port.onmessage = (e) => {\n      if (e.data.event === 'start') this.recording = true;\n      else if (e.data.event === 'stop') {\n        // Final flush so the tail of speech isn't dropped on close, then ack\n        // so the host knows the tail chunk (if any) has been posted and it is\n        // safe to tear the context down.\n        this.flush();\n        this.recording = false;\n        this.port.postMessage({ event: 'stopped' });\n      }\n    };\n  }\n\n  // Convert Float32 -> Int16 and append to the pending batch. Writes through\n  // an Int16Array directly (assignment truncates like DataView.setInt16).\n  accumulate(samples) {\n    let buf = this.pending;\n    if (this.pendingLen + samples.length > buf.length) {\n      // Defensive: only reachable if a render quantum outproduces the 1x\n      // headroom above the flush target (never with 128-sample quanta).\n      const grown = new Int16Array((this.pendingLen + samples.length) * 2);\n      grown.set(buf.subarray(0, this.pendingLen));\n      this.pending = grown;\n      buf = grown;\n    }\n    for (let i = 0; i < samples.length; i++) {\n      const s = Math.max(-1, Math.min(1, samples[i]));\n      buf[this.pendingLen++] = s < 0 ? s * 0x8000 : s * 0x7fff;\n    }\n  }\n\n  // Post the batched samples as one transferred ArrayBuffer and reset.\n  flush() {\n    if (this.pendingLen === 0) return;\n    const buffer = this.pending.buffer.slice(0, this.pendingLen * 2);\n    this.pendingLen = 0;\n    this.port.postMessage({ event: 'chunk', buffer }, [buffer]);\n  }\n\n  // Watch the first window of input for any nonzero sample. One is enough to\n  // prove the device is live \u2014 a real mic in a quiet room still carries a\n  // noise floor, so all-zeros means muted, wrong input, or no input at all.\n  probeForSilence(channel) {\n    for (let i = 0; i < channel.length; i++) {\n      if (channel[i] !== 0) {\n        this.probeSamplesLeft = 0;\n        return;\n      }\n    }\n    this.probeSamplesLeft -= channel.length;\n    if (this.probeSamplesLeft <= 0) {\n      this.port.postMessage({ event: 'silent' });\n    }\n  }\n\n  process(inputs) {\n    const input = inputs[0];\n    if (!input || !input[0] || !this.recording) return true;\n\n    if (this.probeSamplesLeft > 0) this.probeForSilence(input[0]);\n\n    this.accumulate(input[0]);\n    if (this.pendingLen >= this.targetSamples) this.flush();\n    return true;\n  }\n}\n\nregisterProcessor('capture-processor', CaptureProcessor);\n";
-declare const _default: string;
-export default _default;
+export declare const captureProcessorSource: string;
+declare const captureProcessorUrl: string;
+export default captureProcessorUrl;

package/dist/worklets/capture-processor.js

@@ -92,6 +92,6 @@ class CaptureProcessor extends AudioWorkletProcessor {
 
 registerProcessor('capture-processor', CaptureProcessor);
 `;
-var capture_processor_default = workletModuleUrl(captureProcessorSource);
+const captureProcessorUrl = workletModuleUrl(captureProcessorSource);
 //#endregion
-export { captureProcessorSource, capture_processor_default as default };
+export { captureProcessorSource, captureProcessorUrl as default };

package/dist/worklets/playback-processor.d.ts

@@ -1,4 +1,4 @@
 /** Raw worklet source — exported so tests can evaluate the processor directly. */
-export declare const playbackProcessorSource = "\nclass PlaybackProcessor extends AudioWorkletProcessor {\n  constructor(options) {\n    super();\n    const opts = options.processorOptions || {};\n    // The node's context IS the playback context (audio/voice-io.ts asserts its rate),\n    // so the worklet-global sampleRate is authoritative; the option exists\n    // for the node-less test harness.\n    const rate = opts.sampleRate ?? sampleRate;\n    // Kept, because every derived quantity below reads it and `bufferedMs` in\n    // process() is the one that used to read the worklet global instead. Those\n    // agree in production (the option is unset, so `rate` IS `sampleRate`) and\n    // diverge only in the node-less harness \u2014 which is the one place a spec\n    // could ever assert on the reported backlog, so the divergence made the\n    // number untestable rather than wrong.\n    this.rate = rate;\n    // The one fill target \u2014 for the start of a turn and for recovery after an\n    // underrun alike. If 'done' arrives first (short utterance), start\n    // immediately instead of waiting for audio that is never coming.\n    this.fillSamples = Math.floor((rate * (opts.fillMs ?? 200)) / 1000);\n    // Concealment source: a ring of the most recently played samples, looped\n    // under a decaying gain to cover a gap. Sized to the fade window, with a\n    // per-sample decay that reaches the floor exactly at its end.\n    this.concealCapacity = Math.max(1, Math.floor((rate * 40) / 1000));\n    this.concealBuf = new Float32Array(this.concealCapacity);\n    this.concealDecay = Math.exp(Math.log(0.001) / this.concealCapacity);\n    // Float32 ring buffer \u2014 PLAYBACK_BUFFER_SECONDS at the context sample\n    // rate. Allocated once for the node's lifetime; per-turn state resets via\n    // resetTurn(). writePos and readPos are absolute (monotonic) sample\n    // counts; the buffer is indexed modulo capacity so a longer reply keeps\n    // playing instead of writing past the end and going silent.\n    this.capacity = rate * 60;\n    this.samples = new Float32Array(this.capacity);\n    // Cadence for the 'progress' report in process(), counted in samples so\n    // the hot path never reads a clock. Survives resetTurn(): the host clamps\n    // upward only, so a stale count costs at most one extra report.\n    this.reportIntervalSamples = Math.floor((rate * 500) / 1000);\n    this.sinceReportSamples = 0;\n    // Platform endianness probe: the wire format is PCM16 little-endian, so\n    // the Int16Array fast path in ingestBytes is only valid on LE hosts\n    // (every shipping browser target; the DataView path is the fallback).\n    this.littleEndian = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;\n    this.resetTurn();\n\n    this.port.onmessage = (e) => {\n      const d = e.data;\n      if (d.event === 'write') {\n        this.ingestBytes(d.buffer);\n      } else if (d.event === 'interrupt') {\n        // Applied eagerly, not deferred to the next process(): onmessage and\n        // process() never interleave (one audio thread), and a deferred\n        // interrupt would let 'write'/'done' frames for the NEXT turn\n        // coalesce in ahead of it and be wiped by the reset along with the\n        // cancelled turn's audio.\n        this.stopTurn('interrupt');\n      } else if (d.event === 'done') {\n        this.isDone = true;\n        // Echoed back on this turn's 'stop' so the host can tell WHICH turn\n        // drained: a stop already in flight when a barge-in lands would\n        // otherwise settle the next turn's done() the moment it arrives.\n        this.doneTurn = d.turn ?? null;\n      }\n    };\n  }\n\n  // Reset per-turn state so the node is reusable across replies without\n  // reallocating the sample buffer or re-instantiating the worklet.\n  resetTurn() {\n    this.isDone = false;\n    // Host turn id carried by this turn's 'done' (null until one arrives).\n    this.doneTurn = null;\n    this.playing = false;\n    // Whether any real audio has been rendered this turn. Separates a turn's\n    // pre-roll (nothing to extrapolate from, and not a defect) from a\n    // mid-turn underrun.\n    this.hasPlayed = false;\n    // Carry-over byte for split samples across chunks\n    this.carry = null;\n    this.writePos = 0;\n    this.readPos = 0;\n    // Concealment ring state and the current fade position.\n    this.concealLen = 0;\n    this.concealWrite = 0;\n    this.concealPos = 0;\n    this.concealGain = 1;\n    // Episode flags, so a multi-quantum gap counts as one event.\n    this.concealing = false;\n    this.concealedSilence = false;\n    // Reported to the host on 'stop'. A fresh object per turn: the one just\n    // posted must not be mutated by the next turn.\n    this.stats = {\n      concealedSamples: 0,\n      silentConcealedSamples: 0,\n      concealmentEvents: 0,\n      silentConcealmentEvents: 0,\n    };\n  }\n\n  // End the current turn: notify the host and rearm for the next reply.\n  // Must NOT return false from process() \u2014 a processor that stops is dead\n  // for good, forcing a new node (and buffer) per reply.\n  // `reason` ('interrupt' | 'done') tells the host which turn boundary this\n  // stop belongs to \u2014 interrupt-stops are dropped host-side, flush() having\n  // already settled that turn \u2014 and `turn` names WHICH turn drained (the id\n  // this turn's 'done' carried), so a drain-stop still in flight when a\n  // barge-in lands cannot settle the next turn's done() early.\n  stopTurn(reason) {\n    this.port.postMessage({ event: 'stop', reason, turn: this.doneTurn, stats: this.stats });\n    this.resetTurn();\n  }\n\n  // Cover a quantum (from `start`) where real audio should have been.\n  //\n  // Before the turn's first samples there is nothing to extrapolate from, so\n  // the gap is plain silence and counted as nothing \u2014 WebRTC likewise only\n  // counts concealment once playout has begun. After that, loop the retained\n  // tail under a decaying gain: a hard zero-fill is a discontinuity mid-word,\n  // which is the click that makes a brief stall sound like breakage.\n  coverGap(out, start) {\n    if (!this.hasPlayed) {\n      out.fill(0, start);\n      return;\n    }\n    if (!this.concealing) {\n      this.concealing = true;\n      this.concealedSilence = false;\n      this.stats.concealmentEvents++;\n    }\n    const total = out.length - start;\n    const len = this.concealLen;\n    let silent = 0;\n    // Second condition: once the fade has decayed to the floor, every sample\n    // the loop would emit is 0 anyway \u2014 bulk-fill instead of running 128\n    // branchy iterations per quantum for the whole tail of a long stall.\n    if (len === 0 || this.concealGain < 0.001) {\n      out.fill(0, start);\n      silent = total;\n    } else {\n      let g = this.concealGain;\n      for (let i = start; i < out.length; i++) {\n        if (g < 0.001) {\n          // The fade has run out: keep counting the gap, but stop looping a\n          // fragment that is now inaudible anyway.\n          out[i] = 0;\n          silent++;\n          continue;\n        }\n        out[i] = this.concealBuf[this.concealPos] * g;\n        this.concealPos = this.concealPos + 1 === len ? 0 : this.concealPos + 1;\n        g *= this.concealDecay;\n      }\n      this.concealGain = g;\n    }\n    this.stats.concealedSamples += total;\n    if (silent > 0) {\n      this.stats.silentConcealedSamples += silent;\n      if (!this.concealedSilence) {\n        this.concealedSilence = true;\n        this.stats.silentConcealmentEvents++;\n      }\n    }\n  }\n\n  // Retain the tail of a rendered quantum as the next gap's concealment\n  // source, and close any episode the real audio just ended.\n  rememberTail(out, n) {\n    const cap = this.concealCapacity;\n    const take = Math.min(n, cap);\n    // Bulk copies (this runs on every cleanly rendered quantum): the tail is\n    // one contiguous source run, landing in at most two ring runs.\n    const tail = out.subarray(n - take, n);\n    const first = Math.min(take, cap - this.concealWrite);\n    this.concealBuf.set(tail.subarray(0, first), this.concealWrite);\n    if (take > first) this.concealBuf.set(tail.subarray(first), 0);\n    this.concealWrite = (this.concealWrite + take) % cap;\n    this.concealLen = Math.min(cap, this.concealLen + take);\n    // Read the loop oldest-first; once the ring is full the write cursor is\n    // the oldest retained sample.\n    this.concealPos = this.concealLen === cap ? this.concealWrite : 0;\n    this.concealing = false;\n    this.concealGain = 1;\n  }\n\n  ingestBytes(uint8) {\n    let bytes = uint8;\n\n    if (this.carry !== null) {\n      const merged = new Uint8Array(1 + bytes.length);\n      merged[0] = this.carry;\n      merged.set(bytes, 1);\n      bytes = merged;\n      this.carry = null;\n    }\n\n    if (bytes.length % 2 !== 0) {\n      this.carry = bytes[bytes.length - 1];\n      bytes = bytes.subarray(0, bytes.length - 1);\n    }\n\n    if (bytes.length === 0) return;\n    const numSamples = bytes.length / 2;\n    const cap = this.capacity;\n    const samples = this.samples;\n    if (this.littleEndian && (bytes.byteOffset & 1) === 0) {\n      // Fast path: 2-byte-aligned LE bytes wrap directly as an Int16Array;\n      // copy wrap-aware in at most two runs with no per-sample DataView call\n      // or modulo. This runs on the realtime audio thread.\n      const int16 = new Int16Array(bytes.buffer, bytes.byteOffset, numSamples);\n      let src = 0;\n      let dst = this.writePos % cap;\n      while (src < numSamples) {\n        const run = Math.min(numSamples - src, cap - dst);\n        for (let j = 0; j < run; j++) {\n          samples[dst + j] = int16[src + j] / 0x8000;\n        }\n        src += run;\n        dst = 0;\n      }\n    } else {\n      // Odd byte offset (or big-endian host): fall back to per-sample reads.\n      const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.length);\n      let dst = this.writePos % cap;\n      for (let i = 0; i < numSamples; i++) {\n        samples[dst] = view.getInt16(i * 2, true) / 0x8000;\n        dst++;\n        if (dst === cap) dst = 0;\n      }\n    }\n    this.writePos += numSamples;\n    // If the producer outran the consumer by more than the buffer holds, drop\n    // the oldest unplayed audio rather than reading samples we've overwritten.\n    if (this.writePos - this.readPos > this.capacity) {\n      this.readPos = this.writePos - this.capacity;\n    }\n  }\n\n  process(inputs, outputs) {\n    // No output wired up yet \u2014 nothing to render this quantum. Throwing here\n    // would permanently kill the processor (the node is persistent per\n    // session), so guard like the capture processor does.\n    if (!outputs[0] || !outputs[0][0]) return true;\n    const out = outputs[0][0];\n    const avail = this.writePos - this.readPos;\n\n    // Report the unplayed backlog to the host (`playback_progress`). This IS\n    // the closed-loop signal: the host otherwise models playback open-loop \u2014\n    // every forwarded chunk assumed to start playing on arrival at exactly\n    // 1.0x \u2014 and cannot see a buffer that has run ahead of the wall clock.\n    // Measured against a client draining at 0.6x, the host declared the line\n    // silent while it still held seconds of the reply, and then opened the\n    // speaking-edge gate over speech the caller had not heard.\n    //\n    // Sent from process() rather than a timer because this is the only place\n    // that sees the buffer on the audio thread; the counter is in QUANTA, so\n    // it costs an integer compare per render and no clock read. Silence is not\n    // reported: an empty buffer is what the host already assumes.\n    this.sinceReportSamples += out.length;\n    if (this.sinceReportSamples >= this.reportIntervalSamples) {\n      this.sinceReportSamples = 0;\n      if (avail > 0) {\n        this.port.postMessage({ event: 'progress', bufferedMs: (avail / this.rate) * 1000 });\n      }\n    }\n\n    // Filling: wait for the target. 'done' short-circuits it \u2014 what is\n    // buffered is all there will be, so there is nothing left to wait for.\n    if (!this.playing) {\n      if (avail >= this.fillSamples || this.isDone) {\n        this.playing = true;\n      } else {\n        this.coverGap(out, 0);\n        return true;\n      }\n    }\n\n    // Underrun: this quantum cannot be filled and more audio is still coming.\n    // Go back to filling and cover the gap, leaving\n    // readPos untouched \u2014 the fragment stays buffered and plays intact once\n    // the buffer recovers, instead of being dribbled out a few samples at a\n    // time for the rest of the turn.\n    if (avail < out.length && !this.isDone) {\n      this.playing = false;\n      this.coverGap(out, 0);\n      return true;\n    }\n\n    if (avail > 0) {\n      const n = Math.min(avail, out.length);\n      // Copy from the ring buffer, splitting across the wrap boundary.\n      const start = this.readPos % this.capacity;\n      const first = Math.min(n, this.capacity - start);\n      out.set(this.samples.subarray(start, start + first), 0);\n      if (n > first) out.set(this.samples.subarray(0, n - first), first);\n      this.readPos += n;\n      // Only reachable with n < out.length on the turn's final partial\n      // quantum (the underrun branch above catches every other case).\n      out.fill(0, n);\n      this.hasPlayed = true;\n      this.rememberTail(out, n);\n      return true;\n    }\n\n    // Drained and done: end the turn. Not reachable mid-turn \u2014 an empty\n    // buffer with audio still coming is the underrun branch above.\n    out.fill(0);\n    if (this.isDone) {\n      this.stopTurn('done');\n    }\n    return true;\n  }\n}\n\nregisterProcessor('playback-processor', PlaybackProcessor);\n";
-declare const _default: string;
-export default _default;
+export declare const playbackProcessorSource: string;
+declare const playbackProcessorUrl: string;
+export default playbackProcessorUrl;

package/dist/worklets/playback-processor.js

@@ -316,6 +316,6 @@ class PlaybackProcessor extends AudioWorkletProcessor {
 
 registerProcessor('playback-processor', PlaybackProcessor);
 `;
-var playback_processor_default = workletModuleUrl(playbackProcessorSource);
+const playbackProcessorUrl = workletModuleUrl(playbackProcessorSource);
 //#endregion
-export { playback_processor_default as default, playbackProcessorSource };
+export { playbackProcessorUrl as default, playbackProcessorSource };