feat(document-api): add scope: block to format.apply for full-paragraph formatting

Author: tupizz

packages/document-api/src/contract/schemas.ts

@@ -4878,8 +4878,14 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
               description:
                 'Set paragraph alignment on the target block(s). Can be combined with inline formatting in the same step.',
             },
+            scope: {
+              type: 'string',
+              enum: ['match', 'block'],
+              description:
+                'When "block", inline formatting expands to cover the entire parent paragraph(s), not just the matched text. Use "block" after markdown inserts to format whole paragraphs with a short identifying pattern. Default: "match".',
+            },
           },
-          [], // Neither field is individually required — at least one must be present
+          [], // No individual field is required — at least one must be present
         ),
       },
       ['id', 'op', 'where', 'args'],

packages/document-api/src/types/mutation-plan.types.ts

@@ -119,6 +119,8 @@ export type StyleApplyStep = {
   args: {
     inline?: InlineRunPatch;
     alignment?: 'left' | 'center' | 'right' | 'justify';
+    /** When "block", inline formatting expands to cover the entire parent textblock(s), not just the matched range. Default: "match". */
+    scope?: 'match' | 'block';
   };
 };
 

packages/sdk/tools/prompt-templates/system-prompt-core.md

@@ -146,17 +146,19 @@ superdoc_edit({action: "insert", type: "markdown",
   value: "# Executive Summary\n\nThis agreement sets forth the principal terms..."})
 ```
 
-**Step 3: Apply ALL formatting in a SINGLE superdoc_mutations call.** Each format.apply step accepts both `inline` (text styles) AND `alignment` (paragraph alignment) — one step per block.
+**Step 3: Apply ALL formatting in a SINGLE superdoc_mutations call.** Each format.apply step accepts `inline` (text styles), `alignment` (paragraph alignment), and `scope` — combine them all in one step per block.
+
+ALWAYS use `scope: "block"` after markdown inserts. This makes the formatting cover the entire paragraph, not just the matched text pattern. The pattern only needs to uniquely identify which paragraph — a short prefix is enough.
 
 Example: if the document has centered, underlined, 12pt headings and justified 12pt body text:
 ```
 superdoc_mutations({action: "apply", atomic: true, steps: [
-  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, underline: true}, alignment: "center"}},
-  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "This agreement sets forth"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, color: "#000000"}, alignment: "justify"}}
+  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, underline: true}, alignment: "center", scope: "block"}},
+  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "This agreement sets forth"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, color: "#000000"}, alignment: "justify", scope: "block"}}
 ]})
 ```
 
-CRITICAL: Do NOT guess formatting values. Copy them from the existing document blocks you read in step 1. Use ONE format.apply step per block with both `inline` and `alignment` combined.
+CRITICAL: Do NOT guess formatting values. Copy them from the existing document blocks you read in step 1. Use `scope: "block"` so the formatting covers the ENTIRE paragraph, not just the matched text.
 
 Total: 3 calls (read + insert + format-all-in-one-batch). Never more.
 

packages/sdk/tools/prompt-templates/system-prompt-mcp-header.md

@@ -30,14 +30,14 @@ superdoc_edit({action: "insert", type: "markdown",
 ```
 Valid placements: "before", "after", "insideStart", "insideEnd". Without target, content appends at document end.
 
-**Formatting — each format.apply step accepts both `inline` AND `alignment`:**
+**Formatting — use `scope: "block"` to format entire paragraphs after markdown insert:**
 ```
 superdoc_mutations({action: "apply", atomic: true, steps: [
-  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, underline: true}, alignment: "center"}},
-  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "body paragraph text"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12}, alignment: "justify"}}
+  {id: "f1", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "Executive Summary"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12, underline: true}, alignment: "center", scope: "block"}},
+  {id: "f2", op: "format.apply", where: {by: "select", select: {type: "text", pattern: "This agreement sets forth"}, require: "first"}, args: {inline: {fontFamily: "Times New Roman, serif", fontSize: 12}, alignment: "justify", scope: "block"}}
 ]})
 ```
-One format.apply step per block. Combine `inline` (text styles) and `alignment` (paragraph alignment) in the same step. Do NOT use separate superdoc_format calls.
+One format.apply step per block. Combine `inline`, `alignment`, and `scope: "block"` in each step. The pattern only needs to identify which paragraph — `scope: "block"` formats the entire paragraph, not just the matched text.
 
 **When to use which tool:**
 - Creating headings, paragraphs, or any block content → `superdoc_edit` with type "markdown" (preferred, even for a single heading + paragraph)

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/executor.ts

@@ -841,15 +841,45 @@ function applyAlignmentToRange(tr: Transaction, absFrom: number, absTo: number,
   return changed;
 }
 
+/**
+ * Expands a position range to cover the full content of all textblock nodes
+ * that overlap with it. Used when scope: "block" is set on a format.apply step.
+ */
+function expandToBlockBoundaries(
+  doc: import('prosemirror-model').Node,
+  from: number,
+  to: number,
+): { from: number; to: number } {
+  let expandedFrom = from;
+  let expandedTo = to;
+
+  doc.nodesBetween(from, to, (node, pos) => {
+    if (!node.isTextblock) return;
+    const blockContentStart = pos + 1;
+    const blockContentEnd = pos + node.nodeSize - 1;
+    expandedFrom = Math.min(expandedFrom, blockContentStart);
+    expandedTo = Math.max(expandedTo, blockContentEnd);
+  });
+
+  return { from: expandedFrom, to: expandedTo };
+}
+
 export function executeStyleApply(
   editor: Editor,
   tr: Transaction,
   target: CompiledRangeTarget,
   step: StyleApplyStep,
   mapping: Mapping,
 ): { changed: boolean } {
-  const absFrom = mapping.map(target.absFrom);
-  const absTo = mapping.map(target.absTo);
+  let absFrom = mapping.map(target.absFrom);
+  let absTo = mapping.map(target.absTo);
+
+  // Expand to full block boundaries when scope is "block"
+  if (step.args.scope === 'block') {
+    const expanded = expandToBlockBoundaries(tr.doc, absFrom, absTo);
+    absFrom = expanded.from;
+    absTo = expanded.to;
+  }
 
   let changed = false;
 
@@ -1002,8 +1032,14 @@ export function executeSpanStyleApply(
   // Apply marks uniformly across the full span
   const firstSeg = target.segments[0];
   const lastSeg = target.segments[target.segments.length - 1];
-  const absFrom = mapping.map(firstSeg.absFrom, 1);
-  const absTo = mapping.map(lastSeg.absTo, -1);
+  let absFrom = mapping.map(firstSeg.absFrom, 1);
+  let absTo = mapping.map(lastSeg.absTo, -1);
+
+  if (step.args.scope === 'block') {
+    const expanded = expandToBlockBoundaries(tr.doc, absFrom, absTo);
+    absFrom = expanded.from;
+    absTo = expanded.to;
+  }
 
   let changed = false;