feat: story-aware bookmark addressing (SD-2358) (#2971)

* feat(document-api): add story-aware bookmark contract

* feat(super-editor): add cross-story bookmark discovery helpers

* feat(super-editor): add story-aware bookmark wrappers

* feat(super-editor): support bookmark targets in navigateTo

* feat: export navigation address types from public APIs

* feat: expose SuperDoc navigateTo wrapper for presentation navigation

* test(behavior): cover bookmark navigation and header roundtrip flows

* fix(super-editor): use live note session editors for bookmark discovery

* fix(super-editor): normalize default header slot bookmark navigation

* fix(super-editor): use story revisions for story-scoped bookmark flows

* fix(super-editor): scope bookmark rename duplicate check by story key

The bookmarkExistsAnywhere exclusion previously matched on bookmarkId
alone, so renaming a bookmark could silently collide with a same-named
bookmark in another story whose id happened to match. Scope the
exclusion to (storyKey, bookmarkId) so cross-story id collisions no
longer mask real duplicate names.

* fix(super-editor): skip unresolved stories during bookmark listing

Document-wide bookmarksList iterates story keys discovered from the
bookmark index; if a story (e.g. a header/footer part) can't be
resolved at list time, resolveStoryRuntime throws STORY_NOT_FOUND and
the whole list call fails. Catch that specific error per-story and
return no items for it so a stale or missing part doesn't break
listing the rest of the document.

* fix(super-editor): prefer live header/footer sessions in bookmark discovery

* docs(document-api): clarify story-aware navigateTo support

* docs(document-api): clarify bookmark story resolution semantics

* fix(super-editor): align bookmark header activation with session API

* fix(super-editor): resolve unqualified bookmark mutations document-wide

* docs(document-api): narrow unqualified bookmark lookup semantics

* fix(super-editor): use aggregate revisions for document-wide bookmark reads

* fix(document-api): allow story on text target schema

* fix(super-editor): reject ambiguous unqualified bookmark mutations

When a bookmark rename or remove target omits `story` but the name exists
in multiple stories, throw INVALID_INPUT asking the caller to disambiguate
instead of silently picking the first match.

* fix(super-editor): reject ambiguous unqualified bookmark mutations

When a bookmark rename or remove target omits `story` but the name exists
in multiple stories, throw INVALID_INPUT asking the caller to disambiguate
instead of silently picking the first match.

* refactor(super-editor): extract header/footer variant normalization

Move normalizeVariant out of the doc-api adapter helper into a dedicated
module under presentation-editor/header-footer/, where its sole non-adapter
caller (HeaderFooterSessionManager) lives. The slot-materialization helper
re-exports it for existing import sites.

* test(super-editor): assert navigateTo returns false for missing bookmarks

* fix(super-editor): exit header surface when navigating to body bookmark

Calling navigateTo for a body-story bookmark while a header/footer surface
is active left the header editor focused, so the selection update was
applied to the wrong editor. Exit the active story surface before delegating
to goToAnchor so navigation lands on the body editor.

* fix(super-editor): scope bookmark discovery IDs by story key

Document-wide bookmark listings collide when the same name exists in
multiple stories (e.g. body and a header part). buildBookmarkDiscoveryItem
now accepts an optional idScope and URL-encodes each segment so each
story's bookmarks get distinct, stable IDs. bookmarksListWrapper passes
the story key through when iterating snapshots.

* fix(document-api): harden bookmark mutation revisions and id allocation

Author: luccas-harbour

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

@@ -20,6 +20,7 @@ function makeAdapter(): BookmarksAdapter {
 }
 
 const validTarget = { kind: 'entity', entityType: 'bookmark', name: 'bm1' };
+const validStory = { kind: 'story', storyType: 'footnote', noteId: 'fn-1' } as const;
 
 describe('bookmarks validation', () => {
   // ── Target validation ───────────────────────────────────────────────
@@ -65,6 +66,15 @@ describe('bookmarks validation', () => {
         }),
       ).toThrow(DocumentApiValidationError);
     });
+
+    it('throws INVALID_INPUT when target.story is invalid', () => {
+      const adapter = makeAdapter();
+      expect(() =>
+        executeBookmarksGet(adapter, {
+          target: { kind: 'entity', entityType: 'bookmark', name: 'bm1', story: 'body' } as any,
+        }),
+      ).toThrow(DocumentApiValidationError);
+    });
   });
 
   // ── Input validation ────────────────────────────────────────────────
@@ -136,6 +146,18 @@ describe('bookmarks validation', () => {
       expect(adapter.list).toHaveBeenCalledWith(query);
     });
 
+    it('delegates to adapter.list with a valid story filter', () => {
+      const adapter = makeAdapter();
+      const query = { in: validStory };
+      executeBookmarksList(adapter, query);
+      expect(adapter.list).toHaveBeenCalledWith(query);
+    });
+
+    it('throws INVALID_INPUT when query.in is invalid', () => {
+      const adapter = makeAdapter();
+      expect(() => executeBookmarksList(adapter, { in: 'body' as any })).toThrow(DocumentApiValidationError);
+    });
+
     it('delegates to adapter.list without query', () => {
       const adapter = makeAdapter();
       executeBookmarksList(adapter);
@@ -150,6 +172,13 @@ describe('bookmarks validation', () => {
       executeBookmarksGet(adapter, input as any);
       expect(adapter.get).toHaveBeenCalledWith(input);
     });
+
+    it('delegates to adapter.get for a story-qualified target', () => {
+      const adapter = makeAdapter();
+      const input = { target: { ...validTarget, story: validStory } };
+      executeBookmarksGet(adapter, input);
+      expect(adapter.get).toHaveBeenCalledWith(input);
+    });
   });
 
   describe('executeBookmarksRemove', () => {

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

@@ -2,6 +2,7 @@ import type { MutationOptions } from '../write/write.js';
 import { normalizeMutationOptions } from '../write/write.js';
 import { DocumentApiValidationError } from '../errors.js';
 import { assertTargetPresent } from '../validation-primitives.js';
+import { validateStoryLocator } from '../validation/story-validator.js';
 import type {
   BookmarkAddress,
   BookmarkGetInput,
@@ -43,13 +44,19 @@ function validateBookmarkTarget(target: unknown, operationName: string): asserts
       { target },
     );
   }
+  if (t.story !== undefined) {
+    validateStoryLocator(t.story, `${operationName}.target.story`);
+  }
 }
 
 // ---------------------------------------------------------------------------
 // Execute wrappers
 // ---------------------------------------------------------------------------
 
 export function executeBookmarksList(adapter: BookmarksAdapter, query?: BookmarkListInput): BookmarksListResult {
+  if (query?.in !== undefined) {
+    validateStoryLocator(query.in, 'bookmarks.list.in');
+  }
   return adapter.list(query);
 }
 

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

@@ -1,5 +1,6 @@
 import type { Position } from '../types/base.js';
 import type { TextTarget } from '../types/address.js';
+import type { StoryLocator } from '../types/story.types.js';
 import type { AdapterMutationFailure } from '../types/adapter-result.js';
 import type { DiscoveryOutput } from '../types/discovery.js';
 
@@ -11,6 +12,18 @@ export interface BookmarkAddress {
   kind: 'entity';
   entityType: 'bookmark';
   name: string;
+  /**
+   * Story containing this bookmark. Omit for body (backward compatible).
+   *
+   * When omitted, bookmark operations resolve by `name` across the whole
+   * document. If multiple stories contain the same bookmark name, omitted-story
+   * lookup resolves to the first match returned by the implementation's
+   * document-wide bookmark scan; callers must not rely on a specific cross-story
+   * ordering rule. Prefer the `address` returned by bookmark read operations
+   * (`bookmarks.list`, `bookmarks.get`) because those responses populate
+   * `story` for non-body bookmarks.
+   */
+  story?: StoryLocator;
 }
 
 // ---------------------------------------------------------------------------
@@ -20,6 +33,8 @@ export interface BookmarkAddress {
 export interface BookmarkListInput {
   limit?: number;
   offset?: number;
+  /** Restrict listing to a specific story. Omit to search document-wide. */
+  in?: StoryLocator;
 }
 
 export interface BookmarkGetInput {

packages/document-api/src/contract/contract.test.ts

@@ -145,6 +145,26 @@ describe('document-api contract catalog', () => {
     ).toEqual(['forbid', 'allow']);
   });
 
+  it('allows story-scoped text targets for bookmark inserts', () => {
+    const schemas = buildInternalContractSchemas();
+    const bookmarkInsertInput = schemas.operations['bookmarks.insert'].input as {
+      properties?: {
+        at?: { $ref?: string };
+      };
+    };
+    const textTarget = schemas.$defs?.TextTarget as {
+      properties?: Record<string, unknown>;
+      required?: string[];
+      additionalProperties?: boolean;
+    };
+
+    expect(bookmarkInsertInput.properties?.at?.$ref).toBe('#/$defs/TextTarget');
+    expect(textTarget.properties).toHaveProperty('story');
+    expect((textTarget.properties?.story as { $ref?: string }).$ref).toBe('#/$defs/StoryLocator');
+    expect(textTarget.required).toEqual(['kind', 'segments']);
+    expect(textTarget.additionalProperties).toBe(false);
+  });
+
   it('accepts both object and array SDFragment in structural insert content schema', () => {
     const schemas = buildInternalContractSchemas();
     const insertInput = schemas.operations.insert.input as { oneOf?: Array<{ properties?: Record<string, unknown> }> };

packages/document-api/src/contract/schemas.ts

@@ -231,6 +231,7 @@ const SHARED_DEFS: Record<string, JsonSchema> = {
     {
       kind: { const: 'text' },
       segments: { type: 'array', items: ref('TextSegment'), minItems: 1 },
+      story: ref('StoryLocator'),
     },
     ['kind', 'segments'],
   ),
@@ -2520,10 +2521,12 @@ function buildContentControlSchemas(): Record<ContentControlOperationId, Operati
 // ---------------------------------------------------------------------------
 
 // --- Shared patterns ---
-const refListQuerySchema = objectSchema({
+const refListQueryProperties = {
   limit: { type: 'integer', minimum: 1 },
   offset: { type: 'integer', minimum: 0 },
-});
+} satisfies Record<string, JsonSchema>;
+
+const refListQuerySchema = objectSchema(refListQueryProperties);
 
 const discoveryOutputSchema: JsonSchema = { type: 'object' };
 
@@ -2567,7 +2570,12 @@ function refConfigSchemas(): { output: JsonSchema; success: JsonSchema; failure:
 
 // --- Bookmark schemas ---
 const bookmarkAddressSchema: JsonSchema = objectSchema(
-  { kind: { const: 'entity' }, entityType: { const: 'bookmark' }, name: { type: 'string' } },
+  {
+    kind: { const: 'entity' },
+    entityType: { const: 'bookmark' },
+    name: { type: 'string' },
+    story: ref('StoryLocator'),
+  },
   ['kind', 'entityType', 'name'],
 );
 
@@ -6993,7 +7001,10 @@ const operationSchemas: Record<OperationId, OperationSchemaSet> = {
   // Bookmarks
   // -------------------------------------------------------------------------
   'bookmarks.list': {
-    input: refListQuerySchema,
+    input: objectSchema({
+      ...refListQueryProperties,
+      in: storyLocatorSchema,
+    }),
     output: discoveryOutputSchema,
   },
   'bookmarks.get': {

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

@@ -1,5 +1,6 @@
 import type { BlockNodeType } from './base.js';
 import type { StoryLocator } from './story.types.js';
+import type { BookmarkAddress } from '../bookmarks/bookmarks.types.js';
 
 export type Range = {
   /** Inclusive start offset (0-based, UTF-16 code units). */
@@ -118,6 +119,12 @@ export type EntityType = 'comment' | 'trackedChange';
 export type CommentAddress = {
   kind: 'entity';
   entityType: 'comment';
+  /**
+   * Comment navigation is currently body-scoped only.
+   *
+   * Unlike bookmark and tracked-change navigation, `navigateTo()` does not yet
+   * accept a `story` locator for comments.
+   */
   entityId: string;
 };
 
@@ -145,6 +152,10 @@ export type EntityAddress = CommentAddress | TrackedChangeAddress;
  * queries (e.g. `query.match`, `find`, `getNode`) as the `nodeId`.
  *
  * When `nodeType` is omitted, the lookup searches across all block types.
+ *
+ * Block navigation is currently body-scoped only. For non-body stories such
+ * as headers, footers, footnotes, and endnotes, `navigateTo()` currently
+ * supports story-aware bookmark and tracked-change targets instead.
  */
 export type BlockNavigationAddress = {
   kind: 'block';
@@ -156,8 +167,13 @@ export type BlockNavigationAddress = {
  * 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`
+ * - Blocks by `nodeId` in the body story
+ * - Bookmarks by `name`, optionally scoped to a `story`
+ * - Comments by `entityId` in the body story
+ * - Tracked changes by `entityId`, optionally scoped to a `story`
+ *
+ * Story-aware navigation is currently supported for bookmarks and tracked
+ * changes. Block and comment targets remain body-only until the runtime gains
+ * equivalent non-body resolution paths.
  */
-export type NavigableAddress = BlockNavigationAddress | CommentAddress | TrackedChangeAddress;
+export type NavigableAddress = BlockNavigationAddress | BookmarkAddress | CommentAddress | TrackedChangeAddress;