@pilotiq/tiptap 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pilotiq/tiptap
 
+## 3.12.0
+
+### Minor Changes
+
+- 7252aaa: GitHub-style line-mode rendering for the AI inline diff. `startAiInlineDiff` / `applySurgicalAiInlineDiff` accept an optional `displayMode: 'inline' | 'lines'` — in `'lines'` mode every block touched by an insert renders as a full-width green row (`+` gutter) and deleted content renders as stacked red rows (`−` gutter) above the change, instead of the inline word-flow. `useAiInlineDiff` gained `resolveDisplayMode`, and all three editor surfaces (rich text, markdown, collab text) resolve it from a `data-ai-diff-view` wrapper marker — stamped by `@pilotiq-pro/ai`'s `Field.aiDiffView('lines')` setter. Default stays `'inline'`.
+
 ## 3.11.0
 
 ### Minor Changes

package/dist/extensions/AiInlineDiffExtension.d.ts

@@ -48,7 +48,7 @@ declare module '@tiptap/core' {
              * banner / approve handlers can correlate the editor state with
              * the queue entry.
              */
-            startAiInlineDiff: (id: string, newDocSlice: Slice) => ReturnType;
+            startAiInlineDiff: (id: string, newDocSlice: Slice, displayMode?: AiDiffDisplayMode) => ReturnType;
             /**
              * Start the inline-diff review session for a surgical edit.
              * Snapshots the current doc as the baseline, then runs
@@ -62,7 +62,7 @@ declare module '@tiptap/core' {
              * `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;
+            applySurgicalAiInlineDiff: (id: string, applyFn: (tr: Transaction) => void, displayMode?: AiDiffDisplayMode) => ReturnType;
             /** Clear diff state. Current doc IS the accepted state. */
             acceptAiInlineDiff: () => ReturnType;
             /** Revert doc to the captured baseline and clear diff state. */
@@ -70,12 +70,24 @@ declare module '@tiptap/core' {
         };
     }
 }
+/**
+ * How the pending diff renders:
+ *   - `'inline'` (default) — word-flow: green inline decorations on
+ *     inserted ranges, deleted text struck through in place.
+ *   - `'lines'` — GitHub-style: every block touched by an insert gets a
+ *     full-width green row (`+` gutter), deleted content renders as a
+ *     full-width red row (`−` gutter) above the change. Suits markdown
+ *     sources / structured text where lines are the meaningful unit.
+ */
+export type AiDiffDisplayMode = 'inline' | 'lines';
 interface DiffState {
     id: string;
     /** Original doc captured at `startAiInlineDiff` time — used for revert. */
     baseline: ProseMirrorNode;
     /** ChangeSet accumulating diffs since baseline. */
     changeset: ChangeSet;
+    /** Rendering mode for the decorations — see `AiDiffDisplayMode`. */
+    displayMode: AiDiffDisplayMode;
 }
 export declare const aiInlineDiffPluginKey: PluginKey<DiffState | null>;
 /** Read the active diff state, if any. Public for hosts that want to

package/dist/extensions/AiInlineDiffExtension.js

@@ -73,30 +73,64 @@ export const AiInlineDiffExtension = Extension.create({
         color: rgb(153, 27, 27);
         padding: 0 0.125em;
       }
+      .${prefix}-inserted-line {
+        display: block;
+        background-color: rgba(187, 247, 208, 0.45);
+        border-radius: 2px;
+        padding-left: 1.25em;
+        position: relative;
+        /* Some text surfaces style the editor root as a flex row (input
+           mimic); full-basis keeps each diff row on its own line there. */
+        flex: 0 0 100%;
+        width: 100%;
+      }
+      .${prefix}-inserted-line::before {
+        content: '+';
+        position: absolute;
+        left: 0.25em;
+        color: rgb(20, 83, 45);
+        opacity: 0.7;
+      }
+      .${prefix}-deleted-lines { display: block; flex: 0 0 100%; width: 100%; }
+      .${prefix}-lines-active { display: block !important; }
+      .${prefix}-deleted-line {
+        background-color: rgba(254, 226, 226, 0.55);
+        color: rgb(153, 27, 27);
+        border-radius: 2px;
+        padding-left: 1.25em;
+        position: relative;
+        white-space: pre-wrap;
+      }
+      .${prefix}-deleted-line::before {
+        content: '−';
+        position: absolute;
+        left: 0.25em;
+        opacity: 0.7;
+      }
     `;
         document.head.appendChild(style);
     },
     addCommands() {
         return {
-            startAiInlineDiff: (id, newDocSlice) => ({ tr, state, dispatch }) => {
+            startAiInlineDiff: (id, newDocSlice, displayMode) => ({ tr, state, dispatch }) => {
                 const baseline = state.doc;
                 const docEnd = state.doc.content.size;
                 // Replace the whole doc body with the proposed content. The
                 // schema enforces validity — if the slice doesn't fit, ProseMirror
                 // throws (callers should pre-validate via `editor.schema`).
                 tr.replaceRange(0, docEnd, newDocSlice);
-                const meta = { type: 'start', id, baseline };
+                const meta = { type: 'start', id, baseline, ...(displayMode ? { displayMode } : {}) };
                 tr.setMeta(aiInlineDiffPluginKey, meta);
                 if (dispatch)
                     dispatch(tr);
                 return true;
             },
-            applySurgicalAiInlineDiff: (id, applyFn) => ({ tr, state, dispatch }) => {
+            applySurgicalAiInlineDiff: (id, applyFn, displayMode) => ({ tr, state, dispatch }) => {
                 const baseline = state.doc;
                 applyFn(tr);
                 if (!tr.docChanged)
                     return false;
-                const meta = { type: 'start', id, baseline };
+                const meta = { type: 'start', id, baseline, ...(displayMode ? { displayMode } : {}) };
                 tr.setMeta(aiInlineDiffPluginKey, meta);
                 if (dispatch)
                     dispatch(tr);
@@ -141,7 +175,7 @@ export const AiInlineDiffExtension = Extension.create({
                             // the transaction's step list to compute the diff between
                             // the baseline doc and the post-transaction doc.
                             const cs = ChangeSet.create(meta.baseline).addSteps(tr.doc, tr.mapping.maps, null);
-                            return { id: meta.id, baseline: meta.baseline, changeset: cs };
+                            return { id: meta.id, baseline: meta.baseline, changeset: cs, displayMode: meta.displayMode ?? 'inline' };
                         }
                         if (meta?.type === 'clear')
                             return null;
@@ -164,12 +198,25 @@ export const AiInlineDiffExtension = Extension.create({
                             return DecorationSet.empty;
                         return buildDiffDecorations(state, ds, ext.options.classPrefix ?? 'pilotiq-ai-diff');
                     },
+                    // While a LINES-mode diff is active, force the editor root to
+                    // block layout. Some text surfaces style the root as a flex row
+                    // (single-line input mimic) — without this the stacked diff
+                    // rows lay out as overflowing columns. Drops automatically on
+                    // accept / reject.
+                    attributes(state) {
+                        const ds = aiInlineDiffPluginKey.getState(state);
+                        return ds?.displayMode === 'lines'
+                            ? { class: `${ext.options.classPrefix ?? 'pilotiq-ai-diff'}-lines-active` }
+                            : {};
+                    },
                 },
             }),
         ];
     },
 });
 function buildDiffDecorations(state, ds, prefix) {
+    if (ds.displayMode === 'lines')
+        return buildLineDiffDecorations(state, ds, prefix);
     const decos = [];
     const docSize = state.doc.content.size;
     for (const change of ds.changeset.changes) {
@@ -213,3 +260,126 @@ function buildDeletedWidget(text, prefix, id) {
     root.appendChild(inner);
     return root;
 }
+/**
+ * GitHub-style line rendering. Unlike the inline mode (which walks the
+ * changeset's MINIMAL change ranges), lines mode treats whole top-level
+ * blocks as the diff unit — an LCS over the baseline's block texts vs
+ * the current doc's block texts. A partially-edited line therefore
+ * renders as one full red row (the old line) above one full green row
+ * (the new line), instead of fragmented word-level shards. Mark-only
+ * changes (same text, different formatting) read as "kept" here — the
+ * block unit is text; use inline mode when formatting deltas matter.
+ *
+ * The changeset state still drives baseline capture / accept / reject;
+ * lines mode just re-derives its presentation from baseline-vs-current
+ * on every decoration pass, so remote collab edits during review stay
+ * correct for free.
+ */
+function buildLineDiffDecorations(state, ds, prefix) {
+    const decos = [];
+    const baseTexts = topLevelBlockTexts(ds.baseline);
+    const current = [];
+    state.doc.forEach((node, pos) => {
+        current.push({ text: node.textContent, pos, nodeSize: node.nodeSize });
+    });
+    // Walk tokens with a pointer into the CURRENT doc's blocks. Removed
+    // baseline lines accumulate and flush as ONE widget anchored before
+    // the next current block (or at doc end), so consecutive deletions
+    // render as a contiguous red row group.
+    let j = 0;
+    let pendingRemoved = [];
+    const flushRemoved = (anchor) => {
+        if (pendingRemoved.length === 0)
+            return;
+        const lines = pendingRemoved;
+        pendingRemoved = [];
+        decos.push(Decoration.widget(anchor, () => buildDeletedLinesWidget(lines.join('\n'), prefix, ds.id), {
+            side: -1,
+            ignoreSelection: true,
+            key: `pilotiq-ai-diff:deleted-lines:${anchor}:${lines.length}`,
+        }));
+    };
+    for (const tok of lcsBlockDiffTokens(baseTexts, current.map(c => c.text))) {
+        if (tok.kind === 'kept') {
+            flushRemoved(current[j].pos);
+            j++;
+            continue;
+        }
+        if (tok.kind === 'added') {
+            flushRemoved(current[j].pos);
+            decos.push(Decoration.node(current[j].pos, current[j].pos + current[j].nodeSize, {
+                class: `${prefix}-inserted-line`,
+                'data-pilotiq-ai-diff-id': ds.id,
+            }));
+            j++;
+            continue;
+        }
+        // removed — baseline-only line; accumulate for the next flush.
+        pendingRemoved.push(tok.text);
+    }
+    flushRemoved(state.doc.content.size);
+    return DecorationSet.create(state.doc, decos);
+}
+function topLevelBlockTexts(doc) {
+    const out = [];
+    doc.forEach((node) => { out.push(node.textContent); });
+    return out;
+}
+/** Standard LCS walk over two block-text arrays, emitting tokens in
+ *  presentation order with removed-before-added on replacements. */
+function lcsBlockDiffTokens(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = 1; i <= n; i++) {
+        for (let j = 1; j <= m; j++) {
+            if (a[i - 1] === b[j - 1])
+                dp[i][j] = dp[i - 1][j - 1] + 1;
+            else
+                dp[i][j] = Math.max(dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    const out = [];
+    let i = n;
+    let j = m;
+    while (i > 0 && j > 0) {
+        if (a[i - 1] === b[j - 1]) {
+            out.push({ kind: 'kept', text: a[i - 1] });
+            i--;
+            j--;
+        }
+        // Strict `>` ties toward pushing `added` first in this backward walk,
+        // which renders removed-before-added after the final reverse.
+        else if (dp[i - 1][j] > dp[i][j - 1]) {
+            out.push({ kind: 'removed', text: a[i - 1] });
+            i--;
+        }
+        else {
+            out.push({ kind: 'added', text: b[j - 1] });
+            j--;
+        }
+    }
+    while (i > 0) {
+        out.push({ kind: 'removed', text: a[i - 1] });
+        i--;
+    }
+    while (j > 0) {
+        out.push({ kind: 'added', text: b[j - 1] });
+        j--;
+    }
+    out.reverse();
+    return out;
+}
+function buildDeletedLinesWidget(text, prefix, id) {
+    const root = document.createElement('div');
+    root.className = `${prefix}-deleted-lines`;
+    root.setAttribute('data-pilotiq-ai-diff-id', id);
+    root.contentEditable = 'false';
+    for (const line of text.split('\n')) {
+        const row = document.createElement('div');
+        row.className = `${prefix}-deleted-line`;
+        row.textContent = line || ' ';
+        root.appendChild(row);
+    }
+    return root;
+}

package/dist/react/CollabTextRenderer.js

@@ -8,7 +8,7 @@ import { createPlainTextEditor, plainTextOf, plainTextToDoc } from '../PlainText
 import { AiSuggestionExtension } from '../extensions/AiSuggestionExtension.js';
 import { AiInlineDiffExtension } from '../extensions/AiInlineDiffExtension.js';
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js';
-import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js';
+import { useAiInlineDiff, useIsAiInlineDiffActive, readAiDiffViewMarker } from './useAiInlineDiff.js';
 import { AiSuggestionBanner } from './AiSuggestionBanner.js';
 /**
  * Tiptap-backed plain-text editor for pilotiq's `TextField` / `TextareaField`
@@ -158,6 +158,7 @@ export function CollabTextRenderer({ name, fragmentKey, multiline, defaultValue,
                 return null;
             }
         },
+        resolveDisplayMode: () => readAiDiffViewMarker(name),
     });
     const isDiffActive = useIsAiInlineDiffActive(editor ?? null);
     // First-load seed when collab is active. Collaboration starts the editor

package/dist/react/MarkdownEditor.js

@@ -16,7 +16,7 @@ import { useCollabSeed } from '@rudderjs/sync/react';
 import { AiSuggestionExtension } from '../extensions/AiSuggestionExtension.js';
 import { AiInlineDiffExtension } from '../extensions/AiInlineDiffExtension.js';
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js';
-import { useAiInlineDiff, useIsAiInlineDiffActive } from './useAiInlineDiff.js';
+import { useAiInlineDiff, useIsAiInlineDiffActive, readAiDiffViewMarker } from './useAiInlineDiff.js';
 import { AiSuggestionBanner } from './AiSuggestionBanner.js';
 import { getMarkdownString, parseMarkdownToHtml } from '../markdownStorage.js';
 // Inline lucide.dev SVGs — same posture as `toolbarButtons.tsx` so this
@@ -200,6 +200,7 @@ export function MarkdownEditor({ name, fragmentKey, defaultValue, placeholder, d
                 return null;
             }
         },
+        resolveDisplayMode: () => readAiDiffViewMarker(name),
     });
     const isDiffActive = useIsAiInlineDiffActive(editor ?? null);
     // First-load seed for collab. Collaboration starts the editor empty

package/dist/react/TiptapEditor.js

@@ -17,7 +17,7 @@ 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 } from './useAiInlineDiff.js';
+import { useAiInlineDiff, useIsAiInlineDiffActive, readAiDiffViewMarker } from './useAiInlineDiff.js';
 import { AiSuggestionBanner } from './AiSuggestionBanner.js';
 import { DOMParser as ProseMirrorDOMParser } from '@tiptap/pm/model';
 import { BlockNodeExtension } from '../extensions/BlockNodeExtension.js';
@@ -490,6 +490,7 @@ function ClientEditor(props) {
                 return null;
             }
         },
+        resolveDisplayMode: () => readAiDiffViewMarker(name),
     });
     const isDiffActive = useIsAiInlineDiffActive(editor ?? null);
     // Re-render the toolbar when the selection / marks change so active-state

package/dist/react/useAiInlineDiff.d.ts

@@ -45,7 +45,23 @@ export interface UseAiInlineDiffOptions {
      *   - HTML       → DOMParser + ProseMirror's DOMParser.parse
      */
     parseSuggestion: (editor: Editor, value: string) => Slice | null;
+    /**
+     * 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.
+     */
+    resolveDisplayMode?: (editor: Editor) => 'inline' | 'lines';
 }
+/**
+ * Read the field's `.aiDiffView(...)` choice off the DOM — the
+ * `@pilotiq-pro/ai` field augmentation stamps `data-ai-diff-view` onto
+ * the FieldShell wrapper via `extraAttributes` (same channel as
+ * `data-ai-suggestions-mode`). Walks up from the field's named input.
+ * 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';
 /**
  * Returns whether a diff is currently active in the editor. Hosts use
  * this to gate the banner's UI between the legacy `onApplyWholeField`

package/dist/react/useAiInlineDiff.js

@@ -34,6 +34,24 @@ import { useEditorState } from '@tiptap/react';
 import { registerPendingSuggestionApplier, usePendingSuggestionsForField, useFormId, } from '@pilotiq/pilotiq/react';
 import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js';
 import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, } from '../surgicalOps.js';
+/**
+ * Read the field's `.aiDiffView(...)` choice off the DOM — the
+ * `@pilotiq-pro/ai` field augmentation stamps `data-ai-diff-view` onto
+ * the FieldShell wrapper via `extraAttributes` (same channel as
+ * `data-ai-suggestions-mode`). Walks up from the field's named input.
+ * Defaults to `'inline'` when no marker is present — including in
+ * open-core installs where the augmentation never runs.
+ */
+export function readAiDiffViewMarker(fieldName) {
+    if (typeof document === 'undefined')
+        return 'inline';
+    const els = document.getElementsByName(fieldName);
+    const el = els[0];
+    if (!(el instanceof Element))
+        return 'inline';
+    const wrapper = el.closest('[data-ai-diff-view]');
+    return wrapper?.getAttribute('data-ai-diff-view') === 'lines' ? 'lines' : 'inline';
+}
 /**
  * Returns whether a diff is currently active in the editor. Hosts use
  * this to gate the banner's UI between the legacy `onApplyWholeField`
@@ -60,6 +78,8 @@ export function useAiInlineDiff(editor, fieldName, options) {
     const formId = useFormId();
     const parseRef = useRef(options.parseSuggestion);
     useEffect(() => { parseRef.current = options.parseSuggestion; }, [options.parseSuggestion]);
+    const modeRef = useRef(options.resolveDisplayMode);
+    useEffect(() => { modeRef.current = options.resolveDisplayMode; }, [options.resolveDisplayMode]);
     // Track which ids we've handed off to the editor's diff extension
     // so we don't re-start the diff every render or for already-active
     // suggestions.
@@ -126,11 +146,12 @@ export function useAiInlineDiff(editor, fieldName, options) {
                 startedRef.current.add(s.id);
                 continue;
             }
+            const displayMode = modeRef.current?.(editor) ?? 'inline';
             if (surgical) {
                 const modifier = planSurgicalModifier(editor, surgical);
                 if (!modifier)
                     continue;
-                editor.commands.applySurgicalAiInlineDiff(s.id, modifier);
+                editor.commands.applySurgicalAiInlineDiff(s.id, modifier, displayMode);
                 startedRef.current.add(s.id);
                 continue;
             }
@@ -139,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);
+            editor.commands.startAiInlineDiff(s.id, slice, displayMode);
             startedRef.current.add(s.id);
         }
         // Cleanup: when a suggestion leaves the context AND we previously

package/package.json

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