homebridge-plugin-utils 2.1.0 → 2.2.0

package/dist/timer-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer-registry.js","sourceRoot":"","sources":["../src/timer-registry.ts"],"names":[],"mappings":"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"}

package/dist/ui/webUi-featureOptions/state.mjs

@@ -16,7 +16,7 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
  *     because each kind carries different data; merging them into a flat record would smear the guarantees across two fields and force consumers to recover the
  *     kind via predicates.
  *   - {@link LifecycleStatus} - `loading` | `ready` | `persisting` | `persist-error` | `connection-error`. The page-state pointer. Discriminated because the
- *     variants carry different per-state payloads (a snapshot when persisting, an error when failed, a message when the connection broke).
+ *     variants carry different per-state payloads (a snapshot when persisting, an error when failed, the full display copy when the connection broke).
  *   - {@link Catalog} - `CatalogIndex` (from featureOptions.ts) extended with plugin-provided validator callbacks. Bundled as one value because both the index and
  *     the validators are plugin-provided immutable config moving together; splitting them would force every consumer that needs both to take two parameters.
  *
@@ -25,7 +25,10 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
  *
  *   - `model:loaded` - first load: catalog, configuredOptions, controllers, mode are populated; status transitions to ready.
  *   - `controllers:loaded` - controllers-only refresh (reducer + nav subscriber wired) that no code currently dispatches; the retry path re-runs the full `model:loaded`.
- *   - `devices:loaded` - devices list updated when the active controller changes or device-only mode resolves the accessory cache.
+ *   - `devices:requested` - a device fetch is beginning: mints the next fetch sequence into state and records it as the pending request, so the outcome that
+ *     eventually answers it can be told apart from a superseded one.
+ *   - `devices:loaded` - a device fetch's outcome - its device list and connection error - stamped with the sequence its request minted. Applies only when it answers
+ *     the pending request; a superseded or seq-less outcome is dropped at this chokepoint. A non-empty error also transitions status to connection-error.
  *   - `scope:changed` - selection pointer moved (global / controller / device).
  *   - `option:set` - single option enabled/disabled (with optional value) at some scope.
  *   - `option:cleared` - single option removed at some scope.
@@ -35,7 +38,7 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
  *   - `persist:started` - persist call entering flight; status becomes persisting.
  *   - `persist:succeeded` - persist call landed on disk; anchor updated, status returns to ready.
  *   - `persist:failed` - final-attempt failure (no superseding mutation); configuredOptions rolls back to anchor, status becomes persist-error.
- *   - `connection:error` - controller unreachable on the current view; status becomes connection-error with the user-facing message.
+ *   - `connection:error` - the config re-sync failed before the page could render; status becomes connection-error carrying the full display copy the view renders.
  *
  * The reducer is pure: `(state, action) => state`. Unchanged slices retain their reference across dispatches (structural sharing), so memoized selectors that
  * depend on a slice return cached results until that specific slice changes. Unknown action types throw - silently ignoring them would let typo bugs escape into
@@ -100,8 +103,12 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
  * LifecycleStatus - The page-state pointer. Discriminated because the variants carry different per-state payloads. Drop a status variant when it stops being a
  * named UI state; add one when a new named state surfaces.
  *
+ * The `connection-error` variant carries its full display copy - `headline`, `guidance`, and `message` - so the connection-error view maps three text slots without
+ * hardcoding any prose. The two suppliers (the reducer's fetch-failure transition on {@link devices:loaded} and the orchestrator's config-sync-failure
+ * {@link connection:error} dispatch) each carry copy appropriate to their failure.
+ *
  * @typedef {{kind: "loading"} | {kind: "ready"} | {kind: "persisting", snapshot: readonly string[]} | {kind: "persist-error", error: Error}
- *           | {kind: "connection-error", message: string}} LifecycleStatus
+ *           | {kind: "connection-error", guidance: string, headline: string, message: string}} LifecycleStatus
  */
 
 /**
@@ -113,9 +120,16 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
  * @property {readonly string[]} configuredOptions - The canonical user-state array. Mutations replace it via the pure transforms from featureOptions.ts.
  * @property {readonly Controller[]} controllers - Controllers list (empty in device-only mode or before resolution).
  * @property {readonly Device[]} devices - Devices list for the active controller (or the cached-accessories list in device-only mode).
+ * @property {number} devicesAppliedSeq - The sequence of the device-fetch outcome currently applied. The reducer's own verdict fact: a dispatcher reads it back to
+ *   learn whether its outcome (the one carrying this sequence) is the one that landed, gating its follow-up work on one integer comparison rather than on the
+ *   device array's reference, which the shared-empty-array idiom and a caching `getDevices` can alias across fetches.
  * @property {string | null} devicesControllerId - Serial of the controller whose `devices` are loaded, or null (device-only / none yet). Preserves the
  *   device-to-controller association that `scope` drops once the selection goes global, so a loaded device's parent controller stays resolvable after the
  *   selection leaves controller scope.
+ * @property {{controllerId: string | null, seq: number} | null} devicesRequest - The pending device-fetch record, or null when no fetch is outstanding. A
+ *   `devices:requested` records the latest fetch here; the `devices:loaded` that carries the same sequence clears it, and any other outcome is dropped.
+ * @property {number} devicesRequestSeq - The persistent monotonic fetch counter. Never reset within a store's life, so every fetch across the session gets a unique,
+ *   increasing sequence and last-request-wins holds even for two fetches against the same controller.
  * @property {{mode: "all" | "modified", query: string}} filter - Search and filter state. Two-field record because the dimensions are independent (every combination
  *                                                                is valid and meaningful).
  * @property {readonly string[]} initialOptions - The at-show() snapshot for "Revert to Saved." Stable across the session except when re-show() loads an option
@@ -143,6 +157,16 @@ const EMPTY_CATALOG = {
   }
 };
 
+// The connection-error display copy for a controller fetch failure. The reducer supplies it at its one fetch-failure transition (on devices:loaded), so this
+// controller wording lives here rather than being hardcoded in the connection-error view, which maps every text slot from the status. The per-fetch failure
+// message travels back on the outcome and is layered on as `message`.
+const CONTROLLER_FAILURE_STATUS = {
+
+  guidance: "Check the Settings tab to verify the controller details are correct.",
+  headline: "Unable to connect to the controller.",
+  kind: "connection-error"
+};
+
 /**
  * Build the initial state. Status is `loading`; every populated-at-runtime field is set to an empty array or default value. The first {@link model:loaded}
  * dispatch transitions every field to its loaded value in one atomic update.
@@ -166,7 +190,10 @@ export const initialState = () => {
     configuredOptions: empty,
     controllers: [],
     devices: [],
+    devicesAppliedSeq: 0,
     devicesControllerId: null,
+    devicesRequest: null,
+    devicesRequestSeq: 0,
     filter: { mode: "all", query: "" },
     initialOptions: empty,
     mode: "device-only",
@@ -215,12 +242,42 @@ export const reducer = (state, action) => {
       return { ...state, controllers: action.controllers };
     }
 
+    case "devices:requested": {
+
+      // Mint the next monotonic fetch sequence and record it as the pending request. The sequence - not the controllerId - is the fetch identity, so two in-flight
+      // fetches for the same controller (a re-click, or a click racing the initial fetch) still resolve last-request-wins. The latest request owns the pending slot;
+      // an earlier in-flight fetch's outcome finds its sequence superseded when it lands.
+      const seq = state.devicesRequestSeq + 1;
+
+      return { ...state, devicesRequest: { controllerId: action.controllerId ?? null, seq }, devicesRequestSeq: seq };
+    }
+
     case "devices:loaded": {
 
-      // Devices list updated when the active controller changes or device-only mode resolves the cached-accessories list. `devicesControllerId` records which
-      // controller these devices belong to (null in device-only mode), so the association survives a later move to global scope. Scope is not touched here - the
-      // caller dispatches `scope:changed` separately if the selection needs to move.
-      return { ...state, devices: action.devices, devicesControllerId: action.controllerId ?? null };
+      // A device fetch's outcome, stamped with the sequence its `devices:requested` minted. Apply it only when it answers the pending request; a superseded or
+      // seq-less outcome vanishes here so a stale continuation cannot clobber the current view, and tests can assert reference equality on the dropped path. The null
+      // check is explicit: an optional-chained comparison would read undefined on both sides for a seq-less action against no pending request and wrongly apply it,
+      // silently green-lighting an unpaired legacy fixture.
+      if((state.devicesRequest === null) || (action.seq !== state.devicesRequest.seq)) {
+
+        return state;
+      }
+
+      // The pending request is answered. Record the applied sequence as the reducer's own verdict fact (dispatchers read it back to gate their follow-ups), clear the
+      // pending slot, and adopt the device list with its owning controller (null in device-only mode) so the association survives a later move to global scope.
+      const applied = {
+
+        ...state,
+        devices: action.devices,
+        devicesAppliedSeq: action.seq,
+        devicesControllerId: action.controllerId ?? null,
+        devicesRequest: null
+      };
+
+      // A non-empty error is the connection-failure signal: the outcome carried an empty device list and the per-fetch failure message alongside it, so the status
+      // moves to connection-error at this, the reducer's one fetch-failure transition, layering the message onto the shared controller-failure copy. Scope is not
+      // touched here - a dispatcher moves the selection separately.
+      return action.error.length ? { ...applied, status: { ...CONTROLLER_FAILURE_STATUS, message: action.error } } : applied;
     }
 
     case "scope:changed": {
@@ -304,9 +361,9 @@ export const reducer = (state, action) => {
 
     case "connection:error": {
 
-      // Controller unreachable on the current view. The orchestrator's connection-error flow dispatches this with the user-facing message that arrived alongside the
-      // device-list response; subscribers (status bar / sidebar) consume the message.
-      return { ...state, status: { kind: "connection-error", message: action.message } };
+      // The config re-sync failed before the page could render. The orchestrator dispatches this with the full display copy for the connection-error view (headline,
+      // guidance, message); the reducer's own fetch-failure transition on devices:loaded is the other supplier of this variant.
+      return { ...state, status: { guidance: action.guidance, headline: action.headline, kind: "connection-error", message: action.message } };
     }
 
     default: {

package/dist/ui/webUi-featureOptions/utils.mjs

@@ -200,14 +200,25 @@ export function showToast(message, variant = "alert-success") {
 }
 
 /**
- * Surface an arbitrary thrown value as an error toast. The webUI's extension points - caller-supplied first-run hooks, plugin device fetchers, the connection-error
- * retry callback - can reject with any shape (an Error, a string, a plain object, a primitive), so the message is extracted defensively: `err?.message` when the
- * value carries one, a string coercion of the whole value otherwise. This is the single normalization every user-facing catch across the webUI routes through, so
- * the toast text stays useful regardless of what bubbled out.
+ * Extract a user-facing message from an arbitrary thrown value. The webUI's extension points - caller-supplied first-run hooks, plugin device fetchers, the
+ * connection-error retry callback, the config re-sync - can reject with any shape (an Error, a string, a plain object, a primitive), so the message is extracted
+ * defensively: `err?.message` when the value carries one, a string coercion of the whole value otherwise. This is the single error-to-text truth the webUI shares,
+ * so a toast, a nav-view connection-error message, and the sync-failure copy all read the same thrown value the same way.
+ *
+ * @param {*} err - The thrown value to describe.
+ * @returns {string} The extracted message.
+ */
+export function errorMessage(err) {
+
+  return err?.message ?? String(err);
+}
+
+/**
+ * Surface an arbitrary thrown value as an error toast. Routes the value through {@link errorMessage} so the toast text stays useful regardless of what bubbled out.
  *
  * @param {*} err - The thrown value to surface.
  */
 export function toastError(err) {
 
-  homebridge.toast.error(err?.message ?? String(err), "Error");
+  homebridge.toast.error(errorMessage(err), "Error");
 }

package/dist/ui/webUi-featureOptions/views/connectionError.mjs

@@ -10,15 +10,16 @@ import { effect } from "../store.mjs";
 /**
  * Mount the connection-error view.
  *
- * Subscribes to `connection:error` and `model:loaded`. On `model:loaded` this view yields - it aborts its retry window and stops rendering - and the shared
- * `#headerInfo` container is reclaimed by the header view; it does not itself clear the error display.
+ * Subscribes to `connection:error`, `devices:loaded`, and `model:loaded`. On `model:loaded` this view yields - it aborts its retry window and stops rendering - and the
+ * shared `#headerInfo` container is reclaimed by the header view; it does not itself clear the error display.
  *
  * Renders into the same `#headerInfo` container the priority-chain header uses. The two views coordinate via the `state.status` tag: header yields when
  * status is connection-error; this view yields when status is anything else.
  *
  * Renders:
  *
- *   - An error message block with the user-facing message from `state.status.message`.
+ *   - An error block whose headline, guidance, and message all come from the `connection-error` status. The caller - the reducer's fetch-failure transition or the
+ *     orchestrator's config-sync-failure dispatch - supplies the full display copy, so this view maps the three text slots without hardcoding any prose.
  *   - A retry button, initially disabled, that becomes enabled after `retryDelayMs` milliseconds. The delay is a brief throttle so the user does not retry-bash a
  *     recovering controller.
  *   - A progress bar that fills during the retry-delay window so the user has visual feedback that the retry button is coming alive.
@@ -38,13 +39,28 @@ export const mountConnectionErrorView = ({ onRetry, retryDelayMs = 5000, root, s
   // retry button does not linger after the user navigates away.
   let retryAbort = null;
 
+  // The last status object this view acted on. The reducer mints a new status object only on a genuine transition, so a `devices:loaded` that did not move the status
+  // leaves this reference unchanged and the effect below skips - a dropped or successful device outcome neither tears down an armed retry window nor restarts its
+  // progress animation.
+  let lastStatus;
+
   effect({
 
-    events: [ "connection:error", "model:loaded" ],
+    events: [ "connection:error", "devices:loaded", "model:loaded" ],
     fn: () => {
 
       const { status } = store.state;
 
+      // Skip when the status is reference-identical to the one already acted on. The subscription includes `devices:loaded` because the reducer folds its
+      // fetch-failure transition into that action - without the subscription the folded error would never render the retry UI - and this guard keeps a successful or
+      // dropped device outcome, which does not touch the status, from resetting the retry window that a live connection-error is showing.
+      if(status === lastStatus) {
+
+        return;
+      }
+
+      lastStatus = status;
+
       // Tear down any prior retry window before either rendering a new one or yielding back to the header view.
       retryAbort?.abort();
       retryAbort = null;
@@ -55,7 +71,7 @@ export const mountConnectionErrorView = ({ onRetry, retryDelayMs = 5000, root, s
       }
 
       retryAbort = new AbortController();
-      renderError({ message: status.message, onRetry, retryDelayMs, retrySignal: retryAbort.signal, root });
+      renderError({ guidance: status.guidance, headline: status.headline, message: status.message, onRetry, retryDelayMs, retrySignal: retryAbort.signal, root });
     },
     signal,
     store
@@ -68,15 +84,16 @@ export const mountConnectionErrorView = ({ onRetry, retryDelayMs = 5000, root, s
   }, { once: true });
 };
 
-// Render the error block into the root container. Builds the structural pieces (error text, retry button, progress bar) and arms the retry window via the
-// supplied retry signal.
-const renderError = ({ message, onRetry, retryDelayMs, retrySignal, root }) => {
+// Render the error block into the root container. Builds the structural pieces (headline, guidance, the failure message, retry button, progress bar) and arms the
+// retry window via the supplied retry signal. The three text slots - headline, guidance, message - are caller-supplied through the status, so this view holds no
+// hardcoded failure prose of its own.
+const renderError = ({ guidance, headline, message, onRetry, retryDelayMs, retrySignal, root }) => {
 
   const errorBlock = createElement("div", {}, [
 
-    "Unable to connect to the controller.",
+    headline,
     createElement("br"),
-    "Check the Settings tab to verify the controller details are correct.",
+    guidance,
     createElement("br"),
     createElement("code", { classList: ["text-danger"] }, [message]),
     createElement("br")

package/dist/ui/webUi-featureOptions/views/deviceInfo.mjs

@@ -34,6 +34,13 @@ export const mountDeviceInfoView = ({ infoPanel = defaultInfoPanel, root, signal
     events: [ "scope:changed", "devices:loaded", "model:loaded" ],
     fn: () => {
 
+      // Skip the pre-model mount. The orchestrator mounts every view before model:loaded fires, so this view's immediate-run pass would otherwise render against the
+      // loading placeholder - work the model:loaded pass immediately redoes. The sibling views carry the same guard.
+      if(store.state.status.kind === "loading") {
+
+        return;
+      }
+
       // The view populates its region but never reveals it; the orchestrator owns region visibility (revealRegions on the success path), so the device-stats panel
       // appears together with the rest of the populated UI rather than the moment this view mounts.
       render(infoPanel);

package/dist/ui/webUi-featureOptions/views/header.mjs

@@ -14,7 +14,8 @@ import { effect } from "../store.mjs";
  * device-only mode. Bold lead-in text frames it as a precedence statement; color-coded labels (warning / success / info) match the same scope-color convention the
  * row labels use, so users have one consistent visual lens for "where does a setting come from."
  *
- * Runs on `model:loaded` and `connection:error`; all other dispatches never invoke it because they are not subscribed. On `connection:error` (and the loading
+ * Runs on `model:loaded`, `connection:error`, and `devices:loaded`; other dispatches never invoke it because they are not subscribed, and a subscribed dispatch
+ * that leaves the status reference unchanged skips via the memo below. On `connection:error` (and the loading
  * status), `fn` yields inside its `status.kind` checks. In practice the header content is rendered once, at `model:loaded`. The connection-error and no-controllers
  * views render their own content into the same container, so this view yields when the status indicates either of those states.
  *
@@ -25,22 +26,38 @@ import { effect } from "../store.mjs";
  */
 export const mountHeaderView = ({ root, signal, store }) => {
 
+  // The last status object this view acted on. The reducer mints a new status object only on a genuine transition, so a `devices:loaded` that did not move the status
+  // (a successful fetch, or a dropped stale outcome that returns the identical state) leaves this reference unchanged and the effect below skips - the precedence
+  // chain is never rebuilt for a device-list change it does not depend on.
+  let lastStatus;
+
   effect({
 
-    events: [ "model:loaded", "connection:error" ],
+    events: [ "connection:error", "devices:loaded", "model:loaded" ],
     fn: () => {
 
       const { mode, status } = store.state;
 
+      // Skip when the status is reference-identical to the one already acted on: this view renders from `mode` and `status`, and `mode` is fixed after model:loaded,
+      // so an unchanged status means nothing to redo. The subscription includes `devices:loaded` because the reducer folds its fetch-failure transition into that
+      // action - without the subscription the header would never yield to the connection-error view on a failed fetch - and this guard keeps every successful or
+      // dropped device outcome from needlessly rebuilding the chain.
+      if(status === lastStatus) {
+
+        return;
+      }
+
+      lastStatus = status;
+
       // Yield to the connection-error view when an error is active - that view owns the header content in error states.
       if(status.kind === "connection-error") {
 
         return;
       }
 
-      // Defensive guard against a "loading" status at mount time. In the current call order this branch is unreachable: the no-controllers path returns from
-      // show() before any views mount, and the success path dispatches model:loaded - which sets status to ready - before mountHeaderView runs. The check stays
-      // in place as a safeguard against a future reordering that mounts views before model:loaded fires.
+      // Yield on the "loading" status at mount time. The orchestrator mounts every view before model:loaded fires - so the connection-error view exists to render a
+      // sync failure - which means this view's immediate-run pass sees the loading placeholder and must not render the precedence chain against an empty model. The
+      // model:loaded dispatch fires this effect again with a ready status, which is when the chain actually renders.
       if(status.kind === "loading") {
 
         return;

package/dist/ui/webUi-featureOptions/views/nav.mjs

@@ -4,7 +4,7 @@
  */
 "use strict";
 
-import { createElement } from "../utils.mjs";
+import { createElement, errorMessage } from "../utils.mjs";
 import { effect } from "../store.mjs";
 
 /**
@@ -28,11 +28,12 @@ import { effect } from "../store.mjs";
  *   - `scope:changed` - update active-link highlighting without rebuilding.
  *   - `model:loaded` - initial build (controllers + global link + mode-aware structure).
  *
- * The controller-click handler does I/O: it calls the caller-supplied `getDevices` callback to fetch the new controller's DeviceListResult, then dispatches a
- * `devices:loaded` action followed by either a scope change (devices present) or a `connection:error` (the result carried a failure message). A per-mount fetch
- * generation guards the last-resolved-wins race: the newest click owns the store, so a superseded controller click discards its result on both settlement paths
- * (resolve and reject) rather than overwriting the newer click's rendered state. The handler wraps its fetch in a try/catch so a rejected fetch surfaces as a
- * `connection:error` action rather than an unhandled rejection; the view layer never silently swallows a failure.
+ * The controller-click handler does I/O: it records the fetch at the store (`devices:requested`, which mints the fetch sequence), calls the caller-supplied
+ * `getDevices` callback for the new controller's DeviceListResult, then stamps the outcome onto a `devices:loaded` carrying that sequence. The reducer applies the
+ * outcome only when it still answers the pending request, so the sequence is the fetch identity and the newest click owns the store: a superseded controller click's
+ * outcome - whether it resolved with devices or rejected - is dropped at the reducer rather than overwriting the newer click's rendered state. A failed fetch's
+ * message travels back on that same `devices:loaded` (empty devices, non-empty error), which the reducer turns into the connection-error transition. The handler
+ * wraps its fetch in a try/catch so a rejected fetch becomes that same outcome rather than an unhandled rejection; the view layer never silently swallows a failure.
  *
  * @param {Object} args
  * @param {((controller: import("../state.mjs").Controller | null) =>
@@ -97,14 +98,9 @@ export const mountNavView = ({ getDevices, labelControllers, labelDevices, rootC
     store
   });
 
-  // Per-mount fetch generation for the controller-click handler. Held as a mutable reference (not a plain number) because handleNavClick is module-scope: a number
-  // would be copied by value into the call, defeating the guard. The closure-held object mirrors the connection-error view's retryAbort per-mount state. Each
-  // controller click captures the incremented generation before its fetch; a continuation whose generation no longer matches has been superseded by a newer click and
-  // discards its result.
-  const clickFetch = { generation: 0 };
-
-  // Click delegation: one listener on each container resolves the clicked nav link's `data-navigation` and dispatches the appropriate scope-change.
-  const onClick = (event) => handleNavClick({ clickFetch, event, getDevices, signal, store });
+  // Click delegation: one listener on each container resolves the clicked nav link's `data-navigation` and dispatches the appropriate scope-change. The
+  // last-request-wins race a controller click can open is owned by the reducer's fetch sequence, so the handler holds no per-mount generation state of its own.
+  const onClick = (event) => handleNavClick({ event, getDevices, signal, store });
 
   rootControllers.addEventListener("click", onClick, { signal });
   rootDevices.addEventListener("click", onClick, { signal });
@@ -246,7 +242,7 @@ const applyDevicesHighlight = (root, scope) => {
 
 // Handle a click on any nav link. Resolves the click target's `data-navigation` and dispatches the corresponding scope-change. Controller clicks additionally
 // fetch the new controller's DeviceListResult via the caller-supplied `getDevices` callback.
-const handleNavClick = async ({ clickFetch, event, getDevices, signal, store }) => {
+const handleNavClick = async ({ event, getDevices, signal, store }) => {
 
   const navLink = event.target.closest(".nav-link[data-navigation]");
 
@@ -271,8 +267,8 @@ const handleNavClick = async ({ clickFetch, event, getDevices, signal, store })
 
     case "controller": {
 
-      // Optimistic scope update before the fetch so the sidebar highlight repaints immediately. If the result carries a failure message we transition to
-      // connection:error; if it carries devices we select the controller-as-device entry (the first device in the returned list).
+      // Optimistic scope update before the fetch so the sidebar highlight repaints immediately. The fetch's outcome lands through the request/outcome pairing
+      // below - the reducer owns both the staleness decision and the failure transition - and a devices-bearing outcome selects the controller-as-device entry.
       store.dispatch({ scope: { controllerId: deviceSerial, kind: "controller" }, type: "scope:changed" });
 
       if(!getDevices) {
@@ -280,35 +276,31 @@ const handleNavClick = async ({ clickFetch, event, getDevices, signal, store })
         return;
       }
 
-      // Capture this fetch's generation before awaiting. The newest click owns the store, so a continuation whose generation no longer matches has been superseded by
-      // a later click and discards its result on both settlement paths below.
-      const generation = ++clickFetch.generation;
+      // Record this fetch at the store's chokepoint before awaiting, then read back the minted sequence - the store's ticket for this fetch. The newest click owns
+      // the pending slot, so a superseded click's outcome finds its sequence gone when it lands and drops at the reducer.
+      store.dispatch({ controllerId: deviceSerial, type: "devices:requested" });
+
+      const seq = store.state.devicesRequest.seq;
 
       try {
 
         const controller = store.state.controllers.find((c) => c.serialNumber === deviceSerial);
         const { devices, error } = await getDevices(controller ?? null);
 
-        // Bail if the page tore down or a newer click superseded this one; a stale continuation must not overwrite the newer click's rendered state.
-        if(signal.aborted || (generation !== clickFetch.generation)) {
+        // Bail if the page tore down; a torn-down store must not be dispatched against. Staleness itself is the reducer's job - it drops an outcome whose sequence no
+        // longer answers the pending request.
+        if(signal.aborted) {
 
           return;
         }
 
-        store.dispatch({ controllerId: deviceSerial, devices, type: "devices:loaded" });
-
-        if(error.length) {
-
-          // The result carried a connection-failure message - hand the header to the connection-error view. The message arrived with the device-list response, so no
-          // separate request is made.
-          store.dispatch({ message: error, type: "connection:error" });
-
-          return;
-        }
+        store.dispatch({ controllerId: deviceSerial, devices, error, seq, type: "devices:loaded" });
 
-        if(devices.length === 0) {
+        // Gate the follow-up on the reducer's own verdict: select the controller-as-device entry only when my outcome is the one that applied, carried no failure,
+        // and returned at least one device. A superseded outcome, a connection failure (the reducer moved the store to connection-error), or an empty controller each
+        // leaves the optimistic controller scope standing with no device-scope dispatch.
+        if((store.state.devicesAppliedSeq !== seq) || error.length || (devices.length === 0)) {
 
-          // A legitimately empty controller: the optimistic controller scope stands over the empty list, with no device-scope dispatch.
           return;
         }
 
@@ -316,14 +308,15 @@ const handleNavClick = async ({ clickFetch, event, getDevices, signal, store })
         store.dispatch({ scope: { controllerId: deviceSerial, deviceId: devices[0].serialNumber, kind: "device" }, type: "scope:changed" });
       } catch(err) {
 
-        // The same staleness bail guards the reject path: a superseded fetch that rejects (an IPC failure, the contract-guard TypeError) must not dispatch a stale
-        // connection:error over the newer click's state. A named Error reaches the user verbatim; non-Error junk falls back to the generic sentence.
-        if(signal.aborted || (generation !== clickFetch.generation)) {
+        // The page-teardown bail guards the reject path too. Route the rejection (an IPC failure, the contract-guard TypeError) through the same outcome channel: the
+        // reducer drops it if a newer click superseded this one, and otherwise clears the stale device list and moves the store to connection-error. A named Error
+        // reaches the user verbatim; other junk is stringified.
+        if(signal.aborted) {
 
           return;
         }
 
-        store.dispatch({ message: (err instanceof Error) ? err.message : "Failed to fetch devices.", type: "connection:error" });
+        store.dispatch({ controllerId: deviceSerial, devices: [], error: errorMessage(err), seq, type: "devices:loaded" });
       }
 
       return;

package/dist/ui/webUi-featureOptions/views/options.mjs

@@ -33,7 +33,8 @@ import { effect } from "../store.mjs";
  *
  * @param {Object} args
  * @param {HTMLElement} args.configTable - The `#configTable` element.
- * @param {string | undefined} args.platform - The Homebridge plugin platform identifier (for localStorage key namespacing).
+ * @param {() => (string | undefined)} args.platform - A thunk returning the Homebridge plugin platform identifier (for localStorage key namespacing). Deferred as a
+ *        thunk because the views mount before the session re-syncs, so the identifier is read inside the model:loaded effect - post-sync - rather than at mount.
  * @param {AbortSignal} args.signal - Lifecycle signal.
  * @param {import("../store.mjs").FeatureOptionsStore} args.store - The store.
  */
@@ -44,10 +45,14 @@ export const mountOptionsView = ({ configTable, platform, signal, store }) => {
   let mountedKey;
 
   // Per-view category expansion state, persisted via localStorage. The orchestrator writes the user's expand/collapse choices through this object so the disk
-  // projection survives page reloads; on re-entry to a view we apply the persisted state so the user's collapse choices stay sticky across sessions.
-  const categoryState = new FeatureOptionsCategoryState(platform);
-
-  // Rebuild on model:loaded - clears any prior content and prepares for the first scope-render. The actual category shells come from the scope-render path.
+  // projection survives page reloads; on re-entry to a view we apply the persisted state so the user's collapse choices stay sticky across sessions. Its localStorage
+  // namespace is the platform identifier, which is only correct once the session has re-synced, so it is constructed inside the model:loaded effect below (reading the
+  // `platform` thunk post-sync) rather than at mount - the views mount before the sync resolves.
+  let categoryState;
+
+  // Rebuild on model:loaded - construct the category-state store from the freshly-synced platform, then clear any prior content and prepare for the first
+  // scope-render. The actual category shells come from the scope-render path. This effect is registered before the scope-render effect below, so on a model:loaded
+  // dispatch it runs first and `categoryState` is built before that effect reads it.
   effect({
 
     events: ["model:loaded"],
@@ -58,6 +63,7 @@ export const mountOptionsView = ({ configTable, platform, signal, store }) => {
         return;
       }
 
+      categoryState = new FeatureOptionsCategoryState(platform());
       configTable.textContent = "";
       cache.clear();
       mountedKey = undefined;