@pilotiq/tiptap 3.4.0 → 3.6.0

package/src/react/MarkdownEditor.tsx

@@ -4,6 +4,7 @@ import type { AnyExtension } from '@tiptap/core'
 import StarterKit from '@tiptap/starter-kit'
 import Placeholder from '@tiptap/extension-placeholder'
 import Image from '@tiptap/extension-image'
+import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model'
 // The `tiptap-markdown` chain (incl. CJS-only `markdown-it-task-lists`) is
 // pre-bundled into `dist/markdownExtension.js` at @pilotiq/tiptap build
 // time; importing the wrapper instead of `tiptap-markdown` directly
@@ -17,7 +18,10 @@ import {
   type MarkdownEditorProps,
 } from '@pilotiq/pilotiq/react'
 import { AiSuggestionExtension } from '../extensions/AiSuggestionExtension.js'
+import { AiInlineDiffExtension, aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js'
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
+import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js'
+import { AiSuggestionBanner } from './AiSuggestionBanner.js'
 
 // Inline lucide.dev SVGs — same posture as `toolbarButtons.tsx` so this
 // package doesn't pull `lucide-react` as a peer dep. Keep stroke / size
@@ -214,12 +218,14 @@ export function MarkdownEditor({
         }),
         Image.configure({ inline: false, allowBase64: false }),
         Placeholder.configure({ placeholder: placeholder ?? 'Write in markdown…' }),
-        // 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.
+        // AI suggestions — chip widget for surgical (range-anchored) edits.
         AiSuggestionExtension,
+        // AI inline diff — Tiptap-Pro-style visualization for whole-field
+        // suggestions (prosemirror-changeset under the hood). Decorations
+        // show green-background inserts inline + red-strikethrough widgets
+        // for deleted text. Host's `<AiSuggestionBanner>` drives Accept /
+        // Reject via the extension's commands.
+        AiInlineDiffExtension,
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         ...(collabExtensions as any[]),
       ],
@@ -247,7 +253,47 @@ 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: NO chip widget here. The chip's `textContent`
+  // renderer surfaces raw markdown (`## Heading\n- item`) as literal text
+  // inside the green pill — visually unparseable for multi-paragraph
+  // rewrites. Instead, `<AiSuggestionBanner>` mounts above the editor
+  // (see render below). Producer-supplied range suggestions still ride
+  // the inline chip path — those have a precise anchor worth showing
+  // in context.
+  const applyWholeField = (value: string): void => {
+    if (!editor || editor.isDestroyed) return
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(editor.commands as any).setContent(value)
+  }
+  useAiSuggestionBridge(editor ?? null, name, {
+    onApplyWholeField: applyWholeField,
+  })
+
+  // Inline diff for whole-field suggestions — replaces the editor doc with
+  // the proposed markdown so the user sees the structural diff (inserted
+  // headings / list items / etc.) before approving. Pipeline:
+  //   1. tiptap-markdown's parser turns the source into HTML
+  //      (`editor.storage.markdown.parser.parse(value)` returns a string).
+  //   2. ProseMirror's `DOMParser.fromSchema(schema).parseSlice(...)` turns
+  //      that HTML into a Slice against THIS editor's schema — same path
+  //      the editor's own clipboard-paste uses, so the slice is guaranteed
+  //      schema-valid.
+  useAiInlineDiff(editor ?? null, name, {
+    parseSuggestion: (ed, value) => {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const parser = (ed.storage as any).markdown?.parser
+        if (!parser || typeof parser.parse !== 'function') return null
+        const html = parser.parse(value)
+        if (typeof html !== 'string') return null
+        const container = document.createElement('div')
+        container.innerHTML = html
+        return ProseMirrorDOMParser.fromSchema(ed.schema).parseSlice(container)
+      } catch { return null }
+    },
+  })
+  const isDiffActive = useIsAiInlineDiffActive(editor ?? null)
 
   // First-load seed for collab. Collaboration starts the editor empty
   // regardless of `content`; once the provider syncs from the server we
@@ -417,6 +463,16 @@ export function MarkdownEditor({
 
   return (
     <div className="flex flex-col rounded-md border bg-background">
+      <AiSuggestionBanner
+        fieldName={name}
+        onApplyWholeField={applyWholeField}
+        {...(isDiffActive && editor
+          ? {
+              onAcceptViaEditor: () => editor.commands.acceptAiInlineDiff(),
+              onRejectViaEditor: () => editor.commands.rejectAiInlineDiff(),
+            }
+          : {})}
+      />
       {canAttach && (
         <input
           ref={fileInputRef}

package/src/react/TiptapEditor.tsx

@@ -20,6 +20,9 @@ import type {
 } from '@pilotiq/pilotiq/react'
 import { useCollabRoom, getCollabExtensions, onProviderSynced } from '@pilotiq/pilotiq/react'
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
+import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js'
+import { AiSuggestionBanner } from './AiSuggestionBanner.js'
+import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model'
 import type { BlockMeta } from '../Block.js'
 import type { ToolbarGroups, RichTextStorage, ColorSwatch } from '../RichTextField.js'
 import { BlockNodeExtension } from '../extensions/BlockNodeExtension.js'
@@ -31,6 +34,7 @@ import { DragHandleExtension } from '../extensions/DragHandleExtension.js'
 import { MergeTagExtension } from '../extensions/MergeTagExtension.js'
 import { LeadMarkExtension, SmallMarkExtension } from '../extensions/TextSizeMarks.js'
 import { AiSuggestionExtension } from '../extensions/AiSuggestionExtension.js'
+import { AiInlineDiffExtension } from '../extensions/AiInlineDiffExtension.js'
 import {
   MentionExtension,
   type MentionState,
@@ -315,10 +319,11 @@ function ClientEditor(props: ClientEditorProps) {
         fieldName:     name,
       })] : [MentionExtension]),
       DragHandleExtension,
-      // AI suggestions — always-on extension that tracks suggested edits as
-      // inline strikethrough + Approve/Reject chip widgets. Idle until the
-      // host calls `editor.commands.addAiSuggestion(...)`.
+      // AI suggestions — chip widget for surgical (range-anchored) edits.
       AiSuggestionExtension,
+      // AI inline diff — Tiptap-Pro-style visualization for whole-field
+      // suggestions via prosemirror-changeset. See AiInlineDiffExtension.
+      AiInlineDiffExtension,
       // Realtime-collab extensions (Yjs `Collaboration` + cursor) — empty
       // when no `<RecordCollabRoom>` is mounted up-tree, or when no plugin
       // registered a factory via `registerCollabExtensions`.
@@ -463,7 +468,36 @@ 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: NO chip widget here. The chip's `textContent`
+  // renderer would surface raw HTML tags as literal text inside the
+  // green pill — unparseable on multi-paragraph rewrites. Instead,
+  // `<AiSuggestionBanner>` mounts above the editor (see render below).
+  // Producer-supplied range suggestions still ride the inline chip —
+  // those have a precise anchor worth visualizing in context.
+  const applyWholeField = (value: string): void => {
+    if (!editor || editor.isDestroyed) return
+    editor.commands.setContent(value)
+  }
+  useAiSuggestionBridge(editor ?? null, name, {
+    onApplyWholeField: applyWholeField,
+  })
+
+  // Inline diff for whole-field suggestions. Pipeline mirrors MarkdownEditor:
+  // HTML → ProseMirror Slice via the schema's DOMParser. Suggested values
+  // on a RichTextField are typically HTML (or marked-up JSON that the
+  // schema's DOMParser also handles via its serialized round-trip). For
+  // JSON suggestions, the schema may reject — falls back to banner-only.
+  useAiInlineDiff(editor ?? null, name, {
+    parseSuggestion: (ed, value) => {
+      try {
+        const container = document.createElement('div')
+        container.innerHTML = value
+        return ProseMirrorDOMParser.fromSchema(ed.schema).parseSlice(container)
+      } catch { return null }
+    },
+  })
+  const isDiffActive = useIsAiInlineDiffActive(editor ?? null)
 
   // Re-render the toolbar when the selection / marks change so active-state
   // booleans stay fresh.
@@ -472,6 +506,16 @@ function ClientEditor(props: ClientEditorProps) {
   return (
     <div className="relative flex flex-col">
       <input type="hidden" name={name} value={serialized} />
+      <AiSuggestionBanner
+        fieldName={name}
+        onApplyWholeField={applyWholeField}
+        {...(isDiffActive && editor
+          ? {
+              onAcceptViaEditor: () => editor.commands.acceptAiInlineDiff(),
+              onRejectViaEditor: () => editor.commands.rejectAiInlineDiff(),
+            }
+          : {})}
+      />
       {editor && toolbarGroups && toolbarGroups.length > 0 && (
         <Toolbar
           editor={editor}

package/src/react/useAiInlineDiff.ts

@@ -0,0 +1,146 @@
+/**
+ * Bridge between the host's `<PendingSuggestionsContext>` queue and the
+ * editor's `AiInlineDiffExtension`. When a whole-field suggestion arrives
+ * for the field, the hook:
+ *
+ *   1. Parses the suggested value into a ProseMirror `Slice` via the
+ *      renderer-supplied parser. Each Tiptap surface owns its own
+ *      content shape — markdown source for `MarkdownEditor`, HTML / JSON
+ *      for `TiptapEditor`, plain text for `CollabTextRenderer`.
+ *   2. Calls `editor.commands.startAiInlineDiff(id, slice)` — the
+ *      extension snapshots the current doc as the baseline, replaces
+ *      the doc content with the proposed slice, and starts a
+ *      `prosemirror-changeset` tracking the diff.
+ *   3. Registers an applier on the cross-tree pending-suggestion
+ *      registry so the host's `<AiSuggestionBanner>` Accept button (and
+ *      any other surface calling `pendingSuggestions.approve(id)`) runs
+ *      `acceptAiInlineDiff()` instead of the legacy `onApplyWholeField`
+ *      callback. The current doc IS the accepted state — no extra
+ *      content swap needed.
+ *
+ * Reject handling: not registered on the applier (the registry only
+ * tracks Approve). Renderers wire Reject through the banner's
+ * `onRejectWithEditor` prop, which calls `rejectAiInlineDiff()` to revert
+ * the doc to the baseline before dismissing the suggestion.
+ *
+ * Defensive: only one inline diff active at a time per editor. If a new
+ * synthesized suggestion arrives while one is still pending review, the
+ * hook drops it (the producer should have waited). This matches
+ * `AiSuggestionExtension`'s chip path which also allows only one
+ * suggestion at a time per id.
+ */
+
+import { useEffect, useRef } from 'react'
+import type { Editor } from '@tiptap/core'
+import type { Slice } from '@tiptap/pm/model'
+import {
+  registerPendingSuggestionApplier,
+  usePendingSuggestionsForField,
+  type PendingSuggestion,
+  type PendingSuggestionApplier,
+} from '@pilotiq/pilotiq/react'
+import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js'
+
+export interface UseAiInlineDiffOptions {
+  /**
+   * Parse the suggested string value into a ProseMirror Slice that's
+   * compatible with this editor's schema. Returns `null` to skip (e.g.
+   * malformed content, unsupported markup) — the suggestion stays in
+   * the queue but no diff renders, and the host's fallback path (banner
+   * with `onApplyWholeField`) takes over.
+   *
+   * Renderers implement this per content shape:
+   *   - plain text → wrap each line in a `paragraph` node
+   *   - markdown   → run through the Markdown extension's parseMarkdown
+   *   - HTML       → DOMParser + ProseMirror's DOMParser.parse
+   */
+  parseSuggestion: (editor: Editor, value: string) => Slice | null
+}
+
+/**
+ * Returns whether a diff is currently active in the editor. Hosts use
+ * this to gate the banner's UI between the legacy `onApplyWholeField`
+ * mode and the diff-aware mode (Reject routes through
+ * `rejectAiInlineDiff` to revert the doc).
+ */
+export function useIsAiInlineDiffActive(editor: Editor | null): boolean {
+  // Re-render on every editor transaction so the hook tracks state
+  // changes (start / accept / reject). useEditorState would be the
+  // idiomatic way; we read directly here to keep the dep surface tiny.
+  const [, force] = useReducerForceUpdate()
+  useEffect(() => {
+    if (!editor) return
+    const handler = () => force()
+    editor.on('transaction', handler)
+    return () => { editor.off('transaction', handler) }
+  }, [editor, force])
+  if (!editor) return false
+  return aiInlineDiffPluginKey.getState(editor.state) !== null
+}
+
+export function useAiInlineDiff(
+  editor: Editor | null,
+  fieldName: string,
+  options: UseAiInlineDiffOptions,
+): void {
+  const { list } = usePendingSuggestionsForField(fieldName)
+
+  const parseRef = useRef(options.parseSuggestion)
+  useEffect(() => { parseRef.current = options.parseSuggestion }, [options.parseSuggestion])
+
+  // Track which ids we've handed off to the editor's diff extension
+  // so we don't re-start the diff every render or for already-active
+  // suggestions.
+  const startedRef = useRef<Set<string>>(new Set())
+
+  // Context → editor: start the diff for each new whole-field suggestion.
+  useEffect(() => {
+    if (!editor) return
+    const wholeField = list.filter(s => !hasEditorRange(s))
+    for (const s of wholeField) {
+      if (startedRef.current.has(s.id)) continue
+      if (typeof s.suggestedValue !== 'string') continue
+      // Bail when a different diff is already showing — one at a time.
+      // Producer should serialize calls; if not, the second suggestion
+      // sits in the queue until the first is approved/rejected.
+      if (aiInlineDiffPluginKey.getState(editor.state) !== null) continue
+      const slice = parseRef.current(editor, s.suggestedValue)
+      if (!slice) continue
+      editor.commands.startAiInlineDiff(s.id, slice)
+      startedRef.current.add(s.id)
+    }
+    // Cleanup: when a suggestion leaves the context AND we previously
+    // started a diff for it, the editor should drop the diff state too.
+    // Approve dismisses via context → here we drop from startedRef.
+    const contextIds = new Set(list.map(s => s.id))
+    for (const id of Array.from(startedRef.current)) {
+      if (!contextIds.has(id)) startedRef.current.delete(id)
+    }
+  }, [editor, list])
+
+  // Cross-tree applier — when the banner / chat-sidebar pill calls
+  // `pendingSuggestions.approve(id)` for one of our tracked suggestions,
+  // accept the diff. Editor is the source of truth for the new doc.
+  useEffect(() => {
+    if (!editor) return
+    const applier: PendingSuggestionApplier = (suggestion) => {
+      if (!startedRef.current.has(suggestion.id)) return
+      editor.commands.acceptAiInlineDiff()
+    }
+    return registerPendingSuggestionApplier(undefined, fieldName, applier)
+  }, [editor, fieldName])
+}
+
+function hasEditorRange(s: PendingSuggestion): boolean {
+  const meta = (s.meta ?? {}) as Record<string, unknown>
+  const range = meta['editorRange'] as { from?: unknown; to?: unknown } | undefined
+  return !!(range && typeof range.from === 'number' && typeof range.to === 'number')
+}
+
+// useReducer + dispatch is the smallest-API force-update primitive React
+// ships. Hoisted into a helper so the call site stays one line.
+import { useReducer } from 'react'
+function useReducerForceUpdate(): [number, () => void] {
+  const [n, inc] = useReducer((x: number) => (x + 1) | 0, 0)
+  return [n, () => inc()]
+}

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+