@lmzhen/dsh-evolution-settings-ui 0.7.0 → 0.8.0

package/README.md

@@ -16,12 +16,20 @@ The cards claim the keyed child slot per namespace, so a namespace the Host does
 
 ## What a card does
 
-A card renders the namespace's user-writable (E3) fields with the registry's Chinese label, its unit, a 用户/部署 source chip, a control **typed from the registry** (switch / select / number / text) holding the current value, the registry's hint, and a per-field 恢复部署默认 action when a user override exists. The card's foot carries one 放弃修改 / 保存 pair: edits live in a draft, 保存 writes only the dirty fields in order and clears the draft on success. Success is decided by READING BACK the raw user section — the client settings scope resolves a refused write (it recovers the snapshot and returns; the remote call never rejects), so a field the Host refused simply leaves no user key. When that happens the card reports it under the fields and keeps the draft, so nothing the operator typed is lost and a refusal never looks like a silent revert.
+A card renders the namespace's user-writable (E3) fields with the registry's Chinese label, its unit, a 用户/部署 source chip, a control **typed from the registry** (switch / select / number / text) holding the current value, the registry's hint, and a per-field 恢复部署默认 action when a user override exists. The card's foot carries one 放弃修改 / 保存 pair: edits live in a draft, 保存 writes only the dirty fields in order, and a settling effect clears the draft once the Host kept every written key.
+
+Success is never assumed from the write call: the client settings scope RESOLVES a refused write (it recovers the snapshot and returns; the remote call never rejects). Both scopes this bundle runs on — the platform's own controller and the bridge variant — finish that recovery read BEFORE the write promise resolves, so the raw user section read in the settling effect is already the verdict: a field the Host refused leaves no user key. The card then reports the refusal under the fields and keeps the draft, so nothing the operator typed is lost and a refusal never looks like a silent revert. The verdict cannot be read from the save callback itself: the raw snapshot is reachable only through the render-time seat (see the next section).
 
 Writes go through the client settings scope (`set`/`unset`), which carries the revision it read as the write's fence; a field whose key is present in the raw user section reads as a user override even when its value equals the deployment value.
 
 The field list AND the per-field UI metadata are GENERATED from the parameter registry (`packages/scripts/gen-param-client-view.mjs` writes `src/client/generated-params.ts`): id, group, the English summary, and the E3 rows' label / hint / control / unit / values. The browser half therefore cannot name a parameter the Host does not register, and cannot invent a control the registry does not declare. Regenerate after every registry edit; the family gate runs the generator with `--check`.
 
+## The `hooks` compartment never reaches the component
+
+A card's inject face carries `hooks: { paramSection: source }` — that is the SHELL's seat, not a prop. The renderer binds each entry to a `use<Name>` seat and hands the component the face with `hooks` REMOVED (the slot contract is `PropsHooks<face['hooks']>` plus `Omit<face, 'hooks'>`). Reading `props.hooks` therefore reads a prop that never exists, and the failure only shows up at runtime, inside the save path.
+
+The props type is spelled the way the renderer derives it — `Omit<ParamCardFace, 'hooks'> & { useParamSection }` — so re-introducing that mistake fails `tsc` instead of failing the operator's save. 0.7.0 shipped the mistake; 0.7.1 fixed it and derived the type this way.
+
 ## Styling
 
 The design system's CSS is not exported to packages outside the platform repository, so this bundle carries its own stylesheet and injects it once behind a `<style data-plugin-css="…">` tag — the mechanism the platform's own client bundles use. Every rule reads a `--dsw-alias-*` design token, so light and dark follow the theme without a colour of our own, and the field metrics (12px padding, 6px gap, 13px label, 12px hint) copy the platform's settings fields.
@@ -40,3 +48,4 @@ The browser half ships as the client module system's lazy CJS factory artifact (
 - The section renders plain controls styled with the design tokens rather than the platform's `@deepseek-ai/dsh-client-ui-primitives` kit: that module IS available to out-of-repo bundles (the market plugin requires it), but its prop shapes are not published, and guessing them would break the live GUI.
 - An unsaved draft lives in the card's own component state and the settings shell renders only the active section, so switching to another section drops a draft that was not saved yet. Values already written are unaffected; moving the draft into an apply-time store is the 0.7.x follow-up.
 - A deployment that overrides a field through the `evolution-policy` row does not show on the card: the card reports the deployment value the settings scope serves, while the policy snapshot can differ. That divergence stays a doctor / `/evolution params` matter.
+- The browser half has no rendered spec: the family specs are Node-level, so this package's client code is covered by `tsc`, the bundle build and the gate steps, plus a live pass on the installed artifact (0.7.0's save defect was found exactly there). A spec that renders the card with the props the renderer actually builds — no `hooks`, the bound seat stubbed — is the follow-up that catches this verdict path in CI.

package/lib/client.js

@@ -435,6 +435,29 @@ window.__ModuleLoader__.load({
 			return language === "zh" ? zh[key] : en[key];
 		}
 		//#endregion
+		//#region src/client/settle.ts
+		/**
+		* Structural equality for the values a parameter can hold.
+		* @param a - one side of the comparison.
+		* @param b - the other side.
+		* @returns true when the two are the same value.
+		*/
+		function sameValue(a, b) {
+			if (Object.is(a, b)) return true;
+			if (typeof a !== typeof b || a === null || b === null) return false;
+			return JSON.stringify(a) === JSON.stringify(b);
+		}
+		/**
+		* Whether every staged write is visible in the user layer.
+		* @param pending - the writes awaiting a verdict.
+		* @param user - the user layer of the post-write snapshot; a non-section reads as empty.
+		* @returns true when each staged id now holds the value that was requested.
+		*/
+		function landedWrites(pending, user) {
+			const section = typeof user === "object" && user !== null && !Array.isArray(user) ? user : {};
+			return pending.every((entry) => sameValue(section[entry.id], entry.want));
+		}
+		//#endregion
 		//#region src/client/ParamCard.ts
 		/**
 		* One namespace's parameter card.
@@ -481,12 +504,6 @@ window.__ModuleLoader__.load({
 		function isSection(value) {
 			return typeof value === "object" && value !== null && !Array.isArray(value);
 		}
-		/** Let the settings store settle one write before the read-back (it batches updates). */
-		async function settle() {
-			await new Promise((done) => {
-				setTimeout(done, 60);
-			});
-		}
 		/** One field's control, typed from the registry. */
 		function FieldControl(props) {
 			const { field, text } = props;
@@ -554,12 +571,14 @@ window.__ModuleLoader__.load({
 			const [draft, setDraft] = (0, react.useState)({});
 			const [busy, setBusy] = (0, react.useState)(false);
 			const [error, setError] = (0, react.useState)("");
+			const [pending, setPending] = (0, react.useState)(null);
 			const snapshot = props.useParamSection((state) => state);
 			if (snapshot.status === "loading") return (0, react.createElement)("p", { className: "evolution-param-note" }, t("loading"));
 			if (snapshot.status === "unavailable") return (0, react.createElement)("p", { className: "evolution-param-note" }, t("unavailable"));
 			const user = isSection(snapshot.user) ? snapshot.user : {};
 			const value = isSection(snapshot.value) ? snapshot.value : {};
 			const disabled = !snapshot.writable;
+			const locked = disabled || busy;
 			const titleKey = NAMESPACE_TITLES[namespace];
 			const title = titleKey === void 0 ? namespace : t(titleKey);
 			const changed = fields.filter((field) => Object.hasOwn(user, field.id)).length;
@@ -571,27 +590,43 @@ window.__ModuleLoader__.load({
 					[id]: next
 				});
 			};
+			/**
+			* Settle a staged write against the Host's answer.
+			*
+			* A resolved write promise is not the verdict: both settings scopes this bundle runs
+			* on (the shell's own controller and the bridge variant) finish their recovery read
+			* BEFORE it resolves, so a value the Host refused is simply still the previous one.
+			* Presence in the user layer therefore cannot answer the question — on a field the
+			* operator had already overridden, a refused value's key is present as well. The
+			* verdict asks whether each staged id now holds the value this card requested.
+			* The check lives in an effect, not in the save callback, because the raw snapshot is
+			* reachable only through the render-time seat — the face's `hooks` compartment never
+			* reaches the component.
+			*/
+			(0, react.useEffect)(() => {
+				if (pending === null) return;
+				setPending(null);
+				setBusy(false);
+				if (landedWrites(pending, snapshot.user)) setDraft({});
+				else setError(t("refused"));
+			}, [
+				pending,
+				snapshot.user,
+				t
+			]);
 			const save = () => {
 				setBusy(true);
 				setError("");
 				(async () => {
 					try {
 						for (const field of dirty) await write(field.id, parseFor(field.control, textOf(field)));
-						let landed = isSection(props.hooks.paramSection.getSnapshot().user) ? props.hooks.paramSection.getSnapshot().user : {};
-						for (let attempt = 0; attempt < 4 && dirty.some((field) => !Object.hasOwn(landed, field.id)); attempt += 1) {
-							await settle();
-							const fresh = props.hooks.paramSection.getSnapshot();
-							landed = isSection(fresh.user) ? fresh.user : {};
-						}
-						if (dirty.some((field) => !Object.hasOwn(landed, field.id))) {
-							setError(t("refused"));
-							return;
-						}
-						setDraft({});
+						setPending(dirty.map((field) => ({
+							id: field.id,
+							want: parseFor(field.control, textOf(field))
+						})));
 					} catch (caught) {
-						setError(caught instanceof Error && caught.message !== "" ? caught.message : t("refused"));
-					} finally {
 						setBusy(false);
+						setError(caught instanceof Error && caught.message !== "" ? caught.message : t("refused"));
 					}
 				})();
 			};
@@ -607,7 +642,7 @@ window.__ModuleLoader__.load({
 				field,
 				text: textOf(field),
 				overridden: Object.hasOwn(user, field.id),
-				disabled,
+				disabled: locked,
 				t,
 				onChange: change,
 				clear

package/lib/types/client/ParamCard.d.ts

@@ -17,7 +17,14 @@ import { type ReactNode } from 'react';
 import type { ClientParamField } from './generated-params.ts';
 import { type MessageKey } from './messages.ts';
 import type { ParamSectionSnapshot, ParamSectionSource } from './seam.ts';
-/** Injected face: plain data and callbacks, plus the hook seat. */
+/**
+ * Injected face: plain data and callbacks, plus the hook seat.
+ *
+ * The `hooks` compartment belongs to the shell, not to the component: the
+ * renderer binds its entries to `use<Name>` props and omits `hooks` from what
+ * the component receives. A card that reads `props.hooks` therefore reads a prop
+ * that never exists.
+ */
 export interface ParamCardFace {
     namespace: string;
     fields: readonly ClientParamField[];
@@ -28,8 +35,12 @@ export interface ParamCardFace {
         paramSection: ParamSectionSource;
     };
 }
-/** Props the renderer binds for one card: the inject face plus its hook seat. */
-export type ParamCardProps = ParamCardFace & {
+/**
+ * Props the renderer binds for one card: the inject face minus its hook compartment,
+ * plus the seats bound from it. Spelled the way the shell derives it, so reaching for
+ * `props.hooks` fails the type check instead of failing at runtime.
+ */
+export type ParamCardProps = Omit<ParamCardFace, 'hooks'> & {
     /** Bound from \`hooks.paramSection\` by the renderer. */
     readonly useParamSection: <T>(selector: (state: ParamSectionSnapshot) => T) => T;
 };

package/lib/types/client/settle.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The save verdict: did the Host take the values this card asked for?
+ *
+ * A write promise that resolves is not a verdict. Both settings scopes this bundle runs
+ * on finish a recovery read before it resolves, so a value the Host refused is simply
+ * still the previous one. Presence in the user layer cannot tell refusal from acceptance
+ * on a field the operator had already overridden — the refused value's key is present
+ * too — so the verdict compares what each staged id holds now against what was requested.
+ * @module @lmzhen/dsh-evolution-settings-ui
+ */
+/** One staged write awaiting its verdict. */
+export interface PendingWrite {
+    /** Parameter id the write named. */
+    readonly id: string;
+    /** The value handed to the scope's `set`. */
+    readonly want: unknown;
+}
+/**
+ * Whether every staged write is visible in the user layer.
+ * @param pending - the writes awaiting a verdict.
+ * @param user - the user layer of the post-write snapshot; a non-section reads as empty.
+ * @returns true when each staged id now holds the value that was requested.
+ */
+export declare function landedWrites(pending: readonly PendingWrite[], user: unknown): boolean;
+//# sourceMappingURL=settle.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-settings-ui",
   "description": "Web settings cards for the evolution family's parameter namespaces (community build)",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },