@pilotiq/tiptap 3.11.0 → 3.13.0

package/dist/extensions/DragHandleExtension.js

@@ -34,11 +34,14 @@ export const DragHandleExtension = Extension.create({
     },
 });
 function createDragHandleView(view) {
-    const handle = document.createElement('button');
-    handle.type = 'button';
+    // A <div> (not <button>): a button grabs DOM focus on click, which yanks
+    // focus out of the editor so a follow-up Backspace/Delete on the selected
+    // block goes nowhere. A div doesn't steal focus, so click-to-select works.
+    const handle = document.createElement('div');
+    handle.setAttribute('role', 'button');
     handle.setAttribute('data-pilotiq-drag-handle', '');
     handle.setAttribute('contenteditable', 'false');
-    handle.setAttribute('aria-label', 'Drag block');
+    handle.setAttribute('aria-label', 'Drag or select block');
     handle.setAttribute('draggable', 'true');
     handle.style.cssText = [
         'position: absolute',
@@ -149,16 +152,30 @@ function createDragHandleView(view) {
     const onDragEnd = () => {
         handle.style.cursor = 'grab';
     };
+    // A plain click (no drag) selects the hovered block as a NodeSelection, so
+    // the whole block can be deleted (Backspace / Delete) or replaced — the only
+    // affordance for removing atom-ish custom blocks (FAQ, callout, grid, …).
+    const onClick = (event) => {
+        event.preventDefault();
+        if (activePos === null)
+            return;
+        if (!view.state.doc.nodeAt(activePos))
+            return;
+        view.dispatch(view.state.tr.setSelection(NodeSelection.create(view.state.doc, activePos)));
+        view.focus();
+    };
     view.dom.addEventListener('mousemove', onMouseMove);
     view.dom.addEventListener('mouseleave', onMouseLeave);
     handle.addEventListener('dragstart', onDragStart);
     handle.addEventListener('dragend', onDragEnd);
+    handle.addEventListener('click', onClick);
     return {
         destroy: () => {
             view.dom.removeEventListener('mousemove', onMouseMove);
             view.dom.removeEventListener('mouseleave', onMouseLeave);
             handle.removeEventListener('dragstart', onDragStart);
             handle.removeEventListener('dragend', onDragEnd);
+            handle.removeEventListener('click', onClick);
             handle.remove();
         },
     };

package/dist/extensions/SlashCommandExtension.js

@@ -137,6 +137,77 @@ export function buildSlashItems(blocks, mergeTags, query, insert) {
             searchKey: 'grid columns layout 3 three split',
             command: ({ editor, range }) => editor.chain().focus().deleteRange(range).setGrid({ columns: 3 }).run(),
         },
+        // Inline content blocks — labelled, editable-in-place regions (nodes in
+        // contentBlocks.ts). Inserted via insertContent; no custom commands.
+        {
+            key: 'key-takeaways', label: 'Key takeaways', icon: '🔑', group: 'Content',
+            searchKey: 'key takeaways points highlights tldr',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({
+                type: 'keyTakeaways',
+                content: [{ type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] }],
+            }).run(),
+        },
+        {
+            key: 'summary', label: 'Summary', icon: '📝', group: 'Content',
+            searchKey: 'summary tldr abstract overview',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'summary', content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'faq', label: 'FAQ', icon: '❓', group: 'Content',
+            searchKey: 'faq questions answers frequently asked',
+            command: ({ editor, range }) => {
+                editor.chain().focus().deleteRange(range).insertContent({
+                    type: 'faq',
+                    content: [
+                        {
+                            type: 'faqItem',
+                            content: [{ type: 'faqQuestion' }, { type: 'faqAnswer', content: [{ type: 'paragraph' }] }],
+                        },
+                    ],
+                }).run();
+                // insertContent leaves the cursor in the answer — move it into the first
+                // question. Resolve the enclosing faqItem and select its question start
+                // (before(faqItem) +1 into the item +1 into the question = +2).
+                const { $from } = editor.state.selection;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'faqItem') {
+                        editor.chain().setTextSelection($from.before(d) + 2).focus().run();
+                        break;
+                    }
+                }
+            },
+        },
+        {
+            key: 'pros-cons', label: 'Pros & cons', icon: '⚖️', group: 'Content',
+            searchKey: 'pros cons advantages disadvantages comparison',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({
+                type: 'prosCons',
+                content: [
+                    { type: 'prosColumn', content: [{ type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] }] },
+                    { type: 'consColumn', content: [{ type: 'bulletList', content: [{ type: 'listItem', content: [{ type: 'paragraph' }] }] }] },
+                ],
+            }).run(),
+        },
+        {
+            key: 'alert-info', label: 'Alert: Info', icon: 'ⓘ', group: 'Content',
+            searchKey: 'alert callout notice info note',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'info' }, content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'alert-warning', label: 'Alert: Warning', icon: '⚠️', group: 'Content',
+            searchKey: 'alert callout notice warning caution danger',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'warning' }, content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'alert-success', label: 'Alert: Success', icon: '✅', group: 'Content',
+            searchKey: 'alert callout notice success ok done',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'success' }, content: [{ type: 'paragraph' }] }).run(),
+        },
+        {
+            key: 'alert-tip', label: 'Alert: Tip', icon: '💡', group: 'Content',
+            searchKey: 'alert callout notice tip hint',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'alert', attrs: { type: 'tip' }, content: [{ type: 'paragraph' }] }).run(),
+        },
         // Image entry shares the toolbar's attach-files dialog; only surfaced
         // when the panel has wired an `UploadAdapter`. Without one, the dialog
         // would post to a missing endpoint — the slash item degrades the same

package/dist/extensions/contentBlocks.d.ts

@@ -0,0 +1,19 @@
+import { Node, Extension } from '@tiptap/core';
+export declare const KeyTakeaways: Node<any, any>;
+export declare const Summary: Node<any, any>;
+export declare const Faq: Node<any, any>;
+export declare const FaqItem: Node<any, any>;
+export declare const FaqQuestion: Node<any, any>;
+export declare const FaqAnswer: Node<any, any>;
+export declare const ALERT_TYPES: readonly ["info", "warning", "success", "tip"];
+export type AlertType = (typeof ALERT_TYPES)[number];
+/** Exported so `render.ts` shares the same coercion at the server boundary. */
+export declare function coerceAlertType(value: unknown): AlertType;
+export declare const Alert: Node<any, any>;
+export declare const ProsCons: Node<any, any>;
+export declare const ProsColumn: Node<any, any>;
+export declare const ConsColumn: Node<any, any>;
+export declare const ContentBlockKeymap: Extension<any, any>;
+/** All inline content-block extensions — registered in the editor's list. */
+export declare const contentBlockNodes: (Node<any, any> | Extension<any, any>)[];
+//# sourceMappingURL=contentBlocks.d.ts.map

package/dist/extensions/contentBlocks.js

@@ -0,0 +1,281 @@
+import { Node, Extension, mergeAttributes } from '@tiptap/core';
+/** A labelled region whose body is ordinary editable content (`block+`). */
+function labeledBlock(spec) {
+    return Node.create({
+        name: spec.name,
+        group: 'block',
+        content: 'block+',
+        defining: true,
+        parseHTML() {
+            return [{ tag: `div[data-type="${spec.name}"]`, contentElement: '.pilotiq-block-body' }];
+        },
+        renderHTML({ HTMLAttributes }) {
+            return [
+                'div',
+                mergeAttributes(HTMLAttributes, { 'data-type': spec.name, class: spec.cssClass }),
+                ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, spec.label],
+                ['div', { class: 'pilotiq-block-body' }, 0],
+            ];
+        },
+    });
+}
+export const KeyTakeaways = labeledBlock({ name: 'keyTakeaways', label: 'Key takeaways', cssClass: 'pilotiq-key-takeaways' });
+export const Summary = labeledBlock({ name: 'summary', label: 'Summary', cssClass: 'pilotiq-summary' });
+// ── FAQ — structured question / answer items ──
+//
+// `faq` > `faqItem+`; each item is a `faqQuestion` (inline text, "Q" marker) +
+// a `faqAnswer` (block+, "A" marker). Authoring: Enter in a question jumps to
+// its answer; Cmd/Ctrl-Enter inside an item adds a new Q&A item below.
+const NEW_FAQ_ITEM = {
+    type: 'faqItem',
+    content: [{ type: 'faqQuestion' }, { type: 'faqAnswer', content: [{ type: 'paragraph' }] }],
+};
+export const Faq = Node.create({
+    name: 'faq',
+    group: 'block',
+    content: 'faqItem+',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faq"]', contentElement: '.pilotiq-block-body' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'faq', class: 'pilotiq-faq' }),
+            ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, 'FAQ'],
+            ['div', { class: 'pilotiq-block-body' }, 0],
+        ];
+    },
+    addKeyboardShortcuts() {
+        return {
+            // Enter drives the whole Q&A flow:
+            //   • in a question → jump to its answer;
+            //   • in an answer  → finish it and start a NEW Q&A item below (focus its
+            //     question). Repeatable: question → Enter → answer → Enter → next.
+            // (Shift-Enter still inserts a line break within an answer.)
+            Enter: ({ editor }) => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty)
+                    return false;
+                for (let d = $from.depth; d > 0; d--) {
+                    const name = $from.node(d).type.name;
+                    if (name === 'faqQuestion') {
+                        return editor.chain().setTextSelection($from.after(d) + 1).focus().run();
+                    }
+                    if (name === 'faqAnswer') {
+                        const after = $from.after(d - 1); // position just after the faqItem
+                        return editor.chain().insertContentAt(after, NEW_FAQ_ITEM).setTextSelection(after + 2).focus().run();
+                    }
+                }
+                return false;
+            },
+            // Cmd/Ctrl-Enter anywhere in an item also adds a new Q&A item below.
+            'Mod-Enter': ({ editor }) => {
+                const { $from } = editor.state.selection;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'faqItem') {
+                        const after = $from.after(d);
+                        return editor.chain().insertContentAt(after, NEW_FAQ_ITEM).setTextSelection(after + 2).focus().run();
+                    }
+                }
+                return false;
+            },
+            // Backspace in an EMPTY question removes that whole Q&A item (and the
+            // whole FAQ block if it was the only item) — like emptying a list item.
+            Backspace: ({ editor }) => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty)
+                    return false;
+                let qDepth = -1;
+                for (let d = $from.depth; d > 0; d--) {
+                    if ($from.node(d).type.name === 'faqQuestion') {
+                        qDepth = d;
+                        break;
+                    }
+                }
+                if (qDepth === -1)
+                    return false;
+                if ($from.node(qDepth).content.size > 0)
+                    return false; // question not empty → normal backspace
+                const faqDepth = qDepth - 2;
+                const itemDepth = qDepth - 1;
+                const faq = $from.node(faqDepth);
+                const faqStart = $from.before(faqDepth);
+                if (faq.childCount <= 1) {
+                    // last item → remove the whole FAQ block
+                    return editor.chain().deleteRange({ from: faqStart, to: faqStart + faq.nodeSize }).focus().run();
+                }
+                // remove just this Q&A item; drop the cursor into a neighbouring item
+                const itemStart = $from.before(itemDepth);
+                const itemEnd = itemStart + $from.node(itemDepth).nodeSize;
+                const caret = $from.index(faqDepth) === 0 ? faqStart + 3 : itemStart - 1;
+                return editor.chain().deleteRange({ from: itemStart, to: itemEnd }).setTextSelection(caret).focus().run();
+            },
+        };
+    },
+});
+export const FaqItem = Node.create({
+    name: 'faqItem',
+    group: 'faqItem',
+    content: 'faqQuestion faqAnswer',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faqItem"]' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'faqItem', class: 'pilotiq-faq-item' }), 0];
+    },
+});
+export const FaqQuestion = Node.create({
+    name: 'faqQuestion',
+    content: 'inline*',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faqQuestion"]', contentElement: '.pilotiq-faq-text' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'faqQuestion', class: 'pilotiq-faq-question' }),
+            ['span', { class: 'pilotiq-faq-marker', contenteditable: 'false' }, 'Q'],
+            ['span', { class: 'pilotiq-faq-text' }, 0],
+        ];
+    },
+});
+export const FaqAnswer = Node.create({
+    name: 'faqAnswer',
+    content: 'block+',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="faqAnswer"]', contentElement: '.pilotiq-faq-body' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'faqAnswer', class: 'pilotiq-faq-answer' }),
+            ['span', { class: 'pilotiq-faq-marker', contenteditable: 'false' }, 'A'],
+            ['div', { class: 'pilotiq-faq-body' }, 0],
+        ];
+    },
+});
+// ── Alert — a typed notice; the label IS the type (Info/Warning/Success/Tip) ──
+export const ALERT_TYPES = ['info', 'warning', 'success', 'tip'];
+const ALERT_LABEL = { info: 'Info', warning: 'Warning', success: 'Success', tip: 'Tip' };
+/** Exported so `render.ts` shares the same coercion at the server boundary. */
+export function coerceAlertType(value) {
+    return ALERT_TYPES.includes(String(value)) ? value : 'info';
+}
+export const Alert = Node.create({
+    name: 'alert',
+    group: 'block',
+    content: 'block+',
+    defining: true,
+    addAttributes() {
+        return {
+            type: {
+                default: 'info',
+                parseHTML: (el) => coerceAlertType(el.getAttribute('data-alert-type')),
+                renderHTML: (attrs) => ({ 'data-alert-type': coerceAlertType(attrs['type']) }),
+            },
+        };
+    },
+    parseHTML() {
+        return [{ tag: 'div[data-type="alert"]', contentElement: '.pilotiq-block-body' }];
+    },
+    renderHTML({ node, HTMLAttributes }) {
+        const type = coerceAlertType(node.attrs['type']);
+        return [
+            'div',
+            mergeAttributes(HTMLAttributes, { 'data-type': 'alert', class: `pilotiq-alert pilotiq-alert-${type}` }),
+            ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, ALERT_LABEL[type]],
+            ['div', { class: 'pilotiq-block-body' }, 0],
+        ];
+    },
+});
+// ── Pros & cons — two labelled columns (each a `block+` body, list by default) ──
+export const ProsCons = Node.create({
+    name: 'prosCons',
+    group: 'block',
+    content: 'prosColumn consColumn',
+    defining: true,
+    parseHTML() {
+        return [{ tag: 'div[data-type="prosCons"]' }];
+    },
+    renderHTML({ HTMLAttributes }) {
+        return ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'prosCons', class: 'pilotiq-pros-cons' }), 0];
+    },
+});
+function prosConsColumn(name, label, cssClass) {
+    return Node.create({
+        name,
+        group: 'prosConsColumn',
+        content: 'block+',
+        defining: true,
+        parseHTML() {
+            return [{ tag: `div[data-type="${name}"]`, contentElement: '.pilotiq-block-body' }];
+        },
+        renderHTML({ HTMLAttributes }) {
+            return [
+                'div',
+                mergeAttributes(HTMLAttributes, { 'data-type': name, class: cssClass }),
+                ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, label],
+                ['div', { class: 'pilotiq-block-body' }, 0],
+            ];
+        },
+    });
+}
+export const ProsColumn = prosConsColumn('prosColumn', 'Pros', 'pilotiq-pros');
+export const ConsColumn = prosConsColumn('consColumn', 'Cons', 'pilotiq-cons');
+// ── Keyboard: delete a whole content block with Backspace at its start ──
+//
+// Custom blocks have no inline "remove" affordance, and Backspace inside a
+// nested block (FAQ etc.) just deletes characters. So: Backspace at the very
+// start of a content block removes the entire block — the reliable, keyboard
+// way to delete one (the drag handle's click-to-select is the mouse way).
+// faq is excluded — it handles Backspace itself (empty-question → remove item).
+const DELETABLE_BLOCKS = new Set(['summary', 'keyTakeaways', 'alert', 'prosCons']);
+export const ContentBlockKeymap = Extension.create({
+    name: 'pilotiqContentBlockKeymap',
+    addKeyboardShortcuts() {
+        return {
+            Backspace: ({ editor }) => {
+                const { $from, empty } = editor.state.selection;
+                if (!empty || $from.parentOffset !== 0)
+                    return false;
+                for (let d = 1; d <= $from.depth; d++) {
+                    const node = $from.node(d);
+                    if (!DELETABLE_BLOCKS.has(node.type.name))
+                        continue;
+                    // Only when the cursor is at the block's very start (first child all
+                    // the way down) — otherwise let Backspace delete normally.
+                    let atStart = true;
+                    for (let dd = $from.depth; dd > d; dd--) {
+                        if ($from.index(dd - 1) !== 0) {
+                            atStart = false;
+                            break;
+                        }
+                    }
+                    if (!atStart)
+                        return false;
+                    const start = $from.before(d);
+                    return editor.chain().deleteRange({ from: start, to: start + node.nodeSize }).focus().run();
+                }
+                return false;
+            },
+        };
+    },
+});
+/** All inline content-block extensions — registered in the editor's list. */
+export const contentBlockNodes = [
+    KeyTakeaways,
+    Summary,
+    Faq,
+    FaqItem,
+    FaqQuestion,
+    FaqAnswer,
+    Alert,
+    ProsCons,
+    ProsColumn,
+    ConsColumn,
+    ContentBlockKeymap,
+];

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { RichTextField, DEFAULT_TOOLBAR_GROUPS, DEFAULT_TEXT_COLORS, DEFAULT_HIGHLIGHT_COLORS, type ColorSwatch, type RichTextAttachmentVisibility, type RichTextFieldMeta, type RichTextStorage, type ToolbarButtonId, type ToolbarGroups, } from './RichTextField.js';
 export { Block, type BlockMeta } from './Block.js';
+export { defaultBlocks, faqBlock, alertBlock, summaryBlock, keyTakeawaysBlock, prosConsBlock, } from './blocks/index.js';
 export { MentionProvider, type MentionItem, type MentionProviderMeta, } from './MentionProvider.js';
 export { registerTiptap } from './register.js';
 export { createPlainTextEditor, plainTextOf, plainTextToDoc, type PlainTextEditorOptions, } from './PlainTextEditor.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { RichTextField, DEFAULT_TOOLBAR_GROUPS, DEFAULT_TEXT_COLORS, DEFAULT_HIGHLIGHT_COLORS, } from './RichTextField.js';
 export { Block } from './Block.js';
+export { defaultBlocks, faqBlock, alertBlock, summaryBlock, keyTakeawaysBlock, prosConsBlock, } from './blocks/index.js';
 export { MentionProvider, } from './MentionProvider.js';
 export { registerTiptap } from './register.js';
 export { createPlainTextEditor, plainTextOf, plainTextToDoc, } from './PlainTextEditor.js';

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

@@ -13,11 +13,12 @@ import Image from '@tiptap/extension-image';
 import { Table, TableRow, TableCell, TableHeader } from '@tiptap/extension-table';
 import { Details, DetailsSummary, DetailsContent } from '@tiptap/extension-details';
 import { Grid, GridColumn } from '../extensions/GridExtension.js';
+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 } 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';
@@ -276,6 +277,9 @@ function ClientEditor(props) {
             // `pilotiq-grid-cols-N`.
             Grid,
             GridColumn,
+            // Inline content blocks — labelled, editable-in-place regions:
+            // Key takeaways / Summary / FAQ / Alert / Pros & cons.
+            ...contentBlockNodes,
             Placeholder.configure({ placeholder: placeholder ?? 'Start writing…' }),
             // BlockNodeExtension carries the block registry on its options —
             // NodeViews mount in a separate React tree and can't see context.
@@ -490,6 +494,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/dist/render.d.ts

@@ -26,8 +26,11 @@
  *           / image.src + alt + title + width + height
  *           / tableCell.colspan + rowspan + colwidth (also tableHeader)
  *           / mergeTag.id / mention.id + label + trigger
- *   custom blocks — render to `<div data-type="..." data-attrs="...">` so
- *           consumers can replay or style by data-type.
+ *   default blocks — the `pilotiqBlock` node's built-in types (faq / alert /
+ *           summary / key-takeaways / pros-cons) render to semantic
+ *           `<div class="pilotiq-...">` markup; consumers own the CSS.
+ *   custom blocks — any other type renders to `<div data-type="..."
+ *           data-attrs="...">` so consumers can replay or style by data-type.
  */
 export interface RenderRichTextOptions {
     /**