fix(scroll): wait for virtualized page mount and center text element (#2221)

* fix(scroll): wait for virtualized page mount and center text element

* fix(super-editor): restore reliable search result scrolling and ignore header/footer scroll targets

* fix(super-editor): improve position tracker, restore reliable search result scrolling

* docs: add stable navigation docs

* chore: fix test

---------

Co-authored-by: Nick Bernal <nick@superdoc.dev>

Author: mattConnHarbour

apps/docs/docs.json

@@ -227,6 +227,7 @@
             "group": "Guides",
             "pages": [
               "guides/general/storage",
+              "guides/general/stable-navigation",
               {
                 "group": "Collaboration",
                 "pages": [

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

@@ -0,0 +1,36 @@
+---
+title: Stable navigation after edits
+sidebarTitle: Stable navigation
+description: Find nodes once and navigate to them reliably after document edits.
+---
+
+When users edit a document, stored positions can drift.
+Use `PositionTracker` so navigation targets stay stable.
+
+## Hyperlinks example
+
+```javascript
+// 1) Find hyperlink nodes
+const found = editor.doc.find({
+  select: { type: 'node', nodeType: 'hyperlink', kind: 'inline' },
+});
+
+// 2) Track each found node
+const links = found.items.map((item) => ({
+  item,
+  trackerId: editor.positionTracker.trackNode(item),
+}));
+
+// 3) Navigate later (for example, from a sidebar click)
+function goToLink(link) {
+  if (!link?.trackerId) return;
+  editor.positionTracker.goToTracked(link.trackerId);
+}
+```
+
+## 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).

packages/super-editor/src/core/PositionTracker.ts

@@ -1,5 +1,6 @@
 import type { Transaction } from 'prosemirror-state';
-import { Plugin, PluginKey } from 'prosemirror-state';
+import { Plugin, PluginKey, TextSelection } from 'prosemirror-state';
+import type { Node as ProseMirrorNode } from 'prosemirror-model';
 import { Decoration, DecorationSet } from 'prosemirror-view';
 import { v4 as uuidv4 } from 'uuid';
 
@@ -21,6 +22,46 @@ export type ResolvedRange = {
   spec: TrackedRangeSpec;
 };
 
+type TrackablePosition = {
+  blockId: string;
+  offset: number;
+};
+
+type TrackableInlineAnchor = {
+  start: TrackablePosition;
+  end: TrackablePosition;
+};
+
+type TrackableNodeAddress =
+  | {
+      kind: 'inline';
+      anchor: TrackableInlineAnchor;
+    }
+  | {
+      kind: 'block';
+      nodeId: string;
+      nodeType?: string;
+    };
+
+type TrackableFindNodeItem = {
+  address?: TrackableNodeAddress;
+};
+
+type TrackNodeInput = TrackableNodeAddress | TrackableFindNodeItem;
+
+type ResolvedBlockCandidate = {
+  node: ProseMirrorNode;
+  pos: number;
+};
+
+type OffsetRange = {
+  start: number;
+  end: number;
+};
+
+const DEFAULT_TRACKED_NODE_TYPE = 'tracked-node';
+type ScrollBlock = 'start' | 'center' | 'end' | 'nearest';
+
 export type PositionTrackerState = {
   decorations: DecorationSet;
   generation: number;
@@ -33,6 +74,140 @@ type PositionTrackerMeta =
 
 export const positionTrackerKey = new PluginKey<PositionTrackerState>('positionTracker');
 
+function getNodeIdCandidates(node: ProseMirrorNode): string[] {
+  const attrs = (node.attrs ?? {}) as Record<string, unknown>;
+  const candidateFields = ['paraId', 'sdBlockId', 'blockId', 'id', 'uuid'] as const;
+  const ids: string[] = [];
+
+  for (const field of candidateFields) {
+    const value = attrs[field];
+    if (typeof value === 'string' && value.length > 0) {
+      ids.push(value);
+    }
+  }
+
+  return ids;
+}
+
+function findBlockCandidateById(doc: ProseMirrorNode, blockId: string): ResolvedBlockCandidate | null {
+  let match: ResolvedBlockCandidate | null = null;
+  let isAmbiguous = false;
+
+  doc.descendants((node, pos) => {
+    if (!node.isBlock) return;
+    const ids = getNodeIdCandidates(node);
+    if (!ids.includes(blockId)) return;
+
+    if (match) {
+      isAmbiguous = true;
+      return false;
+    }
+
+    match = { node, pos };
+    return;
+  });
+
+  if (isAmbiguous) return null;
+  return match;
+}
+
+function resolveSegmentPosition(
+  targetOffset: number,
+  segmentStart: number,
+  segmentLength: number,
+  docFrom: number,
+  docTo: number,
+): number {
+  if (segmentLength <= 1) {
+    return targetOffset <= segmentStart ? docFrom : docTo;
+  }
+  return docFrom + (targetOffset - segmentStart);
+}
+
+function resolveOffsetsInBlock(
+  blockNode: ProseMirrorNode,
+  blockPos: number,
+  range: OffsetRange,
+): { from: number; to: number } | null {
+  if (range.start < 0 || range.end < range.start) return null;
+
+  let flattenedOffset = 0;
+  let fromPos: number | undefined;
+  let toPos: number | undefined;
+
+  const advanceSegment = (segmentLength: number, docFrom: number, docTo: number) => {
+    const segmentStart = flattenedOffset;
+    const segmentEnd = flattenedOffset + segmentLength;
+
+    if (fromPos == null && range.start <= segmentEnd) {
+      fromPos = resolveSegmentPosition(range.start, segmentStart, segmentLength, docFrom, docTo);
+    }
+    if (toPos == null && range.end <= segmentEnd) {
+      toPos = resolveSegmentPosition(range.end, segmentStart, segmentLength, docFrom, docTo);
+    }
+
+    flattenedOffset = segmentEnd;
+  };
+
+  const walkNodeContent = (node: ProseMirrorNode, contentStart: number) => {
+    let isFirstChild = true;
+    let childOffset = 0;
+
+    for (let i = 0; i < node.childCount; i += 1) {
+      const child = node.child(i);
+      const childPos = contentStart + childOffset;
+
+      if (child.isBlock && !isFirstChild) {
+        advanceSegment(1, childPos, childPos + 1);
+      }
+
+      walkNode(child, childPos);
+      childOffset += child.nodeSize;
+      isFirstChild = false;
+    }
+  };
+
+  const walkNode = (node: ProseMirrorNode, docPos: number) => {
+    if (node.isText) {
+      const text = node.text ?? '';
+      if (text.length > 0) {
+        advanceSegment(text.length, docPos, docPos + text.length);
+      }
+      return;
+    }
+
+    if (node.isLeaf) {
+      advanceSegment(1, docPos, docPos + node.nodeSize);
+      return;
+    }
+
+    walkNodeContent(node, docPos + 1);
+  };
+
+  walkNodeContent(blockNode, blockPos + 1);
+
+  if (flattenedOffset === 0 && range.start === 0 && range.end === 0) {
+    const anchor = blockPos + 1;
+    return { from: anchor, to: anchor };
+  }
+
+  if (range.end > flattenedOffset) return null;
+  if (fromPos == null || toPos == null) return null;
+  return { from: fromPos, to: toPos };
+}
+
+function getTrackableAddress(input: TrackNodeInput): TrackableNodeAddress | null {
+  if (!input || typeof input !== 'object') return null;
+  if ('kind' in input && (input.kind === 'inline' || input.kind === 'block')) {
+    return input as TrackableNodeAddress;
+  }
+  if ('address' in input && input.address && typeof input.address === 'object') {
+    const address = input.address as TrackableNodeAddress;
+    if (address.kind === 'inline' || address.kind === 'block') return address;
+  }
+  return null;
+}
+
 export function createPositionTrackerPlugin(): Plugin<PositionTrackerState> {
   return new Plugin<PositionTrackerState>({
     key: positionTrackerKey,
@@ -92,6 +267,30 @@ export class PositionTracker {
     return positionTrackerKey.getState(this.#editor.state) ?? null;
   }
 
+  #resolveTrackNodeAddress(address: TrackableNodeAddress): { from: number; to: number } | null {
+    const doc = this.#editor?.state?.doc;
+    if (!doc) return null;
+
+    if (address.kind === 'inline') {
+      const { start, end } = address.anchor;
+      if (!start || !end || start.blockId !== end.blockId) return null;
+
+      const block = findBlockCandidateById(doc, start.blockId);
+      if (!block) return null;
+
+      return resolveOffsetsInBlock(block.node, block.pos, {
+        start: start.offset,
+        end: end.offset,
+      });
+    }
+
+    const block = findBlockCandidateById(doc, address.nodeId);
+    if (!block) return null;
+
+    const anchor = block.pos + 1;
+    return { from: anchor, to: anchor };
+  }
+
   track(from: number, to: number, spec: Omit<TrackedRangeSpec, 'id'>): string {
     const id = uuidv4();
     if (!this.#editor?.state) return id;
@@ -135,6 +334,45 @@ export class PositionTracker {
     return ids;
   }
 
+  trackNode(input: TrackNodeInput, spec?: Omit<TrackedRangeSpec, 'id' | 'kind'>): string | null {
+    const [trackedId] = this.trackNodes([input], spec);
+    return trackedId ?? null;
+  }
+
+  trackNodes(inputs: TrackNodeInput[], spec?: Omit<TrackedRangeSpec, 'id' | 'kind'>): Array<string | null> {
+    if (!Array.isArray(inputs) || inputs.length === 0) return [];
+
+    const trackSpec = { type: DEFAULT_TRACKED_NODE_TYPE, ...(spec ?? {}) };
+    const pendingRanges: Array<{ from: number; to: number; spec: Omit<TrackedRangeSpec, 'id'> }> = [];
+    const pendingInputIndexes: number[] = [];
+    const results: Array<string | null> = Array.from({ length: inputs.length }, () => null);
+
+    for (let index = 0; index < inputs.length; index += 1) {
+      const address = getTrackableAddress(inputs[index]);
+      if (!address) continue;
+
+      const resolved = this.#resolveTrackNodeAddress(address);
+      if (!resolved) continue;
+
+      pendingRanges.push({
+        from: resolved.from,
+        to: resolved.to,
+        spec: trackSpec,
+      });
+      pendingInputIndexes.push(index);
+    }
+
+    if (pendingRanges.length === 0) return results;
+
+    const trackedIds = this.trackMany(pendingRanges);
+    for (let i = 0; i < pendingInputIndexes.length; i += 1) {
+      const inputIndex = pendingInputIndexes[i];
+      results[inputIndex] = trackedIds[i] ?? null;
+    }
+
+    return results;
+  }
+
   untrack(id: string): void {
     if (!this.#editor?.state) return;
     const tr = this.#editor.state.tr
@@ -226,6 +464,44 @@ export class PositionTracker {
       });
   }
 
+  goToTracked(id: string, options?: { block?: ScrollBlock }): boolean {
+    const resolved = this.resolve(id);
+    if (!resolved) return false;
+
+    const from = Math.max(0, Math.min(resolved.from, this.#editor.state.doc.content.size));
+    const to = Math.max(from, Math.min(resolved.to, this.#editor.state.doc.content.size));
+    const block = options?.block ?? 'center';
+
+    if (this.#editor.commands?.setTextSelection) {
+      this.#editor.commands.setTextSelection({ from, to });
+    } else if (this.#editor.state) {
+      const tr = this.#editor.state.tr
+        .setSelection(TextSelection.create(this.#editor.state.doc, from, to))
+        .scrollIntoView();
+      this.#editor.dispatch(tr);
+    }
+
+    const presentationEditor = this.#editor.presentationEditor;
+    const didPresentationScroll = presentationEditor?.scrollToPosition?.(from, { block }) ?? false;
+
+    if (!didPresentationScroll) {
+      Promise.resolve(presentationEditor?.scrollToPositionAsync?.(from, { block })).catch(() => {});
+
+      try {
+        const { node } = this.#editor.view?.domAtPos(from) ?? { node: null };
+        if (typeof Element !== 'undefined' && node instanceof Element) {
+          node.scrollIntoView({ block, inline: 'nearest' });
+        } else if ((node as Node | null)?.parentElement) {
+          (node as Node).parentElement?.scrollIntoView({ block, inline: 'nearest' });
+        }
+      } catch {
+        // Ignore scroll failures in environments with incomplete DOM APIs.
+      }
+    }
+
+    return true;
+  }
+
   get generation(): number {
     return this.#getState()?.generation ?? 0;
   }