prismcast 1.12.1 → 1.14.0

package/dist/routes/config/settings.js

@@ -1,22 +1,35 @@
-import { CONFIG, getDefaults, validatePositiveInt, validatePositiveNumber } from "../../config/index.js";
-import { CONFIG_METADATA, getAdvancedSections, getEnvOverrides, getNestedValue, getSettingsTabSections, getUITabs, isEqualToDefault, mutateConfig, readConfig, setNestedValue } from "../../config/userConfig.js";
-import { LOG, escapeHtml, isRunningAsService, sanitizeString, stringifySorted } from "../../utils/index.js";
+import { CAPTURE_BASELINE_CODEC, RECOGNIZED_CODECS } from "../../types/index.js";
+import { CONFIG_METADATA, getAdvancedSections, getEnvOverrides, getNestedValue, getSettingsTabSections, getUITabs, isEqualToDefault, readConfig, setNestedValue } from "../../config/userConfig.js";
+import { ConfigurationRejectedError, getConfigurationGap, getDefaults, getLoadedConfiguration, validateInteger, validateNumber } from "../../config/index.js";
+import { LOG, escapeHtml, isRunningAsService, sanitizeString, serializeAttrs, stringifySorted } from "../../utils/index.js";
+import { PENDING_PATH_ATTRIBUTE, REACTIVITY_BADGES, formatSettingCount } from "./vocabulary.js";
 import { applyConfigurationChange, describeConfigurationOutcome } from "./index.js";
 import { sendErrorResponse, sendFormErrors, sendSuccess, sendValidationError } from "./http/envelope.js";
 import { ACTIONS } from "../clientActions.js";
 import { VIDEO_QUALITY_PRESETS } from "../../config/presets.js";
+import { generateBadge } from "../components.js";
 import { getConfigFilePath } from "../../config/paths.js";
-import { getGpuCapabilities } from "../../browser/display.js";
 import { getProviderModuleInfo } from "../../browser/channelSelection.js";
+import { isCaptureCodecSupported } from "../../streaming/codec.js";
+import { systemClock } from "homebridge-plugin-utils";
+/* The capture-codec items' words: each recognized codec's label, and the reason each codec other than the baseline states when this GPU cannot capture it. Each
+ * table is keyed by the codec types, so a codec added to the recognized list cannot compile until the form decides its label and, unless it is the baseline,
+ * its reason. Which codecs are fixed and which are available is the codec module's answer, so the form holds only these words. A label names its codec alone,
+ * and the " (always enabled)" suffix is the fixed item's, which the provider below appends to whichever codec is the baseline.
+ */
+const CAPTURE_CODEC_LABELS = {
+    h264: "H.264",
+    hevc: "HEVC"
+};
+const CAPTURE_CODEC_REASONS = {
+    hevc: "Requires GPU with HEVC hardware encoding."
+};
 // Registry of list item providers for checkboxList settings. Each key matches a listItemsKey value in CONFIG_METADATA.
 const LIST_ITEM_PROVIDERS = {
-    captureCodecs: () => {
-        const gpuCaps = getGpuCapabilities();
-        return [
-            { fixed: true, label: "H.264 (always enabled)", value: "h264" },
-            { disabled: !gpuCaps?.hevcHardwareEncoding, disabledReason: "Requires GPU with HEVC hardware encoding.", label: "HEVC", value: "hevc" }
-        ];
-    },
+    // Every recognized codec in order: the baseline as the fixed item, and every other codec disabled while this GPU cannot capture it.
+    captureCodecs: () => RECOGNIZED_CODECS.map((codec) => (codec === CAPTURE_BASELINE_CODEC) ?
+        { fixed: true, label: CAPTURE_CODEC_LABELS[codec] + " (always enabled)", value: codec } :
+        { disabled: !isCaptureCodecSupported(codec), disabledReason: CAPTURE_CODEC_REASONS[codec], label: CAPTURE_CODEC_LABELS[codec], value: codec }),
     providerModules: () => getProviderModuleInfo().map((p) => ({ label: p.label, value: p.slug }))
 };
 /**
@@ -185,15 +198,83 @@ function getFieldWidthClass(setting) {
     // Generic strings get wide width.
     return "field-wide";
 }
+// The marker sentence of each kind, given the running value as the form displays it. Keyed by the kind union, so a kind added later cannot compile until
+// it decides its sentence.
+const PENDING_SENTENCES = {
+    restart: (running) => REACTIVITY_BADGES.restart.title + " Running value: " + running + ".",
+    unrealized: (running) => "Saved, but not applied yet. Running value: " + running + ". The next save retries it."
+};
 /**
- * Generates HTML for a single setting form field. Supports text inputs, number inputs, and select dropdowns based on the setting type and validValues.
+ * Reads a setting's value for a person: the one reading the default line and the pending markers both use, so a value reads the same wherever the form names
+ * it. A checkbox list reads as its members joined, or none when it has no member; a missing value reads as autodetect; a number reads in display units, grouped
+ * unless the setting is a port, with its unit pluralized by the number; any other value reads as its display text with its unit appended as declared.
+ * @param value - The value, in storage units.
  * @param setting - The setting metadata.
- * @param currentValue - The current effective value (in storage units).
- * @param defaultValue - The default value (in storage units).
- * @param envOverride - The environment variable value if overridden, undefined otherwise.
+ * @returns The value's text with its display unit.
+ */
+function formatSettingValue(value, setting) {
+    const displayUnit = getDisplayUnit(setting);
+    const displayValue = toDisplayValue(value, setting);
+    let text;
+    if (setting.type === "checkboxList") {
+        const members = Array.isArray(value) ? value : [];
+        text = (members.length > 0) ? members.join(", ") : "none";
+    }
+    else if (displayValue === null) {
+        text = "autodetect";
+    }
+    else if (typeof displayValue === "number") {
+        text = formatValueForDisplay(displayValue, setting.type);
+    }
+    else {
+        text = displayValue;
+    }
+    if (!displayUnit) {
+        return text;
+    }
+    return text + " " + ((typeof displayValue === "number") ? formatUnitForValue(displayValue, displayUnit) : displayUnit);
+}
+/**
+ * Derives the pending view of a configuration gap: one entry for each saved setting the running process has not taken, keyed by path in the settings' declared
+ * order, each carrying the marker sentence the form shows. The view is derived from the gap on every call and stored nowhere, which is why a save's response
+ * carries all of it rather than a change against an earlier view.
+ * @param gap - The gap to project, the live gap between the running configuration and the loaded snapshot by default.
+ * @returns The pending settings, keyed by path.
+ */
+export function collectPendingSettings(gap = getConfigurationGap()) {
+    const buckets = {
+        held: { changes: gap.held, kind: "restart" },
+        live: { changes: gap.live, kind: "unrealized" },
+        nextStream: { changes: gap.nextStream, kind: "unrealized" }
+    };
+    const filed = new Map();
+    for (const bucket of Object.values(buckets)) {
+        for (const change of bucket.changes) {
+            filed.set(change.path, { change, kind: bucket.kind });
+        }
+    }
+    // Walking the metadata settings rather than looking each gap path up means no lookup can miss, and the view comes out in the order the form renders.
+    const pending = new Map();
+    for (const setting of Object.values(CONFIG_METADATA).flat()) {
+        const entry = filed.get(setting.path);
+        if (!entry) {
+            continue;
+        }
+        // The gap accessor diffs the running configuration against the loaded snapshot, so a change's previous value is the running one the marker names.
+        const running = entry.change.previous;
+        pending.set(setting.path, { kind: entry.kind, path: setting.path, text: PENDING_SENTENCES[entry.kind](formatSettingValue(running, setting)) });
+    }
+    return pending;
+}
+/**
+ * Generates HTML for a single setting form field. The setting's validValues and type choose the control: a select dropdown when validValues is non-empty,
+ * otherwise a hidden-input-plus-checkbox pair for a boolean, a hidden JSON input with a checkbox grid for a checkboxList, and a text or number input for every
+ * other type. The field also carries its pending marker, its default hint and, where they apply, the reset button and the environment override notice.
+ * @param options - The setting, the saved value the form shows, its default, its environment override, and its pending entry.
  * @returns HTML string for the form field.
  */
-function generateSettingField(setting, currentValue, defaultValue, envOverride) {
+function generateSettingField(options) {
+    const { currentValue, defaultValue, envOverride, pending, setting } = options;
     const isDisabled = (envOverride !== undefined) || (setting.disabledReason !== undefined);
     const inputId = setting.path.replaceAll(".", "-");
     const isModified = !isDisabled && !isEqualToDefault(currentValue, defaultValue);
@@ -205,10 +286,11 @@ function generateSettingField(setting, currentValue, defaultValue, envOverride)
     const displayMax = getDisplayMax(setting);
     // Determine if this should be a select dropdown.
     const hasValidValues = setting.validValues && (setting.validValues.length > 0);
-    // Check if this setting depends on a boolean toggle that is currently disabled. The depends-disabled class applies a visual grey-out without actually
-    // disabling the inputs, so values are still submitted during save.
+    // Check if this setting depends on a boolean toggle the saved configuration turns off. The depends-disabled class applies a visual grey-out without actually
+    // disabling the inputs, so values are still submitted during save. The toggle is read from the saved configuration every field renders from, so the grey-out
+    // agrees with the toggle the form shows.
     const dependsOnId = setting.dependsOn ? setting.dependsOn.replaceAll(".", "-") : undefined;
-    const isDependencyDisabled = setting.dependsOn ? !getNestedValue(CONFIG, setting.dependsOn) : false;
+    const isDependencyDisabled = setting.dependsOn ? !getNestedValue(getLoadedConfiguration(), setting.dependsOn) : false;
     // Build CSS classes for the form group.
     const groupClasses = ["form-group"];
     if (isDisabled) {
@@ -232,8 +314,13 @@ function generateSettingField(setting, currentValue, defaultValue, envOverride)
         lines.push("<span class=\"modified-dot\" title=\"Modified from default\"></span>");
     }
     lines.push(escapeHtml(setting.label));
+    // The class badge tells the user when a save of the setting takes effect, before the click. A class whose promise a save already makes carries none.
+    const classBadge = REACTIVITY_BADGES[setting.reactivity];
+    if (classBadge) {
+        lines.push(generateBadge(classBadge.label, { title: classBadge.title, variant: classBadge.variant }));
+    }
     if (envOverride !== undefined) {
-        lines.push("<span class=\"env-badge\">ENV</span>");
+        lines.push(generateBadge("ENV", { variant: "env" }));
     }
     lines.push("</label>");
     // Block-level content that must appear outside the form-row flex container. Type branches that produce content too large for the inline flex layout (grids,
@@ -277,8 +364,8 @@ function generateSettingField(setting, currentValue, defaultValue, envOverride)
         lines.push("</select>");
     }
     else if (setting.type === "boolean") {
-        // Render boolean as a checkbox. A hidden input with value "false" precedes the checkbox so that unchecking submits "false" rather than omitting the field
-        // entirely (which would cause the server to skip it and fall back to the default).
+        // Render boolean as a checkbox. A hidden input with value "false" precedes the checkbox so that unchecking submits "false". Without it an unchecked box
+        // submits nothing, the save handler skips the path, and the merge keeps the saved true, so the uncheck would be lost.
         const isChecked = (currentValue === true) || (currentValue === "true");
         const defaultStr = defaultValue ? "true" : "false";
         lines.push("<input type=\"hidden\" name=\"" + setting.path + "\" value=\"false\">");
@@ -335,9 +422,10 @@ function generateSettingField(setting, currentValue, defaultValue, envOverride)
     else {
         // Render as input field.
         const inputType = (setting.type === "float") ? "number" : (((setting.type === "integer") || (setting.type === "port")) ? "number" : "text");
-        // Calculate step for arrow key increments. Auto-derived from min/displayDivisor: when the min in display units is between 0 and 1 (exclusive), use it as the
-        // step (e.g., 500ms -> 0.5s step); otherwise step is 1 whole display unit. This gives meaningful arrow increments and constrains input to a sensible value
-        // grid (e.g., 0.5, 1.0, 1.5, ... for half-second steps).
+        // Calculate step for arrow key increments. With a displayDivisor and a min, the step is auto-derived: when the min in display units is between 0 and 1
+        // (exclusive), use it as the step (e.g., 500ms -> 0.5s step); otherwise the step is 1 whole display unit. A float with no displayDivisor steps by 0.01 so
+        // two-decimal values stay reachable, and every other number steps by one display unit. This gives meaningful arrow increments and constrains input to a
+        // sensible value grid (e.g., 0.5, 1.0, 1.5, ... for half-second steps).
         let step = "1";
         if (setting.displayDivisor && (setting.min !== undefined)) {
             const displayMin = setting.min / setting.displayDivisor;
@@ -393,35 +481,16 @@ function generateSettingField(setting, currentValue, defaultValue, envOverride)
     for (const content of postDescription) {
         lines.push(content);
     }
+    // Every field carries one marker slot, holding the server's sentence when the saved value is not the running one and hidden otherwise, so a save's response
+    // fills or clears it as text without creating markup.
+    lines.push("<div" + serializeAttrs({ "class": "form-pending" }) + serializeAttrs({ [PENDING_PATH_ATTRIBUTE]: setting.path, hidden: pending === undefined }) +
+        ">" + escapeHtml(pending?.text ?? "") + "</div>");
     // Add disabled reason warning when a setting is locked out due to an upstream issue.
     if (setting.disabledReason) {
         lines.push("<div class=\"form-warning\">" + escapeHtml(setting.disabledReason) + "</div>");
     }
-    // Add default value hint with properly pluralized unit.
-    let defaultDisplay;
-    if (setting.type === "checkboxList") {
-        // For checkbox lists, show the default items as a comma-separated list, or "none" for empty arrays.
-        const defaultArr = Array.isArray(defaultValue) ? defaultValue : [];
-        defaultDisplay = defaultArr.length > 0 ? defaultArr.join(", ") : "none";
-    }
-    else if (displayDefault === null) {
-        defaultDisplay = "autodetect";
-    }
-    else if (typeof displayDefault === "number") {
-        defaultDisplay = formatValueForDisplay(displayDefault, setting.type);
-    }
-    else {
-        defaultDisplay = displayDefault;
-    }
-    // Format the unit with correct pluralization based on the default value.
-    let formattedUnit = "";
-    if (displayUnit && (typeof displayDefault === "number")) {
-        formattedUnit = " " + formatUnitForValue(displayDefault, displayUnit);
-    }
-    else if (displayUnit) {
-        formattedUnit = " " + displayUnit;
-    }
-    lines.push("<div class=\"form-default\">Default: " + escapeHtml(defaultDisplay) + formattedUnit + "</div>");
+    // Add the default value hint, read as the pending markers read a value.
+    lines.push("<div class=\"form-default\">Default: " + escapeHtml(formatSettingValue(defaultValue, setting)) + "</div>");
     // Add env var override notice if applicable.
     if (isDisabled && setting.envVar && envOverride) {
         lines.push("<div class=\"form-env\">Overridden by environment variable: <code>" + escapeHtml(setting.envVar) + "=" +
@@ -449,7 +518,7 @@ function validateSettingValue(setting, value) {
     // Validate string type with validValues.
     if ((setting.type === "string") && setting.validValues && (setting.validValues.length > 0)) {
         if (!setting.validValues.includes(value)) {
-            return setting.label + " must be one of: " + setting.validValues.join(", ");
+            return setting.label + " must be one of: " + setting.validValues.join(", ") + ".";
         }
         return undefined;
     }
@@ -457,7 +526,7 @@ function validateSettingValue(setting, value) {
     switch (setting.type) {
         case "boolean": {
             if (typeof value !== "boolean") {
-                return setting.label + " must be true or false";
+                return setting.label + " must be true or false.";
             }
             return undefined;
         }
@@ -478,35 +547,35 @@ function validateSettingValue(setting, value) {
         case "integer":
         case "port": {
             if (typeof value !== "number") {
-                return setting.label + " must be a number";
+                return setting.label + " must be a number.";
             }
-            const error = validatePositiveInt(setting.label, value, setting.min, setting.max);
+            const error = validateInteger(setting.label, value, setting.min, setting.max);
             return error ?? undefined;
         }
         case "float": {
             if (typeof value !== "number") {
-                return setting.label + " must be a number";
+                return setting.label + " must be a number.";
             }
-            const error = validatePositiveNumber(setting.label, value, setting.min, setting.max);
+            const error = validateNumber(setting.label, value, setting.min, setting.max);
             return error ?? undefined;
         }
         case "host": {
             if ((typeof value !== "string") || (value.trim() === "")) {
-                return setting.label + " must be a non-empty string";
+                return setting.label + " must be a non-empty string.";
             }
             return undefined;
         }
         case "path": {
             // A path is any string. The empty and null forms mean autodetect and were already accepted by the guard at the top.
             if (typeof value !== "string") {
-                return setting.label + " must be a string";
+                return setting.label + " must be a string.";
             }
             return undefined;
         }
         case "string": {
             // A free-form string carries no value constraint beyond being one. Settings that restrict their values declare validValues and were handled above.
             if (typeof value !== "string") {
-                return setting.label + " must be a string";
+                return setting.label + " must be a string.";
             }
             return undefined;
         }
@@ -568,16 +637,34 @@ function parseFormValue(setting, value) {
         }
     }
 }
+/**
+ * Generates the fields of a run of settings, the one per-field loop the Settings tab and every collapsible section share.
+ * @param settings - The settings to render, in order.
+ * @param context - The environment overrides and the pending view the page render resolved once.
+ * @returns One HTML string per field.
+ */
+function generateSettingFields(settings, context) {
+    const defaults = getDefaults();
+    // The form shows the saved configuration, the loaded snapshot, rather than the running one. After a save that holds a change for a restart, a page load shows
+    // that change, so submitting the page cannot post the running value back over it.
+    const saved = getLoadedConfiguration();
+    return settings.map((setting) => generateSettingField({
+        currentValue: getNestedValue(saved, setting.path),
+        defaultValue: getNestedValue(defaults, setting.path),
+        envOverride: context.envOverrides.get(setting.path),
+        pending: context.pending.get(setting.path),
+        setting
+    }));
+}
 /**
  * Generates the content for the Settings tab with non-collapsible section headers.
- * @param envOverrides - The environment overrides the page render resolved once and shares with every section it draws.
+ * @param context - The environment overrides and the pending view the page render resolved once and shares with every section it draws.
  * @returns HTML string for the Settings tab content.
  */
-export function generateSettingsTabContent(envOverrides) {
+export function generateSettingsTabContent(context) {
     const sections = getSettingsTabSections();
     const tabs = getUITabs();
     const settingsTab = tabs.find((t) => t.id === "settings");
-    const defaults = getDefaults();
     const lines = [];
     // Panel header with description and reset button.
     lines.push("<div class=\"panel-header\">");
@@ -590,12 +677,7 @@ export function generateSettingsTabContent(envOverrides) {
         lines.push("<div class=\"settings-section\">");
         lines.push("<div class=\"settings-section-header\">" + escapeHtml(section.displayName) + "</div>");
         // Generate setting fields for this section.
-        for (const setting of section.settings) {
-            const currentValue = getNestedValue(CONFIG, setting.path);
-            const defaultValue = getNestedValue(defaults, setting.path);
-            const envOverride = envOverrides.get(setting.path);
-            lines.push(generateSettingField(setting, currentValue, defaultValue, envOverride));
-        }
+        lines.push(...generateSettingFields(section.settings, context));
         lines.push("</div>");
     }
     return lines.join("\n");
@@ -603,30 +685,28 @@ export function generateSettingsTabContent(envOverrides) {
 /**
  * Generates the content for a collapsible section within the Advanced tab.
  * @param section - The section definition.
- * @param envOverrides - The environment overrides the page render resolved once and shares with every section it draws.
+ * @param context - The environment overrides and the pending view the page render resolved once and shares with every section it draws.
  * @returns HTML string for the section.
  */
-export function generateCollapsibleSection(section, envOverrides) {
-    const defaults = getDefaults();
+export function generateCollapsibleSection(section, context) {
     const lines = [];
-    const settingCount = section.settings.length;
+    /* A section holding a pending setting is opened on the server, so a pending marker is never hidden behind a collapsed header, and nothing on the client has
+     * to remember it. The client's stored section state only ever adds the expanded class, so a section opened here stays open on load.
+     */
+    const expanded = section.settings.some((setting) => context.pending.has(setting.path)) ? " expanded" : "";
     // Section container.
     lines.push("<div class=\"advanced-section\" data-section=\"" + escapeHtml(section.id) + "\">");
     // Section header with chevron, title, and count.
-    lines.push("<div class=\"section-header\" data-click-action=\"" + ACTIONS.toggleSection + "\" data-section-id=\"" + escapeHtml(section.id) + "\">");
+    lines.push("<div class=\"section-header" + expanded + "\" data-click-action=\"" + ACTIONS.toggleSection + "\" data-section-id=\"" + escapeHtml(section.id) +
+        "\">");
     lines.push("<span class=\"section-chevron\">&#9654;</span>");
     lines.push("<span class=\"section-title\">" + escapeHtml(section.displayName) + "</span>");
-    lines.push("<span class=\"section-count\">(" + String(settingCount) + " setting" + (settingCount === 1 ? "" : "s") + ")</span>");
+    lines.push("<span class=\"section-count\">(" + formatSettingCount(section.settings.length) + ")</span>");
     lines.push("</div>");
-    // Section content (collapsed by default).
-    lines.push("<div class=\"section-content\">");
+    // Section content, collapsed unless the section holds a pending setting.
+    lines.push("<div class=\"section-content" + expanded + "\">");
     // Generate setting fields for this section.
-    for (const setting of section.settings) {
-        const currentValue = getNestedValue(CONFIG, setting.path);
-        const defaultValue = getNestedValue(defaults, setting.path);
-        const envOverride = envOverrides.get(setting.path);
-        lines.push(generateSettingField(setting, currentValue, defaultValue, envOverride));
-    }
+    lines.push(...generateSettingFields(section.settings, context));
     // Close section-content, then advanced-section, in reverse order of the opens above.
     lines.push("</div>");
     lines.push("</div>");
@@ -634,10 +714,10 @@ export function generateCollapsibleSection(section, envOverrides) {
 }
 /**
  * Generates the content for the Advanced tab with collapsible sections.
- * @param envOverrides - The environment overrides the page render resolved once and shares with every section it draws.
+ * @param context - The environment overrides and the pending view the page render resolved once and shares with every section it draws.
  * @returns HTML string for the Advanced tab content.
  */
-export function generateAdvancedTabContent(envOverrides) {
+export function generateAdvancedTabContent(context) {
     const sections = getAdvancedSections();
     const tabs = getUITabs();
     const advancedTab = tabs.find((t) => t.id === "advanced");
@@ -650,7 +730,7 @@ export function generateAdvancedTabContent(envOverrides) {
     lines.push("</div>");
     // Generate each collapsible section.
     for (const section of sections) {
-        lines.push(generateCollapsibleSection(section, envOverrides));
+        lines.push(generateCollapsibleSection(section, context));
     }
     return lines.join("\n");
 }
@@ -661,17 +741,37 @@ export function generateAdvancedTabContent(envOverrides) {
 export function generateSettingsFormFooter() {
     return "<div class=\"config-path\">Configuration file: <code>" + escapeHtml(getConfigFilePath()) + "</code></div>";
 }
+/**
+ * The keys that name an object's prototype machinery rather than a setting. A document parsed from JSON carries any of them as an ordinary key, and assigning
+ * through one reaches a prototype instead of the configuration, so the merge refuses each of them at every level it walks.
+ */
+const PROTOTYPE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Refuses a document key that would reach an object's prototype rather than name a setting. The merge runs inside the save's store mutation, so the refusal
+ * writes nothing, and the route answers it as the validation error it is.
+ * @param key - The key the merge is about to assign through.
+ * @throws ConfigurationRejectedError when the key names prototype machinery.
+ */
+function refusePrototypeKey(key) {
+    if (PROTOTYPE_KEYS.has(key)) {
+        throw new ConfigurationRejectedError("The configuration document carries the key " + key + ", which is not a setting.");
+    }
+}
 /**
  * Shallow-merges a source config into a target config. Top-level object values are merged one level deep (preserving sibling keys within each category).
- * Non-object values are assigned directly. This is the single merge strategy used by both the settings form save and config import endpoints.
+ * Non-object values are assigned directly. This is the single merge strategy the settings form save and the config import share. A key that names prototype
+ * machinery, at any level the merge walks, is refused before anything is assigned through it.
  * @param target - The existing config to merge into (modified in place).
  * @param source - The new values to merge.
+ * @throws ConfigurationRejectedError when the source carries a key that is not a setting.
  */
 function mergeConfigValues(target, source) {
     for (const [path, value] of Object.entries(source)) {
+        refusePrototypeKey(path);
         if ((typeof value === "object") && (value !== null) && !Array.isArray(value)) {
             target[path] ??= {};
             for (const [subPath, subValue] of Object.entries(value)) {
+                refusePrototypeKey(subPath);
                 target[path][subPath] = subValue;
             }
         }
@@ -680,6 +780,31 @@ function mergeConfigValues(target, source) {
         }
     }
 }
+/**
+ * Builds the data envelope of a save response from the save's outcome. The settings save and the import share it, so each answers with the same fields: the
+ * restart members the API reference documents, the outcome by setting under changes, and the pending view under pending. changes.applied and
+ * changes.nextStream are everything this save's reconcile realized, a value an earlier save introduced and this save's retry realized included, while
+ * changes.deferred and changes.rejected are this save's own. pending is the whole view after the save, read here once the save has resolved, and the client
+ * replaces its markers from it rather than merging them. Exported so a unit row holds the mapping of every bucket, the next-stream bucket included, which a
+ * route reaches only through a setting of that class.
+ * @param outcome - The save's apply and restart result.
+ * @returns The response data.
+ */
+export function buildSaveResponseData(outcome) {
+    const paths = (changes) => changes.map((change) => change.path);
+    return {
+        activeStreams: outcome.restart?.activeStreams ?? 0,
+        changes: {
+            applied: paths(outcome.apply.applied),
+            deferred: paths(outcome.apply.deferred),
+            nextStream: paths(outcome.apply.nextStream),
+            rejected: outcome.apply.rejected.map(({ change, reason }) => ({ path: change.path, reason }))
+        },
+        deferred: outcome.restart?.deferred ?? false,
+        pending: Array.from(collectPendingSettings().values()),
+        willRestart: outcome.restart?.willRestart ?? false
+    };
+}
 /**
  * Installs all settings-related route handlers on the Express application.
  * @param app - The Express application.
@@ -725,28 +850,15 @@ export function setupSettingsRoutes(app) {
                 sendFormErrors(res, validationErrors);
                 return;
             }
-            // Merge form values into the existing config via mutateConfig. The settings form only manages CONFIG_METADATA fields, but config.json also stores fields
-            // managed by separate endpoints (disabledPredefined, enabledServices, visibleColumns, setupCompleted, channelSortField, channelSortDirection,
-            // channelsDvr.host, hdhr.deviceId, etc.). Merging form values into the existing config preserves all non-form fields automatically - no carry-forward
-            // list to maintain.
-            await mutateConfig((existing) => {
+            // Merge form values into the existing config through the validated save. The settings form only manages CONFIG_METADATA fields, but config.json also
+            // stores fields managed by separate endpoints (disabledPredefined, enabledServices, visibleColumns, setupCompleted, channelSortField,
+            // channelSortDirection, channelsDvr.host, hdhr.deviceId, etc.). Merging form values into the existing config preserves all non-form fields
+            // automatically - no carry-forward list to maintain. The save then reconciles the running configuration against the file: each change takes effect as
+            // its reactivity class allows, and a restart is scheduled only when this save holds a restart-class change for one.
+            const outcome = await applyConfigurationChange("to apply configuration changes", (existing) => {
                 mergeConfigValues(existing, newConfig);
             });
-            // Reload the in-memory CONFIG from the freshly-written disk state and dispatch the diff to registered subsystem handlers. Subsystems that opted in to
-            // live application (HDHR is the first) make their changes immediately; everything else is reported as deferred and triggers a service restart so the
-            // change lands on the next boot.
-            const outcome = await applyConfigurationChange("to apply configuration changes");
-            sendSuccess(res, {
-                data: {
-                    activeStreams: outcome.restart?.activeStreams ?? 0,
-                    appliedCount: outcome.apply.applied.length,
-                    deferred: outcome.restart?.deferred ?? false,
-                    deferredCount: outcome.apply.deferred.length,
-                    rejectedCount: outcome.apply.rejected.length,
-                    willRestart: outcome.restart?.willRestart ?? false
-                },
-                message: describeConfigurationOutcome(outcome)
-            });
+            sendSuccess(res, { data: buildSaveResponseData(outcome), message: describeConfigurationOutcome(outcome) });
         }
         catch (error) {
             sendErrorResponse(res, error, "save configuration");
@@ -814,11 +926,13 @@ export function setupSettingsRoutes(app) {
                 sendValidationError(res, "Validation errors:\n" + validationErrors.join("\n"));
                 return;
             }
-            // Import replaces the user settings layer and preserves the system state layer. CONFIG_METADATA is the SSOT for which fields are user settings
-            // (port, timeouts, quality preset, etc.) vs system state (channelsDvr.host, deviceId, disabledPredefined, enabledServices, etc.). Clearing all
-            // CONFIG_METADATA-tracked paths before merging ensures that settings not present in the import file revert to defaults rather than surviving
-            // from the previous config. System state fields are untouched because they're not in CONFIG_METADATA.
-            await mutateConfig((existing) => {
+            // Import replaces the user settings layer. CONFIG_METADATA is the SSOT for which fields are user settings (port, timeouts, quality preset, etc.) vs
+            // system state (channelsDvr.host, deviceId, disabledPredefined, enabledServices, etc.). Clearing all CONFIG_METADATA-tracked paths before merging
+            // ensures that settings not present in the import file revert to defaults rather than surviving from the previous config. The merge then copies every
+            // key the document carries, so a system-state field missing from the document keeps its current value, while one present in the document - as in a
+            // file written by the export, which carries the whole configuration - is merged over the current one. The save validates the result before anything
+            // reaches disk and reconciles the running configuration against it, the same path every write to the settings takes.
+            const outcome = await applyConfigurationChange("after configuration import", (existing) => {
                 // Clear all user settings from the existing config, leaving only system state.
                 for (const settings of Object.values(CONFIG_METADATA)) {
                     for (const setting of settings) {
@@ -835,20 +949,7 @@ export function setupSettingsRoutes(app) {
                 // Apply imported settings on top of the preserved system state.
                 mergeConfigValues(existing, importedConfig);
             });
-            // Reload and dispatch the diff. Import frequently changes more fields at once than the form save flow, so a higher fraction of imports will land in the
-            // "restart required" path - but the same live-apply machinery still picks off any subsystem that opted in.
-            const outcome = await applyConfigurationChange("after configuration import");
-            sendSuccess(res, {
-                data: {
-                    activeStreams: outcome.restart?.activeStreams ?? 0,
-                    appliedCount: outcome.apply.applied.length,
-                    deferred: outcome.restart?.deferred ?? false,
-                    deferredCount: outcome.apply.deferred.length,
-                    rejectedCount: outcome.apply.rejected.length,
-                    willRestart: outcome.restart?.willRestart ?? false
-                },
-                message: describeConfigurationOutcome(outcome)
-            });
+            sendSuccess(res, { data: buildSaveResponseData(outcome), message: describeConfigurationOutcome(outcome) });
         }
         catch (error) {
             sendErrorResponse(res, error, "import configuration");
@@ -864,7 +965,7 @@ export function setupSettingsRoutes(app) {
         sendSuccess(res, { message: "Server is restarting..." });
         // Close the browser first to avoid orphan Chrome processes. The delay gives the success response above time to
         // reach the client before the process exits.
-        setTimeout(() => {
+        systemClock.schedule(() => {
             LOG.info("Exiting for forced service manager restart.");
             void import("../../browser/index.js").then(async (mod) => mod.closeBrowser()).then(() => { process.exit(0); }).catch(() => { process.exit(1); });
         }, 500);