@pilotiq/tiptap 3.5.0 → 3.7.0

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`.
@@ -464,22 +469,35 @@ function ClientEditor(props: ClientEditorProps) {
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
   //
-  // 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.
+  // 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, {
-    synthesizeWholeFieldRange: (ed) => ({
-      from: 0,
-      to:   ed.state.doc.content.size,
-    }),
-    onApplyWholeField: (value) => {
-      if (!editor || editor.isDestroyed) return
-      editor.commands.setContent(value)
+    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.
@@ -488,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,267 @@
+/**
+ * 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 { useEditorState } from '@tiptap/react'
+import {
+  registerPendingSuggestionApplier,
+  usePendingSuggestionsForField,
+  type PendingSuggestion,
+  type PendingSuggestionApplier,
+} from '@pilotiq/pilotiq/react'
+import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js'
+import {
+  planReplaceBlock,
+  planInsertBlockBefore,
+  planDeleteBlock,
+  planUpdateBlockMark,
+  type BlockMarkRange,
+  type TransactionModifier,
+} from '../surgicalOps.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 {
+  const active = useEditorState({
+    editor,
+    selector: ({ editor: ed }) => !!ed && aiInlineDiffPluginKey.getState(ed.state) !== null,
+  })
+  return active ?? false
+}
+
+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 /
+  // surgical-block suggestion. `meta.surgical` (if present) routes to a
+  // precise PM transaction; otherwise we treat the suggested value as a
+  // whole-field replacement. `meta.editorRange` (chip path) is filtered
+  // out — handled by AiSuggestionExtension elsewhere.
+  useEffect(() => {
+    if (!editor) return
+    const diffable = list.filter(s => !hasEditorRange(s))
+    for (const s of diffable) {
+      if (startedRef.current.has(s.id)) 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 surgical = readSurgicalMeta(s)
+      if (surgical) {
+        const modifier = planSurgicalModifier(editor, surgical)
+        if (!modifier) continue
+        editor.commands.applySurgicalAiInlineDiff(s.id, modifier)
+        startedRef.current.add(s.id)
+        continue
+      }
+
+      if (typeof s.suggestedValue !== 'string') 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')
+}
+
+/**
+ * Surgical op carried in `PendingSuggestion.meta.surgical`. The pilotiq-
+ * pro `update_form_state` client handler stamps this when the AI agent
+ * picks a block-level op instead of `set_value`.
+ *
+ * `content` is HTML for replace/insert ops, ignored otherwise. `mark` +
+ * `range` apply only to the mark op. Discriminated union; readers should
+ * narrow on `op`.
+ */
+type SurgicalOp =
+  | { op: 'replace_block';       blockIndex: number; content: string }
+  | { op: 'insert_block_before'; blockIndex: number; content: string }
+  | { op: 'delete_block';        blockIndex: number }
+  | { op: 'update_block_mark';   blockIndex: number; mark: string; range: BlockMarkRange; apply: boolean; attrs?: Record<string, unknown> }
+
+/**
+ * Either a single op (when the AI emitted only one surgical change) or
+ * an `{ ops: [...] }` batch (when the AI emitted multiple surgical ops
+ * in one `update_form_state` tool call). We apply a batch as a single
+ * combined diff so the user sees one Accept / Reject for the whole set.
+ */
+type SurgicalMeta = SurgicalOp | { ops: SurgicalOp[] }
+
+function parseSurgicalOp(obj: Record<string, unknown>): SurgicalOp | null {
+  const op = obj['op']
+  const blockIndex = obj['blockIndex']
+  if (typeof blockIndex !== 'number') return null
+  switch (op) {
+    case 'replace_block':
+    case 'insert_block_before': {
+      const content = obj['content']
+      if (typeof content !== 'string') return null
+      return { op, blockIndex, content }
+    }
+    case 'delete_block':
+      return { op, blockIndex }
+    case 'update_block_mark': {
+      const mark  = obj['mark']
+      const range = obj['range'] as { from?: unknown; to?: unknown } | undefined
+      const apply = obj['apply']
+      const attrs = obj['attrs']
+      if (typeof mark !== 'string') return null
+      if (!range || typeof range.from !== 'number' || typeof range.to !== 'number') return null
+      if (typeof apply !== 'boolean') return null
+      return {
+        op,
+        blockIndex,
+        mark,
+        range: { from: range.from, to: range.to },
+        apply,
+        ...(attrs && typeof attrs === 'object' ? { attrs: attrs as Record<string, unknown> } : {}),
+      }
+    }
+    default:
+      return null
+  }
+}
+
+function readSurgicalMeta(s: PendingSuggestion): SurgicalMeta | null {
+  const meta = (s.meta ?? {}) as Record<string, unknown>
+  const raw  = meta['surgical']
+  if (!raw || typeof raw !== 'object') return null
+  const obj = raw as Record<string, unknown>
+  // Batch form: { ops: [SurgicalOp, ...] }
+  if (Array.isArray(obj['ops'])) {
+    const parsed: SurgicalOp[] = []
+    for (const entry of obj['ops'] as unknown[]) {
+      if (!entry || typeof entry !== 'object') continue
+      const op = parseSurgicalOp(entry as Record<string, unknown>)
+      if (op) parsed.push(op)
+    }
+    if (parsed.length === 0) return null
+    return { ops: parsed }
+  }
+  return parseSurgicalOp(obj)
+}
+
+function planOp(editor: Editor, op: SurgicalOp): TransactionModifier | null {
+  switch (op.op) {
+    case 'replace_block':       return planReplaceBlock(editor, op.blockIndex, op.content)
+    case 'insert_block_before': return planInsertBlockBefore(editor, op.blockIndex, op.content)
+    case 'delete_block':        return planDeleteBlock(editor, op.blockIndex)
+    case 'update_block_mark':   return planUpdateBlockMark(editor, op.blockIndex, op.mark, op.range, op.apply, op.attrs)
+  }
+}
+
+/**
+ * Translate a surgical meta into a single TransactionModifier the diff
+ * extension can wrap with a snapshot. For batches, modifiers are
+ * computed against the original (pre-transaction) doc and then applied
+ * in DESC `blockIndex` order — each subsequent modifier touches earlier
+ * positions, so the prior modifiers' edits (at higher positions) don't
+ * shift the absolute positions the later modifiers were planned with.
+ *
+ * Returns null when the batch has no plannable ops (all out-of-range /
+ * unparseable). Drops individual non-plannable ops from a batch but
+ * still runs whatever did plan, so a single bad op doesn't kill the
+ * whole batch.
+ */
+function planSurgicalModifier(editor: Editor, surgical: SurgicalMeta): TransactionModifier | null {
+  if ('ops' in surgical) {
+    const sorted = [...surgical.ops].sort((a, b) => b.blockIndex - a.blockIndex)
+    const modifiers: TransactionModifier[] = []
+    for (const op of sorted) {
+      const mod = planOp(editor, op)
+      if (mod) modifiers.push(mod)
+    }
+    if (modifiers.length === 0) return null
+    return (tr) => { for (const mod of modifiers) mod(tr) }
+  }
+  return planOp(editor, surgical)
+}

package/src/surgicalOps.ts

@@ -0,0 +1,186 @@
+/**
+ * Surgical block-op planners for AI-driven precise edits.
+ *
+ * Each planner takes the editor + a logical block index + a payload and
+ * returns a `TransactionModifier` — a function the caller (typically
+ * `useAiInlineDiff`) feeds into
+ * `editor.commands.applySurgicalAiInlineDiff(id, modifier)`. The diff
+ * extension wraps the modifier in a snapshot-then-apply step so the
+ * inline-diff overlay renders against the precise changed range.
+ *
+ * "Block index" refers to a 0-based position across the doc's top-level
+ * children — what the AI agent sees as a numbered structural summary.
+ * Planners translate that to absolute ProseMirror positions internally.
+ *
+ * Planners return `null` when the request can't be satisfied (out-of-
+ * range index, unparseable HTML, unknown mark). Callers should treat
+ * `null` as "abort the surgical op" and surface a clear error to the
+ * agent so it can retry with a different plan.
+ */
+
+import type { Editor } from '@tiptap/core'
+import type { Transaction } from '@tiptap/pm/state'
+import type { Mark, MarkType, Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { DOMParser as PMDOMParser } from '@tiptap/pm/model'
+
+export type TransactionModifier = (tr: Transaction) => void
+
+/** Resolve the start position of the top-level child at `blockIndex`. */
+function blockStartPos(doc: ProseMirrorNode, blockIndex: number): number | null {
+  if (!Number.isInteger(blockIndex) || blockIndex < 0 || blockIndex >= doc.childCount) return null
+  let pos = 0
+  for (let i = 0; i < blockIndex; i++) pos += doc.child(i).nodeSize
+  return pos
+}
+
+/**
+ * Parse an HTML fragment into a doc-replaceable Slice. Uses the
+ * editor's own schema so block types unknown to the schema fail loudly
+ * rather than silently degrading.
+ *
+ * Returns `null` when DOM isn't available (SSR — shouldn't happen here,
+ * but keeps the planner safe).
+ */
+function parseHtmlToSlice(editor: Editor, html: string): ReturnType<typeof PMDOMParser.prototype.parseSlice> | null {
+  if (typeof document === 'undefined') return null
+  const container = document.createElement('div')
+  container.innerHTML = html
+  return PMDOMParser.fromSchema(editor.schema).parseSlice(container)
+}
+
+/**
+ * Replace the top-level block at `blockIndex` with the parsed content.
+ * Caller-supplied `content` is HTML — multiple top-level nodes are
+ * allowed and will all land where the original block was.
+ */
+export function planReplaceBlock(
+  editor:     Editor,
+  blockIndex: number,
+  content:    string,
+): TransactionModifier | null {
+  const doc = editor.state.doc
+  const start = blockStartPos(doc, blockIndex)
+  if (start === null) return null
+  const slice = parseHtmlToSlice(editor, content)
+  if (!slice) return null
+  const end = start + doc.child(blockIndex).nodeSize
+  return (tr) => { tr.replace(start, end, slice) }
+}
+
+/**
+ * Insert one or more top-level nodes (parsed from `content` HTML)
+ * before the block at `blockIndex`. `blockIndex === doc.childCount`
+ * appends at the end.
+ */
+export function planInsertBlockBefore(
+  editor:     Editor,
+  blockIndex: number,
+  content:    string,
+): TransactionModifier | null {
+  const doc = editor.state.doc
+  if (!Number.isInteger(blockIndex) || blockIndex < 0 || blockIndex > doc.childCount) return null
+  const slice = parseHtmlToSlice(editor, content)
+  if (!slice) return null
+  let pos = 0
+  for (let i = 0; i < blockIndex; i++) pos += doc.child(i).nodeSize
+  return (tr) => { tr.replace(pos, pos, slice) }
+}
+
+/**
+ * Delete the top-level block at `blockIndex`. Doc must retain at least
+ * one child after the delete (most schemas require this) — refuses to
+ * delete the last remaining block.
+ */
+export function planDeleteBlock(
+  editor:     Editor,
+  blockIndex: number,
+): TransactionModifier | null {
+  const doc = editor.state.doc
+  const start = blockStartPos(doc, blockIndex)
+  if (start === null) return null
+  if (doc.childCount <= 1) return null
+  const end = start + doc.child(blockIndex).nodeSize
+  return (tr) => { tr.delete(start, end) }
+}
+
+export interface BlockMarkRange {
+  /** 0-based text offset from the start of the block's content. */
+  from: number
+  /** Exclusive end offset. */
+  to:   number
+}
+
+/**
+ * Apply or remove an inline mark on a range *within* the block at
+ * `blockIndex`. `range.from` / `range.to` are text offsets relative to
+ * the start of the block's content (so `0` is the first character of
+ * the block, not the start of the doc).
+ *
+ * `apply = true` sets the mark (with optional `attrs`); `apply = false`
+ * removes it. Unknown marks (not in the editor's schema) return `null`
+ * so the caller can surface a clean error to the agent.
+ */
+export function planUpdateBlockMark(
+  editor:     Editor,
+  blockIndex: number,
+  mark:       string,
+  range:      BlockMarkRange,
+  apply:      boolean,
+  attrs?:     Record<string, unknown>,
+): TransactionModifier | null {
+  const doc = editor.state.doc
+  const start = blockStartPos(doc, blockIndex)
+  if (start === null) return null
+  const markType: MarkType | undefined = editor.schema.marks[mark]
+  if (!markType) return null
+
+  const block      = doc.child(blockIndex)
+  const blockInner = start + 1 // step inside the block's opening token
+  const contentMax = block.content.size
+
+  if (!Number.isInteger(range.from) || !Number.isInteger(range.to)) return null
+  const clampedFrom = Math.max(0, Math.min(range.from, contentMax))
+  const clampedTo   = Math.max(clampedFrom, Math.min(range.to, contentMax))
+  if (clampedTo === clampedFrom) return null
+
+  const from = blockInner + clampedFrom
+  const to   = blockInner + clampedTo
+
+  if (apply) {
+    const m: Mark = markType.create(attrs ?? null)
+    return (tr) => { tr.addMark(from, to, m) }
+  }
+  return (tr) => { tr.removeMark(from, to, markType) }
+}
+
+/**
+ * Summarize a doc's top-level structure as a numbered list the AI can
+ * cite by index when proposing surgical ops. Each entry includes the
+ * block index, node type, and a truncated text preview — enough for the
+ * model to identify which block it wants to modify without sending the
+ * whole HTML/markdown back through token-priced channels.
+ *
+ * Returns one line per top-level child:
+ *   `[0] heading: Welcome to the docs`
+ *   `[1] paragraph: Lorem ipsum dolor sit amet…`
+ *   `[2] bulletList: 3 items`
+ */
+export function summarizeBlockStructure(doc: ProseMirrorNode, maxChars = 80): string {
+  const lines: string[] = []
+  for (let i = 0; i < doc.childCount; i++) {
+    const node = doc.child(i)
+    const text = node.textContent.trim().replace(/\s+/g, ' ')
+    const preview = text.length === 0
+      ? describeStructuralNode(node)
+      : text.length > maxChars ? `${text.slice(0, maxChars)}…` : text
+    lines.push(`[${i}] ${node.type.name}: ${preview}`)
+  }
+  return lines.join('\n')
+}
+
+function describeStructuralNode(node: ProseMirrorNode): string {
+  const kids = node.childCount
+  if (kids === 0) return '(empty)'
+  if (kids === 1) return `1 ${node.firstChild?.type.name ?? 'child'}`
+  return `${kids} children`
+}