stimeo-ui 0.16.0 → 0.17.0

package/dist/cable/index.js

@@ -1,9 +1,6 @@
 import { Controller } from '@hotwired/stimulus';
 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;
@@ -20,7 +17,6 @@ function fillTemplate(template, values) {
   });
 }
 
-// src/utils/authored_integer.ts
 var TOKEN_BODY = /\d[\d.,'’’    _]*\d|\d/;
 var SIGN_OPENER = /[\s([]/;
 function authoredInteger(text) {
@@ -42,29 +38,21 @@ function authoredInteger(text) {
   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 = () => {
@@ -74,22 +62,18 @@ var BlurDeferral = class {
     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);
@@ -97,44 +81,90 @@ var BlurDeferral = class {
   }
 };
 
-// src/utils/safe_timeout.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  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();
+    });
+  }
+};
+
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
 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);
@@ -151,7 +181,6 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 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);
@@ -165,17 +194,26 @@ var SafeInterval = class extends TimerRegistry {
   }
 };
 
-// src/utils/transient_hooks.ts
 var TransientHooks = class {
   #attributes;
   constructor(options) {
     this.#attributes = options.attributes;
   }
-  /** Drops the declared hooks from `element`; what it carries besides stays. */
   reset(element) {
     for (const attribute of this.#attributes) element.removeAttribute(attribute);
   }
 };
+
+function sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
 function parseSubscriptionParams(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -185,15 +223,21 @@ function parseSubscriptionParams(raw) {
     return {};
   }
 }
-var sharedConsumer = null;
+var consumerRegistry = sharedRegistry(
+  "stimeo-ui.cable-consumer.registry.v1",
+  () => ({ consumer: null })
+);
 function setCableConsumer(consumer) {
-  sharedConsumer = consumer;
+  consumerRegistry.consumer = consumer;
 }
 function getCableConsumer() {
-  if (!sharedConsumer) sharedConsumer = createConsumer();
-  return sharedConsumer;
+  if (!consumerRegistry.consumer) consumerRegistry.consumer = createConsumer();
+  return consumerRegistry.consumer;
 }
-var sharedSubscriptions = /* @__PURE__ */ new WeakMap();
+var sharedSubscriptions = sharedRegistry(
+  "stimeo-ui.cable-subscriptions.registry.v1",
+  () => /* @__PURE__ */ new WeakMap()
+);
 function identifierOf(channel) {
   return JSON.stringify(typeof channel === "string" ? { channel } : channel);
 }
@@ -257,9 +301,6 @@ function openSharedSubscription(consumer, channel) {
     confirmed: false,
     rejected: false,
     subscription: consumer.subscriptions.create(channel, {
-      // A refusal is final: Action Cable never confirms a rejected subscription,
-      // so a late connected/disconnected (only possible from a misbehaving
-      // consumer double) must not reopen the gate `rejected` promised shut.
       connected: () => {
         if (shared.rejected) return;
         shared.confirmed = true;
@@ -281,7 +322,6 @@ function openSharedSubscription(consumer, channel) {
   return shared;
 }
 
-// src/cable/live_counter_controller.ts
 var TRANSIENT = new TransientHooks({ attributes: ["data-live-counter-rejected"] });
 var DISABLED_MARKER = "data-live-counter-disabled";
 var LiveCounterController = class _LiveCounterController extends Controller {
@@ -292,86 +332,42 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     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;
-  /**
-   * 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.
-   */
+  #follow = new MicrotaskCoalescer(() => this.#followDeclaration());
+  #identifier = "";
+  #morphRender = new MorphRenderWatcher(() => this.#syncTriggers());
   #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();
+    this.#follow.schedule();
   }
-  /** Moves the subscription when the declaration names a different channel. */
   channelValueChanged() {
-    this.#resubscribe();
+    this.#follow.schedule();
   }
   connect() {
-    this.#connected = true;
+    this.#morphRender.observe(this.element);
+    this.#follow.activate();
     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.
-   *
-   * @stimeoRuntimeOnly `channel` decides whether this call opens a subscription at all; the
-   *   rejected hook it clears does not depend on it.
-   */
   #subscribe() {
     TRANSIENT.reset(this.element);
     this.#outstanding.length = 0;
+    const descriptor = this.#descriptor;
+    this.#identifier = identifierOf(descriptor);
     if (this.channelValue) {
-      this.#subscription = this.#open();
+      this.#subscription = this.#open(descriptor);
     }
     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.
-   *
-   * @stimeoRuntimeOnly `channel` and its params choose the one subscription this call opens; `id`
-   *   is read by the handlers it wires.
-   */
-  #open() {
+  #open(descriptor) {
     try {
-      return createConfirmedSubscription(this.#descriptor, {
+      return createConfirmedSubscription(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();
@@ -383,26 +379,19 @@ var LiveCounterController = class _LiveCounterController extends Controller {
       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;
+    const { channel: _ignored, ...rest } = parseSubscriptionParams(this.paramsValue);
     return { channel: this.channelValue, ...rest };
   }
-  /** Moves to the identifier the declaration now names. */
-  #resubscribe() {
-    if (!this.#connected) return;
+  #followDeclaration() {
+    if (identifierOf(this.#descriptor) === this.#identifier) return;
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.#subscribe();
   }
   disconnect() {
-    this.#connected = false;
+    this.#morphRender.disconnect();
+    this.#follow.cancel();
     this.#timers.clearAll();
     this.#focusedTriggers.releaseAll();
     this.#subscription?.unsubscribe();
@@ -410,20 +399,13 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     TRANSIENT.reset(this.element);
     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.#ready) return;
     const raw = Number(event?.params?.delta ?? 1);
@@ -436,15 +418,6 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     }
     this.#subscription?.perform("increment", { id: this.idValue, delta });
   }
-  /**
-   * 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 (Number.isSafeInteger(message?.count)) {
@@ -463,32 +436,15 @@ var LiveCounterController = class _LiveCounterController extends Controller {
       this.#reconcile(this.#current + delta);
     }
   }
-  /** 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.#local || (this.#subscription?.confirmed ?? false);
   }
-  /**
-   * Reflects the send gate onto the optional `trigger` targets as the real
-   * `disabled` attribute — the declarative alternative to styling off the
-   * `data-live-counter-rejected` hook (a disabled control is also skipped by
-   * keyboard focus and announced by AT, which CSS alone cannot do).
-   */
   #syncTriggers() {
     for (const trigger of this.triggerTargets) this.#syncTrigger(trigger);
   }
-  /**
-   * `disabled` is a shared attribute: only disable what is currently enabled
-   * (marking it ours), and only lift a disabled carrying our marker — so an
-   * authored-disabled trigger ("disabled until valid", say) is never
-   * re-enabled by the gate. A marked disabled restored from a Turbo cache
-   * snapshot is recognized as ours and lifted once the gate opens.
-   *
-   * @stimeoRenderRoot
-   */
   #syncTrigger(trigger) {
     if (this.#ready) {
       this.#focusedTriggers.release(trigger);
@@ -503,50 +459,26 @@ var LiveCounterController = class _LiveCounterController extends Controller {
     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() {
     return this.hasValueTarget ? this.valueTarget : this.element;
   }
-  /** The current count, parsed from the DOM (the single source of truth). */
   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 false;
     this.#display.textContent = String(count);
     this.dispatch("change", { detail: { count } });
     return true;
   }
-  /**
-   * 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.
-   *
-   * @stimeoRuntimeOnly The count shown is the value received; `announceText` words the one
-   *   announcement of this change.
-   */
   #reconcile(count) {
     if (this.#write(count)) this.#announce(count);
   }
-  /**
-   * Hands a reconciled count to the page's shared announcer.
-   *
-   * 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.
-   */
   #announce(count) {
     this.#timers.clearAll();
     this.#timers.set(() => {
@@ -555,16 +487,9 @@ var LiveCounterController = class _LiveCounterController extends Controller {
   }
 };
 
-// src/utils/keyed_timers.ts
 var KeyedTimers = class {
   #timers = new SafeTimeout();
-  /** The pending timer of each key; an entry lives exactly as long as its timer. */
   #pending = /* @__PURE__ */ new Map();
-  /**
-   * Arms `callback` after `delay` ms for `key`, cancelling the timer `key` had
-   * pending. The entry is dropped before the callback runs, so the callback sees
-   * the key unarmed and may arm it again for the next round.
-   */
   set(key, callback, delay) {
     this.clear(key);
     const id = this.#timers.set(() => {
@@ -573,46 +498,80 @@ var KeyedTimers = class {
     }, delay);
     this.#pending.set(key, id);
   }
-  /**
-   * Cancels `key`'s pending timer, if it has one.
-   *
-   * A timer id is a positive integer, so `-1` stands for "nothing pending" and
-   * the registry ignores an id it does not own — the unarmed case needs no
-   * branch of its own, and no other key's timer can be reached from here.
-   */
   clear(key) {
     this.#timers.clear(this.#pending.get(key) ?? -1);
     this.#pending.delete(key);
   }
-  /**
-   * Cancels every pending timer and forgets every key. Call this from a
-   * controller's `disconnect()` so no timer, and no entry, outlives the element.
-   */
   clearAll() {
     this.#timers.clearAll();
     this.#pending.clear();
   }
-  /** Whether `key` has a timer pending. */
   has(key) {
     return this.#pending.has(key);
   }
 };
 
-// src/utils/template_row.ts
+var NUMBER_BOUNDS = {
+  nonNegative: { finite: true, min: 0 },
+  timer: { finite: true, min: 0, max: MAX_TIMER_DELAY_MS },
+  positiveTimer: { finite: true, exclusiveMin: 0, max: MAX_TIMER_DELAY_MS }
+};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function cloneTemplateRoot(template) {
   const root = template.content.firstElementChild;
   return root instanceof HTMLElement ? root.cloneNode(true) : null;
 }
 
-// src/cable/presence_controller.ts
 var TRANSIENT2 = new TransientHooks({
   attributes: ["data-present", "data-present-count", "data-presence-rejected"]
 });
 var BEACON_THROTTLE_MS = 2e3;
 var DEFAULT_HEARTBEAT_MS = 15e3;
 var DEFAULT_TIMEOUT_MS = 4e4;
-var speakers = /* @__PURE__ */ new Map();
+var speakers = sharedRegistry("stimeo-ui.presence.registry.v1", () => /* @__PURE__ */ new Map());
 var PresenceController = class _PresenceController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["count", "list", "template"];
   static values = {
     channel: { type: String, default: "" },
@@ -624,168 +583,143 @@ var PresenceController = class _PresenceController extends Controller {
     announceJoinText: { type: String, default: "" },
     announceLeaveText: { type: String, default: "" }
   };
+  static valueConstraints = {
+    heartbeat: NUMBER_BOUNDS.positiveTimer,
+    timeout: NUMBER_BOUNDS.positiveTimer
+  };
   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;
-  /** Present peers keyed by id (insertion order = join order). */
+  #follow = new MicrotaskCoalescer(() => this.#followDeclaration());
+  #identifier = "";
+  #period = 0;
   #peers = /* @__PURE__ */ new Map();
-  /** Each peer's auto-expiry timer, restarted by every beacon from that peer. */
   #expiry = new KeyedTimers();
   #timers = new SafeTimeout();
   #intervals = new SafeInterval();
-  /** Epoch ms of the last outgoing beacon, for the convergence throttle. */
   #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()`. */
+  #connected = false;
   #speakerKey = "";
-  /**
-   * Re-parses the identifier parameters when the declaration changes.
-   *
-   * A malformed declaration falls back to no parameters, so the identifier keeps
-   * naming the channel instead of the subscription never being created at all.
-   */
+  #speakerId = "";
+  channelValueChanged() {
+    this.#follow.schedule();
+  }
   paramsValueChanged() {
-    this.#params = parseSubscriptionParams(this.paramsValue);
+    this.#follow.schedule();
+  }
+  idValueChanged() {
+    this.#follow.schedule();
+  }
+  heartbeatValueChanged() {
+    this.#follow.schedule();
   }
-  /**
-   * 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;
+    const { channel: _declared, ...rest } = parseSubscriptionParams(this.paramsValue);
     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.
-   */
+    return this.#safeHeartbeat;
+  }
   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.
-   */
+    return this.#safeTimeout;
+  }
   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);
+    this.#drawList();
+  }
+  listTargetDisconnected() {
+    if (this.#connected) this.#drawList();
   }
-  /** Paints the roster size into a count target that arrives blank, for the same reason. */
   countTargetConnected() {
-    this.countTarget.textContent = this.#countMessage(this.#peers.size);
+    this.#drawCount();
+  }
+  countTargetDisconnected() {
+    if (this.#connected) this.#drawCount();
   }
   connect() {
+    this.#connected = true;
+    this.#follow.activate();
+    this.#start();
+  }
+  disconnect() {
+    this.#connected = false;
+    this.#follow.cancel();
+    this.#close();
+    this.#reset();
+  }
+  #start() {
     this.#reset();
     if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(0);
+    this.#open();
+  }
+  #open() {
+    const descriptor = this.#descriptor;
+    this.#identifier = identifierOf(descriptor);
     if (!this.channelValue) return;
     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.
+    this.#subscription = createConfirmedSubscription(descriptor, {
       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);
+    this.#armHeartbeat();
     window.addEventListener("pagehide", this.#onPageHide);
   }
-  disconnect() {
+  #close() {
     window.removeEventListener("pagehide", this.#onPageHide);
-    if (this.#releaseSpeaker()) this.#sendLeaveNotice();
+    this.#sendLeaveNotice(this.#releaseSpeaker());
     this.#subscription?.unsubscribe();
     this.#subscription = null;
     this.#intervals.clearAll();
-    this.#reset();
   }
-  /**
-   * 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.
-   */
+  #armHeartbeat() {
+    this.#intervals.clearAll();
+    this.#period = this.#heartbeat;
+    this.#intervals.set(() => this.#beacon(true), this.#period);
+  }
+  #followDeclaration() {
+    if (identifierOf(this.#descriptor) !== this.#identifier) {
+      this.#close();
+      this.#start();
+    } else if (this.#subscription) {
+      if (this.idValue !== this.#speakerId) this.#moveVoice();
+      if (this.#heartbeat !== this.#period) this.#armHeartbeat();
+    }
+  }
+  #moveVoice() {
+    this.#sendLeaveNotice(this.#releaseSpeaker());
+    this.#claimSpeaker();
+    this.#forget(this.#speakerId);
+    this.#timers.clear(this.#pendingBeacon ?? -1);
+    this.#pendingBeacon = null;
+    this.#beacon(true);
+  }
   #claimSpeaker() {
-    this.#speakerKey = `${identifierOf(this.#descriptor)}
-${this.idValue}`;
+    this.#speakerId = this.idValue;
+    this.#speakerKey = `${this.#identifier}
+${this.#speakerId}`;
     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;
+    const id = this.#speakerId;
     this.#speakerKey = "";
+    this.#speakerId = "";
     const remaining = (speakers.get(key) ?? 1) - 1;
     if (remaining > 0) speakers.set(key, remaining);
     else speakers.delete(key);
-    return remaining <= 0;
+    return remaining > 0 ? "" : id;
+  }
+  #sendLeaveNotice(id) {
+    if (!this.#subscription?.confirmed || !id) return;
+    this.#subscription.perform("appear", { id, leaving: true });
   }
-  /**
-   * Sends the best-effort leaving notice (skipped without an own `id`, and
-   * outside the confirmed window, where Action Cable would discard it anyway).
-   */
-  #sendLeaveNotice() {
-    if (!this.#subscription?.confirmed || !this.idValue) return;
-    this.#subscription.perform("appear", { id: this.idValue, leaving: true });
-  }
-  /**
-   * `pagehide` covers the leaves `disconnect()` cannot see: closing the tab or
-   * a hard (non-Turbo) navigation destroys the page without running Stimulus
-   * teardown, so this listener is the only chance to announce them. Best-effort
-   * by nature (the socket may close before the frame flushes); peers' expiry
-   * timers stay the safety net. If the page enters the bfcache and is restored
-   * instead, the next heartbeat re-announces this client, so an over-eager
-   * leave self-heals.
-   */
   #onPageHide = () => {
-    this.#sendLeaveNotice();
+    this.#sendLeaveNotice(this.#speakerId);
   };
-  /**
-   * Broadcasts this client's beacon (skipped without an own `id`). A throttled
-   * convergence answer is deferred to the trailing edge rather than dropped —
-   * otherwise a peer joining right after a heartbeat would not learn about
-   * this client until the next full heartbeat period.
-   *
-   * Gated on the confirmed subscription: before confirmation and during an
-   * outage Action Cable silently discards perform(), so a beacon sent then is
-   * pure waste — worse, it would burn `#lastBeaconAt` and delay the next real
-   * convergence answer by up to the throttle window. The heartbeat interval
-   * keeps ticking regardless; `connected` re-fires on reconfirm and
-   * force-beacons immediately, so a gated tick is never missed for long.
-   */
   #beacon(force) {
     if (!this.#subscription?.confirmed || !this.idValue) return;
     const now = Date.now();
@@ -802,14 +736,6 @@ ${this.idValue}`;
     this.#lastBeaconAt = now;
     this.#subscription.perform("appear", { id: this.idValue, name: this.nameValue });
   }
-  /**
-   * Tracks a broadcast beacon: upserts the peer (restarting its expiry timer),
-   * removes it on a `leaving` notice, and re-announces this client when the
-   * peer was unknown (roster convergence — see the class doc).
-   *
-   * @stimeoRuntimeOnly `id` filters this client's own echo, `timeout` arms one peer's expiry,
-   *   `name` answers one beacon and the texts word one announcement.
-   */
   #onReceived(data) {
     const beacon = data;
     const id = beacon?.id;
@@ -833,11 +759,6 @@ ${this.idValue}`;
       this.#render();
     }
   }
-  /**
-   * Removes a peer (expiry or graceful leave) and reflects the change.
-   *
-   * @stimeoRuntimeOnly `announceLeaveText` words the one announcement this departure makes.
-   */
   #drop(id) {
     const peer = this.#peers.get(id);
     if (peer === void 0) return;
@@ -848,25 +769,22 @@ ${this.idValue}`;
     this.#announce(this.announceLeaveTextValue, peer.name);
     this.dispatch("leave", { detail: { id } });
   }
-  /**
-   * Reflects the roster onto the hooks + count target and emits `change`.
-   */
+  #forget(id) {
+    if (!this.#peers.delete(id)) return;
+    this.#expiry.clear(id);
+    this.#removeClone(id);
+    this.#paint();
+  }
   #render() {
+    this.dispatch("change", { detail: { users: this.#paint() } });
+  }
+  #paint() {
     const users = [...this.#peers.entries()].map(([id, peer]) => ({ id, name: peer.name }));
     this.element.setAttribute("data-present", users.length > 0 ? "true" : "false");
     this.element.setAttribute("data-present-count", String(users.length));
     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.
-   */
+    return users;
+  }
   #announce(template, name) {
     const message = fillTemplate(template, { name, count: this.#peers.size });
     if (message.trim() === "") return;
@@ -876,17 +794,21 @@ ${this.idValue}`;
       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
-   * the fallback (copy-free, so nothing to localize by default).
-   */
   #countMessage(count) {
     const templates = this.countTarget.dataset;
     const template = (count === 0 ? templates.zero : count === 1 ? templates.one : templates.other) ?? templates.other;
     return template ? template.replace("%{count}", String(count)) : String(count);
   }
-  /** Appends one template clone for a newly present peer (list + template only). */
+  #drawList() {
+    if (!this.hasListTarget) return;
+    for (const child of this.listTarget.querySelectorAll("[data-presence-id]")) {
+      child.remove();
+    }
+    for (const [id, peer] of this.#peers) this.#appendClone(id, peer.name);
+  }
+  #drawCount() {
+    if (this.hasCountTarget) this.countTarget.textContent = this.#countMessage(this.#peers.size);
+  }
   #appendClone(id, name) {
     if (!this.hasListTarget || !this.hasTemplateTarget) return;
     const root = cloneTemplateRoot(this.templateTarget);
@@ -909,7 +831,6 @@ ${this.idValue}`;
     }
     return null;
   }
-  /** Writes the peer's name into the clone's `data-presence-name` slots. */
   #fillName(root, name) {
     const slots = root.querySelectorAll("[data-presence-name]");
     for (const slot of slots) slot.textContent = name;
@@ -917,7 +838,6 @@ ${this.idValue}`;
       root.textContent = name;
     }
   }
-  /** Clears the transient roster state (connect reset + disconnect teardown). */
   #reset() {
     this.#timers.clearAll();
     this.#expiry.clearAll();
@@ -933,6 +853,24 @@ ${this.idValue}`;
       }
     }
   }
+  get #safeHeartbeat() {
+    return this.#numbers.read(
+      this,
+      "heartbeat",
+      this.heartbeatValue,
+      _PresenceController.values.heartbeat.default,
+      _PresenceController.valueConstraints.heartbeat
+    );
+  }
+  get #safeTimeout() {
+    return this.#numbers.read(
+      this,
+      "timeout",
+      this.timeoutValue,
+      _PresenceController.values.timeout.default,
+      _PresenceController.valueConstraints.timeout
+    );
+  }
 };
 var TRANSIENT3 = new TransientHooks({
   attributes: ["data-typing", "data-typing-indicator-rejected"]
@@ -941,76 +879,95 @@ var DEFAULT_TIMEOUT = 3e3;
 var DEFAULT_THROTTLE = 2e3;
 var fillTokens = (template, values) => template.replace(/%\{(name|names|count)\}/g, (match, token) => values[token] ?? match);
 var TypingIndicatorController = class _TypingIndicatorController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["input", "status"];
   static values = {
     channel: { type: String, default: "" },
     params: { type: String, default: "" },
     name: { type: String, default: "" },
     timeout: { type: Number, default: DEFAULT_TIMEOUT },
-    // Must stay below `timeout`: the throttle is leading-edge only (no trailing
-    // send), so a receiver's display survives continuous typing only while a
-    // fresh signal lands within its timeout window.
     throttle: { type: Number, default: DEFAULT_THROTTLE },
     announceOneText: { type: String, default: "" },
     announceManyText: { type: String, default: "" }
   };
+  static valueConstraints = {
+    timeout: NUMBER_BOUNDS.timer,
+    throttle: NUMBER_BOUNDS.nonNegative
+  };
   static events = ["change"];
-  /** Delay (ms) before one settled typer set is sent to the shared announcer. */
   static #announceDelay = 200;
-  /** Identifier parameters parsed once from their declaration, never in the hot path. */
-  #params = {};
   #subscription = null;
-  /** Names currently typing (other clients), in the order their first signal arrived. */
+  #follow = new MicrotaskCoalescer(() => this.#followDeclaration());
+  #identifier = "";
   #typers = /* @__PURE__ */ new Set();
-  /** Each typer's auto-clear timer, restarted by every further signal from that name. */
   #expiry = new KeyedTimers();
   #timers = new SafeTimeout();
-  /** Epoch ms of the last broadcast, for leading-edge throttling. */
   #lastSentAt = 0;
-  /** The one outstanding announcement, so a newer set supersedes it. */
   #announceId = null;
-  /**
-   * Re-parses the identifier parameters when the declaration changes.
-   *
-   * A malformed declaration falls back to no parameters, so the identifier keeps
-   * naming the channel instead of the subscription never being created at all.
-   */
+  #connected = false;
+  channelValueChanged() {
+    this.#follow.schedule();
+  }
   paramsValueChanged() {
-    this.#params = parseSubscriptionParams(this.paramsValue);
-  }
-  /**
-   * Paints the current copy into a `status` target that arrived at runtime.
-   *
-   * No event: the set of typers did not change, only the element that displays it.
-   * Without this a region swapped in mid-conversation stays empty while `data-typing`
-   * still says someone is typing, leaving the state in the visual hook alone. An empty
-   * set needs no paint — a fresh region already shows it.
-   */
+    this.#follow.schedule();
+  }
+  nameValueChanged() {
+    this.#follow.schedule();
+  }
+  get #descriptor() {
+    const { channel: _declared, ...rest } = parseSubscriptionParams(this.paramsValue);
+    return { channel: this.channelValue, ...rest };
+  }
   statusTargetConnected() {
-    if (this.#typers.size > 0) this.#paint();
+    if (this.#connected) this.#paintStatus([...this.#typers]);
+  }
+  statusTargetDisconnected() {
+    if (this.#connected) this.#paintStatus([...this.#typers]);
   }
   connect() {
-    TRANSIENT3.reset(this.element);
-    if (this.hasStatusTarget) this.statusTarget.textContent = "";
+    this.#connected = true;
+    this.#reset();
     this.element.addEventListener("input", this.#onInput);
-    if (this.channelValue) {
-      this.#subscription = createConfirmedSubscription(
-        { channel: this.channelValue, ...this.#params },
-        {
-          // The server refused the subscription: the send gate stays shut for
-          // good, and the hook lets the consumer's CSS reflect the dead stream.
-          rejected: () => {
-            this.element.setAttribute("data-typing-indicator-rejected", "true");
-          },
-          received: (data) => this.#onReceived(data)
-        }
-      );
-    }
+    this.#follow.activate();
+    this.#open();
   }
   disconnect() {
+    this.#connected = false;
+    this.#follow.cancel();
     this.element.removeEventListener("input", this.#onInput);
+    this.#close();
+    this.#reset();
+  }
+  #open() {
+    const descriptor = this.#descriptor;
+    this.#identifier = identifierOf(descriptor);
+    if (!this.channelValue) return;
+    this.#subscription = createConfirmedSubscription(descriptor, {
+      rejected: () => {
+        this.element.setAttribute("data-typing-indicator-rejected", "true");
+      },
+      received: (data) => this.#onReceived(data)
+    });
+  }
+  #close() {
     this.#subscription?.unsubscribe();
     this.#subscription = null;
+  }
+  #followDeclaration() {
+    if (identifierOf(this.#descriptor) !== this.#identifier) {
+      this.#close();
+      this.#reset();
+      this.#open();
+    } else {
+      this.#forget(this.nameValue);
+    }
+  }
+  #forget(name) {
+    if (!this.#typers.delete(name)) return;
+    this.#expiry.clear(name);
+    this.#paint();
+  }
+  #reset() {
     this.#timers.clearAll();
     this.#expiry.clearAll();
     this.#announceId = null;
@@ -1019,7 +976,6 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     if (this.hasStatusTarget) this.statusTarget.textContent = "";
     this.#lastSentAt = 0;
   }
-  /** Throttled (leading-edge) broadcast of this client's typing signal. */
   #onInput = () => {
     if (!this.#subscription?.confirmed) return;
     const now = Date.now();
@@ -1027,14 +983,6 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     this.#lastSentAt = now;
     this.#subscription.perform("typing", { name: this.nameValue });
   };
-  /**
-   * Tracks a broadcast typer. The own echo is dropped (same `name`); every
-   * further signal from a name restarts its auto-clear timer, so the indicator
-   * survives continuous typing and clears `timeout` ms after the last signal.
-   *
-   * @stimeoRuntimeOnly `name` filters this client's own echo and `timeout` arms one typer's expiry;
-   *   the typers shown come from what is received.
-   */
   #onReceived(data) {
     const name = data?.name;
     if (typeof name !== "string" || name === "" || name === this.nameValue) return;
@@ -1043,53 +991,21 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     this.#expiry.set(name, () => this.#untrack(name), this.#timeout);
     if (added) this.#render();
   }
-  /**
-   * 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 <= MAX_TIMER_DELAY_MS ? declared : DEFAULT_TIMEOUT;
-  }
-  /**
-   * The minimum gap between outgoing signals, in ms: a finite, non-negative number.
-   * Anything else names no interval, and the gate then settles the same way at every
-   * keystroke — `NaN` and a negative gap leave it open, so every keystroke broadcasts,
-   * while `Infinity` is never exceeded, so nothing is ever sent. Such a declaration
-   * falls back to the default.
-   */
+    return this.#safeTimeout;
+  }
   get #throttle() {
-    const declared = this.throttleValue;
-    return Number.isFinite(declared) && declared >= 0 ? declared : DEFAULT_THROTTLE;
+    return this.#safeThrottle;
   }
   #untrack(name) {
     this.#typers.delete(name);
     this.#render();
   }
-  /**
-   * Reflects the typer set onto the display, announces it, and emits `change`.
-   */
   #render() {
     const names = this.#paint();
     this.#announce(names);
     this.dispatch("change", { detail: { names } });
   }
-  /**
-   * Hands the settled typer set to the page's shared announcer.
-   *
-   * Debounced: a burst of arrivals is one announcement, not one per name. Only a
-   * non-empty set is announced — that typing stopped is not news worth interrupting
-   * a reader for, and the visible copy already clears. Wording comes from the
-   * consumer, and {@link announce} drops an empty message, so an undeclared template
-   * announces nothing at all.
-   *
-   * @stimeoRuntimeOnly The wording Values are read to compose one announcement; the
-   * visible typer list is rendered from the set, not from them.
-   */
   #announce(names) {
     if (this.#announceId !== null) this.#timers.clear(this.#announceId);
     this.#announceId = null;
@@ -1103,20 +1019,15 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
       this.#announceId = null;
     }, _TypingIndicatorController.#announceDelay);
   }
-  /** Writes the current typer set onto the hook and the status slot. */
   #paint() {
     const names = [...this.#typers];
     this.element.setAttribute("data-typing", names.length > 0 ? "true" : "false");
-    if (this.hasStatusTarget) {
-      this.statusTarget.textContent = this.#message(names);
-    }
+    this.#paintStatus(names);
     return names;
   }
-  /**
-   * Builds the status copy. Localizable through `data-one` / `data-many`
-   * templates on the status target (`%{name}` / `%{names}` / `%{count}`); terse
-   * English is the fallback.
-   */
+  #paintStatus(names) {
+    if (this.hasStatusTarget) this.statusTarget.textContent = this.#message(names);
+  }
   #message(names) {
     if (names.length === 0) return "";
     const joined = names.join(", ");
@@ -1128,9 +1039,26 @@ var TypingIndicatorController = class _TypingIndicatorController extends Control
     const template = this.statusTarget.dataset.many;
     return template ? fillTokens(template, { names: joined, count: String(names.length) }) : `${joined} are typing\u2026`;
   }
+  get #safeTimeout() {
+    return this.#numbers.read(
+      this,
+      "timeout",
+      this.timeoutValue,
+      _TypingIndicatorController.values.timeout.default,
+      _TypingIndicatorController.valueConstraints.timeout
+    );
+  }
+  get #safeThrottle() {
+    return this.#numbers.read(
+      this,
+      "throttle",
+      this.throttleValue,
+      _TypingIndicatorController.values.throttle.default,
+      _TypingIndicatorController.valueConstraints.throttle
+    );
+  }
 };
 
-// src/cable/index.ts
 var cableControllers = {
   "stimeo--live-counter": LiveCounterController,
   "stimeo--presence": PresenceController,
@@ -1143,5 +1071,4 @@ function registerCable(application) {
 }
 
 export { LiveCounterController, PresenceController, TypingIndicatorController, cableControllers, createConfirmedSubscription, getCableConsumer, registerCable, setCableConsumer };
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map