@pilotiq/tiptap 3.16.0 → 3.17.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @pilotiq/tiptap
 
+## 3.17.0
+
+### Minor Changes
+
+- 4930902: Add semantic landmark content blocks and a content-preserving `wrap_blocks` surgical op.
+
+  - **`intro` block** — a labelled ("Introduction") landmark for the start of an article. Exported as `Intro` and registered in `contentBlockNodes`; rendered read-side via `renderRichTextToHtml`; available from the slash menu.
+  - **`summary` block variant** — `summary` gains a `variant: 'section' | 'article'` attr. `section` (default) keeps the "Summary" label for a mid-content paragraph summary; `article` labels it "In summary" for the end-of-article conclusion landmark. The block gear menu offers a Section/Article toggle and the slash menu gains an "Article summary" entry.
+  - **`wrap_blocks` surgical op** (`planWrapBlocks` + `useAiInlineDiff`) — wraps a contiguous run of top-level blocks `[fromIndex..toIndex]` into a single container node (`intro` / `summary` / `keyTakeaways`) using ProseMirror's own model, with no HTML round-trip, so marks and attrs are preserved verbatim. Lets agents turn unstructured prose into a landmark block without rewriting its text.
+
+  These establish document landmarks so block-placement agents can position content deterministically (e.g. key-takeaways after the intro, FAQ after the conclusion).
+
 ## 3.16.0
 
 ### Minor Changes

package/dist/extensions/SlashCommandExtension.js

@@ -139,6 +139,11 @@ export function buildSlashItems(blocks, mergeTags, query, insert) {
         },
         // Inline content blocks — labelled, editable-in-place regions (nodes in
         // contentBlocks.ts). Inserted via insertContent; no custom commands.
+        {
+            key: 'intro', label: 'Intro', icon: '✍️', group: 'Content',
+            searchKey: 'intro introduction lead opening preamble',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'intro', content: [{ type: 'paragraph' }] }).run(),
+        },
         {
             key: 'key-takeaways', label: 'Key takeaways', icon: '🔑', group: 'Content',
             searchKey: 'key takeaways points highlights tldr',
@@ -152,6 +157,13 @@ export function buildSlashItems(blocks, mergeTags, query, insert) {
             searchKey: 'summary tldr abstract overview',
             command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'summary', content: [{ type: 'paragraph' }] }).run(),
         },
+        {
+            // Same `summary` node, `article` variant — the end-of-article summary
+            // landmark (renders "In summary", sits before the FAQ).
+            key: 'article-summary', label: 'Article summary', icon: '📋', group: 'Content',
+            searchKey: 'article summary conclusion wrap up in summary closing landmark',
+            command: ({ editor, range }) => editor.chain().focus().deleteRange(range).insertContent({ type: 'summary', attrs: { variant: 'article' }, content: [{ type: 'paragraph' }] }).run(),
+        },
         {
             key: 'faq', label: 'FAQ', icon: '❓', group: 'Content',
             searchKey: 'faq questions answers frequently asked',

package/dist/extensions/contentBlocks.d.ts

@@ -2,6 +2,7 @@ import { Node, Extension } from '@tiptap/core';
 export { ALERT_VARIANTS, ALERT_VARIANT_LABEL, coerceAlertType, type AlertType } from './alertVariants.js';
 export declare const KeyTakeaways: Node<any, any>;
 export declare const Summary: Node<any, any>;
+export declare const Intro: Node<any, any>;
 export declare const Faq: Node<any, any>;
 export declare const FaqItem: Node<any, any>;
 export declare const FaqQuestion: Node<any, any>;

package/dist/extensions/contentBlocks.js

@@ -42,7 +42,8 @@ function widthAttribute() {
  * editor renders `LabeledBlockNodeView` (shared across every labelled block —
  * label + gear menu + width); the `renderHTML` below is the serialized/read
  * shape and mirrors it: outer anchor + inner `.pilotiq-block-content` wrapper.
- * `label`/`cssClass` ride `addOptions()` so the shared NodeView can read them.
+ * `label`/`cssClass`/`plain`/`variant` ride `addOptions()` so the shared
+ * NodeView can read them.
  */
 function labeledBlock(spec) {
     return Node.create({
@@ -51,20 +52,40 @@ function labeledBlock(spec) {
         content: 'block+',
         defining: true,
         addOptions() {
-            return { label: spec.label, cssClass: spec.cssClass };
+            return { label: spec.label, cssClass: spec.cssClass, plain: spec.plain ?? false, variant: spec.variant ?? null };
         },
         addAttributes() {
-            return { width: widthAttribute() };
+            const attrs = { width: widthAttribute() };
+            if (spec.variant) {
+                const v = spec.variant;
+                attrs['variant'] = {
+                    default: v.default,
+                    parseHTML: (el) => el.getAttribute('data-variant') ?? v.default,
+                    renderHTML: (a) => a['variant'] && a['variant'] !== v.default ? { 'data-variant': a['variant'] } : {},
+                };
+            }
+            return attrs;
         },
         parseHTML() {
             return [{ tag: `div[data-type="${spec.name}"]`, contentElement: '.pilotiq-block-body' }];
         },
-        renderHTML({ HTMLAttributes }) {
+        renderHTML({ node, HTMLAttributes }) {
+            // Plain (intro): no label, no content wrapper — body sits in the anchor.
+            if (spec.plain) {
+                return [
+                    'div',
+                    mergeAttributes(HTMLAttributes, { 'data-type': spec.name, class: spec.cssClass }),
+                    ['div', { class: 'pilotiq-block-body' }, 0],
+                ];
+            }
+            const label = spec.variant
+                ? (spec.variant.labels[node.attrs['variant']] ?? spec.label)
+                : spec.label;
             return [
                 'div',
                 mergeAttributes(HTMLAttributes, { 'data-type': spec.name, class: spec.cssClass }),
                 ['div', { class: 'pilotiq-block-content' },
-                    ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, spec.label],
+                    ['div', { class: 'pilotiq-block-label', contenteditable: 'false' }, label],
                     ['div', { class: 'pilotiq-block-body' }, 0],
                 ],
             ];
@@ -75,7 +96,20 @@ function labeledBlock(spec) {
     });
 }
 export const KeyTakeaways = labeledBlock({ name: 'keyTakeaways', label: 'Key takeaways', cssClass: 'pilotiq-key-takeaways' });
-export const Summary = labeledBlock({ name: 'summary', label: 'Summary', cssClass: 'pilotiq-summary' });
+// `summary` has two purposes, switched by the `variant` attr: `section` (a
+// paragraph/section summary used inside the body) and `article` (the
+// end-of-article summary landmark that sits before the FAQ). One block, two
+// labels — the Normalizer + future block agents read `variant` for placement.
+export const Summary = labeledBlock({
+    name: 'summary',
+    label: 'Summary',
+    cssClass: 'pilotiq-summary',
+    variant: { default: 'section', labels: { section: 'Summary', article: 'In summary' } },
+});
+// `intro` is the article's opening landmark — a labelled region ("Introduction"
+// above the body, like Summary / Key takeaways) so the landmark is visible to
+// authors and block agents (e.g. key-takeaways) know to place after it.
+export const Intro = labeledBlock({ name: 'intro', label: 'Introduction', cssClass: 'pilotiq-intro' });
 // ── FAQ — structured question / answer items ──
 //
 // `faq` > `faqItem+`; each item is a `faqQuestion` (inline text, "Q" marker) +
@@ -525,7 +559,7 @@ export const ConsColumn = prosConsColumn('consColumn', 'Cons', 'pilotiq-cons');
 // 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']);
+const DELETABLE_BLOCKS = new Set(['summary', 'keyTakeaways', 'intro', 'alert', 'prosCons']);
 export const ContentBlockKeymap = Extension.create({
     name: 'pilotiqContentBlockKeymap',
     addKeyboardShortcuts() {
@@ -561,6 +595,7 @@ export const ContentBlockKeymap = Extension.create({
 export const contentBlockNodes = [
     KeyTakeaways,
     Summary,
+    Intro,
     Faq,
     FaqItem,
     FaqQuestion,

package/dist/index.d.ts

@@ -11,5 +11,5 @@ 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';
-export { contentBlockNodes, Faq, FaqItem, FaqQuestion, FaqAnswer, Alert, AlertTitle, AlertBody, Summary, KeyTakeaways, ProsCons, ProsColumn, ConsColumn, ContentBlockKeymap, ALERT_VARIANTS, ALERT_VARIANT_LABEL, coerceAlertType, type AlertType, } from './extensions/contentBlocks.js';
+export { contentBlockNodes, Intro, Faq, FaqItem, FaqQuestion, FaqAnswer, Alert, AlertTitle, AlertBody, Summary, KeyTakeaways, ProsCons, ProsColumn, ConsColumn, ContentBlockKeymap, ALERT_VARIANTS, ALERT_VARIANT_LABEL, coerceAlertType, type AlertType, } from './extensions/contentBlocks.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -11,9 +11,9 @@ 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';
-// Default content-block node specs (FAQ / Alert / Summary / Key takeaways /
+// Default content-block node specs (Intro / FAQ / Alert / Summary / Key takeaways /
 // Pros & cons). `contentBlockNodes` is the exact array `TiptapEditor` registers,
 // so a consumer can build a headless editor whose schema matches the live
 // editor — e.g. to parse the content-block HTML or drive the surgical-op
 // planners (`planInsertBlockBefore` & co.) in a test, without mounting React.
-export { contentBlockNodes, Faq, FaqItem, FaqQuestion, FaqAnswer, Alert, AlertTitle, AlertBody, Summary, KeyTakeaways, ProsCons, ProsColumn, ConsColumn, ContentBlockKeymap, ALERT_VARIANTS, ALERT_VARIANT_LABEL, coerceAlertType, } from './extensions/contentBlocks.js';
+export { contentBlockNodes, Intro, Faq, FaqItem, FaqQuestion, FaqAnswer, Alert, AlertTitle, AlertBody, Summary, KeyTakeaways, ProsCons, ProsColumn, ConsColumn, ContentBlockKeymap, ALERT_VARIANTS, ALERT_VARIANT_LABEL, coerceAlertType, } from './extensions/contentBlocks.js';

package/dist/react/LabeledBlockNodeView.d.ts

@@ -3,14 +3,22 @@ import { type NodeViewProps } from '@tiptap/react';
 /**
  * Shared React NodeView for the simple **labelled** content blocks — the ones
  * that are just a non-editable label above a `block+` body (Key takeaways,
- * Summary). They rhyme structurally, so they share ONE NodeView instead of a
- * bespoke component each; the per-block `label` + `cssClass` ride the node's
- * `addOptions()` (see `labeledBlock()` in `extensions/contentBlocks.ts`).
+ * Summary, Intro). They rhyme structurally, so they share ONE NodeView instead
+ * of a bespoke component each; the per-block `label` / `cssClass` / `plain` /
+ * `variant` ride the node's `addOptions()` (see `labeledBlock()` in
+ * `extensions/contentBlocks.ts`).
+ *
+ * Three shapes, one component:
+ *  - **labelled** (default) — non-editable label above the body.
+ *  - **variant** (summary) — label resolved from the active `variant` attr,
+ *    plus a "Type" toggle in the gear menu (e.g. Summary ↔ In summary).
+ *  - **plain** (intro) — no label, no max-width wrapper: ordinary prose with a
+ *    faint hover-revealed affordance so authors can still see it's a landmark.
+ *    The read-side renderer emits no label for plain blocks.
  *
  * The two-layer shell (full-width anchor + gear + the inner
  * `.pilotiq-block-content` that carries the max-width / centering) lives in the
- * shared `BlockGearShell`, alongside the Width gear setting. This component
- * only supplies the label + body content hole.
+ * shared `BlockGearShell`, alongside the Width gear setting.
  */
 export declare function LabeledBlockNodeView({ node, updateAttributes, editor, extension }: NodeViewProps): ReactElement;
 //# sourceMappingURL=LabeledBlockNodeView.d.ts.map

package/dist/react/LabeledBlockNodeView.js

@@ -4,16 +4,44 @@ import { BlockGearShell } from './BlockGearShell.js';
 /**
  * Shared React NodeView for the simple **labelled** content blocks — the ones
  * that are just a non-editable label above a `block+` body (Key takeaways,
- * Summary). They rhyme structurally, so they share ONE NodeView instead of a
- * bespoke component each; the per-block `label` + `cssClass` ride the node's
- * `addOptions()` (see `labeledBlock()` in `extensions/contentBlocks.ts`).
+ * Summary, Intro). They rhyme structurally, so they share ONE NodeView instead
+ * of a bespoke component each; the per-block `label` / `cssClass` / `plain` /
+ * `variant` ride the node's `addOptions()` (see `labeledBlock()` in
+ * `extensions/contentBlocks.ts`).
+ *
+ * Three shapes, one component:
+ *  - **labelled** (default) — non-editable label above the body.
+ *  - **variant** (summary) — label resolved from the active `variant` attr,
+ *    plus a "Type" toggle in the gear menu (e.g. Summary ↔ In summary).
+ *  - **plain** (intro) — no label, no max-width wrapper: ordinary prose with a
+ *    faint hover-revealed affordance so authors can still see it's a landmark.
+ *    The read-side renderer emits no label for plain blocks.
  *
  * The two-layer shell (full-width anchor + gear + the inner
  * `.pilotiq-block-content` that carries the max-width / centering) lives in the
- * shared `BlockGearShell`, alongside the Width gear setting. This component
- * only supplies the label + body content hole.
+ * shared `BlockGearShell`, alongside the Width gear setting.
  */
 export function LabeledBlockNodeView({ node, updateAttributes, editor, extension }) {
-    const { label, cssClass } = extension.options;
-    return (_jsx(BlockGearShell, { node: node, editor: editor, updateAttributes: updateAttributes, cssClass: cssClass, settingsLabel: label + ' settings', children: _jsxs("div", { className: "pilotiq-block-content", children: [_jsx("div", { className: "pilotiq-block-label", contentEditable: false, children: label }), _jsx(NodeViewContent, { className: "pilotiq-block-body" })] }) }));
+    const opts = extension.options;
+    // Plain (intro): render as ordinary prose. The faint affordance is editor-
+    // only and hover-revealed (mirrors the gear's hover reveal in BlockGearShell).
+    if (opts.plain) {
+        return (_jsxs(BlockGearShell, { node: node, editor: editor, updateAttributes: updateAttributes, cssClass: opts.cssClass, settingsLabel: opts.label + ' settings', children: [editor.isEditable && (_jsx("div", { contentEditable: false, className: 'pointer-events-none absolute -top-2.5 left-0 text-[0.65rem] font-medium uppercase tracking-wide ' +
+                        'text-muted-foreground opacity-0 transition-opacity [.' + opts.cssClass + ':hover_&]:opacity-60', children: opts.label })), _jsx(NodeViewContent, { className: "pilotiq-block-body" })] }));
+    }
+    const label = opts.variant
+        ? (opts.variant.labels[node.attrs['variant']] ?? opts.label)
+        : opts.label;
+    // Multi-variant blocks (summary) expose a "Type" select in the gear menu.
+    const extraSettings = opts.variant
+        ? [{
+                kind: 'select',
+                key: 'variant',
+                label: 'Type',
+                value: node.attrs['variant'] ?? opts.variant.default,
+                options: Object.entries(opts.variant.labels).map(([value, lbl]) => ({ value, label: lbl })),
+                onChange: (v) => updateAttributes({ variant: v }),
+            }]
+        : [];
+    return (_jsx(BlockGearShell, { node: node, editor: editor, updateAttributes: updateAttributes, cssClass: opts.cssClass, settingsLabel: label + ' settings', extraSettings: extraSettings, children: _jsxs("div", { className: "pilotiq-block-content", children: [_jsx("div", { className: "pilotiq-block-label", contentEditable: false, children: label }), _jsx(NodeViewContent, { className: "pilotiq-block-body" })] }) }));
 }

package/dist/react/useAiInlineDiff.js

@@ -33,7 +33,7 @@ import { useEffect, useRef } from 'react';
 import { useEditorState } from '@tiptap/react';
 import { registerPendingSuggestionApplier, usePendingSuggestionsForField, useFormId, } from '@pilotiq/pilotiq/react';
 import { aiInlineDiffPluginKey } from '../extensions/AiInlineDiffExtension.js';
-import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, } from '../surgicalOps.js';
+import { planReplaceBlock, planInsertBlockBefore, planDeleteBlock, planUpdateBlockMark, planWrapBlocks, } from '../surgicalOps.js';
 /**
  * Read the field's `.aiDiffView(...)` choice off the DOM — the
  * `@pilotiq-pro/ai` field augmentation stamps `data-ai-diff-view` onto
@@ -231,6 +231,22 @@ function parseSurgicalOp(obj) {
         }
         case 'delete_block':
             return { op, blockIndex };
+        case 'wrap_blocks': {
+            const toIndex = obj['toIndex'];
+            const wrapperType = obj['wrapperType'];
+            if (typeof toIndex !== 'number')
+                return null;
+            if (typeof wrapperType !== 'string')
+                return null;
+            const attrs = obj['attrs'];
+            return {
+                op,
+                blockIndex,
+                toIndex,
+                wrapperType,
+                ...(attrs && typeof attrs === 'object' ? { attrs: attrs } : {}),
+            };
+        }
         case 'update_block_mark': {
             const mark = obj['mark'];
             const range = obj['range'];
@@ -283,6 +299,7 @@ function planOp(editor, op) {
         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);
+        case 'wrap_blocks': return planWrapBlocks(editor, op.blockIndex, op.toIndex, op.wrapperType, op.attrs);
     }
 }
 /**

package/dist/render.js

@@ -146,7 +146,8 @@ function renderNode(node, opts) {
         case 'grid': return renderGrid(n, opts);
         case 'gridColumn': return wrap('div', n, opts);
         case 'keyTakeaways': return labeledBlockHtml('pilotiq-key-takeaways', 'Key takeaways', n, opts, true);
-        case 'summary': return labeledBlockHtml('pilotiq-summary', 'Summary', n, opts, true);
+        case 'summary': return renderSummary(n, opts);
+        case 'intro': return labeledBlockHtml('pilotiq-intro', 'Introduction', n, opts, true);
         case 'faq': return renderFaqNode(n, opts);
         case 'faqItem': return renderFaqItem(n, opts);
         case 'faqQuestion': return `<summary class="pilotiq-faq-question">${renderChildren(n, opts)}</summary>`;
@@ -362,7 +363,7 @@ function clampGridColumnsForRender(raw) {
 // Mirrors the editor's `renderHTML` (extensions/contentBlocks.ts): a small
 // label above an editable body. Consumer owns the `pilotiq-*` CSS. Covers
 // keyTakeaways / summary / faq / alert / prosCons (+ pros/cons columns).
-function labeledBlockHtml(cssClass, label, n, opts, wrap = false) {
+function labeledBlockHtml(cssClass, label, n, opts, wrap = false, extraAttr = '') {
     const inner = `<div class="pilotiq-block-label">${escapeHtml(label)}</div>` +
         `<div class="pilotiq-block-body">${renderChildren(n, opts)}</div>`;
     // Top-level labelled blocks (summary / keyTakeaways) carry the gear menu, so
@@ -370,9 +371,19 @@ function labeledBlockHtml(cssClass, label, n, opts, wrap = false) {
     // `.pilotiq-block-content` that holds the max-width / width toggle. Columns
     // inside Pros & cons render flat (no width of their own).
     if (!wrap)
-        return `<div class="${cssClass}">${inner}</div>`;
+        return `<div class="${cssClass}"${extraAttr}>${inner}</div>`;
     const width = n.attrs?.['width'] === 'full' ? ' data-width="full"' : '';
-    return `<div class="${cssClass}"${width}><div class="pilotiq-block-content">${inner}</div></div>`;
+    return `<div class="${cssClass}"${width}${extraAttr}><div class="pilotiq-block-content">${inner}</div></div>`;
+}
+// `summary` carries a `variant` attr (`section` default | `article`). The label
+// + a `data-variant` styling hook differ per variant; otherwise it's the shared
+// labelled-block shape. The Normalizer + block agents use `article` as the
+// end-of-article landmark (sits before the FAQ).
+function renderSummary(n, opts) {
+    const isArticle = n.attrs?.['variant'] === 'article';
+    const label = isArticle ? 'In summary' : 'Summary';
+    const extraAttr = isArticle ? ' data-variant="article"' : '';
+    return labeledBlockHtml('pilotiq-summary', label, n, opts, true, extraAttr);
 }
 // Pros & cons — two labelled columns. Same two-layer anchor as the labelled
 // blocks: a full-width outer (`.pilotiq-pros-cons`) + an inner

package/dist/surgicalOps.d.ts

@@ -42,6 +42,21 @@ export declare function planInsertBlockBefore(editor: Editor, blockIndex: number
  * delete the last remaining block.
  */
 export declare function planDeleteBlock(editor: Editor, blockIndex: number): TransactionModifier | null;
+/**
+ * Wrap the contiguous top-level blocks `[fromIndex .. toIndex]` (inclusive)
+ * into a single `wrapperType` container node — content-preserving, no HTML
+ * round-trip. Used by the Normalizer agent to turn a run of prose into a
+ * landmark block (`intro` / `summary` / `keyTakeaways`) WITHOUT rewriting the
+ * text (the existing replace/insert ops would need the slice re-serialized to
+ * HTML, which has no clean utility here and risks dropping marks/attrs).
+ *
+ * Returns `null` for an out-of-range or inverted range, an unknown wrapper
+ * type, or when the wrapper's content schema can't hold the wrapped blocks
+ * (`createAndFill` yields null). Batches sort DESC by `fromIndex` (carried as
+ * `blockIndex` by the caller) so disjoint wraps planned against the original
+ * doc stay position-valid.
+ */
+export declare function planWrapBlocks(editor: Editor, fromIndex: number, toIndex: number, wrapperType: string, attrs?: Record<string, unknown>): TransactionModifier | null;
 export interface BlockMarkRange {
     /** 0-based text offset from the start of the block's content. */
     from: number;

package/dist/surgicalOps.js

@@ -113,6 +113,51 @@ export function planDeleteBlock(editor, blockIndex) {
     const end = start + doc.child(blockIndex).nodeSize;
     return (tr) => { tr.delete(start, end); };
 }
+/**
+ * Wrap the contiguous top-level blocks `[fromIndex .. toIndex]` (inclusive)
+ * into a single `wrapperType` container node — content-preserving, no HTML
+ * round-trip. Used by the Normalizer agent to turn a run of prose into a
+ * landmark block (`intro` / `summary` / `keyTakeaways`) WITHOUT rewriting the
+ * text (the existing replace/insert ops would need the slice re-serialized to
+ * HTML, which has no clean utility here and risks dropping marks/attrs).
+ *
+ * Returns `null` for an out-of-range or inverted range, an unknown wrapper
+ * type, or when the wrapper's content schema can't hold the wrapped blocks
+ * (`createAndFill` yields null). Batches sort DESC by `fromIndex` (carried as
+ * `blockIndex` by the caller) so disjoint wraps planned against the original
+ * doc stay position-valid.
+ */
+export function planWrapBlocks(editor, fromIndex, toIndex, wrapperType, attrs) {
+    const doc = editor.state.doc;
+    if (!Number.isInteger(fromIndex) || !Number.isInteger(toIndex))
+        return null;
+    if (fromIndex < 0 || toIndex < fromIndex || toIndex >= doc.childCount)
+        return null;
+    const nodeType = editor.schema.nodes[wrapperType];
+    if (!nodeType)
+        return null;
+    const start = blockStartPos(doc, fromIndex);
+    if (start === null)
+        return null;
+    const children = [];
+    let end = start;
+    for (let i = fromIndex; i <= toIndex; i++) {
+        const child = doc.child(i);
+        children.push(child);
+        end += child.nodeSize;
+    }
+    // Build the wrapper with the existing blocks as its content; bail if the
+    // schema rejects them (so a bad request never produces an invalid doc).
+    // Pass the raw node array (NOT a separately-imported `Fragment`) — `createAndFill`
+    // builds the fragment with the EDITOR's prosemirror-model, so the wrapped nodes
+    // and the wrapper share one model instance. Mixing a `Fragment` from this
+    // module's own `@tiptap/pm/model` import throws "Can not convert … to a Fragment"
+    // whenever two prosemirror-model copies are loaded (e.g. a yalc-linked build).
+    const wrapped = nodeType.createAndFill(attrs ?? null, children);
+    if (!wrapped)
+        return null;
+    return (tr) => { tr.replaceWith(start, end, wrapped); };
+}
 /**
  * Apply or remove an inline mark on a range *within* the block at
  * `blockIndex`. `range.from` / `range.to` are text offsets relative to

package/package.json

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