homebridge-plugin-utils 2.0.0 → 2.2.0

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

@@ -13,10 +13,10 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
  * and derives its view via selectors. Discriminated unions encode the variant types the UI moves through, each listed below:
  *
  *   - {@link Scope} - `{kind: "global"}` | `{kind: "controller", controllerId}` | `{kind: "device", controllerId, deviceId}`. The selection pointer. Discriminated
- *     because each kind carries different data; merging them into a flat record would smear the invariants across two fields and force consumers to recover the
+ *     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
@@ -63,7 +66,7 @@ import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureO
 
 /**
  * @typedef {Object} Validators
- * @property {(device: Device) => boolean} isController - Predicate for "is this device a controller-as-device" (drives controller-vs-device scope discrimination).
+ * @property {(device: Device) => boolean} isController - Predicate for "is this device a controller-as-device" (drives controller-vs-device scope distinction).
  * @property {(device: Device | undefined, option: Object) => boolean} validOption - Predicate for "should this option render for this device."
  * @property {(device: Device | undefined, category: Object) => boolean} validOptionCategory - Predicate for "should this category render for this device."
  */
@@ -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,10 +120,17 @@ 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 {{mode: "all" | "modified", query: string}} filter - Search and filter state. Two-field record because the dimensions are orthogonal (every combination
+ * @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
  *                                                 set that is not set-equal to the prior snapshot, in which case the snapshot is replaced.
@@ -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.
@@ -157,7 +181,7 @@ export const initialState = () => {
 
   // Share a single empty-array reference across every array-typed option field so the persist effect's "are we dirty?" check (configuredOptions === persistedAnchor)
   // returns true at registration time and does not trigger a spurious initial persist. After model:loaded, each field is set to the loaded array's reference; the
-  // invariant is preserved.
+  // guarantee is preserved.
   const empty = [];
 
   return {
@@ -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 after fetching the user-facing message from
-      // `/getErrorMessage`; 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/store.mjs

@@ -24,7 +24,7 @@ const ModuleCustomEvent = CustomEvent;
  *     cleanup follows the caller's {@link AbortSignal} automatically, no `destroy()` ceremony required. The signal-keyed lifecycle is the same primitive every
  *     other part of the webUI already uses for its DOM listeners, so the store's subscription model integrates without a new lifecycle concept.
  *   - **Read-then-dispatch ordering.** The reducer applies before the event fires, so a subscriber reading `store.state` from inside its handler always sees the
- *     post-dispatch state. The ordering is load-bearing: views that re-derive their DOM in response to an event must see the new state, not the pre-mutation
+ *     post-dispatch state. The ordering matters: views that re-derive their DOM in response to an event must see the new state, not the pre-mutation
  *     state that triggered the dispatch.
  *
  * The store carries no domain logic itself - the reducer (passed at construction) and the action vocabulary (consumed by subscribers) are the application-specific

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

@@ -1,6 +1,6 @@
 /* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
  *
- * webUi-featureOptions/utils.mjs: Shared utilities for the feature options webUI components.
+ * webUi-featureOptions/utils.mjs: Shared utilities for the plugin webUI - used by the feature-options components and the top-level orchestrator alike.
  */
 "use strict";
 
@@ -198,3 +198,27 @@ export function showToast(message, variant = "alert-success") {
     setTimeout(() => toast.remove(), 150);
   }, 3000);
 }
+
+/**
+ * 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(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` discriminator: header yields when
+ * 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,23 +28,25 @@ 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 devices, then dispatches a
- * `devices:loaded` action. The dispatch is wrapped in a try/catch so a failing fetch surfaces as a `connection:error` action; the view layer never silently
- * swallows a network 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) =>
- *           Promise<readonly import("../state.mjs").Device[]>) | undefined} args.getDevices
- *        - Plugin-provided fetcher for a controller's devices. Called on controller-link click.
+ *           Promise<import("../../webUi-featureOptions.mjs").DeviceListResult>) | undefined} args.getDevices
+ *        - Plugin-provided fetcher resolving a controller's DeviceListResult. Called on controller-link click.
  * @param {string} args.labelControllers - Section header label for the controllers list.
  * @param {string} args.labelDevices - Section header label for the devices list.
- * @param {{ request: (path: string) => Promise<unknown> }} args.host - Homebridge bridge (used to fetch the error message on connection failure).
  * @param {HTMLElement} args.rootControllers - The `#controllersContainer` element.
  * @param {HTMLElement} args.rootDevices - The `#devicesContainer` element.
  * @param {AbortSignal} args.signal - Lifecycle signal.
  * @param {import("../store.mjs").FeatureOptionsStore} args.store - The store.
  */
-export const mountNavView = ({ getDevices, host, labelControllers, labelDevices, rootControllers, rootDevices, signal, store }) => {
+export const mountNavView = ({ getDevices, labelControllers, labelDevices, rootControllers, rootDevices, signal, store }) => {
 
   // Controllers container rebuilds on model:loaded (initial mode/controllers), plus controllers:loaded - a controllers-only refresh hook not currently dispatched.
   effect({
@@ -96,8 +98,9 @@ export const mountNavView = ({ getDevices, host, labelControllers, labelDevices,
     store
   });
 
-  // 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({ event, getDevices, host, 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 });
@@ -122,7 +125,7 @@ const sectionHeader = (label) => createElement("h6", {
 }, [label]);
 
 // Append a labeled section to a container: an optional header followed by one rendered node per item. The header renders only when the section has at least one item,
-// so a section that heads nothing emits no header. This is the single enforcement point for the "a header labels a non-empty section" invariant - it makes an orphan
+// so a section that heads nothing emits no header. This is the single enforcement point for the "a header labels a non-empty section" rule - it makes an orphan
 // header (a label with no items beneath it) unrepresentable regardless of which list a caller renders, which is what keeps a fully-grouped device set from showing a
 // standalone top-level header that labels nothing.
 const appendSection = ({ items, label, render, root }) => {
@@ -164,7 +167,7 @@ const buildControllersList = ({ controllerLabel, mode, root, state }) => {
 
   // The controllers section. In controller-based mode there is always at least one controller by the time the sidebar builds (the orchestrator shows the
   // no-controllers message and never mounts the nav otherwise), so the non-empty guard is belt-and-suspenders here - but routing through appendSection keeps every
-  // section under one invariant rather than special-casing this one.
+  // section under one rule rather than special-casing this one.
   appendSection({
 
     items: state.controllers,
@@ -175,7 +178,7 @@ const buildControllersList = ({ controllerLabel, mode, root, state }) => {
 };
 
 // Build the devices container. The ungrouped devices form the top-level section under the device label; each sidebarGroup forms its own section in alphabetical order.
-// Because the device-label header renders only when there is at least one ungrouped device (the appendSection invariant), a fully-grouped device set - every device
+// Because the device-label header renders only when there is at least one ungrouped device (the appendSection rule), a fully-grouped device set - every device
 // carrying a sidebarGroup - shows its group headers alone, with no orphan top-level device header. Controllers are excluded from group derivation (their link lives in
 // the controllers container above); the reserved "hidden" group excludes devices from the sidebar entirely.
 const buildDevicesList = ({ catalog, deviceLabel, devices, root }) => {
@@ -238,8 +241,8 @@ 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 devices via the caller-supplied `getDevices` callback.
-const handleNavClick = async ({ event, getDevices, host, signal, store }) => {
+// fetch the new controller's DeviceListResult via the caller-supplied `getDevices` callback.
+const handleNavClick = async ({ event, getDevices, signal, store }) => {
 
   const navLink = event.target.closest(".nav-link[data-navigation]");
 
@@ -264,8 +267,8 @@ const handleNavClick = async ({ event, getDevices, host, signal, store }) => {
 
     case "controller": {
 
-      // Optimistic scope update before the fetch so the sidebar highlight repaints immediately. If the fetch fails we transition to connection:error; if it
-      // succeeds we dispatch devices:loaded and 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) {
@@ -273,43 +276,47 @@ const handleNavClick = async ({ event, getDevices, host, signal, store }) => {
         return;
       }
 
+      // 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 = await getDevices(controller ?? null);
+        const { devices, error } = await getDevices(controller ?? null);
 
+        // 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(devices.length === 0) {
-
-          // No devices returned despite a controller in scope - treat as a connection failure and surface the upstream error message via the host.
-          const message = String(await host.request("/getErrorMessage") ?? "");
-
-          if(signal.aborted) {
-
-            return;
-          }
+        store.dispatch({ controllerId: deviceSerial, devices, error, seq, type: "devices:loaded" });
 
-          store.dispatch({ message, type: "connection:error" });
+        // 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)) {
 
           return;
         }
 
         // Select the controller-as-device entry (the first device in the returned list).
         store.dispatch({ scope: { controllerId: deviceSerial, deviceId: devices[0].serialNumber, kind: "device" }, type: "scope:changed" });
-      } catch {
+      } catch(err) {
 
+        // 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: "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;
@@ -259,7 +265,7 @@ export const mountOptionsView = ({ configTable, platform, signal, store }) => {
 };
 
 // Scope-aware cache invalidation for a per-option mutation. The action's `args.id` field carries the mutation's scope marker (the persisted entry-string format
-// encodes scope by serial), so we discriminate by matching it against the controllers list:
+// encodes scope by serial), so we distinguish it by matching against the controllers list:
 //
 //   - `id` undefined - global-scope mutation. Every cached view inherits from global. Drop every entry.
 //   - `id` matches a controller's serial - controller-scope mutation. Every cached device-view under this controller inherits from it. Drop entries whose key
@@ -375,7 +381,7 @@ const buildCategoryShells = ({ configTable, state }) => {
   configTable.appendChild(fragment);
 };
 
-// Materialize the rows for a single category. Idempotent via dataset.rowsRendered - re-opening an already-built category is a no-op for materialization.
+// Materialize the rows for a single category. Guarded by dataset.rowsRendered - re-opening an already-built category is a no-op for materialization.
 const ensureRowsRendered = ({ details, state }) => {
 
   if(details.dataset.rowsRendered === "true") {

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

@@ -138,7 +138,7 @@ export const mountSearchView = ({ configTable, root, signal, store }) => {
   }
 };
 
-// Build the panel DOM and fill the `refs` record with element pointers that update functions consult later. One-time call; idempotent only insofar as it reassigns
+// Build the panel DOM and fill the `refs` record with element pointers that update functions consult later. One-time call; safe to repeat only insofar as it reassigns
 // `refs` fields (the panel itself is rebuilt fresh, replacing any prior content).
 const buildPanel = ({ refs, root }) => {
 
@@ -350,7 +350,7 @@ const handleClick = ({ configTable, event, refs, store }) => {
       // On bulk expand, synchronously drive the options view's capture-phase `toggle` handler so each category's rows materialize in the SAME layout pass as the open,
       // rather than the open reflowing first and the async native `toggle` task materializing in a second pass. Collapsing the opens and materializations into one
       // settled height change keeps the host's iframe-resize ResizeObserver from cascading ("ResizeObserver loop completed with undelivered notifications"). Row
-      // materialization is idempotent, so the native async toggle that follows is a no-op. Collapse needs no synthetic toggle - hiding rows is already one reflow.
+      // materialization only runs once, so the native async toggle that follows is a no-op. Collapse needs no synthetic toggle - hiding rows is already one reflow.
       if(shouldExpand) {
 
         details.dispatchEvent(new Event("toggle"));