@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/notice-player.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `useInbox()`'s built-in playback: a notice's PCM through an `AudioContext` of
+ * its own.
+ *
+ * **Its own context, not the session's.** The session's playback context exists
+ * only while a session is up (it is built on the `config` frame and closed on
+ * hang-up), and a notice arrives exactly when no session is — that is the
+ * inbox's whole reason to exist. It also runs through a jitter-buffer worklet
+ * tuned for a streamed reply, and a notice is one finished buffer.
+ *
+ * **Unlocked by the first user gesture, because of the autoplay policy.** A
+ * context created outside a gesture starts `suspended` and stays silent until
+ * `resume()` is called INSIDE one — and a reminder arrives hours after the last
+ * click. So the player is unlocked from a capture-phase `pointerdown` /
+ * `keydown` listener (`useInbox` installs it), which creates and resumes the
+ * context while the browser still counts the page as activated; afterwards a
+ * notice plays whenever it lands. A page that has had no gesture at all plays
+ * nothing, which is the browser's rule and not one this can route around.
+ *
+ * **16 kHz** because that is what an inbox notice carries: the rate the device
+ * protocol fixed (`inbox.c` plays at `BOARD_SAMPLE_RATE`), so a step building a
+ * notice asks `stepSpeak` for it (`stepSpeak`'s own default is 24 kHz — a notice
+ * at that rate plays slow and low here; pass `play: false` and play it
+ * yourself). The buffer is created at 16 kHz and the context resamples it — no
+ * worklet, no resampler of ours.
+ */
+/** The rate a notice's PCM16LE mono is played at. */
+export declare const NOTICE_SAMPLE_RATE = 16000;
+/** The slice of `AudioBuffer` the player writes. */
+export type NoticeBuffer = {
+    getChannelData(channel: number): Float32Array;
+};
+/** The slice of `AudioBufferSourceNode` the player drives. */
+export type NoticeSource = {
+    buffer: NoticeBuffer | null;
+    onended: ((ev: never) => unknown) | null;
+    connect(destination: unknown): unknown;
+    start(): void;
+    stop(): void;
+};
+/**
+ * The slice of `AudioContext` the player uses — declared rather than `Pick`ed
+ * so a test's fake satisfies it without a cast, and injectable because jsdom
+ * has no `AudioContext`. `defaultContext()` below is what proves the real one
+ * still fits.
+ */
+export type NoticeAudioContext = {
+    readonly state: AudioContextState;
+    readonly destination: unknown;
+    resume(): Promise<void>;
+    close(): Promise<void>;
+    createBuffer(channels: number, length: number, sampleRate: number): NoticeBuffer;
+    createBufferSource(): NoticeSource;
+};
+/** A notice player — see the module doc. */
+export type NoticePlayer = {
+    /** Create and resume the context — call from inside a user gesture. */
+    unlock(): void;
+    /** Play `pcm` (PCM16LE mono at {@link NOTICE_SAMPLE_RATE}); empty audio plays nothing. */
+    play(pcm: Uint8Array): void;
+    /** Stop every notice still playing. */
+    stop(): void;
+    /** Stop, and release the context. A later `unlock()`/`play()` makes a new one. */
+    close(): void;
+};
+/**
+ * @param makeContext - How a context is made; the page's `AudioContext` by
+ *   default. Where there is none (a server render, jsdom) the player is silent.
+ */
+export declare function createNoticePlayer(makeContext?: (() => NoticeAudioContext) | undefined): NoticePlayer;

package/dist/page.d.ts

@@ -0,0 +1,114 @@
+/** @jsxImportSource react */
+/**
+ * `mountPage()` — mount a WORKFLOW APP's UI: React, theme, no session.
+ *
+ * The twin of `mountClient()` for an agent whose front door is a form rather than a
+ * microphone (`workflowApp()`). It is a separate entry rather than
+ * an option on `mountClient()` because of what `mountClient()` unavoidably does: it
+ * constructs a `BrowserSession`, which owns a WebSocket URL provider, an audio
+ * graph, and a microphone request. A flag would have to make all of that
+ * conditional, and every session hook would then have to answer "what does this
+ * mean with no session?" — so the honest split is two mounts. A page that wants
+ * voice uses `mountClient()`; a page that wants neither audio nor a socket uses this.
+ *
+ * Authoring is otherwise identical — the file is still `client.tsx`, still
+ * React, still Tailwind, still the same theme tokens — so a workflow app reads
+ * like every other agent. What it reaches for instead of `useSession()` is
+ * `useWorkflowSubmit()` / `useWorkflowRun()`, neither of which needs a client
+ * built for it.
+ *
+ * And `component` is OPTIONAL, the way `mountClient()`'s is: with none, this
+ * mounts the generated shell in `_page-shell.tsx`. That is also what a workflow
+ * app with NO `client.tsx` at all now gets — `default-client.tsx`, the prebuilt
+ * page, branches on the agent's declared front door and mounts this.
+ */
+import { type ComponentType } from "react";
+import type { ClientTheme } from "./types.ts";
+/**
+ * Configuration for {@link mountPage}.
+ *
+ * @public
+ */
+export type PageConfig = {
+    /**
+     * The root component, rendered instead of the generated shell.
+     *
+     * **Optional**, the way `mountClient()`'s is: leave it out and `mountPage()`
+     * renders a form per declared workflow, the run's progress, its failure and
+     * its output — see `_page-shell.tsx` for what that shell is composed of and
+     * why it is deliberately functional rather than designed. It was REQUIRED,
+     * because "a workflow app has no default shell to fall back to" — true of a
+     * session and false of the page, and it cost the six shipped workflow
+     * templates 220-511 lines each of the same composition.
+     */
+    component?: ComponentType;
+    /** CSS selector or DOM element to render into. Defaults to `"#app"`. */
+    target?: string | HTMLElement;
+    /**
+     * Page title. Set only when given, so a title the HTML shell declared is never
+     * clobbered — the same rule `mountClient()`'s custom-component tier follows.
+     */
+    name?: string;
+    /** Theme color overrides, read by the same tokens the voice components use. */
+    theme?: ClientTheme;
+};
+/**
+ * Handle returned by {@link mountPage}. `Disposable`, so `using` works.
+ *
+ * @public
+ */
+export type PageHandle = {
+    /** Unmount the React tree. */
+    dispose(): void;
+    /** Alias for `dispose` for use with `using`. */
+    [Symbol.dispose](): void;
+};
+/**
+ * Mount a page for an agent whose work happens in workflows.
+ *
+ * There is deliberately no session, no microphone, and no socket: the page talks
+ * to the agent over the workflow HTTP API (`useWorkflowSubmit`/`useWorkflowRun`),
+ * which is durable and outlives the tab.
+ *
+ * **Config only:** leave `component` out and the generated shell renders — a
+ * form per declared workflow, the run's progress, its failure, its output.
+ *
+ * **A custom component:** pass `component` and it is rendered inside the theme
+ * provider instead. The pieces the default shell is built from are all published
+ * (`useWorkflows`, `<WorkflowFields>`, `useWorkflowSubmit`,
+ * `<WorkflowProgress>`, `<WorkflowRunError>`), so replacing the shell does not
+ * mean starting from `fetch`.
+ *
+ * @example The default shell
+ * ```tsx
+ * import { mountPage } from "@alexkroman1/aai-ui";
+ *
+ * mountPage({ name: "Digest" });
+ * ```
+ *
+ * @example A custom component
+ * ```tsx
+ * import { mountPage, useWorkflows } from "@alexkroman1/aai-ui";
+ *
+ * function App() {
+ *   // No client to build and none to hoist: every workflow hook defaults to one
+ *   // aimed at the agent serving this page, built lazily and once.
+ *   const { workflows, loading } = useWorkflows();
+ *   if (loading) return <p>Loading…</p>;
+ *   return (
+ *     <ul>
+ *       {workflows.map((entry) => (
+ *         <li key={entry.name}>{entry.description ?? entry.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ *
+ * mountPage({ name: "Digest", component: App });
+ * ```
+ *
+ * @throws If the target element is not found in the DOM.
+ *
+ * @public
+ */
+export declare function mountPage(config?: PageConfig): PageHandle;

package/dist/phone.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `phoneE164` — a number as a person types it, in the E.164 form
+ * `VoiceSessionOptions.phone` must carry, or `undefined` when it cannot be
+ * one. The server strips punctuation too, but DROPS a number with no `+`
+ * country code (guessing one would text a stranger), so a settings field that
+ * accepts `(503) 555-0123` must say which country it means — this is where it
+ * says so, and where a page can tell the user the number will not be used
+ * before a connect silently ignores it.
+ *
+ * @module
+ */
+/**
+ * Options for {@link phoneE164}.
+ *
+ * @public
+ */
+export type PhoneE164Options = {
+    /**
+     * The country calling code to assume for a number typed WITHOUT one — `"1"`
+     * for the US and Canada, `"44"` for the UK. Without it, only a number that
+     * already starts with `+` (or the `00` international prefix) is accepted.
+     *
+     * With `"1"`, a 10-digit number takes `+1`, and an 11-digit one starting
+     * with `1` is taken as already carrying it. With any other code, one leading
+     * trunk `0` is dropped before the code is prepended (`020 7946 0958` with
+     * `"44"` is `+442079460958`).
+     */
+    countryCode?: string | undefined;
+};
+/**
+ * The phone number `typed` in E.164 form (`"+15035550123"`), or `undefined`
+ * when it cannot be one — see {@link PhoneE164Options} for how a number
+ * without a country code is read.
+ *
+ * @example The session's phone, from a stored setting, assuming North America
+ * ```ts
+ * import { mountClient, phoneE164 } from "@alexkroman1/aai-ui";
+ *
+ * declare function storedPhone(): string;
+ *
+ * mountClient({ phone: () => phoneE164(storedPhone(), { countryCode: "1" }) });
+ * ```
+ *
+ * @param typed - The number as entered.
+ * @param options - The country to assume; see {@link PhoneE164Options}.
+ * @returns The E.164 number, or `undefined`.
+ *
+ * @public
+ */
+export declare function phoneE164(typed: string, options?: PhoneE164Options): string | undefined;

package/dist/route-fetch.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `routeFetch` — a call to the agent's OWN JSON routes, `agent({ routes })`,
+ * which its server mounts under `/api`.
+ *
+ * Every page that used them wrote the same fifteen lines: resolve `/api/…`
+ * against the page, add `?client=` (a route's `req.clientId` is how it knows
+ * whose data to read), send the body as JSON, and turn a failure into an
+ * `Error` carrying the route's own `{ error }` sentence rather than a status
+ * code. Two of those are easy to get subtly wrong, and both are why this is
+ * here:
+ *
+ * - **The URL is resolved against the page's DIRECTORY**, not the origin, so an
+ *   agent served below a path (`/:slug/`) reaches its own `/:slug/api`. An
+ *   absolute `/api/…` would reach the origin's.
+ * - **A non-JSON failure** (a proxy's HTML 502, an empty 500) still becomes an
+ *   `Error` naming the method, path and status, never a `SyntaxError` from
+ *   parsing a body that was not JSON.
+ *
+ * `useRoute` (`use-route.ts`) is the reading half, for a component.
+ *
+ * @module
+ */
+/**
+ * The HTTP methods an `agent({ routes })` key can declare.
+ *
+ * @public
+ */
+export type RouteMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * Options for {@link routeFetch}.
+ *
+ * @public
+ */
+export type RouteFetchOptions = {
+    /**
+     * The client the call is about, sent as `?client=` — the route's
+     * `req.clientId`. `useClientId()` is the session's; absent or empty sends
+     * none.
+     */
+    client?: string | undefined;
+    /** The agent's base URL. Default: the page's own directory. */
+    baseUrl?: string | undefined;
+    /** Abort the request. */
+    signal?: AbortSignal | undefined;
+};
+/**
+ * Call one of the agent's own routes and return its JSON — see this module's
+ * doc for what it handles.
+ *
+ * `path` is the route as declared, without `/api`: `routeFetch("GET",
+ * "/memories")` calls `"GET /memories"`. A body is sent as JSON. A response
+ * that is not 2xx throws an `Error` whose message is the route's `{ error }`
+ * field when it answered one (`routeResponse(404, { error: "No such memory" })`),
+ * else `"<METHOD> <path>: <status>"`. A 2xx with no JSON body resolves `{}`.
+ *
+ * @example Saving a field for the session's client
+ * ```tsx
+ * import { routeFetch, useClientId } from "@alexkroman1/aai-ui";
+ *
+ * function SaveName({ name }: { name: string }) {
+ *   const client = useClientId();
+ *   return (
+ *     <button type="button" onClick={() => void routeFetch("PUT", "/profile", { name }, { client })}>
+ *       Save
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @typeParam T - The shape the route answers. Not checked: annotate what you know.
+ * @param method - The route's method.
+ * @param path - The route's path as declared, starting with `/`; `?query` allowed.
+ * @param body - Sent as JSON when given.
+ * @param options - `client`, `baseUrl` and `signal`; see {@link RouteFetchOptions}.
+ * @returns The parsed JSON body.
+ *
+ * @public
+ */
+export declare function routeFetch<T = unknown>(method: RouteMethod, path: string, body?: unknown, options?: RouteFetchOptions): Promise<T>;

package/dist/session/audio-effects.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The session core's side of the audio path: every socket frame and snapshot
+ * write the statechart decides on but cannot make itself.
+ *
+ * The split is the one `s2s-lifecycle.ts` draws in the runtime. WHEN a
+ * microphone opens, whether an opening is still wanted, and where audio goes
+ * before there is anywhere to play it are `session/audio-state.ts`'s;
+ * this module is HOW — and it is the only half that touches `conn`, the
+ * snapshot, or the wire, which is what lets the machine be specced without a
+ * browser.
+ */
+import type { SessionCommand } from "@alexkroman1/aai/protocol";
+import type { AudioPathEffects } from "./audio-state.ts";
+import type { MicSender } from "./mic.ts";
+import type { PreConnectAudio } from "./preconnect.ts";
+import type { SessionStateMachine } from "./state.ts";
+import { type ConnState, type SessionSnapshot } from "./types.ts";
+/** What the audio effects need from the owning session core. */
+export type AudioEffectsDeps = {
+    conn: ConnState;
+    updateState: (partial: Partial<SessionSnapshot>) => void;
+    /** The session's state and error, as one fact — see `session/state.ts`. */
+    agentState: SessionStateMachine;
+    sendJson: (msg: SessionCommand) => void;
+    /** The mic's wire half: live frames, and the pre-connect burst. */
+    mic: Pick<MicSender, "sendAudio" | "sendBuffered">;
+    /** The microphone opened at `connect()`, which the next bring-up adopts. */
+    preConnect: PreConnectAudio;
+};
+/** Build the effects for one session's audio path. */
+export declare function createAudioEffects(deps: AudioEffectsDeps): AudioPathEffects;

package/dist/session/audio-setup.d.ts

@@ -0,0 +1,57 @@
+/**
+ * How the audio path is OPENED: the module load, the mic grant, the worklet
+ * registration, and the {@link VoiceIO} those three produce.
+ *
+ * WHEN one is opened, whether it is still wanted by the time it settles, and
+ * what happens to audio that arrives meanwhile all live in
+ * `session/audio-state.ts` — the same split `s2s-lifecycle.ts` and
+ * `aai-runtime/src/transports/pipeline/speech/edges.ts` draw in the runtime, and for the same reason:
+ * nothing here reads or writes session state, so it is callable from an
+ * invoked actor and testable without one.
+ */
+import type { PreConnectCapture, VoiceIO } from "../audio/index.ts";
+type AudioModules = [typeof import("../audio/index.ts"), string, string];
+/**
+ * Load the audio module and worklet sources, memoized so a prefetch at
+ * `connect()` time overlaps the chunk fetch with the WebSocket handshake
+ * instead of serializing it behind the server's `config` frame. A failed
+ * load clears the memo so the next attempt retries the import.
+ */
+export declare function loadAudioModules(): Promise<AudioModules>;
+/** The audio parameters the server's `config` frame carries. */
+export type AudioPathConfig = {
+    sampleRate: number;
+    ttsSampleRate: number;
+};
+/**
+ * What a live audio path reports back.
+ *
+ * Both of the last two used to be guarded at the callback by
+ * `conn.generation.isCurrent(gen)`; they are plain reports now, and whether
+ * one still matters is the state machine's answer — see
+ * `session/audio-state.ts`.
+ */
+export type AudioPathCallbacks = {
+    /** Buffered PCM16 from the microphone, for the socket. */
+    onMicData(pcm16: ArrayBuffer): void;
+    /** Unplayed agent audio in the buffer, in ms — the host's closed playback loop. */
+    onProgress(bufferedMs: number): void;
+    /** A worklet processor died after setup: the audio path is gone. */
+    onFailure(message: string): void;
+    /**
+     * The audio captured before the session was configured, in order and at the
+     * STT rate — sent once, ahead of the first `onMicData` frame.
+     */
+    onPreConnectAudio(chunks: ArrayBuffer[]): void;
+};
+/**
+ * Open one audio path: load the worklets, ask for the microphone, and build
+ * the {@link VoiceIO} wired to `callbacks`.
+ *
+ * Rejects when any of the three refuses — a denied mic prompt being the
+ * ordinary case. The caller owns closing what this resolves: a path that comes
+ * up for a connection nobody wants any more is a live microphone, and no
+ * amount of cancellation upstream releases the device.
+ */
+export declare function openAudioPath(config: AudioPathConfig, callbacks: AudioPathCallbacks, preConnect?: Promise<PreConnectCapture | null> | null): Promise<VoiceIO>;
+export {};

package/dist/session/audio-state.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The browser session's AUDIO PATH — the mic grant, the worklets, and the
+ * {@link VoiceIO} they produce — as a statechart.
+ *
+ * It was a latch, an epoch counter and three buffers spread across
+ * `ConnState`, and every one of them was a question the position already
+ * answers:
+ *
+ * - **`audioSetupInFlight` was a dedup, and dedup is a state.**
+ *   `initAudioCapture` opened with `if (conn.audioSetupInFlight) return` and
+ *   closed with "only the init that still owns the flag may clear it", which is
+ *   an ownership problem a boolean cannot express and a position does not have.
+ *   Here `starting` simply does not handle `START`, and there is no flag to
+ *   hand back.
+ * - **`conn.generation` existed for this module and nothing else.** Four
+ *   `bump()` sites, four `isCurrent(gen)` reads, and its own field on
+ *   `ConnState`. All four bumps sat immediately after a `cleanupAudio()` that
+ *   had *just* cleared the in-flight flag — the reconnect close handler said so
+ *   outright ("cleanupAudio just cleared the in-flight flag, so a survivor
+ *   would otherwise pass the same-generation guard and double-run"). Two
+ *   mechanisms for one question, the second one layered on because the first
+ *   could not stop the work already running. A stopped `invoke` can, so the
+ *   counter is gone.
+ * - **A counter cannot tell two bring-ups in ONE generation apart, and they
+ *   happen.** A repeated `config` frame on a live connection re-opened the path
+ *   without bumping anything, so the outgoing `VoiceIO`'s `onError` still
+ *   passed `isCurrent(gen)` and could tear down the replacement that had just
+ *   taken its slot. `PROGRESS` and `IO_FAILED` carry the instance that fired
+ *   them now, and identity is exact where a counter was approximate.
+ * - **`preInitAudio` / `preInitDone` are only meaningful while the path is
+ *   down.** As connection fields they were readable — and writable — from
+ *   anywhere; as context of `down`/`starting` they are cleared by entering
+ *   `down` rather than by three call sites remembering to.
+ *
+ * ## What cancellation does NOT do, and the one guard that had to survive
+ *
+ * Stopping the `bringUp` actor hides its resolution; it does not close a
+ * microphone the browser has already granted. So `bringUp` checks its own
+ * `signal` after `openAudioPath` settles and releases what it built. That is
+ * the single remaining "is this still wanted?" test, and it lives in the
+ * producer — which owns the value nobody adopted — rather than at the four
+ * consumer sites that used to re-ask.
+ *
+ * ## Effects stay in the session core
+ *
+ * The machine owns WHEN. Every HOW — the socket frame, the snapshot write, the
+ * turn-boundary drain — arrives as an injected {@link AudioPathEffects} call,
+ * the same shape `s2s-lifecycle.ts` uses. So this module touches no socket and
+ * no snapshot.
+ */
+import type { VoiceIO } from "../audio/index.ts";
+import type { AudioPathCallbacks, AudioPathConfig } from "./audio-setup.ts";
+/** Where the audio path is. */
+export type AudioPathPhase = "down" | "starting" | "up";
+/**
+ * The session core's side of the machine: everything the audio path decides to
+ * do but does not know how to.
+ */
+export type AudioPathEffects = {
+    /**
+     * Open one audio path — `openAudioPath` in `session/audio-setup.ts`.
+     * Injected rather than imported so this module needs no browser: the specs
+     * hand it a promise they resolve by hand, which is the only way to hold a
+     * bring-up open across the events that abandon it.
+     */
+    open(config: AudioPathConfig, callbacks: AudioPathCallbacks): Promise<VoiceIO>;
+    /** Relay captured microphone audio to the server. */
+    sendMicAudio(pcm16: ArrayBuffer): void;
+    /**
+     * Relay the audio captured before the session was configured — one burst,
+     * ahead of the first live frame (`session/preconnect.ts`).
+     */
+    sendPreConnectAudio(chunks: ArrayBuffer[]): void;
+    /** Tell the server how much agent audio is still unplayed. */
+    reportProgress(bufferedMs: number): void;
+    /** Tell the server the microphone is live. */
+    announceReady(): void;
+    /** The microphone is live: the snapshot's `recording`. */
+    micLive(): void;
+    /** Back to the mic, with no audio left to wait for. */
+    listen(): void;
+    /**
+     * Wait for `io` to drain, then listen — guarded by the turn boundary, so a
+     * completion landing after a barge-in or a teardown is discarded.
+     */
+    settleWhenDrained(io: VoiceIO): void;
+    /**
+     * Report a non-fatal audio failure and stop the mic. Non-fatal because the
+     * socket may well still be fine, so a later server frame is allowed to
+     * recover the banner — see `session/state.ts`.
+     */
+    reportFailure(message: string): void;
+    /**
+     * The audio path is gone: end whatever turn it was playing.
+     *
+     * Paired with the release below rather than folded into it, because the
+     * bump has to happen on every path into `down` — including a bring-up that
+     * failed before there was anything to close.
+     */
+    endTurn(): void;
+    /** Close `io` and let go of the microphone. Best-effort. */
+    release(io: VoiceIO): void;
+};
+/** Everything that happens to the audio path. */
+export type AudioPathEvent = 
+/** The server's `config` frame: bring the path up for these rates. */
+{
+    type: "START";
+    config: AudioPathConfig;
+}
+/** A PCM16 chunk arrived for playback. */
+ | {
+    type: "CHUNK";
+    chunk: ArrayBuffer;
+}
+/** The server finished sending this turn's audio. */
+ | {
+    type: "DONE";
+}
+/** A live path reported its unplayed depth. */
+ | {
+    type: "PROGRESS";
+    io: VoiceIO;
+    bufferedMs: number;
+}
+/** A live path's worklet died. */
+ | {
+    type: "IO_FAILED";
+    io: VoiceIO;
+    message: string;
+}
+/** Release the audio path: hang-up, reconnect, fatal frame, session end. */
+ | {
+    type: "TEARDOWN";
+};
+/** The session core's handle on its audio path. */
+export type AudioPath = {
+    /** Where the path is. */
+    phase(): AudioPathPhase;
+    /** The server named the audio rates: bring the path up. */
+    start(config: AudioPathConfig): void;
+    /** Play a chunk, or hold it until there is somewhere to play it. */
+    enqueue(chunk: ArrayBuffer): void;
+    /** The server finished this turn's audio. */
+    done(): void;
+    /**
+     * Barge-in: discard what is queued for playback.
+     *
+     * A read rather than an event — it moves the path nowhere, and a turn
+     * boundary is the caller's to declare (see `bargeIn`).
+     */
+    flush(): void;
+    /** Release the microphone and forget anything buffered. */
+    teardown(): void;
+};
+/** Create the audio path for one browser session. */
+export declare function createAudioPath(effects: AudioPathEffects): AudioPath;

package/dist/session/browser-session.d.ts

@@ -0,0 +1,30 @@
+import type { VoiceSessionOptions } from "../types.ts";
+import { type BrowserSession } from "./types.ts";
+/**
+ * Create a framework-agnostic voice session core that connects to an AAI
+ * server via WebSocket.
+ *
+ * Uses a subscribe/getSnapshot pattern for state management, compatible with
+ * React's `useSyncExternalStore` and other external store integrations.
+ *
+ * Most clients never call this: `mountClient()` creates a core and installs it in
+ * React context for the hooks. Reach for it directly when building a
+ * non-React UI (or wiring the session into another framework's store).
+ *
+ * @example
+ * ```ts
+ * import { createBrowserSession, type SessionSnapshot } from "@alexkroman1/aai-ui";
+ *
+ * declare function render(snapshot: SessionSnapshot): void;
+ *
+ * const session = createBrowserSession({ platformUrl: "https://host/my-agent/" });
+ * session.subscribe(() => render(session.getSnapshot()));
+ * session.start();
+ * ```
+ *
+ * @param options - Session configuration including the platform server URL.
+ * @returns A {@link BrowserSession} handle for controlling the session.
+ *
+ * @public
+ */
+export declare function createBrowserSession(options: VoiceSessionOptions): BrowserSession;

package/dist/session/close.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a socket's CLOSE means to the caller.
+ *
+ * One decision, in its own module because `session/browser-session.ts` is at its length cap
+ * and because the decision is worth reading on its own: which endings are
+ * ordinary, and which carry something the user has to be told.
+ *
+ * @module
+ */
+/**
+ * What to REPORT for a socket that closed for good, or null for an ordinary end.
+ *
+ * A sentence the peer wrote beats one this file invented. A guest that cannot
+ * build its runtime closes 1011 with the remedy already in it — "Anthropic LLM:
+ * missing API key. Set ANTHROPIC_API_KEY in the agent env." — and this handler
+ * used to discard `event.reason` entirely, so the one thing a misconfigured
+ * deployment needed to be told surfaced as "WebSocket connection error", or as a
+ * plain disconnect with nothing at all. Measured against a deployed agent with no
+ * provider key.
+ *
+ * A NORMAL close carries no reason worth showing (1000 is the caller hanging up
+ * or the server retiring a finished session; a browser reports a status-less
+ * close as 1005, which has no reason either), so the two ordinary endings are
+ * untouched.
+ */
+export declare function closeFailure(event: CloseEvent, socketErrored: boolean): string | null;