@pilotiq/tiptap 3.5.0 → 3.7.0

package/src/extensions/AiInlineDiffExtension.ts

@@ -0,0 +1,286 @@
+/**
+ * Inline-diff visualization for whole-field AI suggestions.
+ *
+ * Sibling to `AiSuggestionExtension`, which handles producer-supplied
+ * range suggestions (surgical edits with `meta.editorRange`) via the
+ * inline chip widget. This extension handles the *whole-field* case:
+ * the AI proposes a new document and the user reviews the structural
+ * delta (added paragraphs, deleted text, mark changes, etc.) before
+ * accepting or rejecting via the host-mounted `<AiSuggestionBanner>`.
+ *
+ * Architecture:
+ *   1. `startAiInlineDiff(id, newDoc)` captures the current doc as the
+ *      baseline, replaces the doc body with `newDoc`'s content (so the
+ *      editor surface IS the proposed state), and initializes a
+ *      `prosemirror-changeset` tracking the original-to-current
+ *      transition.
+ *   2. The plugin appendTransaction hook keeps the changeset in sync
+ *      with any further transactions while the diff is pending — e.g.
+ *      y-prosemirror remote edits arriving during review. (Rare on
+ *      whole-field flows but free.)
+ *   3. A decorations spec walks `ChangeSet.changes` and emits:
+ *        - inline green-background decorations on inserted ranges
+ *        - widget decorations rendering the *deleted* text struck
+ *          through next to the insert point (the deleted content
+ *          isn't in the current doc, so a widget is the only way to
+ *          surface it)
+ *   4. `acceptAiInlineDiff()` clears the plugin state — the current
+ *      doc is the accepted state.
+ *   5. `rejectAiInlineDiff()` replaces the doc back to the baseline
+ *      via a single transaction and clears state.
+ *
+ * For Tiptap Pro parity. See `[[project_pilotiq_text_field_tiptap_rules]]`.
+ */
+
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import type { EditorState, Transaction } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+import type { Node as ProseMirrorNode, Slice } from '@tiptap/pm/model'
+import { ChangeSet } from 'prosemirror-changeset'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    aiInlineDiff: {
+      /**
+       * Start the inline-diff review session. Snapshots the current
+       * doc as the baseline, replaces the doc with `newDocSlice`'s
+       * content, and shows the diff overlay.
+       *
+       * `id` is the host-side `PendingSuggestion.id` — used so the
+       * banner / approve handlers can correlate the editor state with
+       * the queue entry.
+       */
+      startAiInlineDiff:  (id: string, newDocSlice: Slice) => ReturnType
+      /**
+       * Start the inline-diff review session for a surgical edit.
+       * Snapshots the current doc as the baseline, then runs
+       * `applyFn(tr)` to mutate the transaction with a precise change
+       * (e.g. replace one block, insert before a position, set a mark
+       * on a range). The plugin folds the resulting steps into the
+       * changeset, so decorations land exactly on the modified ranges
+       * — no whole-doc replacement.
+       *
+       * Use this for `replace_block` / `insert_block_before` /
+       * `delete_block` / `update_block_mark` AI ops. Returns false (no
+       * dispatch) when `applyFn` produced no doc change.
+       */
+      applySurgicalAiInlineDiff: (id: string, applyFn: (tr: Transaction) => void) => ReturnType
+      /** Clear diff state. Current doc IS the accepted state. */
+      acceptAiInlineDiff: () => ReturnType
+      /** Revert doc to the captured baseline and clear diff state. */
+      rejectAiInlineDiff: () => ReturnType
+    }
+  }
+}
+
+interface DiffState {
+  id:        string
+  /** Original doc captured at `startAiInlineDiff` time — used for revert. */
+  baseline:  ProseMirrorNode
+  /** ChangeSet accumulating diffs since baseline. */
+  changeset: ChangeSet
+}
+
+export const aiInlineDiffPluginKey = new PluginKey<DiffState | null>('pilotiqAiInlineDiff')
+
+/** Read the active diff state, if any. Public for hosts that want to
+ *  branch their banner UI on "diff active" vs "diff inactive". */
+export function getAiInlineDiffState(state: EditorState): DiffState | null {
+  return aiInlineDiffPluginKey.getState(state) ?? null
+}
+
+interface StartMeta { type: 'start';  id: string; baseline: ProseMirrorNode }
+interface ClearMeta { type: 'clear' }
+type DiffMeta = StartMeta | ClearMeta
+
+export interface AiInlineDiffExtensionOptions {
+  /**
+   * Class prefix for inline-diff decorations. Defaults to
+   * `'pilotiq-ai-diff'`, producing:
+   *   - `pilotiq-ai-diff-inserted`  (green-background span on new ranges)
+   *   - `pilotiq-ai-diff-deleted`   (widget DOM root for deleted text)
+   *   - `pilotiq-ai-diff-deleted-text`  (the strikethrough span inside)
+   */
+  classPrefix?: string
+}
+
+export const AiInlineDiffExtension = Extension.create<AiInlineDiffExtensionOptions>({
+  name: 'pilotiqAiInlineDiff',
+
+  addOptions() {
+    return { classPrefix: 'pilotiq-ai-diff' }
+  },
+
+  onCreate() {
+    // Mirror the chip CSS injection pattern. Idempotent via sentinel.
+    if (typeof document === 'undefined') return
+    const SENTINEL = 'data-pilotiq-ai-diff-styles'
+    if (document.head.querySelector(`style[${SENTINEL}]`)) return
+    const prefix = this.options.classPrefix
+    const style  = document.createElement('style')
+    style.setAttribute(SENTINEL, '')
+    style.textContent = `
+      .${prefix}-inserted {
+        background-color: rgba(187, 247, 208, 0.55);
+        color: rgb(20, 83, 45);
+        text-decoration: none;
+      }
+      .${prefix}-deleted {
+        display: inline;
+        margin-right: 0.125em;
+      }
+      .${prefix}-deleted-text {
+        text-decoration: line-through;
+        text-decoration-color: rgba(220, 38, 38, 0.7);
+        background-color: rgba(254, 226, 226, 0.55);
+        color: rgb(153, 27, 27);
+        padding: 0 0.125em;
+      }
+    `
+    document.head.appendChild(style)
+  },
+
+  addCommands() {
+    return {
+      startAiInlineDiff: (id, newDocSlice) => ({ tr, state, dispatch }) => {
+        const baseline = state.doc
+        const docEnd   = state.doc.content.size
+        // Replace the whole doc body with the proposed content. The
+        // schema enforces validity — if the slice doesn't fit, ProseMirror
+        // throws (callers should pre-validate via `editor.schema`).
+        tr.replaceRange(0, docEnd, newDocSlice)
+        const meta: StartMeta = { type: 'start', id, baseline }
+        tr.setMeta(aiInlineDiffPluginKey, meta)
+        if (dispatch) dispatch(tr)
+        return true
+      },
+      applySurgicalAiInlineDiff: (id, applyFn) => ({ tr, state, dispatch }) => {
+        const baseline = state.doc
+        applyFn(tr)
+        if (!tr.docChanged) return false
+        const meta: StartMeta = { type: 'start', id, baseline }
+        tr.setMeta(aiInlineDiffPluginKey, meta)
+        if (dispatch) dispatch(tr)
+        return true
+      },
+      acceptAiInlineDiff: () => ({ tr, dispatch }) => {
+        const meta: ClearMeta = { type: 'clear' }
+        tr.setMeta(aiInlineDiffPluginKey, meta)
+        if (dispatch) dispatch(tr)
+        return true
+      },
+      rejectAiInlineDiff: () => ({ tr, state, dispatch }) => {
+        const ds = aiInlineDiffPluginKey.getState(state)
+        if (!ds) return false
+        const docEnd = state.doc.content.size
+        // Replace whole body with the baseline's content via a slice that
+        // spans the baseline's open boundaries (always 0 for a top-level
+        // doc replace).
+        tr.replaceWith(0, docEnd, ds.baseline.content)
+        const meta: ClearMeta = { type: 'clear' }
+        tr.setMeta(aiInlineDiffPluginKey, meta)
+        if (dispatch) dispatch(tr)
+        return true
+      },
+    }
+  },
+
+  addProseMirrorPlugins() {
+    const ext = this
+    return [
+      new Plugin<DiffState | null>({
+        key:   aiInlineDiffPluginKey,
+        state: {
+          init() { return null },
+          apply(tr, value) {
+            const meta = tr.getMeta(aiInlineDiffPluginKey) as DiffMeta | undefined
+            if (meta?.type === 'start') {
+              // Baseline captured BEFORE the replaceRange step in this
+              // same transaction. The changeset's `addSteps` consumes
+              // the transaction's step list to compute the diff between
+              // the baseline doc and the post-transaction doc.
+              const cs = ChangeSet.create(meta.baseline).addSteps(tr.doc, tr.mapping.maps, null)
+              return { id: meta.id, baseline: meta.baseline, changeset: cs }
+            }
+            if (meta?.type === 'clear') return null
+            if (!value) return value
+            // No explicit meta — a regular transaction landed while the
+            // diff was active. Fold its steps into the changeset so any
+            // further edits (e.g. y-prosemirror remote ops) are reflected.
+            if (tr.docChanged) {
+              const cs = value.changeset.addSteps(tr.doc, tr.mapping.maps, null)
+              return { ...value, changeset: cs }
+            }
+            return value
+          },
+        },
+        props: {
+          decorations(state) {
+            const ds = aiInlineDiffPluginKey.getState(state)
+            if (!ds) return DecorationSet.empty
+            return buildDiffDecorations(state, ds, ext.options.classPrefix ?? 'pilotiq-ai-diff')
+          },
+        },
+      }),
+    ]
+  },
+})
+
+function buildDiffDecorations(
+  state:     EditorState,
+  ds:        DiffState,
+  prefix:    string,
+): DecorationSet {
+  const decos: Decoration[] = []
+  const docSize = state.doc.content.size
+
+  for (const change of ds.changeset.changes) {
+    // `fromB..toB` is the range in the CURRENT doc that holds the
+    // inserted content. `fromA..toA` is the range in the BASELINE doc
+    // that was removed. `inserted` / `deleted` are Span[] arrays whose
+    // `length` sums to (toB - fromB) / (toA - fromA) respectively.
+    const fromB = Math.max(0, Math.min(change.fromB, docSize))
+    const toB   = Math.max(fromB, Math.min(change.toB,   docSize))
+
+    if (toB > fromB) {
+      decos.push(
+        Decoration.inline(fromB, toB, {
+          class: `${prefix}-inserted`,
+          'data-pilotiq-ai-diff-id': ds.id,
+        }),
+      )
+    }
+
+    // Deleted text — pull from the baseline using the `fromA..toA` range.
+    // Render via a widget at the change's insert-point (or end of insert)
+    // so the deleted text appears immediately before / after the new run.
+    // Empty deletions (pure inserts) skip the widget.
+    if (change.toA > change.fromA) {
+      const deletedText = ds.baseline.textBetween(change.fromA, change.toA, '\n', ' ')
+      if (deletedText.length > 0) {
+        decos.push(
+          Decoration.widget(fromB, () => buildDeletedWidget(deletedText, prefix, ds.id), {
+            side: -1,
+            ignoreSelection: true,
+            key: `pilotiq-ai-diff:deleted:${change.fromA}:${change.toA}`,
+          }),
+        )
+      }
+    }
+  }
+
+  return DecorationSet.create(state.doc, decos)
+}
+
+function buildDeletedWidget(text: string, prefix: string, id: string): HTMLElement {
+  const root = document.createElement('span')
+  root.className = `${prefix}-deleted`
+  root.setAttribute('data-pilotiq-ai-diff-id', id)
+  root.contentEditable = 'false'
+  const inner = document.createElement('span')
+  inner.className   = `${prefix}-deleted-text`
+  inner.textContent = text
+  root.appendChild(inner)
+  return root
+}

package/src/extensions/AiSuggestionExtension.ts

@@ -222,6 +222,57 @@ export const AiSuggestionExtension = Extension.create<AiSuggestionExtensionOptio
       }
       .${prefix}-accept:hover { color: rgb(21, 128, 61); }
       .${prefix}-reject:hover { color: rgb(185, 28, 28); }
+
+      /* Banner — top-of-editor strip for whole-field suggestions on rich
+         surfaces (markdown / richtext). Sibling to the chip styles above;
+         lives here so both ship via the same extension-mount sentinel.
+         Class names live under \`pilotiq-ai-banner-*\` (not \`-suggestion-\`)
+         since the banner is a host-mounted React component, not a PM
+         decoration. */
+      .pilotiq-ai-banner {
+        display: flex;
+        align-items: center;
+        gap: 0.5rem;
+        padding: 0.375rem 0.625rem;
+        margin-bottom: 0.375rem;
+        border-radius: 0.375rem;
+        background-color: rgba(254, 252, 232, 0.9);
+        border: 1px solid rgba(234, 179, 8, 0.4);
+        color: rgb(113, 63, 18);
+        font-size: 0.875rem;
+        line-height: 1.4;
+      }
+      .pilotiq-ai-banner-icon { flex: 0 0 auto; }
+      .pilotiq-ai-banner-label { flex: 1 1 auto; }
+      .pilotiq-ai-banner-actions {
+        display: inline-flex;
+        gap: 0.375rem;
+        flex: 0 0 auto;
+      }
+      .pilotiq-ai-banner-reject,
+      .pilotiq-ai-banner-accept {
+        appearance: none;
+        cursor: pointer;
+        font-size: 0.8125rem;
+        font-weight: 500;
+        line-height: 1;
+        padding: 0.25rem 0.625rem;
+        border-radius: 0.25rem;
+        border: 1px solid transparent;
+      }
+      .pilotiq-ai-banner-reject {
+        background-color: transparent;
+        color: rgb(120, 53, 15);
+        border-color: rgba(180, 83, 9, 0.4);
+      }
+      .pilotiq-ai-banner-reject:hover {
+        background-color: rgba(254, 215, 170, 0.4);
+      }
+      .pilotiq-ai-banner-accept {
+        background-color: rgb(22, 101, 52);
+        color: white;
+      }
+      .pilotiq-ai-banner-accept:hover { background-color: rgb(21, 128, 61); }
     `
     document.head.appendChild(style)
   },

package/src/index.ts

@@ -38,6 +38,21 @@ export {
   type AiSuggestionExtensionOptions,
 } from './extensions/AiSuggestionExtension.js'
 export { useAiSuggestionBridge } from './react/useAiSuggestionBridge.js'
+export {
+  AiInlineDiffExtension,
+  aiInlineDiffPluginKey,
+  getAiInlineDiffState,
+  type AiInlineDiffExtensionOptions,
+} from './extensions/AiInlineDiffExtension.js'
+export {
+  planReplaceBlock,
+  planInsertBlockBefore,
+  planDeleteBlock,
+  planUpdateBlockMark,
+  summarizeBlockStructure,
+  type BlockMarkRange,
+  type TransactionModifier,
+} from './surgicalOps.js'
 export {
   renderRichTextToHtml,
   isRichTextValue,

package/src/react/AiSuggestionBanner.tsx

@@ -0,0 +1,184 @@
+import { useMemo } from 'react'
+import {
+  usePendingSuggestionsForField,
+  usePendingSuggestions,
+  type PendingSuggestion,
+} from '@pilotiq/pilotiq/react'
+
+/**
+ * Top-of-editor banner UI for whole-field AI suggestions on Tiptap surfaces
+ * whose content shape can't survive the inline chip widget's plain-text
+ * replace (richtext, markdown). The chip path renders the replacement via
+ * `Element.textContent = replacement` which surfaces raw HTML / markdown
+ * as literal text — fine for plain `TextField`, ugly for the others.
+ *
+ * Visible only when at least one pending suggestion targets this field
+ * AND lacks `meta.editorRange` (i.e. a whole-field replacement from
+ * `update_form_state`'s `set_value` op). Range-anchored suggestions stay
+ * on the editor-side chip widget path — those have a precise location
+ * the user wants to see in context.
+ *
+ * Phase 1 ships banner-only ("Changes suggested — Accept / Reject"); no
+ * inline diff visualization yet. Phase 2 will replace the banner-only
+ * UX with a `prosemirror-changeset`-driven inline diff on the editor's
+ * doc itself, with the banner staying as the global Accept-all / Reject
+ * control bar. See `[[project_pilotiq_text_field_tiptap_rules]]`.
+ *
+ * Approve runs the renderer-supplied `onApplyWholeField(value)` callback
+ * AND dismisses the suggestion from the queue. Reject just dismisses
+ * (no doc mutation). Multiple pending whole-field suggestions on the
+ * same field stack — Accept all / Reject all collapse the queue in one
+ * pass.
+ */
+export interface AiSuggestionBannerProps {
+  /** Field name, matches the suggestion's `fieldName`. */
+  fieldName: string
+  /**
+   * Apply a whole-field suggestion to the underlying editor. Receives the
+   * raw `suggestedValue` string from the suggestion. The renderer wires
+   * its own content-shape-aware `setContent` here (markdown source for
+   * MarkdownEditor, HTML / JSON for TiptapEditor).
+   *
+   * Skipped when `onAcceptViaEditor` is supplied — that path means the
+   * editor already holds the proposed state via `AiInlineDiffExtension`,
+   * and Accept routes through `acceptAiInlineDiff()` instead. The host
+   * still calls `pendingSuggestions.approve(id)` afterwards to dismiss
+   * the queue entry.
+   */
+  onApplyWholeField: (suggestedValue: string) => void
+  /**
+   * Diff-aware Accept hook. When supplied, the banner calls this first
+   * (so the editor commits its diff state) and then dismisses via the
+   * context. `onApplyWholeField` is NOT called in this mode — the
+   * editor's current doc is already the accepted state.
+   *
+   * Sparse so the simple banner path (Phase 1, no diff) keeps its
+   * existing semantics.
+   */
+  onAcceptViaEditor?: () => void
+  /**
+   * Diff-aware Reject hook. When supplied, the banner calls this first
+   * (so the editor reverts to the baseline) and then dismisses via the
+   * context. Sparse — see `onAcceptViaEditor`.
+   */
+  onRejectViaEditor?: () => void
+  /** Optional class on the outer banner element. Defaults to a minimal styled chrome. */
+  className?: string
+}
+
+/**
+ * Hook variant — returns banner state without rendering, for renderers
+ * that want to compose their own chrome. Renderer-agnostic.
+ */
+export function useAiSuggestionBanner(fieldName: string): {
+  pending:    readonly PendingSuggestion[]
+  approveAll: (apply: (value: string) => void) => void
+  rejectAll:  () => void
+} {
+  const { list, dismiss } = usePendingSuggestionsForField(fieldName)
+
+  // Only whole-field suggestions land in the banner. Range-anchored ones
+  // ride the editor chip widget.
+  const pending = useMemo(
+    () => list.filter(s => !hasEditorRange(s)),
+    [list],
+  )
+
+  const approveAll = (apply: (value: string) => void): void => {
+    for (const s of pending) {
+      if (typeof s.suggestedValue === 'string') apply(s.suggestedValue)
+      dismiss(s.id)
+    }
+  }
+
+  const rejectAll = (): void => {
+    for (const s of pending) dismiss(s.id)
+  }
+
+  return { pending, approveAll, rejectAll }
+}
+
+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')
+}
+
+export function AiSuggestionBanner({
+  fieldName,
+  onApplyWholeField,
+  onAcceptViaEditor,
+  onRejectViaEditor,
+  className,
+}: AiSuggestionBannerProps): React.ReactElement | null {
+  const { pending, approveAll, rejectAll } = useAiSuggestionBanner(fieldName)
+  const { dismiss } = usePendingSuggestions()
+
+  if (pending.length === 0) return null
+
+  // First (and usually only) pending suggestion drives the agent-label
+  // display. Multiple-at-once is rare in practice — the banner shows the
+  // most recent producer to keep the chrome compact.
+  const head = pending[0]!
+  const sourceLabel = head.source?.agentLabel ?? null
+
+  const handleAccept = (): void => {
+    // Diff-active path — editor's current doc IS the accepted state.
+    // Commit via the editor command, then drop the queue entries.
+    if (onAcceptViaEditor) {
+      onAcceptViaEditor()
+      for (const s of pending) dismiss(s.id)
+      return
+    }
+    approveAll(onApplyWholeField)
+  }
+
+  const handleReject = (): void => {
+    // Diff-active path — editor still holds the proposed state; revert
+    // to the captured baseline before dismissing.
+    if (onRejectViaEditor) {
+      onRejectViaEditor()
+      for (const s of pending) dismiss(s.id)
+      return
+    }
+    rejectAll()
+  }
+
+  // Per-suggestion controls when there's more than one — keeps the UX
+  // discoverable. Single suggestion: Accept / Reject only.
+  const single = pending.length === 1
+
+  return (
+    <div
+      role="region"
+      aria-label="AI suggested changes"
+      data-pilotiq-ai-banner=""
+      className={className ?? 'pilotiq-ai-banner'}
+    >
+      <span className="pilotiq-ai-banner-icon" aria-hidden="true">💡</span>
+      <span className="pilotiq-ai-banner-label">
+        {single
+          ? sourceLabel
+            ? `Changes suggested by ${sourceLabel}`
+            : 'Changes suggested'
+          : `${pending.length} changes suggested`}
+      </span>
+      <div className="pilotiq-ai-banner-actions">
+        <button
+          type="button"
+          className="pilotiq-ai-banner-reject"
+          onClick={handleReject}
+        >
+          {single ? 'Reject' : 'Reject all'}
+        </button>
+        <button
+          type="button"
+          className="pilotiq-ai-banner-accept"
+          onClick={handleAccept}
+        >
+          {single ? 'Accept' : 'Accept all'}
+        </button>
+      </div>
+    </div>
+  )
+}

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[]),
       ],
@@ -248,23 +254,46 @@ export function MarkdownEditor({
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
   //
-  // 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.
+  // 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, {
-    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)
+    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
@@ -434,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}