@pilotiq/tiptap 3.4.0 → 3.6.0

package/src/extensions/AiInlineDiffExtension.ts

@@ -0,0 +1,263 @@
+/**
+ * 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
+      /** 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
+      },
+      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

@@ -170,6 +170,113 @@ 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); }
+
+      /* 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)
+  },
+
   addCommands() {
     return {
       addAiSuggestion: (suggestion) => ({ tr, state, dispatch }) => {

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/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