fix(transaction): satisfy kiira doc checks and eslint on clientTransaction cast

Add kiira group tags and explicit snippet types in transaction docs, and
document the phantom-only double cast in clientTransaction with an eslint
opt-out matching the chat activity pattern.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jherr

docs/transaction/overview.md

@@ -21,7 +21,7 @@ Verb names are *your* domain language, not a fixed set of library nouns. A blog
 
 `defineTransaction()` lives on the `/transaction` subpath of `@tanstack/ai`, and `useTransaction()` on the `/transaction` subpath of `@tanstack/ai-react` (Solid and Vue follow the same pattern; Svelte exports `createTransaction` from `@tanstack/ai-svelte/transaction`) — not the package root.
 
-```ts
+```ts group=overview-1
 // lib/blog-studio.ts — define once; the API route only calls `.handler`
 import { chat, generateImage, generateSpeech } from '@tanstack/ai'
 import { chatVerb, clientTransaction, defineTransaction, verb } from '@tanstack/ai/transaction'
@@ -66,17 +66,18 @@ export const blogTxnDef = clientTransaction<typeof blogTransaction>({
 })
 ```
 
-```ts
+```ts group=overview-1
 // routes/api.blog-studio.ts — thin server route
 export const POST = (request: Request) => blogTransaction.handler(request)
 ```
 
 That one route now serves conversational drafting, image generation, and narration. On the client, one hook drives all three:
 
-```tsx
+```tsx group=overview-client
 // routes/blog-studio.tsx
 import { fetchServerSentEvents } from '@tanstack/ai-react'
 import { useTransaction } from '@tanstack/ai-react/transaction'
+import type { UIMessage } from '@tanstack/ai-react'
 import { blogTxnDef } from '../lib/blog-studio'
 
 function BlogStudio() {
@@ -87,7 +88,7 @@ function BlogStudio() {
   return (
     <div>
       <button onClick={() => txn.drafting.sendMessage('Hello!')}>Send</button>
-      {txn.drafting.messages.map((message) => (
+      {txn.drafting.messages.map((message: UIMessage) => (
         <p key={message.id}>
           {message.parts.find((part) => part.type === 'text')?.content}
         </p>
@@ -120,7 +121,7 @@ Both `txn.<oneShot>.run(input)` and `txn.<chatVerb>.sendMessage(...)` **resolve
 
 You can declare **several verbs of the same kind** — including several chat verbs. Each gets its own conversation state, system prompt, and even model:
 
-```ts
+```ts group=overview-2
 // api/support.ts
 import { chat } from '@tanstack/ai'
 import { chatVerb, defineTransaction } from '@tanstack/ai/transaction'
@@ -162,7 +163,9 @@ On the client, `txn.primaryChat` and `txn.summaryChat` are two fully independent
 
 The recommended pattern is to **`defineTransaction` once in a shared module** and export a **`blogTxnDef`** client stub beside it via `clientTransaction<typeof blogTransaction>({ kinds })`. The page imports `blogTxnDef`; the API route imports `blogTransaction` and calls `.handler`. The kinds map is checked exhaustively against the server definition, so drift fails at compile time.
 
-```ts
+```ts group=overview-sharing
+import { clientTransaction, defineTransaction } from '@tanstack/ai/transaction'
+
 // lib/blog-studio.ts
 export const blogTransaction = defineTransaction({ /* … */ })
 

docs/transaction/transactions.md

@@ -25,7 +25,7 @@ One click turns a topic into a finished post: draft the article as a typed objec
 
 ### Server: a `blogPost` verb that composes its siblings
 
-```ts
+```ts group=transactions
 // lib/blog-studio.ts
 import { chat, generateImage, generateSpeech } from '@tanstack/ai'
 import { chatVerb, defineTransaction, verb } from '@tanstack/ai/transaction'
@@ -116,7 +116,7 @@ export const blogTransaction = defineTransaction({
 })
 ```
 
-```ts
+```ts group=transactions
 // routes/api.blog-studio.ts
 export const POST = (request: Request) => blogTransaction.handler(request)
 ```
@@ -128,10 +128,11 @@ export const POST = (request: Request) => blogTransaction.handler(request)
 
 ### Client: one call, live progress, typed result
 
-```tsx
+```tsx group=transactions
 // routes/blog-studio.tsx
 import { fetchServerSentEvents } from '@tanstack/ai-react'
 import { useTransaction } from '@tanstack/ai-react/transaction'
+import type { TransactionSubRun } from '@tanstack/ai-client/transaction'
 import { blogTxnDef } from '../lib/blog-studio'
 
 function BlogStudio() {
@@ -141,9 +142,15 @@ function BlogStudio() {
 
   const { blogPost } = txn
   // One entry per `ctx.call` the server made, keyed by verb name.
-  const draftingRun = blogPost.subRuns.find((run) => run.verb === 'drafting')
-  const heroRun = blogPost.subRuns.find((run) => run.verb === 'heroImage')
-  const narrationRun = blogPost.subRuns.find((run) => run.verb === 'narration')
+  const draftingRun = blogPost.subRuns.find(
+    (run: TransactionSubRun) => run.verb === 'drafting',
+  )
+  const heroRun = blogPost.subRuns.find(
+    (run: TransactionSubRun) => run.verb === 'heroImage',
+  )
+  const narrationRun = blogPost.subRuns.find(
+    (run: TransactionSubRun) => run.verb === 'narration',
+  )
 
   return (
     <div>

packages/ai/src/activities/transaction/index.ts

@@ -250,7 +250,7 @@ export function clientTransaction<TDef extends TransactionDefinition<any>>(
   kinds: ClientTransactionKinds<TDef>,
 ): TDef {
   const verbs = Object.keys(kinds) as Array<keyof TDef['~verbs'] & string>
-  return {
+  const stub = {
     verbs,
     verbKinds: kinds,
     handler: async () => {
@@ -259,7 +259,11 @@ export function clientTransaction<TDef extends TransactionDefinition<any>>(
       )
     },
     '~verbs': {} as TDef['~verbs'],
-  } as unknown as TDef
+  }
+  // Type-only stub: runtime value carries verb names/kinds; `~verbs` phantom
+  // comes from the generic `TDef` supplied by the caller.
+  // eslint-disable-next-line no-restricted-syntax -- phantom-only cast, see comment above
+  return stub as unknown as TDef
 }
 
 /**