@pilotiq/tiptap 3.4.0 → 3.5.0

package/dist/react/useAiSuggestionBridge.js

@@ -1,36 +1,29 @@
 import { useEffect, useRef } from 'react';
 import { registerPendingSuggestionApplier, usePendingSuggestionsForField, } from '@pilotiq/pilotiq/react';
 import { aiSuggestionPluginKey } from '../extensions/AiSuggestionExtension.js';
-/**
- * Two-way sync between the cross-package `<PendingSuggestionsContext>`
- * queue and this editor's `AiSuggestionExtension` state.
- *
- *   - **Context → editor**: every entry whose `meta.editorRange = { from, to }`
- *     is present and whose `suggestedValue` is a string gets pushed into the
- *     editor as an inline-diff hunk via `addAiSuggestion`. Entries leaving the
- *     queue are removed from the editor via `rejectAiSuggestion` (no doc edit).
- *
- *   - **Editor → context**: when a chip's Approve / Reject button removes a
- *     hunk from the editor's plugin state, the matching id is dismissed from
- *     the queue (`dismiss(id)`) so other surfaces (e.g. the chat-sidebar pill,
- *     a future FieldShell overlay) clear in lock-step. The doc mutation
- *     itself happens inside the editor — context is just a notification.
- *
- * Cycle protection: the hook tracks which ids it has personally pushed to
- * the editor (`pushed`). The Context→editor pass never re-pushes an id that's
- * already there, and the Editor→context pass only dismisses ids that this
- * hook had previously pushed (so an id added directly by host code via
- * `editor.commands.addAiSuggestion(...)` doesn't get reflected back through
- * a context that never knew about it).
- */
-export function useAiSuggestionBridge(editor, fieldName) {
+export function useAiSuggestionBridge(editor, fieldName, options = {}) {
     const { list, dismiss } = usePendingSuggestionsForField(fieldName);
     // Hold the latest `dismiss` in a ref so the editor-side listener — which
     // installs once per editor — always reaches the up-to-date context API.
     const dismissRef = useRef(dismiss);
     useEffect(() => { dismissRef.current = dismiss; }, [dismiss]);
+    // Same ref pattern for the whole-field applier — captured here so the
+    // applier closure registered below stays stable across re-renders without
+    // re-registering on every option change.
+    const onApplyWholeFieldRef = useRef(options.onApplyWholeField);
+    useEffect(() => { onApplyWholeFieldRef.current = options.onApplyWholeField; }, [options.onApplyWholeField]);
+    const synthesizeRangeRef = useRef(options.synthesizeWholeFieldRange);
+    useEffect(() => { synthesizeRangeRef.current = options.synthesizeWholeFieldRange; }, [options.synthesizeWholeFieldRange]);
     // Set of ids this hook pushed; used by both directions for cycle control.
     const pushedRef = useRef(new Set());
+    // Subset of `pushedRef` whose range was synthesized (no producer-supplied
+    // `meta.editorRange`). Approving these must NOT route through the chip's
+    // plain-text replace — that would clobber HTML / markdown formatting on
+    // rich editors. Instead the applier delegates to `onApplyWholeField`,
+    // which sets content via the renderer's content-shape-aware command
+    // (`setContent(plainTextToDoc(...))` / `setContent(markdownSrc)` /
+    // `setContent(html)`), then clears the chip without a doc edit.
+    const synthesizedRef = useRef(new Set());
     // Context → editor.
     useEffect(() => {
         if (!editor)
@@ -40,9 +33,25 @@ export function useAiSuggestionBridge(editor, fieldName) {
             if (pushedRef.current.has(s.id))
                 continue;
             const meta = (s.meta ?? {});
-            const range = meta['editorRange'];
-            if (!range || typeof range.from !== 'number' || typeof range.to !== 'number')
-                continue;
+            const rawRange = meta['editorRange'];
+            let range;
+            let isSynthesized = false;
+            if (rawRange && typeof rawRange.from === 'number' && typeof rawRange.to === 'number') {
+                range = { from: rawRange.from, to: rawRange.to };
+            }
+            else {
+                // Producer didn't supply a range — let the renderer synthesize one
+                // so the inline-diff chip widget can still render. Renderers that
+                // can't safely round-trip a plain-text replace (richtext/markdown
+                // losing formatting on approve) STILL benefit by synthesizing for
+                // visualization — the applier below routes Approve through
+                // `onApplyWholeField` for synthesized ids instead of the chip's
+                // text-node replace.
+                range = synthesizeRangeRef.current?.(editor, s);
+                if (!range)
+                    continue;
+                isSynthesized = true;
+            }
             const replacement = typeof s.suggestedValue === 'string' ? s.suggestedValue : '';
             editor.commands.addAiSuggestion({
                 id: s.id,
@@ -52,6 +61,8 @@ export function useAiSuggestionBridge(editor, fieldName) {
                 ...(s.source ? { source: s.source } : {}),
             });
             pushedRef.current.add(s.id);
+            if (isSynthesized)
+                synthesizedRef.current.add(s.id);
         }
         for (const id of Array.from(pushedRef.current)) {
             if (contextIds.has(id))
@@ -60,6 +71,7 @@ export function useAiSuggestionBridge(editor, fieldName) {
             // mutating the doc (rejectAiSuggestion drops state only).
             editor.commands.rejectAiSuggestion(id);
             pushedRef.current.delete(id);
+            synthesizedRef.current.delete(id);
         }
     }, [editor, list]);
     // Editor → context.
@@ -92,13 +104,32 @@ export function useAiSuggestionBridge(editor, fieldName) {
         if (!editor)
             return;
         const applier = (suggestion) => {
-            // Bail when the suggestion isn't one of ours (no editor range or
-            // bridge-pushed entry). Pro provider falls back to plain dismiss.
-            if (!pushedRef.current.has(suggestion.id))
+            const apply = onApplyWholeFieldRef.current;
+            const hasSynthesized = synthesizedRef.current.has(suggestion.id);
+            const hasPushed = pushedRef.current.has(suggestion.id);
+            // Synthesized whole-field range — the chip rendered for visualization,
+            // but routing Approve through the editor's `approveAiSuggestion` would
+            // do a plain-text replace and clobber HTML / markdown formatting.
+            // Delegate to the renderer-supplied applier (content-shape-aware)
+            // and clear the chip state without a doc edit.
+            if (hasSynthesized && apply && typeof suggestion.suggestedValue === 'string') {
+                apply(suggestion.suggestedValue);
+                editor.commands.rejectAiSuggestion(suggestion.id);
                 return;
-            editor.chain().focus().approveAiSuggestion(suggestion.id).run();
-            // The transaction listener above sees the editor state drop the id
-            // and calls `dismiss(id)` on its own — no manual mirror needed.
+            }
+            // Producer-supplied editor range — surgical edit. Forward Approve to
+            // the editor command; the transaction listener above mirrors the
+            // dismiss back into context.
+            if (hasPushed) {
+                editor.chain().focus().approveAiSuggestion(suggestion.id).run();
+                return;
+            }
+            // Whole-field path WITHOUT visualization — producer skipped the range
+            // and the renderer didn't synthesize. Same applier as above, no chip
+            // to clear. Context's `approve()` dismisses the queue entry.
+            if (apply && typeof suggestion.suggestedValue === 'string') {
+                apply(suggestion.suggestedValue);
+            }
         };
         // Editor renderers don't currently have access to a `formId` here;
         // pass `undefined` so the wildcard form scope resolves. Phase 8.5+

package/dist/react/useAiSuggestionBridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAiSuggestionBridge.js","sourceRoot":"","sources":["../../src/react/useAiSuggestionBridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useAiSuggestionBridge.js","sourceRoot":"","sources":["../../src/react/useAiSuggestionBridge.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/tiptap",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Tiptap rich-text editor adapter for @pilotiq/pilotiq — slash menu, draggable blocks, custom-block API",
   "license": "MIT",
   "repository": {
@@ -81,12 +81,12 @@
     "react": "^19",
     "react-dom": "^19",
     "typescript": "^5",
-    "@pilotiq/pilotiq": "^0.18.0"
+    "@pilotiq/pilotiq": "^0.19.0"
   },
   "author": "Suleiman Shahbari",
   "scripts": {
     "build": "tsc -p tsconfig.build.json && pnpm run bundle:markdown",
-    "bundle:markdown": "esbuild src/markdownExtension.ts --bundle --format=esm --outfile=dist/markdownExtension.js --external:@tiptap/* --sourcemap",
+    "bundle:markdown": "esbuild src/markdownExtension.ts --bundle --format=esm --outfile=dist/markdownExtension.js --external:@tiptap/* && rm -f dist/markdownExtension.js.map",
     "dev": "tsc -p tsconfig.build.json --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src",

package/src/extensions/AiSuggestionExtension.ts

@@ -170,6 +170,62 @@ export const AiSuggestionExtension = Extension.create<AiSuggestionExtensionOptio
     }
   },
 
+  onCreate() {
+    // Inject minimal default styles for the chip + strikethrough on first
+    // mount so consumers see the visualization without wiring CSS. Idempotent
+    // via the `data-pilotiq-ai-suggestion-styles` sentinel; consumers who
+    // want full control just add their own `<style>` with the same class
+    // names (last wins — the cascade picks user overrides over our defaults
+    // since the user stylesheet appears AFTER our injected one in `<head>`
+    // when imported via Vite/Webpack, OR via higher specificity).
+    if (typeof document === 'undefined') return
+    const SENTINEL = 'data-pilotiq-ai-suggestion-styles'
+    if (document.head.querySelector(`style[${SENTINEL}]`)) return
+    const prefix = this.options.classPrefix
+    const style  = document.createElement('style')
+    style.setAttribute(SENTINEL, '')
+    // Colors picked to look right on light + dark surfaces without theme
+    // overrides (60% alpha on background-color, 100% on text). Tuned to
+    // match the inline-diff convention used by the Tiptap Pro AI Agent.
+    style.textContent = `
+      .${prefix}-original {
+        text-decoration: line-through;
+        text-decoration-color: rgba(220, 38, 38, 0.7);
+        background-color: rgba(254, 226, 226, 0.6);
+        color: rgb(153, 27, 27);
+      }
+      .${prefix}-chip {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.25rem;
+        margin-left: 0.25rem;
+        padding: 0 0.25rem;
+        border-radius: 0.25rem;
+        background-color: rgba(220, 252, 231, 0.7);
+        color: rgb(22, 101, 52);
+        font-size: 0.875em;
+        line-height: 1.4;
+      }
+      .${prefix}-replacement {
+        padding: 0 0.125rem;
+      }
+      .${prefix}-accept,
+      .${prefix}-reject {
+        appearance: none;
+        background: transparent;
+        border: 0;
+        padding: 0 0.25rem;
+        cursor: pointer;
+        font-size: 0.875em;
+        line-height: 1;
+        color: inherit;
+      }
+      .${prefix}-accept:hover { color: rgb(21, 128, 61); }
+      .${prefix}-reject:hover { color: rgb(185, 28, 28); }
+    `
+    document.head.appendChild(style)
+  },
+
   addCommands() {
     return {
       addAiSuggestion: (suggestion) => ({ tr, state, dispatch }) => {

package/src/react/CollabTextRenderer.tsx

@@ -66,32 +66,47 @@ export function CollabTextRenderer({
   }, [collabActive])
 
   const editor = useEditor(
-    createPlainTextEditor({
-      multiline,
-      ...(placeholder !== undefined ? { placeholder } : {}),
-      editable: !disabled,
-      // When Collaboration owns the doc, omit `content` so the editor
-      // doesn't race the y-prosemirror sync. The post-`synced` effect below
-      // seeds the fragment on first connect when it's still empty. When
-      // collab is off, seed from defaultValue directly.
-      content: collabActive ? '' : defaultValue,
-      // AI suggestions — always-on extension that tracks suggested edits as
-      // inline strikethrough + Approve/Reject chip widgets. Idle until the
-      // host calls `editor.commands.addAiSuggestion(...)` via the bridge below.
-      // Matches the `TiptapEditor` wiring so suggestion mode works uniformly
-      // across RichTextField / MarkdownField / TextField+TextareaField.
-      extensions: [...collabExtensions, AiSuggestionExtension],
-      onUpdate: (text) => onChange(text),
-      ...(onSubmit ? { onSubmit: () => { onSubmit(); return false } } : {}),
-      ...(className || editorAttributes
-        ? {
-            editorAttributes: {
-              ...(editorAttributes ?? {}),
-              ...(className ? { class: className } : {}),
-            },
-          }
-        : {}),
-    }),
+    {
+      // Tiptap v3 SSR guard. With `immediatelyRender: true` (default)
+      // `useEditor` touches the DOM during construction; under Vike's
+      // `onRenderHtml` that throws "SSR has been detected, please set
+      // `immediatelyRender` explicitly to `false` to avoid hydration
+      // mismatches." Deferring until the first React effect lets SSR
+      // produce an empty shell + hydration mount the live editor.
+      //
+      // Load-bearing for the AI-attached auto-upgrade path: with rule
+      // #2, AI fields render the Tiptap surface during SSR (where
+      // `useCollabRoom()` is null but `aiActions.length > 0` flips the
+      // host's gate). Without this flag the dev server would crash on
+      // the first SSR pass of any record-edit page touching AI fields.
+      immediatelyRender: false,
+      ...createPlainTextEditor({
+        multiline,
+        ...(placeholder !== undefined ? { placeholder } : {}),
+        editable: !disabled,
+        // When Collaboration owns the doc, omit `content` so the editor
+        // doesn't race the y-prosemirror sync. The post-`synced` effect below
+        // seeds the fragment on first connect when it's still empty. When
+        // collab is off, seed from defaultValue directly.
+        content: collabActive ? '' : defaultValue,
+        // AI suggestions — always-on extension that tracks suggested edits as
+        // inline strikethrough + Approve/Reject chip widgets. Idle until the
+        // host calls `editor.commands.addAiSuggestion(...)` via the bridge below.
+        // Matches the `TiptapEditor` wiring so suggestion mode works uniformly
+        // across RichTextField / MarkdownField / TextField+TextareaField.
+        extensions: [...collabExtensions, AiSuggestionExtension],
+        onUpdate: (text) => onChange(text),
+        ...(onSubmit ? { onSubmit: () => { onSubmit(); return false } } : {}),
+        ...(className || editorAttributes
+          ? {
+              editorAttributes: {
+                ...(editorAttributes ?? {}),
+                ...(className ? { class: className } : {}),
+              },
+            }
+          : {}),
+      }),
+    },
     // Re-mount when collab toggles. Other props (multiline, name, etc) are
     // stable per mount under the upstream gate.
     [collabActive],
@@ -107,7 +122,26 @@ export function CollabTextRenderer({
   // Cross-package suggestion bridge — sync the host's
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
-  useAiSuggestionBridge(editor ?? null, name)
+  //
+  // Whole-field fallback: chat-driven suggestions (e.g. `update_form_state`)
+  // arrive without `meta.editorRange`. Plain-text editors opt into a
+  // synthesized full-doc range so the inline-diff chip (red strikethrough on
+  // the current value + green chip with the suggested text + ✓/✕ buttons)
+  // renders BEFORE the user approves. The extension's `applyApprove` is
+  // text-node-based which fits the plain-text schema exactly. The
+  // `onApplyWholeField` callback stays as a fallback for cases that don't
+  // synthesize (e.g. an empty doc — `from === to` skips the chip but the
+  // applier still needs to swap content).
+  useAiSuggestionBridge(editor ?? null, name, {
+    synthesizeWholeFieldRange: (ed) => ({
+      from: 0,
+      to:   ed.state.doc.content.size,
+    }),
+    onApplyWholeField: (value) => {
+      if (!editor || editor.isDestroyed) return
+      editor.commands.setContent(plainTextToDoc(value, !!multiline))
+    },
+  })
 
   // First-load seed when collab is active. Collaboration starts the editor
   // empty regardless of `defaultValue`; once the provider syncs the room

package/src/react/MarkdownEditor.tsx

@@ -247,7 +247,24 @@ export function MarkdownEditor({
   // Cross-package suggestion bridge — sync the host's
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
-  useAiSuggestionBridge(editor ?? null, name)
+  //
+  // Whole-field handling for chat-driven suggestions (e.g.
+  // `update_form_state`). The chip widget renders inline for visualization
+  // (synthesized range over the whole doc), but Approve routes through
+  // `onApplyWholeField` so the new markdown source parses correctly via
+  // the Markdown extension — the chip's plain-text replace would lose
+  // headings, lists, formatting.
+  useAiSuggestionBridge(editor ?? null, name, {
+    synthesizeWholeFieldRange: (ed) => ({
+      from: 0,
+      to:   ed.state.doc.content.size,
+    }),
+    onApplyWholeField: (value) => {
+      if (!editor || editor.isDestroyed) return
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ;(editor.commands as any).setContent(value)
+    },
+  })
 
   // First-load seed for collab. Collaboration starts the editor empty
   // regardless of `content`; once the provider syncs from the server we

package/src/react/TiptapEditor.tsx

@@ -463,7 +463,23 @@ function ClientEditor(props: ClientEditorProps) {
   // Cross-package suggestion bridge — sync the host's
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
-  useAiSuggestionBridge(editor ?? null, name)
+  //
+  // Whole-field handling: rare for RichTextField (chat-driven flows usually
+  // emit range-anchored suggestions for richtext), but `update_form_state`
+  // can still arrive with `set_value` on a rich field. The chip widget
+  // renders over the whole doc for visualization; Approve routes through
+  // `onApplyWholeField` so `setContent` parses the new HTML / JSON
+  // correctly — the chip's plain-text replace would lose all formatting.
+  useAiSuggestionBridge(editor ?? null, name, {
+    synthesizeWholeFieldRange: (ed) => ({
+      from: 0,
+      to:   ed.state.doc.content.size,
+    }),
+    onApplyWholeField: (value) => {
+      if (!editor || editor.isDestroyed) return
+      editor.commands.setContent(value)
+    },
+  })
 
   // Re-render the toolbar when the selection / marks change so active-state
   // booleans stay fresh.

package/src/react/useAiSuggestionBridge.ts

@@ -29,8 +29,50 @@ import { aiSuggestionPluginKey } from '../extensions/AiSuggestionExtension.js'
  * hook had previously pushed (so an id added directly by host code via
  * `editor.commands.addAiSuggestion(...)` doesn't get reflected back through
  * a context that never knew about it).
+ *
+ * **Whole-field fallback** (chat-driven suggestions). Producers like
+ * `@pilotiq-pro/ai`'s `update_form_state` tool push suggestions that target
+ * the whole field — no `meta.editorRange`, just `suggestedValue` as a string.
+ * Without `editorRange` the bridge can't render the inline-diff chip widget
+ * (it has nowhere to anchor), so the host renderer passes an
+ * `onApplyWholeField(value)` callback. When the chat-sidebar Approve fires
+ * for a non-bridge-pushed id, the registered applier calls this callback
+ * instead of no-op'ing — letting each renderer apply the suggestion the
+ * right way for its shape (plain text → `plainTextToDoc`, markdown → set
+ * markdown source, richtext → setContent with HTML/JSON). The host is also
+ * responsible for the Approve UI — FieldShell hides its legacy overlay
+ * whenever a Tiptap renderer is mounted (richtext / markdown / collab text).
  */
-export function useAiSuggestionBridge(editor: Editor | null, fieldName: string): void {
+export interface UseAiSuggestionBridgeOptions {
+  /**
+   * Apply a whole-field suggestion that lacks `meta.editorRange`. Each
+   * Tiptap renderer passes its own implementation (different content
+   * shapes — plain text, markdown source, HTML/JSON). Omit for editors
+   * that should ignore whole-field suggestions entirely.
+   */
+  onApplyWholeField?: (suggestedValue: string) => void
+
+  /**
+   * Synthesize a `{ from, to }` range for whole-field suggestions so the
+   * inline-diff chip widget can render BEFORE the user approves. The
+   * extension's `applyApprove` inserts a plain text node spanning the
+   * synthesized range — safe only for editors whose schema accepts a
+   * text-node replacement covering the whole doc (CollabTextRenderer's
+   * plain-text schema fits; richtext / markdown lose formatting if
+   * approved that way). Return `undefined` to skip synthesis and fall
+   * through to the legacy `onApplyWholeField` callback (silent swap).
+   */
+  synthesizeWholeFieldRange?: (
+    editor:     Editor,
+    suggestion: PendingSuggestion,
+  ) => { from: number; to: number } | undefined
+}
+
+export function useAiSuggestionBridge(
+  editor: Editor | null,
+  fieldName: string,
+  options: UseAiSuggestionBridgeOptions = {},
+): void {
   const { list, dismiss } = usePendingSuggestionsForField(fieldName)
 
   // Hold the latest `dismiss` in a ref so the editor-side listener — which
@@ -38,8 +80,24 @@ export function useAiSuggestionBridge(editor: Editor | null, fieldName: string):
   const dismissRef = useRef(dismiss)
   useEffect(() => { dismissRef.current = dismiss }, [dismiss])
 
+  // Same ref pattern for the whole-field applier — captured here so the
+  // applier closure registered below stays stable across re-renders without
+  // re-registering on every option change.
+  const onApplyWholeFieldRef = useRef(options.onApplyWholeField)
+  useEffect(() => { onApplyWholeFieldRef.current = options.onApplyWholeField }, [options.onApplyWholeField])
+  const synthesizeRangeRef = useRef(options.synthesizeWholeFieldRange)
+  useEffect(() => { synthesizeRangeRef.current = options.synthesizeWholeFieldRange }, [options.synthesizeWholeFieldRange])
+
   // Set of ids this hook pushed; used by both directions for cycle control.
   const pushedRef = useRef<Set<string>>(new Set())
+  // Subset of `pushedRef` whose range was synthesized (no producer-supplied
+  // `meta.editorRange`). Approving these must NOT route through the chip's
+  // plain-text replace — that would clobber HTML / markdown formatting on
+  // rich editors. Instead the applier delegates to `onApplyWholeField`,
+  // which sets content via the renderer's content-shape-aware command
+  // (`setContent(plainTextToDoc(...))` / `setContent(markdownSrc)` /
+  // `setContent(html)`), then clears the chip without a doc edit.
+  const synthesizedRef = useRef<Set<string>>(new Set())
 
   // Context → editor.
   useEffect(() => {
@@ -49,8 +107,23 @@ export function useAiSuggestionBridge(editor: Editor | null, fieldName: string):
     for (const s of list) {
       if (pushedRef.current.has(s.id)) continue
       const meta = (s.meta ?? {}) as Record<string, unknown>
-      const range = meta['editorRange'] as { from?: unknown; to?: unknown } | undefined
-      if (!range || typeof range.from !== 'number' || typeof range.to !== 'number') continue
+      const rawRange = meta['editorRange'] as { from?: unknown; to?: unknown } | undefined
+      let range: { from: number; to: number } | undefined
+      let isSynthesized = false
+      if (rawRange && typeof rawRange.from === 'number' && typeof rawRange.to === 'number') {
+        range = { from: rawRange.from, to: rawRange.to }
+      } else {
+        // Producer didn't supply a range — let the renderer synthesize one
+        // so the inline-diff chip widget can still render. Renderers that
+        // can't safely round-trip a plain-text replace (richtext/markdown
+        // losing formatting on approve) STILL benefit by synthesizing for
+        // visualization — the applier below routes Approve through
+        // `onApplyWholeField` for synthesized ids instead of the chip's
+        // text-node replace.
+        range = synthesizeRangeRef.current?.(editor, s)
+        if (!range) continue
+        isSynthesized = true
+      }
       const replacement = typeof s.suggestedValue === 'string' ? s.suggestedValue : ''
       editor.commands.addAiSuggestion({
         id:          s.id,
@@ -60,6 +133,7 @@ export function useAiSuggestionBridge(editor: Editor | null, fieldName: string):
         ...(s.source ? { source: s.source } : {}),
       })
       pushedRef.current.add(s.id)
+      if (isSynthesized) synthesizedRef.current.add(s.id)
     }
 
     for (const id of Array.from(pushedRef.current)) {
@@ -68,6 +142,7 @@ export function useAiSuggestionBridge(editor: Editor | null, fieldName: string):
       // mutating the doc (rejectAiSuggestion drops state only).
       editor.commands.rejectAiSuggestion(id)
       pushedRef.current.delete(id)
+      synthesizedRef.current.delete(id)
     }
   }, [editor, list])
 
@@ -98,12 +173,33 @@ export function useAiSuggestionBridge(editor: Editor | null, fieldName: string):
   useEffect(() => {
     if (!editor) return
     const applier: PendingSuggestionApplier = (suggestion) => {
-      // Bail when the suggestion isn't one of ours (no editor range or
-      // bridge-pushed entry). Pro provider falls back to plain dismiss.
-      if (!pushedRef.current.has(suggestion.id)) return
-      editor.chain().focus().approveAiSuggestion(suggestion.id).run()
-      // The transaction listener above sees the editor state drop the id
-      // and calls `dismiss(id)` on its own — no manual mirror needed.
+      const apply = onApplyWholeFieldRef.current
+      const hasSynthesized = synthesizedRef.current.has(suggestion.id)
+      const hasPushed      = pushedRef.current.has(suggestion.id)
+
+      // Synthesized whole-field range — the chip rendered for visualization,
+      // but routing Approve through the editor's `approveAiSuggestion` would
+      // do a plain-text replace and clobber HTML / markdown formatting.
+      // Delegate to the renderer-supplied applier (content-shape-aware)
+      // and clear the chip state without a doc edit.
+      if (hasSynthesized && apply && typeof suggestion.suggestedValue === 'string') {
+        apply(suggestion.suggestedValue)
+        editor.commands.rejectAiSuggestion(suggestion.id)
+        return
+      }
+      // Producer-supplied editor range — surgical edit. Forward Approve to
+      // the editor command; the transaction listener above mirrors the
+      // dismiss back into context.
+      if (hasPushed) {
+        editor.chain().focus().approveAiSuggestion(suggestion.id).run()
+        return
+      }
+      // Whole-field path WITHOUT visualization — producer skipped the range
+      // and the renderer didn't synthesize. Same applier as above, no chip
+      // to clear. Context's `approve()` dismisses the queue entry.
+      if (apply && typeof suggestion.suggestedValue === 'string') {
+        apply(suggestion.suggestedValue)
+      }
     }
     // Editor renderers don't currently have access to a `formId` here;
     // pass `undefined` so the wildcard form scope resolves. Phase 8.5+