@octanejs/tanstack-ai 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @octanejs/tanstack-ai
+
+[TanStack AI](https://tanstack.com/ai) bindings for the
+[Octane](https://github.com/octanejs/octane) UI framework.
+
+This package ports `@tanstack/ai-react@0.17.0` onto Octane while reusing
+`@tanstack/ai` and `@tanstack/ai-client` unchanged. The runtime export surface
+matches the React adapter, so migration starts by changing the package import:
+
+```ts
+// before
+import { useChat } from '@tanstack/ai-react'
+
+// after
+import { useChat } from '@octanejs/tanstack-ai'
+```
+
+The renderer-bearing hook modules are authored as `.tsrx` and compiled by
+Octane. Matching `.tsrx.d.ts` companions are checked declaration emits of
+those implementations, preserving the complete generic surface for
+TypeScript consumers.
+
+## Install
+
+```bash
+pnpm add @octanejs/tanstack-ai @tanstack/ai @tanstack/ai-client octane
+```
+
+## Usage
+
+```tsx
+import { useState } from 'octane'
+import { useChat } from '@octanejs/tanstack-ai'
+
+export function Chat() @{
+  const [input, setInput] = useState('')
+  const chat = useChat({
+    fetcher: myFetcher,
+  })
+
+  <div>
+    @for (const message of chat.messages; key message.id) {
+      <p>
+        {(message.role +
+          ': ' +
+          message.parts
+            .map((part) => (part.type === 'text' ? part.content : ''))
+            .join('')) as string}
+      </p>
+    }
+    <input
+      value={input}
+      onInput={(event) => setInput(event.currentTarget.value)}
+    />
+    <button
+      onClick={() => {
+        void chat.sendMessage(input)
+        setInput('')
+      }}
+    >
+      Send
+    </button>
+  </div>
+}
+```
+
+`useChat` has no input state of its own — hold the text box value in a local
+`useState` and pass it to `sendMessage`. Note the `onInput` handler: Octane
+drives text controls per keystroke through the native `input` event, not a
+synthetic `onChange`.
+
+## API
+
+The adapter includes `useChat`, `useRealtimeChat`, `useMcpAppBridge`,
+`useGeneration`, `useGenerateImage`, `useGenerateAudio`, `useGenerateSpeech`,
+`useGenerateVideo`, `useTranscription`, `useSummarize`, and
+`useAudioRecorder`. It also re-exports all 30 `@tanstack/ai-client`
+convenience helpers and types (`fetchServerSentEvents`, `fetchHttpStream`,
+`xhrServerSentEvents`, `xhrHttpStream`, `stream`, `rpcStream`,
+`createChatClientOptions`, `createMcpAppBridge`, and their associated types)
+unchanged, mirroring the upstream `@tanstack/ai-react` index.
+
+Server rendering through `octane/server` is supported. `useChat` renders its
+initial message snapshot without browser-only setup.
+
+## Divergences from `@tanstack/ai-react`
+
+- The `./mcp-apps` subpath and its `MCPAppResource` component are not ported:
+  they render `AppRenderer` from the React-only `@mcp-ui/client`, which has no
+  Octane equivalent. The framework-agnostic `useMcpAppBridge` hook is ported
+  and available on the main entry.
+- Octane uses native events: text/file/recorder inputs drive updates via
+  `onInput`; there is no synthetic `onChange` layer.
+- Octane has no StrictMode double-invoke and always provides `useId`, so no
+  random-id fallback is needed.
+- Realtime reconnects and token refreshes use the latest `getToken` and adapter
+  supplied to the hook; upstream captures the first render's callbacks.
+- The declared realtime `onStatusChange` callback is invoked alongside the
+  hook's state update; upstream 0.17.0 currently drops the external callback.
+- One upstream `useChat` test case ("auto-resume on mount / when the browser
+  comes back online") is omitted: it targets
+  `ChatClient.prototype.maybeAutoResume`, an API absent from the pinned (and
+  latest published) `@tanstack/ai-client@0.21.0` and never invoked by
+  `useChat`. It is untestable in this binding until that dependency ships the
+  method.
+
+## Verification
+
+The port runs TanStack AI's React adapter tests against Octane across all
+eleven hooks, with no skipped, todo, or expected-failure cases (except the
+untestable auto-resume case above). A differential test compiles a shared
+chat fixture for Octane and React and compares streamed output after each
+step; output is byte-equal against real `@tanstack/ai-react@0.17.0`. An SSR
+fixture and the upstream compile-time type tests are also included.
+
+Current scope and verification status are tracked in the generated
+[bindings status table](../../docs/bindings-status.md), sourced from this
+package's [`status.json`](./status.json).
+
+## License
+
+MIT — contains source derived from
+[TanStack AI](https://github.com/TanStack/ai) (MIT), adapted for Octane.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@octanejs/tanstack-ai",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "TanStack AI bindings for Octane — reuses @tanstack/ai and @tanstack/ai-client and ports the React adapter's hooks (chat, realtime, generation, transcription, media).",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/tanstack-ai"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/ai": "0.41.0",
+    "@tanstack/ai-client": "0.21.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.7"
+  },
+  "devDependencies": {
+    "@tanstack/ai-react": "0.17.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "vitest": "^4.1.9",
+    "@octanejs/testing-library": "0.1.4",
+    "octane": "0.1.7"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.ts

@@ -0,0 +1,62 @@
+export { useChat } from './use-chat.tsrx';
+export { useRealtimeChat } from './use-realtime-chat.tsrx';
+export { useMcpAppBridge } from './use-mcp-app-bridge.tsrx';
+export type { UseMcpAppBridgeOptions } from './use-mcp-app-bridge.tsrx';
+export type {
+	DeepPartial,
+	UseChatOptions,
+	UseChatReturn,
+	UIMessage,
+	ChatRequestBody,
+} from './types';
+export type { UseRealtimeChatOptions, UseRealtimeChatReturn } from './realtime-types';
+
+export { useGeneration } from './use-generation.tsrx';
+export type { UseGenerationOptions, UseGenerationReturn } from './use-generation.tsrx';
+export { useGenerateImage } from './use-generate-image.tsrx';
+export type { UseGenerateImageOptions, UseGenerateImageReturn } from './use-generate-image.tsrx';
+export { useGenerateAudio } from './use-generate-audio.tsrx';
+export type { UseGenerateAudioOptions, UseGenerateAudioReturn } from './use-generate-audio.tsrx';
+export { useGenerateSpeech } from './use-generate-speech.tsrx';
+export type { UseGenerateSpeechOptions, UseGenerateSpeechReturn } from './use-generate-speech.tsrx';
+export { useTranscription } from './use-transcription.tsrx';
+export type { UseTranscriptionOptions, UseTranscriptionReturn } from './use-transcription.tsrx';
+export { useSummarize } from './use-summarize.tsrx';
+export type { UseSummarizeOptions, UseSummarizeReturn } from './use-summarize.tsrx';
+export { useGenerateVideo } from './use-generate-video.tsrx';
+export type { UseGenerateVideoOptions, UseGenerateVideoReturn } from './use-generate-video.tsrx';
+export { useAudioRecorder } from './use-audio-recorder.tsrx';
+export type { UseAudioRecorderOptions, UseAudioRecorderReturn } from './use-audio-recorder.tsrx';
+
+// Re-export from ai-client for convenience (mirror upstream index.ts)
+export {
+	fetchServerSentEvents,
+	fetchHttpStream,
+	xhrServerSentEvents,
+	xhrHttpStream,
+	stream,
+	rpcStream,
+	createChatClientOptions,
+	createMcpAppBridge,
+	type McpAppBridge,
+	type CreateMcpAppBridgeOptions,
+	type ChatFetcher,
+	type ChatFetcherInput,
+	type ChatFetcherOptions,
+	type ConnectionAdapter,
+	type ConnectConnectionAdapter,
+	type SubscribeConnectionAdapter,
+	type RunAgentInputContext,
+	type FetchConnectionOptions,
+	type XhrConnectionOptions,
+	type InferChatMessages,
+	type GenerationClientState,
+	type ImageGenerateInput,
+	type AudioGenerateInput,
+	type SpeechGenerateInput,
+	type TranscriptionGenerateInput,
+	type SummarizeGenerateInput,
+	type VideoGenerateInput,
+	type VideoGenerateResult,
+	type VideoStatusInfo,
+} from '@tanstack/ai-client';

package/src/realtime-types.ts

@@ -0,0 +1,146 @@
+import type {
+	AnyClientTool,
+	RealtimeMessage,
+	RealtimeMode,
+	RealtimeSessionConfig,
+	RealtimeStatus,
+	RealtimeToken,
+	UsageInfo,
+} from '@tanstack/ai';
+import type { RealtimeAdapter } from '@tanstack/ai-client';
+
+/**
+ * Options for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatOptions {
+	/**
+	 * Function to fetch a realtime token from the server.
+	 * Called on connect and when token needs refresh.
+	 */
+	getToken: () => Promise<RealtimeToken>;
+
+	/**
+	 * The realtime adapter to use (e.g., openaiRealtime())
+	 */
+	adapter: RealtimeAdapter;
+
+	/**
+	 * Client-side tools with execution logic
+	 */
+	tools?: ReadonlyArray<AnyClientTool>;
+
+	/**
+	 * Auto-play assistant audio (default: true)
+	 */
+	autoPlayback?: boolean;
+
+	/**
+	 * Request microphone access on connect (default: true)
+	 */
+	autoCapture?: boolean;
+
+	/**
+	 * System instructions for the assistant
+	 */
+	instructions?: string;
+
+	/**
+	 * Voice to use for audio output
+	 */
+	voice?: string;
+
+	/**
+	 * Voice activity detection mode (default: 'server')
+	 */
+	vadMode?: 'server' | 'semantic' | 'manual';
+
+	/**
+	 * Output modalities for responses (e.g., ['audio', 'text'])
+	 */
+	outputModalities?: Array<'audio' | 'text'>;
+
+	/**
+	 * Temperature for generation (provider-specific range)
+	 */
+	temperature?: number;
+
+	/**
+	 * Maximum number of tokens in a response
+	 */
+	maxOutputTokens?: number | 'inf';
+
+	/**
+	 * Eagerness level for semantic VAD ('low', 'medium', 'high')
+	 */
+	semanticEagerness?: 'low' | 'medium' | 'high';
+
+	// Callbacks
+	onConnect?: () => void;
+	onDisconnect?: () => void;
+	onError?: (error: Error) => void;
+	onMessage?: (message: RealtimeMessage) => void;
+	onModeChange?: (mode: RealtimeMode) => void;
+	onInterrupted?: () => void;
+	onUsage?: (usage: UsageInfo) => void;
+	onGoAway?: (timeLeft?: string) => void;
+	onStatusChange?: (status: RealtimeStatus) => void;
+}
+
+/**
+ * Return type for the useRealtimeChat hook.
+ */
+export interface UseRealtimeChatReturn {
+	// Connection state
+	/** Current connection status */
+	status: RealtimeStatus;
+	/** Current error, if any */
+	error: Error | null;
+	/** Connect to the realtime session */
+	connect: () => Promise<void>;
+	/** Disconnect from the realtime session */
+	disconnect: () => Promise<void>;
+
+	// Conversation state
+	/** Current mode (idle, listening, thinking, speaking) */
+	mode: RealtimeMode;
+	/** Conversation messages */
+	messages: Array<RealtimeMessage>;
+	/** User transcript while speaking (before finalized) */
+	pendingUserTranscript: string | null;
+	/** Assistant transcript while speaking (before finalized) */
+	pendingAssistantTranscript: string | null;
+
+	// Voice control
+	/** Start listening for voice input (manual VAD mode) */
+	startListening: () => void;
+	/** Stop listening for voice input (manual VAD mode) */
+	stopListening: () => void;
+	/** Interrupt the current assistant response */
+	interrupt: () => void;
+
+	// Text input
+	/** Send a text message instead of voice */
+	sendText: (text: string) => void;
+
+	// Image input
+	/** Send an image to the conversation */
+	sendImage: (imageData: string, mimeType: string) => void;
+
+	// Audio visualization (0-1 normalized)
+	/** Current input (microphone) volume level */
+	inputLevel: number;
+	/** Current output (speaker) volume level */
+	outputLevel: number;
+	/** Get frequency data for input audio visualization */
+	getInputFrequencyData: () => Uint8Array;
+	/** Get frequency data for output audio visualization */
+	getOutputFrequencyData: () => Uint8Array;
+	/** Get time domain data for input waveform */
+	getInputTimeDomainData: () => Uint8Array;
+	/** Get time domain data for output waveform */
+	getOutputTimeDomainData: () => Uint8Array;
+
+	// Session control
+	/** Update the active session and persist the configuration for reconnects. */
+	updateSession: (config: RealtimeSessionConfig) => void;
+}

package/src/types.ts

@@ -0,0 +1,213 @@
+import type {
+	AnyClientTool,
+	InferSchemaType,
+	ModelMessage,
+	SchemaInput,
+} from '@tanstack/ai/client';
+import type {
+	AIDevtoolsDisplayOptions,
+	ChatClientOptions,
+	ChatClientState,
+	ChatRequestBody,
+	ClientContextOptionFromTools,
+	ConnectionStatus,
+	DistributedOmit,
+	InferredClientContext,
+	MultimodalContent,
+	UIMessage,
+} from '@tanstack/ai-client';
+
+// Re-export types from ai-client
+export type { ChatRequestBody, MultimodalContent, UIMessage };
+
+/**
+ * Recursive partial — every property and every nested array element is optional.
+ * Used to type the in-flight `partial` value the hook exposes while a structured
+ * output stream is still arriving (the JSON has shape but is incomplete).
+ */
+export type DeepPartial<T> =
+	T extends ReadonlyArray<infer U>
+		? Array<DeepPartial<U>>
+		: T extends object
+			? { [K in keyof T]?: DeepPartial<T[K]> }
+			: T;
+
+/**
+ * Options for the useChat hook.
+ *
+ * Pass either `connection` or `fetcher` — the XOR is enforced at the type
+ * level via `ChatTransport`.
+ *
+ * This extends ChatClientOptions but omits the state change callbacks that are
+ * managed internally by hook state:
+ * - `onMessagesChange` - Managed by hook state (exposed as `messages`)
+ * - `onLoadingChange` - Managed by hook state (exposed as `isLoading`)
+ * - `onErrorChange` - Managed by hook state (exposed as `error`)
+ * - `onStatusChange` - Managed by hook state (exposed as `status`)
+ *
+ * All other callbacks (onResponse, onChunk, onFinish, onError) are
+ * passed through to the underlying ChatClient and can be used for side effects.
+ *
+ * When `outputSchema` is supplied, the hook returns a typed `partial` (live
+ * progressive object, updated from `TEXT_MESSAGE_CONTENT` deltas via
+ * `parsePartialJSON`) and `final` (validated terminal payload from the
+ * `structured-output.complete` event). The schema is used purely for type
+ * inference on the client — server-side validation still runs against the
+ * schema you pass to `chat({ outputSchema })` on the server route.
+ *
+ * Changing `connection` or `fetcher` updates the active ChatClient in place,
+ * preserving its state. Changing `id` creates a fresh client.
+ */
+export type UseChatOptions<
+	TTools extends ReadonlyArray<AnyClientTool> = any,
+	TSchema extends SchemaInput | undefined = undefined,
+	TContext = InferredClientContext<TTools>,
+> = DistributedOmit<
+	ChatClientOptions<TTools, TContext>,
+	| 'onMessagesChange'
+	| 'onLoadingChange'
+	| 'onErrorChange'
+	| 'onStatusChange'
+	| 'onSubscriptionChange'
+	| 'onConnectionStatusChange'
+	| 'onSessionGeneratingChange'
+	| 'context'
+	| 'devtools'
+> & {
+	/** Display options for TanStack AI Devtools. */
+	devtools?: AIDevtoolsDisplayOptions;
+	/**
+	 * Opt into mount-time live subscription behavior.
+	 * When enabled, the hook subscribes on mount and unsubscribes on unmount.
+	 */
+	live?: boolean;
+	/**
+	 * Standard-schema-compatible schema (Zod, Valibot, ArkType, or a plain JSON
+	 * Schema). Used to infer the shape of `partial` and `final` in the return.
+	 * The schema is **not** sent to the server — server-side validation runs
+	 * against the schema passed to `chat({ outputSchema })` on the server route.
+	 */
+	outputSchema?: TSchema;
+} & ClientContextOptionFromTools<TTools, TContext>;
+
+/**
+ * Discriminated return shape: when `outputSchema` is supplied, the hook adds
+ * typed `partial` / `final` fields; when it is omitted (default), the return
+ * is unchanged.
+ */
+export type UseChatReturn<
+	TTools extends ReadonlyArray<AnyClientTool> = any,
+	TSchema extends SchemaInput | undefined = undefined,
+> = BaseUseChatReturn<TTools, TSchema extends SchemaInput ? InferSchemaType<TSchema> : unknown> &
+	(TSchema extends SchemaInput
+		? {
+				/**
+				 * Live, progressively-parsed structured output. Updated from
+				 * `TEXT_MESSAGE_CONTENT` deltas via `parsePartialJSON` while the stream
+				 * is still arriving, and snapped to the validated payload when
+				 * `structured-output.complete` fires. Resets on every new run
+				 * (`sendMessage` / `reload`).
+				 */
+				partial: DeepPartial<InferSchemaType<TSchema>>;
+				/**
+				 * Final, schema-validated structured output. `null` until the terminal
+				 * `structured-output.complete` event arrives. Resets on every new run.
+				 */
+				final: InferSchemaType<TSchema> | null;
+			}
+		: Record<never, never>);
+
+interface BaseUseChatReturn<TTools extends ReadonlyArray<AnyClientTool> = any, TData = unknown> {
+	/**
+	 * Current messages in the conversation. When `outputSchema` is supplied,
+	 * `messages[i].parts.find(p => p.type === 'structured-output')` is typed
+	 * with the schema's inferred shape — `data: T`, `partial: DeepPartial<T>`.
+	 */
+	messages: Array<UIMessage<TTools, TData>>;
+
+	/**
+	 * Send a message and get a response.
+	 * Can be a simple string or multimodal content with images, audio, etc.
+	 */
+	sendMessage: (content: string | MultimodalContent) => Promise<void>;
+
+	/**
+	 * Append a message to the conversation
+	 */
+	append: (message: ModelMessage | UIMessage<TTools, TData>) => Promise<void>;
+
+	/**
+	 * Add the result of a client-side tool execution
+	 */
+	addToolResult: (result: {
+		toolCallId: string;
+		tool: string;
+		output: any;
+		state?: 'output-available' | 'output-error';
+		errorText?: string;
+	}) => Promise<void>;
+
+	/**
+	 * Respond to a tool approval request
+	 */
+	addToolApprovalResponse: (response: {
+		id: string; // approval.id, not toolCallId
+		approved: boolean;
+	}) => Promise<void>;
+
+	/**
+	 * Reload the last assistant message
+	 */
+	reload: () => Promise<void>;
+
+	/**
+	 * Stop the current response generation
+	 */
+	stop: () => void;
+
+	/**
+	 * Whether a response is currently being generated
+	 */
+	isLoading: boolean;
+
+	/**
+	 * Current error, if any
+	 */
+	error: Error | undefined;
+
+	/**
+	 * Current status of the chat client
+	 */
+	status: ChatClientState;
+
+	/**
+	 * Whether the subscription loop is currently active
+	 */
+	isSubscribed: boolean;
+
+	/**
+	 * Current connection lifecycle status
+	 */
+	connectionStatus: ConnectionStatus;
+
+	/**
+	 * Whether the shared session is actively generating.
+	 * Derived from stream run events (RUN_STARTED / RUN_FINISHED / RUN_ERROR).
+	 * Unlike `isLoading` (request-local), this reflects shared generation
+	 * activity visible to all subscribers (e.g. across tabs/devices).
+	 */
+	sessionGenerating: boolean;
+
+	/**
+	 * Set messages manually
+	 */
+	setMessages: (messages: Array<UIMessage<TTools, TData>>) => void;
+
+	/**
+	 * Clear all messages
+	 */
+	clear: () => void;
+}
+
+// Note: createChatClientOptions and InferChatMessages are now in @tanstack/ai-client
+// and re-exported from there for convenience