feat(superdoc): fix scrollToComment + scrollToElement, add scrollToHeading

Three related fixes to the public scroll-to-X API surface, motivated
by an external integration where comment-panel click → editor scroll
was silently broken in flow layout and unreliable in paginated
layout.

  fix(superdoc): scrollToComment delegates to scrollToElement

  The previous implementation hand-rolled a DOM-only lookup
  (`root.querySelector('[data-comment-ids*="..."]')` →
  `scrollIntoView`). This had two failure modes:

    1. Paginated/presentation layout virtualises pages — comment
       highlights on offscreen pages aren't in the DOM, so the
       selector misses and the call returns false even though the
       comment exists in the document.
    2. When two `commentMark`s share a position, SuperDoc emits a
       single `.sd-editor-comment-highlight` element. Lookups for the
       suppressed thread silently fail in either layout.

  Route through the existing `scrollToElement` instead. It already
  does the right thing for both layouts (with the flow-layout
  fallback added below). The side-panel activation is preserved.

  fix(superdoc): scrollToElement falls back to body-editor in flow

  In flow / web layouts there is no `presentationEditor`, so
  `presentationEditor.scrollToElement` returned false unconditionally
  and the whole API was a no-op outside paginated mode.

  When the presentation path isn't available (or returns false), walk
  the ProseMirror doc directly: use `editor.commands.setCursorById`
  to resolve comment and tracked-change marks (it already does the
  right `findRangeById`-based lookup), then fall back to a one-pass
  attr-match for block IDs (`nodeId` / `sdBlockId` / `id` /
  `paraId`). Use `editor.getElementAtPos(pos)` for the DOM target so
  callers benefit from the companion `Editor.getElementAtPos` fix
  in the same branch.

  feat(superdoc): scrollToHeading(level, ordinal, options)

  New public API. Walks the ProseMirror doc counting headings of the
  requested level — recognises both the `heading` node type (level
  attr) and the OOXML import shape where headings are paragraphs
  with `paragraphProperties.styleId = 'HeadingN'` — and scrolls to
  the 1-based `ordinal`-th match.

  The walk targets a position INSIDE the heading paragraph's text
  content (the first text descendant), not the doc-level boundary
  before the paragraph. The presentation editor's layout fragment
  index only spans positions inside text content, so a boundary
  position misses every fragment and `scrollToPositionAsync` returns
  false. Walking one level in unblocks the print-mode path.

Verified against a Playwright probe on a 4-comment, 41-heading test
docx: flow comment-scroll went from 0/4 to 4/4 (`scrollToComment`);
heading scroll works 9/9 in both layouts at levels 1–3, ordinals
1–3. Print-mode comment scroll is unchanged at 3/4 (one residual
case where `scrollToPositionAsync` returns true but the painter
doesn't actually scroll; tracked separately as it's not in this
patch's scope).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: bjohas

packages/superdoc/src/core/SuperDoc.js

@@ -1323,27 +1323,29 @@ export class SuperDoc extends EventEmitter {
   /**
    * Scroll the document to a given comment by id.
    *
+   * Delegates to {@link scrollToElement} so it works in both flow and
+   * paginated layouts. The previous implementation looked up the highlight
+   * span via `[data-comment-ids*=...]` and called `scrollIntoView()` on it
+   * directly — that fails in paginated/print mode (the painter virtualises
+   * pages so the highlight may not be in the DOM) and also fails for marks
+   * SuperDoc didn't emit a visible highlight for (e.g. two marks sharing a
+   * single position). The unified path walks the ProseMirror doc for the
+   * mark and dispatches to the presentation editor where available,
+   * falling back to the body editor in flow mode.
+   *
    * @param {string} commentId The comment id
    * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition }} [options]
-   * @returns {boolean} Whether a matching element was found
+   * @returns {Promise<boolean>} Whether the comment was found and scrolled to
    */
-  scrollToComment(commentId, options = {}) {
+  async scrollToComment(commentId, options = {}) {
     const commentsConfig = this.config?.modules?.comments;
-    // `commentsConfig` can be `false | object | undefined`; `!commentsConfig`
-    // already covers both `false` and `undefined`, so the secondary
-    // `=== false` check below is redundant.
     if (!commentsConfig) return false;
     if (!commentId || typeof commentId !== 'string') return false;
 
-    const root = this.element || document;
-    const escaped = globalThis.CSS?.escape ? globalThis.CSS.escape(commentId) : commentId.replace(/"/g, '\\"');
-    const element = root.querySelector(`[data-comment-ids*="${escaped}"]`);
-    if (!element) return false;
-
-    const { behavior = 'smooth', block = 'start' } = options ?? {};
-    element.scrollIntoView({ behavior, block });
+    // Activate the thread in the side panel for visual continuity even if
+    // the scroll path subsequently bails.
     this.commentsStore?.setActiveComment?.(this, commentId);
-    return true;
+    return this.scrollToElement(commentId, options);
   }
 
   /**
@@ -1371,7 +1373,13 @@ export class SuperDoc extends EventEmitter {
    * change entityId. The method resolves the element type automatically
    * and scrolls to it.
    *
+   * In paginated (presentation) layouts this delegates to the
+   * presentation editor's `scrollToElement`. In flow / web layouts the
+   * presentation editor doesn't apply, so we fall back to walking the
+   * ProseMirror doc directly and scrolling the body editor's view.
+   *
    * @param {string} elementId - The element's stable ID.
+   * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition }} [options]
    * @returns {Promise<boolean>} Whether the element was found and scrolled to.
    *
    * @example
@@ -1381,13 +1389,180 @@ export class SuperDoc extends EventEmitter {
    * // Navigate to a comment by its entityId
    * await superdoc.scrollToElement('imported-25def254');
    */
-  async scrollToElement(elementId) {
+  async scrollToElement(elementId, options = {}) {
+    if (!elementId) return false;
     /** @type {RuntimeDocument[] | undefined} */
     const storeDocs = this.superdocStore?.documents;
     if (!storeDocs?.length) return false;
+
     const presentationEditor = storeDocs[0].getPresentationEditor?.();
-    if (!presentationEditor?.scrollToElement) return false;
-    return presentationEditor.scrollToElement(elementId);
+    if (presentationEditor?.scrollToElement) {
+      const ok = await presentationEditor.scrollToElement(elementId);
+      if (ok) return true;
+      // Otherwise: presentationEditor may have returned false because layout
+      // state isn't active (flow/web mode masquerading as presentation). Fall
+      // through to the body-editor path.
+    }
+
+    return this._scrollToElementInBodyEditor(elementId, options);
+  }
+
+  /**
+   * Flow-layout fallback for {@link scrollToElement}.
+   *
+   * The body editor IS the visible view in flow mode, so we walk PM for the
+   * target position and use the editor's own DOM-by-position helper, then
+   * scroll the resulting element into view. Tries comment / tracked-change
+   * marks (via the existing `setCursorById` command) first, then falls back
+   * to block-level node IDs (paragraphs, headings, tables) by attribute
+   * matching.
+   *
+   * @param {string} elementId
+   * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition }} [options]
+   * @returns {Promise<boolean>}
+   * @private
+   */
+  async _scrollToElementInBodyEditor(elementId, options = {}) {
+    const editor = this.activeEditor;
+    if (!editor?.state?.doc) return false;
+
+    let pos = null;
+
+    // 1. Try the comments-plugin command — handles commentMark, tracked
+    //    change marks, and commentRangeStart/End nodes uniformly.
+    const setCursorById = editor.commands?.setCursorById;
+    if (typeof setCursorById === 'function') {
+      if (setCursorById(elementId, { preferredActiveThreadId: elementId })) {
+        pos = editor.state.selection?.from;
+      }
+    }
+
+    // 2. Fall back to a single PM walk looking for matching block-level
+    //    id attributes (nodeId / sdBlockId / id / paraId).
+    if (pos == null || !Number.isFinite(pos)) {
+      editor.state.doc.descendants((node, p) => {
+        if (pos != null) return false;
+        const a = node.attrs || {};
+        const candidate = a.nodeId ?? a.sdBlockId ?? a.id ?? a.paraId;
+        if (candidate && candidate === elementId) {
+          pos = p;
+          return false;
+        }
+      });
+    }
+
+    if (pos == null || !Number.isFinite(pos)) return false;
+
+    const targetEl = typeof editor.getElementAtPos === 'function' ? editor.getElementAtPos(pos) : null;
+    if (!targetEl?.scrollIntoView) return false;
+
+    const { behavior = 'smooth', block = 'center' } = options;
+    try {
+      targetEl.scrollIntoView({ behavior, block, inline: 'nearest' });
+    } catch {
+      // Ignore scroll failures in environments with incomplete DOM APIs.
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Scroll to the Nth heading of a given level (1..6).
+   *
+   * In OOXML headings are paragraphs whose `paragraphProperties.styleId` is
+   * `Heading1`..`Heading6` (the schema also accepts a `heading` node type
+   * with a `level` attr for editor-native callers). This walks the doc in
+   * order, counts headings whose level matches, and scrolls to the
+   * 1-based `ordinal`-th one.
+   *
+   * @param {number} level    1..6
+   * @param {number} [ordinal=1]  1-based index among headings of that level
+   * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition }} [options]
+   * @returns {Promise<boolean>} Whether a matching heading was found and scrolled to
+   *
+   * @example
+   * // Scroll to the third top-level heading (a.k.a. chapter 3)
+   * await superdoc.scrollToHeading(1, 3);
+   */
+  async scrollToHeading(level, ordinal = 1, options = {}) {
+    if (!Number.isInteger(level) || level < 1 || level > 6) return false;
+    if (!Number.isInteger(ordinal) || ordinal < 1) return false;
+
+    const editor = this.activeEditor;
+    if (!editor?.state?.doc) return false;
+
+    let count = 0;
+    let foundPos = null;
+    let foundNode = null;
+    editor.state.doc.descendants((node, p) => {
+      if (foundPos !== null) return false;
+      const t = node.type?.name;
+      let nodeLevel = null;
+      if (t === 'heading' && node.attrs?.level) {
+        nodeLevel = Number(node.attrs.level);
+      } else if (t === 'paragraph') {
+        const styleId = node.attrs?.paragraphProperties?.styleId ?? node.attrs?.styleId ?? null;
+        if (typeof styleId === 'string') {
+          const m = styleId.match(/^Heading(\d)$/);
+          if (m) nodeLevel = Number(m[1]);
+        }
+      }
+      if (nodeLevel === level) {
+        count += 1;
+        if (count === ordinal) {
+          foundPos = p;
+          foundNode = node;
+          return false;
+        }
+      }
+    });
+
+    if (foundPos === null) return false;
+
+    // The position from descendants() is the doc-level boundary just
+    // BEFORE the heading paragraph. The presentation editor's
+    // layout-fragment index only covers positions INSIDE text content,
+    // so a doc-boundary position misses every fragment. Walk into the
+    // paragraph to find the first descendant that has actual text
+    // content (skipping bookmark markers, comment-range markers, etc.)
+    // and target that position instead.
+    if (foundNode && foundNode.content?.size > 0) {
+      let textInsidePos = null;
+      foundNode.descendants((child, offset) => {
+        if (textInsidePos !== null) return false;
+        if (child.isText && child.text && child.text.length > 0) {
+          // Position inside the paragraph = paragraph-start (foundPos+1)
+          // + descendant offset.
+          textInsidePos = foundPos + 1 + offset;
+          return false;
+        }
+      });
+      if (textInsidePos != null) foundPos = textInsidePos;
+    }
+
+    // Same dispatch as scrollToElement: presentation if available, else
+    // body-editor + DOM scrollIntoView.
+    const storeDocs = this.superdocStore?.documents;
+    const presentationEditor = storeDocs?.[0]?.getPresentationEditor?.();
+    if (typeof presentationEditor?.scrollToPositionAsync === 'function') {
+      const ok = await presentationEditor.scrollToPositionAsync(foundPos, {
+        behavior: options.behavior ?? 'auto',
+        block: options.block ?? 'center',
+      });
+      if (ok) return true;
+      // Fall through to body-editor path on layout-state miss.
+    }
+
+    const targetEl = typeof editor.getElementAtPos === 'function' ? editor.getElementAtPos(foundPos) : null;
+    if (!targetEl?.scrollIntoView) return false;
+
+    const { behavior = 'smooth', block = 'center' } = options;
+    try {
+      targetEl.scrollIntoView({ behavior, block, inline: 'nearest' });
+    } catch {
+      return false;
+    }
+    return true;
   }
 
   /**