feat(macos): configuration window + curl-backed macOS updater (#71)

app-updater.js

@@ -0,0 +1,193 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMacAppBundlePath = resolveMacAppBundlePath;
+exports.isMacApplicationsFolderBundle = isMacApplicationsFolderBundle;
+exports.isKnownLinuxPackageManagedAppImage = isKnownLinuxPackageManagedAppImage;
+exports.isNativeUpdaterSupported = isNativeUpdaterSupported;
+exports.configureAutoUpdater = configureAutoUpdater;
+exports.createElectronAppUpdater = createElectronAppUpdater;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_util_1 = require("node:util");
+const electron_updater_1 = require("electron-updater");
+const release_assets_1 = require("./release-assets");
+const updaterErrorListeners = new WeakMap();
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function resolveMacAppBundlePath(execPath) {
+    const marker = '.app/Contents/MacOS/';
+    const markerIndex = execPath.indexOf(marker);
+    if (markerIndex < 0)
+        return null;
+    return execPath.slice(0, markerIndex + '.app'.length);
+}
+async function readMacCodeSignature(appBundlePath) {
+    try {
+        const result = await execFileAsync('/usr/bin/codesign', ['-dv', '--verbose=4', appBundlePath], {
+            encoding: 'utf8',
+        });
+        return `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+    }
+    catch {
+        return null;
+    }
+}
+function realpathOrOriginal(filePath) {
+    try {
+        return (0, node_fs_1.realpathSync)(filePath);
+    }
+    catch {
+        return filePath;
+    }
+}
+function isSameOrInsideDirectory(parentPath, candidatePath) {
+    const relative = node_path_1.default.relative(parentPath, candidatePath);
+    return (relative === '' ||
+        (relative.length > 0 && !relative.startsWith('..') && !node_path_1.default.isAbsolute(relative)));
+}
+function isMacApplicationsFolderBundle(appBundlePath, homeDir = node_os_1.default.homedir()) {
+    const resolvedBundlePath = node_path_1.default.resolve(appBundlePath);
+    return (isSameOrInsideDirectory('/Applications', resolvedBundlePath) ||
+        isSameOrInsideDirectory(node_path_1.default.join(homeDir, 'Applications'), resolvedBundlePath));
+}
+function isKnownLinuxPackageManagedAppImage(appImagePath) {
+    return realpathOrOriginal(appImagePath) === '/opt/SubMiner/SubMiner.AppImage';
+}
+async function isNativeUpdaterSupported(options) {
+    if (!options.isPackaged) {
+        options.log?.('Skipping native updater because this build is not packaged.');
+        return false;
+    }
+    if (options.platform === 'linux') {
+        options.log?.('Skipping native Linux updater because Linux tray checks use GitHub release assets.');
+        return false;
+    }
+    if (options.platform !== 'darwin') {
+        options.log?.('Skipping native updater because this platform uses GitHub metadata checks.');
+        return false;
+    }
+    const appBundlePath = resolveMacAppBundlePath(options.execPath);
+    if (!appBundlePath) {
+        options.log?.('Skipping native macOS updater because the app bundle path could not be resolved.');
+        return false;
+    }
+    if (!isMacApplicationsFolderBundle(appBundlePath, options.homeDir)) {
+        options.log?.('Skipping native macOS updater because the app is not installed in an Applications folder.');
+        return false;
+    }
+    const signature = await (options.readCodeSignature ?? readMacCodeSignature)(appBundlePath);
+    if (!signature) {
+        options.log?.('Skipping native macOS updater because the app code signature could not be read.');
+        return false;
+    }
+    if (/Signature=adhoc\b/.test(signature) || /TeamIdentifier=not set\b/.test(signature)) {
+        options.log?.('Skipping native macOS updater because this build is ad-hoc signed.');
+        return false;
+    }
+    return true;
+}
+function configureAutoUpdater(updater, log = () => { }, channel = 'stable') {
+    updater.autoDownload = false;
+    // On macOS this avoids invoking Squirrel until the explicit restart/install step.
+    updater.autoInstallOnAppQuit = false;
+    updater.allowPrerelease = channel === 'prerelease';
+    updater.allowDowngrade = false;
+    updater.logger = {
+        info: () => { },
+        debug: () => { },
+        warn: (message) => log(message),
+        error: (message) => log(message),
+    };
+    const previousErrorListener = updaterErrorListeners.get(updater);
+    if (previousErrorListener) {
+        if (updater.off) {
+            updater.off('error', previousErrorListener);
+        }
+        else {
+            updater.removeListener?.('error', previousErrorListener);
+        }
+    }
+    if (updater.on) {
+        const errorListener = (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            log(`Updater error event: ${message}`);
+        };
+        updater.on('error', errorListener);
+        updaterErrorListeners.set(updater, errorListener);
+    }
+    return updater;
+}
+function createElectronAppUpdater(options) {
+    const getChannel = options.getChannel ?? (() => 'stable');
+    const updater = configureAutoUpdater(options.updater ?? electron_updater_1.autoUpdater, options.log, getChannel());
+    if (options.configureHttpExecutor) {
+        // electron-updater has no public executor hook; keep the macOS cURL override localized.
+        updater.httpExecutor = options.configureHttpExecutor();
+    }
+    if (options.disableDifferentialDownload !== undefined) {
+        updater.disableDifferentialDownload = options.disableDifferentialDownload;
+    }
+    let nativeUpdaterSupported = null;
+    async function getNativeUpdaterSupported() {
+        if (!options.isNativeUpdaterSupported)
+            return true;
+        if (nativeUpdaterSupported === null) {
+            nativeUpdaterSupported = Promise.resolve(options.isNativeUpdaterSupported());
+        }
+        return nativeUpdaterSupported;
+    }
+    return {
+        async checkForUpdates(channel) {
+            if (!options.isPackaged) {
+                return {
+                    available: false,
+                    version: options.currentVersion,
+                    canUpdate: false,
+                };
+            }
+            if (!(await getNativeUpdaterSupported())) {
+                options.log('Skipping native app update check because native updater is unsupported.');
+                return {
+                    available: false,
+                    version: options.currentVersion,
+                    canUpdate: false,
+                };
+            }
+            configureAutoUpdater(updater, options.log, channel ?? getChannel());
+            const result = await updater.checkForUpdates();
+            const version = result?.updateInfo?.version ?? options.currentVersion;
+            return {
+                available: (0, release_assets_1.compareSemverLike)(version, options.currentVersion) > 0,
+                version,
+                canUpdate: true,
+            };
+        },
+        async downloadUpdate() {
+            if (!options.isPackaged) {
+                options.log('Skipping app update download because this build is not packaged.');
+                return;
+            }
+            if (!(await getNativeUpdaterSupported())) {
+                options.log('Skipping app update download because native updater is unsupported.');
+                return;
+            }
+            await updater.downloadUpdate();
+        },
+        async quitAndInstall() {
+            if (!options.isPackaged) {
+                options.log('Skipping app update install because this build is not packaged.');
+                return;
+            }
+            if (!(await getNativeUpdaterSupported())) {
+                options.log('Skipping app update install because native updater is unsupported.');
+                return;
+            }
+            updater.quitAndInstall(false, true);
+        },
+    };
+}
+//# sourceMappingURL=app-updater.js.map

backlog/drafts/config-settings-window.md

@@ -0,0 +1,15 @@
+# Config Settings Window
+
+Status: draft
+Owner: Kyle Yasuda
+Created: 2026-05-17
+
+## Goal
+
+Add a dedicated configuration window that groups settings by user workflow while saving back to the existing `config.jsonc` paths.
+
+## Notes
+
+- Full current config surface, excluding legacy/ignored compatibility keys.
+- Preserve JSONC comments/formatting when saving.
+- Surface hot-reload vs restart-required results.

bun.lock

@@ -15,6 +15,7 @@
         "jsonc-parser": "^3.3.1",
         "koffi": "^2.15.6",
         "libsql": "^0.5.22",
+        "vscode-json-languageservice": "^5.7.2",
         "ws": "^8.19.0",
       },
       "devDependencies": {
@@ -188,6 +189,8 @@
 
     "@vladfrangu/async_event_emitter": ["@vladfrangu/async_event_emitter@2.4.7", "", {}, "sha512-Xfe6rpCTxSxfbswi/W/Pz7zp1WWSNn4A0eW4mLkQUewCrXXtMj31lCg+iQyTkh/CkusZSq9eDflu7tjEDXUY6g=="],
 
+    "@vscode/l10n": ["@vscode/l10n@0.0.18", "", {}, "sha512-KYSIHVmslkaCDyw013pphY+d7x1qV8IZupYfeIfzNA+nsaWHbn5uPuQRvdRFsa9zFzGeudPuoGoZ1Op4jrJXIQ=="],
+
     "@xhayper/discord-rpc": ["@xhayper/discord-rpc@1.3.3", "", { "dependencies": { "@discordjs/rest": "^2.6.1", "@vladfrangu/async_event_emitter": "^2.4.7", "discord-api-types": "^0.38.42", "ws": "^8.20.0" } }, "sha512-Ih48GHiua7TtZgKO+f0uZPhCeQqb84fY2qUys/oMh8UbUfiUkUJLVCmd/v2AK0/pV33euh0aqSXo7+9LiPSwGw=="],
 
     "@xmldom/xmldom": ["@xmldom/xmldom@0.8.12", "", {}, "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg=="],
@@ -722,6 +725,14 @@
 
     "verror": ["verror@1.10.1", "", { "dependencies": { "assert-plus": "^1.0.0", "core-util-is": "1.0.2", "extsprintf": "^1.2.0" } }, "sha512-veufcmxri4e3XSrT0xwfUR7kguIkaxBeosDg00yDWhk49wdwkSUrvvsm7nc75e1PUyvIeZj6nS8VQRYz2/S4Xg=="],
 
+    "vscode-json-languageservice": ["vscode-json-languageservice@5.7.2", "", { "dependencies": { "@vscode/l10n": "^0.0.18", "jsonc-parser": "^3.3.1", "vscode-languageserver-textdocument": "^1.0.12", "vscode-languageserver-types": "^3.17.5", "vscode-uri": "^3.1.0" } }, "sha512-WtKRDtJfFEmLrgtu+ODexOHm/6/krRF0k6t+uvkKIKW1Jh9ZIyxZQwJJwB3qhrEgvAxa37zbUg+vn+UyUK/U2w=="],
+
+    "vscode-languageserver-textdocument": ["vscode-languageserver-textdocument@1.0.12", "", {}, "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA=="],
+
+    "vscode-languageserver-types": ["vscode-languageserver-types@3.17.5", "", {}, "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg=="],
+
+    "vscode-uri": ["vscode-uri@3.1.0", "", {}, "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ=="],
+
     "wcwidth": ["wcwidth@1.0.1", "", { "dependencies": { "defaults": "^1.0.3" } }, "sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg=="],
 
     "which": ["which@5.0.0", "", { "dependencies": { "isexe": "^3.1.1" }, "bin": { "node-which": "bin/which.js" } }, "sha512-JEdGzHwwkrbWoGOlIHqQ5gtprKGOenpDHpxE9zVR1bWbOtYRyPPHMe9FaP6x61CmNaTThSkb0DAJte5jD+DmzQ=="],

changes/config-settings-window.md

@@ -0,0 +1,6 @@
+type: added
+area: config
+
+- Added a dedicated Configuration window with launcher entry points via `subminer --config` and `subminer config`.
+- Fixed the Configuration window preload so launcher-opened windows can initialize even when Electron sandboxing is active.
+- Kept config-window startup lightweight by skipping AniList token refresh and automatic update polling.

changes/native-updater-crash.md

@@ -1,4 +1,6 @@
 type: fixed
 area: updates
 
-- Kept signed macOS app updates on the native updater path while preventing eager Squirrel install checks before the user confirms restart.
+- Restored the standard macOS `electron-updater`/Squirrel update path and routed supplemental GitHub updater requests through Electron networking instead of Node fetch.
+- macOS update checks now skip local build-output apps outside Applications before touching Squirrel, and macOS tray checks no longer perform the supplemental GitHub asset lookup.
+- macOS `electron-updater` metadata and full ZIP downloads now use `/usr/bin/curl` under the hood to avoid the Electron network crash seen during tray update checks while preserving Squirrel installation.

config.example.jsonc

@@ -10,7 +10,7 @@
   // Overlay Auto-Start
   // When overlay connects to mpv, automatically show overlay and hide mpv subtitles.
   // ==========================================
-  "auto_start_overlay": false, // When overlay connects to mpv, automatically show overlay and hide mpv subtitles. Values: true | false
+  "auto_start_overlay": false, // Auto-start the subtitle overlay window when SubMiner launches. Values: true | false
 
   // ==========================================
   // Texthooker Server
@@ -18,7 +18,7 @@
   // ==========================================
   "texthooker": {
     "launchAtStartup": false, // Launch texthooker server automatically when SubMiner starts. Values: true | false
-    "openBrowser": false // Open browser setting. Values: true | false
+    "openBrowser": false // Open the texthooker page in the default browser when the server starts. Values: true | false
   }, // Configure texthooker startup launch and browser opening behavior.
 
   // ==========================================
@@ -174,24 +174,24 @@
   // Hot-reload: shortcut changes apply live and update the session help modal on reopen.
   // ==========================================
   "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Toggle visible overlay global setting.
-    "copySubtitle": "CommandOrControl+C", // Copy subtitle setting.
-    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Copy subtitle multiple setting.
-    "updateLastCardFromClipboard": "CommandOrControl+V", // Update last card from clipboard setting.
-    "triggerFieldGrouping": "CommandOrControl+G", // Trigger field grouping setting.
-    "triggerSubsync": "Ctrl+Alt+S", // Trigger subsync setting.
-    "mineSentence": "CommandOrControl+S", // Mine sentence setting.
-    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Mine sentence multiple setting.
+    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.
+    "copySubtitle": "CommandOrControl+C", // Accelerator that copies the current subtitle line to the clipboard.
+    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.
+    "updateLastCardFromClipboard": "CommandOrControl+V", // Accelerator that updates the last mined Anki card using the current clipboard contents.
+    "triggerFieldGrouping": "CommandOrControl+G", // Accelerator that triggers Kiku field grouping on duplicate cards.
+    "triggerSubsync": "Ctrl+Alt+S", // Accelerator that triggers subsync against the active subtitle file.
+    "mineSentence": "CommandOrControl+S", // Accelerator that mines the current sentence as a new Anki card.
+    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Accelerator that mines consecutive sentences while the multi-mine window stays open.
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
-    "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
-    "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
-    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
-    "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
-    "openSessionHelp": "CommandOrControl+Slash", // Open session help setting.
-    "openControllerSelect": "Alt+C", // Open controller select setting.
-    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
-    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
+    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
+    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Accelerator that opens the character dictionary modal.
+    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
+    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
+    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
+    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
+    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
+    "toggleSubtitleSidebar": "Backslash" // Accelerator that toggles the subtitle sidebar visibility.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
@@ -328,9 +328,9 @@
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
-    "secondarySubLanguages": [], // Secondary sub languages setting.
-    "autoLoadSecondarySub": false, // Auto load secondary sub setting. Values: true | false
-    "defaultMode": "hover" // Default mode setting.
+    "secondarySubLanguages": [], // Language code priority list used to auto-select a secondary subtitle track when available.
+    "autoLoadSecondarySub": false, // Automatically load a matching secondary subtitle when the primary subtitle loads. Values: true | false
+    "defaultMode": "hover" // Default visibility mode for the secondary subtitle bar. Values: hidden | visible | hover
   }, // Dual subtitle track options.
 
   // ==========================================
@@ -339,9 +339,9 @@
   // ==========================================
   "subsync": {
     "defaultMode": "auto", // Subsync default mode. Values: auto | manual
-    "alass_path": "", // Alass path setting.
-    "ffsubsync_path": "", // Ffsubsync path setting.
-    "ffmpeg_path": "", // Ffmpeg path setting.
+    "alass_path": "", // Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffsubsync_path": "", // Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffmpeg_path": "", // Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.
     "replace": true // Replace the active subtitle file when sync completes. Values: true | false
   }, // Subsync engine and executable paths.
 
@@ -350,7 +350,7 @@
   // Initial vertical subtitle position from the bottom.
   // ==========================================
   "subtitlePosition": {
-    "yPercent": 10 // Y percent setting.
+    "yPercent": 10 // Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.
   }, // Initial vertical subtitle position from the bottom.
 
   // ==========================================
@@ -454,9 +454,9 @@
     "enabled": false, // Enable shared OpenAI-compatible AI provider features. Values: true | false
     "apiKey": "", // Static API key for the shared OpenAI-compatible AI provider.
     "apiKeyCommand": "", // Shell command used to resolve the shared AI provider API key.
-    "model": "openai/gpt-4o-mini", // Model setting.
+    "model": "openai/gpt-4o-mini", // Default model identifier requested from the shared AI provider.
     "baseUrl": "https://openrouter.ai/api", // Base URL for the shared OpenAI-compatible AI provider.
-    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // System prompt setting.
+    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // Default system prompt sent with shared AI provider requests.
     "requestTimeoutMs": 15000 // Timeout in milliseconds for shared AI provider requests.
   }, // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
 
@@ -469,7 +469,7 @@
   // ==========================================
   "ankiConnect": {
     "enabled": true, // Enable AnkiConnect integration. Values: true | false
-    "url": "http://127.0.0.1:8765", // Url setting.
+    "url": "http://127.0.0.1:8765", // Base URL of the AnkiConnect HTTP server.
     "pollingRate": 3000, // Polling interval in milliseconds.
     "proxy": {
       "enabled": true, // Enable local AnkiConnect-compatible proxy for push-based auto-enrichment. Values: true | false
@@ -482,11 +482,11 @@
     ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
-      "audio": "ExpressionAudio", // Audio setting.
-      "image": "Picture", // Image setting.
-      "sentence": "Sentence", // Sentence setting.
-      "miscInfo": "MiscInfo", // Misc info setting.
-      "translation": "SelectionText" // Translation setting.
+      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "image": "Picture", // Card field that receives the captured screenshot or animated image.
+      "sentence": "Sentence", // Card field that receives the source sentence text.
+      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
+      "translation": "SelectionText" // Card field that receives the current selection or translated text.
     }, // Fields setting.
     "ai": {
       "enabled": false, // Enable AI provider usage for Anki translation/enrichment flows. Values: true | false
@@ -494,18 +494,18 @@
       "systemPrompt": "" // Optional system prompt override for Anki AI translation/enrichment flows.
     }, // Ai setting.
     "media": {
-      "generateAudio": true, // Generate audio setting. Values: true | false
-      "generateImage": true, // Generate image setting. Values: true | false
-      "imageType": "static", // Image type setting.
-      "imageFormat": "jpg", // Image format setting.
-      "imageQuality": 92, // Image quality setting.
-      "animatedFps": 10, // Animated fps setting.
-      "animatedMaxWidth": 640, // Animated max width setting.
-      "animatedCrf": 35, // Animated crf setting.
+      "generateAudio": true, // Generate sentence audio for mined cards. Values: true | false
+      "generateImage": true, // Generate screenshot or animated image for mined cards. Values: true | false
+      "imageType": "static", // Image capture type: "static" for a single still frame, "avif" for an animated AVIF. Values: static | avif
+      "imageFormat": "jpg", // Encoding format used when imageType is "static". Values: jpg | png | webp
+      "imageQuality": 92, // Quality (0-100) used for lossy static image encoders.
+      "animatedFps": 10, // Target frame rate for animated AVIF captures.
+      "animatedMaxWidth": 640, // Maximum width applied to animated AVIF captures.
+      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
-      "audioPadding": 0.5, // Audio padding setting.
-      "fallbackDuration": 3, // Fallback duration setting.
-      "maxMediaDuration": 30 // Max media duration setting.
+      "audioPadding": 0.5, // Seconds of padding appended to both ends of generated sentence audio.
+      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -516,11 +516,11 @@
       "color": "#a6da95" // Color used for known-word highlights.
     }, // Known words setting.
     "behavior": {
-      "overwriteAudio": true, // Overwrite audio setting. Values: true | false
-      "overwriteImage": true, // Overwrite image setting. Values: true | false
-      "mediaInsertMode": "append", // Media insert mode setting.
-      "highlightWord": true, // Highlight word setting. Values: true | false
-      "notificationType": "osd", // Notification type setting.
+      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
+      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
+      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
+      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
+      "notificationType": "osd", // Notification surface used to announce mining and update outcomes. Values: osd | system | both | none
       "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
     }, // Behavior setting.
     "nPlusOne": {
@@ -528,16 +528,16 @@
       "nPlusOne": "#c6a0f6" // Color used for the single N+1 target token highlight.
     }, // N plus one setting.
     "metadata": {
-      "pattern": "[SubMiner] %f (%t)" // Pattern setting.
+      "pattern": "[SubMiner] %f (%t)" // Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).
     }, // Metadata setting.
     "isLapis": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "sentenceCardModel": "Japanese sentences" // Sentence card model setting.
+      "enabled": false, // Enable Lapis-specific mining behaviors and sentence card model targeting. Values: true | false
+      "sentenceCardModel": "Japanese sentences" // Note type name used by Lapis sentence cards.
     }, // Is lapis setting.
     "isKiku": {
-      "enabled": false, // Enabled setting. Values: true | false
+      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
-      "deleteDuplicateInAuto": true // Delete duplicate in auto setting. Values: true | false
+      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     } // Is kiku setting.
   }, // Automatic Anki updates and media generation options.
 
@@ -546,7 +546,7 @@
   // Jimaku API configuration and defaults.
   // ==========================================
   "jimaku": {
-    "apiBaseUrl": "https://jimaku.cc", // Api base url setting.
+    "apiBaseUrl": "https://jimaku.cc", // Base URL of the Jimaku subtitle search API.
     "languagePreference": "ja", // Preferred language used in Jimaku search. Values: ja | en | none
     "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
@@ -618,9 +618,9 @@
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
     "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Device id setting.
-    "clientName": "SubMiner", // Client name setting.
-    "clientVersion": "0.1.0", // Client version setting.
+    "deviceId": "subminer", // Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.
+    "clientName": "SubMiner", // Client name sent on the Jellyfin authentication handshake; primarily internal.
+    "clientVersion": "0.1.0", // Client version sent on the Jellyfin authentication handshake; primarily internal.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false

docs-site/configuration.md

@@ -59,6 +59,28 @@ For valid JSON/JSONC with invalid option values, SubMiner uses warn-and-fallback
 
 On macOS, these validation warnings also open a native dialog with full details (desktop notification banners can truncate long messages).
 
+### Configuration Window
+
+SubMiner also includes a dedicated **Configuration** window from the tray menu, the app `--config` flag, or launcher commands such as `subminer --config` and `subminer config`. It groups settings by workflow instead of mirroring the raw config-file shape:
+
+- Viewing
+- Mining & Anki
+- Playback & Sources
+- Input
+- Integrations
+- Tracking & App
+- Advanced
+
+Each field still writes to its current `config.jsonc` path. For example, subtitle hover pause appears under **Viewing** / playback behavior, but saves to `subtitleStyle.autoPauseVideoOnHover`.
+
+The settings window preserves existing JSONC comments, trailing commas, unrelated keys, and unsupported legacy options. Resetting a field removes the explicit config path so the built-in default applies.
+
+Secret fields do not display stored values. They show whether a value is configured; entering a new value writes it, and reset clears the explicit path. Prefer command-based secret options such as `ai.apiKeyCommand` when available.
+
+Some compatibility-only or ignored legacy keys are intentionally hidden from the normal field list, including legacy top-level Anki migration fields, old N+1 aliases, the removed YouTube subtitle-generation primary-language key, `anilist.characterDictionary.refreshTtlHours`, `anilist.characterDictionary.evictionPolicy`, `jellyfin.accessToken`, `jellyfin.userId`, and normal editing for `controller.buttonIndices`. Advanced/raw JSON editing remains the escape hatch for unsupported or legacy keys.
+
+Saving validates the candidate config before writing. Live-reloadable changes are applied immediately; other changes return a restart-required banner in the window.
+
 ### Hot-Reload Behavior
 
 SubMiner watches the active config file (`config.jsonc` or `config.json`) while running and applies supported updates automatically.
@@ -1229,7 +1251,7 @@ Jellyfin integration is optional and disabled by default. When enabled, SubMiner
 | `directPlayContainers`     | string[]        | Container allowlist for direct play decisions                                                                |
 | `transcodeVideoCodec`      | string          | Preferred transcode video codec fallback (default: `h264`)                                                   |
 
-Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup.
+Jellyfin auth session (`accessToken` + `userId`) is stored in local encrypted storage after login/setup. The legacy `jellyfin.accessToken` and `jellyfin.userId` config keys are not resolver-backed settings in the current runtime and are hidden from the configuration window.
 
 - On Linux, token storage defaults to `gnome-libsecret` for `safeStorage`. Override with `--password-store=<backend>` on launcher/app invocations when needed.
 

docs-site/installation.md

@@ -174,9 +174,9 @@ subminer -u
 subminer --update
 ```
 
-SubMiner verifies launcher and Linux rofi theme downloads against `SHA256SUMS.txt`. If the launcher is installed in a protected path such as `/usr/local/bin/subminer`, SubMiner does not elevate itself; it shows the exact `sudo curl ... && sudo chmod +x ...` command to run instead.
+SubMiner verifies AppImage, launcher, and Linux rofi theme downloads against `SHA256SUMS.txt`. If the AppImage or launcher is installed in a protected path, SubMiner does not elevate itself; it shows the exact sudo command to run instead.
 
-On Linux, `subminer -u` performs this update from the launcher process, so it does not need to start or IPC into the tray app.
+On Linux, `subminer -u` performs the AppImage update from the launcher process, so it does not need to start or IPC into the tray app.
 
 ### From Source
 
@@ -206,6 +206,8 @@ Download the **DMG** artifact from [GitHub Releases](https://github.com/ksyasuda
 
 A **ZIP** artifact is also available as a fallback — unzip and drag `SubMiner.app` into `/Applications`.
 
+After the first updater-enabled install, tray update checks can update the macOS app automatically through Electron's standard macOS updater. The updater uses the release ZIP as its payload even when the DMG remains the normal first-install artifact.
+
 Install dependencies using Homebrew:
 
 ```bash

docs-site/public/config.example.jsonc

@@ -10,7 +10,7 @@
   // Overlay Auto-Start
   // When overlay connects to mpv, automatically show overlay and hide mpv subtitles.
   // ==========================================
-  "auto_start_overlay": false, // When overlay connects to mpv, automatically show overlay and hide mpv subtitles. Values: true | false
+  "auto_start_overlay": false, // Auto-start the subtitle overlay window when SubMiner launches. Values: true | false
 
   // ==========================================
   // Texthooker Server
@@ -18,7 +18,7 @@
   // ==========================================
   "texthooker": {
     "launchAtStartup": false, // Launch texthooker server automatically when SubMiner starts. Values: true | false
-    "openBrowser": false // Open browser setting. Values: true | false
+    "openBrowser": false // Open the texthooker page in the default browser when the server starts. Values: true | false
   }, // Configure texthooker startup launch and browser opening behavior.
 
   // ==========================================
@@ -174,24 +174,24 @@
   // Hot-reload: shortcut changes apply live and update the session help modal on reopen.
   // ==========================================
   "shortcuts": {
-    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Toggle visible overlay global setting.
-    "copySubtitle": "CommandOrControl+C", // Copy subtitle setting.
-    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Copy subtitle multiple setting.
-    "updateLastCardFromClipboard": "CommandOrControl+V", // Update last card from clipboard setting.
-    "triggerFieldGrouping": "CommandOrControl+G", // Trigger field grouping setting.
-    "triggerSubsync": "Ctrl+Alt+S", // Trigger subsync setting.
-    "mineSentence": "CommandOrControl+S", // Mine sentence setting.
-    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Mine sentence multiple setting.
+    "toggleVisibleOverlayGlobal": "Alt+Shift+O", // Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.
+    "copySubtitle": "CommandOrControl+C", // Accelerator that copies the current subtitle line to the clipboard.
+    "copySubtitleMultiple": "CommandOrControl+Shift+C", // Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.
+    "updateLastCardFromClipboard": "CommandOrControl+V", // Accelerator that updates the last mined Anki card using the current clipboard contents.
+    "triggerFieldGrouping": "CommandOrControl+G", // Accelerator that triggers Kiku field grouping on duplicate cards.
+    "triggerSubsync": "Ctrl+Alt+S", // Accelerator that triggers subsync against the active subtitle file.
+    "mineSentence": "CommandOrControl+S", // Accelerator that mines the current sentence as a new Anki card.
+    "mineSentenceMultiple": "CommandOrControl+Shift+S", // Accelerator that mines consecutive sentences while the multi-mine window stays open.
     "multiCopyTimeoutMs": 3000, // Timeout for multi-copy/mine modes.
-    "toggleSecondarySub": "CommandOrControl+Shift+V", // Toggle secondary sub setting.
-    "markAudioCard": "CommandOrControl+Shift+A", // Mark audio card setting.
-    "openCharacterDictionary": "CommandOrControl+Alt+A", // Open character dictionary setting.
-    "openRuntimeOptions": "CommandOrControl+Shift+O", // Open runtime options setting.
-    "openJimaku": "Ctrl+Shift+J", // Open jimaku setting.
-    "openSessionHelp": "CommandOrControl+Slash", // Open session help setting.
-    "openControllerSelect": "Alt+C", // Open controller select setting.
-    "openControllerDebug": "Alt+Shift+C", // Open controller debug setting.
-    "toggleSubtitleSidebar": "Backslash" // Toggle subtitle sidebar setting.
+    "toggleSecondarySub": "CommandOrControl+Shift+V", // Accelerator that toggles the secondary subtitle bar visibility.
+    "markAudioCard": "CommandOrControl+Shift+A", // Accelerator that marks the last mined card as an audio card.
+    "openCharacterDictionary": "CommandOrControl+Alt+A", // Accelerator that opens the character dictionary modal.
+    "openRuntimeOptions": "CommandOrControl+Shift+O", // Accelerator that opens the runtime options modal.
+    "openJimaku": "Ctrl+Shift+J", // Accelerator that opens the Jimaku subtitle search modal.
+    "openSessionHelp": "CommandOrControl+Slash", // Accelerator that opens the session help / keybinding cheatsheet.
+    "openControllerSelect": "Alt+C", // Accelerator that opens the controller selection and learn-mode modal.
+    "openControllerDebug": "Alt+Shift+C", // Accelerator that opens the controller debug modal with live axis/button readouts.
+    "toggleSubtitleSidebar": "Backslash" // Accelerator that toggles the subtitle sidebar visibility.
   }, // Overlay keyboard shortcuts. Set a shortcut to null to disable.
 
   // ==========================================
@@ -328,9 +328,9 @@
   // Hot-reload: defaultMode updates live while SubMiner is running.
   // ==========================================
   "secondarySub": {
-    "secondarySubLanguages": [], // Secondary sub languages setting.
-    "autoLoadSecondarySub": false, // Auto load secondary sub setting. Values: true | false
-    "defaultMode": "hover" // Default mode setting.
+    "secondarySubLanguages": [], // Language code priority list used to auto-select a secondary subtitle track when available.
+    "autoLoadSecondarySub": false, // Automatically load a matching secondary subtitle when the primary subtitle loads. Values: true | false
+    "defaultMode": "hover" // Default visibility mode for the secondary subtitle bar. Values: hidden | visible | hover
   }, // Dual subtitle track options.
 
   // ==========================================
@@ -339,9 +339,9 @@
   // ==========================================
   "subsync": {
     "defaultMode": "auto", // Subsync default mode. Values: auto | manual
-    "alass_path": "", // Alass path setting.
-    "ffsubsync_path": "", // Ffsubsync path setting.
-    "ffmpeg_path": "", // Ffmpeg path setting.
+    "alass_path": "", // Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffsubsync_path": "", // Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.
+    "ffmpeg_path": "", // Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.
     "replace": true // Replace the active subtitle file when sync completes. Values: true | false
   }, // Subsync engine and executable paths.
 
@@ -350,7 +350,7 @@
   // Initial vertical subtitle position from the bottom.
   // ==========================================
   "subtitlePosition": {
-    "yPercent": 10 // Y percent setting.
+    "yPercent": 10 // Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.
   }, // Initial vertical subtitle position from the bottom.
 
   // ==========================================
@@ -454,9 +454,9 @@
     "enabled": false, // Enable shared OpenAI-compatible AI provider features. Values: true | false
     "apiKey": "", // Static API key for the shared OpenAI-compatible AI provider.
     "apiKeyCommand": "", // Shell command used to resolve the shared AI provider API key.
-    "model": "openai/gpt-4o-mini", // Model setting.
+    "model": "openai/gpt-4o-mini", // Default model identifier requested from the shared AI provider.
     "baseUrl": "https://openrouter.ai/api", // Base URL for the shared OpenAI-compatible AI provider.
-    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // System prompt setting.
+    "systemPrompt": "You are a translation engine. Return only the translated text with no explanations.", // Default system prompt sent with shared AI provider requests.
     "requestTimeoutMs": 15000 // Timeout in milliseconds for shared AI provider requests.
   }, // Canonical OpenAI-compatible provider transport settings shared by Anki and YouTube subtitle fixing.
 
@@ -469,7 +469,7 @@
   // ==========================================
   "ankiConnect": {
     "enabled": true, // Enable AnkiConnect integration. Values: true | false
-    "url": "http://127.0.0.1:8765", // Url setting.
+    "url": "http://127.0.0.1:8765", // Base URL of the AnkiConnect HTTP server.
     "pollingRate": 3000, // Polling interval in milliseconds.
     "proxy": {
       "enabled": true, // Enable local AnkiConnect-compatible proxy for push-based auto-enrichment. Values: true | false
@@ -482,11 +482,11 @@
     ], // Tags to add to cards mined or updated by SubMiner. Provide an empty array to disable automatic tagging.
     "fields": {
       "word": "Expression", // Card field for the mined word or expression text.
-      "audio": "ExpressionAudio", // Audio setting.
-      "image": "Picture", // Image setting.
-      "sentence": "Sentence", // Sentence setting.
-      "miscInfo": "MiscInfo", // Misc info setting.
-      "translation": "SelectionText" // Translation setting.
+      "audio": "ExpressionAudio", // Card field that receives generated sentence audio.
+      "image": "Picture", // Card field that receives the captured screenshot or animated image.
+      "sentence": "Sentence", // Card field that receives the source sentence text.
+      "miscInfo": "MiscInfo", // Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).
+      "translation": "SelectionText" // Card field that receives the current selection or translated text.
     }, // Fields setting.
     "ai": {
       "enabled": false, // Enable AI provider usage for Anki translation/enrichment flows. Values: true | false
@@ -494,18 +494,18 @@
       "systemPrompt": "" // Optional system prompt override for Anki AI translation/enrichment flows.
     }, // Ai setting.
     "media": {
-      "generateAudio": true, // Generate audio setting. Values: true | false
-      "generateImage": true, // Generate image setting. Values: true | false
-      "imageType": "static", // Image type setting.
-      "imageFormat": "jpg", // Image format setting.
-      "imageQuality": 92, // Image quality setting.
-      "animatedFps": 10, // Animated fps setting.
-      "animatedMaxWidth": 640, // Animated max width setting.
-      "animatedCrf": 35, // Animated crf setting.
+      "generateAudio": true, // Generate sentence audio for mined cards. Values: true | false
+      "generateImage": true, // Generate screenshot or animated image for mined cards. Values: true | false
+      "imageType": "static", // Image capture type: "static" for a single still frame, "avif" for an animated AVIF. Values: static | avif
+      "imageFormat": "jpg", // Encoding format used when imageType is "static". Values: jpg | png | webp
+      "imageQuality": 92, // Quality (0-100) used for lossy static image encoders.
+      "animatedFps": 10, // Target frame rate for animated AVIF captures.
+      "animatedMaxWidth": 640, // Maximum width applied to animated AVIF captures.
+      "animatedCrf": 35, // Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.
       "syncAnimatedImageToWordAudio": true, // For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio. Values: true | false
-      "audioPadding": 0.5, // Audio padding setting.
-      "fallbackDuration": 3, // Fallback duration setting.
-      "maxMediaDuration": 30 // Max media duration setting.
+      "audioPadding": 0.5, // Seconds of padding appended to both ends of generated sentence audio.
+      "fallbackDuration": 3, // Fallback clip duration in seconds when subtitle timing data is unavailable.
+      "maxMediaDuration": 30 // Maximum allowed media clip duration in seconds.
     }, // Media setting.
     "knownWords": {
       "highlightEnabled": false, // Enable fast local highlighting for words already known in Anki. Values: true | false
@@ -516,11 +516,11 @@
       "color": "#a6da95" // Color used for known-word highlights.
     }, // Known words setting.
     "behavior": {
-      "overwriteAudio": true, // Overwrite audio setting. Values: true | false
-      "overwriteImage": true, // Overwrite image setting. Values: true | false
-      "mediaInsertMode": "append", // Media insert mode setting.
-      "highlightWord": true, // Highlight word setting. Values: true | false
-      "notificationType": "osd", // Notification type setting.
+      "overwriteAudio": true, // When updating an existing card, overwrite the audio field instead of skipping it. Values: true | false
+      "overwriteImage": true, // When updating an existing card, overwrite the image field instead of skipping it. Values: true | false
+      "mediaInsertMode": "append", // Whether new media is appended after or prepended before existing field contents on update. Values: append | prepend
+      "highlightWord": true, // Bold the mined word inside the sentence field on the saved Anki card. Values: true | false
+      "notificationType": "osd", // Notification surface used to announce mining and update outcomes. Values: osd | system | both | none
       "autoUpdateNewCards": true // Automatically update newly added cards. Values: true | false
     }, // Behavior setting.
     "nPlusOne": {
@@ -528,16 +528,16 @@
       "nPlusOne": "#c6a0f6" // Color used for the single N+1 target token highlight.
     }, // N plus one setting.
     "metadata": {
-      "pattern": "[SubMiner] %f (%t)" // Pattern setting.
+      "pattern": "[SubMiner] %f (%t)" // Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).
     }, // Metadata setting.
     "isLapis": {
-      "enabled": false, // Enabled setting. Values: true | false
-      "sentenceCardModel": "Japanese sentences" // Sentence card model setting.
+      "enabled": false, // Enable Lapis-specific mining behaviors and sentence card model targeting. Values: true | false
+      "sentenceCardModel": "Japanese sentences" // Note type name used by Lapis sentence cards.
     }, // Is lapis setting.
     "isKiku": {
-      "enabled": false, // Enabled setting. Values: true | false
+      "enabled": false, // Enable Kiku-specific mining behaviors (duplicate handling, field grouping). Values: true | false
       "fieldGrouping": "disabled", // Kiku duplicate-card field grouping mode. Values: auto | manual | disabled
-      "deleteDuplicateInAuto": true // Delete duplicate in auto setting. Values: true | false
+      "deleteDuplicateInAuto": true // When Kiku field grouping is "auto", delete the duplicate source card after grouping completes. Values: true | false
     } // Is kiku setting.
   }, // Automatic Anki updates and media generation options.
 
@@ -546,7 +546,7 @@
   // Jimaku API configuration and defaults.
   // ==========================================
   "jimaku": {
-    "apiBaseUrl": "https://jimaku.cc", // Api base url setting.
+    "apiBaseUrl": "https://jimaku.cc", // Base URL of the Jimaku subtitle search API.
     "languagePreference": "ja", // Preferred language used in Jimaku search. Values: ja | en | none
     "maxEntryResults": 10 // Maximum Jimaku search results returned.
   }, // Jimaku API configuration and defaults.
@@ -618,9 +618,9 @@
     "serverUrl": "", // Base Jellyfin server URL (for example: http://localhost:8096).
     "recentServers": [], // Recently authenticated Jellyfin server URLs shown in setup.
     "username": "", // Default Jellyfin username used during CLI login.
-    "deviceId": "subminer", // Device id setting.
-    "clientName": "SubMiner", // Client name setting.
-    "clientVersion": "0.1.0", // Client version setting.
+    "deviceId": "subminer", // Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.
+    "clientName": "SubMiner", // Client name sent on the Jellyfin authentication handshake; primarily internal.
+    "clientVersion": "0.1.0", // Client version sent on the Jellyfin authentication handshake; primarily internal.
     "defaultLibraryId": "", // Optional default Jellyfin library ID for item listing.
     "remoteControlEnabled": true, // Enable Jellyfin remote cast control mode. Values: true | false
     "remoteControlAutoConnect": true, // Auto-connect to the configured remote control target. Values: true | false

docs/RELEASING.md

@@ -84,5 +84,8 @@ Notes:
 - AUR publish is best-effort: the workflow retries transient SSH clone/push failures, then warns and leaves the GitHub Release green if AUR still fails. Follow up with a manual `git push aur master` from the AUR checkout when needed.
 - Required GitHub Actions secret: `AUR_SSH_PRIVATE_KEY`. Add the matching public key to your AUR account before relying on the automation.
 - Release and prerelease workflows upload updater metadata (`*.yml`) and blockmaps (`*.blockmap`) alongside platform artifacts. Do not remove those files while `electron-updater` is enabled.
+- macOS tray app updates use the standard `electron-updater`/Squirrel path. Keep `latest-mac.yml`, the macOS ZIP, and ZIP blockmap published; Squirrel uses the ZIP payload even when the DMG remains the user-facing installer.
+- macOS update metadata and full ZIP downloads are routed through `/usr/bin/curl` before Squirrel installation to avoid Electron main-process network crashes on update checks.
+- Local macOS build-output apps outside `/Applications` or `~/Applications` skip native update checks. To validate auto-update end to end, install the signed and notarized app bundle into one of those Applications folders and point it at a published updater feed.
 - The first updater-enabled release cannot update older installs automatically. Users need one manual install to get the updater code.
 - Stable auto-update checks ignore beta/RC prereleases by default. Set `updates.channel` to `"prerelease"` on a test install when validating beta/RC updater behavior.

docs/plans/config-settings-window.md

@@ -0,0 +1,70 @@
+# Config Settings Window
+
+read_when: changing config UI, config save behavior, or config docs
+
+## Intent
+
+Add a dedicated Electron settings window for editing canonical config values without exposing the historical layout mistakes in `config.jsonc`.
+
+The UI groups options by workflow:
+
+- Viewing
+- Mining & Anki
+- Playback & Sources
+- Input
+- Integrations
+- Tracking & App
+- Advanced
+
+Each field maps back to its current raw config path. The presentation layer must stay separate from generated config-template sections.
+
+## Sources
+
+- Canonical defaults: `DEFAULT_CONFIG`
+- Existing option descriptions/enums: `CONFIG_OPTION_REGISTRY`
+- UI registry: `src/config/settings/registry.ts`
+- JSONC save path: `src/config/settings/jsonc-edit.ts`
+- Window runtime: `src/main/runtime/config-settings-window.ts`
+
+## Save Contract
+
+Settings writes use `jsonc-parser.modify`, not `JSON.stringify`.
+
+Required behavior:
+
+- Preserve comments, trailing commas, unrelated keys, and hidden legacy keys.
+- Reset removes the explicit path so defaults resolve normally.
+- Validate the candidate config before writing.
+- Reject warnings caused by modified fields.
+- Preserve unrelated existing warnings and return them in the snapshot.
+- Write atomically, reload `ConfigService`, classify with existing hot-reload logic, and apply live changes where supported.
+- Never return secret values to the renderer; snapshots only expose configured/not-configured state.
+
+## Hidden Compatibility Keys
+
+Do not expose these as first-class controls:
+
+- `ankiConnect.deck`
+- Legacy top-level Anki migration fields such as `wordField`, `audioField`, media-generation aliases, and behavior aliases
+- Legacy `ankiConnect.nPlusOne.*` aliases except canonical `nPlusOne.nPlusOne` and `nPlusOne.minSentenceWords`
+- Deprecated Lapis sentence-card fields
+- `youtubeSubgen.primarySubLanguages`
+- `anilist.characterDictionary.refreshTtlHours`
+- `anilist.characterDictionary.evictionPolicy`
+- `jellyfin.accessToken`
+- `jellyfin.userId`
+- `controller.buttonIndices` as a normal editable field
+
+## Verification
+
+Minimum targeted checks:
+
+- `bun test src/config/settings/registry.test.ts src/config/settings/jsonc-edit.test.ts src/settings/settings-model.test.ts src/main/runtime/config-settings-window.test.ts`
+- `bun run test:config`
+- `bun run typecheck`
+- `bun run build`
+
+If docs changed:
+
+- `bun run docs:test`
+- `bun run docs:build`

launcher/commands/app-command.ts

@@ -3,7 +3,14 @@ import type { LauncherCommandContext } from './context.js';
 
 export function runAppPassthroughCommand(context: LauncherCommandContext): boolean {
   const { args, appPath } = context;
-  if (!args.appPassthrough || !appPath) {
+  if (!appPath) {
+    return false;
+  }
+  if (args.configSettings) {
+    runAppCommandWithInherit(appPath, ['--config']);
+    return true;
+  }
+  if (!args.appPassthrough) {
     return false;
   }
   runAppCommandWithInherit(appPath, args.appArgs);

launcher/commands/playback-command.test.ts

@@ -53,6 +53,7 @@ function createContext(): LauncherCommandContext {
       doctor: false,
       doctorRefreshKnownWords: false,
       version: false,
+      configSettings: false,
       configPath: false,
       configShow: false,
       mpvIdle: false,

launcher/config/args-normalizer.test.ts

@@ -159,6 +159,41 @@ test('applyInvocationsToArgs maps config and jellyfin invocation state', () => {
   assert.equal(parsed.logLevel, 'warn');
 });
 
+test('applyInvocationsToArgs maps bare config invocation to settings window', () => {
+  const parsed = createDefaultArgs({});
+
+  applyInvocationsToArgs(parsed, {
+    jellyfinInvocation: null,
+    configInvocation: {
+      action: undefined,
+    },
+    mpvInvocation: null,
+    appInvocation: null,
+    dictionaryTriggered: false,
+    dictionaryTarget: null,
+    dictionaryLogLevel: null,
+    dictionaryCandidates: false,
+    dictionarySelect: false,
+    dictionaryAnilistId: null,
+    statsTriggered: false,
+    statsBackground: false,
+    statsStop: false,
+    statsCleanup: false,
+    statsCleanupVocab: false,
+    statsCleanupLifetime: false,
+    statsLogLevel: null,
+    doctorTriggered: false,
+    doctorLogLevel: null,
+    doctorRefreshKnownWords: false,
+    texthookerTriggered: false,
+    texthookerLogLevel: null,
+    texthookerOpenBrowser: false,
+  });
+
+  assert.equal(parsed.configSettings, true);
+  assert.equal(parsed.configPath, false);
+});
+
 test('applyInvocationsToArgs maps texthooker browser-open request', () => {
   const parsed = createDefaultArgs({});
 

launcher/config/args-normalizer.ts

@@ -158,6 +158,7 @@ export function createDefaultArgs(
     doctorRefreshKnownWords: false,
     version: false,
     update: false,
+    configSettings: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,
@@ -221,6 +222,7 @@ export function applyRootOptionsToArgs(
   if (options.rofi === true) parsed.useRofi = true;
   if (options.update === true) parsed.update = true;
   if (options.version === true) parsed.version = true;
+  if (options.config === true) parsed.configSettings = true;
   if (options.startOverlay === true) parsed.autoStartOverlay = true;
   if (options.texthooker === false) parsed.useTexthooker = false;
   if (typeof options.args === 'string') parsed.mpvArgs = options.args;
@@ -308,8 +310,9 @@ export function applyInvocationsToArgs(parsed: Args, invocations: CliInvocations
     if (invocations.configInvocation.logLevel) {
       parsed.logLevel = parseLogLevel(invocations.configInvocation.logLevel);
     }
-    const action = (invocations.configInvocation.action || 'path').toLowerCase();
-    if (action === 'path') parsed.configPath = true;
+    const action = (invocations.configInvocation.action || '').toLowerCase();
+    if (!action) parsed.configSettings = true;
+    else if (action === 'path') parsed.configPath = true;
     else if (action === 'show') parsed.configShow = true;
     else fail(`Unknown config action: ${invocations.configInvocation.action}`);
   }

launcher/config/cli-parser-builder.ts

@@ -15,7 +15,7 @@ export interface JellyfinInvocation {
 }
 
 export interface CommandActionInvocation {
-  action: string;
+  action?: string;
   logLevel?: string;
 }
 
@@ -58,6 +58,7 @@ function applyRootOptions(program: Command): void {
     .option('--start', 'Explicitly start overlay')
     .option('--log-level <level>', 'Log level')
     .option('-v, --version', 'Show SubMiner version')
+    .option('--config', 'Open configuration window')
     .option('-u, --update', 'Check for updates')
     .option('-R, --rofi', 'Use rofi picker')
     .option('-S, --start-overlay', 'Auto-start overlay')
@@ -293,9 +294,9 @@ export function parseCliPrograms(
   commandProgram
     .command('config')
     .description('Config helpers')
-    .argument('[action]', 'path|show', 'path')
+    .argument('[action]', 'path|show')
     .option('--log-level <level>', 'Log level')
-    .action((action: string, options: Record<string, unknown>) => {
+    .action((action: string | undefined, options: Record<string, unknown>) => {
       configInvocation = {
         action,
         logLevel: typeof options.logLevel === 'string' ? options.logLevel : undefined,

launcher/main.test.ts

@@ -232,6 +232,54 @@ test('doctor refresh-known-words forwards app refresh command without requiring
   });
 });
 
+test('launcher config option forwards app configuration window command', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const appPath = path.join(root, 'fake-subminer.sh');
+    const capturePath = path.join(root, 'captured-args.txt');
+    fs.writeFileSync(
+      appPath,
+      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+    );
+    fs.chmodSync(appPath, 0o755);
+
+    const env = {
+      ...makeTestEnv(homeDir, xdgConfigHome),
+      SUBMINER_APPIMAGE_PATH: appPath,
+      SUBMINER_TEST_CAPTURE: capturePath,
+    };
+    const result = runLauncher(['--config'], env);
+
+    assert.equal(result.status, 0);
+    assert.equal(fs.readFileSync(capturePath, 'utf8'), '--config\n');
+  });
+});
+
+test('launcher config command forwards app configuration window command', () => {
+  withTempDir((root) => {
+    const homeDir = path.join(root, 'home');
+    const xdgConfigHome = path.join(root, 'xdg');
+    const appPath = path.join(root, 'fake-subminer.sh');
+    const capturePath = path.join(root, 'captured-args.txt');
+    fs.writeFileSync(
+      appPath,
+      '#!/bin/sh\nif [ -n "$SUBMINER_TEST_CAPTURE" ]; then printf "%s\\n" "$@" > "$SUBMINER_TEST_CAPTURE"; fi\nexit 0\n',
+    );
+    fs.chmodSync(appPath, 0o755);
+
+    const env = {
+      ...makeTestEnv(homeDir, xdgConfigHome),
+      SUBMINER_APPIMAGE_PATH: appPath,
+      SUBMINER_TEST_CAPTURE: capturePath,
+    };
+    const result = runLauncher(['config'], env);
+
+    assert.equal(result.status, 0);
+    assert.equal(fs.readFileSync(capturePath, 'utf8'), '--config\n');
+  });
+});
+
 test('launcher forwards --args to mpv as parsed tokens', { timeout: 15000 }, () => {
   withTempDir((root) => {
     const homeDir = path.join(root, 'home');

launcher/mpv.test.ts

@@ -530,6 +530,7 @@ function makeArgs(overrides: Partial<Args> = {}): Args {
     doctor: false,
     doctorRefreshKnownWords: false,
     version: false,
+    configSettings: false,
     configPath: false,
     configShow: false,
     mpvIdle: false,

launcher/parse-args.test.ts

@@ -57,6 +57,12 @@ test('parseArgs captures mpv args string', () => {
   assert.equal(parsed.mpvArgs, '--pause=yes --title="movie night"');
 });
 
+test('parseArgs maps root config window option', () => {
+  const parsed = parseArgs(['--config'], 'subminer', {});
+
+  assert.equal(parsed.configSettings, true);
+});
+
 test('parseArgs maps root update flags without conflicting with jellyfin username', () => {
   const shortParsed = parseArgs(['-u'], 'subminer', {});
   const longParsed = parseArgs(['--update'], 'subminer', {});
@@ -101,6 +107,33 @@ test('parseArgs maps config show action', () => {
   assert.equal(parsed.configPath, false);
 });
 
+test('parseArgs maps bare config command to settings window', () => {
+  const parsed = parseArgs(['config'], 'subminer', {});
+
+  assert.equal(parsed.configSettings, true);
+  assert.equal(parsed.configPath, false);
+  assert.equal(parsed.configShow, false);
+});
+
+test('parseArgs maps config path action to config path output', () => {
+  const parsed = parseArgs(['config', 'path'], 'subminer', {});
+
+  assert.equal(parsed.configPath, true);
+  assert.equal(parsed.configSettings, false);
+});
+
+test('parseArgs rejects removed config open and launch actions', () => {
+  const openExit = withProcessExitIntercept(() => {
+    parseArgs(['config', 'open'], 'subminer', {});
+  });
+  const exit = withProcessExitIntercept(() => {
+    parseArgs(['config', 'launch'], 'subminer', {});
+  });
+
+  assert.equal(openExit.code, 1);
+  assert.equal(exit.code, 1);
+});
+
 test('parseArgs maps mpv idle action', () => {
   const parsed = parseArgs(['mpv', 'idle'], 'subminer', {});
 

launcher/types.ts

@@ -136,6 +136,7 @@ export interface Args {
   doctorRefreshKnownWords: boolean;
   version: boolean;
   update?: boolean;
+  configSettings: boolean;
   configPath: boolean;
   configShow: boolean;
   mpvIdle: boolean;

package.json

@@ -18,8 +18,9 @@
     "build:launcher": "bun build ./launcher/main.ts --target=bun --packages=bundle --banner='#!/usr/bin/env bun' --outfile=dist/launcher/subminer",
     "build:stats": "cd stats && bun run build",
     "dev:stats": "cd stats && bun run dev",
-    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:launcher && bun run build:assets",
+    "build": "bun run build:yomitan && bun run build:stats && tsc -p tsconfig.json && bun run build:renderer && bun run build:settings && bun run build:launcher && bun run build:assets",
     "build:renderer": "esbuild src/renderer/renderer.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/renderer/renderer.js --sourcemap",
+    "build:settings": "esbuild src/settings/settings.ts --bundle --platform=browser --format=esm --target=es2022 --outfile=dist/settings/settings.js --sourcemap",
     "changelog:build": "bun run scripts/build-changelog.ts build-release",
     "changelog:check": "bun run scripts/build-changelog.ts check",
     "changelog:docs": "bun run scripts/build-changelog.ts docs",
@@ -48,7 +49,7 @@
     "test:plugin:src": "lua scripts/test-plugin-lua-compat.lua && lua scripts/test-plugin-start-gate.lua && lua scripts/test-plugin-session-bindings.lua && lua scripts/test-plugin-binary-windows.lua",
     "test:launcher:smoke:src": "bun test launcher/smoke.e2e.test.ts",
     "test:launcher:src": "bun test launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/mpv.test.ts launcher/picker.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/smoke.e2e.test.ts && bun run test:plugin:src",
-    "test:core:src": "bun test src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts stats/src/styles/globals.test.ts",
+    "test:core:src": "bun test src/preload-settings.test.ts src/cli/args.test.ts src/cli/help.test.ts src/shared/setup-state.test.ts src/core/services/cli-command.test.ts src/core/services/field-grouping-overlay.test.ts src/core/services/numeric-shortcut-session.test.ts src/core/services/secondary-subtitle.test.ts src/core/services/mpv-render-metrics.test.ts src/core/services/overlay-content-measurement.test.ts src/core/services/mpv-control.test.ts src/core/services/mpv.test.ts src/core/services/runtime-options-ipc.test.ts src/core/services/runtime-config.test.ts src/core/services/yomitan-extension-paths.test.ts src/core/services/yomitan-extension-loader.test.ts src/core/services/yomitan-settings.test.ts src/core/services/config-hot-reload.test.ts src/core/services/discord-presence.test.ts src/core/services/tokenizer.test.ts src/core/services/tokenizer/annotation-stage.test.ts src/core/services/tokenizer/parser-selection-stage.test.ts src/core/services/tokenizer/parser-enrichment-stage.test.ts src/core/services/subsync.test.ts src/core/services/overlay-bridge.test.ts src/core/services/overlay-shortcut-handler.test.ts src/core/services/stats-window.test.ts src/core/services/__tests__/stats-server.test.ts src/main/runtime/stats-server-routing.test.ts src/core/services/mining.test.ts src/core/services/anki-jimaku.test.ts src/core/services/jimaku-download-path.test.ts src/core/services/jellyfin.test.ts src/core/services/jellyfin-remote.test.ts src/core/services/immersion-tracker-service.test.ts src/core/services/overlay-runtime-init.test.ts src/core/services/app-ready.test.ts src/core/services/startup-bootstrap.test.ts src/core/services/subtitle-processing-controller.test.ts src/core/services/anilist/anilist-update-queue.test.ts src/core/services/anilist/rate-limiter.test.ts src/core/services/jlpt-token-filter.test.ts src/core/services/subtitle-position.test.ts src/core/utils/shortcut-config.test.ts src/main/runtime/startup-mode-flags.test.ts src/main/runtime/first-run-setup-plugin.test.ts src/main/runtime/first-run-setup-service.test.ts src/main/runtime/first-run-setup-window.test.ts src/main/runtime/command-line-launcher.test.ts src/main/runtime/tray-runtime.test.ts src/main/runtime/tray-main-actions.test.ts src/main/runtime/tray-main-deps.test.ts src/main/runtime/tray-runtime-handlers.test.ts src/main/runtime/cli-command-context-main-deps.test.ts src/main/runtime/app-ready-main-deps.test.ts src/main/runtime/update/appimage-updater.test.ts src/main/runtime/update/fetch-adapter.test.ts src/main/runtime/update/release-metadata-policy.test.ts src/main/runtime/update/update-dialogs.test.ts src/main/runtime/update/support-assets.test.ts src/renderer/error-recovery.test.ts src/renderer/subtitle-render.test.ts src/renderer/handlers/mouse.test.ts src/renderer/handlers/keyboard.test.ts src/renderer/modals/jimaku.test.ts src/subsync/utils.test.ts src/main/anilist-url-guard.test.ts src/window-trackers/hyprland-tracker.test.ts src/window-trackers/x11-tracker.test.ts src/window-trackers/windows-helper.test.ts src/window-trackers/windows-tracker.test.ts launcher/config.test.ts launcher/config-domain-parsers.test.ts launcher/config/cli-parser-builder.test.ts launcher/config/args-normalizer.test.ts launcher/parse-args.test.ts launcher/main.test.ts launcher/commands/command-modules.test.ts launcher/commands/update-command.test.ts launcher/setup-gate.test.ts stats/src/lib/api-client.test.ts stats/src/hooks/useExcludedWords.test.ts",
     "test:core:dist": "bun test dist/cli/args.test.js dist/cli/help.test.js dist/core/services/cli-command.test.js dist/core/services/ipc.test.js dist/core/services/anki-jimaku-ipc.test.js dist/core/services/field-grouping-overlay.test.js dist/core/services/numeric-shortcut-session.test.js dist/core/services/secondary-subtitle.test.js dist/core/services/mpv-render-metrics.test.js dist/core/services/overlay-content-measurement.test.js dist/core/services/mpv-control.test.js dist/core/services/mpv.test.js dist/core/services/runtime-options-ipc.test.js dist/core/services/runtime-config.test.js dist/core/services/yomitan-extension-paths.test.js dist/core/services/config-hot-reload.test.js dist/core/services/discord-presence.test.js dist/core/services/tokenizer.test.js dist/core/services/tokenizer/annotation-stage.test.js dist/core/services/tokenizer/parser-selection-stage.test.js dist/core/services/tokenizer/parser-enrichment-stage.test.js dist/core/services/subsync.test.js dist/core/services/overlay-bridge.test.js dist/core/services/overlay-manager.test.js dist/core/services/overlay-shortcut-handler.test.js dist/core/services/mining.test.js dist/core/services/anki-jimaku.test.js dist/core/services/jimaku-download-path.test.js dist/core/services/jellyfin.test.js dist/core/services/jellyfin-remote.test.js dist/core/services/immersion-tracker-service.test.js dist/core/services/overlay-runtime-init.test.js dist/core/services/app-ready.test.js dist/core/services/startup-bootstrap.test.js dist/core/services/subtitle-processing-controller.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/anilist/anilist-update-queue.test.js dist/core/services/anilist/rate-limiter.test.js dist/core/services/jlpt-token-filter.test.js dist/core/services/subtitle-position.test.js dist/renderer/error-recovery.test.js dist/renderer/subtitle-render.test.js dist/renderer/handlers/mouse.test.js dist/renderer/handlers/keyboard.test.js dist/renderer/modals/jimaku.test.js dist/subsync/utils.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/hyprland-tracker.test.js dist/window-trackers/x11-tracker.test.js dist/window-trackers/windows-helper.test.js dist/window-trackers/windows-tracker.test.js",
     "test:core:smoke:dist": "bun test dist/cli/help.test.js dist/core/services/runtime-config.test.js dist/core/services/ipc.test.js dist/core/services/overlay-manager.test.js dist/core/services/anilist/anilist-token-store.test.js dist/core/services/startup-bootstrap.test.js dist/renderer/error-recovery.test.js dist/main/anilist-url-guard.test.js dist/window-trackers/x11-tracker.test.js",
     "test:smoke:dist": "bun run test:config:smoke:dist && bun run test:core:smoke:dist",
@@ -116,6 +117,7 @@
     "jsonc-parser": "^3.3.1",
     "koffi": "^2.15.6",
     "libsql": "^0.5.22",
+    "vscode-json-languageservice": "^5.7.2",
     "ws": "^8.19.0"
   },
   "devDependencies": {

release/prerelease-notes.md

@@ -3,33 +3,33 @@
 ## Highlights
 ### Added
 
-**Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`. Checks include checksum verification, configurable notifications, and an opt-in channel for prerelease builds. The `subminer` launcher and Linux rofi theme are also updated automatically.
+- **Auto-Updater:** SubMiner can now check for and apply updates from the system tray or by running `subminer -u`. Checks include checksum verification, configurable notifications, and an opt-in channel for prerelease builds. The `subminer` launcher and Linux rofi theme are also updated automatically.
 
-**First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH.
+- **First-Run Setup:** A new optional setup flow installs Bun and the `subminer` command-line launcher on Linux, macOS, and Windows. Windows users get a `subminer.cmd` PATH shim so `subminer` works in any terminal without manually adding `SubMiner.exe` to PATH.
 
 ### Fixed
 
-**macOS Overlay:** Significantly improved overlay focus and stability — the overlay now hides when mpv loses focus or is minimized, stays stable through transient window-tracking misses, remains correctly layered during stats mouse passthrough, and opens over fullscreen mpv without switching Spaces. Passthrough is also fixed so mpv controls stay clickable before hovering a subtitle bar. Background tracking overhead is reduced while mpv is stably focused.
+- **macOS Overlay:** Significantly improved overlay focus and stability: the overlay now hides when mpv loses focus or is minimized, stays stable through transient window-tracking misses, remains correctly layered during stats mouse passthrough, and opens over fullscreen mpv without switching Spaces. Passthrough is also fixed so mpv controls stay clickable before hovering a subtitle bar. Background tracking overhead is reduced while mpv is stably focused.
 
-**Subtitle Sync Modal:** Fixed a macOS issue where opening the subtitle sync modal would flash and disappear on the first attempt, or leave stale state after syncing.
+- **Subtitle Sync Modal:** Fixed a macOS issue where opening the subtitle sync modal would flash and disappear on the first attempt, or leave stale state after syncing.
 
-**Controller:** Controller config and debug shortcuts now stay closed while controller support is disabled, with a notice to enable `controller.enabled`. Learn mode can be entered from the edit pencil or binding badge, remaps are saved per controller profile, and individual bindings can be reset to their defaults.
+- **Controller:** Controller config and debug shortcuts now stay closed while controller support is disabled, with a notice to enable `controller.enabled`. Learn mode can be entered from the edit pencil or binding badge, remaps are saved per controller profile, and individual bindings can be reset to their defaults.
 
-**AniList Progress:** Progress threshold checks now use fresh playback position data, so updates fire correctly when playback reaches or skips past the watched threshold. Season-specific results are preferred for multi-season files, and a clear message is shown when the matched season is not in Planning or Watching status.
+- **AniList Progress:** Progress threshold checks now use fresh playback position data, so updates fire correctly when playback reaches or skips past the watched threshold. Season-specific results are preferred for multi-season files, and a clear message is shown when the matched season is not in Planning or Watching status.
 
-**Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits.
+- **Character Dictionary:** Cached media matches are reused when loading a title with an existing snapshot, avoiding redundant AniList search requests on repeat visits.
 
-**Updater — Linux:** The tray app now uses GitHub release metadata for update checks instead of the native Electron updater, preventing crashes. `subminer -u` performs updates independently of any running tray instance and correctly reports "up to date" without downloading assets when no newer release exists.
+- **Updater - Linux:** The tray app now uses GitHub release metadata for update checks instead of the native Electron updater, preventing crashes. `subminer -u` performs updates independently of any running tray instance and correctly reports "up to date" without downloading assets when no newer release exists.
 
-**Updater — macOS:** Update dialogs now come to the front when launched from `subminer --update`. Builds that cannot install native updates show a manual-install message instead of an inapplicable restart prompt. Signed macOS builds remain on the native updater path without triggering premature Squirrel install checks.
+- **Updater - macOS:** Update dialogs now come to the front when launched from `subminer --update`. Builds that cannot install native updates show a manual-install message instead of an inapplicable restart prompt. Signed macOS builds remain on the native updater path without triggering premature Squirrel install checks.
 
-**Setup — macOS:** First-run setup now recognizes existing `subminer` launcher installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, returning control to the terminal.
+- **Setup - macOS:** First-run setup now recognizes existing `subminer` launcher installs in Homebrew or user PATH directories, and manual setup avoids writing into Homebrew-owned paths. `subminer app --setup` opens the setup flow even when SubMiner is already running in the background. The standalone setup app quits after completing first-run setup, returning control to the terminal.
 
-**Launcher — Linux:** First-run launcher installs are now built with a valid Bun shebang, fixing installs that previously failed silently.
+- **Launcher - Linux:** First-run launcher installs are now built with a valid Bun shebang, fixing installs that previously failed silently.
 
-**Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; the settings window uses a close-only menu to prevent accidentally quitting the tray app; an in-page close button is provided on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can now close correctly without mpv running.
+- **Tray App:** Fixed several lifecycle issues with tray-launched Yomitan settings: the tray stays running when settings are closed; settings loading no longer blocks other tray actions; the settings window uses a close-only menu to prevent accidentally quitting the tray app; an in-page close button is provided on Hyprland where native window controls are unavailable; the embedded popup preview is disabled to prevent renderer hangs during sidebar navigation; extension refreshes at startup are serialized to prevent race conditions; and the session help modal can now close correctly without mpv running.
 
-**Build — Linux Install:** Fixed one-shot `make clean build install` flows so the install step correctly picks up the AppImage produced earlier in the same make invocation.
+- **Build - Linux Install:** Fixed one-shot `make clean build install` flows so the install step correctly picks up the AppImage produced earlier in the same make invocation.
 
 ## Installation
 

scripts/prepare-build-assets.mjs

@@ -7,6 +7,8 @@ const scriptDir = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(scriptDir, '..');
 const rendererSourceDir = path.join(repoRoot, 'src', 'renderer');
 const rendererOutputDir = path.join(repoRoot, 'dist', 'renderer');
+const settingsSourceDir = path.join(repoRoot, 'src', 'settings');
+const settingsOutputDir = path.join(repoRoot, 'dist', 'settings');
 const scriptsOutputDir = path.join(repoRoot, 'dist', 'scripts');
 const macosHelperSourcePath = path.join(scriptDir, 'get-mpv-window-macos.swift');
 const macosHelperBinaryPath = path.join(scriptsOutputDir, 'get-mpv-window-macos');
@@ -21,14 +23,22 @@ function copyFile(sourcePath, outputPath) {
   fs.copyFileSync(sourcePath, outputPath);
 }
 
-function copyRendererAssets() {
-  copyFile(path.join(rendererSourceDir, 'index.html'), path.join(rendererOutputDir, 'index.html'));
-  copyFile(path.join(rendererSourceDir, 'style.css'), path.join(rendererOutputDir, 'style.css'));
-  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(rendererOutputDir, 'fonts'), {
+function copyAssets(sourceDir, outputDir, label) {
+  copyFile(path.join(sourceDir, 'index.html'), path.join(outputDir, 'index.html'));
+  copyFile(path.join(sourceDir, 'style.css'), path.join(outputDir, 'style.css'));
+  fs.cpSync(path.join(rendererSourceDir, 'fonts'), path.join(outputDir, 'fonts'), {
     recursive: true,
     force: true,
   });
-  process.stdout.write(`Staged renderer assets in ${rendererOutputDir}\n`);
+  process.stdout.write(`Staged ${label} assets in ${outputDir}\n`);
+}
+
+function copyRendererAssets() {
+  copyAssets(rendererSourceDir, rendererOutputDir, 'renderer');
+}
+
+function copySettingsAssets() {
+  copyAssets(settingsSourceDir, settingsOutputDir, 'settings');
 }
 
 function fallbackToMacosSource() {
@@ -70,6 +80,7 @@ function buildMacosHelper() {
 
 function main() {
   copyRendererAssets();
+  copySettingsAssets();
   buildMacosHelper();
 }
 

src/cli/args.test.ts

@@ -212,6 +212,14 @@ test('hasExplicitCommand and shouldStartApp preserve command intent', () => {
   assert.equal(shouldStartApp(settings), true);
   assert.equal(shouldRunSettingsOnlyStartup(settings), true);
 
+  const configSettings = parseArgs(['--config']);
+  assert.equal(configSettings.configSettings, true);
+  assert.equal(hasExplicitCommand(configSettings), true);
+  assert.equal(shouldStartApp(configSettings), true);
+  assert.equal(shouldRunSettingsOnlyStartup(configSettings), false);
+  assert.equal(commandNeedsOverlayRuntime(configSettings), false);
+  assert.equal(commandNeedsOverlayStartupPrereqs(configSettings), false);
+
   const settingsWithOverlay = parseArgs(['--settings', '--toggle-visible-overlay']);
   assert.equal(settingsWithOverlay.settings, true);
   assert.equal(settingsWithOverlay.toggleVisibleOverlay, true);

src/cli/args.ts

@@ -11,6 +11,7 @@ export interface CliArgs {
   toggleVisibleOverlay: boolean;
   togglePrimarySubtitleBar: boolean;
   settings: boolean;
+  configSettings: boolean;
   setup: boolean;
   show: boolean;
   hide: boolean;
@@ -115,6 +116,7 @@ export function parseArgs(argv: string[]): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,
@@ -234,6 +236,7 @@ export function parseArgs(argv: string[]): CliArgs {
     else if (arg === '--toggle-visible-overlay') args.toggleVisibleOverlay = true;
     else if (arg === '--toggle-primary-subtitle-bar') args.togglePrimarySubtitleBar = true;
     else if (arg === '--settings' || arg === '--yomitan') args.settings = true;
+    else if (arg === '--config') args.configSettings = true;
     else if (arg === '--setup') args.setup = true;
     else if (arg === '--show') args.show = true;
     else if (arg === '--hide') args.hide = true;
@@ -486,6 +489,7 @@ export function hasExplicitCommand(args: CliArgs): boolean {
     args.toggleVisibleOverlay ||
     args.togglePrimarySubtitleBar ||
     args.settings ||
+    args.configSettings ||
     args.setup ||
     args.show ||
     args.hide ||
@@ -558,6 +562,7 @@ export function isStandaloneTexthookerCommand(args: CliArgs): boolean {
     !args.toggleVisibleOverlay &&
     !args.togglePrimarySubtitleBar &&
     !args.settings &&
+    !args.configSettings &&
     !args.setup &&
     !args.show &&
     !args.hide &&
@@ -625,6 +630,7 @@ export function shouldStartApp(args: CliArgs): boolean {
     args.toggleVisibleOverlay ||
     args.togglePrimarySubtitleBar ||
     args.settings ||
+    args.configSettings ||
     args.setup ||
     args.copySubtitle ||
     args.copySubtitleMultiple ||
@@ -679,6 +685,7 @@ export function shouldRunSettingsOnlyStartup(args: CliArgs): boolean {
     !args.toggle &&
     !args.toggleVisibleOverlay &&
     !args.togglePrimarySubtitleBar &&
+    !args.configSettings &&
     !args.show &&
     !args.hide &&
     !args.setup &&

src/cli/help.test.ts

@@ -22,6 +22,7 @@ test('printHelp includes configured texthooker port', () => {
   assert.match(output, /--open-browser\s+Open texthooker in your default browser/);
   assert.doesNotMatch(output, /--refresh-known-words/);
   assert.match(output, /--setup\s+Open first-run setup window/);
+  assert.match(output, /--config\s+Open configuration window/);
   assert.match(output, /--anilist-status/);
   assert.match(output, /--anilist-retry-queue/);
   assert.match(output, /--dictionary/);

src/cli/help.ts

@@ -25,6 +25,7 @@ ${B}Overlay${R}
   --show-visible-overlay         Show subtitle overlay
   --hide-visible-overlay         Hide subtitle overlay
   --settings                     Open Yomitan settings window
+  --config                       Open configuration window
   --setup                        Open first-run setup window
   --auto-start-overlay           Auto-hide mpv subs, show overlay on connect
 

src/config/config.test.ts

@@ -2324,7 +2324,10 @@ test('template generator includes known keys', () => {
     /"dpadFallback": "horizontal",? \/\/ Optional D-pad fallback used when this analog controller action should also read D-pad input\. Values: none \| horizontal \| vertical/,
   );
   assert.match(output, /"port": 6678,? \/\/ Annotated subtitle websocket server port\./);
-  assert.match(output, /"openBrowser": false,? \/\/ Open browser setting\. Values: true \| false/);
+  assert.match(
+    output,
+    /"openBrowser": false,? \/\/ Open the texthooker page in the default browser when the server starts\. Values: true \| false/,
+  );
   assert.match(
     output,
     /"enabled": false,? \/\/ Enable overlay controller support through the Chrome Gamepad API\. Values: true \| false/,

src/config/definitions/domain-registry.test.ts

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 
+import { ResolvedConfig } from '../../types/config';
 import {
   CONFIG_OPTION_REGISTRY,
   CONFIG_TEMPLATE_SECTIONS,
@@ -13,6 +14,77 @@ import { buildImmersionConfigOptionRegistry } from './options-immersion';
 import { buildIntegrationConfigOptionRegistry } from './options-integrations';
 import { buildSubtitleConfigOptionRegistry } from './options-subtitle';
 
+function collectConfigLeafPaths(config: ResolvedConfig): string[] {
+  const leaves: string[] = [];
+  const visit = (value: unknown, prefix: string): void => {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+      leaves.push(prefix);
+      return;
+    }
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) {
+      leaves.push(prefix);
+      return;
+    }
+    for (const [key, child] of entries) {
+      visit(child, prefix ? `${prefix}.${key}` : key);
+    }
+  };
+  visit(config, '');
+  return leaves;
+}
+
+// DEFAULT_CONFIG leaves that intentionally do not have a curated
+// CONFIG_OPTION_REGISTRY entry. The generated config.example.jsonc still
+// includes these paths, but their inline comments fall back to an auto-
+// humanized key name instead of a written description.
+//
+// Current intentional gaps:
+//   - subtitleStyle.*: thin wrappers around standard CSS properties; the
+//     CSS reference is the canonical documentation surface.
+//   - keybindings: an array of {key, command} objects, documented at the
+//     section level via CONFIG_TEMPLATE_SECTIONS rather than per-leaf.
+//
+// New leaves added to DEFAULT_CONFIG should prefer a registry entry over
+// an allowlist entry. Only allowlist a path when the registry is genuinely
+// the wrong surface for it.
+const UNDOCUMENTED_LEAVES: ReadonlySet<string> = new Set([
+  'keybindings',
+  'subtitleStyle.backdropFilter',
+  'subtitleStyle.backgroundColor',
+  'subtitleStyle.fontColor',
+  'subtitleStyle.fontFamily',
+  'subtitleStyle.fontKerning',
+  'subtitleStyle.fontSize',
+  'subtitleStyle.fontStyle',
+  'subtitleStyle.fontWeight',
+  'subtitleStyle.jlptColors.N1',
+  'subtitleStyle.jlptColors.N2',
+  'subtitleStyle.jlptColors.N3',
+  'subtitleStyle.jlptColors.N4',
+  'subtitleStyle.jlptColors.N5',
+  'subtitleStyle.knownWordColor',
+  'subtitleStyle.letterSpacing',
+  'subtitleStyle.lineHeight',
+  'subtitleStyle.nPlusOneColor',
+  'subtitleStyle.secondary.backdropFilter',
+  'subtitleStyle.secondary.backgroundColor',
+  'subtitleStyle.secondary.fontColor',
+  'subtitleStyle.secondary.fontFamily',
+  'subtitleStyle.secondary.fontKerning',
+  'subtitleStyle.secondary.fontSize',
+  'subtitleStyle.secondary.fontStyle',
+  'subtitleStyle.secondary.fontWeight',
+  'subtitleStyle.secondary.letterSpacing',
+  'subtitleStyle.secondary.lineHeight',
+  'subtitleStyle.secondary.textRendering',
+  'subtitleStyle.secondary.textShadow',
+  'subtitleStyle.secondary.wordSpacing',
+  'subtitleStyle.textRendering',
+  'subtitleStyle.textShadow',
+  'subtitleStyle.wordSpacing',
+]);
+
 test('config option registry includes critical paths and has unique entries', () => {
   const paths = CONFIG_OPTION_REGISTRY.map((entry) => entry.path);
 
@@ -40,6 +112,35 @@ test('config option registry includes critical paths and has unique entries', ()
   assert.equal(new Set(paths).size, paths.length);
 });
 
+test('every DEFAULT_CONFIG leaf is in CONFIG_OPTION_REGISTRY or UNDOCUMENTED_LEAVES', () => {
+  const registryPaths = new Set(CONFIG_OPTION_REGISTRY.map((entry) => entry.path));
+  const leaves = collectConfigLeafPaths(DEFAULT_CONFIG);
+
+  const missing = leaves
+    .filter((path) => !registryPaths.has(path) && !UNDOCUMENTED_LEAVES.has(path))
+    .sort();
+  assert.deepEqual(
+    missing,
+    [],
+    `Add CONFIG_OPTION_REGISTRY entries (preferred) or add to UNDOCUMENTED_LEAVES allowlist: ${missing.join(', ')}`,
+  );
+
+  const stale = [...UNDOCUMENTED_LEAVES].filter((path) => registryPaths.has(path)).sort();
+  assert.deepEqual(
+    stale,
+    [],
+    `Remove from UNDOCUMENTED_LEAVES (now covered by CONFIG_OPTION_REGISTRY): ${stale.join(', ')}`,
+  );
+
+  const leafSet = new Set(leaves);
+  const orphaned = [...UNDOCUMENTED_LEAVES].filter((path) => !leafSet.has(path)).sort();
+  assert.deepEqual(
+    orphaned,
+    [],
+    `Remove from UNDOCUMENTED_LEAVES (no longer a DEFAULT_CONFIG leaf): ${orphaned.join(', ')}`,
+  );
+});
+
 test('config template sections include expected domains and unique keys', () => {
   const keys = CONFIG_TEMPLATE_SECTIONS.map((section) => section.key);
   const requiredKeys: (typeof keys)[number][] = [

src/config/definitions/options-core.ts

@@ -322,6 +322,46 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.texthooker.launchAtStartup,
       description: 'Launch texthooker server automatically when SubMiner starts.',
     },
+    {
+      path: 'texthooker.openBrowser',
+      kind: 'boolean',
+      defaultValue: defaultConfig.texthooker.openBrowser,
+      description: 'Open the texthooker page in the default browser when the server starts.',
+    },
+    {
+      path: 'subtitlePosition.yPercent',
+      kind: 'number',
+      defaultValue: defaultConfig.subtitlePosition.yPercent,
+      description:
+        'Vertical position of the subtitle overlay expressed as a percentage from the bottom of the screen.',
+    },
+    {
+      path: 'auto_start_overlay',
+      kind: 'boolean',
+      defaultValue: defaultConfig.auto_start_overlay,
+      description: 'Auto-start the subtitle overlay window when SubMiner launches.',
+    },
+    {
+      path: 'secondarySub.secondarySubLanguages',
+      kind: 'array',
+      defaultValue: defaultConfig.secondarySub.secondarySubLanguages,
+      description:
+        'Language code priority list used to auto-select a secondary subtitle track when available.',
+    },
+    {
+      path: 'secondarySub.autoLoadSecondarySub',
+      kind: 'boolean',
+      defaultValue: defaultConfig.secondarySub.autoLoadSecondarySub,
+      description:
+        'Automatically load a matching secondary subtitle when the primary subtitle loads.',
+    },
+    {
+      path: 'secondarySub.defaultMode',
+      kind: 'enum',
+      enumValues: ['hidden', 'visible', 'hover'],
+      defaultValue: defaultConfig.secondarySub.defaultMode,
+      description: 'Default visibility mode for the secondary subtitle bar.',
+    },
     {
       path: 'websocket.enabled',
       kind: 'enum',
@@ -360,6 +400,27 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.subsync.replace,
       description: 'Replace the active subtitle file when sync completes.',
     },
+    {
+      path: 'subsync.alass_path',
+      kind: 'string',
+      defaultValue: defaultConfig.subsync.alass_path,
+      description:
+        'Optional absolute path to the alass binary used by subsync. Leave empty to auto-discover from PATH.',
+    },
+    {
+      path: 'subsync.ffsubsync_path',
+      kind: 'string',
+      defaultValue: defaultConfig.subsync.ffsubsync_path,
+      description:
+        'Optional absolute path to the ffsubsync binary used by subsync. Leave empty to auto-discover from PATH.',
+    },
+    {
+      path: 'subsync.ffmpeg_path',
+      kind: 'string',
+      defaultValue: defaultConfig.subsync.ffmpeg_path,
+      description:
+        'Optional absolute path to the ffmpeg binary used by subsync. Leave empty to auto-discover from PATH.',
+    },
     {
       path: 'startupWarmups.lowPowerMode',
       kind: 'boolean',
@@ -422,5 +483,112 @@ export function buildCoreConfigOptionRegistry(
       defaultValue: defaultConfig.shortcuts.multiCopyTimeoutMs,
       description: 'Timeout for multi-copy/mine modes.',
     },
+    {
+      path: 'shortcuts.toggleVisibleOverlayGlobal',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.toggleVisibleOverlayGlobal,
+      description:
+        'Global accelerator that toggles overlay visibility from anywhere on the system. Use null to disable.',
+    },
+    {
+      path: 'shortcuts.copySubtitle',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.copySubtitle,
+      description: 'Accelerator that copies the current subtitle line to the clipboard.',
+    },
+    {
+      path: 'shortcuts.copySubtitleMultiple',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.copySubtitleMultiple,
+      description:
+        'Accelerator that copies consecutive subtitle lines while the multi-copy window stays open.',
+    },
+    {
+      path: 'shortcuts.updateLastCardFromClipboard',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.updateLastCardFromClipboard,
+      description:
+        'Accelerator that updates the last mined Anki card using the current clipboard contents.',
+    },
+    {
+      path: 'shortcuts.triggerFieldGrouping',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.triggerFieldGrouping,
+      description: 'Accelerator that triggers Kiku field grouping on duplicate cards.',
+    },
+    {
+      path: 'shortcuts.triggerSubsync',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.triggerSubsync,
+      description: 'Accelerator that triggers subsync against the active subtitle file.',
+    },
+    {
+      path: 'shortcuts.mineSentence',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.mineSentence,
+      description: 'Accelerator that mines the current sentence as a new Anki card.',
+    },
+    {
+      path: 'shortcuts.mineSentenceMultiple',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.mineSentenceMultiple,
+      description:
+        'Accelerator that mines consecutive sentences while the multi-mine window stays open.',
+    },
+    {
+      path: 'shortcuts.toggleSecondarySub',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.toggleSecondarySub,
+      description: 'Accelerator that toggles the secondary subtitle bar visibility.',
+    },
+    {
+      path: 'shortcuts.markAudioCard',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.markAudioCard,
+      description: 'Accelerator that marks the last mined card as an audio card.',
+    },
+    {
+      path: 'shortcuts.openCharacterDictionary',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openCharacterDictionary,
+      description: 'Accelerator that opens the character dictionary modal.',
+    },
+    {
+      path: 'shortcuts.openRuntimeOptions',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openRuntimeOptions,
+      description: 'Accelerator that opens the runtime options modal.',
+    },
+    {
+      path: 'shortcuts.openJimaku',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openJimaku,
+      description: 'Accelerator that opens the Jimaku subtitle search modal.',
+    },
+    {
+      path: 'shortcuts.openSessionHelp',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openSessionHelp,
+      description: 'Accelerator that opens the session help / keybinding cheatsheet.',
+    },
+    {
+      path: 'shortcuts.openControllerSelect',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openControllerSelect,
+      description: 'Accelerator that opens the controller selection and learn-mode modal.',
+    },
+    {
+      path: 'shortcuts.openControllerDebug',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.openControllerDebug,
+      description:
+        'Accelerator that opens the controller debug modal with live axis/button readouts.',
+    },
+    {
+      path: 'shortcuts.toggleSubtitleSidebar',
+      kind: 'string',
+      defaultValue: defaultConfig.shortcuts.toggleSubtitleSidebar,
+      description: 'Accelerator that toggles the subtitle sidebar visibility.',
+    },
   ];
 }

src/config/definitions/options-integrations.ts

@@ -15,6 +15,12 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.enabled,
       description: 'Enable AnkiConnect integration.',
     },
+    {
+      path: 'ankiConnect.url',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.url,
+      description: 'Base URL of the AnkiConnect HTTP server.',
+    },
     {
       path: 'ankiConnect.pollingRate',
       kind: 'number',
@@ -58,6 +64,37 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ankiConnect.fields.word,
       description: 'Card field for the mined word or expression text.',
     },
+    {
+      path: 'ankiConnect.fields.audio',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.audio,
+      description: 'Card field that receives generated sentence audio.',
+    },
+    {
+      path: 'ankiConnect.fields.image',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.image,
+      description: 'Card field that receives the captured screenshot or animated image.',
+    },
+    {
+      path: 'ankiConnect.fields.sentence',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.sentence,
+      description: 'Card field that receives the source sentence text.',
+    },
+    {
+      path: 'ankiConnect.fields.miscInfo',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.miscInfo,
+      description:
+        'Card field that receives the miscellaneous info pattern (see ankiConnect.metadata.pattern).',
+    },
+    {
+      path: 'ankiConnect.fields.translation',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.fields.translation,
+      description: 'Card field that receives the current selection or translated text.',
+    },
     {
       path: 'ankiConnect.ai.enabled',
       kind: 'boolean',
@@ -83,6 +120,41 @@ export function buildIntegrationConfigOptionRegistry(
       description: 'Automatically update newly added cards.',
       runtime: runtimeOptionById.get('anki.autoUpdateNewCards'),
     },
+    {
+      path: 'ankiConnect.behavior.overwriteAudio',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.behavior.overwriteAudio,
+      description:
+        'When updating an existing card, overwrite the audio field instead of skipping it.',
+    },
+    {
+      path: 'ankiConnect.behavior.overwriteImage',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.behavior.overwriteImage,
+      description:
+        'When updating an existing card, overwrite the image field instead of skipping it.',
+    },
+    {
+      path: 'ankiConnect.behavior.mediaInsertMode',
+      kind: 'enum',
+      enumValues: ['append', 'prepend'],
+      defaultValue: defaultConfig.ankiConnect.behavior.mediaInsertMode,
+      description:
+        'Whether new media is appended after or prepended before existing field contents on update.',
+    },
+    {
+      path: 'ankiConnect.behavior.highlightWord',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.behavior.highlightWord,
+      description: 'Bold the mined word inside the sentence field on the saved Anki card.',
+    },
+    {
+      path: 'ankiConnect.behavior.notificationType',
+      kind: 'enum',
+      enumValues: ['osd', 'system', 'both', 'none'],
+      defaultValue: defaultConfig.ankiConnect.behavior.notificationType,
+      description: 'Notification surface used to announce mining and update outcomes.',
+    },
     {
       path: 'ankiConnect.media.syncAnimatedImageToWordAudio',
       kind: 'boolean',
@@ -90,6 +162,97 @@ export function buildIntegrationConfigOptionRegistry(
       description:
         'For animated AVIF images, prepend a frozen first frame matching the existing word-audio duration so motion starts with sentence audio.',
     },
+    {
+      path: 'ankiConnect.media.generateAudio',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.generateAudio,
+      description: 'Generate sentence audio for mined cards.',
+    },
+    {
+      path: 'ankiConnect.media.generateImage',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.media.generateImage,
+      description: 'Generate screenshot or animated image for mined cards.',
+    },
+    {
+      path: 'ankiConnect.media.imageType',
+      kind: 'enum',
+      enumValues: ['static', 'avif'],
+      defaultValue: defaultConfig.ankiConnect.media.imageType,
+      description:
+        'Image capture type: "static" for a single still frame, "avif" for an animated AVIF.',
+    },
+    {
+      path: 'ankiConnect.media.imageFormat',
+      kind: 'enum',
+      enumValues: ['jpg', 'png', 'webp'],
+      defaultValue: defaultConfig.ankiConnect.media.imageFormat,
+      description: 'Encoding format used when imageType is "static".',
+    },
+    {
+      path: 'ankiConnect.media.imageQuality',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.imageQuality,
+      description: 'Quality (0-100) used for lossy static image encoders.',
+    },
+    {
+      path: 'ankiConnect.media.imageMaxWidth',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.imageMaxWidth,
+      description:
+        'Optional maximum width for static images. Leave unset to preserve the source resolution.',
+    },
+    {
+      path: 'ankiConnect.media.imageMaxHeight',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.imageMaxHeight,
+      description:
+        'Optional maximum height for static images. Leave unset to preserve the source resolution.',
+    },
+    {
+      path: 'ankiConnect.media.animatedFps',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedFps,
+      description: 'Target frame rate for animated AVIF captures.',
+    },
+    {
+      path: 'ankiConnect.media.animatedMaxWidth',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedMaxWidth,
+      description: 'Maximum width applied to animated AVIF captures.',
+    },
+    {
+      path: 'ankiConnect.media.animatedMaxHeight',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedMaxHeight,
+      description:
+        'Optional maximum height for animated AVIF captures. Leave unset to preserve aspect ratio.',
+    },
+    {
+      path: 'ankiConnect.media.animatedCrf',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.animatedCrf,
+      description:
+        'Animated AVIF CRF quality target. Lower values produce larger, higher-quality files.',
+    },
+    {
+      path: 'ankiConnect.media.audioPadding',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.audioPadding,
+      description: 'Seconds of padding appended to both ends of generated sentence audio.',
+    },
+    {
+      path: 'ankiConnect.media.fallbackDuration',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.fallbackDuration,
+      description: 'Fallback clip duration in seconds when subtitle timing data is unavailable.',
+    },
+    {
+      path: 'ankiConnect.media.maxMediaDuration',
+      kind: 'number',
+      defaultValue: defaultConfig.ankiConnect.media.maxMediaDuration,
+      description: 'Maximum allowed media clip duration in seconds.',
+    },
     {
       path: 'ankiConnect.knownWords.matchMode',
       kind: 'enum',
@@ -148,6 +311,44 @@ export function buildIntegrationConfigOptionRegistry(
       description: 'Kiku duplicate-card field grouping mode.',
       runtime: runtimeOptionById.get('anki.kikuFieldGrouping'),
     },
+    {
+      path: 'ankiConnect.isKiku.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isKiku.enabled,
+      description: 'Enable Kiku-specific mining behaviors (duplicate handling, field grouping).',
+    },
+    {
+      path: 'ankiConnect.isKiku.deleteDuplicateInAuto',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isKiku.deleteDuplicateInAuto,
+      description:
+        'When Kiku field grouping is "auto", delete the duplicate source card after grouping completes.',
+    },
+    {
+      path: 'ankiConnect.isLapis.enabled',
+      kind: 'boolean',
+      defaultValue: defaultConfig.ankiConnect.isLapis.enabled,
+      description: 'Enable Lapis-specific mining behaviors and sentence card model targeting.',
+    },
+    {
+      path: 'ankiConnect.isLapis.sentenceCardModel',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.isLapis.sentenceCardModel,
+      description: 'Note type name used by Lapis sentence cards.',
+    },
+    {
+      path: 'ankiConnect.metadata.pattern',
+      kind: 'string',
+      defaultValue: defaultConfig.ankiConnect.metadata.pattern,
+      description:
+        'Template used to render the miscInfo field. Placeholders include %f (filename) and %t (timestamp).',
+    },
+    {
+      path: 'jimaku.apiBaseUrl',
+      kind: 'string',
+      defaultValue: defaultConfig.jimaku.apiBaseUrl,
+      description: 'Base URL of the Jimaku subtitle search API.',
+    },
     {
       path: 'jimaku.languagePreference',
       kind: 'enum',
@@ -277,6 +478,26 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.jellyfin.username,
       description: 'Default Jellyfin username used during CLI login.',
     },
+    {
+      path: 'jellyfin.deviceId',
+      kind: 'string',
+      defaultValue: defaultConfig.jellyfin.deviceId,
+      description:
+        'Stable device identifier sent on the Jellyfin authentication handshake; primarily internal.',
+    },
+    {
+      path: 'jellyfin.clientName',
+      kind: 'string',
+      defaultValue: defaultConfig.jellyfin.clientName,
+      description: 'Client name sent on the Jellyfin authentication handshake; primarily internal.',
+    },
+    {
+      path: 'jellyfin.clientVersion',
+      kind: 'string',
+      defaultValue: defaultConfig.jellyfin.clientVersion,
+      description:
+        'Client version sent on the Jellyfin authentication handshake; primarily internal.',
+    },
     {
       path: 'jellyfin.defaultLibraryId',
       kind: 'string',
@@ -387,6 +608,18 @@ export function buildIntegrationConfigOptionRegistry(
       defaultValue: defaultConfig.ai.baseUrl,
       description: 'Base URL for the shared OpenAI-compatible AI provider.',
     },
+    {
+      path: 'ai.model',
+      kind: 'string',
+      defaultValue: defaultConfig.ai.model,
+      description: 'Default model identifier requested from the shared AI provider.',
+    },
+    {
+      path: 'ai.systemPrompt',
+      kind: 'string',
+      defaultValue: defaultConfig.ai.systemPrompt,
+      description: 'Default system prompt sent with shared AI provider requests.',
+    },
     {
       path: 'ai.requestTimeoutMs',
       kind: 'number',

src/config/settings/jsonc-edit.test.ts

@@ -0,0 +1,94 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parse } from 'jsonc-parser';
+import { DEFAULT_CONFIG } from '../definitions';
+import { applyConfigSettingsPatchToContent, buildConfigSettingsSnapshot } from './jsonc-edit';
+import { buildConfigSettingsRegistry } from './registry';
+
+test('applyConfigSettingsPatchToContent preserves JSONC comments while setting nested values', () => {
+  const input = `{
+  // keep this comment
+  "subtitleStyle": {
+    "fontSize": 35,
+  },
+}`;
+
+  const result = applyConfigSettingsPatchToContent({
+    content: input,
+    operations: [
+      {
+        op: 'set',
+        path: 'subtitleStyle.autoPauseVideoOnHover',
+        value: false,
+      },
+    ],
+    previousWarnings: [],
+  });
+
+  assert.equal(result.ok, true);
+  assert.match(result.content, /keep this comment/);
+  const parsed = parse(result.content);
+  assert.equal(parsed.subtitleStyle.autoPauseVideoOnHover, false);
+  assert.equal(parsed.subtitleStyle.fontSize, 35);
+});
+
+test('applyConfigSettingsPatchToContent reset removes explicit path', () => {
+  const input = `{
+  "subtitleStyle": {
+    "fontSize": 41,
+    "autoPauseVideoOnHover": false
+  }
+}`;
+
+  const result = applyConfigSettingsPatchToContent({
+    content: input,
+    operations: [{ op: 'reset', path: 'subtitleStyle.autoPauseVideoOnHover' }],
+    previousWarnings: [],
+  });
+
+  assert.equal(result.ok, true);
+  const parsed = parse(result.content);
+  assert.equal(Object.hasOwn(parsed.subtitleStyle, 'autoPauseVideoOnHover'), false);
+  assert.equal(parsed.subtitleStyle.fontSize, 41);
+});
+
+test('applyConfigSettingsPatchToContent rejects warnings caused by modified fields', () => {
+  const result = applyConfigSettingsPatchToContent({
+    content: '{}',
+    operations: [
+      {
+        op: 'set',
+        path: 'subtitleStyle.autoPauseVideoOnHover',
+        value: 'bad',
+      },
+    ],
+    previousWarnings: [],
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.warnings[0]?.path, 'subtitleStyle.autoPauseVideoOnHover');
+});
+
+test('buildConfigSettingsSnapshot masks configured secret values', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const snapshot = buildConfigSettingsSnapshot({
+    configPath: '/tmp/config.jsonc',
+    rawConfig: {
+      ai: {
+        apiKey: 'secret-key',
+      },
+    },
+    resolvedConfig: {
+      ...DEFAULT_CONFIG,
+      ai: {
+        ...DEFAULT_CONFIG.ai,
+        apiKey: 'secret-key',
+      },
+    },
+    warnings: [],
+    fields,
+  });
+
+  const apiKey = snapshot.values['ai.apiKey'];
+  assert.deepEqual(apiKey, { configured: true });
+});

src/config/settings/jsonc-edit.ts

@@ -0,0 +1,200 @@
+import {
+  applyEdits,
+  modify,
+  parse as parseJsonc,
+  type FormattingOptions,
+  type ParseError,
+} from 'jsonc-parser';
+import type { ConfigValidationWarning, RawConfig, ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsField,
+  ConfigSettingsPatchOperation,
+  ConfigSettingsSnapshot,
+} from '../../types/settings';
+import { resolveConfig } from '../resolve';
+import { getConfigValueAtPath } from './registry';
+
+const JSONC_FORMATTING_OPTIONS: FormattingOptions = {
+  insertSpaces: true,
+  tabSize: 2,
+  eol: '\n',
+};
+
+export type ConfigSettingsPatchApplyResult =
+  | {
+      ok: true;
+      content: string;
+      rawConfig: RawConfig;
+      resolvedConfig: ResolvedConfig;
+      warnings: ConfigValidationWarning[];
+    }
+  | {
+      ok: false;
+      content: string;
+      warnings: ConfigValidationWarning[];
+      error: string;
+    };
+
+interface ApplyConfigSettingsPatchOptions {
+  content: string;
+  operations: ConfigSettingsPatchOperation[];
+  previousWarnings: ConfigValidationWarning[];
+}
+
+interface BuildConfigSettingsSnapshotOptions {
+  configPath: string;
+  rawConfig: RawConfig;
+  resolvedConfig: ResolvedConfig;
+  warnings: ConfigValidationWarning[];
+  fields: ConfigSettingsField[];
+}
+
+function pathToSegments(path: string): string[] {
+  return path.split('.').filter(Boolean);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pathStartsWith(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}.`);
+}
+
+function warningBelongsToModifiedPath(
+  warning: ConfigValidationWarning,
+  operation: ConfigSettingsPatchOperation,
+): boolean {
+  return (
+    pathStartsWith(warning.path, operation.path) || pathStartsWith(operation.path, warning.path)
+  );
+}
+
+function warningIdentity(warning: ConfigValidationWarning): string {
+  return `${warning.path}\n${JSON.stringify(warning.value)}\n${warning.message}`;
+}
+
+function parseRawConfig(content: string): RawConfig {
+  const errors: ParseError[] = [];
+  const parsed = parseJsonc(content || '{}', errors, {
+    allowTrailingComma: true,
+    disallowComments: false,
+  });
+  if (errors.length > 0) {
+    throw new Error(`Invalid JSONC (${errors[0]?.error ?? 'unknown'})`);
+  }
+  return isRecord(parsed) ? (parsed as RawConfig) : {};
+}
+
+function normalizeContent(content: string): string {
+  return content.trim().length > 0 ? content : '{}\n';
+}
+
+function applySingleOperation(content: string, operation: ConfigSettingsPatchOperation): string {
+  const edits = modify(
+    content,
+    pathToSegments(operation.path),
+    operation.op === 'reset' ? undefined : operation.value,
+    {
+      formattingOptions: JSONC_FORMATTING_OPTIONS,
+      getInsertionIndex: (properties) => properties.length,
+    },
+  );
+  return applyEdits(content, edits);
+}
+
+function collectModifiedWarnings(
+  warnings: ConfigValidationWarning[],
+  operations: ConfigSettingsPatchOperation[],
+  previousWarnings: ConfigValidationWarning[],
+): ConfigValidationWarning[] {
+  const previous = new Set(previousWarnings.map(warningIdentity));
+  return warnings.filter((warning) => {
+    if (!operations.some((operation) => warningBelongsToModifiedPath(warning, operation))) {
+      return false;
+    }
+    return !previous.has(warningIdentity(warning));
+  });
+}
+
+export function applyConfigSettingsPatchToContent(
+  options: ApplyConfigSettingsPatchOptions,
+): ConfigSettingsPatchApplyResult {
+  let content = normalizeContent(options.content);
+
+  try {
+    parseRawConfig(content);
+  } catch (error) {
+    return {
+      ok: false,
+      content,
+      warnings: [],
+      error: error instanceof Error ? error.message : 'Invalid JSONC.',
+    };
+  }
+
+  try {
+    for (const operation of options.operations) {
+      content = applySingleOperation(content, operation);
+    }
+
+    const rawConfig = parseRawConfig(content);
+    const { resolved, warnings } = resolveConfig(rawConfig);
+    const modifiedWarnings = collectModifiedWarnings(
+      warnings,
+      options.operations,
+      options.previousWarnings,
+    );
+    if (modifiedWarnings.length > 0) {
+      return {
+        ok: false,
+        content,
+        warnings: modifiedWarnings,
+        error: 'One or more modified settings failed validation.',
+      };
+    }
+
+    return {
+      ok: true,
+      content,
+      rawConfig,
+      resolvedConfig: resolved,
+      warnings,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      content,
+      warnings: [],
+      error: error instanceof Error ? error.message : 'Failed to update config content.',
+    };
+  }
+}
+
+export function buildConfigSettingsSnapshot(
+  options: BuildConfigSettingsSnapshotOptions,
+): ConfigSettingsSnapshot {
+  const values: Record<string, unknown> = {};
+
+  for (const field of options.fields) {
+    const rawValue = getConfigValueAtPath(options.rawConfig, field.configPath);
+    const resolvedValue = getConfigValueAtPath(options.resolvedConfig, field.configPath);
+    if (field.secret) {
+      values[field.configPath] = {
+        configured:
+          (typeof rawValue === 'string' && rawValue.length > 0) ||
+          (typeof resolvedValue === 'string' && resolvedValue.length > 0),
+      };
+      continue;
+    }
+
+    values[field.configPath] = structuredClone(rawValue !== undefined ? rawValue : resolvedValue);
+  }
+
+  return {
+    configPath: options.configPath,
+    fields: options.fields,
+    values,
+    warnings: options.warnings,
+  };
+}

src/config/settings/registry.test.ts

@@ -0,0 +1,39 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { DEFAULT_CONFIG } from '../definitions';
+import {
+  buildConfigSettingsRegistry,
+  getConfigSettingsCoverage,
+  LEGACY_HIDDEN_CONFIG_PATHS,
+} from './registry';
+
+test('config settings registry places hover pause under viewing playback behavior', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const hoverPause = fields.find(
+    (field) => field.configPath === 'subtitleStyle.autoPauseVideoOnHover',
+  );
+
+  assert.ok(hoverPause);
+  assert.equal(hoverPause.category, 'viewing');
+  assert.equal(hoverPause.section, 'Playback pause behavior');
+  assert.equal(hoverPause.control, 'boolean');
+});
+
+test('config settings registry hides legacy and ignored paths from normal fields', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const visiblePaths = new Set(
+    fields.filter((field) => !field.legacyHidden).map((field) => field.configPath),
+  );
+
+  for (const path of LEGACY_HIDDEN_CONFIG_PATHS) {
+    assert.equal(visiblePaths.has(path), false, path);
+  }
+  assert.equal(visiblePaths.has('controller.buttonIndices'), false);
+});
+
+test('config settings registry covers canonical defaults or marks explicit raw-only gaps', () => {
+  const fields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
+  const coverage = getConfigSettingsCoverage(DEFAULT_CONFIG, fields);
+
+  assert.deepEqual(coverage.uncoveredDefaultPaths, []);
+});

src/config/settings/registry.ts

@@ -0,0 +1,346 @@
+import type { ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsCategory,
+  ConfigSettingsControl,
+  ConfigSettingsField,
+  ConfigSettingsRestartBehavior,
+} from '../../types/settings';
+import { CONFIG_OPTION_REGISTRY, DEFAULT_CONFIG } from '../definitions';
+
+type Leaf = {
+  path: string;
+  value: unknown;
+};
+
+export const LEGACY_HIDDEN_CONFIG_PATHS = [
+  'ankiConnect.deck',
+  'ankiConnect.wordField',
+  'ankiConnect.audioField',
+  'ankiConnect.imageField',
+  'ankiConnect.sentenceField',
+  'ankiConnect.miscInfoField',
+  'ankiConnect.miscInfoPattern',
+  'ankiConnect.generateAudio',
+  'ankiConnect.generateImage',
+  'ankiConnect.imageType',
+  'ankiConnect.imageFormat',
+  'ankiConnect.imageQuality',
+  'ankiConnect.imageMaxWidth',
+  'ankiConnect.imageMaxHeight',
+  'ankiConnect.animatedFps',
+  'ankiConnect.animatedMaxWidth',
+  'ankiConnect.animatedMaxHeight',
+  'ankiConnect.animatedCrf',
+  'ankiConnect.syncAnimatedImageToWordAudio',
+  'ankiConnect.audioPadding',
+  'ankiConnect.fallbackDuration',
+  'ankiConnect.maxMediaDuration',
+  'ankiConnect.overwriteAudio',
+  'ankiConnect.overwriteImage',
+  'ankiConnect.mediaInsertMode',
+  'ankiConnect.highlightWord',
+  'ankiConnect.notificationType',
+  'ankiConnect.autoUpdateNewCards',
+  'ankiConnect.nPlusOne.highlightEnabled',
+  'ankiConnect.nPlusOne.refreshMinutes',
+  'ankiConnect.nPlusOne.matchMode',
+  'ankiConnect.nPlusOne.decks',
+  'ankiConnect.nPlusOne.knownWord',
+  'ankiConnect.behavior.nPlusOneHighlightEnabled',
+  'ankiConnect.behavior.nPlusOneRefreshMinutes',
+  'ankiConnect.behavior.nPlusOneMatchMode',
+  'ankiConnect.isLapis.sentenceCardSentenceField',
+  'ankiConnect.isLapis.sentenceCardAudioField',
+  'youtubeSubgen.primarySubLanguages',
+  'anilist.characterDictionary.refreshTtlHours',
+  'anilist.characterDictionary.evictionPolicy',
+  'jellyfin.accessToken',
+  'jellyfin.userId',
+  'controller.buttonIndices',
+] as const;
+
+const EXCLUDED_PREFIXES = ['controller.buttonIndices'] as const;
+
+const JSON_OBJECT_FIELDS = new Set([
+  'keybindings',
+  'controller.bindings',
+  'controller.profiles',
+  'ankiConnect.knownWords.decks',
+]);
+
+const SECRET_PATHS = new Set(['ai.apiKey', 'jimaku.apiKey', 'anilist.accessToken']);
+
+const COLOR_SUFFIXES = new Set([
+  'Color',
+  'color',
+  'backgroundColor',
+  'singleColor',
+  'knownWordColor',
+  'nPlusOne',
+]);
+
+const OPTION_BY_PATH = new Map(CONFIG_OPTION_REGISTRY.map((entry) => [entry.path, entry]));
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pathStartsWith(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}.`);
+}
+
+function isLegacyHidden(path: string): boolean {
+  return (
+    LEGACY_HIDDEN_CONFIG_PATHS.some((hiddenPath) => pathStartsWith(path, hiddenPath)) ||
+    EXCLUDED_PREFIXES.some((prefix) => pathStartsWith(path, prefix))
+  );
+}
+
+function flattenConfigLeaves(value: unknown, prefix = ''): Leaf[] {
+  if (JSON_OBJECT_FIELDS.has(prefix)) {
+    return [{ path: prefix, value }];
+  }
+
+  if (Array.isArray(value)) {
+    return [{ path: prefix, value }];
+  }
+
+  if (isRecord(value)) {
+    const entries = Object.entries(value).filter(([, child]) => child !== undefined);
+    if (entries.length === 0) {
+      return [{ path: prefix, value }];
+    }
+    return entries.flatMap(([key, child]) =>
+      flattenConfigLeaves(child, prefix ? `${prefix}.${key}` : key),
+    );
+  }
+
+  return prefix ? [{ path: prefix, value }] : [];
+}
+
+function humanizePath(path: string): string {
+  const key = path.split('.').at(-1) ?? path;
+  const spaced = key
+    .replace(/_/g, ' ')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/\bai\b/i, 'AI')
+    .replace(/\bmpv\b/i, 'mpv')
+    .replace(/\byomitan\b/i, 'Yomitan')
+    .replace(/\bjimaku\b/i, 'Jimaku')
+    .replace(/\banilist\b/i, 'AniList')
+    .replace(/\banki\b/i, 'Anki');
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+function categoryAndSection(path: string): { category: ConfigSettingsCategory; section: string } {
+  if (
+    path === 'subtitleStyle.autoPauseVideoOnHover' ||
+    path === 'subtitleStyle.autoPauseVideoOnYomitanPopup' ||
+    path === 'subtitleSidebar.pauseVideoOnHover'
+  ) {
+    return { category: 'viewing', section: 'Playback pause behavior' };
+  }
+  if (
+    path.startsWith('ankiConnect.knownWords.') ||
+    path.startsWith('ankiConnect.nPlusOne.') ||
+    path.startsWith('subtitleStyle.frequencyDictionary.') ||
+    path.startsWith('subtitleStyle.jlptColors.') ||
+    path === 'subtitleStyle.enableJlpt' ||
+    path === 'subtitleStyle.nameMatchEnabled' ||
+    path === 'subtitleStyle.nameMatchColor'
+  ) {
+    return { category: 'viewing', section: 'Annotation display' };
+  }
+  if (path.startsWith('subtitleStyle.secondary.')) {
+    return { category: 'viewing', section: 'Secondary subtitle appearance' };
+  }
+  if (path.startsWith('subtitleStyle.')) {
+    return { category: 'viewing', section: 'Primary subtitle appearance' };
+  }
+  if (path.startsWith('subtitleSidebar.')) {
+    return { category: 'viewing', section: 'Subtitle sidebar' };
+  }
+  if (path.startsWith('subtitlePosition.') || path.startsWith('secondarySub.')) {
+    return { category: 'viewing', section: 'Subtitle behavior' };
+  }
+  if (path.startsWith('ankiConnect.fields.')) {
+    return { category: 'mining-anki', section: 'Note fields' };
+  }
+  if (path.startsWith('ankiConnect.media.')) {
+    return { category: 'mining-anki', section: 'Media capture' };
+  }
+  if (path.startsWith('ankiConnect.isKiku.') || path.startsWith('ankiConnect.isLapis.')) {
+    return { category: 'mining-anki', section: 'Kiku and Lapis' };
+  }
+  if (path.startsWith('ankiConnect.ai.')) {
+    return { category: 'mining-anki', section: 'Anki AI' };
+  }
+  if (path.startsWith('ankiConnect.proxy.')) {
+    return { category: 'mining-anki', section: 'AnkiConnect proxy' };
+  }
+  if (path.startsWith('ankiConnect.')) {
+    return { category: 'mining-anki', section: 'AnkiConnect' };
+  }
+  if (
+    path.startsWith('mpv.') ||
+    path.startsWith('youtube.') ||
+    path.startsWith('youtubeSubgen.') ||
+    path.startsWith('jimaku.') ||
+    path.startsWith('subsync.')
+  ) {
+    return { category: 'playback-sources', section: topSection(path) };
+  }
+  if (path.startsWith('shortcuts.')) {
+    return { category: 'input', section: 'Overlay shortcuts' };
+  }
+  if (path === 'keybindings') {
+    return { category: 'input', section: 'MPV keybindings' };
+  }
+  if (path.startsWith('controller.')) {
+    return { category: 'input', section: 'Controller' };
+  }
+  if (
+    path.startsWith('ai.') ||
+    path.startsWith('anilist.') ||
+    path.startsWith('yomitan.') ||
+    path.startsWith('jellyfin.') ||
+    path.startsWith('discordPresence.') ||
+    path.startsWith('websocket.') ||
+    path.startsWith('annotationWebsocket.') ||
+    path.startsWith('texthooker.')
+  ) {
+    return { category: 'integrations', section: topSection(path) };
+  }
+  if (
+    path.startsWith('immersionTracking.') ||
+    path.startsWith('stats.') ||
+    path.startsWith('updates.') ||
+    path.startsWith('startupWarmups.') ||
+    path.startsWith('logging.') ||
+    path === 'auto_start_overlay'
+  ) {
+    return { category: 'tracking-app', section: topSection(path) };
+  }
+  return { category: 'advanced', section: 'Advanced' };
+}
+
+function topSection(path: string): string {
+  const top = path.split('.')[0] ?? path;
+  const labels: Record<string, string> = {
+    ai: 'Shared AI provider',
+    anilist: 'AniList',
+    annotationWebsocket: 'Annotation WebSocket',
+    discordPresence: 'Discord Rich Presence',
+    immersionTracking: 'Immersion tracking',
+    jimaku: 'Jimaku',
+    jellyfin: 'Jellyfin',
+    logging: 'Logging',
+    mpv: 'mpv launcher',
+    stats: 'Stats dashboard',
+    startupWarmups: 'Startup warmups',
+    subsync: 'Auto subtitle sync',
+    texthooker: 'Texthooker',
+    updates: 'Updates',
+    websocket: 'WebSocket server',
+    yomitan: 'Yomitan',
+    youtube: 'YouTube playback',
+    youtubeSubgen: 'YouTube subtitle generation',
+    auto_start_overlay: 'Overlay startup',
+  };
+  return labels[top] ?? humanizePath(top);
+}
+
+function controlForPath(path: string, value: unknown): ConfigSettingsControl {
+  if (SECRET_PATHS.has(path)) return 'secret';
+  if (OPTION_BY_PATH.get(path)?.enumValues?.length) return 'select';
+  if (JSON_OBJECT_FIELDS.has(path)) return 'json';
+  if (Array.isArray(value)) return 'string-list';
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'string') {
+    const leaf = path.split('.').at(-1) ?? path;
+    if ([...COLOR_SUFFIXES].some((suffix) => leaf.endsWith(suffix))) return 'color';
+    if (leaf.toLowerCase().includes('prompt')) return 'textarea';
+    return 'text';
+  }
+  return 'json';
+}
+
+function restartBehaviorForPath(path: string): ConfigSettingsRestartBehavior {
+  if (
+    path === 'keybindings' ||
+    pathStartsWith(path, 'shortcuts') ||
+    pathStartsWith(path, 'subtitleStyle') ||
+    pathStartsWith(path, 'subtitleSidebar') ||
+    path === 'secondarySub.defaultMode' ||
+    pathStartsWith(path, 'ankiConnect.ai')
+  ) {
+    return 'hot-reload';
+  }
+  return 'restart';
+}
+
+function fieldForLeaf(leaf: Leaf): ConfigSettingsField {
+  const option = OPTION_BY_PATH.get(leaf.path);
+  const { category, section } = categoryAndSection(leaf.path);
+  return {
+    id: leaf.path,
+    label: option?.path === leaf.path ? humanizePath(leaf.path) : humanizePath(leaf.path),
+    description: option?.description ?? `${humanizePath(leaf.path)} setting.`,
+    configPath: leaf.path,
+    category,
+    section,
+    control: controlForPath(leaf.path, leaf.value),
+    defaultValue: leaf.value,
+    ...(option?.enumValues ? { enumValues: option.enumValues } : {}),
+    restartBehavior: restartBehaviorForPath(leaf.path),
+    advanced:
+      leaf.path.startsWith('controller.') ||
+      leaf.path.startsWith('immersionTracking.retention.') ||
+      leaf.path.startsWith('youtubeSubgen.'),
+    secret: SECRET_PATHS.has(leaf.path),
+  };
+}
+
+export function buildConfigSettingsRegistry(
+  defaultConfig: ResolvedConfig = DEFAULT_CONFIG,
+): ConfigSettingsField[] {
+  const leaves = flattenConfigLeaves(defaultConfig).filter((leaf) => !isLegacyHidden(leaf.path));
+  return leaves.map(fieldForLeaf).sort((a, b) => {
+    const category = a.category.localeCompare(b.category);
+    if (category !== 0) return category;
+    const section = a.section.localeCompare(b.section);
+    if (section !== 0) return section;
+    return a.configPath.localeCompare(b.configPath);
+  });
+}
+
+export function getConfigSettingsCoverage(
+  defaultConfig: ResolvedConfig,
+  fields: ConfigSettingsField[],
+): { uncoveredDefaultPaths: string[] } {
+  const visibleFields = fields.filter((field) => !field.legacyHidden);
+  const uncoveredDefaultPaths = flattenConfigLeaves(defaultConfig)
+    .map((leaf) => leaf.path)
+    .filter((path) => !isLegacyHidden(path))
+    .filter(
+      (path) =>
+        !visibleFields.some(
+          (field) =>
+            field.configPath === path ||
+            (field.control === 'json' && pathStartsWith(path, field.configPath)),
+        ),
+    )
+    .sort();
+
+  return { uncoveredDefaultPaths };
+}
+
+export function getConfigValueAtPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of path.split('.')) {
+    if (!isRecord(current)) return undefined;
+    current = current[segment];
+  }
+  return current;
+}

src/core/services/app-lifecycle.test.ts

@@ -15,6 +15,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,

src/core/services/cli-command.test.ts

@@ -16,6 +16,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggle: false,
     toggleVisibleOverlay: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,
@@ -130,6 +131,9 @@ function createDeps(overrides: Partial<CliCommandServiceDeps> = {}) {
     openYomitanSettingsDelayed: (delayMs) => {
       calls.push(`openYomitanSettingsDelayed:${delayMs}`);
     },
+    openConfigSettingsWindow: () => {
+      calls.push('openConfigSettingsWindow');
+    },
     openFirstRunSetup: (force?: boolean) => {
       calls.push(`openFirstRunSetup:${force === true ? 'force' : 'default'}`);
     },
@@ -582,6 +586,7 @@ test('handleCliCommand handles visibility and utility command dispatches', () =>
     expected: string;
   }> = [
     { args: { settings: true }, expected: 'openYomitanSettingsDelayed:1000' },
+    { args: { configSettings: true }, expected: 'openConfigSettingsWindow' },
     {
       args: { showVisibleOverlay: true },
       expected: 'setVisibleOverlayVisible:true',

src/core/services/cli-command.ts

@@ -43,6 +43,7 @@ export interface CliCommandServiceDeps {
   togglePrimarySubtitleBar: () => void;
   openFirstRunSetup: (force?: boolean) => void;
   openYomitanSettingsDelayed: (delayMs: number) => void;
+  openConfigSettingsWindow: () => void;
   setVisibleOverlayVisible: (visible: boolean) => void;
   copyCurrentSubtitle: () => void;
   startPendingMultiCopy: (timeoutMs: number) => void;
@@ -160,6 +161,7 @@ interface MiningCliRuntime {
 interface UiCliRuntime {
   openFirstRunSetup: (force?: boolean) => void;
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -257,6 +259,7 @@ export function createCliCommandDepsRuntime(
         options.ui.openYomitanSettings();
       }, delayMs);
     },
+    openConfigSettingsWindow: options.ui.openConfigSettingsWindow,
     setVisibleOverlayVisible: options.overlay.setVisible,
     copyCurrentSubtitle: options.mining.copyCurrentSubtitle,
     startPendingMultiCopy: options.mining.startPendingMultiCopy,
@@ -385,6 +388,8 @@ export function handleCliCommand(
     deps.logDebug('Opened first-run setup flow.');
   } else if (args.settings) {
     deps.openYomitanSettingsDelayed(1000);
+  } else if (args.configSettings) {
+    deps.openConfigSettingsWindow();
   } else if (args.show || args.showVisibleOverlay) {
     deps.setVisibleOverlayVisible(true);
   } else if (args.hide || args.hideVisibleOverlay) {

src/core/services/startup-bootstrap.test.ts

@@ -15,6 +15,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,

src/core/services/yomitan-extension-copy.ts

@@ -142,10 +142,7 @@ export function shouldCopyYomitanExtension(sourceDir: string, targetDir: string)
   return sourceHash === null || targetHash === null || sourceHash !== targetHash;
 }
 
-export function ensureExtensionCopy(
-  sourceDir: string,
-  userDataPath: string,
-): ExtensionCopyResult {
+export function ensureExtensionCopy(sourceDir: string, userDataPath: string): ExtensionCopyResult {
   if (process.platform === 'win32') {
     return { targetDir: sourceDir, copied: false };
   }

src/core/services/yomitan-settings.test.ts

@@ -15,12 +15,14 @@ import {
 test('yomitan settings window uses a close-only menu without app quit', () => {
   const calls: string[] = [];
 
-  configureYomitanSettingsWindowChrome({
+  configureYomitanSettingsWindowChrome(
+    {
       isDestroyed: () => false,
       close: () => calls.push('close'),
       setAutoHideMenuBar: (hide: boolean) => calls.push(`auto-hide:${hide}`),
       setMenu: (menu: unknown) => calls.push(`menu:${menu === null ? 'null' : 'custom'}`),
-  } as never, (template) => {
+    } as never,
+    (template) => {
       calls.push(`menu-label:${template[0]?.label ?? ''}`);
       const submenu = template[0]?.submenu;
       assert.ok(Array.isArray(submenu));
@@ -29,7 +31,8 @@ test('yomitan settings window uses a close-only menu without app quit', () => {
       assert.notEqual(closeItem?.role, 'quit');
       closeItem?.click?.({} as never, {} as never, {} as never);
       return { id: 'settings-menu' } as never;
-  });
+    },
+  );
 
   assert.deepEqual(calls, ['auto-hide:false', 'menu-label:File', 'close', 'menu:custom']);
 });

src/main.ts

@@ -20,6 +20,8 @@ import {
   BrowserWindow,
   clipboard,
   globalShortcut,
+  ipcMain,
+  net,
   shell,
   protocol,
   Extension,
@@ -75,28 +77,6 @@ function getDefaultPasswordStore(): string {
   return 'gnome-libsecret';
 }
 
-function getStartupModeFlags(initialArgs: CliArgs | null | undefined): {
-  shouldUseMinimalStartup: boolean;
-  shouldSkipHeavyStartup: boolean;
-} {
-  return {
-    shouldUseMinimalStartup: Boolean(
-      (initialArgs && isStandaloneTexthookerCommand(initialArgs)) ||
-      initialArgs?.update ||
-      (initialArgs?.stats &&
-        (initialArgs.statsCleanup || initialArgs.statsBackground || initialArgs.statsStop)),
-    ),
-    shouldSkipHeavyStartup: Boolean(
-      initialArgs &&
-      (shouldRunSettingsOnlyStartup(initialArgs) ||
-        initialArgs.stats ||
-        initialArgs.dictionary ||
-        initialArgs.update ||
-        initialArgs.setup),
-    ),
-  };
-}
-
 protocol.registerSchemesAsPrivileged([
   {
     scheme: 'chrome-extension',
@@ -152,15 +132,18 @@ import {
   commandNeedsOverlayStartupPrereqs,
   commandNeedsOverlayRuntime,
   isHeadlessInitialCommand,
-  isStandaloneTexthookerCommand,
   parseArgs,
-  shouldRunSettingsOnlyStartup,
   shouldStartApp,
   type CliArgs,
   type CliCommandSource,
 } from './cli/args';
 import { printHelp } from './cli/help';
 import { IPC_CHANNELS, type OverlayHostedModal } from './shared/ipc/contracts';
+import {
+  getStartupModeFlags,
+  shouldRefreshAnilistOnConfigReload,
+  shouldStartAutomaticUpdateChecks,
+} from './main/runtime/startup-mode-flags';
 import {
   buildConfigParseErrorDetails,
   buildConfigWarningDialogDetails,
@@ -515,6 +498,8 @@ import {
   createElectronAppUpdater,
   isNativeUpdaterSupported,
 } from './main/runtime/update/app-updater';
+import { createElectronNetFetch } from './main/runtime/update/fetch-adapter';
+import { createCurlHttpExecutor } from './main/runtime/update/curl-http-executor';
 import {
   fetchLatestStableRelease,
   fetchReleaseAssetBuffer,
@@ -523,6 +508,7 @@ import {
   parseSha256Sums,
   type GitHubRelease,
 } from './main/runtime/update/release-assets';
+import { shouldFetchReleaseMetadataForPlatform } from './main/runtime/update/release-metadata-policy';
 import { updateLauncherFromRelease } from './main/runtime/update/launcher-updater';
 import { notifyUpdateAvailable } from './main/runtime/update/update-notifications';
 import { createUpdateDialogPresenter } from './main/runtime/update/update-dialogs';
@@ -541,9 +527,11 @@ import {
 } from './main/runtime/subtitle-prefetch-runtime';
 import {
   createCreateAnilistSetupWindowHandler,
+  createCreateConfigSettingsWindowHandler,
   createCreateFirstRunSetupWindowHandler,
   createCreateJellyfinSetupWindowHandler,
 } from './main/runtime/setup-window-factory';
+import { createConfigSettingsRuntime } from './main/runtime/config-settings-runtime';
 import { isYoutubePlaybackActive } from './main/runtime/youtube-playback';
 import { createYomitanProfilePolicy } from './main/runtime/yomitan-profile-policy';
 import { formatSkippedYomitanWriteAction } from './main/runtime/yomitan-read-only-log';
@@ -577,6 +565,7 @@ import {
   generateConfigTemplate,
 } from './config';
 import { resolveConfigDir } from './config/path-resolution';
+import { buildConfigSettingsRegistry } from './config/settings/registry';
 import { parseSubtitleCues } from './core/services/subtitle-cue-parser';
 import {
   createSubtitlePrefetchService,
@@ -835,6 +824,7 @@ const {
   appState,
   appLifecycleApp,
 } = bootServices;
+const configSettingsFields = buildConfigSettingsRegistry(DEFAULT_CONFIG);
 notifyAnilistTokenStoreWarning = (message: string) => {
   logger.warn(`[AniList] ${message}`);
   try {
@@ -1777,6 +1767,9 @@ const buildConfigHotReloadAppliedMainDepsHandler = createBuildConfigHotReloadApp
     },
   },
 );
+const applyConfigHotReloadDiff = createConfigHotReloadAppliedHandler(
+  buildConfigHotReloadAppliedMainDepsHandler(),
+);
 const buildConfigHotReloadRuntimeMainDepsHandler = createBuildConfigHotReloadRuntimeMainDepsHandler(
   {
     getCurrentConfig: () => getResolvedConfig(),
@@ -1785,9 +1778,7 @@ const buildConfigHotReloadRuntimeMainDepsHandler = createBuildConfigHotReloadRun
     setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
     clearTimeout: (timeout) => clearTimeout(timeout),
     debounceMs: 250,
-    onHotReloadApplied: createConfigHotReloadAppliedHandler(
-      buildConfigHotReloadAppliedMainDepsHandler(),
-    ),
+    onHotReloadApplied: applyConfigHotReloadDiff,
     onRestartRequired: (fields) =>
       notifyConfigHotReloadMessage(buildRestartRequiredConfigMessage(fields)),
     onInvalidConfig: notifyConfigHotReloadMessage,
@@ -1808,6 +1799,32 @@ const configHotReloadRuntime = createConfigHotReloadRuntime(
   buildConfigHotReloadRuntimeMainDepsHandler(),
 );
 
+const configSettingsRuntime = createConfigSettingsRuntime({
+  fields: configSettingsFields,
+  getConfigPath: () => configService.getConfigPath(),
+  getRawConfig: () => configService.getRawConfig(),
+  getConfig: () => configService.getConfig(),
+  getWarnings: () => configService.getWarnings(),
+  reloadConfigStrict: () => configService.reloadConfigStrict(),
+  applyHotReload: (diff, config) => applyConfigHotReloadDiff(diff, config),
+  getSettingsWindow: () => appState.configSettingsWindow,
+  setSettingsWindow: (window) => {
+    appState.configSettingsWindow = window as BrowserWindow | null;
+  },
+  createSettingsWindow: createCreateConfigSettingsWindowHandler({
+    createBrowserWindow: (options) => new BrowserWindow(options),
+    preloadPath: path.join(__dirname, 'preload-settings.js'),
+  }),
+  settingsHtmlPath: path.join(__dirname, 'settings', 'index.html'),
+  openPath: (targetPath) => shell.openPath(targetPath),
+  ipcMain,
+  ipcChannels: IPC_CHANNELS.request,
+  log: (message) => logger.error(message),
+});
+
+configSettingsRuntime.registerHandlers();
+const openConfigSettingsWindow = () => configSettingsRuntime.openWindow();
+
 const buildDictionaryRootsHandler = createBuildDictionaryRootsMainHandler({
   platform: process.platform,
   dirname: __dirname,
@@ -3759,7 +3776,7 @@ const { appReadyRuntimeRunner } = composeAppReadyRuntime({
     showDesktopNotification: (title, options) => showDesktopNotification(title, options),
     startConfigHotReload: () => configHotReloadRuntime.start(),
     shouldRefreshAnilistClientSecretState: () =>
-      !(appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs)),
+      shouldRefreshAnilistOnConfigReload(appState.initialArgs),
     refreshAnilistClientSecretState: (options) => refreshAnilistClientSecretStateIfEnabled(options),
     failHandlers: {
       logError: (details) => logger.error(details),
@@ -4636,9 +4653,12 @@ flushPendingMpvLogWrites = () => {
 
 const updateStateStore = createFileUpdateStateStore(path.join(USER_DATA_PATH, 'update-state.json'));
 let updateService: ReturnType<typeof createUpdateService> | null = null;
+const electronNetFetch = createElectronNetFetch({
+  fetch: (url, init) => net.fetch(url, init as RequestInit),
+});
 
 function getFetchForUpdater() {
-  return globalThis.fetch.bind(globalThis);
+  return electronNetFetch;
 }
 
 async function updateLauncherFromSelectedRelease(
@@ -4685,6 +4705,9 @@ function getUpdateService() {
     isPackaged: app.isPackaged,
     log: (message) => logger.info(message),
     getChannel: () => getResolvedConfig().updates.channel,
+    configureHttpExecutor:
+      process.platform === 'darwin' ? () => createCurlHttpExecutor() : undefined,
+    disableDifferentialDownload: process.platform === 'darwin',
     isNativeUpdaterSupported: () =>
       isNativeUpdaterSupported({
         platform: process.platform,
@@ -4706,6 +4729,8 @@ function getUpdateService() {
     readState: () => updateStateStore.readState(),
     writeState: (state) => updateStateStore.writeState(state),
     checkAppUpdate: (channel) => appUpdater.checkForUpdates(channel),
+    shouldFetchReleaseMetadata: ({ appUpdate }) =>
+      shouldFetchReleaseMetadataForPlatform(process.platform, appUpdate),
     fetchLatestStableRelease: (channel) =>
       fetchLatestStableRelease({ fetch: getFetchForUpdater(), channel }),
     updateLauncher: (launcherPath, channel, release) =>
@@ -5412,6 +5437,7 @@ const { handleCliCommand, handleInitialArgs } = composeCliStartupHandlers({
     },
     runYoutubePlaybackFlow: (request) => youtubePlaybackRuntime.runYoutubePlaybackFlow(request),
     openYomitanSettings: () => openYomitanSettings(),
+    openConfigSettingsWindow: () => openConfigSettingsWindow(),
     cycleSecondarySubMode: () => handleCycleSecondarySubMode(),
     openRuntimeOptionsPalette: () => openRuntimeOptionsPalette(),
     printHelp: () => printHelp(DEFAULT_TEXTHOOKER_PORT),
@@ -5526,7 +5552,7 @@ const { runAndApplyStartupState } = composeHeadlessStartupHandlers<
 
 runAndApplyStartupState();
 void app.whenReady().then(() => {
-  if (appState.initialArgs && isHeadlessInitialCommand(appState.initialArgs)) {
+  if (!shouldStartAutomaticUpdateChecks(appState.initialArgs)) {
     return;
   }
   getUpdateService().startAutomaticChecks();
@@ -5621,6 +5647,7 @@ const { ensureTray: ensureTrayHandler, destroyTray: destroyTrayHandler } =
       showWindowsMpvLauncherSetup: () => process.platform === 'win32',
       openYomitanSettings: () => openYomitanSettings(),
       openRuntimeOptionsPalette: () => openRuntimeOptionsPalette(),
+      openConfigSettingsWindow: () => openConfigSettingsWindow(),
       openJellyfinSetupWindow: () => openJellyfinSetupWindow(),
       isJellyfinConfigured: () =>
         isJellyfinConfiguredForTrayRuntime(getJellyfinTrayDiscoveryDeps()),

src/main/cli-runtime.ts

@@ -46,6 +46,7 @@ export interface CliCommandRuntimeServiceContext {
   runUpdateCommand: CliCommandRuntimeServiceDepsParams['app']['runUpdateCommand'];
   runYoutubePlaybackFlow: CliCommandRuntimeServiceDepsParams['app']['runYoutubePlaybackFlow'];
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -127,6 +128,7 @@ function createCliCommandDepsFromContext(
     ui: {
       openFirstRunSetup: context.openFirstRunSetup,
       openYomitanSettings: context.openYomitanSettings,
+      openConfigSettingsWindow: context.openConfigSettingsWindow,
       cycleSecondarySubMode: context.cycleSecondarySubMode,
       openRuntimeOptionsPalette: context.openRuntimeOptionsPalette,
       printHelp: context.printHelp,

src/main/dependencies.ts

@@ -192,6 +192,7 @@ export interface CliCommandRuntimeServiceDepsParams {
   ui: {
     openFirstRunSetup: CliCommandDepsRuntimeOptions['ui']['openFirstRunSetup'];
     openYomitanSettings: CliCommandDepsRuntimeOptions['ui']['openYomitanSettings'];
+    openConfigSettingsWindow: CliCommandDepsRuntimeOptions['ui']['openConfigSettingsWindow'];
     cycleSecondarySubMode: CliCommandDepsRuntimeOptions['ui']['cycleSecondarySubMode'];
     openRuntimeOptionsPalette: CliCommandDepsRuntimeOptions['ui']['openRuntimeOptionsPalette'];
     printHelp: CliCommandDepsRuntimeOptions['ui']['printHelp'];
@@ -373,6 +374,7 @@ export function createCliCommandRuntimeServiceDeps(
     ui: {
       openFirstRunSetup: params.ui.openFirstRunSetup,
       openYomitanSettings: params.ui.openYomitanSettings,
+      openConfigSettingsWindow: params.ui.openConfigSettingsWindow,
       cycleSecondarySubMode: params.ui.cycleSecondarySubMode,
       openRuntimeOptionsPalette: params.ui.openRuntimeOptionsPalette,
       printHelp: params.ui.printHelp,

src/main/runtime/app-runtime-main-deps.ts

@@ -84,8 +84,7 @@ export function createBuildOpenYomitanSettingsMainDepsHandler<TYomitanExt, TWind
       : {}),
     ...(deps.getYomitanExtensionLoadInFlight
       ? {
-          getYomitanExtensionLoadInFlight: () =>
-            deps.getYomitanExtensionLoadInFlight?.() ?? null,
+          getYomitanExtensionLoadInFlight: () => deps.getYomitanExtensionLoadInFlight?.() ?? null,
         }
       : {}),
     openYomitanSettingsWindow: (params: {

src/main/runtime/cli-command-context-deps.test.ts

@@ -70,6 +70,7 @@ test('build cli command context deps maps handlers and values', () => {
       calls.push('run-youtube-playback');
     },
     openYomitanSettings: () => calls.push('yomitan'),
+    openConfigSettingsWindow: () => calls.push('config-settings'),
     cycleSecondarySubMode: () => calls.push('cycle-secondary'),
     openRuntimeOptionsPalette: () => calls.push('runtime-options'),
     printHelp: () => calls.push('help'),

src/main/runtime/cli-command-context-deps.ts

@@ -44,6 +44,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
   runUpdateCommand: CliCommandContextFactoryDeps['runUpdateCommand'];
   runYoutubePlaybackFlow: CliCommandContextFactoryDeps['runYoutubePlaybackFlow'];
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -99,6 +100,7 @@ export function createBuildCliCommandContextDepsHandler(deps: {
     runUpdateCommand: deps.runUpdateCommand,
     runYoutubePlaybackFlow: deps.runYoutubePlaybackFlow,
     openYomitanSettings: deps.openYomitanSettings,
+    openConfigSettingsWindow: deps.openConfigSettingsWindow,
     cycleSecondarySubMode: deps.cycleSecondarySubMode,
     openRuntimeOptionsPalette: deps.openRuntimeOptionsPalette,
     printHelp: deps.printHelp,

src/main/runtime/cli-command-context-factory.test.ts

@@ -74,6 +74,7 @@ test('cli command context factory composes main deps and context handlers', () =
     runUpdateCommand: async () => {},
     runYoutubePlaybackFlow: async () => {},
     openYomitanSettings: () => {},
+    openConfigSettingsWindow: () => {},
     cycleSecondarySubMode: () => {},
     openRuntimeOptionsPalette: () => {},
     printHelp: () => {},

src/main/runtime/cli-command-context-main-deps.test.ts

@@ -100,6 +100,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
       calls.push('run-youtube-playback');
     },
     openYomitanSettings: () => calls.push('open-yomitan'),
+    openConfigSettingsWindow: () => calls.push('open-config-settings'),
     cycleSecondarySubMode: () => calls.push('cycle-secondary'),
     openRuntimeOptionsPalette: () => calls.push('open-runtime-options'),
     printHelp: () => calls.push('help'),
@@ -129,6 +130,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
   deps.initializeOverlay();
   deps.openFirstRunSetup(true);
   deps.setVisibleOverlay(true);
+  deps.openConfigSettingsWindow();
   deps.printHelp();
   await deps.runUpdateCommand({ update: true } as never, 'initial');
 
@@ -137,6 +139,7 @@ test('cli command context main deps builder maps state and callbacks', async ()
     'init-overlay',
     'open-setup:force',
     'set-visible:true',
+    'open-config-settings',
     'help',
     'run-update',
   ]);

src/main/runtime/cli-command-context-main-deps.ts

@@ -57,6 +57,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
   runYoutubePlaybackFlow: CliCommandContextFactoryDeps['runYoutubePlaybackFlow'];
 
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -127,6 +128,7 @@ export function createBuildCliCommandContextMainDepsHandler(deps: {
       deps.runUpdateCommand(args, source),
     runYoutubePlaybackFlow: (request) => deps.runYoutubePlaybackFlow(request),
     openYomitanSettings: () => deps.openYomitanSettings(),
+    openConfigSettingsWindow: () => deps.openConfigSettingsWindow(),
     cycleSecondarySubMode: () => deps.cycleSecondarySubMode(),
     openRuntimeOptionsPalette: () => deps.openRuntimeOptionsPalette(),
     printHelp: () => deps.printHelp(),

src/main/runtime/cli-command-context.test.ts

@@ -56,6 +56,7 @@ function createDeps() {
       runUpdateCommand: async () => {},
       runYoutubePlaybackFlow: async () => {},
       openYomitanSettings: () => {},
+      openConfigSettingsWindow: () => {},
       cycleSecondarySubMode: () => {},
       openRuntimeOptionsPalette: () => {},
       printHelp: () => {},

src/main/runtime/cli-command-context.ts

@@ -49,6 +49,7 @@ export type CliCommandContextFactoryDeps = {
   runUpdateCommand: CliCommandRuntimeServiceContext['runUpdateCommand'];
   runYoutubePlaybackFlow: CliCommandRuntimeServiceContext['runYoutubePlaybackFlow'];
   openYomitanSettings: () => void;
+  openConfigSettingsWindow: () => void;
   cycleSecondarySubMode: () => void;
   openRuntimeOptionsPalette: () => void;
   printHelp: () => void;
@@ -126,6 +127,7 @@ export function createCliCommandContext(
     runUpdateCommand: deps.runUpdateCommand,
     runYoutubePlaybackFlow: deps.runYoutubePlaybackFlow,
     openYomitanSettings: deps.openYomitanSettings,
+    openConfigSettingsWindow: deps.openConfigSettingsWindow,
     cycleSecondarySubMode: deps.cycleSecondarySubMode,
     openRuntimeOptionsPalette: deps.openRuntimeOptionsPalette,
     printHelp: deps.printHelp,

src/main/runtime/command-line-launcher-windows.ts

@@ -47,10 +47,7 @@ export function getUserPath(options: CommonOptions & WindowsPathOptions): string
   return options.getUserPath?.() ?? envOf(options).Path ?? envOf(options).PATH ?? '';
 }
 
-async function setWindowsUserPath(
-  options: CommonOptions & WindowsPathOptions,
-  nextPath: string,
-) {
+async function setWindowsUserPath(options: CommonOptions & WindowsPathOptions, nextPath: string) {
   if (options.setUserPath) {
     await options.setUserPath(nextPath);
     return;
@@ -96,6 +93,7 @@ export async function appendWindowsUserPathDir(
 }
 
 export function defaultBunRepairPath(options: CommonOptions & WindowsPathOptions): string {
-  const userProfile = options.userProfile ?? envOf(options).USERPROFILE ?? options.homeDir ?? os.homedir();
+  const userProfile =
+    options.userProfile ?? envOf(options).USERPROFILE ?? options.homeDir ?? os.homedir();
   return path.win32.join(userProfile, '.bun', 'bin');
 }

src/main/runtime/composers/cli-startup-composer.test.ts

@@ -50,6 +50,7 @@ test('composeCliStartupHandlers returns callable CLI startup handlers', () => {
       runUpdateCommand: async () => {},
       runYoutubePlaybackFlow: async () => {},
       openYomitanSettings: () => {},
+      openConfigSettingsWindow: () => {},
       cycleSecondarySubMode: () => {},
       openRuntimeOptionsPalette: () => {},
       printHelp: () => {},

src/main/runtime/config-settings-ipc.test.ts

@@ -0,0 +1,66 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { isConfigSettingsPatch } from './config-settings-ipc';
+import type { ConfigSettingsField } from '../../types/settings';
+
+const fields: ConfigSettingsField[] = [
+  {
+    id: 'mpv.launchMode',
+    label: 'Launch mode',
+    description: 'Launch mode setting.',
+    configPath: 'mpv.launchMode',
+    category: 'playback-sources',
+    section: 'mpv launcher',
+    control: 'select',
+    defaultValue: 'windowed',
+    restartBehavior: 'restart',
+  },
+];
+
+test('isConfigSettingsPatch rejects set operations without a value property', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'set', path: 'mpv.launchMode' }],
+      },
+      fields,
+    ),
+    false,
+  );
+});
+
+test('isConfigSettingsPatch accepts set operations with an explicit value', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'set', path: 'mpv.launchMode', value: 'fullscreen' }],
+      },
+      fields,
+    ),
+    true,
+  );
+});
+
+test('isConfigSettingsPatch accepts reset operations without a value', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'reset', path: 'mpv.launchMode' }],
+      },
+      fields,
+    ),
+    true,
+  );
+});
+
+test('isConfigSettingsPatch rejects unknown config paths', () => {
+  assert.equal(
+    isConfigSettingsPatch(
+      {
+        operations: [{ op: 'reset', path: 'unknown.path' }],
+      },
+      fields,
+    ),
+    false,
+  );
+});

src/main/runtime/config-settings-ipc.ts

@@ -0,0 +1,30 @@
+import type { ConfigSettingsField, ConfigSettingsPatch } from '../../types/settings';
+
+export function isConfigSettingsPatch(
+  value: unknown,
+  fields: readonly ConfigSettingsField[],
+): value is ConfigSettingsPatch {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const operations = (value as { operations?: unknown }).operations;
+  return (
+    Array.isArray(operations) &&
+    operations.every((operation) => {
+      if (!operation || typeof operation !== 'object') {
+        return false;
+      }
+      const candidate = operation as { op?: unknown; path?: unknown; value?: unknown };
+      const knownPath =
+        typeof candidate.path === 'string' &&
+        fields.some((field) => field.configPath === candidate.path);
+      if (!knownPath) {
+        return false;
+      }
+      if (candidate.op === 'set') {
+        return 'value' in candidate;
+      }
+      return candidate.op === 'reset';
+    })
+  );
+}

src/main/runtime/config-settings-runtime.ts

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildConfigSettingsSnapshot } from '../../config/settings/jsonc-edit';
+import type { ConfigValidationWarning, RawConfig, ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsField,
+  ConfigSettingsSaveResult,
+  ConfigSettingsSnapshot,
+} from '../../types/settings';
+import type { ReloadConfigStrictResult } from '../../config';
+import {
+  classifyConfigHotReloadDiff,
+  type ConfigHotReloadDiff,
+} from '../../core/services/config-hot-reload';
+import { createSaveConfigSettingsPatchHandler } from './config-settings-save';
+import {
+  createOpenConfigSettingsWindowHandler,
+  type ConfigSettingsWindowLike,
+} from './config-settings-window';
+import { isConfigSettingsPatch } from './config-settings-ipc';
+
+export interface ConfigSettingsIpcMainLike {
+  handle(channel: string, listener: (event: unknown, ...args: unknown[]) => unknown): unknown;
+}
+
+export interface ConfigSettingsIpcChannels {
+  getConfigSettingsSnapshot: string;
+  saveConfigSettingsPatch: string;
+  openConfigSettingsFile: string;
+  openConfigSettingsWindow: string;
+}
+
+export interface ConfigSettingsRuntimeDeps<TWindow extends ConfigSettingsWindowLike> {
+  fields: ConfigSettingsField[];
+  getConfigPath(): string;
+  getRawConfig(): RawConfig;
+  getConfig(): ResolvedConfig;
+  getWarnings(): ConfigValidationWarning[];
+  reloadConfigStrict(): ReloadConfigStrictResult;
+  applyHotReload(diff: ConfigHotReloadDiff, config: ResolvedConfig): void;
+  getSettingsWindow(): TWindow | null;
+  setSettingsWindow(window: TWindow | null): void;
+  createSettingsWindow(): TWindow;
+  settingsHtmlPath: string;
+  openPath(path: string): Promise<string>;
+  ipcMain: ConfigSettingsIpcMainLike;
+  ipcChannels: ConfigSettingsIpcChannels;
+  log?: (message: string) => void;
+}
+
+export function writeTextFileAtomically(targetPath: string, content: string): void {
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  const tempPath = path.join(
+    path.dirname(targetPath),
+    `.${path.basename(targetPath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  try {
+    fs.writeFileSync(tempPath, content, 'utf-8');
+    fs.renameSync(tempPath, targetPath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // Best effort cleanup after a failed atomic write.
+    }
+    throw error;
+  }
+}
+
+function getRestartRequiredSettingsSections(
+  fields: readonly ConfigSettingsField[],
+  restartRequiredFields: string[],
+): string[] {
+  const sections = new Set<string>();
+  for (const field of fields) {
+    if (
+      restartRequiredFields.some(
+        (restartField) =>
+          field.configPath === restartField ||
+          field.configPath.startsWith(`${restartField}.`) ||
+          restartField.startsWith(`${field.configPath}.`),
+      )
+    ) {
+      sections.add(field.section);
+    }
+  }
+  return [...sections].sort();
+}
+
+export function createConfigSettingsRuntime<TWindow extends ConfigSettingsWindowLike>(
+  deps: ConfigSettingsRuntimeDeps<TWindow>,
+) {
+  function getSnapshot(): ConfigSettingsSnapshot {
+    return buildConfigSettingsSnapshot({
+      configPath: deps.getConfigPath(),
+      rawConfig: deps.getRawConfig(),
+      resolvedConfig: deps.getConfig(),
+      warnings: deps.getWarnings(),
+      fields: deps.fields,
+    });
+  }
+
+  const savePatch = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => deps.getConfigPath(),
+    getCurrentConfig: () => deps.getConfig(),
+    getWarnings: () => deps.getWarnings(),
+    getSnapshot,
+    fileExists: (targetPath) => fs.existsSync(targetPath),
+    readText: (targetPath) => fs.readFileSync(targetPath, 'utf-8'),
+    writeTextAtomically: (targetPath, content) => writeTextFileAtomically(targetPath, content),
+    deleteFile: (targetPath) => fs.rmSync(targetPath, { force: true }),
+    reloadConfigStrict: () => deps.reloadConfigStrict(),
+    classifyDiff: (previous, next) => classifyConfigHotReloadDiff(previous, next),
+    applyHotReload: (diff, config) => deps.applyHotReload(diff, config),
+    getRestartRequiredSections: (fields) => getRestartRequiredSettingsSections(deps.fields, fields),
+  });
+
+  function ensureConfigFileExists(): string {
+    const configPath = deps.getConfigPath();
+    if (!fs.existsSync(configPath)) {
+      writeTextFileAtomically(configPath, '{}\n');
+    }
+    return configPath;
+  }
+
+  const openWindow = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: deps.getSettingsWindow,
+    setSettingsWindow: deps.setSettingsWindow,
+    createSettingsWindow: deps.createSettingsWindow,
+    settingsHtmlPath: deps.settingsHtmlPath,
+    log: deps.log,
+  });
+
+  function invalidPatchResult(): ConfigSettingsSaveResult {
+    return {
+      ok: false,
+      warnings: [],
+      error: 'Invalid config settings patch.',
+      hotReloadFields: [],
+      restartRequiredFields: [],
+      restartRequiredSections: [],
+    };
+  }
+
+  function registerHandlers(): void {
+    deps.ipcMain.handle(deps.ipcChannels.getConfigSettingsSnapshot, () => getSnapshot());
+    deps.ipcMain.handle(deps.ipcChannels.saveConfigSettingsPatch, (_event, patch: unknown) => {
+      if (!isConfigSettingsPatch(patch, deps.fields)) {
+        return invalidPatchResult();
+      }
+      return savePatch(patch);
+    });
+    deps.ipcMain.handle(deps.ipcChannels.openConfigSettingsFile, async () => {
+      const openError = await deps.openPath(ensureConfigFileExists());
+      return openError.length === 0;
+    });
+    deps.ipcMain.handle(deps.ipcChannels.openConfigSettingsWindow, () => openWindow());
+  }
+
+  return {
+    getSnapshot,
+    savePatch,
+    openWindow,
+    registerHandlers,
+  };
+}

src/main/runtime/config-settings-save.test.ts

@@ -0,0 +1,148 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { DEFAULT_CONFIG, type ReloadConfigStrictResult } from '../../config';
+import type { ResolvedConfig } from '../../types/config';
+import type { ConfigSettingsSnapshot } from '../../types/settings';
+import { createSaveConfigSettingsPatchHandler } from './config-settings-save';
+
+function snapshot(): ConfigSettingsSnapshot {
+  return {
+    configPath: '/tmp/config.jsonc',
+    fields: [],
+    values: {},
+    warnings: [],
+  };
+}
+
+test('config settings save applies hot-reloadable diff live', () => {
+  const calls: string[] = [];
+  const previous = DEFAULT_CONFIG;
+  const next: ResolvedConfig = {
+    ...DEFAULT_CONFIG,
+    subtitleStyle: {
+      ...DEFAULT_CONFIG.subtitleStyle,
+      autoPauseVideoOnHover: false,
+    },
+  };
+  let written = '';
+  const save = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => '/tmp/config.jsonc',
+    getCurrentConfig: () => previous,
+    getWarnings: () => [],
+    getSnapshot: () => snapshot(),
+    fileExists: () => true,
+    readText: () => '{}',
+    writeTextAtomically: (_path, content) => {
+      written = content;
+      calls.push('write');
+    },
+    reloadConfigStrict: (): ReloadConfigStrictResult => ({
+      ok: true,
+      config: next,
+      warnings: [],
+      path: '/tmp/config.jsonc',
+    }),
+    classifyDiff: () => ({
+      hotReloadFields: ['subtitleStyle'],
+      restartRequiredFields: [],
+    }),
+    applyHotReload: (diff) => calls.push(`hot:${diff.hotReloadFields.join(',')}`),
+    getRestartRequiredSections: () => [],
+  });
+
+  const result = save({
+    operations: [
+      {
+        op: 'set',
+        path: 'subtitleStyle.autoPauseVideoOnHover',
+        value: false,
+      },
+    ],
+  });
+
+  assert.equal(result.ok, true);
+  assert.match(written, /autoPauseVideoOnHover/);
+  assert.deepEqual(calls, ['write', 'hot:subtitleStyle']);
+  assert.deepEqual(result.hotReloadFields, ['subtitleStyle']);
+  assert.deepEqual(result.restartRequiredFields, []);
+});
+
+test('config settings save returns restart-required sections without applying hot reload', () => {
+  const calls: string[] = [];
+  const previous = DEFAULT_CONFIG;
+  const next: ResolvedConfig = {
+    ...DEFAULT_CONFIG,
+    mpv: {
+      ...DEFAULT_CONFIG.mpv,
+      launchMode: 'fullscreen',
+    },
+  };
+  const save = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => '/tmp/config.jsonc',
+    getCurrentConfig: () => previous,
+    getWarnings: () => [],
+    getSnapshot: () => snapshot(),
+    fileExists: () => true,
+    readText: () => '{}',
+    writeTextAtomically: () => calls.push('write'),
+    reloadConfigStrict: (): ReloadConfigStrictResult => ({
+      ok: true,
+      config: next,
+      warnings: [],
+      path: '/tmp/config.jsonc',
+    }),
+    classifyDiff: () => ({
+      hotReloadFields: [],
+      restartRequiredFields: ['mpv'],
+    }),
+    applyHotReload: () => calls.push('hot'),
+    getRestartRequiredSections: () => ['mpv launcher'],
+  });
+
+  const result = save({
+    operations: [{ op: 'set', path: 'mpv.launchMode', value: 'fullscreen' }],
+  });
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(calls, ['write']);
+  assert.deepEqual(result.hotReloadFields, []);
+  assert.deepEqual(result.restartRequiredFields, ['mpv']);
+  assert.deepEqual(result.restartRequiredSections, ['mpv launcher']);
+});
+
+test('config settings save restores previous file content when strict reload fails', () => {
+  const writes: string[] = [];
+  const save = createSaveConfigSettingsPatchHandler({
+    getConfigPath: () => '/tmp/config.jsonc',
+    getCurrentConfig: () => DEFAULT_CONFIG,
+    getWarnings: () => [],
+    getSnapshot: () => snapshot(),
+    fileExists: () => true,
+    readText: () => '{"mpv":{"launchMode":"normal"}}\n',
+    writeTextAtomically: (_path, content) => {
+      writes.push(content);
+    },
+    reloadConfigStrict: (): ReloadConfigStrictResult => ({
+      ok: false,
+      error: 'invalid config',
+      path: '/tmp/config.jsonc',
+    }),
+    classifyDiff: () => {
+      throw new Error('Should not classify invalid config.');
+    },
+    applyHotReload: () => {
+      throw new Error('Should not hot reload invalid config.');
+    },
+    getRestartRequiredSections: () => [],
+  });
+
+  const result = save({
+    operations: [{ op: 'set', path: 'mpv.launchMode', value: 'fullscreen' }],
+  });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.error, 'invalid config');
+  assert.equal(writes.length, 2);
+  assert.match(writes[0] ?? '', /fullscreen/);
+  assert.equal(writes[1], '{"mpv":{"launchMode":"normal"}}\n');
+});

src/main/runtime/config-settings-save.ts

@@ -0,0 +1,98 @@
+import type { ReloadConfigStrictResult } from '../../config';
+import { applyConfigSettingsPatchToContent } from '../../config/settings/jsonc-edit';
+import type { ConfigValidationWarning, ResolvedConfig } from '../../types/config';
+import type {
+  ConfigSettingsPatch,
+  ConfigSettingsSaveResult,
+  ConfigSettingsSnapshot,
+} from '../../types/settings';
+
+export interface ConfigSettingsHotReloadDiff {
+  hotReloadFields: string[];
+  restartRequiredFields: string[];
+}
+
+export interface ConfigSettingsSaveDeps {
+  getConfigPath(): string;
+  getCurrentConfig(): ResolvedConfig;
+  getWarnings(): ConfigValidationWarning[];
+  getSnapshot(): ConfigSettingsSnapshot;
+  fileExists(path: string): boolean;
+  readText(path: string): string;
+  writeTextAtomically(path: string, content: string): void;
+  deleteFile?(path: string): void;
+  reloadConfigStrict(): ReloadConfigStrictResult;
+  classifyDiff(prev: ResolvedConfig, next: ResolvedConfig): ConfigSettingsHotReloadDiff;
+  applyHotReload(diff: ConfigSettingsHotReloadDiff, config: ResolvedConfig): void;
+  getRestartRequiredSections(restartRequiredFields: string[]): string[];
+}
+
+export function createSaveConfigSettingsPatchHandler(deps: ConfigSettingsSaveDeps) {
+  return (patch: ConfigSettingsPatch): ConfigSettingsSaveResult => {
+    if (patch.operations.length === 0) {
+      return {
+        ok: true,
+        snapshot: deps.getSnapshot(),
+        hotReloadFields: [],
+        restartRequiredFields: [],
+        restartRequiredSections: [],
+      };
+    }
+
+    const configPath = deps.getConfigPath();
+    const previousConfig = deps.getCurrentConfig();
+    const previousWarnings = deps.getWarnings();
+    const hadExistingConfig = deps.fileExists(configPath);
+    const content = hadExistingConfig ? deps.readText(configPath) : '{}\n';
+    const candidate = applyConfigSettingsPatchToContent({
+      content,
+      operations: patch.operations,
+      previousWarnings,
+    });
+
+    if (!candidate.ok) {
+      return {
+        ok: false,
+        warnings: candidate.warnings,
+        error: candidate.error,
+        hotReloadFields: [],
+        restartRequiredFields: [],
+        restartRequiredSections: [],
+      };
+    }
+
+    deps.writeTextAtomically(configPath, candidate.content);
+    const reloadResult = deps.reloadConfigStrict();
+    if (!reloadResult.ok) {
+      if (hadExistingConfig) {
+        deps.writeTextAtomically(configPath, content);
+      } else if (deps.deleteFile) {
+        deps.deleteFile(configPath);
+      } else {
+        deps.writeTextAtomically(configPath, content);
+      }
+      return {
+        ok: false,
+        warnings: [],
+        error: reloadResult.error,
+        hotReloadFields: [],
+        restartRequiredFields: [],
+        restartRequiredSections: [],
+      };
+    }
+
+    const diff = deps.classifyDiff(previousConfig, reloadResult.config);
+    if (diff.hotReloadFields.length > 0) {
+      deps.applyHotReload(diff, reloadResult.config);
+    }
+
+    return {
+      ok: true,
+      snapshot: deps.getSnapshot(),
+      warnings: reloadResult.warnings,
+      hotReloadFields: diff.hotReloadFields,
+      restartRequiredFields: diff.restartRequiredFields,
+      restartRequiredSections: deps.getRestartRequiredSections(diff.restartRequiredFields),
+    };
+  };
+}

src/main/runtime/config-settings-window.test.ts

@@ -0,0 +1,83 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createOpenConfigSettingsWindowHandler } from './config-settings-window';
+
+test('createOpenConfigSettingsWindowHandler focuses existing settings window', () => {
+  const calls: string[] = [];
+  const existing = {
+    isDestroyed: () => false,
+    focus: () => calls.push('focus'),
+    loadFile: () => calls.push('load'),
+    on: () => {},
+  };
+
+  const open = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: () => existing,
+    setSettingsWindow: () => calls.push('set'),
+    createSettingsWindow: () => {
+      throw new Error('Should not create a second window.');
+    },
+    settingsHtmlPath: '/tmp/settings.html',
+  });
+
+  assert.equal(open(), true);
+  assert.deepEqual(calls, ['focus']);
+});
+
+test('createOpenConfigSettingsWindowHandler creates window and clears closed state', () => {
+  const calls: string[] = [];
+  const handlers: { closed?: () => void } = {};
+  const created = {
+    isDestroyed: () => false,
+    focus: () => calls.push('focus'),
+    loadFile: (path: string) => calls.push(`load:${path}`),
+    on: (event: string, handler: () => void) => {
+      if (event === 'closed') handlers.closed = handler;
+    },
+  };
+
+  const open = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: () => null,
+    setSettingsWindow: (window) => calls.push(window ? 'set:window' : 'set:null'),
+    createSettingsWindow: () => created,
+    settingsHtmlPath: '/tmp/settings.html',
+  });
+
+  assert.equal(open(), true);
+  assert.deepEqual(calls, ['load:/tmp/settings.html', 'set:window', 'focus']);
+  assert.ok(handlers.closed);
+  handlers.closed();
+  assert.equal(calls.at(-1), 'set:null');
+});
+
+test('createOpenConfigSettingsWindowHandler clears failed load window state', async () => {
+  const calls: string[] = [];
+  const created = {
+    isDestroyed: () => false,
+    focus: () => calls.push('focus'),
+    loadFile: (path: string) => {
+      calls.push(`load:${path}`);
+      return Promise.reject(new Error('missing settings html'));
+    },
+    on: () => {},
+    destroy: () => calls.push('destroy'),
+  };
+
+  const open = createOpenConfigSettingsWindowHandler({
+    getSettingsWindow: () => null,
+    setSettingsWindow: (window) => calls.push(window ? 'set:window' : 'set:null'),
+    createSettingsWindow: () => created,
+    settingsHtmlPath: '/tmp/missing-settings.html',
+  });
+
+  assert.equal(open(), true);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+
+  assert.deepEqual(calls, [
+    'load:/tmp/missing-settings.html',
+    'set:window',
+    'focus',
+    'set:null',
+    'destroy',
+  ]);
+});

src/main/runtime/config-settings-window.ts

@@ -0,0 +1,41 @@
+export interface ConfigSettingsWindowLike {
+  isDestroyed(): boolean;
+  focus(): void;
+  loadFile(path: string): unknown;
+  on(event: 'closed', handler: () => void): unknown;
+  destroy?(): unknown;
+}
+
+export interface OpenConfigSettingsWindowDeps<TWindow extends ConfigSettingsWindowLike> {
+  getSettingsWindow(): TWindow | null;
+  setSettingsWindow(window: TWindow | null): void;
+  createSettingsWindow(): TWindow;
+  settingsHtmlPath: string;
+  log?: (message: string) => void;
+}
+
+export function createOpenConfigSettingsWindowHandler<TWindow extends ConfigSettingsWindowLike>(
+  deps: OpenConfigSettingsWindowDeps<TWindow>,
+): () => boolean {
+  return () => {
+    const existing = deps.getSettingsWindow();
+    if (existing && !existing.isDestroyed()) {
+      existing.focus();
+      return true;
+    }
+
+    const window = deps.createSettingsWindow();
+    void Promise.resolve(window.loadFile(deps.settingsHtmlPath)).catch((error) => {
+      const message = error instanceof Error ? error.message : String(error);
+      deps.log?.(`Failed to load configuration settings window: ${message}`);
+      deps.setSettingsWindow(null);
+      window.destroy?.();
+    });
+    deps.setSettingsWindow(window);
+    window.on('closed', () => {
+      deps.setSettingsWindow(null);
+    });
+    window.focus();
+    return true;
+  };
+}

src/main/runtime/first-run-setup-service.test.ts

@@ -30,6 +30,7 @@ function makeArgs(overrides: Partial<CliArgs> = {}): CliArgs {
     toggleVisibleOverlay: false,
     togglePrimarySubtitleBar: false,
     settings: false,
+    configSettings: false,
     setup: false,
     show: false,
     hide: false,
@@ -120,6 +121,7 @@ function createCommandLineLauncherSnapshot(
 test('shouldAutoOpenFirstRunSetup only for startup/setup intents', () => {
   assert.equal(shouldAutoOpenFirstRunSetup(makeArgs({ start: true, background: true })), true);
   assert.equal(shouldAutoOpenFirstRunSetup(makeArgs({ background: true, setup: true })), true);
+  assert.equal(shouldAutoOpenFirstRunSetup(makeArgs({ start: true, configSettings: true })), false);
   assert.equal(
     shouldAutoOpenFirstRunSetup(makeArgs({ background: true, jellyfinRemoteAnnounce: true })),
     false,

src/main/runtime/first-run-setup-service.ts

@@ -72,6 +72,7 @@ function hasAnyStartupCommandBeyondSetup(args: CliArgs): boolean {
     args.togglePrimarySubtitleBar ||
     args.launchMpv ||
     args.settings ||
+    args.configSettings ||
     args.show ||
     args.hide ||
     args.showVisibleOverlay ||

src/main/runtime/setup-window-factory.test.ts

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import {
   createCreateAnilistSetupWindowHandler,
+  createCreateConfigSettingsWindowHandler,
   createCreateFirstRunSetupWindowHandler,
   createCreateJellyfinSetupWindowHandler,
 } from './setup-window-factory';
@@ -77,3 +78,31 @@ test('createCreateAnilistSetupWindowHandler builds anilist setup window', () =>
     },
   });
 });
+
+test('createCreateConfigSettingsWindowHandler builds configuration settings window', () => {
+  let options: Electron.BrowserWindowConstructorOptions | null = null;
+  const createSettingsWindow = createCreateConfigSettingsWindowHandler({
+    preloadPath: '/tmp/preload-settings.js',
+    createBrowserWindow: (nextOptions) => {
+      options = nextOptions;
+      return { id: 'config-settings' } as never;
+    },
+  });
+
+  assert.deepEqual(createSettingsWindow(), { id: 'config-settings' });
+  assert.deepEqual(options, {
+    width: 1040,
+    height: 760,
+    title: 'SubMiner Configuration',
+    show: true,
+    autoHideMenuBar: true,
+    resizable: true,
+    backgroundColor: '#24273a',
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+      sandbox: false,
+      preload: '/tmp/preload-settings.js',
+    },
+  });
+});

src/main/runtime/setup-window-factory.ts

@@ -5,6 +5,9 @@ interface SetupWindowConfig {
   resizable?: boolean;
   minimizable?: boolean;
   maximizable?: boolean;
+  preloadPath?: string;
+  sandbox?: boolean;
+  backgroundColor?: string;
 }
 
 function createSetupWindowHandler<TWindow>(
@@ -21,9 +24,12 @@ function createSetupWindowHandler<TWindow>(
       ...(config.resizable === undefined ? {} : { resizable: config.resizable }),
       ...(config.minimizable === undefined ? {} : { minimizable: config.minimizable }),
       ...(config.maximizable === undefined ? {} : { maximizable: config.maximizable }),
+      ...(config.backgroundColor === undefined ? {} : { backgroundColor: config.backgroundColor }),
       webPreferences: {
         nodeIntegration: false,
         contextIsolation: true,
+        ...(config.sandbox === undefined ? {} : { sandbox: config.sandbox }),
+        ...(config.preloadPath ? { preload: config.preloadPath } : {}),
       },
     });
 }
@@ -60,3 +66,18 @@ export function createCreateAnilistSetupWindowHandler<TWindow>(deps: {
     title: 'Anilist Setup',
   });
 }
+
+export function createCreateConfigSettingsWindowHandler<TWindow>(deps: {
+  createBrowserWindow: (options: Electron.BrowserWindowConstructorOptions) => TWindow;
+  preloadPath: string;
+}) {
+  return createSetupWindowHandler(deps, {
+    width: 1040,
+    height: 760,
+    title: 'SubMiner Configuration',
+    resizable: true,
+    preloadPath: deps.preloadPath,
+    sandbox: false,
+    backgroundColor: '#24273a',
+  });
+}

src/main/runtime/startup-mode-flags.test.ts

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { parseArgs } from '../../cli/args';
+import {
+  getStartupModeFlags,
+  shouldRefreshAnilistOnConfigReload,
+  shouldStartAutomaticUpdateChecks,
+} from './startup-mode-flags';
+
+test('config settings startup uses minimal startup and skips background integrations', () => {
+  const args = parseArgs(['--config']);
+  const flags = getStartupModeFlags(args);
+
+  assert.equal(flags.shouldUseMinimalStartup, true);
+  assert.equal(flags.shouldSkipHeavyStartup, true);
+  assert.equal(shouldRefreshAnilistOnConfigReload(args), false);
+  assert.equal(shouldStartAutomaticUpdateChecks(args), false);
+});
+
+test('normal startup still allows background integrations', () => {
+  const flags = getStartupModeFlags(null);
+
+  assert.equal(flags.shouldUseMinimalStartup, false);
+  assert.equal(flags.shouldSkipHeavyStartup, false);
+  assert.equal(shouldRefreshAnilistOnConfigReload(null), true);
+  assert.equal(shouldStartAutomaticUpdateChecks(null), true);
+});

src/main/runtime/startup-mode-flags.ts

@@ -0,0 +1,40 @@
+import type { CliArgs } from '../../cli/args';
+import {
+  isHeadlessInitialCommand,
+  isStandaloneTexthookerCommand,
+  shouldRunSettingsOnlyStartup,
+} from '../../cli/args';
+
+export function getStartupModeFlags(initialArgs: CliArgs | null | undefined): {
+  shouldUseMinimalStartup: boolean;
+  shouldSkipHeavyStartup: boolean;
+} {
+  return {
+    shouldUseMinimalStartup: Boolean(
+      (initialArgs && isStandaloneTexthookerCommand(initialArgs)) ||
+      initialArgs?.configSettings ||
+      initialArgs?.update ||
+      (initialArgs?.stats &&
+        (initialArgs.statsCleanup || initialArgs.statsBackground || initialArgs.statsStop)),
+    ),
+    shouldSkipHeavyStartup: Boolean(
+      initialArgs &&
+      (shouldRunSettingsOnlyStartup(initialArgs) ||
+        initialArgs.configSettings ||
+        initialArgs.stats ||
+        initialArgs.dictionary ||
+        initialArgs.update ||
+        initialArgs.setup),
+    ),
+  };
+}
+
+export function shouldRefreshAnilistOnConfigReload(
+  initialArgs: CliArgs | null | undefined,
+): boolean {
+  return !(initialArgs && (isHeadlessInitialCommand(initialArgs) || initialArgs.configSettings));
+}
+
+export function shouldStartAutomaticUpdateChecks(initialArgs: CliArgs | null | undefined): boolean {
+  return !(initialArgs && (isHeadlessInitialCommand(initialArgs) || initialArgs.configSettings));
+}

src/main/runtime/tray-main-actions.test.ts

@@ -48,6 +48,7 @@ test('build tray template handler wires actions and init guards', () => {
       handlers.openWindowsMpvLauncherSetup();
       handlers.openYomitanSettings();
       handlers.openRuntimeOptions();
+      handlers.openConfigSettings();
       handlers.openJellyfinSetup();
       handlers.toggleJellyfinDiscovery();
       handlers.openAnilistSetup();
@@ -68,6 +69,7 @@ test('build tray template handler wires actions and init guards', () => {
     showWindowsMpvLauncherSetup: () => true,
     openYomitanSettings: () => calls.push('yomitan'),
     openRuntimeOptionsPalette: () => calls.push('runtime-options'),
+    openConfigSettingsWindow: () => calls.push('configuration'),
     openJellyfinSetupWindow: () => calls.push('jellyfin'),
     isJellyfinConfigured: () => true,
     isJellyfinDiscoveryActive: () => false,
@@ -90,6 +92,7 @@ test('build tray template handler wires actions and init guards', () => {
     'setup',
     'yomitan',
     'runtime-options',
+    'configuration',
     'jellyfin',
     'jellyfin-discovery',
     'anilist',

src/main/runtime/tray-main-actions.ts

@@ -37,6 +37,7 @@ export function createBuildTrayMenuTemplateHandler<TMenuItem>(deps: {
     showWindowsMpvLauncherSetup: boolean;
     openYomitanSettings: () => void;
     openRuntimeOptions: () => void;
+    openConfigSettings: () => void;
     openJellyfinSetup: () => void;
     showJellyfinDiscovery: boolean;
     jellyfinDiscoveryActive: boolean;
@@ -55,6 +56,7 @@ export function createBuildTrayMenuTemplateHandler<TMenuItem>(deps: {
   showWindowsMpvLauncherSetup: () => boolean;
   openYomitanSettings: () => void;
   openRuntimeOptionsPalette: () => void;
+  openConfigSettingsWindow: () => void;
   openJellyfinSetupWindow: () => void;
   isJellyfinConfigured: () => boolean;
   isJellyfinDiscoveryActive: () => boolean;
@@ -92,6 +94,9 @@ export function createBuildTrayMenuTemplateHandler<TMenuItem>(deps: {
         }
         deps.openRuntimeOptionsPalette();
       },
+      openConfigSettings: () => {
+        deps.openConfigSettingsWindow();
+      },
       openJellyfinSetup: () => {
         deps.openJellyfinSetupWindow();
       },

src/main/runtime/tray-main-deps.test.ts

@@ -32,6 +32,7 @@ test('tray main deps builders return mapped handlers', () => {
     showWindowsMpvLauncherSetup: () => true,
     openYomitanSettings: () => calls.push('yomitan'),
     openRuntimeOptionsPalette: () => calls.push('runtime-options'),
+    openConfigSettingsWindow: () => calls.push('configuration'),
     openJellyfinSetupWindow: () => calls.push('jellyfin'),
     isJellyfinConfigured: () => true,
     isJellyfinDiscoveryActive: () => false,
@@ -53,6 +54,7 @@ test('tray main deps builders return mapped handlers', () => {
     showWindowsMpvLauncherSetup: true,
     openYomitanSettings: () => calls.push('open-yomitan'),
     openRuntimeOptions: () => calls.push('open-runtime-options'),
+    openConfigSettings: () => calls.push('open-configuration'),
     openJellyfinSetup: () => calls.push('open-jellyfin'),
     showJellyfinDiscovery: true,
     jellyfinDiscoveryActive: false,

src/main/runtime/tray-main-deps.ts

@@ -36,6 +36,7 @@ export function createBuildTrayMenuTemplateMainDepsHandler<TMenuItem>(deps: {
     showWindowsMpvLauncherSetup: boolean;
     openYomitanSettings: () => void;
     openRuntimeOptions: () => void;
+    openConfigSettings: () => void;
     openJellyfinSetup: () => void;
     showJellyfinDiscovery: boolean;
     jellyfinDiscoveryActive: boolean;
@@ -54,6 +55,7 @@ export function createBuildTrayMenuTemplateMainDepsHandler<TMenuItem>(deps: {
   showWindowsMpvLauncherSetup: () => boolean;
   openYomitanSettings: () => void;
   openRuntimeOptionsPalette: () => void;
+  openConfigSettingsWindow: () => void;
   openJellyfinSetupWindow: () => void;
   isJellyfinConfigured: () => boolean;
   isJellyfinDiscoveryActive: () => boolean;
@@ -74,6 +76,7 @@ export function createBuildTrayMenuTemplateMainDepsHandler<TMenuItem>(deps: {
     showWindowsMpvLauncherSetup: deps.showWindowsMpvLauncherSetup,
     openYomitanSettings: deps.openYomitanSettings,
     openRuntimeOptionsPalette: deps.openRuntimeOptionsPalette,
+    openConfigSettingsWindow: deps.openConfigSettingsWindow,
     openJellyfinSetupWindow: deps.openJellyfinSetupWindow,
     isJellyfinConfigured: deps.isJellyfinConfigured,
     isJellyfinDiscoveryActive: deps.isJellyfinDiscoveryActive,

src/main/runtime/tray-runtime-handlers.test.ts

@@ -32,6 +32,7 @@ test('tray runtime handlers compose resolve/menu/ensure/destroy handlers', () =>
       showWindowsMpvLauncherSetup: () => true,
       openYomitanSettings: () => {},
       openRuntimeOptionsPalette: () => {},
+      openConfigSettingsWindow: () => {},
       openJellyfinSetupWindow: () => {},
       isJellyfinConfigured: () => false,
       isJellyfinDiscoveryActive: () => false,

src/main/runtime/tray-runtime.test.ts

@@ -38,6 +38,7 @@ test('tray menu template contains expected entries and handlers', () => {
     showWindowsMpvLauncherSetup: true,
     openYomitanSettings: () => calls.push('yomitan'),
     openRuntimeOptions: () => calls.push('runtime'),
+    openConfigSettings: () => calls.push('configuration'),
     openJellyfinSetup: () => calls.push('jellyfin'),
     showJellyfinDiscovery: true,
     jellyfinDiscoveryActive: false,
@@ -47,7 +48,7 @@ test('tray menu template contains expected entries and handlers', () => {
     quitApp: () => calls.push('quit'),
   });
 
-  assert.equal(template.length, 12);
+  assert.equal(template.length, 13);
   assert.equal(
     template.some((entry) => entry.label === 'Open Overlay'),
     false,
@@ -60,10 +61,10 @@ test('tray menu template contains expected entries and handlers', () => {
   template[0]!.click?.();
   assert.equal(template[1]!.label, 'Open Texthooker');
   template[1]!.click?.();
-  assert.equal(template[9]!.label, 'Check for Updates');
-  template[9]!.click?.();
-  template[10]!.type === 'separator' ? calls.push('separator') : calls.push('bad');
-  template[11]!.click?.();
+  assert.equal(template[10]!.label, 'Check for Updates');
+  template[10]!.click?.();
+  template[11]!.type === 'separator' ? calls.push('separator') : calls.push('bad');
+  template[12]!.click?.();
   assert.deepEqual(calls, [
     'jellyfin-discovery',
     'help',
@@ -85,6 +86,7 @@ test('tray menu template omits first-run setup entry when setup is complete', ()
     showWindowsMpvLauncherSetup: false,
     openYomitanSettings: () => undefined,
     openRuntimeOptions: () => undefined,
+    openConfigSettings: () => undefined,
     openJellyfinSetup: () => undefined,
     showJellyfinDiscovery: false,
     jellyfinDiscoveryActive: false,
@@ -112,6 +114,7 @@ test('tray menu template omits texthooker entry when texthooker page is disabled
     showWindowsMpvLauncherSetup: false,
     openYomitanSettings: () => undefined,
     openRuntimeOptions: () => undefined,
+    openConfigSettings: () => undefined,
     openJellyfinSetup: () => undefined,
     showJellyfinDiscovery: false,
     jellyfinDiscoveryActive: false,
@@ -137,6 +140,7 @@ test('tray menu template renders active jellyfin discovery checkbox', () => {
     showWindowsMpvLauncherSetup: false,
     openYomitanSettings: () => undefined,
     openRuntimeOptions: () => undefined,
+    openConfigSettings: () => undefined,
     openJellyfinSetup: () => undefined,
     showJellyfinDiscovery: true,
     jellyfinDiscoveryActive: true,

src/main/runtime/tray-runtime.ts

@@ -39,6 +39,7 @@ export type TrayMenuActionHandlers = {
   showWindowsMpvLauncherSetup: boolean;
   openYomitanSettings: () => void;
   openRuntimeOptions: () => void;
+  openConfigSettings: () => void;
   openJellyfinSetup: () => void;
   showJellyfinDiscovery: boolean;
   jellyfinDiscoveryActive: boolean;
@@ -92,6 +93,10 @@ export function buildTrayMenuTemplateRuntime(handlers: TrayMenuActionHandlers):
       label: 'Open Runtime Options',
       click: handlers.openRuntimeOptions,
     },
+    {
+      label: 'Open Configuration',
+      click: handlers.openConfigSettings,
+    },
     {
       label: 'Configure Jellyfin',
       click: handlers.openJellyfinSetup,

src/main/runtime/update/app-updater.test.ts

@@ -162,6 +162,46 @@ test('app updater skips native downloads when native updater is unsupported', as
   assert.deepEqual(logged, ['Skipping app update download because native updater is unsupported.']);
 });
 
+test('app updater installs a custom HTTP executor before native checks', async () => {
+  const httpExecutor = { request: async () => null };
+  let executorDuringCheck: unknown;
+  let differentialDownloadDuringCheck: unknown;
+  const updater: ElectronAutoUpdaterLike & {
+    httpExecutor?: unknown;
+    disableDifferentialDownload?: boolean;
+  } = {
+    autoDownload: true,
+    allowPrerelease: false,
+    allowDowngrade: true,
+    logger: null,
+    checkForUpdates: async () => {
+      executorDuringCheck = updater.httpExecutor;
+      differentialDownloadDuringCheck = updater.disableDifferentialDownload;
+      return {
+        updateInfo: {
+          version: '0.15.0',
+        },
+      };
+    },
+    downloadUpdate: async () => [],
+    quitAndInstall: () => {},
+  };
+  const appUpdater = createElectronAppUpdater({
+    currentVersion: '0.14.0',
+    isPackaged: true,
+    updater,
+    log: () => {},
+    configureHttpExecutor: () => httpExecutor,
+    disableDifferentialDownload: true,
+  });
+
+  const result = await appUpdater.checkForUpdates('stable');
+
+  assert.equal(result.available, true);
+  assert.equal(executorDuringCheck, httpExecutor);
+  assert.equal(differentialDownloadDuringCheck, true);
+});
+
 test('resolveMacAppBundlePath resolves packaged macOS executable path', () => {
   assert.equal(
     resolveMacAppBundlePath('/Applications/SubMiner.app/Contents/MacOS/SubMiner'),
@@ -185,6 +225,25 @@ test('mac native updater is unsupported for ad-hoc signed app bundles', async ()
   assert.deepEqual(logged, ['Skipping native macOS updater because this build is ad-hoc signed.']);
 });
 
+test('mac native updater is unsupported outside Applications folders before signature probing', async () => {
+  const logged: string[] = [];
+  const supported = await isNativeUpdaterSupported({
+    platform: 'darwin',
+    isPackaged: true,
+    execPath: '/Users/tester/build/SubMiner.app/Contents/MacOS/SubMiner',
+    homeDir: '/Users/tester',
+    readCodeSignature: () => {
+      throw new Error('signature should not be read');
+    },
+    log: (message) => logged.push(message),
+  });
+
+  assert.equal(supported, false);
+  assert.deepEqual(logged, [
+    'Skipping native macOS updater because the app is not installed in an Applications folder.',
+  ]);
+});
+
 test('mac native updater supports Developer ID signed packaged app bundles', async () => {
   const logged: string[] = [];
   const supported = await isNativeUpdaterSupported({

src/main/runtime/update/app-updater.ts

@@ -1,5 +1,7 @@
 import { realpathSync } from 'node:fs';
 import { execFile } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
 import { promisify } from 'node:util';
 import { autoUpdater as electronAutoUpdater } from 'electron-updater';
 import type { UpdateChannel } from '../../../types/config';
@@ -34,11 +36,16 @@ export interface ElectronAutoUpdaterLike {
   } | null>;
   downloadUpdate: () => Promise<unknown>;
   quitAndInstall: (isSilent?: boolean, isForceRunAfter?: boolean) => void;
+  disableDifferentialDownload?: boolean;
 }
 
 const updaterErrorListeners = new WeakMap<object, (error: unknown) => void>();
 const execFileAsync = promisify(execFile);
 
+type ElectronAutoUpdaterWithHttpExecutor = ElectronAutoUpdaterLike & {
+  httpExecutor?: unknown;
+};
+
 export function resolveMacAppBundlePath(execPath: string): string | null {
   const marker = '.app/Contents/MacOS/';
   const markerIndex = execPath.indexOf(marker);
@@ -65,6 +72,25 @@ function realpathOrOriginal(filePath: string): string {
   }
 }
 
+function isSameOrInsideDirectory(parentPath: string, candidatePath: string): boolean {
+  const relative = path.relative(parentPath, candidatePath);
+  return (
+    relative === '' ||
+    (relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative))
+  );
+}
+
+export function isMacApplicationsFolderBundle(
+  appBundlePath: string,
+  homeDir: string = os.homedir(),
+): boolean {
+  const resolvedBundlePath = path.resolve(appBundlePath);
+  return (
+    isSameOrInsideDirectory('/Applications', resolvedBundlePath) ||
+    isSameOrInsideDirectory(path.join(homeDir, 'Applications'), resolvedBundlePath)
+  );
+}
+
 export function isKnownLinuxPackageManagedAppImage(appImagePath: string): boolean {
   return realpathOrOriginal(appImagePath) === '/opt/SubMiner/SubMiner.AppImage';
 }
@@ -74,6 +100,7 @@ export async function isNativeUpdaterSupported(options: {
   isPackaged: boolean;
   execPath: string;
   env?: NodeJS.ProcessEnv;
+  homeDir?: string;
   readCodeSignature?: (appBundlePath: string) => string | null | Promise<string | null>;
   log?: (message: string) => void;
 }): Promise<boolean> {
@@ -100,6 +127,13 @@ export async function isNativeUpdaterSupported(options: {
     return false;
   }
 
+  if (!isMacApplicationsFolderBundle(appBundlePath, options.homeDir)) {
+    options.log?.(
+      'Skipping native macOS updater because the app is not installed in an Applications folder.',
+    );
+    return false;
+  }
+
   const signature = await (options.readCodeSignature ?? readMacCodeSignature)(appBundlePath);
   if (!signature) {
     options.log?.(
@@ -157,6 +191,8 @@ export function createElectronAppUpdater(options: {
   log: (message: string) => void;
   getChannel?: () => UpdateChannel;
   isNativeUpdaterSupported?: () => boolean | Promise<boolean>;
+  configureHttpExecutor?: () => unknown;
+  disableDifferentialDownload?: boolean;
 }) {
   const getChannel = options.getChannel ?? (() => 'stable' as const);
   const updater = configureAutoUpdater(
@@ -164,6 +200,13 @@ export function createElectronAppUpdater(options: {
     options.log,
     getChannel(),
   );
+  if (options.configureHttpExecutor) {
+    // electron-updater has no public executor hook; keep the macOS cURL override localized.
+    (updater as ElectronAutoUpdaterWithHttpExecutor).httpExecutor = options.configureHttpExecutor();
+  }
+  if (options.disableDifferentialDownload !== undefined) {
+    updater.disableDifferentialDownload = options.disableDifferentialDownload;
+  }
   let nativeUpdaterSupported: Promise<boolean> | null = null;
 
   async function getNativeUpdaterSupported(): Promise<boolean> {

src/main/runtime/update/curl-http-executor.test.ts

@@ -0,0 +1,144 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { createCurlHttpExecutor, type CurlExecFile } from './curl-http-executor';
+
+test('curl HTTP executor requests updater metadata without Electron networking', async () => {
+  const calls: Array<{ file: string; args: readonly string[] }> = [];
+  const execFile: CurlExecFile = (file, args, _options, callback) => {
+    calls.push({ file, args });
+    queueMicrotask(() => callback(null, 'metadata', ''));
+    return { kill: () => true };
+  };
+  const executor = createCurlHttpExecutor({ execFile, curlPath: '/usr/bin/curl' });
+
+  const result = await executor.request({
+    protocol: 'https:',
+    hostname: 'api.github.com',
+    path: '/repos/ksyasuda/SubMiner/releases',
+    headers: {
+      Accept: 'application/vnd.github+json',
+      'x-user-staging-id': 'abc',
+    },
+    timeout: 120_000,
+  });
+
+  assert.equal(result, 'metadata');
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0]?.file, '/usr/bin/curl');
+  assert.deepEqual(calls[0]?.args, [
+    '--fail',
+    '--location',
+    '--silent',
+    '--show-error',
+    '--connect-timeout',
+    '30',
+    '--max-time',
+    '120',
+    '--header',
+    'Accept: application/vnd.github+json',
+    '--header',
+    'x-user-staging-id: abc',
+    'https://api.github.com/repos/ksyasuda/SubMiner/releases',
+  ]);
+});
+
+test('curl HTTP executor downloads updater assets to the requested destination', async () => {
+  const calls: Array<{ args: readonly string[] }> = [];
+  const execFile: CurlExecFile = (_file, args, _options, callback) => {
+    calls.push({ args });
+    queueMicrotask(() => callback(null, Buffer.alloc(0), Buffer.alloc(0)));
+    return { kill: () => true };
+  };
+  const executor = createCurlHttpExecutor({
+    execFile,
+    curlPath: '/usr/bin/curl',
+    mkdir: async () => undefined,
+  });
+
+  await executor.download(
+    new URL('https://github.com/ksyasuda/SubMiner/releases/download/v1/app.zip'),
+    '/tmp/subminer/update.zip',
+    {
+      headers: { 'User-Agent': 'SubMiner updater' },
+      cancellationToken: {
+        createPromise: (callback) =>
+          new Promise((resolve, reject) => callback(resolve, reject, () => {})),
+      },
+    },
+  );
+
+  assert.deepEqual(calls[0]?.args, [
+    '--fail',
+    '--location',
+    '--silent',
+    '--show-error',
+    '--connect-timeout',
+    '30',
+    '--header',
+    'User-Agent: SubMiner updater',
+    '--output',
+    '/tmp/subminer/update.zip',
+    'https://github.com/ksyasuda/SubMiner/releases/download/v1/app.zip',
+  ]);
+});
+
+test('curl HTTP executor verifies downloaded updater asset hashes', async () => {
+  const data = Buffer.from('zip payload');
+  const expectedSha512 = createHash('sha512').update(data).digest('base64');
+  const execFile: CurlExecFile = (_file, _args, _options, callback) => {
+    queueMicrotask(() => callback(null, Buffer.alloc(0), Buffer.alloc(0)));
+    return { kill: () => true };
+  };
+  const executor = createCurlHttpExecutor({
+    execFile,
+    curlPath: '/usr/bin/curl',
+    mkdir: async () => undefined,
+    readFile: async () => data,
+  });
+
+  await executor.download(new URL('https://example.test/update.zip'), '/tmp/subminer/update.zip', {
+    sha512: expectedSha512,
+    cancellationToken: {
+      createPromise: (callback) =>
+        new Promise((resolve, reject) => callback(resolve, reject, () => {})),
+    },
+  });
+
+  await assert.rejects(
+    () =>
+      executor.download(new URL('https://example.test/update.zip'), '/tmp/subminer/update.zip', {
+        sha512: 'bad',
+        cancellationToken: {
+          createPromise: (callback) =>
+            new Promise((resolve, reject) => callback(resolve, reject, () => {})),
+        },
+      }),
+    /sha512 mismatch/,
+  );
+});
+
+test('curl HTTP executor does not expose command arguments when stderr is empty', async () => {
+  const execFile: CurlExecFile = (_file, _args, _options, callback) => {
+    const error = new Error('--header Authorization: Bearer secret-token');
+    Object.assign(error, { code: 'ENOENT' });
+    queueMicrotask(() => callback(error, '', ''));
+    return { kill: () => true };
+  };
+  const executor = createCurlHttpExecutor({ execFile, curlPath: '/usr/bin/curl' });
+
+  await assert.rejects(
+    () =>
+      executor.request({
+        protocol: 'https:',
+        hostname: 'api.github.com',
+        path: '/repos/ksyasuda/SubMiner/releases',
+      }),
+    (error) => {
+      assert.ok(error instanceof Error);
+      assert.equal(error.message, 'curl failed (ENOENT)');
+      assert.doesNotMatch(error.message, /secret-token|Authorization/);
+      return true;
+    },
+  );
+});

src/main/runtime/update/curl-http-executor.ts

@@ -0,0 +1,212 @@
+import { execFile as defaultExecFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RequestOptions, OutgoingHttpHeaders } from 'node:http';
+
+export type CurlExecFile = (
+  file: string,
+  args: readonly string[],
+  options: {
+    encoding: 'utf8' | 'buffer';
+    maxBuffer?: number;
+    timeout?: number;
+  },
+  callback: (error: Error | null, stdout: string | Buffer, stderr: string | Buffer) => void,
+) => { kill: (signal?: NodeJS.Signals) => unknown };
+
+type CancellationTokenLike = {
+  createPromise: <T>(
+    callback: (
+      resolve: (value: T | PromiseLike<T>) => void,
+      reject: (error: Error) => void,
+      onCancel: (callback: () => void) => void,
+    ) => void,
+  ) => Promise<T>;
+};
+
+type CurlDownloadOptions = {
+  headers?: OutgoingHttpHeaders | null;
+  sha2?: string | null;
+  sha512?: string | null;
+  cancellationToken: CancellationTokenLike;
+};
+
+export type CurlHttpExecutor = {
+  request: (
+    options: RequestOptions,
+    cancellationToken?: CancellationTokenLike,
+    data?: Record<string, unknown> | null,
+  ) => Promise<string | null>;
+  download: (url: URL, destination: string, options: CurlDownloadOptions) => Promise<string>;
+  downloadToBuffer: (url: URL, options: CurlDownloadOptions) => Promise<Buffer>;
+};
+
+function requestOptionsToUrl(options: RequestOptions): string {
+  const protocol = options.protocol ?? 'https:';
+  const hostname = options.hostname ?? options.host;
+  if (!hostname) throw new Error('Updater request is missing a hostname.');
+  const port = options.port ? `:${options.port}` : '';
+  const requestPath = options.path ?? '/';
+  return `${protocol}//${hostname}${port}${requestPath}`;
+}
+
+function addHeaderArgs(
+  args: string[],
+  headers: RequestOptions['headers'] | OutgoingHttpHeaders | null | undefined,
+): void {
+  if (Array.isArray(headers)) {
+    for (let index = 0; index < headers.length; index += 2) {
+      const name = headers[index];
+      const value = headers[index + 1];
+      if (name !== undefined && value !== undefined) {
+        args.push('--header', `${name}: ${value}`);
+      }
+    }
+    return;
+  }
+  for (const [name, value] of Object.entries(headers ?? {})) {
+    if (value === undefined) continue;
+    const values = Array.isArray(value) ? value : [value];
+    for (const item of values) {
+      args.push('--header', `${name}: ${String(item)}`);
+    }
+  }
+}
+
+function buildBaseArgs(timeoutMs?: number): string[] {
+  const args = ['--fail', '--location', '--silent', '--show-error', '--connect-timeout', '30'];
+  if (typeof timeoutMs === 'number' && timeoutMs > 0) {
+    args.push('--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))));
+  }
+  return args;
+}
+
+function runCurl<T>(options: {
+  execFile: CurlExecFile;
+  curlPath: string;
+  args: readonly string[];
+  encoding: 'utf8' | 'buffer';
+  maxBuffer?: number;
+  timeout?: number;
+  cancellationToken?: CancellationTokenLike;
+}): Promise<T> {
+  const run = (
+    resolve: (value: T) => void,
+    reject: (error: Error) => void,
+    onCancel: (callback: () => void) => void,
+  ) => {
+    const child = options.execFile(
+      options.curlPath,
+      options.args,
+      {
+        encoding: options.encoding,
+        maxBuffer: options.maxBuffer,
+        timeout: options.timeout,
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          const stderrMessage = Buffer.isBuffer(stderr) ? stderr.toString('utf8') : stderr;
+          const errno = (error as NodeJS.ErrnoException).code;
+          const safeFallback = errno ? `curl failed (${errno})` : 'curl failed';
+          reject(new Error(stderrMessage.trim() || safeFallback));
+          return;
+        }
+        resolve(stdout as T);
+      },
+    );
+    onCancel(() => {
+      child.kill('SIGTERM');
+    });
+  };
+
+  if (options.cancellationToken) {
+    return options.cancellationToken.createPromise<T>(run);
+  }
+  return new Promise<T>((resolve, reject) => run(resolve, reject, () => {}));
+}
+
+export function createCurlHttpExecutor(
+  options: {
+    execFile?: CurlExecFile;
+    curlPath?: string;
+    mkdir?: (targetPath: string) => Promise<unknown>;
+    readFile?: (targetPath: string) => Promise<Buffer>;
+  } = {},
+): CurlHttpExecutor {
+  const execFile = options.execFile ?? (defaultExecFile as unknown as CurlExecFile);
+  const curlPath = options.curlPath ?? '/usr/bin/curl';
+  const mkdir =
+    options.mkdir ?? ((targetPath: string) => fs.promises.mkdir(targetPath, { recursive: true }));
+  const readFile = options.readFile ?? ((targetPath: string) => fs.promises.readFile(targetPath));
+
+  async function verifyDownloadedFile(destination: string, downloadOptions: CurlDownloadOptions) {
+    if (!downloadOptions.sha512 && !downloadOptions.sha2) return;
+    const data = await readFile(destination);
+    if (downloadOptions.sha512) {
+      const actual = createHash('sha512').update(data).digest('base64');
+      if (actual !== downloadOptions.sha512) {
+        throw new Error(`sha512 mismatch: expected ${downloadOptions.sha512}, got ${actual}`);
+      }
+    }
+    if (downloadOptions.sha2) {
+      const actual = createHash('sha256').update(data).digest('hex');
+      if (actual !== downloadOptions.sha2.toLowerCase()) {
+        throw new Error(`sha2 mismatch: expected ${downloadOptions.sha2}, got ${actual}`);
+      }
+    }
+  }
+
+  return {
+    async request(requestOptions, cancellationToken, data): Promise<string | null> {
+      const args = buildBaseArgs(requestOptions.timeout);
+      addHeaderArgs(args, requestOptions.headers);
+      if (requestOptions.method && requestOptions.method !== 'GET') {
+        args.push('--request', requestOptions.method);
+      }
+      if (data) {
+        args.push('--data-binary', JSON.stringify(data));
+      }
+      args.push(requestOptionsToUrl(requestOptions));
+      const result = await runCurl<string>({
+        execFile,
+        curlPath,
+        args,
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024,
+        timeout: requestOptions.timeout,
+        cancellationToken,
+      });
+      return result.length === 0 ? null : result;
+    },
+    async download(url, destination, downloadOptions): Promise<string> {
+      await mkdir(path.dirname(destination));
+      const args = buildBaseArgs();
+      addHeaderArgs(args, downloadOptions.headers);
+      args.push('--output', destination, url.href);
+      await runCurl<Buffer>({
+        execFile,
+        curlPath,
+        args,
+        encoding: 'buffer',
+        maxBuffer: 1024 * 1024,
+        cancellationToken: downloadOptions.cancellationToken,
+      });
+      await verifyDownloadedFile(destination, downloadOptions);
+      return destination;
+    },
+    async downloadToBuffer(url, downloadOptions): Promise<Buffer> {
+      const args = buildBaseArgs();
+      addHeaderArgs(args, downloadOptions.headers);
+      args.push(url.href);
+      return await runCurl<Buffer>({
+        execFile,
+        curlPath,
+        args,
+        encoding: 'buffer',
+        maxBuffer: 600 * 1024 * 1024,
+        cancellationToken: downloadOptions.cancellationToken,
+      });
+    },
+  };
+}

src/main/runtime/update/fetch-adapter.test.ts

@@ -0,0 +1,35 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createElectronNetFetch } from './fetch-adapter';
+import type { FetchResponseLike } from './release-assets';
+
+test('createElectronNetFetch delegates updater requests to Electron net.fetch', async () => {
+  const calls: Array<{ url: string; init?: Record<string, unknown> }> = [];
+  const response: FetchResponseLike = {
+    ok: true,
+    status: 200,
+    statusText: 'OK',
+    json: async () => ({ ok: true }),
+    text: async () => 'ok',
+    arrayBuffer: async () => new ArrayBuffer(0),
+  };
+
+  const fetch = createElectronNetFetch({
+    fetch: async (url, init) => {
+      calls.push({ url, init });
+      return response;
+    },
+  });
+
+  const result = await fetch('https://api.github.com/repos/ksyasuda/SubMiner/releases', {
+    headers: { 'User-Agent': 'SubMiner updater' },
+  });
+
+  assert.equal(result, response);
+  assert.deepEqual(calls, [
+    {
+      url: 'https://api.github.com/repos/ksyasuda/SubMiner/releases',
+      init: { headers: { 'User-Agent': 'SubMiner updater' } },
+    },
+  ]);
+});

src/main/runtime/update/fetch-adapter.ts

@@ -0,0 +1,9 @@
+import type { FetchLike, FetchResponseLike } from './release-assets';
+
+export interface ElectronNetFetchLike {
+  fetch: (url: string, init?: Record<string, unknown>) => Promise<FetchResponseLike>;
+}
+
+export function createElectronNetFetch(net: ElectronNetFetchLike): FetchLike {
+  return (url, init) => net.fetch(url, init);
+}

src/main/runtime/update/release-metadata-policy.test.ts

@@ -0,0 +1,48 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { shouldFetchReleaseMetadataForPlatform } from './release-metadata-policy';
+
+test('macOS release metadata fetch is skipped only when native updater is unsupported', () => {
+  assert.equal(
+    shouldFetchReleaseMetadataForPlatform('darwin', {
+      available: false,
+      version: '0.14.0',
+      canUpdate: false,
+    }),
+    false,
+  );
+  assert.equal(
+    shouldFetchReleaseMetadataForPlatform('darwin', {
+      available: false,
+      version: '0.14.0',
+    }),
+    true,
+  );
+  assert.equal(
+    shouldFetchReleaseMetadataForPlatform('darwin', {
+      available: true,
+      version: '0.15.0',
+      canUpdate: true,
+    }),
+    true,
+  );
+});
+
+test('non-macOS release metadata fetch is not gated by native updater support', () => {
+  assert.equal(
+    shouldFetchReleaseMetadataForPlatform('linux', {
+      available: false,
+      version: '0.14.0',
+      canUpdate: false,
+    }),
+    true,
+  );
+  assert.equal(
+    shouldFetchReleaseMetadataForPlatform('win32', {
+      available: false,
+      version: '0.14.0',
+      canUpdate: false,
+    }),
+    true,
+  );
+});

src/main/runtime/update/release-metadata-policy.ts

@@ -0,0 +1,15 @@
+type AppUpdateMetadata = {
+  available: boolean;
+  version: string;
+  canUpdate?: boolean;
+};
+
+export function shouldFetchReleaseMetadataForPlatform(
+  platform: NodeJS.Platform,
+  appUpdate: AppUpdateMetadata,
+): boolean {
+  if (platform !== 'darwin') {
+    return true;
+  }
+  return appUpdate.canUpdate !== false;
+}

src/main/runtime/update/update-service.test.ts

@@ -151,11 +151,72 @@ test('manual update check does not prompt restart when only launcher updates', a
   const result = await service.checkForUpdates({ source: 'manual' });
 
   assert.equal(result.status, 'update-available');
-  assert.deepEqual(calls, [
-    'available-dialog:0.15.0',
-    'launcher:stable',
-    'manual-install:0.15.0',
-  ]);
+  assert.deepEqual(calls, ['available-dialog:0.15.0', 'launcher:stable', 'manual-install:0.15.0']);
+});
+
+test('manual update check can skip release metadata after unsupported app updater', async () => {
+  const { deps, calls } = createDeps({
+    checkAppUpdate: async () => ({ available: false, version: '0.14.0', canUpdate: false }),
+    shouldFetchReleaseMetadata: ({ appUpdate }) => appUpdate.canUpdate !== false,
+    fetchLatestStableRelease: async () => {
+      calls.push('fetch-release');
+      return {
+        tag_name: 'v0.15.0',
+        prerelease: false,
+        draft: false,
+        assets: [],
+      };
+    },
+  } as Partial<UpdateServiceDeps>);
+  const service = createUpdateService(deps);
+
+  const result = await service.checkForUpdates({ source: 'manual' });
+
+  assert.equal(result.status, 'up-to-date');
+  assert.deepEqual(calls, ['no-update:0.14.0']);
+});
+
+test('manual update check fetches release metadata after app metadata errors', async () => {
+  const { deps, calls } = createDeps({
+    checkAppUpdate: async () => {
+      throw new Error('latest-mac.yml missing');
+    },
+    shouldFetchReleaseMetadata: ({ appUpdate }) => appUpdate.canUpdate !== false,
+    fetchLatestStableRelease: async () => {
+      calls.push('fetch-release');
+      return {
+        tag_name: 'v0.15.0',
+        prerelease: false,
+        draft: false,
+        assets: [],
+      };
+    },
+  } as Partial<UpdateServiceDeps>);
+  const service = createUpdateService(deps);
+
+  const result = await service.checkForUpdates({ source: 'manual' });
+
+  assert.equal(result.status, 'update-available');
+  assert.deepEqual(calls, ['fetch-release', 'available-dialog:0.15.0']);
+});
+
+test('manual update check reports non-Error failures safely', async () => {
+  const { deps, calls } = createDeps({
+    checkAppUpdate: async () => ({ available: true, version: '0.15.0' }),
+    showUpdateAvailableDialog: async (version) => {
+      calls.push(`available-dialog:${version}`);
+      return 'update';
+    },
+    downloadAppUpdate: async () => {
+      throw 'download rejected';
+    },
+  });
+  const service = createUpdateService(deps);
+
+  const result = await service.checkForUpdates({ source: 'manual' });
+
+  assert.deepEqual(result, { status: 'failed', error: 'download rejected' });
+  assert.deepEqual(calls, ['available-dialog:0.15.0', 'failed:download rejected']);
 });
 
 test('automatic update check skips inside configured interval', async () => {

src/main/runtime/update/update-service.ts

@@ -30,15 +30,24 @@ export interface UpdateCheckResult {
   error?: string;
 }
 
+type AppUpdateMetadata = {
+  available: boolean;
+  version: string;
+  canUpdate?: boolean;
+};
+
 export interface UpdateServiceDeps {
   getConfig: () => Required<UpdatesConfig>;
   getCurrentVersion: () => string;
   now: () => number;
   readState: () => Promise<UpdateState>;
   writeState: (state: UpdateState) => Promise<void>;
-  checkAppUpdate: (
-    channel: UpdateChannel,
-  ) => Promise<{ available: boolean; version: string; canUpdate?: boolean }>;
+  checkAppUpdate: (channel: UpdateChannel) => Promise<AppUpdateMetadata>;
+  shouldFetchReleaseMetadata?: (input: {
+    request: UpdateCheckRequest;
+    channel: UpdateChannel;
+    appUpdate: AppUpdateMetadata;
+  }) => boolean;
   fetchLatestStableRelease: (channel: UpdateChannel) => Promise<GitHubRelease | null>;
   updateLauncher: (
     launcherPath?: string,
@@ -112,22 +121,23 @@ export function createUpdateService(deps: UpdateServiceDeps) {
     }
 
     try {
-      const [appUpdate, release] = await Promise.all([
-        deps.checkAppUpdate(channel).catch((error) => {
+      const appUpdate: AppUpdateMetadata = await deps.checkAppUpdate(channel).catch((error) => {
         if (isAutomatic) {
           deps.log(`App update metadata check failed: ${summarizeError(error)}`);
         }
         return {
           available: false,
           version: deps.getCurrentVersion(),
-            canUpdate: false,
         };
-        }),
-        deps.fetchLatestStableRelease(channel).catch((error) => {
-          deps.log(`GitHub release update check failed: ${(error as Error).message}`);
+      });
+      const shouldFetchReleaseMetadata =
+        deps.shouldFetchReleaseMetadata?.({ request, channel, appUpdate }) ?? true;
+      const release = shouldFetchReleaseMetadata
+        ? await deps.fetchLatestStableRelease(channel).catch((error) => {
+            deps.log(`GitHub release update check failed: ${summarizeError(error)}`);
             return null;
-        }),
-      ]);
+          })
+        : null;
       const currentVersion = deps.getCurrentVersion();
       const latest = getBestLatestVersion(currentVersion, appUpdate, release);
 
@@ -181,7 +191,7 @@ export function createUpdateService(deps: UpdateServiceDeps) {
       }
       return { status: 'updated', version: latest.version };
     } catch (error) {
-      const message = (error as Error).message;
+      const message = summarizeError(error);
       if (isAutomatic) {
         deps.log(`Automatic update check failed: ${message}`);
       } else {

src/main/state.ts

@@ -151,6 +151,7 @@ export interface AppState {
   anilistSetupWindow: BrowserWindow | null;
   jellyfinSetupWindow: BrowserWindow | null;
   firstRunSetupWindow: BrowserWindow | null;
+  configSettingsWindow: BrowserWindow | null;
   yomitanParserReadyPromise: Promise<void> | null;
   yomitanParserInitPromise: Promise<boolean> | null;
   mpvClient: MpvIpcClient | null;
@@ -235,6 +236,7 @@ export function createAppState(values: AppStateInitialValues): AppState {
     anilistSetupWindow: null,
     jellyfinSetupWindow: null,
     firstRunSetupWindow: null,
+    configSettingsWindow: null,
     yomitanParserReadyPromise: null,
     yomitanParserInitPromise: null,
     mpvClient: null,

src/preload-settings.test.ts

@@ -0,0 +1,10 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import test from 'node:test';
+
+test('settings preload stays sandbox-compatible by avoiding local runtime imports', () => {
+  const source = fs.readFileSync(path.join(process.cwd(), 'src', 'preload-settings.ts'), 'utf8');
+
+  assert.doesNotMatch(source, /from\s+['"]\.\/shared\/ipc\/contracts(?:\.(?:js|ts))?['"]/);
+});

src/preload-settings.ts

@@ -0,0 +1,25 @@
+import { contextBridge, ipcRenderer } from 'electron';
+import type {
+  ConfigSettingsAPI,
+  ConfigSettingsPatch,
+  ConfigSettingsSaveResult,
+  ConfigSettingsSnapshot,
+} from './types/settings';
+
+const SETTINGS_IPC_CHANNELS = {
+  getSnapshot: 'config:get-settings-snapshot',
+  savePatch: 'config:save-settings-patch',
+  openFile: 'config:open-settings-file',
+  openWindow: 'config:open-settings-window',
+} as const;
+
+const configSettingsAPI: ConfigSettingsAPI = {
+  getSnapshot: (): Promise<ConfigSettingsSnapshot> =>
+    ipcRenderer.invoke(SETTINGS_IPC_CHANNELS.getSnapshot),
+  savePatch: (patch: ConfigSettingsPatch): Promise<ConfigSettingsSaveResult> =>
+    ipcRenderer.invoke(SETTINGS_IPC_CHANNELS.savePatch, patch),
+  openSettingsFile: (): Promise<boolean> => ipcRenderer.invoke(SETTINGS_IPC_CHANNELS.openFile),
+  openSettingsWindow: (): Promise<boolean> => ipcRenderer.invoke(SETTINGS_IPC_CHANNELS.openWindow),
+};
+
+contextBridge.exposeInMainWorld('configSettingsAPI', configSettingsAPI);

src/settings/index.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      http-equiv="Content-Security-Policy"
+      content="default-src 'self'; script-src 'self'; style-src 'self';"
+    />
+    <title>SubMiner Configuration</title>
+    <link rel="stylesheet" href="style.css" />
+  </head>
+  <body>
+    <main id="app" class="settings-shell">
+      <aside class="settings-nav" aria-label="Configuration categories">
+        <div class="brand-block">
+          <div class="brand-title">SubMiner</div>
+          <div class="brand-subtitle">Configuration</div>
+        </div>
+        <nav id="categoryNav" class="category-nav"></nav>
+      </aside>
+      <section class="settings-main">
+        <header class="settings-toolbar">
+          <div class="toolbar-title-block">
+            <h1 id="categoryTitle">Configuration</h1>
+            <div id="categoryMeta" class="toolbar-meta"></div>
+          </div>
+          <div class="toolbar-actions">
+            <input
+              id="searchInput"
+              class="search-input"
+              type="search"
+              placeholder="Search"
+              aria-label="Search settings"
+            />
+            <button id="openFileButton" class="secondary-button" type="button">Open File</button>
+            <button id="saveButton" class="primary-button" type="button" disabled>Save</button>
+          </div>
+        </header>
+        <div id="statusBanner" class="status-banner hidden" role="status"></div>
+        <div id="warningsPanel" class="warnings-panel hidden"></div>
+        <div id="settingsContent" class="settings-content"></div>
+      </section>
+    </main>
+    <script type="module" src="settings.js"></script>
+  </body>
+</html>

src/settings/input-values.test.ts

@@ -0,0 +1,17 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseOptionalNumberInputValue } from './input-values';
+
+test('parseOptionalNumberInputValue treats empty input as unset', () => {
+  assert.deepEqual(parseOptionalNumberInputValue(''), { ok: true, value: undefined });
+  assert.deepEqual(parseOptionalNumberInputValue('   '), { ok: true, value: undefined });
+});
+
+test('parseOptionalNumberInputValue parses finite numeric input', () => {
+  assert.deepEqual(parseOptionalNumberInputValue('42'), { ok: true, value: 42 });
+  assert.deepEqual(parseOptionalNumberInputValue(' 3.5 '), { ok: true, value: 3.5 });
+});
+
+test('parseOptionalNumberInputValue rejects invalid numeric input', () => {
+  assert.deepEqual(parseOptionalNumberInputValue('abc'), { ok: false });
+});

src/settings/input-values.ts

@@ -0,0 +1,20 @@
+export type OptionalNumberInputParseResult =
+  | {
+      ok: true;
+      value: number | undefined;
+    }
+  | {
+      ok: false;
+    };
+
+export function parseOptionalNumberInputValue(value: string): OptionalNumberInputParseResult {
+  const raw = value.trim();
+  if (raw.length === 0) {
+    return { ok: true, value: undefined };
+  }
+  const next = Number(raw);
+  if (!Number.isFinite(next)) {
+    return { ok: false };
+  }
+  return { ok: true, value: next };
+}

src/settings/settings-model.test.ts

@@ -0,0 +1,62 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createSettingsDraft,
+  filterSettingsFields,
+  setDraftValue,
+  getDirtyOperations,
+} from './settings-model';
+import type { ConfigSettingsField } from '../types/settings';
+
+const fields: ConfigSettingsField[] = [
+  {
+    id: 'subtitleStyle.autoPauseVideoOnHover',
+    label: 'Pause on subtitle hover',
+    description: 'Pause while hovering subtitles.',
+    configPath: 'subtitleStyle.autoPauseVideoOnHover',
+    category: 'viewing',
+    section: 'Playback pause behavior',
+    control: 'boolean',
+    defaultValue: true,
+    restartBehavior: 'hot-reload',
+  },
+  {
+    id: 'ankiConnect.enabled',
+    label: 'Enable AnkiConnect',
+    description: 'Enable Anki integration.',
+    configPath: 'ankiConnect.enabled',
+    category: 'mining-anki',
+    section: 'Connection',
+    control: 'boolean',
+    defaultValue: true,
+    restartBehavior: 'restart',
+  },
+];
+
+test('filterSettingsFields searches label, section, and config path', () => {
+  assert.deepEqual(
+    filterSettingsFields(fields, { category: 'viewing', query: 'hover' }).map(
+      (field) => field.configPath,
+    ),
+    ['subtitleStyle.autoPauseVideoOnHover'],
+  );
+  assert.deepEqual(filterSettingsFields(fields, { category: 'viewing', query: 'anki' }), []);
+});
+
+test('settings draft tracks dirty set and emits save operations', () => {
+  const draft = createSettingsDraft({
+    'subtitleStyle.autoPauseVideoOnHover': true,
+  });
+
+  setDraftValue(draft, 'subtitleStyle.autoPauseVideoOnHover', false);
+  assert.deepEqual(getDirtyOperations(draft), [
+    {
+      op: 'set',
+      path: 'subtitleStyle.autoPauseVideoOnHover',
+      value: false,
+    },
+  ]);
+
+  setDraftValue(draft, 'subtitleStyle.autoPauseVideoOnHover', true);
+  assert.deepEqual(getDirtyOperations(draft), []);
+});

src/settings/settings-model.ts

@@ -0,0 +1,95 @@
+import type {
+  ConfigSettingsCategory,
+  ConfigSettingsField,
+  ConfigSettingsPatchOperation,
+  ConfigSettingsSnapshotValue,
+} from '../types/settings';
+
+export interface SettingsFilter {
+  category: ConfigSettingsCategory;
+  query?: string;
+}
+
+export interface SettingsDraft {
+  readonly initialValues: Record<string, ConfigSettingsSnapshotValue>;
+  readonly values: Record<string, ConfigSettingsSnapshotValue>;
+  readonly resetPaths: Set<string>;
+}
+
+function normalizeQuery(query: string | undefined): string {
+  return (query ?? '').trim().toLowerCase();
+}
+
+function valuesEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+export function filterSettingsFields(
+  fields: ConfigSettingsField[],
+  filter: SettingsFilter,
+): ConfigSettingsField[] {
+  const query = normalizeQuery(filter.query);
+  return fields.filter((field) => {
+    if (field.category !== filter.category || field.legacyHidden) {
+      return false;
+    }
+    if (!query) {
+      return true;
+    }
+    const haystack = [
+      field.label,
+      field.description,
+      field.configPath,
+      field.section,
+      field.enumValues?.join(' ') ?? '',
+    ]
+      .join(' ')
+      .toLowerCase();
+    return haystack.includes(query);
+  });
+}
+
+export function createSettingsDraft(
+  values: Record<string, ConfigSettingsSnapshotValue>,
+): SettingsDraft {
+  return {
+    initialValues: structuredClone(values),
+    values: structuredClone(values),
+    resetPaths: new Set(),
+  };
+}
+
+export function setDraftValue(
+  draft: SettingsDraft,
+  path: string,
+  value: ConfigSettingsSnapshotValue,
+): void {
+  draft.values[path] = value;
+  draft.resetPaths.delete(path);
+}
+
+export function resetDraftPath(draft: SettingsDraft, path: string, defaultValue: unknown): void {
+  draft.values[path] = structuredClone(defaultValue);
+  draft.resetPaths.add(path);
+}
+
+export function getDirtyOperations(draft: SettingsDraft): ConfigSettingsPatchOperation[] {
+  const operations: ConfigSettingsPatchOperation[] = [];
+  const paths = new Set([...Object.keys(draft.initialValues), ...Object.keys(draft.values)]);
+
+  for (const path of [...paths].sort()) {
+    if (draft.resetPaths.has(path)) {
+      operations.push({ op: 'reset', path });
+      continue;
+    }
+    if (!valuesEqual(draft.values[path], draft.initialValues[path])) {
+      operations.push({
+        op: 'set',
+        path,
+        value: draft.values[path],
+      });
+    }
+  }
+
+  return operations;
+}

src/settings/settings.ts

@@ -0,0 +1,452 @@
+import type {
+  ConfigSettingsAPI,
+  ConfigSettingsCategory,
+  ConfigSettingsField,
+  ConfigSettingsPatchOperation,
+  ConfigSettingsSnapshot,
+  ConfigSettingsSnapshotValue,
+} from '../types/settings';
+import { parseOptionalNumberInputValue } from './input-values';
+import {
+  createSettingsDraft,
+  filterSettingsFields,
+  getDirtyOperations,
+  resetDraftPath,
+  setDraftValue,
+  type SettingsDraft,
+} from './settings-model';
+
+declare global {
+  interface Window {
+    configSettingsAPI: ConfigSettingsAPI;
+  }
+}
+
+const CATEGORY_LABELS: Record<ConfigSettingsCategory, string> = {
+  viewing: 'Viewing',
+  'mining-anki': 'Mining & Anki',
+  'playback-sources': 'Playback & Sources',
+  input: 'Input',
+  integrations: 'Integrations',
+  'tracking-app': 'Tracking & App',
+  advanced: 'Advanced',
+};
+
+const CATEGORY_ORDER: ConfigSettingsCategory[] = [
+  'viewing',
+  'mining-anki',
+  'playback-sources',
+  'input',
+  'integrations',
+  'tracking-app',
+  'advanced',
+];
+
+const state: {
+  snapshot: ConfigSettingsSnapshot | null;
+  draft: SettingsDraft | null;
+  category: ConfigSettingsCategory;
+  query: string;
+  inputErrors: Map<string, string>;
+} = {
+  snapshot: null,
+  draft: null,
+  category: 'viewing',
+  query: '',
+  inputErrors: new Map(),
+};
+
+function getElement<T extends HTMLElement>(id: string): T {
+  const element = document.getElementById(id);
+  if (!element) {
+    throw new Error(`Missing settings element: ${id}`);
+  }
+  return element as T;
+}
+
+const dom = {
+  categoryNav: getElement<HTMLElement>('categoryNav'),
+  categoryTitle: getElement<HTMLHeadingElement>('categoryTitle'),
+  categoryMeta: getElement<HTMLElement>('categoryMeta'),
+  searchInput: getElement<HTMLInputElement>('searchInput'),
+  openFileButton: getElement<HTMLButtonElement>('openFileButton'),
+  saveButton: getElement<HTMLButtonElement>('saveButton'),
+  statusBanner: getElement<HTMLElement>('statusBanner'),
+  warningsPanel: getElement<HTMLElement>('warningsPanel'),
+  settingsContent: getElement<HTMLElement>('settingsContent'),
+};
+
+function isSecretSnapshotValue(
+  value: ConfigSettingsSnapshotValue,
+): value is { configured: boolean } {
+  return Boolean(value && typeof value === 'object' && 'configured' in value);
+}
+
+function setStatus(message: string, tone: 'info' | 'error' | 'success' = 'info'): void {
+  dom.statusBanner.textContent = message;
+  dom.statusBanner.className = `status-banner ${tone}`;
+}
+
+function clearStatus(): void {
+  dom.statusBanner.textContent = '';
+  dom.statusBanner.className = 'status-banner hidden';
+}
+
+function getDirtyCount(): number {
+  return state.draft ? getDirtyOperations(state.draft).length : 0;
+}
+
+function syncSaveButton(): void {
+  const dirtyCount = getDirtyCount();
+  dom.saveButton.disabled = dirtyCount === 0 || state.inputErrors.size > 0;
+  dom.saveButton.textContent = dirtyCount > 0 ? `Save ${dirtyCount}` : 'Save';
+}
+
+function createElement<K extends keyof HTMLElementTagNameMap>(
+  tagName: K,
+  className?: string,
+): HTMLElementTagNameMap[K] {
+  const element = document.createElement(tagName);
+  if (className) {
+    element.className = className;
+  }
+  return element;
+}
+
+function createFieldMeta(field: ConfigSettingsField): HTMLElement {
+  const meta = createElement('div', 'field-meta');
+  const path = createElement('code');
+  path.textContent = field.configPath;
+  meta.append(path);
+
+  const restart = createElement('span', `restart-chip ${field.restartBehavior}`);
+  restart.textContent = field.restartBehavior === 'hot-reload' ? 'Live' : 'Restart';
+  meta.append(restart);
+
+  if (field.advanced) {
+    const advanced = createElement('span', 'advanced-chip');
+    advanced.textContent = 'Advanced';
+    meta.append(advanced);
+  }
+  return meta;
+}
+
+function valueForField(field: ConfigSettingsField): ConfigSettingsSnapshotValue {
+  return state.draft?.values[field.configPath] ?? field.defaultValue;
+}
+
+function setFieldError(path: string, message: string | null): void {
+  if (message) {
+    state.inputErrors.set(path, message);
+  } else {
+    state.inputErrors.delete(path);
+  }
+  syncSaveButton();
+}
+
+function updateDraft(path: string, value: ConfigSettingsSnapshotValue): void {
+  if (!state.draft) return;
+  setDraftValue(state.draft, path, value);
+  syncSaveButton();
+}
+
+function renderJsonInput(
+  field: ConfigSettingsField,
+  value: ConfigSettingsSnapshotValue,
+): HTMLElement {
+  const textarea = createElement('textarea', 'config-textarea') as HTMLTextAreaElement;
+  textarea.spellcheck = false;
+  textarea.value = JSON.stringify(value ?? {}, null, 2);
+  textarea.addEventListener('input', () => {
+    try {
+      updateDraft(field.configPath, JSON.parse(textarea.value));
+      textarea.classList.remove('invalid');
+      setFieldError(field.configPath, null);
+    } catch {
+      textarea.classList.add('invalid');
+      setFieldError(field.configPath, 'Invalid JSON');
+    }
+  });
+  return textarea;
+}
+
+function renderStringListInput(
+  field: ConfigSettingsField,
+  value: ConfigSettingsSnapshotValue,
+): HTMLElement {
+  const textarea = createElement('textarea', 'config-textarea compact') as HTMLTextAreaElement;
+  textarea.spellcheck = false;
+  textarea.value = Array.isArray(value) ? value.join('\n') : '';
+  textarea.addEventListener('input', () => {
+    updateDraft(
+      field.configPath,
+      textarea.value
+        .split('\n')
+        .map((entry) => entry.trim())
+        .filter(Boolean),
+    );
+  });
+  return textarea;
+}
+
+function renderControl(field: ConfigSettingsField): HTMLElement {
+  const value = valueForField(field);
+
+  if (field.control === 'boolean') {
+    const label = createElement('label', 'switch-control');
+    const input = createElement('input') as HTMLInputElement;
+    input.type = 'checkbox';
+    input.checked = Boolean(value);
+    input.addEventListener('change', () => updateDraft(field.configPath, input.checked));
+    const track = createElement('span', 'switch-track');
+    label.append(input, track);
+    return label;
+  }
+
+  if (field.control === 'number') {
+    const input = createElement('input', 'config-input') as HTMLInputElement;
+    input.type = 'number';
+    input.value = typeof value === 'number' ? String(value) : '';
+    input.addEventListener('input', () => {
+      const next = parseOptionalNumberInputValue(input.value);
+      if (next.ok) {
+        input.classList.remove('invalid');
+        setFieldError(field.configPath, null);
+        updateDraft(field.configPath, next.value);
+      } else {
+        input.classList.add('invalid');
+        setFieldError(field.configPath, 'Invalid number');
+      }
+    });
+    return input;
+  }
+
+  if (field.control === 'select') {
+    const select = createElement('select', 'config-input') as HTMLSelectElement;
+    for (const enumValue of field.enumValues ?? []) {
+      const option = createElement('option') as HTMLOptionElement;
+      option.value = enumValue;
+      option.textContent = enumValue;
+      option.selected = enumValue === value;
+      select.append(option);
+    }
+    select.addEventListener('change', () => updateDraft(field.configPath, select.value));
+    return select;
+  }
+
+  if (field.control === 'string-list') {
+    return renderStringListInput(field, value);
+  }
+
+  if (field.control === 'json') {
+    return renderJsonInput(field, value);
+  }
+
+  if (field.control === 'textarea') {
+    const textarea = createElement('textarea', 'config-textarea compact') as HTMLTextAreaElement;
+    textarea.spellcheck = false;
+    textarea.value = typeof value === 'string' ? value : '';
+    textarea.addEventListener('input', () => updateDraft(field.configPath, textarea.value));
+    return textarea;
+  }
+
+  const input = createElement('input', 'config-input') as HTMLInputElement;
+  input.type = field.control === 'secret' ? 'password' : field.control;
+  if (field.control === 'secret') {
+    input.placeholder =
+      isSecretSnapshotValue(value) && value.configured ? 'Configured' : 'Not configured';
+    input.addEventListener('input', () => {
+      if (input.value.trim().length === 0) {
+        if (state.draft) {
+          setDraftValue(state.draft, field.configPath, state.draft.initialValues[field.configPath]);
+        }
+        syncSaveButton();
+        return;
+      }
+      updateDraft(field.configPath, input.value);
+    });
+  } else {
+    input.value = typeof value === 'string' ? value : '';
+    input.addEventListener('input', () => updateDraft(field.configPath, input.value));
+  }
+  return input;
+}
+
+function renderWarnings(snapshot: ConfigSettingsSnapshot): void {
+  dom.warningsPanel.replaceChildren();
+  if (snapshot.warnings.length === 0) {
+    dom.warningsPanel.className = 'warnings-panel hidden';
+    return;
+  }
+
+  const title = createElement('div', 'warnings-title');
+  title.textContent = `${snapshot.warnings.length} validation warning${
+    snapshot.warnings.length === 1 ? '' : 's'
+  }`;
+  dom.warningsPanel.append(title);
+
+  for (const warning of snapshot.warnings.slice(0, 6)) {
+    const row = createElement('div', 'warning-row');
+    const path = createElement('code');
+    path.textContent = warning.path;
+    const message = createElement('span');
+    message.textContent = warning.message;
+    row.append(path, message);
+    dom.warningsPanel.append(row);
+  }
+  dom.warningsPanel.className = 'warnings-panel';
+}
+
+function renderCategoryNav(snapshot: ConfigSettingsSnapshot): void {
+  dom.categoryNav.replaceChildren();
+  for (const category of CATEGORY_ORDER) {
+    const count = snapshot.fields.filter(
+      (field) => field.category === category && !field.legacyHidden,
+    ).length;
+    if (count === 0) continue;
+    const button = createElement('button', 'category-button') as HTMLButtonElement;
+    button.type = 'button';
+    button.classList.toggle('active', state.category === category);
+    const label = createElement('span');
+    label.textContent = CATEGORY_LABELS[category];
+    const badge = createElement('strong');
+    badge.textContent = String(count);
+    button.append(label, badge);
+    button.addEventListener('click', () => {
+      state.category = category;
+      render();
+    });
+    dom.categoryNav.append(button);
+  }
+}
+
+function renderField(field: ConfigSettingsField): HTMLElement {
+  const row = createElement('article', 'field-row');
+  const header = createElement('div', 'field-copy');
+  const label = createElement('h3');
+  label.textContent = field.label;
+  const description = createElement('p');
+  description.textContent = field.description;
+  header.append(label, description, createFieldMeta(field));
+
+  const controlWrap = createElement('div', 'field-control');
+  controlWrap.append(renderControl(field));
+  const resetButton = createElement('button', 'reset-button') as HTMLButtonElement;
+  resetButton.type = 'button';
+  resetButton.textContent = 'Reset';
+  resetButton.addEventListener('click', () => {
+    if (!state.draft) return;
+    resetDraftPath(state.draft, field.configPath, field.defaultValue);
+    state.inputErrors.delete(field.configPath);
+    render();
+  });
+  controlWrap.append(resetButton);
+  row.append(header, controlWrap);
+  return row;
+}
+
+function renderSettingsContent(snapshot: ConfigSettingsSnapshot): void {
+  dom.settingsContent.replaceChildren();
+  const fields = filterSettingsFields(snapshot.fields, {
+    category: state.category,
+    query: state.query,
+  });
+
+  dom.categoryTitle.textContent = CATEGORY_LABELS[state.category];
+  dom.categoryMeta.textContent = `${fields.length} setting${fields.length === 1 ? '' : 's'}`;
+
+  if (fields.length === 0) {
+    const empty = createElement('div', 'empty-state');
+    empty.textContent = 'No matching settings';
+    dom.settingsContent.append(empty);
+    return;
+  }
+
+  const sections = new Map<string, ConfigSettingsField[]>();
+  for (const field of fields) {
+    const sectionFields = sections.get(field.section) ?? [];
+    sectionFields.push(field);
+    sections.set(field.section, sectionFields);
+  }
+
+  for (const [section, sectionFields] of sections) {
+    const sectionEl = createElement('section', 'settings-section');
+    const title = createElement('h2');
+    title.textContent = section;
+    sectionEl.append(title);
+    for (const field of sectionFields) {
+      sectionEl.append(renderField(field));
+    }
+    dom.settingsContent.append(sectionEl);
+  }
+}
+
+function render(): void {
+  const snapshot = state.snapshot;
+  if (!snapshot) return;
+  renderCategoryNav(snapshot);
+  renderWarnings(snapshot);
+  renderSettingsContent(snapshot);
+  syncSaveButton();
+}
+
+async function loadSnapshot(): Promise<void> {
+  clearStatus();
+  const snapshot = await window.configSettingsAPI.getSnapshot();
+  state.snapshot = snapshot;
+  state.draft = createSettingsDraft(snapshot.values);
+  state.inputErrors.clear();
+  render();
+}
+
+async function save(): Promise<void> {
+  if (!state.draft) return;
+  const operations: ConfigSettingsPatchOperation[] = getDirtyOperations(state.draft);
+  if (operations.length === 0) return;
+
+  dom.saveButton.disabled = true;
+  setStatus('Saving...', 'info');
+  try {
+    const result = await window.configSettingsAPI.savePatch({ operations });
+    if (!result.ok || !result.snapshot) {
+      const message =
+        result.error ??
+        result.warnings?.map((warning) => `${warning.path}: ${warning.message}`).join('\n') ??
+        'Save failed';
+      setStatus(message, 'error');
+      return;
+    }
+
+    state.snapshot = result.snapshot;
+    state.draft = createSettingsDraft(result.snapshot.values);
+    state.inputErrors.clear();
+    const restartSections = result.restartRequiredSections ?? [];
+    if (restartSections.length > 0) {
+      setStatus(`Saved. Restart required: ${restartSections.join(', ')}`, 'info');
+    } else if (result.hotReloadFields.length > 0) {
+      setStatus('Saved. Live settings applied.', 'success');
+    } else {
+      setStatus('Saved.', 'success');
+    }
+    render();
+  } catch (error) {
+    setStatus(error instanceof Error ? error.message : 'Save failed', 'error');
+  } finally {
+    syncSaveButton();
+  }
+}
+
+dom.searchInput.addEventListener('input', () => {
+  state.query = dom.searchInput.value;
+  render();
+});
+dom.saveButton.addEventListener('click', () => {
+  void save();
+});
+dom.openFileButton.addEventListener('click', () => {
+  void window.configSettingsAPI.openSettingsFile();
+});
+
+void loadSnapshot().catch((error) => {
+  setStatus(error instanceof Error ? error.message : 'Failed to load settings', 'error');
+});

src/settings/style.css

@@ -0,0 +1,655 @@
+@font-face {
+  font-family: 'M PLUS 1';
+  src: url('./fonts/MPLUS1[wght].ttf') format('truetype');
+  font-weight: 100 900;
+  font-display: swap;
+}
+
+:root {
+  /* Catppuccin Macchiato */
+  --ctp-rosewater: #f4dbd6;
+  --ctp-flamingo: #f0c6c6;
+  --ctp-pink: #f5bde6;
+  --ctp-mauve: #c6a0f6;
+  --ctp-red: #ed8796;
+  --ctp-maroon: #ee99a0;
+  --ctp-peach: #f5a97f;
+  --ctp-yellow: #eed49f;
+  --ctp-green: #a6da95;
+  --ctp-teal: #8bd5ca;
+  --ctp-sky: #91d7e3;
+  --ctp-sapphire: #7dc4e4;
+  --ctp-blue: #8aadf4;
+  --ctp-lavender: #b7bdf8;
+  --ctp-text: #cad3f5;
+  --ctp-subtext1: #b8c0e0;
+  --ctp-subtext0: #a5adcb;
+  --ctp-overlay2: #939ab7;
+  --ctp-overlay1: #8087a2;
+  --ctp-overlay0: #6e738d;
+  --ctp-surface2: #5b6078;
+  --ctp-surface1: #494d64;
+  --ctp-surface0: #363a4f;
+  --ctp-base: #24273a;
+  --ctp-mantle: #1e2030;
+  --ctp-crust: #181926;
+
+  /* Semantic */
+  --bg: var(--ctp-base);
+  --panel: rgba(36, 39, 58, 0.85);
+  --panel-elevated: rgba(54, 58, 79, 0.55);
+  --line: rgba(110, 115, 141, 0.28);
+  --line-soft: rgba(110, 115, 141, 0.14);
+  --text: var(--ctp-text);
+  --muted: var(--ctp-subtext0);
+  --faint: var(--ctp-overlay1);
+  --accent: var(--ctp-blue);
+  --accent-strong: var(--ctp-lavender);
+  --highlight: var(--ctp-mauve);
+  --danger: var(--ctp-red);
+  --ok: var(--ctp-green);
+  --warn: var(--ctp-peach);
+  --shadow: rgba(0, 0, 0, 0.42);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+html,
+body {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  overflow: hidden;
+  background: var(--ctp-base);
+  color: var(--text);
+  font-family:
+    'M PLUS 1', 'Avenir Next', 'Hiragino Sans', 'Hiragino Kaku Gothic ProN', 'Yu Gothic', sans-serif;
+  letter-spacing: 0;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+button {
+  font-family: inherit;
+}
+
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  border: 2px solid transparent;
+  border-radius: 999px;
+  background-clip: padding-box;
+  background-color: rgba(110, 115, 141, 0.35);
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background-color: rgba(138, 173, 244, 0.45);
+}
+
+.settings-shell {
+  display: grid;
+  grid-template-columns: 244px minmax(0, 1fr);
+  width: 100%;
+  height: 100%;
+}
+
+.settings-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  padding: 22px 16px;
+  border-right: 1px solid var(--line);
+  background: var(--ctp-mantle);
+}
+
+.brand-block {
+  padding: 6px 8px 14px;
+  border-bottom: 1px solid var(--line-soft);
+}
+
+.brand-title {
+  font-size: 21px;
+  font-weight: 820;
+  color: var(--ctp-lavender);
+}
+
+.brand-subtitle {
+  margin-top: 4px;
+  color: var(--ctp-overlay2);
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.category-nav {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.category-button {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  min-height: 38px;
+  padding: 8px 11px;
+  border: 1px solid transparent;
+  border-radius: 9px;
+  background: transparent;
+  color: var(--muted);
+  text-align: left;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+  transition:
+    background 140ms ease,
+    border-color 140ms ease,
+    color 140ms ease;
+}
+
+.category-button:hover {
+  border-color: var(--line-soft);
+  background: rgba(138, 173, 244, 0.06);
+  color: var(--text);
+}
+
+.category-button.active {
+  border-color: rgba(138, 173, 244, 0.42);
+  background: rgba(138, 173, 244, 0.14);
+  color: var(--text);
+}
+
+.category-button strong {
+  min-width: 24px;
+  padding: 2px 7px;
+  border-radius: 999px;
+  background: rgba(110, 115, 141, 0.2);
+  color: var(--ctp-subtext0);
+  font-size: 11px;
+  font-weight: 700;
+  text-align: center;
+}
+
+.category-button.active strong {
+  background: rgba(138, 173, 244, 0.22);
+  color: var(--ctp-lavender);
+}
+
+.settings-main {
+  min-width: 0;
+  height: 100%;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+.settings-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 18px;
+  min-height: 78px;
+  padding: 18px 24px;
+  border-bottom: 1px solid var(--line);
+  background: var(--ctp-mantle);
+}
+
+.toolbar-title-block {
+  min-width: 0;
+}
+
+h1 {
+  margin: 0;
+  font-size: 22px;
+  line-height: 1.15;
+  font-weight: 800;
+  color: var(--ctp-text);
+  letter-spacing: -0.01em;
+}
+
+.toolbar-meta {
+  margin-top: 5px;
+  color: var(--ctp-overlay2);
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.toolbar-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.search-input,
+.config-input,
+.config-textarea {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: rgba(24, 25, 38, 0.85);
+  color: var(--text);
+  outline: none;
+  transition:
+    border-color 140ms ease,
+    box-shadow 140ms ease,
+    background 140ms ease;
+}
+
+.search-input::placeholder,
+.config-input::placeholder,
+.config-textarea::placeholder {
+  color: var(--ctp-overlay0);
+}
+
+.search-input {
+  width: 210px;
+  height: 36px;
+  padding: 0 12px;
+}
+
+.config-input {
+  width: min(320px, 100%);
+  min-height: 36px;
+  padding: 7px 10px;
+}
+
+.config-textarea {
+  width: min(420px, 100%);
+  min-height: 138px;
+  padding: 9px 11px;
+  resize: vertical;
+  font-family:
+    'JetBrains Mono', 'SF Mono', 'M PLUS 1', 'Avenir Next', ui-monospace, SFMono-Regular, Menlo,
+    monospace;
+  font-size: 12.5px;
+  line-height: 1.55;
+}
+
+.config-textarea.compact {
+  min-height: 86px;
+}
+
+.search-input:hover,
+.config-input:hover,
+.config-textarea:hover {
+  border-color: rgba(138, 173, 244, 0.32);
+}
+
+.search-input:focus,
+.config-input:focus,
+.config-textarea:focus {
+  border-color: rgba(138, 173, 244, 0.65);
+  background: rgba(24, 25, 38, 0.95);
+  box-shadow: 0 0 0 3px rgba(138, 173, 244, 0.15);
+}
+
+select.config-input {
+  appearance: none;
+  padding-right: 32px;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6' fill='none'><path d='M1 1l4 4 4-4' stroke='%23a5adcb' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/></svg>");
+  background-position: right 12px center;
+  background-repeat: no-repeat;
+}
+
+select.config-input option {
+  background: var(--ctp-mantle);
+  color: var(--text);
+}
+
+.invalid,
+.invalid:focus {
+  border-color: rgba(237, 135, 150, 0.65);
+  box-shadow: 0 0 0 3px rgba(237, 135, 150, 0.12);
+}
+
+.primary-button,
+.secondary-button,
+.reset-button {
+  height: 36px;
+  border-radius: 8px;
+  border: 1px solid var(--line);
+  cursor: pointer;
+  font-weight: 700;
+  font-size: 13px;
+  transition:
+    background 140ms ease,
+    border-color 140ms ease,
+    color 140ms ease,
+    transform 60ms ease;
+}
+
+.primary-button:active,
+.secondary-button:active,
+.reset-button:active {
+  transform: translateY(1px);
+}
+
+.primary-button {
+  min-width: 92px;
+  padding: 0 16px;
+  border-color: transparent;
+  background: var(--ctp-blue);
+  color: var(--ctp-crust);
+}
+
+.primary-button:hover:not(:disabled) {
+  filter: brightness(1.06);
+}
+
+.primary-button:disabled {
+  border-color: var(--line);
+  background: rgba(54, 58, 79, 0.55);
+  color: var(--ctp-overlay0);
+  box-shadow: none;
+  cursor: default;
+}
+
+.secondary-button,
+.reset-button {
+  padding: 0 13px;
+  background: rgba(54, 58, 79, 0.5);
+  color: var(--text);
+}
+
+.secondary-button:hover,
+.reset-button:hover {
+  border-color: rgba(138, 173, 244, 0.45);
+  background: rgba(73, 77, 100, 0.6);
+  color: var(--ctp-lavender);
+}
+
+.reset-button {
+  height: 32px;
+  padding: 0 10px;
+  font-size: 12px;
+  color: var(--ctp-subtext0);
+}
+
+.status-banner,
+.warnings-panel {
+  margin: 14px 24px 0;
+  border-radius: 10px;
+  border: 1px solid var(--line);
+  background: var(--ctp-surface0);
+}
+
+.status-banner {
+  padding: 11px 14px;
+  white-space: pre-wrap;
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--ctp-subtext1);
+}
+
+.status-banner.success {
+  border-color: rgba(166, 218, 149, 0.45);
+  background: rgba(166, 218, 149, 0.1);
+  color: var(--ctp-green);
+}
+
+.status-banner.error {
+  border-color: rgba(237, 135, 150, 0.55);
+  background: rgba(237, 135, 150, 0.1);
+  color: var(--ctp-red);
+}
+
+.hidden {
+  display: none !important;
+}
+
+.warnings-panel {
+  padding: 12px 14px;
+  border-color: rgba(238, 212, 159, 0.32);
+  background: rgba(238, 212, 159, 0.07);
+}
+
+.warnings-title {
+  margin-bottom: 8px;
+  color: var(--ctp-yellow);
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+}
+
+.warning-row {
+  display: grid;
+  grid-template-columns: minmax(120px, 220px) minmax(0, 1fr);
+  gap: 12px;
+  padding: 5px 0;
+  color: var(--ctp-subtext1);
+  font-size: 12px;
+  line-height: 1.5;
+}
+
+code {
+  padding: 2px 6px;
+  border-radius: 5px;
+  background: rgba(24, 25, 38, 0.7);
+  border: 1px solid var(--line-soft);
+  color: var(--ctp-teal);
+  font-family: 'JetBrains Mono', 'SF Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 11px;
+  font-weight: 500;
+}
+
+.settings-content {
+  min-height: 0;
+  overflow: auto;
+  padding: 20px 24px 32px;
+}
+
+.settings-section {
+  margin-bottom: 24px;
+  border-radius: 12px;
+  border: 1px solid var(--line-soft);
+  background: var(--ctp-mantle);
+  overflow: hidden;
+}
+
+.settings-section h2 {
+  margin: 0;
+  padding: 12px 16px;
+  background: var(--ctp-crust);
+  border-bottom: 1px solid var(--line-soft);
+  color: var(--ctp-lavender);
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.14em;
+  text-transform: uppercase;
+}
+
+.field-row {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(220px, 430px);
+  gap: 20px;
+  align-items: start;
+  padding: 16px 16px;
+  border-top: 1px solid var(--line-soft);
+}
+
+.settings-section h2 + .field-row {
+  border-top: none;
+}
+
+.field-copy h3 {
+  margin: 0 0 5px;
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--ctp-text);
+  letter-spacing: -0.005em;
+}
+
+.field-copy p {
+  max-width: 640px;
+  margin: 0;
+  color: var(--ctp-subtext0);
+  font-size: 12.5px;
+  line-height: 1.55;
+}
+
+.field-meta {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 6px;
+  margin-top: 10px;
+}
+
+.restart-chip,
+.advanced-chip {
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--line);
+  background: rgba(54, 58, 79, 0.5);
+  color: var(--ctp-overlay2);
+  font-size: 10px;
+  font-weight: 800;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.restart-chip.hot-reload {
+  border-color: rgba(166, 218, 149, 0.42);
+  background: rgba(166, 218, 149, 0.1);
+  color: var(--ctp-green);
+}
+
+.restart-chip.restart {
+  border-color: rgba(245, 169, 127, 0.42);
+  background: rgba(245, 169, 127, 0.1);
+  color: var(--ctp-peach);
+}
+
+.advanced-chip {
+  border-color: rgba(198, 160, 246, 0.4);
+  background: rgba(198, 160, 246, 0.1);
+  color: var(--ctp-mauve);
+}
+
+.field-control {
+  display: flex;
+  justify-content: flex-end;
+  align-items: flex-start;
+  gap: 8px;
+  min-width: 0;
+}
+
+.switch-control {
+  position: relative;
+  display: inline-flex;
+  width: 46px;
+  height: 26px;
+  flex-shrink: 0;
+}
+
+.switch-control input {
+  position: absolute;
+  opacity: 0;
+  inset: 0;
+  cursor: pointer;
+}
+
+.switch-track {
+  width: 100%;
+  height: 100%;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: rgba(24, 25, 38, 0.85);
+  cursor: pointer;
+  transition:
+    background 140ms ease,
+    border-color 140ms ease;
+}
+
+.switch-track::after {
+  content: '';
+  position: absolute;
+  top: 3px;
+  left: 4px;
+  width: 18px;
+  height: 18px;
+  border-radius: 50%;
+  background: var(--ctp-overlay1);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.35);
+  transition:
+    transform 160ms cubic-bezier(0.4, 0, 0.2, 1),
+    background 140ms ease;
+}
+
+.switch-control input:checked + .switch-track {
+  border-color: rgba(138, 173, 244, 0.6);
+  background: rgba(138, 173, 244, 0.3);
+}
+
+.switch-control input:checked + .switch-track::after {
+  transform: translateX(20px);
+  background: var(--ctp-lavender);
+}
+
+.switch-control input:focus-visible + .switch-track {
+  box-shadow: 0 0 0 3px rgba(138, 173, 244, 0.22);
+}
+
+.empty-state {
+  padding: 40px;
+  border: 1px dashed var(--line);
+  border-radius: 10px;
+  color: var(--ctp-overlay1);
+  text-align: center;
+  font-size: 13px;
+}
+
+@media (max-width: 780px) {
+  .settings-shell {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-nav {
+    max-height: 200px;
+    border-right: 0;
+    border-bottom: 1px solid var(--line);
+  }
+
+  .category-nav {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .settings-toolbar,
+  .field-row,
+  .field-control {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .toolbar-actions {
+    width: 100%;
+    flex-wrap: wrap;
+  }
+
+  .search-input {
+    width: 100%;
+  }
+}

src/shared/ipc/contracts.ts

@@ -97,6 +97,10 @@ export const IPC_CHANNELS = {
     statsGetMediaSessions: 'stats:get-media-sessions',
     statsGetMediaDailyRollups: 'stats:get-media-daily-rollups',
     statsGetMediaCover: 'stats:get-media-cover',
+    getConfigSettingsSnapshot: 'config:get-settings-snapshot',
+    saveConfigSettingsPatch: 'config:save-settings-patch',
+    openConfigSettingsFile: 'config:open-settings-file',
+    openConfigSettingsWindow: 'config:open-settings-window',
   },
   event: {
     subtitleSet: 'subtitle:set',

src/types.ts

@@ -4,4 +4,5 @@ export * from './types/integrations';
 export * from './types/runtime';
 export * from './types/runtime-options';
 export * from './types/session-bindings';
+export * from './types/settings';
 export * from './types/subtitle';

src/types/settings.ts

@@ -0,0 +1,80 @@
+import type { ConfigValidationWarning } from './config';
+
+export type ConfigSettingsCategory =
+  | 'viewing'
+  | 'mining-anki'
+  | 'playback-sources'
+  | 'input'
+  | 'integrations'
+  | 'tracking-app'
+  | 'advanced';
+
+export type ConfigSettingsControl =
+  | 'boolean'
+  | 'number'
+  | 'text'
+  | 'textarea'
+  | 'select'
+  | 'color'
+  | 'string-list'
+  | 'json'
+  | 'secret';
+
+export type ConfigSettingsRestartBehavior = 'hot-reload' | 'restart';
+
+export interface ConfigSettingsField {
+  id: string;
+  label: string;
+  description: string;
+  configPath: string;
+  category: ConfigSettingsCategory;
+  section: string;
+  control: ConfigSettingsControl;
+  defaultValue: unknown;
+  enumValues?: readonly string[];
+  restartBehavior: ConfigSettingsRestartBehavior;
+  advanced?: boolean;
+  secret?: boolean;
+  legacyHidden?: boolean;
+}
+
+export type ConfigSettingsSnapshotValue = unknown;
+
+export interface ConfigSettingsSnapshot {
+  configPath: string;
+  fields: ConfigSettingsField[];
+  values: Record<string, ConfigSettingsSnapshotValue>;
+  warnings: ConfigValidationWarning[];
+}
+
+export type ConfigSettingsPatchOperation =
+  | {
+      op: 'set';
+      path: string;
+      value: unknown;
+    }
+  | {
+      op: 'reset';
+      path: string;
+    };
+
+export interface ConfigSettingsPatch {
+  operations: ConfigSettingsPatchOperation[];
+}
+
+export interface ConfigSettingsSaveResult {
+  ok: boolean;
+  snapshot?: ConfigSettingsSnapshot;
+  warnings?: ConfigValidationWarning[];
+  error?: string;
+  hotReloadFields: string[];
+  restartRequiredFields: string[];
+  restartRequiredSections?: string[];
+}
+
+export interface ConfigSettingsAPI {
+  getSnapshot(): Promise<ConfigSettingsSnapshot>;
+  savePatch(patch: ConfigSettingsPatch): Promise<ConfigSettingsSaveResult>;
+  openSettingsFile(): Promise<boolean>;
+  openSettingsWindow(): Promise<boolean>;
+}

update-service.js

@@ -0,0 +1,172 @@
+'use strict';
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.createUpdateService = createUpdateService;
+exports.createFileUpdateStateStore = createFileUpdateStateStore;
+const node_fs_1 = __importDefault(require('node:fs'));
+const node_path_1 = __importDefault(require('node:path'));
+const release_assets_1 = require('./release-assets');
+function getBestLatestVersion(currentVersion, appUpdate, release) {
+  const releaseVersion = (0, release_assets_1.parseReleaseVersion)(release);
+  const candidates = [appUpdate.version, releaseVersion].filter(
+    (value) => typeof value === 'string' && value.length > 0,
+  );
+  const latest = candidates.reduce(
+    (best, candidate) =>
+      (0, release_assets_1.compareSemverLike)(candidate, best) > 0 ? candidate : best,
+    currentVersion,
+  );
+  return {
+    available:
+      appUpdate.available || (0, release_assets_1.compareSemverLike)(latest, currentVersion) > 0,
+    version: latest,
+  };
+}
+function shouldSkipAutomaticCheck(config, state, now) {
+  if (!config.enabled) return true;
+  if (!state.lastAutomaticCheckAt) return false;
+  const intervalMs = Math.max(1, config.checkIntervalHours) * 60 * 60 * 1000;
+  return now - state.lastAutomaticCheckAt < intervalMs;
+}
+function summarizeError(error) {
+  const raw = error instanceof Error ? error.message : String(error);
+  const firstLine = raw
+    .split('\n')
+    .map((line) => line.trim())
+    .find((line) => line.length > 0);
+  return firstLine ?? 'unknown error';
+}
+function createUpdateService(deps) {
+  const inFlightBySource = new Map();
+  async function runCheck(request) {
+    const now = deps.now();
+    const config = deps.getConfig();
+    const channel = config.channel;
+    const state = await deps.readState();
+    const isAutomatic = request.source === 'automatic';
+    if (isAutomatic && !request.force && shouldSkipAutomaticCheck(config, state, now)) {
+      return { status: 'skipped' };
+    }
+    try {
+      const appUpdate = await deps.checkAppUpdate(channel).catch((error) => {
+        if (isAutomatic) {
+          deps.log(`App update metadata check failed: ${summarizeError(error)}`);
+        }
+        return {
+          available: false,
+          version: deps.getCurrentVersion(),
+        };
+      });
+      const shouldFetchReleaseMetadata =
+        deps.shouldFetchReleaseMetadata?.({ request, channel, appUpdate }) ?? true;
+      const release = shouldFetchReleaseMetadata
+        ? await deps.fetchLatestStableRelease(channel).catch((error) => {
+            deps.log(`GitHub release update check failed: ${summarizeError(error)}`);
+            return null;
+          })
+        : null;
+      const currentVersion = deps.getCurrentVersion();
+      const latest = getBestLatestVersion(currentVersion, appUpdate, release);
+      if (isAutomatic) {
+        const nextState = {
+          ...state,
+          lastAutomaticCheckAt: now,
+        };
+        if (latest.available && state.lastNotifiedVersion !== latest.version) {
+          await deps.notifyUpdateAvailable(latest.version);
+          nextState.lastNotifiedVersion = latest.version;
+        }
+        await deps.writeState(nextState);
+      }
+      if (!latest.available) {
+        if (!isAutomatic) {
+          await deps.showNoUpdateDialog(currentVersion);
+        }
+        return { status: 'up-to-date', version: currentVersion };
+      }
+      if (isAutomatic) {
+        return { status: 'update-available', version: latest.version };
+      }
+      const choice = await deps.showUpdateAvailableDialog(latest.version);
+      if (choice === 'close') {
+        return { status: 'update-available', version: latest.version };
+      }
+      const canInstallAppUpdate = appUpdate.available && appUpdate.canUpdate !== false;
+      let appUpdateApplied = false;
+      if (canInstallAppUpdate) {
+        await deps.downloadAppUpdate();
+        appUpdateApplied = true;
+      }
+      const launcherResult = await deps.updateLauncher(request.launcherPath, channel, release);
+      if (launcherResult.status === 'protected' && launcherResult.command) {
+        deps.log(`Launcher update requires manual command: ${launcherResult.command}`);
+      }
+      if (!appUpdateApplied) {
+        await deps.showManualUpdateRequiredDialog(latest.version);
+        return { status: 'update-available', version: latest.version };
+      }
+      const restartChoice = await deps.showRestartDialog();
+      if (restartChoice === 'restart') {
+        await deps.quitAndInstall();
+      }
+      return { status: 'updated', version: latest.version };
+    } catch (error) {
+      const message = summarizeError(error);
+      if (isAutomatic) {
+        deps.log(`Automatic update check failed: ${message}`);
+      } else {
+        await deps.showUpdateFailedDialog(message);
+      }
+      return { status: 'failed', error: message };
+    }
+  }
+  return {
+    checkForUpdates(request) {
+      const inFlight = inFlightBySource.get(request.source);
+      if (inFlight) return inFlight;
+      const nextInFlight = runCheck(request).finally(() => {
+        inFlightBySource.delete(request.source);
+      });
+      inFlightBySource.set(request.source, nextInFlight);
+      return nextInFlight;
+    },
+    startAutomaticChecks(options = {}) {
+      const setTimeoutFn = deps.setTimeout ?? setTimeout;
+      const setIntervalFn = deps.setInterval ?? setInterval;
+      const startupDelayMs = options.startupDelayMs ?? 15_000;
+      const pollIntervalMs = options.pollIntervalMs ?? 60 * 60 * 1000;
+      setTimeoutFn(() => {
+        void this.checkForUpdates({ source: 'automatic' });
+      }, startupDelayMs);
+      setIntervalFn(() => {
+        void this.checkForUpdates({ source: 'automatic' });
+      }, pollIntervalMs);
+    },
+  };
+}
+function createFileUpdateStateStore(statePath) {
+  return {
+    async readState() {
+      try {
+        return JSON.parse(await node_fs_1.default.promises.readFile(statePath, 'utf8'));
+      } catch {
+        return {};
+      }
+    },
+    async writeState(state) {
+      await node_fs_1.default.promises.mkdir(node_path_1.default.dirname(statePath), {
+        recursive: true,
+      });
+      await node_fs_1.default.promises.writeFile(
+        statePath,
+        `${JSON.stringify(state, null, 2)}\n`,
+        'utf8',
+      );
+    },
+  };
+}
+//# sourceMappingURL=update-service.js.map