@pilotiq/tiptap 3.6.0 → 3.8.0

package/dist/extensions/AiInlineDiffExtension.d.ts

@@ -33,7 +33,7 @@
  */
 import { Extension } from '@tiptap/core';
 import { PluginKey } from '@tiptap/pm/state';
-import type { EditorState } from '@tiptap/pm/state';
+import type { EditorState, Transaction } from '@tiptap/pm/state';
 import type { Node as ProseMirrorNode, Slice } from '@tiptap/pm/model';
 import { ChangeSet } from 'prosemirror-changeset';
 declare module '@tiptap/core' {
@@ -49,6 +49,20 @@ declare module '@tiptap/core' {
              * the queue entry.
              */
             startAiInlineDiff: (id: string, newDocSlice: Slice) => ReturnType;
+            /**
+             * Start the inline-diff review session for a surgical edit.
+             * Snapshots the current doc as the baseline, then runs
+             * `applyFn(tr)` to mutate the transaction with a precise change
+             * (e.g. replace one block, insert before a position, set a mark
+             * on a range). The plugin folds the resulting steps into the
+             * changeset, so decorations land exactly on the modified ranges
+             * — no whole-doc replacement.
+             *
+             * Use this for `replace_block` / `insert_block_before` /
+             * `delete_block` / `update_block_mark` AI ops. Returns false (no
+             * dispatch) when `applyFn` produced no doc change.
+             */
+            applySurgicalAiInlineDiff: (id: string, applyFn: (tr: Transaction) => void) => ReturnType;
             /** Clear diff state. Current doc IS the accepted state. */
             acceptAiInlineDiff: () => ReturnType;
             /** Revert doc to the captured baseline and clear diff state. */

package/dist/extensions/AiInlineDiffExtension.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AiInlineDiffExtension.d.ts","sourceRoot":"","sources":["../../src/extensions/AiInlineDiffExtension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAU,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,kBAAkB,CAAA;AAEhE,OAAO,KAAK,EAAE,IAAI,IAAI,eAAe,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEjD,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,QAAQ,CAAC,UAAU;QAC3B,YAAY,EAAE;YACZ;;;;;;;;eAQG;YACH,iBAAiB,EAAG,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,KAAK,UAAU,CAAA;YAClE,2DAA2D;YAC3D,kBAAkB,EAAE,MAAM,UAAU,CAAA;YACpC,gEAAgE;YAChE,kBAAkB,EAAE,MAAM,UAAU,CAAA;SACrC,CAAA;KACF;CACF;AAED,UAAU,SAAS;IACjB,EAAE,EAAS,MAAM,CAAA;IACjB,2EAA2E;IAC3E,QAAQ,EAAG,eAAe,CAAA;IAC1B,mDAAmD;IACnD,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,eAAO,MAAM,qBAAqB,6BAAyD,CAAA;AAE3F;kEACkE;AAClE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAEzE;AAMD,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,qBAAqB,8CA+GhC,CAAA"}
+{"version":3,"file":"AiInlineDiffExtension.d.ts","sourceRoot":"","sources":["../../src/extensions/AiInlineDiffExtension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AACxC,OAAO,EAAU,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEhE,OAAO,KAAK,EAAE,IAAI,IAAI,eAAe,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAEjD,OAAO,QAAQ,cAAc,CAAC;IAC5B,UAAU,QAAQ,CAAC,UAAU;QAC3B,YAAY,EAAE;YACZ;;;;;;;;eAQG;YACH,iBAAiB,EAAG,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,KAAK,UAAU,CAAA;YAClE;;;;;;;;;;;;eAYG;YACH,yBAAyB,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,KAAK,UAAU,CAAA;YACzF,2DAA2D;YAC3D,kBAAkB,EAAE,MAAM,UAAU,CAAA;YACpC,gEAAgE;YAChE,kBAAkB,EAAE,MAAM,UAAU,CAAA;SACrC,CAAA;KACF;CACF;AAED,UAAU,SAAS;IACjB,EAAE,EAAS,MAAM,CAAA;IACjB,2EAA2E;IAC3E,QAAQ,EAAG,eAAe,CAAA;IAC1B,mDAAmD;IACnD,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,eAAO,MAAM,qBAAqB,6BAAyD,CAAA;AAE3F;kEACkE;AAClE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAEzE;AAMD,MAAM,WAAW,4BAA4B;IAC3C;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,eAAO,MAAM,qBAAqB,8CAwHhC,CAAA"}

package/dist/extensions/AiInlineDiffExtension.js

@@ -91,6 +91,17 @@ export const AiInlineDiffExtension = Extension.create({
                     dispatch(tr);
                 return true;
             },
+            applySurgicalAiInlineDiff: (id, applyFn) => ({ tr, state, dispatch }) => {
+                const baseline = state.doc;
+                applyFn(tr);
+                if (!tr.docChanged)
+                    return false;
+                const meta = { type: 'start', id, baseline };
+                tr.setMeta(aiInlineDiffPluginKey, meta);
+                if (dispatch)
+                    dispatch(tr);
+                return true;
+            },
             acceptAiInlineDiff: () => ({ tr, dispatch }) => {
                 const meta = { type: 'clear' };
                 tr.setMeta(aiInlineDiffPluginKey, meta);

package/dist/extensions/AiInlineDiffExtension.js.map

@@ -1 +1 @@
-{"version":3,"file":"AiInlineDiffExtension.js","sourceRoot":"","sources":["../../src/extensions/AiInlineDiffExtension.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"AiInlineDiffExtension.js","sourceRoot":"","sources":["../../src/extensions/AiInlineDiffExtension.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -7,5 +7,7 @@ export { tiptap } from './plugin.js';
 export { TiptapEditor } from './react/TiptapEditor.js';
 export { AiSuggestionExtension, aiSuggestionPluginKey, upsertSuggestion, upsertSuggestions, removeSuggestion, remapSuggestions, sortForApproveAll, clampPos, type AiSuggestion, type AiSuggestionExtensionOptions, } from './extensions/AiSuggestionExtension.js';
 export { useAiSuggestionBridge } from './react/useAiSuggestionBridge.js';
+export { AiInlineDiffExtension, aiInlineDiffPluginKey, getAiInlineDiffState, type AiInlineDiffExtensionOptions, } from './extensions/AiInlineDiffExtension.js';
+export { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, summarizeBlockStructure, type BlockMarkRange, type TransactionModifier, } from './surgicalOps.js';
 export { renderRichTextToHtml, isRichTextValue, type RenderRichTextOptions, type TiptapNode, type TiptapMark, } from './render.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,WAAW,EAChB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,4BAA4B,GAClC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AACxE,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,EACxB,KAAK,WAAW,EAChB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACzB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,EACd,KAAK,sBAAsB,GAC5B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,EACR,KAAK,YAAY,EACjB,KAAK,4BAA4B,GAClC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AACxE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,4BAA4B,GAClC,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,KAAK,qBAAqB,EAC1B,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -7,5 +7,7 @@ export { tiptap } from './plugin.js';
 export { TiptapEditor } from './react/TiptapEditor.js';
 export { AiSuggestionExtension, aiSuggestionPluginKey, upsertSuggestion, upsertSuggestions, removeSuggestion, remapSuggestions, sortForApproveAll, clampPos, } from './extensions/AiSuggestionExtension.js';
 export { useAiSuggestionBridge } from './react/useAiSuggestionBridge.js';
+export { AiInlineDiffExtension, aiInlineDiffPluginKey, getAiInlineDiffState, } from './extensions/AiInlineDiffExtension.js';
+export { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, summarizeBlockStructure, } from './surgicalOps.js';
 export { renderRichTextToHtml, isRichTextValue, } from './render.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,GAOzB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,EAAkB,MAAM,YAAY,CAAA;AAClD,OAAO,EACL,eAAe,GAGhB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,GAEf,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,GAGT,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AACxE,OAAO,EACL,oBAAoB,EACpB,eAAe,GAIhB,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,wBAAwB,GAOzB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,EAAkB,MAAM,YAAY,CAAA;AAClD,OAAO,EACL,eAAe,GAGhB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EACL,qBAAqB,EACrB,WAAW,EACX,cAAc,GAEf,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AACtD,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,QAAQ,GAGT,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAA;AACxE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,GAErB,MAAM,uCAAuC,CAAA;AAC9C,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,GAGxB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,eAAe,GAIhB,MAAM,aAAa,CAAA"}

package/dist/react/useAiInlineDiff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAiInlineDiff.d.ts","sourceRoot":"","sources":["../../src/react/useAiInlineDiff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAS7C,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,GAAG,IAAI,CAAA;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAatE;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CA+CN"}
+{"version":3,"file":"useAiInlineDiff.d.ts","sourceRoot":"","sources":["../../src/react/useAiInlineDiff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAkB7C,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;OAWG;IACH,eAAe,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,GAAG,IAAI,CAAA;CACjE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAMtE;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CA8GN"}

package/dist/react/useAiInlineDiff.js

@@ -30,8 +30,10 @@
  * suggestion at a time per id.
  */
 import { useEffect, useRef } from 'react';
+import { useEditorState } from '@tiptap/react';
 import { registerPendingSuggestionApplier, usePendingSuggestionsForField, } from '@pilotiq/pilotiq/react';
 import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js';
+import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, } from '../surgicalOps.js';
 /**
  * Returns whether a diff is currently active in the editor. Hosts use
  * this to gate the banner's UI between the legacy `onApplyWholeField`
@@ -39,20 +41,11 @@ import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js';
  * `rejectAiInlineDiff` to revert the doc).
  */
 export function useIsAiInlineDiffActive(editor) {
-    // Re-render on every editor transaction so the hook tracks state
-    // changes (start / accept / reject). useEditorState would be the
-    // idiomatic way; we read directly here to keep the dep surface tiny.
-    const [, force] = useReducerForceUpdate();
-    useEffect(() => {
-        if (!editor)
-            return;
-        const handler = () => force();
-        editor.on('transaction', handler);
-        return () => { editor.off('transaction', handler); };
-    }, [editor, force]);
-    if (!editor)
-        return false;
-    return aiInlineDiffPluginKey.getState(editor.state) !== null;
+    const active = useEditorState({
+        editor,
+        selector: ({ editor: ed }) => !!ed && aiInlineDiffPluginKey.getState(ed.state) !== null,
+    });
+    return active ?? false;
 }
 export function useAiInlineDiff(editor, fieldName, options) {
     const { list } = usePendingSuggestionsForField(fieldName);
@@ -62,20 +55,62 @@ export function useAiInlineDiff(editor, fieldName, options) {
     // so we don't re-start the diff every render or for already-active
     // suggestions.
     const startedRef = useRef(new Set());
-    // Context → editor: start the diff for each new whole-field suggestion.
+    // 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 wholeField = list.filter(s => !hasEditorRange(s));
-        for (const s of wholeField) {
+        const diffable = list.filter(s => !hasEditorRange(s));
+        for (const s of diffable) {
             if (startedRef.current.has(s.id))
                 continue;
-            if (typeof s.suggestedValue !== 'string')
+            const diffActive = aiInlineDiffPluginKey.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
+            // emitted a second `update_form_state` tool call instead of
+            // batching ops in one), fold the new modifier into the active
+            // diff. We dispatch a plain transaction with no extension meta;
+            // the plugin's existing "no explicit meta + tr.docChanged" branch
+            // adds the steps to the running changeset, so decorations update
+            // to cover both ops' ranges and the banner shows the combined
+            // count. Accept commits the union, Reject reverts to the same
+            // baseline captured when the FIRST suggestion started the diff —
+            // semantically "reject all pending suggested changes", which
+            // matches the banner copy.
+            //
+            // Whole-field suggestions still bail when a diff is active —
+            // dropping a fresh slice on top of an active review is too
+            // disruptive (it'd swap the entire doc mid-review).
+            if (diffActive) {
+                if (!surgical)
+                    continue;
+                const modifier = planSurgicalModifier(editor, surgical);
+                if (!modifier)
+                    continue;
+                editor.commands.command(({ tr, dispatch }) => {
+                    modifier(tr);
+                    if (!tr.docChanged)
+                        return false;
+                    if (dispatch)
+                        dispatch(tr);
+                    return true;
+                });
+                startedRef.current.add(s.id);
+                continue;
+            }
+            if (surgical) {
+                const modifier = planSurgicalModifier(editor, surgical);
+                if (!modifier)
+                    continue;
+                editor.commands.applySurgicalAiInlineDiff(s.id, modifier);
+                startedRef.current.add(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)
+            }
+            if (typeof s.suggestedValue !== 'string')
                 continue;
             const slice = parseRef.current(editor, s.suggestedValue);
             if (!slice)
@@ -92,16 +127,41 @@ export function useAiInlineDiff(editor, fieldName, options) {
                 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.
+    // Cross-tree applier — two paths:
+    //
+    //   1. Review-mode accept. Banner / chat-sidebar pill calls
+    //      `pendingSuggestions.approve(id)` for a suggestion we've already
+    //      started a diff for. Clear the diff state — current doc IS the
+    //      accepted state.
+    //   2. Auto-mode direct apply. AI tool binding bypassed the queue and
+    //      called the registry's applier with a synthetic suggestion
+    //      carrying `meta.surgical` (the suggestion was never pushed to
+    //      the context, so it's not in `startedRef`). Plan the modifier
+    //      and dispatch it as a plain transaction — no diff overlay, no
+    //      Accept / Reject step. Mirrors `set_value` auto-mode, which
+    //      writes directly via the same registry.
     useEffect(() => {
         if (!editor)
             return;
         const applier = (suggestion) => {
-            if (!startedRef.current.has(suggestion.id))
+            if (startedRef.current.has(suggestion.id)) {
+                editor.commands.acceptAiInlineDiff();
+                return;
+            }
+            const surgical = readSurgicalMeta(suggestion);
+            if (!surgical)
+                return;
+            const modifier = planSurgicalModifier(editor, surgical);
+            if (!modifier)
                 return;
-            editor.commands.acceptAiInlineDiff();
+            editor.commands.command(({ tr, dispatch }) => {
+                modifier(tr);
+                if (!tr.docChanged)
+                    return false;
+                if (dispatch)
+                    dispatch(tr);
+                return true;
+            });
         };
         return registerPendingSuggestionApplier(undefined, fieldName, applier);
     }, [editor, fieldName]);
@@ -111,11 +171,102 @@ function hasEditorRange(s) {
     const range = meta['editorRange'];
     return !!(range && typeof range.from === 'number' && typeof range.to === 'number');
 }
-// useReducer + dispatch is the smallest-API force-update primitive React
-// ships. Hoisted into a helper so the call site stays one line.
-import { useReducer } from 'react';
-function useReducerForceUpdate() {
-    const [n, inc] = useReducer((x) => (x + 1) | 0, 0);
-    return [n, () => inc()];
+function parseSurgicalOp(obj) {
+    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'];
+            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 } : {}),
+            };
+        }
+        default:
+            return null;
+    }
+}
+function readSurgicalMeta(s) {
+    const meta = (s.meta ?? {});
+    const raw = meta['surgical'];
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const obj = raw;
+    // Batch form: { ops: [SurgicalOp, ...] }
+    if (Array.isArray(obj['ops'])) {
+        const parsed = [];
+        for (const entry of obj['ops']) {
+            if (!entry || typeof entry !== 'object')
+                continue;
+            const op = parseSurgicalOp(entry);
+            if (op)
+                parsed.push(op);
+        }
+        if (parsed.length === 0)
+            return null;
+        return { ops: parsed };
+    }
+    return parseSurgicalOp(obj);
+}
+function planOp(editor, op) {
+    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, surgical) {
+    if ('ops' in surgical) {
+        const sorted = [...surgical.ops].sort((a, b) => b.blockIndex - a.blockIndex);
+        const modifiers = [];
+        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);
 }
 //# sourceMappingURL=useAiInlineDiff.js.map

package/dist/react/useAiInlineDiff.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAiInlineDiff.js","sourceRoot":"","sources":["../../src/react/useAiInlineDiff.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useAiInlineDiff.js","sourceRoot":"","sources":["../../src/react/useAiInlineDiff.ts"],"names":[],"mappings":"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"}

package/dist/surgicalOps.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { Node as ProseMirrorNode } from '@tiptap/pm/model';
+export type TransactionModifier = (tr: Transaction) => void;
+/**
+ * Replace the top-level block at `blockIndex` with the parsed content.
+ * `content` is HTML for `RichTextField` (Tiptap) editors and markdown
+ * source for `MarkdownField` (markdown-extension) editors —
+ * auto-detected by `parseContentToSlice`. Multiple top-level nodes are
+ * allowed and will all land where the original block was.
+ */
+export declare function planReplaceBlock(editor: Editor, blockIndex: number, content: string): TransactionModifier | null;
+/**
+ * Insert one or more top-level nodes before the block at `blockIndex`.
+ * `content` is HTML on `RichTextField` editors and markdown source on
+ * `MarkdownField` editors — auto-detected by `parseContentToSlice`.
+ * `blockIndex === doc.childCount` appends at the end.
+ */
+export declare function planInsertBlockBefore(editor: Editor, blockIndex: number, content: string): TransactionModifier | null;
+/**
+ * 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 declare function planDeleteBlock(editor: Editor, blockIndex: number): TransactionModifier | null;
+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 declare function planUpdateBlockMark(editor: Editor, blockIndex: number, mark: string, range: BlockMarkRange, apply: boolean, attrs?: Record<string, unknown>): TransactionModifier | null;
+/**
+ * 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 declare function summarizeBlockStructure(doc: ProseMirrorNode, maxChars?: number): string;
+//# sourceMappingURL=surgicalOps.d.ts.map

package/dist/surgicalOps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surgicalOps.d.ts","sourceRoot":"","sources":["../src/surgicalOps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,KAAK,EAAkB,IAAI,IAAI,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAG/E,MAAM,MAAM,mBAAmB,GAAG,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAA;AA6C3D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAM,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAK,MAAM,GACjB,mBAAmB,GAAG,IAAI,CAQ5B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAM,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAK,MAAM,GACjB,mBAAmB,GAAG,IAAI,CAQ5B;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAM,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,mBAAmB,GAAG,IAAI,CAO5B;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAA;IACZ,4BAA4B;IAC5B,EAAE,EAAI,MAAM,CAAA;CACb;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAM,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAQ,MAAM,EAClB,KAAK,EAAO,cAAc,EAC1B,KAAK,EAAO,OAAO,EACnB,KAAK,CAAC,EAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,mBAAmB,GAAG,IAAI,CAwB5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,SAAK,GAAG,MAAM,CAWnF"}

package/dist/surgicalOps.js

@@ -0,0 +1,187 @@
+/**
+ * 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 { DOMParser as PMDOMParser } from '@tiptap/pm/model';
+/** Resolve the start position of the top-level child at `blockIndex`. */
+function blockStartPos(doc, blockIndex) {
+    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 content into a doc-replaceable Slice against the editor's
+ * schema. Auto-detects markdown editors by sniffing for the
+ * `tiptap-markdown` extension's `storage.markdown.parser`: if present,
+ * the editor is a `MarkdownEditor` and AI-supplied `content` is
+ * markdown source — run it through the markdown parser to produce
+ * HTML first. Otherwise content is HTML (the `RichTextField` /
+ * `TiptapEditor` path).
+ *
+ * Mirrors the same auto-detect strategy `MarkdownEditor.tsx` uses for
+ * its `parseSuggestion` whole-field callback (see `useAiInlineDiff`),
+ * so surgical ops on markdown fields stay consistent with the
+ * existing whole-field replacement path.
+ *
+ * Returns `null` when DOM isn't available (SSR — shouldn't happen
+ * here, but keeps the planner safe) or when the markdown parser
+ * throws / returns a non-string (malformed content).
+ */
+function parseContentToSlice(editor, content) {
+    if (typeof document === 'undefined')
+        return null;
+    let html = content;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mdParser = editor.storage?.markdown?.parser;
+    if (mdParser && typeof mdParser.parse === 'function') {
+        try {
+            const parsed = mdParser.parse(content);
+            if (typeof parsed !== 'string')
+                return null;
+            html = parsed;
+        }
+        catch {
+            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.
+ * `content` is HTML for `RichTextField` (Tiptap) editors and markdown
+ * source for `MarkdownField` (markdown-extension) editors —
+ * auto-detected by `parseContentToSlice`. Multiple top-level nodes are
+ * allowed and will all land where the original block was.
+ */
+export function planReplaceBlock(editor, blockIndex, content) {
+    const doc = editor.state.doc;
+    const start = blockStartPos(doc, blockIndex);
+    if (start === null)
+        return null;
+    const slice = parseContentToSlice(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 before the block at `blockIndex`.
+ * `content` is HTML on `RichTextField` editors and markdown source on
+ * `MarkdownField` editors — auto-detected by `parseContentToSlice`.
+ * `blockIndex === doc.childCount` appends at the end.
+ */
+export function planInsertBlockBefore(editor, blockIndex, content) {
+    const doc = editor.state.doc;
+    if (!Number.isInteger(blockIndex) || blockIndex < 0 || blockIndex > doc.childCount)
+        return null;
+    const slice = parseContentToSlice(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, blockIndex) {
+    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); };
+}
+/**
+ * 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, blockIndex, mark, range, apply, attrs) {
+    const doc = editor.state.doc;
+    const start = blockStartPos(doc, blockIndex);
+    if (start === null)
+        return null;
+    const markType = 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 = 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, maxChars = 80) {
+    const lines = [];
+    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) {
+    const kids = node.childCount;
+    if (kids === 0)
+        return '(empty)';
+    if (kids === 1)
+        return `1 ${node.firstChild?.type.name ?? 'child'}`;
+    return `${kids} children`;
+}
+//# sourceMappingURL=surgicalOps.js.map

package/dist/surgicalOps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surgicalOps.js","sourceRoot":"","sources":["../src/surgicalOps.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/extensions/AiInlineDiffExtension.ts

@@ -52,6 +52,20 @@ declare module '@tiptap/core' {
        * the queue entry.
        */
       startAiInlineDiff:  (id: string, newDocSlice: Slice) => ReturnType
+      /**
+       * Start the inline-diff review session for a surgical edit.
+       * Snapshots the current doc as the baseline, then runs
+       * `applyFn(tr)` to mutate the transaction with a precise change
+       * (e.g. replace one block, insert before a position, set a mark
+       * on a range). The plugin folds the resulting steps into the
+       * changeset, so decorations land exactly on the modified ranges
+       * — no whole-doc replacement.
+       *
+       * Use this for `replace_block` / `insert_block_before` /
+       * `delete_block` / `update_block_mark` AI ops. Returns false (no
+       * dispatch) when `applyFn` produced no doc change.
+       */
+      applySurgicalAiInlineDiff: (id: string, applyFn: (tr: Transaction) => void) => ReturnType
       /** Clear diff state. Current doc IS the accepted state. */
       acceptAiInlineDiff: () => ReturnType
       /** Revert doc to the captured baseline and clear diff state. */
@@ -141,6 +155,15 @@ export const AiInlineDiffExtension = Extension.create<AiInlineDiffExtensionOptio
         if (dispatch) dispatch(tr)
         return true
       },
+      applySurgicalAiInlineDiff: (id, applyFn) => ({ tr, state, dispatch }) => {
+        const baseline = state.doc
+        applyFn(tr)
+        if (!tr.docChanged) return false
+        const meta: StartMeta = { type: 'start', id, baseline }
+        tr.setMeta(aiInlineDiffPluginKey, meta)
+        if (dispatch) dispatch(tr)
+        return true
+      },
       acceptAiInlineDiff: () => ({ tr, dispatch }) => {
         const meta: ClearMeta = { type: 'clear' }
         tr.setMeta(aiInlineDiffPluginKey, meta)

package/src/index.ts

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

package/src/react/useAiInlineDiff.ts

@@ -33,6 +33,7 @@
 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,
@@ -40,6 +41,14 @@ import {
   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 {
   /**
@@ -64,18 +73,11 @@ export interface UseAiInlineDiffOptions {
  * `rejectAiInlineDiff` to revert the doc).
  */
 export function useIsAiInlineDiffActive(editor: Editor | null): boolean {
-  // Re-render on every editor transaction so the hook tracks state
-  // changes (start / accept / reject). useEditorState would be the
-  // idiomatic way; we read directly here to keep the dep surface tiny.
-  const [, force] = useReducerForceUpdate()
-  useEffect(() => {
-    if (!editor) return
-    const handler = () => force()
-    editor.on('transaction', handler)
-    return () => { editor.off('transaction', handler) }
-  }, [editor, force])
-  if (!editor) return false
-  return aiInlineDiffPluginKey.getState(editor.state) !== null
+  const active = useEditorState({
+    editor,
+    selector: ({ editor: ed }) => !!ed && aiInlineDiffPluginKey.getState(ed.state) !== null,
+  })
+  return active ?? false
 }
 
 export function useAiInlineDiff(
@@ -93,17 +95,58 @@ export function useAiInlineDiff(
   // suggestions.
   const startedRef = useRef<Set<string>>(new Set())
 
-  // Context → editor: start the diff for each new whole-field suggestion.
+  // 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 wholeField = list.filter(s => !hasEditorRange(s))
-    for (const s of wholeField) {
+    const diffable = list.filter(s => !hasEditorRange(s))
+    for (const s of diffable) {
       if (startedRef.current.has(s.id)) continue
+      const diffActive = aiInlineDiffPluginKey.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
+      // emitted a second `update_form_state` tool call instead of
+      // batching ops in one), fold the new modifier into the active
+      // diff. We dispatch a plain transaction with no extension meta;
+      // the plugin's existing "no explicit meta + tr.docChanged" branch
+      // adds the steps to the running changeset, so decorations update
+      // to cover both ops' ranges and the banner shows the combined
+      // count. Accept commits the union, Reject reverts to the same
+      // baseline captured when the FIRST suggestion started the diff —
+      // semantically "reject all pending suggested changes", which
+      // matches the banner copy.
+      //
+      // Whole-field suggestions still bail when a diff is active —
+      // dropping a fresh slice on top of an active review is too
+      // disruptive (it'd swap the entire doc mid-review).
+      if (diffActive) {
+        if (!surgical) continue
+        const modifier = planSurgicalModifier(editor, surgical)
+        if (!modifier) continue
+        editor.commands.command(({ tr, dispatch }) => {
+          modifier(tr)
+          if (!tr.docChanged) return false
+          if (dispatch) dispatch(tr)
+          return true
+        })
+        startedRef.current.add(s.id)
+        continue
+      }
+
+      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
-      // 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 slice = parseRef.current(editor, s.suggestedValue)
       if (!slice) continue
       editor.commands.startAiInlineDiff(s.id, slice)
@@ -118,14 +161,36 @@ export function useAiInlineDiff(
     }
   }, [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.
+  // Cross-tree applier — two paths:
+  //
+  //   1. Review-mode accept. Banner / chat-sidebar pill calls
+  //      `pendingSuggestions.approve(id)` for a suggestion we've already
+  //      started a diff for. Clear the diff state — current doc IS the
+  //      accepted state.
+  //   2. Auto-mode direct apply. AI tool binding bypassed the queue and
+  //      called the registry's applier with a synthetic suggestion
+  //      carrying `meta.surgical` (the suggestion was never pushed to
+  //      the context, so it's not in `startedRef`). Plan the modifier
+  //      and dispatch it as a plain transaction — no diff overlay, no
+  //      Accept / Reject step. Mirrors `set_value` auto-mode, which
+  //      writes directly via the same registry.
   useEffect(() => {
     if (!editor) return
     const applier: PendingSuggestionApplier = (suggestion) => {
-      if (!startedRef.current.has(suggestion.id)) return
-      editor.commands.acceptAiInlineDiff()
+      if (startedRef.current.has(suggestion.id)) {
+        editor.commands.acceptAiInlineDiff()
+        return
+      }
+      const surgical = readSurgicalMeta(suggestion)
+      if (!surgical) return
+      const modifier = planSurgicalModifier(editor, surgical)
+      if (!modifier) return
+      editor.commands.command(({ tr, dispatch }) => {
+        modifier(tr)
+        if (!tr.docChanged) return false
+        if (dispatch) dispatch(tr)
+        return true
+      })
     }
     return registerPendingSuggestionApplier(undefined, fieldName, applier)
   }, [editor, fieldName])
@@ -137,10 +202,115 @@ function hasEditorRange(s: PendingSuggestion): boolean {
   return !!(range && typeof range.from === 'number' && typeof range.to === 'number')
 }
 
-// useReducer + dispatch is the smallest-API force-update primitive React
-// ships. Hoisted into a helper so the call site stays one line.
-import { useReducer } from 'react'
-function useReducerForceUpdate(): [number, () => void] {
-  const [n, inc] = useReducer((x: number) => (x + 1) | 0, 0)
-  return [n, () => inc()]
+/**
+ * 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,209 @@
+/**
+ * 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 content into a doc-replaceable Slice against the editor's
+ * schema. Auto-detects markdown editors by sniffing for the
+ * `tiptap-markdown` extension's `storage.markdown.parser`: if present,
+ * the editor is a `MarkdownEditor` and AI-supplied `content` is
+ * markdown source — run it through the markdown parser to produce
+ * HTML first. Otherwise content is HTML (the `RichTextField` /
+ * `TiptapEditor` path).
+ *
+ * Mirrors the same auto-detect strategy `MarkdownEditor.tsx` uses for
+ * its `parseSuggestion` whole-field callback (see `useAiInlineDiff`),
+ * so surgical ops on markdown fields stay consistent with the
+ * existing whole-field replacement path.
+ *
+ * Returns `null` when DOM isn't available (SSR — shouldn't happen
+ * here, but keeps the planner safe) or when the markdown parser
+ * throws / returns a non-string (malformed content).
+ */
+function parseContentToSlice(editor: Editor, content: string): ReturnType<typeof PMDOMParser.prototype.parseSlice> | null {
+  if (typeof document === 'undefined') return null
+  let html = content
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const mdParser = (editor.storage as any)?.markdown?.parser
+  if (mdParser && typeof mdParser.parse === 'function') {
+    try {
+      const parsed: unknown = mdParser.parse(content)
+      if (typeof parsed !== 'string') return null
+      html = parsed
+    } catch { 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.
+ * `content` is HTML for `RichTextField` (Tiptap) editors and markdown
+ * source for `MarkdownField` (markdown-extension) editors —
+ * auto-detected by `parseContentToSlice`. 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 = parseContentToSlice(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 before the block at `blockIndex`.
+ * `content` is HTML on `RichTextField` editors and markdown source on
+ * `MarkdownField` editors — auto-detected by `parseContentToSlice`.
+ * `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 = parseContentToSlice(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`
+}