homebridge-plugin-utils 1.35.0 → 2.0.0

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

@@ -0,0 +1,152 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/effects/tokens.mjs: Design-token stylesheet adoption for the feature options webUI.
+ */
+"use strict";
+
+/**
+ * Register the design-tokens effect. Adopts a constructable stylesheet declaring every `--fo-*` CSS custom property the rest of the webUI references (font family,
+ * font scale, spacing scale, radii, motion, accent colors, surfaces, borders, text, form controls, interactive states, specific colors). Cleanup is automatic via
+ * the supplied AbortSignal - aborting removes the stylesheet from `document.adoptedStyleSheets`.
+ *
+ * Stylistic invariants the tokens encode:
+ *
+ *   1. **Tokens declare, theme overrides.** Accent tokens default to the CSS-standard `AccentColor` / `AccentColorText` keywords; the theme effect overrides them at
+ *      runtime via `documentElement.style.setProperty` after probing Bootstrap's `.btn-primary`. The declared defaults remain in effect until (and if) the probe
+ *      succeeds, so the user sees a sensible accent before Bootstrap's stylesheet is necessarily ready.
+ *   2. **Dark mode is token redefinition, not light-dark() at the consumer.** Every light/dark color pair is expressed as two declarations of the same token - one
+ *      at `:root` for the light default, one at `:root.fo-dark` for the dark override. Consumers reference the token by name (`var(--fo-surface-bg)`) and get the
+ *      right value automatically. A future third theme (high-contrast, brand variant) joins by adding a third selector block; no consumer rules change.
+ *
+ * Adopted synchronously - token declarations are static and have no I/O dependencies, so the stylesheet is ready by the time the call returns. Must run before any
+ * consumer (the theme effect or any inline style using `var(--fo-*)`) references a token, which the orchestrator's boot sequence guarantees by registering this
+ * effect first.
+ *
+ * @param {Object} args
+ * @param {AbortSignal} args.signal - Lifecycle signal. Aborting releases the stylesheet from the document.
+ */
+export const registerTokensEffect = ({ signal }) => {
+
+  if(signal.aborted) {
+
+    return;
+  }
+
+  const stylesheet = new CSSStyleSheet();
+
+  stylesheet.replaceSync(buildTokenCss());
+  document.adoptedStyleSheets = [ ...document.adoptedStyleSheets, stylesheet ];
+
+  signal.addEventListener("abort", () => {
+
+    // Release the stylesheet. Filter-rebuild rather than mutate to preserve the array's identity contract across consumers.
+    document.adoptedStyleSheets = document.adoptedStyleSheets.filter((sheet) => sheet !== stylesheet);
+  }, { once: true });
+};
+
+// Assemble the full token CSS. Grouped by category with a section comment per group so the file reads as the design vocabulary it represents. Within a scale
+// group, tokens order smallest-to-largest by magnitude; within a flat group, tokens order alphabetically by token name; surfaces order by conceptual layering
+// (base surface before elevated) rather than by scale or alphabet. The groups themselves are ordered by their position in the same conceptual hierarchy, from
+// the broadest, foundational concerns down to the narrowest, single-purpose tokens.
+const buildTokenCss = () => [
+
+  ":root {",
+
+  // Font family. Provides explicit fallbacks beyond the `ui-monospace` keyword because Chrome's form-control font-resolution path can land on serif when only the
+  // keyword is specified. The stack walks the platform's canonical monospace files explicitly, terminating in the `monospace` generic.
+  "  --fo-font-monospace: ui-monospace, SFMono-Regular, Menlo, Consolas, \"Liberation Mono\", \"Courier New\", monospace;",
+
+  // Font scale.
+  "  --fo-font-size-xs: 0.75rem;",
+  "  --fo-font-size-sm: 0.8125rem;",
+
+  // Spacing scale. T-shirt sized, rem-based, distinct from Bootstrap's numbered `--bs-spacer * N` to avoid the half-aligned trap.
+  "  --fo-space-xxs: 0.125rem;",
+  "  --fo-space-xs: 0.25rem;",
+  "  --fo-space-sm: 0.5rem;",
+  "  --fo-space-md: 0.75rem;",
+  "  --fo-space-lg: 1rem;",
+
+  // Border-radius scale.
+  "  --fo-radius-sm: 0.375rem;",
+  "  --fo-radius-md: 0.5rem;",
+
+  // Motion.
+  "  --fo-transition-fast: 0.15s;",
+  "  --fo-transition-base: 0.2s;",
+
+  // Accent colors. CSS-standard `AccentColor` / `AccentColorText` keywords as the declared defaults; the theme effect overrides at runtime via setProperty after
+  // probing Bootstrap's `.btn-primary`. The derivative tokens (-hover, -subtle) compose via `color-mix()` against whatever value the accent currently holds, so the
+  // derivatives stay in lockstep with both the default and the probed override without separate machinery.
+  "  --fo-accent-bg: AccentColor;",
+  "  --fo-accent-fg: AccentColorText;",
+  "  --fo-accent-hover: color-mix(in srgb, var(--fo-accent-bg) 10%, transparent);",
+  "  --fo-accent-subtle: color-mix(in srgb, var(--fo-accent-bg) 8%, transparent);",
+
+  // Surfaces. Light defaults; `:root.fo-dark` redeclares for dark mode. Tokens that defer to Bootstrap variables carry an explicit fallback inside the `var()` so
+  // the token resolves cleanly even when Bootstrap has not loaded yet (the orchestrator initializes tokens before Bootstrap's stylesheet is necessarily ready).
+  "  --fo-surface-bg: #ffffff;",
+  "  --fo-elevated-bg: var(--bs-gray-100, #f8f9fa);",
+
+  // Borders.
+  // Accent-derived container border - the probed theme accent at reduced opacity, shared by every outer container frame. One declaration for both themes: the
+  // accent is theme-probed, not light/dark-specific, so it needs no `:root.fo-dark` redeclaration. Kept a step lighter than the full-accent per-category frame so
+  // the two read as the same family at different weights.
+  "  --fo-border-accent: color-mix(in srgb, var(--fo-accent-bg) 50%, transparent);",
+  "  --fo-border-strong: var(--bs-border-color, #dee2e6);",
+  "  --fo-border-subtle: rgba(0, 0, 0, 0.1);",
+
+  // Text.
+  "  --fo-text-muted: var(--bs-gray-600, #6c757d);",
+  "  --fo-text-on-elevated: var(--bs-body-color, #212529);",
+
+  // Form controls (light = Bootstrap defaults; dark overrides at `:root.fo-dark`).
+  "  --fo-form-control-bg: var(--bs-body-bg, #ffffff);",
+  "  --fo-form-control-border: var(--bs-border-color, #dee2e6);",
+  // A latent hook kept for symmetry with the dark override below: no light-mode rule consumes this token today (light-mode search focus uses Bootstrap's own focus
+  // styling), so this accent default takes effect only if a future light-mode focus rule references it.
+  "  --fo-form-control-focus-border: var(--fo-accent-bg);",
+  "  --fo-form-control-placeholder: var(--bs-secondary-color, rgba(33, 37, 41, 0.75));",
+  // The focus ring (box-shadow glow) shared by the search input's light and dark focus rules. Light matches the container border color (--fo-border-accent) so the
+  // ring reads as the same theme slate; dark redeclares a lighter accent tint below, because a translucent color that reads well on the dark surface washes out to
+  // near-gray on the light one - the ring is genuinely mode-dependent, like the surface tokens.
+  "  --fo-focus-ring: 0 0 0 0.2rem var(--fo-border-accent);",
+
+  // Interactive-state colors.
+  "  --fo-row-hover-bg: rgba(0, 0, 0, 0.03);",
+
+  // Specific colors. The grouped-option indicator (the Unicode `\\21B3` arrow) and the statusInfo's muted text want a distinct value from `--fo-text-muted` for
+  // visual hierarchy; they get their own tokens to express that.
+  "  --fo-grouped-indicator: #666;",
+  "  --fo-statusinfo-muted: var(--bs-secondary-color, rgba(33, 37, 41, 0.75));",
+
+  "}",
+
+  // Dark-mode redeclarations. Same tokens, dark values. The cascade applies these when `.fo-dark` is on `:root`, which the theme effect toggles based on the user's
+  // Homebridge lighting-mode preference.
+  ":root.fo-dark {",
+  "  --fo-surface-bg: #242424;",
+  "  --fo-elevated-bg: #1A1A1A;",
+  "  --fo-border-strong: #444;",
+  "  --fo-border-subtle: rgba(255, 255, 255, 0.1);",
+  "  --fo-text-muted: #999;",
+  "  --fo-text-on-elevated: #F8F9FA;",
+  "  --fo-form-control-bg: #1A1A1A;",
+  "  --fo-form-control-border: #444;",
+  // A deliberately neutral border rather than the accent: the dark focus rule pairs this with an accent-tinted glow (the focus box-shadow), so the accent affordance
+  // shows through the glow while the border stays plain gray rather than doubling the accent on both the border and the ring.
+  "  --fo-form-control-focus-border: #666;",
+  "  --fo-form-control-placeholder: #999;",
+  // Dark focus ring: a lighter accent tint than light's border-matched value - 25% reads as a clear glow against the dark surface, where a stronger ring would be
+  // heavy. (Light uses the full border color; see the light declaration above.)
+  "  --fo-focus-ring: 0 0 0 0.2rem color-mix(in srgb, var(--fo-accent-bg) 25%, transparent);",
+  // A white tint at a far higher alpha than the light block's 3% black: a faint dark overlay is invisible against the dark surface, so the dark hover needs a lighter,
+  // stronger tint to read as an equivalent highlight.
+  "  --fo-row-hover-bg: rgba(255, 255, 255, 0.20);",
+  // Kept distinct from --fo-text-muted (#999 in dark mode) for the same visual-hierarchy reason as the light-mode block above; lighter than the muted text so the
+  // grouped-option arrow reads as slightly more prominent on a dark surface, mirroring the darker-than-muted emphasis it carries in light mode.
+  "  --fo-grouped-indicator: #B0B0B0;",
+  "  --fo-statusinfo-muted: #B8B8B8;",
+  "}"
+
+].join("\n");

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

@@ -0,0 +1,431 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * webUi-featureOptions/rendering.mjs: Pure DOM construction for the feature options webUI.
+ */
+"use strict";
+
+import { isValueOption, optionExists } from "../featureOptions.js";
+import { createElement } from "./utils.mjs";
+
+/**
+ * Pure DOM construction for the feature options webUI.
+ *
+ * Every export here is a pure function from data to DOM:
+ *
+ *   - {@link categoryShell} - builds the `<details>` shell for one category (header + empty rows container). Lazy materialization: the rows container is intentionally
+ *     empty; the view fills it on first expand to keep initial render bounded by category count, not option count.
+ *   - {@link optionRow} - builds one option row's bare structure (checkbox, label, optional value-input) and applies its initial state via {@link applyRowState}.
+ *   - {@link applyRowState} - the single writer for every state-dependent attribute of a row (tri-state, value-input state, label color, visibility, dependency
+ *     badge), derived from the projection entry. The construction path and the per-mutation update walk both call it, so a freshly-built row and a re-derived row run
+ *     identical code - no derived attribute can be set on one path and forgotten on the other. This is what makes the row DOM a pure function of the projection.
+ *   - {@link triStateTransition} - the click-time state machine. Given the current DOM state of a checkbox plus the projection entry and configuration, computes only
+ *     the action to dispatch. The resulting DOM state is not returned: the dispatch updates the store, and the view re-derives the row through {@link applyRowState}
+ *     against the post-dispatch projection. Pure - takes data, returns data.
+ *
+ * The functions take projection entries (the view-relative records built by {@link projection}), the current view's scope kind, and any view-context identifiers
+ * they need (controllerId, deviceId). They do not read from a store, do not subscribe to events, do not call selectors. The view layer assembles the inputs and
+ * applies the outputs.
+ *
+ * Splitting the tri-state click logic out as a pure function ({@link triStateTransition}) means the inheritance state machine's action selection can be tested in
+ * isolation with plain DOM stubs - no store, no view layer, no event scaffolding. The view layer calls it on the change event, dispatches the returned action, and
+ * lets the reactive re-projection drive the DOM through {@link applyRowState}.
+ *
+ * @module
+ */
+
+/**
+ * Build the `<details>` shell for a category. Returns the disclosure element with its header (`<summary>`) and an empty `<div class="fo-category-rows">` rows
+ * container. The rows container is intentionally empty; the view materializes its option rows lazily on first expand via {@link optionRow}.
+ *
+ * The category header carries a scope-suffix label - `(Global)` / `(Controller-specific)` / `(Device-specific)` - so the user always knows which scope they are
+ * editing at. Each variant maps directly from the view's scope kind; we do not consult validators here because the scope DU already encodes the distinction
+ * (controller view vs device view is the scope's kind, not a runtime predicate).
+ *
+ * @param {Object} args
+ * @param {import("../featureOptions.js").FeatureCategoryEntry} args.category - The catalog entry for the category.
+ * @param {"controller" | "device" | "global"} args.scopeKind - The current view's scope kind.
+ * @returns {HTMLDetailsElement} The category shell, ready for insertion into the config table.
+ */
+export const categoryShell = ({ category, scopeKind }) => {
+
+  const arrow = createElement("span", { "aria-hidden": "true", classList: ["fo-category-arrow"] }, ["▶"]);
+  const title = createElement("span", { classList: ["fo-category-title"] }, [category.description + scopeLabel(scopeKind)]);
+  const summary = createElement("summary", { classList: ["fo-category-header"], title: "Expand or collapse this category." }, [ arrow, title ]);
+  const rows = createElement("div", { classList: ["fo-category-rows"] });
+  const details = createElement("details", { classList: ["fo-category"], "data-category": category.name });
+
+  details.appendChild(summary);
+  details.appendChild(rows);
+
+  return details;
+};
+
+/**
+ * Build one option row: its bare structure plus the initial state applied through {@link applyRowState}.
+ *
+ * Every row has one uniform shape - a checkbox followed by a `<div class="fo-option-content">` cell - regardless of option kind:
+ *
+ *   - **Boolean options**: the content cell holds only the `<label>`.
+ *   - **Value-centric options**: the content cell stacks the `<label>` and an `<input type="text">` directly beneath it. The label always reads at full width and the
+ *     field sits below at the width declared by the option's `inputSize` (5 ch when unspecified). The field never occupies a shared grid column, so its width cannot
+ *     crush its own label or widen sibling rows. `inputSize` controls only the field's declared width.
+ *
+ * The row structure is uniform regardless of option kind: one row, one stacked content cell, so a long descriptive label and a compact value render through exactly
+ * the same path and differ only in the field's declared width.
+ *
+ * The element factories ({@link createCheckbox}, {@link createLabel}, {@link createValueInput}) build only the bare, state-independent shape. Every state-dependent
+ * attribute - the checkbox tri-state, the value-input's value / disabled state, the label color, row visibility, the dependency badge - is set by {@link applyRowState}
+ * once the structure exists. Sharing that single writer between construction here and the per-mutation update walk in the view is what keeps a freshly-built row and a
+ * re-derived row identical.
+ *
+ * @param {Object} args
+ * @param {string | null} args.deviceId - The currently-selected device's serial, or null for the global view.
+ * @param {import("./selectors.mjs").ProjectionEntry} args.entry - The projection entry for this option.
+ * @param {"controller" | "device" | "global"} args.scopeKind - The current view's scope kind.
+ * @returns {HTMLDivElement} The constructed row element.
+ */
+export const optionRow = ({ deviceId, entry, scopeKind }) => {
+
+  const { expandedName, isGrouped, option } = entry;
+  const valueCentric = option.defaultValue !== undefined;
+  const classes = [ "fo-option-row", ...(isGrouped ? ["grouped-option"] : []) ];
+
+  const row = createElement("div", { classList: classes, id: "row-" + expandedName });
+
+  // The content cell stacks the label and, for a value-centric option, its value-input directly beneath it. The label always reads at full width and the field sits
+  // below at the declared inputSize width, so one layout serves both the compact and the descriptive case and no value-input ever occupies a shared right-hand column.
+  const content = [createLabel({ entry, expandedName })];
+
+  if(valueCentric) {
+
+    content.push(createValueInput({ option }));
+  }
+
+  row.appendChild(createCheckbox({ deviceId, expandedName, option }));
+  row.appendChild(createElement("div", { classList: ["fo-option-content"] }, content));
+
+  // The structure is in place; apply every state-dependent attribute from the projection entry. This is the same writer the view's per-mutation walk uses, so a
+  // freshly-materialized row arrives correct from its first render without a separate "set the initial state here" path that could drift from the update path.
+  applyRowState({ entry, row, scopeKind });
+
+  return row;
+};
+
+/**
+ * Apply every state-dependent attribute of an option row from its projection entry. The single source of truth for "what does this row look like given the model" -
+ * called once at construction (from {@link optionRow}) and again on every projection-affecting dispatch (from the view's update walk), so the row DOM is a pure
+ * function of the projection at all times.
+ *
+ * What it derives:
+ *
+ *   - **Visibility** (`fo-hidden`) and the **dependency badge** (dimmed opacity + disabled checkbox) - a grouped option whose parent is currently disabled is shown
+ *     dimmed and non-interactive when a filter or search keeps it visible; every other row carries no dim treatment.
+ *   - **Checkbox tri-state** - inheriting from a higher scope reads as indeterminate + readOnly (the "borrowing from above" state the click machine cycles out of);
+ *     otherwise the checkbox reflects the resolved enabled state directly.
+ *   - **Label color** - the "where did this value come from / has it been modified" cue. Re-applying it here on every projection change is what makes a toggle that
+ *     modifies (or reverts) an option re-color its label in place, rather than freezing the color at construction time.
+ *   - **Value-input state** (value-centric options only) - readOnly / disabled track the inherit + enabled axes. The value text is re-derived from the projection
+ *     EXCEPT while the user is actively editing it: uncommitted text exists only while the input holds focus (the `change` event commits on blur / Enter), so guarding
+ *     on `document.activeElement` is exactly the condition under which a re-derive would clobber an in-progress edit.
+ *
+ * @param {Object} args
+ * @param {import("./selectors.mjs").ProjectionEntry} args.entry - The projection entry for this option.
+ * @param {HTMLDivElement} args.row - The option row element to update in place.
+ * @param {"controller" | "device" | "global"} args.scopeKind - The current view's scope kind.
+ */
+export const applyRowState = ({ entry, row, scopeKind }) => {
+
+  const inheriting = isInheritingView(scopeKind, entry.scope);
+
+  row.classList.toggle("fo-hidden", !entry.visible);
+  row.style.opacity = entry.requiresParentBadge ? "0.5" : "";
+
+  const checkbox = row.querySelector(".fo-option-checkbox");
+
+  if(checkbox) {
+
+    // The inherit axis (indeterminate + readOnly) and the dependency-badge axis (disabled) are independent; a row can be both inheriting and parent-disabled.
+    checkbox.checked = entry.enabled;
+    checkbox.indeterminate = inheriting;
+    checkbox.readOnly = inheriting;
+    checkbox.disabled = entry.requiresParentBadge;
+  }
+
+  const label = row.querySelector(".fo-option-label");
+
+  if(label) {
+
+    applyLabelColor({ entry, inheriting, label });
+  }
+
+  const input = row.querySelector(".fo-option-value");
+
+  if(input) {
+
+    const locked = inheriting || !entry.enabled;
+
+    input.readOnly = locked;
+    input.disabled = locked;
+
+    if(locked) {
+
+      input.setAttribute("aria-disabled", "true");
+    } else {
+
+      input.removeAttribute("aria-disabled");
+    }
+
+    // Never overwrite the value the user is currently editing. Outside an active edit the projection's resolved value is authoritative.
+    if(document.activeElement !== input) {
+
+      input.value = entry.value ?? defaultDisplay(entry.option);
+    }
+  }
+};
+
+/**
+ * The tri-state click-time state machine. Given the current DOM state of a clicked checkbox (post-browser-toggle) plus the projection entry, configuration index, and
+ * view context, compute the action to dispatch.
+ *
+ * Three transitions, distinguished by the checkbox's pre-call state:
+ *
+ *   - **readOnly (was indeterminate)** -> the user clicked through to an explicit state at this scope. Action: set explicitly, or clear when the write rule says the
+ *     entry-less resolution already matches the user's intent.
+ *   - **just unchecked (was checked)** -> if an upstream entry exists, clear so resolution falls back to inheritance (the row returns to indeterminate); otherwise the
+ *     explicit disable stays, recorded or normalized to a clear per the write rule.
+ *   - **just checked (was unchecked)** -> set explicitly (or clear when the post-state matches default with no upstream).
+ *
+ * Write rule (parallels {@link FeatureOptions} semantics): a clearOption is correct when the resulting resolution equals the user's intent at this scope - that is,
+ * when the catalog default matches AND no upstream entry exists. In that case the entry-less lookup naturally produces the right value. A setOption is needed when
+ * any of those conditions break (default differs, value differs, upstream needs overriding).
+ *
+ * The function neither mutates nor returns DOM state: it returns only the action. The caller dispatches it, and the reactive re-projection drives the row's DOM
+ * through {@link applyRowState} against the post-dispatch projection - the resolved tri-state the projection produces is, by construction, exactly the state this
+ * transition intends, so there is no second DOM-writing path to keep in sync.
+ *
+ * @param {Object} args
+ * @param {import("./state.mjs").Catalog} args.catalog - The catalog index (for value-centric detection and upstream lookup).
+ * @param {HTMLInputElement} args.checkbox - The clicked checkbox, with its post-browser-toggle state.
+ * @param {import("../featureOptions.js").ConfigIndex} args.configIndex - The current config lookup index.
+ * @param {string | null} args.controllerId - The current controller serial, or null when no controller is in context.
+ * @param {string | null} args.deviceId - The current view's device serial, or null for global view.
+ * @param {import("./selectors.mjs").ProjectionEntry} args.entry - The projection entry for the option.
+ * @param {HTMLInputElement | null} args.inputValue - The value-input element, when the option is value-centric; null otherwise.
+ * @returns {{ action: Object }} The action to dispatch.
+ */
+export const triStateTransition = ({ catalog, checkbox, configIndex, controllerId, deviceId, entry, inputValue }) => {
+
+  const { expandedName, option } = entry;
+  const upstream = hasUpstreamOption({ configIndex, controllerId, deviceId, expandedName });
+
+  // Transition 1: was indeterminate (readOnly). The user clicked through to an explicit state at this scope.
+  if(checkbox.readOnly) {
+
+    return { action: writeAction({ deviceId, enabled: false, expandedName, inputValue, option, upstream, valueCentric: isValueOption(catalog, expandedName) }) };
+  }
+
+  // Transition 2: just transitioned to unchecked. With an upstream entry the clearOption returns the row to inheritance; without one the explicit disable stays
+  // (recorded or normalized to a clear per the write rule).
+  if(!checkbox.checked) {
+
+    if(upstream) {
+
+      return { action: { args: { id: deviceId ?? undefined, option: expandedName }, type: "option:cleared" } };
+    }
+
+    return { action: writeAction({ deviceId, enabled: false, expandedName, inputValue, option, upstream, valueCentric: isValueOption(catalog, expandedName) }) };
+  }
+
+  // Transition 3: just transitioned to checked. Explicit enable at this scope.
+  return { action: writeAction({ deviceId, enabled: true, expandedName, inputValue, option, upstream, valueCentric: isValueOption(catalog, expandedName) }) };
+};
+
+// Map a view scope kind to the suffix label rendered on category headers. Switch on the discriminator; every scope kind maps to its own label.
+const scopeLabel = (scopeKind) => {
+
+  switch(scopeKind) {
+
+    case "global":
+
+      return " (Global)";
+
+    case "controller":
+
+      return " (Controller-specific)";
+
+    case "device":
+
+      return " (Device-specific)";
+
+    default:
+
+      return "";
+  }
+};
+
+// Decide whether the entry is "inherited from above" relative to the current view. The view is at viewKind; the entry resolved at resolvedScope. An entry is
+// inherited when the resolved scope is strictly higher than the view scope. The switch covers the three current scope kinds; an unrecognized kind silently resolves to
+// "not inheriting" rather than throwing.
+const isInheritingView = (viewKind, resolvedScope) => {
+
+  switch(viewKind) {
+
+    case "global":
+
+      // The view IS the highest scope - nothing is inherited from above.
+      return false;
+
+    case "controller":
+
+      // From a controller view, only global is higher.
+      return resolvedScope === "global";
+
+    case "device":
+
+      // From a device view, both global and controller are higher.
+      return (resolvedScope === "global") || (resolvedScope === "controller");
+
+    default:
+
+      return false;
+  }
+};
+
+// Build the checkbox element. Pure: returns a fresh element carrying only its bare, state-independent shape. The tri-state is applied by {@link applyRowState}.
+const createCheckbox = ({ deviceId, expandedName, option }) => {
+
+  const checkbox = createElement("input", {
+
+    classList: ["fo-option-checkbox"],
+    "data-device-serial": deviceId ?? "",
+    id: expandedName,
+    name: expandedName,
+    type: "checkbox",
+    value: expandedName + (deviceId ? ("." + deviceId) : "")
+  });
+
+  // Record the option's default-on/off as the checkbox's default state, kept separate from the live `.checked` tri-state that applyRowState owns. Nothing reads this
+  // default today - there is no form reset, clone, or `:default` rule - but it keeps the element honest for any future consumer that relies on default-state semantics.
+  checkbox.defaultChecked = option.default;
+
+  return checkbox;
+};
+
+// Build the description label for an option. The `for` attribute connects it to the checkbox so native label-for click semantics work. The color class is applied
+// separately by {@link applyLabelColor} (via {@link applyRowState}) so the label's structure stays state-independent.
+const createLabel = ({ entry, expandedName }) => createElement("label", {
+
+  classList: [ "fo-option-label", "user-select-none", "my-0", "py-0", "cursor-pointer" ],
+  for: expandedName
+}, [entry.description]);
+
+// Apply the label's scope-color class, replacing any color previously applied. The color classes are mutually exclusive, so we strip every one of them before adding
+// the current one - this makes the function idempotent and safe to re-run on every projection change, which is what lets a toggle re-color a modified option's label
+// in place. The construction path and the per-mutation update path share this one writer, so the initial color and every subsequent color come from the same map.
+const applyLabelColor = ({ entry, inheriting, label }) => {
+
+  label.classList.remove("text-body", "text-info", "text-success", "text-warning");
+  label.classList.add(scopeColorClass({ entry, inheriting }));
+};
+
+// Map the row's display state to its Bootstrap utility class. Two cases by inheritance:
+//
+//   - **Inheriting from a higher scope**: the row is showing a value sourced from an ancestor scope. Color identifies the source - text-success for controller,
+//     text-warning for global (warning because the global entry is the most distant source, the row is "borrowing" from far away).
+//   - **Explicit at this scope or below** (not inheriting): the entry IS set at the current view's scope (or unset entirely). When the explicit state differs
+//     from the catalog default, mark it text-info as a "this row has been modified" cue. Default-matching unset rows render text-body.
+//
+// The webUI's sole scope-to-class mapping. It consumes the `inheriting` boolean that {@link applyRowState} derives via {@link isInheritingView} from the view's
+// scopeKind and the projection's `entry.scope`, rather than re-deriving that boolean itself; the switch below still reads `entry.scope` directly to pick the color.
+const scopeColorClass = ({ entry, inheriting }) => {
+
+  if(inheriting) {
+
+    switch(entry.scope) {
+
+      case "controller":
+
+        return "text-success";
+
+      case "global":
+
+        return "text-warning";
+
+      default:
+
+        return "text-body";
+    }
+  }
+
+  // Explicit at this scope or below. The modification highlight is boolean-deviation-only by design: a row lights up text-info only when its
+  // enabled-state differs from the catalog default. A value-centric option whose value was changed but whose enabled-state still matches the default is intentionally
+  // NOT highlighted - the cue tracks the boolean axis, not the value axis. A default-matching row renders plain body color.
+  if(entry.isModified && (entry.enabled !== entry.option.default)) {
+
+    return "text-info";
+  }
+
+  return "text-body";
+};
+
+// Build the value input for a value-centric option. Pure: returns a fresh element carrying only its bare, state-independent shape - the class set, the input type,
+// and the width derived from the option's `inputSize` declaration (or 5 ch when unspecified), capped at the content cell's width so a wide field never overflows the
+// row on a narrow panel. The value, readOnly, and disabled state are applied by {@link applyRowState}.
+const createValueInput = ({ option }) => createElement("input", {
+
+  classList: [ "form-control", "shadow-none", "fo-option-value" ],
+  style: {
+
+    boxSizing: "content-box",
+    fontFamily: "var(--fo-font-monospace)",
+    maxWidth: "100%",
+    width: (option.inputSize ?? 5) + "ch"
+  },
+  type: "text"
+});
+
+// Render the catalog's `defaultValue` as the displayable string used by both the input element and the deviation comparison. Empty string is the consistent
+// representation across every consumer so the input reads empty when disabled and the deviation check treats an empty input as "matches default."
+const defaultDisplay = (option) => option.defaultValue?.toString() ?? "";
+
+// Whether the option is set at a strictly higher scope than the current view. Drives the "fall back to inheritance" branch of the tri-state machine: a checked
+// checkbox that goes unchecked returns to indeterminate when upstream is set, otherwise stays explicitly unchecked.
+const hasUpstreamOption = ({ configIndex, controllerId, deviceId, expandedName }) => {
+
+  // Global view (no device) is the top - nothing above it. A device view where the device IS the controller-as-device collapses to "controller view" which only
+  // inherits from global; the controllerIsUpstream check below handles that case.
+  if(!deviceId) {
+
+    return false;
+  }
+
+  const controllerIsUpstream = (controllerId !== null) && (deviceId !== controllerId);
+
+  if(controllerIsUpstream && optionExists({ configIndex, id: controllerId, option: expandedName })) {
+
+    return true;
+  }
+
+  return optionExists({ configIndex, option: expandedName });
+};
+
+// Decide whether the post-transition state warrants writing a new entry, or whether clearing the option falls back to the default. We write when the user's intent
+// differs from the catalog default (boolean axis OR value axis) OR when there is an upstream entry that the local state needs to override. Otherwise clearing the
+// option is equivalent and keeps the configuredOptions array minimal.
+const writeAction = ({ deviceId, enabled, expandedName, inputValue, option, upstream, valueCentric }) => {
+
+  const inputValueText = inputValue?.value ?? "";
+  const valueDeviates = (inputValue !== null) && (inputValueText !== defaultDisplay(option));
+  const booleanDeviates = enabled !== option.default;
+  const writeNeeded = booleanDeviates || valueDeviates || upstream;
+  const id = deviceId ?? undefined;
+
+  if(!writeNeeded) {
+
+    return { args: { id, option: expandedName }, type: "option:cleared" };
+  }
+
+  const value = (valueCentric && enabled && (inputValueText.length > 0)) ? inputValueText : undefined;
+
+  return { args: { enabled, id, option: expandedName, value }, type: "option:set" };
+};