stimeo-ui 0.12.0 → 0.13.0

package/dist/cable/index.js

@@ -3,6 +3,23 @@ import { createConsumer } from '@rails/actioncable';
 
 // src/cable/live_counter_controller.ts
 
+// 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/utils/authored_integer.ts
 var TOKEN_BODY = /\d[\d.,'’’    _]*\d|\d/;
 var SIGN_OPENER = /[\s([]/;
@@ -24,6 +41,129 @@ function authoredInteger(text) {
   const magnitude = Number.parseInt(digits, 10);
   return signed ? -magnitude || 0 : magnitude;
 }
+
+// src/utils/blur_deferral.ts
+var BlurDeferral = class {
+  /** Elements currently holding an update back, mapped to their `blur` listener. */
+  #pending = /* @__PURE__ */ new Map();
+  /** Called after a pending element blurs and has been detached. */
+  #onRelease;
+  /** @param onRelease - Invoked once `element` actually blurs; never on `release`. */
+  constructor(onRelease) {
+    this.#onRelease = onRelease;
+  }
+  /** Number of elements currently holding an update back. */
+  get size() {
+    return this.#pending.size;
+  }
+  /** Snapshot of the pending elements, safe to iterate while releasing them. */
+  get elements() {
+    return [...this.#pending.keys()];
+  }
+  /** Whether `element` is currently holding an update back. */
+  has(element) {
+    return this.#pending.has(element);
+  }
+  /** Holds an update back until `element` blurs. Idempotent (no stacked listeners). */
+  defer(element) {
+    if (this.#pending.has(element)) return;
+    const onBlur = () => {
+      this.#detach(element);
+      this.#onRelease(element);
+    };
+    this.#pending.set(element, onBlur);
+    element.addEventListener("blur", onBlur);
+  }
+  /** Defers `element` as the only pending entry, cancelling any others. */
+  deferOnly(element) {
+    for (const pending of this.elements) {
+      if (pending !== element) this.#detach(pending);
+    }
+    this.defer(element);
+  }
+  /** Cancels `element`'s deferral without completing it; no-ops when not pending. */
+  release(element) {
+    this.#detach(element);
+  }
+  /** Cancels every deferral without completing any of them. */
+  releaseAll() {
+    for (const element of this.elements) this.#detach(element);
+  }
+  /** Removes the `blur` listener for `element` and forgets it. */
+  #detach(element) {
+    const onBlur = this.#pending.get(element);
+    if (onBlur) element.removeEventListener("blur", onBlur);
+    this.#pending.delete(element);
+  }
+};
+
+// src/utils/safe_timeout.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+var TimerRegistry = class {
+  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
+  ids = /* @__PURE__ */ new Set();
+  /**
+   * Cancels a single tracked timer.
+   *
+   * No-ops if the id is unknown (already cleared, fired, or never owned by this
+   * registry), so callers can clear defensively without guarding.
+   */
+  clear(id) {
+    if (this.ids.delete(id)) {
+      this.cancel(id);
+    }
+  }
+  /**
+   * Cancels every tracked timer. Call this from a controller's `disconnect()`
+   * to guarantee no timer outlives the element.
+   */
+  clearAll() {
+    for (const id of this.ids) {
+      this.cancel(id);
+    }
+    this.ids.clear();
+  }
+  /** Number of timers currently tracked (pending). */
+  get size() {
+    return this.ids.size;
+  }
+};
+var SafeTimeout = class extends TimerRegistry {
+  /**
+   * Schedules `callback` after `delay` ms and returns the timer id.
+   *
+   * The id is removed from the registry automatically when the timeout fires,
+   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   */
+  set(callback, delay) {
+    const id = this.schedule(() => {
+      this.ids.delete(id);
+      callback();
+    }, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setTimeout(callback, delay);
+  }
+  cancel(id) {
+    window.clearTimeout(id);
+  }
+};
+var SafeInterval = class extends TimerRegistry {
+  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */
+  set(callback, delay) {
+    const id = this.schedule(callback, delay);
+    this.ids.add(id);
+    return id;
+  }
+  schedule(callback, delay) {
+    return window.setInterval(callback, delay);
+  }
+  cancel(id) {
+    window.clearInterval(id);
+  }
+};
 function parseSubscriptionParams(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -131,92 +271,186 @@ function openSharedSubscription(consumer, channel) {
 
 // src/cable/live_counter_controller.ts
 var DISABLED_MARKER = "data-live-counter-disabled";
-var LiveCounterController = class extends Controller {
+var LiveCounterController = class _LiveCounterController extends Controller {
   static targets = ["value", "trigger"];
   static values = {
     channel: { type: String, default: "" },
     params: { type: String, default: "" },
-    id: { type: String, default: "" }
+    id: { type: String, default: "" },
+    announceText: { type: String, default: "" }
   };
+  /** Collapses a burst of broadcasts into one announcement. */
+  static #announceDelay = 200;
   static actions = ["increment"];
   static events = ["change"];
   /** Identifier parameters parsed once from their declaration, never in the hot path. */
   #params = {};
   #subscription = null;
+  #connected = false;
   /**
-   * Re-parses the identifier parameters when the declaration changes.
+   * The optimistic bumps this client has yet to see echoed back, in the order it
+   * sent them. An echo belongs to the send that caused it, and the amount is what
+   * names that send: a counter that guessed nothing — or guessed a different
+   * amount — applies the delta like any other, so siblings and other tabs
+   * converge whatever step each of them uses.
+   */
+  #outstanding = [];
+  /** Holds a disable back while the trigger owns focus, so focus is never taken away. */
+  #focusedTriggers = new BlurDeferral((trigger) => this.#syncTrigger(trigger));
+  #timers = new SafeTimeout();
+  /**
+   * Re-parses the identifier parameters and moves the subscription to the
+   * identifier they now name.
    *
    * A malformed declaration falls back to no parameters, so the identifier keeps
    * naming the channel instead of the subscription never being created at all.
    */
   paramsValueChanged() {
     this.#params = parseSubscriptionParams(this.paramsValue);
+    this.#resubscribe();
+  }
+  /** Moves the subscription when the declaration names a different channel. */
+  channelValueChanged() {
+    this.#resubscribe();
   }
   connect() {
+    this.#connected = true;
+    this.#subscribe();
+  }
+  /**
+   * Opens the subscription the declaration names, and reflects the gate.
+   *
+   * The rejected hook is transient server state: a Turbo cache snapshot must not
+   * resurrect it — the fresh subscription re-decides it. An outstanding guess
+   * belongs to the identifier that is going away, so it is dropped with it.
+   */
+  #subscribe() {
     this.element.removeAttribute("data-live-counter-rejected");
+    this.#outstanding.length = 0;
     if (this.channelValue) {
-      this.#subscription = createConfirmedSubscription(
-        { channel: this.channelValue, ...this.#params },
-        {
-          connected: () => this.#syncTriggers(),
-          // A drop closes the send window (the shared subscription tracks it)
-          // until Action Cable reconnects and re-confirms — an increment during
-          // the outage would bump the display while its perform() is silently
-          // discarded by the closed socket.
-          disconnected: () => this.#syncTriggers(),
-          // The server refused the subscription (auth, bad params): the gate
-          // stays shut for good, and the hook lets the consumer's CSS disable
-          // or hide the trigger instead of leaving a silently dead button.
-          rejected: () => {
-            this.element.setAttribute("data-live-counter-rejected", "true");
-            this.#syncTriggers();
-          },
-          received: (data) => this.#onReceived(data)
-        }
-      );
+      this.#subscription = this.#open();
     }
     this.#syncTriggers();
   }
+  /**
+   * Opens the wire subscription, or returns null when it cannot be opened.
+   *
+   * A consumer that cannot be built (no Action Cable meta tag, a boot-order
+   * mistake) would otherwise throw out of `connect()` and leave the element
+   * half-wired: no gate reflected, and a trigger that looks live. The gate reads
+   * the declaration, so a null subscription keeps it shut and the display never
+   * moves past what the server can receive.
+   */
+  #open() {
+    try {
+      return createConfirmedSubscription(this.#descriptor, {
+        connected: () => this.#syncTriggers(),
+        // A drop closes the send window (the shared subscription tracks it)
+        // until Action Cable reconnects and re-confirms — an increment during
+        // the outage would bump the display while its perform() is silently
+        // discarded by the closed socket.
+        disconnected: () => this.#syncTriggers(),
+        // The server refused the subscription (auth, bad params): the gate
+        // stays shut for good, and the hook lets the consumer's CSS disable
+        // or hide the trigger instead of leaving a silently dead button.
+        rejected: () => {
+          this.element.setAttribute("data-live-counter-rejected", "true");
+          this.#syncTriggers();
+        },
+        received: (data) => this.#onReceived(data)
+      });
+    } catch (error) {
+      console.warn("Stimeo UI: the live counter could not open its subscription.", error);
+      return null;
+    }
+  }
+  /**
+   * The identifier this declaration names.
+   *
+   * `channel` comes first so the identifier text matches what Action Cable
+   * builds, and a `channel` key inside `params` cannot displace the declared
+   * one — `params` names *additional* identifier parameters.
+   */
+  get #descriptor() {
+    const { channel: _ignored, ...rest } = this.#params;
+    return { channel: this.channelValue, ...rest };
+  }
+  /** Moves to the identifier the declaration now names. */
+  #resubscribe() {
+    if (!this.#connected) return;
+    this.#subscription?.unsubscribe();
+    this.#subscription = null;
+    this.#subscribe();
+  }
   disconnect() {
+    this.#connected = false;
+    this.#timers.clearAll();
+    this.#focusedTriggers.releaseAll();
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.element.removeAttribute("data-live-counter-rejected");
+    for (const trigger of this.triggerTargets) this.#release(trigger);
   }
   /** Late-added triggers (e.g. via a Turbo Stream) pick up the current gate. */
   triggerTargetConnected(target) {
     this.#syncTrigger(target);
   }
+  /** A trigger that stops being one keeps nothing this controller lent it. */
+  triggerTargetDisconnected(target) {
+    this.#focusedTriggers.release(target);
+    this.#release(target);
+  }
   /**
    * Optimistic local increment: bumps the display immediately, then asks the
    * server to persist and broadcast. The step comes from the action param
    * (`data-stimeo--live-counter-delta-param`), default 1. Bound via `data-action`.
    */
   increment(event) {
-    if (this.#subscription && !this.#subscription.confirmed) return;
+    if (!this.#ready) return;
     const raw = Number(event?.params?.delta ?? 1);
-    const delta = Number.isFinite(raw) ? raw : 1;
-    if (!this.#subscription || this.idValue !== "") {
+    const delta = Number.isSafeInteger(raw) ? raw : 1;
+    if (this.#local) {
+      this.#write(this.#current + delta);
+    } else if (this.idValue !== "") {
+      this.#outstanding.push(delta);
       this.#write(this.#current + delta);
     }
     this.#subscription?.perform("increment", { id: this.idValue, delta });
   }
-  /** Reconciles a broadcast: absolute `count` wins; own-echo deltas are skipped. */
+  /**
+   * Reconciles a broadcast: absolute `count` wins; the echo of this client's own
+   * guess is skipped.
+   *
+   * Only whole numbers reach the display. The wire carries values another client
+   * named and the server relayed, and the display is the state this controller
+   * reads back — a fraction, an infinity or a NaN would be written as text that
+   * reads back as a different number, or as none at all.
+   */
   #onReceived(data) {
     const message = data;
-    if (typeof message?.count === "number") {
-      this.#write(message.count);
+    if (Number.isSafeInteger(message?.count)) {
+      this.#outstanding.length = 0;
+      this.#reconcile(message?.count);
       return;
     }
-    if (typeof message?.delta === "number") {
-      if (typeof message.by === "string" && message.by !== "" && message.by === this.idValue) {
+    if (Number.isSafeInteger(message?.delta)) {
+      const delta = message?.delta;
+      const own = typeof message?.by === "string" && message.by !== "" && message.by === this.idValue;
+      const guess = own ? this.#outstanding.indexOf(delta) : -1;
+      if (guess !== -1) {
+        this.#outstanding.splice(guess, 1);
         return;
       }
-      this.#write(this.#current + message.delta);
+      this.#reconcile(this.#current + delta);
     }
   }
-  /** True while an increment would go through (channel-less counters always are). */
+  /** True when no channel is declared: the local-only mode, with no server to diverge from. */
+  get #local() {
+    return this.channelValue === "";
+  }
+  /** True while an increment would go through (local-only counters always are). */
   get #ready() {
-    return !this.#subscription || this.#subscription.confirmed;
+    return this.#local || (this.#subscription?.confirmed ?? false);
   }
   /**
    * Reflects the send gate onto the optional `trigger` targets as the real
@@ -236,14 +470,23 @@ var LiveCounterController = class extends Controller {
    */
   #syncTrigger(trigger) {
     if (this.#ready) {
-      if (trigger.hasAttribute(DISABLED_MARKER)) {
-        trigger.removeAttribute("disabled");
-        trigger.removeAttribute(DISABLED_MARKER);
-      }
-    } else if (!trigger.hasAttribute("disabled")) {
-      trigger.setAttribute("disabled", "");
-      trigger.setAttribute(DISABLED_MARKER, "");
+      this.#focusedTriggers.release(trigger);
+      this.#release(trigger);
+      return;
+    }
+    if (trigger.hasAttribute("disabled")) return;
+    if (trigger.contains(document.activeElement)) {
+      this.#focusedTriggers.defer(trigger);
+      return;
     }
+    trigger.setAttribute("disabled", "");
+    trigger.setAttribute(DISABLED_MARKER, "");
+  }
+  /** Gives back a `disabled` this controller lent, leaving an authored one alone. */
+  #release(trigger) {
+    if (!trigger.hasAttribute(DISABLED_MARKER)) return;
+    trigger.removeAttribute("disabled");
+    trigger.removeAttribute(DISABLED_MARKER);
   }
   /** The displayed element: the `value` target, else the controller element. */
   get #display() {
@@ -253,93 +496,59 @@ var LiveCounterController = class extends Controller {
   get #current() {
     return authoredInteger(this.#display.textContent ?? "") ?? 0;
   }
+  /**
+   * Writes a whole count — every caller has already established that it is one —
+   * and reports whether the display actually moved.
+   */
   #write(count) {
-    if (count === this.#current) return;
+    if (count === this.#current) return false;
     this.#display.textContent = String(count);
     this.dispatch("change", { detail: { count } });
+    return true;
   }
-};
-
-// src/utils/safe_timeout.ts
-var TimerRegistry = class {
-  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
-  ids = /* @__PURE__ */ new Set();
   /**
-   * Cancels a single tracked timer.
-   *
-   * No-ops if the id is unknown (already cleared, fired, or never owned by this
-   * registry), so callers can clear defensively without guarding.
+   * Settles the display on a count the server stated, announcing what it settled
+   * on. Announcing the optimistic bump instead would read a guess out and then
+   * correct it, so the announcement rides this path only.
    */
-  clear(id) {
-    if (this.ids.delete(id)) {
-      this.cancel(id);
-    }
+  #reconcile(count) {
+    if (this.#write(count)) this.#announce(count);
   }
   /**
-   * Cancels every tracked timer. Call this from a controller's `disconnect()`
-   * to guarantee no timer outlives the element.
-   */
-  clearAll() {
-    for (const id of this.ids) {
-      this.cancel(id);
-    }
-    this.ids.clear();
-  }
-  /** Number of timers currently tracked (pending). */
-  get size() {
-    return this.ids.size;
-  }
-};
-var SafeTimeout = class extends TimerRegistry {
-  /**
-   * Schedules `callback` after `delay` ms and returns the timer id.
+   * Hands a reconciled count to the page's shared announcer.
    *
-   * The id is removed from the registry automatically when the timeout fires,
-   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
+   * Debounced: a burst of broadcasts is one announcement, not one per message,
+   * and only the last one is ever sent. Wording comes from the consumer and
+   * {@link announce} drops an empty message, so an undeclared template announces
+   * nothing at all — a count that ticks constantly should not interrupt a reader
+   * unless the page asked for it.
    */
-  set(callback, delay) {
-    const id = this.schedule(() => {
-      this.ids.delete(id);
-      callback();
-    }, delay);
-    this.ids.add(id);
-    return id;
-  }
-  schedule(callback, delay) {
-    return window.setTimeout(callback, delay);
-  }
-  cancel(id) {
-    window.clearTimeout(id);
-  }
-};
-var SafeInterval = class extends TimerRegistry {
-  /** Schedules a repeating `callback` every `delay` ms and returns the timer id. */
-  set(callback, delay) {
-    const id = this.schedule(callback, delay);
-    this.ids.add(id);
-    return id;
-  }
-  schedule(callback, delay) {
-    return window.setInterval(callback, delay);
-  }
-  cancel(id) {
-    window.clearInterval(id);
+  #announce(count) {
+    this.#timers.clearAll();
+    this.#timers.set(() => {
+      announce(fillTemplate(this.announceTextValue, { count }));
+    }, _LiveCounterController.#announceDelay);
   }
 };
-
-// src/cable/presence_controller.ts
 var BEACON_THROTTLE_MS = 2e3;
-var PresenceController = class extends Controller {
+var DEFAULT_HEARTBEAT_MS = 15e3;
+var DEFAULT_TIMEOUT_MS = 4e4;
+var speakers = /* @__PURE__ */ new Map();
+var PresenceController = class _PresenceController extends Controller {
   static targets = ["count", "list", "template"];
   static values = {
     channel: { type: String, default: "" },
     params: { type: String, default: "" },
     id: { type: String, default: "" },
     name: { type: String, default: "" },
-    heartbeat: { type: Number, default: 15e3 },
-    timeout: { type: Number, default: 4e4 }
+    heartbeat: { type: Number, default: DEFAULT_HEARTBEAT_MS },
+    timeout: { type: Number, default: DEFAULT_TIMEOUT_MS },
+    announceJoinText: { type: String, default: "" },
+    announceLeaveText: { type: String, default: "" }
   };
   static events = ["join", "leave", "change"];
+  /** Delay (ms) before one roster change is sent to the shared announcer. */
+  static #announceDelay = 200;
   /** Identifier parameters parsed once from their declaration, never in the hot path. */
   #params = {};
   #subscription = null;
@@ -351,6 +560,10 @@ var PresenceController = class extends Controller {
   #lastBeaconAt = 0;
   /** Pending trailing-edge convergence beacon (at most one queued). */
   #pendingBeacon = null;
+  /** The one outstanding announcement, so a newer roster change supersedes it. */
+  #announceId = null;
+  /** The `speakers` key this element holds, recomputed on every `connect()`. */
+  #speakerKey = "";
   /**
    * Re-parses the identifier parameters when the declaration changes.
    *
@@ -360,38 +573,108 @@ var PresenceController = class extends Controller {
   paramsValueChanged() {
     this.#params = parseSubscriptionParams(this.paramsValue);
   }
+  /**
+   * The identifier this declaration names. `params` *adds* to the identifier, so a
+   * `channel` key inside it names an extra parameter and never replaces the channel
+   * the element declares.
+   */
+  get #descriptor() {
+    const { channel: _declared, ...rest } = this.#params;
+    return { channel: this.channelValue, ...rest };
+  }
+  /**
+   * The beacon period, in ms: a finite, positive number a timer can hold. Anything
+   * else names no interval — `setInterval` reads `NaN`, a negative value, `Infinity`
+   * and a value past {@link MAX_TIMER_DELAY_MS} alike as "as often as possible", so
+   * the declaration would flood the channel rather than heartbeat on it. Zero is out
+   * for the same reason, which is why this bound is tighter than the non-negative one
+   * a throttle or a plain delay can use. Such a declaration falls back to the default.
+   */
+  get #heartbeat() {
+    const declared = this.heartbeatValue;
+    return Number.isFinite(declared) && declared > 0 && declared <= MAX_TIMER_DELAY_MS ? declared : DEFAULT_HEARTBEAT_MS;
+  }
+  /**
+   * The silence after which a peer is dropped, in ms: a finite, positive number a
+   * timer can hold. Anything else names no delay and every peer expires in the task
+   * that records it, so the roster could never hold anyone. Such a declaration falls
+   * back to the default.
+   */
+  get #timeout() {
+    const declared = this.timeoutValue;
+    return Number.isFinite(declared) && declared > 0 && declared <= MAX_TIMER_DELAY_MS ? declared : DEFAULT_TIMEOUT_MS;
+  }
+  /**
+   * Draws the roster into a list target, which arrives empty from a Turbo Stream
+   * replacement or a morph. Stimulus runs this before `connect()` on the first mount
+   * too, where the roster is still empty and clearing whatever a cache snapshot
+   * preserved is what `connect()` goes on to do anyway.
+   */
+  listTargetConnected() {
+    for (const child of this.listTarget.querySelectorAll("[data-presence-id]")) {
+      child.remove();
+    }
+    for (const [id, peer] of this.#peers) this.#appendClone(id, peer.name);
+  }
+  /** Paints the roster size into a count target that arrives blank, for the same reason. */
+  countTargetConnected() {
+    this.countTarget.textContent = this.#countMessage(this.#peers.size);
+  }
   connect() {
     this.#reset();
     this.element.removeAttribute("data-presence-rejected");
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(0);
     if (!this.channelValue) return;
-    this.#subscription = createConfirmedSubscription(
-      { channel: this.channelValue, ...this.#params },
-      {
-        // The first beacon must wait for the confirmed subscription — a
-        // perform() before that is silently dropped by Action Cable. Fires
-        // again on every reconnect, so the roster self-heals after an outage.
-        connected: () => this.#beacon(true),
-        // The server refused the subscription: no beacon will ever go through,
-        // and the hook lets the consumer's CSS reflect the dead stream.
-        rejected: () => {
-          this.element.setAttribute("data-presence-rejected", "true");
-        },
-        received: (data) => this.#onReceived(data)
-      }
-    );
-    this.#intervals.set(() => this.#beacon(true), this.heartbeatValue);
+    this.#claimSpeaker();
+    this.#subscription = createConfirmedSubscription(this.#descriptor, {
+      // The first beacon must wait for the confirmed subscription — a
+      // perform() before that is silently dropped by Action Cable. Fires
+      // again on every reconnect, so the roster self-heals after an outage.
+      connected: () => this.#beacon(true),
+      // The server refused the subscription: no beacon will ever go through,
+      // and the hook lets the consumer's CSS reflect the dead stream.
+      rejected: () => {
+        this.element.setAttribute("data-presence-rejected", "true");
+      },
+      received: (data) => this.#onReceived(data)
+    });
+    this.#intervals.set(() => this.#beacon(true), this.#heartbeat);
     window.addEventListener("pagehide", this.#onPageHide);
   }
   disconnect() {
     window.removeEventListener("pagehide", this.#onPageHide);
-    this.#sendLeaveNotice();
+    if (this.#releaseSpeaker()) this.#sendLeaveNotice();
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.#intervals.clearAll();
     this.#reset();
     this.element.removeAttribute("data-presence-rejected");
   }
+  /**
+   * Registers this element as one of the voices for its peer, so a sibling on the
+   * same channel claiming the same `id` keeps the peer present until they all go.
+   * Whether the peer is worth announcing at all is {@link #sendLeaveNotice}'s
+   * question, so an element with no own `id` claims a voice like any other and is
+   * simply never heard.
+   */
+  #claimSpeaker() {
+    this.#speakerKey = `${identifierOf(this.#descriptor)}
+${this.idValue}`;
+    speakers.set(this.#speakerKey, (speakers.get(this.#speakerKey) ?? 0) + 1);
+  }
+  /**
+   * Gives up the claim, reporting whether this element was the last voice for the
+   * peer. The key is spent here: an element that goes on to connect without a
+   * channel claims nothing, and a stale key would spend a voice its siblings own.
+   */
+  #releaseSpeaker() {
+    const key = this.#speakerKey;
+    this.#speakerKey = "";
+    const remaining = (speakers.get(key) ?? 1) - 1;
+    if (remaining > 0) speakers.set(key, remaining);
+    else speakers.delete(key);
+    return remaining <= 0;
+  }
   /**
    * Sends the best-effort leaving notice (skipped without an own `id`, and
    * outside the confirmed window, where Action Cable would discard it anyway).
@@ -457,11 +740,12 @@ var PresenceController = class extends Controller {
     const name = typeof beacon?.name === "string" ? beacon.name : "";
     const existing = this.#peers.get(id);
     if (existing !== void 0) this.#timers.clear(existing.timer);
-    const timer = this.#timers.set(() => this.#drop(id), this.timeoutValue);
+    const timer = this.#timers.set(() => this.#drop(id), this.#timeout);
     this.#peers.set(id, { name, timer });
     if (existing === void 0) {
       this.#appendClone(id, name);
       this.#render();
+      this.#announce(this.announceJoinTextValue, name);
       this.dispatch("join", { detail: { id, name } });
       this.#beacon(false);
     } else if (existing.name !== name) {
@@ -477,6 +761,7 @@ var PresenceController = class extends Controller {
     this.#peers.delete(id);
     this.#removeClone(id);
     this.#render();
+    this.#announce(this.announceLeaveTextValue, peer.name);
     this.dispatch("leave", { detail: { id } });
   }
   /** Reflects the roster onto the hooks + count target and emits `change`. */
@@ -487,6 +772,24 @@ var PresenceController = class extends Controller {
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(users.length);
     this.dispatch("change", { detail: { users } });
   }
+  /**
+   * Hands one roster change to the page's shared announcer.
+   *
+   * Debounced: a burst of arrivals is one announcement, not one per peer — reading
+   * out every entry and exit of a busy room is the noise the default avoids. Wording
+   * comes from the consumer (`{name}` / `{count}`, where the count is the roster
+   * after the change), and an undeclared template does nothing at all — not even
+   * cancel an announcement already pending for the other direction.
+   */
+  #announce(template, name) {
+    const message = fillTemplate(template, { name, count: this.#peers.size });
+    if (message.trim() === "") return;
+    if (this.#announceId !== null) this.#timers.clear(this.#announceId);
+    this.#announceId = this.#timers.set(() => {
+      announce(message);
+      this.#announceId = null;
+    }, _PresenceController.#announceDelay);
+  }
   /**
    * Builds the count copy. Localizable through `data-zero` / `data-one` /
    * `data-other` templates on the count target (`%{count}`); the bare number is
@@ -500,12 +803,11 @@ var PresenceController = class extends Controller {
   /** Appends one template clone for a newly present peer (list + template only). */
   #appendClone(id, name) {
     if (!this.hasListTarget || !this.hasTemplateTarget) return;
-    const clone = this.templateTarget.content.cloneNode(true);
-    const root = clone.firstElementChild;
-    if (!root) return;
+    const root = this.templateTarget.content.firstElementChild?.cloneNode(true);
+    if (!(root instanceof Element)) return;
     root.setAttribute("data-presence-id", id);
     this.#fillName(root, name);
-    this.listTarget.appendChild(clone);
+    this.listTarget.appendChild(root);
   }
   #updateClone(id, name) {
     const root = this.#cloneFor(id);
@@ -533,6 +835,7 @@ var PresenceController = class extends Controller {
   #reset() {
     this.#timers.clearAll();
     this.#pendingBeacon = null;
+    this.#announceId = null;
     this.#peers.clear();
     this.#lastBeaconAt = 0;
     this.element.removeAttribute("data-present");
@@ -545,25 +848,6 @@ var PresenceController = class extends Controller {
     }
   }
 };
-
-// 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/cable/typing_indicator_controller.ts
 var DEFAULT_TIMEOUT = 3e3;
 var DEFAULT_THROTTLE = 2e3;
 var fillTokens = (template, values) => template.replace(/%\{(name|names|count)\}/g, (match, token) => values[token] ?? match);
@@ -671,14 +955,16 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     if (added) this.#render();
   }
   /**
-   * The silence after which a typer is dropped, in ms: a finite, non-negative number.
-   * Anything else names no delay — `setTimeout` reads `NaN`, a negative value and
-   * `Infinity` alike as "now", so the typer would vanish in the same task it appeared
-   * and the indicator could never be seen. Such a declaration falls back to the default.
+   * The silence after which a typer is dropped, in ms: a finite, non-negative number
+   * a timer can hold. Anything else names no delay — `setTimeout` reads `NaN`, a
+   * negative value and `Infinity` alike as "now", and a value past
+   * {@link MAX_TIMER_DELAY_MS} overflows to the same place — so the typer would
+   * vanish in the same task it appeared and the indicator could never be seen. Such
+   * a declaration falls back to the default.
    */
   get #timeout() {
     const declared = this.timeoutValue;
-    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_TIMEOUT;
+    return Number.isFinite(declared) && declared >= 0 && declared <= MAX_TIMER_DELAY_MS ? declared : DEFAULT_TIMEOUT;
   }
   /**
    * The minimum gap between outgoing signals, in ms: a finite, non-negative number.