stimeo-ui 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4f40e999f04533e49b382f7a5165c17b2338e8d520c702c34523843c12eff4c
-  data.tar.gz: 2bd4c18004fd4f92998513dd6a0d51975c7f9fcbe452fcef89477eb3f87edd7b
+  metadata.gz: d5c989b2c56e2578e6c05c5e01c29e31cdba141e9a49110701ba4a40dc91198e
+  data.tar.gz: 6b123f7cad0a54ef52b13c525bb53cf2eb43f0cc09748ab0d8cbf7d738e1fca9
 SHA512:
-  metadata.gz: 06ed197e53937fa086971d86c22d66efa4aed0f2accf14000046711be6aa73c3f486671c3912264a4ce5ca7c6da97a9836d7fe79c1d3ce106e1b368e5013f0d1
-  data.tar.gz: e49c3e2ccbc075def36be9d4e926d167fa4714cb66710389ad983ad7725f86e91d525fddfbb809090b4af09bc0cdaed44541466cb57391db53566119613f8863
+  metadata.gz: b95db793fc2a866c4c099f98ca1a689a36b5f15419d6b89b1c2f6423f694e03421c68d1bf930c0920c6d8feeb0c554a430e03523367fdabfa24578769a922c9b
+  data.tar.gz: 06ee52f5e9a6a56c9fea57f9e2f291e58336228e17a5bc5685238be3d98e00718a81837eb4196ddd08a230006492cd5e23d950537285f1e088c6bb2767b4fc12

data/CHANGELOG.md

@@ -7,6 +7,163 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 While the version is `0.x`, the public API (the `stimeo--*` data attributes) may
 change between releases.
 
+## [0.4.0] - 2026-08-11
+
+The feedback and status components announce through the shared
+`stimeo--announcer` and survive Turbo caching and morphs. The Inspector reads the
+`data:` hashes Rails helpers render. Two public API entries were removed.
+
+### Removed
+
+- **Breaking** — sidebar: the `beforeCache` action. Delete
+  `data-action="turbo:before-cache@document->stimeo--sidebar#beforeCache"`; the
+  behavior is built in, and leaving it makes `stimeo check` report an unknown
+  action.
+- **Breaking** — empty-state: the `announce` boolean, and the `role="status"` /
+  `aria-live="polite"` it applied to the `empty` target. Use `announceText` /
+  `announceFilledText` instead.
+
+### Added
+
+- countdown, empty-state, frame-loading, meter, network-status, progress,
+  skeleton, spinner: `announceText`, plus `announceFilledText` /
+  `announceOnlineText` / `announceReadyText` where a component has two
+  transitions to report. Wording is yours and defaults to empty, and the page
+  needs a `stimeo--announcer` for any of it to be read.
+- spinner: `timeout`, with a `stimeo--spinner:timeout` event. Off by default.
+- stick-to-bottom: `pinOnConnect`. Off by default.
+- Inspector: Stimulus wiring in a Rails helper's literal `data:` hash is checked
+  like static attributes. Re-run `stimeo check` — it can report new diagnostics.
+
+### Changed
+
+- meter, progress: an `aria-valuetext` you authored is preserved across renders.
+- local-time, relative-time: the locale falls back to the nearest ancestor
+  carrying `lang`, not just the element's own and then the document's.
+- countdown: `data-state` is the source of truth for the run state; `autostart`
+  governs only markup that states none.
+
+### Fixed
+
+- Turbo caching and morphs across announcer, color-picker, countdown,
+  date-range-picker, frame-loading, local-time, meter, overflow-menu, progress,
+  range-slider, rating, relative-time, sidebar, spinner, step-indicator: the
+  page is rewound before the snapshot and repaints when values are swapped,
+  instead of restoring stuck state or leaving a stale reading.
+- network-status: transitions are actually announced.
+- countdown: resume steps by one unit, and a settled timer no longer re-emits
+  `complete` on reconnect.
+- step-indicator: runtime step changes re-derive the set, and a non-numeric
+  `current` falls back to the first step.
+- local-time: a `datetime` with a space separator (`2026-06-08 12:30`) parses.
+- relative-time: a malformed `locale` no longer throws.
+- skeleton, frame-loading: a repeated signal no longer restarts or stacks the
+  minimum-duration wait.
+- Empty, inverted, and non-numeric ranges floor to `0` across meter, progress,
+  slider, and range-slider.
+
+## [0.3.0] - 2026-08-09
+
+Minor release focused on consistent keyboard and selection behavior, resilient
+runtime DOM changes, and substantially stronger Inspector diagnostics. No
+controller, target, value, action, event, or package export was removed. The
+Inspector manifest advances from schema v5 to v8, so tools that read the raw
+manifest must accept the new schema and fields.
+
+### Upgrade notes
+
+- Run `stimeo check` against existing views before deploying. New structural
+  checks can report errors for incomplete optional target groups, missing
+  companion controllers, undeclared role-bearing targets, and invalid
+  cardinality. New ARIA checks can also add warnings without failing the command.
+- In RTL containers, horizontal arrow keys now follow logical inline direction
+  across composite widgets. LTR behavior is unchanged.
+- Slider, range-slider, and color-picker pointer/arrow mirroring remains opt-in:
+  set their new `logicalTrack` value only when the consuming CSS mirrors the
+  track in RTL.
+- calendar's `stimeo--calendar:monthchange` no longer fires while the grid
+  settles on its initial month, so code that ran from that first event must now
+  run once at initialization. Listeners that re-apply per-date `aria-disabled`
+  marks are the common case.
+
+### Added
+
+- breadcrumb: a public `update` action for reconciling collapsible state after
+  application-driven DOM changes.
+- tree-view: a public `toggle` action for explicitly expanding or collapsing an
+  item from application markup.
+- scrollspy: a `focusSection` value for opting into focus movement when a link
+  activates a section.
+- slider, range-slider, color-picker: the `logicalTrack` value described above.
+- Inspector schema v6-v8: conditional target requirements and the new
+  `missing-companion`, `undeclared-target`, `cardinality-violation`,
+  `forbidden-aria`, and `missing-conditional-target` diagnostics. Rules can now
+  depend on controller values, element/document conditions, contained targets,
+  and ARIA requirement severity.
+
+### Changed
+
+- accordion, carousel, calendar, combobox, command-palette, context-menu,
+  data-grid, date-range-picker, listbox, menu, menubar, multi-select,
+  navigation-menu, OTP, radio-group, roving, tabs, tags-input, time-picker,
+  toggle-group, toolbar, tree-view, and related horizontal controls now resolve
+  Left/Right behavior from the effective text direction. Sortable geometry also
+  follows logical inline direction.
+- Arrow-key handlers yield modified browser shortcuts, and composite handlers
+  yield events already consumed by a nested widget. IME composition continues to
+  take precedence over component shortcuts.
+- Selection widgets normalize controller-owned `aria-selected` state, preserve a
+  single active/selected item where the pattern requires one, and reconcile that
+  state when options are inserted, removed, or replaced at runtime.
+- menu and overflow-menu delegate item interaction from their containers, so
+  dynamically added items work without per-item actions. Existing action markup
+  remains compatible.
+- `aria-disabled="true"` items remain discoverable by composite keyboard
+  navigation while activation, expansion, and consumer actions are suppressed.
+- Outside pointer listeners for dismissible composites — click and context-menu
+  alike — run in the capture phase so nested application code cannot leave an
+  open layer stuck by stopping bubbling.
+- Inspector accessible-name diagnostics now follow ARIA's Required, Recommended,
+  and conditional levels instead of treating every role alike.
+
+### Fixed
+
+- combobox, command-palette, listbox, and multi-select no longer retain stale
+  active IDs, selection, chips, or hidden fields after Turbo morphs and runtime
+  target replacement. A disconnect/reconnect in the same task can no longer let
+  an old reconciliation microtask consume the fresh generation's pass.
+- breadcrumb fails open when its optional disclosure targets are incomplete and
+  restores items that leave the collapsible set instead of leaving them hidden.
+- menu, menubar, navigation-menu, overflow-menu, pagination, and tree-view now
+  recover focus consistently across empty lists, disabled fieldsets, hidden
+  ancestors, item banking, and runtime item removal.
+- toolbar restores its single tab stop when an enclosing `<fieldset>` is
+  re-enabled, so unlocking a form brings the group back into the Tab sequence.
+- multi-select keeps chip focus when the selection was made in an order other
+  than the option order. The chips are reconciled against the selected value set
+  rather than position by position, and their labels are paired by value.
+- overflow-menu measures items adopted from server-rendered overflow in the bar
+  rather than inside the closed menu, so an already-overflowed bar no longer
+  returns every item to the bar on first paint.
+- combobox commits a clicked option after its input target is removed instead of
+  throwing, matching the tolerance the popup already had for that state.
+- color-picker falls back to the per-channel range when a slider omits
+  `aria-valuemin` / `aria-valuemax`, instead of pinning the channel at zero.
+- calendar maintains exactly one roving tab stop while selection and available
+  days change.
+- calendar reports `monthchange` from the month it paints, so a malformed
+  `month` value can no longer put a raw non-`YYYY-MM` string in `detail.month`.
+  The report is driven by the repaint rather than by the `month` value, so a
+  fallback month moved by `selected` or by selecting a neighbouring month's cell
+  is announced as it happens instead of arriving on a later repaint. Re-applying
+  the same month, as a Turbo cache restore does, stays silent.
+- scrollspy re-evaluates links and sections after every supported entry path;
+  intersection-based controllers align fallback thresholds, hidden-layout
+  handling, and reduced-motion behavior.
+- `stimeo catalog --json` and large `stimeo check --json` reports are no longer
+  truncated when stdout is piped; the CLI now lets buffered output flush before
+  exiting, and the build audit exercises the real piped catalog.
+
 ## [0.2.1] - 2026-07-26
 
 Patch release from a review of the disclosure and layout components, plus a
@@ -234,6 +391,9 @@ Initial public alpha: 101 behavior-only, accessible Stimulus controllers driven
 by `data-*` attributes, shipping no CSS. Published to npm (with provenance) and
 RubyGems.
 
+[0.4.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.4.0
+[0.3.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.3.0
+[0.2.1]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.2.1
 [0.2.0]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.2.0
 [0.1.0-beta.3]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.3
 [0.1.0-beta.2]: https://github.com/taiyaky/stimeo-ui/releases/tag/v0.1.0-beta.2

data/dist/controllers/accordion_controller.js

@@ -1,5 +1,13 @@
 import { Controller } from '@hotwired/stimulus';
 
+// src/controllers/accordion_controller.ts
+
+// src/utils/arrow_step.ts
+function isReservedArrowChord(event, allow = []) {
+  if (!event.key.startsWith("Arrow")) return false;
+  return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
+}
+
 // src/controllers/accordion_controller.ts
 var AccordionController = class extends Controller {
   static targets = ["trigger", "panel"];
@@ -39,6 +47,8 @@ var AccordionController = class extends Controller {
    * `.focus()` lands on nothing and navigation appears to stall.
    */
   onKeydown(event) {
+    if (event.defaultPrevented) return;
+    if (isReservedArrowChord(event)) return;
     const current = event.currentTarget;
     if (this.triggerTargets.indexOf(current) === -1) return;
     const navigable = this.triggerTargets.filter((trigger) => trigger.closest("[hidden]") === null);

data/dist/controllers/alert_dialog_controller.js

@@ -2,6 +2,35 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/alert_dialog_controller.ts
 
+// 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/escape_layer.ts
 var EscapeLayer = class _EscapeLayer {
   static #registries = /* @__PURE__ */ new WeakMap();
@@ -135,7 +164,7 @@ var FocusTrap = class {
     }
     if (this.#flag(this.#options.isolate, true)) this.#isolateBackground();
     document.addEventListener("keydown", this.#onKeydown);
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     const onEscape = this.#options.onEscape;
     if (onEscape) this.#escapeLayer.activate(document, { onDismiss: () => onEscape() });
     if (this.#flag(this.#options.autoFocus, true)) this.#focusInitial();
@@ -152,7 +181,7 @@ var FocusTrap = class {
     this.#activeState = false;
     this.#escapeLayer.deactivate();
     document.removeEventListener("keydown", this.#onKeydown);
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     if (this.#scrollLocked) {
       document.body.style.overflow = this.#previousBodyOverflow;
       this.#scrollLocked = false;
@@ -176,9 +205,7 @@ var FocusTrap = class {
    * untouched (restore-open designs reopen against a clean baseline), and focus
    * is left alone mid-navigation. The listener lives only while active.
    */
-  #onBeforeCache = () => {
-    this.deactivate({ restoreFocus: false });
-  };
+  #beforeCache = new BeforeCacheReset(() => this.deactivate({ restoreFocus: false }));
   /**
    * Handles `Tab` (focus trap) while active. `Escape` dismissal is owned by the
    * shared {@link EscapeLayer} resolver, so Tab trapping stays independent of

data/dist/controllers/announcer_controller.js

@@ -2,6 +2,68 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/announcer_controller.ts
 
+// 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/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/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -56,6 +118,7 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/announcer_controller.ts
+var LEVELS = ["polite", "assertive"];
 var AnnouncerController = class extends Controller {
   static targets = ["polite", "assertive"];
   static values = {
@@ -67,6 +130,30 @@ var AnnouncerController = class extends Controller {
   #timers = new SafeTimeout();
   /** Live regions generated to stand in for absent targets, for teardown. */
   #generated = /* @__PURE__ */ new Map();
+  /** Messages waiting to be written, oldest first, one queue per politeness. */
+  #queues = /* @__PURE__ */ new Map();
+  /** Politeness levels whose next drain is already armed. */
+  #draining = /* @__PURE__ */ new Set();
+  /** Collapses a batch of target callbacks (and morph removals) into one pass. */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileRegions());
+  /**
+   * Watches the host's own children for a generated region disappearing. A morph
+   * drops it — the server's HTML never had it — and no target callback reports
+   * that, because a generated region carries no target attribute. `subtree` stays
+   * off so writing a message inside a region does not re-enter this pass.
+   */
+  #hostWatch = new MutationObserver(() => {
+    this.#reconcile.schedule();
+  });
+  /** Rewinds to an announceable initial state for the snapshot; see the remarks. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  /**
+   * The one timer a region may have outstanding — its dedupe re-set, then its
+   * auto-clear. Held weakly so a swapped-out target is not retained; a leftover
+   * id is harmless because {@link SafeTimeout.clear} no-ops on an id it does not
+   * own.
+   */
+  #pending = /* @__PURE__ */ new WeakMap();
   /**
    * Guards against handling the same CustomEvent twice. An event dispatched on
    * the controller element with `bubbles: true` reaches both the element and the
@@ -83,13 +170,86 @@ var AnnouncerController = class extends Controller {
     this.#announce(message, this.#assertiveFromDetail(detail));
   };
   connect() {
+    this.#reconcile.activate();
+    this.#beforeCache.activate();
+    this.#reconcileRegions();
+    this.#hostWatch.observe(this.element, { childList: true });
     this.element.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     window.addEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
   }
   disconnect() {
+    this.#reconcile.cancel();
+    this.#hostWatch.disconnect();
+    this.#beforeCache.deactivate();
     this.element.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     window.removeEventListener("stimeo--announcer:announce", this.#onAnnounceEvent);
     this.#timers.clearAll();
+    this.#queues.clear();
+    this.#draining.clear();
+    this.#removeGenerated();
+  }
+  /** Retires the stand-in once the consumer supplies a polite region. */
+  politeTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Materialises a stand-in once the consumer's polite region goes away. */
+  politeTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /** Retires the stand-in once the consumer supplies an assertive region. */
+  assertiveTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Materialises a stand-in once the consumer's assertive region goes away. */
+  assertiveTargetDisconnected() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Brings the region set back to exactly one region per politeness and reports
+   * whether anything had to be created.
+   *
+   * A region created here is not written to in the same task: assistive tech
+   * reports changes to regions it already knows about, so {@link drain} waits a
+   * task whenever this says a region is new.
+   */
+  #reconcileRegions() {
+    let created = false;
+    for (const level of LEVELS) {
+      if (this.#hasTargetFor(level)) {
+        const generated = this.#generated.get(level);
+        if (generated) {
+          generated.remove();
+          this.#generated.delete(level);
+        }
+        continue;
+      }
+      const existing = this.#generated.get(level);
+      if (existing?.isConnected) continue;
+      this.#generated.set(level, this.#createRegion(level));
+      created = true;
+    }
+    return created;
+  }
+  /** Whether the consumer supplied a target for `level`. */
+  #hasTargetFor(level) {
+    return level === "assertive" ? this.hasAssertiveTarget : this.hasPoliteTarget;
+  }
+  /** Builds a visually hidden live region for `level` and attaches it. */
+  #createRegion(level) {
+    const region = document.createElement("div");
+    region.setAttribute("aria-live", level);
+    region.setAttribute("aria-atomic", "true");
+    visuallyHide(region);
+    this.element.appendChild(region);
+    return region;
+  }
+  /**
+   * Removes and forgets every region this controller generated. Authored targets
+   * belong to the consumer and are left untouched. Forgetting them is what keeps
+   * the live page working after a snapshot rewind: the next announcement finds an
+   * empty map and materialises a fresh region.
+   */
+  #removeGenerated() {
     for (const region of this.#generated.values()) {
       region.remove();
     }
@@ -111,47 +271,122 @@ var AnnouncerController = class extends Controller {
     this.#announce(message, assertive);
   }
   /**
-   * Writes `message` into the matching live region and schedules its clear.
+   * Queues `message` for its politeness and arms the drain.
    *
-   * When the region already holds the same text, an aria-atomic region is not
-   * re-read by assistive tech (the node did not change). If `dedupeReannounce`
-   * is on, the text is cleared and re-set on a later task so the mutation is
-   * observed and announced again.
+   * Queuing is what makes a burst audible: assistive tech announces the changes it
+   * observes, so several messages written into one region within a single task are
+   * one change and only the last is read.
    */
   #announce(message, assertive) {
-    const region = this.#regionFor(assertive ? "assertive" : "polite");
+    const level = assertive ? "assertive" : "polite";
+    const queue = this.#queues.get(level);
+    if (queue) {
+      queue.push(message);
+    } else {
+      this.#queues.set(level, [message]);
+    }
+    this.#scheduleDrain(level);
+  }
+  /** Arms one drain pass for `level`; further messages ride the pass already armed. */
+  #scheduleDrain(level) {
+    if (this.#draining.has(level)) return;
+    this.#draining.add(level);
+    this.#timers.set(() => {
+      this.#draining.delete(level);
+      this.#drain(level);
+    }, 0);
+  }
+  /**
+   * Writes one queued message, then arms the next pass while the queue holds more.
+   *
+   * Two steps take a whole pass without consuming the message: materialising a
+   * region (it has to be in the accessibility tree before the text arrives) and
+   * emptying a region that already holds this exact text (an unchanged node is not
+   * re-read, so `dedupeReannounce` clears first and writes on the following pass).
+   */
+  #drain(level) {
+    const queue = this.#queues.get(level);
+    const message = queue?.[0];
+    if (queue === void 0 || message === void 0) return;
+    if (this.#reconcileRegions()) {
+      this.#scheduleDrain(level);
+      return;
+    }
+    const region = this.#regionFor(level);
     if (this.dedupeReannounceValue && region.textContent === message) {
+      this.#cancelPending(region);
       region.textContent = "";
-      this.#timers.set(() => {
-        region.textContent = message;
-        this.#scheduleClear(region, message);
-      }, 0);
+      this.#scheduleDrain(level);
       return;
     }
+    queue.shift();
+    this.#cancelPending(region);
     region.textContent = message;
     this.#scheduleClear(region, message);
+    if (queue.length > 0) this.#scheduleDrain(level);
   }
   /** Clears the region after `clearAfter` ms, unless a newer message replaced it. */
   #scheduleClear(region, message) {
     if (this.clearAfterValue <= 0) return;
-    this.#timers.set(() => {
-      if (region.textContent === message) region.textContent = "";
-    }, this.clearAfterValue);
+    this.#schedule(
+      region,
+      () => {
+        if (region.textContent === message) region.textContent = "";
+      },
+      this.clearAfterValue
+    );
   }
-  /** Resolves the live region for a politeness level, generating it if absent. */
+  /**
+   * Arms `region`'s single pending timer. Callers reach here with the slot
+   * already free — `#announce` releases it, and a fired timer clears its own
+   * entry below — so this does not cancel again.
+   */
+  #schedule(region, callback, delay) {
+    const id = this.#timers.set(() => {
+      this.#pending.delete(region);
+      callback();
+    }, delay);
+    this.#pending.set(region, id);
+  }
+  /** Releases `region`'s pending timer, if it has one. */
+  #cancelPending(region) {
+    this.#timers.clear(this.#pending.get(region) ?? -1);
+    this.#pending.delete(region);
+  }
+  /**
+   * Resolves the live region for a politeness level.
+   *
+   * The remembered stand-in is used only while it is still in the document: a morph
+   * can drop it, and writing into the detached node would announce nothing at all.
+   */
   #regionFor(level) {
     if (level === "assertive" && this.hasAssertiveTarget) return this.assertiveTarget;
     if (level === "polite" && this.hasPoliteTarget) return this.politeTarget;
     const existing = this.#generated.get(level);
-    if (existing) return existing;
-    const region = document.createElement("div");
-    region.setAttribute("aria-live", level);
-    region.setAttribute("aria-atomic", "true");
-    visuallyHide(region);
-    this.element.appendChild(region);
+    if (existing?.isConnected) return existing;
+    const region = this.#createRegion(level);
     this.#generated.set(level, region);
     return region;
   }
+  /**
+   * Restores the announceable initial state for the snapshot Turbo is about to
+   * take: queued and displayed messages go, generated regions go, and the live
+   * page — which keeps running when a visit is aborted — gets its regions back on
+   * the next task, after the clone.
+   */
+  #rewindForCache() {
+    this.#queues.clear();
+    this.#draining.clear();
+    this.#timers.clearAll();
+    for (const level of LEVELS) {
+      if (this.#hasTargetFor(level)) {
+        const target = level === "assertive" ? this.assertiveTarget : this.politeTarget;
+        target.textContent = "";
+      }
+    }
+    this.#removeGenerated();
+    this.#timers.set(() => this.#reconcileRegions(), 0);
+  }
   /** Extracts a non-empty string `message` from a CustomEvent detail, else null. */
   #messageFromDetail(detail) {
     if (detail && typeof detail === "object" && "message" in detail) {