feat: TanStack AI adapter for client-side tool calling (@simplepdf/embed/tanstack-ai)

Author: bendersej

.changeset/tanstack-ai-adapter.md

@@ -0,0 +1,10 @@
+---
+"@simplepdf/embed": minor
+"@simplepdf/react-embed-pdf": minor
+---
+
+Add a TanStack AI adapter (the `/tanstack-ai` subpath) for client-side tool calling, alongside the existing Vercel AI SDK (`/ai-sdk`) adapter. Both wrap the same generated tool registry + bridge router, so the editor is drivable from either SDK with no duplicated logic.
+
+- `@simplepdf/embed/tanstack-ai`: `simplePDFTanstackToolDefinitions()` (server, for `chat({ tools })`) and `createSimplePDFTanstackTools({ embed })` (browser `.client()` tools for `clientTools(...)` then `useChat({ tools })`).
+- `@simplepdf/react-embed-pdf/tanstack-ai`: `useEmbedTanstackTools(embedRef)`, the editor-bound client tools, plus the re-exported server definitions.
+- `@tanstack/ai` is a new optional peer, pulled only by the `/tanstack-ai` subpath; the package roots stay free of it (and of `zod`).

embed/README.md

@@ -49,13 +49,26 @@ const execute = createSimplePDFExecutor({ embed })
 
 `@simplepdf/embed/tools` exposes the same registry SDK-agnostically (`routeToolCall`, `isSimplePDFToolName`). In React, `@simplepdf/react-embed-pdf/ai-sdk`'s `useEmbedTools(embedRef)` is the same registry pre-bound to the live editor.
 
+For TanStack AI, the same registry is exposed via `@simplepdf/embed/tanstack-ai`:
+
+```ts
+// server: execute-less definitions so the model is aware of the tools
+import { simplePDFTanstackToolDefinitions } from '@simplepdf/embed/tanstack-ai'
+chat({ adapter, messages, tools: simplePDFTanstackToolDefinitions() })
+
+// browser: the same definitions bound to the live editor via .client()
+import { clientTools } from '@tanstack/ai-react'
+import { createSimplePDFTanstackTools } from '@simplepdf/embed/tanstack-ai'
+useChat({ connection, tools: clientTools(...createSimplePDFTanstackTools({ embed })) })
+```
+
 ## Install
 
 ```bash
 npm install @simplepdf/embed
 ```
 
-Zero runtime dependencies at the root. `zod` is an optional peer, needed only by the `/schemas`, `/tools`, and `/ai-sdk` subpaths. `/ai-sdk` produces values for the Vercel AI SDK but never imports `ai`; bring your own.
+Zero runtime dependencies at the root. `zod` is an optional peer, needed by the `/schemas`, `/tools`, `/ai-sdk`, and `/tanstack-ai` subpaths. `/ai-sdk` produces values for the Vercel AI SDK without importing `ai` (bring your own); `/tanstack-ai` uses `@tanstack/ai`'s `toolDefinition` (also an optional peer, pulled only by that subpath).
 
 ## Subpaths
 
@@ -66,6 +79,7 @@ Zero runtime dependencies at the root. `zod` is an optional peer, needed only by
 | `@simplepdf/embed/schemas` | zod schema for every operation input | `zod` |
 | `@simplepdf/embed/tools` | SDK-agnostic agentic tool registry + `routeToolCall` + `isSimplePDFToolName` | `zod` |
 | `@simplepdf/embed/ai-sdk` | `simplePDFToolDefinitions()` (server) + `createSimplePDFExecutor({ embed })` (browser) for the Vercel AI SDK | `zod` |
+| `@simplepdf/embed/tanstack-ai` | `simplePDFTanstackToolDefinitions()` (server) + `createSimplePDFTanstackTools({ embed })` (browser) for TanStack AI | `zod`, `@tanstack/ai` |
 
 ## Where the editor goes
 

embed/package.json

@@ -47,6 +47,11 @@
       "types": "./dist/ai-sdk.d.ts",
       "import": "./dist/ai-sdk.js",
       "require": "./dist/ai-sdk.cjs"
+    },
+    "./tanstack-ai": {
+      "types": "./dist/tanstack-ai.d.ts",
+      "import": "./dist/tanstack-ai.js",
+      "require": "./dist/tanstack-ai.cjs"
     }
   },
   "scripts": {
@@ -62,14 +67,19 @@
     "check:size": "npm run build && node scripts/check-bundle-size.mjs"
   },
   "peerDependencies": {
+    "@tanstack/ai": "^0.38.0",
     "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
+    "@tanstack/ai": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
   },
   "devDependencies": {
+    "@tanstack/ai": "^0.38.0",
     "jsdom": "^26.1.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",

embed/scripts/check-bundle-size.mjs

@@ -19,6 +19,7 @@ const BUDGETS = {
   'schemas.js': 3 * 1024,
   'tools.js': 5 * 1024,
   'ai-sdk.js': 5.5 * 1024,
+  'tanstack-ai.js': 5.5 * 1024,
 }
 
 const localImports = (file) => {

embed/src/tanstack-ai.ts

@@ -0,0 +1,35 @@
+// TanStack AI adapter. The same generated registry + bridge router as the Vercel
+// `/ai-sdk` adapter, in TanStack's isomorphic tool shape: server-registerable
+// definitions for `chat({ tools })`, and browser `.client()` tools bound to the live
+// editor for `clientTools(...)` -> `useChat({ tools })`. The zod input schemas drop
+// in directly (TanStack accepts any Standard Schema); `@tanstack/ai` is the only
+// added peer, pulled solely by this subpath.
+
+import { type AnyClientTool, toolDefinition } from '@tanstack/ai'
+import { TOOL_DEFINITIONS, type SimplePDFToolName } from './generated/tools'
+import { isSimplePDFToolName, routeToolCall } from './tools'
+import type { Embed } from './types'
+
+export type { SimplePDFToolName } from './generated/tools'
+
+const TOOL_NAMES: readonly SimplePDFToolName[] = Object.keys(TOOL_DEFINITIONS).filter(isSimplePDFToolName)
+
+// One shared definition per tool (name + description + zod input schema): the unit
+// `chat({ tools })` registers and `.client()` / `.server()` instantiate from.
+const define = (name: SimplePDFToolName) =>
+  toolDefinition({
+    name,
+    description: TOOL_DEFINITIONS[name].description,
+    inputSchema: TOOL_DEFINITIONS[name].inputSchema,
+  })
+
+// Server: execute-less definitions for `chat({ tools })`, so the model is aware of
+// the tools. A fresh array each call so the host can pick/omit (e.g. gate submit XOR
+// download) without mutating shared state.
+export const simplePDFTanstackToolDefinitions = (): ReturnType<typeof define>[] => TOOL_NAMES.map(define)
+
+// Browser: the same definitions bound to the live editor via `.client()`, for
+// `clientTools(...)` -> `useChat({ tools })`. Each call validates input against the
+// tool schema and dispatches to the matching editor action, resolving to a BridgeResult.
+export const createSimplePDFTanstackTools = ({ embed }: { embed: Embed }): AnyClientTool[] =>
+  TOOL_NAMES.map((name) => define(name).client((input) => routeToolCall(embed.actions, name, input)))

embed/test/helpers.ts

@@ -0,0 +1,35 @@
+import { vi } from 'vitest'
+import type { BridgeResult, Embed, IframeActions } from '../src/types'
+
+const okResult: BridgeResult<unknown> = { success: true, data: null }
+
+// A fully-stubbed actions group: every editor operation is a vi.fn resolving to a
+// success Result. Shared by the tools + adapter tests.
+export const makeActionsStub = (): IframeActions => {
+  const method = (): Promise<BridgeResult<unknown>> => Promise.resolve(okResult)
+  return {
+    createField: vi.fn(method),
+    deleteFields: vi.fn(method),
+    deletePages: vi.fn(method),
+    detectFields: vi.fn(method),
+    download: vi.fn(method),
+    focusField: vi.fn(method),
+    getDocumentContent: vi.fn(method),
+    getFields: vi.fn(method),
+    goTo: vi.fn(method),
+    loadDocument: vi.fn(method),
+    movePage: vi.fn(method),
+    rotatePage: vi.fn(method),
+    selectTool: vi.fn(method),
+    setFieldValue: vi.fn(method),
+    submit: vi.fn(method),
+  }
+}
+
+// A minimal Embed handle wrapping stubbed actions (events + lifecycle are no-ops);
+// enough for adapters that only dispatch through embed.actions.
+export const makeEmbedStub = (): Embed => ({
+  actions: makeActionsStub(),
+  events: { on: () => () => {} },
+  lifecycle: { dispose: () => {} },
+})

embed/test/tanstack-ai.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest'
+import { createSimplePDFTanstackTools, simplePDFTanstackToolDefinitions } from '../src/tanstack-ai'
+import type { BridgeResult } from '../src/types'
+import { makeEmbedStub } from './helpers'
+
+describe('simplePDFTanstackToolDefinitions', () => {
+  it('returns the 14 agentic operations as execute-less definitions (loadDocument excluded)', () => {
+    const definitions = simplePDFTanstackToolDefinitions()
+    expect(definitions).toHaveLength(14)
+    expect(definitions.map((definition) => definition.name)).not.toContain('loadDocument')
+    for (const definition of definitions) {
+      expect(typeof definition.description).toBe('string')
+      expect(definition.inputSchema).toBeDefined()
+    }
+  })
+})
+
+describe('createSimplePDFTanstackTools', () => {
+  it('binds each tool to the editor: a client call validates input + dispatches to the matching action', async () => {
+    const embed = makeEmbedStub()
+    const goTo = createSimplePDFTanstackTools({ embed }).find((tool) => tool.name === 'goTo')
+    if (goTo === undefined || goTo.execute === undefined) {
+      throw new Error('expected a goTo client tool with an execute')
+    }
+    await goTo.execute({ page: 2 })
+    expect(embed.actions.goTo).toHaveBeenCalledWith({ page: 2 })
+  })
+
+  it('returns bad_request:invalid_input on schema-invalid input without dispatching', async () => {
+    const embed = makeEmbedStub()
+    const goTo = createSimplePDFTanstackTools({ embed }).find((tool) => tool.name === 'goTo')
+    if (goTo === undefined || goTo.execute === undefined) {
+      throw new Error('expected a goTo client tool with an execute')
+    }
+    const result: BridgeResult<unknown> = await goTo.execute({ page: 'not-a-number' })
+    expect(result.success).toBe(false)
+    if (!result.success) {
+      expect(result.error.code).toBe('bad_request:invalid_input')
+    }
+    expect(embed.actions.goTo).not.toHaveBeenCalled()
+  })
+})

embed/test/tools.test.ts

@@ -1,29 +1,6 @@
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { isSimplePDFToolName, routeToolCall, SIMPLEPDF_TOOLS } from '../src/tools'
-import type { BridgeResult, IframeActions } from '../src/types'
-
-const okResult: BridgeResult<unknown> = { success: true, data: null }
-
-const makeActionsStub = (): IframeActions => {
-  const method = (): Promise<BridgeResult<unknown>> => Promise.resolve(okResult)
-  return {
-    createField: vi.fn(method),
-    deleteFields: vi.fn(method),
-    deletePages: vi.fn(method),
-    detectFields: vi.fn(method),
-    download: vi.fn(method),
-    focusField: vi.fn(method),
-    getDocumentContent: vi.fn(method),
-    getFields: vi.fn(method),
-    goTo: vi.fn(method),
-    loadDocument: vi.fn(method),
-    movePage: vi.fn(method),
-    rotatePage: vi.fn(method),
-    selectTool: vi.fn(method),
-    setFieldValue: vi.fn(method),
-    submit: vi.fn(method),
-  }
-}
+import { makeActionsStub } from './helpers'
 
 describe(isSimplePDFToolName.name, () => {
   it('accepts agentic tool names', () => {

embed/tsup.config.ts

@@ -13,12 +13,13 @@ export default defineConfig({
     schemas: 'src/schemas.ts',
     tools: 'src/tools.ts',
     'ai-sdk': 'src/ai-sdk.ts',
+    'tanstack-ai': 'src/tanstack-ai.ts',
   },
   format: ['esm', 'cjs'],
   dts: true,
   treeshake: true,
   splitting: true,
   sourcemap: true,
   clean: true,
-  external: ['zod'],
+  external: ['zod', '@tanstack/ai'],
 })