homebridge-plugin-utils 1.34.0 → 2.0.0

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

@@ -0,0 +1,181 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/store.mjs: Reactive state primitive for the feature options webUI.
+ */
+"use strict";
+
+// Capture the platform's CustomEvent constructor at module load. `extends EventTarget` below resolves at the same moment - both come from the same DOM
+// implementation, so the dispatched event matches the EventTarget's expected event family. Without this capture, a test environment that swaps `globalThis.CustomEvent`
+// to a different implementation after module load would dispatch events that the originally-resolved EventTarget rejects (silently or throwing); pinning both at
+// the same load timestamp keeps the implementation family coherent.
+const ModuleCustomEvent = CustomEvent;
+
+/**
+ * FeatureOptionsStore - The event-emitting state container at the heart of the feature options webUI.
+ *
+ * Architectural contract:
+ *
+ *   - **One source of truth.** A single state object replaces ad-hoc cross-component synchronization. Components do not hold parallel state; they subscribe to the
+ *     store and re-derive their view from {@link state} on dispatch.
+ *   - **Unidirectional flow.** Mutations enter through {@link dispatch}, which feeds the action to the pure reducer and atomically replaces the state. The store
+ *     then fires a {@link CustomEvent} naming the action's type, with the full action as `event.detail` so subscribers receive the payload without reaching back
+ *     into the store for "what changed."
+ *   - **Platform-native subscription.** The class extends {@link EventTarget} so subscribers register via the standard `addEventListener({ signal })` idiom -
+ *     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
+ *     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
+ * surface. The store is the platform-shaped wire between them.
+ */
+export class FeatureOptionsStore extends EventTarget {
+
+  #reducer;
+  #state;
+
+  /**
+   * Create a new store seeded with initial state and a reducer.
+   *
+   * @param {Object} args
+   * @param {Object} args.initialState - The starting state. Treated as the first value of the immutable state sequence; subsequent values come from the reducer.
+   * @param {(state: Object, action: { type: string }) => Object} args.reducer - Pure (state, action) => state function. Should be an exhaustive switch on
+   *                                                                              `action.type` so adding a new action type forces a corresponding reducer case.
+   */
+  constructor({ initialState, reducer }) {
+
+    super();
+    this.#reducer = reducer;
+    this.#state = initialState;
+  }
+
+  /**
+   * Read the current state. Returned by reference - callers MUST treat the result as readonly. The reducer's structural-sharing contract guarantees that unchanged
+   * slices retain their reference across dispatches, so subscribers can use reference equality (`===`) to detect what changed without a deep comparison.
+   *
+   * @returns {Object} The current state.
+   */
+  get state() {
+
+    return this.#state;
+  }
+
+  /**
+   * Apply an action through the reducer and notify subscribers.
+   *
+   * Sequence:
+   *
+   *   1. The reducer is invoked with the current state and the action; its return value becomes the new state.
+   *   2. A {@link CustomEvent} named after `action.type` is dispatched on the store, with the full action as `event.detail`.
+   *
+   * The state replacement happens BEFORE the event dispatches, so subscribers reading `store.state` from inside their handler see the post-dispatch state. Reversing
+   * this order would force subscribers to either read from `event.detail` only (losing access to other state slices the dispatch did not touch) or to compute their
+   * view from stale state (a correctness hazard). The current order is the only one that satisfies "subscribers see consistent state every time they read."
+   *
+   * @param {{ type: string }} action - The action to dispatch. Must carry a string `type` field naming a past-tense domain event. Additional payload fields are
+   *                                    forwarded verbatim as `event.detail` to subscribers.
+   */
+  dispatch(action) {
+
+    this.#state = this.#reducer(this.#state, action);
+    this.dispatchEvent(new ModuleCustomEvent(action.type, { detail: action }));
+  }
+}
+
+/**
+ * Subscribe a function to a set of action types on a store, with automatic teardown.
+ *
+ * Two phases:
+ *
+ *   1. **Immediate run.** The function is invoked once synchronously at registration so the caller's initial view derives from the current state without waiting
+ *      for a dispatch. This eliminates the "render on mount AND on every event" boilerplate every subscriber would otherwise repeat. {@link fn} receives
+ *      `undefined` for the action argument at the immediate run - the marker for "no triggering action."
+ *   2. **Subscription.** The function is registered as a listener for every event type in `events`. Every subsequent {@link FeatureOptionsStore.dispatch} of a
+ *      listed type fires the function with the action as its argument (extracted from the {@link CustomEvent}'s `detail`). Cleanup is automatic: when the
+ *      supplied {@link AbortSignal} aborts, every registered listener is removed in one operation.
+ *
+ * A pre-aborted signal short-circuits the entire effect: neither the immediate run nor the subscription registration takes effect. This protects views that
+ * subscribed during a mount sequence from running against a torn-down DOM when an abort races the mount.
+ *
+ * The handler receives the action as its argument so subscribers that care about the dispatched payload can read it directly; subscribers that only need the
+ * post-mutation state ignore the argument and read `store.state` as usual. JavaScript's parameter semantics mean a handler declared as `() => void` silently
+ * ignores the action, so consumers pay no cost for the extra capability. Action-aware consumers declare `(action) => void` (or `(action) => { if(action) ... }`
+ * to gate on subscription-only logic) without needing a parallel API.
+ *
+ * @param {Object} args
+ * @param {readonly string[]} args.events - The action types this effect subscribes to.
+ * @param {(action?: { type: string }) => void} args.fn - The effect body. Runs once immediately with `action === undefined`, then on every dispatch of a listed
+ *                                                        action type with the dispatched action as its argument.
+ * @param {AbortSignal} args.signal - The lifecycle signal. Every listener registered by this effect is bound to this signal and cleaned up on abort.
+ * @param {FeatureOptionsStore} args.store - The store to subscribe against.
+ */
+export const effect = ({ events, fn, signal, store }) => {
+
+  // Respect a pre-aborted signal. Without this short-circuit, a mount sequence that races against an abort can land the immediate-run pass on a torn-down DOM.
+  // The subscription registrations after this point would be no-ops anyway (addEventListener with an aborted signal silently skips), but the immediate-run pass
+  // can have side effects that need to be skipped.
+  if(signal.aborted) {
+
+    return;
+  }
+
+  fn(undefined);
+
+  // One wrapper closure shared across every listener registration extracts the action from the event's detail and hands it to the handler. Centralizing the
+  // extraction here means each handler sees the same "action or undefined" contract regardless of which event type triggered it, and the addEventListener
+  // registrations themselves stay symmetric.
+  const dispatch = (event) => fn(event.detail);
+
+  for(const type of events) {
+
+    store.addEventListener(type, dispatch, { signal });
+  }
+};
+
+/**
+ * Memoize a pure selector over a set of state slices.
+ *
+ * Pattern: the caller provides `compute(state)` (the derivation) and an array of `slices` (functions that pull cache-key inputs from state). On each call, the
+ * memoized selector re-runs the slice accessors and compares their results to the previous call's; if every slice returns the same reference (or primitive value)
+ * as before, the cached result is returned. Otherwise `compute` runs against the current state, and the new result is cached for next time.
+ *
+ * Reference equality is the cache key, which matches the structural-sharing contract the reducer follows: unchanged slices retain their reference across
+ * dispatches, so selectors that depend on them return cached results without recomputation. A selector that reads `state.scope` and `state.filter` is
+ * automatically cached across any dispatch that does not modify those slices, regardless of whether the dispatch touched some other unrelated slice.
+ *
+ * Single shared helper for every memoized selector. The alternative - hand-rolling closure-cached selectors at each site - duplicates the memoization shape and
+ * makes the cache key less discoverable. Using this helper means every memoized selector reads as "what does it compute" + "what does it depend on," with the
+ * machinery factored out.
+ *
+ * @param {Object} args
+ * @param {(state: Object) => unknown} args.compute - The pure derivation. Invoked when any slice's reference changes; the result is cached until the next change.
+ * @param {readonly ((state: Object) => unknown)[]} args.slices - The state-slice accessors. Their return values are compared by `===` against the previous call's.
+ *                                                                 Order matters - the comparison is positional.
+ * @returns {(state: Object) => unknown} The memoized selector. Call it with the current state to read the derivation.
+ */
+export const memoize = ({ compute, slices }) => {
+
+  // The cache's "no value yet" state is encoded by `lastKeys === null`. Once the selector has run once, lastKeys is a non-null array (possibly empty when the
+  // selector takes no slices) and the comparison branch can proceed unconditionally. Two closure variables instead of a wrapper object - one fewer level of
+  // indirection on every cache check, which matters because cache-hit is the hot path for every selector called per dispatch.
+  let lastKeys = null;
+  let lastResult;
+
+  return (state) => {
+
+    const keys = slices.map((slice) => slice(state));
+
+    // Cache hit when every slice returns a value identical to its prior return. `Array.every` short-circuits on the first mismatch so the comparison cost is
+    // bounded by "how many slices match before one diverges," not by the slice count.
+    if(lastKeys && (keys.length === lastKeys.length) && keys.every((k, i) => k === lastKeys[i])) {
+
+      return lastResult;
+    }
+
+    lastKeys = keys;
+    lastResult = compute(state);
+
+    return lastResult;
+  };
+};

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

@@ -0,0 +1,200 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/utils.mjs: Shared utilities for the feature options webUI components.
+ */
+"use strict";
+
+/**
+ * Sleep for the given duration and resolve, or reject early when the supplied signal aborts.
+ *
+ * This is the browser-side counterpart to the server-side `onAbort` disposable pattern: every lifecycle-bound async pause in the webUI funnels through one
+ * helper, so listener cleanup, pre-aborted fast-path semantics, and rejection-reason propagation live in exactly one place. Callers express "wait, but only while
+ * this view is alive" by composing a delay with their lifecycle signal - the rest is mechanical.
+ *
+ * @param {number} ms - Duration to sleep, in milliseconds.
+ * @param {AbortSignal} [signal] - Optional lifecycle signal. When provided, an abort cancels the timer and rejects the promise with the signal's reason. A signal
+ *                                 that is already aborted at call time rejects synchronously on the next microtask without scheduling a timer.
+ * @returns {Promise<void>} Resolves after `ms` milliseconds, or rejects with `signal.reason` on abort.
+ */
+export function delay(ms, signal) {
+
+  if(signal?.aborted) {
+
+    return Promise.reject(signal.reason);
+  }
+
+  const { promise, resolve, reject } = Promise.withResolvers();
+
+  // `onAbort` references `timer` lexically; the const is initialized before any addEventListener fires it, so the TDZ is never touched at call time. Both
+  // closures only run later, after both consts are initialized, so `onAbort` is declared first purely for readability - either declaration order is safe.
+  const onAbort = () => {
+
+    clearTimeout(timer);
+    reject(signal.reason);
+  };
+
+  const timer = setTimeout(() => {
+
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+
+  signal?.addEventListener("abort", onAbort, { once: true });
+
+  return promise;
+}
+
+/**
+ * Create a DOM element with optional properties and children.
+ *
+ * This utility is shared across all feature options components. It reduces the verbosity of DOM manipulation by handling common patterns like setting classes,
+ * styles, and adding children in a functional style.
+ *
+ * @param {string} tag - The HTML tag name to create.
+ * @param {Object} [props={}] - Properties to set on the element.
+ * @param {string|string[]|Array} [props.classList] - CSS classes to add.
+ * @param {Object} [props.style] - Inline styles to apply.
+ * @param {Array<string|Node>} [children=[]] - Child nodes or text content.
+ * @returns {HTMLElement} The created DOM element.
+ */
+export function createElement(tag, props = {}, children = []) {
+
+  const element = document.createElement(tag);
+
+  // Destructure classList and style off the props object so the remaining `attrs` can be iterated as plain DOM property/attribute assignments. We destructure
+  // (rather than mutate) so callers can safely reuse the same props record across multiple createElement invocations.
+  const { classList, style, ...attrs } = props;
+
+  if(classList) {
+
+    const classes = Array.isArray(classList) ? classList : classList.split(" ");
+
+    element.classList.add(...classes);
+  }
+
+  if(style) {
+
+    Object.assign(element.style, style);
+  }
+
+  for(const [ key, value ] of Object.entries(attrs)) {
+
+    // Use setAttribute for two cases that don't reflect via property assignment:
+    //   1. Dashed attributes (`data-*`, `aria-*`, etc.) - no corresponding JS property to set.
+    //   2. JS reserved words mapped to non-obvious DOM property names. `for` is the canonical case: setting `label.for = id` creates a JS expando property
+    //      with no effect on the HTML attribute (the reflective property is `htmlFor`, not `for`). Without this branch, `<label for="...">` ends up without
+    //      its `for` attribute and native label-for click-to-toggle silently doesn't work. Other reserved-word collisions (`class` -> className) are handled
+    //      via the `classList` destructuring above; `for` is the only remaining case the renderer relies on.
+    if(key.includes("-") || (key === "for")) {
+
+      element.setAttribute(key, value);
+    } else {
+
+      element[key] = value;
+    }
+  }
+
+  for(const child of children) {
+
+    element.appendChild((typeof child === "string") ? document.createTextNode(child) : child);
+  }
+
+  return element;
+}
+
+/**
+ * Capture the current expansion state of every category in the supplied container as a plain `{ [categoryName]: isCollapsed }` map. Symmetric counterpart to
+ * {@link applyCategoryStates}; both sit alongside {@link setCategoryExpanded} as the SSOT for category reads and writes, so the persistence layer can stay
+ * DOM-agnostic.
+ *
+ * Reads `details.open` rather than any JS-mirrored expand state - the `<details>` element's own `open` attribute is the SSOT for "is this category currently
+ * expanded?"
+ *
+ * @param {HTMLElement} configTable - Container holding category `<details>` elements (each `<details data-category="...">` whose `open` attribute marks it expanded).
+ * @returns {Object<string, boolean>} Map of category name to collapsed boolean.
+ */
+export function captureCategoryStates(configTable) {
+
+  const states = {};
+
+  for(const details of configTable.querySelectorAll("details[data-category]")) {
+
+    states[details.getAttribute("data-category")] = !details.open;
+  }
+
+  return states;
+}
+
+/**
+ * Apply a previously-captured `{ [categoryName]: isCollapsed }` map onto the matching category `<details>` elements in the supplied container. Categories absent
+ * from the map are left at their current state. Symmetric counterpart to {@link captureCategoryStates}; routes every write through {@link setCategoryExpanded}
+ * so each programmatic toggle fires the `toggle` event the orchestrator listens for (which materializes lazy rows on expand and coalesces post-toggle sync).
+ *
+ * @param {HTMLElement} configTable - Container holding category `<details>` elements to apply state to.
+ * @param {Object<string, boolean>} states - Map of category name to collapsed boolean (the shape returned by captureCategoryStates).
+ */
+export function applyCategoryStates(configTable, states) {
+
+  for(const details of configTable.querySelectorAll("details[data-category]")) {
+
+    const categoryName = details.getAttribute("data-category");
+
+    if(categoryName in states) {
+
+      setCategoryExpanded(details, !states[categoryName]);
+    }
+  }
+}
+
+/**
+ * Set the expansion state of a category. This is the single source of truth for programmatic category-state writes: it mutates `details.open`, which the browser
+ * propagates to the visible disclosure state (header arrow rotation via CSS keyed on `[open]`, content visibility via the native disclosure widget) and fires
+ * the `toggle` event the orchestrator's capture-phase delegated handler intercepts.
+ *
+ * Used by the search component for bulk expand/collapse and auto-expand during search, and by the orchestrator for restoring saved category states. User-driven
+ * toggles via summary click happen natively in the browser - no code path here.
+ *
+ * @param {HTMLDetailsElement} details - The category `<details>` element.
+ * @param {boolean} expanded - True to expand the category, false to collapse it.
+ */
+export function setCategoryExpanded(details, expanded) {
+
+  details.open = expanded;
+}
+
+/**
+ * Show a transient toast below the status bar (success styling by default; pass a variant for other alert types).
+ *
+ * The toast auto-dismisses after 3 seconds with a fade-out transition. Uses Bootstrap's alert component for consistent styling.
+ *
+ * @param {string} message - The bold message text to display.
+ * @param {string} [variant="alert-success"] - The Bootstrap alert variant class.
+ */
+export function showToast(message, variant = "alert-success") {
+
+  const statusBar = document.getElementById("featureStatusBar");
+
+  if(!statusBar) {
+
+    return;
+  }
+
+  // Construct the toast body as DOM nodes so the message string flows through textContent in <strong>, never as HTML. The dismiss button's static attributes are
+  // declared on the createElement props, including the `aria-label` and `data-bs-dismiss` attributes the helper routes to setAttribute.
+  const toast = createElement("div", { classList: "alert " + variant + " alert-dismissible fade show mt-2", role: "alert" }, [
+
+    createElement("strong", {}, [message]),
+    createElement("button", { "aria-label": "Close", classList: "btn-close", "data-bs-dismiss": "alert", type: "button" })
+  ]);
+
+  statusBar.insertAdjacentElement("afterend", toast);
+
+  // Auto-dismiss after 3 seconds. This keeps the UI clean while still providing sufficient time to read the message.
+  setTimeout(() => {
+
+    toast.classList.remove("show");
+
+    // Remove the node only after Bootstrap's `.fade` transition (150ms) has visually completed, so the toast fades out rather than vanishing abruptly.
+    setTimeout(() => toast.remove(), 150);
+  }, 3000);
+}

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

@@ -0,0 +1,152 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/views/connectionError.mjs: The connection-error state - error message + retry button + progress bar.
+ */
+"use strict";
+
+import { createElement, delay } from "../utils.mjs";
+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.
+ *
+ * Renders into the same `#headerInfo` container the priority-chain header uses. The two views coordinate via the `state.status` discriminator: 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`.
+ *   - 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.
+ *
+ * The retry button's click invokes the caller-supplied `onRetry` callback (typically the orchestrator's cleanup + show() sequence).
+ *
+ * @param {Object} args
+ * @param {() => Promise<void>} args.onRetry - Callback invoked when the retry button is clicked. The orchestrator passes its restart routine.
+ * @param {number} [args.retryDelayMs=5000] - Milliseconds before the retry button becomes enabled.
+ * @param {HTMLElement} args.root - The `#headerInfo` container.
+ * @param {AbortSignal} args.signal - Lifecycle signal.
+ * @param {import("../store.mjs").FeatureOptionsStore} args.store - The store.
+ */
+export const mountConnectionErrorView = ({ onRetry, retryDelayMs = 5000, root, signal, store }) => {
+
+  // One active retry-window controller at a time. Aborting the parent signal aborts it; transitioning out of the error state also aborts it so a partially-armed
+  // retry button does not linger after the user navigates away.
+  let retryAbort = null;
+
+  effect({
+
+    events: [ "connection:error", "model:loaded" ],
+    fn: () => {
+
+      const { status } = store.state;
+
+      // Tear down any prior retry window before either rendering a new one or yielding back to the header view.
+      retryAbort?.abort();
+      retryAbort = null;
+
+      if(status.kind !== "connection-error") {
+
+        return;
+      }
+
+      retryAbort = new AbortController();
+      renderError({ message: status.message, onRetry, retryDelayMs, retrySignal: retryAbort.signal, root });
+    },
+    signal,
+    store
+  });
+
+  // Cleanup on parent abort. The effect's signal handles its own teardown; this ensures the inner retry-window controller is also aborted if it is still active.
+  signal.addEventListener("abort", () => {
+
+    retryAbort?.abort();
+  }, { 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 }) => {
+
+  const errorBlock = createElement("div", {}, [
+
+    "Unable to connect to the controller.",
+    createElement("br"),
+    "Check the Settings tab to verify the controller details are correct.",
+    createElement("br"),
+    createElement("code", { classList: ["text-danger"] }, [message]),
+    createElement("br")
+  ]);
+
+  const retryButton = createElement("button", {
+
+    classList: [ "btn", "btn-warning", "btn-sm", "mt-3" ],
+    textContent: "↻ Retry",
+    type: "button"
+  });
+
+  retryButton.disabled = true;
+
+  const barWrap = createElement("div", {
+
+    classList: [ "progress", "mt-1", "w-100" ],
+    style: { height: "4px" }
+  }, [
+
+    createElement("div", {
+
+      classList: ["progress-bar"],
+      role: "progressbar",
+      style: { transition: "width " + retryDelayMs + "ms linear", width: "0%" }
+    })
+  ]);
+
+  const retryWrap = createElement("div", { classList: [ "d-inline-block", "w-auto" ] }, [ retryButton, barWrap ]);
+
+  errorBlock.appendChild(retryWrap);
+  root.replaceChildren(errorBlock);
+  root.style.display = "";
+
+  // Kick the progress bar animation on the next animation frame so the transition has a starting value to interpolate from.
+  window.requestAnimationFrame(() => {
+
+    const bar = barWrap.querySelector(".progress-bar");
+
+    if(bar) {
+
+      bar.style.width = "100%";
+    }
+  });
+
+  // Arm the retry window. The retry button enables after the delay and removes the progress bar; an abort cancels both.
+  void armRetry({ barWrap, onRetry, retryButton, retryDelayMs, retrySignal });
+};
+
+// Arm the retry button after the configured delay. The button enables, the progress bar removes itself, and a click handler is wired up that invokes the supplied
+// onRetry callback. An abort mid-window cancels both the delay and any wired click handler.
+const armRetry = async ({ barWrap, onRetry, retryButton, retryDelayMs, retrySignal }) => {
+
+  try {
+
+    await delay(retryDelayMs, retrySignal);
+  } catch {
+
+    // Retry window was aborted before completion - either by a state transition out of connection-error or by the parent lifecycle signal. Nothing to clean up;
+    // the DOM detaches with the surrounding view.
+    return;
+  }
+
+  retryButton.disabled = false;
+  barWrap.remove();
+
+  retryButton.addEventListener("click", () => {
+
+    retryButton.disabled = true;
+    retryButton.textContent = "Retrying...";
+    void onRetry();
+  }, { once: true, signal: retrySignal });
+};

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

@@ -0,0 +1,80 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/views/deviceInfo.mjs: The device-stats panel in the sidebar.
+ */
+"use strict";
+
+import { createElement } from "../utils.mjs";
+import { effect } from "../store.mjs";
+import { selectedDevice } from "../selectors.mjs";
+
+/**
+ * Mount the device-info view.
+ *
+ * Re-renders on every scope change so the stats panel reflects the currently-selected device. The view delegates the actual stats rendering to a caller-supplied
+ * `infoPanel` callback - plugins override this to surface plugin-specific device metadata (firmware version, model, status indicators). When no override is
+ * supplied, the default callback ({@link defaultInfoPanel}) renders a four-column grid of firmware / serial / model / manufacturer.
+ *
+ * The container is shown when any device is in scope (controller-as-device or regular device) and cleared when the scope is global (no specific device to show
+ * stats for - the global view aggregates options across every device).
+ *
+ * @param {Object} args
+ * @param {((root: HTMLElement, device: import("../state.mjs").Device | undefined) => void) | undefined} args.infoPanel - Optional plugin-provided renderer. When
+ *                                                                                                                          omitted, {@link defaultInfoPanel} is used.
+ * @param {HTMLElement} args.root - The `#deviceStatsContainer` element.
+ * @param {AbortSignal} args.signal - Lifecycle signal.
+ * @param {import("../store.mjs").FeatureOptionsStore} args.store - The store.
+ */
+export const mountDeviceInfoView = ({ infoPanel = defaultInfoPanel, root, signal, store }) => {
+
+  const render = (panelFn) => (panelFn ?? defaultInfoPanel)(root, selectedDevice(store.state));
+
+  effect({
+
+    events: [ "scope:changed", "devices:loaded", "model:loaded" ],
+    fn: () => {
+
+      // 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);
+    },
+    signal,
+    store
+  });
+};
+
+/**
+ * Default device-info renderer. Renders a labeled grid of device identity fields (firmware / serial number / model / manufacturer), each cell carrying a small
+ * uppercase label above the value. Clears the container entirely when no device is in scope.
+ *
+ * Untrusted device fields flow through `textContent` (via createElement's text-node path) so any markup-shaped fragments surface as literal text rather than
+ * rendered HTML. Container is rebuilt on every call - replaceChildren handles both the initial render and any subsequent device switch.
+ *
+ * @param {HTMLElement} root - The container element.
+ * @param {import("../state.mjs").Device | undefined} device - The device to render stats for, or undefined for global view.
+ */
+export const defaultInfoPanel = (root, device) => {
+
+  if(!device) {
+
+    root.textContent = "";
+
+    return;
+  }
+
+  const stats = [
+
+    [ "Firmware", device.firmwareRevision ?? "N/A" ],
+    [ "Serial Number", device.serialNumber ?? "N/A" ],
+    [ "Model", device.model ?? "N/A" ],
+    [ "Manufacturer", device.manufacturer ?? "N/A" ]
+  ];
+
+  const grid = createElement("div", { classList: ["device-stats-grid"] }, stats.map(([ label, value ]) => createElement("div", { classList: ["stat-item"] }, [
+
+    createElement("span", { classList: ["stat-label"] }, [label]),
+    createElement("span", { classList: ["stat-value"] }, [value])
+  ])));
+
+  root.replaceChildren(grid);
+};