diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 3bb6dbe..9566f0f 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -53,6 +53,15 @@ jobs:
     permissions:
       checks: write
 
+  rustfmt_check:
+    name: Formatting for Rust backend
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - run: rustup update stable && rustup default stable && rustup component add rustfmt
+      # Source-only formatting check (no compile / no frontend build needed). Run `cargo fmt` to fix.
+      - run: cargo fmt --all --check
+
   client_test:
     name: Tests and linting for React client
     runs-on: ubuntu-latest
diff --git a/AGENTS.md b/AGENTS.md
index b8e9d38..3694a6d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -201,7 +201,9 @@ the working-directory-aware tools.
 | Build | `cargo build` |
 | Test | `cargo test` |
 | Lint | `cargo clippy` |
+| Format (check / fix) | `cargo fmt --check` / `cargo fmt` (default rustfmt) |
 | Run full app (dev) | `cargo tauri dev` |
+| Run a 2nd dev instance alongside the installed release | `cargo run -- --multi` (or `WIDGETSACK_MULTI=1`) — skips the single-instance lock + isolates config to `<app config>/multi` |
 | Release build → `target/release/widgetsack.exe` | `cargo tauri build` |
 
 > ⚠️ **Build order gotcha:** Tauri embeds `client/build` (`frontendDist`), so the frontend
diff --git a/Cargo.lock b/Cargo.lock
index c101ad9..1f0cdba 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5130,7 +5130,7 @@ dependencies = [
 
 [[package]]
 name = "widgetsack"
-version = "0.0.47"
+version = "0.0.48"
 dependencies = [
  "fontdb",
  "futures-util",
diff --git a/client/.eslintrc.cjs b/client/.eslintrc.cjs
index 6a6f96d..a5cd659 100644
--- a/client/.eslintrc.cjs
+++ b/client/.eslintrc.cjs
@@ -22,5 +22,13 @@ module.exports = {
 	},
 	settings: {
 		react: { version: 'detect' }
-	}
+	},
+	overrides: [
+		{
+			// Test code may use non-null assertions on values it has just constructed / knows are defined
+			// (e.g. asserting on a Patch's `monitor`). Production code keeps the strict rule.
+			files: ['**/*.test.ts', '**/*.test.tsx'],
+			rules: { '@typescript-eslint/no-non-null-assertion': 'off' }
+		}
+	]
 };
diff --git a/client/.gitignore b/client/.gitignore
index 2293605..f6f40f0 100644
--- a/client/.gitignore
+++ b/client/.gitignore
@@ -18,3 +18,4 @@ build/*
 /blob-report
 /.playwright-mcp
 /playwright/.cache
+coverage/
diff --git a/client/.prettierignore b/client/.prettierignore
index d99d3de..3a4b0c6 100644
--- a/client/.prettierignore
+++ b/client/.prettierignore
@@ -20,3 +20,4 @@ build
 /blob-report
 /.playwright-mcp
 /playwright/.cache
+coverage/
diff --git a/client/e2e/helpers.ts b/client/e2e/helpers.ts
index 3392a2e..65d993e 100644
--- a/client/e2e/helpers.ts
+++ b/client/e2e/helpers.ts
@@ -49,12 +49,24 @@ export async function previewTemplate(page: Page, name: string): Promise<void> {
 	await page.getByRole('button', { name, exact: true }).click();
 }
 
-/** Add a widget from the Inspector palette (Layouts section) and return the now-selected host. */
+/**
+ * Add a widget from the Inspector palette (Layouts section) and return the now-selected host.
+ * `type` is the palette LABEL (e.g. "Gauge", "Analog Clock"). The palette button's accessible name
+ * is "<label> — <description>" (the description was folded into the aria-label), so we anchor on the
+ * label: the accessible name is exactly the label, or the label followed by the " — " separator. The
+ * anchor avoids the substring collisions a bare name match would hit (e.g. "Bar" ⊂ Gauge's
+ * "…linear bar…", "Text" ⊂ Transcribe's "…speech-to-text…").
+ */
 export async function addWidget(page: Page, type: string): Promise<Locator> {
 	await openSection(page, 'layouts');
+	// The Add palette lives in a <details> that auto-collapses once a node is selected, so re-open it
+	// (a no-op on a fresh boot where nothing is selected) before reaching for a palette button.
+	const summary = page.locator('.inspector .add-panel > summary');
+	if (!(await page.locator('.inspector .add-panel[open]').count())) await summary.click();
+	const label = type.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); // escape regex metachars in the label
 	await page
 		.locator('.inspector .palette')
-		.getByRole('button', { name: type, exact: true })
+		.getByRole('button', { name: new RegExp(`^${label}( — |$)`) })
 		.click();
 	const selected = page.locator('.widget.selected');
 	await expect(selected).toBeVisible();
diff --git a/client/package-lock.json b/client/package-lock.json
index 763c13b..02ea9fb 100644
--- a/client/package-lock.json
+++ b/client/package-lock.json
@@ -7,6 +7,7 @@
 		"": {
 			"name": "client",
 			"version": "0.0.1",
+			"license": "MIT OR Apache-2.0",
 			"dependencies": {
 				"@codemirror/autocomplete": "^6.20.3",
 				"@codemirror/commands": "^6.10.3",
@@ -35,6 +36,7 @@
 				"@typescript-eslint/eslint-plugin": "^5.62.0",
 				"@typescript-eslint/parser": "^5.62.0",
 				"@vitejs/plugin-react": "^4.3.4",
+				"@vitest/coverage-v8": "^2.1.9",
 				"eslint": "^8.57.1",
 				"eslint-config-prettier": "^8.10.0",
 				"eslint-plugin-react": "^7.37.2",
@@ -53,6 +55,19 @@
 			"integrity": "sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q==",
 			"dev": true
 		},
+		"node_modules/@ampproject/remapping": {
+			"version": "2.3.0",
+			"resolved": "https://registry.npmjs.org/@ampproject/remapping/-/remapping-2.3.0.tgz",
+			"integrity": "sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==",
+			"dev": true,
+			"dependencies": {
+				"@jridgewell/gen-mapping": "^0.3.5",
+				"@jridgewell/trace-mapping": "^0.3.24"
+			},
+			"engines": {
+				"node": ">=6.0.0"
+			}
+		},
 		"node_modules/@babel/code-frame": {
 			"version": "7.29.7",
 			"resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.7.tgz",
@@ -357,6 +372,12 @@
 				"node": ">=6.9.0"
 			}
 		},
+		"node_modules/@bcoe/v8-coverage": {
+			"version": "0.2.3",
+			"resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-0.2.3.tgz",
+			"integrity": "sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==",
+			"dev": true
+		},
 		"node_modules/@codemirror/autocomplete": {
 			"version": "6.20.3",
 			"resolved": "https://registry.npmjs.org/@codemirror/autocomplete/-/autocomplete-6.20.3.tgz",
@@ -892,6 +913,59 @@
 			"deprecated": "Use @eslint/object-schema instead",
 			"dev": true
 		},
+		"node_modules/@isaacs/cliui": {
+			"version": "8.0.2",
+			"resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz",
+			"integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==",
+			"dev": true,
+			"dependencies": {
+				"string-width": "^5.1.2",
+				"string-width-cjs": "npm:string-width@^4.2.0",
+				"strip-ansi": "^7.0.1",
+				"strip-ansi-cjs": "npm:strip-ansi@^6.0.1",
+				"wrap-ansi": "^8.1.0",
+				"wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0"
+			},
+			"engines": {
+				"node": ">=12"
+			}
+		},
+		"node_modules/@isaacs/cliui/node_modules/ansi-regex": {
+			"version": "6.2.2",
+			"resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
+			"integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
+			"dev": true,
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-regex?sponsor=1"
+			}
+		},
+		"node_modules/@isaacs/cliui/node_modules/strip-ansi": {
+			"version": "7.2.0",
+			"resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+			"integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+			"dev": true,
+			"dependencies": {
+				"ansi-regex": "^6.2.2"
+			},
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/strip-ansi?sponsor=1"
+			}
+		},
+		"node_modules/@istanbuljs/schema": {
+			"version": "0.1.6",
+			"resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.6.tgz",
+			"integrity": "sha512-+Sg6GCR/wy1oSmQDFq4LQDAhm3ETKnorxN+y5nbLULOR3P0c14f2Wurzj3/xqPXtasLFfHd5iRFQ7AJt4KH2cw==",
+			"dev": true,
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/@jitl/quickjs-ffi-types": {
 			"version": "0.32.0",
 			"resolved": "https://registry.npmjs.org/@jitl/quickjs-ffi-types/-/quickjs-ffi-types-0.32.0.tgz",
@@ -1021,6 +1095,16 @@
 				"node": ">= 8"
 			}
 		},
+		"node_modules/@pkgjs/parseargs": {
+			"version": "0.11.0",
+			"resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz",
+			"integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==",
+			"dev": true,
+			"optional": true,
+			"engines": {
+				"node": ">=14"
+			}
+		},
 		"node_modules/@playwright/test": {
 			"version": "1.60.0",
 			"resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.60.0.tgz",
@@ -1765,6 +1849,38 @@
 				"vite": "^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
 			}
 		},
+		"node_modules/@vitest/coverage-v8": {
+			"version": "2.1.9",
+			"resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-2.1.9.tgz",
+			"integrity": "sha512-Z2cOr0ksM00MpEfyVE8KXIYPEcBFxdbLSs56L8PO0QQMxt/6bDj45uQfxoc96v05KW3clk7vvgP0qfDit9DmfQ==",
+			"dev": true,
+			"dependencies": {
+				"@ampproject/remapping": "^2.3.0",
+				"@bcoe/v8-coverage": "^0.2.3",
+				"debug": "^4.3.7",
+				"istanbul-lib-coverage": "^3.2.2",
+				"istanbul-lib-report": "^3.0.1",
+				"istanbul-lib-source-maps": "^5.0.6",
+				"istanbul-reports": "^3.1.7",
+				"magic-string": "^0.30.12",
+				"magicast": "^0.3.5",
+				"std-env": "^3.8.0",
+				"test-exclude": "^7.0.1",
+				"tinyrainbow": "^1.2.0"
+			},
+			"funding": {
+				"url": "https://opencollective.com/vitest"
+			},
+			"peerDependencies": {
+				"@vitest/browser": "2.1.9",
+				"vitest": "2.1.9"
+			},
+			"peerDependenciesMeta": {
+				"@vitest/browser": {
+					"optional": true
+				}
+			}
+		},
 		"node_modules/@vitest/expect": {
 			"version": "2.1.9",
 			"resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-2.1.9.tgz",
@@ -2369,9 +2485,9 @@
 			"integrity": "sha512-VQ2MBenTq1fWZUH9DJNGti7kKv6EeAuYr3cLwxUWhIu1baTaXh4Ib5W2CqHVqib4/MqbYGJqiL3Zb8GJZr3l4g=="
 		},
 		"node_modules/cross-spawn": {
-			"version": "7.0.3",
-			"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
-			"integrity": "sha512-iRDPJKUPVEND7dHPO8rkbOnPpyDygcDFtWjpeWNCgy8WP2rXcxXL8TskReQl6OrB2G7+UJrags1q15Fudc7G6w==",
+			"version": "7.0.6",
+			"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+			"integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
 			"dev": true,
 			"dependencies": {
 				"path-key": "^3.1.0",
@@ -2584,12 +2700,24 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/eastasianwidth": {
+			"version": "0.2.0",
+			"resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz",
+			"integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==",
+			"dev": true
+		},
 		"node_modules/electron-to-chromium": {
 			"version": "1.5.366",
 			"resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.366.tgz",
 			"integrity": "sha512-OlRuhb688YTCzzU3gXPLn6nGyd+F+53INE1qaKKlu6kETErE8FYsyDh0XqXEU+uBRn0MpCzz2vfNwORhkap8qg==",
 			"dev": true
 		},
+		"node_modules/emoji-regex": {
+			"version": "9.2.2",
+			"resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
+			"integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
+			"dev": true
+		},
 		"node_modules/entities": {
 			"version": "4.5.0",
 			"resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
@@ -3239,6 +3367,22 @@
 				"url": "https://github.com/sponsors/ljharb"
 			}
 		},
+		"node_modules/foreground-child": {
+			"version": "3.3.1",
+			"resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz",
+			"integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==",
+			"dev": true,
+			"dependencies": {
+				"cross-spawn": "^7.0.6",
+				"signal-exit": "^4.0.1"
+			},
+			"engines": {
+				"node": ">=14"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
 		"node_modules/fs.realpath": {
 			"version": "1.0.0",
 			"resolved": "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz",
@@ -3571,6 +3715,12 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/html-escaper": {
+			"version": "2.0.2",
+			"resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
+			"integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==",
+			"dev": true
+		},
 		"node_modules/ignore": {
 			"version": "5.2.4",
 			"resolved": "https://registry.npmjs.org/ignore/-/ignore-5.2.4.tgz",
@@ -3795,6 +3945,15 @@
 				"url": "https://github.com/sponsors/ljharb"
 			}
 		},
+		"node_modules/is-fullwidth-code-point": {
+			"version": "3.0.0",
+			"resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+			"integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+			"dev": true,
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/is-generator-function": {
 			"version": "1.1.2",
 			"resolved": "https://registry.npmjs.org/is-generator-function/-/is-generator-function-1.1.2.tgz",
@@ -4032,6 +4191,56 @@
 			"integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
 			"dev": true
 		},
+		"node_modules/istanbul-lib-coverage": {
+			"version": "3.2.2",
+			"resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
+			"integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
+			"dev": true,
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/istanbul-lib-report": {
+			"version": "3.0.1",
+			"resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
+			"integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
+			"dev": true,
+			"dependencies": {
+				"istanbul-lib-coverage": "^3.0.0",
+				"make-dir": "^4.0.0",
+				"supports-color": "^7.1.0"
+			},
+			"engines": {
+				"node": ">=10"
+			}
+		},
+		"node_modules/istanbul-lib-source-maps": {
+			"version": "5.0.6",
+			"resolved": "https://registry.npmjs.org/istanbul-lib-source-maps/-/istanbul-lib-source-maps-5.0.6.tgz",
+			"integrity": "sha512-yg2d+Em4KizZC5niWhQaIomgf5WlL4vOOjZ5xGCmF8SnPE/mDWWXgvRExdcpCgh9lLRRa1/fSYp2ymmbJ1pI+A==",
+			"dev": true,
+			"dependencies": {
+				"@jridgewell/trace-mapping": "^0.3.23",
+				"debug": "^4.1.1",
+				"istanbul-lib-coverage": "^3.0.0"
+			},
+			"engines": {
+				"node": ">=10"
+			}
+		},
+		"node_modules/istanbul-reports": {
+			"version": "3.2.0",
+			"resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
+			"integrity": "sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==",
+			"dev": true,
+			"dependencies": {
+				"html-escaper": "^2.0.0",
+				"istanbul-lib-report": "^3.0.0"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/iterator.prototype": {
 			"version": "1.1.5",
 			"resolved": "https://registry.npmjs.org/iterator.prototype/-/iterator.prototype-1.1.5.tgz",
@@ -4049,6 +4258,21 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/jackspeak": {
+			"version": "3.4.3",
+			"resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz",
+			"integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==",
+			"dev": true,
+			"dependencies": {
+				"@isaacs/cliui": "^8.0.2"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			},
+			"optionalDependencies": {
+				"@pkgjs/parseargs": "^0.11.0"
+			}
+		},
 		"node_modules/js-tokens": {
 			"version": "4.0.0",
 			"resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -4179,16 +4403,10 @@
 			"dev": true
 		},
 		"node_modules/lru-cache": {
-			"version": "6.0.0",
-			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz",
-			"integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==",
-			"dev": true,
-			"dependencies": {
-				"yallist": "^4.0.0"
-			},
-			"engines": {
-				"node": ">=10"
-			}
+			"version": "10.4.3",
+			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+			"integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
+			"dev": true
 		},
 		"node_modules/lz-string": {
 			"version": "1.5.0",
@@ -4208,6 +4426,32 @@
 				"@jridgewell/sourcemap-codec": "^1.5.5"
 			}
 		},
+		"node_modules/magicast": {
+			"version": "0.3.5",
+			"resolved": "https://registry.npmjs.org/magicast/-/magicast-0.3.5.tgz",
+			"integrity": "sha512-L0WhttDl+2BOsybvEOLK7fW3UA0OQ0IQ2d6Zl2x/a6vVRs3bAY0ECOSHHeL5jD+SbOpOCUEi0y1DgHEn9Qn1AQ==",
+			"dev": true,
+			"dependencies": {
+				"@babel/parser": "^7.25.4",
+				"@babel/types": "^7.25.4",
+				"source-map-js": "^1.2.0"
+			}
+		},
+		"node_modules/make-dir": {
+			"version": "4.0.0",
+			"resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
+			"integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
+			"dev": true,
+			"dependencies": {
+				"semver": "^7.5.3"
+			},
+			"engines": {
+				"node": ">=10"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
 		"node_modules/math-intrinsics": {
 			"version": "1.1.0",
 			"resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz",
@@ -4260,6 +4504,15 @@
 				"node": "*"
 			}
 		},
+		"node_modules/minipass": {
+			"version": "7.1.3",
+			"resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
+			"integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
+			"dev": true,
+			"engines": {
+				"node": ">=16 || 14 >=14.17"
+			}
+		},
 		"node_modules/ms": {
 			"version": "2.1.3",
 			"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -4505,6 +4758,12 @@
 				"url": "https://github.com/sponsors/sindresorhus"
 			}
 		},
+		"node_modules/package-json-from-dist": {
+			"version": "1.0.1",
+			"resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
+			"integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==",
+			"dev": true
+		},
 		"node_modules/parent-module": {
 			"version": "1.0.1",
 			"resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -4550,6 +4809,22 @@
 			"integrity": "sha512-LDJzPVEEEPR+y48z93A0Ed0yXb8pAByGWo/k5YYdYgpY2/2EsOsksJrq7lOHxryrVOn1ejG6oAp8ahvOIQD8sw==",
 			"dev": true
 		},
+		"node_modules/path-scurry": {
+			"version": "1.11.1",
+			"resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz",
+			"integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==",
+			"dev": true,
+			"dependencies": {
+				"lru-cache": "^10.2.0",
+				"minipass": "^5.0.0 || ^6.0.2 || ^7.0.0"
+			},
+			"engines": {
+				"node": ">=16 || 14 >=14.18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
 		"node_modules/path-type": {
 			"version": "4.0.0",
 			"resolved": "https://registry.npmjs.org/path-type/-/path-type-4.0.0.tgz",
@@ -4979,13 +5254,10 @@
 			"integrity": "sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q=="
 		},
 		"node_modules/semver": {
-			"version": "7.5.1",
-			"resolved": "https://registry.npmjs.org/semver/-/semver-7.5.1.tgz",
-			"integrity": "sha512-Wvss5ivl8TMRZXXESstBA4uR5iXgEN/VC5/sOcuXdVLzcdkz4HWetIoRfG5gb5X+ij/G9rw9YoGn3QoQ8OCSpw==",
+			"version": "7.8.4",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-7.8.4.tgz",
+			"integrity": "sha512-rUCObTnP32Q08R2uuIrt7r9PlEonuTmtuXYcW6s5kjdlj3xbnwe+21yXptAUYcMAABLkYYTtnmzb3w3EDZfueA==",
 			"dev": true,
-			"dependencies": {
-				"lru-cache": "^6.0.0"
-			},
 			"bin": {
 				"semver": "bin/semver.js"
 			},
@@ -5138,6 +5410,18 @@
 			"integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
 			"dev": true
 		},
+		"node_modules/signal-exit": {
+			"version": "4.1.0",
+			"resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+			"integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+			"dev": true,
+			"engines": {
+				"node": ">=14"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
 		"node_modules/slash": {
 			"version": "3.0.0",
 			"resolved": "https://registry.npmjs.org/slash/-/slash-3.0.0.tgz",
@@ -5181,6 +5465,71 @@
 				"node": ">= 0.4"
 			}
 		},
+		"node_modules/string-width": {
+			"version": "5.1.2",
+			"resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz",
+			"integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==",
+			"dev": true,
+			"dependencies": {
+				"eastasianwidth": "^0.2.0",
+				"emoji-regex": "^9.2.2",
+				"strip-ansi": "^7.0.1"
+			},
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/string-width-cjs": {
+			"name": "string-width",
+			"version": "4.2.3",
+			"resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+			"integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+			"dev": true,
+			"dependencies": {
+				"emoji-regex": "^8.0.0",
+				"is-fullwidth-code-point": "^3.0.0",
+				"strip-ansi": "^6.0.1"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/string-width-cjs/node_modules/emoji-regex": {
+			"version": "8.0.0",
+			"resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+			"integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+			"dev": true
+		},
+		"node_modules/string-width/node_modules/ansi-regex": {
+			"version": "6.2.2",
+			"resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
+			"integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
+			"dev": true,
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-regex?sponsor=1"
+			}
+		},
+		"node_modules/string-width/node_modules/strip-ansi": {
+			"version": "7.2.0",
+			"resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+			"integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+			"dev": true,
+			"dependencies": {
+				"ansi-regex": "^6.2.2"
+			},
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/strip-ansi?sponsor=1"
+			}
+		},
 		"node_modules/string.prototype.matchall": {
 			"version": "4.0.12",
 			"resolved": "https://registry.npmjs.org/string.prototype.matchall/-/string.prototype.matchall-4.0.12.tgz",
@@ -5286,6 +5635,19 @@
 				"node": ">=8"
 			}
 		},
+		"node_modules/strip-ansi-cjs": {
+			"name": "strip-ansi",
+			"version": "6.0.1",
+			"resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+			"integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+			"dev": true,
+			"dependencies": {
+				"ansi-regex": "^5.0.1"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
 		"node_modules/strip-indent": {
 			"version": "3.0.0",
 			"resolved": "https://registry.npmjs.org/strip-indent/-/strip-indent-3.0.0.tgz",
@@ -5339,6 +5701,107 @@
 				"url": "https://github.com/sponsors/ljharb"
 			}
 		},
+		"node_modules/test-exclude": {
+			"version": "7.0.2",
+			"resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-7.0.2.tgz",
+			"integrity": "sha512-u9E6A+ZDYdp7a4WnarkXPZOx8Ilz46+kby6p1yZ8zsGTz9gYa6FIS7lj2oezzNKmtdyyJNNmmXDppga5GB7kSw==",
+			"dev": true,
+			"dependencies": {
+				"@istanbuljs/schema": "^0.1.2",
+				"glob": "^10.4.1",
+				"minimatch": "^10.2.2"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/test-exclude/node_modules/balanced-match": {
+			"version": "4.0.4",
+			"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+			"integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+			"dev": true,
+			"engines": {
+				"node": "18 || 20 || >=22"
+			}
+		},
+		"node_modules/test-exclude/node_modules/brace-expansion": {
+			"version": "5.0.6",
+			"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.6.tgz",
+			"integrity": "sha512-kLpxurY4Z4r9sgMsyG0Z9uzsBlgiU/EFKhj/h91/8yHu0edo7XuixOIH3VcJ8kkxs6/jPzoI6U9Vj3WqbMQ94g==",
+			"dev": true,
+			"dependencies": {
+				"balanced-match": "^4.0.2"
+			},
+			"engines": {
+				"node": "18 || 20 || >=22"
+			}
+		},
+		"node_modules/test-exclude/node_modules/glob": {
+			"version": "10.5.0",
+			"resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+			"integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
+			"deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+			"dev": true,
+			"dependencies": {
+				"foreground-child": "^3.1.0",
+				"jackspeak": "^3.1.2",
+				"minimatch": "^9.0.4",
+				"minipass": "^7.1.2",
+				"package-json-from-dist": "^1.0.0",
+				"path-scurry": "^1.11.1"
+			},
+			"bin": {
+				"glob": "dist/esm/bin.mjs"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
+		"node_modules/test-exclude/node_modules/glob/node_modules/balanced-match": {
+			"version": "1.0.2",
+			"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+			"integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+			"dev": true
+		},
+		"node_modules/test-exclude/node_modules/glob/node_modules/brace-expansion": {
+			"version": "2.1.1",
+			"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.1.1.tgz",
+			"integrity": "sha512-WR1cURNjuvBLMZBMbqM0UoE+WAfdUcEV1ccD8PVBVOI+Z3ND4+SZbN8RsfT2bMuG1qwz5RFvPukSZm5fF2D5eA==",
+			"dev": true,
+			"dependencies": {
+				"balanced-match": "^1.0.0"
+			}
+		},
+		"node_modules/test-exclude/node_modules/glob/node_modules/minimatch": {
+			"version": "9.0.9",
+			"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+			"integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
+			"dev": true,
+			"dependencies": {
+				"brace-expansion": "^2.0.2"
+			},
+			"engines": {
+				"node": ">=16 || 14 >=14.17"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
+		"node_modules/test-exclude/node_modules/minimatch": {
+			"version": "10.2.5",
+			"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.5.tgz",
+			"integrity": "sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==",
+			"dev": true,
+			"dependencies": {
+				"brace-expansion": "^5.0.5"
+			},
+			"engines": {
+				"node": "18 || 20 || >=22"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
 		"node_modules/text-table": {
 			"version": "0.2.0",
 			"resolved": "https://registry.npmjs.org/text-table/-/text-table-0.2.0.tgz",
@@ -5928,18 +6391,106 @@
 				"node": ">=0.10.0"
 			}
 		},
+		"node_modules/wrap-ansi": {
+			"version": "8.1.0",
+			"resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz",
+			"integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==",
+			"dev": true,
+			"dependencies": {
+				"ansi-styles": "^6.1.0",
+				"string-width": "^5.0.1",
+				"strip-ansi": "^7.0.1"
+			},
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+			}
+		},
+		"node_modules/wrap-ansi-cjs": {
+			"name": "wrap-ansi",
+			"version": "7.0.0",
+			"resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+			"integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+			"dev": true,
+			"dependencies": {
+				"ansi-styles": "^4.0.0",
+				"string-width": "^4.1.0",
+				"strip-ansi": "^6.0.0"
+			},
+			"engines": {
+				"node": ">=10"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+			}
+		},
+		"node_modules/wrap-ansi-cjs/node_modules/emoji-regex": {
+			"version": "8.0.0",
+			"resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+			"integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+			"dev": true
+		},
+		"node_modules/wrap-ansi-cjs/node_modules/string-width": {
+			"version": "4.2.3",
+			"resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+			"integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+			"dev": true,
+			"dependencies": {
+				"emoji-regex": "^8.0.0",
+				"is-fullwidth-code-point": "^3.0.0",
+				"strip-ansi": "^6.0.1"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/wrap-ansi/node_modules/ansi-regex": {
+			"version": "6.2.2",
+			"resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.2.2.tgz",
+			"integrity": "sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==",
+			"dev": true,
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-regex?sponsor=1"
+			}
+		},
+		"node_modules/wrap-ansi/node_modules/ansi-styles": {
+			"version": "6.2.3",
+			"resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+			"integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+			"dev": true,
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/ansi-styles?sponsor=1"
+			}
+		},
+		"node_modules/wrap-ansi/node_modules/strip-ansi": {
+			"version": "7.2.0",
+			"resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+			"integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+			"dev": true,
+			"dependencies": {
+				"ansi-regex": "^6.2.2"
+			},
+			"engines": {
+				"node": ">=12"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/strip-ansi?sponsor=1"
+			}
+		},
 		"node_modules/wrappy": {
 			"version": "1.0.2",
 			"resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
 			"integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==",
 			"dev": true
 		},
-		"node_modules/yallist": {
-			"version": "4.0.0",
-			"resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
-			"integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
-			"dev": true
-		},
 		"node_modules/yocto-queue": {
 			"version": "0.1.0",
 			"resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
diff --git a/client/package.json b/client/package.json
index 77d44bf..c66d07b 100644
--- a/client/package.json
+++ b/client/package.json
@@ -8,6 +8,7 @@
 		"preview": "vite preview",
 		"check": "tsc --noEmit",
 		"test:unit": "vitest",
+		"test:coverage": "vitest run --coverage",
 		"test:e2e": "playwright test",
 		"lint": "prettier --check . && eslint . --max-warnings 0",
 		"lint:fix": "prettier --write . && eslint . --max-warnings 0 --fix",
@@ -29,6 +30,7 @@
 		"@typescript-eslint/eslint-plugin": "^5.62.0",
 		"@typescript-eslint/parser": "^5.62.0",
 		"@vitejs/plugin-react": "^4.3.4",
+		"@vitest/coverage-v8": "^2.1.9",
 		"eslint": "^8.57.1",
 		"eslint-config-prettier": "^8.10.0",
 		"eslint-plugin-react": "^7.37.2",
diff --git a/client/src/lib/bridge/contract.ts b/client/src/lib/bridge/contract.ts
index 35ddd46..35137bf 100644
--- a/client/src/lib/bridge/contract.ts
+++ b/client/src/lib/bridge/contract.ts
@@ -22,6 +22,8 @@ export const EVENTS = {
 	toggleEdit: 'toggle_edit',
 	openStudio: 'open_studio',
 	arrangeZones: 'arrange_zones',
+	// re-fit overlays to the current display layout (tray "Re-fit overlays" + auto on display change)
+	refitOverlays: 'refit_overlays',
 	// foreign-window drag watcher (windowmgr.rs)
 	winDragStart: 'win_drag_start',
 	winDragEnd: 'win_drag_end',
@@ -36,6 +38,8 @@ export const EVENTS = {
 export const COMMANDS = {
 	// media / now-playing (command.rs, media.rs)
 	getInitialSessions: 'get_initial_sessions',
+	// dev/extra-instance flag (main.rs) — drives the studio's "dev" badge
+	isDevInstance: 'is_dev_instance',
 	mediaControl: 'media_control',
 	mediaCapabilities: 'media_capabilities',
 	// layout persistence + saved layout profiles (command.rs)
@@ -76,6 +80,9 @@ export const COMMANDS = {
 	currentWorkArea: 'current_work_area',
 	setOverlayWallpaper: 'set_overlay_wallpaper',
 	listDisplayNames: 'list_display_names',
+	// monitor input-source switcher — DDC/CI VCP 0x60 (ddc.rs, the Monitor Switch widget)
+	listMonitorInputs: 'list_monitor_inputs',
+	setMonitorInput: 'set_monitor_input',
 	// devtools / diagnostics / recovery (command.rs, process_diag.rs, log.rs)
 	openDevtools: 'open_devtools',
 	listWindowLabels: 'list_window_labels',
@@ -109,6 +116,8 @@ export const COMMANDS = {
 	listHaEntities: 'list_ha_entities',
 	haRegistrySnapshot: 'ha_registry_snapshot',
 	haCallService: 'ha_call_service',
+	haHistory: 'ha_history',
+	haMediaArt: 'ha_media_art',
 	saveHaConfig: 'save_ha_config',
 	haConfigStatus: 'ha_config_status',
 	haTestConnection: 'ha_test_connection',
diff --git a/client/src/lib/core/condition.test.ts b/client/src/lib/core/condition.test.ts
index df18037..926270d 100644
--- a/client/src/lib/core/condition.test.ts
+++ b/client/src/lib/core/condition.test.ts
@@ -107,6 +107,17 @@ describe('conditionMet — sensor', () => {
 		expect(conditionMet(c, ctx([], s(90)))).toBe(true);
 		expect(conditionMet(c, ctx([], s(50)))).toBe(false);
 	});
+	it('>=, <, <= numeric operators', () => {
+		const ge: Condition = { kind: 'sensor', sensorId: 'cpu.total', op: '>=', value: '80' };
+		expect(conditionMet(ge, ctx([], s(80)))).toBe(true);
+		expect(conditionMet(ge, ctx([], s(79)))).toBe(false);
+		const lt: Condition = { kind: 'sensor', sensorId: 'cpu.total', op: '<', value: '80' };
+		expect(conditionMet(lt, ctx([], s(79)))).toBe(true);
+		expect(conditionMet(lt, ctx([], s(80)))).toBe(false);
+		const le: Condition = { kind: 'sensor', sensorId: 'cpu.total', op: '<=', value: '80' };
+		expect(conditionMet(le, ctx([], s(80)))).toBe(true);
+		expect(conditionMet(le, ctx([], s(81)))).toBe(false);
+	});
 	it('missing sensor → not satisfied', () => {
 		const c: Condition = { kind: 'sensor', sensorId: 'cpu.total', op: '>', value: '80' };
 		expect(conditionMet(c, ctx([], {}))).toBe(false);
diff --git a/client/src/lib/core/controls.test.ts b/client/src/lib/core/controls.test.ts
index 7626307..7cd9c17 100644
--- a/client/src/lib/core/controls.test.ts
+++ b/client/src/lib/core/controls.test.ts
@@ -78,6 +78,22 @@ describe('chordMatches', () => {
 		expect(chordMatches({ code: 'Space' }, chord({ code: 'Space', key: ' ' }))).toBe(true);
 		expect(chordMatches({ code: 'Space' }, chord({ code: 'KeyA', key: 'a' }))).toBe(false);
 	});
+
+	it('fails on each modifier mismatch independently (ctrl / alt / meta)', () => {
+		// trigger requires the modifier UP, chord has it DOWN → bail at that exact check.
+		expect(chordMatches({ key: 'a' }, chord({ key: 'a', ctrl: true }))).toBe(false); // ctrl
+		expect(chordMatches({ key: 'a' }, chord({ key: 'a', alt: true }))).toBe(false); // alt
+		expect(chordMatches({ key: 'a' }, chord({ key: 'a', meta: true }))).toBe(false); // meta
+	});
+
+	it('matches a plain key when no code is set', () => {
+		expect(chordMatches({ key: 'a' }, chord({ key: 'a' }))).toBe(true);
+		expect(chordMatches({ key: 'a' }, chord({ key: 'b' }))).toBe(false);
+	});
+
+	it('returns false for a trigger with neither key nor code', () => {
+		expect(chordMatches({}, chord({ key: 'a' }))).toBe(false);
+	});
 });
 
 describe('matchKeyChord', () => {
@@ -140,6 +156,61 @@ describe('matchPointer', () => {
 			matchPointer({ button: 'left', kind: 'drag', target: 'widget' }, controls, baseCtx)
 		).toBeNull();
 	});
+
+	it('does not match on a different button or kind', () => {
+		const click = ctrl({
+			id: 'click',
+			triggers: [{ type: 'pointer', button: 'left', kind: 'click', target: 'widget' }]
+		});
+		// wrong button
+		expect(
+			matchPointer({ button: 'right', kind: 'click', target: 'widget' }, [click], baseCtx)
+		).toBeNull();
+		// wrong kind (drag vs click)
+		expect(
+			matchPointer({ button: 'left', kind: 'drag', target: 'widget' }, [click], baseCtx)
+		).toBeNull();
+	});
+
+	it('does not match on each pointer modifier mismatch (ctrl / shift / alt / meta)', () => {
+		const plain = ctrl({
+			id: 'plain',
+			triggers: [{ type: 'pointer', button: 'left', kind: 'click', target: 'any' }]
+		});
+		for (const mod of ['ctrl', 'shift', 'alt', 'meta'] as const) {
+			expect(
+				matchPointer(
+					{ button: 'left', kind: 'click', target: 'any', [mod]: true },
+					[plain],
+					baseCtx
+				)
+			).toBeNull();
+		}
+	});
+
+	it('skips a control whose only trigger is not a pointer trigger', () => {
+		const keyOnly = ctrl({ id: 'k', triggers: [{ type: 'key', key: 'a' }] });
+		expect(
+			matchPointer({ button: 'left', kind: 'click', target: 'any' }, [keyOnly], baseCtx)
+		).toBeNull();
+	});
+
+	it('skips a disabled-by-when control before testing its trigger', () => {
+		const gated = ctrl({
+			id: 'gated',
+			when: (c) => c.hasSelection,
+			triggers: [{ type: 'pointer', button: 'left', kind: 'click', target: 'any' }]
+		});
+		expect(
+			matchPointer({ button: 'left', kind: 'click', target: 'any' }, [gated], baseCtx)
+		).toBeNull();
+		expect(
+			matchPointer({ button: 'left', kind: 'click', target: 'any' }, [gated], {
+				...baseCtx,
+				hasSelection: true
+			})?.id
+		).toBe('gated');
+	});
 });
 
 describe('matchWheel', () => {
@@ -148,6 +219,23 @@ describe('matchWheel', () => {
 		expect(matchWheel({ ctrl: false, shift: false, alt: false }, [zoom], baseCtx)?.id).toBe('zoom');
 		expect(matchWheel({ ctrl: true, shift: false, alt: false }, [zoom], baseCtx)).toBeNull();
 	});
+
+	it('skips a control whose only trigger is not a wheel trigger', () => {
+		const keyOnly = ctrl({ id: 'k', triggers: [{ type: 'key', key: 'a' }] });
+		expect(matchWheel({ ctrl: false, shift: false, alt: false }, [keyOnly], baseCtx)).toBeNull();
+	});
+
+	it('respects shift/alt modifier requirements on a wheel trigger', () => {
+		const ctrlZoom = ctrl({ id: 'z', triggers: [{ type: 'wheel', ctrl: true }] });
+		expect(matchWheel({ ctrl: true, shift: false, alt: false }, [ctrlZoom], baseCtx)?.id).toBe('z');
+		expect(matchWheel({ ctrl: true, shift: true, alt: false }, [ctrlZoom], baseCtx)).toBeNull();
+		expect(matchWheel({ ctrl: true, shift: false, alt: true }, [ctrlZoom], baseCtx)).toBeNull();
+	});
+
+	it('skips a disabled-by-when control', () => {
+		const gated = ctrl({ id: 'g', when: (c) => c.dirty, triggers: [{ type: 'wheel' }] });
+		expect(matchWheel({ ctrl: false, shift: false, alt: false }, [gated], baseCtx)).toBeNull();
+	});
 });
 
 describe('mergeOverrides', () => {
@@ -163,6 +251,18 @@ describe('mergeOverrides', () => {
 		expect(merged.map((c) => c.id)).toEqual(['save']); // del dropped, ghost ignored
 		expect((merged[0].triggers[0] as { shift?: boolean }).shift).toBe(true);
 	});
+
+	it('passes a control through unchanged when it has no override', () => {
+		const merged = mergeOverrides([save, del], {});
+		expect(merged).toEqual([save, del]); // both untouched
+		expect(merged[0]).toBe(save); // same reference (no clone)
+	});
+
+	it('keeps the original control when an override has neither triggers nor disabled', () => {
+		const merged = mergeOverrides([save], { save: {} });
+		expect(merged).toHaveLength(1);
+		expect(merged[0]).toBe(save); // the `: c` arm — override present but inert
+	});
 });
 
 describe('parseControlOverrides', () => {
@@ -185,16 +285,56 @@ describe('parseControlOverrides', () => {
 		expect(parseControlOverrides(null)).toEqual({});
 		expect(parseControlOverrides({ nope: true })).toEqual({});
 	});
+
+	it('returns empty when overrides is not an object', () => {
+		expect(parseControlOverrides({ overrides: 'nope' })).toEqual({});
+		expect(parseControlOverrides({ overrides: null })).toEqual({});
+	});
+
+	it('accepts pointer and wheel triggers (every isTrigger arm)', () => {
+		const o = parseControlOverrides({
+			overrides: {
+				pan: { triggers: [{ type: 'pointer', button: 'middle', kind: 'drag', target: 'any' }] },
+				zoom: { triggers: [{ type: 'wheel', ctrl: true }] }
+			}
+		});
+		expect(Object.keys(o).sort()).toEqual(['pan', 'zoom']);
+	});
+
+	it('drops an override whose triggers array contains a non-object or wrong-type element', () => {
+		const o = parseControlOverrides({
+			overrides: {
+				// 42 is truthy but not an object → isTrigger false → every() false → triggers dropped,
+				// and with no disabled the whole override is dropped.
+				a: { triggers: [{ type: 'key', key: 's' }, 42] },
+				// an object with a bad `type` → isTrigger false
+				b: { triggers: [{ type: 'nope' }] },
+				// null element → the `!t` arm of isTrigger
+				c: { triggers: [null] }
+			}
+		});
+		expect(o).toEqual({});
+	});
+
+	it('skips an override value that is not an object', () => {
+		expect(parseControlOverrides({ overrides: { a: 5, b: 'x' } })).toEqual({});
+	});
 });
 
 describe('formatTrigger', () => {
 	const cases: [Trigger, string][] = [
 		[{ type: 'key', key: 's', ctrl: true }, 'Ctrl+S'],
 		[{ type: 'key', key: 'z', ctrl: true, shift: true }, 'Ctrl+Shift+Z'],
+		[{ type: 'key', key: 'f', alt: true }, 'Alt+F'],
+		[{ type: 'key', key: 'k', meta: true }, 'Cmd+K'],
 		[{ type: 'key', key: 'escape' }, 'Esc'],
 		[{ type: 'key', key: 'delete' }, 'Del'],
 		[{ type: 'key', code: 'Space' }, 'Space'],
 		[{ type: 'key', key: 'arrowleft' }, '←'],
+		// a multi-char key with no map entry → title-cased (the k.length !== 1 arm of keyLabel)
+		[{ type: 'key', key: 'home' }, 'Home'],
+		// code-only key, code !== 'Space' → key falls back to '' (the `t.key ?? ''` arm)
+		[{ type: 'key', code: 'F13' }, ''],
 		[{ type: 'pointer', button: 'middle', kind: 'drag', target: 'any' }, 'Middle-drag'],
 		[{ type: 'pointer', button: 'right', kind: 'click', target: 'any' }, 'Right-click'],
 		[{ type: 'pointer', button: 'right', kind: 'drag', target: 'widget' }, 'Right-drag'],
@@ -202,13 +342,19 @@ describe('formatTrigger', () => {
 			{ type: 'pointer', button: 'left', kind: 'drag', target: 'canvas', shift: true },
 			'Shift+Drag'
 		],
+		[{ type: 'pointer', button: 'left', kind: 'click', target: 'any', ctrl: true }, 'Ctrl+Click'],
+		[{ type: 'pointer', button: 'left', kind: 'click', target: 'any', alt: true }, 'Alt+Click'],
+		[{ type: 'pointer', button: 'left', kind: 'click', target: 'any', meta: true }, 'Cmd+Click'],
 		[
 			{ type: 'pointer', button: 'left', kind: 'drag', target: 'any', spaceHeld: true },
 			'Space+Drag'
 		],
 		[{ type: 'pointer', button: 'left', kind: 'drag', target: 'widget' }, 'Drag'],
 		[{ type: 'pointer', button: 'left', kind: 'click', target: 'widget' }, 'Click'],
-		[{ type: 'wheel' }, 'Scroll']
+		[{ type: 'wheel' }, 'Scroll'],
+		[{ type: 'wheel', ctrl: true }, 'Ctrl+Scroll'],
+		[{ type: 'wheel', shift: true }, 'Shift+Scroll'],
+		[{ type: 'wheel', alt: true }, 'Alt+Scroll']
 	];
 	it.each(cases)('formats %j as %s', (trigger, expected) => {
 		expect(formatTrigger(trigger)).toBe(expected);
@@ -285,6 +431,51 @@ describe('deriveHints', () => {
 			{ key: 'Release', label: 'done' }
 		]);
 	});
+
+	it('advertises a global-scope control regardless of the active scope', () => {
+		const global = ctrl({
+			id: 'esc',
+			label: 'close',
+			scope: 'global',
+			triggers: [{ type: 'key', key: 'escape' }],
+			hintOrder: 1
+		});
+		const hints = deriveHints([global], { ...baseCtx, scope: 'widget' });
+		expect(hints).toEqual([{ key: 'Esc', label: 'close' }]);
+	});
+
+	it('filters out an advertised control from a different (non-global) scope', () => {
+		const widgetOnly = ctrl({
+			id: 'w',
+			label: 'widget thing',
+			scope: 'widget',
+			triggers: [{ type: 'key', key: 'x' }],
+			hintOrder: 1
+		});
+		expect(deriveHints([widgetOnly], { ...baseCtx, scope: 'studio' })).toEqual([]);
+	});
+
+	it('uses a context-aware hintLabel when provided', () => {
+		const withLabel = ctrl({
+			id: 'undo',
+			label: 'Undo',
+			triggers: [{ type: 'key', key: 'z', ctrl: true }],
+			hintOrder: 1,
+			hintLabel: (c) => (c.canUndo ? 'Undo edit' : 'Nothing to undo')
+		});
+		expect(deriveHints([withLabel], baseCtx)[0].label).toBe('Nothing to undo');
+		expect(deriveHints([withLabel], { ...baseCtx, canUndo: true })[0].label).toBe('Undo edit');
+	});
+
+	it('advertises a control with neither when nor hintWhen (the default-true predicate)', () => {
+		const always = ctrl({
+			id: 'always',
+			label: 'always',
+			triggers: [{ type: 'key', key: 'a' }],
+			hintOrder: 1
+		});
+		expect(deriveHints([always], baseCtx)).toEqual([{ key: 'A', label: 'always' }]);
+	});
 });
 
 describe('detectConflicts', () => {
@@ -308,6 +499,57 @@ describe('detectConflicts', () => {
 		expect(detectConflicts([a, b])).toHaveLength(0);
 		expect(detectConflicts([move, marquee])).toHaveLength(0);
 	});
+
+	it('does not flag two triggers of different types (key vs pointer)', () => {
+		const a = ctrl({ id: 'a', triggers: [{ type: 'key', key: 'x' }] });
+		const b = ctrl({
+			id: 'b',
+			triggers: [{ type: 'pointer', button: 'left', kind: 'click', target: 'any' }]
+		});
+		expect(detectConflicts([a, b])).toHaveLength(0);
+	});
+
+	it('flags two key triggers that collide by code (not key)', () => {
+		const a = ctrl({ id: 'a', triggers: [{ type: 'key', code: 'Space' }] });
+		const b = ctrl({ id: 'b', triggers: [{ type: 'key', code: 'Space' }] });
+		expect(detectConflicts([a, b])).toHaveLength(1);
+		// differing codes do not collide
+		const c = ctrl({ id: 'c', triggers: [{ type: 'key', code: 'KeyA' }] });
+		expect(detectConflicts([a, c])).toHaveLength(0);
+	});
+
+	it('does not flag key triggers that differ only by a modifier', () => {
+		const a = ctrl({ id: 'a', triggers: [{ type: 'key', key: 'z', ctrl: true }] });
+		const b = ctrl({ id: 'b', triggers: [{ type: 'key', key: 'z', ctrl: true, shift: true }] });
+		expect(detectConflicts([a, b])).toHaveLength(0);
+	});
+
+	it('flags two identical pointer triggers and respects each modifier + spaceHeld', () => {
+		const a = ctrl({
+			id: 'a',
+			triggers: [{ type: 'pointer', button: 'left', kind: 'drag', target: 'any' }]
+		});
+		const b = ctrl({
+			id: 'b',
+			triggers: [{ type: 'pointer', button: 'left', kind: 'drag', target: 'canvas' }]
+		});
+		// same button/kind, target 'any' overlaps 'canvas', no mods → collide
+		expect(detectConflicts([a, b])).toHaveLength(1);
+		// a differing modifier (spaceHeld) breaks the collision
+		const c = ctrl({
+			id: 'c',
+			triggers: [{ type: 'pointer', button: 'left', kind: 'drag', target: 'any', spaceHeld: true }]
+		});
+		expect(detectConflicts([a, c])).toHaveLength(0);
+	});
+
+	it('flags two colliding wheel triggers and separates them by a modifier', () => {
+		const a = ctrl({ id: 'a', triggers: [{ type: 'wheel' }] });
+		const b = ctrl({ id: 'b', triggers: [{ type: 'wheel' }] });
+		expect(detectConflicts([a, b])).toHaveLength(1);
+		const c = ctrl({ id: 'c', triggers: [{ type: 'wheel', ctrl: true }] });
+		expect(detectConflicts([a, c])).toHaveLength(0);
+	});
 });
 
 describe('registry', () => {
diff --git a/client/src/lib/core/flowStyle.test.ts b/client/src/lib/core/flowStyle.test.ts
index 8e639bc..be5f936 100644
--- a/client/src/lib/core/flowStyle.test.ts
+++ b/client/src/lib/core/flowStyle.test.ts
@@ -72,6 +72,22 @@ describe('containerStyle', () => {
 		expect(s.gridTemplateRows).toBe('50px 1fr');
 	});
 
+	it('grid without an explicit cols defaults to a single column', () => {
+		// cols unset → `cols ?? 1` → one column; two children → two rows.
+		const s = containerStyle(container('g', 'grid', [leaf(prim('A')), leaf(prim('B'))]));
+		expect(s.display).toBe('grid');
+		expect(s.gridTemplateColumns).toBe('repeat(1, 1fr)');
+		expect(s.gridTemplateRows).toBe('repeat(2, 1fr)');
+	});
+
+	it('grid without cols still derives fixed tracks from a cell (cols ?? 1 path in gridFixedTracks)', () => {
+		// A fixed-height cell with no cols on the parent → single-column grid, row 0 pinned to 40px.
+		const c0 = container('c0', 'col', [], { cellH: 40 });
+		const s = containerStyle(container('g', 'grid', [c0, leaf(prim('B'))]));
+		expect(s.gridTemplateColumns).toBe('repeat(1, 1fr)');
+		expect(s.gridTemplateRows).toBe('40px 1fr');
+	});
+
 	it('overlap → single-cell grid stack', () => {
 		const s = containerStyle(container('o', 'col', [], { overlap: true }));
 		expect(s.display).toBe('grid');
@@ -167,6 +183,14 @@ describe('itemStyle (sizing)', () => {
 	it('a CONTAINER with auto basis shrink-wraps (flex-basis:auto)', () => {
 		expect(itemStyle(container('c', 'col', []), 'row').flexBasis).toBe('auto');
 	});
+
+	it('a GROUP with auto/unset basis takes its STORED group size as the main-axis basis', () => {
+		// The group is a leaf-with-group-unit; on the fall-through (auto) path the basis is the group's
+		// size on the parent's main axis (rect would be wrong — a group has `size`, not `rect`).
+		const g = group('g', { w: 80, h: 120 }, container('c', 'col', []));
+		expect(itemStyle(leaf(g), 'row').flexBasis).toBe('80px'); // row → width
+		expect(itemStyle(leaf(g), 'col').flexBasis).toBe('120px'); // col → height
+	});
 });
 
 describe('itemStyle (per-leaf alignment)', () => {
@@ -185,6 +209,12 @@ describe('itemStyle (per-leaf alignment)', () => {
 		expect(s.marginTop).toBe('auto'); // valign bottom pushes it down the vertical main axis
 	});
 
+	it('col parent: valign middle → centered via dual auto margins on the vertical main axis', () => {
+		const s = itemStyle({ ...leaf(textPrim('A')), valign: 'middle' }, 'col');
+		expect(s.marginTop).toBe('auto');
+		expect(s.marginBottom).toBe('auto');
+	});
+
 	it('row parent: halign center → centered via dual auto margins', () => {
 		const s = itemStyle({ ...leaf(prim('A')), halign: 'center' }, 'row');
 		expect(s.marginLeft).toBe('auto');
diff --git a/client/src/lib/core/geometry.test.ts b/client/src/lib/core/geometry.test.ts
index 4f684e7..0059991 100644
--- a/client/src/lib/core/geometry.test.ts
+++ b/client/src/lib/core/geometry.test.ts
@@ -51,6 +51,13 @@ describe('resizeRect', () => {
 		expect(resizeRect(r, 'w', 100, 0, 1, 16)).toEqual({ x: 44, y: 10, w: 16, h: 40 });
 	});
 
+	it('clamps the minimum HEIGHT too, keeping the opposite edge fixed', () => {
+		// south edge dragged up past the minimum: height pins to min, top unchanged
+		expect(resizeRect(r, 's', 0, -100, 1, 16)).toEqual({ x: 10, y: 10, w: 50, h: 16 });
+		// north edge dragged down past the minimum: top moves so the south edge stays fixed
+		expect(resizeRect(r, 'n', 0, 100, 1, 16)).toEqual({ x: 10, y: 34, w: 50, h: 16 });
+	});
+
 	it('snaps only the moved edge to the grid', () => {
 		expect(resizeRect(r, 'e', 3, 0, 8)).toEqual({ x: 10, y: 10, w: 54, h: 40 });
 	});
diff --git a/client/src/lib/core/haControls.test.ts b/client/src/lib/core/haControls.test.ts
index 2d354ba..c9ce7e7 100644
--- a/client/src/lib/core/haControls.test.ts
+++ b/client/src/lib/core/haControls.test.ts
@@ -1,10 +1,19 @@
 import { describe, expect, it } from 'vitest';
 import {
 	brightnessToPct,
+	climateNextHvacMode,
 	climateNudge,
+	climateSetFanMode,
 	climateSetHvacMode,
 	climateSetTemperature,
 	climateUsesRange,
+	coverSetPosition,
+	entityDomain,
+	fanSetPercentage,
+	inputNumberSetValue,
+	inputSelectOption,
+	inputTextSetValue,
+	mediaVolumeSet,
 	lightBrightnessPct,
 	lightColorTempKelvin,
 	lightRgb,
@@ -72,4 +81,63 @@ describe('haControls — climate', () => {
 			data: { hvac_mode: 'heat' }
 		});
 	});
+
+	it('cycles to the next hvac mode, wrapping', () => {
+		const attrs = { hvac_modes: ['off', 'cool', 'heat'] };
+		expect(climateNextHvacMode(attrs, 'off')).toBe('cool');
+		expect(climateNextHvacMode(attrs, 'heat')).toBe('off');
+		// Unknown current / empty list → unchanged.
+		expect(climateNextHvacMode(attrs, 'dry')).toBe('off');
+		expect(climateNextHvacMode({}, 'cool')).toBe('cool');
+	});
+
+	it('builds set_fan_mode (A/C fan speed)', () => {
+		expect(climateSetFanMode('high')).toEqual({
+			service: 'set_fan_mode',
+			data: { fan_mode: 'high' }
+		});
+	});
+});
+
+describe('haControls — fan / cover / input helpers', () => {
+	it('builds fan.set_percentage clamped + rounded', () => {
+		expect(fanSetPercentage(40)).toEqual({ service: 'set_percentage', data: { percentage: 40 } });
+		expect(fanSetPercentage(140).data.percentage).toBe(100);
+		expect(fanSetPercentage(-5).data.percentage).toBe(0);
+	});
+
+	it('builds cover.set_cover_position clamped + rounded', () => {
+		expect(coverSetPosition(75)).toEqual({
+			service: 'set_cover_position',
+			data: { position: 75 }
+		});
+		expect(coverSetPosition(120).data.position).toBe(100);
+	});
+
+	it('builds input_number.set_value clamped to min/max', () => {
+		const attrs = { min: 5, max: 30 };
+		expect(inputNumberSetValue(20, attrs).data.value).toBe(20);
+		expect(inputNumberSetValue(99, attrs).data.value).toBe(30);
+		expect(inputNumberSetValue(0, attrs).data.value).toBe(5);
+	});
+
+	it('builds input_select.select_option + input_text.set_value', () => {
+		expect(inputSelectOption('Home')).toEqual({
+			service: 'select_option',
+			data: { option: 'Home' }
+		});
+		expect(inputTextSetValue('hi')).toEqual({ service: 'set_value', data: { value: 'hi' } });
+	});
+
+	it('reads the domain from an entity_id', () => {
+		expect(entityDomain('input_number.x')).toBe('input_number');
+		expect(entityDomain('light.kitchen')).toBe('light');
+		expect(entityDomain(undefined)).toBe('');
+	});
+
+	it('builds media_player.volume_set from a 0..100 percentage', () => {
+		expect(mediaVolumeSet(40)).toEqual({ service: 'volume_set', data: { volume_level: 0.4 } });
+		expect(mediaVolumeSet(150).data.volume_level).toBe(1);
+		expect(mediaVolumeSet(-5).data.volume_level).toBe(0);
+	});
 });
diff --git a/client/src/lib/core/haControls.ts b/client/src/lib/core/haControls.ts
index 49f5001..43c35ae 100644
--- a/client/src/lib/core/haControls.ts
+++ b/client/src/lib/core/haControls.ts
@@ -56,6 +56,8 @@ export function lightRgb(r: number, g: number, b: number): ServiceCall {
 
 export type ClimateAttrs = {
 	hvac_modes?: string[];
+	fan_modes?: string[];
+	fan_mode?: string;
 	min_temp?: number;
 	max_temp?: number;
 	target_temp_step?: number;
@@ -88,3 +90,73 @@ export function climateNudge(attrs: ClimateAttrs, dir: 1 | -1): ServiceCall {
 export function climateSetHvacMode(mode: string): ServiceCall {
 	return { service: 'set_hvac_mode', data: { hvac_mode: mode } };
 }
+
+/** The next hvac mode in the entity's supported list, wrapping — for a tap-to-cycle mode button. */
+export function climateNextHvacMode(attrs: ClimateAttrs, current: string): string {
+	const modes = attrs.hvac_modes ?? [];
+	if (modes.length === 0) return current;
+	const i = modes.indexOf(current);
+	return modes[(i + 1) % modes.length];
+}
+
+/** climate.set_fan_mode (e.g. 'auto', 'low', 'high') — A/C fan speed. */
+export function climateSetFanMode(mode: string): ServiceCall {
+	return { service: 'set_fan_mode', data: { fan_mode: mode } };
+}
+
+// ---- generic ----
+
+/** The domain of an entity_id, e.g. 'light.kitchen' → 'light' ('' when unknown). */
+export function entityDomain(entityId?: string): string {
+	return entityId ? entityId.split('.')[0] : '';
+}
+
+// ---- fan ----
+
+export type FanAttrs = {
+	percentage?: number | null;
+	percentage_step?: number;
+	preset_modes?: string[];
+	preset_mode?: string;
+	oscillating?: boolean;
+};
+
+/** fan.set_percentage (0..100, clamped + rounded). */
+export function fanSetPercentage(pct: number): ServiceCall {
+	return { service: 'set_percentage', data: { percentage: Math.round(clamp(pct, 0, 100)) } };
+}
+
+// ---- cover ----
+
+/** cover.set_cover_position (0 = closed … 100 = open, clamped + rounded). */
+export function coverSetPosition(pct: number): ServiceCall {
+	return { service: 'set_cover_position', data: { position: Math.round(clamp(pct, 0, 100)) } };
+}
+
+// ---- input_* helpers ----
+
+export type InputNumberAttrs = { min?: number; max?: number; step?: number };
+
+/** input_number.set_value, clamped to the helper's configured min/max. */
+export function inputNumberSetValue(value: number, attrs: InputNumberAttrs): ServiceCall {
+	const lo = attrs.min ?? 0;
+	const hi = attrs.max ?? 100;
+	return { service: 'set_value', data: { value: round1(clamp(value, lo, hi)) } };
+}
+
+/** input_select.select_option. */
+export function inputSelectOption(option: string): ServiceCall {
+	return { service: 'select_option', data: { option } };
+}
+
+/** input_text.set_value. */
+export function inputTextSetValue(value: string): ServiceCall {
+	return { service: 'set_value', data: { value } };
+}
+
+// ---- media_player ----
+
+/** media_player.volume_set: a 0..100 percentage → HA's 0..1 `volume_level`. */
+export function mediaVolumeSet(pct: number): ServiceCall {
+	return { service: 'volume_set', data: { volume_level: Math.round(clamp(pct, 0, 100)) / 100 } };
+}
diff --git a/client/src/lib/core/layoutEdit.ts b/client/src/lib/core/layoutEdit.ts
index 9a5b15c..20ba927 100644
--- a/client/src/lib/core/layoutEdit.ts
+++ b/client/src/lib/core/layoutEdit.ts
@@ -46,9 +46,10 @@ export function findParent(root: Container, id: string): Container | null {
 }
 
 /**
- * Rebuild the tree, replacing the node whose id matches via `fn` (applied before
- * recursing into the result's children). Returns a new root; a no-op clone if `id` is
- * absent. `fn` is expected to preserve node kind.
+ * Rebuild the tree, replacing the matched node with `fn(node)`. Recursion STOPS at the
+ * match — `fn`'s result is returned as-is and is NOT re-descended into (so a replacement
+ * that re-nests a node with the same id never re-runs `fn`). Returns a new root, or a
+ * no-op clone if `id` is absent. `fn` is expected to preserve node kind.
  */
 export function updateNode(
 	root: Container,
@@ -59,11 +60,15 @@ export function updateNode(
 }
 
 function rebuild(node: LayoutNode, id: string, fn: (n: LayoutNode) => LayoutNode): LayoutNode {
-	const replaced = node.id === id ? fn(node) : node;
-	if (isContainer(replaced)) {
-		return { ...replaced, children: replaced.children.map((c) => rebuild(c, id, fn)) };
+	// Matched node: apply fn and STOP — do NOT re-descend into the result. Re-descending re-ran fn
+	// whenever the replacement re-contained a node with the same id (e.g. wrapLeafWith nests the
+	// target inside a fresh cell), which recursed unboundedly on the merge-drop path. Ids are unique,
+	// so there is never a second node with this id to find below the match.
+	if (node.id === id) return fn(node);
+	if (isContainer(node)) {
+		return { ...node, children: node.children.map((c) => rebuild(c, id, fn)) };
 	}
-	return replaced;
+	return node;
 }
 
 /** Shallow-patch the container with `id` (kind/gap/pad/align/justify/cols/basis/…). */
diff --git a/client/src/lib/core/layoutTree.test.ts b/client/src/lib/core/layoutTree.test.ts
index 80ed06b..f39c8a1 100644
--- a/client/src/lib/core/layoutTree.test.ts
+++ b/client/src/lib/core/layoutTree.test.ts
@@ -9,6 +9,7 @@ import {
 	isGroup,
 	isLeaf,
 	leaf,
+	monitorHasWidgets,
 	resolvePad,
 	ROOT_PAD,
 	type Group
@@ -89,3 +90,23 @@ describe('guards', () => {
 		expect(isGroup(prim('w'))).toBe(false);
 	});
 });
+
+describe('monitorHasWidgets', () => {
+	it('is false for an empty monitor', () => {
+		expect(monitorHasWidgets(emptyMonitorLayout())).toBe(false);
+	});
+
+	it('is true when there is a floating widget', () => {
+		expect(monitorHasWidgets({ ...emptyMonitorLayout(), floating: [leaf(prim('f'))] })).toBe(true);
+	});
+
+	it('is true for a leaf anywhere in the flow tree, false for empty containers', () => {
+		const nested = {
+			...emptyMonitorLayout(),
+			root: container('r', 'col', [container('c', 'row', [])])
+		};
+		expect(monitorHasWidgets(nested)).toBe(false);
+		const withLeaf = { ...emptyMonitorLayout(), root: container('r', 'col', [leaf(prim('w'))]) };
+		expect(monitorHasWidgets(withLeaf)).toBe(true);
+	});
+});
diff --git a/client/src/lib/core/llm.test.ts b/client/src/lib/core/llm.test.ts
index 74f746f..d62c7d1 100644
--- a/client/src/lib/core/llm.test.ts
+++ b/client/src/lib/core/llm.test.ts
@@ -5,6 +5,7 @@ import {
 	applyDelta,
 	buildAssistantMessages,
 	buildBriefingMessages,
+	buildLayoutUserPrompt,
 	buildTranslateMessages,
 	buildLayoutSystemPrompt,
 	describeLayout,
@@ -12,10 +13,14 @@ import {
 	formatReadings,
 	parseAssistantReply,
 	providerMeta,
+	pushUser,
 	startTurn,
+	toMessages,
 	type AssistantOp
 } from './llm';
-import { listMetas } from './widget';
+import { container, group, leaf } from './layoutTree';
+import { createWidget, registerMeta } from './widget';
+import { listMetas, type WidgetMeta } from './widget';
 
 const monitor = (): MonitorLayout => ({ root: emptyRoot(), floating: [] });
 
@@ -68,6 +73,38 @@ describe('chat reducer (applyDelta)', () => {
 		// a done for an id we never opened is also a no-op
 		expect(applyDelta(base, { requestId: 'ghost', token: '', done: true })).toBe(base);
 	});
+
+	it('seeds an unknown-id turn already in the error state when the first frame is an error', () => {
+		// not done, unknown id, but carries an error → seed a non-streaming turn that records it.
+		const s = applyDelta(emptyChat(), {
+			requestId: 'z',
+			token: '',
+			done: false,
+			error: 'rate limited'
+		});
+		expect(s.turns).toHaveLength(1);
+		expect(s.turns[0].error).toBe('rate limited');
+		expect(s.turns[0].streaming).toBe(false);
+	});
+});
+
+describe('pushUser / toMessages', () => {
+	it('appends a user turn', () => {
+		const s = pushUser(emptyChat(), 'u1', 'hello there');
+		expect(s.turns).toEqual([{ id: 'u1', role: 'user', content: 'hello there' }]);
+	});
+
+	it('flattens the transcript to ChatMessages, dropping empty + errored turns', () => {
+		let s = pushUser(emptyChat(), 'u1', 'hi');
+		s = startTurn(s, 'a1'); // empty streaming assistant turn → dropped (content.length 0)
+		s = applyDelta(s, { requestId: 'a1', token: 'hey', done: true });
+		s = startTurn(s, 'a2'); // a second turn we mark errored → dropped
+		s = applyDelta(s, { requestId: 'a2', token: 'partial', done: true, error: 'boom' });
+		expect(toMessages(s)).toEqual([
+			{ role: 'user', content: 'hi' },
+			{ role: 'assistant', content: 'hey' }
+		]);
+	});
 });
 
 describe('parseAssistantReply', () => {
@@ -102,6 +139,32 @@ describe('parseAssistantReply', () => {
 		expect(parseAssistantReply('no json here')).toBeNull();
 		expect(parseAssistantReply('{"summary":"x"}')).toBeNull();
 	});
+
+	it('skips a candidate that parses to a non-object (a bare JSON value)', () => {
+		// `{ "x": 5 }` has no ops, then the whole string parses but is not the ops shape; a leading
+		// candidate that JSON.parses to null/number is skipped via the typeof guard.
+		const r = parseAssistantReply('{"v": null}\n{"ops":[{"op":"clear"}]}');
+		expect(r?.ops).toEqual([{ op: 'clear' }]);
+	});
+
+	it('ignores braces inside string literals (escapes do not miscount depth)', () => {
+		// The summary string contains an escaped quote and a brace; the brace-counter must not be
+		// fooled into ending the object early.
+		const r = parseAssistantReply('{"ops":[{"op":"clear"}],"summary":"a \\" and a } brace"}');
+		expect(r?.ops).toEqual([{ op: 'clear' }]);
+		expect(r?.summary).toBe('a " and a } brace');
+	});
+
+	it('returns null when the only brace opens an unbalanced (never-closed) object', () => {
+		// No balanced candidate yields, and the whole-string fallback fails to parse → null.
+		expect(parseAssistantReply('prefix {"ops":[{"op":"clear"}')).toBeNull();
+	});
+
+	it('skips a whole-string candidate that JSON-parses to a falsy value (null)', () => {
+		// No `{` → jsonObjectCandidates yields nothing; the whole-string fallback parses to `null`,
+		// which the `!parsed` guard rejects → null.
+		expect(parseAssistantReply('null')).toBeNull();
+	});
 });
 
 describe('briefing', () => {
@@ -126,6 +189,11 @@ describe('briefing', () => {
 		expect(m[1].content).toContain('cpu.total=50');
 	});
 
+	it('falls back to a default instruction when the assistant prompt is blank', () => {
+		const m = buildAssistantMessages('   ', { 'cpu.total': 50 });
+		expect(m[1].content).toContain('Summarize my system status in one short sentence.');
+	});
+
 	it('builds translate messages targeting a language', () => {
 		const m = buildTranslateMessages('hello', 'Spanish');
 		expect(m[0].content).toContain('Spanish');
@@ -144,6 +212,77 @@ describe('buildLayoutSystemPrompt', () => {
 		// the op grammar is taught
 		expect(prompt).toContain('addWidget');
 	});
+
+	it('filters out the spacer and exercises the meta-default fallbacks', () => {
+		// A bare meta with no defaultConfig/binds/description/label exercises every `??` fallback:
+		// binds defaults to 'scalar' ("takes a sensor"), no config string, falls back to the type as label.
+		const metas: WidgetMeta[] = [
+			{ type: 'spacer' }, // filtered out
+			{ type: 'bare' }, // no binds → 'scalar' → "takes a sensor"; no cfg; label/desc → type
+			{ type: 'selfsrc', binds: 'none', label: 'Self', description: 'a self-sourcing widget' }
+		];
+		const prompt = buildLayoutSystemPrompt(metas, []);
+		expect(prompt).not.toContain('- spacer:');
+		expect(prompt).toContain('- bare: bare takes a sensor.');
+		expect(prompt).toContain('- selfsrc: a self-sourcing widget self-sourcing (no sensor).');
+		// empty sensor list renders the placeholder
+		expect(prompt).toContain('(none reported yet)');
+	});
+
+	it('uses the label when there is no description', () => {
+		const prompt = buildLayoutSystemPrompt(
+			[{ type: 'x', label: 'Labelled', defaultConfig: { color: 'red' } }],
+			['cpu.total']
+		);
+		// label is used as the description fallback, and config keys are listed
+		expect(prompt).toContain('- x: Labelled takes a sensor. config: color.');
+	});
+});
+
+describe('buildLayoutUserPrompt', () => {
+	it('renders an empty layout placeholder and the instruction', () => {
+		const p = buildLayoutUserPrompt('add a clock', monitor());
+		expect(p).toContain('Current layout:\n(empty)');
+		expect(p).toContain('Request: add a clock');
+	});
+
+	it('lists each placed widget with its container and sensor', () => {
+		const res = applyAssistantOps(
+			monitor(),
+			[{ op: 'addWidget', widgetType: 'gauge', sensor: 'cpu.total' }],
+			counter()
+		);
+		const id = res.addedIds[0];
+		const p = buildLayoutUserPrompt('tweak it', res.monitor);
+		expect(p).toContain(`${id} (gauge, sensor=cpu.total) in`);
+	});
+
+	it('omits the sensor= clause for a self-sourcing (sensorless) widget', () => {
+		const res = applyAssistantOps(monitor(), [{ op: 'addWidget', widgetType: 'clock' }], counter());
+		const id = res.addedIds[0];
+		const p = buildLayoutUserPrompt('go', res.monitor);
+		// clock self-sources → no `sensor=` clause for that line
+		expect(p).toContain(`${id} (clock) in`);
+		expect(p).not.toContain(`${id} (clock, sensor=`);
+	});
+});
+
+describe('describeLayout', () => {
+	it('describes a group leaf as type "group" and walks floating nodes', () => {
+		const clock = leaf(createWidget('clock', 'c1'));
+		const g = leaf(group('g1', { w: 100, h: 100 }, clock));
+		const floatingGauge = leaf(createWidget('gauge', 'f1'));
+		const m: MonitorLayout = {
+			root: container('root', 'col', [g]),
+			floating: [floatingGauge]
+		};
+		const items = describeLayout(m);
+		const grp = items.find((i) => i.id === 'g1');
+		expect(grp?.type).toBe('group');
+		expect(grp?.container).toBe('root');
+		const flt = items.find((i) => i.id === 'f1');
+		expect(flt?.container).toBe('floating');
+	});
 });
 
 describe('applyAssistantOps', () => {
@@ -202,6 +341,27 @@ describe('applyAssistantOps', () => {
 		expect(describeLayout(res.monitor)[0].sensor).toBe('cpu.total');
 	});
 
+	it("defaults a meta with no explicit binds to 'scalar' (sensor is accepted)", () => {
+		// Every built-in meta declares binds; register a synthetic one with binds undefined to drive
+		// the `meta.binds ?? 'scalar'` fallback in addWidget — the sensor must then be accepted.
+		registerMeta({ type: 'no-binds-test', label: 'NoBinds' });
+		let res = applyAssistantOps(
+			monitor(),
+			[{ op: 'addWidget', widgetType: 'no-binds-test', sensor: 'cpu.total' }],
+			counter()
+		);
+		expect(res.applied).toBe(1);
+		expect(res.errors).toHaveLength(0);
+		expect(describeLayout(res.monitor)[0].sensor).toBe('cpu.total');
+
+		// setSensor on the same leaf drives leafBinds' `?? 'scalar'` fallback (meta.binds undefined),
+		// which the SENSOR_BINDS gate then accepts.
+		const id = res.addedIds[0];
+		res = applyAssistantOps(res.monitor, [{ op: 'setSensor', id, sensor: 'gpu.util' }], counter());
+		expect(res.applied).toBe(1);
+		expect(describeLayout(res.monitor)[0].sensor).toBe('gpu.util');
+	});
+
 	it('reports an unknown widget type without aborting the batch', () => {
 		const res = applyAssistantOps(
 			monitor(),
@@ -258,4 +418,69 @@ describe('applyAssistantOps', () => {
 		applyAssistantOps(m, [{ op: 'addWidget', widgetType: 'clock' }], counter());
 		expect(JSON.stringify(m)).toBe(before);
 	});
+
+	it('falls back to the root for an unknown parent container (with an error note)', () => {
+		const res = applyAssistantOps(
+			monitor(),
+			[{ op: 'addWidget', widgetType: 'clock', parent: 'no-such-container' }],
+			counter()
+		);
+		expect(res.applied).toBe(1);
+		expect(res.errors.join(' ')).toMatch(/unknown container "no-such-container"/);
+		// landed on root anyway
+		expect(describeLayout(res.monitor)[0].container).toBe(res.monitor.root.id);
+	});
+
+	it('rejects a parent id that resolves to a widget leaf (not a container) → root', () => {
+		let res = applyAssistantOps(monitor(), [{ op: 'addWidget', widgetType: 'clock' }], counter());
+		const leafId = res.addedIds[0];
+		res = applyAssistantOps(
+			res.monitor,
+			[{ op: 'addWidget', widgetType: 'gauge', parent: leafId }],
+			counter()
+		);
+		expect(res.errors.join(' ')).toMatch(/unknown container/);
+		expect(describeLayout(res.monitor).find((i) => i.type === 'gauge')?.container).toBe(
+			res.monitor.root.id
+		);
+	});
+
+	it('creates a grid container with its grid defaults', () => {
+		const res = applyAssistantOps(monitor(), [{ op: 'addContainer', kind: 'grid' }], counter());
+		expect(res.applied).toBe(1);
+		const node = res.monitor.root.children[0];
+		expect(isContainer(node) && node.kind).toBe('grid');
+		expect(isContainer(node) && node.cols).toBe(2);
+		expect(isContainer(node) && node.rows).toBe(2);
+	});
+
+	it('reports removeWidget on a missing id without aborting', () => {
+		const res = applyAssistantOps(monitor(), [{ op: 'removeWidget', id: 'ghost' }], counter());
+		expect(res.applied).toBe(0);
+		expect(res.errors.join(' ')).toMatch(/cannot remove "ghost" — not found/);
+	});
+
+	it('reports setConfig on a non-widget (a container) without aborting', () => {
+		let res = applyAssistantOps(monitor(), [{ op: 'addContainer', kind: 'row' }], counter());
+		const containerId = res.addedIds[0];
+		res = applyAssistantOps(
+			res.monitor,
+			[{ op: 'setConfig', id: containerId, config: { x: 1 } }],
+			counter()
+		);
+		expect(res.applied).toBe(0);
+		expect(res.errors.join(' ')).toMatch(/cannot configure ".*" — not a widget/);
+	});
+
+	it('reports setSensor on a non-widget (a container) — leafBinds returns null', () => {
+		let res = applyAssistantOps(monitor(), [{ op: 'addContainer', kind: 'row' }], counter());
+		const containerId = res.addedIds[0];
+		res = applyAssistantOps(
+			res.monitor,
+			[{ op: 'setSensor', id: containerId, sensor: 'cpu.total' }],
+			counter()
+		);
+		expect(res.applied).toBe(0);
+		expect(res.errors.join(' ')).toMatch(/cannot set sensor on ".*" — not a widget/);
+	});
 });
diff --git a/client/src/lib/core/logs.test.ts b/client/src/lib/core/logs.test.ts
new file mode 100644
index 0000000..04b0baf
--- /dev/null
+++ b/client/src/lib/core/logs.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { atLeastLevel, LOG_LEVELS, type LogLevel } from './logs';
+
+describe('logs', () => {
+	it('LOG_LEVELS is ascending severity', () => {
+		expect(LOG_LEVELS).toEqual(['trace', 'debug', 'info', 'warn', 'error']);
+	});
+
+	it('atLeastLevel compares severity (inclusive)', () => {
+		expect(atLeastLevel('warn', 'info')).toBe(true); // higher
+		expect(atLeastLevel('info', 'info')).toBe(true); // equal
+		expect(atLeastLevel('info', 'warn')).toBe(false); // lower
+		expect(atLeastLevel('trace', 'error')).toBe(false); // extreme low vs high
+		expect(atLeastLevel('error', 'trace')).toBe(true); // extreme high vs low
+	});
+
+	it('every level is at least itself', () => {
+		for (const l of LOG_LEVELS) expect(atLeastLevel(l as LogLevel, l as LogLevel)).toBe(true);
+	});
+});
diff --git a/client/src/lib/core/macro.test.ts b/client/src/lib/core/macro.test.ts
index 514dce2..3a50922 100644
--- a/client/src/lib/core/macro.test.ts
+++ b/client/src/lib/core/macro.test.ts
@@ -6,6 +6,7 @@ import {
 	removeAction,
 	runMacro,
 	updateAction,
+	withEntityId,
 	type Macro,
 	type MacroAction
 } from './macro';
@@ -149,4 +150,19 @@ describe('macro edit ops (pure / immutable)', () => {
 		expect(moveAction(base, 1, 1)).toBe(base);
 		expect(base[0]).toEqual({ domain: 'light', service: 'toggle' });
 	});
+
+	it('withEntityId sets, preserves other keys, and clears', () => {
+		expect(withEntityId(undefined, 'light.x')).toEqual({ entity_id: 'light.x' });
+		expect(withEntityId({ brightness_pct: 60 }, 'light.x')).toEqual({
+			entity_id: 'light.x',
+			brightness_pct: 60
+		});
+		// clearing removes only entity_id, keeping the rest
+		expect(withEntityId({ entity_id: 'light.x', brightness_pct: 60 }, '')).toEqual({
+			brightness_pct: 60
+		});
+		// clearing the last key → undefined (matches optional data)
+		expect(withEntityId({ entity_id: 'light.x' }, '')).toBeUndefined();
+		expect(withEntityId({ entity_id: 'light.x' }, '   ')).toBeUndefined();
+	});
 });
diff --git a/client/src/lib/core/macro.ts b/client/src/lib/core/macro.ts
index 0222af6..553d701 100644
--- a/client/src/lib/core/macro.ts
+++ b/client/src/lib/core/macro.ts
@@ -75,6 +75,21 @@ export function updateAction(actions: Macro, index: number, patch: Partial<Macro
 	return actions.map((a, i) => (i === index ? { ...a, ...patch } : a));
 }
 
+/** Set (or, when `id` is blank, clear) the `entity_id` in an action's `data` — for the editor's
+ * entity picker — without disturbing other data keys. Returns `undefined` when clearing leaves no
+ * keys, matching the model's optional `data`. Pure. */
+export function withEntityId(
+	data: Record<string, unknown> | undefined,
+	id: string
+): Record<string, unknown> | undefined {
+	const rest = { ...(data ?? {}) };
+	if (id.trim() === '') {
+		delete rest.entity_id;
+		return Object.keys(rest).length ? rest : undefined;
+	}
+	return { ...rest, entity_id: id };
+}
+
 /** Move the action at `index` by `delta` slots; returns the list unchanged if the move is a no-op. */
 export function moveAction(actions: Macro, index: number, delta: number): Macro {
 	const to = index + delta;
diff --git a/client/src/lib/core/migration.test.ts b/client/src/lib/core/migration.test.ts
index 842120d..880257b 100644
--- a/client/src/lib/core/migration.test.ts
+++ b/client/src/lib/core/migration.test.ts
@@ -38,6 +38,9 @@ const widget = (id: string, x: number, y: number, w: number, h: number): WidgetI
 	config: {}
 });
 
+// A minimal valid primitive unit (passes isUnit) for node-level parse tests.
+const validWidgetNode: WidgetInstance = widget('w1', 0, 0, 10, 10);
+
 describe('migrateV1', () => {
 	it('wraps every widget as a floating leaf under an empty root, rects verbatim', () => {
 		const v1: LayoutV1 = {
@@ -251,6 +254,229 @@ describe('parseLayoutAny', () => {
 			parseLayoutAny({ version: '1', monitors: { default: { widgets: [validWidget] } } })
 		).toBeNull();
 	});
+
+	it('returns null when an explicit-v1 file fails v1 validation', () => {
+		// version === 1 takes the `v1raw = raw` path; the monitor has no widgets[] so parseLayoutV1
+		// returns null → parseLayoutAny returns null (the `if (v1 === null)` arm).
+		expect(parseLayoutAny({ version: 1, monitors: { default: {} } })).toBeNull();
+	});
+
+	it('returns null when a monitor entry is null (the raw === null guard)', () => {
+		expect(parseLayoutAny({ version: 2, monitors: { m: null } })).toBeNull();
+	});
+
+	it('returns null when floating is present but not an array', () => {
+		expect(
+			parseLayoutAny({
+				version: 2,
+				monitors: { m: { root: { id: 'r', kind: 'col', children: [] }, floating: 42 } }
+			})
+		).toBeNull();
+	});
+
+	it('fails the monitor when the container id is not a string', () => {
+		expect(
+			parseLayoutAny({
+				version: 2,
+				monitors: { m: { root: { id: 5, kind: 'col', children: [] } } }
+			})
+		).toBeNull();
+	});
+
+	it('defaults floating to [] when the key is absent (not undefined-but-present)', () => {
+		const r = parseLayoutAny({
+			version: 2,
+			monitors: { m: { root: { id: 'r', kind: 'col', children: [] } } }
+		});
+		expect(r?.monitors.m.floating).toEqual([]);
+	});
+});
+
+describe('parseLayoutNode (node-level whitelist, exercises parseContainer / parseLeaf)', () => {
+	it('returns null for a non-object / null node', () => {
+		expect(parseLayoutNode(null)).toBeNull();
+		expect(parseLayoutNode(42)).toBeNull();
+	});
+
+	it('returns null for an object that is neither a container kind nor a leaf (no "unit")', () => {
+		expect(parseLayoutNode({ foo: 'bar' })).toBeNull();
+	});
+
+	it('keeps every whitelisted container field when valid', () => {
+		const n = parseLayoutNode({
+			id: 'c',
+			kind: 'row',
+			children: [],
+			basis: 'auto',
+			cols: 3,
+			rows: 2,
+			gap: 8,
+			pad: 4,
+			margin: { t: 1, r: 2, b: 3, l: 4 },
+			align: 'center',
+			justify: 'between',
+			bounds: { x: 0, y: 0, w: 100, h: 50 },
+			overlap: false
+		});
+		expect(n).toMatchObject({
+			id: 'c',
+			kind: 'row',
+			basis: 'auto',
+			cols: 3,
+			rows: 2,
+			gap: 8,
+			pad: 4,
+			margin: { t: 1, r: 2, b: 3, l: 4 },
+			align: 'center',
+			justify: 'between',
+			bounds: { x: 0, y: 0, w: 100, h: 50 },
+			overlap: false
+		});
+	});
+
+	it('drops invalid optional container fields (the implicit-false arms)', () => {
+		const n = parseLayoutNode({
+			id: 'c',
+			kind: 'col',
+			children: [],
+			basis: 'nonsense',
+			cols: 'x',
+			rows: null,
+			gap: '8',
+			pad: { t: 1 }, // missing r/b/l → not a Pad
+			margin: 'no',
+			align: 'middle', // not a valid Align
+			justify: 'evenly', // not a valid Justify
+			bounds: { x: 0 }, // not a full Rect
+			overlap: 'yes',
+			cellW: 'no',
+			cellH: null,
+			aspect: 'x',
+			colFr: [1, 'x'], // not all finite numbers
+			rowFr: 'no'
+		}) as Record<string, unknown>;
+		expect(n).toEqual({ id: 'c', kind: 'col', children: [] });
+	});
+
+	it('drops malformed children inside a container (children filter null-drop)', () => {
+		const n = parseLayoutNode({
+			id: 'c',
+			kind: 'col',
+			children: [{ id: 'L', unit: validWidgetNode }, { nope: true }, 99]
+		}) as { children: unknown[] };
+		expect(n.children).toHaveLength(1);
+	});
+
+	it('treats a non-array children as empty', () => {
+		const n = parseLayoutNode({ id: 'c', kind: 'grid', children: 'oops' }) as {
+			children: unknown[];
+		};
+		expect(n.children).toEqual([]);
+	});
+
+	it('falls back to the unit id when the leaf has no string id', () => {
+		const n = parseLayoutNode({ unit: validWidgetNode }) as { id: string };
+		expect(n.id).toBe('w1'); // taken from unit.id
+	});
+
+	it('keeps every whitelisted leaf field when valid', () => {
+		const n = parseLayoutNode({
+			id: 'lf',
+			unit: validWidgetNode,
+			basis: { fr: 2 },
+			margin: 6,
+			pad: { t: 1, r: 1, b: 1, l: 1 },
+			halign: 'right',
+			valign: 'bottom'
+		});
+		expect(n).toMatchObject({
+			id: 'lf',
+			basis: { fr: 2 },
+			margin: 6,
+			pad: { t: 1, r: 1, b: 1, l: 1 },
+			halign: 'right',
+			valign: 'bottom'
+		});
+	});
+
+	it('drops invalid optional leaf fields (the implicit-false arms)', () => {
+		const n = parseLayoutNode({
+			id: 'lf',
+			unit: validWidgetNode,
+			basis: 'bad',
+			margin: 'no',
+			pad: { t: 1 }, // not a full Pad
+			halign: 'middle', // not a valid HAlign
+			valign: 'center' // not a valid VAlign (center is HAlign, not VAlign)
+		}) as Record<string, unknown>;
+		expect(n).toEqual({ id: 'lf', unit: validWidgetNode });
+	});
+
+	it('rejects a leaf whose unit is not a valid unit', () => {
+		expect(parseLayoutNode({ id: 'lf', unit: 42 })).toBeNull();
+		expect(parseLayoutNode({ id: 'lf', unit: null })).toBeNull();
+	});
+
+	it('accepts a group unit by def id or by inline child, rejects an empty group', () => {
+		// def-id group
+		expect(
+			parseLayoutNode({ id: 'g', unit: { id: 'g', kind: 'group', def: 'lib1' } })
+		).not.toBeNull();
+		// inline-child group
+		expect(
+			parseLayoutNode({
+				id: 'g',
+				unit: { id: 'g', kind: 'group', child: { id: 'c', kind: 'col', children: [] } }
+			})
+		).not.toBeNull();
+		// a group with neither def nor a non-null child is not a valid unit → leaf rejected
+		expect(parseLayoutNode({ id: 'g', unit: { id: 'g', kind: 'group', child: null } })).toBeNull();
+		expect(parseLayoutNode({ id: 'g', unit: { id: 'g', kind: 'group' } })).toBeNull();
+	});
+
+	it('validates each Align / HAlign / VAlign / Justify alternative', () => {
+		const withField = (field: string, value: unknown) =>
+			parseLayoutNode({ id: 'c', kind: 'row', children: [], [field]: value }) as Record<
+				string,
+				unknown
+			>;
+		for (const a of ['start', 'center', 'end', 'stretch'])
+			expect(withField('align', a).align).toBe(a);
+		for (const j of ['start', 'center', 'end', 'between', 'around'])
+			expect(withField('justify', j).justify).toBe(j);
+		const leafWith = (field: string, value: unknown) =>
+			parseLayoutNode({ id: 'lf', unit: validWidgetNode, [field]: value }) as Record<
+				string,
+				unknown
+			>;
+		for (const h of ['left', 'right', 'center', 'fill'])
+			expect(leafWith('halign', h).halign).toBe(h);
+		for (const v of ['top', 'middle', 'bottom', 'fill'])
+			expect(leafWith('valign', v).valign).toBe(v);
+	});
+
+	it('accepts every Length form for basis (number | auto | content | {fr}) and rejects others', () => {
+		const basisOf = (b: unknown) =>
+			(parseLayoutNode({ id: 'c', kind: 'row', children: [], basis: b }) as { basis?: unknown })
+				.basis;
+		expect(basisOf(120)).toBe(120);
+		expect(basisOf('auto')).toBe('auto');
+		expect(basisOf('content')).toBe('content');
+		expect(basisOf({ fr: 1 })).toEqual({ fr: 1 });
+		expect(basisOf({ fr: 'x' })).toBeUndefined(); // {fr} present but not a number
+		expect(basisOf(null)).toBeUndefined(); // object branch short-circuits on null
+		expect(basisOf('weird')).toBeUndefined();
+	});
+
+	it('accepts a numeric pad and a per-side pad, rejects partial / non-object', () => {
+		const padOf = (p: unknown) =>
+			(parseLayoutNode({ id: 'c', kind: 'row', children: [], pad: p }) as { pad?: unknown }).pad;
+		expect(padOf(4)).toBe(4); // number form
+		expect(padOf({ t: 1, r: 2, b: 3, l: 4 })).toEqual({ t: 1, r: 2, b: 3, l: 4 }); // per-side
+		expect(padOf({ t: 1, r: 2, b: 3 })).toBeUndefined(); // missing l
+		expect(padOf(null)).toBeUndefined(); // non-number, null object
+		expect(padOf('x')).toBeUndefined(); // non-number, non-object
+	});
 });
 
 describe("parseLayoutNode preserves a 'content' (hug) basis", () => {
diff --git a/client/src/lib/core/monitorInputs.test.ts b/client/src/lib/core/monitorInputs.test.ts
new file mode 100644
index 0000000..090aa0c
--- /dev/null
+++ b/client/src/lib/core/monitorInputs.test.ts
@@ -0,0 +1,160 @@
+import { describe, expect, it } from 'vitest';
+import {
+	buildSourceSpec,
+	formatStats,
+	inputName,
+	monitorInputRows,
+	parseSourceSpec,
+	sourceEditorRows
+} from './monitorInputs';
+
+describe('inputName', () => {
+	it('names standard MCCS codes', () => {
+		expect(inputName(0x0f)).toBe('DisplayPort 1');
+		expect(inputName(0x11)).toBe('HDMI 1');
+		expect(inputName(0x12)).toBe('HDMI 2');
+	});
+
+	it('falls back to a padded hex label for unknown codes', () => {
+		expect(inputName(0x1b)).toBe('Input 0x1B');
+		expect(inputName(0x03)).toBe('DVI 1');
+	});
+});
+
+describe('parseSourceSpec', () => {
+	it('returns [] for blank/undefined', () => {
+		expect(parseSourceSpec(undefined)).toEqual([]);
+		expect(parseSourceSpec('')).toEqual([]);
+		expect(parseSourceSpec('   ')).toEqual([]);
+	});
+
+	it('parses decimal, 0x-hex and trailing-h codes', () => {
+		expect(parseSourceSpec('17, 0x0f, 12h')).toEqual([
+			{ value: 17, label: inputName(17) },
+			{ value: 0x0f, label: 'DisplayPort 1' },
+			{ value: 0x12, label: 'HDMI 2' }
+		]);
+	});
+
+	it('honours explicit labels and preserves order', () => {
+		expect(parseSourceSpec('0x11=Desktop, 0x12=Console')).toEqual([
+			{ value: 0x11, label: 'Desktop' },
+			{ value: 0x12, label: 'Console' }
+		]);
+	});
+
+	it('accepts newline separators and trims whitespace', () => {
+		expect(parseSourceSpec(' 0x0f = DP \n 0x11 = HDMI ')).toEqual([
+			{ value: 0x0f, label: 'DP' },
+			{ value: 0x11, label: 'HDMI' }
+		]);
+	});
+
+	it('drops junk and out-of-range codes', () => {
+		expect(parseSourceSpec('zzz, 999, -1, 0x11=ok')).toEqual([{ value: 0x11, label: 'ok' }]);
+	});
+});
+
+describe('monitorInputRows', () => {
+	it('uses discovered inputs when no spec, marking the active one', () => {
+		const rows = monitorInputRows({ discovered: [0x0f, 0x11, 0x12], current: 0x11 });
+		expect(rows).toEqual([
+			{ value: 0x0f, label: 'DisplayPort 1', active: false },
+			{ value: 0x11, label: 'HDMI 1', active: true },
+			{ value: 0x12, label: 'HDMI 2', active: false }
+		]);
+	});
+
+	it('prefers the spec over discovered inputs (filter + order + rename)', () => {
+		const rows = monitorInputRows({
+			discovered: [0x0f, 0x10, 0x11, 0x12],
+			spec: '0x12=Console, 0x0f=PC',
+			current: 0x0f
+		});
+		expect(rows).toEqual([
+			{ value: 0x12, label: 'Console', active: false },
+			{ value: 0x0f, label: 'PC', active: true }
+		]);
+	});
+
+	it('falls back to defaults when nothing is discovered or specced', () => {
+		const rows = monitorInputRows({ discovered: [], current: null });
+		expect(rows.map((r) => r.value)).toEqual([0x0f, 0x10, 0x11, 0x12]);
+		expect(rows.every((r) => !r.active)).toBe(true);
+	});
+
+	it('always includes the active input even if outside the chosen set', () => {
+		const rows = monitorInputRows({ discovered: [], spec: '0x11', current: 0x1b });
+		expect(rows).toEqual([
+			{ value: 0x11, label: 'HDMI 1', active: false },
+			{ value: 0x1b, label: 'Input 0x1B', active: true }
+		]);
+	});
+
+	it('de-duplicates repeated values, keeping the first label', () => {
+		const rows = monitorInputRows({ discovered: [], spec: '0x11=One, 0x11=Two', current: null });
+		expect(rows).toEqual([{ value: 0x11, label: 'One', active: false }]);
+	});
+});
+
+describe('formatStats', () => {
+	it('formats resolution + refresh', () => {
+		expect(formatStats({ width: 2560, height: 1440, refreshHz: 144 })).toBe('2560×1440 · 144 Hz');
+	});
+
+	it('drops the refresh when unknown', () => {
+		expect(formatStats({ width: 1920, height: 1080, refreshHz: 0 })).toBe('1920×1080');
+	});
+
+	it('is empty when the mode is unknown', () => {
+		expect(formatStats(null)).toBe('');
+		expect(formatStats({ width: 0, height: 0, refreshHz: 0 })).toBe('');
+	});
+});
+
+describe('sourceEditorRows', () => {
+	it('lists all detected inputs as included with default names when the spec is blank', () => {
+		expect(sourceEditorRows([0x0f, 0x11], '')).toEqual([
+			{ value: 0x0f, defaultName: 'DisplayPort 1', label: '', include: true, detected: true },
+			{ value: 0x11, defaultName: 'HDMI 1', label: '', include: true, detected: true }
+		]);
+	});
+
+	it('includes only spec-listed inputs and carries custom labels', () => {
+		const rows = sourceEditorRows([0x0f, 0x11, 0x12], '0x11=Desktop, 0x12');
+		expect(rows).toEqual([
+			{ value: 0x0f, defaultName: 'DisplayPort 1', label: '', include: false, detected: true },
+			{ value: 0x11, defaultName: 'HDMI 1', label: 'Desktop', include: true, detected: true },
+			{ value: 0x12, defaultName: 'HDMI 2', label: '', include: true, detected: true }
+		]);
+	});
+
+	it('appends spec entries the monitor did not report as manual rows', () => {
+		const rows = sourceEditorRows([0x11], '0x11, 0x1b=Console');
+		expect(rows).toEqual([
+			{ value: 0x11, defaultName: 'HDMI 1', label: '', include: true, detected: true },
+			{ value: 0x1b, defaultName: 'Input 0x1B', label: 'Console', include: true, detected: false }
+		]);
+	});
+});
+
+describe('buildSourceSpec', () => {
+	it('returns blank (auto) when all detected inputs are included with default names', () => {
+		expect(buildSourceSpec(sourceEditorRows([0x0f, 0x11], ''))).toBe('');
+	});
+
+	it('emits an explicit code=label spec for a renamed/filtered set', () => {
+		const rows = sourceEditorRows([0x0f, 0x11, 0x12], '');
+		rows[0].include = false; // drop DisplayPort 1
+		rows[2].label = 'Switch 2'; // rename HDMI 2
+		expect(buildSourceSpec(rows)).toBe('0x11, 0x12=Switch 2');
+	});
+
+	it('round-trips through parseSourceSpec', () => {
+		const rows = sourceEditorRows([0x11, 0x12], '0x11=Desktop, 0x12=Switch 2');
+		expect(parseSourceSpec(buildSourceSpec(rows))).toEqual([
+			{ value: 0x11, label: 'Desktop' },
+			{ value: 0x12, label: 'Switch 2' }
+		]);
+	});
+});
diff --git a/client/src/lib/core/monitorInputs.ts b/client/src/lib/core/monitorInputs.ts
new file mode 100644
index 0000000..0ab22fe
--- /dev/null
+++ b/client/src/lib/core/monitorInputs.ts
@@ -0,0 +1,178 @@
+// Pure shaping for the Monitor Switch widget (a DDC/CI input-source switcher). No React/Tauri —
+// unit-tested. The backend (widgetsack/src/ddc.rs) enumerates monitors and reads/sets VCP 0x60; this
+// module names the standard MCCS input codes, parses the user's `sources` config, and merges the
+// discovered + configured + current inputs into display rows for the meter.
+
+export type MonitorInputRow = { value: number; label: string; active: boolean };
+export type SourceSpec = { value: number; label: string };
+
+// Standard MCCS v2.x VCP 0x60 ("Input Select") values. Real monitors deviate (these codes are
+// vendor-specific in practice), so this is only a friendly FALLBACK name — discovery comes from the
+// monitor's own capabilities and the user can rename/choose per source via the `sources` spec.
+export const MCCS_INPUT_NAMES: Record<number, string> = {
+	0x01: 'VGA 1',
+	0x02: 'VGA 2',
+	0x03: 'DVI 1',
+	0x04: 'DVI 2',
+	0x05: 'Composite 1',
+	0x06: 'Composite 2',
+	0x07: 'S-Video 1',
+	0x08: 'S-Video 2',
+	0x09: 'Tuner 1',
+	0x0a: 'Tuner 2',
+	0x0b: 'Tuner 3',
+	0x0c: 'Component 1',
+	0x0d: 'Component 2',
+	0x0e: 'Component 3',
+	0x0f: 'DisplayPort 1',
+	0x10: 'DisplayPort 2',
+	0x11: 'HDMI 1',
+	0x12: 'HDMI 2',
+	0x15: 'USB-C' // common vendor extension (USB-C / Thunderbolt on some panels)
+};
+
+// A usable fallback when neither the user's spec nor capability discovery yields any inputs (some
+// monitors don't report a 0x60 list). The user can always narrow this with the `sources` spec.
+const DEFAULT_INPUTS = [0x0f, 0x10, 0x11, 0x12]; // DP 1, DP 2, HDMI 1, HDMI 2
+
+/** Friendly name for a VCP 0x60 value: the MCCS name, else a hex fallback like `Input 0x1B`. */
+export function inputName(value: number): string {
+	return MCCS_INPUT_NAMES[value] ?? `Input 0x${value.toString(16).toUpperCase().padStart(2, '0')}`;
+}
+
+/** Parse a single input code: decimal (`17`), `0x`-hex (`0x11`), or trailing-`h` hex (`11h`). Returns
+ *  null for junk or an out-of-byte-range value. */
+function parseCode(s: string): number | null {
+	const t = s.trim();
+	let v: number;
+	if (/^0x[0-9a-f]+$/i.test(t)) v = parseInt(t.slice(2), 16);
+	else if (/^[0-9a-f]+h$/i.test(t)) v = parseInt(t.slice(0, -1), 16);
+	else if (/^\d+$/.test(t)) v = parseInt(t, 10);
+	else return null;
+	return Number.isFinite(v) && v >= 0 && v <= 255 ? v : null;
+}
+
+/** Parse the optional `sources` config: a comma/newline-separated list of `code` or `code=label`
+ *  entries (code = decimal `17`, hex `0x11`, or `11h`). Blank/invalid entries are dropped; a missing
+ *  label defaults to the MCCS name. Lets a user choose WHICH inputs appear (and order + rename them)
+ *  without a multi-select control. Pure. */
+export function parseSourceSpec(spec: string | undefined): SourceSpec[] {
+	if (!spec) return [];
+	const out: SourceSpec[] = [];
+	for (const raw of spec.split(/[,\n]/)) {
+		const entry = raw.trim();
+		if (!entry) continue;
+		const eq = entry.indexOf('=');
+		const value = parseCode(eq >= 0 ? entry.slice(0, eq) : entry);
+		if (value === null) continue;
+		const label = eq >= 0 ? entry.slice(eq + 1).trim() : '';
+		out.push({ value, label: label || inputName(value) });
+	}
+	return out;
+}
+
+/** Build the meter's input rows from the monitor's discovered inputs (caps), the user's `sources`
+ *  spec, and the current input. Precedence: an explicit spec wins; else discovered inputs; else a
+ *  sensible default set. The active input is always included (even if outside the chosen set) so the
+ *  user can see — and switch back to — what's selected. De-duplicated by value, order preserved. Pure. */
+export function monitorInputRows(opts: {
+	discovered: number[];
+	spec?: string;
+	current?: number | null;
+}): MonitorInputRow[] {
+	const { discovered, spec, current = null } = opts;
+	const parsed = parseSourceSpec(spec);
+
+	let base: SourceSpec[];
+	if (parsed.length > 0) base = parsed;
+	else if (discovered.length > 0) base = discovered.map((v) => ({ value: v, label: inputName(v) }));
+	else base = DEFAULT_INPUTS.map((v) => ({ value: v, label: inputName(v) }));
+
+	if (current !== null && !base.some((b) => b.value === current)) {
+		base = [...base, { value: current, label: inputName(current) }];
+	}
+
+	const seen = new Set<number>();
+	const rows: MonitorInputRow[] = [];
+	for (const b of base) {
+		if (seen.has(b.value)) continue;
+		seen.add(b.value);
+		rows.push({ value: b.value, label: b.label, active: b.value === current });
+	}
+	return rows;
+}
+
+/** Format the current-mode stats line, e.g. `2560×1440 · 144 Hz`. Empty string when the mode is
+ *  unknown (width/height 0); drops the refresh when it's unknown. Pure. */
+export function formatStats(
+	stats: { width: number; height: number; refreshHz: number } | null | undefined
+): string {
+	if (!stats || stats.width <= 0 || stats.height <= 0) return '';
+	const res = `${stats.width}×${stats.height}`;
+	return stats.refreshHz > 0 ? `${res} · ${stats.refreshHz} Hz` : res;
+}
+
+// --- Friendly sources editor (the studio Inspector control) ------------------------------------
+
+/** One row in the Inspector's sources editor: an input the user can include/exclude and rename.
+ *  `label` is the custom name ('' = use `defaultName`). `detected` is false for a manual entry kept
+ *  from the spec that the monitor didn't report. */
+export type SourceEditorRow = {
+	value: number;
+	defaultName: string;
+	label: string;
+	include: boolean;
+	detected: boolean;
+};
+
+/** Build the editor rows from the monitor's detected inputs + the current `sources` spec. Detected
+ *  inputs come first (checked when the spec is blank, else only those the spec lists); spec entries the
+ *  monitor didn't report follow as manual rows. `label` is '' when it matches the default name. Pure. */
+export function sourceEditorRows(detected: number[], spec: string | undefined): SourceEditorRow[] {
+	const parsed = parseSourceSpec(spec);
+	const specEmpty = parsed.length === 0;
+	const byValue = new Map(parsed.map((p) => [p.value, p.label]));
+	const rows: SourceEditorRow[] = [];
+	const seen = new Set<number>();
+	for (const value of detected) {
+		if (seen.has(value)) continue;
+		seen.add(value);
+		const custom = byValue.get(value);
+		const defaultName = inputName(value);
+		rows.push({
+			value,
+			defaultName,
+			label: custom && custom !== defaultName ? custom : '',
+			include: specEmpty || byValue.has(value),
+			detected: true
+		});
+	}
+	for (const p of parsed) {
+		if (seen.has(p.value)) continue;
+		seen.add(p.value);
+		const defaultName = inputName(p.value);
+		rows.push({
+			value: p.value,
+			defaultName,
+			label: p.label !== defaultName ? p.label : '',
+			include: true,
+			detected: false
+		});
+	}
+	return rows;
+}
+
+/** Build the `sources` spec string from editor rows. Included rows become `0xNN` (or `0xNN=label`
+ *  when renamed). Returns '' (the clean "auto: show all detected" default) when the rows are exactly
+ *  all-detected, all-included, none-renamed. Pure — inverse of `sourceEditorRows`. */
+export function buildSourceSpec(rows: SourceEditorRow[]): string {
+	const isAuto = rows.length > 0 && rows.every((r) => r.detected && r.include && r.label === '');
+	if (isAuto) return '';
+	return rows
+		.filter((r) => r.include)
+		.map((r) => {
+			const code = `0x${r.value.toString(16)}`;
+			return r.label ? `${code}=${r.label}` : code;
+		})
+		.join(', ');
+}
diff --git a/client/src/lib/core/palette.test.ts b/client/src/lib/core/palette.test.ts
index c184103..21edf7e 100644
--- a/client/src/lib/core/palette.test.ts
+++ b/client/src/lib/core/palette.test.ts
@@ -8,6 +8,8 @@ import {
 	pickSeed,
 	averageLuminance,
 	deriveTokens,
+	rgbCss,
+	rgbaCss,
 	type RGB
 } from './palette';
 
@@ -34,6 +36,46 @@ describe('colour conversions', () => {
 		expect(relLuminance([255, 255, 255])).toBeCloseTo(1, 5);
 		expect(relLuminance([0, 0, 0])).toBeCloseTo(0, 5);
 		expect(contrast(1, 0)).toBeCloseTo(21, 1);
+		// contrast is symmetric in its arguments (it sorts hi/lo internally).
+		expect(contrast(0, 1)).toBeCloseTo(21, 1);
+	});
+
+	it('hslToRgb covers all six hue sextants (a full hue sweep round-trips)', () => {
+		// One pure hue per 60° sextant — exercises every branch of the hp<n chain, incl. blue→magenta
+		// (hp∈[4,5)) and magenta→red (hp≥5) which the representative round-trip set above misses.
+		const hues: Array<[number, RGB]> = [
+			[0, [255, 0, 0]], // red          (hp 0)
+			[60, [255, 255, 0]], // yellow    (hp 1)
+			[120, [0, 255, 0]], // green      (hp 2)
+			[180, [0, 255, 255]], // cyan     (hp 3)
+			[240, [0, 0, 255]], // blue       (hp 4)
+			[300, [255, 0, 255]] // magenta   (hp 5)
+		];
+		for (const [h, rgb] of hues) {
+			expect(hslToRgb([h, 1, 0.5])).toEqual(rgb);
+		}
+	});
+
+	it('hslToRgb wraps an out-of-range / negative hue into [0,360)', () => {
+		expect(hslToRgb([360, 1, 0.5])).toEqual([255, 0, 0]); // 360 ≡ 0 (red)
+		expect(hslToRgb([-60, 1, 0.5])).toEqual([255, 0, 255]); // -60 ≡ 300 (magenta)
+	});
+
+	it('rgbToHsl wraps a negative computed hue (red-dominant, blue>green) back into [0,360)', () => {
+		// magenta-leaning red: max is red, gn-bn is negative → raw hue < 0 → the `h += 360` branch.
+		const [h] = rgbToHsl([255, 0, 128]);
+		expect(h).toBeGreaterThan(300);
+		expect(h).toBeLessThan(360);
+	});
+
+	it('rgbToHsl reports hue for green- and blue-dominant colours (the other max branches)', () => {
+		expect(rgbToHsl([0, 255, 0])[0]).toBeCloseTo(120, 1); // green max
+		expect(rgbToHsl([0, 0, 255])[0]).toBeCloseTo(240, 1); // blue max
+	});
+
+	it('rgbCss / rgbaCss format CSS colour strings', () => {
+		expect(rgbCss([1, 2, 3])).toBe('rgb(1, 2, 3)');
+		expect(rgbaCss([1, 2, 3], 0.5)).toBe('rgba(1, 2, 3, 0.5)');
 	});
 });
 
@@ -63,6 +105,21 @@ describe('quantize + pickSeed', () => {
 		// The default teal accent (119,196,211) — bluish, not grey.
 		expect(seed[2]).toBeGreaterThan(seed[0]);
 	});
+
+	it('falls back to the most-saturated bucket when every colour fails the strict accent gate', () => {
+		// A muted blue with saturation in [0.12, 0.2): rejected by the strict gate (s < 0.2 continue),
+		// but it clears the loose `mostSaturated.s >= 0.12` fallback, so it — not the default — is the seed.
+		const muted: RGB = [96, 110, 140]; // s ≈ 0.18
+		const sCheck = rgbToHsl(muted)[1];
+		expect(sCheck).toBeGreaterThan(0.12);
+		expect(sCheck).toBeLessThan(0.2);
+		const seed = pickSeed(quantize([muted]));
+		expect(rgbToHsl(seed)[0]).toBeCloseTo(rgbToHsl(muted)[0], -1); // blue hue preserved, not the teal default
+	});
+
+	it('averageLuminance is 0 for an empty sample set', () => {
+		expect(averageLuminance([])).toBe(0);
+	});
 });
 
 describe('deriveTokens', () => {
@@ -95,4 +152,24 @@ describe('deriveTokens', () => {
 			['--np-accent', '--np-bg', '--np-fg', '--np-label', '--np-muted', '--np-track'].sort()
 		);
 	});
+
+	it('lightens the accent until readable on a borderline-dark wallpaper (the lighten loop runs)', () => {
+		// avgLum just under the 0.42 dark threshold → a mid-light seed accent (l≈0.66) starts BELOW 3:1,
+		// so ensureReadable must iterate, lightening (l += 0.04) until it clears contrast.
+		const wall: RGB[] = Array(60).fill([150, 110, 60]); // warm mid-dark, avg lum < 0.42 but not tiny
+		expect(averageLuminance(wall)).toBeLessThan(0.42);
+		const t = deriveTokens(wall);
+		const accent = (t['--np-accent'].match(/\d+/g) ?? []).map(Number) as RGB;
+		expect(contrast(relLuminance(accent), averageLuminance(wall))).toBeGreaterThanOrEqual(2.9);
+	});
+
+	it('darkens the accent until readable on a light wallpaper (the darken loop runs)', () => {
+		// Light wallpaper → lighten=false; a seed accent at l≈0.42 may start below 3:1 against a bright
+		// background, forcing the darken arm (l -= 0.04) of the readability loop.
+		const wall: RGB[] = Array(60).fill([210, 205, 120]); // bright warm, avg lum > 0.42
+		expect(averageLuminance(wall)).toBeGreaterThan(0.42);
+		const t = deriveTokens(wall);
+		const accent = (t['--np-accent'].match(/\d+/g) ?? []).map(Number) as RGB;
+		expect(contrast(relLuminance(accent), averageLuminance(wall))).toBeGreaterThanOrEqual(2.9);
+	});
 });
diff --git a/client/src/lib/core/plugin.test.ts b/client/src/lib/core/plugin.test.ts
index 93241ee..40d7da5 100644
--- a/client/src/lib/core/plugin.test.ts
+++ b/client/src/lib/core/plugin.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { createTelemetryHub } from './telemetry';
 import {
 	listSources,
@@ -36,6 +36,33 @@ describe('sensor sources', () => {
 		expect(stopped).toBe(2);
 	});
 
+	it('skips (does not reject on) a source whose start() throws, still stopping the rest', async () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		let stopped = 0;
+		registerSource({
+			id: 'boom',
+			start: async () => {
+				throw new Error('unreachable HA');
+			}
+		});
+		registerSource({
+			id: 'survivor',
+			start: async () => () => {
+				stopped += 1;
+			}
+		});
+
+		const hub = createTelemetryHub();
+		const stop = await startAllSources(hub); // must resolve despite 'boom' rejecting
+		expect(warn).toHaveBeenCalledWith('source "boom" failed to start', expect.any(Error));
+		// stop() runs every source's stopper, including the failed source's no-op (must not throw).
+		expect(() => stop()).not.toThrow();
+		expect(stopped).toBe(1);
+		warn.mockRestore();
+		unregisterSource('boom');
+		unregisterSource('survivor');
+	});
+
 	it('registering by id replaces; catalog ids are the deduped union', () => {
 		registerSource({ id: 'dup', start: async () => () => undefined, catalog: () => ['x', 'y'] });
 		registerSource({ id: 'dup', start: async () => () => undefined, catalog: () => ['y', 'z'] });
diff --git a/client/src/lib/core/pluginPackage.test.ts b/client/src/lib/core/pluginPackage.test.ts
index 554e676..3a92dc9 100644
--- a/client/src/lib/core/pluginPackage.test.ts
+++ b/client/src/lib/core/pluginPackage.test.ts
@@ -105,6 +105,221 @@ describe('parsePluginPackage', () => {
 		expect(r.pkg.manifest.theme).toBeUndefined();
 		expect(r.pkg.warnings[0]).toContain('theme dropped');
 	});
+
+	it('carries optional metadata (description/author/homepage) through when present', () => {
+		const r = parsePluginPackage(
+			'weather-pack',
+			manifest({ description: 'Live weather', author: 'Acme', homepage: 'https://acme.dev' })
+		);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.pkg.manifest.description).toBe('Live weather');
+		expect(r.pkg.manifest.author).toBe('Acme');
+		expect(r.pkg.manifest.homepage).toBe('https://acme.dev');
+	});
+
+	it('accepts a valid theme and a template with a description', () => {
+		const r = parsePluginPackage(
+			'weather-pack',
+			manifest({
+				theme: { name: 'Sky', file: 'sky.css' },
+				templates: [
+					{
+						id: 'desc-tpl',
+						name: 'Has desc',
+						description: 'a described template',
+						size: { w: 10, h: 10 },
+						tree: leafNode()
+					}
+				]
+			})
+		);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.pkg.manifest.theme).toEqual({ name: 'Sky', file: 'sky.css' });
+		expect(r.pkg.manifest.templates[0].description).toBe('a described template');
+		expect(r.pkg.warnings).toEqual([]);
+	});
+
+	it('rejects the manifest-level required-string fields when missing/blank/non-string', () => {
+		// non-object / array JSON
+		expect(parsePluginPackage('weather-pack', '"a string"').ok).toBe(false);
+		expect(parsePluginPackage('weather-pack', '[1,2]').ok).toBe(false);
+		// id missing
+		const noId = parsePluginPackage('weather-pack', JSON.stringify({ manifestVersion: 1 }));
+		expect(noId.ok).toBe(false);
+		if (!noId.ok) expect(noId.reason).toContain('"id"');
+		// name blank (string but trims empty) and non-string version
+		const blankName = parsePluginPackage('weather-pack', manifest({ name: '   ' }));
+		expect(blankName.ok).toBe(false);
+		if (!blankName.ok) expect(blankName.reason).toContain('"name"');
+		const badVer = parsePluginPackage('weather-pack', manifest({ version: 42 }));
+		expect(badVer.ok).toBe(false);
+		if (!badVer.ok) expect(badVer.reason).toContain('"version"');
+	});
+
+	it('rejects non-string optional metadata (description/author/homepage)', () => {
+		for (const [field, label] of [
+			['description', '"description"'],
+			['author', '"author"'],
+			['homepage', '"homepage"']
+		] as const) {
+			const r = parsePluginPackage('weather-pack', manifest({ [field]: 123 }));
+			expect(r.ok).toBe(false);
+			if (!r.ok) expect(r.reason).toContain(label);
+		}
+	});
+
+	it('rejects a non-array "templates" outright', () => {
+		const r = parsePluginPackage('weather-pack', manifest({ templates: 'nope' }));
+		expect(r.ok).toBe(false);
+		if (!r.ok) expect(r.reason).toContain('"templates" must be an array');
+	});
+
+	it('drops a duplicate template id (second occurrence) with a warning', () => {
+		const r = parsePluginPackage(
+			'weather-pack',
+			manifest({
+				templates: [
+					{ id: 'dup', name: 'First', size: { w: 10, h: 10 }, tree: leafNode('a') },
+					{ id: 'dup', name: 'Second', size: { w: 10, h: 10 }, tree: leafNode('b') }
+				]
+			})
+		);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.pkg.manifest.templates.map((t) => t.name)).toEqual(['First']);
+		expect(r.pkg.warnings.some((w) => w.includes('duplicate id'))).toBe(true);
+	});
+});
+
+describe('parsePluginPackage — template + param validation', () => {
+	const tpl = (over: Record<string, unknown>) =>
+		parsePluginPackage(
+			'weather-pack',
+			manifest({
+				templates: [{ id: 't', name: 'T', size: { w: 10, h: 10 }, tree: leafNode(), ...over }]
+			})
+		);
+	const warn = (over: Record<string, unknown>): string => {
+		const r = tpl(over);
+		expect(r.ok).toBe(true);
+		if (!r.ok) throw new Error('unreachable');
+		expect(r.pkg.manifest.templates).toEqual([]); // the only template was dropped
+		return r.pkg.warnings[0];
+	};
+
+	it('drops a template that is not an object', () => {
+		const r = parsePluginPackage('weather-pack', manifest({ templates: ['nope'] }));
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.pkg.warnings[0]).toContain('not an object');
+	});
+
+	it('drops a template with a missing id, blank name, non-string description, or bad size', () => {
+		expect(
+			parsePluginPackage(
+				'weather-pack',
+				manifest({ templates: [{ name: 'X', size: { w: 1, h: 1 }, tree: leafNode() }] })
+			)
+		).toMatchObject({ ok: true });
+		// blank name (string-but-trims-empty)
+		expect(warn({ name: '  ' })).toContain('missing "name"');
+		// non-string description
+		expect(warn({ description: 9 })).toContain('"description" must be a string');
+		// bad size: missing, non-numeric, zero/negative, NaN
+		expect(warn({ size: undefined })).toContain('"size"');
+		expect(warn({ size: { w: 'x', h: 1 } })).toContain('"size"');
+		expect(warn({ size: { w: 0, h: 5 } })).toContain('"size"');
+		expect(warn({ size: { w: NaN, h: 5 } })).toContain('"size"');
+		expect(warn({ size: null })).toContain('"size"');
+	});
+
+	it('drops a template whose "params" is not an array', () => {
+		expect(warn({ params: 'nope' })).toContain('"params" must be an array');
+	});
+
+	it('drops a template with a non-object param spec or an invalid key', () => {
+		expect(warn({ params: ['nope'] })).toContain('malformed param spec');
+		expect(warn({ params: [{ key: '' }] })).toContain('malformed param spec'); // empty key
+		expect(warn({ params: [{}] })).toContain('malformed param spec'); // missing key
+	});
+
+	it('drops a param whose key has an empty path segment (a.. / trailing dot)', () => {
+		// isSafePath rejects empty segments — `a..b` splits to ['a','','b'] (length-0 middle segment).
+		expect(warn({ params: [{ key: 'a..b' }] })).toContain('malformed param spec');
+	});
+
+	it('drops a param whose target is an empty string (isSafePath rejects the empty path)', () => {
+		// key passes (non-empty), but the empty-string target trips isSafePath's `!v.length` guard.
+		expect(warn({ params: [{ key: 'k', target: '' }] })).toContain('malformed param spec');
+	});
+
+	it('drops a param with a non-string label, bad target, bad targets, or bad choices', () => {
+		expect(warn({ params: [{ key: 'k', label: 42 }] })).toContain('malformed param spec');
+		expect(warn({ params: [{ key: 'k', target: '__proto__.x' }] })).toContain('malformed');
+		expect(warn({ params: [{ key: 'k', targets: 'nope' }] })).toContain('malformed');
+		expect(warn({ params: [{ key: 'k', targets: ['ok', 'constructor'] }] })).toContain('malformed');
+		expect(warn({ params: [{ key: 'k', choices: 'nope' }] })).toContain('malformed');
+		expect(warn({ params: [{ key: 'k', choices: [{ value: 'v' }] }] })).toContain('malformed'); // no label
+		expect(warn({ params: [{ key: 'k', choices: ['nope'] }] })).toContain('malformed'); // non-object choice
+	});
+
+	it('accepts a fully-populated param (label/default/target/targets/choices) and clones it', () => {
+		const r = tpl({
+			params: [
+				{
+					key: 'k',
+					label: 'K',
+					default: 7,
+					target: 'unit.config.k',
+					targets: ['unit.config.a', 'unit.config.b'],
+					choices: [
+						{ value: 'x', label: 'X' },
+						{ value: 'y', label: 'Y' }
+					]
+				}
+			]
+		});
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const spec = r.pkg.manifest.templates[0].params![0];
+		expect(spec).toEqual({
+			key: 'k',
+			label: 'K',
+			default: 7,
+			target: 'unit.config.k',
+			targets: ['unit.config.a', 'unit.config.b'],
+			choices: [
+				{ value: 'x', label: 'X' },
+				{ value: 'y', label: 'Y' }
+			]
+		});
+	});
+
+	it('keeps a template whose empty params array yields no "params" key', () => {
+		const r = tpl({ params: [] });
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.pkg.manifest.templates[0].params).toBeUndefined();
+	});
+});
+
+describe('parsePluginPackage — theme validation', () => {
+	const theme = (t: unknown) => {
+		const r = parsePluginPackage('weather-pack', manifest({ theme: t }));
+		expect(r.ok).toBe(true);
+		if (!r.ok) throw new Error('unreachable');
+		return r.pkg;
+	};
+
+	it('drops a non-object theme, a theme with a blank name, and a non-string file', () => {
+		expect(theme('nope').warnings[0]).toContain('theme dropped: not an object');
+		expect(theme({ name: '  ', file: 'a.css' }).warnings[0]).toContain('missing "name"');
+		expect(theme({ name: 'Ok', file: 123 }).warnings[0]).toContain('"file"'); // non-string file
+		expect(theme({ name: 'Ok', file: 'a.b.css' }).warnings[0]).toContain('"file"'); // extra dot
+		expect(theme({ name: 'Ok', file: 'a.json' }).warnings[0]).toContain('"file"'); // wrong ext
+	});
 });
 
 describe('parsePluginPackage — source + sensors (Phase 2)', () => {
@@ -185,6 +400,15 @@ describe('parsePluginPackage — source + sensors (Phase 2)', () => {
 		expect(pkg.warnings[0]).toContain('pollSeconds');
 	});
 
+	it('drops a non-object source (e.g. null) and a non-array sensors block', () => {
+		const nullSrc = parse({ source: null });
+		expect(nullSrc.manifest.source).toBeUndefined();
+		expect(nullSrc.warnings[0]).toContain('source dropped: not an object');
+		const badSensors = parse({ source: source(), sensors: 'not-an-array' });
+		expect(badSensors.manifest.sensors).toEqual([]);
+		expect(badSensors.warnings[0]).toContain('sensors dropped: not an array');
+	});
+
 	it('drops malformed sensors (bad id, duplicate, non-string label) but keeps the package', () => {
 		for (const bad of [
 			[{ id: 'a/b' }],
@@ -226,6 +450,15 @@ describe('packageSensorId / consentFingerprint / enableConsentMessage', () => {
 		expect(both).toContain('theme contains');
 		expect(both).toContain('every 300s: a.com, b.com');
 	});
+
+	it('falls back to the default poll interval (60s) when hosts are given without pollSeconds', () => {
+		const msg = enableConsentMessage({ hosts: ['a.com'] });
+		expect(msg).toContain('polls the network every 60s: a.com');
+	});
+
+	it('renders an empty message (just the trailing prompt) when nothing is consent-worthy', () => {
+		expect(enableConsentMessage({})).toBe('Enable?');
+	});
 });
 
 describe('validateSourceRequests', () => {
@@ -350,4 +583,20 @@ describe('packageTemplates', () => {
 		expect(a).not.toBe(b); // private copy per insert
 		expect(isLeaf(a)).toBe(true);
 	});
+
+	it('omits the params key for a template that declares none', () => {
+		const r = parsePluginPackage(
+			'weather-pack',
+			manifest({
+				templates: [
+					{ id: 'no-params', name: 'No params', size: { w: 10, h: 10 }, tree: leafNode() }
+				]
+			})
+		);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const [tpl] = packageTemplates(r.pkg.manifest);
+		expect(tpl.params).toBeUndefined();
+		expect(tpl.description).toBe(''); // default when the template had no description
+	});
 });
diff --git a/client/src/lib/core/sack.test.ts b/client/src/lib/core/sack.test.ts
index b2f14ed..4b1a51d 100644
--- a/client/src/lib/core/sack.test.ts
+++ b/client/src/lib/core/sack.test.ts
@@ -69,6 +69,23 @@ describe('mergeLibrary', () => {
 		expect(grp.def).toBe('b-2'); // points to B's NEW id
 	});
 
+	it('rewrites group refs nested inside a CONTAINER child (recursion)', () => {
+		const into: Library = { version: 1, defs: [mkDef('a'), mkDef('b')] };
+		// A's child is a container whose descendant is a group referencing B — exercises the
+		// container-recursion branch of remapRefs (not just a top-level group leaf).
+		const incomingA: WidgetDef = {
+			id: 'a',
+			name: 'A',
+			size: { w: 10, h: 10 },
+			child: { id: 'row', kind: 'row', children: [groupLeaf('g', 'b')] }
+		};
+		const { library, idMap } = mergeLibrary(into, [incomingA, mkDef('b')]);
+		const mergedA = library.defs.find((d) => d.id === idMap.a);
+		const cont = mergedA?.child as { children: Leaf[] };
+		const grp = cont.children[0].unit as { def: string };
+		expect(grp.def).toBe(idMap.b);
+	});
+
 	it('does not mutate the incoming defs', () => {
 		const incoming = mkDef('a', groupLeaf('g', 'a'));
 		const into: Library = { version: 1, defs: [mkDef('a')] };
diff --git a/client/src/lib/core/schedule.test.ts b/client/src/lib/core/schedule.test.ts
index 9f8df50..72bef1a 100644
--- a/client/src/lib/core/schedule.test.ts
+++ b/client/src/lib/core/schedule.test.ts
@@ -6,9 +6,14 @@ describe('intervalMs', () => {
 		expect(intervalMs('30s')).toBe(30_000);
 		expect(intervalMs('5m')).toBe(300_000);
 		expect(intervalMs('2h')).toBe(7_200_000);
+		expect(intervalMs('1d')).toBe(86_400_000); // days
 		expect(intervalMs('90')).toBe(90_000); // bare = seconds
 		expect(intervalMs('500ms')).toBe(500);
 	});
+	it('accepts a fractional value and trims/normalizes whitespace + case', () => {
+		expect(intervalMs('1.5h')).toBe(5_400_000);
+		expect(intervalMs('  2 M ')).toBe(120_000); // padding + space before unit + uppercase
+	});
 	it('rejects non-intervals', () => {
 		expect(intervalMs('manual')).toBeNull();
 		expect(intervalMs('')).toBeNull();
@@ -65,6 +70,26 @@ describe('cronMatches', () => {
 		expect(cronMatches('not cron', mon0900)).toBe(false);
 		expect(cronMatches('0 9 * *', mon0900)).toBe(false);
 	});
+
+	it('treats an unparseable step as 1 (every value in the range matches)', () => {
+		// "*/x" → step parses to NaN → `|| 1` falls back to 1, so every minute in [0,59] matches.
+		expect(cronMatches('*/x 9 * * *', mon0900)).toBe(true); // minute 0, step 1 → match
+		expect(cronMatches('*/x 9 * * *', new Date(2026, 0, 5, 9, 37))).toBe(true);
+		// "*/0" would divide by zero; the `|| 1` guard turns the 0 step into 1 too.
+		expect(cronMatches('*/0 9 * * *', mon0900)).toBe(true);
+	});
+
+	it('a list comma-separates alternatives (any part may match)', () => {
+		expect(cronMatches('0,30 9 * * *', mon0900)).toBe(true); // minute 0 is the first alternative
+		expect(cronMatches('15,30 9 * * *', mon0900)).toBe(false); // minute 0 is neither
+	});
+
+	it('rejects a range with a non-numeric bound (NaN bounds → that part never matches)', () => {
+		// "a-b" → lo/hi are NaN → the part is skipped; with no other alternative the field never matches.
+		expect(cronMatches('a-b 9 * * *', mon0900)).toBe(false);
+		// …but a sibling numeric alternative still matches around the bogus range.
+		expect(cronMatches('a-b,0 9 * * *', mon0900)).toBe(true);
+	});
 });
 
 describe('describeSchedule', () => {
diff --git a/client/src/lib/core/sensorActivity.test.ts b/client/src/lib/core/sensorActivity.test.ts
index 6c04e54..ed133d6 100644
--- a/client/src/lib/core/sensorActivity.test.ts
+++ b/client/src/lib/core/sensorActivity.test.ts
@@ -1,6 +1,11 @@
 import { describe, expect, it } from 'vitest';
-import { collectSensorRefs, isAlwaysOnSensor, sensorActivity } from './sensorActivity';
-import { container, leaf, type MonitorLayout } from './layoutTree';
+import {
+	collectSensorRefs,
+	isAlwaysOnSensor,
+	sensorActivity,
+	type SensorRef
+} from './sensorActivity';
+import { container, group, leaf, type Library, type MonitorLayout } from './layoutTree';
 
 const inst = (id: string, type: string, extra: Record<string, unknown> = {}) => ({
 	id,
@@ -74,6 +79,103 @@ describe('collectSensorRefs', () => {
 		expect(refs.get('mem.used.bytes')?.[0]).toMatchObject({ widgetType: 'text', via: 'formula' });
 		expect(refs.get('gpu.temp')?.[0].via).toBe('formula');
 	});
+
+	it('ignores a widget whose bound sensor is the empty string', () => {
+		// An empty bound `sensor` is treated as "no sensor" (the `if (inst.sensor)` guard in visit),
+		// so it contributes nothing.
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [leaf(inst('g', 'gauge', { sensor: '' }))]),
+			floating: []
+		};
+		expect(collectSensorRefs([{ key: 'default', layout: ml }]).size).toBe(0);
+	});
+
+	it('accumulates multiple widgets that reference the same sensor', () => {
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [
+				leaf(inst('a', 'gauge', { sensor: 'cpu.total' })),
+				leaf(inst('b', 'bar', { sensor: 'cpu.total' }))
+			]),
+			floating: []
+		};
+		const r = collectSensorRefs([{ key: 'default', layout: ml }]);
+		expect(r.get('cpu.total')).toHaveLength(2);
+		expect(r.get('cpu.total')?.map((x) => x.widgetId)).toEqual(['a', 'b']);
+	});
+
+	it('extracts refs from a NUMBER-result expr field (not just text templates)', () => {
+		// gauge's `value` field is kind:'expr', result:'number' → exprRefs(), not templateRefs().
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [
+				leaf(inst('g', 'gauge', { config: { value: 'round(gpu.power) + cpu.total' } }))
+			]),
+			floating: []
+		};
+		const r = collectSensorRefs([{ key: 'default', layout: ml }]);
+		expect(r.get('gpu.power')?.[0]).toMatchObject({ widgetType: 'gauge', via: 'formula' });
+		expect(r.get('cpu.total')?.[0].via).toBe('formula');
+	});
+
+	it('ignores a non-string or empty expr config value', () => {
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [
+				leaf(inst('g1', 'gauge', { config: { value: 42 } })), // non-string → skipped
+				leaf(inst('g2', 'gauge', { config: { value: '' } })) // empty string → skipped
+			]),
+			floating: []
+		};
+		expect(collectSensorRefs([{ key: 'default', layout: ml }]).size).toBe(0);
+	});
+
+	it('walks a floating leaf', () => {
+		const ml: MonitorLayout = {
+			root: container('r', 'col', []),
+			floating: [leaf(inst('f', 'gauge', { sensor: 'gpu.util' }))]
+		};
+		const r = collectSensorRefs([{ key: 'm', layout: ml }]);
+		expect(r.get('gpu.util')?.[0]).toMatchObject({ widgetId: 'f', monitorKey: 'm', via: 'bound' });
+	});
+
+	it('descends into an inline-child group leaf', () => {
+		const inner = container('gi', 'col', [leaf(inst('w', 'gauge', { sensor: 'disk.c.read' }))]);
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [leaf(group('grp', { w: 100, h: 60 }, inner))]),
+			floating: []
+		};
+		const r = collectSensorRefs([{ key: 'default', layout: ml }]);
+		expect(r.get('disk.c.read')?.[0].widgetId).toBe('w');
+	});
+
+	it('resolves a def-backed group through the library', () => {
+		const def = {
+			id: 'def1',
+			name: 'Disk',
+			size: { w: 100, h: 60 },
+			child: container('dc', 'col', [leaf(inst('dw', 'gauge', { sensor: 'gpu.temp' }))])
+		};
+		const library: Library = { version: 1, defs: [def] };
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [
+				leaf(group('grp', { w: 100, h: 60 }, container('placeholder', 'col', []), { def: 'def1' }))
+			]),
+			floating: []
+		};
+		const r = collectSensorRefs([{ key: 'default', layout: ml }], library);
+		expect(r.get('gpu.temp')?.[0].widgetId).toBe('dw');
+	});
+
+	it('safely handles a def-backed group whose def is missing from the library (no child)', () => {
+		const ml: MonitorLayout = {
+			root: container('r', 'col', [
+				leaf(group('grp', { w: 100, h: 60 }, container('placeholder', 'col', []), { def: 'ghost' }))
+			]),
+			floating: []
+		};
+		// def 'ghost' not in the (empty) library → child undefined → nothing collected, no throw.
+		expect(collectSensorRefs([{ key: 'default', layout: ml }], { version: 1, defs: [] }).size).toBe(
+			0
+		);
+	});
 });
 
 describe('sensorActivity', () => {
@@ -96,4 +198,20 @@ describe('sensorActivity', () => {
 		expect(sensorActivity('gpu.temp', undefined).active).toBe(false);
 		expect(sensorActivity('ha.light.x', undefined).active).toBe(false);
 	});
+
+	it('treats an empty refs array as unreferenced (falls through to the always-on / stops check)', () => {
+		// refs is defined but length 0 → the `refs.length` guard is false.
+		expect(sensorActivity('cpu.total', []).referenced).toBe(false);
+		expect(sensorActivity('gpu.temp', []).active).toBe(false);
+	});
+
+	it('de-duplicates repeated widget labels in the reason (formula labelled distinctly)', () => {
+		const refs: SensorRef[] = [
+			{ widgetType: 'gauge', widgetId: 'a', monitorKey: 'm', via: 'bound' },
+			{ widgetType: 'gauge', widgetId: 'b', monitorKey: 'm', via: 'bound' }, // dupe label → skipped
+			{ widgetType: 'gauge', widgetId: 'c', monitorKey: 'm', via: 'formula' } // distinct label
+		];
+		const a = sensorActivity('cpu.total', refs);
+		expect(a.reason).toBe('used by gauge, gauge (formula)');
+	});
 });
diff --git a/client/src/lib/core/solve.test.ts b/client/src/lib/core/solve.test.ts
index 7666bbe..65a7fd9 100644
--- a/client/src/lib/core/solve.test.ts
+++ b/client/src/lib/core/solve.test.ts
@@ -47,6 +47,85 @@ describe('intrinsicSize', () => {
 		const c = container('c', 'col', [leaf(prim('A', 50, 40)), leaf(prim('B', 80, 20))]);
 		expect(intrinsicSize(c)).toEqual({ w: 80, h: 60 });
 	});
+
+	it('a bare primitive leaf reports its own rect', () => {
+		expect(intrinsicSize(leaf(prim('A', 64, 24)))).toEqual({ w: 64, h: 24 });
+	});
+
+	it('an explicit `bounds` overrides the derived size on both axes', () => {
+		const c = container('c', 'col', [leaf(prim('A', 50, 40))], {
+			bounds: { x: 0, y: 0, w: 7, h: 9 }
+		});
+		expect(intrinsicSize(c)).toEqual({ w: 7, h: 9 });
+	});
+
+	it('an empty container collapses to just its padding', () => {
+		const c = container('c', 'col', [], { pad: { t: 3, r: 5, b: 7, l: 11 } });
+		// padAlong horizontal = l+r = 16, vertical = t+b = 10.
+		expect(intrinsicSize(c)).toEqual({ w: 16, h: 10 });
+	});
+
+	it('an overlap container is only as big as its largest child (plus pad)', () => {
+		const c = container('c', 'row', [leaf(prim('A', 50, 40)), leaf(prim('B', 80, 20))], {
+			overlap: true,
+			pad: 5
+		});
+		// max width 80 + 2*5, max height 40 + 2*5 — children share one box, not summed.
+		expect(intrinsicSize(c)).toEqual({ w: 90, h: 50 });
+	});
+
+	it('a group leaf reports its resolved def size as its intrinsic box', () => {
+		const lib: Library = {
+			version: 1,
+			defs: [{ id: 'cg', name: 'cg', size: { w: 40, h: 26 }, child: leaf(prim('spk', 1, 1)) }]
+		};
+		const g = leaf(group('g0', { w: 999, h: 999 }, leaf(prim('fb', 1, 1)), { def: 'cg' }));
+		// resolveGroup picks the def's size (40×26), not the inline 999×999.
+		expect(intrinsicSize(g, lib)).toEqual({ w: 40, h: 26 });
+	});
+
+	describe('grid intrinsic sizing', () => {
+		it('a uniform grid is cols × max-child-width + gaps wide, rows × max-child-height + gaps tall', () => {
+			// 2 cols, 2 children → 1 row. max child 30×20, gap 4.
+			const g = container('g', 'grid', [leaf(prim('A', 30, 20)), leaf(prim('B', 10, 10))], {
+				cols: 2,
+				gap: 4
+			});
+			// w = 30*2 + 4*(2-1) = 64 ; h = 20*1 + 4*0 = 20.
+			expect(intrinsicSize(g)).toEqual({ w: 64, h: 20 });
+		});
+
+		it('a bounds-less grid with no explicit cols defaults to a single track', () => {
+			// no cols → cols defaults to 1; 3 children → 3 rows.
+			const g = container('g', 'grid', [
+				leaf(prim('A', 30, 20)),
+				leaf(prim('B', 10, 10)),
+				leaf(prim('C', 10, 10))
+			]);
+			// w = max-child-width 30 * 1 col ; h = max-child-height 20 * 3 rows.
+			expect(intrinsicSize(g)).toEqual({ w: 30, h: 60 });
+		});
+
+		it('an explicit `rows` minimum grows the intrinsic height even with few children', () => {
+			const g = container('g', 'grid', [leaf(prim('A', 30, 20))], { cols: 1, rows: 3, gap: 2 });
+			// rows = max(3, ceil(1/1)) = 3 → h = 20*3 + 2*(3-1) = 64.
+			expect(intrinsicSize(g).h).toBe(64);
+		});
+
+		it('a grid with per-cell fixed widths sums each track (fixed size, else its largest child)', () => {
+			const c0 = container('c0', 'col', [leaf(prim('A', 5, 5))], { cellW: 100 });
+			const g = container('g', 'grid', [c0, leaf(prim('B', 30, 10))], { cols: 2, gap: 6 });
+			// track 0 fixed 100, track 1 = max child width 30 → w = 100 + 30 + 6*(2-1) = 136.
+			expect(intrinsicSize(g).w).toBe(136);
+		});
+
+		it('a grid with per-cell fixed heights sums each row track', () => {
+			const c0 = container('c0', 'col', [leaf(prim('A', 5, 5))], { cellH: 80 });
+			const g = container('g', 'grid', [c0, leaf(prim('B', 10, 40))], { cols: 1 });
+			// 1 col → 2 rows; row 0 fixed 80, row 1 = max child height 40 → h = 80 + 40 = 120.
+			expect(intrinsicSize(g).h).toBe(120);
+		});
+	});
 });
 
 // ---- groups (resolveGroup only — the solver-driven cases are gone) -------
@@ -135,6 +214,58 @@ describe('groups', () => {
 		expect((defChild.children[0] as Leaf).unit).toMatchObject({ config: { locale: 'en' } });
 	});
 
+	it('no def and no library: uses the inline child + size verbatim', () => {
+		const inline = leaf(prim('inl', 12, 8));
+		const r = resolveGroup(group('inst', { w: 12, h: 8 }, inline)); // no library arg at all
+		expect(r.size).toEqual({ w: 12, h: 8 });
+		expect((r.child as Leaf).id).toBe('inl');
+	});
+
+	it('a group with no resolvable child falls back to an empty col + zero size', () => {
+		// Bypass the constructor to model a malformed/empty group instance (no def, no inline child).
+		const grp = { id: 'g', kind: 'group' as const } as unknown as Parameters<
+			typeof resolveGroup
+		>[0];
+		const r = resolveGroup(grp);
+		expect(r.size).toEqual({ w: 0, h: 0 }); // grp.size missing → {w:0,h:0} fallback
+		const child = r.child as Container;
+		expect(child.kind).toBe('col');
+		expect(child.children).toEqual([]);
+		expect(child.id).toBe('g:empty');
+	});
+
+	it('inline child WITH params but NO def specs: applyParams is a no-op (no specs to drive)', () => {
+		const inline = leaf(prim('inl', 1, 1, { config: { core: 'orig' } }));
+		// def-less group carrying params; there are no ParamSpecs (those live on the def) → no writes.
+		const r = resolveGroup(group('inst', { w: 1, h: 1 }, inline, { params: { core: 'changed' } }));
+		expect(((r.child as Leaf).unit as WidgetInstance).config?.core).toBe('orig');
+	});
+
+	it('a spec whose key is absent from the instance params is skipped', () => {
+		const defChild = leaf(prim('spk', 10, 10, { config: { core: 'orig', label: 'orig' } }));
+		const def = {
+			id: 'd',
+			name: 'd',
+			size: { w: 40, h: 26 },
+			child: defChild,
+			params: [
+				{ key: 'core', target: 'unit.config.core' },
+				{ key: 'label', target: 'unit.config.label' } // this key is NOT supplied below
+			]
+		};
+		const lib: Library = { version: 1, defs: [def] };
+		const r = resolveGroup(
+			group('g', { w: 40, h: 26 }, leaf(prim('x', 1, 1)), {
+				def: 'd',
+				params: { core: 'cpu.7' } // only `core`; `label` absent → its spec is skipped
+			}),
+			lib
+		);
+		const unit = (r.child as Leaf).unit as WidgetInstance;
+		expect(unit.config?.core).toBe('cpu.7'); // applied
+		expect(unit.config?.label).toBe('orig'); // untouched (key not in params)
+	});
+
 	it('default param target is fail-closed on a container-rooted child (no bogus unit grafted)', () => {
 		const containerChild = container('inner', 'col', []);
 		const def = {
@@ -212,6 +343,70 @@ describe('collectRenderables', () => {
 		expect(spk?.instance.type).toBe('sparkline');
 		expect(rs.find((r) => r.id === 'g0')).toBeUndefined();
 	});
+
+	it('descends a group that sits IN THE FLOW TREE (not floating), namespacing + selecting it', () => {
+		const def = {
+			id: 'cg',
+			name: 'core-graph',
+			size: { w: 40, h: 26 },
+			child: leaf(prim('spk', 40, 26, { type: 'sparkline' }))
+		};
+		const lib: Library = { version: 1, defs: [def] };
+		// The group leaf lives inside the flow root (the `walk(monitor.root, …)` path), carrying its
+		// own `def` so defSel falls through to node.unit.def.
+		const g = group('gf', { w: 40, h: 26 }, leaf(prim('fb', 1, 1)), { def: 'cg' });
+		const root = container('root', 'col', [leaf(g)], { align: 'stretch' });
+		const mon: MonitorLayout = { root, floating: [] };
+		const solved: Solved = new Map([
+			['root', { x: 0, y: 0, w: 1000, h: 200 }],
+			['gf/spk', { x: 0, y: 0, w: 40, h: 26 }]
+		]);
+		const rs = collectRenderables(mon, solved, lib);
+		const spk = rs.find((r) => r.id === 'gf/spk');
+		expect(spk).toMatchObject({
+			selectId: 'gf', // the group is the selectable unit
+			movable: false, // flow-tree group descendants are never movable
+			groupId: 'gf',
+			defId: 'cg', // node.unit.def threads through as defSel
+			rect: { x: 0, y: 0, w: 40, h: 26 }
+		});
+		expect(spk?.instance.type).toBe('sparkline');
+	});
+
+	it('a FLOW-TREE group WITHOUT a def descends its inline child (no defId)', () => {
+		// node.unit.def is undefined → `defSel ?? node.unit.def ?? null` takes the trailing `?? null`.
+		const g = group('gn', { w: 30, h: 20 }, leaf(prim('inl', 30, 20, { type: 'text' })));
+		const root = container('root', 'col', [leaf(g)], { align: 'stretch' });
+		const mon: MonitorLayout = { root, floating: [] };
+		const solved: Solved = new Map([
+			['root', { x: 0, y: 0, w: 100, h: 100 }],
+			['gn/inl', { x: 1, y: 2, w: 30, h: 20 }]
+		]);
+		const rs = collectRenderables(mon, solved);
+		const inl = rs.find((r) => r.id === 'gn/inl');
+		expect(inl).toMatchObject({ selectId: 'gn', groupId: 'gn', movable: false });
+		expect(inl?.defId).toBeUndefined();
+	});
+
+	it('a FLOATING group WITHOUT a def resolves its inline child (defId omitted)', () => {
+		// No def → resolveGroup falls back to the inline child; `lf.unit.def ?? null` takes the null arm.
+		const g = group('gi', { w: 40, h: 26 }, leaf(prim('inl', 40, 26, { type: 'bar' })));
+		const mon: MonitorLayout = { root: container('root', 'col', []), floating: [leaf(g)] };
+		const solved: Solved = new Map([
+			['root', { x: 0, y: 0, w: 1000, h: 200 }],
+			['gi/inl', { x: 5, y: 6, w: 40, h: 26 }]
+		]);
+		const rs = collectRenderables(mon, solved);
+		const inl = rs.find((r) => r.id === 'gi/inl');
+		expect(inl).toMatchObject({
+			selectId: 'gi',
+			groupId: 'gi',
+			movable: false,
+			rect: { x: 5, y: 6, w: 40, h: 26 }
+		});
+		expect(inl?.defId).toBeUndefined(); // def-less group → no defId css hook
+		expect(inl?.instance.type).toBe('bar');
+	});
 });
 
 // ---- collectContainerRects -----------------------------------------------
@@ -356,6 +551,26 @@ describe('non-uniform grid (fixed cell width/height + aspect)', () => {
 		expect(cells[1]).toEqual({ x: 0, y: 50, w: 100, h: 150 });
 	});
 
+	it('a grid with no explicit cols lays out a single column per row', () => {
+		// cols omitted → 1; two children → two rows over a 100×200 box → two stacked 100×100 cells.
+		const grid = container('g', 'grid', [leaf(prim('A', 10, 10)), leaf(prim('B', 10, 10))]);
+		const cells = gridCellRects(grid, { x: 0, y: 0, w: 100, h: 200 });
+		expect(cells).toHaveLength(2);
+		expect(cells[0]).toEqual({ x: 0, y: 0, w: 100, h: 100 });
+		expect(cells[1]).toEqual({ x: 0, y: 100, w: 100, h: 100 });
+	});
+
+	it('when every column is fixed there is no flexible pool to split (tracks take their fixed px)', () => {
+		// Both columns carry a cellW → flexWeight is 0; each track is exactly its fixed width regardless
+		// of the box width (the box is wider than the fixed total).
+		const c0 = container('c0', 'col', [leaf(prim('A', 5, 5))], { cellW: 60 });
+		const c1 = container('c1', 'col', [leaf(prim('B', 5, 5))], { cellW: 40 });
+		const grid = container('g', 'grid', [c0, c1], { cols: 2 });
+		const cells = gridCellRects(grid, { x: 0, y: 0, w: 300, h: 100 });
+		expect(cells[0].w).toBe(60);
+		expect(cells[1].w).toBe(40);
+	});
+
 	it('a fixed column is untouched by colFr; only the FLEXIBLE rest is weighted', () => {
 		// col 0 fixed 100; cols 1,2 flexible with weights 1:3 over the remaining 200 → 50 / 150.
 		const c0 = container('c0', 'col', [leaf(prim('A', 10, 10))], { cellW: 100 });
@@ -409,6 +624,14 @@ describe('collectSplitters', () => {
 		expect(collectSplitters(mon, solved)).toHaveLength(0);
 	});
 
+	it('skips an fr↔fr pair when a child has no measured rect yet', () => {
+		const row = container('r', 'row', [frLeaf('a'), frLeaf('b')]);
+		const mon: MonitorLayout = { root: container('root', 'col', [row]), floating: [] };
+		// `b` is absent from the solved map (not yet measured) → the boundary can't be placed.
+		const solved: Solved = new Map([['a', { x: 0, y: 0, w: 100, h: 50 }]]);
+		expect(collectSplitters(mon, solved)).toHaveLength(0);
+	});
+
 	it('a col with three fr children yields two horizontal bars', () => {
 		const col = container('c', 'col', [frLeaf('a'), frLeaf('b'), frLeaf('d')]);
 		const mon: MonitorLayout = { root: col, floating: [] };
@@ -475,6 +698,28 @@ describe('collectSplitters — grid tracks', () => {
 		const solved: Solved = new Map([['g', { x: 0, y: 0, w: 200, h: 100 }]]);
 		expect(collectSplitters(mon, solved)).toHaveLength(0);
 	});
+
+	it('skips a row boundary whose TRAILING row track is fixed (cellH on the next row)', () => {
+		// 1 col × 2 rows; row 0 flexible, row 1 fixed (cellH). Boundary 0↔1: rowFixed[0] null (left arm
+		// false) but rowFixed[1] non-null (right arm true) → the boundary is skipped.
+		const r1 = container('r1', 'col', [leaf(prim('B', 10, 10))], { cellH: 40 });
+		const grid = container('g', 'grid', [leaf(prim('A', 10, 10)), r1], { cols: 1 });
+		const mon: MonitorLayout = { root: container('root', 'col', [grid]), floating: [] };
+		const solved: Solved = new Map([['g', { x: 0, y: 0, w: 100, h: 200 }]]);
+		expect(collectSplitters(mon, solved).filter((s) => s.track?.which === 'row')).toHaveLength(0);
+	});
+
+	it('a grid with no explicit cols (1-col default) and an explicit rows minimum yields row splitters', () => {
+		// cols omitted → 1; rows:3 minimum with 2 children → 3 row tracks → 2 row splitters, 0 col.
+		const grid = container('g', 'grid', [leaf(prim('A', 10, 10)), leaf(prim('B', 10, 10))], {
+			rows: 3
+		});
+		const mon: MonitorLayout = { root: container('root', 'col', [grid]), floating: [] };
+		const solved: Solved = new Map([['g', { x: 0, y: 0, w: 200, h: 300 }]]);
+		const sp = collectSplitters(mon, solved);
+		expect(sp.filter((s) => s.track?.which === 'col')).toHaveLength(0);
+		expect(sp.filter((s) => s.track?.which === 'row')).toHaveLength(2);
+	});
 });
 
 describe('resizeSplit', () => {
@@ -496,4 +741,22 @@ describe('resizeSplit', () => {
 		const { frA } = resizeSplit(100, 100, 1, 1, -500, { minPx: 16, snapPx: 0 });
 		expect(frA).toBeCloseTo((16 / 200) * 2, 2); // newA pinned to 16px
 	});
+
+	it('uses default snapPx/minPx when no opts are passed', () => {
+		// No opts arg → snapPx 14, minPx 16. delta +200 over 200px clamps A to total-minPx = 184.
+		const { frA, frB } = resizeSplit(100, 100, 1, 1, 200);
+		expect(frA + frB).toBeCloseTo(2);
+		// 184/200 = 0.92, within 14px of no snap; raw fraction 0.92 → frA = 0.92*2 = 1.84.
+		expect(frA).toBeCloseTo(1.84, 2);
+	});
+
+	it('returns the weights unchanged when the combined size is non-positive', () => {
+		// total = 0 → the divide-by-zero guard returns the inputs verbatim.
+		expect(resizeSplit(0, 0, 1, 1, 50)).toEqual({ frA: 1, frB: 1 });
+	});
+
+	it('returns the weights unchanged when the combined fr is non-positive', () => {
+		// combinedFr = 0 → same guard.
+		expect(resizeSplit(100, 100, 0, 0, 50)).toEqual({ frA: 0, frB: 0 });
+	});
 });
diff --git a/client/src/lib/core/style.test.ts b/client/src/lib/core/style.test.ts
index 552f8de..4425cee 100644
--- a/client/src/lib/core/style.test.ts
+++ b/client/src/lib/core/style.test.ts
@@ -56,6 +56,23 @@ describe('assembleStyles', () => {
 		expect(css.indexOf('[data-def=')).toBeLessThan(css.indexOf('[data-w="flowA"'));
 	});
 
+	it('collects css of widgets nested INSIDE a group (recurses the group child tree)', () => {
+		// A group is a leaf in its parent tree but owns a nested child tree; its inner widgets' css must
+		// still be assembled, scoped to each inner [data-w] — in flow AND floating groups. Regression:
+		// the demoSeed now-playing widget (a floating group) rendered unstyled (two covers) because the
+		// inner leaf's crossfade css was skipped.
+		const monitor: MonitorLayout = {
+			root: container('root', 'col', [
+				leaf(group('gFlow', { w: 1, h: 1 }, leaf(prim('deep', 'color: red')), {}))
+			]),
+			floating: [leaf(group('gFloat', { w: 1, h: 1 }, leaf(prim('floatDeep', 'opacity: 0')), {}))]
+		};
+		const css = assembleStyles({ monitor });
+		// Inner ids are namespaced by the group leaf id + '/', matching FlowNode's rendered data-w.
+		expect(css).toContain(scopeCss('color: red', '[data-w="gFlow/deep"]'));
+		expect(css).toContain(scopeCss('opacity: 0', '[data-w="gFloat/floatDeep"]'));
+	});
+
 	it('scopes per-widget token overrides to [data-w], before that widget css', () => {
 		const w: WidgetInstance = {
 			id: 'w1',
diff --git a/client/src/lib/core/style.ts b/client/src/lib/core/style.ts
index fe32921..39f3b29 100644
--- a/client/src/lib/core/style.ts
+++ b/client/src/lib/core/style.ts
@@ -58,22 +58,32 @@ export function assembleStyles(opts: {
 		if (s) parts.push(s);
 	}
 
-	const leafCss = (lf: Leaf): void => {
-		const sel = isGroup(lf.unit) ? `[data-group="${lf.id}"]` : `[data-w="${lf.id}"]`;
+	const leafCss = (lf: Leaf, prefix: string): void => {
+		const fullId = prefix + lf.id;
+		const sel = isGroup(lf.unit) ? `[data-group="${fullId}"]` : `[data-w="${fullId}"]`;
 		const tk = lf.unit.tokens;
 		if (tk && Object.keys(tk).length) parts.push(tokensToCss(tk, sel));
 		const s = scopeCss(lf.unit.css, sel);
 		if (s) parts.push(s);
 	};
-	const walk = (node: LayoutNode): void => {
+	const walk = (node: LayoutNode, prefix: string): void => {
 		if (isContainer(node)) {
-			node.children.forEach(walk);
+			node.children.forEach((c) => walk(c, prefix));
 			return;
 		}
-		if (isLeaf(node)) leafCss(node);
+		if (isLeaf(node)) {
+			leafCss(node, prefix);
+			// A group is a leaf here but owns a NESTED child tree whose widgets render with ids
+			// NAMESPACED by the group leaf id + '/' (FlowNode's prefixing — the load-bearing data-id
+			// invariant). Recurse with that same prefix so the inner css scopes to the [data-w] those
+			// widgets ACTUALLY render with — without this, anything inside a group (incl. the demoSeed
+			// templates) renders unstyled (e.g. a now-playing widget showing two stacked covers).
+			if (isGroup(node.unit)) walk(node.unit.child, `${prefix}${node.id}/`);
+		}
 	};
-	walk(opts.monitor.root);
-	opts.monitor.floating.forEach(leafCss);
+	walk(opts.monitor.root, '');
+	// Floating items can be groups too — walk (not just leafCss) so their nested widgets are collected.
+	opts.monitor.floating.forEach((lf) => walk(lf, ''));
 
 	return parts.join('\n');
 }
diff --git a/client/src/lib/core/telemetry.test.ts b/client/src/lib/core/telemetry.test.ts
index 1601dd8..c211469 100644
--- a/client/src/lib/core/telemetry.test.ts
+++ b/client/src/lib/core/telemetry.test.ts
@@ -33,6 +33,93 @@ describe('appendSample', () => {
 		);
 		expect(s.history).toEqual([3]);
 	});
+
+	it('keeps history ordered by ts_ms when samples arrive out of order (backfill)', () => {
+		let s = emptySensorState();
+		for (const t of [3, 1, 2]) {
+			s = appendSample(s, { sensor: 'x', ts_ms: t, value: { kind: 'scalar', value: t } }, 10);
+		}
+		expect(s.history).toEqual([1, 2, 3]);
+		expect(s.historyTs).toEqual([1, 2, 3]);
+		// `value` stays the most-recently-INGESTED sample (live current value), not the latest ts.
+		expect(s.value).toEqual({ kind: 'scalar', value: 2 });
+	});
+
+	it('merges back-dated backfill ahead of existing live samples, then appends fresh ones', () => {
+		let s = emptySensorState();
+		s = appendSample(s, { sensor: 'x', ts_ms: 100, value: { kind: 'scalar', value: 5 } }, 10);
+		s = appendSample(s, { sensor: 'x', ts_ms: 10, value: { kind: 'scalar', value: 1 } }, 10);
+		s = appendSample(s, { sensor: 'x', ts_ms: 20, value: { kind: 'scalar', value: 2 } }, 10);
+		s = appendSample(s, { sensor: 'x', ts_ms: 200, value: { kind: 'scalar', value: 9 } }, 10);
+		expect(s.history).toEqual([1, 2, 5, 9]);
+		expect(s.historyTs).toEqual([10, 20, 100, 200]);
+	});
+
+	it('caps to the most-recent-by-ts after ordering', () => {
+		let s = emptySensorState();
+		for (const t of [5, 4, 3, 2, 1]) {
+			s = appendSample(s, { sensor: 'x', ts_ms: t, value: { kind: 'scalar', value: t } }, 3);
+		}
+		expect(s.history).toEqual([3, 4, 5]);
+		expect(s.historyTs).toEqual([3, 4, 5]);
+	});
+
+	it('zero-fills the ts of a LEGACY state that has history but no historyTs', () => {
+		// Older snapshots lack historyTs; the reducer must zero-fill it (oldest) to stay in lockstep with
+		// history. A fresh ts ≥ 0 then appends after those zeros.
+		const legacy = { value: { kind: 'scalar', value: 1 } as const, history: [1, 2] }; // no historyTs
+		const s = appendSample(
+			legacy,
+			{ sensor: 'x', ts_ms: 5, value: { kind: 'scalar', value: 3 } },
+			10
+		);
+		expect(s.history).toEqual([1, 2, 3]);
+		expect(s.historyTs).toEqual([0, 0, 5]); // legacy points back-filled to ts 0
+	});
+
+	it('zero-fills when historyTs length is out of sync with history', () => {
+		// A mismatched-length historyTs is treated as missing (defensive) → rebuilt as zeros.
+		const desynced = { value: null, history: [7, 8, 9], historyTs: [100] };
+		const s = appendSample(
+			desynced,
+			{ sensor: 'x', ts_ms: 200, value: { kind: 'scalar', value: 10 } },
+			10
+		);
+		expect(s.history).toEqual([7, 8, 9, 10]);
+		expect(s.historyTs).toEqual([0, 0, 0, 200]);
+	});
+
+	it('drops history entirely when historyLen <= 0 (keeps only the latest value)', () => {
+		const s = appendSample(
+			emptySensorState(),
+			{ sensor: 'x', ts_ms: 1, value: { kind: 'scalar', value: 42 } },
+			0
+		);
+		expect(s.history).toEqual([]);
+		expect(s.historyTs).toEqual([]);
+		expect(s.value).toEqual({ kind: 'scalar', value: 42 });
+	});
+
+	it('treats an EMPTY series sample as non-numeric (no history point)', () => {
+		const s = appendSample(
+			emptySensorState(),
+			{ sensor: 'x', ts_ms: 1, value: { kind: 'series', value: [] } },
+			10
+		);
+		expect(s.history).toEqual([]);
+		expect(s.value).toEqual({ kind: 'series', value: [] });
+	});
+
+	it('treats a json sample as non-numeric (latest value kept, history untouched)', () => {
+		let s = appendSample(
+			emptySensorState(),
+			{ sensor: 'x', ts_ms: 1, value: { kind: 'scalar', value: 5 } },
+			10
+		);
+		s = appendSample(s, { sensor: 'x', ts_ms: 2, value: { kind: 'json', value: { a: 1 } } }, 10);
+		expect(s.history).toEqual([5]); // unchanged by the non-numeric json sample
+		expect(s.value).toEqual({ kind: 'json', value: { a: 1 } });
+	});
 });
 
 describe('createTelemetryHub', () => {
@@ -123,6 +210,21 @@ describe('active-sensor tracking (demand-gating)', () => {
 		expect(changes).toBe(2);
 	});
 
+	it('calling a sensor unsubscribe twice is a no-op (no extra onActiveChange)', () => {
+		const hub = createTelemetryHub();
+		let changes = 0;
+		hub.onActiveChange(() => changes++);
+
+		const off = hub.sensor('gpu.fan').subscribe(() => undefined);
+		expect(changes).toBe(1);
+		off(); // last listener gone → 1→0 transition
+		expect(hub.activeSensorIds()).toEqual([]);
+		expect(changes).toBe(2);
+		off(); // already removed → the `!set.delete(cb)` guard returns early, no further notify
+		expect(changes).toBe(2);
+		expect(hub.activeSensorIds()).toEqual([]);
+	});
+
 	it('onActiveChange unsubscribe stops further notifications', () => {
 		const hub = createTelemetryHub();
 		let changes = 0;
diff --git a/client/src/lib/core/telemetry.ts b/client/src/lib/core/telemetry.ts
index c416181..40a0043 100644
--- a/client/src/lib/core/telemetry.ts
+++ b/client/src/lib/core/telemetry.ts
@@ -12,13 +12,21 @@ export type SensorValue =
 export type SensorSample = { sensor: string; ts_ms: number; value: SensorValue };
 export type TelemetryBatch = SensorSample[];
 
-export type SensorState = { value: SensorValue | null; history: number[] };
+// `historyTs` runs parallel to `history` (same length): the ts_ms of each retained sample, kept so
+// ingest can stay ORDER-STABLE BY TIME. It's optional so existing `{ value, history }` literals (and
+// older snapshots) still type-check; when absent it's treated as empty / zero-filled. Consumers that
+// only chart values read `history` and can ignore it.
+export type SensorState = { value: SensorValue | null; history: number[]; historyTs?: number[] };
 
 // A single frozen empty state, shared so `getSnapshot()` is referentially stable
 // before any sample arrives (required for React's useSyncExternalStore).
-const EMPTY: SensorState = Object.freeze({ value: null, history: [] }) as SensorState;
+const EMPTY: SensorState = Object.freeze({
+	value: null,
+	history: [],
+	historyTs: []
+}) as SensorState;
 
-export const emptySensorState = (): SensorState => ({ value: null, history: [] });
+export const emptySensorState = (): SensorState => ({ value: null, history: [], historyTs: [] });
 
 /** The numeric component of a sample for history/sparklines, or null if non-numeric. */
 function numericOf(value: SensorValue): number | null {
@@ -27,17 +35,42 @@ function numericOf(value: SensorValue): number | null {
 	return null;
 }
 
-/** Pure reducer: apply a sample to a sensor's state, capping history at `historyLen`. */
+/** Pure reducer: apply a sample to a sensor's state, capping history at `historyLen`. Keeps the
+ * series ORDER-STABLE BY `ts_ms` so back-dated samples (history backfill) merge into the right place
+ * instead of being appended out of order. The common live case (ts ≥ the last sample) is a plain
+ * append; only an earlier ts triggers an insertion-sort, so steady-state ingest stays O(1). */
 export function appendSample(
 	state: SensorState,
 	sample: SensorSample,
 	historyLen: number
 ): SensorState {
+	// Keep ts in lockstep with history length even for legacy states that lacked it (zero-fill = oldest).
+	const ts0 =
+		state.historyTs && state.historyTs.length === state.history.length
+			? state.historyTs
+			: state.history.map(() => 0);
 	const n = numericOf(sample.value);
-	if (n === null) return { value: sample.value, history: state.history };
-	const next = [...state.history, n];
-	const history = historyLen > 0 ? next.slice(-historyLen) : [];
-	return { value: sample.value, history };
+	if (n === null) return { value: sample.value, history: state.history, historyTs: ts0 };
+	if (historyLen <= 0) return { value: sample.value, history: [], historyTs: [] };
+
+	const ts = sample.ts_ms;
+	let history: number[];
+	let historyTs: number[];
+	if (ts0.length === 0 || ts >= ts0[ts0.length - 1]) {
+		history = [...state.history, n];
+		historyTs = [...ts0, ts];
+	} else {
+		// First index whose ts is greater than this sample's → insert before it (after equal ts, stable).
+		let i = ts0.length;
+		while (i > 0 && ts0[i - 1] > ts) i--;
+		history = [...state.history.slice(0, i), n, ...state.history.slice(i)];
+		historyTs = [...ts0.slice(0, i), ts, ...ts0.slice(i)];
+	}
+	if (history.length > historyLen) {
+		history = history.slice(-historyLen);
+		historyTs = historyTs.slice(-historyLen);
+	}
+	return { value: sample.value, history, historyTs };
 }
 
 /** A minimal notify-based observable — consumable by Svelte stores and React alike. */
diff --git a/client/src/lib/core/templates.test.ts b/client/src/lib/core/templates.test.ts
index 55a6602..d578a1f 100644
--- a/client/src/lib/core/templates.test.ts
+++ b/client/src/lib/core/templates.test.ts
@@ -1,17 +1,25 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 import {
+	BUILTIN_TEMPLATE_GROUP,
 	TEMPLATES,
 	demoSeed,
 	freshIds,
 	getTemplate,
 	instantiateTemplate,
+	listTemplateGroups,
+	registerTemplates,
 	resolveTemplateOptions,
+	subscribeTemplates,
+	unregisterTemplates,
 	type Template
 } from './templates';
 import {
+	container,
+	group,
 	isContainer,
 	isGroup,
 	isLeaf,
+	leaf,
 	type Container,
 	type LayoutNode,
 	type Leaf,
@@ -242,3 +250,131 @@ describe('demoSeed (the default skin = the templates, single source of truth)',
 		expect(new Set([...a, ...b]).size).toBe(a.length + b.length);
 	});
 });
+
+describe('getTemplate', () => {
+	it('returns undefined for an unknown id', () => {
+		expect(getTemplate('does-not-exist')).toBeUndefined();
+	});
+});
+
+describe('freshIds (group leaf)', () => {
+	it('remaps a leaf whose unit is a GROUP with a group-* id (not the unit type)', () => {
+		// The clock-jp trees only carry primitive leaves, so the group-unit arm of freshIds needs a leaf
+		// that wraps a GROUP unit. Its fresh id must use the `group-` prefix and the leaf id mirrors it.
+		const g = group('g-orig', { w: 50, h: 50 }, container('c', 'col', []), { name: 'Wrapped' });
+		const out = freshIds(leaf(g));
+		if (!isLeaf(out) || !isGroup(out.unit)) throw new Error('expected a group leaf');
+		expect(out.unit.id).toMatch(/^group-/);
+		expect(out.unit.id).not.toBe('g-orig');
+		expect(out.id).toBe(out.unit.id); // leaf id mirrors the unit id
+		expect(out.unit.name).toBe('Wrapped'); // non-id fields survive
+	});
+});
+
+describe('resolveTemplateOptions (non-select params)', () => {
+	// A synthetic template exercising the param-without-choices skip and the undefined-default fallback —
+	// the built-in templates only carry select params, so these arms need a hand-built spec.
+	const tpl: Template = {
+		id: 'synthetic',
+		name: 'Synthetic',
+		description: '',
+		size: { w: 10, h: 10 },
+		params: [
+			{ key: 'note', label: 'Note', default: 'x', target: 'a' }, // no `choices` → skipped (not a select)
+			{ key: 'pick', label: 'Pick', target: 'b', choices: [{ value: 'one', label: 'One' }] } // no default
+		],
+		tree: () => leaf({ id: 'w', type: 'text', rect: { x: 0, y: 0, w: 10, h: 10 }, config: {} })
+	};
+
+	it('skips params with no choices and defaults a choice-param with no `default` to an empty string', () => {
+		// 'note' (no choices) is dropped entirely; 'pick' (choices, no default) → '' (the `?? ''` fallback).
+		expect(resolveTemplateOptions(tpl)).toEqual({ pick: '' });
+		// A valid override for the select still takes; the non-select is still skipped.
+		expect(resolveTemplateOptions(tpl, { pick: 'one', note: 'ignored' })).toEqual({ pick: 'one' });
+	});
+});
+
+describe('template registry (register / unregister / list / subscribe)', () => {
+	const PLUGIN_GROUP = 'Test Plugin';
+	const sample: Template = {
+		id: 'plugin-widget',
+		name: 'Plugin Widget',
+		description: '',
+		size: { w: 20, h: 20 },
+		tree: () => leaf({ id: 'pw', type: 'text', rect: { x: 0, y: 0, w: 20, h: 20 }, config: {} })
+	};
+
+	afterEach(() => {
+		// Module-level registry state — always clean up so tests stay independent.
+		unregisterTemplates(PLUGIN_GROUP);
+	});
+
+	it('lists exactly the built-in group when nothing is registered (stable identity between calls)', () => {
+		const a = listTemplateGroups();
+		const b = listTemplateGroups();
+		expect(a).toBe(b); // cached snapshot — referentially stable
+		expect(a).toEqual([{ group: BUILTIN_TEMPLATE_GROUP, templates: TEMPLATES }]);
+	});
+
+	it('registering a group appends it after the built-ins, notifies, and invalidates the snapshot', () => {
+		let notified = 0;
+		const unsub = subscribeTemplates(() => notified++);
+		const before = listTemplateGroups();
+
+		registerTemplates(PLUGIN_GROUP, [sample]);
+		expect(notified).toBe(1);
+		const after = listTemplateGroups();
+		expect(after).not.toBe(before); // snapshot rebuilt after the change
+		expect(after[0].group).toBe(BUILTIN_TEMPLATE_GROUP); // built-ins stay first
+		expect(after.find((g) => g.group === PLUGIN_GROUP)?.templates).toEqual([sample]);
+
+		unsub();
+	});
+
+	it('copies the registered list (later caller mutation does not leak into the registry)', () => {
+		const list = [sample];
+		registerTemplates(PLUGIN_GROUP, list);
+		list.push({ ...sample, id: 'extra' }); // mutate the caller's array after registering
+		expect(listTemplateGroups().find((g) => g.group === PLUGIN_GROUP)?.templates).toEqual([sample]);
+	});
+
+	it('getTemplate finds a template contributed by a registered group (loop continues past built-ins)', () => {
+		expect(getTemplate('plugin-widget')).toBeUndefined();
+		registerTemplates(PLUGIN_GROUP, [sample]);
+		expect(getTemplate('plugin-widget')).toBe(sample);
+	});
+
+	it('the built-in group cannot be overwritten or removed', () => {
+		registerTemplates(BUILTIN_TEMPLATE_GROUP, []); // ignored
+		expect(getTemplate('system')).toBeTruthy();
+		unregisterTemplates(BUILTIN_TEMPLATE_GROUP); // ignored
+		expect(listTemplateGroups()[0]).toEqual({
+			group: BUILTIN_TEMPLATE_GROUP,
+			templates: TEMPLATES
+		});
+	});
+
+	it('unregistering a group notifies once; unregistering an unknown group is a silent no-op', () => {
+		let notified = 0;
+		const unsub = subscribeTemplates(() => notified++);
+
+		registerTemplates(PLUGIN_GROUP, [sample]);
+		expect(notified).toBe(1);
+		unregisterTemplates(PLUGIN_GROUP);
+		expect(notified).toBe(2);
+		expect(listTemplateGroups().some((g) => g.group === PLUGIN_GROUP)).toBe(false);
+
+		unregisterTemplates('never-registered'); // delete() returns false → no notify
+		expect(notified).toBe(2);
+
+		unsub();
+	});
+
+	it('subscribe returns an unsubscribe that stops further notifications', () => {
+		let notified = 0;
+		const unsub = subscribeTemplates(() => notified++);
+		unsub();
+		registerTemplates(PLUGIN_GROUP, [sample]);
+		expect(notified).toBe(0);
+	});
+});
diff --git a/client/src/lib/core/textTemplate.test.ts b/client/src/lib/core/textTemplate.test.ts
index 22958a8..9ac1aa2 100644
--- a/client/src/lib/core/textTemplate.test.ts
+++ b/client/src/lib/core/textTemplate.test.ts
@@ -32,6 +32,17 @@ describe('parseTemplate', () => {
 		expect(parseTemplate('{ {a: 1}.a }')).toEqual([{ kind: 'expr', src: '{a: 1}.a' }]);
 	});
 
+	it('keeps an escaped quote inside an expr string literal (escape + char both retained)', () => {
+		// The backslash-escaped quote must NOT end the string early — both the \ and the quote
+		// stay in the expr src, and the brace that follows the real closing quote still closes it.
+		expect(parseTemplate(`{ 'a\\'b' }`)).toEqual([{ kind: 'expr', src: `'a\\'b'` }]);
+		expect(parseTemplate(`pre { "x\\"}y" } post`)).toEqual([
+			{ kind: 'text', text: 'pre ' },
+			{ kind: 'expr', src: `"x\\"}y"` },
+			{ kind: 'text', text: ' post' }
+		]);
+	});
+
 	it('returns plain text unchanged', () => {
 		expect(parseTemplate('just text')).toEqual([{ kind: 'text', text: 'just text' }]);
 	});
@@ -46,6 +57,38 @@ describe('exprRefs / templateRefs', () => {
 		expect(exprRefs(`'cpu.total' + net.down`)).toEqual(['net.down']);
 	});
 
+	it('ignores ids written inside double-quoted string literals', () => {
+		expect(exprRefs('"cpu.total" + net.down')).toEqual(['net.down']);
+	});
+
+	it('ignores ids written inside template (backtick) literals', () => {
+		expect(exprRefs('`cpu.total` + net.down')).toEqual(['net.down']);
+	});
+
+	it('tolerates an unterminated string literal (runs to end of source)', () => {
+		// The string never closes, so the strip loop exhausts the source (the `i < length` guard,
+		// not the closing quote, ends it). cpu.total inside the open string is still ignored.
+		expect(exprRefs("net.down + 'cpu.total")).toEqual(['net.down']);
+	});
+
+	it('tolerates a trailing open-quote (the strip loop exits before testing the char)', () => {
+		// The opening quote is the LAST char: after stepping past it i === length, so the inner
+		// `src[i] !== quote` is never evaluated (the `i < length` guard short-circuits).
+		expect(exprRefs("net.down + '")).toEqual(['net.down']);
+	});
+
+	it('honours backslash escapes inside a string so an escaped quote does not end it early', () => {
+		// The \' is skipped as one unit; the string only closes at the real trailing quote, so the
+		// cpu.total written AFTER the escaped quote is still inside the string and ignored.
+		expect(exprRefs("net.down + 'a\\'cpu.total'")).toEqual(['net.down']);
+	});
+
+	it('returns [] when an expression has no dotted sensor chains', () => {
+		// match() returns null here (no `a.b` chains at all) → the `?? []` fallback.
+		expect(exprRefs('42 + 7')).toEqual([]);
+		expect(exprRefs('round(x)')).toEqual([]);
+	});
+
 	it('filters to known ids when a catalog is supplied', () => {
 		expect(exprRefs('mem.used + bogus.sensor', ['mem.used', 'cpu.total'])).toEqual(['mem.used']);
 	});
diff --git a/client/src/lib/core/weather.test.ts b/client/src/lib/core/weather.test.ts
index 0f56c51..4fab148 100644
--- a/client/src/lib/core/weather.test.ts
+++ b/client/src/lib/core/weather.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { weatherInfo, forecastDayLabel, labelForecast } from './weather';
+import { weatherInfo, forecastDayLabel, labelForecast, type WeatherInfo } from './weather';
 
 describe('weatherInfo', () => {
 	it('maps representative WMO codes to a label', () => {
@@ -21,6 +21,48 @@ describe('weatherInfo', () => {
 	it('falls back for an unknown code', () => {
 		expect(weatherInfo(999)).toEqual({ label: '—', icon: '❓' });
 	});
+
+	it('maps every WMO 4677 code group to its label + day icon', () => {
+		// One representative per case arm (covers the fall-through groups too).
+		const expected: Record<number, WeatherInfo> = {
+			0: { label: 'Clear', icon: '☀️' },
+			1: { label: 'Mainly clear', icon: '🌤️' },
+			2: { label: 'Partly cloudy', icon: '⛅' },
+			3: { label: 'Overcast', icon: '☁️' },
+			45: { label: 'Fog', icon: '🌫️' },
+			48: { label: 'Fog', icon: '🌫️' },
+			51: { label: 'Drizzle', icon: '🌦️' },
+			53: { label: 'Drizzle', icon: '🌦️' },
+			55: { label: 'Drizzle', icon: '🌦️' },
+			56: { label: 'Freezing drizzle', icon: '🌧️' },
+			57: { label: 'Freezing drizzle', icon: '🌧️' },
+			61: { label: 'Rain', icon: '🌧️' },
+			63: { label: 'Rain', icon: '🌧️' },
+			65: { label: 'Rain', icon: '🌧️' },
+			66: { label: 'Freezing rain', icon: '🌧️' },
+			67: { label: 'Freezing rain', icon: '🌧️' },
+			71: { label: 'Snow', icon: '🌨️' },
+			73: { label: 'Snow', icon: '🌨️' },
+			75: { label: 'Snow', icon: '🌨️' },
+			77: { label: 'Snow grains', icon: '🌨️' },
+			80: { label: 'Rain showers', icon: '🌦️' },
+			81: { label: 'Rain showers', icon: '🌦️' },
+			82: { label: 'Rain showers', icon: '🌦️' },
+			85: { label: 'Snow showers', icon: '🌨️' },
+			86: { label: 'Snow showers', icon: '🌨️' },
+			95: { label: 'Thunderstorm', icon: '⛈️' },
+			96: { label: 'Thunderstorm + hail', icon: '⛈️' },
+			99: { label: 'Thunderstorm + hail', icon: '⛈️' }
+		};
+		for (const [code, info] of Object.entries(expected)) {
+			expect(weatherInfo(Number(code)), code).toEqual(info);
+		}
+	});
+
+	it('uses the night cloud glyph for partly-cloudy at night (code 2)', () => {
+		expect(weatherInfo(2, false)).toEqual({ label: 'Partly cloudy', icon: '☁️' });
+		expect(weatherInfo(1, false).icon).toBe('🌙');
+	});
 });
 
 describe('forecastDayLabel', () => {
diff --git a/client/src/lib/core/widget.test.ts b/client/src/lib/core/widget.test.ts
index f64d52a..0bcb074 100644
--- a/client/src/lib/core/widget.test.ts
+++ b/client/src/lib/core/widget.test.ts
@@ -3,6 +3,7 @@ import {
 	BUILTIN_METAS,
 	configCompleteness,
 	createWidget,
+	exprFieldsOf,
 	getMeta,
 	listMetas,
 	registerMeta
@@ -74,7 +75,8 @@ describe('meta registry', () => {
 			'note',
 			'spacer',
 			'countdown',
-			'timer'
+			'timer',
+			'monitorswitch'
 		]);
 		expect(getMeta('gauge')).toMatchObject({ label: 'Gauge', binds: 'scalar' });
 		expect(getMeta('sparkline')?.binds).toBe('series');
@@ -103,6 +105,122 @@ describe('meta registry', () => {
 		expect(w).toMatchObject({ type: 'demo.widget', sensor: 'demo.x', config: { k: 1 } });
 		expect(w.rect).toMatchObject({ w: 50, h: 60 });
 	});
+
+	it('seeds defaultCss into the instance when the meta declares it', () => {
+		registerMeta({
+			type: 'demo.styled',
+			label: 'Styled',
+			defaultSize: { w: 40, h: 40 },
+			defaultCss: '.x { color: red; }'
+		});
+		const w = createWidget('demo.styled', 's1');
+		expect(w.css).toBe('.x { color: red; }');
+	});
+});
+
+describe('meta.sensors (config → named sensor ids)', () => {
+	const sensorsOf = (type: string, config: Record<string, unknown> = {}) => {
+		const fn = getMeta(type)?.sensors;
+		expect(fn).toBeTypeOf('function');
+		return fn!(config);
+	};
+
+	it('battery binds the fixed battery.* family', () => {
+		expect(sensorsOf('battery')).toEqual({
+			percent: 'battery.percent',
+			state: 'battery.state',
+			time: 'battery.time'
+		});
+	});
+
+	it('gpu binds the fixed gpu.* family', () => {
+		expect(sensorsOf('gpu')).toEqual({
+			util: 'gpu.util',
+			name: 'gpu.name',
+			temp: 'gpu.temp',
+			vramUsed: 'gpu.vram.used',
+			vramTotal: 'gpu.vram.total',
+			power: 'gpu.power',
+			clock: 'gpu.clock.core',
+			fan: 'gpu.fan'
+		});
+	});
+
+	it('wifi binds the fixed net.wifi.* family', () => {
+		expect(sensorsOf('wifi')).toEqual({
+			ssid: 'net.wifi.ssid',
+			signal: 'net.wifi.signal',
+			rssi: 'net.wifi.rssi',
+			rx: 'net.wifi.rx',
+			tx: 'net.wifi.tx',
+			band: 'net.wifi.band',
+			channel: 'net.wifi.channel',
+			phy: 'net.wifi.phy'
+		});
+	});
+
+	it('recyclebin binds the fixed recyclebin.* family', () => {
+		expect(sensorsOf('recyclebin')).toEqual({
+			items: 'recyclebin.items',
+			bytes: 'recyclebin.bytes'
+		});
+	});
+
+	it('topproc derives proc.<by>.top.* from config.by (default cpu)', () => {
+		expect(sensorsOf('topproc')).toEqual({
+			name: 'proc.cpu.top.name',
+			value: 'proc.cpu.top.pct'
+		});
+		expect(sensorsOf('topproc', { by: 'mem' })).toEqual({
+			name: 'proc.mem.top.name',
+			value: 'proc.mem.top.bytes'
+		});
+	});
+
+	it('procwatch derives proc.watch.<name>.* from config.name (default chrome.exe)', () => {
+		expect(sensorsOf('procwatch')).toEqual({
+			running: 'proc.watch.chrome.exe.running',
+			cpu: 'proc.watch.chrome.exe.cpu',
+			mem: 'proc.watch.chrome.exe.mem',
+			count: 'proc.watch.chrome.exe.count'
+		});
+		expect(sensorsOf('procwatch', { name: 'obs64.exe' }).running).toBe(
+			'proc.watch.obs64.exe.running'
+		);
+	});
+
+	it('ping derives net.ping.<host>.* from config.host (default 1.1.1.1)', () => {
+		expect(sensorsOf('ping')).toEqual({ ms: 'net.ping.1.1.1.1.ms', up: 'net.ping.1.1.1.1.up' });
+		expect(sensorsOf('ping', { host: 'cloudflare.com' })).toEqual({
+			ms: 'net.ping.cloudflare.com.ms',
+			up: 'net.ping.cloudflare.com.up'
+		});
+	});
+});
+
+describe('exprFieldsOf', () => {
+	it('returns [] for an undefined meta', () => {
+		expect(exprFieldsOf(undefined)).toEqual([]);
+	});
+
+	it('returns [] for a meta with no formula fields', () => {
+		expect(exprFieldsOf(getMeta('clock'))).toEqual([]);
+	});
+
+	it('extracts expr fields and defaults target to the key', () => {
+		// gauge has value (text→number, no target → key), minExpr (target:'min'), maxExpr (target:'max')
+		expect(exprFieldsOf(getMeta('gauge'))).toEqual([
+			{ key: 'value', result: 'number', target: 'value' },
+			{ key: 'minExpr', result: 'number', target: 'min' },
+			{ key: 'maxExpr', result: 'number', target: 'max' }
+		]);
+	});
+
+	it('carries the text result kind (the text meter template)', () => {
+		expect(exprFieldsOf(getMeta('text'))).toEqual([
+			{ key: 'value', result: 'text', target: 'value' }
+		]);
+	});
 });
 
 describe('configCompleteness (UI-driven config guard)', () => {
diff --git a/client/src/lib/core/widget.ts b/client/src/lib/core/widget.ts
index 159c56a..3147acf 100644
--- a/client/src/lib/core/widget.ts
+++ b/client/src/lib/core/widget.ts
@@ -50,7 +50,12 @@ export type ConfigField =
 	// A macro field: an ordered list of {domain, service, data?} action calls (core/macro.ts), edited
 	// as rows in the inspector and run in sequence when the widget is pressed. The value is a
 	// MacroAction[]; the side-effecting dispatch lives in Canvas.onWidgetControl (domain 'macro').
-	| ({ key: string; label: string; kind: 'macro' } & FieldMeta);
+	| ({ key: string; label: string; kind: 'macro' } & FieldMeta)
+	// A monitor-sources field (the Monitor Switch widget): a friendly checklist of the chosen monitor's
+	// detected DDC inputs — pick which to show and optionally rename each. The value is the same
+	// `code=label` spec string `text` would hold (core/monitorInputs); the editor just builds it. The
+	// inspector renders MonitorSourcesEditor (it detects inputs via a Tauri command — studio-only).
+	| ({ key: string; label: string; kind: 'monitorSources' } & FieldMeta);
 
 export type SensorKind = 'scalar' | 'series' | 'text' | 'json' | 'none';
 
@@ -437,7 +442,7 @@ export const BUILTIN_METAS: WidgetMeta[] = [
 		description:
 			'Pressable button that runs a macro of {domain, service, data} calls (HA services or media transport).',
 		binds: 'none',
-		label: 'Button',
+		label: 'Button / Macro',
 		category: 'Utility',
 		defaultSize: { w: 90, h: 44 },
 		defaultConfig: { label: 'tap', actions: [] },
@@ -1037,6 +1042,57 @@ export const BUILTIN_METAS: WidgetMeta[] = [
 			text('label', 'label', { help: 'header text' }),
 			color('color', 'color', { help: 'text colour (blank = theme)' })
 		]
+	},
+	{
+		// Monitor input-source switcher (binds:'none', interactive): switches a monitor's active input
+		// (HDMI / DisplayPort / …) over DDC/CI (VCP 0x60). Bespoke wiring lives in MonitorSwitchHost
+		// (ddc.rs commands); the meter stays props-only. interactive:true so the rows catch clicks on the
+		// passive overlay. DDC/CI must be enabled in the OSD; input codes are vendor-specific (auto-detected).
+		type: 'monitorswitch',
+		description:
+			'Switch a monitor’s input source (HDMI / DisplayPort / …) with a tap, over DDC/CI. Shows the current source and, optionally, the resolution + refresh rate. Requires DDC/CI enabled on the monitor; input codes are vendor-specific (auto-detected). Windows.',
+		binds: 'none',
+		interactive: true,
+		label: 'Monitor Switch',
+		category: 'Utility',
+		defaultSize: { w: 220, h: 150 },
+		defaultConfig: { showCurrent: true, showStats: false, compact: false },
+		configFields: [
+			{
+				key: 'monitor',
+				label: 'monitor',
+				kind: 'select',
+				options: [],
+				catalog: 'displayNames',
+				help: 'which monitor to control (blank = the primary monitor)'
+			},
+			{
+				key: 'sources',
+				label: 'sources',
+				kind: 'monitorSources',
+				help: 'pick which inputs to show, and rename them (e.g. HDMI 2 → Switch 2); blank = show all detected'
+			},
+			text('label', 'label', { help: 'title override (blank = the monitor’s name)' }),
+			{
+				key: 'showCurrent',
+				label: 'show current',
+				kind: 'toggle',
+				help: 'highlight the currently-selected input'
+			},
+			{
+				key: 'showStats',
+				label: 'show stats',
+				kind: 'toggle',
+				help: 'show the current resolution + refresh rate'
+			},
+			{
+				key: 'compact',
+				label: 'compact list',
+				kind: 'toggle',
+				help: 'show a compact list instead of large touch buttons'
+			},
+			color('color', 'accent')
+		]
 	}
 ];
 
diff --git a/client/src/lib/ddc/monitors.ts b/client/src/lib/ddc/monitors.ts
new file mode 100644
index 0000000..a414077
--- /dev/null
+++ b/client/src/lib/ddc/monitors.ts
@@ -0,0 +1,46 @@
+// Outer-ring adapter (AGENTS.md §5) for the Monitor Switch widget: list monitors with their current /
+// supported DDC input + display mode, and switch the input. Tauri lives here, never in the meter or
+// core/. Command names mirror widgetsack/src/ddc.rs; `MonitorInputs` mirrors the Rust struct of the
+// same name.
+
+import { invoke } from '@tauri-apps/api/core';
+import { COMMANDS } from '../bridge/contract';
+
+/** One monitor's input-switching state. Mirrors `MonitorInputs` in widgetsack/src/ddc.rs. Keyed by
+ *  `gdi` (`\\.\DISPLAYn`). `currentInput` / `supported` are DDC/CI (VCP 0x60) and only filled for the
+ *  queried target; `width`/`height`/`refreshHz` are the OS display mode (0 if unknown). */
+export type MonitorInputs = {
+	gdi: string;
+	friendly: string;
+	primary: boolean;
+	current_input: number | null;
+	supported: number[];
+	width: number;
+	height: number;
+	refresh_hz: number;
+};
+
+/** All monitors; DDC (current/supported) is filled only for `target` (a GDI device name) — or the
+ *  primary monitor when omitted. Empty list off-Windows / on failure. */
+export async function listMonitorInputs(target?: string): Promise<MonitorInputs[]> {
+	try {
+		return (
+			(await invoke<MonitorInputs[]>(COMMANDS.listMonitorInputs, { target: target ?? null })) ?? []
+		);
+	} catch (err) {
+		console.warn('list_monitor_inputs failed', err);
+		return [];
+	}
+}
+
+/** Switch `target` (a GDI device name) to VCP 0x60 input `value`. Resolves true on success, false on
+ *  failure (DDC/CI off, monitor not found, or an unsupported value) so the host can roll back. */
+export async function setMonitorInput(target: string, value: number): Promise<boolean> {
+	try {
+		await invoke(COMMANDS.setMonitorInput, { target, value });
+		return true;
+	} catch (err) {
+		console.warn('set_monitor_input failed', err);
+		return false;
+	}
+}
diff --git a/client/src/lib/devMock.ts b/client/src/lib/devMock.ts
index 8861137..2388322 100644
--- a/client/src/lib/devMock.ts
+++ b/client/src/lib/devMock.ts
@@ -76,6 +76,10 @@ export function installDevMock(opts: { layout?: string } = {}): void {
 			case COMMANDS.autostartSet:
 				return false;
 
+			// --- dev / multi instance badge: the e2e mock is a normal (non-dev, non-multi) instance ---
+			case COMMANDS.isDevInstance:
+				return false;
+
 			// --- app update check: pretend we're current ---
 			case COMMANDS.checkAppUpdate:
 				return {
diff --git a/client/src/lib/formula/engine.initfail.test.ts b/client/src/lib/formula/engine.initfail.test.ts
new file mode 100644
index 0000000..44f7c94
--- /dev/null
+++ b/client/src/lib/formula/engine.initfail.test.ts
@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+// Drive initFormulaEngine's failure path (the `.catch` that logs and leaves the engine not-ready)
+// by making the WASM module loader reject. Isolated in its OWN file so the module mock + the
+// engine singleton it builds on don't bleed into engine.test.ts (which uses the real runtime).
+vi.mock('quickjs-emscripten-core', () => ({
+	newQuickJSWASMModuleFromVariant: vi.fn(async () => {
+		throw new Error('wasm boom');
+	})
+}));
+vi.mock('@jitl/quickjs-singlefile-browser-release-sync', () => ({ default: {} }));
+
+describe('initFormulaEngine — load failure', () => {
+	afterEach(() => vi.restoreAllMocks());
+
+	it('logs and stays not-ready when the WASM module fails to load (never rejects)', async () => {
+		const err = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+		const { initFormulaEngine, isFormulaEngineReady, evalExpr } = await import('./engine');
+		// must RESOLVE (the catch swallows the rejection) rather than throw
+		await expect(initFormulaEngine()).resolves.toBeUndefined();
+		expect(isFormulaEngineReady()).toBe(false);
+		expect(evalExpr('1 + 1', {})).toBeNull(); // not-ready guard
+		expect(err).toHaveBeenCalledWith('[formula] engine init failed', expect.any(Error));
+	});
+});
diff --git a/client/src/lib/formula/engine.test.ts b/client/src/lib/formula/engine.test.ts
index 06d62b5..17aa3cd 100644
--- a/client/src/lib/formula/engine.test.ts
+++ b/client/src/lib/formula/engine.test.ts
@@ -3,7 +3,8 @@ import {
 	__disposeFormulaEngine,
 	evalExpr,
 	initFormulaEngine,
-	isFormulaEngineReady
+	isFormulaEngineReady,
+	onFormulaEngineReady
 } from './engine';
 import { TEMPLATE_FUNCTIONS } from '../core/templateFns';
 
@@ -70,4 +71,60 @@ describe('formula engine', () => {
 		// A later eval that doesn't provide cpu must not see the previous 99.
 		expect(evalExpr('typeof cpu', {})).toBe('undefined');
 	});
+
+	it('stringifies a boolean result', () => {
+		expect(evalExpr('cpu.total > 50', { 'cpu.total': 75 })).toBe('true');
+		expect(evalExpr('cpu.total > 50', { 'cpu.total': 10 })).toBe('false');
+	});
+
+	it('returns null for a non-number/string/boolean result (object / array / undefined)', () => {
+		expect(evalExpr('({ a: 1 })', {})).toBeNull();
+		expect(evalExpr('[1, 2, 3]', {})).toBeNull();
+		expect(evalExpr('undefined', {})).toBeNull();
+	});
+
+	it('omits a null sensor value (treated as absent) so a bare ref yields null, not 0', () => {
+		// cpu.total is null → omitted from scope → bare reference throws (caught) → null, NOT 0.
+		expect(evalExpr('cpu.total', { 'cpu.total': null })).toBeNull();
+		// a present sensor alongside a null one still resolves.
+		expect(evalExpr('mem.used + 1', { 'mem.used': 4, 'cpu.total': null })).toBe(5);
+	});
+});
+
+describe('onFormulaEngineReady', () => {
+	it('returns an unsubscribe that removes the listener (no double-fire, no leak)', async () => {
+		// The engine is already ready (beforeAll), so a fresh subscriber won't be called by a future
+		// transition — but subscribe/unsubscribe must still add then drop the listener cleanly.
+		let calls = 0;
+		const off = onFormulaEngineReady(() => {
+			calls += 1;
+		});
+		off(); // unsubscribe
+		// Re-init is idempotent (cached promise) and does not re-run listeners.
+		await initFormulaEngine();
+		expect(calls).toBe(0);
+	});
+
+	it('fires registered ready listeners when init transitions from cold', async () => {
+		__disposeFormulaEngine(); // clears the cached promise + listeners
+		expect(isFormulaEngineReady()).toBe(false);
+		let fired = false;
+		const off = onFormulaEngineReady(() => {
+			fired = true;
+		});
+		await initFormulaEngine();
+		expect(fired).toBe(true);
+		expect(isFormulaEngineReady()).toBe(true);
+		off();
+	});
+});
+
+describe('evalExpr before init', () => {
+	it('returns null when the engine is not ready (no ctx/runtime), then restores', async () => {
+		__disposeFormulaEngine();
+		expect(isFormulaEngineReady()).toBe(false);
+		expect(evalExpr('1 + 1', {})).toBeNull(); // the !ctx || !runtime guard
+		await initFormulaEngine(); // restore so afterAll's dispose has something to tear down
+		expect(isFormulaEngineReady()).toBe(true);
+	});
 });
diff --git a/client/src/lib/formula/packageSandbox.initfail.test.ts b/client/src/lib/formula/packageSandbox.initfail.test.ts
new file mode 100644
index 0000000..da6233f
--- /dev/null
+++ b/client/src/lib/formula/packageSandbox.initfail.test.ts
@@ -0,0 +1,21 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Drive createPackageSandbox's init-failure path (the runtime can't be built) by making the shared
+// WASM module loader reject. Isolated in its own file so the module mock doesn't bleed into
+// packageSandbox.test.ts (which uses the real runtime).
+vi.mock('./engine', () => ({
+	loadQuickJSModule: vi.fn(async () => {
+		throw new Error('wasm load boom');
+	})
+}));
+
+describe('createPackageSandbox — init failure', () => {
+	it('returns { ok:false, error } (never throws) when the runtime cannot be built', async () => {
+		const { createPackageSandbox } = await import('./packageSandbox');
+		const r = await createPackageSandbox(`module.exports = { requests(){}, transform(){} };`);
+		expect(r.ok).toBe(false);
+		if (r.ok) return;
+		expect(r.error).toContain('sandbox init failed');
+		expect(r.error).toContain('wasm load boom');
+	});
+});
diff --git a/client/src/lib/formula/packageSandbox.test.ts b/client/src/lib/formula/packageSandbox.test.ts
new file mode 100644
index 0000000..71d2508
--- /dev/null
+++ b/client/src/lib/formula/packageSandbox.test.ts
@@ -0,0 +1,197 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { __disposeFormulaEngine, initFormulaEngine } from './engine';
+import { createPackageSandbox, type SandboxResponse } from './packageSandbox';
+
+// The package sandbox builds its runtime from the SAME shared WASM module as the formula engine,
+// so prime that load once up front and tear it down after (engine.ts owns the module cache).
+beforeAll(async () => {
+	await initFormulaEngine();
+});
+afterAll(() => __disposeFormulaEngine());
+
+// A well-formed source.js: returns two https URLs from requests(), maps the bodies in transform().
+const GOOD_SCRIPT = `
+module.exports = {
+	requests: function () { return ['https://a.example/1', 'https://b.example/2']; },
+	transform: function (responses) {
+		return responses.map(function (r) {
+			return { sensor: 'status.' + r.status, value: r.body.length };
+		});
+	}
+};
+`;
+
+describe('createPackageSandbox', () => {
+	it('compiles a valid source and round-trips requests() / transform() as JSON', async () => {
+		const r = await createPackageSandbox(GOOD_SCRIPT);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const sb = r.sandbox;
+
+		const req = sb.requests();
+		expect(req).toEqual({ ok: true, value: ['https://a.example/1', 'https://b.example/2'] });
+
+		const responses: SandboxResponse[] = [
+			{ url: 'https://a.example/1', status: 200, body: 'hello' },
+			{ url: 'https://b.example/2', status: 404, body: 'no' }
+		];
+		const out = sb.transform(responses);
+		expect(out).toEqual({
+			ok: true,
+			value: [
+				{ sensor: 'status.200', value: 5 },
+				{ sensor: 'status.404', value: 2 }
+			]
+		});
+		sb.dispose();
+	});
+
+	it('rejects a script that never assigns the two required functions', async () => {
+		const r = await createPackageSandbox(
+			`module.exports = { requests: function () { return []; } };`
+		);
+		expect(r.ok).toBe(false);
+		if (r.ok) return;
+		expect(r.error).toContain('module.exports = { requests, transform }');
+	});
+
+	it('rejects a script that throws at compile time (the compile eval reports the error)', async () => {
+		const r = await createPackageSandbox(`throw new Error('compile go boom');`);
+		expect(r.ok).toBe(false);
+		if (r.ok) return;
+		expect(r.error).toContain('compile go boom');
+	});
+
+	it('surfaces a thrown Error from requests() as { ok:false, error } with the message', async () => {
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { throw new Error('no network plan'); },
+				transform: function () { return []; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const out = r.sandbox.requests();
+		expect(out.ok).toBe(false);
+		if (out.ok) return;
+		expect(out.error).toContain('no network plan');
+		r.sandbox.dispose();
+	});
+
+	it('reports "error" for a thrown object without a message (the ?? fallback)', async () => {
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { throw { code: 7 }; },
+				transform: function () { return []; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		// dumped error is an object with no .message → `err.message ?? 'error'` → "error".
+		expect(r.sandbox.requests()).toEqual({ ok: false, error: 'error' });
+		r.sandbox.dispose();
+	});
+
+	it('stringifies a thrown primitive (non-object error) verbatim', async () => {
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { throw 'plain string'; },
+				transform: function () { return []; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		// a thrown string dumps to a primitive → the ternary's `: err` arm → String(err).
+		expect(r.sandbox.requests()).toEqual({ ok: false, error: 'plain string' });
+		r.sandbox.dispose();
+	});
+
+	it('reports "returned malformed JSON" when a hostile script poisons JSON.stringify', async () => {
+		// The host wraps each call in `JSON.stringify(__src.xxx())`; a script that globally replaces
+		// JSON.stringify with a non-JSON producer trips the inner JSON.parse guard.
+		const r = await createPackageSandbox(`
+			JSON.stringify = function () { return 'NOT JSON'; };
+			module.exports = {
+				requests: function () { return []; },
+				transform: function () { return []; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.sandbox.requests()).toEqual({ ok: false, error: 'returned malformed JSON' });
+		r.sandbox.dispose();
+	});
+
+	it('reports "returned no JSON-serializable value" when a call yields undefined', async () => {
+		// transform returns undefined → JSON.stringify(undefined) is `undefined` (not a string).
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { return []; },
+				transform: function () { return undefined; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const out = r.sandbox.transform([]);
+		expect(out).toEqual({ ok: false, error: 'returned no JSON-serializable value' });
+		r.sandbox.dispose();
+	});
+
+	it('injects responses as inert DATA — a hostile body cannot escape into code', async () => {
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { return []; },
+				transform: function (responses) { return [{ sensor: 's', value: responses[0].body }]; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		// A body that looks like code stays a plain string.
+		const out = r.sandbox.transform([
+			{ url: 'https://x', status: 200, body: '"); globalThis.PWNED = 1; ("' }
+		]);
+		expect(out).toEqual({
+			ok: true,
+			value: [{ sensor: 's', value: '"); globalThis.PWNED = 1; ("' }]
+		});
+		r.sandbox.dispose();
+	});
+
+	it('kills a runaway transform() via the per-call deadline', async () => {
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { return []; },
+				transform: function () { while (true) {} }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const out = r.sandbox.transform([]);
+		expect(out.ok).toBe(false);
+		r.sandbox.dispose();
+	});
+
+	it('is sandboxed — host globals (fetch / process) are not reachable', async () => {
+		const r = await createPackageSandbox(`
+			module.exports = {
+				requests: function () { return [typeof fetch, typeof process]; },
+				transform: function () { return []; }
+			};
+		`);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		expect(r.sandbox.requests()).toEqual({ ok: true, value: ['undefined', 'undefined'] });
+		r.sandbox.dispose();
+	});
+
+	it('returns "sandbox disposed" once dispose() has run, and dispose is idempotent', async () => {
+		const r = await createPackageSandbox(GOOD_SCRIPT);
+		expect(r.ok).toBe(true);
+		if (!r.ok) return;
+		const sb = r.sandbox;
+		sb.dispose();
+		sb.dispose(); // second dispose is a no-op (must not throw / double-free)
+		expect(sb.requests()).toEqual({ ok: false, error: 'sandbox disposed' });
+		expect(sb.transform([])).toEqual({ ok: false, error: 'sandbox disposed' });
+	});
+});
diff --git a/client/src/lib/llm/source.test.ts b/client/src/lib/llm/source.test.ts
new file mode 100644
index 0000000..b0b5c46
--- /dev/null
+++ b/client/src/lib/llm/source.test.ts
@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Outer-ring Tauri adapter for streamed LLM tokens. We mock @tauri-apps/api/event's `listen` and the
+// store's pure `handleDelta` so the reference-counting + attach race can be exercised without a Tauri
+// runtime or a real store. Module-level refcount state is reset per test via vi.resetModules() +
+// dynamic import.
+
+const handleDelta = vi.fn();
+vi.mock('../../stores/llmStore', () => ({ handleDelta: (...a: unknown[]) => handleDelta(...a) }));
+
+// `listen` is reconfigured per test. By default it resolves immediately to a spy unlisten fn.
+const unlistenSpy = vi.fn();
+let listen: ReturnType<typeof vi.fn>;
+vi.mock('@tauri-apps/api/event', () => ({ listen: (...a: unknown[]) => listen(...a) }));
+
+type Source = typeof import('./source');
+const load = async (): Promise<Source> => {
+	vi.resetModules();
+	return import('./source');
+};
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	unlistenSpy.mockClear();
+	listen = vi.fn(() => Promise.resolve(unlistenSpy));
+});
+afterEach(() => vi.restoreAllMocks());
+
+describe('startLlmSource', () => {
+	it('exposes the llm_delta event name from the bridge contract', async () => {
+		const mod = await load();
+		expect(mod.LLM_DELTA_EVENT).toBe('llm_delta');
+	});
+
+	it('attaches one listener that folds each delta into the store via the reducer', async () => {
+		const mod = await load();
+		const stop = await mod.startLlmSource();
+		expect(listen).toHaveBeenCalledTimes(1);
+		expect(listen.mock.calls[0][0]).toBe('llm_delta');
+
+		// Drive the registered handler with a frame → it forwards the payload to handleDelta.
+		const handler = listen.mock.calls[0][1] as (ev: { payload: unknown }) => void;
+		handler({ payload: { id: 'r1', text: 'hi' } });
+		expect(handleDelta).toHaveBeenCalledWith({ id: 'r1', text: 'hi' });
+
+		stop();
+		expect(unlistenSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('reference-counts: the listener attaches once and detaches only when the last consumer stops', async () => {
+		const mod = await load();
+		const stopA = await mod.startLlmSource();
+		const stopB = await mod.startLlmSource();
+		// Second consumer reuses the live listener — no second attach.
+		expect(listen).toHaveBeenCalledTimes(1);
+
+		stopA();
+		expect(unlistenSpy).not.toHaveBeenCalled(); // B still holds a ref
+		stopB();
+		expect(unlistenSpy).toHaveBeenCalledTimes(1); // last consumer → detach
+	});
+
+	it('per-call stop fn is idempotent (a double-stop does not over-decrement)', async () => {
+		const mod = await load();
+		const stopA = await mod.startLlmSource();
+		const stopB = await mod.startLlmSource();
+		stopA();
+		stopA(); // idempotent: must NOT release B's ref
+		expect(unlistenSpy).not.toHaveBeenCalled();
+		stopB();
+		expect(unlistenSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('reuses the in-flight attach: a second consumer started mid-attach does not re-listen', async () => {
+		// Defer the listen() resolution so a second consumer arrives while the attach is in flight.
+		let resolveListen: (u: () => void) => void = () => undefined;
+		listen = vi.fn(() => new Promise<() => void>((res) => (resolveListen = res)));
+
+		const mod = await load();
+		const p1 = mod.startLlmSource(); // refs = 1, attach in flight
+		const p2 = mod.startLlmSource(); // refs = 2, sees `attaching` → shares it, no 2nd listen()
+		expect(listen).toHaveBeenCalledTimes(1);
+
+		resolveListen(unlistenSpy);
+		const [stop1, stop2] = await Promise.all([p1, p2]);
+		// Still one listener; it detaches only after BOTH stop.
+		stop1();
+		expect(unlistenSpy).not.toHaveBeenCalled();
+		stop2();
+		expect(unlistenSpy).toHaveBeenCalledTimes(1);
+	});
+
+	it('keeps running silently when there is no Tauri runtime (listen rejects)', async () => {
+		listen = vi.fn(() => Promise.reject(new Error('no tauri')));
+		const mod = await load();
+		const stop = await mod.startLlmSource();
+		// No listener attached, but the stop fn is still safe to call.
+		expect(() => stop()).not.toThrow();
+		expect(unlistenSpy).not.toHaveBeenCalled();
+	});
+});
diff --git a/client/src/lib/llm/useLlmChat.test.ts b/client/src/lib/llm/useLlmChat.test.ts
index a4b4781..81480b5 100644
--- a/client/src/lib/llm/useLlmChat.test.ts
+++ b/client/src/lib/llm/useLlmChat.test.ts
@@ -1,19 +1,29 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { act, renderHook, waitFor } from '@testing-library/react';
 
-// llm_stream rejects (the real-world "AI provider not configured" / backend error case). The hook
-// must NOT leave the opened assistant turn streaming forever — it should surface the error.
+// llm_stream defaults to rejecting (the real-world "AI provider not configured" / backend error
+// case). The hook must NOT leave the opened assistant turn streaming forever — it should surface the
+// error. Individual tests override llmStream via vi.mocked for the happy path.
 vi.mock('../widgets/plugins/llm-commands', () => ({
 	llmStream: vi.fn(() => Promise.reject('AI provider not configured')),
 	llmCancel: vi.fn()
 }));
-// No Tauri in the test: the delta source is a no-op unlisten.
-vi.mock('./source', () => ({ startLlmSource: () => Promise.resolve(() => undefined) }));
+// No Tauri in the test: the delta source is a no-op unlisten by default; individual tests override
+// startLlmSource via vi.mocked to exercise the unmount-before-listen race and the stop-on-unmount path.
+vi.mock('./source', () => ({
+	startLlmSource: vi.fn(() => Promise.resolve(() => undefined))
+}));
 
 import { useLlmChat } from './useLlmChat';
 import { resetChat } from '../../stores/llmStore';
+import { llmCancel, llmStream } from '../widgets/plugins/llm-commands';
+import { startLlmSource } from './source';
 
-beforeEach(() => resetChat());
+beforeEach(() => {
+	resetChat();
+	// Default: the delta source resolves immediately to a no-op stop fn (mount keeps the ref alive).
+	vi.mocked(startLlmSource).mockImplementation(() => Promise.resolve(() => undefined));
+});
 afterEach(() => vi.clearAllMocks());
 
 describe('useLlmChat', () => {
@@ -31,4 +41,83 @@ describe('useLlmChat', () => {
 			expect(assistant?.error).toContain('AI provider not configured');
 		});
 	});
+
+	it('opens a user turn + a streaming assistant turn and sends the prior transcript', async () => {
+		vi.mocked(llmStream).mockResolvedValueOnce(undefined);
+		const { result } = renderHook(() => useLlmChat());
+
+		let requestId = '';
+		await act(async () => {
+			requestId = await result.current.send('  hi there  ');
+		});
+
+		// The user turn carries the trimmed text; the assistant turn (id === requestId) is streaming.
+		const turns = result.current.chat.turns;
+		expect(turns.map((t) => t.role)).toEqual(['user', 'assistant']);
+		expect(turns[0].content).toBe('hi there');
+		expect(turns[1].id).toBe(requestId);
+		expect(turns[1].streaming).toBe(true);
+
+		// llm_stream got the request id + the prior transcript (the empty assistant turn filtered out).
+		expect(llmStream).toHaveBeenCalledWith(requestId, [{ role: 'user', content: 'hi there' }]);
+	});
+
+	it('ignores blank input (no turn opened, no stream started)', async () => {
+		const { result } = renderHook(() => useLlmChat());
+
+		let requestId = 'unset';
+		await act(async () => {
+			requestId = await result.current.send('   ');
+		});
+
+		expect(requestId).toBe('');
+		expect(result.current.chat.turns).toHaveLength(0);
+		expect(llmStream).not.toHaveBeenCalled();
+	});
+
+	it('cancel() forwards the request id to llm_cancel', () => {
+		const { result } = renderHook(() => useLlmChat());
+		act(() => result.current.cancel('chat-7'));
+		expect(llmCancel).toHaveBeenCalledWith('chat-7');
+	});
+
+	it('reset() clears the transcript', async () => {
+		vi.mocked(llmStream).mockResolvedValueOnce(undefined);
+		const { result } = renderHook(() => useLlmChat());
+		await act(async () => {
+			await result.current.send('hello');
+		});
+		expect(result.current.chat.turns.length).toBeGreaterThan(0);
+		act(() => result.current.reset());
+		expect(result.current.chat.turns).toHaveLength(0);
+	});
+
+	it('stops the delta source if it resolves AFTER unmount (no leaked listener)', async () => {
+		const stop = vi.fn();
+		let resolve: (fn: () => void) => void = () => undefined;
+		// Defer the source promise so unmount happens before startLlmSource resolves.
+		vi.mocked(startLlmSource).mockImplementationOnce(
+			() => new Promise<() => void>((res) => (resolve = res))
+		);
+		const { unmount } = renderHook(() => useLlmChat());
+		unmount(); // cancelled = true before the source resolves
+		await act(async () => {
+			resolve(stop); // late resolution: the effect must call stop immediately
+			await Promise.resolve();
+		});
+		expect(stop).toHaveBeenCalledTimes(1);
+	});
+
+	it('stops the delta source on a normal unmount', async () => {
+		const stop = vi.fn();
+		vi.mocked(startLlmSource).mockImplementationOnce(() => Promise.resolve(stop));
+		const { unmount } = renderHook(() => useLlmChat());
+		// Let the (immediately-resolving) source settle so `stop` is captured.
+		await act(async () => {
+			await Promise.resolve();
+		});
+		expect(stop).not.toHaveBeenCalled();
+		unmount();
+		expect(stop).toHaveBeenCalledTimes(1);
+	});
 });
diff --git a/client/src/lib/logs.test.ts b/client/src/lib/logs.test.ts
new file mode 100644
index 0000000..ab7c2fb
--- /dev/null
+++ b/client/src/lib/logs.test.ts
@@ -0,0 +1,67 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Outer-ring Tauri adapter for the backend structured log stream (widgetsack/src/log.rs). We mock
+// @tauri-apps/api's `invoke`/`listen` so the backlog fetch + live-stream subscription can be
+// exercised without a Tauri runtime. The module is re-imported per test so the mocks bind cleanly.
+
+const invoke = vi.fn();
+const listen = vi.fn();
+vi.mock('@tauri-apps/api/core', () => ({ invoke: (...a: unknown[]) => invoke(...a) }));
+vi.mock('@tauri-apps/api/event', () => ({ listen: (...a: unknown[]) => listen(...a) }));
+
+type Logs = typeof import('./logs');
+const load = async (): Promise<Logs> => {
+	vi.resetModules();
+	return import('./logs');
+};
+
+const sample = (
+	over: Partial<import('./core/logs').LogRecord> = {}
+): import('./core/logs').LogRecord => ({
+	ts_ms: 1_700_000_000_000,
+	level: 'info',
+	target: 'sensors',
+	message: 'hello',
+	...over
+});
+
+beforeEach(() => vi.clearAllMocks());
+afterEach(() => vi.restoreAllMocks());
+
+describe('getLogs', () => {
+	it('invokes get_logs and resolves the backlog', async () => {
+		const backlog = [sample(), sample({ level: 'warn', message: 'careful' })];
+		invoke.mockResolvedValueOnce(backlog);
+		const { getLogs } = await load();
+		await expect(getLogs()).resolves.toEqual(backlog);
+		expect(invoke).toHaveBeenCalledWith('get_logs');
+	});
+
+	it('resolves to an empty array when the command rejects', async () => {
+		invoke.mockRejectedValueOnce(new Error('backend down'));
+		const { getLogs } = await load();
+		await expect(getLogs()).resolves.toEqual([]);
+	});
+});
+
+describe('subscribeLogs', () => {
+	it('listens on the log event and forwards each payload to the callback', async () => {
+		const unlisten = vi.fn();
+		listen.mockResolvedValueOnce(unlisten);
+		const cb = vi.fn();
+		const { subscribeLogs } = await load();
+		const stop = await subscribeLogs(cb);
+
+		expect(listen).toHaveBeenCalledTimes(1);
+		expect(listen.mock.calls[0][0]).toBe('log');
+
+		// Drive the registered handler with an event → the bare payload reaches the callback.
+		const handler = listen.mock.calls[0][1] as (ev: { payload: unknown }) => void;
+		const record = sample({ target: 'bridge', message: 'connected' });
+		handler({ payload: record });
+		expect(cb).toHaveBeenCalledWith(record);
+
+		// returns the unlisten fn straight through
+		expect(stop).toBe(unlisten);
+	});
+});
diff --git a/client/src/lib/overlay.ts b/client/src/lib/overlay.ts
index ca8d6aa..0996a86 100644
--- a/client/src/lib/overlay.ts
+++ b/client/src/lib/overlay.ts
@@ -299,6 +299,50 @@ export async function fillOwnMonitor(key: string): Promise<void> {
 	}
 }
 
+/** Poll interval for the display-topology watcher. Relaxed — display changes are rare and a few
+ * seconds of lag before overlays re-fit is fine (the tray "Re-fit overlays" gives an instant trigger). */
+const DISPLAY_POLL_MS = 4000;
+
+/** Watch for DISPLAY TOPOLOGY changes (monitors added / removed / moved / resized) and call `onChange`.
+ * Windows fires no per-window JS event for this (only DPI scale-change is exposed via onScaleChanged),
+ * so poll `availableMonitors()` on a relaxed cadence + on window focus and fire when the set of monitor
+ * geometries differs from the last seen. Cheap (one fast call per tick). Returns a cleanup fn. Without
+ * this, overlays go stale on a topology change — e.g. dragging a monitor in Windows display settings
+ * leaves an overlay anchored to the old coordinates (clipped/misaligned) until the app restarts. */
+export function watchDisplayChanges(onChange: () => void): () => void {
+	const sig = (mons: Awaited<ReturnType<typeof availableMonitors>>): string =>
+		mons
+			.map(
+				(m) =>
+					`${m.name ?? ''}:${m.position.x},${m.position.y}:${m.size.width}x${m.size.height}@${
+						m.scaleFactor
+					}`
+			)
+			.sort()
+			.join('|');
+	let last: string | null = null;
+	let alive = true;
+	const tick = async (): Promise<void> => {
+		if (!alive) return;
+		try {
+			const s = sig(await availableMonitors());
+			if (last !== null && s !== last) onChange();
+			last = s;
+		} catch {
+			/* transient enumeration failure — retry next tick */
+		}
+	};
+	void tick(); // seed `last` without firing
+	const timer = window.setInterval(() => void tick(), DISPLAY_POLL_MS);
+	const onFocus = (): void => void tick();
+	window.addEventListener('focus', onFocus);
+	return () => {
+		alive = false;
+		window.clearInterval(timer);
+		window.removeEventListener('focus', onFocus);
+	};
+}
+
 /** Whole-window click-through: true = clicks pass through (passive overlay). */
 export async function setClickThrough(enabled: boolean): Promise<void> {
 	await getCurrentWindow().setIgnoreCursorEvents(enabled);
diff --git a/client/src/lib/stt.test.ts b/client/src/lib/stt.test.ts
index aae9c98..2aa2211 100644
--- a/client/src/lib/stt.test.ts
+++ b/client/src/lib/stt.test.ts
@@ -36,6 +36,23 @@ describe('stt', () => {
 
 		vi.stubGlobal('MediaRecorder', { isTypeSupported: () => false });
 		expect(pickMime()).toBe('');
+
+		// No isTypeSupported on the constructor -> empty (let the browser default).
+		vi.stubGlobal('MediaRecorder', class {});
+		expect(pickMime()).toBe('');
+	});
+
+	it('listMicrophones returns [] when enumerateDevices throws', async () => {
+		vi.stubGlobal('MediaRecorder', class {});
+		vi.stubGlobal('navigator', {
+			mediaDevices: {
+				getUserMedia: async () => ({}),
+				enumerateDevices: async () => {
+					throw new Error('blocked');
+				}
+			}
+		});
+		expect(await listMicrophones()).toEqual([]);
 	});
 
 	it('stop() resolves (does not hang) even when the recorder already went inactive', async () => {
@@ -77,4 +94,156 @@ describe('stt', () => {
 		expect(result.mime).toMatch(/audio/);
 		expect(tracks[0].stop).toHaveBeenCalled(); // mic released
 	});
+
+	it('records, applies the device constraint, and stop() returns the captured bytes', async () => {
+		const tracks = [{ stop: vi.fn() }, { stop: vi.fn() }];
+		let constraints: unknown;
+		const created: FakeRecorder[] = [];
+		class FakeRecorder {
+			state = 'recording';
+			mimeType = 'audio/webm;codecs=opus';
+			ondataavailable: ((e: { data: Blob }) => void) | null = null;
+			onstop: (() => void) | null = null;
+			onerror: (() => void) | null = null;
+			started = false;
+			constructor(public stream: unknown, public opts: unknown) {
+				created.push(this);
+			}
+			start(): void {
+				this.started = true;
+			}
+			stop(): void {
+				this.state = 'inactive';
+				this.onstop?.();
+			}
+			static isTypeSupported(m: string): boolean {
+				return m === 'audio/webm;codecs=opus';
+			}
+		}
+		vi.stubGlobal('MediaRecorder', FakeRecorder);
+		vi.stubGlobal('navigator', {
+			mediaDevices: {
+				getUserMedia: async (c: unknown) => {
+					constraints = c;
+					return { getTracks: () => tracks };
+				}
+			}
+		});
+		// happy-dom lacks Blob.arrayBuffer here; provide a minimal Blob that yields the chunk bytes.
+		vi.stubGlobal(
+			'Blob',
+			class {
+				type: string;
+				constructor(public parts: Uint8Array[], opts?: { type?: string }) {
+					this.type = opts?.type ?? '';
+				}
+				arrayBuffer(): Promise<ArrayBuffer> {
+					return Promise.resolve(new Uint8Array([7, 8, 9]).buffer);
+				}
+			}
+		);
+
+		const rec = await startRecording('mic-42');
+		const inst = created[0]!;
+		expect(inst.started).toBe(true);
+		expect((inst.opts as { mimeType: string }).mimeType).toBe('audio/webm;codecs=opus');
+		expect(constraints).toEqual({ audio: { deviceId: { exact: 'mic-42' } } });
+
+		// A non-empty data chunk is kept; an empty chunk is ignored.
+		inst.ondataavailable!({ data: { size: 3 } as Blob });
+		inst.ondataavailable!({ data: { size: 0 } as Blob }); // empty chunk ignored
+		const result = await rec.stop();
+		expect(Array.from(result.bytes)).toEqual([7, 8, 9]);
+		expect(result.mime).toBe('audio/webm;codecs=opus');
+		expect(tracks[0]!.stop).toHaveBeenCalled();
+		expect(tracks[1]!.stop).toHaveBeenCalled();
+	});
+
+	it('stop() falls back to audio/webm when neither the recorder nor the blob report a mime', async () => {
+		const tracks = [{ stop: vi.fn() }];
+		const created: FakeRecorder[] = [];
+		class FakeRecorder {
+			state = 'recording';
+			mimeType = ''; // -> falls through to `mime` (also '' here) -> 'audio/webm'
+			ondataavailable: ((e: { data: Blob }) => void) | null = null;
+			onstop: (() => void) | null = null;
+			onerror: (() => void) | null = null;
+			constructor() {
+				created.push(this);
+			}
+			start(): void {
+				/* no-op */
+			}
+			stop(): void {
+				this.state = 'inactive';
+				this.onstop?.();
+			}
+			static isTypeSupported(): boolean {
+				return false; // pickMime -> ''
+			}
+		}
+		vi.stubGlobal('MediaRecorder', FakeRecorder);
+		vi.stubGlobal('navigator', {
+			mediaDevices: { getUserMedia: async () => ({ getTracks: () => tracks }) }
+		});
+		vi.stubGlobal(
+			'Blob',
+			class {
+				type = ''; // -> mime fallback 'audio/webm'
+				constructor(public parts: unknown[]) {}
+				arrayBuffer(): Promise<ArrayBuffer> {
+					return Promise.resolve(new Uint8Array().buffer);
+				}
+			}
+		);
+
+		const rec = await startRecording();
+		const result = await rec.stop();
+		expect(result.mime).toBe('audio/webm');
+	});
+
+	it('stop() rejects when the recorder errors, and cancel() releases the mic', async () => {
+		const tracks = [{ stop: vi.fn() }];
+		const created: FakeRecorder[] = [];
+		class FakeRecorder {
+			state = 'recording';
+			mimeType = '';
+			ondataavailable: ((e: { data: Blob }) => void) | null = null;
+			onstop: (() => void) | null = null;
+			onerror: (() => void) | null = null;
+			constructor() {
+				created.push(this);
+			}
+			start(): void {
+				/* no-op */
+			}
+			stop(): void {
+				/* leave state 'recording' so stop()'s rec.stop() path runs onerror */
+			}
+			static isTypeSupported(): boolean {
+				return false; // -> pickMime returns '', MediaRecorder constructed with undefined opts
+			}
+		}
+		vi.stubGlobal('MediaRecorder', FakeRecorder);
+		vi.stubGlobal('navigator', {
+			mediaDevices: { getUserMedia: async () => ({ getTracks: () => tracks }) }
+		});
+
+		const rec = await startRecording(); // no deviceId -> audio:true
+		const inst = created[0]!;
+		const pending = rec.stop();
+		inst.onerror!(); // recorder fails
+		await expect(pending).rejects.toThrow(/recording failed/);
+		expect(tracks[0]!.stop).toHaveBeenCalled();
+
+		// cancel() on an active recorder also releases tracks (swallowing any stop() throw).
+		tracks[0]!.stop.mockClear();
+		const rec2 = await startRecording();
+		const inst2 = created[1]!;
+		inst2.stop = () => {
+			throw new Error('already stopped');
+		};
+		expect(() => rec2.cancel()).not.toThrow();
+		expect(tracks[0]!.stop).toHaveBeenCalled();
+	});
 });
diff --git a/client/src/lib/tts.test.ts b/client/src/lib/tts.test.ts
index 6d8003f..09a4f6e 100644
--- a/client/src/lib/tts.test.ts
+++ b/client/src/lib/tts.test.ts
@@ -43,4 +43,38 @@ describe('tts', () => {
 		speak('   '); // blank -> no new utterance
 		expect(spoken).toHaveLength(1);
 	});
+
+	it('selects a matching voice and lists voice names; cancelSpeech cancels', () => {
+		class FakeUtterance {
+			text: string;
+			rate = 1;
+			pitch = 1;
+			volume = 1;
+			voice: { name: string } | null = null;
+			constructor(t: string) {
+				this.text = t;
+			}
+		}
+		const voices = [{ name: 'Alice' }, { name: 'Bob' }];
+		const spoken: FakeUtterance[] = [];
+		const synth = {
+			cancel: vi.fn(),
+			getVoices: () => voices,
+			speak: vi.fn((u: FakeUtterance) => spoken.push(u))
+		};
+		vi.stubGlobal('speechSynthesis', synth);
+		vi.stubGlobal('SpeechSynthesisUtterance', FakeUtterance);
+
+		expect(listVoices()).toEqual(['Alice', 'Bob']);
+
+		speak('hi', { voice: 'Bob' });
+		expect(spoken[0]!.voice).toEqual({ name: 'Bob' });
+
+		// An unknown voice name leaves the utterance voice unset (default voice).
+		speak('hi', { voice: 'Nobody' });
+		expect(spoken[1]!.voice).toBeNull();
+
+		cancelSpeech();
+		expect(synth.cancel).toHaveBeenCalledTimes(3); // 2 speaks + 1 explicit cancel
+	});
 });
diff --git a/client/src/lib/viewTransition.test.ts b/client/src/lib/viewTransition.test.ts
new file mode 100644
index 0000000..ca635da
--- /dev/null
+++ b/client/src/lib/viewTransition.test.ts
@@ -0,0 +1,61 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { prefersReducedMotion, startViewTransition } from './viewTransition';
+
+type VTDoc = Document & { startViewTransition?: (cb: () => void) => unknown };
+const doc = document as VTDoc;
+const origMatchMedia = window.matchMedia;
+const origVT = doc.startViewTransition;
+
+afterEach(() => {
+	window.matchMedia = origMatchMedia;
+	doc.startViewTransition = origVT;
+});
+
+const setReducedMotion = (reduced: boolean): void => {
+	window.matchMedia = vi.fn(() => ({ matches: reduced } as unknown as MediaQueryList));
+};
+
+describe('viewTransition', () => {
+	it('prefersReducedMotion reflects the media query', () => {
+		setReducedMotion(true);
+		expect(prefersReducedMotion()).toBe(true);
+		setReducedMotion(false);
+		expect(prefersReducedMotion()).toBe(false);
+	});
+
+	it('prefersReducedMotion is false when matchMedia is unavailable', () => {
+		window.matchMedia = undefined as unknown as typeof window.matchMedia;
+		expect(prefersReducedMotion()).toBe(false);
+	});
+
+	it('runs the update directly when the View Transitions API is unavailable', () => {
+		setReducedMotion(false);
+		doc.startViewTransition = undefined;
+		const update = vi.fn();
+		startViewTransition(update);
+		expect(update).toHaveBeenCalledTimes(1);
+	});
+
+	it('uses startViewTransition when available and motion is allowed', () => {
+		setReducedMotion(false);
+		const vt = vi.fn((cb: () => void) => {
+			cb();
+			return {};
+		});
+		doc.startViewTransition = vt;
+		const update = vi.fn();
+		startViewTransition(update);
+		expect(vt).toHaveBeenCalledTimes(1);
+		expect(update).toHaveBeenCalledTimes(1); // the stub invokes the callback
+	});
+
+	it('skips the transition (runs update directly) under reduced motion', () => {
+		setReducedMotion(true);
+		const vt = vi.fn();
+		doc.startViewTransition = vt;
+		const update = vi.fn();
+		startViewTransition(update);
+		expect(vt).not.toHaveBeenCalled();
+		expect(update).toHaveBeenCalledTimes(1);
+	});
+});
diff --git a/client/src/lib/viewTransition.ts b/client/src/lib/viewTransition.ts
new file mode 100644
index 0000000..b6b0480
--- /dev/null
+++ b/client/src/lib/viewTransition.ts
@@ -0,0 +1,26 @@
+// Run a DOM-updating callback inside a View Transition where the engine supports it (Chromium /
+// WebView2 — the overlay + studio runtime), so a state change cross-fades instead of cutting.
+// Everywhere else (older engines, the test happy-dom) it just runs the update directly, so callers
+// don't need to feature-check. React state changes inside `update` should be flushed synchronously
+// (flushSync) by the caller, so the new DOM is in place when the transition captures the "after"
+// snapshot. Honours prefers-reduced-motion — those users get the instant update, no animation.
+type DocumentWithViewTransitions = Document & {
+	startViewTransition?: (callback: () => void) => unknown;
+};
+
+export function prefersReducedMotion(): boolean {
+	return (
+		typeof window !== 'undefined' &&
+		typeof window.matchMedia === 'function' &&
+		window.matchMedia('(prefers-reduced-motion: reduce)').matches
+	);
+}
+
+export function startViewTransition(update: () => void): void {
+	const doc = document as DocumentWithViewTransitions;
+	if (typeof doc.startViewTransition === 'function' && !prefersReducedMotion()) {
+		doc.startViewTransition(update);
+	} else {
+		update();
+	}
+}
diff --git a/client/src/lib/widgets/AudioSwitcherHost.test.tsx b/client/src/lib/widgets/AudioSwitcherHost.test.tsx
new file mode 100644
index 0000000..287cce6
--- /dev/null
+++ b/client/src/lib/widgets/AudioSwitcherHost.test.tsx
@@ -0,0 +1,139 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+import type { AudioDevice } from '../core/audioDevices';
+
+// Stub the Tauri-backed audio adapter (no backend in tests). The host owns all the wiring (list /
+// read default / set default + the refresh cadence); these spies let us drive what it sees and
+// assert which command a row click fires.
+const { listAudioOutputs, getDefaultAudioOutput, setDefaultAudioOutput } = vi.hoisted(() => ({
+	listAudioOutputs: vi.fn<() => Promise<AudioDevice[]>>(),
+	getDefaultAudioOutput: vi.fn<() => Promise<string | null>>(),
+	setDefaultAudioOutput: vi.fn<(id: string) => Promise<boolean>>()
+}));
+vi.mock('../audio/devices', () => ({
+	listAudioOutputs,
+	getDefaultAudioOutput,
+	setDefaultAudioOutput
+}));
+
+import AudioSwitcherHost from './AudioSwitcherHost';
+
+const DEVICES: AudioDevice[] = [
+	{ id: 'spk', name: 'Speakers' },
+	{ id: 'hp', name: 'Headphones' }
+];
+
+beforeEach(() => {
+	listAudioOutputs.mockReset().mockResolvedValue(DEVICES);
+	getDefaultAudioOutput.mockReset().mockResolvedValue('spk');
+	setDefaultAudioOutput.mockReset().mockResolvedValue(true);
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+	vi.restoreAllMocks();
+});
+
+const rowByName = (container: HTMLElement, name: string): HTMLButtonElement => {
+	const el = [...container.querySelectorAll<HTMLButtonElement>('.as-row')].find(
+		(b) => b.querySelector('.as-name')?.textContent === name
+	);
+	if (!el) throw new Error(`no row named "${name}"`);
+	return el;
+};
+
+describe('AudioSwitcherHost (container wiring)', () => {
+	it('refreshes on mount and renders the devices with the default marked active', async () => {
+		const { container } = render(<AudioSwitcherHost />);
+		expect(listAudioOutputs).toHaveBeenCalled();
+		expect(getDefaultAudioOutput).toHaveBeenCalled();
+		await waitFor(() => expect(container.querySelectorAll('.as-row').length).toBe(2));
+		// The active (default) row floats to the top and carries data-active.
+		const rows = [...container.querySelectorAll<HTMLButtonElement>('.as-row')];
+		expect(rows[0].querySelector('.as-name')?.textContent).toBe('Speakers');
+		expect(rows[0].getAttribute('data-active')).toBe('true');
+	});
+
+	it('passes the accent color through to the meter', async () => {
+		const { container } = render(<AudioSwitcherHost color="#abcdef" />);
+		await waitFor(() => expect(container.querySelectorAll('.as-row').length).toBe(2));
+		const root = container.querySelector('.audioswitch') as HTMLElement;
+		expect(root.style.getPropertyValue('--as-accent')).toBe('#abcdef');
+	});
+
+	it('picking a different device sets it optimistically, calls the backend, then re-refreshes', async () => {
+		const { container } = render(<AudioSwitcherHost />);
+		await waitFor(() => expect(container.querySelectorAll('.as-row').length).toBe(2));
+		listAudioOutputs.mockClear();
+		getDefaultAudioOutput.mockClear();
+
+		// After the switch the backend reports the new default so the active marker stays on Headphones.
+		getDefaultAudioOutput.mockResolvedValue('hp');
+
+		await act(async () => {
+			fireEvent.click(rowByName(container, 'Headphones'));
+		});
+
+		expect(setDefaultAudioOutput).toHaveBeenCalledWith('hp');
+		// refresh() re-runs after the switch.
+		expect(listAudioOutputs).toHaveBeenCalled();
+		expect(getDefaultAudioOutput).toHaveBeenCalled();
+		await waitFor(() =>
+			expect(rowByName(container, 'Headphones').getAttribute('data-active')).toBe('true')
+		);
+	});
+
+	it('clicking the already-default row is a no-op (no backend call)', async () => {
+		const { container } = render(<AudioSwitcherHost />);
+		await waitFor(() => expect(container.querySelectorAll('.as-row').length).toBe(2));
+		await act(async () => {
+			fireEvent.click(rowByName(container, 'Speakers')); // 'spk' === currentId
+		});
+		expect(setDefaultAudioOutput).not.toHaveBeenCalled();
+	});
+
+	it('warns and lets refresh restore the real default when the switch fails', async () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		setDefaultAudioOutput.mockResolvedValue(false);
+		const { container } = render(<AudioSwitcherHost />);
+		await waitFor(() => expect(container.querySelectorAll('.as-row').length).toBe(2));
+
+		await act(async () => {
+			fireEvent.click(rowByName(container, 'Headphones'));
+		});
+
+		expect(setDefaultAudioOutput).toHaveBeenCalledWith('hp');
+		expect(warn).toHaveBeenCalledWith('audio switch failed; reverted to the real default');
+	});
+
+	it('re-polls on window focus and on the interval tick, and stops after unmount (alive guard)', async () => {
+		vi.useFakeTimers();
+		const { unmount } = render(<AudioSwitcherHost />);
+		// Mount poll.
+		expect(listAudioOutputs).toHaveBeenCalledTimes(1);
+		await act(async () => undefined); // let the mount refresh settle
+
+		// A focus event triggers a refresh.
+		listAudioOutputs.mockClear();
+		await act(async () => {
+			window.dispatchEvent(new Event('focus'));
+		});
+		expect(listAudioOutputs).toHaveBeenCalledTimes(1);
+
+		// An interval tick triggers a refresh while alive.
+		listAudioOutputs.mockClear();
+		await act(async () => {
+			vi.advanceTimersByTime(8000); // REFRESH_MS
+		});
+		expect(listAudioOutputs).toHaveBeenCalledTimes(1);
+
+		// After unmount the focus listener is removed and the interval is cleared.
+		unmount();
+		listAudioOutputs.mockClear();
+		await act(async () => {
+			window.dispatchEvent(new Event('focus'));
+			vi.advanceTimersByTime(16000);
+		});
+		expect(listAudioOutputs).not.toHaveBeenCalled();
+	});
+});
diff --git a/client/src/lib/widgets/BackgroundPanel.test.tsx b/client/src/lib/widgets/BackgroundPanel.test.tsx
new file mode 100644
index 0000000..c4f5857
--- /dev/null
+++ b/client/src/lib/widgets/BackgroundPanel.test.tsx
@@ -0,0 +1,266 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render } from '@testing-library/react';
+
+// The only module call the panel makes itself is the stateless open-folder helper — mock the Tauri
+// adapter so a click is observable without a backend.
+vi.mock('../overlay', () => ({ openWallpapersDir: vi.fn() }));
+
+import BackgroundPanel from './BackgroundPanel';
+import { openWallpapersDir } from '../overlay';
+import type { BackgroundSpec } from '../core/layoutTree';
+import type { AutoTheme } from './canvas/useAutoTheme';
+
+type Handlers = {
+	patchBg: ReturnType<typeof vi.fn>;
+	setBgKind: ReturnType<typeof vi.fn>;
+	clearBg: ReturnType<typeof vi.fn>;
+	refreshWallpapers: ReturnType<typeof vi.fn>;
+};
+
+function handlers(): Handlers {
+	return {
+		patchBg: vi.fn(),
+		setBgKind: vi.fn(),
+		clearBg: vi.fn(),
+		refreshWallpapers: vi.fn()
+	};
+}
+
+function renderPanel(
+	bg: BackgroundSpec | undefined,
+	opts: {
+		wallpaperFiles?: string[];
+		autoTheme?: AutoTheme;
+		onClearTokens?: () => void;
+	} = {}
+) {
+	const h = handlers();
+	const utils = render(
+		<BackgroundPanel
+			bg={bg}
+			wallpaperFiles={opts.wallpaperFiles ?? []}
+			refreshWallpapers={h.refreshWallpapers}
+			patchBg={h.patchBg}
+			setBgKind={h.setBgKind}
+			clearBg={h.clearBg}
+			autoTheme={opts.autoTheme}
+			onClearTokens={opts.onClearTokens}
+		/>
+	);
+	return { ...utils, h };
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+describe('BackgroundPanel — type picker', () => {
+	it('renders the Type select defaulting to "none" with no background', () => {
+		const { container } = renderPanel(undefined);
+		const select = container.querySelector('.bg-field select') as HTMLSelectElement;
+		expect(select.value).toBe('none');
+		// All kinds (+ None) are offered as options.
+		const opts = [...select.options].map((o) => o.value);
+		expect(opts).toEqual(['none', 'color', 'image', 'video', 'web']);
+	});
+
+	it('picking a kind emits setBgKind, not clearBg', () => {
+		const { container, h } = renderPanel(undefined);
+		const select = container.querySelector('.bg-field select') as HTMLSelectElement;
+		fireEvent.change(select, { target: { value: 'color' } });
+		expect(h.setBgKind).toHaveBeenCalledWith('color');
+		expect(h.clearBg).not.toHaveBeenCalled();
+	});
+
+	it('picking "none" emits clearBg', () => {
+		const { container, h } = renderPanel({ kind: 'color', src: '#102030' });
+		const select = container.querySelector('.bg-field select') as HTMLSelectElement;
+		expect(select.value).toBe('color');
+		fireEvent.change(select, { target: { value: 'none' } });
+		expect(h.clearBg).toHaveBeenCalledTimes(1);
+		expect(h.setBgKind).not.toHaveBeenCalled();
+	});
+});
+
+describe('BackgroundPanel — colour kind', () => {
+	it('shows a colour input seeded from a valid src and emits the new colour', () => {
+		const { container, h } = renderPanel({ kind: 'color', src: '#abcdef' });
+		const color = container.querySelector('input[type="color"]') as HTMLInputElement;
+		expect(color.value).toBe('#abcdef');
+		fireEvent.change(color, { target: { value: '#112233' } });
+		expect(h.patchBg).toHaveBeenCalledWith({ src: '#112233' });
+	});
+
+	it('falls back to a default colour when src is not a valid hex', () => {
+		const { container } = renderPanel({ kind: 'color', src: 'not-a-colour' });
+		const color = container.querySelector('input[type="color"]') as HTMLInputElement;
+		expect(color.value).toBe('#0b0b0e');
+	});
+});
+
+describe('BackgroundPanel — web kind', () => {
+	it('commits a trimmed URL on blur', () => {
+		const { container, h } = renderPanel({ kind: 'web', src: 'https://a' });
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		expect(url.value).toBe('https://a');
+		fireEvent.change(url, { target: { value: '  https://b  ' } });
+		fireEvent.blur(url);
+		expect(h.patchBg).toHaveBeenCalledWith({ src: 'https://b' });
+	});
+});
+
+describe('BackgroundPanel — media kinds (image/video)', () => {
+	it('lists wallpaper files and selecting one emits patchBg({src})', () => {
+		const { getByText, getByTitle, h } = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png', 'b.jpg'] }
+		);
+		expect(() => getByText('b.jpg')).not.toThrow();
+		fireEvent.click(getByText('b.jpg'));
+		expect(h.patchBg).toHaveBeenCalledWith({ src: 'b.jpg' });
+		// The currently-selected file carries the .cur class.
+		const cur = getByTitle('a.png');
+		expect(cur.className).toContain('cur');
+	});
+
+	it('refresh button calls refreshWallpapers; Folder button opens the wallpapers dir', () => {
+		const { getByTitle, h } = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png'] }
+		);
+		fireEvent.click(getByTitle('Refresh the list'));
+		expect(h.refreshWallpapers).toHaveBeenCalledTimes(1);
+		fireEvent.click(getByTitle(/Open the wallpapers folder/));
+		expect(openWallpapersDir).toHaveBeenCalledTimes(1);
+	});
+
+	it('shows an empty-state hint when there are no wallpaper files', () => {
+		const { getByText } = renderPanel({ kind: 'image', src: 'a.png' }, { wallpaperFiles: [] });
+		expect(() => getByText(/No files yet/)).not.toThrow();
+	});
+
+	it('Fit select emits patchBg({fit})', () => {
+		const { container, h } = renderPanel(
+			{ kind: 'video', src: 'clip.mp4' },
+			{ wallpaperFiles: ['clip.mp4'] }
+		);
+		// The Fit select is the only <select> inside a .bg-field besides Type — find it by its option set.
+		const selects = [...container.querySelectorAll('.bg-field select')] as HTMLSelectElement[];
+		const fit = selects.find((s) =>
+			[...s.options].some((o) => o.value === 'cover')
+		) as HTMLSelectElement;
+		fireEvent.change(fit, { target: { value: 'contain' } });
+		expect(h.patchBg).toHaveBeenCalledWith({ fit: 'contain' });
+	});
+});
+
+describe('BackgroundPanel — video checkboxes', () => {
+	it('muted/loop default to checked and toggling emits the patch', () => {
+		const { getByText, h } = renderPanel({ kind: 'video', src: 'clip.mp4' });
+		const muted = getByText('muted').querySelector('input') as HTMLInputElement;
+		const loop = getByText('loop').querySelector('input') as HTMLInputElement;
+		expect(muted.checked).toBe(true);
+		expect(loop.checked).toBe(true);
+		fireEvent.click(muted);
+		expect(h.patchBg).toHaveBeenCalledWith({ mute: false });
+		fireEvent.click(loop);
+		expect(h.patchBg).toHaveBeenCalledWith({ loop: false });
+	});
+});
+
+describe('BackgroundPanel — opacity/dim/remove (any background)', () => {
+	it('labels show the rounded percentages and the sliders emit numeric patches', () => {
+		const { getByText, container, h } = renderPanel({
+			kind: 'color',
+			src: '#102030',
+			opacity: 0.6,
+			dim: 0.25
+		});
+		expect(() => getByText('Opacity 60%')).not.toThrow();
+		expect(() => getByText('Dim 25%')).not.toThrow();
+		const ranges = [...container.querySelectorAll('input[type="range"]')] as HTMLInputElement[];
+		fireEvent.change(ranges[0], { target: { value: '0.5' } });
+		expect(h.patchBg).toHaveBeenCalledWith({ opacity: 0.5 });
+		fireEvent.change(ranges[1], { target: { value: '0.4' } });
+		expect(h.patchBg).toHaveBeenCalledWith({ dim: 0.4 });
+	});
+
+	it('Remove background emits clearBg', () => {
+		const { getByText, h } = renderPanel({ kind: 'color', src: '#102030' });
+		fireEvent.click(getByText('Remove background'));
+		expect(h.clearBg).toHaveBeenCalledTimes(1);
+	});
+
+	it('renders no opacity/dim/remove controls when there is no background', () => {
+		const { container, queryByText } = renderPanel(undefined);
+		expect(container.querySelector('input[type="range"]')).toBeNull();
+		expect(queryByText('Remove background')).toBeNull();
+	});
+});
+
+describe('BackgroundPanel — auto theme (image only)', () => {
+	const autoTheme = (over: Partial<AutoTheme> = {}): AutoTheme => ({
+		canAuto: true,
+		busy: false,
+		status: 'idle',
+		run: vi.fn(() => Promise.resolve()),
+		resetStatus: vi.fn(),
+		...over
+	});
+
+	it('runs the wallpaper sampler on click', () => {
+		const at = autoTheme();
+		const { getByText } = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png'], autoTheme: at }
+		);
+		fireEvent.click(getByText('🎨 From wallpaper'));
+		expect(at.run).toHaveBeenCalledTimes(1);
+	});
+
+	it('shows a busy label and disables the button while sampling', () => {
+		const at = autoTheme({ busy: true });
+		const { getByText } = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png'], autoTheme: at }
+		);
+		const btn = getByText('Reading…') as HTMLButtonElement;
+		expect(btn.disabled).toBe(true);
+		expect(btn.getAttribute('aria-busy')).toBe('true');
+	});
+
+	it('Reset colours clears tokens and the status', () => {
+		const at = autoTheme();
+		const onClearTokens = vi.fn();
+		const { getByText } = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png'], autoTheme: at, onClearTokens }
+		);
+		fireEvent.click(getByText('Reset colours'));
+		expect(onClearTokens).toHaveBeenCalledTimes(1);
+		expect(at.resetStatus).toHaveBeenCalledTimes(1);
+	});
+
+	it('reports the done / fail status', () => {
+		const done = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png'], autoTheme: autoTheme({ status: 'done' }) }
+		);
+		expect(() => done.getByText(/Applied/)).not.toThrow();
+		done.unmount();
+
+		const fail = renderPanel(
+			{ kind: 'image', src: 'a.png' },
+			{ wallpaperFiles: ['a.png'], autoTheme: autoTheme({ status: 'fail' }) }
+		);
+		expect(() => fail.getByText(/Couldn’t read the image’s colours/)).not.toThrow();
+	});
+
+	it('hides the auto-theme block for a non-image background', () => {
+		const { queryByText } = renderPanel(
+			{ kind: 'video', src: 'clip.mp4' },
+			{ wallpaperFiles: ['clip.mp4'], autoTheme: autoTheme() }
+		);
+		expect(queryByText('🎨 From wallpaper')).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/BoxField.test.tsx b/client/src/lib/widgets/BoxField.test.tsx
index 16caccd..b01365a 100644
--- a/client/src/lib/widgets/BoxField.test.tsx
+++ b/client/src/lib/widgets/BoxField.test.tsx
@@ -47,4 +47,39 @@ describe('BoxField', () => {
 		fireEvent.input(getByLabelText('pad all sides'), { target: { value: '999' } });
 		expect(onChange).toHaveBeenCalledWith(20);
 	});
+
+	it('re-locking a per-side value collapses it to uniform using the top side', () => {
+		const onChange = vi.fn();
+		const { getByLabelText, queryByLabelText } = render(
+			<BoxField label="margin" max={100} value={{ t: 7, r: 2, b: 3, l: 4 }} onChange={onChange} />
+		);
+		// Non-uniform value forces the per-side view; the lock control reads as 'per-side'.
+		expect(getByLabelText('margin per-side')).toBeTruthy();
+		fireEvent.click(getByLabelText('margin per-side'));
+		// Collapses to the top side across all four → a uniform number (7).
+		expect(onChange).toHaveBeenCalledWith(7);
+		// And once re-locked with the value emitted, the single field would show.
+		expect(queryByLabelText('margin top')).toBeTruthy(); // value prop unchanged this render → still per-side
+	});
+
+	it('unlock then re-lock toggles between single and four inputs', () => {
+		const onChange = vi.fn();
+		const { getByLabelText, queryByLabelText } = render(
+			<BoxField label="pad" max={100} value={6} onChange={onChange} />
+		);
+		expect(getByLabelText('pad all sides')).toBeTruthy(); // locked + uniform → single input
+		fireEvent.click(getByLabelText('pad locked')); // unlock
+		expect(queryByLabelText('pad all sides')).toBeNull();
+		expect(getByLabelText('pad top')).toBeTruthy();
+		fireEvent.click(getByLabelText('pad per-side')); // re-lock (value still uniform 6)
+		expect(onChange).toHaveBeenCalledWith(6); // collapse emits the uniform top value
+		expect(getByLabelText('pad all sides')).toBeTruthy(); // back to single input
+	});
+
+	it('applies the dirty class when dirty', () => {
+		const { container } = render(
+			<BoxField label="margin" max={100} value={4} dirty onChange={vi.fn()} />
+		);
+		expect(container.querySelector('.boxfield.dirty')).toBeTruthy();
+	});
 });
diff --git a/client/src/lib/widgets/Canvas.css b/client/src/lib/widgets/Canvas.css
index 862ea93..34fc273 100644
--- a/client/src/lib/widgets/Canvas.css
+++ b/client/src/lib/widgets/Canvas.css
@@ -586,6 +586,24 @@
 }
 
 /* The window-control cluster (— ▢ ✕), pushed to the far right; the gap before it is a drag region. */
+/* Dev/extra-instance badge: an amber pill that takes the title bar's free space (margin-left:auto), so
+   it sits immediately left of the window controls (whose own auto-margin then collapses to 0). */
+.canvas .studio-bar .dev-badge {
+	margin-left: auto;
+	align-self: center;
+	padding: 1px 8px;
+	border-radius: 999px;
+	font-size: var(--text-sm, 0.72rem);
+	font-weight: 700;
+	letter-spacing: 0.05em;
+	text-transform: uppercase;
+	color: #1a1a1a;
+	background: rgba(230, 170, 0, 0.92);
+	white-space: nowrap;
+	user-select: none;
+	-webkit-user-select: none;
+}
+
 .canvas .studio-bar .win-controls {
 	margin-left: auto;
 	display: flex;
diff --git a/client/src/lib/widgets/Canvas.tsx b/client/src/lib/widgets/Canvas.tsx
index a3e7f8e..d36297e 100644
--- a/client/src/lib/widgets/Canvas.tsx
+++ b/client/src/lib/widgets/Canvas.tsx
@@ -15,6 +15,7 @@ import {
 	useRef,
 	useState
 } from 'react';
+import { flushSync } from 'react-dom';
 import { invoke } from '@tauri-apps/api/core';
 import { emit, listen } from '@tauri-apps/api/event';
 import { getVersion } from '@tauri-apps/api/app';
@@ -107,6 +108,7 @@ import {
 	syncInteractiveRects,
 	applyOverlayPresentation
 } from '../overlay';
+import { startViewTransition } from '../viewTransition';
 import { TelemetryHubContext } from './telemetryContext';
 import { listMicrophones } from '../stt';
 import {
@@ -742,6 +744,26 @@ export default function Canvas({ studio = false }: Props) {
 			.catch(() => undefined);
 	}, [studio]);
 
+	// Monitors for the monitor-switch widget's monitor picker (studio only). Friendly EDID names where
+	// known, falling back to the GDI device tag. Empty list just leaves the "Primary monitor" option.
+	const [displayNames, setDisplayNames] = useState<{ id: string; name: string }[]>([]);
+	useEffect(() => {
+		if (!studio) return;
+		invoke<{ gdi: string; friendly: string }[]>(COMMANDS.listDisplayNames)
+			.then((list) => setDisplayNames(list.map((d) => ({ id: d.gdi, name: d.friendly || d.gdi }))))
+			.catch(() => undefined);
+	}, [studio]);
+
+	// Dev / extra-instance flag — drives the "dev" badge in the studio title bar (main.rs); lets you
+	// tell a --multi / debug instance apart from the installed release at a glance.
+	const [devInstance, setDevInstance] = useState(false);
+	useEffect(() => {
+		if (!studio) return;
+		invoke<boolean>(COMMANDS.isDevInstance)
+			.then((v) => setDevInstance(Boolean(v)))
+			.catch(() => undefined);
+	}, [studio]);
+
 	const selectedSet = useMemo(() => new Set(selectedIds), [selectedIds]);
 
 	// --- multi-selection (2+ widgets) → the common-properties details pane ---
@@ -1300,7 +1322,11 @@ export default function Canvas({ studio = false }: Props) {
 				if (action === 'stay') return;
 				foldOpenDef();
 			}
-			setNavSection(id);
+			// Cross-fade the section swap (View Transitions where supported): snapshots the old + new
+			// panels and blends them, which both polishes the change AND avoids the stage flashing
+			// through behind the incoming panel. flushSync so the new section is in the DOM when the
+			// transition captures its "after" snapshot.
+			startViewTransition(() => flushSync(() => setNavSection(id)));
 		},
 		[designing, previewing, defDirty, editingDefName, foldOpenDef]
 	);
@@ -1926,13 +1952,14 @@ export default function Canvas({ studio = false }: Props) {
 		// Index the SAME grouped sequence the NavRail renders (main group, then foot), so Ctrl+1..8
 		// lands on the i-th visible rail button even if the section groups are reordered independently.
 		const s = RAIL_ORDER[index];
-		if (s) setNavSection(s.id);
+		if (s) startViewTransition(() => flushSync(() => setNavSection(s.id)));
 	}, []);
 	const cycleSection = useCallback((delta: number) => {
 		if (designingRef.current) return;
 		const ids = RAIL_ORDER.map((s) => s.id);
 		const i = ids.indexOf(navSectionRef.current);
-		setNavSection(ids[(i + delta + ids.length) % ids.length]);
+		const next = ids[(i + delta + ids.length) % ids.length];
+		startViewTransition(() => flushSync(() => setNavSection(next)));
 	}, []);
 
 	// Select every widget on the monitor (Ctrl+A) — the distinct selectIds across all renderables, i.e.
@@ -2494,6 +2521,16 @@ export default function Canvas({ studio = false }: Props) {
 											Cancel
 										</button>
 									)}
+									{/* Dev/extra-instance badge (main.rs is_dev_instance): a --multi or debug build run
+									    alongside the installed release shows this so the two are distinguishable. */}
+									{devInstance && (
+										<span
+											className="dev-badge"
+											title="Dev / extra instance (--multi or debug build) — separate, isolated config"
+										>
+											dev
+										</span>
+									)}
 									{/* Window controls (the borderless window's min / maximize-restore / close). Pushed to
 									    the far right (margin-left:auto); the gap before them is a drag region. */}
 									<div className="win-controls">
@@ -3044,6 +3081,7 @@ export default function Canvas({ studio = false }: Props) {
 									sensorMeta={sensorMeta}
 									audioOutputs={audioOutputs}
 									microphones={microphones}
+									displayNames={displayNames}
 									docked={studio}
 									onOp={handleOp}
 									onDeleteDef={studio ? deleteWidget : undefined}
diff --git a/client/src/lib/widgets/ConditionEditor.test.tsx b/client/src/lib/widgets/ConditionEditor.test.tsx
index fe54324..884d356 100644
--- a/client/src/lib/widgets/ConditionEditor.test.tsx
+++ b/client/src/lib/widgets/ConditionEditor.test.tsx
@@ -26,6 +26,15 @@ describe('ConditionEditor', () => {
 		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchExe: 'spotify.exe' });
 	});
 
+	it('clears the exe match to undefined when blurred empty', () => {
+		const onChange = vi.fn();
+		render(<ConditionEditor value={{ kind: 'appOpen', matchExe: 'x.exe' }} onChange={onChange} />);
+		const exe = screen.getByLabelText(/exe/i);
+		fireEvent.change(exe, { target: { value: '   ' } });
+		fireEvent.blur(exe);
+		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchExe: undefined });
+	});
+
 	it('switching to a sensor condition seeds a sensor shape, keeping negate', () => {
 		const onChange = vi.fn();
 		const value: Condition = { kind: 'appOpen', matchExe: 'a.exe', negate: true };
@@ -72,10 +81,81 @@ describe('ConditionEditor', () => {
 		for (const call of onChange.mock.calls) expect(call[0]?.kind).not.toBe('sensor');
 	});
 
-	it('toggles negate (invert)', () => {
+	it('commits a window-title match on blur, and clears it to undefined when emptied', () => {
+		const onChange = vi.fn();
+		const { rerender } = render(
+			<ConditionEditor value={{ kind: 'appOpen' }} onChange={onChange} />
+		);
+		const title = screen.getByLabelText(/window title/i);
+		fireEvent.change(title, { target: { value: '  YouTube  ' } });
+		fireEvent.blur(title);
+		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchTitle: 'YouTube' });
+
+		onChange.mockClear();
+		rerender(
+			<ConditionEditor value={{ kind: 'appOpen', matchTitle: 'YouTube' }} onChange={onChange} />
+		);
+		const title2 = screen.getByLabelText(/window title/i);
+		fireEvent.change(title2, { target: { value: '   ' } });
+		fireEvent.blur(title2);
+		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchTitle: undefined });
+	});
+
+	it('commits a window-class match on blur', () => {
+		const onChange = vi.fn();
+		render(<ConditionEditor value={{ kind: 'appOpen' }} onChange={onChange} />);
+		const cls = screen.getByLabelText(/window class/i);
+		fireEvent.change(cls, { target: { value: 'Chrome_WidgetWin_1' } });
+		fireEvent.blur(cls);
+		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchClass: 'Chrome_WidgetWin_1' });
+
+		onChange.mockClear();
+		fireEvent.change(cls, { target: { value: '  ' } });
+		fireEvent.blur(cls);
+		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchClass: undefined });
+	});
+
+	it('picks a sensor id and an operator', () => {
+		const onChange = vi.fn();
+		const value: Condition = { kind: 'sensor', sensorId: 'cpu.total', op: '>', value: '' };
+		render(
+			<ConditionEditor value={value} sensors={['cpu.total', 'gpu.total']} onChange={onChange} />
+		);
+		fireEvent.click(screen.getByLabelText('condition sensor'));
+		fireEvent.click(screen.getByText('gpu.total'));
+		expect(onChange).toHaveBeenCalledWith({ ...value, sensorId: 'gpu.total' });
+
+		onChange.mockClear();
+		fireEvent.click(screen.getByLabelText('condition operator'));
+		fireEvent.click(screen.getByText('≥ at least'));
+		expect(onChange).toHaveBeenCalledWith({ ...value, op: '>=' });
+	});
+
+	it('toggles negate on, then off (clearing it to undefined)', () => {
 		const onChange = vi.fn();
-		render(<ConditionEditor value={{ kind: 'appOpen', matchExe: 'a.exe' }} onChange={onChange} />);
+		const { rerender } = render(
+			<ConditionEditor value={{ kind: 'appOpen', matchExe: 'a.exe' }} onChange={onChange} />
+		);
 		fireEvent.click(screen.getByRole('checkbox', { name: /Invert/i }));
 		expect(onChange).toHaveBeenCalledWith({ kind: 'appOpen', matchExe: 'a.exe', negate: true });
+
+		onChange.mockClear();
+		rerender(
+			<ConditionEditor
+				value={{ kind: 'appOpen', matchExe: 'a.exe', negate: true }}
+				onChange={onChange}
+			/>
+		);
+		fireEvent.click(screen.getByRole('checkbox', { name: /Invert/i }));
+		expect(onChange).toHaveBeenCalledWith({
+			kind: 'appOpen',
+			matchExe: 'a.exe',
+			negate: undefined
+		});
+	});
+
+	it('applies the dirty class when dirty is set', () => {
+		const { container } = render(<ConditionEditor onChange={() => undefined} dirty />);
+		expect(container.querySelector('.cond-editor')!.classList.contains('dirty')).toBe(true);
 	});
 });
diff --git a/client/src/lib/widgets/ControlsPanel.test.tsx b/client/src/lib/widgets/ControlsPanel.test.tsx
index 2feb14b..e969e2a 100644
--- a/client/src/lib/widgets/ControlsPanel.test.tsx
+++ b/client/src/lib/widgets/ControlsPanel.test.tsx
@@ -72,4 +72,90 @@ describe('ControlsPanel', () => {
 		fireEvent.click(getByText(/Reset all/));
 		expect(onResetAll).toHaveBeenCalledTimes(1);
 	});
+
+	it('Escape during capture cancels without rebinding', () => {
+		const onRebind = vi.fn();
+		const { getByText } = render(
+			<ControlsPanel overrides={{}} onRebind={onRebind} onReset={noop} onResetAll={noop} />
+		);
+		const row = getByText('Save draft').closest('.cp-row') as HTMLElement;
+		fireEvent.click(within(row).getByText('Rebind'));
+		// While capturing, the prompt replaces the binding text.
+		expect(() => within(row).getByText(/Press keys/)).not.toThrow();
+		act(() => {
+			window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', code: 'Escape' }));
+		});
+		expect(onRebind).not.toHaveBeenCalled();
+		// Capture ended → the original binding text is shown again, no prompt.
+		expect(() => within(row).getByText('Ctrl+S')).not.toThrow();
+	});
+
+	it('ignores a lone modifier press while capturing and waits for a real key', () => {
+		const onRebind = vi.fn();
+		const { getByText } = render(
+			<ControlsPanel overrides={{}} onRebind={onRebind} onReset={noop} onResetAll={noop} />
+		);
+		const row = getByText('Save draft').closest('.cp-row') as HTMLElement;
+		fireEvent.click(within(row).getByText('Rebind'));
+		// A bare modifier must not end capture (you'd never be able to bind Ctrl+anything otherwise).
+		act(() => {
+			window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Control', code: 'ControlLeft' }));
+		});
+		expect(onRebind).not.toHaveBeenCalled();
+		expect(() => within(row).getByText(/Press keys/)).not.toThrow(); // still capturing
+		// The next real key completes the rebind.
+		act(() => {
+			window.dispatchEvent(new KeyboardEvent('keydown', { key: 'g', code: 'KeyG', ctrlKey: true }));
+		});
+		expect(onRebind).toHaveBeenCalledWith('studio.save', { type: 'key', key: 'g', ctrl: true });
+	});
+
+	it('captures Alt + Meta modifiers into the new trigger', () => {
+		const onRebind = vi.fn();
+		const { getByText } = render(
+			<ControlsPanel overrides={{}} onRebind={onRebind} onReset={noop} onResetAll={noop} />
+		);
+		const row = getByText('Save draft').closest('.cp-row') as HTMLElement;
+		fireEvent.click(within(row).getByText('Rebind'));
+		act(() => {
+			window.dispatchEvent(
+				new KeyboardEvent('keydown', { key: 'm', code: 'KeyM', altKey: true, metaKey: true })
+			);
+		});
+		expect(onRebind).toHaveBeenCalledWith('studio.save', {
+			type: 'key',
+			key: 'm',
+			alt: true,
+			meta: true
+		});
+	});
+
+	it('shows the em-dash placeholder for a control whose triggers were cleared to none', () => {
+		// An override with an empty triggers array fully replaces the defaults → the row has no binding.
+		const overrides = { 'studio.save': { triggers: [] } };
+		const { getByText } = render(
+			<ControlsPanel overrides={overrides} onRebind={noop} onReset={noop} onResetAll={noop} />
+		);
+		const keys = getByText('Save draft').closest('.cp-row')!.querySelector('.cp-keys')!;
+		expect(keys.textContent).toContain('—');
+	});
+
+	it('flags a conflict on both colliding controls with a warning mark + aria-label', () => {
+		// Rebind Save draft onto Ctrl+Z, which collides with Undo (same studio scope) → both rows warn.
+		const overrides = {
+			'studio.save': { triggers: [{ type: 'key' as const, key: 'z', ctrl: true }] }
+		};
+		const { getByText } = render(
+			<ControlsPanel overrides={overrides} onRebind={noop} onReset={noop} onResetAll={noop} />
+		);
+		const saveKeys = getByText('Save draft').closest('.cp-row')!.querySelector('.cp-keys')!;
+		const undoKeys = getByText('Undo').closest('.cp-row')!.querySelector('.cp-keys')!;
+		// Both the remapped control and the one it shadows are marked.
+		expect(saveKeys.classList.contains('cp-conflict')).toBe(true);
+		expect(undoKeys.classList.contains('cp-conflict')).toBe(true);
+		// The visible warning glyph + the accessible description are both present.
+		expect(saveKeys.querySelector('.cp-conflict-mark')).not.toBeNull();
+		expect(saveKeys.getAttribute('aria-label')).toMatch(/conflicts with another control/);
+		expect(saveKeys.getAttribute('title')).toBe('Conflicts with another control');
+	});
 });
diff --git a/client/src/lib/widgets/CssEditorImpl.test.tsx b/client/src/lib/widgets/CssEditorImpl.test.tsx
new file mode 100644
index 0000000..ba9eb35
--- /dev/null
+++ b/client/src/lib/widgets/CssEditorImpl.test.tsx
@@ -0,0 +1,95 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render, waitFor } from '@testing-library/react';
+import { act } from 'react';
+import { EditorView } from '@codemirror/view';
+import CssEditorImpl from './CssEditorImpl';
+
+// Direct tests against the (normally lazy-loaded) CodeMirror impl: construct under happy-dom, then
+// drive the EditorView programmatically. Rich interactions (real typing/popups) need layout and are
+// covered elsewhere — here we verify the wiring: doc render, onChange/onBlur callbacks, external
+// value resync (only while unfocused), aria-label, and className merging.
+
+const cmEditor = (container: HTMLElement) => container.querySelector('.cm-editor') as HTMLElement;
+const cmContent = (container: HTMLElement) =>
+	container.querySelector('.cm-content') as HTMLElement | null;
+// happy-dom has no real contentEditable, so drive the doc through CodeMirror's own view API rather
+// than synthetic key events (which CodeMirror reads from the DOM and so can't process here).
+const view = (container: HTMLElement) => EditorView.findFromDOM(cmEditor(container))!;
+
+describe('CssEditorImpl', () => {
+	it('mounts a CodeMirror editor and renders the initial value', async () => {
+		const { container } = render(<CssEditorImpl value=".value { color: red }" />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		expect(cmContent(container)?.textContent).toContain('color: red');
+	});
+
+	it('defaults the aria-label and merges the className onto the host', async () => {
+		const { container } = render(<CssEditorImpl value="" className="inspector-css" />);
+		await waitFor(() => expect(cmContent(container)).toBeTruthy());
+		expect(cmContent(container)?.getAttribute('aria-label')).toBe('CSS editor');
+		const host = container.querySelector('.css-editor');
+		expect(host?.classList.contains('inspector-css')).toBe(true);
+	});
+
+	it('uses the supplied aria-label when given', async () => {
+		const { container } = render(<CssEditorImpl value="" ariaLabel="theme css" />);
+		await waitFor(() => expect(cmContent(container)).toBeTruthy());
+		expect(cmContent(container)?.getAttribute('aria-label')).toBe('theme css');
+	});
+
+	it('fires onChange with the new doc on a document change', async () => {
+		const onChange = vi.fn();
+		const { container } = render(<CssEditorImpl value="a" onChange={onChange} />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		// Dispatch a doc edit through the view → the updateListener fires onChange.
+		act(() => {
+			view(container).dispatch({ changes: { from: 1, insert: 'bc' } });
+		});
+		expect(onChange).toHaveBeenCalled();
+		expect(onChange.mock.calls.at(-1)?.[0]).toBe('abc');
+	});
+
+	it('fires onBlur with the current doc when the content blurs', async () => {
+		const onBlur = vi.fn();
+		const { container } = render(<CssEditorImpl value="x: 1" onBlur={onBlur} />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		act(() => {
+			cmContent(container)!.dispatchEvent(new FocusEvent('blur', { bubbles: true }));
+		});
+		expect(onBlur).toHaveBeenCalledWith('x: 1');
+	});
+
+	it('resyncs the doc when the external value changes while unfocused', async () => {
+		const { container, rerender } = render(<CssEditorImpl value="before" />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		rerender(<CssEditorImpl value="after" />);
+		await waitFor(() => expect(cmContent(container)?.textContent).toContain('after'));
+	});
+
+	it('does NOT resync while the editor is focused (no clobbering the cursor)', async () => {
+		const { container, rerender } = render(<CssEditorImpl value="typed" />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		// Really focus the content so view.hasFocus (activeElement check) is true.
+		act(() => cmContent(container)!.focus());
+		expect(view(container).hasFocus).toBe(true);
+		rerender(<CssEditorImpl value="external" />);
+		// The displayed doc keeps the user's content, not the external value.
+		expect(cmContent(container)?.textContent).toContain('typed');
+		expect(cmContent(container)?.textContent).not.toContain('external');
+	});
+
+	it('is a no-op resync when the external value already matches the doc', async () => {
+		const { container, rerender } = render(<CssEditorImpl value="same" />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		// Re-render with the identical value: the value-sync effect runs but dispatches no change.
+		rerender(<CssEditorImpl value="same" />);
+		expect(cmContent(container)?.textContent).toContain('same');
+	});
+
+	it('destroys the view on unmount without throwing', async () => {
+		const { container, unmount } = render(<CssEditorImpl value="z" />);
+		await waitFor(() => expect(cmEditor(container)).toBeTruthy());
+		expect(() => unmount()).not.toThrow();
+		expect(container.querySelector('.cm-editor')).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/DesignerListPanel.test.tsx b/client/src/lib/widgets/DesignerListPanel.test.tsx
new file mode 100644
index 0000000..dde78ac
--- /dev/null
+++ b/client/src/lib/widgets/DesignerListPanel.test.tsx
@@ -0,0 +1,178 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, waitFor, within } from '@testing-library/react';
+
+// copyToClipboard is a Tauri/clipboard adapter (outer ring) — mock it so the "Copy widget reference"
+// button can be exercised without a backend. The panel also calls window.alert after copying.
+vi.mock('../overlay', () => ({ copyToClipboard: vi.fn(() => Promise.resolve(true)) }));
+
+import DesignerListPanel from './DesignerListPanel';
+import { copyToClipboard } from '../overlay';
+import type { Library } from '../core/layoutTree';
+import type { DefEditor } from './canvas/useDefEditor';
+
+// The grouped def-edit actions (useDefEditor) — every entry is a spy so we can assert which one a
+// click/row dispatches. Only the subset DesignerListPanel uses is required.
+function makeActions(): Pick<
+	DefEditor,
+	| 'startNewWidget'
+	| 'openExistingDef'
+	| 'renameWidget'
+	| 'cloneDefToEdit'
+	| 'deleteWidget'
+	| 'previewTemplate'
+	| 'newFromTemplate'
+> {
+	return {
+		startNewWidget: vi.fn(),
+		openExistingDef: vi.fn(),
+		renameWidget: vi.fn(),
+		cloneDefToEdit: vi.fn(),
+		deleteWidget: vi.fn(),
+		previewTemplate: vi.fn(),
+		newFromTemplate: vi.fn()
+	};
+}
+
+const library = (): Library => ({
+	version: 1,
+	defs: [
+		{
+			id: 'def-a',
+			name: 'My Gauge',
+			size: { w: 100, h: 40 },
+			child: { id: 'x', kind: 'col', children: [] }
+		},
+		{
+			id: 'def-b',
+			name: 'My Clock',
+			size: { w: 100, h: 40 },
+			child: { id: 'y', kind: 'col', children: [] }
+		}
+	]
+});
+
+const baseProps = () => ({
+	library: library(),
+	editingDefId: null as string | null,
+	previewName: null as string | null,
+	designing: false,
+	actions: makeActions()
+});
+
+let alertSpy: ReturnType<typeof vi.spyOn>;
+beforeEach(() => {
+	vi.clearAllMocks();
+	alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+});
+afterEach(() => alertSpy.mockRestore());
+
+describe('DesignerListPanel library list', () => {
+	it('renders one row per library def with its name', () => {
+		const { getByText } = render(<DesignerListPanel {...baseProps()} />);
+		expect(getByText('My Gauge')).toBeTruthy();
+		expect(getByText('My Clock')).toBeTruthy();
+	});
+
+	it('clicking a def label opens it for editing', () => {
+		const props = baseProps();
+		const { getByText } = render(<DesignerListPanel {...props} />);
+		fireEvent.click(getByText('My Gauge'));
+		expect(props.actions.openExistingDef).toHaveBeenCalledWith('def-a');
+	});
+
+	it('the per-row icons fire rename / clone / delete for that def', () => {
+		const props = baseProps();
+		const { getByText } = render(<DesignerListPanel {...props} />);
+		const row = within(getByText('My Gauge').closest('.dl-item')! as HTMLElement);
+		fireEvent.click(row.getByTitle('Rename widget'));
+		expect(props.actions.renameWidget).toHaveBeenCalledWith('def-a', 'My Gauge');
+		fireEvent.click(row.getByTitle('Clone to a new widget'));
+		expect(props.actions.cloneDefToEdit).toHaveBeenCalledWith('def-a');
+		fireEvent.click(row.getByTitle('Delete widget'));
+		expect(props.actions.deleteWidget).toHaveBeenCalledWith('def-a', 'My Gauge');
+	});
+
+	it('marks the currently-edited def row with the "cur" class', () => {
+		const { getByText } = render(<DesignerListPanel {...baseProps()} editingDefId="def-b" />);
+		expect(getByText('My Clock').closest('.dl-item')!.className).toContain('cur');
+		expect(getByText('My Gauge').closest('.dl-item')!.className).not.toContain('cur');
+	});
+
+	it('shows the empty-library stub when there are no defs', () => {
+		const { getByText } = render(
+			<DesignerListPanel {...baseProps()} library={{ version: 1, defs: [] }} />
+		);
+		expect(getByText(/No widgets yet/)).toBeTruthy();
+	});
+});
+
+describe('DesignerListPanel template groups', () => {
+	it('renders the built-in Templates group with the preset rows', () => {
+		const { getByText } = render(<DesignerListPanel {...baseProps()} />);
+		expect(getByText('Templates')).toBeTruthy();
+		// The built-in template names (core/templates.ts TEMPLATES).
+		expect(getByText('System monitor')).toBeTruthy();
+		expect(getByText('Now playing')).toBeTruthy();
+	});
+
+	it('clicking a template name previews it (read-only)', () => {
+		const props = baseProps();
+		const { getByText } = render(<DesignerListPanel {...props} />);
+		fireEvent.click(getByText('System monitor'));
+		expect(props.actions.previewTemplate).toHaveBeenCalledWith('system');
+	});
+
+	it('the template clone icon clones it into a new library widget', () => {
+		const props = baseProps();
+		const { getByText } = render(<DesignerListPanel {...props} />);
+		const row = within(getByText('Network').closest('.dl-item')! as HTMLElement);
+		fireEvent.click(row.getByTitle(/Clone into a new editable library widget/));
+		expect(props.actions.newFromTemplate).toHaveBeenCalledWith('network');
+	});
+
+	it('highlights the previewed template row by name', () => {
+		const { getByText } = render(<DesignerListPanel {...baseProps()} previewName="Network" />);
+		expect(getByText('Network').closest('.dl-item')!.className).toContain('cur');
+	});
+});
+
+describe('DesignerListPanel header actions', () => {
+	it('the New widget button starts a fresh def', () => {
+		const props = baseProps();
+		const { getByText } = render(<DesignerListPanel {...props} />);
+		fireEvent.click(getByText('＋ New widget'));
+		expect(props.actions.startNewWidget).toHaveBeenCalledTimes(1);
+	});
+
+	it('Copy widget reference copies markdown and alerts success', async () => {
+		const { getByText } = render(<DesignerListPanel {...baseProps()} />);
+		fireEvent.click(getByText('⧉ Copy widget reference'));
+		await waitFor(() => expect(copyToClipboard).toHaveBeenCalledTimes(1));
+		// The copied payload is the generated widget-reference markdown (non-empty).
+		const md = vi.mocked(copyToClipboard).mock.calls[0][0];
+		expect(typeof md).toBe('string');
+		expect(md.length).toBeGreaterThan(0);
+		await waitFor(() => expect(alertSpy).toHaveBeenCalledWith(expect.stringMatching(/copied/i)));
+	});
+
+	it('alerts a failure (and does not claim success) when the copy fails', async () => {
+		vi.mocked(copyToClipboard).mockResolvedValueOnce(false);
+		const { getByText } = render(<DesignerListPanel {...baseProps()} />);
+		fireEvent.click(getByText('⧉ Copy widget reference'));
+		await waitFor(() =>
+			expect(alertSpy).toHaveBeenCalledWith(expect.stringMatching(/Copy failed/i))
+		);
+	});
+});
+
+describe('DesignerListPanel empty-state explainer', () => {
+	it('shows the "Widget designer" explainer when not designing', () => {
+		const { getByText } = render(<DesignerListPanel {...baseProps()} designing={false} />);
+		expect(getByText('Widget designer')).toBeTruthy();
+	});
+
+	it('hides the explainer once a def/preview is open', () => {
+		const { queryByText } = render(<DesignerListPanel {...baseProps()} designing />);
+		expect(queryByText('Widget designer')).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/DiagnosticsPanel.test.tsx b/client/src/lib/widgets/DiagnosticsPanel.test.tsx
new file mode 100644
index 0000000..4083437
--- /dev/null
+++ b/client/src/lib/widgets/DiagnosticsPanel.test.tsx
@@ -0,0 +1,294 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+import type { WindowDiag } from '../core/diagnostics';
+
+// Mock the cross-window diagnostics bridge (the Tauri adapter): the panel polls these on an
+// interval and subscribes to live reports. Each fn is a spy so we can drive what the panel sees
+// and assert which backend command a recovery button fires. `listenDiagReports` captures the
+// callback so a test can push a synthetic WindowDiag through it.
+let reportCb: ((r: WindowDiag) => void) | null = null;
+const unlisten = vi.fn();
+vi.mock('../diag', () => ({
+	getProcessDiagnostics: vi.fn(() => Promise.resolve(null)),
+	getSubsystemTimings: vi.fn(() => Promise.resolve([])),
+	listWindowLabels: vi.fn(() => Promise.resolve([])),
+	listenDiagReports: vi.fn((cb: (r: WindowDiag) => void) => {
+		reportCb = cb;
+		return Promise.resolve(unlisten);
+	}),
+	openDevtoolsFor: vi.fn(() => Promise.resolve()),
+	reloadWindow: vi.fn(() => Promise.resolve()),
+	requestDiagnostics: vi.fn(),
+	setSubsystemProfiling: vi.fn(() => Promise.resolve()),
+	setWindowInteractive: vi.fn(() => Promise.resolve())
+}));
+
+// Mock the per-widget render-cost accumulator (module singleton) so the panel renders a known set
+// of cost rows and we can assert the reset button clears them.
+vi.mock('./canvas/widgetProfile', () => ({
+	widgetCosts: vi.fn(() => []),
+	resetWidgetProfile: vi.fn()
+}));
+
+import DiagnosticsPanel from './DiagnosticsPanel';
+import {
+	getProcessDiagnostics,
+	getSubsystemTimings,
+	listWindowLabels,
+	openDevtoolsFor,
+	reloadWindow,
+	requestDiagnostics,
+	setSubsystemProfiling,
+	setWindowInteractive
+} from '../diag';
+import { resetWidgetProfile, widgetCosts } from './canvas/widgetProfile';
+
+// A WindowDiag fixture with sensible defaults; `at` is stamped on the studio clock by the panel
+// (it re-stamps performance.now() on arrival), so its exact value here doesn't matter. Heap/art
+// bytes are clean powers of 1024 so the formatBytes (binary-scaled) output is exact.
+function diag(label: string, over: Partial<WindowDiag> = {}): WindowDiag {
+	return {
+		label,
+		role: label === 'studio' ? 'studio' : label === 'main' ? 'main' : 'overlay',
+		monitor: null,
+		heap: {
+			usedBytes: 50 * 1024 * 1024,
+			totalBytes: 80 * 1024 * 1024,
+			limitBytes: 200 * 1024 * 1024
+		},
+		sessions: 1,
+		artBytes: 2 * 1024 * 1024,
+		sensors: 12,
+		activeSensors: 5,
+		domNodes: 420,
+		widgets: [],
+		at: 0,
+		...over
+	};
+}
+
+// Let the mount effect's mocked polls (proc/labels/timings/reports) resolve inside act() so the
+// resulting setState commits don't log "not wrapped in act" warnings after the test returns.
+const flush = () => act(async () => undefined);
+
+// RTL's default getByText matches one element's normalized text; readouts like `up {duration}` are
+// split across literal + interpolated text nodes inside one span, so match on the element's full
+// textContent instead. Returns the matched element (throws if absent).
+function hasText(container: HTMLElement, text: string): HTMLElement {
+	const el = [...container.querySelectorAll<HTMLElement>('span,div,button')].find(
+		(e) => e.textContent === text
+	);
+	if (!el) throw new Error(`no element whose textContent is exactly "${text}"`);
+	return el;
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	reportCb = null;
+	vi.mocked(getProcessDiagnostics).mockResolvedValue(null);
+	vi.mocked(getSubsystemTimings).mockResolvedValue([]);
+	vi.mocked(listWindowLabels).mockResolvedValue([]);
+	vi.mocked(widgetCosts).mockReturnValue([]);
+});
+
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+describe('DiagnosticsPanel lifecycle', () => {
+	it('kicks off a poll and enables backend profiling on mount, disabling it on unmount', async () => {
+		const { unmount } = render(<DiagnosticsPanel />);
+		// The first tick runs synchronously in the mount effect (before the interval).
+		expect(requestDiagnostics).toHaveBeenCalled();
+		expect(getProcessDiagnostics).toHaveBeenCalled();
+		expect(listWindowLabels).toHaveBeenCalled();
+		// Demand-gated backend timing: ON while the panel is open.
+		await waitFor(() => expect(setSubsystemProfiling).toHaveBeenCalledWith(true));
+		unmount();
+		expect(setSubsystemProfiling).toHaveBeenCalledWith(false);
+	});
+
+	it('re-polls every interval tick (not just the initial mount poll)', async () => {
+		vi.useFakeTimers();
+		const { unmount } = render(<DiagnosticsPanel />);
+		// One poll from the mount effect.
+		expect(requestDiagnostics).toHaveBeenCalledTimes(1);
+		await act(async () => {
+			vi.advanceTimersByTime(1500); // POLL_MS — one interval tick
+		});
+		expect(requestDiagnostics).toHaveBeenCalledTimes(2);
+		unmount();
+		// The interval is cleared on unmount: further time advances trigger no more polls.
+		await act(async () => {
+			vi.advanceTimersByTime(3000);
+		});
+		expect(requestDiagnostics).toHaveBeenCalledTimes(2);
+	});
+
+	it('shows the "Polling windows…" stub when no window has reported and no labels exist', async () => {
+		const { getByText } = render(<DiagnosticsPanel />);
+		expect(() => getByText(/Polling windows/)).not.toThrow();
+		await flush();
+	});
+});
+
+describe('DiagnosticsPanel native-process row', () => {
+	it('renders the host-process cpu / rss / virt / uptime once the proc poll resolves', async () => {
+		vi.mocked(getProcessDiagnostics).mockResolvedValue({
+			pid: 1234,
+			cpuPercent: 7.5,
+			memBytes: 256 * 1024 * 1024,
+			virtualBytes: 512 * 1024 * 1024,
+			uptimeSecs: 3661,
+			cpus: 8
+		});
+		const { findByText, container } = render(<DiagnosticsPanel />);
+		expect(await findByText(/pid 1234 · 8 cpus/)).toBeTruthy();
+		expect(hasText(container, 'cpu 7.5%')).toBeTruthy();
+		expect(hasText(container, 'rss 256.0 MiB')).toBeTruthy();
+		expect(hasText(container, 'virt 512.0 MiB')).toBeTruthy();
+		// Uptime uses core/timer's formatDuration ('auto' → hh:mm:ss once over an hour), not the
+		// compact "1h 1m" form: 3661s → 01:01:01.
+		expect(hasText(container, 'up 01:01:01')).toBeTruthy();
+		await flush();
+	});
+});
+
+describe('DiagnosticsPanel backend subsystem timings', () => {
+	it('lists the per-subsystem CPU rows from the timings poll', async () => {
+		vi.mocked(getSubsystemTimings).mockResolvedValue([
+			// One hot subsystem (msPerSec ≥ 5 → data-hot) and one cold one (< 5).
+			{ key: 'sensors', avgMs: 6, lastMs: 6.1, samples: 30, perSec: 1, msPerSec: 6 },
+			{ key: 'ha', avgMs: 0.5, lastMs: 0.4, samples: 10, perSec: 0.5, msPerSec: 0.25 }
+		]);
+		const { findByText, getByText, container } = render(<DiagnosticsPanel />);
+		expect(await findByText('sensors')).toBeTruthy();
+		expect(hasText(container, '6.0 ms/s')).toBeTruthy(); // msPerSec.toFixed(1)
+		expect(getByText('ha')).toBeTruthy();
+		// The hot row is flagged; the cold row is not.
+		expect(container.querySelector('.diag-cost-row[data-hot]')).toBeTruthy();
+		expect(container.querySelectorAll('.diag-cost-row[data-hot]').length).toBe(1);
+		await flush();
+	});
+});
+
+describe('DiagnosticsPanel widget render cost', () => {
+	it('shows the no-renders stub when nothing has been profiled', async () => {
+		const { getByText } = render(<DiagnosticsPanel />);
+		expect(() => getByText(/No renders captured yet/)).not.toThrow();
+		await flush();
+	});
+
+	it('renders cost rows and the reset button clears them', async () => {
+		vi.mocked(widgetCosts).mockReturnValue([
+			// A churning widget (perSec ≥ 2 → data-hot) and a calm one (< 2 → not flagged).
+			{ id: 'clock-ab12', type: 'clock', commits: 4, perSec: 3.2, avgMs: 0.8, lastMs: 0.9 },
+			{ id: 'text-cd34', type: 'text', commits: 2, perSec: 0.5, avgMs: 0.2, lastMs: 0.2 }
+		]);
+		const { getByText, queryByText, container } = render(<DiagnosticsPanel />);
+		expect(getByText('clock')).toBeTruthy();
+		expect(hasText(container, '3.2/s')).toBeTruthy();
+		expect(container.querySelectorAll('.diag-cost-row[data-hot]').length).toBe(1); // only the hot one
+		// After reset the accumulator is cleared AND the local rows drop to the empty stub.
+		vi.mocked(widgetCosts).mockReturnValue([]);
+		fireEvent.click(getByText('reset'));
+		expect(resetWidgetProfile).toHaveBeenCalledTimes(1);
+		expect(queryByText('clock')).toBeNull();
+		expect(getByText(/No renders captured yet/)).toBeTruthy();
+		await flush();
+	});
+});
+
+describe('DiagnosticsPanel window rows', () => {
+	it('renders a backend-listed window with its heap / sessions / sensors / dom once it reports', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['main']);
+		const { findByText, container } = render(<DiagnosticsPanel />);
+		// The label row appears from the backend list even before a report arrives.
+		expect(await findByText('main')).toBeTruthy();
+		// Push a live report (with a monitor key) through the captured listener callback.
+		act(() => reportCb?.(diag('main', { monitor: '2' })));
+		// heap used/limit + fraction (50/200 MiB → 25%).
+		expect(hasText(container, 'heap 50.0 MiB / 200.0 MiB · 25%')).toBeTruthy();
+		expect(hasText(container, 'sessions 1 · art 2.0 MiB')).toBeTruthy();
+		expect(hasText(container, 'sensors 5/12')).toBeTruthy();
+		expect(hasText(container, 'dom 420')).toBeTruthy();
+		// The monitor key rides the role line ("· mon 2") when the report carries one.
+		expect(container.textContent).toContain('· mon 2');
+		await flush();
+	});
+
+	it('marks a listed-but-silent window "not responding" and still offers recovery actions', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['overlay-2']);
+		const { findByText, getByRole } = render(<DiagnosticsPanel />);
+		// No report ever arrives for this label → responding:false (report:null).
+		expect(await findByText('not responding')).toBeTruthy();
+		// Recovery controls (overlay role) reach the backend by label even with no JS report. Use the
+		// button role to disambiguate from the explanatory note that also mentions Devtools/Reload.
+		fireEvent.click(getByRole('button', { name: /Devtools/ }));
+		expect(openDevtoolsFor).toHaveBeenCalledWith('overlay-2');
+		fireEvent.click(getByRole('button', { name: /Reload/ }));
+		expect(reloadWindow).toHaveBeenCalledWith('overlay-2');
+		await flush();
+	});
+
+	it('toggling "interactive" drops click-through for that window via the backend', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['overlay-2']);
+		const { findByText, getByLabelText } = render(<DiagnosticsPanel />);
+		await findByText('overlay-2');
+		const box = getByLabelText('interactive') as HTMLInputElement;
+		expect(box.checked).toBe(false);
+		fireEvent.click(box);
+		expect(setWindowInteractive).toHaveBeenCalledWith('overlay-2', true);
+		expect(box.checked).toBe(true);
+		await flush();
+	});
+
+	it('does not offer recovery actions for the studio window itself', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['studio']);
+		const { findByText, queryByRole } = render(<DiagnosticsPanel />);
+		await findByText('studio');
+		act(() => reportCb?.(diag('studio')));
+		expect(queryByRole('button', { name: /Devtools/ })).toBeNull();
+		expect(queryByRole('button', { name: /Reload/ })).toBeNull();
+		await flush();
+	});
+
+	it('renders the per-widget DOM breakdown when a report carries one', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['main']);
+		const { findByText, getByText } = render(<DiagnosticsPanel />);
+		await findByText('main');
+		act(() =>
+			reportCb?.(
+				diag('main', {
+					widgets: [
+						{ type: 'cpu', count: 2, nodes: 64 },
+						{ type: 'clock', count: 1, nodes: 8 }
+					]
+				})
+			)
+		);
+		expect(getByText(/cpu×2/)).toBeTruthy();
+		expect(getByText('64')).toBeTruthy();
+		await flush();
+	});
+
+	it('ignores a report that arrives after the panel unmounts (alive guard)', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['main']);
+		const { findByText, unmount } = render(<DiagnosticsPanel />);
+		await findByText('main');
+		unmount();
+		// The listener's `if (!alive) return` short-circuits — pushing a report must not throw or
+		// attempt a setState on the unmounted tree.
+		expect(() => act(() => reportCb?.(diag('main')))).not.toThrow();
+	});
+
+	it('renders heap "n/a" when a window reports no heap stats', async () => {
+		vi.mocked(listWindowLabels).mockResolvedValue(['main']);
+		const { findByText, container } = render(<DiagnosticsPanel />);
+		await findByText('main');
+		act(() => reportCb?.(diag('main', { heap: null })));
+		// The heap branch falls back to 'n/a' and drops the % fraction.
+		expect(hasText(container, 'heap n/a')).toBeTruthy();
+		await flush();
+	});
+});
diff --git a/client/src/lib/widgets/DragSnapLayer.test.tsx b/client/src/lib/widgets/DragSnapLayer.test.tsx
index ad94b8f..4273faa 100644
--- a/client/src/lib/widgets/DragSnapLayer.test.tsx
+++ b/client/src/lib/widgets/DragSnapLayer.test.tsx
@@ -67,6 +67,33 @@ const DOCKED_LAYOUT = JSON.stringify({
 	}
 });
 
+// A layout whose floating layer holds non-zone units (a plain widget + a group) alongside a real
+// zone — the non-zone/group entries must be skipped, only the zone becomes a snap target.
+const MIXED_FLOATING_LAYOUT = JSON.stringify({
+	version: 2,
+	monitors: {
+		default: {
+			root: { id: 'root', kind: 'col', children: [] },
+			floating: [
+				{ id: 'g1', unit: { id: 'g1', kind: 'group', size: { w: 50, h: 50 }, child: null } },
+				{
+					id: 'w1',
+					unit: { id: 'w1', type: 'clock', rect: { x: 0, y: 0, w: 100, h: 50 }, config: {} }
+				},
+				{
+					id: 'z1',
+					unit: {
+						id: 'z1',
+						type: 'zone',
+						rect: { x: 0, y: 0, w: 960, h: 1080 },
+						config: { matchExe: 'notepad.exe' }
+					}
+				}
+			]
+		}
+	}
+});
+
 // The layout loadLayoutRaw() serves; swapped per test, reset in beforeEach.
 let layoutJson = LAYOUT;
 
@@ -195,6 +222,180 @@ describe('DragSnapLayer (zone widgets)', () => {
 		expect(snapWindow).toHaveBeenCalledWith(42, { x: 100, y: 200, w: 800, h: 600 });
 	});
 
+	it('tolerates a malformed widgets.json (parse throws → no zones, no snap)', async () => {
+		layoutJson = '{ not valid json';
+		pointerProbe.mockResolvedValue({ x: 480, y: 540, shift: true });
+		render(<DragSnapLayer />);
+		await settle();
+
+		act(() => handlers['win_drag_start']?.({ payload: { hwnd: 7 } }));
+		await pollOnce();
+		await act(async () => {
+			handlers['win_drag_end']?.({ payload: { hwnd: 7 } });
+			await Promise.resolve();
+		});
+		expect(snapWindow).not.toHaveBeenCalled();
+	});
+
+	it('tolerates an empty widgets.json (loadLayoutRaw returns nothing → no zones)', async () => {
+		layoutJson = '';
+		pointerProbe.mockResolvedValue({ x: 480, y: 540, shift: true });
+		render(<DragSnapLayer />);
+		await settle();
+
+		await act(async () => {
+			handlers['arrange_zones']?.({ payload: {} });
+			await new Promise((r) => setTimeout(r, 0));
+		});
+		expect(snapWindow).not.toHaveBeenCalled();
+	});
+
+	it('renders the zone highlight while a Shift-drag hovers an armed zone', async () => {
+		pointerProbe.mockResolvedValue({ x: 480, y: 540, shift: true }); // inside the left zone
+		const view = render(<DragSnapLayer />);
+		await settle();
+
+		act(() => handlers['win_drag_start']?.({ payload: { hwnd: 7 } }));
+		await pollOnce();
+		const hl = view.container.querySelector('.zone-drag-highlight') as HTMLElement;
+		expect(hl).toBeTruthy();
+		// The highlight uses the zone's LOCAL rect (logical px), not the physical one.
+		expect(hl.style.left).toBe('0px');
+		expect(hl.style.width).toBe('960px');
+
+		await act(async () => {
+			handlers['win_drag_end']?.({ payload: { hwnd: 7 } });
+			await Promise.resolve();
+		});
+		// Cleared on release.
+		expect(view.container.querySelector('.zone-drag-highlight')).toBeNull();
+	});
+
+	it('reloads its zones when a layout_changed event fires', async () => {
+		layoutJson = JSON.stringify({ version: 2, monitors: {} }); // start with no zones
+		pointerProbe.mockResolvedValue({ x: 480, y: 540, shift: true });
+		render(<DragSnapLayer />);
+		await settle();
+
+		// No zones yet → a drag arms nothing.
+		act(() => handlers['win_drag_start']?.({ payload: { hwnd: 7 } }));
+		await pollOnce();
+		await act(async () => {
+			handlers['win_drag_end']?.({ payload: { hwnd: 7 } });
+			await Promise.resolve();
+		});
+		expect(snapWindow).not.toHaveBeenCalled();
+
+		// A layout with zones lands; layout_changed triggers a reload.
+		layoutJson = LAYOUT;
+		await act(async () => {
+			handlers['layout_changed']?.({ payload: {} });
+			await new Promise((r) => setTimeout(r, 0));
+		});
+		act(() => handlers['win_drag_start']?.({ payload: { hwnd: 8 } }));
+		await pollOnce();
+		await act(async () => {
+			handlers['win_drag_end']?.({ payload: { hwnd: 8 } });
+			await Promise.resolve();
+		});
+		expect(snapWindow).toHaveBeenCalledWith(8, { x: 0, y: 0, w: 960, h: 1080 });
+	});
+
+	it('ignores a collapsed (zero-size) docked zone — not a snap target', async () => {
+		layoutJson = DOCKED_LAYOUT;
+		const world = document.createElement('div');
+		world.className = 'world';
+		world.getBoundingClientRect = () => domRect(0, 0, 1920, 1080) as DOMRect;
+		const zoneEl = document.createElement('div');
+		zoneEl.setAttribute('data-type', 'zone');
+		zoneEl.setAttribute('data-w', 'dz');
+		zoneEl.getBoundingClientRect = () => domRect(0, 0, 0, 0) as DOMRect; // collapsed
+		world.appendChild(zoneEl);
+		document.body.appendChild(world);
+
+		pointerProbe.mockResolvedValue({ x: 0, y: 0, shift: false });
+		render(<DragSnapLayer />);
+		await settle();
+
+		await act(async () => {
+			handlers['arrange_zones']?.({ payload: {} });
+			await new Promise((r) => setTimeout(r, 0));
+		});
+		expect(snapWindow).not.toHaveBeenCalled();
+	});
+
+	it('ignores a docked zone element with no data-w id', async () => {
+		layoutJson = DOCKED_LAYOUT;
+		const world = document.createElement('div');
+		world.className = 'world';
+		world.getBoundingClientRect = () => domRect(0, 0, 1920, 1080) as DOMRect;
+		const zoneEl = document.createElement('div');
+		zoneEl.setAttribute('data-type', 'zone'); // no data-w attribute → skipped
+		zoneEl.getBoundingClientRect = () => domRect(100, 200, 800, 600) as DOMRect;
+		world.appendChild(zoneEl);
+		document.body.appendChild(world);
+
+		pointerProbe.mockResolvedValue({ x: 0, y: 0, shift: false });
+		render(<DragSnapLayer />);
+		await settle();
+
+		await act(async () => {
+			handlers['arrange_zones']?.({ payload: {} });
+			await new Promise((r) => setTimeout(r, 0));
+		});
+		expect(snapWindow).not.toHaveBeenCalled();
+	});
+
+	it('skips non-zone floating units (a plain widget + a group), arming only the zone', async () => {
+		layoutJson = MIXED_FLOATING_LAYOUT;
+		pointerProbe.mockResolvedValue({ x: 480, y: 540, shift: true }); // inside the left zone
+		render(<DragSnapLayer />);
+		await settle();
+
+		act(() => handlers['win_drag_start']?.({ payload: { hwnd: 7 } }));
+		await pollOnce();
+		await act(async () => {
+			handlers['win_drag_end']?.({ payload: { hwnd: 7 } });
+			await Promise.resolve();
+		});
+		// Only the single zone is a snap target; the group + clock contribute nothing.
+		expect(snapWindow).toHaveBeenCalledTimes(1);
+		expect(snapWindow).toHaveBeenCalledWith(7, { x: 0, y: 0, w: 960, h: 1080 });
+	});
+
+	it('unmounting before currentMonitor() resolves cancels the setup (alive guard)', async () => {
+		pointerProbe.mockResolvedValue({ x: 480, y: 540, shift: true });
+		const view = render(<DragSnapLayer />);
+		// A setState-after-unmount (the guard failing to bail) surfaces as a React act warning on
+		// console.error; test-setup.ts doesn't fail on it, so assert it explicitly.
+		const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+		view.unmount(); // tear down before currentMonitor()/loadLayoutRaw() resolve
+		// Let the in-flight currentMonitor()/loadLayoutRaw() promises settle against the dead instance;
+		// the `!alive` guard must bail without throwing or writing state.
+		await act(async () => void (await new Promise((r) => setTimeout(r, 0))));
+		expect(errorSpy).not.toHaveBeenCalled();
+		errorSpy.mockRestore();
+	});
+
+	it('unmounting mid-reload cancels it (reload alive guard)', async () => {
+		// Mount normally so the layout_changed listener is registered.
+		const view = render(<DragSnapLayer />);
+		await settle();
+
+		// Fire layout_changed (starts reload(), which suspends at `await loadLayoutRaw()`), then unmount
+		// synchronously in the same act() before the awaited continuation runs. When reload resumes its
+		// `!alive` guard must bail without writing zone refs or throwing. A failed bail would setState on
+		// the dead instance → a React act warning on console.error (test-setup.ts doesn't fail on it).
+		const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+		await act(async () => {
+			handlers['layout_changed']?.({ payload: {} });
+			view.unmount();
+			await new Promise((r) => setTimeout(r, 0));
+		});
+		expect(errorSpy).not.toHaveBeenCalled(); // reload's `!alive` branch returned cleanly
+		errorSpy.mockRestore();
+	});
+
 	it('snaps a window dragged (Shift held) over a docked zone on release', async () => {
 		layoutJson = DOCKED_LAYOUT;
 		const world = document.createElement('div');
@@ -220,4 +421,34 @@ describe('DragSnapLayer (zone widgets)', () => {
 
 		expect(snapWindow).toHaveBeenCalledWith(9, { x: 100, y: 200, w: 800, h: 600 });
 	});
+
+	// Kept LAST: a slow never-fully-drained probe loop is hard to fully quiesce within a test, so run
+	// it after every other case to avoid leaking a stray in-flight probe into a sibling.
+	it('does not overlap pointer probes — never more than one in flight at a time (busy guard)', async () => {
+		// A slow probe lets several poll ticks pile up. The busy guard must keep exactly one probe in
+		// flight: track concurrency and assert it never exceeds 1, even across many overlapping ticks.
+		let inFlight = 0;
+		let maxInFlight = 0;
+		pointerProbe.mockImplementation(async () => {
+			inFlight += 1;
+			maxInFlight = Math.max(maxInFlight, inFlight);
+			await new Promise((r) => setTimeout(r, 60)); // slower than POLL_MS (33ms) → ticks overlap
+			inFlight -= 1;
+			return { x: 0, y: 0, shift: false };
+		});
+		render(<DragSnapLayer />);
+		await settle();
+
+		act(() => handlers['win_drag_start']?.({ payload: { hwnd: 7 } }));
+		// Let many poll intervals fire while probes are slow.
+		await act(async () => void (await new Promise((r) => setTimeout(r, 250))));
+		act(() => handlers['win_drag_end']?.({ payload: { hwnd: 7 } })); // stops the interval
+
+		expect(pointerProbe).toHaveBeenCalled(); // probing happened
+		expect(maxInFlight).toBe(1); // the busy guard prevented any overlap
+
+		// Drain the last in-flight probe (60ms) so nothing leaks past this test.
+		await act(async () => void (await new Promise((r) => setTimeout(r, 80))));
+		expect(inFlight).toBe(0);
+	});
 });
diff --git a/client/src/lib/widgets/FlowNode.test.tsx b/client/src/lib/widgets/FlowNode.test.tsx
index f466770..c8bb734 100644
--- a/client/src/lib/widgets/FlowNode.test.tsx
+++ b/client/src/lib/widgets/FlowNode.test.tsx
@@ -123,4 +123,85 @@ describe('FlowNode — emitted CSS', () => {
 		expect(el.style.display).toBe('grid');
 		expect(el.style.gridTemplateColumns).toBe('repeat(3, 1fr)');
 	});
+
+	it('the top-level node fills its parent when fill is set (width/height 100%)', () => {
+		const view = render(
+			<FlowNode
+				node={container('root', 'col', [leaf(prim('A'))])}
+				parentKind="col"
+				renderLeaf={renderLeaf}
+				fill
+			/>
+		);
+		const el = view.container.querySelector('[data-id="root"]') as HTMLElement;
+		expect(el.style.width).toBe('100%');
+		expect(el.style.height).toBe('100%');
+	});
+});
+
+describe('FlowNode — overlap (stacking) parents', () => {
+	it('an overlap container stacks its children into the shared cell (grid 1/1)', () => {
+		const view = render(
+			<FlowNode
+				node={container('ov', 'col', [leaf(prim('A')), leaf(prim('B'))], { overlap: true })}
+				parentKind="col"
+				renderLeaf={renderLeaf}
+			/>
+		);
+		// overlapChildStyle puts every child in the same grid cell (gridArea 1 / 1 / …).
+		const a = view.container.querySelector('[data-id="A"]') as HTMLElement;
+		const b = view.container.querySelector('[data-id="B"]') as HTMLElement;
+		expect(a.style.gridArea).toBeTruthy();
+		expect(b.style.gridArea).toBe(a.style.gridArea);
+	});
+});
+
+describe('FlowNode — conditional containers (hiddenIds)', () => {
+	it('an unmet conditional container keeps its slot but hides its subtree', () => {
+		const node = container('cond', 'col', [leaf(prim('A'))]);
+		const view = render(
+			<FlowNode
+				node={node}
+				parentKind="col"
+				renderLeaf={renderLeaf}
+				hiddenIds={new Set(['cond'])}
+			/>
+		);
+		const el = view.container.querySelector('[data-id="cond"]') as HTMLElement;
+		expect(el.style.visibility).toBe('hidden');
+		expect(el.getAttribute('data-hidden')).toBe('');
+	});
+
+	it('a container not in hiddenIds is visible (no data-hidden marker)', () => {
+		const node = container('shown', 'col', [leaf(prim('A'))]);
+		const view = render(
+			<FlowNode
+				node={node}
+				parentKind="col"
+				renderLeaf={renderLeaf}
+				hiddenIds={new Set(['other'])}
+			/>
+		);
+		const el = view.container.querySelector('[data-id="shown"]') as HTMLElement;
+		expect(el.style.visibility).toBe('');
+		expect(el.getAttribute('data-hidden')).toBeNull();
+	});
+});
+
+describe('FlowNode — groups', () => {
+	it('renders an empty group box (resolveGroup yields an empty container) without throwing', () => {
+		// A group whose def has no child still resolves to a (col) container, so the group box renders
+		// its single empty-container child rather than nothing.
+		const emptyGroup = leaf(group('EG', { w: 20, h: 20 }, container('inner', 'col', [])));
+		const view = render(
+			<FlowNode node={emptyGroup} parentKind="col" renderLeaf={renderLeaf} library={lib} />
+		);
+		const box = view.container.querySelector('[data-id="EG"]') as HTMLElement;
+		expect(box.getAttribute('data-group')).toBe('');
+		expect(box.style.flexDirection).toBe('column');
+		// The namespaced empty container is rendered inside the group box and fills it.
+		const inner = view.container.querySelector('[data-id="EG/inner"]') as HTMLElement;
+		expect(inner).toBeTruthy();
+		expect(inner.style.width).toBe('100%');
+	});
 });
diff --git a/client/src/lib/widgets/GroupFrame.test.tsx b/client/src/lib/widgets/GroupFrame.test.tsx
index 118638b..b88ce90 100644
--- a/client/src/lib/widgets/GroupFrame.test.tsx
+++ b/client/src/lib/widgets/GroupFrame.test.tsx
@@ -93,4 +93,178 @@ describe('GroupFrame', () => {
 		expect(container.querySelector('.drag-overlay')).toBeNull();
 		expect(container.querySelector('.handle')).toBeNull();
 	});
+
+	it('context menu in edit mode selects the group then opens the menu at the cursor', () => {
+		const onSelect = vi.fn();
+		const onContextMenu = vi.fn();
+		const { container } = render(
+			<GroupFrame
+				id="grp-1"
+				rect={rect}
+				editMode
+				onSelect={onSelect}
+				onContextMenu={onContextMenu}
+			/>
+		);
+		fireEvent.contextMenu(box(container), { clientX: 33, clientY: 44 });
+		expect(onSelect).toHaveBeenCalledWith({ id: 'grp-1' });
+		expect(onContextMenu).toHaveBeenCalledWith({ id: 'grp-1', x: 33, y: 44 });
+	});
+
+	it('context menu does nothing outside edit mode (passive overlay)', () => {
+		const onContextMenu = vi.fn();
+		const { container } = render(
+			<GroupFrame id="grp-1" rect={rect} onContextMenu={onContextMenu} />
+		);
+		fireEvent.contextMenu(box(container));
+		expect(onContextMenu).not.toHaveBeenCalled();
+	});
+
+	it('suppresses the context menu (and skips selection) when suppressContextMenu() is true', () => {
+		const onSelect = vi.fn();
+		const onContextMenu = vi.fn();
+		const { container } = render(
+			<GroupFrame
+				id="grp-1"
+				rect={rect}
+				editMode
+				onSelect={onSelect}
+				onContextMenu={onContextMenu}
+				suppressContextMenu={() => true}
+			/>
+		);
+		fireEvent.contextMenu(box(container));
+		expect(onSelect).not.toHaveBeenCalled();
+		expect(onContextMenu).not.toHaveBeenCalled();
+	});
+
+	it('a press that never exceeds DRAG_SLOP is a click — no onChange, no commit', () => {
+		const onChange = vi.fn();
+		const onCommit = vi.fn();
+		const onSelect = vi.fn();
+		const { container } = render(
+			<GroupFrame
+				id="grp-1"
+				rect={rect}
+				editMode
+				selected
+				onChange={onChange}
+				onCommit={onCommit}
+				onSelect={onSelect}
+			/>
+		);
+		const ov = overlay(container);
+		fireEvent.pointerDown(ov, { button: 0, pointerId: 1, clientX: 10, clientY: 10 });
+		fireEvent.pointerMove(ov, { pointerId: 1, clientX: 12, clientY: 11 }); // within DRAG_SLOP
+		expect(onChange).not.toHaveBeenCalled();
+		fireEvent.pointerUp(ov, { pointerId: 1, clientX: 12, clientY: 11 });
+		expect(onCommit).not.toHaveBeenCalled();
+		// A click (no drag) on an already-selected group collapses the multi-selection to just it.
+		expect(onSelect).toHaveBeenCalledWith({ id: 'grp-1' });
+	});
+
+	it('right-button press is a free-move (skipFlow): commit skips flow + suppresses the next menu', () => {
+		const onChange = vi.fn();
+		const onCommit = vi.fn();
+		const onSuppressContextMenu = vi.fn();
+		const { container } = render(
+			<GroupFrame
+				id="grp-1"
+				rect={rect}
+				editMode
+				selected
+				onChange={onChange}
+				onCommit={onCommit}
+				onSuppressContextMenu={onSuppressContextMenu}
+			/>
+		);
+		const ov = overlay(container);
+		fireEvent.pointerDown(ov, { button: 2, pointerId: 1, clientX: 10, clientY: 10 });
+		fireEvent.pointerMove(ov, { pointerId: 1, clientX: 50, clientY: 10 }); // past DRAG_SLOP
+		expect(onChange).toHaveBeenCalled();
+		fireEvent.pointerUp(ov, { pointerId: 1, clientX: 50, clientY: 10 });
+		expect(onCommit).toHaveBeenCalledWith({ skipFlow: true });
+		expect(onSuppressContextMenu).toHaveBeenCalled();
+	});
+
+	it('right-button on a resize handle is ignored (free-move only applies to a move)', () => {
+		const onChange = vi.fn();
+		const onSelect = vi.fn();
+		const { container } = render(
+			<GroupFrame id="grp-1" rect={rect} editMode onChange={onChange} onSelect={onSelect} />
+		);
+		const handle = container.querySelector('.handle.se') as HTMLElement;
+		fireEvent.pointerDown(handle, { button: 2, pointerId: 1, clientX: 110, clientY: 80 });
+		fireEvent.pointerMove(handle, { pointerId: 1, clientX: 140, clientY: 110 });
+		expect(onSelect).not.toHaveBeenCalled();
+		expect(onChange).not.toHaveBeenCalled();
+	});
+
+	it('a middle-button press is reserved for panning — begin() bails, no select/change', () => {
+		const onChange = vi.fn();
+		const onSelect = vi.fn();
+		const { container } = render(
+			<GroupFrame id="grp-1" rect={rect} editMode onChange={onChange} onSelect={onSelect} />
+		);
+		const ov = overlay(container);
+		fireEvent.pointerDown(ov, { button: 1, pointerId: 1, clientX: 10, clientY: 10 });
+		fireEvent.pointerMove(ov, { pointerId: 1, clientX: 50, clientY: 10 });
+		expect(onSelect).not.toHaveBeenCalled();
+		expect(onChange).not.toHaveBeenCalled();
+	});
+
+	it('pointer events without any callbacks bound are no-ops (no throw)', () => {
+		const { container } = render(<GroupFrame id="grp-1" rect={rect} editMode selected />);
+		const ov = overlay(container);
+		expect(() => {
+			fireEvent.pointerDown(ov, { button: 0, pointerId: 1, clientX: 10, clientY: 10 });
+			fireEvent.pointerMove(ov, { pointerId: 1, clientX: 50, clientY: 10 });
+			fireEvent.pointerUp(ov, { pointerId: 1, clientX: 50, clientY: 10 });
+		}).not.toThrow();
+	});
+
+	it('pointerMove/Up with no active drag are no-ops (action === null guard)', () => {
+		const onChange = vi.fn();
+		const onCommit = vi.fn();
+		const { container } = render(
+			<GroupFrame id="grp-1" rect={rect} editMode onChange={onChange} onCommit={onCommit} />
+		);
+		const ov = overlay(container);
+		fireEvent.pointerMove(ov, { pointerId: 1, clientX: 50, clientY: 10 });
+		fireEvent.pointerUp(ov, { pointerId: 1, clientX: 50, clientY: 10 });
+		expect(onChange).not.toHaveBeenCalled();
+		expect(onCommit).not.toHaveBeenCalled();
+	});
+
+	it('applies multi / highlighted modifier classes', () => {
+		const { container } = render(
+			<GroupFrame id="grp-1" rect={rect} editMode selected multi highlighted name="My Group" />
+		);
+		const b = box(container);
+		expect(b.classList.contains('editable')).toBe(true);
+		expect(b.classList.contains('selected')).toBe(true);
+		expect(b.classList.contains('multi-member')).toBe(true);
+		expect(b.classList.contains('hl')).toBe(true);
+		// The move overlay uses the provided name in its aria-label.
+		expect(overlay(container).getAttribute('aria-label')).toBe('Move My Group widget');
+	});
+
+	it('adds the .active class while a drag is in progress', () => {
+		const { container } = render(<GroupFrame id="grp-1" rect={rect} editMode onChange={vi.fn()} />);
+		const ov = overlay(container);
+		expect(box(container).classList.contains('active')).toBe(false);
+		fireEvent.pointerDown(ov, { button: 0, pointerId: 1, clientX: 10, clientY: 10 });
+		expect(box(container).classList.contains('active')).toBe(true);
+		fireEvent.pointerUp(ov, { pointerId: 1, clientX: 10, clientY: 10 });
+		expect(box(container).classList.contains('active')).toBe(false);
+	});
+
+	it('fires onHover with the id on enter and null on leave', () => {
+		const onHover = vi.fn();
+		const { container } = render(<GroupFrame id="grp-1" rect={rect} onHover={onHover} />);
+		fireEvent.mouseEnter(box(container));
+		expect(onHover).toHaveBeenLastCalledWith('grp-1');
+		fireEvent.mouseLeave(box(container));
+		expect(onHover).toHaveBeenLastCalledWith(null);
+	});
 });
diff --git a/client/src/lib/widgets/ImageHost.test.tsx b/client/src/lib/widgets/ImageHost.test.tsx
new file mode 100644
index 0000000..981c170
--- /dev/null
+++ b/client/src/lib/widgets/ImageHost.test.tsx
@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { render, waitFor, cleanup, act } from '@testing-library/react';
+
+// Mock the Tauri asset resolver (outer ring). The pure direct-URL classifier (core/imageSrc) is left
+// REAL — it's already unit-tested — so we verify the host routes each src kind correctly.
+const wallpaperAssetUrl = vi.fn();
+vi.mock('../overlay', () => ({ wallpaperAssetUrl: (n: string) => wallpaperAssetUrl(n) }));
+
+import ImageHost from './ImageHost';
+
+afterEach(() => {
+	cleanup();
+	vi.clearAllMocks();
+});
+
+function imgSrc(container: HTMLElement): string | null {
+	return container.querySelector('img')?.getAttribute('src') ?? null;
+}
+
+describe('ImageHost', () => {
+	it('uses a direct URL verbatim and never hits the asset resolver', async () => {
+		const { container } = render(<ImageHost src="https://example.com/a.png" />);
+		await waitFor(() => expect(imgSrc(container)).toBe('https://example.com/a.png'));
+		expect(wallpaperAssetUrl).not.toHaveBeenCalled();
+	});
+
+	it('resolves a bare filename against the wallpapers/ folder', async () => {
+		wallpaperAssetUrl.mockResolvedValue('asset://localhost/cat.png');
+		const { container } = render(<ImageHost src="  cat.png  " fit="cover" alt="a cat" />);
+		await waitFor(() => expect(imgSrc(container)).toBe('asset://localhost/cat.png'));
+		expect(wallpaperAssetUrl).toHaveBeenCalledWith('cat.png'); // trimmed
+		const img = container.querySelector('img')!;
+		expect(img.getAttribute('alt')).toBe('a cat');
+	});
+
+	it('renders the empty state for a blank/whitespace src (no resolve)', () => {
+		const { container } = render(<ImageHost src="   " />);
+		expect(container.querySelector('[data-empty="true"]')).toBeTruthy();
+		expect(imgSrc(container)).toBeNull();
+		expect(wallpaperAssetUrl).not.toHaveBeenCalled();
+	});
+
+	it('treats a missing src as blank (the default empty string)', () => {
+		const { container } = render(<ImageHost />);
+		expect(container.querySelector('[data-empty="true"]')).toBeTruthy();
+		expect(wallpaperAssetUrl).not.toHaveBeenCalled();
+	});
+
+	it('defends against a null src (the ?? "" guard)', () => {
+		// A malformed layout could feed a null src past the default param; the guard coalesces it.
+		const { container } = render(<ImageHost src={null as unknown as string} />);
+		expect(container.querySelector('[data-empty="true"]')).toBeTruthy();
+		expect(wallpaperAssetUrl).not.toHaveBeenCalled();
+	});
+
+	it('ignores a stale resolve after the src changes (cleanup guards the late setUrl)', async () => {
+		let resolveFirst!: (u: string) => void;
+		wallpaperAssetUrl
+			.mockImplementationOnce(() => new Promise<string>((r) => (resolveFirst = r)))
+			.mockResolvedValueOnce('asset://localhost/second.png');
+		const { container, rerender } = render(<ImageHost src="first.png" />);
+		rerender(<ImageHost src="second.png" />); // first effect cleaned up before it resolves
+		await waitFor(() => expect(imgSrc(container)).toBe('asset://localhost/second.png'));
+		await act(async () => {
+			resolveFirst('asset://localhost/first.png'); // late: must NOT overwrite
+		});
+		expect(imgSrc(container)).toBe('asset://localhost/second.png');
+	});
+});
diff --git a/client/src/lib/widgets/Inspector.configFields.test.tsx b/client/src/lib/widgets/Inspector.configFields.test.tsx
new file mode 100644
index 0000000..22f8010
--- /dev/null
+++ b/client/src/lib/widgets/Inspector.configFields.test.tsx
@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import Inspector from './Inspector';
+import type { WidgetInstance } from '../core/layoutTree';
+import type { ConfigField } from '../core/widget';
+import type { LayoutOp } from './ops';
+
+// Mock the Tauri-backed DDC adapter so the monitorSources field's effect resolves to "no inputs"
+// (its detect path calls a backend command via lib/ddc/monitors) instead of hitting `invoke`.
+vi.mock('../ddc/monitors', () => ({
+	listMonitorInputs: vi.fn().mockResolvedValue([]),
+	setMonitorInput: vi.fn().mockResolvedValue(true)
+}));
+
+// A `gauge`-typed widget: a real meta is registered (widget.ts BUILTIN_METAS), so fieldDefault can
+// fall back to the type's defaultConfig where a field declares no explicit `default`.
+const gaugeWidget = (config: Record<string, unknown> = {}): WidgetInstance => ({
+	id: 'w1',
+	type: 'gauge',
+	rect: { x: 0, y: 0, w: 110, h: 110 },
+	config
+});
+
+// Pull the single patchWidget(config) op out of the recorded calls (the only op these fields emit).
+const lastConfigPatch = (onOp: ReturnType<typeof vi.fn>): Record<string, unknown> | undefined => {
+	const calls = onOp.mock.calls.map((c) => c[0] as LayoutOp);
+	const patch = [...calls].reverse().find((o) => o.op === 'patchWidget');
+	return patch && patch.op === 'patchWidget'
+		? (patch.patch.config as Record<string, unknown>)
+		: undefined;
+};
+
+// The properties form is a `role="tabpanel"`; scope queries to it so the (always-rendered, just
+// collapsed) Add-palette above — which has its own buttons/selects/textareas — never aliases a match.
+const panel = (): HTMLElement => screen.getByRole('tabpanel');
+
+describe('Inspector config-field rendering (per ConfigField kind)', () => {
+	it('renders a text field and emits the typed value into config (empty → undefined)', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [{ key: 'label', label: 'label', kind: 'text' }];
+		render(
+			<Inspector widget={gaugeWidget()} placement="floating" configFields={fields} onOp={onOp} />
+		);
+		const input = within(panel()).getByRole('textbox', { name: 'label' });
+		fireEvent.input(input, { target: { value: 'CPU' } });
+		expect(lastConfigPatch(onOp)).toEqual({ label: 'CPU' });
+
+		onOp.mockClear();
+		fireEvent.input(input, { target: { value: '' } });
+		expect(lastConfigPatch(onOp)).toEqual({ label: undefined });
+	});
+
+	it('renders a number field and coerces the value (empty → undefined, else Number)', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [{ key: 'max', label: 'max', kind: 'number' }];
+		render(
+			<Inspector widget={gaugeWidget()} placement="floating" configFields={fields} onOp={onOp} />
+		);
+		const input = within(panel()).getByRole('spinbutton', { name: 'max' });
+		fireEvent.input(input, { target: { value: '42' } });
+		expect(lastConfigPatch(onOp)).toEqual({ max: 42 });
+
+		onOp.mockClear();
+		fireEvent.input(input, { target: { value: '' } });
+		expect(lastConfigPatch(onOp)).toEqual({ max: undefined });
+	});
+
+	it('renders a color field as a text input with a "css color" placeholder', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [{ key: 'color', label: 'color', kind: 'color' }];
+		render(
+			<Inspector widget={gaugeWidget()} placement="floating" configFields={fields} onOp={onOp} />
+		);
+		const input = within(panel()).getByRole('textbox', { name: 'color' }) as HTMLInputElement;
+		expect(input.placeholder).toBe('css color');
+		fireEvent.input(input, { target: { value: '#0f0' } });
+		expect(lastConfigPatch(onOp)).toEqual({ color: '#0f0' });
+	});
+
+	it('renders a select field as a Select and emits the picked option', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [
+			{ key: 'style', label: 'style', kind: 'select', options: ['arc', 'circle', 'linear'] }
+		];
+		render(
+			<Inspector
+				widget={gaugeWidget({ style: 'arc' })}
+				placement="floating"
+				configFields={fields}
+				onOp={onOp}
+			/>
+		);
+		// The shared <Select> is a trigger + portaled menu; open it (in-panel, found by aria-label) and
+		// pick a different value (the menu itself is portaled to <body>, so screen-level for the option).
+		fireEvent.click(within(panel()).getByLabelText('style'));
+		fireEvent.click(screen.getByText('circle', { selector: '.np-select-opt-label' }));
+		expect(lastConfigPatch(onOp)).toEqual({ style: 'circle' });
+	});
+
+	it('fills a select with a runtime catalog (audioOutputs) plus the system-default row', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [
+			{
+				key: 'device',
+				label: 'output device',
+				kind: 'select',
+				options: [],
+				catalog: 'audioOutputs'
+			}
+		];
+		render(
+			<Inspector
+				widget={gaugeWidget()}
+				placement="floating"
+				configFields={fields}
+				audioOutputs={[{ id: 'spk', name: 'Speakers' }]}
+				onOp={onOp}
+			/>
+		);
+		fireEvent.click(within(panel()).getByLabelText('output device'));
+		expect(screen.getByText('System default', { selector: '.np-select-opt-label' })).toBeTruthy();
+		fireEvent.click(screen.getByText('Speakers', { selector: '.np-select-opt-label' }));
+		expect(lastConfigPatch(onOp)).toEqual({ device: 'spk' });
+	});
+
+	it('renders an expr (formula) field as a textarea with an ExprHint flagging unknown sensors', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [
+			{ key: 'value', label: 'value (formula)', kind: 'expr', result: 'number' }
+		];
+		render(
+			<Inspector
+				widget={gaugeWidget({ value: 'cpu.total + mystery.sensor' })}
+				placement="floating"
+				configFields={fields}
+				sensors={['cpu.total']}
+				onOp={onOp}
+			/>
+		);
+		// The hint lists referenced sensors; the unknown one carries a "?" + the .unknown class.
+		const hint = document.querySelector('.cfg-expr-refs') as HTMLElement;
+		expect(hint).toBeTruthy();
+		expect(within(hint).getByText(/cpu\.total/)).toBeTruthy();
+		expect(hint.querySelector('.unknown')?.textContent).toContain('mystery.sensor');
+
+		// The expr textarea has no aria-label; its placeholder identifies it ('expression' for a number
+		// result). Querying by role+name would fold in the ExprHint text the label also wraps.
+		const area = within(panel()).getByPlaceholderText('expression');
+		fireEvent.input(area, { target: { value: 'cpu.total / 2' } });
+		expect(lastConfigPatch(onOp)).toEqual({ value: 'cpu.total / 2' });
+	});
+
+	it('renders a toggle as a labelled checkbox and emits the boolean', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [{ key: 'fill', label: 'fill', kind: 'toggle' }];
+		render(
+			<Inspector
+				widget={gaugeWidget({ fill: false })}
+				placement="floating"
+				configFields={fields}
+				onOp={onOp}
+			/>
+		);
+		const box = within(panel()).getByRole('checkbox', { name: 'fill' }) as HTMLInputElement;
+		expect(box.checked).toBe(false);
+		fireEvent.click(box);
+		expect(lastConfigPatch(onOp)).toEqual({ fill: true });
+	});
+
+	it('renders a macro field as a list editor that adds an action via setConfig', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [{ key: 'actions', label: 'actions (macro)', kind: 'macro' }];
+		render(
+			<Inspector
+				widget={{ ...gaugeWidget(), type: 'button', config: { actions: [] } }}
+				placement="floating"
+				configFields={fields}
+				onOp={onOp}
+			/>
+		);
+		// Empty macro shows the inert hint; "+ action" appends one row.
+		expect(within(panel()).getByText(/the button is inert/i)).toBeTruthy();
+		fireEvent.click(within(panel()).getByRole('button', { name: '+ action' }));
+		const patch = lastConfigPatch(onOp);
+		expect(Array.isArray(patch?.actions)).toBe(true);
+		expect((patch?.actions as unknown[]).length).toBe(1);
+	});
+
+	it('renders a monitorSources field, degrading to a manual code entry when none detected', async () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [{ key: 'sources', label: 'sources', kind: 'monitorSources' }];
+		render(
+			<Inspector
+				widget={{ ...gaugeWidget(), type: 'monitorswitch', config: {} }}
+				placement="floating"
+				configFields={fields}
+				onOp={onOp}
+			/>
+		);
+		// The header label appears immediately; the manual fallback shows after the (mocked) detect resolves.
+		expect(within(panel()).getByText('sources', { selector: '.hd' })).toBeTruthy();
+		const manual = await screen.findByPlaceholderText('0x11=Desktop, 0x12=Switch');
+		fireEvent.change(manual, { target: { value: '0x11=Desktop' } });
+		expect(lastConfigPatch(onOp)).toEqual({ sources: '0x11=Desktop' });
+	});
+});
+
+describe('Inspector config-field reset button', () => {
+	it('resets a field to its explicit default', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const fields: ConfigField[] = [
+			{ key: 'style', label: 'style', kind: 'select', options: ['arc', 'circle'], default: 'arc' }
+		];
+		render(
+			<Inspector
+				widget={gaugeWidget({ style: 'circle' })}
+				placement="floating"
+				configFields={fields}
+				onOp={onOp}
+			/>
+		);
+		// The reset button shows "↺" (which becomes its accessible name); identify it by its title.
+		fireEvent.click(within(panel()).getByTitle('Reset to default'));
+		expect(lastConfigPatch(onOp)).toEqual({ style: 'arc' });
+	});
+
+	it('disables the reset button when neither the field nor the meta defines a default', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		// A bespoke key absent from the gauge meta's defaultConfig → no default → disabled reset.
+		const fields: ConfigField[] = [{ key: 'nodefault', label: 'no default', kind: 'text' }];
+		render(
+			<Inspector widget={gaugeWidget()} placement="floating" configFields={fields} onOp={onOp} />
+		);
+		expect(within(panel()).getByTitle('Reset to default')).toBeDisabled();
+	});
+});
+
+describe('Inspector advanced config JSON / CSS escape hatch', () => {
+	it('commits valid raw-JSON config on blur via patchWidget', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(
+			<Inspector
+				widget={gaugeWidget({ label: 'CPU' })}
+				placement="floating"
+				configFields={[]}
+				onOp={onOp}
+			/>
+		);
+		const area = within(panel()).getByRole('textbox', { name: /config \(JSON\)/i });
+		expect((area as HTMLTextAreaElement).value).toContain('"label": "CPU"');
+		fireEvent.change(area, { target: { value: '{ "label": "RAM", "unit": "%" }' } });
+		fireEvent.blur(area);
+		const patch = lastConfigPatch(onOp);
+		expect(patch).toEqual({ label: 'RAM', unit: '%' });
+	});
+
+	it('flags invalid raw JSON (error class) without emitting a patch', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector widget={gaugeWidget()} placement="floating" configFields={[]} onOp={onOp} />);
+		const area = within(panel()).getByRole('textbox', { name: /config \(JSON\)/i });
+		fireEvent.change(area, { target: { value: '{ not json' } });
+		fireEvent.blur(area);
+		expect(area.className).toContain('error');
+		expect(onOp.mock.calls.some((c) => c[0].op === 'patchWidget')).toBe(false);
+	});
+});
diff --git a/client/src/lib/widgets/Inspector.css b/client/src/lib/widgets/Inspector.css
index 384129c..176f73f 100644
--- a/client/src/lib/widgets/Inspector.css
+++ b/client/src/lib/widgets/Inspector.css
@@ -42,10 +42,24 @@
 	font-size: var(--text-sm);
 }
 
+/* A MAJOR palette section header (Templates / Library) — full-width, set off from the section above
+   with a hairline rule + breathing room, so the top-level groups read as distinct sections rather
+   than running together under uniform gaps. Scoped to palette CHILDREN so the many other `.hd`
+   headers in the property panel (config labels, Align, Visibility, Params, node headers…) keep their
+   plain styling. */
+.inspector .palette > .hd {
+	flex: 1 1 100%;
+	margin-top: var(--space-4);
+	padding-top: var(--space-4);
+	border-top: 1px solid var(--ui-border);
+}
+
 /* A palette CATEGORY header (Meters / Clocks / Utility / per-plugin) — one step below .hd
-   (dim, not accent) so the widget-type groups don't compete with the Library/Templates sections. */
+   (dim, not accent) so the widget-type groups don't compete with the Library/Templates sections.
+   A small top margin separates adjacent categories without the heavy rule of a major section. */
 .inspector .hd2 {
 	flex: 1 1 100%;
+	margin-top: var(--space-2);
 	color: var(--ui-fg-dim);
 	text-transform: uppercase;
 	letter-spacing: 1px;
@@ -216,6 +230,59 @@
 	min-height: var(--control-h);
 }
 
+/* Checkboxes: a themed custom control. The generic `width: 100%` above otherwise stretched the native
+   box full-width with a centered tick (looked off). Drawn as a small accent-on-check box that sits at
+   its natural size, vertically centered with its label (see the toggle field layout below). */
+.inspector input[type='checkbox'] {
+	appearance: none;
+	-webkit-appearance: none;
+	flex: 0 0 auto;
+	width: 16px;
+	height: 16px;
+	margin: 0;
+	padding: 0;
+	border: 1px solid var(--ui-border-strong);
+	border-radius: 4px;
+	background: var(--ui-raised);
+	cursor: pointer;
+	position: relative;
+	transition: background var(--motion-fast, 100ms) var(--ease-out, ease-out),
+		border-color var(--motion-fast, 100ms) var(--ease-out, ease-out);
+}
+.inspector input[type='checkbox']:hover {
+	border-color: rgb(var(--ui-accent-rgb));
+}
+.inspector input[type='checkbox']:checked {
+	background: rgb(var(--ui-accent-rgb));
+	border-color: rgb(var(--ui-accent-rgb));
+}
+/* The tick: a rotated box-corner centered in the 16px box. */
+.inspector input[type='checkbox']:checked::after {
+	content: '';
+	position: absolute;
+	left: 5px;
+	top: 2px;
+	width: 4px;
+	height: 8px;
+	border: solid var(--ui-accent-fg, #fff);
+	border-width: 0 2px 2px 0;
+	transform: rotate(45deg);
+}
+.inspector input[type='checkbox']:focus-visible {
+	outline: none;
+	box-shadow: 0 0 0 2px rgba(var(--ui-accent-rgb), 0.4);
+}
+
+/* A toggle config field: checkbox + label on one vertically-centered row (.check supplies row + center
+   + gap), with the reset button still pinned top-right and any help text wrapping below. */
+.inspector .cfg-toggle .check {
+	cursor: pointer;
+	padding-right: var(--space-4);
+}
+.inspector .cfg-toggle .check span {
+	user-select: none;
+}
+
 /* A crisp mint focus ring (the box-shadow IS the focus affordance, so the default outline is off). */
 .inspector input:focus,
 .inspector textarea:focus,
@@ -489,3 +556,59 @@
 .inspector .data-err {
 	color: var(--ui-danger-fg);
 }
+
+/* Add-palette hover preview (Tier 2): a floating card with a LIVE widget render + its name/description.
+   position:fixed so it escapes the rail's overflow; JS positions it to the left of the hovered chip.
+   pointer-events:none so it never steals the hover/click from the palette (which would make it flicker). */
+.inspector .palette-preview {
+	position: fixed;
+	z-index: 1000;
+	width: 216px;
+	display: flex;
+	flex-direction: column;
+	gap: var(--space-2);
+	padding: var(--space-2);
+	background: var(--ui-raised);
+	border: 1px solid var(--ui-border-strong);
+	border-radius: var(--radius-md, 6px);
+	box-shadow: 0 6px 24px var(--ui-scrim, rgba(0, 0, 0, 0.45));
+	pointer-events: none;
+}
+.inspector .palette-preview .pp-stage {
+	width: 200px;
+	height: 120px;
+	overflow: hidden;
+	border-radius: var(--radius-sm, 4px);
+	background: var(--ui-sunken, rgba(0, 0, 0, 0.25));
+}
+.inspector .palette-preview .pp-meta {
+	display: flex;
+	flex-direction: column;
+	gap: 2px;
+}
+.inspector .palette-preview .pp-name {
+	font-weight: 600;
+	font-size: var(--text-md);
+}
+.inspector .palette-preview .pp-desc {
+	font-size: var(--text-sm);
+	color: var(--ui-fg-dim);
+	line-height: 1.3;
+}
+.inspector .palette-preview .pp-hint {
+	margin-top: 2px;
+	font-size: var(--text-sm);
+	color: var(--ui-fg-dim);
+	font-style: italic;
+	opacity: 0.85;
+}
+
+/* Add-palette filter (search) + its no-matches note. */
+.inspector .palette-filter {
+	width: 100%;
+}
+.inspector .palette-empty {
+	color: var(--ui-fg-dim);
+	font-size: var(--text-sm);
+	padding: var(--space-2);
+}
diff --git a/client/src/lib/widgets/Inspector.palette.test.tsx b/client/src/lib/widgets/Inspector.palette.test.tsx
new file mode 100644
index 0000000..59ccaec
--- /dev/null
+++ b/client/src/lib/widgets/Inspector.palette.test.tsx
@@ -0,0 +1,141 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import Inspector from './Inspector';
+import type { WidgetDef } from '../core/layoutTree';
+import type { LayoutOp } from './ops';
+
+// WidgetPreview (rendered into the hover popover) seeds a telemetry hub + renders real meters; the
+// palette tests only assert on the palette list + emitted ops, never the popover, so we stub it to a
+// cheap div to keep these tests fast and free of meter-render churn.
+vi.mock('./WidgetPreview', () => ({ default: () => null }));
+
+const palette = () =>
+	screen.getByText('＋ Add widget · floating').closest('details') as HTMLElement;
+
+const widgetTypes = [
+	{ type: 'gauge', label: 'Gauge', category: 'Meters' },
+	{ type: 'clock', label: 'Clock', category: 'Clocks' }
+];
+
+describe('Inspector add-palette — widget types', () => {
+	it('groups widget types by category and emits addWidget on click', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector widgetTypes={widgetTypes} onOp={onOp} />);
+		// Category headers + the entries under them.
+		expect(within(palette()).getByText('Meters', { selector: '.hd2' })).toBeTruthy();
+		expect(within(palette()).getByText('Clocks', { selector: '.hd2' })).toBeTruthy();
+		fireEvent.click(within(palette()).getByRole('button', { name: /^Gauge/ }));
+		expect(onOp).toHaveBeenCalledWith({ op: 'addWidget', widgetType: 'gauge' });
+	});
+
+	it('names its destination "into <container.kind>" when a container is selected', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(
+			<Inspector
+				widgetTypes={widgetTypes}
+				container={{ id: 'root', kind: 'col', children: [] }}
+				onOp={onOp}
+			/>
+		);
+		expect(screen.getByText('＋ Add widget · into col')).toBeTruthy();
+	});
+
+	it('puts the widget type on the dataTransfer when dragged from the palette', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector widgetTypes={widgetTypes} onOp={onOp} />);
+		const setData = vi.fn();
+		fireEvent.dragStart(within(palette()).getByRole('button', { name: /^Gauge/ }), {
+			dataTransfer: { setData }
+		});
+		expect(setData).toHaveBeenCalledWith('text/x-widget-type', 'gauge');
+	});
+});
+
+describe('Inspector add-palette — templates', () => {
+	it('inserts a no-param built-in template via insertTemplate', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector onOp={onOp} />);
+		// "System monitor" is a built-in template with no params → a plain insert button.
+		fireEvent.click(within(palette()).getByRole('button', { name: /^System monitor/ }));
+		expect(onOp).toHaveBeenCalledWith({ op: 'insertTemplate', templateId: 'system' });
+	});
+
+	it('renders a param template as an options form and passes the chosen options on insert', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector onOp={onOp} />);
+		// "Clock (JP weekday)" (clock-jp) carries ParamSpecs → an options form with selects + Insert.
+		const weekday = within(palette()).getByLabelText('Clock (JP weekday) — Weekday');
+		fireEvent.click(weekday);
+		fireEvent.click(screen.getByText('English', { selector: '.np-select-opt-label' }));
+		const insert = within(palette())
+			.getAllByText('＋ Insert')
+			.find((b) => b.getAttribute('title')?.includes('Analog icon'))!;
+		fireEvent.click(insert);
+		const call = onOp.mock.calls.map((c) => c[0]).find((o) => o.op === 'insertTemplate');
+		expect(call && call.op === 'insertTemplate' && call.templateId).toBe('clock-jp');
+		expect(call && call.op === 'insertTemplate' && call.options?.weekdayLang).toBe('en');
+	});
+
+	it('shows a 👁 preview affordance per template and routes it to onPreviewTemplate', () => {
+		const onPreviewTemplate = vi.fn<(id: string) => void>();
+		render(<Inspector onOp={vi.fn()} onPreviewTemplate={onPreviewTemplate} />);
+		// The 👁 button next to "System monitor" jumps to the designer's read-only preview.
+		fireEvent.click(
+			within(palette()).getByLabelText('Preview System monitor in the widget designer')
+		);
+		expect(onPreviewTemplate).toHaveBeenCalledWith('system');
+	});
+});
+
+describe('Inspector add-palette — library defs', () => {
+	const def = (id: string, name: string): WidgetDef => ({
+		id,
+		name,
+		size: { w: 100, h: 40 },
+		child: {
+			id: `${id}-c`,
+			unit: { id: `${id}-w`, type: 'clock', rect: { x: 0, y: 0, w: 1, h: 1 }, config: {} }
+		}
+	});
+
+	it('lists library defs and inserts an instance on click', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector defs={[def('d1', 'My Widget')]} onOp={onOp} />);
+		expect(within(palette()).getByText('Library', { selector: '.hd' })).toBeTruthy();
+		fireEvent.click(within(palette()).getByRole('button', { name: 'My Widget' }));
+		expect(onOp).toHaveBeenCalledWith({ op: 'insertWidget', defId: 'd1' });
+	});
+
+	it('routes the ✕ delete through onDeleteDef when provided', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const onDeleteDef = vi.fn<(id: string, name: string) => void>();
+		render(<Inspector defs={[def('d1', 'My Widget')]} onOp={onOp} onDeleteDef={onDeleteDef} />);
+		fireEvent.click(within(palette()).getByLabelText('Delete My Widget from library'));
+		expect(onDeleteDef).toHaveBeenCalledWith('d1', 'My Widget');
+		// With a handler supplied, the plain deleteDef op is NOT emitted.
+		expect(onOp.mock.calls.some((c) => c[0].op === 'deleteDef')).toBe(false);
+	});
+
+	it('falls back to a deleteDef op when no onDeleteDef handler is given (overlay)', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector defs={[def('d1', 'My Widget')]} onOp={onOp} />);
+		fireEvent.click(within(palette()).getByLabelText('Delete My Widget from library'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'deleteDef', defId: 'd1' });
+	});
+});
+
+describe('Inspector add-palette — filter', () => {
+	it('narrows widgets, templates and library to the query, then shows an empty state', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector widgetTypes={widgetTypes} onOp={onOp} />);
+		const filter = screen.getByLabelText('Filter the add palette');
+		fireEvent.change(filter, { target: { value: 'gauge' } });
+		// The Gauge widget survives; the Clock widget + every (non-matching) template is filtered out.
+		expect(within(palette()).getByRole('button', { name: /^Gauge/ })).toBeTruthy();
+		expect(within(palette()).queryByRole('button', { name: /^Clock$/ })).toBeNull();
+		expect(within(palette()).queryByRole('button', { name: /^System monitor/ })).toBeNull();
+
+		fireEvent.change(filter, { target: { value: 'zzz-no-such-widget' } });
+		expect(within(palette()).getByText(/No matches for/)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/Inspector.panels.test.tsx b/client/src/lib/widgets/Inspector.panels.test.tsx
new file mode 100644
index 0000000..93cc523
--- /dev/null
+++ b/client/src/lib/widgets/Inspector.panels.test.tsx
@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import Inspector from './Inspector';
+import { container, group, leaf, type Group, type WidgetDef } from '../core/layoutTree';
+import type { LayoutOp } from './ops';
+
+// The hover-preview popover renders real meters; the panel tests never touch it.
+vi.mock('./WidgetPreview', () => ({ default: () => null }));
+
+const panel = (): HTMLElement => screen.getByRole('tabpanel');
+const lastOp = (onOp: ReturnType<typeof vi.fn>, op: string): LayoutOp | undefined =>
+	[...onOp.mock.calls.map((c) => c[0] as LayoutOp)].reverse().find((o) => o.op === op);
+
+describe('Inspector container property panel', () => {
+	it('shows the kind · id header and emits patchContainer on a kind change', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const c = container('root', 'col', [], { align: 'stretch' });
+		render(<Inspector container={c} onOp={onOp} />);
+		expect(within(panel()).getByText('col · root')).toBeTruthy();
+		fireEvent.click(within(panel()).getByLabelText('kind'));
+		fireEvent.click(screen.getByText('row (hsplit)', { selector: '.np-select-opt-label' }));
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'root',
+			patch: { kind: 'row' }
+		});
+	});
+
+	it('shows grid cols/rows only for a grid and patches them', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const colC = container('root', 'col', []);
+		const { rerender } = render(<Inspector container={colC} onOp={onOp} />);
+		expect(within(panel()).queryByRole('spinbutton', { name: 'cols' })).toBeNull();
+
+		const gridC = container('g', 'grid', [], { cols: 2, rows: 2 });
+		rerender(<Inspector container={gridC} onOp={onOp} />);
+		fireEvent.input(within(panel()).getByRole('spinbutton', { name: 'cols' }), {
+			target: { value: '3' }
+		});
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'g',
+			patch: { cols: 3 }
+		});
+	});
+
+	it('patches the gap', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector container={container('root', 'col', [])} onOp={onOp} />);
+		fireEvent.input(within(panel()).getByRole('spinbutton', { name: 'gap' }), {
+			target: { value: '8' }
+		});
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'root',
+			patch: { gap: 8 }
+		});
+	});
+
+	it('toggles "stack children (overlap)"', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector container={container('root', 'col', [])} onOp={onOp} />);
+		fireEvent.click(within(panel()).getByRole('checkbox', { name: /stack children/i }));
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'root',
+			patch: { overlap: true }
+		});
+	});
+
+	it('reflects an fr basis as "grow" and clears it to fit on "hug — fit children"', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const c = container('root', 'col', [], { basis: { fr: 1 } });
+		render(<Inspector container={c} onOp={onOp} />);
+		const trigger = within(panel()).getByLabelText('container size in parent');
+		expect(trigger).toHaveTextContent(/grow/i);
+		fireEvent.click(trigger);
+		fireEvent.click(screen.getByText('hug — fit children', { selector: '.np-select-opt-label' }));
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'root',
+			patch: { basis: undefined }
+		});
+	});
+
+	it('shows a fixed-px size input when the basis is numeric and patches it', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const c = container('root', 'col', [], { basis: 120 });
+		render(<Inspector container={c} onOp={onOp} />);
+		fireEvent.input(within(panel()).getByRole('spinbutton', { name: 'size (px)' }), {
+			target: { value: '200' }
+		});
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'root',
+			patch: { basis: 200 }
+		});
+	});
+
+	it('shows grid-cell sizing fields only when isGridCell, and patches cellW', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const c = container('cell', 'col', []);
+		const { rerender } = render(<Inspector container={c} onOp={onOp} />);
+		expect(within(panel()).queryByText('Grid cell', { selector: '.hd' })).toBeNull();
+
+		rerender(<Inspector container={c} isGridCell onOp={onOp} />);
+		expect(within(panel()).getByText('Grid cell', { selector: '.hd' })).toBeTruthy();
+		fireEvent.input(within(panel()).getByRole('spinbutton', { name: 'width (px)' }), {
+			target: { value: '64' }
+		});
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'cell',
+			patch: { cellW: 64 }
+		});
+	});
+
+	it('emits makeWidget and remove from the container actions', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector container={container('root', 'col', [])} onOp={onOp} />);
+		fireEvent.click(within(panel()).getByRole('button', { name: 'Make widget' }));
+		expect(lastOp(onOp, 'makeWidget')).toEqual({ op: 'makeWidget', id: 'root' });
+		fireEvent.click(within(panel()).getByRole('button', { name: 'Remove' }));
+		expect(lastOp(onOp, 'remove')).toEqual({ op: 'remove', id: 'root' });
+	});
+
+	it('turns the container conditional via the Visibility editor', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector container={container('root', 'col', [])} onOp={onOp} />);
+		fireEvent.click(within(panel()).getByRole('checkbox', { name: /Conditional — show \/ hide/i }));
+		expect(lastOp(onOp, 'patchContainer')).toEqual({
+			op: 'patchContainer',
+			id: 'root',
+			patch: { condition: { kind: 'appOpen' } }
+		});
+	});
+});
+
+describe('Inspector group property panel', () => {
+	const groupUnit = (over: Partial<Group> = {}): Group =>
+		group(
+			'grp1',
+			{ w: 100, h: 40 },
+			{ id: 'c', unit: { id: 'w', type: 'clock', rect: { x: 0, y: 0, w: 1, h: 1 }, config: {} } },
+			{ name: 'My Group', ...over }
+		);
+
+	it('shows the group · id header and patches the name', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector groupUnit={groupUnit()} onOp={onOp} />);
+		expect(screen.getByText('group · grp1')).toBeTruthy();
+		fireEvent.input(screen.getByDisplayValue('My Group'), { target: { value: 'Renamed' } });
+		expect(lastOp(onOp, 'patchGroup')).toEqual({
+			op: 'patchGroup',
+			id: 'grp1',
+			patch: { name: 'Renamed' }
+		});
+	});
+
+	it('shows "inline group (no def)" when no def backs the group', () => {
+		render(<Inspector groupUnit={groupUnit()} onOp={vi.fn()} />);
+		expect(screen.getByText('inline group (no def)')).toBeTruthy();
+	});
+
+	it('renders def fields when a def is supplied, and renames the def', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const def: WidgetDef = {
+			id: 'def1',
+			name: 'Lib Widget',
+			size: { w: 120, h: 50 },
+			child: {
+				id: 'c',
+				unit: { id: 'w', type: 'clock', rect: { x: 0, y: 0, w: 1, h: 1 }, config: {} }
+			}
+		};
+		render(<Inspector groupUnit={groupUnit({ def: 'def1' })} def={def} onOp={onOp} />);
+		fireEvent.input(screen.getByDisplayValue('Lib Widget'), { target: { value: 'New Name' } });
+		expect(lastOp(onOp, 'renameDef')).toEqual({ op: 'renameDef', defId: 'def1', name: 'New Name' });
+		fireEvent.click(screen.getByRole('button', { name: 'Edit def…' }));
+		expect(lastOp(onOp, 'editDef')).toEqual({ op: 'editDef', defId: 'def1' });
+	});
+
+	it('adds a def param from the key/target inputs', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const def: WidgetDef = {
+			id: 'def1',
+			name: 'Lib Widget',
+			size: { w: 120, h: 50 },
+			child: {
+				id: 'c',
+				unit: { id: 'w', type: 'clock', rect: { x: 0, y: 0, w: 1, h: 1 }, config: {} }
+			}
+		};
+		render(<Inspector groupUnit={groupUnit({ def: 'def1' })} def={def} onOp={onOp} />);
+		fireEvent.change(screen.getByPlaceholderText('param key'), { target: { value: 'core' } });
+		fireEvent.change(screen.getByPlaceholderText('target e.g. unit.sensor'), {
+			target: { value: 'unit.sensor' }
+		});
+		fireEvent.click(screen.getByRole('button', { name: 'Add param' }));
+		expect(lastOp(onOp, 'addDefParam')).toEqual({
+			op: 'addDefParam',
+			defId: 'def1',
+			key: 'core',
+			target: 'unit.sensor'
+		});
+	});
+
+	it('emits ungroup (Unlink) and remove from the group actions', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(<Inspector groupUnit={groupUnit()} onOp={onOp} />);
+		fireEvent.click(screen.getByRole('button', { name: /Unlink/ }));
+		expect(lastOp(onOp, 'ungroup')).toEqual({ op: 'ungroup', id: 'grp1' });
+		fireEvent.click(screen.getByRole('button', { name: 'Remove' }));
+		expect(lastOp(onOp, 'remove')).toEqual({ op: 'remove', id: 'grp1' });
+	});
+});
+
+describe('Inspector detail tabs (Fields / Data roving)', () => {
+	const flowWidget = {
+		id: 'w1',
+		type: 'clock' as const,
+		rect: { x: 0, y: 0, w: 160, h: 40 },
+		config: {}
+	};
+
+	it('switches Fields ↔ Data with the arrow keys (WAI-ARIA roving tabs)', () => {
+		const node = leaf(flowWidget);
+		render(<Inspector widget={flowWidget} placement="floating" node={node} onOp={vi.fn()} />);
+		const tablist = screen.getByRole('tablist');
+		const fieldsTab = within(tablist).getByRole('tab', { name: 'Fields' });
+		const dataTab = within(tablist).getByRole('tab', { name: 'Data' });
+		expect(fieldsTab.getAttribute('aria-selected')).toBe('true');
+
+		fireEvent.keyDown(tablist, { key: 'ArrowRight' });
+		expect(dataTab.getAttribute('aria-selected')).toBe('true');
+		expect(screen.getByLabelText('Node JSON')).toBeTruthy(); // the Data panel is now shown
+
+		fireEvent.keyDown(tablist, { key: 'ArrowLeft' });
+		expect(fieldsTab.getAttribute('aria-selected')).toBe('true');
+	});
+});
+
+describe('Inspector per-widget token overrides', () => {
+	const flowWidget = {
+		id: 'w1',
+		type: 'clock' as const,
+		rect: { x: 0, y: 0, w: 160, h: 40 },
+		config: {}
+	};
+
+	it('opens the override group pre-expanded with a count and clears all overrides', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		render(
+			<Inspector
+				widget={{ ...flowWidget, tokens: { '--np-fg': 'red' } }}
+				placement="floating"
+				onOp={onOp}
+			/>
+		);
+		// The summary reflects the override count (the section is keyed open when overrides exist).
+		expect(screen.getByText(/Override theme for this widget · 1 set/)).toBeTruthy();
+		// TokenFields' clear button is labelled by its text ("Clear 1 override"), not its title.
+		fireEvent.click(screen.getByRole('button', { name: 'Clear 1 override' }));
+		expect(lastOp(onOp, 'clearWidgetTokens')).toEqual({ op: 'clearWidgetTokens', id: 'w1' });
+	});
+});
diff --git a/client/src/lib/widgets/Inspector.test.tsx b/client/src/lib/widgets/Inspector.test.tsx
index 0dbea56..51870af 100644
--- a/client/src/lib/widgets/Inspector.test.tsx
+++ b/client/src/lib/widgets/Inspector.test.tsx
@@ -1,7 +1,13 @@
 import { describe, expect, it, vi } from 'vitest';
 import { fireEvent, render, screen } from '@testing-library/react';
 import Inspector, { groupPalette } from './Inspector';
-import { container, leaf, type WidgetInstance } from '../core/layoutTree';
+import {
+	container,
+	leaf,
+	type Group,
+	type WidgetDef,
+	type WidgetInstance
+} from '../core/layoutTree';
 import type { LayoutOp } from './ops';
 
 describe('groupPalette', () => {
@@ -178,3 +184,132 @@ describe('Inspector sensor typeahead options', () => {
 		expect(screen.getByText('cpu.total', { selector: '.np-select-opt-label' })).toBeInTheDocument();
 	});
 });
+
+describe('Inspector group + def params block', () => {
+	const child = leaf({
+		id: 'g1.child',
+		type: 'clock',
+		rect: { x: 0, y: 0, w: 80, h: 40 },
+		config: {}
+	});
+	const groupUnit: Group = {
+		id: 'g1',
+		kind: 'group',
+		name: 'My clock',
+		def: 'd1',
+		size: { w: 120, h: 60 },
+		child,
+		params: { tz: 'UTC' },
+		config: { x: 10, y: 20 }
+	};
+	const def: WidgetDef = {
+		id: 'd1',
+		name: 'ClockDef',
+		size: { w: 120, h: 60 },
+		child,
+		params: [
+			{ key: 'tz', label: 'Timezone', target: 'unit.config.tz' },
+			{
+				key: 'hours',
+				label: 'Clock',
+				default: '24',
+				choices: [
+					{ value: '12', label: '12-hour' },
+					{ value: '24', label: '24-hour' }
+				]
+			}
+		]
+	};
+
+	it('renders the def fields + params and emits ops for every editable control (floating)', () => {
+		const onOp = vi.fn<(op: LayoutOp) => void>();
+		const {
+			getByText,
+			getByLabelText,
+			container: root
+		} = render(<Inspector groupUnit={groupUnit} def={def} placement="floating" onOp={onOp} />);
+		const lastOp = (pred: (o: LayoutOp) => boolean) => onOp.mock.calls.map((c) => c[0]).find(pred);
+
+		// The group header + name field.
+		expect(getByText('group · g1')).toBeTruthy();
+		const name = root.querySelector('input[value="My clock"]') as HTMLInputElement;
+		fireEvent.input(name, { target: { value: 'Renamed' } });
+		expect(lastOp((o) => o.op === 'patchGroup' && !!o.patch.name)).toMatchObject({
+			op: 'patchGroup',
+			id: 'g1',
+			patch: { name: 'Renamed' }
+		});
+
+		// Floating x/y/w/h write into the group's config (anchor + size override).
+		const floatRow = root.querySelector('.row') as HTMLElement;
+		const numInputs = [...floatRow.querySelectorAll('input[type="number"]')];
+		fireEvent.input(numInputs[0], { target: { value: '99' } }); // x
+		expect(lastOp((o) => o.op === 'patchGroup' && o.patch.config?.x === 99)).toBeTruthy();
+
+		// def name / def w / def h. The def w/h live in their own `.row2` (the floating row also has a w
+		// input at value 120, so scope to .row2 to hit the def-size inputs specifically).
+		const defName = root.querySelector('input[value="ClockDef"]') as HTMLInputElement;
+		fireEvent.input(defName, { target: { value: 'NewName' } });
+		expect(lastOp((o) => o.op === 'renameDef')).toMatchObject({ op: 'renameDef', defId: 'd1' });
+		const row2 = root.querySelector('.row2') as HTMLElement;
+		const [defW, defH] = [...row2.querySelectorAll('input[type="number"]')];
+		fireEvent.input(defW, { target: { value: '200' } });
+		expect(lastOp((o) => o.op === 'setDefSize' && o.w === 200)).toBeTruthy();
+		fireEvent.input(defH, { target: { value: '80' } });
+		expect(lastOp((o) => o.op === 'setDefSize' && o.h === 80)).toBeTruthy();
+
+		// Edit def…
+		fireEvent.click(getByText('Edit def…'));
+		expect(lastOp((o) => o.op === 'editDef')).toMatchObject({ op: 'editDef', defId: 'd1' });
+
+		// A text param writes the override into group.params.
+		const tz = root.querySelector('input[value="UTC"]') as HTMLInputElement;
+		fireEvent.input(tz, { target: { value: 'Asia/Tokyo' } });
+		expect(
+			lastOp((o) => o.op === 'patchGroup' && o.patch.params?.tz === 'Asia/Tokyo')
+		).toBeTruthy();
+
+		// A select param (the 12/24-hour choice) — open the combobox + pick 12-hour.
+		fireEvent.click(getByLabelText('param Clock'));
+		fireEvent.click(screen.getByText('12-hour', { selector: '.np-select-opt-label' }));
+		expect(lastOp((o) => o.op === 'patchGroup' && o.patch.params?.hours === '12')).toBeTruthy();
+
+		// Add a new param from the key/target inputs (the row above the "Add param" button).
+		const addRow = getByText('Add param').previousElementSibling as HTMLElement;
+		const [keyInput, targetInput] = [...addRow.querySelectorAll('input')];
+		fireEvent.change(keyInput, { target: { value: 'fmt' } });
+		fireEvent.change(targetInput, { target: { value: 'unit.config.fmt' } });
+		fireEvent.click(getByText('Add param'));
+		expect(lastOp((o) => o.op === 'addDefParam')).toMatchObject({
+			op: 'addDefParam',
+			defId: 'd1',
+			key: 'fmt',
+			target: 'unit.config.fmt'
+		});
+
+		// Unlink + Remove.
+		fireEvent.click(getByText('⛓ Unlink'));
+		expect(lastOp((o) => o.op === 'ungroup')).toMatchObject({ op: 'ungroup', id: 'g1' });
+		fireEvent.click(getByText('Remove'));
+		expect(lastOp((o) => o.op === 'remove')).toMatchObject({ op: 'remove', id: 'g1' });
+	});
+
+	it('shows the "inline group (no def)" hint when the group has no def, and flow sizing controls', () => {
+		const inline: Group = { ...groupUnit, def: undefined, params: undefined };
+		const { getByText, getByLabelText } = render(
+			<Inspector groupUnit={inline} placement="flow" onOp={vi.fn()} />
+		);
+		expect(getByText('inline group (no def)')).toBeTruthy();
+		// flow placement shows the group's leaf sizing control (aria-label "size in parent").
+		expect(getByLabelText('size in parent')).toBeTruthy();
+	});
+
+	it('does not render the Params section when the def declares none', () => {
+		const noParams: WidgetDef = { ...def, params: [] };
+		const noParamGroup: Group = { ...groupUnit, params: undefined };
+		const { queryByText } = render(
+			<Inspector groupUnit={noParamGroup} def={noParams} placement="floating" onOp={vi.fn()} />
+		);
+		expect(queryByText('Params')).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/Inspector.tsx b/client/src/lib/widgets/Inspector.tsx
index 146cfc8..3d2e79c 100644
--- a/client/src/lib/widgets/Inspector.tsx
+++ b/client/src/lib/widgets/Inspector.tsx
@@ -2,7 +2,14 @@
 // the selected node — widget props (sensor / rect / config / dock·float) or container
 // props (kind / cols / gap / pad / align / justify / grow). Emits a single `op` event;
 // all state + persistence lives in Canvas.
-import { useEffect, useMemo, useState, type DragEvent as ReactDragEvent } from 'react';
+import {
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+	type DragEvent as ReactDragEvent
+} from 'react';
 import type {
 	Align,
 	AlignH,
@@ -22,6 +29,8 @@ import type { ConfigField } from '../core/widget';
 import { toYaml } from '../core/yaml';
 import { normalizeMacro } from '../core/macro';
 import MacroEditor from './MacroEditor';
+import MonitorSourcesEditor from './meters/MonitorSourcesEditor';
+import WidgetPreview from './WidgetPreview';
 import CssEditor from './CssEditor';
 import BoxField from './BoxField';
 import Select, { type SelectOption } from './Select';
@@ -87,6 +96,9 @@ type Props = {
 	audioOutputs?: { id: string; name: string }[];
 	// Runtime options for a `catalog:'microphones'` select (the transcribe widget's mic picker).
 	microphones?: { id: string; name: string }[];
+	// Runtime options for a `catalog:'displayNames'` select (the monitor-switch widget's monitor
+	// picker). `id` is the GDI device name (\\.\DISPLAYn), `name` the friendly/EDID label.
+	displayNames?: { id: string; name: string }[];
 	onOp?: (op: LayoutOp) => void;
 	// Deleting a library def from the Inspector routes through the container (which checks whether the
 	// def is in use and explains the block, matching the Widget-designer list) instead of the reducer's
@@ -286,6 +298,7 @@ export default function Inspector({
 	sensorMeta = {},
 	audioOutputs = [],
 	microphones = [],
+	displayNames = [],
 	onOp,
 	onDeleteDef,
 	onPreviewTemplate,
@@ -302,12 +315,83 @@ export default function Inspector({
 	// still user-toggleable in between, and re-opens when nothing is selected (the primary add affordance).
 	const hasSelection = !!(widget || container || groupUnit);
 	const [addOpen, setAddOpen] = useState(!hasSelection);
+
+	// Add-palette hover preview (Tier 2): a floating popover with a live demo render of the hovered
+	// entry — a widget type, OR a library def / template tree. Debounced so a quick pass doesn't spin up
+	// a render; positioned to the LEFT (the palette is the right rail) and clamped into the viewport.
+	type PreviewSpec = {
+		label: string;
+		desc?: string;
+		hint: string;
+		type?: string; // a single widget
+		node?: LayoutNode; // a def / template tree (with its native size)
+		size?: { w: number; h: number };
+	};
+	const [palettePreview, setPalettePreview] = useState<
+		(PreviewSpec & { top: number; left: number }) | null
+	>(null);
+	const previewTimer = useRef<number | null>(null);
+	const previewRef = useRef<HTMLDivElement | null>(null);
+	const showPreview = (spec: PreviewSpec, el: HTMLElement): void => {
+		if (previewTimer.current !== null) window.clearTimeout(previewTimer.current);
+		previewTimer.current = window.setTimeout(() => {
+			const r = el.getBoundingClientRect();
+			const left = Math.max(8, r.left - 232 - 10);
+			setPalettePreview({ ...spec, top: Math.max(8, r.top - 8), left });
+		}, 280);
+	};
+	const hidePreview = (): void => {
+		if (previewTimer.current !== null) {
+			window.clearTimeout(previewTimer.current);
+			previewTimer.current = null;
+		}
+		setPalettePreview(null);
+	};
+	useEffect(
+		() => () => {
+			if (previewTimer.current !== null) window.clearTimeout(previewTimer.current);
+		},
+		[]
+	);
+	// Keep the popover on-screen: after render, clamp its top so the bottom isn't cut off (its height
+	// varies with the description, so a fixed estimate clipped tall cards hovered near the bottom).
+	useLayoutEffect(() => {
+		const el = previewRef.current;
+		if (!el || !palettePreview) return;
+		const top = Math.min(palettePreview.top, Math.max(8, window.innerHeight - el.offsetHeight - 8));
+		el.style.top = `${Math.max(8, top)}px`;
+	}, [palettePreview]);
 	useEffect(() => {
 		setAddOpen(!hasSelection);
 	}, [hasSelection]);
 	// Built-ins + one group per enabled plugin package (re-renders on package toggle).
 	const templateGroups = useTemplateGroups();
 
+	// Add-palette filter: one search box narrows widgets + templates + library by name/type/description.
+	const [paletteFilter, setPaletteFilter] = useState('');
+	const pq = paletteFilter.trim().toLowerCase();
+	const pmatch = (...parts: (string | undefined)[]): boolean =>
+		!pq || parts.some((p) => p?.toLowerCase().includes(pq));
+	const fWidgetGroups = groupPalette(
+		widgetTypes.filter((w) => pmatch(w.label, w.type, getMeta(w.type)?.description))
+	);
+	const fDefs = defs.filter((d) => pmatch(d.name));
+	const fTemplateGroups = templateGroups
+		.map((g) => ({ ...g, templates: g.templates.filter((t) => pmatch(t.name, t.description)) }))
+		.filter((g) => g.templates.length);
+	const paletteEmpty = !fWidgetGroups.length && !fDefs.length && !fTemplateGroups.length;
+
+	// HA entity ids (e.g. "light.kitchen") for the macro editor's entity picker — from the json
+	// `ha.<id>` catalog entries (not the `.state` scalars, nor the `ha.status` connection sensor).
+	const haEntityIds = useMemo(
+		() =>
+			sensors
+				.filter((s) => s.startsWith('ha.') && !s.endsWith('.state'))
+				.map((s) => s.slice('ha.'.length))
+				.filter((e) => e.includes('.')),
+		[sensors]
+	);
+
 	// Sensor combobox options: friendly "Name (unit)" label, the raw id kept as the value + shown as a
 	// dim hint. A bare id (no metadata) is its own label with no hint. Drives the typeahead sensor field.
 	const sensorOptions = useMemo<SelectOption[]>(
@@ -614,15 +698,47 @@ export default function Inspector({
 
 	return (
 		<div className={['inspector', docked && 'docked'].filter(Boolean).join(' ')}>
+			{/* Add-palette hover preview (Tier 2): a fixed popover with a live demo render of the hovered
+			    entry (a widget type, or a library def / template tree), its name, description + a hint. */}
+			{palettePreview ? (
+				<div
+					ref={previewRef}
+					className="palette-preview"
+					style={{ top: palettePreview.top, left: palettePreview.left }}
+				>
+					<div className="pp-stage">
+						<WidgetPreview
+							type={palettePreview.type}
+							node={palettePreview.node}
+							size={palettePreview.size}
+						/>
+					</div>
+					<div className="pp-meta">
+						<span className="pp-name">{palettePreview.label}</span>
+						{palettePreview.desc ? <span className="pp-desc">{palettePreview.desc}</span> : null}
+						<span className="pp-hint">{palettePreview.hint}</span>
+					</div>
+				</div>
+			) : null}
 			<details
 				className="add-panel"
 				open={addOpen}
 				onToggle={(e) => setAddOpen(e.currentTarget.open)}
 			>
 				<summary>＋ Add widget · {addDest}</summary>
-				{/* Grouped by meta.category in first-seen order (uncategorized falls into "Other") —
-				    ~20 ungrouped same-weight chips made find-by-scan fail. */}
-				{groupPalette(widgetTypes).map((g) => (
+				{/* One search box narrows widgets + templates + library at once — ~20 widgets plus
+				    templates + library made find-by-scan slow. */}
+				<input
+					className="palette-filter"
+					type="search"
+					placeholder="Filter widgets, templates, library…"
+					value={paletteFilter}
+					onChange={(e) => setPaletteFilter(e.currentTarget.value)}
+					aria-label="Filter the add palette"
+				/>
+
+				{/* Widgets, grouped by meta.category (first-seen order; uncategorized falls into "Other"). */}
+				{fWidgetGroups.map((g) => (
 					<div key={g.category} className="palette">
 						<span className="hd2">{g.category}</span>
 						{g.items.map((w) => (
@@ -630,15 +746,31 @@ export default function Inspector({
 								key={w.type}
 								type="button"
 								draggable
-								title={
-									container
-										? `Add "${w.label}" into the selected ${container.kind} — or drag it onto the canvas / a container in the Outline to place it elsewhere`
-										: `Add "${w.label}" as a floating widget — or drag it onto the canvas / a container in the Outline`
-								}
-								onClick={() => op({ op: 'addWidget', widgetType: w.type })}
-								onDragStart={(e: ReactDragEvent) =>
-									e.dataTransfer?.setData('text/x-widget-type', w.type)
+								// No native `title` tooltip — the hover preview popover is the richer replacement
+								// (both at once was redundant). The description stays as the aria-label for a11y.
+								aria-label={[w.label, getMeta(w.type)?.description].filter(Boolean).join(' — ')}
+								onClick={() => {
+									hidePreview();
+									op({ op: 'addWidget', widgetType: w.type });
+								}}
+								onMouseEnter={(e) =>
+									showPreview(
+										{
+											label: w.label,
+											desc: getMeta(w.type)?.description,
+											hint: container
+												? `Click to add into the ${container.kind} · drag to place`
+												: 'Click to add · drag to place',
+											type: w.type
+										},
+										e.currentTarget
+									)
 								}
+								onMouseLeave={hidePreview}
+								onDragStart={(e: ReactDragEvent) => {
+									hidePreview();
+									e.dataTransfer?.setData('text/x-widget-type', w.type);
+								}}
 							>
 								{w.label}
 							</button>
@@ -646,40 +778,10 @@ export default function Inspector({
 					</div>
 				))}
 
-				{defs.length ? (
-					<div className="palette">
-						<span className="hd">Library</span>
-						{defs.map((d) => (
-							<span key={d.id} className="libitem">
-								<button
-									type="button"
-									title={d.name}
-									onClick={() => op({ op: 'insertWidget', defId: d.id })}
-								>
-									{d.name}
-								</button>
-								<button
-									type="button"
-									className="x"
-									title="Delete from library (only if unused)"
-									aria-label={`Delete ${d.name} from library`}
-									onClick={() =>
-										onDeleteDef ? onDeleteDef(d.id, d.name) : op({ op: 'deleteDef', defId: d.id })
-									}
-								>
-									✕
-								</button>
-							</span>
-						))}
-					</div>
-				) : null}
-
-				{/* Inserting from here drops a STANDALONE inline copy (no library def) — the designer
-				    rail's ⎘ is the path that clones a template into an editable library widget. The
-				    titles say which is which; 👁 jumps to the designer's read-only preview. Groups come
-				    from the template registry: built-ins first, then one group per enabled plugin
-				    package (under the package's name). */}
-				{templateGroups.map((g) => (
+				{/* Templates: insert a STANDALONE inline copy (the designer rail's ⎘ clones one into an
+				    editable library widget instead). 👁 jumps to the designer's read-only preview. Groups
+				    come from the registry: built-ins first, then one per enabled plugin package. */}
+				{fTemplateGroups.map((g) => (
 					<div key={g.group} className="palette">
 						<span className="hd">
 							{g.group === BUILTIN_TEMPLATE_GROUP ? 'Templates' : `Templates · ${g.group}`}
@@ -696,8 +798,24 @@ export default function Inspector({
 								<span key={t.id} className="libitem">
 									<button
 										type="button"
-										title={`${t.description} — inserts a standalone copy onto the canvas (not linked to the library)`}
-										onClick={() => op({ op: 'insertTemplate', templateId: t.id })}
+										aria-label={[t.name, t.description].filter(Boolean).join(' — ')}
+										onClick={() => {
+											hidePreview();
+											op({ op: 'insertTemplate', templateId: t.id });
+										}}
+										onMouseEnter={(e) =>
+											showPreview(
+												{
+													label: t.name,
+													desc: t.description,
+													hint: 'Click to insert a standalone copy',
+													node: t.tree(),
+													size: t.size
+												},
+												e.currentTarget
+											)
+										}
+										onMouseLeave={hidePreview}
 									>
 										{t.name}
 									</button>
@@ -709,6 +827,49 @@ export default function Inspector({
 						)}
 					</div>
 				))}
+
+				{/* Library: your saved widget defs (insert an instance linked to the def). */}
+				{fDefs.length ? (
+					<div className="palette">
+						<span className="hd">Library</span>
+						{fDefs.map((d) => (
+							<span key={d.id} className="libitem">
+								<button
+									type="button"
+									aria-label={d.name}
+									onClick={() => {
+										hidePreview();
+										op({ op: 'insertWidget', defId: d.id });
+									}}
+									onMouseEnter={(e) =>
+										showPreview(
+											{ label: d.name, hint: 'Click to insert', node: d.child, size: d.size },
+											e.currentTarget
+										)
+									}
+									onMouseLeave={hidePreview}
+								>
+									{d.name}
+								</button>
+								<button
+									type="button"
+									className="x"
+									title="Delete from library (only if unused)"
+									aria-label={`Delete ${d.name} from library`}
+									onClick={() =>
+										onDeleteDef ? onDeleteDef(d.id, d.name) : op({ op: 'deleteDef', defId: d.id })
+									}
+								>
+									✕
+								</button>
+							</span>
+						))}
+					</div>
+				) : null}
+
+				{paletteEmpty ? (
+					<div className="palette-empty">No matches for “{paletteFilter}”.</div>
+				) : null}
 			</details>
 
 			{node && (
@@ -1138,11 +1299,79 @@ export default function Inspector({
 									<MacroEditor
 										value={normalizeMacro(widget.config[f.key])}
 										onChange={(next) => setConfig(f.key, next)}
+										entities={haEntityIds}
+									/>
+									{f.help ? <small className="field-help">{f.help}</small> : null}
+								</div>
+							);
+						}
+						// A monitor-sources field is a multi-row editor (checklist + rename), so like the
+						// macro field it renders outside the single-control <label> pattern below.
+						if (f.kind === 'monitorSources') {
+							return (
+								<div
+									className={['cfg-field', dirtyKeys.has('config.' + f.key) && 'dirty']
+										.filter(Boolean)
+										.join(' ')}
+									key={f.key}
+								>
+									<button
+										type="button"
+										className="reset-field"
+										title="Reset to default"
+										disabled={def === undefined}
+										onClick={() => setConfig(f.key, def)}
+									>
+										↺
+									</button>
+									<span className="hd" title={f.help}>
+										{f.label}
+									</span>
+									<MonitorSourcesEditor
+										value={cfgStr(widget.config[f.key])}
+										monitor={cfgStr(widget.config.monitor)}
+										onChange={(spec) => setConfig(f.key, spec || undefined)}
 									/>
 									{f.help ? <small className="field-help">{f.help}</small> : null}
 								</div>
 							);
 						}
+						// A toggle is a checkbox + its label on one aligned row (checkbox left, label
+						// vertically centred), help below — not the label-stacked-over-control layout the
+						// generic fields use.
+						if (f.kind === 'toggle') {
+							return (
+								<div
+									className={[
+										'cfg-field',
+										'cfg-toggle',
+										dirtyKeys.has('config.' + f.key) && 'dirty'
+									]
+										.filter(Boolean)
+										.join(' ')}
+									key={f.key}
+								>
+									<button
+										type="button"
+										className="reset-field"
+										title="Reset to default"
+										disabled={def === undefined}
+										onClick={() => setConfig(f.key, def)}
+									>
+										↺
+									</button>
+									<label className="check" title={f.help}>
+										<input
+											type="checkbox"
+											checked={cfgBool(widget.config[f.key])}
+											onChange={(e) => setConfig(f.key, e.currentTarget.checked)}
+										/>
+										<span>{f.label}</span>
+									</label>
+									{f.help ? <small className="field-help">{f.help}</small> : null}
+								</div>
+							);
+						}
 						return (
 							<div className="cfg-field" key={f.key}>
 								<button
@@ -1172,12 +1401,6 @@ export default function Inspector({
 												)
 											}
 										/>
-									) : f.kind === 'toggle' ? (
-										<input
-											type="checkbox"
-											checked={cfgBool(widget.config[f.key])}
-											onChange={(e) => setConfig(f.key, e.currentTarget.checked)}
-										/>
 									) : f.kind === 'select' ? (
 										<Select
 											value={cfgStr(widget.config[f.key])}
@@ -1192,6 +1415,11 @@ export default function Inspector({
 															{ value: '', label: 'System default' },
 															...microphones.map((d) => ({ value: d.id, label: d.name }))
 													  ]
+													: f.catalog === 'displayNames'
+													? [
+															{ value: '', label: 'Primary monitor' },
+															...displayNames.map((d) => ({ value: d.id, label: d.name }))
+													  ]
 													: f.options.map((o) => ({ value: o, label: o }))
 											}
 											onChange={(v) => setConfig(f.key, v)}
diff --git a/client/src/lib/widgets/MacroEditor.test.tsx b/client/src/lib/widgets/MacroEditor.test.tsx
index 804fd92..59cae8c 100644
--- a/client/src/lib/widgets/MacroEditor.test.tsx
+++ b/client/src/lib/widgets/MacroEditor.test.tsx
@@ -45,6 +45,61 @@ describe('MacroEditor', () => {
 		expect(data.className).toContain('error');
 	});
 
+	it('clears data when the JSON field is emptied (committing undefined)', () => {
+		const onChange = vi.fn();
+		const value: Macro = [{ domain: 'light', service: 'toggle', data: { brightness_pct: 60 } }];
+		const { getByPlaceholderText } = render(<MacroEditor value={value} onChange={onChange} />);
+		const data = getByPlaceholderText(/data \(JSON\)/i) as HTMLInputElement;
+		// Seeds from props, then user clears it.
+		expect(data.value).toBe('{"brightness_pct":60}');
+		fireEvent.change(data, { target: { value: '   ' } });
+		fireEvent.blur(data);
+		expect(onChange).toHaveBeenCalledWith([
+			{ domain: 'light', service: 'toggle', data: undefined }
+		]);
+		expect(data.className).not.toContain('error');
+	});
+
+	it('flags valid JSON that is not a plain object (array) and does not commit it', () => {
+		const onChange = vi.fn();
+		const value: Macro = [{ domain: 'light', service: 'toggle' }];
+		const { getByPlaceholderText } = render(<MacroEditor value={value} onChange={onChange} />);
+		const data = getByPlaceholderText(/data \(JSON\)/i);
+		fireEvent.change(data, { target: { value: '[1,2,3]' } });
+		fireEvent.blur(data);
+		expect(onChange).not.toHaveBeenCalled();
+		expect(data.className).toContain('error');
+	});
+
+	it('flags valid JSON that is a non-object scalar (number) and does not commit it', () => {
+		const onChange = vi.fn();
+		const value: Macro = [{ domain: 'light', service: 'toggle' }];
+		const { getByPlaceholderText } = render(<MacroEditor value={value} onChange={onChange} />);
+		const data = getByPlaceholderText(/data \(JSON\)/i);
+		fireEvent.change(data, { target: { value: '42' } });
+		fireEvent.blur(data);
+		expect(onChange).not.toHaveBeenCalled();
+		expect(data.className).toContain('error');
+	});
+
+	it('renders the empty hint only when there are no actions', () => {
+		const { queryByText, rerender } = render(<MacroEditor value={[]} onChange={vi.fn()} />);
+		expect(queryByText(/inert until you add one/i)).not.toBeNull();
+		rerender(<MacroEditor value={[{ domain: 'light', service: 'toggle' }]} onChange={vi.fn()} />);
+		expect(queryByText(/inert until you add one/i)).toBeNull();
+	});
+
+	it('tolerates a null value (treated as an empty macro)', () => {
+		// `value ?? []` guard — defensive for a config field that was never set.
+		const onChange = vi.fn();
+		const { getByText, queryByText } = render(
+			<MacroEditor value={null as unknown as Macro} onChange={onChange} />
+		);
+		expect(queryByText(/inert until you add one/i)).not.toBeNull();
+		fireEvent.click(getByText('+ action'));
+		expect(onChange).toHaveBeenCalledWith([{ domain: '', service: '' }]);
+	});
+
 	it('removes a row', () => {
 		const onChange = vi.fn();
 		const value: Macro = [
@@ -73,4 +128,46 @@ describe('MacroEditor', () => {
 			{ domain: 'light', service: 'toggle' }
 		]);
 	});
+
+	it('reorders rows (move up) from the second row', () => {
+		const onChange = vi.fn();
+		const value: Macro = [
+			{ domain: 'light', service: 'toggle' },
+			{ domain: 'media', service: 'pause' }
+		];
+		const { getAllByTitle } = render(<MacroEditor value={value} onChange={onChange} />);
+		const up = getAllByTitle('Move up') as HTMLButtonElement[];
+		expect(up[1].disabled).toBe(false); // second row CAN move up
+		fireEvent.click(up[1]);
+		expect(onChange).toHaveBeenCalledWith([
+			{ domain: 'media', service: 'pause' },
+			{ domain: 'light', service: 'toggle' }
+		]);
+	});
+
+	it('commits the entity picker into data.entity_id on blur', () => {
+		const onChange = vi.fn();
+		const value: Macro = [{ domain: 'light', service: 'toggle' }];
+		const { getByPlaceholderText } = render(
+			<MacroEditor value={value} onChange={onChange} entities={['light.kitchen', 'light.lounge']} />
+		);
+		const entity = getByPlaceholderText(/entity \(optional\)/i);
+		fireEvent.change(entity, { target: { value: 'light.kitchen' } });
+		fireEvent.blur(entity);
+		expect(onChange).toHaveBeenCalledWith([
+			{ domain: 'light', service: 'toggle', data: { entity_id: 'light.kitchen' } }
+		]);
+	});
+
+	it('wires domain/service/entity datalists (autocomplete)', () => {
+		const value: Macro = [{ domain: '', service: '' }];
+		const { container, getByPlaceholderText } = render(
+			<MacroEditor value={value} onChange={vi.fn()} entities={['light.kitchen']} />
+		);
+		expect(getByPlaceholderText('domain').getAttribute('list')).toBe('macro-domains');
+		expect(getByPlaceholderText('service').getAttribute('list')).toBe('macro-services');
+		expect(container.querySelector('#macro-entities option')?.getAttribute('value')).toBe(
+			'light.kitchen'
+		);
+	});
 });
diff --git a/client/src/lib/widgets/MacroEditor.tsx b/client/src/lib/widgets/MacroEditor.tsx
index fc77bd3..a4fbae2 100644
--- a/client/src/lib/widgets/MacroEditor.tsx
+++ b/client/src/lib/widgets/MacroEditor.tsx
@@ -1,15 +1,17 @@
 // Inspector control for a `kind:'macro'` config field: edit an ordered list of {domain, service,
 // data?} action calls run in sequence on press. Controlled (value + onChange) and prop-only — the
 // immutable edit ops live in core/macro.ts; this just wires them to row inputs. `domain`/`service`
-// are plain text; `data` is a JSON object edited as text and committed on blur (like the inspector's
-// raw-config escape hatch), so partial/invalid JSON while typing never clobbers the field. Styled by
-// Inspector.css (it only ever renders inside the inspector).
+// are plain text with native <datalist> autocomplete of common values; an entity picker (also a
+// datalist, fed the HA catalog) writes `data.entity_id` for the common case, while `data` stays an
+// editable JSON escape hatch for everything else (committed on blur so partial JSON never clobbers
+// the field). Styled by Inspector.css (it only ever renders inside the inspector).
 import { useState } from 'react';
 import {
 	addAction,
 	moveAction,
 	removeAction,
 	updateAction,
+	withEntityId,
 	type Macro,
 	type MacroAction
 } from '../core/macro';
@@ -17,22 +19,90 @@ import {
 type Props = {
 	value: Macro;
 	onChange: (next: Macro) => void;
+	// HA entity ids (e.g. "light.kitchen") for the entity-picker datalist; empty/absent → free text.
+	entities?: string[];
 };
 
+// Autocomplete suggestions — the inputs stay free text, these are just hints. Covers the HA control
+// family + the built-in `media` (now-playing) domain.
+const DOMAIN_SUGGESTIONS = [
+	'light',
+	'switch',
+	'fan',
+	'cover',
+	'lock',
+	'climate',
+	'media_player',
+	'scene',
+	'script',
+	'automation',
+	'input_boolean',
+	'input_number',
+	'input_select',
+	'input_button',
+	'vacuum',
+	'media'
+];
+const SERVICE_SUGGESTIONS = [
+	'toggle',
+	'turn_on',
+	'turn_off',
+	'trigger',
+	'press',
+	'select_option',
+	'set_value',
+	'set_temperature',
+	'set_hvac_mode',
+	'set_fan_mode',
+	'set_percentage',
+	'open_cover',
+	'close_cover',
+	'stop_cover',
+	'set_cover_position',
+	'lock',
+	'unlock',
+	'volume_set',
+	'volume_mute',
+	'media_play_pause',
+	'media_next_track',
+	'media_previous_track',
+	'playpause',
+	'next',
+	'previous'
+];
+
 const dataToText = (data: Record<string, unknown> | undefined): string =>
 	data ? JSON.stringify(data) : '';
 
-export default function MacroEditor({ value, onChange }: Props) {
+export default function MacroEditor({ value, onChange, entities = [] }: Props) {
 	const actions = value ?? [];
 	return (
 		<div className="macro-editor">
+			{/* Shared datalists referenced by every row's inputs (one per document; only one MacroEditor
+			    renders at a time — for the selected widget). */}
+			<datalist id="macro-domains">
+				{DOMAIN_SUGGESTIONS.map((d) => (
+					<option key={d} value={d} />
+				))}
+			</datalist>
+			<datalist id="macro-services">
+				{SERVICE_SUGGESTIONS.map((s) => (
+					<option key={s} value={s} />
+				))}
+			</datalist>
+			<datalist id="macro-entities">
+				{entities.map((e) => (
+					<option key={e} value={e} />
+				))}
+			</datalist>
+
 			{actions.length === 0 ? (
 				<div className="macro-empty">No actions — the button is inert until you add one.</div>
 			) : null}
 			{actions.map((a, i) => (
 				<MacroRow
 					// Keyed by index + data identity so a reorder (which changes the data at this slot)
-					// re-mounts the row and re-seeds its local data buffer from props.
+					// re-mounts the row and re-seeds its local data/entity buffers from props.
 					key={`${i}:${dataToText(a.data)}`}
 					action={a}
 					first={i === 0}
@@ -69,6 +139,11 @@ function MacroRow({
 }) {
 	const [dataText, setDataText] = useState(dataToText(action.data));
 	const [dataError, setDataError] = useState(false);
+	// Local buffer so typing an entity doesn't re-write `data` (and remount the row) on every keystroke;
+	// committed on blur, like the JSON field.
+	const [entityText, setEntityText] = useState(
+		(action.data?.entity_id as string | undefined) ?? ''
+	);
 
 	// Commit the data field: empty clears `data`; a JSON object sets it; anything else flags an error
 	// and leaves the committed value untouched (the text stays so the user can fix it).
@@ -92,12 +167,15 @@ function MacroRow({
 		}
 	};
 
+	const commitEntity = () => onPatch({ data: withEntityId(action.data, entityText) });
+
 	return (
 		<div className="macro-row">
 			<div className="macro-row-main">
 				<input
 					className="macro-domain"
 					placeholder="domain"
+					list="macro-domains"
 					title="domain — e.g. light, switch, scene, script, or media"
 					value={action.domain}
 					onChange={(e) => onPatch({ domain: e.currentTarget.value })}
@@ -105,6 +183,7 @@ function MacroRow({
 				<input
 					className="macro-service"
 					placeholder="service"
+					list="macro-services"
 					title="service — e.g. toggle, turn_on; for media: playpause, next, previous"
 					value={action.service}
 					onChange={(e) => onPatch({ service: e.currentTarget.value })}
@@ -127,10 +206,19 @@ function MacroRow({
 					</button>
 				</div>
 			</div>
+			<input
+				className="macro-entity"
+				placeholder="entity (optional), e.g. light.kitchen"
+				list="macro-entities"
+				title="target entity — picks from your HA entities; sets data.entity_id"
+				value={entityText}
+				onChange={(e) => setEntityText(e.currentTarget.value)}
+				onBlur={commitEntity}
+			/>
 			<input
 				className={dataError ? 'macro-data error' : 'macro-data'}
-				placeholder='data (JSON), e.g. {"entity_id":"light.kitchen"}'
-				title="optional JSON args — HA needs entity_id here on an unbound button"
+				placeholder='extra data (JSON), e.g. {"brightness_pct":60}'
+				title="optional JSON args merged with the entity above (brightness, temperature, …)"
 				value={dataText}
 				onChange={(e) => setDataText(e.currentTarget.value)}
 				onBlur={commitData}
diff --git a/client/src/lib/widgets/MonitorSwitchHost.test.tsx b/client/src/lib/widgets/MonitorSwitchHost.test.tsx
new file mode 100644
index 0000000..8aad1e5
--- /dev/null
+++ b/client/src/lib/widgets/MonitorSwitchHost.test.tsx
@@ -0,0 +1,193 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, waitFor, fireEvent, cleanup, act } from '@testing-library/react';
+
+// Stub the Tauri-backed DDC adapter (no backend in tests): the host must still resolve the target
+// monitor, derive its rows/title/stats, and drive the optimistic switch → reconcile flow through it.
+const { listMonitorInputs, setMonitorInput } = vi.hoisted(() => ({
+	listMonitorInputs: vi.fn(),
+	setMonitorInput: vi.fn()
+}));
+vi.mock('../ddc/monitors', () => ({ listMonitorInputs, setMonitorInput }));
+
+import MonitorSwitchHost from './MonitorSwitchHost';
+import type { MonitorInputs } from '../ddc/monitors';
+
+const mon = (over: Partial<MonitorInputs> = {}): MonitorInputs => ({
+	gdi: '\\\\.\\DISPLAY1',
+	friendly: 'Dell U2720Q',
+	primary: true,
+	current_input: 0x11, // HDMI 1
+	supported: [0x0f, 0x11], // DisplayPort 1, HDMI 1
+	width: 2560,
+	height: 1440,
+	refresh_hz: 144,
+	...over
+});
+
+beforeEach(() => {
+	listMonitorInputs.mockReset();
+	setMonitorInput.mockReset();
+	listMonitorInputs.mockResolvedValue([mon()]);
+	setMonitorInput.mockResolvedValue(true);
+});
+
+describe('MonitorSwitchHost (container wiring)', () => {
+	it('lists monitors and renders the primary monitor: title, rows, active input', async () => {
+		const { container } = render(<MonitorSwitchHost />);
+		expect(listMonitorInputs).toHaveBeenCalledWith(undefined); // blank target = primary
+		await waitFor(() => expect(container.querySelectorAll('.ms-row')).toHaveLength(2));
+		expect(container.querySelector('.ms-title')?.textContent).toBe('Dell U2720Q');
+		const active = [...container.querySelectorAll('.ms-row')].find(
+			(r) => r.getAttribute('data-active') === 'true'
+		);
+		expect(active?.textContent).toContain('HDMI 1');
+	});
+
+	it('resolves a configured target by GDI name and flags it missing when absent', async () => {
+		listMonitorInputs.mockResolvedValue([mon({ gdi: '\\\\.\\DISPLAY2', primary: false })]);
+		// JSX string literals don't process escapes, so pass the GDI name as a JS expression.
+		const { container } = render(<MonitorSwitchHost monitor={'  \\\\.\\DISPLAY9  '} />);
+		// trimmed target is passed to the adapter
+		await waitFor(() => expect(listMonitorInputs).toHaveBeenCalledWith('\\\\.\\DISPLAY9'));
+		// no monitor matches that gdi → missing hint, no rows
+		await waitFor(() =>
+			expect(container.querySelector('[data-part="empty"]')?.textContent).toBe('monitor not found')
+		);
+		expect(container.querySelector('.ms-row')).toBeNull();
+	});
+
+	it('uses the label override as the title when provided', async () => {
+		const { container } = render(<MonitorSwitchHost label="  Desk  " />);
+		await waitFor(() => expect(container.querySelector('.ms-title')?.textContent).toBe('Desk'));
+	});
+
+	it('shows resolution/refresh stats only when showStats is on', async () => {
+		const { container, rerender } = render(<MonitorSwitchHost />);
+		await waitFor(() => expect(container.querySelector('.ms-row')).not.toBeNull());
+		expect(container.querySelector('.ms-stats')).toBeNull();
+		rerender(<MonitorSwitchHost showStats />);
+		await waitFor(() =>
+			expect(container.querySelector('.ms-stats')?.textContent).toBe('2560×1440 · 144 Hz')
+		);
+	});
+
+	it('drops the active highlight when showCurrent is off', async () => {
+		const { container } = render(<MonitorSwitchHost showCurrent={false} />);
+		await waitFor(() => expect(container.querySelectorAll('.ms-row')).toHaveLength(2));
+		expect(container.querySelector('.ms-row[data-active="true"]')).toBeNull();
+	});
+
+	it('falls back to the first monitor when none reports primary', async () => {
+		listMonitorInputs.mockResolvedValue([
+			mon({ primary: false, supported: [0x0f], current_input: 0x0f }), // list[0]
+			mon({ gdi: '\\\\.\\DISPLAY2', primary: false })
+		]);
+		const { container } = render(<MonitorSwitchHost />);
+		// no primary → list[0], whose single supported input is DisplayPort 1
+		await waitFor(() => expect(container.querySelectorAll('.ms-row')).toHaveLength(1));
+		expect(container.querySelector('.ms-name')?.textContent).toBe('DisplayPort 1');
+	});
+
+	it('renders the default input set (and ignores clicks) when no monitor resolves', async () => {
+		listMonitorInputs.mockResolvedValue([]); // empty list, blank target → selected = null
+		const { container } = render(<MonitorSwitchHost />);
+		// monitorInputRows falls back to DEFAULT_INPUTS (DP1, DP2, HDMI1, HDMI2)
+		await waitFor(() => expect(container.querySelectorAll('.ms-row')).toHaveLength(4));
+		expect(container.querySelector('[data-part="empty"]')).toBeNull(); // not "missing" (no target)
+		// no resolved gdi → pick() early-returns, never calls the switch
+		fireEvent.click(container.querySelector('.ms-row')!);
+		expect(setMonitorInput).not.toHaveBeenCalled();
+	});
+
+	it('picks an input: optimistic highlight, then reconciles via setMonitorInput + refresh', async () => {
+		// after the switch the monitor reports DP1 as the current input
+		listMonitorInputs
+			.mockResolvedValueOnce([mon()]) // initial
+			.mockResolvedValue([mon({ current_input: 0x0f })]); // post-switch refresh
+		const { container } = render(<MonitorSwitchHost />);
+		await waitFor(() => expect(container.querySelectorAll('.ms-row')).toHaveLength(2));
+
+		const dp = [...container.querySelectorAll('.ms-row')].find((r) =>
+			r.textContent?.includes('DisplayPort 1')
+		);
+		fireEvent.click(dp as Element);
+
+		await waitFor(() => expect(setMonitorInput).toHaveBeenCalledWith('\\\\.\\DISPLAY1', 0x0f));
+		await waitFor(() => {
+			const active = [...container.querySelectorAll('.ms-row')].find(
+				(r) => r.getAttribute('data-active') === 'true'
+			);
+			expect(active?.textContent).toContain('DisplayPort 1');
+		});
+	});
+
+	it('warns and reverts when a switch fails (monitor reports the old input)', async () => {
+		setMonitorInput.mockResolvedValue(false);
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		const { container } = render(<MonitorSwitchHost />);
+		await waitFor(() => expect(container.querySelectorAll('.ms-row')).toHaveLength(2));
+
+		const dp = [...container.querySelectorAll('.ms-row')].find((r) =>
+			r.textContent?.includes('DisplayPort 1')
+		);
+		fireEvent.click(dp as Element);
+
+		await waitFor(() => expect(warn).toHaveBeenCalled());
+		// reconcile snapped back to HDMI 1 (the reported input)
+		await waitFor(() => {
+			const active = [...container.querySelectorAll('.ms-row')].find(
+				(r) => r.getAttribute('data-active') === 'true'
+			);
+			expect(active?.textContent).toContain('HDMI 1');
+		});
+		warn.mockRestore();
+	});
+
+	it('polls on the relaxed interval to keep the highlight honest', async () => {
+		vi.useFakeTimers();
+		try {
+			listMonitorInputs
+				.mockResolvedValueOnce([mon()]) // initial: HDMI 1
+				.mockResolvedValue([mon({ current_input: 0x0f })]); // next poll: DP 1
+			const { container, unmount } = render(<MonitorSwitchHost />);
+			await act(async () => {
+				await Promise.resolve(); // flush the initial refresh
+			});
+			expect(container.querySelectorAll('.ms-row')).toHaveLength(2);
+
+			await act(async () => {
+				await vi.advanceTimersByTimeAsync(8000); // one REFRESH_MS tick → interval fires
+			});
+			const active = [...container.querySelectorAll('.ms-row')].find(
+				(r) => r.getAttribute('data-active') === 'true'
+			);
+			expect(active?.textContent).toContain('DisplayPort 1');
+			unmount(); // tears down the interval + focus listener
+		} finally {
+			vi.useRealTimers();
+		}
+	});
+
+	it('refreshes the active input on window focus', async () => {
+		listMonitorInputs
+			.mockResolvedValueOnce([mon()]) // initial: HDMI 1
+			.mockResolvedValue([mon({ current_input: 0x0f })]); // on focus: DP 1
+		const { container } = render(<MonitorSwitchHost />);
+		await waitFor(() => {
+			const active = [...container.querySelectorAll('.ms-row')].find(
+				(r) => r.getAttribute('data-active') === 'true'
+			);
+			expect(active?.textContent).toContain('HDMI 1');
+		});
+
+		fireEvent(window, new Event('focus'));
+
+		await waitFor(() => {
+			const active = [...container.querySelectorAll('.ms-row')].find(
+				(r) => r.getAttribute('data-active') === 'true'
+			);
+			expect(active?.textContent).toContain('DisplayPort 1');
+		});
+		cleanup(); // unmount tears down the focus listener + interval
+	});
+});
diff --git a/client/src/lib/widgets/MonitorSwitchHost.tsx b/client/src/lib/widgets/MonitorSwitchHost.tsx
new file mode 100644
index 0000000..9ebfe22
--- /dev/null
+++ b/client/src/lib/widgets/MonitorSwitchHost.tsx
@@ -0,0 +1,105 @@
+// Container (AGENTS.md §6) for the Monitor Switch widget: owns the Tauri wiring (list monitors, read
+// current/supported DDC input + display mode, switch via VCP 0x60) and feeds the presentational
+// MonitorSwitch meter plain props. A bespoke host — like AudioSwitcherHost — because it sources from
+// commands, not a sensor. Registered as the `monitorswitch` component in registry.tsx. The pure
+// shaping (which rows, names, stats) lives in core/monitorInputs.
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import MonitorSwitch from './meters/MonitorSwitch';
+import { listMonitorInputs, setMonitorInput, type MonitorInputs } from '../ddc/monitors';
+import { formatStats, monitorInputRows } from '../core/monitorInputs';
+
+// Config fields, spread onto the host as props by WidgetHost (see widget.ts `monitorswitch` meta).
+type Props = {
+	monitor?: string; // GDI device name (\\.\DISPLAYn); blank = the primary monitor
+	sources?: string; // optional `code=label` spec choosing/ordering/renaming inputs
+	label?: string; // widget title override
+	showCurrent?: boolean;
+	showStats?: boolean;
+	compact?: boolean; // compact list instead of large touch buttons
+	color?: string;
+};
+
+// DDC reads are slow and the active input rarely changes from outside the app, so poll on a relaxed
+// cadence (+ on window focus), like the Audio Switcher — enough to keep the highlight honest.
+const REFRESH_MS = 8000;
+
+export default function MonitorSwitchHost({
+	monitor,
+	sources,
+	label,
+	showCurrent = true,
+	showStats = false,
+	compact = false,
+	color
+}: Props) {
+	const target = monitor?.trim() ?? '';
+	const [selected, setSelected] = useState<MonitorInputs | null>(null);
+	const [missing, setMissing] = useState(false);
+	const [busyValue, setBusyValue] = useState<number | null>(null);
+
+	const refresh = useCallback(async (): Promise<void> => {
+		const list = await listMonitorInputs(target || undefined);
+		const found = target
+			? list.find((m) => m.gdi === target) ?? null
+			: list.find((m) => m.primary) ?? list[0] ?? null;
+		setSelected(found);
+		setMissing(Boolean(target) && found === null);
+	}, [target]);
+
+	useEffect(() => {
+		let alive = true;
+		void refresh();
+		const onFocus = (): void => void refresh();
+		window.addEventListener('focus', onFocus);
+		const timer = window.setInterval(() => {
+			if (alive) void refresh();
+		}, REFRESH_MS);
+		return () => {
+			alive = false;
+			window.removeEventListener('focus', onFocus);
+			window.clearInterval(timer);
+		};
+	}, [refresh]);
+
+	const pick = useCallback(
+		async (value: number): Promise<void> => {
+			const gdi = selected?.gdi ?? target;
+			if (!gdi) return;
+			setBusyValue(value);
+			setSelected((s) => (s ? { ...s, current_input: value } : s)); // optimistic highlight
+			const ok = await setMonitorInput(gdi, value);
+			setBusyValue(null);
+			await refresh(); // reconcile with the input the monitor actually reports (snaps back on failure)
+			if (!ok) console.warn('monitor input switch failed; reverted to the reported input');
+		},
+		[selected, target, refresh]
+	);
+
+	const current = showCurrent ? selected?.current_input ?? null : null;
+	const rows = useMemo(
+		() => monitorInputRows({ discovered: selected?.supported ?? [], spec: sources, current }),
+		[selected, sources, current]
+	);
+	const title = label?.trim() || selected?.friendly || 'Monitor';
+	const stats = selected
+		? formatStats({
+				width: selected.width,
+				height: selected.height,
+				refreshHz: selected.refresh_hz
+		  })
+		: '';
+
+	return (
+		<MonitorSwitch
+			title={title}
+			rows={rows}
+			stats={stats}
+			showStats={showStats}
+			busyValue={busyValue}
+			missing={missing}
+			compact={compact}
+			onPick={pick}
+			color={color}
+		/>
+	);
+}
diff --git a/client/src/lib/widgets/MultiInspector.test.tsx b/client/src/lib/widgets/MultiInspector.test.tsx
new file mode 100644
index 0000000..113c33e
--- /dev/null
+++ b/client/src/lib/widgets/MultiInspector.test.tsx
@@ -0,0 +1,207 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, within } from '@testing-library/react';
+import MultiInspector from './MultiInspector';
+import type { MergedField } from './canvas/multiSelect';
+import type { ConfigField } from '../core/widget';
+
+// Presentational pane: the merged fields/basis are computed upstream (canvas/multiSelect.ts) and the
+// bulk apply lives in the Canvas. So the test feeds MergedField[] + a BasisSummary directly and
+// asserts what each control RENDERS and what editing it EMITS via the callbacks.
+
+const field = (f: ConfigField, value: unknown, mixed = false): MergedField => ({
+	field: f,
+	value,
+	mixed
+});
+
+const textField: ConfigField = { key: 'label', label: 'Label', kind: 'text' };
+const numField: ConfigField = { key: 'size', label: 'Size', kind: 'number' };
+const toggleField: ConfigField = { key: 'bold', label: 'Bold', kind: 'toggle' };
+const selectField: ConfigField = {
+	key: 'align',
+	label: 'Align',
+	kind: 'select',
+	options: ['left', 'center', 'right']
+};
+
+const items = [
+	{ id: 'w1', label: 'Gauge' },
+	{ id: 'w2', label: 'Clock' }
+];
+
+const baseProps = {
+	items,
+	fields: [] as MergedField[],
+	basis: null,
+	onFocus: vi.fn(),
+	onPatchConfig: vi.fn(),
+	onSetBasis: vi.fn(),
+	onDelete: vi.fn()
+};
+
+describe('MultiInspector header + item list', () => {
+	it('shows the selection count and one button per selected item', () => {
+		const { getByText } = render(<MultiInspector {...baseProps} />);
+		expect(getByText('2 widgets selected')).toBeTruthy();
+		expect(getByText('Gauge')).toBeTruthy();
+		expect(getByText('Clock')).toBeTruthy();
+	});
+
+	it('clicking an item focuses just that one (onFocus with its id)', () => {
+		const onFocus = vi.fn();
+		const { getByText } = render(<MultiInspector {...baseProps} onFocus={onFocus} />);
+		fireEvent.click(getByText('Clock'));
+		expect(onFocus).toHaveBeenCalledWith('w2');
+	});
+
+	it('the delete button reports the count and fires onDelete', () => {
+		const onDelete = vi.fn();
+		const { getByText } = render(<MultiInspector {...baseProps} onDelete={onDelete} />);
+		const del = getByText(/Delete 2/);
+		fireEvent.click(del);
+		expect(onDelete).toHaveBeenCalledTimes(1);
+	});
+});
+
+describe('MultiInspector common-properties empty state', () => {
+	it('shows the no-shared-properties note when there are no fields', () => {
+		const { getByText } = render(<MultiInspector {...baseProps} fields={[]} />);
+		expect(getByText(/No shared editable properties/)).toBeTruthy();
+	});
+
+	it('shows the "Common properties" heading when fields exist', () => {
+		const { getByText } = render(
+			<MultiInspector {...baseProps} fields={[field(textField, 'Hi')]} />
+		);
+		expect(getByText('Common properties')).toBeTruthy();
+	});
+});
+
+describe('MultiInspector text / number fields', () => {
+	it('renders a shared text value and emits the raw string on edit', () => {
+		const onPatchConfig = vi.fn();
+		const { getByLabelText } = render(
+			<MultiInspector
+				{...baseProps}
+				fields={[field(textField, 'Hi')]}
+				onPatchConfig={onPatchConfig}
+			/>
+		);
+		const input = getByLabelText('Label') as HTMLInputElement;
+		expect(input.value).toBe('Hi');
+		fireEvent.input(input, { target: { value: 'Bye' } });
+		expect(onPatchConfig).toHaveBeenCalledWith('label', 'Bye');
+	});
+
+	it('renders a number field that emits a coerced number', () => {
+		const onPatchConfig = vi.fn();
+		const { getByLabelText } = render(
+			<MultiInspector {...baseProps} fields={[field(numField, 12)]} onPatchConfig={onPatchConfig} />
+		);
+		const input = getByLabelText('Size') as HTMLInputElement;
+		expect(input.type).toBe('number');
+		expect(input.value).toBe('12');
+		fireEvent.input(input, { target: { value: '20' } });
+		expect(onPatchConfig).toHaveBeenCalledWith('size', 20);
+	});
+
+	it('a MIXED text field shows an empty value with a "mixed" placeholder', () => {
+		const { getByLabelText } = render(
+			<MultiInspector {...baseProps} fields={[field(textField, undefined, true)]} />
+		);
+		const input = getByLabelText('Label') as HTMLInputElement;
+		expect(input.value).toBe('');
+		expect(input.placeholder).toBe('mixed');
+	});
+});
+
+describe('MultiInspector toggle field', () => {
+	it('a shared-on toggle is checked and emits the new boolean', () => {
+		const onPatchConfig = vi.fn();
+		const { getByLabelText } = render(
+			<MultiInspector
+				{...baseProps}
+				fields={[field(toggleField, true)]}
+				onPatchConfig={onPatchConfig}
+			/>
+		);
+		const box = getByLabelText('Bold') as HTMLInputElement;
+		expect(box.checked).toBe(true);
+		expect(box.indeterminate).toBe(false);
+		fireEvent.click(box);
+		expect(onPatchConfig).toHaveBeenCalledWith('bold', false);
+	});
+
+	it('a MIXED toggle renders indeterminate (neither checked nor unchecked)', () => {
+		const { getByLabelText } = render(
+			<MultiInspector {...baseProps} fields={[field(toggleField, undefined, true)]} />
+		);
+		const box = getByLabelText('Bold') as HTMLInputElement;
+		expect(box.checked).toBe(false);
+		expect(box.indeterminate).toBe(true);
+	});
+});
+
+describe('MultiInspector select field (Downshift listbox)', () => {
+	it('emits onPatchConfig with the picked option value', () => {
+		const onPatchConfig = vi.fn();
+		const { getByLabelText, getByText } = render(
+			<MultiInspector
+				{...baseProps}
+				fields={[field(selectField, 'left')]}
+				onPatchConfig={onPatchConfig}
+			/>
+		);
+		// Open the listbox (the trigger carries the field's aria-label) and pick a value.
+		fireEvent.click(getByLabelText('Align'));
+		fireEvent.click(getByText('center'));
+		expect(onPatchConfig).toHaveBeenCalledWith('align', 'center');
+	});
+
+	it('a MIXED select offers a "— mixed —" option', () => {
+		const { getByLabelText, getByRole } = render(
+			<MultiInspector {...baseProps} fields={[field(selectField, undefined, true)]} />
+		);
+		fireEvent.click(getByLabelText('Align'));
+		// The trigger also shows the selected "— mixed —" label, so target the listbox OPTION specifically.
+		expect(getByRole('option', { name: '— mixed —' })).toBeTruthy();
+	});
+});
+
+describe('MultiInspector basis (size along the row / column)', () => {
+	it('renders the basis control only when a basis summary is given', () => {
+		const { queryByLabelText, rerender, getByLabelText } = render(
+			<MultiInspector {...baseProps} basis={null} />
+		);
+		expect(queryByLabelText('size along the row / column')).toBeNull();
+		rerender(<MultiInspector {...baseProps} basis="fixed" />);
+		expect(getByLabelText('size along the row / column')).toBeTruthy();
+	});
+
+	it('picking a basis option fires onSetBasis with the chosen mode', () => {
+		const onSetBasis = vi.fn();
+		const { getByLabelText, getByText } = render(
+			<MultiInspector {...baseProps} basis="fixed" onSetBasis={onSetBasis} />
+		);
+		fireEvent.click(getByLabelText('size along the row / column'));
+		fireEvent.click(getByText('grow — stretch to fill'));
+		expect(onSetBasis).toHaveBeenCalledWith('grow');
+	});
+
+	it('a MIXED basis adds a "— mixed —" option', () => {
+		const { getByLabelText, getByRole } = render(<MultiInspector {...baseProps} basis="mixed" />);
+		fireEvent.click(getByLabelText('size along the row / column'));
+		// The trigger also shows the selected "— mixed —" label, so target the listbox OPTION specifically.
+		expect(getByRole('option', { name: '— mixed —' })).toBeTruthy();
+	});
+});
+
+describe('MultiInspector docked variant', () => {
+	it('adds the docked class when docked', () => {
+		const { container } = render(<MultiInspector {...baseProps} docked />);
+		const root = container.querySelector('.inspector.multi')!;
+		expect(root.className).toContain('docked');
+		// Sanity: the same scoped query lands a single root node.
+		expect(within(root as HTMLElement).getByText('2 widgets selected')).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/NavRail.css b/client/src/lib/widgets/NavRail.css
index 3c99ed7..38f05ca 100644
--- a/client/src/lib/widgets/NavRail.css
+++ b/client/src/lib/widgets/NavRail.css
@@ -88,19 +88,10 @@
 	font-size: var(--text-lg);
 	z-index: 7;
 	pointer-events: auto;
-	/* A quick fade + tiny rise on open, so swapping sections reads as "new screen" not a hard cut. */
-	animation: rail-panel-in var(--motion, 150ms) var(--ease-out, ease-out);
-}
-
-@keyframes rail-panel-in {
-	from {
-		opacity: 0;
-		transform: translateY(-4px);
-	}
-	to {
-		opacity: 1;
-		transform: translateY(0);
-	}
+	/* No entry animation: the panel is opaque and covers the whole stage, so fading it up from
+	   opacity:0 briefly revealed the layout/stage behind it — a flash on every tab switch. An instant,
+	   opaque swap is flash-free. (A content-only fade could return the "new screen" cue without
+	   exposing the stage, but the hard swap is the safe fix.) */
 }
 
 /* A picker grid (widget types / templates) that spreads across the full-screen panel. */
diff --git a/client/src/lib/widgets/NavRail.test.tsx b/client/src/lib/widgets/NavRail.test.tsx
new file mode 100644
index 0000000..ead0f64
--- /dev/null
+++ b/client/src/lib/widgets/NavRail.test.tsx
@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { fireEvent, render } from '@testing-library/react';
+import NavRail from './NavRail';
+import { SECTIONS } from './canvas/studioSections';
+
+// NavRail is a presentational molecule: it renders one button per studio section, split into the
+// `main` group and the `foot` group around a spacer, and reports clicks via onSelect. The title /
+// aria-label / aria-current attribute logic is the interesting surface — drive it through the real
+// SECTIONS data so the test tracks the rail.
+
+const noop = () => undefined;
+
+describe('NavRail', () => {
+	it('renders one button per section, in two groups around the spacer', () => {
+		const { container } = render(<NavRail active="layouts" onSelect={noop} />);
+		const buttons = container.querySelectorAll('button.nav-item');
+		expect(buttons.length).toBe(SECTIONS.length);
+
+		const spacer = container.querySelector('.nav-spacer');
+		expect(spacer).not.toBeNull();
+
+		// The foot group renders after the spacer (Settings is the sole foot item).
+		const foot = SECTIONS.filter((s) => s.group === 'foot');
+		const lastBtn = container.querySelector(`button[data-section="${foot[0].id}"]`)!;
+		// spacer precedes the foot button in document order
+		const order = Array.from(container.querySelector('.nav-rail')!.children);
+		expect(order.indexOf(spacer!)).toBeLessThan(order.indexOf(lastBtn));
+	});
+
+	it('marks only the active section with the active class and aria-current=page', () => {
+		const { container } = render(<NavRail active="themes" onSelect={noop} />);
+		const active = container.querySelector('button[data-section="themes"]')!;
+		expect(active.classList.contains('active')).toBe(true);
+		expect(active.getAttribute('aria-current')).toBe('page');
+
+		const other = container.querySelector('button[data-section="layouts"]')!;
+		expect(other.classList.contains('active')).toBe(false);
+		expect(other.getAttribute('aria-current')).toBeNull();
+	});
+
+	it('fires onSelect with the section id on click', () => {
+		const onSelect = vi.fn();
+		const { container } = render(<NavRail active="layouts" onSelect={onSelect} />);
+		fireEvent.click(container.querySelector('button[data-section="sensors"]')!);
+		expect(onSelect).toHaveBeenCalledWith('sensors');
+	});
+
+	it('sets a title only when the full label differs from the short label, else omits it', () => {
+		const { container } = render(<NavRail active="layouts" onSelect={noop} />);
+
+		// widget-designer: label "Widget designer" !== short "Defs" → title is the full label.
+		const defs = container.querySelector('button[data-section="widget-designer"]')!;
+		expect(defs.getAttribute('title')).toBe('Widget designer');
+
+		// sensors: label "Sensors" === short "Sensors" and not a stub → no redundant title.
+		const sensors = container.querySelector('button[data-section="sensors"]')!;
+		expect(sensors.getAttribute('title')).toBeNull();
+	});
+
+	it('always exposes the full label as the accessible name via aria-label', () => {
+		const { container } = render(<NavRail active="layouts" onSelect={noop} />);
+		const sensors = container.querySelector('button[data-section="sensors"]')!;
+		expect(sensors.getAttribute('aria-label')).toBe('Sensors');
+		const backdrop = container.querySelector('button[data-section="background"]')!;
+		expect(backdrop.getAttribute('aria-label')).toBe('Background');
+		// the visible short label still differs from the accessible name
+		expect(backdrop.querySelector('.nav-short')!.textContent).toBe('Backdrop');
+	});
+
+	it('does not annotate the (non-stub) real sections with "(coming soon)"', () => {
+		const { container } = render(<NavRail active="layouts" onSelect={noop} />);
+		for (const s of SECTIONS) {
+			const btn = container.querySelector(`button[data-section="${s.id}"]`)!;
+			expect(btn.getAttribute('aria-label')).not.toContain('(coming soon)');
+		}
+	});
+
+	it('hides the decorative glyph from assistive tech and shows the short label', () => {
+		const { container } = render(<NavRail active="layouts" onSelect={noop} />);
+		const icon = container.querySelector('button[data-section="layouts"] .nav-icon')!;
+		expect(icon.getAttribute('aria-hidden')).toBe('true');
+		expect(container.querySelector('button[data-section="layouts"] .nav-short')!.textContent).toBe(
+			'Layout'
+		);
+	});
+});
+
+// SECTIONS today has no stub:true entry, so the "(coming soon)" arm (NavRail lines 23-24) is only
+// reachable for a future stub section. Drive that branch through the real component by mocking the
+// studioSections data to include a stub, re-importing NavRail under the mock.
+describe('NavRail — stub section ("coming soon" arm)', () => {
+	afterEach(() => vi.resetModules());
+
+	it('suffixes a stub section with "(coming soon)" in both title and aria-label', async () => {
+		vi.resetModules();
+		vi.doMock('./canvas/studioSections', () => ({
+			SECTIONS: [
+				{ id: 'layouts', label: 'Layouts', short: 'Layout', icon: '▤', group: 'main' },
+				{
+					id: 'future',
+					label: 'Future thing',
+					short: 'Future',
+					icon: '✦',
+					group: 'main',
+					stub: true
+				}
+			]
+		}));
+		const { default: NavRailMocked } = await import('./NavRail');
+		const { render: renderMocked } = await import('@testing-library/react');
+		const { container } = renderMocked(<NavRailMocked active="layouts" onSelect={noop} />);
+
+		const stub = container.querySelector('button[data-section="future"]')!;
+		// label "Future thing" !== short "Future" AND stub:true → both pieces appended
+		expect(stub.getAttribute('title')).toBe('Future thing (coming soon)');
+		expect(stub.getAttribute('aria-label')).toBe('Future thing (coming soon)');
+	});
+});
diff --git a/client/src/lib/widgets/NavRail.tsx b/client/src/lib/widgets/NavRail.tsx
index 757cac1..b17f56d 100644
--- a/client/src/lib/widgets/NavRail.tsx
+++ b/client/src/lib/widgets/NavRail.tsx
@@ -16,14 +16,19 @@ export default function NavRail({ active, onSelect }: Props) {
 			type="button"
 			data-section={s.id}
 			className={['nav-item', s.id === active && 'active'].filter(Boolean).join(' ')}
-			title={s.label + (s.stub ? ' (coming soon)' : '')}
+			// Native tooltip only when it ADDS to the visible short label (an abbreviation like "Defs" →
+			// "Widget designer", or "Backdrop" → "Background") or flags a stub — otherwise it just repeats
+			// the label that's already shown, which reads as redundant clutter. The full name is the
+			// accessible name regardless, via aria-label.
+			title={s.label !== s.short || s.stub ? s.label + (s.stub ? ' (coming soon)' : '') : undefined}
+			aria-label={s.label + (s.stub ? ' (coming soon)' : '')}
 			// Convey the open section to assistive tech (the visual cue is colour-only otherwise — WCAG
 			// 1.4.1). aria-current marks the active rail item as the current "page" of the studio.
 			aria-current={s.id === active ? 'page' : undefined}
 			onClick={() => onSelect(s.id)}
 		>
-			{/* Decorative glyph: the .nav-short text + title already name the button, so hide the icon
-			    from screen readers to avoid a doubled / emoji-name announcement. */}
+			{/* Decorative glyph: the aria-label already names the button, so hide the icon from screen
+			    readers to avoid a doubled / emoji-name announcement. */}
 			<span className="nav-icon" aria-hidden="true">
 				{s.icon}
 			</span>
diff --git a/client/src/lib/widgets/Outline.test.tsx b/client/src/lib/widgets/Outline.test.tsx
index 2e7db04..10c3fd5 100644
--- a/client/src/lib/widgets/Outline.test.tsx
+++ b/client/src/lib/widgets/Outline.test.tsx
@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest';
-import { render, fireEvent } from '@testing-library/react';
+import { render, fireEvent, within } from '@testing-library/react';
 import Outline from './Outline';
-import { emptyRoot, leaf, type Container } from '../core/layoutTree';
+import { container, emptyRoot, group, leaf, type Container, type Leaf } from '../core/layoutTree';
 import type { WidgetInstance } from '../core/layout';
 
 // A small flow tree: root(col) > [row > [a, b], c]
@@ -100,3 +100,215 @@ describe('Outline row context menu', () => {
 		expect(fireEvent.contextMenu(row)).toBe(true); // not prevented
 	});
 });
+
+// --- a labelled tree so rows are individually addressable by their hint text -----------------------
+const prim = (id: string, type: string, extra: Partial<WidgetInstance> = {}): WidgetInstance => ({
+	id,
+	type,
+	rect: { x: 0, y: 0, w: 100, h: 24 },
+	config: {},
+	...extra
+});
+
+// root(col)
+//   ├─ row "rowA"
+//   │    ├─ text "a-text"  (config.label "Hello")
+//   │    └─ gauge "a-gauge" (sensor "cpu.total")
+//   └─ clock "b-clock"
+const labelledRoot = (): Container =>
+	container(
+		'root',
+		'col',
+		[
+			container('rowA', 'row', [
+				leaf(prim('a-text', 'text', { config: { label: 'Hello' } })),
+				leaf(prim('a-gauge', 'gauge', { sensor: 'cpu.total' }))
+			]),
+			leaf(prim('b-clock', 'clock'))
+		],
+		{ align: 'stretch' }
+	);
+
+describe('Outline row labels + hints', () => {
+	it('shows each node primary text + the recognisable hint (label / sensor)', () => {
+		const { getByText } = render(<Outline root={labelledRoot()} />);
+		expect(getByText('▦ root (col)')).toBeTruthy();
+		expect(getByText('▦ row')).toBeTruthy();
+		expect(getByText('• text')).toBeTruthy();
+		expect(getByText('• gauge')).toBeTruthy();
+		expect(getByText('• clock')).toBeTruthy();
+		// hints: text leaf surfaces config.label, gauge surfaces its bound sensor.
+		expect(getByText('Hello')).toBeTruthy();
+		expect(getByText('cpu.total')).toBeTruthy();
+	});
+
+	it('shows a group leaf as "• group" with its name as the hint', () => {
+		const g = group('g1', { w: 50, h: 50 }, leaf(prim('inner', 'text')), { name: 'My Widget' });
+		const root = container('root', 'col', [leaf(g)]);
+		const { getByText } = render(<Outline root={root} />);
+		expect(getByText('• group')).toBeTruthy();
+		expect(getByText('My Widget')).toBeTruthy();
+	});
+
+	it('appends the scopeLabel to the header when given', () => {
+		const { getByText } = render(<Outline root={labelledRoot()} scopeLabel="MyDef" />);
+		expect(getByText('Outline · MyDef')).toBeTruthy();
+	});
+});
+
+describe('Outline select + structural ops', () => {
+	it('clicking a row label emits a select op for that node', () => {
+		const onOp = vi.fn();
+		const { getByText } = render(<Outline root={labelledRoot()} onOp={onOp} />);
+		fireEvent.click(getByText('• text'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'select', id: 'a-text' });
+	});
+
+	it('clicking the root row selects the root', () => {
+		const onOp = vi.fn();
+		const { getByText } = render(<Outline root={labelledRoot()} onOp={onOp} />);
+		fireEvent.click(getByText('▦ root (col)'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'select', id: 'root' });
+	});
+
+	it('the header +Row / +Column / +Grid buttons emit addContainer ops', () => {
+		const onOp = vi.fn();
+		const { getByText } = render(<Outline root={labelledRoot()} onOp={onOp} />);
+		fireEvent.click(getByText('＋ Row'));
+		fireEvent.click(getByText('＋ Column'));
+		fireEvent.click(getByText('＋ Grid'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'addContainer', kind: 'row' });
+		expect(onOp).toHaveBeenCalledWith({ op: 'addContainer', kind: 'col' });
+		expect(onOp).toHaveBeenCalledWith({ op: 'addContainer', kind: 'grid' });
+	});
+
+	it('the per-row action buttons emit move/outdent/remove ops scoped to that node', () => {
+		const onOp = vi.fn();
+		// a-text is the FIRST child of rowA (siblings: a-text, a-gauge) → Move down/out/float enabled.
+		const row = container('rowA', 'row', [
+			leaf(prim('a-text', 'text')),
+			leaf(prim('a-gauge', 'gauge'))
+		]);
+		const root = container('root', 'col', [row]);
+		const { getByText } = render(<Outline root={root} onOp={onOp} />);
+		// Scope the (per-row) action buttons to a-text's own row — every row renders the same set.
+		const aRow = within(getByText('• text').closest('.row')!);
+		fireEvent.click(aRow.getByLabelText('Move down'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'moveDown', id: 'a-text' });
+		fireEvent.click(aRow.getByLabelText('Move out'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'outdent', id: 'a-text' });
+		fireEvent.click(aRow.getByLabelText('Float'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'float', id: 'a-text' });
+	});
+
+	it('disables Move up for a first child and Move out for a direct child of root', () => {
+		// Two direct children of root so the disabled flags are unambiguous.
+		const root = container('root', 'col', [leaf(prim('x', 'text')), leaf(prim('y', 'text'))]);
+		const { getAllByText } = render(<Outline root={root} />);
+		// x is the first direct child of root → Move up disabled; its parent IS root → Move out disabled.
+		const xRow = within(getAllByText('• text')[0].closest('.row')!);
+		expect((xRow.getByLabelText('Move up') as HTMLButtonElement).disabled).toBe(true);
+		expect((xRow.getByLabelText('Move out') as HTMLButtonElement).disabled).toBe(true);
+	});
+
+	it('marks the selected node row with the .sel class', () => {
+		const { getByText } = render(<Outline root={labelledRoot()} selectedId="b-clock" />);
+		expect(getByText('• clock').closest('.row')!.className).toContain('sel');
+	});
+});
+
+describe('Outline hover cross-highlight', () => {
+	it('reports hover enter/leave for a row via onHover', () => {
+		const onHover = vi.fn();
+		const { getByText } = render(<Outline root={labelledRoot()} onHover={onHover} />);
+		const row = getByText('• clock').closest('.row')!;
+		fireEvent.mouseEnter(row);
+		expect(onHover).toHaveBeenCalledWith('b-clock');
+		fireEvent.mouseLeave(row);
+		expect(onHover).toHaveBeenCalledWith(null);
+	});
+
+	it('marks the hovered row with the .hover class from the hoverId prop', () => {
+		const { getByText } = render(<Outline root={labelledRoot()} hoverId="b-clock" />);
+		expect(getByText('• clock').closest('.row')!.className).toContain('hover');
+	});
+});
+
+describe('Outline drag-and-drop into containers', () => {
+	// happy-dom has no DataTransfer; a minimal stub that records type/data writes.
+	function fakeDataTransfer(initial: Record<string, string> = {}) {
+		const store: Record<string, string> = { ...initial };
+		return {
+			effectAllowed: '',
+			dropEffect: '',
+			setData: (k: string, v: string) => {
+				store[k] = v;
+			},
+			getData: (k: string) => store[k] ?? ''
+		};
+	}
+
+	it('dropping a node-id onto a CONTAINER row emits a reparent op', () => {
+		const onOp = vi.fn();
+		const { getByText } = render(<Outline root={labelledRoot()} onOp={onOp} />);
+		const containerRow = getByText('▦ row').closest('.row')!;
+		const dt = fakeDataTransfer({ 'text/x-node-id': 'b-clock' });
+		fireEvent.dragOver(containerRow, { dataTransfer: dt });
+		expect(containerRow.className).toContain('dropok'); // valid target highlight
+		fireEvent.drop(containerRow, { dataTransfer: dt });
+		expect(onOp).toHaveBeenCalledWith({ op: 'reparent', id: 'b-clock', containerId: 'rowA' });
+	});
+
+	it('dropping a palette widget-type onto a container row emits a dropWidget op', () => {
+		const onOp = vi.fn();
+		const { getByText } = render(<Outline root={labelledRoot()} onOp={onOp} />);
+		const containerRow = getByText('▦ row').closest('.row')!;
+		const dt = fakeDataTransfer({ 'text/x-widget-type': 'sparkline' });
+		fireEvent.dragOver(containerRow, { dataTransfer: dt });
+		fireEvent.drop(containerRow, { dataTransfer: dt });
+		expect(onOp).toHaveBeenCalledWith({
+			op: 'dropWidget',
+			containerId: 'rowA',
+			widgetType: 'sparkline'
+		});
+	});
+
+	it('dragging a row writes its node id onto the dataTransfer (so it can be reparented)', () => {
+		const { getByText } = render(<Outline root={labelledRoot()} />);
+		const leafRow = getByText('• clock').closest('.row')!;
+		const dt = fakeDataTransfer();
+		fireEvent.dragStart(leafRow, { dataTransfer: dt });
+		// The row carries its node id as the drag payload → a later drop reparents THIS node.
+		expect(dt.getData('text/x-node-id')).toBe('b-clock');
+	});
+
+	it('drag-leave clears the drop-target highlight from a container row', () => {
+		const { getByText } = render(<Outline root={labelledRoot()} />);
+		const containerRow = getByText('▦ row').closest('.row')!;
+		const dt = fakeDataTransfer({ 'text/x-node-id': 'b-clock' });
+		fireEvent.dragOver(containerRow, { dataTransfer: dt });
+		expect(containerRow.className).toContain('dropok');
+		fireEvent.dragLeave(containerRow, { dataTransfer: dt });
+		expect(containerRow.className).not.toContain('dropok');
+	});
+});
+
+describe('Outline floating layer', () => {
+	const floating: Leaf[] = [leaf(prim('fl-1', 'text', { config: { label: 'Floater' } }))];
+
+	it('renders a Floating section with a dock + remove action per floating leaf', () => {
+		const onOp = vi.fn();
+		const { getByText, getByLabelText } = render(
+			<Outline root={labelledRoot()} floating={floating} onOp={onOp} />
+		);
+		expect(getByText('Floating')).toBeTruthy();
+		expect(getByText('Floater')).toBeTruthy(); // the floating leaf's label hint
+		fireEvent.click(getByLabelText('Dock into root'));
+		expect(onOp).toHaveBeenCalledWith({ op: 'dock', id: 'fl-1' });
+	});
+
+	it('omits the Floating section when there are no floating leaves', () => {
+		const { queryByText } = render(<Outline root={labelledRoot()} />);
+		expect(queryByText('Floating')).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/PluginsPanel.test.tsx b/client/src/lib/widgets/PluginsPanel.test.tsx
new file mode 100644
index 0000000..da69c14
--- /dev/null
+++ b/client/src/lib/widgets/PluginsPanel.test.tsx
@@ -0,0 +1,425 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+import type { Plugin } from './plugin';
+import type { PackageRow } from './plugins/packages';
+
+// Keep the real package STORES (the panel subscribes to them via useStore) but spy the action
+// functions — installPackage / togglePackage / removePackage / checkPackageUpdate / updatePackage —
+// so a click's emitted call is observable without the Tauri command layer. importOriginal preserves
+// `packagesStore` + `enabledPackages` (real createStore/createPersistedStore instances) so a test
+// can drive the rendered rows with `.set(...)`.
+vi.mock('./plugins/packages', async (importOriginal) => {
+	const actual = await importOriginal<typeof import('./plugins/packages')>();
+	return {
+		...actual,
+		installPackage: vi.fn(() => Promise.resolve({ ok: true })),
+		togglePackage: vi.fn(() => Promise.resolve()),
+		removePackage: vi.fn(() => Promise.resolve({ ok: true })),
+		checkPackageUpdate: vi.fn(() =>
+			Promise.resolve({ ok: true, current: '1.0.0', latest: '2.0.0', updateAvailable: true })
+		),
+		updatePackage: vi.fn(() => Promise.resolve({ ok: true }))
+	};
+});
+// The built-in plugin-load-error table (registerBuiltinPlugins records throws here). Mocked so a
+// test can assert the "failed to load" rows render without actually breaking a plugin registration.
+vi.mock('./plugins', () => ({ pluginLoadErrors: vi.fn(() => []) }));
+
+import PluginsPanel from './PluginsPanel';
+import {
+	checkPackageUpdate,
+	enabledPackages,
+	installPackage,
+	packagesStore,
+	removePackage,
+	togglePackage,
+	updatePackage
+} from './plugins/packages';
+import { pluginLoadErrors } from './plugins';
+import { createTelemetryHub, type TelemetryHub } from '../core/telemetry';
+
+let hub: TelemetryHub;
+
+function renderPanel(over: Partial<Parameters<typeof PluginsPanel>[0]> = {}) {
+	hub = createTelemetryHub();
+	const props = {
+		hub,
+		plugins: [] as Plugin[],
+		selectedId: null as string | null,
+		onSelect: vi.fn(),
+		...over
+	};
+	return { ...render(<PluginsPanel {...props} />), props };
+}
+
+// A minimal package row; override the bits a test cares about.
+function pkgRow(over: Partial<PackageRow> = {}): PackageRow {
+	return {
+		id: 'demo',
+		name: 'Demo Pack',
+		version: '1.2.0',
+		error: null,
+		warnings: [],
+		templates: 0,
+		themeName: null,
+		sensors: 0,
+		hosts: [],
+		installedFrom: null,
+		...over
+	};
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	packagesStore.set([]);
+	enabledPackages.set([]);
+	vi.mocked(pluginLoadErrors).mockReturnValue([]);
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe('PluginsPanel plugin list', () => {
+	it('shows the empty stub when no plugins are registered', () => {
+		const { getByText } = renderPanel();
+		expect(getByText('No plugins registered.')).toBeTruthy();
+	});
+
+	it('lists each plugin and fires onSelect with its id on click', () => {
+		const plugins: Plugin[] = [
+			{ id: 'home-assistant', name: 'Home Assistant' },
+			{ id: 'now-playing', name: 'Now Playing' }
+		];
+		const { getByText, props } = renderPanel({ plugins });
+		expect(getByText('Home Assistant')).toBeTruthy();
+		fireEvent.click(getByText('Now Playing'));
+		expect(props.onSelect).toHaveBeenCalledWith('now-playing');
+	});
+
+	it('renders a plugin status dot that reflects the live status-sensor value', () => {
+		const plugins: Plugin[] = [
+			{ id: 'home-assistant', name: 'Home Assistant', statusSensor: 'ha.status' }
+		];
+		const { container } = renderPanel({ plugins });
+		// Absent sample → "Not connected" (statusDotFrom default → 'off').
+		expect(container.querySelector('.pl-dot--off')).toBeTruthy();
+		act(() => {
+			hub.ingest({ sensor: 'ha.status', ts_ms: 0, value: { kind: 'text', value: 'connected' } });
+		});
+		const dot = container.querySelector('.pl-dot') as HTMLElement;
+		expect(dot.classList.contains('pl-dot--ok')).toBe(true);
+		expect(dot.getAttribute('title')).toBe('Connected');
+	});
+
+	it('lists plugins whose registration threw as inert "failed to load" rows', () => {
+		vi.mocked(pluginLoadErrors).mockReturnValue([
+			{ id: 'mqtt', name: 'MQTT', error: 'boom while registering' }
+		]);
+		const { getByText, getByTitle } = renderPanel();
+		expect(getByText('MQTT')).toBeTruthy();
+		expect(getByText('failed to load')).toBeTruthy();
+		expect(getByTitle('boom while registering')).toBeTruthy();
+	});
+});
+
+describe('PluginsPanel detail pane', () => {
+	it('prompts to select a plugin when none is selected', () => {
+		const { getByText } = renderPanel({ plugins: [{ id: 'a', name: 'A' }] });
+		expect(getByText('Select a plugin to view its settings.')).toBeTruthy();
+	});
+
+	it('renders the selected plugin name + description and its custom settings panel', () => {
+		const Settings = () => <div data-testid="custom-settings">my settings UI</div>;
+		const plugins: Plugin[] = [
+			{ id: 'a', name: 'Alpha', description: 'the alpha plugin', settings: Settings }
+		];
+		const { getByText, getByTestId } = renderPanel({ plugins, selectedId: 'a' });
+		// "Alpha" appears in both the list button and the detail title — scope to the detail title.
+		expect(getByText('Alpha', { selector: '.pl-title' })).toBeTruthy();
+		expect(getByText('the alpha plugin')).toBeTruthy();
+		expect(getByTestId('custom-settings').textContent).toBe('my settings UI');
+	});
+
+	it('isolates a throwing settings panel behind the ErrorBoundary instead of blanking the rail', () => {
+		const Boom = () => {
+			throw new Error('settings exploded');
+		};
+		const plugins: Plugin[] = [{ id: 'a', name: 'Alpha', settings: Boom }];
+		// Silence the boundary's componentDidCatch console.error for a clean run.
+		vi.spyOn(console, 'error').mockImplementation(() => undefined);
+		const { getByRole } = renderPanel({ plugins, selectedId: 'a' });
+		const alert = getByRole('alert');
+		expect(alert.textContent).toContain('Alpha settings failed to render');
+		expect(alert.textContent).toContain('settings exploded');
+	});
+
+	it('falls back to a Sources + Widget types summary when the plugin ships no settings panel', () => {
+		const plugins: Plugin[] = [
+			{
+				id: 'sys',
+				name: 'System',
+				sources: [
+					{ id: 'system', start: async () => () => undefined, catalog: () => ['cpu.total'] }
+				],
+				widgets: [
+					{
+						meta: { type: 'gauge', label: 'Gauge', binds: 'scalar' },
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						component: (() => null) as any
+					}
+				]
+			}
+		];
+		const { getByText } = renderPanel({ plugins, selectedId: 'sys' });
+		expect(getByText('Sources')).toBeTruthy();
+		expect(getByText('system')).toBeTruthy();
+		expect(getByText('1 sensors')).toBeTruthy(); // the source's catalog count
+		expect(getByText('cpu.total')).toBeTruthy(); // SensorList row
+		expect(getByText('Widget types')).toBeTruthy();
+		expect(getByText('Gauge')).toBeTruthy();
+	});
+
+	it('shows the "no configurable settings" stub for a plugin with no settings, sources, or widgets', () => {
+		const plugins: Plugin[] = [{ id: 'bare', name: 'Bare' }];
+		const { getByText } = renderPanel({ plugins, selectedId: 'bare' });
+		expect(getByText('This plugin has no configurable settings.')).toBeTruthy();
+	});
+
+	it('renders only the Widget types section (no Sources, no stub) for a widgets-only plugin', () => {
+		const plugins: Plugin[] = [
+			{
+				id: 'w',
+				name: 'W',
+				widgets: [
+					{
+						meta: { type: 'gauge', label: 'Gauge', binds: 'scalar' },
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						component: (() => null) as any
+					}
+				]
+			}
+		];
+		const { getByText, queryByText } = renderPanel({ plugins, selectedId: 'w' });
+		expect(getByText('Widget types')).toBeTruthy();
+		expect(queryByText('Sources')).toBeNull();
+		// Has widgets → the "no configurable settings" stub must NOT appear.
+		expect(queryByText('This plugin has no configurable settings.')).toBeNull();
+	});
+
+	it('renders only the Sources section (no Widget types, no stub) for a sources-only plugin', () => {
+		const plugins: Plugin[] = [
+			{
+				id: 'src',
+				name: 'Src',
+				sources: [
+					{ id: 'system', start: async () => () => undefined, catalog: () => ['cpu.total'] }
+				]
+			}
+		];
+		const { getByText, queryByText } = renderPanel({ plugins, selectedId: 'src' });
+		expect(getByText('Sources')).toBeTruthy();
+		expect(queryByText('Widget types')).toBeNull();
+		// Has sources → the "no configurable settings" stub must NOT appear.
+		expect(queryByText('This plugin has no configurable settings.')).toBeNull();
+	});
+
+	it('renders "0 sensors" (no SensorList) for a source without a catalog, and a widget by type when it has no label', () => {
+		const plugins: Plugin[] = [
+			{
+				id: 'p',
+				name: 'P',
+				// A source with no catalog() → 0 sensors, no SensorList rows.
+				sources: [{ id: 'no-cat', start: async () => () => undefined }],
+				widgets: [
+					{
+						// No `label` in the meta → the row falls back to the bare type string.
+						meta: { type: 'spectrum', binds: 'none' },
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						component: (() => null) as any
+					}
+				]
+			}
+		];
+		const { getByText, container } = renderPanel({ plugins, selectedId: 'p' });
+		expect(getByText('0 sensors')).toBeTruthy();
+		expect(container.querySelector('.rp-sensors')).toBeNull(); // SensorList suppressed at 0 ids
+		// Label-less meta → the widget row uses the bare type for BOTH the name span and the dim type
+		// span, so the type string appears twice under Widget types.
+		const spectrumSpans = [...container.querySelectorAll('.rp-list .rp-row span')].filter(
+			(s) => s.textContent === 'spectrum'
+		);
+		expect(spectrumSpans.length).toBe(2);
+	});
+});
+
+describe('PluginsPanel packages list', () => {
+	it('shows the no-packages stub and the install button when nothing is discovered', () => {
+		const { getByText } = renderPanel();
+		expect(getByText('Install from URL…')).toBeTruthy();
+		expect(getByText(/No packages installed/)).toBeTruthy();
+	});
+
+	it('renders a package row with its name, version, and a singular contents subtext', () => {
+		// One template + a theme + one sensor → both count ternaries take the singular ('') arm.
+		act(() => packagesStore.set([pkgRow({ templates: 1, themeName: 'Midnight', sensors: 1 })]));
+		const { getByText } = renderPanel();
+		expect(getByText('Demo Pack')).toBeTruthy();
+		expect(getByText('v1.2.0')).toBeTruthy();
+		// packageSubtext joins the contents with " · ".
+		expect(getByText('1 template · theme “Midnight” · 1 sensor')).toBeTruthy();
+	});
+
+	it('pluralizes the template and sensor counts when there is more than one', () => {
+		act(() => packagesStore.set([pkgRow({ templates: 3, sensors: 2 })]));
+		const { getByText } = renderPanel();
+		expect(getByText('3 templates · 2 sensors')).toBeTruthy();
+	});
+
+	it('renders an "empty" subtext for a package that ships no templates, theme, or sensors', () => {
+		act(() => packagesStore.set([pkgRow()]));
+		const { getByText } = renderPanel();
+		expect(getByText('empty')).toBeTruthy();
+	});
+
+	it('shows a warning dot (no error) for a package that parsed with drop warnings', () => {
+		act(() => packagesStore.set([pkgRow({ warnings: ['dropped an unsupported template'] })]));
+		const { container, getByLabelText } = renderPanel();
+		// A warn dot with the joined warnings as its tooltip — but the toggle stays enabled.
+		expect(getByLabelText('Package warning')).toBeTruthy();
+		expect((getByLabelText('Enable Demo Pack') as HTMLInputElement).disabled).toBe(false);
+		expect(container.querySelector('[title="dropped an unsupported template"]')).toBeTruthy();
+	});
+
+	it('shows a failed-to-load subtext + untoggleable disabled checkbox for a parse failure', () => {
+		act(() => packagesStore.set([pkgRow({ error: 'bad manifest' })]));
+		const { getByText, getByLabelText } = renderPanel();
+		expect(getByText('failed to load')).toBeTruthy();
+		const box = getByLabelText('Enable Demo Pack') as HTMLInputElement;
+		expect(box.disabled).toBe(true);
+	});
+
+	it('reflects the enabled allowlist in the toggle and emits togglePackage on change', () => {
+		act(() => packagesStore.set([pkgRow()]));
+		act(() => enabledPackages.set(['demo']));
+		const { getByLabelText } = renderPanel();
+		const box = getByLabelText('Enable Demo Pack') as HTMLInputElement;
+		expect(box.checked).toBe(true);
+		fireEvent.click(box); // unchecking
+		expect(togglePackage).toHaveBeenCalledWith('demo', false, expect.any(Function));
+	});
+
+	it('wires the consent confirm callback through to window.confirm', () => {
+		act(() => packagesStore.set([pkgRow()]));
+		const confirmSpy = vi.spyOn(window, 'confirm').mockReturnValue(true);
+		// Drive the consent path: when the panel toggles, togglePackage invokes the confirm callback
+		// it was handed (the first-enable consent dialog) — assert it routes to window.confirm.
+		vi.mocked(togglePackage).mockImplementation((_id, _enabled, confirmEnable) => {
+			confirmEnable?.('Enable Demo Pack and allow network?');
+			return Promise.resolve();
+		});
+		const { getByLabelText } = renderPanel();
+		fireEvent.click(getByLabelText('Enable Demo Pack')); // enabling
+		expect(confirmSpy).toHaveBeenCalledWith('Enable Demo Pack and allow network?');
+	});
+
+	it('shows the declared network hosts as a dim line', () => {
+		act(() => packagesStore.set([pkgRow({ hosts: ['api.example.com', 'cdn.example.com'] })]));
+		const { getByText } = renderPanel();
+		expect(getByText('network: api.example.com, cdn.example.com')).toBeTruthy();
+	});
+
+	it('removes a package after the confirm dialog is accepted', async () => {
+		act(() => packagesStore.set([pkgRow()]));
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		const { getByText } = renderPanel();
+		fireEvent.click(getByText('Remove'));
+		await waitFor(() => expect(removePackage).toHaveBeenCalledWith('demo'));
+	});
+
+	it('alerts the reason when removal fails', async () => {
+		act(() => packagesStore.set([pkgRow()]));
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		const alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		vi.mocked(removePackage).mockResolvedValue({ ok: false, error: 'folder locked' });
+		const { getByText } = renderPanel();
+		fireEvent.click(getByText('Remove'));
+		await waitFor(() => expect(alertSpy).toHaveBeenCalledWith('Remove failed: folder locked'));
+	});
+
+	it('does NOT remove when the confirm dialog is declined', async () => {
+		act(() => packagesStore.set([pkgRow()]));
+		vi.spyOn(window, 'confirm').mockReturnValue(false);
+		const { getByText } = renderPanel();
+		fireEvent.click(getByText('Remove'));
+		// Give the (declined) async handler a tick — it must short-circuit before removePackage.
+		await act(async () => undefined);
+		expect(removePackage).not.toHaveBeenCalled();
+	});
+
+	it('installs from the URL prompt, passing the trimmed source', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('  owner/repo  ');
+		const { getByText } = renderPanel();
+		fireEvent.click(getByText('Install from URL…'));
+		await waitFor(() => expect(installPackage).toHaveBeenCalledWith('owner/repo'));
+	});
+
+	it('alerts the reason when the install fails', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('owner/repo');
+		const alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		vi.mocked(installPackage).mockResolvedValue({ ok: false, error: 'not found' });
+		const { getByText } = renderPanel();
+		fireEvent.click(getByText('Install from URL…'));
+		await waitFor(() => expect(alertSpy).toHaveBeenCalledWith('Install failed: not found'));
+	});
+
+	it('does not install when the install prompt is cancelled (empty)', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('');
+		const { getByText } = renderPanel();
+		fireEvent.click(getByText('Install from URL…'));
+		await act(async () => undefined);
+		expect(installPackage).not.toHaveBeenCalled();
+	});
+
+	it('offers a manual update check for a URL-installed row and surfaces an available update', async () => {
+		act(() => packagesStore.set([pkgRow({ installedFrom: 'owner/repo' })]));
+		const { getByText, findByText } = renderPanel();
+		expect(getByText('from owner/repo')).toBeTruthy();
+		fireEvent.click(getByText('Check updates'));
+		expect(checkPackageUpdate).toHaveBeenCalledWith('demo');
+		// The available-update state surfaces an Update button + a version line.
+		expect(await findByText('Update')).toBeTruthy();
+		fireEvent.click(getByText('Update'));
+		await waitFor(() => expect(updatePackage).toHaveBeenCalledWith('demo'));
+	});
+
+	it('falls back to "update failed" when the update returns an error-less failure', async () => {
+		act(() => packagesStore.set([pkgRow({ installedFrom: 'owner/repo' })]));
+		vi.mocked(updatePackage).mockResolvedValue({ ok: false }); // no `error` → default message
+		const { getByText, findByText } = renderPanel();
+		fireEvent.click(getByText('Check updates'));
+		fireEvent.click(await findByText('Update'));
+		expect(await findByText('update failed')).toBeTruthy();
+	});
+
+	it('reports "up to date" when the manual check finds no newer version', async () => {
+		act(() => packagesStore.set([pkgRow({ installedFrom: 'owner/repo' })]));
+		vi.mocked(checkPackageUpdate).mockResolvedValue({
+			ok: true,
+			current: '1.2.0',
+			latest: '1.2.0',
+			updateAvailable: false
+		});
+		const { getByText, findByText } = renderPanel();
+		fireEvent.click(getByText('Check updates'));
+		expect(await findByText('up to date')).toBeTruthy();
+	});
+
+	it('surfaces the manual update-check error message when the check fails', async () => {
+		act(() => packagesStore.set([pkgRow({ installedFrom: 'owner/repo' })]));
+		vi.mocked(checkPackageUpdate).mockResolvedValue({ ok: false, error: 'network unreachable' });
+		const { getByText, findByText } = renderPanel();
+		fireEvent.click(getByText('Check updates'));
+		expect(await findByText('network unreachable')).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/SensorList.test.tsx b/client/src/lib/widgets/SensorList.test.tsx
new file mode 100644
index 0000000..58e9456
--- /dev/null
+++ b/client/src/lib/widgets/SensorList.test.tsx
@@ -0,0 +1,174 @@
+import { describe, expect, it } from 'vitest';
+import { act, fireEvent, render } from '@testing-library/react';
+import SensorList from './SensorList';
+import { createTelemetryHub, type TelemetryHub } from '../core/telemetry';
+import type { SensorActivity } from '../core/sensorActivity';
+
+// SensorList rows subscribe live via useSensor; ingest happens outside React, so wrap in act().
+function ingest(hub: TelemetryHub, id: string, value: number | string): void {
+	act(() => {
+		hub.ingest({
+			sensor: id,
+			ts_ms: 0,
+			value: typeof value === 'number' ? { kind: 'scalar', value } : { kind: 'text', value }
+		});
+	});
+}
+
+describe('SensorList — flat (no filter)', () => {
+	it('renders one row per id with its live value, ticking in place', () => {
+		const hub = createTelemetryHub();
+		const ids = ['mqtt.alpha', 'mqtt.beta'];
+		const { container, getByTitle } = render(<SensorList hub={hub} ids={ids} />);
+		// Both ids render as rows (title carries the id); value shows the em-dash placeholder until a sample.
+		expect(getByTitle('mqtt.alpha')).toBeTruthy();
+		expect(getByTitle('mqtt.beta')).toBeTruthy();
+		expect(container.querySelectorAll('.rp-row').length).toBe(2);
+
+		ingest(hub, 'mqtt.alpha', 42);
+		// The row's value cell now reflects the ingested sample (integer id → plain number).
+		const alphaRow = getByTitle('mqtt.alpha').closest('.rp-row') as HTMLElement;
+		expect(alphaRow.querySelector('.dim')?.textContent).toBe('42');
+	});
+
+	it('shows an empty stub when there are no ids', () => {
+		const hub = createTelemetryHub();
+		const { getByText, container } = render(<SensorList hub={hub} ids={[]} />);
+		expect(() => getByText('No sensors yet.')).not.toThrow();
+		expect(container.querySelector('.rp-row')).toBeNull();
+	});
+
+	it('renders a per-row badge from badgeFor in the ungrouped list', () => {
+		const hub = createTelemetryHub();
+		const { getByText } = render(
+			<SensorList hub={hub} ids={['mqtt.alpha']} badgeFor={() => 'mqtt'} />
+		);
+		const badge = getByText('mqtt');
+		expect(badge.className).toContain('rp-badge');
+	});
+});
+
+describe('SensorList — filter box', () => {
+	it('shows the total count and filters rows by a case-insensitive substring', () => {
+		const hub = createTelemetryHub();
+		const ids = ['cpu.total.pct', 'mem.used.pct', 'net.rx'];
+		const { container, getByLabelText, getByText, queryByTitle } = render(
+			<SensorList hub={hub} ids={ids} filter />
+		);
+		// Count starts as the full total.
+		expect(() => getByText('3')).not.toThrow();
+
+		fireEvent.input(getByLabelText('Filter sensors'), { target: { value: 'CPU' } });
+		expect(queryByTitle('cpu.total.pct')).toBeTruthy();
+		expect(queryByTitle('mem.used.pct')).toBeNull();
+		expect(container.querySelectorAll('.rp-row').length).toBe(1);
+		// Count switches to "shown / total" while filtered.
+		expect(() => getByText('1 / 3')).not.toThrow();
+	});
+
+	it('shows a "no match" stub when the filter excludes everything (ids present)', () => {
+		const hub = createTelemetryHub();
+		const { getByLabelText, getByText } = render(
+			<SensorList hub={hub} ids={['cpu.total.pct']} filter />
+		);
+		fireEvent.input(getByLabelText('Filter sensors'), { target: { value: 'zzz' } });
+		expect(() => getByText('No sensors match.')).not.toThrow();
+	});
+
+	it('shows the empty stub (not "no match") when there were never any ids', () => {
+		const hub = createTelemetryHub();
+		const { getByText } = render(<SensorList hub={hub} ids={[]} filter />);
+		expect(() => getByText('No sensors yet.')).not.toThrow();
+	});
+});
+
+describe('SensorList — grouped', () => {
+	const groupFor = (id: string) => (id.startsWith('cpu.') ? 'System' : 'MQTT');
+
+	it('renders a header per group with its id-count, and collapses on click', () => {
+		const hub = createTelemetryHub();
+		const ids = ['cpu.total.pct', 'mqtt.alpha', 'mqtt.beta'];
+		const { container, getByText, getByTitle } = render(
+			<SensorList hub={hub} ids={ids} filter groupFor={groupFor} />
+		);
+		// System group floats to the top; both group headers present.
+		expect(() => getByText('System')).not.toThrow();
+		expect(() => getByText('MQTT')).not.toThrow();
+		// Rows from both groups are visible while expanded.
+		expect(getByTitle('cpu.total.pct')).toBeTruthy();
+		expect(getByTitle('mqtt.alpha')).toBeTruthy();
+
+		// Collapsing the MQTT group hides its rows but keeps the header.
+		const mqttHeader = getByText('MQTT').closest('button') as HTMLButtonElement;
+		expect(mqttHeader.getAttribute('aria-expanded')).toBe('true');
+		fireEvent.click(mqttHeader);
+		expect(mqttHeader.getAttribute('aria-expanded')).toBe('false');
+		expect(container.querySelector('[title="mqtt.alpha"]')).toBeNull();
+		// The System group is unaffected.
+		expect(getByTitle('cpu.total.pct')).toBeTruthy();
+	});
+
+	it('suppresses per-row badges in grouped mode (the header carries the source)', () => {
+		const hub = createTelemetryHub();
+		const { queryByText } = render(
+			<SensorList
+				hub={hub}
+				ids={['mqtt.alpha']}
+				filter
+				groupFor={groupFor}
+				badgeFor={() => 'mqtt'}
+			/>
+		);
+		// The MQTT group header exists, but no per-row .rp-badge "mqtt" pill.
+		expect(queryByText('mqtt')).toBeNull();
+	});
+});
+
+describe('SensorList — activity dots + legend', () => {
+	const activityFor =
+		(map: Record<string, SensorActivity>) =>
+		(id: string): SensorActivity | null =>
+			map[id] ?? null;
+
+	const referenced: SensorActivity = { active: true, referenced: true, reason: 'used by gauge' };
+	const alwaysOn: SensorActivity = {
+		active: true,
+		referenced: false,
+		reason: 'always sampled (a cheap system sensor)'
+	};
+	const studioOnly: SensorActivity = {
+		active: false,
+		referenced: false,
+		reason: 'stops when the studio closes'
+	};
+
+	it('renders a shaped status dot per row reflecting its after-close fate', () => {
+		const hub = createTelemetryHub();
+		const map = { 'a.ref': referenced, 'b.on': alwaysOn, 'c.studio': studioOnly };
+		const { getByTitle } = render(
+			<SensorList hub={hub} ids={Object.keys(map)} activityFor={activityFor(map)} />
+		);
+		// ★ referenced, ● always-on, ○ studio-only (shape, not colour alone — WCAG 1.4.1).
+		const dotFor = (id: string) =>
+			getByTitle(id).closest('.rp-row')?.querySelector('.sensor-dot') as HTMLElement;
+		expect(dotFor('a.ref').textContent).toBe('★');
+		expect(dotFor('a.ref').className).toContain('on');
+		expect(dotFor('b.on').textContent).toBe('●');
+		expect(dotFor('b.on').className).toContain('amb');
+		expect(dotFor('c.studio').textContent).toBe('○');
+		expect(dotFor('c.studio').className).toContain('off');
+	});
+
+	it('summarizes the after-close legend counts in filter mode', () => {
+		const hub = createTelemetryHub();
+		const map = { 'a.ref': referenced, 'b.on': alwaysOn, 'c.studio': studioOnly };
+		const { getByText } = render(
+			<SensorList hub={hub} ids={Object.keys(map)} filter activityFor={activityFor(map)} />
+		);
+		// 1 referenced, (2 active − 1 referenced) = 1 always-on, (3 total − 2 active) = 1 studio-only.
+		expect(() => getByText('1 used by widgets')).not.toThrow();
+		expect(() => getByText('1 always-on')).not.toThrow();
+		expect(() => getByText('1 studio-only')).not.toThrow();
+		expect(() => getByText('2/3 stay active after close')).not.toThrow();
+	});
+});
diff --git a/client/src/lib/widgets/StudioSettingsPanel.test.tsx b/client/src/lib/widgets/StudioSettingsPanel.test.tsx
new file mode 100644
index 0000000..32555d5
--- /dev/null
+++ b/client/src/lib/widgets/StudioSettingsPanel.test.tsx
@@ -0,0 +1,310 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor, within } from '@testing-library/react';
+import type { Rect } from '../core/layout';
+import type { OverlayPrefs } from './canvas/overlayPrefs';
+
+// Stub the stateless overlay helpers the panel calls directly (devtools / rescue / clipboard /
+// update check). They are the only module-level side effects in this panel — everything else is
+// owned by Canvas and arrives as props.
+const { checkAppUpdate, copyToClipboard, openDevtools, rescueWindows } = vi.hoisted(() => ({
+	checkAppUpdate: vi.fn(),
+	copyToClipboard: vi.fn(() => Promise.resolve(true)),
+	openDevtools: vi.fn(() => Promise.resolve()),
+	rescueWindows: vi.fn(() => Promise.resolve())
+}));
+vi.mock('../overlay', () => ({ checkAppUpdate, copyToClipboard, openDevtools, rescueWindows }));
+
+// The two child panels are tested in isolation; stub them so this test exercises only the settings
+// shell (tab switching + the sections it owns) and can assert they get the pass-through props.
+vi.mock('./ControlsPanel', () => ({
+	default: (p: Record<string, unknown>) => (
+		<div data-testid="controls-panel" data-has-rebind={typeof p.onRebind === 'function'} />
+	)
+}));
+vi.mock('./DiagnosticsPanel', () => ({
+	default: () => <div data-testid="diagnostics-panel" />
+}));
+vi.mock('../../assets/mascot.png', () => ({ default: 'mascot.png' }));
+
+import StudioSettingsPanel, { SETTINGS_TABS, type SettingsTab } from './StudioSettingsPanel';
+
+const baseProps = (over: Partial<Parameters<typeof StudioSettingsPanel>[0]> = {}) => {
+	const workArea: Rect = { x: 0, y: 0, w: 1920, h: 1040 };
+	return {
+		tab: 'display' as SettingsTab,
+		onTab: vi.fn(),
+		display: {
+			monName: 'DELL U2720Q',
+			monSize: { w: 3840, h: 2160 },
+			workArea,
+			multiMonitor: false,
+			zoom: 0.5,
+			fit: vi.fn()
+		},
+		theme: {
+			options: [
+				{ value: '', label: 'Default' },
+				{ value: 'neon', label: 'Neon' }
+			],
+			selected: '',
+			setTheme: vi.fn(),
+			lock: true,
+			setLock: vi.fn()
+		},
+		overlay: {
+			prefs: {
+				respectWorkArea: true,
+				overlayLayer: 'bottom',
+				debugWindowed: false
+			} as OverlayPrefs,
+			setPrefs: vi.fn(),
+			layerStatus: 'always on top'
+		},
+		startup: { autostart: false, toggleAutostart: vi.fn() },
+		controls: { overrides: {}, onRebind: vi.fn(), onReset: vi.fn(), onResetAll: vi.fn() },
+		appVersion: '1.2.3',
+		clearMonitor: vi.fn(),
+		...over
+	};
+};
+
+const flush = () => act(async () => undefined);
+
+beforeEach(() => {
+	checkAppUpdate.mockReset();
+	copyToClipboard.mockReset().mockResolvedValue(true);
+	openDevtools.mockReset().mockResolvedValue(undefined);
+	rescueWindows.mockReset().mockResolvedValue(undefined);
+});
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('StudioSettingsPanel — tab list', () => {
+	// Tab labels collide with the section titles ("Display", "Overlay", …), so scope queries to the
+	// side list (.pl-list) to hit the buttons specifically.
+	const tabBtn = (container: HTMLElement, label: string): HTMLButtonElement => {
+		const list = within(container.querySelector('.pl-list') as HTMLElement);
+		return list.getByText(label) as HTMLButtonElement;
+	};
+
+	it('renders every settings tab and marks the danger tab apart', () => {
+		const { container } = render(<StudioSettingsPanel {...baseProps()} />);
+		for (const t of SETTINGS_TABS) expect(() => tabBtn(container, t.label)).not.toThrow();
+		expect(tabBtn(container, 'Danger zone').className).toContain('set-danger');
+	});
+
+	it('marks the active tab and calls onTab when a tab is clicked', () => {
+		const onTab = vi.fn();
+		const { container } = render(<StudioSettingsPanel {...baseProps({ onTab, tab: 'overlay' })} />);
+		expect(tabBtn(container, 'Overlay').className).toContain('cur');
+		fireEvent.click(tabBtn(container, 'Startup'));
+		expect(onTab).toHaveBeenCalledWith('startup');
+	});
+});
+
+describe('StudioSettingsPanel — Display section', () => {
+	it('shows the monitor name/size + rounded work area, and a single-monitor view has no move hint', () => {
+		const { getByText, queryByText, container } = render(<StudioSettingsPanel {...baseProps()} />);
+		expect(() => getByText('DELL U2720Q · 3840×2160')).not.toThrow();
+		// workArea rounded for display.
+		expect(container.textContent).toContain('1920×1040');
+		expect(queryByText(/Move a widget to another monitor/)).toBeNull();
+		// Fit button shows the zoom percentage.
+		expect(() => getByText('⤢ Fit to screen (50%)')).not.toThrow();
+	});
+
+	it('falls back to an em-dash for an unnamed monitor and shows the multi-monitor move hint', () => {
+		const props = baseProps();
+		props.display.monName = '';
+		props.display.multiMonitor = true;
+		const { getByText, queryByText } = render(<StudioSettingsPanel {...props} />);
+		expect(() => getByText('— · 3840×2160')).not.toThrow();
+		expect(queryByText(/Move a widget to another monitor/)).not.toBeNull();
+	});
+
+	it('Fit to screen calls the supplied fit handler', () => {
+		const props = baseProps();
+		const { getByText } = render(<StudioSettingsPanel {...props} />);
+		fireEvent.click(getByText(/Fit to screen/));
+		expect(props.display.fit).toHaveBeenCalledOnce();
+	});
+
+	it('locked theme: shows the all-monitors copy + the global picker, toggling lock + theme', () => {
+		const props = baseProps();
+		const { getByText, getByLabelText } = render(<StudioSettingsPanel {...props} />);
+		expect(() => getByText(/One theme styles every monitor/)).not.toThrow();
+		// Lock checkbox is on; unchecking it reports false. The <label> wraps the span + checkbox, so
+		// reach the checkbox via the label that carries the copy.
+		const lockLabel = getByText('apply theme to all monitors').closest('label') as HTMLElement;
+		const lockBox = lockLabel.querySelector('input[type="checkbox"]') as HTMLInputElement;
+		expect(lockBox.checked).toBe(true);
+		fireEvent.click(lockBox);
+		expect(props.theme.setLock).toHaveBeenCalledWith(false);
+		// The picker is labelled for all monitors when locked.
+		const select = getByLabelText('Theme for all monitors') as HTMLSelectElement;
+		fireEvent.change(select, { target: { value: 'neon' } });
+		expect(props.theme.setTheme).toHaveBeenCalledWith('neon');
+	});
+
+	it('unlocked theme: shows the per-monitor copy + a per-monitor-labelled picker', () => {
+		const props = baseProps();
+		props.theme.lock = false;
+		const { getByText, getByLabelText } = render(<StudioSettingsPanel {...props} />);
+		expect(() => getByText(/Each monitor keeps its own theme/)).not.toThrow();
+		expect(() => getByText('theme · DELL U2720Q')).not.toThrow();
+		expect(getByLabelText('Theme for this monitor')).toBeTruthy();
+	});
+
+	it('unlocked theme on an unnamed monitor falls back to "this monitor" in the picker label', () => {
+		const props = baseProps();
+		props.theme.lock = false;
+		props.display.monName = '';
+		const { getByText } = render(<StudioSettingsPanel {...props} />);
+		expect(() => getByText('theme · this monitor')).not.toThrow();
+	});
+});
+
+describe('StudioSettingsPanel — Overlay section', () => {
+	const overlayProps = (over: Partial<OverlayPrefs> = {}) => {
+		const props = baseProps({ tab: 'overlay' });
+		props.overlay.prefs = { ...props.overlay.prefs, ...over };
+		return props;
+	};
+
+	it('toggles respect-work-area, the layer select, and windowed mode through setPrefs', () => {
+		const props = overlayProps();
+		const { getByText, container } = render(<StudioSettingsPanel {...props} />);
+		const [work, windowed] = container.querySelectorAll<HTMLInputElement>('input[type="checkbox"]');
+		fireEvent.click(work);
+		expect(props.overlay.setPrefs).toHaveBeenCalledWith({ respectWorkArea: false });
+
+		const select = container.querySelector('select') as HTMLSelectElement;
+		fireEvent.change(select, { target: { value: 'wallpaper' } });
+		expect(props.overlay.setPrefs).toHaveBeenCalledWith({ overlayLayer: 'wallpaper' });
+
+		fireEvent.click(windowed);
+		expect(props.overlay.setPrefs).toHaveBeenCalledWith({ debugWindowed: true });
+
+		// The layer status line is shown verbatim.
+		expect(() => getByText('always on top')).not.toThrow();
+	});
+
+	it('shows the waiting placeholder when no layer status has been reported', () => {
+		const props = overlayProps();
+		props.overlay.layerStatus = '';
+		const { getByText } = render(<StudioSettingsPanel {...props} />);
+		expect(() => getByText(/waiting for the overlay to apply a layer/)).not.toThrow();
+	});
+});
+
+describe('StudioSettingsPanel — Startup section', () => {
+	it('reflects the autostart pref and toggles it', () => {
+		const props = baseProps({ tab: 'startup' });
+		const { container } = render(<StudioSettingsPanel {...props} />);
+		const box = container.querySelector('input[type="checkbox"]') as HTMLInputElement;
+		expect(box.checked).toBe(false);
+		fireEvent.click(box);
+		expect(props.startup.toggleAutostart).toHaveBeenCalledWith(true);
+	});
+});
+
+describe('StudioSettingsPanel — Controls section', () => {
+	it('mounts ControlsPanel with the pass-through handlers', () => {
+		const props = baseProps({ tab: 'controls' });
+		const { getByTestId } = render(<StudioSettingsPanel {...props} />);
+		const panel = getByTestId('controls-panel');
+		expect(panel.getAttribute('data-has-rebind')).toBe('true');
+	});
+});
+
+describe('StudioSettingsPanel — Diagnostics section', () => {
+	it('mounts DiagnosticsPanel and wires the devtools + rescue buttons', () => {
+		const props = baseProps({ tab: 'diagnostics' });
+		const { getByText, getByTestId } = render(<StudioSettingsPanel {...props} />);
+		expect(getByTestId('diagnostics-panel')).toBeTruthy();
+		fireEvent.click(getByText(/Inspect this window/));
+		expect(openDevtools).toHaveBeenCalledOnce();
+		fireEvent.click(getByText(/Rescue all windows/));
+		expect(rescueWindows).toHaveBeenCalledOnce();
+	});
+});
+
+describe('StudioSettingsPanel — About section', () => {
+	it('shows the version + license and copies the repo link', async () => {
+		const props = baseProps({ tab: 'about' });
+		const { getByText, container } = render(<StudioSettingsPanel {...props} />);
+		expect(container.textContent).toContain('1.2.3');
+		expect(() => getByText('MIT OR Apache-2.0')).not.toThrow();
+		const repoRow = getByText('github.com/gyng/widgetsack').closest('.rp-row') as HTMLElement;
+		fireEvent.click(within(repoRow).getByText('copy'));
+		expect(copyToClipboard).toHaveBeenCalledWith('https://github.com/gyng/widgetsack');
+		await flush();
+	});
+
+	it('shows an ellipsis placeholder when the app version is null', () => {
+		const props = baseProps({ tab: 'about', appVersion: null });
+		const { container } = render(<StudioSettingsPanel {...props} />);
+		const versionRow = [...container.querySelectorAll('.rp-row')].find((r) =>
+			r.textContent?.startsWith('version')
+		) as HTMLElement;
+		expect(versionRow.querySelector('.dim')?.textContent).toBe('…');
+	});
+
+	describe('AppUpdateCheck', () => {
+		it('reports "up to date" when no update is available', async () => {
+			checkAppUpdate.mockResolvedValue({
+				updateAvailable: false,
+				current: '1.2.3',
+				latest: '1.2.3',
+				url: 'https://x'
+			});
+			const props = baseProps({ tab: 'about' });
+			const { getByText, findByText } = render(<StudioSettingsPanel {...props} />);
+			fireEvent.click(getByText(/Check for updates/));
+			// The button flips to a busy label while the check is in flight.
+			expect(() => getByText('Checking…')).not.toThrow();
+			expect(await findByText(/You’re up to date \(v1\.2\.3\)/)).toBeTruthy();
+		});
+
+		it('offers a copy-link row when an update is available', async () => {
+			checkAppUpdate.mockResolvedValue({
+				updateAvailable: true,
+				current: '1.2.3',
+				latest: '1.3.0',
+				url: 'https://example/release'
+			});
+			const props = baseProps({ tab: 'about' });
+			const { getByText, findByText } = render(<StudioSettingsPanel {...props} />);
+			fireEvent.click(getByText(/Check for updates/));
+			expect(await findByText('v1.3.0 available')).toBeTruthy();
+			fireEvent.click(getByText('copy link'));
+			await waitFor(() => expect(copyToClipboard).toHaveBeenCalledWith('https://example/release'));
+		});
+
+		it('surfaces an Error message inline when the check throws', async () => {
+			checkAppUpdate.mockRejectedValue(new Error('offline'));
+			const props = baseProps({ tab: 'about' });
+			const { getByText, findByText } = render(<StudioSettingsPanel {...props} />);
+			fireEvent.click(getByText(/Check for updates/));
+			const msg = await findByText(/Update check failed: offline/);
+			expect(msg.getAttribute('title')).toBe('offline');
+		});
+
+		it('stringifies a non-Error rejection in the failure message', async () => {
+			checkAppUpdate.mockRejectedValue('nope');
+			const props = baseProps({ tab: 'about' });
+			const { getByText, findByText } = render(<StudioSettingsPanel {...props} />);
+			fireEvent.click(getByText(/Check for updates/));
+			expect(await findByText(/Update check failed: nope/)).toBeTruthy();
+		});
+	});
+});
+
+describe('StudioSettingsPanel — Danger section', () => {
+	it('clears this monitor when the danger button is pressed', () => {
+		const props = baseProps({ tab: 'danger' });
+		const { getByText } = render(<StudioSettingsPanel {...props} />);
+		fireEvent.click(getByText(/Clear this monitor/));
+		expect(props.clearMonitor).toHaveBeenCalledOnce();
+	});
+});
diff --git a/client/src/lib/widgets/StyleLayer.test.tsx b/client/src/lib/widgets/StyleLayer.test.tsx
new file mode 100644
index 0000000..ddd40b7
--- /dev/null
+++ b/client/src/lib/widgets/StyleLayer.test.tsx
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import StyleLayer from './StyleLayer';
+
+// StyleLayer is an atom: it drops the pre-assembled (core/style.ts) stylesheet string into a real
+// <style> element via dangerouslySetInnerHTML. Verify the element renders and carries the CSS
+// verbatim, and that the default empty-string prop renders an empty <style>.
+
+describe('StyleLayer', () => {
+	it('renders a <style> element carrying the supplied CSS verbatim', () => {
+		const css = '.np { color: red; }\n.bar::after { content: "x"; }';
+		const { container } = render(<StyleLayer css={css} />);
+		const style = container.querySelector('style');
+		expect(style).not.toBeNull();
+		expect(style!.innerHTML).toBe(css);
+	});
+
+	it('renders an empty <style> when css is omitted (default empty string)', () => {
+		const { container } = render(<StyleLayer />);
+		const style = container.querySelector('style');
+		expect(style).not.toBeNull();
+		expect(style!.innerHTML).toBe('');
+	});
+});
diff --git a/client/src/lib/widgets/ThemeList.test.tsx b/client/src/lib/widgets/ThemeList.test.tsx
index 92202e3..43693dd 100644
--- a/client/src/lib/widgets/ThemeList.test.tsx
+++ b/client/src/lib/widgets/ThemeList.test.tsx
@@ -119,4 +119,66 @@ describe('<ThemeList>', () => {
 		const nordRow = screen.getByRole('button', { name: /^Nord/ });
 		expect(nordRow).toHaveAttribute('aria-pressed', 'true');
 	});
+
+	// The filter box only appears once the combined list is long enough to be worth searching
+	// (FILTER_THRESHOLD = 8 non-default items).
+	describe('filter box (long list)', () => {
+		// 10 user themes → comfortably over the threshold and easy to filter down deterministically.
+		const manyUser = Array.from({ length: 10 }, (_, i) => ({
+			value: `theme-${i}`,
+			label: i < 3 ? `alpha-${i}` : `beta-${i}`
+		}));
+
+		const renderMany = () =>
+			render(
+				<ThemeList
+					groups={[]}
+					userThemes={manyUser}
+					active=""
+					onPick={vi.fn()}
+					onEdit={vi.fn()}
+					onDuplicate={vi.fn()}
+					onDelete={vi.fn()}
+				/>
+			);
+
+		it('does NOT show the filter box for a short list', () => {
+			setup(); // 2 built-ins + 1 user = 3 non-default, below the threshold
+			expect(screen.queryByLabelText('Filter themes')).toBeNull();
+		});
+
+		it('shows the filter box and the total count once the list is long', () => {
+			renderMany();
+			expect(screen.getByLabelText('Filter themes')).toBeInTheDocument();
+			// total = 10 user + 1 default = 11; with no query shown === total so the bare total renders.
+			expect(screen.getByText('11')).toBeInTheDocument();
+		});
+
+		it('filters the visible rows and shows a "shown / total" count as you type', () => {
+			renderMany();
+			const input = screen.getByLabelText('Filter themes') as HTMLInputElement;
+			fireEvent.input(input, { target: { value: 'alpha' } });
+			// Only the 3 alpha-* user themes survive; the default no longer matches.
+			expect(screen.getByText('alpha-0')).toBeInTheDocument();
+			expect(screen.queryByText('beta-3')).toBeNull();
+			expect(screen.queryByText('(default)')).toBeNull();
+			expect(screen.getByText('3 / 11')).toBeInTheDocument();
+		});
+
+		it('keeps the "(default)" reset visible when the query matches it', () => {
+			renderMany();
+			const input = screen.getByLabelText('Filter themes') as HTMLInputElement;
+			fireEvent.input(input, { target: { value: 'default' } });
+			expect(screen.getByText('(default)')).toBeInTheDocument();
+			expect(screen.getByText('1 / 11')).toBeInTheDocument();
+		});
+
+		it('shows the empty stub when nothing matches the query', () => {
+			renderMany();
+			const input = screen.getByLabelText('Filter themes') as HTMLInputElement;
+			fireEvent.input(input, { target: { value: 'zzz-no-such-theme' } });
+			expect(screen.getByText('No themes match.')).toBeInTheDocument();
+			expect(screen.getByText('0 / 11')).toBeInTheDocument();
+		});
+	});
 });
diff --git a/client/src/lib/widgets/TokenFields.test.tsx b/client/src/lib/widgets/TokenFields.test.tsx
new file mode 100644
index 0000000..f2f7ddf
--- /dev/null
+++ b/client/src/lib/widgets/TokenFields.test.tsx
@@ -0,0 +1,131 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, fireEvent } from '@testing-library/react';
+import TokenFields from './TokenFields';
+import { TOKEN_FIELDS } from './themeTokens';
+
+const COLOR = TOKEN_FIELDS.find((t) => t.kind === 'color')!;
+const FONT = TOKEN_FIELDS.find((t) => t.kind === 'font')!;
+const TEXT = TOKEN_FIELDS.find((t) => t.kind === 'text')!;
+
+describe('TokenFields', () => {
+	it('renders a field per token: colour fields get a swatch, text/font get a text input', () => {
+		const { getByLabelText, getAllByText, container } = render(
+			<TokenFields values={{}} onSet={vi.fn()} onClear={vi.fn()} />
+		);
+		for (const t of TOKEN_FIELDS) {
+			expect(getAllByText(t.label).length).toBeGreaterThan(0); // the <label> text
+		}
+		// Each colour token renders a ColorField (swatch + text); each font/text token a plain input.
+		const colorCount = TOKEN_FIELDS.filter((t) => t.kind === 'color').length;
+		expect(container.querySelectorAll('.color-field').length).toBe(colorCount);
+		// A colour field exposes a swatch control labelled by the token.
+		expect(getByLabelText(`${COLOR.label} swatch`)).toBeTruthy();
+		// Font/text tokens render a labelled text input that is not a ColorField.
+		expect(getByLabelText(FONT.label).closest('.color-field')).toBeNull();
+		expect(getByLabelText(TEXT.label).closest('.color-field')).toBeNull();
+	});
+
+	it('only the font field references the shared datalist', () => {
+		const { getByLabelText } = render(
+			<TokenFields values={{}} onSet={vi.fn()} onClear={vi.fn()} />
+		);
+		const fontInput = getByLabelText(FONT.label) as HTMLInputElement;
+		const textInput = getByLabelText(TEXT.label) as HTMLInputElement;
+		const listId = fontInput.getAttribute('list');
+		expect(listId).toBeTruthy();
+		expect(textInput.getAttribute('list')).toBeNull();
+		// The datalist with that id exists and is populated with suggestions.
+		const datalist = document.getElementById(listId!) as HTMLDataListElement;
+		expect(datalist?.tagName.toLowerCase()).toBe('datalist');
+		expect(datalist.querySelectorAll('option').length).toBeGreaterThan(0);
+	});
+
+	it('commits a changed text/font value on blur', () => {
+		const onSet = vi.fn();
+		const { getByLabelText } = render(
+			<TokenFields values={{ [TEXT.key]: '2px' }} onSet={onSet} onClear={vi.fn()} />
+		);
+		const input = getByLabelText(TEXT.label) as HTMLInputElement;
+		fireEvent.change(input, { target: { value: '8px' } });
+		fireEvent.blur(input);
+		expect(onSet).toHaveBeenCalledWith(TEXT.key, '8px');
+	});
+
+	it('does not commit when the text/font value is unchanged on blur', () => {
+		const onSet = vi.fn();
+		const { getByLabelText } = render(
+			<TokenFields values={{ [TEXT.key]: '2px' }} onSet={onSet} onClear={vi.fn()} />
+		);
+		const input = getByLabelText(TEXT.label);
+		fireEvent.blur(input); // no edit
+		expect(onSet).not.toHaveBeenCalled();
+	});
+
+	it('editing the colour text field commits via onSet', () => {
+		const onSet = vi.fn();
+		const { container } = render(<TokenFields values={{}} onSet={onSet} onClear={vi.fn()} />);
+		// The colour fields render first; the first .cf-text is the first colour token's text input.
+		const input = container.querySelector('.cf-text') as HTMLInputElement;
+		fireEvent.change(input, { target: { value: '#123456' } });
+		fireEvent.blur(input);
+		expect(onSet).toHaveBeenCalledWith(TOKEN_FIELDS[0].key, '#123456');
+	});
+
+	it('marks a field dirty when its value differs from baseValues', () => {
+		const { container } = render(
+			<TokenFields
+				values={{ [TEXT.key]: '8px' }}
+				baseValues={{ [TEXT.key]: '2px' }}
+				onSet={vi.fn()}
+				onClear={vi.fn()}
+				labelClassName="full"
+			/>
+		);
+		const dirtyLabels = container.querySelectorAll('label.full.dirty');
+		expect(dirtyLabels.length).toBe(1);
+	});
+
+	it('treats a field matching baseValues (and a missing base key) as not dirty', () => {
+		const { container } = render(
+			<TokenFields
+				values={{ [TEXT.key]: '2px' }}
+				baseValues={{ [TEXT.key]: '2px' }}
+				onSet={vi.fn()}
+				onClear={vi.fn()}
+			/>
+		);
+		expect(container.querySelectorAll('label.dirty').length).toBe(0);
+	});
+
+	it('shows a singular clear button for one override and calls onClear', () => {
+		const onClear = vi.fn();
+		const { getByRole } = render(
+			<TokenFields
+				values={{ [COLOR.key]: '#fff' }}
+				onSet={vi.fn()}
+				onClear={onClear}
+				clearTitle="Clear all"
+			/>
+		);
+		const btn = getByRole('button', { name: 'Clear 1 override' });
+		expect(btn.getAttribute('title')).toBe('Clear all');
+		fireEvent.click(btn);
+		expect(onClear).toHaveBeenCalledTimes(1);
+	});
+
+	it('pluralises the clear button for multiple overrides', () => {
+		const { getByRole } = render(
+			<TokenFields
+				values={{ [COLOR.key]: '#fff', [TEXT.key]: '2px' }}
+				onSet={vi.fn()}
+				onClear={vi.fn()}
+			/>
+		);
+		expect(getByRole('button', { name: 'Clear 2 overrides' })).toBeTruthy();
+	});
+
+	it('renders no clear button when there are no overrides', () => {
+		const { queryByRole } = render(<TokenFields values={{}} onSet={vi.fn()} onClear={vi.fn()} />);
+		expect(queryByRole('button', { name: /Clear/ })).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/VolumeHost.test.tsx b/client/src/lib/widgets/VolumeHost.test.tsx
new file mode 100644
index 0000000..6297f46
--- /dev/null
+++ b/client/src/lib/widgets/VolumeHost.test.tsx
@@ -0,0 +1,132 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, cleanup } from '@testing-library/react';
+
+// Mock the outer-ring Tauri audio adapter; the pure readout/icon math (core/volume) stays REAL via
+// the presentational Volume meter. We assert the host's wiring: poll → state, optimistic set + the
+// drag-hold suppression, and the mute toggle.
+const getAudioVolume = vi.fn();
+const setAudioVolume = vi.fn<(level: number) => Promise<void>>(() => Promise.resolve());
+const setAudioMute = vi.fn<(muted: boolean) => Promise<void>>(() => Promise.resolve());
+vi.mock('../audio/volume', () => ({
+	getAudioVolume: () => getAudioVolume(),
+	setAudioVolume: (l: number) => setAudioVolume(l),
+	setAudioMute: (m: boolean) => setAudioMute(m)
+}));
+
+import VolumeHost from './VolumeHost';
+
+beforeEach(() => {
+	vi.useFakeTimers();
+	getAudioVolume.mockResolvedValue({ level: 0.5, muted: false });
+});
+afterEach(() => {
+	cleanup();
+	vi.runOnlyPendingTimers();
+	vi.useRealTimers();
+	vi.clearAllMocks();
+});
+
+function pct(c: HTMLElement): string {
+	return c.querySelector('[data-part="value"]')!.textContent ?? '';
+}
+function slider(c: HTMLElement): HTMLInputElement {
+	return c.querySelector('input.vol-slider')!;
+}
+
+describe('VolumeHost', () => {
+	it('polls the backend on mount and reflects level + mute', async () => {
+		const { container } = render(<VolumeHost />);
+		await act(async () => {
+			await Promise.resolve(); // flush the initial poll()
+		});
+		expect(getAudioVolume).toHaveBeenCalled();
+		expect(pct(container)).toBe('50%');
+		expect(container.querySelector('[data-muted]')).toBeNull();
+	});
+
+	it('keeps polling on the interval', async () => {
+		const { container } = render(<VolumeHost />);
+		await act(async () => {
+			await Promise.resolve();
+		});
+		getAudioVolume.mockResolvedValue({ level: 0.8, muted: false });
+		await act(async () => {
+			vi.advanceTimersByTime(1000);
+			await Promise.resolve();
+		});
+		expect(pct(container)).toBe('80%');
+	});
+
+	it('sets the volume optimistically and suppresses a poll that lands during the drag-hold', async () => {
+		const { container } = render(<VolumeHost />);
+		await act(async () => {
+			await Promise.resolve();
+		});
+		// Advance most of the way to the next poll tick, then drag — so the tick lands inside the
+		// 400ms hold window and the (stale) backend value must NOT yank the thumb back.
+		await act(async () => {
+			vi.advanceTimersByTime(800);
+			await Promise.resolve();
+		});
+		getAudioVolume.mockResolvedValue({ level: 0.5, muted: false }); // stale
+		await act(async () => {
+			fireEvent.change(slider(container), { target: { value: '30' } });
+		});
+		expect(setAudioVolume).toHaveBeenCalledWith(0.3);
+		expect(pct(container)).toBe('30%'); // optimistic
+		// A rapid second drag re-arms the hold timer (clears the pending one — line 42 branch).
+		await act(async () => {
+			fireEvent.change(slider(container), { target: { value: '35' } });
+		});
+		expect(setAudioVolume).toHaveBeenLastCalledWith(0.35);
+		expect(pct(container)).toBe('35%');
+		await act(async () => {
+			vi.advanceTimersByTime(200); // poll tick at t=1000, hold still active
+			await Promise.resolve();
+		});
+		expect(pct(container)).toBe('35%'); // suppressed: still the optimistic value
+
+		// After the hold releases, the next poll is accepted again.
+		getAudioVolume.mockResolvedValue({ level: 0.65, muted: false });
+		await act(async () => {
+			vi.advanceTimersByTime(1000); // release hold (t=1200) then next poll tick (t=2000)
+			await Promise.resolve();
+		});
+		expect(pct(container)).toBe('65%');
+	});
+
+	it('toggles mute and pushes it to the backend', async () => {
+		const { container } = render(<VolumeHost />);
+		await act(async () => {
+			await Promise.resolve();
+		});
+		const muteBtn = container.querySelector('button.vol-mute')!;
+		await act(async () => {
+			fireEvent.click(muteBtn);
+		});
+		expect(setAudioMute).toHaveBeenCalledWith(true);
+		expect(container.querySelector('[data-muted]')).not.toBeNull();
+		await act(async () => {
+			fireEvent.click(muteBtn);
+		});
+		expect(setAudioMute).toHaveBeenLastCalledWith(false);
+	});
+
+	it('ignores a null reading from the backend (stays at —)', async () => {
+		getAudioVolume.mockResolvedValue(null);
+		const { container } = render(<VolumeHost />);
+		await act(async () => {
+			await Promise.resolve();
+		});
+		expect(pct(container)).toBe('—');
+	});
+
+	it('passes the color prop through to the meter accent', async () => {
+		const { container } = render(<VolumeHost color="#0f0" />);
+		await act(async () => {
+			await Promise.resolve();
+		});
+		const root = container.querySelector('.volume') as HTMLElement;
+		expect(root.style.getPropertyValue('--vol-accent')).toBe('#0f0');
+	});
+});
diff --git a/client/src/lib/widgets/WidgetHost.test.tsx b/client/src/lib/widgets/WidgetHost.test.tsx
index 0ac01b4..e46b6b8 100644
--- a/client/src/lib/widgets/WidgetHost.test.tsx
+++ b/client/src/lib/widgets/WidgetHost.test.tsx
@@ -1,15 +1,60 @@
-import { beforeAll, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 import { act, fireEvent, render } from '@testing-library/react';
 import WidgetHost from './WidgetHost';
 import HaSensor from './meters/HaSensor';
 import { registerWidget } from './registry';
 import { createTelemetryHub, type SensorState } from '../core/telemetry';
+import type { MeterProps } from './meterProps';
 import type { WidgetInstance } from '../core/layout';
 
 // A binds:'json' widget type for the test (reuses the HA sensor meter as the renderer —
 // registerWidget is generic over the meter's props, so no cast).
 registerWidget({ type: 'test.json', binds: 'json', label: 'T' }, HaSensor);
 
+// A scalar meter that shows its value + history and exposes a button that bubbles an onControl call.
+// Declared interactive in the meta (not on the instance) so the meta-fallback path is exercised.
+function ScalarProbe({ value, history, onControl }: MeterProps) {
+	return (
+		<div>
+			<span data-testid="scalar">
+				{value === null || value === undefined ? '–' : String(value)}
+			</span>
+			<span data-testid="hist">{(history ?? []).join(',')}</span>
+			<button
+				type="button"
+				onClick={() => onControl?.({ domain: 'light', service: 'toggle', data: { x: 1 } })}
+			>
+				act
+			</button>
+		</div>
+	);
+}
+registerWidget(
+	{ type: 'test.scalar', binds: 'scalar', label: 'S', interactive: true },
+	ScalarProbe
+);
+
+// A text-bound meter (binds:'text') — proves the rawValue path distinct from scalar.
+function TextProbe({ value }: MeterProps) {
+	return <div data-testid="text">{String(value ?? '')}</div>;
+}
+registerWidget({ type: 'test.text', binds: 'text', label: 'TX' }, TextProbe);
+
+// A formula type: an `expr` config field whose key is also the meter prop. WidgetHost strips the raw
+// source from the meter config (so the literal formula never renders before the engine resolves).
+function ExprProbe(props: MeterProps) {
+	return <div data-testid="expr">{props.foo === undefined ? 'stripped' : String(props.foo)}</div>;
+}
+registerWidget(
+	{
+		type: 'test.expr',
+		binds: 'none',
+		label: 'E',
+		configFields: [{ key: 'foo', label: 'Foo', kind: 'expr', result: 'number' }]
+	},
+	ExprProbe
+);
+
 describe('WidgetHost binds-driven value passing', () => {
 	it('forwards the raw JSON SensorValue payload to a binds:json meter', () => {
 		const hub = createTelemetryHub();
@@ -171,3 +216,388 @@ describe('WidgetHost selection vs drag (multi-select group drag)', () => {
 		expect(onSelect).toHaveBeenCalledWith({ id: 'w1' });
 	});
 });
+
+describe('WidgetHost scalar/text/expr value passing', () => {
+	const hub = createTelemetryHub();
+
+	it('passes the scalar value + history and bubbles an onControl with the widget identity', () => {
+		const onControl = vi.fn();
+		const instance: WidgetInstance = {
+			id: 'sc',
+			type: 'test.scalar',
+			sensor: 's',
+			rect: { x: 0, y: 0, w: 80, h: 40 },
+			config: {}
+		};
+		const { getByText, getByTestId } = render(
+			<WidgetHost hub={hub} instance={instance} editMode={false} onControl={onControl} />
+		);
+		act(() => {
+			hub.ingest({ sensor: 's', ts_ms: 0, value: { kind: 'scalar', value: 7 } });
+			hub.ingest({ sensor: 's', ts_ms: 1, value: { kind: 'scalar', value: 9 } });
+		});
+		expect(getByTestId('scalar').textContent).toBe('9');
+		expect(getByTestId('hist').textContent).toBe('7,9');
+		fireEvent.click(getByText('act'));
+		expect(onControl).toHaveBeenCalledWith({
+			id: 'sc',
+			sensor: 's',
+			domain: 'light',
+			service: 'toggle',
+			data: { x: 1 }
+		});
+	});
+
+	it('marks an interactive meta type catchable on the passive overlay', () => {
+		const instance: WidgetInstance = {
+			id: 'sc2',
+			type: 'test.scalar',
+			sensor: 's',
+			rect: { x: 0, y: 0, w: 80, h: 40 },
+			config: {}
+		};
+		const { container } = render(<WidgetHost hub={hub} instance={instance} editMode={false} />);
+		// `interactive` comes from the meta (the instance doesn't set it) → the box catches clicks.
+		expect(container.querySelector('.widget')?.classList.contains('catch')).toBe(true);
+	});
+
+	it('passes the raw value to a binds:text meter', () => {
+		const instance: WidgetInstance = {
+			id: 'tx',
+			type: 'test.text',
+			sensor: 't',
+			rect: { x: 0, y: 0, w: 80, h: 40 },
+			config: {}
+		};
+		const { getByTestId } = render(<WidgetHost hub={hub} instance={instance} editMode={false} />);
+		act(() => {
+			hub.ingest({ sensor: 't', ts_ms: 0, value: { kind: 'text', value: 'hello' } });
+		});
+		expect(getByTestId('text').textContent).toBe('hello');
+	});
+
+	it('strips a formula field’s raw source from the meter config', () => {
+		const instance: WidgetInstance = {
+			id: 'ex',
+			type: 'test.expr',
+			rect: { x: 0, y: 0, w: 80, h: 40 },
+			config: { foo: 'cpu.total / 2' }
+		};
+		const { getByTestId } = render(<WidgetHost hub={hub} instance={instance} editMode={false} />);
+		// The expr key is removed before reaching the meter (the literal formula must never render).
+		expect(getByTestId('expr').textContent).toBe('stripped');
+	});
+
+	it('renders a placeholder for an unregistered widget type', () => {
+		const instance: WidgetInstance = {
+			id: 'missing',
+			type: 'nope.unregistered',
+			rect: { x: 0, y: 0, w: 80, h: 40 },
+			config: {}
+		};
+		const { getByText } = render(<WidgetHost hub={hub} instance={instance} editMode={false} />);
+		expect(getByText('?nope.unregistered')).toBeTruthy();
+	});
+});
+
+describe('WidgetHost presentation flags', () => {
+	const hub = createTelemetryHub();
+	const inst: WidgetInstance = {
+		id: 'w',
+		type: 'test.json',
+		sensor: 'x',
+		rect: { x: 5, y: 6, w: 150, h: 44 },
+		config: {}
+	};
+
+	it('flow mode fills the slot (width/height 100%) and adds the flow class', () => {
+		const { container } = render(<WidgetHost hub={hub} instance={inst} flow editMode={false} />);
+		const box = container.querySelector('.widget') as HTMLElement;
+		expect(box.style.width).toBe('100%');
+		expect(box.style.height).toBe('100%');
+		expect(box.classList.contains('flow')).toBe(true);
+	});
+
+	it('applies the multi / highlighted classes', () => {
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode selected multi highlighted />
+		);
+		const box = container.querySelector('.widget') as HTMLElement;
+		expect(box.classList.contains('multi-member')).toBe(true);
+		expect(box.classList.contains('hl')).toBe(true);
+		expect(box.classList.contains('selected')).toBe(true);
+		expect(box.classList.contains('editable')).toBe(true);
+	});
+
+	it('reports hover enter/leave through onHover (selectId)', () => {
+		const onHover = vi.fn();
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode={false} onHover={onHover} selectId="grp" />
+		);
+		const box = container.querySelector('.widget') as HTMLElement;
+		fireEvent.mouseEnter(box);
+		expect(onHover).toHaveBeenLastCalledWith('grp');
+		fireEvent.mouseLeave(box);
+		expect(onHover).toHaveBeenLastCalledWith(null);
+	});
+});
+
+describe('WidgetHost context menu', () => {
+	const hub = createTelemetryHub();
+	const inst: WidgetInstance = {
+		id: 'w',
+		type: 'test.json',
+		sensor: 'x',
+		rect: { x: 0, y: 0, w: 150, h: 44 },
+		config: {}
+	};
+
+	it('selects + opens the context menu in edit mode', () => {
+		const onSelect = vi.fn();
+		const onContextMenu = vi.fn();
+		const { container } = render(
+			<WidgetHost
+				hub={hub}
+				instance={inst}
+				editMode
+				onSelect={onSelect}
+				onContextMenu={onContextMenu}
+			/>
+		);
+		const box = container.querySelector('.widget') as HTMLElement;
+		fireEvent.contextMenu(box, { clientX: 12, clientY: 34 });
+		expect(onSelect).toHaveBeenCalledWith({ id: 'w' });
+		expect(onContextMenu).toHaveBeenCalledWith({ id: 'w', x: 12, y: 34 });
+	});
+
+	it('swallows the context menu when suppression is armed (consume-once)', () => {
+		const onContextMenu = vi.fn();
+		const suppressContextMenu = vi.fn(() => true);
+		const { container } = render(
+			<WidgetHost
+				hub={hub}
+				instance={inst}
+				editMode
+				onContextMenu={onContextMenu}
+				suppressContextMenu={suppressContextMenu}
+			/>
+		);
+		fireEvent.contextMenu(container.querySelector('.widget') as HTMLElement);
+		expect(suppressContextMenu).toHaveBeenCalled();
+		expect(onContextMenu).not.toHaveBeenCalled();
+	});
+
+	it('ignores the context menu outside edit mode', () => {
+		const onContextMenu = vi.fn();
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode={false} onContextMenu={onContextMenu} />
+		);
+		fireEvent.contextMenu(container.querySelector('.widget') as HTMLElement);
+		expect(onContextMenu).not.toHaveBeenCalled();
+	});
+});
+
+describe('WidgetHost drag interactions', () => {
+	beforeAll(() => {
+		Element.prototype.setPointerCapture = () => undefined;
+	});
+	const hub = createTelemetryHub();
+	const inst: WidgetInstance = {
+		id: 'w',
+		type: 'test.json',
+		sensor: 'x',
+		rect: { x: 0, y: 0, w: 150, h: 44 },
+		config: {}
+	};
+	const overlayOf = (el: HTMLElement) => el.querySelector('.drag-overlay') as HTMLElement;
+
+	it('in-flow widget ghost-drags then drops (reparent/reorder)', () => {
+		const onDragOver = vi.fn();
+		const onDrop = vi.fn();
+		const { container } = render(
+			<WidgetHost
+				hub={hub}
+				instance={inst}
+				editMode
+				movable={false}
+				flow
+				onDragOver={onDragOver}
+				onDrop={onDrop}
+			/>
+		);
+		const overlay = overlayOf(container);
+		fireEvent.pointerDown(overlay, { button: 0, pointerId: 1, clientX: 10, clientY: 10 });
+		expect(container.querySelector('.widget')?.classList.contains('dragging')).toBe(true);
+		fireEvent.pointerMove(overlay, { pointerId: 1, clientX: 40, clientY: 10 }); // past slop
+		expect(onDragOver).toHaveBeenCalledWith({ id: 'w', x: 40, y: 10 });
+		fireEvent.pointerUp(overlay, { pointerId: 1, clientX: 40, clientY: 10 });
+		expect(onDrop).toHaveBeenCalledWith({ id: 'w', x: 40, y: 10 });
+	});
+
+	it('a click (no movement) on a selected in-flow widget re-selects it on pointer-up', () => {
+		const onSelect = vi.fn();
+		const onDrop = vi.fn();
+		const { container } = render(
+			<WidgetHost
+				hub={hub}
+				instance={inst}
+				editMode
+				selected
+				movable={false}
+				flow
+				onSelect={onSelect}
+				onDrop={onDrop}
+			/>
+		);
+		const overlay = overlayOf(container);
+		fireEvent.pointerDown(overlay, { button: 0, pointerId: 1, clientX: 10, clientY: 10 });
+		fireEvent.pointerUp(overlay, { pointerId: 1, clientX: 10, clientY: 10 }); // no movement
+		expect(onDrop).not.toHaveBeenCalled();
+		expect(onSelect).toHaveBeenCalledWith({ id: 'w' });
+	});
+
+	it('does not move below the drag slop (click-to-select only)', () => {
+		const onChange = vi.fn();
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode onChange={onChange} />
+		);
+		const overlay = overlayOf(container);
+		fireEvent.pointerDown(overlay, { button: 0, pointerId: 1, clientX: 10, clientY: 10 });
+		fireEvent.pointerMove(overlay, { pointerId: 1, clientX: 12, clientY: 12 }); // within slop
+		expect(onChange).not.toHaveBeenCalled();
+	});
+
+	it('right-button free-move never docks and arms context-menu suppression', () => {
+		const onChange = vi.fn();
+		const onDragOver = vi.fn();
+		const onCommit = vi.fn();
+		const onSuppressContextMenu = vi.fn();
+		const { container } = render(
+			<WidgetHost
+				hub={hub}
+				instance={inst}
+				editMode
+				onChange={onChange}
+				onDragOver={onDragOver}
+				onCommit={onCommit}
+				onSuppressContextMenu={onSuppressContextMenu}
+			/>
+		);
+		const overlay = overlayOf(container);
+		fireEvent.pointerDown(overlay, { button: 2, pointerId: 1, clientX: 10, clientY: 10 });
+		fireEvent.pointerMove(overlay, { pointerId: 1, clientX: 40, clientY: 40 });
+		// Free-move reports a skipFlow dragOver (Canvas keeps it floating) + a rect change.
+		expect(onDragOver).toHaveBeenCalledWith(expect.objectContaining({ id: 'w', skipFlow: true }));
+		expect(onChange).toHaveBeenCalled();
+		fireEvent.pointerUp(overlay, { pointerId: 1, clientX: 40, clientY: 40 });
+		expect(onCommit).toHaveBeenCalledWith({ skipFlow: true });
+		expect(onSuppressContextMenu).toHaveBeenCalled();
+	});
+
+	it('ignores a middle-button press (reserved for panning) and a right-button on a resize handle', () => {
+		const onSelect = vi.fn();
+		const onChange = vi.fn();
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode onSelect={onSelect} onChange={onChange} />
+		);
+		const overlay = overlayOf(container);
+		fireEvent.pointerDown(overlay, { button: 1, pointerId: 1, clientX: 10, clientY: 10 }); // middle
+		const handle = container.querySelector('.handle.nw') as HTMLElement;
+		fireEvent.pointerDown(handle, { button: 2, pointerId: 2, clientX: 10, clientY: 10 }); // right on handle
+		expect(onSelect).not.toHaveBeenCalled();
+		fireEvent.pointerMove(overlay, { pointerId: 1, clientX: 40, clientY: 40 });
+		expect(onChange).not.toHaveBeenCalled(); // no drag began
+	});
+
+	it('ignores a press when not in edit mode', () => {
+		const onSelect = vi.fn();
+		// editMode false → no overlay rendered; press the box itself does nothing draggable.
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode={false} onSelect={onSelect} />
+		);
+		expect(container.querySelector('.drag-overlay')).toBeNull();
+	});
+
+	it('a pointer move/up with no active drag is a no-op', () => {
+		const onChange = vi.fn();
+		const onCommit = vi.fn();
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode onChange={onChange} onCommit={onCommit} />
+		);
+		const overlay = overlayOf(container);
+		// Move/up without a preceding pointerdown → drag.action is null → both early-return.
+		fireEvent.pointerMove(overlay, { pointerId: 1, clientX: 40, clientY: 40 });
+		fireEvent.pointerUp(overlay, { pointerId: 1, clientX: 40, clientY: 40 });
+		expect(onChange).not.toHaveBeenCalled();
+		expect(onCommit).not.toHaveBeenCalled();
+	});
+
+	it('resize-handle drag reports a resized rect', () => {
+		const onChange = vi.fn();
+		const { container } = render(
+			<WidgetHost hub={hub} instance={inst} editMode onChange={onChange} />
+		);
+		const handle = container.querySelector('.handle.se') as HTMLElement;
+		fireEvent.pointerDown(handle, { button: 0, pointerId: 1, clientX: 0, clientY: 0 });
+		fireEvent.pointerMove(handle, { pointerId: 1, clientX: 40, clientY: 40 });
+		expect(onChange).toHaveBeenCalled();
+		const last = onChange.mock.calls.at(-1)![0] as { rect: { w: number; h: number } };
+		expect(last.rect.w).toBeGreaterThan(150);
+	});
+});
+
+describe('WidgetHost content-fit measurement (ResizeObserver)', () => {
+	let observed: Array<() => void>;
+	afterEach(() => {
+		// @ts-expect-error -- remove the test double
+		delete globalThis.ResizeObserver;
+	});
+
+	it('measures the box at natural size and reports it (deduped)', () => {
+		observed = [];
+		class FakeRO {
+			cb: () => void;
+			constructor(cb: () => void) {
+				this.cb = cb;
+			}
+			observe() {
+				observed.push(this.cb);
+			}
+			disconnect() {
+				// no-op test double
+			}
+		}
+		// @ts-expect-error -- install a test double for the effect's guard
+		globalThis.ResizeObserver = FakeRO;
+
+		const hub = createTelemetryHub();
+		const instance: WidgetInstance = {
+			id: 'cf',
+			type: 'test.json',
+			sensor: 'x',
+			rect: { x: 0, y: 0, w: 150, h: 44 },
+			config: {}
+		};
+		const onMeasure = vi.fn();
+		const { container } = render(
+			<WidgetHost
+				hub={hub}
+				instance={instance}
+				contentSize
+				editMode={false}
+				onMeasure={onMeasure}
+			/>
+		);
+		const box = container.querySelector('.widget') as HTMLElement;
+		// happy-dom reports 0×0 offsets, but the report still fires once on mount.
+		Object.defineProperty(box, 'offsetWidth', { value: 120, configurable: true });
+		Object.defineProperty(box, 'offsetHeight', { value: 30, configurable: true });
+		// The initial report ran with 0×0 at mount; trigger the observer to pick up the sized box.
+		act(() => observed.forEach((cb) => cb()));
+		expect(onMeasure).toHaveBeenCalledWith('cf', { w: 120, h: 30 });
+		// A second identical observation is deduped (no extra report).
+		const calls = onMeasure.mock.calls.length;
+		act(() => observed.forEach((cb) => cb()));
+		expect(onMeasure.mock.calls.length).toBe(calls);
+	});
+});
diff --git a/client/src/lib/widgets/WidgetPreview.test.tsx b/client/src/lib/widgets/WidgetPreview.test.tsx
new file mode 100644
index 0000000..99c51df
--- /dev/null
+++ b/client/src/lib/widgets/WidgetPreview.test.tsx
@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import WidgetPreview from './WidgetPreview';
+import { createWidget } from '../core/widget';
+import { container, leaf } from '../core/layoutTree';
+
+// WidgetPreview is a molecule: it renders palette entries through the REAL FlowNode + WidgetHost
+// against a seeded telemetry hub. We don't mock the render layer (ThemePreview's test renders the
+// same WidgetHost happily in happy-dom) — we assert the host's OWN decisions: the NO_DEMO
+// placeholder branch, type→one-leaf-tree normalisation, the def/template tree path, the
+// scale-to-fit math, and the null (nothing to draw) branch.
+
+const stage = (c: HTMLElement): HTMLElement | null =>
+	c.querySelector('div[style*="transform-origin"]') as HTMLElement | null;
+
+describe('WidgetPreview — NO_DEMO placeholder', () => {
+	it('renders the "shows live data" placeholder for a backend/device-bound type (no meter)', () => {
+		const { getByText, container: c } = render(<WidgetPreview type="spectrum" />);
+		expect(getByText('shows live data')).toBeTruthy();
+		// The real widget render path (a FlowNode data-id slot) must NOT be present.
+		expect(c.querySelector('[data-id]')).toBeNull();
+	});
+
+	it('treats nowplaying / image / iframe / monitorswitch as NO_DEMO too', () => {
+		// Each render is scoped to its own container (the prior renders persist in the shared document).
+		for (const type of ['nowplaying', 'image', 'iframe', 'monitorswitch']) {
+			const { container: c } = render(<WidgetPreview type={type} />);
+			expect(c.textContent).toBe('shows live data');
+			expect(c.querySelector('[data-id]')).toBeNull();
+		}
+	});
+});
+
+describe('WidgetPreview — single widget type', () => {
+	it('normalises a demoable type into a one-leaf tree and renders it via WidgetHost (data-id slot)', () => {
+		const { container: c, queryByText } = render(<WidgetPreview type="clock" />);
+		// type → leaf(createWidget('clock', 'preview-clock')); FlowNode emits its data-id.
+		expect(c.querySelector('[data-id="preview-clock"]')).toBeTruthy();
+		// NOT the placeholder — clock is data-independent and previews fine.
+		expect(queryByText('shows live data')).toBeNull();
+	});
+
+	it('renders a demoable type at scale 1 (box == native size → no transform)', () => {
+		const { container: c } = render(<WidgetPreview type="gauge" w={180} h={100} />);
+		const st = stage(c);
+		expect(st).toBeTruthy();
+		// scale === 1 → transform omitted; the inner stage carries the box size.
+		expect(st!.style.transform).toBe('');
+		expect(st!.style.width).toBe('180px');
+		expect(st!.style.height).toBe('100px');
+	});
+});
+
+describe('WidgetPreview — def / template tree (scale-to-fit)', () => {
+	const tree = () =>
+		container('preview-root', 'col', [leaf(mk('gauge', 'g1'))], { align: 'stretch' });
+	function mk(type: string, id: string) {
+		const inst = createWidget(type, id);
+		inst.rect = { x: 0, y: 0, w: 400, h: 300 };
+		return inst;
+	}
+
+	it('draws a tree at its native size and scales it down to fit the preview box', () => {
+		const { container: c } = render(
+			<WidgetPreview node={tree()} size={{ w: 400, h: 300 }} w={200} h={120} />
+		);
+		const st = stage(c);
+		expect(st).toBeTruthy();
+		// native 400x300 in a 200x120 box → min(200/400, 120/300, 1) = min(0.5, 0.4, 1) = 0.4
+		expect(st!.style.transform).toBe('scale(0.4)');
+		// the inner stage keeps the AUTHORED size; the wrapper clips to the box.
+		expect(st!.style.width).toBe('400px');
+		expect(st!.style.height).toBe('300px');
+	});
+
+	it('never scales a tree UP past 1 even when the box is larger than native', () => {
+		const small = () =>
+			container('preview-root', 'col', [leaf(mk('gauge', 'g2'))], { align: 'stretch' });
+		const { container: c } = render(
+			<WidgetPreview node={small()} size={{ w: 50, h: 40 }} w={300} h={300} />
+		);
+		const st = stage(c);
+		// min(300/50, 300/40, 1) = 1 → no transform.
+		expect(st!.style.transform).toBe('');
+	});
+});
+
+describe('WidgetPreview — nothing to draw', () => {
+	it('renders null when given neither a type nor a node', () => {
+		const { container: c } = render(<WidgetPreview />);
+		expect(c.firstChild).toBeNull();
+	});
+
+	it('renders null when given a node but no size', () => {
+		const node = container('preview-root', 'col', [leaf(createWidget('text', 't1'))]);
+		const { container: c } = render(<WidgetPreview node={node} />);
+		expect(c.firstChild).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/WidgetPreview.tsx b/client/src/lib/widgets/WidgetPreview.tsx
new file mode 100644
index 0000000..779004b
--- /dev/null
+++ b/client/src/lib/widgets/WidgetPreview.tsx
@@ -0,0 +1,134 @@
+// A small live preview of a palette entry, for the Add-palette hover popover (Tier 2). Renders EITHER
+// a single widget TYPE (its createWidget defaults) OR an arbitrary tree (a library def's `child` or a
+// template's `tree()`), through the real FlowNode + WidgetHost against a seeded telemetry hub — so the
+// preview matches how it renders on the canvas, theme tokens and all. A tree is drawn at its native
+// size and scaled to fit the box. Self-sourcing / bespoke widgets that need the backend (now-playing,
+// spectrum, HA…) just render their idle state here, which still previews their chrome.
+import { useMemo } from 'react';
+import { createTelemetryHub, type SensorSample, type TelemetryHub } from '../core/telemetry';
+import { createWidget } from '../core/widget';
+import { leaf, type LayoutNode, type WidgetInstance } from '../core/layoutTree';
+import { TelemetryHubContext } from './telemetryContext';
+import WidgetHost from './WidgetHost';
+import FlowNode, { type RenderLeaf } from './FlowNode';
+
+const clamp = (v: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, v));
+
+// Seed the common sensors so data-bound meters (gauge/sparkline/cpu/text/…) look representative.
+// Mirrors ThemePreview's seed, broadened (gpu/net-up/swap/battery) since the palette previews any type.
+function seedHub(now: number): TelemetryHub {
+	const hub = createTelemetryHub();
+	const series = (sensor: string, gen: (i: number) => number, n = 40): void => {
+		const batch: SensorSample[] = [];
+		for (let i = 0; i < n; i++)
+			batch.push({ sensor, ts_ms: now - (n - i) * 1000, value: { kind: 'scalar', value: gen(i) } });
+		hub.ingestBatch(batch);
+	};
+	series('cpu.total', (i) => clamp(46 + 22 * Math.sin(i * 0.4) + 8 * Math.sin(i * 0.9), 3, 98));
+	series('mem.used', (i) => clamp(55 + 15 * Math.sin(i * 0.3), 20, 90));
+	series('net.down', (i) => 1_400_000 + 1_300_000 * Math.abs(Math.sin(i * 0.5)));
+	series('net.up', (i) => 300_000 + 500_000 * Math.abs(Math.sin(i * 0.6)));
+	series('gpu.util', (i) => clamp(40 + 30 * Math.sin(i * 0.5), 2, 99));
+	// Per-core series so the Cpu widget (which discovers cpu.core.* from the hub) has a grid to draw.
+	for (let c = 0; c < 8; c++)
+		series(`cpu.core.${c}`, (i) => clamp(28 + 45 * Math.abs(Math.sin(i * 0.3 + c)), 2, 99));
+	const points: Record<string, number> = {
+		'mem.used': 61,
+		'swap.used': 12,
+		'gpu.util': 57,
+		'gpu.vram.used': 5_400_000_000,
+		'gpu.vram.total': 8_000_000_000,
+		'battery.percent': 82,
+		'net.up': 480_000,
+		'net.down': 2_600_000
+	};
+	for (const [sensor, value] of Object.entries(points))
+		hub.ingest({ sensor, ts_ms: now, value: { kind: 'scalar', value } });
+	return hub;
+}
+
+// Types whose live render needs a real backend / device / per-instance binding (media, audio FFT, a
+// chosen image or URL, a monitor, a microphone…), so a seeded-hub demo is just blank. Show a small
+// "shows live data" placeholder for these instead of an empty box — the popover still names + describes
+// the widget below the stage.
+const NO_DEMO = new Set([
+	'nowplaying',
+	'spectrum',
+	'assistant',
+	'transcribe',
+	'monitorswitch',
+	'audioswitch',
+	'volume',
+	'image',
+	'iframe'
+]);
+
+type Props = {
+	// One of: a widget type (single meter) OR a tree (def/template) with its native size.
+	type?: string;
+	node?: LayoutNode;
+	size?: { w: number; h: number };
+	w?: number; // preview box
+	h?: number;
+};
+
+export default function WidgetPreview({ type, node, size, w = 200, h = 120 }: Props) {
+	const hub = useMemo(() => seedHub(Date.now()), []);
+	// Normalise to a (tree, native-size) pair: a type becomes a one-leaf tree at the box size (scale 1);
+	// a def/template tree keeps its authored size and is scaled to fit.
+	const { tree, nat } = useMemo<{ tree: LayoutNode | null; nat: { w: number; h: number } }>(() => {
+		if (type) {
+			const inst = createWidget(type, `preview-${type}`);
+			inst.rect = { x: 0, y: 0, w, h };
+			return { tree: leaf(inst), nat: { w, h } };
+		}
+		if (node && size) return { tree: node, nat: size };
+		return { tree: null, nat: { w, h } };
+	}, [type, node, size, w, h]);
+
+	if (type && NO_DEMO.has(type))
+		return (
+			<div
+				style={{
+					width: w,
+					height: h,
+					display: 'flex',
+					alignItems: 'center',
+					justifyContent: 'center',
+					padding: '0 10px',
+					boxSizing: 'border-box',
+					textAlign: 'center',
+					color: 'var(--ui-fg-dim)',
+					fontSize: 'var(--text-sm)',
+					fontStyle: 'italic'
+				}}
+			>
+				shows live data
+			</div>
+		);
+	if (!tree) return null;
+	const scale = Math.min(w / nat.w, h / nat.h, 1);
+	const renderLeaf: RenderLeaf = (lf, id) => (
+		<WidgetHost flow hub={hub} instance={lf.unit as WidgetInstance} domId={id} selectId={id} />
+	);
+
+	return (
+		<div style={{ position: 'relative', width: w, height: h, overflow: 'hidden' }}>
+			<div
+				style={{
+					position: 'absolute',
+					top: 0,
+					left: 0,
+					width: nat.w,
+					height: nat.h,
+					transform: scale !== 1 ? `scale(${scale})` : undefined,
+					transformOrigin: 'top left'
+				}}
+			>
+				<TelemetryHubContext.Provider value={hub}>
+					<FlowNode node={tree} parentKind="col" renderLeaf={renderLeaf} fill />
+				</TelemetryHubContext.Provider>
+			</div>
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/canvas/debugInfo.test.ts b/client/src/lib/widgets/canvas/debugInfo.test.ts
index db73a1d..93bd06a 100644
--- a/client/src/lib/widgets/canvas/debugInfo.test.ts
+++ b/client/src/lib/widgets/canvas/debugInfo.test.ts
@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
-import { buildDebugInfo } from './debugInfo';
-import { container, type MonitorLayout } from '../../core/layoutTree';
+import { buildDebugInfo, type DebugArgs } from './debugInfo';
+import { container, group, leaf, type MonitorLayout } from '../../core/layoutTree';
+import { createWidget } from '../../core/widget';
 import type { Solved } from '../../core/solve';
 
 describe('buildDebugInfo', () => {
@@ -63,4 +64,108 @@ describe('buildDebugInfo', () => {
 		expect(out).toContain('issues: none detected');
 		expect(out).not.toContain('COLLAPSED');
 	});
+
+	// A monitor whose root holds a single placed leaf (widget instance or group). Used to drive the
+	// `isLeaf(sel)` summary branch — the existing tests only ever select a container.
+	function withLeaf(leafNode: ReturnType<typeof leaf>): MonitorLayout {
+		return { root: container('root', 'col', [leafNode], { pad: 8 }), floating: [] };
+	}
+
+	const leafArgs = (mon: MonitorLayout, selectedId: string | null): DebugArgs => ({
+		designing: false,
+		editingDef: null,
+		monitorKey: 'default',
+		workArea: { x: 0, y: 0, w: 200, h: 100 },
+		stageSize: { w: 200, h: 100 },
+		zoom: 1,
+		panX: 0,
+		panY: 0,
+		monitor: mon,
+		solved: new Map([
+			['root', { x: 0, y: 0, w: 200, h: 100 }],
+			['w1', { x: 8, y: 8, w: 184, h: 84 }]
+		]),
+		selectedId,
+		defs: []
+	});
+
+	it('summarises a selected widget-instance leaf by its type and box', () => {
+		const w = createWidget('gauge', 'w1');
+		const out = buildDebugInfo(leafArgs(withLeaf(leaf(w)), 'w1'));
+		expect(out).toContain('selected: w1 (gauge) box {x:8, y:8, w:184, h:84}');
+		expect(out).toContain('mode: layout');
+		expect(out).toContain('floating widgets: 0');
+		expect(out).not.toContain('editing def:');
+		expect(out).not.toContain('library defs:');
+	});
+
+	it('summarises a selected group leaf that references a library def', () => {
+		const g = group('w1', { w: 80, h: 40 }, leaf(createWidget('clock', 'inner')), { def: 'def-x' });
+		const out = buildDebugInfo(leafArgs(withLeaf(leaf(g)), 'w1'));
+		expect(out).toContain('selected: w1 (group:def-x) box');
+	});
+
+	it('summarises an inline group leaf (no def) as group:inline', () => {
+		const g = group('w1', { w: 80, h: 40 }, leaf(createWidget('clock', 'inner')));
+		const out = buildDebugInfo(leafArgs(withLeaf(leaf(g)), 'w1'));
+		expect(out).toContain('selected: w1 (group:inline) box');
+	});
+
+	it('finds a selected leaf in the floating layer (not just the flow tree)', () => {
+		const w = createWidget('text', 'w1');
+		const mon: MonitorLayout = {
+			root: container('root', 'col', [], { pad: 8 }),
+			floating: [leaf(w)]
+		};
+		const out = buildDebugInfo(leafArgs(mon, 'w1'));
+		expect(out).toContain('selected: w1 (text)');
+		expect(out).toContain('floating widgets: 1');
+	});
+
+	it('reports "(none)" when nothing is selected', () => {
+		const out = buildDebugInfo(leafArgs(withLeaf(leaf(createWidget('gauge', 'w1'))), null));
+		expect(out).toContain('selected: (none)');
+	});
+
+	it('reports "(none)" when the selected id matches no node anywhere', () => {
+		// findNode → null AND floating.find → null exercises the final `?? null` fallback.
+		const out = buildDebugInfo(leafArgs(withLeaf(leaf(createWidget('gauge', 'w1'))), 'ghost'));
+		expect(out).toContain('selected: (none)');
+	});
+
+	it('renders an em dash for a selected node with no solved box (container + leaf)', () => {
+		// A container with no `basis`/`pad`/`gap` exercises the padGap fallbacks; an empty `solved`
+		// map exercises the `box ? … : '—'` else-arms for both the container and the leaf branches.
+		const cont: MonitorLayout = { root: container('root', 'col', []), floating: [] };
+		const cOut = buildDebugInfo({
+			...leafArgs(cont, 'root'),
+			solved: new Map() as Solved
+		});
+		expect(cOut).toContain('selected: root (col) box —');
+		expect(cOut).toContain('basis="auto"'); // c.basis ?? 'auto' fallback
+
+		const leafMon = withLeaf(leaf(createWidget('gauge', 'w1')));
+		const lOut = buildDebugInfo({
+			...leafArgs(leafMon, 'w1'),
+			solved: new Map() as Solved
+		});
+		expect(lOut).toContain('selected: w1 (gauge) box —');
+	});
+
+	it('flags an out-of-bounds (but non-collapsed) container', () => {
+		const mon: MonitorLayout = {
+			root: container('root', 'col', [container('cell', 'col', [], { basis: { fr: 1 } })], {
+				pad: 8
+			}),
+			floating: []
+		};
+		const solved: Solved = new Map([
+			['root', { x: 0, y: 0, w: 200, h: 100 }],
+			// extends past the 200×100 work area on the right/bottom — escapes, but has real size
+			['cell', { x: 150, y: 80, w: 100, h: 60 }]
+		]);
+		const out = buildDebugInfo({ ...leafArgs(mon, null), solved });
+		expect(out).toContain('OUT-OF-BOUNDS');
+		expect(out).not.toContain('COLLAPSED');
+	});
 });
diff --git a/client/src/lib/widgets/canvas/editorOps.bulk.test.ts b/client/src/lib/widgets/canvas/editorOps.bulk.test.ts
new file mode 100644
index 0000000..98a7cc6
--- /dev/null
+++ b/client/src/lib/widgets/canvas/editorOps.bulk.test.ts
@@ -0,0 +1,149 @@
+// Behavior tests for the multi-selection / reset editorOps that the by-group files didn't reach:
+// bulkPatchConfig, bulkSetBasis, resetWidget. Each is pure and returns a Patch; we assert the
+// resulting tree (config / basis) and the no-op branches.
+import { describe, expect, it } from 'vitest';
+import {
+	bulkPatchConfig,
+	bulkSetBasis,
+	clearWidgetTokens,
+	patchFloating,
+	patchUnit,
+	resetWidget,
+	setWidgetToken
+} from './editorOps';
+import { createWidget, getMeta } from '../../core/widget';
+import {
+	container,
+	emptyMonitorLayout,
+	leaf,
+	type Leaf,
+	type WidgetInstance
+} from '../../core/layoutTree';
+import type { EditorState } from './types';
+
+const gauge = (id: string): WidgetInstance => createWidget('gauge', id);
+
+// root(col) > [ leaf w1, leaf w2 ]
+function stateWith(selectedId: string | null, selectedIds: string[]): EditorState {
+	return {
+		monitor: {
+			...emptyMonitorLayout(),
+			root: container('root', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))])
+		},
+		library: undefined,
+		selectedId,
+		selectedIds,
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: false,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: false
+	};
+}
+
+const unitAt = (s: { monitor: { root: { children: unknown[] } } }, i: number): WidgetInstance =>
+	((s.monitor.root.children[i] as Leaf).unit as WidgetInstance) ?? ({} as WidgetInstance);
+
+describe('bulkPatchConfig', () => {
+	it('sets a config key on every selected primitive (flow + floating)', () => {
+		const s = stateWith('w1', ['w1', 'w2']);
+		s.monitor.floating = [leaf(gauge('f1'))];
+		s.selectedIds = ['w1', 'w2', 'f1'];
+		const patch = bulkPatchConfig(s, 'unit', '%');
+		expect(unitAt(patch as never, 0).config.unit).toBe('%');
+		expect(unitAt(patch as never, 1).config.unit).toBe('%');
+		expect((patch.monitor!.floating[0].unit as WidgetInstance).config.unit).toBe('%');
+	});
+
+	it('does not mutate the input state', () => {
+		const s = stateWith('w1', ['w1']);
+		const before = unitAt(s as never, 0).config.unit;
+		bulkPatchConfig(s, 'unit', '%');
+		expect(unitAt(s as never, 0).config.unit).toBe(before); // input unchanged
+	});
+
+	it('is a no-op with no selection', () => {
+		expect(bulkPatchConfig(stateWith(null, []), 'x', 1)).toEqual({});
+	});
+});
+
+describe('bulkSetBasis', () => {
+	it('sets the basis on selected flow leaves', () => {
+		const patch = bulkSetBasis(stateWith('w1', ['w1', 'w2']), { fr: 2 });
+		const c0 = patch.monitor!.root.children[0] as Leaf & { basis?: unknown };
+		expect(c0.basis).toEqual({ fr: 2 });
+	});
+
+	it('clears the basis when given undefined', () => {
+		const s = stateWith('w1', ['w1']);
+		(s.monitor.root.children[0] as Leaf & { basis?: unknown }).basis = { fr: 3 };
+		const patch = bulkSetBasis(s, undefined);
+		expect((patch.monitor!.root.children[0] as Leaf & { basis?: unknown }).basis).toBeUndefined();
+	});
+
+	it('is a no-op with no selection', () => {
+		expect(bulkSetBasis(stateWith(null, []), { fr: 1 })).toEqual({});
+	});
+});
+
+describe('resetWidget', () => {
+	it('restores a widget to its type meta defaults', () => {
+		const s = stateWith('w1', []);
+		(s.monitor.root.children[0] as Leaf).unit = { ...gauge('w1'), config: { unit: 'XXX' } };
+		const patch = resetWidget(s, 'w1');
+		expect(unitAt(patch as never, 0).config).toEqual(getMeta('gauge')?.defaultConfig ?? {});
+	});
+
+	it('is a no-op on a missing id or a non-leaf', () => {
+		expect(resetWidget(stateWith(null, []), 'nope')).toEqual({});
+		expect(resetWidget(stateWith(null, []), 'root')).toEqual({});
+	});
+});
+
+describe('setWidgetToken / clearWidgetTokens', () => {
+	it('sets a per-widget token, then clearing the last key drops the tokens object', () => {
+		const set = setWidgetToken(stateWith(null, []), 'w1', '--accent', '#f00');
+		expect(unitAt(set as never, 0).tokens).toEqual({ '--accent': '#f00' });
+
+		const s = stateWith(null, []);
+		(s.monitor.root.children[0] as Leaf).unit = { ...gauge('w1'), tokens: { '--accent': '#f00' } };
+		const cleared = setWidgetToken(s, 'w1', '--accent', '');
+		expect(unitAt(cleared as never, 0).tokens).toBeUndefined();
+	});
+
+	it('clearWidgetTokens drops all overrides; no-op when there are none / id missing', () => {
+		const s = stateWith(null, []);
+		(s.monitor.root.children[0] as Leaf).unit = { ...gauge('w1'), tokens: { a: '1' } };
+		expect(unitAt(clearWidgetTokens(s, 'w1') as never, 0).tokens).toBeUndefined();
+		expect(clearWidgetTokens(stateWith(null, []), 'w1')).toEqual({}); // no tokens
+		expect(clearWidgetTokens(stateWith(null, []), 'missing')).toEqual({});
+	});
+});
+
+describe('patchFloating / patchUnit', () => {
+	it('patchFloating patches a floating leaf', () => {
+		const s = stateWith(null, []);
+		s.monitor.floating = [leaf(gauge('f1'))];
+		const patch = patchFloating(s, 'f1', { sensor: 'cpu.total' });
+		expect((patch.monitor!.floating[0].unit as WidgetInstance).sensor).toBe('cpu.total');
+	});
+
+	it('patchUnit routes to flow leaves and no-ops a non-leaf id', () => {
+		const s = stateWith(null, []);
+		const flow = patchUnit(s, 'w1', { sensor: 'mem.used' });
+		expect(unitAt(flow as never, 0).sensor).toBe('mem.used');
+		const noop = patchUnit(s, 'root', { sensor: 'x' }); // container id → tree unchanged
+		expect(noop.monitor!.root.children).toHaveLength(2);
+	});
+});
diff --git a/client/src/lib/widgets/canvas/editorOps.defs.test.ts b/client/src/lib/widgets/canvas/editorOps.defs.test.ts
new file mode 100644
index 0000000..bbcb39d
--- /dev/null
+++ b/client/src/lib/widgets/canvas/editorOps.defs.test.ts
@@ -0,0 +1,388 @@
+// Behavior tests for the def/library + small-utility editorOps: insertWidget, insertTemplate,
+// defInUse, renameDef, deleteDef, cfgNum, clone, rand. These are PURE ops — each returns a Patch
+// (Partial<EditorState>) the reducer applies via spread; they never mutate the input. We assert on
+// the observable result (the patched tree shape, ids, library defs, the returned boolean/value),
+// never on internals.
+import { describe, expect, it } from 'vitest';
+import {
+	cfgNum,
+	clone,
+	defInUse,
+	deleteDef,
+	insertTemplate,
+	insertWidget,
+	rand,
+	renameDef
+} from './editorOps';
+import {
+	container,
+	group,
+	isContainer,
+	isGroup,
+	isLeaf,
+	leaf,
+	type Container,
+	type Leaf,
+	type Library,
+	type MonitorLayout,
+	type WidgetDef
+} from '../../core/layoutTree';
+import { getTemplate } from '../../core/templates';
+import type { EditorState } from './types';
+
+const CLOCK = 'clock-jp'; // a built-in template id
+
+// A minimal valid EditorState with the few fields these ops read defaulted; `over` overrides.
+function state(over: Partial<EditorState> = {}): EditorState {
+	const monitor: MonitorLayout = { root: container('root', 'col', []), floating: [] };
+	return {
+		monitor,
+		library: undefined,
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: true,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: true,
+		...over
+	};
+}
+
+// A WidgetDef with an inline child (what insertWidget clones an instance from).
+function gaugeDef(id: string, name = 'gauge'): WidgetDef {
+	return {
+		id,
+		name,
+		size: { w: 100, h: 80 },
+		child: container('def-inner', 'col', [], { align: 'stretch' })
+	};
+}
+
+// A floating leaf that is a GROUP instance of `defId` (what defInUse scans for).
+const instanceOf = (defId: string): Leaf =>
+	leaf(group(`grp-${defId}`, { w: 10, h: 10 }, container('inner', 'col', []), { def: defId }));
+
+describe('rand', () => {
+	it('returns a 6-char base-36 suffix', () => {
+		const r = rand();
+		expect(typeof r).toBe('string');
+		expect(r).toHaveLength(6);
+		expect(r).toMatch(/^[0-9a-z]{6}$/);
+	});
+
+	it('is (practically) unique between calls', () => {
+		const ids = new Set(Array.from({ length: 50 }, () => rand()));
+		expect(ids.size).toBe(50);
+	});
+});
+
+describe('clone', () => {
+	it('deep-copies a value so mutating the copy leaves the original intact', () => {
+		const original = { a: 1, nested: { list: [1, 2, 3] } };
+		const copy = clone(original);
+
+		expect(copy).toEqual(original);
+		expect(copy).not.toBe(original); // a fresh top-level object
+		expect(copy.nested).not.toBe(original.nested); // …and fresh nested objects
+
+		copy.nested.list.push(4);
+		copy.a = 99;
+		expect(original.nested.list).toEqual([1, 2, 3]);
+		expect(original.a).toBe(1);
+	});
+
+	it('round-trips a layout container tree by value', () => {
+		const tree = container('c', 'row', [
+			leaf({ id: 'w', type: 'gauge', rect: { x: 0, y: 0, w: 1, h: 1 }, config: {} })
+		]);
+		const copy = clone(tree);
+		expect(copy).toEqual(tree);
+		expect(copy.children[0]).not.toBe(tree.children[0]);
+	});
+});
+
+describe('cfgNum', () => {
+	it('returns the value when the key holds a number', () => {
+		expect(cfgNum({ x: 42 }, 'x')).toBe(42);
+		expect(cfgNum({ x: 0 }, 'x')).toBe(0);
+		expect(cfgNum({ x: -12.5 }, 'x')).toBe(-12.5);
+	});
+
+	it('returns 0 for a missing key, non-number value, or undefined config', () => {
+		expect(cfgNum({ x: 42 }, 'y')).toBe(0); // missing key
+		expect(cfgNum({ x: '42' }, 'x')).toBe(0); // string, not number
+		expect(cfgNum({ x: null }, 'x')).toBe(0); // null
+		expect(cfgNum(undefined, 'x')).toBe(0); // no config at all
+	});
+});
+
+describe('insertWidget', () => {
+	it('docks a group instance of the def into the flow ROOT and selects it', () => {
+		const library: Library = { version: 1, defs: [gaugeDef('def-1')] };
+		const s = state({ library });
+
+		const patch = insertWidget(s, 'def-1');
+
+		// Input untouched (pure op).
+		expect(s.monitor.root.children).toHaveLength(0);
+
+		const next = { ...s, ...patch };
+		expect(next.monitor.root.children).toHaveLength(1);
+		const node = next.monitor.root.children[0];
+		if (!isLeaf(node) || !isGroup(node.unit)) throw new Error('expected a group leaf');
+		expect(node.unit.def).toBe('def-1');
+		expect(node.unit.name).toBe('gauge');
+		expect(node.unit.size).toEqual({ w: 100, h: 80 }); // copied from the def
+		expect(node.id).toMatch(/^grp-/);
+		expect(next.selectedId).toBe(node.id);
+		// The leaf id mirrors its group unit id (leaf() invariant).
+		expect(node.id).toBe(node.unit.id);
+	});
+
+	it('clones the def child (the group child is a copy, not a shared reference)', () => {
+		const def = gaugeDef('def-1');
+		const s = state({ library: { version: 1, defs: [def] } });
+
+		const patch = insertWidget(s, 'def-1');
+		const node = (patch.monitor as MonitorLayout).root.children[0] as Leaf;
+		const grp = node.unit;
+		if (!isGroup(grp)) throw new Error('expected a group');
+		expect(grp.child).toEqual(def.child);
+		expect(grp.child).not.toBe(def.child); // a deep clone
+	});
+
+	it('docks into the SELECTED container when one is selected', () => {
+		const col = container('col1', 'col', [], { align: 'stretch' });
+		const root = container('root', 'col', [col]);
+		const s = state({
+			monitor: { root, floating: [] },
+			library: { version: 1, defs: [gaugeDef('def-1')] },
+			selectedId: 'col1'
+		});
+
+		const next = { ...s, ...insertWidget(s, 'def-1') };
+		const target = next.monitor.root.children[0] as Container;
+		expect(isContainer(target)).toBe(true);
+		expect(target.id).toBe('col1');
+		expect(target.children).toHaveLength(1); // landed inside the selected col, not the root
+		expect(next.monitor.root.children).toHaveLength(1); // root gained nothing else
+	});
+
+	it('is a no-op (empty patch) for an unknown def id', () => {
+		const s = state({ library: { version: 1, defs: [gaugeDef('def-1')] } });
+		expect(insertWidget(s, 'def-nope')).toEqual({});
+	});
+
+	it('is a no-op when there is no library at all', () => {
+		expect(insertWidget(state(), 'def-1')).toEqual({});
+	});
+
+	it('gives repeated inserts fresh, non-colliding ids', () => {
+		const s = state({ library: { version: 1, defs: [gaugeDef('def-1')] } });
+		const a = (insertWidget(s, 'def-1').monitor as MonitorLayout).root.children[0];
+		const b = (insertWidget(s, 'def-1').monitor as MonitorLayout).root.children[0];
+		expect(a.id).not.toBe(b.id);
+	});
+});
+
+describe('insertTemplate', () => {
+	it('drops a built-in template as a self-contained inline group (no library def)', () => {
+		const s = state();
+		const patch = insertTemplate(s, CLOCK);
+
+		// Pure: input tree unchanged.
+		expect(s.monitor.root.children).toHaveLength(0);
+
+		const next = { ...s, ...patch };
+		expect(next.monitor.root.children).toHaveLength(1);
+		const node = next.monitor.root.children[0];
+		if (!isLeaf(node) || !isGroup(node.unit)) throw new Error('expected a group leaf');
+		expect(node.unit.name).toBe('Clock (JP weekday)');
+		expect(node.unit.def).toBeUndefined(); // inline child, NOT a library reference
+		expect(node.unit.child).toBeTruthy();
+		expect(node.unit.size).toEqual(getTemplate(CLOCK)?.size);
+		expect(next.library).toBeUndefined(); // library untouched
+		expect(next.selectedId).toBe(node.id);
+	});
+
+	it('remaps template-local ids to fresh ones (two inserts never collide)', () => {
+		const s = state();
+		const a = (insertTemplate(s, CLOCK).monitor as MonitorLayout).root.children[0] as Leaf;
+		const b = (insertTemplate(s, CLOCK).monitor as MonitorLayout).root.children[0] as Leaf;
+
+		// The group ids differ…
+		expect(a.id).not.toBe(b.id);
+
+		// …and so do every inner node id (no template-local id like 'dt-root' survives).
+		const ids = (node: Leaf): string[] => {
+			const out: string[] = [];
+			const walk = (n: Container | Leaf): void => {
+				out.push(n.id);
+				if (isContainer(n)) n.children.forEach(walk);
+				else if (isGroup(n.unit) && n.unit.child) walk(n.unit.child as Container | Leaf);
+			};
+			walk(node);
+			return out;
+		};
+		const aIds = ids(a);
+		const bIds = ids(b);
+		expect(aIds.some((id) => id === 'dt-root')).toBe(false);
+		expect(aIds.filter((id) => bIds.includes(id))).toEqual([]); // zero overlap
+	});
+
+	it('applies picked options through the ParamSpec path (12-hour time)', () => {
+		const s = state();
+		const next = { ...s, ...insertTemplate(s, CLOCK, { time: 'h:mm A' }) };
+		const node = next.monitor.root.children[0] as Leaf;
+		const grp = node.unit;
+		if (!isGroup(grp)) throw new Error('expected a group');
+
+		const hasFormat = (n: Container | Leaf, fmt: string): boolean => {
+			if (isContainer(n)) return n.children.some((c) => hasFormat(c, fmt));
+			if (isGroup(n.unit))
+				return n.unit.child ? hasFormat(n.unit.child as Container | Leaf, fmt) : false;
+			return n.unit.config?.format === fmt;
+		};
+		expect(hasFormat(grp.child as Container | Leaf, 'h:mm A')).toBe(true);
+	});
+
+	it('docks into the selected container when one is selected', () => {
+		const col = container('col1', 'col', [], { align: 'stretch' });
+		const s = state({
+			monitor: { root: container('root', 'col', [col]), floating: [] },
+			selectedId: 'col1'
+		});
+		const next = { ...s, ...insertTemplate(s, CLOCK) };
+		const target = next.monitor.root.children[0] as Container;
+		expect(target.id).toBe('col1');
+		expect(target.children).toHaveLength(1); // inside the selected col
+	});
+
+	it('is a no-op (empty patch) for an unknown template id', () => {
+		expect(insertTemplate(state(), 'no-such-template')).toEqual({});
+	});
+});
+
+describe('defInUse', () => {
+	it('is true when a group instance of the def sits on the monitor (floating)', () => {
+		const s = state({
+			monitor: { root: container('root', 'col', []), floating: [instanceOf('def-x')] }
+		});
+		expect(defInUse(s, 'def-x')).toBe(true);
+	});
+
+	it('is true when the instance is nested in the flow tree', () => {
+		const inner = container('inner', 'col', [instanceOf('def-x')]);
+		const s = state({ monitor: { root: container('root', 'col', [inner]), floating: [] } });
+		expect(defInUse(s, 'def-x')).toBe(true);
+	});
+
+	it('is false when no instance of that def is placed', () => {
+		const s = state({
+			monitor: { root: container('root', 'col', []), floating: [instanceOf('def-other')] }
+		});
+		expect(defInUse(s, 'def-x')).toBe(false);
+	});
+
+	it('scans the REAL monitor (savedMonitor) while another def is being designed', () => {
+		const savedMonitor: MonitorLayout = {
+			root: container('root', 'col', []),
+			floating: [instanceOf('def-x')]
+		};
+		const scoped: MonitorLayout = { root: container('scoped', 'col', []), floating: [] };
+		const s = state({ editingDefId: 'def-y', savedMonitor, monitor: scoped });
+		expect(defInUse(s, 'def-x')).toBe(true);
+	});
+
+	it('also scans the scoped editing tree (a composite def can embed this one)', () => {
+		const savedMonitor: MonitorLayout = { root: container('root', 'col', []), floating: [] };
+		const scoped: MonitorLayout = {
+			root: container('scoped', 'col', [instanceOf('def-x')]),
+			floating: []
+		};
+		const s = state({ editingDefId: 'def-y', savedMonitor, monitor: scoped });
+		expect(defInUse(s, 'def-x')).toBe(true);
+	});
+});
+
+describe('renameDef', () => {
+	it('renames the matching def, leaving the others (and ids) unchanged', () => {
+		const library: Library = {
+			version: 1,
+			defs: [gaugeDef('def-1', 'Old'), gaugeDef('def-2', 'Keep')]
+		};
+		const s = state({ library });
+
+		const patch = renameDef(s, 'def-1', 'New');
+		expect(s.library?.defs[0].name).toBe('Old'); // input untouched
+
+		const defs = (patch.library as Library).defs;
+		expect(defs[0]).toMatchObject({ id: 'def-1', name: 'New' });
+		expect(defs[1]).toMatchObject({ id: 'def-2', name: 'Keep' });
+	});
+
+	it('preserves the library version and only patches the library', () => {
+		const s = state({ library: { version: 7, defs: [gaugeDef('def-1', 'Old')] } });
+		const patch = renameDef(s, 'def-1', 'New');
+		expect((patch.library as Library).version).toBe(7);
+		expect(Object.keys(patch)).toEqual(['library']);
+	});
+
+	it('is a no-op (empty patch) when there is no library', () => {
+		expect(renameDef(state(), 'def-1', 'New')).toEqual({});
+	});
+
+	it('leaves the defs unchanged when the id matches nothing', () => {
+		const s = state({ library: { version: 1, defs: [gaugeDef('def-1', 'Old')] } });
+		const patch = renameDef(s, 'def-missing', 'New');
+		expect((patch.library as Library).defs).toEqual(s.library?.defs);
+	});
+});
+
+describe('deleteDef', () => {
+	it('removes an unused def from the library', () => {
+		const s = state({
+			monitor: { root: container('root', 'col', []), floating: [] },
+			library: { version: 1, defs: [gaugeDef('def-1'), gaugeDef('def-2')] }
+		});
+
+		const patch = deleteDef(s, 'def-1');
+		expect(s.library?.defs).toHaveLength(2); // input untouched
+
+		const defs = (patch.library as Library).defs;
+		expect(defs).toHaveLength(1);
+		expect(defs[0].id).toBe('def-2');
+	});
+
+	it('refuses to delete a def that is in use (returns empty patch)', () => {
+		const s = state({
+			monitor: { root: container('root', 'col', []), floating: [instanceOf('def-1')] },
+			library: { version: 1, defs: [gaugeDef('def-1')] }
+		});
+		expect(deleteDef(s, 'def-1')).toEqual({});
+	});
+
+	it('refuses to delete the def currently being edited (returns empty patch)', () => {
+		const s = state({
+			library: { version: 1, defs: [gaugeDef('def-1')] },
+			editingDefId: 'def-1'
+		});
+		expect(deleteDef(s, 'def-1')).toEqual({});
+	});
+
+	it('is a no-op (empty patch) when there is no library', () => {
+		expect(deleteDef(state(), 'def-1')).toEqual({});
+	});
+});
diff --git a/client/src/lib/widgets/canvas/editorOps.place.test.ts b/client/src/lib/widgets/canvas/editorOps.place.test.ts
new file mode 100644
index 0000000..319ed41
--- /dev/null
+++ b/client/src/lib/widgets/canvas/editorOps.place.test.ts
@@ -0,0 +1,540 @@
+// Behavior tests for the "place" subset of editorOps: the helpers and tree-edit ops that put
+// widgets/containers INTO the flow tree (or floating layer) and re-home existing nodes. Each op is
+// pure and returns a Patch (Partial<EditorState>); we apply it via spread and assert the resulting
+// tree shape / ids / basis / floating layer — never internals. Covers: lookup, currentContainer,
+// wrapLeafWith, dropWidgetInto, reparentNode, replaceNodeOp, addWidget, addWidgetAt, addContainer,
+// addBeside.
+import { describe, expect, it } from 'vitest';
+import {
+	addBeside,
+	addContainer,
+	addWidget,
+	addWidgetAt,
+	currentContainer,
+	dropWidgetInto,
+	lookup,
+	reparentNode,
+	replaceNodeOp,
+	wrapLeafWith
+} from './editorOps';
+import { createWidget } from '../../core/widget';
+import {
+	container,
+	emptyMonitorLayout,
+	isContainer,
+	isLeaf,
+	leaf,
+	NEW_CONTAINER_GAP,
+	type Container,
+	type Leaf,
+	type LayoutNode
+} from '../../core/layoutTree';
+import type { EditorState } from './types';
+
+// --- fixtures -------------------------------------------------------------------------------
+
+function minimalState(): EditorState {
+	return {
+		monitor: emptyMonitorLayout(),
+		library: undefined,
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: false,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: false
+	};
+}
+
+const gauge = (id: string) => createWidget('gauge', id);
+
+// A small tree:  root(col) > container1(row) > col1(col) > [ leaf w1, leaf w2 ]
+function stateWithLayout(): {
+	state: EditorState;
+	rootId: string;
+	containerId: string;
+	col1Id: string;
+} {
+	const state = minimalState();
+	const col1 = container('col1', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))], {
+		gap: 6,
+		basis: { fr: 1 }
+	});
+	const containerNode = container('container1', 'row', [col1], { gap: 6, align: 'stretch' });
+	const root = container('root', 'col', [containerNode], { align: 'stretch', pad: 16 });
+	state.monitor.root = root;
+	state.selectedId = 'w1';
+	return { state, rootId: root.id, containerId: containerNode.id, col1Id: col1.id };
+}
+
+// =============================================================================================
+// lookup
+// =============================================================================================
+
+describe('lookup', () => {
+	it('finds a node deep in the flow tree by id', () => {
+		const { state } = stateWithLayout();
+		const node = lookup('w2', state.monitor);
+		expect(node).not.toBeNull();
+		expect(node?.id).toBe('w2');
+		expect(node && isLeaf(node)).toBe(true);
+	});
+
+	it('finds a container (including the root)', () => {
+		const { state } = stateWithLayout();
+		const col1 = lookup('col1', state.monitor);
+		expect(col1?.id).toBe('col1');
+		expect(col1 && isContainer(col1)).toBe(true);
+		expect(lookup('root', state.monitor)?.id).toBe('root');
+	});
+
+	it('finds a leaf in the floating layer when it is not in the tree', () => {
+		const state = minimalState();
+		state.monitor.floating = [leaf(gauge('float-1'))];
+		const node = lookup('float-1', state.monitor);
+		expect(node).not.toBeNull();
+		expect(node?.id).toBe('float-1');
+		expect(node && isLeaf(node)).toBe(true);
+	});
+
+	it('returns null for an unknown id', () => {
+		const { state } = stateWithLayout();
+		expect(lookup('nope', state.monitor)).toBeNull();
+	});
+});
+
+// =============================================================================================
+// currentContainer
+// =============================================================================================
+
+describe('currentContainer', () => {
+	it('returns the selected node when it is a container', () => {
+		const { state } = stateWithLayout();
+		state.selectedId = 'col1';
+		const cont = currentContainer(state);
+		expect(cont).not.toBeNull();
+		expect(cont?.id).toBe('col1');
+		expect(cont?.kind).toBe('col');
+	});
+
+	it('returns null when the selected node is a leaf (widget), not a container', () => {
+		const { state } = stateWithLayout();
+		state.selectedId = 'w1';
+		expect(currentContainer(state)).toBeNull();
+	});
+
+	it('returns null when nothing is selected', () => {
+		const { state } = stateWithLayout();
+		state.selectedId = null;
+		expect(currentContainer(state)).toBeNull();
+	});
+
+	it('returns null when the selected id no longer exists', () => {
+		const { state } = stateWithLayout();
+		state.selectedId = 'ghost';
+		expect(currentContainer(state)).toBeNull();
+	});
+});
+
+// =============================================================================================
+// wrapLeafWith
+// =============================================================================================
+
+describe('wrapLeafWith', () => {
+	// The production merge-drop wraps a DISTINCT incoming node into the target's slot: it FIRST prunes
+	// `removeId` from wherever it sits, then wraps `targetId` + the incoming node in a fresh cell.
+	it('prunes the donor node (removeId) from its old slot', () => {
+		const { state, col1Id } = stateWithLayout();
+		const incoming = leaf(gauge('incoming'));
+		// targetId absent → the updateNode pass is a no-op; only the prune of removeId (w2) is observable.
+		const root = wrapLeafWith(state.monitor.root, 'absent-target', 'w2', incoming);
+
+		expect(countOccurrences(root, 'w2')).toBe(0);
+		expect((findNode2(root, col1Id) as Container).children.map((c) => c.id)).toEqual(['w1']);
+	});
+
+	it('wraps a PRESENT target + the incoming node into a fresh cell, without recursing', () => {
+		// Merge-drop shape. Regression: this used to recurse unboundedly (rebuild re-descended into the
+		// fresh wrapper, which still held the same-id target) — see the fix in core/layoutEdit.ts.
+		const { state, col1Id } = stateWithLayout();
+		const incoming = leaf(gauge('incoming'));
+		const root = wrapLeafWith(state.monitor.root, 'w1', 'absent-donor', incoming);
+
+		const col1 = findNode2(root, col1Id) as Container;
+		expect(col1.children).toHaveLength(2);
+		expect(col1.children[1].id).toBe('w2'); // sibling untouched
+		const wrapper = col1.children[0] as Container;
+		expect(isContainer(wrapper)).toBe(true);
+		expect(wrapper.id).toMatch(/^cell-/);
+		expect(wrapper.children.map((c) => c.id)).toEqual(['w1', 'incoming']);
+		expect(countOccurrences(root, 'w1')).toBe(1); // not re-wrapped (recursion fixed)
+	});
+
+	it('leaves the tree shape intact (no new wrapper cell) when the target id is absent', () => {
+		const { state } = stateWithLayout();
+		const incoming = leaf(gauge('incoming'));
+		const root = wrapLeafWith(state.monitor.root, 'absent-target', 'absent-donor', incoming);
+
+		// No prune (donor absent) + no wrap (target absent) ⇒ same shape, no cell-* container appears.
+		expect(allContainerIds(root)).toEqual(['root', 'container1', 'col1']);
+		expect(countOccurrences(root, 'w1')).toBe(1);
+		expect(countOccurrences(root, 'w2')).toBe(1);
+	});
+});
+
+// =============================================================================================
+// dropWidgetInto
+// =============================================================================================
+
+describe('dropWidgetInto', () => {
+	it('appends a fresh widget of the given type into the target container and selects it', () => {
+		const { state, col1Id } = stateWithLayout();
+		const patch = dropWidgetInto(state, col1Id, 'text');
+		const next = { ...state, ...patch };
+
+		const col1 = lookup(col1Id, next.monitor) as Container;
+		expect(col1.children).toHaveLength(3);
+		const added = col1.children[2];
+		expect(isLeaf(added)).toBe(true);
+		expect((added as Leaf).id).toBe(patch.selectedId);
+		expect(patch.selectedId).toMatch(/^text-/);
+		expect(((added as Leaf).unit as { type: string }).type).toBe('text');
+	});
+
+	it('does not mutate the input state', () => {
+		const { state, col1Id } = stateWithLayout();
+		dropWidgetInto(state, col1Id, 'gauge');
+		expect((lookup(col1Id, state.monitor) as Container).children).toHaveLength(2);
+	});
+
+	it('is a no-op on the tree when the target container id is unknown (still selects the new id)', () => {
+		const { state } = stateWithLayout();
+		const before = countLeaves(state.monitor.root);
+		const patch = dropWidgetInto(state, 'nope', 'gauge');
+		const next = { ...state, ...patch };
+		// insertChild on a missing id leaves the tree unchanged, so no leaf was actually added.
+		expect(countLeaves(next.monitor.root)).toBe(before);
+		expect(patch.selectedId).toMatch(/^gauge-/);
+	});
+});
+
+// =============================================================================================
+// reparentNode
+// =============================================================================================
+
+describe('reparentNode', () => {
+	it('moves a flow leaf into another container', () => {
+		const { state, col1Id } = stateWithLayout();
+		// Add a second empty container to move into.
+		const withTarget = {
+			...state,
+			monitor: {
+				...state.monitor,
+				root: container('root', 'col', [
+					state.monitor.root.children[0],
+					container('bay', 'col', [], { align: 'stretch' })
+				])
+			}
+		};
+		const patch = reparentNode(withTarget, 'w2', 'bay');
+		const next = { ...withTarget, ...patch };
+
+		expect((lookup(col1Id, next.monitor) as Container).children.map((c) => c.id)).toEqual(['w1']);
+		expect((lookup('bay', next.monitor) as Container).children.map((c) => c.id)).toEqual(['w2']);
+		expect(patch.selectedId).toBe('w2');
+	});
+
+	it('docks a floating leaf into a flow container (removes it from floating)', () => {
+		const { state, col1Id } = stateWithLayout();
+		state.monitor.floating = [leaf(gauge('fl'))];
+		const patch = reparentNode(state, 'fl', col1Id);
+		const next = { ...state, ...patch };
+
+		expect(next.monitor.floating).toHaveLength(0);
+		expect((lookup(col1Id, next.monitor) as Container).children.map((c) => c.id)).toEqual([
+			'w1',
+			'w2',
+			'fl'
+		]);
+		expect(patch.selectedId).toBe('fl');
+	});
+
+	it('is a no-op when reparenting a node into itself', () => {
+		const { state } = stateWithLayout();
+		expect(reparentNode(state, 'col1', 'col1')).toEqual({});
+	});
+
+	it('is a no-op when the target container is inside the moved subtree (would form a cycle)', () => {
+		const { state } = stateWithLayout();
+		// container1 contains col1 — moving container1 INTO col1 would be a cycle.
+		expect(reparentNode(state, 'container1', 'col1')).toEqual({});
+	});
+});
+
+// =============================================================================================
+// replaceNodeOp
+// =============================================================================================
+
+describe('replaceNodeOp', () => {
+	it('swaps a flow node wholesale and keeps selection on that id', () => {
+		const { state } = stateWithLayout();
+		const replacement = leaf(gauge('w1')); // same id, fresh unit (Inspector coerces the id)
+		const patch = replaceNodeOp(state, 'w1', replacement);
+		const next = { ...state, ...patch };
+
+		const node = lookup('w1', next.monitor) as Leaf;
+		expect(node).not.toBeNull();
+		expect(node).toBe(replacement);
+		expect(patch.selectedId).toBe('w1');
+	});
+
+	it('can replace a leaf with a container of the same id', () => {
+		const { state } = stateWithLayout();
+		const replacement = container('w2', 'row', [], { align: 'stretch' });
+		const next = { ...state, ...replaceNodeOp(state, 'w2', replacement) };
+		const node = lookup('w2', next.monitor);
+		expect(node).not.toBeNull();
+		expect(node && isContainer(node)).toBe(true);
+		expect((node as Container).kind).toBe('row');
+	});
+
+	it('swaps a floating leaf in the floating array, not the tree', () => {
+		const state = minimalState();
+		state.monitor.floating = [leaf(gauge('fl'))];
+		const replacement = leaf(gauge('fl'));
+		const patch = replaceNodeOp(state, 'fl', replacement);
+		const next = { ...state, ...patch };
+
+		expect(next.monitor.floating).toHaveLength(1);
+		expect(next.monitor.floating[0]).toBe(replacement);
+		expect(patch.selectedId).toBe('fl');
+	});
+});
+
+// =============================================================================================
+// addWidget
+// =============================================================================================
+
+describe('addWidget', () => {
+	it('inserts the widget into the selected container when one is selected', () => {
+		const { state, col1Id } = stateWithLayout();
+		state.selectedId = col1Id;
+		const patch = addWidget(state, 'gauge');
+		const next = { ...state, ...patch };
+
+		const col1 = lookup(col1Id, next.monitor) as Container;
+		expect(col1.children).toHaveLength(3);
+		expect(col1.children[2].id).toBe(patch.selectedId);
+		expect(patch.selectedId).toMatch(/^gauge-/);
+		// nothing went to the floating layer
+		expect(next.monitor.floating).toHaveLength(0);
+	});
+
+	it('falls back to the floating layer when no container is selected', () => {
+		const s = minimalState();
+		s.selectedId = null;
+		const patch = addWidget(s, 'gauge');
+		const next = { ...s, ...patch };
+
+		expect(next.monitor.floating).toHaveLength(1);
+		expect(next.monitor.floating[0].id).toBe(patch.selectedId);
+		// the flow tree is untouched
+		expect(next.monitor.root.children).toHaveLength(0);
+	});
+
+	it('floats the widget when a LEAF is selected (a leaf is not a container)', () => {
+		const { state } = stateWithLayout();
+		state.selectedId = 'w1';
+		const next = { ...state, ...addWidget(state, 'gauge') };
+		expect(next.monitor.floating).toHaveLength(1);
+	});
+});
+
+// =============================================================================================
+// addWidgetAt
+// =============================================================================================
+
+describe('addWidgetAt', () => {
+	it('creates a floating widget centered + grid-snapped on the drop point', () => {
+		const s = minimalState();
+		// gauge default size is 110x110. dropPlacement snaps (x - w/2) to the 8px grid.
+		const patch = addWidgetAt(s, 'gauge', 200, 300);
+		const next = { ...s, ...patch };
+
+		expect(next.monitor.floating).toHaveLength(1);
+		const fl = next.monitor.floating[0];
+		expect(isLeaf(fl)).toBe(true);
+		const rect = (fl.unit as { rect: { x: number; y: number } }).rect;
+		// round((200 - 55) / 8) * 8 = round(18.125) * 8 = 144 ; round((300 - 55)/8)*8 = round(30.625)*8 = 248
+		expect(rect.x).toBe(144);
+		expect(rect.y).toBe(248);
+		expect(patch.selectedId).toBe(fl.id);
+	});
+
+	it('does not touch the flow tree', () => {
+		const { state } = stateWithLayout();
+		const before = countLeaves(state.monitor.root);
+		const next = { ...state, ...addWidgetAt(state, 'gauge', 0, 0) };
+		expect(countLeaves(next.monitor.root)).toBe(before);
+		expect(next.monitor.floating).toHaveLength(1);
+	});
+});
+
+// =============================================================================================
+// addContainer
+// =============================================================================================
+
+describe('addContainer', () => {
+	it('appends a new col with the default gap + fr basis into the explicit target', () => {
+		const { state, rootId } = stateWithLayout();
+		const patch = addContainer(state, 'col', rootId);
+		const next = { ...state, ...patch };
+
+		const root = next.monitor.root;
+		expect(root.children).toHaveLength(2);
+		const added = root.children[1] as Container;
+		expect(added.id).toBe(patch.selectedId);
+		expect(added.kind).toBe('col');
+		expect(added.gap).toBe(NEW_CONTAINER_GAP);
+		expect(added.basis).toEqual({ fr: 1 });
+		// the target gets align:'stretch'
+		expect(root.align).toBe('stretch');
+	});
+
+	it('builds a 2x2 grid of col cells when kind is grid', () => {
+		const { state, rootId } = stateWithLayout();
+		const next = { ...state, ...addContainer(state, 'grid', rootId) };
+		const grid = next.monitor.root.children[1] as Container;
+		expect(grid.kind).toBe('grid');
+		expect(grid.cols).toBe(2);
+		expect(grid.rows).toBe(2);
+		expect(grid.children).toHaveLength(4);
+		expect(grid.children.every((c) => isContainer(c) && (c as Container).kind === 'col')).toBe(
+			true
+		);
+	});
+
+	it('targets the selected container when no containerId is given', () => {
+		const { state, col1Id } = stateWithLayout();
+		state.selectedId = col1Id;
+		const next = { ...state, ...addContainer(state, 'row') };
+		const col1 = lookup(col1Id, next.monitor) as Container;
+		// w1, w2, + the new row
+		expect(col1.children).toHaveLength(3);
+		expect((col1.children[2] as Container).kind).toBe('row');
+	});
+
+	it('is a no-op when the target id is not a container', () => {
+		const { state } = stateWithLayout();
+		expect(addContainer(state, 'col', 'w1')).toEqual({});
+	});
+
+	it('pads earlier empty grid cells so the band lands in the clicked cell (index past child count)', () => {
+		const { state } = stateWithLayout();
+		// An empty grid with zero children; ask to insert the new col at index 2.
+		const withGrid = {
+			...state,
+			monitor: {
+				...state.monitor,
+				root: container('root', 'col', [container('g', 'grid', [], { cols: 2, rows: 2 })], {
+					align: 'stretch'
+				})
+			}
+		};
+		const next = { ...withGrid, ...addContainer(withGrid, 'col', 'g', 2) };
+		const grid = lookup('g', next.monitor) as Container;
+		// 2 spacer cells padded in (indices 0,1) + the new col at index 2 = 3 children.
+		expect(grid.children).toHaveLength(3);
+		expect(grid.children[2].id).toBe((next as EditorState).selectedId);
+	});
+});
+
+// =============================================================================================
+// addBeside
+// =============================================================================================
+
+describe('addBeside', () => {
+	it('inserts a sibling of the given kind directly after the target in its parent', () => {
+		const { state, containerId } = stateWithLayout();
+		const patch = addBeside(state, 'col1', 'row');
+		const next = { ...state, ...patch };
+
+		const parent = lookup(containerId, next.monitor) as Container;
+		expect(parent.children.map((c) => c.id)[0]).toBe('col1');
+		const inserted = parent.children[1] as Container;
+		expect(inserted.id).toBe(patch.selectedId);
+		expect(inserted.kind).toBe('row');
+		expect(inserted.gap).toBe(NEW_CONTAINER_GAP);
+		// the parent is stretched so the new band fills the cross axis
+		expect(parent.align).toBe('stretch');
+	});
+
+	it('is a no-op at the root (the root has no siblings)', () => {
+		const { state } = stateWithLayout();
+		expect(addBeside(state, 'root', 'row')).toEqual({});
+	});
+
+	it('is a no-op when the target id is not in the tree', () => {
+		const { state } = stateWithLayout();
+		expect(addBeside(state, 'does-not-exist', 'col')).toEqual({});
+	});
+
+	it('builds a 2x2 grid when kind is grid', () => {
+		const { state } = stateWithLayout();
+		const next = { ...state, ...addBeside(state, 'col1', 'grid') };
+		const parent = lookup('container1', next.monitor) as Container;
+		const grid = parent.children[1] as Container;
+		expect(grid.kind).toBe('grid');
+		expect(grid.cols).toBe(2);
+		expect(grid.children).toHaveLength(4);
+	});
+});
+
+// --- tiny tree helpers (test-local; assert on shape, not editorOps internals) ----------------
+
+function findNode2(root: Container, id: string): LayoutNode | null {
+	if (root.id === id) return root;
+	for (const c of root.children) {
+		if (isContainer(c)) {
+			const hit = findNode2(c, id);
+			if (hit) return hit;
+		} else if (c.id === id) return c;
+	}
+	return null;
+}
+
+function allContainerIds(root: Container): string[] {
+	const out = [root.id];
+	for (const c of root.children) if (isContainer(c)) out.push(...allContainerIds(c));
+	return out;
+}
+
+function countOccurrences(root: Container, id: string): number {
+	let n = root.id === id ? 1 : 0;
+	for (const c of root.children) {
+		if (isContainer(c)) n += countOccurrences(c, id);
+		else if (c.id === id) n += 1;
+	}
+	return n;
+}
+
+function countLeaves(root: Container): number {
+	let n = 0;
+	for (const c of root.children) {
+		if (isContainer(c)) n += countLeaves(c);
+		else n += 1;
+	}
+	return n;
+}
diff --git a/client/src/lib/widgets/canvas/editorOps.rest.test.ts b/client/src/lib/widgets/canvas/editorOps.rest.test.ts
new file mode 100644
index 0000000..0c67f23
--- /dev/null
+++ b/client/src/lib/widgets/canvas/editorOps.rest.test.ts
@@ -0,0 +1,377 @@
+// Behavior tests for the editorOps the by-group suites left uncovered: the grid-CELL split path
+// (splitNode with a cellIndex → splitGridCell / splitBandContainer), the floating-composite
+// ungroup guard, the def-param/group/def-size/def-css ops, the global-token ops (setToken /
+// setTokens / clearTokens), the monitor background op, plus the group/floating-skip branches of
+// clearWidgetTokens and patchFloating. Each op is pure and returns a Patch (Partial<EditorState>);
+// we apply it via spread and assert the resulting tree / library / token map / background — never
+// internals — and cover each op's no-op branch alongside its main path.
+import { describe, expect, it, vi } from 'vitest';
+import {
+	addDefParam,
+	clearTokens,
+	clearWidgetTokens,
+	patchFloating,
+	patchGroup,
+	setBackground,
+	setDefCss,
+	setDefSize,
+	setToken,
+	setTokens,
+	splitNode,
+	ungroupSelected
+} from './editorOps';
+import { createWidget } from '../../core/widget';
+import {
+	container,
+	emptyMonitorLayout,
+	group,
+	isContainer,
+	leaf,
+	type BackgroundSpec,
+	type Container,
+	type Group,
+	type Leaf,
+	type Library,
+	type WidgetDef,
+	type WidgetInstance
+} from '../../core/layoutTree';
+import type { EditorState } from './types';
+
+// --- fixtures (mirrors editorOps.place.test.ts / editorOps.bulk.test.ts) ---------------------
+
+function minimalState(): EditorState {
+	return {
+		monitor: emptyMonitorLayout(),
+		library: undefined,
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: false,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: false
+	};
+}
+
+const gauge = (id: string): WidgetInstance => createWidget('gauge', id);
+
+// A WidgetDef with an inline child (what the def-* ops read/patch).
+function gaugeDef(id: string, name = 'gauge'): WidgetDef {
+	return { id, name, size: { w: 100, h: 80 }, child: container('def-inner', 'col', []) };
+}
+
+const stateWithLib = (defs: WidgetDef[], over: Partial<EditorState> = {}): EditorState => ({
+	...minimalState(),
+	library: { version: 1, defs },
+	...over
+});
+
+// =============================================================================================
+// splitNode — the grid-CELL path (cellIndex + grid → splitGridCell / splitBandContainer)
+// =============================================================================================
+
+describe('splitNode (grid-cell path)', () => {
+	// An empty 2×2 grid placeholder: splitting cell 0 should materialise a band container AT that
+	// cell, NOT re-kind/wrap the whole grid (which the non-cell path would do).
+	function gridState(cellChildren: Container[] = []): EditorState {
+		const s = minimalState();
+		s.monitor.root = container('root', 'col', [
+			container('g', 'grid', cellChildren, { cols: 2, rows: 2, align: 'stretch' })
+		]);
+		return s;
+	}
+
+	it('splits an empty leading cell (index 0) into a rows band WITHOUT padding earlier cells', () => {
+		const s = gridState();
+		const patch = splitNode(s, 'g', 'rows', 0);
+		const grid = patch.monitor!.root.children[0] as Container;
+
+		expect(grid.kind).toBe('grid'); // the grid is preserved, not re-kinded
+		expect(grid.align).toBe('stretch');
+		// exactly one band landed at index 0 (no spacer cells before it)
+		expect(grid.children).toHaveLength(1);
+		const band = grid.children[0] as Container;
+		expect(isContainer(band)).toBe(true);
+		// 'rows' band = a COL parent holding two ROW cells (see splitBandContainer)
+		expect(band.kind).toBe('col');
+		expect(band.children.map((c) => (c as Container).kind)).toEqual(['row', 'row']);
+		expect(patch.selectedId).toBe(band.id);
+	});
+
+	it('pads earlier empty cells with spacers when the clicked cell index is past the child count', () => {
+		const s = gridState();
+		const patch = splitNode(s, 'g', 'cols', 2); // click cell 2 of an empty grid
+		const grid = patch.monitor!.root.children[0] as Container;
+
+		// 2 spacer col cells (indices 0,1) + the new band at index 2 = 3 children.
+		expect(grid.children).toHaveLength(3);
+		expect((grid.children[0] as Container).kind).toBe('col'); // spacer
+		expect((grid.children[1] as Container).kind).toBe('col'); // spacer
+		const band = grid.children[2] as Container;
+		// 'cols' band = a ROW parent holding two COL cells
+		expect(band.kind).toBe('row');
+		expect(band.children.map((c) => (c as Container).kind)).toEqual(['col', 'col']);
+		expect(patch.selectedId).toBe(band.id);
+	});
+
+	it('splits a grid cell into a nested 2×2 grid when dir is grid', () => {
+		const s = gridState();
+		const patch = splitNode(s, 'g', 'grid', 0);
+		const grid = patch.monitor!.root.children[0] as Container;
+
+		expect(grid.children).toHaveLength(1);
+		const band = grid.children[0] as Container;
+		expect(band.kind).toBe('grid'); // a fresh 2×2 grid materialised in the cell
+		expect(band.cols).toBe(2);
+		expect(band.rows).toBe(2);
+		expect(band.children).toHaveLength(4);
+		expect(patch.selectedId).toBe(band.id);
+	});
+
+	it('does not mutate the input state', () => {
+		const s = gridState();
+		splitNode(s, 'g', 'rows', 0);
+		expect((s.monitor.root.children[0] as Container).children).toHaveLength(0);
+	});
+});
+
+// =============================================================================================
+// ungroupSelected — the floating-COMPOSITE guard (a group whose base is not a plain leaf)
+// =============================================================================================
+
+describe('ungroupSelected (floating composite guard)', () => {
+	it('refuses to ungroup a floating group whose child is a CONTAINER (warns, empty patch)', () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		try {
+			// child is a container (composite), not a plain widget leaf → can't unwrap to a single unit.
+			const g = group('grpC', { w: 120, h: 80 }, container('inner', 'col', [leaf(gauge('w1'))]), {
+				config: { x: 10, y: 20 }
+			});
+			const s = minimalState();
+			s.monitor.floating = [leaf(g)];
+
+			expect(ungroupSelected(s, 'grpC')).toEqual({});
+			expect(warn).toHaveBeenCalled();
+			// the floating group is left in place
+			expect(s.monitor.floating).toHaveLength(1);
+		} finally {
+			warn.mockRestore();
+		}
+	});
+});
+
+// =============================================================================================
+// addDefParam
+// =============================================================================================
+
+describe('addDefParam', () => {
+	it('appends a param (with target) to the matching def, leaving others untouched', () => {
+		const s = stateWithLib([gaugeDef('def-1'), gaugeDef('def-2')]);
+		const patch = addDefParam(s, 'def-1', 'core', 'unit.sensor');
+
+		const defs = (patch.library as Library).defs;
+		expect(defs[0].params).toEqual([{ key: 'core', target: 'unit.sensor' }]);
+		expect(defs[1].params).toBeUndefined(); // sibling def untouched
+		// input untouched (pure op)
+		expect(s.library!.defs[0].params).toBeUndefined();
+	});
+
+	it('appends onto an existing params array and stores target undefined when blank', () => {
+		const def = { ...gaugeDef('def-1'), params: [{ key: 'a' }] };
+		const s = stateWithLib([def]);
+		const patch = addDefParam(s, 'def-1', 'b'); // no target arg → target: undefined
+		expect((patch.library as Library).defs[0].params).toEqual([
+			{ key: 'a' },
+			{ key: 'b', target: undefined }
+		]);
+	});
+
+	it('is a no-op with no library or an empty key', () => {
+		expect(addDefParam(minimalState(), 'def-1', 'k')).toEqual({});
+		expect(addDefParam(stateWithLib([gaugeDef('def-1')]), 'def-1', '')).toEqual({});
+	});
+});
+
+// =============================================================================================
+// patchGroup
+// =============================================================================================
+
+describe('patchGroup', () => {
+	it('merges a patch into a FLOW group leaf, leaving non-group leaves alone', () => {
+		const s = minimalState();
+		const g = group('grp1', { w: 120, h: 80 }, leaf(gauge('inner')), { name: 'old' });
+		s.monitor.root = container('root', 'col', [leaf(g), leaf(gauge('plain'))]);
+
+		const patch = patchGroup(s, 'grp1', { name: 'new' });
+		const kids = patch.monitor!.root.children as Leaf[];
+		expect((kids[0].unit as Group).name).toBe('new');
+		expect((kids[0].unit as Group).size).toEqual({ w: 120, h: 80 }); // unspecified fields kept
+		expect((kids[1].unit as WidgetInstance).type).toBe('gauge'); // sibling untouched
+	});
+
+	it('merges a patch into a FLOATING group leaf', () => {
+		const s = minimalState();
+		const g = group('grpF', { w: 50, h: 50 }, leaf(gauge('inner')));
+		s.monitor.floating = [leaf(g)];
+
+		const patch = patchGroup(s, 'grpF', { css: '.x{}' });
+		expect((patch.monitor!.floating[0].unit as Group).css).toBe('.x{}');
+	});
+
+	it('leaves the tree unchanged when the id is a non-group leaf', () => {
+		const s = minimalState();
+		s.monitor.root = container('root', 'col', [leaf(gauge('w1'))]);
+		const patch = patchGroup(s, 'w1', { name: 'nope' });
+		const unit = (patch.monitor!.root.children[0] as Leaf).unit as WidgetInstance;
+		expect(unit.type).toBe('gauge');
+		expect((unit as unknown as Group).name).toBeUndefined();
+	});
+});
+
+// =============================================================================================
+// setDefSize / setDefCss
+// =============================================================================================
+
+describe('setDefSize', () => {
+	it('sets the def size, clamping each dimension to a minimum of 8', () => {
+		const s = stateWithLib([gaugeDef('def-1')]);
+		const patch = setDefSize(s, 'def-1', 200, 3); // h below the floor
+		const defs = (patch.library as Library).defs;
+		expect(defs[0].size).toEqual({ w: 200, h: 8 });
+		expect(s.library!.defs[0].size).toEqual({ w: 100, h: 80 }); // input untouched
+	});
+
+	it('only patches the matching def', () => {
+		const s = stateWithLib([gaugeDef('def-1'), gaugeDef('def-2')]);
+		const defs = (setDefSize(s, 'def-2', 64, 64).library as Library).defs;
+		expect(defs[0].size).toEqual({ w: 100, h: 80 }); // def-1 untouched
+		expect(defs[1].size).toEqual({ w: 64, h: 64 });
+	});
+
+	it('is a no-op when there is no library', () => {
+		expect(setDefSize(minimalState(), 'def-1', 10, 10)).toEqual({});
+	});
+});
+
+describe('setDefCss', () => {
+	it('sets the css on the matching def', () => {
+		const s = stateWithLib([gaugeDef('def-1')]);
+		const defs = (setDefCss(s, 'def-1', '.a{color:red}').library as Library).defs;
+		expect(defs[0].css).toBe('.a{color:red}');
+	});
+
+	it('clears the css to undefined when given an empty string', () => {
+		const def = { ...gaugeDef('def-1'), css: '.old{}' };
+		const s = stateWithLib([def]);
+		const defs = (setDefCss(s, 'def-1', '').library as Library).defs;
+		expect(defs[0].css).toBeUndefined();
+	});
+
+	it('is a no-op when there is no library', () => {
+		expect(setDefCss(minimalState(), 'def-1', '.x{}')).toEqual({});
+	});
+});
+
+// =============================================================================================
+// setToken / setTokens / clearTokens (global theme-token overrides)
+// =============================================================================================
+
+describe('setToken', () => {
+	it('adds a token override when given a value', () => {
+		const patch = setToken(minimalState(), '--accent', '#f00');
+		expect(patch.tokenOverrides).toEqual({ '--accent': '#f00' });
+	});
+
+	it('removes the key when given an empty value', () => {
+		const s = { ...minimalState(), tokenOverrides: { '--accent': '#f00', '--bg': '#000' } };
+		const patch = setToken(s, '--accent', '');
+		expect(patch.tokenOverrides).toEqual({ '--bg': '#000' });
+		expect(s.tokenOverrides).toEqual({ '--accent': '#f00', '--bg': '#000' }); // input untouched
+	});
+});
+
+describe('setTokens', () => {
+	it('merges a map over the existing overrides, clearing keys with empty values', () => {
+		const s = { ...minimalState(), tokenOverrides: { '--a': '1', '--b': '2' } };
+		const patch = setTokens(s, { '--b': '', '--c': '3' }); // clear --b, keep --a, add --c
+		expect(patch.tokenOverrides).toEqual({ '--a': '1', '--c': '3' });
+	});
+
+	it('is a no-op for an empty map (no undo entry)', () => {
+		expect(setTokens(minimalState(), {})).toEqual({});
+	});
+});
+
+describe('clearTokens', () => {
+	it('drops every override when there is something to clear', () => {
+		const s = { ...minimalState(), tokenOverrides: { '--a': '1' } };
+		expect(clearTokens(s)).toEqual({ tokenOverrides: {} });
+	});
+
+	it('is a no-op when there are no overrides', () => {
+		expect(clearTokens(minimalState())).toEqual({});
+	});
+});
+
+// =============================================================================================
+// setBackground (the monitor's full-screen background layer)
+// =============================================================================================
+
+describe('setBackground', () => {
+	it('sets the monitor background spec', () => {
+		const spec: BackgroundSpec = { kind: 'color', src: '#123' };
+		const patch = setBackground(minimalState(), spec);
+		expect(patch.monitor!.background).toEqual(spec);
+	});
+
+	it('clears an existing background when spec is undefined', () => {
+		const s = minimalState();
+		s.monitor.background = { kind: 'color', src: '#000' };
+		const patch = setBackground(s, undefined);
+		expect(patch.monitor!.background).toBeUndefined();
+		expect('background' in patch.monitor!).toBe(false); // the field is deleted, not set undefined
+	});
+
+	it('is a no-op when clearing an already-empty background', () => {
+		expect(setBackground(minimalState(), undefined)).toEqual({});
+	});
+});
+
+// =============================================================================================
+// clearWidgetTokens / patchFloating — the group / floating-skip branches
+// =============================================================================================
+
+describe('clearWidgetTokens (group branch)', () => {
+	it('drops a GROUP leaf token map via the patchGroup route', () => {
+		const s = minimalState();
+		const g = group('grp1', { w: 80, h: 80 }, leaf(gauge('inner')), { tokens: { '--a': '1' } });
+		s.monitor.root = container('root', 'col', [leaf(g)]);
+
+		const patch = clearWidgetTokens(s, 'grp1');
+		expect((patch.monitor!.root.children[0] as Leaf).unit.tokens).toBeUndefined();
+	});
+});
+
+describe('patchFloating (group-skip branch)', () => {
+	it('leaves a floating GROUP leaf untouched (only primitive floats are patched)', () => {
+		const s = minimalState();
+		const g = group('grpF', { w: 50, h: 50 }, leaf(gauge('inner')), { name: 'keep' });
+		s.monitor.floating = [leaf(g)];
+
+		const patch = patchFloating(s, 'grpF', { sensor: 'cpu.total' });
+		const unit = patch.monitor!.floating[0].unit as Group;
+		expect(unit.name).toBe('keep'); // a group leaf is skipped by patchFloating
+		expect((unit as unknown as WidgetInstance).sensor).toBeUndefined();
+	});
+});
diff --git a/client/src/lib/widgets/canvas/editorOps.sizing.test.ts b/client/src/lib/widgets/canvas/editorOps.sizing.test.ts
new file mode 100644
index 0000000..838cd8d
--- /dev/null
+++ b/client/src/lib/widgets/canvas/editorOps.sizing.test.ts
@@ -0,0 +1,565 @@
+// Behavior tests for editorOps sizing / placement / float-dock ops. These ops are PURE — each
+// returns a Patch (Partial<EditorState>) describing the change and NEVER mutates the input state.
+// We assert on the resulting tree shape / floating layer / ids, not on internals. Covers:
+//   patchContainerOp, setNodeBasis, setNodeBases, distributeEvenly, setGridTracks,
+//   setLeafAlign, setLeafBox, floatingLeafFrom, dock, floatNode.
+import { describe, expect, it } from 'vitest';
+import {
+	patchContainerOp,
+	setNodeBasis,
+	setNodeBases,
+	distributeEvenly,
+	setGridTracks,
+	setLeafAlign,
+	setLeafBox,
+	floatingLeafFrom,
+	dock,
+	floatNode,
+	setSolvedForFloat,
+	lookup
+} from './editorOps';
+import { createWidget } from '../../core/widget';
+import {
+	container,
+	leaf,
+	group,
+	isContainer,
+	isGroup,
+	isLeaf,
+	emptyMonitorLayout,
+	emptyRoot,
+	type Container,
+	type Leaf,
+	type MonitorLayout
+} from '../../core/layoutTree';
+import type { Solved } from '../../core/solve';
+import type { EditorState } from './types';
+
+// --- fixtures --------------------------------------------------------------------------------
+
+function minimalState(): EditorState {
+	return {
+		monitor: emptyMonitorLayout(),
+		library: undefined,
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: true,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: true
+	};
+}
+
+function gauge(id: string) {
+	return createWidget('gauge', id);
+}
+
+// A row container ('container1') holding a col ('col1') with two gauge leaves (w1, w2).
+function stateWithLayout(): { state: EditorState; rootId: string; col1Id: string } {
+	const col1 = container('col1', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))], {
+		gap: 6,
+		basis: { fr: 1 }
+	});
+	const containerNode = container('container1', 'row', [col1], { gap: 6, align: 'stretch' });
+	const root = emptyRoot();
+	root.children = [containerNode];
+
+	const state = minimalState();
+	state.monitor.root = root;
+	state.selectedId = 'w1';
+
+	return { state, rootId: root.id, col1Id: col1.id };
+}
+
+// A 2x2 grid 'g' with four 'col' cells, parented under root.
+function stateWithGrid(): { state: EditorState; grid: Container } {
+	const cells = ['c0', 'c1', 'c2', 'c3'].map((id) =>
+		container(id, 'col', [], { align: 'stretch' })
+	);
+	const grid = container('g', 'grid', cells, { cols: 2, rows: 2, gap: 6 });
+	const root = emptyRoot();
+	root.children = [grid];
+	const state = minimalState();
+	state.monitor.root = root;
+	return { state, grid };
+}
+
+const rootOf = (patch: Partial<EditorState>): Container => (patch.monitor as MonitorLayout).root;
+const find = (root: Container, id: string): Container => {
+	const hit = root.children.find((n): n is Container => isContainer(n) && n.id === id);
+	if (!hit) throw new Error(`no container ${id}`);
+	return hit;
+};
+
+// =============================================================================================
+// patchContainerOp
+// =============================================================================================
+
+describe('patchContainerOp', () => {
+	it('merges the patch onto the targeted container', () => {
+		const { state, col1Id } = stateWithLayout();
+		const patch = patchContainerOp(state, col1Id, { gap: 24, justify: 'center' });
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		expect(col1.gap).toBe(24);
+		expect(col1.justify).toBe('center');
+		// untouched fields survive
+		expect(col1.basis).toEqual({ fr: 1 });
+	});
+
+	it('does not mutate the input state', () => {
+		const { state, col1Id } = stateWithLayout();
+		patchContainerOp(state, col1Id, { gap: 99 });
+		const orig = find(find(state.monitor.root, 'container1'), col1Id);
+		expect(orig.gap).toBe(6);
+	});
+
+	it('trims grid children when cols/rows shrink below the cell count', () => {
+		const { state } = stateWithGrid(); // 2x2 = cap 4, has 4 children
+		const patch = patchContainerOp(state, 'g', { cols: 1, rows: 2 }); // cap 2
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.cols).toBe(1);
+		expect(grid.rows).toBe(2);
+		expect(grid.children).toHaveLength(2); // dropped from the END (row-major)
+		expect(grid.children.map((c) => c.id)).toEqual(['c0', 'c1']);
+	});
+
+	it('keeps all grid children when the new capacity still holds them', () => {
+		const { state } = stateWithGrid();
+		const patch = patchContainerOp(state, 'g', { cols: 3, rows: 2 }); // cap 6 >= 4
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.children).toHaveLength(4);
+	});
+
+	it('does not trim a non-grid container even when given cols', () => {
+		const { state, col1Id } = stateWithLayout(); // col1 has 2 leaves
+		const patch = patchContainerOp(state, col1Id, { cols: 1 });
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		expect(col1.children).toHaveLength(2);
+	});
+});
+
+// =============================================================================================
+// setNodeBasis
+// =============================================================================================
+
+describe('setNodeBasis', () => {
+	it('sets a fr basis on a flow leaf', () => {
+		const { state } = stateWithLayout();
+		const patch = setNodeBasis(state, 'w1', { fr: 2 });
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect(w1.basis).toEqual({ fr: 2 });
+	});
+
+	it('sets a fixed px basis on a container', () => {
+		const { state, col1Id } = stateWithLayout();
+		const patch = setNodeBasis(state, col1Id, 200);
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		expect(col1.basis).toBe(200);
+	});
+
+	it('clears the basis when given undefined (back to auto)', () => {
+		const { state, col1Id } = stateWithLayout(); // col1 starts with basis fr:1
+		const patch = setNodeBasis(state, col1Id, undefined);
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		expect('basis' in col1).toBe(false);
+	});
+
+	it('is a no-op (unchanged tree) for an unknown id', () => {
+		const { state } = stateWithLayout();
+		const patch = setNodeBasis(state, 'nope', { fr: 5 });
+		// nothing changed: w1/w2 keep their (absent) basis
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect('basis' in w1).toBe(false);
+	});
+});
+
+// =============================================================================================
+// setNodeBases
+// =============================================================================================
+
+describe('setNodeBases', () => {
+	it('sets multiple node bases in one pass', () => {
+		const { state } = stateWithLayout();
+		const patch = setNodeBases(state, [
+			{ id: 'w1', basis: { fr: 3 } },
+			{ id: 'w2', basis: 50 }
+		]);
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		const w2 = col1.children.find((n) => n.id === 'w2') as Leaf;
+		expect(w1.basis).toEqual({ fr: 3 });
+		expect(w2.basis).toBe(50);
+	});
+
+	it('skips unknown ids and applies the known ones', () => {
+		const { state } = stateWithLayout();
+		const patch = setNodeBases(state, [
+			{ id: 'ghost', basis: { fr: 9 } },
+			{ id: 'w2', basis: { fr: 2 } }
+		]);
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w2 = col1.children.find((n) => n.id === 'w2') as Leaf;
+		expect(w2.basis).toEqual({ fr: 2 });
+	});
+
+	it('returns the same monitor root reference behavior with an empty entry list', () => {
+		const { state } = stateWithLayout();
+		const patch = setNodeBases(state, []);
+		// no entries → root passes through unchanged in shape
+		expect(rootOf(patch).children).toHaveLength(1);
+	});
+});
+
+// =============================================================================================
+// distributeEvenly
+// =============================================================================================
+
+describe('distributeEvenly', () => {
+	it('sets every child of a row/col to fr:1', () => {
+		// col1 children start with no basis; set one to a fixed px first, then distribute.
+		const { state, col1Id } = stateWithLayout();
+		const pre = setNodeBasis(state, 'w1', 300);
+		const s2 = { ...state, ...pre };
+		const patch = distributeEvenly(s2, col1Id);
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		for (const c of col1.children) {
+			expect((c as Leaf).basis).toEqual({ fr: 1 });
+		}
+	});
+
+	it('clears colFr/rowFr weights on a grid (reset to uniform)', () => {
+		const { state } = stateWithGrid();
+		// seed track weights, then distribute should drop them
+		const seeded = setGridTracks(state, 'g', 'col', [{ index: 0, fr: 3 }]);
+		const s2 = { ...state, ...seeded };
+		const seededGrid = find(s2.monitor.root, 'g');
+		expect(seededGrid.colFr).toBeDefined();
+
+		const patch = distributeEvenly(s2, 'g');
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.colFr).toBeUndefined();
+		expect(grid.rowFr).toBeUndefined();
+	});
+
+	it('is a no-op for an empty container', () => {
+		const empty = container('empty', 'col', []);
+		const state = minimalState();
+		state.monitor.root = container('root', 'col', [empty], { align: 'stretch' });
+		expect(distributeEvenly(state, 'empty')).toEqual({});
+	});
+
+	it('is a no-op for an unknown id', () => {
+		const { state } = stateWithLayout();
+		expect(distributeEvenly(state, 'missing')).toEqual({});
+	});
+
+	it('is a no-op when the id is a leaf, not a container', () => {
+		const { state } = stateWithLayout();
+		expect(distributeEvenly(state, 'w1')).toEqual({});
+	});
+});
+
+// =============================================================================================
+// setGridTracks
+// =============================================================================================
+
+describe('setGridTracks', () => {
+	it('writes col weights, defaulting absent tracks to 1', () => {
+		const { state } = stateWithGrid(); // cols:2
+		const patch = setGridTracks(state, 'g', 'col', [{ index: 1, fr: 2.5 }]);
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.colFr).toEqual([1, 2.5]); // index 0 defaults to 1
+	});
+
+	it('writes row weights to rowFr', () => {
+		const { state } = stateWithGrid(); // rows:2
+		const patch = setGridTracks(state, 'g', 'row', [{ index: 0, fr: 4 }]);
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.rowFr).toEqual([4, 1]);
+	});
+
+	it('rounds fr to 3 decimal places', () => {
+		const { state } = stateWithGrid();
+		const patch = setGridTracks(state, 'g', 'col', [{ index: 0, fr: 1.23456 }]);
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.colFr?.[0]).toBe(1.235);
+	});
+
+	it('grows the array to cover an index beyond the col hint', () => {
+		const { state } = stateWithGrid(); // cols:2
+		const patch = setGridTracks(state, 'g', 'col', [{ index: 3, fr: 5 }]);
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.colFr).toHaveLength(4); // grown to maxIdx+1
+		expect(grid.colFr).toEqual([1, 1, 1, 5]);
+	});
+
+	it('preserves existing positive weights for tracks not in the entries', () => {
+		const { state } = stateWithGrid();
+		const seeded = setGridTracks(state, 'g', 'col', [{ index: 0, fr: 3 }]);
+		const s2 = { ...state, ...seeded };
+		const patch = setGridTracks(s2, 'g', 'col', [{ index: 1, fr: 2 }]);
+		const grid = find(rootOf(patch), 'g');
+		expect(grid.colFr).toEqual([3, 2]); // index 0's prior weight kept
+	});
+
+	it('is a no-op when the id is not a grid', () => {
+		const { state, col1Id } = stateWithLayout(); // col1 is a 'col', not a grid
+		expect(setGridTracks(state, col1Id, 'col', [{ index: 0, fr: 2 }])).toEqual({});
+	});
+
+	it('is a no-op for an unknown id', () => {
+		const { state } = stateWithGrid();
+		expect(setGridTracks(state, 'nope', 'col', [{ index: 0, fr: 2 }])).toEqual({});
+	});
+});
+
+// =============================================================================================
+// setLeafAlign
+// =============================================================================================
+
+describe('setLeafAlign', () => {
+	it('sets halign/valign on a leaf', () => {
+		const { state } = stateWithLayout();
+		const patch = setLeafAlign(state, 'w1', 'right', 'bottom');
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect(w1.halign).toBe('right');
+		expect(w1.valign).toBe('bottom');
+	});
+
+	it("clears halign/valign when set to 'fill' (the default)", () => {
+		const { state } = stateWithLayout();
+		// first pin both, then reset both to fill
+		const pinned = setLeafAlign(state, 'w1', 'center', 'middle');
+		const s2 = { ...state, ...pinned };
+		const patch = setLeafAlign(s2, 'w1', 'fill', 'fill');
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect('halign' in w1).toBe(false);
+		expect('valign' in w1).toBe(false);
+	});
+
+	it('is a no-op on a container (only leaves carry halign/valign)', () => {
+		const { state, col1Id } = stateWithLayout();
+		const patch = setLeafAlign(state, col1Id, 'left', 'top');
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		expect('halign' in col1).toBe(false);
+		expect('valign' in col1).toBe(false);
+	});
+
+	it('can set just one axis while leaving the other at fill', () => {
+		const { state } = stateWithLayout();
+		const patch = setLeafAlign(state, 'w2', 'fill', 'top');
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w2 = col1.children.find((n) => n.id === 'w2') as Leaf;
+		expect('halign' in w2).toBe(false);
+		expect(w2.valign).toBe('top');
+	});
+});
+
+// =============================================================================================
+// setLeafBox
+// =============================================================================================
+
+describe('setLeafBox', () => {
+	it('sets a uniform margin on a leaf', () => {
+		const { state } = stateWithLayout();
+		const patch = setLeafBox(state, 'w1', 'margin', 8);
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect(w1.margin).toBe(8);
+	});
+
+	it('sets per-side padding on a leaf', () => {
+		const { state } = stateWithLayout();
+		const pad = { t: 1, r: 2, b: 3, l: 4 };
+		const patch = setLeafBox(state, 'w2', 'pad', pad);
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w2 = col1.children.find((n) => n.id === 'w2') as Leaf;
+		expect(w2.pad).toEqual(pad);
+	});
+
+	it('clears the field when value is undefined', () => {
+		const { state } = stateWithLayout();
+		const set = setLeafBox(state, 'w1', 'margin', 12);
+		const s2 = { ...state, ...set };
+		const patch = setLeafBox(s2, 'w1', 'margin', undefined);
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect('margin' in w1).toBe(false);
+	});
+
+	it('is a no-op on a container', () => {
+		const { state, col1Id } = stateWithLayout();
+		const patch = setLeafBox(state, col1Id, 'pad', 10);
+		const col1 = find(find(rootOf(patch), 'container1'), col1Id);
+		// the container's own pad is untouched (it had none)
+		expect('pad' in col1).toBe(false);
+	});
+
+	it('leaves margin untouched when setting pad and vice versa', () => {
+		const { state } = stateWithLayout();
+		const withMargin = setLeafBox(state, 'w1', 'margin', 5);
+		const s2 = { ...state, ...withMargin };
+		const patch = setLeafBox(s2, 'w1', 'pad', 7);
+		const col1 = find(find(rootOf(patch), 'container1'), 'col1');
+		const w1 = col1.children.find((n) => n.id === 'w1') as Leaf;
+		expect(w1.margin).toBe(5);
+		expect(w1.pad).toBe(7);
+	});
+});
+
+// =============================================================================================
+// floatingLeafFrom
+// =============================================================================================
+
+describe('floatingLeafFrom', () => {
+	it('positions a primitive leaf at (x,y), preserving its size by default', () => {
+		const src = gauge('w1');
+		const node = leaf(src);
+		const fl = floatingLeafFrom(node, 100, 200);
+		expect(fl.id).toBe('w1');
+		expect(isLeaf(fl)).toBe(true);
+		expect(isGroup(fl.unit)).toBe(false);
+		const u = fl.unit as ReturnType<typeof gauge>;
+		expect(u.rect.x).toBe(100);
+		expect(u.rect.y).toBe(200);
+		// size carried over from the source rect (no rect arg given)
+		expect(u.rect.w).toBe(src.rect.w);
+		expect(u.rect.h).toBe(src.rect.h);
+	});
+
+	it('overrides w/h from the provided rect', () => {
+		const node = leaf(gauge('w1'));
+		const fl = floatingLeafFrom(node, 10, 20, { x: 0, y: 0, w: 333, h: 222 });
+		const u = fl.unit as ReturnType<typeof gauge>;
+		expect(u.rect).toEqual({ x: 10, y: 20, w: 333, h: 222 });
+	});
+
+	it('anchors a group leaf via config.x/config.y (not a rect)', () => {
+		const g = group('grp-1', { w: 40, h: 40 }, leaf(gauge('inner')), { name: 'g' });
+		const node = leaf(g);
+		const fl = floatingLeafFrom(node, 70, 90);
+		expect(isGroup(fl.unit)).toBe(true);
+		const out = fl.unit as typeof g;
+		expect(out.config?.x).toBe(70);
+		expect(out.config?.y).toBe(90);
+	});
+});
+
+// =============================================================================================
+// dock (floating -> flow tree)
+// =============================================================================================
+
+describe('dock', () => {
+	it('moves a floating leaf into the flow root and selects it', () => {
+		const state = minimalState();
+		const fl = floatingLeafFrom(leaf(gauge('f1')), 50, 60);
+		state.monitor.floating = [fl];
+
+		const patch = dock(state, 'f1');
+		const mon = patch.monitor as MonitorLayout;
+		expect(mon.floating).toHaveLength(0);
+		expect(mon.root.children.map((c) => c.id)).toContain('f1');
+		expect(patch.selectedId).toBe('f1');
+	});
+
+	it('is a no-op for an id not in the floating layer', () => {
+		const { state } = stateWithLayout(); // w1 is in the flow tree, not floating
+		expect(dock(state, 'w1')).toEqual({});
+	});
+
+	it('only removes the docked leaf, leaving other floaters in place', () => {
+		const state = minimalState();
+		state.monitor.floating = [
+			floatingLeafFrom(leaf(gauge('f1')), 0, 0),
+			floatingLeafFrom(leaf(gauge('f2')), 10, 10)
+		];
+		const patch = dock(state, 'f1');
+		const mon = patch.monitor as MonitorLayout;
+		expect(mon.floating.map((l) => l.id)).toEqual(['f2']);
+	});
+});
+
+// =============================================================================================
+// floatNode (flow tree -> floating)
+// =============================================================================================
+
+describe('floatNode', () => {
+	it('moves a flow leaf to the floating layer using the solved rect', () => {
+		setSolvedForFloat(new Map([['w1', { x: 12, y: 34, w: 100, h: 50 }]]) as Solved);
+		const { state } = stateWithLayout();
+
+		const patch = floatNode(state, 'w1');
+		const mon = patch.monitor as MonitorLayout;
+		// removed from the flow tree
+		const col1 = find(find(mon.root, 'container1'), 'col1');
+		expect(col1.children.map((c) => c.id)).toEqual(['w2']);
+		// added to floating at the solved position/size
+		expect(mon.floating).toHaveLength(1);
+		const fl = mon.floating[0];
+		expect(fl.id).toBe('w1');
+		const u = fl.unit as ReturnType<typeof gauge>;
+		expect(u.rect).toEqual({ x: 12, y: 34, w: 100, h: 50 });
+		expect(patch.selectedId).toBe('w1');
+	});
+
+	it('honors an explicit `at` point over the solved rect position', () => {
+		setSolvedForFloat(new Map([['w1', { x: 12, y: 34, w: 100, h: 50 }]]) as Solved);
+		const { state } = stateWithLayout();
+		const patch = floatNode(state, 'w1', { x: 500, y: 600 });
+		const mon = patch.monitor as MonitorLayout;
+		const u = mon.floating[0].unit as ReturnType<typeof gauge>;
+		expect(u.rect.x).toBe(500);
+		expect(u.rect.y).toBe(600);
+		// size still from the solved rect
+		expect(u.rect.w).toBe(100);
+		expect(u.rect.h).toBe(50);
+	});
+
+	it('defaults to (0,0) when there is no solved rect and no `at`', () => {
+		setSolvedForFloat(new Map() as Solved);
+		const { state } = stateWithLayout();
+		const patch = floatNode(state, 'w1');
+		const mon = patch.monitor as MonitorLayout;
+		const u = mon.floating[0].unit as ReturnType<typeof gauge>;
+		expect(u.rect.x).toBe(0);
+		expect(u.rect.y).toBe(0);
+	});
+
+	it('is a no-op for an unknown id', () => {
+		setSolvedForFloat(new Map() as Solved);
+		const { state } = stateWithLayout();
+		expect(floatNode(state, 'ghost')).toEqual({});
+	});
+
+	it('is a no-op for a container id (only leaves float)', () => {
+		setSolvedForFloat(new Map() as Solved);
+		const { state, col1Id } = stateWithLayout();
+		expect(floatNode(state, col1Id)).toEqual({});
+	});
+
+	it('the floated leaf is findable via lookup in the resulting monitor', () => {
+		setSolvedForFloat(new Map([['w2', { x: 1, y: 2, w: 3, h: 4 }]]) as Solved);
+		const { state } = stateWithLayout();
+		const patch = floatNode(state, 'w2');
+		const mon = patch.monitor as MonitorLayout;
+		const found = lookup('w2', mon);
+		expect(found).not.toBeNull();
+		expect(isLeaf(found as Leaf)).toBe(true);
+	});
+});
diff --git a/client/src/lib/widgets/canvas/editorOps.structure.test.ts b/client/src/lib/widgets/canvas/editorOps.structure.test.ts
new file mode 100644
index 0000000..b151c1d
--- /dev/null
+++ b/client/src/lib/widgets/canvas/editorOps.structure.test.ts
@@ -0,0 +1,342 @@
+// Behavior tests for the structural editorOps: split / remove / reorder / indent / outdent /
+// ungroup / makeWidget. Each op is PURE and returns a Patch (Partial<EditorState>) that we apply
+// via spread — we assert on the resulting tree shape, ids, basis, the floating layer, and library
+// defs, never on op internals. Covers the no-op / clamp / empty-selection branches too.
+import { describe, expect, it } from 'vitest';
+import {
+	indent,
+	makeWidget,
+	outdent,
+	removeById,
+	reorder,
+	splitNode,
+	ungroupSelected
+} from './editorOps';
+import { createWidget } from '../../core/widget';
+import {
+	container,
+	group,
+	isContainer,
+	isGroup,
+	isLeaf,
+	leaf,
+	type Container
+} from '../../core/layoutTree';
+import type { EditorState } from './types';
+
+// --- fixtures -------------------------------------------------------------------------------
+
+function minimalState(root: Container): EditorState {
+	return {
+		monitor: { root, floating: [] },
+		library: undefined,
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: true,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: true
+	};
+}
+
+const gauge = (id: string) => createWidget('gauge', id);
+
+// Find a container child by id (throws so a wrong-tree assertion fails loudly).
+function childContainer(c: Container, id: string): Container {
+	const hit = c.children.find((n): n is Container => isContainer(n) && n.id === id);
+	if (!hit) throw new Error(`no container child ${id}`);
+	return hit;
+}
+
+describe('splitNode', () => {
+	it('empty col → "rows" becomes a col holding two empty row bands', () => {
+		const s = minimalState(container('root', 'col', []));
+		const patch = splitNode(s, 'root', 'rows');
+		const root = patch.monitor!.root;
+		expect(root.kind).toBe('col'); // the stacker keeps the col kind
+		const bands = root.children.filter(isContainer);
+		expect(bands.map((b) => b.kind)).toEqual(['row', 'row']);
+		// no existing content → the FIRST band is selected
+		expect(patch.selectedId).toBe(root.children[0].id);
+	});
+
+	it('"cols" turns a col into a row of two col strips', () => {
+		const s = minimalState(container('root', 'col', []));
+		const root = splitNode(s, 'root', 'cols').monitor!.root;
+		expect(root.kind).toBe('row');
+		expect(root.children.filter(isContainer).map((b) => b.kind)).toEqual(['col', 'col']);
+	});
+
+	it('a populated node keeps its content in band 0 and adds ONE new band, selecting the new band', () => {
+		const populated = container('root', 'col', [leaf(gauge('w1'))]);
+		const s = minimalState(populated);
+		const patch = splitNode(s, 'root', 'rows');
+		const root = patch.monitor!.root;
+		expect(root.children).toHaveLength(2);
+		// band 0 wraps the existing content (a re-wrapped cell that still carries the widget)…
+		const keep = root.children[0] as Container;
+		expect(isContainer(keep)).toBe(true);
+		expect(keep.children[0].id).toBe('w1');
+		// …band 1 is a fresh empty band, and IT is the selection
+		const fresh = root.children[1] as Container;
+		expect(fresh.children).toHaveLength(0);
+		expect(patch.selectedId).toBe(fresh.id);
+	});
+
+	it('"grid" produces a 2×2 grid (4 cells)', () => {
+		const s = minimalState(container('root', 'col', []));
+		const root = splitNode(s, 'root', 'grid').monitor!.root;
+		expect(root.kind).toBe('grid');
+		expect(root.cols).toBe(2);
+		expect(root.rows).toBe(2);
+		expect(root.children).toHaveLength(4);
+	});
+
+	it('is a no-op ({}) when the id is missing or is a leaf', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1'))]));
+		expect(splitNode(s, 'nope', 'rows')).toEqual({});
+		expect(splitNode(s, 'w1', 'rows')).toEqual({}); // a widget leaf is not a container
+	});
+});
+
+describe('removeById', () => {
+	it('removes a flow leaf from the tree', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))]));
+		const patch = removeById(s, 'w1');
+		const root = patch.monitor!.root;
+		expect(root.children.map((c) => c.id)).toEqual(['w2']);
+	});
+
+	it('removes a leaf from the floating layer (tree untouched)', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1'))]));
+		s.monitor.floating = [leaf(gauge('f1')), leaf(gauge('f2'))];
+		const patch = removeById(s, 'f1');
+		expect(patch.monitor!.floating.map((l) => l.id)).toEqual(['f2']);
+		expect(patch.monitor!.root.children.map((c) => c.id)).toEqual(['w1']);
+	});
+
+	it('removing the PRIMARY selection clears both selectedId and the marquee set', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))]));
+		s.selectedId = 'w1';
+		s.selectedIds = ['w1', 'w2'];
+		const patch = removeById(s, 'w1');
+		expect(patch.selectedId).toBeNull();
+		expect(patch.selectedIds).toEqual([]);
+	});
+
+	it('removing a NON-primary marquee member just filters it (primary kept)', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))]));
+		s.selectedId = 'w1';
+		s.selectedIds = ['w1', 'w2'];
+		const patch = removeById(s, 'w2');
+		expect(patch.selectedIds).toEqual(['w1']);
+		expect(patch.selectedId).toBeUndefined(); // primary not touched in the patch
+	});
+
+	it('does not touch selection when the removed id was not selected', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1')), leaf(gauge('w2'))]));
+		s.selectedId = 'w1';
+		s.selectedIds = ['w1'];
+		const patch = removeById(s, 'w2');
+		expect(patch.selectedId).toBeUndefined();
+		expect(patch.selectedIds).toBeUndefined();
+		expect(patch.monitor!.root.children.map((c) => c.id)).toEqual(['w1']);
+	});
+});
+
+describe('reorder', () => {
+	const threeKids = () =>
+		minimalState(container('root', 'col', [leaf(gauge('a')), leaf(gauge('b')), leaf(gauge('c'))]));
+
+	it('moves a child forward by a positive delta', () => {
+		const patch = reorder(threeKids(), 'a', 1);
+		expect(patch.monitor!.root.children.map((c) => c.id)).toEqual(['b', 'a', 'c']);
+	});
+
+	it('moves a child backward by a negative delta', () => {
+		const patch = reorder(threeKids(), 'c', -1);
+		expect(patch.monitor!.root.children.map((c) => c.id)).toEqual(['a', 'c', 'b']);
+	});
+
+	it('clamps to a no-op past the start', () => {
+		expect(reorder(threeKids(), 'a', -1)).toEqual({});
+	});
+
+	it('clamps to a no-op past the end', () => {
+		expect(reorder(threeKids(), 'c', 1)).toEqual({});
+	});
+
+	it('is a no-op for a node with no parent (the root)', () => {
+		expect(reorder(threeKids(), 'root', 1)).toEqual({});
+	});
+});
+
+describe('indent', () => {
+	it('nests a node into its previous sibling container', () => {
+		// [colA(empty), w] → indenting w moves it into colA
+		const s = minimalState(
+			container('root', 'col', [container('colA', 'col', []), leaf(gauge('w'))])
+		);
+		const patch = indent(s, 'w');
+		const root = patch.monitor!.root;
+		expect(root.children.map((c) => c.id)).toEqual(['colA']); // w left the root level
+		const colA = childContainer(root, 'colA');
+		expect(colA.children.map((c) => c.id)).toEqual(['w']); // …and landed inside colA
+	});
+
+	it('is a no-op when the previous sibling is a leaf (not a container)', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('a')), leaf(gauge('b'))]));
+		expect(indent(s, 'b')).toEqual({});
+	});
+
+	it('is a no-op when there is no previous sibling (first child)', () => {
+		const s = minimalState(
+			container('root', 'col', [leaf(gauge('a')), container('colB', 'col', [])])
+		);
+		expect(indent(s, 'a')).toEqual({});
+	});
+});
+
+describe('outdent', () => {
+	it('lifts a node out to its grandparent, right after its old parent', () => {
+		// root > colA > [w] ; outdent w → root > [colA, w]
+		const s = minimalState(
+			container('root', 'col', [container('colA', 'col', [leaf(gauge('w'))])])
+		);
+		const patch = outdent(s, 'w');
+		const root = patch.monitor!.root;
+		expect(root.children.map((c) => c.id)).toEqual(['colA', 'w']);
+		expect(childContainer(root, 'colA').children).toHaveLength(0);
+	});
+
+	it('inserts the node directly after its parent among the grandparent siblings', () => {
+		// root > [colA > [w], colB] ; outdent w → root > [colA, w, colB]
+		const s = minimalState(
+			container('root', 'col', [
+				container('colA', 'col', [leaf(gauge('w'))]),
+				container('colB', 'col', [])
+			])
+		);
+		const root = outdent(s, 'w').monitor!.root;
+		expect(root.children.map((c) => c.id)).toEqual(['colA', 'w', 'colB']);
+	});
+
+	it('is a no-op when the node sits directly under the root (parent IS root)', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w'))]));
+		expect(outdent(s, 'w')).toEqual({});
+	});
+});
+
+describe('ungroupSelected', () => {
+	it('replaces a flow group leaf with its inline child', () => {
+		const inner = leaf(gauge('inner'));
+		const g = group('grp1', { w: 120, h: 80 }, inner);
+		const s = minimalState(container('root', 'col', [leaf(g)]));
+		const patch = ungroupSelected(s, 'grp1');
+		const root = patch.monitor!.root;
+		// the group leaf is gone; its concrete child took its place
+		expect(root.children).toHaveLength(1);
+		const replaced = root.children[0];
+		expect(isLeaf(replaced)).toBe(true);
+		expect(replaced.id).toBe('inner');
+		expect(isGroup((replaced as ReturnType<typeof leaf>).unit)).toBe(false);
+		expect(patch.selectedId).toBeNull();
+	});
+
+	it('ungroups a FLOATING group: unwraps the child unit and carries the group anchor onto its rect', () => {
+		const inner = leaf(gauge('inner'));
+		const g = group('grpF', { w: 120, h: 80 }, inner, { config: { x: 30, y: 40 } });
+		const s = minimalState(container('root', 'col', []));
+		s.monitor.floating = [leaf(g)];
+		const patch = ungroupSelected(s, 'grpF');
+		const fl = patch.monitor!.floating;
+		expect(fl).toHaveLength(1);
+		const u = fl[0].unit;
+		expect(isGroup(u)).toBe(false);
+		// the unwrapped primitive inherits the group's floating anchor as its rect origin
+		expect((u as ReturnType<typeof gauge>).rect.x).toBe(30);
+		expect((u as ReturnType<typeof gauge>).rect.y).toBe(40);
+		expect(patch.selectedId).toBe(u.id);
+	});
+
+	it('is a no-op on a non-group floating leaf', () => {
+		const s = minimalState(container('root', 'col', []));
+		s.monitor.floating = [leaf(gauge('plain'))];
+		expect(ungroupSelected(s, 'plain')).toEqual({});
+	});
+
+	it('is a no-op ({}) on a missing id', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1'))]));
+		// a plain flow leaf isn't a group → ungroupNode returns the (unchanged) root, selection nulled
+		const patch = ungroupSelected(s, 'nope');
+		expect(patch.monitor!.root.children.map((c) => c.id)).toEqual(['w1']);
+		expect(patch.selectedId).toBeNull();
+	});
+});
+
+describe('makeWidget', () => {
+	it('promotes a flow leaf into a group backed by a new library def', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1'))]));
+		const patch = makeWidget(s, 'w1');
+		// library gained exactly one def, named after the widget type
+		expect(patch.library).toBeDefined();
+		expect(patch.library!.defs).toHaveLength(1);
+		const def = patch.library!.defs[0];
+		expect(def.name).toBe('gauge');
+		expect(def.id).toMatch(/^def-/);
+		// the leaf at w1's slot is now a group leaf referencing that def
+		const node = patch.monitor!.root.children[0];
+		expect(isLeaf(node)).toBe(true);
+		const unit = (node as ReturnType<typeof leaf>).unit;
+		expect(isGroup(unit)).toBe(true);
+		if (!isGroup(unit)) throw new Error('expected a group unit');
+		expect(unit.def).toBe(def.id);
+		// the new group is selected
+		expect(patch.selectedId).toBe(unit.id);
+		expect(patch.selectedId).toMatch(/^grp-/);
+	});
+
+	it('appends to an existing library rather than replacing it', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1'))]));
+		s.library = {
+			version: 1,
+			defs: [{ id: 'def-keep', name: 'existing', size: { w: 10, h: 10 }, child: leaf(gauge('x')) }]
+		};
+		const patch = makeWidget(s, 'w1');
+		expect(patch.library!.defs.map((d) => d.id)).toContain('def-keep');
+		expect(patch.library!.defs).toHaveLength(2);
+	});
+
+	it('promotes a FLOATING primitive into a floating group preserving its x/y anchor', () => {
+		const inst = gauge('f1');
+		inst.rect = { ...inst.rect, x: 55, y: 66 };
+		const s = minimalState(container('root', 'col', []));
+		s.monitor.floating = [leaf(inst)];
+		const patch = makeWidget(s, 'f1');
+		const fl = patch.monitor!.floating;
+		expect(fl).toHaveLength(1);
+		const unit = fl[0].unit;
+		expect(isGroup(unit)).toBe(true);
+		if (!isGroup(unit)) throw new Error('expected a group unit');
+		// the group keeps the floating anchor in its config
+		expect(unit.config).toEqual({ x: 55, y: 66 });
+		expect(patch.selectedId).toBe(unit.id);
+	});
+
+	it('is a no-op ({}) on a missing id', () => {
+		const s = minimalState(container('root', 'col', [leaf(gauge('w1'))]));
+		expect(makeWidget(s, 'nope')).toEqual({});
+	});
+});
diff --git a/client/src/lib/widgets/canvas/overlayPrefs.test.ts b/client/src/lib/widgets/canvas/overlayPrefs.test.ts
index f0d636b..580f35e 100644
--- a/client/src/lib/widgets/canvas/overlayPrefs.test.ts
+++ b/client/src/lib/widgets/canvas/overlayPrefs.test.ts
@@ -1,5 +1,11 @@
 import { describe, it, expect, beforeEach } from 'vitest';
-import { OVERLAY_PREF_DEFAULTS, readOverlayPrefs, writeOverlayPrefs } from './overlayPrefs';
+import { act, renderHook } from '@testing-library/react';
+import {
+	OVERLAY_PREF_DEFAULTS,
+	readOverlayPrefs,
+	useOverlayPrefs,
+	writeOverlayPrefs
+} from './overlayPrefs';
 
 describe('overlayPrefs', () => {
 	beforeEach(() => localStorage.clear());
@@ -44,3 +50,64 @@ describe('overlayPrefs', () => {
 		});
 	});
 });
+
+describe('useOverlayPrefs', () => {
+	beforeEach(() => localStorage.clear());
+
+	it('seeds from storage and patches persist + re-render', () => {
+		const { result } = renderHook(() => useOverlayPrefs());
+		expect(result.current[0]).toEqual(OVERLAY_PREF_DEFAULTS);
+
+		act(() => result.current[1]({ overlayLayer: 'top' }));
+		expect(result.current[0].overlayLayer).toBe('top');
+		// Other keys untouched and the patch was written to storage.
+		expect(result.current[0].respectWorkArea).toBe(true);
+		expect(readOverlayPrefs().overlayLayer).toBe('top');
+	});
+
+	it('a patch merges over the latest persisted value, not stale state', () => {
+		const { result } = renderHook(() => useOverlayPrefs());
+		// Another window writes directly to storage between renders.
+		writeOverlayPrefs({ respectWorkArea: false, overlayLayer: 'wallpaper', debugWindowed: true });
+		act(() => result.current[1]({ debugWindowed: false }));
+		expect(result.current[0]).toEqual({
+			respectWorkArea: false,
+			overlayLayer: 'wallpaper',
+			debugWindowed: false
+		});
+	});
+
+	it('reacts to a storage event for the prefs key from another window', () => {
+		const { result } = renderHook(() => useOverlayPrefs());
+		writeOverlayPrefs({ respectWorkArea: false, overlayLayer: 'top', debugWindowed: true });
+		act(() => {
+			window.dispatchEvent(new StorageEvent('storage', { key: 'widgetsack.overlay.prefs' }));
+		});
+		expect(result.current[0]).toEqual({
+			respectWorkArea: false,
+			overlayLayer: 'top',
+			debugWindowed: true
+		});
+	});
+
+	it('ignores storage events for other keys', () => {
+		const { result } = renderHook(() => useOverlayPrefs());
+		writeOverlayPrefs({ respectWorkArea: false, overlayLayer: 'top', debugWindowed: true });
+		act(() => {
+			window.dispatchEvent(new StorageEvent('storage', { key: 'some.other.key' }));
+		});
+		// Unchanged — the hook didn't re-read for an unrelated key.
+		expect(result.current[0]).toEqual(OVERLAY_PREF_DEFAULTS);
+	});
+
+	it('detaches the storage listener on unmount', () => {
+		const { result, unmount } = renderHook(() => useOverlayPrefs());
+		unmount();
+		writeOverlayPrefs({ respectWorkArea: false, overlayLayer: 'top', debugWindowed: true });
+		act(() => {
+			window.dispatchEvent(new StorageEvent('storage', { key: 'widgetsack.overlay.prefs' }));
+		});
+		// No throw / no update after unmount; the captured snapshot is still the default.
+		expect(result.current[0]).toEqual(OVERLAY_PREF_DEFAULTS);
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useAutoTheme.test.ts b/client/src/lib/widgets/canvas/useAutoTheme.test.ts
new file mode 100644
index 0000000..5361e58
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useAutoTheme.test.ts
@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import type { BackgroundSpec } from '../../core/layoutTree';
+import type { Tokens } from '../../core/tokens';
+
+// Mock the DOM/canvas pixel sampler (outer ring; happy-dom can't draw). The colour math
+// (core/palette deriveTokens) stays REAL so the hook's sample→derive→apply→status flow is exercised.
+const sampleImagePixels = vi.fn();
+vi.mock('./wallpaperSampler', () => ({
+	sampleImagePixels: (url: string) => sampleImagePixels(url)
+}));
+
+import { useAutoTheme } from './useAutoTheme';
+
+afterEach(() => vi.clearAllMocks());
+
+const imageBg: BackgroundSpec = { kind: 'image', src: 'wall.png' };
+const resolveWallpaper = (n: string) => `asset://localhost/${n}`;
+
+describe('useAutoTheme', () => {
+	it('canAuto is false without an image wallpaper, and run() is a no-op', async () => {
+		const applyTokens = vi.fn();
+		const { result } = renderHook(() =>
+			useAutoTheme({ bg: { kind: 'color', src: '#000' }, resolveWallpaper, applyTokens })
+		);
+		expect(result.current.canAuto).toBe(false);
+		await act(async () => {
+			await result.current.run();
+		});
+		expect(sampleImagePixels).not.toHaveBeenCalled();
+		expect(applyTokens).not.toHaveBeenCalled();
+		expect(result.current.busy).toBe(false);
+	});
+
+	it('canAuto is false for an image with no src', () => {
+		const { result } = renderHook(() =>
+			useAutoTheme({ bg: { kind: 'image', src: '' }, resolveWallpaper, applyTokens: vi.fn() })
+		);
+		expect(result.current.canAuto).toBe(false);
+	});
+
+	it('canAuto is true and run() samples → derives → applies, ending in done', async () => {
+		// A solid mid-grey image derives a non-empty Tokens map.
+		sampleImagePixels.mockResolvedValue(Array.from({ length: 50 }, () => [120, 130, 140]));
+		const applyTokens = vi.fn();
+		const { result } = renderHook(() =>
+			useAutoTheme({ bg: imageBg, resolveWallpaper, applyTokens })
+		);
+		expect(result.current.canAuto).toBe(true);
+
+		await act(async () => {
+			await result.current.run();
+		});
+		expect(sampleImagePixels).toHaveBeenCalledWith('asset://localhost/wall.png');
+		expect(applyTokens).toHaveBeenCalledOnce();
+		expect(Object.keys(applyTokens.mock.calls[0]![0] as Tokens).length).toBeGreaterThan(0);
+		expect(result.current.status).toBe('done');
+		expect(result.current.busy).toBe(false);
+	});
+
+	it('run() reports fail (and does not apply) when no pixels could be sampled', async () => {
+		sampleImagePixels.mockResolvedValue([]); // tainted/failed decode → empty Tokens
+		const applyTokens = vi.fn();
+		const { result } = renderHook(() =>
+			useAutoTheme({ bg: imageBg, resolveWallpaper, applyTokens })
+		);
+		await act(async () => {
+			await result.current.run();
+		});
+		expect(applyTokens).not.toHaveBeenCalled();
+		expect(result.current.status).toBe('fail');
+		expect(result.current.busy).toBe(false);
+	});
+
+	it('clears busy even when sampling throws (finally)', async () => {
+		sampleImagePixels.mockRejectedValue(new Error('decode error'));
+		const { result } = renderHook(() =>
+			useAutoTheme({ bg: imageBg, resolveWallpaper, applyTokens: vi.fn() })
+		);
+		await act(async () => {
+			await expect(result.current.run()).rejects.toThrow('decode error');
+		});
+		expect(result.current.busy).toBe(false);
+	});
+
+	it('resetStatus returns the status to idle', async () => {
+		sampleImagePixels.mockResolvedValue([]);
+		const { result } = renderHook(() =>
+			useAutoTheme({ bg: imageBg, resolveWallpaper, applyTokens: vi.fn() })
+		);
+		await act(async () => {
+			await result.current.run();
+		});
+		expect(result.current.status).toBe('fail');
+		act(() => result.current.resetStatus());
+		expect(result.current.status).toBe('idle');
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useBackground.test.ts b/client/src/lib/widgets/canvas/useBackground.test.ts
new file mode 100644
index 0000000..51ef3aa
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useBackground.test.ts
@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import type { MonitorLayout } from '../../core/layoutTree';
+import type { LayoutOp } from '../ops';
+
+// Mock the outer-ring Tauri file/asset bridge (overlay). The pure isMediaKind helper (core/background)
+// stays REAL, so we verify the side-band state: async name→asset-URL resolution (cached), the
+// section's file listing, and the patch/kind/clear op dispatch.
+const listWallpapers = vi.fn();
+const wallpaperAssetUrl = vi.fn();
+vi.mock('../../overlay', () => ({
+	listWallpapers: () => listWallpapers(),
+	wallpaperAssetUrl: (n: string) => wallpaperAssetUrl(n)
+}));
+
+import { useBackground } from './useBackground';
+
+const monitor = (over: Partial<MonitorLayout> = {}): MonitorLayout =>
+	({ root: {}, floating: [], ...over } as MonitorLayout);
+
+beforeEach(() => {
+	listWallpapers.mockResolvedValue(['a.png', 'b.mp4']);
+	wallpaperAssetUrl.mockResolvedValue('asset://localhost/wall.png');
+});
+afterEach(() => vi.clearAllMocks());
+
+describe('useBackground', () => {
+	it('exposes the monitor background spec', () => {
+		const m = monitor({ background: { kind: 'color', src: '#123' } });
+		const { result } = renderHook(() =>
+			useBackground({ studio: true, navSection: 'layouts', monitor: m, handleOp: vi.fn() })
+		);
+		expect(result.current.bg).toEqual({ kind: 'color', src: '#123' });
+	});
+
+	it('resolves an image/video src to an asset URL and caches it by name', async () => {
+		const m = monitor({ background: { kind: 'image', src: 'wall.png' } });
+		const { result } = renderHook(() =>
+			useBackground({ studio: true, navSection: 'layouts', monitor: m, handleOp: vi.fn() })
+		);
+		expect(result.current.resolveWallpaper('wall.png')).toBe(''); // not resolved yet
+		await waitFor(() =>
+			expect(result.current.resolveWallpaper('wall.png')).toBe('asset://localhost/wall.png')
+		);
+		expect(wallpaperAssetUrl).toHaveBeenCalledTimes(1); // resolved once, then cached
+	});
+
+	it('does not resolve a color/web background (src used verbatim)', () => {
+		const m = monitor({ background: { kind: 'web', src: 'https://x.test' } });
+		renderHook(() =>
+			useBackground({ studio: true, navSection: 'layouts', monitor: m, handleOp: vi.fn() })
+		);
+		expect(wallpaperAssetUrl).not.toHaveBeenCalled();
+	});
+
+	it('lists the wallpapers/ folder only when the Background section is open in the studio', async () => {
+		const { result, rerender } = renderHook(
+			(props: { studio: boolean; section: string }) =>
+				useBackground({
+					studio: props.studio,
+					navSection: props.section as never,
+					monitor: monitor(),
+					handleOp: vi.fn()
+				}),
+			{ initialProps: { studio: true, section: 'widgets' } }
+		);
+		expect(listWallpapers).not.toHaveBeenCalled(); // wrong section
+		rerender({ studio: true, section: 'background' });
+		await waitFor(() => expect(result.current.wallpaperFiles).toEqual(['a.png', 'b.mp4']));
+
+		// refreshWallpapers re-reads the folder on demand.
+		listWallpapers.mockResolvedValue(['only.png']);
+		await act(async () => {
+			result.current.refreshWallpapers();
+		});
+		await waitFor(() => expect(result.current.wallpaperFiles).toEqual(['only.png']));
+	});
+
+	it('does not list wallpapers on the overlay (studio=false)', () => {
+		renderHook(() =>
+			useBackground({
+				studio: false,
+				navSection: 'background',
+				monitor: monitor(),
+				handleOp: vi.fn()
+			})
+		);
+		expect(listWallpapers).not.toHaveBeenCalled();
+	});
+
+	it('patchBg merges into the existing spec via setBackground', () => {
+		const handleOp = vi.fn<(op: LayoutOp) => void>();
+		const m = monitor({ background: { kind: 'image', src: 'wall.png' } });
+		const { result } = renderHook(() =>
+			useBackground({ studio: true, navSection: 'background', monitor: m, handleOp })
+		);
+		act(() => result.current.patchBg({ opacity: 0.5 }));
+		expect(handleOp).toHaveBeenCalledWith({
+			op: 'setBackground',
+			spec: { kind: 'image', src: 'wall.png', opacity: 0.5 }
+		});
+	});
+
+	it('patchBg starts from a default color base when there is no background yet', () => {
+		const handleOp = vi.fn<(op: LayoutOp) => void>();
+		const { result } = renderHook(() =>
+			useBackground({ studio: true, navSection: 'background', monitor: monitor(), handleOp })
+		);
+		act(() => result.current.patchBg({ src: '#abc' }));
+		expect(handleOp).toHaveBeenCalledWith({
+			op: 'setBackground',
+			spec: { kind: 'color', src: '#abc' }
+		});
+	});
+
+	it('setBgKind keeps src when the kind is unchanged, else resets it', () => {
+		const handleOp = vi.fn<(op: LayoutOp) => void>();
+		const m = monitor({ background: { kind: 'image', src: 'wall.png' } });
+		const { result } = renderHook(() =>
+			useBackground({ studio: true, navSection: 'background', monitor: m, handleOp })
+		);
+		act(() => result.current.setBgKind('image')); // same kind → keep src
+		expect(handleOp).toHaveBeenLastCalledWith({
+			op: 'setBackground',
+			spec: { kind: 'image', src: 'wall.png' }
+		});
+		act(() => result.current.setBgKind('color')); // different kind → reset src
+		expect(handleOp).toHaveBeenLastCalledWith({
+			op: 'setBackground',
+			spec: { kind: 'color', src: '' }
+		});
+	});
+
+	it('clearBg dispatches setBackground with an undefined spec', () => {
+		const handleOp = vi.fn<(op: LayoutOp) => void>();
+		const { result } = renderHook(() =>
+			useBackground({ studio: true, navSection: 'background', monitor: monitor(), handleOp })
+		);
+		act(() => result.current.clearBg());
+		expect(handleOp).toHaveBeenCalledWith({ op: 'setBackground', spec: undefined });
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useCanvasPointer.test.ts b/client/src/lib/widgets/canvas/useCanvasPointer.test.ts
index 50e914f..15efcdd 100644
--- a/client/src/lib/widgets/canvas/useCanvasPointer.test.ts
+++ b/client/src/lib/widgets/canvas/useCanvasPointer.test.ts
@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { act, renderHook } from '@testing-library/react';
-import { useCanvasPointer, type CanvasPointerDeps } from './useCanvasPointer';
+import { marqueeSelection, useCanvasPointer, type CanvasPointerDeps } from './useCanvasPointer';
 import type { Pan } from './useZoomFit';
+import type { Renderable } from '../../core/solve';
 
 const canvasEl = document.createElement('div');
 canvasEl.classList.add('canvas');
@@ -9,24 +10,30 @@ const widgetEl = document.createElement('div'); // not .canvas/.world
 
 const state = { space: false };
 
+const setPan = vi.fn();
+const setSelection = vi.fn();
+const clearSelection = vi.fn();
+
 const deps: CanvasPointerDeps = {
 	editMode: true,
 	studio: true,
 	overrides: () => ({}),
 	spaceDown: () => state.space,
 	pan: (): Pan => ({ panX: 0, panY: 0, zoom: 1 }),
-	setPan: vi.fn(),
+	setPan,
 	canvasRef: { current: document.createElement('div') },
 	renderables: () => [],
 	selectedIds: () => [],
-	setSelection: vi.fn(),
-	clearSelection: vi.fn()
+	setSelection,
+	clearSelection
 };
 
 type Over = Partial<{
 	button: number;
 	target: EventTarget;
 	shiftKey: boolean;
+	clientX: number;
+	clientY: number;
 }>;
 const ev = (o: Over) =>
 	({
@@ -47,9 +54,38 @@ function release() {
 	act(() => window.dispatchEvent(new MouseEvent('mouseup')));
 }
 
+const rend = (selectId: string, rect: { x: number; y: number; w: number; h: number }): Renderable =>
+	({ selectId, rect } as unknown as Renderable);
+
 afterEach(() => {
 	release();
 	state.space = false;
+	vi.clearAllMocks();
+});
+
+describe('marqueeSelection (pure)', () => {
+	it('replaces selection with intersecting renderables; primary is the last added', () => {
+		const rs = [
+			rend('a', { x: 0, y: 0, w: 10, h: 10 }),
+			rend('b', { x: 100, y: 100, w: 10, h: 10 })
+		];
+		const box = { x: 0, y: 0, w: 5, h: 5 };
+		expect(marqueeSelection(rs, box, false, ['x'])).toEqual({ ids: ['a'], primary: 'a' });
+	});
+
+	it('additive merges into the current ids and de-dups', () => {
+		const rs = [rend('b', { x: 0, y: 0, w: 10, h: 10 })];
+		const box = { x: 0, y: 0, w: 5, h: 5 };
+		expect(marqueeSelection(rs, box, true, ['a', 'b'])).toEqual({ ids: ['a', 'b'], primary: 'b' });
+	});
+
+	it('an empty hit yields no primary', () => {
+		const rs = [rend('a', { x: 100, y: 100, w: 10, h: 10 })];
+		expect(marqueeSelection(rs, { x: 0, y: 0, w: 1, h: 1 }, false, [])).toEqual({
+			ids: [],
+			primary: null
+		});
+	});
 });
 
 describe('useCanvasPointer registry-driven gestures', () => {
@@ -66,11 +102,25 @@ describe('useCanvasPointer registry-driven gestures', () => {
 		expect(result.current.panning).toBe(true);
 	});
 
+	it('a pan move translates panX/panY by the pointer delta, and mouseup ends panning', () => {
+		const { result } = renderHook(() => useCanvasPointer(deps));
+		act(() => result.current.onCanvasMouseDown(ev({ button: 1, clientX: 100, clientY: 50 })));
+		act(() => window.dispatchEvent(new MouseEvent('mousemove', { clientX: 130, clientY: 70 })));
+		// setPan was called with an updater. The pan origin (0,0) was captured at mousedown from
+		// deps.pan(); the updater spreads the base pan only for `zoom`, and writes panX/panY from
+		// the captured origin + the pointer delta (30, 20).
+		const updater = setPan.mock.calls.at(-1)![0] as (p: Pan) => Pan;
+		expect(updater({ panX: 5, panY: 6, zoom: 2 })).toEqual({ panX: 30, panY: 20, zoom: 2 });
+		act(() => window.dispatchEvent(new MouseEvent('mouseup')));
+		expect(result.current.panning).toBe(false);
+	});
+
 	it('left-drag on the empty canvas starts a marquee', () => {
 		const { result } = renderHook(() => useCanvasPointer(deps));
 		act(() => result.current.onCanvasMouseDown(ev({ button: 0, target: canvasEl })));
 		expect(result.current.marquee).not.toBeNull();
 		expect(result.current.panning).toBe(false);
+		expect(clearSelection).toHaveBeenCalled();
 	});
 
 	it('left-drag that did not land on the canvas does nothing', () => {
@@ -79,4 +129,59 @@ describe('useCanvasPointer registry-driven gestures', () => {
 		expect(result.current.marquee).toBeNull();
 		expect(result.current.panning).toBe(false);
 	});
+
+	it('a real drag updates the marquee rect on move and selects intersecting renderables on up', () => {
+		const renderables = [rend('hit', { x: 0, y: 0, w: 200, h: 200 })];
+		const { result } = renderHook(() =>
+			useCanvasPointer({ ...deps, renderables: () => renderables })
+		);
+		act(() => result.current.onCanvasMouseDown(ev({ button: 0, clientX: 0, clientY: 0 })));
+		act(() => window.dispatchEvent(new MouseEvent('mousemove', { clientX: 100, clientY: 80 })));
+		expect(result.current.marquee).toEqual({ x: 0, y: 0, w: 100, h: 80 });
+		act(() => window.dispatchEvent(new MouseEvent('mouseup')));
+		expect(result.current.marquee).toBeNull();
+		expect(setSelection).toHaveBeenCalledWith(['hit'], 'hit');
+	});
+
+	it('a sub-3px drag is treated as a click and leaves the selection untouched', () => {
+		const { result } = renderHook(() => useCanvasPointer(deps));
+		act(() => result.current.onCanvasMouseDown(ev({ button: 0, clientX: 0, clientY: 0 })));
+		act(() => window.dispatchEvent(new MouseEvent('mousemove', { clientX: 1, clientY: 1 })));
+		act(() => window.dispatchEvent(new MouseEvent('mouseup')));
+		expect(setSelection).not.toHaveBeenCalled();
+	});
+
+	it('Shift + left-drag is an additive marquee (no clearSelection)', () => {
+		const { result } = renderHook(() => useCanvasPointer(deps));
+		act(() =>
+			result.current.onCanvasMouseDown(ev({ button: 0, shiftKey: true, clientX: 0, clientY: 0 }))
+		);
+		expect(clearSelection).not.toHaveBeenCalled();
+		act(() => window.dispatchEvent(new MouseEvent('mousemove', { clientX: 50, clientY: 50 })));
+		act(() => window.dispatchEvent(new MouseEvent('mouseup')));
+		expect(setSelection).toHaveBeenCalled();
+	});
+
+	it('does nothing when not in edit mode', () => {
+		const { result } = renderHook(() => useCanvasPointer({ ...deps, editMode: false }));
+		act(() => result.current.onCanvasMouseDown(ev({ button: 0 })));
+		expect(result.current.marquee).toBeNull();
+		expect(result.current.panning).toBe(false);
+	});
+
+	it('a right-click resolves to no gesture and does nothing', () => {
+		const { result } = renderHook(() => useCanvasPointer(deps));
+		act(() => result.current.onCanvasMouseDown(ev({ button: 2 })));
+		expect(result.current.marquee).toBeNull();
+		expect(result.current.panning).toBe(false);
+	});
+
+	it('falls back to raw client coords when the canvasRef is null', () => {
+		const { result } = renderHook(() =>
+			useCanvasPointer({ ...deps, canvasRef: { current: null } })
+		);
+		act(() => result.current.onCanvasMouseDown(ev({ button: 0, clientX: 7, clientY: 9 })));
+		// toCanvas with no element returns the raw coords → marquee origin at (7, 9).
+		expect(result.current.marquee).toEqual({ x: 7, y: 9, w: 0, h: 0 });
+	});
 });
diff --git a/client/src/lib/widgets/canvas/useControls.test.ts b/client/src/lib/widgets/canvas/useControls.test.ts
new file mode 100644
index 0000000..efc73d0
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useControls.test.ts
@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+
+// Mock the outer-ring disk IO (overlay loadControls/saveControls). The pure validator
+// (core/controls parseControlOverrides) stays REAL so we verify load → parse → state, and that
+// mutations both update state AND persist the `{ version, overrides }` envelope.
+const loadControls = vi.fn();
+const saveControls = vi.fn();
+vi.mock('../../overlay', () => ({
+	loadControls: () => loadControls(),
+	saveControls: (s: string) => saveControls(s)
+}));
+
+import { useControls } from './useControls';
+import type { ControlOverride } from '../../core/controls';
+
+beforeEach(() => {
+	loadControls.mockResolvedValue(null);
+});
+afterEach(() => vi.clearAllMocks());
+
+const remap: ControlOverride = { triggers: [{ type: 'key', key: 'j', ctrl: true }] };
+
+describe('useControls', () => {
+	it('starts empty', () => {
+		const { result } = renderHook(() => useControls());
+		expect(result.current.overrides).toEqual({});
+		expect(result.current.overridesRef.current).toEqual({});
+	});
+
+	it('reloadControls loads + validates the on-disk envelope into state', async () => {
+		const onDisk = { triggers: [{ type: 'key', key: 'z', ctrl: true }] };
+		loadControls.mockResolvedValue(JSON.stringify({ version: 1, overrides: { undo: onDisk } }));
+		const { result } = renderHook(() => useControls());
+		await act(async () => {
+			await result.current.reloadControls();
+		});
+		expect(result.current.overrides).toEqual({ undo: onDisk });
+		expect(result.current.overridesRef.current).toEqual({ undo: onDisk });
+	});
+
+	it('reloadControls falls back to defaults (empty) for a null file', async () => {
+		loadControls.mockResolvedValue(null);
+		const { result } = renderHook(() => useControls());
+		await act(async () => {
+			await result.current.reloadControls();
+		});
+		expect(result.current.overrides).toEqual({});
+	});
+
+	it('reloadControls falls back to defaults for a corrupt (unparseable) file', async () => {
+		loadControls.mockResolvedValue('{ not json');
+		const { result } = renderHook(() => useControls());
+		await act(async () => {
+			await result.current.reloadControls();
+		});
+		expect(result.current.overrides).toEqual({}); // degraded safely, no throw
+	});
+
+	it('setOverride updates state and persists the versioned envelope', async () => {
+		const { result } = renderHook(() => useControls());
+		act(() => result.current.setOverride('redo', remap));
+		expect(result.current.overrides).toEqual({ redo: remap });
+		expect(result.current.overridesRef.current).toEqual({ redo: remap });
+		expect(JSON.parse(saveControls.mock.calls[0]![0])).toEqual({
+			version: 1,
+			overrides: { redo: remap }
+		});
+	});
+
+	it('resetOverride removes a single binding and persists the rest', () => {
+		const { result } = renderHook(() => useControls());
+		const disabled: ControlOverride = { disabled: true };
+		act(() => result.current.setOverride('redo', remap));
+		act(() => result.current.setOverride('undo', disabled));
+		act(() => result.current.resetOverride('redo'));
+		expect(result.current.overrides).toEqual({ undo: disabled });
+		expect(JSON.parse(saveControls.mock.calls.at(-1)![0]).overrides).toEqual({ undo: disabled });
+	});
+
+	it('resetAll clears every override and persists an empty map', () => {
+		const { result } = renderHook(() => useControls());
+		act(() => result.current.setOverride('redo', remap));
+		act(() => result.current.resetAll());
+		expect(result.current.overrides).toEqual({});
+		expect(JSON.parse(saveControls.mock.calls.at(-1)![0]).overrides).toEqual({});
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useDefEditor.test.ts b/client/src/lib/widgets/canvas/useDefEditor.test.ts
new file mode 100644
index 0000000..977992e
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useDefEditor.test.ts
@@ -0,0 +1,256 @@
+// useDefEditor is the studio-bar/list-side wrapper around the def-edit reducer: every "open a
+// widget in the designer" path FOLDS any open def first (so the reducer's re-entry guard never
+// blocks switching), then dispatches the mode action; rename/delete wrap handleOp with the
+// window prompt/confirm/alert dialogs. The reducer itself is tested in useEditorModel.test.ts —
+// here we assert this hook's orchestration (which action fires, in what order, with what guards)
+// by spying on the injected dispatch / handleOp and stubbing the window dialogs.
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useDefEditor } from './useDefEditor';
+import type { EditorState } from './types';
+import { container, emptyRoot, group, leaf, type MonitorLayout } from '../../core/layoutTree';
+import { createWidget } from '../../core/widget';
+
+// A minimal EditorState — only the fields defInUse() actually reads (monitor / editingDefId /
+// savedMonitor) need to be real; the rest are filled to satisfy the type.
+function makeState(monitor: MonitorLayout, over: Partial<EditorState> = {}): EditorState {
+	return {
+		monitor,
+		library: { version: 1, defs: [] },
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: false,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: true,
+		...over
+	};
+}
+
+const emptyMonitor = (): MonitorLayout => ({ root: emptyRoot(), floating: [] });
+
+// A monitor whose flow tree contains one group leaf that instantiates `defId` (makes defInUse true).
+function monitorUsing(defId: string): MonitorLayout {
+	const g = group('g1', { w: 100, h: 50 }, leaf(createWidget('text', 'g1-child')), { def: defId });
+	return { root: container('root', 'col', [leaf(g)]), floating: [] };
+}
+
+type Deps = Parameters<typeof useDefEditor>[0];
+
+// Render the hook with spy dispatch / handleOp and a mutable stateRef. Returns the hook result, the
+// spies, and a rerender that lets a test flip editingDefId / previewing (the hook reads them via refs).
+function setup(init: Partial<Deps> = {}) {
+	const dispatch = vi.fn();
+	const handleOp = vi.fn();
+	const stateRef: React.RefObject<EditorState> = { current: makeState(emptyMonitor()) };
+	const base: Deps = {
+		editingDefId: null,
+		previewing: false,
+		stateRef,
+		dispatch,
+		handleOp,
+		...init
+	};
+	const r = renderHook((props: Deps) => useDefEditor(props), { initialProps: base });
+	return { ...r, dispatch, handleOp, stateRef, base };
+}
+
+let prompt: MockInstance<typeof window.prompt>;
+let confirm: MockInstance<typeof window.confirm>;
+let alert: MockInstance<typeof window.alert>;
+
+beforeEach(() => {
+	prompt = vi.spyOn(window, 'prompt').mockReturnValue(null);
+	confirm = vi.spyOn(window, 'confirm').mockReturnValue(false);
+	alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+});
+afterEach(() => vi.restoreAllMocks());
+
+describe('foldOpenDef', () => {
+	it('discards a read-only preview via endPreview', () => {
+		const { result, dispatch } = setup({ previewing: true });
+		act(() => result.current.foldOpenDef());
+		expect(dispatch).toHaveBeenCalledWith({ type: 'endPreview' });
+	});
+
+	it('folds a real def edit via endDefEdit', () => {
+		const { result, dispatch } = setup({ editingDefId: 'd1' });
+		act(() => result.current.foldOpenDef());
+		expect(dispatch).toHaveBeenCalledWith({ type: 'endDefEdit' });
+	});
+
+	it('preview wins over an open def edit (only endPreview fires)', () => {
+		const { result, dispatch } = setup({ previewing: true, editingDefId: 'd1' });
+		act(() => result.current.foldOpenDef());
+		expect(dispatch).toHaveBeenCalledTimes(1);
+		expect(dispatch).toHaveBeenCalledWith({ type: 'endPreview' });
+	});
+
+	it('does nothing when neither previewing nor editing', () => {
+		const { result, dispatch } = setup();
+		act(() => result.current.foldOpenDef());
+		expect(dispatch).not.toHaveBeenCalled();
+	});
+
+	it('reads the LATEST previewing/editingDefId via refs after a rerender', () => {
+		const { result, rerender, dispatch, base } = setup();
+		// Initially neither flag is set → no-op.
+		act(() => result.current.foldOpenDef());
+		expect(dispatch).not.toHaveBeenCalled();
+		// Flip editingDefId on a rerender; the stable callback must observe the new value.
+		rerender({ ...base, editingDefId: 'd9' });
+		act(() => result.current.foldOpenDef());
+		expect(dispatch).toHaveBeenLastCalledWith({ type: 'endDefEdit' });
+	});
+});
+
+describe('open / new / clone / template entry points fold first then dispatch', () => {
+	it('startNewWidget folds the open def then dispatches newWidget (in that order)', () => {
+		const { result, dispatch } = setup({ editingDefId: 'd1' });
+		act(() => result.current.startNewWidget());
+		expect(dispatch.mock.calls.map((c) => c[0])).toEqual([
+			{ type: 'endDefEdit' },
+			{ type: 'newWidget' }
+		]);
+	});
+
+	it('openExistingDef folds then enters def-edit on the id', () => {
+		const { result, dispatch } = setup({ previewing: true });
+		act(() => result.current.openExistingDef('def-7'));
+		expect(dispatch.mock.calls.map((c) => c[0])).toEqual([
+			{ type: 'endPreview' },
+			{ type: 'enterDefEdit', defId: 'def-7' }
+		]);
+	});
+
+	it('openExistingDef is a guarded no-op for an empty id (no fold, no enter)', () => {
+		const { result, dispatch } = setup({ editingDefId: 'd1' });
+		act(() => result.current.openExistingDef(''));
+		expect(dispatch).not.toHaveBeenCalled();
+	});
+
+	it('cloneDefToEdit folds then dispatches cloneDef', () => {
+		const { result, dispatch } = setup({ editingDefId: 'd1' });
+		act(() => result.current.cloneDefToEdit('src'));
+		expect(dispatch.mock.calls.map((c) => c[0])).toEqual([
+			{ type: 'endDefEdit' },
+			{ type: 'cloneDef', defId: 'src' }
+		]);
+	});
+
+	it('newFromTemplate folds then dispatches newFromTemplate', () => {
+		const { result, dispatch } = setup();
+		act(() => result.current.newFromTemplate('clock-jp'));
+		expect(dispatch).toHaveBeenCalledWith({ type: 'newFromTemplate', templateId: 'clock-jp' });
+	});
+
+	it('previewTemplate folds then dispatches previewTemplate', () => {
+		const { result, dispatch } = setup({ editingDefId: 'd1' });
+		act(() => result.current.previewTemplate('clock-jp'));
+		expect(dispatch.mock.calls.map((c) => c[0])).toEqual([
+			{ type: 'endDefEdit' },
+			{ type: 'previewTemplate', templateId: 'clock-jp' }
+		]);
+	});
+});
+
+describe('preview banner buttons (no fold)', () => {
+	it('clonePreview dispatches clonePreview without folding', () => {
+		const { result, dispatch } = setup({ previewing: true });
+		act(() => result.current.clonePreview());
+		expect(dispatch).toHaveBeenCalledTimes(1);
+		expect(dispatch).toHaveBeenCalledWith({ type: 'clonePreview' });
+	});
+
+	it('closePreview dispatches endPreview', () => {
+		const { result, dispatch } = setup({ previewing: true });
+		act(() => result.current.closePreview());
+		expect(dispatch).toHaveBeenCalledTimes(1);
+		expect(dispatch).toHaveBeenCalledWith({ type: 'endPreview' });
+	});
+});
+
+describe('renameWidget (prompt)', () => {
+	it('renames via handleOp with the trimmed prompt value', () => {
+		prompt.mockReturnValue('  Fresh Name  ');
+		const { result, handleOp } = setup();
+		act(() => result.current.renameWidget('d1', 'Old'));
+		expect(prompt).toHaveBeenCalledWith('Rename widget:', 'Old');
+		expect(handleOp).toHaveBeenCalledWith({ op: 'renameDef', defId: 'd1', name: 'Fresh Name' });
+	});
+
+	it('is a no-op when the prompt is cancelled (null)', () => {
+		prompt.mockReturnValue(null);
+		const { result, handleOp } = setup();
+		act(() => result.current.renameWidget('d1', 'Old'));
+		expect(handleOp).not.toHaveBeenCalled();
+	});
+
+	it('is a no-op for a blank / whitespace-only name', () => {
+		prompt.mockReturnValue('   ');
+		const { result, handleOp } = setup();
+		act(() => result.current.renameWidget('d1', 'Old'));
+		expect(handleOp).not.toHaveBeenCalled();
+	});
+});
+
+describe('deleteWidget (in-use guard + confirm)', () => {
+	it('refuses to delete a def that is placed on a layout (alert, no handleOp)', () => {
+		const stateRef: React.RefObject<EditorState> = { current: makeState(monitorUsing('used')) };
+		const { result, handleOp } = setup({ stateRef });
+		act(() => result.current.deleteWidget('used', 'My Widget'));
+		expect(alert).toHaveBeenCalledTimes(1);
+		expect(alert.mock.calls[0][0]).toContain('My Widget');
+		expect(handleOp).not.toHaveBeenCalled();
+	});
+
+	it('is a no-op when the confirm dialog is declined', () => {
+		confirm.mockReturnValue(false);
+		const { result, handleOp } = setup(); // empty monitor → not in use
+		act(() => result.current.deleteWidget('free', 'Spare'));
+		expect(confirm).toHaveBeenCalledTimes(1);
+		expect(handleOp).not.toHaveBeenCalled();
+	});
+
+	it('deletes an unused, confirmed def via handleOp (no fold when it is not being edited)', () => {
+		confirm.mockReturnValue(true);
+		const { result, handleOp, dispatch } = setup({ editingDefId: 'other' });
+		act(() => result.current.deleteWidget('free', 'Spare'));
+		expect(handleOp).toHaveBeenCalledWith({ op: 'deleteDef', defId: 'free' });
+		// editingDefId !== the deleted id → no foldOpenDef dispatch.
+		expect(dispatch).not.toHaveBeenCalled();
+	});
+
+	it('folds the open def first when deleting the def currently being designed', () => {
+		confirm.mockReturnValue(true);
+		// The deleted def is the one being edited → deleteWidget folds (endDefEdit) BEFORE deleteDef so
+		// the reducer's deleteDef isn't blocked by the open scope.
+		const { result, handleOp, dispatch } = setup({ editingDefId: 'self' });
+		act(() => result.current.deleteWidget('self', 'Self'));
+		expect(dispatch).toHaveBeenCalledWith({ type: 'endDefEdit' });
+		expect(handleOp).toHaveBeenCalledWith({ op: 'deleteDef', defId: 'self' });
+	});
+});
+
+describe('callback stability', () => {
+	it('keeps every wrapper identity stable across a rerender (deps are dispatch/handleOp/stateRef)', () => {
+		const { result, rerender, base } = setup();
+		const first = { ...result.current };
+		rerender({ ...base });
+		for (const key of Object.keys(first) as (keyof typeof first)[]) {
+			expect(result.current[key]).toBe(first[key]);
+		}
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useEditorModel.test.ts b/client/src/lib/widgets/canvas/useEditorModel.test.ts
new file mode 100644
index 0000000..4279dc6
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useEditorModel.test.ts
@@ -0,0 +1,706 @@
+// The Canvas editor model's reducer — driven through the hook because the reducer + Action union are
+// internal to useEditorModel (only the hook, the op helpers, and editHelpers are exported). This
+// file targets the reducer paths the existing canvas tests (previewTemplate / insertTemplate /
+// useKeyboard / useStudioInit) leave uncovered: selection, undo/redo + history, the op-apply commit
+// chokepoint, the def-edit mode switches, the load/theme/baseline actions, and the handleOp switch.
+import { describe, it, expect } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useEditorModel } from './useEditorModel';
+import {
+	container,
+	isContainer,
+	isGroup,
+	isLeaf,
+	leaf,
+	type Library,
+	type MonitorLayout,
+	type WidgetInstance
+} from '../../core/layoutTree';
+import { createWidget } from '../../core/widget';
+
+const ROOT = 'root'; // emptyRoot()'s container id
+
+// Render the model with the root container selected, so addWidget docks into the flow tree (with
+// nothing selected, addWidget would drop the widget on the FLOATING layer instead). Returns the hook.
+function renderModel() {
+	const r = renderHook(() => useEditorModel(true, []));
+	act(() => r.result.current.handleOp({ op: 'select', id: ROOT }));
+	return r;
+}
+
+// Render the model and add `count` flow widgets via handleOp (each its own commit / undo step). Returns
+// the hook result + the placed widget ids in insertion order. Re-selects the root before each add so
+// every widget lands as a direct root child (addWidget targets the currently-selected container).
+// `resetHistory` first: the initial state has historyReady=false, so commits don't record undo until
+// the layout is "loaded" (the Canvas dispatches resetHistory after load) — mirror that here.
+function modelWith(count: number) {
+	const { result } = renderModel();
+	act(() => result.current.dispatch({ type: 'resetHistory' }));
+	const ids: string[] = [];
+	for (let i = 0; i < count; i++) {
+		act(() => result.current.handleOp({ op: 'select', id: ROOT }));
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		ids.push(result.current.state.selectedId!);
+	}
+	return { result, ids };
+}
+
+// A tiny monitor with one docked text widget under the root (handy for `load` / baseline fixtures).
+function oneWidgetMonitor(id = 'w-fix'): MonitorLayout {
+	const root = container('root', 'col', [leaf(createWidget('text', id))], { align: 'stretch' });
+	return { root, floating: [] };
+}
+
+describe('selection sub-reducer', () => {
+	it('select sets selectedId and collapses any marquee to the single primary', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'setSelectedIds', ids: ['a', 'b'], primary: 'a' }));
+		expect(result.current.state.selectedIds).toEqual(['a', 'b']);
+
+		act(() => result.current.dispatch({ type: 'select', id: 'c' }));
+		expect(result.current.state.selectedId).toBe('c');
+		// syncPrimary collapses the stale marquee down to just the new primary.
+		expect(result.current.state.selectedIds).toEqual(['c']);
+		expect(result.current.state.lastPrimary).toBe('c');
+	});
+
+	it('select with id already the primary is a no-op for the marquee set', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'setSelectedIds', ids: ['a', 'b'], primary: 'a' }));
+		// selecting the SAME id as the current primary leaves selectedId === lastPrimary, so syncPrimary
+		// bails early and the marquee set survives.
+		act(() => result.current.dispatch({ type: 'select', id: 'a' }));
+		expect(result.current.state.selectedIds).toEqual(['a', 'b']);
+	});
+
+	it('selectClick sets both selectedId and selectedIds and marks them synced', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'setSelectedIds', ids: ['a', 'b'], primary: 'a' }));
+		act(() => result.current.dispatch({ type: 'selectClick', id: 'z' }));
+		const s = result.current.state;
+		expect(s.selectedId).toBe('z');
+		expect(s.selectedIds).toEqual(['z']);
+		expect(s.lastPrimary).toBe('z');
+	});
+
+	it('setSelectedIds is authoritative (set + primary) and survives a follow-up no-op sync', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() =>
+			result.current.dispatch({ type: 'setSelectedIds', ids: ['x', 'y', 'z'], primary: 'y' })
+		);
+		const s = result.current.state;
+		expect(s.selectedIds).toEqual(['x', 'y', 'z']);
+		expect(s.selectedId).toBe('y');
+		expect(s.lastPrimary).toBe('y');
+	});
+});
+
+describe('op-apply path (commit chokepoint)', () => {
+	it('commitOp applies the patch, records undo, and bumps saveSeq', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const seq0 = result.current.state.saveSeq;
+		act(() => result.current.commitOp((s) => ({ monitor: { ...s.monitor, floating: [] } })));
+		// Even a no-op-shaped patch bumps saveSeq (the persistence effect fires on the seq, the undo
+		// recorder dedupes by reference).
+		expect(result.current.state.saveSeq).toBe(seq0 + 1);
+	});
+
+	it('a real commit edit pushes one undo entry and clears redo (after history is ready)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		// historyReady is false until the first resetHistory (the post-load re-anchor) — commits before
+		// then don't record undo.
+		act(() => result.current.dispatch({ type: 'resetHistory' }));
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		expect(result.current.state.undoStack.length).toBe(1);
+		expect(result.current.state.redoStack).toEqual([]);
+	});
+
+	it('commits made before resetHistory do NOT record undo (historyReady gate)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		expect(result.current.state.undoStack).toEqual([]);
+	});
+
+	it('mutateNoSave applies the patch WITHOUT recording undo or bumping saveSeq', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const seq0 = result.current.state.saveSeq;
+		act(() =>
+			result.current.mutateNoSave((s) => ({ selectedId: 'transient', monitor: s.monitor }))
+		);
+		expect(result.current.state.selectedId).toBe('transient');
+		expect(result.current.state.saveSeq).toBe(seq0);
+		expect(result.current.state.undoStack).toEqual([]);
+	});
+
+	it('an op patch that sets selectedId (without selectedIds) collapses the marquee', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'setSelectedIds', ids: ['a', 'b'], primary: 'a' }));
+		act(() => result.current.mutateNoSave(() => ({ selectedId: 'solo' })));
+		expect(result.current.state.selectedIds).toEqual(['solo']);
+	});
+
+	it('an op patch that sets selectedIds is authoritative (the set is NOT collapsed)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() =>
+			result.current.mutateNoSave(() => ({ selectedId: 'p', selectedIds: ['p', 'q', 'r'] }))
+		);
+		expect(result.current.state.selectedIds).toEqual(['p', 'q', 'r']);
+	});
+
+	it('plain patch action applies + syncs primary without committing', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const seq0 = result.current.state.saveSeq;
+		act(() => result.current.dispatch({ type: 'patch', patch: { selectedId: 'pp' } }));
+		expect(result.current.state.selectedId).toBe('pp');
+		expect(result.current.state.selectedIds).toEqual(['pp']); // collapsed
+		expect(result.current.state.saveSeq).toBe(seq0);
+	});
+});
+
+describe('history sub-reducer (undo / redo)', () => {
+	it('undo reverts the monitor to the previous snapshot', () => {
+		const { result, ids } = modelWith(2);
+		expect(result.current.state.monitor.root.children).toHaveLength(2);
+		const beforeUndo = result.current.state.monitor;
+
+		act(() => result.current.dispatch({ type: 'undo' }));
+		const s = result.current.state;
+		expect(s.monitor.root.children).toHaveLength(1);
+		expect(s.monitor.root.children[0].id).toBe(ids[0]);
+		expect(s.redoStack).toHaveLength(1); // the undone state is on the redo branch
+		expect(s.redoStack[0].monitor).toBe(beforeUndo);
+	});
+
+	it('redo re-applies an undone edit', () => {
+		const { result } = modelWith(2);
+		act(() => result.current.dispatch({ type: 'undo' }));
+		expect(result.current.state.monitor.root.children).toHaveLength(1);
+		act(() => result.current.dispatch({ type: 'redo' }));
+		expect(result.current.state.monitor.root.children).toHaveLength(2);
+		expect(result.current.state.redoStack).toEqual([]);
+	});
+
+	it('undo on an empty stack is a no-op (same state reference)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'undo' }));
+		expect(result.current.state).toBe(before);
+	});
+
+	it('redo on an empty stack is a no-op', () => {
+		const { result } = modelWith(1);
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'redo' }));
+		expect(result.current.state).toBe(before);
+	});
+
+	it('a fresh edit after an undo clears the redo branch', () => {
+		const { result } = modelWith(2);
+		act(() => result.current.dispatch({ type: 'undo' }));
+		expect(result.current.state.redoStack).toHaveLength(1);
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		expect(result.current.state.redoStack).toEqual([]); // recordHistory cleared it
+	});
+
+	it('multiple edits then undo walks back one step at a time', () => {
+		const { result } = modelWith(3);
+		expect(result.current.state.monitor.root.children).toHaveLength(3);
+		act(() => result.current.dispatch({ type: 'undo' }));
+		expect(result.current.state.monitor.root.children).toHaveLength(2);
+		act(() => result.current.dispatch({ type: 'undo' }));
+		expect(result.current.state.monitor.root.children).toHaveLength(1);
+	});
+});
+
+describe('history reset + baseline', () => {
+	it('resetHistory clears both stacks and re-anchors lastSnap', () => {
+		const { result } = modelWith(2);
+		expect(result.current.state.undoStack.length).toBeGreaterThan(0);
+		act(() => result.current.dispatch({ type: 'resetHistory' }));
+		const s = result.current.state;
+		expect(s.undoStack).toEqual([]);
+		expect(s.redoStack).toEqual([]);
+		expect(s.historyReady).toBe(true);
+		expect(s.lastSnap?.monitor).toBe(s.monitor);
+	});
+
+	it('setBaseline captures the current monitor/library/theme/tokens as the saved baseline', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'setTheme', name: 'builtin:dark' }));
+		act(() => result.current.handleOp({ op: 'setToken', key: '--accent', value: '#f00' }));
+		act(() => result.current.dispatch({ type: 'setBaseline' }));
+		const b = result.current.state.savedBaseline!;
+		expect(b).not.toBeNull();
+		expect(b.monitor).toBe(result.current.state.monitor);
+		expect(b.theme).toBe('builtin:dark');
+		expect(b.tokens).toEqual({ '--accent': '#f00' });
+	});
+
+	it('setBaseline mid-def-edit also re-anchors the def-edit baseline to the scoped monitor', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		expect(result.current.state.editingDefId).not.toBeNull();
+		act(() => result.current.dispatch({ type: 'setBaseline' }));
+		expect(result.current.state.defEditBaseline).toBe(result.current.state.monitor);
+	});
+});
+
+describe('def-edit sub-reducer', () => {
+	it('newWidget appends an empty def, enters def-edit, and stashes the real monitor', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const realMonitor = result.current.state.monitor;
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const s = result.current.state;
+		expect(s.library?.defs).toHaveLength(1);
+		expect(s.editingDefId).toBe(s.library!.defs[0].id);
+		expect(s.savedMonitor).toBe(realMonitor); // the live layout is preserved untouched
+		expect(s.defEditBaseline).toBe(s.monitor); // scoped monitor as the def-edit baseline
+		expect(s.selectedId).toBeNull();
+		expect(s.undoStack).toEqual([]); // history reset on entering the scope
+	});
+
+	it('newWidget is refused while already editing a def (would orphan savedMonitor)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const firstDefId = result.current.state.editingDefId;
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		expect(result.current.state).toBe(before); // unchanged
+		expect(result.current.state.editingDefId).toBe(firstDefId);
+		expect(result.current.state.library?.defs).toHaveLength(1);
+	});
+
+	it('cloneDef duplicates an existing def (-copy) and enters def-edit on the copy', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		// Seed a library def, then leave def-edit so a clone is allowed.
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const srcId = result.current.state.editingDefId!;
+		act(() => result.current.dispatch({ type: 'endDefEdit' }));
+
+		act(() => result.current.dispatch({ type: 'cloneDef', defId: srcId }));
+		const s = result.current.state;
+		expect(s.library?.defs).toHaveLength(2);
+		const copy = s.library!.defs.find((d) => d.id !== srcId)!;
+		expect(copy.name.endsWith('-copy')).toBe(true);
+		expect(s.editingDefId).toBe(copy.id);
+	});
+
+	it('cloneDef is a no-op for an unknown def id', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'cloneDef', defId: 'nope' }));
+		expect(result.current.state).toBe(before);
+	});
+
+	it('enterDefEdit scopes the monitor to the def and stashes the real layout', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const defId = result.current.state.editingDefId!;
+		// Fold the open def first; now re-enter via the handleOp editDef path.
+		act(() => result.current.dispatch({ type: 'endDefEdit' }));
+		const realMonitor = result.current.state.monitor;
+		act(() => result.current.handleOp({ op: 'editDef', defId }));
+		const s = result.current.state;
+		expect(s.editingDefId).toBe(defId);
+		expect(s.savedMonitor).toBe(realMonitor);
+		expect(s.monitor.root.id).toContain(defId); // scopedMonitorFromDef rooted the def's child
+	});
+
+	it('enterDefEdit is refused while another def is already open', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const open = result.current.state.editingDefId;
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'enterDefEdit', defId: 'whatever' }));
+		expect(result.current.state).toBe(before);
+		expect(result.current.state.editingDefId).toBe(open);
+	});
+
+	it('endDefEdit writes the scoped tree back onto the def, restores the monitor, and commits', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const realMonitor = result.current.state.monitor;
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const defId = result.current.state.editingDefId!;
+		const seqBefore = result.current.state.saveSeq;
+		// Edit the scoped tree (add a widget into the def's root) before folding it back.
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const editedScopedRoot = result.current.state.monitor.root;
+
+		act(() => result.current.dispatch({ type: 'endDefEdit' }));
+		const s = result.current.state;
+		expect(s.editingDefId).toBeNull();
+		expect(s.savedMonitor).toBeNull();
+		expect(s.monitor).toBe(realMonitor); // back on the real layout
+		const def = s.library!.defs.find((d) => d.id === defId)!;
+		expect(def.child).toBe(editedScopedRoot); // the scoped edit was synced into the def
+		expect(s.saveSeq).toBeGreaterThan(seqBefore); // endDefEdit runs a commit (saveLayout)
+	});
+
+	it('endDefEdit is a no-op when not editing a def', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'endDefEdit' }));
+		expect(result.current.state).toBe(before);
+	});
+
+	it('newFromTemplate with an unknown template id is a no-op', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'newFromTemplate', templateId: 'no-such' }));
+		expect(result.current.state).toBe(before);
+	});
+
+	it('newFromTemplate of a LEAF-rooted template wraps the leaf in a scoped col root', () => {
+		// The nowplaying template's tree is a single leaf (not a container); scopedMonitorFromDef must
+		// synthesize a col root around it so the def editor has a container to edit.
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newFromTemplate', templateId: 'nowplaying' }));
+		const s = result.current.state;
+		expect(s.editingDefId).not.toBeNull();
+		expect(s.monitor.root.kind).toBe('col');
+		expect(s.monitor.root.id).toBe(`${s.editingDefId}__root`);
+		// The def itself keeps the raw leaf child (the synthesized root is only the EDITING scope).
+		const def = s.library!.defs.find((d) => d.id === s.editingDefId)!;
+		expect(isLeaf(def.child)).toBe(true);
+	});
+});
+
+describe('load / theme / monitor sub-reducer', () => {
+	it('load bulk-applies the supplied patch', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const mon = oneWidgetMonitor();
+		const library: Library = { version: 1, defs: [] };
+		act(() =>
+			result.current.dispatch({
+				type: 'load',
+				patch: { monitor: mon, library, selectedTheme: 'builtin:nord' }
+			})
+		);
+		const s = result.current.state;
+		expect(s.monitor).toBe(mon);
+		expect(s.library).toBe(library);
+		expect(s.selectedTheme).toBe('builtin:nord');
+	});
+
+	it('setTheme mirrors selectedTheme only', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'setTheme', name: 'builtin:solarized' }));
+		expect(result.current.state.selectedTheme).toBe('builtin:solarized');
+	});
+
+	it('replaceMonitor swaps the monitor wholesale (no commit)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const seq0 = result.current.state.saveSeq;
+		const mon = oneWidgetMonitor('rep');
+		act(() => result.current.dispatch({ type: 'replaceMonitor', monitor: mon }));
+		expect(result.current.state.monitor).toBe(mon);
+		expect(result.current.state.saveSeq).toBe(seq0);
+	});
+
+	it('setMonitorKey leaves the state reference untouched (a marker action)', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'setMonitorKey' }));
+		expect(result.current.state).toBe(before);
+	});
+
+	it('revertToBaseline restores the saved baseline and clears pendingExtras', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const baselineMon = oneWidgetMonitor('base');
+		const baselineLib: Library = { version: 1, defs: [] };
+		// Establish a baseline via load + setBaseline, then drift the editor, then revert.
+		act(() =>
+			result.current.dispatch({
+				type: 'load',
+				patch: {
+					monitor: baselineMon,
+					library: baselineLib,
+					selectedTheme: 'builtin:dark',
+					tokenOverrides: { '--accent': '#abc' }
+				}
+			})
+		);
+		act(() => result.current.dispatch({ type: 'setBaseline' }));
+		// Drift: change theme + add a widget + queue an extra.
+		act(() => result.current.dispatch({ type: 'setTheme', name: 'changed' }));
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		act(() =>
+			result.current.dispatch({
+				type: 'patch',
+				patch: { pendingExtras: [{ key: 'k', leaf: leaf(createWidget('text', 'extra')) }] }
+			})
+		);
+
+		act(() => result.current.dispatch({ type: 'revertToBaseline' }));
+		const s = result.current.state;
+		expect(s.monitor).toBe(baselineMon);
+		expect(s.library).toBe(baselineLib);
+		expect(s.selectedTheme).toBe('builtin:dark');
+		expect(s.tokenOverrides).toEqual({ '--accent': '#abc' });
+		expect(s.pendingExtras).toEqual([]);
+	});
+
+	it('revertToBaseline is a no-op when no baseline was ever captured', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const before = result.current.state;
+		act(() => result.current.dispatch({ type: 'revertToBaseline' }));
+		expect(result.current.state).toBe(before);
+	});
+});
+
+describe('handleOp switch (Inspector / Outline / menu funnel)', () => {
+	it('select routes to a non-saving selection', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		const seq0 = result.current.state.saveSeq;
+		act(() => result.current.handleOp({ op: 'select', id: 'sel' }));
+		expect(result.current.state.selectedId).toBe('sel');
+		expect(result.current.state.saveSeq).toBe(seq0); // selection isn't persisted
+	});
+
+	it('addContainer / split / collapse / remove drive the flow tree and commit', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		// addContainer into the root.
+		act(() => result.current.handleOp({ op: 'addContainer', kind: 'row' }));
+		const rowId = result.current.state.selectedId!;
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).toContain(rowId);
+
+		// split the new row into rows.
+		act(() => result.current.handleOp({ op: 'split', id: rowId, dir: 'rows' }));
+		const splitNode = result.current.state.monitor.root.children.find((c) => c.id === rowId)!;
+		expect(isContainer(splitNode) && splitNode.children.length).toBeGreaterThan(0);
+
+		// collapse it back.
+		act(() => result.current.handleOp({ op: 'collapse', id: rowId }));
+		expect(result.current.state.selectedId).toBe(rowId);
+
+		// remove it.
+		act(() => result.current.handleOp({ op: 'remove', id: rowId }));
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).not.toContain(rowId);
+	});
+
+	it('moveUp / moveDown / indent / outdent reorder and reparent siblings', () => {
+		// Two sibling containers under the root (containerId pins them to root level, since addContainer
+		// otherwise targets the just-selected container — which would nest them).
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.handleOp({ op: 'addContainer', kind: 'col', containerId: ROOT }));
+		const aId = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'addContainer', kind: 'col', containerId: ROOT }));
+		const bId = result.current.state.selectedId!;
+		const order0 = result.current.state.monitor.root.children.map((c) => c.id);
+		expect(order0).toEqual([aId, bId]);
+
+		act(() => result.current.handleOp({ op: 'moveUp', id: bId }));
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).toEqual([bId, aId]);
+		act(() => result.current.handleOp({ op: 'moveDown', id: bId }));
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).toEqual([aId, bId]);
+
+		// indent b into a (the previous sibling container), then outdent it back to the root.
+		act(() => result.current.handleOp({ op: 'indent', id: bId }));
+		const aNode = result.current.state.monitor.root.children[0];
+		expect(isContainer(aNode) && aNode.children.map((c) => c.id)).toContain(bId);
+		act(() => result.current.handleOp({ op: 'outdent', id: bId }));
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).toContain(bId);
+	});
+
+	it('addWidgetAt / float / dock move a leaf between the flow and floating layers', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		// Drop a floating widget on the stage.
+		act(() => result.current.handleOp({ op: 'addWidgetAt', widgetType: 'text', x: 100, y: 50 }));
+		const id = result.current.state.selectedId!;
+		expect(result.current.state.monitor.floating.map((l) => l.id)).toContain(id);
+
+		// Dock it into the flow root, then float it back out.
+		act(() => result.current.handleOp({ op: 'dock', id }));
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).toContain(id);
+		act(() => result.current.handleOp({ op: 'float', id }));
+		expect(result.current.state.monitor.floating.map((l) => l.id)).toContain(id);
+	});
+
+	it('makeWidget wraps a leaf into a group + library def; ungroup inlines it back', () => {
+		const { result } = renderModel();
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const id = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'makeWidget', id }));
+		const s1 = result.current.state;
+		expect(s1.library?.defs.length).toBe(1);
+		const grpId = s1.selectedId!;
+		const grpNode = s1.monitor.root.children.find((c) => c.id === grpId)!;
+		expect(isLeaf(grpNode) && isGroup(grpNode.unit)).toBe(true);
+
+		act(() => result.current.handleOp({ op: 'ungroup', id: grpId }));
+		// ungroup leaves the underlying widget in the tree (inlined) — the group leaf is gone.
+		const after = result.current.state.monitor.root.children;
+		expect(after.some((c) => isLeaf(c) && isGroup(c.unit))).toBe(false);
+	});
+
+	it('insertWidget instantiates a library def as a new group into the flow', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		// Seed a def via newWidget → endDefEdit so the library has one.
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const defId = result.current.state.editingDefId!;
+		act(() => result.current.dispatch({ type: 'endDefEdit' }));
+		act(() => result.current.handleOp({ op: 'insertWidget', defId }));
+		const grpId = result.current.state.selectedId!;
+		const node = result.current.state.monitor.root.children.find((c) => c.id === grpId)!;
+		expect(isLeaf(node) && isGroup(node.unit) && node.unit.def).toBe(defId);
+	});
+
+	it('renameDef / setDefSize / setDefCss / addDefParam mutate a library def; deleteDef removes it', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		const defId = result.current.state.editingDefId!;
+		act(() => result.current.dispatch({ type: 'endDefEdit' }));
+
+		act(() => result.current.handleOp({ op: 'renameDef', defId, name: 'renamed' }));
+		act(() => result.current.handleOp({ op: 'setDefSize', defId, w: 321, h: 222 }));
+		act(() => result.current.handleOp({ op: 'setDefCss', defId, css: '.x{}' }));
+		act(() => result.current.handleOp({ op: 'addDefParam', defId, key: 'core', target: 'unit.s' }));
+		const def = result.current.state.library!.defs.find((d) => d.id === defId)!;
+		expect(def.name).toBe('renamed');
+		expect(def.size).toEqual({ w: 321, h: 222 });
+		expect(def.css).toBe('.x{}');
+		expect(def.params).toEqual([{ key: 'core', target: 'unit.s' }]);
+
+		act(() => result.current.handleOp({ op: 'deleteDef', defId }));
+		expect(result.current.state.library!.defs.find((d) => d.id === defId)).toBeUndefined();
+	});
+
+	it('token ops: setToken / setTokens / clearTokens', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.handleOp({ op: 'setToken', key: '--a', value: '#1' }));
+		act(() => result.current.handleOp({ op: 'setTokens', tokens: { '--b': '#2', '--c': '#3' } }));
+		expect(result.current.state.tokenOverrides).toEqual({ '--a': '#1', '--b': '#2', '--c': '#3' });
+		act(() => result.current.handleOp({ op: 'clearTokens' }));
+		expect(result.current.state.tokenOverrides).toEqual({});
+	});
+
+	it('setBackground sets and clears the monitor background', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() =>
+			result.current.handleOp({ op: 'setBackground', spec: { kind: 'color', src: '#000' } })
+		);
+		expect(result.current.state.monitor.background).toEqual({ kind: 'color', src: '#000' });
+		act(() => result.current.handleOp({ op: 'setBackground', spec: undefined }));
+		expect(result.current.state.monitor.background).toBeUndefined();
+	});
+
+	it('per-widget token ops: setWidgetToken then clearWidgetTokens', () => {
+		const { result } = renderModel();
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const id = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'setWidgetToken', id, key: '--fg', value: '#fff' }));
+		const node1 = result.current.state.monitor.root.children.find((c) => c.id === id)!;
+		expect(isLeaf(node1) && node1.unit.tokens).toEqual({ '--fg': '#fff' });
+		act(() => result.current.handleOp({ op: 'clearWidgetTokens', id }));
+		const node2 = result.current.state.monitor.root.children.find((c) => c.id === id)!;
+		expect(isLeaf(node2) && node2.unit.tokens).toBeUndefined();
+	});
+
+	it('patchWidget / resetWidget / setBasis / setLeafAlign / setLeafBox edit a flow leaf', () => {
+		const { result } = renderModel();
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const id = result.current.state.selectedId!;
+
+		act(() => result.current.handleOp({ op: 'patchWidget', id, patch: { config: { custom: 1 } } }));
+		act(() => result.current.handleOp({ op: 'setBasis', id, basis: { fr: 2 } }));
+		act(() => result.current.handleOp({ op: 'setLeafAlign', id, halign: 'center', valign: 'top' }));
+		act(() => result.current.handleOp({ op: 'setLeafBox', id, field: 'pad', value: 7 }));
+		const node = result.current.state.monitor.root.children.find((c) => c.id === id)!;
+		expect(isLeaf(node) && (node.unit as WidgetInstance).config.custom).toBe(1);
+		expect(isLeaf(node) && node.basis).toEqual({ fr: 2 });
+		expect(isLeaf(node) && node.halign).toBe('center');
+		expect(isLeaf(node) && node.valign).toBe('top');
+		expect(isLeaf(node) && node.pad).toBe(7);
+
+		// resetWidget restores config back to the type defaults (custom key gone).
+		act(() => result.current.handleOp({ op: 'resetWidget', id }));
+		const reset = result.current.state.monitor.root.children.find((c) => c.id === id)!;
+		expect(isLeaf(reset) && (reset.unit as WidgetInstance).config.custom).toBeUndefined();
+	});
+
+	it('patchContainer / distributeEvenly edit a container; reparent moves a node into it', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.handleOp({ op: 'addContainer', kind: 'col' }));
+		const colId = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'patchContainer', id: colId, patch: { gap: 12 } }));
+		const colNode = result.current.state.monitor.root.children.find((c) => c.id === colId)!;
+		expect(isContainer(colNode) && colNode.gap).toBe(12);
+
+		// Add a widget then reparent it into the col, then distributeEvenly across the col.
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const wId = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'reparent', id: wId, containerId: colId }));
+		const col2 = result.current.state.monitor.root.children.find((c) => c.id === colId)!;
+		expect(isContainer(col2) && col2.children.map((c) => c.id)).toContain(wId);
+		act(() => result.current.handleOp({ op: 'distributeEvenly', containerId: colId }));
+		const col3 = result.current.state.monitor.root.children.find((c) => c.id === colId)!;
+		expect(isContainer(col3) && col3.children.every((c) => isLeaf(c) && c.basis)).toBe(true);
+	});
+
+	it('dropWidget / addBeside place containers/widgets next to a target', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.handleOp({ op: 'addContainer', kind: 'col' }));
+		const colId = result.current.state.selectedId!;
+		// dropWidget into the col.
+		act(() =>
+			result.current.handleOp({ op: 'dropWidget', containerId: colId, widgetType: 'text' })
+		);
+		const dropped = result.current.state.selectedId!;
+		const col = result.current.state.monitor.root.children.find((c) => c.id === colId)!;
+		expect(isContainer(col) && col.children.map((c) => c.id)).toContain(dropped);
+
+		// addBeside the col → a sibling under the root.
+		act(() => result.current.handleOp({ op: 'addBeside', id: colId, kind: 'row' }));
+		const besideId = result.current.state.selectedId!;
+		expect(result.current.state.monitor.root.children.map((c) => c.id)).toContain(besideId);
+	});
+
+	it('patchGroup edits a group; replaceNode swaps a node wholesale', () => {
+		const { result } = renderModel();
+		act(() => result.current.handleOp({ op: 'addWidget', widgetType: 'text' }));
+		const id = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'makeWidget', id }));
+		const grpId = result.current.state.selectedId!;
+		act(() => result.current.handleOp({ op: 'patchGroup', id: grpId, patch: { name: 'grpname' } }));
+		const grp = result.current.state.monitor.root.children.find((c) => c.id === grpId)!;
+		expect(isLeaf(grp) && isGroup(grp.unit) && grp.unit.name).toBe('grpname');
+
+		// replaceNode swaps the group leaf for a fresh primitive leaf at the same id.
+		const replacement = leaf(createWidget('text', grpId));
+		act(() => result.current.handleOp({ op: 'replaceNode', id: grpId, node: replacement }));
+		const swapped = result.current.state.monitor.root.children.find((c) => c.id === grpId)!;
+		expect(isLeaf(swapped) && isGroup(swapped.unit)).toBe(false);
+	});
+
+	it('endDefEdit via handleOp folds the open def back', () => {
+		const { result } = renderHook(() => useEditorModel(true, []));
+		act(() => result.current.dispatch({ type: 'newWidget' }));
+		expect(result.current.state.editingDefId).not.toBeNull();
+		act(() => result.current.handleOp({ op: 'endDefEdit' }));
+		expect(result.current.state.editingDefId).toBeNull();
+	});
+});
+
+describe('hook identity', () => {
+	it('seeds the monitor with the demo floating leaves and a fresh empty root', () => {
+		const seed = [leaf(createWidget('text', 'seed-1'))];
+		const { result } = renderHook(() => useEditorModel(false, seed));
+		expect(result.current.state.studio).toBe(false);
+		expect(result.current.state.monitor.floating.map((l) => l.id)).toEqual(['seed-1']);
+		expect(result.current.state.monitor.root.children).toEqual([]);
+	});
+
+	it('exposes a stable handleOp / commitOp / mutateNoSave across re-renders', () => {
+		const { result, rerender } = renderHook(() => useEditorModel(true, []));
+		const first = {
+			handleOp: result.current.handleOp,
+			commitOp: result.current.commitOp,
+			mutateNoSave: result.current.mutateNoSave
+		};
+		rerender();
+		expect(result.current.handleOp).toBe(first.handleOp);
+		expect(result.current.commitOp).toBe(first.commitOp);
+		expect(result.current.mutateNoSave).toBe(first.mutateNoSave);
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useKeyboard.test.ts b/client/src/lib/widgets/canvas/useKeyboard.test.ts
index 3cea93e..89b61b1 100644
--- a/client/src/lib/widgets/canvas/useKeyboard.test.ts
+++ b/client/src/lib/widgets/canvas/useKeyboard.test.ts
@@ -14,6 +14,7 @@ const handlers = {
 	'studio.delete': vi.fn()
 };
 const nudge = vi.fn();
+const gotoSection = vi.fn();
 
 const deps: KeyboardDeps = {
 	studio: true,
@@ -27,7 +28,8 @@ const deps: KeyboardDeps = {
 	}),
 	overrides: () => ({}),
 	handlers,
-	nudge
+	nudge,
+	gotoSection
 };
 
 function press(init: KeyboardEventInit, target?: EventTarget) {
@@ -43,6 +45,7 @@ beforeEach(() => {
 	state.previewing = false;
 	Object.values(handlers).forEach((h) => h.mockClear());
 	nudge.mockClear();
+	gotoSection.mockClear();
 });
 afterEach(() => vi.restoreAllMocks());
 
@@ -114,4 +117,65 @@ describe('useKeyboard registry dispatch', () => {
 		press({ key: ' ', code: 'Space' });
 		expect(result.current.spaceDown).toBe(true);
 	});
+
+	it('Ctrl+1..8 jumps to the matching section (0-based index)', () => {
+		renderHook(() => useKeyboard(deps));
+		press({ key: '1', code: 'Digit1', ctrlKey: true });
+		expect(gotoSection).toHaveBeenLastCalledWith(0);
+		press({ key: '8', code: 'Digit8', ctrlKey: true });
+		expect(gotoSection).toHaveBeenLastCalledWith(7);
+		expect(gotoSection).toHaveBeenCalledTimes(2);
+	});
+
+	it('a section chord with no gotoSection handler is a harmless no-op', () => {
+		// The section digit is in range but the Canvas didn't supply gotoSection (optional dep).
+		const { unmount } = renderHook(() => useKeyboard({ ...deps, gotoSection: undefined }));
+		expect(() => press({ key: '3', code: 'Digit3', ctrlKey: true })).not.toThrow();
+		expect(gotoSection).not.toHaveBeenCalled();
+		unmount();
+	});
+
+	it('Space pan mode is released on keyup', () => {
+		const { result } = renderHook(() => useKeyboard(deps));
+		press({ key: ' ', code: 'Space' });
+		expect(result.current.spaceDown).toBe(true);
+		act(() => {
+			window.dispatchEvent(new KeyboardEvent('keyup', { code: 'Space' }));
+		});
+		expect(result.current.spaceDown).toBe(false);
+		// A non-Space keyup is ignored (the guard's false branch).
+		act(() => {
+			window.dispatchEvent(new KeyboardEvent('keyup', { code: 'KeyA' }));
+		});
+		expect(result.current.spaceDown).toBe(false);
+	});
+
+	it('runs in the overlay (widget scope) when studio is false', () => {
+		// studio:false → ctx.scope === 'widget'; the global toggle-edit chord still dispatches there.
+		const overlayDeps: KeyboardDeps = {
+			...deps,
+			studio: false,
+			ctx: () => ({
+				studio: false,
+				editMode: true,
+				menuOpen: false,
+				dirty: false,
+				hasSelection: false,
+				previewing: false
+			})
+		};
+		const { unmount } = renderHook(() => useKeyboard(overlayDeps));
+		press({ key: 'e', code: 'KeyE', ctrlKey: true });
+		expect(handlers['global.toggleEdit']).toHaveBeenCalledTimes(1);
+		unmount();
+	});
+
+	it('does not steal Space pan-mode from a focused button', () => {
+		const { result } = renderHook(() => useKeyboard(deps));
+		const button = document.createElement('button');
+		document.body.appendChild(button);
+		press({ key: ' ', code: 'Space' }, button);
+		expect(result.current.spaceDown).toBe(false); // button keeps its own Space (activate)
+		button.remove();
+	});
 });
diff --git a/client/src/lib/widgets/canvas/usePaneSizes.test.ts b/client/src/lib/widgets/canvas/usePaneSizes.test.ts
index 737b867..ce524d1 100644
--- a/client/src/lib/widgets/canvas/usePaneSizes.test.ts
+++ b/client/src/lib/widgets/canvas/usePaneSizes.test.ts
@@ -1,5 +1,9 @@
-import { describe, it, expect } from 'vitest';
-import { clampPane, applyDelta, PANE_DEFAULTS } from './usePaneSizes';
+import { beforeEach, describe, it, expect } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import type { PointerEvent as ReactPointerEvent } from 'react';
+import { clampPane, applyDelta, PANE_DEFAULTS, usePaneSizes, type Edge } from './usePaneSizes';
+
+const KEY = 'widgetsack.studio.panes';
 
 describe('clampPane', () => {
 	it('clamps each edge to its limits and rounds', () => {
@@ -35,3 +39,114 @@ describe('applyDelta', () => {
 		expect(applyDelta(PANE_DEFAULTS, 'left', 500, 999).railL).toBe(520);
 	});
 });
+
+describe('usePaneSizes', () => {
+	beforeEach(() => localStorage.clear());
+
+	// A React-pointer-event-shaped object for startResize.
+	const reactDown = (clientX: number): ReactPointerEvent => {
+		const e = { clientX, preventDefault: () => undefined };
+		return e as unknown as ReactPointerEvent;
+	};
+
+	it('overlay role uses defaults and emits no inline vars', () => {
+		const { result } = renderHook(() => usePaneSizes(false));
+		expect(result.current.vars).toEqual({});
+	});
+
+	it('studio role seeds from defaults and exposes inline CSS vars', () => {
+		const { result } = renderHook(() => usePaneSizes(true));
+		expect(result.current.vars).toEqual({
+			'--rail-l': '250px',
+			'--rail-r': '264px',
+			'--tree-w': '200px'
+		});
+	});
+
+	it('studio role loads + clamps persisted sizes (ignoring bad fields)', () => {
+		localStorage.setItem(
+			KEY,
+			JSON.stringify({ railL: 9999, railR: 'nope', treeW: 150 }) // railL over max, railR wrong type
+		);
+		const { result } = renderHook(() => usePaneSizes(true));
+		expect(result.current.vars).toEqual({
+			'--rail-l': '520px', // clamped to max
+			'--rail-r': '264px', // non-number → default
+			'--tree-w': '150px'
+		});
+	});
+
+	it('studio role loads all-valid persisted numbers verbatim (within range)', () => {
+		localStorage.setItem(KEY, JSON.stringify({ railL: 300, railR: 320, treeW: 160 }));
+		const { result } = renderHook(() => usePaneSizes(true));
+		expect(result.current.vars).toEqual({
+			'--rail-l': '300px',
+			'--rail-r': '320px',
+			'--tree-w': '160px'
+		});
+	});
+
+	it('studio role falls back per-field when a number is missing/wrong type', () => {
+		localStorage.setItem(KEY, JSON.stringify({ railR: 300 })); // railL + treeW absent → defaults
+		const { result } = renderHook(() => usePaneSizes(true));
+		expect(result.current.vars).toEqual({
+			'--rail-l': '250px',
+			'--rail-r': '300px',
+			'--tree-w': '200px'
+		});
+	});
+
+	it('a divider drag updates the matching var and persists on pointerup', () => {
+		const { result } = renderHook(() => usePaneSizes(true));
+
+		act(() => result.current.startResize('left', reactDown(100)));
+		act(() => {
+			window.dispatchEvent(new MouseEvent('pointermove', { clientX: 140 }));
+		});
+		// 250 (start) + 40 (dx) = 290.
+		expect(result.current.vars['--rail-l' as keyof typeof result.current.vars]).toBe('290px');
+
+		act(() => {
+			window.dispatchEvent(new MouseEvent('pointerup'));
+		});
+		// Persisted on release.
+		expect(JSON.parse(localStorage.getItem(KEY)!).railL).toBe(290);
+
+		// Listeners removed: a further move after pointerup does nothing.
+		act(() => {
+			window.dispatchEvent(new MouseEvent('pointermove', { clientX: 999 }));
+		});
+		expect(result.current.vars['--rail-l' as keyof typeof result.current.vars]).toBe('290px');
+	});
+
+	it('the right rail grows as its divider moves left (-dx)', () => {
+		const { result } = renderHook(() => usePaneSizes(true));
+		act(() => result.current.startResize('right', reactDown(200)));
+		act(() => {
+			window.dispatchEvent(new MouseEvent('pointermove', { clientX: 150 })); // dx -50
+		});
+		// 264 - (-50)?? right grows by -dx → 264 + 50 = 314.
+		expect(result.current.vars['--rail-r' as keyof typeof result.current.vars]).toBe('314px');
+	});
+
+	it('drags the tree column too (covers the tree startVal branch)', () => {
+		const { result } = renderHook(() => usePaneSizes(true));
+		act(() => result.current.startResize('tree', reactDown(0) as ReactPointerEvent));
+		act(() => {
+			window.dispatchEvent(new MouseEvent('pointermove', { clientX: 30 }));
+		});
+		expect(result.current.vars['--tree-w' as keyof typeof result.current.vars]).toBe('230px');
+	});
+
+	it('all three edges resolve a start value', () => {
+		const { result } = renderHook(() => usePaneSizes(true));
+		// Sanity: starting a resize on each edge does not throw and persists on release.
+		for (const edge of ['left', 'tree', 'right'] as Edge[]) {
+			act(() => result.current.startResize(edge, reactDown(0)));
+			act(() => {
+				window.dispatchEvent(new MouseEvent('pointerup'));
+			});
+		}
+		expect(localStorage.getItem(KEY)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/canvas/usePersistence.test.ts b/client/src/lib/widgets/canvas/usePersistence.test.ts
new file mode 100644
index 0000000..3b74cb4
--- /dev/null
+++ b/client/src/lib/widgets/canvas/usePersistence.test.ts
@@ -0,0 +1,478 @@
+// usePersistence is the one disk-touching seam, but it's not *just* glue: persistToDisk /
+// writeBaseline assemble the widgets.json object from the live editor state with real branch logic
+// (theme lock placement, the mid-def-edit library fold, the cross-monitor `extras` merge, the
+// conditional theme/themeLock/tokens fields) and re-read + merge the OTHER monitors off disk. We
+// mock only the Tauri `invoke` adapter, then assert the exact JSON handed to save_layout and the
+// success/failure boolean contract. The debounce timer is driven with fake timers.
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { usePersistence } from './usePersistence';
+import { COMMANDS } from '../../bridge/contract';
+import { container, leaf, type Library, type MonitorLayout } from '../../core/layoutTree';
+import { createWidget } from '../../core/widget';
+import type { Baseline, EditorState, Extra } from './types';
+
+// One mocked Tauri command surface for the whole file. invoke(loadLayout) returns whatever
+// `loadLayoutRaw` is set to (the on-disk file); invoke(saveLayout) records its args and resolves
+// (or rejects when `saveRejects`) so we can read back the written JSON + the resolved boolean.
+const invoke = vi.fn();
+vi.mock('@tauri-apps/api/core', () => ({
+	invoke: (...args: unknown[]) => invoke(...args)
+}));
+
+let loadLayoutRaw: string | null = null;
+let saveRejects = false;
+let savedContents: string | null = null;
+
+beforeEach(() => {
+	loadLayoutRaw = null;
+	saveRejects = false;
+	savedContents = null;
+	invoke.mockReset();
+	invoke.mockImplementation(async (cmd: string, args?: { contents?: string }) => {
+		if (cmd === COMMANDS.loadLayout) return loadLayoutRaw;
+		if (cmd === COMMANDS.saveLayout) {
+			if (saveRejects) throw new Error('save_layout rejected');
+			savedContents = args?.contents ?? null;
+			return undefined;
+		}
+		throw new Error(`unexpected command ${cmd}`);
+	});
+});
+afterEach(() => {
+	vi.useRealTimers();
+});
+
+// The parsed object handed to save_layout (the last write).
+function written(): Record<string, unknown> {
+	expect(savedContents).not.toBeNull();
+	return JSON.parse(savedContents!) as Record<string, unknown>;
+}
+
+// A monitor with one docked text widget.
+function monitorWith(id = 'w1'): MonitorLayout {
+	return {
+		root: container('root', 'col', [leaf(createWidget('text', id))], { align: 'stretch' }),
+		floating: []
+	};
+}
+
+// A minimal EditorState — only the persistence-relevant slice is read by the hook.
+function editorState(over: Partial<EditorState> = {}): EditorState {
+	return {
+		monitor: monitorWith(),
+		library: undefined,
+		selectedId: null,
+		selectedIds: [],
+		lastPrimary: null,
+		selectedTheme: '',
+		themeLock: true,
+		tokenOverrides: {},
+		editingDefId: null,
+		savedMonitor: null,
+		defEditBaseline: null,
+		previewDef: null,
+		undoStack: [],
+		redoStack: [],
+		lastSnap: null,
+		historyReady: true,
+		savedBaseline: null,
+		pendingExtras: [],
+		saveSeq: 0,
+		studio: true,
+		...over
+	};
+}
+
+describe('persistToDisk — widgets.json assembly', () => {
+	it('writes version 2 + this monitor under its key, and omits theme/library/tokens when bare', async () => {
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		let ok = false;
+		await act(async () => {
+			ok = await result.current.persistToDisk([]);
+		});
+		expect(ok).toBe(true);
+		const out = written();
+		expect(out.version).toBe(2);
+		// LOCKED + no selected theme + no tokens + no library → only version + monitors are written.
+		expect(out).not.toHaveProperty('theme');
+		expect(out).not.toHaveProperty('themeLock');
+		expect(out).not.toHaveProperty('tokens');
+		expect(out).not.toHaveProperty('library');
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect(Object.keys(monitors)).toEqual(['mon-A']);
+		// A locked theme strips any per-monitor `theme` field off the record.
+		expect(monitors['mon-A']).not.toHaveProperty('theme');
+	});
+
+	it('LOCKED: the selection becomes the GLOBAL theme and the monitor record carries none', async () => {
+		const { result } = renderHook(() =>
+			usePersistence(editorState({ themeLock: true, selectedTheme: 'builtin:nord' }), 'mon-A')
+		);
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const out = written();
+		expect(out.theme).toBe('builtin:nord');
+		expect(out).not.toHaveProperty('themeLock'); // absent ⇒ locked (the default)
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-A']).not.toHaveProperty('theme');
+	});
+
+	it('UNLOCKED: the selection pins onto THIS monitor and themeLock:false is written', async () => {
+		const { result } = renderHook(() =>
+			usePersistence(editorState({ themeLock: false, selectedTheme: 'mytheme' }), 'mon-A')
+		);
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const out = written();
+		expect(out.themeLock).toBe(false);
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect((monitors['mon-A'] as MonitorLayout).theme).toBe('mytheme');
+		// The selection is NOT promoted to the global theme when unlocked (none on disk → none global).
+		expect(out).not.toHaveProperty('theme');
+	});
+
+	it('writes library + tokens when present', async () => {
+		const library: Library = { version: 1, defs: [] };
+		const { result } = renderHook(() =>
+			usePersistence(editorState({ library, tokenOverrides: { '--accent': '#f00' } }), 'mon-A')
+		);
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const out = written();
+		expect(out.library).toEqual(library);
+		expect(out.tokens).toEqual({ '--accent': '#f00' });
+	});
+
+	it('merges the OTHER monitors + library + global theme already on disk', async () => {
+		// The file already holds monitor mon-B, a library, and a global theme; persistToDisk must
+		// re-read and preserve them while replacing only mon-A.
+		const fileLib: Library = { version: 1, defs: [] };
+		loadLayoutRaw = JSON.stringify({
+			version: 2,
+			monitors: { 'mon-B': monitorWith('other') },
+			library: fileLib,
+			theme: 'builtin:dark'
+		});
+		// Unlocked here so the GLOBAL theme falls back to the file's existing global (inherit-default).
+		const { result } = renderHook(() => usePersistence(editorState({ themeLock: false }), 'mon-A'));
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const out = written();
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect(Object.keys(monitors).sort()).toEqual(['mon-A', 'mon-B']);
+		expect(out.library).toEqual(fileLib); // editor had no library → fell back to the file's
+		expect(out.theme).toBe('builtin:dark'); // unlocked → keep the file's global as inherit-default
+	});
+
+	it('appends a cross-monitor `extra` leaf onto its target monitor without clobbering this one', async () => {
+		const extras: Extra[] = [{ key: 'mon-B', leaf: leaf(createWidget('text', 'moved')) }];
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.persistToDisk(extras);
+		});
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-A']).toBeDefined();
+		expect(monitors['mon-B'].floating?.map((l) => l.id)).toEqual(['moved']);
+	});
+
+	it('an extra whose key === this monitor is skipped (no double-append)', async () => {
+		const extras: Extra[] = [{ key: 'mon-A', leaf: leaf(createWidget('text', 'dup')) }];
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.persistToDisk(extras);
+		});
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		// mon-A is the editor's own monitor (one widget), NOT the extra'd one.
+		expect(monitors['mon-A'].root.children.map((c) => c.id)).toEqual(['w1']);
+	});
+
+	it('mid def-edit: folds the in-progress def child back into the library and persists the REAL monitor', async () => {
+		const editingChild = container('def-root', 'row', [leaf(createWidget('text', 'inner'))]);
+		const library: Library = {
+			version: 1,
+			defs: [{ id: 'd1', name: 'D1', size: { w: 200, h: 100 }, child: container('old', 'col', []) }]
+		};
+		const realMonitor = monitorWith('real-widget');
+		const { result } = renderHook(() =>
+			usePersistence(
+				editorState({
+					editingDefId: 'd1',
+					library,
+					monitor: { root: editingChild, floating: [] }, // the scoped editing tree
+					savedMonitor: realMonitor // the real layout to persist
+				}),
+				'mon-A'
+			)
+		);
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const out = written();
+		const outLib = out.library as Library;
+		// The def's child was replaced with the scoped editing tree…
+		expect(outLib.defs[0].child).toEqual(editingChild);
+		// …and the REAL monitor (savedMonitor), not the scoped tree, is what got written.
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-A'].root.children.map((c) => c.id)).toEqual(['real-widget']);
+	});
+
+	it('folds only the matching def, leaving sibling defs untouched', async () => {
+		const editingChild = container('def-root', 'row', []);
+		const sibling = {
+			id: 'd2',
+			name: 'D2',
+			size: { w: 10, h: 10 },
+			child: container('s', 'col', [])
+		};
+		const library: Library = {
+			version: 1,
+			defs: [
+				{ id: 'd1', name: 'D1', size: { w: 1, h: 1 }, child: container('old', 'col', []) },
+				sibling
+			]
+		};
+		const { result } = renderHook(() =>
+			usePersistence(
+				editorState({
+					editingDefId: 'd1',
+					library,
+					monitor: { root: editingChild, floating: [] },
+					savedMonitor: monitorWith('real')
+				}),
+				'mon-A'
+			)
+		);
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const outLib = written().library as Library;
+		expect(outLib.defs[0].child).toEqual(editingChild); // d1 folded
+		expect(outLib.defs[1]).toEqual(sibling); // d2 passed through unchanged
+	});
+
+	it('appends an extra alongside the on-disk monitor’s EXISTING floating leaves', async () => {
+		// mon-B already has a floating leaf on disk → the extra is appended after it (no clobber).
+		loadLayoutRaw = JSON.stringify({
+			version: 2,
+			monitors: {
+				'mon-B': {
+					root: container('root', 'col', []),
+					floating: [leaf(createWidget('text', 'pre'))]
+				}
+			}
+		});
+		const extras: Extra[] = [{ key: 'mon-B', leaf: leaf(createWidget('text', 'added')) }];
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.persistToDisk(extras);
+		});
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-B'].floating?.map((l) => l.id)).toEqual(['pre', 'added']);
+	});
+
+	it('appends an extra onto an on-disk monitor that has no `floating` field', async () => {
+		// The on-disk mon-B record omits `floating` → the `?? []` guard must synthesize the array.
+		loadLayoutRaw = JSON.stringify({
+			version: 2,
+			monitors: { 'mon-B': { root: container('root', 'col', []) } }
+		});
+		const extras: Extra[] = [{ key: 'mon-B', leaf: leaf(createWidget('text', 'late')) }];
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.persistToDisk(extras);
+		});
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-B'].floating?.map((l) => l.id)).toEqual(['late']);
+	});
+
+	it('returns false when save_layout rejects (the caller must not mark it saved)', async () => {
+		saveRejects = true;
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		let ok = true;
+		await act(async () => {
+			ok = await result.current.persistToDisk([]);
+		});
+		expect(ok).toBe(false);
+		warn.mockRestore();
+	});
+
+	it('survives a load_layout that throws / returns garbage and still writes a fresh monitors map', async () => {
+		// loadLayout rejects → the catch falls back to an empty monitors map (no other monitors).
+		invoke.mockImplementation(async (cmd: string, args?: { contents?: string }) => {
+			if (cmd === COMMANDS.loadLayout) throw new Error('disk read failed');
+			if (cmd === COMMANDS.saveLayout) {
+				savedContents = args?.contents ?? null;
+				return undefined;
+			}
+		});
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.persistToDisk([]);
+		});
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(Object.keys(monitors)).toEqual(['mon-A']);
+	});
+});
+
+describe('writeBaseline — revert path', () => {
+	function baseline(over: Partial<Baseline> = {}): Baseline {
+		return {
+			monitor: monitorWith('base'),
+			library: undefined,
+			theme: '',
+			themeLock: true,
+			tokens: {},
+			...over
+		};
+	}
+
+	it('writes the baseline values for THIS monitor while preserving the file’s other monitors', async () => {
+		loadLayoutRaw = JSON.stringify({
+			version: 2,
+			monitors: { 'mon-B': monitorWith('keepme') }
+		});
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		let ok = false;
+		await act(async () => {
+			ok = await result.current.writeBaseline(baseline(), 'mon-A');
+		});
+		expect(ok).toBe(true);
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-A'].root.children.map((c) => c.id)).toEqual(['base']);
+		expect(monitors['mon-B'].root.children.map((c) => c.id)).toEqual(['keepme']);
+	});
+
+	it('UNLOCKED baseline pins its theme on the monitor record + writes themeLock:false', async () => {
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.writeBaseline(
+				baseline({ themeLock: false, theme: 'btheme', tokens: { '--x': '1' } }),
+				'mon-A'
+			);
+		});
+		const out = written();
+		expect(out.themeLock).toBe(false);
+		expect(out.tokens).toEqual({ '--x': '1' });
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect((monitors['mon-A'] as MonitorLayout).theme).toBe('btheme');
+	});
+
+	it('LOCKED baseline promotes its theme to the global theme + strips it off the record', async () => {
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.writeBaseline(
+				baseline({ themeLock: true, theme: 'builtin:nord', library: { version: 1, defs: [] } }),
+				'mon-A'
+			);
+		});
+		const out = written();
+		expect(out.theme).toBe('builtin:nord');
+		expect(out).not.toHaveProperty('themeLock');
+		const monitors = out.monitors as Record<string, MonitorLayout>;
+		expect(monitors['mon-A']).not.toHaveProperty('theme');
+		expect(out.library).toEqual({ version: 1, defs: [] });
+	});
+
+	it('LOCKED baseline with no theme inherits the file’s existing global theme', async () => {
+		// The file already has a string global theme; a locked baseline whose own theme is '' must keep
+		// the file's as the global (b.theme || fileTheme).
+		loadLayoutRaw = JSON.stringify({
+			version: 2,
+			monitors: { 'mon-A': monitorWith() },
+			theme: 'builtin:dracula'
+		});
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.writeBaseline(baseline({ themeLock: true, theme: '' }), 'mon-A');
+		});
+		expect(written().theme).toBe('builtin:dracula');
+	});
+
+	it('returns false when save_layout rejects', async () => {
+		saveRejects = true;
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		let ok = true;
+		await act(async () => {
+			ok = await result.current.writeBaseline(baseline(), 'mon-A');
+		});
+		expect(ok).toBe(false);
+		warn.mockRestore();
+	});
+
+	it('falls back to an empty monitors map when the load read throws', async () => {
+		invoke.mockImplementation(async (cmd: string, args?: { contents?: string }) => {
+			if (cmd === COMMANDS.loadLayout) throw new Error('read failed');
+			savedContents = args?.contents ?? null;
+			return undefined;
+		});
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		await act(async () => {
+			await result.current.writeBaseline(baseline(), 'mon-A');
+		});
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(Object.keys(monitors)).toEqual(['mon-A']);
+	});
+});
+
+describe('debounced preview write', () => {
+	it('schedulePreviewWrite fires a persistToDisk ~150ms later', async () => {
+		vi.useFakeTimers();
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		act(() => result.current.schedulePreviewWrite());
+		expect(savedContents).toBeNull(); // nothing written yet
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(160);
+		});
+		expect(savedContents).not.toBeNull();
+		const monitors = written().monitors as Record<string, MonitorLayout>;
+		expect(Object.keys(monitors)).toEqual(['mon-A']);
+	});
+
+	it('clearPreviewWrite cancels a pending write', async () => {
+		vi.useFakeTimers();
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		act(() => result.current.schedulePreviewWrite());
+		act(() => result.current.clearPreviewWrite());
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(300);
+		});
+		expect(savedContents).toBeNull();
+	});
+
+	it('a second schedule debounces the first (only one write fires)', async () => {
+		vi.useFakeTimers();
+		const { result } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		act(() => result.current.schedulePreviewWrite());
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(100); // not yet
+		});
+		act(() => result.current.schedulePreviewWrite()); // resets the timer
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(100); // 100ms after the RESET → still pending
+		});
+		const saveCalls = () => invoke.mock.calls.filter((c) => c[0] === COMMANDS.saveLayout).length;
+		expect(saveCalls()).toBe(0);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(100); // now past 150 from the reset
+		});
+		expect(saveCalls()).toBe(1);
+	});
+
+	it('clears the pending preview write on unmount', async () => {
+		vi.useFakeTimers();
+		const { result, unmount } = renderHook(() => usePersistence(editorState(), 'mon-A'));
+		act(() => result.current.schedulePreviewWrite());
+		unmount();
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(300);
+		});
+		expect(savedContents).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useSacks.test.ts b/client/src/lib/widgets/canvas/useSacks.test.ts
index 31bc563..acf0875 100644
--- a/client/src/lib/widgets/canvas/useSacks.test.ts
+++ b/client/src/lib/widgets/canvas/useSacks.test.ts
@@ -1,5 +1,16 @@
-import { describe, expect, it } from 'vitest';
-import { sackSummary } from './useSacks';
+// useSacks owns the sacks/ + themes/ file I/O around the pure pack/unpack core, plus real branch
+// logic worth pinning: the refreshSacks peek-mapping (def count / theme / token / unreadable null),
+// the mid-def-edit export+import guards, the CSS-threat confirm gate, the theme name-collision
+// (-imported) resolution, and the SINGLE import commit patch. We mock only the overlay adapter +
+// window prompts, keep the real sack/cssThreats/mergeLibrary core, and assert observable effects.
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { sackSummary, useSacks } from './useSacks';
+import { packSack } from '../../core/sack';
+import type { Library } from '../../core/layoutTree';
+import { container } from '../../core/layoutTree';
+import type { EditorState } from './types';
+import type { Themes } from './useThemes';
 
 describe('sackSummary', () => {
 	it('joins widgets, theme, and overrides with middots (singular/plural aware)', () => {
@@ -18,3 +29,315 @@ describe('sackSummary', () => {
 		);
 	});
 });
+
+// --- the hook itself ---
+
+const listSacks = vi.fn<() => Promise<string[]>>();
+const readSack = vi.fn<(name: string) => Promise<string | null>>();
+const writeSack = vi.fn<(name: string, json: string) => Promise<string | null>>();
+const listThemes = vi.fn<() => Promise<string[]>>();
+const resolveThemeCss = vi.fn<(id: string) => Promise<string>>();
+const saveThemeCss = vi.fn<(name: string, css: string) => Promise<void>>();
+vi.mock('../../overlay', () => ({
+	listSacks: (...a: []) => listSacks(...a),
+	readSack: (...a: [string]) => readSack(...a),
+	writeSack: (...a: [string, string]) => writeSack(...a),
+	listThemes: (...a: []) => listThemes(...a),
+	resolveThemeCss: (...a: [string]) => resolveThemeCss(...a),
+	saveThemeCss: (...a: [string, string]) => saveThemeCss(...a)
+}));
+
+const themeLabel = vi.fn((n: string) => n || '(default)');
+const setThemeList = vi.fn<(names: string[]) => void>();
+const adoptTheme = vi.fn<(name: string) => Promise<void>>();
+
+// A library with one def (so packSack keeps it).
+function libWith(id = 'd1'): Library {
+	return {
+		version: 1,
+		defs: [{ id, name: id, size: { w: 100, h: 60 }, child: container('c', 'col', []) }]
+	};
+}
+
+type Opts = {
+	navSection?: 'sacks' | 'settings';
+	editingDefId?: string | null;
+	selectedTheme?: string;
+	library?: Library | undefined;
+	tokenOverrides?: Record<string, string>;
+};
+function setup(opts: Opts = {}) {
+	const commitOp = vi.fn<(run: (s: EditorState) => Partial<EditorState>) => void>();
+	const themes: Pick<Themes, 'themeLabel' | 'setThemeList' | 'adoptTheme'> = {
+		themeLabel,
+		setThemeList,
+		adoptTheme
+	};
+	const hook = renderHook(() =>
+		useSacks({
+			studio: true,
+			navSection: opts.navSection ?? 'sacks',
+			editingDefId: opts.editingDefId ?? null,
+			selectedTheme: opts.selectedTheme ?? '',
+			library: 'library' in opts ? opts.library : undefined,
+			tokenOverrides: opts.tokenOverrides ?? {},
+			commitOp,
+			themes
+		})
+	);
+	return { ...hook, commitOp };
+}
+
+beforeEach(() => {
+	vi.restoreAllMocks();
+	listSacks.mockReset().mockResolvedValue([]);
+	readSack.mockReset().mockResolvedValue(null);
+	writeSack.mockReset().mockResolvedValue('C:/cfg/sacks/x.sack.json');
+	listThemes.mockReset().mockResolvedValue([]);
+	resolveThemeCss.mockReset().mockResolvedValue('');
+	saveThemeCss.mockReset().mockResolvedValue(undefined);
+	themeLabel.mockClear();
+	setThemeList.mockClear();
+	adoptTheme.mockClear();
+});
+
+describe('refreshSacks (section-open peek)', () => {
+	it('summarizes each sack: def count, theme name, token count — and flags unreadable files', async () => {
+		listSacks.mockResolvedValue(['good', 'bad']);
+		readSack.mockImplementation(async (name: string) =>
+			name === 'good'
+				? JSON.stringify(
+						packSack({
+							name: 'good',
+							library: libWith(),
+							theme: { name: 'Nord', css: 'x' },
+							tokens: { '--a': '1', '--b': '2' }
+						})
+				  )
+				: 'not a sack'
+		);
+		const { result } = setup({ navSection: 'sacks' });
+		await waitFor(() => expect(result.current.sackInfos).toHaveLength(2));
+		const byName = Object.fromEntries(result.current.sackInfos.map((i) => [i.name, i]));
+		expect(byName.good).toEqual({ name: 'good', widgets: 1, theme: 'Nord', tokens: 2 });
+		// A file that doesn't parse as a sack → widgets:null (renders as "unreadable").
+		expect(byName.bad).toEqual({ name: 'bad', widgets: null, theme: null, tokens: 0 });
+	});
+
+	it('reports zeros for a sack with no library/theme/tokens', async () => {
+		listSacks.mockResolvedValue(['empty']);
+		readSack.mockResolvedValue(JSON.stringify(packSack({ name: 'empty' })));
+		const { result } = setup();
+		await waitFor(() => expect(result.current.sackInfos).toHaveLength(1));
+		expect(result.current.sackInfos[0]).toEqual({
+			name: 'empty',
+			widgets: 0,
+			theme: null,
+			tokens: 0
+		});
+	});
+
+	it('flags a sack whose file read returns null as unreadable', async () => {
+		listSacks.mockResolvedValue(['missing']);
+		readSack.mockResolvedValue(null);
+		const { result } = setup();
+		await waitFor(() => expect(result.current.sackInfos).toHaveLength(1));
+		expect(result.current.sackInfos[0]).toEqual({
+			name: 'missing',
+			widgets: null,
+			theme: null,
+			tokens: 0
+		});
+	});
+
+	it('does not load while a different section is open', async () => {
+		setup({ navSection: 'settings' });
+		expect(listSacks).not.toHaveBeenCalled();
+	});
+});
+
+describe('exportSack', () => {
+	it('refuses (alerts) mid def-edit', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		const { result } = setup({ editingDefId: 'd1', navSection: 'settings' });
+		await act(async () => {
+			await result.current.exportSack();
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Finish editing'));
+		expect(writeSack).not.toHaveBeenCalled();
+	});
+
+	it('aborts when the name prompt is cancelled', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue(null);
+		const { result } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.exportSack();
+		});
+		expect(writeSack).not.toHaveBeenCalled();
+	});
+
+	it('packs library + resolved theme CSS + tokens, writes, and alerts the saved path', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('my-sack');
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		resolveThemeCss.mockResolvedValue(':root{--np-accent:#abc}');
+		themeLabel.mockReturnValue('Nord');
+		writeSack.mockResolvedValue('C:/cfg/sacks/my-sack.sack.json');
+		const lib = libWith();
+		const { result } = setup({
+			navSection: 'settings',
+			selectedTheme: 'builtin:nord',
+			library: lib,
+			tokenOverrides: { '--x': '1' }
+		});
+		await act(async () => {
+			await result.current.exportSack();
+		});
+		expect(resolveThemeCss).toHaveBeenCalledWith('builtin:nord');
+		const [name, json] = writeSack.mock.calls[0];
+		expect(name).toBe('my-sack');
+		const sack = JSON.parse(json);
+		expect(sack.library).toEqual(lib);
+		expect(sack.theme).toEqual({ name: 'Nord', css: ':root{--np-accent:#abc}' });
+		expect(sack.tokens).toEqual({ '--x': '1' });
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('C:/cfg/sacks/my-sack.sack.json'));
+	});
+
+	it('omits the theme (no resolve) when nothing is selected, and skips the path alert when write returns null', async () => {
+		const prompt = vi.spyOn(window, 'prompt').mockReturnValue('plain');
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		writeSack.mockResolvedValue(null); // write produced no path
+		themeLabel.mockReturnValue(''); // empty label → prompt falls back to the 'my-sack' default
+		const { result } = setup({ navSection: 'settings', selectedTheme: '' });
+		await act(async () => {
+			await result.current.exportSack();
+		});
+		expect(resolveThemeCss).not.toHaveBeenCalled();
+		expect(JSON.parse(writeSack.mock.calls[0][1]).theme).toBeUndefined();
+		expect(prompt).toHaveBeenCalledWith(expect.any(String), 'my-sack'); // the || fallback default
+		expect(alert).not.toHaveBeenCalled(); // no path → no "Saved sack" alert
+	});
+});
+
+describe('importSack', () => {
+	it('refuses (alerts) mid def-edit', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		const { result, commitOp } = setup({ editingDefId: 'd1', navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Finish editing'));
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('alerts and bails on an unreadable sack', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		readSack.mockResolvedValue('garbage');
+		const { result, commitOp } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Could not read'));
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('also bails when readSack returns null', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		readSack.mockResolvedValue(null);
+		const { result, commitOp } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('gone');
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Could not read'));
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('merges library + tokens + theme through ONE commit and live-applies the theme', async () => {
+		const sack = packSack({
+			name: 's',
+			library: libWith('imp'),
+			theme: { name: 'Imported', css: ':root{}' },
+			tokens: { '--t': '9' }
+		});
+		readSack.mockResolvedValue(JSON.stringify(sack));
+		listThemes.mockResolvedValue([]); // no collision
+		const { result, commitOp } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		// The theme was written under its own (uncollided) name + the picker list refreshed.
+		expect(saveThemeCss).toHaveBeenCalledWith('Imported', ':root{}');
+		expect(setThemeList).toHaveBeenCalled();
+		// ONE commit carries the merged library + tokens + selected theme.
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		const patch = commitOp.mock.calls[0][0]({
+			library: undefined,
+			tokenOverrides: {}
+		} as EditorState);
+		expect(patch.library?.defs.map((d) => d.id)).toEqual(['imp']);
+		expect(patch.tokenOverrides).toEqual({ '--t': '9' });
+		expect(patch.selectedTheme).toBe('Imported');
+		// Live-apply mirrored the committed selection onto the live CSS.
+		expect(adoptTheme).toHaveBeenCalledWith('Imported');
+	});
+
+	it('resolves a theme-name collision by suffixing -imported', async () => {
+		const sack = packSack({ name: 's', theme: { name: 'Nord', css: ':root{}' } });
+		readSack.mockResolvedValue(JSON.stringify(sack));
+		listThemes.mockResolvedValue(['Nord']); // collision!
+		const { result } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		expect(saveThemeCss).toHaveBeenCalledWith('Nord-imported', ':root{}');
+		expect(adoptTheme).toHaveBeenCalledWith('Nord-imported');
+	});
+
+	it('confirms before importing a theme whose CSS contains threats; declining aborts everything', async () => {
+		const sack = packSack({
+			name: 's',
+			theme: { name: 'Evil', css: '@import url(https://evil.example/x.css);' }
+		});
+		readSack.mockResolvedValue(JSON.stringify(sack));
+		const confirm = vi.spyOn(window, 'confirm').mockReturnValue(false);
+		const { result, commitOp } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		expect(confirm).toHaveBeenCalled();
+		expect(saveThemeCss).not.toHaveBeenCalled();
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('proceeds when the threat confirm is accepted', async () => {
+		const sack = packSack({
+			name: 's',
+			theme: { name: 'Risky', css: '@import url(https://evil.example/x.css);' }
+		});
+		readSack.mockResolvedValue(JSON.stringify(sack));
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		listThemes.mockResolvedValue([]);
+		const { result, commitOp } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		expect(saveThemeCss).toHaveBeenCalledWith('Risky', expect.any(String));
+		expect(commitOp).toHaveBeenCalledTimes(1);
+	});
+
+	it('imports a themeless sack: commit applies only library/tokens, no theme adopt', async () => {
+		const sack = packSack({ name: 's', library: libWith('only'), tokens: { '--z': '0' } });
+		readSack.mockResolvedValue(JSON.stringify(sack));
+		const { result, commitOp } = setup({ navSection: 'settings' });
+		await act(async () => {
+			await result.current.importSack('s');
+		});
+		expect(saveThemeCss).not.toHaveBeenCalled();
+		expect(adoptTheme).not.toHaveBeenCalled();
+		const patch = commitOp.mock.calls[0][0]({
+			library: undefined,
+			tokenOverrides: {}
+		} as EditorState);
+		expect(patch.selectedTheme).toBeUndefined();
+		expect(patch.library?.defs.map((d) => d.id)).toEqual(['only']);
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useSavedLayouts.test.ts b/client/src/lib/widgets/canvas/useSavedLayouts.test.ts
new file mode 100644
index 0000000..a72e0b7
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useSavedLayouts.test.ts
@@ -0,0 +1,222 @@
+// useSavedLayouts owns the layouts/ file I/O AROUND the pure pack/unpack core, but it has real
+// branch logic worth pinning: the mid-def-edit guards, the overwrite-confirm, the name trim/empty
+// guard, the save-failure alert, and the load confirm → single commit (which clears selection). We
+// mock the overlay adapter + window prompts, keep the real packLayout/unpackLayout, and assert the
+// observable effects (what got written, what the commit patch was, which alert fired).
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { useSavedLayouts } from './useSavedLayouts';
+import { container, leaf, type MonitorLayout } from '../../core/layoutTree';
+import { createWidget } from '../../core/widget';
+import { packLayout } from '../../core/savedLayout';
+import type { EditorState } from './types';
+
+const listLayouts = vi.fn<() => Promise<string[]>>();
+const readLayout = vi.fn<(name: string) => Promise<string | null>>();
+const saveLayoutAs = vi.fn<(name: string, json: string) => Promise<string | null>>();
+const deleteLayout = vi.fn<(name: string) => Promise<boolean>>();
+vi.mock('../../overlay', () => ({
+	listLayouts: (...a: []) => listLayouts(...a),
+	readLayout: (...a: [string]) => readLayout(...a),
+	saveLayoutAs: (...a: [string, string]) => saveLayoutAs(...a),
+	deleteLayout: (...a: [string]) => deleteLayout(...a)
+}));
+
+function monitorWith(id = 'w1'): MonitorLayout {
+	return { root: container('root', 'col', [leaf(createWidget('text', id))]), floating: [] };
+}
+
+// The hook only reads `monitorRef` + the four scalar deps; build a minimal harness.
+type Opts = {
+	navSection?: 'saved-layouts' | 'settings';
+	editingDefId?: string | null;
+	monitor?: MonitorLayout;
+};
+function setup(opts: Opts = {}) {
+	const commitOp = vi.fn<(run: (s: EditorState) => Partial<EditorState>) => void>();
+	const monitorRef = { current: opts.monitor ?? monitorWith() } as React.RefObject<MonitorLayout>;
+	const hook = renderHook(() =>
+		useSavedLayouts({
+			studio: true,
+			navSection: opts.navSection ?? 'saved-layouts',
+			editingDefId: opts.editingDefId ?? null,
+			monitorRef,
+			commitOp
+		})
+	);
+	return { ...hook, commitOp, monitorRef };
+}
+
+beforeEach(() => {
+	vi.restoreAllMocks();
+	listLayouts.mockReset().mockResolvedValue([]);
+	readLayout.mockReset().mockResolvedValue(null);
+	saveLayoutAs.mockReset().mockResolvedValue('C:/cfg/layouts/x.json');
+	deleteLayout.mockReset().mockResolvedValue(true);
+});
+
+describe('section load', () => {
+	it('loads the layout names when the Saved-layouts section is open', async () => {
+		listLayouts.mockResolvedValue(['Home', 'Work']);
+		const { result } = setup({ navSection: 'saved-layouts' });
+		await waitFor(() => expect(result.current.layoutNames).toEqual(['Home', 'Work']));
+	});
+
+	it('does NOT load names while a different section is open', async () => {
+		setup({ navSection: 'settings' });
+		expect(listLayouts).not.toHaveBeenCalled();
+	});
+});
+
+describe('saveCurrentLayout', () => {
+	it('refuses (alerts) while editing a def', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		const { result } = setup({ editingDefId: 'd1' });
+		await act(async () => {
+			await result.current.saveCurrentLayout();
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Finish editing'));
+		expect(saveLayoutAs).not.toHaveBeenCalled();
+	});
+
+	it('aborts when the name prompt is cancelled or blank', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('   '); // trims to empty
+		const { result } = setup();
+		await act(async () => {
+			await result.current.saveCurrentLayout();
+		});
+		expect(saveLayoutAs).not.toHaveBeenCalled();
+	});
+
+	it('packs the live monitor (from the ref) under the typed name and refreshes', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('Gaming');
+		const mon = monitorWith('live');
+		// 'widgets' section → no mount auto-load; the pre-check sees no existing 'Gaming' (skip the
+		// overwrite confirm), then the post-save refresh returns the new name.
+		listLayouts.mockResolvedValueOnce([]).mockResolvedValueOnce(['Gaming']);
+		const { result } = setup({ monitor: mon, navSection: 'settings' });
+		await act(async () => {
+			await result.current.saveCurrentLayout();
+		});
+		expect(saveLayoutAs).toHaveBeenCalledTimes(1);
+		const [name, json] = saveLayoutAs.mock.calls[0];
+		expect(name).toBe('Gaming');
+		expect(JSON.parse(json)).toEqual(packLayout(mon, 'Gaming'));
+		await waitFor(() => expect(result.current.layoutNames).toEqual(['Gaming']));
+	});
+
+	it('confirms before overwriting an existing name; declining aborts the write', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('Home');
+		vi.spyOn(window, 'confirm').mockReturnValue(false);
+		listLayouts.mockResolvedValue(['Home']);
+		const { result } = setup();
+		await act(async () => {
+			await result.current.saveCurrentLayout();
+		});
+		expect(saveLayoutAs).not.toHaveBeenCalled();
+	});
+
+	it('proceeds past the overwrite confirm when accepted', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('Home');
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		listLayouts.mockResolvedValue(['Home']);
+		const { result } = setup();
+		await act(async () => {
+			await result.current.saveCurrentLayout();
+		});
+		expect(saveLayoutAs).toHaveBeenCalledWith('Home', expect.any(String));
+	});
+
+	it('alerts on a rejected save (saveLayoutAs returned null)', async () => {
+		vi.spyOn(window, 'prompt').mockReturnValue('Bad/Name');
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		saveLayoutAs.mockResolvedValue(null);
+		const { result } = setup();
+		await act(async () => {
+			await result.current.saveCurrentLayout();
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Could not save'));
+	});
+});
+
+describe('loadSavedLayout', () => {
+	it('refuses (alerts) while editing a def', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		const { result, commitOp } = setup({ editingDefId: 'd1' });
+		await act(async () => {
+			await result.current.loadSavedLayout('Home');
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Finish editing'));
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('alerts and bails when the slot is unreadable', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		readLayout.mockResolvedValue('not json');
+		const { result, commitOp } = setup();
+		await act(async () => {
+			await result.current.loadSavedLayout('Home');
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Could not read'));
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('alerts and bails when the slot read returns null (missing file)', async () => {
+		const alert = vi.spyOn(window, 'alert').mockImplementation(() => undefined);
+		readLayout.mockResolvedValue(null);
+		const { result, commitOp } = setup();
+		await act(async () => {
+			await result.current.loadSavedLayout('Gone');
+		});
+		expect(alert).toHaveBeenCalledWith(expect.stringContaining('Could not read'));
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('asks to confirm the replace; declining does not commit', async () => {
+		readLayout.mockResolvedValue(JSON.stringify(packLayout(monitorWith('saved'), 'Home')));
+		vi.spyOn(window, 'confirm').mockReturnValue(false);
+		const { result, commitOp } = setup();
+		await act(async () => {
+			await result.current.loadSavedLayout('Home');
+		});
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('commits the loaded monitor + clears the selection on confirm', async () => {
+		const saved = monitorWith('saved');
+		readLayout.mockResolvedValue(JSON.stringify(packLayout(saved, 'Home')));
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		const { result, commitOp } = setup();
+		await act(async () => {
+			await result.current.loadSavedLayout('Home');
+		});
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		// The op patch replaces the monitor and clears selection (the old ids are gone).
+		const patch = commitOp.mock.calls[0][0]({} as EditorState);
+		expect((patch.monitor as MonitorLayout).root.children.map((c) => c.id)).toEqual(['saved']);
+		expect(patch.selectedId).toBeNull();
+		expect(patch.selectedIds).toEqual([]);
+	});
+});
+
+describe('deleteSavedLayout', () => {
+	it('confirms first; declining skips the delete', async () => {
+		vi.spyOn(window, 'confirm').mockReturnValue(false);
+		const { result } = setup();
+		await act(async () => {
+			await result.current.deleteSavedLayout('Home');
+		});
+		expect(deleteLayout).not.toHaveBeenCalled();
+	});
+
+	it('deletes + refreshes the list on confirm', async () => {
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		listLayouts.mockResolvedValue(['Work']); // post-delete list
+		const { result } = setup({ navSection: 'settings' }); // avoid the section-open auto-load
+		await act(async () => {
+			await result.current.deleteSavedLayout('Home');
+		});
+		expect(deleteLayout).toHaveBeenCalledWith('Home');
+		await waitFor(() => expect(result.current.layoutNames).toEqual(['Work']));
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useSplitters.test.ts b/client/src/lib/widgets/canvas/useSplitters.test.ts
new file mode 100644
index 0000000..d006c94
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useSplitters.test.ts
@@ -0,0 +1,266 @@
+// useSplitters mixes pointer-drag glue (setPointerCapture / clientX-Y deltas) with REAL logic: the
+// grid-track vs child-basis commit branch (setSplit), the zoom-scaled drag delta, the even-split
+// double-click reset, and the WCAG keyboard nudge (axis + Shift step). We pass commitOp/mutateNoSave
+// as spies and drive the handlers with synthetic pointer/keyboard events, then INVOKE the captured
+// updater against a real grid/row monitor so the actual editHelpers math runs and we can assert the
+// resulting tree (real behavior, not "was a fn called"). The pure geometry (resizeSplit) is also
+// unit-tested directly in solve.test.ts; here we pin the wiring + branch selection around it.
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useSplitters } from './useSplitters';
+import type { Splitter } from '../../core/solve';
+import { container, leaf, type MonitorLayout } from '../../core/layoutTree';
+import { createWidget } from '../../core/widget';
+import type { EditorState } from './types';
+
+// A row container with two fr children A/B (the non-grid splitter case).
+function rowMonitor(): MonitorLayout {
+	const a = leaf(createWidget('text', 'A'), { fr: 1 });
+	const b = leaf(createWidget('text', 'B'), { fr: 1 });
+	return { root: container('row1', 'row', [a, b]), floating: [] };
+}
+// A grid container (the grid-track splitter case).
+function gridMonitor(): MonitorLayout {
+	const a = leaf(createWidget('text', 'A'));
+	const b = leaf(createWidget('text', 'B'));
+	return { root: container('grid1', 'grid', [a, b], { cols: 2, rows: 1 }), floating: [] };
+}
+function stateWith(monitor: MonitorLayout): EditorState {
+	return { monitor } as EditorState;
+}
+
+// A non-grid (child-basis) splitter between A and B.
+function rowSplitter(over: Partial<Splitter> = {}): Splitter {
+	return {
+		containerId: 'row1',
+		axis: 'row',
+		aId: 'A',
+		bId: 'B',
+		frA: 1,
+		frB: 1,
+		mainA: 100,
+		mainB: 100,
+		rect: { x: 0, y: 0, w: 8, h: 50 },
+		...over
+	};
+}
+// A grid-track splitter between columns 0 and 1.
+function gridSplitter(): Splitter {
+	return {
+		containerId: 'grid1',
+		axis: 'row',
+		aId: 'A',
+		bId: 'B',
+		frA: 1,
+		frB: 1,
+		mainA: 100,
+		mainB: 100,
+		rect: { x: 0, y: 0, w: 8, h: 50 },
+		track: { which: 'col', a: 0, b: 1 }
+	};
+}
+
+// A synthetic pointer event with the bits the hook reads.
+function ptr(over: Partial<Record<string, unknown>> = {}) {
+	return {
+		button: 0,
+		clientX: 0,
+		clientY: 0,
+		pointerId: 1,
+		preventDefault: vi.fn(),
+		stopPropagation: vi.fn(),
+		currentTarget: { setPointerCapture: vi.fn(), releasePointerCapture: vi.fn() },
+		...over
+	} as unknown as React.PointerEvent;
+}
+
+function setup(zoom = 1) {
+	const commitOp = vi.fn<(run: (s: EditorState) => Partial<EditorState>) => void>();
+	const mutateNoSave = vi.fn<(run: (s: EditorState) => Partial<EditorState>) => void>();
+	const { result } = renderHook(() => useSplitters({ zoom, commitOp, mutateNoSave }));
+	return { result, commitOp, mutateNoSave };
+}
+
+describe('pointer drag (down → move → up)', () => {
+	it('captures the pointer on down and ignores non-primary buttons', () => {
+		const { result } = setup();
+		const e = ptr({ button: 1 }); // middle button → ignored
+		result.current.onSplitDown(e, rowSplitter());
+		expect(
+			(e.currentTarget as unknown as { setPointerCapture: ReturnType<typeof vi.fn> })
+				.setPointerCapture
+		).not.toHaveBeenCalled();
+
+		const e2 = ptr({ button: 0 });
+		result.current.onSplitDown(e2, rowSplitter());
+		expect(e2.preventDefault).toHaveBeenCalled();
+		expect(
+			(e2.currentTarget as unknown as { setPointerCapture: ReturnType<typeof vi.fn> })
+				.setPointerCapture
+		).toHaveBeenCalledWith(1);
+	});
+
+	it('move resizes LIVE (mutateNoSave, no commit) using a zoom-scaled delta on a child-basis splitter', () => {
+		const { result, commitOp, mutateNoSave } = setup(2); // zoom 2 → screen delta halved in world px
+		result.current.onSplitDown(ptr({ clientX: 0 }), rowSplitter());
+		result.current.onSplitMove(ptr({ clientX: 40 })); // 40 screen px / zoom 2 = 20 world px
+		expect(commitOp).not.toHaveBeenCalled();
+		expect(mutateNoSave).toHaveBeenCalledTimes(1);
+		// Run the captured updater against the real row monitor → A grows, B shrinks, fr sum preserved.
+		const patch = mutateNoSave.mock.calls[0][0](stateWith(rowMonitor()));
+		const root = (patch.monitor as MonitorLayout).root;
+		const kids = (root as { children: { id: string; basis?: { fr: number } }[] }).children;
+		const frA = kids.find((c) => c.id === 'A')!.basis!.fr;
+		const frB = kids.find((c) => c.id === 'B')!.basis!.fr;
+		expect(frA).toBeGreaterThan(frB); // dragging right widened A
+		expect(Number((frA + frB).toFixed(3))).toBe(2); // combined fr conserved
+	});
+
+	it('a COL-axis move uses the clientY delta, and zoom 0 falls back to a 1:1 scale', () => {
+		const { result, mutateNoSave } = setup(0); // zoom 0 → the `zoom || 1` guard scales by 1
+		result.current.onSplitDown(
+			ptr({ clientY: 0 }),
+			rowSplitter({ axis: 'col', containerId: 'row1' })
+		);
+		result.current.onSplitMove(ptr({ clientY: 24 })); // vertical drag on a col splitter
+		const patch = mutateNoSave.mock.calls[0][0](
+			stateWith({
+				root: container('row1', 'col', [
+					leaf(createWidget('text', 'A'), { fr: 1 }),
+					leaf(createWidget('text', 'B'), { fr: 1 })
+				]),
+				floating: []
+			})
+		);
+		const kids = (
+			(patch.monitor as MonitorLayout).root as {
+				children: { id: string; basis?: { fr: number } }[];
+			}
+		).children;
+		expect(kids.find((c) => c.id === 'A')!.basis!.fr).toBeGreaterThan(1); // dragging down widened A
+	});
+
+	it('move with no active drag is a no-op', () => {
+		const { result, mutateNoSave } = setup();
+		result.current.onSplitMove(ptr({ clientX: 40 }));
+		expect(mutateNoSave).not.toHaveBeenCalled();
+	});
+
+	it('up COMMITS the final sizes, releases capture, and clears the drag', () => {
+		const { result, commitOp } = setup();
+		result.current.onSplitDown(ptr({ clientX: 0 }), rowSplitter());
+		result.current.onSplitMove(ptr({ clientX: 30 }));
+		const up = ptr({ clientX: 30 });
+		result.current.onSplitUp(up);
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		expect(
+			(up.currentTarget as unknown as { releasePointerCapture: ReturnType<typeof vi.fn> })
+				.releasePointerCapture
+		).toHaveBeenCalledWith(1);
+		// A second up is a no-op now the drag is cleared.
+		result.current.onSplitUp(ptr());
+		expect(commitOp).toHaveBeenCalledTimes(1);
+	});
+
+	it('a grid-track splitter drag commits via the GRID colFr branch', () => {
+		const { result, commitOp } = setup();
+		result.current.onSplitDown(ptr({ clientX: 0 }), gridSplitter());
+		result.current.onSplitUp(ptr({ clientX: 25 }));
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		const patch = commitOp.mock.calls[0][0](stateWith(gridMonitor()));
+		const grid = (patch.monitor as MonitorLayout).root as { colFr?: number[] };
+		expect(Array.isArray(grid.colFr)).toBe(true);
+		expect(grid.colFr).toHaveLength(2);
+		// Default deltas of 0 keep the tracks balanced; a non-empty weight array is what matters here.
+		expect(grid.colFr!.every((w) => w > 0)).toBe(true);
+	});
+});
+
+describe('onSplitReset (double-click → even pair)', () => {
+	it('commits an even split that preserves the pair’s combined fr', () => {
+		const { result, commitOp } = setup();
+		result.current.onSplitReset(rowSplitter({ frA: 3, frB: 1 }));
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		const patch = commitOp.mock.calls[0][0](stateWith(rowMonitor()));
+		const kids = (
+			(patch.monitor as MonitorLayout).root as {
+				children: { id: string; basis?: { fr: number } }[];
+			}
+		).children;
+		// (3 + 1) / 2 = 2 on each side.
+		expect(kids.find((c) => c.id === 'A')!.basis!.fr).toBe(2);
+		expect(kids.find((c) => c.id === 'B')!.basis!.fr).toBe(2);
+	});
+});
+
+describe('onSplitKey (WCAG keyboard nudge)', () => {
+	const key = (k: string, shift = false) =>
+		({ key: k, shiftKey: shift, preventDefault: vi.fn() } as unknown as React.KeyboardEvent);
+	// fr of child A after the n-th commit, run against a real row monitor.
+	const frA = (commitOp: ReturnType<typeof setup>['commitOp'], call: number) => {
+		const patch = commitOp.mock.calls[call][0](stateWith(rowMonitor()));
+		const kids = (
+			(patch.monitor as MonitorLayout).root as {
+				children: { id: string; basis?: { fr: number } }[];
+			}
+		).children;
+		return kids.find((c) => c.id === 'A')!.basis!.fr;
+	};
+
+	it('row axis: Shift+ArrowRight grows A, Shift+ArrowLeft shrinks A (direction mapping)', () => {
+		// Use the Shift step (24px) so the nudge clears resizeSplit's 14px center-snap band.
+		const { result, commitOp } = setup();
+		const right = key('ArrowRight', true);
+		result.current.onSplitKey(right, rowSplitter());
+		expect(right.preventDefault).toHaveBeenCalled();
+		expect(frA(commitOp, 0)).toBeGreaterThan(1);
+
+		result.current.onSplitKey(key('ArrowLeft', true), rowSplitter());
+		expect(frA(commitOp, 1)).toBeLessThan(1);
+	});
+
+	it('Shift takes a bigger step than the bare arrow', () => {
+		const { result, commitOp } = setup();
+		// Off-center mains so the bare 8px step also produces a (small) change rather than snapping.
+		const sp = rowSplitter({ mainA: 320, mainB: 80 });
+		result.current.onSplitKey(key('ArrowRight', false), sp);
+		result.current.onSplitKey(key('ArrowRight', true), sp);
+		expect(frA(commitOp, 1)).toBeGreaterThan(frA(commitOp, 0)); // Shift (24) > bare (8)
+	});
+
+	it('col axis uses ArrowDown (preventDefault + commit)', () => {
+		const { result, commitOp } = setup();
+		const down = key('ArrowDown', true);
+		result.current.onSplitKey(down, rowSplitter({ axis: 'col' }));
+		expect(down.preventDefault).toHaveBeenCalled();
+		expect(commitOp).toHaveBeenCalledTimes(1);
+	});
+
+	it('col axis ArrowUp shrinks; row-axis ArrowUp/ArrowDown are ignored (wrong axis)', () => {
+		const { result, commitOp } = setup();
+		// col + ArrowUp → negative step → commit.
+		result.current.onSplitKey(key('ArrowUp', true), rowSplitter({ axis: 'col' }));
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		// row + ArrowUp → d stays 0 → ignored.
+		const up = key('ArrowUp');
+		result.current.onSplitKey(up, rowSplitter({ axis: 'row' }));
+		expect(up.preventDefault).not.toHaveBeenCalled();
+		expect(commitOp).toHaveBeenCalledTimes(1); // unchanged
+	});
+
+	it('an irrelevant key is ignored (no commit, no preventDefault)', () => {
+		const { result, commitOp } = setup();
+		const noop = key('Enter');
+		result.current.onSplitKey(noop, rowSplitter());
+		expect(noop.preventDefault).not.toHaveBeenCalled();
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+
+	it('a wrong-axis arrow on a COL splitter (ArrowLeft) is ignored', () => {
+		const { result, commitOp } = setup();
+		const left = key('ArrowLeft');
+		result.current.onSplitKey(left, rowSplitter({ axis: 'col' }));
+		expect(left.preventDefault).not.toHaveBeenCalled();
+		expect(commitOp).not.toHaveBeenCalled();
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useStudioInit.test.ts b/client/src/lib/widgets/canvas/useStudioInit.test.ts
index 24e1a80..9a496f3 100644
--- a/client/src/lib/widgets/canvas/useStudioInit.test.ts
+++ b/client/src/lib/widgets/canvas/useStudioInit.test.ts
@@ -20,7 +20,8 @@ vi.mock('../../overlay', () => ({
 	monitorParam: () => monitorParamValue,
 	listThemes: vi.fn(async () => []),
 	openStudio: vi.fn(() => Promise.resolve()),
-	studioMonitorOptions: vi.fn(async () => [])
+	studioMonitorOptions: vi.fn(async () => []),
+	watchDisplayChanges: vi.fn(() => () => undefined)
 }));
 vi.mock('../../core/plugin', () => ({
 	startAllSources: vi.fn(async () => () => undefined)
diff --git a/client/src/lib/widgets/canvas/useStudioInit.ts b/client/src/lib/widgets/canvas/useStudioInit.ts
index 855f90c..c683b7a 100644
--- a/client/src/lib/widgets/canvas/useStudioInit.ts
+++ b/client/src/lib/widgets/canvas/useStudioInit.ts
@@ -15,7 +15,8 @@ import {
 	monitorParam,
 	openStudio,
 	setMainWindowVisible,
-	studioMonitorOptions
+	studioMonitorOptions,
+	watchDisplayChanges
 } from '../../overlay';
 import type { MonitorOption } from './types';
 
@@ -49,6 +50,8 @@ export function useStudioInit(deps: StudioInitDeps): void {
 		let unlistenThemes: UnlistenFn | undefined;
 		let unlistenStudio: UnlistenFn | undefined;
 		let unlistenEdit: UnlistenFn | undefined;
+		let unlistenRefit: UnlistenFn | undefined;
+		let stopDisplayWatch: (() => void) | undefined;
 
 		(async () => {
 			const dep = d.current;
@@ -60,6 +63,30 @@ export function useStudioInit(deps: StudioInitDeps): void {
 			// window-state plugin parked it.
 			const ownKey = dep.studio ? null : monitorParam();
 			if (ownKey) await fillOwnMonitor(ownKey);
+
+			// Re-fit this window to the CURRENT display layout — on the tray "Re-fit overlays" trigger AND
+			// automatically when monitors are moved/added/removed at runtime (no per-window scale-change
+			// event fires for that, so an overlay otherwise stays anchored to stale coordinates and clips).
+			// Each role re-runs its own fit: a secondary re-fits itself, the primary re-fits + reconciles
+			// its overlays, the studio refreshes its monitor list.
+			const refit = async (): Promise<void> => {
+				if (dep.studio) {
+					d.current.setMonitorOptions(await studioMonitorOptions());
+				} else if (ownKey) {
+					await fillOwnMonitor(ownKey);
+				} else {
+					await fillPrimaryMonitor();
+					await d.current.syncPrimaryOverlays();
+				}
+			};
+			unlistenRefit = await listen(EVENTS.refitOverlays, () => void refit());
+			stopDisplayWatch = watchDisplayChanges(() => void refit());
+			if (cancelled) {
+				unlistenRefit?.();
+				stopDisplayWatch?.();
+				return;
+			}
+
 			await dep.updateWorkArea();
 			sourceStop = await startAllSources(dep.hub); // built-in `system` + any plugin sources
 			if (cancelled) {
@@ -170,6 +197,8 @@ export function useStudioInit(deps: StudioInitDeps): void {
 			unlistenThemes?.();
 			unlistenStudio?.();
 			unlistenEdit?.();
+			unlistenRefit?.();
+			stopDisplayWatch?.();
 			d.current.clearPreviewWrite();
 		};
 		// Run once on mount (non-idempotent). eslint-disable to keep the empty dep list intentional.
diff --git a/client/src/lib/widgets/canvas/useThemes.test.ts b/client/src/lib/widgets/canvas/useThemes.test.ts
new file mode 100644
index 0000000..7c2d447
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useThemes.test.ts
@@ -0,0 +1,294 @@
+// useThemes wires the themes/ file I/O AROUND the selected-theme state, but it carries real logic
+// worth pinning: themeLabel (built-in catalog name / '(default)' / filename), the duplicate-name
+// collision loop (-copy / -copyN), the destructive-overwrite confirm guard, the built-in FORK
+// branch in the editor, the delete-active-theme fallback to default, adoptTheme/setTheme CSS swaps,
+// and the per-user-theme swatch effect. We mock only the overlay adapter + window prompts, keep the
+// real tokens/builtinThemes core, and assert observable state + the dispatch/commit it drives.
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { useThemes } from './useThemes';
+import type { EditorModel } from './useEditorModel';
+
+const resolveThemeCss = vi.fn<(name: string) => Promise<string>>();
+const loadThemeCss = vi.fn<(name: string) => Promise<string>>();
+const listThemes = vi.fn<() => Promise<string[]>>();
+const saveThemeCss = vi.fn<(name: string, css: string) => Promise<void>>();
+const deleteThemeCss = vi.fn<(name: string) => Promise<void>>();
+vi.mock('../../overlay', () => ({
+	resolveThemeCss: (...a: [string]) => resolveThemeCss(...a),
+	loadThemeCss: (...a: [string]) => loadThemeCss(...a),
+	listThemes: (...a: []) => listThemes(...a),
+	saveThemeCss: (...a: [string, string]) => saveThemeCss(...a),
+	deleteThemeCss: (...a: [string]) => deleteThemeCss(...a)
+}));
+
+function setup(opts: { studio?: boolean; selectedTheme?: string } = {}) {
+	const dispatch = vi.fn() as unknown as EditorModel['dispatch'];
+	const commitOp = vi.fn() as unknown as EditorModel['commitOp'];
+	const hook = renderHook(
+		(p: { studio: boolean; selectedTheme: string }) =>
+			useThemes({ studio: p.studio, selectedTheme: p.selectedTheme, dispatch, commitOp }),
+		{
+			initialProps: {
+				studio: opts.studio ?? true,
+				selectedTheme: opts.selectedTheme ?? ''
+			}
+		}
+	);
+	return {
+		...hook,
+		dispatch: dispatch as unknown as ReturnType<typeof vi.fn>,
+		commitOp: commitOp as unknown as ReturnType<typeof vi.fn>
+	};
+}
+
+beforeEach(() => {
+	vi.restoreAllMocks();
+	resolveThemeCss.mockReset().mockResolvedValue('/*resolved*/');
+	loadThemeCss.mockReset().mockResolvedValue('/*loaded*/');
+	listThemes.mockReset().mockResolvedValue([]);
+	saveThemeCss.mockReset().mockResolvedValue(undefined);
+	deleteThemeCss.mockReset().mockResolvedValue(undefined);
+});
+
+describe('themeLabel', () => {
+	it('maps a built-in selection to its catalog name, blank to (default), and a user name verbatim', () => {
+		const { result } = setup();
+		expect(result.current.themeLabel('builtin:nord')).toBe('Nord');
+		expect(result.current.themeLabel('')).toBe('(default)');
+		expect(result.current.themeLabel('mytheme.css')).toBe('mytheme.css');
+		// An unknown built-in id falls back to the bare id.
+		expect(result.current.themeLabel('builtin:does-not-exist')).toBe('does-not-exist');
+	});
+});
+
+describe('applyTheme / adoptTheme / setTheme (CSS swaps)', () => {
+	it('applyTheme re-resolves the CURRENT selection into themeCss', async () => {
+		resolveThemeCss.mockResolvedValue('/*current*/');
+		const { result } = setup({ selectedTheme: 'builtin:nord' });
+		await act(async () => {
+			await result.current.applyTheme();
+		});
+		expect(resolveThemeCss).toHaveBeenCalledWith('builtin:nord');
+		expect(result.current.themeCss).toBe('/*current*/');
+	});
+
+	it('adoptTheme swaps the live CSS WITHOUT dispatching', async () => {
+		resolveThemeCss.mockResolvedValue('/*adopted*/');
+		const { result, dispatch } = setup();
+		await act(async () => {
+			await result.current.adoptTheme('imported');
+		});
+		expect(result.current.themeCss).toBe('/*adopted*/');
+		expect(dispatch).not.toHaveBeenCalled();
+	});
+
+	it('setTheme dispatches setTheme, swaps CSS, and commits (a history no-op write)', async () => {
+		resolveThemeCss.mockResolvedValue('/*set*/');
+		const { result, dispatch, commitOp } = setup();
+		await act(async () => {
+			result.current.setTheme('builtin:dark');
+		});
+		expect(dispatch).toHaveBeenCalledWith({ type: 'setTheme', name: 'builtin:dark' });
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		await waitFor(() => expect(result.current.themeCss).toBe('/*set*/'));
+	});
+});
+
+describe('theme editor dialog', () => {
+	it('opens a USER theme in place: seeds the draft from its file CSS', async () => {
+		loadThemeCss.mockResolvedValue('.user{}');
+		const { result } = setup();
+		await act(async () => {
+			await result.current.openThemeEditor('mine');
+		});
+		expect(result.current.themeEditorOpen).toBe(true);
+		expect(result.current.themeDraftName).toBe('mine');
+		expect(result.current.themeDraft).toBe('.user{}');
+		expect(loadThemeCss).toHaveBeenCalledWith('mine');
+	});
+
+	it('opening a built-in FORKS it: draft seeded from resolved CSS under its catalog name, no in-place save', async () => {
+		resolveThemeCss.mockResolvedValue('/*nord css*/');
+		const { result } = setup();
+		await act(async () => {
+			await result.current.openThemeEditor('builtin:nord');
+		});
+		expect(result.current.themeDraftName).toBe('Nord');
+		expect(result.current.themeDraft).toBe('/*nord css*/');
+		expect(resolveThemeCss).toHaveBeenCalledWith('builtin:nord');
+	});
+
+	it('forking an UNKNOWN built-in id falls back to the bare id as the draft name', async () => {
+		// builtinIdOf treats any `builtin:` prefix as a built-in; an id with no catalog entry has no
+		// name, so the draft name falls back to the bare id (the `?? builtinId` arm).
+		const { result } = setup();
+		await act(async () => {
+			await result.current.openThemeEditor('builtin:ghost');
+		});
+		expect(result.current.themeDraftName).toBe('ghost');
+	});
+
+	it('open then close drives the focus-management effect (both arms)', async () => {
+		const { result } = setup();
+		await act(async () => {
+			await result.current.openThemeEditor('mine'); // open arm
+		});
+		expect(result.current.themeEditorOpen).toBe(true);
+		act(() => result.current.setThemeEditorOpen(false)); // close arm (focus-return)
+		expect(result.current.themeEditorOpen).toBe(false);
+	});
+
+	it('opening with NO name + no active theme scaffolds a starter "custom" theme', async () => {
+		const { result } = setup({ selectedTheme: '' });
+		await act(async () => {
+			await result.current.openThemeEditor();
+		});
+		expect(result.current.themeDraftName).toBe('custom');
+		expect(result.current.themeDraft).toContain('--np-accent');
+		expect(loadThemeCss).not.toHaveBeenCalled();
+	});
+
+	it('saveThemeEditor with a blank name is a no-op', async () => {
+		const { result } = setup();
+		act(() => result.current.setThemeDraftName('   '));
+		await act(async () => {
+			await result.current.saveThemeEditor();
+		});
+		expect(saveThemeCss).not.toHaveBeenCalled();
+	});
+
+	it('saveThemeEditor writes, refreshes the list, dispatches the selection, and commits', async () => {
+		listThemes.mockResolvedValue(['fresh']);
+		loadThemeCss.mockResolvedValue('.fresh{}');
+		const { result, dispatch, commitOp } = setup();
+		act(() => {
+			result.current.setThemeDraftName('fresh');
+			result.current.setThemeDraft('.fresh{}');
+		});
+		await act(async () => {
+			await result.current.saveThemeEditor();
+		});
+		expect(saveThemeCss).toHaveBeenCalledWith('fresh', '.fresh{}');
+		expect(dispatch).toHaveBeenCalledWith({ type: 'setTheme', name: 'fresh' });
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		expect(result.current.themeEditorOpen).toBe(false);
+		await waitFor(() => expect(result.current.themeList).toEqual(['fresh']));
+	});
+
+	it('saveThemeEditor confirms before clobbering a DIFFERENT existing theme; declining aborts', async () => {
+		const confirm = vi.spyOn(window, 'confirm').mockReturnValue(false);
+		const { result } = setup();
+		// The editor list already has "taken"; the user types that name while opened on nothing.
+		act(() => result.current.setThemeList(['taken']));
+		act(() => result.current.setThemeDraftName('taken'));
+		await act(async () => {
+			await result.current.saveThemeEditor();
+		});
+		expect(confirm).toHaveBeenCalled();
+		expect(saveThemeCss).not.toHaveBeenCalled();
+	});
+
+	it('saveThemeEditor proceeds past the overwrite confirm when accepted', async () => {
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		listThemes.mockResolvedValue(['taken']);
+		const { result } = setup();
+		act(() => result.current.setThemeList(['taken']));
+		act(() => result.current.setThemeDraftName('taken'));
+		await act(async () => {
+			await result.current.saveThemeEditor();
+		});
+		expect(saveThemeCss).toHaveBeenCalledWith('taken', expect.any(String));
+	});
+});
+
+describe('duplicateTheme', () => {
+	it('saves to a free "<label>-copy" stem and opens the copy for editing', async () => {
+		resolveThemeCss.mockResolvedValue('/*src*/');
+		listThemes.mockResolvedValue(['nord-copy']); // post-save refresh
+		const { result } = setup();
+		await act(async () => {
+			await result.current.duplicateTheme('builtin:nord');
+		});
+		// Built-in duplicates under its catalog label, not the builtin: id.
+		expect(saveThemeCss).toHaveBeenCalledWith('Nord-copy', '/*src*/');
+		expect(result.current.themeEditorOpen).toBe(true);
+	});
+
+	it('bumps the suffix (-copy2, -copy3…) past names already taken', async () => {
+		resolveThemeCss.mockResolvedValue('/*src*/');
+		const { result } = setup();
+		// Seed the editor's themeList so the collision loop has to skip -copy and -copy2.
+		act(() => result.current.setThemeList(['base-copy', 'base-copy2']));
+		await act(async () => {
+			await result.current.duplicateTheme('base');
+		});
+		expect(saveThemeCss).toHaveBeenCalledWith('base-copy3', '/*src*/');
+	});
+});
+
+describe('deleteTheme', () => {
+	it('confirms first; declining skips the delete', async () => {
+		vi.spyOn(window, 'confirm').mockReturnValue(false);
+		const { result } = setup();
+		await act(async () => {
+			await result.current.deleteTheme('mine');
+		});
+		expect(deleteThemeCss).not.toHaveBeenCalled();
+	});
+
+	it('deletes + refreshes the list; a non-active theme leaves the selection alone', async () => {
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		listThemes.mockResolvedValue(['other']);
+		const { result, dispatch } = setup({ selectedTheme: 'active' });
+		await act(async () => {
+			await result.current.deleteTheme('mine'); // not the active one
+		});
+		expect(deleteThemeCss).toHaveBeenCalledWith('mine');
+		await waitFor(() => expect(result.current.themeList).toEqual(['other']));
+		expect(dispatch).not.toHaveBeenCalled(); // selection untouched
+	});
+
+	it('deleting the ACTIVE theme falls back to (default): dispatch setTheme "" + clears CSS', async () => {
+		vi.spyOn(window, 'confirm').mockReturnValue(true);
+		listThemes.mockResolvedValue([]);
+		const { result, dispatch, commitOp } = setup({ selectedTheme: 'mine' });
+		// themeRef tracks selectedTheme; deleting it must reset to default.
+		await act(async () => {
+			await result.current.deleteTheme('mine');
+		});
+		expect(dispatch).toHaveBeenCalledWith({ type: 'setTheme', name: '' });
+		expect(commitOp).toHaveBeenCalledTimes(1);
+		expect(result.current.themeCss).toBe('');
+	});
+});
+
+describe('per-user-theme swatches', () => {
+	it('parses a {bg,accent,fg} swatch for each theme once the list is set (studio only)', async () => {
+		loadThemeCss.mockImplementation(async (name: string) =>
+			name === 'a'
+				? ':root{--ui-bg:#101010;--np-accent:#ff0000;--np-fg:#eeeeee}'
+				: ':root{--np-accent:#00ff00}'
+		);
+		const { result } = setup({ studio: true });
+		act(() => result.current.setThemeList(['a', 'b']));
+		await waitFor(() => expect(Object.keys(result.current.userThemeSwatches)).toHaveLength(2));
+		expect(result.current.userThemeSwatches.a).toEqual({
+			bg: '#101010',
+			accent: '#ff0000',
+			fg: '#eeeeee'
+		});
+		// Missing tokens fall back to the defaults inside swatchFromTokens.
+		expect(result.current.userThemeSwatches.b.accent).toBe('#00ff00');
+	});
+
+	it('does not compute swatches outside the studio', async () => {
+		const { result } = setup({ studio: false });
+		act(() => result.current.setThemeList(['a']));
+		// Give any (suppressed) async effect a tick; loadThemeCss must not have been called for swatches.
+		await act(async () => {
+			await Promise.resolve();
+		});
+		expect(result.current.userThemeSwatches).toEqual({});
+	});
+});
diff --git a/client/src/lib/widgets/canvas/useZoomFit.test.ts b/client/src/lib/widgets/canvas/useZoomFit.test.ts
new file mode 100644
index 0000000..17f145b
--- /dev/null
+++ b/client/src/lib/widgets/canvas/useZoomFit.test.ts
@@ -0,0 +1,261 @@
+// useZoomFit owns the studio world transform: fit() scales+centers the monitor work area into the
+// measured stage, an effect auto-fits once per monitor/size key (studio only), and a NATIVE wheel
+// listener zooms toward the cursor (gated on the studio.zoom control). The math is pure-testable;
+// the wheel/auto-fit paths are exercised by stubbing getBoundingClientRect and dispatching a real
+// WheelEvent on a happy-dom element (importing the hook also registers the controls defaults, so the
+// studio.zoom gate resolves). See useCanvasPointer.test.ts for the native-listener-on-a-ref pattern.
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useZoomFit } from './useZoomFit';
+import type { ControlOverrides } from '../../core/controls';
+
+type Opts = Parameters<typeof useZoomFit>[0];
+
+// A canvas element with a stubbed bounding rect (happy-dom returns zeros otherwise). `left`/`top`
+// become the wheel handler's origin for the cursor→world math.
+function makeCanvas(left = 0, top = 0): HTMLDivElement {
+	const el = document.createElement('div');
+	el.classList.add('canvas');
+	el.getBoundingClientRect = () =>
+		({
+			left,
+			top,
+			width: 0,
+			height: 0,
+			right: 0,
+			bottom: 0,
+			x: left,
+			y: top,
+			toJSON: () => ({})
+		} as DOMRect);
+	document.body.appendChild(el);
+	return el;
+}
+
+function baseOpts(over: Partial<Opts> = {}): Opts {
+	return {
+		studio: true,
+		myMonitor: 'm1',
+		monSize: { w: 1000, h: 500 },
+		stageW: 800,
+		stageH: 600,
+		canvasRef: { current: makeCanvas() },
+		...over
+	};
+}
+
+function wheel(deltaY: number, at: { x: number; y: number }, mods: Partial<WheelEventInit> = {}) {
+	const ev = new WheelEvent('wheel', {
+		deltaY,
+		ctrlKey: false,
+		shiftKey: false,
+		altKey: false,
+		bubbles: true,
+		cancelable: true,
+		...mods
+	});
+	// happy-dom's WheelEvent ctor drops clientX/clientY — set them so the cursor→world math runs.
+	Object.defineProperty(ev, 'clientX', { value: at.x, configurable: true });
+	Object.defineProperty(ev, 'clientY', { value: at.y, configurable: true });
+	return ev;
+}
+
+afterEach(() => {
+	document.body.innerHTML = '';
+	vi.restoreAllMocks();
+});
+
+describe('fit() — scale + center math', () => {
+	it('scales to the limiting axis * 0.95 and centers the world in the stage', () => {
+		// limiting axis: 800/1000 = 0.8 vs 600/500 = 1.2 → min 0.8 * 0.95 = 0.76
+		const { result } = renderHook(() => useZoomFit(baseOpts()));
+		act(() => result.current.fit());
+		const zoom = Math.min(800 / 1000, 600 / 500) * 0.95;
+		expect(result.current.zoom).toBeCloseTo(0.76, 10);
+		expect(result.current.zoom).toBe(zoom);
+		expect(result.current.panX).toBeCloseTo((800 - 1000 * zoom) / 2, 10);
+		expect(result.current.panY).toBeCloseTo((600 - 500 * zoom) / 2, 10);
+	});
+
+	it('is a no-op when the monitor size is zero (nothing to fit yet)', () => {
+		// Disable auto-fit (overlay) so only the explicit fit() under test runs.
+		const { result } = renderHook(() =>
+			useZoomFit(baseOpts({ studio: false, monSize: { w: 0, h: 0 } }))
+		);
+		const before = { ...result.current };
+		act(() => result.current.fit());
+		expect(result.current.zoom).toBe(before.zoom);
+		expect(result.current.panX).toBe(before.panX);
+		expect(result.current.panY).toBe(before.panY);
+	});
+
+	it('is a no-op when the stage has not been measured yet (stageW/H = 0)', () => {
+		const { result } = renderHook(() =>
+			useZoomFit(baseOpts({ studio: false, stageW: 0, stageH: 0 }))
+		);
+		act(() => result.current.fit());
+		expect(result.current).toMatchObject({ zoom: 1, panX: 0, panY: 0 });
+	});
+});
+
+describe('initial pan + auto-fit effect', () => {
+	it('overlay (studio=false) stays at the identity transform — no auto-fit', () => {
+		const { result } = renderHook(() => useZoomFit(baseOpts({ studio: false })));
+		expect(result.current).toMatchObject({ zoom: 1, panX: 0, panY: 0 });
+	});
+
+	it('studio auto-fits on first real measure', () => {
+		const { result } = renderHook(() => useZoomFit(baseOpts()));
+		// The mount effect fit()s immediately because studio + sizes are all > 0.
+		expect(result.current.zoom).toBeCloseTo(Math.min(800 / 1000, 600 / 500) * 0.95, 10);
+	});
+
+	it('does not auto-fit again for the SAME monitor/size key after a manual zoom', () => {
+		const opts = baseOpts();
+		const { result, rerender } = renderHook((p: Opts) => useZoomFit(p), { initialProps: opts });
+		// Manually drift the zoom, then rerender with the SAME key — the effect must not re-fit.
+		act(() => result.current.setPan({ zoom: 2, panX: 11, panY: 22 }));
+		rerender({ ...opts });
+		expect(result.current).toMatchObject({ zoom: 2, panX: 11, panY: 22 });
+	});
+
+	it('auto-fits AGAIN when the monitor key changes (different monitor)', () => {
+		const opts = baseOpts();
+		const { result, rerender } = renderHook((p: Opts) => useZoomFit(p), { initialProps: opts });
+		act(() => result.current.setPan({ zoom: 2, panX: 11, panY: 22 }));
+		// Switch monitors → new key → re-fit.
+		rerender({ ...opts, myMonitor: 'm2' });
+		expect(result.current.zoom).toBeCloseTo(Math.min(800 / 1000, 600 / 500) * 0.95, 10);
+		expect(result.current.zoom).not.toBe(2);
+	});
+});
+
+describe('wheel zoom (native listener)', () => {
+	it('zooms IN toward the cursor on a negative deltaY and preventDefaults', () => {
+		const canvas = makeCanvas(10, 20);
+		const { result } = renderHook(() => useZoomFit(baseOpts({ canvasRef: { current: canvas } })));
+		// Reset to a known transform so the cursor→world math is checkable.
+		act(() => result.current.setPan({ zoom: 1, panX: 0, panY: 0 }));
+
+		const ev = wheel(-100, { x: 110, y: 220 }); // cursor at (cx=100, cy=200) inside the canvas
+		act(() => {
+			canvas.dispatchEvent(ev);
+		});
+		// next zoom = 1 * 1.1; world point under the cursor is preserved, so panX = cx - wx*next where
+		// wx = (cx - 0)/1 = 100, cx = 110-10 = 100.
+		const next = 1.1;
+		expect(result.current.zoom).toBeCloseTo(next, 10);
+		expect(result.current.panX).toBeCloseTo(100 - 100 * next, 10);
+		expect(result.current.panY).toBeCloseTo(200 - 200 * next, 10);
+		expect(ev.defaultPrevented).toBe(true);
+	});
+
+	it('zooms OUT on a positive deltaY (1/1.1)', () => {
+		const canvas = makeCanvas();
+		const { result } = renderHook(() => useZoomFit(baseOpts({ canvasRef: { current: canvas } })));
+		act(() => result.current.setPan({ zoom: 1, panX: 0, panY: 0 }));
+		act(() => {
+			canvas.dispatchEvent(wheel(100, { x: 0, y: 0 }));
+		});
+		expect(result.current.zoom).toBeCloseTo(1 / 1.1, 10);
+	});
+
+	it('clamps zoom-in at the 4x ceiling', () => {
+		const canvas = makeCanvas();
+		const { result } = renderHook(() => useZoomFit(baseOpts({ canvasRef: { current: canvas } })));
+		act(() => result.current.setPan({ zoom: 4, panX: 0, panY: 0 }));
+		act(() => {
+			canvas.dispatchEvent(wheel(-100, { x: 0, y: 0 }));
+		});
+		expect(result.current.zoom).toBe(4);
+	});
+
+	it('clamps zoom-out at the 0.05x floor', () => {
+		const canvas = makeCanvas();
+		const { result } = renderHook(() => useZoomFit(baseOpts({ canvasRef: { current: canvas } })));
+		act(() => result.current.setPan({ zoom: 0.05, panX: 0, panY: 0 }));
+		act(() => {
+			canvas.dispatchEvent(wheel(100, { x: 0, y: 0 }));
+		});
+		expect(result.current.zoom).toBe(0.05);
+	});
+
+	it('ignores wheel events over a docked rail / toolbar (does not hijack their scroll)', () => {
+		const canvas = makeCanvas();
+		const rail = document.createElement('div');
+		rail.classList.add('inspector'); // one of the bail-out selectors
+		canvas.appendChild(rail);
+		const { result } = renderHook(() => useZoomFit(baseOpts({ canvasRef: { current: canvas } })));
+		act(() => result.current.setPan({ zoom: 1, panX: 0, panY: 0 }));
+		const ev = wheel(-100, { x: 0, y: 0 });
+		// Dispatch ON the rail child; the listener (on .canvas, via bubbling) should bail.
+		act(() => {
+			rail.dispatchEvent(ev);
+		});
+		expect(result.current.zoom).toBe(1);
+		expect(ev.defaultPrevented).toBe(false);
+	});
+
+	it('does not zoom in the overlay (studio=false → studio.zoom gate fails)', () => {
+		const canvas = makeCanvas();
+		const { result } = renderHook(() =>
+			useZoomFit(baseOpts({ studio: false, canvasRef: { current: canvas } }))
+		);
+		act(() => result.current.setPan({ zoom: 1, panX: 0, panY: 0 }));
+		const ev = wheel(-100, { x: 0, y: 0 });
+		act(() => {
+			canvas.dispatchEvent(ev);
+		});
+		expect(result.current.zoom).toBe(1);
+		expect(ev.defaultPrevented).toBe(false);
+	});
+
+	it('a disabling override on studio.zoom suppresses the wheel zoom (read live via ref)', () => {
+		const canvas = makeCanvas();
+		// overrides() returns a fresh fn each render; the hook reads it through a ref without
+		// re-subscribing. Disabling studio.zoom drops it from the matcher → no zoom.
+		const overrides = (): ControlOverrides => ({ 'studio.zoom': { disabled: true } });
+		const { result } = renderHook(() =>
+			useZoomFit(baseOpts({ canvasRef: { current: canvas }, overrides }))
+		);
+		act(() => result.current.setPan({ zoom: 1, panX: 0, panY: 0 }));
+		const ev = wheel(-100, { x: 0, y: 0 });
+		act(() => {
+			canvas.dispatchEvent(ev);
+		});
+		expect(result.current.zoom).toBe(1);
+		expect(ev.defaultPrevented).toBe(false);
+	});
+
+	it('is inert when the canvas ref is null (effect bails, hook still usable)', () => {
+		// The wheel effect early-returns with no element to attach to; the hook must still render and
+		// expose a working transform.
+		const { result } = renderHook(() =>
+			useZoomFit(baseOpts({ studio: false, canvasRef: { current: null } }))
+		);
+		expect(result.current).toMatchObject({ zoom: 1, panX: 0, panY: 0 });
+		act(() => result.current.setPan({ zoom: 2, panX: 0, panY: 0 }));
+		expect(result.current.zoom).toBe(2);
+	});
+
+	it('removes the wheel listener on unmount (no zoom after teardown)', () => {
+		const canvas = makeCanvas();
+		const { result, unmount } = renderHook(() =>
+			useZoomFit(baseOpts({ canvasRef: { current: canvas } }))
+		);
+		act(() => result.current.setPan({ zoom: 1, panX: 0, panY: 0 }));
+		const zoomBefore = result.current.zoom;
+		unmount();
+		// After unmount the cleanup detached the listener; dispatching must not change anything observable.
+		canvas.dispatchEvent(wheel(-100, { x: 0, y: 0 }));
+		expect(result.current.zoom).toBe(zoomBefore);
+	});
+});
+
+describe('setPan passthrough', () => {
+	it('exposes setPan to drive the world transform directly (Fit button / drag math)', () => {
+		const { result } = renderHook(() => useZoomFit(baseOpts({ studio: false })));
+		act(() => result.current.setPan({ zoom: 3, panX: 5, panY: 7 }));
+		expect(result.current).toMatchObject({ zoom: 3, panX: 5, panY: 7 });
+	});
+});
diff --git a/client/src/lib/widgets/colorHex.test.ts b/client/src/lib/widgets/colorHex.test.ts
index bd26f77..f712f3a 100644
--- a/client/src/lib/widgets/colorHex.test.ts
+++ b/client/src/lib/widgets/colorHex.test.ts
@@ -31,4 +31,17 @@ describe('toHexColor', () => {
 		expect(toHexColor('var(--np-accent)')).toBeNull();
 		expect(toHexColor('#ab')).toBeNull();
 	});
+	it('returns null for 5- and 7-digit hex (matched length but not a valid form)', () => {
+		expect(toHexColor('#abcde')).toBeNull(); // 5 nibbles
+		expect(toHexColor('#abcdef0')).toBeNull(); // 7 nibbles
+	});
+	it('rejects rgb() with fewer than three channels', () => {
+		expect(toHexColor('rgb(10, 20)')).toBeNull();
+	});
+	it('rejects rgb() with a non-numeric channel', () => {
+		expect(toHexColor('rgb(10, abc, 30)')).toBeNull();
+	});
+	it('treats a null value as empty', () => {
+		expect(toHexColor(null as unknown as string)).toBeNull();
+	});
 });
diff --git a/client/src/lib/widgets/cssEditorExt.test.ts b/client/src/lib/widgets/cssEditorExt.test.ts
index a96311f..2d19d43 100644
--- a/client/src/lib/widgets/cssEditorExt.test.ts
+++ b/client/src/lib/widgets/cssEditorExt.test.ts
@@ -1,6 +1,8 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
 import { CompletionContext } from '@codemirror/autocomplete';
+import { diagnosticCount, forceLinting } from '@codemirror/lint';
 import { css } from '@codemirror/lang-css';
 import { cssExtensions, partCompletionSource, tokenCompletionSource } from './cssEditorExt';
 import { DEFAULT_TOKENS } from '../core/tokens';
@@ -53,3 +55,40 @@ describe('autocomplete wiring', () => {
 		expect(state.languageDataAt('autocomplete', 5)).toHaveLength(3);
 	});
 });
+
+describe('linter wiring (cssDiagnostics → CM diagnostics)', () => {
+	// Drive the bundled linter end-to-end against a real EditorView so the linter source callback
+	// (the cssDiagnostics → CM-diagnostic mapping) actually runs. Uses a hidden DOM container.
+	function mount(doc: string): EditorView {
+		const parent = document.createElement('div');
+		document.body.appendChild(parent);
+		return new EditorView({
+			state: EditorState.create({ doc, extensions: cssExtensions() }),
+			parent
+		});
+	}
+
+	it('surfaces a diagnostic for a broken CSS fragment', async () => {
+		// An unbalanced bracket fragment is flagged by the balance pass inside cssDiagnostics; the
+		// linter callback maps that to a CodeMirror diagnostic on the document.
+		const view = mount('color: red; }}');
+		try {
+			forceLinting(view);
+			await vi.waitFor(() => expect(diagnosticCount(view.state)).toBeGreaterThan(0));
+		} finally {
+			view.destroy();
+		}
+	});
+
+	it('produces no diagnostics for a clean fragment', async () => {
+		const view = mount('color: red;');
+		try {
+			forceLinting(view);
+			// Let the (forced) lint pass settle, then assert it stayed clean.
+			await new Promise((r) => setTimeout(r, 0));
+			expect(diagnosticCount(view.state)).toBe(0);
+		} finally {
+			view.destroy();
+		}
+	});
+});
diff --git a/client/src/lib/widgets/cssEditorLint.test.ts b/client/src/lib/widgets/cssEditorLint.test.ts
index 13381a1..451d637 100644
--- a/client/src/lib/widgets/cssEditorLint.test.ts
+++ b/client/src/lib/widgets/cssEditorLint.test.ts
@@ -1,8 +1,16 @@
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { cssDiagnostics } from './cssEditorLint';
 
 const ok = () => true;
 
+// Snapshot + restore the global CSS so the runtimeSupports tests can drive each branch.
+const realCss = globalThis.CSS;
+afterEach(() => {
+	if (realCss === undefined) delete (globalThis as { CSS?: unknown }).CSS;
+	else (globalThis as { CSS?: unknown }).CSS = realCss;
+	vi.restoreAllMocks();
+});
+
 describe('cssDiagnostics', () => {
 	it('returns nothing for empty or valid fragments', () => {
 		expect(cssDiagnostics('')).toEqual([]);
@@ -30,9 +38,21 @@ describe('cssDiagnostics', () => {
 		expect(d[0].message).toMatch(/font-sze/);
 	});
 
-	it('does not check custom properties or var()/nested values', () => {
+	it('does not check custom properties, var()/brace values, or empty values', () => {
 		expect(cssDiagnostics('--my-token: anything goes', { supports: () => false })).toEqual([]);
 		expect(cssDiagnostics('color: var(--np-accent)', { supports: () => false })).toEqual([]);
+		// A declaration whose value is itself a nested block (contains '{') can't be statically checked.
+		expect(cssDiagnostics('grid: { foo }', { supports: () => false })).toEqual([]);
+		// An empty value (trailing colon) is skipped, not flagged.
+		expect(cssDiagnostics('color:', { supports: () => false })).toEqual([]);
+	});
+
+	it('caps the diagnostic count on a very broken doc', () => {
+		// A flood of distinct unknown props — the gutter is capped at 50 entries.
+		const lines = Array.from({ length: 80 }, (_, i) => `bad-prop-${i}: x`).join(';\n');
+		const d = cssDiagnostics(lines, { supports: (p) => !p.startsWith('bad-prop') });
+		expect(d.length).toBe(50);
+		expect(d.every((x) => x.severity === 'warning')).toBe(true);
 	});
 
 	it('maps diagnostic positions back into the fragment (not the scope wrapper)', () => {
@@ -42,4 +62,30 @@ describe('cssDiagnostics', () => {
 		// "font-sze" starts at index 12 (after "color: red;\n").
 		expect(warn?.from).toBe(12);
 	});
+
+	// The default supports path (runtimeSupports) — exercised by NOT passing `supports`.
+	describe('runtimeSupports (default supports)', () => {
+		it('assumes valid (no warnings) when CSS is unavailable', () => {
+			delete (globalThis as { CSS?: unknown }).CSS;
+			expect(cssDiagnostics('font-sze: 52px')).toEqual([]);
+		});
+
+		it('flags via the runtime CSS.supports when present', () => {
+			(globalThis as { CSS?: unknown }).CSS = {
+				supports: (p: string) => p !== 'font-sze'
+			};
+			const d = cssDiagnostics('font-sze: 52px');
+			expect(d).toHaveLength(1);
+			expect(d[0].severity).toBe('warning');
+		});
+
+		it('treats a value as valid when CSS.supports throws', () => {
+			(globalThis as { CSS?: unknown }).CSS = {
+				supports: () => {
+					throw new Error('malformed');
+				}
+			};
+			expect(cssDiagnostics('color: red')).toEqual([]);
+		});
+	});
 });
diff --git a/client/src/lib/widgets/meters/Agenda.test.tsx b/client/src/lib/widgets/meters/Agenda.test.tsx
index 22d6208..cbe4f76 100644
--- a/client/src/lib/widgets/meters/Agenda.test.tsx
+++ b/client/src/lib/widgets/meters/Agenda.test.tsx
@@ -15,12 +15,15 @@ const list = (rows: unknown[]): SensorSample => ({
 	value: { kind: 'json', value: rows }
 });
 
-const renderWith = async (hub: ReturnType<typeof createTelemetryHub>) => {
+const renderWith = async (
+	hub: ReturnType<typeof createTelemetryHub> | null,
+	props: Record<string, unknown> = {}
+) => {
 	let container!: HTMLElement;
 	await act(async () => {
 		container = render(
 			<TelemetryHubContext.Provider value={hub}>
-				<Agenda />
+				<Agenda {...props} />
 			</TelemetryHubContext.Provider>
 		).container;
 	});
@@ -51,4 +54,38 @@ describe('Agenda meter', () => {
 		const c = await renderWith(createTelemetryHub());
 		expect(c.querySelector('.ag-empty')?.textContent).toBe('No upcoming events');
 	});
+
+	it('renders a header with the configured title (and applies the accent var)', async () => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date(2027, 0, 1, 13, 0, 0));
+		const c = await renderWith(createTelemetryHub(), { title: 'My Calendar', color: 'tomato' });
+		expect(c.querySelector('.ag-head .ag-title')?.textContent).toBe('My Calendar');
+		expect((c.querySelector('.agenda') as HTMLElement).style.getPropertyValue('--ag-accent')).toBe(
+			'tomato'
+		);
+	});
+
+	it('uses the location as the summary tooltip when present', async () => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date(2027, 0, 1, 13, 0, 0));
+		const hub = createTelemetryHub();
+		hub.ingestBatch([
+			list([
+				{
+					summary: 'Standup',
+					start: new Date(2027, 0, 1, 15, 0).toISOString(),
+					location: 'Room 4'
+				}
+			])
+		]);
+		const c = await renderWith(hub);
+		expect(c.querySelector('.ag-summary')?.getAttribute('title')).toBe('Room 4');
+	});
+
+	it('renders nothing-but-empty (no subscription) when there is no telemetry hub', async () => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date(2027, 0, 1, 13, 0, 0));
+		const c = await renderWith(null);
+		expect(c.querySelector('.ag-empty')?.textContent).toBe('No upcoming events');
+	});
 });
diff --git a/client/src/lib/widgets/meters/Bar.test.tsx b/client/src/lib/widgets/meters/Bar.test.tsx
new file mode 100644
index 0000000..310d8c4
--- /dev/null
+++ b/client/src/lib/widgets/meters/Bar.test.tsx
@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import Bar from './Bar';
+
+const part = (c: Element, p: string) => {
+	const el = c.querySelector(`[data-part="${p}"]`);
+	if (!el) throw new Error(`missing data-part="${p}"`);
+	return el as HTMLElement;
+};
+
+describe('Bar', () => {
+	it('horizontal (default): fills width from the value fraction, uses accent/track tokens', () => {
+		const { container } = render(<Bar value={42} />);
+		const track = part(container, 'track');
+		const fill = part(container, 'fill');
+		expect(track.className).toContain('horizontal');
+		// fraction(42, 0, 100) * 100 → '42.0%' on width
+		expect(fill.style.width).toBe('42.0%');
+		expect(fill.style.height).toBe('');
+		// happy-dom does not serialise a `var(...)` background into the inline style attribute,
+		// so the token-driven defaults leave `style.background` empty (look lives in CSS).
+		expect(track.style.background).toBe('');
+		expect(fill.style.background).toBe('');
+		// No label by default.
+		expect(container.querySelector('[data-part="label"]')).toBeNull();
+	});
+
+	it('vertical orientation drives height instead of width', () => {
+		const { container } = render(<Bar value={75} orientation="vertical" />);
+		const track = part(container, 'track');
+		const fill = part(container, 'fill');
+		expect(track.className).toContain('vertical');
+		expect(fill.style.height).toBe('75.0%');
+		expect(fill.style.width).toBe('');
+	});
+
+	it('per-instance color/track override the tokens and a label renders', () => {
+		const { container } = render(
+			<Bar value={50} min={0} max={200} color="red" track="#222" label="RAM" />
+		);
+		const track = part(container, 'track');
+		const fill = part(container, 'fill');
+		// Concrete colours (unlike var() tokens) do serialise into the inline style.
+		expect(track.style.background).toBe('#222');
+		expect(fill.style.background).toBe('red');
+		// fraction(50, 0, 200) = 0.25 → '25.0%'
+		expect(fill.style.width).toBe('25.0%');
+		expect(part(container, 'label').textContent).toBe('RAM');
+	});
+
+	it('null value (default) clamps to 0%', () => {
+		const { container } = render(<Bar />);
+		expect(part(container, 'fill').style.width).toBe('0.0%');
+	});
+});
diff --git a/client/src/lib/widgets/meters/Clock.test.tsx b/client/src/lib/widgets/meters/Clock.test.tsx
index 038a128..a19cd8d 100644
--- a/client/src/lib/widgets/meters/Clock.test.tsx
+++ b/client/src/lib/widgets/meters/Clock.test.tsx
@@ -1,7 +1,9 @@
-import { describe, expect, it } from 'vitest';
-import { render } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
 import Clock from './Clock';
 
+afterEach(cleanup);
+
 describe('Clock (digital) is bare DOM, color via CSS variable', () => {
 	it('passes a per-instance color as --clock-color, not an inline color', () => {
 		const { container } = render(<Clock format="HH:mm" color="rgb(1, 2, 3)" />);
@@ -21,4 +23,24 @@ describe('Clock (digital) is bare DOM, color via CSS variable', () => {
 		expect(container.querySelector('[data-part="value"]')?.textContent).toMatch(/^\d{2}:\d{2}$/);
 		expect(container.querySelector('[data-part="label"]')?.textContent).toBe('JST');
 	});
+
+	it('renders no label element when none is given', () => {
+		const { container } = render(<Clock format="HH:mm" />);
+		expect(container.querySelector('[data-part="label"]')).toBeNull();
+	});
+});
+
+describe('Clock ticks on a 1s interval', () => {
+	beforeEach(() => vi.useFakeTimers({ now: new Date('2020-01-01T10:00:00') }));
+	afterEach(() => vi.useRealTimers());
+
+	it('re-reads the time each second so the display advances', () => {
+		const { container } = render(<Clock format="HH:mm:ss" />);
+		const value = (): string => container.querySelector('[data-part="value"]')?.textContent ?? '';
+		expect(value()).toBe('10:00:00');
+		act(() => {
+			vi.advanceTimersByTime(2000);
+		});
+		expect(value()).toBe('10:00:02');
+	});
 });
diff --git a/client/src/lib/widgets/meters/Countdown.test.tsx b/client/src/lib/widgets/meters/Countdown.test.tsx
index def72e8..524dc3b 100644
--- a/client/src/lib/widgets/meters/Countdown.test.tsx
+++ b/client/src/lib/widgets/meters/Countdown.test.tsx
@@ -1,5 +1,5 @@
 import { describe, it, expect, afterEach, vi } from 'vitest';
-import { render, cleanup } from '@testing-library/react';
+import { render, cleanup, act } from '@testing-library/react';
 import Countdown from './Countdown';
 
 afterEach(() => {
@@ -47,4 +47,35 @@ describe('Countdown meter', () => {
 		expect(container.querySelector('.cd-value')?.textContent).toBe('25:00');
 		expect(container.querySelector('.cd-sub')?.textContent).toContain('Work');
 	});
+
+	it('enters the break phase once the work session elapses', () => {
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date('2026-01-01T00:00:00Z'));
+		const { container } = render(<Countdown mode="pomodoro" workMin={25} breakMin={5} />);
+		act(() => {
+			// Past the 25-min work session → break phase. The tick advances the fake clock 1s,
+			// so 26:01 elapsed leaves 3:59 of the 5-min break.
+			vi.setSystemTime(new Date('2026-01-01T00:26:00Z'));
+			vi.advanceTimersByTime(1000);
+		});
+		expect(container.querySelector('.countdown')?.getAttribute('data-phase')).toBe('break');
+		expect(container.querySelector('.cd-value')?.textContent).toBe('03:59');
+		expect(container.querySelector('.cd-sub')?.textContent).toContain('Break');
+	});
+
+	it('renders a custom label and applies the accent colour', () => {
+		const { container } = render(
+			<Countdown mode="event" target="" label="Launch" color="#ff0066" />
+		);
+		expect(container.querySelector('.cd-label')?.textContent).toBe('Launch');
+		const root = container.querySelector('.countdown') as HTMLElement;
+		expect(root.style.getPropertyValue('--cd-accent')).toBe('#ff0066');
+	});
+
+	it('drops the accent var when no colour is given', () => {
+		const { container } = render(<Countdown mode="event" target="" />);
+		const root = container.querySelector('.countdown') as HTMLElement;
+		expect(root.style.getPropertyValue('--cd-accent')).toBe('');
+		expect(container.querySelector('.cd-label')).toBeNull();
+	});
 });
diff --git a/client/src/lib/widgets/meters/Cpu.test.tsx b/client/src/lib/widgets/meters/Cpu.test.tsx
index d868e89..ef25cdf 100644
--- a/client/src/lib/widgets/meters/Cpu.test.tsx
+++ b/client/src/lib/widgets/meters/Cpu.test.tsx
@@ -84,3 +84,38 @@ describe('Cpu (per-core grid)', () => {
 		expect(cap.props?.color).toBe('red');
 	});
 });
+
+describe('Cpu (combined gauge)', () => {
+	it("renders a Gauge of cpu.total (not the per-core canvas) when mode is 'combined'", () => {
+		// The hub seeds cpu.total = 10; combined mode composes the real Gauge (only CpuCoresCanvas is
+		// mocked), so the rounded total + unit + label must show up in the gauge text.
+		const { container } = renderCpu(<Cpu mode="combined" label="Load" />, 4);
+		expect(cap.props).toBeNull(); // the per-core canvas is NOT rendered in combined mode
+		expect(container.querySelector('[data-part="value"]')?.textContent).toBe('10%');
+		expect(container.querySelector('[data-part="label"]')?.textContent).toBe('Load');
+	});
+
+	it('shows a dash in combined mode before any cpu.total sample arrives', () => {
+		cap.props = null;
+		const { container } = render(
+			<TelemetryHubContext.Provider value={createTelemetryHub()}>
+				<Cpu mode="combined" />
+			</TelemetryHubContext.Provider>
+		);
+		// Gauge renders the en-dash placeholder for a null value.
+		expect(container.querySelector('[data-part="value"]')?.textContent).toBe('–%');
+	});
+});
+
+describe('Cpu (no hub)', () => {
+	it('renders an empty gauge without throwing when there is no telemetry hub', () => {
+		// Outside a provider the context is null; the effect bails (no subscription) and combined mode
+		// still renders the null-value placeholder gauge.
+		const { container } = render(
+			<TelemetryHubContext.Provider value={null}>
+				<Cpu mode="combined" />
+			</TelemetryHubContext.Provider>
+		);
+		expect(container.querySelector('[data-part="value"]')?.textContent).toBe('–%');
+	});
+});
diff --git a/client/src/lib/widgets/meters/Disks.test.tsx b/client/src/lib/widgets/meters/Disks.test.tsx
index c8a438a..158ea5e 100644
--- a/client/src/lib/widgets/meters/Disks.test.tsx
+++ b/client/src/lib/widgets/meters/Disks.test.tsx
@@ -1,10 +1,13 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, afterEach, vi } from 'vitest';
 import { render, cleanup, act } from '@testing-library/react';
 import Disks from './Disks';
 import { createTelemetryHub } from '../../core/telemetry';
 import { TelemetryHubContext } from '../telemetryContext';
 
-afterEach(cleanup);
+afterEach(() => {
+	cleanup();
+	vi.useRealTimers();
+});
 const s = (sensor: string, value: number) => ({
 	sensor,
 	ts_ms: 0,
@@ -50,4 +53,118 @@ describe('Disks meter', () => {
 		});
 		expect(container.querySelector('.disk-empty')?.textContent).toBe('—');
 	});
+
+	it('shows a dash (no rows) when there is no telemetry hub', async () => {
+		let container!: HTMLElement;
+		await act(async () => {
+			container = render(
+				<TelemetryHubContext.Provider value={null}>
+					<Disks />
+				</TelemetryHubContext.Provider>
+			).container;
+		});
+		expect(container.querySelector('.disk-empty')?.textContent).toBe('—');
+		expect(container.querySelectorAll('.disk-row')).toHaveLength(0);
+	});
+
+	it('omits the byte meta when showBytes is off (percent only)', async () => {
+		const hub = createTelemetryHub();
+		hub.ingestBatch([
+			s('disk.C.used.pct', 50),
+			s('disk.C.used', 500_000_000_000),
+			s('disk.C.total', 1_000_000_000_000)
+		]);
+		let container!: HTMLElement;
+		await act(async () => {
+			container = render(
+				<TelemetryHubContext.Provider value={hub}>
+					<Disks showBytes={false} />
+				</TelemetryHubContext.Provider>
+			).container;
+		});
+		const meta = container.querySelector('.disk-meta')?.textContent;
+		expect(meta).toBe('50%'); // no " · 500GB/1TB" tail
+		expect(meta).not.toContain('·');
+	});
+
+	it('renders a discovered volume with no percent sample (blank meta, no byte tail)', async () => {
+		// total present (so the letter is discovered) but neither used.pct nor used → pct is null:
+		// the bar floors at 0% and the meta is empty (the byte tail also needs `used`, which is absent).
+		const hub = createTelemetryHub();
+		hub.ingestBatch([s('disk.E.total', 2_000_000_000_000)]);
+		let container!: HTMLElement;
+		await act(async () => {
+			container = render(
+				<TelemetryHubContext.Provider value={hub}>
+					<Disks />
+				</TelemetryHubContext.Provider>
+			).container;
+		});
+		const row = container.querySelector('.disk-row') as HTMLElement;
+		expect(row.querySelector('.disk-label')?.textContent).toBe('E:');
+		expect(row.style.getPropertyValue('--disk-pct')).toBe('0%'); // null pct → clamped to 0
+		expect(row.querySelector('.disk-meta')?.textContent).toBe(''); // null pct → blank meta
+	});
+
+	it('applies the accent color as a CSS var on the container', async () => {
+		const hub = createTelemetryHub();
+		hub.ingestBatch([s('disk.C.used.pct', 10)]);
+		let container!: HTMLElement;
+		await act(async () => {
+			container = render(
+				<TelemetryHubContext.Provider value={hub}>
+					<Disks color="cyan" />
+				</TelemetryHubContext.Provider>
+			).container;
+		});
+		expect(
+			(container.querySelector('.disks') as HTMLElement).style.getPropertyValue('--disk-accent')
+		).toBe('cyan');
+	});
+
+	it('bails the re-render on the 5s re-read when capacity is unchanged (sameVols dedupe)', async () => {
+		vi.useFakeTimers();
+		const hub = createTelemetryHub();
+		hub.ingestBatch([
+			s('disk.C.used.pct', 40),
+			s('disk.C.used', 400_000_000_000),
+			s('disk.C.total', 1_000_000_000_000)
+		]);
+		let container!: HTMLElement;
+		await act(async () => {
+			container = render(
+				<TelemetryHubContext.Provider value={hub}>
+					<Disks />
+				</TelemetryHubContext.Provider>
+			).container;
+		});
+		const before = container.querySelector('.disk-meta')?.textContent;
+		// The interval re-reads the same hub snapshot → next equals prev (same length, every field equal),
+		// so sameVols's .every callback runs and returns true; React keeps the prior array (no churn).
+		await act(async () => {
+			vi.advanceTimersByTime(5000);
+		});
+		expect(container.querySelectorAll('.disk-row')).toHaveLength(1);
+		expect(container.querySelector('.disk-meta')?.textContent).toBe(before);
+	});
+
+	it('updates rows on the 5s re-read when a volume capacity changes', async () => {
+		vi.useFakeTimers();
+		const hub = createTelemetryHub();
+		hub.ingestBatch([s('disk.C.used.pct', 40)]);
+		let container!: HTMLElement;
+		await act(async () => {
+			container = render(
+				<TelemetryHubContext.Provider value={hub}>
+					<Disks />
+				</TelemetryHubContext.Provider>
+			).container;
+		});
+		expect(container.querySelector('.disk-meta')?.textContent).toBe('40%');
+		hub.ingestBatch([s('disk.C.used.pct', 88)]); // same letter, changed pct → sameVols returns false
+		await act(async () => {
+			vi.advanceTimersByTime(5000);
+		});
+		expect(container.querySelector('.disk-meta')?.textContent).toBe('88%');
+	});
 });
diff --git a/client/src/lib/widgets/meters/HaBinarySensor.tsx b/client/src/lib/widgets/meters/HaBinarySensor.tsx
new file mode 100644
index 0000000..03b91fe
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaBinarySensor.tsx
@@ -0,0 +1,52 @@
+// Presentational HA meter (molecule): a binary_sensor, with device_class-aware wording so an `on`
+// reads as "Open" / "Motion" / "Wet" etc. instead of a bare ON. Read-only; the `value` is the raw
+// HA state object (binds: 'json'). Prop-only, themeable via tokens (AGENTS.md §6).
+import './HaControls.css';
+
+type HaState = { state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+};
+
+// [on-word, off-word] per device_class — the common subset; anything else falls back to ON/OFF.
+const CLASS_WORDS: Record<string, [string, string]> = {
+	door: ['Open', 'Closed'],
+	window: ['Open', 'Closed'],
+	garage_door: ['Open', 'Closed'],
+	opening: ['Open', 'Closed'],
+	lock: ['Unlocked', 'Locked'],
+	motion: ['Motion', 'Clear'],
+	occupancy: ['Occupied', 'Clear'],
+	presence: ['Home', 'Away'],
+	moisture: ['Wet', 'Dry'],
+	smoke: ['Smoke', 'Clear'],
+	gas: ['Gas', 'Clear'],
+	problem: ['Problem', 'OK'],
+	connectivity: ['Connected', 'Disconnected'],
+	battery: ['Low', 'OK'],
+	power: ['On', 'Off']
+};
+
+export default function HaBinarySensor({ value = null, label }: Props) {
+	const s = (value ?? null) as HaState | null;
+	const attrs = s?.attributes ?? {};
+	const name = label ?? (attrs.friendly_name as string | undefined) ?? '—';
+	const state = s?.state ?? '—';
+	const on = state === 'on';
+	const dc = attrs.device_class as string | undefined;
+	const words = (dc && CLASS_WORDS[dc]) || ['ON', 'OFF'];
+	const text = state === 'on' ? words[0] : state === 'off' ? words[1] : state;
+
+	return (
+		<div className={`ha-binary np-ha-binary${on ? ' on' : ''}`} data-part="root">
+			<span className="label" data-part="label">
+				{name}
+			</span>
+			<span className="value" data-part="value">
+				{text}
+			</span>
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaClimate.css b/client/src/lib/widgets/meters/HaClimate.css
index 4af99e4..ba2db1c 100644
--- a/client/src/lib/widgets/meters/HaClimate.css
+++ b/client/src/lib/widgets/meters/HaClimate.css
@@ -53,3 +53,27 @@
 .np-ha-climate .ha-climate-btn:hover {
 	background: var(--np-accent, rgba(119, 196, 211, 0.2));
 }
+
+/* Tap-to-cycle HVAC mode — shares .mode's look, dotted underline hints it's actionable. */
+.np-ha-climate .mode-btn {
+	align-self: flex-start;
+	padding: 0;
+	border: none;
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	cursor: pointer;
+	text-decoration: underline dotted;
+	text-underline-offset: 2px;
+}
+
+.np-ha-climate .ha-climate-fan {
+	margin-top: 2px;
+	width: 100%;
+	box-sizing: border-box;
+	background: var(--np-bg, rgba(10, 10, 12, 0.6));
+	color: inherit;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.5));
+	border-radius: var(--np-radius, 3px);
+	font: inherit;
+}
diff --git a/client/src/lib/widgets/meters/HaClimate.tsx b/client/src/lib/widgets/meters/HaClimate.tsx
index 0e82069..9b38d5d 100644
--- a/client/src/lib/widgets/meters/HaClimate.tsx
+++ b/client/src/lib/widgets/meters/HaClimate.tsx
@@ -1,9 +1,17 @@
-// Interactive HA meter (molecule): a climate readout (current → target setpoint + mode) with
-// ± setpoint nudge buttons for single-setpoint thermostats. Reads from the entity's JSON
-// attributes (binds: 'json'); a nudge calls `onControl` (climate.set_temperature) that WidgetHost
-// bubbles to Canvas. Range (high/low) thermostats display read-only. Prop-only, token-themeable
-// (AGENTS.md §6); the service_data is built by the pure core/haControls helpers.
-import { climateNudge, climateUsesRange, type ClimateAttrs } from '../../core/haControls';
+// Interactive HA meter (molecule): a climate / A-C readout (current → target setpoint) with
+// controls — ± setpoint nudge for single-setpoint thermostats, a tap-to-cycle HVAC mode button
+// (off/cool/heat/…), and an A/C fan-mode selector (auto/low/high). Reads from the entity's JSON
+// attributes (binds: 'json'); each control emits onControl that WidgetHost bubbles to Canvas
+// (ha_call_service). Range (high/low) thermostats display the setpoint read-only. Prop-only,
+// token-themeable (AGENTS.md §6); service_data is built by the pure core/haControls helpers.
+import {
+	climateNextHvacMode,
+	climateNudge,
+	climateSetFanMode,
+	climateSetHvacMode,
+	climateUsesRange,
+	type ClimateAttrs
+} from '../../core/haControls';
 import type { ControlEvent } from '../meterProps';
 import './HaClimate.css';
 
@@ -13,9 +21,19 @@ type Props = {
 	value?: unknown;
 	label?: string;
 	onControl?: (e: ControlEvent) => void;
+	showMode?: boolean; // tap-to-cycle HVAC mode button
+	showTemp?: boolean; // ± setpoint buttons
+	showFan?: boolean; // fan-mode selector
 };
 
-export default function HaClimate({ value = null, label, onControl }: Props) {
+export default function HaClimate({
+	value = null,
+	label,
+	onControl,
+	showMode = true,
+	showTemp = true,
+	showFan = true
+}: Props) {
 	const s = (value ?? null) as HaState | null;
 	const attrs = (s?.attributes ?? {}) as ClimateAttrs & Record<string, unknown>;
 	const name = label ?? (attrs.friendly_name as string | undefined) ?? 'Climate';
@@ -24,13 +42,20 @@ export default function HaClimate({ value = null, label, onControl }: Props) {
 	const target = attrs.temperature as number | undefined;
 	const fmt = (n: number | undefined): string => (n === undefined ? '—' : `${n}°`);
 
-	// Single-setpoint, controllable thermostats get nudge buttons; range/off/unavailable display only.
-	const controllable =
-		!!onControl && mode !== 'off' && mode !== 'unavailable' && !climateUsesRange(attrs);
-	const nudge = (dir: 1 | -1) => {
-		const call = climateNudge(attrs, dir);
+	const hvacModes = (attrs.hvac_modes as string[] | undefined) ?? [];
+	const fanModes = (attrs.fan_modes as string[] | undefined) ?? [];
+	const fanMode = attrs.fan_mode as string | undefined;
+
+	// Single-setpoint controllable thermostats get nudge buttons; range/off/unavailable display only.
+	const canSetTemp =
+		showTemp && !!onControl && mode !== 'off' && mode !== 'unavailable' && !climateUsesRange(attrs);
+	const canCycleMode = showMode && !!onControl && hvacModes.length > 1;
+	const canSetFan = showFan && !!onControl && fanModes.length > 0;
+
+	const emit = (call: { service: string; data: Record<string, unknown> }): void =>
 		onControl?.({ domain: 'climate', service: call.service, data: call.data });
-	};
+	const nudge = (dir: 1 | -1) => emit(climateNudge(attrs, dir));
+	const cycleMode = () => emit(climateSetHvacMode(climateNextHvacMode(attrs, mode)));
 
 	return (
 		<div className="ha-climate np-ha-climate" data-part="root">
@@ -40,10 +65,22 @@ export default function HaClimate({ value = null, label, onControl }: Props) {
 			<span className="temps" data-part="value">
 				{fmt(current)} → {fmt(target)}
 			</span>
-			<span className="mode" data-part="mode">
-				{mode}
-			</span>
-			{controllable && (
+			{canCycleMode ? (
+				<button
+					type="button"
+					className="mode mode-btn"
+					data-part="mode"
+					aria-label={`${name} mode (tap to change)`}
+					onClick={cycleMode}
+				>
+					{mode}
+				</button>
+			) : (
+				<span className="mode" data-part="mode">
+					{mode}
+				</span>
+			)}
+			{canSetTemp && (
 				<div className="ha-climate-set" data-part="controls">
 					<button
 						type="button"
@@ -63,6 +100,26 @@ export default function HaClimate({ value = null, label, onControl }: Props) {
 					</button>
 				</div>
 			)}
+			{canSetFan && (
+				<select
+					className="ha-climate-fan"
+					data-part="fan"
+					value={fanMode ?? ''}
+					aria-label={`${name} fan mode`}
+					onChange={(e) => emit(climateSetFanMode(e.currentTarget.value))}
+				>
+					{fanMode === undefined && <option value="">fan…</option>}
+					{/* Keep the controlled value matched even if HA reports a fan_mode not in fan_modes. */}
+					{fanMode !== undefined && !fanModes.includes(fanMode) && (
+						<option value={fanMode}>{fanMode}</option>
+					)}
+					{fanModes.map((m) => (
+						<option key={m} value={m}>
+							{m}
+						</option>
+					))}
+				</select>
+			)}
 		</div>
 	);
 }
diff --git a/client/src/lib/widgets/meters/HaControls.css b/client/src/lib/widgets/meters/HaControls.css
new file mode 100644
index 0000000..3da6e3a
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaControls.css
@@ -0,0 +1,259 @@
+/* Shared styling for the Home Assistant control family (switch / scene / fan / cover / lock / input /
+   binary_sensor). Follows the HA widgets' --np-* token conventions and .np-ha-* root scoping, so user
+   themes / per-widget css targeting [data-part] or the inner class names keep matching. */
+
+/* --- button-shaped roots: switch / scene / lock --- */
+.np-ha-switch,
+.np-ha-scene,
+.np-ha-lock {
+	display: flex;
+	flex-direction: column;
+	align-items: flex-start;
+	justify-content: center;
+	gap: 2px;
+	width: 100%;
+	height: 100%;
+	padding: 0 10px;
+	box-sizing: border-box;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.8));
+	border-radius: var(--np-radius, 4px);
+	background: var(--np-bg, rgba(10, 10, 12, 0.6));
+	color: var(--np-fg, #fff);
+	font-family: var(--np-font, 'Bahnschrift', 'Arial Narrow', sans-serif);
+	text-align: left;
+	cursor: pointer;
+}
+.np-ha-switch.on,
+.np-ha-lock.locked {
+	background: var(--np-accent, rgba(119, 196, 211, 0.85));
+	color: var(--np-bg, #0a0a0c);
+}
+.np-ha-switch .label,
+.np-ha-scene .label,
+.np-ha-lock .label,
+.np-ha-fan .label,
+.np-ha-cover .label,
+.np-ha-input .label,
+.np-ha-binary .label {
+	font-size: 10px;
+	text-transform: uppercase;
+	letter-spacing: 0.5px;
+	opacity: 0.8;
+}
+.np-ha-switch .state,
+.np-ha-lock .state {
+	font-size: 16px;
+	letter-spacing: 1px;
+}
+.np-ha-scene,
+.np-ha-lock {
+	flex-direction: row;
+	align-items: center;
+	gap: 8px;
+}
+.np-ha-scene .icon {
+	font-size: 14px;
+}
+.np-ha-scene .label {
+	font-size: 13px;
+	text-transform: none;
+}
+.np-ha-lock .icon {
+	font-size: 16px;
+}
+
+/* --- fan --- */
+.np-ha-fan,
+.np-ha-cover,
+.np-ha-input,
+.np-ha-binary {
+	display: flex;
+	flex-direction: column;
+	justify-content: center;
+	gap: 3px;
+	width: 100%;
+	height: 100%;
+	padding: 0 10px;
+	box-sizing: border-box;
+	color: var(--np-fg, #fff);
+	font-family: var(--np-font, 'Bahnschrift', 'Arial Narrow', sans-serif);
+}
+.np-ha-fan {
+	gap: 4px;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.7));
+	border-radius: var(--np-radius, 4px);
+	background: var(--np-bg, rgba(10, 10, 12, 0.6));
+}
+.np-ha-fan.on {
+	border-color: var(--np-accent, rgba(119, 196, 211, 1));
+}
+.np-ha-fan .ha-fan-toggle {
+	display: flex;
+	justify-content: space-between;
+	align-items: baseline;
+	gap: 6px;
+	padding: 0;
+	border: none;
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	cursor: pointer;
+}
+.np-ha-fan .state {
+	font-size: 14px;
+}
+.np-ha-fan .ha-fan-speed,
+.np-ha-cover .ha-cover-pos,
+.np-ha-input .hi-range {
+	width: 100%;
+	accent-color: var(--np-accent, rgba(119, 196, 211, 0.9));
+	cursor: pointer;
+}
+.np-ha-fan .ha-fan-osc {
+	align-self: flex-end;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.6));
+	border-radius: var(--np-radius, 3px);
+	background: transparent;
+	color: inherit;
+	cursor: pointer;
+}
+.np-ha-fan .ha-fan-osc.on {
+	background: var(--np-accent, rgba(119, 196, 211, 0.3));
+}
+
+/* --- cover --- */
+.np-ha-cover .state {
+	font-size: 14px;
+}
+.np-ha-cover .ha-cover-btns {
+	display: flex;
+	gap: 4px;
+}
+.np-ha-cover .ha-cover-btns button {
+	flex: 1;
+	padding: 1px 0;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.6));
+	border-radius: var(--np-radius, 3px);
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	line-height: 1;
+	cursor: pointer;
+}
+.np-ha-cover .ha-cover-btns button:hover {
+	background: var(--np-accent, rgba(119, 196, 211, 0.2));
+}
+
+/* --- input_* helpers --- */
+.np-ha-input .hi-toggle,
+.np-ha-input .hi-press {
+	align-self: flex-start;
+	padding: 2px 10px;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.8));
+	border-radius: var(--np-radius, 3px);
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	cursor: pointer;
+}
+.np-ha-input .hi-toggle.on {
+	background: var(--np-accent, rgba(119, 196, 211, 0.85));
+	color: var(--np-bg, #0a0a0c);
+}
+.np-ha-input .hi-select,
+.np-ha-input .hi-text {
+	width: 100%;
+	box-sizing: border-box;
+	background: var(--np-bg, rgba(10, 10, 12, 0.6));
+	color: inherit;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.5));
+	border-radius: var(--np-radius, 3px);
+	font: inherit;
+}
+.np-ha-input .hi-num {
+	font-size: 14px;
+}
+
+/* --- binary_sensor --- */
+.np-ha-binary .value {
+	font-size: 16px;
+}
+.np-ha-binary.on .value {
+	color: var(--np-accent, rgb(119, 196, 211));
+}
+
+/* --- media_player --- */
+.np-ha-media {
+	display: flex;
+	flex-direction: row;
+	align-items: center;
+	gap: 8px;
+	width: 100%;
+	height: 100%;
+	padding: 0 10px;
+	box-sizing: border-box;
+	color: var(--np-fg, #fff);
+	font-family: var(--np-font, 'Bahnschrift', 'Arial Narrow', sans-serif);
+}
+.np-ha-media .art {
+	flex: 0 0 auto;
+	width: 56px;
+	height: 56px;
+	object-fit: cover;
+	border-radius: var(--np-radius, 4px);
+}
+.np-ha-media-body {
+	flex: 1 1 auto;
+	min-width: 0;
+	display: flex;
+	flex-direction: column;
+	justify-content: center;
+	gap: 3px;
+}
+.np-ha-media .label {
+	font-size: 10px;
+	text-transform: uppercase;
+	letter-spacing: 0.5px;
+	opacity: 0.8;
+}
+.np-ha-media .now {
+	font-size: 13px;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+.np-ha-media .ha-media-tx {
+	display: flex;
+	gap: 4px;
+}
+.np-ha-media .ha-media-tx button {
+	flex: 1;
+	padding: 1px 0;
+	border: 1px solid var(--np-accent, rgba(119, 196, 211, 0.6));
+	border-radius: var(--np-radius, 3px);
+	background: transparent;
+	color: inherit;
+	font: inherit;
+	line-height: 1;
+	cursor: pointer;
+}
+.np-ha-media .ha-media-tx button:hover {
+	background: var(--np-accent, rgba(119, 196, 211, 0.2));
+}
+.np-ha-media .ha-media-vol {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+}
+.np-ha-media .ha-media-vol button {
+	padding: 0;
+	border: none;
+	background: transparent;
+	color: inherit;
+	cursor: pointer;
+}
+.np-ha-media .ha-media-vol input {
+	flex: 1;
+	accent-color: var(--np-accent, rgba(119, 196, 211, 0.9));
+	cursor: pointer;
+}
diff --git a/client/src/lib/widgets/meters/HaCover.tsx b/client/src/lib/widgets/meters/HaCover.tsx
new file mode 100644
index 0000000..4584ad4
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaCover.tsx
@@ -0,0 +1,74 @@
+// Interactive HA meter (molecule): a cover (blinds/garage) — open / stop / close buttons + an
+// optional position slider for covers that report current_position. Reads from the entity JSON
+// (binds: 'json'); controls emit onControl (cover.open_cover / stop_cover / close_cover /
+// set_cover_position) which Canvas turns into ha_call_service. Prop-only (AGENTS.md §6).
+import { coverSetPosition } from '../../core/haControls';
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+	showButtons?: boolean;
+	showPosition?: boolean;
+};
+
+export default function HaCover({
+	value = null,
+	label,
+	onControl,
+	showButtons = true,
+	showPosition = true
+}: Props) {
+	const s = (value ?? null) as HaState | null;
+	const state = s?.state ?? '—';
+	const attrs = (s?.attributes ?? {}) as Record<string, unknown>;
+	const name = label ?? (attrs.friendly_name as string | undefined) ?? 'Cover';
+	const position = attrs.current_position as number | undefined; // 0 (closed) .. 100 (open)
+	const hasPosition = showPosition && position != null;
+
+	const call = (service: string) => onControl?.({ domain: 'cover', service });
+	const setPos = (p: number) => {
+		const c = coverSetPosition(p);
+		onControl?.({ domain: 'cover', service: c.service, data: c.data });
+	};
+
+	return (
+		<div className="ha-cover np-ha-cover" data-part="root">
+			<span className="label" data-part="label">
+				{name}
+			</span>
+			<span className="state" data-part="state">
+				{hasPosition ? `${Math.round(position)}%` : state}
+			</span>
+			{showButtons && (
+				<div className="ha-cover-btns" data-part="controls">
+					<button type="button" aria-label={`Open ${name}`} onClick={() => call('open_cover')}>
+						▲
+					</button>
+					<button type="button" aria-label={`Stop ${name}`} onClick={() => call('stop_cover')}>
+						■
+					</button>
+					<button type="button" aria-label={`Close ${name}`} onClick={() => call('close_cover')}>
+						▼
+					</button>
+				</div>
+			)}
+			{hasPosition && (
+				<input
+					type="range"
+					min={0}
+					max={100}
+					value={Math.round(position)}
+					className="ha-cover-pos"
+					data-part="position"
+					aria-label={`${name} position`}
+					onChange={(e) => setPos(Number(e.currentTarget.value))}
+				/>
+			)}
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaFan.tsx b/client/src/lib/widgets/meters/HaFan.tsx
new file mode 100644
index 0000000..1170ea5
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaFan.tsx
@@ -0,0 +1,78 @@
+// Interactive HA meter (molecule): a fan toggle + optional speed slider + oscillate toggle. Reads
+// on/off + percentage + oscillating from the entity JSON (binds: 'json'); controls emit onControl
+// (fan.toggle / set_percentage / oscillate) which Canvas turns into ha_call_service. service_data is
+// built by the pure core/haControls helper. Prop-only (AGENTS.md §6).
+import { fanSetPercentage, type FanAttrs } from '../../core/haControls';
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+	showSpeed?: boolean;
+	showOscillate?: boolean;
+};
+
+export default function HaFan({
+	value = null,
+	label,
+	onControl,
+	showSpeed = true,
+	showOscillate = true
+}: Props) {
+	const s = (value ?? null) as HaState | null;
+	const on = s?.state === 'on';
+	const attrs = (s?.attributes ?? {}) as FanAttrs & Record<string, unknown>;
+	const name = label ?? (attrs.friendly_name as string | undefined) ?? 'Fan';
+	const hasSpeed = showSpeed && on && attrs.percentage != null;
+	const pct = Math.round((attrs.percentage as number | undefined) ?? 0);
+	const canOscillate = showOscillate && on && attrs.oscillating !== undefined;
+
+	const toggle = () => onControl?.({ domain: 'fan', service: 'toggle' });
+	const setSpeed = (p: number) => {
+		const call = fanSetPercentage(p);
+		onControl?.({ domain: 'fan', service: call.service, data: call.data });
+	};
+	const oscillate = () =>
+		onControl?.({ domain: 'fan', service: 'oscillate', data: { oscillating: !attrs.oscillating } });
+
+	return (
+		<div className={`ha-fan np-ha-fan${on ? ' on' : ''}`} data-part="root">
+			<button type="button" className="ha-fan-toggle" data-part="toggle" onClick={toggle}>
+				<span className="label" data-part="label">
+					{name}
+				</span>
+				<span className="state" data-part="state">
+					{on ? (hasSpeed ? `${pct}%` : 'ON') : 'OFF'}
+				</span>
+			</button>
+			{hasSpeed && (
+				<input
+					type="range"
+					min={1}
+					max={100}
+					value={pct}
+					className="ha-fan-speed"
+					data-part="speed"
+					aria-label={`${name} speed`}
+					onChange={(e) => setSpeed(Number(e.currentTarget.value))}
+				/>
+			)}
+			{canOscillate && (
+				<button
+					type="button"
+					className={`ha-fan-osc${attrs.oscillating ? ' on' : ''}`}
+					data-part="oscillate"
+					aria-pressed={!!attrs.oscillating}
+					aria-label={`${name} oscillate`}
+					onClick={oscillate}
+				>
+					⟲
+				</button>
+			)}
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaInput.test.tsx b/client/src/lib/widgets/meters/HaInput.test.tsx
new file mode 100644
index 0000000..04e659d
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaInput.test.tsx
@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render } from '@testing-library/react';
+import HaInput from './HaInput';
+
+afterEach(cleanup);
+
+describe('HaInput infers the control from the entity domain', () => {
+	it('input_boolean → a toggle that emits ha toggle and reflects on/off', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<HaInput value={{ entity_id: 'input_boolean.x', state: 'on' }} onControl={onControl} />
+		);
+		const btn = container.querySelector('[data-part="toggle"]') as HTMLButtonElement;
+		expect(btn.textContent).toBe('ON');
+		expect(btn.getAttribute('aria-pressed')).toBe('true');
+		expect(btn.className).toContain('on');
+		fireEvent.click(btn);
+		expect(onControl).toHaveBeenCalledWith({ domain: 'input_boolean', service: 'toggle' });
+	});
+
+	it('input_boolean off renders OFF and is not pressed', () => {
+		const { container } = render(
+			<HaInput value={{ entity_id: 'input_boolean.x', state: 'off' }} />
+		);
+		const btn = container.querySelector('[data-part="toggle"]') as HTMLButtonElement;
+		expect(btn.textContent).toBe('OFF');
+		expect(btn.getAttribute('aria-pressed')).toBe('false');
+		expect(btn.className).not.toContain(' on');
+	});
+
+	it('input_button → a press button emitting the press service', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<HaInput value={{ entity_id: 'input_button.doit' }} onControl={onControl} />
+		);
+		fireEvent.click(container.querySelector('[data-part="press"]') as HTMLButtonElement);
+		expect(onControl).toHaveBeenCalledWith({ domain: 'input_button', service: 'press' });
+	});
+
+	it('input_select → a dropdown of options emitting select_option', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<HaInput
+				value={{
+					entity_id: 'input_select.mode',
+					state: 'a',
+					attributes: { options: ['a', 'b', 'c'] }
+				}}
+				onControl={onControl}
+			/>
+		);
+		const sel = container.querySelector('[data-part="select"]') as HTMLSelectElement;
+		expect(Array.from(sel.options).map((o) => o.value)).toEqual(['a', 'b', 'c']);
+		expect(sel.value).toBe('a');
+		fireEvent.change(sel, { target: { value: 'c' } });
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'input_select',
+			service: 'select_option',
+			data: { option: 'c' }
+		});
+	});
+
+	it('input_select with no options attribute renders an empty dropdown', () => {
+		const { container } = render(<HaInput value={{ entity_id: 'input_select.mode' }} />);
+		const sel = container.querySelector('[data-part="select"]') as HTMLSelectElement;
+		expect(sel.options).toHaveLength(0);
+	});
+
+	it('input_number → a range slider clamped to the helper min/max emitting set_value', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<HaInput
+				value={{
+					entity_id: 'input_number.temp',
+					state: '21',
+					attributes: { min: 10, max: 30, step: 0.5 }
+				}}
+				onControl={onControl}
+			/>
+		);
+		const range = container.querySelector('[data-part="number"]') as HTMLInputElement;
+		expect(range.min).toBe('10');
+		expect(range.max).toBe('30');
+		expect(range.step).toBe('0.5');
+		expect(range.value).toBe('21');
+		// The current numeric state is also shown as text.
+		expect(container.querySelector('.hi-num')?.textContent).toBe('21');
+		fireEvent.change(range, { target: { value: '25' } });
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'input_number',
+			service: 'set_value',
+			data: { value: 25 }
+		});
+	});
+
+	it('input_number with a non-finite state falls back to the min for the slider value', () => {
+		const { container } = render(
+			<HaInput
+				value={{ entity_id: 'input_number.temp', state: '', attributes: { min: 5, max: 9 } }}
+			/>
+		);
+		const range = container.querySelector('[data-part="number"]') as HTMLInputElement;
+		expect(range.value).toBe('5');
+	});
+
+	it('input_number with no min/max attributes defaults the slider value to 0', () => {
+		const { container } = render(
+			<HaInput value={{ entity_id: 'input_number.temp', state: 'NaN' }} />
+		);
+		const range = container.querySelector('[data-part="number"]') as HTMLInputElement;
+		expect(range.min).toBe('0');
+		expect(range.max).toBe('100');
+		expect(range.value).toBe('0');
+	});
+
+	it('input_text → a text field emitting set_value on Enter and on blur', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<HaInput value={{ entity_id: 'input_text.note', state: 'hi' }} onControl={onControl} />
+		);
+		const text = container.querySelector('[data-part="text"]') as HTMLInputElement;
+		expect(text.defaultValue).toBe('hi');
+		fireEvent.change(text, { target: { value: 'typed' } });
+		// A non-Enter key does nothing.
+		fireEvent.keyDown(text, { key: 'a' });
+		expect(onControl).not.toHaveBeenCalled();
+		fireEvent.keyDown(text, { key: 'Enter' });
+		expect(onControl).toHaveBeenLastCalledWith({
+			domain: 'input_text',
+			service: 'set_value',
+			data: { value: 'typed' }
+		});
+		fireEvent.blur(text);
+		expect(onControl).toHaveBeenCalledTimes(2);
+	});
+
+	it('an unknown / missing domain falls back to a plain value display', () => {
+		const { container } = render(<HaInput value={{ entity_id: 'sensor.x', state: '42' }} />);
+		expect(container.querySelector('[data-part="value"]')?.textContent).toBe('42');
+		expect(container.querySelector('[data-part="toggle"]')).toBeNull();
+	});
+
+	it('uses an explicit label, then the friendly_name attribute, then "Input"', () => {
+		const explicit = render(<HaInput value={{ entity_id: 'input_boolean.x' }} label="My Switch" />);
+		expect(explicit.container.querySelector('[data-part="label"]')?.textContent).toBe('My Switch');
+		explicit.unmount();
+
+		const friendly = render(
+			<HaInput value={{ entity_id: 'input_boolean.x', attributes: { friendly_name: 'Lamp' } }} />
+		);
+		expect(friendly.container.querySelector('[data-part="label"]')?.textContent).toBe('Lamp');
+		friendly.unmount();
+
+		const fallback = render(<HaInput value={null} />);
+		expect(fallback.container.querySelector('[data-part="label"]')?.textContent).toBe('Input');
+	});
+
+	it('does not throw when onControl is omitted', () => {
+		const { container } = render(<HaInput value={{ entity_id: 'input_button.x' }} />);
+		expect(() =>
+			fireEvent.click(container.querySelector('[data-part="press"]') as HTMLButtonElement)
+		).not.toThrow();
+	});
+});
diff --git a/client/src/lib/widgets/meters/HaInput.tsx b/client/src/lib/widgets/meters/HaInput.tsx
new file mode 100644
index 0000000..21aba94
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaInput.tsx
@@ -0,0 +1,135 @@
+// Interactive HA meter (molecule): a unified Home Assistant input-helper widget. It infers the
+// helper kind from the entity's domain (read off the state's entity_id) and renders the matching
+// control: input_boolean → toggle, input_button → press, input_select → dropdown, input_number →
+// slider, input_text → text field. Each emits onControl with the right {domain, service, data}, which
+// Canvas turns into ha_call_service. service_data is built by the pure core/haControls helpers.
+import type { ReactNode } from 'react';
+import {
+	entityDomain,
+	inputNumberSetValue,
+	inputSelectOption,
+	inputTextSetValue,
+	type InputNumberAttrs
+} from '../../core/haControls';
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { entity_id?: string; state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+};
+
+export default function HaInput({ value = null, label, onControl }: Props) {
+	const s = (value ?? null) as HaState | null;
+	const attrs = (s?.attributes ?? {}) as Record<string, unknown>;
+	const name = label ?? (attrs.friendly_name as string | undefined) ?? 'Input';
+	const domain = entityDomain(s?.entity_id);
+	const state = s?.state ?? '';
+	// `domain` is always a concrete input_* here (emit is only called from the per-domain control
+	// branches below, which render only when `domain` matched); the fallback is defensive belt only.
+	const emit = (service: string, data?: Record<string, unknown>): void =>
+		onControl?.({ domain: domain || 'input_boolean', service, ...(data ? { data } : {}) });
+
+	let control: ReactNode;
+	if (domain === 'input_boolean') {
+		const on = state === 'on';
+		control = (
+			<button
+				type="button"
+				className={`hi-toggle${on ? ' on' : ''}`}
+				data-part="toggle"
+				aria-pressed={on}
+				onClick={() => emit('toggle')}
+			>
+				{on ? 'ON' : 'OFF'}
+			</button>
+		);
+	} else if (domain === 'input_button') {
+		control = (
+			<button type="button" className="hi-press" data-part="press" onClick={() => emit('press')}>
+				Press
+			</button>
+		);
+	} else if (domain === 'input_select') {
+		const options = (attrs.options as string[] | undefined) ?? [];
+		control = (
+			<select
+				className="hi-select"
+				data-part="select"
+				value={state}
+				aria-label={`${name} option`}
+				onChange={(e) => {
+					const c = inputSelectOption(e.currentTarget.value);
+					emit(c.service, c.data);
+				}}
+			>
+				{options.map((o) => (
+					<option key={o} value={o}>
+						{o}
+					</option>
+				))}
+			</select>
+		);
+	} else if (domain === 'input_number') {
+		const a = attrs as InputNumberAttrs;
+		const num = Number(state);
+		control = (
+			<input
+				type="range"
+				className="hi-range"
+				data-part="number"
+				min={a.min ?? 0}
+				max={a.max ?? 100}
+				step={a.step ?? 1}
+				value={Number.isFinite(num) ? num : a.min ?? 0}
+				aria-label={`${name} value`}
+				onChange={(e) => {
+					const c = inputNumberSetValue(Number(e.currentTarget.value), a);
+					emit(c.service, c.data);
+				}}
+			/>
+		);
+	} else if (domain === 'input_text') {
+		control = (
+			<input
+				type="text"
+				className="hi-text"
+				data-part="text"
+				defaultValue={state}
+				aria-label={`${name} value`}
+				onKeyDown={(e) => {
+					if (e.key !== 'Enter') return;
+					const c = inputTextSetValue(e.currentTarget.value);
+					emit(c.service, c.data);
+				}}
+				onBlur={(e) => {
+					const c = inputTextSetValue(e.currentTarget.value);
+					emit(c.service, c.data);
+				}}
+			/>
+		);
+	} else {
+		control = (
+			<span className="value" data-part="value">
+				{state}
+			</span>
+		);
+	}
+
+	return (
+		<div className="ha-input np-ha-input" data-part="root">
+			<span className="label" data-part="label">
+				{name}
+			</span>
+			{domain === 'input_number' ? (
+				<span className="hi-num" data-part="value">
+					{state}
+				</span>
+			) : null}
+			{control}
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaLight.tsx b/client/src/lib/widgets/meters/HaLight.tsx
index 25940b1..162ba7a 100644
--- a/client/src/lib/widgets/meters/HaLight.tsx
+++ b/client/src/lib/widgets/meters/HaLight.tsx
@@ -18,14 +18,15 @@ type Props = {
 	value?: unknown;
 	label?: string;
 	onControl?: (e: ControlEvent) => void;
+	showBrightness?: boolean;
 };
 
-export default function HaLight({ value = null, label, onControl }: Props) {
+export default function HaLight({ value = null, label, onControl, showBrightness = true }: Props) {
 	const s = (value ?? null) as HaState | null;
 	const on = s?.state === 'on';
 	const attrs = (s?.attributes ?? {}) as LightAttrs & Record<string, unknown>;
 	const name = label ?? (attrs.friendly_name as string | undefined) ?? 'Light';
-	const dimmable = on && lightSupports(attrs, 'brightness');
+	const dimmable = showBrightness && on && lightSupports(attrs, 'brightness');
 	const pct = brightnessToPct(attrs.brightness as number | undefined);
 
 	const toggle = () => onControl?.({ domain: 'light', service: 'toggle' });
diff --git a/client/src/lib/widgets/meters/HaLock.tsx b/client/src/lib/widgets/meters/HaLock.tsx
new file mode 100644
index 0000000..29de8c6
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaLock.tsx
@@ -0,0 +1,40 @@
+// Interactive HA meter (molecule): a lock toggle. Reads locked/unlocked from the entity JSON
+// (binds: 'json'); a tap emits onControl (lock.lock / lock.unlock) which Canvas turns into
+// ha_call_service. Prop-only (AGENTS.md §6).
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+};
+
+export default function HaLock({ value = null, label, onControl }: Props) {
+	const s = (value ?? null) as HaState | null;
+	const state = s?.state ?? '—';
+	const locked = state === 'locked';
+	const name = label ?? (s?.attributes?.friendly_name as string | undefined) ?? 'Lock';
+
+	return (
+		<button
+			type="button"
+			className={`ha-lock np-ha-lock${locked ? ' locked' : ''}`}
+			data-part="root"
+			aria-pressed={locked}
+			onClick={() => onControl?.({ domain: 'lock', service: locked ? 'unlock' : 'lock' })}
+		>
+			<span className="icon" data-part="icon" aria-hidden="true">
+				{locked ? '🔒' : '🔓'}
+			</span>
+			<span className="label" data-part="label">
+				{name}
+			</span>
+			<span className="state" data-part="state">
+				{state}
+			</span>
+		</button>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaMediaPlayer.tsx b/client/src/lib/widgets/meters/HaMediaPlayer.tsx
new file mode 100644
index 0000000..f622d43
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaMediaPlayer.tsx
@@ -0,0 +1,112 @@
+// Interactive HA meter (molecule): a media_player — album art + now-playing text + transport (prev /
+// play-pause / next) + a volume slider with mute. Reads title/artist/state/volume from the entity
+// JSON (binds: 'json'); controls emit onControl (media_player.media_play_pause / media_next_track /
+// media_previous_track / volume_set / volume_mute) which Canvas turns into ha_call_service. volume
+// service_data is built by the pure core/haControls helper. Prop-only (AGENTS.md §6) — the `art` URL
+// is resolved by the sibling HaMediaPlayerHost (entity_picture → ha_media_art → art-scheme URL).
+import { mediaVolumeSet } from '../../core/haControls';
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+	showTransport?: boolean;
+	showVolume?: boolean;
+	art?: string; // resolved cover URL (art-scheme), supplied by the host
+};
+
+export default function HaMediaPlayer({
+	value = null,
+	label,
+	onControl,
+	showTransport = true,
+	showVolume = true,
+	art
+}: Props) {
+	const s = (value ?? null) as HaState | null;
+	const state = s?.state ?? '—';
+	const attrs = (s?.attributes ?? {}) as Record<string, unknown>;
+	const name = label ?? (attrs.friendly_name as string | undefined) ?? 'Media';
+	const title = attrs.media_title as string | undefined;
+	const artist =
+		(attrs.media_artist as string | undefined) ??
+		(attrs.media_series_title as string | undefined) ??
+		(attrs.app_name as string | undefined);
+	const playing = state === 'playing';
+	const active = state !== 'off' && state !== 'unavailable' && state !== 'standby';
+	const vol = attrs.volume_level as number | undefined; // 0..1
+	const muted = attrs.is_volume_muted === true;
+	const hasVolume = showVolume && vol != null;
+
+	const call = (service: string, data?: Record<string, unknown>): void =>
+		onControl?.({ domain: 'media_player', service, ...(data ? { data } : {}) });
+	const setVol = (pct: number): void => {
+		const c = mediaVolumeSet(pct);
+		call(c.service, c.data);
+	};
+
+	return (
+		<div className="ha-media np-ha-media" data-part="root">
+			{art ? <img className="art" data-part="art" src={art} alt="" /> : null}
+			<div className="np-ha-media-body">
+				<span className="label" data-part="label">
+					{name}
+				</span>
+				<span className="now" data-part="value">
+					{title ?? (active ? state : 'idle')}
+					{artist ? ` · ${artist}` : ''}
+				</span>
+				{showTransport && active && (
+					<div className="ha-media-tx" data-part="controls">
+						<button
+							type="button"
+							aria-label={`Previous on ${name}`}
+							onClick={() => call('media_previous_track')}
+						>
+							⏮
+						</button>
+						<button
+							type="button"
+							aria-label={playing ? `Pause ${name}` : `Play ${name}`}
+							onClick={() => call('media_play_pause')}
+						>
+							{playing ? '⏸' : '▶'}
+						</button>
+						<button
+							type="button"
+							aria-label={`Next on ${name}`}
+							onClick={() => call('media_next_track')}
+						>
+							⏭
+						</button>
+					</div>
+				)}
+				{hasVolume && (
+					<div className="ha-media-vol" data-part="volume">
+						<button
+							type="button"
+							className={muted ? 'on' : ''}
+							aria-label={`Mute ${name}`}
+							aria-pressed={muted}
+							onClick={() => call('volume_mute', { is_volume_muted: !muted })}
+						>
+							{muted ? '🔇' : '🔊'}
+						</button>
+						<input
+							type="range"
+							min={0}
+							max={100}
+							value={Math.round((vol ?? 0) * 100)}
+							aria-label={`${name} volume`}
+							onChange={(e) => setVol(Number(e.currentTarget.value))}
+						/>
+					</div>
+				)}
+			</div>
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaScene.tsx b/client/src/lib/widgets/meters/HaScene.tsx
new file mode 100644
index 0000000..81f2582
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaScene.tsx
@@ -0,0 +1,33 @@
+// Interactive HA meter (molecule): a one-tap scene activator. A scene has no on/off state, so this
+// is a button labelled with the scene name that emits onControl (scene.turn_on). Prop-only.
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+};
+
+export default function HaScene({ value = null, label, onControl }: Props) {
+	const s = (value ?? null) as HaState | null;
+	const name = label ?? (s?.attributes?.friendly_name as string | undefined) ?? 'Scene';
+
+	return (
+		<button
+			type="button"
+			className="ha-scene np-ha-scene"
+			data-part="root"
+			onClick={() => onControl?.({ domain: 'scene', service: 'turn_on' })}
+		>
+			<span className="icon" data-part="icon" aria-hidden="true">
+				▶
+			</span>
+			<span className="label" data-part="label">
+				{name}
+			</span>
+		</button>
+	);
+}
diff --git a/client/src/lib/widgets/meters/HaSwitch.tsx b/client/src/lib/widgets/meters/HaSwitch.tsx
new file mode 100644
index 0000000..26d18f5
--- /dev/null
+++ b/client/src/lib/widgets/meters/HaSwitch.tsx
@@ -0,0 +1,36 @@
+// Interactive HA meter (molecule): a switch toggle (on/off). Reads state from the entity JSON
+// (binds: 'json'); a tap emits onControl (switch.toggle), which Canvas turns into ha_call_service.
+// Prop-only + Tauri-free (AGENTS.md §6).
+import type { ControlEvent } from '../meterProps';
+import './HaControls.css';
+
+type HaState = { state?: string; attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+};
+
+export default function HaSwitch({ value = null, label, onControl }: Props) {
+	const s = (value ?? null) as HaState | null;
+	const on = s?.state === 'on';
+	const name = label ?? (s?.attributes?.friendly_name as string | undefined) ?? 'Switch';
+
+	return (
+		<button
+			type="button"
+			className={`ha-switch np-ha-switch${on ? ' on' : ''}`}
+			data-part="root"
+			aria-pressed={on}
+			onClick={() => onControl?.({ domain: 'switch', service: 'toggle' })}
+		>
+			<span className="label" data-part="label">
+				{name}
+			</span>
+			<span className="state" data-part="state">
+				{on ? 'ON' : 'OFF'}
+			</span>
+		</button>
+	);
+}
diff --git a/client/src/lib/widgets/meters/MonitorSourcesEditor.css b/client/src/lib/widgets/meters/MonitorSourcesEditor.css
new file mode 100644
index 0000000..7782731
--- /dev/null
+++ b/client/src/lib/widgets/meters/MonitorSourcesEditor.css
@@ -0,0 +1,75 @@
+/* Friendly sources editor for the Monitor Switch widget (studio Inspector). A checklist of detected
+   inputs with a rename field each. */
+.ms-src-editor {
+	display: flex;
+	flex-direction: column;
+	gap: 6px;
+	width: 100%;
+}
+
+.ms-src-head {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 8px;
+}
+.ms-src-status {
+	font-size: 0.85em;
+	opacity: 0.7;
+}
+.ms-src-scan {
+	font: inherit;
+	font-size: 0.8em;
+	padding: 2px 8px;
+	cursor: pointer;
+}
+.ms-src-scan:disabled {
+	opacity: 0.5;
+	cursor: default;
+}
+
+.ms-src-rows {
+	list-style: none;
+	margin: 0;
+	padding: 0;
+	display: flex;
+	flex-direction: column;
+	gap: 4px;
+}
+.ms-src-row {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+}
+.ms-src-row[data-off] {
+	opacity: 0.5;
+}
+.ms-src-check {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	flex: 0 0 auto;
+	min-width: 7.5em;
+	cursor: pointer;
+}
+.ms-src-name {
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+.ms-src-label {
+	flex: 1 1 auto;
+	min-width: 0;
+}
+
+.ms-src-empty {
+	font-size: 0.85em;
+	opacity: 0.8;
+	display: flex;
+	flex-direction: column;
+	gap: 6px;
+}
+.ms-src-empty code {
+	font-size: 0.95em;
+	opacity: 0.9;
+}
diff --git a/client/src/lib/widgets/meters/MonitorSourcesEditor.test.tsx b/client/src/lib/widgets/meters/MonitorSourcesEditor.test.tsx
new file mode 100644
index 0000000..218f128
--- /dev/null
+++ b/client/src/lib/widgets/meters/MonitorSourcesEditor.test.tsx
@@ -0,0 +1,147 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, waitFor, fireEvent, cleanup } from '@testing-library/react';
+
+// Stub the Tauri-backed DDC adapter: the editor must still scan the chosen monitor's inputs and round-
+// trip include/rename edits through the same `code=label` spec the widget consumes.
+const { listMonitorInputs } = vi.hoisted(() => ({ listMonitorInputs: vi.fn() }));
+vi.mock('../../ddc/monitors', () => ({ listMonitorInputs }));
+
+import MonitorSourcesEditor from './MonitorSourcesEditor';
+import type { MonitorInputs } from '../../ddc/monitors';
+
+const mon = (over: Partial<MonitorInputs> = {}): MonitorInputs => ({
+	gdi: '\\\\.\\DISPLAY1',
+	friendly: 'Dell',
+	primary: true,
+	current_input: 0x11,
+	supported: [0x0f, 0x11], // DisplayPort 1, HDMI 1
+	width: 0,
+	height: 0,
+	refresh_hz: 0,
+	...over
+});
+
+beforeEach(() => {
+	listMonitorInputs.mockReset();
+	listMonitorInputs.mockResolvedValue([mon()]);
+});
+
+describe('MonitorSourcesEditor (config form)', () => {
+	it('scans the primary monitor and renders one checklist row per detected input', async () => {
+		const { container } = render(
+			<MonitorSourcesEditor value="" monitor="" onChange={() => undefined} />
+		);
+		expect(listMonitorInputs).toHaveBeenCalledWith(undefined); // '' monitor → primary
+		await waitFor(() => expect(container.querySelectorAll('.ms-src-row')).toHaveLength(2));
+		expect(container.querySelector('.ms-src-status')?.textContent).toBe('2 inputs');
+		// blank spec = auto: every detected input checked
+		const checks = [...container.querySelectorAll<HTMLInputElement>('.ms-src-check input')];
+		expect(checks.every((c) => c.checked)).toBe(true);
+	});
+
+	it('falls back to the first monitor when none reports primary', async () => {
+		listMonitorInputs.mockResolvedValue([
+			mon({ primary: false, supported: [0x0f] }),
+			mon({ gdi: '\\\\.\\DISPLAY2', primary: false, supported: [0x12] })
+		]);
+		const { container } = render(
+			<MonitorSourcesEditor value="" monitor="" onChange={() => undefined} />
+		);
+		// no primary → list[0], whose single input is DisplayPort 1
+		await waitFor(() => expect(container.querySelectorAll('.ms-src-row')).toHaveLength(1));
+		expect(container.querySelector('.ms-src-name')?.textContent).toBe('DisplayPort 1');
+	});
+
+	it('scans the configured monitor by GDI name', async () => {
+		listMonitorInputs.mockResolvedValue([
+			mon({ gdi: '\\\\.\\DISPLAY2', primary: false, supported: [0x12] })
+		]);
+		const { container } = render(
+			<MonitorSourcesEditor value="" monitor={'\\\\.\\DISPLAY2'} onChange={() => undefined} />
+		);
+		await waitFor(() => expect(listMonitorInputs).toHaveBeenCalledWith('\\\\.\\DISPLAY2'));
+		await waitFor(() => expect(container.querySelectorAll('.ms-src-row')).toHaveLength(1));
+		expect(container.querySelector('.ms-src-name')?.textContent).toBe('HDMI 2');
+	});
+
+	it('singularises the count for one input', async () => {
+		listMonitorInputs.mockResolvedValue([mon({ supported: [0x0f] })]);
+		const { container } = render(
+			<MonitorSourcesEditor value="" monitor="" onChange={() => undefined} />
+		);
+		await waitFor(() =>
+			expect(container.querySelector('.ms-src-status')?.textContent).toBe('1 input')
+		);
+	});
+
+	it('toggling an input off emits a spec listing only the remaining included inputs', async () => {
+		const onChange = vi.fn();
+		const { container } = render(<MonitorSourcesEditor value="" monitor="" onChange={onChange} />);
+		await waitFor(() => expect(container.querySelectorAll('.ms-src-row')).toHaveLength(2));
+		const firstCheck = container.querySelector<HTMLInputElement>('.ms-src-check input')!;
+		fireEvent.click(firstCheck); // uncheck DisplayPort 1 (0x0f)
+		// auto no longer holds → explicit spec of just the still-included HDMI 1 (0x11)
+		expect(onChange).toHaveBeenCalledWith('0x11');
+	});
+
+	it('renaming an input emits `code=label` and strips the spec separator (comma)', async () => {
+		const onChange = vi.fn();
+		const { container } = render(<MonitorSourcesEditor value="" monitor="" onChange={onChange} />);
+		await waitFor(() => expect(container.querySelectorAll('.ms-src-row')).toHaveLength(2));
+		const firstLabel = container.querySelector<HTMLInputElement>('.ms-src-label')!;
+		// (A text <input> strips newlines per the HTML spec, so the comma is what exercises the
+		// component's own [,\n] → space replacement.)
+		fireEvent.change(firstLabel, { target: { value: 'Work,PC' } });
+		// comma collapsed to a space so the spec stays parseable; HDMI 1 (auto) tails along
+		expect(onChange).toHaveBeenLastCalledWith('0xf=Work PC, 0x11');
+	});
+
+	it('reflects an existing spec: only listed inputs checked, custom label shown', async () => {
+		const { container } = render(
+			<MonitorSourcesEditor value="0x11=Switch" monitor="" onChange={() => undefined} />
+		);
+		await waitFor(() => expect(container.querySelectorAll('.ms-src-row')).toHaveLength(2));
+		const checks = [...container.querySelectorAll<HTMLInputElement>('.ms-src-check input')];
+		// DisplayPort 1 not in the spec → unchecked; HDMI 1 in the spec → checked
+		expect(checks[0].checked).toBe(false);
+		expect(checks[1].checked).toBe(true);
+		const labels = [...container.querySelectorAll<HTMLInputElement>('.ms-src-label')];
+		expect(labels[1].value).toBe('Switch');
+		// the unchecked row's label field is disabled
+		expect(labels[0].disabled).toBe(true);
+	});
+
+	it('falls back to a manual text field when nothing is detected and the spec is blank', async () => {
+		// No detected inputs AND an empty spec → no rows synthesised → the manual entry fallback.
+		// (A non-empty spec would synthesise manual rows and keep the checklist instead.)
+		listMonitorInputs.mockResolvedValue([mon({ supported: [] })]);
+		const onChange = vi.fn();
+		const { container } = render(<MonitorSourcesEditor value="" monitor="" onChange={onChange} />);
+		await waitFor(() => expect(container.querySelector('.ms-src-empty')).not.toBeNull());
+		expect(container.querySelector('.ms-src-row')).toBeNull();
+		const field = container.querySelector<HTMLInputElement>('.ms-src-empty input')!;
+		expect(field.value).toBe('');
+		fireEvent.change(field, { target: { value: '0x12=Switch' } });
+		expect(onChange).toHaveBeenCalledWith('0x12=Switch'); // raw passthrough, no spec rebuild
+	});
+
+	it('shows the manual fallback when no monitors are listed at all', async () => {
+		listMonitorInputs.mockResolvedValue([]); // no target → detected = []
+		const { container } = render(
+			<MonitorSourcesEditor value="" monitor="" onChange={() => undefined} />
+		);
+		await waitFor(() => expect(container.querySelector('.ms-src-empty')).not.toBeNull());
+		expect(container.querySelector('.ms-src-row')).toBeNull();
+	});
+
+	it('rescans on demand', async () => {
+		const { container } = render(
+			<MonitorSourcesEditor value="" monitor="" onChange={() => undefined} />
+		);
+		await waitFor(() => expect(container.querySelector('.ms-src-scan')).not.toBeNull());
+		expect(listMonitorInputs).toHaveBeenCalledTimes(1);
+		fireEvent.click(container.querySelector('.ms-src-scan')!);
+		await waitFor(() => expect(listMonitorInputs).toHaveBeenCalledTimes(2));
+		cleanup();
+	});
+});
diff --git a/client/src/lib/widgets/meters/MonitorSourcesEditor.tsx b/client/src/lib/widgets/meters/MonitorSourcesEditor.tsx
new file mode 100644
index 0000000..1548afb
--- /dev/null
+++ b/client/src/lib/widgets/meters/MonitorSourcesEditor.tsx
@@ -0,0 +1,95 @@
+// Studio Inspector editor for the Monitor Switch widget's `sources` config. Replaces the raw hex spec
+// with a friendly checklist: it detects the chosen monitor's inputs (DDC/CI) and lets you pick which to
+// show and rename each (e.g. "HDMI 2" → "Switch 2"). It reads/writes the same `code=label` spec string
+// the widget already consumes (core/monitorInputs `sourceEditorRows` / `buildSourceSpec`), so the
+// stored config is unchanged. Studio-only (it calls a Tauri command); degrades to a plain text field
+// when no inputs can be detected (DDC/CI off, dev mock, or a monitor that doesn't report them).
+import { useCallback, useEffect, useState } from 'react';
+import { listMonitorInputs } from '../../ddc/monitors';
+import { buildSourceSpec, sourceEditorRows, type SourceEditorRow } from '../../core/monitorInputs';
+import './MonitorSourcesEditor.css';
+
+type Props = {
+	value: string; // current `sources` spec (code=label, comma-separated)
+	monitor: string; // configured GDI device name ('' = the primary monitor)
+	onChange: (spec: string) => void;
+};
+
+export default function MonitorSourcesEditor({ value, monitor, onChange }: Props) {
+	const [detected, setDetected] = useState<number[]>([]);
+	const [loading, setLoading] = useState(true);
+
+	const scan = useCallback(async (): Promise<void> => {
+		setLoading(true);
+		const list = await listMonitorInputs(monitor || undefined);
+		const target = monitor
+			? list.find((m) => m.gdi === monitor)
+			: list.find((m) => m.primary) ?? list[0];
+		setDetected(target?.supported ?? []);
+		setLoading(false);
+	}, [monitor]);
+
+	useEffect(() => {
+		void scan();
+	}, [scan]);
+
+	const rows = sourceEditorRows(detected, value);
+	const emit = (next: SourceEditorRow[]): void => onChange(buildSourceSpec(next));
+	const toggle = (i: number): void =>
+		emit(rows.map((r, j) => (j === i ? { ...r, include: !r.include } : r)));
+	// Commas/newlines are the spec's separators, so strip them from a label to keep it parseable.
+	const rename = (i: number, label: string): void =>
+		emit(rows.map((r, j) => (j === i ? { ...r, label: label.replace(/[,\n]/g, ' ') } : r)));
+
+	return (
+		<div className="ms-src-editor">
+			<div className="ms-src-head">
+				<span className="ms-src-status">
+					{loading ? 'detecting inputs…' : `${rows.length} input${rows.length === 1 ? '' : 's'}`}
+				</span>
+				<button
+					type="button"
+					className="ms-src-scan"
+					onClick={() => void scan()}
+					disabled={loading}
+				>
+					rescan
+				</button>
+			</div>
+			{rows.length === 0 ? (
+				<div className="ms-src-empty">
+					No inputs detected — DDC/CI may be off in the monitor’s menu, or it doesn’t report them.
+					Enter codes manually, e.g. <code>0x11=Desktop, 0x12=Switch</code>:
+					<input
+						type="text"
+						value={value}
+						placeholder="0x11=Desktop, 0x12=Switch"
+						onChange={(e) => onChange(e.currentTarget.value)}
+					/>
+				</div>
+			) : (
+				<ul className="ms-src-rows">
+					{rows.map((r, i) => (
+						<li key={r.value} className="ms-src-row" data-off={!r.include || undefined}>
+							<label className="ms-src-check">
+								<input type="checkbox" checked={r.include} onChange={() => toggle(i)} />
+								<span className="ms-src-name">
+									{r.defaultName}
+									{r.detected ? '' : ' (manual)'}
+								</span>
+							</label>
+							<input
+								type="text"
+								className="ms-src-label"
+								value={r.label}
+								placeholder={r.defaultName}
+								disabled={!r.include}
+								onChange={(e) => rename(i, e.currentTarget.value)}
+							/>
+						</li>
+					))}
+				</ul>
+			)}
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/MonitorSwitch.css b/client/src/lib/widgets/meters/MonitorSwitch.css
new file mode 100644
index 0000000..f649790
--- /dev/null
+++ b/client/src/lib/widgets/meters/MonitorSwitch.css
@@ -0,0 +1,118 @@
+/* Monitor Switch — a title (+ optional resolution/refresh stats) and one clickable row per input
+   source; the active input is marked. Rows are bare buttons (overlay-interactive). Themeable via
+   --np-* / --ms-* tokens (mirrors the Audio Switcher). */
+.monitorswitch {
+	display: flex;
+	flex-direction: column;
+	gap: var(--ms-gap, 3px);
+	width: 100%;
+	height: 100%;
+	box-sizing: border-box;
+	overflow: hidden;
+	font-family: var(--np-font-display, 'Bahnschrift', 'Arial Narrow', sans-serif);
+	color: var(--np-fg, rgb(255, 255, 255));
+}
+
+.ms-head {
+	flex: 0 0 auto;
+	display: flex;
+	align-items: baseline;
+	justify-content: space-between;
+	gap: 8px;
+}
+.ms-title {
+	font-size: var(--ms-title-size, 0.66em);
+	letter-spacing: 0.04em;
+	text-transform: uppercase;
+	color: var(--np-label, rgba(255, 255, 255, 0.5));
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+.ms-stats {
+	flex: 0 0 auto;
+	font-size: var(--ms-stats-size, 0.6em);
+	color: var(--np-label, rgba(255, 255, 255, 0.4));
+	white-space: nowrap;
+}
+
+.ms-list {
+	display: flex;
+	flex-flow: row wrap;
+	gap: var(--ms-row-gap, 6px);
+	align-content: flex-start;
+	min-height: 0;
+	overflow: auto;
+}
+.ms-row {
+	/* Big, tiled, finger-friendly buttons (wrap to fill the widget). */
+	flex: 1 1 var(--ms-btn-min, 84px);
+	min-width: var(--ms-btn-min, 84px);
+	min-height: var(--ms-btn-h, 44px); /* >= 44px: the common minimum touch target */
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: 8px 12px;
+	border: 1px solid var(--ms-border, rgba(255, 255, 255, 0.16));
+	border-radius: var(--ms-radius, 8px);
+	background: var(--ms-row-bg, rgba(255, 255, 255, 0.06));
+	color: inherit;
+	font: inherit;
+	font-size: var(--ms-row-size, 0.95em);
+	text-align: center;
+	cursor: pointer;
+	transition: background 0.12s ease, border-color 0.12s ease;
+	/* Touch ergonomics: no tap flash, no double-tap zoom, no text selection on press. */
+	-webkit-tap-highlight-color: transparent;
+	touch-action: manipulation;
+	user-select: none;
+}
+.ms-row:hover {
+	background: var(--ms-row-hover, rgba(255, 255, 255, 0.14));
+}
+.ms-row:active {
+	transform: translateY(1px);
+}
+.ms-row[data-active] {
+	background: var(--ms-active-bg, rgba(119, 196, 211, 0.22));
+	border-color: var(--ms-accent, var(--np-accent, rgb(119, 196, 211)));
+	font-weight: 600;
+}
+.ms-row[data-busy] {
+	opacity: 0.6;
+	cursor: progress;
+}
+
+.ms-name {
+	min-width: 0;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+/* Compact mode: a tight single-column list (the original look) instead of large touch buttons. */
+.monitorswitch[data-compact] .ms-list {
+	flex-direction: column;
+	flex-wrap: nowrap;
+	gap: var(--ms-row-gap, 2px);
+}
+.monitorswitch[data-compact] .ms-row {
+	flex: 0 0 auto;
+	min-width: 0;
+	min-height: 0;
+	justify-content: flex-start;
+	padding: 2px 8px;
+	border: 0;
+	border-radius: var(--ms-radius, 5px);
+	font-size: var(--ms-row-size-compact, 0.86em);
+	font-weight: 400;
+	text-align: left;
+}
+.monitorswitch[data-compact] .ms-row[data-active] {
+	font-weight: 600;
+}
+
+.ms-empty {
+	color: var(--np-label, rgba(255, 255, 255, 0.4));
+	font-size: 0.9em;
+}
diff --git a/client/src/lib/widgets/meters/MonitorSwitch.test.tsx b/client/src/lib/widgets/meters/MonitorSwitch.test.tsx
new file mode 100644
index 0000000..f6bce0b
--- /dev/null
+++ b/client/src/lib/widgets/meters/MonitorSwitch.test.tsx
@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { render, cleanup, fireEvent } from '@testing-library/react';
+import MonitorSwitch from './MonitorSwitch';
+import type { MonitorInputRow } from '../../core/monitorInputs';
+
+afterEach(cleanup);
+
+const rows: MonitorInputRow[] = [
+	{ value: 0x0f, label: 'DisplayPort 1', active: false },
+	{ value: 0x11, label: 'HDMI 1', active: true }
+];
+
+describe('MonitorSwitch meter', () => {
+	it('renders the title and one row per input, marking the active one', () => {
+		const { container } = render(
+			<MonitorSwitch title="Desk" rows={rows} onPick={() => undefined} />
+		);
+		expect(container.querySelector('.ms-title')?.textContent).toBe('Desk');
+		const els = container.querySelectorAll('.ms-row');
+		expect(els).toHaveLength(2);
+		const active = [...els].find((r) => r.getAttribute('data-active') === 'true');
+		expect(active?.textContent).toContain('HDMI 1');
+	});
+
+	it('calls onPick with the VCP value on click', () => {
+		const onPick = vi.fn();
+		const { container } = render(<MonitorSwitch title="Desk" rows={rows} onPick={onPick} />);
+		const dp = [...container.querySelectorAll('.ms-row')].find((r) =>
+			r.textContent?.includes('DisplayPort 1')
+		);
+		fireEvent.click(dp as Element);
+		expect(onPick).toHaveBeenCalledWith(0x0f);
+	});
+
+	it('shows the stats line only when enabled and present', () => {
+		const { container, rerender } = render(
+			<MonitorSwitch title="Desk" rows={rows} stats="2560×1440 · 144 Hz" onPick={() => undefined} />
+		);
+		expect(container.querySelector('.ms-stats')).toBeNull();
+		rerender(
+			<MonitorSwitch
+				title="Desk"
+				rows={rows}
+				stats="2560×1440 · 144 Hz"
+				showStats
+				onPick={() => undefined}
+			/>
+		);
+		expect(container.querySelector('.ms-stats')?.textContent).toBe('2560×1440 · 144 Hz');
+	});
+
+	it('marks the busy input while a switch is in flight', () => {
+		const { container } = render(
+			<MonitorSwitch title="Desk" rows={rows} busyValue={0x0f} onPick={() => undefined} />
+		);
+		const busy = [...container.querySelectorAll('.ms-row')].find(
+			(r) => r.getAttribute('data-busy') === 'true'
+		);
+		expect(busy?.textContent).toContain('DisplayPort 1');
+	});
+
+	it('shows a "monitor not found" hint when missing', () => {
+		const { container } = render(
+			<MonitorSwitch title="Desk" rows={rows} missing onPick={() => undefined} />
+		);
+		expect(container.querySelector('.ms-empty')?.textContent).toBe('monitor not found');
+		expect(container.querySelector('.ms-row')).toBeNull();
+	});
+
+	it('shows a dash placeholder when there are no input rows (and not missing)', () => {
+		const { container } = render(<MonitorSwitch title="Desk" rows={[]} onPick={() => undefined} />);
+		const empty = container.querySelector('.ms-empty');
+		expect(empty?.textContent).toBe('—');
+		expect(container.querySelector('.ms-row')).toBeNull();
+	});
+
+	it('applies the accent color var and compact attribute when set', () => {
+		const { container } = render(
+			<MonitorSwitch title="Desk" rows={rows} compact color="#abc" onPick={() => undefined} />
+		);
+		const root = container.querySelector('.monitorswitch') as HTMLElement;
+		expect(root.getAttribute('data-compact')).toBe('true');
+		expect(root.style.getPropertyValue('--ms-accent')).toBe('#abc');
+	});
+});
diff --git a/client/src/lib/widgets/meters/MonitorSwitch.tsx b/client/src/lib/widgets/meters/MonitorSwitch.tsx
new file mode 100644
index 0000000..a93bc69
--- /dev/null
+++ b/client/src/lib/widgets/meters/MonitorSwitch.tsx
@@ -0,0 +1,75 @@
+// Monitor Switch meter (presentational, props-only). Renders a title (+ optional resolution/refresh
+// stats) and one clickable row per selectable input source, marking the active one. The wiring (list
+// monitors, read current input, switch via DDC/CI) lives in the sibling MonitorSwitchHost; this just
+// renders rows and calls `onPick`. BARE DOM; styled in MonitorSwitch.css via --np-* / --ms-* tokens.
+import type { CSSProperties } from 'react';
+import type { MonitorInputRow } from '../../core/monitorInputs';
+import './MonitorSwitch.css';
+
+type Props = {
+	title: string;
+	rows: MonitorInputRow[];
+	stats?: string;
+	showStats?: boolean;
+	busyValue?: number | null;
+	// The configured monitor isn't present (unplugged / switched away / wrong id) — show a hint
+	// instead of buttons that would target nothing.
+	missing?: boolean;
+	// Compact list (small rows) instead of the default large touch buttons.
+	compact?: boolean;
+	onPick: (value: number) => void;
+	color?: string;
+};
+
+export default function MonitorSwitch({
+	title,
+	rows,
+	stats,
+	showStats,
+	busyValue,
+	missing,
+	compact,
+	onPick,
+	color
+}: Props) {
+	const vars = color ? ({ '--ms-accent': color } as CSSProperties) : undefined;
+
+	return (
+		<div
+			className="monitorswitch np-monitorswitch"
+			data-compact={compact || undefined}
+			style={vars}
+		>
+			<div className="ms-head">
+				<span className="ms-title">{title}</span>
+				{showStats && stats ? <span className="ms-stats">{stats}</span> : null}
+			</div>
+			{missing ? (
+				<div className="ms-empty" data-part="empty">
+					monitor not found
+				</div>
+			) : rows.length === 0 ? (
+				<div className="ms-empty" data-part="empty">
+					—
+				</div>
+			) : (
+				<div className="ms-list">
+					{rows.map((r) => (
+						<button
+							type="button"
+							key={r.value}
+							className="ms-row"
+							data-active={r.active || undefined}
+							data-busy={busyValue === r.value || undefined}
+							aria-pressed={r.active || undefined}
+							onClick={() => onPick(r.value)}
+							title={r.label}
+						>
+							<span className="ms-name">{r.label}</span>
+						</button>
+					))}
+				</div>
+			)}
+		</div>
+	);
+}
diff --git a/client/src/lib/widgets/meters/NowPlaying.test.tsx b/client/src/lib/widgets/meters/NowPlaying.test.tsx
index c87c9b1..79fb009 100644
--- a/client/src/lib/widgets/meters/NowPlaying.test.tsx
+++ b/client/src/lib/widgets/meters/NowPlaying.test.tsx
@@ -1,7 +1,41 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { act, fireEvent, render, waitFor } from '@testing-library/react';
+import { act, createEvent, fireEvent, render, waitFor } from '@testing-library/react';
 import NowPlaying from './NowPlaying';
-import type { SessionRecord } from '../../../stores/stores';
+import type { AutoRepeat, PlaybackStatus, SessionRecord } from '../../../stores/stores';
+
+// happy-dom's TransitionEvent constructor drops `propertyName`, so fireEvent.transitionEnd(el, {…})
+// can't carry it — the meter filters on e.propertyName === 'opacity'. Build the event and pin the
+// property explicitly so the real handler runs (or short-circuits) as it would in a browser.
+function fireTransitionEnd(el: Element, propertyName: string) {
+	const ev = createEvent.transitionEnd(el);
+	Object.defineProperty(ev, 'propertyName', { value: propertyName });
+	fireEvent(el, ev);
+}
+
+// The transport buttons read playback/timeline from last_model_update.Model (the live model), with
+// the media model only as a fallback. Set the model directly so play state / repeat / shuffle / seek
+// reflect what we intend (the bare session() fixture leaves Model.playback null).
+function withModel(
+	s: SessionRecord,
+	model: { status?: PlaybackStatus; shuffle?: boolean; auto_repeat?: AutoRepeat },
+	timeline?: { start: number; end: number; position: number }
+): SessionRecord {
+	s.last_model_update = {
+		Model: {
+			playback: {
+				auto_repeat: model.auto_repeat ?? 'None',
+				rate: 1,
+				shuffle: model.shuffle ?? false,
+				status: model.status ?? 'Playing',
+				type: 'Music'
+			},
+			timeline: timeline ? { ...timeline, last_updated_at_ms: 0 } : null,
+			media: null,
+			source: s.source
+		}
+	};
+	return s;
+}
 
 // The cover is now a backend-served URL (art.rs), so the meter just sets it as the <img src> — no
 // object URLs to stub. artKey is the url itself, so a distinct url = a distinct cover (crossfade).
@@ -123,3 +157,493 @@ describe('NowPlaying — capabilities', () => {
 		});
 	});
 });
+
+describe('NowPlaying — transport controls', () => {
+	it('bubbles previous / stop / next with just the source (no value)', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<NowPlaying session={session('Song A', ART)} onControl={onControl} />
+		);
+		for (const [part, service] of [
+			['prev', 'previous'],
+			['stop', 'stop'],
+			['next', 'next']
+		] as const) {
+			onControl.mockClear();
+			fireEvent.click(container.querySelector(`[data-part="${part}"]`) as HTMLElement);
+			expect(onControl).toHaveBeenCalledWith({
+				domain: 'media',
+				service,
+				data: { source: 'spotify.exe' }
+			});
+		}
+	});
+
+	it('shuffle press sends the toggled value (off → 1) and is not active when off', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<NowPlaying session={session('Song A', ART)} onControl={onControl} />
+		);
+		const btn = container.querySelector('[data-part="shuffle"]') as HTMLElement;
+		expect(btn.getAttribute('data-active')).toBe('false');
+		expect(btn.getAttribute('aria-pressed')).toBe('false');
+		fireEvent.click(btn);
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'shuffle',
+			data: { source: 'spotify.exe', value: 1 }
+		});
+	});
+
+	it('shuffle press sends 0 when already on (reflected via data-active / aria-pressed)', () => {
+		const onControl = vi.fn();
+		const s = withModel(session('Song A', ART), { shuffle: true });
+		const { container } = render(<NowPlaying session={s} onControl={onControl} />);
+		const btn = container.querySelector('[data-part="shuffle"]') as HTMLElement;
+		expect(btn.getAttribute('data-active')).toBe('true');
+		expect(btn.getAttribute('aria-pressed')).toBe('true');
+		fireEvent.click(btn);
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'shuffle',
+			data: { source: 'spotify.exe', value: 0 }
+		});
+	});
+
+	it('repeat cycles None → Track (sends value 1) and shows the loop glyph + mode', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<NowPlaying session={session('Song A', ART)} onControl={onControl} />
+		);
+		const btn = container.querySelector('[data-part="repeat"]') as HTMLElement;
+		expect(btn.getAttribute('data-mode')).toBe('None');
+		expect(btn.getAttribute('aria-label')).toBe('Repeat: None');
+		expect(btn.textContent).toBe('🔁');
+		fireEvent.click(btn);
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'repeat',
+			data: { source: 'spotify.exe', value: 1 }
+		});
+	});
+
+	it('repeat in Track mode shows the single-track glyph and cycles to List (value 2)', () => {
+		const onControl = vi.fn();
+		const s = withModel(session('Song A', ART), { auto_repeat: 'Track' });
+		const { container } = render(<NowPlaying session={s} onControl={onControl} />);
+		const btn = container.querySelector('[data-part="repeat"]') as HTMLElement;
+		expect(btn.getAttribute('data-mode')).toBe('Track');
+		expect(btn.textContent).toBe('🔂');
+		fireEvent.click(btn);
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'repeat',
+			data: { source: 'spotify.exe', value: 2 }
+		});
+	});
+
+	it('repeat in List mode cycles back to None (value 0)', () => {
+		const onControl = vi.fn();
+		const s = withModel(session('Song A', ART), { auto_repeat: 'List' });
+		const { container } = render(<NowPlaying session={s} onControl={onControl} />);
+		const btn = container.querySelector('[data-part="repeat"]') as HTMLElement;
+		fireEvent.click(btn);
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'repeat',
+			data: { source: 'spotify.exe', value: 0 }
+		});
+	});
+
+	it('play/pause shows the pause glyph while playing and the play glyph while paused', () => {
+		const playingS = withModel(session('Song A', ART), { status: 'Playing' });
+		const { container, rerender } = render(<NowPlaying session={playingS} />);
+		expect(container.querySelector('[data-part="playpause"]')!.textContent).toBe('⏸');
+		expect(container.querySelector('[data-part="root"]')!.getAttribute('data-playing')).toBe(
+			'true'
+		);
+		const paused = withModel(session('Song A', ART), { status: 'Paused' });
+		rerender(<NowPlaying session={paused} />);
+		expect(container.querySelector('[data-part="playpause"]')!.textContent).toBe('▶');
+		expect(container.querySelector('[data-part="root"]')!.getAttribute('data-playing')).toBe(
+			'false'
+		);
+	});
+
+	it('omits source from the payload when the session has no source', () => {
+		const onControl = vi.fn();
+		const s = session('Song A', ART);
+		s.source = '';
+		s.last_media_update!.Media[0].source = '';
+		const { container } = render(<NowPlaying session={s} onControl={onControl} />);
+		fireEvent.click(container.querySelector('[data-part="next"]') as HTMLElement);
+		expect(onControl).toHaveBeenCalledWith({ domain: 'media', service: 'next', data: {} });
+	});
+
+	it('a transport press stops propagation (does not reach the widget behind it)', () => {
+		const onControl = vi.fn();
+		const behind = vi.fn();
+		const { container } = render(
+			<div onClick={behind}>
+				<NowPlaying session={session('Song A', ART)} onControl={onControl} />
+			</div>
+		);
+		fireEvent.click(container.querySelector('[data-part="next"]') as HTMLElement);
+		expect(onControl).toHaveBeenCalledTimes(1);
+		expect(behind).not.toHaveBeenCalled();
+	});
+
+	it('does nothing on a transport press when no onControl is wired (optional chaining)', () => {
+		const { container } = render(<NowPlaying session={session('Song A', ART)} />);
+		// No onControl prop: the click must not throw.
+		expect(() =>
+			fireEvent.click(container.querySelector('[data-part="next"]') as HTMLElement)
+		).not.toThrow();
+	});
+});
+
+// The progress bar is hidden by default but is a live, click-to-seek control when the session
+// reports `seek` support. The position/duration timers render the formatted time from the timeline.
+describe('NowPlaying — seek + timeline', () => {
+	const seekableSession = (): SessionRecord => {
+		const s = session('Song A', ART);
+		// liveModel falls back to the media model; give it a real timeline for position/duration.
+		s.last_model_update = {
+			Model: {
+				playback: {
+					auto_repeat: 'None',
+					rate: 1,
+					shuffle: false,
+					status: 'Playing',
+					type: 'Music'
+				},
+				timeline: { start: 0, end: 200, position: 65, last_updated_at_ms: 0 },
+				media: null,
+				source: 'spotify.exe'
+			}
+		};
+		return s;
+	};
+	const caps = {
+		play: true,
+		pause: true,
+		playpause: true,
+		stop: true,
+		next: true,
+		previous: true,
+		shuffle: true,
+		repeat: true,
+		seek: true
+	};
+
+	it('renders position / duration timers and the fill width from the timeline', () => {
+		const { container } = render(<NowPlaying session={seekableSession()} />);
+		expect(container.querySelector('[data-part="position"]')!.textContent).toBe('1:05');
+		expect(container.querySelector('[data-part="duration"]')!.textContent).toBe('3:20');
+		// 65 / 200 = 32.5%
+		expect(
+			(container.querySelector('[data-part="progress-fill"]') as HTMLElement).style.width
+		).toBe('32.5%');
+	});
+
+	it('clicking the seekable progress bar sends seek to the clicked fraction of the duration', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<NowPlaying session={seekableSession()} caps={caps} onControl={onControl} />
+		);
+		const bar = container.querySelector('[data-part="progress"]') as HTMLElement;
+		expect(bar.getAttribute('data-seekable')).toBe('true');
+		// happy-dom getBoundingClientRect returns zeros; stub a 200px-wide bar so the fraction is real.
+		bar.getBoundingClientRect = () =>
+			({ left: 0, width: 200, top: 0, height: 4, right: 200, bottom: 4, x: 0, y: 0 } as DOMRect);
+		fireEvent.click(bar, { clientX: 100 }); // halfway → 0.5 * 200 = 100
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'seek',
+			data: { source: 'spotify.exe', value: 100 }
+		});
+	});
+
+	it('clamps a seek click past the right edge to the end of the track', () => {
+		const onControl = vi.fn();
+		const { container } = render(
+			<NowPlaying session={seekableSession()} caps={caps} onControl={onControl} />
+		);
+		const bar = container.querySelector('[data-part="progress"]') as HTMLElement;
+		bar.getBoundingClientRect = () =>
+			({ left: 0, width: 200, top: 0, height: 4, right: 200, bottom: 4, x: 0, y: 0 } as DOMRect);
+		fireEvent.click(bar, { clientX: 9999 }); // past the end → clamped to frac 1 → full duration
+		expect(onControl).toHaveBeenCalledWith({
+			domain: 'media',
+			service: 'seek',
+			data: { source: 'spotify.exe', value: 200 }
+		});
+	});
+
+	it('a seek click with a zero-duration timeline is a no-op', () => {
+		const onControl = vi.fn();
+		const s = seekableSession();
+		s.last_model_update!.Model.timeline!.end = 0;
+		const { container } = render(<NowPlaying session={s} caps={caps} onControl={onControl} />);
+		const bar = container.querySelector('[data-part="progress"]') as HTMLElement;
+		fireEvent.click(bar, { clientX: 50 });
+		expect(onControl).not.toHaveBeenCalled();
+	});
+
+	it('the progress bar is not clickable when the session does not support seeking', () => {
+		const onControl = vi.fn();
+		const noSeek = { ...caps, seek: false };
+		const { container } = render(
+			<NowPlaying session={seekableSession()} caps={noSeek} onControl={onControl} />
+		);
+		const bar = container.querySelector('[data-part="progress"]') as HTMLElement;
+		expect(bar.getAttribute('data-seekable')).toBe('false');
+		fireEvent.click(bar, { clientX: 50 });
+		expect(onControl).not.toHaveBeenCalled();
+	});
+});
+
+// The crossfade stack adds/removes <img> layers on art changes; transitionend drives the cleanup.
+describe('NowPlaying — crossfade layer lifecycle (transitionend)', () => {
+	it('removes a faded-out layer when its opacity transition ends', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		// New, distinct art → the old (visible) layer becomes outgoing (loaded:false), a new one is pushed.
+		const next = session('Song B', 'http://art.localhost/456');
+		rerender(<NowPlaying session={next} />);
+		await waitFor(() => {
+			expect(container.querySelectorAll('.np-thumb').length).toBe(2);
+		});
+		const outgoing = container.querySelector('.np-thumb[src="http://art.localhost/123"]')!;
+		fireTransitionEnd(outgoing, 'opacity');
+		await waitFor(() => {
+			expect(container.querySelector('.np-thumb[src="http://art.localhost/123"]')).toBeNull();
+		});
+	});
+
+	it('a faded-in layer drops everything beneath it on transitionend', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		const next = session('Song B', 'http://art.localhost/456');
+		rerender(<NowPlaying session={next} />);
+		const incoming = await waitFor(() => {
+			const el = container.querySelector('.np-thumb[src="http://art.localhost/456"]');
+			if (!el) throw new Error('no incoming layer');
+			return el as HTMLImageElement;
+		});
+		fireEvent.load(incoming); // decode → rAF → loaded:true
+		await waitFor(() => expect(incoming.getAttribute('data-loaded')).toBe('true'));
+		// The newly-shown (loaded) layer finishing its fade drops all older layers beneath it.
+		fireTransitionEnd(incoming, 'opacity');
+		await waitFor(() => {
+			const imgs = container.querySelectorAll('.np-thumb');
+			expect(imgs.length).toBe(1);
+			expect(imgs[0].getAttribute('src')).toBe('http://art.localhost/456');
+		});
+	});
+
+	it('ignores a transitionend for a property other than opacity', async () => {
+		const { container, img } = await renderWithLoadedCover();
+		fireTransitionEnd(img, 'transform');
+		// The layer survives an unrelated transition end.
+		expect(container.querySelectorAll('.np-thumb').length).toBe(1);
+	});
+
+	it('flips a layer in even when the image element has no decode() (older webview)', async () => {
+		const proto = window.HTMLImageElement.prototype as { decode?: unknown };
+		const orig = Object.getOwnPropertyDescriptor(proto, 'decode');
+		// Simulate an <img> without decode() so onLayerLoad takes the synchronous flip path.
+		Object.defineProperty(proto, 'decode', { value: undefined, configurable: true });
+		try {
+			const view = render(<NowPlaying session={session('Song A', ART)} />);
+			const img = await waitFor(() => {
+				const el = view.container.querySelector('.np-thumb') as HTMLImageElement | null;
+				if (!el) throw new Error('no cover layer yet');
+				return el;
+			});
+			fireEvent.load(img);
+			await waitFor(() => expect(img.getAttribute('data-loaded')).toBe('true'));
+		} finally {
+			if (orig) Object.defineProperty(proto, 'decode', orig);
+		}
+	});
+
+	it('still flips a layer in when decode() rejects (src superseded)', async () => {
+		const proto = window.HTMLImageElement.prototype as { decode?: unknown };
+		const orig = Object.getOwnPropertyDescriptor(proto, 'decode');
+		Object.defineProperty(proto, 'decode', {
+			value: () => Promise.reject(new Error('superseded')),
+			configurable: true
+		});
+		try {
+			const view = render(<NowPlaying session={session('Song A', ART)} />);
+			const img = await waitFor(() => {
+				const el = view.container.querySelector('.np-thumb') as HTMLImageElement | null;
+				if (!el) throw new Error('no cover layer yet');
+				return el;
+			});
+			fireEvent.load(img);
+			await waitFor(() => expect(img.getAttribute('data-loaded')).toBe('true'));
+		} finally {
+			if (orig) Object.defineProperty(proto, 'decode', orig);
+		}
+	});
+});
+
+// Art-clearing paths: the player vanishing drops every layer immediately; an art-less track keeps the
+// stale cover for a grace window then fades it out, unless new art arrives first.
+describe('NowPlaying — art clearing', () => {
+	it('drops every cover layer immediately when the player goes away', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		expect(container.querySelectorAll('.np-thumb').length).toBe(1);
+		rerender(<NowPlaying session={null} />);
+		await waitFor(() => expect(container.querySelectorAll('.np-thumb').length).toBe(0));
+		// With no title and no layers the whole body collapses (only the root remains).
+		expect(container.querySelector('[data-part="title"]')).toBeNull();
+	});
+
+	it('keeps the stale cover during the grace window, then fades it out for a genuinely art-less track', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		vi.useFakeTimers();
+		// Same track stays playing but its art is now gone (null thumb): hold the previous cover up.
+		rerender(<NowPlaying session={session('Song A', null)} />);
+		expect(container.querySelectorAll('.np-thumb').length).toBe(1);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(1300); // past NO_ART_GRACE_MS (1200)
+		});
+		// The visible layer is now fading out (loaded:false) ahead of its self-removal on transitionend.
+		expect(container.querySelector('.np-thumb')!.getAttribute('data-loaded')).toBe('false');
+	});
+
+	it('cancels the pending no-art teardown when fresh art arrives before the grace elapses', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		vi.useFakeTimers();
+		rerender(<NowPlaying session={session('Song A', null)} />); // schedules the teardown timer
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(300); // still within the grace window
+		});
+		// New art arrives in time → supersedes the pending teardown (the timer is cleared).
+		rerender(<NowPlaying session={session('Song A', 'http://art.localhost/789')} />);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(2000); // well past the original grace deadline
+		});
+		// The old cover was not torn down by the cancelled timer; the new art layer is present.
+		expect(container.querySelector('.np-thumb[src="http://art.localhost/789"]')).not.toBeNull();
+	});
+
+	it('clears a pending no-art teardown timer on unmount (no late state update)', async () => {
+		const { rerender, unmount } = await renderWithLoadedCover();
+		vi.useFakeTimers();
+		rerender(<NowPlaying session={session('Song A', null)} />); // schedules the teardown timer
+		// A fired-after-unmount setState logs a React "setState on unmounted component" act warning via
+		// console.error. test-setup.ts doesn't fail on that, so assert it explicitly: the cleanup must
+		// cancel the timer so it never fires against the dead instance.
+		const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+		unmount(); // cleanup cancels the pending teardown timer
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(2000); // would have fired the teardown if not cleared
+		});
+		expect(errorSpy).not.toHaveBeenCalled();
+		errorSpy.mockRestore();
+	});
+});
+
+// The song-change grey cue has several conditional arms around which layers exist and are loaded.
+describe('NowPlaying — grey cue edge cases', () => {
+	it('does not grey anything when the track changes before any cover has loaded', async () => {
+		// Render art but never fire load → a single not-yet-loaded layer exists.
+		const view = render(<NowPlaying session={session('Song A', ART)} />);
+		const img = await waitFor(() => {
+			const el = view.container.querySelector('.np-thumb') as HTMLImageElement | null;
+			if (!el) throw new Error('no cover layer yet');
+			return el;
+		});
+		expect(img.getAttribute('data-loaded')).toBe('false');
+		// Track change with no loaded layer → grey effect's `.some(loaded)` is false → layers unchanged.
+		view.rerender(<NowPlaying session={session('Song B', ART)} />);
+		const after = view.container.querySelector('.np-thumb') as HTMLImageElement;
+		expect(after.getAttribute('data-leaving')).toBe('false');
+	});
+
+	it('greys only the loaded layer, leaving an in-flight incoming layer in colour', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		// New art (distinct url) pushes an incoming layer that has NOT loaded yet, over the loaded one.
+		rerender(<NowPlaying session={session('Song B', 'http://art.localhost/456')} />);
+		await waitFor(() => expect(container.querySelectorAll('.np-thumb').length).toBe(2));
+		// Now change the track again (same art urls) so the grey effect runs over a mixed loaded set.
+		rerender(<NowPlaying session={session('Song C', 'http://art.localhost/456')} />);
+		const loaded = container.querySelector('.np-thumb[src="http://art.localhost/123"]')!;
+		const notLoaded = container.querySelector('.np-thumb[src="http://art.localhost/456"]')!;
+		expect(loaded.getAttribute('data-loaded')).toBe('false'); // outgoing copy, fading out
+		// The grey effect maps loaded → leaving and leaves the not-yet-loaded incoming layer untouched.
+		expect(notLoaded.getAttribute('data-leaving')).toBe('false');
+	});
+
+	it('on a track change, greys the loaded layer but leaves a stale not-loaded layer as-is', async () => {
+		const { container, rerender } = await renderWithLoadedCover(); // {123, loaded}
+		// Art change (same track) → outgoing {123, loaded:false} + incoming {456, loaded:false}.
+		rerender(<NowPlaying session={session('Song A', 'http://art.localhost/456')} />);
+		const incoming = await waitFor(() => {
+			const el = container.querySelector('.np-thumb[src="http://art.localhost/456"]');
+			if (!el) throw new Error('no incoming layer');
+			return el as HTMLImageElement;
+		});
+		fireEvent.load(incoming); // 456 → loaded:true; 123 stays loaded:false (its transitionend unfired)
+		await waitFor(() => expect(incoming.getAttribute('data-loaded')).toBe('true'));
+		// Now change the TRACK: grey effect runs over [123 not-loaded, 456 loaded] → 456 greys, 123 as-is.
+		rerender(<NowPlaying session={session('Song B', 'http://art.localhost/456')} />);
+		const stale = container.querySelector('.np-thumb[src="http://art.localhost/123"]')!;
+		await waitFor(() => expect(incoming.getAttribute('data-leaving')).toBe('true'));
+		expect(stale.getAttribute('data-loaded')).toBe('false');
+		expect(stale.getAttribute('data-leaving')).toBe('false'); // the not-loaded layer is left untouched
+	});
+
+	it('the grey-recovery timer leaves a not-yet-loaded layer untouched (only loaded layers recover)', async () => {
+		const { container, rerender } = await renderWithLoadedCover();
+		vi.useFakeTimers();
+		// Push an incoming (not-yet-loaded) layer alongside the loaded outgoing one.
+		rerender(<NowPlaying session={session('Song B', 'http://art.localhost/456')} />);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(0); // flush the crossfade effect so both layers commit
+		});
+		expect(container.querySelectorAll('.np-thumb').length).toBe(2);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(1000); // fire the grey-recovery timer (GREY_HOLD_MS = 900)
+		});
+		// The not-yet-loaded incoming layer is untouched by the recovery map (it only flips loaded ones).
+		const notLoaded = container.querySelector('.np-thumb[src="http://art.localhost/456"]');
+		expect(notLoaded).not.toBeNull();
+		expect(notLoaded!.getAttribute('data-leaving')).toBe('false');
+	});
+
+	it('clears a previously-pending grey timer when the track changes a second time', async () => {
+		const { img, rerender } = await renderWithLoadedCover();
+		vi.useFakeTimers();
+		rerender(<NowPlaying session={session('Song B', ART)} />); // schedules the first grey timer
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(100); // still within GREY_HOLD_MS
+		});
+		expect(img.getAttribute('data-leaving')).toBe('true');
+		// Second track change while the first grey timer is pending → it must be cleared and re-armed.
+		rerender(<NowPlaying session={session('Song C', ART)} />);
+		expect(img.getAttribute('data-leaving')).toBe('true');
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(1000); // past the (re-armed) hold → recover to colour
+		});
+		expect(img.getAttribute('data-leaving')).toBe('false');
+	});
+
+	it('clears a pending grey-recovery timer on unmount', async () => {
+		const { rerender, unmount } = await renderWithLoadedCover();
+		vi.useFakeTimers();
+		rerender(<NowPlaying session={session('Song B', ART)} />); // schedules the grey timer
+		// If the recovery timer fired after unmount it would setState on a dead instance, which React
+		// reports via a console.error act warning (test-setup.ts doesn't fail on it). Assert it never
+		// fires by checking console.error stays silent past the (would-be) recovery deadline.
+		const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+		unmount(); // cleanup cancels the pending grey timer
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(1000); // would have fired had it not been cleared
+		});
+		expect(errorSpy).not.toHaveBeenCalled();
+		errorSpy.mockRestore();
+	});
+});
diff --git a/client/src/lib/widgets/meters/Ping.test.tsx b/client/src/lib/widgets/meters/Ping.test.tsx
index 39aa4eb..6ffcf85 100644
--- a/client/src/lib/widgets/meters/Ping.test.tsx
+++ b/client/src/lib/widgets/meters/Ping.test.tsx
@@ -37,4 +37,18 @@ describe('Ping meter', () => {
 		);
 		expect(container.querySelector('.ping-host')?.textContent).toBe('Cloudflare');
 	});
+
+	it('shows a bare "up" when reachable but latency is not yet known', () => {
+		const { container } = render(<Ping sensors={{ up: st(1) }} />);
+		expect(container.querySelector('.ping')?.getAttribute('data-level')).toBe('up');
+		expect(container.querySelector('.ping-value')?.textContent).toBe('up');
+	});
+
+	it('applies the accent colour as a CSS var', () => {
+		const { container } = render(
+			<Ping sensors={{ up: st(1), ms: st(8) }} color="rgb(0, 200, 0)" />
+		);
+		const root = container.querySelector('.ping') as HTMLElement;
+		expect(root.style.getPropertyValue('--ping-accent')).toBe('rgb(0, 200, 0)');
+	});
 });
diff --git a/client/src/lib/widgets/meters/Rss.test.tsx b/client/src/lib/widgets/meters/Rss.test.tsx
new file mode 100644
index 0000000..53896ee
--- /dev/null
+++ b/client/src/lib/widgets/meters/Rss.test.tsx
@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { act, cleanup, render } from '@testing-library/react';
+import Rss from './Rss';
+import { TelemetryHubContext } from '../telemetryContext';
+import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
+
+afterEach(cleanup);
+
+const withHub = (hub: TelemetryHub | null, node: React.ReactNode) =>
+	render(<TelemetryHubContext.Provider value={hub}>{node}</TelemetryHubContext.Provider>);
+
+const feed = (hub: TelemetryHub, value: unknown): void =>
+	act(() => hub.ingest({ sensor: 'rss.list', ts_ms: Date.now(), value: { kind: 'json', value } }));
+
+describe('Rss', () => {
+	it('shows the empty state before any headlines arrive', () => {
+		const { container } = withHub(createTelemetryHub(), <Rss title="News" />);
+		expect(container.querySelector('[data-part="empty"]')?.textContent).toBe('No headlines yet');
+		// The title still renders above the empty placeholder.
+		expect(container.querySelector('.rss-title')?.textContent).toBe('News');
+	});
+
+	it('renders no header when no title is given', () => {
+		const { container } = withHub(createTelemetryHub(), <Rss />);
+		expect(container.querySelector('.rss-head')).toBeNull();
+	});
+
+	it('renders headline titles from the rss.list json sensor', () => {
+		const hub = createTelemetryHub();
+		const { container } = withHub(hub, <Rss />);
+		feed(hub, [
+			{ title: 'First', link: 'https://a' },
+			{ title: 'Second', link: '' }
+		]);
+		const rows = container.querySelectorAll('.rss-item');
+		expect(Array.from(rows).map((r) => r.textContent)).toEqual(['First', 'Second']);
+		// link falls back to the title in the tooltip when absent.
+		expect(rows[0].getAttribute('title')).toBe('https://a');
+		expect(rows[1].getAttribute('title')).toBe('Second');
+	});
+
+	it('caps the list at maxRows', () => {
+		const hub = createTelemetryHub();
+		const { container } = withHub(hub, <Rss maxRows={2} />);
+		feed(hub, [{ title: 'a' }, { title: 'b' }, { title: 'c' }]);
+		expect(container.querySelectorAll('.rss-row')).toHaveLength(2);
+	});
+
+	it('only re-renders on an actual change (same payload keeps the same rows)', () => {
+		const hub = createTelemetryHub();
+		const { container } = withHub(hub, <Rss />);
+		feed(hub, [{ title: 'x' }]);
+		const firstLi = container.querySelector('.rss-row');
+		feed(hub, [{ title: 'x' }]); // identical signature → no state change
+		expect(container.querySelector('.rss-row')).toBe(firstLi);
+	});
+
+	it('passes a per-instance color as the --rss-accent CSS variable', () => {
+		const { container } = withHub(createTelemetryHub(), <Rss color="rgb(9, 8, 7)" />);
+		const root = container.querySelector('.np-rss') as HTMLElement;
+		expect(root.style.getPropertyValue('--rss-accent')).toBe('rgb(9, 8, 7)');
+	});
+
+	it('sets no inline style when no color is given', () => {
+		const { container } = withHub(createTelemetryHub(), <Rss />);
+		expect((container.querySelector('.np-rss') as HTMLElement).getAttribute('style')).toBeNull();
+	});
+
+	it('renders nothing from the hub when there is no provider (hub is null)', () => {
+		const { container } = withHub(null, <Rss />);
+		// The effect early-returns; the empty placeholder is shown.
+		expect(container.querySelector('[data-part="empty"]')).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/meters/StickyNote.test.tsx b/client/src/lib/widgets/meters/StickyNote.test.tsx
index e0307fd..959e1dc 100644
--- a/client/src/lib/widgets/meters/StickyNote.test.tsx
+++ b/client/src/lib/widgets/meters/StickyNote.test.tsx
@@ -1,5 +1,5 @@
-import { describe, it, expect, afterEach, beforeEach } from 'vitest';
-import { render, cleanup, fireEvent } from '@testing-library/react';
+import { describe, it, expect, afterEach, beforeEach, vi } from 'vitest';
+import { render, cleanup, fireEvent, act } from '@testing-library/react';
 import StickyNote from './StickyNote';
 
 afterEach(cleanup);
@@ -33,4 +33,90 @@ describe('StickyNote', () => {
 			'Type here'
 		);
 	});
+
+	it('syncs edits from the other window via the storage event', () => {
+		const { container } = render(<StickyNote widgetId="w4" />);
+		const ta = container.querySelector('textarea') as HTMLTextAreaElement;
+		expect(ta.value).toBe('');
+		// A matching key updates the note; a non-matching key is ignored.
+		act(() => {
+			window.dispatchEvent(
+				new StorageEvent('storage', { key: 'scratch:w4', newValue: 'from overlay' })
+			);
+		});
+		expect(ta.value).toBe('from overlay');
+		act(() => {
+			window.dispatchEvent(new StorageEvent('storage', { key: 'scratch:other', newValue: 'nope' }));
+		});
+		expect(ta.value).toBe('from overlay');
+		// A cleared key (newValue null) resets to empty.
+		act(() => {
+			window.dispatchEvent(new StorageEvent('storage', { key: 'scratch:w4', newValue: null }));
+		});
+		expect(ta.value).toBe('');
+	});
+
+	it('does not touch localStorage when it has no widget id', () => {
+		const spy = vi.spyOn(localStorage, 'setItem');
+		const { container } = render(<StickyNote />);
+		fireEvent.change(container.querySelector('textarea') as HTMLTextAreaElement, {
+			target: { value: 'ephemeral' }
+		});
+		expect(spy).not.toHaveBeenCalled();
+		spy.mockRestore();
+	});
+
+	it('swallows a localStorage write failure (note just will not persist)', () => {
+		const spy = vi.spyOn(localStorage, 'setItem').mockImplementation(() => {
+			throw new Error('quota');
+		});
+		const { container } = render(<StickyNote widgetId="w5" />);
+		const ta = container.querySelector('textarea') as HTMLTextAreaElement;
+		expect(() => fireEvent.change(ta, { target: { value: 'x' } })).not.toThrow();
+		// The in-memory value still updates even though the write threw.
+		expect(ta.value).toBe('x');
+		spy.mockRestore();
+	});
+
+	it('recovers an empty string when reading localStorage throws', () => {
+		const spy = vi.spyOn(localStorage, 'getItem').mockImplementation(() => {
+			throw new Error('blocked');
+		});
+		const { container } = render(<StickyNote widgetId="w6" />);
+		expect(spy).toHaveBeenCalled();
+		expect((container.querySelector('textarea') as HTMLTextAreaElement).value).toBe('');
+		spy.mockRestore();
+	});
+
+	it('stops pointer/wheel from bubbling on the live overlay (not edit mode)', () => {
+		const { container } = render(<StickyNote widgetId="w7" />);
+		const ta = container.querySelector('textarea') as HTMLTextAreaElement;
+		const down = new Event('pointerdown', { bubbles: true });
+		const stopDown = vi.spyOn(down, 'stopPropagation');
+		ta.dispatchEvent(down);
+		expect(stopDown).toHaveBeenCalled();
+		const wheel = new Event('wheel', { bubbles: true });
+		const stopWheel = vi.spyOn(wheel, 'stopPropagation');
+		ta.dispatchEvent(wheel);
+		expect(stopWheel).toHaveBeenCalled();
+	});
+
+	it('lets pointer/wheel through in edit mode (so the widget stays draggable)', () => {
+		const { container } = render(<StickyNote widgetId="w8" editMode />);
+		const ta = container.querySelector('textarea') as HTMLTextAreaElement;
+		const down = new Event('pointerdown', { bubbles: true });
+		const stopDown = vi.spyOn(down, 'stopPropagation');
+		ta.dispatchEvent(down);
+		expect(stopDown).not.toHaveBeenCalled();
+		const wheel = new Event('wheel', { bubbles: true });
+		const stopWheel = vi.spyOn(wheel, 'stopPropagation');
+		ta.dispatchEvent(wheel);
+		expect(stopWheel).not.toHaveBeenCalled();
+	});
+
+	it('passes a per-instance color as the --note-accent CSS variable', () => {
+		const { container } = render(<StickyNote widgetId="w9" color="rgb(4, 5, 6)" />);
+		const root = container.querySelector('.np-stickynote') as HTMLElement;
+		expect(root.style.getPropertyValue('--note-accent')).toBe('rgb(4, 5, 6)');
+	});
 });
diff --git a/client/src/lib/widgets/meters/Text.test.tsx b/client/src/lib/widgets/meters/Text.test.tsx
new file mode 100644
index 0000000..2315e89
--- /dev/null
+++ b/client/src/lib/widgets/meters/Text.test.tsx
@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import Text from './Text';
+
+const part = (c: Element, p: string) => {
+	const el = c.querySelector(`[data-part="${p}"]`);
+	if (!el) throw new Error(`missing data-part="${p}"`);
+	return el as HTMLElement;
+};
+
+describe('Text', () => {
+	it('formats a numeric value via formatScalar (integer default) and uses the --np-fg token', () => {
+		const { container } = render(<Text value={42.7} />);
+		const value = part(container, 'value');
+		expect(value.textContent).toBe('43'); // integer → rounded
+		// happy-dom does not serialise a `var(...)` colour into the inline style attribute, so the
+		// token-driven default leaves `style.color` empty (the look lives in CSS).
+		const root = container.querySelector('.text') as HTMLElement;
+		expect(root.style.color).toBe('');
+		// No label by default.
+		expect(container.querySelector('[data-part="label"]')).toBeNull();
+	});
+
+	it('honours an explicit format (percent appends %)', () => {
+		const { container } = render(<Text value={50} format="percent" />);
+		expect(part(container, 'value').textContent).toBe('50%');
+	});
+
+	it('passes a string value straight through (formula-rendered) without formatting', () => {
+		const { container } = render(<Text value="hello world" format="integer" />);
+		expect(part(container, 'value').textContent).toBe('hello world');
+	});
+
+	it('renders a label and a per-instance color override', () => {
+		const { container } = render(<Text value={7} label="Cores" color="#0f0" />);
+		expect(part(container, 'label').textContent).toBe('Cores');
+		// A concrete colour (unlike a var() token) does serialise into the inline style.
+		const root = container.querySelector('.text') as HTMLElement;
+		expect(root.style.color).toBe('#0f0');
+	});
+
+	it('null value (default) formats to the placeholder', () => {
+		const { container } = render(<Text />);
+		expect(part(container, 'value').textContent).toBe('–');
+	});
+});
diff --git a/client/src/lib/widgets/meters/Timer.test.tsx b/client/src/lib/widgets/meters/Timer.test.tsx
index e8a7ebe..8b0a535 100644
--- a/client/src/lib/widgets/meters/Timer.test.tsx
+++ b/client/src/lib/widgets/meters/Timer.test.tsx
@@ -1,6 +1,8 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, fireEvent } from '@testing-library/react';
-import { TimerView } from './Timer';
+import { afterEach, beforeEach, describe, it, expect, vi } from 'vitest';
+import { render, fireEvent, act, cleanup } from '@testing-library/react';
+import Timer, { TimerView } from './Timer';
+
+afterEach(cleanup);
 
 describe('TimerView', () => {
 	it('renders the time and label', () => {
@@ -33,4 +35,75 @@ describe('TimerView', () => {
 		const { container } = render(<TimerView time="00:00" done />);
 		expect(container.querySelector('.timer.is-done')).toBeTruthy();
 	});
+
+	it('renders no label when none is given', () => {
+		const { container } = render(<TimerView time="00:00" />);
+		expect(container.querySelector('[data-part="label"]')).toBeNull();
+	});
+
+	it('renders no controls block when neither callback is given', () => {
+		const { container } = render(<TimerView time="00:00" />);
+		expect(container.querySelector('[data-part="controls"]')).toBeNull();
+	});
+
+	it('renders only the reset control when onToggle is absent', () => {
+		const onReset = vi.fn();
+		const { container, getByLabelText } = render(<TimerView time="00:00" onReset={onReset} />);
+		expect(getByLabelText('Reset')).toBeTruthy();
+		expect(container.querySelector('[title="Start"]')).toBeNull();
+	});
+
+	it('applies an explicit color inline; without one it leans on the token (no rgb override)', () => {
+		const a = render(<TimerView time="00:00" color="rgb(1, 2, 3)" />);
+		expect((a.container.querySelector('[data-part="root"]') as HTMLElement).style.color).toBe(
+			'rgb(1, 2, 3)'
+		);
+		a.unmount();
+		// Default branch sets color to the var() token fallback; happy-dom's CSSOM can't store a
+		// var() color, so the observable effect is simply no concrete rgb() override.
+		const b = render(<TimerView time="00:00" />);
+		expect((b.container.querySelector('[data-part="root"]') as HTMLElement).style.color).toBe('');
+	});
+});
+
+describe('Timer (default, self-sourcing) wires useTimer to TimerView', () => {
+	beforeEach(() => vi.useFakeTimers());
+	afterEach(() => vi.useRealTimers());
+
+	const val = (c: HTMLElement): string => c.querySelector('[data-part="value"]')?.textContent ?? '';
+
+	it('shows a paused countdown at its full duration (ceiling) and counts down on start', () => {
+		const { container, getByLabelText } = render(<Timer mode="countdown" duration={5} />);
+		expect(val(container)).toBe('00:05');
+		act(() => fireEvent.click(getByLabelText('Start')));
+		// Past 1.2s: 3.8s left → ceil reads 00:04.
+		act(() => vi.advanceTimersByTime(1200));
+		expect(val(container)).toBe('00:04');
+		expect(getByLabelText('Pause')).toBeTruthy();
+	});
+
+	it('a stopwatch floors elapsed seconds', () => {
+		const { container, getByLabelText } = render(<Timer mode="stopwatch" />);
+		expect(val(container)).toBe('00:00');
+		act(() => fireEvent.click(getByLabelText('Start')));
+		act(() => vi.advanceTimersByTime(1900));
+		expect(val(container)).toBe('00:01');
+	});
+
+	it('reset returns the value to the start', () => {
+		const { container, getByLabelText } = render(<Timer mode="stopwatch" />);
+		act(() => fireEvent.click(getByLabelText('Start')));
+		act(() => vi.advanceTimersByTime(3000));
+		expect(val(container)).toBe('00:03');
+		act(() => fireEvent.click(getByLabelText('Reset')));
+		expect(val(container)).toBe('00:00');
+	});
+
+	it('honours the label and a custom format', () => {
+		const { container } = render(
+			<Timer mode="countdown" duration={3600} format="hh:mm:ss" label="Pomodoro" />
+		);
+		expect(container.querySelector('[data-part="label"]')?.textContent).toBe('Pomodoro');
+		expect(val(container)).toBe('01:00:00');
+	});
 });
diff --git a/client/src/lib/widgets/meters/Transcribe.test.tsx b/client/src/lib/widgets/meters/Transcribe.test.tsx
index 521f563..dd1ca47 100644
--- a/client/src/lib/widgets/meters/Transcribe.test.tsx
+++ b/client/src/lib/widgets/meters/Transcribe.test.tsx
@@ -2,6 +2,12 @@ import { describe, it, expect, vi } from 'vitest';
 import { render, fireEvent } from '@testing-library/react';
 import { TranscribeView } from './Transcribe';
 
+// The default-export wrapper just binds useTranscribe → TranscribeView. Mock the hook so we can
+// assert the config it receives and that its state flows into the view (no real mic/LLM).
+const useTranscribe = vi.fn();
+vi.mock('./useTranscribe', () => ({ useTranscribe: (c: unknown) => useTranscribe(c) }));
+import Transcribe from './Transcribe';
+
 describe('TranscribeView', () => {
 	it('shows the placeholder, then the output', () => {
 		const { getByText, rerender } = render(<TranscribeView />);
@@ -39,3 +45,61 @@ describe('TranscribeView', () => {
 		expect(getByText(/no API key/)).toBeTruthy();
 	});
 });
+
+describe('Transcribe (container)', () => {
+	it('passes its config to useTranscribe and renders the hook state via the view', () => {
+		const toggle = vi.fn();
+		useTranscribe.mockReturnValue({
+			source: 'bonjour',
+			output: 'hello',
+			busy: false,
+			error: '',
+			recording: false,
+			toggle
+		});
+		const { getByText, getByLabelText } = render(
+			<Transcribe
+				mode="translate"
+				targetLang="English"
+				sourceLang="fr"
+				model="whisper-1"
+				audioSource="mic-1"
+				speak
+				label="Live"
+			/>
+		);
+		expect(useTranscribe).toHaveBeenCalledWith({
+			mode: 'translate',
+			targetLang: 'English',
+			sourceLang: 'fr',
+			model: 'whisper-1',
+			audioSource: 'mic-1',
+			speak: true
+		});
+		expect(getByText('hello')).toBeTruthy(); // translated output
+		expect(getByText('bonjour')).toBeTruthy(); // faint source (translate mode)
+		expect(getByText('Live')).toBeTruthy();
+		fireEvent.click(getByLabelText('Record'));
+		expect(toggle).toHaveBeenCalledOnce();
+	});
+
+	it('uses the documented defaults when no props are given', () => {
+		useTranscribe.mockReturnValue({
+			source: '',
+			output: '',
+			busy: false,
+			error: '',
+			recording: false,
+			toggle: vi.fn()
+		});
+		render(<Transcribe />);
+		expect(useTranscribe).toHaveBeenCalledWith({
+			mode: 'transcribe',
+			targetLang: 'English',
+			sourceLang: 'auto',
+			model: '',
+			audioSource: '',
+			speak: false
+		});
+	});
+});
diff --git a/client/src/lib/widgets/meters/ha-controls.test.tsx b/client/src/lib/widgets/meters/ha-controls.test.tsx
new file mode 100644
index 0000000..dfc7101
--- /dev/null
+++ b/client/src/lib/widgets/meters/ha-controls.test.tsx
@@ -0,0 +1,505 @@
+import { describe, expect, it } from 'vitest';
+import { fireEvent, render } from '@testing-library/react';
+import HaSwitch from './HaSwitch';
+import HaScene from './HaScene';
+import HaFan from './HaFan';
+import HaCover from './HaCover';
+import HaLock from './HaLock';
+import HaBinarySensor from './HaBinarySensor';
+import HaInput from './HaInput';
+import HaClimate from './HaClimate';
+import HaLight from './HaLight';
+import HaMediaPlayer from './HaMediaPlayer';
+
+describe('HaSwitch', () => {
+	it('shows ON/OFF and toggles', () => {
+		let detail: unknown = null;
+		const { getByText, getByRole } = render(
+			<HaSwitch
+				value={{ state: 'on', attributes: { friendly_name: 'Plug' } }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		expect(() => getByText('ON')).not.toThrow();
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'switch', service: 'toggle' });
+	});
+});
+
+describe('HaScene', () => {
+	it('activates the scene on click', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaScene value={{ attributes: { friendly_name: 'Movie' } }} onControl={(e) => (detail = e)} />
+		);
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'scene', service: 'turn_on' });
+	});
+});
+
+describe('HaFan', () => {
+	it('toggles when off (no speed / oscillate controls)', () => {
+		let detail: unknown = null;
+		const { getByRole, queryByRole } = render(
+			<HaFan
+				value={{ state: 'off', attributes: { friendly_name: 'Fan' } }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		expect(queryByRole('slider')).toBeNull();
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'fan', service: 'toggle' });
+	});
+
+	it('emits set_percentage from the speed slider', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaFan
+				value={{ state: 'on', attributes: { friendly_name: 'Fan', percentage: 50 } }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.change(getByRole('slider'), { target: { value: '80' } });
+		expect(detail).toEqual({ domain: 'fan', service: 'set_percentage', data: { percentage: 80 } });
+	});
+
+	it('emits oscillate, and hides the speed slider when showSpeed=false', () => {
+		let detail: unknown = null;
+		const { getByLabelText, queryByRole } = render(
+			<HaFan
+				value={{
+					state: 'on',
+					attributes: { friendly_name: 'Fan', percentage: 50, oscillating: false }
+				}}
+				showSpeed={false}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		expect(queryByRole('slider')).toBeNull();
+		fireEvent.click(getByLabelText('Fan oscillate'));
+		expect(detail).toEqual({ domain: 'fan', service: 'oscillate', data: { oscillating: true } });
+	});
+});
+
+describe('HaCover', () => {
+	const cover = { state: 'open', attributes: { friendly_name: 'Blind', current_position: 60 } };
+
+	it('emits open/stop/close + set_cover_position', () => {
+		let detail: unknown = null;
+		const { getByLabelText, getByRole } = render(
+			<HaCover value={cover} onControl={(e) => (detail = e)} />
+		);
+		fireEvent.click(getByLabelText('Open Blind'));
+		expect(detail).toEqual({ domain: 'cover', service: 'open_cover' });
+		fireEvent.click(getByLabelText('Stop Blind'));
+		expect(detail).toEqual({ domain: 'cover', service: 'stop_cover' });
+		fireEvent.click(getByLabelText('Close Blind'));
+		expect(detail).toEqual({ domain: 'cover', service: 'close_cover' });
+		fireEvent.change(getByRole('slider'), { target: { value: '30' } });
+		expect(detail).toEqual({
+			domain: 'cover',
+			service: 'set_cover_position',
+			data: { position: 30 }
+		});
+	});
+
+	it('respects showButtons / showPosition toggles', () => {
+		const { queryByLabelText, queryByRole } = render(
+			<HaCover value={cover} showButtons={false} showPosition={false} onControl={() => undefined} />
+		);
+		expect(queryByLabelText('Open Blind')).toBeNull();
+		expect(queryByRole('slider')).toBeNull();
+	});
+});
+
+describe('HaLock', () => {
+	it('locks when unlocked', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaLock
+				value={{ state: 'unlocked', attributes: { friendly_name: 'Door' } }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'lock', service: 'lock' });
+	});
+
+	it('unlocks when locked', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaLock
+				value={{ state: 'locked', attributes: { friendly_name: 'Door' } }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'lock', service: 'unlock' });
+	});
+});
+
+describe('HaBinarySensor', () => {
+	it('maps device_class on/off to semantic words', () => {
+		const door = render(
+			<HaBinarySensor
+				value={{ state: 'on', attributes: { friendly_name: 'Front', device_class: 'door' } }}
+			/>
+		);
+		expect(() => door.getByText('Open')).not.toThrow();
+	});
+
+	it('falls back to ON/OFF without a device_class', () => {
+		const { getByText } = render(
+			<HaBinarySensor value={{ state: 'off', attributes: { friendly_name: 'X' } }} />
+		);
+		expect(() => getByText('OFF')).not.toThrow();
+	});
+});
+
+describe('HaInput', () => {
+	it('input_boolean → toggle', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaInput
+				value={{ entity_id: 'input_boolean.x', state: 'off', attributes: {} }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'input_boolean', service: 'toggle' });
+	});
+
+	it('input_button → press', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaInput
+				value={{ entity_id: 'input_button.x', state: '', attributes: {} }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.click(getByRole('button'));
+		expect(detail).toEqual({ domain: 'input_button', service: 'press' });
+	});
+
+	it('input_select → select_option', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaInput
+				value={{ entity_id: 'input_select.x', state: 'A', attributes: { options: ['A', 'B'] } }}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.change(getByRole('combobox'), { target: { value: 'B' } });
+		expect(detail).toEqual({
+			domain: 'input_select',
+			service: 'select_option',
+			data: { option: 'B' }
+		});
+	});
+
+	it('input_number → set_value, clamped to min/max', () => {
+		let detail: unknown = null;
+		const { getByRole } = render(
+			<HaInput
+				value={{
+					entity_id: 'input_number.x',
+					state: '5',
+					attributes: { min: 0, max: 10, step: 1 }
+				}}
+				onControl={(e) => (detail = e)}
+			/>
+		);
+		fireEvent.change(getByRole('slider'), { target: { value: '8' } });
+		expect(detail).toEqual({ domain: 'input_number', service: 'set_value', data: { value: 8 } });
+	});
+});
+
+describe('HaClimate (A/C controls)', () => {
+	const ac = {
+		state: 'cool',
+		attributes: {
+			friendly_name: 'AC',
+			current_temperature: 26,
+			temperature: 23,
+			hvac_modes: ['off', 'cool', 'heat'],
+			fan_modes: ['auto', 'low', 'high'],
+			fan_mode: 'auto',
+			min_temp: 16,
+			max_temp: 30,
+			target_temp_step: 1
+		}
+	};
+
+	it('cycles HVAC mode on tap', () => {
+		let detail: unknown = null;
+		const { getByLabelText } = render(<HaClimate value={ac} onControl={(e) => (detail = e)} />);
+		fireEvent.click(getByLabelText(/AC mode/i));
+		expect(detail).toEqual({
+			domain: 'climate',
+			service: 'set_hvac_mode',
+			data: { hvac_mode: 'heat' }
+		});
+	});
+
+	it('sets fan mode from the selector', () => {
+		let detail: unknown = null;
+		const { getByLabelText } = render(<HaClimate value={ac} onControl={(e) => (detail = e)} />);
+		fireEvent.change(getByLabelText('AC fan mode'), { target: { value: 'high' } });
+		expect(detail).toEqual({
+			domain: 'climate',
+			service: 'set_fan_mode',
+			data: { fan_mode: 'high' }
+		});
+	});
+
+	it('show* toggles hide the mode button / fan select / temp buttons', () => {
+		const { queryByLabelText } = render(
+			<HaClimate
+				value={ac}
+				showMode={false}
+				showFan={false}
+				showTemp={false}
+				onControl={() => undefined}
+			/>
+		);
+		expect(queryByLabelText(/AC mode/i)).toBeNull();
+		expect(queryByLabelText('AC fan mode')).toBeNull();
+		expect(queryByLabelText('Raise AC setpoint')).toBeNull();
+	});
+});
+
+describe('HaLight showBrightness gate', () => {
+	it('hides the slider for a dimmable light when showBrightness=false', () => {
+		const dimmable = {
+			state: 'on',
+			attributes: {
+				friendly_name: 'Kitchen',
+				supported_color_modes: ['brightness'],
+				brightness: 128
+			}
+		};
+		const { queryByRole } = render(<HaLight value={dimmable} showBrightness={false} />);
+		expect(queryByRole('slider')).toBeNull();
+	});
+});
+
+describe('HaMediaPlayer', () => {
+	const playing = {
+		state: 'playing',
+		attributes: {
+			friendly_name: 'Speaker',
+			media_title: 'Song',
+			media_artist: 'Artist',
+			volume_level: 0.5,
+			is_volume_muted: false
+		}
+	};
+
+	it('shows now-playing text and emits transport + volume', () => {
+		let detail: unknown = null;
+		const { getByText, getByLabelText, getByRole } = render(
+			<HaMediaPlayer value={playing} onControl={(e) => (detail = e)} />
+		);
+		expect(() => getByText(/Song · Artist/)).not.toThrow();
+
+		fireEvent.click(getByLabelText('Previous on Speaker'));
+		expect(detail).toEqual({ domain: 'media_player', service: 'media_previous_track' });
+		fireEvent.click(getByLabelText('Pause Speaker'));
+		expect(detail).toEqual({ domain: 'media_player', service: 'media_play_pause' });
+		fireEvent.click(getByLabelText('Next on Speaker'));
+		expect(detail).toEqual({ domain: 'media_player', service: 'media_next_track' });
+		fireEvent.change(getByRole('slider'), { target: { value: '80' } });
+		expect(detail).toEqual({
+			domain: 'media_player',
+			service: 'volume_set',
+			data: { volume_level: 0.8 }
+		});
+		fireEvent.click(getByLabelText('Mute Speaker'));
+		expect(detail).toEqual({
+			domain: 'media_player',
+			service: 'volume_mute',
+			data: { is_volume_muted: true }
+		});
+	});
+
+	it('hides transport when off, and respects show* toggles', () => {
+		const off = render(
+			<HaMediaPlayer value={{ state: 'off', attributes: { friendly_name: 'Speaker' } }} />
+		);
+		expect(off.queryByLabelText(/Play|Pause/)).toBeNull();
+
+		const gated = render(
+			<HaMediaPlayer value={playing} showTransport={false} showVolume={false} />
+		);
+		expect(gated.queryByLabelText('Next on Speaker')).toBeNull();
+		expect(gated.queryByRole('slider')).toBeNull();
+	});
+
+	it('renders album art when an art URL is provided', () => {
+		const { container } = render(<HaMediaPlayer value={playing} art="http://art.localhost/123" />);
+		const img = container.querySelector('img.art');
+		expect(img?.getAttribute('src')).toBe('http://art.localhost/123');
+	});
+});
+
+// Branch/fallback coverage: null value (default prop), missing friendly_name → the per-widget
+// default label, and the off/alternate state arms. These render-only paths don't need handlers.
+describe('HA control fallbacks (null value, default names, off/alt states)', () => {
+	it('HaSwitch: null value → OFF + "Switch" default, no className "on", click is a no-op without onControl', () => {
+		const { getByRole, getByText } = render(<HaSwitch />);
+		const btn = getByRole('button');
+		expect(getByText('Switch')).toBeTruthy();
+		expect(getByText('OFF')).toBeTruthy();
+		expect(btn.getAttribute('aria-pressed')).toBe('false');
+		expect(btn.className).not.toContain(' on');
+		// onControl is optional — clicking without it must not throw.
+		expect(() => fireEvent.click(btn)).not.toThrow();
+	});
+
+	it('HaScene: null value → "Scene" default; click without onControl is a no-op', () => {
+		const { getByRole, getByText } = render(<HaScene />);
+		expect(getByText('Scene')).toBeTruthy();
+		expect(() => fireEvent.click(getByRole('button'))).not.toThrow();
+	});
+
+	it('HaLock: null value → "Lock" + "—" state, not locked; click without onControl is a no-op', () => {
+		const { getByRole, getByText } = render(<HaLock />);
+		const btn = getByRole('button');
+		expect(getByText('Lock')).toBeTruthy();
+		expect(getByText('—')).toBeTruthy();
+		expect(btn.getAttribute('aria-pressed')).toBe('false');
+		expect(btn.className).not.toContain('locked');
+		expect(() => fireEvent.click(btn)).not.toThrow();
+	});
+
+	it('HaFan: null value → "Fan" + OFF, no slider/oscillate; toggle is a no-op without onControl', () => {
+		const { getByText, queryByRole, queryByLabelText } = render(<HaFan />);
+		expect(getByText('Fan')).toBeTruthy();
+		expect(getByText('OFF')).toBeTruthy();
+		expect(queryByRole('slider')).toBeNull();
+		expect(queryByLabelText('Fan oscillate')).toBeNull();
+		expect(() => fireEvent.click(getByText('Fan'))).not.toThrow();
+	});
+
+	it('HaFan: oscillating=true marks the oscillate button on', () => {
+		const { getByLabelText } = render(
+			<HaFan value={{ state: 'on', attributes: { friendly_name: 'Fan', oscillating: true } }} />
+		);
+		const osc = getByLabelText('Fan oscillate');
+		expect(osc.className).toContain('on');
+		expect(osc.getAttribute('aria-pressed')).toBe('true');
+	});
+
+	it('HaFan: on but no percentage → ON (no speed slider)', () => {
+		const { getByText, queryByRole } = render(
+			<HaFan value={{ state: 'on', attributes: { friendly_name: 'Fan' } }} />
+		);
+		expect(getByText('ON')).toBeTruthy();
+		expect(queryByRole('slider')).toBeNull();
+	});
+
+	it('HaCover: null value → "Cover" + "—" state; controls are no-ops without onControl', () => {
+		const { getByText, getByLabelText } = render(<HaCover />);
+		expect(getByText('Cover')).toBeTruthy();
+		expect(getByText('—')).toBeTruthy();
+		// Buttons render (showButtons defaults true) but have no position slider (no current_position).
+		expect(() => fireEvent.click(getByLabelText('Open Cover'))).not.toThrow();
+	});
+
+	it('HaCover: no-op setPos when onControl is absent', () => {
+		const { getByRole } = render(
+			<HaCover
+				value={{ state: 'open', attributes: { friendly_name: 'Blind', current_position: 60 } }}
+			/>
+		);
+		expect(() => fireEvent.change(getByRole('slider'), { target: { value: '30' } })).not.toThrow();
+	});
+
+	it('HaLight: null value → "Light" + OFF; toggle is a no-op without onControl', () => {
+		const { getByText } = render(<HaLight />);
+		expect(getByText('Light')).toBeTruthy();
+		expect(getByText('OFF')).toBeTruthy();
+		expect(() => fireEvent.click(getByText('Light'))).not.toThrow();
+	});
+
+	it('HaBinarySensor: null value → "—" name and "—" value', () => {
+		const { getAllByText } = render(<HaBinarySensor />);
+		expect(getAllByText('—').length).toBeGreaterThanOrEqual(2);
+	});
+
+	it('HaBinarySensor: device_class off → the off-word (words[1])', () => {
+		const { getByText } = render(
+			<HaBinarySensor
+				value={{ state: 'off', attributes: { friendly_name: 'Front', device_class: 'door' } }}
+			/>
+		);
+		expect(getByText('Closed')).toBeTruthy();
+	});
+
+	it('HaBinarySensor: an unknown state (neither on nor off) renders verbatim', () => {
+		const { getByText } = render(
+			<HaBinarySensor value={{ state: 'unavailable', attributes: { friendly_name: 'Front' } }} />
+		);
+		expect(getByText('unavailable')).toBeTruthy();
+	});
+
+	it('HaMediaPlayer: null value → "Media"; the "—" state is treated as active so transport shows', () => {
+		const { getByText, queryByLabelText } = render(<HaMediaPlayer />);
+		expect(getByText('Media')).toBeTruthy();
+		// state defaults to '—', which is NOT in the off/unavailable/standby exclusion list → active,
+		// so with no media_title the now-playing line shows the raw state and transport renders.
+		expect(getByText('—')).toBeTruthy();
+		expect(queryByLabelText(/Play|Pause/)).toBeTruthy();
+	});
+
+	it('HaMediaPlayer: an inactive state with no title shows "idle" and hides transport', () => {
+		const { getByText, queryByLabelText } = render(
+			<HaMediaPlayer value={{ state: 'off', attributes: { friendly_name: 'Speaker' } }} />
+		);
+		expect(getByText('idle')).toBeTruthy();
+		expect(queryByLabelText(/Play|Pause/)).toBeNull();
+	});
+
+	it('HaMediaPlayer: paused shows the play (▶) glyph and falls back through artist sources', () => {
+		const { getByLabelText, getByText } = render(
+			<HaMediaPlayer
+				value={{
+					state: 'paused',
+					attributes: { friendly_name: 'Speaker', media_title: 'Show', media_series_title: 'S1' }
+				}}
+			/>
+		);
+		// state==='paused' (active, not playing) → Play label + ▶ icon.
+		const playBtn = getByLabelText('Play Speaker');
+		expect(playBtn.textContent).toBe('▶');
+		expect(getByText(/Show · S1/)).toBeTruthy();
+	});
+
+	it('HaMediaPlayer: artist falls back to app_name when title/series/artist absent', () => {
+		const { getByText } = render(
+			<HaMediaPlayer
+				value={{ state: 'playing', attributes: { friendly_name: 'Speaker', app_name: 'Spotify' } }}
+			/>
+		);
+		// No media_title → shows the active state ('playing') then " · Spotify".
+		expect(getByText(/playing · Spotify/)).toBeTruthy();
+	});
+
+	it('HaMediaPlayer: muted shows 🔇 + "on" class; transport/volume are no-ops without onControl', () => {
+		const { getByLabelText, getByRole } = render(
+			<HaMediaPlayer
+				value={{
+					state: 'playing',
+					attributes: { friendly_name: 'Speaker', volume_level: 0.4, is_volume_muted: true }
+				}}
+			/>
+		);
+		const mute = getByLabelText('Mute Speaker');
+		expect(mute.textContent).toBe('🔇');
+		expect(mute.className).toContain('on');
+		expect(mute.getAttribute('aria-pressed')).toBe('true');
+		// No onControl → clicks/changes must not throw.
+		expect(() => fireEvent.click(getByLabelText('Next on Speaker'))).not.toThrow();
+		expect(() => fireEvent.change(getByRole('slider'), { target: { value: '70' } })).not.toThrow();
+	});
+});
diff --git a/client/src/lib/widgets/meters/ha.test.tsx b/client/src/lib/widgets/meters/ha.test.tsx
index 45cfbbc..813e878 100644
--- a/client/src/lib/widgets/meters/ha.test.tsx
+++ b/client/src/lib/widgets/meters/ha.test.tsx
@@ -112,4 +112,134 @@ describe('HaClimate', () => {
 		const { queryByLabelText } = render(<HaClimate value={range} onControl={() => undefined} />);
 		expect(queryByLabelText('Raise X setpoint')).toBeNull();
 	});
+
+	it('lowers the setpoint with the − button', () => {
+		const climate = {
+			state: 'cool',
+			attributes: {
+				friendly_name: 'Bedroom',
+				temperature: 21,
+				target_temp_step: 0.5,
+				min_temp: 7,
+				max_temp: 35
+			}
+		};
+		let detail: unknown = null;
+		const { getByLabelText } = render(
+			<HaClimate value={climate} onControl={(e) => (detail = e)} />
+		);
+		fireEvent.click(getByLabelText('Lower Bedroom setpoint'));
+		expect(detail).toEqual({
+			domain: 'climate',
+			service: 'set_temperature',
+			data: { temperature: 20.5 }
+		});
+	});
+
+	it('cycles the HVAC mode with the mode button', () => {
+		const climate = {
+			state: 'off',
+			attributes: { friendly_name: 'Bedroom', hvac_modes: ['off', 'cool', 'heat'] }
+		};
+		let detail: unknown = null;
+		const { getByLabelText } = render(
+			<HaClimate value={climate} onControl={(e) => (detail = e)} />
+		);
+		const btn = getByLabelText('Bedroom mode (tap to change)');
+		expect(btn.tagName).toBe('BUTTON');
+		expect(btn.textContent).toBe('off');
+		fireEvent.click(btn);
+		expect(detail).toEqual({
+			domain: 'climate',
+			service: 'set_hvac_mode',
+			data: { hvac_mode: 'cool' }
+		});
+	});
+
+	it('shows the mode read-only when there is no controllable mode list', () => {
+		const climate = {
+			state: 'heat',
+			attributes: { friendly_name: 'Bedroom', hvac_modes: ['heat'] }
+		};
+		const { getByText, queryByLabelText } = render(
+			<HaClimate value={climate} onControl={() => undefined} />
+		);
+		// Single-entry list → not a button, just a span.
+		expect(queryByLabelText('Bedroom mode (tap to change)')).toBeNull();
+		expect(getByText('heat').tagName).toBe('SPAN');
+	});
+
+	it('selects an A/C fan mode from the dropdown', () => {
+		const climate = {
+			state: 'cool',
+			attributes: {
+				friendly_name: 'Bedroom',
+				fan_modes: ['auto', 'low', 'high'],
+				fan_mode: 'auto'
+			}
+		};
+		let detail: unknown = null;
+		const { getByLabelText } = render(
+			<HaClimate value={climate} onControl={(e) => (detail = e)} />
+		);
+		const select = getByLabelText('Bedroom fan mode') as HTMLSelectElement;
+		expect(select.value).toBe('auto');
+		fireEvent.change(select, { target: { value: 'high' } });
+		expect(detail).toEqual({
+			domain: 'climate',
+			service: 'set_fan_mode',
+			data: { fan_mode: 'high' }
+		});
+	});
+
+	it('offers a "fan…" placeholder when no fan mode is reported', () => {
+		const climate = {
+			state: 'cool',
+			attributes: { friendly_name: 'Bedroom', fan_modes: ['auto', 'low'] }
+		};
+		const { getByLabelText, getByText } = render(
+			<HaClimate value={climate} onControl={() => undefined} />
+		);
+		const select = getByLabelText('Bedroom fan mode') as HTMLSelectElement;
+		expect(select.value).toBe('');
+		expect(getByText('fan…').tagName).toBe('OPTION');
+	});
+
+	it('keeps an unlisted reported fan mode selectable', () => {
+		const climate = {
+			state: 'cool',
+			attributes: { friendly_name: 'Bedroom', fan_modes: ['low', 'high'], fan_mode: 'turbo' }
+		};
+		const { getByLabelText, getByText } = render(
+			<HaClimate value={climate} onControl={() => undefined} />
+		);
+		const select = getByLabelText('Bedroom fan mode') as HTMLSelectElement;
+		expect(select.value).toBe('turbo');
+		// The reported-but-unlisted mode is added as its own option so the value stays matched.
+		expect(getByText('turbo').tagName).toBe('OPTION');
+	});
+
+	it('falls back to placeholders and defaults when value is null', () => {
+		const { getByText, getAllByText } = render(<HaClimate value={null} />);
+		// label ?? friendly_name ?? 'Climate'; state ?? '—'; current/target → '—'.
+		expect(() => getByText('Climate')).not.toThrow();
+		expect(getAllByText('—').length).toBeGreaterThan(0);
+		expect(() => getByText(/—\s*→\s*—/)).not.toThrow();
+	});
+
+	it('renders read-only (no controls) without an onControl handler', () => {
+		const climate = {
+			state: 'cool',
+			attributes: {
+				friendly_name: 'Bedroom',
+				temperature: 21,
+				hvac_modes: ['off', 'cool', 'heat'],
+				fan_modes: ['auto', 'low']
+			}
+		};
+		const { queryByLabelText } = render(<HaClimate value={climate} />);
+		expect(queryByLabelText('Bedroom mode (tap to change)')).toBeNull();
+		expect(queryByLabelText('Raise Bedroom setpoint')).toBeNull();
+		expect(queryByLabelText('Bedroom fan mode')).toBeNull();
+	});
 });
diff --git a/client/src/lib/widgets/meters/useTimer.test.ts b/client/src/lib/widgets/meters/useTimer.test.ts
new file mode 100644
index 0000000..720b5ae
--- /dev/null
+++ b/client/src/lib/widgets/meters/useTimer.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useTimer, type TimerConfig } from './useTimer';
+
+beforeEach(() => vi.useFakeTimers({ now: 1_000_000 }));
+afterEach(() => vi.useRealTimers());
+
+const advance = (ms: number): void => {
+	act(() => {
+		vi.advanceTimersByTime(ms);
+	});
+};
+
+describe('useTimer countdown', () => {
+	it('starts idle at the full duration and is not done', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		expect(result.current.seconds).toBe(10);
+		expect(result.current.running).toBe(false);
+		expect(result.current.done).toBe(false);
+	});
+
+	it('counts down while running', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.start());
+		expect(result.current.running).toBe(true);
+		advance(3000);
+		expect(result.current.seconds).toBeCloseTo(7, 5);
+	});
+
+	it('start() is a no-op when already running (does not reset the anchor)', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.start());
+		advance(2000);
+		act(() => result.current.start()); // ignored — anchor stays put
+		advance(1000);
+		expect(result.current.seconds).toBeCloseTo(7, 5);
+	});
+
+	it('pause() freezes elapsed time and resumes from there', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.start());
+		advance(2000);
+		act(() => result.current.pause());
+		expect(result.current.running).toBe(false);
+		expect(result.current.seconds).toBeCloseTo(8, 5);
+		// Time passing while paused must NOT advance the count.
+		advance(5000);
+		expect(result.current.seconds).toBeCloseTo(8, 5);
+		// Resume continues from the frozen accumulator.
+		act(() => result.current.start());
+		advance(1000);
+		expect(result.current.seconds).toBeCloseTo(7, 5);
+	});
+
+	it('pause() is a no-op when already paused', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.pause()); // already stopped — no change
+		expect(result.current.running).toBe(false);
+		expect(result.current.seconds).toBe(10);
+	});
+
+	it('toggle() flips between running and paused', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.toggle());
+		expect(result.current.running).toBe(true);
+		act(() => result.current.toggle());
+		expect(result.current.running).toBe(false);
+	});
+
+	it('reset() while paused clears the accumulator (and keeps the timer stopped)', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.start());
+		advance(4000);
+		act(() => result.current.pause());
+		expect(result.current.seconds).toBeCloseTo(6, 5);
+		act(() => result.current.reset());
+		expect(result.current.seconds).toBe(10);
+		expect(result.current.running).toBe(false);
+	});
+
+	it('reset() while running re-anchors to now and starts the full duration again', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 10 }));
+		act(() => result.current.start());
+		advance(4000);
+		act(() => result.current.reset());
+		expect(result.current.running).toBe(true);
+		expect(result.current.seconds).toBeCloseTo(10, 5);
+		advance(1000);
+		expect(result.current.seconds).toBeCloseTo(9, 5);
+	});
+
+	it('auto-stops frozen exactly at zero when the countdown completes (no loop)', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 2, loop: false }));
+		act(() => result.current.start());
+		advance(2500); // past the end
+		expect(result.current.seconds).toBe(0);
+		expect(result.current.done).toBe(true);
+		expect(result.current.running).toBe(false);
+		// Stays frozen at 0 even as more time elapses.
+		advance(2000);
+		expect(result.current.seconds).toBe(0);
+	});
+
+	it('loops back to the full duration when loop is set', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 2, loop: true }));
+		act(() => result.current.start());
+		advance(2100); // crosses zero → restarts
+		expect(result.current.running).toBe(true);
+		// Re-anchored: close to the full duration again, still counting.
+		expect(result.current.seconds).toBeGreaterThan(1.5);
+		expect(result.current.seconds).toBeLessThanOrEqual(2);
+	});
+
+	it('a zero-duration countdown is never "done" (guards the divide-by-nothing edge)', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'countdown', duration: 0 }));
+		act(() => result.current.start());
+		advance(1000);
+		expect(result.current.done).toBe(false);
+	});
+});
+
+describe('useTimer stopwatch', () => {
+	it('counts up from zero while running', () => {
+		const { result } = renderHook(() => useTimer({ mode: 'stopwatch', duration: 0 }));
+		expect(result.current.seconds).toBe(0);
+		act(() => result.current.start());
+		advance(3000);
+		expect(result.current.seconds).toBeCloseTo(3, 5);
+		expect(result.current.done).toBe(false);
+	});
+
+	it('reset() zeroes the elapsed count', () => {
+		const cfg: TimerConfig = { mode: 'stopwatch', duration: 0 };
+		const { result } = renderHook(() => useTimer(cfg));
+		act(() => result.current.start());
+		advance(5000);
+		act(() => result.current.reset());
+		expect(result.current.seconds).toBeCloseTo(0, 5);
+	});
+});
diff --git a/client/src/lib/widgets/meters/useTranscribe.test.ts b/client/src/lib/widgets/meters/useTranscribe.test.ts
new file mode 100644
index 0000000..680f299
--- /dev/null
+++ b/client/src/lib/widgets/meters/useTranscribe.test.ts
@@ -0,0 +1,301 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import type { ChatMessage } from '../../core/llm';
+import type { Recorder } from '../../stt';
+
+// Mock every outer-ring dependency the hook touches: the mic recorder (lib/stt), the two LLM Tauri
+// command adapters (transcribe + complete), and the TTS adapter. The hook's own branch logic
+// (push-to-talk toggle, transcribe→translate→speak flow, the re-entrancy guard, error handling) is
+// what we assert. `buildTranslateMessages` is a pure core fn, left REAL so we verify the host calls
+// translate with the right shape.
+const { startRecording, llmTranscribe, llmComplete, speakSmart, makeRecorder } = vi.hoisted(() => {
+	const makeRecorder = (bytes = new Uint8Array([1, 2, 3]), mime = 'audio/webm') => ({
+		stop: vi.fn(() => Promise.resolve({ bytes, mime })),
+		cancel: vi.fn()
+	});
+	return {
+		makeRecorder,
+		startRecording: vi.fn<(deviceId?: string) => Promise<Recorder>>(),
+		llmTranscribe: vi.fn<
+			(
+				audio: Uint8Array,
+				mime: string,
+				opts?: { model?: string; language?: string }
+			) => Promise<string>
+		>(() => Promise.resolve('hello world')),
+		llmComplete: vi.fn<
+			(
+				messages: ChatMessage[],
+				opts?: { temperature?: number; maxTokens?: number }
+			) => Promise<string>
+		>(() => Promise.resolve('hola mundo')),
+		speakSmart: vi.fn<(text: string) => Promise<void>>(() => Promise.resolve())
+	};
+});
+vi.mock('../../stt', () => ({ startRecording }));
+vi.mock('../plugins/llm-commands', () => ({ llmTranscribe, llmComplete }));
+vi.mock('../plugins/llm-tts', () => ({ speakSmart }));
+
+import { useTranscribe, type TranscribeConfig } from './useTranscribe';
+
+const cfg = (over: Partial<TranscribeConfig> = {}): TranscribeConfig => ({
+	mode: 'transcribe',
+	targetLang: 'Spanish',
+	...over
+});
+
+beforeEach(() => {
+	startRecording.mockResolvedValue(makeRecorder());
+	llmTranscribe.mockResolvedValue('hello world');
+	llmComplete.mockResolvedValue('hola mundo');
+	speakSmart.mockResolvedValue(undefined);
+});
+afterEach(() => vi.clearAllMocks());
+
+describe('useTranscribe — push-to-talk recording', () => {
+	it('starts the mic on first toggle and flips to recording', async () => {
+		const { result } = renderHook(() => useTranscribe(cfg()));
+		expect(result.current.recording).toBe(false);
+
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(startRecording).toHaveBeenCalledOnce();
+		expect(result.current.recording).toBe(true);
+		expect(result.current.error).toBe('');
+	});
+
+	it('passes a blank audioSource through as undefined (system default mic)', async () => {
+		const { result } = renderHook(() => useTranscribe(cfg({ audioSource: '' })));
+		await act(async () => {
+			result.current.toggle();
+		});
+		expect(startRecording).toHaveBeenCalledWith(undefined);
+	});
+
+	it('passes a chosen audioSource through to the recorder', async () => {
+		const { result } = renderHook(() => useTranscribe(cfg({ audioSource: 'mic-42' })));
+		await act(async () => {
+			result.current.toggle();
+		});
+		expect(startRecording).toHaveBeenCalledWith('mic-42');
+	});
+
+	it('surfaces a getUserMedia rejection as an error and stays not-recording', async () => {
+		startRecording.mockRejectedValueOnce(new Error('permission denied'));
+		const { result } = renderHook(() => useTranscribe(cfg()));
+
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(result.current.recording).toBe(false);
+		expect(result.current.error).toContain('permission denied');
+	});
+
+	it('ignores a rapid second toggle while a start is still pending (re-entrancy guard)', async () => {
+		let resolveStart!: (r: ReturnType<typeof makeRecorder>) => void;
+		startRecording.mockImplementationOnce(
+			() => new Promise((res) => (resolveStart = res as typeof resolveStart))
+		);
+		const { result } = renderHook(() => useTranscribe(cfg()));
+
+		// Two presses before the first startRecording resolves: the second must be dropped.
+		act(() => {
+			result.current.toggle();
+			result.current.toggle();
+		});
+		await act(async () => {
+			resolveStart(makeRecorder());
+		});
+
+		expect(startRecording).toHaveBeenCalledOnce();
+		expect(result.current.recording).toBe(true);
+	});
+});
+
+describe('useTranscribe — stop, transcribe, translate, speak', () => {
+	it('transcribe mode: stops, transcribes, and shows the trimmed transcript (no translate/speak)', async () => {
+		llmTranscribe.mockResolvedValueOnce('  hello world  ');
+		const rec = makeRecorder(new Uint8Array([9, 9]), 'audio/ogg');
+		startRecording.mockResolvedValueOnce(rec);
+		const { result } = renderHook(() => useTranscribe(cfg({ mode: 'transcribe' })));
+
+		await act(async () => {
+			result.current.toggle(); // start
+		});
+		await act(async () => {
+			result.current.toggle(); // stop → transcribe
+		});
+
+		expect(rec.stop).toHaveBeenCalledOnce();
+		expect(llmTranscribe).toHaveBeenCalledWith(new Uint8Array([9, 9]), 'audio/ogg', {
+			model: undefined,
+			language: undefined
+		});
+		expect(result.current.source).toBe('hello world');
+		expect(result.current.output).toBe('hello world');
+		expect(result.current.recording).toBe(false);
+		expect(result.current.busy).toBe(false);
+		expect(llmComplete).not.toHaveBeenCalled();
+		expect(speakSmart).not.toHaveBeenCalled();
+	});
+
+	it('forwards the model + sourceLang overrides to the transcription call', async () => {
+		const { result } = renderHook(() =>
+			useTranscribe(cfg({ model: 'gpt-4o-transcribe', sourceLang: 'de' }))
+		);
+		await act(async () => {
+			result.current.toggle();
+		});
+		await act(async () => {
+			result.current.toggle();
+		});
+		expect(llmTranscribe).toHaveBeenCalledWith(expect.any(Uint8Array), expect.any(String), {
+			model: 'gpt-4o-transcribe',
+			language: 'de'
+		});
+	});
+
+	it('translate mode: transcribes then translates into the target language', async () => {
+		llmTranscribe.mockResolvedValueOnce('hello world');
+		llmComplete.mockResolvedValueOnce('  hola mundo  ');
+		const { result } = renderHook(() =>
+			useTranscribe(cfg({ mode: 'translate', targetLang: 'Spanish' }))
+		);
+
+		await act(async () => {
+			result.current.toggle();
+		});
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(result.current.source).toBe('hello world'); // raw transcript kept
+		expect(result.current.output).toBe('hola mundo'); // translated + trimmed
+		const [messages, opts] = llmComplete.mock.calls[0]!;
+		expect(opts).toEqual({ temperature: 0 });
+		// buildTranslateMessages (real) → a system translate instruction naming the target + the user text.
+		expect(messages[0].role).toBe('system');
+		expect(messages[0].content).toContain('Spanish');
+		expect(messages[1]).toEqual({ role: 'user', content: 'hello world' });
+	});
+
+	it('translate mode with an empty transcript skips the translate call', async () => {
+		llmTranscribe.mockResolvedValueOnce('   ');
+		const { result } = renderHook(() => useTranscribe(cfg({ mode: 'translate' })));
+
+		await act(async () => {
+			result.current.toggle();
+		});
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(llmComplete).not.toHaveBeenCalled();
+		expect(result.current.source).toBe('');
+		expect(result.current.output).toBe('');
+	});
+
+	it('speaks the result when speak is enabled', async () => {
+		llmTranscribe.mockResolvedValueOnce('hello world');
+		const { result } = renderHook(() => useTranscribe(cfg({ speak: true })));
+
+		await act(async () => {
+			result.current.toggle();
+		});
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(speakSmart).toHaveBeenCalledWith('hello world');
+	});
+
+	it('does not speak when the result is empty even with speak enabled', async () => {
+		llmTranscribe.mockResolvedValueOnce('');
+		const { result } = renderHook(() => useTranscribe(cfg({ speak: true })));
+
+		await act(async () => {
+			result.current.toggle();
+		});
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(speakSmart).not.toHaveBeenCalled();
+	});
+
+	it('a second stop in the same batch is a no-op once the recorder ref is consumed', async () => {
+		const rec = makeRecorder();
+		startRecording.mockResolvedValueOnce(rec);
+		const { result } = renderHook(() => useTranscribe(cfg()));
+
+		await act(async () => {
+			result.current.toggle(); // start
+		});
+		// Two stop presses in one batch: the memoised `run` still sees recording===true on the second
+		// call, but the recorder ref was already nulled by the first → the `if (!rec) return` guard.
+		await act(async () => {
+			result.current.toggle();
+			result.current.toggle();
+		});
+
+		expect(rec.stop).toHaveBeenCalledOnce(); // only the first stop actually transcribed
+		expect(llmTranscribe).toHaveBeenCalledOnce();
+		expect(result.current.recording).toBe(false);
+	});
+
+	it('surfaces a transcription rejection as an error and clears busy', async () => {
+		llmTranscribe.mockRejectedValueOnce(new Error('whisper 401'));
+		const { result } = renderHook(() => useTranscribe(cfg()));
+
+		await act(async () => {
+			result.current.toggle();
+		});
+		await act(async () => {
+			result.current.toggle();
+		});
+
+		expect(result.current.error).toContain('whisper 401');
+		expect(result.current.busy).toBe(false);
+		expect(result.current.recording).toBe(false);
+	});
+});
+
+describe('useTranscribe — lifecycle', () => {
+	it('cancels the recorder on unmount while recording (releases the mic)', async () => {
+		const rec = makeRecorder();
+		startRecording.mockResolvedValueOnce(rec);
+		const { result, unmount } = renderHook(() => useTranscribe(cfg()));
+
+		await act(async () => {
+			result.current.toggle();
+		});
+		unmount();
+
+		expect(rec.cancel).toHaveBeenCalledOnce();
+		expect(rec.stop).not.toHaveBeenCalled();
+	});
+
+	it('uses the LATEST config at stop time (cfgRef freshness across a re-render)', async () => {
+		llmTranscribe.mockResolvedValueOnce('hello world');
+		llmComplete.mockResolvedValueOnce('bonjour le monde');
+		const { result, rerender } = renderHook((c: TranscribeConfig) => useTranscribe(c), {
+			initialProps: cfg({ mode: 'transcribe', targetLang: 'Spanish' })
+		});
+
+		await act(async () => {
+			result.current.toggle(); // start under the transcribe config
+		});
+		// Config changes to translate→French between start and stop.
+		rerender(cfg({ mode: 'translate', targetLang: 'French' }));
+		await act(async () => {
+			result.current.toggle(); // stop → should honor the NEW config
+		});
+
+		expect(llmComplete).toHaveBeenCalledOnce();
+		expect(llmComplete.mock.calls[0]![0][0].content).toContain('French');
+		expect(result.current.output).toBe('bonjour le monde');
+	});
+});
diff --git a/client/src/lib/widgets/plugin.test.tsx b/client/src/lib/widgets/plugin.test.tsx
index c7794a7..6825ef3 100644
--- a/client/src/lib/widgets/plugin.test.tsx
+++ b/client/src/lib/widgets/plugin.test.tsx
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
 	actionHandlerFor,
 	listPlugins,
+	pluginSensorNames,
 	pluginSensorNamesFrom,
 	registerPlugin,
 	statusDotFrom,
@@ -164,4 +165,32 @@ describe('pluginSensorNamesFrom', () => {
 		expect(names.has('cpu.total')).toBe(false);
 		expect(names.has('mem.used')).toBe(false);
 	});
+
+	it('tolerates a source with no catalog() (no ids contributed)', () => {
+		const names = pluginSensorNamesFrom([
+			{
+				id: 'catless',
+				name: 'Catless',
+				sources: [{ id: 'catless', start: async () => () => undefined }]
+			}
+		]);
+		expect(names.size).toBe(0);
+	});
+});
+
+describe('pluginSensorNames (live registry)', () => {
+	it('reads the live plugin registry', () => {
+		registerPlugin({
+			id: 'test.livesensor',
+			name: 'Live Sensor Plugin',
+			sources: [
+				{
+					id: 'test.livesensor',
+					start: async () => () => undefined,
+					catalog: () => ['live.sensor.one']
+				}
+			]
+		});
+		expect(pluginSensorNames().get('live.sensor.one')).toBe('Live Sensor Plugin');
+	});
 });
diff --git a/client/src/lib/widgets/plugins/AgendaSettings.test.tsx b/client/src/lib/widgets/plugins/AgendaSettings.test.tsx
new file mode 100644
index 0000000..12eaaed
--- /dev/null
+++ b/client/src/lib/widgets/plugins/AgendaSettings.test.tsx
@@ -0,0 +1,157 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+
+// Mock the Agenda Tauri command adapter so the panel runs without a backend. Each fn is a spy so we can
+// assert call args + ordering (Save must save → disconnect → connect). The feed is a public ICS URL —
+// nothing secret.
+vi.mock('./agenda-commands', () => ({
+	agendaConfigStatus: vi.fn(() =>
+		Promise.resolve({
+			configured: true,
+			url: 'https://calendar.example.com/basic.ics',
+			title: 'Work',
+			pollSeconds: 1800
+		})
+	),
+	saveAgendaConfig: vi.fn(() => Promise.resolve()),
+	agendaConnect: vi.fn(() => Promise.resolve()),
+	agendaDisconnect: vi.fn(() => Promise.resolve())
+}));
+
+import AgendaSettings from './AgendaSettings';
+import {
+	agendaConfigStatus,
+	agendaConnect,
+	agendaDisconnect,
+	saveAgendaConfig
+} from './agenda-commands';
+import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
+import { TelemetryHubContext } from '../telemetryContext';
+
+let hub: TelemetryHub;
+
+function renderPanel() {
+	hub = createTelemetryHub();
+	return render(
+		<TelemetryHubContext.Provider value={hub}>
+			<AgendaSettings />
+		</TelemetryHubContext.Provider>
+	);
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	vi.mocked(agendaConfigStatus).mockResolvedValue({
+		configured: true,
+		url: 'https://calendar.example.com/basic.ics',
+		title: 'Work',
+		pollSeconds: 1800
+	});
+});
+
+describe('AgendaSettings', () => {
+	it('prefills the form from agenda_config_status and starts the live feed', async () => {
+		const { container, getByText } = renderPanel();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://calendar.example.com/basic.ics'));
+		const title = container.querySelector('input[placeholder="Agenda"]') as HTMLInputElement;
+		expect(title.value).toBe('Work');
+		// pollSeconds is shown as minutes (1800s → 30min).
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		expect(poll.value).toBe('30');
+		expect(getByText('configured')).toBeTruthy();
+		// The studio panel kicks the poll task so the badge has a live status to read.
+		expect(agendaConnect).toHaveBeenCalled();
+	});
+
+	it('shows "not configured" with an empty URL when unconfigured', async () => {
+		vi.mocked(agendaConfigStatus).mockResolvedValue({
+			configured: false,
+			url: '',
+			title: '',
+			pollSeconds: 1800
+		});
+		const { findByText, container } = renderPanel();
+		expect(await findByText('not configured')).toBeTruthy();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		expect(url.value).toBe('');
+	});
+
+	it('updates the URL input as the user types', async () => {
+		const { container } = renderPanel();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://calendar.example.com/basic.ics'));
+		fireEvent.change(url, { target: { value: 'https://other.example/cal.ics' } });
+		expect(url.value).toBe('https://other.example/cal.ics');
+	});
+
+	it('flags a non-URL value and disables Save', async () => {
+		const { container, getByRole } = renderPanel();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://calendar.example.com/basic.ics'));
+		fireEvent.change(url, { target: { value: 'not-a-url' } });
+		expect(url.getAttribute('aria-invalid')).toBe('true');
+		const save = getByRole('button', { name: /Save & fetch/ });
+		expect(save.hasAttribute('disabled')).toBe(true);
+		// A bad URL must not reach the backend.
+		fireEvent.click(save);
+		expect(saveAgendaConfig).not.toHaveBeenCalled();
+	});
+
+	it('accepts a webcal:// URL as valid', async () => {
+		const { container, getByRole } = renderPanel();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://calendar.example.com/basic.ics'));
+		fireEvent.change(url, { target: { value: 'webcal://cal.example/feed.ics' } });
+		expect(url.getAttribute('aria-invalid')).toBe('false');
+		expect(getByRole('button', { name: /Save & fetch/ }).hasAttribute('disabled')).toBe(false);
+	});
+
+	it('saves the trimmed config (minutes → seconds) then restarts the task in order', async () => {
+		const { container, getByRole } = renderPanel();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://calendar.example.com/basic.ics'));
+		// Leading/trailing whitespace is trimmed before it crosses the bridge.
+		fireEvent.change(url, { target: { value: '  https://new.example/feed.ics  ' } });
+		const title = container.querySelector('input[placeholder="Agenda"]') as HTMLInputElement;
+		fireEvent.change(title, { target: { value: 'Personal' } });
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		fireEvent.change(poll, { target: { value: '45' } });
+
+		fireEvent.click(getByRole('button', { name: /Save & fetch/ }));
+
+		await waitFor(() =>
+			expect(saveAgendaConfig).toHaveBeenCalledWith({
+				url: 'https://new.example/feed.ics',
+				title: 'Personal',
+				pollSeconds: 2700 // 45 minutes
+			})
+		);
+		await waitFor(() => expect(agendaDisconnect).toHaveBeenCalled());
+		// Restart order: save → disconnect → connect (the running task holds the old config).
+		const save = vi.mocked(saveAgendaConfig).mock.invocationCallOrder[0];
+		const disc = vi.mocked(agendaDisconnect).mock.invocationCallOrder[0];
+		const conn = vi.mocked(agendaConnect).mock.invocationCallOrder.at(-1) as number;
+		expect(save).toBeLessThan(disc);
+		expect(disc).toBeLessThan(conn);
+	});
+
+	it('shows the "Saved ✓" confirmation after a successful save', async () => {
+		const { container, getByRole, findByText } = renderPanel();
+		const url = container.querySelector('input[inputmode="url"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://calendar.example.com/basic.ics'));
+		fireEvent.click(getByRole('button', { name: /Save & fetch/ }));
+		expect(await findByText('Saved ✓')).toBeTruthy();
+	});
+
+	it('reflects the live agenda.status sample in the badge', async () => {
+		const { getByText } = renderPanel();
+		await waitFor(() => expect(agendaConfigStatus).toHaveBeenCalled());
+		// Default badge before any sample is "Not connected".
+		expect(getByText(/Not connected/)).toBeTruthy();
+		act(() => {
+			hub.ingest({ sensor: 'agenda.status', ts_ms: 0, value: { kind: 'text', value: 'error' } });
+		});
+		expect(getByText(/Error/)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/HaMediaPlayerHost.test.tsx b/client/src/lib/widgets/plugins/HaMediaPlayerHost.test.tsx
new file mode 100644
index 0000000..69e006b
--- /dev/null
+++ b/client/src/lib/widgets/plugins/HaMediaPlayerHost.test.tsx
@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, render, waitFor } from '@testing-library/react';
+
+// Stub the HA Tauri command adapter (no backend in tests): the host resolves entity_picture →
+// art-scheme URL through haMediaArt and feeds it to the prop-only meter. A deferred promise lets us
+// drive when (and whether) the fetch resolves, so we can exercise the cancelled-after-unmount guard.
+const { haMediaArt } = vi.hoisted(() => ({
+	haMediaArt: vi.fn<(entity: string) => Promise<string>>()
+}));
+vi.mock('./ha-commands', () => ({ haMediaArt }));
+
+import HaMediaPlayerHost from './HaMediaPlayerHost';
+
+const withPicture = (entity_picture?: string): unknown =>
+	entity_picture === undefined
+		? { attributes: {} }
+		: { attributes: { entity_picture, friendly_name: 'Living Room' }, state: 'playing' };
+
+beforeEach(() => {
+	haMediaArt.mockReset();
+});
+
+afterEach(() => {
+	vi.restoreAllMocks();
+});
+
+describe('HaMediaPlayerHost (container wiring)', () => {
+	it('resolves entity_picture through haMediaArt and passes the art URL to the meter', async () => {
+		haMediaArt.mockResolvedValue('art://abc');
+		const { container } = render(<HaMediaPlayerHost value={withPicture('/api/pic?token=x')} />);
+		expect(haMediaArt).toHaveBeenCalledWith('/api/pic?token=x');
+		await waitFor(() => {
+			const img = container.querySelector('img[data-part="art"]') as HTMLImageElement | null;
+			expect(img?.getAttribute('src')).toBe('art://abc');
+		});
+	});
+
+	it('renders the meter with no art when the entity carries no entity_picture', async () => {
+		const { container } = render(<HaMediaPlayerHost value={withPicture()} />);
+		// No picture → no fetch, no <img>.
+		expect(haMediaArt).not.toHaveBeenCalled();
+		expect(container.querySelector('img[data-part="art"]')).toBeNull();
+		// The pure meter still renders (root present).
+		expect(container.querySelector('[data-part="root"]')).toBeTruthy();
+	});
+
+	it('clears the art when the picture is removed on a later render', async () => {
+		haMediaArt.mockResolvedValue('art://abc');
+		const { container, rerender } = render(
+			<HaMediaPlayerHost value={withPicture('/api/pic?token=x')} />
+		);
+		await waitFor(() => expect(container.querySelector('img[data-part="art"]')).toBeTruthy());
+		// Re-render with the picture gone: the effect's !pic branch resets art to undefined.
+		rerender(<HaMediaPlayerHost value={withPicture()} />);
+		await waitFor(() => expect(container.querySelector('img[data-part="art"]')).toBeNull());
+	});
+
+	it('falls back to no art when the fetch rejects', async () => {
+		haMediaArt.mockRejectedValue(new Error('boom'));
+		const { container } = render(<HaMediaPlayerHost value={withPicture('/api/pic?token=x')} />);
+		await waitFor(() => expect(haMediaArt).toHaveBeenCalled());
+		// The .catch arm sets art to undefined → no <img>.
+		await waitFor(() => expect(container.querySelector('img[data-part="art"]')).toBeNull());
+	});
+
+	it('does not apply a resolved URL after unmount (cancelled guard)', async () => {
+		let resolveArt!: (url: string) => void;
+		haMediaArt.mockReturnValue(new Promise<string>((res) => (resolveArt = res)));
+		const { unmount } = render(<HaMediaPlayerHost value={withPicture('/api/pic?token=x')} />);
+		expect(haMediaArt).toHaveBeenCalled();
+		unmount();
+		// Resolving after unmount must not throw or setState on the dead tree (cancelled === true).
+		await act(async () => {
+			resolveArt('art://late');
+		});
+	});
+
+	it('ignores a rejection that arrives after unmount (cancelled guard, catch arm)', async () => {
+		let rejectArt!: (err: unknown) => void;
+		haMediaArt.mockReturnValue(new Promise<string>((_res, rej) => (rejectArt = rej)));
+		const { unmount } = render(<HaMediaPlayerHost value={withPicture('/api/pic?token=x')} />);
+		expect(haMediaArt).toHaveBeenCalled();
+		unmount();
+		await act(async () => {
+			rejectArt(new Error('late'));
+		});
+	});
+});
diff --git a/client/src/lib/widgets/plugins/HaMediaPlayerHost.tsx b/client/src/lib/widgets/plugins/HaMediaPlayerHost.tsx
new file mode 100644
index 0000000..dd338fe
--- /dev/null
+++ b/client/src/lib/widgets/plugins/HaMediaPlayerHost.tsx
@@ -0,0 +1,45 @@
+// Bespoke container for the HA media_player widget: resolves the album-art URL as a side effect
+// (entity_picture → ha_media_art → art-scheme URL the webview can <img>-load), then renders the
+// prop-only HaMediaPlayer meter. Registered as ha.media_player's component — a documented Host
+// exception (AGENTS.md §6) so the meter itself stays pure/Tauri-free. Re-fetches only when the
+// entity_picture changes (HA varies it by a cache key per track), so it's one fetch per track.
+import { useEffect, useState } from 'react';
+import HaMediaPlayer from '../meters/HaMediaPlayer';
+import type { ControlEvent } from '../meterProps';
+import { haMediaArt } from './ha-commands';
+
+type HaState = { attributes?: Record<string, unknown> };
+
+type Props = {
+	value?: unknown;
+	label?: string;
+	onControl?: (e: ControlEvent) => void;
+	showTransport?: boolean;
+	showVolume?: boolean;
+};
+
+export default function HaMediaPlayerHost(props: Props) {
+	const pic =
+		((props.value as HaState | null)?.attributes?.entity_picture as string | undefined) ?? '';
+	const [art, setArt] = useState<string | undefined>(undefined);
+
+	useEffect(() => {
+		if (!pic) {
+			setArt(undefined);
+			return;
+		}
+		let cancelled = false;
+		haMediaArt(pic)
+			.then((url) => {
+				if (!cancelled) setArt(url);
+			})
+			.catch(() => {
+				if (!cancelled) setArt(undefined);
+			});
+		return () => {
+			cancelled = true;
+		};
+	}, [pic]);
+
+	return <HaMediaPlayer {...props} art={art} />;
+}
diff --git a/client/src/lib/widgets/plugins/HaSettings.test.tsx b/client/src/lib/widgets/plugins/HaSettings.test.tsx
index 7c9f8d9..91d6e09 100644
--- a/client/src/lib/widgets/plugins/HaSettings.test.tsx
+++ b/client/src/lib/widgets/plugins/HaSettings.test.tsx
@@ -50,7 +50,9 @@ import {
 	haConfigStatus,
 	haConnect,
 	haDisconnect,
+	haRegistrySnapshot,
 	haTestConnection,
+	listHaEntities,
 	saveHaConfig
 } from './ha-commands';
 import { copyToClipboard } from '../../overlay';
@@ -179,4 +181,191 @@ describe('HaSettings', () => {
 		// The device-less entity lands under the Unassigned bucket.
 		expect(await findByText('Unassigned')).toBeTruthy();
 	});
+
+	it('edits the URL field (marking the form dirty) and the basePath in Advanced', async () => {
+		const { container, findByText } = renderPanel();
+		await findByText('Kitchen Light');
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		fireEvent.change(url, { target: { value: 'http://ha.local:8123' } });
+		expect(url.value).toBe('http://ha.local:8123');
+		// The reverse-proxy subpath input is the second text-typed field (inside <details>).
+		const texts = container.querySelectorAll('input[type="text"]');
+		const basePath = texts[1] as HTMLInputElement;
+		fireEvent.change(basePath, { target: { value: '/homeassistant' } });
+		expect(basePath.value).toBe('/homeassistant');
+	});
+
+	it('toggles the insecure-TLS checkbox and shows the warning', async () => {
+		const { container, findByText, queryByText } = renderPanel();
+		await findByText('Kitchen Light');
+		// The first checkbox is the self-signed/invalid TLS toggle.
+		const insecure = container.querySelector('input[type="checkbox"]') as HTMLInputElement;
+		expect(queryByText(/Skips certificate/)).toBeNull();
+		fireEvent.click(insecure);
+		expect(insecure.checked).toBe(true);
+		expect(await findByText(/Skips certificate/)).toBeTruthy();
+		// Toggling it back hides the warning again.
+		fireEvent.click(insecure);
+		expect(queryByText(/Skips certificate/)).toBeNull();
+	});
+
+	it('passes the insecure flag and base path through to save', async () => {
+		const { container, getByText, findByText } = renderPanel();
+		await findByText('Kitchen Light');
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('http://ha:8123'));
+		const insecure = container.querySelector('input[type="checkbox"]') as HTMLInputElement;
+		fireEvent.click(insecure);
+		const basePath = container.querySelectorAll('input[type="text"]')[1] as HTMLInputElement;
+		fireEvent.change(basePath, { target: { value: '/ha' } });
+		fireEvent.click(getByText('Save & connect'));
+		await waitFor(() =>
+			expect(saveHaConfig).toHaveBeenCalledWith('http://ha:8123', '', true, '/ha')
+		);
+	});
+
+	it('shows a Save failed message when saveHaConfig rejects', async () => {
+		vi.mocked(saveHaConfig).mockRejectedValueOnce('disk full');
+		const { container, getByText, findByText } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('http://ha:8123'));
+		fireEvent.click(getByText('Save & connect'));
+		expect(await findByText(/Save failed: disk full/)).toBeTruthy();
+	});
+
+	it('reports a bare "Connected" when the test returns no version', async () => {
+		vi.mocked(haTestConnection).mockResolvedValueOnce({ ha_version: '' });
+		const { container, getByText, findByText } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('http://ha:8123'));
+		fireEvent.click(getByText('Test connection'));
+		const ok = await findByText('Connected');
+		expect(ok.textContent).toBe('Connected');
+	});
+
+	it('refreshes the entity catalog from the Refresh button', async () => {
+		const { findByText, getByText } = renderPanel();
+		await findByText('Kitchen Light');
+		vi.mocked(listHaEntities).mockResolvedValueOnce([
+			{ entity_id: 'switch.fan', state: 'off', friendly_name: 'Fan' }
+		]);
+		fireEvent.click(getByText('↻ Refresh'));
+		expect(await findByText('Fan')).toBeTruthy();
+	});
+
+	it('shows "No entities match the filter." when the flat search excludes everything', async () => {
+		const { findByText, getByLabelText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.change(getByLabelText('Filter entities'), { target: { value: 'zzz-nope' } });
+		expect(await findByText('No entities match the filter.')).toBeTruthy();
+	});
+
+	it('bulk-exposes then clears every visible entity', async () => {
+		const { findByText, getByText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.click(getByText('Expose all'));
+		expect(haExposedStore.getSnapshot()).toEqual(['ha.light.kitchen', 'ha.sensor.temp']);
+		fireEvent.click(getByText('Clear'));
+		expect(haExposedStore.getSnapshot()).toEqual([]);
+	});
+
+	it('filters the grouped tree (exercising the tree match fn)', async () => {
+		const { findAllByText, findByText, queryByText, getByLabelText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.click(getByLabelText('Group by area'));
+		await findByText('Living Room');
+		// Filter the grouped tree down to the kitchen light (exercises the tree match fn,
+		// which drops the device-less Temp entity from the Unassigned bucket).
+		fireEvent.change(getByLabelText('Filter entities'), { target: { value: 'kitchen' } });
+		await waitFor(() => expect(queryByText('Temp')).toBeNull());
+		// The grouped name uses live.friendly_name precedence → 'Kitchen Light'.
+		expect((await findAllByText('Kitchen Light')).length).toBeGreaterThan(0);
+	});
+
+	it('shows "Loading registry…" when grouping is on before the registry resolves', async () => {
+		// Never-resolving snapshot → the grouped view stays in its loading state with no tree.
+		vi.mocked(haRegistrySnapshot).mockReturnValueOnce(new Promise(() => undefined));
+		const { findByText, getByLabelText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.click(getByLabelText('Group by area'));
+		// The flat entities are gone (grouped view) but the registry hasn't arrived yet.
+		expect(await findByText('Loading registry…')).toBeTruthy();
+	});
+
+	it('falls back to the entity_id when an entity has no friendly name', async () => {
+		vi.mocked(listHaEntities).mockResolvedValueOnce([{ entity_id: 'light.bare', state: 'on' }]);
+		const { findAllByText } = renderPanel();
+		// No friendly_name → the name cell shows the entity_id itself (also shown in the id <code>).
+		expect((await findAllByText('light.bare')).length).toBeGreaterThan(0);
+	});
+
+	it('filters past a friendly-name-less entity (the `?? ""` fallback in the predicate)', async () => {
+		// switch.bare has no friendly_name; a query that misses its entity_id forces the predicate to
+		// evaluate `(e.friendly_name ?? '')` on a null name (the left `||` arm being false).
+		vi.mocked(listHaEntities).mockResolvedValueOnce([
+			{ entity_id: 'light.kitchen', state: 'on', friendly_name: 'Kitchen Light' },
+			{ entity_id: 'switch.bare', state: 'off' }
+		]);
+		const { findByText, getByLabelText, queryByText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.change(getByLabelText('Filter entities'), { target: { value: 'kitchen' } });
+		// switch.bare is dropped (its id misses + it has no friendly_name); kitchen stays.
+		await waitFor(() => expect(queryByText('switch.bare')).toBeNull());
+		expect(await findByText('Kitchen Light')).toBeTruthy();
+	});
+
+	it('shows "No entities match the filter." in the grouped view too', async () => {
+		const { findByText, getByLabelText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.click(getByLabelText('Group by area'));
+		await findByText('Living Room'); // registry resolved
+		fireEvent.change(getByLabelText('Filter entities'), { target: { value: 'zzz-nope' } });
+		expect(await findByText('No entities match the filter.')).toBeTruthy();
+	});
+
+	it('renders a registry entity with no live state in the grouped tree', async () => {
+		// The registry can list an entity that /api/states didn't return → no liveMap entry, so its
+		// state falls back to '' (exercises `e.state ?? ''` for both device + loose grouped rows).
+		vi.mocked(haRegistrySnapshot).mockResolvedValueOnce({
+			areas: [{ area_id: 'living', name: 'Living Room' }],
+			devices: [{ id: 'd1', name: 'Lamp', area_id: 'living', manufacturer: null, model: null }],
+			entities: [
+				{
+					entity_id: 'light.ghost', // not in listHaEntities → no live state
+					device_id: 'd1',
+					area_id: null,
+					name: 'Ghost Light',
+					original_name: null,
+					platform: 'x'
+				},
+				{
+					entity_id: 'sensor.loose', // device-less + no live state → loose row
+					device_id: null,
+					area_id: null,
+					name: 'Loose Sensor',
+					original_name: null,
+					platform: 'x'
+				}
+			]
+		});
+		const { findByText, getByLabelText } = renderPanel();
+		await findByText('Kitchen Light');
+		fireEvent.click(getByLabelText('Group by area'));
+		expect(await findByText('Ghost Light')).toBeTruthy();
+		expect(await findByText('Loose Sensor')).toBeTruthy();
+	});
+
+	it('defaults the URL to empty when ha_config_status omits it', async () => {
+		// Exercises the `s.url ?? ''` fallback in the prefill effect.
+		vi.mocked(haConfigStatus).mockResolvedValueOnce({
+			configured: false,
+			url: null,
+			insecure: false,
+			base_path: ''
+		});
+		const { container, findByText } = renderPanel();
+		await findByText('Kitchen Light');
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		expect(url.value).toBe('');
+	});
 });
diff --git a/client/src/lib/widgets/plugins/LlmSettings.test.tsx b/client/src/lib/widgets/plugins/LlmSettings.test.tsx
new file mode 100644
index 0000000..6ffe10a
--- /dev/null
+++ b/client/src/lib/widgets/plugins/LlmSettings.test.tsx
@@ -0,0 +1,658 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+
+// Mock the LLM Tauri command adapter so the panel (the form + the model picker + the chat tester) can
+// be exercised without a backend. Every fn is a spy so we can assert call args. The api_key is
+// write-only over the bridge, so llmConfigStatus only ever reports `hasKey` (see llm-types.ts).
+vi.mock('./llm-commands', () => ({
+	controlStart: vi.fn(() => Promise.resolve()),
+	controlStop: vi.fn(() => Promise.resolve()),
+	llmConfigStatus: vi.fn(() =>
+		Promise.resolve({
+			configured: true,
+			active: 'openai',
+			providers: {
+				openai: {
+					baseUrl: 'https://my-proxy.test/v1',
+					model: 'gpt-4o',
+					hasKey: true,
+					insecure: false,
+					sttModel: '',
+					ttsModel: '',
+					ttsVoice: ''
+				}
+			},
+			temperature: 0.7,
+			maxTokens: 1024,
+			agentControl: false
+		})
+	),
+	saveLlmConfig: vi.fn(() => Promise.resolve()),
+	llmTestConnection: vi.fn(() => Promise.resolve({ model: 'gpt-4o', reply: 'pong' })),
+	llmComplete: vi.fn(() => Promise.resolve('{"ops":[],"summary":"ok"}')),
+	llmListModels: vi.fn(() =>
+		Promise.resolve([
+			{ id: 'gpt-4o', label: 'gpt-4o' },
+			{ id: 'gpt-4o-mini', label: 'gpt-4o-mini' }
+		])
+	),
+	llmTranscribe: vi.fn(() => Promise.resolve('')),
+	// Used by the chat tester (useLlmChat) + llm-tts; resolve so a Send doesn't hang.
+	llmStream: vi.fn(() => Promise.resolve()),
+	llmCancel: vi.fn(() => Promise.resolve()),
+	llmSynthesize: vi.fn(() => Promise.reject(new Error('no tts')))
+}));
+
+// happy-dom exposes no real mic/speech APIs, so the mic + read-aloud controls never render unless we
+// force the feature-detect adapters on. Mock them so the dictation / TTS branches are reachable.
+vi.mock('../../stt', () => ({
+	sttAvailable: vi.fn(() => true),
+	startRecording: vi.fn()
+}));
+vi.mock('../../tts', () => ({
+	ttsAvailable: vi.fn(() => true)
+}));
+vi.mock('./llm-tts', () => ({
+	speakSmart: vi.fn(() => Promise.resolve())
+}));
+
+import LlmSettings from './LlmSettings';
+import {
+	controlStart,
+	controlStop,
+	llmComplete,
+	llmConfigStatus,
+	llmListModels,
+	llmStream,
+	llmTestConnection,
+	llmTranscribe,
+	saveLlmConfig
+} from './llm-commands';
+import type { LlmStatus } from './llm-types';
+import { setLlmStudioApi } from './llm-studio';
+import { speakSmart } from './llm-tts';
+import { startRecording, type Recorder } from '../../stt';
+import { handleDelta, resetChat } from '../../../stores/llmStore';
+import { emptyMonitorLayout } from '../../core/layoutTree';
+import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
+import { TelemetryHubContext } from '../telemetryContext';
+
+let hub: TelemetryHub;
+
+function renderPanel() {
+	hub = createTelemetryHub();
+	return render(
+		<TelemetryHubContext.Provider value={hub}>
+			<LlmSettings />
+		</TelemetryHubContext.Provider>
+	);
+}
+
+// A configured status with one OpenAI provider that has a saved key — the default the panel loads.
+const configuredStatus = (over: Partial<LlmStatus> = {}): LlmStatus => ({
+	configured: true,
+	active: 'openai',
+	providers: {
+		openai: {
+			baseUrl: 'https://my-proxy.test/v1',
+			model: 'gpt-4o',
+			hasKey: true,
+			insecure: false,
+			sttModel: '',
+			ttsModel: '',
+			ttsVoice: ''
+		}
+	},
+	temperature: 0.7,
+	maxTokens: 1024,
+	agentControl: false,
+	...over
+});
+
+// Field-locating helpers: the form has no test ids, so reach inputs by their wrapping <label> text.
+const baseUrlInput = (c: HTMLElement) =>
+	[...c.querySelectorAll('label')]
+		.find((l) => l.textContent?.includes('Base URL'))!
+		.querySelector('input') as HTMLInputElement;
+const apiKeyInput = (c: HTMLElement) =>
+	c.querySelector('input[type="password"]') as HTMLInputElement;
+const providerSelect = (c: HTMLElement) =>
+	[...c.querySelectorAll('label')]
+		.find((l) => l.textContent?.startsWith('Provider'))!
+		.querySelector('select') as HTMLSelectElement;
+// "Save"/"Test" also appear as <strong> in the help line, so target the actual <button> by its text.
+const button = (c: HTMLElement, text: string) =>
+	[...c.querySelectorAll('button')].find(
+		(b) => b.textContent?.trim() === text
+	) as HTMLButtonElement;
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	resetChat(); // the chat tester shares the module-level llmStore — clear it between tests
+	setLlmStudioApi(null); // the layout assistant reads a module-level studio slot — reset it
+	vi.mocked(llmConfigStatus).mockResolvedValue(configuredStatus());
+	vi.mocked(llmListModels).mockResolvedValue([
+		{ id: 'gpt-4o', label: 'gpt-4o' },
+		{ id: 'gpt-4o-mini', label: 'gpt-4o-mini' }
+	]);
+});
+
+describe('LlmSettings', () => {
+	it('prefills the active provider + base URL from llm_config_status, never showing the key', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(providerSelect(container).value).toBe('openai'));
+		expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1');
+		// The API key is write-only: the field stays empty even though OpenAI is configured.
+		expect(apiKeyInput(container).value).toBe('');
+		// The placeholder signals a saved key without revealing it.
+		expect(apiKeyInput(container).placeholder).toMatch(/saved — leave blank to keep/);
+	});
+
+	it('shows the "configured" badge + the active provider label when the saved provider has a key', async () => {
+		const { container } = renderPanel();
+		// The status badge flips to ● configured once the saved key is loaded.
+		await waitFor(() =>
+			expect(container.querySelector('.has-badge')?.textContent).toMatch(/● configured/)
+		);
+		// The active provider's label sits in the dim status line next to the badge.
+		expect(container.querySelector('.has-state-dim')?.textContent).toBe('OpenAI / compatible');
+	});
+
+	it('auto-loads the provider model list on mount', async () => {
+		renderPanel();
+		await waitFor(() =>
+			expect(llmListModels).toHaveBeenCalledWith(
+				expect.objectContaining({ provider: 'openai', baseUrl: 'https://my-proxy.test/v1' })
+			)
+		);
+	});
+
+	it('marks the form dirty after an edit (Unsaved cue)', async () => {
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		fireEvent.change(baseUrlInput(container), { target: { value: 'https://other.test/v1' } });
+		expect(baseUrlInput(container).value).toBe('https://other.test/v1');
+		expect(await findByText(/Unsaved/)).toBeTruthy();
+	});
+
+	it('switches providers and reloads the picked provider defaults (key field hidden for keyless ollama)', async () => {
+		const { container, queryByText } = renderPanel();
+		await waitFor(() => expect(providerSelect(container).value).toBe('openai'));
+		fireEvent.change(providerSelect(container), { target: { value: 'ollama' } });
+		// Ollama has no saved entry → its catalog default base URL + first sample model populate the form.
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('http://localhost:11434'));
+		// Ollama is keyless, so the API key field is not rendered at all.
+		expect(apiKeyInput(container)).toBeNull();
+		expect(queryByText(/saved — leave blank to keep/)).toBeNull();
+	});
+
+	it('saves the form body, clears the key, refreshes status and shows Saved ✓', async () => {
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-new-key' } });
+		// A fresh status is returned after save (so the badges + hasKey refresh).
+		vi.mocked(llmConfigStatus).mockResolvedValueOnce(configuredStatus());
+		fireEvent.click(button(container, 'Save'));
+
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(
+				expect.objectContaining({
+					provider: 'openai',
+					baseUrl: 'https://my-proxy.test/v1',
+					apiKey: 'sk-new-key',
+					model: 'gpt-4o'
+				})
+			)
+		);
+		// Status is re-read after the save to refresh the per-provider key badges.
+		await waitFor(() => expect(llmConfigStatus).toHaveBeenCalledTimes(2));
+		// The key field is cleared back to write-only and the toast appears.
+		await waitFor(() => expect(apiKeyInput(container).value).toBe(''));
+		expect(await findByText('Saved ✓')).toBeTruthy();
+	});
+
+	it('surfaces a save failure in the test line', async () => {
+		vi.mocked(saveLlmConfig).mockRejectedValueOnce('disk full');
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-x' } });
+		fireEvent.click(button(container, 'Save'));
+		expect(await findByText(/Save failed: disk full/)).toBeTruthy();
+	});
+
+	it('tests the connection without saving and reports the model + reply', async () => {
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		fireEvent.click(button(container, 'Test'));
+		await waitFor(() =>
+			expect(llmTestConnection).toHaveBeenCalledWith(
+				'openai',
+				'https://my-proxy.test/v1',
+				'',
+				'gpt-4o',
+				false
+			)
+		);
+		// Test must NOT persist anything.
+		expect(saveLlmConfig).not.toHaveBeenCalled();
+		expect(await findByText(/gpt-4o replied/)).toBeTruthy();
+		expect(await findByText(/pong/)).toBeTruthy();
+	});
+
+	it('shows the test error message when the connection test rejects', async () => {
+		vi.mocked(llmTestConnection).mockRejectedValueOnce('401 invalid api key');
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		fireEvent.click(button(container, 'Test'));
+		expect(await findByText(/401 invalid api key/)).toBeTruthy();
+	});
+
+	it('refreshes the model list and reports the count next to the ↻ Models button', async () => {
+		const { getByText, findByText } = renderPanel();
+		await waitFor(() => expect(llmListModels).toHaveBeenCalled()); // the on-mount auto-load
+		vi.mocked(llmListModels).mockClear();
+		fireEvent.click(getByText('↻ Models'));
+		await waitFor(() => expect(llmListModels).toHaveBeenCalledTimes(1));
+		expect(await findByText('Loaded 2 models')).toBeTruthy();
+	});
+
+	it('reports an empty-list result as a typeable hint', async () => {
+		const { getByText, findByText } = renderPanel();
+		await waitFor(() => expect(llmListModels).toHaveBeenCalled());
+		vi.mocked(llmListModels).mockResolvedValueOnce([]);
+		fireEvent.click(getByText('↻ Models'));
+		expect(await findByText(/returned no models/)).toBeTruthy();
+	});
+
+	it('reports a model-list failure rather than silently doing nothing', async () => {
+		const { getByText, findByText } = renderPanel();
+		await waitFor(() => expect(llmListModels).toHaveBeenCalled());
+		vi.mocked(llmListModels).mockRejectedValueOnce('network down');
+		fireEvent.click(getByText('↻ Models'));
+		expect(await findByText(/Could not list models: network down/)).toBeTruthy();
+	});
+
+	it('gates the chat tester on a SAVED configured provider', async () => {
+		// Active provider is configured → the chat input is reachable (no "save first" warning).
+		const { findByPlaceholderText, queryByText } = renderPanel();
+		expect(await findByPlaceholderText('Ask anything…')).toBeTruthy();
+		expect(queryByText(/Save a configured provider/)).toBeNull();
+	});
+
+	it('shows the chat "save first" warning when no provider is configured', async () => {
+		vi.mocked(llmConfigStatus).mockResolvedValue(
+			configuredStatus({
+				configured: false,
+				providers: { openai: { ...configuredStatus().providers.openai, hasKey: false } }
+			})
+		);
+		const { findByText, queryByPlaceholderText } = renderPanel();
+		expect(await findByText(/Save a configured provider above to start chatting/)).toBeTruthy();
+		expect(queryByPlaceholderText('Ask anything…')).toBeNull();
+	});
+
+	it('disables the layout assistant Generate button until a prompt is typed, then runs it', async () => {
+		const { container, getByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const gen = getByText(/Generate/).closest('button') as HTMLButtonElement;
+		expect(gen.disabled).toBe(true);
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		fireEvent.change(textarea, { target: { value: 'add a clock' } });
+		expect(gen.disabled).toBe(false);
+		// No studio api is wired (overlay/dev) → the assistant tells the user to open the canvas first.
+		fireEvent.click(gen);
+		await waitFor(() => expect(getByText(/Open the studio canvas first/)).toBeTruthy());
+	});
+
+	it('disables Save until a usable key exists (needs-key provider, none saved, blank input)', async () => {
+		// An OpenAI provider that has NO saved key → Save must stay disabled until the user types one.
+		vi.mocked(llmConfigStatus).mockResolvedValue(
+			configuredStatus({
+				configured: false,
+				providers: { openai: { ...configuredStatus().providers.openai, hasKey: false } }
+			})
+		);
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		expect(button(container, 'Save').disabled).toBe(true);
+		// Typing a key makes the form submittable.
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-typed' } });
+		expect(button(container, 'Save').disabled).toBe(false);
+	});
+
+	it('shows the speech model fields only for an audio-capable provider and folds edits into the save body', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		// OpenAI supports audio → the STT/TTS/voice combobox inputs render (Select sets an aria-label).
+		const stt = await waitFor(() => {
+			const el = container.querySelector('input[aria-label="Speech-to-text model"]');
+			if (!el) throw new Error('no speech field yet');
+			return el as HTMLInputElement;
+		});
+		fireEvent.change(stt, { target: { value: 'whisper-1' } });
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-aud' } });
+		fireEvent.click(button(container, 'Save'));
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(expect.objectContaining({ sttModel: 'whisper-1' }))
+		);
+		// Switching to keyless Ollama (no audio support) removes the speech pickers entirely.
+		fireEvent.change(providerSelect(container), { target: { value: 'ollama' } });
+		await waitFor(() =>
+			expect(container.querySelector('input[aria-label="Speech-to-text model"]')).toBeNull()
+		);
+	});
+
+	it('persists the advanced temperature / max-token params into the save body', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const temp = container.querySelector('input[type="number"][max="2"]') as HTMLInputElement;
+		const maxTok = container.querySelector('input[type="number"][max="32000"]') as HTMLInputElement;
+		fireEvent.change(temp, { target: { value: '0.2' } });
+		fireEvent.change(maxTok, { target: { value: '2048' } });
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-adv' } });
+		fireEvent.click(button(container, 'Save'));
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(
+				expect.objectContaining({ temperature: 0.2, maxTokens: 2048 })
+			)
+		);
+	});
+
+	it('persists + starts the agent-control server when the toggle is enabled (independent of the key)', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const toggle = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('agent control')
+		) as HTMLInputElement;
+		fireEvent.click(toggle);
+		// The toggle saves directly (not gated behind Save) and then boots the local control server.
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(expect.objectContaining({ agentControl: true }))
+		);
+		await waitFor(() => expect(controlStart).toHaveBeenCalled());
+	});
+
+	it('sends a chat message: shows the user turn and streams via llm_stream', async () => {
+		const { container, findByPlaceholderText, findByText } = renderPanel();
+		const input = (await findByPlaceholderText('Ask anything…')) as HTMLInputElement;
+		fireEvent.change(input, { target: { value: 'hello there' } });
+		fireEvent.click(button(container, 'Send'));
+		// The user's turn renders immediately and the stream is kicked off.
+		expect(await findByText('hello there')).toBeTruthy();
+		await waitFor(() =>
+			expect(llmStream).toHaveBeenCalledWith(
+				expect.stringMatching(/^chat-/),
+				expect.arrayContaining([expect.objectContaining({ role: 'user', content: 'hello there' })])
+			)
+		);
+		// The input clears after sending.
+		expect(input.value).toBe('');
+	});
+
+	it('reports an agent-control toggle failure in the test line', async () => {
+		vi.mocked(saveLlmConfig).mockRejectedValueOnce('locked');
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const toggle = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('agent control')
+		) as HTMLInputElement;
+		fireEvent.click(toggle);
+		expect(await findByText(/Agent control: locked/)).toBeTruthy();
+		// The save rejected before the control server boot, so neither start nor stop ran.
+		expect(controlStart).not.toHaveBeenCalled();
+		expect(controlStop).not.toHaveBeenCalled();
+	});
+
+	it('marks the form dirty when the model / TTS-voice combobox is edited', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const model = container.querySelector('input[aria-label="Model"]') as HTMLInputElement;
+		fireEvent.change(model, { target: { value: 'gpt-4o-mini' } });
+		// Change every speech picker to a NON-default value so each Select's onChange actually fires
+		// (Downshift skips onInputValueChange when the typed text equals the current value).
+		const stt = container.querySelector(
+			'input[aria-label="Speech-to-text model"]'
+		) as HTMLInputElement;
+		const ttsModel = container.querySelector(
+			'input[aria-label="Text-to-speech model"]'
+		) as HTMLInputElement;
+		const voice = container.querySelector(
+			'input[aria-label="Text-to-speech voice"]'
+		) as HTMLInputElement;
+		fireEvent.change(stt, { target: { value: 'gpt-4o-transcribe' } });
+		fireEvent.change(ttsModel, { target: { value: 'tts-1-hd' } });
+		fireEvent.change(voice, { target: { value: 'nova' } });
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-x' } });
+		fireEvent.click(button(container, 'Save'));
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(
+				expect.objectContaining({
+					model: 'gpt-4o-mini',
+					sttModel: 'gpt-4o-transcribe',
+					ttsModel: 'tts-1-hd',
+					ttsVoice: 'nova'
+				})
+			)
+		);
+	});
+
+	it('marks the form dirty when the self-signed-TLS checkbox is toggled', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const insecure = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('self-signed')
+		) as HTMLInputElement;
+		fireEvent.click(insecure);
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-tls' } });
+		fireEvent.click(button(container, 'Save'));
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(expect.objectContaining({ insecure: true }))
+		);
+	});
+
+	// --- layout assistant: dictation + generate ---------------------------------------------
+
+	it('dictates into the prompt: starts the mic, then stops + transcribes on the second click', async () => {
+		const stop = vi.fn(() =>
+			Promise.resolve({ bytes: new Uint8Array([1, 2]), mime: 'audio/webm' })
+		);
+		const cancel = vi.fn();
+		const recorder: Recorder = { stop, cancel };
+		vi.mocked(startRecording).mockResolvedValue(recorder);
+		vi.mocked(llmTranscribe).mockResolvedValueOnce('hello world');
+
+		const { container, findByText, getByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		// First click starts the mic.
+		fireEvent.click(getByText('🎤 Speak'));
+		await waitFor(() => expect(startRecording).toHaveBeenCalled());
+		expect(await findByText(/Listening/)).toBeTruthy();
+		// Second click stops + transcribes the captured bytes into the prompt textarea.
+		fireEvent.click(getByText('■ Stop'));
+		await waitFor(() => expect(stop).toHaveBeenCalled());
+		await waitFor(() =>
+			expect(llmTranscribe).toHaveBeenCalledWith(new Uint8Array([1, 2]), 'audio/webm')
+		);
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		await waitFor(() => expect(textarea.value).toBe('hello world'));
+	});
+
+	it('appends a 2nd dictation to existing prompt text and surfaces a transcription failure', async () => {
+		const stop = vi.fn(() => Promise.resolve({ bytes: new Uint8Array([9]), mime: 'audio/webm' }));
+		vi.mocked(startRecording).mockResolvedValue({ stop, cancel: vi.fn() });
+		const { container, getByText, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		fireEvent.change(textarea, { target: { value: 'existing' } });
+		vi.mocked(llmTranscribe).mockResolvedValueOnce('more');
+		fireEvent.click(getByText('🎤 Speak'));
+		await waitFor(() => expect(startRecording).toHaveBeenCalled());
+		fireEvent.click(getByText('■ Stop'));
+		await waitFor(() => expect(textarea.value).toBe('existing more'));
+		// A subsequent recording whose transcription rejects shows the failure message.
+		vi.mocked(llmTranscribe).mockRejectedValueOnce('whisper 500');
+		fireEvent.click(getByText('🎤 Speak'));
+		await waitFor(() => expect(startRecording).toHaveBeenCalledTimes(2));
+		fireEvent.click(getByText('■ Stop'));
+		expect(await findByText(/Voice failed: whisper 500/)).toBeTruthy();
+	});
+
+	it('falls back to the openai provider when the saved status reports no active provider', async () => {
+		vi.mocked(llmConfigStatus).mockResolvedValue(configuredStatus({ active: '' }));
+		const { container } = renderPanel();
+		await waitFor(() => expect(providerSelect(container).value).toBe('openai'));
+	});
+
+	it('stops the agent-control server when the toggle is switched OFF', async () => {
+		// Start from a status with agent control already ON so the toggle's first flip turns it off.
+		vi.mocked(llmConfigStatus).mockResolvedValue(configuredStatus({ agentControl: true }));
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const toggle = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('agent control')
+		) as HTMLInputElement;
+		expect(toggle.checked).toBe(true);
+		fireEvent.click(toggle);
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(expect.objectContaining({ agentControl: false }))
+		);
+		await waitFor(() => expect(controlStop).toHaveBeenCalled());
+		expect(controlStart).not.toHaveBeenCalled();
+	});
+
+	it('reports a single loaded model with singular wording', async () => {
+		const { getByText, findByText } = renderPanel();
+		await waitFor(() => expect(llmListModels).toHaveBeenCalled());
+		vi.mocked(llmListModels).mockResolvedValueOnce([{ id: 'gpt-4o', label: 'gpt-4o' }]);
+		fireEvent.click(getByText('↻ Models'));
+		expect(await findByText('Loaded 1 model')).toBeTruthy();
+	});
+
+	it('falls back to 1024 max-tokens when the field is cleared', async () => {
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const maxTok = container.querySelector('input[type="number"][max="32000"]') as HTMLInputElement;
+		fireEvent.change(maxTok, { target: { value: '' } });
+		fireEvent.change(apiKeyInput(container), { target: { value: 'sk-mt' } });
+		fireEvent.click(button(container, 'Save'));
+		await waitFor(() =>
+			expect(saveLlmConfig).toHaveBeenCalledWith(expect.objectContaining({ maxTokens: 1024 }))
+		);
+	});
+
+	it('shows a mic-unavailable message when starting the recorder rejects', async () => {
+		vi.mocked(startRecording).mockRejectedValueOnce('NotAllowedError');
+		const { container, getByText, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		fireEvent.click(getByText('🎤 Speak'));
+		expect(await findByText(/Mic unavailable: NotAllowedError/)).toBeTruthy();
+	});
+
+	it('ignores a Ctrl+Enter on an empty prompt (no completion call)', async () => {
+		setLlmStudioApi({ monitor: () => emptyMonitorLayout(), apply: vi.fn() });
+		const { container } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		fireEvent.keyDown(textarea, { key: 'Enter', ctrlKey: true });
+		expect(llmComplete).not.toHaveBeenCalled();
+	});
+
+	it('warns when generating with no monitor layout available', async () => {
+		setLlmStudioApi({
+			monitor: () => null as never,
+			apply: () => ({ applied: 0, addedIds: [], errors: [] })
+		});
+		const { container, getByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		fireEvent.change(textarea, { target: { value: 'add a clock' } });
+		fireEvent.click(getByText(/Generate/));
+		await waitFor(() => expect(getByText(/No layout to edit yet/)).toBeTruthy());
+	});
+
+	it('runs the layout assistant end-to-end via Ctrl+Enter when the studio is wired', async () => {
+		const apply = vi.fn(() => ({ applied: 2, addedIds: ['a', 'b'], errors: [] }));
+		const monitor = emptyMonitorLayout();
+		setLlmStudioApi({ monitor: () => monitor, apply });
+		const { container, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		fireEvent.change(textarea, { target: { value: 'add a clock and a gauge' } });
+		// Ctrl+Enter submits (covers the textarea keydown handler).
+		fireEvent.keyDown(textarea, { key: 'Enter', ctrlKey: true });
+		await waitFor(() => expect(llmComplete).toHaveBeenCalled());
+		await waitFor(() => expect(apply).toHaveBeenCalledWith([]));
+		// The summary + applied-count line renders, and the prompt clears.
+		expect(await findByText(/ok — 2 changes/)).toBeTruthy();
+		expect(textarea.value).toBe('');
+	});
+
+	it('reports applied errors and an invalid-reply / failed completion in the assistant', async () => {
+		const apply = vi.fn(() => ({ applied: 1, addedIds: [], errors: ['bad op'] }));
+		const monitor = emptyMonitorLayout();
+		setLlmStudioApi({ monitor: () => monitor, apply });
+		// First: a reply the parser rejects → "did not return valid layout ops".
+		vi.mocked(llmComplete).mockResolvedValueOnce('not json at all');
+		const { container, getByText, findByText } = renderPanel();
+		await waitFor(() => expect(baseUrlInput(container).value).toBe('https://my-proxy.test/v1'));
+		const textarea = container.querySelector('textarea') as HTMLTextAreaElement;
+		fireEvent.change(textarea, { target: { value: 'do a thing' } });
+		fireEvent.click(getByText(/Generate/));
+		expect(await findByText(/did not return valid layout ops/)).toBeTruthy();
+
+		// Next: a valid reply whose apply yields errors → summary includes the error tail (1 change).
+		fireEvent.change(textarea, { target: { value: 'again' } });
+		fireEvent.click(getByText(/Generate/));
+		expect(await findByText(/1 change \(bad op\)/)).toBeTruthy();
+
+		// A reply with no summary string falls back to "Done" in the result line.
+		vi.mocked(llmComplete).mockResolvedValueOnce('{"ops":[]}');
+		fireEvent.change(textarea, { target: { value: 'no summary' } });
+		fireEvent.click(getByText(/Generate/));
+		expect(await findByText(/Done — 1 change/)).toBeTruthy();
+
+		// Finally: llm_complete rejects → "Failed:" message.
+		vi.mocked(llmComplete).mockRejectedValueOnce('timeout');
+		fireEvent.change(textarea, { target: { value: 'boom' } });
+		fireEvent.click(getByText(/Generate/));
+		expect(await findByText(/Failed: timeout/)).toBeTruthy();
+	});
+
+	// --- chat tester: streamed assistant turn + read-aloud ----------------------------------
+
+	it('renders a finished assistant turn with a working read-aloud button, and sends on Enter', async () => {
+		const { container, findByPlaceholderText, findByText } = renderPanel();
+		const input = (await findByPlaceholderText('Ask anything…')) as HTMLInputElement;
+		fireEvent.change(input, { target: { value: 'hi' } });
+		// Enter (no modifier) sends — covers the chat input keydown handler.
+		fireEvent.keyDown(input, { key: 'Enter' });
+		await waitFor(() => expect(llmStream).toHaveBeenCalled());
+		const requestId = vi.mocked(llmStream).mock.calls[0][0] as string;
+		// Stream a completed assistant turn into the shared store so the read-aloud button renders.
+		act(() => {
+			handleDelta({ requestId, token: 'a reply', done: false });
+			handleDelta({ requestId, token: '', done: true });
+		});
+		const speak = (await findByText('🔊')) as HTMLButtonElement;
+		fireEvent.click(speak);
+		expect(speakSmart).toHaveBeenCalledWith('a reply');
+		// Clearing the transcript removes the turns + the Clear button.
+		fireEvent.click(button(container, 'Clear'));
+		await waitFor(() => expect(container.querySelector('.has-entity')).toBeNull());
+	});
+
+	it('ignores Enter with an empty chat input and renders an errored assistant turn', async () => {
+		const { findByPlaceholderText, findByText } = renderPanel();
+		const input = (await findByPlaceholderText('Ask anything…')) as HTMLInputElement;
+		// Enter on an empty input is a no-op (covers the onSend empty guard).
+		fireEvent.keyDown(input, { key: 'Enter' });
+		expect(llmStream).not.toHaveBeenCalled();
+		// A real send whose stream ends in an error renders the ⚠ error turn (no read-aloud button).
+		fireEvent.change(input, { target: { value: 'go' } });
+		fireEvent.keyDown(input, { key: 'Enter' });
+		await waitFor(() => expect(llmStream).toHaveBeenCalled());
+		const requestId = vi.mocked(llmStream).mock.calls[0][0] as string;
+		act(() => handleDelta({ requestId, token: '', done: true, error: 'rate limited' }));
+		expect(await findByText(/⚠ rate limited/)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/MqttSettings.test.tsx b/client/src/lib/widgets/plugins/MqttSettings.test.tsx
index c2a1bb7..d8a0de6 100644
--- a/client/src/lib/widgets/plugins/MqttSettings.test.tsx
+++ b/client/src/lib/widgets/plugins/MqttSettings.test.tsx
@@ -27,7 +27,7 @@ vi.mock('./mqtt-commands', () => ({
 vi.mock('../../overlay', () => ({ copyToClipboard: vi.fn(() => Promise.resolve(true)) }));
 
 import MqttSettings from './MqttSettings';
-import { mqttConfigStatus, mqttDisconnect, saveMqttConfig } from './mqtt-commands';
+import { mqttCatalog, mqttConfigStatus, mqttDisconnect, saveMqttConfig } from './mqtt-commands';
 import { copyToClipboard } from '../../overlay';
 import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
 import { TelemetryHubContext } from '../telemetryContext';
@@ -86,4 +86,99 @@ describe('MqttSettings', () => {
 		});
 		expect(getByText(/Connected/)).toBeTruthy();
 	});
+
+	it('edits every broker field, toggles the options and folds them into the save body', async () => {
+		const { container, getByText, getByLabelText, getByPlaceholderText } = renderPanel();
+		const host = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(host.value).toBe('broker.local'));
+
+		fireEvent.change(host, { target: { value: 'mqtt.example' } });
+		const port = container.querySelector('input[type="number"]') as HTMLInputElement;
+		fireEvent.change(port, { target: { value: '8883' } });
+		const username = getByPlaceholderText('(optional)') as HTMLInputElement;
+		fireEvent.change(username, { target: { value: 'alice' } });
+		const password = container.querySelector('input[type="password"]') as HTMLInputElement;
+		fireEvent.change(password, { target: { value: 'secret' } });
+		const clientId = getByPlaceholderText('widgetsack (default)') as HTMLInputElement;
+		fireEvent.change(clientId, { target: { value: 'cid' } });
+
+		// Removing a topic chip drives the TokenListField onChange.
+		fireEvent.click(getByLabelText('Remove tasmota/SENSOR'));
+
+		// Discovery defaults ON (status.discovery=true) → toggle it OFF; flip TLS + insecure ON.
+		const discovery = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('discovery')
+		) as HTMLInputElement;
+		const tls = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('Use TLS')
+		) as HTMLInputElement;
+		const insecure = [...container.querySelectorAll('input[type="checkbox"]')].find((c) =>
+			c.closest('label')?.textContent?.includes('self-signed')
+		) as HTMLInputElement;
+		fireEvent.click(discovery);
+		fireEvent.click(tls);
+		fireEvent.click(insecure);
+		// The self-signed warning renders once insecure is checked.
+		expect(getByText(/only for a trusted LAN broker/)).toBeTruthy();
+
+		fireEvent.click(getByText('Save & connect'));
+		await waitFor(() =>
+			expect(saveMqttConfig).toHaveBeenCalledWith(
+				expect.objectContaining({
+					host: 'mqtt.example',
+					port: 8883,
+					username: 'alice',
+					password: 'secret',
+					clientId: 'cid',
+					topics: ['zigbee2mqtt/#'],
+					tls: true,
+					insecure: true,
+					discovery: false
+				})
+			)
+		);
+	});
+
+	it('falls back to port 1883 when the port field is cleared', async () => {
+		const { container, getByText } = renderPanel();
+		const host = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(host.value).toBe('broker.local'));
+		const port = container.querySelector('input[type="number"]') as HTMLInputElement;
+		fireEvent.change(port, { target: { value: '' } });
+		fireEvent.click(getByText('Save & connect'));
+		await waitFor(() =>
+			expect(saveMqttConfig).toHaveBeenCalledWith(expect.objectContaining({ port: 1883 }))
+		);
+	});
+
+	it('surfaces a save failure (Error message) in the error line', async () => {
+		vi.mocked(saveMqttConfig).mockRejectedValueOnce(new Error('broker refused'));
+		const { container, getByText, findByText } = renderPanel();
+		const host = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(host.value).toBe('broker.local'));
+		fireEvent.click(getByText('Save & connect'));
+		expect(await findByText(/Couldn’t save: broker refused/)).toBeTruthy();
+	});
+
+	it('surfaces a non-Error save failure stringified', async () => {
+		vi.mocked(saveMqttConfig).mockRejectedValueOnce('disk full');
+		const { container, getByText, findByText } = renderPanel();
+		const host = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(host.value).toBe('broker.local'));
+		fireEvent.click(getByText('Save & connect'));
+		expect(await findByText(/Couldn’t save: disk full/)).toBeTruthy();
+	});
+
+	it('refreshes the topic catalog on demand and falls back to the topic when an entry has no label', async () => {
+		// First mount loads the default catalog; the refresh returns a label-less entry → topic fallback.
+		const { findByText, getByText } = renderPanel();
+		await findByText('Temp');
+		vi.mocked(mqttCatalog).mockResolvedValueOnce([
+			{ id: 'mqtt.tasmota/x', topic: 'tasmota/x', label: null, unit: null }
+		]);
+		fireEvent.click(getByText('↻ Refresh'));
+		// The label-less entry renders its topic as the name (e.label ?? e.topic).
+		const name = await findByText('tasmota/x', { selector: '.has-entity-name' });
+		expect(name).toBeTruthy();
+	});
 });
diff --git a/client/src/lib/widgets/plugins/NowPlayingSettings.test.tsx b/client/src/lib/widgets/plugins/NowPlayingSettings.test.tsx
index df39132..b7d99c3 100644
--- a/client/src/lib/widgets/plugins/NowPlayingSettings.test.tsx
+++ b/client/src/lib/widgets/plugins/NowPlayingSettings.test.tsx
@@ -1,26 +1,33 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { fireEvent, render } from '@testing-library/react';
 
-// Stub the Tauri-backed media source; resolve a known MediaCaps so the capabilities grid renders.
+// Stub the Tauri-backed media source; resolve a known MediaCaps for an active source so the
+// capabilities grid renders, and null for no source (mirrors the off-Windows / no-session case).
 vi.mock('../../components/NowPlaying/source', () => ({
 	startMediaSource: () => undefined,
-	getMediaCapabilities: () =>
-		Promise.resolve({
-			play: true,
-			pause: true,
-			playpause: true,
-			stop: false,
-			next: true,
-			previous: true,
-			shuffle: false,
-			repeat: false,
-			seek: true
-		})
+	getMediaCapabilities: vi.fn((source?: string) =>
+		Promise.resolve(
+			source
+				? {
+						play: true,
+						pause: true,
+						playpause: true,
+						stop: false,
+						next: true,
+						previous: true,
+						shuffle: false,
+						repeat: false,
+						seek: true
+				  }
+				: null
+		)
+	)
 }));
-vi.mock('../../overlay', () => ({ copyToClipboard: () => Promise.resolve(true) }));
+vi.mock('../../overlay', () => ({ copyToClipboard: vi.fn(() => Promise.resolve(true)) }));
 
 import NowPlayingSettings from './NowPlayingSettings';
 import { defaultState, mediaStore, type SessionRecord } from '../../../stores/stores';
+import { copyToClipboard } from '../../overlay';
 
 const session = (source: string, title: string): SessionRecord => ({
 	session_id: 1,
@@ -56,6 +63,7 @@ const session = (source: string, title: string): SessionRecord => ({
 });
 
 beforeEach(() => {
+	vi.clearAllMocks();
 	mediaStore.set({
 		...defaultState,
 		sourcePriority: '',
@@ -124,4 +132,101 @@ describe('NowPlayingSettings', () => {
 		const { container } = render(<NowPlayingSettings />);
 		expect(container.querySelectorAll('details.nps-raw').length).toBe(2);
 	});
+
+	it('formats a fractional scalar sensor to one decimal place', () => {
+		// position 1 / end 3 → progress 33.333… → np.progress reads "33.3" (the toFixed(1) arm).
+		const s = session('spotify.exe', 'Track');
+		const model = s.last_media_update!.Media![0]!;
+		model.timeline = { start: 0, end: 3, position: 1, last_updated_at_ms: 0 };
+		mediaStore.set({ ...defaultState, sourcePriority: '', ignoreList: '', sessions: { 1: s } });
+		const { container } = render(<NowPlayingSettings />);
+		const rows = Array.from(container.querySelectorAll('.nps-sensor'));
+		const progress = rows.find(
+			(r) => r.querySelector('.nps-sensor-id')?.textContent === 'np.progress'
+		);
+		expect(progress?.querySelector('.nps-sensor-val')?.textContent).toBe('33.3');
+	});
+
+	it('reorders the priority list by drag-and-drop', () => {
+		mediaStore.set({ ...mediaStore.getSnapshot(), sourcePriority: 'a\nb\nc' });
+		const { container } = render(<NowPlayingSettings />);
+		const rows = container.querySelectorAll('ul[aria-label="Source priority order"] li');
+		// Drag the first row (a) onto the third (c).
+		fireEvent.dragStart(rows[0]);
+		fireEvent.dragOver(rows[2]);
+		fireEvent.drop(rows[2]);
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('b\nc\na');
+	});
+
+	it('ignores a drop onto the same row (no reorder)', () => {
+		mediaStore.set({ ...mediaStore.getSnapshot(), sourcePriority: 'a\nb\nc' });
+		const { container } = render(<NowPlayingSettings />);
+		const rows = container.querySelectorAll('ul[aria-label="Source priority order"] li');
+		fireEvent.dragStart(rows[1]);
+		fireEvent.dragOver(rows[1]);
+		fireEvent.drop(rows[1]); // same index → early return, list unchanged
+		fireEvent.dragEnd(rows[1]); // clears the recorded drag origin (rows stay attached here)
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('a\nb\nc');
+	});
+
+	it('does nothing on a drop without a recorded drag origin', () => {
+		mediaStore.set({ ...mediaStore.getSnapshot(), sourcePriority: 'a\nb\nc' });
+		const { container } = render(<NowPlayingSettings />);
+		const rows = container.querySelectorAll('ul[aria-label="Source priority order"] li');
+		fireEvent.drop(rows[2]); // dragIndex.current is null → early return
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('a\nb\nc');
+	});
+
+	it('moves a priority entry down and removes one', () => {
+		mediaStore.set({ ...mediaStore.getSnapshot(), sourcePriority: 'a\nb\nc' });
+		const { getByLabelText } = render(<NowPlayingSettings />);
+		fireEvent.click(getByLabelText('Move a down'));
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('b\na\nc');
+		fireEvent.click(getByLabelText('Remove a from priority'));
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('b\nc');
+	});
+
+	it('edits the priority list as text and normalizes on blur', () => {
+		mediaStore.set({ ...mediaStore.getSnapshot(), sourcePriority: 'a' });
+		const { container } = render(<NowPlayingSettings />);
+		const priority = container.querySelectorAll('textarea')[0];
+		fireEvent.change(priority, { target: { value: 'X\nY' } });
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('X\nY'); // raw until blur
+		fireEvent.blur(priority);
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('x\ny');
+	});
+
+	it('quick-adds a detected source to the priority and ignore lists', () => {
+		mediaStore.set({ ...mediaStore.getSnapshot(), sourcePriority: '', ignoreList: '' });
+		const { getByLabelText } = render(<NowPlayingSettings />);
+		fireEvent.click(getByLabelText('Add spotify.exe to the priority list'));
+		expect(mediaStore.getSnapshot().sourcePriority).toBe('spotify.exe');
+		fireEvent.click(getByLabelText('Add spotify.exe to the ignore list'));
+		expect(mediaStore.getSnapshot().ignoreList).toContain('spotify.exe');
+	});
+
+	it('flags the now-showing source with a NOW badge', () => {
+		const { container } = render(<NowPlayingSettings />); // spotify.exe is the active session
+		const now = container.querySelector('.nps-badge-now');
+		expect(now?.textContent).toBe('NOW');
+	});
+
+	it('copies a live sensor id to the clipboard', () => {
+		const { getByLabelText } = render(<NowPlayingSettings />);
+		fireEvent.click(getByLabelText('Copy sensor id np.title'));
+		expect(copyToClipboard).toHaveBeenCalledWith('np.title');
+	});
+
+	it('shows the empty-state hint when no media source is detected', () => {
+		mediaStore.set({ ...defaultState, sourcePriority: '', ignoreList: '', sessions: {} });
+		const { getByText } = render(<NowPlayingSettings />);
+		expect(getByText(/No media sources detected yet/)).toBeTruthy();
+	});
+
+	it('shows "No active session." when nothing is playing (caps unresolved)', () => {
+		mediaStore.set({ ...defaultState, sourcePriority: '', ignoreList: '', sessions: {} });
+		const { getByText } = render(<NowPlayingSettings />);
+		// No session → getMediaCapabilities is still pending/empty in the no-session branch.
+		expect(getByText('No active session.')).toBeTruthy();
+	});
 });
diff --git a/client/src/lib/widgets/plugins/RssSettings.test.tsx b/client/src/lib/widgets/plugins/RssSettings.test.tsx
new file mode 100644
index 0000000..0860148
--- /dev/null
+++ b/client/src/lib/widgets/plugins/RssSettings.test.tsx
@@ -0,0 +1,178 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+
+// Mock the RSS Tauri command adapter so the panel runs without a backend. Each fn is a spy so we
+// can assert call args + ordering (Save must save → disconnect → connect to apply the new config
+// to the running poll task). Public feeds — nothing here is secret.
+vi.mock('./rss-commands', () => ({
+	rssConfigStatus: vi.fn(() =>
+		Promise.resolve({
+			configured: true,
+			url: 'https://example.com/feed.xml',
+			count: 12,
+			title: 'My Headlines',
+			pollSeconds: 1800
+		})
+	),
+	saveRssConfig: vi.fn(() => Promise.resolve()),
+	rssConnect: vi.fn(() => Promise.resolve()),
+	rssDisconnect: vi.fn(() => Promise.resolve())
+}));
+
+import RssSettings from './RssSettings';
+import { rssConfigStatus, rssConnect, rssDisconnect, saveRssConfig } from './rss-commands';
+import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
+import { TelemetryHubContext } from '../telemetryContext';
+
+let hub: TelemetryHub;
+
+function renderPanel() {
+	hub = createTelemetryHub();
+	return render(
+		<TelemetryHubContext.Provider value={hub}>
+			<RssSettings />
+		</TelemetryHubContext.Provider>
+	);
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	vi.mocked(rssConfigStatus).mockResolvedValue({
+		configured: true,
+		url: 'https://example.com/feed.xml',
+		count: 12,
+		title: 'My Headlines',
+		pollSeconds: 1800
+	});
+});
+
+describe('RssSettings', () => {
+	it('prefills every field from rss_config_status (pollSeconds → minutes)', async () => {
+		const { container, getByText } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://example.com/feed.xml'));
+		const texts = container.querySelectorAll('input[type="text"]');
+		expect((texts[1] as HTMLInputElement).value).toBe('My Headlines'); // title
+		const numbers = container.querySelectorAll('input[type="number"]');
+		expect((numbers[0] as HTMLInputElement).value).toBe('12'); // headline count
+		expect((numbers[1] as HTMLInputElement).value).toBe('30'); // 1800s / 60 = 30 min
+		// "configured" state reflected next to the badge.
+		expect(getByText('configured')).toBeTruthy();
+		// The live feed is started in the studio window for the badge.
+		expect(rssConnect).toHaveBeenCalled();
+	});
+
+	it('shows "not configured" when status reports it, defaulting empty/zero fields', async () => {
+		vi.mocked(rssConfigStatus).mockResolvedValueOnce({
+			configured: false,
+			url: '',
+			count: 0, // falsy → default 8
+			title: '',
+			pollSeconds: 0 // falsy → default 900 → 15 min
+		});
+		const { container, getByText } = renderPanel();
+		await waitFor(() => expect(getByText('not configured')).toBeTruthy());
+		const numbers = container.querySelectorAll('input[type="number"]');
+		expect((numbers[0] as HTMLInputElement).value).toBe('8'); // default headline count
+		expect((numbers[1] as HTMLInputElement).value).toBe('15'); // default 900s / 60
+	});
+
+	it('edits update the inputs', async () => {
+		const { container } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://example.com/feed.xml'));
+		fireEvent.change(url, { target: { value: 'https://other.test/rss' } });
+		expect(url.value).toBe('https://other.test/rss');
+		const count = container.querySelectorAll('input[type="number"]')[0] as HTMLInputElement;
+		fireEvent.change(count, { target: { value: '5' } });
+		expect(count.value).toBe('5');
+	});
+
+	it('unmounting before rss_config_status resolves does not set state (alive guard)', async () => {
+		let resolve!: (v: {
+			configured: boolean;
+			url: string;
+			count: number;
+			title: string;
+			pollSeconds: number;
+		}) => void;
+		vi.mocked(rssConfigStatus).mockReturnValueOnce(new Promise((r) => (resolve = r)));
+		const { unmount } = renderPanel();
+		unmount();
+		await act(async () => {
+			resolve({ configured: true, url: 'x', count: 1, title: 't', pollSeconds: 60 });
+		});
+		// No throw / no act warning means the !alive early-return fired.
+		expect(rssConfigStatus).toHaveBeenCalled();
+	});
+
+	it('edits to the title and refresh (minutes) inputs update them too', async () => {
+		const { container } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://example.com/feed.xml'));
+		const title = container.querySelectorAll('input[type="text"]')[1] as HTMLInputElement;
+		fireEvent.change(title, { target: { value: 'Top Stories' } });
+		expect(title.value).toBe('Top Stories');
+		const poll = container.querySelectorAll('input[type="number"]')[1] as HTMLInputElement;
+		fireEvent.change(poll, { target: { value: '20' } });
+		expect(poll.value).toBe('20');
+	});
+
+	it('flags an invalid (non-http) URL and disables Save', async () => {
+		const { container, getByText, queryByText } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://example.com/feed.xml'));
+		expect(queryByText(/Enter a full http/)).toBeNull(); // valid to start
+		fireEvent.change(url, { target: { value: 'ftp://nope' } });
+		expect(getByText(/Enter a full http/)).toBeTruthy();
+		expect(url.getAttribute('aria-invalid')).toBe('true');
+		expect((getByText('Save & fetch') as HTMLButtonElement).disabled).toBe(true);
+	});
+
+	it('saves (clamping count + minutes→seconds) then restarts in order (save → disconnect → connect)', async () => {
+		const { container, getByText } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://example.com/feed.xml'));
+		// Push count past its max (30) to prove the clamp on save.
+		const count = container.querySelectorAll('input[type="number"]')[0] as HTMLInputElement;
+		fireEvent.change(count, { target: { value: '99' } });
+		fireEvent.click(getByText('Save & fetch'));
+
+		await waitFor(() =>
+			expect(saveRssConfig).toHaveBeenCalledWith({
+				url: 'https://example.com/feed.xml',
+				count: 30, // clamped to the 1..30 range
+				title: 'My Headlines',
+				pollSeconds: 1800 // 30 min × 60
+			})
+		);
+		await waitFor(() => expect(rssDisconnect).toHaveBeenCalled());
+		// disconnect-first is mandatory so the new config replaces the running task.
+		const save = vi.mocked(saveRssConfig).mock.invocationCallOrder[0];
+		const disc = vi.mocked(rssDisconnect).mock.invocationCallOrder[0];
+		const conn = vi.mocked(rssConnect).mock.invocationCallOrder.at(-1) as number;
+		expect(save).toBeLessThan(disc);
+		expect(disc).toBeLessThan(conn);
+		expect(await waitFor(() => getByText('Saved ✓'))).toBeTruthy();
+	});
+
+	it('does not save while the URL is invalid', async () => {
+		const { container, getByText } = renderPanel();
+		const url = container.querySelector('input[type="text"]') as HTMLInputElement;
+		await waitFor(() => expect(url.value).toBe('https://example.com/feed.xml'));
+		fireEvent.change(url, { target: { value: 'not-a-url' } });
+		// The disabled button still fires onClick in jsdom/happy-dom; the guard must short-circuit.
+		fireEvent.click(getByText('Save & fetch'));
+		await waitFor(() => expect(rssConfigStatus).toHaveBeenCalled());
+		expect(saveRssConfig).not.toHaveBeenCalled();
+	});
+
+	it('reflects the live rss.status sample in the badge', async () => {
+		const { getByText } = renderPanel();
+		await waitFor(() => expect(rssConfigStatus).toHaveBeenCalled());
+		act(() => {
+			hub.ingest({ sensor: 'rss.status', ts_ms: 0, value: { kind: 'text', value: 'connected' } });
+		});
+		expect(getByText(/Connected/)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/StocksSettings.test.tsx b/client/src/lib/widgets/plugins/StocksSettings.test.tsx
new file mode 100644
index 0000000..b292aad
--- /dev/null
+++ b/client/src/lib/widgets/plugins/StocksSettings.test.tsx
@@ -0,0 +1,170 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+
+// Mock the stocks command adapter (no backend). Spies so we can assert args + the save → disconnect
+// → connect → refresh ordering. Yahoo is keyless, so nothing here is secret.
+vi.mock('./stocks-commands', () => ({
+	stocksConfigStatus: vi.fn(() =>
+		Promise.resolve({
+			configured: true,
+			provider: 'yahoo',
+			symbols: ['AAPL', 'BTC-USD'],
+			pollSeconds: 90
+		})
+	),
+	saveStocksConfig: vi.fn(() => Promise.resolve()),
+	stocksConnect: vi.fn(() => Promise.resolve()),
+	stocksDisconnect: vi.fn(() => Promise.resolve())
+}));
+// Mock the source so the bindable-id list is deterministic and refreshStocksCatalog is observable.
+vi.mock('./stocks-source', () => ({
+	refreshStocksCatalog: vi.fn(() => Promise.resolve(['AAPL', 'BTC-USD'])),
+	stocksSource: {
+		catalogEntries: vi.fn(() => [
+			{ id: 'stocks.AAPL.price', label: 'AAPL price' },
+			{ id: 'stocks.AAPL.change', label: 'AAPL change', unit: '%' }
+		])
+	}
+}));
+vi.mock('../../overlay', () => ({ copyToClipboard: vi.fn(() => Promise.resolve(true)) }));
+
+import StocksSettings from './StocksSettings';
+import {
+	saveStocksConfig,
+	stocksConfigStatus,
+	stocksConnect,
+	stocksDisconnect
+} from './stocks-commands';
+import { refreshStocksCatalog } from './stocks-source';
+import { copyToClipboard } from '../../overlay';
+import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
+import { TelemetryHubContext } from '../telemetryContext';
+
+let hub: TelemetryHub;
+
+function renderPanel() {
+	hub = createTelemetryHub();
+	return render(
+		<TelemetryHubContext.Provider value={hub}>
+			<StocksSettings />
+		</TelemetryHubContext.Provider>
+	);
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	vi.mocked(stocksConfigStatus).mockResolvedValue({
+		configured: true,
+		provider: 'yahoo',
+		symbols: ['AAPL', 'BTC-USD'],
+		pollSeconds: 90
+	});
+});
+
+describe('StocksSettings', () => {
+	it('prefills the symbol chips + poll interval from stocks_config_status', async () => {
+		const { findByLabelText, getByLabelText, container, getByText } = renderPanel();
+		// Tickers arrive as chips in the TokenListField — each chip has a unique remove button
+		// (the symbol names also appear in the help blurb, so target the chips directly).
+		expect(await findByLabelText('Remove AAPL')).toBeTruthy();
+		expect(getByLabelText('Remove BTC-USD')).toBeTruthy();
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		await waitFor(() => expect(poll.value).toBe('90'));
+		expect(getByText('configured')).toBeTruthy();
+		// The live feed is started in the studio window for the badge.
+		expect(stocksConnect).toHaveBeenCalled();
+	});
+
+	it('lists the bindable per-symbol sensor ids', async () => {
+		const { findByText, getByText } = renderPanel();
+		expect(await findByText('AAPL price')).toBeTruthy();
+		expect(getByText('stocks.AAPL.price')).toBeTruthy();
+		expect(getByText('stocks.AAPL.change')).toBeTruthy();
+	});
+
+	it('adds a ticker chip via the token field and removes it', async () => {
+		const { findByText, getByLabelText, queryByText } = renderPanel();
+		await findByText('AAPL price'); // wait for prefill (sensor list is unambiguous)
+		const add = getByLabelText('Add Tickers') as HTMLInputElement;
+		fireEvent.change(add, { target: { value: 'msft' } });
+		fireEvent.keyDown(add, { key: 'Enter' });
+		// parseSymbols upper-cases, so the chip shows MSFT.
+		expect(await findByText('MSFT')).toBeTruthy();
+		fireEvent.click(getByLabelText('Remove MSFT'));
+		expect(queryByText('MSFT')).toBeNull();
+	});
+
+	it('edits the poll interval', async () => {
+		const { container, findByText } = renderPanel();
+		await findByText('AAPL price'); // wait for prefill (sensor list is unambiguous)
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		await waitFor(() => expect(poll.value).toBe('90'));
+		fireEvent.change(poll, { target: { value: '120' } });
+		expect(poll.value).toBe('120');
+	});
+
+	it('saves the symbols + interval then restarts in order (save → disconnect → connect → refresh)', async () => {
+		const { getByText, findByText } = renderPanel();
+		await findByText('AAPL price'); // wait for prefill (sensor list is unambiguous)
+		fireEvent.click(getByText('Save & refresh'));
+
+		await waitFor(() =>
+			expect(saveStocksConfig).toHaveBeenCalledWith({
+				provider: 'yahoo',
+				symbols: ['AAPL', 'BTC-USD'],
+				pollSeconds: 90
+			})
+		);
+		await waitFor(() => expect(stocksDisconnect).toHaveBeenCalled());
+		await waitFor(() => expect(refreshStocksCatalog).toHaveBeenCalled());
+		const save = vi.mocked(saveStocksConfig).mock.invocationCallOrder[0];
+		const disc = vi.mocked(stocksDisconnect).mock.invocationCallOrder[0];
+		const conn = vi.mocked(stocksConnect).mock.invocationCallOrder.at(-1) as number;
+		const refresh = vi.mocked(refreshStocksCatalog).mock.invocationCallOrder.at(-1) as number;
+		expect(save).toBeLessThan(disc);
+		expect(disc).toBeLessThan(conn);
+		expect(conn).toBeLessThan(refresh);
+		expect(await findByText('Saved ✓')).toBeTruthy();
+	});
+
+	it('surfaces a save error instead of swallowing it', async () => {
+		vi.mocked(saveStocksConfig).mockRejectedValueOnce(new Error('disk full'));
+		const { getByText, findByText, queryByText } = renderPanel();
+		await findByText('AAPL price'); // wait for prefill (sensor list is unambiguous)
+		fireEvent.click(getByText('Save & refresh'));
+		expect(await findByText(/Couldn.t save: disk full/)).toBeTruthy();
+		expect(queryByText('Saved ✓')).toBeNull();
+	});
+
+	it('copies a bindable sensor id', async () => {
+		const { findByText, getByLabelText } = renderPanel();
+		await findByText('AAPL price');
+		fireEvent.click(getByLabelText('Copy sensor id stocks.AAPL.price'));
+		expect(copyToClipboard).toHaveBeenCalledWith('stocks.AAPL.price');
+	});
+
+	it('shows the empty-symbols hint when no tickers are configured', async () => {
+		vi.mocked(stocksConfigStatus).mockResolvedValueOnce({
+			configured: false,
+			provider: 'yahoo',
+			symbols: [],
+			pollSeconds: 60
+		});
+		const { findByText, getByText } = renderPanel();
+		expect(await findByText('not configured')).toBeTruthy();
+		expect(getByText(/No symbols yet/)).toBeTruthy();
+	});
+
+	it('reflects the live stocks.status sample in the badge', async () => {
+		const { getByText } = renderPanel();
+		await waitFor(() => expect(stocksConfigStatus).toHaveBeenCalled());
+		act(() => {
+			hub.ingest({
+				sensor: 'stocks.status',
+				ts_ms: 0,
+				value: { kind: 'text', value: 'connected' }
+			});
+		});
+		expect(getByText(/Connected/)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/WeatherSettings.test.tsx b/client/src/lib/widgets/plugins/WeatherSettings.test.tsx
new file mode 100644
index 0000000..f71f364
--- /dev/null
+++ b/client/src/lib/widgets/plugins/WeatherSettings.test.tsx
@@ -0,0 +1,167 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, waitFor } from '@testing-library/react';
+
+// Mock the weather Tauri command adapter so the panel runs without a backend. Each fn is a spy so we
+// can assert call args + ordering (Save must save → disconnect → connect). Open-Meteo is keyless, so
+// there's no secret field — the form is just location + units + refresh.
+vi.mock('./weather-commands', () => ({
+	weatherConfigStatus: vi.fn(() =>
+		Promise.resolve({
+			configured: true,
+			latitude: 51.5072,
+			longitude: -0.1276,
+			unit: 'fahrenheit',
+			pollSeconds: 1800
+		})
+	),
+	saveWeatherConfig: vi.fn(() => Promise.resolve()),
+	weatherConnect: vi.fn(() => Promise.resolve()),
+	weatherDisconnect: vi.fn(() => Promise.resolve())
+}));
+
+import WeatherSettings from './WeatherSettings';
+import {
+	saveWeatherConfig,
+	weatherConfigStatus,
+	weatherConnect,
+	weatherDisconnect
+} from './weather-commands';
+import { createTelemetryHub, type TelemetryHub } from '../../core/telemetry';
+import { TelemetryHubContext } from '../telemetryContext';
+
+let hub: TelemetryHub;
+
+function renderPanel() {
+	hub = createTelemetryHub();
+	return render(
+		<TelemetryHubContext.Provider value={hub}>
+			<WeatherSettings />
+		</TelemetryHubContext.Provider>
+	);
+}
+
+beforeEach(() => {
+	vi.clearAllMocks();
+	vi.mocked(weatherConfigStatus).mockResolvedValue({
+		configured: true,
+		latitude: 51.5072,
+		longitude: -0.1276,
+		unit: 'fahrenheit',
+		pollSeconds: 1800
+	});
+});
+
+describe('WeatherSettings', () => {
+	it('prefills the form from weather_config_status and starts the live feed', async () => {
+		const { container, getByText } = renderPanel();
+		const lat = container.querySelector('input[placeholder="51.5072"]') as HTMLInputElement;
+		const lon = container.querySelector('input[placeholder="-0.1276"]') as HTMLInputElement;
+		await waitFor(() => expect(lat.value).toBe('51.5072'));
+		expect(lon.value).toBe('-0.1276');
+		// Units mirror the loaded config; poll seconds are shown as minutes (1800s → 30min).
+		const unit = container.querySelector('select') as HTMLSelectElement;
+		expect(unit.value).toBe('fahrenheit');
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		expect(poll.value).toBe('30');
+		expect(getByText('configured')).toBeTruthy();
+		// The studio panel kicks the poll task so the badge has a live status to read.
+		expect(weatherConnect).toHaveBeenCalled();
+	});
+
+	it('shows "not configured" when the status is unconfigured', async () => {
+		vi.mocked(weatherConfigStatus).mockResolvedValue({
+			configured: false,
+			latitude: 0,
+			longitude: 0,
+			unit: 'celsius',
+			pollSeconds: 900
+		});
+		const { findByText, container } = renderPanel();
+		expect(await findByText('not configured')).toBeTruthy();
+		// Falsy lat/lon (0) round-trip to empty fields; default unit + 900s → 15min.
+		const lat = container.querySelector('input[placeholder="51.5072"]') as HTMLInputElement;
+		expect(lat.value).toBe('');
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		await waitFor(() => expect(poll.value).toBe('15'));
+	});
+
+	it('updates the latitude input as the user types', async () => {
+		const { container } = renderPanel();
+		const lat = container.querySelector('input[placeholder="51.5072"]') as HTMLInputElement;
+		await waitFor(() => expect(lat.value).toBe('51.5072'));
+		fireEvent.change(lat, { target: { value: '40.7128' } });
+		expect(lat.value).toBe('40.7128');
+	});
+
+	it('flags an out-of-range latitude and disables Save', async () => {
+		const { container, getByRole } = renderPanel();
+		const lat = container.querySelector('input[placeholder="51.5072"]') as HTMLInputElement;
+		await waitFor(() => expect(lat.value).toBe('51.5072'));
+		fireEvent.change(lat, { target: { value: '999' } });
+		expect(lat.getAttribute('aria-invalid')).toBe('true');
+		const save = getByRole('button', { name: /Save & fetch/ });
+		expect(save.hasAttribute('disabled')).toBe(true);
+		// A bad value must not reach the backend.
+		fireEvent.click(save);
+		expect(saveWeatherConfig).not.toHaveBeenCalled();
+	});
+
+	it('flags an out-of-range longitude', async () => {
+		const { container } = renderPanel();
+		const lon = container.querySelector('input[placeholder="-0.1276"]') as HTMLInputElement;
+		await waitFor(() => expect(lon.value).toBe('-0.1276'));
+		fireEvent.change(lon, { target: { value: '-500' } });
+		expect(lon.getAttribute('aria-invalid')).toBe('true');
+	});
+
+	it('saves the parsed numeric config (minutes → seconds) then restarts the task in order', async () => {
+		const { container, getByRole } = renderPanel();
+		const lat = container.querySelector('input[placeholder="51.5072"]') as HTMLInputElement;
+		await waitFor(() => expect(lat.value).toBe('51.5072'));
+		const unit = container.querySelector('select') as HTMLSelectElement;
+		fireEvent.change(unit, { target: { value: 'celsius' } });
+		const poll = container.querySelector('input[type="number"]') as HTMLInputElement;
+		fireEvent.change(poll, { target: { value: '20' } });
+
+		fireEvent.click(getByRole('button', { name: /Save & fetch/ }));
+
+		await waitFor(() =>
+			expect(saveWeatherConfig).toHaveBeenCalledWith({
+				latitude: 51.5072,
+				longitude: -0.1276,
+				unit: 'celsius',
+				pollSeconds: 1200 // 20 minutes
+			})
+		);
+		await waitFor(() => expect(weatherDisconnect).toHaveBeenCalled());
+		// Restart order: save → disconnect → connect (the running task holds the old config).
+		const save = vi.mocked(saveWeatherConfig).mock.invocationCallOrder[0];
+		const disc = vi.mocked(weatherDisconnect).mock.invocationCallOrder[0];
+		const conn = vi.mocked(weatherConnect).mock.invocationCallOrder.at(-1) as number;
+		expect(save).toBeLessThan(disc);
+		expect(disc).toBeLessThan(conn);
+	});
+
+	it('shows the "Saved ✓" confirmation after a successful save', async () => {
+		const { container, getByRole, findByText } = renderPanel();
+		const lat = container.querySelector('input[placeholder="51.5072"]') as HTMLInputElement;
+		await waitFor(() => expect(lat.value).toBe('51.5072'));
+		fireEvent.click(getByRole('button', { name: /Save & fetch/ }));
+		expect(await findByText('Saved ✓')).toBeTruthy();
+	});
+
+	it('reflects the live weather.status sample in the badge', async () => {
+		const { getByText } = renderPanel();
+		await waitFor(() => expect(weatherConfigStatus).toHaveBeenCalled());
+		// Default badge before any sample is "Not connected".
+		expect(getByText(/Not connected/)).toBeTruthy();
+		act(() => {
+			hub.ingest({
+				sensor: 'weather.status',
+				ts_ms: 0,
+				value: { kind: 'text', value: 'connected' }
+			});
+		});
+		expect(getByText(/Connected/)).toBeTruthy();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/agenda.test.ts b/client/src/lib/widgets/plugins/agenda.test.ts
new file mode 100644
index 0000000..066c0bd
--- /dev/null
+++ b/client/src/lib/widgets/plugins/agenda.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { registerAgendaPlugin } from './agenda';
+import { getMeta } from '../../core/widget';
+
+registerAgendaPlugin();
+
+describe('agenda plugin', () => {
+	it('registers the agenda widget with title / maxRows / color config', () => {
+		const meta = getMeta('agenda');
+		expect(meta).toBeTruthy();
+		const keys = (meta?.configFields ?? []).map((f) => f.key);
+		expect(keys).toEqual(expect.arrayContaining(['title', 'maxRows', 'color']));
+	});
+});
diff --git a/client/src/lib/widgets/plugins/ha-backfill.test.ts b/client/src/lib/widgets/plugins/ha-backfill.test.ts
new file mode 100644
index 0000000..9f23c65
--- /dev/null
+++ b/client/src/lib/widgets/plugins/ha-backfill.test.ts
@@ -0,0 +1,111 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createTelemetryHub } from '../../core/telemetry';
+
+// Mock the Tauri command adapter so the orchestration test stays I/O-free.
+const haHistory = vi.fn();
+vi.mock('./ha-commands', () => ({ haHistory: (...a: unknown[]) => haHistory(...a) }));
+
+import { haEntityForHistory, startHaBackfill } from './ha-backfill';
+
+// The mock is module-level (shared across tests); reset its call log so each test asserts
+// absolute call counts from a clean baseline.
+beforeEach(() => haHistory.mockReset());
+
+describe('haEntityForHistory', () => {
+	it('maps a numeric .state id to its entity_id', () => {
+		expect(haEntityForHistory('ha.sensor.temp.state')).toBe('sensor.temp');
+		expect(haEntityForHistory('ha.binary_sensor.front_door.state')).toBe(
+			'binary_sensor.front_door'
+		);
+	});
+
+	it('ignores non-history ids', () => {
+		expect(haEntityForHistory('ha.sensor.temp')).toBeNull(); // json id, no history
+		expect(haEntityForHistory('ha.status')).toBeNull(); // connection sensor (no entity dot)
+		expect(haEntityForHistory('cpu.total')).toBeNull(); // not HA
+		expect(haEntityForHistory('ha.power_state')).toBeNull(); // single-part, not <domain>.<obj>
+	});
+
+	it('does not mis-strip an entity whose object id merely ends in "state"', () => {
+		// 'ha.sensor.power_state' is a JSON id (no '.state' suffix) → ignored, not '.state' scalar
+		expect(haEntityForHistory('ha.sensor.power_state')).toBeNull();
+	});
+});
+
+describe('startHaBackfill', () => {
+	it('backfills each active HA entity once when it gains a subscriber', async () => {
+		haHistory.mockResolvedValue([]);
+		const hub = createTelemetryHub();
+		const stop = startHaBackfill(hub);
+
+		// A sparkline subscribes to a numeric HA sensor → triggers one backfill.
+		hub.sensor('ha.sensor.temp.state').subscribe(() => undefined);
+		expect(haHistory).toHaveBeenCalledTimes(1);
+		expect(haHistory.mock.calls[0][0]).toBe('sensor.temp');
+
+		// A second subscriber to the same entity does not re-fetch.
+		hub.sensor('ha.sensor.temp.state').subscribe(() => undefined);
+		expect(haHistory).toHaveBeenCalledTimes(1);
+
+		// A different entity triggers another backfill; a non-history id does not.
+		hub.sensor('ha.sensor.power.state').subscribe(() => undefined);
+		hub.sensor('ha.light.kitchen').subscribe(() => undefined);
+		expect(haHistory).toHaveBeenCalledTimes(2);
+
+		stop();
+	});
+
+	it('ingests returned samples into the hub', async () => {
+		haHistory.mockResolvedValue([
+			{ sensor: 'ha.sensor.temp.state', ts_ms: 1000, value: { kind: 'scalar', value: 21 } },
+			{ sensor: 'ha.sensor.temp.state', ts_ms: 2000, value: { kind: 'scalar', value: 22 } }
+		]);
+		const hub = createTelemetryHub();
+		startHaBackfill(hub);
+		hub.sensor('ha.sensor.temp.state').subscribe(() => undefined);
+		// let the backfill promise resolve
+		await Promise.resolve();
+		await Promise.resolve();
+		expect(hub.sensor('ha.sensor.temp.state').getSnapshot().history).toEqual([21, 22]);
+	});
+
+	it('does not ingest when the history is empty (no samples to merge)', async () => {
+		haHistory.mockResolvedValue([]);
+		const hub = createTelemetryHub();
+		const ingest = vi.spyOn(hub, 'ingestBatch');
+		startHaBackfill(hub);
+		hub.sensor('ha.sensor.temp.state').subscribe(() => undefined);
+		await Promise.resolve();
+		await Promise.resolve();
+		expect(ingest).not.toHaveBeenCalled();
+	});
+
+	it('warns and releases the claim on a failed fetch so a later tick can retry', async () => {
+		const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+		// First fetch rejects (HA blip at mount); every later fetch (the retry + other entities) is
+		// an empty success so the test produces no unhandled rejections.
+		haHistory.mockResolvedValue([]).mockRejectedValueOnce(new Error('HA blip'));
+		const hub = createTelemetryHub();
+		startHaBackfill(hub);
+
+		hub.sensor('ha.sensor.temp.state').subscribe(() => undefined);
+		expect(haHistory).toHaveBeenCalledTimes(1);
+		// Let the rejected backfill settle so the entity's claim is released.
+		await Promise.resolve();
+		await Promise.resolve();
+		expect(warn).toHaveBeenCalledWith(
+			'HA history backfill failed for',
+			'sensor.temp',
+			expect.any(Error)
+		);
+
+		// A later active-change tick (another sensor mounts) retries the still-unfilled entity.
+		hub.sensor('ha.sensor.other.state').subscribe(() => undefined);
+		expect(haHistory.mock.calls.filter((c) => c[0] === 'sensor.temp')).toHaveLength(2);
+		// Let the retry + sibling fetch settle before restoring the console spy.
+		await Promise.resolve();
+		await Promise.resolve();
+
+		warn.mockRestore();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/ha-backfill.ts b/client/src/lib/widgets/plugins/ha-backfill.ts
new file mode 100644
index 0000000..ec282f4
--- /dev/null
+++ b/client/src/lib/widgets/plugins/ha-backfill.ts
@@ -0,0 +1,59 @@
+// HA history backfill (outer-ring adapter): when a numeric HA sensor (`ha.<entity>.state`) gains a
+// live subscriber, fetch its recent history once and ingest it into THIS window's hub, so a sparkline
+// / gauge bound to an HA entity isn't blank on launch. Driven reactively off hub.onActiveChange so it
+// fires whenever a widget mounts (no startup timing race), and runs per-window (each overlay backfills
+// its own hub). The hub's order-stable ingest (core/telemetry.ts) merges the back-dated samples into
+// the right place. The pure id helper is unit-tested; the orchestration is thin I/O.
+import type { TelemetryHub } from '../../core/telemetry';
+import { haHistory } from './ha-commands';
+
+// How far back to backfill. The hub is count-windowed (caps at its historyLen) and we request
+// significant-changes-only, so a wider horizon mainly helps QUIET sensors (which change rarely) have
+// at least a few points on launch; chatty sensors stay bounded by the significant-changes filter +
+// the hub cap. A day balances "not blank for slow sensors" against payload size.
+const HISTORY_HOURS = 24;
+
+/** The HA entity_id to backfill from a hub sensor id, or null if it isn't a numeric HA history id.
+ * Only the scalar `ha.<entity>.state` id has history to fill; the json `ha.<entity>` id (and the
+ * `ha.status` connection sensor) are ignored. `ha.sensor.temp.state` → `sensor.temp`. */
+export function haEntityForHistory(sensorId: string): string | null {
+	const SUFFIX = '.state';
+	if (!sensorId.startsWith('ha.') || !sensorId.endsWith(SUFFIX)) return null;
+	const entity = sensorId.slice('ha.'.length, -SUFFIX.length);
+	// A real entity id is `<domain>.<object_id>` — must contain a dot (rejects e.g. `ha.status`).
+	return entity.includes('.') ? entity : null;
+}
+
+async function backfillOne(hub: TelemetryHub, entity: string): Promise<boolean> {
+	try {
+		const end = new Date().toISOString();
+		const start = new Date(Date.now() - HISTORY_HOURS * 3600_000).toISOString();
+		const samples = await haHistory(entity, start, end);
+		if (samples.length) hub.ingestBatch(samples);
+		return true;
+	} catch (err) {
+		console.warn('HA history backfill failed for', entity, err);
+		return false;
+	}
+}
+
+/** Start reactive HA history backfill on `hub`. Each entity is backfilled at most once on success.
+ * Returns a stop function (unsubscribes the active-change listener). */
+export function startHaBackfill(hub: TelemetryHub): () => void {
+	const done = new Set<string>();
+	const run = (): void => {
+		for (const id of hub.activeSensorIds()) {
+			const entity = haEntityForHistory(id);
+			if (!entity || done.has(entity)) continue;
+			// Claim it now so concurrent active-change ticks don't double-fetch the same entity, but
+			// release it again if the fetch failed (HA blip at mount) so a later tick can retry.
+			done.add(entity);
+			void backfillOne(hub, entity).then((ok) => {
+				if (!ok) done.delete(entity);
+			});
+		}
+	};
+	const off = hub.onActiveChange(run);
+	run(); // catch anything already subscribed
+	return off;
+}
diff --git a/client/src/lib/widgets/plugins/ha-commands.ts b/client/src/lib/widgets/plugins/ha-commands.ts
index a7f13eb..253903a 100644
--- a/client/src/lib/widgets/plugins/ha-commands.ts
+++ b/client/src/lib/widgets/plugins/ha-commands.ts
@@ -6,6 +6,7 @@
 
 import { invoke } from '@tauri-apps/api/core';
 import { COMMANDS } from '../../bridge/contract';
+import type { SensorSample } from '../../core/telemetry';
 import type { HaEntity, HaRegistry, HaStatus, HaTestResult } from './ha-types';
 
 /** Whether HA is configured + its URL + the self-signed opt-in — NEVER the token. */
@@ -48,3 +49,13 @@ export const haCallService = (
 	service: string,
 	data: Record<string, unknown>
 ): Promise<unknown> => invoke(COMMANDS.haCallService, { domain, service, data });
+
+/** Numeric history for one entity over [start, end] (ISO-8601 UTC), as `ha.<entity>.state` samples —
+ * for sparkline backfill. Returns [] when the entity has no numeric history in the window. */
+export const haHistory = (entityId: string, start: string, end: string): Promise<SensorSample[]> =>
+	invoke<SensorSample[]>(COMMANDS.haHistory, { entityId, start, end });
+
+/** Fetch an HA entity_picture (e.g. a media_player cover) and get back an art-scheme URL the webview
+ * can <img>-load — bytes are cached server-side, not shipped over the bridge. */
+export const haMediaArt = (path: string): Promise<string> =>
+	invoke<string>(COMMANDS.haMediaArt, { path });
diff --git a/client/src/lib/widgets/plugins/ha-exposed-store.test.ts b/client/src/lib/widgets/plugins/ha-exposed-store.test.ts
new file mode 100644
index 0000000..0260d1f
--- /dev/null
+++ b/client/src/lib/widgets/plugins/ha-exposed-store.test.ts
@@ -0,0 +1,51 @@
+// The HA "exposed" allowlist persistence adapter. The store is seeded once at module load by
+// parsing localStorage at the legacy key 'ha.exposed'; the pure normalize logic lives (and is
+// tested) in core/haExposed. Here we cover the adapter's own `parse` seam — both the array and
+// the non-array (corrupt / missing) branches — by seeding storage and re-importing the module so
+// its module-level createPersistedStore runs the parse, plus the write-through on update.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const KEY = 'ha.exposed';
+
+async function loadWith(raw: string | null) {
+	if (raw === null) localStorage.removeItem(KEY);
+	else localStorage.setItem(KEY, raw);
+	vi.resetModules();
+	return import('./ha-exposed-store');
+}
+
+beforeEach(() => {
+	localStorage.removeItem(KEY);
+	vi.resetModules();
+});
+
+afterEach(() => {
+	localStorage.removeItem(KEY);
+	vi.resetModules();
+});
+
+describe('haExposedStore', () => {
+	it('parses a stored string array: de-dupes, trims, drops empties, and sorts', async () => {
+		const { haExposedStore } = await loadWith(
+			JSON.stringify(['ha.light.b', '  ha.light.a  ', '', 'ha.light.b', 42, null])
+		);
+		// Non-string entries are filtered out before normalizeExposed runs.
+		expect(haExposedStore.getSnapshot()).toEqual(['ha.light.a', 'ha.light.b']);
+	});
+
+	it('falls back to an empty list when the stored value is not an array', async () => {
+		const { haExposedStore } = await loadWith(JSON.stringify({ not: 'an array' }));
+		expect(haExposedStore.getSnapshot()).toEqual([]);
+	});
+
+	it('falls back to an empty list when nothing is stored', async () => {
+		const { haExposedStore } = await loadWith(null);
+		expect(haExposedStore.getSnapshot()).toEqual([]);
+	});
+
+	it('persists updates back to the legacy key', async () => {
+		const { haExposedStore } = await loadWith(null);
+		haExposedStore.set(['ha.switch.fan']);
+		expect(JSON.parse(localStorage.getItem(KEY)!)).toEqual(['ha.switch.fan']);
+	});
+});
diff --git a/client/src/lib/widgets/plugins/ha-source.ts b/client/src/lib/widgets/plugins/ha-source.ts
index a7e561b..ab66b2b 100644
--- a/client/src/lib/widgets/plugins/ha-source.ts
+++ b/client/src/lib/widgets/plugins/ha-source.ts
@@ -11,6 +11,7 @@
 import type { SensorSource, SensorCatalogEntry } from '../../core/plugin';
 import { curate } from '../../core/haExposed';
 import { haConnect, haDisconnect, listHaEntities } from './ha-commands';
+import { startHaBackfill } from './ha-backfill';
 import type { HaEntity } from './ha-types';
 import { haExposedStore } from './ha-exposed-store';
 
@@ -43,9 +44,14 @@ export async function refreshHaCatalog(): Promise<HaEntity[]> {
 
 export const haSource: SensorSource = {
 	id: 'home-assistant',
-	start: async () => {
+	start: async (hub) => {
 		await refreshHaCatalog();
+		// Backfill recent HA history into this window's hub so sparklines bound to HA entities aren't
+		// blank on launch (reactive: fires as widgets subscribe). Order-stable ingest merges the
+		// back-dated samples — see core/telemetry.ts + plugins/ha-backfill.ts.
+		const stopBackfill = startHaBackfill(hub);
 		return () => {
+			stopBackfill();
 			haDisconnect().catch(() => undefined);
 		};
 	},
diff --git a/client/src/lib/widgets/plugins/home-assistant.test.ts b/client/src/lib/widgets/plugins/home-assistant.test.ts
new file mode 100644
index 0000000..41e5543
--- /dev/null
+++ b/client/src/lib/widgets/plugins/home-assistant.test.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it, vi } from 'vitest';
+import { registerHomeAssistantPlugin } from './home-assistant';
+import { getMeta } from '../../core/widget';
+import { listSources } from '../../core/plugin';
+import { actionHandlerFor } from '../plugin';
+import { haCallService } from './ha-commands';
+
+// Keep the real adapter shape (ha-source etc. import from here) but stub the one call we assert.
+vi.mock('./ha-commands', async (importOriginal) => ({
+	...(await importOriginal<typeof import('./ha-commands')>()),
+	haCallService: vi.fn()
+}));
+
+registerHomeAssistantPlugin();
+
+describe('home-assistant plugin', () => {
+	const types = [
+		'ha.sensor',
+		'ha.binary_sensor',
+		'ha.light',
+		'ha.switch',
+		'ha.fan',
+		'ha.climate',
+		'ha.cover',
+		'ha.lock',
+		'ha.scene',
+		'ha.input',
+		'ha.media_player'
+	];
+
+	it('registers every HA widget as json-bound under the "Home Assistant" category', () => {
+		for (const t of types) {
+			const meta = getMeta(t);
+			expect(meta, t).toBeTruthy();
+			expect(meta?.binds).toBe('json');
+			expect(meta?.category).toBe('Home Assistant');
+		}
+	});
+
+	it('marks control widgets interactive, leaves read-only sensors passive', () => {
+		expect(getMeta('ha.light')?.interactive).toBe(true);
+		expect(getMeta('ha.media_player')?.interactive).toBe(true);
+		expect(getMeta('ha.cover')?.interactive).toBe(true);
+		expect(getMeta('ha.sensor')?.interactive).toBeFalsy();
+		expect(getMeta('ha.binary_sensor')?.interactive).toBeFalsy();
+	});
+
+	it('exposes show* config toggles on controls with sub-controls', () => {
+		const keys = (t: string): string[] => (getMeta(t)?.configFields ?? []).map((f) => f.key);
+		expect(keys('ha.climate')).toEqual(expect.arrayContaining(['showMode', 'showTemp', 'showFan']));
+		expect(keys('ha.fan')).toEqual(expect.arrayContaining(['showSpeed', 'showOscillate']));
+		expect(keys('ha.cover')).toEqual(expect.arrayContaining(['showButtons', 'showPosition']));
+		expect(keys('ha.light')).toEqual(expect.arrayContaining(['showBrightness']));
+		expect(keys('ha.media_player')).toEqual(
+			expect.arrayContaining(['showTransport', 'showVolume'])
+		);
+	});
+
+	it('registers its source + a catch-all control action', () => {
+		expect(listSources().some((s) => s.id === 'home-assistant')).toBe(true);
+		// Any non-media domain (light/switch/climate/…) routes through the '*' catch-all → ha_call_service.
+		expect(actionHandlerFor('light')).toBeTruthy();
+		expect(actionHandlerFor('climate')).toBeTruthy();
+	});
+
+	it('the catch-all action resolves the entity + calls ha_call_service', async () => {
+		const dispatch = actionHandlerFor('light');
+		if (!dispatch) throw new Error('no catch-all handler');
+		vi.mocked(haCallService).mockClear();
+
+		// Bound `ha.<entity>` sensor supplies the entity when data carries none.
+		await dispatch({ domain: 'light', service: 'toggle' }, { sensor: 'ha.light.kitchen' });
+		expect(haCallService).toHaveBeenCalledWith('light', 'toggle', { entity_id: 'light.kitchen' });
+
+		// Explicit data.entity_id wins; extra data (brightness) is merged.
+		await dispatch(
+			{ domain: 'light', service: 'turn_on', data: { entity_id: 'light.x', brightness_pct: 50 } },
+			{ sensor: undefined }
+		);
+		expect(haCallService).toHaveBeenLastCalledWith('light', 'turn_on', {
+			entity_id: 'light.x',
+			brightness_pct: 50
+		});
+
+		// No entity from data or sensor → no service call.
+		vi.mocked(haCallService).mockClear();
+		await dispatch({ domain: 'light', service: 'toggle' }, { sensor: undefined });
+		expect(haCallService).not.toHaveBeenCalled();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/home-assistant.ts b/client/src/lib/widgets/plugins/home-assistant.ts
index e12e225..31de777 100644
--- a/client/src/lib/widgets/plugins/home-assistant.ts
+++ b/client/src/lib/widgets/plugins/home-assistant.ts
@@ -12,6 +12,14 @@ import HaSettings from './HaSettings';
 import HaSensor from '../meters/HaSensor';
 import HaLight from '../meters/HaLight';
 import HaClimate from '../meters/HaClimate';
+import HaSwitch from '../meters/HaSwitch';
+import HaScene from '../meters/HaScene';
+import HaFan from '../meters/HaFan';
+import HaCover from '../meters/HaCover';
+import HaLock from '../meters/HaLock';
+import HaBinarySensor from '../meters/HaBinarySensor';
+import HaInput from '../meters/HaInput';
+import HaMediaPlayerHost from './HaMediaPlayerHost';
 import { asMeter } from '../registry';
 
 // HA widgets have no defaultSensor — the entity is unknown until the user picks one from
@@ -44,41 +52,173 @@ export const registerHomeAssistantPlugin = (): void =>
 				}
 			}
 		],
+		// All grouped under a "Home Assistant" palette category. Read-only meters (sensor /
+		// binary_sensor) omit `interactive`; the control widgets set it so clicks aren't passed through
+		// the overlay. Every control just emits onControl — the `'*'` action above performs the
+		// ha_call_service, resolving the entity from the bound `ha.<entity>` sensor. The control
+		// widgets expose `show*` toggles so each sub-control (mode / fan / brightness / position …) can
+		// be turned off per widget.
 		widgets: [
 			{
 				meta: {
 					type: 'ha.sensor',
 					binds: 'json',
 					label: 'HA Sensor',
+					category: 'Home Assistant',
 					defaultSize: { w: 150, h: 44 },
 					defaultConfig: {},
 					configFields: [{ key: 'label', label: 'label', kind: 'text' }]
 				},
 				component: asMeter(HaSensor)
 			},
+			{
+				meta: {
+					type: 'ha.binary_sensor',
+					binds: 'json',
+					label: 'HA Binary Sensor',
+					category: 'Home Assistant',
+					defaultSize: { w: 150, h: 44 },
+					defaultConfig: {},
+					configFields: [{ key: 'label', label: 'label', kind: 'text' }]
+				},
+				component: asMeter(HaBinarySensor)
+			},
 			{
 				meta: {
 					type: 'ha.light',
 					binds: 'json',
 					label: 'HA Light',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 120, h: 48 },
+					defaultConfig: { showBrightness: true },
+					configFields: [
+						{ key: 'label', label: 'label', kind: 'text' },
+						{ key: 'showBrightness', label: 'brightness slider', kind: 'toggle' }
+					]
+				},
+				component: asMeter(HaLight)
+			},
+			{
+				meta: {
+					type: 'ha.switch',
+					binds: 'json',
+					label: 'HA Switch',
+					category: 'Home Assistant',
 					interactive: true,
 					defaultSize: { w: 120, h: 48 },
 					defaultConfig: {},
 					configFields: [{ key: 'label', label: 'label', kind: 'text' }]
 				},
-				component: asMeter(HaLight)
+				component: asMeter(HaSwitch)
+			},
+			{
+				meta: {
+					type: 'ha.fan',
+					binds: 'json',
+					label: 'HA Fan',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 150, h: 56 },
+					defaultConfig: { showSpeed: true, showOscillate: true },
+					configFields: [
+						{ key: 'label', label: 'label', kind: 'text' },
+						{ key: 'showSpeed', label: 'speed slider', kind: 'toggle' },
+						{ key: 'showOscillate', label: 'oscillate toggle', kind: 'toggle' }
+					]
+				},
+				component: asMeter(HaFan)
 			},
 			{
 				meta: {
 					type: 'ha.climate',
 					binds: 'json',
-					label: 'HA Climate',
+					label: 'HA Climate / A-C',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 170, h: 92 },
+					defaultConfig: { showMode: true, showTemp: true, showFan: true },
+					configFields: [
+						{ key: 'label', label: 'label', kind: 'text' },
+						{ key: 'showMode', label: 'mode toggle', kind: 'toggle' },
+						{ key: 'showTemp', label: 'temp buttons', kind: 'toggle' },
+						{ key: 'showFan', label: 'fan-mode select', kind: 'toggle' }
+					]
+				},
+				component: asMeter(HaClimate)
+			},
+			{
+				meta: {
+					type: 'ha.cover',
+					binds: 'json',
+					label: 'HA Cover',
+					category: 'Home Assistant',
 					interactive: true,
-					defaultSize: { w: 160, h: 72 },
+					defaultSize: { w: 150, h: 76 },
+					defaultConfig: { showButtons: true, showPosition: true },
+					configFields: [
+						{ key: 'label', label: 'label', kind: 'text' },
+						{ key: 'showButtons', label: 'open / close buttons', kind: 'toggle' },
+						{ key: 'showPosition', label: 'position slider', kind: 'toggle' }
+					]
+				},
+				component: asMeter(HaCover)
+			},
+			{
+				meta: {
+					type: 'ha.lock',
+					binds: 'json',
+					label: 'HA Lock',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 120, h: 48 },
 					defaultConfig: {},
 					configFields: [{ key: 'label', label: 'label', kind: 'text' }]
 				},
-				component: asMeter(HaClimate)
+				component: asMeter(HaLock)
+			},
+			{
+				meta: {
+					type: 'ha.scene',
+					binds: 'json',
+					label: 'HA Scene',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 130, h: 40 },
+					defaultConfig: {},
+					configFields: [{ key: 'label', label: 'label', kind: 'text' }]
+				},
+				component: asMeter(HaScene)
+			},
+			{
+				meta: {
+					type: 'ha.input',
+					binds: 'json',
+					label: 'HA Input',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 160, h: 48 },
+					defaultConfig: {},
+					configFields: [{ key: 'label', label: 'label', kind: 'text' }]
+				},
+				component: asMeter(HaInput)
+			},
+			{
+				meta: {
+					type: 'ha.media_player',
+					binds: 'json',
+					label: 'HA Media Player',
+					category: 'Home Assistant',
+					interactive: true,
+					defaultSize: { w: 180, h: 92 },
+					defaultConfig: { showTransport: true, showVolume: true },
+					configFields: [
+						{ key: 'label', label: 'label', kind: 'text' },
+						{ key: 'showTransport', label: 'transport buttons', kind: 'toggle' },
+						{ key: 'showVolume', label: 'volume slider', kind: 'toggle' }
+					]
+				},
+				component: asMeter(HaMediaPlayerHost)
 			}
 		]
 	});
diff --git a/client/src/lib/widgets/plugins/llm-studio.test.ts b/client/src/lib/widgets/plugins/llm-studio.test.ts
new file mode 100644
index 0000000..07749f7
--- /dev/null
+++ b/client/src/lib/widgets/plugins/llm-studio.test.ts
@@ -0,0 +1,49 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { applyLlmStudioOps, llmStudioMonitor, llmStudioReady, setLlmStudioApi } from './llm-studio';
+import type { StudioApi, StudioApplyResult } from '../plugin';
+import type { MonitorLayout } from '../../core/layoutTree';
+
+// Reset the module-level api slot between tests so each starts from "no studio mounted".
+afterEach(() => setLlmStudioApi(null));
+
+const monitor = { id: 'm', root: { kind: 'frame', children: [] } } as unknown as MonitorLayout;
+
+function fakeApi(over: Partial<StudioApi> = {}): StudioApi {
+	return {
+		monitor: () => monitor,
+		apply: (): StudioApplyResult => ({ applied: 2, addedIds: ['a', 'b'], errors: [] }),
+		...over
+	};
+}
+
+describe('llm-studio bridge', () => {
+	it('reports not-ready and degrades gracefully when no studio is mounted', () => {
+		expect(llmStudioReady()).toBe(false);
+		expect(llmStudioMonitor()).toBeNull();
+		expect(applyLlmStudioOps([])).toEqual({
+			applied: 0,
+			addedIds: [],
+			errors: ['the editor is not ready']
+		});
+	});
+
+	it('reports ready and proxies through to the stashed api once set', () => {
+		const apply = vi.fn((): StudioApplyResult => ({ applied: 1, addedIds: ['x'], errors: [] }));
+		setLlmStudioApi(fakeApi({ apply }));
+
+		expect(llmStudioReady()).toBe(true);
+		expect(llmStudioMonitor()).toBe(monitor);
+
+		const ops = [{ kind: 'noop' }] as unknown as Parameters<typeof applyLlmStudioOps>[0];
+		expect(applyLlmStudioOps(ops)).toEqual({ applied: 1, addedIds: ['x'], errors: [] });
+		expect(apply).toHaveBeenCalledWith(ops);
+	});
+
+	it('clearing the api returns to the degraded path', () => {
+		setLlmStudioApi(fakeApi());
+		expect(llmStudioReady()).toBe(true);
+		setLlmStudioApi(null);
+		expect(llmStudioReady()).toBe(false);
+		expect(llmStudioMonitor()).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/llm-tts.test.ts b/client/src/lib/widgets/plugins/llm-tts.test.ts
new file mode 100644
index 0000000..b6602f0
--- /dev/null
+++ b/client/src/lib/widgets/plugins/llm-tts.test.ts
@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock the two outer-ring deps: the provider-TTS Tauri command and the Web-Speech adapter (lib/tts).
+// The smart-fallback decision logic (provider clip → else browser voice) and the playback bookkeeping
+// (object-URL create/revoke, single in-flight clip) are what we assert.
+const llmSynthesize = vi.fn();
+const speak = vi.fn();
+const cancelSpeech = vi.fn();
+vi.mock('./llm-commands', () => ({ llmSynthesize: (t: string) => llmSynthesize(t) }));
+vi.mock('../../tts', () => ({
+	speak: (t: string) => speak(t),
+	cancelSpeech: () => cancelSpeech()
+}));
+
+import { speakSmart, stopSpeaking } from './llm-tts';
+
+// A controllable fake <audio>. play() resolves/rejects per the test; we record pause + the src URL.
+let audios: FakeAudio[] = [];
+class FakeAudio {
+	src: string;
+	onended: (() => void) | null = null;
+	onerror: (() => void) | null = null;
+	paused = false;
+	playResult: Promise<void> = Promise.resolve();
+	constructor(src: string) {
+		this.src = src;
+		audios.push(this);
+	}
+	play(): Promise<void> {
+		return this.playResult;
+	}
+	pause(): void {
+		this.paused = true;
+	}
+}
+
+const revoked: string[] = [];
+
+beforeEach(() => {
+	audios = [];
+	revoked.length = 0;
+	vi.stubGlobal('Audio', FakeAudio);
+	vi.stubGlobal(
+		'Blob',
+		class {
+			constructor(public parts: unknown[], public opts: { type?: string }) {}
+		}
+	);
+	let n = 0;
+	vi.stubGlobal('URL', {
+		createObjectURL: vi.fn(() => `blob:url-${++n}`),
+		revokeObjectURL: vi.fn((u: string) => revoked.push(u))
+	});
+});
+afterEach(() => {
+	vi.unstubAllGlobals();
+	vi.clearAllMocks();
+});
+
+describe('speakSmart', () => {
+	it('does nothing for blank text', async () => {
+		await speakSmart('   ');
+		expect(llmSynthesize).not.toHaveBeenCalled();
+		expect(speak).not.toHaveBeenCalled();
+	});
+
+	it('plays the provider clip when synthesis succeeds (no browser fallback)', async () => {
+		llmSynthesize.mockResolvedValue({ audio: [1, 2, 3], mime: 'audio/mpeg' });
+		await speakSmart('hello');
+		expect(llmSynthesize).toHaveBeenCalledWith('hello');
+		expect(cancelSpeech).toHaveBeenCalled(); // never overlap provider audio + web speech
+		expect(audios).toHaveLength(1);
+		expect(audios[0]!.src).toBe('blob:url-1');
+		expect(speak).not.toHaveBeenCalled();
+	});
+
+	it('falls back to the browser voice when synthesis is unavailable', async () => {
+		llmSynthesize.mockRejectedValue(new Error('no provider tts'));
+		await speakSmart('hi there');
+		expect(speak).toHaveBeenCalledWith('hi there');
+		expect(audios).toHaveLength(0);
+	});
+
+	it('falls back to the browser voice when playback rejects (autoplay/codec)', async () => {
+		llmSynthesize.mockResolvedValue({ audio: [9], mime: '' });
+		// Make the constructed audio reject on play().
+		const realCtor = FakeAudio;
+		vi.stubGlobal(
+			'Audio',
+			class extends realCtor {
+				constructor(src: string) {
+					super(src);
+					this.playResult = Promise.reject(new Error('autoplay blocked'));
+				}
+			}
+		);
+		await speakSmart('hi');
+		expect(speak).toHaveBeenCalledWith('hi');
+	});
+
+	it('stops the previous clip and revokes its URL when a new clip starts', async () => {
+		llmSynthesize.mockResolvedValue({ audio: [1], mime: 'audio/mpeg' });
+		await speakSmart('first');
+		await speakSmart('second'); // stopAudio() pauses #1 + revokes its url
+		expect(audios).toHaveLength(2);
+		expect(audios[0]!.paused).toBe(true);
+		expect(revoked).toContain('blob:url-1');
+	});
+
+	it('releases the clip when it ends (onended)', async () => {
+		llmSynthesize.mockResolvedValue({ audio: [1], mime: 'audio/mpeg' });
+		await speakSmart('clip');
+		const a = audios[0]!;
+		a.onended!(); // playback finished
+		expect(a.paused).toBe(true);
+		expect(revoked).toContain('blob:url-1');
+	});
+});
+
+describe('stopSpeaking', () => {
+	it('stops a playing provider clip and cancels web speech', async () => {
+		llmSynthesize.mockResolvedValue({ audio: [1], mime: 'audio/mpeg' });
+		await speakSmart('playing');
+		cancelSpeech.mockClear();
+		stopSpeaking();
+		expect(audios[0]!.paused).toBe(true);
+		expect(revoked).toContain('blob:url-1');
+		expect(cancelSpeech).toHaveBeenCalled();
+	});
+
+	it('is a safe no-op when nothing is playing', () => {
+		expect(() => stopSpeaking()).not.toThrow();
+		expect(cancelSpeech).toHaveBeenCalled();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/llm.test.ts b/client/src/lib/widgets/plugins/llm.test.ts
new file mode 100644
index 0000000..a0c948a
--- /dev/null
+++ b/client/src/lib/widgets/plugins/llm.test.ts
@@ -0,0 +1,97 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// The plugin's readiness source reads the non-secret config command, and its studio hook stashes the
+// editor api. Mock the command + the seam helpers so both can be exercised without a backend/studio.
+const llmConfigStatus = vi.fn();
+vi.mock('./llm-commands', async (importOriginal) => ({
+	...(await importOriginal<typeof import('./llm-commands')>()),
+	llmConfigStatus: (...a: unknown[]) => llmConfigStatus(...a)
+}));
+vi.mock('./llm-status', async (importOriginal) => ({
+	...(await importOriginal<typeof import('./llm-status')>()),
+	ingestLlmStatus: vi.fn()
+}));
+vi.mock('./llm-studio', async (importOriginal) => ({
+	...(await importOriginal<typeof import('./llm-studio')>()),
+	setLlmStudioApi: vi.fn()
+}));
+
+import { registerLlmPlugin } from './llm';
+import { listPlugins, type StudioApi } from '../plugin';
+import { getMeta } from '../../core/widget';
+import { createTelemetryHub } from '../../core/telemetry';
+import { ingestLlmStatus } from './llm-status';
+import { setLlmStudioApi } from './llm-studio';
+
+registerLlmPlugin();
+
+const plugin = () => {
+	const p = listPlugins().find((x) => x.id === 'ai-provider');
+	if (!p) throw new Error('ai-provider plugin not registered');
+	return p;
+};
+
+beforeEach(() => vi.clearAllMocks());
+
+describe('llm (ai-provider) plugin', () => {
+	it('registers the assistant + transcribe widgets', () => {
+		expect(getMeta('assistant')).toBeTruthy();
+		expect(getMeta('transcribe')).toBeTruthy();
+	});
+
+	it('assistant widget exposes a speak (TTS) toggle', () => {
+		const keys = (getMeta('assistant')?.configFields ?? []).map((f) => f.key);
+		expect(keys).toContain('speak');
+	});
+
+	it('declares the llm.status sensor as the plugins-list status dot', () => {
+		expect(plugin().statusSensor).toBe('llm.status');
+	});
+
+	describe('the llm.status readiness source', () => {
+		const source = () => {
+			const s = plugin().sources?.find((x) => x.id === 'ai-provider');
+			if (!s) throw new Error('ai-provider source not registered');
+			return s;
+		};
+
+		it('catalogs the llm.status sensor', () => {
+			expect(source().catalog?.()).toEqual(['llm.status']);
+			expect(source().catalogEntries?.()).toEqual([
+				{ id: 'llm.status', label: 'AI provider status' }
+			]);
+		});
+
+		it('ingests one readiness sample at start from the config command', async () => {
+			const status = { configured: true, active: 'openai', providers: {} };
+			llmConfigStatus.mockResolvedValue(status);
+			const hub = createTelemetryHub();
+			const stop = await source().start(hub);
+			expect(ingestLlmStatus).toHaveBeenCalledWith(hub, status);
+			// The returned stop fn is a no-op (the dot is event-driven, not a live listener).
+			expect(stop()).toBeUndefined();
+		});
+
+		it('stays silent when the command is unavailable (no backend)', async () => {
+			llmConfigStatus.mockRejectedValue(new Error('no backend'));
+			const hub = createTelemetryHub();
+			const stop = await source().start(hub);
+			expect(ingestLlmStatus).not.toHaveBeenCalled();
+			expect(stop()).toBeUndefined();
+		});
+	});
+
+	describe('the studio capability', () => {
+		it('stashes the editor api on mount and drops it on cleanup', () => {
+			const api = { monitor: vi.fn(), apply: vi.fn() } as unknown as StudioApi;
+			const studio = plugin().studio;
+			if (!studio) throw new Error('no studio hook');
+			const cleanup = studio(api);
+			expect(setLlmStudioApi).toHaveBeenCalledWith(api);
+
+			if (typeof cleanup !== 'function') throw new Error('studio hook returns no cleanup');
+			cleanup();
+			expect(setLlmStudioApi).toHaveBeenLastCalledWith(null);
+		});
+	});
+});
diff --git a/client/src/lib/widgets/plugins/mqtt.test.ts b/client/src/lib/widgets/plugins/mqtt.test.ts
new file mode 100644
index 0000000..08890e3
--- /dev/null
+++ b/client/src/lib/widgets/plugins/mqtt.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+import { registerMqttPlugin } from './mqtt';
+import { listSources } from '../../core/plugin';
+
+registerMqttPlugin();
+
+describe('mqtt plugin', () => {
+	it('registers the mqtt sensor source (source + settings only, no widget)', () => {
+		expect(listSources().some((s) => s.id === 'mqtt')).toBe(true);
+	});
+});
diff --git a/client/src/lib/widgets/plugins/now-playing.test.tsx b/client/src/lib/widgets/plugins/now-playing.test.tsx
index b7ccb9e..712aa18 100644
--- a/client/src/lib/widgets/plugins/now-playing.test.tsx
+++ b/client/src/lib/widgets/plugins/now-playing.test.tsx
@@ -1,15 +1,16 @@
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 // startMediaSource()/getMediaCapabilities()/mediaControl() call Tauri (no runtime in tests) — stub
-// the module.
+// the module. mediaControl is a spy so the `media` control-action handler can be asserted.
 vi.mock('../../components/NowPlaying/source', () => ({
 	startMediaSource: () => undefined,
 	getMediaCapabilities: () => Promise.resolve(null),
-	mediaControl: () => Promise.resolve()
+	mediaControl: vi.fn(() => Promise.resolve())
 }));
 vi.mock('../../overlay', () => ({ copyToClipboard: () => Promise.resolve(true) }));
 
 import { registerNowPlayingPlugin } from './now-playing';
+import { mediaControl } from '../../components/NowPlaying/source';
 import { listPlugins } from '../plugin';
 import { sourceCatalogIds } from '../../core/plugin';
 import { configCompleteness, createWidget, getMeta } from '../../core/widget';
@@ -17,6 +18,14 @@ import { configCompleteness, createWidget, getMeta } from '../../core/widget';
 // Registers the plugin + the nowplaying widget meta + the np source (was an import side-effect).
 registerNowPlayingPlugin();
 
+const nowPlaying = () => {
+	const p = listPlugins().find((x) => x.id === 'now-playing');
+	if (!p) throw new Error('now-playing plugin not registered');
+	return p;
+};
+
+beforeEach(() => vi.clearAllMocks());
+
 describe('now-playing plugin', () => {
 	it('registers as a plugin with a settings panel + a media source', () => {
 		const p = listPlugins().find((x) => x.id === 'now-playing');
@@ -40,4 +49,22 @@ describe('now-playing plugin', () => {
 			expect.arrayContaining(['np.title', 'np.artist', 'np.progress', 'np.status'])
 		);
 	});
+
+	describe('the media control-action handler', () => {
+		const dispatch = () => {
+			const a = nowPlaying().actions?.find((x) => x.domain === 'media');
+			if (!a) throw new Error('no media action handler');
+			return a.dispatch;
+		};
+
+		it('routes a transport bang to the backend media controller with source + value', () => {
+			dispatch()({ domain: 'media', service: 'seek', data: { source: 'spotify', value: 42 } }, {});
+			expect(mediaControl).toHaveBeenCalledWith('seek', 'spotify', 42);
+		});
+
+		it('defaults missing source/value to null', () => {
+			dispatch()({ domain: 'media', service: 'next' }, {});
+			expect(mediaControl).toHaveBeenCalledWith('next', null, null);
+		});
+	});
 });
diff --git a/client/src/lib/widgets/plugins/packages.test.ts b/client/src/lib/widgets/plugins/packages.test.ts
new file mode 100644
index 0000000..b8a9deb
--- /dev/null
+++ b/client/src/lib/widgets/plugins/packages.test.ts
@@ -0,0 +1,715 @@
+// The plugin-PACKAGE orchestration (install/list/remove/manifest apply, toggle + consent gating,
+// remote install/update/remove). The pure parse/validate lives in core/pluginPackage.ts and is
+// tested there; this suite drives the ADAPTER half: discovery → rows, the enabled allowlist, the
+// CSS/network consent gates, the template-group + sensor-catalog + theme-style side effects, and
+// the {ok,error?} result branches of the remote ops. The two IO modules (the Tauri command adapter
+// and the QuickJS poll-loop starter) are mocked so every branch runs without a backend.
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ---- IO mocks ------------------------------------------------------------------------------------
+// packages-commands is the only Tauri seam; we drive its read commands from in-memory fixtures and
+// can make the remote (throwing) commands resolve or reject per test.
+type PkgFile = { id: string; manifest: string; install: string | null };
+let listFiles: PkgFile[] = [];
+const assets = new Map<string, string>(); // keyed by `${id}/${name}`
+let installImpl: (source: string) => Promise<{ id: string; version: string }>;
+let checkImpl: (id: string) => Promise<{ current: string; latest: string; source: string }>;
+let removeImpl: (id: string) => Promise<void>;
+const installCalls: string[] = [];
+const removeCalls: string[] = [];
+
+vi.mock('./packages-commands', () => ({
+	listPluginPackages: () => Promise.resolve(listFiles),
+	readPluginPackageAsset: (id: string, name: string) =>
+		Promise.resolve(assets.get(`${id}/${name}`) ?? null),
+	installPluginPackage: (source: string) => {
+		installCalls.push(source);
+		return installImpl(source);
+	},
+	checkPluginPackageUpdate: (id: string) => checkImpl(id),
+	removePluginPackage: (id: string) => {
+		removeCalls.push(id);
+		return removeImpl(id);
+	}
+}));
+
+// packages-source is the poll-loop starter; we record starts + hand back a recording stop fn so we
+// can assert the consent-gated lifecycle (started only on enable + matching net consent, stopped on
+// disable/remove) without the real QuickJS sandbox.
+const sourceStarts: string[] = [];
+const sourceStops: string[] = [];
+vi.mock('./packages-source', () => ({
+	startPackageSource: (m: { id: string }) => {
+		sourceStarts.push(m.id);
+		return Promise.resolve(() => {
+			sourceStops.push(m.id);
+		});
+	}
+}));
+
+import { createTelemetryHub } from '../../core/telemetry';
+import { listTemplateGroups } from '../../core/templates';
+import { listSources, sourceCatalogEntries } from '../../core/plugin';
+import {
+	checkPackageUpdate,
+	enabledPackages,
+	initPackages,
+	installPackage,
+	packagesStore,
+	refreshPackages,
+	removePackage,
+	resetPackagesForTest,
+	togglePackage,
+	updatePackage,
+	type PackageRow
+} from './packages';
+
+// ---- manifest fixtures ---------------------------------------------------------------------------
+
+// A minimal structurally-valid layout node (a clock leaf) the template whitelist accepts.
+const leafNode = (id = 'w1') => ({
+	id,
+	unit: { id, type: 'clock', rect: { x: 0, y: 0, w: 160, h: 40 }, config: { format: 'HH:mm' } }
+});
+
+const template = (id: string) => ({
+	id,
+	name: `Tpl ${id}`,
+	size: { w: 100, h: 40 },
+	tree: leafNode(id)
+});
+
+const manifestJson = (over: Record<string, unknown> = {}): string =>
+	JSON.stringify({
+		manifestVersion: 1,
+		id: 'pack-a',
+		name: 'Pack A',
+		version: '1.0.0',
+		templates: [template('t1')],
+		...over
+	});
+
+const sidecarJson = (over: Record<string, unknown> = {}): string =>
+	JSON.stringify({
+		source: 'owner/repo',
+		ref: 'main',
+		version: '1.0.0',
+		installedAt: 1000,
+		...over
+	});
+
+// Register a single package on disk (and optionally its assets), then re-scan.
+function setFiles(files: PkgFile[]): void {
+	listFiles = files;
+}
+
+const rowFor = (id: string): PackageRow | undefined =>
+	packagesStore.getSnapshot().find((r) => r.id === id);
+
+const styleTagFor = (id: string): Element | null =>
+	document.querySelector(`style[data-pkg-theme="${id}"]`);
+
+const hub = createTelemetryHub();
+
+beforeEach(() => {
+	resetPackagesForTest();
+	listFiles = [];
+	assets.clear();
+	installCalls.length = 0;
+	removeCalls.length = 0;
+	sourceStarts.length = 0;
+	sourceStops.length = 0;
+	installImpl = () => Promise.resolve({ id: 'pack-a', version: '1.0.0' });
+	checkImpl = () => Promise.resolve({ current: '1.0.0', latest: '1.0.0', source: 'owner/repo' });
+	removeImpl = () => Promise.resolve();
+	// A clean head: strip any package theme tags a prior test left.
+	document.querySelectorAll('style[data-pkg-theme]').forEach((el) => el.remove());
+});
+
+afterEach(() => {
+	resetPackagesForTest();
+});
+
+// ---- discovery → rows ----------------------------------------------------------------------------
+
+describe('refreshPackages → packagesStore rows', () => {
+	it('publishes a row per discovered manifest with parsed metadata', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({ description: 'desc', version: '2.3.4' }),
+				install: null
+			}
+		]);
+		await refreshPackages();
+
+		const row = rowFor('pack-a')!;
+		expect(row.name).toBe('Pack A');
+		expect(row.version).toBe('2.3.4');
+		expect(row.description).toBe('desc');
+		expect(row.error).toBeNull();
+		expect(row.warnings).toEqual([]);
+		expect(row.templates).toBe(1);
+		expect(row.themeName).toBeNull();
+		expect(row.sensors).toBe(0);
+		expect(row.hosts).toEqual([]);
+		expect(row.installedFrom).toBeNull();
+		expect(row.installedVersion).toBeUndefined();
+	});
+
+	it('rows an unparsed manifest as an error (folder id as name, no toggle metadata)', async () => {
+		setFiles([{ id: 'pack-a', manifest: '{not json', install: null }]);
+		await refreshPackages();
+
+		const row = rowFor('pack-a')!;
+		expect(row.error).toContain('not valid JSON');
+		expect(row.name).toBe('pack-a'); // falls back to the bare folder id
+		expect(row.version).toBe('');
+		expect(row.templates).toBe(0);
+	});
+
+	it('carries dropped-template warnings onto the row but still loads the package', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					templates: [
+						{ id: 'bad', name: 'Bad', size: { w: 1, h: 1 }, tree: { not: 'a node' } },
+						template('good')
+					]
+				}),
+				install: null
+			}
+		]);
+		await refreshPackages();
+
+		const row = rowFor('pack-a')!;
+		expect(row.error).toBeNull();
+		expect(row.templates).toBe(1); // only the good one
+		expect(row.warnings.join(' ')).toContain('"bad" dropped');
+	});
+
+	it('surfaces theme/source/host metadata from the manifest', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					theme: { name: 'Midnight', file: 'theme.css' },
+					source: { file: 'src.js', pollSeconds: 30, hosts: ['api.example.com'] },
+					sensors: [{ id: 'temp', label: 'Temp' }]
+				}),
+				install: null
+			}
+		]);
+		await refreshPackages();
+
+		const row = rowFor('pack-a')!;
+		expect(row.themeName).toBe('Midnight');
+		expect(row.sensors).toBe(1);
+		expect(row.hosts).toEqual(['api.example.com']);
+	});
+
+	it('reads provenance from a valid install sidecar', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson(),
+				install: sidecarJson({ source: 'gh/owner', version: '0.9.0' })
+			}
+		]);
+		await refreshPackages();
+
+		const row = rowFor('pack-a')!;
+		expect(row.installedFrom).toBe('gh/owner');
+		expect(row.installedVersion).toBe('0.9.0');
+	});
+
+	it('treats a malformed sidecar as a hand-dropped (local) package', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: '{bad sidecar' }]);
+		await refreshPackages();
+
+		const row = rowFor('pack-a')!;
+		expect(row.installedFrom).toBeNull();
+		expect(row.installedVersion).toBeUndefined();
+	});
+
+	it('drops rows for packages that vanished from disk on the next scan', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: null }]);
+		await refreshPackages();
+		expect(rowFor('pack-a')).toBeDefined();
+
+		setFiles([]);
+		await refreshPackages();
+		expect(packagesStore.getSnapshot()).toEqual([]);
+	});
+});
+
+// ---- initPackages (one-shot) ---------------------------------------------------------------------
+
+describe('initPackages', () => {
+	it('discovers on first call and is idempotent on subsequent calls', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: null }]);
+		await initPackages(hub);
+		expect(rowFor('pack-a')).toBeDefined();
+
+		// A second init must NOT re-scan: change disk, re-init, rows stay as-was.
+		setFiles([{ id: 'pack-b', manifest: manifestJson({ id: 'pack-b' }), install: null }]);
+		await initPackages(hub);
+		expect(rowFor('pack-b')).toBeUndefined();
+		expect(rowFor('pack-a')).toBeDefined();
+	});
+});
+
+// ---- togglePackage: enable side effects ----------------------------------------------------------
+
+describe('togglePackage — enabling a plain package', () => {
+	beforeEach(async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: null }]);
+		await initPackages(hub);
+	});
+
+	it('registers the template group and records the id in the enabled allowlist', async () => {
+		await togglePackage('pack-a', true);
+
+		expect(enabledPackages.getSnapshot()).toContain('pack-a');
+		const group = listTemplateGroups().find((g) => g.group === 'Pack A');
+		expect(group?.templates).toHaveLength(1);
+	});
+
+	it('unregisters the group and drops the id when disabled', async () => {
+		await togglePackage('pack-a', true);
+		await togglePackage('pack-a', false);
+
+		expect(enabledPackages.getSnapshot()).not.toContain('pack-a');
+		expect(listTemplateGroups().find((g) => g.group === 'Pack A')).toBeUndefined();
+	});
+
+	it('does nothing for an unknown or unparsed package id', async () => {
+		await togglePackage('nope', true);
+		expect(enabledPackages.getSnapshot()).toEqual([]);
+	});
+});
+
+// ---- togglePackage: CSS consent gate -------------------------------------------------------------
+
+describe('togglePackage — theme CSS consent', () => {
+	const REMOTE_CSS = 'body { background: url(https://evil.example.com/pixel.png); }';
+
+	beforeEach(async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({ theme: { name: 'T', file: 'theme.css' } }),
+				install: null
+			}
+		]);
+		assets.set('pack-a/theme.css', REMOTE_CSS);
+		await initPackages(hub);
+	});
+
+	it('injects a benign theme style without prompting', async () => {
+		assets.set('pack-a/theme.css', 'body { color: red; }');
+		const confirm = vi.fn(() => true);
+		await togglePackage('pack-a', true, confirm);
+
+		expect(confirm).not.toHaveBeenCalled();
+		expect(styleTagFor('pack-a')?.textContent).toBe('body { color: red; }');
+	});
+
+	it('prompts once for a threat-flagged theme and injects after accept', async () => {
+		const confirm = vi.fn<(message: string) => boolean>(() => true);
+		await togglePackage('pack-a', true, confirm);
+
+		expect(confirm).toHaveBeenCalledTimes(1);
+		expect(confirm.mock.calls[0]![0]).toContain('remote resource');
+		expect(styleTagFor('pack-a')).not.toBeNull();
+		expect(enabledPackages.getSnapshot()).toContain('pack-a');
+	});
+
+	it('aborts the enable (no allowlist, no style) when the prompt is declined', async () => {
+		const confirm = vi.fn(() => false);
+		await togglePackage('pack-a', true, confirm);
+
+		expect(enabledPackages.getSnapshot()).not.toContain('pack-a');
+		expect(styleTagFor('pack-a')).toBeNull();
+	});
+
+	it('remembers CSS consent — re-enabling the same package does not re-prompt', async () => {
+		await togglePackage('pack-a', true, () => true);
+		await togglePackage('pack-a', false);
+
+		const confirm = vi.fn(() => true);
+		await togglePackage('pack-a', true, confirm);
+		expect(confirm).not.toHaveBeenCalled(); // consent already stored
+		expect(styleTagFor('pack-a')).not.toBeNull();
+	});
+
+	it('removes the theme style tag on disable', async () => {
+		await togglePackage('pack-a', true, () => true);
+		expect(styleTagFor('pack-a')).not.toBeNull();
+		await togglePackage('pack-a', false);
+		expect(styleTagFor('pack-a')).toBeNull();
+	});
+});
+
+// ---- togglePackage: network source consent + lifecycle -------------------------------------------
+
+describe('togglePackage — network source consent', () => {
+	beforeEach(async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					source: { file: 'src.js', pollSeconds: 30, hosts: ['api.example.com'] },
+					sensors: [{ id: 'temp', label: 'Temp' }]
+				}),
+				install: null
+			}
+		]);
+		await initPackages(hub);
+	});
+
+	it('registers catalog entries and starts the poll loop after net consent', async () => {
+		const confirm = vi.fn<(message: string) => boolean>(() => true);
+		await togglePackage('pack-a', true, confirm);
+
+		expect(confirm).toHaveBeenCalledTimes(1);
+		expect(confirm.mock.calls[0]![0]).toContain('polls the network');
+		// The declared sensor + the implicit status sensor are now in the live catalog.
+		const ids = sourceCatalogEntries().map((e) => e.id);
+		expect(ids).toContain('pkg.pack-a.temp');
+		expect(ids).toContain('pkg.pack-a.status');
+		expect(sourceStarts).toContain('pack-a');
+	});
+
+	it('does not start the loop when the net prompt is declined', async () => {
+		await togglePackage('pack-a', true, () => false);
+		expect(enabledPackages.getSnapshot()).not.toContain('pack-a');
+		expect(sourceStarts).toEqual([]);
+	});
+
+	it('stops the loop and unregisters the source on disable', async () => {
+		await togglePackage('pack-a', true, () => true);
+		expect(sourceStarts).toEqual(['pack-a']);
+		await togglePackage('pack-a', false);
+		expect(sourceStops).toContain('pack-a');
+		expect(sourceCatalogEntries().map((e) => e.id)).not.toContain('pkg.pack-a.temp');
+	});
+
+	it('re-applies an enabled source on refresh without stacking two loops', async () => {
+		await togglePackage('pack-a', true, () => true);
+		sourceStarts.length = 0;
+		sourceStops.length = 0;
+		await refreshPackages();
+		// applyPackage stops any prior loop, then starts the fresh one exactly once.
+		expect(sourceStarts).toEqual(['pack-a']);
+		expect(sourceStops).toEqual(['pack-a']);
+	});
+
+	it('auto-approves via the default confirm when no callback is passed', async () => {
+		// Omitting confirmEnable uses the default `() => true`, so the consent gate auto-approves.
+		await togglePackage('pack-a', true);
+		expect(enabledPackages.getSnapshot()).toContain('pack-a');
+		expect(sourceStarts).toContain('pack-a');
+	});
+
+	it('registers an inert no-op start for the pkg source (lifecycle is owned here, not startAllSources)', async () => {
+		await togglePackage('pack-a', true, () => true);
+		const src = listSources().find((s) => s.id === 'pkg:pack-a')!;
+		expect(src).toBeDefined();
+		// The registered start is deliberately a no-op: invoking it just yields a no-op stop fn.
+		const stop = await src.start(hub);
+		expect(typeof stop).toBe('function');
+		expect(stop()).toBeUndefined();
+	});
+});
+
+// ---- installPackage ------------------------------------------------------------------------------
+
+describe('installPackage', () => {
+	it('installs then re-scans, returning ok (fresh install lands disabled)', async () => {
+		installImpl = (source) => {
+			expect(source).toBe('owner/repo');
+			setFiles([{ id: 'pack-a', manifest: manifestJson(), install: sidecarJson() }]);
+			return Promise.resolve({ id: 'pack-a', version: '1.0.0' });
+		};
+		const r = await installPackage('owner/repo');
+
+		expect(r).toEqual({ ok: true });
+		expect(rowFor('pack-a')).toBeDefined();
+		expect(enabledPackages.getSnapshot()).toEqual([]); // opt-in: untouched
+	});
+
+	it('returns the backend error string on failure', async () => {
+		installImpl = () => Promise.reject(new Error('network down'));
+		const r = await installPackage('owner/repo');
+
+		expect(r.ok).toBe(false);
+		expect(r.error).toContain('network down');
+	});
+});
+
+// ---- checkPackageUpdate --------------------------------------------------------------------------
+
+describe('checkPackageUpdate', () => {
+	it('reports updateAvailable=false when versions match', async () => {
+		checkImpl = () => Promise.resolve({ current: '1.0.0', latest: '1.0.0', source: 'owner/repo' });
+		const r = await checkPackageUpdate('pack-a');
+
+		expect(r).toEqual({
+			ok: true,
+			current: '1.0.0',
+			latest: '1.0.0',
+			updateAvailable: false
+		});
+	});
+
+	it('reports updateAvailable=true when the version strings differ', async () => {
+		checkImpl = () => Promise.resolve({ current: '1.0.0', latest: '1.1.0', source: 'owner/repo' });
+		const r = await checkPackageUpdate('pack-a');
+
+		expect(r.ok).toBe(true);
+		if (r.ok) expect(r.updateAvailable).toBe(true);
+	});
+
+	it('returns an error result when the check throws', async () => {
+		checkImpl = () => Promise.reject(new Error('no sidecar'));
+		const r = await checkPackageUpdate('pack-a');
+
+		expect(r.ok).toBe(false);
+		if (!r.ok) expect(r.error).toContain('no sidecar');
+	});
+});
+
+// ---- updatePackage -------------------------------------------------------------------------------
+
+describe('updatePackage', () => {
+	it('refuses a hand-dropped (no-sidecar) package', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: null }]);
+		await initPackages(hub);
+
+		const r = await updatePackage('pack-a');
+		expect(r.ok).toBe(false);
+		expect(r.error).toContain('not installed from a URL');
+		expect(installCalls).toEqual([]);
+	});
+
+	it('re-installs from the recorded source and re-scans on success', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: sidecarJson() }]);
+		await initPackages(hub);
+
+		const r = await updatePackage('pack-a');
+		expect(r).toEqual({ ok: true });
+		// ref 'main' round-trips as the bare source string.
+		expect(installCalls).toEqual(['owner/repo']);
+	});
+
+	it('feeds reinstallSource a pinned-ref URL', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: sidecarJson({ ref: 'v2' }) }]);
+		await initPackages(hub);
+
+		await updatePackage('pack-a');
+		expect(installCalls).toEqual(['https://github.com/owner/repo/tree/v2']);
+	});
+
+	it('restores the old registration and returns an error when the re-install fails', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: sidecarJson() }]);
+		await initPackages(hub);
+		await togglePackage('pack-a', true);
+		expect(listTemplateGroups().find((g) => g.group === 'Pack A')).toBeDefined();
+
+		installImpl = () => Promise.reject(new Error('boom'));
+		const r = await updatePackage('pack-a');
+		expect(r.ok).toBe(false);
+		if (!r.ok) expect(r.error).toContain('boom');
+		// The closing refresh restored the still-enabled old version's group.
+		expect(listTemplateGroups().find((g) => g.group === 'Pack A')).toBeDefined();
+	});
+
+	it('drops stale network consent when the update changes the hosts list', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					source: { file: 'src.js', pollSeconds: 30, hosts: ['api.example.com'] },
+					sensors: [{ id: 'temp' }]
+				}),
+				install: sidecarJson()
+			}
+		]);
+		await initPackages(hub);
+		await togglePackage('pack-a', true, () => true); // consent for api.example.com
+		expect(sourceStarts).toContain('pack-a');
+
+		// The update ships a manifest with a DIFFERENT host — the install writes it to disk.
+		installImpl = () => {
+			setFiles([
+				{
+					id: 'pack-a',
+					manifest: manifestJson({
+						source: { file: 'src.js', pollSeconds: 30, hosts: ['other.example.com'] },
+						sensors: [{ id: 'temp' }]
+					}),
+					install: sidecarJson({ version: '2.0.0' })
+				}
+			]);
+			return Promise.resolve({ id: 'pack-a', version: '2.0.0' });
+		};
+		sourceStarts.length = 0;
+		await updatePackage('pack-a');
+
+		// Stale consent dropped → the new host's loop stays OFF until re-confirmed.
+		expect(sourceStarts).toEqual([]);
+		// Re-enabling now re-prompts (consent was cleared).
+		const confirm = vi.fn(() => true);
+		await togglePackage('pack-a', false);
+		await togglePackage('pack-a', true, confirm);
+		expect(confirm).toHaveBeenCalledTimes(1);
+	});
+});
+
+// ---- removePackage -------------------------------------------------------------------------------
+
+describe('removePackage', () => {
+	it('clears the enable + consent allowlists, deletes, and re-scans on success', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({ theme: { name: 'T', file: 'theme.css' } }),
+				install: null
+			}
+		]);
+		assets.set('pack-a/theme.css', 'body { color: red; }');
+		await initPackages(hub);
+		await togglePackage('pack-a', true);
+		expect(enabledPackages.getSnapshot()).toContain('pack-a');
+
+		removeImpl = (id) => {
+			expect(id).toBe('pack-a');
+			setFiles([]); // the folder is gone after delete
+			return Promise.resolve();
+		};
+		const r = await removePackage('pack-a');
+
+		expect(r).toEqual({ ok: true });
+		expect(removeCalls).toEqual(['pack-a']);
+		expect(enabledPackages.getSnapshot()).not.toContain('pack-a');
+		expect(rowFor('pack-a')).toBeUndefined();
+		expect(styleTagFor('pack-a')).toBeNull();
+	});
+
+	it('clears stored network consent on remove', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					source: { file: 'src.js', pollSeconds: 30, hosts: ['api.example.com'] },
+					sensors: [{ id: 'temp' }]
+				}),
+				install: null
+			}
+		]);
+		await initPackages(hub);
+		await togglePackage('pack-a', true, () => true); // stores net consent + starts the loop
+
+		removeImpl = () => {
+			setFiles([]);
+			return Promise.resolve();
+		};
+		const r = await removePackage('pack-a');
+		expect(r).toEqual({ ok: true });
+		expect(sourceStops).toContain('pack-a'); // loop stopped on remove
+
+		// Re-discovering the same package and re-enabling must re-prompt — consent was cleared.
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					source: { file: 'src.js', pollSeconds: 30, hosts: ['api.example.com'] },
+					sensors: [{ id: 'temp' }]
+				}),
+				install: null
+			}
+		]);
+		await refreshPackages();
+		const confirm = vi.fn(() => true);
+		await togglePackage('pack-a', true, confirm);
+		expect(confirm).toHaveBeenCalledTimes(1);
+	});
+
+	it('returns an error and re-scans (restoring the row) when the delete fails', async () => {
+		setFiles([{ id: 'pack-a', manifest: manifestJson(), install: null }]);
+		await initPackages(hub);
+
+		removeImpl = () => Promise.reject(new Error('locked'));
+		const r = await removePackage('pack-a');
+
+		expect(r.ok).toBe(false);
+		if (!r.ok) expect(r.error).toContain('locked');
+		// The closing refresh re-discovered the still-present folder.
+		expect(rowFor('pack-a')).toBeDefined();
+	});
+});
+
+// ---- resetPackagesForTest ------------------------------------------------------------------------
+
+describe('resetPackagesForTest', () => {
+	it('clears rows, the enabled allowlist, and any registered groups/styles', async () => {
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({ theme: { name: 'T', file: 'theme.css' } }),
+				install: null
+			}
+		]);
+		assets.set('pack-a/theme.css', 'body { color: red; }');
+		await initPackages(hub);
+		await togglePackage('pack-a', true);
+
+		resetPackagesForTest();
+
+		expect(packagesStore.getSnapshot()).toEqual([]);
+		expect(enabledPackages.getSnapshot()).toEqual([]);
+		expect(listTemplateGroups().find((g) => g.group === 'Pack A')).toBeUndefined();
+		expect(styleTagFor('pack-a')).toBeNull();
+	});
+});
+
+// ---- netConsent store parse (parseConsentMap) ----------------------------------------------------
+// The network-consent map is parsed once at module load from localStorage. Seed a populated map
+// (with a non-string entry to prove the typeof filter) and re-import the module so the parse runs
+// its object-iteration path; the loaded consent must then let an enable skip the net prompt.
+
+describe('netConsent persisted map parsing', () => {
+	it('loads a stored consent map (string values only) so a matching enable does not re-prompt', async () => {
+		// fingerprint of ['api.example.com'] is the sorted-join → the host itself. The `dropped: 123`
+		// entry proves parseConsentMap's `typeof v === 'string'` filter skips non-string values.
+		localStorage.setItem(
+			'widgetsack.packages.netConsent',
+			JSON.stringify({ 'pack-a': 'api.example.com', dropped: 123 })
+		);
+		// Fresh module instance: its module-level createPersistedStore(..., parseConsentMap) parses
+		// the seeded map (the object-iteration path). DON'T resetPackagesForTest — that clears it.
+		vi.resetModules();
+		const m = await import('./packages');
+		setFiles([
+			{
+				id: 'pack-a',
+				manifest: manifestJson({
+					source: { file: 'src.js', pollSeconds: 30, hosts: ['api.example.com'] },
+					sensors: [{ id: 'temp', label: 'Temp' }]
+				}),
+				install: null
+			}
+		]);
+		await m.initPackages(createTelemetryHub());
+		const confirm = vi.fn(() => true);
+		await m.togglePackage('pack-a', true, confirm);
+		// Consent for these exact hosts was already loaded from storage → no prompt.
+		expect(confirm).not.toHaveBeenCalled();
+		expect(sourceStarts).toContain('pack-a');
+		m.resetPackagesForTest();
+		localStorage.removeItem('widgetsack.packages.netConsent');
+		vi.resetModules();
+	});
+});
diff --git a/client/src/lib/widgets/plugins/rss.test.ts b/client/src/lib/widgets/plugins/rss.test.ts
new file mode 100644
index 0000000..73f4691
--- /dev/null
+++ b/client/src/lib/widgets/plugins/rss.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { registerRssPlugin } from './rss';
+import { getMeta } from '../../core/widget';
+
+registerRssPlugin();
+
+describe('rss plugin', () => {
+	it('registers the rss widget with title / maxRows / color config', () => {
+		const meta = getMeta('rss');
+		expect(meta).toBeTruthy();
+		const keys = (meta?.configFields ?? []).map((f) => f.key);
+		expect(keys).toEqual(expect.arrayContaining(['title', 'maxRows', 'color']));
+	});
+});
diff --git a/client/src/lib/widgets/plugins/stocks.test.tsx b/client/src/lib/widgets/plugins/stocks.test.tsx
index bd999dd..e8db138 100644
--- a/client/src/lib/widgets/plugins/stocks.test.tsx
+++ b/client/src/lib/widgets/plugins/stocks.test.tsx
@@ -44,4 +44,27 @@ describe('stocks plugin', () => {
 	it('always exposes the global stocks.status sensor in the catalog', () => {
 		expect(sourceCatalogEntries().map((e) => e.id)).toContain('stocks.status');
 	});
+
+	it('the ticker sensors resolver derives stocks.<SYMBOL>.* ids, upper-cased + trimmed', () => {
+		const sensors = getMeta('ticker')?.sensors as (
+			c: Record<string, unknown>
+		) => Record<string, string>;
+		expect(typeof sensors).toBe('function');
+		const map = sensors({ symbol: '  aapl ' });
+		expect(map).toEqual({
+			price: 'stocks.AAPL.price',
+			change: 'stocks.AAPL.change',
+			series: 'stocks.AAPL.series',
+			currency: 'stocks.AAPL.currency',
+			state: 'stocks.AAPL.state'
+		});
+	});
+
+	it('the ticker sensors resolver binds nothing without a symbol', () => {
+		const sensors = getMeta('ticker')?.sensors as (
+			c: Record<string, unknown>
+		) => Record<string, string>;
+		expect(sensors({})).toEqual({});
+		expect(sensors({ symbol: '   ' })).toEqual({});
+	});
 });
diff --git a/client/src/lib/widgets/plugins/weather.test.ts b/client/src/lib/widgets/plugins/weather.test.ts
new file mode 100644
index 0000000..2efb522
--- /dev/null
+++ b/client/src/lib/widgets/plugins/weather.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { registerWeatherPlugin } from './weather';
+import { getMeta } from '../../core/widget';
+import { listSources } from '../../core/plugin';
+
+registerWeatherPlugin();
+
+describe('weather plugin', () => {
+	it('registers the weather, sunmoon and airquality widgets', () => {
+		for (const t of ['weather', 'sunmoon', 'airquality']) {
+			expect(getMeta(t), t).toBeTruthy();
+		}
+	});
+
+	it('exposes display toggles on the weather + sunmoon widgets', () => {
+		const keys = (t: string): string[] => (getMeta(t)?.configFields ?? []).map((f) => f.key);
+		expect(keys('weather')).toContain('showHiLo');
+		expect(keys('sunmoon')).toEqual(expect.arrayContaining(['showSun', 'showMoon']));
+	});
+
+	it('registers a sensor source', () => {
+		expect(listSources().some((s) => s.id === 'weather')).toBe(true);
+	});
+
+	it('the weather sensors resolver expands forecast-day series, clamped to 0..7', () => {
+		const sensors = getMeta('weather')?.sensors as (
+			c: Record<string, unknown>
+		) => Record<string, string>;
+		expect(typeof sensors).toBe('function');
+		const map = sensors({ forecastDays: 2 });
+		expect(map.temp).toBe('weather.temp');
+		expect(map.d0high).toBe('weather.day.0.high');
+		expect(map.d1code).toBe('weather.day.1.code');
+		expect(map.d2high).toBeUndefined(); // only days 0..1 for forecastDays:2
+		// out-of-range clamps to 7 days (× high/low/code)
+		const dayKeys = Object.keys(sensors({ forecastDays: 99 })).filter((k) => /^d\d/.test(k));
+		expect(dayKeys).toHaveLength(7 * 3);
+		// no forecastDays → base map only
+		expect(Object.keys(sensors({}))).toContain('temp');
+	});
+});
diff --git a/client/src/lib/widgets/registry.test.tsx b/client/src/lib/widgets/registry.test.tsx
new file mode 100644
index 0000000..6c3f1b0
--- /dev/null
+++ b/client/src/lib/widgets/registry.test.tsx
@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import { render } from '@testing-library/react';
+import { asMeter, getMeta, paletteItems, registry, registerWidget } from './registry';
+import type { WidgetMeta } from '../core/widget';
+import type { MeterProps } from './meterProps';
+
+// A trivial presentational meter for registration tests. Narrower-than-MeterProps props prove
+// `registerWidget`'s generic accepts a correctly-typed component without a cast.
+function StubMeter({ value }: { value?: MeterProps['value'] }) {
+	return <div data-testid="stub">{String(value ?? '')}</div>;
+}
+
+describe('registry', () => {
+	it('exposes built-in types in the back-compat `registry` alias', () => {
+		// A sample of the built-ins wired in this module.
+		expect(typeof registry.gauge).toBe('function');
+		expect(typeof registry.button).toBe('function');
+		expect(typeof registry.note).toBe('function');
+	});
+
+	it('re-exports getMeta resolving a built-in meta', () => {
+		const meta = getMeta('gauge');
+		expect(meta?.type).toBe('gauge');
+	});
+
+	it('asMeter passes the component through (identity adapter)', () => {
+		expect(asMeter(StubMeter)).toBe(StubMeter as unknown);
+	});
+
+	it('paletteItems lists registered metas that have a component', () => {
+		const items = paletteItems();
+		const types = items.map((i) => i.type);
+		// Built-ins with components show up...
+		expect(types).toContain('gauge');
+		expect(types).toContain('button');
+		// ...and each item carries a label (falls back to the type when meta has no label).
+		const gauge = items.find((i) => i.type === 'gauge')!;
+		expect(typeof gauge.label).toBe('string');
+		expect(gauge.label.length).toBeGreaterThan(0);
+	});
+
+	it('registerWidget registers the meta + component and surfaces it in the palette', () => {
+		const meta: WidgetMeta = {
+			type: 'test-plugin-widget',
+			label: 'Test Plugin Widget',
+			category: 'Test Pack'
+		};
+		registerWidget(meta, StubMeter);
+
+		// Component attached to the registry under its type.
+		expect(typeof registry['test-plugin-widget']).toBe('function');
+		// Meta resolvable via the re-exported getMeta.
+		expect(getMeta('test-plugin-widget')?.label).toBe('Test Plugin Widget');
+
+		// It now appears in the palette with its label + category.
+		const item = paletteItems().find((i) => i.type === 'test-plugin-widget');
+		expect(item).toEqual({
+			type: 'test-plugin-widget',
+			label: 'Test Plugin Widget',
+			category: 'Test Pack'
+		});
+
+		// And the registered component renders as the meter it was given.
+		const Comp = registry['test-plugin-widget'];
+		const { getByTestId } = render(<Comp value={42} />);
+		expect(getByTestId('stub').textContent).toBe('42');
+	});
+
+	it('paletteItems falls back to the type as label when meta has none', () => {
+		registerWidget({ type: 'test-nolabel-widget' }, StubMeter);
+		const item = paletteItems().find((i) => i.type === 'test-nolabel-widget')!;
+		// No label on the meta → label defaults to the type; no category → undefined.
+		expect(item.label).toBe('test-nolabel-widget');
+		expect(item.category).toBeUndefined();
+	});
+});
diff --git a/client/src/lib/widgets/registry.tsx b/client/src/lib/widgets/registry.tsx
index 8a89b3f..4d2bcd6 100644
--- a/client/src/lib/widgets/registry.tsx
+++ b/client/src/lib/widgets/registry.tsx
@@ -32,6 +32,7 @@ import Timer from './meters/Timer';
 import Recyclebin from './meters/Recyclebin';
 import StickyNote from './meters/StickyNote';
 import AudioSwitcherHost from './AudioSwitcherHost';
+import MonitorSwitchHost from './MonitorSwitchHost';
 import VolumeHost from './VolumeHost';
 import ImageHost from './ImageHost';
 
@@ -64,6 +65,7 @@ const components: Record<string, MeterComponent> = {
 	timer: asMeter(Timer),
 	recyclebin: asMeter(Recyclebin),
 	audioswitch: asMeter(AudioSwitcherHost),
+	monitorswitch: asMeter(MonitorSwitchHost),
 	volume: asMeter(VolumeHost),
 	image: asMeter(ImageHost),
 	note: asMeter(StickyNote)
diff --git a/client/src/lib/widgets/telemetryContext.test.tsx b/client/src/lib/widgets/telemetryContext.test.tsx
new file mode 100644
index 0000000..20473e4
--- /dev/null
+++ b/client/src/lib/widgets/telemetryContext.test.tsx
@@ -0,0 +1,35 @@
+// The ambient telemetry-hub context. useTelemetryHub returns the provided hub, and throws a
+// clear programming-error when used outside a provider.
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { TelemetryHubContext, useTelemetryHub } from './telemetryContext';
+import { createTelemetryHub, type TelemetryHub } from '../core/telemetry';
+
+describe('useTelemetryHub', () => {
+	it('returns the hub provided by the context provider', () => {
+		const hub = createTelemetryHub();
+		const wrapper = ({ children }: { children: React.ReactNode }) => (
+			<TelemetryHubContext.Provider value={hub}>{children}</TelemetryHubContext.Provider>
+		);
+		const { result } = renderHook(() => useTelemetryHub(), { wrapper });
+		expect(result.current).toBe(hub);
+	});
+
+	it('throws when used outside a provider (a programming error)', () => {
+		expect(() => renderHook(() => useTelemetryHub())).toThrow(/no TelemetryHubContext provider/);
+	});
+
+	it('the default context value is null', () => {
+		let captured: TelemetryHub | null | undefined;
+		const wrapper = ({ children }: { children: React.ReactNode }) => (
+			<TelemetryHubContext.Consumer>
+				{(v) => {
+					captured = v;
+					return children;
+				}}
+			</TelemetryHubContext.Consumer>
+		);
+		renderHook(() => null, { wrapper });
+		expect(captured).toBeNull();
+	});
+});
diff --git a/client/src/lib/widgets/useAssistant.test.ts b/client/src/lib/widgets/useAssistant.test.ts
new file mode 100644
index 0000000..02166b8
--- /dev/null
+++ b/client/src/lib/widgets/useAssistant.test.ts
@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { createElement, type ReactNode } from 'react';
+import { createTelemetryHub, type TelemetryHub } from '../core/telemetry';
+import { TelemetryHubContext } from './telemetryContext';
+
+// Mock the outer-ring deps: the LLM Tauri command, the TTS adapter, and the window-role check. The
+// prompt builder (core/llm) and the schedule math (core/schedule) stay REAL so we verify the
+// snapshot→prompt→complete flow and the interval/cron scheduling.
+const llmComplete = vi.fn();
+const speakSmart = vi.fn<(text: string) => Promise<void>>(() => Promise.resolve());
+const isStudioWindow = vi.fn(() => false);
+vi.mock('./plugins/llm-commands', () => ({ llmComplete: (...a: unknown[]) => llmComplete(...a) }));
+vi.mock('./plugins/llm-tts', () => ({ speakSmart: (t: string) => speakSmart(t) }));
+vi.mock('../overlay', () => ({ isStudioWindow: () => isStudioWindow() }));
+
+import { useAssistant, type AssistantConfig } from './useAssistant';
+
+let hub: TelemetryHub;
+
+function wrapper({ children }: { children: ReactNode }) {
+	return createElement(TelemetryHubContext.Provider, { value: hub }, children);
+}
+
+const cfg = (over: Partial<AssistantConfig> = {}): AssistantConfig => ({
+	prompt: 'Summarize',
+	schedule: '',
+	sensors: 'auto',
+	...over
+});
+
+beforeEach(() => {
+	vi.useFakeTimers();
+	hub = createTelemetryHub();
+	llmComplete.mockResolvedValue('  the briefing  ');
+	isStudioWindow.mockReturnValue(false);
+});
+afterEach(() => {
+	vi.runOnlyPendingTimers();
+	vi.useRealTimers();
+	vi.clearAllMocks();
+});
+
+describe('useAssistant', () => {
+	it('refresh() snapshots the hub, calls the provider, and trims the result', async () => {
+		hub.ingest({ sensor: 'cpu.total', ts_ms: 1, value: { kind: 'scalar', value: 42.37 } });
+		hub.ingest({ sensor: 'proc.cpu.top.name', ts_ms: 1, value: { kind: 'text', value: 'node' } });
+		const { result } = renderHook(() => useAssistant(cfg()), { wrapper });
+
+		await act(async () => {
+			result.current.refresh();
+		});
+
+		expect(llmComplete).toHaveBeenCalledOnce();
+		const [messages, opts] = llmComplete.mock.calls[0]!;
+		expect(opts).toEqual({ temperature: 0.4, maxTokens: 200 });
+		// The user message carries the rounded scalar (42.4) and the text reading.
+		const userMsg = (messages as { role: string; content: string }[]).find(
+			(m) => m.role === 'user'
+		)!;
+		expect(userMsg.content).toContain('42.4'); // scalar rounded to 1dp
+		expect(userMsg.content).toContain('node');
+		expect(result.current.text).toBe('the briefing'); // trimmed
+		expect(result.current.busy).toBe(false);
+		expect(result.current.error).toBe('');
+	});
+
+	it('only includes present, scalar/text sensors from a custom CSV (absent + non-readable skipped)', async () => {
+		hub.ingest({ sensor: 'gpu.util', ts_ms: 1, value: { kind: 'scalar', value: 80 } });
+		// A series-valued sensor has no scalar/text reading → readingOf returns null → it's skipped.
+		hub.ingest({ sensor: 'cpu.cores', ts_ms: 1, value: { kind: 'series', value: [1, 2, 3] } });
+		const { result } = renderHook(
+			() => useAssistant(cfg({ sensors: 'gpu.util, cpu.cores, missing.id' })),
+			{ wrapper }
+		);
+		await act(async () => {
+			result.current.refresh();
+		});
+		const userMsg = (llmComplete.mock.calls[0]![0] as { role: string; content: string }[]).find(
+			(m) => m.role === 'user'
+		)!;
+		expect(userMsg.content).toContain('gpu.util');
+		expect(userMsg.content).not.toContain('cpu.cores'); // series reading skipped
+		expect(userMsg.content).not.toContain('missing.id');
+	});
+
+	it('speaks the result when speak is enabled', async () => {
+		const { result } = renderHook(() => useAssistant(cfg({ speak: true })), { wrapper });
+		await act(async () => {
+			result.current.refresh();
+		});
+		expect(speakSmart).toHaveBeenCalledWith('the briefing');
+	});
+
+	it('surfaces a provider error and clears busy', async () => {
+		llmComplete.mockRejectedValueOnce(new Error('rate limited'));
+		const { result } = renderHook(() => useAssistant(cfg()), { wrapper });
+		await act(async () => {
+			result.current.refresh();
+		});
+		expect(result.current.error).toContain('rate limited');
+		expect(result.current.busy).toBe(false);
+		expect(result.current.text).toBe('');
+	});
+
+	it('auto-generates after the first-delay on the overlay (interval schedule)', async () => {
+		renderHook(() => useAssistant(cfg({ schedule: '30s' })), { wrapper });
+		expect(llmComplete).not.toHaveBeenCalled(); // nothing before the first delay
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(3000); // FIRST_DELAY_MS
+		});
+		expect(llmComplete).toHaveBeenCalledTimes(1);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(30_000); // one interval tick
+		});
+		expect(llmComplete).toHaveBeenCalledTimes(2);
+	});
+
+	it('floors a too-fast interval to the minimum (no API hammering)', async () => {
+		renderHook(() => useAssistant(cfg({ schedule: '1s' })), { wrapper });
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(3000); // first delay fires once
+		});
+		expect(llmComplete).toHaveBeenCalledTimes(1);
+		// A 1s schedule is floored to 15s — at +5s nothing more has fired.
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(5000);
+		});
+		expect(llmComplete).toHaveBeenCalledTimes(1);
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(10_000); // now past the 15s floor
+		});
+		expect(llmComplete).toHaveBeenCalledTimes(2);
+	});
+
+	it('does NOT auto-generate in the studio (manual refresh only)', async () => {
+		isStudioWindow.mockReturnValue(true);
+		const { result } = renderHook(() => useAssistant(cfg({ schedule: '30s' })), { wrapper });
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(60_000);
+		});
+		expect(llmComplete).not.toHaveBeenCalled(); // no auto run
+		await act(async () => {
+			result.current.refresh(); // but manual refresh still works
+		});
+		expect(llmComplete).toHaveBeenCalledOnce();
+	});
+
+	it('fires a cron schedule once per matching minute', async () => {
+		// Pin "now" to a minute boundary so the cron "* * * * *" (every minute) matches deterministically.
+		vi.setSystemTime(new Date('2026-06-19T10:00:30Z'));
+		renderHook(() => useAssistant(cfg({ schedule: '* * * * *' })), { wrapper });
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(3000); // first-delay run
+		});
+		expect(llmComplete).toHaveBeenCalledTimes(1);
+		// The cron poller ticks every 30s; within the same minute it must NOT re-fire (dedup).
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(30_000);
+		});
+		const afterSameMinute = llmComplete.mock.calls.length;
+		// Cross into the next minute → exactly one more fire.
+		await act(async () => {
+			await vi.advanceTimersByTimeAsync(60_000);
+		});
+		expect(llmComplete.mock.calls.length).toBeGreaterThan(afterSameMinute);
+	});
+});
diff --git a/client/src/lib/widgets/useSensors.test.ts b/client/src/lib/widgets/useSensors.test.ts
index af7f1e1..83c41c2 100644
--- a/client/src/lib/widgets/useSensors.test.ts
+++ b/client/src/lib/widgets/useSensors.test.ts
@@ -33,4 +33,26 @@ describe('useSensors', () => {
 		});
 		expect(result.current).toEqual({ 'np.title': 'Song', 'cpu.total': 3 });
 	});
+
+	it('an empty series yields null (no latest point)', () => {
+		const hub = createTelemetryHub();
+		const { result } = renderHook(() => useSensors(hub, ['cpu.total']));
+		act(() => hub.ingest({ sensor: 'cpu.total', ts_ms: 0, value: { kind: 'series', value: [] } }));
+		expect(result.current).toEqual({ 'cpu.total': null }); // .at(-1) ?? null
+	});
+
+	it('treats an opaque json value as null (a formula can not read it)', () => {
+		const hub = createTelemetryHub();
+		const { result } = renderHook(() => useSensors(hub, ['ha.entity']));
+		act(() =>
+			hub.ingest({ sensor: 'ha.entity', ts_ms: 0, value: { kind: 'json', value: { on: true } } })
+		);
+		expect(result.current).toEqual({ 'ha.entity': null });
+	});
+
+	it('returns an empty snapshot for no ids (no subscriptions)', () => {
+		const hub = createTelemetryHub();
+		const { result } = renderHook(() => useSensors(hub, []));
+		expect(result.current).toEqual({});
+	});
 });
diff --git a/client/src/mcp/tools.test.ts b/client/src/mcp/tools.test.ts
index 4a7c3ee..76017ef 100644
--- a/client/src/mcp/tools.test.ts
+++ b/client/src/mcp/tools.test.ts
@@ -84,6 +84,28 @@ describe('mcp tools', () => {
 		expect(describeLayoutText(null)).toMatch(/No layout yet/);
 	});
 
+	it('describeLayoutText defaults to every monitor and omits sensor for self-sourcing widgets', () => {
+		// No monitor arg => the `keys` (all monitors) branch. A clock has no sensor => the no-sensor arm.
+		const { file } = applyOpsToFile(
+			fileWith('DELL-1'),
+			[{ op: 'addWidget', widgetType: 'clock' }],
+			counter()
+		);
+		const out = describeLayoutText(file);
+		expect(out).toContain('## DELL-1');
+		expect(out).toMatch(/- .*: clock in /);
+		expect(out).not.toMatch(/clock \(sensor=/);
+	});
+
+	it('describeLayoutText flags a requested monitor that does not exist', () => {
+		// The file HAS a monitor (so keys is non-empty), but the requested key is not among them —
+		// each requested target prints "(no such monitor)".
+		const out = describeLayoutText(fileWith('DELL-1'), 'NOPE-9');
+		expect(out).toContain('Monitors: DELL-1');
+		expect(out).toContain('## NOPE-9');
+		expect(out).toContain('(no such monitor)');
+	});
+
 	it('sets and reads the active theme, preserving the rest of the file', () => {
 		const before = fileWith('DELL-1'); // the helper seeds theme:'neon'
 		expect(currentTheme(before)).toBe('neon');
@@ -97,6 +119,13 @@ describe('mcp tools', () => {
 		expect(currentTheme(setThemeInFile(null, 'cool'))).toBe('cool');
 	});
 
+	it('setThemeInFile back-fills version:2 on a versionless file and preserves extra keys', () => {
+		const themed = setThemeInFile({ monitors: {}, custom: 'keep' }, 'aurora');
+		expect(themed.version).toBe(2);
+		expect(themed.theme).toBe('aurora');
+		expect(themed.custom).toBe('keep');
+	});
+
 	it('describeNowPlayingText formats entries or reports nothing playing', () => {
 		expect(describeNowPlayingText(null)).toMatch(/Nothing is playing/);
 		expect(describeNowPlayingText([])).toMatch(/Nothing is playing/);
@@ -106,6 +135,11 @@ describe('mcp tools', () => {
 		expect(out).toBe('Playing: Song — Band [Spotify]');
 	});
 
+	it('describeNowPlayingText falls back for an entry missing every field', () => {
+		// Exercises the `status ?? '?'`, `title ?? '(unknown)'`, and the absent artist/source arms.
+		expect(describeNowPlayingText([{}])).toBe('?: (unknown)');
+	});
+
 	it('describeSensorsText lists live readings (sorted) or hints when absent', () => {
 		expect(describeSensorsText(null)).toMatch(/is widgetsack running/);
 		expect(describeSensorsText({ sensors: {} })).toMatch(/is widgetsack running/);
diff --git a/client/src/stores/persist.test.ts b/client/src/stores/persist.test.ts
index 373092d..60a3fd0 100644
--- a/client/src/stores/persist.test.ts
+++ b/client/src/stores/persist.test.ts
@@ -1,6 +1,8 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { createPersistedStore, readJson, readString, writeJson, writeString } from './persist';
 
+afterEach(() => vi.restoreAllMocks());
+
 describe('readJson / writeJson', () => {
 	beforeEach(() => localStorage.clear());
 
@@ -17,6 +19,15 @@ describe('readJson / writeJson', () => {
 		localStorage.setItem('t.corrupt', '{not json');
 		expect(readJson('t.corrupt')).toBeNull();
 	});
+
+	it('swallows a setItem failure (quota / unavailable) on writeJson', () => {
+		const spy = vi.spyOn(localStorage, 'setItem').mockImplementation(() => {
+			throw new DOMException('QuotaExceededError');
+		});
+		expect(() => writeJson('t.json', { a: 1 })).not.toThrow();
+		expect(spy).toHaveBeenCalledWith('t.json', JSON.stringify({ a: 1 }));
+		spy.mockRestore();
+	});
 });
 
 describe('readString / writeString', () => {
@@ -31,6 +42,23 @@ describe('readString / writeString', () => {
 	it('returns null for a missing key', () => {
 		expect(readString('t.missing')).toBeNull();
 	});
+
+	it('returns null instead of throwing when getItem is unavailable', () => {
+		const spy = vi.spyOn(localStorage, 'getItem').mockImplementation(() => {
+			throw new DOMException('SecurityError');
+		});
+		expect(readString('t.str')).toBeNull();
+		spy.mockRestore();
+	});
+
+	it('swallows a setItem failure on writeString', () => {
+		const spy = vi.spyOn(localStorage, 'setItem').mockImplementation(() => {
+			throw new DOMException('QuotaExceededError');
+		});
+		expect(() => writeString('t.str', 'value')).not.toThrow();
+		expect(spy).toHaveBeenCalledWith('t.str', 'value');
+		spy.mockRestore();
+	});
 });
 
 describe('createPersistedStore', () => {
diff --git a/client/src/stores/stores.test.ts b/client/src/stores/stores.test.ts
new file mode 100644
index 0000000..ab38c04
--- /dev/null
+++ b/client/src/stores/stores.test.ts
@@ -0,0 +1,216 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// The mediaStore + handle* reducers are an orchestration-ring module: pure TS types mirroring the
+// Rust session structs (state.rs), a localStorage-backed external store (via persist.ts), and three
+// reducers folded over the live session map. The store is created at module load from
+// localStorage, so each test re-imports the module after seeding/clearing storage to exercise the
+// parse seam (parseMediaStore) and the persisted defaults (serializeMediaStore) deterministically.
+
+type Stores = typeof import('./stores');
+const MEDIA_STORE_KEY = '_mediaStore';
+
+const load = async (): Promise<Stores> => {
+	vi.resetModules();
+	return import('./stores');
+};
+
+// A minimal SessionRecord with just the fields the reducers/priority touch.
+const rec = (
+	over: Partial<import('./stores').SessionRecord> = {}
+): import('./stores').SessionRecord => ({
+	session_id: 1,
+	source: 'foobar2000.exe',
+	timestamp_created: null,
+	timestamp_updated: null,
+	last_media_update: null,
+	last_model_update: null,
+	...over
+});
+
+beforeEach(() => localStorage.clear());
+afterEach(() => vi.restoreAllMocks());
+
+describe('defaultState', () => {
+	it('seeds the priority list lowercased and newline-joined', async () => {
+		const { defaultState } = await load();
+		expect(defaultState.sessions).toEqual({});
+		expect(defaultState.sourcePriority).toBe(
+			'spotifyab.spotifymusic_zpdnekdrzrea0!spotify\nfoobar2000.exe'
+		);
+		expect(defaultState.ignoreList).toBe('');
+		expect(defaultState.restoreToSavedPosition).toBe(false);
+		expect(defaultState.preferredMonitor).toBeNull();
+		expect(defaultState.savedPosition).toBeNull();
+	});
+});
+
+describe('mediaStore creation (parseMediaStore seam)', () => {
+	it('falls back to defaults when storage is empty', async () => {
+		const { mediaStore, defaultState } = await load();
+		expect(mediaStore.getSnapshot()).toEqual(defaultState);
+	});
+
+	it('falls back to defaults when storage is the literal null JSON', async () => {
+		localStorage.setItem(MEDIA_STORE_KEY, 'null');
+		const { mediaStore, defaultState } = await load();
+		expect(mediaStore.getSnapshot().sourcePriority).toBe(defaultState.sourcePriority);
+	});
+
+	it('overlays every persisted SerializedState field over the defaults', async () => {
+		const monitor = { name: 'DISPLAY1', position: { x: 0, y: 0 }, size: { width: 1, height: 1 } };
+		const saved = { x: 1, y: 2, width: 3, height: 4, timestamp: 5 };
+		localStorage.setItem(
+			MEDIA_STORE_KEY,
+			JSON.stringify({
+				sourcePriority: 'a\nb',
+				ignoreList: 'spotify',
+				styleOverride: '.np {}',
+				preferredMonitor: monitor,
+				savedPosition: saved,
+				restoreToSavedPosition: true
+			})
+		);
+		const { mediaStore } = await load();
+		const s = mediaStore.getSnapshot();
+		expect(s.sourcePriority).toBe('a\nb');
+		expect(s.ignoreList).toBe('spotify');
+		expect(s.styleOverride).toBe('.np {}');
+		expect(s.preferredMonitor).toEqual(monitor);
+		expect(s.savedPosition).toEqual(saved);
+		expect(s.restoreToSavedPosition).toBe(true);
+		// runtime-only field stays at its default
+		expect(s.sessions).toEqual({});
+	});
+
+	it('keeps defaults for fields the persisted blob omits (partial state)', async () => {
+		localStorage.setItem(MEDIA_STORE_KEY, JSON.stringify({ ignoreList: 'x' }));
+		const { mediaStore, defaultState } = await load();
+		const s = mediaStore.getSnapshot();
+		expect(s.ignoreList).toBe('x');
+		// untouched → default
+		expect(s.sourcePriority).toBe(defaultState.sourcePriority);
+		expect(s.restoreToSavedPosition).toBe(false);
+	});
+
+	it('treats an explicit null preferredMonitor as "provided" (overlays it)', async () => {
+		// preferredMonitor defaults to null; assert the `!== undefined` branch accepts an explicit null
+		localStorage.setItem(
+			MEDIA_STORE_KEY,
+			JSON.stringify({ preferredMonitor: null, savedPosition: null, restoreToSavedPosition: false })
+		);
+		const { mediaStore } = await load();
+		expect(mediaStore.getSnapshot().preferredMonitor).toBeNull();
+	});
+});
+
+describe('serializeMediaStore (persist seam)', () => {
+	it('persists exactly the SerializedState subset on creation — never the runtime sessions', async () => {
+		const { mediaStore } = await load();
+		mediaStore.update((cur) => ({
+			...cur,
+			sessions: { 1: rec() } as Record<string, import('./stores').SessionRecord>,
+			ignoreList: 'persist-me'
+		}));
+		const written = JSON.parse(localStorage.getItem(MEDIA_STORE_KEY) ?? '{}');
+		expect(written.ignoreList).toBe('persist-me');
+		expect(Object.keys(written).sort()).toEqual(
+			[
+				'ignoreList',
+				'preferredMonitor',
+				'restoreToSavedPosition',
+				'savedPosition',
+				'sourcePriority',
+				'styleOverride'
+			].sort()
+		);
+		// sessions must NOT cross into storage
+		expect('sessions' in written).toBe(false);
+	});
+});
+
+describe('handleInitialize', () => {
+	it('does nothing when opts is falsy', async () => {
+		const { mediaStore, handleInitialize } = await load();
+		const before = mediaStore.getSnapshot();
+		// @ts-expect-error exercising the falsy guard
+		handleInitialize(undefined);
+		expect(mediaStore.getSnapshot()).toBe(before);
+	});
+
+	it('folds the backend snapshot through upsertSession into the store', async () => {
+		const { mediaStore, handleInitialize } = await load();
+		handleInitialize({
+			sessions: {
+				1: rec({ session_id: 1, source: 'a.exe' }),
+				2: rec({ session_id: 2, source: 'b.exe' })
+			}
+		});
+		const s = mediaStore.getSnapshot().sessions;
+		expect(Object.keys(s).sort()).toEqual(['1', '2']);
+		expect(s[1].source).toBe('a.exe');
+		expect(s[2].source).toBe('b.exe');
+	});
+
+	it('dedupes a same-source duplicate in the initial set (no startup leak seed)', async () => {
+		const { mediaStore, handleInitialize } = await load();
+		handleInitialize({
+			sessions: {
+				1: rec({ session_id: 1, source: 'dup.exe' }),
+				2: rec({ session_id: 2, source: 'dup.exe' })
+			}
+		});
+		const s = mediaStore.getSnapshot().sessions;
+		// only the later upsert for that source survives
+		expect(Object.keys(s)).toEqual(['2']);
+	});
+});
+
+describe('handleUpdate', () => {
+	it('inserts a never-seen session keyed by session_id', async () => {
+		const { mediaStore, handleUpdate } = await load();
+		handleUpdate({ sessionRecord: rec({ session_id: 7, source: 's.exe' }) });
+		expect(mediaStore.getSnapshot().sessions[7].source).toBe('s.exe');
+	});
+
+	it('carries prior media forward when an update omits last_media_update', async () => {
+		const { mediaStore, handleUpdate } = await load();
+		const media = {
+			Media: [{ playback: null, timeline: null, media: null, source: 's.exe' }, { bytes: 42 }]
+		} as import('./stores').SessionUpdateEventMedia;
+		// first: a real media update
+		handleUpdate({
+			sessionRecord: rec({ session_id: 3, source: 's.exe', last_media_update: media })
+		});
+		// then: a model/timeline tick with no media → prior media is restored
+		handleUpdate({
+			sessionRecord: rec({ session_id: 3, source: 's.exe', last_media_update: null })
+		});
+		expect(mediaStore.getSnapshot().sessions[3].last_media_update).toEqual(media);
+	});
+
+	it('evicts a stale record for the SAME source recreated under a new id', async () => {
+		const { mediaStore, handleUpdate } = await load();
+		handleUpdate({ sessionRecord: rec({ session_id: 1, source: 'player.exe' }) });
+		handleUpdate({ sessionRecord: rec({ session_id: 2, source: 'player.exe' }) });
+		const s = mediaStore.getSnapshot().sessions;
+		expect(Object.keys(s)).toEqual(['2']);
+	});
+});
+
+describe('handleDelete', () => {
+	it('removes the record for the given session_id', async () => {
+		const { mediaStore, handleUpdate, handleDelete } = await load();
+		handleUpdate({ sessionRecord: rec({ session_id: 9, source: 'x.exe' }) });
+		expect(mediaStore.getSnapshot().sessions[9]).toBeDefined();
+		handleDelete({ sessionRecord: rec({ session_id: 9, source: 'x.exe' }) });
+		expect(mediaStore.getSnapshot().sessions[9]).toBeUndefined();
+		expect(mediaStore.getSnapshot().sessions).toEqual({});
+	});
+
+	it('is a no-op (leaves other sessions intact) when the id is absent', async () => {
+		const { mediaStore, handleUpdate, handleDelete } = await load();
+		handleUpdate({ sessionRecord: rec({ session_id: 1, source: 'a.exe' }) });
+		handleDelete({ sessionRecord: rec({ session_id: 999, source: 'gone.exe' }) });
+		expect(Object.keys(mediaStore.getSnapshot().sessions)).toEqual(['1']);
+	});
+});
diff --git a/client/src/styles.css b/client/src/styles.css
index f0c5f68..b52bd10 100644
--- a/client/src/styles.css
+++ b/client/src/styles.css
@@ -156,3 +156,18 @@ html.overlay-windowed body {
 	outline: 2px solid var(--ui-accent-fg);
 	outline-offset: 1px;
 }
+
+/* View Transitions — the studio section cross-fade (see lib/viewTransition.ts wraps the section
+   swap). Keep it snappy. The JS already skips the transition under prefers-reduced-motion; this is a
+   belt-and-suspenders guard that also covers any future view-transition-driven change. */
+::view-transition-old(root),
+::view-transition-new(root) {
+	animation-duration: 200ms;
+}
+@media (prefers-reduced-motion: reduce) {
+	::view-transition-group(*),
+	::view-transition-old(*),
+	::view-transition-new(*) {
+		animation: none !important;
+	}
+}
diff --git a/client/vite.config.ts b/client/vite.config.ts
index f933e65..3f0b2eb 100644
--- a/client/vite.config.ts
+++ b/client/vite.config.ts
@@ -40,6 +40,65 @@ export default defineConfig({
 		environment: 'happy-dom',
 		globals: true,
 		setupFiles: ['./src/test-setup.ts'],
-		include: ['src/**/*.{test,spec}.{js,ts,jsx,tsx}']
+		include: ['src/**/*.{test,spec}.{js,ts,jsx,tsx}'],
+		coverage: {
+			provider: 'v8',
+			all: true,
+			reporter: ['text', 'json-summary', 'text-summary'],
+			include: ['src/**/*.{ts,tsx}'],
+			// Principled exclusions: code that unit tests can't cover usefully. Bootstrap + dev-only
+			// mocks; the Canvas organism + studio interactions are covered by the Playwright e2e suite
+			// (test:e2e), not happy-dom; and the thin Tauri IO adapters (invoke/listen/emit + window
+			// manipulation) are integration glue, not unit logic. Everything else is held to 100%.
+			exclude: [
+				'src/**/*.{test,spec}.{ts,tsx}',
+				'src/test-setup.ts',
+				'src/**/*.d.ts',
+				// bootstrap / dev-only
+				'src/main.tsx',
+				'src/App.tsx',
+				'src/lib/devMock.ts',
+				// e2e-driven (Playwright)
+				'src/lib/widgets/Canvas.tsx',
+				// DOM-measurement glue: reads getBoundingClientRect off every [data-id] + reacts to
+				// Resize/MutationObserver (happy-dom returns zero rects). Its pure seam screenRectToLayout
+				// is unit-tested in core/measureMath.test.ts; the rest is runtime/e2e only.
+				'src/lib/widgets/canvas/useMeasuredRects.ts',
+				// canvas-2D / FFT-stream draw glue: the substance is imperative draw() on a 2D context
+				// happy-dom doesn't provide (getContext returns null, client sizes are 0). The pure geometry
+				// is unit-tested in cpuCoresMath / sparklineMath / spectrumMath.test.ts; acquire/release is
+				// in Spectrum.test.ts. Same class as audio/**.
+				'src/lib/widgets/meters/CpuCoresCanvas.tsx',
+				'src/lib/widgets/meters/Spectrum.tsx',
+				// overlay-runtime + DOM/canvas glue (ResizeObserver / getImageData / listen-emit +
+				// window/monitor manipulation): no domain logic, not drivable under happy-dom. Pure seams
+				// live elsewhere (palette.ts for the sampler; per-role reveal in useStudioInit is covered).
+				'src/lib/widgets/canvas/useStageSize.ts',
+				'src/lib/widgets/canvas/useStudioInit.ts',
+				'src/lib/widgets/canvas/wallpaperSampler.ts',
+				// plugin barrel: imports + calls the 8 registerXPlugin fns in a try/catch table (wiring,
+				// not logic — each plugin is registration-tested individually).
+				'src/lib/widgets/plugins/index.ts',
+				// Tauri IO adapters (invoke/listen/emit + window/monitor manipulation)
+				'src/lib/overlay.ts',
+				'src/lib/diag.ts',
+				'src/lib/utils/**',
+				'src/lib/audio/**',
+				'src/lib/windows/**',
+				'src/lib/ddc/**',
+				'src/lib/telemetry/**',
+				'src/lib/components/NowPlaying/source.ts',
+				'src/lib/components/NowPlaying/np-source.ts',
+				'src/lib/widgets/plugins/*-source.ts',
+				'src/lib/widgets/plugins/*-commands.ts',
+				'src/mcp/server.ts'
+			],
+			// Principled floors, not literal 100%: the included scope is ~99.4% lines / 96.9% funcs /
+			// 95.6% branches. The residue is genuinely uncoverable with *useful* tests — unreachable
+			// defensive arms (`?? []`, impossible `default:`/guards) and happy-dom-undrivable visual glue
+			// (e.g. the Inspector add-palette hover-preview: 280ms debounce + getBoundingClientRect). Pure
+			// IO/DOM/canvas adapters are excluded above. These thresholds ratchet-guard against regression.
+			thresholds: { statements: 99, lines: 99, functions: 96, branches: 95 }
+		}
 	}
 });
diff --git a/docs/widgets.md b/docs/widgets.md
index e604eed..1e5c6bf 100644
--- a/docs/widgets.md
+++ b/docs/widgets.md
@@ -172,9 +172,9 @@ Analog clock face with hour / minute / second hands (self-sourcing).
 | `accent` | color |  |  |  |
 | `face` | color |  |  | face fill (default transparent) |
 
-### Button — `button`
+### Button / Macro — `button`
 
-![Button widget](img/widgets/button.png)
+![Button / Macro widget](img/widgets/button.png)
 
 Pressable button that runs a macro of {domain, service, data} calls (HA services or media transport).
 
@@ -503,3 +503,23 @@ A countdown timer or stopwatch with start / pause / reset. A countdown can loop
 | `loop` | toggle | false |  | restart automatically when a countdown reaches zero |
 | `label` | text | "" |  | header text |
 | `color` | color | "" |  | text colour (blank = theme) |
+
+### Monitor Switch — `monitorswitch`
+
+![Monitor Switch widget](img/widgets/monitorswitch.png)
+
+Switch a monitor’s input source (HDMI / DisplayPort / …) with a tap, over DDC/CI. Shows the current source and, optionally, the resolution + refresh rate. Requires DDC/CI enabled on the monitor; input codes are vendor-specific (auto-detected). Windows.
+
+- **Sensor:** none (self-sourcing)
+- **Default size:** 220×150
+- **Interactive:** catches clicks in passive mode (per-widget click-through)
+
+| key | type | default | options / range | description |
+| --- | --- | --- | --- | --- |
+| `monitor` | select |  | (runtime list) — from `displayNames` | which monitor to control (blank = the primary monitor) |
+| `sources` | monitorSources |  |  | pick which inputs to show, and rename them (e.g. HDMI 2 → Switch 2); blank = show all detected |
+| `label` | text |  |  | title override (blank = the monitor’s name) |
+| `showCurrent` | toggle | true |  | highlight the currently-selected input |
+| `showStats` | toggle | false |  | show the current resolution + refresh rate |
+| `compact` | toggle | false |  | show a compact list instead of large touch buttons |
+| `color` | color |  |  |  |
diff --git a/widgetsack/Cargo.toml b/widgetsack/Cargo.toml
index 6d4060b..dbd8f60 100644
--- a/widgetsack/Cargo.toml
+++ b/widgetsack/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "widgetsack"
 # Keep in lockstep with tauri.conf.json's version (the bundle/updater source of truth).
-version = "0.0.47"
+version = "0.0.48"
 description = "widgetsack desktop widget platform"
 authors = ["you"]
 license = "MIT OR Apache-2.0"
diff --git a/widgetsack/src/agenda.rs b/widgetsack/src/agenda.rs
index 2eb3d5f..541be7c 100644
--- a/widgetsack/src/agenda.rs
+++ b/widgetsack/src/agenda.rs
@@ -211,7 +211,9 @@ fn agenda_config_path<R: Runtime>(app: &AppHandle<R>) -> Result<PathBuf, String>
 pub fn load_agenda_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<AgendaConfig>, String> {
     let path = agenda_config_path(app)?;
     match std::fs::read_to_string(&path) {
-        Ok(txt) => serde_json::from_str(&txt).map(Some).map_err(|e| e.to_string()),
+        Ok(txt) => serde_json::from_str(&txt)
+            .map(Some)
+            .map_err(|e| e.to_string()),
         Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
         Err(err) => Err(err.to_string()),
     }
@@ -407,14 +409,23 @@ mod tests {
     #[test]
     fn ics_to_iso_handles_the_three_forms() {
         assert_eq!(ics_to_iso("20261231"), Some(("2026-12-31".into(), true)));
-        assert_eq!(ics_to_iso("20261231T180000Z"), Some(("2026-12-31T18:00:00Z".into(), false)));
-        assert_eq!(ics_to_iso("20261231T093000"), Some(("2026-12-31T09:30:00".into(), false)));
+        assert_eq!(
+            ics_to_iso("20261231T180000Z"),
+            Some(("2026-12-31T18:00:00Z".into(), false))
+        );
+        assert_eq!(
+            ics_to_iso("20261231T093000"),
+            Some(("2026-12-31T09:30:00".into(), false))
+        );
         assert_eq!(ics_to_iso("garbage"), None);
     }
 
     #[test]
     fn unescape_ics_decodes_text_escapes() {
-        assert_eq!(unescape_ics("Lunch with Bob\\, then gym"), "Lunch with Bob, then gym");
+        assert_eq!(
+            unescape_ics("Lunch with Bob\\, then gym"),
+            "Lunch with Bob, then gym"
+        );
         assert_eq!(unescape_ics("line1\\nline2"), "line1 line2");
     }
 
@@ -436,12 +447,15 @@ mod tests {
             END:VCALENDAR";
         let ev = parse_ics_events(ics, 10);
         assert_eq!(ev.len(), 2); // the third (no SUMMARY) is skipped
-        assert_eq!(ev[0], AgendaEvent {
-            summary: "Standup".into(),
-            start: "2026-12-31T09:30:00".into(),
-            all_day: false,
-            location: "Room 2".into(),
-        });
+        assert_eq!(
+            ev[0],
+            AgendaEvent {
+                summary: "Standup".into(),
+                start: "2026-12-31T09:30:00".into(),
+                all_day: false,
+                location: "Room 2".into(),
+            }
+        );
         assert_eq!(ev[1].summary, "All-day off");
         assert!(ev[1].all_day);
         assert_eq!(ev[1].start, "2027-01-01");
@@ -479,13 +493,23 @@ mod tests {
 
     #[test]
     fn normalize_url_rewrites_webcal() {
-        assert_eq!(normalize_url("webcal://ex.com/cal.ics"), "https://ex.com/cal.ics");
-        assert_eq!(normalize_url("https://ex.com/cal.ics"), "https://ex.com/cal.ics");
+        assert_eq!(
+            normalize_url("webcal://ex.com/cal.ics"),
+            "https://ex.com/cal.ics"
+        );
+        assert_eq!(
+            normalize_url("https://ex.com/cal.ics"),
+            "https://ex.com/cal.ics"
+        );
     }
 
     #[test]
     fn has_feed_accepts_http_and_webcal() {
-        let mk = |u: &str| AgendaConfig { url: u.into(), title: String::new(), poll_interval_secs: 1800 };
+        let mk = |u: &str| AgendaConfig {
+            url: u.into(),
+            title: String::new(),
+            poll_interval_secs: 1800,
+        };
         assert!(has_feed(&mk("https://ex.com/c.ics")));
         assert!(has_feed(&mk("webcal://ex.com/c.ics")));
         assert!(!has_feed(&mk("ftp://x")));
diff --git a/widgetsack/src/art.rs b/widgetsack/src/art.rs
index 8e44547..c56a265 100644
--- a/widgetsack/src/art.rs
+++ b/widgetsack/src/art.rs
@@ -26,7 +26,7 @@ use std::collections::{HashMap, VecDeque};
 use std::hash::{Hash, Hasher};
 use std::sync::{Arc, Mutex};
 
-use tauri::http::{header, Request, Response, StatusCode};
+use tauri::http::{Request, Response, StatusCode, header};
 use tauri::{AppHandle, Manager, Runtime, UriSchemeContext};
 
 use crate::listener::{ImageWrapper, SessionUpdateEventWrapper};
@@ -164,7 +164,10 @@ pub fn build_response(art: Option<&ImageWrapper>) -> Response<Cow<'static, [u8]>
     match art {
         Some(img) => Response::builder()
             .status(StatusCode::OK)
-            .header(header::CONTENT_TYPE, content_type_for(&img.content_type, &img.data))
+            .header(
+                header::CONTENT_TYPE,
+                content_type_for(&img.content_type, &img.data),
+            )
             .header(header::CACHE_CONTROL, "no-store")
             .header(header::ACCESS_CONTROL_ALLOW_ORIGIN, "*")
             .body(Cow::Owned(img.data.clone()))
@@ -234,7 +237,10 @@ mod tests {
         assert_eq!(content_type_for("IMAGE/JPG", &[]), "image/jpeg");
         // Unknown declared type → sniff the magic bytes.
         assert_eq!(content_type_for("", &[0x89, 0x50, 0x4E, 0x47]), "image/png");
-        assert_eq!(content_type_for("application/octet-stream", &[0xFF, 0xD8, 0xFF]), "image/jpeg");
+        assert_eq!(
+            content_type_for("application/octet-stream", &[0xFF, 0xD8, 0xFF]),
+            "image/jpeg"
+        );
         // Unrecognisable → jpeg default (never an invalid header value).
         assert_eq!(content_type_for("", &[0, 0, 0]), "image/jpeg");
     }
@@ -309,12 +315,18 @@ mod tests {
 
         let state = ArtState::default();
         note_record(&state, &rec);
-        assert!(state.0.lock().unwrap().get(hash).is_some(), "media cover is registered");
+        assert!(
+            state.0.lock().unwrap().get(hash).is_some(),
+            "media cover is registered"
+        );
 
         // A model/timeline update carries no cover → nothing new registered.
         rec.last_media_update = Some(SessionUpdateEventWrapper::Model(model));
         let state2 = ArtState::default();
         note_record(&state2, &rec);
-        assert!(state2.0.lock().unwrap().is_empty(), "model update registers no cover");
+        assert!(
+            state2.0.lock().unwrap().is_empty(),
+            "model update registers no cover"
+        );
     }
 }
diff --git a/widgetsack/src/audio.rs b/widgetsack/src/audio.rs
index 54567c8..253d03e 100644
--- a/widgetsack/src/audio.rs
+++ b/widgetsack/src/audio.rs
@@ -27,8 +27,8 @@ use std::time::{SystemTime, UNIX_EPOCH};
 use realfft::num_complex::Complex;
 use realfft::{RealFftPlanner, RealToComplex};
 use serde::Serialize;
-use tauri::ipc::Channel;
 use tauri::Runtime;
+use tauri::ipc::Channel;
 
 use crate::log;
 
@@ -160,14 +160,22 @@ fn band_edges(band_count: usize, fmin: f32, fmax: f32, linear: bool) -> Vec<f32>
             .collect();
     }
     let ratio = (fmax / fmin).powf(1.0 / band_count as f32);
-    (0..=band_count).map(|i| fmin * ratio.powi(i as i32)).collect()
+    (0..=band_count)
+        .map(|i| fmin * ratio.powi(i as i32))
+        .collect()
 }
 
 /// Group linear FFT-bin magnitudes into `band_count` display bands over [`FMIN_HZ`, `FMAX_HZ`]
 /// (log- or `linear`-spaced), each the dB-normalised (0..1) PEAK magnitude within its frequency span.
 /// Peak (not average) keeps narrow tones visible. The frequency range and dB floor are the fixed
 /// app constants, so they aren't parameters.
-fn to_bands(mags: &[f32], sample_rate: u32, fft_size: usize, band_count: usize, linear: bool) -> Vec<f32> {
+fn to_bands(
+    mags: &[f32],
+    sample_rate: u32,
+    fft_size: usize,
+    band_count: usize,
+    linear: bool,
+) -> Vec<f32> {
     if band_count == 0 || mags.is_empty() || fft_size == 0 {
         return vec![0.0; band_count];
     }
@@ -249,7 +257,11 @@ impl SpectrumProcessor {
             *slot = window.get(i).copied().unwrap_or(0.0) * self.window[i];
         }
         // realfft uses `input` as scratch and writes N/2+1 complex bins into `spectrum`.
-        if self.fft.process(&mut self.input, &mut self.spectrum).is_ok() {
+        if self
+            .fft
+            .process(&mut self.input, &mut self.spectrum)
+            .is_ok()
+        {
             let mags = magnitudes(&self.spectrum);
             let bands = to_bands(&mags, self.sample_rate, self.fft_size, band_count, linear);
             if self.smoothed.len() != band_count {
@@ -338,7 +350,7 @@ pub fn stop_spectrum<R: Runtime>(
 #[cfg(target_os = "windows")]
 #[tauri::command]
 pub fn list_audio_outputs() -> Result<Vec<AudioDevice>, String> {
-    use wasapi::{initialize_mta, Direction};
+    use wasapi::{Direction, initialize_mta};
     // The command may run on a COM-uninitialised pool thread; init MTA (a no-op / harmless
     // RPC_E_CHANGED_MODE if COM is already up on this thread — enumeration works either way).
     let _ = initialize_mta().ok();
@@ -374,7 +386,7 @@ pub fn list_audio_outputs() -> Result<Vec<AudioDevice>, String> {
 #[cfg(target_os = "windows")]
 #[tauri::command]
 pub fn default_audio_output() -> Option<String> {
-    use wasapi::{initialize_mta, Direction};
+    use wasapi::{Direction, initialize_mta};
     let _ = initialize_mta().ok();
     let enumerator = wasapi::DeviceEnumerator::new().ok()?;
     enumerator
@@ -397,19 +409,71 @@ pub fn default_audio_output() -> Option<String> {
 #[cfg(target_os = "windows")]
 #[windows::core::interface("f8679f50-850a-41cf-9c72-430f290290c8")]
 unsafe trait IPolicyConfig: windows::core::IUnknown {
-    unsafe fn get_mix_format(&self, id: windows::core::PCWSTR, fmt: *mut *mut ::core::ffi::c_void) -> windows::core::HRESULT;
-    unsafe fn get_device_format(&self, id: windows::core::PCWSTR, default: i32, fmt: *mut *mut ::core::ffi::c_void) -> windows::core::HRESULT;
+    unsafe fn get_mix_format(
+        &self,
+        id: windows::core::PCWSTR,
+        fmt: *mut *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
+    unsafe fn get_device_format(
+        &self,
+        id: windows::core::PCWSTR,
+        default: i32,
+        fmt: *mut *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
     unsafe fn reset_device_format(&self, id: windows::core::PCWSTR) -> windows::core::HRESULT;
-    unsafe fn set_device_format(&self, id: windows::core::PCWSTR, endpoint_fmt: *mut ::core::ffi::c_void, mix_fmt: *mut ::core::ffi::c_void) -> windows::core::HRESULT;
-    unsafe fn get_processing_period(&self, id: windows::core::PCWSTR, default: i32, default_period: *mut i64, min_period: *mut i64) -> windows::core::HRESULT;
-    unsafe fn set_processing_period(&self, id: windows::core::PCWSTR, period: *mut i64) -> windows::core::HRESULT;
-    unsafe fn get_share_mode(&self, id: windows::core::PCWSTR, mode: *mut ::core::ffi::c_void) -> windows::core::HRESULT;
-    unsafe fn set_share_mode(&self, id: windows::core::PCWSTR, mode: *mut ::core::ffi::c_void) -> windows::core::HRESULT;
-    unsafe fn get_property_value(&self, id: windows::core::PCWSTR, key: i32, value: *const ::core::ffi::c_void, out: *mut ::core::ffi::c_void) -> windows::core::HRESULT;
-    unsafe fn set_property_value(&self, id: windows::core::PCWSTR, key: i32, value: *const ::core::ffi::c_void, out: *mut ::core::ffi::c_void) -> windows::core::HRESULT;
+    unsafe fn set_device_format(
+        &self,
+        id: windows::core::PCWSTR,
+        endpoint_fmt: *mut ::core::ffi::c_void,
+        mix_fmt: *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
+    unsafe fn get_processing_period(
+        &self,
+        id: windows::core::PCWSTR,
+        default: i32,
+        default_period: *mut i64,
+        min_period: *mut i64,
+    ) -> windows::core::HRESULT;
+    unsafe fn set_processing_period(
+        &self,
+        id: windows::core::PCWSTR,
+        period: *mut i64,
+    ) -> windows::core::HRESULT;
+    unsafe fn get_share_mode(
+        &self,
+        id: windows::core::PCWSTR,
+        mode: *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
+    unsafe fn set_share_mode(
+        &self,
+        id: windows::core::PCWSTR,
+        mode: *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
+    unsafe fn get_property_value(
+        &self,
+        id: windows::core::PCWSTR,
+        key: i32,
+        value: *const ::core::ffi::c_void,
+        out: *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
+    unsafe fn set_property_value(
+        &self,
+        id: windows::core::PCWSTR,
+        key: i32,
+        value: *const ::core::ffi::c_void,
+        out: *mut ::core::ffi::c_void,
+    ) -> windows::core::HRESULT;
     /// SetDefaultEndpoint(wszDeviceId, eRole) — the one we call. role: 0 eConsole, 1 eMultimedia, 2 eCommunications.
-    unsafe fn set_default_endpoint(&self, device_id: windows::core::PCWSTR, role: u32) -> windows::core::HRESULT;
-    unsafe fn set_endpoint_visibility(&self, id: windows::core::PCWSTR, visible: i32) -> windows::core::HRESULT;
+    unsafe fn set_default_endpoint(
+        &self,
+        device_id: windows::core::PCWSTR,
+        role: u32,
+    ) -> windows::core::HRESULT;
+    unsafe fn set_endpoint_visibility(
+        &self,
+        id: windows::core::PCWSTR,
+        visible: i32,
+    ) -> windows::core::HRESULT;
 }
 
 /// Make `id` the default render endpoint for ALL roles (console + multimedia + communications), like
@@ -419,10 +483,10 @@ unsafe trait IPolicyConfig: windows::core::IUnknown {
 #[tauri::command]
 pub fn set_default_audio_output(id: String) -> Result<(), String> {
     use std::iter::once;
-    use windows::core::PCWSTR;
     use windows::Win32::System::Com::{
-        CoCreateInstance, CoInitializeEx, CLSCTX_ALL, COINIT_MULTITHREADED,
+        CLSCTX_ALL, COINIT_MULTITHREADED, CoCreateInstance, CoInitializeEx,
     };
+    use windows::core::PCWSTR;
 
     // CPolicyConfigClient.
     const CLSID_POLICY_CONFIG: windows::core::GUID =
@@ -471,15 +535,20 @@ pub struct AudioVolume {
 /// Acquire the default render endpoint's `IAudioEndpointVolume`. COM is initialised MTA on the calling
 /// (pool) thread; `RPC_E_CHANGED_MODE` if already up in another mode is harmless.
 #[cfg(target_os = "windows")]
-fn endpoint_volume() -> windows::core::Result<windows::Win32::Media::Audio::Endpoints::IAudioEndpointVolume>
-{
-    use windows::Win32::Media::Audio::{eConsole, eRender, IMMDeviceEnumerator, MMDeviceEnumerator};
-    use windows::Win32::System::Com::{CoCreateInstance, CoInitializeEx, CLSCTX_ALL, COINIT_MULTITHREADED};
+fn endpoint_volume()
+-> windows::core::Result<windows::Win32::Media::Audio::Endpoints::IAudioEndpointVolume> {
+    use windows::Win32::Media::Audio::{
+        IMMDeviceEnumerator, MMDeviceEnumerator, eConsole, eRender,
+    };
+    use windows::Win32::System::Com::{
+        CLSCTX_ALL, COINIT_MULTITHREADED, CoCreateInstance, CoInitializeEx,
+    };
 
     // SAFETY: standard COM create/activate; every interface is released on drop.
     unsafe {
         let _ = CoInitializeEx(None, COINIT_MULTITHREADED);
-        let enumerator: IMMDeviceEnumerator = CoCreateInstance(&MMDeviceEnumerator, None, CLSCTX_ALL)?;
+        let enumerator: IMMDeviceEnumerator =
+            CoCreateInstance(&MMDeviceEnumerator, None, CLSCTX_ALL)?;
         let device = enumerator.GetDefaultAudioEndpoint(eRender, eConsole)?;
         device.Activate(CLSCTX_ALL, None)
     }
@@ -529,7 +598,8 @@ pub fn set_audio_mute(muted: bool) -> Result<(), String> {
     // SAFETY: writes the mute flag; eventcontext is null.
     unsafe {
         let vol = endpoint_volume().map_err(|e| e.to_string())?;
-        vol.SetMute(muted, std::ptr::null()).map_err(|e| e.to_string())
+        vol.SetMute(muted, std::ptr::null())
+            .map_err(|e| e.to_string())
     }
 }
 
@@ -560,9 +630,7 @@ mod capture {
     use super::*;
     use std::collections::VecDeque;
     use std::time::{Duration, Instant};
-    use wasapi::{
-        initialize_mta, Direction, SampleType, StreamMode, WaveFormat,
-    };
+    use wasapi::{Direction, SampleType, StreamMode, WaveFormat, initialize_mta};
 
     /// How long to wait before re-initialising after a recoverable device error / switch.
     const RETRY_BACKOFF: Duration = Duration::from_millis(500);
@@ -620,7 +688,11 @@ mod capture {
                 }
             }
             if failures >= MAX_CONSECUTIVE_FAILURES {
-                log::error("audio", "spectrum: giving up after repeated capture failures").emit();
+                log::error(
+                    "audio",
+                    "spectrum: giving up after repeated capture failures",
+                )
+                .emit();
                 state.lock().running = false;
                 return;
             }
@@ -664,7 +736,14 @@ mod capture {
             .unwrap_or_else(|_| "unknown".to_string());
         let mut audio_client = device.get_iaudioclient()?;
 
-        let format = WaveFormat::new(32, 32, &SampleType::Float, SAMPLE_RATE as usize, CHANNELS as usize, None);
+        let format = WaveFormat::new(
+            32,
+            32,
+            &SampleType::Float,
+            SAMPLE_RATE as usize,
+            CHANNELS as usize,
+            None,
+        );
         let (_default_period, min_period) = audio_client.get_device_period()?;
         // Polling (not event-driven): loopback is incompatible with EVENTCALLBACK in shared mode.
         let mode = StreamMode::PollingShared {
@@ -866,7 +945,10 @@ mod tests {
         mags[bin] = FFT_SIZE as f32 / 4.0; // ≈ full scale
         let bands = to_bands(&mags, SAMPLE_RATE, FFT_SIZE, 32, false);
         assert!(bands.iter().all(|&b| (0.0..=1.0).contains(&b)));
-        assert!(bands.iter().cloned().fold(0.0_f32, f32::max) > 0.9, "1 kHz band should be near full");
+        assert!(
+            bands.iter().cloned().fold(0.0_f32, f32::max) > 0.9,
+            "1 kHz band should be near full"
+        );
     }
 
     #[test]
@@ -899,7 +981,12 @@ mod tests {
         assert!(frame.bands.iter().all(|&b| (0.0..=1.0).contains(&b)));
 
         // Which band owns 1 kHz?
-        let edges = band_edges(band_count, FMIN_HZ, FMAX_HZ.min(SAMPLE_RATE as f32 / 2.0), false);
+        let edges = band_edges(
+            band_count,
+            FMIN_HZ,
+            FMAX_HZ.min(SAMPLE_RATE as f32 / 2.0),
+            false,
+        );
         let tone_band = (0..band_count)
             .find(|&b| freq >= edges[b] && freq < edges[b + 1])
             .expect("1 kHz within range");
@@ -907,10 +994,12 @@ mod tests {
         assert!(peak > 0.5, "tone band should be strong, got {peak}");
 
         // A far-away band (well below the tone, e.g. ~50 Hz) should be near silent.
-        let low_band = (0..band_count)
-            .find(|&b| edges[b + 1] < 100.0)
-            .unwrap_or(0);
-        assert!(frame.bands[low_band] < 0.2, "low band should be quiet, got {}", frame.bands[low_band]);
+        let low_band = (0..band_count).find(|&b| edges[b + 1] < 100.0).unwrap_or(0);
+        assert!(
+            frame.bands[low_band] < 0.2,
+            "low band should be quiet, got {}",
+            frame.bands[low_band]
+        );
     }
 
     #[test]
diff --git a/widgetsack/src/autostart.rs b/widgetsack/src/autostart.rs
index 7d3b366..6fa0fab 100644
--- a/widgetsack/src/autostart.rs
+++ b/widgetsack/src/autostart.rs
@@ -81,7 +81,11 @@ pub fn reconcile(app: &tauri::AppHandle) {
     let Some(want) = reconcile_action(read_pref(), current) else {
         return;
     };
-    let result = if want { manager.enable() } else { manager.disable() };
+    let result = if want {
+        manager.enable()
+    } else {
+        manager.disable()
+    };
     if let Err(err) = result {
         crate::log::error("startup", "failed to reconcile autostart from preference")
             .field("enable", want)
diff --git a/widgetsack/src/bridge.rs b/widgetsack/src/bridge.rs
index 13a9384..1354e3f 100644
--- a/widgetsack/src/bridge.rs
+++ b/widgetsack/src/bridge.rs
@@ -32,6 +32,10 @@ pub const CONTROLS_CHANGED_EVENT: &str = "controls_changed";
 pub const TOGGLE_EDIT_EVENT: &str = "toggle_edit";
 pub const OPEN_STUDIO_EVENT: &str = "open_studio";
 pub const ARRANGE_ZONES_EVENT: &str = "arrange_zones";
+/// Re-fit every overlay to the CURRENT display layout (tray "Re-fit overlays" + the manual trigger).
+/// Each overlay/studio listens and re-runs its fit/reconcile — used when monitors are
+/// added/removed/moved/resized at runtime, which fires no per-window scale-change event.
+pub const REFIT_OVERLAYS_EVENT: &str = "refit_overlays";
 
 /// Foreign-window drag watcher (windowmgr.rs → DragSnapLayer.tsx).
 pub const WIN_DRAG_START_EVENT: &str = "win_drag_start";
diff --git a/widgetsack/src/clickthrough.rs b/widgetsack/src/clickthrough.rs
index 6d9f7a8..19c2884 100644
--- a/widgetsack/src/clickthrough.rs
+++ b/widgetsack/src/clickthrough.rs
@@ -100,7 +100,7 @@ pub fn current_work_area(window: tauri::WebviewWindow) -> Result<ScreenRect, Str
 fn work_area_for(window: &tauri::WebviewWindow) -> Result<ScreenRect, String> {
     use windows::Win32::Foundation::POINT;
     use windows::Win32::Graphics::Gdi::{
-        GetMonitorInfoW, MonitorFromPoint, MONITORINFO, MONITOR_DEFAULTTONEAREST,
+        GetMonitorInfoW, MONITOR_DEFAULTTONEAREST, MONITORINFO, MonitorFromPoint,
     };
 
     let monitor = window
@@ -141,7 +141,10 @@ fn work_area_for(_window: &tauri::WebviewWindow) -> Result<ScreenRect, String> {
 /// surviving Show Desktop (the Wallpaper-Engine trick). When disabled, re-attach it to the
 /// desktop root so it's a normal top-level overlay again. Windows-only; a no-op error elsewhere.
 #[tauri::command]
-pub fn set_overlay_wallpaper(window: tauri::WebviewWindow, enabled: bool) -> Result<String, String> {
+pub fn set_overlay_wallpaper(
+    window: tauri::WebviewWindow,
+    enabled: bool,
+) -> Result<String, String> {
     set_wallpaper_parent(&window, enabled)
 }
 
@@ -149,7 +152,7 @@ pub fn set_overlay_wallpaper(window: tauri::WebviewWindow, enabled: bool) -> Res
 fn set_wallpaper_parent(window: &tauri::WebviewWindow, enabled: bool) -> Result<String, String> {
     use windows::Win32::Foundation::{HWND, LPARAM, WPARAM};
     use windows::Win32::UI::WindowsAndMessaging::{
-        EnumWindows, FindWindowW, SendMessageTimeoutW, SetParent, SMTO_NORMAL,
+        EnumWindows, FindWindowW, SMTO_NORMAL, SendMessageTimeoutW, SetParent,
     };
     use windows::core::w;
 
@@ -185,7 +188,10 @@ fn set_wallpaper_parent(window: &tauri::WebviewWindow, enabled: bool) -> Result<
     let mut worker = HWND::default();
     for attempt in 0..10 {
         unsafe {
-            let _ = EnumWindows(Some(enum_find_workerw), LPARAM(&mut worker as *mut HWND as isize));
+            let _ = EnumWindows(
+                Some(enum_find_workerw),
+                LPARAM(&mut worker as *mut HWND as isize),
+            );
         }
         if !worker.is_invalid() {
             break;
@@ -210,7 +216,7 @@ unsafe extern "system" fn enum_find_workerw(
 ) -> windows::core::BOOL {
     use windows::Win32::Foundation::{HWND, TRUE};
     use windows::Win32::UI::WindowsAndMessaging::FindWindowExW;
-    use windows::core::{w, BOOL};
+    use windows::core::{BOOL, w};
 
     let defview =
         unsafe { FindWindowExW(Some(top), None, w!("SHELLDLL_DefView"), None) }.unwrap_or_default();
diff --git a/widgetsack/src/command.rs b/widgetsack/src/command.rs
index 32ea52a..5553d5b 100644
--- a/widgetsack/src/command.rs
+++ b/widgetsack/src/command.rs
@@ -1,1498 +1,1549 @@
-use std::collections::HashMap;
-use std::fs;
-use std::path::{Path, PathBuf};
-
-use notify::Watcher;
-use serde::Serialize;
-use tauri::{Emitter, Manager};
-
-use crate::bridge::{CONTROLS_CHANGED_EVENT, LAYOUT_CHANGED_EVENT, THEMES_CHANGED_EVENT};
-use crate::{log, AppState, SessionRecord};
-
-#[derive(Serialize)]
-pub struct UpdateResponse {
-    pub sessions: HashMap<usize, SessionRecord>,
-}
-
-#[tauri::command]
-pub async fn get_initial_sessions(
-    _message: String,
-    state: tauri::State<'_, AppState>,
-    art: tauri::State<'_, crate::art::ArtState>,
-) -> Result<UpdateResponse, String> {
-    let sessions = state.sessions.lock().await;
-
-    let mut cloned: HashMap<usize, SessionRecord> = HashMap::new();
-    cloned.clone_from(&sessions);
-
-    // Re-register each session's cover so the URLs in this snapshot resolve for a just-booted
-    // overlay even if the live media events fired before its webview existed (art.rs).
-    for record in cloned.values() {
-        crate::art::note_record(&art, record);
-    }
-
-    Ok(UpdateResponse { sessions: cloned })
-}
-
-/// Path to the persisted widget layout (`widgets.json` in the app config dir).
-fn layout_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("widgets.json"))
-}
-
-/// Read the saved layout file, or `None` if it does not exist yet. The frontend
-/// validates/parses the contents (see core/layout.ts) so this stays dumb I/O.
-#[tauri::command]
-pub async fn load_layout(app: tauri::AppHandle) -> Result<Option<String>, String> {
-    let path = layout_path(&app)?;
-    match fs::read_to_string(&path) {
-        Ok(contents) => Ok(Some(contents)),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-/// Write the layout file, creating the config directory if needed.
-#[tauri::command]
-pub async fn save_layout(app: tauri::AppHandle, contents: String) -> Result<(), String> {
-    let path = layout_path(&app)?;
-    if let Some(parent) = path.parent() {
-        fs::create_dir_all(parent).map_err(|e| e.to_string())?;
-    }
-    fs::write(&path, contents).map_err(|e| e.to_string())
-}
-
-/// Path to the persisted control remaps (`controls.json` in the app config dir).
-fn controls_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("controls.json"))
-}
-
-/// Read the saved control overrides, or `None` if none saved yet. The frontend validates/parses
-/// the contents (core/controls.ts `parseControlOverrides`) so this stays dumb I/O — mirrors
-/// `load_layout`, and an absent/garbage file simply falls back to the code defaults.
-#[tauri::command]
-pub async fn load_controls(app: tauri::AppHandle) -> Result<Option<String>, String> {
-    let path = controls_path(&app)?;
-    match fs::read_to_string(&path) {
-        Ok(contents) => Ok(Some(contents)),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-/// Write the control overrides file, creating the config directory if needed.
-#[tauri::command]
-pub async fn save_controls(app: tauri::AppHandle, contents: String) -> Result<(), String> {
-    let path = controls_path(&app)?;
-    if let Some(parent) = path.parent() {
-        fs::create_dir_all(parent).map_err(|e| e.to_string())?;
-    }
-    fs::write(&path, contents).map_err(|e| e.to_string())
-}
-
-/// Open the webview devtools/inspector for the calling window (CSS development from the studio's
-/// context menu). `open_devtools` is available because tauri's `devtools` feature is enabled in
-/// Cargo.toml (it is also always available in debug builds).
-#[tauri::command]
-pub fn open_devtools(window: tauri::WebviewWindow) {
-    window.open_devtools();
-}
-
-// --- by-label window control (the Diagnostics panel's crash-recovery controls) -----------------------
-// These target ANOTHER window by label from the studio, driven entirely by the backend. That matters
-// because the per-window JS event bridge (lib/diag.ts) dies with the window's webview — when an overlay
-// OOM-crashes, its JS can no longer answer the poll or obey "open devtools / drop click-through", so the
-// crashed window vanishes from the list and stays an un-clickable, uninspectable click-through surface.
-// Routing these through the backend (the OS window object outlives the renderer) keeps a crashed overlay
-// listable, inspectable, and rescuable.
-
-/// Every live app window's label (`studio`, `main`, `overlay-1`, …). The Diagnostics panel uses this as
-/// the source of truth for which windows exist, so a window whose webview crashed (and therefore stopped
-/// reporting over the JS bridge) still appears — marked "not responding" — instead of silently dropping.
-#[tauri::command]
-pub fn list_window_labels(app: tauri::AppHandle) -> Vec<String> {
-    app.webview_windows().into_keys().collect()
-}
-
-/// Open devtools for the window with `label` (not necessarily the caller). Lets the studio inspect a
-/// crashed/passive overlay it could never reach through that overlay's own (dead) JS.
-#[tauri::command]
-pub fn open_devtools_for(app: tauri::AppHandle, label: String) {
-    if let Some(win) = app.get_webview_window(&label) {
-        win.open_devtools();
-    }
-}
-
-/// Toggle whole-window click-through for the window with `label`. `interactive = true` drops
-/// click-through (and brings the window forward so you can actually click it — e.g. a crashed overlay's
-/// "Reload" page); `false` restores it. No-op if the label is unknown.
-#[tauri::command]
-pub fn set_window_interactive(
-    app: tauri::AppHandle,
-    label: String,
-    interactive: bool,
-) -> Result<(), String> {
-    if let Some(win) = app.get_webview_window(&label) {
-        win.set_ignore_cursor_events(!interactive)
-            .map_err(|e| e.to_string())?;
-        if interactive {
-            let _ = win.show();
-            let _ = win.set_focus();
-        }
-    }
-    Ok(())
-}
-
-/// Make EVERY app window interactive again and bring it forward — the backend "panic button" for a
-/// window you can't reach: a click-through overlay, or one whose webview crashed so its own JS can no
-/// longer drop click-through. Best-effort per window; never panics. Shared by the rescue hotkey
-/// (main.rs) and the `rescue_windows` command, so it's generic over the runtime.
-pub fn rescue_all<R: tauri::Runtime>(app: &tauri::AppHandle<R>) {
-    for win in app.webview_windows().into_values() {
-        let _ = win.set_ignore_cursor_events(false);
-        let _ = win.unminimize();
-        let _ = win.show();
-        let _ = win.set_focus();
-    }
-}
-
-/// Command wrapper for [`rescue_all`] (the studio's "Rescue all windows" button).
-#[tauri::command]
-pub fn rescue_windows(app: tauri::AppHandle) {
-    rescue_all(&app);
-}
-
-/// Reload the webview of the window with `label` — respawns its renderer, recovering a crashed overlay
-/// (the WebView2 "Out of Memory" page) without relaunching the app. No-op if the label is unknown.
-#[tauri::command]
-pub fn reload_window(app: tauri::AppHandle, label: String) -> Result<(), String> {
-    if let Some(win) = app.get_webview_window(&label) {
-        win.reload().map_err(|e| e.to_string())?;
-    }
-    Ok(())
-}
-
-/// Append a window's diagnostics summary to the rotating log file (the memory TRAIL). Each window calls
-/// this on an interval (lib/diag.ts `startMemoryTrail`); because it lands on disk, the run-up to an
-/// unattended overnight OOM survives the crash — read the last `memtrail` lines to see which metric was
-/// climbing. Logged at info so it persists in release builds; the window label is attached as a field.
-#[tauri::command]
-pub fn log_diag(window: tauri::WebviewWindow, summary: String) {
-    log::info("memtrail", summary)
-        .field("window", window.label())
-        .emit();
-}
-
-#[derive(serde::Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct SystemFont {
-    /// Family name (CSS `font-family`).
-    pub name: String,
-    /// PostScript name (often a spaceless variant of the family).
-    pub font_name: String,
-    /// Absolute path to the font file (for the webview to @font-face via the asset protocol).
-    pub path: String,
-}
-
-/// Enumerate installed fonts (incl. PER-USER ones) with their file paths. Chromium's sandboxed
-/// webview won't render a per-user-installed font by name — but fontdb can find it here, and the
-/// frontend then loads the file directly via @font-face + the asset protocol (the approach of
-/// tauri-plugin-system-fonts, inlined). The per-user fonts dir is added explicitly (where Windows
-/// puts "install for me only" fonts).
-#[tauri::command]
-pub fn system_fonts() -> Vec<SystemFont> {
-    use fontdb::{Database, Source};
-    let mut db = Database::new();
-    db.load_system_fonts();
-    if let Ok(local) = std::env::var("LOCALAPPDATA") {
-        db.load_fonts_dir(std::path::Path::new(&local).join("Microsoft\\Windows\\Fonts"));
-    }
-    db.faces()
-        .filter_map(|f| match &f.source {
-            Source::File(path) => {
-                let name = f.families.first()?.0.clone();
-                if name.starts_with('.') {
-                    return None; // hidden/system aliases
-                }
-                Some(SystemFont {
-                    name,
-                    font_name: f.post_script_name.clone(),
-                    path: path.to_string_lossy().into_owned(),
-                })
-            }
-            _ => None,
-        })
-        .collect()
-}
-
-// ---- themes (Phase 7c): a `themes/<name>.css` plugin folder in the app config dir ----
-
-fn themes_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("themes"))
-}
-
-/// Write `contents` to `path` atomically: write a sibling temp file, then rename it onto the target
-/// (a rename is atomic on the same volume), so a concurrent reader — or a crash mid-write — never
-/// sees a truncated/partial file. The temp name keeps the original and appends `.tmp`, so its
-/// extension is `tmp` (not `css`/`json`) and the directory watchers, which filter by extension,
-/// ignore it. Best-effort cleanup of the temp file on failure.
-fn atomic_write(path: &Path, contents: &str) -> Result<(), String> {
-    let file_name = path
-        .file_name()
-        .and_then(|s| s.to_str())
-        .ok_or_else(|| "write path has no file name".to_string())?;
-    let mut tmp = path.to_path_buf();
-    tmp.set_file_name(format!("{file_name}.tmp"));
-    if let Err(err) = fs::write(&tmp, contents) {
-        let _ = fs::remove_file(&tmp);
-        return Err(err.to_string());
-    }
-    fs::rename(&tmp, path).map_err(|e| {
-        let _ = fs::remove_file(&tmp);
-        e.to_string()
-    })
-}
-
-/// The theme names (file stems of `themes/*.css`), sorted. The frontend adds a synthetic
-/// "(default)" option (no theme = the meters' token fallbacks).
-#[tauri::command]
-pub fn list_themes(app: tauri::AppHandle) -> Result<Vec<String>, String> {
-    let dir = themes_dir(&app)?;
-    let mut names = Vec::new();
-    if let Ok(entries) = fs::read_dir(&dir) {
-        for entry in entries.flatten() {
-            let path = entry.path();
-            if path.extension().and_then(|x| x.to_str()) == Some("css")
-                && let Some(stem) = path.file_stem().and_then(|s| s.to_str())
-            {
-                names.push(stem.to_string());
-            }
-        }
-    }
-    names.sort();
-    Ok(names)
-}
-
-/// The CSS of theme `name` (a bare file stem), or `None` if it doesn't exist.
-#[tauri::command]
-pub fn load_theme(app: tauri::AppHandle, name: String) -> Result<Option<String>, String> {
-    if !valid_name(&name) {
-        return Err("invalid theme name".to_string());
-    }
-    let path = themes_dir(&app)?.join(format!("{name}.css"));
-    match fs::read_to_string(&path) {
-        Ok(contents) => Ok(Some(contents)),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-/// Write theme `name` (used by the studio's theme editor + token panel, Phase 7d). Creates
-/// `themes/`. Atomic (temp + rename) so a concurrent overlay reload never reads a half-written file.
-#[tauri::command]
-pub fn save_theme(app: tauri::AppHandle, name: String, contents: String) -> Result<(), String> {
-    if !valid_name(&name) {
-        return Err("invalid theme name".to_string());
-    }
-    let dir = themes_dir(&app)?;
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    atomic_write(&dir.join(format!("{name}.css")), &contents)
-}
-
-/// Delete theme `name` → removes `themes/<name>.css`. Ok even if it's already gone (idempotent),
-/// mirroring `delete_layout`. The themes watcher then emits `themes_changed` so the picker refreshes.
-#[tauri::command]
-pub fn delete_theme(app: tauri::AppHandle, name: String) -> Result<(), String> {
-    if !valid_name(&name) {
-        return Err("invalid theme name".to_string());
-    }
-    let path = themes_dir(&app)?.join(format!("{name}.css"));
-    match fs::remove_file(&path) {
-        Ok(()) => Ok(()),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-// ---- wallpapers: media for the per-monitor full-screen background layer ----
-// Same "dumb I/O to a fixed folder, no native picker" pattern as themes/sacks: the user drops image
-// or video files into `<app config>/wallpapers/` (already inside the asset-protocol scope, so the
-// webview can load them), and the studio lists them for the Background section. `BackgroundSpec.src`
-// stores the bare filename; the frontend resolves it to an asset URL via `wallpaper_path`.
-
-fn wallpapers_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("wallpapers"))
-}
-
-// Image/video extensions the webview can render (the picker shows only these).
-const WALLPAPER_EXTS: &[&str] = &[
-    "png", "jpg", "jpeg", "gif", "webp", "bmp", "avif", "mp4", "webm", "mkv", "mov", "m4v",
-];
-
-/// A wallpaper filename is a single path component with a media extension. Rejects separators / `..`
-/// (path traversal) but — unlike `valid_name` — ALLOWS the extension dot.
-fn valid_wallpaper_name(name: &str) -> bool {
-    !name.is_empty()
-        && name.len() <= 128
-        && !name.contains('/')
-        && !name.contains('\\')
-        && !name.contains("..")
-        && std::path::Path::new(name)
-            .extension()
-            .and_then(|x| x.to_str())
-            .map(|e| WALLPAPER_EXTS.contains(&e.to_ascii_lowercase().as_str()))
-            .unwrap_or(false)
-}
-
-/// The media filenames in `wallpapers/` (image + video only), sorted. Creates the folder so the
-/// studio's "open folder" button always has somewhere to point.
-#[tauri::command]
-pub fn list_wallpapers(app: tauri::AppHandle) -> Result<Vec<String>, String> {
-    let dir = wallpapers_dir(&app)?;
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    let mut names = Vec::new();
-    if let Ok(entries) = fs::read_dir(&dir) {
-        for entry in entries.flatten() {
-            if let Some(name) = entry.file_name().to_str()
-                && valid_wallpaper_name(name)
-            {
-                names.push(name.to_string());
-            }
-        }
-    }
-    names.sort();
-    Ok(names)
-}
-
-/// The absolute path of wallpaper `name`, for the frontend to feed `convertFileSrc`. Validates the
-/// name (no traversal); returns the path even if the file is missing (the <img>/<video> just won't
-/// load), so the caller doesn't have to special-case a not-yet-present file.
-#[tauri::command]
-pub fn wallpaper_path(app: tauri::AppHandle, name: String) -> Result<String, String> {
-    if !valid_wallpaper_name(&name) {
-        return Err("invalid wallpaper name".to_string());
-    }
-    Ok(wallpapers_dir(&app)?
-        .join(name)
-        .to_string_lossy()
-        .into_owned())
-}
-
-/// Open the `wallpapers/` folder in Explorer so the user can drop media in. Creates it first.
-#[tauri::command]
-pub fn open_wallpapers_dir(app: tauri::AppHandle) -> Result<(), String> {
-    let dir = wallpapers_dir(&app)?;
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    std::process::Command::new("explorer")
-        .arg(&dir)
-        .spawn()
-        .map_err(|e| e.to_string())?;
-    Ok(())
-}
-
-// ---- sacks: shareable bundles (`sacks/<name>.sack.json` in the app config dir) ----
-// A "sack" packs the widget library + active theme CSS + token overrides as one JSON file so a
-// user can share/reuse a set. Dumb I/O to a fixed folder (no native file picker); the frontend
-// owns the format + merge logic (core/sack.ts).
-
-fn sacks_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("sacks"))
-}
-
-/// Shared filename allowlist for user-named config files (themes, sacks). The name becomes a
-/// path segment, so it must be a safe, bounded token: 1–64 chars of `[A-Za-z0-9 _-]` only. This
-/// rejects control chars, path separators, `..`, and Windows-reserved characters by construction;
-/// the explicit empty/`..`/separator checks below are kept as a defensive backstop. Leading/trailing
-/// spaces are rejected too — Windows silently trims trailing spaces/dots from filenames, so `"a "`
-/// and `"a"` would collide on disk and a delete-by-name could miss.
-fn valid_name(name: &str) -> bool {
-    !name.is_empty()
-        && name == name.trim()
-        && !name.contains('/')
-        && !name.contains('\\')
-        && !name.contains("..")
-        && name.len() <= 64
-        && name
-            .chars()
-            .all(|c| c.is_ascii_alphanumeric() || c == ' ' || c == '_' || c == '-')
-}
-
-fn valid_sack_name(name: &str) -> bool {
-    valid_name(name)
-}
-
-/// The sack names (file stems of `sacks/*.sack.json`), sorted.
-#[tauri::command]
-pub fn list_sacks(app: tauri::AppHandle) -> Result<Vec<String>, String> {
-    let dir = sacks_dir(&app)?;
-    let mut names = Vec::new();
-    if let Ok(entries) = fs::read_dir(&dir) {
-        for entry in entries.flatten() {
-            let path = entry.path();
-            if let Some(file) = path.file_name().and_then(|s| s.to_str())
-                && let Some(stem) = file.strip_suffix(".sack.json")
-            {
-                names.push(stem.to_string());
-            }
-        }
-    }
-    names.sort();
-    Ok(names)
-}
-
-/// The JSON of sack `name`, or `None` if it doesn't exist. The frontend parses/validates it.
-#[tauri::command]
-pub fn read_sack(app: tauri::AppHandle, name: String) -> Result<Option<String>, String> {
-    if !valid_sack_name(&name) {
-        return Err("invalid sack name".to_string());
-    }
-    let path = sacks_dir(&app)?.join(format!("{name}.sack.json"));
-    match fs::read_to_string(&path) {
-        Ok(contents) => Ok(Some(contents)),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-/// Write sack `name` (creates `sacks/`). Returns the absolute path written, for the UI to show.
-#[tauri::command]
-pub fn write_sack(app: tauri::AppHandle, name: String, contents: String) -> Result<String, String> {
-    if !valid_sack_name(&name) {
-        return Err("invalid sack name".to_string());
-    }
-    let dir = sacks_dir(&app)?;
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    let path = dir.join(format!("{name}.sack.json"));
-    fs::write(&path, contents).map_err(|e| e.to_string())?;
-    Ok(path.to_string_lossy().into_owned())
-}
-
-// ---- saved layouts: named layout profiles (`layouts/<name>.layout.json` in the app config dir) ----
-// A saved layout is one monitor's arrangement (root tree + floating widgets) the user can name, list,
-// load back, and delete from the studio. Dumb I/O to a fixed folder (same shape as sacks/themes); the
-// frontend owns the JSON format + the load/replace logic (core/savedLayout.ts).
-
-fn layouts_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("layouts"))
-}
-
-/// The saved-layout names (file stems of `layouts/*.layout.json`), sorted.
-#[tauri::command]
-pub fn list_layouts(app: tauri::AppHandle) -> Result<Vec<String>, String> {
-    let dir = layouts_dir(&app)?;
-    let mut names = Vec::new();
-    if let Ok(entries) = fs::read_dir(&dir) {
-        for entry in entries.flatten() {
-            let path = entry.path();
-            if let Some(file) = path.file_name().and_then(|s| s.to_str())
-                && let Some(stem) = file.strip_suffix(".layout.json")
-            {
-                names.push(stem.to_string());
-            }
-        }
-    }
-    names.sort();
-    Ok(names)
-}
-
-/// The JSON of saved layout `name`, or `None` if it doesn't exist. The frontend parses/validates it.
-#[tauri::command]
-pub fn read_layout(app: tauri::AppHandle, name: String) -> Result<Option<String>, String> {
-    if !valid_name(&name) {
-        return Err("invalid layout name".to_string());
-    }
-    let path = layouts_dir(&app)?.join(format!("{name}.layout.json"));
-    match fs::read_to_string(&path) {
-        Ok(contents) => Ok(Some(contents)),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-/// Write saved layout `name` (creates `layouts/`). Returns the absolute path written.
-#[tauri::command]
-pub fn save_layout_as(app: tauri::AppHandle, name: String, contents: String) -> Result<String, String> {
-    if !valid_name(&name) {
-        return Err("invalid layout name".to_string());
-    }
-    let dir = layouts_dir(&app)?;
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    let path = dir.join(format!("{name}.layout.json"));
-    fs::write(&path, contents).map_err(|e| e.to_string())?;
-    Ok(path.to_string_lossy().into_owned())
-}
-
-/// Delete saved layout `name`. Ok even if it's already gone (idempotent).
-#[tauri::command]
-pub fn delete_layout(app: tauri::AppHandle, name: String) -> Result<(), String> {
-    if !valid_name(&name) {
-        return Err("invalid layout name".to_string());
-    }
-    let path = layouts_dir(&app)?.join(format!("{name}.layout.json"));
-    match fs::remove_file(&path) {
-        Ok(()) => Ok(()),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-// ---- plugin packages: declarative third-party bundles (`plugins/<id>/plugin.json`) ----
-// The app-config `plugins/` dir already holds first-party config FILES (ha.json, llm.json, …);
-// a third-party package is a SUBDIRECTORY containing a `plugin.json`, so the two coexist
-// unambiguously — only directories with a manifest are listed. Dumb I/O only: the frontend
-// parses/validates the manifest (core/pluginPackage.ts) and decides what to register.
-
-fn plugins_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
-    let dir = app.path().app_config_dir().map_err(|e| e.to_string())?;
-    Ok(dir.join("plugins"))
-}
-
-/// A package asset filename is a single path component: `<valid_name stem>.<css|json|js>` (`.js`
-/// is a Phase 2 sandboxed source script — it is only ever TEXT to the backend). Splitting at the
-/// LAST dot and running the stem through `valid_name` rejects separators, `..`, extra dots
-/// (so no `x.css.tmp` smuggling), and oversized names by construction.
-fn valid_asset_name(name: &str) -> bool {
-    match name.rsplit_once('.') {
-        Some((stem, ext)) => {
-            (ext.eq_ignore_ascii_case("css")
-                || ext.eq_ignore_ascii_case("json")
-                || ext.eq_ignore_ascii_case("js"))
-                && valid_name(stem)
-        }
-        None => false,
-    }
-}
-
-#[derive(Serialize)]
-pub struct PluginPackageFile {
-    /// The package directory name (its id; the frontend cross-checks the manifest's `id`).
-    pub id: String,
-    /// Raw `plugin.json` contents, unparsed.
-    pub manifest: String,
-    /// Raw `.install.json` sidecar (written by `install_plugin_package`), unparsed — the frontend
-    /// parses it (core/pluginPackage.ts `parseInstallSidecar`) to show provenance and drive the
-    /// update-check/update affordances. `None` for hand-dropped (local) packages.
-    pub install: Option<String>,
-}
-
-/// Every `plugins/<id>/plugin.json`, sorted by id. Directories only (first-party config FILES in
-/// `plugins/` are skipped), ids must pass `valid_name` (they become path segments in
-/// `read_plugin_package_asset`). Missing `plugins/` dir → empty vec.
-#[tauri::command]
-pub fn list_plugin_packages(app: tauri::AppHandle) -> Result<Vec<PluginPackageFile>, String> {
-    let dir = plugins_dir(&app)?;
-    let mut out = Vec::new();
-    if let Ok(entries) = fs::read_dir(&dir) {
-        for entry in entries.flatten() {
-            let path = entry.path();
-            if !path.is_dir() {
-                continue;
-            }
-            let Some(id) = path.file_name().and_then(|s| s.to_str()) else {
-                continue;
-            };
-            if !valid_name(id) {
-                continue;
-            }
-            if let Ok(manifest) = fs::read_to_string(path.join("plugin.json")) {
-                out.push(PluginPackageFile {
-                    id: id.to_string(),
-                    manifest,
-                    install: fs::read_to_string(path.join(INSTALL_SIDECAR)).ok(),
-                });
-            }
-        }
-    }
-    out.sort_by(|a, b| a.id.cmp(&b.id));
-    Ok(out)
-}
-
-/// Read `plugins/<id>/<name>` — a manifest-declared asset (theme CSS / extra JSON). Both segments
-/// are sanitized (no traversal); only `.css`/`.json` files are readable. `None` if absent.
-#[tauri::command]
-pub fn read_plugin_package_asset(
-    app: tauri::AppHandle,
-    id: String,
-    name: String,
-) -> Result<Option<String>, String> {
-    if !valid_name(&id) {
-        return Err("invalid package id".to_string());
-    }
-    if !valid_asset_name(&name) {
-        return Err("invalid asset name".to_string());
-    }
-    let path = plugins_dir(&app)?.join(&id).join(&name);
-    match fs::read_to_string(&path) {
-        Ok(contents) => Ok(Some(contents)),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-// ---- plugin packages: remote install (Phase 3) -------------------------------------------------
-// Install a package straight from a GitHub link (or any https URL to a plugin.json): fetch the
-// manifest + its declared assets over https (10s timeout, 256 KiB per-file cap), write them into
-// `plugins/<id>/` via atomic_write, and record provenance in a `.install.json` sidecar so the
-// frontend can offer MANUAL update checks later. Validation stays split exactly like Phase 1: the
-// backend only enforces the path-safety invariants (`valid_name` id, `valid_asset_name` assets);
-// the frontend does the full structural validation and the enable/consent gate — a freshly
-// installed package lands DISABLED like a hand-dropped folder.
-
-/// Provenance sidecar filename. Starts with a dot so its stem fails `valid_name`, which keeps it
-/// out of `read_plugin_package_asset`'s reachable set and out of any manifest's declarable assets.
-const INSTALL_SIDECAR: &str = ".install.json";
-
-/// Per-file download cap (manifest and each asset) — a plugin.json is a few KiB, a theme CSS tens.
-const FETCH_CAP: usize = 256 * 1024;
-
-/// A resolved install source: where the manifest lives, plus what the sidecar should record.
-#[derive(Debug, PartialEq)]
-struct ResolvedSource {
-    /// Direct https URL of the `plugin.json` to GET.
-    manifest_url: String,
-    /// What the sidecar stores as `source`: `owner/repo` for GitHub forms, the URL itself for
-    /// direct links. Paired with `reff`, it's enough to re-derive `manifest_url` at update time.
-    display_source: String,
-    /// Git ref for GitHub forms (`main` unless a `/tree/<ref>` URL pinned one); `direct` for a
-    /// verbatim plugin.json URL.
-    reff: String,
-}
-
-/// One GitHub owner/repo path segment: ASCII alphanumeric plus `-`/`_`/`.`, no `..`, bounded.
-fn gh_token(s: &str) -> bool {
-    !s.is_empty()
-        && s.len() <= 100
-        && !s.contains("..")
-        && s.chars()
-            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')
-}
-
-/// A git ref as it may appear in a `/tree/<ref>` URL: like `gh_token` but slashes are allowed
-/// (branch names such as `feature/x`), `..` still rejected.
-fn valid_ref(s: &str) -> bool {
-    !s.is_empty()
-        && s.len() <= 200
-        && !s.contains("..")
-        && s.chars()
-            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.' || c == '/')
-}
-
-fn raw_manifest_url(owner: &str, repo: &str, reff: &str) -> String {
-    format!("https://raw.githubusercontent.com/{owner}/{repo}/{reff}/plugin.json")
-}
-
-/// PURE SEAM: turn the user's install input into a manifest URL + sidecar provenance. Accepted
-/// forms (anything else → `None`; plain `http://` is rejected outright — https only):
-///
-/// | input                                        | manifest_url                                              | ref      |
-/// |----------------------------------------------|-----------------------------------------------------------|----------|
-/// | `owner/repo`                                 | `https://raw.githubusercontent.com/owner/repo/main/plugin.json`  | `main`   |
-/// | `https://github.com/owner/repo[/]`           | same as above                                             | `main`   |
-/// | `https://github.com/owner/repo/tree/<ref>`   | `…/owner/repo/<ref>/plugin.json`                          | `<ref>`  |
-/// | any https URL ending in `/plugin.json`       | used verbatim                                             | `direct` |
-fn resolve_package_source(input: &str) -> Option<ResolvedSource> {
-    let input = input.trim().trim_end_matches('/');
-    if let Some(rest) = input.strip_prefix("https://") {
-        if let Some(path) = rest.strip_prefix("github.com/") {
-            // splitn(4): segment 4 keeps any remaining slashes — that's the (slash-friendly) ref.
-            let parts: Vec<&str> = path.splitn(4, '/').collect();
-            return match parts.as_slice() {
-                [owner, repo] if gh_token(owner) && gh_token(repo) => Some(ResolvedSource {
-                    manifest_url: raw_manifest_url(owner, repo, "main"),
-                    display_source: format!("{owner}/{repo}"),
-                    reff: "main".to_string(),
-                }),
-                [owner, repo, "tree", reff]
-                    if gh_token(owner) && gh_token(repo) && valid_ref(reff) =>
-                {
-                    Some(ResolvedSource {
-                        manifest_url: raw_manifest_url(owner, repo, reff),
-                        display_source: format!("{owner}/{repo}"),
-                        reff: reff.to_string(),
-                    })
-                }
-                _ => None,
-            };
-        }
-        if input.ends_with("/plugin.json") {
-            return Some(ResolvedSource {
-                manifest_url: input.to_string(),
-                display_source: input.to_string(),
-                reff: "direct".to_string(),
-            });
-        }
-        return None;
-    }
-    // `owner/repo` shorthand — exactly one slash, both segments GitHub-safe, no scheme at all.
-    if input.contains("://") {
-        return None;
-    }
-    let (owner, repo) = input.split_once('/')?;
-    if gh_token(owner) && gh_token(repo) && !repo.contains('/') {
-        return Some(ResolvedSource {
-            manifest_url: raw_manifest_url(owner, repo, "main"),
-            display_source: format!("{owner}/{repo}"),
-            reff: "main".to_string(),
-        });
-    }
-    None
-}
-
-/// PURE SEAM: a declared asset lives next to its manifest — swap the URL's last segment.
-fn asset_url_for(manifest_url: &str, asset_name: &str) -> String {
-    match manifest_url.rsplit_once('/') {
-        Some((base, _)) => format!("{base}/{asset_name}"),
-        None => asset_name.to_string(),
-    }
-}
-
-/// PURE SEAM: re-derive the manifest URL from sidecar provenance (`source` + `ref`) for update
-/// checks / re-installs. `direct` sources re-run through `resolve_package_source` so a tampered
-/// sidecar can't smuggle a non-https or non-plugin.json URL back in.
-fn manifest_url_from_sidecar(source: &str, reff: &str) -> Option<String> {
-    if reff == "direct" {
-        let resolved = resolve_package_source(source)?;
-        return (resolved.reff == "direct").then_some(resolved.manifest_url);
-    }
-    let (owner, repo) = source.split_once('/')?;
-    if gh_token(owner) && gh_token(repo) && !repo.contains('/') && valid_ref(reff) {
-        Some(raw_manifest_url(owner, repo, reff))
-    } else {
-        None
-    }
-}
-
-/// A 10s-timeout https client for the (small) manifest/asset fetches.
-fn install_http_client() -> Result<reqwest::Client, String> {
-    reqwest::Client::builder()
-        .timeout(std::time::Duration::from_secs(10))
-        .build()
-        .map_err(|e| e.to_string())
-}
-
-/// GET `url` and return its body as text, enforcing `FETCH_CAP` while streaming (a hostile or
-/// misconfigured server can't make us buffer an unbounded body).
-async fn fetch_text_capped(client: &reqwest::Client, url: &str) -> Result<String, String> {
-    use futures_util::StreamExt;
-    let resp = client
-        .get(url)
-        .send()
-        .await
-        .map_err(|e| format!("GET {url} failed: {e}"))?;
-    if !resp.status().is_success() {
-        return Err(format!("GET {url} failed: HTTP {}", resp.status()));
-    }
-    if let Some(len) = resp.content_length()
-        && len > FETCH_CAP as u64
-    {
-        return Err(format!("{url} is too large ({len} bytes; cap {FETCH_CAP})"));
-    }
-    let mut buf: Vec<u8> = Vec::new();
-    let mut stream = resp.bytes_stream();
-    while let Some(chunk) = stream.next().await {
-        let bytes = chunk.map_err(|e| format!("GET {url} failed mid-body: {e}"))?;
-        if buf.len() + bytes.len() > FETCH_CAP {
-            return Err(format!("{url} exceeded the {FETCH_CAP}-byte download cap"));
-        }
-        buf.extend_from_slice(&bytes);
-    }
-    String::from_utf8(buf).map_err(|_| format!("{url} is not valid UTF-8"))
-}
-
-/// GitHub releases API for the app's own repo — the manual "check for updates" source (the app
-/// ships no auto-updater, so this just tells the user a newer release exists).
-const GITHUB_LATEST_RELEASE_API: &str =
-    "https://api.github.com/repos/gyng/widgetsack/releases/latest";
-const RELEASES_PAGE: &str = "https://github.com/gyng/widgetsack/releases";
-
-#[derive(Serialize)]
-pub struct AppUpdate {
-    pub current: String,
-    pub latest: String,
-    pub url: String,
-    pub update_available: bool,
-}
-
-/// Parse an `X.Y.Z` version into a comparable tuple, tolerating a leading `v` and a `-pre`/`+build`
-/// suffix; any missing or non-numeric part is 0 so a malformed tag never falsely reports an update.
-fn parse_version(v: &str) -> (u32, u32, u32) {
-    let core = v.trim().trim_start_matches('v');
-    let core = core.split(['-', '+']).next().unwrap_or(core);
-    let mut parts = core.split('.').map(|p| p.parse::<u32>().unwrap_or(0));
-    (
-        parts.next().unwrap_or(0),
-        parts.next().unwrap_or(0),
-        parts.next().unwrap_or(0),
-    )
-}
-
-/// Whether `latest` is a newer version than `current` (numeric X.Y.Z compare). Pure seam.
-fn version_is_newer(latest: &str, current: &str) -> bool {
-    parse_version(latest) > parse_version(current)
-}
-
-/// Ask GitHub for the latest published release of the app and compare it to the running version.
-/// Manual (driven by the About panel button); best-effort — any network/parse failure is returned
-/// as an `Err` the UI shows verbatim. The GitHub REST API requires a User-Agent.
-#[tauri::command]
-pub async fn check_app_update(app: tauri::AppHandle) -> Result<AppUpdate, String> {
-    let current = app.package_info().version.to_string();
-    let client = install_http_client()?;
-    let resp = client
-        .get(GITHUB_LATEST_RELEASE_API)
-        .header(reqwest::header::USER_AGENT, "widgetsack")
-        .header(reqwest::header::ACCEPT, "application/vnd.github+json")
-        .send()
-        .await
-        .map_err(|e| format!("update check failed: {e}"))?;
-    if !resp.status().is_success() {
-        return Err(format!("update check failed: HTTP {}", resp.status()));
-    }
-    let json: serde_json::Value = resp
-        .json()
-        .await
-        .map_err(|e| format!("update check failed: {e}"))?;
-    let latest = json
-        .get("tag_name")
-        .and_then(|v| v.as_str())
-        .ok_or("update check failed: no tag_name in latest release")?
-        .trim_start_matches('v')
-        .to_string();
-    let url = json
-        .get("html_url")
-        .and_then(|v| v.as_str())
-        .unwrap_or(RELEASES_PAGE)
-        .to_string();
-    let update_available = version_is_newer(&latest, &current);
-    Ok(AppUpdate {
-        current,
-        latest,
-        url,
-        update_available,
-    })
-}
-
-#[derive(Serialize)]
-pub struct InstalledPackage {
-    pub id: String,
-    pub version: String,
-}
-
-/// Install (or re-install — that IS the update path) a package from `source` (see
-/// `resolve_package_source` for the accepted forms). Fetches the manifest, minimally reads
-/// `id`/`version`/`theme.file` (full validation stays in the frontend), fetches every declared
-/// asset, and only THEN writes — a failed download never leaves a half-installed directory.
-#[tauri::command]
-pub async fn install_plugin_package(
-    app: tauri::AppHandle,
-    source: String,
-) -> Result<InstalledPackage, String> {
-    let resolved = resolve_package_source(&source).ok_or_else(|| {
-        "unrecognized source — use owner/repo, a github.com repo URL, or an https URL ending in /plugin.json"
-            .to_string()
-    })?;
-    let client = install_http_client()?;
-    let manifest_text = fetch_text_capped(&client, &resolved.manifest_url).await?;
-    let json: serde_json::Value = serde_json::from_str(&manifest_text)
-        .map_err(|_| "downloaded plugin.json is not valid JSON".to_string())?;
-    let id = json
-        .get("id")
-        .and_then(|v| v.as_str())
-        .unwrap_or_default()
-        .to_string();
-    if !valid_name(&id) {
-        return Err("manifest \"id\" is missing or not a safe folder name".to_string());
-    }
-    let version = json
-        .get("version")
-        .and_then(|v| v.as_str())
-        .unwrap_or_default()
-        .trim()
-        .to_string();
-    if version.is_empty() {
-        return Err("manifest has no \"version\"".to_string());
-    }
-    // Declared assets: `theme.file` (Phase 1) and `source.file` (Phase 2 sandbox script) are the
-    // only asset slots in manifestVersion 1. Fetch before writing anything.
-    let mut assets: Vec<(String, String)> = Vec::new();
-    for pointer in ["/theme/file", "/source/file"] {
-        if let Some(file) = json.pointer(pointer).and_then(|v| v.as_str()) {
-            if !valid_asset_name(file) {
-                return Err(format!("declared asset \"{file}\" has an unsafe filename"));
-            }
-            let body =
-                fetch_text_capped(&client, &asset_url_for(&resolved.manifest_url, file)).await?;
-            assets.push((file.to_string(), body));
-        }
-    }
-    let dir = plugins_dir(&app)?.join(&id);
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    atomic_write(&dir.join("plugin.json"), &manifest_text)?;
-    for (name, body) in &assets {
-        atomic_write(&dir.join(name), body)?;
-    }
-    let installed_at = std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .map(|d| d.as_millis() as u64)
-        .unwrap_or(0);
-    let sidecar = serde_json::json!({
-        "source": resolved.display_source,
-        "ref": resolved.reff,
-        "version": version,
-        "installedAt": installed_at,
-    });
-    atomic_write(&dir.join(INSTALL_SIDECAR), &sidecar.to_string())?;
-    Ok(InstalledPackage { id, version })
-}
-
-#[derive(Serialize)]
-pub struct UpdateCheck {
-    pub current: String,
-    pub latest: String,
-    pub source: String,
-}
-
-/// MANUAL update check for an installed package: re-fetch just the manifest from the sidecar's
-/// recorded source and report both versions (the frontend compares — any difference counts as
-/// "update available"; downgrades are deliberate re-installs). Packages without a sidecar
-/// (hand-dropped folders) have nowhere to check against.
-#[tauri::command]
-pub async fn check_plugin_package_update(
-    app: tauri::AppHandle,
-    id: String,
-) -> Result<UpdateCheck, String> {
-    if !valid_name(&id) {
-        return Err("invalid package id".to_string());
-    }
-    let raw = fs::read_to_string(plugins_dir(&app)?.join(&id).join(INSTALL_SIDECAR))
-        .map_err(|_| "package was not installed from a URL".to_string())?;
-    let side: serde_json::Value =
-        serde_json::from_str(&raw).map_err(|_| "install record is corrupt".to_string())?;
-    let source = side
-        .get("source")
-        .and_then(|v| v.as_str())
-        .unwrap_or_default()
-        .to_string();
-    let reff = side.get("ref").and_then(|v| v.as_str()).unwrap_or("main");
-    let current = side
-        .get("version")
-        .and_then(|v| v.as_str())
-        .unwrap_or_default()
-        .to_string();
-    let url = manifest_url_from_sidecar(&source, reff)
-        .ok_or_else(|| "install record has an invalid source".to_string())?;
-    let client = install_http_client()?;
-    let manifest_text = fetch_text_capped(&client, &url).await?;
-    let json: serde_json::Value = serde_json::from_str(&manifest_text)
-        .map_err(|_| "remote plugin.json is not valid JSON".to_string())?;
-    let latest = json
-        .get("version")
-        .and_then(|v| v.as_str())
-        .unwrap_or_default()
-        .trim()
-        .to_string();
-    if latest.is_empty() {
-        return Err("remote manifest has no \"version\"".to_string());
-    }
-    Ok(UpdateCheck {
-        current,
-        latest,
-        source,
-    })
-}
-
-/// Delete `plugins/<id>/` (works for installed AND hand-dropped packages — it's just a dir
-/// delete). Ok even if it's already gone (idempotent, like the other deletes here).
-#[tauri::command]
-pub fn remove_plugin_package(app: tauri::AppHandle, id: String) -> Result<(), String> {
-    if !valid_name(&id) {
-        return Err("invalid package id".to_string());
-    }
-    match fs::remove_dir_all(plugins_dir(&app)?.join(&id)) {
-        Ok(()) => Ok(()),
-        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
-        Err(err) => Err(err.to_string()),
-    }
-}
-
-// ---- plugin packages: sandboxed source network proxy (Phase 2) ----------------------------------
-// A package's `source.js` runs in a QuickJS sandbox with ZERO capabilities; the frontend asks this
-// command to perform each fetch between the sandbox's two pure calls. The hosts allowlist is
-// re-read from the manifest ON DISK per request (server-side enforcement — a compromised webview
-// can't widen it), https only, GET only, redirects DISABLED (so the response host can never drift
-// off-allowlist), 10s timeout, 256 KiB body cap.
-
-/// PURE SEAM: is `url` an https URL whose host is a DOMAIN matching one of `hosts` exactly?
-/// Subdomains must be listed explicitly; IP literals, explicit ports, embedded credentials, and
-/// non-https schemes all fail. Comparison is ASCII-case-insensitive (URL hosts parse lowercased,
-/// but the manifest on disk is untrusted text).
-fn host_allowed(url: &str, hosts: &[String]) -> bool {
-    let Ok(u) = reqwest::Url::parse(url) else {
-        return false;
-    };
-    if u.scheme() != "https" || u.port().is_some() {
-        return false;
-    }
-    if !u.username().is_empty() || u.password().is_some() {
-        return false;
-    }
-    match u.domain() {
-        Some(d) => hosts.iter().any(|h| h.eq_ignore_ascii_case(d)),
-        None => false, // IP literal (or no host at all)
-    }
-}
-
-#[derive(Serialize)]
-pub struct PackageFetchResponse {
-    pub url: String,
-    pub status: u16,
-    pub body: String,
-}
-
-/// GET `url` on behalf of package `id`'s sandboxed source. Non-2xx responses are returned (with
-/// their status) rather than erroring — the sandbox's `transform` decides what a miss means; only
-/// transport/validation failures are `Err`.
-#[tauri::command]
-pub async fn package_fetch(
-    app: tauri::AppHandle,
-    id: String,
-    url: String,
-) -> Result<PackageFetchResponse, String> {
-    if !valid_name(&id) {
-        return Err("invalid package id".to_string());
-    }
-    let raw = fs::read_to_string(plugins_dir(&app)?.join(&id).join("plugin.json"))
-        .map_err(|_| "package manifest not found".to_string())?;
-    let json: serde_json::Value = serde_json::from_str(&raw)
-        .map_err(|_| "package manifest is not valid JSON".to_string())?;
-    let hosts: Vec<String> = json
-        .pointer("/source/hosts")
-        .and_then(|v| v.as_array())
-        .map(|a| {
-            a.iter()
-                .filter_map(|x| x.as_str().map(str::to_string))
-                .collect()
-        })
-        .unwrap_or_default();
-    if hosts.is_empty() {
-        return Err("package declares no source hosts".to_string());
-    }
-    if !host_allowed(&url, &hosts) {
-        return Err(format!("url is not in the package's host allowlist: {url}"));
-    }
-    let client = reqwest::Client::builder()
-        .redirect(reqwest::redirect::Policy::none())
-        .timeout(std::time::Duration::from_secs(10))
-        .build()
-        .map_err(|e| e.to_string())?;
-    let resp = client
-        .get(&url)
-        .send()
-        .await
-        .map_err(|e| format!("GET {url} failed: {e}"))?;
-    let status = resp.status().as_u16();
-    if let Some(len) = resp.content_length()
-        && len > FETCH_CAP as u64
-    {
-        return Err(format!("{url} is too large ({len} bytes; cap {FETCH_CAP})"));
-    }
-    use futures_util::StreamExt;
-    let mut buf: Vec<u8> = Vec::new();
-    let mut stream = resp.bytes_stream();
-    while let Some(chunk) = stream.next().await {
-        let bytes = chunk.map_err(|e| format!("GET {url} failed mid-body: {e}"))?;
-        if buf.len() + bytes.len() > FETCH_CAP {
-            return Err(format!("{url} exceeded the {FETCH_CAP}-byte download cap"));
-        }
-        buf.extend_from_slice(&bytes);
-    }
-    let body = String::from_utf8(buf).map_err(|_| format!("{url} body is not valid UTF-8"))?;
-    Ok(PackageFetchResponse { url, status, body })
-}
-
-/// Seed a couple of example themes on first run so the picker has something to show
-/// (the default look needs no theme). No-op once `themes/` exists.
-pub fn seed_themes(app: &tauri::AppHandle) {
-    let dir = match themes_dir(app) {
-        Ok(d) => d,
-        Err(_) => return,
-    };
-    if dir.exists() {
-        return;
-    }
-    if fs::create_dir_all(&dir).is_err() {
-        return;
-    }
-    let samples: &[(&str, &str)] = &[
-        (
-            "amber",
-            ":root {\n\t--np-accent: #ffb000;\n\t--np-label: #ffd27f;\n\t--np-track: rgba(255, 176, 0, 0.18);\n}\n",
-        ),
-        (
-            "mono",
-            ":root {\n\t--np-accent: #d8dee9;\n\t--np-fg: #eceff4;\n\t--np-label: #9aa5b1;\n\t--np-track: rgba(255, 255, 255, 0.12);\n}\n",
-        ),
-    ];
-    for (name, css) in samples {
-        let _ = fs::write(dir.join(format!("{name}.css")), css);
-    }
-}
-
-/// Shared loop behind `watch_themes`/`watch_layout`/`watch_controls`: watch `dir` (non-recursive)
-/// on a dedicated thread for the app's lifetime, and for every filesystem event that passes
-/// `filter`, emit `event_name` then run `on_match` (the layout watcher's main-respawn hook; a
-/// no-op for the others). `label` tags the log lines. Best-effort: logs and returns on watcher
-/// failure, leaving live reload off for that file.
-fn watch_and_emit(
-    app: tauri::AppHandle,
-    dir: PathBuf,
-    label: &'static str,
-    event_name: &'static str,
-    filter: impl Fn(&notify::Event) -> bool + Send + 'static,
-    on_match: impl Fn(&tauri::AppHandle) + Send + 'static,
-) {
-    std::thread::spawn(move || {
-        let (tx, rx) = std::sync::mpsc::channel();
-        let mut watcher = match notify::recommended_watcher(move |res| {
-            let _ = tx.send(res);
-        }) {
-            Ok(watcher) => watcher,
-            Err(err) => {
-                log::error("watch", format!("{label} watcher init failed"))
-                    .field("error", err)
-                    .emit();
-                return;
-            }
-        };
-        if let Err(err) = watcher.watch(&dir, notify::RecursiveMode::NonRecursive) {
-            log::error("watch", format!("{label} watch failed")).field("error", err).emit();
-            return;
-        }
-        // Keep `watcher` alive by blocking on the channel for the app's lifetime.
-        for res in rx {
-            match res {
-                Ok(event) => {
-                    if filter(&event) {
-                        let _ = app.emit(event_name, ());
-                        on_match(&app);
-                    }
-                }
-                Err(err) => {
-                    log::warn("watch", format!("{label} watch error")).field("error", err).emit()
-                }
-            }
-        }
-    });
-}
-
-/// Watch `themes/` and emit `themes_changed` so the frontend live-reloads the active theme.
-pub fn watch_themes(app: tauri::AppHandle) -> Result<(), String> {
-    let dir = themes_dir(&app)?;
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    // Only react to `*.css` files (mirrors the layout/controls watchers' filter), so the
-    // atomic-write `*.css.tmp` sidecar and any non-theme file dropped in the folder don't
-    // spuriously trigger a reload.
-    watch_and_emit(
-        app,
-        dir,
-        "themes",
-        THEMES_CHANGED_EVENT,
-        |event| {
-            event
-                .paths
-                .iter()
-                .any(|p| p.extension().and_then(|x| x.to_str()) == Some("css"))
-        },
-        |_| {},
-    );
-    Ok(())
-}
-
-/// Re-create the primary `main` overlay window (born hidden) after it was torn down to reclaim its
-/// renderer (overlay.ts `setMainWindowVisible(false)`). Mirrors the static `main` config in
-/// tauri.conf.json; the frontend reveals it — or re-destroys it if the primary is still empty — once
-/// its Canvas init runs. Must be called on the main thread (window creation). Best-effort: logs.
-fn respawn_main_hidden(app: &tauri::AppHandle) {
-    match tauri::WebviewWindowBuilder::new(app, "main", tauri::WebviewUrl::App("/".into()))
-        .title("WidgetSack")
-        .inner_size(300.0, 400.0)
-        .transparent(true)
-        .shadow(false)
-        .decorations(false)
-        .always_on_top(false)
-        .always_on_bottom(true)
-        .skip_taskbar(true)
-        .visible(false)
-        .disable_drag_drop_handler()
-        .build()
-    {
-        Ok(_) => log::info("reclaim", "respawned primary overlay (main) after external layout change")
-            .emit(),
-        Err(err) => log::warn("reclaim", "failed to respawn main").field("error", err).emit(),
-    }
-}
-
-/// Watch the config dir for changes to widgets.json and emit `layout_changed`
-/// so the frontend can live-reload. Best-effort: logs and returns on failure.
-pub fn watch_layout(app: tauri::AppHandle) -> Result<(), String> {
-    let path = layout_path(&app)?;
-    let dir = path
-        .parent()
-        .ok_or_else(|| "layout path has no parent".to_string())?
-        .to_path_buf();
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    watch_and_emit(
-        app,
-        dir,
-        "layout",
-        LAYOUT_CHANGED_EVENT,
-        move |event| event.paths.iter().any(|p| p.file_name() == path.file_name()),
-        |app| {
-            // Reclaim: `main` is DESTROYED (not hidden) to free its renderer when the primary
-            // monitor is empty (overlay.ts setMainWindowVisible). While it's gone, no window
-            // drives overlay reconcile, so an external edit to widgets.json that re-populates
-            // the primary would never bring the primary overlay back. Respawn `main` (born
-            // hidden) so its own Canvas init decides: reveal if the primary now has widgets, or
-            // self-destroy if still empty. Skipped while the studio is open — the studio
-            // recreates `main` on close, so we avoid spawn/destroy churn during live editing.
-            // Window creation must run on the main thread.
-            let app_for_respawn = app.clone();
-            let _ = app.run_on_main_thread(move || {
-                if app_for_respawn.get_webview_window("main").is_none()
-                    && app_for_respawn.get_webview_window("studio").is_none()
-                {
-                    respawn_main_hidden(&app_for_respawn);
-                }
-            });
-        },
-    );
-    Ok(())
-}
-
-/// Watch the config dir for changes to controls.json and emit `controls_changed` so the frontend
-/// can live-reload remaps (e.g. an external edit, or another window saving). Mirrors `watch_layout`.
-pub fn watch_controls(app: tauri::AppHandle) -> Result<(), String> {
-    let path = controls_path(&app)?;
-    let dir = path
-        .parent()
-        .ok_or_else(|| "controls path has no parent".to_string())?
-        .to_path_buf();
-    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
-    watch_and_emit(
-        app,
-        dir,
-        "controls",
-        CONTROLS_CHANGED_EVENT,
-        move |event| event.paths.iter().any(|p| p.file_name() == path.file_name()),
-        |_| {},
-    );
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{valid_name, version_is_newer};
-
-    #[test]
-    fn version_is_newer_compares_numerically() {
-        assert!(version_is_newer("0.0.42", "0.0.41"));
-        assert!(version_is_newer("0.1.0", "0.0.41")); // 0.1.0 > 0.0.41, not string compare
-        assert!(version_is_newer("1.0.0", "0.9.9"));
-        assert!(!version_is_newer("0.0.41", "0.0.41")); // equal → no update
-        assert!(!version_is_newer("0.0.40", "0.0.41")); // older
-    }
-
-    #[test]
-    fn version_is_newer_tolerates_v_prefix_and_suffixes() {
-        assert!(version_is_newer("v0.0.42", "0.0.41"));
-        assert!(!version_is_newer("0.0.41-rc1", "0.0.41")); // pre-release suffix stripped → equal
-        assert!(!version_is_newer("garbage", "0.0.1")); // unparseable → (0,0,0), no false update
-    }
-
-    #[test]
-    fn valid_name_accepts_plain_tokens() {
-        assert!(valid_name("amber"));
-        assert!(valid_name("My Theme 2"));
-        assert!(valid_name("dark_mode-v2"));
-        assert!(valid_name(&"x".repeat(64)));
-    }
-
-    #[test]
-    fn valid_name_rejects_unsafe_or_oversized() {
-        assert!(!valid_name("")); // empty
-        assert!(!valid_name("..")); // traversal
-        assert!(!valid_name("a/b")); // separator
-        assert!(!valid_name("a\\b")); // separator
-        assert!(!valid_name("a..b")); // contains ..
-        assert!(!valid_name("name.css")); // dot (extension is added by the caller)
-        assert!(!valid_name("a:b")); // reserved char
-        assert!(!valid_name("tab\tname")); // control char
-        assert!(!valid_name("café")); // non-ASCII
-        assert!(!valid_name(&"x".repeat(65))); // too long
-        assert!(!valid_name(" lead")); // leading space (Windows trims → name collision)
-        assert!(!valid_name("trail ")); // trailing space
-        assert!(!valid_name("   ")); // all whitespace
-    }
-
-    #[test]
-    fn valid_asset_name_requires_css_json_or_js_and_no_traversal() {
-        assert!(super::valid_asset_name("theme.css"));
-        assert!(super::valid_asset_name("extra.JSON")); // case-insensitive ext
-        assert!(super::valid_asset_name("My Theme 2.css")); // spaces ok (valid_name stem)
-        assert!(super::valid_asset_name("source.js")); // Phase 2 sandbox script
-        assert!(super::valid_asset_name("Source.JS")); // case-insensitive ext
-        assert!(!super::valid_asset_name("theme.css.tmp")); // wrong ext (last dot wins)
-        assert!(!super::valid_asset_name("evil.tmp.css")); // stem contains a dot
-        assert!(!super::valid_asset_name("../theme.css")); // traversal
-        assert!(!super::valid_asset_name("..css")); // empty/.. stem
-        assert!(!super::valid_asset_name("a/b.css")); // separator
-        assert!(!super::valid_asset_name("a\\b.css")); // separator
-        assert!(!super::valid_asset_name("theme.exe")); // disallowed ext
-        assert!(!super::valid_asset_name("source.mjs")); // js only, not mjs/cjs
-        assert!(!super::valid_asset_name("noext")); // no extension
-        assert!(!super::valid_asset_name(".css")); // empty stem
-        assert!(!super::valid_asset_name("")); // empty
-    }
-
-    #[test]
-    fn host_allowed_matches_exact_https_domains_only() {
-        let hosts = vec!["api.open-meteo.com".to_string(), "example.org".to_string()];
-        assert!(super::host_allowed(
-            "https://api.open-meteo.com/v1/forecast?latitude=1.35",
-            &hosts
-        ));
-        // URL hosts parse case-folded; a SHOUTING url still matches.
-        assert!(super::host_allowed("https://API.OPEN-METEO.COM/v1", &hosts));
-        // An explicit default port is elided by the parser → still allowed.
-        assert!(super::host_allowed("https://example.org:443/", &hosts));
-        // Subdomains are NOT implied — they must be listed.
-        assert!(!super::host_allowed("https://sub.example.org/", &hosts));
-        assert!(!super::host_allowed("https://example.org.evil.com/", &hosts));
-        // https only, no explicit ports, no credentials, no IP literals.
-        assert!(!super::host_allowed("http://api.open-meteo.com/", &hosts));
-        assert!(!super::host_allowed("https://api.open-meteo.com:8443/", &hosts));
-        assert!(!super::host_allowed("https://user@example.org/", &hosts));
-        assert!(!super::host_allowed(
-            "https://93.184.216.34/",
-            &["93.184.216.34".to_string()]
-        ));
-        // Host case-insensitivity also covers an uppercased (hand-edited) manifest entry.
-        assert!(super::host_allowed(
-            "https://example.org/",
-            &["EXAMPLE.ORG".to_string()]
-        ));
-        assert!(!super::host_allowed("https://evil.com/?q=example.org", &hosts));
-        assert!(!super::host_allowed("not a url", &hosts));
-        assert!(!super::host_allowed("https://example.org/", &[]));
-    }
-
-    #[test]
-    fn resolve_package_source_accepts_the_documented_forms() {
-        // owner/repo shorthand → raw manifest on main.
-        let r = super::resolve_package_source("acme/widget-pack").unwrap();
-        assert_eq!(
-            r.manifest_url,
-            "https://raw.githubusercontent.com/acme/widget-pack/main/plugin.json"
-        );
-        assert_eq!(r.display_source, "acme/widget-pack");
-        assert_eq!(r.reff, "main");
-        // Full repo URL (trailing slash + surrounding whitespace tolerated) → same resolution.
-        let r = super::resolve_package_source(" https://github.com/acme/widget-pack/ ").unwrap();
-        assert_eq!(
-            r.manifest_url,
-            "https://raw.githubusercontent.com/acme/widget-pack/main/plugin.json"
-        );
-        assert_eq!(r.display_source, "acme/widget-pack");
-        // /tree/<ref> pins the ref; slash-y branch names survive the splitn.
-        let r = super::resolve_package_source("https://github.com/acme/widget-pack/tree/feature/x")
-            .unwrap();
-        assert_eq!(
-            r.manifest_url,
-            "https://raw.githubusercontent.com/acme/widget-pack/feature/x/plugin.json"
-        );
-        assert_eq!(r.reff, "feature/x");
-        // Any https URL ending in /plugin.json is used verbatim with ref "direct".
-        let r = super::resolve_package_source("https://example.com/packs/clock/plugin.json")
-            .unwrap();
-        assert_eq!(r.manifest_url, "https://example.com/packs/clock/plugin.json");
-        assert_eq!(r.display_source, "https://example.com/packs/clock/plugin.json");
-        assert_eq!(r.reff, "direct");
-    }
-
-    #[test]
-    fn resolve_package_source_rejects_everything_else() {
-        assert!(super::resolve_package_source("http://github.com/a/b").is_none()); // plain http
-        assert!(super::resolve_package_source("http://example.com/plugin.json").is_none());
-        assert!(super::resolve_package_source("https://example.com/pack").is_none()); // no plugin.json
-        assert!(super::resolve_package_source("https://github.com/onlyowner").is_none());
-        assert!(super::resolve_package_source("https://github.com/a/b/blob/main/x").is_none());
-        assert!(super::resolve_package_source("a/b/c").is_none()); // shorthand has ONE slash
-        assert!(super::resolve_package_source("owner").is_none());
-        assert!(super::resolve_package_source("ftp://a/b").is_none()); // non-https scheme
-        assert!(super::resolve_package_source("a/../b").is_none()); // traversal in a segment
-        assert!(super::resolve_package_source("ow ner/repo").is_none()); // bad owner char
-        assert!(super::resolve_package_source("").is_none());
-    }
-
-    #[test]
-    fn asset_url_for_swaps_the_last_segment() {
-        assert_eq!(
-            super::asset_url_for(
-                "https://raw.githubusercontent.com/a/b/main/plugin.json",
-                "sky.css"
-            ),
-            "https://raw.githubusercontent.com/a/b/main/sky.css"
-        );
-        assert_eq!(
-            super::asset_url_for("https://example.com/packs/clock/plugin.json", "extra.json"),
-            "https://example.com/packs/clock/extra.json"
-        );
-    }
-
-    #[test]
-    fn manifest_url_from_sidecar_rederives_or_fails_closed() {
-        // GitHub provenance: owner/repo + recorded ref.
-        assert_eq!(
-            super::manifest_url_from_sidecar("acme/pack", "v2").as_deref(),
-            Some("https://raw.githubusercontent.com/acme/pack/v2/plugin.json")
-        );
-        // Direct provenance: the URL itself, re-validated through resolve_package_source.
-        assert_eq!(
-            super::manifest_url_from_sidecar("https://example.com/p/plugin.json", "direct")
-                .as_deref(),
-            Some("https://example.com/p/plugin.json")
-        );
-        // Tampered sidecars fail closed.
-        assert!(super::manifest_url_from_sidecar("http://example.com/p/plugin.json", "direct")
-            .is_none());
-        assert!(super::manifest_url_from_sidecar("https://example.com/p", "direct").is_none());
-        assert!(super::manifest_url_from_sidecar("acme/pack", "..").is_none());
-        assert!(super::manifest_url_from_sidecar("acme", "main").is_none());
-        assert!(super::manifest_url_from_sidecar("a/../b", "main").is_none());
-    }
-
-    #[test]
-    fn install_sidecar_is_unreachable_as_an_asset() {
-        // The sidecar must never be readable via read_plugin_package_asset or declarable as a
-        // manifest asset — its dotted stem fails valid_name.
-        assert!(!super::valid_asset_name(super::INSTALL_SIDECAR));
-    }
-
-    #[test]
-    fn valid_wallpaper_name_requires_media_ext_and_no_traversal() {
-        assert!(super::valid_wallpaper_name("loop.mp4"));
-        assert!(super::valid_wallpaper_name("My Wallpaper 2.PNG")); // case-insensitive ext, spaces ok
-        assert!(super::valid_wallpaper_name("clip.webm"));
-        assert!(!super::valid_wallpaper_name("notes.txt")); // not a media ext
-        assert!(!super::valid_wallpaper_name("noext")); // no extension
-        assert!(!super::valid_wallpaper_name("../escape.png")); // traversal
-        assert!(!super::valid_wallpaper_name("sub/dir.png")); // separator
-        assert!(!super::valid_wallpaper_name("a\\b.png")); // separator
-        assert!(!super::valid_wallpaper_name("")); // empty
-    }
-}
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use notify::Watcher;
+use serde::Serialize;
+use tauri::{Emitter, Manager};
+
+use crate::bridge::{CONTROLS_CHANGED_EVENT, LAYOUT_CHANGED_EVENT, THEMES_CHANGED_EVENT};
+use crate::{AppState, SessionRecord, log};
+
+#[derive(Serialize)]
+pub struct UpdateResponse {
+    pub sessions: HashMap<usize, SessionRecord>,
+}
+
+#[tauri::command]
+pub async fn get_initial_sessions(
+    _message: String,
+    state: tauri::State<'_, AppState>,
+    art: tauri::State<'_, crate::art::ArtState>,
+) -> Result<UpdateResponse, String> {
+    let sessions = state.sessions.lock().await;
+
+    let mut cloned: HashMap<usize, SessionRecord> = HashMap::new();
+    cloned.clone_from(&sessions);
+
+    // Re-register each session's cover so the URLs in this snapshot resolve for a just-booted
+    // overlay even if the live media events fired before its webview existed (art.rs).
+    for record in cloned.values() {
+        crate::art::note_record(&art, record);
+    }
+
+    Ok(UpdateResponse { sessions: cloned })
+}
+
+/// The app config dir — isolated into a `multi/` subfolder for an extra dev instance
+/// (`crate::multi_instance`), so a dev build run alongside the installed release never reads or writes
+/// the release's widgets.json / themes / layouts / sacks. The real config dir otherwise. All the
+/// config/theme/layout/sack/wallpaper/plugin paths (and their file watchers) go through this.
+fn config_root(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let base = app.path().app_config_dir().map_err(|e| e.to_string())?;
+    Ok(if crate::multi_instance() {
+        base.join("multi")
+    } else {
+        base
+    })
+}
+
+/// Path to the persisted widget layout (`widgets.json` in the app config dir).
+fn layout_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("widgets.json"))
+}
+
+/// Read the saved layout file, or `None` if it does not exist yet. The frontend
+/// validates/parses the contents (see core/layout.ts) so this stays dumb I/O.
+#[tauri::command]
+pub async fn load_layout(app: tauri::AppHandle) -> Result<Option<String>, String> {
+    let path = layout_path(&app)?;
+    match fs::read_to_string(&path) {
+        Ok(contents) => Ok(Some(contents)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+/// Write the layout file, creating the config directory if needed.
+#[tauri::command]
+pub async fn save_layout(app: tauri::AppHandle, contents: String) -> Result<(), String> {
+    let path = layout_path(&app)?;
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|e| e.to_string())?;
+    }
+    fs::write(&path, contents).map_err(|e| e.to_string())
+}
+
+/// Path to the persisted control remaps (`controls.json` in the app config dir).
+fn controls_path(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("controls.json"))
+}
+
+/// Read the saved control overrides, or `None` if none saved yet. The frontend validates/parses
+/// the contents (core/controls.ts `parseControlOverrides`) so this stays dumb I/O — mirrors
+/// `load_layout`, and an absent/garbage file simply falls back to the code defaults.
+#[tauri::command]
+pub async fn load_controls(app: tauri::AppHandle) -> Result<Option<String>, String> {
+    let path = controls_path(&app)?;
+    match fs::read_to_string(&path) {
+        Ok(contents) => Ok(Some(contents)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+/// Write the control overrides file, creating the config directory if needed.
+#[tauri::command]
+pub async fn save_controls(app: tauri::AppHandle, contents: String) -> Result<(), String> {
+    let path = controls_path(&app)?;
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|e| e.to_string())?;
+    }
+    fs::write(&path, contents).map_err(|e| e.to_string())
+}
+
+/// Open the webview devtools/inspector for the calling window (CSS development from the studio's
+/// context menu). `open_devtools` is available because tauri's `devtools` feature is enabled in
+/// Cargo.toml (it is also always available in debug builds).
+#[tauri::command]
+pub fn open_devtools(window: tauri::WebviewWindow) {
+    window.open_devtools();
+}
+
+// --- by-label window control (the Diagnostics panel's crash-recovery controls) -----------------------
+// These target ANOTHER window by label from the studio, driven entirely by the backend. That matters
+// because the per-window JS event bridge (lib/diag.ts) dies with the window's webview — when an overlay
+// OOM-crashes, its JS can no longer answer the poll or obey "open devtools / drop click-through", so the
+// crashed window vanishes from the list and stays an un-clickable, uninspectable click-through surface.
+// Routing these through the backend (the OS window object outlives the renderer) keeps a crashed overlay
+// listable, inspectable, and rescuable.
+
+/// Every live app window's label (`studio`, `main`, `overlay-1`, …). The Diagnostics panel uses this as
+/// the source of truth for which windows exist, so a window whose webview crashed (and therefore stopped
+/// reporting over the JS bridge) still appears — marked "not responding" — instead of silently dropping.
+#[tauri::command]
+pub fn list_window_labels(app: tauri::AppHandle) -> Vec<String> {
+    app.webview_windows().into_keys().collect()
+}
+
+/// Open devtools for the window with `label` (not necessarily the caller). Lets the studio inspect a
+/// crashed/passive overlay it could never reach through that overlay's own (dead) JS.
+#[tauri::command]
+pub fn open_devtools_for(app: tauri::AppHandle, label: String) {
+    if let Some(win) = app.get_webview_window(&label) {
+        win.open_devtools();
+    }
+}
+
+/// Toggle whole-window click-through for the window with `label`. `interactive = true` drops
+/// click-through (and brings the window forward so you can actually click it — e.g. a crashed overlay's
+/// "Reload" page); `false` restores it. No-op if the label is unknown.
+#[tauri::command]
+pub fn set_window_interactive(
+    app: tauri::AppHandle,
+    label: String,
+    interactive: bool,
+) -> Result<(), String> {
+    if let Some(win) = app.get_webview_window(&label) {
+        win.set_ignore_cursor_events(!interactive)
+            .map_err(|e| e.to_string())?;
+        if interactive {
+            let _ = win.show();
+            let _ = win.set_focus();
+        }
+    }
+    Ok(())
+}
+
+/// Make EVERY app window interactive again and bring it forward — the backend "panic button" for a
+/// window you can't reach: a click-through overlay, or one whose webview crashed so its own JS can no
+/// longer drop click-through. Best-effort per window; never panics. Shared by the rescue hotkey
+/// (main.rs) and the `rescue_windows` command, so it's generic over the runtime.
+pub fn rescue_all<R: tauri::Runtime>(app: &tauri::AppHandle<R>) {
+    for win in app.webview_windows().into_values() {
+        let _ = win.set_ignore_cursor_events(false);
+        let _ = win.unminimize();
+        let _ = win.show();
+        let _ = win.set_focus();
+    }
+}
+
+/// Command wrapper for [`rescue_all`] (the studio's "Rescue all windows" button).
+#[tauri::command]
+pub fn rescue_windows(app: tauri::AppHandle) {
+    rescue_all(&app);
+}
+
+/// Reload the webview of the window with `label` — respawns its renderer, recovering a crashed overlay
+/// (the WebView2 "Out of Memory" page) without relaunching the app. No-op if the label is unknown.
+#[tauri::command]
+pub fn reload_window(app: tauri::AppHandle, label: String) -> Result<(), String> {
+    if let Some(win) = app.get_webview_window(&label) {
+        win.reload().map_err(|e| e.to_string())?;
+    }
+    Ok(())
+}
+
+/// Append a window's diagnostics summary to the rotating log file (the memory TRAIL). Each window calls
+/// this on an interval (lib/diag.ts `startMemoryTrail`); because it lands on disk, the run-up to an
+/// unattended overnight OOM survives the crash — read the last `memtrail` lines to see which metric was
+/// climbing. Logged at info so it persists in release builds; the window label is attached as a field.
+#[tauri::command]
+pub fn log_diag(window: tauri::WebviewWindow, summary: String) {
+    log::info("memtrail", summary)
+        .field("window", window.label())
+        .emit();
+}
+
+#[derive(serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SystemFont {
+    /// Family name (CSS `font-family`).
+    pub name: String,
+    /// PostScript name (often a spaceless variant of the family).
+    pub font_name: String,
+    /// Absolute path to the font file (for the webview to @font-face via the asset protocol).
+    pub path: String,
+}
+
+/// Enumerate installed fonts (incl. PER-USER ones) with their file paths. Chromium's sandboxed
+/// webview won't render a per-user-installed font by name — but fontdb can find it here, and the
+/// frontend then loads the file directly via @font-face + the asset protocol (the approach of
+/// tauri-plugin-system-fonts, inlined). The per-user fonts dir is added explicitly (where Windows
+/// puts "install for me only" fonts).
+#[tauri::command]
+pub fn system_fonts() -> Vec<SystemFont> {
+    use fontdb::{Database, Source};
+    let mut db = Database::new();
+    db.load_system_fonts();
+    if let Ok(local) = std::env::var("LOCALAPPDATA") {
+        db.load_fonts_dir(std::path::Path::new(&local).join("Microsoft\\Windows\\Fonts"));
+    }
+    db.faces()
+        .filter_map(|f| match &f.source {
+            Source::File(path) => {
+                let name = f.families.first()?.0.clone();
+                if name.starts_with('.') {
+                    return None; // hidden/system aliases
+                }
+                Some(SystemFont {
+                    name,
+                    font_name: f.post_script_name.clone(),
+                    path: path.to_string_lossy().into_owned(),
+                })
+            }
+            _ => None,
+        })
+        .collect()
+}
+
+// ---- themes (Phase 7c): a `themes/<name>.css` plugin folder in the app config dir ----
+
+fn themes_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("themes"))
+}
+
+/// Write `contents` to `path` atomically: write a sibling temp file, then rename it onto the target
+/// (a rename is atomic on the same volume), so a concurrent reader — or a crash mid-write — never
+/// sees a truncated/partial file. The temp name keeps the original and appends `.tmp`, so its
+/// extension is `tmp` (not `css`/`json`) and the directory watchers, which filter by extension,
+/// ignore it. Best-effort cleanup of the temp file on failure.
+fn atomic_write(path: &Path, contents: &str) -> Result<(), String> {
+    let file_name = path
+        .file_name()
+        .and_then(|s| s.to_str())
+        .ok_or_else(|| "write path has no file name".to_string())?;
+    let mut tmp = path.to_path_buf();
+    tmp.set_file_name(format!("{file_name}.tmp"));
+    if let Err(err) = fs::write(&tmp, contents) {
+        let _ = fs::remove_file(&tmp);
+        return Err(err.to_string());
+    }
+    fs::rename(&tmp, path).map_err(|e| {
+        let _ = fs::remove_file(&tmp);
+        e.to_string()
+    })
+}
+
+/// The theme names (file stems of `themes/*.css`), sorted. The frontend adds a synthetic
+/// "(default)" option (no theme = the meters' token fallbacks).
+#[tauri::command]
+pub fn list_themes(app: tauri::AppHandle) -> Result<Vec<String>, String> {
+    let dir = themes_dir(&app)?;
+    let mut names = Vec::new();
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if path.extension().and_then(|x| x.to_str()) == Some("css")
+                && let Some(stem) = path.file_stem().and_then(|s| s.to_str())
+            {
+                names.push(stem.to_string());
+            }
+        }
+    }
+    names.sort();
+    Ok(names)
+}
+
+/// The CSS of theme `name` (a bare file stem), or `None` if it doesn't exist.
+#[tauri::command]
+pub fn load_theme(app: tauri::AppHandle, name: String) -> Result<Option<String>, String> {
+    if !valid_name(&name) {
+        return Err("invalid theme name".to_string());
+    }
+    let path = themes_dir(&app)?.join(format!("{name}.css"));
+    match fs::read_to_string(&path) {
+        Ok(contents) => Ok(Some(contents)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+/// Write theme `name` (used by the studio's theme editor + token panel, Phase 7d). Creates
+/// `themes/`. Atomic (temp + rename) so a concurrent overlay reload never reads a half-written file.
+#[tauri::command]
+pub fn save_theme(app: tauri::AppHandle, name: String, contents: String) -> Result<(), String> {
+    if !valid_name(&name) {
+        return Err("invalid theme name".to_string());
+    }
+    let dir = themes_dir(&app)?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    atomic_write(&dir.join(format!("{name}.css")), &contents)
+}
+
+/// Delete theme `name` → removes `themes/<name>.css`. Ok even if it's already gone (idempotent),
+/// mirroring `delete_layout`. The themes watcher then emits `themes_changed` so the picker refreshes.
+#[tauri::command]
+pub fn delete_theme(app: tauri::AppHandle, name: String) -> Result<(), String> {
+    if !valid_name(&name) {
+        return Err("invalid theme name".to_string());
+    }
+    let path = themes_dir(&app)?.join(format!("{name}.css"));
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+// ---- wallpapers: media for the per-monitor full-screen background layer ----
+// Same "dumb I/O to a fixed folder, no native picker" pattern as themes/sacks: the user drops image
+// or video files into `<app config>/wallpapers/` (already inside the asset-protocol scope, so the
+// webview can load them), and the studio lists them for the Background section. `BackgroundSpec.src`
+// stores the bare filename; the frontend resolves it to an asset URL via `wallpaper_path`.
+
+fn wallpapers_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("wallpapers"))
+}
+
+// Image/video extensions the webview can render (the picker shows only these).
+const WALLPAPER_EXTS: &[&str] = &[
+    "png", "jpg", "jpeg", "gif", "webp", "bmp", "avif", "mp4", "webm", "mkv", "mov", "m4v",
+];
+
+/// A wallpaper filename is a single path component with a media extension. Rejects separators / `..`
+/// (path traversal) but — unlike `valid_name` — ALLOWS the extension dot.
+fn valid_wallpaper_name(name: &str) -> bool {
+    !name.is_empty()
+        && name.len() <= 128
+        && !name.contains('/')
+        && !name.contains('\\')
+        && !name.contains("..")
+        && std::path::Path::new(name)
+            .extension()
+            .and_then(|x| x.to_str())
+            .map(|e| WALLPAPER_EXTS.contains(&e.to_ascii_lowercase().as_str()))
+            .unwrap_or(false)
+}
+
+/// The media filenames in `wallpapers/` (image + video only), sorted. Creates the folder so the
+/// studio's "open folder" button always has somewhere to point.
+#[tauri::command]
+pub fn list_wallpapers(app: tauri::AppHandle) -> Result<Vec<String>, String> {
+    let dir = wallpapers_dir(&app)?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    let mut names = Vec::new();
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            if let Some(name) = entry.file_name().to_str()
+                && valid_wallpaper_name(name)
+            {
+                names.push(name.to_string());
+            }
+        }
+    }
+    names.sort();
+    Ok(names)
+}
+
+/// The absolute path of wallpaper `name`, for the frontend to feed `convertFileSrc`. Validates the
+/// name (no traversal); returns the path even if the file is missing (the <img>/<video> just won't
+/// load), so the caller doesn't have to special-case a not-yet-present file.
+#[tauri::command]
+pub fn wallpaper_path(app: tauri::AppHandle, name: String) -> Result<String, String> {
+    if !valid_wallpaper_name(&name) {
+        return Err("invalid wallpaper name".to_string());
+    }
+    Ok(wallpapers_dir(&app)?
+        .join(name)
+        .to_string_lossy()
+        .into_owned())
+}
+
+/// Open the `wallpapers/` folder in Explorer so the user can drop media in. Creates it first.
+#[tauri::command]
+pub fn open_wallpapers_dir(app: tauri::AppHandle) -> Result<(), String> {
+    let dir = wallpapers_dir(&app)?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    std::process::Command::new("explorer")
+        .arg(&dir)
+        .spawn()
+        .map_err(|e| e.to_string())?;
+    Ok(())
+}
+
+// ---- sacks: shareable bundles (`sacks/<name>.sack.json` in the app config dir) ----
+// A "sack" packs the widget library + active theme CSS + token overrides as one JSON file so a
+// user can share/reuse a set. Dumb I/O to a fixed folder (no native file picker); the frontend
+// owns the format + merge logic (core/sack.ts).
+
+fn sacks_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("sacks"))
+}
+
+/// Shared filename allowlist for user-named config files (themes, sacks). The name becomes a
+/// path segment, so it must be a safe, bounded token: 1–64 chars of `[A-Za-z0-9 _-]` only. This
+/// rejects control chars, path separators, `..`, and Windows-reserved characters by construction;
+/// the explicit empty/`..`/separator checks below are kept as a defensive backstop. Leading/trailing
+/// spaces are rejected too — Windows silently trims trailing spaces/dots from filenames, so `"a "`
+/// and `"a"` would collide on disk and a delete-by-name could miss.
+fn valid_name(name: &str) -> bool {
+    !name.is_empty()
+        && name == name.trim()
+        && !name.contains('/')
+        && !name.contains('\\')
+        && !name.contains("..")
+        && name.len() <= 64
+        && name
+            .chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == ' ' || c == '_' || c == '-')
+}
+
+fn valid_sack_name(name: &str) -> bool {
+    valid_name(name)
+}
+
+/// The sack names (file stems of `sacks/*.sack.json`), sorted.
+#[tauri::command]
+pub fn list_sacks(app: tauri::AppHandle) -> Result<Vec<String>, String> {
+    let dir = sacks_dir(&app)?;
+    let mut names = Vec::new();
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if let Some(file) = path.file_name().and_then(|s| s.to_str())
+                && let Some(stem) = file.strip_suffix(".sack.json")
+            {
+                names.push(stem.to_string());
+            }
+        }
+    }
+    names.sort();
+    Ok(names)
+}
+
+/// The JSON of sack `name`, or `None` if it doesn't exist. The frontend parses/validates it.
+#[tauri::command]
+pub fn read_sack(app: tauri::AppHandle, name: String) -> Result<Option<String>, String> {
+    if !valid_sack_name(&name) {
+        return Err("invalid sack name".to_string());
+    }
+    let path = sacks_dir(&app)?.join(format!("{name}.sack.json"));
+    match fs::read_to_string(&path) {
+        Ok(contents) => Ok(Some(contents)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+/// Write sack `name` (creates `sacks/`). Returns the absolute path written, for the UI to show.
+#[tauri::command]
+pub fn write_sack(app: tauri::AppHandle, name: String, contents: String) -> Result<String, String> {
+    if !valid_sack_name(&name) {
+        return Err("invalid sack name".to_string());
+    }
+    let dir = sacks_dir(&app)?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    let path = dir.join(format!("{name}.sack.json"));
+    fs::write(&path, contents).map_err(|e| e.to_string())?;
+    Ok(path.to_string_lossy().into_owned())
+}
+
+// ---- saved layouts: named layout profiles (`layouts/<name>.layout.json` in the app config dir) ----
+// A saved layout is one monitor's arrangement (root tree + floating widgets) the user can name, list,
+// load back, and delete from the studio. Dumb I/O to a fixed folder (same shape as sacks/themes); the
+// frontend owns the JSON format + the load/replace logic (core/savedLayout.ts).
+
+fn layouts_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("layouts"))
+}
+
+/// The saved-layout names (file stems of `layouts/*.layout.json`), sorted.
+#[tauri::command]
+pub fn list_layouts(app: tauri::AppHandle) -> Result<Vec<String>, String> {
+    let dir = layouts_dir(&app)?;
+    let mut names = Vec::new();
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if let Some(file) = path.file_name().and_then(|s| s.to_str())
+                && let Some(stem) = file.strip_suffix(".layout.json")
+            {
+                names.push(stem.to_string());
+            }
+        }
+    }
+    names.sort();
+    Ok(names)
+}
+
+/// The JSON of saved layout `name`, or `None` if it doesn't exist. The frontend parses/validates it.
+#[tauri::command]
+pub fn read_layout(app: tauri::AppHandle, name: String) -> Result<Option<String>, String> {
+    if !valid_name(&name) {
+        return Err("invalid layout name".to_string());
+    }
+    let path = layouts_dir(&app)?.join(format!("{name}.layout.json"));
+    match fs::read_to_string(&path) {
+        Ok(contents) => Ok(Some(contents)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+/// Write saved layout `name` (creates `layouts/`). Returns the absolute path written.
+#[tauri::command]
+pub fn save_layout_as(
+    app: tauri::AppHandle,
+    name: String,
+    contents: String,
+) -> Result<String, String> {
+    if !valid_name(&name) {
+        return Err("invalid layout name".to_string());
+    }
+    let dir = layouts_dir(&app)?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    let path = dir.join(format!("{name}.layout.json"));
+    fs::write(&path, contents).map_err(|e| e.to_string())?;
+    Ok(path.to_string_lossy().into_owned())
+}
+
+/// Delete saved layout `name`. Ok even if it's already gone (idempotent).
+#[tauri::command]
+pub fn delete_layout(app: tauri::AppHandle, name: String) -> Result<(), String> {
+    if !valid_name(&name) {
+        return Err("invalid layout name".to_string());
+    }
+    let path = layouts_dir(&app)?.join(format!("{name}.layout.json"));
+    match fs::remove_file(&path) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+// ---- plugin packages: declarative third-party bundles (`plugins/<id>/plugin.json`) ----
+// The app-config `plugins/` dir already holds first-party config FILES (ha.json, llm.json, …);
+// a third-party package is a SUBDIRECTORY containing a `plugin.json`, so the two coexist
+// unambiguously — only directories with a manifest are listed. Dumb I/O only: the frontend
+// parses/validates the manifest (core/pluginPackage.ts) and decides what to register.
+
+fn plugins_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
+    let dir = config_root(app)?;
+    Ok(dir.join("plugins"))
+}
+
+/// A package asset filename is a single path component: `<valid_name stem>.<css|json|js>` (`.js`
+/// is a Phase 2 sandboxed source script — it is only ever TEXT to the backend). Splitting at the
+/// LAST dot and running the stem through `valid_name` rejects separators, `..`, extra dots
+/// (so no `x.css.tmp` smuggling), and oversized names by construction.
+fn valid_asset_name(name: &str) -> bool {
+    match name.rsplit_once('.') {
+        Some((stem, ext)) => {
+            (ext.eq_ignore_ascii_case("css")
+                || ext.eq_ignore_ascii_case("json")
+                || ext.eq_ignore_ascii_case("js"))
+                && valid_name(stem)
+        }
+        None => false,
+    }
+}
+
+#[derive(Serialize)]
+pub struct PluginPackageFile {
+    /// The package directory name (its id; the frontend cross-checks the manifest's `id`).
+    pub id: String,
+    /// Raw `plugin.json` contents, unparsed.
+    pub manifest: String,
+    /// Raw `.install.json` sidecar (written by `install_plugin_package`), unparsed — the frontend
+    /// parses it (core/pluginPackage.ts `parseInstallSidecar`) to show provenance and drive the
+    /// update-check/update affordances. `None` for hand-dropped (local) packages.
+    pub install: Option<String>,
+}
+
+/// Every `plugins/<id>/plugin.json`, sorted by id. Directories only (first-party config FILES in
+/// `plugins/` are skipped), ids must pass `valid_name` (they become path segments in
+/// `read_plugin_package_asset`). Missing `plugins/` dir → empty vec.
+#[tauri::command]
+pub fn list_plugin_packages(app: tauri::AppHandle) -> Result<Vec<PluginPackageFile>, String> {
+    let dir = plugins_dir(&app)?;
+    let mut out = Vec::new();
+    if let Ok(entries) = fs::read_dir(&dir) {
+        for entry in entries.flatten() {
+            let path = entry.path();
+            if !path.is_dir() {
+                continue;
+            }
+            let Some(id) = path.file_name().and_then(|s| s.to_str()) else {
+                continue;
+            };
+            if !valid_name(id) {
+                continue;
+            }
+            if let Ok(manifest) = fs::read_to_string(path.join("plugin.json")) {
+                out.push(PluginPackageFile {
+                    id: id.to_string(),
+                    manifest,
+                    install: fs::read_to_string(path.join(INSTALL_SIDECAR)).ok(),
+                });
+            }
+        }
+    }
+    out.sort_by(|a, b| a.id.cmp(&b.id));
+    Ok(out)
+}
+
+/// Read `plugins/<id>/<name>` — a manifest-declared asset (theme CSS / extra JSON). Both segments
+/// are sanitized (no traversal); only `.css`/`.json` files are readable. `None` if absent.
+#[tauri::command]
+pub fn read_plugin_package_asset(
+    app: tauri::AppHandle,
+    id: String,
+    name: String,
+) -> Result<Option<String>, String> {
+    if !valid_name(&id) {
+        return Err("invalid package id".to_string());
+    }
+    if !valid_asset_name(&name) {
+        return Err("invalid asset name".to_string());
+    }
+    let path = plugins_dir(&app)?.join(&id).join(&name);
+    match fs::read_to_string(&path) {
+        Ok(contents) => Ok(Some(contents)),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+// ---- plugin packages: remote install (Phase 3) -------------------------------------------------
+// Install a package straight from a GitHub link (or any https URL to a plugin.json): fetch the
+// manifest + its declared assets over https (10s timeout, 256 KiB per-file cap), write them into
+// `plugins/<id>/` via atomic_write, and record provenance in a `.install.json` sidecar so the
+// frontend can offer MANUAL update checks later. Validation stays split exactly like Phase 1: the
+// backend only enforces the path-safety invariants (`valid_name` id, `valid_asset_name` assets);
+// the frontend does the full structural validation and the enable/consent gate — a freshly
+// installed package lands DISABLED like a hand-dropped folder.
+
+/// Provenance sidecar filename. Starts with a dot so its stem fails `valid_name`, which keeps it
+/// out of `read_plugin_package_asset`'s reachable set and out of any manifest's declarable assets.
+const INSTALL_SIDECAR: &str = ".install.json";
+
+/// Per-file download cap (manifest and each asset) — a plugin.json is a few KiB, a theme CSS tens.
+const FETCH_CAP: usize = 256 * 1024;
+
+/// A resolved install source: where the manifest lives, plus what the sidecar should record.
+#[derive(Debug, PartialEq)]
+struct ResolvedSource {
+    /// Direct https URL of the `plugin.json` to GET.
+    manifest_url: String,
+    /// What the sidecar stores as `source`: `owner/repo` for GitHub forms, the URL itself for
+    /// direct links. Paired with `reff`, it's enough to re-derive `manifest_url` at update time.
+    display_source: String,
+    /// Git ref for GitHub forms (`main` unless a `/tree/<ref>` URL pinned one); `direct` for a
+    /// verbatim plugin.json URL.
+    reff: String,
+}
+
+/// One GitHub owner/repo path segment: ASCII alphanumeric plus `-`/`_`/`.`, no `..`, bounded.
+fn gh_token(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= 100
+        && !s.contains("..")
+        && s.chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.')
+}
+
+/// A git ref as it may appear in a `/tree/<ref>` URL: like `gh_token` but slashes are allowed
+/// (branch names such as `feature/x`), `..` still rejected.
+fn valid_ref(s: &str) -> bool {
+    !s.is_empty()
+        && s.len() <= 200
+        && !s.contains("..")
+        && s.chars()
+            .all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_' || c == '.' || c == '/')
+}
+
+fn raw_manifest_url(owner: &str, repo: &str, reff: &str) -> String {
+    format!("https://raw.githubusercontent.com/{owner}/{repo}/{reff}/plugin.json")
+}
+
+/// PURE SEAM: turn the user's install input into a manifest URL + sidecar provenance. Accepted
+/// forms (anything else → `None`; plain `http://` is rejected outright — https only):
+///
+/// | input                                        | manifest_url                                              | ref      |
+/// |----------------------------------------------|-----------------------------------------------------------|----------|
+/// | `owner/repo`                                 | `https://raw.githubusercontent.com/owner/repo/main/plugin.json`  | `main`   |
+/// | `https://github.com/owner/repo[/]`           | same as above                                             | `main`   |
+/// | `https://github.com/owner/repo/tree/<ref>`   | `…/owner/repo/<ref>/plugin.json`                          | `<ref>`  |
+/// | any https URL ending in `/plugin.json`       | used verbatim                                             | `direct` |
+fn resolve_package_source(input: &str) -> Option<ResolvedSource> {
+    let input = input.trim().trim_end_matches('/');
+    if let Some(rest) = input.strip_prefix("https://") {
+        if let Some(path) = rest.strip_prefix("github.com/") {
+            // splitn(4): segment 4 keeps any remaining slashes — that's the (slash-friendly) ref.
+            let parts: Vec<&str> = path.splitn(4, '/').collect();
+            return match parts.as_slice() {
+                [owner, repo] if gh_token(owner) && gh_token(repo) => Some(ResolvedSource {
+                    manifest_url: raw_manifest_url(owner, repo, "main"),
+                    display_source: format!("{owner}/{repo}"),
+                    reff: "main".to_string(),
+                }),
+                [owner, repo, "tree", reff]
+                    if gh_token(owner) && gh_token(repo) && valid_ref(reff) =>
+                {
+                    Some(ResolvedSource {
+                        manifest_url: raw_manifest_url(owner, repo, reff),
+                        display_source: format!("{owner}/{repo}"),
+                        reff: reff.to_string(),
+                    })
+                }
+                _ => None,
+            };
+        }
+        if input.ends_with("/plugin.json") {
+            return Some(ResolvedSource {
+                manifest_url: input.to_string(),
+                display_source: input.to_string(),
+                reff: "direct".to_string(),
+            });
+        }
+        return None;
+    }
+    // `owner/repo` shorthand — exactly one slash, both segments GitHub-safe, no scheme at all.
+    if input.contains("://") {
+        return None;
+    }
+    let (owner, repo) = input.split_once('/')?;
+    if gh_token(owner) && gh_token(repo) && !repo.contains('/') {
+        return Some(ResolvedSource {
+            manifest_url: raw_manifest_url(owner, repo, "main"),
+            display_source: format!("{owner}/{repo}"),
+            reff: "main".to_string(),
+        });
+    }
+    None
+}
+
+/// PURE SEAM: a declared asset lives next to its manifest — swap the URL's last segment.
+fn asset_url_for(manifest_url: &str, asset_name: &str) -> String {
+    match manifest_url.rsplit_once('/') {
+        Some((base, _)) => format!("{base}/{asset_name}"),
+        None => asset_name.to_string(),
+    }
+}
+
+/// PURE SEAM: re-derive the manifest URL from sidecar provenance (`source` + `ref`) for update
+/// checks / re-installs. `direct` sources re-run through `resolve_package_source` so a tampered
+/// sidecar can't smuggle a non-https or non-plugin.json URL back in.
+fn manifest_url_from_sidecar(source: &str, reff: &str) -> Option<String> {
+    if reff == "direct" {
+        let resolved = resolve_package_source(source)?;
+        return (resolved.reff == "direct").then_some(resolved.manifest_url);
+    }
+    let (owner, repo) = source.split_once('/')?;
+    if gh_token(owner) && gh_token(repo) && !repo.contains('/') && valid_ref(reff) {
+        Some(raw_manifest_url(owner, repo, reff))
+    } else {
+        None
+    }
+}
+
+/// A 10s-timeout https client for the (small) manifest/asset fetches.
+fn install_http_client() -> Result<reqwest::Client, String> {
+    reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(10))
+        .build()
+        .map_err(|e| e.to_string())
+}
+
+/// GET `url` and return its body as text, enforcing `FETCH_CAP` while streaming (a hostile or
+/// misconfigured server can't make us buffer an unbounded body).
+async fn fetch_text_capped(client: &reqwest::Client, url: &str) -> Result<String, String> {
+    use futures_util::StreamExt;
+    let resp = client
+        .get(url)
+        .send()
+        .await
+        .map_err(|e| format!("GET {url} failed: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!("GET {url} failed: HTTP {}", resp.status()));
+    }
+    if let Some(len) = resp.content_length()
+        && len > FETCH_CAP as u64
+    {
+        return Err(format!("{url} is too large ({len} bytes; cap {FETCH_CAP})"));
+    }
+    let mut buf: Vec<u8> = Vec::new();
+    let mut stream = resp.bytes_stream();
+    while let Some(chunk) = stream.next().await {
+        let bytes = chunk.map_err(|e| format!("GET {url} failed mid-body: {e}"))?;
+        if buf.len() + bytes.len() > FETCH_CAP {
+            return Err(format!("{url} exceeded the {FETCH_CAP}-byte download cap"));
+        }
+        buf.extend_from_slice(&bytes);
+    }
+    String::from_utf8(buf).map_err(|_| format!("{url} is not valid UTF-8"))
+}
+
+/// GitHub releases API for the app's own repo — the manual "check for updates" source (the app
+/// ships no auto-updater, so this just tells the user a newer release exists).
+const GITHUB_LATEST_RELEASE_API: &str =
+    "https://api.github.com/repos/gyng/widgetsack/releases/latest";
+const RELEASES_PAGE: &str = "https://github.com/gyng/widgetsack/releases";
+
+#[derive(Serialize)]
+pub struct AppUpdate {
+    pub current: String,
+    pub latest: String,
+    pub url: String,
+    pub update_available: bool,
+}
+
+/// Parse an `X.Y.Z` version into a comparable tuple, tolerating a leading `v` and a `-pre`/`+build`
+/// suffix; any missing or non-numeric part is 0 so a malformed tag never falsely reports an update.
+fn parse_version(v: &str) -> (u32, u32, u32) {
+    let core = v.trim().trim_start_matches('v');
+    let core = core.split(['-', '+']).next().unwrap_or(core);
+    let mut parts = core.split('.').map(|p| p.parse::<u32>().unwrap_or(0));
+    (
+        parts.next().unwrap_or(0),
+        parts.next().unwrap_or(0),
+        parts.next().unwrap_or(0),
+    )
+}
+
+/// Whether `latest` is a newer version than `current` (numeric X.Y.Z compare). Pure seam.
+fn version_is_newer(latest: &str, current: &str) -> bool {
+    parse_version(latest) > parse_version(current)
+}
+
+/// Ask GitHub for the latest published release of the app and compare it to the running version.
+/// Manual (driven by the About panel button); best-effort — any network/parse failure is returned
+/// as an `Err` the UI shows verbatim. The GitHub REST API requires a User-Agent.
+#[tauri::command]
+pub async fn check_app_update(app: tauri::AppHandle) -> Result<AppUpdate, String> {
+    let current = app.package_info().version.to_string();
+    let client = install_http_client()?;
+    let resp = client
+        .get(GITHUB_LATEST_RELEASE_API)
+        .header(reqwest::header::USER_AGENT, "widgetsack")
+        .header(reqwest::header::ACCEPT, "application/vnd.github+json")
+        .send()
+        .await
+        .map_err(|e| format!("update check failed: {e}"))?;
+    if !resp.status().is_success() {
+        return Err(format!("update check failed: HTTP {}", resp.status()));
+    }
+    let json: serde_json::Value = resp
+        .json()
+        .await
+        .map_err(|e| format!("update check failed: {e}"))?;
+    let latest = json
+        .get("tag_name")
+        .and_then(|v| v.as_str())
+        .ok_or("update check failed: no tag_name in latest release")?
+        .trim_start_matches('v')
+        .to_string();
+    let url = json
+        .get("html_url")
+        .and_then(|v| v.as_str())
+        .unwrap_or(RELEASES_PAGE)
+        .to_string();
+    let update_available = version_is_newer(&latest, &current);
+    Ok(AppUpdate {
+        current,
+        latest,
+        url,
+        update_available,
+    })
+}
+
+#[derive(Serialize)]
+pub struct InstalledPackage {
+    pub id: String,
+    pub version: String,
+}
+
+/// Install (or re-install — that IS the update path) a package from `source` (see
+/// `resolve_package_source` for the accepted forms). Fetches the manifest, minimally reads
+/// `id`/`version`/`theme.file` (full validation stays in the frontend), fetches every declared
+/// asset, and only THEN writes — a failed download never leaves a half-installed directory.
+#[tauri::command]
+pub async fn install_plugin_package(
+    app: tauri::AppHandle,
+    source: String,
+) -> Result<InstalledPackage, String> {
+    let resolved = resolve_package_source(&source).ok_or_else(|| {
+        "unrecognized source — use owner/repo, a github.com repo URL, or an https URL ending in /plugin.json"
+            .to_string()
+    })?;
+    let client = install_http_client()?;
+    let manifest_text = fetch_text_capped(&client, &resolved.manifest_url).await?;
+    let json: serde_json::Value = serde_json::from_str(&manifest_text)
+        .map_err(|_| "downloaded plugin.json is not valid JSON".to_string())?;
+    let id = json
+        .get("id")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .to_string();
+    if !valid_name(&id) {
+        return Err("manifest \"id\" is missing or not a safe folder name".to_string());
+    }
+    let version = json
+        .get("version")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .trim()
+        .to_string();
+    if version.is_empty() {
+        return Err("manifest has no \"version\"".to_string());
+    }
+    // Declared assets: `theme.file` (Phase 1) and `source.file` (Phase 2 sandbox script) are the
+    // only asset slots in manifestVersion 1. Fetch before writing anything.
+    let mut assets: Vec<(String, String)> = Vec::new();
+    for pointer in ["/theme/file", "/source/file"] {
+        if let Some(file) = json.pointer(pointer).and_then(|v| v.as_str()) {
+            if !valid_asset_name(file) {
+                return Err(format!("declared asset \"{file}\" has an unsafe filename"));
+            }
+            let body =
+                fetch_text_capped(&client, &asset_url_for(&resolved.manifest_url, file)).await?;
+            assets.push((file.to_string(), body));
+        }
+    }
+    let dir = plugins_dir(&app)?.join(&id);
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    atomic_write(&dir.join("plugin.json"), &manifest_text)?;
+    for (name, body) in &assets {
+        atomic_write(&dir.join(name), body)?;
+    }
+    let installed_at = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map(|d| d.as_millis() as u64)
+        .unwrap_or(0);
+    let sidecar = serde_json::json!({
+        "source": resolved.display_source,
+        "ref": resolved.reff,
+        "version": version,
+        "installedAt": installed_at,
+    });
+    atomic_write(&dir.join(INSTALL_SIDECAR), &sidecar.to_string())?;
+    Ok(InstalledPackage { id, version })
+}
+
+#[derive(Serialize)]
+pub struct UpdateCheck {
+    pub current: String,
+    pub latest: String,
+    pub source: String,
+}
+
+/// MANUAL update check for an installed package: re-fetch just the manifest from the sidecar's
+/// recorded source and report both versions (the frontend compares — any difference counts as
+/// "update available"; downgrades are deliberate re-installs). Packages without a sidecar
+/// (hand-dropped folders) have nowhere to check against.
+#[tauri::command]
+pub async fn check_plugin_package_update(
+    app: tauri::AppHandle,
+    id: String,
+) -> Result<UpdateCheck, String> {
+    if !valid_name(&id) {
+        return Err("invalid package id".to_string());
+    }
+    let raw = fs::read_to_string(plugins_dir(&app)?.join(&id).join(INSTALL_SIDECAR))
+        .map_err(|_| "package was not installed from a URL".to_string())?;
+    let side: serde_json::Value =
+        serde_json::from_str(&raw).map_err(|_| "install record is corrupt".to_string())?;
+    let source = side
+        .get("source")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .to_string();
+    let reff = side.get("ref").and_then(|v| v.as_str()).unwrap_or("main");
+    let current = side
+        .get("version")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .to_string();
+    let url = manifest_url_from_sidecar(&source, reff)
+        .ok_or_else(|| "install record has an invalid source".to_string())?;
+    let client = install_http_client()?;
+    let manifest_text = fetch_text_capped(&client, &url).await?;
+    let json: serde_json::Value = serde_json::from_str(&manifest_text)
+        .map_err(|_| "remote plugin.json is not valid JSON".to_string())?;
+    let latest = json
+        .get("version")
+        .and_then(|v| v.as_str())
+        .unwrap_or_default()
+        .trim()
+        .to_string();
+    if latest.is_empty() {
+        return Err("remote manifest has no \"version\"".to_string());
+    }
+    Ok(UpdateCheck {
+        current,
+        latest,
+        source,
+    })
+}
+
+/// Delete `plugins/<id>/` (works for installed AND hand-dropped packages — it's just a dir
+/// delete). Ok even if it's already gone (idempotent, like the other deletes here).
+#[tauri::command]
+pub fn remove_plugin_package(app: tauri::AppHandle, id: String) -> Result<(), String> {
+    if !valid_name(&id) {
+        return Err("invalid package id".to_string());
+    }
+    match fs::remove_dir_all(plugins_dir(&app)?.join(&id)) {
+        Ok(()) => Ok(()),
+        Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(()),
+        Err(err) => Err(err.to_string()),
+    }
+}
+
+// ---- plugin packages: sandboxed source network proxy (Phase 2) ----------------------------------
+// A package's `source.js` runs in a QuickJS sandbox with ZERO capabilities; the frontend asks this
+// command to perform each fetch between the sandbox's two pure calls. The hosts allowlist is
+// re-read from the manifest ON DISK per request (server-side enforcement — a compromised webview
+// can't widen it), https only, GET only, redirects DISABLED (so the response host can never drift
+// off-allowlist), 10s timeout, 256 KiB body cap.
+
+/// PURE SEAM: is `url` an https URL whose host is a DOMAIN matching one of `hosts` exactly?
+/// Subdomains must be listed explicitly; IP literals, explicit ports, embedded credentials, and
+/// non-https schemes all fail. Comparison is ASCII-case-insensitive (URL hosts parse lowercased,
+/// but the manifest on disk is untrusted text).
+fn host_allowed(url: &str, hosts: &[String]) -> bool {
+    let Ok(u) = reqwest::Url::parse(url) else {
+        return false;
+    };
+    if u.scheme() != "https" || u.port().is_some() {
+        return false;
+    }
+    if !u.username().is_empty() || u.password().is_some() {
+        return false;
+    }
+    match u.domain() {
+        Some(d) => hosts.iter().any(|h| h.eq_ignore_ascii_case(d)),
+        None => false, // IP literal (or no host at all)
+    }
+}
+
+#[derive(Serialize)]
+pub struct PackageFetchResponse {
+    pub url: String,
+    pub status: u16,
+    pub body: String,
+}
+
+/// GET `url` on behalf of package `id`'s sandboxed source. Non-2xx responses are returned (with
+/// their status) rather than erroring — the sandbox's `transform` decides what a miss means; only
+/// transport/validation failures are `Err`.
+#[tauri::command]
+pub async fn package_fetch(
+    app: tauri::AppHandle,
+    id: String,
+    url: String,
+) -> Result<PackageFetchResponse, String> {
+    if !valid_name(&id) {
+        return Err("invalid package id".to_string());
+    }
+    let raw = fs::read_to_string(plugins_dir(&app)?.join(&id).join("plugin.json"))
+        .map_err(|_| "package manifest not found".to_string())?;
+    let json: serde_json::Value =
+        serde_json::from_str(&raw).map_err(|_| "package manifest is not valid JSON".to_string())?;
+    let hosts: Vec<String> = json
+        .pointer("/source/hosts")
+        .and_then(|v| v.as_array())
+        .map(|a| {
+            a.iter()
+                .filter_map(|x| x.as_str().map(str::to_string))
+                .collect()
+        })
+        .unwrap_or_default();
+    if hosts.is_empty() {
+        return Err("package declares no source hosts".to_string());
+    }
+    if !host_allowed(&url, &hosts) {
+        return Err(format!("url is not in the package's host allowlist: {url}"));
+    }
+    let client = reqwest::Client::builder()
+        .redirect(reqwest::redirect::Policy::none())
+        .timeout(std::time::Duration::from_secs(10))
+        .build()
+        .map_err(|e| e.to_string())?;
+    let resp = client
+        .get(&url)
+        .send()
+        .await
+        .map_err(|e| format!("GET {url} failed: {e}"))?;
+    let status = resp.status().as_u16();
+    if let Some(len) = resp.content_length()
+        && len > FETCH_CAP as u64
+    {
+        return Err(format!("{url} is too large ({len} bytes; cap {FETCH_CAP})"));
+    }
+    use futures_util::StreamExt;
+    let mut buf: Vec<u8> = Vec::new();
+    let mut stream = resp.bytes_stream();
+    while let Some(chunk) = stream.next().await {
+        let bytes = chunk.map_err(|e| format!("GET {url} failed mid-body: {e}"))?;
+        if buf.len() + bytes.len() > FETCH_CAP {
+            return Err(format!("{url} exceeded the {FETCH_CAP}-byte download cap"));
+        }
+        buf.extend_from_slice(&bytes);
+    }
+    let body = String::from_utf8(buf).map_err(|_| format!("{url} body is not valid UTF-8"))?;
+    Ok(PackageFetchResponse { url, status, body })
+}
+
+/// Seed a couple of example themes on first run so the picker has something to show
+/// (the default look needs no theme). No-op once `themes/` exists.
+pub fn seed_themes(app: &tauri::AppHandle) {
+    let dir = match themes_dir(app) {
+        Ok(d) => d,
+        Err(_) => return,
+    };
+    if dir.exists() {
+        return;
+    }
+    if fs::create_dir_all(&dir).is_err() {
+        return;
+    }
+    let samples: &[(&str, &str)] = &[
+        (
+            "amber",
+            ":root {\n\t--np-accent: #ffb000;\n\t--np-label: #ffd27f;\n\t--np-track: rgba(255, 176, 0, 0.18);\n}\n",
+        ),
+        (
+            "mono",
+            ":root {\n\t--np-accent: #d8dee9;\n\t--np-fg: #eceff4;\n\t--np-label: #9aa5b1;\n\t--np-track: rgba(255, 255, 255, 0.12);\n}\n",
+        ),
+    ];
+    for (name, css) in samples {
+        let _ = fs::write(dir.join(format!("{name}.css")), css);
+    }
+}
+
+/// Shared loop behind `watch_themes`/`watch_layout`/`watch_controls`: watch `dir` (non-recursive)
+/// on a dedicated thread for the app's lifetime, and for every filesystem event that passes
+/// `filter`, emit `event_name` then run `on_match` (the layout watcher's main-respawn hook; a
+/// no-op for the others). `label` tags the log lines. Best-effort: logs and returns on watcher
+/// failure, leaving live reload off for that file.
+fn watch_and_emit(
+    app: tauri::AppHandle,
+    dir: PathBuf,
+    label: &'static str,
+    event_name: &'static str,
+    filter: impl Fn(&notify::Event) -> bool + Send + 'static,
+    on_match: impl Fn(&tauri::AppHandle) + Send + 'static,
+) {
+    std::thread::spawn(move || {
+        let (tx, rx) = std::sync::mpsc::channel();
+        let mut watcher = match notify::recommended_watcher(move |res| {
+            let _ = tx.send(res);
+        }) {
+            Ok(watcher) => watcher,
+            Err(err) => {
+                log::error("watch", format!("{label} watcher init failed"))
+                    .field("error", err)
+                    .emit();
+                return;
+            }
+        };
+        if let Err(err) = watcher.watch(&dir, notify::RecursiveMode::NonRecursive) {
+            log::error("watch", format!("{label} watch failed"))
+                .field("error", err)
+                .emit();
+            return;
+        }
+        // Keep `watcher` alive by blocking on the channel for the app's lifetime.
+        for res in rx {
+            match res {
+                Ok(event) => {
+                    if filter(&event) {
+                        let _ = app.emit(event_name, ());
+                        on_match(&app);
+                    }
+                }
+                Err(err) => log::warn("watch", format!("{label} watch error"))
+                    .field("error", err)
+                    .emit(),
+            }
+        }
+    });
+}
+
+/// Watch `themes/` and emit `themes_changed` so the frontend live-reloads the active theme.
+pub fn watch_themes(app: tauri::AppHandle) -> Result<(), String> {
+    let dir = themes_dir(&app)?;
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    // Only react to `*.css` files (mirrors the layout/controls watchers' filter), so the
+    // atomic-write `*.css.tmp` sidecar and any non-theme file dropped in the folder don't
+    // spuriously trigger a reload.
+    watch_and_emit(
+        app,
+        dir,
+        "themes",
+        THEMES_CHANGED_EVENT,
+        |event| {
+            event
+                .paths
+                .iter()
+                .any(|p| p.extension().and_then(|x| x.to_str()) == Some("css"))
+        },
+        |_| {},
+    );
+    Ok(())
+}
+
+/// Re-create the primary `main` overlay window (born hidden) after it was torn down to reclaim its
+/// renderer (overlay.ts `setMainWindowVisible(false)`). Mirrors the static `main` config in
+/// tauri.conf.json; the frontend reveals it — or re-destroys it if the primary is still empty — once
+/// its Canvas init runs. Must be called on the main thread (window creation). Best-effort: logs.
+fn respawn_main_hidden(app: &tauri::AppHandle) {
+    match tauri::WebviewWindowBuilder::new(app, "main", tauri::WebviewUrl::App("/".into()))
+        .title("WidgetSack")
+        .inner_size(300.0, 400.0)
+        .transparent(true)
+        .shadow(false)
+        .decorations(false)
+        .always_on_top(false)
+        .always_on_bottom(true)
+        .skip_taskbar(true)
+        .visible(false)
+        .disable_drag_drop_handler()
+        .build()
+    {
+        Ok(_) => log::info(
+            "reclaim",
+            "respawned primary overlay (main) after external layout change",
+        )
+        .emit(),
+        Err(err) => log::warn("reclaim", "failed to respawn main")
+            .field("error", err)
+            .emit(),
+    }
+}
+
+/// Watch the config dir for changes to widgets.json and emit `layout_changed`
+/// so the frontend can live-reload. Best-effort: logs and returns on failure.
+pub fn watch_layout(app: tauri::AppHandle) -> Result<(), String> {
+    let path = layout_path(&app)?;
+    let dir = path
+        .parent()
+        .ok_or_else(|| "layout path has no parent".to_string())?
+        .to_path_buf();
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    watch_and_emit(
+        app,
+        dir,
+        "layout",
+        LAYOUT_CHANGED_EVENT,
+        move |event| {
+            event
+                .paths
+                .iter()
+                .any(|p| p.file_name() == path.file_name())
+        },
+        |app| {
+            // Reclaim: `main` is DESTROYED (not hidden) to free its renderer when the primary
+            // monitor is empty (overlay.ts setMainWindowVisible). While it's gone, no window
+            // drives overlay reconcile, so an external edit to widgets.json that re-populates
+            // the primary would never bring the primary overlay back. Respawn `main` (born
+            // hidden) so its own Canvas init decides: reveal if the primary now has widgets, or
+            // self-destroy if still empty. Skipped while the studio is open — the studio
+            // recreates `main` on close, so we avoid spawn/destroy churn during live editing.
+            // Window creation must run on the main thread.
+            let app_for_respawn = app.clone();
+            let _ = app.run_on_main_thread(move || {
+                if app_for_respawn.get_webview_window("main").is_none()
+                    && app_for_respawn.get_webview_window("studio").is_none()
+                {
+                    respawn_main_hidden(&app_for_respawn);
+                }
+            });
+        },
+    );
+    Ok(())
+}
+
+/// Watch the config dir for changes to controls.json and emit `controls_changed` so the frontend
+/// can live-reload remaps (e.g. an external edit, or another window saving). Mirrors `watch_layout`.
+pub fn watch_controls(app: tauri::AppHandle) -> Result<(), String> {
+    let path = controls_path(&app)?;
+    let dir = path
+        .parent()
+        .ok_or_else(|| "controls path has no parent".to_string())?
+        .to_path_buf();
+    fs::create_dir_all(&dir).map_err(|e| e.to_string())?;
+    watch_and_emit(
+        app,
+        dir,
+        "controls",
+        CONTROLS_CHANGED_EVENT,
+        move |event| {
+            event
+                .paths
+                .iter()
+                .any(|p| p.file_name() == path.file_name())
+        },
+        |_| {},
+    );
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{valid_name, version_is_newer};
+
+    #[test]
+    fn version_is_newer_compares_numerically() {
+        assert!(version_is_newer("0.0.42", "0.0.41"));
+        assert!(version_is_newer("0.1.0", "0.0.41")); // 0.1.0 > 0.0.41, not string compare
+        assert!(version_is_newer("1.0.0", "0.9.9"));
+        assert!(!version_is_newer("0.0.41", "0.0.41")); // equal → no update
+        assert!(!version_is_newer("0.0.40", "0.0.41")); // older
+    }
+
+    #[test]
+    fn version_is_newer_tolerates_v_prefix_and_suffixes() {
+        assert!(version_is_newer("v0.0.42", "0.0.41"));
+        assert!(!version_is_newer("0.0.41-rc1", "0.0.41")); // pre-release suffix stripped → equal
+        assert!(!version_is_newer("garbage", "0.0.1")); // unparseable → (0,0,0), no false update
+    }
+
+    #[test]
+    fn valid_name_accepts_plain_tokens() {
+        assert!(valid_name("amber"));
+        assert!(valid_name("My Theme 2"));
+        assert!(valid_name("dark_mode-v2"));
+        assert!(valid_name(&"x".repeat(64)));
+    }
+
+    #[test]
+    fn valid_name_rejects_unsafe_or_oversized() {
+        assert!(!valid_name("")); // empty
+        assert!(!valid_name("..")); // traversal
+        assert!(!valid_name("a/b")); // separator
+        assert!(!valid_name("a\\b")); // separator
+        assert!(!valid_name("a..b")); // contains ..
+        assert!(!valid_name("name.css")); // dot (extension is added by the caller)
+        assert!(!valid_name("a:b")); // reserved char
+        assert!(!valid_name("tab\tname")); // control char
+        assert!(!valid_name("café")); // non-ASCII
+        assert!(!valid_name(&"x".repeat(65))); // too long
+        assert!(!valid_name(" lead")); // leading space (Windows trims → name collision)
+        assert!(!valid_name("trail ")); // trailing space
+        assert!(!valid_name("   ")); // all whitespace
+    }
+
+    #[test]
+    fn valid_asset_name_requires_css_json_or_js_and_no_traversal() {
+        assert!(super::valid_asset_name("theme.css"));
+        assert!(super::valid_asset_name("extra.JSON")); // case-insensitive ext
+        assert!(super::valid_asset_name("My Theme 2.css")); // spaces ok (valid_name stem)
+        assert!(super::valid_asset_name("source.js")); // Phase 2 sandbox script
+        assert!(super::valid_asset_name("Source.JS")); // case-insensitive ext
+        assert!(!super::valid_asset_name("theme.css.tmp")); // wrong ext (last dot wins)
+        assert!(!super::valid_asset_name("evil.tmp.css")); // stem contains a dot
+        assert!(!super::valid_asset_name("../theme.css")); // traversal
+        assert!(!super::valid_asset_name("..css")); // empty/.. stem
+        assert!(!super::valid_asset_name("a/b.css")); // separator
+        assert!(!super::valid_asset_name("a\\b.css")); // separator
+        assert!(!super::valid_asset_name("theme.exe")); // disallowed ext
+        assert!(!super::valid_asset_name("source.mjs")); // js only, not mjs/cjs
+        assert!(!super::valid_asset_name("noext")); // no extension
+        assert!(!super::valid_asset_name(".css")); // empty stem
+        assert!(!super::valid_asset_name("")); // empty
+    }
+
+    #[test]
+    fn host_allowed_matches_exact_https_domains_only() {
+        let hosts = vec!["api.open-meteo.com".to_string(), "example.org".to_string()];
+        assert!(super::host_allowed(
+            "https://api.open-meteo.com/v1/forecast?latitude=1.35",
+            &hosts
+        ));
+        // URL hosts parse case-folded; a SHOUTING url still matches.
+        assert!(super::host_allowed("https://API.OPEN-METEO.COM/v1", &hosts));
+        // An explicit default port is elided by the parser → still allowed.
+        assert!(super::host_allowed("https://example.org:443/", &hosts));
+        // Subdomains are NOT implied — they must be listed.
+        assert!(!super::host_allowed("https://sub.example.org/", &hosts));
+        assert!(!super::host_allowed(
+            "https://example.org.evil.com/",
+            &hosts
+        ));
+        // https only, no explicit ports, no credentials, no IP literals.
+        assert!(!super::host_allowed("http://api.open-meteo.com/", &hosts));
+        assert!(!super::host_allowed(
+            "https://api.open-meteo.com:8443/",
+            &hosts
+        ));
+        assert!(!super::host_allowed("https://user@example.org/", &hosts));
+        assert!(!super::host_allowed(
+            "https://93.184.216.34/",
+            &["93.184.216.34".to_string()]
+        ));
+        // Host case-insensitivity also covers an uppercased (hand-edited) manifest entry.
+        assert!(super::host_allowed(
+            "https://example.org/",
+            &["EXAMPLE.ORG".to_string()]
+        ));
+        assert!(!super::host_allowed(
+            "https://evil.com/?q=example.org",
+            &hosts
+        ));
+        assert!(!super::host_allowed("not a url", &hosts));
+        assert!(!super::host_allowed("https://example.org/", &[]));
+    }
+
+    #[test]
+    fn resolve_package_source_accepts_the_documented_forms() {
+        // owner/repo shorthand → raw manifest on main.
+        let r = super::resolve_package_source("acme/widget-pack").unwrap();
+        assert_eq!(
+            r.manifest_url,
+            "https://raw.githubusercontent.com/acme/widget-pack/main/plugin.json"
+        );
+        assert_eq!(r.display_source, "acme/widget-pack");
+        assert_eq!(r.reff, "main");
+        // Full repo URL (trailing slash + surrounding whitespace tolerated) → same resolution.
+        let r = super::resolve_package_source(" https://github.com/acme/widget-pack/ ").unwrap();
+        assert_eq!(
+            r.manifest_url,
+            "https://raw.githubusercontent.com/acme/widget-pack/main/plugin.json"
+        );
+        assert_eq!(r.display_source, "acme/widget-pack");
+        // /tree/<ref> pins the ref; slash-y branch names survive the splitn.
+        let r = super::resolve_package_source("https://github.com/acme/widget-pack/tree/feature/x")
+            .unwrap();
+        assert_eq!(
+            r.manifest_url,
+            "https://raw.githubusercontent.com/acme/widget-pack/feature/x/plugin.json"
+        );
+        assert_eq!(r.reff, "feature/x");
+        // Any https URL ending in /plugin.json is used verbatim with ref "direct".
+        let r =
+            super::resolve_package_source("https://example.com/packs/clock/plugin.json").unwrap();
+        assert_eq!(
+            r.manifest_url,
+            "https://example.com/packs/clock/plugin.json"
+        );
+        assert_eq!(
+            r.display_source,
+            "https://example.com/packs/clock/plugin.json"
+        );
+        assert_eq!(r.reff, "direct");
+    }
+
+    #[test]
+    fn resolve_package_source_rejects_everything_else() {
+        assert!(super::resolve_package_source("http://github.com/a/b").is_none()); // plain http
+        assert!(super::resolve_package_source("http://example.com/plugin.json").is_none());
+        assert!(super::resolve_package_source("https://example.com/pack").is_none()); // no plugin.json
+        assert!(super::resolve_package_source("https://github.com/onlyowner").is_none());
+        assert!(super::resolve_package_source("https://github.com/a/b/blob/main/x").is_none());
+        assert!(super::resolve_package_source("a/b/c").is_none()); // shorthand has ONE slash
+        assert!(super::resolve_package_source("owner").is_none());
+        assert!(super::resolve_package_source("ftp://a/b").is_none()); // non-https scheme
+        assert!(super::resolve_package_source("a/../b").is_none()); // traversal in a segment
+        assert!(super::resolve_package_source("ow ner/repo").is_none()); // bad owner char
+        assert!(super::resolve_package_source("").is_none());
+    }
+
+    #[test]
+    fn asset_url_for_swaps_the_last_segment() {
+        assert_eq!(
+            super::asset_url_for(
+                "https://raw.githubusercontent.com/a/b/main/plugin.json",
+                "sky.css"
+            ),
+            "https://raw.githubusercontent.com/a/b/main/sky.css"
+        );
+        assert_eq!(
+            super::asset_url_for("https://example.com/packs/clock/plugin.json", "extra.json"),
+            "https://example.com/packs/clock/extra.json"
+        );
+    }
+
+    #[test]
+    fn manifest_url_from_sidecar_rederives_or_fails_closed() {
+        // GitHub provenance: owner/repo + recorded ref.
+        assert_eq!(
+            super::manifest_url_from_sidecar("acme/pack", "v2").as_deref(),
+            Some("https://raw.githubusercontent.com/acme/pack/v2/plugin.json")
+        );
+        // Direct provenance: the URL itself, re-validated through resolve_package_source.
+        assert_eq!(
+            super::manifest_url_from_sidecar("https://example.com/p/plugin.json", "direct")
+                .as_deref(),
+            Some("https://example.com/p/plugin.json")
+        );
+        // Tampered sidecars fail closed.
+        assert!(
+            super::manifest_url_from_sidecar("http://example.com/p/plugin.json", "direct")
+                .is_none()
+        );
+        assert!(super::manifest_url_from_sidecar("https://example.com/p", "direct").is_none());
+        assert!(super::manifest_url_from_sidecar("acme/pack", "..").is_none());
+        assert!(super::manifest_url_from_sidecar("acme", "main").is_none());
+        assert!(super::manifest_url_from_sidecar("a/../b", "main").is_none());
+    }
+
+    #[test]
+    fn install_sidecar_is_unreachable_as_an_asset() {
+        // The sidecar must never be readable via read_plugin_package_asset or declarable as a
+        // manifest asset — its dotted stem fails valid_name.
+        assert!(!super::valid_asset_name(super::INSTALL_SIDECAR));
+    }
+
+    #[test]
+    fn valid_wallpaper_name_requires_media_ext_and_no_traversal() {
+        assert!(super::valid_wallpaper_name("loop.mp4"));
+        assert!(super::valid_wallpaper_name("My Wallpaper 2.PNG")); // case-insensitive ext, spaces ok
+        assert!(super::valid_wallpaper_name("clip.webm"));
+        assert!(!super::valid_wallpaper_name("notes.txt")); // not a media ext
+        assert!(!super::valid_wallpaper_name("noext")); // no extension
+        assert!(!super::valid_wallpaper_name("../escape.png")); // traversal
+        assert!(!super::valid_wallpaper_name("sub/dir.png")); // separator
+        assert!(!super::valid_wallpaper_name("a\\b.png")); // separator
+        assert!(!super::valid_wallpaper_name("")); // empty
+    }
+}
diff --git a/widgetsack/src/control.rs b/widgetsack/src/control.rs
index 803e717..f8621dc 100644
--- a/widgetsack/src/control.rs
+++ b/widgetsack/src/control.rs
@@ -18,15 +18,15 @@ use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;
 
-use serde_json::{json, Value};
+use serde_json::{Value, json};
 use tauri::async_runtime::{JoinHandle, Mutex};
 use tauri::{AppHandle, Manager, Runtime};
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio::net::{TcpListener, TcpStream};
 use tokio::sync::Semaphore;
 
-use crate::log;
 use crate::AppState;
+use crate::log;
 
 const MAX_HEAD: usize = 16 * 1024;
 const MAX_BODY: usize = 256 * 1024;
@@ -244,7 +244,12 @@ async fn handle_conn<R: Runtime>(app: AppHandle<R>, token: String, mut stream: T
     }
     // Everything else needs the bearer token.
     if !bearer_ok(&head.headers, &token) {
-        write_resp(&mut stream, "401 Unauthorized", &json!({ "error": "unauthorized" })).await;
+        write_resp(
+            &mut stream,
+            "401 Unauthorized",
+            &json!({ "error": "unauthorized" }),
+        )
+        .await;
         return;
     }
 
@@ -261,16 +266,31 @@ async fn handle_conn<R: Runtime>(app: AppHandle<R>, token: String, mut stream: T
                 .iter()
                 .filter_map(|r| serde_json::to_value(r).ok())
                 .collect();
-            write_resp(&mut stream, "200 OK", &json!(now_playing_from_records(&values))).await;
+            write_resp(
+                &mut stream,
+                "200 OK",
+                &json!(now_playing_from_records(&values)),
+            )
+            .await;
         }
         ("POST", "/media") => {
             if !is_json(&head.headers) {
-                write_resp(&mut stream, "415 Unsupported Media Type", &json!({ "error": "send application/json" })).await;
+                write_resp(
+                    &mut stream,
+                    "415 Unsupported Media Type",
+                    &json!({ "error": "send application/json" }),
+                )
+                .await;
                 return;
             }
             let v: Value = serde_json::from_slice(&body).unwrap_or(Value::Null);
             let Some(action) = v["action"].as_str().map(String::from) else {
-                write_resp(&mut stream, "400 Bad Request", &json!({ "error": "missing action" })).await;
+                write_resp(
+                    &mut stream,
+                    "400 Bad Request",
+                    &json!({ "error": "missing action" }),
+                )
+                .await;
                 return;
             };
             let source = v["source"].as_str().map(String::from);
@@ -282,23 +302,42 @@ async fn handle_conn<R: Runtime>(app: AppHandle<R>, token: String, mut stream: T
         }
         ("POST", "/ha") => {
             if !is_json(&head.headers) {
-                write_resp(&mut stream, "415 Unsupported Media Type", &json!({ "error": "send application/json" })).await;
+                write_resp(
+                    &mut stream,
+                    "415 Unsupported Media Type",
+                    &json!({ "error": "send application/json" }),
+                )
+                .await;
                 return;
             }
             let v: Value = serde_json::from_slice(&body).unwrap_or(Value::Null);
             let domain = v["domain"].as_str().unwrap_or("").to_string();
             let service = v["service"].as_str().unwrap_or("").to_string();
             if domain.is_empty() || service.is_empty() {
-                write_resp(&mut stream, "400 Bad Request", &json!({ "error": "missing domain/service" })).await;
+                write_resp(
+                    &mut stream,
+                    "400 Bad Request",
+                    &json!({ "error": "missing domain/service" }),
+                )
+                .await;
                 return;
             }
             let data = v.get("data").cloned().unwrap_or_else(|| json!({}));
             match crate::ha::ha_call_service(app.clone(), domain, service, data).await {
-                Ok(res) => write_resp(&mut stream, "200 OK", &json!({ "ok": true, "result": res })).await,
+                Ok(res) => {
+                    write_resp(&mut stream, "200 OK", &json!({ "ok": true, "result": res })).await
+                }
                 Err(e) => write_resp(&mut stream, "502 Bad Gateway", &json!({ "error": e })).await,
             }
         }
-        _ => write_resp(&mut stream, "404 Not Found", &json!({ "error": "not found" })).await,
+        _ => {
+            write_resp(
+                &mut stream,
+                "404 Not Found",
+                &json!({ "error": "not found" }),
+            )
+            .await
+        }
     }
 }
 
@@ -308,7 +347,9 @@ async fn run_control_server<R: Runtime>(app: AppHandle<R>, listener: TcpListener
     let token = gen_token();
     let url = format!("http://127.0.0.1:{port}");
     write_control_file(&app, &url, &token);
-    log::info("control", "agent control listening").field("url", &url).emit();
+    log::info("control", "agent control listening")
+        .field("url", &url)
+        .emit();
 
     let sem = Arc::new(Semaphore::new(MAX_CONNS));
     loop {
@@ -327,7 +368,9 @@ async fn run_control_server<R: Runtime>(app: AppHandle<R>, listener: TcpListener
                 });
             }
             Err(e) => {
-                log::warn("control", "accept failed").field("error", e.to_string()).emit();
+                log::warn("control", "accept failed")
+                    .field("error", e.to_string())
+                    .emit();
             }
         }
     }
@@ -355,14 +398,18 @@ pub async fn start_if_enabled<R: Runtime>(app: AppHandle<R>, state: &ControlStat
     let listener = match TcpListener::bind("127.0.0.1:0").await {
         Ok(l) => l,
         Err(e) => {
-            log::error("control", "bind failed").field("error", e.to_string()).emit();
+            log::error("control", "bind failed")
+                .field("error", e.to_string())
+                .emit();
             return;
         }
     };
     let port = match listener.local_addr() {
         Ok(a) => a.port(),
         Err(e) => {
-            log::error("control", "local_addr failed").field("error", e.to_string()).emit();
+            log::error("control", "local_addr failed")
+                .field("error", e.to_string())
+                .emit();
             return;
         }
     };
diff --git a/widgetsack/src/ddc.rs b/widgetsack/src/ddc.rs
new file mode 100644
index 0000000..66c7e84
--- /dev/null
+++ b/widgetsack/src/ddc.rs
@@ -0,0 +1,458 @@
+//! DDC/CI monitor input-source switcher — the anti-corruption edge for the Monitor Switch widget.
+//!
+//! Switching a monitor's active input (HDMI ↔ DisplayPort ↔ …) is MCCS **VCP feature 0x60**
+//! ("Input Select") sent over the DDC/CI I²C side-channel of the video cable, via the Win32 dxva2
+//! Physical Monitor API. As with `display.rs`/`listener.rs`, the `unsafe` Win32 calls are quarantined
+//! here; everything the rest of the app sees is `widgetsack`'s own `MonitorInputs` (serialized across
+//! the bridge) keyed on the same GDI device name (`\\.\DISPLAYn`) the overlays/studio already use.
+//!
+//! The only real logic — parsing the monitor's capabilities string for its supported 0x60 values — is
+//! the pure, cross-platform, unit-tested seam (`parse_vcp60_capabilities`).
+//!
+//! Caveats baked into the design:
+//! - **Blocking + slow.** DDC reads take 100–300 ms and can hang on a flaky monitor, so the commands
+//!   run on a `spawn_blocking` thread (never the main/UI thread) and only DDC-query the ONE requested
+//!   `target` monitor (the others return their OS display mode only — that's cheap).
+//! - **Vendor-specific values.** 0x60 codes are nominally standardised (0x0F DP, 0x11 HDMI1, …) but
+//!   widely deviate, so we always parse the monitor's own capability list rather than assume.
+//!
+//! Bridge contract: `MonitorInputs` mirrors `MonitorInputs` in `client/src/lib/ddc/monitors.ts`;
+//! the command names (`list_monitor_inputs`, `set_monitor_input`) must match the frontend.
+
+use serde::Serialize;
+
+/// One monitor's input-switching state for the Monitor Switch widget. Mirrors `MonitorInputs` in
+/// `client/src/lib/ddc/monitors.ts`. Keyed by `gdi` (`\\.\DISPLAYn`). `current_input` / `supported`
+/// are DDC/CI (VCP 0x60) and are only filled for the queried `target` (DDC reads are slow); other
+/// monitors report `None` / empty. `width` / `height` / `refresh_hz` are the OS's current display mode
+/// (cheap, always filled — 0 if unknown). `friendly` is the EDID model name (may be empty).
+#[derive(Debug, Clone, Serialize)]
+pub struct MonitorInputs {
+    pub gdi: String,
+    pub friendly: String,
+    pub primary: bool,
+    pub current_input: Option<u32>,
+    pub supported: Vec<u32>,
+    pub width: u32,
+    pub height: u32,
+    pub refresh_hz: u32,
+}
+
+/// MCCS VCP feature code for "Input Select" — the one code this widget reads, writes, and parses.
+const VCP_INPUT_SELECT: u8 = 0x60;
+
+// --- Pure seam (unit-tested, no I/O, cross-platform) -------------------------------------------
+
+/// Parse a DDC/CI capabilities string for the supported VCP 0x60 (Input Select) values. A capabilities
+/// string looks like `(prot(monitor)type(lcd)…vcp(02 04 … 60(0F 11 12) AC)…)`; we locate the top-level
+/// `vcp(...)` block, then the `60(...)` group inside it, and read its space-separated hex bytes. Pure:
+/// returns `[]` when there's no `vcp` block or no `60(...)` group. Robust to a `0x60` byte appearing as
+/// a *value* of some other code (e.g. `14(60 …)`) — only a top-level `60` code is matched.
+pub fn parse_vcp60_capabilities(caps: &str) -> Vec<u32> {
+    let vcp = match vcp_block(caps) {
+        Some(v) => v,
+        None => return Vec::new(),
+    };
+    match value_group(&vcp, VCP_INPUT_SELECT) {
+        Some(list) => parse_hex_list(&list),
+        None => Vec::new(),
+    }
+}
+
+/// The inner text of the top-level `vcp(...)` group (case-insensitive tag), tracking nested parens to
+/// find the matching close. Capability strings are ASCII per the MCCS spec, so byte indices are fine.
+fn vcp_block(caps: &str) -> Option<String> {
+    let lower = caps.to_ascii_lowercase();
+    let tag = lower.find("vcp(")?;
+    let b = caps.as_bytes();
+    let mut i = tag + 4; // first char after "vcp("
+    let mut depth = 1usize;
+    let mut out = String::new();
+    while i < b.len() {
+        let c = b[i] as char;
+        match c {
+            '(' => {
+                depth += 1;
+                out.push(c);
+            }
+            ')' => {
+                depth -= 1;
+                if depth == 0 {
+                    return Some(out);
+                }
+                out.push(c);
+            }
+            _ => out.push(c),
+        }
+        i += 1;
+    }
+    None
+}
+
+/// Within a vcp block's inner text, return `code`'s parenthesised value list, e.g. for 0x60 in
+/// `… 60(01 03 11 12) …` returns `"01 03 11 12"`. Reads top-level hex tokens; a token followed by a
+/// `(...)` group carries a value list (whose contents are skipped as code candidates). `None` if the
+/// code is absent or has no value group.
+fn value_group(vcp: &str, code: u8) -> Option<String> {
+    let b = vcp.as_bytes();
+    let mut i = 0usize;
+    while i < b.len() {
+        if (b[i] as char).is_ascii_whitespace() {
+            i += 1;
+            continue;
+        }
+        // Read a hex token (a candidate VCP code).
+        let start = i;
+        while i < b.len() && (b[i] as char).is_ascii_hexdigit() {
+            i += 1;
+        }
+        if i == start {
+            // Not hex (some separator) — skip one char and retry.
+            i += 1;
+            continue;
+        }
+        let this = u8::from_str_radix(&vcp[start..i], 16).ok();
+        // Optional parenthesised value group immediately after the code.
+        if i < b.len() && b[i] as char == '(' {
+            i += 1; // past '('
+            let vstart = i;
+            let mut depth = 1usize;
+            while i < b.len() && depth > 0 {
+                match b[i] as char {
+                    '(' => depth += 1,
+                    ')' => {
+                        depth -= 1;
+                        if depth == 0 {
+                            break;
+                        }
+                    }
+                    _ => {}
+                }
+                i += 1;
+            }
+            let inner = &vcp[vstart..i];
+            if i < b.len() {
+                i += 1; // past ')'
+            }
+            if this == Some(code) {
+                return Some(inner.to_string());
+            }
+        }
+    }
+    None
+}
+
+/// Split a whitespace-separated list of hex byte values (`"01 03 11 12"`) into numbers; junk tokens
+/// are dropped. Pure.
+fn parse_hex_list(s: &str) -> Vec<u32> {
+    s.split_whitespace()
+        .filter_map(|t| u32::from_str_radix(t, 16).ok())
+        .collect()
+}
+
+// --- Tauri commands ----------------------------------------------------------------------------
+
+/// All monitors with their current/supported DDC input source (VCP 0x60) and current display mode.
+/// DDC reads are slow and can hang on a flaky monitor, so they run on a blocking thread and only for
+/// the requested `target` (a GDI device name; the primary monitor when blank/None) — every other
+/// monitor returns its display mode (resolution + refresh) only. Empty off-Windows.
+#[tauri::command]
+pub async fn list_monitor_inputs(target: Option<String>) -> Vec<MonitorInputs> {
+    #[cfg(target_os = "windows")]
+    {
+        tokio::task::spawn_blocking(move || enumerate_blocking(target))
+            .await
+            .unwrap_or_default()
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = target;
+        Vec::new()
+    }
+}
+
+/// Switch `target` (a GDI device name, `\\.\DISPLAYn`) to VCP 0x60 input `value`. Errs if the monitor
+/// can't be found or rejects the switch (DDC/CI disabled in the OSD, or an unsupported value). Runs on
+/// a blocking thread. Windows-only.
+#[tauri::command]
+pub async fn set_monitor_input(target: String, value: u32) -> Result<(), String> {
+    #[cfg(target_os = "windows")]
+    {
+        tokio::task::spawn_blocking(move || set_blocking(target, value))
+            .await
+            .map_err(|e| e.to_string())?
+    }
+    #[cfg(not(target_os = "windows"))]
+    {
+        let _ = (target, value);
+        Err("switching monitor input is only supported on Windows".into())
+    }
+}
+
+// --- Windows implementation (the unsafe Win32 edge) --------------------------------------------
+
+/// Collect every monitor's `HMONITOR` via `EnumDisplayMonitors`. The handles are only ever used on the
+/// thread that gathered them (inside `spawn_blocking`), so `HMONITOR`'s non-`Send` raw pointer is fine.
+#[cfg(target_os = "windows")]
+fn collect_hmonitors() -> Vec<windows::Win32::Graphics::Gdi::HMONITOR> {
+    use windows::Win32::Foundation::{LPARAM, RECT};
+    use windows::Win32::Graphics::Gdi::{EnumDisplayMonitors, HDC, HMONITOR};
+
+    unsafe extern "system" fn cb(
+        h: HMONITOR,
+        _dc: HDC,
+        _rc: *mut RECT,
+        data: LPARAM,
+    ) -> windows::core::BOOL {
+        // SAFETY: `data` carries the `&mut Vec<HMONITOR>` we hand to EnumDisplayMonitors below; it
+        // outlives the (synchronous) enumeration.
+        unsafe {
+            let v = &mut *(data.0 as *mut Vec<HMONITOR>);
+            v.push(h);
+        }
+        windows::core::BOOL(1) // keep enumerating
+    }
+
+    let mut handles: Vec<HMONITOR> = Vec::new();
+    let ptr = &mut handles as *mut Vec<HMONITOR>;
+    // SAFETY: standard EnumDisplayMonitors callback pattern; `ptr` is valid for the call.
+    unsafe {
+        let _ = EnumDisplayMonitors(None, None, Some(cb), LPARAM(ptr as isize));
+    }
+    handles
+}
+
+/// `(gdi device name, is-primary)` for an `HMONITOR`, or `None` if the info call fails / the name is
+/// blank. `MONITORINFOF_PRIMARY` is the low bit of `dwFlags` (the windows-rs metadata doesn't export
+/// the constant, so the bit is inlined).
+#[cfg(target_os = "windows")]
+fn monitor_gdi(h: windows::Win32::Graphics::Gdi::HMONITOR) -> Option<(String, bool)> {
+    use windows::Win32::Graphics::Gdi::{GetMonitorInfoW, MONITORINFO, MONITORINFOEXW};
+
+    let mut mi = MONITORINFOEXW::default();
+    mi.monitorInfo.cbSize = core::mem::size_of::<MONITORINFOEXW>() as u32;
+    // SAFETY: `cbSize` is set to the EX size so Win32 fills `szDevice`; the pointer is to the struct
+    // start (monitorInfo is its first field).
+    let ok = unsafe { GetMonitorInfoW(h, &mut mi.monitorInfo as *mut MONITORINFO) };
+    if !ok.as_bool() {
+        return None;
+    }
+    let gdi = crate::display::wide_to_string(&mi.szDevice);
+    if gdi.is_empty() {
+        return None;
+    }
+    let primary = (mi.monitorInfo.dwFlags & 1) != 0; // MONITORINFOF_PRIMARY
+    Some((gdi, primary))
+}
+
+/// The monitor's current display mode `(width, height, refresh_hz)` from `EnumDisplaySettingsW`,
+/// keyed by GDI device name. `(0, 0, 0)` if unknown. Cheap (no DDC).
+#[cfg(target_os = "windows")]
+fn current_mode(gdi: &str) -> (u32, u32, u32) {
+    use std::iter::once;
+    use windows::Win32::Graphics::Gdi::{DEVMODEW, ENUM_CURRENT_SETTINGS, EnumDisplaySettingsW};
+    use windows::core::PCWSTR;
+
+    let wide: Vec<u16> = gdi.encode_utf16().chain(once(0)).collect();
+    let mut dm = DEVMODEW {
+        dmSize: core::mem::size_of::<DEVMODEW>() as u16,
+        ..Default::default()
+    };
+    // SAFETY: `wide` is a NUL-terminated UTF-16 device name that outlives the call; `dm` is sized.
+    let ok = unsafe { EnumDisplaySettingsW(PCWSTR(wide.as_ptr()), ENUM_CURRENT_SETTINGS, &mut dm) };
+    if ok.as_bool() {
+        (dm.dmPelsWidth, dm.dmPelsHeight, dm.dmDisplayFrequency)
+    } else {
+        (0, 0, 0)
+    }
+}
+
+/// DDC-query one monitor: its current input (VCP 0x60) and the supported inputs parsed from its
+/// capabilities string. `None` if the monitor exposes no physical-monitor handle (DDC/CI unavailable).
+/// `current_input` is `None` when the 0x60 read fails; `supported` is empty when caps can't be read.
+#[cfg(target_os = "windows")]
+fn query_ddc(hmon: windows::Win32::Graphics::Gdi::HMONITOR) -> Option<(Option<u32>, Vec<u32>)> {
+    use windows::Win32::Devices::Display::{
+        CapabilitiesRequestAndCapabilitiesReply, DestroyPhysicalMonitors,
+        GetCapabilitiesStringLength, GetNumberOfPhysicalMonitorsFromHMONITOR,
+        GetPhysicalMonitorsFromHMONITOR, GetVCPFeatureAndVCPFeatureReply, PHYSICAL_MONITOR,
+    };
+
+    // SAFETY: dxva2 physical-monitor lifecycle — create handles, query, then always destroy them.
+    unsafe {
+        let mut count: u32 = 0;
+        GetNumberOfPhysicalMonitorsFromHMONITOR(hmon, &mut count).ok()?;
+        if count == 0 {
+            return None;
+        }
+        let mut monitors = vec![PHYSICAL_MONITOR::default(); count as usize];
+        GetPhysicalMonitorsFromHMONITOR(hmon, &mut monitors).ok()?;
+        let handle = monitors[0].hPhysicalMonitor;
+
+        // Current input (VCP 0x60). Returns i32: nonzero = success. The reply is a 16-bit value but
+        // input-select is a single byte; some monitors echo it into the high byte too (e.g. 0x0F0F for
+        // DisplayPort 0x0F), so mask to the low byte to match the capability list (0x0F/0x11/0x12…).
+        let mut current: u32 = 0;
+        let current_input =
+            if GetVCPFeatureAndVCPFeatureReply(handle, VCP_INPUT_SELECT, None, &mut current, None)
+                != 0
+            {
+                Some(current & 0xFF)
+            } else {
+                None
+            };
+
+        // Supported inputs from the capabilities string (ASCII, NUL-terminated).
+        let mut supported = Vec::new();
+        let mut len: u32 = 0;
+        if GetCapabilitiesStringLength(handle, &mut len) != 0 && len > 0 {
+            let mut buf = vec![0u8; len as usize];
+            if CapabilitiesRequestAndCapabilitiesReply(handle, &mut buf) != 0 {
+                let end = buf.iter().position(|&c| c == 0).unwrap_or(buf.len());
+                let caps = String::from_utf8_lossy(&buf[..end]);
+                supported = parse_vcp60_capabilities(&caps);
+            }
+        }
+
+        let _ = DestroyPhysicalMonitors(&monitors);
+        Some((current_input, supported))
+    }
+}
+
+#[cfg(target_os = "windows")]
+fn enumerate_blocking(target: Option<String>) -> Vec<MonitorInputs> {
+    struct Base {
+        h: windows::Win32::Graphics::Gdi::HMONITOR,
+        gdi: String,
+        primary: bool,
+        width: u32,
+        height: u32,
+        refresh: u32,
+    }
+
+    let friendly = crate::display::friendly_map();
+
+    // Cheap base info for every monitor (no DDC yet).
+    let mut bases: Vec<Base> = Vec::new();
+    for h in collect_hmonitors() {
+        if let Some((gdi, primary)) = monitor_gdi(h) {
+            let (width, height, refresh) = current_mode(&gdi);
+            bases.push(Base {
+                h,
+                gdi,
+                primary,
+                width,
+                height,
+                refresh,
+            });
+        }
+    }
+
+    // Resolve which monitor to DDC-query: the requested GDI name, else the primary, else the first.
+    let want = target.unwrap_or_default();
+    let target_idx = bases
+        .iter()
+        .position(|b| !want.is_empty() && b.gdi == want)
+        .or_else(|| bases.iter().position(|b| b.primary))
+        .or_else(|| (!bases.is_empty()).then_some(0));
+
+    bases
+        .iter()
+        .enumerate()
+        .map(|(idx, b)| {
+            let (current_input, supported) = if Some(idx) == target_idx {
+                query_ddc(b.h).unwrap_or((None, Vec::new()))
+            } else {
+                (None, Vec::new())
+            };
+            MonitorInputs {
+                gdi: b.gdi.clone(),
+                friendly: friendly.get(&b.gdi).cloned().unwrap_or_default(),
+                primary: b.primary,
+                current_input,
+                supported,
+                width: b.width,
+                height: b.height,
+                refresh_hz: b.refresh,
+            }
+        })
+        .collect()
+}
+
+#[cfg(target_os = "windows")]
+fn set_blocking(target: String, value: u32) -> Result<(), String> {
+    use windows::Win32::Devices::Display::{
+        DestroyPhysicalMonitors, GetNumberOfPhysicalMonitorsFromHMONITOR,
+        GetPhysicalMonitorsFromHMONITOR, PHYSICAL_MONITOR, SetVCPFeature,
+    };
+
+    if target.is_empty() {
+        return Err("no monitor specified".into());
+    }
+
+    // Find the HMONITOR whose GDI device name matches `target`.
+    let hmon = collect_hmonitors()
+        .into_iter()
+        .find(|&h| {
+            monitor_gdi(h)
+                .map(|(gdi, _)| gdi == target)
+                .unwrap_or(false)
+        })
+        .ok_or_else(|| format!("monitor {target} not found"))?;
+
+    // SAFETY: dxva2 physical-monitor lifecycle — create, set VCP 0x60, always destroy.
+    unsafe {
+        let mut count: u32 = 0;
+        GetNumberOfPhysicalMonitorsFromHMONITOR(hmon, &mut count).map_err(|e| e.to_string())?;
+        if count == 0 {
+            return Err("no physical monitor for this display (DDC/CI unavailable)".into());
+        }
+        let mut monitors = vec![PHYSICAL_MONITOR::default(); count as usize];
+        GetPhysicalMonitorsFromHMONITOR(hmon, &mut monitors).map_err(|e| e.to_string())?;
+        let rc = SetVCPFeature(monitors[0].hPhysicalMonitor, VCP_INPUT_SELECT, value);
+        let _ = DestroyPhysicalMonitors(&monitors);
+        if rc == 0 {
+            return Err(
+				"the monitor rejected the input switch (DDC/CI off in the OSD, or an unsupported value)"
+					.into(),
+			);
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_vcp60_input_list() {
+        let caps = "(prot(monitor)type(lcd)model(U2720Q)cmds(01 02 03)vcp(02 04 05 10 12 60(0F 11 12) AC B6)mccs_ver(2.1))";
+        assert_eq!(parse_vcp60_capabilities(caps), vec![0x0F, 0x11, 0x12]);
+    }
+
+    #[test]
+    fn no_vcp60_group_is_empty() {
+        let caps = "(prot(monitor)vcp(02 04 10 12))";
+        assert!(parse_vcp60_capabilities(caps).is_empty());
+    }
+
+    #[test]
+    fn missing_vcp_block_is_empty() {
+        assert!(parse_vcp60_capabilities("garbage").is_empty());
+        assert!(parse_vcp60_capabilities("").is_empty());
+    }
+
+    #[test]
+    fn case_insensitive_tag_and_hex() {
+        let caps = "(VCP(60(01 03 0f)))";
+        assert_eq!(parse_vcp60_capabilities(caps), vec![0x01, 0x03, 0x0F]);
+    }
+
+    #[test]
+    fn ignores_0x60_inside_other_value_groups() {
+        // 14(60 05) is colour-preset code 0x14 carrying value 0x60 — must NOT be read as the 0x60 list.
+        let caps = "(vcp(14(60 05) 60(11 12)))";
+        assert_eq!(parse_vcp60_capabilities(caps), vec![0x11, 0x12]);
+    }
+}
diff --git a/widgetsack/src/display.rs b/widgetsack/src/display.rs
index f3e8768..fe746d6 100644
--- a/widgetsack/src/display.rs
+++ b/widgetsack/src/display.rs
@@ -8,126 +8,149 @@
 //! device name the overlays/studio already use, so the frontend can append the friendly name to its
 //! monitor-switcher labels with a safe fallback when it's blank.
 
+use std::collections::HashMap;
+
 use serde::Serialize;
 
 /// One active display: its GDI device name (`\\.\DISPLAY1`) and the friendly/EDID name. `friendly` can
 /// be empty (virtual / RDP / nameless panels, or an API miss) — the caller falls back to `gdi` then.
 #[derive(Debug, Clone, Serialize)]
 pub struct DisplayName {
-	pub gdi: String,
-	pub friendly: String,
+    pub gdi: String,
+    pub friendly: String,
 }
 
 /// A fixed-size, NUL-terminated UTF-16 Win32 name buffer → a trimmed `String`. Pure seam (tested):
 /// stops at the first NUL, tolerates an unterminated buffer, and trims surrounding whitespace.
-fn wide_to_string(buf: &[u16]) -> String {
-	let len = buf.iter().position(|&c| c == 0).unwrap_or(buf.len());
-	String::from_utf16_lossy(&buf[..len]).trim().to_string()
+/// `pub(crate)` so peers that already hold a Win32 wide buffer (e.g. ddc.rs' `MONITORINFOEXW.szDevice`)
+/// decode it the same way instead of re-implementing the NUL/trim logic.
+pub(crate) fn wide_to_string(buf: &[u16]) -> String {
+    let len = buf.iter().position(|&c| c == 0).unwrap_or(buf.len());
+    String::from_utf16_lossy(&buf[..len]).trim().to_string()
 }
 
 /// All active displays with their friendly names. Best-effort: any Win32 failure yields the entries
 /// gathered so far (or none), never an error — this only enriches a label.
 #[tauri::command]
 pub fn list_display_names() -> Vec<DisplayName> {
-	enumerate()
+    enumerate()
 }
 
 #[cfg(target_os = "windows")]
 fn enumerate() -> Vec<DisplayName> {
-	use windows::Win32::Devices::Display::{
-		DisplayConfigGetDeviceInfo, GetDisplayConfigBufferSizes, QueryDisplayConfig,
-		DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME, DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME,
-		DISPLAYCONFIG_MODE_INFO, DISPLAYCONFIG_PATH_INFO, DISPLAYCONFIG_SOURCE_DEVICE_NAME,
-		DISPLAYCONFIG_TARGET_DEVICE_NAME, QDC_ONLY_ACTIVE_PATHS,
-	};
-	use windows::Win32::Foundation::ERROR_SUCCESS;
-
-	let mut out = Vec::new();
-	unsafe {
-		// Size the path/mode arrays for the currently-active topology, then fetch them.
-		let mut n_paths: u32 = 0;
-		let mut n_modes: u32 = 0;
-		if GetDisplayConfigBufferSizes(QDC_ONLY_ACTIVE_PATHS, &mut n_paths, &mut n_modes)
-			!= ERROR_SUCCESS
-		{
-			return out;
-		}
-		let mut paths = vec![DISPLAYCONFIG_PATH_INFO::default(); n_paths as usize];
-		let mut modes = vec![DISPLAYCONFIG_MODE_INFO::default(); n_modes as usize];
-		if QueryDisplayConfig(
-			QDC_ONLY_ACTIVE_PATHS,
-			&mut n_paths,
-			paths.as_mut_ptr(),
-			&mut n_modes,
-			modes.as_mut_ptr(),
-			None,
-		) != ERROR_SUCCESS
-		{
-			return out;
-		}
-		paths.truncate(n_paths as usize);
-
-		for p in &paths {
-			// Source → the GDI device name (\\.\DISPLAYn): the key the overlays/studio share.
-			let mut src = DISPLAYCONFIG_SOURCE_DEVICE_NAME::default();
-			src.header.r#type = DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME;
-			src.header.size = core::mem::size_of::<DISPLAYCONFIG_SOURCE_DEVICE_NAME>() as u32;
-			src.header.adapterId = p.sourceInfo.adapterId;
-			src.header.id = p.sourceInfo.id;
-			// DisplayConfigGetDeviceInfo returns a Win32 LONG; ERROR_SUCCESS (0) on success.
-			if DisplayConfigGetDeviceInfo(&mut src.header) != 0 {
-				continue;
-			}
-			let gdi = wide_to_string(&src.viewGdiDeviceName);
-			if gdi.is_empty() {
-				continue;
-			}
-
-			// Target → the friendly/EDID name. Best-effort: a failure or blank name just leaves it empty.
-			let mut tgt = DISPLAYCONFIG_TARGET_DEVICE_NAME::default();
-			tgt.header.r#type = DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME;
-			tgt.header.size = core::mem::size_of::<DISPLAYCONFIG_TARGET_DEVICE_NAME>() as u32;
-			tgt.header.adapterId = p.targetInfo.adapterId;
-			tgt.header.id = p.targetInfo.id;
-			let friendly = if DisplayConfigGetDeviceInfo(&mut tgt.header) == 0 {
-				wide_to_string(&tgt.monitorFriendlyDeviceName)
-			} else {
-				String::new()
-			};
-
-			out.push(DisplayName { gdi, friendly });
-		}
-	}
-	out
+    use windows::Win32::Devices::Display::{
+        DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME, DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME,
+        DISPLAYCONFIG_MODE_INFO, DISPLAYCONFIG_PATH_INFO, DISPLAYCONFIG_SOURCE_DEVICE_NAME,
+        DISPLAYCONFIG_TARGET_DEVICE_NAME, DisplayConfigGetDeviceInfo, GetDisplayConfigBufferSizes,
+        QDC_ONLY_ACTIVE_PATHS, QueryDisplayConfig,
+    };
+    use windows::Win32::Foundation::ERROR_SUCCESS;
+
+    let mut out = Vec::new();
+    unsafe {
+        // Size the path/mode arrays for the currently-active topology, then fetch them.
+        let mut n_paths: u32 = 0;
+        let mut n_modes: u32 = 0;
+        if GetDisplayConfigBufferSizes(QDC_ONLY_ACTIVE_PATHS, &mut n_paths, &mut n_modes)
+            != ERROR_SUCCESS
+        {
+            return out;
+        }
+        let mut paths = vec![DISPLAYCONFIG_PATH_INFO::default(); n_paths as usize];
+        let mut modes = vec![DISPLAYCONFIG_MODE_INFO::default(); n_modes as usize];
+        if QueryDisplayConfig(
+            QDC_ONLY_ACTIVE_PATHS,
+            &mut n_paths,
+            paths.as_mut_ptr(),
+            &mut n_modes,
+            modes.as_mut_ptr(),
+            None,
+        ) != ERROR_SUCCESS
+        {
+            return out;
+        }
+        paths.truncate(n_paths as usize);
+
+        for p in &paths {
+            // Source → the GDI device name (\\.\DISPLAYn): the key the overlays/studio share.
+            let mut src = DISPLAYCONFIG_SOURCE_DEVICE_NAME::default();
+            src.header.r#type = DISPLAYCONFIG_DEVICE_INFO_GET_SOURCE_NAME;
+            src.header.size = core::mem::size_of::<DISPLAYCONFIG_SOURCE_DEVICE_NAME>() as u32;
+            src.header.adapterId = p.sourceInfo.adapterId;
+            src.header.id = p.sourceInfo.id;
+            // DisplayConfigGetDeviceInfo returns a Win32 LONG; ERROR_SUCCESS (0) on success.
+            if DisplayConfigGetDeviceInfo(&mut src.header) != 0 {
+                continue;
+            }
+            let gdi = wide_to_string(&src.viewGdiDeviceName);
+            if gdi.is_empty() {
+                continue;
+            }
+
+            // Target → the friendly/EDID name. Best-effort: a failure or blank name just leaves it empty.
+            let mut tgt = DISPLAYCONFIG_TARGET_DEVICE_NAME::default();
+            tgt.header.r#type = DISPLAYCONFIG_DEVICE_INFO_GET_TARGET_NAME;
+            tgt.header.size = core::mem::size_of::<DISPLAYCONFIG_TARGET_DEVICE_NAME>() as u32;
+            tgt.header.adapterId = p.targetInfo.adapterId;
+            tgt.header.id = p.targetInfo.id;
+            let friendly = if DisplayConfigGetDeviceInfo(&mut tgt.header) == 0 {
+                wide_to_string(&tgt.monitorFriendlyDeviceName)
+            } else {
+                String::new()
+            };
+
+            out.push(DisplayName { gdi, friendly });
+        }
+    }
+    out
 }
 
 #[cfg(not(target_os = "windows"))]
 fn enumerate() -> Vec<DisplayName> {
-	Vec::new()
+    Vec::new()
+}
+
+/// GDI device name (`\\.\DISPLAYn`) → friendly/EDID name, for callers that already have a GDI name and
+/// want the human label without re-running the CCD enumeration themselves (ddc.rs labels the monitor
+/// switcher this way). Best-effort: empty map on failure, and blank-friendly entries are dropped so a
+/// missing key cleanly means "no friendly name known" (the caller falls back to the GDI tag).
+pub(crate) fn friendly_map() -> HashMap<String, String> {
+    enumerate()
+        .into_iter()
+        .filter(|d| !d.friendly.is_empty())
+        .map(|d| (d.gdi, d.friendly))
+        .collect()
 }
 
 #[cfg(test)]
 mod tests {
-	use super::*;
-
-	#[test]
-	fn wide_to_string_stops_at_first_nul() {
-		// "DELL\0XX\0" → only the run before the first NUL.
-		let buf: [u16; 8] = [
-			b'D' as u16, b'E' as u16, b'L' as u16, b'L' as u16, 0, b'X' as u16, b'X' as u16, 0,
-		];
-		assert_eq!(wide_to_string(&buf), "DELL");
-	}
-
-	#[test]
-	fn wide_to_string_trims_and_tolerates_no_nul() {
-		let buf: [u16; 4] = [b' ' as u16, b'L' as u16, b'G' as u16, b' ' as u16];
-		assert_eq!(wide_to_string(&buf), "LG");
-	}
-
-	#[test]
-	fn wide_to_string_empty_is_empty() {
-		assert_eq!(wide_to_string(&[0u16]), "");
-		assert_eq!(wide_to_string(&[]), "");
-	}
+    use super::*;
+
+    #[test]
+    fn wide_to_string_stops_at_first_nul() {
+        // "DELL\0XX\0" → only the run before the first NUL.
+        let buf: [u16; 8] = [
+            b'D' as u16,
+            b'E' as u16,
+            b'L' as u16,
+            b'L' as u16,
+            0,
+            b'X' as u16,
+            b'X' as u16,
+            0,
+        ];
+        assert_eq!(wide_to_string(&buf), "DELL");
+    }
+
+    #[test]
+    fn wide_to_string_trims_and_tolerates_no_nul() {
+        let buf: [u16; 4] = [b' ' as u16, b'L' as u16, b'G' as u16, b' ' as u16];
+        assert_eq!(wide_to_string(&buf), "LG");
+    }
+
+    #[test]
+    fn wide_to_string_empty_is_empty() {
+        assert_eq!(wide_to_string(&[0u16]), "");
+        assert_eq!(wide_to_string(&[]), "");
+    }
 }
diff --git a/widgetsack/src/event.rs b/widgetsack/src/event.rs
index 27dbfab..dfb1884 100644
--- a/widgetsack/src/event.rs
+++ b/widgetsack/src/event.rs
@@ -1,60 +1,60 @@
-#![allow(clippy::large_enum_variant)]
-
-use serde::Serialize;
-use tauri::Emitter;
-
-use crate::{
-    listener::{ManagerEventWrapper, SessionUpdateEventWrapper},
-    log,
-    state::SessionRecord,
-};
-
-pub fn emit_to_bridge<R: tauri::Runtime>(
-    emitter: &impl Emitter<R>,
-    delta: (&str, Option<SessionRecord>),
-) {
-    match delta {
-        (event_type, Some(record)) => {
-            let _ = emitter.emit(event_type, record);
-        }
-        (event_type, None) => {
-            // FIXME: Might not be true in all cases
-            log::debug("bridge", "skipped emit: no session record")
-                .field("event_type", event_type)
-                .emit();
-        }
-    };
-}
-
-#[derive(Clone, Debug, Serialize)]
-pub enum NpSessionEvent {
-    /// session ID, event
-    /// ManagerEvent actually already contains session_id but we still keep session ID to be consistent
-    Create(usize, ManagerEventWrapper),
-    Update(usize, SessionUpdateEventWrapper),
-    Delete(usize, ManagerEventWrapper),
-    Unsupported(Option<usize>, String),
-}
-
-impl From<ManagerEventWrapper> for NpSessionEvent {
-    fn from(event: ManagerEventWrapper) -> Self {
-        match &event {
-            ManagerEventWrapper::SessionCreated {
-                session_id,
-                source: _,
-            } => NpSessionEvent::Create(*session_id, event),
-            ManagerEventWrapper::SessionRemoved { session_id } => {
-                NpSessionEvent::Delete(*session_id, event)
-            }
-            ManagerEventWrapper::CurrentSessionChanged { session_id } => {
-                NpSessionEvent::Unsupported(*session_id, "CurrentSessionChanged".to_owned())
-            }
-        }
-    }
-}
-
-impl NpSessionEvent {
-    pub fn from_session_update_event(event: SessionUpdateEventWrapper, session_id: usize) -> Self {
-        NpSessionEvent::Update(session_id, event)
-    }
-}
+#![allow(clippy::large_enum_variant)]
+
+use serde::Serialize;
+use tauri::Emitter;
+
+use crate::{
+    listener::{ManagerEventWrapper, SessionUpdateEventWrapper},
+    log,
+    state::SessionRecord,
+};
+
+pub fn emit_to_bridge<R: tauri::Runtime>(
+    emitter: &impl Emitter<R>,
+    delta: (&str, Option<SessionRecord>),
+) {
+    match delta {
+        (event_type, Some(record)) => {
+            let _ = emitter.emit(event_type, record);
+        }
+        (event_type, None) => {
+            // FIXME: Might not be true in all cases
+            log::debug("bridge", "skipped emit: no session record")
+                .field("event_type", event_type)
+                .emit();
+        }
+    };
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub enum NpSessionEvent {
+    /// session ID, event
+    /// ManagerEvent actually already contains session_id but we still keep session ID to be consistent
+    Create(usize, ManagerEventWrapper),
+    Update(usize, SessionUpdateEventWrapper),
+    Delete(usize, ManagerEventWrapper),
+    Unsupported(Option<usize>, String),
+}
+
+impl From<ManagerEventWrapper> for NpSessionEvent {
+    fn from(event: ManagerEventWrapper) -> Self {
+        match &event {
+            ManagerEventWrapper::SessionCreated {
+                session_id,
+                source: _,
+            } => NpSessionEvent::Create(*session_id, event),
+            ManagerEventWrapper::SessionRemoved { session_id } => {
+                NpSessionEvent::Delete(*session_id, event)
+            }
+            ManagerEventWrapper::CurrentSessionChanged { session_id } => {
+                NpSessionEvent::Unsupported(*session_id, "CurrentSessionChanged".to_owned())
+            }
+        }
+    }
+}
+
+impl NpSessionEvent {
+    pub fn from_session_update_event(event: SessionUpdateEventWrapper, session_id: usize) -> Self {
+        NpSessionEvent::Update(session_id, event)
+    }
+}
diff --git a/widgetsack/src/ha.rs b/widgetsack/src/ha.rs
index 62e7491..7826ac5 100644
--- a/widgetsack/src/ha.rs
+++ b/widgetsack/src/ha.rs
@@ -20,11 +20,11 @@ use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use futures_util::{SinkExt, Stream, StreamExt};
 use serde::{Deserialize, Serialize};
-use serde_json::{json, Value};
+use serde_json::{Value, json};
 use tauri::async_runtime::{JoinHandle, Mutex};
 use tauri::{AppHandle, Emitter, Manager, Runtime, State};
 use tokio_tungstenite::tungstenite::{Error as WsError, Message};
-use tokio_tungstenite::{connect_async, connect_async_tls_with_config, Connector};
+use tokio_tungstenite::{Connector, connect_async, connect_async_tls_with_config};
 
 use crate::log;
 use crate::sensors::{SensorSample, SensorValue, TELEMETRY_EVENT};
@@ -142,7 +142,9 @@ fn ha_config_path<R: Runtime>(app: &AppHandle<R>) -> Result<PathBuf, String> {
 pub fn load_ha_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<HaConfig>, String> {
     let path = ha_config_path(app)?;
     match std::fs::read_to_string(&path) {
-        Ok(txt) => serde_json::from_str(&txt).map(Some).map_err(|e| e.to_string()),
+        Ok(txt) => serde_json::from_str(&txt)
+            .map(Some)
+            .map_err(|e| e.to_string()),
         Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
         Err(err) => Err(err.to_string()),
     }
@@ -222,6 +224,97 @@ fn state_to_samples(entity_id: &str, new_state: &Value, ts_ms: u64) -> Option<Ve
     Some(out)
 }
 
+/// A plain `<domain>.<object_id>` HA entity id (lowercase slug). Guards the value before it goes
+/// into a request (no `/`, `..`, spaces, etc. — path/param injection defence).
+fn valid_entity_id(id: &str) -> bool {
+    let mut parts = id.split('.');
+    let (Some(domain), Some(object), None) = (parts.next(), parts.next(), parts.next()) else {
+        return false;
+    };
+    !domain.is_empty()
+        && !object.is_empty()
+        && domain.chars().all(|c| c.is_ascii_lowercase() || c == '_')
+        && object
+            .chars()
+            .all(|c| c.is_ascii_lowercase() || c.is_ascii_digit() || c == '_')
+}
+
+/// A safe HA `entity_picture` path to fetch: host-absolute (`/api/...`), no scheme/host (`//`), no
+/// traversal (`..`) or whitespace. The path is appended raw to the REST base, so this guards it.
+fn valid_art_path(path: &str) -> bool {
+    path.starts_with('/')
+        && !path.starts_with("//")
+        && !path.contains("..")
+        && !path.contains([' ', '\n', '\r', '\t'])
+}
+
+/// Parse an ISO-8601 UTC timestamp (HA's `last_changed`/`last_updated`, e.g.
+/// "2026-06-17T12:34:56.789+00:00") to epoch milliseconds. HA stores these in UTC, so any zone
+/// suffix is ignored (the wall-clock fields are treated as UTC). `None` on a malformed prefix.
+/// Pure — unit-tested without I/O. Uses Howard Hinnant's days-from-civil algorithm (no chrono dep).
+fn iso8601_to_ms(s: &str) -> Option<u64> {
+    let year: i64 = s.get(0..4)?.parse().ok()?;
+    let month: i64 = s.get(5..7)?.parse().ok()?;
+    let day: i64 = s.get(8..10)?.parse().ok()?;
+    let hour: i64 = s.get(11..13)?.parse().ok()?;
+    let min: i64 = s.get(14..16)?.parse().ok()?;
+    let sec: i64 = s.get(17..19)?.parse().ok()?;
+    if !(1..=12).contains(&month) || !(1..=31).contains(&day) || hour > 23 || min > 59 || sec > 60 {
+        return None;
+    }
+    // Fractional seconds → ms: the first up to 3 digits after a '.', right-padded.
+    let frac_ms: i64 = if s.as_bytes().get(19) == Some(&b'.') {
+        let mut d = String::new();
+        for c in s.get(20..).unwrap_or("").chars() {
+            if c.is_ascii_digit() && d.len() < 3 {
+                d.push(c);
+            } else {
+                break;
+            }
+        }
+        while d.len() < 3 {
+            d.push('0');
+        }
+        d.parse().unwrap_or(0)
+    } else {
+        0
+    };
+    // days since 1970-01-01 (civil → days), then to seconds + ms.
+    let y = if month <= 2 { year - 1 } else { year };
+    let era = (if y >= 0 { y } else { y - 399 }) / 400;
+    let yoe = y - era * 400;
+    let mp = if month > 2 { month - 3 } else { month + 9 };
+    let doy = (153 * mp + 2) / 5 + day - 1;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    let days = era * 146097 + doe - 719468;
+    let secs = days * 86400 + hour * 3600 + min * 60 + sec;
+    if secs < 0 {
+        return None;
+    }
+    Some((secs * 1000 + frac_ms) as u64)
+}
+
+/// Map one entity's HA history array (the inner array from `/api/history/period`'s array-of-arrays)
+/// to NUMERIC samples on `ha.<entity_id>.state` — the SAME id the live stream produces, so backfill
+/// merges into one series. Non-numeric states (on/off/strings) and unparseable timestamps are
+/// skipped. No `Json` variant: backfill exists only to feed numeric sparkline history. Pure seam.
+fn history_to_samples(entity_id: &str, history: &Value) -> Vec<SensorSample> {
+    let id = format!("ha.{entity_id}.state");
+    let Some(rows) = history.as_array() else {
+        return Vec::new();
+    };
+    rows.iter()
+        .filter_map(|st| {
+            let n = st["state"].as_str()?.parse::<f64>().ok()?;
+            let ts_str = st["last_changed"]
+                .as_str()
+                .or_else(|| st["last_updated"].as_str())?;
+            let ts = iso8601_to_ms(ts_str)?;
+            Some(SensorSample::scalar(id.clone(), ts, n))
+        })
+        .collect()
+}
+
 /// Classify an auth-phase frame: `Some(Ok)` on `auth_ok` (capturing `ha_version`), `Some(Err)`
 /// on `auth_invalid`, `None` for any other frame (keep reading). Pure — unit-tested without I/O.
 fn auth_outcome(v: &Value) -> Option<Result<HaTestResult, String>> {
@@ -424,7 +517,10 @@ async fn ws_request_many(
             None => return Err("stream ended during registry fetch".into()),
         }
     }
-    Ok(results.into_iter().map(|r| r.unwrap_or(Value::Null)).collect())
+    Ok(results
+        .into_iter()
+        .map(|r| r.unwrap_or(Value::Null))
+        .collect())
 }
 
 /// One connection lifecycle: connect → auth → seed snapshot → subscribe → stream events.
@@ -598,7 +694,9 @@ pub async fn ha_test_connection(
         .await
         .map_err(|e| e.to_string())?;
     let auth = json!({ "type": "auth", "access_token": token }).to_string();
-    ws.send(Message::Text(auth)).await.map_err(|e| e.to_string())?;
+    ws.send(Message::Text(auth))
+        .await
+        .map_err(|e| e.to_string())?;
     while let Some(msg) = ws.next().await {
         if let Message::Text(txt) = msg.map_err(|e| e.to_string())? {
             let v: Value = serde_json::from_str(&txt).map_err(|e| e.to_string())?;
@@ -667,7 +765,10 @@ pub async fn list_ha_entities<R: Runtime>(app: AppHandle<R>) -> Result<Vec<HaEnt
     let cfg = load_ha_config(&app)?.ok_or("HA not configured")?;
     let client = ha_http_client(cfg.insecure)?;
     let resp = client
-        .get(format!("{}/api/states", rest_base(&cfg.url, &cfg.base_path)))
+        .get(format!(
+            "{}/api/states",
+            rest_base(&cfg.url, &cfg.base_path)
+        ))
         .bearer_auth(&cfg.token)
         .send()
         .await
@@ -701,8 +802,14 @@ pub async fn ha_registry_snapshot<R: Runtime>(app: AppHandle<R>) -> Result<HaReg
     let as_rows = |v: &Value| v.as_array().cloned().unwrap_or_default();
     Ok(HaRegistry {
         areas: as_rows(&results[0]).iter().filter_map(area_from).collect(),
-        devices: as_rows(&results[1]).iter().filter_map(device_from).collect(),
-        entities: as_rows(&results[2]).iter().filter_map(entity_reg_from).collect(),
+        devices: as_rows(&results[1])
+            .iter()
+            .filter_map(device_from)
+            .collect(),
+        entities: as_rows(&results[2])
+            .iter()
+            .filter_map(entity_reg_from)
+            .collect(),
     })
 }
 
@@ -740,10 +847,171 @@ pub async fn ha_call_service<R: Runtime>(
     resp.json().await.map_err(|e| e.to_string())
 }
 
+/// Fetch historical state for ONE entity over [start, end] (ISO-8601 UTC) via REST
+/// `/api/history/period`, returning NUMERIC samples on `ha.<entity_id>.state` for sparkline
+/// backfill. `minimal_response` + `significant_changes_only` + numeric-only keep the payload small;
+/// the caller ingests the result into its OWN hub (no telemetry emit), so each window backfills once
+/// without double-counting. Errors never include the token.
+#[tauri::command]
+pub async fn ha_history<R: Runtime>(
+    app: AppHandle<R>,
+    entity_id: String,
+    start: String,
+    end: String,
+) -> Result<Vec<SensorSample>, String> {
+    if !valid_entity_id(&entity_id) {
+        return Err("invalid entity_id".to_string());
+    }
+    // `start` is interpolated into the URL PATH (`end` into a query) — require a real ISO-8601
+    // timestamp so neither can carry path/query separators (`/`, `?`, `#`) or other junk.
+    if iso8601_to_ms(&start).is_none() || iso8601_to_ms(&end).is_none() {
+        return Err("invalid time range".to_string());
+    }
+    let cfg = load_ha_config(&app)?.ok_or("HA not configured")?;
+    let client = ha_http_client(cfg.insecure)?;
+    // parse_with_params percent-encodes the query (the ISO `end_time` carries ':' and '+').
+    let url = reqwest::Url::parse_with_params(
+        &format!(
+            "{}/api/history/period/{}",
+            rest_base(&cfg.url, &cfg.base_path),
+            start
+        ),
+        &[
+            ("filter_entity_id", entity_id.as_str()),
+            ("end_time", end.as_str()),
+            ("minimal_response", ""),
+            ("significant_changes_only", ""),
+        ],
+    )
+    .map_err(|e| e.to_string())?;
+    let resp = client
+        .get(url)
+        .bearer_auth(&cfg.token)
+        .timeout(std::time::Duration::from_secs(120))
+        .send()
+        .await
+        .map_err(|e| e.to_string())?;
+    if !resp.status().is_success() {
+        return Err(format!("GET /api/history failed: {}", resp.status()));
+    }
+    // HA returns an array-of-arrays (one inner array per filtered entity); we filtered to one.
+    let data: Vec<Value> = resp.json().await.map_err(|e| e.to_string())?;
+    Ok(data
+        .first()
+        .map(|h| history_to_samples(&entity_id, h))
+        .unwrap_or_default())
+}
+
+/// Fetch an HA `entity_picture` (e.g. a media_player cover) over REST using the server-side token +
+/// insecure opt-in, store the bytes in the shared album-art registry, and return the
+/// `http://art.localhost/<hash>` URL the webview can `<img>`-load. Reuses the now-playing art scheme
+/// (already allowed by the CSP), so no bytes cross the JSON bridge and no CSP change is needed. The
+/// token never crosses the bridge; errors never include it.
+#[tauri::command]
+pub async fn ha_media_art<R: Runtime>(app: AppHandle<R>, path: String) -> Result<String, String> {
+    if !valid_art_path(&path) {
+        return Err("invalid art path".to_string());
+    }
+    let cfg = load_ha_config(&app)?.ok_or("HA not configured")?;
+    let client = ha_http_client(cfg.insecure)?;
+    let resp = client
+        .get(format!("{}{}", rest_base(&cfg.url, &cfg.base_path), path))
+        .bearer_auth(&cfg.token)
+        .timeout(std::time::Duration::from_secs(20))
+        .send()
+        .await
+        .map_err(|e| e.to_string())?;
+    if !resp.status().is_success() {
+        return Err(format!("GET art failed: {}", resp.status()));
+    }
+    let content_type = resp
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("image/jpeg")
+        .to_string();
+    let bytes = resp.bytes().await.map_err(|e| e.to_string())?.to_vec();
+    let img = std::sync::Arc::new(crate::listener::ImageWrapper::new(content_type, bytes));
+    let hash = img.hash;
+    app.state::<crate::art::ArtState>()
+        .0
+        .lock()
+        .unwrap()
+        .insert(hash, img);
+    Ok(crate::art::art_url(hash))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
+    #[test]
+    fn valid_entity_id_accepts_slugs_rejects_injection() {
+        assert!(valid_entity_id("sensor.cpu_temp"));
+        assert!(valid_entity_id("binary_sensor.front_door"));
+        assert!(valid_entity_id("input_number.x1"));
+        assert!(!valid_entity_id("x/api/admin"));
+        assert!(!valid_entity_id("../etc"));
+        assert!(!valid_entity_id("a.b.c"));
+        assert!(!valid_entity_id(""));
+        assert!(!valid_entity_id("sensor."));
+        assert!(!valid_entity_id("Sensor.X")); // uppercase is not a slug
+    }
+
+    #[test]
+    fn valid_art_path_requires_host_absolute_no_traversal() {
+        assert!(valid_art_path(
+            "/api/media_player_proxy/media_player.x?token=abc&cache=1"
+        ));
+        assert!(!valid_art_path("http://evil/x")); // not host-absolute
+        assert!(!valid_art_path("//evil/x")); // protocol-relative
+        assert!(!valid_art_path("/a/../../etc")); // traversal
+        assert!(!valid_art_path("/a b")); // whitespace
+        assert!(!valid_art_path(""));
+    }
+
+    #[test]
+    fn iso8601_parses_to_ms_as_utc() {
+        assert_eq!(iso8601_to_ms("1970-01-01T00:00:00+00:00"), Some(0));
+        assert_eq!(
+            iso8601_to_ms("2021-01-01T00:00:00.000+00:00"),
+            Some(1_609_459_200_000)
+        );
+        // fractional seconds → ms (first 3 digits)
+        assert_eq!(
+            iso8601_to_ms("2021-01-01T00:00:00.789012+00:00"),
+            Some(1_609_459_200_789)
+        );
+        assert_eq!(
+            iso8601_to_ms("2021-01-01T00:00:00.5Z"),
+            Some(1_609_459_200_500)
+        );
+        assert_eq!(iso8601_to_ms("not-a-date"), None);
+        assert_eq!(iso8601_to_ms("2021-13-01T00:00:00Z"), None);
+    }
+
+    #[test]
+    fn history_to_samples_keeps_numeric_only_with_ts() {
+        let hist = json!([
+            { "state": "21.6", "last_changed": "2021-01-01T00:00:00+00:00" },
+            { "state": "unavailable", "last_changed": "2021-01-01T00:01:00+00:00" },
+            { "state": "22.0", "last_updated": "2021-01-01T00:02:00+00:00" }
+        ]);
+        let samples = history_to_samples("sensor.temp", &hist);
+        assert_eq!(samples.len(), 2);
+        assert_eq!(samples[0].sensor, "ha.sensor.temp.state");
+        assert_eq!(samples[0].ts_ms, 1_609_459_200_000);
+        assert!(matches!(samples[0].value, SensorValue::Scalar(v) if (v - 21.6).abs() < 1e-9));
+        // the second numeric row falls back to last_updated for its ts
+        assert_eq!(samples[1].ts_ms, 1_609_459_320_000);
+    }
+
+    #[test]
+    fn history_to_samples_empty_on_non_array() {
+        assert!(history_to_samples("sensor.x", &Value::Null).is_empty());
+        assert!(history_to_samples("sensor.x", &json!([])).is_empty());
+    }
+
     #[test]
     fn ws_url_maps_scheme_and_appends_path() {
         assert_eq!(
@@ -758,9 +1026,18 @@ mod tests {
 
     #[test]
     fn ws_url_strips_trailing_slash_and_passes_ws_schemes() {
-        assert_eq!(ws_url_from("http://ha:8123/", ""), "ws://ha:8123/api/websocket");
-        assert_eq!(ws_url_from("ws://ha:8123", ""), "ws://ha:8123/api/websocket");
-        assert_eq!(ws_url_from("wss://ha:8123/", ""), "wss://ha:8123/api/websocket");
+        assert_eq!(
+            ws_url_from("http://ha:8123/", ""),
+            "ws://ha:8123/api/websocket"
+        );
+        assert_eq!(
+            ws_url_from("ws://ha:8123", ""),
+            "ws://ha:8123/api/websocket"
+        );
+        assert_eq!(
+            ws_url_from("wss://ha:8123/", ""),
+            "wss://ha:8123/api/websocket"
+        );
         // No scheme defaults to ws://.
         assert_eq!(ws_url_from("ha:8123", ""), "ws://ha:8123/api/websocket");
     }
@@ -873,13 +1150,16 @@ mod tests {
         assert_eq!(ok.ha_version.as_deref(), Some("2026.6.0"));
 
         // auth_ok without a version is still a success.
-        let ok2 = auth_outcome(&json!({ "type": "auth_ok" })).unwrap().unwrap();
+        let ok2 = auth_outcome(&json!({ "type": "auth_ok" }))
+            .unwrap()
+            .unwrap();
         assert!(ok2.ha_version.is_none());
 
         // auth_invalid maps to a descriptive error (so the UI can say "bad token").
-        let err = auth_outcome(&json!({ "type": "auth_invalid", "message": "Invalid access token" }))
-            .unwrap()
-            .unwrap_err();
+        let err =
+            auth_outcome(&json!({ "type": "auth_invalid", "message": "Invalid access token" }))
+                .unwrap()
+                .unwrap_err();
         assert!(err.contains("auth_invalid"));
         assert!(err.contains("Invalid access token"));
 
diff --git a/widgetsack/src/listener.rs b/widgetsack/src/listener.rs
index a2f8527..9dfc883 100644
--- a/widgetsack/src/listener.rs
+++ b/widgetsack/src/listener.rs
@@ -1,196 +1,199 @@
-use std::fmt;
-use std::sync::Arc;
-
-use gsmtc::{Image, ManagerEvent, SessionModel, SessionUpdateEvent};
-use serde::ser::SerializeStruct;
-use serde::{Serialize, Serializer};
-use tokio::sync::mpsc;
-
-use crate::event::NpSessionEvent;
-use crate::log;
-
-pub async fn session_listener_windows_gsmtc(
-    mut manager_rx: mpsc::UnboundedReceiver<ManagerEvent>,
-    tx: mpsc::Sender<NpSessionEvent>,
-) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
-    while let Some(evt) = manager_rx.recv().await {
-        match evt {
-            ManagerEvent::SessionCreated {
-                session_id,
-                mut rx,
-                source,
-            } => {
-                // `rx` is killing our .into() when destructured so manually create the struct here
-                let evt_wrapper: ManagerEventWrapper = ManagerEventWrapper::SessionCreated {
-                    session_id,
-                    source: source.clone(),
-                };
-
-                log::info("gsmtc", "session created")
-                    .field("session_id", session_id)
-                    .field("source", &source)
-                    .emit();
-
-                let _ = tx.send(evt_wrapper.into()).await;
-
-                let tx_child = tx.clone();
-                tokio::spawn(async move {
-                    while let Some(evt_update) = rx.recv().await {
-                        let evt_update_wrapper: SessionUpdateEventWrapper = evt_update.into();
-                        let _ = tx_child
-                            .send(NpSessionEvent::from_session_update_event(
-                                evt_update_wrapper,
-                                session_id,
-                            ))
-                            .await;
-                    }
-                });
-            }
-            ManagerEvent::SessionRemoved { session_id } => {
-                let evt_wrapper: ManagerEventWrapper =
-                    ManagerEventWrapper::SessionRemoved { session_id };
-
-                let _ = tx.send(evt_wrapper.into()).await;
-                log::info("gsmtc", "session removed")
-                    .field("session_id", session_id)
-                    .emit();
-            }
-            ManagerEvent::CurrentSessionChanged {
-                session_id: Some(id),
-            } => {
-                // TODO: reset frontend
-                log::debug("gsmtc", "current session changed")
-                    .field("session_id", id)
-                    .emit();
-            }
-            ManagerEvent::CurrentSessionChanged { session_id: None } => {
-                // TODO: clear frontend
-                log::debug("gsmtc", "no current session").emit();
-            }
-        }
-    }
-
-    Ok(())
-}
-
-#[derive(Clone)]
-pub struct ImageWrapper {
-    pub content_type: String,
-    pub data: Vec<u8>,
-    /// Content hash of `data`, computed once at construction (`art::art_hash`). Drives the cover's
-    /// bridge URL (`art::art_url`) and its registry key, so identical covers (same album across
-    /// tracks) map to the same URL — a browser cache hit and a stable crossfade `artKey`.
-    pub hash: u64,
-}
-
-impl ImageWrapper {
-    pub fn new(content_type: String, data: Vec<u8>) -> Self {
-        let hash = crate::art::art_hash(&data);
-        ImageWrapper {
-            content_type,
-            data,
-            hash,
-        }
-    }
-}
-
-impl From<Image> for ImageWrapper {
-    fn from(value: Image) -> Self {
-        ImageWrapper::new(value.content_type, value.data)
-    }
-}
-
-// The cover bytes DO NOT cross the JSON bridge — that's the whole point of `art.rs`. Instead of
-// serde_json rendering `data: Vec<u8>` as a multi-MB array of decimal numbers, an `ImageWrapper`
-// serializes to a compact descriptor the frontend (`stores.ts` `ThumbnailInfo`) reads: `url` points
-// the `<img>` at the custom `art` scheme handler, `bytes` is the retained byte count surfaced in the
-// studio Diagnostics panel. Keep this in lockstep with `ThumbnailInfo` (AGENTS.md §5).
-impl Serialize for ImageWrapper {
-    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
-        let mut state = serializer.serialize_struct("ImageWrapper", 3)?;
-        state.serialize_field("content_type", &self.content_type)?;
-        state.serialize_field("url", &crate::art::art_url(self.hash))?;
-        state.serialize_field("bytes", &self.data.len())?;
-        state.end()
-    }
-}
-
-impl fmt::Debug for ImageWrapper {
-    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        write!(
-            f,
-            "ImageWrapper {{ content_type: {}, data: u8[{}] }}",
-            self.content_type,
-            self.data.len()
-        )
-    }
-}
-
-// Serde's remote doesn't seem to work on enum fields? Image in Media wants to be Serialize, but that won't work.
-// The cover art is held behind an `Arc` so carrying it forward across model/timeline updates
-// (state.rs `updater`) and emitting it are pointer copies, not memcpy of the (hundreds-of-KB) bytes.
-// `Arc<ImageWrapper>` serializes identically to `ImageWrapper` (serde `rc` feature) — the bridge JSON
-// is unchanged, so the TS mirror in stores.ts needs no change.
-#[derive(Clone, Debug, Serialize)]
-pub enum SessionUpdateEventWrapper {
-    Model(SessionModel),
-    Media(SessionModel, Option<Arc<ImageWrapper>>),
-}
-
-impl From<gsmtc::SessionUpdateEvent> for SessionUpdateEventWrapper {
-    fn from(value: gsmtc::SessionUpdateEvent) -> Self {
-        match value {
-            SessionUpdateEvent::Model(model) => SessionUpdateEventWrapper::Model(model),
-            SessionUpdateEvent::Media(model, image) => {
-                SessionUpdateEventWrapper::Media(model, image.map(|i| Arc::new(i.into())))
-            }
-        }
-    }
-}
-
-#[derive(Clone, Debug, Serialize)]
-pub enum ManagerEventWrapper {
-    SessionCreated { session_id: usize, source: String },
-    SessionRemoved { session_id: usize },
-    CurrentSessionChanged { session_id: Option<usize> },
-}
-
-impl From<ManagerEvent> for ManagerEventWrapper {
-    fn from(value: ManagerEvent) -> Self {
-        match value {
-            gsmtc::ManagerEvent::SessionCreated {
-                session_id,
-                rx: _,
-                source,
-            } => Self::SessionCreated { session_id, source },
-            gsmtc::ManagerEvent::SessionRemoved { session_id } => {
-                Self::SessionRemoved { session_id }
-            }
-            gsmtc::ManagerEvent::CurrentSessionChanged { session_id } => {
-                Self::CurrentSessionChanged { session_id }
-            }
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn image_wrapper_serializes_as_url_and_bytes_not_raw_data() {
-        let data = vec![0x89u8, 0x50, 0x4E, 0x47, 1, 2, 3];
-        let wrapper = ImageWrapper::new("image/png".to_string(), data.clone());
-        let value = serde_json::to_value(&wrapper).expect("serialize");
-
-        assert_eq!(value["content_type"], "image/png");
-        assert_eq!(value["bytes"], data.len() as u64);
-        // The whole point: the encoded bytes must NOT cross the JSON bridge.
-        assert!(value.get("data").is_none(), "raw cover bytes must not be serialized");
-        // The url is the content-hash scheme URL the webview's <img> fetches.
-        assert_eq!(
-            value["url"],
-            crate::art::art_url(crate::art::art_hash(&data))
-        );
-    }
-}
+use std::fmt;
+use std::sync::Arc;
+
+use gsmtc::{Image, ManagerEvent, SessionModel, SessionUpdateEvent};
+use serde::ser::SerializeStruct;
+use serde::{Serialize, Serializer};
+use tokio::sync::mpsc;
+
+use crate::event::NpSessionEvent;
+use crate::log;
+
+pub async fn session_listener_windows_gsmtc(
+    mut manager_rx: mpsc::UnboundedReceiver<ManagerEvent>,
+    tx: mpsc::Sender<NpSessionEvent>,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    while let Some(evt) = manager_rx.recv().await {
+        match evt {
+            ManagerEvent::SessionCreated {
+                session_id,
+                mut rx,
+                source,
+            } => {
+                // `rx` is killing our .into() when destructured so manually create the struct here
+                let evt_wrapper: ManagerEventWrapper = ManagerEventWrapper::SessionCreated {
+                    session_id,
+                    source: source.clone(),
+                };
+
+                log::info("gsmtc", "session created")
+                    .field("session_id", session_id)
+                    .field("source", &source)
+                    .emit();
+
+                let _ = tx.send(evt_wrapper.into()).await;
+
+                let tx_child = tx.clone();
+                tokio::spawn(async move {
+                    while let Some(evt_update) = rx.recv().await {
+                        let evt_update_wrapper: SessionUpdateEventWrapper = evt_update.into();
+                        let _ = tx_child
+                            .send(NpSessionEvent::from_session_update_event(
+                                evt_update_wrapper,
+                                session_id,
+                            ))
+                            .await;
+                    }
+                });
+            }
+            ManagerEvent::SessionRemoved { session_id } => {
+                let evt_wrapper: ManagerEventWrapper =
+                    ManagerEventWrapper::SessionRemoved { session_id };
+
+                let _ = tx.send(evt_wrapper.into()).await;
+                log::info("gsmtc", "session removed")
+                    .field("session_id", session_id)
+                    .emit();
+            }
+            ManagerEvent::CurrentSessionChanged {
+                session_id: Some(id),
+            } => {
+                // TODO: reset frontend
+                log::debug("gsmtc", "current session changed")
+                    .field("session_id", id)
+                    .emit();
+            }
+            ManagerEvent::CurrentSessionChanged { session_id: None } => {
+                // TODO: clear frontend
+                log::debug("gsmtc", "no current session").emit();
+            }
+        }
+    }
+
+    Ok(())
+}
+
+#[derive(Clone)]
+pub struct ImageWrapper {
+    pub content_type: String,
+    pub data: Vec<u8>,
+    /// Content hash of `data`, computed once at construction (`art::art_hash`). Drives the cover's
+    /// bridge URL (`art::art_url`) and its registry key, so identical covers (same album across
+    /// tracks) map to the same URL — a browser cache hit and a stable crossfade `artKey`.
+    pub hash: u64,
+}
+
+impl ImageWrapper {
+    pub fn new(content_type: String, data: Vec<u8>) -> Self {
+        let hash = crate::art::art_hash(&data);
+        ImageWrapper {
+            content_type,
+            data,
+            hash,
+        }
+    }
+}
+
+impl From<Image> for ImageWrapper {
+    fn from(value: Image) -> Self {
+        ImageWrapper::new(value.content_type, value.data)
+    }
+}
+
+// The cover bytes DO NOT cross the JSON bridge — that's the whole point of `art.rs`. Instead of
+// serde_json rendering `data: Vec<u8>` as a multi-MB array of decimal numbers, an `ImageWrapper`
+// serializes to a compact descriptor the frontend (`stores.ts` `ThumbnailInfo`) reads: `url` points
+// the `<img>` at the custom `art` scheme handler, `bytes` is the retained byte count surfaced in the
+// studio Diagnostics panel. Keep this in lockstep with `ThumbnailInfo` (AGENTS.md §5).
+impl Serialize for ImageWrapper {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        let mut state = serializer.serialize_struct("ImageWrapper", 3)?;
+        state.serialize_field("content_type", &self.content_type)?;
+        state.serialize_field("url", &crate::art::art_url(self.hash))?;
+        state.serialize_field("bytes", &self.data.len())?;
+        state.end()
+    }
+}
+
+impl fmt::Debug for ImageWrapper {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        write!(
+            f,
+            "ImageWrapper {{ content_type: {}, data: u8[{}] }}",
+            self.content_type,
+            self.data.len()
+        )
+    }
+}
+
+// Serde's remote doesn't seem to work on enum fields? Image in Media wants to be Serialize, but that won't work.
+// The cover art is held behind an `Arc` so carrying it forward across model/timeline updates
+// (state.rs `updater`) and emitting it are pointer copies, not memcpy of the (hundreds-of-KB) bytes.
+// `Arc<ImageWrapper>` serializes identically to `ImageWrapper` (serde `rc` feature) — the bridge JSON
+// is unchanged, so the TS mirror in stores.ts needs no change.
+#[derive(Clone, Debug, Serialize)]
+pub enum SessionUpdateEventWrapper {
+    Model(SessionModel),
+    Media(SessionModel, Option<Arc<ImageWrapper>>),
+}
+
+impl From<gsmtc::SessionUpdateEvent> for SessionUpdateEventWrapper {
+    fn from(value: gsmtc::SessionUpdateEvent) -> Self {
+        match value {
+            SessionUpdateEvent::Model(model) => SessionUpdateEventWrapper::Model(model),
+            SessionUpdateEvent::Media(model, image) => {
+                SessionUpdateEventWrapper::Media(model, image.map(|i| Arc::new(i.into())))
+            }
+        }
+    }
+}
+
+#[derive(Clone, Debug, Serialize)]
+pub enum ManagerEventWrapper {
+    SessionCreated { session_id: usize, source: String },
+    SessionRemoved { session_id: usize },
+    CurrentSessionChanged { session_id: Option<usize> },
+}
+
+impl From<ManagerEvent> for ManagerEventWrapper {
+    fn from(value: ManagerEvent) -> Self {
+        match value {
+            gsmtc::ManagerEvent::SessionCreated {
+                session_id,
+                rx: _,
+                source,
+            } => Self::SessionCreated { session_id, source },
+            gsmtc::ManagerEvent::SessionRemoved { session_id } => {
+                Self::SessionRemoved { session_id }
+            }
+            gsmtc::ManagerEvent::CurrentSessionChanged { session_id } => {
+                Self::CurrentSessionChanged { session_id }
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn image_wrapper_serializes_as_url_and_bytes_not_raw_data() {
+        let data = vec![0x89u8, 0x50, 0x4E, 0x47, 1, 2, 3];
+        let wrapper = ImageWrapper::new("image/png".to_string(), data.clone());
+        let value = serde_json::to_value(&wrapper).expect("serialize");
+
+        assert_eq!(value["content_type"], "image/png");
+        assert_eq!(value["bytes"], data.len() as u64);
+        // The whole point: the encoded bytes must NOT cross the JSON bridge.
+        assert!(
+            value.get("data").is_none(),
+            "raw cover bytes must not be serialized"
+        );
+        // The url is the content-hash scheme URL the webview's <img> fetches.
+        assert_eq!(
+            value["url"],
+            crate::art::art_url(crate::art::art_hash(&data))
+        );
+    }
+}
diff --git a/widgetsack/src/llm.rs b/widgetsack/src/llm.rs
index c4151fe..5504112 100644
--- a/widgetsack/src/llm.rs
+++ b/widgetsack/src/llm.rs
@@ -24,7 +24,7 @@ use std::time::Duration;
 
 use futures_util::StreamExt;
 use serde::{Deserialize, Serialize};
-use serde_json::{json, Value};
+use serde_json::{Value, json};
 use tauri::async_runtime::{JoinHandle, Mutex};
 use tauri::{AppHandle, Emitter, Manager, Runtime, State};
 
@@ -374,7 +374,10 @@ fn mime_ext(mime: &str) -> &'static str {
 
 /// Pull the transcript text out of a transcription response (`{ "text": "..." }`).
 fn parse_transcription(v: &Value) -> Option<String> {
-    v["text"].as_str().map(str::to_string).filter(|s| !s.is_empty())
+    v["text"]
+        .as_str()
+        .map(str::to_string)
+        .filter(|s| !s.is_empty())
 }
 
 /// The OpenAI-style text-to-speech endpoint. Shares `supports_transcription`'s provider gate (the same
@@ -536,11 +539,7 @@ fn parse_chat_text(provider: &str, v: &Value) -> Option<String> {
             .unwrap_or("")
             .to_string(),
     };
-    if text.is_empty() {
-        None
-    } else {
-        Some(text)
-    }
+    if text.is_empty() { None } else { Some(text) }
 }
 
 /// Pull a human-readable error message out of an error response body (best-effort).
@@ -651,7 +650,11 @@ fn llm_http_client(insecure: bool) -> Result<reqwest::Client, String> {
 }
 
 /// Attach the provider's auth headers to a request. The key never leaves this process.
-fn apply_auth(rb: reqwest::RequestBuilder, provider: &str, api_key: &str) -> reqwest::RequestBuilder {
+fn apply_auth(
+    rb: reqwest::RequestBuilder,
+    provider: &str,
+    api_key: &str,
+) -> reqwest::RequestBuilder {
     match provider {
         "anthropic" => rb
             .header("x-api-key", api_key)
@@ -911,7 +914,12 @@ pub async fn llm_list_models<R: Runtime>(
         }
         None => {
             let cfg = load_llm_config(&app)?.ok_or("AI provider not configured")?;
-            (cfg.provider.clone(), effective_base(&cfg), cfg.api_key, cfg.insecure)
+            (
+                cfg.provider.clone(),
+                effective_base(&cfg),
+                cfg.api_key,
+                cfg.insecure,
+            )
         }
     };
     let url = models_endpoint(&provider, &base);
@@ -1003,7 +1011,10 @@ pub async fn llm_transcribe<R: Runtime>(
 /// expose this — anthropic + ollama do not (the frontend falls back to the browser's Web Speech voice).
 /// NOT studio-guarded: the overlay's widgets read it aloud too; the key never crosses the bridge.
 #[tauri::command]
-pub async fn llm_synthesize<R: Runtime>(app: AppHandle<R>, text: String) -> Result<LlmAudio, String> {
+pub async fn llm_synthesize<R: Runtime>(
+    app: AppHandle<R>,
+    text: String,
+) -> Result<LlmAudio, String> {
     let cfg = load_llm_config(&app)?.ok_or("AI provider not configured")?;
     if !supports_tts(&cfg.provider) {
         return Err(format!(
@@ -1059,7 +1070,13 @@ pub async fn llm_synthesize<R: Runtime>(app: AppHandle<R>, text: String) -> Resu
     Ok(LlmAudio { audio, mime })
 }
 
-fn emit_delta<R: Runtime>(app: &AppHandle<R>, request_id: &str, token: &str, done: bool, error: Option<String>) {
+fn emit_delta<R: Runtime>(
+    app: &AppHandle<R>,
+    request_id: &str,
+    token: &str,
+    done: bool,
+    error: Option<String>,
+) {
     let _ = app.emit(
         LLM_DELTA_EVENT,
         &LlmDelta {
@@ -1073,9 +1090,20 @@ fn emit_delta<R: Runtime>(app: &AppHandle<R>, request_id: &str, token: &str, don
 
 /// The streaming worker: open the streamed response and emit `llm_delta` frames token-by-token, then a
 /// final `{ done: true }`. Errors emit a `{ done: true, error }` frame so the UI always terminates.
-async fn run_stream<R: Runtime>(app: AppHandle<R>, request_id: String, cfg: LlmConfig, messages: Vec<ChatMessage>) {
+async fn run_stream<R: Runtime>(
+    app: AppHandle<R>,
+    request_id: String,
+    cfg: LlmConfig,
+    messages: Vec<ChatMessage>,
+) {
     if needs_key(&cfg.provider) && cfg.api_key.trim().is_empty() {
-        emit_delta(&app, &request_id, "", true, Some("no API key configured".into()));
+        emit_delta(
+            &app,
+            &request_id,
+            "",
+            true,
+            Some("no API key configured".into()),
+        );
         return;
     }
     let base = effective_base(&cfg);
@@ -1182,7 +1210,9 @@ pub async fn llm_cancel<R: Runtime>(
 ) -> Result<(), String> {
     if let Some((_, handle)) = state.streams.lock().await.remove(&request_id) {
         handle.abort();
-        log::info("llm", "stream cancelled").field("id", &request_id).emit();
+        log::info("llm", "stream cancelled")
+            .field("id", &request_id)
+            .emit();
         emit_delta(&app, &request_id, "", true, None);
     }
     Ok(())
@@ -1286,7 +1316,10 @@ mod tests {
     #[test]
     fn parse_text_per_provider() {
         let anth = serde_json::json!({ "content": [ { "type": "text", "text": "he" }, { "type": "text", "text": "llo" } ] });
-        assert_eq!(parse_chat_text("anthropic", &anth).as_deref(), Some("hello"));
+        assert_eq!(
+            parse_chat_text("anthropic", &anth).as_deref(),
+            Some("hello")
+        );
         let oai = serde_json::json!({ "choices": [ { "message": { "content": "hi there" } } ] });
         assert_eq!(parse_chat_text("openai", &oai).as_deref(), Some("hi there"));
         let oll = serde_json::json!({ "message": { "content": "yo" } });
@@ -1307,8 +1340,19 @@ mod tests {
 
     #[test]
     fn uses_completion_tokens_matches_next_gen_families() {
-        for m in ["gpt-5", "gpt-5-nano", "gpt-5.1", "o1", "o1-mini", "o3-mini", "o4-mini"] {
-            assert!(uses_completion_tokens(m), "{m} should use max_completion_tokens");
+        for m in [
+            "gpt-5",
+            "gpt-5-nano",
+            "gpt-5.1",
+            "o1",
+            "o1-mini",
+            "o3-mini",
+            "o4-mini",
+        ] {
+            assert!(
+                uses_completion_tokens(m),
+                "{m} should use max_completion_tokens"
+            );
         }
         for m in ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo", "llama3.2", ""] {
             assert!(!uses_completion_tokens(m), "{m} should keep max_tokens");
@@ -1344,13 +1388,22 @@ mod tests {
     #[test]
     fn openai_sse_lines() {
         assert_eq!(
-            stream_event_from_line("openai", "data: {\"choices\":[{\"delta\":{\"content\":\"Hi\"}}]}"),
+            stream_event_from_line(
+                "openai",
+                "data: {\"choices\":[{\"delta\":{\"content\":\"Hi\"}}]}"
+            ),
             StreamEvent::Token("Hi".into())
         );
-        assert_eq!(stream_event_from_line("openai", "data: [DONE]"), StreamEvent::Done);
+        assert_eq!(
+            stream_event_from_line("openai", "data: [DONE]"),
+            StreamEvent::Done
+        );
         // a role-only opening delta carries no content -> Ignore
         assert_eq!(
-            stream_event_from_line("openai", "data: {\"choices\":[{\"delta\":{\"role\":\"assistant\"}}]}"),
+            stream_event_from_line(
+                "openai",
+                "data: {\"choices\":[{\"delta\":{\"role\":\"assistant\"}}]}"
+            ),
             StreamEvent::Ignore
         );
         assert_eq!(stream_event_from_line("openai", ""), StreamEvent::Ignore);
@@ -1379,7 +1432,10 @@ mod tests {
     #[test]
     fn ollama_stream_lines() {
         assert_eq!(
-            stream_event_from_line("ollama", "{\"message\":{\"content\":\"yo\"},\"done\":false}"),
+            stream_event_from_line(
+                "ollama",
+                "{\"message\":{\"content\":\"yo\"},\"done\":false}"
+            ),
             StreamEvent::Token("yo".into())
         );
         assert_eq!(
@@ -1405,7 +1461,10 @@ mod tests {
             parse_transcription(&serde_json::json!({ "text": "hello world" })).as_deref(),
             Some("hello world")
         );
-        assert_eq!(parse_transcription(&serde_json::json!({ "text": "" })), None);
+        assert_eq!(
+            parse_transcription(&serde_json::json!({ "text": "" })),
+            None
+        );
     }
 
     #[test]
@@ -1449,7 +1508,10 @@ mod tests {
         .unwrap();
         assert!(v.get("api_key").is_none() && v.get("apiKey").is_none());
         assert_eq!(v["providers"]["openai"]["hasKey"], true);
-        assert_eq!(v["providers"]["openai"]["baseUrl"], "https://api.openai.com/v1");
+        assert_eq!(
+            v["providers"]["openai"]["baseUrl"],
+            "https://api.openai.com/v1"
+        );
         assert_eq!(v["maxTokens"], 1024);
     }
 
@@ -1457,9 +1519,9 @@ mod tests {
     fn migrates_legacy_flat_config_into_providers_map() {
         // A pre-multi-provider file (no `providers` key) → one entry, active = its provider, globals kept.
         let file = parse_config_json(
-            r#"{ "provider": "anthropic", "api_key": "sk-x", "model": "claude-x", "max_tokens": 2048 }"#,
-        )
-        .unwrap();
+			r#"{ "provider": "anthropic", "api_key": "sk-x", "model": "claude-x", "max_tokens": 2048 }"#,
+		)
+		.unwrap();
         assert_eq!(file.active, "anthropic");
         assert_eq!(file.max_tokens, 2048);
         let entry = file.providers.get("anthropic").unwrap();
diff --git a/widgetsack/src/log.rs b/widgetsack/src/log.rs
index 3771dde..68f0bd1 100644
--- a/widgetsack/src/log.rs
+++ b/widgetsack/src/log.rs
@@ -221,7 +221,12 @@ pub fn error(target: &'static str, message: impl Into<String>) -> LogBuilder {
 
 /// A compact one-liner for the console / panic hook: `LEVEL target: message k=v …`.
 fn console_line(record: &LogRecord) -> String {
-    let mut line = format!("{} {}: {}", record.level.label(), record.target, record.message);
+    let mut line = format!(
+        "{} {}: {}",
+        record.level.label(),
+        record.target,
+        record.message
+    );
     for (k, v) in &record.fields {
         line.push_str(&format!(" {k}={v}"));
     }
diff --git a/widgetsack/src/main.rs b/widgetsack/src/main.rs
index 14e7e00..bf9348a 100644
--- a/widgetsack/src/main.rs
+++ b/widgetsack/src/main.rs
@@ -3,11 +3,11 @@
     windows_subsystem = "windows"
 )]
 
-use listener::{session_listener_windows_gsmtc, ManagerEventWrapper, SessionUpdateEventWrapper};
+use listener::{ManagerEventWrapper, SessionUpdateEventWrapper, session_listener_windows_gsmtc};
 use state::SessionRecord;
 use std::collections::HashMap;
 use tauri::async_runtime::Mutex;
-use tauri::menu::{MenuBuilder, MenuItemBuilder};
+use tauri::menu::{CheckMenuItemBuilder, MenuBuilder, MenuItemBuilder};
 use tauri::tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent};
 use tauri::{Emitter, Manager, State};
 use tauri_plugin_global_shortcut::{Code, GlobalShortcutExt, Modifiers, Shortcut, ShortcutState};
@@ -25,6 +25,7 @@ pub mod bridge;
 pub mod clickthrough;
 pub mod command;
 pub mod control;
+pub mod ddc;
 pub mod display;
 pub mod event;
 pub mod ha;
@@ -39,8 +40,8 @@ pub mod process_diag;
 pub mod recyclebin;
 pub mod rss;
 pub mod sensors;
-pub mod stocks;
 pub mod state;
+pub mod stocks;
 pub mod timings;
 pub mod weather;
 pub mod wifi;
@@ -54,7 +55,7 @@ pub struct AppState {
 /// studio construction (it listens for `open_studio`) — but `main` is DESTROYED to reclaim its renderer
 /// when the primary monitor is empty (overlay.ts `setMainWindowVisible` / command.rs `watch_layout`),
 /// and a dead window can't host that listener. So when `main` is absent we build the studio directly
-/// here, mirroring overlay.ts `openStudio`, keeping the tray "Open designer", the tray left-click, and
+/// here, mirroring overlay.ts `openStudio`, keeping the tray "Open studio", the tray left-click, and
 /// the single-instance second-launch working even with no primary overlay present. Runs on the main
 /// thread (its callers are tray/single-instance handlers on the event loop).
 fn open_or_focus_studio(app: &tauri::AppHandle) {
@@ -101,6 +102,31 @@ fn launched_with_studio_flag() -> bool {
     std::env::args().any(|arg| arg == "--studio")
 }
 
+/// Whether this process should run as an independent EXTRA instance — typically a dev/debug build run
+/// alongside the installed release. When set, the single-instance lock is skipped (so this process
+/// doesn't just focus the already-running one and exit) AND the config dir is isolated to a `multi/`
+/// subfolder (see `command::config_root`), so it never clobbers the release's widgets.json / themes /
+/// layouts. Enabled by the `--multi` flag or `WIDGETSACK_MULTI=1`. Memoized — args/env are fixed for
+/// the process lifetime.
+pub fn multi_instance() -> bool {
+    use std::sync::OnceLock;
+    static MULTI: OnceLock<bool> = OnceLock::new();
+    *MULTI.get_or_init(|| {
+        std::env::args().any(|arg| arg == "--multi")
+            || std::env::var("WIDGETSACK_MULTI")
+                .map(|v| !v.is_empty() && v != "0")
+                .unwrap_or(false)
+    })
+}
+
+/// Whether this is a dev / extra instance — launched with `--multi` (run alongside the installed
+/// release) or built in debug. The studio shows a small "dev" badge by the window controls so it's
+/// distinguishable from the real release at a glance.
+#[tauri::command]
+fn is_dev_instance() -> bool {
+    multi_instance() || cfg!(debug_assertions)
+}
+
 /// The window-state the app persists across runs: size / position / maximized / fullscreen, but NOT
 /// decorations or visibility (config + the frontend own those — see the plugin registration). Shared
 /// by the plugin (what it saves + restores) AND the studio-close flush below, so both agree.
@@ -124,13 +150,23 @@ async fn main() -> Result<(), ()> {
     // SessionUpdateEvents) can't briefly block the gsmtc listener task on a full channel.
     let (tx_gsmtc, mut rx_gsmtc) = mpsc::channel(16);
 
-    tauri::Builder::default()
-        // Single-instance MUST be the first plugin (its callback fires synchronously on a second
-        // launch, before windows exist). A second launch focuses the running app by emitting
-        // open_studio (the primary overlay opens the studio), then that process exits.
-        .plugin(tauri_plugin_single_instance::init(|app, _argv, _cwd| {
+    // Single-instance MUST be the first plugin (its callback fires synchronously on a second
+    // launch, before windows exist). A second launch focuses the running app by emitting
+    // open_studio (the primary overlay opens the studio), then that process exits. SKIPPED for an
+    // extra dev instance (`--multi` / WIDGETSACK_MULTI), so it can run alongside the installed
+    // release instead of just focusing it — see `multi_instance`.
+    let builder = tauri::Builder::default();
+    let builder = if multi_instance() {
+        eprintln!(
+            "[widgetsack] multi-instance: single-instance lock skipped; config isolated to <app config>/multi"
+        );
+        builder
+    } else {
+        builder.plugin(tauri_plugin_single_instance::init(|app, _argv, _cwd| {
             open_or_focus_studio(app);
         }))
+    };
+    builder
         // "Launch at login" support. The Settings toggle enables/disables it via the granted
         // autostart:* commands (overlay.json capability); registering it here just makes them work.
         .plugin(tauri_plugin_autostart::init(
@@ -200,6 +236,7 @@ async fn main() -> Result<(), ()> {
         .register_uri_scheme_protocol("art", |ctx, request| art::serve_art(ctx, request))
         .invoke_handler(tauri::generate_handler![
             get_initial_sessions,
+            is_dev_instance,
             command::load_layout,
             command::save_layout,
             command::load_controls,
@@ -237,6 +274,8 @@ async fn main() -> Result<(), ()> {
             command::check_app_update,
             command::system_fonts,
             display::list_display_names,
+            ddc::list_monitor_inputs,
+            ddc::set_monitor_input,
             clickthrough::set_interactive_rects,
             clickthrough::current_work_area,
             clickthrough::set_overlay_wallpaper,
@@ -257,6 +296,8 @@ async fn main() -> Result<(), ()> {
             ha::list_ha_entities,
             ha::ha_registry_snapshot,
             ha::ha_call_service,
+            ha::ha_history,
+            ha::ha_media_art,
             ha::save_ha_config,
             ha::ha_config_status,
             ha::ha_test_connection,
@@ -385,27 +426,47 @@ async fn main() -> Result<(), ()> {
             // clickthrough watcher has no message pump). No-op off Windows.
             windowmgr::run_drag_watcher(app.handle().clone());
 
-            // Tray menu: the only reliable way to toggle edit mode while the overlay
-            // is click-through (a passive window receives no in-app keys).
-            let edit_item = MenuItemBuilder::with_id("edit", "Edit layout").build(app)?;
-            let designer_item = MenuItemBuilder::with_id("designer", "Open designer").build(app)?;
+            // Tray menu (right-click): open the studio, the two overlay utilities, a launch-at-login
+            // toggle, then Quit (separated). Edit mode is NOT here — it lives on Ctrl+E and the global
+            // hotkey; a tray toggle for it read as confusing chrome.
+            let designer_item = MenuItemBuilder::with_id("designer", "Open studio").build(app)?;
             // Snap every open window that matches a zone widget's rule into that zone (overlays handle it).
             let arrange_item = MenuItemBuilder::with_id("arrange", "Arrange windows").build(app)?;
+            // Re-fit overlays to the current display layout — for when monitors are moved/added/removed
+            // at runtime (no per-window scale-change event fires for that, so overlays go stale).
+            let refit_item =
+                MenuItemBuilder::with_id("refit", "Re-fit overlays to displays").build(app)?;
+            // "Start at login" — a check item mirroring the Settings toggle (the durable HKCU pref). Read
+            // the current state for the initial check; the handler flips it via the same autostart path.
+            let autostart_on =
+                autostart::get_autostart_enabled(app.handle().clone()).unwrap_or(false);
+            let autostart_item = CheckMenuItemBuilder::with_id("autostart", "Start at login")
+                .checked(autostart_on)
+                .build(app)?;
             let quit_item = MenuItemBuilder::with_id("quit", "Quit").build(app)?;
             let tray_menu = MenuBuilder::new(app)
-                .item(&edit_item)
                 .item(&designer_item)
                 .item(&arrange_item)
+                .item(&refit_item)
+                .item(&autostart_item)
+                .separator()
                 .item(&quit_item)
                 .build()?;
+            // Mark a dev / extra instance in the tooltip too (matches the studio "dev" badge), so a
+            // --multi / debug instance is identifiable from the tray.
+            let dev_suffix = if is_dev_instance() { " (dev)" } else { "" };
             let _tray = TrayIconBuilder::new()
                 .icon(app.default_window_icon().unwrap().clone())
-                .tooltip("Widget overlay — right-click for menu")
+                .tooltip(format!(
+                    "widgetsack v{}{}: click to open studio",
+                    app.package_info().version,
+                    dev_suffix
+                ))
                 .menu(&tray_menu)
-                .on_menu_event(|app, event| match event.id().as_ref() {
-                    "edit" => {
-                        let _ = app.emit(bridge::TOGGLE_EDIT_EVENT, ());
-                    }
+                // The menu is RIGHT-click only; left-click opens the studio (on_tray_icon_event below).
+                // Tauri's default ALSO pops the menu on left-click, so a left-click would do both — off.
+                .show_menu_on_left_click(false)
+                .on_menu_event(move |app, event| match event.id().as_ref() {
                     "designer" => {
                         // Opens (or focuses) the studio. Falls back to building it directly when the
                         // primary overlay (`main`) was reclaimed and can't host the open_studio listener.
@@ -415,6 +476,18 @@ async fn main() -> Result<(), ()> {
                         // Each overlay snaps the windows matching ITS monitor's zone rules.
                         let _ = app.emit(bridge::ARRANGE_ZONES_EVENT, ());
                     }
+                    "refit" => {
+                        // Re-fit every overlay to the CURRENT display layout (monitors moved/added/removed).
+                        let _ = app.emit(bridge::REFIT_OVERLAYS_EVENT, ());
+                    }
+                    "autostart" => {
+                        // Flip launch-at-login via the same durable-pref path as Settings, then reflect the
+                        // applied state on the check item (clicking a check item doesn't auto-toggle it).
+                        let now = autostart::get_autostart_enabled(app.clone()).unwrap_or(false);
+                        let applied =
+                            autostart::set_autostart_enabled(app.clone(), !now).unwrap_or(now);
+                        let _ = autostart_item.set_checked(applied);
+                    }
                     "quit" => app.exit(0),
                     _ => {}
                 })
diff --git a/widgetsack/src/media.rs b/widgetsack/src/media.rs
index d14f75e..019bb56 100644
--- a/widgetsack/src/media.rs
+++ b/widgetsack/src/media.rs
@@ -131,7 +131,7 @@ fn resolve_session(
     source: Option<&str>,
 ) -> Result<Option<windows::Media::Control::GlobalSystemMediaTransportControlsSession>, String> {
     use windows::Media::Control::GlobalSystemMediaTransportControlsSessionManager as Manager;
-    use windows::Win32::System::Com::{CoInitializeEx, COINIT_MULTITHREADED};
+    use windows::Win32::System::Com::{COINIT_MULTITHREADED, CoInitializeEx};
 
     // Best-effort: S_OK / S_FALSE (already inited) / RPC_E_CHANGED_MODE are all fine to ignore.
     unsafe {
@@ -173,7 +173,11 @@ fn session_for_source(
 }
 
 #[cfg(not(target_os = "windows"))]
-async fn control(_action: String, _source: Option<String>, _value: Option<f64>) -> Result<(), String> {
+async fn control(
+    _action: String,
+    _source: Option<String>,
+    _value: Option<f64>,
+) -> Result<(), String> {
     Err("media control is only available on Windows".to_string())
 }
 
diff --git a/widgetsack/src/mqtt.rs b/widgetsack/src/mqtt.rs
index ddd82ab..0f44662 100644
--- a/widgetsack/src/mqtt.rs
+++ b/widgetsack/src/mqtt.rs
@@ -103,7 +103,9 @@ fn mqtt_config_path<R: Runtime>(app: &AppHandle<R>) -> Result<PathBuf, String> {
 pub fn load_mqtt_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<MqttConfig>, String> {
     let path = mqtt_config_path(app)?;
     match std::fs::read_to_string(&path) {
-        Ok(txt) => serde_json::from_str(&txt).map(Some).map_err(|e| e.to_string()),
+        Ok(txt) => serde_json::from_str(&txt)
+            .map(Some)
+            .map_err(|e| e.to_string()),
         Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
         Err(err) => Err(err.to_string()),
     }
@@ -307,12 +309,13 @@ pub async fn run_mqtt_client<R: Runtime>(
                 }
                 // Record the seen topic (keeps a discovered entry's friendly label if already set).
                 if let Ok(mut cat) = catalog.lock() {
-                    cat.entry(p.topic.clone()).or_insert_with(|| MqttCatalogEntry {
-                        id: topic_to_id(&p.topic),
-                        topic: p.topic.clone(),
-                        label: None,
-                        unit: None,
-                    });
+                    cat.entry(p.topic.clone())
+                        .or_insert_with(|| MqttCatalogEntry {
+                            id: topic_to_id(&p.topic),
+                            topic: p.topic.clone(),
+                            label: None,
+                            unit: None,
+                        });
                 }
                 let batch = payload_to_samples(&p.topic, &payload, now_ms());
                 let _ = app.emit(TELEMETRY_EVENT, &batch);
@@ -483,7 +486,10 @@ mod tests {
         assert!(ids.contains(&"mqtt.t/dev.name")); // string field → text
         assert!(ids.contains(&"mqtt.t/dev.on")); // bool field → text
         let temp = s.iter().find(|x| x.sensor == "mqtt.t/dev.temp").unwrap();
-        assert_eq!(serde_json::to_value(temp).unwrap()["value"]["kind"], "scalar");
+        assert_eq!(
+            serde_json::to_value(temp).unwrap()["value"]["kind"],
+            "scalar"
+        );
     }
 
     #[test]
diff --git a/widgetsack/src/netconn.rs b/widgetsack/src/netconn.rs
index bcfdb96..ebd546b 100644
--- a/widgetsack/src/netconn.rs
+++ b/widgetsack/src/netconn.rs
@@ -149,7 +149,10 @@ pub fn aggregate(conns: &[RawConn], names: &HashMap<u32, String>) -> (Vec<ProcCo
         // Drop pids with nothing established or listening (e.g. only transient states seen).
         .filter(|(_, a)| a.established > 0 || a.listening > 0)
         .map(|(pid, a)| ProcConn {
-            proc: names.get(&pid).cloned().unwrap_or_else(|| format!("pid {pid}")),
+            proc: names
+                .get(&pid)
+                .cloned()
+                .unwrap_or_else(|| format!("pid {pid}")),
             pid,
             established: a.established,
             listening: a.listening,
@@ -168,7 +171,11 @@ pub fn aggregate(conns: &[RawConn], names: &HashMap<u32, String>) -> (Vec<ProcCo
 }
 
 /// Build the `net.conn.*` samples from raw rows + a pid→name map. Pure seam — fully unit-tested.
-pub fn build_samples(ts: u64, conns: &[RawConn], names: &HashMap<u32, String>) -> Vec<SensorSample> {
+pub fn build_samples(
+    ts: u64,
+    conns: &[RawConn],
+    names: &HashMap<u32, String>,
+) -> Vec<SensorSample> {
     let (rows, totals) = aggregate(conns, names);
     let list = serde_json::to_value(&rows).unwrap_or(serde_json::Value::Null);
     vec![
@@ -196,9 +203,8 @@ fn read_tcp_table() -> Vec<RawConn> {
     let mut size: u32 = 0;
     // First call sizes the buffer (expects ERROR_INSUFFICIENT_BUFFER).
     // SAFETY: a sizing call — null table pointer, size-out only.
-    let rc = unsafe {
-        GetExtendedTcpTable(None, &mut size, false, AF_INET, TCP_TABLE_OWNER_PID_ALL, 0)
-    };
+    let rc =
+        unsafe { GetExtendedTcpTable(None, &mut size, false, AF_INET, TCP_TABLE_OWNER_PID_ALL, 0) };
     if rc != ERROR_INSUFFICIENT_BUFFER.0 || size == 0 {
         return Vec::new();
     }
@@ -238,7 +244,7 @@ fn read_tcp_table() -> Vec<RawConn> {
 fn process_names() -> HashMap<u32, String> {
     use windows::Win32::Foundation::CloseHandle;
     use windows::Win32::System::Diagnostics::ToolHelp::{
-        CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W,
+        CreateToolhelp32Snapshot, PROCESSENTRY32W, Process32FirstW, Process32NextW,
         TH32CS_SNAPPROCESS,
     };
 
@@ -254,7 +260,11 @@ fn process_names() -> HashMap<u32, String> {
     // SAFETY: `pe.dwSize` is set; First/Next fill `pe` until they return Err (end of list).
     if unsafe { Process32FirstW(snap, &mut pe) }.is_ok() {
         loop {
-            let len = pe.szExeFile.iter().position(|&c| c == 0).unwrap_or(pe.szExeFile.len());
+            let len = pe
+                .szExeFile
+                .iter()
+                .position(|&c| c == 0)
+                .unwrap_or(pe.szExeFile.len());
             let name = String::from_utf16_lossy(&pe.szExeFile[..len]);
             if !name.is_empty() {
                 map.insert(pe.th32ProcessID, name);
@@ -336,19 +346,57 @@ mod tests {
     fn aggregate_counts_and_ranks_by_public_talkers() {
         let conns = vec![
             // chrome: two established to public + one to a private LAN host.
-            RawConn { pid: 100, state: STATE_ESTAB, remote_addr: addr(8, 8, 8, 8), remote_port: port(443) },
-            RawConn { pid: 100, state: STATE_ESTAB, remote_addr: addr(1, 1, 1, 1), remote_port: port(443) },
-            RawConn { pid: 100, state: STATE_ESTAB, remote_addr: addr(192, 168, 1, 9), remote_port: port(445) },
+            RawConn {
+                pid: 100,
+                state: STATE_ESTAB,
+                remote_addr: addr(8, 8, 8, 8),
+                remote_port: port(443),
+            },
+            RawConn {
+                pid: 100,
+                state: STATE_ESTAB,
+                remote_addr: addr(1, 1, 1, 1),
+                remote_port: port(443),
+            },
+            RawConn {
+                pid: 100,
+                state: STATE_ESTAB,
+                remote_addr: addr(192, 168, 1, 9),
+                remote_port: port(445),
+            },
             // svchost: a listener only.
-            RawConn { pid: 200, state: STATE_LISTEN, remote_addr: addr(0, 0, 0, 0), remote_port: port(135) },
+            RawConn {
+                pid: 200,
+                state: STATE_LISTEN,
+                remote_addr: addr(0, 0, 0, 0),
+                remote_port: port(135),
+            },
             // foo: one established to a public host.
-            RawConn { pid: 300, state: STATE_ESTAB, remote_addr: addr(93, 184, 216, 34), remote_port: port(80) },
+            RawConn {
+                pid: 300,
+                state: STATE_ESTAB,
+                remote_addr: addr(93, 184, 216, 34),
+                remote_port: port(80),
+            },
             // transient state is ignored.
-            RawConn { pid: 300, state: 4 /* SYN_SENT */, remote_addr: addr(5, 5, 5, 5), remote_port: port(80) },
+            RawConn {
+                pid: 300,
+                state: 4, /* SYN_SENT */
+                remote_addr: addr(5, 5, 5, 5),
+                remote_port: port(80),
+            },
         ];
-        let (rows, totals) = aggregate(&conns, &names(&[(100, "chrome.exe"), (200, "svchost.exe")]));
-
-        assert_eq!(totals, ConnTotals { established: 4, listening: 1, public: 3 });
+        let (rows, totals) =
+            aggregate(&conns, &names(&[(100, "chrome.exe"), (200, "svchost.exe")]));
+
+        assert_eq!(
+            totals,
+            ConnTotals {
+                established: 4,
+                listening: 1,
+                public: 3
+            }
+        );
         // chrome (2 public) ranks before foo (1 public) before svchost (0 public, listener).
         assert_eq!(rows.len(), 3);
         assert_eq!(rows[0].proc, "chrome.exe");
diff --git a/widgetsack/src/ping.rs b/widgetsack/src/ping.rs
index bf96cc5..6884fe0 100644
--- a/widgetsack/src/ping.rs
+++ b/widgetsack/src/ping.rs
@@ -93,7 +93,7 @@ fn resolve_ipv4(host: &str) -> Option<Ipv4Addr> {
 #[cfg(target_os = "windows")]
 fn icmp_ping(addr: Ipv4Addr, timeout_ms: u32) -> Option<f64> {
     use windows::Win32::NetworkManagement::IpHelper::{
-        IcmpCloseHandle, IcmpCreateFile, IcmpSendEcho, ICMP_ECHO_REPLY,
+        ICMP_ECHO_REPLY, IcmpCloseHandle, IcmpCreateFile, IcmpSendEcho,
     };
 
     // SAFETY: IcmpCreateFile returns a handle (Err / INVALID_HANDLE_VALUE on failure).
@@ -192,7 +192,12 @@ mod tests {
     fn active(entries: &[(&str, &[&str])]) -> HashMap<String, HashSet<String>> {
         entries
             .iter()
-            .map(|(label, ids)| (label.to_string(), ids.iter().map(|s| s.to_string()).collect()))
+            .map(|(label, ids)| {
+                (
+                    label.to_string(),
+                    ids.iter().map(|s| s.to_string()).collect(),
+                )
+            })
             .collect()
     }
 
@@ -200,7 +205,10 @@ mod tests {
     fn host_of_strips_prefix_and_suffix_even_with_dotted_ips() {
         assert_eq!(host_of("net.ping.1.1.1.1.ms"), Some("1.1.1.1"));
         assert_eq!(host_of("net.ping.8.8.8.8.up"), Some("8.8.8.8"));
-        assert_eq!(host_of("net.ping.cloudflare.com.ms"), Some("cloudflare.com"));
+        assert_eq!(
+            host_of("net.ping.cloudflare.com.ms"),
+            Some("cloudflare.com")
+        );
         assert_eq!(host_of("net.ping..ms"), None); // empty host
         assert_eq!(host_of("net.down"), None);
         assert_eq!(host_of("*"), None);
@@ -209,7 +217,10 @@ mod tests {
     #[test]
     fn hosts_from_active_dedupes_sorts_and_ignores_wildcard() {
         let a = active(&[
-            ("studio", &["*", "net.ping.1.1.1.1.ms", "net.ping.1.1.1.1.up"]),
+            (
+                "studio",
+                &["*", "net.ping.1.1.1.1.ms", "net.ping.1.1.1.1.up"],
+            ),
             ("main", &["net.ping.8.8.8.8.ms", "cpu.total"]),
         ]);
         assert_eq!(hosts_from_active(&a), vec!["1.1.1.1", "8.8.8.8"]);
diff --git a/widgetsack/src/recyclebin.rs b/widgetsack/src/recyclebin.rs
index e4fcdbd..ffa663b 100644
--- a/widgetsack/src/recyclebin.rs
+++ b/widgetsack/src/recyclebin.rs
@@ -17,8 +17,8 @@ pub fn recyclebin_samples_from(items: i64, bytes: i64, ts: u64) -> Vec<SensorSam
 /// so the per-tick cost is small.
 #[cfg(target_os = "windows")]
 fn query() -> Option<(i64, i64)> {
+    use windows::Win32::UI::Shell::{SHQUERYRBINFO, SHQueryRecycleBinW};
     use windows::core::PCWSTR;
-    use windows::Win32::UI::Shell::{SHQueryRecycleBinW, SHQUERYRBINFO};
 
     let mut info = SHQUERYRBINFO {
         cbSize: std::mem::size_of::<SHQUERYRBINFO>() as u32,
diff --git a/widgetsack/src/rss.rs b/widgetsack/src/rss.rs
index 6320920..260d5d1 100644
--- a/widgetsack/src/rss.rs
+++ b/widgetsack/src/rss.rs
@@ -97,7 +97,10 @@ fn extract_tag(block: &str, tag: &str) -> Option<String> {
     let close = format!("</{tag}>");
     let end = block[gt + 1..].find(&close)? + gt + 1;
     let raw = block[gt + 1..end].trim();
-    if let Some(inner) = raw.strip_prefix("<![CDATA[").and_then(|s| s.strip_suffix("]]>")) {
+    if let Some(inner) = raw
+        .strip_prefix("<![CDATA[")
+        .and_then(|s| s.strip_suffix("]]>"))
+    {
         Some(inner.trim().to_string())
     } else {
         Some(unescape(raw))
@@ -169,7 +172,9 @@ fn rss_config_path<R: Runtime>(app: &AppHandle<R>) -> Result<PathBuf, String> {
 pub fn load_rss_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<RssConfig>, String> {
     let path = rss_config_path(app)?;
     match std::fs::read_to_string(&path) {
-        Ok(txt) => serde_json::from_str(&txt).map(Some).map_err(|e| e.to_string()),
+        Ok(txt) => serde_json::from_str(&txt)
+            .map(Some)
+            .map_err(|e| e.to_string()),
         Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
         Err(err) => Err(err.to_string()),
     }
@@ -377,7 +382,13 @@ mod tests {
         let items = parse_feed_items(xml, 10);
         assert_eq!(items.len(), 3);
         // The channel title is NOT picked up — only item titles.
-        assert_eq!(items[0], FeedItem { title: "First & Foremost".into(), link: "https://ex.com/1".into() });
+        assert_eq!(
+            items[0],
+            FeedItem {
+                title: "First & Foremost".into(),
+                link: "https://ex.com/1".into()
+            }
+        );
         assert_eq!(items[1].title, "Second <b>story</b>"); // CDATA kept literal
         assert_eq!(items[1].link, "https://ex.com/2");
     }
@@ -391,7 +402,13 @@ mod tests {
         </feed>"#;
         let items = parse_feed_items(xml, 10);
         assert_eq!(items.len(), 2);
-        assert_eq!(items[0], FeedItem { title: "Alpha".into(), link: "https://ex.com/a".into() });
+        assert_eq!(
+            items[0],
+            FeedItem {
+                title: "Alpha".into(),
+                link: "https://ex.com/a".into()
+            }
+        );
         assert_eq!(items[1].link, "https://ex.com/b");
     }
 
@@ -408,7 +425,10 @@ mod tests {
 
     #[test]
     fn feed_to_samples_emits_json_list_and_count() {
-        let items = vec![FeedItem { title: "X".into(), link: "u".into() }];
+        let items = vec![FeedItem {
+            title: "X".into(),
+            link: "u".into(),
+        }];
         let s = feed_to_samples(&items, 5);
         assert_eq!(s[0].sensor, "rss.list");
         assert!(matches!(s[0].value, SensorValue::Json(_)));
@@ -420,7 +440,12 @@ mod tests {
 
     #[test]
     fn has_feed_requires_an_http_url() {
-        let mk = |u: &str| RssConfig { url: u.into(), count: 8, title: String::new(), poll_interval_secs: 900 };
+        let mk = |u: &str| RssConfig {
+            url: u.into(),
+            count: 8,
+            title: String::new(),
+            poll_interval_secs: 900,
+        };
         assert!(has_feed(&mk("https://example.com/feed.xml")));
         assert!(has_feed(&mk("http://lan.local/rss")));
         assert!(!has_feed(&mk("")));
diff --git a/widgetsack/src/sensors.rs b/widgetsack/src/sensors.rs
index ad5edc6..c5b1836 100644
--- a/widgetsack/src/sensors.rs
+++ b/widgetsack/src/sensors.rs
@@ -41,7 +41,10 @@ use std::path::Path;
 use std::sync::Mutex;
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
-use nvml_wrapper::{enum_wrappers::device::{Clock, TemperatureSensor}, Nvml};
+use nvml_wrapper::{
+    Nvml,
+    enum_wrappers::device::{Clock, TemperatureSensor},
+};
 use serde::Serialize;
 use sysinfo::{Disks, Networks, ProcessesToUpdate, System};
 use tauri::{AppHandle, Emitter, Manager, Runtime};
@@ -171,7 +174,9 @@ fn name_matches(proc_name: &str, watched: &str) -> bool {
 
 /// Flatten the latest-value map to a `{ id: number|string }` JSON object — Scalar and Text only
 /// (Series/Json are dropped; not useful in a flat snapshot). Pure seam for the MCP live-state file.
-fn flatten_latest(latest: &HashMap<String, SensorValue>) -> serde_json::Map<String, serde_json::Value> {
+fn flatten_latest(
+    latest: &HashMap<String, SensorValue>,
+) -> serde_json::Map<String, serde_json::Value> {
     let mut out = serde_json::Map::new();
     for (id, v) in latest {
         match v {
@@ -301,19 +306,38 @@ fn perf_info_samples(ts: u64) -> Vec<SensorSample> {
     use windows::Win32::System::ProcessStatus::{GetPerformanceInfo, PERFORMANCE_INFORMATION};
 
     let cb = std::mem::size_of::<PERFORMANCE_INFORMATION>() as u32;
-    let mut pi = PERFORMANCE_INFORMATION { cb, ..Default::default() };
+    let mut pi = PERFORMANCE_INFORMATION {
+        cb,
+        ..Default::default()
+    };
     // SAFETY: pi is a valid owned struct and cb is its byte size; GetPerformanceInfo fills it.
     if unsafe { GetPerformanceInfo(&mut pi, cb) }.is_err() {
         return Vec::new();
     }
     let page = pi.PageSize;
     vec![
-        SensorSample::scalar("mem.commit.used", ts, bytes_from_pages(pi.CommitTotal, page)),
-        SensorSample::scalar("mem.commit.limit", ts, bytes_from_pages(pi.CommitLimit, page)),
+        SensorSample::scalar(
+            "mem.commit.used",
+            ts,
+            bytes_from_pages(pi.CommitTotal, page),
+        ),
+        SensorSample::scalar(
+            "mem.commit.limit",
+            ts,
+            bytes_from_pages(pi.CommitLimit, page),
+        ),
         SensorSample::scalar("mem.commit.peak", ts, bytes_from_pages(pi.CommitPeak, page)),
         SensorSample::scalar("mem.cached", ts, bytes_from_pages(pi.SystemCache, page)),
-        SensorSample::scalar("mem.kernel.paged", ts, bytes_from_pages(pi.KernelPaged, page)),
-        SensorSample::scalar("mem.kernel.nonpaged", ts, bytes_from_pages(pi.KernelNonpaged, page)),
+        SensorSample::scalar(
+            "mem.kernel.paged",
+            ts,
+            bytes_from_pages(pi.KernelPaged, page),
+        ),
+        SensorSample::scalar(
+            "mem.kernel.nonpaged",
+            ts,
+            bytes_from_pages(pi.KernelNonpaged, page),
+        ),
         SensorSample::scalar("host.handles", ts, f64::from(pi.HandleCount)),
         SensorSample::scalar("host.threads", ts, f64::from(pi.ThreadCount)),
     ]
@@ -333,7 +357,7 @@ fn perf_info_samples(_ts: u64) -> Vec<SensorSample> {
 #[cfg(target_os = "windows")]
 fn cpu_freq_samples(ts: u64, logical_cores: usize) -> Vec<SensorSample> {
     use windows::Win32::System::Power::{
-        CallNtPowerInformation, ProcessorInformation, PROCESSOR_POWER_INFORMATION,
+        CallNtPowerInformation, PROCESSOR_POWER_INFORMATION, ProcessorInformation,
     };
 
     if logical_cores == 0 {
@@ -367,8 +391,16 @@ fn cpu_freq_samples(ts: u64, logical_cores: usize) -> Vec<SensorSample> {
         current_max = current_max.max(p.CurrentMhz);
         rated_max = rated_max.max(p.MaxMhz);
     }
-    out.push(SensorSample::scalar("cpu.freq.current", ts, f64::from(current_max)));
-    out.push(SensorSample::scalar("cpu.freq.max", ts, f64::from(rated_max)));
+    out.push(SensorSample::scalar(
+        "cpu.freq.current",
+        ts,
+        f64::from(current_max),
+    ));
+    out.push(SensorSample::scalar(
+        "cpu.freq.max",
+        ts,
+        f64::from(rated_max),
+    ));
     out
 }
 
@@ -461,14 +493,14 @@ fn utf16_to_string(buf: &[u16]) -> String {
 /// volume handle is opened with zero access rights (no admin needed). `None` on any failure.
 #[cfg(target_os = "windows")]
 fn read_disk_io(letter: &str) -> Option<DiskIo> {
-    use windows::core::PCWSTR;
     use windows::Win32::Foundation::CloseHandle;
     use windows::Win32::Storage::FileSystem::{
         CreateFileW, FILE_FLAGS_AND_ATTRIBUTES, FILE_SHARE_MODE, FILE_SHARE_READ, FILE_SHARE_WRITE,
         OPEN_EXISTING,
     };
-    use windows::Win32::System::Ioctl::{DISK_PERFORMANCE, IOCTL_DISK_PERFORMANCE};
     use windows::Win32::System::IO::DeviceIoControl;
+    use windows::Win32::System::Ioctl::{DISK_PERFORMANCE, IOCTL_DISK_PERFORMANCE};
+    use windows::core::PCWSTR;
 
     let path: Vec<u16> = format!("\\\\.\\{}:", letter.to_uppercase())
         .encode_utf16()
@@ -527,7 +559,7 @@ fn read_disk_io(_letter: &str) -> Option<DiskIo> {
 #[cfg(target_os = "windows")]
 fn battery_power_samples(ts: u64) -> Vec<SensorSample> {
     use windows::Win32::System::Power::{
-        CallNtPowerInformation, SystemBatteryState, SYSTEM_BATTERY_STATE,
+        CallNtPowerInformation, SYSTEM_BATTERY_STATE, SystemBatteryState,
     };
 
     // SAFETY: a zeroed POD output buffer, filled by CallNtPowerInformation.
@@ -548,10 +580,18 @@ fn battery_power_samples(ts: u64) -> Vec<SensorSample> {
     // Rate is mW, signed (reinterpret the u32 as i32); 0x8000_0000 is the "unknown" sentinel.
     let rate = sbs.Rate as i32;
     if rate != i32::MIN {
-        out.push(SensorSample::scalar("battery.rate", ts, f64::from(rate) / 1000.0));
+        out.push(SensorSample::scalar(
+            "battery.rate",
+            ts,
+            f64::from(rate) / 1000.0,
+        ));
     }
     if sbs.MaxCapacity != u32::MAX {
-        out.push(SensorSample::scalar("battery.capacity.full", ts, f64::from(sbs.MaxCapacity) / 1000.0));
+        out.push(SensorSample::scalar(
+            "battery.capacity.full",
+            ts,
+            f64::from(sbs.MaxCapacity) / 1000.0,
+        ));
     }
     if sbs.RemainingCapacity != u32::MAX {
         out.push(SensorSample::scalar(
@@ -600,11 +640,23 @@ fn net_link_samples(ts: u64) -> Vec<SensorSample> {
     let mut out = vec![SensorSample::text(
         "net.state",
         ts,
-        if any_connected { "connected" } else { "disconnected" },
+        if any_connected {
+            "connected"
+        } else {
+            "disconnected"
+        },
     )];
     if let Some(r) = best {
-        out.push(SensorSample::scalar("net.linkspeed.rx", ts, (r.ReceiveLinkSpeed / 8) as f64));
-        out.push(SensorSample::scalar("net.linkspeed.tx", ts, (r.TransmitLinkSpeed / 8) as f64));
+        out.push(SensorSample::scalar(
+            "net.linkspeed.rx",
+            ts,
+            (r.ReceiveLinkSpeed / 8) as f64,
+        ));
+        out.push(SensorSample::scalar(
+            "net.linkspeed.tx",
+            ts,
+            (r.TransmitLinkSpeed / 8) as f64,
+        ));
         let name = utf16_to_string(&r.Alias);
         if !name.is_empty() {
             out.push(SensorSample::text("net.adapter", ts, name));
@@ -648,7 +700,10 @@ pub async fn set_active_sensors<R: Runtime>(
 /// counts when the union of every window's reported set is EMPTY (nobody has reported yet, so don't
 /// blank sensors at startup), OR any window asked for everything (`"*"`), OR any window's id
 /// satisfies `pred`.
-pub(crate) fn any_wanted(active: &HashMap<String, HashSet<String>>, pred: impl Fn(&str) -> bool) -> bool {
+pub(crate) fn any_wanted(
+    active: &HashMap<String, HashSet<String>>,
+    pred: impl Fn(&str) -> bool,
+) -> bool {
     if active.values().all(|ids| ids.is_empty()) {
         return true;
     }
@@ -824,14 +879,32 @@ pub async fn run_system_sensors<R: Runtime>(app: AppHandle<R>) {
         }
 
         for (i, cpu) in sys.cpus().iter().enumerate() {
-            batch.push(SensorSample::scalar(core_sensor_id(i), ts, f64::from(cpu.cpu_usage())));
+            batch.push(SensorSample::scalar(
+                core_sensor_id(i),
+                ts,
+                f64::from(cpu.cpu_usage()),
+            ));
         }
 
         // Compute all demand-gates under ONE brief lock, then DROP it before any expensive I/O
         // (NVML, process enumeration, disk refresh, frequency refresh) — the std Mutex must never be
         // held across an await or a blocking driver call.
         #[allow(clippy::type_complexity)]
-        let (want_gpu, want_disks, want_disk_io, want_procs, proc_w, proc_watch, want_freq, want_perf, want_cpufreq, want_netlink, want_conns, want_wifi, want_recyclebin) = {
+        let (
+            want_gpu,
+            want_disks,
+            want_disk_io,
+            want_procs,
+            proc_w,
+            proc_watch,
+            want_freq,
+            want_perf,
+            want_cpufreq,
+            want_netlink,
+            want_conns,
+            want_wifi,
+            want_recyclebin,
+        ) = {
             let active: tauri::State<ActiveSensors> = app.state();
             let g = active.0.lock().unwrap_or_else(|e| e.into_inner());
             let pw = |p: &str| any_wanted(&g, |id| id.starts_with(p));
@@ -898,10 +971,22 @@ pub async fn run_system_sensors<R: Runtime>(app: AppHandle<R>) {
                     ts,
                     if count > 0 { 1.0 } else { 0.0 },
                 ));
-                batch.push(SensorSample::scalar(format!("proc.watch.{watched}.count"), ts, count as f64));
+                batch.push(SensorSample::scalar(
+                    format!("proc.watch.{watched}.count"),
+                    ts,
+                    count as f64,
+                ));
                 if count > 0 {
-                    batch.push(SensorSample::scalar(format!("proc.watch.{watched}.cpu"), ts, cpu));
-                    batch.push(SensorSample::scalar(format!("proc.watch.{watched}.mem"), ts, mem));
+                    batch.push(SensorSample::scalar(
+                        format!("proc.watch.{watched}.cpu"),
+                        ts,
+                        cpu,
+                    ));
+                    batch.push(SensorSample::scalar(
+                        format!("proc.watch.{watched}.mem"),
+                        ts,
+                        mem,
+                    ));
                 }
             }
 
@@ -966,9 +1051,21 @@ pub async fn run_system_sensors<R: Runtime>(app: AppHandle<R>) {
                     let total = disk.total_space();
                     let avail = disk.available_space();
                     let used = total.saturating_sub(avail);
-                    batch.push(SensorSample::scalar(format!("disk.{letter}.total"), ts, total as f64));
-                    batch.push(SensorSample::scalar(format!("disk.{letter}.free"), ts, avail as f64));
-                    batch.push(SensorSample::scalar(format!("disk.{letter}.used"), ts, used as f64));
+                    batch.push(SensorSample::scalar(
+                        format!("disk.{letter}.total"),
+                        ts,
+                        total as f64,
+                    ));
+                    batch.push(SensorSample::scalar(
+                        format!("disk.{letter}.free"),
+                        ts,
+                        avail as f64,
+                    ));
+                    batch.push(SensorSample::scalar(
+                        format!("disk.{letter}.used"),
+                        ts,
+                        used as f64,
+                    ));
                     batch.push(SensorSample::scalar(
                         format!("disk.{letter}.used.pct"),
                         ts,
@@ -989,10 +1086,18 @@ pub async fn run_system_sensors<R: Runtime>(app: AppHandle<R>) {
             let _t = timings.start("sensors.gpu");
             if let Ok(util) = device.utilization_rates() {
                 batch.push(SensorSample::scalar("gpu.util", ts, f64::from(util.gpu)));
-                batch.push(SensorSample::scalar("gpu.mem.util", ts, f64::from(util.memory)));
+                batch.push(SensorSample::scalar(
+                    "gpu.mem.util",
+                    ts,
+                    f64::from(util.memory),
+                ));
             }
             if let Ok(mem) = device.memory_info() {
-                batch.push(SensorSample::scalar("gpu.vram", ts, percent(mem.used, mem.total)));
+                batch.push(SensorSample::scalar(
+                    "gpu.vram",
+                    ts,
+                    percent(mem.used, mem.total),
+                ));
                 batch.push(SensorSample::scalar("gpu.vram.total", ts, mem.total as f64));
                 batch.push(SensorSample::scalar("gpu.vram.used", ts, mem.used as f64));
                 batch.push(SensorSample::scalar("gpu.vram.free", ts, mem.free as f64));
@@ -1008,10 +1113,18 @@ pub async fn run_system_sensors<R: Runtime>(app: AppHandle<R>) {
             }
             // NVML reports power in milliwatts; emit watts. NotSupported on some boards → skip.
             if let Ok(mw) = device.power_usage() {
-                batch.push(SensorSample::scalar("gpu.power", ts, f64::from(mw) / 1000.0));
+                batch.push(SensorSample::scalar(
+                    "gpu.power",
+                    ts,
+                    f64::from(mw) / 1000.0,
+                ));
             }
             if let Ok(mw) = device.enforced_power_limit() {
-                batch.push(SensorSample::scalar("gpu.power.limit", ts, f64::from(mw) / 1000.0));
+                batch.push(SensorSample::scalar(
+                    "gpu.power.limit",
+                    ts,
+                    f64::from(mw) / 1000.0,
+                ));
             }
             // fan_speed is a driver setpoint percent; frequently NotSupported on laptop GPUs.
             if let Ok(pct) = device.fan_speed(0) {
@@ -1209,8 +1322,18 @@ mod tests {
     #[test]
     fn disk_io_samples_derive_rates_and_busy() {
         // query delta = 10_000_000 ×100ns = 1.0s; idle delta = 4_000_000 ×100ns = 0.4s.
-        let prev = DiskIo { idle: 0, query: 0, read: 0, written: 0 };
-        let cur = DiskIo { idle: 4_000_000, query: 10_000_000, read: 2048, written: 1024 };
+        let prev = DiskIo {
+            idle: 0,
+            query: 0,
+            read: 0,
+            written: 0,
+        };
+        let cur = DiskIo {
+            idle: 4_000_000,
+            query: 10_000_000,
+            read: 2048,
+            written: 1024,
+        };
         let s = disk_io_samples_for("c", 1, prev, cur);
         assert_eq!(s[0].sensor, "disk.c.busy.pct");
         assert_eq!(s[1].sensor, "disk.c.read");
@@ -1225,8 +1348,18 @@ mod tests {
 
         // After a demand-gate gap the query delta widens with real time, so the byte delta is spread
         // over the true elapsed and the rate stays sane — never an N× spike. 5120 B over a 5s gap.
-        let gap_prev = DiskIo { idle: 0, query: 0, read: 0, written: 0 };
-        let gap_cur = DiskIo { idle: 0, query: 50_000_000, read: 5120, written: 0 };
+        let gap_prev = DiskIo {
+            idle: 0,
+            query: 0,
+            read: 0,
+            written: 0,
+        };
+        let gap_cur = DiskIo {
+            idle: 0,
+            query: 50_000_000,
+            read: 5120,
+            written: 0,
+        };
         let g = disk_io_samples_for("c", 1, gap_prev, gap_cur);
         assert_eq!(val(&g[1].value), 1024.0); // 5120 B / 5s, not 5120 B/s
     }
@@ -1276,7 +1409,10 @@ mod tests {
         entries
             .iter()
             .map(|(label, ids)| {
-                (label.to_string(), ids.iter().map(|s| s.to_string()).collect())
+                (
+                    label.to_string(),
+                    ids.iter().map(|s| s.to_string()).collect(),
+                )
             })
             .collect()
     }
@@ -1341,22 +1477,34 @@ mod tests {
         latest.insert("cpu.series".into(), SensorValue::Series(vec![1.0, 2.0]));
         let flat = flatten_latest(&latest);
         assert_eq!(flat.get("cpu.total"), Some(&serde_json::json!(42.0)));
-        assert_eq!(flat.get("net.adapter"), Some(&serde_json::json!("Ethernet")));
+        assert_eq!(
+            flat.get("net.adapter"),
+            Some(&serde_json::json!("Ethernet"))
+        );
         assert!(!flat.contains_key("cpu.series")); // Series dropped
     }
 
     #[test]
     fn proc_watch_helpers_parse_and_match() {
         // Name extraction tolerates dots in the process name + every suffix.
-        assert_eq!(proc_watch_name_of("proc.watch.chrome.exe.running"), Some("chrome.exe"));
+        assert_eq!(
+            proc_watch_name_of("proc.watch.chrome.exe.running"),
+            Some("chrome.exe")
+        );
         assert_eq!(proc_watch_name_of("proc.watch.obs64.cpu"), Some("obs64"));
         assert_eq!(proc_watch_name_of("proc.watch.steam.mem"), Some("steam"));
         assert_eq!(proc_watch_name_of("proc.watch..running"), None);
         assert_eq!(proc_watch_name_of("proc.cpu.top.name"), None);
 
         let a = active(&[
-            ("main", &["proc.watch.chrome.exe.running", "proc.watch.chrome.exe.cpu"]),
-            ("overlay-1", &["proc.watch.Spotify.exe.running", "cpu.total"]),
+            (
+                "main",
+                &["proc.watch.chrome.exe.running", "proc.watch.chrome.exe.cpu"],
+            ),
+            (
+                "overlay-1",
+                &["proc.watch.Spotify.exe.running", "cpu.total"],
+            ),
         ]);
         assert_eq!(proc_watch_names(&a), vec!["Spotify.exe", "chrome.exe"]);
 
diff --git a/widgetsack/src/state.rs b/widgetsack/src/state.rs
index de3ad9b..37d7f03 100644
--- a/widgetsack/src/state.rs
+++ b/widgetsack/src/state.rs
@@ -1,274 +1,283 @@
-use std::{collections::HashMap, time::SystemTime};
-
-use serde::Serialize;
-
-use crate::bridge::{SESSION_CREATE_EVENT, SESSION_DELETE_EVENT, SESSION_UPDATE_EVENT};
-use crate::{event::NpSessionEvent, log, ManagerEventWrapper, SessionUpdateEventWrapper};
-
-#[derive(Debug, Clone, Serialize)]
-pub struct SessionRecord {
-    pub session_id: usize,
-    pub source: Option<String>,
-    pub timestamp_created: Option<SystemTime>,
-    pub timestamp_updated: Option<SystemTime>,
-    pub last_media_update: Option<SessionUpdateEventWrapper>,
-    pub last_model_update: Option<SessionUpdateEventWrapper>,
-}
-
-pub fn updater(
-    sessions: &mut HashMap<usize, SessionRecord>,
-    event: NpSessionEvent,
-) -> (&str, Option<SessionRecord>) {
-    match event {
-        NpSessionEvent::Create(
-            _session_id_dupe,
-            ManagerEventWrapper::SessionCreated { session_id, source },
-        ) => {
-            let new_record = SessionRecord {
-                session_id,
-                source: Some(source),
-                timestamp_created: Some(SystemTime::now()),
-                timestamp_updated: None,
-                last_media_update: None,
-                last_model_update: None,
-            };
-            let _ = (*sessions).insert(session_id, new_record.clone());
-            (SESSION_CREATE_EVENT, Some(new_record))
-        }
-        NpSessionEvent::Create(_session_id_dupe, ev) => {
-            log::warn("session", "unexpected manager event for Create")
-                .field("event", format!("{ev:?}"))
-                .emit();
-            (SESSION_CREATE_EVENT, None)
-        }
-        NpSessionEvent::Update(session_id, ev) => {
-            // Model/timeline (play/pause/seek) updates carry NO new album art — capture that before `ev`
-            // is consumed so the emit below can strip the (unchanged) cover bytes rather than re-shipping
-            // hundreds of KB over the IPC bridge on every tick.
-            let is_model = matches!(ev, SessionUpdateEventWrapper::Model(_));
-            let maybe_existing = (*sessions).get(&session_id);
-            // TODO: create np-widget-specific models for sessions and map gsmtc to it
-
-            let updated_record = if let Some(existing) = maybe_existing {
-                let mut record_mut = SessionRecord {
-                    session_id: existing.session_id,
-                    source: existing.source.clone(),
-                    timestamp_created: existing.timestamp_created,
-                    timestamp_updated: Some(SystemTime::now()),
-                    // Check if this can be CoW?
-                    last_media_update: existing.last_media_update.clone(),
-                    last_model_update: existing.last_model_update.clone(),
-                };
-
-                match ev {
-                    SessionUpdateEventWrapper::Model(_) => {
-                        record_mut.last_model_update = Some(ev);
-                    }
-                    SessionUpdateEventWrapper::Media(_, _) => {
-                        record_mut.last_media_update = Some(ev);
-                    }
-                }
-
-                record_mut
-            } else {
-                let updated_ev: SessionUpdateEventWrapper = ev;
-                SessionRecord {
-                    session_id,
-                    source: None,
-                    timestamp_created: Some(SystemTime::now()),
-                    timestamp_updated: Some(SystemTime::now()),
-                    last_media_update: match updated_ev {
-                        SessionUpdateEventWrapper::Model(_) => None,
-                        // FIXME: awful clone here
-                        SessionUpdateEventWrapper::Media(_, _) => Some(updated_ev.clone()),
-                    },
-                    last_model_update: match updated_ev {
-                        SessionUpdateEventWrapper::Model(_) => Some(updated_ev),
-                        SessionUpdateEventWrapper::Media(_, _) => None,
-                    },
-                }
-            };
-
-            let _ = (*sessions).insert(session_id, updated_record.clone());
-            // The stored record (above) keeps the art; the EMITTED one drops it on a model/timeline
-            // update so we don't re-serialise + re-send the cover bytes to every webview each tick. The
-            // frontend carries the previous cover forward by session_id (see stores.ts mergeMediaForward).
-            // A media update keeps its art so a new cover still reaches the overlay.
-            let emitted = if is_model {
-                SessionRecord {
-                    last_media_update: None,
-                    ..updated_record
-                }
-            } else {
-                updated_record
-            };
-            (SESSION_UPDATE_EVENT, Some(emitted))
-        }
-        NpSessionEvent::Delete(session_id, _ev) => {
-            let maybe_deleted_record = (*sessions).remove(&session_id);
-
-            if let Some(deleted_record) = maybe_deleted_record {
-                (SESSION_DELETE_EVENT, Some(deleted_record))
-            } else {
-                (SESSION_DELETE_EVENT, None)
-            }
-        }
-        NpSessionEvent::Unsupported(session_id, label) => {
-            log::debug("gsmtc", "unsupported event")
-                .field("label", &label)
-                .field("session_id", format!("{session_id:?}"))
-                .emit();
-            ("unsupported", None)
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use gsmtc::SessionModel;
-
-    /// A minimal `SessionModel` for building `SessionUpdateEventWrapper` events without any media
-    /// hardware. Only `source` is meaningful here; the rest are absent (None/empty).
-    fn model(source: &str) -> SessionModel {
-        SessionModel {
-            playback: None,
-            timeline: None,
-            media: None,
-            source: source.to_string(),
-        }
-    }
-
-    #[test]
-    fn create_yields_session_create_with_record_and_inserts() {
-        let mut sessions = HashMap::new();
-        let ev = NpSessionEvent::Create(
-            7,
-            ManagerEventWrapper::SessionCreated {
-                session_id: 7,
-                source: "fooplayer".to_string(),
-            },
-        );
-        let (kind, delta) = updater(&mut sessions, ev);
-        assert_eq!(kind, "session_create");
-        let record = delta.expect("create should yield a record");
-        assert_eq!(record.session_id, 7);
-        assert_eq!(record.source.as_deref(), Some("fooplayer"));
-        // The session is now tracked.
-        assert!(sessions.contains_key(&7));
-    }
-
-    #[test]
-    fn update_after_create_yields_session_update_and_keeps_source() {
-        let mut sessions = HashMap::new();
-        let _ = updater(
-            &mut sessions,
-            NpSessionEvent::Create(
-                7,
-                ManagerEventWrapper::SessionCreated {
-                    session_id: 7,
-                    source: "fooplayer".to_string(),
-                },
-            ),
-        );
-
-        let ev = NpSessionEvent::Update(7, SessionUpdateEventWrapper::Model(model("fooplayer")));
-        let (kind, delta) = updater(&mut sessions, ev);
-        assert_eq!(kind, "session_update");
-        let record = delta.expect("update should yield a record");
-        assert_eq!(record.session_id, 7);
-        // Source carried over from the create; a model update populates last_model_update.
-        assert_eq!(record.source.as_deref(), Some("fooplayer"));
-        assert!(record.last_model_update.is_some());
-        assert!(record.timestamp_updated.is_some());
-    }
-
-    #[test]
-    fn model_update_strips_album_art_from_emitted_record_but_keeps_it_stored() {
-        use crate::listener::ImageWrapper;
-        use std::sync::Arc;
-        let mut sessions = HashMap::new();
-        let _ = updater(
-            &mut sessions,
-            NpSessionEvent::Create(
-                7,
-                ManagerEventWrapper::SessionCreated {
-                    session_id: 7,
-                    source: "p".to_string(),
-                },
-            ),
-        );
-
-        // A media update lands cover art on the session — and DOES carry it to the bridge.
-        let media_ev = SessionUpdateEventWrapper::Media(
-            model("p"),
-            Some(Arc::new(ImageWrapper::new(
-                "image/png".to_string(),
-                vec![1, 2, 3, 4],
-            ))),
-        );
-        let (_, media_delta) = updater(&mut sessions, NpSessionEvent::Update(7, media_ev));
-        assert!(
-            media_delta.expect("media update yields a record").last_media_update.is_some(),
-            "a media update must ship its album art"
-        );
-
-        // A following model (play/pause/seek) update must NOT re-ship the art on the emitted record…
-        let (kind, model_delta) = updater(
-            &mut sessions,
-            NpSessionEvent::Update(7, SessionUpdateEventWrapper::Model(model("p"))),
-        );
-        assert_eq!(kind, "session_update");
-        assert!(
-            model_delta.expect("model update yields a record").last_media_update.is_none(),
-            "an emitted model/timeline update must not re-ship the (unchanged) album art"
-        );
-        // …but the STORED record keeps it, so get_initial_sessions / the frontend retain the cover.
-        assert!(
-            sessions.get(&7).unwrap().last_media_update.is_some(),
-            "the stored record must keep the art for later reads"
-        );
-    }
-
-    #[test]
-    fn delete_yields_session_delete_with_record_and_removes() {
-        let mut sessions = HashMap::new();
-        let _ = updater(
-            &mut sessions,
-            NpSessionEvent::Create(
-                7,
-                ManagerEventWrapper::SessionCreated {
-                    session_id: 7,
-                    source: "fooplayer".to_string(),
-                },
-            ),
-        );
-
-        let ev = NpSessionEvent::Delete(7, ManagerEventWrapper::SessionRemoved { session_id: 7 });
-        let (kind, delta) = updater(&mut sessions, ev);
-        assert_eq!(kind, "session_delete");
-        assert!(delta.is_some(), "deleting a tracked session returns its record");
-        // …and it is gone from the map afterwards.
-        assert!(!sessions.contains_key(&7));
-    }
-
-    #[test]
-    fn delete_unknown_session_yields_session_delete_without_record() {
-        let mut sessions = HashMap::new();
-        let ev = NpSessionEvent::Delete(42, ManagerEventWrapper::SessionRemoved { session_id: 42 });
-        let (kind, delta) = updater(&mut sessions, ev);
-        assert_eq!(kind, "session_delete");
-        assert!(delta.is_none());
-    }
-
-    #[test]
-    fn unsupported_event_yields_unsupported_without_record() {
-        let mut sessions = HashMap::new();
-        let ev = NpSessionEvent::Unsupported(Some(3), "CurrentSessionChanged".to_string());
-        let (kind, delta) = updater(&mut sessions, ev);
-        assert_eq!(kind, "unsupported");
-        assert!(delta.is_none());
-        // An unsupported event must not register a session.
-        assert!(sessions.is_empty());
-    }
-}
+use std::{collections::HashMap, time::SystemTime};
+
+use serde::Serialize;
+
+use crate::bridge::{SESSION_CREATE_EVENT, SESSION_DELETE_EVENT, SESSION_UPDATE_EVENT};
+use crate::{ManagerEventWrapper, SessionUpdateEventWrapper, event::NpSessionEvent, log};
+
+#[derive(Debug, Clone, Serialize)]
+pub struct SessionRecord {
+    pub session_id: usize,
+    pub source: Option<String>,
+    pub timestamp_created: Option<SystemTime>,
+    pub timestamp_updated: Option<SystemTime>,
+    pub last_media_update: Option<SessionUpdateEventWrapper>,
+    pub last_model_update: Option<SessionUpdateEventWrapper>,
+}
+
+pub fn updater(
+    sessions: &mut HashMap<usize, SessionRecord>,
+    event: NpSessionEvent,
+) -> (&str, Option<SessionRecord>) {
+    match event {
+        NpSessionEvent::Create(
+            _session_id_dupe,
+            ManagerEventWrapper::SessionCreated { session_id, source },
+        ) => {
+            let new_record = SessionRecord {
+                session_id,
+                source: Some(source),
+                timestamp_created: Some(SystemTime::now()),
+                timestamp_updated: None,
+                last_media_update: None,
+                last_model_update: None,
+            };
+            let _ = (*sessions).insert(session_id, new_record.clone());
+            (SESSION_CREATE_EVENT, Some(new_record))
+        }
+        NpSessionEvent::Create(_session_id_dupe, ev) => {
+            log::warn("session", "unexpected manager event for Create")
+                .field("event", format!("{ev:?}"))
+                .emit();
+            (SESSION_CREATE_EVENT, None)
+        }
+        NpSessionEvent::Update(session_id, ev) => {
+            // Model/timeline (play/pause/seek) updates carry NO new album art — capture that before `ev`
+            // is consumed so the emit below can strip the (unchanged) cover bytes rather than re-shipping
+            // hundreds of KB over the IPC bridge on every tick.
+            let is_model = matches!(ev, SessionUpdateEventWrapper::Model(_));
+            let maybe_existing = (*sessions).get(&session_id);
+            // TODO: create np-widget-specific models for sessions and map gsmtc to it
+
+            let updated_record = if let Some(existing) = maybe_existing {
+                let mut record_mut = SessionRecord {
+                    session_id: existing.session_id,
+                    source: existing.source.clone(),
+                    timestamp_created: existing.timestamp_created,
+                    timestamp_updated: Some(SystemTime::now()),
+                    // Check if this can be CoW?
+                    last_media_update: existing.last_media_update.clone(),
+                    last_model_update: existing.last_model_update.clone(),
+                };
+
+                match ev {
+                    SessionUpdateEventWrapper::Model(_) => {
+                        record_mut.last_model_update = Some(ev);
+                    }
+                    SessionUpdateEventWrapper::Media(_, _) => {
+                        record_mut.last_media_update = Some(ev);
+                    }
+                }
+
+                record_mut
+            } else {
+                let updated_ev: SessionUpdateEventWrapper = ev;
+                SessionRecord {
+                    session_id,
+                    source: None,
+                    timestamp_created: Some(SystemTime::now()),
+                    timestamp_updated: Some(SystemTime::now()),
+                    last_media_update: match updated_ev {
+                        SessionUpdateEventWrapper::Model(_) => None,
+                        // FIXME: awful clone here
+                        SessionUpdateEventWrapper::Media(_, _) => Some(updated_ev.clone()),
+                    },
+                    last_model_update: match updated_ev {
+                        SessionUpdateEventWrapper::Model(_) => Some(updated_ev),
+                        SessionUpdateEventWrapper::Media(_, _) => None,
+                    },
+                }
+            };
+
+            let _ = (*sessions).insert(session_id, updated_record.clone());
+            // The stored record (above) keeps the art; the EMITTED one drops it on a model/timeline
+            // update so we don't re-serialise + re-send the cover bytes to every webview each tick. The
+            // frontend carries the previous cover forward by session_id (see stores.ts mergeMediaForward).
+            // A media update keeps its art so a new cover still reaches the overlay.
+            let emitted = if is_model {
+                SessionRecord {
+                    last_media_update: None,
+                    ..updated_record
+                }
+            } else {
+                updated_record
+            };
+            (SESSION_UPDATE_EVENT, Some(emitted))
+        }
+        NpSessionEvent::Delete(session_id, _ev) => {
+            let maybe_deleted_record = (*sessions).remove(&session_id);
+
+            if let Some(deleted_record) = maybe_deleted_record {
+                (SESSION_DELETE_EVENT, Some(deleted_record))
+            } else {
+                (SESSION_DELETE_EVENT, None)
+            }
+        }
+        NpSessionEvent::Unsupported(session_id, label) => {
+            log::debug("gsmtc", "unsupported event")
+                .field("label", &label)
+                .field("session_id", format!("{session_id:?}"))
+                .emit();
+            ("unsupported", None)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use gsmtc::SessionModel;
+
+    /// A minimal `SessionModel` for building `SessionUpdateEventWrapper` events without any media
+    /// hardware. Only `source` is meaningful here; the rest are absent (None/empty).
+    fn model(source: &str) -> SessionModel {
+        SessionModel {
+            playback: None,
+            timeline: None,
+            media: None,
+            source: source.to_string(),
+        }
+    }
+
+    #[test]
+    fn create_yields_session_create_with_record_and_inserts() {
+        let mut sessions = HashMap::new();
+        let ev = NpSessionEvent::Create(
+            7,
+            ManagerEventWrapper::SessionCreated {
+                session_id: 7,
+                source: "fooplayer".to_string(),
+            },
+        );
+        let (kind, delta) = updater(&mut sessions, ev);
+        assert_eq!(kind, "session_create");
+        let record = delta.expect("create should yield a record");
+        assert_eq!(record.session_id, 7);
+        assert_eq!(record.source.as_deref(), Some("fooplayer"));
+        // The session is now tracked.
+        assert!(sessions.contains_key(&7));
+    }
+
+    #[test]
+    fn update_after_create_yields_session_update_and_keeps_source() {
+        let mut sessions = HashMap::new();
+        let _ = updater(
+            &mut sessions,
+            NpSessionEvent::Create(
+                7,
+                ManagerEventWrapper::SessionCreated {
+                    session_id: 7,
+                    source: "fooplayer".to_string(),
+                },
+            ),
+        );
+
+        let ev = NpSessionEvent::Update(7, SessionUpdateEventWrapper::Model(model("fooplayer")));
+        let (kind, delta) = updater(&mut sessions, ev);
+        assert_eq!(kind, "session_update");
+        let record = delta.expect("update should yield a record");
+        assert_eq!(record.session_id, 7);
+        // Source carried over from the create; a model update populates last_model_update.
+        assert_eq!(record.source.as_deref(), Some("fooplayer"));
+        assert!(record.last_model_update.is_some());
+        assert!(record.timestamp_updated.is_some());
+    }
+
+    #[test]
+    fn model_update_strips_album_art_from_emitted_record_but_keeps_it_stored() {
+        use crate::listener::ImageWrapper;
+        use std::sync::Arc;
+        let mut sessions = HashMap::new();
+        let _ = updater(
+            &mut sessions,
+            NpSessionEvent::Create(
+                7,
+                ManagerEventWrapper::SessionCreated {
+                    session_id: 7,
+                    source: "p".to_string(),
+                },
+            ),
+        );
+
+        // A media update lands cover art on the session — and DOES carry it to the bridge.
+        let media_ev = SessionUpdateEventWrapper::Media(
+            model("p"),
+            Some(Arc::new(ImageWrapper::new(
+                "image/png".to_string(),
+                vec![1, 2, 3, 4],
+            ))),
+        );
+        let (_, media_delta) = updater(&mut sessions, NpSessionEvent::Update(7, media_ev));
+        assert!(
+            media_delta
+                .expect("media update yields a record")
+                .last_media_update
+                .is_some(),
+            "a media update must ship its album art"
+        );
+
+        // A following model (play/pause/seek) update must NOT re-ship the art on the emitted record…
+        let (kind, model_delta) = updater(
+            &mut sessions,
+            NpSessionEvent::Update(7, SessionUpdateEventWrapper::Model(model("p"))),
+        );
+        assert_eq!(kind, "session_update");
+        assert!(
+            model_delta
+                .expect("model update yields a record")
+                .last_media_update
+                .is_none(),
+            "an emitted model/timeline update must not re-ship the (unchanged) album art"
+        );
+        // …but the STORED record keeps it, so get_initial_sessions / the frontend retain the cover.
+        assert!(
+            sessions.get(&7).unwrap().last_media_update.is_some(),
+            "the stored record must keep the art for later reads"
+        );
+    }
+
+    #[test]
+    fn delete_yields_session_delete_with_record_and_removes() {
+        let mut sessions = HashMap::new();
+        let _ = updater(
+            &mut sessions,
+            NpSessionEvent::Create(
+                7,
+                ManagerEventWrapper::SessionCreated {
+                    session_id: 7,
+                    source: "fooplayer".to_string(),
+                },
+            ),
+        );
+
+        let ev = NpSessionEvent::Delete(7, ManagerEventWrapper::SessionRemoved { session_id: 7 });
+        let (kind, delta) = updater(&mut sessions, ev);
+        assert_eq!(kind, "session_delete");
+        assert!(
+            delta.is_some(),
+            "deleting a tracked session returns its record"
+        );
+        // …and it is gone from the map afterwards.
+        assert!(!sessions.contains_key(&7));
+    }
+
+    #[test]
+    fn delete_unknown_session_yields_session_delete_without_record() {
+        let mut sessions = HashMap::new();
+        let ev = NpSessionEvent::Delete(42, ManagerEventWrapper::SessionRemoved { session_id: 42 });
+        let (kind, delta) = updater(&mut sessions, ev);
+        assert_eq!(kind, "session_delete");
+        assert!(delta.is_none());
+    }
+
+    #[test]
+    fn unsupported_event_yields_unsupported_without_record() {
+        let mut sessions = HashMap::new();
+        let ev = NpSessionEvent::Unsupported(Some(3), "CurrentSessionChanged".to_string());
+        let (kind, delta) = updater(&mut sessions, ev);
+        assert_eq!(kind, "unsupported");
+        assert!(delta.is_none());
+        // An unsupported event must not register a session.
+        assert!(sessions.is_empty());
+    }
+}
diff --git a/widgetsack/src/stocks.rs b/widgetsack/src/stocks.rs
index 1cfa3f3..66f02d4 100644
--- a/widgetsack/src/stocks.rs
+++ b/widgetsack/src/stocks.rs
@@ -84,7 +84,9 @@ fn stocks_config_path<R: Runtime>(app: &AppHandle<R>) -> Result<PathBuf, String>
 pub fn load_stocks_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<StocksConfig>, String> {
     let path = stocks_config_path(app)?;
     match std::fs::read_to_string(&path) {
-        Ok(txt) => serde_json::from_str(&txt).map(Some).map_err(|e| e.to_string()),
+        Ok(txt) => serde_json::from_str(&txt)
+            .map(Some)
+            .map_err(|e| e.to_string()),
         Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
         Err(err) => Err(err.to_string()),
     }
@@ -96,7 +98,9 @@ pub fn load_stocks_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<Stock
 /// `^GSPC`) is percent-encoded; plain tickers and `BTC-USD` need no encoding.
 fn yahoo_chart_url(symbol: &str, interval: &str, range: &str) -> String {
     let enc = symbol.trim().to_uppercase().replace('^', "%5E");
-    format!("https://query1.finance.yahoo.com/v8/finance/chart/{enc}?range={range}&interval={interval}")
+    format!(
+        "https://query1.finance.yahoo.com/v8/finance/chart/{enc}?range={range}&interval={interval}"
+    )
 }
 
 /// Percent change of `price` vs `prev_close`, or `None` when prev is missing / zero (avoids a /0 and a
@@ -144,7 +148,11 @@ fn quote_to_samples(symbol: &str, chart: &Value, ts_ms: u64) -> Vec<SensorSample
             if let Some(pct) = change_pct(p, pc) {
                 out.push(SensorSample::scalar(format!("{base}.change"), ts_ms, pct));
             }
-            out.push(SensorSample::scalar(format!("{base}.changeAbs"), ts_ms, p - pc));
+            out.push(SensorSample::scalar(
+                format!("{base}.changeAbs"),
+                ts_ms,
+                p - pc,
+            ));
         }
     }
     if let Some(pc) = prev {
@@ -178,7 +186,13 @@ fn quote_to_samples(symbol: &str, chart: &Value, ts_ms: u64) -> Vec<SensorSample
 /// `client/src/lib/widgets/plugins/stocks-source.ts`. Used to tell a real `stocks.<SYM>.<field>` id
 /// apart from the `stocks.status` sentinel when reverse-deriving which symbols are in demand.
 const SYMBOL_FIELDS: &[&str] = &[
-    "price", "change", "changeAbs", "prevClose", "currency", "state", "series",
+    "price",
+    "change",
+    "changeAbs",
+    "prevClose",
+    "currency",
+    "state",
+    "series",
 ];
 
 /// Reverse-derive the uppercased stock symbols implied by a set of active sensor ids. An id shaped
@@ -248,7 +262,12 @@ fn stocks_wanted<R: Runtime>(app: &AppHandle<R>) -> bool {
 fn active_stock_symbols<R: Runtime>(app: &AppHandle<R>) -> Vec<String> {
     let active: State<ActiveSensors> = app.state();
     let guard = active.0.lock().unwrap_or_else(|e| e.into_inner());
-    symbols_from_active(guard.values().flat_map(|set| set.iter()).map(String::as_str))
+    symbols_from_active(
+        guard
+            .values()
+            .flat_map(|set| set.iter())
+            .map(String::as_str),
+    )
 }
 
 // ---- connection / poll task ----
@@ -302,7 +321,10 @@ pub async fn run_stocks_client<R: Runtime>(app: AppHandle<R>, cfg: StocksConfig)
         .filter(|s| !s.is_empty())
         .collect();
     if cfg.provider != "yahoo" {
-        eprintln!("stocks: provider '{}' is not implemented; using yahoo", cfg.provider);
+        eprintln!(
+            "stocks: provider '{}' is not implemented; using yahoo",
+            cfg.provider
+        );
     }
 
     // `idle` re-emits a fresh "connecting" when a ticker (re)mounts after an idle gap; `fails` drives
@@ -503,15 +525,16 @@ mod tests {
         assert_eq!(pv["value"]["value"], 110.0);
 
         let change = find(&s, "stocks.AAPL.change").unwrap();
-        assert_eq!(serde_json::to_value(change).unwrap()["value"]["value"], 10.0);
         assert_eq!(
-            serde_json::to_value(find(&s, "stocks.AAPL.changeAbs").unwrap()).unwrap()["value"]
-                ["value"],
+            serde_json::to_value(change).unwrap()["value"]["value"],
+            10.0
+        );
+        assert_eq!(
+            serde_json::to_value(find(&s, "stocks.AAPL.changeAbs").unwrap()).unwrap()["value"]["value"],
             10.0
         );
         assert_eq!(
-            serde_json::to_value(find(&s, "stocks.AAPL.currency").unwrap()).unwrap()["value"]
-                ["value"],
+            serde_json::to_value(find(&s, "stocks.AAPL.currency").unwrap()).unwrap()["value"]["value"],
             "USD"
         );
         assert_eq!(
@@ -548,7 +571,7 @@ mod tests {
     fn symbols_from_active_extracts_symbols_and_skips_sentinels() {
         let ids = [
             "stocks.NVDA.price",
-            "stocks.NVDA.change",   // duplicate symbol — deduped
+            "stocks.NVDA.change", // duplicate symbol — deduped
             "stocks.AAPL.series",
             "stocks.status",        // status sentinel: not a symbol
             "*",                    // studio wildcard: not a symbol
diff --git a/widgetsack/src/timings.rs b/widgetsack/src/timings.rs
index 00bb3a7..b00cee6 100644
--- a/widgetsack/src/timings.rs
+++ b/widgetsack/src/timings.rs
@@ -8,8 +8,8 @@
 //! imposes — e.g. a 5 ms process refresh at 1 Hz = 5 ms/s ≈ 0.5% of one core.
 
 use std::collections::HashMap;
-use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::Mutex;
+use std::sync::atomic::{AtomicBool, Ordering};
 use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 
 use serde::Serialize;
diff --git a/widgetsack/src/weather.rs b/widgetsack/src/weather.rs
index c6dd6db..1ec62a5 100644
--- a/widgetsack/src/weather.rs
+++ b/widgetsack/src/weather.rs
@@ -79,10 +79,14 @@ fn weather_config_path<R: Runtime>(app: &AppHandle<R>) -> Result<PathBuf, String
     Ok(dir.join("plugins").join("weather.json"))
 }
 
-pub fn load_weather_config<R: Runtime>(app: &AppHandle<R>) -> Result<Option<WeatherConfig>, String> {
+pub fn load_weather_config<R: Runtime>(
+    app: &AppHandle<R>,
+) -> Result<Option<WeatherConfig>, String> {
     let path = weather_config_path(app)?;
     match std::fs::read_to_string(&path) {
-        Ok(txt) => serde_json::from_str(&txt).map(Some).map_err(|e| e.to_string()),
+        Ok(txt) => serde_json::from_str(&txt)
+            .map(Some)
+            .map_err(|e| e.to_string()),
         Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(None),
         Err(err) => Err(err.to_string()),
     }
@@ -160,8 +164,14 @@ fn weather_to_samples(body: &Value, unit_letter: &str, ts_ms: u64) -> Vec<Sensor
     scalar("weather.uv", cur["uv_index"].as_f64());
     scalar("weather.code", cur["weather_code"].as_f64());
     scalar("weather.is_day", cur["is_day"].as_f64());
-    scalar("weather.high", body["daily"]["temperature_2m_max"][0].as_f64());
-    scalar("weather.low", body["daily"]["temperature_2m_min"][0].as_f64());
+    scalar(
+        "weather.high",
+        body["daily"]["temperature_2m_max"][0].as_f64(),
+    );
+    scalar(
+        "weather.low",
+        body["daily"]["temperature_2m_min"][0].as_f64(),
+    );
     // Multi-day forecast: weather.day.N.{high,low,code} for each day Open-Meteo returned (day 0 = today,
     // duplicating weather.high/low which are kept for back-compat). A short array just yields fewer days.
     let highs = body["daily"]["temperature_2m_max"].as_array();
@@ -323,7 +333,11 @@ pub async fn save_weather_config(
     let cfg = WeatherConfig {
         latitude,
         longitude,
-        unit: if unit.is_empty() { default_unit() } else { unit },
+        unit: if unit.is_empty() {
+            default_unit()
+        } else {
+            unit
+        },
         poll_interval_secs: poll_seconds.clamp(MIN_INTERVAL, MAX_INTERVAL),
     };
     let txt = serde_json::to_string_pretty(&cfg).map_err(|e| e.to_string())?;
@@ -453,7 +467,9 @@ mod tests {
     #[test]
     fn body_maps_to_current_plus_highlow_plus_unit() {
         let s = weather_to_samples(&sample_body(), "C", 7);
-        let v = |id: &str| serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone();
+        let v = |id: &str| {
+            serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone()
+        };
         assert_eq!(v("weather.temp"), 12.3);
         assert_eq!(v("weather.humidity"), 80.0);
         assert_eq!(v("weather.apparent"), 10.1);
@@ -469,7 +485,9 @@ mod tests {
     #[test]
     fn daily_arrays_become_per_day_forecast_samples() {
         let s = weather_to_samples(&sample_body(), "C", 0);
-        let v = |id: &str| serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone();
+        let v = |id: &str| {
+            serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone()
+        };
         // Day 0 mirrors today's high/low and carries the code.
         assert_eq!(v("weather.day.0.high"), 15.0);
         assert_eq!(v("weather.day.0.low"), 8.0);
@@ -489,9 +507,12 @@ mod tests {
         assert!(u.contains("european_aqi"));
         assert!(u.contains("latitude=51.5"));
 
-        let body = json!({ "current": { "european_aqi": 34, "us_aqi": 51, "pm2_5": 8.2, "pm10": 14.0 } });
+        let body =
+            json!({ "current": { "european_aqi": 34, "us_aqi": 51, "pm2_5": 8.2, "pm10": 14.0 } });
         let s = air_to_samples(&body, 9);
-        let v = |id: &str| serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone();
+        let v = |id: &str| {
+            serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone()
+        };
         assert_eq!(v("weather.air.aqi"), 34.0);
         assert_eq!(v("weather.air.us_aqi"), 51.0);
         assert_eq!(v("weather.air.pm25"), 8.2);
@@ -503,7 +524,9 @@ mod tests {
     #[test]
     fn sunrise_and_sunset_ride_along_as_text() {
         let s = weather_to_samples(&sample_body(), "C", 0);
-        let v = |id: &str| serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone();
+        let v = |id: &str| {
+            serde_json::to_value(find(&s, id).unwrap()).unwrap()["value"]["value"].clone()
+        };
         assert_eq!(v("weather.sun.rise"), "2026-06-14T05:12");
         assert_eq!(v("weather.sun.set"), "2026-06-14T21:30");
     }
@@ -544,7 +567,8 @@ mod tests {
 
     #[test]
     fn config_defaults_keep_a_minimal_json_valid() {
-        let cfg: WeatherConfig = serde_json::from_str(r#"{ "latitude": 51.5, "longitude": -0.1 }"#).unwrap();
+        let cfg: WeatherConfig =
+            serde_json::from_str(r#"{ "latitude": 51.5, "longitude": -0.1 }"#).unwrap();
         assert_eq!(cfg.unit, "celsius");
         assert_eq!(cfg.poll_interval_secs, 900);
     }
diff --git a/widgetsack/src/wifi.rs b/widgetsack/src/wifi.rs
index 47e37d7..c025201 100644
--- a/widgetsack/src/wifi.rs
+++ b/widgetsack/src/wifi.rs
@@ -71,13 +71,33 @@ pub fn wifi_samples_from(info: &WifiInfo, ts: u64) -> Vec<SensorSample> {
     if !info.ssid.is_empty() {
         out.push(SensorSample::text("net.wifi.ssid", ts, info.ssid.clone()));
     }
-    out.push(SensorSample::scalar("net.wifi.signal", ts, f64::from(info.quality.min(100))));
-    out.push(SensorSample::scalar("net.wifi.rssi", ts, f64::from(rssi_from_quality(info.quality))));
+    out.push(SensorSample::scalar(
+        "net.wifi.signal",
+        ts,
+        f64::from(info.quality.min(100)),
+    ));
+    out.push(SensorSample::scalar(
+        "net.wifi.rssi",
+        ts,
+        f64::from(rssi_from_quality(info.quality)),
+    ));
     // kbps → Mbps for display (Wi-Fi link rates read in Mbps).
-    out.push(SensorSample::scalar("net.wifi.rx", ts, f64::from(info.rx_kbps) / 1000.0));
-    out.push(SensorSample::scalar("net.wifi.tx", ts, f64::from(info.tx_kbps) / 1000.0));
+    out.push(SensorSample::scalar(
+        "net.wifi.rx",
+        ts,
+        f64::from(info.rx_kbps) / 1000.0,
+    ));
+    out.push(SensorSample::scalar(
+        "net.wifi.tx",
+        ts,
+        f64::from(info.tx_kbps) / 1000.0,
+    ));
     if info.channel > 0 {
-        out.push(SensorSample::scalar("net.wifi.channel", ts, f64::from(info.channel)));
+        out.push(SensorSample::scalar(
+            "net.wifi.channel",
+            ts,
+            f64::from(info.channel),
+        ));
         let band = band_from_channel(info.channel);
         if !band.is_empty() {
             out.push(SensorSample::text("net.wifi.band", ts, band));
@@ -97,9 +117,9 @@ fn read_wifi() -> Option<WifiInfo> {
     use std::ptr::null_mut;
     use windows::Win32::Foundation::HANDLE;
     use windows::Win32::NetworkManagement::WiFi::{
+        WLAN_CONNECTION_ATTRIBUTES, WLAN_INTERFACE_INFO_LIST, WlanCloseHandle, WlanEnumInterfaces,
+        WlanFreeMemory, WlanOpenHandle, WlanQueryInterface, wlan_interface_state_connected,
         wlan_intf_opcode_channel_number, wlan_intf_opcode_current_connection,
-        wlan_interface_state_connected, WlanCloseHandle, WlanEnumInterfaces, WlanFreeMemory,
-        WlanOpenHandle, WlanQueryInterface, WLAN_CONNECTION_ATTRIBUTES, WLAN_INTERFACE_INFO_LIST,
     };
 
     const WLAN_API_VERSION_2_0: u32 = 2;
@@ -116,8 +136,10 @@ fn read_wifi() -> Option<WifiInfo> {
         // SAFETY: fills `list_ptr` with a WlanFreeMemory-owned interface list.
         let info = if WlanEnumInterfaces(handle, None, &mut list_ptr) == 0 && !list_ptr.is_null() {
             let list = &*list_ptr;
-            let ifaces =
-                std::slice::from_raw_parts(list.InterfaceInfo.as_ptr(), list.dwNumberOfItems as usize);
+            let ifaces = std::slice::from_raw_parts(
+                list.InterfaceInfo.as_ptr(),
+                list.dwNumberOfItems as usize,
+            );
             let mut found = None;
             for iface in ifaces {
                 if iface.isState != wlan_interface_state_connected {
@@ -139,7 +161,8 @@ fn read_wifi() -> Option<WifiInfo> {
                 {
                     let conn = &*(data as *const WLAN_CONNECTION_ATTRIBUTES);
                     let assoc = &conn.wlanAssociationAttributes;
-                    let len = (assoc.dot11Ssid.uSSIDLength as usize).min(assoc.dot11Ssid.ucSSID.len());
+                    let len =
+                        (assoc.dot11Ssid.uSSIDLength as usize).min(assoc.dot11Ssid.ucSSID.len());
                     let mut wifi = WifiInfo {
                         ssid: ssid_to_string(&assoc.dot11Ssid.ucSSID[..len]),
                         quality: assoc.wlanSignalQuality,
diff --git a/widgetsack/src/windowmgr.rs b/widgetsack/src/windowmgr.rs
index 8f0494b..5ebe0ba 100644
--- a/widgetsack/src/windowmgr.rs
+++ b/widgetsack/src/windowmgr.rs
@@ -66,7 +66,13 @@ const MAX_DWM_BORDER: f64 = 24.0;
 /// (negative — classic theme / DWM off / no frame; or implausibly large — a bad read) clamp to 0.
 /// Twin of `frameMargins` in core/snapMath.ts.
 fn frame_margins(window: ScreenRect, frame: Option<ScreenRect>) -> (f64, f64, f64) {
-    let clamp = |m: f64| if (0.0..=MAX_DWM_BORDER).contains(&m) { m } else { 0.0 };
+    let clamp = |m: f64| {
+        if (0.0..=MAX_DWM_BORDER).contains(&m) {
+            m
+        } else {
+            0.0
+        }
+    };
     match frame {
         None => (0.0, 0.0, 0.0),
         Some(f) => {
@@ -262,8 +268,15 @@ pub struct PointerState {
 /// (not the studio) polls it during a drag.
 #[tauri::command]
 pub fn pointer_probe(app: tauri::AppHandle) -> PointerState {
-    let (x, y) = app.cursor_position().map(|p| (p.x, p.y)).unwrap_or((0.0, 0.0));
-    PointerState { x, y, shift: shift_held() }
+    let (x, y) = app
+        .cursor_position()
+        .map(|p| (p.x, p.y))
+        .unwrap_or((0.0, 0.0));
+    PointerState {
+        x,
+        y,
+        shift: shift_held(),
+    }
 }
 
 /// Payload for `win_drag_start` / `win_drag_end`.
@@ -308,8 +321,8 @@ fn spawn_drag_pump() {
     std::thread::spawn(|| unsafe {
         use windows::Win32::UI::Accessibility::SetWinEventHook;
         use windows::Win32::UI::WindowsAndMessaging::{
-            DispatchMessageW, GetMessageW, EVENT_OBJECT_LOCATIONCHANGE, EVENT_SYSTEM_MOVESIZEEND,
-            EVENT_SYSTEM_MOVESIZESTART, MSG, WINEVENT_OUTOFCONTEXT, WM_TIMER,
+            DispatchMessageW, EVENT_OBJECT_LOCATIONCHANGE, EVENT_SYSTEM_MOVESIZEEND,
+            EVENT_SYSTEM_MOVESIZESTART, GetMessageW, MSG, WINEVENT_OUTOFCONTEXT, WM_TIMER,
         };
         // Hook 1: the standard modal move/size loop (classic titlebars) → real drags.
         let move_hook = SetWinEventHook(
@@ -380,10 +393,11 @@ fn arrangeable_hwnd(hwnd: windows::Win32::Foundation::HWND) -> bool {
     use std::ffi::c_void;
     use std::mem::size_of;
     use windows::Win32::Foundation::RECT;
-    use windows::Win32::Graphics::Dwm::{DwmGetWindowAttribute, DWMWA_CLOAKED};
+    use windows::Win32::Graphics::Dwm::{DWMWA_CLOAKED, DwmGetWindowAttribute};
     use windows::Win32::UI::WindowsAndMessaging::{
-        GetWindow, GetWindowLongW, GetWindowRect, GetWindowTextLengthW, GetWindowThreadProcessId,
-        IsWindowVisible, GWL_EXSTYLE, GWL_STYLE, GW_OWNER, WS_CHILD, WS_EX_TOOLWINDOW,
+        GW_OWNER, GWL_EXSTYLE, GWL_STYLE, GetWindow, GetWindowLongW, GetWindowRect,
+        GetWindowTextLengthW, GetWindowThreadProcessId, IsWindowVisible, WS_CHILD,
+        WS_EX_TOOLWINDOW,
     };
     unsafe {
         let ex_style = GetWindowLongW(hwnd, GWL_EXSTYLE) as u32;
@@ -488,11 +502,14 @@ static SNAPPED: std::sync::LazyLock<std::sync::Mutex<std::collections::HashMap<i
 unsafe fn restore_on_drag_out(hwnd: windows::Win32::Foundation::HWND) {
     use windows::Win32::Foundation::{POINT, RECT};
     use windows::Win32::UI::WindowsAndMessaging::{
-        GetCursorPos, GetWindowRect, SetWindowPos, SWP_NOACTIVATE, SWP_NOZORDER,
+        GetCursorPos, GetWindowRect, SWP_NOACTIVATE, SWP_NOZORDER, SetWindowPos,
     };
 
     let id = hwnd.0 as isize as i64;
-    let size = SNAPPED.lock().unwrap_or_else(|e| e.into_inner()).remove(&id);
+    let size = SNAPPED
+        .lock()
+        .unwrap_or_else(|e| e.into_inner())
+        .remove(&id);
     let Some((rw, rh)) = size else { return };
     if rw <= 0 || rh <= 0 {
         return;
@@ -513,8 +530,17 @@ unsafe fn restore_on_drag_out(hwnd: windows::Win32::Foundation::HWND) {
         h: (rc.bottom - rc.top) as f64,
     };
     let (nx, ny) = restore_top_left(snapped, (cur.x as f64, cur.y as f64), rw as f64, rh as f64);
-    let _ =
-        unsafe { SetWindowPos(hwnd, None, nx as i32, ny as i32, rw, rh, SWP_NOACTIVATE | SWP_NOZORDER) };
+    let _ = unsafe {
+        SetWindowPos(
+            hwnd,
+            None,
+            nx as i32,
+            ny as i32,
+            rw,
+            rh,
+            SWP_NOACTIVATE | SWP_NOZORDER,
+        )
+    };
 }
 
 #[cfg(target_os = "windows")]
@@ -528,7 +554,8 @@ unsafe extern "system" fn win_event_proc(
     _time: u32,
 ) {
     use windows::Win32::UI::WindowsAndMessaging::{
-        EVENT_OBJECT_LOCATIONCHANGE, EVENT_SYSTEM_MOVESIZEEND, EVENT_SYSTEM_MOVESIZESTART, OBJID_WINDOW,
+        EVENT_OBJECT_LOCATIONCHANGE, EVENT_SYSTEM_MOVESIZEEND, EVENT_SYSTEM_MOVESIZESTART,
+        OBJID_WINDOW,
     };
     // Only the window itself (OBJID_WINDOW), not its caret/cursor/child accessible objects — the
     // LOCATIONCHANGE stream is otherwise very noisy.
@@ -560,14 +587,14 @@ unsafe extern "system" fn win_event_proc(
 fn list_arrangeable() -> Result<Vec<WindowDescriptor>, String> {
     use std::ffi::c_void;
     use std::mem::size_of;
-    use windows::core::BOOL;
     use windows::Win32::Foundation::{HWND, LPARAM, RECT};
-    use windows::Win32::Graphics::Dwm::{DwmGetWindowAttribute, DWMWA_CLOAKED};
+    use windows::Win32::Graphics::Dwm::{DWMWA_CLOAKED, DwmGetWindowAttribute};
     use windows::Win32::UI::WindowsAndMessaging::{
-        EnumWindows, GetClassNameW, GetWindow, GetWindowLongW, GetWindowRect, GetWindowTextW,
-        GetWindowThreadProcessId, IsWindowVisible, GWL_EXSTYLE, GWL_STYLE, GW_OWNER,
-        WS_CHILD, WS_EX_TOOLWINDOW,
+        EnumWindows, GW_OWNER, GWL_EXSTYLE, GWL_STYLE, GetClassNameW, GetWindow, GetWindowLongW,
+        GetWindowRect, GetWindowTextW, GetWindowThreadProcessId, IsWindowVisible, WS_CHILD,
+        WS_EX_TOOLWINDOW,
     };
+    use windows::core::BOOL;
 
     // Collect raw HWNDs first (do nothing heavy inside the enum callback). The body is push-only and
     // cannot panic, so no `catch_unwind` is needed across the `extern "system"` FFI boundary.
@@ -662,12 +689,12 @@ fn list_arrangeable() -> Result<Vec<WindowDescriptor>, String> {
 /// protected processes — those return None and matching falls back to class/title.
 #[cfg(target_os = "windows")]
 fn exe_path(pid: u32) -> Option<String> {
-    use windows::core::PWSTR;
     use windows::Win32::Foundation::CloseHandle;
     use windows::Win32::System::Threading::{
-        OpenProcess, QueryFullProcessImageNameW, PROCESS_NAME_WIN32,
-        PROCESS_QUERY_LIMITED_INFORMATION,
+        OpenProcess, PROCESS_NAME_WIN32, PROCESS_QUERY_LIMITED_INFORMATION,
+        QueryFullProcessImageNameW,
     };
+    use windows::core::PWSTR;
 
     unsafe {
         let handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid).ok()?;
@@ -692,10 +719,10 @@ fn snap(hwnd: i64, zone: ScreenRect) -> Result<(), String> {
     use std::thread::sleep;
     use std::time::Duration;
     use windows::Win32::Foundation::{HWND, RECT};
-    use windows::Win32::Graphics::Dwm::{DwmGetWindowAttribute, DWMWA_EXTENDED_FRAME_BOUNDS};
+    use windows::Win32::Graphics::Dwm::{DWMWA_EXTENDED_FRAME_BOUNDS, DwmGetWindowAttribute};
     use windows::Win32::UI::WindowsAndMessaging::{
-        GetWindowRect, IsIconic, IsZoomed, SetWindowPos, ShowWindow, SWP_NOACTIVATE, SWP_NOZORDER,
-        SW_RESTORE,
+        GetWindowRect, IsIconic, IsZoomed, SW_RESTORE, SWP_NOACTIVATE, SWP_NOZORDER, SetWindowPos,
+        ShowWindow,
     };
 
     let hwnd_id = hwnd;
@@ -708,7 +735,7 @@ fn snap(hwnd: i64, zone: ScreenRect) -> Result<(), String> {
         (Some(x), Some(y)) => {
             x.left == y.left && x.top == y.top && x.right == y.right && x.bottom == y.bottom
         }
-        _ => false
+        _ => false,
     };
     unsafe {
         // A maximized/minimized window ignores SetWindowPos (it snaps back), so restore it first —
@@ -796,20 +823,39 @@ mod tests {
 
     #[test]
     fn is_arrangeable_requires_visible_titled_real_unowned_window() {
-        assert!(is_arrangeable(true, false, false, true, 800, 600, false, false));
-        assert!(!is_arrangeable(false, false, false, true, 800, 600, false, false)); // hidden
-        assert!(!is_arrangeable(true, true, false, true, 800, 600, false, false)); // tool window
-        assert!(!is_arrangeable(true, false, true, true, 800, 600, false, false)); // cloaked
-        assert!(!is_arrangeable(true, false, false, false, 800, 600, false, false)); // no title
-        assert!(!is_arrangeable(true, false, false, true, 0, 600, false, false)); // zero width
-        assert!(!is_arrangeable(true, false, false, true, 800, 600, true, false)); // our own window
-        assert!(!is_arrangeable(true, false, false, true, 800, 600, false, true)); // owned/child popup
+        assert!(is_arrangeable(
+            true, false, false, true, 800, 600, false, false
+        ));
+        assert!(!is_arrangeable(
+            false, false, false, true, 800, 600, false, false
+        )); // hidden
+        assert!(!is_arrangeable(
+            true, true, false, true, 800, 600, false, false
+        )); // tool window
+        assert!(!is_arrangeable(
+            true, false, true, true, 800, 600, false, false
+        )); // cloaked
+        assert!(!is_arrangeable(
+            true, false, false, false, 800, 600, false, false
+        )); // no title
+        assert!(!is_arrangeable(
+            true, false, false, true, 0, 600, false, false
+        )); // zero width
+        assert!(!is_arrangeable(
+            true, false, false, true, 800, 600, true, false
+        )); // our own window
+        assert!(!is_arrangeable(
+            true, false, false, true, 800, 600, false, true
+        )); // owned/child popup
     }
 
     #[test]
     fn adjust_returns_zone_unchanged_without_a_frame() {
         let zone = rect(100.0, 200.0, 800.0, 600.0);
-        assert_eq!(adjust_for_frame_bounds(zone, rect(0.0, 0.0, 800.0, 600.0), None), zone);
+        assert_eq!(
+            adjust_for_frame_bounds(zone, rect(0.0, 0.0, 800.0, 600.0), None),
+            zone
+        );
     }
 
     #[test]
@@ -818,7 +864,10 @@ mod tests {
         let zone = rect(100.0, 200.0, 800.0, 600.0);
         let window = rect(0.0, 0.0, 814.0, 607.0);
         let frame = Some(rect(7.0, 0.0, 800.0, 600.0));
-        assert_eq!(adjust_for_frame_bounds(zone, window, frame), rect(93.0, 200.0, 814.0, 607.0));
+        assert_eq!(
+            adjust_for_frame_bounds(zone, window, frame),
+            rect(93.0, 200.0, 814.0, 607.0)
+        );
     }
 
     #[test]
@@ -841,7 +890,10 @@ mod tests {
 
     #[test]
     fn exe_basename_lowercases_and_strips_dir() {
-        assert_eq!(exe_basename("C:\\Program Files\\Spotify\\Spotify.exe"), "spotify.exe");
+        assert_eq!(
+            exe_basename("C:\\Program Files\\Spotify\\Spotify.exe"),
+            "spotify.exe"
+        );
         assert_eq!(exe_basename("/usr/bin/Foo"), "foo");
         assert_eq!(exe_basename("Code.exe"), "code.exe");
     }
@@ -918,13 +970,21 @@ mod tests {
             exe: "C:\\X\\app.exe".to_string(),
             class_name: "Chrome_WidgetWin_1".to_string(),
             title: "Title".to_string(),
-            rect: ScreenRect { x: 1.0, y: 2.0, w: 3.0, h: 4.0 },
+            rect: ScreenRect {
+                x: 1.0,
+                y: 2.0,
+                w: 3.0,
+                h: 4.0,
+            },
         };
         let json = serde_json::to_value(&d).unwrap();
         assert_eq!(json["hwnd"], 123);
         assert_eq!(json["exe"], "C:\\X\\app.exe");
         assert_eq!(json["className"], "Chrome_WidgetWin_1"); // camelCase, NOT class_name
-        assert!(json.get("class_name").is_none(), "snake_case class_name must not leak to the bridge");
+        assert!(
+            json.get("class_name").is_none(),
+            "snake_case class_name must not leak to the bridge"
+        );
         assert_eq!(json["title"], "Title");
         assert_eq!(json["rect"]["x"], 1.0);
         assert_eq!(json["rect"]["w"], 3.0);
@@ -933,7 +993,12 @@ mod tests {
     #[test]
     fn pointer_state_serializes_to_the_ts_bridge_shape() {
         // Mirrors `Pointer` in core/dragSnap.ts ({ x, y, shift }) — the overlay's drag poll reads these.
-        let json = serde_json::to_value(PointerState { x: 10.0, y: 20.0, shift: true }).unwrap();
+        let json = serde_json::to_value(PointerState {
+            x: 10.0,
+            y: 20.0,
+            shift: true,
+        })
+        .unwrap();
         assert_eq!(json["x"], 10.0);
         assert_eq!(json["y"], 20.0);
         assert_eq!(json["shift"], true);
@@ -960,7 +1025,10 @@ mod manual_smoke {
     }
 
     fn rect_of(hwnd: i64) -> Option<ScreenRect> {
-        arrangeable().into_iter().find(|w| w.hwnd == hwnd).map(|w| w.rect)
+        arrangeable()
+            .into_iter()
+            .find(|w| w.hwnd == hwnd)
+            .map(|w| w.rect)
     }
 
     fn close_window(hwnd: i64) {
@@ -975,7 +1043,9 @@ mod manual_smoke {
     #[ignore = "spawns + moves a real Notepad window; run explicitly with --ignored"]
     fn snap_moves_a_real_window() {
         let before: HashSet<i64> = arrangeable().into_iter().map(|w| w.hwnd).collect();
-        let mut child = Command::new("notepad.exe").spawn().expect("failed to spawn notepad.exe");
+        let mut child = Command::new("notepad.exe")
+            .spawn()
+            .expect("failed to spawn notepad.exe");
 
         // Wait for a NEW arrangeable window (ours) — prefer one whose exe is notepad.exe.
         let deadline = Instant::now() + Duration::from_secs(5);
@@ -993,13 +1063,18 @@ mod manual_smoke {
             Some(h) => h,
             None => {
                 let _ = child.kill();
-        let _ = child.wait(); // reap the process so clippy's zombie_processes lint is satisfied
+                let _ = child.wait(); // reap the process so clippy's zombie_processes lint is satisfied
                 panic!("no new window appeared within 5s — did Notepad open?");
             }
         };
 
         let start = rect_of(hwnd);
-        let target = ScreenRect { x: 200.0, y: 200.0, w: 800.0, h: 600.0 };
+        let target = ScreenRect {
+            x: 200.0,
+            y: 200.0,
+            w: 800.0,
+            h: 600.0,
+        };
         let snapped = snap(hwnd, target);
         sleep(Duration::from_millis(250));
         let end = rect_of(hwnd);
@@ -1017,17 +1092,32 @@ mod manual_smoke {
         snapped.expect("snap returned Err");
         let end = end.expect("could not read the window rect after snapping");
         // The VISIBLE frame fills ~the target; the window rect sits within a small DWM border of it.
-        assert!((end.x - target.x).abs() < 16.0, "x off target: {} vs {}", end.x, target.x);
-        assert!((end.y - target.y).abs() < 16.0, "y off target: {} vs {}", end.y, target.y);
-        assert!((end.w - target.w).abs() < 32.0, "w off target: {} vs {}", end.w, target.w);
+        assert!(
+            (end.x - target.x).abs() < 16.0,
+            "x off target: {} vs {}",
+            end.x,
+            target.x
+        );
+        assert!(
+            (end.y - target.y).abs() < 16.0,
+            "y off target: {} vs {}",
+            end.y,
+            target.y
+        );
+        assert!(
+            (end.w - target.w).abs() < 32.0,
+            "w off target: {} vs {}",
+            end.w,
+            target.w
+        );
     }
 
     /// Synthesize the left mouse button down/up (so `GetAsyncKeyState(VK_LBUTTON)` — the synthetic-drag
     /// arming gate — reads it). Injected at the current cursor position.
     fn send_lmb(down: bool) {
         use windows::Win32::UI::Input::KeyboardAndMouse::{
-            SendInput, INPUT, INPUT_0, INPUT_MOUSE, MOUSEEVENTF_LEFTDOWN, MOUSEEVENTF_LEFTUP,
-            MOUSEINPUT,
+            INPUT, INPUT_0, INPUT_MOUSE, MOUSEEVENTF_LEFTDOWN, MOUSEEVENTF_LEFTUP, MOUSEINPUT,
+            SendInput,
         };
         let input = INPUT {
             r#type: INPUT_MOUSE,
@@ -1036,7 +1126,11 @@ mod manual_smoke {
                     dx: 0,
                     dy: 0,
                     mouseData: 0,
-                    dwFlags: if down { MOUSEEVENTF_LEFTDOWN } else { MOUSEEVENTF_LEFTUP },
+                    dwFlags: if down {
+                        MOUSEEVENTF_LEFTDOWN
+                    } else {
+                        MOUSEEVENTF_LEFTUP
+                    },
                     time: 0,
                     dwExtraInfo: 0,
                 },
@@ -1061,7 +1155,7 @@ mod manual_smoke {
         use std::sync::mpsc;
         use windows::Win32::Foundation::{HWND, RECT};
         use windows::Win32::UI::WindowsAndMessaging::{
-            GetWindowRect, SetCursorPos, SetWindowPos, SWP_NOACTIVATE, SWP_NOSIZE, SWP_NOZORDER,
+            GetWindowRect, SWP_NOACTIVATE, SWP_NOSIZE, SWP_NOZORDER, SetCursorPos, SetWindowPos,
         };
 
         // Capture drag signals (no Tauri), then start the REAL hook pipeline.
@@ -1074,12 +1168,17 @@ mod manual_smoke {
 
         // Spawn a throwaway window; identify it by diffing the arrangeable set across the spawn.
         let before: HashSet<i64> = arrangeable().into_iter().map(|w| w.hwnd).collect();
-        let mut child = Command::new("notepad.exe").spawn().expect("failed to spawn notepad.exe");
+        let mut child = Command::new("notepad.exe")
+            .spawn()
+            .expect("failed to spawn notepad.exe");
         let deadline = Instant::now() + Duration::from_secs(5);
         let mut hwnd_id = None;
         while Instant::now() < deadline && hwnd_id.is_none() {
             sleep(Duration::from_millis(150));
-            hwnd_id = arrangeable().into_iter().find(|w| !before.contains(&w.hwnd)).map(|w| w.hwnd);
+            hwnd_id = arrangeable()
+                .into_iter()
+                .find(|w| !before.contains(&w.hwnd))
+                .map(|w| w.hwnd);
         }
         let Some(hwnd_id) = hwnd_id else {
             let _ = child.kill();
@@ -1124,11 +1223,15 @@ mod manual_smoke {
         let signals: Vec<DragAction> = rx.try_iter().collect();
         println!("captured drag signals: {signals:?}");
         assert!(
-            signals.iter().any(|a| matches!(a, DragAction::Start(h) if *h == hwnd_id)),
+            signals
+                .iter()
+                .any(|a| matches!(a, DragAction::Start(h) if *h == hwnd_id)),
             "expected a synthetic Start for the dragged window; got {signals:?}"
         );
         assert!(
-            signals.iter().any(|a| matches!(a, DragAction::End(h) if *h == hwnd_id)),
+            signals
+                .iter()
+                .any(|a| matches!(a, DragAction::End(h) if *h == hwnd_id)),
             "expected an End after the button release; got {signals:?}"
         );
     }
diff --git a/widgetsack/tauri.conf.json b/widgetsack/tauri.conf.json
index 62bd766..f2362e6 100644
--- a/widgetsack/tauri.conf.json
+++ b/widgetsack/tauri.conf.json
@@ -50,7 +50,7 @@
     "createUpdaterArtifacts": false
   },
   "productName": "widgetsack",
-  "version": "0.0.47",
+  "version": "0.0.48",
   "identifier": "io.github.gyng",
   "plugins": {},
   "app": {