@zhz8888/dsh-android-emulator-helper 1.0.0 → 1.1.0

package/lib/client.js

@@ -39,38 +39,58 @@ window.__ModuleLoader__.load({
 		const CSS_TAG = "@zhz8888/dsh-android-emulator-helper/Settings.module.css";
 
 		const CSS = [
-			".aemh_page{flex-direction:column;gap:20px;display:flex;max-width:760px;color:var(--dsw-alias-label-primary)}",
-			".aemh_intro{color:var(--dsw-alias-label-tertiary);margin:0;font-size:13px;line-height:20px}",
-			".aemh_group{flex-direction:column;gap:14px;display:flex}",
-			".aemh_groupHead{flex-direction:column;gap:2px;display:flex}",
-			".aemh_groupTitle{margin:0;font-size:15px;font-weight:600;line-height:22px}",
-			".aemh_groupHint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:18px}",
-			".aemh_field{flex-direction:column;gap:6px;display:flex;min-width:0}",
+			// Page frame. The shell renders the section's nav label but no title of
+			// its own, so the page carries one, then a secondary intro. Below that
+			// it is one card per category: the card outline is what separates the
+			// categories, so no rule is needed between them and each group reads as
+			// one block. The metrics are read from the platform's own field kit —
+			// `@deepseek-ai/dsh-client-ui-primitives/lib/settings-form/fields.module.css`
+			// (MIT), which every built-in settings page uses — so the page sits
+			// beside them: a 13/1.5 label, a 12px hint, a 34px control on a 0.5px
+			// border-l4 edge. The composition above those pieces is this page's own.
+			".aemh_page{flex-direction:column;display:flex;max-width:720px;color:var(--dsw-alias-label-primary)}",
+			".aemh_title{margin:0;font-size:16px;font-weight:600;line-height:1.5}",
+			".aemh_intro{margin:6px 0 0;font-size:13px;line-height:1.6;color:var(--dsw-alias-label-secondary)}",
+			".aemh_readOnly{margin:12px 0 0;font-size:12px;line-height:1.6;color:var(--dsw-alias-label-tertiary)}",
+			".aemh_group{margin-top:20px;padding:14px 16px 16px;border:.5px solid var(--dsw-alias-border-l2);border-radius:var(--dsw-radius-lg);background:var(--dsw-alias-bg-layer-2);flex-direction:column;display:flex}",
+			".aemh_groupHead{align-items:baseline;gap:8px;display:flex}",
+			".aemh_groupTitle{margin:0;font-size:14px;font-weight:600;line-height:1.5}",
+			".aemh_groupHint{color:var(--dsw-alias-label-tertiary);margin:2px 0 4px;font-size:12px;line-height:1.6}",
+			".aemh_field{flex-direction:column;gap:6px;display:flex;padding:10px 0;min-width:0}",
 			".aemh_fieldHead{align-items:center;gap:8px;display:flex;min-width:0}",
-			".aemh_label{font-size:13px;font-weight:500;line-height:20px}",
-			".aemh_reset{font:inherit;color:var(--dsw-alias-label-tertiary);cursor:pointer;background:0 0;border:0;padding:0;font-size:12px;line-height:18px;text-decoration:underline}",
-			".aemh_reset:hover{color:var(--dsw-alias-label-primary)}",
-			".aemh_control{border:.5px solid var(--dsw-alias-border-l4);border-radius:var(--dsw-radius-md);background:var(--dsw-alias-bg-layer-3);height:36px;font:inherit;color:var(--dsw-alias-label-primary);outline:none;padding:0 12px;font-size:13px;width:100%;box-sizing:border-box}",
-			".aemh_control:focus{border-color:var(--dsw-alias-state-business-primary);box-shadow:inset 0 0 0 .5px var(--dsw-alias-state-business-primary)}",
-			".aemh_control[aria-invalid=true]{border-color:var(--dsw-alias-state-error-primary);box-shadow:none}",
-			".aemh_control:disabled{opacity:.6;cursor:default}",
-			"textarea.aemh_control{height:auto;min-height:84px;padding:8px 12px;line-height:20px;resize:vertical;font-family:var(--dsw-font-mono,ui-monospace,SFMono-Regular,Menlo,monospace);font-size:12px}",
-			".aemh_select{appearance:none;cursor:pointer;padding-right:30px;background-repeat:no-repeat;background-position:right 10px center;background-size:12px;background-image:url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 14 14' fill='none'><path d='M3.5 5.5L7 9l3.5-3.5' stroke='%23888' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/></svg>\")}",
-			".aemh_switchRow{align-items:center;gap:10px;display:flex}",
-			".aemh_hint{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:18px}",
-			".aemh_error{color:var(--dsw-alias-state-error-primary);margin:0;font-size:12px;line-height:18px}",
-			".aemh_tools{border-top:.5px solid var(--dsw-alias-border-l2);flex-direction:column;gap:12px;padding-top:16px;display:flex}",
+			".aemh_label{font-size:13px;font-weight:500;line-height:1.5}",
+			".aemh_reset{font-size:12px;line-height:1.5;color:var(--dsw-alias-label-tertiary);text-decoration:underline;cursor:pointer;background:none;border:0;padding:0}",
+			".aemh_reset:hover:not(:disabled){color:var(--dsw-alias-label-primary)}",
+			".aemh_reset:disabled{cursor:default;opacity:.5}",
+			".aemh_control{box-sizing:border-box;border:.5px solid var(--dsw-alias-border-l4);border-radius:var(--dsw-radius-md);background:var(--dsw-alias-bg-layer-3);height:34px;font:inherit;color:var(--dsw-alias-label-primary);outline:none;padding:0 12px;font-size:13px;line-height:1.5;width:100%}",
+			".aemh_control:focus-visible{border-color:var(--dsw-alias-state-business-primary)}",
+			".aemh_control[aria-invalid=true]{border-color:var(--dsw-alias-state-error-primary)}",
+			".aemh_control:disabled{color:var(--dsw-alias-label-tertiary);cursor:default}",
+			"textarea.aemh_control{height:auto;min-height:96px;padding:10px 12px;line-height:1.6;resize:vertical;font-family:var(--dsw-font-mono,ui-monospace,SFMono-Regular,Menlo,monospace);font-size:12px}",
+			".aemh_selectWrap{position:relative;display:block}",
+			".aemh_selectWrap::after{content:\"\";position:absolute;right:12px;top:calc(50% - 2px);border-left:4px solid transparent;border-right:4px solid transparent;border-top:5px solid var(--dsw-alias-label-tertiary);pointer-events:none}",
+			".aemh_select{appearance:none;cursor:pointer;padding-right:28px}",
+			".aemh_hint{font-size:12px;line-height:1.6;color:var(--dsw-alias-label-tertiary)}",
+			".aemh_error{color:var(--dsw-alias-state-error-primary);margin:0;font-size:12px;line-height:1.6}",
 			".aemh_toolRow{flex-wrap:wrap;align-items:center;gap:10px;display:flex}",
 			".aemh_checks{flex-direction:column;gap:2px;margin:0;padding:0;list-style:none;display:flex}",
 			".aemh_check{border-bottom:.5px solid var(--dsw-alias-border-l2);align-items:flex-start;gap:10px;padding:8px 0;display:flex}",
 			".aemh_check:last-child{border-bottom:0}",
 			".aemh_checkBody{flex-direction:column;gap:2px;min-width:0;flex:1;display:flex}",
-			".aemh_checkName{font-size:13px;line-height:20px}",
-			".aemh_checkDetail{color:var(--dsw-alias-label-tertiary);overflow-wrap:anywhere;white-space:pre-wrap;margin:0;font-size:12px;line-height:18px}",
-			".aemh_checkFix{color:var(--dsw-alias-state-warn-label,var(--dsw-alias-label-secondary));overflow-wrap:anywhere;margin:0;font-size:12px;line-height:18px}",
-			".aemh_verdict{align-items:center;gap:8px;font-size:13px;line-height:20px;display:flex}",
-			".aemh_note{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:18px}",
+			".aemh_checkName{font-size:13px;line-height:1.5}",
+			".aemh_checkDetail{color:var(--dsw-alias-label-tertiary);overflow-wrap:anywhere;white-space:pre-wrap;margin:0;font-size:12px;line-height:1.6}",
+			".aemh_checkFix{color:var(--dsw-alias-state-warn-label,var(--dsw-alias-label-secondary));overflow-wrap:anywhere;margin:0;font-size:12px;line-height:1.6}",
+			".aemh_verdict{align-items:center;gap:8px;font-size:13px;line-height:1.5;display:flex}",
+			".aemh_note{color:var(--dsw-alias-label-tertiary);margin:0;font-size:12px;line-height:1.6}",
 			".aemh_mono{font-family:var(--dsw-font-mono,ui-monospace,SFMono-Regular,Menlo,monospace);overflow-wrap:anywhere}",
+			// A small pill, not a full-width panel: it hugs its message and buttons and
+			// centres itself in the page column with auto margins, so it reads as a
+			// floating notice. It is still one in-flow child held at the bottom by
+			// `position: sticky`, so it never covers a field and nothing has to
+			// reserve room for it.
+			".aemh_actions{position:sticky;bottom:16px;z-index:1;box-sizing:border-box;margin:20px auto 0;padding:6px 8px 6px 14px;width:max-content;max-width:min(560px,100%);border:.5px solid var(--dsw-alias-border-l2);border-radius:999px;background:var(--dsw-alias-bg-layer-1);box-shadow:var(--dsw-elevation-soft,0 4px 14px -6px rgba(0,0,0,.2));align-items:center;gap:8px;display:flex}",
+			".aemh_actionsText{flex:0 1 auto;min-width:0;margin:0 4px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-size:13px;line-height:1.5}",
+			".aemh_actionsError .aemh_actionsText{color:var(--dsw-alias-state-error-primary)}",
 		].join("");
 
 		/**
@@ -174,12 +194,12 @@ window.__ModuleLoader__.load({
 						},
 					},
 					{
-						key: "bootTimeoutMs",
+						key: "bootTimeoutSeconds",
 						kind: "number",
-						label: { zh: "模拟器启动超时 (ms)", en: "Emulator boot timeout (ms)" },
+						label: { zh: "模拟器启动超时（秒）", en: "Emulator boot timeout (seconds)" },
 						hint: {
-							zh: "等待模拟器完成启动的最长时间，默认 180000。",
-							en: "Longest wait for the emulator to finish booting; 180000 by default.",
+							zh: "等待模拟器完成启动的最长时间，默认 180 秒。",
+							en: "Longest wait for the emulator to finish booting; 180 seconds by default.",
 						},
 					},
 				],
@@ -199,8 +219,8 @@ window.__ModuleLoader__.load({
 						placeholder: "35",
 						label: { zh: "Android API 级别", en: "Android API level" },
 						hint: {
-							zh: "compileSdk 与系统镜像包名中的 API 级别。",
-							en: "The API level used for compileSdk and the system-image package id.",
+							zh: "生成项目、安装 SDK 包与选择系统镜像时使用的 API 级别。",
+							en: "API level used when generating projects, installing SDK packages and picking a system image.",
 						},
 					},
 					{
@@ -241,12 +261,12 @@ window.__ModuleLoader__.load({
 				hint: { zh: "Gradle 构建的超时与附加参数。", en: "Gradle timeouts and extra arguments." },
 				fields: [
 					{
-						key: "buildTimeoutMs",
+						key: "buildTimeoutSeconds",
 						kind: "number",
-						label: { zh: "Gradle 构建超时 (ms)", en: "Gradle build timeout (ms)" },
+						label: { zh: "Gradle 构建超时（秒）", en: "Gradle build timeout (seconds)" },
 						hint: {
-							zh: "一次 assemble 任务的最长运行时间，默认 600000。",
-							en: "Longest runtime of one assemble task; 600000 by default.",
+							zh: "一次 assemble 任务的最长运行时间，默认 600 秒。",
+							en: "Longest runtime of one assemble task; 600 seconds by default.",
 						},
 					},
 					{
@@ -374,6 +394,7 @@ window.__ModuleLoader__.load({
 		function buildDictionaries() {
 			const en = {
 				nav: "Android emulator",
+				title: "Android Emulator",
 				intro:
 					"Parameters for the android_* tools: which Android SDK and JDK to use, how an emulator starts, and where captures and build logs are written. Changes are saved to this profile and take effect on the next tool call.",
 				invalid: "Enter a whole number, or leave blank to use the default.",
@@ -381,7 +402,11 @@ window.__ModuleLoader__.load({
 				reset: "Reset to default",
 				save: "Save",
 				saving: "Saving…",
-				saveFailed: "The deployment did not accept these values; they were left for you to correct.",
+				discard: "Discard changes",
+				pendingWrite: "Unsaved changes",
+				writeBlocked: "One value is invalid; fix it before saving",
+				writeFailed: "These values were not accepted, so they are still staged.",
+				written: "Saved to this profile",
 				readOnly: "This deployment stores settings read-only.",
 				unavailable: "This plugin's settings are not served, so it cannot be configured right now.",
 				loading: "Loading saved values…",
@@ -402,6 +427,7 @@ window.__ModuleLoader__.load({
 			};
 			const zh = {
 				nav: "Android 模拟器",
+				title: "Android 模拟器",
 				intro:
 					"android_* 工具的运行参数：使用哪个 Android SDK 与 JDK、模拟器如何启动、截图与构建日志写到哪里。保存后写入当前 profile，并在下一次工具调用时生效。",
 				invalid: "请填整数；留空表示使用默认值。",
@@ -409,7 +435,11 @@ window.__ModuleLoader__.load({
 				reset: "恢复默认",
 				save: "保存",
 				saving: "保存中…",
-				saveFailed: "本部署没有接受这些值，已保留供你修改。",
+				discard: "放弃改动",
+				pendingWrite: "有改动尚未保存",
+				writeBlocked: "有取值不合法，修正后才能保存",
+				writeFailed: "这批取值未被接受，仍保留在表单里。",
+				written: "已保存到当前 profile",
 				readOnly: "本部署的设置为只读。",
 				unavailable: "该插件的设置当前未被服务，暂时无法配置。",
 				loading: "正在读取已保存的值…",
@@ -517,30 +547,34 @@ window.__ModuleLoader__.load({
 			const { field, state, disabled, id, listId, suggestions, onChange, t } = input;
 			switch (field.kind) {
 				case "boolean":
-					return h(
-						"div",
-						{ className: "aemh_switchRow" },
-						h(P.Switch, {
-							checked: state.text === "true",
-							disabled,
-							label: t(`field.${field.key}`),
-							onChange: (next) => onChange(next ? "true" : "false"),
-						}),
-						h("span", { className: "aemh_hint" }, state.text === "true" ? "on" : "off"),
-					);
+					// The switch is its own state indicator: a neighbouring "on"/"off"
+					// label would only repeat what the track already shows.
+					return h(P.Switch, {
+						checked: state.text === "true",
+						disabled,
+						label: t(`field.${field.key}`),
+						onChange: (next) => onChange(next ? "true" : "false"),
+					});
 				case "select":
+					// The chevron is drawn by the wrapper: a native select cannot carry a
+					// pseudo-element of its own, and the CSS triangle follows the theme
+					// where a data-URI glyph could not.
 					return h(
-						"select",
-						{
-							id,
-							className: "aemh_control aemh_select",
-							value: state.text,
-							disabled,
-							"aria-invalid": state.invalid ? "true" : undefined,
-							onChange: (event) => onChange(event.target.value),
-						},
-						selectOptions(field, state.text).map((value) =>
-							h("option", { key: value === "" ? "__auto__" : value, value }, optionLabel(field, value, t)),
+						"span",
+						{ className: "aemh_selectWrap" },
+						h(
+							"select",
+							{
+								id,
+								className: "aemh_control aemh_select",
+								value: state.text,
+								disabled,
+								"aria-invalid": state.invalid ? "true" : undefined,
+								onChange: (event) => onChange(event.target.value),
+							},
+							selectOptions(field, state.text).map((value) =>
+								h("option", { key: value === "" ? "__auto__" : value, value }, optionLabel(field, value, t)),
+							),
 						),
 					);
 				case "multiline":
@@ -583,6 +617,93 @@ window.__ModuleLoader__.load({
 			}
 		}
 
+		/**
+		 * The action bar's state for one projection of the form.
+		 *
+		 * The bar is the only place a save starts, and it exists only while there is
+		 * something to act on: a staged edit waiting to be written, a write in
+		 * flight, or a failure worth retrying. A clean form answers `null`, which is
+		 * what removes the bar from the page — nothing lingers in a hidden state.
+		 *
+		 * The shape is flat on purpose: the component below only maps it to
+		 * elements, so every rule about what may be pressed lives here, in one place.
+		 *
+		 * @param {{dirty: boolean, invalid: boolean, saving: boolean, failed: boolean}} shell -
+		 *   the form-level state the shared model publishes.
+		 * @param {Function} t - the page's dictionary lookup.
+		 * @returns {{tone: string, message: string, canSave: boolean, canDiscard: boolean}|null}
+		 *   the bar state, or `null` when the bar has nothing to say.
+		 */
+		function actionBarState(shell, t) {
+			if (shell.failed) {
+				return { tone: "error", message: t("writeFailed"), canDiscard: true, canSave: shell.dirty && !shell.invalid };
+			}
+			if (shell.saving) return { tone: "pending", message: t("saving"), canDiscard: false, canSave: false };
+			if (!shell.dirty) return null;
+			if (shell.invalid) return { tone: "error", message: t("writeBlocked"), canDiscard: true, canSave: false };
+			return { tone: "pending", message: t("pendingWrite"), canDiscard: true, canSave: true };
+		}
+
+		/**
+		 * The action bar: the staged form's status plus the two ways out of it.
+		 *
+		 * A plain element at the end of the page column, kept on screen by the
+		 * stylesheet while the page scrolls. Both buttons are the shared `Button`
+		 * primitive and the leading mark is the shared `StateDot`, so what it looks
+		 * like comes from the platform rather than from this page.
+		 *
+		 * @param {object} props - the bar state, the form shell and the two actions.
+		 * @returns {object|null} the bar, or nothing while the form is clean.
+		 */
+		function ActionBar(props) {
+			const { view, shell, t, onDiscard, onSave } = props;
+			if (view === null) return null;
+			const failed = view.tone === "error";
+			return h(
+				"div",
+				{ className: failed ? "aemh_actions aemh_actionsError" : "aemh_actions" },
+				h(P.StateDot, { state: failed ? "error" : "warning", size: 8 }),
+				// The pill is as wide as its content, so a long failure message is
+				// truncated; the title attribute keeps the whole sentence reachable.
+				h(
+					"p",
+					{ className: "aemh_actionsText", role: "status", "aria-live": "polite", title: view.message },
+					view.message,
+				),
+				h(
+					P.Button,
+					{ variant: "ghost", size: "sm", disabled: !view.canDiscard || shell.saving, onClick: onDiscard },
+					t("discard"),
+				),
+				h(
+					P.Button,
+					{ variant: "primary", size: "sm", disabled: !view.canSave || shell.saving, onClick: onSave },
+					shell.saving ? t("saving") : t("save"),
+				),
+			);
+		}
+
+		/**
+		 * The transient "written" confirmation.
+		 *
+		 * The shared `Toast` owns the hold, the fade and the teardown: it reports
+		 * completion through `onDone`, which clears the sequence and unmounts it.
+		 * Keying the toast by the sequence restarts the cycle when a later write
+		 * lands, and a page that has never saved mounts nothing at all.
+		 *
+		 * @param {object} props - the landed-write counter and the dictionary lookup.
+		 * @returns {object|null} the toast, or nothing.
+		 */
+		function SavedToast(props) {
+			const { tick, t } = props;
+			const [shown, setShown] = React.useState(0);
+			React.useEffect(() => {
+				if (tick > 0) setShown(tick);
+			}, [tick]);
+			if (shown === 0) return null;
+			return h(P.Toast, { key: shown, tone: "success", text: t("written"), onDone: () => setShown(0) });
+		}
+
 		/** The full settings page. */
 		function SettingsPage(props) {
 			const state = props.useAndroidEmulatorSettings((snapshot) => snapshot);
@@ -603,10 +724,20 @@ window.__ModuleLoader__.load({
 				buildTools: unique((inventory.data?.buildTools ?? []).map((id) => id.split(";")[1] ?? "").filter(Boolean)).sort(),
 			};
 
+			// Leaving the page abandons staged edits, exactly as the harness's own
+			// settings forms do: the controller outlives the page, so without this a
+			// half-finished edit would still be staged on the next visit.
+			const discard = React.useRef(props.discard);
+			discard.current = props.discard;
+			React.useEffect(() => () => discard.current(), []);
+
+			const bar = actionBarState(state, t);
+
 			if (!state.available) {
 				return h(
 					"div",
 					{ className: "aemh_page" },
+					h("h2", { className: "aemh_title" }, t("title")),
 					h("p", { className: "aemh_intro", role: "status" }, t(state.status === "loading" ? "loading" : "unavailable")),
 				);
 			}
@@ -614,51 +745,39 @@ window.__ModuleLoader__.load({
 			return h(
 				"div",
 				{ className: "aemh_page" },
+				h("h2", { className: "aemh_title" }, t("title")),
 				h("p", { className: "aemh_intro" }, t("intro")),
-				h(
-					P.SettingsForm,
-					{
-						state,
-						labels: {
-							unavailable: t("unavailable"),
-							readOnly: t("readOnly"),
-							saveFailed: t("saveFailed"),
-							save: t("save"),
-							saving: t("saving"),
-						},
-						onSave: props.save,
-						onDiscard: props.discard,
-					},
-					GROUPS.map((group) =>
+				state.writable ? null : h("p", { className: "aemh_readOnly", role: "status" }, t("readOnly")),
+				GROUPS.map((group) =>
+					h(
+						"section",
+						{ className: "aemh_group", key: group.id },
 						h(
-							"section",
-							{ className: "aemh_group", key: group.id },
-							h(
-								"div",
-								{ className: "aemh_groupHead" },
-								h("h3", { className: "aemh_groupTitle" }, t(`group.${group.id}`)),
-								h("p", { className: "aemh_groupHint" }, t(`group.${group.id}.hint`)),
-							),
-							group.fields.map((field) =>
-								h(Field, {
-									key: field.key,
-									field,
-									state: state.fields[field.key],
-									disabled: !state.writable || state.saving,
-									suggestions: field.suggest ? suggestions[field.suggest] : undefined,
-									onChange: (text) => props.edit(field.key, text),
-									onReset: () => props.resetField(field.key),
-									t,
-								}),
-							),
+							"div",
+							{ className: "aemh_groupHead" },
+							h("h3", { className: "aemh_groupTitle" }, t(`group.${group.id}`)),
+						),
+						h("p", { className: "aemh_groupHint" }, t(`group.${group.id}.hint`)),
+						group.fields.map((field) =>
+							h(Field, {
+								key: field.key,
+								field,
+								state: state.fields[field.key],
+								disabled: !state.writable || state.saving,
+								suggestions: field.suggest ? suggestions[field.suggest] : undefined,
+								onChange: (text) => props.edit(field.key, text),
+								onReset: () => props.resetField(field.key),
+								t,
+							}),
 						),
 					),
+				),
+				h(
+					"section",
+					{ className: "aemh_group" },
+					h("div", { className: "aemh_groupHead" }, h("h3", { className: "aemh_groupTitle" }, t("toolsTitle"))),
+					h("p", { className: "aemh_groupHint" }, t("toolsHint")),
 					h(
-						"section",
-						{ className: "aemh_tools" },
-						h("h3", { className: "aemh_groupTitle" }, t("toolsTitle")),
-						h("p", { className: "aemh_groupHint" }, t("toolsHint")),
-						h(
 							"div",
 							{ className: "aemh_toolRow" },
 							h(
@@ -685,7 +804,8 @@ window.__ModuleLoader__.load({
 						renderDiagnostics(diagnostics, t),
 						renderInventory(inventory, t),
 					),
-				),
+				h(ActionBar, { view: bar, shell: state, t, onDiscard: props.discard, onSave: props.save }),
+				h(SavedToast, { tick: state.savedCount, t }),
 			);
 		}
 
@@ -810,6 +930,29 @@ window.__ModuleLoader__.load({
 			return body;
 		}
 
+		/**
+		 * Whether a draft would actually change anything.
+		 *
+		 * The shared model counts any staged draft as dirty, including one that
+		 * stages the value already in effect: typing a field's own value back left
+		 * the form dirty and the control flagged as overridden while a save would
+		 * write nothing. This classifies the draft by comparing the value it would
+		 * write with the one in effect, so the page can present a control that has
+		 * not actually changed as unchanged.
+		 *
+		 * @param {object} model - the bound `SettingsFormModel`.
+		 * @param {object} field - the field descriptor.
+		 * @param {string} text - the control's current text.
+		 * @returns {"noop"|"real"|"invalid"} `noop` when a save would change nothing,
+		 *   `invalid` when the draft is not a value the field accepts.
+		 */
+		function draftDelta(model, field, text) {
+			const write = specFor(field).parse(text);
+			if (write === undefined) return "invalid";
+			if (write.kind === "clear") return model.stored(field.key) ? "real" : "noop";
+			return Object.is(write.value, model.sectionValue(field.key)) ? "noop" : "real";
+		}
+
 		/**
 		 * Own the page's staged form and the face its slot entry injects.
 		 *
@@ -824,14 +967,45 @@ window.__ModuleLoader__.load({
 				scope,
 				FIELDS.map((field) => specFor(field)),
 			);
+			/** Saves that landed; the page flashes its confirmation when this grows. */
+			this.savedCount = 0;
+			/** Whether a write was in flight at the last projection. */
+			this.saveInFlight = false;
 			this.store = this.model.bind(() => this.projection());
 		}
 
 		Controller.prototype.projection = function projection() {
 			const shell = this.model.shell();
+			// The primitive reports its state, not its outcome, so a save that landed
+			// is observed as the transition out of "saving" with no failure and no
+			// edits left staged. Counting it here keeps the page's confirmation free
+			// of timers of its own.
+			if (shell.saving) this.saveInFlight = true;
+			else if (this.saveInFlight) {
+				this.saveInFlight = false;
+				if (!shell.failed && !shell.dirty) this.savedCount += 1;
+			}
 			const fields = {};
-			for (const field of FIELDS) fields[field.key] = this.model.field(field.key);
-			return { ...shell, status: this.scope.getSnapshot().status, fields };
+			let changes = 0;
+			for (const field of FIELDS) {
+				const state = this.model.field(field.key);
+				const delta = draftDelta(this.model, field, state.text);
+				if (delta !== "noop") changes += 1;
+				fields[field.key] =
+					delta === "noop" && state.overridden
+						? { ...state, overridden: this.model.stored(field.key) }
+						: state;
+			}
+			return {
+				...shell,
+				// The model counts any staged draft as dirty, including one that would
+				// write the value already in effect; the bar and the save button follow
+				// this count instead, so reverting an edit really does clean the form.
+				dirty: shell.dirty && changes > 0,
+				savedCount: this.savedCount,
+				status: this.scope.getSnapshot().status,
+				fields,
+			};
 		};
 
 		Controller.prototype.inject = function inject() {
@@ -903,17 +1077,35 @@ window.__ModuleLoader__.load({
 
 		exports.NS = NS;
 		/**
-		 * Field descriptors as this half sees them.
+		 * The field table as this half sees it, complete.
 		 *
 		 * Exported for the drift check in `scripts/check-bundle.mjs` only: the
-		 * browser cannot import the host's `lib/settings.js`, so the two field
-		 * tables are written twice and must be kept identical by construction.
+		 * browser cannot import the host's `lib/settings.js`, so the labels,
+		 * hints and options are written twice and must be kept identical by
+		 * construction. Exporting the *whole* descriptor rather than a projection
+		 * is what lets the gate catch a reworded label, not just a renamed field.
 		 * Nothing at runtime reads this.
 		 */
 		exports.FIELD_META = FIELDS.map((field) => ({
 			key: field.key,
 			kind: field.kind,
 			options: field.options,
+			label: field.label,
+			hint: field.hint,
+			placeholder: field.placeholder,
+			optionLabel: field.optionLabel,
+		}));
+		/**
+		 * The group table as this half sees it: the headings and hints the page
+		 * renders around each card, plus the field keys each card holds.
+		 *
+		 * Also for the drift check. Nothing at runtime reads this.
+		 */
+		exports.GROUP_META = GROUPS.map((group) => ({
+			id: group.id,
+			title: group.title,
+			hint: group.hint,
+			fields: group.fields.map((field) => field.key),
 		}));
 		exports.apply = apply;
 		exports.inject = inject;

package/lib/index.js

@@ -105,6 +105,16 @@ function registerSkill(ctx, logger) {
         description: loaded.description,
         ...(loaded.whenToUse === undefined ? {} : { whenToUse: loaded.whenToUse }),
         content: loaded.content,
+        // `source` and `path` are not optional in practice. The registry builds a
+        // discovery CANDIDATE out of the registered skill and validates it with
+        // `typeof candidate.source !== "string" -> throw`, so a registration that
+        // omits `source` fails when the skill is looked up, not when it is
+        // registered: `apply` succeeds and `skills.get('android-dev')` then throws
+        // "loaded skill android-dev source must be a string". `path` is what a
+        // caller shows and resolves the body from.
+        source: 'runtime',
+        path: path.join(SKILL_DIR, 'SKILL.md'),
+        provider: 'runtime',
         resourceBase: { kind: 'directory', path: SKILL_DIR },
       })
     }, 'android-emulator-helper: android-dev skill')
@@ -247,8 +257,11 @@ function registerRoutes(ctx, { config, logger }) {
           methods: ['GET'],
           requestBody: 'buffered',
           fetch: async () => {
-            const rt = createRuntime({ config, exec: undefined, logger })
+            // `createRuntime` reads the live settings, so it belongs inside the
+            // guard: a reference that cannot be read must still answer with a
+            // JSON body instead of rejecting the request.
             try {
+              const rt = createRuntime({ config, exec: undefined, logger })
               return jsonResponse(200, await preflight(rt))
             } catch (error) {
               return jsonResponse(500, { error: message(error) })
@@ -264,8 +277,8 @@ function registerRoutes(ctx, { config, logger }) {
           methods: ['GET'],
           requestBody: 'buffered',
           fetch: async () => {
-            const rt = createRuntime({ config, exec: undefined, logger })
             try {
+              const rt = createRuntime({ config, exec: undefined, logger })
               return jsonResponse(200, await inventory(rt))
             } catch (error) {
               return jsonResponse(500, { error: message(error) })