dsh-web-search-plugin 0.4.1 → 0.5.0

package/lib/client.js

@@ -12,6 +12,10 @@
  * writes once, credential written through the credentials domain) without
  * depending on that package's internal `CardForm`.
  *
+ * Adapted to DeepSeek Harness `0.2.x`: the card reads and writes its namespace
+ * through `ctx.configForms` (`ConfigForm`), replacing the removed
+ * `ctx.settingsScope` service.
+ *
  * @module dsh-web-search-plugin/client
  */
 window.__ModuleLoader__.load({
@@ -44,6 +48,42 @@ window.__ModuleLoader__.load({
 			for (const entry of BUILTIN_REST_PROVIDERS) if (entry.keyField === field) return entry;
 			return void 0;
 		}
+		/**
+		 * Where each provider issues its keys. The REST rows carry their own
+		 * `officialUrl`; the three with dedicated branches are listed here so every
+		 * engine gets the same "get an API key" affordance.
+		 */
+		const KEY_CONSOLE_URLS = {
+			"deepseek-official": "https://platform.deepseek.com/",
+			tavily: "https://app.tavily.com/",
+			brave: "https://api-dashboard.search.brave.com/"
+		};
+		/** The console URL for the active engine, when it issues keys. */
+		function keyConsoleUrl(provider, restMeta) {
+			if (restMeta !== void 0) return restMeta.keyRequired ? restMeta.officialUrl : "";
+			return KEY_CONSOLE_URLS[provider] ?? "";
+		}
+		/**
+		 * The "get an API key" link every key-issuing engine shows.
+		 * @param t - the card's locale reader.
+		 * @param provider - the active engine id.
+		 * @param restMeta - the engine's metadata row, when it has one.
+		 * @param keyed - Tavily only: whether it is in keyed mode.
+		 * @returns the link element, or null when the engine issues no keys.
+		 */
+		function keyConsoleLink(t, provider, restMeta, keyed) {
+			// Tavily's keyless mode needs no key, so it gets no console link.
+			if (provider === "tavily" && keyed !== true) return null;
+			const url = keyConsoleUrl(provider, restMeta);
+			if (url === "") return null;
+			return react.createElement("a", {
+				href: url,
+				target: "_blank",
+				rel: "noopener noreferrer",
+				className: "dshws_field_hint",
+				style: { color: "var(--dsw-alias-brand-primary,#3b82f6)", textDecoration: "none", padding: "8px 0", display: "inline-block" }
+			}, t("getKey") + " ↗");
+		}
 		/** Credential reference Tavily keyed mode resolves when the section names none. */
 		const DEFAULT_TAVILY_KEY_REF = "TAVILY_API_KEY";
 		/** Credential reference Brave resolves when the section names none. */
@@ -162,6 +202,7 @@ window.__ModuleLoader__.load({
 			invalidToast: "Fix the highlighted fields before saving.",
 			readOnly: "This deployment stores settings read-only.",
 			invalidNumber: "Enter a whole number of at least 1, or leave blank for the default.",
+			invalidCredentialRef: "Use an environment variable name: letters, digits, and underscores; the first character must be a letter or underscore.",
 			quotaTitle: "Quota",
 			quotaPlan: "Plan {plan}",
 			quotaUsed: "Used {used} / {limit}",
@@ -258,6 +299,7 @@ window.__ModuleLoader__.load({
 			invalidToast: "请先修正标红的字段再保存。",
 			readOnly: "本部署的设置为只读。",
 			invalidNumber: "请输入不小于 1 的整数；留空表示使用默认值。",
+			invalidCredentialRef: "请使用环境变量名：仅含字母、数字和下划线，且以字母或下划线开头。",
 			quotaTitle: "额度",
 			quotaPlan: "计划 {plan}",
 			quotaUsed: "已用 {used} / {limit}",
@@ -311,6 +353,17 @@ window.__ModuleLoader__.load({
 				}
 			};
 		}
+		function credentialField(field) {
+			return {
+				field,
+				format: (value) => typeof value === "string" ? value : "",
+				parse: (text) => {
+					const trimmed = text.trim();
+					if (trimmed === "") return { kind: "clear" };
+					return /^[A-Za-z_][A-Za-z0-9_]*$/u.test(trimmed) ? { kind: "set", value: trimmed } : void 0;
+				}
+			};
+		}
 		/** A choice field spec: staged as its raw string. */
 		function choiceField(field) {
 			return {
@@ -330,7 +383,7 @@ window.__ModuleLoader__.load({
 
 		/**
 		 * Staged form over the `dsh-web-search-plugin` settings namespace.
-		 * Write-only credential fields (`apiKey`, `braveApiKey`) have no section
+		 * Write-only credential fields have no section
 		 * spec and are written through the credentials domain.
 		 */
 		var SearchCardForm = class {
@@ -341,33 +394,33 @@ window.__ModuleLoader__.load({
 					choiceField("provider"),
 					choiceField("mode"),
 					numberField("maxResults", { min: 1, max: MAX_RESULTS_CAP }),
-					textField("apiKeyEnv"),
+					credentialField("apiKeyEnv"),
 					textField("baseURL"),
 					choiceField("searchDepth"),
 					choiceField("topic"),
 					booleanField("includeAnswer"),
-					textField("braveApiKeyEnv"),
+					credentialField("braveApiKeyEnv"),
 					textField("braveBaseURL"),
 					textField("country"),
 					textField("searchLang"),
 					choiceField("freshness"),
 					textField("proxy"),
-					textField("deepseekApiKeyEnv"),
+					credentialField("deepseekApiKeyEnv"),
 					textField("deepseekBaseURL"),
 					textField("model"),
 					textField("apiVersion"),
 					numberField("maxTokens", { min: 1 }),
 					numberField("maxUses", { min: 1 }),
-					textField("serperApiKeyEnv"),
+					credentialField("serperApiKeyEnv"),
 					textField("serperBaseURL"),
-					textField("serpapiApiKeyEnv"),
+					credentialField("serpapiApiKeyEnv"),
 					textField("serpapiBaseURL"),
-					textField("exaApiKeyEnv"),
+					credentialField("exaApiKeyEnv"),
 					textField("exaBaseURL"),
 					textField("searxngBaseURL"),
-					textField("scavioApiKeyEnv"),
+					credentialField("scavioApiKeyEnv"),
 					textField("scavioBaseURL"),
-					textField("firecrawlApiKeyEnv"),
+					credentialField("firecrawlApiKeyEnv"),
 					textField("firecrawlBaseURL")
 				].map((spec) => [spec.field, spec]));
 				this.staged = new Map();
@@ -404,7 +457,7 @@ window.__ModuleLoader__.load({
 					available: snapshot.status === "ready",
 					writable: snapshot.writable,
 					dirty: plan.length > 0,
-					invalid: plan.some((item) => item.run === void 0),
+					invalid: plan.some((item) => item.invalid === true),
 					saving: this.saving,
 					failed: this.failed,
 					toastKey: this.toastKey
@@ -435,19 +488,19 @@ window.__ModuleLoader__.load({
 				for (const [field, staged] of this.staged) {
 					if (SECRET_FIELDS.has(field)) {
 						const value = staged.text.trim();
-						if (value !== "") plan.push({ field, run: () => this.writeKey(field, value) });
+						if (value !== "") plan.push({ field, credential: () => this.writeKey(field, value) });
 						continue;
 					}
 					const spec = this.specs.get(field);
 					if (staged.clear) {
-						if (this.stored(field)) plan.push({ field, run: () => this.clear(field) });
+						if (this.stored(field)) plan.push({ field, op: { op: "unset", path: [field] } });
 						continue;
 					}
 					if (staged.text === spec.format(this.sectionValue(field))) continue;
 					const write = spec.parse(staged.text);
-					if (write === void 0) plan.push({ field, run: void 0 });
-					else if (write.kind === "clear") plan.push({ field, run: () => this.clear(field) });
-					else plan.push({ field, run: () => this.store(field, write.value) });
+					if (write === void 0) plan.push({ field, invalid: true });
+					else if (write.kind === "clear") plan.push({ field, op: { op: "unset", path: [field] } });
+					else plan.push({ field, op: { op: "set", path: [field], value: write.value } });
 				}
 				return plan;
 			}
@@ -463,22 +516,31 @@ window.__ModuleLoader__.load({
 			}
 			async save() {
 				const plan = this.plan();
-				const writes = plan.flatMap((item) => item.run === void 0 ? [] : [item.run]);
 				if (this.saving) return;
 				if (plan.length === 0) {
 					this.showToast("nothing");
 					return;
 				}
-				if (writes.length !== plan.length) {
+				if (plan.some((item) => item.invalid === true)) {
 					this.showToast("invalid");
 					return;
 				}
+				const revision = this.snapshotOf().revision;
+				const credentials = plan.filter((item) => item.credential !== void 0);
+				const ops = plan.flatMap((item) => item.op === void 0 ? [] : [item.op]);
+				for (const item of credentials) {
+					// Override even an inherited literal key; unsetting could expose it again.
+					if (!ops.some((op) => op.path[0] === item.field)) ops.push({ op: "set", path: [item.field], value: "" });
+				}
 				this.saving = true;
 				this.failed = false;
 				this.publish();
 				let landed = true;
 				try {
-					for (const write of writes) landed = await write() && landed;
+					for (const item of credentials) {
+						if (!await item.credential()) { landed = false; break; }
+					}
+					if (landed && ops.length > 0) landed = await this.scope.mutate(ops, revision) === true;
 				} catch (_saveFailure) {
 					landed = false;
 				}
@@ -486,19 +548,23 @@ window.__ModuleLoader__.load({
 				this.saving = false;
 				this.failed = !landed;
 				this.showToast(landed ? "saved" : "failed");
+				if (landed) void usageStore.sync();
 			}
 			actions() {
 				return {
 					edit: (field, text) => {
+						if (this.saving) return;
 						this.stage(field, { text, clear: false });
 					},
 					resetField: (field) => {
+						if (this.saving) return;
 						this.stage(field, { text: this.baseText(field), clear: true });
 					},
 					save: () => {
 						this.save();
 					},
 					discard: () => {
+						if (this.saving) return;
 						if (this.staged.size === 0 && !this.failed) return;
 						this.staged.clear();
 						this.failed = false;
@@ -506,22 +572,6 @@ window.__ModuleLoader__.load({
 					}
 				};
 			}
-			async clear(field) {
-				try {
-					await this.scope.unset(field);
-					return true;
-				} catch (_clearFailure) {
-					return false;
-				}
-			}
-			async store(field, value) {
-				try {
-					await this.scope.set(field, value);
-					return true;
-				} catch (_storeFailure) {
-					return false;
-				}
-			}
 			stage(field, edit) {
 				this.staged.set(field, edit);
 				this.failed = false;
@@ -556,17 +606,21 @@ window.__ModuleLoader__.load({
 				if (declared === "tavily" || declared === "brave" || declared === "deepseek-official" || builtinRest(declared) !== void 0) return declared;
 				return "deepseek-official";
 			}
+			credentialRef(field, fallback) {
+				const staged = this.staged.get(field);
+				const declared = staged === void 0
+					? this.sectionValue(field)
+					: staged.clear ? this.snapshotOf().base?.[field] : staged.text.trim();
+				return typeof declared === "string" && declared.length > 0 ? declared : fallback;
+			}
 			tavilyRef() {
-				const declared = this.sectionValue("apiKeyEnv");
-				return declared !== void 0 && declared.length > 0 ? declared : DEFAULT_TAVILY_KEY_REF;
+				return this.credentialRef("apiKeyEnv", DEFAULT_TAVILY_KEY_REF);
 			}
 			braveRef() {
-				const declared = this.sectionValue("braveApiKeyEnv");
-				return declared !== void 0 && declared.length > 0 ? declared : DEFAULT_BRAVE_KEY_REF;
+				return this.credentialRef("braveApiKeyEnv", DEFAULT_BRAVE_KEY_REF);
 			}
 			deepseekRef() {
-				const declared = this.sectionValue("deepseekApiKeyEnv");
-				return declared !== void 0 && declared.length > 0 ? declared : DEFAULT_DEEPSEEK_KEY_REF;
+				return this.credentialRef("deepseekApiKeyEnv", DEFAULT_DEEPSEEK_KEY_REF);
 			}
 			/** The credential reference the currently visible engine uses. */
 			refOf() {
@@ -579,9 +633,8 @@ window.__ModuleLoader__.load({
 			}
 			/** Credential reference for a built-in REST provider's key env field. */
 			restKeyRef(rest) {
-				const declared = this.sectionValue(rest.keyEnvField);
-				if (declared !== void 0 && declared.length > 0) return declared;
-				return rest.id === "serper" ? "SERPER_API_KEY" : rest.id === "serpapi" ? "SERPAPI_API_KEY" : rest.id === "exa" ? "EXA_API_KEY" : rest.id === "scavio" ? "SCAVIO_API_KEY" : "FIRECRAWL_API_KEY";
+				const fallback = rest.id === "serper" ? "SERPER_API_KEY" : rest.id === "serpapi" ? "SERPAPI_API_KEY" : rest.id === "exa" ? "EXA_API_KEY" : rest.id === "scavio" ? "SCAVIO_API_KEY" : "FIRECRAWL_API_KEY";
+				return this.credentialRef(rest.keyEnvField, fallback);
 			}
 			async readCredential() {
 				const ref = this.refOf();
@@ -621,9 +674,11 @@ window.__ModuleLoader__.load({
 				try {
 					const response = await this.remote.credentials.set(ref, value);
 					if (!response.ok) return false;
-				} catch (_credentialWriteFailure) {}
+				} catch (_credentialWriteFailure) {
+					return false;
+				}
 				await this.readCredential();
-				return this.credential.ref === ref ? this.credential.configured : true;
+				return true;
 			}
 		};
 
@@ -681,10 +736,10 @@ window.__ModuleLoader__.load({
 					firecrawlApiKeyEnv: this.form.field("firecrawlApiKeyEnv"),
 					firecrawlBaseURL: this.form.field("firecrawlBaseURL"),
 					apiKeyConfigured: this.form.credential.configured,
-					apiKeyWritable: this.form.credential.writable,
-					toastKey: this.form.toastKey
-				};
-			}
+				apiKeyWritable: this.form.credential.writable,
+				toastKey: this.form.toastKey
+			};
+		}
 			inject() {
 				return {
 					hooks: { pluginSearchCard: this.store },
@@ -701,7 +756,7 @@ window.__ModuleLoader__.load({
 					react.createElement("span", { className: "dshws_badge" }, meta.t("overridden")),
 					react.createElement("button", { type: "button", className: "dshws_reset", disabled: meta.disabled === true, onClick: meta.onReset }, meta.t("reset"))) : null),
 			children,
-			meta?.invalid ? react.createElement("p", { className: "dshws_field_error" }, meta.t("invalidNumber")) : hint ? react.createElement("p", { className: "dshws_field_hint" }, hint) : null);
+			meta?.invalid ? react.createElement("p", { className: "dshws_field_error" }, meta.t(meta.errorKey ?? "invalidNumber")) : hint ? react.createElement("p", { className: "dshws_field_hint" }, hint) : null);
 		const pair = (left, right) => {
 			if (!left && !right) return null;
 			if (!left) return right;
@@ -838,8 +893,9 @@ window.__ModuleLoader__.load({
 					return snap;
 				},
 				refresh: () => load(true),
+				sync: () => load(false),
 				start() {
-					void load(true);
+					void load(false);
 					const timer = setInterval(() => {
 						void load(false);
 					}, USAGE_POLL_MS);
@@ -970,7 +1026,7 @@ window.__ModuleLoader__.load({
 		function WebSearchCard(props) {
 			const { t, state, actions } = props;
 			if (!state.available) return null;
-			const disabled = !state.writable;
+			const disabled = !state.writable || state.saving;
 			const provider = state.provider.text === "tavily" || state.provider.text === "brave" || state.provider.text === "deepseek-official" || builtinRest(state.provider.text) !== void 0 ? state.provider.text : "deepseek-official";
 			const brave = provider === "brave";
 			const deepseek = provider === "deepseek-official";
@@ -984,6 +1040,7 @@ window.__ModuleLoader__.load({
 				t,
 				overridden: state[field]?.overridden === true,
 				invalid: state[field]?.invalid === true,
+				errorKey: field.endsWith("ApiKeyEnv") || field === "apiKeyEnv" ? "invalidCredentialRef" : "invalidNumber",
 				disabled,
 				onReset: () => actions.resetField(field)
 			});
@@ -1008,9 +1065,9 @@ window.__ModuleLoader__.load({
 				!state.writable ? react.createElement("p", { className: "dshws_field_hint", style: { padding: "8px 0 0" } }, t("readOnly")) : null,
 				pair(
 					row("provider", t("provider"), null, selectInput({ id: "ws-provider", value: provider, disabled, onChange: (e) => actions.edit("provider", e.target.value), children: [
+						react.createElement("option", { value: "deepseek-official", key: "deepseek-official" }, t("providerDeepseek")),
 						react.createElement("option", { value: "tavily", key: "tavily" }, t("providerTavily")),
 						react.createElement("option", { value: "brave", key: "brave" }, t("providerBrave")),
-						react.createElement("option", { value: "deepseek-official", key: "deepseek-official" }, t("providerDeepseek")),
 						...BUILTIN_REST_PROVIDERS.map((entry) => react.createElement("option", { value: entry.id, key: entry.id }, entry.name)),
 						react.createElement("option", { value: "__ddg__", key: "ddg", disabled: true }, t("ddgDisabled"))
 					] }),
@@ -1021,16 +1078,17 @@ window.__ModuleLoader__.load({
 					] })) : null
 				),
 				react.createElement(QuotaCard, { t, provider, keyed }),
+				keyConsoleLink(t, provider, restMeta, keyed),
 				deepseek ? pair(
-					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-deepseek-key", value: state.deepseekApiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(DEEPSEEK_API_KEY_FIELD, e.target.value) })),
+					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-deepseek-key", value: state.deepseekApiKey.text, disabled: disabled || !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(DEEPSEEK_API_KEY_FIELD, e.target.value) })),
 					row("deepseekApiKeyEnv", t("deepseekApiKeyEnv"), t("deepseekApiKeyEnvHint"), textInput({ id: "ws-deepseek-keyref", value: state.deepseekApiKeyEnv.text, disabled, onChange: (e) => actions.edit("deepseekApiKeyEnv", e.target.value) }))
 				) : null,
 				brave ? pair(
-					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-brave-key", value: state.braveApiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(BRAVE_API_KEY_FIELD, e.target.value) })),
+					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-brave-key", value: state.braveApiKey.text, disabled: disabled || !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(BRAVE_API_KEY_FIELD, e.target.value) })),
 					row("braveApiKeyEnv", t("braveApiKeyEnv"), t("braveApiKeyEnvHint"), textInput({ id: "ws-brave-keyref", value: state.braveApiKeyEnv.text, disabled, onChange: (e) => actions.edit("braveApiKeyEnv", e.target.value) }))
 				) : null,
 				(tavily && keyed) ? pair(
-					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-tavily-key", value: state.apiKey.text, disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(TAVILY_API_KEY_FIELD, e.target.value) })),
+					fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-tavily-key", value: state.apiKey.text, disabled: disabled || !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(TAVILY_API_KEY_FIELD, e.target.value) })),
 					row("apiKeyEnv", t("apiKeyEnv"), t("apiKeyEnvHint"), textInput({ id: "ws-tavily-keyref", value: state.apiKeyEnv.text, disabled, onChange: (e) => actions.edit("apiKeyEnv", e.target.value) }))
 				) : null,
 				deepseek ? row("deepseekBaseURL", t("deepseekBaseURL"), t("deepseekBaseURLHint"), textInput({ id: "ws-deepseek-base", value: state.deepseekBaseURL.text, disabled, onChange: (e) => actions.edit("deepseekBaseURL", e.target.value) })) : null,
@@ -1075,15 +1133,8 @@ window.__ModuleLoader__.load({
 				brave ? row("proxy", t("proxy"), null, textInput({ id: "ws-proxy", value: state.proxy.text, disabled, placeholder: t("proxyPlaceholder"), onChange: (e) => actions.edit("proxy", e.target.value) })) : null,
 				deepseek ? maxResultsRow : null,
 				restMeta ? react.createElement("div", { className: "dshws_form" },
-					restMeta.keyRequired && restMeta.officialUrl ? react.createElement("a", {
-						href: restMeta.officialUrl,
-						target: "_blank",
-						rel: "noopener noreferrer",
-						className: "dshws_field_hint",
-						style: { color: "var(--dsw-alias-brand-primary,#3b82f6)", textDecoration: "none", padding: "8px 0", display: "inline-block" }
-					}, t("getKey") + " ↗") : null,
 					restMeta.keyRequired ? pair(
-						fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-" + restMeta.id + "-key", value: state[restMeta.keyField]?.text ?? "", disabled: !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(restMeta.keyField, e.target.value) })),
+						fieldRow(t("apiKey"), keyHint, secretInput({ id: "ws-" + restMeta.id + "-key", value: state[restMeta.keyField]?.text ?? "", disabled: disabled || !state.apiKeyWritable, placeholder: state.apiKeyConfigured ? t("apiKeySet") : t("apiKeyUnset"), onChange: (e) => actions.edit(restMeta.keyField, e.target.value) })),
 						row(restMeta.keyEnvField, t("apiKeyEnv"), t("apiKeyEnvHint"), textInput({ id: "ws-" + restMeta.id + "-keyref", value: state[restMeta.keyEnvField]?.text ?? "", disabled, onChange: (e) => actions.edit(restMeta.keyEnvField, e.target.value) }))
 					) : null,
 					row(restMeta.baseURLField, t("baseURL"), t("baseURLHint"), textInput({ id: "ws-" + restMeta.id + "-base", value: state[restMeta.baseURLField]?.text || restMeta.defaultBaseURL || "", disabled, onChange: (e) => actions.edit(restMeta.baseURLField, e.target.value) })),
@@ -1112,17 +1163,37 @@ window.__ModuleLoader__.load({
 		}
 
 		/** Section component: the "Web search" page body, driven by useSyncExternalStore. */
-		function makeSection(ctx, controller) {
+		function makeSection(ctx) {
 			return function WebSearchSection() {
-				const state = react.useSyncExternalStore(controller.store.subscribe, controller.store.getSnapshot);
-				const t = ctx.locale.bind(NS);
-				if (!state.available) return react.createElement("p", { style: { padding: "16px" } }, t("readOnly"));
+				if (shared.controller === null) return null;
 				return react.createElement("div", { style: { padding: "16px" } },
-					react.createElement("div", { style: { border: "1px solid var(--dsw-alias-border-l2)", background: "var(--dsw-alias-bg-layer-3)", borderRadius: "12px", padding: "4px 16px" } },
-						react.createElement(WebSearchCard, { t: t, state: state, actions: controller.form.actions() })));
+					react.createElement(WebSearchConfigCard, { ctx: ctx }));
 			};
 		}
 
+		/**
+		 * The settings card controller, or `null` when the Host does not serve
+		 * this namespace.
+		 * @type {{controller: SearchCardController | null}}
+		 */
+		const shared = { controller: null };
+
+		/**
+		 * The configuration card reads the shared controller's store and draws
+		 * the bordered panel in the settings section.
+		 * @param props - `ctx` for locale binding.
+		 * @returns the card element, or null while the namespace is unserved.
+		 */
+		function WebSearchConfigCard(props) {
+			const controller = shared.controller;
+			if (controller === null) return null;
+			const state = react.useSyncExternalStore(controller.store.subscribe, controller.store.getSnapshot);
+			const t = props.ctx.locale.bind(NS);
+			if (!state.available) return react.createElement("p", { style: { padding: "16px" } }, t("readOnly"));
+			return react.createElement("div", { style: { border: "1px solid var(--dsw-alias-border-l2)", background: "var(--dsw-alias-bg-layer-3)", borderRadius: "12px", padding: "4px 16px" } },
+				react.createElement(WebSearchCard, { t: t, state: state, actions: controller.form.actions() }));
+		}
+
 		function syncSettingsNavIcon() {
 			if (typeof document === "undefined" || typeof document.querySelectorAll !== "function") return;
 			const lists = document.querySelectorAll("[class*='_navList']");
@@ -1149,26 +1220,43 @@ window.__ModuleLoader__.load({
 			return () => observer.disconnect();
 		}
 
-		/** Mount the top-level "Web search" settings section. */
 		function apply(ctx) {
 			const t = ctx.locale.bind(NS);
 			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-web-search-plugin: card dictionaries");
-			const controller = new SearchCardController(ctx.settingsScope.bind({ namespace: NS }), ctx.remote);
-			ctx.effect(() => ctx.remote.$on("credentials/reference-updated", (ref) => {
-				controller.form.refreshCredential(ref);
-			}), "dsh-web-search-plugin: credential invalidations");
-			ctx.effect(() => usageStore.start(), "dsh-web-search-plugin: usage poll");
-			ctx.effect(() => startSettingsNavIconSync(), "dsh-web-search-plugin: settings nav icon");
-			ctx.slots.inject("settings.section", () => ctx.slots.register({
-				name: "settings.section",
-				id: "web-search",
-				order: 10,
-				label: () => t("nav"),
-				locale: NS
-			}, makeSection(ctx, controller)));
+
+			// One controller for the settings section, created as soon as the Host
+			// serves this namespace and torn down with it.
+			ctx.effect(() => ctx.configForms.whileServed([NS], () => {
+				shared.controller = new SearchCardController(ctx.configForms.get(NS), ctx.remote);
+				const stopUsage = usageStore.start();
+				const stopCredentials = ctx.remote.$on("credentials/reference-updated", (ref) => {
+					shared.controller?.form.refreshCredential(ref);
+				});
+				const stopNavIcon = startSettingsNavIconSync();
+				// The navigation entry belongs to the same lifetime as its Host form.
+				let stopSection = () => {};
+				const sectionFiber = ctx.slots.inject("settings.section", () => {
+					stopSection = ctx.slots.register({
+						name: "settings.section",
+						id: "web-search",
+						order: 10,
+						label: () => t("nav"),
+						locale: NS
+					}, makeSection(ctx));
+					return stopSection;
+				});
+				return () => {
+					shared.controller = null;
+					stopUsage();
+					stopCredentials();
+					stopNavIcon();
+					stopSection();
+					void sectionFiber.dispose();
+				};
+			}), "dsh-web-search-plugin: forms");
 		}
 
-		const inject = ["slots", "locale", "remote", "remote.credentials", "settingsScope"];
+		const inject = ["slots", "locale", "remote", "remote.credentials", "configForms"];
 
 		exports.apply = apply;
 		exports.inject = inject;