feat(P060): rename REMOVE_FIELDS->DELETE_FIELDS and DELETE_PAGE->DELETE_PAGES (array) (#33)

## Background

Cleanup pass on the copilot bridge + LLM-tool adapter. Pairs with the
matching top-level repo PR
([SimplePDF/simple-pdf#196](SimplePDF/simple-pdf#196))
which carries the editor / e2e changes.

The bridge now owns the iframe contract end-to-end (Zod schemas +
descriptions + parsing). The adapter is a one-line-per-tool router.

## Changes

**Bridge owns the contract**
- New `embed-bridge/schemas.ts` — single source of truth: one Zod schema
per iframe operation, each with `.describe()`. Snake_case keys
throughout (matches the wire).
- `IframeBridge` methods accept `unknown` and validate internally via
`parseAndSend(Schema, 'EVENT', args)`. Bad input → `bad_input` without a
postMessage round-trip.
- `BridgeResult.error.code` is now a typed union with autocomplete for
bridge-owned codes.

**Adapter is thin**
- `dispatch.ts`, `safeDispatch`, `client-tools/schemas.ts`, and the
redundant `isClientToolName` runtime narrow are gone.
- New `tools.ts` enumerates LLM tool names and pulls descriptions
verbatim from the bridge schemas (no duplicated text).
- `factory.ts` switch terminus is pure routing — every arm is one line;
`satisfies never` keeps it exhaustive.
- `chat.ts` and `transport.ts` drop ~50 lines each: tool registration is
now `tools: withFinalisationTool(LLM_STATIC_TOOLS)`.

**Dead code pruned**
- `bridge.createField` + `CreateFieldArgs` removed (no LLM tool, no
other consumer).
- `chat.toolInvocation.names.create_field` i18n key dropped from all 23
locales.
- `createLlmFieldBaselineMiddleware` + `markFieldAsKnown` plumbing
removed (the `create_field` tool was never registered).

**Iframe contract rename** (also part of this PR)
- `REMOVE_FIELDS` → `DELETE_FIELDS` (response `removed_count` →
`deleted_count`).
- `DELETE_PAGE { page }` → `DELETE_PAGES { pages: number[] }`.

**React SDK (BREAKING)**
- `actions.removeFields` → `actions.deleteFields`; `removed_count` →
`deleted_count`. Major-version changeset added.

Net: `+388 / -674` lines on `copilot/`. Adding a new bridge operation is
now: schema in `schemas.ts`, method on `IframeBridge`, `parseAndSend`
line in `bridge.ts`. Exposing it to the LLM: one entry in
`LLM_STATIC_TOOLS`, one switch arm in `factory.ts`. The `satisfies
never` exhaustiveness catches drift at compile time.

Author: bendersej

.changeset/rename-remove-fields-to-delete-fields.md

@@ -0,0 +1,21 @@
+---
+"@simplepdf/react-embed-pdf": major
+---
+
+Renames `actions.removeFields` to `actions.deleteFields` and the corresponding iframe event from `REMOVE_FIELDS` to `DELETE_FIELDS`. The result payload field is renamed from `removed_count` to `deleted_count`. Aligns naming with the new `DELETE_PAGES` event so all destructive operations use `delete_*` consistently.
+
+If you are not using `actions.removeFields(...)` or `sendEvent("REMOVE_FIELDS", ...)`, you can safely update to this new major version.
+
+```ts
+// Before
+const result = await actions.removeFields({ page: 1 });
+if (result.success) {
+  console.log(result.data.removed_count);
+}
+
+// After
+const result = await actions.deleteFields({ page: 1 });
+if (result.success) {
+  console.log(result.data.deleted_count);
+}
+```

copilot/src/components/chat/chat_pane.tsx

@@ -324,25 +324,6 @@ const createToolbarSyncMiddleware =
     return result
   }
 
-// When the LLM itself creates a field (via `create_field`), the iframe's
-// field set grows by one. If we did nothing, the post-stream getFields
-// would diff that field as "user-added" and nudge the LLM about a field
-// it just created itself. This middleware extracts the new field id from
-// the bridge result and forwards it to the host so the field-detection
-// hook can pre-mark it as known.
-const createLlmFieldBaselineMiddleware =
-  ({ onLlmCreatedField }: { onLlmCreatedField: (fieldId: string) => void }): ToolMiddleware =>
-  async ({ toolName }, next) => {
-    const result = await next()
-    if (toolName === 'create_field' && result.success) {
-      const data = result.data
-      if (data !== null && typeof data === 'object' && 'field_id' in data && typeof data.field_id === 'string') {
-        onLlmCreatedField(data.field_id)
-      }
-    }
-    return result
-  }
-
 const toUnexpectedToolResult = (error: unknown): BridgeResult<null> => {
   const errorMessage = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
   return {
@@ -550,7 +531,7 @@ export const ChatPane = ({
     if (activeBridge === null) {
       return
     }
-    void activeBridge.submit({ downloadCopy: false })
+    void activeBridge.submit({ download_copy: false })
   }, [])
 
   const handleDownloadRequested = useCallback((): void => {
@@ -640,13 +621,13 @@ export const ChatPane = ({
   }, [])
 
   // Refs-not-props for isStreaming + onFieldAdded: useDetectUserAddedField
-  // must be called BEFORE `tools` useMemo (which needs markFieldAsKnown),
-  // but both of those pieces of information come from useChat which runs
-  // AFTER `tools`. Refs break the cycle; they are synced once useChat's
-  // output is in scope (a bit further down in this component).
+  // must be called BEFORE `tools` useMemo, but both of those pieces of
+  // information come from useChat which runs AFTER `tools`. Refs break the
+  // cycle; they are synced once useChat's output is in scope (a bit further
+  // down in this component).
   const isStreamingRef = useRef(false)
   const onFieldAddedRef = useRef<(event: { tools: SupportedFieldType[]; delta: number }) => void>(() => {})
-  const { markFieldAsKnown: markFieldDetectionAsKnown } = useDetectUserAddedField({
+  useDetectUserAddedField({
     bridge,
     isReady,
     toolbarTool,
@@ -665,11 +646,6 @@ export const ChatPane = ({
     }
     const sharedMiddleware: ToolMiddleware[] = [
       createToolbarSyncMiddleware({ onChange: setToolbarTool }),
-      createLlmFieldBaselineMiddleware({
-        // When the LLM creates a field, mark its id as known so the next
-        // user-placed-field diff does not attribute it to the user.
-        onLlmCreatedField: (fieldId) => markFieldDetectionAsKnown(fieldId),
-      }),
       createCompactionMiddleware({ getByokActive: () => byokConfigRef.current !== null }),
     ]
     // Demo-only middleware lives at the head of the chain so it
@@ -684,7 +660,7 @@ export const ChatPane = ({
       systemPrompt: SYSTEM_PROMPT,
       middleware,
     })
-  }, [bridge, handleDownloadRequested, markFieldDetectionAsKnown])
+  }, [bridge, handleDownloadRequested])
 
   const { messages, status, error, sendMessage, stop, addToolOutput, setMessages } = useChat({
     transport,

copilot/src/components/chat/hooks/use_detect_user_added_field.ts

@@ -1,4 +1,4 @@
-import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
+import { type MutableRefObject, useEffect, useRef } from 'react'
 import type { IframeBridge, SupportedFieldType } from '../../../lib/embed-bridge'
 
 // WORKAROUND: the SimplePDF editor does not currently emit an outbound
@@ -30,11 +30,6 @@ import type { IframeBridge, SupportedFieldType } from '../../../lib/embed-bridge
 // the UI can show one icon per unique type when the user mixed (e.g.
 // TEXT + SIGNATURE in the same batch).
 //
-// LLM-created fields bypass this nudge via `markFieldAsKnown(fieldId)`,
-// called from the create_field middleware once the iframe has confirmed
-// the new field id. The id goes straight into the seen set; the next
-// poll's diff sees no user-added fields.
-//
 // Refs-not-props for the streaming flag and the fire callback let the
 // hook be called BEFORE useChat in the consumer (useChat produces the
 // status + sendMessage used downstream). The consumer syncs the refs
@@ -53,31 +48,17 @@ type UseDetectUserAddedFieldArgs = {
   onFieldAddedRef: MutableRefObject<(event: FieldAddedEvent) => void>
 }
 
-type UseDetectUserAddedFieldReturn = {
-  // Consumers call this when they know a field was added by something
-  // other than the user (e.g. the LLM's `create_field` tool returned a
-  // field id). The id is added to the seen set so the next poll does
-  // NOT attribute that field to the user.
-  markFieldAsKnown: (fieldId: string) => void
-}
-
 export const useDetectUserAddedField = ({
   bridge,
   isReady,
   toolbarTool,
   isCursorOverEditor,
   isStreamingRef,
   onFieldAddedRef,
-}: UseDetectUserAddedFieldArgs): UseDetectUserAddedFieldReturn => {
+}: UseDetectUserAddedFieldArgs): void => {
   const seenIdsRef = useRef<Set<string> | null>(null)
   const lastBridgeRef = useRef<IframeBridge | null>(null)
 
-  const markFieldAsKnown = useCallback((fieldId: string): void => {
-    if (seenIdsRef.current !== null) {
-      seenIdsRef.current.add(fieldId)
-    }
-  }, [])
-
   useEffect(() => {
     // Bridge swap is the only event that invalidates the seen set; the
     // ids belong to a different document context. Tool changes, cursor
@@ -145,6 +126,4 @@ export const useDetectUserAddedField = ({
       }
     }
   }, [bridge, isReady, toolbarTool, isCursorOverEditor, isStreamingRef, onFieldAddedRef])
-
-  return { markFieldAsKnown }
 }

copilot/src/lib/byok/transport.ts

@@ -1,18 +1,8 @@
 import { convertToModelMessages, streamText, type UIMessage } from 'ai'
 import { buildSystemPrompt } from '../../server/tools'
 import {
-  DeletePageInput,
-  DetectFieldsInput,
   FINALISATION_ACTION,
-  FocusFieldInput,
-  GetDocumentContentInput,
-  GetFieldsInput,
-  GoToPageInput,
-  MovePageInput,
-  RemoveFieldsInput,
-  RotatePageInput,
-  SelectToolInput,
-  SetFieldValueInput,
+  LLM_STATIC_TOOLS,
   withFinalisationTool,
 } from '../embed-bridge-adapters/client-tools'
 import { formatStreamError } from '../error-classifier'
@@ -93,58 +83,7 @@ export const runByokStream = async ({ config, init }: RunByokStreamArgs): Promis
     abortSignal: init?.signal ?? undefined,
     maxRetries: 0,
     maxOutputTokens: MAX_OUTPUT_TOKENS,
-    tools: withFinalisationTool({
-      get_fields: {
-        description: 'Lists every fillable field currently on the document.',
-        inputSchema: GetFieldsInput,
-      },
-      get_document_content: {
-        description: 'Extracts the textual content of the document page by page.',
-        inputSchema: GetDocumentContentInput,
-      },
-      detect_fields: {
-        description:
-          'Asks the editor to auto-detect and create missing fields. Call this when get_fields returned 0 fields.',
-        inputSchema: DetectFieldsInput,
-      },
-      remove_fields: {
-        description:
-          'Removes fields from the document. field_ids targets specific fields by id; page targets a single page (1-indexed); both omitted clears all fields. Destructive — only call when the user explicitly asks to remove fields.',
-        inputSchema: RemoveFieldsInput,
-      },
-      select_tool: {
-        description:
-          'Switches the editor tool (TEXT, BOXED_TEXT, CHECKBOX, SIGNATURE, PICTURE, or null for cursor).',
-        inputSchema: SelectToolInput,
-      },
-      set_field_value: {
-        description: 'Writes a value into a single field. Always focus_field first.',
-        inputSchema: SetFieldValueInput,
-      },
-      focus_field: {
-        description: 'Scrolls to and visually highlights a field.',
-        inputSchema: FocusFieldInput,
-      },
-      go_to_page: {
-        description: 'Scrolls the editor to a given 1-based page.',
-        inputSchema: GoToPageInput,
-      },
-      move_page: {
-        description:
-          'Reorders pages: from_page and to_page are 1-indexed visible page positions. Destructive — only call when the user explicitly asks to reorder a page.',
-        inputSchema: MovePageInput,
-      },
-      delete_page: {
-        description:
-          'Permanently removes a visible page (1-indexed) and any fields placed on it. The last remaining page cannot be deleted. Destructive — only call when the user explicitly asks to delete a page.',
-        inputSchema: DeletePageInput,
-      },
-      rotate_page: {
-        description:
-          'Rotates a visible page (1-indexed) 90° clockwise per call (repeat for 180° / 270°). Destructive — only call when the user explicitly asks to rotate a page.',
-        inputSchema: RotatePageInput,
-      },
-    }),
+    tools: withFinalisationTool(LLM_STATIC_TOOLS),
     onError: ({ error }) => {
       monitoring.error('byok.stream_error', { detail: normalizeError(error) })
     },