@pilotiq/tiptap 3.5.0 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/tiptap",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Tiptap rich-text editor adapter for @pilotiq/pilotiq — slash menu, draggable blocks, custom-block API",
   "license": "MIT",
   "repository": {
@@ -30,26 +30,28 @@
       "types": "./dist/render.d.ts"
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "prosemirror-changeset": "^2.4.1"
+  },
   "peerDependencies": {
-    "@pilotiq/pilotiq": ">=0.6.0 <1.0.0",
     "@base-ui/react": "^1",
+    "@pilotiq/pilotiq": ">=0.6.0 <1.0.0",
     "@tiptap/core": "^3",
-    "@tiptap/pm": "^3",
-    "@tiptap/react": "^3",
-    "@tiptap/starter-kit": "^3",
+    "@tiptap/extension-color": "3.22.4",
+    "@tiptap/extension-details": "3.22.4",
+    "@tiptap/extension-highlight": "3.22.4",
+    "@tiptap/extension-image": "3.22.4",
     "@tiptap/extension-link": "^3",
     "@tiptap/extension-placeholder": "^3",
-    "@tiptap/extension-underline": "3.22.4",
     "@tiptap/extension-subscript": "3.22.4",
     "@tiptap/extension-superscript": "3.22.4",
+    "@tiptap/extension-table": "3.22.4",
     "@tiptap/extension-text-align": "3.22.4",
     "@tiptap/extension-text-style": "3.22.4",
-    "@tiptap/extension-color": "3.22.4",
-    "@tiptap/extension-highlight": "3.22.4",
-    "@tiptap/extension-image": "3.22.4",
-    "@tiptap/extension-table": "3.22.4",
-    "@tiptap/extension-details": "3.22.4",
+    "@tiptap/extension-underline": "3.22.4",
+    "@tiptap/pm": "^3",
+    "@tiptap/react": "^3",
+    "@tiptap/starter-kit": "^3",
     "@tiptap/suggestion": "^3",
     "react": "^18 || ^19",
     "react-dom": "^18 || ^19"
@@ -57,29 +59,29 @@
   "devDependencies": {
     "@base-ui/react": "^1",
     "@tiptap/core": "^3",
-    "@tiptap/pm": "^3",
-    "@tiptap/react": "^3",
-    "@tiptap/starter-kit": "^3",
+    "@tiptap/extension-color": "3.22.4",
+    "@tiptap/extension-details": "3.22.4",
+    "@tiptap/extension-highlight": "3.22.4",
+    "@tiptap/extension-image": "3.22.4",
     "@tiptap/extension-link": "^3",
     "@tiptap/extension-placeholder": "^3",
-    "@tiptap/extension-underline": "3.22.4",
     "@tiptap/extension-subscript": "3.22.4",
     "@tiptap/extension-superscript": "3.22.4",
+    "@tiptap/extension-table": "3.22.4",
     "@tiptap/extension-text-align": "3.22.4",
     "@tiptap/extension-text-style": "3.22.4",
-    "@tiptap/extension-color": "3.22.4",
-    "@tiptap/extension-highlight": "3.22.4",
-    "@tiptap/extension-image": "3.22.4",
-    "@tiptap/extension-table": "3.22.4",
-    "@tiptap/extension-details": "3.22.4",
+    "@tiptap/extension-underline": "3.22.4",
+    "@tiptap/pm": "^3",
+    "@tiptap/react": "^3",
+    "@tiptap/starter-kit": "^3",
     "@tiptap/suggestion": "^3",
-    "tiptap-markdown": "^0.9",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
     "esbuild": "^0.27",
     "react": "^19",
     "react-dom": "^19",
+    "tiptap-markdown": "^0.9",
     "typescript": "^5",
     "@pilotiq/pilotiq": "^0.19.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

@@ -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/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>
+  )
+}