feat(navigation): universal scrollToElement API (SD-2519) (#2772)

* feat(navigation): add universal navigateTo for blocks, comments, and tracked changes (SD-2519)

Add navigateTo(address) to PresentationEditor and SuperDoc that navigates
to any element by its ID:

- BlockNavigationAddress: navigate to paragraphs, headings, tables, images
  by nodeId using the existing block index (O(1) lookup)
- CommentAddress: navigate to comments via setCursorById with active thread
  activation
- TrackedChangeAddress: navigate to tracked changes with cascading fallback
  (setCursorById → rawId → scroll to position)

All navigation building blocks already existed — this wires them behind a
single unified API. Replaces the need for text-search workarounds in RAG
citation linking.

* feat(navigation): add scrollToElement — single-ID navigation for any element (SD-2519)

Add scrollToElement(elementId) to PresentationEditor and SuperDoc.
Takes any element ID (paragraph nodeId, comment entityId, tracked change
entityId) and resolves the element type automatically:

1. Tries block index lookup (O(1) — paragraphs, headings, tables)
2. Falls back to comment/tracked-change mark lookup
3. Falls back to tracked change canonical ID resolution

Consumer usage:
  await superdoc.scrollToElement('5AF80E61');  // any ID, any type

navigateTo(address) is preserved as the typed foundation.
scrollToElement is the DX layer for the common case (RAG citations,
search results, cross-references).

Also extracts #scrollToBlockCandidate as shared helper for block
position resolution — handles the layout engine's content-position
mapping (skips zero-width annotation nodes like bookmarkStart).

* refactor(navigation): simplify API — scrollToElement delegates to navigateTo (SD-2519)

Address review findings:
- scrollToElement now delegates to navigateTo instead of reimplementing
  the same block/comment/tracked-change lookup cascade
- Remove navigateTo from SuperDoc public API — scrollToElement(id) is
  the sole public entry point. navigateTo stays on PresentationEditor
  as the typed internal dispatcher.
- Remove duplicate JSDoc address types from superdoc package
- Fix tracked change fallback: check scrollToPositionAsync return value
  instead of returning true unconditionally

* test(navigation): add behavior tests and consumer typecheck for scrollToElement (SD-2519)

- Behavior tests: navigate to paragraph (by nodeId), comment (by entityId),
  tracked change (by entityId), non-existent ID returns false, sequential
  multi-block navigation
- Consumer typecheck: verify scrollToElement and navigateTo compile with
  correct type signatures (block, comment, tracked change addresses)

* docs(navigation): document scrollToElement API and cross-session navigation (SD-2519)

- Add scrollToElement to SuperDoc methods reference with usage examples
  and full example covering paragraphs, comments, and tracked changes
- Update cross-session block addressing workflow to show browser-side
  navigation with scrollToElement after headless extraction
- Rewrite stable navigation guide to cover both approaches: scrollToElement
  for ID-based navigation (cross-session) and PositionTracker for tracking
  nodes during edits (single-session)

* fix(navigation): scroll viewport after placing cursor for comments and tracked changes (SD-2519)

setCursorById places the ProseMirror cursor but doesn't scroll the
DomPainter viewport in presentation mode. Add scrollToPositionAsync
after each successful setCursorById call so off-screen elements are
actually scrolled into view.

Author: caio-pizzol

apps/docs/core/superdoc/methods.mdx

@@ -765,6 +765,69 @@ const superdoc = new SuperDoc({
 
 </CodeGroup>
 
+### `scrollToElement`
+
+Scroll to any document element by its ID. Pass a paragraph `nodeId`, comment `entityId`, or tracked change `entityId` — the method figures out what kind of element it is and scrolls there.
+
+<ParamField path="elementId" type="string" required>
+  The element's stable ID. Get this from `query.match` results (`address.nodeId`), `comments.list` (`entityId`), or `trackChanges.list` (`entityId`).
+</ParamField>
+
+**Returns:** `Promise<boolean>` — `true` if the element was found and scrolled to, `false` otherwise. Never throws.
+
+<CodeGroup>
+
+```javascript Usage
+// Get a paragraph's nodeId from the Document API
+const result = editor.doc.query.match({
+  select: { type: 'text', pattern: 'Introduction', mode: 'contains' },
+  require: 'first',
+});
+const nodeId = result.items[0].address.nodeId;
+
+// Scroll to it — one call, any element type
+await superdoc.scrollToElement(nodeId);
+```
+
+```javascript Full Example
+import { SuperDoc } from 'superdoc';
+import 'superdoc/style.css';
+
+const superdoc = new SuperDoc({
+  selector: '#editor',
+  document: yourFile,
+  modules: { comments: {} },
+  onReady: async (superdoc) => {
+    const editor = superdoc.editor;
+
+    // Navigate to a paragraph
+    const match = editor.doc.query.match({
+      select: { type: 'text', pattern: 'Summary', mode: 'contains' },
+      require: 'first',
+    });
+    await superdoc.scrollToElement(match.items[0].address.nodeId);
+
+    // Navigate to a comment
+    const comments = editor.doc.comments.list();
+    if (comments.items.length > 0) {
+      await superdoc.scrollToElement(comments.items[0].entityId);
+    }
+
+    // Navigate to a tracked change
+    const changes = editor.doc.trackChanges.list();
+    if (changes.items.length > 0) {
+      await superdoc.scrollToElement(changes.items[0].entityId);
+    }
+  },
+});
+```
+
+</CodeGroup>
+
+<Info>
+For DOCX-imported documents, paragraph `nodeId` values come from the OOXML `paraId` attribute and are stable across sessions. See [cross-session block addressing](/document-api/common-workflows#cross-session-block-addressing) for the full pattern.
+</Info>
+
 ## User management
 
 ### `addSharedUser`

apps/docs/document-api/common-workflows.mdx

@@ -279,6 +279,27 @@ for (const { address } of saved) {
 editor2.destroy();
 ```
 
+### Navigate to saved addresses in the browser
+
+When the saved addresses are used in a browser-based viewer (RAG citations, search results, cross-references), pass the `nodeId` directly to `scrollToElement`:
+
+```ts
+// In the browser — user clicks a citation
+const savedNodeId = citation.nodeId; // from your database / vector store
+const found = await superdoc.scrollToElement(savedNodeId);
+
+if (!found) {
+  console.warn('Element no longer exists in the document');
+}
+```
+
+`scrollToElement` also works with comment and tracked change IDs:
+
+```ts
+await superdoc.scrollToElement(commentEntityId);
+await superdoc.scrollToElement(trackedChangeEntityId);
+```
+
 <Info>
 `nodeId` stability depends on the ID source. For DOCX-imported content, `nodeId` comes from `paraId` when available and is best-effort stable across loads. Runtime-created content is still not guaranteed stable across loads; many nodes use session-scoped editor identity, while some structures such as tables or table cells may expose deterministic fallback IDs instead of raw `sdBlockId`.
 </Info>

apps/docs/guides/general/stable-navigation.mdx

@@ -1,13 +1,45 @@
 ---
 title: Stable navigation after edits
 sidebarTitle: Stable navigation
-description: Find nodes once and navigate to them reliably after document edits.
+description: Navigate to document elements reliably — during edits and across sessions.
 ---
 
-When users edit a document, stored positions can drift.
-Use `PositionTracker` so navigation targets stay stable.
+SuperDoc has two navigation approaches depending on your use case:
 
-## Hyperlinks example
+| Approach | Use case | Stability |
+|----------|----------|-----------|
+| `scrollToElement(id)` | Navigate to any element by its ID | Cross-session (for DOCX-imported content) |
+| `PositionTracker` | Track nodes that move during edits | Within a single session |
+
+## Navigate by element ID
+
+`scrollToElement` takes any element ID — paragraph, comment, or tracked change — and scrolls to it. The ID comes from the Document API.
+
+```javascript
+// Get an element's ID
+const match = editor.doc.query.match({
+  select: { type: 'text', pattern: 'Introduction', mode: 'contains' },
+  require: 'first',
+});
+const nodeId = match.items[0].address.nodeId;
+
+// Navigate to it — works for paragraphs, comments, tracked changes
+await superdoc.scrollToElement(nodeId);
+```
+
+This is the approach to use for:
+- **RAG citations** — store `nodeId` alongside embeddings, navigate on click
+- **Cross-references** — link to specific paragraphs from external UI
+- **Search results** — scroll to the matching paragraph
+- **Cross-session addressing** — IDs from DOCX-imported content survive reloads
+
+For the full cross-session pattern, see [cross-session block addressing](/document-api/common-workflows#cross-session-block-addressing).
+
+## Track nodes during edits
+
+When users edit a document, stored positions can drift. Use `PositionTracker` so navigation targets stay stable within the current session.
+
+### Hyperlinks example
 
 ```javascript
 // 1) Find hyperlink nodes
@@ -30,7 +62,7 @@ function goToLink(link) {
 
 ## Best practices
 
-- Track results right after `find()`.
-- Store `trackerId` in UI state, not raw positions.
-- Re-run `find()` and rebuild tracked IDs when refreshing your list.
-- Handle missing targets gracefully (`goToTracked` can return `false` if content was removed).
+- Use `scrollToElement` when you have an element ID from the Document API.
+- Use `PositionTracker` when you need to follow nodes that move during edits.
+- For cross-session use, store `nodeId` values (not `sdBlockId` — those regenerate on each open).
+- Handle missing targets gracefully — both APIs return `false` if the element no longer exists.

packages/document-api/src/types/address.ts

@@ -128,3 +128,32 @@ export type TrackedChangeAddress = {
 };
 
 export type EntityAddress = CommentAddress | TrackedChangeAddress;
+
+// ---------------------------------------------------------------------------
+// Navigation addressing
+// ---------------------------------------------------------------------------
+
+/**
+ * Address for navigating to a block-level element by its node ID.
+ *
+ * The `nodeId` maps to `paraId` (from OOXML) when available, with fallback
+ * to `sdBlockId` (session-scoped). Use the value returned by Document API
+ * queries (e.g. `query.match`, `find`, `getNode`) as the `nodeId`.
+ *
+ * When `nodeType` is omitted, the lookup searches across all block types.
+ */
+export type BlockNavigationAddress = {
+  kind: 'block';
+  nodeId: string;
+  nodeType?: SelectionEdgeNodeType;
+};
+
+/**
+ * Union of all address types accepted by `navigateTo()`.
+ *
+ * Supports navigation to:
+ * - Blocks by `nodeId` (paragraphs, headings, tables, images, SDTs)
+ * - Comments by `entityId`
+ * - Tracked changes by `entityId`
+ */
+export type NavigableAddress = BlockNavigationAddress | CommentAddress | TrackedChangeAddress;

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

@@ -130,7 +130,10 @@ import {
   ensureEditorFieldAnnotationInteractionStyles,
 } from './dom/EditorStyleInjector.js';
 
-import type { ResolveRangeOutput, DocumentApi } from '@superdoc/document-api';
+import type { ResolveRangeOutput, DocumentApi, NavigableAddress, BlockNavigationAddress } from '@superdoc/document-api';
+import { getBlockIndex } from '../../document-api-adapters/helpers/index-cache.js';
+import { findBlockByNodeIdOnly, findBlockById } from '../../document-api-adapters/helpers/node-address-resolver.js';
+import { resolveTrackedChange } from '../../document-api-adapters/helpers/tracked-change-resolver.js';
 import type { SelectionHandle } from '../selection-state.js';
 
 const DOCUMENT_RELS_PART_ID = 'word/_rels/document.xml.rels';
@@ -5843,6 +5846,171 @@ export class PresentationEditor extends EventEmitter {
    */
   private static readonly ANCHOR_NAV_TIMEOUT_MS = 2000;
 
+  /**
+   * Scroll to any document element by its ID.
+   *
+   * Accepts any element ID — paragraph nodeId, comment entityId, or tracked
+   * change entityId. Resolves the element type automatically:
+   * 1. Tries block index lookup (paragraphs, headings, tables)
+   * 2. Tries comment navigation (activates comment thread)
+   * 3. Tries tracked change navigation (with raw ID fallback)
+   *
+   * @param elementId - The element's stable ID (nodeId, commentId, or trackedChangeId).
+   * @returns Promise resolving to true if the element was found and scrolled to.
+   */
+  async scrollToElement(elementId: string): Promise<boolean> {
+    if (!elementId) return false;
+
+    // Try block first — O(1) index lookup, most common for RAG citations.
+    if (await this.navigateTo({ kind: 'block', nodeId: elementId })) return true;
+
+    // Try comment — setCursorById handles both comment and TC marks,
+    // but we try comment first to get full thread activation.
+    if (await this.navigateTo({ kind: 'entity', entityType: 'comment', entityId: elementId })) return true;
+
+    // Try tracked change — has its own fallback chain (canonical → raw ID → scroll).
+    if (await this.navigateTo({ kind: 'entity', entityType: 'trackedChange', entityId: elementId })) return true;
+
+    return false;
+  }
+
+  /**
+   * Navigate to a typed document element address.
+   *
+   * @param target - Typed address: block (nodeId), comment (entityId), or tracked change (entityId).
+   * @returns Promise resolving to true if navigation succeeded.
+   */
+  async navigateTo(target: NavigableAddress): Promise<boolean> {
+    if (!target) return false;
+
+    try {
+      if (target.kind === 'block') {
+        return await this.#navigateToBlock(target);
+      }
+
+      if (target.kind === 'entity') {
+        if (target.entityType === 'comment') {
+          return await this.#navigateToComment(target.entityId);
+        }
+        if (target.entityType === 'trackedChange') {
+          return await this.#navigateToTrackedChange(target.entityId);
+        }
+      }
+
+      return false;
+    } catch (error) {
+      console.error('[PresentationEditor] navigateTo failed:', error);
+      this.emit('error', { error, context: 'navigateTo' });
+      return false;
+    }
+  }
+
+  async #navigateToBlock(target: BlockNavigationAddress): Promise<boolean> {
+    const editor = this.#editor;
+    if (!editor) return false;
+
+    const index = getBlockIndex(editor);
+
+    let candidate;
+    try {
+      if (target.nodeType) {
+        candidate = findBlockById(index, { kind: 'block', nodeType: target.nodeType, nodeId: target.nodeId });
+      } else {
+        candidate = findBlockByNodeIdOnly(index, target.nodeId);
+      }
+    } catch {
+      return false;
+    }
+
+    if (!candidate) return false;
+    return this.#scrollToBlockCandidate(editor, candidate);
+  }
+
+  /**
+   * Scroll to a resolved block candidate and place the cursor inside it.
+   *
+   * Resolves the first text-content position inside the block — the layout
+   * engine maps fragments to text content ranges, so block wrappers and
+   * zero-width annotation nodes (bookmarkStart, commentRangeStart) don't
+   * generate layout fragments. We walk the block's children to find the
+   * first inline node with text content (typically a `run` node).
+   */
+  async #scrollToBlockCandidate(editor: Editor, candidate: { pos: number }): Promise<boolean> {
+    const blockNode = editor.state.doc.nodeAt(candidate.pos);
+    let contentPos = candidate.pos + 1;
+    if (blockNode) {
+      blockNode.forEach((child, offset) => {
+        if (contentPos !== candidate.pos + 1) return;
+        if (child.textContent.length > 0) {
+          contentPos = candidate.pos + 1 + offset + (child.isText ? 0 : 1);
+        }
+      });
+    }
+
+    const scrolled = await this.scrollToPositionAsync(contentPos, {
+      behavior: 'auto',
+      block: 'center',
+    });
+    if (!scrolled) return false;
+
+    editor.commands?.setTextSelection?.({ from: contentPos, to: contentPos });
+    editor.view?.focus?.();
+    return true;
+  }
+
+  async #navigateToComment(entityId: string): Promise<boolean> {
+    const editor = this.#editor;
+    if (!editor) return false;
+
+    const setCursorById = editor.commands?.setCursorById;
+    if (typeof setCursorById !== 'function') return false;
+
+    if (!setCursorById(entityId, { preferredActiveThreadId: entityId, activeCommentId: entityId })) {
+      return false;
+    }
+
+    // Scroll the viewport — setCursorById places the cursor but doesn't
+    // scroll in presentation mode where DomPainter renders the output.
+    await this.scrollToPositionAsync(editor.state.selection.from, { behavior: 'auto', block: 'center' });
+    return true;
+  }
+
+  async #navigateToTrackedChange(entityId: string): Promise<boolean> {
+    const editor = this.#editor;
+    if (!editor) return false;
+
+    const setCursorById = editor.commands?.setCursorById;
+
+    // Try direct cursor placement, then scroll to the new selection.
+    if (typeof setCursorById === 'function' && setCursorById(entityId, { preferredActiveThreadId: entityId })) {
+      await this.scrollToPositionAsync(editor.state.selection.from, { behavior: 'auto', block: 'center' });
+      return true;
+    }
+
+    // Fall back to resolving the tracked change position and scrolling.
+    const resolved = resolveTrackedChange(editor, entityId);
+    if (!resolved) return false;
+
+    // Try with the raw ID (tracked changes may use a different internal ID).
+    if (typeof setCursorById === 'function' && resolved.rawId !== entityId) {
+      if (setCursorById(resolved.rawId, { preferredActiveThreadId: resolved.rawId })) {
+        await this.scrollToPositionAsync(editor.state.selection.from, { behavior: 'auto', block: 'center' });
+        return true;
+      }
+    }
+
+    // Last resort: scroll to position directly.
+    const scrolled = await this.scrollToPositionAsync(resolved.from, {
+      behavior: 'auto',
+      block: 'center',
+    });
+    if (!scrolled) return false;
+
+    editor.commands?.setTextSelection?.({ from: resolved.from, to: resolved.from });
+    editor.view?.focus?.();
+    return true;
+  }
+
   /**
    * Navigate to a bookmark/anchor in the current document (e.g., TOC links).
    *