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

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

@@ -652,4 +652,55 @@ describe('create.contentControl validation', () => {
     });
     expect(adapter.create).toHaveBeenCalled();
   });
+
+  it('rejects at and target together', () => {
+    expect(() =>
+      executeCreateContentControl(createAdapter, {
+        kind: 'inline',
+        target: validTarget,
+        at: {
+          kind: 'selection',
+          start: { kind: 'text', blockId: 'p1', offset: 0 },
+          end: { kind: 'text', blockId: 'p1', offset: 5 },
+        },
+      } 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: {
+          kind: 'bogus',
+          start: { kind: 'text', blockId: 'p1', offset: 0 },
+          end: { kind: 'text', blockId: 'p1', offset: 5 },
+        },
+      } as any),
+    ).toThrow(/valid SelectionTarget/);
+  });
+
+  it('accepts valid at (SelectionTarget)', () => {
+    const adapter = { create: mock(noop) } as any;
+    executeCreateContentControl(adapter, {
+      kind: 'inline',
+      at: {
+        kind: 'selection',
+        start: { kind: 'text', blockId: 'p1', offset: 0 },
+        end: { kind: 'text', blockId: 'p1', offset: 5 },
+      },
+      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';
@@ -1036,6 +1037,22 @@ export function executeCreateContentControl(
   if (input.target !== undefined) {
     validateCCTarget(input.target, 'create.contentControl');
   }
+  if (input.at !== undefined) {
+    if (input.target !== undefined) {
+      throw new DocumentApiValidationError(
+        'INVALID_INPUT',
+        `create.contentControl: "at" and "target" are mutually exclusive — provide one or neither.`,
+        { field: 'at' },
+      );
+    }
+    if (!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,8 @@ export interface CreateContentControlInput {
   kind: NodeKind;
   controlType?: ContentControlType;
   target?: ContentControlTarget;
+  /** Text range to wrap in the new content control. Mutually exclusive with `target`. */
+  at?: SelectionTarget;
   tag?: string;
   alias?: string;
   lockMode?: LockMode;

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,6 +1855,15 @@ 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);
+    }
+
     // Default: delegate to the editor command (inserts at current selection).
     if (contentText !== undefined) {
       if (input.kind === 'block') {