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

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

@@ -16,6 +16,7 @@ import type {
 } from '@superdoc/document-api';
 import { collectEntityHitsFromChain } from './entity-at.js';
 import { shallowEqual } from './equality.js';
+import { resolvePositionAt } from './position-at.js';
 import { shortcutFromEvent } from './keyboard-shortcuts.js';
 import { scrollRangeIntoView } from './scroll-into-view.js';
 import { getSelectionAnchorRect, getSelectionRects } from './selection-rects.js';
@@ -51,6 +52,8 @@ import type {
   ViewportEntityAtInput,
   ViewportEntityHit,
   ViewportGetRectInput,
+  ViewportPositionAtInput,
+  ViewportPositionHit,
   ViewportHandle,
   ViewportRect,
   ViewportRectResult,
@@ -1658,6 +1661,23 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
       if (!startEl || !host.contains(startEl)) return [];
       return collectEntityHitsFromChain(startEl);
     },
+
+    getHost(): HTMLElement | null {
+      const editor = resolveHostEditor(superdoc);
+      return editor?.presentationEditor?.visibleHost ?? null;
+    },
+
+    positionAt(input: ViewportPositionAtInput): ViewportPositionHit | null {
+      if (!input || typeof input.x !== 'number' || typeof input.y !== 'number') return null;
+      const hostEditor = resolveHostEditor(superdoc);
+      const routedEditor = resolveRoutedEditor(superdoc);
+      return resolvePositionAt(
+        hostEditor as unknown as Parameters<typeof resolvePositionAt>[0],
+        routedEditor as unknown as Parameters<typeof resolvePositionAt>[1],
+        input.x,
+        input.y,
+      );
+    },
   };
 
   // ---- ui.selection ------------------------------------------------------

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

@@ -128,6 +128,8 @@ export type {
   ViewportEntityHit,
   ViewportGetRectInput,
   ViewportHandle,
+  ViewportPositionAtInput,
+  ViewportPositionHit,
   ViewportRect,
   ViewportRectResult,
 

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

@@ -0,0 +1,105 @@
+/**
+ * `ui.viewport.positionAt({ x, y })` helper. Resolves a viewport
+ * coordinate to a {@link SelectionPoint} / {@link SelectionTarget}
+ * pair on the routed editor's PM document. 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
+ * actions like "Paste here" / "Insert clause at this point" without
+ * dispatching against the user's previous selection.
+ */
+
+import type { Node as ProseMirrorNode } from 'prosemirror-model';
+import type { SelectionPoint, SelectionTarget } from '@superdoc/document-api';
+import type { Editor } from '../editors/v1/core/Editor.js';
+import { pmPositionToTextOffset } from '../editors/v1/document-api-adapters/helpers/text-offset-resolver.js';
+import type { ViewportPositionHit } from './types.js';
+
+interface HostEditor {
+  presentationEditor?: {
+    posAtCoords?(coords: { clientX: number; clientY: number }): { pos: number; inside: number } | null;
+    visibleHost?: HTMLElement;
+  } | null;
+}
+
+/**
+ * Resolve a viewport (x, y) coordinate to the caret position under
+ * that point. Returns `null` for points outside the painted host or
+ * when no editor is mounted.
+ *
+ * `hostEditor` is the controller's host editor (where the painted
+ * host and the coord-to-position helper live). `routedEditor` is the
+ * editor whose PM document the caret belongs to — for clicks inside a
+ * header/footer/footnote story while focus is in that surface, the
+ * routed editor is the story editor; otherwise it is the host.
+ */
+export function resolvePositionAt(
+  hostEditor: (Editor & HostEditor) | null,
+  routedEditor: Editor | null,
+  x: number,
+  y: number,
+): ViewportPositionHit | null {
+  if (!hostEditor || !routedEditor) return null;
+  const presentation = hostEditor.presentationEditor;
+  if (!presentation || typeof presentation.posAtCoords !== 'function') return null;
+
+  // Scope to this controller's painted host. `posAtCoords` itself is
+  // already painter-scoped (returns null for points outside the
+  // layout), but checking the host upfront also avoids running the
+  // coord lookup for clicks that obviously aren't ours, e.g. on a
+  // sidebar that happens to overlap the painted page.
+  const host = presentation.visibleHost;
+  if (host && typeof document !== 'undefined') {
+    const elAtPoint = document.elementFromPoint?.(x, y);
+    if (elAtPoint && !host.contains(elAtPoint)) return null;
+  }
+
+  let result: { pos: number; inside: number } | null = null;
+  try {
+    result = presentation.posAtCoords({ clientX: x, clientY: y });
+  } catch {
+    return null;
+  }
+  if (!result) return null;
+
+  const block = findContainingTextBlock(routedEditor.state?.doc as ProseMirrorNode | undefined, result.pos);
+  if (!block) return null;
+
+  const offset = pmPositionToTextOffset(block.node, block.pos, result.pos);
+  const point: SelectionPoint = { kind: 'text', blockId: block.blockId, offset };
+  const target: SelectionTarget = { kind: 'selection', start: point, end: point };
+  return { point, target };
+}
+
+interface BlockMatch {
+  node: ProseMirrorNode;
+  pos: number;
+  blockId: string;
+}
+
+/**
+ * Walk the doc to find the textblock that contains `pmPos`. Same
+ * shape `collectTextSegments` uses for selections, but specialized
+ * for a single point so we don't allocate a segments array.
+ */
+function findContainingTextBlock(doc: ProseMirrorNode | undefined, pmPos: number): BlockMatch | null {
+  if (!doc) return null;
+  let match: BlockMatch | null = null;
+  doc.descendants((node, pos) => {
+    if (match) return false;
+    if (!node.isTextblock) return true;
+    const blockStart = pos;
+    const blockEnd = pos + node.nodeSize;
+    if (pmPos < blockStart || pmPos > blockEnd) return false;
+    const blockId = readBlockId(node);
+    if (!blockId) return false;
+    match = { node, pos, blockId };
+    return false;
+  });
+  return match;
+}
+
+function readBlockId(node: ProseMirrorNode): string | null {
+  const id = (node.attrs as { id?: unknown })?.id;
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}

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

@@ -177,6 +177,12 @@ export interface SuperDocEditorLike {
      * from the wrong instance.
      */
     visibleHost?: HTMLElement;
+    /**
+     * Coordinate-to-position helper. Consumed by
+     * `ui.viewport.positionAt` to resolve a viewport `(x, y)` to a
+     * caret position in the editor's PM document.
+     */
+    posAtCoords?(coords: { clientX: number; clientY: number }): { pos: number; inside: number } | null;
   } | null;
 }
 
@@ -1574,6 +1580,77 @@ export interface ViewportHandle {
    * compatible.
    */
   entityAt(input: ViewportEntityAtInput): ViewportEntityHit[];
+  /**
+   * The painted-DOM host element for this controller's editor, or
+   * `null` when no editor is mounted (SSR, post-destroy, before
+   * `onReady` fires).
+   *
+   * Custom UI consumers reach for the host element to scope their
+   * own DOM listeners — `contextmenu`, hover tooltips, drag-and-drop
+   * — to events that originate inside the editor. Without this,
+   * consumers either listen on `document` and filter by a CSS class
+   * they control (fragile, breaks when the wrapper class is renamed)
+   * or pass the editor's container down through their own component
+   * tree (verbose).
+   *
+   * The returned element is the host SuperDoc paints into. The
+   * editor's hidden ProseMirror DOM is appended elsewhere and is not
+   * inside this host — events whose target is in the hidden PM DOM
+   * (most keyboard events after focus moves into the editor) won't
+   * pass `host.contains(target)` checks. For coordinate-based hit
+   * tests use {@link entityAt} or {@link positionAt} instead, both of
+   * which scope correctly across painted-DOM and hidden-DOM events.
+   */
+  getHost(): HTMLElement | null;
+  /**
+   * Resolve a viewport coordinate to a position in the editor's
+   * document, or `null` when the point is outside the painted host or
+   * no editor is mounted.
+   *
+   * The natural pair to {@link entityAt}: while `entityAt` answers
+   * "what entity is under this point?", `positionAt` answers "what
+   * caret position is under this point?". Right-click menus offering
+   * "Paste here", "Insert clause at this point", or "Add comment at
+   * this point" need this to dispatch their action against the click
+   * coordinate rather than the user's previous selection somewhere
+   * else in the document.
+   *
+   * Returns a {@link ViewportPositionHit} with both the resolved
+   * `point` (a `SelectionPoint` consumers can pass straight to
+   * `editor.doc.insert({ target })` and similar APIs) and the
+   * `target` (a `SelectionTarget` for selection-shaped operations).
+   * The two shapes are derived from the same underlying position,
+   * just packaged differently to match the doc-api method that's
+   * about to consume them.
+   */
+  positionAt(input: ViewportPositionAtInput): ViewportPositionHit | null;
+}
+
+/**
+ * Input shape for {@link ViewportHandle.positionAt}. Same coordinate
+ * space as `MouseEvent.clientX` / `clientY` and {@link ViewportRect}.
+ */
+export interface ViewportPositionAtInput {
+  x: number;
+  y: number;
+}
+
+/**
+ * Resolved caret position returned by {@link ViewportHandle.positionAt}.
+ *
+ * `point` is the {@link import('@superdoc/document-api').SelectionPoint}
+ * shape used by point-anchored doc-api operations (`editor.doc.insert(
+ * { target: { kind: 'selection', start: point, end: point } })` for a
+ * collapsed insert at the click site).
+ *
+ * `target` is the equivalent {@link import('@superdoc/document-api').SelectionTarget}
+ * — a collapsed selection at the click point — for operations that
+ * accept a target shape directly. Same underlying position, two
+ * packagings; consumers pick the shape their downstream call needs.
+ */
+export interface ViewportPositionHit {
+  point: import('@superdoc/document-api').SelectionPoint;
+  target: import('@superdoc/document-api').SelectionTarget;
 }
 
 /**

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

@@ -362,3 +362,47 @@ describe('ui.viewport.entityAt — host scoping', () => {
     ui.destroy();
   });
 });
+
+describe('ui.viewport.getHost', () => {
+  it('returns the painted host element when one is mounted', () => {
+    const { superdoc } = makeStubs();
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    (
+      superdoc.activeEditor as unknown as { presentationEditor: { visibleHost: HTMLElement } }
+    ).presentationEditor.visibleHost = host;
+
+    const ui = createSuperDocUI({ superdoc });
+    expect(ui.viewport.getHost()).toBe(host);
+
+    host.remove();
+    ui.destroy();
+  });
+
+  it('returns null when no editor is mounted', () => {
+    const { superdoc } = makeStubs();
+    (superdoc.activeEditor as unknown as { presentationEditor: unknown }).presentationEditor = undefined;
+    const ui = createSuperDocUI({ superdoc });
+    expect(ui.viewport.getHost()).toBeNull();
+    ui.destroy();
+  });
+});
+
+describe('ui.viewport.positionAt — input validation', () => {
+  it('returns null for invalid input (missing or non-numeric coordinates)', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    expect(ui.viewport.positionAt({} as never)).toBeNull();
+    expect(ui.viewport.positionAt({ x: 'a', y: 0 } as never)).toBeNull();
+
+    ui.destroy();
+  });
+
+  it('returns null when posAtCoords is missing on the presentation stub', () => {
+    const { superdoc } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+    expect(ui.viewport.positionAt({ x: 10, y: 10 })).toBeNull();
+    ui.destroy();
+  });
+});

packages/superdoc/src/ui.d.ts

@@ -59,6 +59,8 @@ export {
   type ViewportEntityHit,
   type ViewportGetRectInput,
   type ViewportHandle,
+  type ViewportPositionAtInput,
+  type ViewportPositionHit,
   type ViewportRect,
   type ViewportRectResult,
 } from '@superdoc/super-editor/ui';