@tanstack/ai-svelte 0.13.14 → 0.14.0

package/dist/create-audio-recorder.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { AudioRecorderOptions, AudioRecording, InferAudioRecordingOutput } from '@tanstack/ai-client';
+export type CreateAudioRecorderOptions<TOnComplete> = AudioRecorderOptions & {
+    /**
+     * Optional transform applied to the recording when `stop()` resolves. Its
+     * (awaited) return value becomes `recording` and the resolved value of
+     * `stop()`. Return nothing to keep the raw `AudioRecording`.
+     */
+    onComplete?: TOnComplete;
+};
+export interface CreateAudioRecorderReturn<TOutput> {
+    /** Reactive: latest recording (transformed if `onComplete` provided), or null. */
+    readonly recording: TOutput | null;
+    /** Reactive: true while actively capturing audio. */
+    readonly isRecording: boolean;
+    /** Whether the browser supports recording. */
+    readonly isSupported: boolean;
+    start: () => Promise<void>;
+    /** Stop and resolve with the completed recording (transformed if `onComplete` provided). */
+    stop: () => Promise<TOutput>;
+    /**
+     * Discard the in-progress recording and release the mic. Svelte 5 runes
+     * can't register automatic teardown here (matching `createChat`), so call
+     * this from your component's cleanup if a recording may still be active.
+     */
+    cancel: () => void;
+}
+/**
+ * Svelte 5 factory for recording an audio message. The resolved recording
+ * carries `.part` (for `createChat.sendMessage`) and `.base64` (for the
+ * generation factories).
+ *
+ * Errors are delivered via `onError`. `start()` and `stop()` also reject on
+ * failure (and `stop()` rejects with `Recording cancelled` if `cancel()` runs
+ * while a stop is in flight) — handle one channel, not both.
+ */
+export declare function createAudioRecorder<TOnComplete extends (recording: AudioRecording) => unknown>(options: CreateAudioRecorderOptions<TOnComplete>): CreateAudioRecorderReturn<InferAudioRecordingOutput<TOnComplete>>;
+export declare function createAudioRecorder(options?: CreateAudioRecorderOptions<undefined>): CreateAudioRecorderReturn<AudioRecording>;

package/dist/create-audio-recorder.svelte.js

@@ -0,0 +1,36 @@
+import { AudioRecorder } from '@tanstack/ai-client';
+export function createAudioRecorder(options = {}) {
+    const recorder = new AudioRecorder({
+        ...(options.audio !== undefined && { audio: options.audio }),
+        ...(options.mimeType !== undefined && { mimeType: options.mimeType }),
+        ...(options.onError !== undefined && { onError: options.onError }),
+    });
+    let isRecording = $state(false);
+    let recording = $state(null);
+    recorder.subscribe((state) => {
+        isRecording = state === 'recording';
+    });
+    const stop = async () => {
+        const rawRecording = await recorder.stop();
+        const transformed = await options.onComplete?.(rawRecording);
+        // Only `undefined` (returning nothing) keeps the raw recording; a returned
+        // null is a real value, matching the inferred output type.
+        const output = transformed === undefined ? rawRecording : transformed;
+        recording = output;
+        return output;
+    };
+    return {
+        get recording() {
+            return recording;
+        },
+        get isRecording() {
+            return isRecording;
+        },
+        get isSupported() {
+            return AudioRecorder.isSupported();
+        },
+        start: () => recorder.start(),
+        stop,
+        cancel: () => recorder.cancel(),
+    };
+}

package/dist/create-chat.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { InferredClientContext } from '@tanstack/ai-client';
+import type { AnyClientTool, SchemaInput } from '@tanstack/ai';
+import type { CreateChatOptions, CreateChatReturn } from './types';
+/**
+ * Creates a reactive chat instance for Svelte 5.
+ *
+ * This function wraps the ChatClient from @tanstack/ai-client and exposes
+ * reactive state using Svelte 5 runes. The returned object has reactive
+ * getters that automatically update when state changes.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChat, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const chat = createChat({
+ *     connection: fetchServerSentEvents('/api/chat'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   {#each chat.messages as message}
+ *     <div>{message.role}: {message.parts[0].content}</div>
+ *   {/each}
+ *
+ *   {#if chat.isLoading}
+ *     <button onclick={chat.stop}>Stop</button>
+ *   {/if}
+ *
+ *   <button onclick={() => chat.sendMessage('Hello!')}>Send</button>
+ * </div>
+ * ```
+ */
+export declare function createChat<TTools extends ReadonlyArray<AnyClientTool> = any, TSchema extends SchemaInput | undefined = undefined, TContext = InferredClientContext<TTools>>(options: CreateChatOptions<TTools, TSchema, TContext>): CreateChatReturn<TTools, TSchema, TContext>;

package/dist/create-chat.svelte.js

@@ -0,0 +1,248 @@
+import { ChatClient } from '@tanstack/ai-client';
+import { createChatDevtoolsBridge } from '@tanstack/ai-client/devtools';
+/**
+ * Creates a reactive chat instance for Svelte 5.
+ *
+ * This function wraps the ChatClient from @tanstack/ai-client and exposes
+ * reactive state using Svelte 5 runes. The returned object has reactive
+ * getters that automatically update when state changes.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createChat, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const chat = createChat({
+ *     connection: fetchServerSentEvents('/api/chat'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   {#each chat.messages as message}
+ *     <div>{message.role}: {message.parts[0].content}</div>
+ *   {/each}
+ *
+ *   {#if chat.isLoading}
+ *     <button onclick={chat.stop}>Stop</button>
+ *   {/if}
+ *
+ *   <button onclick={() => chat.sendMessage('Hello!')}>Send</button>
+ * </div>
+ * ```
+ */
+export function createChat(options) {
+    // Generate a unique ID for this chat instance
+    const clientId = options.id ||
+        `chat-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+    // Create reactive state using Svelte 5 runes
+    let messages = $state(options.initialMessages || []);
+    let isLoading = $state(false);
+    let error = $state(undefined);
+    let status = $state('ready');
+    let isSubscribed = $state(false);
+    let connectionStatus = $state('disconnected');
+    let sessionGenerating = $state(false);
+    // Create ChatClient instance.
+    // Note: Svelte's createChat runs once per instance and `options` is captured
+    // by reference. Callbacks are therefore frozen to whatever the caller passed
+    // at creation — to swap them dynamically, mutate the options object
+    // in-place or call `client.updateOptions(...)` imperatively.
+    // Optional fields use conditional spread because the target
+    // `ChatClientOptions` declares them as `field?: T` (absent vs. present)
+    // rather than `field?: T | undefined`. Under `exactOptionalPropertyTypes`,
+    // passing an explicit `undefined` for an absent-only optional is a type
+    // error, so we omit the key when the caller's value is undefined.
+    const transport = options.connection
+        ? { connection: options.connection }
+        : { fetcher: options.fetcher };
+    const client = new ChatClient({
+        devtoolsBridgeFactory: createChatDevtoolsBridge,
+        ...transport,
+        id: clientId,
+        ...(options.initialMessages !== undefined && {
+            initialMessages: options.initialMessages,
+        }),
+        ...(options.persistence !== undefined && {
+            persistence: options.persistence,
+        }),
+        ...(options.body !== undefined && { body: options.body }),
+        ...(options.threadId !== undefined && { threadId: options.threadId }),
+        ...(options.forwardedProps !== undefined && {
+            forwardedProps: options.forwardedProps,
+        }),
+        ...(options.context !== undefined && { context: options.context }),
+        devtools: {
+            ...options.devtools,
+            framework: 'svelte',
+            hookName: 'useChat',
+            outputKind: options.outputSchema ? 'structured' : 'chat',
+        },
+        ...(options.onResponse !== undefined && { onResponse: options.onResponse }),
+        onChunk: (chunk) => {
+            options.onChunk?.(chunk);
+        },
+        onFinish: (message) => {
+            options.onFinish?.(message);
+        },
+        onError: (err) => {
+            options.onError?.(err);
+        },
+        tools: options.tools,
+        ...(options.onCustomEvent !== undefined && {
+            onCustomEvent: options.onCustomEvent,
+        }),
+        ...(options.streamProcessor !== undefined && {
+            streamProcessor: options.streamProcessor,
+        }),
+        onMessagesChange: (newMessages) => {
+            messages = newMessages;
+        },
+        onLoadingChange: (newIsLoading) => {
+            isLoading = newIsLoading;
+        },
+        onStatusChange: (newStatus) => {
+            status = newStatus;
+        },
+        onErrorChange: (newError) => {
+            error = newError;
+        },
+        onSubscriptionChange: (nextIsSubscribed) => {
+            isSubscribed = nextIsSubscribed;
+        },
+        onConnectionStatusChange: (nextStatus) => {
+            connectionStatus = nextStatus;
+        },
+        onSessionGeneratingChange: (isGenerating) => {
+            sessionGenerating = isGenerating;
+        },
+    });
+    messages = client.getMessages();
+    if (options.live) {
+        client.subscribe();
+    }
+    client.mountDevtools();
+    // Note: Cleanup is handled by calling stop() directly when needed.
+    // Unlike React/Vue/Solid, Svelte 5 runes like $effect can only be used
+    // during component initialization, so we don't add automatic cleanup here.
+    // Users should call chat.stop() in their component's cleanup if needed.
+    // Define methods
+    const sendMessage = async (content) => {
+        await client.sendMessage(content);
+    };
+    const append = async (message) => {
+        await client.append(message);
+    };
+    const reload = async () => {
+        await client.reload();
+    };
+    const stop = () => {
+        client.stop();
+    };
+    const dispose = () => {
+        client.dispose();
+    };
+    const clear = () => {
+        client.clear();
+    };
+    const setMessages = (newMessages) => {
+        client.setMessagesManually(newMessages);
+    };
+    const addToolResult = async (result) => {
+        await client.addToolResult(result);
+    };
+    const addToolApprovalResponse = async (response) => {
+        await client.addToolApprovalResponse(response);
+    };
+    /**
+     * @deprecated Use `updateForwardedProps` instead.
+     * Both populate the same wire payload.
+     */
+    const updateBody = (newBody) => {
+        client.updateOptions({ body: newBody });
+    };
+    const updateForwardedProps = (newForwardedProps) => {
+        client.updateOptions({ forwardedProps: newForwardedProps });
+    };
+    const updateContext = (newContext) => {
+        client.updateOptions({ context: newContext });
+    };
+    // The "active" structured-output part is the one on the assistant message
+    // after the latest user message. When no user message exists yet (e.g.
+    // `initialMessages` carries only a stale assistant turn), we return null
+    // rather than scanning history — otherwise a `final` from a previous
+    // session would leak in on first render. Uses `$derived.by` so the
+    // multi-line scan re-runs whenever `messages` changes.
+    const activeStructuredPart = $derived.by(() => {
+        let lastUserIndex = -1;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i]?.role === 'user') {
+                lastUserIndex = i;
+                break;
+            }
+        }
+        if (lastUserIndex === -1)
+            return null;
+        for (let i = messages.length - 1; i > lastUserIndex; i--) {
+            const m = messages[i];
+            if (m?.role !== 'assistant')
+                continue;
+            const part = m.parts.find((p) => p.type === 'structured-output');
+            if (part)
+                return part;
+        }
+        return null;
+    });
+    const partial = $derived.by(() => {
+        if (!activeStructuredPart)
+            return {};
+        const v = activeStructuredPart.partial ?? activeStructuredPart.data;
+        return (v ?? {});
+    });
+    const final = $derived(activeStructuredPart && activeStructuredPart.status === 'complete'
+        ? activeStructuredPart.data
+        : null);
+    // Return the chat interface with reactive getters
+    // Using getters allows Svelte to track reactivity without needing $ prefix
+    // eslint-disable-next-line no-restricted-syntax -- rune return shape diverges from generic CreateChatReturn<TTools, TSchema, TContext> due to TSchema conditional partial/final fields; TS can't structurally narrow.
+    return {
+        get messages() {
+            return messages;
+        },
+        get isLoading() {
+            return isLoading;
+        },
+        get error() {
+            return error;
+        },
+        get status() {
+            return status;
+        },
+        get isSubscribed() {
+            return isSubscribed;
+        },
+        get connectionStatus() {
+            return connectionStatus;
+        },
+        get sessionGenerating() {
+            return sessionGenerating;
+        },
+        get partial() {
+            return partial;
+        },
+        get final() {
+            return final;
+        },
+        sendMessage,
+        append,
+        reload,
+        stop,
+        dispose,
+        setMessages,
+        clear,
+        addToolResult,
+        addToolApprovalResponse,
+        updateBody,
+        updateForwardedProps,
+        updateContext,
+    };
+}

package/dist/create-generate-audio.svelte.d.ts

@@ -0,0 +1,85 @@
+import type { AudioGenerationResult, StreamChunk } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, AudioGenerateInput, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
+/**
+ * Options for the createGenerateAudio function.
+ *
+ * @template TOutput - The output type after optional transform (defaults to AudioGenerationResult)
+ */
+export interface CreateGenerateAudioOptions<TOutput = AudioGenerationResult> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for audio generation */
+    fetcher?: GenerationFetcher<AudioGenerateInput, AudioGenerationResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Callback when audio is generated. Can optionally return a transformed value.
+     *
+     * - Return a non-null value to transform and store it as the result
+     * - Return `null` to keep the previous result unchanged
+     * - Return nothing (`void`) to store the raw result as-is
+     */
+    onResult?: (result: AudioGenerationResult) => TOutput | null | void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when progress is reported (0-100) */
+    onProgress?: (progress: number, message?: string) => void;
+    /** Callback for each stream chunk (connect-based adapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the createGenerateAudio function.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface CreateGenerateAudioReturn<TOutput = AudioGenerationResult> {
+    /** The generation result containing audio, or null */
+    readonly result: TOutput | null;
+    /** Whether generation is in progress */
+    readonly isLoading: boolean;
+    /** Current error, if any */
+    readonly error: Error | undefined;
+    /** Current state of the generation */
+    readonly status: GenerationClientState;
+    /** Trigger audio generation */
+    generate: (input: AudioGenerateInput) => Promise<void>;
+    /** Abort the current generation */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+    /** Update additional body parameters */
+    updateBody: (body: Record<string, any>) => void;
+}
+/**
+ * Creates a reactive audio generation instance for Svelte 5.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGenerateAudio, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const audio = createGenerateAudio({
+ *     connection: fetchServerSentEvents('/api/generate/audio'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => audio.generate({ prompt: 'An upbeat electronic track', duration: 10 })}>
+ *     Generate
+ *   </button>
+ *   {#if audio.isLoading}
+ *     <p>Generating...</p>
+ *   {/if}
+ *   {#if audio.result?.audio.url}
+ *     <audio src={audio.result.audio.url} controls></audio>
+ *   {/if}
+ * </div>
+ * ```
+ */
+export declare function createGenerateAudio<TTransformed = void>(options: Omit<CreateGenerateAudioOptions, 'onResult'> & {
+    onResult?: (result: AudioGenerationResult) => TTransformed;
+}): CreateGenerateAudioReturn<InferGenerationOutputFromReturn<AudioGenerationResult, TTransformed>>;

package/dist/create-generate-audio.svelte.js

@@ -0,0 +1,57 @@
+import { createGeneration } from './create-generation.svelte';
+/**
+ * Creates a reactive audio generation instance for Svelte 5.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGenerateAudio, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const audio = createGenerateAudio({
+ *     connection: fetchServerSentEvents('/api/generate/audio'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => audio.generate({ prompt: 'An upbeat electronic track', duration: 10 })}>
+ *     Generate
+ *   </button>
+ *   {#if audio.isLoading}
+ *     <p>Generating...</p>
+ *   {/if}
+ *   {#if audio.result?.audio.url}
+ *     <audio src={audio.result.audio.url} controls></audio>
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function createGenerateAudio(options) {
+    const devtools = {
+        ...options.devtools,
+        framework: 'svelte',
+        hookName: 'createGenerateAudio',
+        outputKind: 'audio',
+    };
+    const gen = createGeneration({
+        ...options,
+        devtools,
+    });
+    return {
+        get result() {
+            return gen.result;
+        },
+        get isLoading() {
+            return gen.isLoading;
+        },
+        get error() {
+            return gen.error;
+        },
+        get status() {
+            return gen.status;
+        },
+        generate: gen.generate,
+        stop: gen.stop,
+        reset: gen.reset,
+        updateBody: gen.updateBody,
+    };
+}

package/dist/create-generate-image.svelte.d.ts

@@ -0,0 +1,94 @@
+import type { ImageGenerationResult, StreamChunk } from '@tanstack/ai';
+import type { AIDevtoolsDisplayOptions, ConnectConnectionAdapter, GenerationClientState, GenerationFetcher, ImageGenerateInput, InferGenerationOutputFromReturn } from '@tanstack/ai-client';
+/**
+ * Options for the createGenerateImage function.
+ *
+ * @template TOutput - The output type after optional transform (defaults to ImageGenerationResult)
+ */
+export interface CreateGenerateImageOptions<TOutput = ImageGenerationResult> {
+    /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+    connection?: ConnectConnectionAdapter;
+    /** Direct async function for image generation */
+    fetcher?: GenerationFetcher<ImageGenerateInput, ImageGenerationResult>;
+    /** Unique identifier for this generation instance */
+    id?: string;
+    /** Additional body parameters to send with connect-based adapter requests */
+    body?: Record<string, any>;
+    /** Display options for TanStack AI Devtools. */
+    devtools?: AIDevtoolsDisplayOptions;
+    /**
+     * Callback when images are generated. Can optionally return a transformed value.
+     *
+     * - Return a non-null value to transform and store it as the result
+     * - Return `null` to keep the previous result unchanged
+     * - Return nothing (`void`) to store the raw result as-is
+     */
+    onResult?: (result: ImageGenerationResult) => TOutput | null | void;
+    /** Callback when an error occurs */
+    onError?: (error: Error) => void;
+    /** Callback when progress is reported (0-100) */
+    onProgress?: (progress: number, message?: string) => void;
+    /** Callback for each stream chunk (connect-based adapter mode only) */
+    onChunk?: (chunk: StreamChunk) => void;
+}
+/**
+ * Return type for the createGenerateImage function.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface CreateGenerateImageReturn<TOutput = ImageGenerationResult> {
+    /** The generation result containing images, or null */
+    readonly result: TOutput | null;
+    /** Whether generation is in progress */
+    readonly isLoading: boolean;
+    /** Current error, if any */
+    readonly error: Error | undefined;
+    /** Current state of the generation */
+    readonly status: GenerationClientState;
+    /** Trigger image generation */
+    generate: (input: ImageGenerateInput) => Promise<void>;
+    /** Abort the current generation */
+    stop: () => void;
+    /** Clear result, error, and return to idle */
+    reset: () => void;
+    /** Update additional body parameters */
+    updateBody: (body: Record<string, any>) => void;
+}
+/**
+ * Creates a reactive image generation instance for Svelte 5.
+ *
+ * Supports two transport modes:
+ * - **ConnectConnectionAdapter** -- Streaming transport (SSE, HTTP stream, custom)
+ * - **Fetcher** -- Direct async function call
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGenerateImage, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const imageGen = createGenerateImage({
+ *     connection: fetchServerSentEvents('/api/generate/image'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => imageGen.generate({ prompt: 'A sunset over mountains' })}>
+ *     Generate
+ *   </button>
+ *   {#if imageGen.isLoading}
+ *     <p>Generating...</p>
+ *   {/if}
+ *   {#if imageGen.error}
+ *     <p>Error: {imageGen.error.message}</p>
+ *   {/if}
+ *   {#if imageGen.result}
+ *     {#each imageGen.result.images as img}
+ *       <img src={img.url || `data:image/png;base64,${img.b64Json}`} alt="Generated" />
+ *     {/each}
+ *   {/if}
+ * </div>
+ * ```
+ */
+export declare function createGenerateImage<TTransformed = void>(options: Omit<CreateGenerateImageOptions, 'onResult'> & {
+    onResult?: (result: ImageGenerationResult) => TTransformed;
+}): CreateGenerateImageReturn<InferGenerationOutputFromReturn<ImageGenerationResult, TTransformed>>;

package/dist/create-generate-image.svelte.js

@@ -0,0 +1,66 @@
+import { createGeneration } from './create-generation.svelte';
+/**
+ * Creates a reactive image generation instance for Svelte 5.
+ *
+ * Supports two transport modes:
+ * - **ConnectConnectionAdapter** -- Streaming transport (SSE, HTTP stream, custom)
+ * - **Fetcher** -- Direct async function call
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGenerateImage, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const imageGen = createGenerateImage({
+ *     connection: fetchServerSentEvents('/api/generate/image'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => imageGen.generate({ prompt: 'A sunset over mountains' })}>
+ *     Generate
+ *   </button>
+ *   {#if imageGen.isLoading}
+ *     <p>Generating...</p>
+ *   {/if}
+ *   {#if imageGen.error}
+ *     <p>Error: {imageGen.error.message}</p>
+ *   {/if}
+ *   {#if imageGen.result}
+ *     {#each imageGen.result.images as img}
+ *       <img src={img.url || `data:image/png;base64,${img.b64Json}`} alt="Generated" />
+ *     {/each}
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function createGenerateImage(options) {
+    const devtools = {
+        ...options.devtools,
+        framework: 'svelte',
+        hookName: 'createGenerateImage',
+        outputKind: 'image',
+    };
+    const gen = createGeneration({
+        ...options,
+        devtools,
+    });
+    return {
+        get result() {
+            return gen.result;
+        },
+        get isLoading() {
+            return gen.isLoading;
+        },
+        get error() {
+            return gen.error;
+        },
+        get status() {
+            return gen.status;
+        },
+        generate: gen.generate,
+        stop: gen.stop,
+        reset: gen.reset,
+        updateBody: gen.updateBody,
+    };
+}