fix(navigation): reject unsupported note bookmark targets

Author: luccas-harbour

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

@@ -12,7 +12,13 @@ export interface BookmarkAddress {
   kind: 'entity';
   entityType: 'bookmark';
   name: string;
-  /** Story containing this bookmark. Omit for body (backward compatible). */
+  /**
+   * Story containing this bookmark. Omit for body (backward compatible).
+   *
+   * **Limitation:** `navigateTo()` currently supports bookmark navigation only
+   * in the body and header/footer stories. Footnote/endnote bookmark
+   * navigation currently returns `false`.
+   */
   story?: StoryLocator;
 }
 

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

@@ -6001,6 +6001,17 @@ export class PresentationEditor extends EventEmitter {
       return this.goToAnchor(target.name);
     }
 
+    // Note stories are rendered into layout, but they do not currently expose
+    // a visible interactive editor surface that can receive selection/focus.
+    // Returning false is more accurate than reporting success after moving the
+    // selection in a detached headless note runtime.
+    if (story.storyType === 'footnote' || story.storyType === 'endnote') {
+      console.warn(
+        `[PresentationEditor] navigateTo does not yet support bookmark navigation in ${story.storyType} stories.`,
+      );
+      return false;
+    }
+
     if (!this.#editor) return false;
 
     try {

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

@@ -732,4 +732,26 @@ describe('PresentationEditor - goToAnchor', () => {
     expect(bodyEditor.view?.focus).toHaveBeenCalled();
     expect(mockResolveTrackedChange).toHaveBeenCalledWith(bodyEditor, 'canonical-tc-id');
   });
+
+  it('returns false for bookmark navigation in note stories', async () => {
+    editor = new PresentationEditor({
+      element: container,
+      documentId: 'test-doc',
+    });
+
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const result = await editor.navigateTo({
+      kind: 'entity',
+      entityType: 'bookmark',
+      name: 'bookmark-in-footnote',
+      story: { kind: 'story', storyType: 'footnote', noteId: 'fn-1' },
+    });
+
+    expect(result).toBe(false);
+    expect(mockResolveBookmarkTarget).not.toHaveBeenCalled();
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[PresentationEditor] navigateTo does not yet support bookmark navigation in footnote stories.',
+    );
+  });
 });

packages/superdoc/src/core/SuperDoc.js

@@ -1464,6 +1464,9 @@ export class SuperDoc extends EventEmitter {
    * Prefers the active document's PresentationEditor because navigation depends
    * on rendered layout rather than raw editor commands.
    *
+   * Note: bookmark navigation currently supports the body and header/footer
+   * stories. Footnote/endnote bookmark navigation returns `false`.
+   *
    * @param {NavigableEntityAddress} address Navigation target descriptor
    * @returns {Promise<boolean>}
    */