stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/persist_controller.js

@@ -2,6 +2,64 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/persist_controller.ts
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+// src/utils/safe_storage.ts
+function readLocalStorage(key) {
+  try {
+    return { ok: true, value: window.localStorage.getItem(key) };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+function writeLocalStorage(key, value) {
+  try {
+    window.localStorage.setItem(key, value);
+    return { ok: true, value: void 0 };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+function removeLocalStorage(key) {
+  try {
+    window.localStorage.removeItem(key);
+    return { ok: true, value: void 0 };
+  } catch (error) {
+    return { ok: false, error };
+  }
+}
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -55,203 +113,474 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/string_list.ts
+function parseStringList(raw, fallback = []) {
+  const text = raw.trim();
+  if (text.length === 0) return [...fallback];
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [...fallback];
+  }
+  if (!Array.isArray(parsed)) return [...fallback];
+  return parsed.filter((entry) => typeof entry === "string");
+}
+
 // src/controllers/persist_controller.ts
 var NON_VALUE_TYPES = /* @__PURE__ */ new Set(["file", "submit", "reset", "button", "image"]);
+var SENSITIVE_TYPES = /* @__PURE__ */ new Set(["password"]);
+var DEFAULT_EXCLUDE = ["authenticity_token", "_method", "utf8"];
 var STORAGE_PREFIX = "stimeo--persist:";
 var OCCURRENCE_SEP = "\0";
+var OWNERSHIP_ATTRIBUTE = "data-controller";
+var DEFAULT_DEBOUNCE = 400;
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isPersistValue = (value) => typeof value === "string" || typeof value === "boolean" || Array.isArray(value) && value.every((item) => typeof item === "string");
+var parsePayload = (raw) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed) || parsed.version !== 1 || !Array.isArray(parsed.fields)) return null;
+  const fields = [];
+  const keys = /* @__PURE__ */ new Set();
+  for (const candidate of parsed.fields) {
+    if (!isRecord(candidate)) return null;
+    const { key, value } = candidate;
+    if (typeof key !== "string" || key.length === 0 || keys.has(key)) return null;
+    if (!isPersistValue(value)) return null;
+    keys.add(key);
+    fields.push({ key, value });
+  }
+  return { version: 1, fields };
+};
+var isPersistField = (node) => node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement || node instanceof HTMLSelectElement;
 var PersistController = class extends Controller {
   static targets = ["field"];
   static values = {
     key: { type: String, default: "" },
-    debounce: { type: Number, default: 400 },
-    exclude: { type: Array, default: ["password"] },
+    debounce: { type: Number, default: DEFAULT_DEBOUNCE },
+    // A malformed JSON list must fall back without aborting Stimulus connection.
+    exclude: { type: String, default: "" },
     clearOn: { type: String, default: "" }
   };
   static actions = ["clear"];
-  static events = ["restore", "save", "clear"];
+  static events = ["restore", "save", "clear", "error"];
   #timeouts = new SafeTimeout();
-  #saveId = null;
-  #onInput = () => {
+  #restoreDynamic = new MicrotaskCoalescer(() => this.#restoreDynamicFields());
+  #observer = new MutationObserver((records) => this.#onMutations(records));
+  #pendingSave = null;
+  #connected = false;
+  #logicalKey = null;
+  #payload = null;
+  #registeredClearOn = null;
+  #excluded = DEFAULT_EXCLUDE;
+  #knownFields = /* @__PURE__ */ new WeakSet();
+  #forcedRestore = /* @__PURE__ */ new Set();
+  #onInput = (event) => {
+    const field = event.target;
+    if (!isPersistField(field) || !this.#ownsField(field)) return;
+    if (this.hasFieldTarget && !this.fieldTargets.includes(field)) return;
+    if (this.#keyOf(field) === null || !this.#persistable(field, this.#excluded)) return;
     this.#scheduleSave();
   };
   #onClearEvent = () => {
     this.clear();
   };
   connect() {
-    if (this.#storageKey === null) return;
-    this.#restore();
+    if (this.#connected) return;
+    this.#connected = true;
+    this.#logicalKey = this.#resolveLogicalKey();
+    this.#excluded = parseStringList(this.excludeValue, DEFAULT_EXCLUDE);
+    this.#knownFields = /* @__PURE__ */ new WeakSet();
+    this.#forcedRestore.clear();
+    this.element.removeAttribute("data-persist-restored");
     this.element.addEventListener("input", this.#onInput);
     this.element.addEventListener("change", this.#onInput);
-    if (this.clearOnValue.length > 0) {
-      this.element.addEventListener(this.clearOnValue, this.#onClearEvent);
-    }
+    this.#syncClearOn();
+    this.#restoreDynamic.activate();
+    this.#observer.observe(this.element, {
+      attributes: true,
+      attributeFilter: [
+        "checked",
+        "data-controller",
+        "data-stimeo--persist-target",
+        "id",
+        "multiple",
+        "name",
+        "selected",
+        "type",
+        "value"
+      ],
+      childList: true,
+      subtree: true
+    });
+    this.#loadActiveDraft();
   }
   disconnect() {
+    this.#flushPendingSave();
+    this.#connected = false;
     this.element.removeEventListener("input", this.#onInput);
     this.element.removeEventListener("change", this.#onInput);
-    if (this.clearOnValue.length > 0) {
-      this.element.removeEventListener(this.clearOnValue, this.#onClearEvent);
-    }
-    if (this.#saveId !== null) {
-      this.#timeouts.clear(this.#saveId);
-      this.#saveId = null;
-      this.#write();
-    }
+    this.#unbindClearOn();
+    this.#observer.disconnect();
+    this.#restoreDynamic.cancel();
+    this.#forcedRestore.clear();
     this.#timeouts.clearAll();
+    this.element.removeAttribute("data-persist-restored");
+    this.#payload = null;
   }
-  /** Drops the saved draft and clears the restored marker. */
+  /** Drops the active draft after storage confirms the removal. */
   clear() {
-    const key = this.#storageKey;
-    if (key === null) return;
-    if (this.#saveId !== null) {
-      this.#timeouts.clear(this.#saveId);
-      this.#saveId = null;
+    const logicalKey = this.#logicalKey ?? this.#resolveLogicalKey();
+    if (logicalKey === null) return;
+    this.#cancelPendingSave();
+    const result = removeLocalStorage(this.#storageKey(logicalKey));
+    if (!result.ok) {
+      this.#dispatchError(logicalKey, "remove", "unavailable");
+      return;
     }
-    this.#removeItem(key);
+    this.#payload = null;
     this.element.removeAttribute("data-persist-restored");
-    this.dispatch("clear", { detail: { key: this.#logicalKey } });
+    this.dispatch("clear", { detail: { key: logicalKey } });
+  }
+  /** Rebinds the external clear event when its Value changes. */
+  clearOnValueChanged() {
+    if (this.#connected) this.#syncClearOn();
+  }
+  /** Switches storage namespaces without writing old edits under the new key. */
+  keyValueChanged() {
+    if (this.#connected) this.#switchLogicalKey();
+  }
+  /** Reschedules a pending write against the current debounce delay. */
+  debounceValueChanged() {
+    if (this.#connected && this.#pendingSave !== null) this.#scheduleSave();
+  }
+  /** Restores every field the new exclusion list makes eligible. */
+  excludeValueChanged() {
+    const previous = this.#excluded;
+    this.#excluded = parseStringList(this.excludeValue, DEFAULT_EXCLUDE);
+    if (!this.#connected) return;
+    for (const field of this.#candidateFields()) {
+      if (this.#persistable(field, this.#excluded) && !this.#persistable(field, previous)) {
+        this.#forcedRestore.add(field);
+      }
+    }
+    this.#restoreDynamic.schedule();
   }
   /** Schedules a debounced save. */
   #scheduleSave() {
-    if (this.#saveId !== null) this.#timeouts.clear(this.#saveId);
-    this.#saveId = this.#timeouts.set(() => {
-      this.#saveId = null;
-      this.#save();
-    }, this.debounceValue);
-  }
-  /** Writes the current values and emits `save`. */
-  #save() {
-    this.#write();
-    this.dispatch("save", { detail: { key: this.#logicalKey } });
-  }
-  /** Serializes persistable fields and stores them under the storage key. */
-  #write() {
-    const key = this.#storageKey;
-    if (key === null) return;
-    const data = {};
-    for (const { field, key: fieldKey } of this.#fieldEntries()) {
+    const logicalKey = this.#logicalKey;
+    if (logicalKey === null) return;
+    this.#cancelPendingSave();
+    const id = this.#timeouts.set(() => {
+      this.#pendingSave = null;
+      this.#save(logicalKey);
+    }, this.#debounceDelay);
+    this.#pendingSave = { id, logicalKey };
+  }
+  /** Cancels the currently pending save, if any. */
+  #cancelPendingSave() {
+    const pending = this.#pendingSave;
+    if (pending === null) return;
+    this.#timeouts.clear(pending.id);
+    this.#pendingSave = null;
+  }
+  /** Flushes a pending edit through the same success/error event path as a timer. */
+  #flushPendingSave() {
+    const pending = this.#pendingSave;
+    if (pending === null) return;
+    this.#cancelPendingSave();
+    this.#save(pending.logicalKey);
+  }
+  /** Writes the active payload and emits `save` only after storage succeeds. */
+  #save(logicalKey) {
+    const payload = this.#serialize();
+    const result = writeLocalStorage(this.#storageKey(logicalKey), JSON.stringify(payload));
+    if (!result.ok) {
+      this.#dispatchError(logicalKey, "write", "unavailable");
+      return false;
+    }
+    this.#payload = payload;
+    this.dispatch("save", { detail: { key: logicalKey } });
+    return true;
+  }
+  /** Serializes every persistable field into a versioned, typed payload. */
+  #serialize() {
+    const fields = [];
+    for (const { field, key } of this.#fieldEntries()) {
       if (field instanceof HTMLInputElement && field.type === "checkbox") {
-        data[fieldKey] = field.checked;
+        fields.push({ key, value: field.checked });
       } else if (field instanceof HTMLInputElement && field.type === "radio") {
-        if (field.checked) data[fieldKey] = field.value;
+        if (field.checked) fields.push({ key, value: field.value });
       } else if (field instanceof HTMLSelectElement && field.multiple) {
-        data[fieldKey] = Array.from(field.selectedOptions).map((o) => o.value);
+        fields.push({
+          key,
+          value: Array.from(field.selectedOptions).map((option) => option.value)
+        });
       } else {
-        data[fieldKey] = field.value;
+        fields.push({ key, value: field.value });
       }
     }
-    this.#setItem(key, JSON.stringify(data));
-  }
-  /** Applies any saved values to the fields, without moving focus. */
-  #restore() {
-    const key = this.#storageKey;
-    if (key === null) return;
-    const raw = this.#getItem(key);
-    if (raw === null) return;
-    let data;
-    try {
-      data = JSON.parse(raw);
-    } catch {
+    return { version: 1, fields };
+  }
+  /** Reads, validates, and restores the active namespace. */
+  #loadActiveDraft() {
+    this.element.removeAttribute("data-persist-restored");
+    this.#payload = null;
+    this.#knownFields = /* @__PURE__ */ new WeakSet();
+    this.#forcedRestore.clear();
+    const logicalKey = this.#logicalKey;
+    if (logicalKey === null) {
+      this.#markCurrentFieldsKnown();
       return;
     }
-    let restoredAny = false;
-    for (const { field, key: fieldKey } of this.#fieldEntries()) {
-      if (!Object.hasOwn(data, fieldKey)) continue;
-      this.#applyValue(field, data[fieldKey]);
-      restoredAny = true;
+    const result = readLocalStorage(this.#storageKey(logicalKey));
+    if (!result.ok) {
+      this.#dispatchError(logicalKey, "read", "unavailable");
+      this.#markCurrentFieldsKnown();
+      return;
     }
-    if (restoredAny) {
+    if (result.value === null) {
+      this.#markCurrentFieldsKnown();
+      return;
+    }
+    const payload = parsePayload(result.value);
+    if (payload === null) {
+      const removal = removeLocalStorage(this.#storageKey(logicalKey));
+      this.#dispatchError(logicalKey, "read", "invalid-payload");
+      if (!removal.ok) this.#dispatchError(logicalKey, "remove", "unavailable");
+      this.#markCurrentFieldsKnown();
+      return;
+    }
+    this.#payload = payload;
+    this.#restoreEntries(null);
+  }
+  /** Restores fields inserted or made eligible after the initial connection. */
+  #restoreDynamicFields() {
+    const selected = new Set(this.#forcedRestore);
+    this.#forcedRestore.clear();
+    for (const { field } of this.#fieldEntries()) {
+      if (!this.#knownFields.has(field)) selected.add(field);
+    }
+    this.#restoreEntries(selected);
+  }
+  /** Applies the active payload to all fields, or only the supplied candidates. */
+  #restoreEntries(selected) {
+    const entries = this.#fieldEntries();
+    for (const { field } of entries) this.#knownFields.add(field);
+    const payload = this.#payload;
+    if (payload === null) return;
+    const savedFields = new Map(payload.fields.map((field) => [field.key, field]));
+    const restoredKeys = /* @__PURE__ */ new Set();
+    const processedRadios = /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      if (selected !== null && !selected.has(entry.field)) continue;
+      const saved = savedFields.get(entry.key);
+      if (saved === void 0) continue;
+      const { value } = saved;
+      if (entry.field instanceof HTMLInputElement && entry.field.type === "radio") {
+        if (processedRadios.has(entry.key)) continue;
+        processedRadios.add(entry.key);
+        const radios = entries.filter(
+          ({ key, field }) => key === entry.key && field instanceof HTMLInputElement && field.type === "radio"
+        ).map(({ field }) => field);
+        if (typeof value !== "string" || !radios.some((radio) => radio.value === value)) continue;
+        for (const radio of radios) radio.checked = radio.value === value;
+        restoredKeys.add(entry.key);
+        continue;
+      }
+      if (this.#applyValue(entry.field, value)) restoredKeys.add(entry.key);
+    }
+    if (restoredKeys.size > 0) {
+      this.#observer.takeRecords();
       this.element.setAttribute("data-persist-restored", "true");
       this.dispatch("restore", { detail: { key: this.#logicalKey } });
     }
   }
-  /** Sets a single field's value from a stored entry. */
+  /** Applies a type-compatible stored value without coercion. */
   #applyValue(field, value) {
     if (field instanceof HTMLInputElement && field.type === "checkbox") {
-      field.checked = Boolean(value);
-    } else if (field instanceof HTMLInputElement && field.type === "radio") {
-      field.checked = field.value === value;
-    } else if (field instanceof HTMLSelectElement && field.multiple) {
-      const selected = new Set(Array.isArray(value) ? value.map(String) : []);
+      if (typeof value !== "boolean") return false;
+      field.checked = value;
+      return true;
+    }
+    if (field instanceof HTMLSelectElement && field.multiple) {
+      if (!Array.isArray(value)) return false;
+      const available = new Set(Array.from(field.options).map((option) => option.value));
+      const selected = value.filter((candidate) => available.has(candidate));
+      if (value.length > 0 && selected.length === 0) return false;
+      const selectedValues = new Set(selected);
       for (const option of Array.from(field.options)) {
-        option.selected = selected.has(option.value);
+        option.selected = selectedValues.has(option.value);
       }
-    } else {
-      field.value = String(value);
+      return true;
+    }
+    if (typeof value !== "string") return false;
+    if (field instanceof HTMLSelectElement) {
+      const exists = Array.from(field.options).some((option) => option.value === value);
+      if (!exists) return false;
     }
+    field.value = value;
+    return true;
+  }
+  /** Every control this instance owns, before the exclusion list narrows them. */
+  #candidateFields() {
+    return this.hasFieldTarget ? this.fieldTargets.filter(isPersistField) : Array.from(this.element.querySelectorAll("input, textarea, select")).filter(
+      (field) => this.#ownsField(field)
+    );
   }
   /**
-   * Persistable fields paired with a stable storage key. Uniquely-named fields key
-   * by their name. Repeated same-name fields (e.g. a `tags[]` checkbox group or
-   * array text inputs) are disambiguated by DOM-order occurrence — the first keeps
-   * its plain `name`, later ones get a NUL-separated index suffix — so each is
-   * stored and restored individually instead of the last one clobbering the rest.
-   * Radios are the exception: a group intentionally shares one key (one value per
-   * name).
+   * Pairs persistable fields with DOM-order occurrence keys. Every HTML radio
+   * group (same name and form owner) occupies one shared occurrence slot.
    */
   #fieldEntries() {
     const entries = [];
-    const occurrence = /* @__PURE__ */ new Map();
-    for (const field of this.#fields()) {
+    const eligible = [];
+    for (const field of this.#candidateFields()) {
       const name = this.#keyOf(field);
-      if (name === null) continue;
+      if (name === null || !this.#persistable(field, this.#excluded)) continue;
+      eligible.push({ field, name });
+    }
+    const nextOccurrence = /* @__PURE__ */ new Map();
+    const radioSlots = /* @__PURE__ */ new Map();
+    const allocate = (name) => {
+      const occurrence = nextOccurrence.get(name) ?? 0;
+      nextOccurrence.set(name, occurrence + 1);
+      return occurrence === 0 ? name : `${name}${OCCURRENCE_SEP}${occurrence}`;
+    };
+    for (const { field, name } of eligible) {
       if (field instanceof HTMLInputElement && field.type === "radio") {
-        entries.push({ field, key: name });
+        const groups = radioSlots.get(name) ?? /* @__PURE__ */ new Map();
+        radioSlots.set(name, groups);
+        let key = groups.get(field.form);
+        if (key === void 0) {
+          key = allocate(name);
+          groups.set(field.form, key);
+        }
+        entries.push({ field, key });
         continue;
       }
-      const seen = occurrence.get(name) ?? 0;
-      occurrence.set(name, seen + 1);
-      entries.push({ field, key: seen === 0 ? name : `${name}${OCCURRENCE_SEP}${seen}` });
+      entries.push({ field, key: allocate(name) });
     }
     return entries;
   }
-  /** The fields to persist: `field` targets, or the element's named controls. */
-  #fields() {
-    const candidates = this.hasFieldTarget ? this.fieldTargets : Array.from(this.element.querySelectorAll("input, textarea, select"));
-    return candidates.filter((field) => this.#persistable(field));
-  }
   /** Whether a field carries a restorable, non-excluded value. */
-  #persistable(field) {
-    if (this.#keyOf(field) === null) return false;
-    const type = field instanceof HTMLInputElement ? field.type : "";
-    if (NON_VALUE_TYPES.has(type)) return false;
-    if (this.excludeValue.includes(type)) return false;
-    if (field.name.length > 0 && this.excludeValue.includes(field.name)) return false;
+  #persistable(field, excluded) {
+    if (NON_VALUE_TYPES.has(field.type) || SENSITIVE_TYPES.has(field.type)) return false;
+    if (excluded.includes(field.type)) return false;
+    if (field.name.length > 0 && excluded.includes(field.name)) return false;
     return true;
   }
   /** A stable storage sub-key for a field (its name, else id). */
   #keyOf(field) {
     return field.name || field.id || null;
   }
-  /** The logical key (key Value or element id), or null when neither is set. */
-  get #logicalKey() {
-    const key = this.keyValue || this.element.id;
-    return key.length > 0 ? key : null;
+  /** Whether this instance, rather than a nested Persist host, owns a field. */
+  #ownsField(field) {
+    return field.closest('[data-controller~="stimeo--persist"]') === this.element;
+  }
+  /** Marks all currently eligible fields without applying a payload. */
+  #markCurrentFieldsKnown() {
+    for (const { field } of this.#fieldEntries()) this.#knownFields.add(field);
   }
-  /** The prefixed localStorage key, or null when persistence is disabled. */
-  get #storageKey() {
-    const logical = this.#logicalKey;
-    return logical === null ? null : `${STORAGE_PREFIX}${logical}`;
+  /** Switches namespace after flushing the old namespace's pending edit. */
+  #switchLogicalKey() {
+    const next = this.#resolveLogicalKey();
+    if (next === this.#logicalKey) return;
+    this.#flushPendingSave();
+    this.#logicalKey = next;
+    this.#loadActiveDraft();
   }
-  #getItem(key) {
-    try {
-      return window.localStorage.getItem(key);
-    } catch {
-      return null;
+  /** Synchronizes the exact event name owned by the `clearOn` Value. */
+  #syncClearOn() {
+    const next = this.#validEventName(this.clearOnValue);
+    if (next === this.#registeredClearOn) return;
+    this.#unbindClearOn();
+    if (next === null) return;
+    this.element.addEventListener(next, this.#onClearEvent);
+    this.#registeredClearOn = next;
+  }
+  /** Removes the event listener using the name that was actually registered. */
+  #unbindClearOn() {
+    if (this.#registeredClearOn === null) return;
+    this.element.removeEventListener(this.#registeredClearOn, this.#onClearEvent);
+    this.#registeredClearOn = null;
+  }
+  /** Returns a non-whitespace event type, or null when the hook is disabled. */
+  #validEventName(value) {
+    const name = value.trim();
+    return name.length > 0 && !/\s/.test(name) ? name : null;
+  }
+  /** Collects dynamic controls and select-option changes into one restore pass. */
+  #onMutations(records) {
+    let rootIdChanged = false;
+    for (const record of records) {
+      if (record.type === "attributes") {
+        if (record.target === this.element && record.attributeName === "id") {
+          rootIdChanged = true;
+        }
+        this.#collectAttributeCandidate(record.target, record.attributeName);
+        continue;
+      }
+      for (const node of record.addedNodes) this.#collectRestoreCandidate(node);
+    }
+    if (rootIdChanged && this.keyValue.length === 0) this.#switchLogicalKey();
+    this.#restoreDynamic.schedule();
+  }
+  /**
+   * Adds the controls one mutated attribute can affect. Only an ownership change on a
+   * descendant moves fields between Persist hosts, so that is the single case worth a
+   * subtree sweep; every other observed attribute describes one control, and sweeping
+   * from its container would re-apply the stored draft over edits still being debounced.
+   */
+  #collectAttributeCandidate(target, attributeName) {
+    if (attributeName === OWNERSHIP_ATTRIBUTE && target !== this.element) {
+      this.#collectRestoreCandidate(target);
+      return;
     }
+    this.#collectControlCandidate(target);
   }
-  #setItem(key, value) {
-    try {
-      window.localStorage.setItem(key, value);
-    } catch {
+  /** Adds a native control, or the select that owns a mutated option. */
+  #collectControlCandidate(node) {
+    if (isPersistField(node)) {
+      this.#forcedRestore.add(node);
+      return;
+    }
+    if (node instanceof HTMLOptionElement) {
+      const select = node.closest("select");
+      if (select) this.#forcedRestore.add(select);
     }
   }
-  #removeItem(key) {
-    try {
-      window.localStorage.removeItem(key);
-    } catch {
+  /** Adds every control inside an inserted or newly owned subtree. */
+  #collectRestoreCandidate(node) {
+    this.#collectControlCandidate(node);
+    if (!(node instanceof Element)) return;
+    for (const field of node.querySelectorAll("input, textarea, select")) {
+      this.#forcedRestore.add(field);
     }
   }
+  /** Resolves the logical key from the Value, falling back to the host id. */
+  #resolveLogicalKey() {
+    const key = this.keyValue || this.element.id;
+    return key.length > 0 ? key : null;
+  }
+  /** Namespaces one logical key within localStorage. */
+  #storageKey(logicalKey) {
+    return `${STORAGE_PREFIX}${logicalKey}`;
+  }
+  /** Normalizes invalid debounce Values to the documented default. */
+  get #debounceDelay() {
+    const value = this.debounceValue;
+    return Number.isFinite(value) && value >= 0 ? value : DEFAULT_DEBOUNCE;
+  }
+  /** Dispatches one observable storage failure without exposing browser errors. */
+  #dispatchError(key, operation, reason) {
+    this.dispatch("error", { detail: { key, operation, reason } });
+  }
 };
 
 export { PersistController };