stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/scroll_area_controller.js

@@ -2,6 +2,154 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/scroll_area_controller.ts
 
+// src/utils/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    this.#reflect(element, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const stillOwned = element.getAttribute(this.#attribute) === record.written;
+    if (stillOwned) this.#reflect(element, record.original);
+  }
+  /** Reflects only a real value transition, avoiding self-triggered mutation work. */
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+function canTakeFocus(element) {
+  if (element.closest("[hidden], [inert]")) return false;
+  if (element instanceof HTMLInputElement && element.type === "hidden") return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+var TAB_STOP_CANDIDATE_SELECTOR = [
+  "a[href]",
+  "area[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "summary",
+  "iframe",
+  "audio[controls]",
+  "video[controls]",
+  "[tabindex]",
+  "[contenteditable]"
+].join(",");
+function isRenderedForFocus(element) {
+  const check = element.checkVisibility;
+  return typeof check === "function" ? check.call(element, { visibilityProperty: true }) : true;
+}
+function authoredTabindex(element) {
+  const value = element.getAttribute("tabindex");
+  if (value === null || !/^[+-]?\d+$/.test(value.trim())) return null;
+  return Number(value);
+}
+function hasNativeTabStop(element) {
+  if (element instanceof HTMLAnchorElement || element instanceof HTMLAreaElement) {
+    return element.hasAttribute("href");
+  }
+  if (element instanceof HTMLButtonElement || element instanceof HTMLSelectElement || element instanceof HTMLTextAreaElement) {
+    return true;
+  }
+  if (element instanceof HTMLInputElement) return element.type !== "hidden";
+  if (element instanceof HTMLIFrameElement) return true;
+  if (element.tagName === "AUDIO" || element.tagName === "VIDEO") {
+    return element.hasAttribute("controls");
+  }
+  if (element instanceof HTMLElement && element.tagName === "SUMMARY") {
+    const details = element.parentElement;
+    return details instanceof HTMLDetailsElement && Array.from(details.children).find((child) => child.tagName === "SUMMARY") === element;
+  }
+  return false;
+}
+function hasEditableTabStop(element) {
+  const value = element.getAttribute("contenteditable")?.toLowerCase();
+  return value === "" || value === "true" || value === "plaintext-only";
+}
+function isTabStop(element) {
+  if (!canTakeFocus(element) || !isRenderedForFocus(element)) return false;
+  const tabindex = authoredTabindex(element);
+  if (tabindex !== null) return tabindex >= 0;
+  return hasNativeTabStop(element) || hasEditableTabStop(element);
+}
+function firstTabStop(root) {
+  for (const candidate of root.querySelectorAll(TAB_STOP_CANDIDATE_SELECTOR)) {
+    if (isTabStop(candidate)) return candidate;
+  }
+  return null;
+}
+function hasTabStop(root) {
+  return firstTabStop(root) !== null;
+}
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -72,10 +220,97 @@ function logicalScrollMetrics(element, horizontal) {
   return { position: Math.min(max, Math.max(0, position)), max };
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+// src/utils/style_property_lease.ts
+var StylePropertyLease = class {
+  #property;
+  #records = /* @__PURE__ */ new Map();
+  /** @param property - The CSS property whose temporary values this lease owns. */
+  constructor(property) {
+    this.#property = property;
+  }
+  /** Writes or removes the leased declaration while preserving its authored value. */
+  write(element, value, priority = "") {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.writtenValue = value;
+      existing.writtenPriority = value === null ? "" : priority;
+    } else {
+      this.#records.set(element, {
+        originalValue: element.style.getPropertyValue(this.#property),
+        originalPriority: element.style.getPropertyPriority(this.#property),
+        writtenValue: value,
+        writtenPriority: value === null ? "" : priority
+      });
+    }
+    this.#reflect(element, value, priority);
+  }
+  /** Returns one lease without overwriting a later consumer declaration. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const style = element.style;
+    const stillOwned = style.getPropertyValue(this.#property) === (record.writtenValue ?? "") && style.getPropertyPriority(this.#property) === record.writtenPriority;
+    if (stillOwned) {
+      this.#reflect(element, record.originalValue, record.originalPriority);
+    }
+  }
+  /** Returns every outstanding declaration lease. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+  /** Reflects only a real declaration transition. */
+  #reflect(element, value, priority) {
+    const style = element.style;
+    const nextValue = value ?? "";
+    const nextPriority = value === null ? "" : priority;
+    if (style.getPropertyValue(this.#property) === nextValue && style.getPropertyPriority(this.#property) === nextPriority) {
+      return;
+    }
+    if (value === null) style.removeProperty(this.#property);
+    else style.setProperty(this.#property, value, priority);
+  }
+};
+
 // src/utils/tabindex_loan.ts
 var TabindexLoan = class {
   #value;
   #lent = /* @__PURE__ */ new Set();
+  /** Returns live loans before Turbo can copy them into its page snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.returnAll());
   /**
    * @param value - the `tabindex` to lend. `"-1"` (the default) is
    *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
@@ -89,6 +324,7 @@ var TabindexLoan = class {
     if (element.hasAttribute("tabindex")) return;
     element.setAttribute("tabindex", this.#value);
     this.#lent.add(element);
+    this.#beforeCache.activate();
   }
   /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
@@ -96,19 +332,11 @@ var TabindexLoan = class {
       if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
     }
     this.#lent.clear();
+    this.#beforeCache.deactivate();
   }
 };
 
 // src/controllers/scroll_area_controller.ts
-var FOCUSABLE_SELECTOR = [
-  "a[href]",
-  "button:not([disabled])",
-  "input:not([disabled])",
-  "select:not([disabled])",
-  "textarea:not([disabled])",
-  "[tabindex]:not([tabindex='-1'])",
-  "[contenteditable='true']"
-].join(",");
 var EDGE_EPSILON = 1;
 var ScrollAreaController = class extends Controller {
   static targets = ["viewport"];
@@ -116,152 +344,356 @@ var ScrollAreaController = class extends Controller {
     orientation: { type: String, default: "vertical" }
   };
   static events = ["reach"];
-  #layout = new LayoutObserver(() => this.#update());
-  /** Re-checks the tab stop when the viewport's focusable content comes or goes. */
+  #layout = new LayoutObserver(() => this.#refresh());
+  #rebind = new MicrotaskCoalescer(() => this.#syncViewport());
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #tabindex = new TabindexLoan("0");
+  #role = new AttributeLease("role");
+  #overflowState = new AttributeLease("data-overflow");
+  #scrollState = new AttributeLease("data-scroll");
+  #progress = new StylePropertyLease("--stimeo--scroll-progress");
+  #viewport = null;
   #content = null;
-  /** Last edge reported via `reach`, so the event fires once per arrival. */
+  #nameSources = null;
+  #nameGraph = null;
+  #observedNameIds = /* @__PURE__ */ new Set();
+  #observedNameSources = [];
+  #fonts = null;
+  #scrollFrame = null;
+  #overflowing = false;
   #lastEdge = null;
-  /** Whether this controller added `tabindex`, so teardown only removes its own. */
-  #tabindex = new TabindexLoan("0");
-  /** Whether this controller added `role="region"`, for symmetric teardown. */
-  #addedRole = false;
+  #ownedHostMutations = /* @__PURE__ */ new Map();
   #onScroll = () => {
-    this.#update();
+    if (this.#scrollFrame !== null) return;
+    this.#scrollFrame = requestAnimationFrame(() => {
+      this.#scrollFrame = null;
+      const viewport = this.#viewport;
+      if (viewport) this.#syncPosition(viewport, this.#overflowing);
+    });
+  };
+  #onLoad = () => {
+    this.#refresh();
+  };
+  #onFontsSettled = () => {
+    this.#refresh();
   };
   connect() {
-    if (!this.hasViewportTarget) return;
-    this.viewportTarget.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.#layout.observe(this.viewportTarget);
+    this.#beforeCache.activate();
+    this.#rebind.activate();
     this.#layout.observeViewport();
-    if (typeof MutationObserver !== "undefined") {
-      this.#content = new MutationObserver(() => {
-        if (!this.hasViewportTarget) return;
-        const vp = this.viewportTarget;
-        this.#syncKeyboardReach(vp, this.#syncOverflow(vp));
-      });
-      this.#content.observe(this.viewportTarget, {
-        subtree: true,
-        childList: true,
-        attributes: true
-      });
-    }
-    this.#update();
+    this.#bindFonts();
+    this.#syncViewport();
   }
   disconnect() {
-    if (this.hasViewportTarget) {
-      this.viewportTarget.removeEventListener("scroll", this.#onScroll);
-      this.#clearAddedAttributes(this.viewportTarget);
-    }
+    this.#beforeCache.deactivate();
+    this.#rebind.cancel();
+    this.#cancelScrollFrame();
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
     this.#layout.disconnect();
+    this.#unbindFonts();
+    this.#clearHostState();
+  }
+  /** Re-measures when a retained viewport's orientation Value is morphed. */
+  orientationValueChanged() {
+    this.#refresh();
+  }
+  /** Schedules a complete resource rebind for a runtime viewport target. */
+  viewportTargetConnected() {
+    this.#rebind.schedule();
+  }
+  /** Schedules cleanup or replacement binding after a viewport leaves. */
+  viewportTargetDisconnected() {
+    this.#rebind.schedule();
+  }
+  /** Rebinds every viewport-owned resource against the final target in the mutation batch. */
+  #syncViewport() {
+    const next = this.hasViewportTarget ? this.viewportTarget : null;
+    if (next === this.#viewport) {
+      if (next) this.#refresh();
+      else this.#clearHostState();
+      return;
+    }
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
+    this.#viewport = next;
+    if (!next) {
+      this.#clearHostState();
+      return;
+    }
+    next.addEventListener("scroll", this.#onScroll, { passive: true });
+    next.addEventListener("load", this.#onLoad, true);
+    this.#layout.observe(next);
+    this.#bindContentObserver(next);
+    this.#refresh();
+  }
+  /** Observes structural and attribute changes that can alter overflow or Tab stops. */
+  #bindContentObserver(viewport) {
+    this.#content = new MutationObserver((records) => {
+      if (this.#viewport !== viewport || !this.#hasRelevantContentMutation(records)) return;
+      this.#refresh();
+    });
+    this.#content.observe(viewport, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      characterData: true
+    });
+  }
+  /** Ignores only state-hook mutations whose exact value this controller just wrote. */
+  #hasRelevantContentMutation(records) {
+    let relevant = false;
+    const consumed = /* @__PURE__ */ new Set();
+    for (const record of records) {
+      const attribute = record.attributeName;
+      if (record.type === "attributes" && record.target === this.element && attribute !== null && this.#ownedHostMutations.has(attribute) && this.element.getAttribute(attribute) === this.#ownedHostMutations.get(attribute)) {
+        consumed.add(attribute);
+      } else {
+        relevant = true;
+      }
+    }
+    for (const attribute of consumed) this.#ownedHostMutations.delete(attribute);
+    return relevant;
+  }
+  /** Releases every resource and borrowed attribute owned by one former viewport. */
+  #unbindViewport(viewport) {
+    this.#cancelScrollFrame();
+    viewport.removeEventListener("scroll", this.#onScroll);
+    viewport.removeEventListener("load", this.#onLoad, true);
+    this.#layout.unobserve(viewport);
     this.#content?.disconnect();
     this.#content = null;
+    this.#disconnectNameSources();
+    this.#clearViewportAttributes(viewport);
+    this.#ownedHostMutations.clear();
+    this.#viewport = null;
+    this.#overflowing = false;
     this.#lastEdge = null;
   }
-  /** Re-measures overflow and scroll position and reflects the state hooks. */
-  #update() {
-    if (!this.hasViewportTarget) return;
-    const vp = this.viewportTarget;
-    const overflowing = this.#syncOverflow(vp);
-    this.#syncKeyboardReach(vp, overflowing);
-    const { position, progress } = this.#measurePosition(vp);
-    this.element.setAttribute("data-scroll", position);
-    this.element.style.setProperty("--stimeo--scroll-progress", String(progress));
-    const edge = position === "start" ? "start" : position === "end" ? "end" : null;
-    if (overflowing && edge && edge !== this.#lastEdge) {
-      this.#lastEdge = edge;
-      this.dispatch("reach", { detail: { edge } });
-    } else if (!edge) {
-      this.#lastEdge = null;
-    }
+  /** Runs the full structural and positional measurement pass. */
+  #refresh() {
+    const viewport = this.#viewport;
+    if (!viewport) return;
+    this.#cancelScrollFrame();
+    this.#syncNameSources(viewport);
+    this.#overflowing = this.#syncOverflow(viewport);
+    this.#syncKeyboardReach(viewport, this.#overflowing);
+    this.#syncPosition(viewport, this.#overflowing);
   }
-  /** Whether the viewport can scroll on the configured axis. */
-  /**
-   * Measures overflow and reflects the `data-overflow` hook.
-   *
-   * The write is skipped when the value is unchanged. An identical `setAttribute` still
-   * queues a MutationRecord, and markup that puts the viewport target on the controller
-   * element itself would then have the content observer trigger its own next callback.
-   */
-  #syncOverflow(vp) {
-    const overflowing = this.#measureOverflow(vp);
-    const next = overflowing ? "true" : "false";
-    if (this.element.getAttribute("data-overflow") !== next) {
-      this.element.setAttribute("data-overflow", next);
-    }
+  /** Measures overflow and reflects the state hook without identical DOM writes. */
+  #syncOverflow(viewport) {
+    const overflowing = this.#measureOverflow(viewport);
+    this.#writeHostAttribute(this.#overflowState, "data-overflow", overflowing ? "true" : "false");
     return overflowing;
   }
-  #measureOverflow(vp) {
-    const o = this.orientationValue;
-    const vertical = o !== "horizontal" && vp.scrollHeight > vp.clientHeight + EDGE_EPSILON;
-    const horizontal = o !== "vertical" && vp.scrollWidth > vp.clientWidth + EDGE_EPSILON;
+  /** Measures the primary-axis position and dispatches a newly established edge. */
+  #syncPosition(viewport, overflowing) {
+    const { position, progress } = this.#measurePosition(viewport);
+    this.#writeHostAttribute(this.#scrollState, "data-scroll", position);
+    this.#writeHostProgress(String(progress));
+    const edge = overflowing && (position === "start" || position === "end") ? position : null;
+    if (edge === this.#lastEdge) return;
+    this.#lastEdge = edge;
+    if (edge) this.dispatch("reach", { detail: { edge } });
+  }
+  /** Writes one leased host attribute and records self-generated observer input. */
+  #writeHostAttribute(lease, attribute, value) {
+    const before = this.element.getAttribute(attribute);
+    lease.write(this.element, value);
+    this.#recordOwnedHostMutation(attribute, before);
+  }
+  /** Writes the leased progress property and records its serialized style mutation. */
+  #writeHostProgress(value) {
+    const before = this.element.getAttribute("style");
+    this.#progress.write(this.element, value);
+    this.#recordOwnedHostMutation("style", before);
+  }
+  /** Records an exact host mutation only when the host is also the observed viewport. */
+  #recordOwnedHostMutation(attribute, before) {
+    if (this.#viewport !== this.element) return;
+    const after = this.element.getAttribute(attribute);
+    if (after !== before) this.#ownedHostMutations.set(attribute, after);
+  }
+  /** Returns host hooks to authored values and clears edge bookkeeping. */
+  #clearHostState() {
+    this.#overflowState.returnAll();
+    this.#scrollState.returnAll();
+    this.#progress.returnAll();
+    this.#ownedHostMutations.clear();
+    this.#overflowing = false;
+    this.#lastEdge = null;
+  }
+  /** Whether the configured axis currently has a scroll range. */
+  #measureOverflow(viewport) {
+    const orientation = this.orientationValue;
+    const vertical = orientation !== "horizontal" && viewport.scrollHeight > viewport.clientHeight + EDGE_EPSILON;
+    const horizontal = orientation !== "vertical" && viewport.scrollWidth > viewport.clientWidth + EDGE_EPSILON;
     return vertical || horizontal;
   }
-  /**
-   * Reports the scroll position bucket and 0–1 progress on the primary axis. For
-   * `both`, the vertical axis is used when it overflows, otherwise the horizontal.
-   */
-  #measurePosition(vp) {
-    const horizontalPrimary = this.orientationValue === "horizontal" || this.orientationValue === "both" && vp.scrollHeight <= vp.clientHeight + EDGE_EPSILON;
-    const { position: scrollPos, max: maxScroll } = logicalScrollMetrics(vp, horizontalPrimary);
+  /** Reports the primary-axis position bucket and normalized 0–1 progress. */
+  #measurePosition(viewport) {
+    const horizontalPrimary = this.orientationValue === "horizontal" || this.orientationValue === "both" && viewport.scrollHeight <= viewport.clientHeight + EDGE_EPSILON;
+    const { position: scrollPosition, max: maxScroll } = logicalScrollMetrics(
+      viewport,
+      horizontalPrimary
+    );
     if (maxScroll <= EDGE_EPSILON) return { position: "start", progress: 0 };
-    const progress = Math.min(1, Math.max(0, scrollPos / maxScroll));
-    if (scrollPos <= EDGE_EPSILON) return { position: "start", progress };
-    if (scrollPos >= maxScroll - EDGE_EPSILON) return { position: "end", progress };
+    const progress = Math.min(1, Math.max(0, scrollPosition / maxScroll));
+    if (scrollPosition <= EDGE_EPSILON) return { position: "start", progress };
+    if (scrollPosition >= maxScroll - EDGE_EPSILON) return { position: "end", progress };
     return { position: "middle", progress };
   }
-  /**
-   * Makes the viewport keyboard-scrollable when it overflows and contains no
-   * focusable elements of its own (avoiding a double tab stop). Adds `role="region"`
-   * only when the viewport already carries an accessible name.
-   */
-  #syncKeyboardReach(vp, overflowing) {
-    const wantsTabindex = overflowing && !this.#hasFocusableContent(vp);
-    if (wantsTabindex) {
-      this.#tabindex.lend(vp);
-      if (!vp.hasAttribute("role") && this.#hasAccessibleName(vp)) {
-        vp.setAttribute("role", "region");
-        this.#addedRole = true;
-      }
+  /** Borrows keyboard reach only when no usable descendant already owns a Tab stop. */
+  #syncKeyboardReach(viewport, overflowing) {
+    const wantsTabindex = overflowing && !hasTabStop(viewport);
+    if (!wantsTabindex) {
+      this.#clearViewportAttributes(viewport);
+      return;
+    }
+    this.#tabindex.lend(viewport);
+    if (this.#hasAccessibleName(viewport)) {
+      if (!viewport.hasAttribute("role")) this.#role.write(viewport, "region");
     } else {
-      this.#clearAddedAttributes(vp);
+      this.#role.return(viewport);
     }
   }
-  /** Removes (and resets the flags for) only the attributes this controller added. */
-  #clearAddedAttributes(vp) {
+  /** Returns only the viewport attributes borrowed by this controller. */
+  #clearViewportAttributes(viewport) {
     this.#tabindex.returnAll();
-    if (this.#addedRole) {
-      vp.removeAttribute("role");
-      this.#addedRole = false;
+    this.#role.return(viewport);
+  }
+  /** Whether the viewport already has a non-empty accessible name. */
+  #hasAccessibleName(viewport) {
+    const sources = this.#resolveNameSources(viewport);
+    if (sources.length > 0) {
+      return sources.some((source) => {
+        const label = source.getAttribute("aria-label")?.trim();
+        return Boolean(label || source.textContent?.trim());
+      });
     }
+    return Boolean(viewport.getAttribute("aria-label")?.trim());
   }
-  /**
-   * Whether the viewport owns something the user can Tab to *right now*.
-   *
-   * The selector alone is not enough: a `display: none` button still matches it,
-   * so a viewport whose only control is revealed on demand would never get a tab
-   * stop — leaving it unreachable by keyboard exactly while it has nothing else to
-   * offer. Only rendered candidates count.
-   */
-  #hasFocusableContent(vp) {
-    return Array.from(vp.querySelectorAll(FOCUSABLE_SELECTOR)).some(
-      (el) => this.#isRendered(el)
+  /** Resolves unique, live `aria-labelledby` references in authored order. */
+  #resolveNameSources(viewport) {
+    const ids = this.#nameReferenceIds(viewport);
+    const sources = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const id of ids) {
+      const source = viewport.ownerDocument.getElementById(id);
+      if (source && !seen.has(source)) {
+        seen.add(source);
+        sources.push(source);
+      }
+    }
+    return sources;
+  }
+  /** Observes external name sources so a retained region never becomes unnamed. */
+  #syncNameSources(viewport) {
+    const ids = this.#nameReferenceIds(viewport);
+    const sources = this.#resolveNameSources(viewport).filter(
+      (source) => !viewport.contains(source)
     );
+    if (ids.length === this.#observedNameIds.size && ids.every((id) => this.#observedNameIds.has(id)) && sources.length === this.#observedNameSources.length && sources.every((source, index) => source === this.#observedNameSources[index])) {
+      return;
+    }
+    this.#disconnectNameSources();
+    this.#observedNameIds = new Set(ids);
+    this.#observedNameSources = sources;
+    if (ids.length > 0) {
+      this.#nameGraph = new MutationObserver((records) => {
+        if (this.#viewport === viewport && this.#hasRelevantNameGraphMutation(records)) {
+          this.#refresh();
+        }
+      });
+      const documentElement = viewport.ownerDocument.documentElement;
+      if (documentElement) {
+        this.#nameGraph.observe(documentElement, {
+          subtree: true,
+          childList: true,
+          attributes: true,
+          attributeFilter: ["id"],
+          attributeOldValue: true
+        });
+      }
+    }
+    if (sources.length === 0) return;
+    this.#nameSources = new MutationObserver(() => {
+      this.#refresh();
+    });
+    for (const source of sources) {
+      this.#nameSources.observe(source, {
+        subtree: true,
+        childList: true,
+        characterData: true,
+        attributes: true
+      });
+    }
   }
-  /**
-   * Whether `el` is actually rendered, and so can hold focus.
-   *
-   * `checkVisibility()` answers this for every way CSS can remove a box, including
-   * a class-driven `display: none` that no attribute reveals. The `hidden` walk in
-   * front of it is not redundant: it is the one case a DOM-only environment with no
-   * layout engine has to be told about explicitly.
-   */
-  #isRendered(el) {
-    if (el.closest("[hidden]") !== null) return false;
-    const check = el.checkVisibility;
-    return typeof check === "function" ? check.call(el, { visibilityProperty: true }) : true;
+  /** Returns normalized unique label-reference ids in authored order. */
+  #nameReferenceIds(viewport) {
+    const tokens = viewport.getAttribute("aria-labelledby")?.trim().split(/\s+/).filter(Boolean);
+    return Array.from(new Set(tokens));
+  }
+  /** Whether document-graph changes can resolve or invalidate a referenced id. */
+  #hasRelevantNameGraphMutation(records) {
+    for (const record of records) {
+      if (record.type === "attributes") {
+        const current = record.target.id;
+        if (this.#observedNameIds.has(current) || this.#observedNameIds.has(record.oldValue ?? "")) {
+          return true;
+        }
+        continue;
+      }
+      for (const node of [...record.addedNodes, ...record.removedNodes]) {
+        if (this.#nodeContainsObservedNameId(node)) return true;
+      }
+    }
+    return false;
   }
-  #hasAccessibleName(vp) {
-    return vp.hasAttribute("aria-label") || vp.hasAttribute("aria-labelledby");
+  /** Whether a changed subtree contains one of the current label-reference ids. */
+  #nodeContainsObservedNameId(node) {
+    if (!(node instanceof Element)) return false;
+    if (this.#observedNameIds.has(node.id)) return true;
+    return Array.from(node.querySelectorAll("[id]")).some(
+      (element) => this.#observedNameIds.has(element.id)
+    );
+  }
+  /** Stops observing accessible-name sources. */
+  #disconnectNameSources() {
+    this.#nameSources?.disconnect();
+    this.#nameSources = null;
+    this.#nameGraph?.disconnect();
+    this.#nameGraph = null;
+    this.#observedNameIds.clear();
+    this.#observedNameSources = [];
+  }
+  /** Subscribes to font completion when the current engine exposes `document.fonts`. */
+  #bindFonts() {
+    const fonts = this.element.ownerDocument.fonts;
+    if (!fonts || this.#fonts === fonts) return;
+    this.#unbindFonts();
+    this.#fonts = fonts;
+    fonts.addEventListener("loadingdone", this.#onFontsSettled);
+    fonts.addEventListener("loadingerror", this.#onFontsSettled);
+  }
+  /** Removes the font completion subscriptions. */
+  #unbindFonts() {
+    this.#fonts?.removeEventListener("loadingdone", this.#onFontsSettled);
+    this.#fonts?.removeEventListener("loadingerror", this.#onFontsSettled);
+    this.#fonts = null;
+  }
+  /** Cancels a pending scroll frame. */
+  #cancelScrollFrame() {
+    if (this.#scrollFrame === null) return;
+    cancelAnimationFrame(this.#scrollFrame);
+    this.#scrollFrame = null;
+  }
+  /** Suspends live resources and returns all derived state before snapshotting. */
+  #rewindForCache() {
+    this.#rebind.cancel();
+    this.#cancelScrollFrame();
+    if (this.#viewport) this.#unbindViewport(this.#viewport);
+    this.#layout.disconnect();
+    this.#unbindFonts();
+    this.#clearHostState();
   }
 };