@alexkroman1/aai-ui 5.13.2 → 6.1.0

package/dist/types.js

@@ -1,4 +1,4 @@
-import { CAPTURE_STOP_ACK_TIMEOUT_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_JITTER_MS, PLAYBACK_PROGRESS_INTERVAL_MS, PLAYBACK_REFILL_MS } from "@alexkroman1/aai";
+import { CAPTURE_STOP_ACK_TIMEOUT_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_JITTER_MS, PLAYBACK_PROGRESS_INTERVAL_MS, PLAYBACK_REFILL_MS } from "@alexkroman1/aai/internal";
 //#region types.ts
 /**
 * `getUserMedia` audio constraints for every capture path in this package.

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

@@ -0,0 +1,70 @@
+/**
+ * `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
+ *
+ * `SessionSnapshot.userTranscript` is `string | null`, and the two falsy values
+ * mean different things:
+ *
+ * - `null` — nobody is speaking. There is no partial turn.
+ * - `""` — speech HAS been detected and no words have come back yet. A live
+ *   session sits here for a few hundred milliseconds at the start of every turn.
+ *
+ * Read as one falsy check, those collapse and the indicator never appears at the
+ * start of a turn — which is the moment it is for. So every custom chrome writes
+ * `transcript !== null && (transcript === "" ? "…" : transcript)`, three
+ * templates did exactly that, and each one re-derived a protocol distinction
+ * from the type rather than from anything that told them.
+ *
+ * This is the same distinction as two named booleans, so a component can say
+ * what it means: render on `speaking`, show `text`, and use the SDK's own
+ * placeholder when there is nothing to show yet.
+ */
+/**
+ * Placeholder for "listening, no words yet" — the `""` case above.
+ *
+ * A one-character ellipsis rather than three dots, because it is read by a
+ * screen reader as an ellipsis and it does not reflow the row when the first
+ * real word replaces it.
+ *
+ * @public
+ */
+export declare const TRANSCRIBING_PLACEHOLDER = "\u2026";
+/** What {@link useUserTranscript} returns. */
+export interface UseUserTranscriptResult {
+    /**
+     * True while the caller holds the turn — from speech detection to the final
+     * transcript. This is the flag a live-transcript row renders on.
+     */
+    speaking: boolean;
+    /**
+     * The words so far, or {@link TRANSCRIBING_PLACEHOLDER} while there are none.
+     * Empty string when nobody is speaking.
+     */
+    text: string;
+    /**
+     * The raw partial: the words so far, `""` while there are none, and `null`
+     * when nobody is speaking. For a chrome that wants to render its own
+     * placeholder (or none).
+     */
+    partial: string | null;
+}
+/**
+ * Subscribe to the caller's in-progress turn.
+ *
+ * Narrowly subscribed — a component using this re-renders at STT-partial rate,
+ * which is exactly what it is for and exactly what a whole-page `useSession()`
+ * should not do.
+ *
+ * @example
+ * ```tsx
+ * import { useUserTranscript } from "@alexkroman1/aai-ui";
+ *
+ * function LiveTranscript() {
+ *   const { speaking, text } = useUserTranscript();
+ *   if (!speaking) return null;
+ *   return <div className="italic opacity-60">{text}</div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useUserTranscript(): UseUserTranscriptResult;

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

@@ -0,0 +1,136 @@
+/**
+ * The two hooks a FORM needs, as against the one a status view does.
+ *
+ * `useWorkflowRun` (`workflow-client.ts`) watches a run you already have.
+ * These two are what comes before it: `useWorkflows` reads the declared
+ * workflows so `<WorkflowFields>` can render a form from a schema, and
+ * `useWorkflowSubmit` starts a run and hands the id straight to
+ * `useWorkflowRun`.
+ *
+ * ## `useWorkflowSubmit` — a form's two halves in one hook
+ *
+ * A page that submits a workflow always needs the same four pieces of state:
+ * the run id, whether a submit is in flight, whether the RUN is still going, and
+ * whichever of the two failed. `link-digest` writes them out by hand, which is
+ * the right shape for a template teaching the primitives and the wrong shape to
+ * write a third time — and it is easy to get subtly wrong: dropping the previous
+ * run id before the new `POST` returns is what stops a finished result sitting
+ * under a form that is already submitting again.
+ *
+ * So this is `api.start` plus {@link useWorkflowRun}, with the state between
+ * them. It adds no transport of its own and holds no run state of its own; the
+ * watching (stream first, poll as its fallback, terminal stops) is entirely
+ * `useWorkflowRun`'s, and `run` here IS its run.
+ *
+ * ## Why it starts ASYNCHRONOUSLY even though a synchronous call exists
+ *
+ * `api.startAndWait` would collapse this to one request, and it is the wrong
+ * default for a page: it holds a socket open for up to a minute, answers nothing
+ * until it settles, and a page has `useWorkflowRun` — which survives a reload,
+ * shows progress, and costs one stream. The synchronous call is for callers with
+ * nowhere to put a watch (a script, a cron, a form POST from a server). Pass
+ * `wait` here when the page really does want one request, and the run is
+ * followed from the same id either way.
+ */
+import { type WorkflowSummary } from "@alexkroman1/aai";
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/** Options for {@link useWorkflows}. */
+export type UseWorkflowsOptions = {
+    /** The client to read the listing with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /**
+     * Skip the lookup entirely, reporting an empty listing that is not loading.
+     *
+     * For a caller that may or may not need the listing and cannot decide with a
+     * conditional hook — `<WorkflowFields>` handed a summary rather than a name is
+     * the one in this package. It reports `loading: false`, because a skipped
+     * lookup is finished rather than pending.
+     */
+    skip?: boolean;
+};
+/** What {@link useWorkflows} reports. */
+export type UseWorkflowsResult = {
+    /** The agent's declared workflows, each with the JSON Schema of its input. */
+    workflows: WorkflowSummary[];
+    /** True until the listing lands, so a form can hold its fields back. */
+    loading: boolean;
+    /** The lookup's failure. Set alongside an EMPTY list, which is why it exists. */
+    error: string | undefined;
+};
+/**
+ * Read the agent's declared workflows.
+ *
+ * What `<WorkflowFields>` renders a form FROM: each summary carries the JSON
+ * Schema of that workflow's input, converted server-side precisely so a browser
+ * can read it.
+ *
+ * The failure is reported rather than swallowed, because the alternative is an
+ * empty list — which renders as a form with no fields and reads as "this agent
+ * declares no workflows" about an agent that was merely unreachable.
+ *
+ * @public
+ */
+export declare function useWorkflows(opts?: UseWorkflowsOptions): UseWorkflowsResult;
+/** What {@link useWorkflowSubmit} returns. */
+export type WorkflowSubmission<R = unknown> = {
+    /**
+     * Start a run with this input. Resolves once the run EXISTS — progress
+     * arrives through `run` — so a `<Form>`'s handler can await it to know the
+     * submission was accepted.
+     */
+    submit: (input: unknown) => Promise<void>;
+    /** Clear the run and any error, putting the form back to its initial state. */
+    reset: () => void;
+    /** The run, once started, followed to completion. */
+    run: WorkflowRun<R> | undefined;
+    /**
+     * True from `submit()` until the run reaches a terminal status.
+     *
+     * The WORK, not the request: a run outlives its `POST`, and a submit button
+     * that re-enabled on the response would invite a second submission of work
+     * already in flight.
+     */
+    pending: boolean;
+    /** The submit's own failure (a rejected input), or the watch's. */
+    error: string | undefined;
+};
+/** Options for {@link useWorkflowSubmit}. */
+export type UseWorkflowSubmitOptions = {
+    /** 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. */
+    key?: string;
+    /**
+     * Hold the `POST` open until the run settles, up to this many ms — the
+     * synchronous mode. Omitted (the default) returns as soon as the run exists.
+     */
+    wait?: number;
+    /** How often the fallback poll re-reads a live run. */
+    intervalMs?: number;
+};
+/**
+ * Start a workflow from a form, and follow the run it creates.
+ *
+ * @typeParam R - The workflow's output type, which is what makes
+ *   `run.status === "completed"` narrow to a typed `run.output`. Derive it with
+ *   `WorkflowOutputOf<typeof myWorkflow>`.
+ *
+ * @example
+ * ```tsx
+ * import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ *
+ * function DigestForm() {
+ *   const { submit, run, pending, error } = useWorkflowSubmit("digest");
+ *   return (
+ *     <Form onSubmit={(values) => submit(values)} error={error}>
+ *       <TextField name="url" label="Link" type="url" required />
+ *       <SubmitButton pending={pending}>Digest</SubmitButton>
+ *       {run?.status === "completed" && <p>Done.</p>}
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowSubmit<R = unknown>(workflow: string, opts?: UseWorkflowSubmitOptions): WorkflowSubmission<R>;

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

@@ -0,0 +1,100 @@
+/**
+ * `useWorkflowProgress` — read what a run has WRITTEN while it runs.
+ *
+ * The sibling of `useWorkflowRun`, and the split between them is the whole
+ * reason this exists. That hook reports a run's STATE: the status transitions
+ * the world records, which every run has. This reports what the run itself
+ * wrote through `getWritable()`, which is the only thing a long run can say
+ * before it finishes — a snapshot carries a status and, once terminal, an
+ * output, and nothing in between. A page that shows only status shows
+ * "Working…" for ten minutes and then a result.
+ *
+ * ## There is no poll fallback, and that is not an omission
+ *
+ * `useWorkflowRun` degrades to polling `GET /runs/:id` because a run's STATE is
+ * readable that way. A run's written chunks are not: the stream is the only
+ * route to them, so an agent that does not serve it has no progress to give and
+ * `supported` says so once, rather than a poll pretending to look for something
+ * that is not there. A page renders its status line either way.
+ *
+ * ## Chunks are RETAINED, so this is a replay as much as a tail
+ *
+ * The run's stream keeps every chunk, so a page that mounts late — a reload, a
+ * second tab, a link opened tomorrow — reads the whole history from index 0 and
+ * arrives at the same list as one that watched throughout. That is what makes a
+ * durable run's progress durable too, and it is why the default `startIndex` is
+ * 0 rather than "from now": a tail-only default would make the same page show
+ * different things depending on when it opened.
+ *
+ * ## It RE-OPENS while the run is live, because a progress read is bounded
+ *
+ * The route answers with the chunks written when the request arrived and then
+ * ends, reporting `complete` — whether the run itself was terminal. It has to:
+ * a workflow stream signals its end only once CLOSED, and a progress channel
+ * written by one step after another is never closed, so a read that waited for
+ * the end would hang forever on a finished run. (It did: see the route's own
+ * doc.)
+ *
+ * So this hook re-opens from where it left off until a read comes back
+ * `complete`. That is a poll, and the honest description of progress is a durable
+ * log rather than a socket — but it is a poll of a CHEAP shape: each read asks
+ * only for chunks past the last index it saw, so a quiet run costs an empty
+ * answer rather than the whole log again.
+ */
+import type { WorkflowApi } from "./workflow-client.ts";
+/** The slice of the client this needs: one method. */
+export type RunProgressReader = Pick<WorkflowApi, "streamOutput">;
+export type UseWorkflowProgressResult<T = string> = {
+    /** Every chunk the run has written, oldest first. */
+    progress: T[];
+    /** The newest chunk, or undefined before the first one lands. */
+    latest: T | undefined;
+    /** True while the run is still being read — it may yet say more. */
+    streaming: boolean;
+    /**
+     * False once the agent has answered that it does not serve this route.
+     *
+     * Distinguishes "this deploy predates progress streams" from "the run has not
+     * written anything yet", which look identical from `progress` alone. A page
+     * uses it to hide the section rather than show an empty one forever.
+     */
+    supported: boolean;
+};
+/** How often a live run's progress is re-read once a bounded read has ended. */
+export declare const DEFAULT_PROGRESS_POLL_MS = 1000;
+/**
+ * Follow one run's progress stream.
+ *
+ * Passing `undefined` (nothing started yet) costs nothing, and reading stops for
+ * good once a read reports the run terminal — so a finished run costs one read.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowProgress } from "@alexkroman1/aai-ui";
+ *
+ * function Progress({ runId }: { runId?: string }) {
+ *   const { progress, streaming, supported } = useWorkflowProgress(runId);
+ *   if (!supported) return null;
+ *   return (
+ *     <pre>
+ *       {progress.join("\n")}
+ *       {streaming && "\n…"}
+ *     </pre>
+ *   );
+ * }
+ * ```
+ *
+ * @typeParam T - What the workflow writes. Defaults to `string`, which is what
+ *   a progress channel usually carries; a workflow writing objects names its own
+ *   shape. Nothing in the browser can verify it — the route describes no type —
+ *   so this is the page's assertion about its own agent, narrowed once here
+ *   rather than at every read.
+ *
+ * @public
+ */
+export declare function useWorkflowProgress<T = string>(runId: string | undefined, opts?: {
+    api?: WorkflowApi;
+    namespace?: string;
+    startIndex?: number;
+    intervalMs?: number;
+}): UseWorkflowProgressResult<T>;

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

@@ -0,0 +1,56 @@
+/**
+ * `useWorkflowRun` — watch one run until it settles.
+ *
+ * Split from `workflow-client.ts` on the seam that module's doc already draws:
+ * everything there is a REQUEST (one call, one answer, no React), and everything
+ * here is the loop that keeps asking. They are read for different reasons — the
+ * client is what a script or a `curl` equivalent needs, this is what a page needs
+ * — and only this half imports React.
+ *
+ * `workflow-events.ts` sits under it as the streaming fast path, and
+ * `use-workflow-form.ts` above it as the form-shaped caller.
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/** How often {@link useWorkflowRun} re-reads a live run when it has to poll. */
+export declare const DEFAULT_WORKFLOW_POLL_MS = 2000;
+/**
+ * Consecutive "no such run" reads {@link useWorkflowRun} tolerates before giving
+ * up on the id.
+ *
+ * Small on purpose: a 404 is a stable answer, so the budget exists only to
+ * absorb a first read that races the run's creation — not to keep hoping.
+ * Unbounded, a stale id polls (and, on the platform, BROKERS) for as long as the
+ * tab is open.
+ */
+export declare const MAX_MISSING_READS = 3;
+export type UseWorkflowRunResult<R = unknown> = {
+    /** Latest snapshot, or undefined before the first read lands. */
+    run: WorkflowRun<R> | undefined;
+    /** The last read's failure, cleared by the next successful one. */
+    error: string | undefined;
+    /** True while a non-terminal run is still being watched. */
+    polling: boolean;
+};
+/**
+ * Watch one run until it reaches a terminal status.
+ *
+ * A watch rather than a subscription because a run is durable and the page is
+ * not: it can complete while the tab is closed, on a different sandbox, hours
+ * later. There is no session to reconnect — the id is the whole state.
+ *
+ * The stream (`GET /runs/:id/events`) is tried first and the poll is its
+ * fallback, so an agent deployed before that route existed still works. Watching
+ * STOPS on a terminal status, so a finished run costs nothing; passing
+ * `undefined` (nothing started yet) also costs nothing.
+ *
+ * @typeParam R - The workflow's output type. Supplying it is what makes
+ *   `run.status === "completed"` narrow to a typed `run.output` instead of
+ *   `unknown`. Derive it with `WorkflowOutputOf<typeof myWorkflow>` — a
+ *   type-only import of `agent.ts` is erased, so it costs the bundle nothing.
+ *
+ * @public
+ */
+export declare function useWorkflowRun<R = unknown>(runId: string | undefined, opts?: {
+    api?: WorkflowApi;
+    intervalMs?: number;
+}): UseWorkflowRunResult<R>;

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

@@ -0,0 +1,71 @@
+/**
+ * The RUNS a workflow has had — the list a page shows beside its form.
+ *
+ * `useWorkflowRun` watches one run you already hold an id for, which is the
+ * right shape for the run a page just started and the wrong one for everything
+ * before it. A workflow app that only offers that leaves its own history
+ * unreachable: a page reload drops the id, and the only way back to yesterday's
+ * transcript is to have written the id down — which is what
+ * `transcription-workflow` asked people to do, with a text box for pasting one.
+ *
+ * `GET /workflows/runs?workflow=…` has always been able to answer this. This is
+ * the hook over it, so a page renders history instead of asking for an id.
+ *
+ * ## It re-reads on demand, and does not poll on its own
+ *
+ * A list is not a live view: the run a page cares about right now is already
+ * being watched by `useWorkflowRun`, and a second polling loop over the whole
+ * history would broker N requests a minute on the platform to re-learn what the
+ * first one already knows. So this reads once and hands back `refresh` — which
+ * a page calls when its own run settles, which is exactly when the list is
+ * stale.
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/** Options for {@link useWorkflowRuns}. */
+export type UseWorkflowRunsOptions = {
+    /** The client to read with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /** Most runs to return, newest first. The agent clamps its own ceiling. */
+    limit?: number;
+    /**
+     * Narrow to one correlation key — the `key` a run was started with.
+     *
+     * Omitted, the list is every recent run of the workflow, which is what an
+     * operator's page wants. A page showing "your" runs passes the key it started
+     * them with; there is no per-user filtering behind this, so the key IS the
+     * scoping mechanism.
+     */
+    key?: string;
+    /** Skip the read entirely — for a page that does not know its workflow yet. */
+    skip?: boolean;
+};
+/** What {@link useWorkflowRuns} reports. */
+export type UseWorkflowRunsResult<R = unknown> = {
+    /** The runs, newest first. Empty until the first read lands. */
+    runs: WorkflowRun<R>[];
+    /** True until the first read settles, and during an explicit refresh. */
+    loading: boolean;
+    /** The read's failure, alongside an empty list — which is why it exists. */
+    error: string | undefined;
+    /** Re-read now. Call it when a run this page started reaches a terminal status. */
+    refresh: () => void;
+};
+/**
+ * Read a workflow's recent runs.
+ *
+ * @typeParam R - The workflow's output type, so a completed run's `output` is
+ *   typed rather than `unknown`. Derive it with `WorkflowOutputOf`.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowRuns } from "@alexkroman1/aai-ui";
+ *
+ * function History() {
+ *   const { runs } = useWorkflowRuns("transcribe", { limit: 10 });
+ *   return <ul>{runs.map((run) => <li key={run.runId}>{run.status}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowRuns<R = unknown>(workflow: string | undefined, opts?: UseWorkflowRunsOptions): UseWorkflowRunsResult<R>;

package/dist/workflow-client.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Browser client for the workflow HTTP API (`aai/host/workflow-api.ts`).
+ *
+ * This is the whole client half of a WORKFLOW APP: an agent whose front door is
+ * a form rather than a microphone (`workflowApp()`) starts runs
+ * here and watches them for the answer. It deliberately does NOT go through
+ * `SessionCore` — there is no socket, no audio graph, and no session to resume.
+ *
+ * **The requests themselves are the SDK's now**
+ * (`createWorkflowApiClient`, `@alexkroman1/aai/workflow-api`), and what is left
+ * here is the one thing that is genuinely a BROWSER's: the default base URL.
+ * Every route, every query, the 404-is-an-answer rule and the `wait` clamp were
+ * written three times over — here, in the studio's Workflows card, and in
+ * `aai workflow` — and the parts the copies disagreed on were exactly the ones a
+ * reader cannot check by eye. The SDK module's doc carries that argument; this
+ * file must not grow a second implementation of any of it.
+ *
+ * The one thing worth knowing before using it: **a run outlives the page.**
+ * Starting one resolves as soon as the run is created, so `runId` is the only
+ * handle that matters and it stays valid across a reload, a different device, or
+ * `curl` — which is what makes `useWorkflowRun` a watch rather than a
+ * subscription to something the page owns.
+ *
+ * The loop that keeps asking lives in `use-workflow-run.ts`, and the streaming
+ * fast path under it in `workflow-events.ts`.
+ */
+import type { WorkflowRunSnapshot } from "@alexkroman1/aai";
+import { type WorkflowApi } from "@alexkroman1/aai/workflow-api";
+/**
+ * A run's observable state.
+ *
+ * Aliased from the SDK rather than restated. `import type` is erased entirely,
+ * so a second definition of the fields and the five-member status union would
+ * buy nothing and cost the one thing that matters — nothing would assert the two
+ * agree, so a status added to the SDK would never reach the browser type.
+ *
+ * `WorkflowRun` keeps the shorter name because it is what a page's own code
+ * writes; nothing in a browser needs the word "snapshot" to know a read returns
+ * one.
+ *
+ * It is GENERIC on the run's output, and a page supplies it — see
+ * {@link useWorkflowRun}. It does NOT have to restate that type: a page can name
+ * its own workflow and derive the rest with `WorkflowOutputOf`, pulling no
+ * server graph into the bundle.
+ *
+ * @public
+ */
+export type WorkflowRun<R = unknown> = WorkflowRunSnapshot<R>;
+/**
+ * A workflow's own output type, and the shape `GET /workflows` lists — both
+ * re-exported so a page needs ONE import to type its runs and render its form.
+ */
+export type { WorkflowOutputOf, WorkflowSummary } from "@alexkroman1/aai";
+/**
+ * A run status nothing will change again.
+ *
+ * Re-exported from the SDK rather than defined here. A second implementation
+ * listing two of the three terminal statuses would leave a cancelled run polled
+ * forever by a page while the agent considered it finished — the kind of drift a
+ * status predicate beside the status union cannot have.
+ */
+export { isTerminal } from "@alexkroman1/aai";
+/**
+ * The call set {@link createWorkflowApi} returns.
+ *
+ * Re-exported from the SDK rather than declared here: it IS the SDK's client,
+ * and a structural restatement would be a second thing to keep in step with the
+ * routes for no gain.
+ */
+export type { WorkflowApi } from "@alexkroman1/aai/workflow-api";
+export type WorkflowApiOptions = {
+    /**
+     * Base URL of the agent. Defaults to the page's own origin + path, which is
+     * right for a page the agent itself serves — the only case that exists today,
+     * and the reason this wrapper exists at all: the SDK client requires a base
+     * URL, because `location` does not exist in that half of the SDK.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer for an agent whose operator set `AAI_WORKFLOW_API_TOKEN`. A page
+     * served to the public has nothing to put here (and should not — it would be
+     * readable in the bundle); this exists for a programmatic caller written
+     * against the same client.
+     */
+    token?: string;
+};
+/**
+ * Create a workflow API client aimed at the agent serving this page.
+ *
+ * Hoist it out of the component that uses it. `useWorkflowRun` holds the client
+ * in a ref precisely so a fresh object per render does not restart its watch,
+ * but a client built in render is still a new `fetch` closure every time and
+ * reads as though it were free.
+ *
+ * @public
+ */
+export declare function createWorkflowApi(opts?: WorkflowApiOptions): WorkflowApi;

package/dist/workflow-events.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Watching a run over server-sent events — the PUSH half of `useWorkflowRun`.
+ *
+ * Its own module because the seam is clean: everything in `workflow-client.ts`
+ * is request/response shaping plus the poll, and this is one long-lived stream
+ * and the SSE parser it needs.
+ *
+ * @internal
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/**
+ * The slice of the client this needs: one method.
+ *
+ * Narrowed rather than taking the whole `WorkflowApi`, and the narrowing is the
+ * honest statement — nothing here reads a run, starts one, or cancels one, it
+ * opens ONE stream. It also makes a test double a plain object rather than a
+ * six-method stub cast into shape. A real client satisfies it structurally.
+ */
+export type RunWatcher = Pick<WorkflowApi, "watch">;
+/**
+ * Watch a run over SSE, falling back to the caller's poll on any failure.
+ *
+ * The poll stays the fallback rather than being replaced, and that is the whole
+ * shape of this: a stream is an optimisation over a mechanism that already
+ * works, so every way it can fail — an older agent with no `/events` route, a
+ * proxy that buffers, a network that drops it — has to degrade to the thing that
+ * does. What it buys is real, though: on the platform every polled read BROKERS,
+ * so N open tabs at `DEFAULT_WORKFLOW_POLL_MS` is N/2 brokered requests a
+ * second, each able to boot a sandbox. One stream per tab replaces all of it.
+ *
+ * `EventSource` is not used, for two reasons that both matter here: it cannot
+ * send an `Authorization` header (an agent with `AAI_WORKFLOW_API_TOKEN` set
+ * would be unreachable), and it reconnects on its own schedule, which would
+ * fight the caller's. A `fetch` stream gives both back.
+ *
+ * Returns a stop function. `onFallback` is called at most once, when this stream
+ * cannot be relied on and the poll should take over.
+ */
+export declare function watchRunEvents<R>(getClient: () => RunWatcher, runId: string, onRun: (run: WorkflowRun<R>) => void, onSettled: () => void, onFallback: () => void): () => void;

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.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    // Fill target for the start of a turn. If 'done' arrives first (short\n    // utterance), start immediately instead of waiting for audio that is\n    // never coming.\n    this.jitterSamples = Math.floor((rate * (opts.jitterMs ?? 400)) / 1000);\n    // Fill target after an underrun \u2014 see PLAYBACK_REFILL_MS.\n    this.refillSamples = Math.floor((rate * (opts.refillMs ?? 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    this.fillTarget = this.jitterSamples;\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 / sampleRate) * 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.fillTarget || 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 (at the refill target) 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.fillTarget = this.refillSamples;\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";
+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.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    // Fill target for the start of a turn. If 'done' arrives first (short\n    // utterance), start immediately instead of waiting for audio that is\n    // never coming.\n    this.jitterSamples = Math.floor((rate * (opts.jitterMs ?? 400)) / 1000);\n    // Fill target after an underrun \u2014 see PLAYBACK_REFILL_MS.\n    this.refillSamples = Math.floor((rate * (opts.refillMs ?? 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    this.fillTarget = this.jitterSamples;\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.fillTarget || 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 (at the refill target) 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.fillTarget = this.refillSamples;\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;