@tanstack/ai-client 0.18.6 → 0.19.1

package/dist/esm/audio-recorder.d.ts

@@ -0,0 +1,76 @@
+import { AudioPart } from '@tanstack/ai/client';
+/** Lifecycle state of an {@link AudioRecorder}. */
+export type AudioRecorderState = 'idle' | 'recording' | 'stopping';
+export interface AudioRecorderOptions {
+    /** Constraints forwarded to `getUserMedia({ audio })`. Defaults to `true`. */
+    audio?: MediaTrackConstraints | boolean;
+    /**
+     * Preferred recorder mime type. Used only when
+     * `MediaRecorder.isTypeSupported` reports it; otherwise the browser default
+     * is used.
+     */
+    mimeType?: string;
+    /** Fired on `getUserMedia` rejection (permission denied) or recorder error. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Resolves the value `stop()` produces from a recorder transform callback.
+ *
+ * - If the callback returns a value — sync or async — that value's awaited type
+ *   is used (a returned `null` is a real value and is preserved).
+ * - If the callback returns nothing (`void`/`undefined`), or is absent, falls
+ *   back to {@link AudioRecording}.
+ *
+ * @template TFn - The transform callback type (or undefined if not provided)
+ */
+export type InferAudioRecordingOutput<TFn> = TFn extends (recording: AudioRecording) => infer R ? [Exclude<Awaited<R>, void | undefined>] extends [never] ? AudioRecording : Exclude<Awaited<R>, void | undefined> : AudioRecording;
+export interface AudioRecording {
+    /** The raw recorded media blob. */
+    blob: Blob;
+    /** Base64 of the recorded bytes (no `data:` prefix). */
+    base64: string;
+    /** The recorder's native mime type, e.g. `audio/webm;codecs=opus`. */
+    mimeType: string;
+    /** Recording length in milliseconds. */
+    durationMs: number;
+    /**
+     * Ready-to-use audio content part for `sendMessage`/generation prompts:
+     * `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`.
+     */
+    part: AudioPart;
+}
+/**
+ * Framework-agnostic browser audio recorder. Wraps `getUserMedia` +
+ * `MediaRecorder`, returns the recorder's native output (no transcode), and
+ * builds a plug-and-play {@link AudioRecording.part}.
+ */
+export declare class AudioRecorder {
+    private readonly options;
+    private recorder;
+    private stream;
+    private chunks;
+    private startedAt;
+    private _state;
+    private starting;
+    private pendingCancel;
+    private readonly listeners;
+    private stopResolve;
+    private stopReject;
+    constructor(options?: AudioRecorderOptions);
+    /** Feature-detect the browser media APIs. SSR/Worker-safe. */
+    static isSupported(): boolean;
+    get state(): AudioRecorderState;
+    subscribe(cb: (state: AudioRecorderState) => void): () => void;
+    private setState;
+    start(): Promise<void>;
+    stop(): Promise<AudioRecording>;
+    cancel(): void;
+    private finalize;
+    private handleError;
+    /** Invoke the user onError callback, isolating a throw so it can't disrupt
+     * internal state teardown or strand a pending promise. */
+    private notifyError;
+    private releaseStream;
+    /** Detach all event handlers so a stale recorder can't mutate our state. */
+    private detachRecorder;
+}

package/dist/esm/audio-recorder.js

@@ -0,0 +1,215 @@
+import { arrayBufferToBase64 } from "@tanstack/ai-utils";
+class AudioRecorder {
+  options;
+  recorder = null;
+  stream = null;
+  chunks = [];
+  startedAt = 0;
+  _state = "idle";
+  // True while start() is awaiting getUserMedia (state is still 'idle' then).
+  starting = false;
+  // Set by cancel()/teardown during that window so start() releases the
+  // freshly acquired stream instead of beginning a leaked recording.
+  pendingCancel = false;
+  listeners = /* @__PURE__ */ new Set();
+  stopResolve = null;
+  stopReject = null;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /** Feature-detect the browser media APIs. SSR/Worker-safe. */
+  static isSupported() {
+    return typeof navigator !== "undefined" && typeof navigator.mediaDevices !== "undefined" && typeof navigator.mediaDevices.getUserMedia === "function" && typeof MediaRecorder !== "undefined";
+  }
+  get state() {
+    return this._state;
+  }
+  subscribe(cb) {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  }
+  setState(state) {
+    this._state = state;
+    for (const cb of this.listeners) {
+      cb(state);
+    }
+  }
+  async start() {
+    if (this._state !== "idle" || this.starting) {
+      return;
+    }
+    this.starting = true;
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: this.options.audio ?? true
+      });
+      if (this.pendingCancel) {
+        stream.getTracks().forEach((t) => t.stop());
+        return;
+      }
+      this.stream = stream;
+      const wanted = this.options.mimeType;
+      const useMimeType = wanted && typeof MediaRecorder.isTypeSupported === "function" && MediaRecorder.isTypeSupported(wanted) ? wanted : void 0;
+      const recorder = useMimeType ? new MediaRecorder(stream, { mimeType: useMimeType }) : new MediaRecorder(stream);
+      this.chunks = [];
+      recorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          this.chunks.push(e.data);
+        }
+      };
+      recorder.onstop = () => {
+        void this.finalize();
+      };
+      recorder.onerror = (event) => {
+        const detail = "error" in event && event.error instanceof Error ? event.error : new Error("Audio recording failed");
+        this.handleError(detail);
+      };
+      this.recorder = recorder;
+      this.startedAt = Date.now();
+      recorder.start();
+      this.setState("recording");
+    } catch (err) {
+      this.releaseStream();
+      this.recorder = null;
+      const error = err instanceof Error ? err : new Error("Failed to start recording");
+      this.setState("idle");
+      this.notifyError(error);
+      throw error;
+    } finally {
+      this.starting = false;
+      this.pendingCancel = false;
+    }
+  }
+  stop() {
+    if (this._state !== "recording" || !this.recorder) {
+      return Promise.reject(
+        new Error("AudioRecorder.stop() called while not recording")
+      );
+    }
+    this.setState("stopping");
+    const recorder = this.recorder;
+    return new Promise((resolve, reject) => {
+      const watchdog = setTimeout(() => {
+        if (this._state !== "stopping") {
+          return;
+        }
+        this.detachRecorder();
+        if (this.chunks.length > 0) {
+          void this.finalize();
+        } else {
+          this.handleError(
+            new Error("Recording stop timed out after 10s with no audio")
+          );
+        }
+      }, 1e4);
+      this.stopResolve = (rec) => {
+        clearTimeout(watchdog);
+        resolve(rec);
+      };
+      this.stopReject = (err) => {
+        clearTimeout(watchdog);
+        reject(err);
+      };
+      recorder.stop();
+    });
+  }
+  cancel() {
+    if (this.starting) {
+      this.pendingCancel = true;
+      return;
+    }
+    if (this._state === "idle") {
+      return;
+    }
+    const recorder = this.recorder;
+    if (recorder) {
+      this.detachRecorder();
+      try {
+        recorder.stop();
+      } catch (err) {
+        if (!(err instanceof DOMException && err.name === "InvalidStateError")) {
+          this.notifyError(
+            err instanceof Error ? err : new Error("Failed to stop recorder")
+          );
+        }
+      }
+    }
+    this.releaseStream();
+    this.recorder = null;
+    this.chunks = [];
+    const reject = this.stopReject;
+    this.stopResolve = null;
+    this.stopReject = null;
+    this.setState("idle");
+    reject?.(new Error("Recording cancelled"));
+  }
+  async finalize() {
+    const mimeType = this.recorder?.mimeType || "audio/webm";
+    const durationMs = Date.now() - this.startedAt;
+    try {
+      const blob = new Blob(this.chunks, { type: mimeType });
+      const base64 = arrayBufferToBase64(await blob.arrayBuffer());
+      const recording = {
+        blob,
+        base64,
+        mimeType,
+        durationMs,
+        part: {
+          type: "audio",
+          source: { type: "data", value: base64, mimeType }
+        }
+      };
+      this.releaseStream();
+      this.recorder = null;
+      this.chunks = [];
+      const resolve = this.stopResolve;
+      this.stopResolve = null;
+      this.stopReject = null;
+      this.setState("idle");
+      resolve?.(recording);
+    } catch (err) {
+      this.handleError(
+        err instanceof Error ? err : new Error("Failed to finalize recording")
+      );
+    }
+  }
+  handleError(error) {
+    this.releaseStream();
+    this.recorder = null;
+    this.chunks = [];
+    const reject = this.stopReject;
+    this.stopResolve = null;
+    this.stopReject = null;
+    this.setState("idle");
+    reject?.(error);
+    this.notifyError(error);
+  }
+  /** Invoke the user onError callback, isolating a throw so it can't disrupt
+   * internal state teardown or strand a pending promise. */
+  notifyError(error) {
+    try {
+      this.options.onError?.(error);
+    } catch {
+    }
+  }
+  releaseStream() {
+    this.stream?.getTracks().forEach((t) => t.stop());
+    this.stream = null;
+  }
+  /** Detach all event handlers so a stale recorder can't mutate our state. */
+  detachRecorder() {
+    const recorder = this.recorder;
+    if (!recorder) {
+      return;
+    }
+    recorder.onstop = null;
+    recorder.onerror = null;
+    recorder.ondataavailable = null;
+  }
+}
+export {
+  AudioRecorder
+};
+//# sourceMappingURL=audio-recorder.js.map

package/dist/esm/audio-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-recorder.js","sources":["../../src/audio-recorder.ts"],"sourcesContent":["import { arrayBufferToBase64 } from '@tanstack/ai-utils'\nimport type { AudioPart } from '@tanstack/ai/client'\n\n/** Lifecycle state of an {@link AudioRecorder}. */\nexport type AudioRecorderState = 'idle' | 'recording' | 'stopping'\n\nexport interface AudioRecorderOptions {\n  /** Constraints forwarded to `getUserMedia({ audio })`. Defaults to `true`. */\n  audio?: MediaTrackConstraints | boolean\n  /**\n   * Preferred recorder mime type. Used only when\n   * `MediaRecorder.isTypeSupported` reports it; otherwise the browser default\n   * is used.\n   */\n  mimeType?: string\n  /** Fired on `getUserMedia` rejection (permission denied) or recorder error. */\n  onError?: (error: Error) => void\n}\n\n/**\n * Resolves the value `stop()` produces from a recorder transform callback.\n *\n * - If the callback returns a value — sync or async — that value's awaited type\n *   is used (a returned `null` is a real value and is preserved).\n * - If the callback returns nothing (`void`/`undefined`), or is absent, falls\n *   back to {@link AudioRecording}.\n *\n * @template TFn - The transform callback type (or undefined if not provided)\n */\nexport type InferAudioRecordingOutput<TFn> = TFn extends (\n  recording: AudioRecording,\n) => infer R\n  ? [Exclude<Awaited<R>, void | undefined>] extends [never]\n    ? AudioRecording\n    : Exclude<Awaited<R>, void | undefined>\n  : AudioRecording\n\nexport interface AudioRecording {\n  /** The raw recorded media blob. */\n  blob: Blob\n  /** Base64 of the recorded bytes (no `data:` prefix). */\n  base64: string\n  /** The recorder's native mime type, e.g. `audio/webm;codecs=opus`. */\n  mimeType: string\n  /** Recording length in milliseconds. */\n  durationMs: number\n  /**\n   * Ready-to-use audio content part for `sendMessage`/generation prompts:\n   * `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`.\n   */\n  part: AudioPart\n}\n\n/**\n * Framework-agnostic browser audio recorder. Wraps `getUserMedia` +\n * `MediaRecorder`, returns the recorder's native output (no transcode), and\n * builds a plug-and-play {@link AudioRecording.part}.\n */\nexport class AudioRecorder {\n  private readonly options: AudioRecorderOptions\n  private recorder: MediaRecorder | null = null\n  private stream: MediaStream | null = null\n  private chunks: Array<Blob> = []\n  private startedAt = 0\n  private _state: AudioRecorderState = 'idle'\n  // True while start() is awaiting getUserMedia (state is still 'idle' then).\n  private starting = false\n  // Set by cancel()/teardown during that window so start() releases the\n  // freshly acquired stream instead of beginning a leaked recording.\n  private pendingCancel = false\n  private readonly listeners = new Set<(state: AudioRecorderState) => void>()\n  private stopResolve: ((recording: AudioRecording) => void) | null = null\n  private stopReject: ((error: Error) => void) | null = null\n\n  constructor(options: AudioRecorderOptions = {}) {\n    this.options = options\n  }\n\n  /** Feature-detect the browser media APIs. SSR/Worker-safe. */\n  static isSupported(): boolean {\n    return (\n      typeof navigator !== 'undefined' &&\n      typeof navigator.mediaDevices !== 'undefined' &&\n      typeof navigator.mediaDevices.getUserMedia === 'function' &&\n      typeof MediaRecorder !== 'undefined'\n    )\n  }\n\n  get state(): AudioRecorderState {\n    return this._state\n  }\n\n  subscribe(cb: (state: AudioRecorderState) => void): () => void {\n    this.listeners.add(cb)\n    return () => {\n      this.listeners.delete(cb)\n    }\n  }\n\n  private setState(state: AudioRecorderState): void {\n    this._state = state\n    for (const cb of this.listeners) {\n      cb(state)\n    }\n  }\n\n  async start(): Promise<void> {\n    if (this._state !== 'idle' || this.starting) {\n      return\n    }\n    this.starting = true\n    try {\n      const stream = await navigator.mediaDevices.getUserMedia({\n        audio: this.options.audio ?? true,\n      })\n      // cancel()/teardown ran while we were awaiting the mic: release the\n      // freshly acquired stream and bail rather than starting a recording the\n      // caller can no longer stop (a leaked live microphone).\n      if (this.pendingCancel) {\n        stream.getTracks().forEach((t) => t.stop())\n        return\n      }\n      this.stream = stream\n      const wanted = this.options.mimeType\n      const useMimeType =\n        wanted &&\n        typeof MediaRecorder.isTypeSupported === 'function' &&\n        MediaRecorder.isTypeSupported(wanted)\n          ? wanted\n          : undefined\n      const recorder = useMimeType\n        ? new MediaRecorder(stream, { mimeType: useMimeType })\n        : new MediaRecorder(stream)\n      this.chunks = []\n      recorder.ondataavailable = (e) => {\n        if (e.data.size > 0) {\n          this.chunks.push(e.data)\n        }\n      }\n      recorder.onstop = () => {\n        void this.finalize()\n      }\n      recorder.onerror = (event) => {\n        const detail =\n          'error' in event && event.error instanceof Error\n            ? event.error\n            : new Error('Audio recording failed')\n        this.handleError(detail)\n      }\n      this.recorder = recorder\n      this.startedAt = Date.now()\n      recorder.start()\n      this.setState('recording')\n    } catch (err) {\n      this.releaseStream()\n      this.recorder = null\n      const error =\n        err instanceof Error ? err : new Error('Failed to start recording')\n      this.setState('idle')\n      this.notifyError(error)\n      throw error\n    } finally {\n      this.starting = false\n      // Reset here (not before the await) so a cancel() that arrives mid-start\n      // is observed above; clearing it afterward keeps the next start() clean.\n      this.pendingCancel = false\n    }\n  }\n\n  stop(): Promise<AudioRecording> {\n    if (this._state !== 'recording' || !this.recorder) {\n      return Promise.reject(\n        new Error('AudioRecorder.stop() called while not recording'),\n      )\n    }\n    this.setState('stopping')\n    const recorder = this.recorder\n    return new Promise<AudioRecording>((resolve, reject) => {\n      // Some browsers/codecs never fire onstop; this watchdog unwedges the\n      // recorder instead of leaking this promise forever.\n      const watchdog = setTimeout(() => {\n        if (this._state !== 'stopping') {\n          return\n        }\n        // Detach handlers so a late onstop/onerror from the stalled recorder\n        // can't reach back in and fire finalize()/onError a second time.\n        this.detachRecorder()\n        if (this.chunks.length > 0) {\n          // onstop never fired, but ondataavailable already delivered the\n          // audio — finalize from the buffered chunks rather than discarding a\n          // recording the user successfully captured.\n          void this.finalize()\n        } else {\n          this.handleError(\n            new Error('Recording stop timed out after 10s with no audio'),\n          )\n        }\n      }, 10_000)\n      this.stopResolve = (rec) => {\n        clearTimeout(watchdog)\n        resolve(rec)\n      }\n      this.stopReject = (err) => {\n        clearTimeout(watchdog)\n        reject(err)\n      }\n      recorder.stop()\n    })\n  }\n\n  cancel(): void {\n    if (this.starting) {\n      // A start() is awaiting getUserMedia; flag it so the resolved stream is\n      // released instead of beginning a recording with no handle to stop it.\n      this.pendingCancel = true\n      return\n    }\n    if (this._state === 'idle') {\n      return\n    }\n    const recorder = this.recorder\n    if (recorder) {\n      // Detach handlers so finalize()/onError never run for a discarded\n      // recording.\n      this.detachRecorder()\n      try {\n        recorder.stop()\n      } catch (err) {\n        // Stopping an already-inactive recorder throws InvalidStateError —\n        // that's expected here. Anything else is unexpected; surface it rather\n        // than swallowing it silently.\n        if (\n          !(err instanceof DOMException && err.name === 'InvalidStateError')\n        ) {\n          this.notifyError(\n            err instanceof Error ? err : new Error('Failed to stop recorder'),\n          )\n        }\n      }\n    }\n    this.releaseStream()\n    this.recorder = null\n    this.chunks = []\n    const reject = this.stopReject\n    this.stopResolve = null\n    this.stopReject = null\n    this.setState('idle')\n    reject?.(new Error('Recording cancelled'))\n  }\n\n  private async finalize(): Promise<void> {\n    const mimeType = this.recorder?.mimeType || 'audio/webm'\n    const durationMs = Date.now() - this.startedAt\n    try {\n      const blob = new Blob(this.chunks, { type: mimeType })\n      const base64 = arrayBufferToBase64(await blob.arrayBuffer())\n      const recording: AudioRecording = {\n        blob,\n        base64,\n        mimeType,\n        durationMs,\n        part: {\n          type: 'audio',\n          source: { type: 'data', value: base64, mimeType },\n        },\n      }\n      this.releaseStream()\n      this.recorder = null\n      this.chunks = []\n      const resolve = this.stopResolve\n      this.stopResolve = null\n      this.stopReject = null\n      this.setState('idle')\n      resolve?.(recording)\n    } catch (err) {\n      this.handleError(\n        err instanceof Error ? err : new Error('Failed to finalize recording'),\n      )\n    }\n  }\n\n  private handleError(error: Error): void {\n    this.releaseStream()\n    this.recorder = null\n    this.chunks = []\n    const reject = this.stopReject\n    this.stopResolve = null\n    this.stopReject = null\n    this.setState('idle')\n    // Settle the pending stop() promise before invoking the user callback so a\n    // throwing onError can't strand the awaiter (the two error channels are\n    // independent — see start()/stop() docs).\n    reject?.(error)\n    this.notifyError(error)\n  }\n\n  /** Invoke the user onError callback, isolating a throw so it can't disrupt\n   * internal state teardown or strand a pending promise. */\n  private notifyError(error: Error): void {\n    try {\n      this.options.onError?.(error)\n    } catch {\n      // A user onError that throws must not propagate into recorder internals.\n    }\n  }\n\n  private releaseStream(): void {\n    this.stream?.getTracks().forEach((t) => t.stop())\n    this.stream = null\n  }\n\n  /** Detach all event handlers so a stale recorder can't mutate our state. */\n  private detachRecorder(): void {\n    const recorder = this.recorder\n    if (!recorder) {\n      return\n    }\n    recorder.onstop = null\n    recorder.onerror = null\n    recorder.ondataavailable = null\n  }\n}\n"],"names":[],"mappings":";AA0DO,MAAM,cAAc;AAAA,EACR;AAAA,EACT,WAAiC;AAAA,EACjC,SAA6B;AAAA,EAC7B,SAAsB,CAAA;AAAA,EACtB,YAAY;AAAA,EACZ,SAA6B;AAAA;AAAA,EAE7B,WAAW;AAAA;AAAA;AAAA,EAGX,gBAAgB;AAAA,EACP,gCAAgB,IAAA;AAAA,EACzB,cAA4D;AAAA,EAC5D,aAA8C;AAAA,EAEtD,YAAY,UAAgC,IAAI;AAC9C,SAAK,UAAU;AAAA,EACjB;AAAA;AAAA,EAGA,OAAO,cAAuB;AAC5B,WACE,OAAO,cAAc,eACrB,OAAO,UAAU,iBAAiB,eAClC,OAAO,UAAU,aAAa,iBAAiB,cAC/C,OAAO,kBAAkB;AAAA,EAE7B;AAAA,EAEA,IAAI,QAA4B;AAC9B,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,UAAU,IAAqD;AAC7D,SAAK,UAAU,IAAI,EAAE;AACrB,WAAO,MAAM;AACX,WAAK,UAAU,OAAO,EAAE;AAAA,IAC1B;AAAA,EACF;AAAA,EAEQ,SAAS,OAAiC;AAChD,SAAK,SAAS;AACd,eAAW,MAAM,KAAK,WAAW;AAC/B,SAAG,KAAK;AAAA,IACV;AAAA,EACF;AAAA,EAEA,MAAM,QAAuB;AAC3B,QAAI,KAAK,WAAW,UAAU,KAAK,UAAU;AAC3C;AAAA,IACF;AACA,SAAK,WAAW;AAChB,QAAI;AACF,YAAM,SAAS,MAAM,UAAU,aAAa,aAAa;AAAA,QACvD,OAAO,KAAK,QAAQ,SAAS;AAAA,MAAA,CAC9B;AAID,UAAI,KAAK,eAAe;AACtB,eAAO,YAAY,QAAQ,CAAC,MAAM,EAAE,MAAM;AAC1C;AAAA,MACF;AACA,WAAK,SAAS;AACd,YAAM,SAAS,KAAK,QAAQ;AAC5B,YAAM,cACJ,UACA,OAAO,cAAc,oBAAoB,cACzC,cAAc,gBAAgB,MAAM,IAChC,SACA;AACN,YAAM,WAAW,cACb,IAAI,cAAc,QAAQ,EAAE,UAAU,YAAA,CAAa,IACnD,IAAI,cAAc,MAAM;AAC5B,WAAK,SAAS,CAAA;AACd,eAAS,kBAAkB,CAAC,MAAM;AAChC,YAAI,EAAE,KAAK,OAAO,GAAG;AACnB,eAAK,OAAO,KAAK,EAAE,IAAI;AAAA,QACzB;AAAA,MACF;AACA,eAAS,SAAS,MAAM;AACtB,aAAK,KAAK,SAAA;AAAA,MACZ;AACA,eAAS,UAAU,CAAC,UAAU;AAC5B,cAAM,SACJ,WAAW,SAAS,MAAM,iBAAiB,QACvC,MAAM,QACN,IAAI,MAAM,wBAAwB;AACxC,aAAK,YAAY,MAAM;AAAA,MACzB;AACA,WAAK,WAAW;AAChB,WAAK,YAAY,KAAK,IAAA;AACtB,eAAS,MAAA;AACT,WAAK,SAAS,WAAW;AAAA,IAC3B,SAAS,KAAK;AACZ,WAAK,cAAA;AACL,WAAK,WAAW;AAChB,YAAM,QACJ,eAAe,QAAQ,MAAM,IAAI,MAAM,2BAA2B;AACpE,WAAK,SAAS,MAAM;AACpB,WAAK,YAAY,KAAK;AACtB,YAAM;AAAA,IACR,UAAA;AACE,WAAK,WAAW;AAGhB,WAAK,gBAAgB;AAAA,IACvB;AAAA,EACF;AAAA,EAEA,OAAgC;AAC9B,QAAI,KAAK,WAAW,eAAe,CAAC,KAAK,UAAU;AACjD,aAAO,QAAQ;AAAA,QACb,IAAI,MAAM,iDAAiD;AAAA,MAAA;AAAA,IAE/D;AACA,SAAK,SAAS,UAAU;AACxB,UAAM,WAAW,KAAK;AACtB,WAAO,IAAI,QAAwB,CAAC,SAAS,WAAW;AAGtD,YAAM,WAAW,WAAW,MAAM;AAChC,YAAI,KAAK,WAAW,YAAY;AAC9B;AAAA,QACF;AAGA,aAAK,eAAA;AACL,YAAI,KAAK,OAAO,SAAS,GAAG;AAI1B,eAAK,KAAK,SAAA;AAAA,QACZ,OAAO;AACL,eAAK;AAAA,YACH,IAAI,MAAM,kDAAkD;AAAA,UAAA;AAAA,QAEhE;AAAA,MACF,GAAG,GAAM;AACT,WAAK,cAAc,CAAC,QAAQ;AAC1B,qBAAa,QAAQ;AACrB,gBAAQ,GAAG;AAAA,MACb;AACA,WAAK,aAAa,CAAC,QAAQ;AACzB,qBAAa,QAAQ;AACrB,eAAO,GAAG;AAAA,MACZ;AACA,eAAS,KAAA;AAAA,IACX,CAAC;AAAA,EACH;AAAA,EAEA,SAAe;AACb,QAAI,KAAK,UAAU;AAGjB,WAAK,gBAAgB;AACrB;AAAA,IACF;AACA,QAAI,KAAK,WAAW,QAAQ;AAC1B;AAAA,IACF;AACA,UAAM,WAAW,KAAK;AACtB,QAAI,UAAU;AAGZ,WAAK,eAAA;AACL,UAAI;AACF,iBAAS,KAAA;AAAA,MACX,SAAS,KAAK;AAIZ,YACE,EAAE,eAAe,gBAAgB,IAAI,SAAS,sBAC9C;AACA,eAAK;AAAA,YACH,eAAe,QAAQ,MAAM,IAAI,MAAM,yBAAyB;AAAA,UAAA;AAAA,QAEpE;AAAA,MACF;AAAA,IACF;AACA,SAAK,cAAA;AACL,SAAK,WAAW;AAChB,SAAK,SAAS,CAAA;AACd,UAAM,SAAS,KAAK;AACpB,SAAK,cAAc;AACnB,SAAK,aAAa;AAClB,SAAK,SAAS,MAAM;AACpB,aAAS,IAAI,MAAM,qBAAqB,CAAC;AAAA,EAC3C;AAAA,EAEA,MAAc,WAA0B;AACtC,UAAM,WAAW,KAAK,UAAU,YAAY;AAC5C,UAAM,aAAa,KAAK,IAAA,IAAQ,KAAK;AACrC,QAAI;AACF,YAAM,OAAO,IAAI,KAAK,KAAK,QAAQ,EAAE,MAAM,UAAU;AACrD,YAAM,SAAS,oBAAoB,MAAM,KAAK,aAAa;AAC3D,YAAM,YAA4B;AAAA,QAChC;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,MAAM;AAAA,UACJ,MAAM;AAAA,UACN,QAAQ,EAAE,MAAM,QAAQ,OAAO,QAAQ,SAAA;AAAA,QAAS;AAAA,MAClD;AAEF,WAAK,cAAA;AACL,WAAK,WAAW;AAChB,WAAK,SAAS,CAAA;AACd,YAAM,UAAU,KAAK;AACrB,WAAK,cAAc;AACnB,WAAK,aAAa;AAClB,WAAK,SAAS,MAAM;AACpB,gBAAU,SAAS;AAAA,IACrB,SAAS,KAAK;AACZ,WAAK;AAAA,QACH,eAAe,QAAQ,MAAM,IAAI,MAAM,8BAA8B;AAAA,MAAA;AAAA,IAEzE;AAAA,EACF;AAAA,EAEQ,YAAY,OAAoB;AACtC,SAAK,cAAA;AACL,SAAK,WAAW;AAChB,SAAK,SAAS,CAAA;AACd,UAAM,SAAS,KAAK;AACpB,SAAK,cAAc;AACnB,SAAK,aAAa;AAClB,SAAK,SAAS,MAAM;AAIpB,aAAS,KAAK;AACd,SAAK,YAAY,KAAK;AAAA,EACxB;AAAA;AAAA;AAAA,EAIQ,YAAY,OAAoB;AACtC,QAAI;AACF,WAAK,QAAQ,UAAU,KAAK;AAAA,IAC9B,QAAQ;AAAA,IAER;AAAA,EACF;AAAA,EAEQ,gBAAsB;AAC5B,SAAK,QAAQ,YAAY,QAAQ,CAAC,MAAM,EAAE,MAAM;AAChD,SAAK,SAAS;AAAA,EAChB;AAAA;AAAA,EAGQ,iBAAuB;AAC7B,UAAM,WAAW,KAAK;AACtB,QAAI,CAAC,UAAU;AACb;AAAA,IACF;AACA,aAAS,SAAS;AAClB,aAAS,UAAU;AACnB,aAAS,kBAAkB;AAAA,EAC7B;AACF;"}

package/dist/esm/generation-types.d.ts

@@ -3,7 +3,26 @@ import { ConnectConnectionAdapter } from './connection-adapters.js';
 import { AIDevtoolsClientMetadata } from './devtools.js';
 import { GenerationDevtoolsBridgeFactory, VideoDevtoolsBridgeFactory } from './devtools-noop.js';
 /**
- * Infers the output type from an `onResult` callback's return type.
+ * Maps an `onResult` transform's raw return type to the stored output type.
+ *
+ * - A concrete return (excluding null/void/undefined) becomes the output type.
+ * - A return of only null/void/undefined falls back to TResult (the transform
+ *   reacted to the result or chose to keep it, rather than replacing it).
+ *
+ * Hooks infer `TReturn` directly from the `onResult` return position — a
+ * covariant inference site that works even for an optional nested property —
+ * which both contextually types the callback parameter as `TResult` and
+ * narrows `result`. See issue #848.
+ *
+ * @template TResult - The raw result type from the generation
+ * @template TReturn - The transform's return type (defaults to `void` when no
+ *   transform is provided)
+ */
+export type InferGenerationOutputFromReturn<TResult, TReturn> = [
+    Exclude<TReturn, null | void | undefined>
+] extends [never] ? TResult : Exclude<TReturn, null | void | undefined>;
+/**
+ * Infers the output type from an `onResult` callback's type.
  *
  * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.
  * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.
@@ -11,7 +30,7 @@ import { GenerationDevtoolsBridgeFactory, VideoDevtoolsBridgeFactory } from './d
  * @template TResult - The raw result type from the generation
  * @template TFn - The onResult callback type (or undefined if not provided)
  */
-export type InferGenerationOutput<TResult, TFn> = TFn extends (result: any) => infer R ? [Exclude<R, null | void | undefined>] extends [never] ? TResult : Exclude<R, null | void | undefined> : TResult;
+export type InferGenerationOutput<TResult, TFn> = TFn extends (result: any) => infer R ? InferGenerationOutputFromReturn<TResult, R> : TResult;
 /**
  * State machine for generation clients.
  * Simpler than ChatClientState since generation is a single request/response cycle.

package/dist/esm/generation-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"generation-types.js","sources":["../../src/generation-types.ts"],"sourcesContent":["import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'\nimport type { ConnectConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type {\n  GenerationDevtoolsBridgeFactory,\n  VideoDevtoolsBridgeFactory,\n} from './devtools-noop'\n\n// ===========================\n// Inference Utilities\n// ===========================\n\n/**\n * Infers the output type from an `onResult` callback's return type.\n *\n * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.\n * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.\n *\n * @template TResult - The raw result type from the generation\n * @template TFn - The onResult callback type (or undefined if not provided)\n */\nexport type InferGenerationOutput<TResult, TFn> = TFn extends (\n  result: any,\n) => infer R\n  ? [Exclude<R, null | void | undefined>] extends [never]\n    ? TResult\n    : Exclude<R, null | void | undefined>\n  : TResult\n\n// ===========================\n// State\n// ===========================\n\n/**\n * State machine for generation clients.\n * Simpler than ChatClientState since generation is a single request/response cycle.\n */\nexport type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'\n\n// ===========================\n// Event Constants\n// ===========================\n\n/**\n * Well-known CUSTOM event names used by generation clients.\n * These events are emitted by the server-side streaming helpers\n * and consumed by the client-side GenerationClient.\n */\nexport const GENERATION_EVENTS = {\n  /** The generation result payload */\n  RESULT: 'generation:result',\n  /** Progress update (0-100) with optional message */\n  PROGRESS: 'generation:progress',\n  /** Video job created with jobId */\n  VIDEO_JOB_CREATED: 'video:job:created',\n  /** Video job status update */\n  VIDEO_STATUS: 'video:status',\n} as const\n\n// ===========================\n// Transport Types\n// ===========================\n\n/**\n * Options passed to a fetcher function by the generation client.\n */\nexport interface GenerationFetcherOptions {\n  /** AbortSignal that is triggered when the user calls `stop()` */\n  signal: AbortSignal\n}\n\n/**\n * A direct async function that performs a generation request.\n *\n * Can return the result directly, or return a `Response` with an SSE body\n * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).\n * When a `Response` is returned, the client will parse it as an SSE stream.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n */\nexport type GenerationFetcher<TInput, TResult> = (\n  input: TInput,\n  options?: GenerationFetcherOptions,\n) => Promise<TResult | Response>\n\n/**\n * Transport configuration for generation clients.\n * Supports either a connect-based streaming adapter or a direct fetcher function.\n */\nexport type GenerationTransport<TInput, TResult> =\n  | { connection: ConnectConnectionAdapter; fetcher?: never }\n  | { fetcher: GenerationFetcher<TInput, TResult>; connection?: never }\n\n// ===========================\n// Client Options\n// ===========================\n\n/**\n * Options for the GenerationClient.\n *\n * @template TInput - The input type for the generation request (used by consuming code)\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention -- _TInput is unused in the interface body but part of the public positional generic API (callers supply it for inference)\nexport interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {\n  /** Unique identifier for this generation client instance */\n  id?: string\n\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n\n  /** Metadata used to register this generation hook with TanStack AI Devtools */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory\n\n  /**\n   * Callback when a result is received. Can optionally return a transformed value\n   * that replaces the stored result.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: TResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n\n  // Framework state callbacks (set by hooks, not users)\n  /** @internal Called when result changes */\n  onResultChange?: (result: TOutput | null) => void\n  /** @internal Called when loading state changes */\n  onLoadingChange?: (isLoading: boolean) => void\n  /** @internal Called when error state changes */\n  onErrorChange?: (error: Error | undefined) => void\n  /** @internal Called when generation status changes */\n  onStatusChange?: (status: GenerationClientState) => void\n}\n\n// ===========================\n// Video-Specific Options\n// ===========================\n\n/**\n * Video status information returned during job polling.\n */\nexport interface VideoStatusInfo {\n  /** Job identifier */\n  jobId: string\n  /** Current status of the video generation job */\n  status: 'pending' | 'processing' | 'completed' | 'failed'\n  /** Progress percentage (0-100), if available */\n  progress?: number\n  /** URL to the generated video (when completed) */\n  url?: string\n  /** Error message if status is 'failed' */\n  error?: string\n}\n\n/**\n * Composite result for video generation (job completion).\n */\nexport interface VideoGenerateResult {\n  /** Job identifier */\n  jobId: string\n  /** Final status */\n  status: 'completed'\n  /** URL to the generated video */\n  url: string\n  /** When the URL expires, if applicable */\n  expiresAt?: Date\n}\n\n/**\n * Options for the VideoGenerationClient.\n */\nexport interface VideoGenerationClientOptions<\n  TOutput = VideoGenerateResult,\n> extends Omit<\n  GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>,\n  'devtoolsBridgeFactory'\n> {\n  /**\n   * Factory that constructs the video devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory\n\n  /** Callback when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n\n  // Framework state callbacks\n  /** @internal Called when jobId changes */\n  onJobIdChange?: (jobId: string | null) => void\n  /** @internal Called when video status changes */\n  onVideoStatusChange?: (status: VideoStatusInfo | null) => void\n}\n\n// ===========================\n// Input Types\n// ===========================\n\n/**\n * Input for image generation.\n */\nexport interface ImageGenerateInput {\n  /**\n   * Description of the desired image(s): plain text, or an ordered array of\n   * content parts (text + image) for image-conditioned generation\n   * (image-to-image, multi-reference, edit / inpaint).\n   */\n  prompt: MediaPrompt\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: string\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio generation (music, sound effects).\n */\nexport interface AudioGenerateInput {\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text-to-speech generation.\n */\nexport interface SpeechGenerateInput {\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio transcription.\n */\nexport interface TranscriptionGenerateInput {\n  /** The audio data to transcribe - can be base64 string, File, Blob, or ArrayBuffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text summarization.\n */\nexport interface SummarizeGenerateInput {\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary */\n  maxLength?: number\n  /** Style of the summary */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics to focus on */\n  focus?: Array<string>\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for video generation.\n */\nexport interface VideoGenerateInput {\n  /**\n   * Description of the desired video: plain text, or an ordered array of\n   * content parts (text + image) for image-conditioned generation\n   * (image-to-video, start/end frames).\n   */\n  prompt: MediaPrompt\n  /** Video size — format depends on provider (e.g., \"16:9\", \"1280x720\") */\n  size?: string\n  /** Video duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n"],"names":[],"mappings":"AAgDO,MAAM,oBAAoB;AAAA;AAAA,EAE/B,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,mBAAmB;AAAA;AAAA,EAEnB,cAAc;AAChB;"}
+{"version":3,"file":"generation-types.js","sources":["../../src/generation-types.ts"],"sourcesContent":["import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'\nimport type { ConnectConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type {\n  GenerationDevtoolsBridgeFactory,\n  VideoDevtoolsBridgeFactory,\n} from './devtools-noop'\n\n// ===========================\n// Inference Utilities\n// ===========================\n\n/**\n * Maps an `onResult` transform's raw return type to the stored output type.\n *\n * - A concrete return (excluding null/void/undefined) becomes the output type.\n * - A return of only null/void/undefined falls back to TResult (the transform\n *   reacted to the result or chose to keep it, rather than replacing it).\n *\n * Hooks infer `TReturn` directly from the `onResult` return position — a\n * covariant inference site that works even for an optional nested property —\n * which both contextually types the callback parameter as `TResult` and\n * narrows `result`. See issue #848.\n *\n * @template TResult - The raw result type from the generation\n * @template TReturn - The transform's return type (defaults to `void` when no\n *   transform is provided)\n */\nexport type InferGenerationOutputFromReturn<TResult, TReturn> = [\n  Exclude<TReturn, null | void | undefined>,\n] extends [never]\n  ? TResult\n  : Exclude<TReturn, null | void | undefined>\n\n/**\n * Infers the output type from an `onResult` callback's type.\n *\n * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.\n * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.\n *\n * @template TResult - The raw result type from the generation\n * @template TFn - The onResult callback type (or undefined if not provided)\n */\nexport type InferGenerationOutput<TResult, TFn> = TFn extends (\n  result: any,\n) => infer R\n  ? InferGenerationOutputFromReturn<TResult, R>\n  : TResult\n\n// ===========================\n// State\n// ===========================\n\n/**\n * State machine for generation clients.\n * Simpler than ChatClientState since generation is a single request/response cycle.\n */\nexport type GenerationClientState = 'idle' | 'generating' | 'success' | 'error'\n\n// ===========================\n// Event Constants\n// ===========================\n\n/**\n * Well-known CUSTOM event names used by generation clients.\n * These events are emitted by the server-side streaming helpers\n * and consumed by the client-side GenerationClient.\n */\nexport const GENERATION_EVENTS = {\n  /** The generation result payload */\n  RESULT: 'generation:result',\n  /** Progress update (0-100) with optional message */\n  PROGRESS: 'generation:progress',\n  /** Video job created with jobId */\n  VIDEO_JOB_CREATED: 'video:job:created',\n  /** Video job status update */\n  VIDEO_STATUS: 'video:status',\n} as const\n\n// ===========================\n// Transport Types\n// ===========================\n\n/**\n * Options passed to a fetcher function by the generation client.\n */\nexport interface GenerationFetcherOptions {\n  /** AbortSignal that is triggered when the user calls `stop()` */\n  signal: AbortSignal\n}\n\n/**\n * A direct async function that performs a generation request.\n *\n * Can return the result directly, or return a `Response` with an SSE body\n * (e.g., from a TanStack Start server function using `toServerSentEventsResponse()`).\n * When a `Response` is returned, the client will parse it as an SSE stream.\n *\n * @template TInput - The input type for the generation request\n * @template TResult - The result type returned by the generation\n */\nexport type GenerationFetcher<TInput, TResult> = (\n  input: TInput,\n  options?: GenerationFetcherOptions,\n) => Promise<TResult | Response>\n\n/**\n * Transport configuration for generation clients.\n * Supports either a connect-based streaming adapter or a direct fetcher function.\n */\nexport type GenerationTransport<TInput, TResult> =\n  | { connection: ConnectConnectionAdapter; fetcher?: never }\n  | { fetcher: GenerationFetcher<TInput, TResult>; connection?: never }\n\n// ===========================\n// Client Options\n// ===========================\n\n/**\n * Options for the GenerationClient.\n *\n * @template TInput - The input type for the generation request (used by consuming code)\n * @template TResult - The result type returned by the generation\n * @template TOutput - The output type after optional transform (defaults to TResult)\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention -- _TInput is unused in the interface body but part of the public positional generic API (callers supply it for inference)\nexport interface GenerationClientOptions<_TInput, TResult, TOutput = TResult> {\n  /** Unique identifier for this generation client instance */\n  id?: string\n\n  /** Additional body parameters to send with connect-based adapter requests */\n  body?: Record<string, any>\n\n  /** Metadata used to register this generation hook with TanStack AI Devtools */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: GenerationDevtoolsBridgeFactory\n\n  /**\n   * Callback when a result is received. Can optionally return a transformed value\n   * that replaces the stored result.\n   *\n   * - Return a non-null value to transform and store it as the result\n   * - Return `null` to keep the previous result unchanged\n   * - Return nothing (`void`) to store the raw result as-is\n   */\n  onResult?: (result: TResult) => TOutput | null | void\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void\n  /** Callback when progress is reported (0-100) */\n  onProgress?: (progress: number, message?: string) => void\n  /** Callback for each stream chunk (connect-based adapter mode only) */\n  onChunk?: (chunk: StreamChunk) => void\n\n  // Framework state callbacks (set by hooks, not users)\n  /** @internal Called when result changes */\n  onResultChange?: (result: TOutput | null) => void\n  /** @internal Called when loading state changes */\n  onLoadingChange?: (isLoading: boolean) => void\n  /** @internal Called when error state changes */\n  onErrorChange?: (error: Error | undefined) => void\n  /** @internal Called when generation status changes */\n  onStatusChange?: (status: GenerationClientState) => void\n}\n\n// ===========================\n// Video-Specific Options\n// ===========================\n\n/**\n * Video status information returned during job polling.\n */\nexport interface VideoStatusInfo {\n  /** Job identifier */\n  jobId: string\n  /** Current status of the video generation job */\n  status: 'pending' | 'processing' | 'completed' | 'failed'\n  /** Progress percentage (0-100), if available */\n  progress?: number\n  /** URL to the generated video (when completed) */\n  url?: string\n  /** Error message if status is 'failed' */\n  error?: string\n}\n\n/**\n * Composite result for video generation (job completion).\n */\nexport interface VideoGenerateResult {\n  /** Job identifier */\n  jobId: string\n  /** Final status */\n  status: 'completed'\n  /** URL to the generated video */\n  url: string\n  /** When the URL expires, if applicable */\n  expiresAt?: Date\n}\n\n/**\n * Options for the VideoGenerationClient.\n */\nexport interface VideoGenerationClientOptions<\n  TOutput = VideoGenerateResult,\n> extends Omit<\n  GenerationClientOptions<VideoGenerateInput, VideoGenerateResult, TOutput>,\n  'devtoolsBridgeFactory'\n> {\n  /**\n   * Factory that constructs the video devtools bridge. Default is a no-op\n   * factory; the real implementation lives in `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: VideoDevtoolsBridgeFactory\n\n  /** Callback when a video job is created */\n  onJobCreated?: (jobId: string) => void\n  /** Callback on each status update */\n  onStatusUpdate?: (status: VideoStatusInfo) => void\n\n  // Framework state callbacks\n  /** @internal Called when jobId changes */\n  onJobIdChange?: (jobId: string | null) => void\n  /** @internal Called when video status changes */\n  onVideoStatusChange?: (status: VideoStatusInfo | null) => void\n}\n\n// ===========================\n// Input Types\n// ===========================\n\n/**\n * Input for image generation.\n */\nexport interface ImageGenerateInput {\n  /**\n   * Description of the desired image(s): plain text, or an ordered array of\n   * content parts (text + image) for image-conditioned generation\n   * (image-to-image, multi-reference, edit / inpaint).\n   */\n  prompt: MediaPrompt\n  /** Number of images to generate (default: 1) */\n  numberOfImages?: number\n  /** Image size in WIDTHxHEIGHT format (e.g., \"1024x1024\") */\n  size?: string\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio generation (music, sound effects).\n */\nexport interface AudioGenerateInput {\n  /** Text description of the desired audio */\n  prompt: string\n  /** Desired duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text-to-speech generation.\n */\nexport interface SpeechGenerateInput {\n  /** The text to convert to speech */\n  text: string\n  /** The voice to use for generation */\n  voice?: string\n  /** The output audio format */\n  format?: 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'\n  /** The speed of the generated audio (0.25 to 4.0) */\n  speed?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for audio transcription.\n */\nexport interface TranscriptionGenerateInput {\n  /** The audio data to transcribe - can be base64 string, File, Blob, or ArrayBuffer */\n  audio: string | File | Blob | ArrayBuffer\n  /** The language of the audio in ISO-639-1 format (e.g., 'en') */\n  language?: string\n  /** An optional prompt to guide the transcription */\n  prompt?: string\n  /** The format of the transcription output */\n  responseFormat?: 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for text summarization.\n */\nexport interface SummarizeGenerateInput {\n  /** The text to summarize */\n  text: string\n  /** Maximum length of the summary */\n  maxLength?: number\n  /** Style of the summary */\n  style?: 'bullet-points' | 'paragraph' | 'concise'\n  /** Topics to focus on */\n  focus?: Array<string>\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n\n/**\n * Input for video generation.\n */\nexport interface VideoGenerateInput {\n  /**\n   * Description of the desired video: plain text, or an ordered array of\n   * content parts (text + image) for image-conditioned generation\n   * (image-to-video, start/end frames).\n   */\n  prompt: MediaPrompt\n  /** Video size — format depends on provider (e.g., \"16:9\", \"1280x720\") */\n  size?: string\n  /** Video duration in seconds */\n  duration?: number\n  /** Model-specific options */\n  modelOptions?: Record<string, any>\n}\n"],"names":[],"mappings":"AAoEO,MAAM,oBAAoB;AAAA;AAAA,EAE/B,QAAQ;AAAA;AAAA,EAER,UAAU;AAAA;AAAA,EAEV,mBAAmB;AAAA;AAAA,EAEnB,cAAc;AAChB;"}

package/dist/esm/index.d.ts

@@ -1,9 +1,13 @@
+export { AudioRecorder } from './audio-recorder.js';
+export type { AudioRecorderOptions, AudioRecorderState, AudioRecording, InferAudioRecordingOutput, } from './audio-recorder.js';
 export { ChatClient } from './chat-client.js';
+export { createMcpAppBridge } from './mcp-app-bridge.js';
+export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge.js';
 export { RealtimeClient } from './realtime-client.js';
 export { GenerationClient } from './generation-client.js';
 export { VideoGenerationClient } from './video-generation-client.js';
 export type { UIMessage, MessagePart, TextPart, ToolCallPart, ToolResultPart, ThinkingPart, StructuredOutputPart, ChatClientPersistence, ChatClientOptions, ClientContextOptionFromTools, ChatRequestBody, InferChatMessages, InferredClientContext, ChatClientState, ConnectionStatus, ChatFetcher, ChatFetcherInput, ChatFetcherOptions, ChatTransport, DistributedOmit, MultimodalContent, } from './types.js';
-export type { InferGenerationOutput, GenerationClientState, GenerationClientOptions, GenerationFetcher, GenerationFetcherOptions, GenerationTransport, VideoGenerationClientOptions, VideoStatusInfo, VideoGenerateResult, ImageGenerateInput, AudioGenerateInput, SpeechGenerateInput, TranscriptionGenerateInput, SummarizeGenerateInput, VideoGenerateInput, } from './generation-types.js';
+export type { InferGenerationOutput, InferGenerationOutputFromReturn, GenerationClientState, GenerationClientOptions, GenerationFetcher, GenerationFetcherOptions, GenerationTransport, VideoGenerationClientOptions, VideoStatusInfo, VideoGenerateResult, ImageGenerateInput, AudioGenerateInput, SpeechGenerateInput, TranscriptionGenerateInput, SummarizeGenerateInput, VideoGenerateInput, } from './generation-types.js';
 export { GENERATION_EVENTS } from './generation-types.js';
 export { UnsupportedResponseStreamError } from './response-stream.js';
 export { clientTools, createChatClientOptions } from './types.js';

package/dist/esm/index.js

@@ -1,4 +1,6 @@
+import { AudioRecorder } from "./audio-recorder.js";
 import { ChatClient } from "./chat-client.js";
+import { createMcpAppBridge } from "./mcp-app-bridge.js";
 import { RealtimeClient } from "./realtime-client.js";
 import { GenerationClient } from "./generation-client.js";
 import { VideoGenerationClient } from "./video-generation-client.js";
@@ -9,6 +11,7 @@ import { createAIDevtoolsGenerationPreview } from "./devtools.js";
 import { StreamTruncatedError, fetchHttpStream, fetchServerSentEvents, rpcStream, stream, xhrHttpStream, xhrServerSentEvents } from "./connection-adapters.js";
 import { BatchStrategy, CompositeStrategy, ImmediateStrategy, PartialJSONParser, PunctuationStrategy, StreamProcessor, WordBoundaryStrategy, convertMessagesToModelMessages, defaultJSONParser, generateMessageId, modelMessageToUIMessage, modelMessagesToUIMessages, normalizeToUIMessage, parsePartialJSON, uiMessageToModelMessages } from "@tanstack/ai/client";
 export {
+  AudioRecorder,
   BatchStrategy,
   ChatClient,
   CompositeStrategy,
@@ -27,6 +30,7 @@ export {
   convertMessagesToModelMessages,
   createAIDevtoolsGenerationPreview,
   createChatClientOptions,
+  createMcpAppBridge,
   defaultJSONParser,
   fetchHttpStream,
   fetchServerSentEvents,

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;"}

package/dist/esm/mcp-app-bridge.d.ts

@@ -0,0 +1,27 @@
+export interface CreateMcpAppBridgeOptions {
+    threadId: string;
+    callEndpoint: string;
+    chat: {
+        sendMessage: (content: string, body?: Record<string, unknown>) => Promise<void>;
+    };
+    fetchImpl?: typeof fetch;
+    onLink?: (url: string) => void;
+}
+export interface McpAppBridge {
+    callTool: (input: {
+        serverId?: string;
+        toolName: string;
+        args?: Record<string, unknown>;
+        /**
+         * Reserved — forwarded to the call handler for correlation purposes but
+         * not consumed by the handler. Accepted on the wire; the handler does not
+         * read it (mirrors the `meta` convention on `UIResourcePart`).
+         */
+        messageId?: string;
+    }) => Promise<unknown>;
+    sendPrompt: (text: string) => Promise<void>;
+    openLink: (url: string) => {
+        isError: boolean;
+    };
+}
+export declare function createMcpAppBridge(options: CreateMcpAppBridgeOptions): McpAppBridge;

package/dist/esm/mcp-app-bridge.js

@@ -0,0 +1,70 @@
+function isToolCallResponse(value) {
+  return value !== null && typeof value === "object" && "ok" in value && typeof value.ok === "boolean";
+}
+const SAFE_LINK_SCHEMES = /* @__PURE__ */ new Set(["http:", "https:", "mailto:"]);
+function isSafeLink(url) {
+  try {
+    return SAFE_LINK_SCHEMES.has(new URL(url).protocol);
+  } catch {
+    return false;
+  }
+}
+function createMcpAppBridge(options) {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options;
+  const doFetch = fetchImpl ?? fetch;
+  return {
+    async callTool(input) {
+      const response = await doFetch(callEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          threadId,
+          serverId: input.serverId,
+          toolName: input.toolName,
+          args: input.args,
+          messageId: input.messageId
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`MCP app tool call failed: HTTP ${response.status}`);
+      }
+      const raw = await response.json();
+      if (!isToolCallResponse(raw)) {
+        throw new Error("MCP app tool call failed");
+      }
+      if (!raw.ok) {
+        throw new Error(raw.error ?? "MCP app tool call failed");
+      }
+      return raw.result;
+    },
+    async sendPrompt(text) {
+      await chat.sendMessage(text);
+    },
+    openLink(url) {
+      if (!isSafeLink(url)) {
+        console.warn(
+          "[mcp-app-bridge] openLink rejected: unsupported URL scheme",
+          url
+        );
+        return { isError: true };
+      }
+      if (onLink) {
+        try {
+          onLink(url);
+          return { isError: false };
+        } catch (err) {
+          console.warn("[mcp-app-bridge] openLink: onLink handler threw", err);
+          return { isError: true };
+        }
+      }
+      console.warn(
+        "[mcp-app-bridge] openLink ignored: no onLink handler configured"
+      );
+      return { isError: true };
+    }
+  };
+}
+export {
+  createMcpAppBridge
+};
+//# sourceMappingURL=mcp-app-bridge.js.map

package/dist/esm/mcp-app-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-app-bridge.js","sources":["../../src/mcp-app-bridge.ts"],"sourcesContent":["export interface CreateMcpAppBridgeOptions {\n  threadId: string\n  callEndpoint: string\n  chat: {\n    sendMessage: (\n      content: string,\n      body?: Record<string, unknown>,\n    ) => Promise<void>\n  }\n  fetchImpl?: typeof fetch\n  onLink?: (url: string) => void\n}\n\nexport interface McpAppBridge {\n  callTool: (input: {\n    serverId?: string\n    toolName: string\n    args?: Record<string, unknown>\n    /**\n     * Reserved — forwarded to the call handler for correlation purposes but\n     * not consumed by the handler. Accepted on the wire; the handler does not\n     * read it (mirrors the `meta` convention on `UIResourcePart`).\n     */\n    messageId?: string\n  }) => Promise<unknown>\n  sendPrompt: (text: string) => Promise<void>\n  openLink: (url: string) => { isError: boolean }\n}\n\ninterface ToolCallResponse {\n  ok: boolean\n  result?: unknown\n  error?: string\n}\n\nfunction isToolCallResponse(value: unknown): value is ToolCallResponse {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'ok' in value &&\n    typeof value.ok === 'boolean'\n  )\n}\n\n// Links arrive from an untrusted sandboxed widget. Only hand http(s)/mailto\n// URLs to the host's onLink; reject javascript:/data:/file:/etc. so a widget\n// can't smuggle a script-executing or local-resource URL through the bridge.\nconst SAFE_LINK_SCHEMES = new Set(['http:', 'https:', 'mailto:'])\nfunction isSafeLink(url: string): boolean {\n  try {\n    return SAFE_LINK_SCHEMES.has(new URL(url).protocol)\n  } catch {\n    return false\n  }\n}\n\nexport function createMcpAppBridge(\n  options: CreateMcpAppBridgeOptions,\n): McpAppBridge {\n  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options\n  const doFetch = fetchImpl ?? fetch\n\n  return {\n    async callTool(input) {\n      const response = await doFetch(callEndpoint, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json' },\n        body: JSON.stringify({\n          threadId,\n          serverId: input.serverId,\n          toolName: input.toolName,\n          args: input.args,\n          messageId: input.messageId,\n        }),\n      })\n\n      if (!response.ok) {\n        throw new Error(`MCP app tool call failed: HTTP ${response.status}`)\n      }\n\n      const raw: unknown = await response.json()\n      if (!isToolCallResponse(raw)) {\n        throw new Error('MCP app tool call failed')\n      }\n\n      if (!raw.ok) {\n        throw new Error(raw.error ?? 'MCP app tool call failed')\n      }\n\n      return raw.result\n    },\n\n    async sendPrompt(text) {\n      await chat.sendMessage(text)\n    },\n\n    openLink(url) {\n      if (!isSafeLink(url)) {\n        console.warn(\n          '[mcp-app-bridge] openLink rejected: unsupported URL scheme',\n          url,\n        )\n        return { isError: true }\n      }\n      if (onLink) {\n        try {\n          onLink(url)\n          return { isError: false }\n        } catch (err) {\n          console.warn('[mcp-app-bridge] openLink: onLink handler threw', err)\n          return { isError: true }\n        }\n      }\n      console.warn(\n        '[mcp-app-bridge] openLink ignored: no onLink handler configured',\n      )\n      return { isError: true }\n    },\n  }\n}\n"],"names":[],"mappings":"AAmCA,SAAS,mBAAmB,OAA2C;AACrE,SACE,UAAU,QACV,OAAO,UAAU,YACjB,QAAQ,SACR,OAAO,MAAM,OAAO;AAExB;AAKA,MAAM,oBAAoB,oBAAI,IAAI,CAAC,SAAS,UAAU,SAAS,CAAC;AAChE,SAAS,WAAW,KAAsB;AACxC,MAAI;AACF,WAAO,kBAAkB,IAAI,IAAI,IAAI,GAAG,EAAE,QAAQ;AAAA,EACpD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,SAAS,mBACd,SACc;AACd,QAAM,EAAE,UAAU,cAAc,MAAM,WAAW,WAAW;AAC5D,QAAM,UAAU,aAAa;AAE7B,SAAO;AAAA,IACL,MAAM,SAAS,OAAO;AACpB,YAAM,WAAW,MAAM,QAAQ,cAAc;AAAA,QAC3C,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,mBAAA;AAAA,QAC3B,MAAM,KAAK,UAAU;AAAA,UACnB;AAAA,UACA,UAAU,MAAM;AAAA,UAChB,UAAU,MAAM;AAAA,UAChB,MAAM,MAAM;AAAA,UACZ,WAAW,MAAM;AAAA,QAAA,CAClB;AAAA,MAAA,CACF;AAED,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,IAAI,MAAM,kCAAkC,SAAS,MAAM,EAAE;AAAA,MACrE;AAEA,YAAM,MAAe,MAAM,SAAS,KAAA;AACpC,UAAI,CAAC,mBAAmB,GAAG,GAAG;AAC5B,cAAM,IAAI,MAAM,0BAA0B;AAAA,MAC5C;AAEA,UAAI,CAAC,IAAI,IAAI;AACX,cAAM,IAAI,MAAM,IAAI,SAAS,0BAA0B;AAAA,MACzD;AAEA,aAAO,IAAI;AAAA,IACb;AAAA,IAEA,MAAM,WAAW,MAAM;AACrB,YAAM,KAAK,YAAY,IAAI;AAAA,IAC7B;AAAA,IAEA,SAAS,KAAK;AACZ,UAAI,CAAC,WAAW,GAAG,GAAG;AACpB,gBAAQ;AAAA,UACN;AAAA,UACA;AAAA,QAAA;AAEF,eAAO,EAAE,SAAS,KAAA;AAAA,MACpB;AACA,UAAI,QAAQ;AACV,YAAI;AACF,iBAAO,GAAG;AACV,iBAAO,EAAE,SAAS,MAAA;AAAA,QACpB,SAAS,KAAK;AACZ,kBAAQ,KAAK,mDAAmD,GAAG;AACnE,iBAAO,EAAE,SAAS,KAAA;AAAA,QACpB;AAAA,MACF;AACA,cAAQ;AAAA,QACN;AAAA,MAAA;AAEF,aAAO,EAAE,SAAS,KAAA;AAAA,IACpB;AAAA,EAAA;AAEJ;"}

package/dist/esm/types.d.ts

@@ -1,4 +1,4 @@
-import { AnyClientTool, AudioPart, ChunkStrategy, ContentPart, DocumentPart, ImagePart, InferToolInput, InferToolOutput, ModelMessage, StreamChunk, StructuredOutputPart, VideoPart } from '@tanstack/ai/client';
+import { AnyClientTool, AudioPart, ChunkStrategy, ContentPart, DocumentPart, ImagePart, InferToolInput, InferToolOutput, ModelMessage, StreamChunk, StructuredOutputPart, UIResourcePart, VideoPart } from '@tanstack/ai/client';
 import { ConnectionAdapter } from './connection-adapters.js';
 import { AIDevtoolsClientMetadata } from './devtools.js';
 import { ChatDevtoolsBridgeFactory } from './devtools-noop.js';
@@ -171,7 +171,7 @@ export interface ThinkingPart {
     type: 'thinking';
     content: string;
 }
-export type MessagePart<TTools extends ReadonlyArray<AnyClientTool> = any, TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart<TTools> | ToolResultPart | ThinkingPart | StructuredOutputPart<TData>;
+export type MessagePart<TTools extends ReadonlyArray<AnyClientTool> = any, TData = unknown> = TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | ToolCallPart<TTools> | ToolResultPart | ThinkingPart | StructuredOutputPart<TData> | UIResourcePart;
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs
  * Contains parts that can be text, tool calls, or tool results.

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  AnyClientTool,\n  AudioPart,\n  ChunkStrategy,\n  ContentPart,\n  DocumentPart,\n  ImagePart,\n  InferToolInput,\n  InferToolOutput,\n  ModelMessage,\n  StreamChunk,\n  StructuredOutputPart,\n  VideoPart,\n} from '@tanstack/ai/client'\nimport type { ConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type { ChatDevtoolsBridgeFactory } from './devtools-noop'\n\nexport type { StructuredOutputPart } from '@tanstack/ai/client'\n\n/**\n * `messages` is the full UIMessage history (not a delta). `data` is the\n * merged body — `ChatClientOptions.body` plus any per-call data passed to\n * `sendMessage(...)`. `threadId` / `runId` are the AG-UI correlation ids\n * the chat client uses to track this turn — forward them to your server\n * if it needs to correlate requests.\n */\nexport interface ChatFetcherInput {\n  messages: Array<UIMessage>\n  data?: Record<string, unknown>\n  threadId: string\n  runId: string\n}\n\nexport interface ChatFetcherOptions {\n  /** Fires when `stop()` is called or the request is superseded. */\n  signal: AbortSignal\n}\n\n/**\n * Direct function that performs a chat request. Mirrors\n * `GenerationFetcher`. Returns either a `Response` (SSE body parsed by the\n * chat client) or an `AsyncIterable<StreamChunk>` (yielded directly). May\n * return the value synchronously, as a `Promise`, or as an async generator\n * (`async function*`) — the chat client awaits whichever shape is returned.\n *\n * @example\n * ```ts\n * useChat({\n *   fetcher: ({ messages }, { signal }) =>\n *     chatFn({ data: { messages }, signal }),\n * })\n * ```\n */\nexport type ChatFetcher = (\n  input: ChatFetcherInput,\n  options: ChatFetcherOptions,\n) =>\n  | Response\n  | AsyncIterable<StreamChunk>\n  | Promise<Response | AsyncIterable<StreamChunk>>\n\n/**\n * Distributive `Omit` — applies `Omit<O, K>` per branch of a union so\n * discriminated unions survive omission. Plain `Omit` collapses unions\n * into a single object shape, which would erase the `ChatTransport` XOR\n * when framework hooks omit React-managed callbacks from\n * `ChatClientOptions`.\n */\nexport type DistributedOmit<\n  TObject,\n  TKeys extends keyof any,\n> = TObject extends unknown ? Omit<TObject, TKeys> : never\n\n/**\n * Discriminated union enforcing that exactly one of `connection` or\n * `fetcher` is provided. Mirrors `GenerationTransport`.\n */\nexport type ChatTransport =\n  | { connection: ConnectionAdapter; fetcher?: never }\n  | { fetcher: ChatFetcher; connection?: never }\n\n/**\n * Tool call states - track the lifecycle of a tool call\n */\nexport type ToolCallState =\n  | 'awaiting-input' // Received start but no arguments yet\n  | 'input-streaming' // Partial arguments received\n  | 'input-complete' // All arguments received\n  | 'approval-requested' // Waiting for user approval\n  | 'approval-responded' // User has approved/denied\n  | 'complete' // Result is complete\n  | 'error' // Tool execution failed (terminal)\n\n/**\n * Tool result states - track the lifecycle of a tool result\n */\nexport type ToolResultState =\n  | 'streaming' // Placeholder for future streamed output\n  | 'complete' // Result is complete\n  | 'error' // Error occurred\n\n/**\n * ChatClient state - track the lifecycle of a chat\n */\nexport type ChatClientState = 'ready' | 'submitted' | 'streaming' | 'error'\n\n/**\n * Connection lifecycle state for the subscription loop.\n */\nexport type ConnectionStatus =\n  | 'disconnected'\n  | 'connecting'\n  | 'connected'\n  | 'error'\n\n/**\n * Multimodal content input for sending messages with rich media.\n * Allows sending text, images, audio, video, and documents to the LLM.\n *\n * @example\n * ```ts\n * // Send an image with a question\n * client.sendMessage({\n *   content: [\n *     { type: 'text', content: 'What is in this image?' },\n *     { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }\n *   ],\n *   id: 'custom-message-id' // optional\n * })\n * ```\n */\nexport interface MultimodalContent {\n  /**\n   * The content of the message.\n   * Can be a simple string or an array of content parts for multimodal messages.\n   */\n  content: string | Array<ContentPart>\n  /**\n   * Optional custom ID for the message.\n   * If not provided, a unique ID will be generated.\n   */\n  id?: string\n}\n\n/**\n * Message parts - building blocks of UIMessage\n */\nexport interface TextPart {\n  type: 'text'\n  content: string\n}\n\n/**\n * Helper type that creates a tool-call part for a specific tool.\n * This is a conditional type to enable proper distribution over union types,\n * creating a discriminated union where `name` is the discriminant.\n */\ntype ToolCallPartForTool<T> = T extends AnyClientTool\n  ? {\n      type: 'tool-call'\n      id: string\n      name: T['name']\n      arguments: string // JSON string (may be incomplete)\n      /** Parsed tool input (typed from inputSchema) */\n      input?: InferToolInput<T>\n      state: ToolCallState\n      /** Approval metadata if tool requires user approval */\n      approval?: {\n        id: string // Unique approval ID\n        needsApproval: boolean // Always true if present\n        approved?: boolean // User's decision (undefined until responded)\n      }\n      /** Tool execution output (for client tools or after approval) */\n      output?: InferToolOutput<T>\n    }\n  : never\n\n/**\n * Fallback tool-call part type when tools are not typed\n */\ntype UntypedToolCallPart = {\n  type: 'tool-call'\n  id: string\n  name: string\n  arguments: string\n  input?: any\n  state: ToolCallState\n  approval?: {\n    id: string\n    needsApproval: boolean\n    approved?: boolean\n  }\n  output?: any\n}\n\n/**\n * Tool call part that creates a proper discriminated union.\n * When TTools is typed, checking `part.name === 'toolName'` will narrow\n * `part.output` to the correct type for that tool.\n *\n * The discriminant is `name`, so code like:\n * ```ts\n * if (part.name === 'recommendGuitar') {\n *   // part.output is now typed to the recommendGuitar tool's output\n * }\n * ```\n */\nexport type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> =\n  // Check if we have a concrete tools array (not 'any' or 'never')\n  [TTools] extends [never]\n    ? UntypedToolCallPart\n    : unknown extends TTools\n      ? UntypedToolCallPart\n      : TTools extends ReadonlyArray<infer Tool>\n        ? Tool extends AnyClientTool\n          ? ToolCallPartForTool<Tool>\n          : UntypedToolCallPart\n        : UntypedToolCallPart\n\nexport interface ToolResultPart {\n  type: 'tool-result'\n  toolCallId: string\n  content: string | Array<ContentPart>\n  state: ToolResultState\n  error?: string // Error message if state is \"error\"\n}\n\nexport interface ThinkingPart {\n  type: 'thinking'\n  content: string\n}\n\nexport type MessagePart<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> =\n  | TextPart\n  | ImagePart\n  | AudioPart\n  | VideoPart\n  | DocumentPart\n  | ToolCallPart<TTools>\n  | ToolResultPart\n  | ThinkingPart\n  | StructuredOutputPart<TData>\n\n/**\n * UIMessage - Domain-specific message format optimized for building chat UIs\n * Contains parts that can be text, tool calls, or tool results.\n *\n * `TTools` narrows the tool-call/result part types based on the registered\n * tools. `TData` is the schema-inferred type for any `structured-output` part\n * on the message — defaulted to `unknown` so untyped consumers (the core\n * stream processor, the wire converter) don't need to thread a schema generic\n * everywhere; the hook layer (`useChat({ outputSchema })`) substitutes it on\n * the public return so `m.parts.find(p => p.type === 'structured-output').data`\n * is typed without manual casts.\n */\nexport interface UIMessage<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> {\n  id: string\n  role: 'system' | 'user' | 'assistant'\n  parts: Array<MessagePart<TTools, TData>>\n  createdAt?: Date\n}\n\nexport interface ChatClientPersistence<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n> {\n  getItem: (\n    id: string,\n  ) =>\n    | Array<UIMessage<TTools>>\n    | null\n    | undefined\n    | Promise<Array<UIMessage<TTools>> | null | undefined>\n  setItem: (\n    id: string,\n    messages: Array<UIMessage<TTools>>,\n  ) => void | Promise<void>\n  removeItem: (id: string) => void | Promise<void>\n}\n\ntype IsUnknown<T> = unknown extends T\n  ? [T] extends [unknown]\n    ? true\n    : false\n  : false\n\ntype KnownContext<T> = IsUnknown<T> extends true ? never : T\n\ntype MergeContext<TLeft, TRight> = [TLeft] extends [never]\n  ? TRight\n  : [TRight] extends [never]\n    ? TLeft\n    : TLeft & TRight\n\ntype UnionToIntersection<T> = [T] extends [never]\n  ? never\n  : (T extends unknown ? (value: T) => void : never) extends (\n        value: infer TIntersection,\n      ) => void\n    ? TIntersection\n    : never\n\ntype DefinedContext<T> = Exclude<T, undefined>\n\ntype ContextFromExecute<T> = T extends (...args: any) => any\n  ? NonNullable<Parameters<T>[1]> extends { context: infer TContext }\n    ? KnownContext<TContext>\n    : never\n  : never\n\ntype ContextFromClientTool<T> = T extends AnyClientTool\n  ? T extends { execute?: infer TExecute }\n    ? ContextFromExecute<TExecute>\n    : never\n  : never\n\ntype RequiredContextFromClientToolUnion<T> = T extends unknown\n  ? undefined extends ContextFromClientTool<T>\n    ? never\n    : ContextFromClientTool<T>\n  : never\n\ntype ContextFromClientToolUnion<T> = [\n  UnionToIntersection<DefinedContext<ContextFromClientTool<T>>>,\n] extends [never]\n  ? never\n  : [RequiredContextFromClientToolUnion<T>] extends [never]\n    ? UnionToIntersection<DefinedContext<ContextFromClientTool<T>>> | undefined\n    : UnionToIntersection<DefinedContext<ContextFromClientTool<T>>>\n\ntype ContextFromClientTools<TTools> =\n  IsUnknown<TTools> extends true\n    ? never\n    : TTools extends readonly [infer THead, ...infer TTail]\n      ? MergeContext<\n          ContextFromClientTool<THead>,\n          ContextFromClientTools<TTail>\n        >\n      : TTools extends ReadonlyArray<infer TItem>\n        ? ContextFromClientToolUnion<TItem>\n        : never\n\nexport type InferredClientContext<TTools> = [\n  ContextFromClientTools<TTools>,\n] extends [never]\n  ? unknown\n  : ContextFromClientTools<TTools>\n\nexport type ClientContextOptionFromTools<TTools, TContext> = [\n  ContextFromClientTools<TTools>,\n] extends [never]\n  ? { context?: TContext }\n  : undefined extends ContextFromClientTools<TTools>\n    ? { context?: TContext & ContextFromClientTools<TTools> }\n    : { context: TContext & ContextFromClientTools<TTools> }\n\n/**\n * Base options for `ChatClient`, excluding the transport (`connection` or\n * `fetcher`) which is supplied separately via `ChatTransport` so the XOR\n * is preserved when composing the final `ChatClientOptions` type.\n */\nexport interface ChatClientBaseOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TContext = unknown,\n> {\n  /**\n   * Initial messages to populate the chat\n   */\n  initialMessages?: Array<UIMessage<TTools>>\n\n  /**\n   * Optional persistence adapter for chat messages.\n   */\n  persistence?: ChatClientPersistence<TTools>\n\n  /**\n   * Unique identifier for this chat instance\n   * Used for managing multiple chats\n   */\n  id?: string\n\n  /**\n   * Thread ID to use for this chat session. Persists across sends within\n   * the session. If omitted, a unique thread ID is generated.\n   */\n  threadId?: string\n\n  /**\n   * Arbitrary client-controlled JSON forwarded to the server in the\n   * AG-UI `RunAgentInput.forwardedProps` field. Use this for per-session\n   * options like provider/model selection or feature flags that the\n   * server endpoint should read.\n   *\n   * Replaces the legacy `body` option. If both are provided,\n   * `forwardedProps` wins on key collision.\n   */\n  forwardedProps?: Record<string, any>\n\n  /**\n   * @deprecated Use `forwardedProps` instead. `body` continues to work\n   * unchanged — its values are merged into the AG-UI\n   * `RunAgentInput.forwardedProps` field on the wire and are also\n   * mirrored under the legacy `data` field for servers that have not\n   * migrated yet. Will be removed in a future major release.\n   */\n  body?: Record<string, any>\n\n  /**\n   * Client-local runtime context passed to client tool implementations.\n   *\n   * This value is not serialized to the server. Use `forwardedProps` for\n   * explicit client-to-server handoff of serializable values.\n   */\n  context?: TContext\n\n  /**\n   * Callback when a response is received\n   */\n  onResponse?: (response?: Response) => void | Promise<void>\n\n  /**\n   * Callback when a stream chunk is received\n   */\n  onChunk?: (chunk: StreamChunk) => void\n\n  /**\n   * Callback when the response is finished\n   */\n  onFinish?: (message: UIMessage<TTools>) => void\n\n  /**\n   * Callback when an error occurs\n   */\n  onError?: (error: Error) => void\n\n  /**\n   * Callback when messages change\n   */\n  onMessagesChange?: (messages: Array<UIMessage<TTools>>) => void\n\n  /**\n   * Callback when loading state changes\n   */\n  onLoadingChange?: (isLoading: boolean) => void\n\n  /**\n   * Callback when error state changes\n   */\n  onErrorChange?: (error: Error | undefined) => void\n\n  /**\n   * Callback when chat status changes\n   */\n  onStatusChange?: (status: ChatClientState) => void\n\n  /**\n   * Callback when subscription lifecycle changes.\n   * This is independent from request lifecycle (`isLoading`, `status`).\n   */\n  onSubscriptionChange?: (isSubscribed: boolean) => void\n\n  /**\n   * Callback when connection lifecycle changes.\n   */\n  onConnectionStatusChange?: (status: ConnectionStatus) => void\n\n  /**\n   * Callback when session generation activity changes.\n   * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).\n   * Unlike `onLoadingChange` (request-local), this reflects shared generation\n   * activity visible to all subscribers (e.g. across tabs/devices).\n   */\n  onSessionGeneratingChange?: (isGenerating: boolean) => void\n\n  /**\n   * Callback when a custom event is received from a server-side tool.\n   * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.\n   *\n   * @param eventType - The name of the custom event\n   * @param data - The event payload data\n   * @param context - Additional context including the toolCallId that emitted the event\n   */\n  onCustomEvent?: (\n    eventType: string,\n    data: unknown,\n    context: { toolCallId?: string },\n  ) => void\n\n  /**\n   * Client-side tools with execution logic\n   * When provided, tools with execute functions will be called automatically\n   */\n  tools?: TTools\n\n  /**\n   * Devtools hook metadata for this client instance.\n   */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory, which keeps `@tanstack/ai-client/devtools` (the heavy\n   * bridge implementation) out of the main entry's bundle. Frameworks\n   * that need live devtools should pass the real factory from\n   * `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: ChatDevtoolsBridgeFactory\n\n  /**\n   * Stream processing options (optional)\n   * Configure chunking strategy\n   */\n  streamProcessor?: {\n    /**\n     * Strategy for when to emit text updates\n     * Defaults to ImmediateStrategy (every chunk)\n     */\n    chunkStrategy?: ChunkStrategy\n  }\n}\n\n/**\n * Options for `ChatClient`. Exactly one of `connection` or `fetcher` must be\n * provided — the type-level XOR is enforced via `ChatTransport`.\n */\nexport type ChatClientOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TContext = InferredClientContext<TTools>,\n> = DistributedOmit<ChatClientBaseOptions<TTools, TContext>, 'context'> &\n  ClientContextOptionFromTools<TTools, TContext> &\n  ChatTransport\n\nexport interface ChatRequestBody {\n  messages: Array<ModelMessage>\n  data?: Record<string, any>\n}\n\n/**\n * Create a typed array of client tools with proper type inference.\n * This eliminates the need for `as const` when defining tool arrays.\n *\n * @example\n * ```ts\n * const tools = clientTools(\n *   myTool1.client(() => result1),\n *   myTool2.client(() => result2),\n * )\n *\n * // tools is now properly typed as a tuple with literal tool names\n * // This enables type narrowing when checking part.name === 'toolName'\n * ```\n */\nexport function clientTools<const T extends Array<AnyClientTool>>(\n  ...tools: T\n): T {\n  return tools\n}\n\n/**\n * Helper to create typed chat client options\n * Use this to get proper type inference for messages\n *\n * @example\n * ```ts\n * const tools = clientTools(myTool1, myTool2)\n *\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools,\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * ```\n */\nexport function createChatClientOptions<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n>(\n  options: ChatClientOptions<TTools, TContext>,\n): ChatClientOptions<TTools, TContext> {\n  return options\n}\n\n/**\n * Extract the message type from chat options\n *\n * @example\n * ```ts\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools: [myTool1, myTool2],\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>\n * ```\n */\nexport type InferChatMessages<T> =\n  T extends ChatClientOptions<infer TTools, any>\n    ? Array<UIMessage<TTools>>\n    : never\n"],"names":[],"mappings":"AA8iBO,SAAS,eACX,OACA;AACH,SAAO;AACT;AAkBO,SAAS,wBAId,SACqC;AACrC,SAAO;AACT;"}
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  AnyClientTool,\n  AudioPart,\n  ChunkStrategy,\n  ContentPart,\n  DocumentPart,\n  ImagePart,\n  InferToolInput,\n  InferToolOutput,\n  ModelMessage,\n  StreamChunk,\n  StructuredOutputPart,\n  UIResourcePart,\n  VideoPart,\n} from '@tanstack/ai/client'\nimport type { ConnectionAdapter } from './connection-adapters'\nimport type { AIDevtoolsClientMetadata } from './devtools'\nimport type { ChatDevtoolsBridgeFactory } from './devtools-noop'\n\nexport type { StructuredOutputPart } from '@tanstack/ai/client'\n\n/**\n * `messages` is the full UIMessage history (not a delta). `data` is the\n * merged body — `ChatClientOptions.body` plus any per-call data passed to\n * `sendMessage(...)`. `threadId` / `runId` are the AG-UI correlation ids\n * the chat client uses to track this turn — forward them to your server\n * if it needs to correlate requests.\n */\nexport interface ChatFetcherInput {\n  messages: Array<UIMessage>\n  data?: Record<string, unknown>\n  threadId: string\n  runId: string\n}\n\nexport interface ChatFetcherOptions {\n  /** Fires when `stop()` is called or the request is superseded. */\n  signal: AbortSignal\n}\n\n/**\n * Direct function that performs a chat request. Mirrors\n * `GenerationFetcher`. Returns either a `Response` (SSE body parsed by the\n * chat client) or an `AsyncIterable<StreamChunk>` (yielded directly). May\n * return the value synchronously, as a `Promise`, or as an async generator\n * (`async function*`) — the chat client awaits whichever shape is returned.\n *\n * @example\n * ```ts\n * useChat({\n *   fetcher: ({ messages }, { signal }) =>\n *     chatFn({ data: { messages }, signal }),\n * })\n * ```\n */\nexport type ChatFetcher = (\n  input: ChatFetcherInput,\n  options: ChatFetcherOptions,\n) =>\n  | Response\n  | AsyncIterable<StreamChunk>\n  | Promise<Response | AsyncIterable<StreamChunk>>\n\n/**\n * Distributive `Omit` — applies `Omit<O, K>` per branch of a union so\n * discriminated unions survive omission. Plain `Omit` collapses unions\n * into a single object shape, which would erase the `ChatTransport` XOR\n * when framework hooks omit React-managed callbacks from\n * `ChatClientOptions`.\n */\nexport type DistributedOmit<\n  TObject,\n  TKeys extends keyof any,\n> = TObject extends unknown ? Omit<TObject, TKeys> : never\n\n/**\n * Discriminated union enforcing that exactly one of `connection` or\n * `fetcher` is provided. Mirrors `GenerationTransport`.\n */\nexport type ChatTransport =\n  | { connection: ConnectionAdapter; fetcher?: never }\n  | { fetcher: ChatFetcher; connection?: never }\n\n/**\n * Tool call states - track the lifecycle of a tool call\n */\nexport type ToolCallState =\n  | 'awaiting-input' // Received start but no arguments yet\n  | 'input-streaming' // Partial arguments received\n  | 'input-complete' // All arguments received\n  | 'approval-requested' // Waiting for user approval\n  | 'approval-responded' // User has approved/denied\n  | 'complete' // Result is complete\n  | 'error' // Tool execution failed (terminal)\n\n/**\n * Tool result states - track the lifecycle of a tool result\n */\nexport type ToolResultState =\n  | 'streaming' // Placeholder for future streamed output\n  | 'complete' // Result is complete\n  | 'error' // Error occurred\n\n/**\n * ChatClient state - track the lifecycle of a chat\n */\nexport type ChatClientState = 'ready' | 'submitted' | 'streaming' | 'error'\n\n/**\n * Connection lifecycle state for the subscription loop.\n */\nexport type ConnectionStatus =\n  | 'disconnected'\n  | 'connecting'\n  | 'connected'\n  | 'error'\n\n/**\n * Multimodal content input for sending messages with rich media.\n * Allows sending text, images, audio, video, and documents to the LLM.\n *\n * @example\n * ```ts\n * // Send an image with a question\n * client.sendMessage({\n *   content: [\n *     { type: 'text', content: 'What is in this image?' },\n *     { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }\n *   ],\n *   id: 'custom-message-id' // optional\n * })\n * ```\n */\nexport interface MultimodalContent {\n  /**\n   * The content of the message.\n   * Can be a simple string or an array of content parts for multimodal messages.\n   */\n  content: string | Array<ContentPart>\n  /**\n   * Optional custom ID for the message.\n   * If not provided, a unique ID will be generated.\n   */\n  id?: string\n}\n\n/**\n * Message parts - building blocks of UIMessage\n */\nexport interface TextPart {\n  type: 'text'\n  content: string\n}\n\n/**\n * Helper type that creates a tool-call part for a specific tool.\n * This is a conditional type to enable proper distribution over union types,\n * creating a discriminated union where `name` is the discriminant.\n */\ntype ToolCallPartForTool<T> = T extends AnyClientTool\n  ? {\n      type: 'tool-call'\n      id: string\n      name: T['name']\n      arguments: string // JSON string (may be incomplete)\n      /** Parsed tool input (typed from inputSchema) */\n      input?: InferToolInput<T>\n      state: ToolCallState\n      /** Approval metadata if tool requires user approval */\n      approval?: {\n        id: string // Unique approval ID\n        needsApproval: boolean // Always true if present\n        approved?: boolean // User's decision (undefined until responded)\n      }\n      /** Tool execution output (for client tools or after approval) */\n      output?: InferToolOutput<T>\n    }\n  : never\n\n/**\n * Fallback tool-call part type when tools are not typed\n */\ntype UntypedToolCallPart = {\n  type: 'tool-call'\n  id: string\n  name: string\n  arguments: string\n  input?: any\n  state: ToolCallState\n  approval?: {\n    id: string\n    needsApproval: boolean\n    approved?: boolean\n  }\n  output?: any\n}\n\n/**\n * Tool call part that creates a proper discriminated union.\n * When TTools is typed, checking `part.name === 'toolName'` will narrow\n * `part.output` to the correct type for that tool.\n *\n * The discriminant is `name`, so code like:\n * ```ts\n * if (part.name === 'recommendGuitar') {\n *   // part.output is now typed to the recommendGuitar tool's output\n * }\n * ```\n */\nexport type ToolCallPart<TTools extends ReadonlyArray<AnyClientTool> = any> =\n  // Check if we have a concrete tools array (not 'any' or 'never')\n  [TTools] extends [never]\n    ? UntypedToolCallPart\n    : unknown extends TTools\n      ? UntypedToolCallPart\n      : TTools extends ReadonlyArray<infer Tool>\n        ? Tool extends AnyClientTool\n          ? ToolCallPartForTool<Tool>\n          : UntypedToolCallPart\n        : UntypedToolCallPart\n\nexport interface ToolResultPart {\n  type: 'tool-result'\n  toolCallId: string\n  content: string | Array<ContentPart>\n  state: ToolResultState\n  error?: string // Error message if state is \"error\"\n}\n\nexport interface ThinkingPart {\n  type: 'thinking'\n  content: string\n}\n\nexport type MessagePart<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> =\n  | TextPart\n  | ImagePart\n  | AudioPart\n  | VideoPart\n  | DocumentPart\n  | ToolCallPart<TTools>\n  | ToolResultPart\n  | ThinkingPart\n  | StructuredOutputPart<TData>\n  | UIResourcePart\n\n/**\n * UIMessage - Domain-specific message format optimized for building chat UIs\n * Contains parts that can be text, tool calls, or tool results.\n *\n * `TTools` narrows the tool-call/result part types based on the registered\n * tools. `TData` is the schema-inferred type for any `structured-output` part\n * on the message — defaulted to `unknown` so untyped consumers (the core\n * stream processor, the wire converter) don't need to thread a schema generic\n * everywhere; the hook layer (`useChat({ outputSchema })`) substitutes it on\n * the public return so `m.parts.find(p => p.type === 'structured-output').data`\n * is typed without manual casts.\n */\nexport interface UIMessage<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TData = unknown,\n> {\n  id: string\n  role: 'system' | 'user' | 'assistant'\n  parts: Array<MessagePart<TTools, TData>>\n  createdAt?: Date\n}\n\nexport interface ChatClientPersistence<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n> {\n  getItem: (\n    id: string,\n  ) =>\n    | Array<UIMessage<TTools>>\n    | null\n    | undefined\n    | Promise<Array<UIMessage<TTools>> | null | undefined>\n  setItem: (\n    id: string,\n    messages: Array<UIMessage<TTools>>,\n  ) => void | Promise<void>\n  removeItem: (id: string) => void | Promise<void>\n}\n\ntype IsUnknown<T> = unknown extends T\n  ? [T] extends [unknown]\n    ? true\n    : false\n  : false\n\ntype KnownContext<T> = IsUnknown<T> extends true ? never : T\n\ntype MergeContext<TLeft, TRight> = [TLeft] extends [never]\n  ? TRight\n  : [TRight] extends [never]\n    ? TLeft\n    : TLeft & TRight\n\ntype UnionToIntersection<T> = [T] extends [never]\n  ? never\n  : (T extends unknown ? (value: T) => void : never) extends (\n        value: infer TIntersection,\n      ) => void\n    ? TIntersection\n    : never\n\ntype DefinedContext<T> = Exclude<T, undefined>\n\ntype ContextFromExecute<T> = T extends (...args: any) => any\n  ? NonNullable<Parameters<T>[1]> extends { context: infer TContext }\n    ? KnownContext<TContext>\n    : never\n  : never\n\ntype ContextFromClientTool<T> = T extends AnyClientTool\n  ? T extends { execute?: infer TExecute }\n    ? ContextFromExecute<TExecute>\n    : never\n  : never\n\ntype RequiredContextFromClientToolUnion<T> = T extends unknown\n  ? undefined extends ContextFromClientTool<T>\n    ? never\n    : ContextFromClientTool<T>\n  : never\n\ntype ContextFromClientToolUnion<T> = [\n  UnionToIntersection<DefinedContext<ContextFromClientTool<T>>>,\n] extends [never]\n  ? never\n  : [RequiredContextFromClientToolUnion<T>] extends [never]\n    ? UnionToIntersection<DefinedContext<ContextFromClientTool<T>>> | undefined\n    : UnionToIntersection<DefinedContext<ContextFromClientTool<T>>>\n\ntype ContextFromClientTools<TTools> =\n  IsUnknown<TTools> extends true\n    ? never\n    : TTools extends readonly [infer THead, ...infer TTail]\n      ? MergeContext<\n          ContextFromClientTool<THead>,\n          ContextFromClientTools<TTail>\n        >\n      : TTools extends ReadonlyArray<infer TItem>\n        ? ContextFromClientToolUnion<TItem>\n        : never\n\nexport type InferredClientContext<TTools> = [\n  ContextFromClientTools<TTools>,\n] extends [never]\n  ? unknown\n  : ContextFromClientTools<TTools>\n\nexport type ClientContextOptionFromTools<TTools, TContext> = [\n  ContextFromClientTools<TTools>,\n] extends [never]\n  ? { context?: TContext }\n  : undefined extends ContextFromClientTools<TTools>\n    ? { context?: TContext & ContextFromClientTools<TTools> }\n    : { context: TContext & ContextFromClientTools<TTools> }\n\n/**\n * Base options for `ChatClient`, excluding the transport (`connection` or\n * `fetcher`) which is supplied separately via `ChatTransport` so the XOR\n * is preserved when composing the final `ChatClientOptions` type.\n */\nexport interface ChatClientBaseOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TContext = unknown,\n> {\n  /**\n   * Initial messages to populate the chat\n   */\n  initialMessages?: Array<UIMessage<TTools>>\n\n  /**\n   * Optional persistence adapter for chat messages.\n   */\n  persistence?: ChatClientPersistence<TTools>\n\n  /**\n   * Unique identifier for this chat instance\n   * Used for managing multiple chats\n   */\n  id?: string\n\n  /**\n   * Thread ID to use for this chat session. Persists across sends within\n   * the session. If omitted, a unique thread ID is generated.\n   */\n  threadId?: string\n\n  /**\n   * Arbitrary client-controlled JSON forwarded to the server in the\n   * AG-UI `RunAgentInput.forwardedProps` field. Use this for per-session\n   * options like provider/model selection or feature flags that the\n   * server endpoint should read.\n   *\n   * Replaces the legacy `body` option. If both are provided,\n   * `forwardedProps` wins on key collision.\n   */\n  forwardedProps?: Record<string, any>\n\n  /**\n   * @deprecated Use `forwardedProps` instead. `body` continues to work\n   * unchanged — its values are merged into the AG-UI\n   * `RunAgentInput.forwardedProps` field on the wire and are also\n   * mirrored under the legacy `data` field for servers that have not\n   * migrated yet. Will be removed in a future major release.\n   */\n  body?: Record<string, any>\n\n  /**\n   * Client-local runtime context passed to client tool implementations.\n   *\n   * This value is not serialized to the server. Use `forwardedProps` for\n   * explicit client-to-server handoff of serializable values.\n   */\n  context?: TContext\n\n  /**\n   * Callback when a response is received\n   */\n  onResponse?: (response?: Response) => void | Promise<void>\n\n  /**\n   * Callback when a stream chunk is received\n   */\n  onChunk?: (chunk: StreamChunk) => void\n\n  /**\n   * Callback when the response is finished\n   */\n  onFinish?: (message: UIMessage<TTools>) => void\n\n  /**\n   * Callback when an error occurs\n   */\n  onError?: (error: Error) => void\n\n  /**\n   * Callback when messages change\n   */\n  onMessagesChange?: (messages: Array<UIMessage<TTools>>) => void\n\n  /**\n   * Callback when loading state changes\n   */\n  onLoadingChange?: (isLoading: boolean) => void\n\n  /**\n   * Callback when error state changes\n   */\n  onErrorChange?: (error: Error | undefined) => void\n\n  /**\n   * Callback when chat status changes\n   */\n  onStatusChange?: (status: ChatClientState) => void\n\n  /**\n   * Callback when subscription lifecycle changes.\n   * This is independent from request lifecycle (`isLoading`, `status`).\n   */\n  onSubscriptionChange?: (isSubscribed: boolean) => void\n\n  /**\n   * Callback when connection lifecycle changes.\n   */\n  onConnectionStatusChange?: (status: ConnectionStatus) => void\n\n  /**\n   * Callback when session generation activity changes.\n   * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).\n   * Unlike `onLoadingChange` (request-local), this reflects shared generation\n   * activity visible to all subscribers (e.g. across tabs/devices).\n   */\n  onSessionGeneratingChange?: (isGenerating: boolean) => void\n\n  /**\n   * Callback when a custom event is received from a server-side tool.\n   * Custom events are emitted by tools using `context.emitCustomEvent()` during execution.\n   *\n   * @param eventType - The name of the custom event\n   * @param data - The event payload data\n   * @param context - Additional context including the toolCallId that emitted the event\n   */\n  onCustomEvent?: (\n    eventType: string,\n    data: unknown,\n    context: { toolCallId?: string },\n  ) => void\n\n  /**\n   * Client-side tools with execution logic\n   * When provided, tools with execute functions will be called automatically\n   */\n  tools?: TTools\n\n  /**\n   * Devtools hook metadata for this client instance.\n   */\n  devtools?: Partial<AIDevtoolsClientMetadata>\n\n  /**\n   * Factory that constructs the devtools bridge. Default is a no-op\n   * factory, which keeps `@tanstack/ai-client/devtools` (the heavy\n   * bridge implementation) out of the main entry's bundle. Frameworks\n   * that need live devtools should pass the real factory from\n   * `@tanstack/ai-client/devtools`.\n   */\n  devtoolsBridgeFactory?: ChatDevtoolsBridgeFactory\n\n  /**\n   * Stream processing options (optional)\n   * Configure chunking strategy\n   */\n  streamProcessor?: {\n    /**\n     * Strategy for when to emit text updates\n     * Defaults to ImmediateStrategy (every chunk)\n     */\n    chunkStrategy?: ChunkStrategy\n  }\n}\n\n/**\n * Options for `ChatClient`. Exactly one of `connection` or `fetcher` must be\n * provided — the type-level XOR is enforced via `ChatTransport`.\n */\nexport type ChatClientOptions<\n  TTools extends ReadonlyArray<AnyClientTool> = any,\n  TContext = InferredClientContext<TTools>,\n> = DistributedOmit<ChatClientBaseOptions<TTools, TContext>, 'context'> &\n  ClientContextOptionFromTools<TTools, TContext> &\n  ChatTransport\n\nexport interface ChatRequestBody {\n  messages: Array<ModelMessage>\n  data?: Record<string, any>\n}\n\n/**\n * Create a typed array of client tools with proper type inference.\n * This eliminates the need for `as const` when defining tool arrays.\n *\n * @example\n * ```ts\n * const tools = clientTools(\n *   myTool1.client(() => result1),\n *   myTool2.client(() => result2),\n * )\n *\n * // tools is now properly typed as a tuple with literal tool names\n * // This enables type narrowing when checking part.name === 'toolName'\n * ```\n */\nexport function clientTools<const T extends Array<AnyClientTool>>(\n  ...tools: T\n): T {\n  return tools\n}\n\n/**\n * Helper to create typed chat client options\n * Use this to get proper type inference for messages\n *\n * @example\n * ```ts\n * const tools = clientTools(myTool1, myTool2)\n *\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools,\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * ```\n */\nexport function createChatClientOptions<\n  const TTools extends ReadonlyArray<AnyClientTool>,\n  TContext = InferredClientContext<TTools>,\n>(\n  options: ChatClientOptions<TTools, TContext>,\n): ChatClientOptions<TTools, TContext> {\n  return options\n}\n\n/**\n * Extract the message type from chat options\n *\n * @example\n * ```ts\n * const chatOptions = createChatClientOptions({\n *   connection: fetchServerSentEvents('/api/chat'),\n *   tools: [myTool1, myTool2],\n * })\n *\n * type MyMessages = InferChatMessages<typeof chatOptions>\n * // MyMessages is now Array<UIMessage<[typeof myTool1, typeof myTool2]>>\n * ```\n */\nexport type InferChatMessages<T> =\n  T extends ChatClientOptions<infer TTools, any>\n    ? Array<UIMessage<TTools>>\n    : never\n"],"names":[],"mappings":"AAgjBO,SAAS,eACX,OACA;AACH,SAAO;AACT;AAkBO,SAAS,wBAId,SACqC;AACrC,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-client",
-  "version": "0.18.6",
+  "version": "0.19.1",
   "description": "Framework-agnostic headless client for TanStack AI chat, realtime sessions, streaming transports, and media generations.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -49,8 +49,9 @@
     "src"
   ],
   "dependencies": {
-    "@tanstack/ai": "0.37.0",
-    "@tanstack/ai-event-client": "0.6.8"
+    "@tanstack/ai": "0.39.0",
+    "@tanstack/ai-event-client": "0.6.8",
+    "@tanstack/ai-utils": "0.3.1"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",

package/src/audio-recorder.ts

@@ -0,0 +1,322 @@
+import { arrayBufferToBase64 } from '@tanstack/ai-utils'
+import type { AudioPart } from '@tanstack/ai/client'
+
+/** Lifecycle state of an {@link AudioRecorder}. */
+export type AudioRecorderState = 'idle' | 'recording' | 'stopping'
+
+export interface AudioRecorderOptions {
+  /** Constraints forwarded to `getUserMedia({ audio })`. Defaults to `true`. */
+  audio?: MediaTrackConstraints | boolean
+  /**
+   * Preferred recorder mime type. Used only when
+   * `MediaRecorder.isTypeSupported` reports it; otherwise the browser default
+   * is used.
+   */
+  mimeType?: string
+  /** Fired on `getUserMedia` rejection (permission denied) or recorder error. */
+  onError?: (error: Error) => void
+}
+
+/**
+ * Resolves the value `stop()` produces from a recorder transform callback.
+ *
+ * - If the callback returns a value — sync or async — that value's awaited type
+ *   is used (a returned `null` is a real value and is preserved).
+ * - If the callback returns nothing (`void`/`undefined`), or is absent, falls
+ *   back to {@link AudioRecording}.
+ *
+ * @template TFn - The transform callback type (or undefined if not provided)
+ */
+export type InferAudioRecordingOutput<TFn> = TFn extends (
+  recording: AudioRecording,
+) => infer R
+  ? [Exclude<Awaited<R>, void | undefined>] extends [never]
+    ? AudioRecording
+    : Exclude<Awaited<R>, void | undefined>
+  : AudioRecording
+
+export interface AudioRecording {
+  /** The raw recorded media blob. */
+  blob: Blob
+  /** Base64 of the recorded bytes (no `data:` prefix). */
+  base64: string
+  /** The recorder's native mime type, e.g. `audio/webm;codecs=opus`. */
+  mimeType: string
+  /** Recording length in milliseconds. */
+  durationMs: number
+  /**
+   * Ready-to-use audio content part for `sendMessage`/generation prompts:
+   * `{ type: 'audio', source: { type: 'data', value: base64, mimeType } }`.
+   */
+  part: AudioPart
+}
+
+/**
+ * Framework-agnostic browser audio recorder. Wraps `getUserMedia` +
+ * `MediaRecorder`, returns the recorder's native output (no transcode), and
+ * builds a plug-and-play {@link AudioRecording.part}.
+ */
+export class AudioRecorder {
+  private readonly options: AudioRecorderOptions
+  private recorder: MediaRecorder | null = null
+  private stream: MediaStream | null = null
+  private chunks: Array<Blob> = []
+  private startedAt = 0
+  private _state: AudioRecorderState = 'idle'
+  // True while start() is awaiting getUserMedia (state is still 'idle' then).
+  private starting = false
+  // Set by cancel()/teardown during that window so start() releases the
+  // freshly acquired stream instead of beginning a leaked recording.
+  private pendingCancel = false
+  private readonly listeners = new Set<(state: AudioRecorderState) => void>()
+  private stopResolve: ((recording: AudioRecording) => void) | null = null
+  private stopReject: ((error: Error) => void) | null = null
+
+  constructor(options: AudioRecorderOptions = {}) {
+    this.options = options
+  }
+
+  /** Feature-detect the browser media APIs. SSR/Worker-safe. */
+  static isSupported(): boolean {
+    return (
+      typeof navigator !== 'undefined' &&
+      typeof navigator.mediaDevices !== 'undefined' &&
+      typeof navigator.mediaDevices.getUserMedia === 'function' &&
+      typeof MediaRecorder !== 'undefined'
+    )
+  }
+
+  get state(): AudioRecorderState {
+    return this._state
+  }
+
+  subscribe(cb: (state: AudioRecorderState) => void): () => void {
+    this.listeners.add(cb)
+    return () => {
+      this.listeners.delete(cb)
+    }
+  }
+
+  private setState(state: AudioRecorderState): void {
+    this._state = state
+    for (const cb of this.listeners) {
+      cb(state)
+    }
+  }
+
+  async start(): Promise<void> {
+    if (this._state !== 'idle' || this.starting) {
+      return
+    }
+    this.starting = true
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: this.options.audio ?? true,
+      })
+      // cancel()/teardown ran while we were awaiting the mic: release the
+      // freshly acquired stream and bail rather than starting a recording the
+      // caller can no longer stop (a leaked live microphone).
+      if (this.pendingCancel) {
+        stream.getTracks().forEach((t) => t.stop())
+        return
+      }
+      this.stream = stream
+      const wanted = this.options.mimeType
+      const useMimeType =
+        wanted &&
+        typeof MediaRecorder.isTypeSupported === 'function' &&
+        MediaRecorder.isTypeSupported(wanted)
+          ? wanted
+          : undefined
+      const recorder = useMimeType
+        ? new MediaRecorder(stream, { mimeType: useMimeType })
+        : new MediaRecorder(stream)
+      this.chunks = []
+      recorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          this.chunks.push(e.data)
+        }
+      }
+      recorder.onstop = () => {
+        void this.finalize()
+      }
+      recorder.onerror = (event) => {
+        const detail =
+          'error' in event && event.error instanceof Error
+            ? event.error
+            : new Error('Audio recording failed')
+        this.handleError(detail)
+      }
+      this.recorder = recorder
+      this.startedAt = Date.now()
+      recorder.start()
+      this.setState('recording')
+    } catch (err) {
+      this.releaseStream()
+      this.recorder = null
+      const error =
+        err instanceof Error ? err : new Error('Failed to start recording')
+      this.setState('idle')
+      this.notifyError(error)
+      throw error
+    } finally {
+      this.starting = false
+      // Reset here (not before the await) so a cancel() that arrives mid-start
+      // is observed above; clearing it afterward keeps the next start() clean.
+      this.pendingCancel = false
+    }
+  }
+
+  stop(): Promise<AudioRecording> {
+    if (this._state !== 'recording' || !this.recorder) {
+      return Promise.reject(
+        new Error('AudioRecorder.stop() called while not recording'),
+      )
+    }
+    this.setState('stopping')
+    const recorder = this.recorder
+    return new Promise<AudioRecording>((resolve, reject) => {
+      // Some browsers/codecs never fire onstop; this watchdog unwedges the
+      // recorder instead of leaking this promise forever.
+      const watchdog = setTimeout(() => {
+        if (this._state !== 'stopping') {
+          return
+        }
+        // Detach handlers so a late onstop/onerror from the stalled recorder
+        // can't reach back in and fire finalize()/onError a second time.
+        this.detachRecorder()
+        if (this.chunks.length > 0) {
+          // onstop never fired, but ondataavailable already delivered the
+          // audio — finalize from the buffered chunks rather than discarding a
+          // recording the user successfully captured.
+          void this.finalize()
+        } else {
+          this.handleError(
+            new Error('Recording stop timed out after 10s with no audio'),
+          )
+        }
+      }, 10_000)
+      this.stopResolve = (rec) => {
+        clearTimeout(watchdog)
+        resolve(rec)
+      }
+      this.stopReject = (err) => {
+        clearTimeout(watchdog)
+        reject(err)
+      }
+      recorder.stop()
+    })
+  }
+
+  cancel(): void {
+    if (this.starting) {
+      // A start() is awaiting getUserMedia; flag it so the resolved stream is
+      // released instead of beginning a recording with no handle to stop it.
+      this.pendingCancel = true
+      return
+    }
+    if (this._state === 'idle') {
+      return
+    }
+    const recorder = this.recorder
+    if (recorder) {
+      // Detach handlers so finalize()/onError never run for a discarded
+      // recording.
+      this.detachRecorder()
+      try {
+        recorder.stop()
+      } catch (err) {
+        // Stopping an already-inactive recorder throws InvalidStateError —
+        // that's expected here. Anything else is unexpected; surface it rather
+        // than swallowing it silently.
+        if (
+          !(err instanceof DOMException && err.name === 'InvalidStateError')
+        ) {
+          this.notifyError(
+            err instanceof Error ? err : new Error('Failed to stop recorder'),
+          )
+        }
+      }
+    }
+    this.releaseStream()
+    this.recorder = null
+    this.chunks = []
+    const reject = this.stopReject
+    this.stopResolve = null
+    this.stopReject = null
+    this.setState('idle')
+    reject?.(new Error('Recording cancelled'))
+  }
+
+  private async finalize(): Promise<void> {
+    const mimeType = this.recorder?.mimeType || 'audio/webm'
+    const durationMs = Date.now() - this.startedAt
+    try {
+      const blob = new Blob(this.chunks, { type: mimeType })
+      const base64 = arrayBufferToBase64(await blob.arrayBuffer())
+      const recording: AudioRecording = {
+        blob,
+        base64,
+        mimeType,
+        durationMs,
+        part: {
+          type: 'audio',
+          source: { type: 'data', value: base64, mimeType },
+        },
+      }
+      this.releaseStream()
+      this.recorder = null
+      this.chunks = []
+      const resolve = this.stopResolve
+      this.stopResolve = null
+      this.stopReject = null
+      this.setState('idle')
+      resolve?.(recording)
+    } catch (err) {
+      this.handleError(
+        err instanceof Error ? err : new Error('Failed to finalize recording'),
+      )
+    }
+  }
+
+  private handleError(error: Error): void {
+    this.releaseStream()
+    this.recorder = null
+    this.chunks = []
+    const reject = this.stopReject
+    this.stopResolve = null
+    this.stopReject = null
+    this.setState('idle')
+    // Settle the pending stop() promise before invoking the user callback so a
+    // throwing onError can't strand the awaiter (the two error channels are
+    // independent — see start()/stop() docs).
+    reject?.(error)
+    this.notifyError(error)
+  }
+
+  /** Invoke the user onError callback, isolating a throw so it can't disrupt
+   * internal state teardown or strand a pending promise. */
+  private notifyError(error: Error): void {
+    try {
+      this.options.onError?.(error)
+    } catch {
+      // A user onError that throws must not propagate into recorder internals.
+    }
+  }
+
+  private releaseStream(): void {
+    this.stream?.getTracks().forEach((t) => t.stop())
+    this.stream = null
+  }
+
+  /** Detach all event handlers so a stale recorder can't mutate our state. */
+  private detachRecorder(): void {
+    const recorder = this.recorder
+    if (!recorder) {
+      return
+    }
+    recorder.onstop = null
+    recorder.onerror = null
+    recorder.ondataavailable = null
+  }
+}

package/src/generation-types.ts

@@ -11,7 +11,29 @@ import type {
 // ===========================
 
 /**
- * Infers the output type from an `onResult` callback's return type.
+ * Maps an `onResult` transform's raw return type to the stored output type.
+ *
+ * - A concrete return (excluding null/void/undefined) becomes the output type.
+ * - A return of only null/void/undefined falls back to TResult (the transform
+ *   reacted to the result or chose to keep it, rather than replacing it).
+ *
+ * Hooks infer `TReturn` directly from the `onResult` return position — a
+ * covariant inference site that works even for an optional nested property —
+ * which both contextually types the callback parameter as `TResult` and
+ * narrows `result`. See issue #848.
+ *
+ * @template TResult - The raw result type from the generation
+ * @template TReturn - The transform's return type (defaults to `void` when no
+ *   transform is provided)
+ */
+export type InferGenerationOutputFromReturn<TResult, TReturn> = [
+  Exclude<TReturn, null | void | undefined>,
+] extends [never]
+  ? TResult
+  : Exclude<TReturn, null | void | undefined>
+
+/**
+ * Infers the output type from an `onResult` callback's type.
  *
  * - If the callback returns a concrete type (excluding null/void/undefined), uses that type.
  * - If the callback only returns null/void/undefined, or is not provided, falls back to TResult.
@@ -22,9 +44,7 @@ import type {
 export type InferGenerationOutput<TResult, TFn> = TFn extends (
   result: any,
 ) => infer R
-  ? [Exclude<R, null | void | undefined>] extends [never]
-    ? TResult
-    : Exclude<R, null | void | undefined>
+  ? InferGenerationOutputFromReturn<TResult, R>
   : TResult
 
 // ===========================

package/src/index.ts

@@ -1,4 +1,13 @@
+export { AudioRecorder } from './audio-recorder'
+export type {
+  AudioRecorderOptions,
+  AudioRecorderState,
+  AudioRecording,
+  InferAudioRecordingOutput,
+} from './audio-recorder'
 export { ChatClient } from './chat-client'
+export { createMcpAppBridge } from './mcp-app-bridge'
+export type { McpAppBridge, CreateMcpAppBridgeOptions } from './mcp-app-bridge'
 export { RealtimeClient } from './realtime-client'
 export { GenerationClient } from './generation-client'
 export { VideoGenerationClient } from './video-generation-client'
@@ -30,6 +39,7 @@ export type {
 // Generation client types
 export type {
   InferGenerationOutput,
+  InferGenerationOutputFromReturn,
   GenerationClientState,
   GenerationClientOptions,
   GenerationFetcher,

package/src/mcp-app-bridge.ts

@@ -0,0 +1,120 @@
+export interface CreateMcpAppBridgeOptions {
+  threadId: string
+  callEndpoint: string
+  chat: {
+    sendMessage: (
+      content: string,
+      body?: Record<string, unknown>,
+    ) => Promise<void>
+  }
+  fetchImpl?: typeof fetch
+  onLink?: (url: string) => void
+}
+
+export interface McpAppBridge {
+  callTool: (input: {
+    serverId?: string
+    toolName: string
+    args?: Record<string, unknown>
+    /**
+     * Reserved — forwarded to the call handler for correlation purposes but
+     * not consumed by the handler. Accepted on the wire; the handler does not
+     * read it (mirrors the `meta` convention on `UIResourcePart`).
+     */
+    messageId?: string
+  }) => Promise<unknown>
+  sendPrompt: (text: string) => Promise<void>
+  openLink: (url: string) => { isError: boolean }
+}
+
+interface ToolCallResponse {
+  ok: boolean
+  result?: unknown
+  error?: string
+}
+
+function isToolCallResponse(value: unknown): value is ToolCallResponse {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'ok' in value &&
+    typeof value.ok === 'boolean'
+  )
+}
+
+// Links arrive from an untrusted sandboxed widget. Only hand http(s)/mailto
+// URLs to the host's onLink; reject javascript:/data:/file:/etc. so a widget
+// can't smuggle a script-executing or local-resource URL through the bridge.
+const SAFE_LINK_SCHEMES = new Set(['http:', 'https:', 'mailto:'])
+function isSafeLink(url: string): boolean {
+  try {
+    return SAFE_LINK_SCHEMES.has(new URL(url).protocol)
+  } catch {
+    return false
+  }
+}
+
+export function createMcpAppBridge(
+  options: CreateMcpAppBridgeOptions,
+): McpAppBridge {
+  const { threadId, callEndpoint, chat, fetchImpl, onLink } = options
+  const doFetch = fetchImpl ?? fetch
+
+  return {
+    async callTool(input) {
+      const response = await doFetch(callEndpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          threadId,
+          serverId: input.serverId,
+          toolName: input.toolName,
+          args: input.args,
+          messageId: input.messageId,
+        }),
+      })
+
+      if (!response.ok) {
+        throw new Error(`MCP app tool call failed: HTTP ${response.status}`)
+      }
+
+      const raw: unknown = await response.json()
+      if (!isToolCallResponse(raw)) {
+        throw new Error('MCP app tool call failed')
+      }
+
+      if (!raw.ok) {
+        throw new Error(raw.error ?? 'MCP app tool call failed')
+      }
+
+      return raw.result
+    },
+
+    async sendPrompt(text) {
+      await chat.sendMessage(text)
+    },
+
+    openLink(url) {
+      if (!isSafeLink(url)) {
+        console.warn(
+          '[mcp-app-bridge] openLink rejected: unsupported URL scheme',
+          url,
+        )
+        return { isError: true }
+      }
+      if (onLink) {
+        try {
+          onLink(url)
+          return { isError: false }
+        } catch (err) {
+          console.warn('[mcp-app-bridge] openLink: onLink handler threw', err)
+          return { isError: true }
+        }
+      }
+      console.warn(
+        '[mcp-app-bridge] openLink ignored: no onLink handler configured',
+      )
+      return { isError: true }
+    },
+  }
+}

package/src/types.ts

@@ -10,6 +10,7 @@ import type {
   ModelMessage,
   StreamChunk,
   StructuredOutputPart,
+  UIResourcePart,
   VideoPart,
 } from '@tanstack/ai/client'
 import type { ConnectionAdapter } from './connection-adapters'
@@ -244,6 +245,7 @@ export type MessagePart<
   | ToolResultPart
   | ThinkingPart
   | StructuredOutputPart<TData>
+  | UIResourcePart
 
 /**
  * UIMessage - Domain-specific message format optimized for building chat UIs