@plannotator/ui 0.28.0 → 0.29.0

package/utils/vimNavigation.ts

@@ -0,0 +1,417 @@
+import { getAnnotatableTextNodes } from './domSelection';
+
+/** A durable cursor location measured within one rendered Markdown block. */
+export interface VimTextPosition {
+  readonly blockId: string;
+  readonly textOffset: number;
+  /**
+   * Resolve an offset shared by adjacent text nodes toward the next or previous
+   * node. Omitted positions preserve the historical backward affinity.
+   */
+  readonly affinity?: 'forward' | 'backward';
+}
+
+/** Text movement commands understood by the Markdown Vim adapter. */
+export type VimTextMotion =
+  | 'left'
+  | 'right'
+  | 'word-forward'
+  | 'word-backward'
+  | 'word-end'
+  | 'line-start'
+  | 'line-end'
+  | 'block-backward'
+  | 'block-forward'
+  | 'document-start'
+  | 'document-end';
+
+/** Block-level keyboard navigation with no browser text selection. */
+export interface VimBlockState {
+  readonly phase: 'block';
+  readonly targetKey: string;
+}
+
+/** A refined semantic child such as inline code, a table row, or a cell. */
+export interface VimInlineState {
+  readonly phase: 'inline';
+  readonly targetKey: string;
+}
+
+/** A collapsed text cursor inside the current semantic target. */
+export interface VimTextState {
+  readonly phase: 'text';
+  readonly targetKey: string;
+  readonly cursor: VimTextPosition;
+}
+
+/** A characterwise browser selection anchored inside rendered text. */
+export interface VimVisualState {
+  readonly phase: 'visual';
+  readonly targetKey: string;
+  readonly cursor: VimTextPosition;
+  readonly anchor: VimTextPosition;
+}
+
+/** A whole-block selection extending through block-navigation order. */
+export interface VimVisualBlockState {
+  readonly phase: 'visual-block';
+  readonly targetKey: string;
+  readonly anchorTargetKey: string;
+}
+
+/** Any Vim state that can be restored after an annotation UI closes. */
+export type VimRestorableState =
+  | VimBlockState
+  | VimInlineState
+  | VimTextState
+  | VimVisualState
+  | VimVisualBlockState;
+
+/** Annotation UI owns the keyboard while this state is active. */
+export interface VimActionState {
+  readonly phase: 'action';
+  readonly returnTo: VimRestorableState;
+}
+
+/**
+ * Complete Vim navigation state.
+ *
+ * The discriminated union prevents semantic focus, text cursors, and visual
+ * anchors from existing in contradictory combinations.
+ */
+export type VimSelectionState =
+  | { readonly phase: 'inactive' }
+  | VimRestorableState
+  | VimActionState;
+
+/** Return a fresh state with no semantic or text target. */
+export function createInitialVimSelectionState(): { readonly phase: 'inactive' } {
+  return { phase: 'inactive' };
+}
+
+function getBlockElements(container: HTMLElement): HTMLElement[] {
+  const seen = new Set<string>();
+  const result: HTMLElement[] = [];
+
+  container.querySelectorAll<HTMLElement>('[data-block-id]').forEach((element) => {
+    const blockId = element.dataset.blockId;
+    if (!blockId || seen.has(blockId) || element.tagName === 'HR') return;
+    seen.add(blockId);
+    result.push(element);
+  });
+
+  return result;
+}
+
+function getBlockText(block: HTMLElement): string {
+  return getAnnotatableTextNodes(block).map((node) => node.data).join('');
+}
+
+function getPositionAtBlockBoundary(
+  block: HTMLElement,
+  boundary: 'start' | 'end',
+): VimTextPosition | null {
+  const blockId = block.dataset.blockId;
+  if (!blockId) return null;
+  const textLength = getBlockText(block).length;
+  if (textLength === 0) return null;
+  return {
+    blockId,
+    textOffset: boundary === 'start' ? 0 : textLength,
+  };
+}
+
+function findBlock(container: HTMLElement, blockId: string): HTMLElement | null {
+  for (const element of getBlockElements(container)) {
+    if (element.dataset.blockId === blockId) return element;
+  }
+  return null;
+}
+
+function getViewportCenterY(
+  container: HTMLElement,
+  scrollViewport?: HTMLElement | null,
+): number {
+  const rect = (scrollViewport ?? container).getBoundingClientRect();
+  return rect.top + rect.height / 2;
+}
+
+/** Pick the first text cursor nearest the visible center of the document. */
+export function findInitialTextPosition(
+  container: HTMLElement,
+  scrollViewport?: HTMLElement | null,
+): VimTextPosition | null {
+  const centerY = getViewportCenterY(container, scrollViewport);
+  const candidates = getBlockElements(container)
+    .map((block) => ({ block, position: getPositionAtBlockBoundary(block, 'start') }))
+    .filter((candidate): candidate is { block: HTMLElement; position: VimTextPosition } =>
+      candidate.position !== null,
+    );
+
+  candidates.sort((left, right) => {
+    const leftRect = left.block.getBoundingClientRect();
+    const rightRect = right.block.getBoundingClientRect();
+    const leftDistance = Math.abs((leftRect.top + leftRect.bottom) / 2 - centerY);
+    const rightDistance = Math.abs((rightRect.top + rightRect.bottom) / 2 - centerY);
+    return leftDistance - rightDistance;
+  });
+
+  return candidates[0]?.position ?? null;
+}
+
+/** Resolve a logical Vim position into a live text-node DOM point. */
+export function resolveTextPosition(
+  container: HTMLElement,
+  position: VimTextPosition,
+): { node: Text; offset: number } | null {
+  const block = findBlock(container, position.blockId);
+  if (!block) return null;
+
+  const nodes = getAnnotatableTextNodes(block);
+  if (nodes.length === 0) return null;
+
+  let remaining = Math.max(0, position.textOffset);
+  for (const [index, node] of nodes.entries()) {
+    if (remaining < node.length) {
+      return { node, offset: remaining };
+    }
+    if (remaining === node.length) {
+      if (position.affinity === 'forward' && index < nodes.length - 1) {
+        remaining = 0;
+        continue;
+      }
+      return { node, offset: remaining };
+    }
+    remaining -= node.length;
+  }
+
+  const lastNode = nodes[nodes.length - 1];
+  return { node: lastNode, offset: lastNode.length };
+}
+
+function normalizeDomPoint(
+  node: Node,
+  offset: number,
+): { node: Text; offset: number } | null {
+  if (node instanceof Text) {
+    return { node, offset: Math.max(0, Math.min(offset, node.length)) };
+  }
+  if (!(node instanceof Element)) return null;
+
+  // A DOM point whose offset equals `childNodes.length` sits after the final
+  // child. Treating it as the start of that child moves a line/document-end
+  // cursor backward when Selection.modify() returns an element endpoint.
+  const childAtOffset = offset < node.childNodes.length
+    ? node.childNodes[Math.max(0, offset)]
+    : undefined;
+  if (childAtOffset) {
+    const nextWalker = document.createTreeWalker(childAtOffset, NodeFilter.SHOW_TEXT);
+    const nextCandidate = childAtOffset instanceof Text
+      ? childAtOffset
+      : nextWalker.nextNode();
+    const nextText = nextCandidate instanceof Text ? nextCandidate : null;
+    if (nextText) return { node: nextText, offset: 0 };
+  }
+
+  const previousChild = node.childNodes[Math.max(0, offset - 1)];
+  if (!previousChild) return null;
+  const previousTexts = previousChild instanceof Text
+    ? [previousChild]
+    : previousChild instanceof Element
+      ? getAnnotatableTextNodes(previousChild)
+      : [];
+  const previousText = previousTexts[previousTexts.length - 1];
+  return previousText ? { node: previousText, offset: previousText.length } : null;
+}
+
+/** Serialize a live DOM selection point back into a durable block-relative position. */
+export function serializeTextPosition(
+  container: HTMLElement,
+  node: Node,
+  offset: number,
+): VimTextPosition | null {
+  const point = normalizeDomPoint(node, offset);
+  if (!point) return null;
+
+  const block = point.node.parentElement?.closest<HTMLElement>('[data-block-id]');
+  const blockId = block?.dataset.blockId;
+  if (!block || !blockId || !container.contains(block)) return null;
+
+  let textOffset = 0;
+  for (const textNode of getAnnotatableTextNodes(block)) {
+    if (textNode === point.node) {
+      return {
+        blockId,
+        textOffset: textOffset + Math.max(0, Math.min(point.offset, textNode.length)),
+      };
+    }
+    textOffset += textNode.length;
+  }
+  return null;
+}
+
+function compareTextPositions(
+  container: HTMLElement,
+  left: VimTextPosition,
+  right: VimTextPosition,
+): number {
+  if (left.blockId === right.blockId) return left.textOffset - right.textOffset;
+  const blocks = getBlockElements(container);
+  const leftIndex = blocks.findIndex((block) => block.dataset.blockId === left.blockId);
+  const rightIndex = blocks.findIndex((block) => block.dataset.blockId === right.blockId);
+  return leftIndex - rightIndex;
+}
+
+/** Build a live range between two logical positions regardless of selection direction. */
+export function createRangeBetweenTextPositions(
+  container: HTMLElement,
+  anchor: VimTextPosition,
+  cursor: VimTextPosition,
+): Range | null {
+  const anchorPoint = resolveTextPosition(container, anchor);
+  const cursorPoint = resolveTextPosition(container, cursor);
+  if (!anchorPoint || !cursorPoint) return null;
+
+  const anchorFirst = compareTextPositions(container, anchor, cursor) <= 0;
+  const start = anchorFirst ? anchorPoint : cursorPoint;
+  const end = anchorFirst ? cursorPoint : anchorPoint;
+  const range = document.createRange();
+  range.setStart(start.node, start.offset);
+  range.setEnd(end.node, end.offset);
+  return range;
+}
+
+/**
+ * Return durable text bounds for a semantic target element.
+ *
+ * Bounds may span multiple Markdown blocks for group targets.
+ */
+export function getTextElementBounds(
+  container: HTMLElement,
+  element: HTMLElement,
+): { start: VimTextPosition; end: VimTextPosition } | null {
+  const nodes = getAnnotatableTextNodes(element);
+  const first = nodes[0];
+  const last = nodes.at(-1);
+  if (!first || !last) return null;
+  const start = serializeTextPosition(container, first, 0);
+  const end = serializeTextPosition(container, last, last.length);
+  return start && end
+    ? {
+        start: { ...start, affinity: 'forward' },
+        end: { ...end, affinity: 'backward' },
+      }
+    : null;
+}
+
+/** Show a logical cursor or visual range through the browser Selection API. */
+export function applyNativeTextSelection(
+  container: HTMLElement,
+  cursor: VimTextPosition,
+  anchor: VimTextPosition | null,
+): Selection | null {
+  const cursorPoint = resolveTextPosition(container, cursor);
+  if (!cursorPoint) return null;
+
+  const selection = window.getSelection();
+  selection?.removeAllRanges();
+  if (!selection) return null;
+
+  if (!anchor) {
+    const range = document.createRange();
+    range.setStart(cursorPoint.node, cursorPoint.offset);
+    range.collapse(true);
+    selection.addRange(range);
+    return selection;
+  }
+
+  const anchorPoint = resolveTextPosition(container, anchor);
+  if (!anchorPoint) return null;
+  selection.setBaseAndExtent(
+    anchorPoint.node,
+    anchorPoint.offset,
+    cursorPoint.node,
+    cursorPoint.offset,
+  );
+  return selection;
+}
+
+function segmentBoundaries(text: string, granularity: 'grapheme' | 'word'): number[] {
+  const segmenter = new Intl.Segmenter(undefined, { granularity });
+  return Array.from(segmenter.segment(text), (segment) => segment.index);
+}
+
+function moveWithinBlock(
+  text: string,
+  offset: number,
+  motion: VimTextMotion,
+): number | null {
+  const safeOffset = Math.max(0, Math.min(offset, text.length));
+
+  if (motion === 'left' || motion === 'right') {
+    const boundaries = [...segmentBoundaries(text, 'grapheme'), text.length];
+    if (motion === 'left') {
+      return boundaries.filter((boundary) => boundary < safeOffset).at(-1) ?? null;
+    }
+    return boundaries.find((boundary) => boundary > safeOffset) ?? null;
+  }
+
+  if (
+    motion === 'word-forward'
+    || motion === 'word-backward'
+    || motion === 'word-end'
+  ) {
+    const segmenter = new Intl.Segmenter(undefined, { granularity: 'word' });
+    const words = Array.from(segmenter.segment(text)).filter((segment) => segment.isWordLike);
+    if (motion === 'word-backward') {
+      return words.filter((word) => word.index < safeOffset).at(-1)?.index ?? null;
+    }
+    if (motion === 'word-end') {
+      const word = words.find((candidate) => candidate.index + candidate.segment.length > safeOffset);
+      return word ? word.index + word.segment.length : null;
+    }
+    return words.find((word) => word.index > safeOffset)?.index ?? null;
+  }
+
+  if (motion === 'line-start') return 0;
+  if (motion === 'line-end') return text.length;
+  return null;
+}
+
+/** Move a logical text cursor without retaining stale DOM-node references. */
+export function moveTextPosition(
+  container: HTMLElement,
+  position: VimTextPosition,
+  motion: VimTextMotion,
+  scrollViewport?: HTMLElement | null,
+): VimTextPosition {
+  const currentBlock = findBlock(container, position.blockId);
+  if (!currentBlock) return findInitialTextPosition(container, scrollViewport) ?? position;
+  const currentText = getBlockText(currentBlock);
+  const nextOffset = moveWithinBlock(currentText, position.textOffset, motion);
+  if (nextOffset !== null) {
+    return { blockId: position.blockId, textOffset: nextOffset };
+  }
+
+  const blocks = getBlockElements(container).filter((block) => getBlockText(block).length > 0);
+  if (blocks.length === 0) return position;
+  if (motion === 'document-start') {
+    return getPositionAtBlockBoundary(blocks[0], 'start') ?? position;
+  }
+  if (motion === 'document-end') {
+    return getPositionAtBlockBoundary(blocks[blocks.length - 1], 'end') ?? position;
+  }
+
+  const blockIndex = blocks.indexOf(currentBlock);
+  if (blockIndex < 0) return findInitialTextPosition(container, scrollViewport) ?? position;
+  if (motion === 'block-backward' || motion === 'block-forward') {
+    const delta = motion === 'block-backward' ? -1 : 1;
+    const nextBlock = blocks[Math.max(0, Math.min(blocks.length - 1, blockIndex + delta))];
+    return getPositionAtBlockBoundary(nextBlock, 'start') ?? position;
+  }
+
+  const direction = motion === 'left' || motion === 'word-backward' ? -1 : 1;
+  const adjacent = blocks[blockIndex + direction];
+  if (!adjacent) return position;
+  return getPositionAtBlockBoundary(adjacent, direction < 0 ? 'end' : 'start') ?? position;
+}

package/utils/vimReticle.ts

@@ -0,0 +1,88 @@
+import type { SemanticTarget } from './blockTargeting';
+import type { VimRestorableState } from './vimNavigation';
+import type { VimHudCommand } from './vimHud';
+
+const CURSOR_DESCRIPTORS: Partial<
+  Record<VimHudCommand['actionId'], string>
+> = {
+  moveDown: 'NEXT LINE',
+  moveUp: 'PREVIOUS LINE',
+  lineStart: 'LINE START',
+  lineEnd: 'LINE END',
+  wordForward: 'NEXT WORD',
+  wordBackward: 'PREVIOUS WORD',
+  wordEnd: 'WORD END',
+  previousTextBlock: 'PREVIOUS TEXT',
+  nextTextBlock: 'NEXT TEXT',
+  documentStart: 'DOCUMENT START',
+  documentEnd: 'DOCUMENT END',
+};
+
+const VISUAL_DESCRIPTORS: Partial<
+  Record<VimHudCommand['actionId'], string>
+> = {
+  visual: 'RANGE START',
+  visualBlock: 'BLOCK RANGE',
+  wordForward: 'NEXT WORD',
+  wordBackward: 'PREVIOUS WORD',
+  wordEnd: 'EXACT TOKEN',
+  lineStart: 'TO LINE START',
+  lineEnd: 'TO LINE END',
+  moveDown: 'NEXT LINE',
+  moveUp: 'PREVIOUS LINE',
+  previousTextBlock: 'PREVIOUS BLOCK',
+  nextTextBlock: 'NEXT BLOCK',
+  swapSelectionEnds: 'SWAPPED ENDS',
+};
+
+type VimReticleSemanticTarget = Pick<SemanticTarget, 'kind' | 'label'>;
+
+function semanticDescriptor(target: VimReticleSemanticTarget): string {
+  switch (target.kind) {
+    case 'code':
+      return 'CODE';
+    case 'math':
+      return 'FORMULA';
+    case 'table':
+      return 'TABLE';
+    case 'row':
+      return 'ROW';
+    case 'cell':
+      return 'CELL';
+    case 'group':
+      return target.label.toUpperCase();
+    case 'inline':
+    case 'block':
+      return (target.label.split(':')[0] || target.kind).toUpperCase();
+  }
+}
+
+function cursorDescriptor(command: VimHudCommand | null): string {
+  if (!command) return 'TEXT';
+  if (command.actionId === 'moveOut' || command.actionId === 'refine') {
+    const characterMotion = command.context === 'text' || command.context === 'visual';
+    if (command.actionId === 'moveOut') {
+      return characterMotion ? 'PREVIOUS CHARACTER' : 'TEXT';
+    }
+    return characterMotion ? 'NEXT CHARACTER' : 'INLINE TEXT';
+  }
+  return CURSOR_DESCRIPTORS[command.actionId] ?? 'TEXT';
+}
+
+/** Build the concise target label shared with the approved Vim demo. */
+export function getVimReticleLabel(
+  state: VimRestorableState,
+  target: VimReticleSemanticTarget | null,
+  command: VimHudCommand | null,
+): string {
+  if (state.phase === 'text') return `CURSOR · ${cursorDescriptor(command)}`;
+  if (state.phase === 'visual') {
+    return `VISUAL · ${
+      command ? VISUAL_DESCRIPTORS[command.actionId] ?? 'RANGE' : 'RANGE'
+    }`;
+  }
+  if (state.phase === 'visual-block') return 'VISUAL · BLOCK RANGE';
+  return `${state.phase === 'inline' ? 'INLINE' : 'BLOCK'} · ${
+    target ? semanticDescriptor(target) : 'TARGET'
+  }`;
+}

package/utils/vimScroll.ts

@@ -0,0 +1,162 @@
+/**
+ * Keep the Vim cursor clear of the HUD bands that hug the viewport edges.
+ *
+ * `Element.scrollIntoView({ block: 'nearest' })` parks a target flush against
+ * the nearest viewport edge — exactly where the sticky action bar (top) and the
+ * key HUD / status pill (bottom) float. Keyboard motion then lands the caret
+ * behind an overlay, while a mouse wheel (which the browser lets overshoot)
+ * keeps the same text nearer the centre. These helpers reproduce that mouse
+ * feel: a target inside the safe band never scrolls, and one that strays into a
+ * HUD band is revealed with a margin instead of being pinned to the edge.
+ */
+
+/** A viewport's vertical geometry, relative to the page. */
+export interface VimScrollViewportRect {
+  readonly top: number;
+  readonly height: number;
+}
+
+/** A target's vertical extent, relative to the page. */
+export interface VimScrollTargetRect {
+  readonly top: number;
+  readonly bottom: number;
+}
+
+/** The occluded strips to keep the caret out of, measured from each edge. */
+export interface VimScrollBand {
+  readonly topMargin: number;
+  readonly bottomMargin: number;
+}
+
+/** Fraction of the viewport height reserved as a HUD band at each edge. */
+export const VIM_SCROLL_MARGIN_RATIO = 0.2;
+/** Lower clamp so short viewports still leave a usable margin. */
+export const VIM_SCROLL_MARGIN_MIN = 24;
+/** Upper clamp so tall viewports do not reserve most of the screen. */
+export const VIM_SCROLL_MARGIN_MAX = 160;
+
+/**
+ * How far to move `scrollTop` so `target` clears the HUD bands.
+ *
+ * Returns a signed delta (negative scrolls up, positive scrolls down) or `0`
+ * when the target already sits inside the safe band. A target taller than the
+ * band is aligned to its top edge — reading order wins, so the start of the
+ * block is never pushed above the top margin to chase its bottom.
+ */
+export function computeVimScrollDelta(
+  viewport: VimScrollViewportRect,
+  target: VimScrollTargetRect,
+  band: VimScrollBand,
+): number {
+  const relativeTop = target.top - viewport.top;
+  const relativeBottom = target.bottom - viewport.top;
+  const safeTop = band.topMargin;
+  const safeBottom = viewport.height - band.bottomMargin;
+
+  // Behind the top HUD → scroll up just enough to reach the top margin.
+  if (relativeTop < safeTop) return relativeTop - safeTop;
+
+  // Behind the bottom HUD → scroll down, but never past the point where the
+  // target's top would slip under the top margin.
+  if (relativeBottom > safeBottom) {
+    const bottomDelta = relativeBottom - safeBottom;
+    const topRoom = relativeTop - safeTop;
+    return Math.min(bottomDelta, Math.max(0, topRoom));
+  }
+
+  return 0;
+}
+
+/** Resolve the ratio-based HUD margin, clamped for very short or tall viewports. */
+export function resolveVimScrollMargin(viewportHeight: number): number {
+  return Math.min(
+    Math.max(viewportHeight * VIM_SCROLL_MARGIN_RATIO, VIM_SCROLL_MARGIN_MIN),
+    VIM_SCROLL_MARGIN_MAX,
+  );
+}
+
+/**
+ * Top edge of the lowest floating Vim HUD, or `undefined` when none is shown.
+ *
+ * The key HUD and the mode badge are portaled to `document.body`, outside the
+ * scroll viewport's subtree, so the query is necessarily document-wide. It is
+ * still scoped to `element.ownerDocument` (never the global `document`) so a
+ * host mounted inside another document measures its own HUD, and because both
+ * widgets are fixed-position singletons, a host mounting two viewers in one
+ * document gets the same band geometry from either instance.
+ *
+ * The expanded key HUD is deliberately skipped: it is a modal state that can
+ * stand taller than the viewport, so no band could clear it — scrolling keeps
+ * the ratio margin until the user collapses it.
+ */
+function vimHudBandTop(element: HTMLElement): number | undefined {
+  const doc = element.ownerDocument;
+  const keyHud = doc.querySelector<HTMLElement>('[data-vim-key-hud]');
+  const badge = doc.querySelector<HTMLElement>('[data-vim-mode-badge]');
+  const tops: number[] = [];
+  if (keyHud && keyHud.getAttribute('data-expanded') !== 'true') {
+    const rect = keyHud.getBoundingClientRect();
+    if (rect.height > 0) tops.push(rect.top);
+  }
+  if (badge) {
+    const rect = badge.getBoundingClientRect();
+    if (rect.height > 0) tops.push(rect.top);
+  }
+  return tops.length > 0 ? Math.min(...tops) : undefined;
+}
+
+/**
+ * Scroll `element` into view while keeping it clear of the Vim HUD bands.
+ *
+ * `scrollViewport` is the element that actually scrolls — the caller passes the
+ * value it already holds from ScrollViewportContext (the same node the reticle
+ * measures against), because the native-scroll host carries no attribute that
+ * would rediscover it. When it is absent the helper falls back to the
+ * historical `scrollIntoView({ block: 'nearest' })`, so behaviour never
+ * regresses.
+ *
+ * Both bands are measured from live geometry rather than guessed constants:
+ * the top band clears the sticky action bar when present, and the bottom band
+ * clears the floating key HUD / mode pill, so the caret is never parked behind
+ * either overlay — and the default pill configuration no longer reserves the
+ * full ratio band for a 25px widget.
+ */
+export function scrollVimTargetIntoView(
+  element: HTMLElement,
+  scrollViewport?: HTMLElement | null,
+): void {
+  const viewport = scrollViewport ?? null;
+  if (!viewport) {
+    element.scrollIntoView({ block: 'nearest' });
+    return;
+  }
+
+  const viewportRect = viewport.getBoundingClientRect();
+  const targetRect = element.getBoundingClientRect();
+  if (targetRect.height === 0 && targetRect.width === 0) return;
+
+  const margin = resolveVimScrollMargin(viewport.clientHeight);
+  const stickyBottom = viewport
+    .querySelector<HTMLElement>('[data-sticky-actions]')
+    ?.getBoundingClientRect().bottom;
+  const topMargin = stickyBottom !== undefined
+    ? Math.max(margin, stickyBottom - viewportRect.top + 8)
+    : margin;
+
+  // Mirror of the top band: keep the caret above the floating HUD by the same
+  // 8px gap. The HUD rect wins over the ratio band whenever it is larger (the
+  // key HUD needs ~238px, well past the 160px clamp) and is allowed to shrink
+  // past it when only the small mode pill floats (floor: the minimum margin).
+  const hudTop = vimHudBandTop(element);
+  const bottomMargin = hudTop !== undefined
+    ? Math.max(VIM_SCROLL_MARGIN_MIN, viewportRect.bottom - hudTop + 8)
+    : margin;
+
+  const delta = computeVimScrollDelta(
+    { top: viewportRect.top, height: viewport.clientHeight },
+    { top: targetRect.top, bottom: targetRect.bottom },
+    { topMargin, bottomMargin },
+  );
+  if (delta === 0) return;
+  viewport.scrollTop += delta;
+}