fix(ui): scope entityAt to mounted host + publish new types (SD-2936)

Two review issues from PR #3139:

1. entityAt previously called document.elementFromPoint globally and
   walked all ancestors with no check that the controller had a
   mounted editor or that the hit landed inside this instance's
   painted DOM. A page mounting two SuperDoc instances would have
   one's entityAt return ids from the other; post-destroy calls
   would return stale ids from cached painted nodes. Now resolves
   the host editor via resolveHostEditor, reads
   presentationEditor.visibleHost (newly added to the structural
   type), and returns [] when the host is missing or the hit
   element isn't inside it.

2. The published `superdoc/ui` declaration barrel at
   packages/superdoc/src/ui.d.ts didn't list the new public types,
   so `import type { ViewportEntityHit, ViewportEntityAtInput } from
   'superdoc/ui'` failed for consumers. Same gap existed for
   SelectionAnchorRectOptions from PR #3134. Added all three.

Author: caio-pizzol

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

@@ -1572,13 +1572,21 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
     // surfaces a typed `EntityHit[]` consumers can switch on.
     entityAt(input: ViewportEntityAtInput): ViewportEntityHit[] {
       if (!input || typeof input.x !== 'number' || typeof input.y !== 'number') return [];
-      // `document.elementFromPoint` is the only entry point — guard
+      // `document.elementFromPoint` is the only entry point. Guard
       // SSR / non-browser stubs explicitly so the call doesn't throw
       // in test environments without a global `document`.
       if (typeof document === 'undefined' || typeof document.elementFromPoint !== 'function') {
         return [];
       }
+      // Scope the lookup to this controller's editor: a page mounting
+      // two SuperDoc instances would otherwise have one's entityAt
+      // return ids from the other's painted DOM. A null host (no
+      // editor mounted, post-destroy, SSR test stub) returns [].
+      const editor = resolveHostEditor(superdoc);
+      const host = editor?.presentationEditor?.visibleHost;
+      if (!host) return [];
       const startEl = document.elementFromPoint(input.x, input.y);
+      if (!startEl || !host.contains(startEl)) return [];
       return collectEntityHitsFromChain(startEl);
     },
   };

packages/super-editor/src/ui/types.ts

@@ -169,6 +169,14 @@ export interface SuperDocEditorLike {
       width: number;
       height: number;
     }>;
+    /**
+     * Painted-DOM host element. `ui.viewport.entityAt` reads it to
+     * confirm the hit returned by `document.elementFromPoint` lives
+     * inside this controller's editor — without that scope check, a
+     * page mounting two SuperDoc instances would return entity ids
+     * from the wrong instance.
+     */
+    visibleHost?: HTMLElement;
   } | null;
 }
 
@@ -1373,19 +1381,25 @@ export interface ViewportHandle {
    * Look up entities painted under a viewport coordinate. Used by
    * right-click menus and hover tooltips to ask "what's at this point?"
    * without consumers reading `data-track-change-id` /
-   * `data-comment-ids` off the painted DOM themselves — the
+   * `data-comment-ids` off the painted DOM themselves; the
    * data-attribute layout is an implementation detail of the painter
    * that consumers shouldn't depend on.
    *
    * Returns an ordered array of {@link ViewportEntityHit}, innermost
    * first. A point can sit inside several entities at once (a tracked
-   * change inside a comment highlight, for example) — every match is
+   * change inside a comment highlight, for example); every match is
    * surfaced, not just the topmost. Empty array when the point isn't
    * over any painted entity, when called outside a browser, or when no
    * editor is mounted.
    *
+   * Scoped to the controller's own editor: hits are only returned when
+   * the point lands inside this editor's painted host. A page mounting
+   * two SuperDoc instances therefore can't have one controller return
+   * ids from the other's DOM, and post-destroy calls return `[]`
+   * rather than stale ids from cached painted nodes.
+   *
    * Today the supported entity types are `comment` and `trackedChange`.
-   * `link`, `image`, and `tableCell` are reserved for follow-ups —
+   * `link`, `image`, and `tableCell` are reserved for follow-ups;
    * adding them is purely additive (new union members), so callers can
    * `switch` on `hit.type` and the default branch remains forward
    * compatible.

packages/super-editor/src/ui/viewport.test.ts

@@ -311,7 +311,7 @@ describe('ui.viewport.scrollIntoView', () => {
   });
 });
 
-describe('ui.viewport.entityAt — input validation', () => {
+describe('ui.viewport.entityAt — host scoping', () => {
   it('returns [] for invalid input (missing or non-numeric coordinates)', () => {
     const { superdoc } = makeStubs();
     const ui = createSuperDocUI({ superdoc });
@@ -321,4 +321,44 @@ describe('ui.viewport.entityAt — input validation', () => {
 
     ui.destroy();
   });
+
+  it('returns [] when no editor is mounted (no presentationEditor.visibleHost)', () => {
+    const { superdoc } = makeStubs();
+    // Stub editor has no `visibleHost` on its presentationEditor —
+    // simulating SSR / non-paginated mounts and post-destroy state.
+    const ui = createSuperDocUI({ superdoc });
+
+    expect(ui.viewport.entityAt({ x: 10, y: 10 })).toEqual([]);
+
+    ui.destroy();
+  });
+
+  it('returns [] when the hit element is outside the controller`s painted host', () => {
+    const { superdoc } = makeStubs();
+    // Mount a fake host on the stub presentation editor and put the
+    // "hit" element OUTSIDE that host — the equivalent of a second
+    // SuperDoc instance painting the cursor target.
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    (
+      superdoc.activeEditor as unknown as { presentationEditor: { visibleHost: HTMLElement } }
+    ).presentationEditor.visibleHost = host;
+
+    const outside = document.createElement('span');
+    outside.dataset.commentIds = 'c-foreign';
+    document.body.appendChild(outside);
+
+    const docAny = document as unknown as { elementFromPoint?: (x: number, y: number) => Element | null };
+    const original = docAny.elementFromPoint;
+    docAny.elementFromPoint = () => outside;
+
+    const ui = createSuperDocUI({ superdoc });
+    expect(ui.viewport.entityAt({ x: 0, y: 0 })).toEqual([]);
+
+    if (original) docAny.elementFromPoint = original;
+    else delete docAny.elementFromPoint;
+    outside.remove();
+    host.remove();
+    ui.destroy();
+  });
 });

packages/superdoc/src/ui.d.ts

@@ -23,6 +23,7 @@ export {
   type Receipt,
   type ScrollIntoViewInput,
   type ScrollIntoViewOutput,
+  type SelectionAnchorRectOptions,
   type SelectionCapture,
   type SelectionHandle,
   type SelectionInfo,
@@ -50,6 +51,8 @@ export {
   type TrackChangesSlice,
   type TrackedChangeAddress,
   type UIToolbarCommandState,
+  type ViewportEntityAtInput,
+  type ViewportEntityHit,
   type ViewportGetRectInput,
   type ViewportHandle,
   type ViewportRect,