@pilotiq/tiptap 3.20.0 → 4.0.0

package/dist/react/TiptapEditor.js

@@ -17,17 +17,17 @@ import { contentBlockNodes } from '../extensions/contentBlocks.js';
 import { Popover } from '@base-ui/react/popover';
 import { useCollabRoom, getCollabExtensions, useRowCoords, parseRowFieldPath } from '@pilotiq/pilotiq/react';
 import { useCollabSeed } from '@rudderjs/sync/react';
-import { useAiSuggestionBridge } from './useAiSuggestionBridge.js';
-import { useAiInlineDiff, useIsAiInlineDiffActive, readAiDiffViewMarker } from './useAiInlineDiff.js';
-import { AiSuggestionBanner } from './AiSuggestionBanner.js';
+import { useSuggestionBridge } from './useSuggestionBridge.js';
+import { useInlineDiff, useIsInlineDiffActive, readDiffViewMarker } from './useInlineDiff.js';
+import { SuggestionBanner } from './SuggestionBanner.js';
 import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model';
 import { BlockNodeExtension } from '../extensions/BlockNodeExtension.js';
 import { SlashCommandExtension, } from '../extensions/SlashCommandExtension.js';
 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 { SuggestionChipExtension } from '../extensions/SuggestionChipExtension.js';
+import { InlineDiffExtension } from '../extensions/InlineDiffExtension.js';
 import { MentionExtension, } from '../extensions/MentionExtension.js';
 import { SlashMenu } from './SlashMenu.js';
 import { MentionMenu } from './MentionMenu.js';
@@ -278,10 +278,10 @@ function ClientEditor(props) {
                 })] : [MentionExtension]),
             DragHandleExtension,
             // AI suggestions — chip widget for surgical (range-anchored) edits.
-            AiSuggestionExtension,
+            SuggestionChipExtension,
             // AI inline diff — Tiptap-Pro-style visualization for whole-field
-            // suggestions via prosemirror-changeset. See AiInlineDiffExtension.
-            AiInlineDiffExtension,
+            // suggestions via prosemirror-changeset. See InlineDiffExtension.
+            InlineDiffExtension,
             // Realtime-collab extensions (Yjs `Collaboration` + cursor) — empty
             // when no `<RecordCollabRoom>` is mounted up-tree, or when no plugin
             // registered a factory via `registerCollabExtensions`.
@@ -426,13 +426,13 @@ function ClientEditor(props) {
         }
     });
     // Cross-package suggestion bridge — sync the host's
-    // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
+    // `<PendingSuggestionsContext>` queue with the editor's `InlineSuggestion`
     // extension. No-op when no provider is mounted (default no-op context).
     //
     // 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 below the editor (see render below).
+    // `<SuggestionBanner>` mounts below 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) => {
@@ -440,7 +440,7 @@ function ClientEditor(props) {
             return;
         editor.commands.setContent(value);
     };
-    useAiSuggestionBridge(editor ?? null, name, {
+    useSuggestionBridge(editor ?? null, name, {
         onApplyWholeField: applyWholeField,
     });
     // Inline diff for whole-field suggestions. Pipeline mirrors MarkdownEditor:
@@ -448,7 +448,7 @@ function ClientEditor(props) {
     // 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, {
+    useInlineDiff(editor ?? null, name, {
         parseSuggestion: (ed, value) => {
             try {
                 const container = document.createElement('div');
@@ -459,16 +459,16 @@ function ClientEditor(props) {
                 return null;
             }
         },
-        resolveDisplayMode: () => readAiDiffViewMarker(name),
+        resolveDisplayMode: () => readDiffViewMarker(name),
     });
-    const isDiffActive = useIsAiInlineDiffActive(editor ?? null);
+    const isDiffActive = useIsInlineDiffActive(editor ?? null);
     // Re-render the toolbar when the selection / marks change so active-state
     // booleans stay fresh.
     const tick = useEditorTick(editor);
-    return (_jsxs("div", { className: "relative flex flex-col", children: [_jsx("input", { type: "hidden", name: name, value: serialized }), editor && toolbarGroups && toolbarGroups.length > 0 && (_jsx(Toolbar, { editor: editor, groups: toolbarGroups, tick: tick, textColors: textColors, customTextColors: customTextColors, highlightColors: highlightColors, onAttachOpenChange: setAttachOpen })), editor && (_jsx(AttachFilesDialog, { open: attachOpen, onOpenChange: setAttachOpen, editor: editor, fieldName: name, ...(uploadUrl !== undefined ? { uploadUrl } : {}), ...(acceptedFileTypes !== undefined ? { acceptedFileTypes } : {}), ...(maxAttachmentSize !== undefined ? { maxFileSize: maxAttachmentSize } : {}), ...(attachmentDir !== undefined ? { directory: attachmentDir } : {}), ...(attachmentVis !== undefined ? { visibility: attachmentVis } : {}) })), _jsx(EditorContent, { editor: editor }), _jsx(AiSuggestionBanner, { fieldName: name, onApplyWholeField: applyWholeField, ...(isDiffActive && editor
+    return (_jsxs("div", { className: "relative flex flex-col", children: [_jsx("input", { type: "hidden", name: name, value: serialized }), editor && toolbarGroups && toolbarGroups.length > 0 && (_jsx(Toolbar, { editor: editor, groups: toolbarGroups, tick: tick, textColors: textColors, customTextColors: customTextColors, highlightColors: highlightColors, onAttachOpenChange: setAttachOpen })), editor && (_jsx(AttachFilesDialog, { open: attachOpen, onOpenChange: setAttachOpen, editor: editor, fieldName: name, ...(uploadUrl !== undefined ? { uploadUrl } : {}), ...(acceptedFileTypes !== undefined ? { acceptedFileTypes } : {}), ...(maxAttachmentSize !== undefined ? { maxFileSize: maxAttachmentSize } : {}), ...(attachmentDir !== undefined ? { directory: attachmentDir } : {}), ...(attachmentVis !== undefined ? { visibility: attachmentVis } : {}) })), _jsx(EditorContent, { editor: editor }), _jsx(SuggestionBanner, { fieldName: name, onApplyWholeField: applyWholeField, ...(isDiffActive && editor
                     ? {
-                        onAcceptViaEditor: () => editor.commands.acceptAiInlineDiff(),
-                        onRejectViaEditor: () => editor.commands.rejectAiInlineDiff(),
+                        onAcceptViaEditor: () => editor.commands.acceptInlineDiff(),
+                        onRejectViaEditor: () => editor.commands.rejectInlineDiff(),
                     }
                     : {}) }), editor && floatingEnabled && _jsx(FloatingToolbar, { editor: editor }), editor && _jsx(TableFloatingToolbar, { editor: editor }), _jsx(SlashPopover, { state: slashState, keyHandlerRef: slashKeyRef }), _jsx(MentionPopover, { state: mentionState, keyHandlerRef: mentionKeyRef })] }));
 }

package/dist/react/{useAiInlineDiff.d.ts → useInlineDiff.d.ts}

@@ -1,37 +1,37 @@
 /**
  * Bridge between the host's `<PendingSuggestionsContext>` queue and the
- * editor's `AiInlineDiffExtension`. When a whole-field suggestion arrives
+ * editor's `InlineDiffExtension`. 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
+ *   2. Calls `editor.commands.startInlineDiff(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
+ *      registry so the host's `<SuggestionBanner>` Accept button (and
  *      any other surface calling `pendingSuggestions.approve(id)`) runs
- *      `acceptAiInlineDiff()` instead of the legacy `onApplyWholeField`
+ *      `acceptInlineDiff()` 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
+ * `onRejectWithEditor` prop, which calls `rejectInlineDiff()` 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
+ * `SuggestionChipExtension`'s chip path which also allows only one
  * suggestion at a time per id.
  */
 import type { Editor } from '@tiptap/core';
 import type { Slice } from '@tiptap/pm/model';
-export interface UseAiInlineDiffOptions {
+export interface UseInlineDiffOptions {
     /**
      * Parse the suggested string value into a ProseMirror Slice that's
      * compatible with this editor's schema. Returns `null` to skip (e.g.
@@ -49,7 +49,7 @@ export interface UseAiInlineDiffOptions {
      * Resolve the diff rendering mode at diff-start time. Return `'lines'`
      * for the GitHub-style stacked rows, anything else / omitted keeps the
      * default `'inline'` word-flow. Called lazily per diff so DOM-marker
-     * readers (`readAiDiffViewMarker`) see the mounted field wrapper.
+     * readers (`readDiffViewMarker`) see the mounted field wrapper.
      */
     resolveDisplayMode?: (editor: Editor) => 'inline' | 'lines';
 }
@@ -61,13 +61,13 @@ export interface UseAiInlineDiffOptions {
  * Defaults to `'inline'` when no marker is present — including in
  * open-core installs where the augmentation never runs.
  */
-export declare function readAiDiffViewMarker(fieldName: string): 'inline' | 'lines';
+export declare function readDiffViewMarker(fieldName: string): 'inline' | 'lines';
 /**
  * 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).
+ * `rejectInlineDiff` to revert the doc).
  */
-export declare function useIsAiInlineDiffActive(editor: Editor | null): boolean;
-export declare function useAiInlineDiff(editor: Editor | null, fieldName: string, options: UseAiInlineDiffOptions): void;
-//# sourceMappingURL=useAiInlineDiff.d.ts.map
+export declare function useIsInlineDiffActive(editor: Editor | null): boolean;
+export declare function useInlineDiff(editor: Editor | null, fieldName: string, options: UseInlineDiffOptions): void;
+//# sourceMappingURL=useInlineDiff.d.ts.map

package/dist/react/{useAiInlineDiff.js → useInlineDiff.js}

@@ -1,39 +1,39 @@
 /**
  * Bridge between the host's `<PendingSuggestionsContext>` queue and the
- * editor's `AiInlineDiffExtension`. When a whole-field suggestion arrives
+ * editor's `InlineDiffExtension`. 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
+ *   2. Calls `editor.commands.startInlineDiff(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
+ *      registry so the host's `<SuggestionBanner>` Accept button (and
  *      any other surface calling `pendingSuggestions.approve(id)`) runs
- *      `acceptAiInlineDiff()` instead of the legacy `onApplyWholeField`
+ *      `acceptInlineDiff()` 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
+ * `onRejectWithEditor` prop, which calls `rejectInlineDiff()` 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
+ * `SuggestionChipExtension`'s chip path which also allows only one
  * suggestion at a time per id.
  */
 import { useEffect, useRef } from 'react';
 import { useEditorState } from '@tiptap/react';
 import { registerPendingSuggestionApplier, usePendingSuggestionsForField, useFormId, } from '@pilotiq/pilotiq/react';
-import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js';
-import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, planWrapBlocks, } from '../surgicalOps.js';
+import { inlineDiffPluginKey } from '../extensions/InlineDiffExtension.js';
+import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, planWrapBlocks, planReplaceText, } from '../surgicalOps.js';
 /**
  * Read the field's `.aiDiffView(...)` choice off the DOM — the
  * `@pilotiq-pro/ai` field augmentation stamps `data-ai-diff-view` onto
@@ -42,7 +42,7 @@ import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlo
  * Defaults to `'inline'` when no marker is present — including in
  * open-core installs where the augmentation never runs.
  */
-export function readAiDiffViewMarker(fieldName) {
+export function readDiffViewMarker(fieldName) {
     if (typeof document === 'undefined')
         return 'inline';
     const els = document.getElementsByName(fieldName);
@@ -56,16 +56,16 @@ export function readAiDiffViewMarker(fieldName) {
  * 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).
+ * `rejectInlineDiff` to revert the doc).
  */
-export function useIsAiInlineDiffActive(editor) {
+export function useIsInlineDiffActive(editor) {
     const active = useEditorState({
         editor,
-        selector: ({ editor: ed }) => !!ed && aiInlineDiffPluginKey.getState(ed.state) !== null,
+        selector: ({ editor: ed }) => !!ed && inlineDiffPluginKey.getState(ed.state) !== null,
     });
     return active ?? false;
 }
-export function useAiInlineDiff(editor, fieldName, options) {
+export function useInlineDiff(editor, fieldName, options) {
     const { list } = usePendingSuggestionsForField(fieldName);
     // Scope the applier registration by the surrounding form's id so
     // multi-form pages route suggestions to the editor instance inside the
@@ -103,7 +103,7 @@ export function useAiInlineDiff(editor, fieldName, options) {
     // 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.
+    // out — handled by SuggestionChipExtension elsewhere.
     useEffect(() => {
         if (!editor)
             return;
@@ -111,7 +111,7 @@ export function useAiInlineDiff(editor, fieldName, options) {
         for (const s of diffable) {
             if (startedRef.current.has(s.id))
                 continue;
-            const diffActive = aiInlineDiffPluginKey.getState(editor.state) !== null;
+            const diffActive = inlineDiffPluginKey.getState(editor.state) !== null;
             const surgical = readSurgicalMeta(s);
             // Cross-tool-call surgical stacking. When a diff is already active
             // and a fresh surgical suggestion arrives (typically the model
@@ -151,7 +151,7 @@ export function useAiInlineDiff(editor, fieldName, options) {
                 const modifier = planSurgicalModifier(editor, surgical);
                 if (!modifier)
                     continue;
-                editor.commands.applySurgicalAiInlineDiff(s.id, modifier, displayMode);
+                editor.commands.applySurgicalInlineDiff(s.id, modifier, displayMode);
                 startedRef.current.add(s.id);
                 continue;
             }
@@ -160,7 +160,7 @@ export function useAiInlineDiff(editor, fieldName, options) {
             const slice = parseRef.current(editor, s.suggestedValue);
             if (!slice)
                 continue;
-            editor.commands.startAiInlineDiff(s.id, slice, displayMode);
+            editor.commands.startInlineDiff(s.id, slice, displayMode);
             startedRef.current.add(s.id);
         }
         // Cleanup: when a suggestion leaves the context AND we previously
@@ -190,7 +190,7 @@ export function useAiInlineDiff(editor, fieldName, options) {
             return;
         const applier = (suggestion) => {
             if (startedRef.current.has(suggestion.id)) {
-                editor.commands.acceptAiInlineDiff();
+                editor.commands.acceptInlineDiff();
                 return;
             }
             const surgical = readSurgicalMeta(suggestion);
@@ -218,6 +218,16 @@ function hasEditorRange(s) {
 }
 function parseSurgicalOp(obj) {
     const op = obj['op'];
+    // `replace_text` carries no `blockIndex` — parse it before the index guard.
+    if (op === 'replace_text') {
+        const search = obj['search'];
+        const replace = obj['replace'];
+        if (typeof search !== 'string' || search.length === 0)
+            return null;
+        if (typeof replace !== 'string')
+            return null;
+        return { op, search, replace };
+    }
     const blockIndex = obj['blockIndex'];
     if (typeof blockIndex !== 'number')
         return null;
@@ -300,6 +310,7 @@ function planOp(editor, op) {
         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);
         case 'wrap_blocks': return planWrapBlocks(editor, op.blockIndex, op.toIndex, op.wrapperType, op.attrs);
+        case 'replace_text': return planReplaceText(editor, op.search, op.replace);
     }
 }
 /**
@@ -315,9 +326,15 @@ function planOp(editor, op) {
  * still runs whatever did plan, so a single bad op doesn't kill the
  * whole batch.
  */
+/** Sort key for batch ordering. Index-free ops (`replace_text`) sort last so the
+ * index-based ops apply first at their original positions; the text swap then
+ * resolves against the live tr doc. */
+function opBlockIndex(op) {
+    return 'blockIndex' in op ? op.blockIndex : Number.NEGATIVE_INFINITY;
+}
 function planSurgicalModifier(editor, surgical) {
     if ('ops' in surgical) {
-        const sorted = [...surgical.ops].sort((a, b) => b.blockIndex - a.blockIndex);
+        const sorted = [...surgical.ops].sort((a, b) => opBlockIndex(b) - opBlockIndex(a));
         const modifiers = [];
         for (const op of sorted) {
             const mod = planOp(editor, op);

package/dist/react/{useAiSuggestionBridge.d.ts → useSuggestionBridge.d.ts}

@@ -2,12 +2,12 @@ import type { Editor } from '@tiptap/core';
 import { type PendingSuggestion } from '@pilotiq/pilotiq/react';
 /**
  * Two-way sync between the cross-package `<PendingSuggestionsContext>`
- * queue and this editor's `AiSuggestionExtension` state.
+ * queue and this editor's `SuggestionChipExtension` state.
  *
  *   - **Context → editor**: every entry whose `meta.editorRange = { from, to }`
  *     is present and whose `suggestedValue` is a string gets pushed into the
- *     editor as an inline-diff hunk via `addAiSuggestion`. Entries leaving the
- *     queue are removed from the editor via `rejectAiSuggestion` (no doc edit).
+ *     editor as an inline-diff hunk via `addSuggestion`. Entries leaving the
+ *     queue are removed from the editor via `rejectSuggestion` (no doc edit).
  *
  *   - **Editor → context**: when a chip's Approve / Reject button removes a
  *     hunk from the editor's plugin state, the matching id is dismissed from
@@ -19,7 +19,7 @@ import { type PendingSuggestion } from '@pilotiq/pilotiq/react';
  * the editor (`pushed`). The Context→editor pass never re-pushes an id that's
  * already there, and the Editor→context pass only dismisses ids that this
  * hook had previously pushed (so an id added directly by host code via
- * `editor.commands.addAiSuggestion(...)` doesn't get reflected back through
+ * `editor.commands.addSuggestion(...)` doesn't get reflected back through
  * a context that never knew about it).
  *
  * **Whole-field fallback** (chat-driven suggestions). Producers like
@@ -35,7 +35,7 @@ import { type PendingSuggestion } from '@pilotiq/pilotiq/react';
  * responsible for the Approve UI — FieldShell hides its legacy overlay
  * whenever a Tiptap renderer is mounted (richtext / markdown / collab text).
  */
-export interface UseAiSuggestionBridgeOptions {
+export interface UseSuggestionBridgeOptions {
     /**
      * Apply a whole-field suggestion that lacks `meta.editorRange`. Each
      * Tiptap renderer passes its own implementation (different content
@@ -58,6 +58,6 @@ export interface UseAiSuggestionBridgeOptions {
         to: number;
     } | undefined;
 }
-export declare function useAiSuggestionBridge(editor: Editor | null, fieldName: string, options?: UseAiSuggestionBridgeOptions): void;
+export declare function useSuggestionBridge(editor: Editor | null, fieldName: string, options?: UseSuggestionBridgeOptions): void;
 export type { PendingSuggestion };
-//# sourceMappingURL=useAiSuggestionBridge.d.ts.map
+//# sourceMappingURL=useSuggestionBridge.d.ts.map

package/dist/react/{useAiSuggestionBridge.js → useSuggestionBridge.js}

@@ -1,10 +1,10 @@
 import { useEffect, useRef } from 'react';
 import { registerPendingSuggestionApplier, usePendingSuggestionsForField, useFormId, } from '@pilotiq/pilotiq/react';
-import { aiSuggestionPluginKey } from '../extensions/AiSuggestionExtension.js';
-export function useAiSuggestionBridge(editor, fieldName, options = {}) {
+import { suggestionChipPluginKey } from '../extensions/SuggestionChipExtension.js';
+export function useSuggestionBridge(editor, fieldName, options = {}) {
     const { list, dismiss } = usePendingSuggestionsForField(fieldName);
     // Scope the applier under the surrounding form's id — same reasoning
-    // as `useAiInlineDiff`: two editors with the same field name across
+    // as `useInlineDiff`: two editors with the same field name across
     // different forms (main edit form vs. a Replicate modal, say) would
     // otherwise race on `registerPendingSuggestionApplier(undefined, …)`
     // and the last-mounted editor would steal every approval.
@@ -59,7 +59,7 @@ export function useAiSuggestionBridge(editor, fieldName, options = {}) {
                 isSynthesized = true;
             }
             const replacement = typeof s.suggestedValue === 'string' ? s.suggestedValue : '';
-            editor.commands.addAiSuggestion({
+            editor.commands.addSuggestion({
                 id: s.id,
                 from: range.from,
                 to: range.to,
@@ -74,8 +74,8 @@ export function useAiSuggestionBridge(editor, fieldName, options = {}) {
             if (contextIds.has(id))
                 continue;
             // Context dropped the suggestion — remove from editor without
-            // mutating the doc (rejectAiSuggestion drops state only).
-            editor.commands.rejectAiSuggestion(id);
+            // mutating the doc (rejectSuggestion drops state only).
+            editor.commands.rejectSuggestion(id);
             pushedRef.current.delete(id);
             synthesizedRef.current.delete(id);
         }
@@ -85,7 +85,7 @@ export function useAiSuggestionBridge(editor, fieldName, options = {}) {
         if (!editor)
             return;
         const handler = () => {
-            const ps = aiSuggestionPluginKey.getState(editor.state);
+            const ps = suggestionChipPluginKey.getState(editor.state);
             if (!ps)
                 return;
             const editorIds = new Set(ps.suggestions.map((s) => s.id));
@@ -114,20 +114,20 @@ export function useAiSuggestionBridge(editor, fieldName, options = {}) {
             const hasSynthesized = synthesizedRef.current.has(suggestion.id);
             const hasPushed = pushedRef.current.has(suggestion.id);
             // Synthesized whole-field range — the chip rendered for visualization,
-            // but routing Approve through the editor's `approveAiSuggestion` would
+            // but routing Approve through the editor's `approveSuggestion` would
             // do a plain-text replace and clobber HTML / markdown formatting.
             // Delegate to the renderer-supplied applier (content-shape-aware)
             // and clear the chip state without a doc edit.
             if (hasSynthesized && apply && typeof suggestion.suggestedValue === 'string') {
                 apply(suggestion.suggestedValue);
-                editor.commands.rejectAiSuggestion(suggestion.id);
+                editor.commands.rejectSuggestion(suggestion.id);
                 return;
             }
             // Producer-supplied editor range — surgical edit. Forward Approve to
             // the editor command; the transaction listener above mirrors the
             // dismiss back into context.
             if (hasPushed) {
-                editor.chain().focus().approveAiSuggestion(suggestion.id).run();
+                editor.chain().focus().approveSuggestion(suggestion.id).run();
                 return;
             }
             // Whole-field path WITHOUT visualization — producer skipped the range

package/dist/surgicalOps.d.ts

@@ -3,8 +3,8 @@
  *
  * 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
+ * `useInlineDiff`) feeds into
+ * `editor.commands.applySurgicalInlineDiff(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.
  *
@@ -87,4 +87,17 @@ export declare function planUpdateBlockMark(editor: Editor, blockIndex: number,
  *   `[2] bulletList: 3 items`
  */
 export declare function summarizeBlockStructure(doc: ProseMirrorNode, maxChars?: number): string;
+/**
+ * In-block text find→replace. Swaps the FIRST occurrence of `search` with
+ * `replace`, preserving the surrounding node structure — so it can fix a word,
+ * number, or typo INSIDE a custom block (alert / prosCons / faq / keyTakeaways)
+ * or a table cell without rebuilding (and flattening) the block, which is what
+ * `replace_block` would force. Index-free: the match position is resolved at
+ * apply time against the live transaction doc, so it composes safely after the
+ * index-based block ops in a batch.
+ *
+ * Returns `null` when `search` isn't present (the caller surfaces "no change")
+ * so a stale/guessed search string can never silently corrupt the doc.
+ */
+export declare function planReplaceText(editor: Editor, search: string, replace: string): TransactionModifier | null;
 //# sourceMappingURL=surgicalOps.d.ts.map

package/dist/surgicalOps.js

@@ -3,8 +3,8 @@
  *
  * 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
+ * `useInlineDiff`) feeds into
+ * `editor.commands.applySurgicalInlineDiff(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.
  *
@@ -38,7 +38,7 @@ function blockStartPos(doc, blockIndex) {
  * `TiptapEditor` path).
  *
  * Mirrors the same auto-detect strategy `MarkdownEditor.tsx` uses for
- * its `parseSuggestion` whole-field callback (see `useAiInlineDiff`),
+ * its `parseSuggestion` whole-field callback (see `useInlineDiff`),
  * so surgical ops on markdown fields stay consistent with the
  * existing whole-field replacement path.
  *
@@ -217,6 +217,53 @@ export function summarizeBlockStructure(doc, maxChars = 80) {
     }
     return lines.join('\n');
 }
+/**
+ * In-block text find→replace. Swaps the FIRST occurrence of `search` with
+ * `replace`, preserving the surrounding node structure — so it can fix a word,
+ * number, or typo INSIDE a custom block (alert / prosCons / faq / keyTakeaways)
+ * or a table cell without rebuilding (and flattening) the block, which is what
+ * `replace_block` would force. Index-free: the match position is resolved at
+ * apply time against the live transaction doc, so it composes safely after the
+ * index-based block ops in a batch.
+ *
+ * Returns `null` when `search` isn't present (the caller surfaces "no change")
+ * so a stale/guessed search string can never silently corrupt the doc.
+ */
+export function planReplaceText(editor, search, replace) {
+    if (typeof search !== 'string' || search.length === 0)
+        return null;
+    if (typeof replace !== 'string')
+        return null;
+    let present = false;
+    editor.state.doc.descendants((node) => {
+        if (present)
+            return false;
+        if (node.isText && node.text && node.text.includes(search)) {
+            present = true;
+            return false;
+        }
+        return true;
+    });
+    if (!present)
+        return null;
+    return (tr) => {
+        let foundFrom = -1;
+        tr.doc.descendants((node, pos) => {
+            if (foundFrom >= 0)
+                return false;
+            if (node.isText && node.text) {
+                const i = node.text.indexOf(search);
+                if (i !== -1) {
+                    foundFrom = pos + i;
+                    return false;
+                }
+            }
+            return true;
+        });
+        if (foundFrom >= 0)
+            tr.insertText(replace, foundFrom, foundFrom + search.length);
+    };
+}
 function describeStructuralNode(node) {
     const kids = node.childCount;
     if (kids === 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/tiptap",
-  "version": "3.20.0",
+  "version": "4.0.0",
   "description": "Tiptap rich-text editor adapter for @pilotiq/pilotiq — slash menu, draggable blocks, custom-block API",
   "license": "MIT",
   "repository": {