feat(ui): add ui.contentControls.scrollIntoView (SD-3310)

Scroll a content control into view by id. The position is resolved from the
document model, not the painted DOM, so it works for off-screen controls -
the page mounts, then scrolls (mirrors the comment / tracked-change navigate
path). Scroll-only: focus/activate stays a separate concern.

Match the id with String() normalization so a control whose PM attr is numeric
still resolves from a consumer's string id (the list / painted data-sdt-id are
always strings).

Kept UI-local rather than widening the Document API address union, matching
how getRect resolves a content control. Updates the custom-UI docs and drops
the now-stale "no scroll-to-control" limit.

Author: caio-pizzol

apps/docs/editor/custom-ui/content-controls.mdx

@@ -39,14 +39,16 @@ The event tells you *what* is active; `getRect` tells you *where* to draw. `acti
 | Full live list and active stack | `ui.contentControls.observe()` / `getSnapshot()` |
 | Read one control | `ui.contentControls.get({ id })` |
 | Position your UI | `ui.contentControls.getRect({ id })` |
+| Scroll a control into view | `ui.contentControls.scrollIntoView({ id })` |
 | Hover and right-click hit-testing | `ui.viewport.entityAt()` / `contextAt()` |
 | Change content, tags, or locks | `editor.doc.contentControls.*` |
 
 `active` is the innermost control. For nested controls (an inline field inside a block clause), `activePath` carries the full stack, innermost first, so you don't also need `observe()` just to read the nesting.
 
+`scrollIntoView` resolves the control's position from the document, so it works even when the control is on a page that hasn't rendered yet (the page mounts, then scrolls). It scrolls only - it does not move the cursor into the control.
+
 ## Current limits
 
-- No built-in scroll-to-control. Read the position with `getRect()` and scroll your container.
 - No geometry-change subscription. Re-read `getRect()` on scroll, resize, and the `pagination-update` / `zoomChange` events.
 - No focus-by-id helper. Clicking a control in the document still drives selection.
 

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -3815,6 +3815,74 @@ export class PresentationEditor extends EventEmitter {
     return this.scrollToPosition(pos, options);
   }
 
+  /**
+   * Scroll a content control (SDT field/clause) into view by its id.
+   *
+   * Model-aware: the control's position is resolved from the document
+   * model, not the painted DOM, so this works even when the control sits
+   * on a not-yet-rendered (virtualized) page — `scrollToPositionAsync`
+   * mounts the page first, then scrolls. This is why it cannot reuse the
+   * paint-only `getEntityRects` rect path.
+   *
+   * Scroll-only: it does NOT move the selection or place the caret inside
+   * the control. Focusing/activating a control is a separate concern.
+   *
+   * v1 is body-only: it searches the body editor, and `scrollToPositionAsync`
+   * only scrolls in body mode, so a control inside a header/footer/note
+   * story does not resolve and returns `false`.
+   *
+   * @returns `true` once scrolled; `false` when the id is empty/unknown,
+   *   the control is in a non-body story, or no editor is available.
+   */
+  async scrollContentControlIntoView(
+    entityId: string,
+    options: { block?: 'start' | 'center' | 'end' | 'nearest'; behavior?: ScrollBehavior } = {},
+  ): Promise<boolean> {
+    const editor = this.#editor;
+    if (!editor || typeof entityId !== 'string' || entityId.length === 0) return false;
+
+    let found: { pos: number; node: ReturnType<typeof editor.state.doc.nodeAt> } | null = null;
+    editor.state.doc.descendants((node, pos) => {
+      if (found) return false;
+      const name = node.type?.name;
+      // Normalize the node id to a string before comparing. The id a
+      // consumer passes comes from the list / painted `data-sdt-id` (always
+      // a string), but the PM attr can be numeric, so a strict `===` would
+      // miss it. Matches the painted-DOM (`getRect`) id convention.
+      if ((name === 'structuredContent' || name === 'structuredContentBlock') && String(node.attrs?.id) === entityId) {
+        found = { pos, node };
+        return false;
+      }
+      return true;
+    });
+    if (!found) return false;
+
+    // Resolve the first *text* position inside the control. Only text
+    // positions reliably map to a layout fragment; wrapper boundaries
+    // (block, paragraph, run) sit between fragments and make
+    // `scrollToPositionAsync` fail. A deep `descendants` walk handles
+    // inline (`run > text`) and block (`paragraph > run > text`) nesting
+    // uniformly. `descendants` yields each child's position relative to
+    // the node's content, so the absolute position is `found.pos + 1 + rel`.
+    // Scroll-only: this does NOT move the selection or focus.
+    let contentPos = found.pos + 1;
+    let textFound = false;
+    found.node?.descendants((child, rel) => {
+      if (textFound) return false;
+      if (child.isText) {
+        contentPos = found.pos + 1 + rel;
+        textFound = true;
+        return false;
+      }
+      return true;
+    });
+
+    return this.scrollToPositionAsync(contentPos, {
+      behavior: options.behavior ?? 'smooth',
+      block: options.block ?? 'center',
+    });
+  }
+
   /**
    * Scrolls a specific page into view.
    *

packages/super-editor/src/ui/content-controls.test.ts

@@ -351,6 +351,51 @@ describe('ui.contentControls handle (SD-3157)', () => {
     ui.destroy();
   });
 
+  it('scrollIntoView({ id }) returns { success: false } for an empty or missing id without touching the presentation', async () => {
+    const { superdoc, editor } = makeStub({ items: [makeItem('sdt-1')] });
+    const ui = createSuperDocUI({ superdoc });
+    // Attach after construction: a `presentationEditor` present during the
+    // toolbar-snapshot build would need the full presentation interface.
+    const scroll = vi.fn().mockResolvedValue(true);
+    (editor as { presentationEditor?: unknown }).presentationEditor = { scrollContentControlIntoView: scroll };
+
+    expect(await ui.contentControls.scrollIntoView({ id: '' })).toEqual({ success: false });
+    // @ts-expect-error exercising the runtime guard for a missing id
+    expect(await ui.contentControls.scrollIntoView({})).toEqual({ success: false });
+    expect(scroll).not.toHaveBeenCalled();
+
+    ui.destroy();
+  });
+
+  it('scrollIntoView({ id }) returns { success: false } when the presentation layer is not ready', async () => {
+    // The stub editor has no `presentationEditor` (e.g. SSR / pre-mount).
+    const { superdoc } = makeStub({ items: [makeItem('sdt-1')] });
+    const ui = createSuperDocUI({ superdoc });
+
+    expect(await ui.contentControls.scrollIntoView({ id: 'sdt-1' })).toEqual({ success: false });
+
+    ui.destroy();
+  });
+
+  it('scrollIntoView({ id }) delegates to the presentation scroll with center/smooth defaults and maps the boolean to { success }', async () => {
+    const { superdoc, editor } = makeStub({ items: [makeItem('sdt-1')] });
+    const ui = createSuperDocUI({ superdoc });
+    const scroll = vi.fn().mockResolvedValue(true);
+    (editor as { presentationEditor?: unknown }).presentationEditor = { scrollContentControlIntoView: scroll };
+
+    expect(await ui.contentControls.scrollIntoView({ id: 'sdt-1' })).toEqual({ success: true });
+    expect(scroll).toHaveBeenCalledWith('sdt-1', { block: 'center', behavior: 'smooth' });
+
+    // Explicit options pass through; a falsy presentation result maps to failure.
+    scroll.mockResolvedValueOnce(false);
+    expect(await ui.contentControls.scrollIntoView({ id: 'sdt-1', block: 'start', behavior: 'auto' })).toEqual({
+      success: false,
+    });
+    expect(scroll).toHaveBeenLastCalledWith('sdt-1', { block: 'start', behavior: 'auto' });
+
+    ui.destroy();
+  });
+
   it('observe receives the snapshot value directly (parallel to comments/trackChanges)', async () => {
     // `observe` is the value-shaped alias of `subscribe`. The demo
     // (`field-chip.ts`) consumes it directly, so an explicit test

packages/super-editor/src/ui/create-super-doc-ui.ts

@@ -2250,6 +2250,43 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
         target: { kind: 'entity', entityType: 'contentControl', entityId: id },
       });
     },
+    async scrollIntoView({
+      id,
+      block,
+      behavior,
+    }: {
+      id: string;
+      block?: 'start' | 'center' | 'end' | 'nearest';
+      behavior?: 'auto' | 'smooth';
+    }): Promise<ScrollIntoViewOutput> {
+      if (typeof id !== 'string' || id.length === 0) return { success: false };
+      // Resolve through the host editor — `presentationEditor` lives on the
+      // body/host, not a routed child story editor. Same posture as
+      // `viewport.getRect` / `runScrollIntoView`. The model-aware scroll is
+      // body-only, so a control in a header/footer/note resolves to a no-op
+      // `{ success: false }`. We call the presentation method directly rather
+      // than routing a content-control target through `viewport.scrollIntoView`
+      // — content controls are UI-local and deliberately absent from the
+      // Document API `ScrollIntoViewInput` address union (mirrors `getRect`).
+      const editor = resolveHostEditor(superdoc);
+      const presentation = editor?.presentationEditor as
+        | {
+            scrollContentControlIntoView?: (
+              id: string,
+              opts: { block?: 'start' | 'center' | 'end' | 'nearest'; behavior?: 'auto' | 'smooth' },
+            ) => Promise<boolean>;
+          }
+        | null
+        | undefined;
+      if (!presentation || typeof presentation.scrollContentControlIntoView !== 'function') {
+        return { success: false };
+      }
+      const ok = await presentation.scrollContentControlIntoView(id, {
+        block: block ?? 'center',
+        behavior: behavior ?? 'smooth',
+      });
+      return { success: Boolean(ok) };
+    },
   };
 
   // Resolve a metadata id (= the SDT's w:tag) to the SDT's content-

packages/super-editor/src/ui/types.ts

@@ -462,9 +462,10 @@ export interface ContentControlsSlice {
  * directly, matching the architectural rule that this handle is a UI
  * surface, not a parallel mutation contract.
  *
- * The handle does not include `scrollIntoView` in v1: that path
- * widens `ui.viewport.scrollIntoView` and is a separate slice from
- * `ui.viewport.getRect` (SD-3156).
+ * The handle includes `scrollIntoView` via a dedicated model-aware
+ * path. It does NOT widen `ui.viewport.scrollIntoView`: content controls
+ * stay UI-local and out of the Document API address union, mirroring how
+ * `getRect` resolves a content control through a UI-local address.
  */
 export interface ContentControlsHandle {
   /** Snapshot the current content-controls slice synchronously. */
@@ -496,6 +497,28 @@ export interface ContentControlsHandle {
    * failure reason).
    */
   getRect(input: { id: string }): ViewportRectResult;
+  /**
+   * Scroll the content control identified by `id` into view. The
+   * control's position is resolved from the document model (not the
+   * painted DOM), so it works even when the control sits on a
+   * not-yet-rendered (virtualized) page — the page is mounted, then
+   * scrolled. Scroll-only: it does not move the selection or place the
+   * caret inside the control.
+   *
+   * Returns the same `ScrollIntoViewOutput` shape as
+   * `ui.viewport.scrollIntoView`: `{ success: true }` once scrolled, or
+   * `{ success: false }` when `id` is empty/unknown or the presentation
+   * layer isn't ready. `block` defaults to `'center'`, `behavior` to
+   * `'smooth'`.
+   *
+   * v1 is body-only: a control inside a header/footer/note story does
+   * not resolve and returns `{ success: false }`.
+   */
+  scrollIntoView(input: {
+    id: string;
+    block?: 'start' | 'center' | 'end' | 'nearest';
+    behavior?: 'auto' | 'smooth';
+  }): Promise<import('@superdoc/document-api').ScrollIntoViewOutput>;
 }
 
 /**