@lmzhen/dsh-evolution-settings-ui 0.21.0 → 0.23.0

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

@@ -28,10 +28,11 @@ import type { ParamSectionSnapshot, ParamSectionSource, SettingsPathOpLike } fro
 export interface ParamCardFace {
     namespace: string;
     fields: readonly ClientParamField[];
-    t: (key: MessageKey) => string;
-    /** ONE call per save, carrying every dirty field as one op list (T5-01/A56). */
-    mutateOnce: (ops: readonly SettingsParamOp[]) => Promise<void>;
-    clear: (field: string) => Promise<void>;
+    t: (key: MessageKey, values?: Readonly<Record<string, string | number>>) => string;
+    /** ONE call per save, carrying every dirty field as one op list (T5-01/A56). The returned boolean IS
+     * the Host's verdict (contract C2/G5): `true` = accepted, `false` = refused after its recovery read. */
+    mutateOnce: (ops: readonly SettingsParamOp[]) => Promise<boolean>;
+    clear: (field: string) => Promise<boolean>;
     hooks: {
         paramSection: ParamSectionSource;
     };
@@ -47,6 +48,17 @@ export type ParamCardProps = Omit<ParamCardFace, 'hooks'> & {
 };
 /** The op list a save hands to the seat — the seam's own shape, never a second vocabulary. */
 export type SettingsParamOp = SettingsPathOpLike;
+/**
+ * U-4: whether one field's CURRENT text is a value the Host can take. The controls constrain their own
+ * domains (a number input sanitizes, a select only offers listed values), so the reachable case is a
+ * value the registry no longer lists — carried in the user layer and re-staged by any other edit.
+ * @param field - the generated field.
+ * @param text - the text the control holds right now.
+ * @param peer - U-4: the text the row this field declares `atLeast` against currently holds (absent
+ * when the field declares no relation, or when that row is not on this card).
+ * @returns the message key explaining the refusal, or null when the value is acceptable.
+ */
+export declare function invalidReason(field: ClientParamField, text: string, peer?: string): MessageKey | null;
 /**
  * Render one namespace's card.
  * @param props - the card data, its callbacks, and the bound section hook.
@@ -56,11 +68,11 @@ export type SettingsParamOp = SettingsPathOpLike;
 export interface ParamCardViewProps {
     namespace: string;
     fields: readonly ClientParamField[];
-    t: (key: MessageKey) => string;
+    t: (key: MessageKey, values?: Readonly<Record<string, string | number>>) => string;
     /** ONE call per save, carrying every dirty field as one op list (T5-01/A56). */
-    mutateOnce: (ops: readonly SettingsParamOp[]) => Promise<void>;
+    mutateOnce: (ops: readonly SettingsParamOp[]) => Promise<boolean>;
     /** Ask the scope to drop one override; resolves when the scope answered, not when it landed. */
-    clear: (field: string) => Promise<void>;
+    clear: (field: string) => Promise<boolean>;
     /** The current row state, from whichever source owns it (the bound hook or the page). */
     snapshot: ParamSectionSnapshot;
 }

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

@@ -17,9 +17,22 @@ import type { ApprovalApi } from './api.ts';
 import type { MessageKey } from './messages.ts';
 /** Injected face: the copy seat and the host calls. No hook compartment — this card keeps its own state. */
 export interface PendingCardFace {
-    t: (key: MessageKey) => string;
+    t: (key: MessageKey, values?: Readonly<Record<string, string | number>>) => string;
     api: ApprovalApi;
+    /**
+     * U-6 (registry `approvalConfirm`): read PER RENDER, like the entry's own seat probe — a value
+     * captured once would pin the gate for the life of the fiber. Absent ⇒ the shipped default `auto`.
+     */
+    confirmMode?: () => 'auto' | 'ask' | 'timeout';
 }
+/**
+ * U-6: the registry's gate word, read out of a section's user layer. ONE definition, exported so the
+ * mapping itself is judgeable: the entry does the wiring, this does the reading. Anything that is not
+ * one of the two explicit words falls back to the shipped default (`auto`) — a document written by a
+ * future version must not silently turn the confirmation ON, and a typo must not turn it off. The
+ * independent review flagged that this reader had no case at all (P2-11).
+ */
+export declare function confirmModeFrom(user: unknown): 'auto' | 'ask' | 'timeout';
 /**
  * Render the pending window.
  * @param props - the copy seat and the host calls.

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

@@ -17,7 +17,7 @@ export interface RowConfigFace {
     /** The row's entry id, for the card title. */
     namespace: string;
     fields: readonly ClientParamField[];
-    t: (key: MessageKey) => string;
+    t: (key: MessageKey, values?: Readonly<Record<string, string | number>>) => string;
 }
 /** Props one row entry is rendered with: the page's seat plus this row's own face. */
 export type RowConfigCardProps = RowConfigViewProps & RowConfigFace;

package/lib/types/client/generated-about.d.ts

@@ -0,0 +1,11 @@
+/**
+ * GENERATED by packages/scripts/gen-about.mjs — do not edit.
+ *
+ * The version comes from the repository package.json and the purpose from this package own
+ * description, so the settings surface can state both without a hand-written copy.
+ */
+/** The family version this surface belongs to. */
+export declare const FAMILY_VERSION = "0.23.0";
+/** What this surface is for, in one line. */
+export declare const PACKAGE_PURPOSE = "Web settings cards for the evolution family's parameter namespaces";
+//# sourceMappingURL=generated-about.d.ts.map

package/lib/types/client/generated-params.d.ts

@@ -8,6 +8,8 @@
 export interface ClientParamField {
     id: string;
     group: string;
+    /** U-4: the sibling id this field may not go below (an empty string when the row declares no relation). */
+    atLeast: string;
     /** The registry summary (English), kept for parity with PARAMETERS.md. */
     doc: string;
     /** Card label, from the registry UI tail (Chinese). */

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

@@ -0,0 +1,13 @@
+/**
+ * Is this a non-null, non-array object (what JSON calls an object)?
+ * @param value - the value to test.
+ * @returns whether it is a plain object.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Read a value as a record, or undefined when it is not one.
+ * @param value - the value to read.
+ * @returns the value typed as a record, or undefined.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | undefined;
+//# sourceMappingURL=guards.d.ts.map

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

@@ -14,7 +14,7 @@ export declare const NS = "evolution-settings";
 export declare const zh: {
     readonly title: "自进化";
     readonly subtitle: "待你决定的写入在最上面；下面按功能列出你能改的参数，没有列出的由安装时的配置决定。";
-    readonly overridden: "我改过";
+    readonly overridden: "已覆盖";
     readonly deployment: "默认";
     readonly loading: "正在读取设置…";
     readonly unavailable: "这个功能没有启动（对应的插件没有安装）";
@@ -24,12 +24,21 @@ export declare const zh: {
     readonly apply: "保存";
     readonly reset: "恢复默认值";
     readonly empty: "这里没有可改项";
-    readonly changed: "{n} 项已改";
+    readonly changed: "{n} 项已覆盖";
     readonly discard: "放弃修改";
     readonly saving: "保存中…";
     readonly resetting: "恢复中…";
-    readonly refused: "这个值没有被接受（界面上保持原样）。想看原因：运行 /evolution params 或 /evolution doctor。";
-    readonly resetRefused: "恢复默认值没有生效（这一行还是你的值）。想看原因：运行 /evolution params 或 /evolution doctor。";
+    readonly destHost: "保存去向：本机配置";
+    readonly invalidNumber: "需要一个数字";
+    readonly invalidSelect: "不在允许的取值里";
+    readonly invalidAtLeast: "不能小于同组的 {n}";
+    readonly approvalConfirmNamed: "即将批准：{n}";
+    readonly approvalConfirmYes: "确认批准";
+    readonly approvalConfirmNo: "取消";
+    readonly destMemory: "保存去向：仅本次会话";
+    readonly resetTo: "复位为 {value}";
+    readonly refused: "这个值没有被接受（界面上保持原样）。想看原因：在对话里让它说明。";
+    readonly resetRefused: "恢复默认值没有生效（这一行还是你的值）。想看原因：在对话里让它说明。";
     readonly cardReview: "会话回顾";
     readonly cardMemory: "长期记忆";
     readonly cardToolMemory: "记忆写入";
@@ -81,4 +90,22 @@ export type MessageKey = keyof typeof zh;
  * @returns the copy this bundle carries.
  */
 export declare function message(key: MessageKey, language?: 'zh' | 'en'): string;
+/**
+ * Fill one TEMPLATE's `{slot}` placeholders (G5 C4). The seat's translator takes the values, so the
+ * rule lives here instead of at every call site — `t('changed').replace('{n}', …)` used to be
+ * written seven times across three components. An UNKNOWN slot is left standing: a missing value
+ * must not print "undefined" into the operator's UI.
+ * @param template - the resolved copy, with `{slot}` placeholders.
+ * @param values - substitutions keyed by the slot name inside the braces.
+ * @returns the filled copy.
+ */
+export declare function fill(template: string, values: Readonly<Record<string, string | number>>): string;
+/**
+ * Resolve one message and fill its slots in one step: exactly what the seat's `t` does (G5 C4),
+ * for specs and stand-alone callers that hold no seat.
+ * @param key - the copy key.
+ * @param values - substitutions, or undefined for the plain copy.
+ * @returns the copy a reader sees.
+ */
+export declare function formatText(key: MessageKey, values?: Readonly<Record<string, string | number>>): string;
 //# sourceMappingURL=messages.d.ts.map

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

@@ -42,6 +42,10 @@ export interface ParamSectionSnapshot {
     /** Raw user section: a key's PRESENCE marks the override, not its value. */
     user: unknown;
     writable: boolean;
+    /** U-5: the composition layer a cleared field reverts to (platform `base`, previously dropped). */
+    base: Record<string, unknown> | undefined;
+    /** U-5: where a save lands — `memory` means this session only (platform `mode`, previously dropped). */
+    mode: 'host' | 'memory';
     /**
      * Why an `unavailable` snapshot is unavailable: this bundle found no settings seat at
      * all, or the seat is there and serves no such row. The two read differently to the

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

@@ -29,12 +29,8 @@ export declare const SEAT_MISSING: ParamSectionSnapshot;
  * so a failing row keeps ONE reference: a fresh object per call would reintroduce the
  * render loop this module exists to prevent. */
 export declare const PROJECTION_FAILED: ParamSectionSnapshot;
-/**
- * Whether a value is a plain section object.
- * @param value - the value to test.
- * @returns true for a non-null, non-array object.
- */
-export declare function isSection(value: unknown): value is Record<string, unknown>;
+import { isRecord as isSection } from './guards.ts';
+export { isSection };
 /**
  * Project one platform snapshot into the card's own shape.
  * @param snapshot - the seat's snapshot.
@@ -70,8 +66,8 @@ export declare function sourceFor(probe: SeatProbe, namespace: string): ParamSec
  * @returns the two calls a card's save/reset path uses; without a seat they resolve without writing.
  */
 export declare function writeFaceFor(probe: SeatProbe, namespace: string): {
-    mutateOnce: (ops: readonly SettingsPathOpLike[]) => Promise<void>;
-    clear: (field: string) => Promise<void>;
+    mutateOnce: (ops: readonly SettingsPathOpLike[]) => Promise<boolean>;
+    clear: (field: string) => Promise<boolean>;
 };
 /**
  * One source object per namespace, for the life of the plugin fiber.

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.21.0",
+  "version": "0.23.0",
   "publishConfig": {
     "access": "public"
   },

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

@@ -1,35 +0,0 @@
-/**
- * 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 operation awaiting its verdict, in the platform's own two op kinds.
- *
- * `unset` is here because "restore the default" had NO verdict at all (T5-05/A60): the reset path
- * called the scope and dropped its answer, so a host refusal changed nothing on screen — the row kept
- * its "edited by you" chip and the reader concluded the button was broken. The two ops need different
- * evidence (a set landed when the id holds the value; an unset landed when the id is GONE), which is
- * exactly why they are one union judged by one function instead of two look-alike helpers.
- */
-export type Settlement = {
-    readonly op: 'set';
-    readonly id: string;
-    readonly want: unknown;
-} | {
-    readonly op: 'unset';
-    readonly id: string;
-};
-/**
- * Whether every staged operation is visible in the user layer.
- * @param pending - the operations 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 requested value, or is gone after an `unset`.
- */
-export declare function landedSettlements(pending: readonly Settlement[], user: unknown): boolean;
-//# sourceMappingURL=settle.d.ts.map