@alexkroman1/aai-ui 0.16.0 → 0.18.0

package/dist/workflow-submission.d.ts

@@ -0,0 +1,265 @@
+/**
+ * What a workflow SUBMISSION is, as a type: the object `useWorkflowSubmit` and
+ * `useWorkflowStream` both hand back. Moved out of `use-workflow-form.ts` at
+ * the source-length cap, on the seam `form-types.ts` is cut on — the two hooks
+ * and the form statechart all name these, and a type living in one of them
+ * would make the others import a hook to say what they return.
+ */
+import type { UploadProgress, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import type { FormValues } from "./components/form-types.ts";
+import type { WorkflowRun } from "./workflow-client.ts";
+import type { SubmitInputOf } from "./workflow-def-types.ts";
+/**
+ * What {@link WorkflowSubmission.upload} reports while the bytes are going.
+ *
+ * The SDK's per-request {@link UploadProgress} plus WHICH file it describes,
+ * 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 & {
+    /** The file being sent, by the name the picker gave it. */
+    name: string;
+    /** Which file of the submission this is, counting from 1. */
+    index: number;
+    /** How many files this submission sends in total. */
+    count: number;
+    /**
+     * Whether the person has parked this upload.
+     *
+     * A paused upload is not a stopped one: the windows already stored stay stored,
+     * `loaded` holds where it got to, and resuming sends what is missing rather than
+     * the file. So a bar rendering this reads "Paused at 62%", never "62% and
+     * frozen" — which is what a page could otherwise only guess from a number that
+     * stopped moving, the same ambiguity `complete` exists to remove on the run side.
+     */
+    paused: boolean;
+};
+/**
+ * The two marks a submission's wall clock is read from — press to settle,
+ * across the upload, the run, and the gap between them, which no server-side
+ * number can give: `output.elapsedMs` is the RUN's own clock and begins after
+ * the upload. Only the browser holds both ends.
+ *
+ * `performance.now()` marks rather than elapsed durations, and that is the
+ * load-bearing part: an elapsed number is stale the instant it is computed, so
+ * a page holding one has to re-render to keep it true. A mark lets the one
+ * section that prints a running clock re-render on its own interval and read
+ * `performance.now() - submittedAt` at render. Monotonic, so a clock
+ * correction cannot make a run look instant, or negative.
+ *
+ * @sealed
+ * @public
+ */
+export type WorkflowSubmissionTiming = {
+    /** When `submit()` was called on this mount, or `undefined` before the first. */
+    submittedAt?: number | undefined;
+    /**
+     * When the submission settled — the run reached a terminal status, or the
+     * submit itself failed — measured at that moment rather than at the next
+     * render. `undefined` while it is in flight, and for a run this page did
+     * not start (there was no press to time from).
+     */
+    settledAt?: number | undefined;
+};
+/**
+ * Who can find the run again — the lifetime of the key it was recorded under.
+ *
+ * - `"tab"` — `useWorkflowSubmit`'s own `sessionStorage` key: a reload or a
+ *   same-tab navigation finds the run; a new tab does not.
+ * - `"browser"` — a `localStorage` key (`key: { storage: "local" }`, or
+ *   `useRunKey({ storage: "local" })`), or a key the page supplied itself (an
+ *   account's id): any tab on this browser finds it, so closing the tab loses
+ *   nothing.
+ * - `"none"` — nothing will find it: `recover: false`, or `useWorkflowStream`,
+ *   whose run is reading the bytes THIS page is sending and is ended, not
+ *   orphaned, by a reload.
+ *
+ * `<WorkflowPendingNote>` reads it to say the right sentence; the raw fact is
+ * published so a page with its own note can too.
+ *
+ * @public
+ */
+export type WorkflowSubmissionScope = "tab" | "browser" | "none";
+/**
+ * What {@link useWorkflowSubmit} returns.
+ *
+ * @see {@link WorkflowStreamSubmission} — an ALIAS of this type, returned by
+ * `useWorkflowStream`, which is a drop-in sibling. Exactly two fields MEAN
+ * something different there, and both differences follow from WHEN the run is
+ * created: there, `submit()` resolves when the UPLOAD finishes rather than when
+ * 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> = {
+    /**
+     * 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: I) => Promise<void>;
+    /**
+     * Start a run from a `<Form>`'s values, which are UNVALIDATED.
+     *
+     * The same function as {@link WorkflowSubmission.submit}, with the type the
+     * form path can honestly offer. `FormValues` is `Record<string, unknown>`
+     * scraped off the DOM at submit time — a `<TextField name="limit">`
+     * contributes a string whatever the schema says — so the shape is not known
+     * here and the SERVER is what checks it against the workflow's schema.
+     *
+     * Two doors rather than one loose one: `submit` takes the workflow's own
+     * input type, so a hand-built object is checked at compile time and
+     * `submit({ ur1: 42 })` is an error; widening it to accept `FormValues` would
+     * have made every object satisfy it and given the typing back. Reaching for
+     * this one is the author saying "these came from a form", which is a fact
+     * about the values and not a cast.
+     */
+    submitForm: (values: FormValues) => Promise<void>;
+    /** Clear the run and any error, putting the form back to its initial state. */
+    reset: () => void;
+    /**
+     * End the current run's `sleep()` early — "file it now" — resolving how many
+     * pending sleeps were interrupted.
+     *
+     * Bound to the run this submission is following, which is the point: it is
+     * the only reason a page holding one of these hooks needed an `api` of its
+     * own. `0` is an answer rather than a failure (the run had already moved past
+     * its wait, or there is no run yet), so nothing here has to be guarded.
+     */
+    wake: () => Promise<number>;
+    /**
+     * Stop the current run, resolving whether this call is what ended it.
+     *
+     * `false` for a run that had already finished, and for no run at all — the
+     * SDK's contract, because two tabs pressing Stop is ordinary. Distinct from
+     * `reset()`, which puts the FORM back and leaves the run running.
+     */
+    cancel: () => Promise<boolean>;
+    /** The run, once started, followed to completion. */
+    run: WorkflowRun<R> | undefined;
+    /**
+     * True from `submit()` on this mount until `reset()` — did THIS page start
+     * the run it is showing?
+     *
+     * A page needs it to say the right sentence and cannot derive it: a run
+     * ADOPTED by the mount-time lookup after a reload looks exactly like one this
+     * page started. Six templates kept a `useState(false)` next to this hook, set
+     * it in their `onSubmit` and mirrored it in their `onClear` — shadow state
+     * for a fact only this hook can know, since it is the thing that decides
+     * between `submit()` and the recovery lookup. One of the six grew a fourth
+     * branch and had to move the whole note into its own module with its own
+     * spec, which is what a seam missing one layer down looks like.
+     *
+     * The RAW fact rather than a derived "recovered", deliberately: with `run`
+     * these are three states, not two, and the third is the one a page most needs
+     * to explain. `startedHere` is "you pressed the button"; `!startedHere &&
+     * !run` is the mount-time lookup still going; `!startedHere && run` is a run
+     * this browser started earlier, now in front of somebody who did not press
+     * anything. A boolean meaning only the last of those cannot express the
+     * middle one.
+     *
+     * @example
+     * ```ts
+     * declare const submission: import("@alexkroman1/aai-ui").WorkflowSubmission;
+     * const note = submission.startedHere
+     *   ? "You can close this tab or reload it — this page will find the run again."
+     *   : submission.run === undefined
+     *     ? "Looking for a run this tab started earlier…"
+     *     : "Still working on the run this tab started earlier. Reloading is safe.";
+     * ```
+     */
+    startedHere: boolean;
+    /**
+     * 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;
+    /**
+     * How far the submission's files have got, while any are still going.
+     *
+     * Undefined before the first byte and again from the moment the last one
+     * lands, so a page can render `{upload && <UploadProgressBar upload={upload} />}`
+     * and the bar exists exactly for as long as there is an upload to describe. A
+     * form with no files never sets it at all.
+     *
+     * The wait it covers is the one `run` cannot: a run does not EXIST until its
+     * input is stored, so `pending` is true and there is nothing to poll — which
+     * for a 200 MB recording is minutes of a page that looks stuck.
+     */
+    upload: UploadStatus | undefined;
+    /**
+     * Park the upload where it is, stopping the bytes in flight.
+     *
+     * The windows already stored stay stored, so `resumeUpload()` sends what is
+     * missing rather than the file — which is the difference between a pause a
+     * person will actually use on a 200 MB recording and a cancel dressed up as one.
+     *
+     * `submit()`'s promise stays unresolved across a pause, because the submission
+     * genuinely has not finished: the run does not exist until the last byte lands,
+     * so resolving here would tell a `<Form>` the work was accepted when nothing has
+     * been started. A no-op when there is no upload in flight.
+     */
+    pauseUpload: () => void;
+    /** Continue a paused upload, sending only the windows the store does not have. */
+    resumeUpload: () => void;
+    /** The submit's own failure (a rejected input), or the watch's. */
+    error: string | undefined;
+    /**
+     * Press-to-settle marks for the submission THIS mount made — see
+     * {@link WorkflowSubmissionTiming}. Both `undefined` before the first
+     * `submit()` and again after `reset()`; a run adopted by the mount-time
+     * lookup has no press to time from and sets neither.
+     */
+    timing: WorkflowSubmissionTiming;
+    /**
+     * Who can find the run again after this page is gone — see
+     * {@link WorkflowSubmissionScope}. Derived from the hook's options (`key`,
+     * `recover`), so a page never restates it; `<WorkflowPendingNote>` reads it.
+     */
+    scope: WorkflowSubmissionScope;
+};
+/**
+ * The submission `useWorkflowSubmit<D>` / `useWorkflowStream<D>` hands back for
+ * the workflow def `D`, named so a component can take one as a prop.
+ *
+ * The hook's own return is inferred, so a page that renders everything in one
+ * function never needs this. A page that splits does, and there was no way to
+ * write it from the outside without three names — `WorkflowSubmission`,
+ * `WorkflowOutputOf` and `SubmitInputOf` — composed by hand, which is what a
+ * `ReturnType<typeof useWorkflowSubmit>` cannot say because the hook is
+ * generic. `podcast-digest-workflow`'s `client.tsx` composed exactly that.
+ *
+ * @example
+ * ```tsx
+ * // file: agent.ts
+ * import { agent, workflow } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * export const dailyDigest = workflow({
+ *   input: z.object({ hour: z.number() }),
+ *   output: z.object({ posted: z.string() }),
+ *   run: async ({ hour }) => ({ posted: `daily at ${hour}:00` }),
+ * });
+ *
+ * export default agent({ name: "Digest", workflows: { dailyDigest } });
+ *
+ * // file: client.tsx
+ * import type { WorkflowSubmissionOf } from "@alexkroman1/aai-ui";
+ * import type { dailyDigest } from "./agent.ts";
+ *
+ * function ScheduleControls({ submission }: { submission: WorkflowSubmissionOf<typeof dailyDigest> }) {
+ *   return submission.run?.status === "completed" ? <p>{submission.run.output.posted}</p> : null;
+ * }
+ * ```
+ *
+ * @public
+ */
+export type WorkflowSubmissionOf<D> = WorkflowSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.7.0",
     "xstate": "^5.33.2",
-    "@alexkroman1/aai": "0.16.0"
+    "@alexkroman1/aai": "0.18.0"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",

package/dist/default-client/assets/audio-DzwGxdv4.js

@@ -1 +0,0 @@
-import{a as e,i as t,t as n}from"./index-BOTLwsNO.js";var r={echoCancellation:!0,noiseSuppression:!1,autoGainControl:!1,voiceIsolation:!1};function i(e,t,n){if(e!==t)throw Error(`Browser refused the ${n} sample rate: asked for ${t} Hz, got ${e} Hz`)}function a(e){let t=Error(`Audio ${e} worklet crashed`);return console.error(`[aai-ui]`,t.message),t}function o(e){e.then(e=>{for(let t of e.getTracks())t.stop()}).catch(()=>{})}function s(e,t,n){let r=new AudioWorkletNode(e,`capture-processor`,{channelCount:1,channelCountMode:`explicit`}),i=null;return r.port.onmessage=e=>{let r=e.data;r.event===`chunk`&&r.buffer?t(r.buffer):r.event===`silent`?n?.():r.event===`stopped`&&(i?.(),i=null)},{node:r,start(){r.port.postMessage({event:`start`})},stop(){let{promise:e,resolve:t}=Promise.withResolvers(),n=setTimeout(t,250);return i=()=>{clearTimeout(n),t()},r.port.postMessage({event:`stop`}),e}}}async function c(e){let{sampleRate:t,captureWorkletSrc:n,maxSeconds:a}=e,c=new AudioContext({sampleRate:t,latencyHint:`interactive`}),l=navigator.mediaDevices.getUserMedia({audio:{deviceId:{ideal:`default`},...r}}),u;try{[u]=await Promise.all([l,c.resume(),c.audioWorklet.addModule(n)]),i(c.sampleRate,t,`capture`)}catch(e){throw o(l),await c.close().catch(()=>{}),e}let d=Math.round(t*a)*2,f=[],p=0,m=!1,h=null,g=c.createMediaStreamSource(u),_=s(c,e=>{if(h){h.onChunk(e);return}for(f.push(e),p+=e.byteLength;p>d&&f.length>1;)p-=f.shift()?.byteLength??0},()=>{h?h.onSilent?.():m=!0});g.connect(_.node),_.start();let v=()=>{let e=f;return f=[],p=0,e},y=!1,b=async()=>{y||(y=!0,g.disconnect(),_.node.disconnect(),await c.close().catch(e=>{console.warn(`AudioContext close failed:`,e)}))};return{sampleRate:t,stream:u,ctx:c,handOff(e){h=e;let t=v();return t.length>0&&e.onBuffered(t),m&&e.onSilent?.(),{mic:g,capture:_}},async detach(){return await _.stop(),await b(),{chunks:v(),sampleRate:t}},async close(){y||await _.stop();for(let e of u.getTracks())e.stop();await b()}}}function l(e){let t=new Int16Array(e.length);for(let n=0;n<e.length;n++){let r=Math.max(-1,Math.min(1,e[n]??0));t[n]=r<0?r*32768:r*32767}return t.buffer}async function u(e,t,r){let i=e.reduce((e,t)=>e+t.byteLength/2,0);if(i===0)return[];if(t===r)return e;try{let a=Math.round(i*r/t),o=new OfflineAudioContext(1,a,r),s=o.createBuffer(1,i,t),c=s.getChannelData(0),u=0;for(let t of e)for(let e of new Int16Array(t))c[u++]=e/32768;let d=o.createBufferSource();d.buffer=s,d.connect(o.destination),d.start();let f=(await o.startRendering()).getChannelData(0),p=Math.max(1,Math.round(r*n)),m=[];for(let e=0;e<f.length;e+=p)m.push(l(f.subarray(e,e+p)));return m}catch(e){return console.warn(`[aai-ui] pre-connect audio dropped: resample failed`,e),[]}}async function d(e,t,n){let r=e.createMediaStreamSource(t),i=s(e,n.onMicData,n.onMicSilent);if(r.connect(i.node),n.buffered){let{chunks:t,sampleRate:r}=n.buffered,i=await u(t,r,e.sampleRate);i.length>0&&n.onBuffered(i)}return i.start(),{mic:r,capture:i}}async function f(n){let{sttSampleRate:s,ttsSampleRate:c,captureWorkletSrc:l,playbackWorkletSrc:u,onMicData:f,onError:p,onPlaybackStats:m,onPlaybackProgress:h,onMicSilent:g,preConnect:_}=n,v=n.onPreConnectAudio??(e=>{for(let t of e)f(t)}),y=_?.sampleRate===s?_:null,b=_&&!y?await _.detach():null,x=new AudioContext({sampleRate:c,latencyHint:`playback`}),S=!y&&s===c,C=y?.ctx??(S?x:new AudioContext({sampleRate:s,latencyHint:`interactive`}));async function w(){let e=S?[x]:[x,C];await Promise.all(e.map(e=>e.close().catch(e=>{console.warn(`AudioContext close failed:`,e)})))}let T=_?Promise.resolve(_.stream):navigator.mediaDevices.getUserMedia({audio:{deviceId:{ideal:`default`},...r}}),E;try{[E]=await Promise.all([T,x.resume(),C.resume(),y?void 0:C.audioWorklet.addModule(l),x.audioWorklet.addModule(u)]),i(C.sampleRate,s,`capture`),i(x.sampleRate,c,`playback`)}catch(e){throw o(T),await w(),e}let{mic:D,capture:O}=y?y.handOff({onBuffered:v,onChunk:f,onSilent:g}):await d(C,E,{onMicData:f,onMicSilent:g,buffered:b,onBuffered:v});O.node.onprocessorerror=()=>p?.(a(`capture`));let k=null,A=0,j=null,M=new AbortController;function N(){let e=j;j=null,e?.settle()}function P(e){e.stats&&e.stats.concealedSamples>0&&m?.(e.stats),e.reason!==`interrupt`&&(j===null||e.turn===j.turn)&&N()}function F(){if(k)return k;let e=new AudioWorkletNode(x,`playback-processor`);return e.connect(x.destination),e.port.onmessage=e=>{e.data.event===`stop`?P(e.data):e.data.event===`progress`&&h?.(e.data.bufferedMs)},e.onprocessorerror=()=>{let e=a(`playback`);N(),p?.(e)},k=e,e}let I={enqueue(e){M.signal.aborted||e.byteLength!==0&&F().port.postMessage({event:`write`,buffer:new Uint8Array(e)},[e])},done(){if(!k)return Promise.resolve();let n=++A;if(k.port.postMessage({event:`done`,turn:n}),x.state!==`running`)return N(),Promise.resolve();let{promise:r,resolve:i}=Promise.withResolvers();N();let a=()=>{clearInterval(o),clearTimeout(s),j?.settle===a&&(j=null),i()},o=setInterval(()=>{x.state!==`running`&&a()},e),s=setTimeout(a,t);return j={turn:n,settle:a},r},flush(){k&&(N(),k.port.postMessage({event:`interrupt`}))},async close(){if(!M.signal.aborted){M.abort(),await O.stop(),D.disconnect(),O.node.disconnect(),k&&k.disconnect();for(let e of E.getTracks())e.stop();await w()}},async[Symbol.asyncDispose](){await I.close()}};return I}export{f as createVoiceIO,c as openPreConnectCapture};