homebridge-plugin-utils 1.34.0 → 2.0.0

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

@@ -0,0 +1,360 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/selectors.mjs: Memoized pure derivations over the feature options state.
+ */
+"use strict";
+
+import { buildConfigIndex, expandOption, isDependencyMet, isValueOption, resolveScope } from "../featureOptions.js";
+import { memoize } from "./store.mjs";
+
+/**
+ * Memoized pure derivations over the feature options state.
+ *
+ * Every selector here reads from {@link FeatureOptionsState} (the shape defined in `webUi-featureOptions/state.mjs`) and returns a derived value. Selectors are
+ * the read side of the unidirectional data flow - views and effects consume them, dispatches do not. Each selector is memoized via {@link memoize} on its specific
+ * dependency slices, so a state transition that does not touch a selector's inputs returns a cached result in O(1).
+ *
+ * Composition: selectors that build on other selectors call them through their memoized exports. {@link projection} calls {@link configIndex} and
+ * {@link selectedDevice}; each of those is independently cached. A dispatch that only changes `state.filter` re-runs `projection` (cache miss) but the inner
+ * `configIndex` and `selectedDevice` calls hit their caches and return without recomputation.
+ *
+ * Reference-equality everywhere: the reducer's structural-sharing contract guarantees that unchanged slices retain their reference across dispatches. Selectors
+ * compare slice references via `===`, which is the right grain for typical state mutations - a `scope:changed` dispatch produces a new `state.scope` reference but
+ * leaves `state.catalog` and `state.configuredOptions` unchanged, so any selector depending only on the latter pair hits its cache.
+ *
+ * @module
+ */
+
+/**
+ * Extract the controller serial from the scope discriminator, or null when no controller is in context. Pure helper - one-line discriminant read, not memoized.
+ *
+ * @param {import("./state.mjs").FeatureOptionsState} state - The current state.
+ * @returns {string | null} The controller serial when the scope is controller-based, null otherwise.
+ */
+export const selectedControllerId = (state) => {
+
+  switch(state.scope.kind) {
+
+    case "controller":
+
+      return state.scope.controllerId;
+
+    case "device":
+
+      return state.scope.controllerId;
+
+    default:
+
+      return null;
+  }
+};
+
+/**
+ * Extract the device serial from the scope discriminator, or null when the scope is global or controller-only. Pure helper - one-line discriminant read, not
+ * memoized.
+ *
+ * @param {import("./state.mjs").FeatureOptionsState} state - The current state.
+ * @returns {string | null} The device serial when the scope is device-based, null otherwise.
+ */
+export const selectedDeviceId = (state) => {
+
+  return (state.scope.kind === "device") ? state.scope.deviceId : null;
+};
+
+/**
+ * Map a {@link Scope} to a string key that uniquely identifies the view. Pure derivation from the discriminated union - every Scope variant maps to a distinct
+ * key and no two variants collide.
+ *
+ * Used as the SSOT identifier for "which view is this" wherever a view's identity matters across mutations or navigations: the in-memory DOM cache keys its
+ * entries by this, and the category-state localStorage projection uses the same key as its context identifier. Sharing one identifier across the two consumers
+ * means a navigation and a localStorage lookup observe the same notion of "view," and any future code that needs to address a view by id picks up the same
+ * convention without inventing a parallel scheme.
+ *
+ * Format:
+ *
+ *   - `global` - the global-scope view, single canonical key.
+ *   - `controller:<serial>` - a controller's transient between-click view. Distinct per controller; never collides with the global key.
+ *   - `device:<controllerSerial>/<deviceSerial>` - a device view under a controller (or under no controller in device-only mode, where the slot is empty). The
+ *     compound key encodes the full inheritance lineage so a controller-scope cache invalidation can match every device under that controller by string prefix
+ *     in O(N) over the cache without consulting the controller/devices lists.
+ *
+ * Delimiter contract: the device-key format relies on serial values not containing the `"/"` character, which matches the MAC-derived hex format Homebridge uses
+ * for device and controller serials. A serial containing `"/"` would let the prefix match in {@link mountOptionsView}'s scope-aware cache invalidation over-match
+ * unrelated entries. If that assumption ever needs to weaken (e.g., a plugin starts surfacing user-chosen serials), encode the components with
+ * `encodeURIComponent` at this seam before composing the key.
+ *
+ * @param {import("./state.mjs").Scope} scope - The scope discriminator.
+ * @returns {string} A stable string key identifying the view.
+ */
+export const scopeCacheKey = (scope) => {
+
+  switch(scope.kind) {
+
+    case "global":
+
+      return "global";
+
+    case "controller":
+
+      return "controller:" + scope.controllerId;
+
+    case "device":
+
+      return "device:" + (scope.controllerId ?? "") + "/" + scope.deviceId;
+
+    default:
+
+      // Exhaustive switch over the Scope DU - this branch is unreachable as long as the DU stays in sync with the cases above. A future variant addition surfaces
+      // here as a runtime throw rather than a silent fallthrough that produces a colliding key.
+      throw new Error("scopeCacheKey: unknown scope kind.");
+  }
+};
+
+/**
+ * Build the O(1) lookup index from the configured-options array. Memoized on `(catalog, configuredOptions)` so any dispatch that does not touch the configured
+ * options returns the cached index without rebuilding.
+ *
+ * Consumed by every other selector that needs to resolve options through the scope hierarchy (projection, rendering factories, effects) - sharing one cached index
+ * across them means the parse-and-build work happens at most once per configured-options mutation.
+ *
+ * @param {import("./state.mjs").FeatureOptionsState} state - The current state.
+ * @returns {import("../featureOptions.js").ConfigIndex} The lookup index.
+ */
+export const configIndex = memoize({
+
+  compute: (state) => buildConfigIndex(state.catalog, state.configuredOptions),
+  slices: [ (s) => s.catalog, (s) => s.configuredOptions ]
+});
+
+/**
+ * Resolve the currently-selected device by walking the devices list for the scope's deviceId. Memoized on `(scope, devices)` so any dispatch that does not touch
+ * the selection or the devices list returns the cached result.
+ *
+ * Returns `undefined` for the global view (no device in scope) and for a scope.kind of "controller" (the controller-level view has no concrete device until the
+ * user drills in). Consumers that need the device for validator calls pass `undefined` through directly - the validator signatures expect a possibly-undefined
+ * device for exactly this case.
+ *
+ * @param {import("./state.mjs").FeatureOptionsState} state - The current state.
+ * @returns {import("./state.mjs").Device | undefined} The selected device, or undefined.
+ */
+export const selectedDevice = memoize({
+
+  compute: (state) => {
+
+    if(state.scope.kind !== "device") {
+
+      return undefined;
+    }
+
+    return state.devices.find((d) => d.serialNumber === state.scope.deviceId);
+  },
+  slices: [ (s) => s.scope, (s) => s.devices ]
+});
+
+/**
+ * Resolve the currently-selected controller by walking the controllers list for the scope's controllerId. Memoized on `(scope, controllers)`.
+ *
+ * Returns `null` for the global view (no controller in scope), the device-only-mode device view (controllerId is null), or when the controller is not found.
+ * Consumers display the controller's name in headers / breadcrumbs and skip the display entirely on null.
+ *
+ * @param {import("./state.mjs").FeatureOptionsState} state - The current state.
+ * @returns {import("./state.mjs").Controller | null} The selected controller, or null.
+ */
+export const selectedController = memoize({
+
+  compute: (state) => {
+
+    const controllerId = selectedControllerId(state);
+
+    if(controllerId === null) {
+
+      return null;
+    }
+
+    return state.controllers.find((c) => c.serialNumber === controllerId) ?? null;
+  },
+  slices: [ (s) => s.scope, (s) => s.controllers ]
+});
+
+/**
+ * @typedef {Object} ProjectionEntry
+ * @property {string} description - The option's display description.
+ * @property {boolean} enabled - The resolved enabled state at the highest-precedence scope where the option was found (or the catalog default at scope "none").
+ * @property {string} expandedName - The canonical `category.option` identifier.
+ * @property {boolean} isGrouped - The option declares a `group` in the catalog (subordinate to a parent option).
+ * @property {boolean} isModified - The option has a configured entry at any scope (not just the default).
+ * @property {string} name - The option's catalog name (without the category prefix).
+ * @property {import("../featureOptions.js").FeatureOptionEntry} option - The raw catalog entry for the option.
+ * @property {boolean} requiresParentBadge - The "requires parent" badge applies: option is visible, grouped, and its parent is currently disabled.
+ * @property {import("../featureOptions.js").OptionScope} scope - The scope at which the option resolved ("device" / "controller" / "global" / "none").
+ * @property {string | undefined} value - The resolved value for value-centric options when enabled; undefined for booleans and disabled options.
+ * @property {boolean} visible - The option's row should be displayed under the current search query, filter mode, and dependency state.
+ */
+
+/**
+ * @typedef {Object} ProjectionCategory
+ * @property {import("../featureOptions.js").FeatureCategoryEntry} category - The raw catalog entry for the category.
+ * @property {string} description - The category's display description.
+ * @property {readonly ProjectionEntry[]} entries - The active options for this category, in catalog order.
+ * @property {boolean} hasVisible - At least one entry has `visible === true`.
+ * @property {string} name - The category's name.
+ */
+
+/**
+ * @typedef {Object} ProjectionCounts
+ * @property {number} grouped - Active options that declare a `group` (subordinate to a parent).
+ * @property {number} modified - Active options with an explicit configured entry at any scope.
+ * @property {number} total - Active options across every active (validator-passed) category, regardless of per-entry visibility.
+ * @property {number} visible - Active options currently visible under the search query, filter mode, and dependency state.
+ */
+
+/**
+ * @typedef {Object} Projection
+ * @property {readonly ProjectionCategory[]} categories - Active categories in catalog order. Categories with zero active options are omitted.
+ * @property {ProjectionCounts} counts - Aggregate counts across the active option set.
+ */
+
+/**
+ * The view projection. One pass over the active option set produces every downstream display decision: status-bar counts, per-category visibility, per-row
+ * visibility, per-row dependency-badge state, and per-row resolved value for value-centric options. Memoized on `(catalog, configuredOptions, scope, filter,
+ * devices)` so any dispatch that does not touch those slices returns the cached projection.
+ *
+ * Visibility rules (the three-way cascade below is authoritative for what a row shows):
+ *
+ *   - The `modified` filter excludes unmodified options unconditionally.
+ *   - A non-empty search query excludes options whose description does not contain the query (case-insensitive).
+ *   - When either search or modified filter is active, dependency-hiding is SUPPRESSED - grouped options with disabled parents stay visible (with a "requires
+ *     parent" badge) instead of disappearing. The rationale: a user who searched explicitly wants to see matches; hiding a match because its parent is off would
+ *     be more confusing than the badge.
+ *   - When neither search nor filter is active, grouped options with disabled parents are HIDDEN entirely. The dependency-hide is the natural state.
+ *
+ * `requiresParentBadge` collapses the combined predicate `visible && isGrouped && !dependencyMet` into one boolean so rendering code does not have to reconstruct
+ * the rule from the raw fields.
+ *
+ * @param {import("./state.mjs").FeatureOptionsState} state - The current state.
+ * @returns {Projection} The computed projection.
+ */
+export const projection = memoize({
+
+  compute: (state) => computeProjection(state),
+  slices: [ (s) => s.catalog, (s) => s.configuredOptions, (s) => s.scope, (s) => s.filter, (s) => s.devices ]
+});
+
+// The projection's compute path. Walks the catalog once, applies validators, resolves each option through the scope hierarchy, computes per-entry flags and the
+// overall counts. Pulled out of the memoize call site for readability - the function body is too long to inline in a property value.
+const computeProjection = (state) => {
+
+  const { catalog, filter } = state;
+  const idx = configIndex(state);
+  const device = selectedDevice(state);
+  const controllerId = selectedControllerId(state) ?? undefined;
+  const deviceId = selectedDeviceId(state) ?? undefined;
+  const query = filter.query.toLowerCase();
+  const filterActive = (query.length > 0) || (filter.mode === "modified");
+
+  const categories = [];
+  const counts = { grouped: 0, modified: 0, total: 0, visible: 0 };
+
+  for(const category of catalog.categories) {
+
+    if(!catalog.validators.validOptionCategory(device, category)) {
+
+      continue;
+    }
+
+    const entries = [];
+    let categoryHasVisible = false;
+
+    for(const option of (catalog.options[category.name] ?? [])) {
+
+      if(!catalog.validators.validOption(device, option)) {
+
+        continue;
+      }
+
+      const expandedName = expandOption(category, option);
+      const resolved = resolveScope({ catalog, configIndex: idx, controller: controllerId, device: deviceId, option: expandedName });
+      const optionIsGrouped = option.group !== undefined;
+      const optionIsModified = resolved.scope !== "none";
+      const optionDependencyMet = isDependencyMet({ catalog, configIndex: idx, controller: controllerId, device: deviceId, option: expandedName });
+
+      // Visibility cascade: modified filter, search query, then dependency-hide (only when neither filter nor search is active).
+      let visible = true;
+
+      if((filter.mode === "modified") && !optionIsModified) {
+
+        visible = false;
+      } else if((query.length > 0) && !option.description.toLowerCase().includes(query)) {
+
+        visible = false;
+      } else if(!filterActive) {
+
+        visible = optionDependencyMet;
+      }
+
+      // Resolve the displayable value for value-centric options. Mirrors the FeatureOptions.value() semantics: explicit configured value wins, otherwise the
+      // catalog-declared default when the option is enabled at no explicit scope ("none"), otherwise undefined (enabled at scope but no value provided).
+      let value;
+
+      if(isValueOption(catalog, expandedName) && resolved.enabled) {
+
+        if(resolved.optionValue !== undefined) {
+
+          value = resolved.optionValue;
+        } else if(resolved.scope === "none") {
+
+          value = catalog.valueOptions[expandedName.toLowerCase()]?.toString();
+        }
+      }
+
+      counts.total++;
+
+      if(optionIsGrouped) {
+
+        counts.grouped++;
+      }
+
+      if(optionIsModified) {
+
+        counts.modified++;
+      }
+
+      if(visible) {
+
+        counts.visible++;
+        categoryHasVisible = true;
+      }
+
+      entries.push({
+
+        description: option.description,
+        enabled: resolved.enabled,
+        expandedName,
+        isGrouped: optionIsGrouped,
+        isModified: optionIsModified,
+        name: option.name,
+        option,
+        requiresParentBadge: visible && optionIsGrouped && !optionDependencyMet,
+        scope: resolved.scope,
+        value,
+        visible
+      });
+    }
+
+    if(entries.length === 0) {
+
+      continue;
+    }
+
+    categories.push({
+
+      category,
+      description: category.description,
+      entries,
+      hasVisible: categoryHasVisible,
+      name: category.name
+    });
+  }
+
+  return { categories, counts };
+};

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

@@ -0,0 +1,319 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/state.mjs: State shape, action vocabulary, and reducer for the feature options webUI.
+ */
+"use strict";
+
+import { applyClearOption, applySetOption, buildCatalogIndex } from "../featureOptions.js";
+
+/**
+ * State shape, action vocabulary, and reducer for the feature options webUI.
+ *
+ * This module is the SSOT for what state the UI carries and how that state transitions. Every dispatch lands here; every component reads from {@link FeatureOptionsState}
+ * 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
+ *     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).
+ *   - {@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.
+ *
+ * The action vocabulary names past-tense domain events. Each action below corresponds to a {@link reducer} case and to at least one effect or view subscriber.
+ * Names use a `domain:event` shape so they group naturally and read as natural language at dispatch sites.
+ *
+ *   - `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.
+ *   - `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.
+ *   - `options:reset` - every configured option dropped (reset to defaults).
+ *   - `model:reverted` - configuredOptions restored to the at-show() snapshot.
+ *   - `filter:changed` - search query and/or filter mode updated.
+ *   - `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.
+ *
+ * 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
+ * production where they manifest as missing UI updates.
+ *
+ * @module
+ */
+
+/**
+ * @typedef {Object} Controller
+ * @property {string} address - The network address of the controller.
+ * @property {string} name - The display name of the controller.
+ * @property {string} serialNumber - The unique serial number of the controller.
+ */
+
+/**
+ * @typedef {Object} Device
+ * @property {string} firmwareRevision - The firmware version of the device.
+ * @property {string} manufacturer - The manufacturer of the device.
+ * @property {string} model - The model identifier of the device.
+ * @property {string} name - The display name of the device.
+ * @property {string} serialNumber - The unique serial number of the device.
+ * @property {string} [sidebarGroup] - Optional grouping identifier for sidebar organization.
+ */
+
+/**
+ * @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 | 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."
+ */
+
+/**
+ * Catalog - The plugin-provided immutable configuration bundle. `CatalogIndex` from featureOptions.ts carries the catalog data and its derived indices; the
+ * `validators` field adds the webUI-specific predicates plugins supply for device-aware visibility. Both halves are set once at {@link model:loaded} and never
+ * change during a session; consumers can rely on reference stability for memoization.
+ *
+ * @typedef {Object} Catalog
+ * @property {readonly import("../featureOptions.js").FeatureCategoryEntry[]} categories
+ * @property {Readonly<Record<string, boolean>>} defaults
+ * @property {Readonly<Record<string, string>>} groupParents
+ * @property {Readonly<Record<string, readonly string[]>>} groups
+ * @property {Readonly<Record<string, readonly import("../featureOptions.js").FeatureOptionEntry[]>>} options
+ * @property {Readonly<Record<string, (value: string) => string>>} renderers
+ * @property {readonly string[]} sortedValueOptionNames
+ * @property {Validators} validators
+ * @property {Readonly<Record<string, number | string | undefined>>} valueOptions
+ */
+
+/**
+ * Scope - The selection pointer through the global / controller / device hierarchy. Discriminated by `kind` so each variant carries exactly its required data
+ * and invalid combinations (a "device" view without a deviceId, a "controller" view without a controllerId) are unrepresentable.
+ *
+ * The `device` variant carries `controllerId: string | null` because two device-view shapes exist: a device under a controller (controllerId is the parent
+ * controller's serial) and a device in device-only mode (controllerId is null because there is no controller). Splitting these into two further variants would
+ * over-fragment the type for a distinction that no consumer cares about - both render the same view.
+ *
+ * @typedef {{kind: "global"} | {kind: "controller", controllerId: string} | {kind: "device", controllerId: string | null, deviceId: string}} Scope
+ */
+
+/**
+ * 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.
+ *
+ * @typedef {{kind: "loading"} | {kind: "ready"} | {kind: "persisting", snapshot: readonly string[]} | {kind: "persist-error", error: Error}
+ *           | {kind: "connection-error", message: string}} LifecycleStatus
+ */
+
+/**
+ * FeatureOptionsState - The complete state shape. Every field has a defined purpose; every consumer reads from here. No view, effect, or component holds parallel
+ * state that could drift from this.
+ *
+ * @typedef {Object} FeatureOptionsState
+ * @property {Catalog} catalog - Plugin-provided immutable configuration: catalog index + validators.
+ * @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 {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
+ *                                                                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.
+ * @property {"controller-based" | "device-only"} mode - Operating mode. Set once at model:loaded based on whether the plugin provided `getControllers`.
+ * @property {readonly string[]} persistedAnchor - The last-known-on-disk state. Updated on every successful persist; restored to configuredOptions on a final
+ *                                                  persist failure (memory then matches disk).
+ * @property {Scope} scope - Selection pointer (DU).
+ * @property {LifecycleStatus} status - Page-state pointer (DU).
+ */
+
+// The placeholder catalog used during the "loading" status, before {@link model:loaded} has fired with the real one. Built from empty inputs so every selector
+// works against it without null guards; selectors that iterate categories or options produce empty results, which matches the "nothing to render yet" semantics.
+// validOption and validOptionCategory default to permissive (return true) so any speculative iteration during loading does not accidentally hide a category
+// or option; isController defaults to false since it plays no role in visibility.
+const EMPTY_CATALOG = {
+
+  ...buildCatalogIndex([], {}),
+
+  validators: {
+
+    isController: () => false,
+    validOption: () => true,
+    validOptionCategory: () => true
+  }
+};
+
+/**
+ * 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.
+ *
+ * No constructor parameters because the variant data (mode, validators, configuredOptions) is not yet available at store-construction time - it arrives over the
+ * wire from Homebridge's `getPluginConfig` + `request("/getOptions")` plus the plugin's optional `getControllers`. The orchestrator dispatches `model:loaded` once
+ * those resolve.
+ *
+ * @returns {FeatureOptionsState} A fresh initial-state object.
+ */
+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.
+  const empty = [];
+
+  return {
+
+    catalog: EMPTY_CATALOG,
+    configuredOptions: empty,
+    controllers: [],
+    devices: [],
+    devicesControllerId: null,
+    filter: { mode: "all", query: "" },
+    initialOptions: empty,
+    mode: "device-only",
+    persistedAnchor: empty,
+    scope: { kind: "global" },
+    status: { kind: "loading" }
+  };
+};
+
+/**
+ * The pure reducer. Applies an action to the current state and returns the new state. Structural sharing: unchanged slices retain their reference across the
+ * transition, so memoized selectors that depend on those slices return cached results.
+ *
+ * Unknown action types throw - silently ignoring them would let typo bugs escape into production where they manifest as missing UI updates. Every legitimate
+ * action lives below; an unknown type is a bug at the dispatch site, surfaced loudly.
+ *
+ * @param {FeatureOptionsState} state - The current state.
+ * @param {{type: string}} action - The action to apply. Discriminated by `type`; the switch below enumerates every legitimate value.
+ * @returns {FeatureOptionsState} The new state.
+ */
+export const reducer = (state, action) => {
+
+  switch(action.type) {
+
+    case "model:loaded": {
+
+      // First load: catalog, configuredOptions, mode, controllers populated. The persistence anchor seeds from the just-loaded options (pre-mutation the loaded array
+      // IS the disk state). The initial snapshot - the revert target - takes `action.initialOptions` if the dispatcher supplied it (orchestrator re-shows that
+      // detected set-equal options carry the original snapshot forward), otherwise falls back to the loaded options. Status transitions to ready.
+      return {
+
+        ...state,
+        catalog: action.catalog,
+        configuredOptions: action.configuredOptions,
+        controllers: action.controllers,
+        initialOptions: action.initialOptions ?? action.configuredOptions,
+        mode: action.mode,
+        persistedAnchor: action.configuredOptions,
+        status: { kind: "ready" }
+      };
+    }
+
+    case "controllers:loaded": {
+
+      // Controllers list refreshed without re-loading the model - a controllers-only refresh hook that no code currently dispatches (nav rebuilds the sidebar on it).
+      return { ...state, controllers: action.controllers };
+    }
+
+    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 };
+    }
+
+    case "scope:changed": {
+
+      // Replace the selection pointer wholesale. The DU is atomic - controllerId, deviceId, and kind all move together so subscribers never observe a partial
+      // selection state.
+      return { ...state, scope: action.scope };
+    }
+
+    case "option:set": {
+
+      // Compute the new configuredOptions via the pure transform. The transform returns a fresh array so reference equality on configuredOptions detects the
+      // change; the catalog reference is unchanged so selectors that depend only on the catalog continue to hit their caches.
+      return {
+
+        ...state,
+        configuredOptions: applySetOption({ args: action.args, catalog: state.catalog, configuredOptions: state.configuredOptions })
+      };
+    }
+
+    case "option:cleared": {
+
+      // The pure transform returns the input reference unchanged when nothing matched, so the reducer's `...state, configuredOptions: ...` spread also yields a
+      // state value whose configuredOptions reference equals the prior one. Subscribers reading reference equality see a no-op and skip recomputation.
+      return {
+
+        ...state,
+        configuredOptions: applyClearOption({ args: action.args, catalog: state.catalog, configuredOptions: state.configuredOptions })
+      };
+    }
+
+    case "options:reset": {
+
+      // Wipe every configured option. Fresh empty array so reference equality reflects the change. The initial snapshot and the anchor are untouched - revert
+      // and persist failure still have their respective rollback targets.
+      return { ...state, configuredOptions: [] };
+    }
+
+    case "model:reverted": {
+
+      // Restore configuredOptions to the at-show() snapshot. The snapshot reference is reused as-is - subsequent option:set / option:cleared mutations will fork
+      // it via the pure transforms, so the snapshot stays stable for the next revert.
+      return { ...state, configuredOptions: state.initialOptions };
+    }
+
+    case "filter:changed": {
+
+      // Partial update: action fields override; absent fields preserve. The action shape carries optional `query` and `mode` so callers can update one axis without
+      // touching the other. A new filter object is allocated so reference equality reflects the change.
+      return {
+
+        ...state,
+        filter: {
+
+          mode: action.mode ?? state.filter.mode,
+          query: action.query ?? state.filter.query
+        }
+      };
+    }
+
+    case "persist:started": {
+
+      // Status transitions to persisting, carrying the snapshot that's now in flight. Subscribers (status bar) can show a "saving" affordance and read the snapshot
+      // when they need to know what's pending.
+      return { ...state, status: { kind: "persisting", snapshot: action.snapshot } };
+    }
+
+    case "persist:succeeded": {
+
+      // The in-flight snapshot landed on disk. Promote it to the anchor so any subsequent rollback (after a future failure) restores to this state, and return
+      // status to ready.
+      return { ...state, persistedAnchor: action.snapshot, status: { kind: "ready" } };
+    }
+
+    case "persist:failed": {
+
+      // Final-attempt failure with no superseding mutation. Roll configuredOptions back to the last-known disk state so memory matches disk, and transition status
+      // to persist-error so subscribers (status bar / toast emitter) can surface the failure.
+      return { ...state, configuredOptions: state.persistedAnchor, status: { error: action.error, kind: "persist-error" } };
+    }
+
+    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 } };
+    }
+
+    default: {
+
+      // Unknown action: bug at the dispatch site. Surface loudly rather than silently ignore - the user's reported "UI didn't update" stack trace is more useful
+      // than a months-later realization that a typo was eating dispatches.
+      throw new Error("FeatureOptionsState.reducer: unknown action type \"" + action.type + "\".");
+    }
+  }
+};