homebridge-plugin-utils 1.34.0 → 2.0.0

package/dist/ui/webUi-featureOptions/effects/persist.mjs

@@ -0,0 +1,226 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/effects/persist.mjs: The persistence effect for the feature options webUI.
+ */
+"use strict";
+
+import { delay } from "../utils.mjs";
+import { effect } from "../store.mjs";
+
+/**
+ * Debounce window for coalescing rapid mutations before writing to disk. 300ms sits below the instant-feel ceiling - a single click feels immediate from the user's
+ * perspective (a 300ms persist completes invisibly while the next click is being decided) - yet above the burst-coalescing floor, so a rapid sequence of mutations
+ * (the user dragging a slider, batching reset/revert through multiple controllers) collapses into a single write rather than one write per mutation.
+ */
+const DEBOUNCE_MS = 300;
+
+/**
+ * Register the persistence effect on a store.
+ *
+ * Coalesces, serializes, and rolls back option persistence:
+ *
+ *   - **Coalescing**: every mutation that changes `configuredOptions` enters this effect through a single dirty flag (`pending`). The drain loop reads the flag at
+ *     each iteration and re-enters when it is set, so rapid mutations collapse into one persist of the latest state. The debounce on top of the drain absorbs
+ *     burst-mutation patterns (drag/keystroke) without queueing multiple writes.
+ *   - **Serialization**: a single drain promise (`inFlight`) is held while a persist call is in flight. Concurrent mutations only set `pending = true`; the drain
+ *     loop picks up the latest state at its next iteration. No two persist calls can be in flight against the host at the same time.
+ *   - **Rollback**: a final-iteration failure (no superseding mutation) dispatches `persist:failed`, which the reducer translates into restoring
+ *     `configuredOptions` to the last-known-good `persistedAnchor`. Intermediate-iteration failures (a mutation rescued the user's intent) are swallowed because
+ *     the next iteration will retry with the newer state; the user's most recent action is what matters.
+ *
+ * The dispatch sequence per iteration:
+ *
+ *   1. `persist:started` with the snapshot being written. Status transitions to `persisting`; the status bar can show a "saving" affordance.
+ *   2. `session.commit({ options })` is awaited - the session merges the options onto its primary entry, preserves siblings, writes to the host, and advances its
+ *      held reference only on success.
+ *   3. Success: `persist:succeeded` with the snapshot. Status returns to `ready`; the anchor advances to this snapshot.
+ *   4. Failure with no superseding mutation: `persist:failed` with the error. Status transitions to `persist-error`; the reducer rolls `configuredOptions` back to
+ *      the anchor.
+ *   5. Failure with a superseding mutation: the error is swallowed; the loop continues with the newer state.
+ *
+ * The effect is registered with the page-level signal. Aborting the signal cleanly tears down the listener; an in-flight `updatePluginConfig` call cannot itself
+ * be aborted (the Homebridge bridge does not accept an `AbortSignal`), but the drain checks `signal.aborted` after every await and bails before dispatching any
+ * post-call action against a torn-down view.
+ *
+ * Returns a `{ flush }` handle. The page calls `flush()` at its navigate-away chokepoint (and best-effort on browser background/close) BEFORE aborting the signal,
+ * so a debounced-but-unwritten edit reaches disk instead of being dropped when the signal aborts. `flush()` drives the same single-writer drain to completion - it
+ * skips the debounce wait, never starts a parallel commit, and is a no-op when the store is already clean.
+ *
+ * @param {Object} args
+ * @param {{toast?: {error?: (message: string, id: string) => void}}} args.host - The Homebridge bridge, used only for the failure toast channel.
+ * @param {{commit: (patch: Object) => Promise<void>}} args.session - The config session; option saves persist through its single write seam.
+ * @param {AbortSignal} args.signal - The lifecycle signal. Aborting tears down the effect.
+ * @param {import("../store.mjs").FeatureOptionsStore} args.store - The store the effect subscribes against.
+ * @returns {{flush: () => Promise<void>}} A handle whose `flush()` drains any pending edit to disk now; called at the page's navigate-away / browser-exit edges.
+ */
+export const registerPersistEffect = ({ host, session, signal, store }) => {
+
+  // The drain-state variables below encode the irreducible coordination this pattern requires:
+  //
+  //   - `inFlight`: the in-flight drain promise. When non-null, the drain loop is active; subsequent mutations only set `pending` and return.
+  //   - `pending`: the dirty flag. Set by every subscribed mutation; cleared by the drain loop at the top of each iteration. Setting it during an in-flight persist
+  //     is the signal "your current snapshot is already stale; iterate again with the newer state."
+  //   - `debounceAbort`: the abort controller for the current debounce window. Every new mutation aborts the prior debounce so the timer always restarts from zero
+  //     on the latest mutation - the burst-mutation case (drag/keystroke) collapses to one debounced fire after the burst ends.
+  //   - `flushing`: set by flush() to drive the drain to completion NOW (skipping the debounce wait) when the page is navigating away. It keeps the loop running even
+  //     once `pending` has been consumed, so an edit made within the debounce window is written before teardown rather than dropped. Reset in every drain's `finally`
+  //     so it never outlives the drain it belongs to - the set-once-never-cleared leak this flag would otherwise introduce.
+  let debounceAbort = null;
+  let flushing = false;
+  let inFlight = null;
+  let pending = false;
+
+  const drain = async () => {
+
+    while((pending || flushing) && !signal.aborted) {
+
+      pending = false;
+
+      // The debounce is the burst-coalescing wait, but on the flush path (navigating away) we skip it: the edit must reach disk before teardown, so we go straight to
+      // the snapshot. In the normal path we restart the debounce on the latest mutation as before.
+      if(!flushing) {
+
+        debounceAbort?.abort();
+        debounceAbort = new AbortController();
+
+        try {
+
+          // The debounce itself is the loop's intentional serialization point - each iteration must wait the debounce window before sampling state again. Same
+          // exception applies as the persist call below: this await is the point.
+          // eslint-disable-next-line no-await-in-loop
+          await delay(DEBOUNCE_MS, AbortSignal.any([ debounceAbort.signal, signal ]));
+        } catch {
+
+          // Debounce was aborted. If the page signal aborted, bail entirely. Otherwise the abort was a new mutation arriving during the debounce window - continue
+          // the loop and the next iteration starts a fresh debounce.
+          if(signal.aborted) {
+
+            return;
+          }
+
+          continue;
+        }
+      }
+
+      // In-loop dirty check. The effect-fn dirty check below does NOT gate the flush path (flush() bypasses the fn and starts the drain directly), so the drain must
+      // re-test here: once a just-committed edit advances `persistedAnchor` to match `configuredOptions`, there is nothing left to write, and we break rather than
+      // looping again on a now-clean store. This also skips a redundant write when an edit was reverted back to the anchor within the debounce window.
+      if(store.state.configuredOptions === store.state.persistedAnchor) {
+
+        break;
+      }
+
+      // Capture the configuredOptions reference (not a spread copy). Reference preservation matters: when the persist succeeds with no superseding mutation,
+      // `persistedAnchor` becomes this same reference, so the next `pending` check at the effect's fn sees `configuredOptions === persistedAnchor` and skips.
+      const snapshot = store.state.configuredOptions;
+
+      store.dispatch({ snapshot, type: "persist:started" });
+
+      try {
+
+        // Sequential awaits are the point: the drain serializes persists so concurrent mutations cannot race on disk. The eslint rule's concern (parallelizing
+        // independent work) does not apply - each iteration's persist is the only legitimate I/O the drain should be running at any moment. The session owns the
+        // payload shape (primary entry + siblings) and the write; we hand it only the options delta.
+        // eslint-disable-next-line no-await-in-loop
+        await session.commit({ options: snapshot });
+
+        if(signal.aborted) {
+
+          return;
+        }
+
+        store.dispatch({ snapshot, type: "persist:succeeded" });
+      } catch(error) {
+
+        // A mutation arrived during the persist call - swallow the error and let the next iteration retry with the newer state. The user's most recent intent is
+        // what matters; an intermediate failure that the next iteration rescues need not surface to the user.
+        if(pending) {
+
+          continue;
+        }
+
+        if(signal.aborted) {
+
+          return;
+        }
+
+        store.dispatch({ error, type: "persist:failed" });
+
+        // Surface the failure via the host's toast channel so the user sees an actionable indication that their last edit did not reach disk. The single
+        // toast-emission seam keeps the user-facing notification policy in one place; effects elsewhere that dispatch persist:failed have the same path
+        // available through this effect's subscription.
+        host.toast?.error?.(error?.message ?? String(error), "config-persist");
+
+        return;
+      }
+    }
+  };
+
+  effect({
+
+    events: [ "option:set", "option:cleared", "options:reset", "model:reverted" ],
+    fn: () => {
+
+      // Reference-equality dirty check: when configuredOptions matches the anchor, there is nothing new to persist. Handles both the registration-time immediate
+      // call (initial state shares one empty-array reference across the three options-array fields) and any genuine no-op mutation that produced the same reference
+      // (e.g., an option:cleared against an option that did not exist - applyClearOption returns the input reference unchanged, so the reducer's spread preserves
+      // configuredOptions).
+      if(store.state.configuredOptions === store.state.persistedAnchor) {
+
+        return;
+      }
+
+      pending = true;
+
+      if(inFlight) {
+
+        return;
+      }
+
+      // Single-writer drain start-site (mutation path). The macrotask-ordering invariant the serialization rests on: every subscribed store mutation
+      // (option:set / option:cleared / options:reset / model:reverted) and every flush() caller (hide() / the visibilitychange handler) originates from a DOM-event
+      // macrotask, so none can preempt the queued `inFlight.finally` microtask and strand a `pending` edit in the gap between the drain returning and its `finally`
+      // clearing `inFlight`. (Forward-safety: if a future caller ever dispatches one of those subscribed actions from a microtask continuation, this invariant
+      // must be re-checked.) Reset `flushing` here too so it never outlives the drain it belongs to.
+      inFlight = drain().finally(() => {
+
+        inFlight = null;
+        flushing = false;
+      });
+    },
+    signal,
+    store
+  });
+
+  // Drain any pending-but-unwritten edit to disk NOW, used by the page's navigate-away chokepoint (hide()) and the best-effort browser-exit handler. flush() drives
+  // the drain to completion by setting `flushing` (which keeps the loop running past the debounce wait) and aborting the in-flight debounce so the current iteration
+  // proceeds straight to the write. It preserves single-writer serialization: it starts a NEW drain only when none is in flight; when a drain is already running it
+  // merely nudges it (set `flushing`, abort the debounce) and awaits the same promise - never a parallel commit. When the store is already clean (nothing dirty), it
+  // starts no drain and resets `flushing` immediately, so a flush() on a clean store cannot leak `flushing = true` into the next mutation's debounce decision.
+  const flush = async () => {
+
+    flushing = true;
+
+    debounceAbort?.abort();
+
+    if(!inFlight) {
+
+      if(store.state.configuredOptions === store.state.persistedAnchor) {
+
+        flushing = false;
+
+        return;
+      }
+
+      inFlight = drain().finally(() => {
+
+        inFlight = null;
+        flushing = false;
+      });
+    }
+
+    await inFlight;
+  };
+
+  return { flush };
+};

package/dist/ui/webUi-featureOptions/effects/theme.mjs

@@ -0,0 +1,398 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/effects/theme.mjs: Theme detection, stylesheet adoption, dark-mode toggling, and Bootstrap accent probing for the feature options webUI.
+ */
+"use strict";
+
+import { delay } from "../utils.mjs";
+
+/**
+ * Register the theme effect. Adopts the layout/behavior stylesheet, applies color-scheme + dark-mode class from the Homebridge lighting-mode setting, listens for
+ * `prefers-color-scheme` changes, and probes Bootstrap's `.btn-primary` to enhance the accent tokens.
+ *
+ * Cleanup is automatic via the AbortSignal: aborting releases the stylesheet from the document, clears the `color-scheme`, `.fo-dark` class, and accent-token inline
+ * overrides the effect wrote on `:root` (so it leaves no trace on a shared document), removes the matchMedia listener (via `{signal}` on addEventListener), and
+ * short-circuits the in-progress Bootstrap probe at the next await checkpoint.
+ *
+ * The function returns once the synchronous portion completes (stylesheet adopted, color-scheme applied, matchMedia listener registered). The Bootstrap accent
+ * probe runs in the background - the caller's `show()` pipeline is not blocked on probe completion. Until the probe resolves, the tokens' declared `AccentColor` /
+ * `AccentColorText` defaults remain in effect, so the user sees a sensible accent immediately rather than waiting up to `probe.timeoutMs` for Bootstrap to load.
+ *
+ * @param {Object} args
+ * @param {{userCurrentLightingMode: () => Promise<string>}} args.host - The Homebridge bridge (or a test stub matching that surface). The lighting mode is normally
+ *        "light" or "dark"; any unrecognized value is tolerated and treated as a no-op (no color scheme is applied).
+ * @param {AbortSignal} args.signal - Lifecycle signal. Aborting tears down every listener and the background probe.
+ * @param {Object} [args.probe] - Optional probe overrides.
+ * @param {number} [args.probe.timeoutMs=2000] - Maximum time, in milliseconds, to poll for Bootstrap's stylesheet. Override to `0` in tests to skip the probe.
+ * @param {number} [args.probe.intervalMs=20] - Poll interval, in milliseconds.
+ * @returns {Promise<void>} Resolves when the synchronous setup is complete (after color-scheme is applied and the matchMedia listener is registered). Does NOT wait
+ *                          for the Bootstrap probe to complete.
+ */
+export const registerThemeEffect = async ({ host, probe: { intervalMs = 20, timeoutMs = 2000 } = {}, signal }) => {
+
+  if(signal.aborted) {
+
+    return;
+  }
+
+  // Build & adopt the stylesheet immediately. The user perceives the layout the moment this resolves, with the fallback accent color in effect via the CSS
+  // custom-property cascade. The stylesheet content is mode-independent (`:root.fo-dark` selectors resolve dynamically based on the class), so it does not need
+  // re-emission when the theme mode changes.
+  const stylesheet = new CSSStyleSheet();
+
+  stylesheet.replaceSync(buildThemeCss());
+  document.adoptedStyleSheets = [ ...document.adoptedStyleSheets, stylesheet ];
+
+  signal.addEventListener("abort", () => {
+
+    // Restore the document to its pre-effect state, symmetric with every mutation the effect made to it: drop the adopted stylesheet, then the `color-scheme` and
+    // `.fo-dark` class that applyColorScheme set on `:root` and the accent-token inline overrides the Bootstrap probe wrote there. The `color-scheme` removal is the
+    // load-bearing one - it is a native property, so a leftover `dark` value would tint default form-control and scrollbar rendering on whatever content occupies the
+    // document after teardown (in a multi-page host, a sibling tab). The class and token overrides are inert once the stylesheet that reads them is gone, but are
+    // cleared too so the effect leaves no trace on `:root`.
+    document.adoptedStyleSheets = document.adoptedStyleSheets.filter((sheet) => sheet !== stylesheet);
+    document.documentElement.classList.remove("fo-dark");
+    document.documentElement.style.removeProperty("color-scheme");
+    document.documentElement.style.removeProperty("--fo-accent-bg");
+    document.documentElement.style.removeProperty("--fo-accent-fg");
+  }, { once: true });
+
+  // Apply the color-scheme from the current Homebridge setting. The lightweight portion of "apply theme" - no Bootstrap probe required; just sets the color-scheme
+  // property on :root and toggles the fo-dark class.
+  applyColorScheme(await host.userCurrentLightingMode());
+
+  if(signal.aborted) {
+
+    return;
+  }
+
+  // Listen for system / browser changes to the current dark-mode setting. Re-applying the color-scheme is cheap (no probe); the accent is then re-probed directly
+  // and immediately below - not through the deferred wait-for-Bootstrap path used at initial registration - since Bootstrap is assumed to already be loaded by
+  // the time a preference change can fire.
+  window.matchMedia("(prefers-color-scheme: dark)").addEventListener("change", async () => {
+
+    applyColorScheme(await host.userCurrentLightingMode());
+
+    if(signal.aborted) {
+
+      return;
+    }
+
+    probeAndApplyAccent();
+  }, { signal });
+
+  // Fire the Bootstrap probe in the background. Its job is to replace the fallback `AccentColor` keyword with Bootstrap's actual `.btn-primary` background color;
+  // until it resolves, the user sees the system accent. Void-discarded because the caller cannot meaningfully wait on it.
+  void runAccentProbe({ intervalMs, signal, timeoutMs });
+};
+
+// Set the color-scheme property on :root and toggle the fo-dark class. No accent probe - the accent custom properties are managed separately so the lightweight
+// color-scheme update does not pay the probe cost.
+const applyColorScheme = (mode) => {
+
+  if((mode !== "dark") && (mode !== "light")) {
+
+    return;
+  }
+
+  const current = document.documentElement.style.getPropertyValue("color-scheme");
+
+  if(current === mode) {
+
+    return;
+  }
+
+  document.documentElement.style.setProperty("color-scheme", mode);
+  document.documentElement.classList.toggle("fo-dark", mode === "dark");
+};
+
+// Background probe coordinator. Awaits Bootstrap readiness (or the timeout), then re-probes the accent color and writes the result into the :root custom properties.
+// A teardown that fires mid-probe short-circuits the post-await mutation; the stylesheet stays adopted (the signal-keyed listener handles that) and the fallback
+// accent remains in effect for the brief window before teardown completes.
+const runAccentProbe = async ({ intervalMs, signal, timeoutMs }) => {
+
+  await waitForBootstrap({ intervalMs, signal, timeoutMs });
+
+  if(signal.aborted) {
+
+    return;
+  }
+
+  probeAndApplyAccent();
+};
+
+// Probe the current Bootstrap `.btn-primary` accent color and write it into the `--fo-accent-*` tokens. The cascade propagates the change to every element
+// referencing the accent tokens or their `color-mix()` derivatives.
+//
+// Probed values are validated before being written. An empty string or fully-transparent value (which happens when Bootstrap's stylesheet has not applied to the
+// probe button yet) is rejected, leaving the tokens module's declared `AccentColor` default in effect. The opportunistic-override contract: the probe enhances
+// when it can, never degrades when it can not.
+const probeAndApplyAccent = () => {
+
+  const colors = probeAccentColor();
+
+  if(isValidAccentValue(colors.background)) {
+
+    document.documentElement.style.setProperty("--fo-accent-bg", colors.background);
+  }
+
+  if(isValidAccentValue(colors.text)) {
+
+    document.documentElement.style.setProperty("--fo-accent-fg", colors.text);
+  }
+};
+
+// Probe the current primary background and foreground from Bootstrap's .btn-primary. Returns an object with the two resolved color values; caller decides whether
+// to accept or reject each via {@link isValidAccentValue}.
+const probeAccentColor = () => {
+
+  const probeBtn = document.createElement("button");
+
+  probeBtn.className = "btn btn-primary";
+
+  // getComputedStyle resolves color and background-color independent of layout, so hiding the probe button via display: none does not affect the readout below.
+  probeBtn.style.display = "none";
+  document.body.appendChild(probeBtn);
+
+  const background = getComputedStyle(probeBtn).backgroundColor;
+  const text = getComputedStyle(probeBtn).color;
+
+  document.body.removeChild(probeBtn);
+
+  return { background, text };
+};
+
+// Whether a probed accent-color value is usable. Empty, fully transparent, or `unset`-equivalent values mean the probe ran before Bootstrap was ready; writing
+// them would replace the sensible `AccentColor` default with a useless value.
+const isValidAccentValue = (value) => {
+
+  if(!value) {
+
+    return false;
+  }
+
+  const normalized = value.replace(/\s+/g, "").toLowerCase();
+
+  return (normalized !== "transparent") && (normalized !== "rgba(0,0,0,0)");
+};
+
+// Wait for Bootstrap to finish loading in the DOM, or until the timeout expires. The composed signal (deadline + caller) is the single source of truth for the
+// loop and each per-iteration delay; one mechanism handles both timeout exhaustion and external cancellation. Emits a console.warn when the timeout expires
+// without detecting Bootstrap - a timeout-with-no-result is actionable info for plugin developers configuring their UI; without the warning the silent fallback
+// would leave them wondering why their accent color does not match Bootstrap.
+const waitForBootstrap = async ({ intervalMs, signal, timeoutMs }) => {
+
+  // Honor the documented `probe: { timeoutMs: 0 }` opt-out synchronously. A pre-aborted caller signal gets the same fast path.
+  if((timeoutMs <= 0) || signal.aborted) {
+
+    return false;
+  }
+
+  // .d-none is a Bootstrap-defined utility class, not a native CSS keyword; its display: none effect on this briefly-attached probe element only appears once
+  // Bootstrap's stylesheet has actually applied, making it a reliable readiness signal.
+  const isBootstrapApplied = () => {
+
+    const testElem = document.createElement("div");
+
+    testElem.className = "d-none";
+    document.body.appendChild(testElem);
+
+    const display = getComputedStyle(testElem).display;
+
+    document.body.removeChild(testElem);
+
+    return display === "none";
+  };
+
+  const deadline = AbortSignal.timeout(timeoutMs);
+  const composed = AbortSignal.any([ signal, deadline ]);
+
+  while(!composed.aborted) {
+
+    if(isBootstrapApplied()) {
+
+      return true;
+    }
+
+    try {
+
+      // The poll interval is the loop's intentional throttle - one probe per interval, not in a tight loop. Same exception as the persist drain: the await is the
+      // point of the iteration.
+      // eslint-disable-next-line no-await-in-loop
+      await delay(intervalMs, composed);
+    } catch {
+
+      // Composed signal aborted (deadline or caller). Exit the loop.
+      break;
+    }
+  }
+
+  // Only warn on the deadline path - a caller-driven abort (page teardown) is not actionable, just a lifecycle event. The accent color falls back to the system
+  // AccentColor keyword; the UI continues to function.
+  if(deadline.aborted && !signal.aborted) {
+
+    // eslint-disable-next-line no-console
+    console.warn("FeatureOptions: Bootstrap stylesheet did not load within " + timeoutMs + "ms - accent color falling back to the system AccentColor keyword.");
+  }
+
+  return false;
+};
+
+// The theme stylesheet. Layout, sidebar, category-frame, search bar, dark-mode utility-class overrides. Color, spacing, radius, and motion values reference the
+// `--fo-*` tokens declared by the tokens effect; structural layout rules (resets, flex containers, container queries) intentionally use raw values since they are
+// not design-token concerns. Consumers see one cohesive design language regardless of which mode is active.
+const buildThemeCss = () => [
+
+  // Base layout reset.
+  "html, body { margin: 0; padding: 0; }",
+
+  // Single source of truth for option-row visibility. Search, filter, and dependency logic all toggle this class.
+  ".fo-hidden { display: none !important; }",
+
+  // Page background AND base text color - the two halves of the base contrast pair, owned together. HBPU forces the surface background, so it must also own the text
+  // color: otherwise the body inherits config-ui-x's cascade, which - because the custom-UI iframe body carries Bootstrap's `.modal-content` class - resolves the
+  // text from `--bs-modal-color` rather than the surface's body color, so an unrelated host value can land on the forced background and render inherited text
+  // (category headers, device names) unreadable. `!important` beats `.modal-content`'s class-level color; elements carrying their own `.text-*` class still set
+  // their own color, so only un-classed inherited text is affected.
+  "body { background-color: var(--fo-surface-bg) !important; color: var(--fo-text-on-elevated) !important; }",
+
+  // Page layout.
+  "#pageFeatureOptions { display: flex !important; flex-direction: column; width: 100%; }",
+  ".feature-main-content { display: flex !important; flex-direction: row !important; width: 100%; }",
+
+  // Sidebar. Background matches the main surface rather than an elevated fill; an accent-derived border delineates it, consistent with the other container frames.
+  "#sidebar { display: block; width: 200px; min-width: 200px; max-width: 200px; position: relative; " +
+    "background-color: var(--fo-surface-bg) !important; border: 1px solid var(--fo-border-accent); border-radius: var(--fo-radius-md); }",
+  "#sidebar .sidebar-content { padding: 0rem; overflow: unset; }",
+  "#controllersContainer { padding: 0; margin-bottom: 0; }",
+  "#devicesContainer { padding: 0; margin-top: 0; padding-top: 0 !important; }",
+
+  // Feature content (right-hand pane).
+  ".feature-content { display: flex !important; flex-direction: column !important; flex: 1 1 auto; min-width: 0; }",
+
+  // Category disclosure header.
+  ".fo-category-header { align-items: center; cursor: pointer; display: flex; font-weight: bold; gap: var(--fo-space-sm); " +
+    "list-style: none; padding: var(--fo-space-sm) var(--fo-space-md); user-select: none; -webkit-user-select: none; }",
+  ".fo-category-header::-webkit-details-marker { display: none; }",
+  ".fo-category-header:hover { color: var(--fo-accent-bg); }",
+
+  // Arrow glyph.
+  ".fo-category-arrow { display: inline-block; font-family: var(--fo-font-monospace); line-height: 1; " +
+    "transition: transform var(--fo-transition-base); }",
+  "details[open] > .fo-category-header .fo-category-arrow { transform: rotate(90deg); }",
+
+  // Rows container: bordered accent frame + soft outer ring + two subgrid column tracks - the checkbox gutter and the content column. A value option's field stacks
+  // beneath its label inside the content column rather than occupying a third track, so there is no shared input column whose width a wide field could distort.
+  ".fo-category-rows { border: 1px solid var(--fo-accent-bg); border-radius: var(--fo-radius-md); " +
+    "box-shadow: 0 0 0 1px var(--fo-accent-hover); overflow: hidden; display: grid; grid-template-columns: auto 1fr; }",
+
+  // Off-screen rendering optimization, scoped to OPEN categories only. `content-visibility: auto` lets the browser skip layout and paint for off-screen rows;
+  // `contain-intrinsic-size` provides a placeholder height (heuristic 200px average) so scroll position stays stable as open categories enter and leave the viewport.
+  // It MUST stay scoped to `details[open]`: a collapsed category's rows container is empty (rows materialize lazily on first expand), and leaving content-visibility on
+  // it makes the browser hold the `contain-intrinsic-size` placeholder height instead of letting the closed disclosure collapse the container to zero. This is the
+  // defined behavior of content-visibility, not an engine quirk - it was observed identically in Chromium and WebKit, and was the source of the large empty gaps
+  // between collapsed categories. Scoping to open categories keeps the optimization where rows actually exist and lets collapsed categories collapse to zero.
+  "details[open] > .fo-category-rows { content-visibility: auto; contain-intrinsic-size: 0 200px; }",
+
+  // Per-row subgrid inheriting the parent's column tracks. The checkbox top-aligns (align-items: start) so that on a multi-line label - or a value option whose field
+  // stacks beneath the label - it sits beside the first line rather than floating against the vertical center of a tall cell.
+  ".fo-option-row { align-items: start; display: grid; gap: var(--fo-space-sm); grid-column: 1 / -1; " +
+    "grid-template-columns: subgrid; padding: var(--fo-space-xs) var(--fo-space-md); " +
+    "transition: background-color var(--fo-transition-fast); }",
+  ".fo-option-row:hover { background-color: var(--fo-row-hover-bg); }",
+  ".fo-option-row.fo-hidden { display: none !important; }",
+
+  // The checkbox top-aligns with the row; this nudge re-centers it on the label's first line (half the line's leading), so a single-line row keeps the control optically
+  // centered on its text while a multi-line or stacked row aligns the control to the first line.
+  ".fo-option-checkbox { margin-top: calc((1lh - 1em) / 2); }",
+
+  // Content cell: the label and, for a value option, its field stack vertically. align-items: flex-start keeps the fixed-width field left-aligned at its declared width
+  // rather than stretching, and min-width: 0 lets a long label wrap within the grid track instead of forcing the track wider.
+  ".fo-option-content { align-items: flex-start; display: flex; flex-direction: column; gap: var(--fo-space-xs); min-width: 0; }",
+
+  // Main options area. Owns its outline with a theme-aware border rather than config-ui-x's box-shadow "border", which exists only in the host's dark theme (so it
+  // is absent in light) and bleeds outside the box (so it clips at the flush iframe edge). Every outer container frame shares --fo-border-accent (the probed theme
+  // accent, subtled), a step lighter than the full-accent per-category frame nested inside so the two read as one family at different weights; the border sits
+  // inside the box, so no edge gutter, and box-shadow: none drops the leftover host shadow.
+  "#optionsContainer { border: 1px solid var(--fo-border-accent); box-shadow: none; margin: 0; padding: 1rem; }",
+
+  // Info header. Owns its outline via --fo-border-accent (see #optionsContainer) so it reads in both themes; the inside-the-box border needs no edge gutter.
+  "#headerInfo { border: 1px solid var(--fo-border-accent); box-shadow: none; flex-shrink: 0; " +
+    "margin-bottom: var(--fo-space-sm) !important; padding: var(--fo-space-sm) !important; }",
+
+  // Device stats grid. The `#headerInfo` ancestor carries `container-type: inline-size` (below) so the grid's responsive hiding fires when its container narrows -
+  // not when the viewport does. The Homebridge plugin UI panel can resize independently of the viewport (custom UI tab, embedded contexts), so container-relative
+  // sizing is what users actually want.
+  "#headerInfo { container-type: inline-size; }",
+  ".device-stats-grid { border: 1px solid var(--fo-border-accent); border-radius: var(--fo-radius-md); display: flex; " +
+    "justify-content: space-between; gap: var(--fo-space-md); margin-bottom: var(--fo-space-sm); padding: 0 var(--fo-space-md); flex-wrap: nowrap; overflow: hidden; }",
+  ".device-stats-grid .stat-item:first-child { flex: 0 0 25%; }",
+  ".device-stats-grid .stat-item:not(:first-child) { flex-grow: 1; min-width: 0; }",
+  ".stat-item { display: flex; flex-direction: column; gap: var(--fo-space-xxs); }",
+  ".stat-label { font-weight: 600; color: var(--fo-text-muted); font-size: var(--fo-font-size-xs); " +
+    "text-transform: uppercase; letter-spacing: 0.05em; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }",
+  ".stat-value { font-size: 0.875rem; color: var(--fo-text-on-elevated); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }",
+
+  // Responsive hiding for device stats grid. `@container` (not `@media`) so the breakpoints fire on the panel's actual width, not the viewport. Progressive
+  // degradation: as the container narrows, the last stat hides first, then the second-to-last, etc., so the most-important left-most stat (Firmware) stays visible
+  // longest.
+  "@container (max-width: 700px) { .device-stats-grid .stat-item:nth-last-of-type(1) { display: none !important; } }",
+  "@container (max-width: 500px) { .device-stats-grid .stat-item:nth-last-of-type(2) { display: none !important; } }",
+  "@container (max-width: 300px) { .device-stats-grid .stat-item:nth-last-of-type(3) { display: none !important; } }",
+  "@container (max-width: 400px) { #statusInfo { display: none !important; } }",
+
+  // Navigation styles.
+  ".nav-link { border-radius: var(--fo-radius-sm); transition: all var(--fo-transition-base); position: relative; " +
+    "padding: var(--fo-space-xs) var(--fo-space-md) !important; line-height: 1.2; font-size: var(--fo-font-size-sm); }",
+  ".nav-link:hover { background-color: var(--fo-accent-hover); color: var(--fo-accent-bg) !important; }",
+  ".nav-link.active { background-color: var(--fo-accent-bg); color: var(--fo-accent-fg) !important; }",
+  // In-scope controller affordance: a 1px accent ring (inset box-shadow so it follows the radius and adds no layout shift) marking the controller whose devices are
+  // currently listed. `:not(.active)` suppresses it when that controller is the active selection - so it shows only in the Global-selected state, one tier below the
+  // filled active pill.
+  ".nav-link.context:not(.active) { box-shadow: inset 0 0 0 1px var(--fo-border-accent); }",
+  ".nav-header { border-bottom: 1px solid var(--fo-border-subtle); margin-bottom: var(--fo-space-xxs); " +
+    "padding: var(--fo-space-xs) var(--fo-space-md) !important; font-size: var(--fo-font-size-xs) !important; line-height: 1.2; }",
+  "#devicesContainer .nav-header, #controllersContainer .nav-header { font-weight: 600; margin-top: 0 !important; padding-top: var(--fo-space-sm) !important; }",
+  // The Global Options link shares `.nav-header` for its bold-uppercase look but is a selectable, highlighted pill, not a section separator - so it keeps symmetric
+  // vertical padding rather than inheriting the section-header top spacing above (which otherwise pushes its text below the pill's center).
+  "#controllersContainer .nav-link[data-navigation=\"global\"] { padding-top: var(--fo-space-xs) !important; }",
+
+  // Search bar.
+  ".search-toolbar { border-radius: var(--fo-radius-md); padding: 0 0 var(--fo-space-sm) 0; }",
+  ".search-input-wrapper { min-width: 0; }",
+  ".filter-pills { display: flex; gap: var(--fo-space-sm); flex-wrap: wrap; }",
+
+  // Search input resting border. Matches the container frames via --fo-border-accent for a consistent outline; scoped :not(:focus) so it never touches the focus
+  // state - the accent glow (box-shadow) and focus border that appear when the field is selected are left entirely to the focus rules below.
+  "#search .form-control:not(:focus) { border-color: var(--fo-border-accent); }",
+
+  // Search input focus state (governs light mode). Sets the accent border and glow so the selected field matches the theme instead of Bootstrap's blue; the
+  // dark-mode override further below wins in dark and carries the same glow via the shared --fo-focus-ring token.
+  "#search .form-control:focus { border-color: var(--fo-border-accent); box-shadow: var(--fo-focus-ring); }",
+
+  // Status bar. Owns its outline via --fo-border-accent (see #optionsContainer) for a consistent border in both themes.
+  "#featureStatusBar { border: 1px solid var(--fo-border-accent); box-shadow: none; }",
+
+  // Grouped-option visual indicator.
+  ".fo-option-row.grouped-option { background-color: var(--fo-accent-subtle); }",
+  ".fo-option-row.grouped-option .fo-option-content { padding-left: 1.25rem; position: relative; }",
+  ".fo-option-row.grouped-option .fo-option-content::before { content: \"\\21B3\"; position: absolute; left: var(--fo-space-xs); color: var(--fo-grouped-indicator); }",
+
+  // Dark-mode-only overrides for Bootstrap utility classes that need treatment beyond what tokens express.
+  ":root.fo-dark .text-body { color: var(--fo-text-muted) !important; }",
+  ":root.fo-dark .text-muted { color: var(--fo-text-muted) !important; }",
+  ":root.fo-dark #search .form-control { background-color: var(--fo-form-control-bg); border-color: var(--fo-border-accent); color: var(--fo-text-on-elevated); }",
+  ":root.fo-dark #search .form-control:focus { background-color: var(--fo-form-control-bg); border-color: var(--fo-form-control-focus-border); " +
+    "color: var(--fo-text-on-elevated); box-shadow: var(--fo-focus-ring); }",
+  ":root.fo-dark #search .form-control::placeholder { color: var(--fo-form-control-placeholder); }",
+  ":root.fo-dark #statusInfo .text-muted { color: var(--fo-statusinfo-muted) !important; }",
+
+  // Utility styles.
+  ".btn-xs { font-size: var(--fo-font-size-xs) !important; padding: var(--fo-space-xxs) var(--fo-space-sm) !important; line-height: 1.5; touch-action: manipulation; }",
+  ".cursor-pointer { cursor: pointer; }",
+  ".user-select-none { user-select: none; -webkit-user-select: none; }",
+
+  // Accessibility.
+  "@media (prefers-reduced-motion: reduce) { * { transition: none !important; animation: none !important; } }"
+
+].join("\n");