refactor(tanstack-ai): unify names with the Vercel convention (createSimplePDFTools / simplePDFToolDefinitions / useEmbedTools) + keep server defs React-free

Author: bendersej

.changeset/tanstack-ai-adapter.md

@@ -5,6 +5,6 @@
 
 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.
+- `@simplepdf/embed/tanstack-ai`: `simplePDFToolDefinitions()` (server, for `chat({ tools })`) and `createSimplePDFTools({ embed })` (browser `.client()` tools for `clientTools(...)` then `useChat({ tools })`).
+- `@simplepdf/react-embed-pdf/tanstack-ai`: `useEmbedTools(embedRef)`, the editor-bound client tools. Server definitions stay in the React-free core `@simplepdf/embed/tanstack-ai`, so a server route never pulls React in.
 - `@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

@@ -53,13 +53,13 @@ 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() })
+import { simplePDFToolDefinitions } from '@simplepdf/embed/tanstack-ai'
+chat({ adapter, messages, tools: simplePDFToolDefinitions() })
 
 // 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 })) })
+import { createSimplePDFTools } from '@simplepdf/embed/tanstack-ai'
+useChat({ connection, tools: clientTools(...createSimplePDFTools({ embed })) })
 ```
 
 ## Install
@@ -79,7 +79,7 @@ Zero runtime dependencies at the root. `zod` is an optional peer, needed by the
 | `@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` |
+| `@simplepdf/embed/tanstack-ai` | `simplePDFToolDefinitions()` (server) + `createSimplePDFTools({ embed })` (browser) for TanStack AI | `zod`, `@tanstack/ai` |
 
 ## Where the editor goes
 

embed/src/tanstack-ai.ts

@@ -26,10 +26,10 @@ const define = (name: SimplePDFToolName) =>
 // 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)
+export const simplePDFToolDefinitions = (): 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[] =>
+export const createSimplePDFTools = ({ embed }: { embed: Embed }): AnyClientTool[] =>
   TOOL_NAMES.map((name) => define(name).client((input) => routeToolCall(embed.actions, name, input)))

embed/test/tanstack-ai.test.ts

@@ -1,11 +1,11 @@
 import { describe, expect, it } from 'vitest'
-import { createSimplePDFTanstackTools, simplePDFTanstackToolDefinitions } from '../src/tanstack-ai'
+import { createSimplePDFTools, simplePDFToolDefinitions } from '../src/tanstack-ai'
 import type { BridgeResult } from '../src/types'
 import { makeEmbedStub } from './helpers'
 
-describe('simplePDFTanstackToolDefinitions', () => {
+describe('simplePDFToolDefinitions', () => {
   it('returns the 14 agentic operations as execute-less definitions (loadDocument excluded)', () => {
-    const definitions = simplePDFTanstackToolDefinitions()
+    const definitions = simplePDFToolDefinitions()
     expect(definitions).toHaveLength(14)
     expect(definitions.map((definition) => definition.name)).not.toContain('loadDocument')
     for (const definition of definitions) {
@@ -15,16 +15,16 @@ describe('simplePDFTanstackToolDefinitions', () => {
   })
 })
 
-describe('createSimplePDFTanstackTools', () => {
+describe('createSimplePDFTools', () => {
   it('produces a client tool for each of the 14 agentic operations', () => {
-    const tools = createSimplePDFTanstackTools({ embed: makeEmbedStub() })
+    const tools = createSimplePDFTools({ embed: makeEmbedStub() })
     expect(tools).toHaveLength(14)
     expect(tools.every((tool) => typeof tool.execute === 'function')).toBe(true)
   })
 
   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')
+    const goTo = createSimplePDFTools({ embed }).find((tool) => tool.name === 'goTo')
     if (goTo === undefined || goTo.execute === undefined) {
       throw new Error('expected a goTo client tool with an execute')
     }
@@ -34,7 +34,7 @@ describe('createSimplePDFTanstackTools', () => {
 
   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')
+    const goTo = createSimplePDFTools({ embed }).find((tool) => tool.name === 'goTo')
     if (goTo === undefined || goTo.execute === undefined) {
       throw new Error('expected a goTo client tool with an execute')
     }

react/README.md

@@ -223,26 +223,26 @@ const CopilotEditor = () => {
 };
 ```
 
-For server-side tool definitions (execute-less, for `streamText`), import `simplePDFToolDefinitions` from `@simplepdf/react-embed-pdf/ai-sdk`. `embedRef.current` is the flat editor-actions handle, every camelCase operation, with the deprecated `selectTool` / `submit` overloads; subscribe to editor events via the `onEmbedEvent` prop. (The framework-free `@simplepdf/embed` core exposes the grouped `embed.actions` / `embed.events` / `embed.lifecycle` handle for non-React use.)
+For server-side tool definitions (execute-less, for `streamText`), import `simplePDFToolDefinitions` from the React-free core `@simplepdf/embed/ai-sdk` (importing it from this React subpath would pull React into your server). `embedRef.current` is the flat editor-actions handle, every camelCase operation, with the deprecated `selectTool` / `submit` overloads; subscribe to editor events via the `onEmbedEvent` prop. (The framework-free `@simplepdf/embed` core exposes the grouped `embed.actions` / `embed.events` / `embed.lifecycle` handle for non-React use.)
 
-#### Agentic: `useEmbedTanstackTools` (TanStack AI)
+#### Agentic: `useEmbedTools` (TanStack AI)
 
-The TanStack mirror lives in the opt-in `@simplepdf/react-embed-pdf/tanstack-ai` subpath (importing it pulls `@tanstack/ai`). `useEmbedTanstackTools(embedRef)` returns the editor-bound client tools; pass them to `clientTools(...)`, then `useChat`:
+The TanStack mirror lives in the opt-in `@simplepdf/react-embed-pdf/tanstack-ai` subpath (importing it pulls `@tanstack/ai`). `useEmbedTools(embedRef)` returns the editor-bound client tools; pass them to `clientTools(...)`, then `useChat`:
 
 ```jsx
 import { useChat, clientTools } from '@tanstack/ai-react';
 import { EmbedPDF, useEmbed } from '@simplepdf/react-embed-pdf';
-import { useEmbedTanstackTools } from '@simplepdf/react-embed-pdf/tanstack-ai';
+import { useEmbedTools } from '@simplepdf/react-embed-pdf/tanstack-ai';
 
 const CopilotEditor = () => {
   const { embedRef } = useEmbed();
-  const tools = clientTools(...useEmbedTanstackTools(embedRef));
+  const tools = clientTools(...useEmbedTools(embedRef));
   useChat({ connection, tools }); // the model's tool calls run against the live editor
   return <EmbedPDF ref={embedRef} mode="inline" companyIdentifier="yourcompany" style={{ width: 900, height: 800 }} />;
 };
 ```
 
-On your server `chat({ tools })` route, register `simplePDFTanstackToolDefinitions()` (re-exported from the same subpath) so the model is aware of the tools.
+On your server `chat({ tools })` route, register `simplePDFToolDefinitions()` imported from the React-free core `@simplepdf/embed/tanstack-ai` (not from this React subpath, which would pull React into your server) so the model is aware of the tools.
 
 See [Retrieving PDF Data](../README.md#retrieving-pdf-data) for text extraction, downloading, and server-side storage options.
 

react/src/tanstack-ai.test.tsx

@@ -5,23 +5,23 @@ import { describe, expect, it, vi } from 'vitest';
 import { render } from '@testing-library/react';
 import type { BridgeResult } from '@simplepdf/embed';
 import { useEmbed } from './index';
-import { useEmbedTanstackTools } from './tanstack-ai';
+import { useEmbedTools } from './tanstack-ai';
 
 // useEmbed pulls in <EmbedPDF>, which imports scss (a build concern, irrelevant here).
 vi.mock('./styles.scss', () => ({}));
 
-describe('useEmbedTanstackTools', () => {
+describe('useEmbedTools', () => {
   it('returns TanStack client tools, each execute null-safe before <EmbedPDF> mounts', async () => {
-    const captured: ReturnType<typeof useEmbedTanstackTools>[] = [];
+    const captured: ReturnType<typeof useEmbedTools>[] = [];
     const Probe = (): null => {
       const { embedRef } = useEmbed();
-      captured.push(useEmbedTanstackTools(embedRef));
+      captured.push(useEmbedTools(embedRef));
       return null;
     };
     render(<Probe />);
     const tools = captured[0];
     if (tools === undefined) {
-      throw new Error('expected useEmbedTanstackTools to have rendered');
+      throw new Error('expected useEmbedTools to have rendered');
     }
     const goTo = tools.find((tool) => tool.name === 'goTo');
     if (goTo === undefined || goTo.execute === undefined) {

react/src/tanstack-ai.tsx

@@ -4,29 +4,30 @@
 // with useEmbed():
 //
 //   const { embedRef } = useEmbed()
-//   const tools = clientTools(...useEmbedTanstackTools(embedRef)) // from @tanstack/ai-react
+//   const tools = clientTools(...useEmbedTools(embedRef)) // from @tanstack/ai-react
 //   useChat({ connection, tools })
 
 import * as React from 'react';
 import type { RefObject } from 'react';
 import type { AnyClientTool } from '@tanstack/ai';
 import { routeToolCall } from '@simplepdf/embed/tools';
-import { simplePDFTanstackToolDefinitions } from '@simplepdf/embed/tanstack-ai';
+import { simplePDFToolDefinitions } from '@simplepdf/embed/tanstack-ai';
 import type { EmbedActions } from './embed-pdf';
 import { notMounted } from './not-mounted';
 
-// Re-export the server-side definitions + the tool-name type so React consumers get
-// the whole TanStack surface from this one subpath (mirroring /ai-sdk).
-export { simplePDFTanstackToolDefinitions } from '@simplepdf/embed/tanstack-ai';
+// The server-side tool definitions are NOT re-exported here on purpose: this module
+// imports React (for the hook), so re-exporting them would drag React into a server
+// route that only needs the defs. Import those from the React-free core instead
+// (`@simplepdf/embed/tanstack-ai`). Only the tool-name type (erased at build) is re-exported.
 export type { SimplePDFToolName } from '@simplepdf/embed/tanstack-ai';
 
 // The agentic tools bound to the live editor via useEmbed().embedRef. Stable and
 // null-safe before the editor mounts (each .client() reads embedRef.current at call
 // time). Pass to clientTools(...) -> useChat({ tools }).
-export const useEmbedTanstackTools = (embedRef: RefObject<EmbedActions | null>): AnyClientTool[] =>
+export const useEmbedTools = (embedRef: RefObject<EmbedActions | null>): AnyClientTool[] =>
   React.useMemo<AnyClientTool[]>(
     () =>
-      simplePDFTanstackToolDefinitions().map((definition) =>
+      simplePDFToolDefinitions().map((definition) =>
         definition.client((input) =>
           embedRef.current === null ? notMounted() : routeToolCall(embedRef.current, definition.name, input),
         ),