dsh-model-input-toggle 0.0.0-stage → 1.0.0

package/tools/test-client.mjs

@@ -0,0 +1,954 @@
+/**
+ * dsh-model-input-toggle — client-half render test.
+ *
+ * WHAT THIS PROVES
+ * ----------------
+ * The client bundle is plain CJS wrapped in `window.__ModuleLoader__.load({...})`
+ * and is never transpiled, so a syntax-valid file can still be dead on arrival
+ * (a bad `require` target, JSX left in, an import statement, a slot key the
+ * owner never dispatches). This harness supplies a fake `__ModuleLoader__`, a
+ * minimal React implementation with a working hook dispatcher, and a fake slot
+ * service, then renders the REAL registration tree and drives the checkbox.
+ *
+ * React itself is not installed alongside a renderer here, so the "React" below
+ * is a small stand-in implementing exactly the API surface the bundle uses
+ * (createElement, useState, useEffect, useMemo-free). Hook ORDER and the effect
+ * lifecycle are honoured, which is what makes the optimistic-update and
+ * rollback paths testable.
+ *
+ * Run: node tools/test-client.mjs
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+	try {
+		await fn();
+		passed += 1;
+		process.stdout.write(`  ok   ${name}\n`);
+	} catch (error) {
+		failed += 1;
+		process.stdout.write(`  FAIL ${name}\n       ${String(error?.message ?? error).replace(/\n/g, "\n       ")}\n`);
+	}
+}
+
+function assert(condition, message) {
+	if (!condition) throw new Error(`assertion failed: ${message}`);
+}
+
+function assertEqual(actual, expected, label) {
+	if (actual !== expected) throw new Error(`${label}: got ${JSON.stringify(actual)}, expected ${JSON.stringify(expected)}`);
+}
+
+// ── a minimal React with real hook semantics ───────────────────────────────
+
+/**
+ * Create a React stand-in. `render` walks the element tree, maintaining a hook
+ * cursor per component instance so useState/useEffect behave as they do in the
+ * real thing (state persists across re-renders, effects run after commit).
+ */
+function createReact() {
+	let current = null; // { hooks, cursor }
+	const pendingEffects = [];
+
+	function createElement(type, props, ...children) {
+		const flat = [];
+		const push = (child) => {
+			if (child === null || child === undefined || child === false || child === true) return;
+			if (Array.isArray(child)) {
+				child.forEach(push);
+				return;
+			}
+			flat.push(child);
+		};
+		children.forEach(push);
+		return { type, props: { ...(props ?? {}), children: flat.length === 1 ? flat[0] : flat } };
+	}
+
+	function useHook(initial) {
+		const instance = current;
+		const index = instance.cursor;
+		instance.cursor += 1;
+		if (instance.hooks.length <= index) {
+			instance.hooks[index] = { value: typeof initial === "function" ? initial() : initial };
+		}
+		return instance.hooks[index];
+	}
+
+	function useState(initial) {
+		const hook = useHook(initial);
+		const setter = (next) => {
+			const resolved = typeof next === "function" ? next(hook.value) : next;
+			if (Object.is(resolved, hook.value)) return;
+			hook.value = resolved;
+			hook.dirty = true;
+		};
+		return [hook.value, setter];
+	}
+
+	function useEffect(effect, deps) {
+		const hook = useHook(undefined);
+		const previous = hook.deps;
+		const changed = previous === undefined || deps === undefined
+			|| deps.length !== previous.length
+			|| deps.some((value, index) => !Object.is(value, previous[index]));
+		if (!changed) return;
+		hook.deps = deps;
+		if (typeof hook.cleanup === "function") hook.cleanup();
+		hook.cleanup = undefined;
+		hook.pending = effect;
+		pendingEffects.push(hook);
+	}
+	return {
+		createElement,
+		useState,
+		useEffect,
+		/** Test hook: set the component instance whose hooks are being read. */
+		__setCurrent(instance) {
+			current = instance;
+		},
+		__createInstance() {
+			return { hooks: [], cursor: 0 };
+		},
+		/** Run effects scheduled during the last render pass. */
+		__flushEffects() {
+			while (pendingEffects.length > 0) {
+				const hook = pendingEffects.shift();
+				const effect = hook.pending;
+				hook.pending = undefined;
+				if (effect !== undefined) hook.cleanup = effect() ?? undefined;
+			}
+		}
+	};
+}
+
+// ── the loader + slot harness ──────────────────────────────────────────────
+
+const REACT = createReact();
+
+/**
+ * Load lib/client.js into a fake browser-ish global and return everything the
+ * test needs to inspect and drive the registration.
+ *
+ * `options.setTimeout` overrides the timer the bundle captures, so a test can
+ * fire the bundle's own 10s request timeout deterministically.
+ */
+function loadClient(options = {}) {
+	const source = readFileSync(join(here, "..", "lib", "client.js"), "utf8");
+	const loaded = [];
+	const listeners = new Set();
+	const styles = [];
+	const registered = [];
+	const injected = [];
+
+	const previousWindow = globalThis.window;
+	const previousDocument = globalThis.document;
+	const previousSetTimeout = globalThis.setTimeout;
+
+	const fakeDocument = {
+		head: {
+			appendChild(node) {
+				styles.push(node);
+			}
+		},
+		createElement(tag) {
+			return {
+				tagName: tag,
+				attributes: {},
+				setAttribute(name, value) {
+					this.attributes[name] = value;
+				},
+				parentNode: null
+			};
+		},
+		addEventListener() {},
+		removeEventListener() {}
+	};
+
+	// window.localStorage is intentionally absent here so the "storage blocked"
+	// path is exercised; a test can install one.
+	const fakeWindow = {
+		__ModuleLoader__: {
+			load(definition) {
+				loaded.push(definition);
+			}
+		},
+		// Tests install a localStorage here BEFORE the bundle reads it.
+		localStorage: options.localStorage
+	};
+
+	globalThis.window = fakeWindow;
+	globalThis.document = fakeDocument;
+	// A controllable timer: tests may replace it to fire the bundle's own timeouts.
+	const timers = [];
+	globalThis.setTimeout = options.setTimeout ?? ((fn, ms) => {
+		const handle = { fn, ms, cleared: false };
+		timers.push(handle);
+		return handle;
+	});
+	globalThis.clearTimeout = (handle) => {
+		if (handle !== undefined && handle !== null) handle.cleared = true;
+	};
+
+	try {
+		// The bundle is a script: evaluate it with `window` in scope.
+		const evaluator = new Function("window", "document", "setTimeout", "clearTimeout", "console", "fetch", "AbortController", source);
+		evaluator(fakeWindow, fakeDocument, globalThis.setTimeout, globalThis.clearTimeout, console, globalThis.fetch, globalThis.AbortController);
+	} finally {
+		globalThis.window = previousWindow;
+		globalThis.document = previousDocument;
+		globalThis.setTimeout = previousSetTimeout;
+	}
+
+	const definition = loaded[0];
+	if (definition === undefined) throw new Error("the bundle never called window.__ModuleLoader__.load");
+
+	// The factory returns its own `module.exports` directly.
+	const exportsObject = definition.factory((id) => {
+		if (id === "react") return REACT;
+		throw new Error(`the client bundle required an unexpected module: ${id}`);
+	});
+	if (typeof exportsObject?.apply !== "function") {
+		throw new Error("the client bundle did not export an apply() function");
+	}
+
+	// A fake slots service recording inject/register, as the shell would.
+	const ctx = {
+		effect(callback, label) {
+			const disposer = callback();
+			return disposer ?? (() => void label);
+		},
+		slots: {
+			inject(slotName, callback) {
+				injected.push(slotName);
+				callback();
+			},
+			register(contract, Component) {
+				registered.push({ contract, Component });
+				return () => void 0;
+			}
+		}
+	};
+	exportsObject.apply(ctx);
+
+	return {
+		module: { exports: exportsObject },
+		definition,
+		ctx,
+		injected,
+		registered,
+		styles,
+		timers,
+		listeners
+	};
+}
+
+/**
+ * Render one element tree to a plain node structure, so a test can assert on
+ * what the user would see. Children render inline; only function components
+ * recurse (and get hook instances).
+ */
+function renderToTree(element, instances = new Map()) {
+	if (element === null || element === undefined || element === false) return null;
+	if (typeof element === "string" || typeof element === "number") return { text: String(element) };
+	if (Array.isArray(element)) return { children: element.map((child) => renderToTree(child, instances)).filter(Boolean) };
+
+	const { type, props } = element;
+	if (typeof type === "function") {
+		let instance = instances.get(type);
+		if (instance === undefined) {
+			instance = REACT.__createInstance();
+			instances.set(type, instance);
+		}
+		// A fresh element identity re-runs the component body, as a re-render would.
+		instance.cursor = 0;
+		REACT.__setCurrent(instance);
+		const output = type(props);
+		return renderToTree(output, instances);
+	}
+	const children = [];
+	const raw = props.children;
+	if (Array.isArray(raw)) {
+		for (const child of raw) {
+			const node = renderToTree(child, instances);
+			if (node !== null) children.push(node);
+		}
+	} else if (raw !== undefined && raw !== null) {
+		const node = renderToTree(raw, instances);
+		if (node !== null) children.push(node);
+	}
+	return { type, props, children, instances };
+}
+
+/** Collect every rendered node matching a predicate. */
+function collect(node, predicate, out = []) {
+	if (node === null || node === undefined) return out;
+	if (predicate(node)) out.push(node);
+	if (Array.isArray(node.children)) node.children.forEach((child) => collect(child, predicate, out));
+	return out;
+}
+
+/** Find the text of every node under `node`, concatenated. */
+function textOf(node) {
+	if (node === null || node === undefined) return "";
+	if (node.text !== undefined) return node.text;
+	if (!Array.isArray(node.children)) return "";
+	return node.children.map(textOf).join("");
+}
+
+/** Find an input element whose aria-label contains `needle`. */
+function findCheckbox(node, needle) {
+	const matches = collect(node, (candidate) => candidate.type === "input"
+		&& candidate.props.type === "checkbox"
+		&& String(candidate.props["aria-label"] ?? "").includes(needle));
+	return matches[0];
+}
+
+/**
+ * Let every pending promise chain and timer callback run to completion, so a
+ * fetch the bundle started during render (or in a click handler) has settled
+ * before the test asserts on the re-rendered tree.
+ */
+async function settle() {
+	for (let i = 0; i < 5; i += 1) {
+		await new Promise((resolve) => setImmediate(resolve));
+	}
+}
+
+/**
+ * Paint the panel and settle it WITHOUT expanding — the exact view a user gets
+ * when the settings page first opens. Use this to assert the collapsed default.
+ */
+async function paintCollapsed(panel, element, instances) {
+	const map = instances ?? new Map();
+	renderToTree(element, map);
+	REACT.__flushEffects();
+	await settle();
+	const settled = renderToTree(element, map);
+	REACT.__flushEffects();
+	await settle();
+	return settled;
+}
+
+/**
+ * Find the panel's collapse toggle in a painted tree, if it has one. Returns
+ * undefined when the panel rendered nothing expandable (absent provider, still
+ * loading, or a header carrying only an error).
+ */
+function findToggle(tree) {
+	return collect(tree, (node) => node.type === "button"
+		&& String(node.props.className ?? "").includes("dsh-imit-toggle"))[0];
+}
+
+/**
+ * Paint the panel the way most tests need it: settled AND expanded, so the model
+ * rows are visible. The expanded state comes from clicking the real toggle, and
+ * because expansion is detected from `aria-expanded` this is safe to call again
+ * mid-test without collapsing what the test already opened.
+ */
+async function paint(panel, element, instances) {
+	const map = instances ?? new Map();
+	const collapsed = await paintCollapsed(panel, element, map);
+	const toggle = findToggle(collapsed);
+	if (toggle === undefined || toggle.props["aria-expanded"] !== "false") return collapsed;
+	toggle.props.onClick();
+	return await paintCollapsed(panel, element, map);
+}
+
+/**
+ * A Map-backed localStorage for a test to hand the bundle. `acknowledged` seeds
+ * the one-time image-input acknowledgement the confirmation dialog writes.
+ */
+function makeStorage(acknowledged) {
+	const map = new Map();
+	if (acknowledged !== undefined) map.set("dsh-model-input-toggle:acknowledged", acknowledged);
+	return {
+		map,
+		getItem: (key) => (map.has(key) ? map.get(key) : null),
+		setItem: (key, value) => map.set(key, String(value))
+	};
+}
+
+// ── test fixtures ──────────────────────────────────────────────────────────
+
+/** An inventory reply covering a pi-ai route and the deepseek route. */
+const INVENTORY = {
+	ok: true,
+	providers: [
+		{
+			router: "pi-ai",
+			namespace: "llm-pi-ai",
+			provider: "agnes",
+			displayName: "agnes",
+			ae: undefined,
+			models: [
+				{ id: "agnes-3.0-flash", name: "Agnes 3.0 Flash", effective: ["text"], source: "defaultInput", locked: false },
+				{ id: "agnes-vision", name: "agnes-vision", effective: ["text", "image"], source: "model", locked: false }
+			]
+		},
+		{
+			router: "deepseek",
+			namespace: "llm-deepseek",
+			provider: "deepseek-official",
+			displayName: "DeepSeek",
+			models: [
+				{ id: "deepseek-v4-flash-vision-exp", name: "Vision Exp", effective: ["text", "image"], source: "catalog", locked: true }
+			]
+		}
+	]
+};
+
+/**
+ * Install a scripted fetch and return a log of the requests the bundle made.
+ * The bundle is loaded with this fetch already in scope, so a test must install
+ * it before loadClient().
+ */
+function installFetch(handler) {
+	const calls = [];
+	const previous = globalThis.fetch;
+	globalThis.fetch = (url, init) => {
+		const body = init === undefined ? undefined : JSON.parse(init.body);
+		calls.push({ url, body });
+		return handler(body, calls.length - 1);
+	};
+	return {
+		calls,
+		restore() {
+			globalThis.fetch = previous;
+		}
+	};
+}
+
+/** A resolved fetch reply for one host method. */
+function replyFor(body, replies) {
+	const scripted = replies[body.method];
+	if (scripted === undefined) throw new Error(`unexpected host call: ${body.method}`);
+	const value = typeof scripted === "function" ? scripted(body) : scripted;
+	return Promise.resolve({
+		status: 200,
+		ok: true,
+		json: () => Promise.resolve(value)
+	});
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+process.stdout.write("dsh-model-input-toggle client tests\n");
+
+await test("the bundle registers one keyed cell per supported namespace", async () => {
+	const harness = loadClient();
+	assertEqual(harness.injected.length, 2, "inject call count");
+	assert(harness.injected.every((name) => name === "settings.models.provider-card"), "the injected slot is the provider card");
+	const keys = harness.registered.map((entry) => entry.contract.key).sort();
+	assertEqual(keys.join(","), "llm-deepseek,llm-pi-ai", "registered keys must be the settings namespaces");
+	for (const entry of harness.registered) {
+		assertEqual(entry.contract.name, "settings.models.provider-card", "contract name");
+	}
+});
+
+await test("the stylesheet is injected as an owned effect", async () => {
+	const harness = loadClient();
+	assertEqual(harness.styles.length, 1, "one style node");
+	const style = harness.styles[0];
+	assertEqual(style.tagName, "style", "tag");
+	assert(String(style.textContent).includes("dsh-imit-panel"), "the panel class is defined");
+	assert(String(style.textContent).includes("dsh-imit-spin"), "the spinner is defined");
+});
+
+await test("a provider with no settingsNs renders nothing", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "some-route", settingsNs: "", settingsPath: [] },
+			configured: true,
+			keyConfigured: true
+		}));
+		assert(tree === null, "no UI may be rendered for an unextendable provider");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("an unconfigured draft card renders nothing", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: false,
+			keyConfigured: false
+		}));
+		assert(tree === null, "an unsaved draft has nothing to write to");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("the panel lists the route's own models with correct initial state", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+		const tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true,
+			keyConfigured: true
+		}), instances);
+
+		const text = textOf(tree);
+		assert(text.includes("图片输入"), "the panel title is present");
+		assert(text.includes("Agnes 3.0 Flash"), "the first model is listed");
+		assert(text.includes("agnes-vision"), "the second model is listed");
+
+		// One shared inventory fetch serves the whole panel.
+		assertEqual(fetchLog.calls.length, 1, "exactly one inventory request");
+		assertEqual(fetchLog.calls[0].body.method, "list", "the request is the list method");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("only the card's own route is rendered, not every provider", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const piPanel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const dsPanel = harness.registered.find((entry) => entry.contract.key === "llm-deepseek").Component;
+
+		const piTree = textOf(await paint(piPanel, REACT.createElement(piPanel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), new Map()));
+		assert(piTree.includes("Agnes 3.0 Flash"), "the pi-ai card shows its own models");
+
+		const dsTree = textOf(await paint(dsPanel, REACT.createElement(dsPanel, {
+			provider: { provider: "deepseek-official", settingsNs: "llm-deepseek" },
+			configured: true
+		}), new Map()));
+		assert(dsTree.includes("Vision Exp"), "the deepseek card shows its own models");
+		assert(!dsTree.includes("Agnes 3.0 Flash"), "cards must not leak each other's models");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("a catalog-declared model is checked, disabled, and explained", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-deepseek").Component;
+		const tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "deepseek-official", settingsNs: "llm-deepseek" },
+			configured: true
+		}), new Map());
+
+		const box = collect(tree, (node) => node.type === "input" && node.props.type === "checkbox")[0];
+		assert(box !== undefined, "a checkbox is rendered");
+		assertEqual(box.props.checked, true, "the catalog declaration shows as checked");
+		assertEqual(box.props.disabled, true, "the catalog declaration is locked");
+		assert(textOf(tree).includes("该模型由官方目录声明"), "the lock reason is stated");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("toggling a model writes the declaration and shows a success mark", async () => {
+	const scripted = {
+		list: INVENTORY,
+		set: { ok: true, namespace: "llm-pi-ai", provider: "agnes", modelId: "agnes-3.0-flash", requested: true, declared: ["text", "image"], verified: true }
+	};
+	const fetchLog = installFetch((body) => replyFor(body, scripted));
+	try {
+		const harness = loadClient({ localStorage: makeStorage("1") });
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+
+		// With the one-time acknowledgement already stored, the toggle writes
+		// directly; the confirmation dialog itself is covered separately.
+		let tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		const box = findCheckbox(tree, "agnes-3.0-flash");
+		assert(box !== undefined, "the model's checkbox exists");
+		assertEqual(box.props.checked, false, "it starts unchecked");
+
+		box.props.onChange({ target: { checked: true } });
+		await new Promise((resolve) => process.nextTick(resolve));
+		await new Promise((resolve) => setTimeout(resolve, 0));
+
+		const setCall = fetchLog.calls.find((entry) => entry.body.method === "set");
+		assert(setCall !== undefined, "the set method must be called");
+		assertEqual(setCall.body.namespace, "llm-pi-ai", "namespace");
+		assertEqual(setCall.body.provider, "agnes", "provider is the card's route");
+		assertEqual(setCall.body.modelId, "agnes-3.0-flash", "model id");
+		assertEqual(setCall.body.supportsImage, true, "the requested value");
+
+		// Re-render and assert the immediate visual outcome.
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+		const text = textOf(tree);
+		assert(text.includes("已保存"), `a success mark is shown: ${text.slice(0, 200)}`);
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("a failed write rolls the checkbox back and shows a red error", async () => {
+	const scripted = {
+		list: INVENTORY,
+		set: { ok: false, code: "provider-missing", message: "provider \"agnes\" 不存在于 llm-pi-ai 配置中。" }
+	};
+	const fetchLog = installFetch((body) => replyFor(body, scripted));
+	try {
+		const harness = loadClient({ localStorage: makeStorage("1") });
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+
+		let tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		const box = findCheckbox(tree, "agnes-3.0-flash");
+		box.props.onChange({ target: { checked: true } });
+		await new Promise((resolve) => process.nextTick(resolve));
+		await new Promise((resolve) => setTimeout(resolve, 0));
+
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		const after = findCheckbox(tree, "agnes-3.0-flash");
+		assertEqual(after.props.checked, false, "the checkbox must roll back to its pre-action state");
+		const text = textOf(tree);
+		assert(text.includes("不存在"), `the host''s message must be shown: ${text.slice(0, 240)}`);
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("the first enable is gated by the confirmation dialog, and can be cancelled", async () => {
+	const scripted = {
+		list: INVENTORY,
+		set: { ok: true, declared: ["text", "image"], verified: true }
+	};
+	const fetchLog = installFetch((body) => replyFor(body, scripted));
+	try {
+		// No localStorage at all: the bundle must still render and must prompt.
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+		let tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		findCheckbox(tree, "agnes-3.0-flash").props.onChange({ target: { checked: true } });
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		const text = textOf(tree);
+		assert(text.includes("DSH 将不再拦截"), `the warning must be shown verbatim: ${text.slice(0, 300)}`);
+		assert(text.includes("400"), "the warning must name the failure mode");
+
+		// The write must NOT have happened yet.
+		assert(fetchLog.calls.every((entry) => entry.body.method !== "set"), "no write before confirmation");
+
+		// Cancel, then confirm.
+		const dialog = collect(tree, (node) => node.props && node.props.role === "alertdialog")[0];
+		assert(dialog !== undefined, "the dialog is present");
+		const buttons = collect(tree, (node) => node.type === "button");
+		const cancel = buttons.find((node) => textOf(node).includes("取消"));
+		const confirm = buttons.find((node) => textOf(node).includes("确认开启"));
+		assert(cancel !== undefined, "a cancel button exists");
+		assert(confirm !== undefined, "a confirm button exists");
+
+		cancel.props.onClick();
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+		assert(!textOf(tree).includes("DSH 将不再拦截"), "cancelling dismisses the dialog");
+		assert(fetchLog.calls.every((entry) => entry.body.method !== "set"), "cancelling performs no write");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("confirming the dialog performs the write once and remembers it", async () => {
+	const scripted = {
+		list: INVENTORY,
+		set: { ok: true, declared: ["text", "image"], verified: true }
+	};
+	const fetchLog = installFetch((body) => replyFor(body, scripted));
+	try {
+		const storage = makeStorage();
+		const harness = loadClient({ localStorage: storage });
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+		let tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		findCheckbox(tree, "agnes-3.0-flash").props.onChange({ target: { checked: true } });
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		const confirm = collect(tree, (node) => node.type === "button" && textOf(node).includes("确认开启"))[0];
+		confirm.props.onClick();
+		await new Promise((resolve) => process.nextTick(resolve));
+		await new Promise((resolve) => setTimeout(resolve, 0));
+
+		const setCalls = fetchLog.calls.filter((entry) => entry.body.method === "set");
+		assertEqual(setCalls.length, 1, "exactly one write after confirming");
+		assertEqual(storage.map.get("dsh-model-input-toggle:acknowledged"), "1", "the acknowledgement is persisted");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("disabling never prompts, even without an acknowledgement", async () => {
+	const starting = JSON.parse(JSON.stringify(INVENTORY));
+	starting.providers[0].models[0].effective = ["text", "image"];
+	const scripted = {
+		list: starting,
+		set: { ok: true, declared: ["text"], verified: true }
+	};
+	const fetchLog = installFetch((body) => replyFor(body, scripted));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+		let tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		const box = findCheckbox(tree, "agnes-3.0-flash");
+		assertEqual(box.props.checked, true, "starts checked");
+		box.props.onChange({ target: { checked: false } });
+		await new Promise((resolve) => process.nextTick(resolve));
+		await new Promise((resolve) => setTimeout(resolve, 0));
+
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+		assert(!textOf(tree).includes("DSH 将不再拦截"), "no confirmation for a disable");
+		const setCall = fetchLog.calls.find((entry) => entry.body.method === "set");
+		assert(setCall !== undefined, "the disabling write happened");
+		assertEqual(setCall.body.supportsImage, false, "the requested value");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("a host timeout surfaces as a connection error and rolls back", async () => {
+	// fetch never settles for `set`; the bundle's own 10s timer must fire.
+	const previousFetch = globalThis.fetch;
+	const previousSetTimeoutGlobal = globalThis.setTimeout;
+	let capturedTimer = null;
+	globalThis.fetch = (url, init) => {
+		const body = JSON.parse(init.body);
+		if (body.method === "list") {
+			return Promise.resolve({ status: 200, ok: true, json: () => Promise.resolve(INVENTORY) });
+		}
+		return new Promise(() => void 0); // set: hangs forever
+	};
+	// Hand the bundle a timer we can fire deterministically. It must be passed
+	// through loadClient, because that is what the bundle actually captures.
+	const controllableSetTimeout = (fn, ms) => {
+		if (ms === 10000) capturedTimer = fn;
+		return { fn, ms };
+	};
+	try {
+		const harness = loadClient({ localStorage: makeStorage("1"), setTimeout: controllableSetTimeout });
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+		let tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+
+		findCheckbox(tree, "agnes-3.0-flash").props.onChange({ target: { checked: true } });
+		assert(capturedTimer !== null, "the bundle must arm a 10s timeout for the write");
+		capturedTimer();
+		await new Promise((resolve) => process.nextTick(resolve));
+		await new Promise((resolve) => process.nextTick(resolve));
+
+		tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), instances);
+		const text = textOf(tree);
+		assert(text.includes("连接超时"), `the timeout message must be shown: ${text.slice(0, 240)}`);
+		assertEqual(findCheckbox(tree, "agnes-3.0-flash").props.checked, false, "rollback after timeout");
+	} finally {
+		globalThis.fetch = previousFetch;
+		globalThis.setTimeout = previousSetTimeoutGlobal;
+	}
+});
+
+await test("the 验证端点 button reports both a supported and a rejected verdict", async () => {
+	for (const scenario of [
+		{ verdict: "supported", ok: true, message: "端点接受了带图片的请求（HTTP 200）。", expect: "✓" },
+		{ verdict: "rejected", ok: true, message: "端点拒绝了图片输入（HTTP 400）。", expect: "✕" }
+	]) {
+		const scripted = {
+			list: INVENTORY,
+			verify: { ok: scenario.ok, status: 200, verdict: scenario.verdict, message: scenario.message }
+		};
+		const fetchLog = installFetch((body) => replyFor(body, scripted));
+		try {
+			const harness = loadClient();
+			const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+			const instances = new Map();
+			let tree = await paint(panel, REACT.createElement(panel, {
+				provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+				configured: true
+			}), instances);
+			REACT.__flushEffects();
+
+			const verifyButton = collect(tree, (node) => node.type === "button" && textOf(node).includes("验证端点"))[0];
+			assert(verifyButton !== undefined, "the verify button exists");
+			verifyButton.props.onClick();
+			await new Promise((resolve) => process.nextTick(resolve));
+			await new Promise((resolve) => setTimeout(resolve, 0));
+
+			tree = await paint(panel, REACT.createElement(panel, {
+				provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+				configured: true
+			}), instances);
+
+			const verifyCall = fetchLog.calls.find((entry) => entry.body.method === "verify");
+			assert(verifyCall !== undefined, "the verify method must be called");
+			assertEqual(verifyCall.body.provider, "agnes", "the verify target is the card's route");
+			const text = textOf(tree);
+			assert(text.includes(scenario.expect), `the ${scenario.verdict} verdict must be visible: ${text.slice(0, 240)}`);
+			assert(text.includes(scenario.message), "the host's message must be shown");
+		} finally {
+			fetchLog.restore();
+		}
+	}
+});
+
+await test("every rendered checkbox carries the required tooltip", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}, new Map()));
+		const labels = collect(tree, (node) => node.type === "label");
+		assertEqual(labels.length, 2, "one label per model");
+		for (const label of labels) {
+			assert(String(label.props.title).includes("勾选后该模型可接收图片消息"), `tooltip missing: ${label.props.title}`);
+			assert(String(label.props.title).includes("验证端点实际能力"), "tooltip must point at verification");
+		}
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("an inventory failure is reported with a retry action", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, {
+		list: { ok: false, code: "unreadable", message: "无法读取模型配置。" }
+	}));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const tree = await paint(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}, new Map()));
+		const text = textOf(tree);
+		assert(text.includes("无法读取模型配置"), `the error is shown: ${text.slice(0, 200)}`);
+		assert(collect(tree, (node) => node.type === "button" && textOf(node).includes("重试")).length === 1, "a retry button exists");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("the panel is collapsed by default and expands on demand", async () => {
+	const fetchLog = installFetch((body) => replyFor(body, { list: INVENTORY }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const instances = new Map();
+		const el = REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true,
+			keyConfigured: true
+		});
+
+		// Default view: one line, no model rows, no checkboxes.
+		const collapsed = await paintCollapsed(panel, el, instances);
+		assert(textOf(collapsed).includes("图片输入"), "the section is still discoverable when collapsed");
+		assertEqual(collect(collapsed, (n) => n.type === "input" && n.props.type === "checkbox").length, 0,
+			"no checkboxes are rendered while collapsed");
+		assert(!textOf(collapsed).includes("Agnes 3.0 Flash"), "model rows are hidden while collapsed");
+
+		// The collapsed summary still reports the current declaration state, so a
+		// user can tell at a glance whether anything is enabled.
+		assert(textOf(collapsed).includes("1/2 已开启"), "the summary reports how many models accept images");
+
+		const toggle = findToggle(collapsed);
+		assert(toggle !== undefined, "the toggle exists");
+		assertEqual(toggle.props["aria-expanded"], "false", "it starts collapsed");
+
+		// Expanding reveals the rows through the real handler.
+		toggle.props.onClick();
+		const open = await paintCollapsed(panel, el, instances);
+		assertEqual(findToggle(open).props["aria-expanded"], "true", "it reports expanded");
+		assert(textOf(open).includes("Agnes 3.0 Flash"), "expanding reveals the model rows");
+		assertEqual(collect(open, (n) => n.type === "input" && n.props.type === "checkbox").length, 2,
+			"expanding reveals one checkbox per model");
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+await test("a route with nothing enabled summarises as text-only", async () => {
+	const textOnly = JSON.parse(JSON.stringify(INVENTORY));
+	textOnly.providers[0].models.forEach((model) => {
+		model.effective = ["text"];
+	});
+	const fetchLog = installFetch((body) => replyFor(body, { list: textOnly }));
+	try {
+		const harness = loadClient();
+		const panel = harness.registered.find((entry) => entry.contract.key === "llm-pi-ai").Component;
+		const tree = await paintCollapsed(panel, REACT.createElement(panel, {
+			provider: { provider: "agnes", settingsNs: "llm-pi-ai" },
+			configured: true
+		}), new Map());
+		assert(textOf(tree).includes("全部仅文本"), `the summary must say nothing is enabled: ${textOf(tree)}`);
+	} finally {
+		fetchLog.restore();
+	}
+});
+
+process.stdout.write(`\n${passed} passed, ${failed} failed\n`);
+process.exit(failed === 0 ? 0 : 1);