stimeo-ui 0.3.0 → 0.4.0

data/dist/index.js

@@ -110,6 +110,35 @@ var AccordionController = class extends Controller {
   }
 };
 
+// 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
 function claimsWhileFocusWithin(element) {
   return () => {
@@ -249,7 +278,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();
@@ -266,7 +295,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;
@@ -290,9 +319,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
@@ -427,6 +454,39 @@ var AlertDialogController = class extends Controller {
   }
 };
 
+// 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). */
@@ -495,6 +555,7 @@ var SafeInterval = class extends TimerRegistry {
 };
 
 // src/controllers/announcer_controller.ts
+var LEVELS = ["polite", "assertive"];
 var AnnouncerController = class extends Controller {
   static targets = ["polite", "assertive"];
   static values = {
@@ -506,6 +567,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
@@ -522,13 +607,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();
     }
@@ -550,47 +708,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
+    );
+  }
+  /**
+   * 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, generating it if absent. */
+  /**
+   * 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) {
@@ -2440,16 +2673,29 @@ var ColorPickerController = class extends Controller {
   /** Aborts in-progress pointer-drag listeners on drag end / teardown. */
   #dragAbort = null;
   /** Seeds the model from the initial hex value and renders every surface. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render();
+  });
   connect() {
+    this.#repaint.activate();
     const parsed = hexToHsla(this.valueValue);
     if (parsed) this.#color = this.alphaValue ? parsed : { ...parsed, alpha: 100 };
     this.#render();
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
+    this.#repaint.cancel();
     this.#dragAbort?.abort();
     this.#dragAbort = null;
   }
+  /** Repaints when application code (or a Turbo morph) changes `alpha` at runtime. */
+  alphaValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Keyboard stepping on the focused channel slider (APG Slider model). */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
@@ -2648,39 +2894,6 @@ function syncActiveOption(options, active) {
   return written;
 }
 
-// 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/option_scroll.ts
 function scrollOptionIntoView(list, option) {
   if (list.scrollHeight <= list.clientHeight) return;
@@ -3846,6 +4059,26 @@ var CountUpController = class extends Controller {
     this.element.removeAttribute("data-count-up-label");
   }
 };
+
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+function fillTemplate(template, values) {
+  return template.replace(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g, (match, name) => {
+    const replacement = values[name];
+    return replacement === void 0 ? match : String(replacement);
+  });
+}
+
+// src/controllers/countdown_controller.ts
+var SECOND_MS = 1e3;
 var CountdownController = class extends Controller {
   static targets = ["days", "hours", "minutes", "seconds", "status"];
   static values = {
@@ -3853,34 +4086,79 @@ var CountdownController = class extends Controller {
     interval: { type: Number, default: 1e3 },
     direction: { type: String, default: "down" },
     autostart: { type: Boolean, default: true },
-    completeLabel: { type: String, default: "" }
+    completeLabel: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
   static actions = ["pause", "reset", "resume", "start"];
   static events = ["complete", "tick"];
   #intervals = new SafeInterval();
   #intervalId = null;
+  /** Collapses a morph that swaps several render inputs at once into one re-derive. */
+  #resync = new MicrotaskCoalescer(() => this.#resyncToValues());
   /** Epoch-ms anchor: the deadline (down) or the count-up origin (up). */
   #reference = 0;
   /** Amount (ms) captured at pause, so resume can restore the same display. */
   #pausedAmount = 0;
+  /**
+   * The amount the slots are currently showing, floored to the second they render.
+   * It lags {@link currentAmount} by up to one tick, and it — not the live reading —
+   * is what a pause has to preserve: storing the fraction behind the display instead
+   * makes the first tick after a resume step by two units.
+   */
+  #renderedAmount = 0;
   connect() {
+    this.#resync.activate();
     this.#initReference();
-    this.#render(this.#currentAmount());
-    if (this.autostartValue && this.#isValidDeadline) {
-      this.start();
-    } else {
+    const amount = this.#currentAmount();
+    this.#render(amount);
+    this.#pausedAmount = this.#renderedAmount;
+    const authored = this.element.getAttribute("data-state");
+    if (authored === null) {
+      if (this.autostartValue && this.#isValidDeadline) {
+        this.start();
+        return;
+      }
       this.element.setAttribute("data-state", "paused");
+      return;
     }
+    if (authored === "complete" && this.#isDown && amount <= 0) {
+      return;
+    }
+    const wasRunning = authored === "running";
+    this.element.setAttribute("data-state", "paused");
+    if (wasRunning) this.start();
   }
   disconnect() {
+    this.#resync.cancel();
     this.#intervals.clearAll();
     this.#intervalId = null;
   }
+  /** Re-derives the display when a morph swaps the deadline in place. */
+  deadlineValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Re-derives the display when a morph flips the counting direction in place. */
+  directionValueChanged() {
+    this.#resync.schedule();
+  }
+  /**
+   * Points the anchor at the current `deadline` / `direction` and repaints.
+   *
+   * Render only: it starts no interval and emits no event, so a morph cannot make a
+   * paused timer run or replay a milestone. A running one needs no restart either —
+   * every tick reads the anchor, so moving it is enough. While paused the stored
+   * amount follows the new reading, or resume would continue from the old deadline.
+   */
+  #resyncToValues() {
+    this.#initReference();
+    this.#render(this.#currentAmount());
+    if (this.#state !== "running") this.#pausedAmount = this.#renderedAmount;
+  }
   /** Starts (or restarts after pause) ticking toward the deadline. */
   start() {
     if (this.#state === "running" || !this.#isValidDeadline) return;
     if (this.#isDown && this.#currentAmount() <= 0) {
-      this.#complete();
+      if (this.#state !== "complete") this.#complete();
       return;
     }
     this.#runInterval();
@@ -3888,7 +4166,7 @@ var CountdownController = class extends Controller {
   /** Pauses ticking, preserving the currently displayed amount. */
   pause() {
     if (this.#state !== "running") return;
-    this.#pausedAmount = this.#currentAmount();
+    this.#pausedAmount = this.#renderedAmount;
     this.#teardownInterval();
     this.element.setAttribute("data-state", "paused");
   }
@@ -3904,8 +4182,8 @@ var CountdownController = class extends Controller {
    * run state**: a running timer keeps counting down from the reset amount, while a
    * paused (or completed) one resets the displayed amount but stays paused until the
    * user resumes — it never silently restarts. The run state is read from the DOM,
-   * not re-derived from the declarative `autostart` Value (which only governs the
-   * initial state on connect); re-deriving it would override a user's pause —
+   * not re-derived from the declarative `autostart` Value (which governs only markup
+   * that states no run state at all); re-deriving it would override a user's pause —
    * the DOM, not a re-run of declarative config, is the source of truth.
    */
   reset() {
@@ -3914,13 +4192,15 @@ var CountdownController = class extends Controller {
     this.#initReference();
     const amount = this.#currentAmount();
     this.#render(amount);
-    if (this.hasStatusTarget) this.statusTarget.textContent = "";
+    if (this.hasStatusTarget && this.statusTarget.textContent === this.completeLabelValue) {
+      this.statusTarget.textContent = "";
+    }
     this.element.setAttribute("data-state", "paused");
     if (wasRunning && this.#isValidDeadline) {
       this.#pausedAmount = 0;
       this.start();
     } else {
-      this.#pausedAmount = amount;
+      this.#pausedAmount = this.#renderedAmount;
     }
   }
   /** Schedules the repeating tick and marks the timer running. */
@@ -3955,6 +4235,7 @@ var CountdownController = class extends Controller {
       this.statusTarget.textContent = this.completeLabelValue;
     }
     this.dispatch("complete", { detail: {} });
+    announce(fillTemplate(this.announceTextValue, {}));
   }
   /** Sets the time anchor from the `deadline` value. */
   #initReference() {
@@ -3969,7 +4250,8 @@ var CountdownController = class extends Controller {
   }
   /** Writes the amount into the day/hour/minute/second slots. */
   #render(amount) {
-    const totalSeconds = Math.floor(amount / 1e3);
+    const totalSeconds = Math.floor(amount / SECOND_MS);
+    this.#renderedAmount = totalSeconds * SECOND_MS;
     const days = Math.floor(totalSeconds / 86400);
     const hours = Math.floor(totalSeconds % 86400 / 3600);
     const minutes = Math.floor(totalSeconds % 3600 / 60);
@@ -4378,7 +4660,15 @@ var DateRangePickerController = class extends Controller {
   /** Deferred focus after an async month transition (cancelled on teardown). */
   #focusTimer = new SafeTimeout();
   /** Seeds the range from any pre-filled hidden fields and renders the grid. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render();
+  });
   connect() {
+    this.#repaint.activate();
     this.#startDate = this.hasStartFieldTarget ? normalizeISO(this.startFieldTarget.value) : "";
     this.#endDate = this.hasEndFieldTarget ? normalizeISO(this.endFieldTarget.value) : "";
     const anchor = parseISODateString(this.#startDate) ?? this.#clampToBounds(/* @__PURE__ */ new Date()) ?? /* @__PURE__ */ new Date();
@@ -4389,8 +4679,17 @@ var DateRangePickerController = class extends Controller {
   }
   /** Cancels any pending deferred focus so it never fires on a detached element. */
   disconnect() {
+    this.#repaint.cancel();
     this.#focusTimer.clearAll();
   }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Navigates to the previous month. */
   prev(event) {
     event?.preventDefault();
@@ -5483,7 +5782,8 @@ var EmptyStateController = class extends Controller {
   static targets = ["list", "empty"];
   static values = {
     itemSelector: { type: String, default: "" },
-    announce: { type: Boolean, default: false }
+    announceText: { type: String, default: "" },
+    announceFilledText: { type: String, default: "" }
   };
   static events = ["change"];
   #observer = null;
@@ -5491,10 +5791,6 @@ var EmptyStateController = class extends Controller {
   #empty = null;
   connect() {
     if (!this.hasListTarget) return;
-    if (this.announceValue && this.hasEmptyTarget && !this.#isLiveRegion(this.emptyTarget)) {
-      this.emptyTarget.setAttribute("role", "status");
-      this.emptyTarget.setAttribute("aria-live", "polite");
-    }
     if (typeof MutationObserver !== "undefined") {
       this.#observer = new MutationObserver(() => this.#apply());
       this.#observer.observe(this.listTarget, { childList: true });
@@ -5520,6 +5816,9 @@ var EmptyStateController = class extends Controller {
     if (this.hasEmptyTarget) this.emptyTarget.hidden = !empty;
     if (this.#empty !== null && empty !== this.#empty) {
       this.dispatch("change", { detail: { count, empty } });
+      announce(
+        fillTemplate(empty ? this.announceTextValue : this.announceFilledTextValue, { count })
+      );
     }
     this.#empty = empty;
   }
@@ -5533,11 +5832,6 @@ var EmptyStateController = class extends Controller {
       return this.listTarget.childElementCount;
     }
   }
-  #isLiveRegion(el) {
-    if (el.hasAttribute("aria-live")) return true;
-    const role = el.getAttribute("role");
-    return role === "status" || role === "alert";
-  }
 };
 var FileDropzoneController = class extends Controller {
   static targets = ["zone", "trigger", "input", "list", "item", "itemTemplate", "status"];
@@ -6362,35 +6656,130 @@ var FormValidationController = class _FormValidationController extends Controlle
     element.willValidate;
   }
 };
+
+// src/utils/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
+// src/utils/min_duration_floor.ts
+var MinDurationFloor = class {
+  #timers;
+  /** Pending finish timer id, or `null` when nothing is held back. */
+  #timerId = null;
+  /** Epoch ms the floor is measured from. */
+  #since = 0;
+  /** @param timers - the controller's registry; the floor schedules into it. */
+  constructor(timers) {
+    this.#timers = timers;
+  }
+  /** Starts the floor: call when the state being held becomes visible. */
+  begin() {
+    this.#since = Date.now();
+  }
+  /** True while a finish is held back waiting for the floor to elapse. */
+  get pending() {
+    return this.#timerId !== null;
+  }
+  /**
+   * Runs `finish` once the floor has elapsed, immediately when it already has.
+   *
+   * A held-back finish is **replaced**, never stacked: only the most recently
+   * queued id is cancellable, so a second timer would outlive every cancel and
+   * end a state that has since restarted. Controllers that want the first signal
+   * to win guard on {@link pending} before calling.
+   */
+  schedule(minDuration, finish) {
+    this.cancel();
+    const remaining = minDuration - (Date.now() - this.#since);
+    if (remaining > 0) {
+      this.#timerId = this.#timers.set(() => {
+        this.#timerId = null;
+        finish();
+      }, remaining);
+    } else {
+      finish();
+    }
+  }
+  /** Drops a held-back finish. Safe when none is queued, or after a bulk clear. */
+  cancel() {
+    if (this.#timerId !== null) {
+      this.#timers.clear(this.#timerId);
+      this.#timerId = null;
+    }
+  }
+};
+
+// src/controllers/frame_loading_controller.ts
 var FrameLoadingController = class extends Controller {
   static targets = ["content", "skeleton", "overlay"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceReadyText: { type: String, default: "" },
     minDuration: { type: Number, default: 0 },
     restoreFocus: { type: Boolean, default: true }
   };
   static events = ["start", "end"];
   #timeouts = new SafeTimeout();
+  #floor = new MinDurationFloor(this.#timeouts);
+  #gate = new DetachGate();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #loading = false;
-  #startedAt = 0;
   #inertApplied = false;
   #previousFocus = null;
   /** The id of the retreated element, used to re-find it if the load replaced it. */
   #previousFocusId = "";
   #onStart = () => {
-    this.#timeouts.clearAll();
+    this.#floor.cancel();
     if (!this.#loading) this.#begin();
   };
   #onEnd = () => {
     if (!this.#loading) return;
-    const remaining = this.minDurationValue - (Date.now() - this.#startedAt);
-    if (remaining > 0) {
-      this.#timeouts.clearAll();
-      this.#timeouts.set(() => this.#finish(), remaining);
-    } else {
-      this.#finish();
-    }
+    this.#floor.schedule(this.minDurationValue, () => this.#finish());
   };
   connect() {
+    this.#gate.cancel();
+    this.#beforeCache.activate();
     this.element.addEventListener("turbo:before-fetch-request", this.#onStart);
     this.element.addEventListener("turbo:frame-load", this.#onEnd);
     this.element.addEventListener("turbo:fetch-request-error", this.#onEnd);
@@ -6399,19 +6788,40 @@ var FrameLoadingController = class extends Controller {
     this.element.removeEventListener("turbo:before-fetch-request", this.#onStart);
     this.element.removeEventListener("turbo:frame-load", this.#onEnd);
     this.element.removeEventListener("turbo:fetch-request-error", this.#onEnd);
+    this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#teardown());
+  }
+  /**
+   * Drops the held finish and the loading bookkeeping on a real detach. The markup
+   * keeps whatever it last held: the page being cached is rewound at
+   * `turbo:before-cache` instead, where the frame is still whole.
+   */
+  #teardown() {
+    this.#gate.cancel();
     this.#timeouts.clearAll();
-    if (this.#loading) {
-      this.element.removeAttribute("aria-busy");
-      this.element.removeAttribute("data-frame-loading");
-      this.#clearInert();
-    }
+    this.#floor.cancel();
     this.#loading = false;
     this.#previousFocus = null;
   }
+  /**
+   * Returns the frame to its resting hooks for the snapshot Turbo is about to
+   * take, so a page reached with the Back button does not restore a frame that is
+   * busy and inert with nothing left to finish it. State only — no `end` event and
+   * no focus move, because the load did not actually complete. The live page keeps
+   * its held finish, so a navigation that never completes still ends properly.
+   */
+  #rewindForCache() {
+    if (!this.#loading) return;
+    this.element.removeAttribute("aria-busy");
+    this.element.removeAttribute("data-frame-loading");
+    if (this.hasSkeletonTarget) this.skeletonTarget.hidden = true;
+    if (this.hasOverlayTarget) this.overlayTarget.hidden = true;
+    this.#clearInert();
+  }
   /** Enters the loading state: hooks, skeleton/overlay, inert content, focus retreat. */
   #begin() {
     this.#loading = true;
-    this.#startedAt = Date.now();
+    this.#floor.begin();
     this.element.setAttribute("aria-busy", "true");
     this.element.setAttribute("data-frame-loading", "true");
     if (this.hasSkeletonTarget) this.skeletonTarget.hidden = false;
@@ -6419,6 +6829,7 @@ var FrameLoadingController = class extends Controller {
     this.#applyInert();
     this.#retreatFocus();
     this.dispatch("start", { detail: {} });
+    announce(fillTemplate(this.announceTextValue, {}));
   }
   /** Leaves the loading state: restore hooks, hide skeleton/overlay, restore focus. */
   #finish() {
@@ -6430,6 +6841,7 @@ var FrameLoadingController = class extends Controller {
     this.#clearInert();
     this.#restoreFocus();
     this.dispatch("end", { detail: {} });
+    announce(fillTemplate(this.announceReadyTextValue, {}));
   }
   /** Marks the content inert to block double-submits while stale (if we own it). */
   #applyInert() {
@@ -7535,7 +7947,53 @@ var LocalTimeController = class extends Controller {
     titleFormat: { type: String, default: "" }
   };
   static events = ["format"];
+  /** Collapses a morph that swaps several render inputs at once into one repaint. */
+  #resync = new MicrotaskCoalescer(() => this.#render());
+  /**
+   * Watches the one render input that is not a Value. Only `datetime` is filtered
+   * in, so the text and `title` this controller writes cannot re-enter the pass.
+   */
+  #datetimeWatch = new MutationObserver(() => {
+    this.#resync.schedule();
+  });
   connect() {
+    this.#resync.activate();
+    this.#datetimeWatch.observe(this.element, { attributeFilter: ["datetime"] });
+    this.#render();
+  }
+  disconnect() {
+    this.#resync.cancel();
+    this.#datetimeWatch.disconnect();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `locale` at runtime. */
+  localeValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `timeZone` at runtime. */
+  timeZoneValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `dateStyle` at runtime. */
+  dateStyleValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `timeStyle` at runtime. */
+  timeStyleValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `titleFormat` at runtime. */
+  titleFormatValueChanged() {
+    this.#resync.schedule();
+  }
+  /**
+   * Formats the instant in `datetime` against the current Values and writes it out.
+   *
+   * The `format` event rides with every pass, including a repaint a morph triggers:
+   * its condition is that formatting was applied, and a repaint applies it with a
+   * new result. A pass that cannot format writes nothing and emits nothing, so the
+   * authored absolute text stays as the fallback.
+   */
+  #render() {
     const date = this.#parse();
     if (date === null) return;
     const formatted = this.#applyFormat(date, this.dateStyleValue, this.timeStyleValue);
@@ -7545,7 +8003,10 @@ var LocalTimeController = class extends Controller {
     if (title !== null) this.element.setAttribute("title", title);
     this.dispatch("format", { detail: { formatted } });
   }
-  /** Parses the UTC `datetime` attribute into a {@link Date}, or `null`. */
+  /**
+   * Parses the UTC `datetime` attribute into a {@link Date}, or `null`. Whitespace
+   * around the attribute value is tolerated.
+   */
   #parse() {
     const raw = this.element.getAttribute("datetime");
     if (!raw) return null;
@@ -7558,11 +8019,21 @@ var LocalTimeController = class extends Controller {
    * the *runtime's* local zone, contradicting "the server emits UTC". Values that
    * already carry `Z` or a `±hh:mm` offset (and bare `YYYY-MM-DD` dates, already
    * parsed as UTC) are returned unchanged.
+   *
+   * HTML accepts a space where ISO 8601 wants `T`, and `Date.parse` of that form is
+   * left to each engine, so a whole value shaped that way is normalized to the `T`
+   * separator first. The pattern is anchored: a value trailing anything else — a
+   * zone word such as `"2026-06-08 12:30:00 UTC"` — is handed to `Date.parse` as
+   * authored instead of being turned into a string nothing can parse.
    */
   #asUtc(value) {
-    const hasTime = /T\d{2}:\d{2}/.test(value);
-    const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(value);
-    return hasTime && !hasZone ? `${value}Z` : value;
+    const isoLike = value.replace(
+      /^(\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)$/,
+      "$1T$2"
+    );
+    const hasTime = /T\d{2}:\d{2}/.test(isoLike);
+    const hasZone = /(Z|[+-]\d{2}:?\d{2})$/.test(isoLike);
+    return hasTime && !hasZone ? `${isoLike}Z` : isoLike;
   }
   /**
    * Builds the optional detailed `title`. `titleFormat` is an `Intl` style
@@ -7591,9 +8062,9 @@ var LocalTimeController = class extends Controller {
       return null;
     }
   }
-  /** Locale precedence: the value, then the element's `lang`, then the document's. */
+  /** Locale precedence: the value, then the nearest `lang` up the ancestor chain. */
   get #locale() {
-    return this.localeValue || this.element.lang || document.documentElement.lang || void 0;
+    return this.localeValue || this.element.closest("[lang]")?.getAttribute("lang") || void 0;
   }
 };
 var COLUMNS_PROPERTY = "--stimeo-masonry-columns";
@@ -8440,9 +8911,29 @@ var MenubarController = class extends Controller {
     if (index !== -1) items[index]?.focus();
   }
 };
+
+// src/utils/range.ts
+function rangeFraction(value, min, max) {
+  const span = max - min;
+  if (!(span > 0)) return 0;
+  const clamped = Math.min(max, Math.max(min, value));
+  let fraction;
+  if (Number.isFinite(span)) {
+    fraction = (clamped - min) / span;
+  } else {
+    const scale = Math.max(Math.abs(min), Math.abs(max));
+    fraction = (clamped / scale - min / scale) / (max / scale - min / scale);
+  }
+  if (!Number.isFinite(fraction)) return 0;
+  return Math.min(1, Math.max(0, fraction));
+}
+
+// src/controllers/meter_controller.ts
+var OWNED_VALUE_TEXT = "data-stimeo--meter-owns-valuetext";
 var MeterController = class extends Controller {
   static targets = ["bar"];
   static values = {
+    announceText: { type: String, default: "" },
     value: { type: Number, default: 0 },
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
@@ -8453,9 +8944,24 @@ var MeterController = class extends Controller {
   };
   static actions = ["setValue"];
   static events = ["change"];
+  /**
+   * Collapses a morph that swaps several render inputs at once into one repaint.
+   * A single update usually rewrites the whole set, and each Value would otherwise
+   * repaint on its own.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render();
+  });
+  /** The segment last announced, so only a change is read out. */
+  #announcedState = null;
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
   /**
    * Updates the measured value from an action param (`amount`) or a
    * `detail.value` CustomEvent, syncs ARIA and `data-state`, and dispatches
@@ -8465,59 +8971,95 @@ var MeterController = class extends Controller {
     const next = toFiniteNumber(event.params?.amount ?? event.detail?.value);
     if (next === null) return;
     this.valueValue = this.#clamp(next);
-    this.#render();
-    this.dispatch("change", {
-      detail: { value: this.valueValue, ratio: this.#ratio, state: this.#state }
-    });
+    const reading = this.#render();
+    this.dispatch("change", { detail: reading });
+    if (reading.state !== this.#announcedState) {
+      this.#announcedState = reading.state;
+      announce(
+        fillTemplate(this.announceTextValue, { state: reading.state, value: reading.value })
+      );
+    }
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `low` at runtime. */
+  lowValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `high` at runtime. */
+  highValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */
+  valueTextValueChanged() {
+    this.#repaint.schedule();
   }
   /** Clamps `raw` into the configured `[min, max]` range. */
   #clamp(raw) {
     return Math.min(this.maxValue, Math.max(this.minValue, raw));
   }
-  /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */
-  get #ratio() {
-    const span = this.maxValue - this.minValue;
-    if (span <= 0) return 0;
-    return (this.#clamp(this.valueValue) - this.minValue) / span;
-  }
   /** Whether a threshold attribute is present (absent = no threshold). */
   #hasThreshold(name) {
     return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);
   }
   /**
-   * Classifies the value into a `low`/`medium`/`high` segment. Values at or
-   * below `low` are `low`; at or above `high` are `high`; otherwise `medium`.
-   * With neither threshold present, everything is `medium`.
+   * Classifies `value` into a `low`/`medium`/`high` segment. Values at or below
+   * `low` are `low`; at or above `high` are `high`; otherwise `medium`. With
+   * neither threshold present, everything is `medium`.
    */
-  get #state() {
-    const value = this.#clamp(this.valueValue);
+  #stateOf(value) {
     if (this.#hasThreshold("low") && value <= this.lowValue) return "low";
     if (this.#hasThreshold("high") && value >= this.highValue) return "high";
     return "medium";
   }
-  /** Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio. */
+  /**
+   * Reflects value/range onto ARIA, the segment onto `data-state`, and the ratio.
+   * The reading is derived once and returned, so the `change` detail reports the
+   * same numbers the DOM just received.
+   */
   #render() {
     const value = this.#clamp(this.valueValue);
+    const reading = {
+      value,
+      ratio: rangeFraction(value, this.minValue, this.maxValue),
+      state: this.#stateOf(value)
+    };
     this.element.setAttribute("aria-valuemin", String(this.minValue));
     this.element.setAttribute("aria-valuemax", String(this.maxValue));
-    this.element.setAttribute("aria-valuenow", String(value));
-    this.element.style.setProperty("--stimeo-meter-ratio", String(this.#ratio));
-    this.element.setAttribute("data-state", this.#state);
-    this.#applyValueText(value);
+    this.element.setAttribute("aria-valuenow", String(reading.value));
+    this.element.style.setProperty("--stimeo-meter-ratio", String(reading.ratio));
+    this.element.setAttribute("data-state", reading.state);
+    this.#applyValueText(reading);
+    return reading;
   }
   /**
    * Sets `aria-valuetext` from the consumer-provided template, substituting
-   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library;
-   * cleared when no template is given.
+   * `{value}`, `{percent}`, and `{state}`. Kept i18n-neutral in the library.
+   * With no template the attribute belongs to the consumer, so only a text this
+   * controller wrote is taken back ({@link OWNED_VALUE_TEXT}).
    */
-  #applyValueText(value) {
+  #applyValueText({ value, ratio, state }) {
     if (this.valueTextValue.length === 0) {
-      this.element.removeAttribute("aria-valuetext");
+      if (this.element.hasAttribute(OWNED_VALUE_TEXT)) {
+        this.element.removeAttribute("aria-valuetext");
+        this.element.removeAttribute(OWNED_VALUE_TEXT);
+      }
       return;
     }
-    const percent = Math.round(this.#ratio * 100);
-    const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent)).replaceAll("{state}", this.#state);
+    const percent = Math.round(ratio * 100);
+    const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent)).replaceAll("{state}", state);
     this.element.setAttribute("aria-valuetext", text);
+    this.element.setAttribute(OWNED_VALUE_TEXT, "");
   }
 };
 
@@ -9585,20 +10127,17 @@ var NestedFormController = class extends Controller {
 var NetworkStatusController = class extends Controller {
   static targets = ["offline", "online"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceOnlineText: { type: String, default: "" },
     onlineAutoHide: { type: Number, default: 0 }
   };
   static events = ["change"];
   #timers = new SafeTimeout();
   /** Last known connectivity; guards against duplicate-state re-announcements. */
   #online = true;
-  /** Banner text captured from the markup so transitions can re-write it. */
-  #offlineMessage = "";
-  #onlineMessage = "";
   #handleOnline = () => this.#update(true);
   #handleOffline = () => this.#update(false);
   connect() {
-    this.#offlineMessage = this.hasOfflineTarget ? (this.offlineTarget.textContent ?? "").trim() : "";
-    this.#onlineMessage = this.hasOnlineTarget ? (this.onlineTarget.textContent ?? "").trim() : "";
     if (this.hasOfflineTarget) this.offlineTarget.hidden = true;
     if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
     this.#online = navigator.onLine;
@@ -9612,7 +10151,12 @@ var NetworkStatusController = class extends Controller {
     window.removeEventListener("offline", this.#handleOffline);
     this.#timers.clearAll();
   }
-  /** Applies a connectivity transition, guarded against duplicate states. */
+  /**
+   * Applies a connectivity transition, guarded against duplicate states.
+   *
+   * The event goes out last, so a listener reading `data-state` or a banner's
+   * visibility sees the state the transition landed on rather than the previous one.
+   */
   #update(online) {
     if (online === this.#online) return;
     this.#online = online;
@@ -9622,6 +10166,9 @@ var NetworkStatusController = class extends Controller {
     } else {
       this.#showOffline();
     }
+    announce(fillTemplate(online ? this.announceOnlineTextValue : this.announceTextValue, {}), {
+      assertive: !online
+    });
     this.dispatch("change", { detail: { online } });
   }
   /** Shows the offline banner and hides the recovery banner. */
@@ -9629,7 +10176,6 @@ var NetworkStatusController = class extends Controller {
     this.#timers.clearAll();
     if (this.hasOnlineTarget) this.onlineTarget.hidden = true;
     if (this.hasOfflineTarget) {
-      this.offlineTarget.textContent = this.#offlineMessage;
       this.offlineTarget.hidden = false;
     }
   }
@@ -9637,7 +10183,6 @@ var NetworkStatusController = class extends Controller {
   #showOnline() {
     if (this.hasOfflineTarget) this.offlineTarget.hidden = true;
     if (!this.hasOnlineTarget) return;
-    this.onlineTarget.textContent = this.#onlineMessage;
     this.onlineTarget.hidden = false;
     if (this.onlineAutoHideValue > 0) {
       this.#timers.set(() => {
@@ -10406,17 +10951,15 @@ var OverflowMenuController = class extends Controller {
   #lastHidden = null;
   /** The `tabindex` this instance lends the root for the focus fallback. */
   #tabindex = new TabindexLoan();
-  /** Hands Turbo a pristine snapshot: the cache is written after this event. */
-  #onBeforeCache = () => {
-    this.#restoreAll();
-  };
+  /** Hands Turbo a pristine snapshot of the bar, with every item back in place. */
+  #beforeCache = new BeforeCacheReset(() => this.#restoreAll());
   connect() {
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
     const trigger = this.#trigger();
     if (trigger !== null && this.#isBareTrigger(trigger)) {
       trigger.textContent = this.moreLabelValue;
     }
-    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.activate();
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
     this.update();
@@ -10424,7 +10967,7 @@ var OverflowMenuController = class extends Controller {
   disconnect() {
     this.#layout.disconnect();
     this.#timers.clearAll();
-    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#beforeCache.deactivate();
     this.#restoreAll();
     this.#lastHidden = null;
   }
@@ -11347,53 +11890,6 @@ var PersistController = class extends Controller {
     }
   }
 };
-
-// src/utils/detach_gate.ts
-var DetachGate = class _DetachGate {
-  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
-  #pending = false;
-  /**
-   * True when the disconnect is definitely a real detach — the element left
-   * the document, or `data-controller` no longer lists the identifier. False
-   * means ambiguous (in-page move or observed-root exit), NOT "alive".
-   */
-  static isDetached(host) {
-    if (!host.element.isConnected) return true;
-    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
-    return !tokens.includes(host.identifier);
-  }
-  /**
-   * Call from `disconnect()`: runs `teardown` synchronously on a definite
-   * detach (fast path), otherwise defers it one microtask — a reconnect
-   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
-   * One microtask is the whole probe window: Stimulus reconnects a moved
-   * element within the same mutation batch, before the checkpoint drains.
-   */
-  disconnected(host, teardown) {
-    if (_DetachGate.isDetached(host)) {
-      this.#pending = false;
-      teardown();
-      return;
-    }
-    this.#pending = true;
-    queueMicrotask(() => {
-      if (!this.#pending) return;
-      this.#pending = false;
-      teardown();
-    });
-  }
-  /**
-   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
-   * an in-page move) and from the head of any teardown path not routed through
-   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
-   * never run the teardown a second time.
-   */
-  cancel() {
-    this.#pending = false;
-  }
-};
-
-// src/controllers/pointer_drag_controller.ts
 var PointerDragController = class _PointerDragController extends Controller {
   static targets = ["handle"];
   static values = {
@@ -11975,6 +12471,7 @@ var PreviewGuardController = class extends Controller {
     this.element.removeAttribute("data-preview-hidden");
   }
 };
+var OWNED_VALUE_TEXT2 = "data-stimeo--progress-owns-valuetext";
 var ProgressController = class extends Controller {
   static targets = ["bar"];
   static values = {
@@ -11982,13 +12479,27 @@ var ProgressController = class extends Controller {
     min: { type: Number, default: 0 },
     max: { type: Number, default: 100 },
     indeterminate: { type: Boolean, default: false },
-    valueText: { type: String, default: "" }
+    valueText: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
   static actions = ["setValue"];
   static events = ["change", "complete"];
+  /**
+   * Collapses a morph that swaps several render inputs at once into one repaint.
+   * A single update usually rewrites the whole set, and each Value would otherwise
+   * repaint on its own.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render();
+  });
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
   /**
    * Updates the progress value from an action param (`amount`) or a
    * `detail.value` CustomEvent, normalizes it into range, syncs ARIA, and
@@ -12004,11 +12515,30 @@ var ProgressController = class extends Controller {
     this.dispatch("change", { detail: { value, ratio: this.#ratio } });
     if (value >= this.maxValue) {
       this.dispatch("complete", { detail: { value } });
+      announce(
+        fillTemplate(this.announceTextValue, { value, percent: Math.round(this.#ratio * 100) })
+      );
     }
   }
-  /** Re-render when the indeterminate flag is toggled via its data attribute. */
+  /** Repaints when application code (or a Turbo morph) changes `indeterminate` at runtime. */
   indeterminateValueChanged() {
-    this.#render();
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `valueText` at runtime. */
+  valueTextValueChanged() {
+    this.#repaint.schedule();
   }
   /** Clamps `raw` into the configured `[min, max]` range. */
   #clamp(raw) {
@@ -12016,9 +12546,7 @@ var ProgressController = class extends Controller {
   }
   /** Current fraction of the range in `[0, 1]`; `0` when the range is empty. */
   get #ratio() {
-    const span = this.maxValue - this.minValue;
-    if (span <= 0) return 0;
-    return (this.#clamp(this.valueValue) - this.minValue) / span;
+    return rangeFraction(this.valueValue, this.minValue, this.maxValue);
   }
   /** Reflects value/range/indeterminate onto ARIA, `data-state`, and the ratio. */
   #render() {
@@ -12026,7 +12554,7 @@ var ProgressController = class extends Controller {
     this.element.setAttribute("aria-valuemax", String(this.maxValue));
     if (this.indeterminateValue) {
       this.element.removeAttribute("aria-valuenow");
-      this.element.removeAttribute("aria-valuetext");
+      this.#clearOwnValueText();
       this.element.style.removeProperty("--stimeo-progress-ratio");
       this.element.setAttribute("data-state", "indeterminate");
       return;
@@ -12040,16 +12568,25 @@ var ProgressController = class extends Controller {
   /**
    * Sets `aria-valuetext` from the consumer-provided template, substituting
    * `{value}` and `{percent}`. Left to the consumer so the human-readable text
-   * stays i18n-neutral in the library; cleared when no template is given.
+   * stays i18n-neutral in the library. With no template the attribute belongs to
+   * the consumer, so only a text this controller wrote is taken back
+   * ({@link OWNED_VALUE_TEXT}).
    */
   #applyValueText(value) {
     if (this.valueTextValue.length === 0) {
-      this.element.removeAttribute("aria-valuetext");
+      this.#clearOwnValueText();
       return;
     }
     const percent = Math.round(this.#ratio * 100);
     const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent));
     this.element.setAttribute("aria-valuetext", text);
+    this.element.setAttribute(OWNED_VALUE_TEXT2, "");
+  }
+  /** Removes `aria-valuetext` only when this controller is the one that wrote it. */
+  #clearOwnValueText() {
+    if (!this.element.hasAttribute(OWNED_VALUE_TEXT2)) return;
+    this.element.removeAttribute("aria-valuetext");
+    this.element.removeAttribute(OWNED_VALUE_TEXT2);
   }
 };
 var RadioGroupController = class extends Controller {
@@ -12155,16 +12692,33 @@ var RangeSliderController = class extends Controller {
     return this.logicalTrackValue && isRtl(this.element);
   }
   /** Normalizes the initial pair (clamped, snapped, ordered) and renders. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    this.#render(this.startValue, this.endValue);
+  });
   connect() {
+    this.#repaint.activate();
     const lo = Math.min(this.startValue, this.endValue);
     const hi = Math.max(this.startValue, this.endValue);
     this.#commit(lo, hi, false);
   }
   /** Cancels any active pointer drag so document listeners never leak. */
   disconnect() {
+    this.#repaint.cancel();
     this.#dragAbort?.abort();
     this.#dragAbort = null;
   }
+  /** Repaints when application code (or a Turbo morph) changes `min` at runtime. */
+  minValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `max` at runtime. */
+  maxValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Keyboard stepping for whichever thumb is focused (the action's element). */
   onKeydown(event) {
     if (isReservedArrowChord(event)) return;
@@ -12280,14 +12834,13 @@ var RangeSliderController = class extends Controller {
       this.endThumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
       this.endThumbTarget.setAttribute("aria-valuenow", String(end));
     }
-    const span = this.maxValue - this.minValue;
     this.element.style.setProperty(
       START_PROPERTY,
-      String(span > 0 ? (start - this.minValue) / span : 0)
+      String(rangeFraction(start, this.minValue, this.maxValue))
     );
     this.element.style.setProperty(
       END_PROPERTY,
-      String(span > 0 ? (end - this.minValue) / span : 0)
+      String(rangeFraction(end, this.minValue, this.maxValue))
     );
   }
   /** Clamps `raw` to `[min, max]` and snaps it to the nearest step from `min`. */
@@ -12313,13 +12866,33 @@ var RatingController = class extends Controller {
   static events = ["change"];
   #roving = new RovingTabindex(() => this.symbolTargets);
   /** Reflects the initial value, or switches to the non-interactive readonly view. */
+  /**
+   * Collapses a morph that swaps render inputs into one repaint, and refuses the
+   * pass Stimulus delivers before `connect()`.
+   */
+  #repaint = new MicrotaskCoalescer(() => {
+    if (this.readonlyValue) {
+      this.#applyReadonly();
+      return;
+    }
+    this.#apply(this.#clamp(this.valueValue), { focus: false });
+  });
   connect() {
+    this.#repaint.activate();
     if (this.readonlyValue) {
       this.#applyReadonly();
       return;
     }
     this.#apply(this.#clamp(this.valueValue), { focus: false });
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `value` at runtime. */
+  valueValueChanged() {
+    this.#repaint.schedule();
+  }
   /** Selects (or clears) the clicked symbol. Bound via `data-action` (click). */
   select(event) {
     if (this.readonlyValue) return;
@@ -12618,11 +13191,16 @@ var RelativeTimeController = class extends Controller {
     tickInterval: { type: Number, default: 6e4 }
   };
   #timers = new SafeTimeout();
+  /** Collapses a morph that swaps several render inputs at once into one repaint. */
+  #resync = new MicrotaskCoalescer(() => this.#resyncToValues());
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   /** Epoch ms parsed from `datetime`; `NaN` when absent or invalid. */
   #targetMs = Number.NaN;
   /** The authored absolute text, restored when the threshold fallback kicks in. */
   #absoluteText = "";
   connect() {
+    this.#resync.activate();
+    this.#beforeCache.activate();
     if (this.element.getAttribute("data-state") !== "relative") {
       this.#absoluteText = (this.element.textContent ?? "").trim();
     }
@@ -12631,9 +13209,50 @@ var RelativeTimeController = class extends Controller {
     this.#schedule();
   }
   disconnect() {
+    this.#resync.cancel();
+    this.#beforeCache.deactivate();
+    this.#timers.clearAll();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `locale` at runtime. */
+  localeValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `threshold` at runtime. */
+  thresholdValueChanged() {
+    this.#resync.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `tickInterval` at runtime. */
+  tickIntervalValueChanged() {
+    this.#resync.schedule();
+  }
+  /**
+   * Renders against the current Values and re-arms the poll from now.
+   *
+   * Render only: it emits no event, and clearing first keeps the single self-arming
+   * timer single — scheduling on top of a pending one would double the poll rate for
+   * the rest of the session. A stamp whose `datetime` never parsed has nothing to
+   * render, and one that already reached its terminal fallback simply renders it
+   * again and stops.
+   */
+  #resyncToValues() {
+    if (Number.isNaN(this.#targetMs)) return;
     this.#timers.clearAll();
+    this.#schedule();
   }
-  /** Renders the current representation and reschedules unless it is now absolute. */
+  /**
+   * Restores the authored absolute text and the pre-render state for the snapshot
+   * Turbo is about to take, leaving the live page's poll timer alone.
+   *
+   * With no authored text held there is nothing to restore, and `data-state` has to
+   * stay as it is: that marker is what tells the next `connect()` the visible text is
+   * a rendered relative form rather than an absolute fallback to hold on to.
+   */
+  #rewindForCache() {
+    if (!this.#absoluteText) return;
+    this.element.textContent = this.#absoluteText;
+    this.element.removeAttribute("data-state");
+  }
+  /** Renders the current representation and reschedules unless polling can stop. */
   #schedule() {
     const nextDelay = this.#applyAndComputeDelay();
     if (nextDelay !== null) {
@@ -12641,31 +13260,44 @@ var RelativeTimeController = class extends Controller {
     }
   }
   /**
-   * Updates the visible text and returns the next poll delay (ms), or `null`
-   * once the absolute fallback is shown (which never changes, so stop polling).
+   * Updates the visible text and returns the next poll delay (ms), or `null` when
+   * polling can stop: a *past* timestamp that fell back to the absolute text can
+   * never leave it again, and a locale the runtime rejects has nothing to render
+   * until that value is corrected.
    */
   #applyAndComputeDelay() {
     const deltaMs = this.#targetMs - Date.now();
     const absSeconds = Math.abs(deltaMs) / 1e3;
+    const scale = UNITS.find((u) => absSeconds < u.limit) ?? YEAR_SCALE;
+    const unitFloor = scale.unit === "second" || scale.unit === "minute" ? 6e4 : scale.ms;
+    const nextDelay = Math.max(this.tickIntervalValue, Math.min(unitFloor, 864e5));
     if (this.thresholdValue > 0 && absSeconds >= this.thresholdValue && this.#absoluteText) {
       this.element.textContent = this.#absoluteText;
       this.element.setAttribute("data-state", "absolute");
-      return null;
+      if (deltaMs <= 0) return null;
+      return Math.min(nextDelay, deltaMs - this.thresholdValue * 1e3 + 1);
     }
-    const scale = UNITS.find((u) => absSeconds < u.limit) ?? YEAR_SCALE;
+    const formatter = this.#formatter;
+    if (formatter === null) return null;
     const value = Math.round(deltaMs / scale.ms);
-    this.element.textContent = this.#formatter.format(value, scale.unit);
+    this.element.textContent = formatter.format(value, scale.unit);
     this.element.setAttribute("data-state", "relative");
-    const unitFloor = scale.unit === "second" || scale.unit === "minute" ? 6e4 : scale.ms;
-    return Math.max(this.tickIntervalValue, Math.min(unitFloor, 864e5));
+    return nextDelay;
   }
-  /** A `RelativeTimeFormat` for the resolved locale (`numeric: "auto"`). */
+  /**
+   * A `RelativeTimeFormat` for the resolved locale (`numeric: "auto"`), or `null`
+   * when the runtime rejects that locale.
+   */
   get #formatter() {
-    return new Intl.RelativeTimeFormat(this.#locale, { numeric: "auto" });
+    try {
+      return new Intl.RelativeTimeFormat(this.#locale, { numeric: "auto" });
+    } catch {
+      return null;
+    }
   }
-  /** Locale precedence: the value, then the element's `lang`, then the document's. */
+  /** Locale precedence: the value, then the nearest `lang` up the ancestor chain. */
   get #locale() {
-    return this.localeValue || this.element.lang || document.documentElement.lang || void 0;
+    return this.localeValue || this.element.closest("[lang]")?.getAttribute("lang") || void 0;
   }
 };
 var ResetBeforeCacheController = class extends Controller {
@@ -13677,7 +14309,7 @@ var ScrollspyController = class extends Controller {
    *
    * @param announce Whether this sync represents a change of current section.
    */
-  #syncActiveStates(announce) {
+  #syncActiveStates(announce2) {
     const activeLinks = this.linkTargets.filter(
       (link) => this.#getAnchorId(link) === this.#activeSectionId
     );
@@ -13688,7 +14320,7 @@ var ScrollspyController = class extends Controller {
         link.removeAttribute("aria-current");
       }
     }
-    if (!announce) return;
+    if (!announce2) return;
     const primaryLink = activeLinks[0];
     if (primaryLink) {
       this.dispatch("change", { detail: { id: this.#activeSectionId, link: primaryLink } });
@@ -13836,7 +14468,7 @@ var SidebarController = class extends Controller {
     key: { type: String, default: "" },
     collapsed: { type: Boolean, default: false }
   };
-  static actions = ["beforeCache", "close", "open", "toggle"];
+  static actions = ["close", "open", "toggle"];
   /** Exact panel currently owned by the modal lifecycle (survives target churn safely). */
   #activePanel = null;
   /** Owns the overlay modal side effects; Escape closes, focus falls to trigger. */
@@ -13858,6 +14490,7 @@ var SidebarController = class extends Controller {
   #connected = false;
   connect() {
     this.#connected = true;
+    this.#beforeCache.activate();
     this.#activePanel = this.hasPanelTarget ? this.panelTarget : null;
     this.#collapsed = this.#restoreCollapsed();
     this.#mqlQuery = this.#breakpointQuery;
@@ -13867,6 +14500,7 @@ var SidebarController = class extends Controller {
   }
   disconnect() {
     this.#connected = false;
+    this.#beforeCache.deactivate();
     this.#mql?.removeEventListener("change", this.#onMediaChange);
     this.#mql = null;
     this.#mqlQuery = null;
@@ -13918,12 +14552,12 @@ var SidebarController = class extends Controller {
    * closed immediately, and modal side effects are released without moving
    * focus during navigation.
    */
-  beforeCache() {
+  #beforeCache = new BeforeCacheReset(() => {
     if (!this.#connected || !this.#isOverlay) return;
     this.#transition.cancel();
     this.#trap.deactivate({ restoreFocus: false });
     this.#setOverlayClosedImmediate();
-  }
+  });
   /** Toggles the panel: inline flips collapsed/expanded, overlay flips open/closed. */
   toggle() {
     if (this.#isOverlay) {
@@ -14120,15 +14754,13 @@ var SidebarController = class extends Controller {
 var SkeletonController = class extends Controller {
   static targets = ["placeholder", "content"];
   static values = {
+    announceReadyText: { type: String, default: "" },
     minDuration: { type: Number, default: 0 }
   };
   static actions = ["ready", "reset"];
   static events = ["ready"];
   #timers = new SafeTimeout();
-  /** Pending min-duration reveal timer id, or `null` when none is scheduled. */
-  #revealTimerId = null;
-  /** Epoch ms when the loading state began; `minDuration` is measured from it. */
-  #loadingSince = 0;
+  #floor = new MinDurationFloor(this.#timers);
   connect() {
     if (this.#state !== "ready") {
       this.#enterLoading();
@@ -14136,32 +14768,21 @@ var SkeletonController = class extends Controller {
   }
   disconnect() {
     this.#timers.clearAll();
-    this.#revealTimerId = null;
+    this.#floor.cancel();
   }
   /** Swaps to the real content. Honors `minDuration` to prevent a flash. */
   ready() {
-    if (this.#state === "ready" || this.#revealTimerId !== null) return;
-    const remaining = this.minDurationValue - (Date.now() - this.#loadingSince);
-    if (remaining > 0) {
-      this.#revealTimerId = this.#timers.set(() => {
-        this.#revealTimerId = null;
-        this.#reveal();
-      }, remaining);
-    } else {
-      this.#reveal();
-    }
+    if (this.#state === "ready" || this.#floor.pending) return;
+    this.#floor.schedule(this.minDurationValue, () => this.#reveal());
   }
   /** Returns to the loading state (e.g. a Turbo Stream re-fetch). */
   reset() {
-    if (this.#revealTimerId !== null) {
-      this.#timers.clear(this.#revealTimerId);
-      this.#revealTimerId = null;
-    }
+    this.#floor.cancel();
     this.#enterLoading();
   }
   /** Shows the placeholder, hides content, and marks the region busy. */
   #enterLoading() {
-    this.#loadingSince = Date.now();
+    this.#floor.begin();
     if (this.hasPlaceholderTarget) this.placeholderTarget.hidden = false;
     if (this.hasContentTarget) this.contentTarget.hidden = true;
     this.element.setAttribute("aria-busy", "true");
@@ -14174,6 +14795,7 @@ var SkeletonController = class extends Controller {
     this.element.setAttribute("aria-busy", "false");
     this.element.setAttribute("data-state", "ready");
     this.dispatch("ready", { detail: {} });
+    announce(fillTemplate(this.announceReadyTextValue, {}));
   }
   /** Current lifecycle phase as reflected on `data-state`. */
   get #state() {
@@ -14284,8 +14906,7 @@ var SliderController = class extends Controller {
       this.thumbTarget.setAttribute("aria-valuemax", String(this.maxValue));
       this.thumbTarget.setAttribute("aria-valuenow", String(value));
     }
-    const span = this.maxValue - this.minValue;
-    const fraction = span > 0 ? (value - this.minValue) / span : 0;
+    const fraction = rangeFraction(value, this.minValue, this.maxValue);
     this.element.style.setProperty(FRACTION_PROPERTY, String(fraction));
     if (changed && !silent) this.dispatch("change", { detail: { value } });
   }
@@ -14546,38 +15167,61 @@ var SortableController = class extends Controller {
 var SpinnerController = class extends Controller {
   static targets = ["indicator", "region", "message"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceReadyText: { type: String, default: "" },
     delay: { type: Number, default: 0 },
-    minDuration: { type: Number, default: 0 }
+    minDuration: { type: Number, default: 0 },
+    timeout: { type: Number, default: 0 }
   };
   static actions = ["start", "stop"];
-  static events = ["hide", "show"];
+  static events = ["hide", "show", "timeout"];
   #timers = new SafeTimeout();
+  #floor = new MinDurationFloor(this.#timers);
+  #gate = new DetachGate();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   /** Pending show-delay timer id, or `null` when no start is awaiting its delay. */
   #delayTimerId = null;
-  /** Pending min-duration hide timer id, or `null` when none is scheduled. */
-  #hideTimerId = null;
-  /** Epoch ms when the spinner became visible; `minDuration` is measured from it. */
-  #shownAt = 0;
+  /** Pending safety-net timer id, or `null` when `timeout` is off or not armed. */
+  #timeoutTimerId = null;
   connect() {
+    this.#gate.cancel();
+    this.#beforeCache.activate();
+    if (this.#state === "pending" && this.#delayTimerId === null) {
+      this.#setBusy(false);
+      this.element.setAttribute("data-state", "idle");
+      return;
+    }
     if (!this.element.hasAttribute("data-state")) {
       this.element.setAttribute("data-state", "idle");
     }
   }
+  /**
+   * Re-applies the current phase to an indicator that arrived after `connect()`.
+   *
+   * A Turbo Stream can swap the indicator for a fresh node mid-load, and that node
+   * carries the markup contract's `hidden`. Without this the spinner would vanish
+   * while `data-state` still says `loading`, and nothing but the next cycle would
+   * bring it back.
+   */
+  indicatorTargetConnected(target) {
+    target.hidden = this.#state !== "loading";
+  }
   disconnect() {
-    this.#timers.clearAll();
-    this.#delayTimerId = null;
-    this.#hideTimerId = null;
+    this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#teardown());
   }
   /** Begins loading. Honors `delay` before the spinner actually appears. */
   start() {
     if (this.#state === "loading") {
       this.#setBusy(true);
-      this.#cancelHide();
+      this.#floor.cancel();
+      this.#armTimeout();
       return;
     }
     if (this.#state !== "idle") return;
     this.#setBusy(true);
-    this.#cancelHide();
+    this.#floor.cancel();
+    this.#armTimeout();
     if (this.delayValue > 0) {
       this.element.setAttribute("data-state", "pending");
       this.#delayTimerId = this.#timers.set(() => {
@@ -14591,6 +15235,7 @@ var SpinnerController = class extends Controller {
   /** Ends loading. Honors `minDuration` so a shown spinner does not flicker. */
   stop() {
     const state = this.#state;
+    this.#cancelTimeout();
     if (state === "pending") {
       this.#cancelDelay();
       this.#setBusy(false);
@@ -14599,28 +15244,52 @@ var SpinnerController = class extends Controller {
     }
     if (state !== "loading") return;
     this.#setBusy(false);
-    const remaining = this.minDurationValue - (Date.now() - this.#shownAt);
-    if (remaining > 0) {
-      this.#hideTimerId = this.#timers.set(() => {
-        this.#hideTimerId = null;
-        this.#hide();
-      }, remaining);
-    } else {
-      this.#hide();
-    }
+    this.#floor.schedule(this.minDurationValue, () => this.#hide());
   }
   /** Reveals the indicator, marks the moment shown, and announces via the live region. */
   #show() {
-    this.#shownAt = Date.now();
+    this.#floor.begin();
+    this.#setBusy(true);
     if (this.hasIndicatorTarget) this.indicatorTarget.hidden = false;
     this.element.setAttribute("data-state", "loading");
     this.dispatch("show", { detail: {} });
+    announce(fillTemplate(this.announceTextValue, {}));
   }
   /** Hides the indicator and returns to the idle state. */
   #hide() {
     if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
     this.element.setAttribute("data-state", "idle");
     this.dispatch("hide", { detail: {} });
+    announce(fillTemplate(this.announceReadyTextValue, {}));
+  }
+  /**
+   * Drops both timers on a real detach. The markup keeps whatever it last held: an
+   * element on its way out of the document has no reader left, and one whose
+   * `data-controller` dropped the identifier no longer resolves its own targets, so
+   * the rollback could only ever be partial. The snapshot is rewound where it is
+   * still whole, on `turbo:before-cache`.
+   */
+  #teardown() {
+    this.#gate.cancel();
+    this.#timers.clearAll();
+    this.#delayTimerId = null;
+    this.#timeoutTimerId = null;
+    this.#floor.cancel();
+  }
+  /**
+   * Returns the loading state to idle for the snapshot Turbo is about to take,
+   * so a page reached with the Back button is not restored mid-load with a
+   * spinner nothing can stop. State only: `data-state`, the indicator's `hidden`,
+   * and `aria-busy`. No `hide` is dispatched — the load was never observed to
+   * finish, and a snapshot rewind is not a lifecycle event the consumer can act
+   * on. The live page keeps its timers, so a navigation that never completes
+   * leaves the running cycle intact.
+   */
+  #rewindForCache() {
+    this.#cancelTimeout();
+    this.#setBusy(false);
+    if (this.hasIndicatorTarget) this.indicatorTarget.hidden = true;
+    this.element.setAttribute("data-state", "idle");
   }
   /** Reflects busy state onto the controlled region (if present). */
   #setBusy(busy) {
@@ -14628,18 +15297,32 @@ var SpinnerController = class extends Controller {
       this.regionTarget.setAttribute("aria-busy", String(busy));
     }
   }
+  /**
+   * Arms the safety net so a `stop` that never arrives cannot strand the spinner.
+   * Off by default: the consumer owns the async work, so only it knows whether a
+   * ceiling makes sense. Re-arming on a restart measures from the newest start.
+   */
+  #armTimeout() {
+    this.#cancelTimeout();
+    if (this.timeoutValue <= 0) return;
+    this.#timeoutTimerId = this.#timers.set(() => {
+      this.#timeoutTimerId = null;
+      this.dispatch("timeout", { detail: {} });
+      this.stop();
+    }, this.timeoutValue);
+  }
+  #cancelTimeout() {
+    if (this.#timeoutTimerId !== null) {
+      this.#timers.clear(this.#timeoutTimerId);
+      this.#timeoutTimerId = null;
+    }
+  }
   #cancelDelay() {
     if (this.#delayTimerId !== null) {
       this.#timers.clear(this.#delayTimerId);
       this.#delayTimerId = null;
     }
   }
-  #cancelHide() {
-    if (this.#hideTimerId !== null) {
-      this.#timers.clear(this.#hideTimerId);
-      this.#hideTimerId = null;
-    }
-  }
   /** Current lifecycle phase as reflected on `data-state`. */
   get #state() {
     return this.element.getAttribute("data-state") ?? "idle";
@@ -14652,26 +15335,63 @@ var StepIndicatorController = class extends Controller {
   };
   static actions = ["setCurrent"];
   static events = ["change"];
+  /**
+   * Whether the target callbacks may render. Stimulus reports the authored steps
+   * as connected before `connect()` and the remaining ones as disconnected after
+   * `disconnect()`, so this keeps a connect at one render pass, not one per step.
+   */
+  /**
+   * Collapses a batch of step callbacks — and a morph that swaps `current` with
+   * them — into one repaint. Replacing a list of N steps delivers N callbacks, and
+   * each one would otherwise rewrite every step's state.
+   */
+  #repaint = new MicrotaskCoalescer(() => this.#render());
   /** Renders the initial state from the `current` value. */
   connect() {
+    this.#repaint.activate();
     this.#render();
   }
+  /** Closes the window in which a queued repaint may still run. */
+  disconnect() {
+    this.#repaint.cancel();
+  }
+  /** Syncs a step appended or replaced at runtime (the consumer owns the list). */
+  stepTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Re-derives the remaining steps when one is removed at runtime. */
+  stepTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code (or a Turbo morph) changes `current` at runtime. */
+  currentValueChanged() {
+    this.#repaint.schedule();
+  }
   /**
    * Updates the current step from an external event (`detail.current`, 0-based)
-   * and dispatches `change`. Out-of-range indices are clamped to the step set.
+   * and dispatches `change`. Out-of-range indices are clamped to the step set,
+   * and both sides of the no-op test are clamped, so moving onto the step an
+   * out-of-range `current` already renders is not reported as a change.
    */
   setCurrent(event) {
     const next = event.detail?.current;
     if (typeof next !== "number" || !Number.isFinite(next)) return;
     const clamped = this.#clamp(next);
-    if (clamped === this.currentValue) return;
+    const moved = clamped !== this.#clamp(this.currentValue);
     this.currentValue = clamped;
+    if (!moved) return;
     this.#render();
     this.dispatch("change", {
       detail: { current: clamped, total: this.stepTargets.length }
     });
   }
-  /** Applies `data-state`, `aria-current`, and the progress ratio custom property. */
+  /**
+   * Applies `data-state`, `aria-current`, and the progress ratio custom property.
+   *
+   * A pure function of the step set and `current`, so running it again writes the
+   * same values — which is what lets the action path paint synchronously (the event
+   * goes out after the DOM is updated) while a coalesced pass may still follow.
+   */
   #render() {
     const total = this.stepTargets.length;
     const current = this.#clamp(this.currentValue);
@@ -14686,10 +15406,15 @@ var StepIndicatorController = class extends Controller {
     const ratio = total > 1 ? current / (total - 1) : 0;
     this.element.style.setProperty("--stimeo-step-indicator-ratio", String(ratio));
   }
-  /** Constrains an index to `[0, total-1]` (or `0` when there are no steps). */
+  /**
+   * Constrains an index to `[0, total-1]` (or `0` when there are no steps). A
+   * non-finite index falls back to the first step: `current` is read from markup,
+   * so an unparsable attribute arrives as `NaN` and would otherwise propagate
+   * into every state hook.
+   */
   #clamp(index) {
     const last = this.stepTargets.length - 1;
-    if (last < 0) return 0;
+    if (last < 0 || !Number.isFinite(index)) return 0;
     return Math.min(last, Math.max(0, Math.trunc(index)));
   }
 };
@@ -14789,14 +15514,18 @@ var StickToBottomController = class extends Controller {
   static targets = ["content"];
   static values = {
     threshold: { type: Number, default: 80 },
-    behavior: { type: String, default: "auto" }
+    behavior: { type: String, default: "auto" },
+    pinOnConnect: { type: Boolean, default: false }
   };
   static actions = ["scrollToBottom"];
   static events = ["pin", "new"];
   #observer = null;
+  /** Watches for the box a deferred `pinOnConnect` jump is still waiting on. */
+  #layout = null;
   #pinned = false;
   #onScroll = () => this.#updatePinned();
   connect() {
+    if (this.pinOnConnectValue && this.#measurable()) this.#scrollToBottom("instant");
     this.#pinned = this.#isPinned();
     this.#reflectPinned();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
@@ -14804,21 +15533,29 @@ var StickToBottomController = class extends Controller {
       this.#observer = new MutationObserver((mutations) => this.#onMutations(mutations));
       this.#observer.observe(this.#watched(), { childList: true });
     }
+    if (this.pinOnConnectValue && !this.#measurable()) this.#pinWhenLaidOut();
   }
   disconnect() {
     this.element.removeEventListener("scroll", this.#onScroll);
     this.#observer?.disconnect();
     this.#observer = null;
+    this.#stopWaitingForLayout();
   }
-  /** Jumps to the bottom and re-pins (wired to a "new messages" button). */
+  /**
+   * Jumps to the bottom and re-pins (wired to a "new messages" button).
+   *
+   * The has-new flag clears on request — the user has acknowledged the arrival — while
+   * pinned is read back from where the scroll landed: a jump that arrives by the time
+   * this returns pins immediately, an animated one settles from its own scroll events,
+   * and a jump the engine cannot honor leaves the container unpinned, so the next append
+   * flags it again instead of being swallowed by a pinned state that does not hold.
+   *
+   * Which of those happens is not this method's to decide — see {@link behaviorValue}.
+   */
   scrollToBottom() {
     this.#scrollToBottom();
     this.element.removeAttribute("data-has-new");
-    if (!this.#pinned) {
-      this.#pinned = true;
-      this.element.setAttribute("data-pinned", "true");
-      this.dispatch("pin", { detail: { pinned: true } });
-    }
+    this.#updatePinned();
   }
   /** Follows appended children while pinned; otherwise flags new content. */
   #onMutations(mutations) {
@@ -14853,10 +15590,43 @@ var StickToBottomController = class extends Controller {
     const el = this.element;
     return el.scrollHeight - el.clientHeight - el.scrollTop <= this.thresholdValue;
   }
-  #scrollToBottom() {
+  /**
+   * Whether the container has a box to scroll and to measure. One that is not rendered
+   * (inside a closed panel) reports every metric as 0, which reads as "already at the
+   * bottom" — a position describing no layout the user will ever see.
+   */
+  #measurable() {
+    return this.element.clientHeight > 0;
+  }
+  /**
+   * Holds the `pinOnConnect` jump until the container is laid out, then runs it and
+   * re-reads the state — otherwise the panel opens at the top still claiming the bottom.
+   */
+  #pinWhenLaidOut() {
+    if (typeof ResizeObserver === "undefined") return;
+    this.#layout = new ResizeObserver(() => {
+      if (!this.#measurable()) return;
+      this.#stopWaitingForLayout();
+      this.#scrollToBottom("instant");
+      this.#updatePinned();
+    });
+    this.#layout.observe(this.element);
+  }
+  /** Releases the layout watch, whether or not the deferred jump ever ran. */
+  #stopWaitingForLayout() {
+    this.#layout?.disconnect();
+    this.#layout = null;
+  }
+  /**
+   * Scrolls to the bottom, clamped by the engine to the maximum scroll offset — which is
+   * 0 for a container tall enough to hold its whole content, so the jump moves nothing
+   * there. `behavior` defaults to the configured follow behavior; pass `"instant"` for a
+   * jump that must not animate.
+   */
+  #scrollToBottom(behavior = this.#behavior()) {
     const top = this.element.scrollHeight;
     if (typeof this.element.scrollTo === "function") {
-      this.element.scrollTo({ top, behavior: this.#behavior() });
+      this.element.scrollTo({ top, behavior });
     } else {
       this.element.scrollTop = top;
     }
@@ -14865,7 +15635,12 @@ var StickToBottomController = class extends Controller {
   #watched() {
     return this.hasContentTarget ? this.contentTarget : this.element;
   }
-  /** Forces reduced-motion jumps while preserving the configured normal behavior. */
+  /**
+   * The behavior a follow-scroll runs with. `"auto"` is **not** a request to arrive at
+   * once: it hands the decision to the element's computed `scroll-behavior`, so a
+   * consumer stylesheet saying `smooth` animates these scrolls too. Only `"instant"`
+   * overrides that CSS, which is why reduced motion and the `pinOnConnect` jump name it.
+   */
   #behavior() {
     if (prefersReducedMotion()) return "instant";
     return this.behaviorValue === "smooth" ? "smooth" : "auto";