feat(document-api): support wrapping text ranges via contentControls.create (SD-2566)

packages/document-api/src/content-controls/content-controls.test.ts

@@ -606,6 +606,11 @@ describe('patchRawProperties validates patch op shapes', () => {
 
 describe('create.contentControl validation', () => {
   const createAdapter = { create: mock(noop) } as any;
+  const validAt = {
+    kind: 'selection' as const,
+    start: { kind: 'text' as const, blockId: 'p1', offset: 0 },
+    end: { kind: 'text' as const, blockId: 'p1', offset: 5 },
+  };
 
   it('rejects null input', () => {
     expect(() => executeCreateContentControl(createAdapter, null as any)).toThrow(/non-null object/);
@@ -652,4 +657,43 @@ describe('create.contentControl validation', () => {
     });
     expect(adapter.create).toHaveBeenCalled();
   });
+
+  it('rejects at and target together', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        target: validTarget,
+        at: validAt,
+      } as any),
+    ).toThrow(/mutually exclusive/);
+  });
+
+  it('rejects invalid at (missing start)', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        at: { kind: 'selection', end: { kind: 'text', blockId: 'p1', offset: 5 } },
+      } as any),
+    ).toThrow(/valid SelectionTarget/);
+  });
+
+  it('rejects invalid at (wrong kind)', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        at: { ...validAt, kind: 'bogus' },
+      } as any),
+    ).toThrow(/valid SelectionTarget/);
+  });
+
+  it('accepts valid at (SelectionTarget)', () => {
+    const adapter = { create: mock(noop) } as any;
+    executeCreateContentControl(adapter, {
+      kind: 'inline',
+      at: validAt,
+      tag: 'name',
+      alias: 'Name',
+    });
+    expect(adapter.create).toHaveBeenCalled();
+  });
 });

packages/document-api/src/content-controls/content-controls.ts

@@ -9,6 +9,7 @@
 import type { MutationOptions } from '../write/write.js';
 import { DocumentApiValidationError } from '../errors.js';
 import { isRecord, isInteger } from '../validation-primitives.js';
+import { isSelectionTarget } from '../validation/selection-target-validator.js';
 import { LOCK_MODES, CONTENT_CONTROL_TYPES, CONTENT_CONTROL_APPEARANCES } from './content-controls.types.js';
 import type { NodeKind } from '../types/base.js';
 import { NODE_KINDS } from '../types/base.js';
@@ -1033,9 +1034,23 @@ export function executeCreateContentControl(
       { field: 'lockMode', value: input.lockMode },
     );
   }
+  if (input.at !== undefined && input.target !== undefined) {
+    throw new DocumentApiValidationError(
+      'INVALID_INPUT',
+      `create.contentControl: "at" and "target" are mutually exclusive — provide one or neither.`,
+      { field: 'at' },
+    );
+  }
   if (input.target !== undefined) {
     validateCCTarget(input.target, 'create.contentControl');
   }
+  if (input.at !== undefined && !isSelectionTarget(input.at)) {
+    throw new DocumentApiValidationError(
+      'INVALID_INPUT',
+      `create.contentControl: "at" must be a valid SelectionTarget with kind "selection", start, and end.`,
+      { field: 'at', value: input.at },
+    );
+  }
   if (input.content !== undefined && typeof input.content !== 'string') {
     throw new DocumentApiValidationError(
       'INVALID_INPUT',

packages/document-api/src/content-controls/content-controls.types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { NodeKind } from '../types/base.js';
+import type { SelectionTarget } from '../types/address.js';
 import type { ReceiptFailure } from '../types/receipt.js';
 
 // ---------------------------------------------------------------------------
@@ -206,6 +207,12 @@ export interface CreateContentControlInput {
   kind: NodeKind;
   controlType?: ContentControlType;
   target?: ContentControlTarget;
+  /**
+   * Text range to wrap in the new content control. Mutually exclusive with `target`.
+   * When `content` is also provided, it replaces the selected text inside the new SDT.
+   * When `content` is omitted, the existing text in the range becomes the SDT content.
+   */
+  at?: SelectionTarget;
   tag?: string;
   alias?: string;
   lockMode?: LockMode;

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

@@ -610,7 +610,7 @@
 const trackedChangeAddressSchema = ref('TrackedChangeAddress');
 const entityAddressSchema = ref('EntityAddress');
 const selectionTargetSchema = ref('SelectionTarget');
 const targetLocatorSchema = ref('TargetLocator');
 const deleteBehaviorSchema = ref('DeleteBehavior');
 const resolvedHandleSchema = ref('ResolvedHandle');
 const pageInfoSchema = ref('PageInfo');
@@ -885,7 +885,7 @@
   text: { type: 'string' },
 });
 
 const nodeInfoSchema: JsonSchema = {
   type: 'object',
   required: ['nodeType', 'kind'],
   properties: {
@@ -901,7 +901,7 @@
   additionalProperties: false,
 };
 
 const matchContextSchema = objectSchema(
   {
     address: nodeAddressSchema,
     snippet: { type: 'string' },
@@ -912,7 +912,7 @@
   ['address', 'snippet', 'highlightRange'],
 );
 
 const unknownNodeDiagnosticSchema = objectSchema(
   {
     message: { type: 'string' },
     address: nodeAddressSchema,
@@ -2190,6 +2190,7 @@
           kind: { enum: ['block', 'inline'] },
           controlType: { type: 'string' },
           target: contentControlTargetSchema,
+          at: selectionTargetSchema,
           tag: { type: 'string' },
           alias: { type: 'string' },
           lockMode: { enum: ['unlocked', 'sdtLocked', 'contentLocked', 'sdtContentLocked'] },

packages/super-editor/src/editors/v1/document-api-adapters/plan-engine/content-controls-wrappers.ts

@@ -13,6 +13,7 @@
  */
 
 import { Fragment, type Node as ProseMirrorNode, type Schema } from 'prosemirror-model';
+import { TextSelection } from 'prosemirror-state';
 import type { Editor } from '../../core/Editor.js';
 import type { ProseMirrorJSON } from '../../core/types/EditorTypes.js';
 import type {
@@ -89,6 +90,7 @@ import type {
 import { DocumentApiAdapterError } from '../errors.js';
 import { executeDomainCommand } from './plan-wrappers.js';
 import { clearIndexCache } from '../helpers/index-cache.js';
+import { resolveSelectionTarget } from '../helpers/selection-target-resolver.js';
 
 // Shared helpers — single source of truth for SDT logic
 import {
@@ -1853,30 +1855,44 @@ function createWrapper(
       return true;
     }
 
+    // When a SelectionTarget is provided, set the editor selection to that
+    // range so insertStructuredContentInline/Block wraps the targeted text.
+    if (input.at) {
+      const { absFrom, absTo } = resolveSelectionTarget(editor, input.at);
+      const { tr } = editor.state;
+      tr.setSelection(TextSelection.create(tr.doc, absFrom, absTo));
+      dispatchTransaction(editor, tr);
+    }
+
+    // Re-acquire the command so it picks up fresh editor state — important
+    // when `at` dispatched a selection change above.
+    const cmd = editor.commands?.[commandName];
+    if (typeof cmd !== 'function') return false;
+
     // Default: delegate to the editor command (inserts at current selection).
     if (contentText !== undefined) {
       if (input.kind === 'block') {
         if (isCheckboxCreate) {
           return Boolean(
-            insertCmd({
+            cmd({
               attrs,
               json: { type: 'paragraph', content: [buildCheckboxTextJson(checkboxSymbol)] },
             }),
           );
         }
         return Boolean(
-          insertCmd({
+          cmd({
             attrs,
             json: { type: 'paragraph', content: [{ type: 'text', text: contentText }] },
           }),
         );
       }
       if (isCheckboxCreate) {
-        return Boolean(insertCmd({ attrs, json: buildCheckboxTextJson(checkboxSymbol) }));
+        return Boolean(cmd({ attrs, json: buildCheckboxTextJson(checkboxSymbol) }));
       }
-      return Boolean(insertCmd({ attrs, text: contentText }));
+      return Boolean(cmd({ attrs, text: contentText }));
     }
-    return Boolean(insertCmd({ attrs }));
+    return Boolean(cmd({ attrs }));
   });
 }