@missionsquad/browserai 0.1.0

package/dist/audio/recorder.js

@@ -0,0 +1,127 @@
+import { MicrophoneError } from "../errors.js";
+import { decodeAudioTo16kMono } from "./decode.js";
+export class MicRecorder {
+    #options;
+    #pending = false;
+    #abortPending = false;
+    #take = null;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    /** Whether a take is currently being captured (true between a successful start() and stop()). */
+    get recording() {
+        return this.#take !== null;
+    }
+    #streamEnded() {
+        try {
+            this.#options.onStreamEnded?.();
+        }
+        catch {
+            // A throwing host disposal hook must not interrupt mic/context teardown.
+        }
+    }
+    /**
+     * Start capturing. No-op (returns false) when already recording or a start is mid-flight.
+     * @throws {MicrophoneError} when the mic cannot be acquired (`permissionDenied` set for denials).
+     */
+    async start() {
+        if (this.#pending || this.#take)
+            return false;
+        this.#pending = true; // claimed synchronously before the getUserMedia await (double-press guard)
+        let stream = null;
+        let ctx = null;
+        try {
+            stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            if (this.#abortPending) {
+                // cancel() ran while the permission prompt / acquisition was pending — release and bail.
+                this.#abortPending = false;
+                stream.getTracks().forEach((track) => track.stop());
+                return false;
+            }
+            ctx = new AudioContext();
+            const source = ctx.createMediaStreamSource(stream);
+            try {
+                this.#options.onStreamReady?.({ context: ctx, source, stream });
+            }
+            catch {
+                // A throwing host visualization hook must not abort the take.
+            }
+            const recorder = new MediaRecorder(stream);
+            const chunks = [];
+            recorder.ondataavailable = (event) => chunks.push(event.data);
+            recorder.start();
+            this.#take = { ctx, stream, recorder, chunks };
+            return true;
+        }
+        catch (error) {
+            // Release anything acquired before the failure — otherwise the mic indicator stays lit.
+            stream?.getTracks().forEach((track) => track.stop());
+            this.#streamEnded();
+            if (ctx)
+                void ctx.close().catch(() => undefined);
+            throw new MicrophoneError(error);
+        }
+        finally {
+            this.#pending = false;
+        }
+    }
+    /**
+     * Stop the take and decode it to 16 kHz mono PCM. Returns null when nothing was recorded (no
+     * take in flight, or an empty capture). Always releases the mic, even if stopping throws.
+     */
+    async stop() {
+        const take = this.#take;
+        this.#take = null; // claim synchronously so a re-entrant stop can't double-clean
+        if (!take)
+            return null;
+        const { recorder, stream, ctx, chunks } = take;
+        try {
+            await new Promise((resolve) => {
+                // The recorder auto-stops when its track ends (device unplugged, permission revoked). stop()
+                // would then be a silent no-op and onstop would never fire — resolve immediately instead.
+                if (recorder.state === "inactive") {
+                    resolve();
+                    return;
+                }
+                recorder.onstop = () => resolve();
+                recorder.stop();
+            });
+        }
+        finally {
+            // Always release the mic and context — even if stop() threw (legacy InvalidStateError).
+            stream.getTracks().forEach((track) => track.stop());
+            this.#streamEnded();
+            await ctx.close().catch(() => undefined);
+        }
+        const blob = new Blob(chunks, { type: recorder.mimeType || "audio/webm" });
+        if (blob.size === 0)
+            return null;
+        return decodeAudioTo16kMono(await blob.arrayBuffer());
+    }
+    /** Abandon a take without decoding it (releases the mic; the audio is discarded). Also aborts a start() still awaiting the permission prompt. */
+    async cancel() {
+        if (this.#pending && !this.#take)
+            this.#abortPending = true; // start() releases the mic when getUserMedia resolves
+        const take = this.#take;
+        this.#take = null;
+        if (!take)
+            return;
+        const { recorder, stream, ctx } = take;
+        try {
+            await new Promise((resolve) => {
+                if (recorder.state === "inactive") {
+                    resolve();
+                    return;
+                }
+                recorder.onstop = () => resolve();
+                recorder.stop();
+            });
+        }
+        finally {
+            stream.getTracks().forEach((track) => track.stop());
+            this.#streamEnded();
+            await ctx.close().catch(() => undefined);
+        }
+    }
+}
+//# sourceMappingURL=recorder.js.map

package/dist/audio/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/audio/recorder.ts"],"names":[],"mappings":"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"}

package/dist/audio/streaming-player.d.ts

@@ -0,0 +1,29 @@
+export type StreamingAudioPlayer = {
+    /** Schedule one PCM chunk to play back-to-back after everything already scheduled. */
+    push(samples: Float32Array, sampleRate: number): void;
+    /** No more chunks; resolves (and tears down) once everything scheduled has finished playing. */
+    end(): Promise<void>;
+    /** Barge-in/error: stop playback now and tear down. Idempotent. */
+    stop(): void;
+};
+export type StreamingAudioPlayerOptions = {
+    /**
+     * Called once with the player's audio graph so hosts can tap it for visualization (e.g. connect an
+     * AnalyserNode to `gain`). The audible path is gain → destination only — do not connect the tap to
+     * the destination or audio doubles.
+     */
+    onGraphReady?: (graph: {
+        context: AudioContext;
+        gain: GainNode;
+    }) => void;
+    /** Called during teardown, before the context closes — dispose whatever onGraphReady created. */
+    onTeardown?: () => void;
+};
+/**
+ * Gapless player for streamed TTS: schedules each chunk's PCM into one AudioContext end-to-end.
+ * Chunks are butt-joined at a running cursor; if synthesis falls behind playback this yields a small
+ * silent gap rather than overlap. Teardown (close ctx) is idempotent, and `stop()` resolves any
+ * in-flight `end()` promise so a barge-in can never hang a waiting turn.
+ */
+export declare function createStreamingAudioPlayer(options?: StreamingAudioPlayerOptions): StreamingAudioPlayer;
+//# sourceMappingURL=streaming-player.d.ts.map

package/dist/audio/streaming-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-player.d.ts","sourceRoot":"","sources":["../../src/audio/streaming-player.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG;IACjC,sFAAsF;IACtF,IAAI,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACtD,gGAAgG;IAChG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACrB,mEAAmE;IACnE,IAAI,IAAI,IAAI,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAA;KAAE,KAAK,IAAI,CAAC;IAC1E,iGAAiG;IACjG,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,2BAAgC,GAAG,oBAAoB,CAwE1G"}

package/dist/audio/streaming-player.js

@@ -0,0 +1,82 @@
+/**
+ * Gapless player for streamed TTS: schedules each chunk's PCM into one AudioContext end-to-end.
+ * Chunks are butt-joined at a running cursor; if synthesis falls behind playback this yields a small
+ * silent gap rather than overlap. Teardown (close ctx) is idempotent, and `stop()` resolves any
+ * in-flight `end()` promise so a barge-in can never hang a waiting turn.
+ */
+export function createStreamingAudioPlayer(options = {}) {
+    const ctx = new AudioContext();
+    const gain = ctx.createGain();
+    gain.connect(ctx.destination);
+    try {
+        options.onGraphReady?.({ context: ctx, gain });
+    }
+    catch {
+        // A throwing host visualization tap must not break (or leak) the player.
+    }
+    let nextTime = ctx.currentTime;
+    let pending = 0;
+    let ended = false;
+    let torn = false;
+    let onDrained = null;
+    const teardown = () => {
+        if (torn)
+            return;
+        torn = true;
+        try {
+            options.onTeardown?.();
+        }
+        catch {
+            // Host tap disposal errors must not prevent the context from closing.
+        }
+        void ctx.close().catch(() => undefined);
+    };
+    const maybeDrain = () => {
+        if (ended && pending === 0) {
+            teardown();
+            onDrained?.();
+            onDrained = null;
+        }
+    };
+    return {
+        push(samples, sampleRate) {
+            if (torn || samples.length === 0)
+                return;
+            // The context is often created outside a click call stack — resume defensively (autoplay policy).
+            if (ctx.state === "suspended")
+                void ctx.resume().catch(() => undefined);
+            const buffer = ctx.createBuffer(1, samples.length, sampleRate);
+            buffer.getChannelData(0).set(samples);
+            const source = ctx.createBufferSource();
+            source.buffer = buffer;
+            source.connect(gain);
+            // If synthesis is slower than playback this yields a small silent gap rather than overlap.
+            const startAt = Math.max(nextTime, ctx.currentTime);
+            pending += 1;
+            source.onended = () => {
+                pending -= 1;
+                maybeDrain();
+            };
+            source.start(startAt);
+            nextTime = startAt + buffer.duration;
+        },
+        end() {
+            ended = true;
+            return new Promise((resolve) => {
+                if (pending === 0 || torn) {
+                    teardown();
+                    resolve();
+                    return;
+                }
+                onDrained = resolve;
+            });
+        },
+        stop() {
+            ended = true;
+            teardown();
+            onDrained?.();
+            onDrained = null;
+        },
+    };
+}
+//# sourceMappingURL=streaming-player.js.map

package/dist/audio/streaming-player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-player.js","sourceRoot":"","sources":["../../src/audio/streaming-player.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,195 @@
+import type { MLCEngineInterface } from "@mlc-ai/web-llm";
+import type { ModelPreset, ModelTask } from "./models.js";
+import type { ChatMessage, GenerationResult, RuntimeStats, TransformersModule, TransformersTextGenerationPipeline, TransformersTokenizer } from "./inference.js";
+import type { RuntimeParameters } from "./generation.js";
+import type { MultimodalHandle, MultimodalTransformers, RawAudio, SttResult, TtsTextSplitter, VlmResult } from "./multimodal.js";
+import type { BrowserAIConfig, ResolvedConfig } from "./config.js";
+import type { HardwareSnapshot } from "./hardware.js";
+import type { CacheCleanupResult, CachedModelStatus, IndividualModelCleanupResult, ModelCacheTarget, StorageEstimateSnapshot } from "./model-cache.js";
+import type { RunRecord } from "./history.js";
+import { RunHistoryStore } from "./history.js";
+import { TypedEmitter } from "./events.js";
+import type { SynthClip, SynthesizeClipOptions } from "./audio/clip.js";
+/**
+ * One loaded model and its engine handles. Exactly one backend group is populated: WebLLM
+ * (`engine` + `worker`), a Transformers.js text LM (`transformersGenerator`/`Tokenizer`/`Module`),
+ * or a multimodal handle (`multimodal` + `mmModule`, for STT/TTS/VLM/Gemma). `slots` are the
+ * capability slots it occupies ({@link modelSlots}).
+ */
+export type LoadedModel = {
+    modelId: string;
+    slots: ModelTask[];
+    backend: "webllm" | "transformers-js";
+    engine: MLCEngineInterface | null;
+    worker: Worker | null;
+    transformersGenerator: TransformersTextGenerationPipeline | null;
+    transformersTokenizer: TransformersTokenizer | null;
+    transformersModule: TransformersModule | null;
+    multimodal: MultimodalHandle | null;
+    mmModule: MultimodalTransformers | null;
+};
+export type LoadProgress = {
+    modelId: string;
+    progress: number;
+    status?: string;
+    file?: string;
+};
+export type BrowserAIEvents = {
+    /** Download/initialization progress for the model currently loading (progress 0–1). */
+    loadprogress: LoadProgress;
+    /** Human-readable engine status lines (loading, loaded-in-Ns, proxy checks…). */
+    status: {
+        message: string;
+    };
+    modelloaded: {
+        model: LoadedModel;
+    };
+    modelunloaded: {
+        modelId: string;
+    };
+};
+export type LoadOptions = {
+    /**
+     * WebLLM-only context-window override. Ignored when ≤0 or equal to the model's tested default
+     * ({@link DEFAULT_CONTEXT_LENGTH}); otherwise clamped to [512, 32768] and merged into the model
+     * record's overrides. Transformers.js and multimodal loads ignore it.
+     */
+    contextLength?: number | null;
+    /** Per-call progress callback (also emitted as the "loadprogress" event). */
+    onProgress?: (info: LoadProgress) => void;
+};
+export type GenerateTextOptions = {
+    /** Overrides merged over the loaded model's preset defaults. */
+    runtime?: Partial<RuntimeParameters>;
+    /** JSON Schema for WebLLM constrained decoding (prompt-only backends receive it via the prompt). */
+    schema?: unknown;
+    /** Stream callback — receives the FULL accumulated text so far on each delta. */
+    onDelta?: (fullText: string) => void;
+    /** Reset the WebLLM KV cache before generating (default true). */
+    resetChat?: boolean;
+};
+export type TtsOverrides = {
+    voice?: string;
+    speed?: number;
+    pitch?: number;
+};
+export type StreamingTtsSession = {
+    /** Push text incrementally (e.g. LLM deltas); sentences are synthesized as they complete. */
+    splitter: TtsTextSplitter;
+    /** One RawAudio per synthesized sentence, in order. Pull-driven. */
+    chunks: AsyncIterable<RawAudio>;
+    /**
+     * MUST be called when the session is finished (after the chunks iterator completes or is
+     * abandoned) — it releases the TTS model's serialization lock so other speech work can run.
+     */
+    release: () => void;
+};
+/**
+ * The BrowserAI client: model catalog + capability-slot manager + inference façade.
+ *
+ * Models load into one of four capability slots — text / vision / stt / tts — with at most one
+ * model per slot (up to four resident at once). Loading a model whose slots conflict with loaded
+ * models replaces the conflicting owners. Loads/unloads are single-flight, and runs are serialized
+ * per loaded model, so concurrent calls queue instead of driving one engine from two places.
+ */
+export declare class BrowserAI extends TypedEmitter<BrowserAIEvents> {
+    #private;
+    readonly config: ResolvedConfig;
+    constructor(config?: BrowserAIConfig);
+    /** The full model catalog. */
+    get presets(): readonly ModelPreset[];
+    /** Catalog lookup without fallback. */
+    getPreset(modelId: string): ModelPreset | undefined;
+    /** Currently loaded models (read-only snapshot). */
+    get loadedModels(): readonly LoadedModel[];
+    /** The loaded model occupying `task`, if any (≤1 owner per slot — enforced at load). */
+    slotOwner(task: ModelTask): LoadedModel | undefined;
+    textModel(): LoadedModel | undefined;
+    visionModel(): LoadedModel | undefined;
+    sttModel(): LoadedModel | undefined;
+    ttsModel(): LoadedModel | undefined;
+    /** Every capability slot currently filled by a loaded model. */
+    occupiedSlots(): Set<ModelTask>;
+    /** Whether `preset` can load without evicting anything (all its slots are free). */
+    isLoadable(preset: ModelPreset): boolean;
+    /** True while a load/unload/delete is in flight or any generation run is executing. */
+    isBusy(): boolean;
+    /** True while a load/unload/cache-delete lifecycle operation is in flight. */
+    get loading(): boolean;
+    /** The most recent hardware probe (from the last load), if any. */
+    get lastHardwareSnapshot(): HardwareSnapshot | null;
+    /** Probe WebGPU + hardware now (also refreshes {@link lastHardwareSnapshot}). */
+    probeHardware(): Promise<HardwareSnapshot>;
+    /** The run log configured by `config.history` (created lazily; localStorage-backed by default). */
+    get history(): RunHistoryStore;
+    /**
+     * Map a run's stats to a {@link RunRecord} and append it to {@link history}. Returns the record,
+     * or null for stats without a model (error placeholders are never logged).
+     */
+    logRun(caseKey: string, stats: RuntimeStats): RunRecord | null;
+    /**
+     * Load a model by catalog id. Evicts any loaded models occupying the slots this one needs
+     * (whole-model eviction: a multi-slot owner is fully released even for a one-slot conflict).
+     * Single-flight: a second load while one is in flight throws.
+     *
+     * @throws {UnknownModelError} for an id not in the catalog.
+     * @throws {WebGPUUnavailableError} when WebGPU is required and unavailable. Only ASR-pipeline and
+     *   TTS presets fall back to wasm; text, vision, Gemma and audio-LLM presets require WebGPU.
+     * @throws {ModelLoadError} wrapping any backend load failure.
+     */
+    load(modelId: string, options?: LoadOptions): Promise<LoadedModel>;
+    /** Unload one model, waiting out its in-flight runs. No-op when the id is not loaded. */
+    unload(modelId: string): Promise<void>;
+    /** Unload every loaded model. */
+    unloadAll(): Promise<void>;
+    /**
+     * Run one text generation against the loaded Text-slot model. A Gemma-4 multimodal handle has no
+     * WebLLM engine or Transformers.js LM pipeline, so it routes through the Gemma text path;
+     * everything else goes to the shared backend-agnostic generator. Runtime parameters default to
+     * the loaded model's preset defaults, with `options.runtime` merged on top.
+     */
+    generateText(messages: ChatMessage[], options?: GenerateTextOptions): Promise<GenerationResult>;
+    /** Reset the WebLLM KV cache of the loaded text model (e.g. for a "new chat"). Queues behind in-flight runs. */
+    resetTextChat(): Promise<void>;
+    /** Transcribe 16 kHz mono PCM (or a URL) with the loaded Transcription-slot model. */
+    transcribe(audio: Float32Array | string, onDelta?: (text: string) => void): Promise<SttResult>;
+    /** Synthesize speech with the loaded Speech-slot model. Returns the raw model audio. */
+    synthesize(text: string, overrides?: TtsOverrides): Promise<RawAudio>;
+    /**
+     * Synthesize speech and package it as a playable clip (pitch baked into the blob, original PCM
+     * kept for re-pitching). Voice/speed/pitch default to the client's TTS config.
+     */
+    synthesizeToClip(text: string, overrides?: TtsOverrides & Pick<SynthesizeClipOptions, "createUrl">): Promise<SynthClip>;
+    /** Whether the loaded Speech-slot model supports sentence-streaming synthesis (Kokoro). */
+    supportsStreamingTts(): boolean;
+    /**
+     * Begin a streaming TTS session on the loaded Kokoro model: push LLM deltas into `splitter`,
+     * consume `chunks` (one RawAudio per sentence), then call `release()` when done. The session
+     * holds the TTS model's serialization lock until released so no other speech run interleaves —
+     * the returned promise resolves only once the lock is actually held (queued behind in-flight
+     * speech runs), and the Kokoro stream is created after that point.
+     * @throws {MissingModelError} when no Speech model is loaded or it cannot stream.
+     */
+    createStreamingTts(overrides?: Pick<TtsOverrides, "voice" | "speed">): Promise<StreamingTtsSession>;
+    /** Ask a question about an image with the loaded Image-slot model (VLM or Gemma). */
+    describeImage(imageSrc: string, prompt: string, onDelta?: (text: string) => void): Promise<VlmResult>;
+    /** Whether a model's artifacts are present in browser storage (Cache API / IndexedDB). */
+    cacheStatus(modelId: string): Promise<CachedModelStatus>;
+    /** Origin-wide storage usage/quota estimate (browser-rounded). */
+    estimateStorage(): Promise<StorageEstimateSnapshot | undefined>;
+    /**
+     * Delete one model's downloaded artifacts. If the model is loaded it is released first (its
+     * in-flight runs are awaited). Targets model artifact storage only.
+     */
+    deleteModelArtifacts(modelId: string): Promise<IndividualModelCleanupResult>;
+    /** Delete ALL downloaded model artifacts (WebLLM + Transformers.js), releasing loaded models first. */
+    deleteAllModelArtifacts(): Promise<CacheCleanupResult>;
+}
+/**
+ * Normalize a context-length override: null/undefined, non-positive, or exactly the tested default
+ * ({@link DEFAULT_CONTEXT_LENGTH}) mean "no override"; anything else clamps to [512, 32768].
+ */
+export declare function normalizeContextLength(value: number | null | undefined): number | null;
+/** The cache-target matchers (id, repo labels, artifact URLs) for a preset's downloaded artifacts. */
+export declare function buildModelCacheTarget(preset: ModelPreset): ModelCacheTarget;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}