feat(ui): context-menu contribution API on ui.commands (SD-2936) (#3145)

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

* feat(ui): context-menu contribution API on ui.commands (SD-2936)

* fix(ui): stabilize custom-group rank in getContextMenuItems (SD-2936)

Author: caio-pizzol

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

@@ -24,6 +24,7 @@ import type {
   CommandHandle,
   CommandsHandle,
   CommentsHandle,
+  ContextMenuItem,
   DocumentExportInput,
   DocumentHandle,
   DocumentSlice,
@@ -1165,6 +1166,15 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
           return handle;
         };
       }
+      // Custom-UI consumers building their own context menu pull
+      // contributed items here. Computed against the current snapshot
+      // (so `selection` matches what observers just saw) and the
+      // caller-supplied entities from `ui.viewport.entityAt`.
+      if (prop === 'getContextMenuItems') {
+        return (input?: { entities?: ViewportEntityHit[] }): ContextMenuItem[] => {
+          return customCommandsRegistry.getContextMenuItems(computeState(), input?.entities ?? []);
+        };
+      }
       // Custom-registered ids surface a typed handle from the registry.
       // Built-in ids fall through to the existing per-id cache so they
       // keep the same observe/execute shape they had before SD-2802.

packages/super-editor/src/ui/custom-commands.test.ts

@@ -949,3 +949,200 @@ describe('ui.commands.get', () => {
     ui.destroy();
   });
 });
+
+describe('ui.commands.getContextMenuItems', () => {
+  it('returns [] when no registered command carries a contextMenu field', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    ui.commands.register({ id: 'company.plain', execute: () => true });
+
+    expect(ui.commands.getContextMenuItems()).toEqual([]);
+
+    ui.destroy();
+  });
+
+  it('surfaces contributions, filling defaults for group / order', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    ui.commands.register({
+      id: 'company.acceptChange',
+      execute: () => true,
+      contextMenu: { label: 'Accept suggestion' },
+    });
+
+    expect(ui.commands.getContextMenuItems()).toEqual([
+      { id: 'company.acceptChange', label: 'Accept suggestion', group: 'custom', order: 0 },
+    ]);
+
+    ui.destroy();
+  });
+
+  it('filters items by the when predicate using caller-supplied entities + current selection', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    const whenSpy = vi.fn(({ entities }) => entities.some((e) => e.type === 'trackedChange'));
+    ui.commands.register({
+      id: 'company.acceptChange',
+      execute: () => true,
+      contextMenu: { label: 'Accept suggestion', group: 'review', when: whenSpy },
+    });
+
+    expect(ui.commands.getContextMenuItems({ entities: [{ type: 'comment', id: 'c1' }] })).toEqual([]);
+    expect(ui.commands.getContextMenuItems({ entities: [{ type: 'trackedChange', id: 'tc1' }] })).toHaveLength(1);
+
+    expect(whenSpy).toHaveBeenCalledTimes(2);
+    expect(whenSpy.mock.calls[0]![0].selection).toBeDefined();
+
+    ui.destroy();
+  });
+
+  it('sorts by built-in group order, then order, then registration sequence', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    // Built-in group order: format(0), clipboard(1), review(2), comment(3), link(4)
+    ui.commands.register({
+      id: 'a.review-2',
+      execute: () => true,
+      contextMenu: { label: 'Review B', group: 'review', order: 20 },
+    });
+    ui.commands.register({
+      id: 'b.format-1',
+      execute: () => true,
+      contextMenu: { label: 'Format A', group: 'format', order: 0 },
+    });
+    ui.commands.register({
+      id: 'c.review-1',
+      execute: () => true,
+      contextMenu: { label: 'Review A', group: 'review', order: 10 },
+    });
+    ui.commands.register({
+      id: 'd.review-tie-second',
+      execute: () => true,
+      contextMenu: { label: 'Review C', group: 'review', order: 10 },
+    });
+    ui.commands.register({
+      id: 'e.custom',
+      execute: () => true,
+      contextMenu: { label: 'Z', group: 'company.workflow', order: 0 },
+    });
+
+    expect(ui.commands.getContextMenuItems().map((i) => i.id)).toEqual([
+      'b.format-1',
+      'c.review-1',
+      'd.review-tie-second',
+      'a.review-2',
+      'e.custom',
+    ]);
+
+    ui.destroy();
+  });
+
+  it('plain custom commands (no contextMenu) do not anchor a custom group rank', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    // Register a plain command first (seq 0) — it has no contextMenu
+    // and must not claim the 'custom' fallback group's rank anchor.
+    ui.commands.register({ id: 'a.plain', execute: () => true });
+    // Register a workflow contribution (seq 1).
+    ui.commands.register({
+      id: 'b.workflow',
+      execute: () => true,
+      contextMenu: { label: 'Workflow A', group: 'company.workflow' },
+    });
+    // Register a 'custom' fallback group contribution (seq 2).
+    ui.commands.register({
+      id: 'c.custom',
+      execute: () => true,
+      contextMenu: { label: 'Default A' },
+    });
+
+    // 'company.workflow' (seq 1) must rank before 'custom' (seq 2).
+    // If the plain seq=0 command anchored 'custom', the order would
+    // flip.
+    expect(ui.commands.getContextMenuItems().map((i) => i.id)).toEqual(['b.workflow', 'c.custom']);
+
+    ui.destroy();
+  });
+
+  it('preserves a group rank anchor when one contributor is replaced and another remains', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    // Group 'workflow' opens with two contributors at seq 0 and seq 1.
+    ui.commands.register({
+      id: 'wf.first',
+      execute: () => true,
+      contextMenu: { label: 'WF 1', group: 'company.workflow', order: 0 },
+    });
+    ui.commands.register({
+      id: 'wf.second',
+      execute: () => true,
+      contextMenu: { label: 'WF 2', group: 'company.workflow', order: 1 },
+    });
+    // A second custom group registers at seq 2.
+    ui.commands.register({
+      id: 'rev.first',
+      execute: () => true,
+      contextMenu: { label: 'Rev 1', group: 'company.review-extras', order: 0 },
+    });
+
+    // Now replace `wf.first` — the new seq becomes 3, but `wf.second`
+    // still carries the original seq 1, so the workflow group's
+    // anchor must stay at 1 and render before 'review-extras' (seq 2).
+    ui.commands.register({
+      id: 'wf.first',
+      execute: () => true,
+      contextMenu: { label: 'WF 1 (replaced)', group: 'company.workflow', order: 0 },
+    });
+
+    expect(ui.commands.getContextMenuItems().map((i) => i.id)).toEqual(['wf.first', 'wf.second', 'rev.first']);
+
+    ui.destroy();
+  });
+
+  it('hides items whose when predicate throws and logs the error once per distinct message', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    ui.commands.register({
+      id: 'company.flaky',
+      execute: () => true,
+      contextMenu: {
+        label: 'Flaky',
+        when: () => {
+          throw new Error('boom');
+        },
+      },
+    });
+
+    expect(ui.commands.getContextMenuItems()).toEqual([]);
+    expect(ui.commands.getContextMenuItems()).toEqual([]);
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+
+    ui.destroy();
+  });
+
+  it("refuses 'getContextMenuItems' as a custom command id (Proxy collision)", () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    const reg = ui.commands.register({
+      id: 'getContextMenuItems',
+      execute: () => true,
+      contextMenu: { label: 'Should not register' },
+    });
+
+    expect(warnSpy).toHaveBeenCalled();
+    // Refused registrations get a no-op handle, so the contribution
+    // never enters the registry.
+    expect(ui.commands.getContextMenuItems()).toEqual([]);
+    reg.unregister();
+
+    ui.destroy();
+  });
+});