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

package/README.md

@@ -16,11 +16,19 @@ 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. A select's option TEXT comes from the registry's optional `valueLabels`; the option VALUE stays the raw spelling the settings document stores. 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 user section read in the settling effect already reflects the outcome. Presence cannot BE the verdict: on a field the operator had already overridden, a refused value's key is present too, so the card records what it asked for (`{ id, want }` per staged write) and settles on whether the section now holds that value (`src/client/settle.ts`). A refusal then renders a line at the card's foot, below the field list, and the draft stays — 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 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 / valueLabels. 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
 
@@ -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 and the family carries no React runtime, so the card itself is covered by `tsc`, the bundle build, the gate steps and a live pass on the installed artifact (0.7.0's save defect was found exactly there). The verdict is pinned instead by `tests/settle.spec.ts` (the pure `landedWrites` decision, including the already-overridden refusal case); rendering the card with the props the renderer actually builds — no `hooks`, the bound seat stubbed — remains the follow-up that would catch the wiring in CI.

package/lib/client.js

@@ -14,121 +14,133 @@ window.__ModuleLoader__.load({
 						id: "curatorIntervalHours",
 						group: "curator",
 						doc: "Minimum hours between deterministic curation passes.",
-						label: "策展间隔",
-						hint: "两次确定性策展之间至少间隔多少小时。",
+						label: "自动整理间隔",
+						hint: "两次自动整理之间至少间隔多少小时。",
 						control: "number",
 						unit: "小时",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "staleAfterDays",
 						group: "curator",
 						doc: "Inactive days before a skill counts as stale.",
-						label: "判为陈旧的天数",
-						hint: "技能多少天没被使用即算陈旧。",
+						label: "多久没用算过时",
+						hint: "技能连续多少天没被用到就算过时。",
 						control: "number",
 						unit: "天",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "archiveAfterDays",
 						group: "curator",
 						doc: "Inactive days before a stale skill is archived (must be >= staleAfterDays).",
-						label: "归档天数",
-						hint: "陈旧技能再过多少天归档（须 ≥ 判为陈旧的天数）。",
+						label: "过时后归档",
+						hint: "过时技能再过多少天移入归档（不能小于上一项）。",
 						control: "number",
 						unit: "天",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "qualityWarnStaleAfterDays",
 						group: "curator",
 						doc: "Age at which a low quality score starts warning.",
-						label: "低质量告警天数",
-						hint: "质量分偏低时从多少天开始告警。",
+						label: "质量偏低提醒",
+						hint: "质量评分偏低时，从多少天开始提醒。",
 						control: "number",
 						unit: "天",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "minIdleHours",
 						group: "curator",
 						doc: "Idle hours required before an automatic curation pass runs.",
-						label: "空闲门槛",
-						hint: "至少空闲多少小时才跑自动策展。",
+						label: "最少空闲时长",
+						hint: "你至少多少小时没用，才运行自动整理。",
 						control: "number",
 						unit: "小时",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "minIdleFailOpen",
 						group: "curator",
 						doc: "Let the idle gate open when the activity probe is unavailable.",
-						label: "空闲探针失败时放行",
-						hint: "活动探针不可用时，是否让空闲门槛直接放行。",
+						label: "检测不到活动也运行",
+						hint: "无法判断你是否空闲时，仍然运行自动整理。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "llmReview",
 						group: "curator",
 						doc: "Enable the LLM nomination pass on top of the deterministic lifecycle.",
-						label: "启用 LLM 提名",
-						hint: "在确定性生命周期之上再跑一遍 LLM 提名。",
+						label: "用模型挑选",
+						hint: "在固定规则之外，再用模型挑一遍候选项。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "curatorReviewMaxTokens",
 						group: "curator",
 						doc: "Token budget of the curator LLM review.",
-						label: "策展 LLM token 预算",
-						hint: "策展 LLM 审查可用的 token 预算。",
+						label: "模型处理上限",
+						hint: "每次用模型挑选时最多消耗多少 token。",
 						control: "number",
 						unit: "token",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "curatorReviewTimeoutMs",
 						group: "curator",
 						doc: "Wall-clock bound of the curator LLM review.",
-						label: "策展 LLM 超时",
-						hint: "策展 LLM 审查的墙钟上限。",
+						label: "模型处理超时",
+						hint: "一次模型挑选最长允许运行多久。",
 						control: "number",
 						unit: "毫秒",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "healthSoftBodyChars",
 						group: "curator",
 						doc: "Body character line the health view judges against.",
-						label: "正文软带",
-						hint: "健康视图判定正文长度的软带。",
+						label: "正文长度参考值",
+						hint: "技能正文超过多少字符算偏长（只用于健康提示）。",
 						control: "number",
 						unit: "字符",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "healthStampDensityPerKb",
 						group: "curator",
 						doc: "Stamp density per KB that flags log-like content in a body.",
-						label: "标记密度阈值",
-						hint: "每 KB 出现多少个时间标记就算「像日志」。",
+						label: "日志化判定阈值",
+						hint: "每 KB 出现多少个时间标记，就判为「像日志」。",
 						control: "number",
 						unit: "处/KB",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "healthChurnMinPatches",
 						group: "curator",
 						doc: "Patches without a read that flag a write-ghost skill.",
-						label: "空写判定补丁数",
-						hint: "多少次改动都没有任何读取，即判为「写幽灵」。",
+						label: "只写不读判定次数",
+						hint: "连续多少次改动都没有被读取，就判为「只写不读」。",
 						control: "number",
 						unit: "处",
-						values: []
+						values: [],
+						valueLabels: []
 					}
 				]
 			},
@@ -139,41 +151,45 @@ window.__ModuleLoader__.load({
 						id: "memoryChars",
 						group: "memory",
 						doc: "Character budget the memory store enforces for MEMORY.md.",
-						label: "MEMORY.md 字符预算",
-						hint: "memory 存储对 MEMORY.md 的字符上限。",
+						label: "记忆库上限",
+						hint: "长期记忆文件（MEMORY.md）最多多少字符。",
 						control: "number",
 						unit: "字符",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "userChars",
 						group: "memory",
 						doc: "Character budget the memory store enforces for USER.md.",
-						label: "USER.md 字符预算",
-						hint: "memory 存储对 USER.md 的字符上限。",
+						label: "用户画像上限",
+						hint: "用户画像文件（USER.md）最多多少字符。",
 						control: "number",
 						unit: "字符",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "addDatePrefix",
 						group: "memory",
 						doc: "Prefix stored memory entries with their date heading.",
-						label: "记忆条目加日期前缀",
-						hint: "写入记忆时为条目加上日期标题。",
+						label: "记忆条目加日期",
+						hint: "写入时在条目开头加上日期。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "maxConsolidationFailures",
 						group: "memory",
 						doc: "Consolidation failures one turn tolerates before the tool gives up.",
-						label: "合并失败容忍次数",
-						hint: "一轮内合并失败多少次后工具放弃。",
+						label: "合并失败重试",
+						hint: "合并记忆连续失败多少次后停止。",
 						control: "number",
 						unit: "次",
-						values: []
+						values: [],
+						valueLabels: []
 					}
 				]
 			},
@@ -183,76 +199,87 @@ window.__ModuleLoader__.load({
 					{
 						id: "reviewSkillInterval",
 						group: "review",
-						doc: "Activity units between skill-review injections.",
-						label: "技能审查间隔",
-						hint: "每多少活动单位触发一次技能审查注入。",
+						doc: "Tool calls between skill-review injections: a turn advances by its tool-call count (a turn with none counts as one), or by 1 when the turn itself used a skill.",
+						label: "技能检查间隔",
+						hint: "每累计多少次工具调用检查一次技能：一轮按该轮工具调用数累加（一轮没有工具调用也算 1 次），本轮本身用到技能则只算 1 次。",
 						control: "number",
 						unit: "次",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "reviewMemoryInterval",
 						group: "review",
-						doc: "Activity units between memory-review injections.",
-						label: "记忆审查间隔",
-						hint: "每多少活动单位触发一次记忆审查注入。",
+						doc: "Tool calls between memory-review injections: a turn advances by its tool-call count (a turn with none counts as one), or by 1 when the turn itself touched memory.",
+						label: "记忆检查间隔",
+						hint: "每累计多少次工具调用检查一次记忆：一轮按该轮工具调用数累加（一轮没有工具调用也算 1 次），本轮本身用到记忆则只算 1 次。",
 						control: "number",
 						unit: "次",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "skillReviewTrigger",
 						group: "review",
 						doc: "Which channel may inject a skill review (cadence, completion, both).",
-						label: "审查触发通道",
-						hint: "哪个通道可以注入技能审查：cadence＝按间隔、completion＝按完成、both＝两者。",
+						label: "技能检查时机",
+						hint: "什么时候检查技能：按间隔／按任务完成／两者。",
 						control: "select",
 						unit: "",
 						values: [
 							"cadence",
 							"completion",
 							"both"
+						],
+						valueLabels: [
+							"按间隔",
+							"按任务完成",
+							"两者"
 						]
 					},
 					{
 						id: "skillReviewCompletionMinToolCalls",
 						group: "review",
 						doc: "Tool calls a task needs before the completion channel injects.",
-						label: "完成通道最少工具调用",
-						hint: "走完成通道时，任务至少经过多少次工具调用才注入。",
+						label: "完成时的最少工具调用",
+						hint: "选「按任务完成」时，任务至少用了几次工具才检查。",
 						control: "number",
 						unit: "次",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "reviewEnabled",
 						group: "review",
 						doc: "Master switch for the review plugin.",
-						label: "启用审查插件",
-						hint: "审查插件的总开关。",
+						label: "启用自动检查",
+						hint: "关闭后不再自动回顾会话。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "reviewMode",
 						group: "review",
 						doc: "Run the review in the parent session (inject) or on a subagent.",
-						label: "审查运行方式",
-						hint: "inject＝在父会话内注入，subagent＝交给子代理运行。",
+						label: "运行位置",
+						hint: "在哪里运行检查：在当前会话里／交给子代理。",
 						control: "select",
 						unit: "",
-						values: ["subagent", "inject"]
+						values: ["subagent", "inject"],
+						valueLabels: ["交给子代理", "在当前会话里"]
 					},
 					{
 						id: "reviewWakeInject",
 						group: "review",
 						doc: "Deliver the deferred review as a waking follow-up message.",
-						label: "审查后续唤醒注入",
-						hint: "把延后的审查作为唤醒消息投递。",
+						label: "延后结果发提醒",
+						hint: "会话空闲时，把延后的检查结果作为一条提醒发给你。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					}
 				]
 			},
@@ -263,81 +290,89 @@ window.__ModuleLoader__.load({
 						id: "skillContentChars",
 						group: "write-caps",
 						doc: "Character cap on a SKILL.md body (tighten-only).",
-						label: "SKILL.md 正文字符上限",
-						hint: "SKILL.md 正文的字符上限（只许收紧）。",
+						label: "技能文件正文上限",
+						hint: "技能 Markdown 正文最多多少字符（只能调小）。",
 						control: "number",
 						unit: "字符",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "maxSkillFileBytes",
 						group: "write-caps",
 						doc: "Byte cap on one support file (tighten-only).",
-						label: "支持文件字节上限",
-						hint: "单个支持文件的字节上限（只许收紧）。",
+						label: "附带文件大小上限",
+						hint: "技能附带文件单个最大多少字节（只能调小）。",
 						control: "number",
 						unit: "字节",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "maxSkillNameLength",
 						group: "write-caps",
 						doc: "Character cap on a skill name (tighten-only).",
-						label: "技能名字符上限",
-						hint: "技能名的字符上限（只许收紧）。",
+						label: "技能名长度上限",
+						hint: "技能名最多多少字符（只能调小）。",
 						control: "number",
 						unit: "字符",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "maxDescriptionLength",
 						group: "write-caps",
 						doc: "Character cap on a skill description (tighten-only).",
-						label: "技能描述字符上限",
-						hint: "技能描述的字符上限（只许收紧）。",
+						label: "技能描述长度上限",
+						hint: "技能描述最多多少字符（只能调小）。",
 						control: "number",
 						unit: "字符",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "descriptionStrict",
 						group: "write-caps",
 						doc: "Refuse a description over the authoring bar instead of advising.",
-						label: "描述严格档",
-						hint: "描述超过写作门槛时拒绝写入，而不是只提示。",
+						label: "描述不合规即拒绝",
+						hint: "描述不符合要求时直接拒绝写入（默认只提醒）。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "strictCrossSource",
 						group: "write-caps",
 						doc: "Refuse writes whose catalog entry resolves outside the family.",
-						label: "跨源严格档",
-						hint: "目录项解析到家族之外时拒绝写入。",
+						label: "引用外部内容即拒绝",
+						hint: "技能引用了本插件之外的文件时拒绝写入。",
 						control: "switch",
 						unit: "",
-						values: []
+						values: [],
+						valueLabels: []
 					},
 					{
 						id: "citationPolicy",
 						group: "write-caps",
 						doc: "Refuse a move that would leave a dangling reference, or verify it.",
-						label: "引用校验档",
-						hint: "移动或合并时对引用的处置：verify＝校验、refuse＝直接拒绝。",
+						label: "引用检查方式",
+						hint: "移动或合并技能时怎么处理引用：先检查／直接拒绝。",
 						control: "select",
 						unit: "",
-						values: ["verify", "refuse"]
+						values: ["verify", "refuse"],
+						valueLabels: ["先检查", "直接拒绝"]
 					},
 					{
 						id: "supportFileCharPolicy",
 						group: "write-caps",
 						doc: "Warn about an oversize support file, or refuse the write.",
-						label: "支持文件超限档",
-						hint: "支持文件超出字符上限时：report＝只报告、enforce＝拒写。",
+						label: "附带文件超限时",
+						hint: "附带文件超出上限时：只提醒／拒绝写入。",
 						control: "select",
 						unit: "",
-						values: ["report", "enforce"]
+						values: ["report", "enforce"],
+						valueLabels: ["只提醒", "拒绝写入"]
 					}
 				]
 			},
@@ -347,11 +382,12 @@ window.__ModuleLoader__.load({
 					id: "entryPreviewChars",
 					group: "memory",
 					doc: "Characters of one memory entry shown in a tool result preview.",
-					label: "条目预览字符数",
-					hint: "单条记忆预览保留多少字符。",
+					label: "记忆预览长度",
+					hint: "列表里每条记忆最多显示多少字符。",
 					control: "number",
 					unit: "字符",
-					values: []
+					values: [],
+					valueLabels: []
 				}]
 			}
 		];
@@ -372,46 +408,46 @@ window.__ModuleLoader__.load({
 		/** Chinese copy (the family's primary language). */
 		const zh = {
 			title: "自进化",
-			subtitle: "审查／记忆／策展／技能四个命名空间的参数可在用户层覆盖；此处只列可改项，其余仍由部署面决定。",
-			overridden: "用户",
-			deployment: "部署",
-			loading: "正在读取设置文档…",
-			unavailable: "这个命名空间没有宿主提供服务（对应插件行未挂载）",
-			readonly: "本次会话的设置文档是只读的（内存模式）",
+			subtitle: "下面按功能列出你能改的参数；没有列出的由安装时的配置决定。",
+			overridden: "我改过",
+			deployment: "默认",
+			loading: "正在读取设置…",
+			unavailable: "这个功能没有启动（对应的插件没有安装）",
+			readonly: "本次会话不允许写入设置（临时运行模式）",
 			apply: "保存",
-			reset: "恢复部署默认",
-			empty: "这个命名空间没有可改项",
+			reset: "恢复默认值",
+			empty: "这里没有可改项",
 			changed: "{n} 项已改",
 			discard: "放弃修改",
 			saving: "保存中…",
-			refused: "写入未被接受——宿主的校验拒绝了它（值保持原样）。原因见 /evolution params 或 /evolution doctor。",
-			cardReview: "审查",
-			cardMemory: "记忆",
-			cardToolMemory: "记忆工具",
-			cardCurator: "策展",
-			cardSkills: "技能"
+			refused: "这个值没有被接受（界面上保持原样）。想看原因：运行 /evolution params 或 /evolution doctor。",
+			cardReview: "会话回顾",
+			cardMemory: "长期记忆",
+			cardToolMemory: "记忆写入",
+			cardCurator: "技能整理",
+			cardSkills: "技能写入规则"
 		};
 		/** English copy, key for key with {@link zh}. */
 		const en = {
 			title: "Self-evolution",
-			subtitle: "Parameters of the review, memory, curation and skill namespaces may be overridden per user; only the writable ones are listed here, everything else still comes from the deployment.",
-			overridden: "user",
-			deployment: "deployment",
-			loading: "reading the settings document…",
-			unavailable: "this namespace is not served by the Host (its owning plugin row is not mounted)",
-			readonly: "the settings document is read-only in this session (memory mode)",
+			subtitle: "Changeable parameters are listed by feature below; anything not listed comes from the deployment configuration.",
+			overridden: "edited by you",
+			deployment: "default",
+			loading: "reading settings…",
+			unavailable: "this feature is not running (its plugin is not installed)",
+			readonly: "settings cannot be written in this session (temporary mode)",
 			apply: "Save",
-			reset: "Reset to deployment",
-			empty: "no writable field in this namespace",
+			reset: "Reset to default",
+			empty: "nothing to change here",
 			changed: "{n} changed",
 			discard: "Discard",
 			saving: "Saving…",
-			refused: "The write was not accepted — the Host refused it and the value is unchanged. See /evolution params or /evolution doctor for the reason.",
-			cardReview: "Review",
-			cardMemory: "Memory",
-			cardToolMemory: "Memory tools",
-			cardCurator: "Curation",
-			cardSkills: "Skills"
+			refused: "The value was not accepted (the page keeps what you see). For the reason run /evolution params or /evolution doctor.",
+			cardReview: "Session review",
+			cardMemory: "Long-term memory",
+			cardToolMemory: "Writing memory",
+			cardCurator: "Skill tidy-up",
+			cardSkills: "Skill write rules"
 		};
 		/**
 		* Card titles per settings namespace. A namespace without an entry falls back to
@@ -435,6 +471,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 +540,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;
@@ -514,10 +567,10 @@ window.__ModuleLoader__.load({
 			}, [field.values.includes(text) || text === "" ? null : (0, react.createElement)("option", {
 				key: text,
 				value: text
-			}, text), ...field.values.map((value) => (0, react.createElement)("option", {
+			}, text), ...field.values.map((value, index) => (0, react.createElement)("option", {
 				key: value,
 				value
-			}, value))]);
+			}, field.valueLabels[index] ?? value))]);
 			return (0, react.createElement)("input", {
 				...common,
 				type: field.control === "number" ? "number" : "text",
@@ -554,12 +607,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 +626,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 +678,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/generated-params.d.ts

@@ -20,6 +20,8 @@ export interface ClientParamField {
     unit: string;
     /** Allowed values for a select field ([] otherwise). */
     values: readonly string[];
+    /** Display names for `values`, same order ([] shows the raw value). */
+    valueLabels: readonly string[];
 }
 /** One card: the settings namespace plus the fields it exposes. */
 export interface ClientParamSection {

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

@@ -13,24 +13,24 @@ export declare const NS = "evolution-settings";
 /** Chinese copy (the family's primary language). */
 export declare const zh: {
     readonly title: "自进化";
-    readonly subtitle: "审查／记忆／策展／技能四个命名空间的参数可在用户层覆盖；此处只列可改项，其余仍由部署面决定。";
-    readonly overridden: "用户";
-    readonly deployment: "部署";
-    readonly loading: "正在读取设置文档…";
-    readonly unavailable: "这个命名空间没有宿主提供服务（对应插件行未挂载）";
-    readonly readonly: "本次会话的设置文档是只读的（内存模式）";
+    readonly subtitle: "下面按功能列出你能改的参数；没有列出的由安装时的配置决定。";
+    readonly overridden: "我改过";
+    readonly deployment: "默认";
+    readonly loading: "正在读取设置…";
+    readonly unavailable: "这个功能没有启动（对应的插件没有安装）";
+    readonly readonly: "本次会话不允许写入设置（临时运行模式）";
     readonly apply: "保存";
-    readonly reset: "恢复部署默认";
-    readonly empty: "这个命名空间没有可改项";
+    readonly reset: "恢复默认值";
+    readonly empty: "这里没有可改项";
     readonly changed: "{n} 项已改";
     readonly discard: "放弃修改";
     readonly saving: "保存中…";
-    readonly refused: "写入未被接受——宿主的校验拒绝了它（值保持原样）。原因见 /evolution params 或 /evolution doctor。";
-    readonly cardReview: "审查";
-    readonly cardMemory: "记忆";
-    readonly cardToolMemory: "记忆工具";
-    readonly cardCurator: "策展";
-    readonly cardSkills: "技能";
+    readonly refused: "这个值没有被接受（界面上保持原样）。想看原因：运行 /evolution params 或 /evolution doctor。";
+    readonly cardReview: "会话回顾";
+    readonly cardMemory: "长期记忆";
+    readonly cardToolMemory: "记忆写入";
+    readonly cardCurator: "技能整理";
+    readonly cardSkills: "技能写入规则";
 };
 /** English copy, key for key with {@link zh}. */
 export declare const en: Record<keyof typeof zh, string>;

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.9.0",
   "publishConfig": {
     "access": "public"
   },