refactor(P060): bridge owns the parsing — adapter is a pure router

Each bridge method now safeParses its `unknown` input via the matching
Zod schema before posting to the iframe. Bad input surfaces as
`{ success: false, error: { code: 'bad_input', message } }` without a
postMessage round-trip. The adapter (createClientTools switch terminus)
collapses to one-line cases that just hand the LLM input to the bridge.

- IframeBridge methods take `args: unknown` (uniform external surface).
- bridge.ts: parseAndSend helper centralises the parse + sendRequest pair.
- factory.ts: switch is pure routing, no schemas imported.
- sendRequest's `data` parameter loosened to `unknown` (it JSON.stringifies
  and doesn't care about the shape).

Adding a new bridge operation is now: schema in schemas.ts, method on
IframeBridge, parseAndSend line in bridge.ts, switch arm in factory.ts.
The schema is the single source of truth.

Author: bendersej

copilot/src/lib/embed-bridge-adapters/client-tools/factory.ts

@@ -1,16 +1,4 @@
-import {
-  type BridgeResult,
-  DeleteFieldsInput,
-  DeletePagesInput,
-  FocusFieldInput,
-  GetDocumentContentInput,
-  GoToInput,
-  type IframeBridge,
-  MovePageInput,
-  RotatePageInput,
-  SelectToolInput,
-  SetFieldValueInput,
-} from '../../embed-bridge'
+import type { BridgeResult, IframeBridge } from '../../embed-bridge'
 import { composeMiddleware, type ToolMiddleware } from './middleware'
 import { type ClientToolName, isClientToolName } from './tools'
 
@@ -41,7 +29,7 @@ export type ClientTools = {
   // registered tools.
   execute: (toolName: ClientToolName, input: ToolInput) => Promise<BridgeResult<unknown>>
   // Type guard re-export so the consumer can branch on tool names without
-  // importing `schemas.ts` separately.
+  // importing `tools.ts` separately.
   isClientToolName: typeof isClientToolName
 }
 
@@ -50,45 +38,43 @@ export const createClientTools = ({
   systemPrompt,
   middleware = [],
 }: CreateClientToolsArgs): ClientTools => {
-  // One arm per tool. Each arm parses the LLM-supplied input via the
-  // bridge schema (single source of truth, lives in
-  // embed-bridge/schemas.ts) and forwards the typed payload to the matching
-  // bridge method. `satisfies never` keeps the switch exhaustive over
-  // ClientToolName at compile time.
-  const composed = composeMiddleware(middleware, async ({ toolName, input }) => {
+  // Pure router. Each arm just hands the LLM input to the matching bridge
+  // method; the bridge owns parsing + validation. `satisfies never` keeps
+  // the switch exhaustive over ClientToolName at compile time.
+  const composed = composeMiddleware(middleware, ({ toolName, input }) => {
     switch (toolName) {
       case 'get_fields':
         return bridge.getFields()
       case 'get_document_content':
-        return bridge.getDocumentContent(GetDocumentContentInput.parse(input))
+        return bridge.getDocumentContent(input)
       case 'detect_fields':
         return bridge.detectFields()
       case 'delete_fields':
-        return bridge.deleteFields(DeleteFieldsInput.parse(input))
+        return bridge.deleteFields(input)
       case 'select_tool':
-        return bridge.selectTool(SelectToolInput.parse(input))
+        return bridge.selectTool(input)
       case 'set_field_value':
-        return bridge.setFieldValue(SetFieldValueInput.parse(input))
+        return bridge.setFieldValue(input)
       case 'focus_field':
-        return bridge.focusField(FocusFieldInput.parse(input))
+        return bridge.focusField(input)
       case 'go_to_page':
-        return bridge.goTo(GoToInput.parse(input))
+        return bridge.goTo(input)
       case 'move_page':
-        return bridge.movePage(MovePageInput.parse(input))
+        return bridge.movePage(input)
       case 'delete_pages':
-        return bridge.deletePages(DeletePagesInput.parse(input))
+        return bridge.deletePages(input)
       case 'rotate_page':
-        return bridge.rotatePage(RotatePageInput.parse(input))
+        return bridge.rotatePage(input)
       case 'submit':
         return bridge.submit({ download_copy: false })
       case 'download':
         return bridge.download()
       default:
         toolName satisfies never
-        return {
+        return Promise.resolve({
           success: false,
           error: { code: 'unknown_tool', message: `Unknown tool: ${String(toolName)}` },
-        }
+        })
     }
   })
   return {

copilot/src/lib/embed-bridge/bridge.ts

@@ -1,10 +1,25 @@
+import type { z } from 'zod'
 import { type BridgeLogger, NOOP_LOGGER } from './logger'
+import {
+  DeleteFieldsInput,
+  DeletePagesInput,
+  FocusFieldInput,
+  GetDocumentContentInput,
+  GoToInput,
+  LoadDocumentInput,
+  MovePageInput,
+  RotatePageInput,
+  SelectToolInput,
+  SetFieldValueInput,
+  SubmitInput,
+} from './schemas'
 import {
   type BridgeRequestType,
   type BridgeResult,
   type BridgeState,
   type DocumentContentResult,
   type FieldRecord,
+  type FocusFieldResult,
   type IframeBridge,
   isBridgeResultLike,
 } from './types'
@@ -109,7 +124,7 @@ export const createBridge = ({
 
   const sendRequest = <TData>(
     type: BridgeRequestType,
-    data: Record<string, unknown>,
+    data: unknown,
   ): Promise<BridgeResult<TData>> =>
     new Promise((resolve) => {
       const iframe = getIframe()
@@ -368,24 +383,49 @@ export const createBridge = ({
 
   window.addEventListener('message', onMessage)
 
-  // Each method is a one-line pass-through to sendRequest. The args shape
-  // already matches the iframe's snake_case payload (see schemas.ts), so
-  // no key conversion happens at this layer.
+  // The bridge OWNS validation: each method validates its `unknown` input
+  // against the schema in schemas.ts before posting to the iframe. The
+  // adapter layer (LLM dispatcher, React SDK, etc.) is therefore a pure
+  // router — no parse, no narrowing. Adding a new method = add a schema in
+  // schemas.ts, add a method on IframeBridge, and add a `parseAndSend` line
+  // here.
+  const parseAndSend = <TSchema extends z.ZodType, TData = null>(
+    schema: TSchema,
+    type: BridgeRequestType,
+    args: unknown,
+  ): Promise<BridgeResult<TData>> => {
+    const parsed = schema.safeParse(args)
+    if (!parsed.success) {
+      return Promise.resolve({
+        success: false,
+        error: { code: 'bad_input', message: parsed.error.message },
+      })
+    }
+    return sendRequest<TData>(type, parsed.data)
+  }
   const bridge: IframeBridge = {
     getState: () => state,
-    loadDocument: (args) => sendRequest('LOAD_DOCUMENT', args),
+    loadDocument: (args) => parseAndSend(LoadDocumentInput, 'LOAD_DOCUMENT', args),
     getFields: () => sendRequest<{ fields: FieldRecord[] }>('GET_FIELDS', {}),
-    getDocumentContent: (args) => sendRequest<DocumentContentResult>('GET_DOCUMENT_CONTENT', args),
+    getDocumentContent: (args) => parseAndSend<typeof GetDocumentContentInput, DocumentContentResult>(
+      GetDocumentContentInput,
+      'GET_DOCUMENT_CONTENT',
+      args,
+    ),
     detectFields: () => sendRequest('DETECT_FIELDS', {}),
-    deleteFields: (args) => sendRequest('DELETE_FIELDS', args),
-    selectTool: (args) => sendRequest('SELECT_TOOL', args),
-    setFieldValue: (args) => sendRequest('SET_FIELD_VALUE', args),
-    focusField: (args) => sendRequest('FOCUS_FIELD', args),
-    goTo: (args) => sendRequest('GO_TO', args),
-    movePage: (args) => sendRequest('MOVE_PAGE', args),
-    deletePages: (args) => sendRequest('DELETE_PAGES', args),
-    rotatePage: (args) => sendRequest('ROTATE_PAGE', args),
-    submit: (args) => sendRequest('SUBMIT', args),
+    deleteFields: (args) => parseAndSend<typeof DeleteFieldsInput, { deleted_count: number }>(
+      DeleteFieldsInput,
+      'DELETE_FIELDS',
+      args,
+    ),
+    selectTool: (args) => parseAndSend(SelectToolInput, 'SELECT_TOOL', args),
+    setFieldValue: (args) => parseAndSend(SetFieldValueInput, 'SET_FIELD_VALUE', args),
+    focusField: (args) => parseAndSend<typeof FocusFieldInput, FocusFieldResult>(FocusFieldInput, 'FOCUS_FIELD', args),
+    goTo: (args) => parseAndSend(GoToInput, 'GO_TO', args),
+    movePage: (args) => parseAndSend(MovePageInput, 'MOVE_PAGE', args),
+    deletePages: (args) => parseAndSend(DeletePagesInput, 'DELETE_PAGES', args),
+    rotatePage: (args) => parseAndSend(RotatePageInput, 'ROTATE_PAGE', args),
+    submit: (args) => parseAndSend(SubmitInput, 'SUBMIT', args),
     download: () => sendRequest('DOWNLOAD', {}),
   }
 

copilot/src/lib/embed-bridge/types.ts

@@ -1,21 +1,6 @@
 // Shared types for the SimplePDF embed bridge. Pure TypeScript, no
 // framework dependencies.
 
-import type { z } from 'zod'
-import type {
-  DeleteFieldsInput,
-  DeletePagesInput,
-  FocusFieldInput,
-  GetDocumentContentInput,
-  GoToInput,
-  LoadDocumentInput,
-  MovePageInput,
-  RotatePageInput,
-  SelectToolInput,
-  SetFieldValueInput,
-  SubmitInput,
-} from './schemas'
-
 export type BridgeResult<TData = null> =
   | { success: true; data: TData }
   | { success: false; error: { code: string; message: string } }
@@ -104,26 +89,28 @@ export type BridgeRequestType =
   | 'DELETE_PAGES'
   | 'ROTATE_PAGE'
 
-// Each method's input is typed via z.infer from its bridge schema in
-// schemas.ts — that file is the single source of truth for the iframe
-// contract shape. Output types (BridgeResult<...>) stay explicit since
-// they describe the iframe response, not the request input.
 export type FocusFieldResult = { hint: { type: 'user_action_expected'; message: string } } | null
 
+// The bridge owns the contract. Each method takes `unknown` (raw, from any
+// caller — the LLM dispatcher, direct UI code, etc.) and validates it
+// internally against the matching Zod schema in schemas.ts before posting
+// to the iframe. Bad input surfaces as `{ success: false, error: { code:
+// 'bad_input', ... } }` without a postMessage round-trip. Adapters do not
+// re-validate.
 export type IframeBridge = {
   getState: () => BridgeState
-  loadDocument: (args: z.infer<typeof LoadDocumentInput>) => Promise<BridgeResult>
+  loadDocument: (args: unknown) => Promise<BridgeResult>
   getFields: () => Promise<BridgeResult<{ fields: FieldRecord[] }>>
-  getDocumentContent: (args: z.infer<typeof GetDocumentContentInput>) => Promise<BridgeResult<DocumentContentResult>>
+  getDocumentContent: (args: unknown) => Promise<BridgeResult<DocumentContentResult>>
   detectFields: () => Promise<BridgeResult<{ detected_count: number }>>
-  deleteFields: (args: z.infer<typeof DeleteFieldsInput>) => Promise<BridgeResult<{ deleted_count: number }>>
-  selectTool: (args: z.infer<typeof SelectToolInput>) => Promise<BridgeResult>
-  setFieldValue: (args: z.infer<typeof SetFieldValueInput>) => Promise<BridgeResult>
-  focusField: (args: z.infer<typeof FocusFieldInput>) => Promise<BridgeResult<FocusFieldResult>>
-  goTo: (args: z.infer<typeof GoToInput>) => Promise<BridgeResult>
-  movePage: (args: z.infer<typeof MovePageInput>) => Promise<BridgeResult>
-  deletePages: (args: z.infer<typeof DeletePagesInput>) => Promise<BridgeResult>
-  rotatePage: (args: z.infer<typeof RotatePageInput>) => Promise<BridgeResult>
-  submit: (args: z.infer<typeof SubmitInput>) => Promise<BridgeResult>
+  deleteFields: (args: unknown) => Promise<BridgeResult<{ deleted_count: number }>>
+  selectTool: (args: unknown) => Promise<BridgeResult>
+  setFieldValue: (args: unknown) => Promise<BridgeResult>
+  focusField: (args: unknown) => Promise<BridgeResult<FocusFieldResult>>
+  goTo: (args: unknown) => Promise<BridgeResult>
+  movePage: (args: unknown) => Promise<BridgeResult>
+  deletePages: (args: unknown) => Promise<BridgeResult>
+  rotatePage: (args: unknown) => Promise<BridgeResult>
+  submit: (args: unknown) => Promise<BridgeResult>
   download: () => Promise<BridgeResult>
 }