@tanstack/ai-remix 0.0.0

package/src/create-generation.ts

@@ -0,0 +1,333 @@
+import { GenerationClient } from '@tanstack/ai-client'
+import { createGenerationDevtoolsBridge } from '@tanstack/ai-client/devtools'
+import type { Handle } from 'remix/ui'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  AIDevtoolsDisplayOptions,
+  ConnectConnectionAdapter,
+  GenerationClientOptions,
+  GenerationClientState,
+  GenerationFetcher,
+  GenerationPersistenceOptions,
+  GenerationRestoredResult,
+  InferGenerationOutputFromReturn,
+} from '@tanstack/ai-client'
+import type { ByokClient } from '@tanstack/ai-client/byok'
+import type { ProviderId } from '@tanstack/ai/byok'
+
+type RemixHandle = Pick<Handle, 'id' | 'update' | 'signal'>
+
+/**
+ * Options for the createGeneration helper.
+ *
+ * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
+ * Handle is the first argument of the helper. It is not part of this type.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+export interface CreateGenerationOptions<TInput, TResult, TOutput = TResult> {
+  /** Connect-based adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectConnectionAdapter
+  /** Direct async function for one-shot generation (no streaming protocol needed) */
+  fetcher?: GenerationFetcher<TInput, TResult>
+  /** Additional body parameters to send with connect-based adapter requests */
+  body?: Record<string, any>
+  /** Optional BYOK keyring. Keys go in `x-byok-*` headers, never the body. */
+  byok?: ByokClient
+  /** Optional provider id. If it returns a slug, only that key is sent. If no slug resolves (`byokProvider`, then `body.provider`), generate throws. */
+  byokProvider?: () => ProviderId | undefined
+  /** Display options for TanStack AI Devtools. */
+  devtools?: AIDevtoolsDisplayOptions
+  /**
+   * How this generation persists across reloads.
+   * - Omit / `false`: ephemeral, in-memory only.
+   * - `true`: server-driven — on mount the client hydrates the last generation
+   *   for its `threadId` from the server (needs a connection with a
+   *   `hydrateGeneration` handler) and repaints it; it never auto-starts a run.
+   */
+  persistence?: boolean
+  /**
+   * The **scope** this generation belongs to: a stable, app-chosen name for the
+   * slot successive runs fill — not a link to a chat conversation.
+   *
+   * The helper starts empty and produces many runs over its life; each gets its
+   * own `runId`, but all belong to one scope. Persistence keys on this, so
+   * derive it from your own domain and keep it identical across reloads (e.g.
+   * `` `video-${videoId}-start-frame` ``). It is also sent as the AG-UI thread
+   * id on the wire, which the protocol requires.
+   *
+   * **Required whenever `persistence` is set** — an app that cannot name the
+   * scope has nothing to restore to. Optional for ephemeral generations. If
+   * omitted, the helper uses `handle.id`.
+   */
+  threadId?: string
+  /**
+   * Server-driven hydration handler for `persistence: true` when the
+   * connection doesn't carry one (e.g. alongside `fetcher`, or a `stream()` /
+   * `rpcStream()` adapter built without handlers) — typically a one-line
+   * server-function call. The connection's own handler takes precedence.
+   */
+  hydrateGeneration?: ConnectConnectionAdapter['hydrateGeneration']
+  /**
+   * Re-attach handler that replays a run still generating to completion on
+   * mount, when the connection doesn't carry one. Without it, a restored
+   * `running` snapshot surfaces as an (interrupted) error. The connection's
+   * own handler takes precedence.
+   */
+  joinRun?: ConnectConnectionAdapter['joinRun']
+  /**
+   * Callback when a result is received. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: TResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (connect-based adapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+  /**
+   * @internal Rebuild a typed result from a restored snapshot, injected by each
+   * specialized helper (image / speech / audio / transcription / summarize).
+   * Forwarded to the client so a server-hydrate restore repaints `result`.
+   */
+  reconstructResult?: (restored: GenerationRestoredResult) => TResult | null
+}
+
+/**
+ * Return type for the createGeneration helper.
+ *
+ * Fields are getters over local lets. Remix re-renders read the latest values
+ * after `handle.update()`.
+ *
+ * @template TOutput - The output type (after optional transform)
+ * @template TInput - The input type accepted by `generate` (defaults to any object)
+ */
+export interface CreateGenerationReturn<
+  TOutput,
+  TInput extends Record<string, any> = Record<string, any>,
+> {
+  /** The generation result, or null if not yet generated */
+  readonly result: TOutput | null
+  /** Whether a generation is currently in progress */
+  readonly isLoading: boolean
+  /** Current error, if any */
+  readonly error: Error | undefined
+  /** Current state of the generation client */
+  readonly status: GenerationClientState
+  /** Trigger a generation request */
+  generate: (input: TInput) => Promise<void>
+  /** Abort the current generation */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+  /**
+   * The id of the generation job currently running, or `null` when nothing is in
+   * flight. Each call to `generate` is one job with its own id. Pass it to your
+   * own endpoint to cancel or poll the provider job — `stop()` only aborts the
+   * local stream, it does not stop work already running on the provider.
+   */
+  readonly runId: string | null
+}
+
+/**
+ * Creates a generation helper for Remix setup.
+ *
+ * This is the base helper used by `createGenerateImage`, `createGenerateSpeech`,
+ * `createTranscription`, and `createSummarize`. You can also use it for custom
+ * generation types.
+ *
+ * Call this in a Remix component setup function. Pass the component Handle as
+ * the first argument. Pass either `connection` or `fetcher`.
+ *
+ * @example
+ * ```tsx
+ * import { createGeneration } from '@tanstack/ai-remix'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ * import type { Handle } from 'remix/ui'
+ *
+ * function CustomGenerator(handle: Handle) {
+ *   const gen = createGeneration(handle, {
+ *     connection: fetchServerSentEvents('/api/generate/custom'),
+ *   })
+ *
+ *   return () => (
+ *     <div>
+ *       <button onClick={() => gen.generate({ prompt: 'Hello' })}>
+ *         Generate
+ *       </button>
+ *       {gen.isLoading ? <p>Generating...</p> : null}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+// `TTransformed` infers from the `onResult` return position (a covariant
+// inference site that works even for an optional nested property), which types
+// the callback parameter as `TResult` and narrows `result`. Inferring the
+// whole callback as a defaulted type parameter instead collapses to the
+// default, leaving the parameter `any` — a hard error under `strict`. See
+// issue #848.
+export function createGeneration<
+  TInput extends Record<string, any>,
+  TResult,
+  TTransformed = void,
+>(
+  handle: RemixHandle,
+  options: Omit<
+    CreateGenerationOptions<TInput, TResult>,
+    'onResult' | 'persistence' | 'threadId'
+  > & {
+    onResult?: (result: TResult) => TTransformed
+  } & GenerationPersistenceOptions,
+) {
+  type TOutput = InferGenerationOutputFromReturn<TResult, TTransformed>
+
+  let result: TOutput | null = null
+  let isLoading = false
+  let error: Error | undefined = undefined
+  let status: GenerationClientState = 'idle'
+  let runId: string | null = null
+  let disposed = false
+
+  const notify = () => {
+    if (disposed) return
+    void handle.update()
+  }
+
+  const threadId = options.threadId ?? handle.id
+
+  // Conditional spread for `body` (strict-optional in target;
+  // local source is `Record<string, any> | undefined`). Callbacks
+  // wrap optional ones in non-returning bodies so `?.()`'s
+  // implicit `undefined` doesn't pollute the function return type.
+  const clientOptions: Omit<
+    GenerationClientOptions<TInput, TResult, TOutput>,
+    'persistence' | 'threadId'
+  > = {
+    ...(options.body !== undefined && { body: options.body }),
+    ...(options.hydrateGeneration !== undefined && {
+      hydrateGeneration: options.hydrateGeneration,
+    }),
+    ...(options.joinRun !== undefined && { joinRun: options.joinRun }),
+    ...(options.byok !== undefined && { byok: options.byok }),
+    byokProvider: () => options.byokProvider?.(),
+    ...(options.reconstructResult
+      ? { reconstructResult: options.reconstructResult }
+      : {}),
+    devtoolsBridgeFactory: createGenerationDevtoolsBridge,
+    devtools: {
+      hookName: 'createGeneration',
+      ...options.devtools,
+      framework: 'remix',
+    },
+    // The transform's raw return type (`TTransformed`) and the stored output
+    // (`TOutput`, with null/void/undefined stripped) are identical at runtime;
+    // the cast bridges the relationship that the conditional type hides.
+    onResult: ((r: TResult) => options.onResult?.(r)) as (
+      result: TResult,
+    ) => TOutput | null | void,
+    onError: (e: Error) => {
+      if (!disposed) options.onError?.(e)
+    },
+    onProgress: (p: number, m?: string) => {
+      if (!disposed) options.onProgress?.(p, m)
+    },
+    onChunk: (c: StreamChunk) => {
+      if (!disposed) options.onChunk?.(c)
+    },
+    onResultChange: (r) => {
+      if (disposed) return
+      result = r
+      notify()
+    },
+    onLoadingChange: (l) => {
+      if (disposed) return
+      isLoading = l
+      notify()
+    },
+    onErrorChange: (e) => {
+      if (disposed) return
+      error = e
+      notify()
+    },
+    onStatusChange: (s) => {
+      if (disposed) return
+      status = s
+      notify()
+    },
+    onResumeStateChange: (rs) => {
+      if (disposed) return
+      runId = rs?.runId ?? null
+      notify()
+    },
+  }
+
+  const persistenceProps =
+    typeof options.threadId === 'string' && options.persistence
+      ? {
+          persistence: options.persistence,
+          threadId: options.threadId,
+        }
+      : {
+          threadId,
+        }
+
+  let client: GenerationClient<TInput, TResult, TOutput>
+  if (options.connection) {
+    client = new GenerationClient<TInput, TResult, TOutput>({
+      ...clientOptions,
+      ...persistenceProps,
+      connection: options.connection,
+    })
+  } else if (options.fetcher) {
+    client = new GenerationClient<TInput, TResult, TOutput>({
+      ...clientOptions,
+      ...persistenceProps,
+      fetcher: options.fetcher,
+    })
+  } else {
+    throw new Error(
+      'createGeneration requires either a connection or fetcher option',
+    )
+  }
+
+  const dispose = () => {
+    if (disposed) return
+    disposed = true
+    client.dispose()
+  }
+
+  if (handle.signal.aborted) {
+    dispose()
+  } else {
+    client.mountDevtools()
+    handle.signal.addEventListener('abort', dispose, { once: true })
+  }
+
+  return {
+    get result() {
+      return result
+    },
+    get isLoading() {
+      return isLoading
+    },
+    get error() {
+      return error
+    },
+    get status() {
+      return status
+    },
+    generate: (input: TInput) => client.generate(input),
+    stop: () => client.stop(),
+    reset: () => client.reset(),
+    get runId() {
+      return runId
+    },
+  }
+}

package/src/create-mcp-app-bridge.ts

@@ -0,0 +1,36 @@
+import { createMcpAppBridge as createClientMcpAppBridge } from '@tanstack/ai-client'
+import type { CreateMcpAppBridgeOptions } from '@tanstack/ai-client'
+import type { Handle } from 'remix/ui'
+
+export type { CreateMcpAppBridgeOptions }
+
+/**
+ * Remix setup wrapper around the client `createMcpAppBridge`.
+ *
+ * Call once in component setup with the Remix `Handle`. Setup does not re-run,
+ * so the bridge is created once from `options`. The client bridge has no
+ * dispose, so `handle.signal` is unused.
+ *
+ * @param handle Remix component handle from setup.
+ * @param options Same options as the client factory (`threadId`, `callEndpoint`,
+ *   `chat.sendMessage`, optional `fetchImpl` / `onLink`).
+ *
+ * @example
+ * ```tsx
+ * function Widget(handle: Handle) {
+ *   const bridge = createMcpAppBridge(handle, {
+ *     threadId: 't1',
+ *     callEndpoint: '/api/mcp-apps-call',
+ *     chat: { sendMessage },
+ *     onLink: (url) => window.open(url, '_blank', 'noopener,noreferrer'),
+ *   })
+ *   return () => <MCPAppResource bridge={bridge} />
+ * }
+ * ```
+ */
+export function createMcpAppBridge(
+  handle: Handle,
+  options: CreateMcpAppBridgeOptions,
+) {
+  return createClientMcpAppBridge(options)
+}

package/src/create-realtime-chat.ts

@@ -0,0 +1,242 @@
+import { RealtimeClient } from '@tanstack/ai-client'
+import type {
+  RealtimeMessage,
+  RealtimeMode,
+  RealtimeSessionConfig,
+  RealtimeStatus,
+} from '@tanstack/ai'
+import type { Handle } from 'remix/ui'
+import type { CreateRealtimeChatOptions } from './realtime-types.ts'
+
+const emptyFrequencyData = new Uint8Array(128)
+const emptyTimeDomainData = new Uint8Array(128).fill(128)
+
+/**
+ * Remix helper for realtime voice conversations.
+ *
+ * Call from component setup with Handle. State fields are getters so the
+ * render function reads the current value after `handle.update()`.
+ *
+ * @param handle - Remix Handle from setup. Used to re-render and to clean up
+ *   when the component disconnects.
+ * @param options - Adapter, token loader, and optional session/callback config.
+ *
+ * @example
+ * ```typescript
+ * import { createRealtimeChat } from '@tanstack/ai-remix'
+ * import { openaiRealtime } from '@tanstack/ai-openai'
+ * import type { Handle } from 'remix/ui'
+ *
+ * function VoiceChat(handle: Handle) {
+ *   const chat = createRealtimeChat(handle, {
+ *     getToken: () => fetch('/api/realtime-token').then((r) => r.json()),
+ *     adapter: openaiRealtime(),
+ *   })
+ *
+ *   return () => (
+ *     <div>
+ *       <p>Status: {chat.status}</p>
+ *       <button on={{ click: chat.status === 'idle' ? chat.connect : chat.disconnect }}>
+ *         {chat.status === 'idle' ? 'Start' : 'Stop'}
+ *       </button>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function createRealtimeChat(
+  handle: Handle,
+  options: CreateRealtimeChatOptions,
+) {
+  let status: RealtimeStatus = 'idle'
+  let mode: RealtimeMode = 'idle'
+  let messages: Array<RealtimeMessage> = []
+  let pendingUserTranscript: string | null = null
+  let pendingAssistantTranscript: string | null = null
+  let error: Error | null = null
+  let animationFrame: number | null = null
+
+  function notify() {
+    if (!handle.signal.aborted) {
+      void handle.update()
+    }
+  }
+
+  function stopLevelLoop() {
+    if (animationFrame === null) return
+    cancelAnimationFrame(animationFrame)
+    animationFrame = null
+  }
+
+  function startLevelLoop() {
+    if (animationFrame !== null) return
+    function tick() {
+      animationFrame = requestAnimationFrame(tick)
+      notify()
+    }
+    animationFrame = requestAnimationFrame(tick)
+  }
+
+  // Each optional source field is spread conditionally because the
+  // `RealtimeClientOptions` target declares strict optionals
+  // (`field?: T`) and `exactOptionalPropertyTypes` rejects passing
+  // `undefined` for absent values.
+  const client = new RealtimeClient({
+    getToken: () => options.getToken(),
+    adapter: {
+      get provider() {
+        return options.adapter.provider
+      },
+      connect(token, tools) {
+        return options.adapter.connect(token, tools)
+      },
+    },
+    ...(options.tools !== undefined && { tools: options.tools }),
+    ...(options.instructions !== undefined && {
+      instructions: options.instructions,
+    }),
+    ...(options.voice !== undefined && { voice: options.voice }),
+    ...(options.autoPlayback !== undefined && {
+      autoPlayback: options.autoPlayback,
+    }),
+    ...(options.autoCapture !== undefined && {
+      autoCapture: options.autoCapture,
+    }),
+    ...(options.vadMode !== undefined && { vadMode: options.vadMode }),
+    ...(options.outputModalities !== undefined && {
+      outputModalities: options.outputModalities,
+    }),
+    ...(options.temperature !== undefined && {
+      temperature: options.temperature,
+    }),
+    ...(options.maxOutputTokens !== undefined && {
+      maxOutputTokens: options.maxOutputTokens,
+    }),
+    ...(options.semanticEagerness !== undefined && {
+      semanticEagerness: options.semanticEagerness,
+    }),
+    onStatusChange: (newStatus) => {
+      status = newStatus
+      if (newStatus === 'connected') {
+        startLevelLoop()
+      } else {
+        stopLevelLoop()
+      }
+      notify()
+      options.onStatusChange?.(newStatus)
+    },
+    onModeChange: (newMode) => {
+      mode = newMode
+      notify()
+      options.onModeChange?.(newMode)
+    },
+    onMessage: (message) => {
+      messages = [...messages, message]
+      notify()
+      options.onMessage?.(message)
+    },
+    onUsage: (usage) => {
+      options.onUsage?.(usage)
+    },
+    onGoAway: (timeLeft) => {
+      options.onGoAway?.(timeLeft)
+    },
+    onError: (err) => {
+      error = err
+      notify()
+      options.onError?.(err)
+    },
+    onConnect: () => {
+      error = null
+      notify()
+      options.onConnect?.()
+    },
+    onDisconnect: () => {
+      options.onDisconnect?.()
+    },
+    onInterrupted: () => {
+      pendingAssistantTranscript = null
+      notify()
+      options.onInterrupted?.()
+    },
+  })
+
+  client.onStateChange((state) => {
+    pendingUserTranscript = state.pendingUserTranscript
+    pendingAssistantTranscript = state.pendingAssistantTranscript
+    notify()
+  })
+
+  handle.signal.addEventListener('abort', () => {
+    stopLevelLoop()
+    client.destroy()
+  })
+
+  return {
+    get status() {
+      return status
+    },
+    get error() {
+      return error
+    },
+    connect: async () => {
+      error = null
+      messages = []
+      pendingUserTranscript = null
+      pendingAssistantTranscript = null
+      notify()
+      await client.connect()
+    },
+    disconnect: () => client.disconnect(),
+
+    get mode() {
+      return mode
+    },
+    get messages() {
+      return messages
+    },
+    get pendingUserTranscript() {
+      return pendingUserTranscript
+    },
+    get pendingAssistantTranscript() {
+      return pendingAssistantTranscript
+    },
+
+    startListening: () => {
+      client.startListening()
+    },
+    stopListening: () => {
+      client.stopListening()
+    },
+    interrupt: () => {
+      client.interrupt()
+    },
+
+    sendText: (text: string) => {
+      client.sendText(text)
+    },
+
+    sendImage: (imageData: string, mimeType: string) => {
+      client.sendImage(imageData, mimeType)
+    },
+
+    get inputLevel() {
+      return client.audio?.inputLevel ?? 0
+    },
+    get outputLevel() {
+      return client.audio?.outputLevel ?? 0
+    },
+    getInputFrequencyData: () =>
+      client.audio?.getInputFrequencyData() ?? emptyFrequencyData,
+    getOutputFrequencyData: () =>
+      client.audio?.getOutputFrequencyData() ?? emptyFrequencyData,
+    getInputTimeDomainData: () =>
+      client.audio?.getInputTimeDomainData() ?? emptyTimeDomainData,
+    getOutputTimeDomainData: () =>
+      client.audio?.getOutputTimeDomainData() ?? emptyTimeDomainData,
+
+    updateSession: (config: RealtimeSessionConfig) => {
+      client.updateSession(config)
+    },
+  }
+}

package/src/create-summarize.ts

@@ -0,0 +1,96 @@
+import { createGeneration } from './create-generation.ts'
+import { reconstructSummarizeResult } from '@tanstack/ai-client'
+import type { Handle } from 'remix/ui'
+import type { SummarizationResult } from '@tanstack/ai'
+import type {
+  GenerationPersistenceOptions,
+  SummarizeGenerateInput,
+} from '@tanstack/ai-client'
+import type {
+  CreateGenerationOptions,
+  CreateGenerationReturn,
+} from './create-generation.ts'
+
+/**
+ * Options for the createSummarize helper.
+ *
+ * Handle is the first argument of the helper. It is not part of this type.
+ *
+ * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
+ */
+export type CreateSummarizeOptions<TOutput = SummarizationResult> = Omit<
+  CreateGenerationOptions<SummarizeGenerateInput, SummarizationResult, TOutput>,
+  'onResult' | 'reconstructResult'
+> & {
+  onResult?: (result: SummarizationResult) => TOutput | null | void
+}
+
+/**
+ * Return type for the createSummarize helper.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export type CreateSummarizeReturn<TOutput = SummarizationResult> =
+  CreateGenerationReturn<TOutput, SummarizeGenerateInput>
+
+/**
+ * Creates a text summarization helper for Remix setup.
+ *
+ * Call this in a Remix component setup function. Pass the component Handle as
+ * the first argument.
+ *
+ * @example
+ * ```tsx
+ * import { createSummarize } from '@tanstack/ai-remix'
+ * import { fetchServerSentEvents } from '@tanstack/ai-client'
+ * import type { Handle } from 'remix/ui'
+ *
+ * function Summarizer(handle: Handle) {
+ *   const summarizer = createSummarize(handle, {
+ *     connection: fetchServerSentEvents('/api/summarize'),
+ *   })
+ *
+ *   return () => (
+ *     <div>
+ *       <button
+ *         onClick={() =>
+ *           summarizer.generate({
+ *             text: 'Long article text...',
+ *             style: 'bullet-points',
+ *             maxLength: 200,
+ *           })
+ *         }
+ *       >
+ *         Summarize
+ *       </button>
+ *       {summarizer.isLoading ? <p>Summarizing...</p> : null}
+ *       {summarizer.result ? <p>{summarizer.result.summary}</p> : null}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function createSummarize<TTransformed = void>(
+  handle: Pick<Handle, 'id' | 'update' | 'signal'>,
+  options: Omit<
+    CreateSummarizeOptions,
+    'onResult' | 'persistence' | 'threadId'
+  > & {
+    onResult?: (result: SummarizationResult) => TTransformed
+  } & GenerationPersistenceOptions,
+) {
+  const devtools = {
+    ...options.devtools,
+    hookName: 'createSummarize',
+    outputKind: 'text' as const,
+  }
+  return createGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TTransformed
+  >(handle, {
+    ...options,
+    devtools,
+    reconstructResult: reconstructSummarizeResult,
+  })
+}