Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
32.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file hitArea.ts
 * @input A target's rect and its neighbours' rects (or, for a live control,
 *   the element and the page around it)
 * @output The touch hit area: how far a target may grow toward 44 px on each
 *   side without taking a tap that is nearer a neighbour. `clampedHitInsets`
 *   and `resolveHitTarget` answer from rects. `watchHitArea` keeps a control's
 *   insets live where the primary pointer is coarse. `groupGrowth` sizes a
 *   group's box from its edge members, and shrinks a side the members do not
 *   reach. `INTERACTIVE_SELECTOR` names what a touch can land on
 * @position Core-internal utility, not exported from `@astryxdesign/core/utils`.
 *   Groups that measure their actions at press start pass `resolveHitTarget`;
 *   a standalone control writes `watchHitArea`'s insets to an invisible
 *   coarse-only hit layer
 *
 */

// A finger needs a 44 × 44 px target, but a control may not grow on a phone,
// and its hit area must never take a neighbor's taps. Each side grows toward
// the minimum and stops at half the gap to the nearest neighbor on that side,
// so a tap always goes to the nearer target. CSS cannot see the neighbors, so a
// live control measures: only under a coarse primary pointer (AST-094), only on
// screen, and in one read pass per frame within a 4 ms budget. Until the first
// pass the insets are 0, so first paint never overlaps anything.
// The insets are lengths in the control's own box, so a pass measures in its
// layout px. A layer that opens from a smaller scale then keeps the insets of
// the size it settles at.

import {
  flushMutations,
  observeContent,
  observeMutations,
} from './sharedMutationObserver';

/** A rect in client pixels. */
export interface HitRect {
  readonly left: number;
  readonly top: number;
  readonly right: number;
  readonly bottom: number;
}

/** How far a hit area extends past its target on each side, px. */
export interface HitInsets {
  readonly top: number;
  readonly right: number;
  readonly bottom: number;
  readonly left: number;
}

/** The smallest touch target, px (Apple's 44 pt). */
export const MIN_TOUCH_TARGET = 44;

/** No growth: the hit area is the target. */
export const NO_HIT_INSETS: HitInsets = {top: 0, right: 0, bottom: 0, left: 0};

/**
 * The custom properties `writeHitInsets` sets, in px, for a coarse-only hit
 * layer to read (`inset: calc(var(--astryx-hit-inset-top, 0px) * -1) ...`).
 */
export const HIT_INSET_PROPERTIES = {
  top: '--astryx-hit-inset-top',
  right: '--astryx-hit-inset-right',
  bottom: '--astryx-hit-inset-bottom',
  left: '--astryx-hit-inset-left',
} as const;

/**
 * The gap between two rects along each axis: positive where they are apart on
 * that axis, negative where their projections overlap.
 */
function gaps(a: HitRect, b: HitRect): {x: number; y: number} {
  return {
    x: Math.max(b.left - a.right, a.left - b.right),
    y: Math.max(b.top - a.bottom, a.top - b.bottom),
  };
}

function grown(rect: HitRect, insets: HitInsets): HitRect {
  return {
    left: rect.left - insets.left,
    top: rect.top - insets.top,
    right: rect.right + insets.right,
    bottom: rect.bottom + insets.bottom,
  };
}

function intersects(a: HitRect, b: HitRect): boolean {
  return (
    a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom
  );
}

/** How far `rect` grows toward `minSize` on each axis, centered, unclamped. */
function growth(rect: HitRect, minSize: number): HitInsets {
  const x = Math.max(0, (minSize - (rect.right - rect.left)) / 2);
  const y = Math.max(0, (minSize - (rect.bottom - rect.top)) / 2);
  return {top: y, right: x, bottom: y, left: x};
}

/**
 * How far a group's box grows on each side before any neighbour stops it: as
 * far as its members on that edge grow toward `minSize`. So an end member's
 * target reaches past the group, as a lone control's would. A side that
 * reaches past its edge member shrinks to that member's grown edge, a
 * negative growth. So a box wider than its members covers only their targets.
 */
export function groupGrowth(
  group: HitRect,
  members: ReadonlyArray<HitRect>,
  minSize: number = MIN_TOUCH_TARGET,
): HitInsets {
  if (members.length === 0) {
    return NO_HIT_INSETS;
  }
  const insets = {
    top: -Infinity,
    right: -Infinity,
    bottom: -Infinity,
    left: -Infinity,
  };
  for (const member of members) {
    const own = growth(member, minSize);
    insets.top = Math.max(insets.top, own.top - (member.top - group.top));
    insets.right = Math.max(
      insets.right,
      own.right - (group.right - member.right),
    );
    insets.bottom = Math.max(
      insets.bottom,
      own.bottom - (group.bottom - member.bottom),
    );
    insets.left = Math.max(insets.left, own.left - (member.left - group.left));
  }
  return insets;
}

/**
 * How far `target` may grow on each side: toward `minSize` on each axis,
 * centered, and on each side no further than half the gap to a neighbour.
 * A neighbour counts when either one, at full growth toward `minSize`, would
 * reach into the other's half of the gap, or their full areas would meet; it
 * stops the side facing it, or,
 * for a neighbour apart on both axes (diagonal), the side with the larger gap.
 * `full` replaces the centered growth, as `groupGrowth` gives a group's box.
 * That decision rests on the two rects alone, so the neighbour decides the
 * same about this target and the two areas never overlap. A neighbour
 * overlapping the target (an ancestor, an overlay) is not beside it and stops
 * nothing.
 */
export function clampedHitInsets(
  target: HitRect,
  neighbours: ReadonlyArray<HitRect>,
  minSize: number = MIN_TOUCH_TARGET,
  full: HitInsets = growth(target, minSize),
): HitInsets {
  if (
    full.top === 0 &&
    full.right === 0 &&
    full.bottom === 0 &&
    full.left === 0
  ) {
    return NO_HIT_INSETS;
  }
  const insets = {...full};
  for (const rect of neighbours) {
    const gap = gaps(target, rect);
    if (gap.x < 0 && gap.y < 0) {
      continue;
    }
    // Each one's half of the gap: a tap there is nearer that one.
    const half = {
      top: Math.max(0, gap.y) / 2,
      right: Math.max(0, gap.x) / 2,
      bottom: Math.max(0, gap.y) / 2,
      left: Math.max(0, gap.x) / 2,
    };
    // Either one, at full growth, would reach into the other's half, or
    // their full areas would meet (a wide and a tall target, diagonally).
    const reach = grown(target, full);
    const neighbourReach = grown(rect, growth(rect, minSize));
    const crosses =
      intersects(reach, grown(rect, half)) ||
      intersects(neighbourReach, grown(target, half)) ||
      intersects(reach, neighbourReach);
    if (!crosses) {
      continue;
    }
    if (gap.x >= gap.y) {
      if (rect.left >= target.right) {
        insets.right = Math.min(insets.right, half.right);
      } else {
        insets.left = Math.min(insets.left, half.left);
      }
    } else {
      if (rect.top >= target.bottom) {
        insets.bottom = Math.min(insets.bottom, half.bottom);
      } else {
        insets.top = Math.min(insets.top, half.top);
      }
    }
  }
  return insets;
}

function contains(rect: HitRect, x: number, y: number): boolean {
  return x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom;
}

function distanceTo(rect: HitRect, x: number, y: number): number {
  const dx = Math.max(rect.left - x, 0, x - rect.right);
  const dy = Math.max(rect.top - y, 0, y - rect.bottom);
  return Math.hypot(dx, dy);
}

/**
 * Which of `rects` a touch at (x, y) is for: the nearest target (inside two
 * overlapping targets, the one whose center is nearer), when the touch is
 * within that target's growth toward `minSize`; -1 otherwise. Being nearest,
 * it is on that target's side of every midpoint, corners included. For a
 * group that measures its actions at press start.
 */
export function resolveHitTarget(
  x: number,
  y: number,
  rects: ReadonlyArray<HitRect>,
  minSize: number = MIN_TOUCH_TARGET,
): number {
  let nearest = -1;
  let nearestDistance = Infinity;
  rects.forEach((rect, index) => {
    const distance =
      distanceTo(rect, x, y) * 1e6 +
      Math.hypot(
        x - (rect.left + rect.right) / 2,
        y - (rect.top + rect.bottom) / 2,
      );
    if (distance < nearestDistance) {
      nearest = index;
      nearestDistance = distance;
    }
  });
  if (nearest === -1) {
    return -1;
  }
  const rect = rects[nearest];
  return contains(grown(rect, growth(rect, minSize)), x, y) ? nearest : -1;
}

/** Sets `HIT_INSET_PROPERTIES` on `element`. */
export function writeHitInsets(element: HTMLElement, insets: HitInsets): void {
  for (const side of ['top', 'right', 'bottom', 'left'] as const) {
    element.style.setProperty(HIT_INSET_PROPERTIES[side], `${insets[side]}px`);
  }
}

// --- Live controls -----------------------------------------------------------

/** What a touch can land on: the neighbours a hit area must not take from. */
export const INTERACTIVE_SELECTOR = [
  'a[href]',
  'area[href]',
  'button',
  'input:not([type="hidden"])',
  'select',
  'textarea',
  'summary',
  'label[for]',
  '[contenteditable=""]',
  '[contenteditable="true"]',
  '[role="button"]',
  '[role="link"]',
  '[role="checkbox"]',
  '[role="radio"]',
  '[role="switch"]',
  '[role="tab"]',
  '[role="menuitem"]',
  '[role="menuitemcheckbox"]',
  '[role="menuitemradio"]',
  '[role="treeitem"]',
  '[role="combobox"]',
  '[role="textbox"]',
  '[role="searchbox"]',
  '[role="spinbutton"]',
  '[role="option"]',
  '[role="slider"]',
  '[tabindex]:not([tabindex="-1"])',
].join(',');

const TOUCH_QUERY = '(pointer: coarse)';

/**
 * How long one frame's pass may spend on controls, ms, after its one read of
 * the page: a page appearing with hundreds of controls spreads over a few
 * frames instead of one long task.
 */
const FRAME_BUDGET_MS = 4;

/**
 * How long a control's parent must stay still after a text or child change
 * before its controls re-measure, ms: a label or link beside a control can
 * move without resizing the control or its parent.
 */
const CONTENT_SETTLE_MS = 100;

const PASSIVE_CAPTURE = {capture: true, passive: true} as const;

/**
 * The mutations that can change which elements `INTERACTIVE_SELECTOR`
 * matches: elements added, removed or moved, and the attributes it reads.
 */
const CANDIDATE_MUTATIONS: MutationObserverInit = {
  childList: true,
  subtree: true,
  attributes: true,
  attributeFilter: [
    'href',
    'type',
    'for',
    'contenteditable',
    'role',
    'tabindex',
  ],
};

function now(): number {
  return typeof performance === 'undefined' ? Date.now() : performance.now();
}

interface Watch {
  readonly element: Element;
  readonly minSize: number;
  readonly ownsDescendantTouches: boolean;
  readonly growth?: (
    target: HitRect,
    toLayout: (rect: HitRect) => HitRect,
  ) => HitInsets;
  readonly checkAtPress: boolean;
  readonly onInsets: (insets: HitInsets) => void;
  isVisible: boolean;
  last: HitInsets;
}

/** Each watched element: its watches, and what observes it while coarse. */
interface Watched {
  readonly watches: Set<Watch>;
  /** Undoes the element's observation; null while the pointer is fine. */
  release: (() => void) | null;
  /** The armed one-shot click swallower, if a touch was nearer a neighbour. */
  disarm: (() => void) | null;
}

const watched = new Map<Element, Watched>();
const pending = new Set<Watch>();
const observedSizes = new WeakMap<Element, string>();
const scopeTimers = new Map<Element, ReturnType<typeof setTimeout>>();
let frame: number | null = null;
let view: Window | null = null;
/** The document the shared press listener is on, while it is on one. */
let pressDocument: Document | null = null;
let pointer: MediaQueryList | null = null;
let visibility: IntersectionObserver | null = null;
let resize: ResizeObserver | null = null;
let isCoarse = false;
/**
 * The page's interactive elements, as the last pass found them. A pass keeps
 * them until a mutation or a watch change can change them.
 */
let interactive: Element[] | null = null;
let interactiveDocument: Document | null = null;
let stopInteractiveWatch: (() => void) | null = null;

function forgetInteractive(): void {
  interactive = null;
}

function stopWatchingInteractive(): void {
  stopInteractiveWatch?.();
  stopInteractiveWatch = null;
  interactiveDocument = null;
  interactive = null;
}

function sameInsets(a: HitInsets, b: HitInsets): boolean {
  return (
    a.top === b.top &&
    a.right === b.right &&
    a.bottom === b.bottom &&
    a.left === b.left
  );
}

function deliver(watch: Watch, insets: HitInsets): void {
  if (sameInsets(watch.last, insets)) {
    return;
  }
  watch.last = insets;
  watch.onInsets(insets);
}

/** Whether `candidate` is the control itself, or part of it. */
function isOwn(watch: Watch, candidate: Element): boolean {
  const {element} = watch;
  if (
    candidate === element ||
    candidate.contains(element) ||
    element.contains(candidate)
  ) {
    return true;
  }
  // The control's own <label for> toggles it: not a neighbour.
  const control = (candidate as HTMLLabelElement).control;
  return control != null && element.contains(control);
}

/**
 * An element's client rect as a plain object: the pass compares every control
 * with every candidate, and a DOMRect's getters cost far more than fields.
 */
function plainRect(element: Element): HitRect {
  const {left, top, right, bottom} = element.getBoundingClientRect();
  return {left, top, right, bottom};
}

/** A box that the transforms around it leave at its layout size. */
const UNSCALED = {x: 1, y: 1} as const;

/** One axis of a box's scale on screen: its client size over its layout size. */
function axisScale(onScreen: number, layout: number): number {
  if (!(layout > 0) || !(onScreen > 0)) {
    return 1;
  }
  const scale = onScreen / layout;
  // Within rounding of 1 the box is at its layout size: no change to the rects.
  return Math.abs(scale - 1) < 1e-3 ? 1 : scale;
}

/**
 * How far the transforms around `element` scale its box on screen, per axis.
 * A layer that opens from a smaller scale scales every rect inside it, while
 * the layout box keeps the size the layer settles at. Only a scale is
 * expected: a rotated or skewed box would read as a larger scale.
 */
function screenScale(
  element: Element,
  onScreen: HitRect,
): {x: number; y: number} {
  // The offset size is the layout size in whole pixels, unaffected by
  // transforms, and costs no style resolution. A box with none, such as an SVG
  // element or a jsdom box, reads as unscaled.
  const box = element as Partial<HTMLElement>;
  const offsetWidth = box.offsetWidth ?? 0;
  const offsetHeight = box.offsetHeight ?? 0;
  if (offsetWidth === 0 || offsetHeight === 0) {
    return UNSCALED;
  }
  // Within a pixel of its layout size the box reads as unscaled, which bounds
  // the inset error at about a pixel. Only a box that a transform shrinks or
  // grows reads its exact size from the computed style.
  if (
    Math.abs(onScreen.right - onScreen.left - offsetWidth) <= 1 &&
    Math.abs(onScreen.bottom - onScreen.top - offsetHeight) <= 1
  ) {
    return UNSCALED;
  }
  const style = element.ownerDocument.defaultView?.getComputedStyle(element);
  if (style == null || !style.width.endsWith('px')) {
    return UNSCALED;
  }
  const px = (value: string) => Number.parseFloat(value) || 0;
  const isContentBox = style.boxSizing !== 'border-box';
  const width =
    px(style.width) +
    (isContentBox
      ? px(style.paddingLeft) +
        px(style.paddingRight) +
        px(style.borderLeftWidth) +
        px(style.borderRightWidth)
      : 0);
  const height =
    px(style.height) +
    (isContentBox
      ? px(style.paddingTop) +
        px(style.paddingBottom) +
        px(style.borderTopWidth) +
        px(style.borderBottomWidth)
      : 0);
  return {
    x: axisScale(onScreen.right - onScreen.left, width),
    y: axisScale(onScreen.bottom - onScreen.top, height),
  };
}

/**
 * `rect` in the layout px of the box at `origin`: its offset from `origin`,
 * divided by that box's scale on screen.
 */
function inLayout(
  rect: HitRect,
  origin: HitRect,
  scale: {x: number; y: number},
): HitRect {
  if (scale.x === 1 && scale.y === 1) {
    return rect;
  }
  return {
    left: origin.left + (rect.left - origin.left) / scale.x,
    top: origin.top + (rect.top - origin.top) / scale.y,
    right: origin.left + (rect.right - origin.left) / scale.x,
    bottom: origin.top + (rect.bottom - origin.top) / scale.y,
  };
}

interface Candidate {
  readonly element: Element;
  readonly rect: HitRect;
}

/** The watched element `element` belongs to, if any (itself included). */
function watchedOwner(element: Element): Element | null {
  for (
    let node: Element | null = element;
    node != null;
    node = node.parentElement
  ) {
    if (watched.has(node)) {
      return node;
    }
  }
  return null;
}

/**
 * The page's interactive elements. A watched control counts by its own box,
 * never by a part inside it (its invisible input is grown by its hit area,
 * which must not shrink a neighbour's).
 */
function interactiveElements(doc: Document): Element[] {
  if (typeof MutationObserver === 'undefined') {
    // Nothing reports a change, so nothing is kept.
    interactive = null;
  } else if (interactiveDocument !== doc) {
    stopWatchingInteractive();
    interactiveDocument = doc;
    stopInteractiveWatch = observeMutations(
      doc,
      CANDIDATE_MUTATIONS,
      forgetInteractive,
    );
  } else {
    // A mutation earlier in this task is not delivered yet.
    flushMutations(CANDIDATE_MUTATIONS);
  }
  if (interactive != null) {
    return interactive;
  }
  const seen = new Set<Element>();
  const elements: Element[] = [];
  for (const found of doc.querySelectorAll(INTERACTIVE_SELECTOR)) {
    const element = watchedOwner(found) ?? found;
    if (!seen.has(element)) {
      seen.add(element);
      elements.push(element);
    }
  }
  interactive = elements;
  return elements;
}

/** The page's interactive elements and their rects: one read. */
function readCandidates(doc: Document): Candidate[] {
  return interactiveElements(doc).map(element => ({
    element,
    rect: plainRect(element),
  }));
}

/** A control's rect and clamped insets, from candidates already read. */
function measureOne(
  watch: Watch,
  candidates: ReadonlyArray<Candidate>,
): {target: HitRect; insets: HitInsets; neighbours: HitRect[]} {
  const target = plainRect(watch.element);
  const scale = screenScale(watch.element, target);
  // Two targets each growing up to half the minimum reach each other from a
  // minimum apart.
  const reach = Math.max(0, watch.minSize);
  const band = grown(target, {
    top: reach * scale.y,
    right: reach * scale.x,
    bottom: reach * scale.y,
    left: reach * scale.x,
  });
  const neighbours = candidates
    .filter(
      ({element, rect}) =>
        rect.right > rect.left &&
        rect.bottom > rect.top &&
        intersects(band, rect) &&
        !isOwn(watch, element),
    )
    .map(({rect}) => rect);
  return {
    target,
    // The insets are in the control's layout px. The returned rects stay in
    // screen px for a touch's distance checks. A neighbour maps by the
    // control's scale, as if it is in the same layer. A neighbour outside that
    // layer then reads farther away. A touch compares screen distances, so it
    // still counts that neighbour.
    insets: clampedHitInsets(
      inLayout(target, target, scale),
      neighbours.map(rect => inLayout(rect, target, scale)),
      watch.minSize,
      watch.growth?.(inLayout(target, target, scale), rect =>
        inLayout(rect, target, scale),
      ),
    ),
    neighbours,
  };
}

/** One pass: every pending control's reads, then every write. */
function measure(): void {
  frame = null;
  const due = [...pending].filter(watch => watch.isVisible);
  pending.clear();
  if (!isCoarse || due.length === 0) {
    return;
  }
  // Reads: the page's interactive elements once for the whole pass.
  const candidates = readCandidates(due[0].element.ownerDocument);
  // The budget is for the controls: the page read above is once a frame.
  const started = now();
  const results: {watch: Watch; insets: HitInsets}[] = [];
  for (const watch of due) {
    // At least one control a frame; past the budget the rest wait for the
    // next frame, their insets still 0 (safe) until measured.
    if (results.length > 0 && now() - started > FRAME_BUDGET_MS) {
      pending.add(watch);
      continue;
    }
    results.push({watch, insets: measureOne(watch, candidates).insets});
  }
  // Writes.
  for (const {watch, insets} of results) {
    deliver(watch, insets);
  }
  if (pending.size > 0) {
    requestFrame();
  }
}

function requestFrame(): void {
  if (frame == null && typeof requestAnimationFrame === 'function') {
    frame = requestAnimationFrame(measure);
  }
}

function schedule(watch: Watch): void {
  if (!isCoarse) {
    return;
  }
  pending.add(watch);
  requestFrame();
}

function scheduleAll(): void {
  for (const entry of watched.values()) {
    entry.watches.forEach(schedule);
  }
}

/**
 * At a touch's start, re-measure the control it landed on, at once: if the
 * touch is outside the fresh area (a neighbour moved nearer since the last
 * measurement), the control's click is swallowed. The tap then does
 * nothing rather than toggle the wrong control; nothing is re-sent to the
 * neighbour, and the next tap uses the fresh insets. A watch whose owner reads
 * its own targets when a press begins skips this (`checkAtPress`).
 */
function onPress(event: Event): void {
  // One listener on the document for every watched control, so a control, row
  // or handle has none of its own (AST-103 FR5). The innermost watched element
  // that the press lands in is the one it is for.
  for (
    let node: Element | null =
      event.target instanceof Element ? event.target : null;
    node != null;
    node = node.parentElement
  ) {
    if (watched.has(node)) {
      checkPress(node, event as PointerEvent);
      return;
    }
  }
}

function checkPress(element: Element, event: PointerEvent): void {
  const entry = watched.get(element);
  if (entry == null) {
    return;
  }
  // A swallower left from a touch that sent no click goes with the next one.
  entry.disarm?.();
  const press = event;
  if (!isCoarse || press.pointerType !== 'touch') {
    return;
  }
  const checked = [...entry.watches].filter(watch => watch.checkAtPress);
  if (checked.length === 0) {
    return;
  }
  const candidates = readCandidates(element.ownerDocument);
  const x = press.clientX;
  const y = press.clientY;
  // The touch is the control's unless a neighbour is nearer it: inside the
  // fresh area too (a corner beside an offset or diagonal neighbour), and
  // a few px past it, where a browser's own touch adjustment reaches.
  let isNearerNeighbour = false;
  for (const watch of checked) {
    const {target, insets, neighbours} = measureOne(watch, candidates);
    deliver(watch, insets);
    const own = distanceTo(target, x, y);
    isNearerNeighbour ||= neighbours.some(rect => distanceTo(rect, x, y) < own);
  }
  // A watch can own its descendants' touches. Then a press that the browser
  // hit-tests onto a descendant lands on content the element paints, even
  // past its own box. A swipe panel's entry beside a moved row is such
  // content. That touch is the element's.
  const isOnOwnContent =
    [...entry.watches].some(watch => watch.ownsDescendantTouches) &&
    press.target instanceof Node &&
    press.target !== element &&
    element.contains(press.target);
  if (isNearerNeighbour && !isOnOwnContent) {
    const swallow = (click: Event) => {
      disarm();
      // A keyboard or assistive-technology activation (detail 0) is never
      // this touch's click: it goes through.
      if ((click as MouseEvent).detail === 0) {
        return;
      }
      click.preventDefault();
      click.stopPropagation();
    };
    const doc = element.ownerDocument;
    const disarm = () => {
      element.removeEventListener('click', swallow, true);
      element.removeEventListener('pointercancel', disarm, true);
      doc.removeEventListener('pointerdown', onNextPress, PASSIVE_CAPTURE);
      if (entry.disarm === disarm) {
        entry.disarm = null;
      }
    };
    // Any next press, here or elsewhere (the control's own label), ends it.
    const onNextPress = () => disarm();
    element.addEventListener('click', swallow, true);
    // A touch the browser takes (a scroll) sends no click.
    element.addEventListener('pointercancel', disarm, true);
    // Registered after this press's own dispatch has passed the document.
    doc.addEventListener('pointerdown', onNextPress, PASSIVE_CAPTURE);
    entry.disarm = disarm;
  }
}

function onScopeChange(scope: Element): void {
  const timer = scopeTimers.get(scope);
  if (timer != null) {
    clearTimeout(timer);
  }
  scopeTimers.set(
    scope,
    setTimeout(() => {
      scopeTimers.delete(scope);
      for (const [element, entry] of watched) {
        if (element.parentElement === scope) {
          entry.watches.forEach(schedule);
        }
      }
    }, CONTENT_SETTLE_MS),
  );
}

/** Starts observing one element; only while the pointer is coarse. */
function observe(element: Element, entry: Watched): void {
  const parent = element.parentElement;
  visibility?.observe(element);
  resize?.observe(element);
  if (parent != null) {
    resize?.observe(parent);
  }
  const stopScope =
    parent == null ? null : observeContent(parent, () => onScopeChange(parent));
  entry.release = () => {
    visibility?.unobserve(element);
    resize?.unobserve(element);
    const parentShared = [...watched.keys()].some(
      other => other !== element && other.parentElement === parent,
    );
    if (parent != null && !parentShared) {
      resize?.unobserve(parent);
      const timer = scopeTimers.get(parent);
      if (timer != null) {
        clearTimeout(timer);
        scopeTimers.delete(parent);
      }
    }
    stopScope?.();
    entry.disarm?.();
  };
}

/**
 * Everything that watches the page for hit areas is on only while the
 * primary pointer is coarse, so a mouse page runs no observer, timer or
 * listener for them.
 */
function startObserving(): void {
  if (view == null) {
    return;
  }
  view.addEventListener('resize', scheduleAll);
  pressDocument = view.document;
  pressDocument.addEventListener('pointerdown', onPress, PASSIVE_CAPTURE);
  if (typeof IntersectionObserver === 'function') {
    visibility = new IntersectionObserver(entries => {
      for (const entry of entries) {
        watched.get(entry.target)?.watches.forEach(watch => {
          watch.isVisible = entry.isIntersecting;
          if (watch.isVisible) {
            schedule(watch);
          } else {
            pending.delete(watch);
          }
        });
      }
    });
  }
  if (typeof ResizeObserver === 'function') {
    resize = new ResizeObserver(entries => {
      for (const entry of entries) {
        // The first notice of an element is its observation, not a resize:
        // the control's first measurement is already pending.
        const {width, height} = entry.contentRect;
        const size = `${width}x${height}`;
        const last = observedSizes.get(entry.target);
        observedSizes.set(entry.target, size);
        if (last === undefined || last === size) {
          continue;
        }
        for (const [element, item] of watched) {
          if (
            element === entry.target ||
            element.parentElement === entry.target
          ) {
            item.watches.forEach(schedule);
          }
        }
      }
    });
  }
  for (const [element, entry] of watched) {
    // Without IntersectionObserver every control counts as on screen.
    entry.watches.forEach(watch => {
      watch.isVisible = visibility == null;
    });
    observe(element, entry);
    if (visibility == null) {
      entry.watches.forEach(schedule);
    }
  }
}

function stopObserving(): void {
  for (const entry of watched.values()) {
    entry.release?.();
    entry.release = null;
  }
  view?.removeEventListener('resize', scheduleAll);
  // The listener leaves the document it went on. A window can close first, as
  // a removed iframe's, and then it has no document to read.
  pressDocument?.removeEventListener('pointerdown', onPress, PASSIVE_CAPTURE);
  pressDocument = null;
  visibility?.disconnect();
  resize?.disconnect();
  visibility = null;
  resize = null;
  scopeTimers.forEach(timer => clearTimeout(timer));
  scopeTimers.clear();
  stopWatchingInteractive();
  if (frame != null && typeof cancelAnimationFrame === 'function') {
    cancelAnimationFrame(frame);
  }
  frame = null;
  pending.clear();
}

function onPointerChange(): void {
  const next = pointer?.matches ?? false;
  if (next === isCoarse) {
    return;
  }
  isCoarse = next;
  if (isCoarse) {
    startObserving();
    return;
  }
  stopObserving();
  for (const entry of watched.values()) {
    entry.watches.forEach(watch => deliver(watch, NO_HIT_INSETS));
  }
}

/** Options of `watchHitArea`. */
export interface WatchHitAreaOptions {
  /** The size to grow toward, px. @default 44 */
  readonly minSize?: number;
  /**
   * A touch that the browser hit-tests onto a descendant is the element's,
   * however near a neighbour is. Set it for a host whose content can paint
   * past its box, such as a list row with a swipe panel. A control whose
   * grown input is its descendant leaves it off. @default false
   */
  readonly ownsDescendantTouches?: boolean;
  /**
   * How far the control grows on each side before any neighbour stops it,
   * read in the measure pass. A group passes `groupGrowth` of its members.
   * It gets the control's box in layout px, and `toLayout` maps a rect the
   * owner reads into the same px.
   * @default toward `minSize` on each axis, centered
   */
  readonly growth?: (
    target: HitRect,
    toLayout: (rect: HitRect) => HitRect,
  ) => HitInsets;
  /**
   * Whether a finger's press on the control re-measures it against every
   * interactive element on the page, at once. An owner that reads its own
   * targets when a press begins, such as a group's tracker, turns it off.
   * @default true
   */
  readonly checkAtPress?: boolean;
}

/**
 * Stops every watch and forgets them, for tests: no observer, listener or
 * answer outlives a test that left a watch behind.
 */
export function resetHitAreaForTests(): void {
  stopObserving();
  for (const entry of watched.values()) {
    entry.disarm?.();
  }
  watched.clear();
  pending.clear();
  pointer?.removeEventListener('change', onPointerChange);
  pointer = null;
  view = null;
  isCoarse = false;
}

/**
 * Keeps `element`'s hit insets live until the returned function runs:
 * `onInsets` hears each change (typically `writeHitInsets` on the control).
 * Where the primary pointer is not coarse the insets are 0 and nothing but
 * the pointer query is listened to; where it is, the element is measured
 * while on screen, on resize (its own, its parent's, the window's) and once
 * its parent's text and children settle after a change, all in the shared
 * per-frame pass, and re-measured at once when a touch starts on it.
 */
export function watchHitArea(
  element: Element,
  onInsets: (insets: HitInsets) => void,
  {
    minSize = MIN_TOUCH_TARGET,
    ownsDescendantTouches = false,
    growth: growthOf,
    checkAtPress = true,
  }: WatchHitAreaOptions = {},
): () => void {
  const owner = element.ownerDocument.defaultView;
  if (owner == null) {
    return () => {};
  }
  view = owner;
  // Read the pointer query at every watch, not only the first: an
  // environment that replaces matchMedia (a test) must not leave a stale
  // answer behind from a watch that never stopped.
  const query = owner.matchMedia?.(TOUCH_QUERY) ?? null;
  if (query !== pointer) {
    pointer?.removeEventListener('change', onPointerChange);
    pointer = query;
    pointer?.addEventListener('change', onPointerChange);
  }
  onPointerChange();
  const watch: Watch = {
    element,
    minSize,
    ownsDescendantTouches,
    growth: growthOf,
    checkAtPress,
    onInsets,
    isVisible: isCoarse && visibility == null,
    last: NO_HIT_INSETS,
  };
  let entry = watched.get(element);
  if (entry == null) {
    entry = {watches: new Set(), release: null, disarm: null};
    watched.set(element, entry);
    forgetInteractive();
    entry.watches.add(watch);
    if (isCoarse) {
      observe(element, entry);
    }
  } else {
    // Another watch of an observed element: as visible as the first.
    watch.isVisible = [...entry.watches][0]?.isVisible ?? watch.isVisible;
    entry.watches.add(watch);
  }
  if (watch.isVisible) {
    schedule(watch);
  }
  return () => {
    const own = watched.get(element);
    if (own == null || !own.watches.delete(watch)) {
      return;
    }
    pending.delete(watch);
    if (own.watches.size === 0) {
      own.release?.();
      watched.delete(element);
      forgetInteractive();
    }
    if (watched.size === 0) {
      stopObserving();
      pointer?.removeEventListener('change', onPointerChange);
      pointer = null;
      view = null;
      isCoarse = false;
    }
  };
}