Skip to content

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

TypeScript
27.7 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.
//
// DOM measurement strategies for Crowdin screenshot manual tagging.
//
// Each strategy runs in the PAGE context (via page.evaluate) and returns
// {x, y, width, height} in CSS pixels, or null if no match was found. The
// caller multiplies by DPR before POSTing to Crowdin.
//
// Strategies are pure DOM lookups — they don't interact with the page.
// Interactions (open popover, click chip, etc.) happen in the target's
// `interact()` function before measurement.
//
// All strategy code is inlined into a single browserside function
// (see buildMeasureSource) which is stringified and executed via
// page.evaluate. The geometry helpers below are injected into that source.

export const STRATEGY_NAMES = [
  'visibleText',
  'option',
  'placeholder',
  'ariaLabel',
  'chipOperator',
  'filterInput',
  'footerButton',
  'srOnlyLabel',
  'srOnlyReveal',
  'textRun',
  'liveRegionReveal',
];

// Strategies that inject a reveal bubble, so they also run before the
// screenshot. Idempotent: measuring returns the rect recorded at injection.
export const MUTATING_STRATEGIES = ['srOnlyReveal', 'liveRegionReveal'];

// Gap in CSS px between a reveal bubble and the widget it labels — a little
// wider beside the widget than above or below it.
export const REVEAL_BUBBLE_GAP = {block: 4, inline: 6};

// Layout coordinates carry float error, so an edge mathematically on the
// boundary can measure a fraction past it.
const EDGE_EPSILON = 1e-6;

/**
 * True when the capture contains the whole rect.
 *
 * Crowdin validates every tag against its image, so containment is part of
 * whether a DOM match is usable at all — a match below the fold is not a
 * match, and a later candidate may still be a good one. Partial rects are
 * rejected rather than trimmed; nothing here scrolls.
 */
export function rectWithinViewport(rect, viewport) {
  if (!rect) return false;
  if (!(rect.width > 0) || !(rect.height > 0)) return false;
  return (
    rect.x >= -EDGE_EPSILON &&
    rect.y >= -EDGE_EPSILON &&
    rect.x + rect.width <= viewport.width + EDGE_EPSILON &&
    rect.y + rect.height <= viewport.height + EDGE_EPSILON
  );
}

/**
 * Viewport-space rect for a reveal bubble of `bubbleSize` placed at
 * `placement` beside `widgetRect`, clamped inside the viewport on both axes.
 *
 * Clamping slides the bubble along the edge it would have crossed, so the tag
 * still labels the widget it was placed against. A bubble larger than the
 * viewport is pinned at the origin and `rectWithinViewport` then rejects it.
 */
export function placeRevealBubble(widgetRect, bubbleSize, placement, viewport) {
  const {width, height} = bubbleSize;
  const centeredX = widgetRect.x + widgetRect.width / 2 - width / 2;
  const centeredY = widgetRect.y + widgetRect.height / 2 - height / 2;
  let x;
  let y;
  switch (placement) {
    case 'below':
      x = centeredX;
      y = widgetRect.y + widgetRect.height + REVEAL_BUBBLE_GAP.block;
      break;
    case 'above':
      x = centeredX;
      y = widgetRect.y - height - REVEAL_BUBBLE_GAP.block;
      break;
    case 'left':
      x = widgetRect.x - width - REVEAL_BUBBLE_GAP.inline;
      y = centeredY;
      break;
    case 'right':
    default:
      x = widgetRect.x + widgetRect.width + REVEAL_BUBBLE_GAP.inline;
      y = centeredY;
  }
  return {
    x: Math.min(Math.max(x, 0), Math.max(0, viewport.width - width)),
    y: Math.min(Math.max(y, 0), Math.max(0, viewport.height - height)),
    width,
    height,
  };
}

/**
 * CSS pixels → the integer device pixels Crowdin stores a tag in.
 *
 * Both EDGES are rounded and the size derived from them: rounding position
 * and size independently can push `x + width` a pixel past the capture.
 */
export function toDevicePixelRect(rect, dpr) {
  const x = Math.round(rect.x * dpr);
  const y = Math.round(rect.y * dpr);
  return {
    x,
    y,
    width: Math.round((rect.x + rect.width) * dpr) - x,
    height: Math.round((rect.y + rect.height) * dpr) - y,
  };
}

// Free variables the stringified browser function reads from module scope.
// Anything it uses has to be listed here to reach the page.
const BROWSER_HELPERS = [rectWithinViewport, placeRevealBubble];
const BROWSER_CONSTANTS = {REVEAL_BUBBLE_GAP, EDGE_EPSILON};

/**
 * Source for `page.evaluate`: an expression evaluating to the `measure`
 * function, with the geometry helpers inlined.
 */
export function buildMeasureSource() {
  return [
    '(() => {',
    ...Object.entries(BROWSER_CONSTANTS).map(
      ([name, value]) => `const ${name} = ${JSON.stringify(value)};`,
    ),
    ...BROWSER_HELPERS.map(fn => fn.toString()),
    `return (${browserSideMeasure.toString()})();`,
    '})()',
  ].join('\n');
}

// This function is stringified and evaluated in the browser. Do not import
// anything from Node.js in here. `strategy` is the strategy name, `args` is
// an array of positional arguments.
export function browserSideMeasure() {
  return function measure(strategy, args) {
    // Utilities ---------------------------------------------------------------
    function visible(el) {
      return !!el && !!el.getClientRects && el.getClientRects().length > 0;
    }
    function rectOf(el) {
      if (!visible(el)) return null;
      const r = el.getBoundingClientRect();
      if (r.width <= 0 || r.height <= 0) return null;
      const rect = {x: r.x, y: r.y, width: r.width, height: r.height};
      return inViewport(rect) ? rect : null;
    }
    // The screenshot is the viewport, so a rect the viewport does not
    // contain cannot be tagged on it.
    function inViewport(rect) {
      return rectWithinViewport(rect, {
        width: window.innerWidth,
        height: window.innerHeight,
      });
    }
    // Matches when trimmed `actual === want`, or (when tolerance > 0) when
    // `actual.startsWith(want)` and the extra suffix is <= `tolerance` chars.
    // Pass tolerance=Infinity to accept any startsWith match.
    function matchText(actual, want, tolerance) {
      const t = (actual || '').trim();
      if (t === want) return true;
      if (!tolerance) return false;
      if (!t.startsWith(want)) return false;
      return t.length <= want.length + tolerance;
    }
    function visibleListbox() {
      const all = Array.from(document.querySelectorAll('[role="listbox"]'));
      return all.find(el => rectOf(el)) || all[0] || null;
    }
    // Shared popover/dialog container selector list, used by strategies that
    // need to scope their DOM query to the currently-open popover surface.
    function visibleContainers(opts) {
      const includeListbox = opts && opts.includeListbox;
      const sel = includeListbox
        ? '[role="dialog"], [role="listbox"], [data-radix-popper-content-wrapper], [data-state="open"]'
        : '[role="dialog"], [data-radix-popper-content-wrapper], [data-state="open"]';
      return Array.from(document.querySelectorAll(sel));
    }
    // Walks up from `el.parentElement` looking for the first ancestor whose
    // rect is >= minSize × minSize. Used to find the visible widget above a
    // visually-hidden (sr-only) label.
    function walkUpToMeasurable(el, minSize) {
      const min = minSize == null ? 20 : minSize;
      let anc = el.parentElement;
      while (anc) {
        const pr = anc.getBoundingClientRect();
        if (pr.width >= min && pr.height >= min) return anc;
        anc = anc.parentElement;
      }
      return null;
    }
    // Like walkUpToMeasurable but considers `el` itself as the first
    // candidate. Used when the tagged element (a button/icon) is usually
    // already the widget but occasionally an inner span too small to
    // measure.
    function expandToMeasurableSelf(el, minSize) {
      const min = minSize == null ? 6 : minSize;
      let w = el;
      while (w) {
        const wr = w.getBoundingClientRect();
        if (wr.width >= min && wr.height >= min) return w;
        w = w.parentElement;
      }
      return null;
    }
    function findByExactText(text, root, candidateSelectors) {
      const scope = root || document.body;
      const els = Array.from(
        scope.querySelectorAll(candidateSelectors || '[role="option"], button, span, div, li, a, p, h1, h2, h3, h4'),
      );
      let best = null;
      for (const el of els) {
        if (!visible(el)) continue;
        if ((el.textContent || '').trim() !== text) continue;
        const r = el.getBoundingClientRect();
        // Skip essentially-invisible rects — sr-only labels are ~1×1 px.
        // Callers that specifically want sr-only labels should use
        // the srOnlyLabel strategy instead.
        if (r.width < 6 || r.height < 6) continue;
        if (!inViewport(r)) continue;
        // Prefer the SMALLEST matching element — it's the most specific
        // (avoids picking up giant wrapper divs whose textContent happens
        // to equal the target text because they contain only that node).
        if (!best || r.width * r.height < best.w * best.h) {
          best = {x: r.x, y: r.y, w: r.width, h: r.height};
        }
      }
      if (!best) return null;
      return {x: best.x, y: best.y, width: best.w, height: best.h};
    }
    // Reveal bubbles — shared by srOnlyReveal and liveRegionReveal. -----------

    // Idempotent: a bubble injected by the pre-screenshot pass reports the
    // rect recorded when it was placed. That recorded rect is the authority —
    // re-deriving it from the DOM would have to redo positionBubble's
    // containing-block correction.
    function readCachedRect(el) {
      if (!el) return null;
      const cx = parseFloat(el.getAttribute('data-crowdin-vx') || '');
      const cy = parseFloat(el.getAttribute('data-crowdin-vy') || '');
      const cw = parseFloat(el.getAttribute('data-crowdin-vw') || '');
      const ch = parseFloat(el.getAttribute('data-crowdin-vh') || '');
      if (Number.isFinite(cx) && Number.isFinite(cy) &&
          Number.isFinite(cw) && Number.isFinite(ch)) {
        return {x: cx, y: cy, width: cw, height: ch};
      }
      return null;
    }
    function cacheRect(bubble, rect) {
      bubble.setAttribute('data-crowdin-vx', String(rect.x));
      bubble.setAttribute('data-crowdin-vy', String(rect.y));
      bubble.setAttribute('data-crowdin-vw', String(rect.width));
      bubble.setAttribute('data-crowdin-vh', String(rect.height));
    }
    function existingBubbleRect(text) {
      const existing = document.querySelector(
        `[data-crowdin-reveal-text="${CSS.escape(text)}"]`,
      );
      if (!existing) return undefined;
      const cached = readCachedRect(existing);
      if (!cached) return undefined;
      return inViewport(cached) ? cached : null;
    }
    function applyBubbleStyle(bubble, t) {
      bubble.setAttribute('data-crowdin-reveal', '1');
      bubble.setAttribute('data-crowdin-reveal-text', t);
      bubble.textContent = t;
      const S = bubble.style;
      S.position = 'fixed';
      S.background = '#ffe680';
      S.border = '1px solid #b8860b';
      S.borderRadius = '4px';
      S.padding = '2px 6px';
      S.font =
        '600 11px system-ui, -apple-system, BlinkMacSystemFont, sans-serif';
      S.color = '#654200';
      S.zIndex = '99999';
      S.whiteSpace = 'nowrap';
      S.pointerEvents = 'none';
      S.lineHeight = '14px';
    }
    // Place the bubble at `place`, clamped inside the viewport, and return the
    // rect it occupies in the screenshot. `position: fixed` resolves against a
    // transformed ancestor or the top layer, not always the viewport, so write
    // viewport coordinates, read back where the browser painted, and correct
    // by the difference.
    function positionBubble(bubble, widgetRect, place) {
      const b = bubble.getBoundingClientRect();
      const target = placeRevealBubble(
        widgetRect,
        {width: b.width, height: b.height},
        place,
        {width: window.innerWidth, height: window.innerHeight},
      );
      bubble.style.left = `${target.x}px`;
      bubble.style.top = `${target.y}px`;
      const painted = bubble.getBoundingClientRect();
      const dx = target.x - painted.x;
      const dy = target.y - painted.y;
      if (Math.abs(dx) >= 0.5 || Math.abs(dy) >= 0.5) {
        bubble.style.left = `${target.x + dx}px`;
        bubble.style.top = `${target.y + dy}px`;
      }
      return target;
    }
    // Inject one bubble reading `text` beside each widget in `anchors`, and
    // return the last placed rect. A widget outside the capture gets no
    // bubble: clamping one into view would park a tag on whatever is at the
    // edge.
    function injectRevealBubbles(text, anchors, place) {
      let lastRect = null;
      for (const anc of anchors) {
        const pr = anc.getBoundingClientRect();
        if (!inViewport(pr)) continue;
        const bubble = document.createElement('div');
        applyBubbleStyle(bubble, text);
        // Native <dialog>.showModal() renders inside the browser's "top
        // layer" above all other content. Elements in the normal DOM tree are
        // painted UNDER the dialog regardless of z-index. If the widget is
        // inside a modal dialog, attach the bubble to that dialog so it also
        // renders in the top layer.
        const modalHost =
          anc.closest('dialog[open]') || anc.closest('[popover]');
        (modalHost || document.body).appendChild(bubble);
        const rect = positionBubble(bubble, pr, place);
        cacheRect(bubble, rect);
        lastRect = rect;
      }
      // A bubble larger than the viewport cannot be placed legally.
      return inViewport(lastRect) ? lastRect : null;
    }

    // Returns true if `el` is the topmost element at its own center — i.e.
    // NOT covered by an overlapping popover/dropdown. Guards against
    // tagging positions of buttons that are hidden behind an open
    // value-picker dropdown that Playwright triggered mid-flight.
    function isVisibleAtCenter(el) {
      const r = el.getBoundingClientRect();
      if (r.width <= 0 || r.height <= 0) return false;
      const cx = r.left + r.width / 2;
      const cy = r.top + r.height / 2;
      const top = document.elementFromPoint(cx, cy);
      if (!top) return false;
      return top === el || el.contains(top) || top.contains(el);
    }

    // Strategy implementations -----------------------------------------------
    // visibleText(text) — find the smallest element whose exact trimmed text
    // is `text`. Searches the whole document. Good for generic labels.
    function visibleText(text) {
      return findByExactText(text);
    }

    // option(text) — find role=option whose accessible name / text is `text`.
    // Prefers the currently-visible listbox. Falls back to any role=option
    // in the document (exact match only for the fallback).
    function option(text) {
      const lb = visibleListbox();
      if (lb) {
        const opts = Array.from(lb.querySelectorAll('[role="option"]'));
        for (const el of opts) {
          if (!visible(el)) continue;
          // Match exact OR startsWith with tight length bound (guards
          // against options that include a trailing icon/counter).
          if (!matchText(el.textContent, text, 4)) continue;
          const r = rectOf(el);
          if (r) return r;
        }
      }
      const opts = Array.from(document.querySelectorAll('[role="option"]'));
      for (const el of opts) {
        if (!visible(el)) continue;
        if (!matchText(el.textContent, text, 0)) continue;
        const r = rectOf(el);
        if (r) return r;
      }
      return null;
    }

    // placeholder(text) — find an <input>/<textarea> whose placeholder
    // attribute equals or starts with `text`. Returns the input's rect.
    // Also matches aria-placeholder / data-placeholder as fallback.
    function placeholder(text) {
      const inputs = Array.from(
        document.querySelectorAll('input[placeholder], textarea[placeholder]'),
      );
      for (const el of inputs) {
        if (!visible(el)) continue;
        if (!matchText(el.getAttribute('placeholder'), text, Infinity)) continue;
        const r = rectOf(el);
        if (r) return r;
      }
      const alt = Array.from(
        document.querySelectorAll('[aria-placeholder], [data-placeholder]'),
      );
      for (const el of alt) {
        if (!visible(el)) continue;
        const p =
          el.getAttribute('aria-placeholder') ||
          el.getAttribute('data-placeholder');
        if (!matchText(p, text, Infinity)) continue;
        const r = rectOf(el);
        if (r) return r;
      }
      return null;
    }

    // ariaLabel(text) — find an element whose aria-label equals `text`.
    function ariaLabel(text) {
      const els = Array.from(document.querySelectorAll('[aria-label]'));
      for (const el of els) {
        if (!visible(el)) continue;
        if (!matchText(el.getAttribute('aria-label'), text, 0)) continue;
        const r = rectOf(el);
        if (r) return r;
      }
      return null;
    }

    // chipOperator(fieldName, opText) — find a chip labeled
    // `${fieldName}: ${opText} ...` and return the rect of just the opText
    // substring (using Range selection on the text node). Chips are
    // rendered as buttons with visible text like "Created: is after Jan 14".
    function chipOperator(fieldName, opText) {
      const buttons = Array.from(document.querySelectorAll('button'));
      for (const btn of buttons) {
        if (!visible(btn)) continue;
        const t = (btn.textContent || '').trim();
        if (!t.startsWith(`${fieldName}:`)) continue;
        // Find the text node containing opText and use a Range to measure.
        const walker = document.createTreeWalker(btn, NodeFilter.SHOW_TEXT);
        let node;
        while ((node = walker.nextNode())) {
          const idx = node.nodeValue.indexOf(opText);
          if (idx === -1) continue;
          const range = document.createRange();
          range.setStart(node, idx);
          range.setEnd(node, idx + opText.length);
          const rects = range.getClientRects();
          if (!rects.length) continue;
          const r = rects[0];
          if (r.width <= 0 || r.height <= 0) continue;
          if (!inViewport(r)) continue;
          return {x: r.x, y: r.y, width: r.width, height: r.height};
        }
      }
      return null;
    }

    // filterInput(kind) — find the value editor input inside the currently
    // open filter popover. `kind` is 'string' | 'number' | 'search' | 'date'.
    //   string  -> input[type=text] or input without type
    //   number  -> input[type=number]
    //   date    -> input[type=date] or input with role=combobox in date popover
    //   search  -> input[placeholder*=Search]
    function filterInput(kind) {
      const containers = visibleContainers({includeListbox: true});
      const scope = containers.length ? containers : [document.body];
      let selector = 'input, textarea';
      if (kind === 'number') selector = 'input[type="number"]';
      else if (kind === 'date') selector = 'input[type="date"], input[type="datetime-local"], input[role="combobox"]';
      else if (kind === 'search') selector = 'input[placeholder*="Search" i]';
      for (const root of scope) {
        const inputs = Array.from(root.querySelectorAll(selector));
        for (const el of inputs) {
          if (!visible(el)) continue;
          const r = rectOf(el);
          if (r) return r;
        }
      }
      return null;
    }

    // footerButton(text) — find a <button> whose text is exactly `text`,
    // scoped to buttons that appear at the bottom of a dialog/popover.
    // Skips buttons that are covered by an overlapping element (e.g. an
    // open value-picker dropdown) so we don't tag hidden positions.
    // Fallback to any matching button in the document (smallest wins).
    function footerButton(text) {
      const containers = visibleContainers();
      for (const root of containers) {
        const btns = Array.from(root.querySelectorAll('button'));
        for (const b of btns) {
          if (!visible(b)) continue;
          if ((b.textContent || '').trim() !== text) continue;
          if (!isVisibleAtCenter(b)) continue;
          const r = rectOf(b);
          if (r) return r;
        }
      }
      const btns = Array.from(document.querySelectorAll('button'));
      let best = null;
      for (const b of btns) {
        if (!visible(b)) continue;
        if ((b.textContent || '').trim() !== text) continue;
        if (!isVisibleAtCenter(b)) continue;
        const r = b.getBoundingClientRect();
        if (r.width <= 0 || r.height <= 0) continue;
        if (!inViewport(r)) continue;
        // Pick the smallest — typically the actual footer button (larger
        // matches would be wrapper divs with the same text).
        if (!best || r.width * r.height < best.w * best.h) {
          best = {x: r.x, y: r.y, w: r.width, h: r.height};
        }
      }
      return best ? {x: best.x, y: best.y, width: best.w, height: best.h} : null;
    }

    // srOnlyLabel(text) — find a <label>/<span>/[aria-hidden] whose exact
    // text is `text` and return the rect of its nearest visible ancestor.
    // Useful for `isLabelHidden` controls where the label is in the DOM
    // (1×1 sr-only) but translators need to see the whole control.
    function srOnlyLabel(text) {
      const cands = Array.from(document.querySelectorAll('label, span, [aria-hidden="true"]'));
      for (const el of cands) {
        if ((el.textContent || '').trim() !== text) continue;
        const r = el.getBoundingClientRect();
        // Only apply when the label itself is visually-hidden (small rect).
        if (r.width > 20 && r.height > 20) continue;
        const anc = walkUpToMeasurable(el, 20);
        if (anc) return rectOf(anc);
      }
      return null;
    }

    // srOnlyReveal(text, placement?) — find a widget labeled `text` (via
    // either a visually-hidden <label>/<span>/aria-hidden element with
    // that text content, OR an aria-label / aria-labelledby matching that
    // text on any interactive element). Injects a small yellow "reveal
    // bubble" showing the label text next to the widget so translators
    // can SEE the label in the screenshot. Returns the bubble's rect so
    // the Crowdin tag lands on readable text, not an icon-only widget.
    //
    // placement: 'right' (default), 'below', 'above', 'left'.
    //
    // Prefer this over srOnlyLabel / ariaLabel when the tagged widget has
    // no visible text of its own (bare checkboxes, icon buttons like ×
    // and chevrons). Reveal bubbles are z-index 99999 so they overlay any
    // nearby content — pick a placement that doesn't cover the widget.
    function srOnlyReveal(text, placement) {
      const place = placement || 'right';

      const cached = existingBubbleRect(text);
      if (cached !== undefined) return cached;

      // Two match paths (deduped):
      // (1) sr-only label/span/aria-hidden element whose textContent is `text`
      //     → the widget is the nearest visible ancestor.
      // (2) any element with aria-label === text (or aria-labelledby → text)
      //     → the widget IS that element (or its measurable ancestor if
      //     the element itself is sub-6px).
      function findWidgetsForRevealText(t) {
        const widgets = [];
        // Path 1: sr-only text nodes
        const textCands = Array.from(
          document.querySelectorAll('label, span, [aria-hidden="true"]'),
        );
        for (const el of textCands) {
          if ((el.textContent || '').trim() !== t) continue;
          const r = el.getBoundingClientRect();
          if (r.width > 20 && r.height > 20) continue;
          const anc = walkUpToMeasurable(el, 20);
          if (anc) widgets.push(anc);
        }
        // Path 2a: aria-label matches
        const ariaCands = Array.from(
          document.querySelectorAll(`[aria-label="${CSS.escape(t)}"]`),
        );
        for (const el of ariaCands) {
          const w = expandToMeasurableSelf(el, 6);
          if (w) widgets.push(w);
        }
        // Path 2b: aria-labelledby matches
        const labelledByEls = Array.from(
          document.querySelectorAll('[aria-labelledby]'),
        );
        for (const el of labelledByEls) {
          const ids = (el.getAttribute('aria-labelledby') || '').split(/\s+/);
          const parts = ids
            .map(id => document.getElementById(id))
            .filter(Boolean)
            .map(n => (n.textContent || '').trim())
            .join(' ')
            .trim();
          if (parts !== t) continue;
          const w = expandToMeasurableSelf(el, 6);
          if (w) widgets.push(w);
        }
        // Dedup (same widget can be discovered via both paths).
        const seen = new Set();
        const unique = [];
        for (const w of widgets) {
          if (seen.has(w)) continue;
          seen.add(w);
          unique.push(w);
        }
        return unique;
      }

      const uniqueWidgets = findWidgetsForRevealText(text);
      if (uniqueWidgets.length === 0) return null;

      // One bubble per widget, so translators see the reveal for every
      // occurrence (e.g. "Expand row" on multiple rows).
      return injectRevealBubbles(text, uniqueWidgets, place);
    }

    // textRun(text) — Range-measure a bare text node reading `text`, for a
    // string sharing its element with other content ("↑↓" + "Navigate").
    function textRun(text) {
      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
      let node;
      let best = null;
      while ((node = walker.nextNode())) {
        const value = node.nodeValue || '';
        if (value.trim() !== text) continue;
        const parent = node.parentElement;
        if (!visible(parent)) continue;
        const range = document.createRange();
        // Skip surrounding whitespace so the rect hugs the words.
        const start = value.indexOf(text);
        range.setStart(node, start);
        range.setEnd(node, start + text.length);
        const r = range.getBoundingClientRect();
        if (r.width <= 0 || r.height <= 0) continue;
        if (!inViewport(r)) continue;
        // Smallest wins, matching findByExactText — the most specific match.
        if (!best || r.width * r.height < best.width * best.height) {
          best = {x: r.x, y: r.y, width: r.width, height: r.height};
        }
      }
      return best;
    }

    // liveRegionReveal(text, anchorSelector, placement?) — reveal a live
    // region announcement, which has no pixels, beside the widget it is about.
    // The announcement is transient, so injection has to happen while it lives.
    function liveRegionReveal(text, anchorSelector, placement) {
      const place = placement || 'below';

      const cached = existingBubbleRect(text);
      if (cached !== undefined) return cached;

      const regions = Array.from(
        document.querySelectorAll('[aria-live], [role="status"], [role="alert"]'),
      );
      if (!regions.some(el => (el.textContent || '').trim() === text)) return null;

      const anchor = anchorSelector
        ? document.querySelector(anchorSelector)
        : null;
      if (!anchor) return null;
      const widget = expandToMeasurableSelf(anchor, 6);
      if (!widget) return null;

      return injectRevealBubbles(text, [widget], place);
    }

    // Dispatcher --------------------------------------------------------------
    switch (strategy) {
      case 'visibleText': return visibleText(args[0]);
      case 'option': return option(args[0]);
      case 'placeholder': return placeholder(args[0]);
      case 'ariaLabel': return ariaLabel(args[0]);
      case 'chipOperator': return chipOperator(args[0], args[1]);
      case 'filterInput': return filterInput(args[0]);
      case 'footerButton': return footerButton(args[0]);
      case 'srOnlyLabel': return srOnlyLabel(args[0]);
      case 'srOnlyReveal': return srOnlyReveal(args[0], args[1]);
      case 'textRun': return textRun(args[0]);
      case 'liveRegionReveal': return liveRegionReveal(args[0], args[1], args[2]);
      default: return null;
    }
  };
}