feat(super-editor): timeoutMs option on scrollToPositionAsync

`scrollToPositionAsync` had a hard-coded 2 second timeout for
waiting on the painter to mount the target virtualised page.
Callers navigating long documents — where the painter may need
longer than 2 s to settle when jumping far from the current
viewport — had no way to extend it short of editing the static
`ANCHOR_NAV_TIMEOUT_MS` constant.

Adds an opt-in `timeoutMs` to the options bag. Backwards-
compatible: defaults stay at 2000 ms when unset. The warn message
now also includes the actual timeout that elapsed, which is
useful when diagnosing whether a particular long-doc click was
fighting the timeout or some other issue.

`SuperDoc.scrollToHeading` passes the option through to
`scrollToPositionAsync` when given, so external apps can extend
the wait at the call site without reaching into the presentation
editor directly:

  await superdoc.scrollToHeading(2, 18, { timeoutMs: 8000 });

`scrollToElement` / `navigateTo` deliberately don't yet thread
the option — those traverse `#navigateToBlock` / `#navigateToComment` /
`#navigateToTrackedChange` before reaching `scrollToPositionAsync`,
which is a wider surface to touch. Can be added in a follow-up
once the call sites that need it surface.

Existing scrollToPosition test updated to match the new warn
message; a new test exercises the option (short timeout fires
faster than the default and the warn text includes the supplied
value). 86/86 SuperDoc.test.js + 14/14 scrollToPosition.test.ts
pass.

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

Author: bjohas

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

@@ -3712,7 +3712,20 @@ export class PresentationEditor extends EventEmitter {
    */
   async scrollToPositionAsync(
     pos: number,
-    options: { block?: 'start' | 'center' | 'end' | 'nearest'; behavior?: ScrollBehavior } = {},
+    options: {
+      block?: 'start' | 'center' | 'end' | 'nearest';
+      behavior?: ScrollBehavior;
+      /**
+       * Maximum time (ms) to wait for the painter to mount the target
+       * virtualised page before giving up. Defaults to
+       * `ANCHOR_NAV_TIMEOUT_MS` (2000 ms). Callers navigating across
+       * long documents — where the painter may need longer than 2 s to
+       * settle when jumping far from the current viewport — can extend
+       * this. The function still returns `false` on timeout, but the
+       * extension reduces false-negative anchor navigations.
+       */
+      timeoutMs?: number;
+    } = {},
   ): Promise<boolean> {
     // Fast path: try sync scroll first (works if page already mounted)
     if (this.scrollToPosition(pos, options)) {
@@ -3747,11 +3760,15 @@ export class PresentationEditor extends EventEmitter {
     this.#scrollPageIntoView(pageIndex);
 
     // Wait for page to mount in the DOM
-    const mounted = await this.#waitForPageMount(pageIndex, {
-      timeout: PresentationEditor.ANCHOR_NAV_TIMEOUT_MS,
-    });
+    const timeout =
+      Number.isFinite(options.timeoutMs) && options.timeoutMs! > 0
+        ? options.timeoutMs!
+        : PresentationEditor.ANCHOR_NAV_TIMEOUT_MS;
+    const mounted = await this.#waitForPageMount(pageIndex, { timeout });
     if (!mounted) {
-      console.warn(`[PresentationEditor] scrollToPositionAsync: Page ${pageIndex} failed to mount within timeout`);
+      console.warn(
+        `[PresentationEditor] scrollToPositionAsync: Page ${pageIndex} failed to mount within ${timeout} ms`,
+      );
       return false;
     }
 

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

@@ -667,7 +667,34 @@ describe('PresentationEditor - scrollToPosition', () => {
 
       // The page never mounted, so it should fail
       expect(result).toBe(false);
-      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('failed to mount within timeout'));
+      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('failed to mount within'));
+
+      consoleWarnSpy.mockRestore();
+    });
+
+    it('honours a caller-supplied timeoutMs and surfaces the value in the warn message', async () => {
+      const consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      editor = new PresentationEditor({
+        element: container,
+        documentId: 'test-doc',
+      });
+
+      await vi.waitFor(() => expect(mockIncrementalLayout).toHaveBeenCalled());
+      await new Promise((resolve) => setTimeout(resolve, 50));
+
+      // 100 ms ceiling — the page never mounts, so it should bail
+      // much faster than the 2 s default.
+      const t0 = Date.now();
+      const result = await editor.scrollToPositionAsync(150, { timeoutMs: 100 });
+      const elapsed = Date.now() - t0;
+
+      expect(result).toBe(false);
+      // The warning should mention the supplied timeout (100 ms), not
+      // the static default.
+      expect(consoleWarnSpy).toHaveBeenCalledWith(expect.stringContaining('100 ms'));
+      // And we should have bailed well under the 2 s default.
+      expect(elapsed).toBeLessThan(1500);
 
       consoleWarnSpy.mockRestore();
     });

packages/superdoc/src/core/SuperDoc.js

@@ -1477,7 +1477,11 @@ export class SuperDoc extends EventEmitter {
    *
    * @param {number} level    1..6
    * @param {number} [ordinal=1]  1-based index among headings of that level
-   * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition }} [options]
+   * @param {{ behavior?: ScrollBehavior, block?: ScrollLogicalPosition, timeoutMs?: number }} [options]
+   *        Pass `timeoutMs` to override the default 2 s page-mount wait
+   *        in paginated layout. Useful when jumping far from the current
+   *        viewport on long docs where the painter takes longer to
+   *        mount the target page.
    * @returns {Promise<boolean>} Whether a matching heading was found and scrolled to
    *
    * @example
@@ -1563,6 +1567,9 @@ export class SuperDoc extends EventEmitter {
       const ok = await presentationEditor.scrollToPositionAsync(foundPos, {
         behavior: options.behavior ?? 'auto',
         block: options.block ?? 'center',
+        // Pass-through so callers can extend the page-mount wait on
+        // long docs without reaching into PresentationEditor directly.
+        ...(Number.isFinite(options.timeoutMs) ? { timeoutMs: options.timeoutMs } : {}),
       });
       if (ok) return true;
       // Fall through to body-editor path on layout-state miss.

packages/superdoc/src/core/SuperDoc.test.js

@@ -518,6 +518,73 @@ describe('SuperDoc core', () => {
     expect(scrollToPositionAsync).toHaveBeenCalledWith(51, expect.any(Object));
   });
 
+  it('scrollToHeading forwards an explicit timeoutMs to scrollToPositionAsync', async () => {
+    const { superdocStore } = createAppHarness();
+    const headings = [{ pos: 10, text: 'only', styleId: 'Heading1' }];
+    const makeNode = (h) => ({
+      type: { name: 'paragraph' },
+      attrs: { paragraphProperties: { styleId: h.styleId } },
+      content: { size: 5 },
+      descendants: (cb) => cb({ isText: true, text: h.text }, 0),
+    });
+    const descendants = (cb) => {
+      for (const h of headings) {
+        if (cb(makeNode(h), h.pos) === false) return;
+      }
+    };
+    const scrollToPositionAsync = vi.fn(async () => true);
+    superdocStore.documents = [{ getPresentationEditor: vi.fn(() => ({ scrollToPositionAsync })) }];
+    const instance = new SuperDoc({
+      selector: '#host',
+      document: 'https://example.com/doc.docx',
+      documents: [],
+      modules: { comments: {}, toolbar: {} },
+      onException: vi.fn(),
+    });
+    await flushMicrotasks();
+    Object.defineProperty(instance, 'activeEditor', {
+      configurable: true,
+      get: () => ({ state: { doc: { descendants, content: { size: 1000 } } } }),
+    });
+
+    await expect(instance.scrollToHeading(1, 1, { timeoutMs: 10000 })).resolves.toBe(true);
+    expect(scrollToPositionAsync).toHaveBeenCalledWith(11, expect.objectContaining({ timeoutMs: 10000 }));
+  });
+
+  it('scrollToHeading omits timeoutMs when not given so the default applies', async () => {
+    const { superdocStore } = createAppHarness();
+    const headings = [{ pos: 10, text: 'only', styleId: 'Heading1' }];
+    const makeNode = (h) => ({
+      type: { name: 'paragraph' },
+      attrs: { paragraphProperties: { styleId: h.styleId } },
+      content: { size: 5 },
+      descendants: (cb) => cb({ isText: true, text: h.text }, 0),
+    });
+    const descendants = (cb) => {
+      for (const h of headings) {
+        if (cb(makeNode(h), h.pos) === false) return;
+      }
+    };
+    const scrollToPositionAsync = vi.fn(async () => true);
+    superdocStore.documents = [{ getPresentationEditor: vi.fn(() => ({ scrollToPositionAsync })) }];
+    const instance = new SuperDoc({
+      selector: '#host',
+      document: 'https://example.com/doc.docx',
+      documents: [],
+      modules: { comments: {}, toolbar: {} },
+      onException: vi.fn(),
+    });
+    await flushMicrotasks();
+    Object.defineProperty(instance, 'activeEditor', {
+      configurable: true,
+      get: () => ({ state: { doc: { descendants, content: { size: 1000 } } } }),
+    });
+
+    await expect(instance.scrollToHeading(1, 1)).resolves.toBe(true);
+    const opts = scrollToPositionAsync.mock.calls[0][1];
+    expect(opts.timeoutMs).toBeUndefined();
+  });
+
   it('scrollToHeading rejects out-of-range levels and non-positive ordinals', async () => {
     createAppHarness();
     const instance = new SuperDoc({