feat(ui): add ui.viewport.entityAt for typed point-to-entity lookup (SD-2936) (#3139)

* feat(ui): add ui.viewport.entityAt for typed point-to-entity lookup (SD-2936)

Right-click menus, hover tooltips, and any UI that asks "what's under
this point?" today read `data-track-change-id` and `data-comment-ids`
off `event.target.closest(...)` themselves. The attribute layout is
an implementation detail of the painter that consumers shouldn't
depend on, and the closest() walk makes id collisions silent (a
trackedChange inside a comment highlight surfaces only the innermost
hit).

ui.viewport.entityAt({ x, y }) takes viewport coordinates (matching
`MouseEvent.clientX/clientY` and `ViewportRect`) and returns
`ViewportEntityHit[]` — every painted entity in the chain, innermost
first. Supports `comment` and `trackedChange` today; `link`, `image`,
and `tableCell` are reserved as additive union members so consumers
switching on `hit.type` with a default branch stay forward-compatible.

The DOM walk is a pure helper (`collectEntityHitsFromChain`) so it's
testable without stubbing `document.elementFromPoint` (happy-dom in
this repo doesn't ship the method natively, and per-realm prototype
mutation didn't survive between the test and source files). The
controller method composes the helper with `elementFromPoint`.

Stacks on top of caio/sd-2936-selection-rects.

* 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.

* fix(ui): reach the DOM document via globalThis in entityAt (SD-2936)

Author: caio-pizzol

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

@@ -14,6 +14,7 @@ import type {
   ScrollIntoViewOutput,
   TrackChangesListResult,
 } from '@superdoc/document-api';
+import { collectEntityHitsFromChain } from './entity-at.js';
 import { shallowEqual } from './equality.js';
 import { scrollRangeIntoView } from './scroll-into-view.js';
 import { getSelectionAnchorRect, getSelectionRects } from './selection-rects.js';
@@ -44,6 +45,8 @@ import type {
   ToolbarHandle,
   ToolbarSnapshotSlice,
   UIToolbarCommandState,
+  ViewportEntityAtInput,
+  ViewportEntityHit,
   ViewportGetRectInput,
   ViewportHandle,
   ViewportRect,
@@ -1560,6 +1563,35 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
     async scrollIntoView(input: ScrollIntoViewInput): Promise<ScrollIntoViewOutput> {
       return runScrollIntoView(input);
     },
+
+    // The painter stamps `data-track-change-id` and `data-comment-ids`
+    // on each painted run; reading them back is what consumers were
+    // doing imperatively from `event.target.closest(...)` in
+    // contextmenu handlers. Centralizing the lookup here keeps the
+    // attribute names an implementation detail of the painter and
+    // surfaces a typed `EntityHit[]` consumers can switch on.
+    entityAt(input: ViewportEntityAtInput): ViewportEntityHit[] {
+      if (!input || typeof input.x !== 'number' || typeof input.y !== 'number') return [];
+      // The DOM `document` is reached through `globalThis.document`
+      // because the local `document: DocumentHandle` declared below
+      // would otherwise shadow it for type-checking. Guard SSR /
+      // non-browser stubs explicitly so the call doesn't throw in
+      // test environments without a global `document`.
+      const dom = (globalThis as { document?: Document }).document;
+      if (!dom || typeof dom.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 = dom.elementFromPoint(input.x, input.y);
+      if (!startEl || !host.contains(startEl)) return [];
+      return collectEntityHitsFromChain(startEl);
+    },
   };
 
   // ---- ui.selection ------------------------------------------------------

packages/super-editor/src/ui/entity-at.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+
+import { collectEntityHitsFromChain } from './entity-at.js';
+
+/**
+ * Build a chain of nested HTMLElements with the dataset stamps the
+ * painter would set. `layers[0]` becomes the innermost element;
+ * subsequent layers wrap it. Returns the innermost element — the one
+ * `document.elementFromPoint` would normally return for a click on
+ * the innermost painted run.
+ */
+function buildPaintedChain(layers: Array<{ trackChangeId?: string; commentIds?: string }>): HTMLElement {
+  const innerLayer = layers[0]!;
+  const inner = document.createElement('span');
+  if (innerLayer.trackChangeId) inner.dataset.trackChangeId = innerLayer.trackChangeId;
+  if (innerLayer.commentIds) inner.dataset.commentIds = innerLayer.commentIds;
+
+  let outer: HTMLElement = inner;
+  for (let i = 1; i < layers.length; i += 1) {
+    const layer = layers[i]!;
+    const wrapper = document.createElement('span');
+    if (layer.trackChangeId) wrapper.dataset.trackChangeId = layer.trackChangeId;
+    if (layer.commentIds) wrapper.dataset.commentIds = layer.commentIds;
+    wrapper.appendChild(outer);
+    outer = wrapper;
+  }
+  document.body.appendChild(outer);
+  return inner;
+}
+
+describe('collectEntityHitsFromChain', () => {
+  it('returns hits for tracked-change and comment data attributes, innermost first', () => {
+    const inner = buildPaintedChain([{ trackChangeId: 'tc-1' }, { commentIds: 'c-1' }]);
+
+    expect(collectEntityHitsFromChain(inner)).toEqual([
+      { type: 'trackedChange', id: 'tc-1' },
+      { type: 'comment', id: 'c-1' },
+    ]);
+  });
+
+  it('expands comma-separated comment ids into one hit per id', () => {
+    const inner = buildPaintedChain([{ commentIds: 'c-1,c-2,c-3' }]);
+
+    expect(collectEntityHitsFromChain(inner)).toEqual([
+      { type: 'comment', id: 'c-1' },
+      { type: 'comment', id: 'c-2' },
+      { type: 'comment', id: 'c-3' },
+    ]);
+  });
+
+  it('deduplicates the same id when it appears multiple times in the chain', () => {
+    const inner = buildPaintedChain([{ commentIds: 'c-1' }, { commentIds: 'c-1' }]);
+
+    expect(collectEntityHitsFromChain(inner)).toEqual([{ type: 'comment', id: 'c-1' }]);
+  });
+
+  it('combines trackedChange + comment + outer comment in document order (innermost → outermost)', () => {
+    const inner = buildPaintedChain([{ trackChangeId: 'tc-1' }, { commentIds: 'c-inner' }, { commentIds: 'c-outer' }]);
+
+    expect(collectEntityHitsFromChain(inner)).toEqual([
+      { type: 'trackedChange', id: 'tc-1' },
+      { type: 'comment', id: 'c-inner' },
+      { type: 'comment', id: 'c-outer' },
+    ]);
+  });
+
+  it('returns [] when the chain has no painted entities', () => {
+    const inner = buildPaintedChain([{}]);
+
+    expect(collectEntityHitsFromChain(inner)).toEqual([]);
+  });
+
+  it('returns [] for null or non-Element starts', () => {
+    expect(collectEntityHitsFromChain(null)).toEqual([]);
+    expect(collectEntityHitsFromChain({} as never)).toEqual([]);
+  });
+
+  it('skips empty ids in a malformed comma list', () => {
+    const inner = buildPaintedChain([{ commentIds: ',c-1,,c-2,' }]);
+
+    expect(collectEntityHitsFromChain(inner)).toEqual([
+      { type: 'comment', id: 'c-1' },
+      { type: 'comment', id: 'c-2' },
+    ]);
+  });
+});

packages/super-editor/src/ui/entity-at.ts

@@ -0,0 +1,59 @@
+/**
+ * Walk a painted-DOM element chain (innermost → outermost) and
+ * collect entity hits for `ui.viewport.entityAt`.
+ *
+ * Pure function — takes a starting element, returns the hits. The
+ * `document.elementFromPoint` lookup that produces the starting
+ * element lives in the controller; this helper is what makes the
+ * data-attribute walk testable without stubbing globals.
+ */
+
+import type { ViewportEntityHit } from './types.js';
+
+/**
+ * Read painted entities off `el` and every ancestor up to the document
+ * root. Innermost-first ordering: a tracked change inside a comment
+ * highlight returns `[{ trackedChange }, { comment }]`, matching what
+ * a switch on `hits[0]` expects when picking the most specific entity.
+ *
+ * Returns `[]` for null / non-Element starts. Uses duck-typed
+ * `getAttribute` access so it works under any DOM implementation
+ * (happy-dom, jsdom, real browser) without an `instanceof` check that
+ * could fail across realms.
+ */
+export function collectEntityHitsFromChain(start: Element | null): ViewportEntityHit[] {
+  if (!start || typeof (start as { getAttribute?: unknown }).getAttribute !== 'function') {
+    return [];
+  }
+
+  const hits: ViewportEntityHit[] = [];
+  const seen = new Set<string>();
+  let el: Element | null = start;
+  while (el) {
+    const node = el as { getAttribute(name: string): string | null };
+    const trackChangeId = node.getAttribute('data-track-change-id');
+    if (trackChangeId) {
+      const key = `trackedChange:${trackChangeId}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        hits.push({ type: 'trackedChange', id: trackChangeId });
+      }
+    }
+    const commentIds = node.getAttribute('data-comment-ids');
+    if (commentIds) {
+      // The painter stamps overlapping comments as a comma-separated
+      // list — surface each id as its own hit so a "Resolve this
+      // comment" item in a context menu can target the right one.
+      for (const id of commentIds.split(',')) {
+        if (!id) continue;
+        const key = `comment:${id}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          hits.push({ type: 'comment', id });
+        }
+      }
+    }
+    el = el.parentElement;
+  }
+  return hits;
+}

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

@@ -120,6 +120,8 @@ export type {
   TrackChangesSlice,
 
   // Viewport
+  ViewportEntityAtInput,
+  ViewportEntityHit,
   ViewportGetRectInput,
   ViewportHandle,
   ViewportRect,

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;
 }
 
@@ -1369,4 +1377,54 @@ export interface ViewportHandle {
   scrollIntoView(
     input: import('@superdoc/document-api').ScrollIntoViewInput,
   ): Promise<import('@superdoc/document-api').ScrollIntoViewOutput>;
+  /**
+   * 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-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
+   * 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;
+   * adding them is purely additive (new union members), so callers can
+   * `switch` on `hit.type` and the default branch remains forward
+   * compatible.
+   */
+  entityAt(input: ViewportEntityAtInput): ViewportEntityHit[];
 }
+
+/**
+ * Input shape for {@link ViewportHandle.entityAt}. Coordinates are
+ * viewport-relative (the same space `MouseEvent.clientX` /
+ * `clientY` produce, and the same space {@link ViewportRect} reports
+ * back), so a `contextmenu` handler can pass `event.clientX` /
+ * `event.clientY` directly.
+ */
+export interface ViewportEntityAtInput {
+  x: number;
+  y: number;
+}
+
+/**
+ * One hit returned by {@link ViewportHandle.entityAt}.
+ *
+ * The union is intentionally narrow today (`comment` /
+ * `trackedChange`); other entity types land via additive union
+ * members so a `switch` on `hit.type` with a default branch stays
+ * forward compatible.
+ */
+export type ViewportEntityHit = { type: 'comment'; id: string } | { type: 'trackedChange'; id: string };

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

@@ -310,3 +310,55 @@ describe('ui.viewport.scrollIntoView', () => {
     ui.destroy();
   });
 });
+
+describe('ui.viewport.entityAt — host scoping', () => {
+  it('returns [] for invalid input (missing or non-numeric coordinates)', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    expect(ui.viewport.entityAt({} as never)).toEqual([]);
+    expect(ui.viewport.entityAt({ x: 'a', y: 0 } as never)).toEqual([]);
+
+    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,