feat(ui): story-aware selection state and capture/restore (SD-2954) (#3166)

* feat(ui): add ui.viewport.getHost and positionAt (SD-2943)

Two primitives consumers building custom UI keep reaching for and not
finding on the public surface:

ui.viewport.getHost() returns the editor's painted host element so
custom-UI components scope DOM listeners to the editor without a CSS
class filter. The information already lives on
presentationEditor.visibleHost; this lifts it onto the controller.

ui.viewport.positionAt({ x, y }) resolves a viewport coordinate to a
caret position on the routed editor's PM document, returning both the
SelectionPoint and the SelectionTarget shapes so consumers can pass
the result straight to editor.doc.insert / replace / etc. The natural
pair to entityAt: while entityAt answers "what entity is under this
point?", positionAt answers "what caret position is under this
point?" — the missing primitive that lets right-click menus offer
"Paste here" / "Insert at this point" honestly, instead of dispatching
against the user's previous selection.

Both methods scope to the controller's painted host: a multi-instance
page can't have one controller's positionAt return positions in
another's PM doc, and post-destroy calls return null.

Tests cover the happy path, the no-editor-mounted case, and the
missing-posAtCoords stub case.

* fix(ui): canonical sdBlockId fallback + story scope on positionAt (SD-2943)

readBlockId now uses the sdBlockId ?? id ?? blockId fallback the
selection resolver already applies, so positionAt resolves paragraph
clicks instead of returning null. Adds PresentationEditor.getActiveStoryLocator
(unifies story-session and header/footer-session locators) and threads
the result onto SelectionPoint.story / SelectionTarget.story so doc-api
operations route to the active story instead of falling back to body.

* feat(ui): story-aware selection state and capture/restore (SD-2954)

The controller stamps the active story locator onto the live
TextTarget when the routed editor is a header/footer/footnote/endnote,
so state.selection.target / selectionTarget and ui.selection.capture()
all carry the same routing information ui.viewport.positionAt got in
SD-2943. ui.selection.restore now compares the captured story against
the active surface and returns a typed 'stale' on mismatch instead of
falling through to a less-specific resolver failure. Captures with no
story keep the prior body/default behavior.

The fix is scoped to the controller surface. Direct
editor.doc.selection.current() calls still return body-scoped targets;
threading story through the lower-level resolver is a separate change.

* fix(ui): jsdoc placement + restore guard order (SD-2954)

Move readActiveStoryLocator and attachStoryToTextTarget below
textTargetToSelectionTarget so the existing JSDoc reattaches to its
function (it was orphaned between two JSDoc blocks).

Move the SD-2954 story-mismatch check after the isEditable / setTextSelection
guards so a header capture restored against a viewing-mode editor
still surfaces 'read-only', matching what body captures already see
in the same condition. Adds a regression test covering the read-only
+ story-capture path.

* fix(ui): resolve story locator via resolveToolbarSources for SD-2954

readActiveStoryLocator was reading hostEditor.presentationEditor
directly, missing the legacy _presentationEditor field and the
superdocStore.documents[].getPresentationEditor() lookup that
resolveToolbarSources covers. Mounts using either fallback would still
report body-scoped selection state and return 'stale' for valid story
captures.

Route the locator lookup through resolveToolbarSources so all three
documented presentation-resolution paths surface the active story.
Selection-restore drops its duplicate helper and accepts the
pre-resolved locator from the controller, removing the separate code
path. Adds a regression test covering the _presentationEditor fallback.

Author: caio-pizzol

packages/super-editor/src/ui/create-super-doc-ui.test.ts

@@ -552,6 +552,173 @@ describe('createSuperDocUI', () => {
     });
   });
 
+  // SD-2954: when the live selection resolver returns a TextTarget
+  // without `story` (the resolver runs against the routed editor and
+  // has no path back to the host's PresentationEditor), the
+  // controller stamps the active story locator at the seam where
+  // both editors are reachable. Without this stamping the live
+  // selection slice carries body-scoped targets even when the user
+  // is editing a header, and downstream doc-api ops route to body
+  // and silently fail to find the block.
+  it('state.selection.target gets the active story locator stamped when the resolver omits it', async () => {
+    const headerStory = { kind: 'story', storyType: 'headerFooterPart', refId: 'rId7' };
+
+    const headerEditor = {
+      on: vi.fn(),
+      off: vi.fn(),
+      state: { selection: { empty: false } },
+      isEditable: true,
+      doc: {
+        selection: {
+          current: vi.fn(() => ({
+            empty: false,
+            text: 'header text',
+            // Resolver returns no story field. Controller must stamp it.
+            target: { kind: 'text', segments: [{ blockId: 'h1', range: { start: 0, end: 4 } }] },
+            activeMarks: [],
+            activeCommentIds: [],
+            activeChangeIds: [],
+          })),
+        },
+      },
+    };
+
+    const presentationEditor: Record<string, unknown> = {
+      on: vi.fn(),
+      off: vi.fn(),
+      isEditable: true,
+      state: { selection: { empty: false } },
+      // Body editor is the host; routed editor is the header.
+      getActiveEditor: vi.fn(() => headerEditor),
+      getActiveStoryLocator: vi.fn(() => headerStory),
+      commands: {},
+    };
+
+    const bodyEditor = {
+      on: vi.fn(),
+      off: vi.fn(),
+      state: { selection: { empty: true } },
+      isEditable: true,
+      doc: {
+        selection: {
+          current: vi.fn(() => ({
+            empty: true,
+            target: null,
+            activeMarks: [],
+            activeCommentIds: [],
+            activeChangeIds: [],
+          })),
+        },
+      },
+    };
+    (bodyEditor as unknown as { _presentationEditor: unknown })._presentationEditor = presentationEditor;
+    (bodyEditor as unknown as { presentationEditor: unknown }).presentationEditor = presentationEditor;
+
+    const superdoc = {
+      activeEditor: bodyEditor as never,
+      config: { documentMode: 'editing' as const },
+      on: vi.fn(),
+      off: vi.fn(),
+    };
+
+    const ui = createSuperDocUI({ superdoc });
+    teardown.push(() => ui.destroy());
+
+    const slice = ui.select((state) => state.selection).get();
+    expect(slice.target).toEqual({
+      kind: 'text',
+      segments: [{ blockId: 'h1', range: { start: 0, end: 4 } }],
+      story: headerStory,
+    });
+    expect(slice.selectionTarget).toEqual({
+      kind: 'selection',
+      start: { kind: 'text', blockId: 'h1', offset: 0, story: headerStory },
+      end: { kind: 'text', blockId: 'h1', offset: 4, story: headerStory },
+      story: headerStory,
+    });
+  });
+
+  // SD-2954 regression: `resolveToolbarSources` resolves the
+  // PresentationEditor through three documented paths, the direct
+  // `activeEditor.presentationEditor` field, the legacy
+  // `activeEditor._presentationEditor` field, and the
+  // `superdocStore.documents[].getPresentationEditor()` lookup.
+  // `readActiveStoryLocator` reads the locator through the same
+  // pipeline so all three paths surface the active story. Reading
+  // `activeEditor.presentationEditor` directly would silently miss
+  // the latter two and the new selection slice would stay
+  // body-scoped on those mounts.
+  it('state.selection.target picks up the active story via the legacy _presentationEditor field', () => {
+    const headerStory = { kind: 'story', storyType: 'headerFooterPart', refId: 'rId-legacy' };
+
+    const headerEditor = {
+      on: vi.fn(),
+      off: vi.fn(),
+      state: { selection: { empty: false } },
+      isEditable: true,
+      doc: {
+        selection: {
+          current: vi.fn(() => ({
+            empty: false,
+            text: 'header text',
+            target: { kind: 'text', segments: [{ blockId: 'h1', range: { start: 0, end: 4 } }] },
+            activeMarks: [],
+            activeCommentIds: [],
+            activeChangeIds: [],
+          })),
+        },
+      },
+    };
+
+    const presentationEditor: Record<string, unknown> = {
+      on: vi.fn(),
+      off: vi.fn(),
+      isEditable: true,
+      state: { selection: { empty: false } },
+      getActiveEditor: vi.fn(() => headerEditor),
+      getActiveStoryLocator: vi.fn(() => headerStory),
+      commands: {},
+    };
+
+    // Mount only via the legacy `_presentationEditor` field. The new
+    // selection state must still pick up the active story.
+    const bodyEditor = {
+      on: vi.fn(),
+      off: vi.fn(),
+      state: { selection: { empty: true } },
+      isEditable: true,
+      doc: {
+        selection: {
+          current: vi.fn(() => ({
+            empty: true,
+            target: null,
+            activeMarks: [],
+            activeCommentIds: [],
+            activeChangeIds: [],
+          })),
+        },
+      },
+    };
+    (bodyEditor as unknown as { _presentationEditor: unknown })._presentationEditor = presentationEditor;
+
+    const superdoc = {
+      activeEditor: bodyEditor as never,
+      config: { documentMode: 'editing' as const },
+      on: vi.fn(),
+      off: vi.fn(),
+    };
+
+    const ui = createSuperDocUI({ superdoc });
+    teardown.push(() => ui.destroy());
+
+    const slice = ui.select((state) => state.selection).get();
+    expect(slice.target).toEqual({
+      kind: 'text',
+      segments: [{ blockId: 'h1', range: { start: 0, end: 4 } }],
+      story: headerStory,
+    });
+  });
+
   it('state.selection.selectionTarget is null when target is null', () => {
     const superdoc = makeSuperdocStub();
     (superdoc.activeEditor as { doc: { selection: { current: unknown } } }).doc.selection.current = vi.fn(() => ({

packages/super-editor/src/ui/create-super-doc-ui.ts

@@ -302,6 +302,59 @@ function textTargetToSelectionTarget(
   return story ? { kind: 'selection', start, end, story } : { kind: 'selection', start, end };
 }
 
+/**
+ * Reads the currently routed story from the host's PresentationEditor.
+ * Returns `null` when the body editor is active or when no presentation
+ * layer is reachable (older mounts, server-side stubs).
+ *
+ * Routes through `resolveToolbarSources` so all three documented
+ * presentation-resolution paths surface the locator: the direct
+ * `activeEditor.presentationEditor` field, the legacy
+ * `activeEditor._presentationEditor` field, and the
+ * `superdocStore.documents[].getPresentationEditor()` lookup that
+ * non-Vue mounts rely on. Reading `hostEditor.presentationEditor`
+ * directly would silently miss the latter two and the new selection
+ * slice would stay body-scoped on those setups.
+ *
+ * The selection-info resolver runs against the routed editor and has
+ * no path back to the host, so the controller stamps the locator onto
+ * the live TextTarget at the seam where both editors are reachable.
+ * Same shape SD-2943's `ui.viewport.positionAt` uses for the same
+ * reason: without it, downstream doc-api ops fall back to body and
+ * fail to locate the block.
+ */
+function readActiveStoryLocator(
+  superdoc: SuperDocUIOptions['superdoc'],
+): import('@superdoc/document-api').StoryLocator | null {
+  let presentation: { getActiveStoryLocator?: () => unknown } | null = null;
+  try {
+    const sources = resolveToolbarSources(superdoc as never);
+    presentation = (sources.presentationEditor as never) ?? null;
+  } catch {
+    return null;
+  }
+  if (!presentation || typeof presentation.getActiveStoryLocator !== 'function') return null;
+  try {
+    return (presentation.getActiveStoryLocator() ?? null) as import('@superdoc/document-api').StoryLocator | null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Stamp `story` onto a live TextTarget when the routed editor is a
+ * non-body story and the resolver didn't already attach it. Idempotent
+ * when `story` is already present (resolver-attached or otherwise).
+ */
+function attachStoryToTextTarget(
+  textTarget: import('@superdoc/document-api').TextTarget | null,
+  story: import('@superdoc/document-api').StoryLocator | null,
+): import('@superdoc/document-api').TextTarget | null {
+  if (!textTarget || !story) return textTarget;
+  if ((textTarget as { story?: unknown }).story) return textTarget;
+  return { ...textTarget, story };
+}
+
 export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
   const { superdoc } = options;
 
@@ -605,7 +658,20 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
     // inside the resolver) keeps the slice identity stable and lets
     // `shallowEqual` short-circuit `ui.select(s => s.selection)`
     // subscribers.
-    const selectionTextTarget = (selectionInfo?.target ?? null) as import('@superdoc/document-api').TextTarget | null;
+    // SD-2954: when the routed editor is a non-body story, stamp the
+    // active story locator onto the live TextTarget. The selection
+    // resolver runs against the routed editor and has no path back to
+    // the host's PresentationEditor, so the controller seam is the
+    // only place where both are reachable. Direct
+    // `editor.doc.selection.current()` calls are unaffected by design;
+    // a deeper adapter change would be a separate ticket.
+    const hostEditor = resolveHostEditor(superdoc);
+    const routedIsStory = editor != null && hostEditor != null && editor !== hostEditor;
+    const activeStory = routedIsStory ? readActiveStoryLocator(superdoc) : null;
+    const selectionTextTarget = attachStoryToTextTarget(
+      (selectionInfo?.target ?? null) as import('@superdoc/document-api').TextTarget | null,
+      activeStory,
+    );
     const selectionActiveMarks = (selectionInfo?.activeMarks ?? EMPTY_ACTIVE_IDS) as string[];
     const selectionKey = buildSelectionKey(
       empty,
@@ -1761,8 +1827,18 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
       // time, the routed editor is body and resolution returns
       // `'stale'` rather than placing the selection on the wrong
       // surface.
+      //
+      // Story locator (SD-2954): pre-resolved here so the helper
+      // doesn't have to repeat the presentation-editor lookup.
+      // `readActiveStoryLocator` routes through `resolveToolbarSources`
+      // and covers the direct, legacy `_presentationEditor`, and
+      // `superdocStore.documents[].getPresentationEditor()` paths
+      // uniformly.
       const editor = resolveRoutedEditor(superdoc);
-      return restoreSelection(editor as unknown as Parameters<typeof restoreSelection>[0], capture);
+      const activeStory = readActiveStoryLocator(superdoc);
+      return restoreSelection(editor as unknown as Parameters<typeof restoreSelection>[0], capture, {
+        activeStory,
+      });
     },
   };