stimeo-ui 0.9.0 → 0.10.0

data/dist/index.js

@@ -36,6 +36,9 @@ 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");
 }
+function hasModifierChord(event) {
+  return event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
+}
 
 // src/controllers/accordion_controller.ts
 var AccordionController = class extends Controller {
@@ -438,15 +441,25 @@ var FocusTrap = class {
    * content cannot be focused or reached by assistive technology, honoring the
    * `aria-modal="true"` contract. An element that was *already* `inert` is left
    * untracked so `#releaseBackground` does not wrongly clear it.
+   *
+   * The walk climbs from the container to `body` and inerts each ancestor's other
+   * children. Scanning only `body`'s children would skip the branch the container
+   * sits in — everything beside it inside that branch is background too, and a
+   * nested container is the ordinary case.
    */
   #isolateBackground() {
     const container = this.#getContainer();
     this.#inertedSiblings = [];
-    for (const sibling of Array.from(document.body.children)) {
-      if (!(sibling instanceof HTMLElement)) continue;
-      if (sibling.contains(container) || sibling.inert) continue;
-      sibling.inert = true;
-      this.#inertedSiblings.push(sibling);
+    for (let node = container; node !== document.body; ) {
+      const parent = node.parentElement;
+      if (!parent) break;
+      for (const sibling of Array.from(parent.children)) {
+        if (!(sibling instanceof HTMLElement)) continue;
+        if (sibling === node || sibling.inert) continue;
+        sibling.inert = true;
+        this.#inertedSiblings.push(sibling);
+      }
+      node = parent;
     }
   }
   /** Reverts the `inert` flags applied by `#isolateBackground`. */
@@ -484,8 +497,8 @@ var AlertDialogController = class extends Controller {
   static actions = ["cancel", "confirm", "open"];
   static events = ["cancel", "confirm"];
   /**
-   * Owns the modal side effects. Escape is routed through {@link cancel} so it
-   * emits the same event as the cancel button (tagged `"escape"`); focus falls
+   * Owns the modal side effects. Escape takes the same cancel path as
+   * {@link cancel} and emits the same event, tagged `"escape"` instead of `"user"`; focus falls
    * back to the trigger when nothing was focused before opening.
    */
   #trap = new FocusTrap(() => this.dialogTarget, {
@@ -855,7 +868,7 @@ var AnnouncerController = class extends Controller {
   }
   /**
    * Arms `region`'s single pending timer. Callers reach here with the slot
-   * already free — `#announce` releases it, and a fired timer clears its own
+   * already free — `#drain` releases it before writing, and a fired timer clears its own
    * entry below — so this does not cancel again.
    */
   #schedule(region, callback, delay) {
@@ -1693,8 +1706,8 @@ var BulkSelectController = class extends Controller {
   static events = ["change", "reconcile"];
   /** All-pages mode is a transient UI state, mirrored to `data-all-pages` so a
    *  `connect()` over markup that already carries the attribute rehydrates the
-   *  mode — a morph, a Turbo Stream, or a server that renders it back. A restore
-   *  visit serves the server's markup instead, so the mode does not survive one. */
+   *  mode — a morph, a Turbo Stream, a server that renders it back, or a restore
+   *  visit, whose cached snapshot carries the attribute too. */
   #allPagesMode = false;
   /** Last emitted figures, so a recompute reports only on a real change. */
   #lastCount = -1;
@@ -3497,7 +3510,7 @@ var CollapsibleController = class extends Controller {
    * `open` Value disagrees. An already-open region remains open without a
    * close/reopen cycle. The Value only seeds a genuinely fresh render where no
    * state attribute is present yet; any opening animation in that case belongs to
-   * the consumer's CSS. Mirrors `sidebar`'s `#restoreCollapsed`.
+   * the consumer's CSS.
    */
   connect() {
     this.#connected = true;
@@ -5421,7 +5434,7 @@ var CountdownController = class extends Controller {
   #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 —
+   * 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.
    */
@@ -6177,7 +6190,7 @@ var DataGridController = class extends Controller {
     const row = cell.closest("[role='row']");
     if (row && this.rowTargets.includes(row)) this.#toggleRow(row);
   }
-  /** Shared sort logic for both click and keyboard activation. */
+  /** Cycles a header's sort on keyboard activation and emits `sort`. */
   #cycleSort(header) {
     const direction = nextSortDirection(header.getAttribute("aria-sort") ?? "none");
     for (const other of this.columnHeaderTargets) {
@@ -6945,10 +6958,6 @@ var DirectUploadController = class extends Controller {
       this.#rows.delete(id);
     }
   }
-  /**
-   * Returns the widget to its pre-upload state just before Turbo caches the
-   * page, so the snapshot never replays rows for uploads that cannot resume.
-   */
   /**
    * Rewinds for the snapshot and reports what that discarded. An upload in flight
    * cannot survive the navigation, so a consumer mirroring the rows would keep a
@@ -6987,7 +6996,7 @@ var DirectUploadController = class extends Controller {
   #detail(event) {
     return event.detail ?? {};
   }
-  /** The file name every ActiveStorage `direct-upload:*` event carries. */
+  /** The event's file name, or `""` when it carries none. */
   #name(detail) {
     return detail.file?.name ?? "";
   }
@@ -7361,8 +7370,8 @@ var DrawerController = class extends Controller {
    * rather than being re-derived from the declarative `open` Value (which would
    * close a user-opened drawer). The `open` Value only seeds a genuinely fresh
    * render. We normalize to a clean closed baseline first so {@link open} runs its
-   * full reveal + trap activation — the {@link FocusTrap} is a fresh instance
-   * after a reconnect and must be re-activated.
+   * full reveal + trap activation — the {@link FocusTrap} is inactive after a
+   * disconnect and must be re-activated.
    */
   connect() {
     this.#connected = true;
@@ -8756,13 +8765,39 @@ var FocusController = class extends Controller {
     initialFocus: () => this.hasInitialTarget ? this.initialTarget : null,
     onEscape: () => this.deactivate()
   });
+  /**
+   * Whether this scope is currently trapping.
+   *
+   * Held here rather than read back from the trap: the trap releases itself
+   * before Turbo caches the page, so its own flag stops answering for the state
+   * this controller publishes on the element and in its events.
+   */
+  #active = false;
+  /**
+   * Returns the element to its untrapped form before Turbo copies the page. The
+   * trap performs its own release on the same event, so what is left is the hook
+   * this controller owns — carried into the snapshot it would describe a scope
+   * that is no longer trapping.
+   *
+   * Silent, like `disconnect()`: the page is about to be frozen, and a release
+   * nobody asked for is not a close to report.
+   */
+  #beforeCache = new BeforeCacheReset(() => {
+    this.#active = false;
+    this.element.removeAttribute("data-focus-trapped");
+  });
   /** Stimulus drives activation from the `trap` value (also fires on connect). */
   trapValueChanged() {
     if (this.trapValue) this.#activate();
     else this.#deactivate();
   }
+  connect() {
+    this.#beforeCache.activate();
+  }
   disconnect() {
     this.#trap.deactivate({ restoreFocus: false });
+    this.#beforeCache.deactivate();
+    this.#active = false;
     this.element.removeAttribute("data-focus-trapped");
   }
   /** Turns the trap on. Acts synchronously and keeps the `trap` value in sync. */
@@ -8776,13 +8811,15 @@ var FocusController = class extends Controller {
     this.#deactivate();
   }
   #activate() {
-    if (this.#trap.active) return;
+    if (this.#active) return;
+    this.#active = true;
     this.#trap.activate();
     this.element.setAttribute("data-focus-trapped", "true");
     this.dispatch("activate", { detail: {} });
   }
   #deactivate() {
-    if (!this.#trap.active) return;
+    if (!this.#active) return;
+    this.#active = false;
     this.#trap.deactivate({ restoreFocus: this.restoreValue });
     this.element.removeAttribute("data-focus-trapped");
     this.dispatch("deactivate", { detail: {} });
@@ -8800,7 +8837,7 @@ var FormFieldController = class _FormFieldController extends Controller {
   static #INVALID_ATTR = "data-stimeo--form-field-invalid";
   /** Collapses one target/morph batch into one silent ARIA reconciliation. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
-  /** ARIA ownership is scoped to the current singular control target. */
+  /** Returns borrowed control ARIA before Turbo snapshots the page. */
   #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #ariaDescribedBy = new AttributeLease("aria-describedby");
   #ariaErrorMessage = new AttributeLease("aria-errormessage");
@@ -11687,8 +11724,8 @@ var MenubarController = class extends Controller {
    * being hidden itself, a menu can stay visible after its owning top was removed,
    * an open pair can appear from a morph with no layer registered for it, and the
    * Tab stop can end up on a now-inert top, on a runtime-added one, or on none at
-   * all. Nothing is remembered between calls (except which side of the Escape stack
-   * this layer is on, which the stack itself does not expose), so the outcome is the
+   * all. The only state carried between calls is the tracked focus record and which side
+   * of the Escape stack this layer is on (which the stack itself does not expose), so the outcome is the
    * same whichever mutation arrived and calling it more often than needed is free.
    */
   #reconcile() {
@@ -12802,7 +12839,7 @@ var MultiSelectController = class extends Controller {
   get #values() {
     return this.#selectedOptions.map((option) => this.#optionValue(option));
   }
-  /** Normalized cardinality cap: zero is unlimited and positive fractions round down. */
+  /** Normalized cardinality cap: zero and below are unlimited; a positive value floors, never below 1. */
   get #selectionLimit() {
     if (!Number.isFinite(this.maxValue) || this.maxValue <= 0) return 0;
     return Math.max(1, Math.floor(this.maxValue));
@@ -14957,8 +14994,8 @@ var OverflowMenuController = class extends Controller {
    *
    * With no known child at all (a fresh instance connecting to markup that already
    * holds banked items), a fully-banked snapshot's inert boundary preserves whether an
-   * unindexed run was prepended or appended before connect. Older or server-rendered
-   * markup has no boundary; for that compatibility path the saved index is used as the
+   * unindexed run was prepended or appended before connect. Markup that holds banked items but no boundary —
+   * server-rendered or hand-authored — uses the saved index as the
    * offset, the inverse of the move that banked it.
    */
   #merge(bar, banked, boundaryAt) {
@@ -15370,6 +15407,7 @@ var PaginationController = class _PaginationController extends Controller {
     return button.hasAttribute(_PaginationController.#BOUNDARY_ATTR);
   }
 };
+var MAX_DELAY = 2 ** 31 - 1;
 var PasswordRevealController = class extends Controller {
   static targets = ["input", "toggle"];
   static values = {
@@ -15379,11 +15417,54 @@ var PasswordRevealController = class extends Controller {
   static events = ["toggle"];
   /** Auto re-mask timer; torn down on disconnect. */
   #timers = new SafeTimeout();
+  /**
+   * Whether this controller is between `connect()` and `disconnect()`.
+   *
+   * Target callbacks outlive the controller: Stimulus stops the target observer
+   * after `disconnect()`, so a field leaving after teardown still reaches
+   * {@link PasswordRevealController.inputTargetDisconnected}. Arming from there
+   * would put a timer back that nothing will clear. The element staying in the
+   * document does not answer this — unloading the controller leaves it there.
+   */
+  #connected = false;
+  /** Masks the field before Turbo copies the page into its snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindToMasked());
   connect() {
-    this.#reflect(this.#isVisible);
+    this.#connected = true;
+    const visible = this.#isVisible;
+    this.#reflect(visible);
+    this.#beforeCache.activate();
+    this.#arm(visible);
   }
   disconnect() {
+    this.#connected = false;
     this.#timers.clearAll();
+    this.#beforeCache.deactivate();
+  }
+  /** Re-derives the hooks and the re-mask for a field swapped in after connect. */
+  inputTargetConnected() {
+    const visible = this.#connected && this.#isVisible;
+    this.#reflect(visible);
+    this.#arm(visible);
+  }
+  /**
+   * Re-derives from whatever field is left rather than assuming none is. A swap
+   * delivers this callback next to the arrival in either order, so a revealed
+   * replacement that answered "masked" here would be described as hidden while
+   * showing the password, and would carry no re-mask.
+   *
+   * Teardown is the one case with nothing to derive: target callbacks run after
+   * `disconnect()`, so the field is still revealed and re-arming from it would
+   * outlive the controller. A detached root is the signal to stand down.
+   */
+  inputTargetDisconnected() {
+    const visible = this.#connected && this.element.isConnected && this.#isVisible;
+    this.#reflect(visible);
+    this.#arm(visible);
+  }
+  /** Re-derives the pressed state for a button swapped in after connect. */
+  toggleTargetConnected() {
+    this.#reflect(this.#isVisible);
   }
   /** Toggles the input between masked and revealed. Bound via `data-action`. */
   toggle() {
@@ -15412,11 +15493,37 @@ var PasswordRevealController = class extends Controller {
     }
     this.#reflect(visible);
     this.dispatch("toggle", { detail: { visible } });
+    this.#arm(visible);
+  }
+  /** Schedules the auto re-mask for a revealed field, replacing any pending one. */
+  #arm(visible) {
     this.#timers.clearAll();
-    if (visible && this.autoHideValue > 0) {
-      this.#timers.set(() => this.#setVisible(false), this.autoHideValue);
+    const delay = this.#autoHideDelay;
+    if (visible && delay > 0) {
+      this.#timers.set(() => this.#setVisible(false), delay);
     }
   }
+  /**
+   * The auto re-mask delay, held to what `setTimeout` can carry. Past that limit
+   * a delay folds to zero, turning "keep it showing" into "hide it at once" —
+   * the opposite of what the declaration asked for. A value that is no delay at
+   * all stays out of the positive range {@link PasswordRevealController.#arm}
+   * requires, so it schedules nothing.
+   */
+  get #autoHideDelay() {
+    return Math.min(this.autoHideValue, MAX_DELAY);
+  }
+  /**
+   * Returns the field to masked before Turbo copies the page. Silent and
+   * focus-free: the page is about to be frozen, so there is no one to tell and
+   * nowhere for focus to go.
+   */
+  #rewindToMasked() {
+    this.#timers.clearAll();
+    if (!this.hasInputTarget) return;
+    this.inputTarget.type = "password";
+    this.#reflect(false);
+  }
   /** Reflects the visible state onto `aria-pressed` and `data-state`. */
   #reflect(visible) {
     if (this.hasToggleTarget) {
@@ -15430,6 +15537,7 @@ var DEFAULT_LEVELS = ["weak", "fair", "good", "strong"];
 var LENGTH_MILESTONES = [8, 12, 16];
 var MAX_POINTS = LENGTH_MILESTONES.length + (CLASS_PATTERNS.length - 1);
 var STRENGTH_BANDS = ["weak", "fair", "good", "strong"];
+var MIN_LEVELS = 2;
 var PasswordStrengthController = class _PasswordStrengthController extends Controller {
   static targets = ["input", "meter", "label"];
   static values = {
@@ -15437,50 +15545,143 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
     // A JSON list read through `parseStringList` rather than Stimulus's `Array`
     // type: that reader throws out of the value observer before any callback
     // runs, so one malformed attribute would stop the meter connecting.
-    levels: { type: String, default: "" }
+    levels: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
-  static actions = ["evaluate"];
-  static events = ["change"];
-  /** Delay (ms) before the polite live-region label is written, to throttle SR flooding. */
+  static actions = ["evaluate", "setScore"];
+  static events = ["change", "reconcile"];
+  /** Delay (ms) before one settled level is sent to the shared announcer. */
   static #announceDelay = 200;
   #timers = new SafeTimeout();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #repaint = new MicrotaskCoalescer(() => this.#reconcile());
+  #levels = [...DEFAULT_LEVELS];
   #announceId = null;
+  #announcedLevel = null;
+  #externalScore = null;
+  #lastDetail = null;
+  /** Reflects the current DOM state and opens the reconciliation window. */
   connect() {
-    this.#update({ announce: false });
+    this.#repaint.activate();
+    this.#beforeCache.activate();
+    this.#lastDetail = this.#detail(this.#render());
   }
+  /** Releases the reconciliation window, the cache subscription and the debounce. */
   disconnect() {
-    this.#timers.clearAll();
-    this.#announceId = null;
+    this.#repaint.cancel();
+    this.#beforeCache.deactivate();
+    this.#cancelAnnouncement();
+    this.#announcedLevel = null;
+    this.#externalScore = null;
+    this.#lastDetail = null;
   }
   /** Re-evaluates strength from the input. Bound via `data-action` (`input`). */
   evaluate() {
-    this.#update();
+    this.#externalScore = null;
+    this.#commit();
+  }
+  /**
+   * Adopts a score computed outside the built-in heuristic, clamped into the
+   * declared scale. An unreadable value leaves the current score standing, and
+   * the next `evaluate` hands scoring back to the heuristic.
+   */
+  setScore(event) {
+    const next = toFiniteNumber(event.params?.score ?? event.detail?.score);
+    if (next === null) return;
+    this.#externalScore = next;
+    this.#commit();
+  }
+  /** Re-reads the scale when application code or a Turbo morph changes `levels`. */
+  levelsValueChanged() {
+    this.#levels = this.#readLevels();
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `minScore`. */
+  minScoreValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Repaints when application code or a Turbo morph changes `announceText`. */
+  announceTextValueChanged() {
+    this.#repaint.schedule();
+  }
+  /** Scores the field added or replaced at runtime. */
+  inputTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Falls back to the pristine state after the scored field is removed. */
+  inputTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Syncs a meter added or replaced at runtime, which carries no value yet. */
+  meterTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints the remaining output after a meter is removed. */
+  meterTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Fills a readout added or replaced at runtime. */
+  labelTargetConnected() {
+    this.#repaint.schedule();
+  }
+  /** Repaints the remaining output after a readout is removed. */
+  labelTargetDisconnected() {
+    this.#repaint.schedule();
+  }
+  /** Reflects one confirmed scoring pass and offers its level to the reader. */
+  #commit() {
+    const reading = this.#render();
+    this.#lastDetail = this.#detail(reading);
+    this.dispatch("change", { detail: this.#lastDetail });
+    this.#scheduleAnnouncement(reading);
+  }
+  /** Repaints one mutation batch and reports a changed controller-derived state. */
+  #reconcile() {
+    const previous = this.#lastDetail;
+    const owed = this.#announceId !== null;
+    this.#cancelAnnouncement();
+    const reading = this.#render();
+    const detail = this.#detail(reading);
+    this.#lastDetail = detail;
+    if (reading.score === 0) this.#announcedLevel = null;
+    if (owed) this.#scheduleAnnouncement(reading);
+    if (previous && this.#detailsDiffer(previous, detail)) {
+      this.dispatch("reconcile", { detail });
+    }
   }
   /**
-   * Recomputes the strength. The meter ARIA, data hooks, the custom property and
-   * the `change` event apply immediately; the live-region label text is debounced
-   * unless `announce` is `false` (the initial render).
+   * Synchronizes the meter ARIA, the root state hooks, the fill custom property
+   * and the visible level readout.
+   *
+   * @stimeoRenderRoot
    */
-  #update(options = {}) {
-    const password = this.hasInputTarget ? this.inputTarget.value : "";
-    const labels = parseStringList(this.levelsValue, DEFAULT_LEVELS);
-    const max = labels.length;
-    const score = this.#score(password, max);
-    const label = score > 0 ? labels[score - 1] ?? "" : "";
+  #render() {
+    const max = this.#levels.length;
+    const score = this.#currentScore(max);
+    const level = this.#levels[score - 1] ?? "";
+    const meetsMin = score > 0 && score >= this.#minScore;
+    const band = this.#band(score, max);
     this.#reflectMeter(score, max);
-    this.#reflectRoot(score, max);
-    if (options.announce === false) {
-      this.#writeLabel(label);
-      return;
+    this.#reflectRoot(score, max, band, meetsMin);
+    this.#writeLabel(level);
+    return { score, level, max, meetsMin, band };
+  }
+  /**
+   * The declared minimum, or the Value's default (`0`, an inert gate) when the
+   * declaration cannot be read as a number. Every comparison against an unread
+   * number answers false, which would fail even the strongest password instead
+   * of leaving the gate off, so the unreadable declaration is confined to its
+   * own Value the way an unreadable scale is.
+   */
+  get #minScore() {
+    return Number.isFinite(this.minScoreValue) ? this.minScoreValue : 0;
+  }
+  /** The externally supplied score when one stands, else the heuristic's. */
+  #currentScore(max) {
+    if (this.#externalScore !== null) {
+      return Math.min(max, Math.max(0, Math.round(this.#externalScore)));
     }
-    this.dispatch("change", {
-      detail: { score, level: label, max, meetsMin: score > 0 && score >= this.minScoreValue }
-    });
-    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
-    this.#announceId = this.#timers.set(() => {
-      this.#writeLabel(label);
-      this.#announceId = null;
-    }, _PasswordStrengthController.#announceDelay);
+    return this.#score(this.hasInputTarget ? this.inputTarget.value : "", max);
   }
   /** Syncs the meter target's ARIA value attributes (`0..levels.length`). */
   #reflectMeter(score, max) {
@@ -15494,25 +15695,27 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
    * empty), the `data-below-min` hook when the score is under `minScore`, and the
    * `0–1` fill the consumer's CSS turns into the bar width.
    */
-  #reflectRoot(score, max) {
-    const band = this.#band(score, max);
+  #reflectRoot(score, max, band, meetsMin) {
     this.#toggle("data-strength", band, band.length > 0);
-    this.#toggle("data-below-min", "true", score > 0 && score < this.minScoreValue);
-    const ratio = max > 0 ? score / max : 0;
-    this.element.style.setProperty("--stimeo--password-strength", String(ratio));
+    this.#toggle("data-below-min", "true", score > 0 && !meetsMin);
+    this.element.style.setProperty("--stimeo--password-strength", String(score / max));
   }
-  #writeLabel(label) {
-    if (this.hasLabelTarget) this.labelTarget.textContent = label;
+  /** Writes the visible readout only when its text actually changed. */
+  #writeLabel(text) {
+    if (!this.hasLabelTarget || this.labelTarget.textContent === text) return;
+    this.labelTarget.textContent = text;
   }
   /**
    * Locale-independent styling band (one of {@link STRENGTH_BANDS}) for `score`
-   * out of `max`. Empty input → `""`. Quantizes the `score/max` ratio into the
-   * four fixed bands, so a non-default level count still maps onto a stable hook.
+   * out of `max`. Empty input → `""`. Maps the position within the declared scale
+   * onto the position within the fixed bands, so both ends stay anchored on any
+   * level count: the weakest score is always `weak` and the strongest `strong`,
+   * and only the middle collapses when the scales differ in size.
    */
   #band(score, max) {
-    if (score <= 0 || max <= 0) return "";
-    const index = Math.ceil(score / max * STRENGTH_BANDS.length) - 1;
-    return STRENGTH_BANDS[Math.min(STRENGTH_BANDS.length - 1, Math.max(0, index))] ?? "";
+    if (score <= 0) return "";
+    const index = Math.round((score - 1) / (max - 1) * (STRENGTH_BANDS.length - 1));
+    return STRENGTH_BANDS[index] ?? STRENGTH_BANDS[0];
   }
   /** Sets `name` to `value` when `on`, else removes it (value/presence data hook). */
   #toggle(name, value, on) {
@@ -15522,6 +15725,11 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
       this.element.removeAttribute(name);
     }
   }
+  /** The declared level labels, or the defaults when the scale cannot order. */
+  #readLevels() {
+    const declared = parseStringList(this.levelsValue, DEFAULT_LEVELS);
+    return declared.length >= MIN_LEVELS ? declared : [...DEFAULT_LEVELS];
+  }
   /**
    * Lightweight zero-dependency strength heuristic returning an integer in
    * `[0, max]` (`max` = number of levels). Empty input is `0` (no level); any
@@ -15531,7 +15739,7 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
    * alone cannot mask trivial repetition.
    */
   #score(password, max) {
-    if (password.length === 0 || max === 0) return 0;
+    if (password.length === 0) return 0;
     let points = 0;
     for (const milestone of LENGTH_MILESTONES) {
       if (password.length >= milestone) points += 1;
@@ -15541,6 +15749,64 @@ var PasswordStrengthController = class _PasswordStrengthController extends Contr
     const bucketed = Math.round(points / MAX_POINTS * max);
     return Math.min(max, Math.max(1, bucketed));
   }
+  /** Debounces one i18n-neutral message for a level transition into the announcer. */
+  #scheduleAnnouncement(reading) {
+    this.#cancelAnnouncement();
+    if (reading.score === 0) {
+      this.#announcedLevel = null;
+      return;
+    }
+    if (reading.level === this.#announcedLevel) return;
+    const message = fillTemplate(this.announceTextValue, {
+      level: reading.level,
+      score: reading.score,
+      max: reading.max,
+      band: reading.band
+    });
+    if (message.trim().length === 0) return;
+    this.#announceId = this.#timers.set(() => {
+      this.#announcedLevel = reading.level;
+      announce(message);
+      this.#announceId = null;
+    }, _PasswordStrengthController.#announceDelay);
+  }
+  /** Cancels the one outstanding message without touching visible output. */
+  #cancelAnnouncement() {
+    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
+    this.#announceId = null;
+  }
+  /**
+   * Returns every output derived from the field value to its pristine form.
+   *
+   * The value itself is not carried in a Turbo snapshot, so a band, a fill or a
+   * readout left behind would describe a password the restored page no longer
+   * holds. The pass is silent: `connect()` derives the state again from whatever
+   * the restored field contains.
+   */
+  #rewindForCache() {
+    this.#cancelAnnouncement();
+    this.#announcedLevel = null;
+    this.#externalScore = null;
+    this.#lastDetail = null;
+    this.#reflectMeter(0, this.#levels.length);
+    this.#toggle("data-strength", "", false);
+    this.#toggle("data-below-min", "true", false);
+    this.element.style.removeProperty("--stimeo--password-strength");
+    this.#writeLabel("");
+  }
+  /** Selects the public event state from the richer internal reading. */
+  #detail(reading) {
+    return {
+      score: reading.score,
+      level: reading.level,
+      max: reading.max,
+      meetsMin: reading.meetsMin
+    };
+  }
+  /** Compares exactly the state carried by `change` and `reconcile`. */
+  #detailsDiffer(left, right) {
+    return left.score !== right.score || left.level !== right.level || left.max !== right.max || left.meetsMin !== right.meetsMin;
+  }
 };
 
 // src/utils/safe_storage.ts
@@ -18326,7 +18592,7 @@ var ResizableController = class extends Controller {
       this.#dispatchChange();
     }
   }
-  /** Double-click or Enter to collapse the primary pane, or put it back. */
+  /** Collapses the primary pane to its minimum, or returns it to the last position. */
   toggle() {
     const { min, max } = this.#range;
     if (this.#position > min) {
@@ -18908,6 +19174,17 @@ var ScrollAreaController = class extends Controller {
     this.#clearHostState();
   }
 };
+function parseStored(raw) {
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function storedOffset(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
 var ScrollRestoreController = class extends Controller {
   static values = {
     key: { type: String, default: "" },
@@ -18920,6 +19197,26 @@ var ScrollRestoreController = class extends Controller {
   /** Last offset captured while the element was live; persisted as-is on teardown. */
   #lastTop = 0;
   #lastLeft = 0;
+  /**
+   * The offsets this controller's own restore produced, awaiting the `scroll`
+   * the engine fires for them. A restore the layout cannot reach yet lands short,
+   * so treating that echo as the reader's position would cut the saved offset
+   * down to whatever the unfinished layout allowed.
+   */
+  #echoTop = null;
+  #echoLeft = null;
+  /** Offsets stored for an axis that is not tracked, carried through saves. */
+  #carried = {};
+  /**
+   * Whether each axis holds an offset worth saving — one this namespace restored
+   * or the reader moved. A save writes only the axes that are marked, so an
+   * offset taken under a different key or axis is never re-published as if the
+   * reader had left it there.
+   */
+  #capturedTop = false;
+  #capturedLeft = false;
+  /** Whether the controller is connected; Value callbacks outside that window do not resync. */
+  #connected = false;
   #onScroll = () => {
     this.#capture();
     if (this.#rafId !== null) return;
@@ -18929,58 +19226,127 @@ var ScrollRestoreController = class extends Controller {
     });
   };
   connect() {
+    this.#connected = true;
     this.#storageKey = this.#resolveKey();
-    if (!this.#storageKey) return;
-    this.#restore();
     this.element.addEventListener("scroll", this.#onScroll, { passive: true });
+    if (this.#storageKey) this.#restore();
   }
   disconnect() {
-    if (!this.#storageKey) return;
+    this.#connected = false;
     this.element.removeEventListener("scroll", this.#onScroll);
+    this.#cancelFrame();
+    this.#persist();
+  }
+  /** Re-derives the namespace when application code or a Turbo morph moves `key`. */
+  keyValueChanged() {
+    this.#resync();
+  }
+  /** Re-derives the tracked axes when application code or a Turbo morph moves `axis`. */
+  axisValueChanged() {
+    this.#resync();
+  }
+  /** Rebuilds the persistence state around the Values as they now read. */
+  #resync() {
+    if (!this.#connected) return;
+    this.#cancelFrame();
+    this.#storageKey = this.#resolveKey();
+    this.#echoTop = null;
+    this.#echoLeft = null;
+    this.#carried = {};
+    this.#capturedTop = false;
+    this.#capturedLeft = false;
+    if (this.#storageKey) this.#restore();
+  }
+  /** Drops the pending coalesced save, if one is queued. */
+  #cancelFrame() {
     if (this.#rafId !== null) {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;
     }
-    this.#persist();
   }
-  /** Records the live scroll offset for the configured axis. */
+  /**
+   * Records the live scroll offset for the configured axis.
+   *
+   * An axis holds its echo until that axis actually moves. A scroll event names
+   * no axis, so consuming both on the first one to arrive would leave the other
+   * unguarded: on `both`, moving one axis would take the clamped reading of the
+   * untouched axis as the reader's own position and save it, cutting the stored
+   * offset down to whatever the layout could reach at restore time.
+   */
   #capture() {
-    if (this.#tracksVertical) this.#lastTop = this.element.scrollTop;
-    if (this.#tracksHorizontal) this.#lastLeft = this.element.scrollLeft;
+    if (this.#tracksVertical) {
+      const top = this.element.scrollTop;
+      if (top !== this.#echoTop) {
+        this.#echoTop = null;
+        this.#lastTop = top;
+        this.#capturedTop = true;
+      }
+    }
+    if (this.#tracksHorizontal) {
+      const left = this.element.scrollLeft;
+      if (left !== this.#echoLeft) {
+        this.#echoLeft = null;
+        this.#lastLeft = left;
+        this.#capturedLeft = true;
+      }
+    }
   }
-  /** Persists the last captured scroll offset for the configured axis. */
+  /**
+   * Writes the marked axes, carrying through any offset held for an untracked one.
+   * Without a key, or with neither axis marked, it writes nothing.
+   */
   #persist() {
-    const data = {};
-    if (this.#tracksVertical) data.top = this.#lastTop;
-    if (this.#tracksHorizontal) data.left = this.#lastLeft;
+    if (!this.#storageKey || !(this.#capturedTop || this.#capturedLeft)) return;
+    const data = { ...this.#carried };
+    if (this.#tracksVertical && this.#capturedTop) data.top = this.#lastTop;
+    if (this.#tracksHorizontal && this.#capturedLeft) data.left = this.#lastLeft;
     try {
-      sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
+      window.sessionStorage.setItem(this.#storageKey, JSON.stringify(data));
     } catch {
     }
   }
   /** Applies the persisted scroll offset, if any, without moving focus. */
   #restore() {
-    let raw = null;
-    try {
-      raw = sessionStorage.getItem(this.#storageKey);
-    } catch {
-      return;
-    }
-    if (raw === null) return;
-    let data;
+    let raw;
     try {
-      data = JSON.parse(raw);
+      raw = window.sessionStorage.getItem(this.#storageKey);
     } catch {
       return;
     }
-    if (this.#tracksVertical && typeof data.top === "number") {
-      this.element.scrollTop = data.top;
-      this.#lastTop = data.top;
-    }
-    if (this.#tracksHorizontal && typeof data.left === "number") {
-      this.element.scrollLeft = data.left;
-      this.#lastLeft = data.left;
+    const data = parseStored(raw);
+    if (data === null) return;
+    this.#echoTop = null;
+    this.#echoLeft = null;
+    const top = storedOffset(data.top);
+    const left = storedOffset(data.left);
+    const options = { behavior: "instant" };
+    let requested = false;
+    if (this.#tracksVertical) {
+      if (top !== null) {
+        options.top = top;
+        this.#lastTop = top;
+        this.#capturedTop = true;
+        requested = true;
+      }
+    } else if (data.top !== void 0) {
+      this.#carried.top = data.top;
+    }
+    if (this.#tracksHorizontal) {
+      if (left !== null) {
+        options.left = left;
+        this.#lastLeft = left;
+        this.#capturedLeft = true;
+        requested = true;
+      }
+    } else if (data.left !== void 0) {
+      this.#carried.left = data.left;
     }
+    if (!requested) return;
+    const beforeTop = this.element.scrollTop;
+    const beforeLeft = this.element.scrollLeft;
+    this.element.scrollTo(options);
+    if (this.element.scrollTop !== beforeTop) this.#echoTop = this.element.scrollTop;
+    if (this.element.scrollLeft !== beforeLeft) this.#echoLeft = this.element.scrollLeft;
   }
   /** The `sessionStorage` key: explicit `key`, else the element `id`, else none. */
   #resolveKey() {
@@ -18994,10 +19360,11 @@ var ScrollRestoreController = class extends Controller {
     return this.axisValue === "horizontal" || this.axisValue === "both";
   }
 };
+var DEFAULT_OFFSET = 400;
 var ScrollVisibilityController = class extends Controller {
   static targets = ["element"];
   static values = {
-    offset: { type: Number, default: 400 },
+    offset: { type: Number, default: DEFAULT_OFFSET },
     mode: { type: String, default: "offset" },
     focusSelector: { type: String, default: "" },
     root: { type: String, default: "" }
@@ -19015,8 +19382,32 @@ var ScrollVisibilityController = class extends Controller {
    * the window. Captured on connect so teardown detaches from the same source.
    */
   #scrollSource = window;
+  /**
+   * Gates the declaration callbacks to the connected window.
+   *
+   * Stimulus delivers a Value callback ahead of `connect()` and again for every
+   * runtime change; without the gate, merely connecting would evaluate — and
+   * announce — before `connect()` runs its own first reflection.
+   */
+  #connected = false;
+  /** Validated threshold; a non-finite declaration reads as the default. */
+  #offset = DEFAULT_OFFSET;
+  /** Validated `root` selector; an unparsable declaration reads as absent. */
+  #rootSelector = "";
+  /** Validated `focusSelector`; an unparsable declaration reads as absent. */
+  #focusSelector = "";
   /** Focus targets this instance lent a `tabindex` to. */
   #tabindex = new TabindexLoan();
+  /**
+   * The hide held back while the control itself owns focus.
+   *
+   * Completing the deferral re-runs the ordinary evaluation rather than applying
+   * the stale decision: by the time focus leaves, the scroll position may have
+   * moved back past the threshold.
+   */
+  #pendingHide = new BlurDeferral(() => {
+    if (this.#connected) this.#evaluate();
+  });
   #onScroll = () => {
     if (this.#rafId !== null) return;
     this.#rafId = requestAnimationFrame(() => {
@@ -19028,61 +19419,134 @@ var ScrollVisibilityController = class extends Controller {
     this.#scrollSource = this.#resolveScrollSource();
     this.#lastScrollY = this.#scrollY();
     this.#scrollSource.addEventListener("scroll", this.#onScroll, { passive: true });
-    this.#evaluate();
+    this.#evaluate(false);
+    this.#connected = true;
   }
   disconnect() {
+    this.#connected = false;
     this.#scrollSource.removeEventListener("scroll", this.#onScroll);
     if (this.#rafId !== null) {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;
     }
+    this.#pendingHide.releaseAll();
     this.#tabindex.returnAll();
     this.#visible = null;
   }
+  /** Writes the current visibility onto a control that arrives after connect. */
+  elementTargetConnected(element) {
+    if (this.#visible !== null) element.hidden = !this.#visible;
+  }
+  /** Drops a held-back hide together with the control it was waiting on. */
+  elementTargetDisconnected() {
+    this.#pendingHide.releaseAll();
+  }
+  /**
+   * Validates `offset` once, then re-renders.
+   *
+   * Re-renders when application code (or a Turbo morph) changes `offset` at
+   * runtime. A declaration that is not a finite number reads as the default, so
+   * the comparison path never sees `NaN` — which would answer `false` to every
+   * comparison and strand the element (in `direction` mode, even the guarantee
+   * that the very top always reveals).
+   */
+  offsetValueChanged() {
+    this.#offset = Number.isFinite(this.offsetValue) ? this.offsetValue : DEFAULT_OFFSET;
+    if (this.#connected) this.#evaluate();
+  }
+  /** Re-renders when application code (or a Turbo morph) changes `mode` at runtime. */
+  modeValueChanged() {
+    if (this.#connected) this.#evaluate();
+  }
+  /** Validates `root` once so connect never parses a selector that throws. */
+  rootValueChanged() {
+    this.#rootSelector = this.#validSelector(this.rootValue);
+  }
+  /** Validates `focusSelector` once so `toTop` never parses a selector that throws. */
+  focusSelectorValueChanged() {
+    this.#focusSelector = this.#validSelector(this.focusSelectorValue);
+  }
   /** Scrolls the source to the top and, optionally, moves focus to a safe target. */
   toTop() {
     const behavior = prefersReducedMotion() ? "instant" : "smooth";
     this.#scrollSource.scrollTo({ top: 0, behavior });
-    if (this.focusSelectorValue) {
-      const target = document.querySelector(this.focusSelectorValue);
+    if (this.#focusSelector) {
+      const target = document.querySelector(this.#focusSelector);
       if (target) {
         this.#tabindex.lend(target);
-        target.focus();
+        target.focus({ preventScroll: true });
       }
     }
   }
-  /** Decides the next visibility from the current scroll state and applies it. */
-  #evaluate() {
+  /**
+   * Decides the next visibility from the current scroll state and applies it.
+   *
+   * @param notify - whether a transition announces itself. The reflection
+   *   `connect()` performs is the current state, not a change.
+   *
+   * @stimeoRenderRoot
+   */
+  #evaluate(notify = true) {
     const y = this.#scrollY();
     let nextVisible;
     if (this.modeValue === "direction") {
-      if (y <= this.offsetValue) {
+      if (y <= this.#offset) {
         nextVisible = true;
+      } else if (y === this.#lastScrollY) {
+        return;
       } else {
         nextVisible = y < this.#lastScrollY;
       }
     } else {
-      nextVisible = y > this.offsetValue;
+      nextVisible = y > this.#offset;
     }
     this.#lastScrollY = y;
-    this.#setVisible(nextVisible);
+    this.#setVisible(nextVisible, notify);
   }
   /** Applies visibility to the target, syncing `hidden`, `data-state`, `change`. */
-  #setVisible(next) {
+  #setVisible(next, notify) {
     if (next === this.#visible) return;
+    const focused = !next && this.hasElementTarget ? this.#focusedWithin() : null;
+    if (focused) {
+      this.#pendingHide.deferOnly(focused);
+      return;
+    }
     this.#visible = next;
     if (this.hasElementTarget) this.elementTarget.hidden = !next;
     this.element.setAttribute("data-state", next ? "visible" : "hidden");
-    this.dispatch("change", { detail: { visible: next } });
+    if (notify) this.dispatch("change", { detail: { visible: next } });
   }
   /** Resolves the scroll source from `root` (falling back to the window). */
   #resolveScrollSource() {
-    if (this.rootValue) {
-      const root = document.querySelector(this.rootValue);
+    if (this.#rootSelector) {
+      const root = document.querySelector(this.#rootSelector);
       if (root) return root;
     }
     return window;
   }
+  /**
+   * The focus owner inside the target, or `null` when focus is elsewhere.
+   *
+   * `blur` does not bubble, so the deferral has to ride the focused element
+   * itself: waiting on a container that never receives the event would hold the
+   * hide forever.
+   */
+  #focusedWithin() {
+    const focused = document.activeElement;
+    if (focused instanceof HTMLElement && this.elementTarget.contains(focused)) return focused;
+    return null;
+  }
+  /** Returns `declared` when it parses as a selector, and `""` when it does not. */
+  #validSelector(declared) {
+    if (declared.length > 0) {
+      try {
+        this.element.matches(declared);
+        return declared;
+      } catch {
+      }
+    }
+    return "";
+  }
   #scrollY() {
     if (this.#scrollSource === window) {
       return window.scrollY ?? window.pageYOffset ?? 0;
@@ -20650,11 +21114,6 @@ 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
@@ -21944,35 +22403,48 @@ var TextareaAutosizeController = class extends Controller {
 };
 var MODES = ["light", "dark", "system"];
 var isMode = (value) => typeof value === "string" && MODES.includes(value);
+var DEFAULT_MODE = "system";
+var DEFAULT_TARGET = "html";
 var ThemeController = class extends Controller {
   static targets = ["option"];
   static values = {
-    mode: { type: String, default: "system" },
+    mode: { type: String, default: DEFAULT_MODE },
     storageKey: { type: String, default: "stimeo-theme" },
-    target: { type: String, default: "html" }
+    target: { type: String, default: DEFAULT_TARGET }
   };
   static actions = ["set", "toggle"];
   static events = ["change"];
   /** The OS dark-mode query, watched so `system` tracks live changes. */
   #media = null;
+  /** Gate for the target callbacks, which Stimulus runs before `connect()`. */
+  #connected = false;
+  /** The `target` declaration after validation; the default when unparsable. */
+  #targetSelector = DEFAULT_TARGET;
+  /** Owns the single Tab stop across the option set (APG radiogroup). */
+  #roving = new RovingTabindex(() => this.optionTargets);
+  /**
+   * The pair last reported, so a move can be told from a repeat. Neither side is
+   * readable after the fact — assigning the Value updates the mode before any
+   * comparison, and the OS query has already flipped by the time it notifies —
+   * so what was reported has to be kept rather than recomputed.
+   */
+  #published = {
+    mode: DEFAULT_MODE,
+    resolved: "light"
+  };
   /** Re-resolves while in `system` mode when the OS preference flips. */
   #onMediaChange = () => {
-    if (this.modeValue === "system") {
-      this.#applyTheme();
-      this.#syncControls();
-      this.#dispatchChange();
-    }
+    if (this.#mode !== "system") return;
+    this.#commit();
   };
   /** Arrow/Home/End navigation for the radiogroup (APG radio pattern). */
   #onKeydown = (event) => {
     if (event.defaultPrevented) return;
     if (isReservedArrowChord(event)) return;
     const options = this.optionTargets;
-    if (options.length === 0) return;
     const target = event.target;
     const current = options.indexOf(target);
     if (current === -1) return;
-    const last = options.length - 1;
     let next = current;
     const step = logicalArrowStep(event.key, this.element);
     switch (event.key) {
@@ -21980,13 +22452,12 @@ var ThemeController = class extends Controller {
       case "ArrowRight":
       case "ArrowUp":
       case "ArrowLeft":
-        next = step === 1 ? current === last ? 0 : current + 1 : current === 0 ? last : current - 1;
+        next = rovingMove(current, options.length, step, "wrap");
         break;
       case "Home":
-        next = 0;
-        break;
       case "End":
-        next = last;
+        if (hasModifierChord(event)) return;
+        next = event.key === "Home" ? 0 : options.length - 1;
         break;
       default:
         return;
@@ -21995,25 +22466,58 @@ var ThemeController = class extends Controller {
     const option = options[next];
     if (!option) return;
     option.focus();
-    this.#setMode(this.#optionMode(option));
+    const mode = this.#optionMode(option);
+    if (mode) this.#setMode(mode);
   };
   connect() {
     const stored = this.#readStored();
     if (stored) this.modeValue = stored;
     this.#media = window.matchMedia?.("(prefers-color-scheme: dark)") ?? null;
     this.#media?.addEventListener("change", this.#onMediaChange);
-    if (this.hasOptionTarget) this.element.addEventListener("keydown", this.#onKeydown);
+    this.element.addEventListener("keydown", this.#onKeydown);
+    this.#connected = true;
     this.#applyTheme();
     this.#syncControls();
+    this.#published = this.#current;
   }
   disconnect() {
+    this.#connected = false;
     this.#media?.removeEventListener("change", this.#onMediaChange);
     this.element.removeEventListener("keydown", this.#onKeydown);
   }
-  /** Selects an explicit mode from the `mode` action param (radiogroup option). */
+  /** Validates the `target` declaration once, so the render path never parses. */
+  targetValueChanged() {
+    const selector = this.targetValue;
+    if (selector.length > 0) {
+      try {
+        this.element.matches(selector);
+        this.#targetSelector = selector;
+        return;
+      } catch {
+      }
+    }
+    this.#targetSelector = DEFAULT_TARGET;
+  }
+  /** Re-derives the single Tab stop and ARIA for an option set that changed. */
+  optionTargetConnected() {
+    if (this.#connected) this.#syncControls();
+  }
+  /** Re-derives them again when an option leaves, so a Tab stop always remains. */
+  optionTargetDisconnected() {
+    if (this.#connected) this.#syncControls();
+  }
+  /**
+   * Selects the mode the activated option declares.
+   *
+   * Read through {@link ThemeController.#optionMode}, the same lane that decides
+   * which option is checked, so the two can never disagree about what an option
+   * declares.
+   */
   set(event) {
-    const mode = event.params?.mode;
-    if (isMode(mode)) this.#setMode(mode);
+    const option = event.currentTarget;
+    if (!(option instanceof HTMLElement)) return;
+    const mode = this.#optionMode(option);
+    if (mode) this.#setMode(mode);
   }
   /** Toggles light↔dark for the 2-value single-button contract. */
   toggle() {
@@ -22023,9 +22527,26 @@ var ThemeController = class extends Controller {
   #setMode(mode) {
     this.modeValue = mode;
     this.#writeStored(mode);
+    this.#commit();
+  }
+  /**
+   * Applies the current mode and reports it, but reports only a real move: the
+   * event means "the selection or the effective theme moved", so re-choosing the
+   * option already chosen is not one.
+   */
+  #commit() {
     this.#applyTheme();
     this.#syncControls();
-    this.#dispatchChange();
+    const next = this.#current;
+    const last = this.#published;
+    this.#published = next;
+    if (last.mode !== next.mode || last.resolved !== next.resolved) {
+      this.dispatch("change", { detail: { ...next } });
+    }
+  }
+  /** The pair the `change` detail carries, read from current state. */
+  get #current() {
+    return { mode: this.#mode, resolved: this.#resolved() };
   }
   /** Writes `data-theme` + `color-scheme` (the resolved theme) onto the target. */
   #applyTheme() {
@@ -22039,39 +22560,45 @@ var ThemeController = class extends Controller {
   #syncControls() {
     const options = this.optionTargets;
     if (options.length > 0) {
-      let hasTabbable = false;
-      for (const option of options) {
-        const selected = this.#optionMode(option) === this.modeValue;
-        option.setAttribute("aria-checked", String(selected));
-        option.tabIndex = selected ? 0 : -1;
-        hasTabbable ||= selected;
-      }
-      const first = options[0];
-      if (!hasTabbable && first) first.tabIndex = 0;
+      const mode = this.#mode;
+      let selected = -1;
+      options.forEach((option, index) => {
+        const isSelected = this.#optionMode(option) === mode;
+        option.setAttribute("aria-checked", String(isSelected));
+        if (isSelected && selected === -1) selected = index;
+      });
+      this.#roving.setActive(selected === -1 ? 0 : selected, { items: options });
       return;
     }
-    this.element.setAttribute("aria-pressed", String(this.#resolved() === "dark"));
+    if (this.#isToggleButton) {
+      this.element.setAttribute("aria-pressed", String(this.#resolved() === "dark"));
+    }
   }
-  /** Emits `change` with the selected mode and the resolved theme. */
-  #dispatchChange() {
-    this.dispatch("change", { detail: { mode: this.modeValue, resolved: this.#resolved() } });
+  /** Whether the controller element is the button of the 2-value contract. */
+  get #isToggleButton() {
+    return this.element.tagName === "BUTTON" || this.element.getAttribute("role") === "button";
+  }
+  /** The selected mode after validation; an unreadable declaration is the default. */
+  get #mode() {
+    return isMode(this.modeValue) ? this.modeValue : DEFAULT_MODE;
   }
   /** The effective theme: the OS preference when `system`, else the mode itself. */
   #resolved() {
-    if (this.modeValue === "dark") return "dark";
-    if (this.modeValue === "light") return "light";
+    const mode = this.#mode;
+    if (mode === "dark") return "dark";
+    if (mode === "light") return "light";
     return this.#media?.matches ? "dark" : "light";
   }
-  /** Reads an option's mode from its action param attribute. */
+  /** An option's mode from its `data-value`, or `null` when that is not one of the three. */
   #optionMode(option) {
-    const mode = option.getAttribute("data-stimeo--theme-mode-param");
-    return isMode(mode) ? mode : "system";
+    const mode = option.getAttribute("data-value");
+    return isMode(mode) ? mode : null;
   }
   /** Resolves the state-hook target (`<html>` by default). */
   #targetElement() {
-    if (this.targetValue === "html" || this.targetValue === ":root")
-      return document.documentElement;
-    return document.querySelector(this.targetValue);
+    const selector = this.#targetSelector;
+    if (selector === DEFAULT_TARGET || selector === ":root") return document.documentElement;
+    return document.querySelector(selector);
   }
   /** Reads a persisted, validated mode from `localStorage` (null when absent/blocked). */
   #readStored() {
@@ -22528,8 +23055,8 @@ var ToastController = class extends Controller {
   }
   /**
    * Stimulus lifecycle callback triggered automatically when a new item target
-   * enters the DOM. Perfectly handles dynamic client-side injections and server-side
-   * Turbo Stream appends alike.
+   * enters the DOM, from a client-side injection or a Turbo Stream append alike. An
+   * item already leaving, or parented outside `list`, is skipped.
    */
   itemTargetConnected(element) {
     this.enforceMaxLimit();
@@ -23495,12 +24022,21 @@ var TransitionController = class extends Controller {
   static events = ["entered", "left"];
   /** Owns the cancellable completion wait (terminal events + bounded fallback). */
   #transition = new TransitionCompletion();
+  /** Rewinds a half-applied stage before Turbo copies the page into its snapshot. */
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
   #rafId = null;
+  /**
+   * Stage classes this controller put on the element. Removing by declaration
+   * instead would take a token the consumer also authored, and would strand the
+   * token that was applied when a Value changes mid-transition.
+   */
+  #staged = /* @__PURE__ */ new Set();
   connect() {
-    this.#strip();
-    this.element.setAttribute("data-transition-state", this.element.hidden ? "left" : "entered");
+    this.#beforeCache.activate();
+    this.#settleState();
   }
   disconnect() {
+    this.#beforeCache.deactivate();
     this.#cancel();
   }
   /** Shows the element with the enter transition. */
@@ -23530,6 +24066,7 @@ var TransitionController = class extends Controller {
     const from = isEnter ? this.enterFromValue : this.leaveFromValue;
     const to = isEnter ? this.enterToValue : this.leaveToValue;
     this.#add(base, from);
+    void this.element.offsetWidth;
     this.#rafId = this.#raf(() => {
       this.#rafId = null;
       this.#remove(from);
@@ -23551,6 +24088,21 @@ var TransitionController = class extends Controller {
       this.dispatch("left", { detail: {} });
     }
   }
+  /** Writes the state hook the element's visibility implies. */
+  #settleState() {
+    this.element.setAttribute("data-transition-state", this.element.hidden ? "left" : "entered");
+  }
+  /**
+   * Returns the element to a settled state before Turbo copies the page.
+   *
+   * The snapshot is taken while the controller is still connected, so stripping on
+   * the next `connect()` would only repair the page after it has been painted from
+   * the cache. The pass is silent: `connect()` derives the state again on restore.
+   */
+  #rewindForCache() {
+    this.#cancel();
+    this.#settleState();
+  }
   /** Cancels any in-flight transition (interruption / teardown). */
   #cancel() {
     if (this.#rafId !== null) {
@@ -23560,24 +24112,34 @@ var TransitionController = class extends Controller {
     this.#transition.cancel();
     this.#strip();
   }
+  /**
+   * Applies the stage tokens this controller does not already find on the
+   * element, and claims exactly those.
+   *
+   * A token already on the element is left unclaimed: it is either the consumer's
+   * standing class or one an earlier stage of this transition already claimed, and
+   * in neither case may this call take ownership of it. That is what keeps a
+   * standing class the consumer also named as a stage Value; the cost is that such
+   * a token cannot be staged, so the property it drives resolves from their CSS.
+   */
   #add(...lists) {
-    const tokens = lists.flatMap(tokensOf);
-    if (tokens.length > 0) this.element.classList.add(...tokens);
+    for (const token of lists.flatMap(tokensOf)) {
+      if (this.element.classList.contains(token)) continue;
+      this.element.classList.add(token);
+      this.#staged.add(token);
+    }
   }
+  /** Drops the named tokens that are this controller's to drop. */
   #remove(...lists) {
-    const tokens = lists.flatMap(tokensOf);
-    if (tokens.length > 0) this.element.classList.remove(...tokens);
+    for (const token of lists.flatMap(tokensOf)) {
+      if (!this.#staged.delete(token)) continue;
+      this.element.classList.remove(token);
+    }
   }
-  /** Removes every stage class so no half-applied state lingers. */
+  /** Removes every stage class this controller applied, so none lingers. */
   #strip() {
-    this.#remove(
-      this.enterValue,
-      this.enterFromValue,
-      this.enterToValue,
-      this.leaveValue,
-      this.leaveFromValue,
-      this.leaveToValue
-    );
+    this.element.classList.remove(...this.#staged);
+    this.#staged.clear();
   }
   #raf(callback) {
     if (typeof window.requestAnimationFrame === "function") {