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.

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,24 @@ 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 [];
+      // `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 [];
+      }
+      const startEl = document.elementFromPoint(input.x, input.y);
+      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

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

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

@@ -1369,4 +1369,48 @@ 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.
+   *
+   * 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,15 @@ describe('ui.viewport.scrollIntoView', () => {
     ui.destroy();
   });
 });
+
+describe('ui.viewport.entityAt — input validation', () => {
+  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();
+  });
+});