@lmzhen/dsh-evolution-settings-ui 0.15.2 → 0.16.0

package/README.md

@@ -24,6 +24,23 @@ Writes go through the client settings scope (`set`/`unset`), which carries the r
 
 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 pending-write card
+
+One card in the same section is not a parameter namespace: **「待批写入」** lists the staged self-evolution
+writes and carries the two decisions plus a preview. It reads the approval plugin's loopback routes
+(`src/client/api.ts` + `approval-routes.ts`; the path literals are compared against the host table by a spec),
+wears the same card shell and button vocabulary as the parameter cards, and invents no state of its own.
+
+Its states are deliberately distinct: **reading** ("正在读取待批项…"), **empty** ("没有待批的写入") and
+**failed** (the reason plus a retry). Merging the first two is what once made a slow answer read as lost data
+(E7), so the state machine lives in `pending-state.ts` and the three are asserted without a browser.
+
+A decision re-reads the window instead of editing the list locally (the host owns the state) and shows the
+host's own sentence when it refuses. **Preview** opens one row at a time: the facts line (`n 行新增` /
+`n 行删除` / truncated) and the source block with `-`/`+` lines, the same shape the history panel's diff
+uses; an unavailable preview prints the host's reason. A late answer for a row the reader already left is
+dropped rather than painted under another row's heading.
+
 ## 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.
@@ -48,4 +65,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.
+- The parameter card has no RENDERED spec: the family specs are Node-level and the family carries no React runtime, so it 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

@@ -5,6 +5,76 @@ window.__ModuleLoader__.load({
 		var exports = module.exports;
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let react = require("react");
+		//#region src/client/approval-routes.ts
+		/**
+		* The approval paths this browser half calls.
+		*
+		* A browser half cannot import the host package's table at runtime (the family's client bundles treat
+		* every `@deepseek-ai/*` specifier as external), so the literals are declared here and a spec compares
+		* them against `APPROVAL_ROUTES` in `evolution-approval` — a rename on one side would otherwise surface
+		* as a 404 in the GUI instead of in CI.
+		* @module @lmzhen/dsh-evolution-settings-ui/client/approval-routes
+		*/
+		/** One path per call the pending card makes. */
+		const APPROVAL_CLIENT_ROUTES = {
+			pending: "/api/dsh-evolution/approval/pending",
+			approve: "/api/dsh-evolution/approval/approve",
+			reject: "/api/dsh-evolution/approval/reject",
+			preview: "/api/dsh-evolution/approval/preview"
+		};
+		//#endregion
+		//#region src/client/api.ts
+		/**
+		* The approval routes this bundle calls, and the ONE place a request is made.
+		*
+		* Structural types on purpose: the browser half cannot import the host package at runtime, so the row
+		* shape is declared by what the route hands over. Every answer — including a refusal — is parsed the
+		* same way, because a refusal is a business answer the card shows as a sentence, not a transport error.
+		* @module @lmzhen/dsh-evolution-settings-ui/client/api
+		*/
+		/** Read one JSON answer, mapping every failure onto the same refusal shape. */
+		async function read(doFetch, path, init) {
+			try {
+				const response = await doFetch(path, init);
+				if (!response.ok) return {
+					ok: false,
+					message: "HTTP " + String(response.status)
+				};
+				const body = await response.json();
+				if (body.ok === true) return {
+					ok: true,
+					data: body.data
+				};
+				return {
+					ok: false,
+					message: typeof body.message === "string" && body.message !== "" ? body.message : "the host refused the request"
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					message: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}
+		/**
+		* Build the approval face over one fetch implementation.
+		* @param doFetch - the fetch to use (the platform's global in the browser, a fake in a spec).
+		* @returns the three calls the pending card makes.
+		*/
+		function createApprovalApi(doFetch) {
+			const post = (path, id) => read(doFetch, path, {
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify({ id })
+			});
+			return {
+				pending: async () => await read(doFetch, APPROVAL_CLIENT_ROUTES.pending),
+				approve: async (id) => await post(APPROVAL_CLIENT_ROUTES.approve, id),
+				reject: async (id) => await post(APPROVAL_CLIENT_ROUTES.reject, id),
+				preview: async (id) => await read(doFetch, APPROVAL_CLIENT_ROUTES.preview + "?id=" + encodeURIComponent(id))
+			};
+		}
+		//#endregion
 		//#region src/client/generated-params.ts
 		const CLIENT_PARAM_SECTIONS = [
 			{
@@ -422,6 +492,267 @@ window.__ModuleLoader__.load({
 			}
 		];
 		//#endregion
+		//#region src/client/pending-state.ts
+		/** The state a card mounts in: still loading, nothing in flight, nothing said yet. */
+		const INITIAL_PENDING_STATE = {
+			view: { kind: "loading" },
+			busy: [],
+			notice: null,
+			open: null,
+			preview: null
+		};
+		/** Open one row's preview: the row is now the open one and its answer is on the way. */
+		function expanded(state, id) {
+			return {
+				...state,
+				open: id,
+				preview: { kind: "loading" }
+			};
+		}
+		/** Close whatever preview is open. */
+		function collapsed(state) {
+			return {
+				...state,
+				open: null,
+				preview: null
+			};
+		}
+		/**
+		* A preview answer arrived. An answer for a row the reader has already left is DROPPED: it would
+		* otherwise paint one row's diff under another row's heading.
+		*/
+		function previewArrived(state, id, view) {
+			return state.open === id ? {
+				...state,
+				preview: view
+			} : state;
+		}
+		/** The first load, or a refresh after a decision: back to loading, keeping no stale rows. */
+		function loading(state) {
+			return {
+				...state,
+				view: { kind: "loading" }
+			};
+		}
+		/**
+		* A list arrived. An empty list is its OWN state — the reader is told the window is clear rather than
+		* being shown the same line a slow answer shows.
+		*/
+		function loaded(state, rows) {
+			return {
+				...state,
+				view: rows.length === 0 ? { kind: "empty" } : {
+					kind: "ready",
+					rows
+				}
+			};
+		}
+		/** The list could not be read: the reason stays on screen next to a retry control. */
+		function failed(state, message) {
+			return {
+				...state,
+				view: {
+					kind: "failed",
+					message
+				}
+			};
+		}
+		/** Mark one record as having an action in flight (its buttons are disabled until it ends). */
+		function beginAction(state, id) {
+			return state.busy.includes(id) ? state : {
+				...state,
+				busy: [...state.busy, id]
+			};
+		}
+		/** The action ended, whatever it answered. */
+		function endAction(state, id) {
+			return {
+				...state,
+				busy: state.busy.filter((candidate) => candidate !== id)
+			};
+		}
+		/** One refusal or failure line under the list; `null` clears it (a later success does). */
+		function noticed(state, message) {
+			return {
+				...state,
+				notice: message
+			};
+		}
+		//#endregion
+		//#region src/client/PendingCard.ts
+		/**
+		* The "writes awaiting approval" card: the staged write window, with the two decisions on each row.
+		*
+		* It is a card in the SAME section and wears the SAME shell as the parameter cards (header with title,
+		* count and chevron; body of field blocks; a button row per block), so nothing here invents a second
+		* visual language. Two things differ on purpose: the data comes from the host's approval routes rather
+		* than the settings transport, and its three states are distinct — "reading", "nothing staged" and "the
+		* read failed" each say so in their own words (E7: merging the first two is what made an empty panel
+		* look like lost data).
+		*
+		* Every decision re-reads the window instead of predicting the outcome: the host owns the state, and a
+		* refusal is shown with the host's own sentence.
+		* @module @lmzhen/dsh-evolution-settings-ui/client/PendingCard
+		*/
+		/** Which word one age bucket gets; an unknown bucket falls back to the count form. */
+		const AGE_KEYS = Object.freeze({
+			now: "approvalAgeNow",
+			minutes: "approvalAgeMinutes",
+			hours: "approvalAgeHours",
+			days: "approvalAgeDays",
+			months: "approvalAgeMonths"
+		});
+		/** Which word one staged kind gets. */
+		const KIND_KEYS = Object.freeze({
+			memory: "approvalKindMemory",
+			skill: "approvalKindSkill",
+			capability: "approvalKindCapability"
+		});
+		/**
+		* Render the pending window.
+		* @param props - the copy seat and the host calls.
+		* @returns the card.
+		*/
+		function PendingCard(props) {
+			const { t, api } = props;
+			const [state, setState] = (0, react.useState)(INITIAL_PENDING_STATE);
+			const [open, setOpen] = (0, react.useState)(true);
+			const latest = (0, react.useRef)(state);
+			const apply = (next) => {
+				const value = next(latest.current);
+				latest.current = value;
+				setState(value);
+			};
+			const load = async () => {
+				apply(loading);
+				const answer = await api.pending();
+				apply((current) => answer.ok ? loaded(current, answer.data) : failed(current, answer.message));
+			};
+			(0, react.useEffect)(() => {
+				load();
+			}, []);
+			const decide = (id, action) => {
+				apply((current) => beginAction(current, id));
+				(async () => {
+					const answer = action === "approve" ? await api.approve(id) : await api.reject(id);
+					if (!answer.ok) {
+						apply((current) => noticed(endAction(current, id), answer.message));
+						return;
+					}
+					apply((current) => noticed(endAction(current, id), null));
+					await load();
+				})();
+			};
+			const age = (row) => {
+				const key = AGE_KEYS[row.age.unit];
+				if (key === void 0) return String(row.age.n);
+				return t(key).replace("{n}", String(row.age.n));
+			};
+			/** Ask the host what this record would store; the answer lands only if the row is still open. */
+			const loadPreview = async (id) => {
+				const answer = await api.preview(id);
+				const view = answer.ok ? answer.data.available ? {
+					kind: "ready",
+					answer: answer.data
+				} : {
+					kind: "unavailable",
+					reason: answer.data.reason
+				} : {
+					kind: "failed",
+					message: answer.message
+				};
+				apply((current) => previewArrived(current, id, view));
+			};
+			const togglePreview = (id) => {
+				if (state.open === id) {
+					apply(collapsed);
+					return;
+				}
+				apply((current) => expanded(current, id));
+				loadPreview(id);
+			};
+			/** The facts line, then the source view: the same shape the history panel's diff uses. */
+			const preview = (view) => {
+				if (view.kind === "loading") return (0, react.createElement)("p", { className: "evolution-param-note" }, t("approvalPreviewReading"));
+				if (view.kind === "failed") return (0, react.createElement)("p", { className: "evolution-param-error" }, view.message);
+				if (view.kind === "unavailable") return (0, react.createElement)("p", { className: "evolution-param-error" }, t("approvalPreviewNone") + view.reason);
+				const facts = [
+					(0, react.createElement)("span", {
+						className: "evolution-param-fact",
+						key: "added"
+					}, t("approvalDiffAdded").replace("{n}", String(view.answer.linesAdded))),
+					(0, react.createElement)("span", {
+						className: "evolution-param-fact",
+						key: "removed"
+					}, t("approvalDiffRemoved").replace("{n}", String(view.answer.linesRemoved))),
+					...view.answer.truncated ? [(0, react.createElement)("span", {
+						className: "evolution-param-fact",
+						key: "cut"
+					}, t("approvalDiffCut"))] : []
+				];
+				const lines = [];
+				for (const hunk of view.answer.hunks) {
+					for (const [index, line] of hunk.oldText.split("\n").entries()) {
+						if (hunk.oldText === "" && line === "") continue;
+						lines.push((0, react.createElement)("div", {
+							key: "old-" + String(index),
+							className: "evolution-param-line-del"
+						}, "- " + line));
+					}
+					for (const [index, line] of hunk.newText.split("\n").entries()) {
+						if (hunk.newText === "" && line === "") continue;
+						lines.push((0, react.createElement)("div", {
+							key: "new-" + String(index),
+							className: "evolution-param-line-add"
+						}, "+ " + line));
+					}
+				}
+				return (0, react.createElement)("div", null, (0, react.createElement)("p", { className: "evolution-param-facts" }, ...facts), (0, react.createElement)("pre", { className: "evolution-param-source" }, ...lines.length === 0 ? ["±"] : lines));
+			};
+			const row = (entry) => {
+				const busy = state.busy.includes(entry.id);
+				const button = (label, action) => (0, react.createElement)("button", {
+					className: "evolution-param-button",
+					type: "button",
+					disabled: busy,
+					onClick: () => {
+						decide(entry.id, action);
+					}
+				}, busy ? t("approvalLoading") : t(label));
+				return (0, react.createElement)("div", {
+					className: "evolution-param-field",
+					key: entry.id
+				}, (0, react.createElement)("div", { className: "evolution-param-label" }, (0, react.createElement)("span", { className: "evolution-param-source" }, t(KIND_KEYS[entry.kind])), (0, react.createElement)("span", { className: "evolution-param-value" }, entry.summary)), (0, react.createElement)("p", { className: "evolution-param-hint" }, age(entry)), (0, react.createElement)("div", { className: "evolution-param-actions" }, button("approvalApprove", "approve"), button("approvalReject", "reject"), (0, react.createElement)("button", {
+					className: "evolution-param-button",
+					type: "button",
+					onClick: () => {
+						togglePreview(entry.id);
+					}
+				}, state.open === entry.id ? t("approvalPreviewClose") : t("approvalPreview"))), state.open === entry.id && state.preview !== null ? preview(state.preview) : null);
+			};
+			const body = () => {
+				if (state.view.kind === "loading") return (0, react.createElement)("p", { className: "evolution-param-note" }, t("approvalLoading"));
+				if (state.view.kind === "empty") return (0, react.createElement)("p", { className: "evolution-param-note" }, t("approvalEmpty"));
+				if (state.view.kind === "failed") return (0, react.createElement)("div", { className: "evolution-param-actions" }, (0, react.createElement)("p", { className: "evolution-param-error" }, t("approvalFailed") + ": " + state.view.message), (0, react.createElement)("button", {
+					className: "evolution-param-button",
+					type: "button",
+					onClick: () => {
+						load();
+					}
+				}, t("approvalRetry")));
+				return (0, react.createElement)("div", null, ...state.view.rows.map(row), state.notice === null ? null : (0, react.createElement)("p", { className: "evolution-param-error" }, state.notice));
+			};
+			const count = state.view.kind === "ready" ? state.view.rows.length : 0;
+			return (0, react.createElement)("section", { className: "evolution-param-card" }, (0, react.createElement)("button", {
+				className: "evolution-param-head",
+				type: "button",
+				onClick: () => {
+					setOpen(!open);
+				},
+				"aria-expanded": open
+			}, (0, react.createElement)("span", { className: "evolution-param-card-title" }, t("approvalTitle")), count === 0 ? null : (0, react.createElement)("span", { className: "evolution-param-count" }, t("approvalCount").replace("{n}", String(count))), (0, react.createElement)("span", { className: "evolution-param-chevron" }, open ? "▲" : "▼")), open ? (0, react.createElement)("div", { className: "evolution-param-body" }, body()) : null);
+		}
+		//#endregion
 		//#region src/client/messages.ts
 		/**
 		* Copy for the evolution settings section and its parameter cards.
@@ -455,7 +786,30 @@ window.__ModuleLoader__.load({
 			cardMemory: "长期记忆",
 			cardToolMemory: "记忆写入",
 			cardCurator: "技能整理",
-			cardSkills: "技能写入规则"
+			cardSkills: "技能写入规则",
+			approvalTitle: "待批写入",
+			approvalLoading: "正在读取待批项…",
+			approvalEmpty: "没有待批的写入",
+			approvalFailed: "待批项读取失败",
+			approvalRetry: "重试",
+			approvalApprove: "批准",
+			approvalReject: "拒绝",
+			approvalCount: "{n} 项待批",
+			approvalKindMemory: "记忆",
+			approvalKindSkill: "技能",
+			approvalKindCapability: "能力",
+			approvalAgeNow: "刚刚",
+			approvalAgeMinutes: "{n} 分钟前",
+			approvalAgeHours: "{n} 小时前",
+			approvalAgeDays: "{n} 天前",
+			approvalAgeMonths: "{n} 个月前",
+			approvalPreview: "预览",
+			approvalPreviewClose: "收起",
+			approvalPreviewReading: "正在读取预览…",
+			approvalPreviewNone: "看不了预览：",
+			approvalDiffAdded: "{n} 行新增",
+			approvalDiffRemoved: "{n} 行删除",
+			approvalDiffCut: "改动区域已截断"
 		};
 		/** English copy, key for key with {@link zh}. */
 		const en = {
@@ -477,7 +831,30 @@ window.__ModuleLoader__.load({
 			cardMemory: "Long-term memory",
 			cardToolMemory: "Writing memory",
 			cardCurator: "Skill tidy-up",
-			cardSkills: "Skill write rules"
+			cardSkills: "Skill write rules",
+			approvalTitle: "Writes awaiting approval",
+			approvalLoading: "reading the pending window…",
+			approvalEmpty: "nothing is waiting for a decision",
+			approvalFailed: "the pending window could not be read",
+			approvalRetry: "Retry",
+			approvalApprove: "Approve",
+			approvalReject: "Reject",
+			approvalCount: "{n} waiting",
+			approvalKindMemory: "memory",
+			approvalKindSkill: "skill",
+			approvalKindCapability: "capability",
+			approvalAgeNow: "just now",
+			approvalAgeMinutes: "{n} min ago",
+			approvalAgeHours: "{n} h ago",
+			approvalAgeDays: "{n} d ago",
+			approvalAgeMonths: "{n} mo ago",
+			approvalPreview: "Preview",
+			approvalPreviewClose: "Hide",
+			approvalPreviewReading: "reading the preview…",
+			approvalPreviewNone: "no preview: ",
+			approvalDiffAdded: "{n} lines added",
+			approvalDiffRemoved: "{n} lines removed",
+			approvalDiffCut: "the changed region is truncated"
 		};
 		/**
 		* Card titles per settings namespace. A namespace without an entry falls back to
@@ -825,7 +1202,12 @@ window.__ModuleLoader__.load({
 			".evolution-param-check:disabled{cursor:default;opacity:.5}",
 			".evolution-param-footer{display:flex;justify-content:flex-end;gap:var(--evo-space-8);padding:var(--evo-space-12) 0 0;border-top:var(--evo-hairline-width) solid var(--dsw-alias-border-l2)}",
 			".evolution-param-note{margin:0;color:var(--dsw-alias-label-tertiary);font-size:var(--evo-type-xs);line-height:var(--evo-leading-base)}",
-			".evolution-param-error{margin:0;color:var(--dsw-alias-state-error-primary);font-size:var(--evo-type-xs);line-height:var(--evo-leading-base)}"
+			".evolution-param-error{margin:0;color:var(--dsw-alias-state-error-primary);font-size:var(--evo-type-xs);line-height:var(--evo-leading-base)}",
+			".evolution-param-facts{display:flex;flex-wrap:wrap;align-items:baseline;margin:0;color:var(--dsw-alias-label-tertiary);font-size:var(--evo-type-xs);line-height:var(--evo-leading-base)}",
+			".evolution-param-fact+.evolution-param-fact::before{content:\"·\";margin:0 var(--evo-space-6);color:var(--dsw-alias-label-tertiary)}",
+			".evolution-param-source{margin:0;padding:var(--evo-space-12) var(--evo-space-16);max-height:var(--evo-cap-block);overflow:auto;border:var(--evo-hairline-width) solid var(--dsw-alias-border-l1);border-radius:var(--evo-radius-surface);background:var(--dsw-alias-markdown-code-block);color:var(--dsw-alias-label-primary);font:var(--dsw-font-markdown-code-block-small);white-space:pre-wrap}",
+			".evolution-param-line-add{color:var(--evo-tone-success)}",
+			".evolution-param-line-del{color:var(--evo-tone-danger)}"
 		].join("\n");
 		/**
 		* Inject the stylesheet once per document.
@@ -853,6 +1235,13 @@ window.__ModuleLoader__.load({
 		const SECTION_ID = "evolution";
 		const SECTION_ORDER = 25;
 		/**
+		* The pending-window card's slot key.
+		*
+		* The section pairs cards by key and the parameter cards use their settings namespace; this card has no
+		* namespace (its data comes from the host's approval routes), so it carries a key of its own.
+		*/
+		const PENDING_CARD_KEY = "approval-pending";
+		/**
 		* Register the locale namespace, the section and its cards.
 		* @param ctx - client cordis context.
 		*/
@@ -913,9 +1302,19 @@ window.__ModuleLoader__.load({
 						inject: face
 					}, ParamCard);
 				}
+				const api = createApprovalApi((input, init) => fetch(input, init));
+				yield seam.slots.register({
+					name: CARD_SLOT,
+					key: PENDING_CARD_KEY,
+					inject: () => ({
+						t,
+						api
+					})
+				}, PendingCard);
 			});
 		}
 		//#endregion
+		exports.PENDING_CARD_KEY = PENDING_CARD_KEY;
 		exports.SECTION_ID = SECTION_ID;
 		exports.SECTION_ORDER = SECTION_ORDER;
 		exports.apply = apply;

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

@@ -0,0 +1,29 @@
+/**
+ * The "writes awaiting approval" card: the staged write window, with the two decisions on each row.
+ *
+ * It is a card in the SAME section and wears the SAME shell as the parameter cards (header with title,
+ * count and chevron; body of field blocks; a button row per block), so nothing here invents a second
+ * visual language. Two things differ on purpose: the data comes from the host's approval routes rather
+ * than the settings transport, and its three states are distinct — "reading", "nothing staged" and "the
+ * read failed" each say so in their own words (E7: merging the first two is what made an empty panel
+ * look like lost data).
+ *
+ * Every decision re-reads the window instead of predicting the outcome: the host owns the state, and a
+ * refusal is shown with the host's own sentence.
+ * @module @lmzhen/dsh-evolution-settings-ui/client/PendingCard
+ */
+import { type ReactNode } from 'react';
+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;
+    api: ApprovalApi;
+}
+/**
+ * Render the pending window.
+ * @param props - the copy seat and the host calls.
+ * @returns the card.
+ */
+export declare function PendingCard(props: PendingCardFace): ReactNode;
+//# sourceMappingURL=PendingCard.d.ts.map

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

@@ -0,0 +1,61 @@
+/** One staged write, as the pending route hands it over (never the staged args). */
+export interface PendingRow {
+    readonly id: string;
+    readonly kind: 'memory' | 'skill' | 'capability';
+    readonly summary: string;
+    readonly createdAt: string;
+    /** How long ago it was staged, in the family's `{unit, n}` closed vocabulary. */
+    readonly age: {
+        readonly unit: string;
+        readonly n: number;
+    };
+    readonly status: 'pending' | 'executing' | 'approved' | 'rejected';
+    readonly claimedBy?: string | undefined;
+}
+/** One windowed hunk of a previewed change: the region the write would touch. */
+export interface PreviewHunk {
+    readonly path: string;
+    readonly oldText: string;
+    readonly newText: string;
+}
+/**
+ * What a staged write WOULD store. `available: false` carries the host's reason — plenty of records have
+ * no bytes worth showing, and the reader is owed that sentence rather than an empty diff.
+ */
+export type PreviewAnswer = {
+    readonly available: true;
+    readonly path: string;
+    readonly linesAdded: number;
+    readonly linesRemoved: number;
+    readonly hunks: readonly PreviewHunk[];
+    readonly truncated: boolean;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+/** What one call answered: the data, or the reason it could not be carried out. */
+export type ApprovalAnswer<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** How this bundle reaches the host. Injectable so a spec drives it without a server. */
+export interface ApprovalApi {
+    /** The staged writes waiting for a decision. */
+    pending: () => Promise<ApprovalAnswer<readonly PendingRow[]>>;
+    /** Ask the host to replay one staged write. */
+    approve: (id: string) => Promise<ApprovalAnswer<unknown>>;
+    /** Close one staged write without replaying it. */
+    reject: (id: string) => Promise<ApprovalAnswer<unknown>>;
+    /** What that staged write would store, resolved by the host without running it. */
+    preview: (id: string) => Promise<ApprovalAnswer<PreviewAnswer>>;
+}
+/**
+ * Build the approval face over one fetch implementation.
+ * @param doFetch - the fetch to use (the platform's global in the browser, a fake in a spec).
+ * @returns the three calls the pending card makes.
+ */
+export declare function createApprovalApi(doFetch: typeof fetch): ApprovalApi;
+//# sourceMappingURL=api.d.ts.map

package/lib/types/client/approval-routes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The approval paths this browser half calls.
+ *
+ * A browser half cannot import the host package's table at runtime (the family's client bundles treat
+ * every `@deepseek-ai/*` specifier as external), so the literals are declared here and a spec compares
+ * them against `APPROVAL_ROUTES` in `evolution-approval` — a rename on one side would otherwise surface
+ * as a 404 in the GUI instead of in CI.
+ * @module @lmzhen/dsh-evolution-settings-ui/client/approval-routes
+ */
+/** One path per call the pending card makes. */
+export declare const APPROVAL_CLIENT_ROUTES: {
+    readonly pending: "/api/dsh-evolution/approval/pending";
+    readonly approve: "/api/dsh-evolution/approval/approve";
+    readonly reject: "/api/dsh-evolution/approval/reject";
+    readonly preview: "/api/dsh-evolution/approval/preview";
+};
+//# sourceMappingURL=approval-routes.d.ts.map

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

@@ -21,6 +21,13 @@ export declare const inject: string[];
 /** Section id and nav order (the platform's own sections sit at 0/10/15/20). */
 export declare const SECTION_ID = "evolution";
 export declare const SECTION_ORDER = 25;
+/**
+ * The pending-window card's slot key.
+ *
+ * The section pairs cards by key and the parameter cards use their settings namespace; this card has no
+ * namespace (its data comes from the host's approval routes), so it carries a key of its own.
+ */
+export declare const PENDING_CARD_KEY = "approval-pending";
 /**
  * Register the locale namespace, the section and its cards.
  * @param ctx - client cordis context.

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

@@ -31,6 +31,29 @@ export declare const zh: {
     readonly cardToolMemory: "记忆写入";
     readonly cardCurator: "技能整理";
     readonly cardSkills: "技能写入规则";
+    readonly approvalTitle: "待批写入";
+    readonly approvalLoading: "正在读取待批项…";
+    readonly approvalEmpty: "没有待批的写入";
+    readonly approvalFailed: "待批项读取失败";
+    readonly approvalRetry: "重试";
+    readonly approvalApprove: "批准";
+    readonly approvalReject: "拒绝";
+    readonly approvalCount: "{n} 项待批";
+    readonly approvalKindMemory: "记忆";
+    readonly approvalKindSkill: "技能";
+    readonly approvalKindCapability: "能力";
+    readonly approvalAgeNow: "刚刚";
+    readonly approvalAgeMinutes: "{n} 分钟前";
+    readonly approvalAgeHours: "{n} 小时前";
+    readonly approvalAgeDays: "{n} 天前";
+    readonly approvalAgeMonths: "{n} 个月前";
+    readonly approvalPreview: "预览";
+    readonly approvalPreviewClose: "收起";
+    readonly approvalPreviewReading: "正在读取预览…";
+    readonly approvalPreviewNone: "看不了预览：";
+    readonly approvalDiffAdded: "{n} 行新增";
+    readonly approvalDiffRemoved: "{n} 行删除";
+    readonly approvalDiffCut: "改动区域已截断";
 };
 /** English copy, key for key with {@link zh}. */
 export declare const en: Record<keyof typeof zh, string>;

package/lib/types/client/pending-state.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The pending card's state machine, kept OUT of the component so the three states the review asked for
+ * can be asserted without a browser (and so a second rendering of the same data cannot invent a fourth).
+ *
+ * The one rule worth naming: LOADING and EMPTY are different states with different copy. The skill
+ * history panel shipped them merged once and a reader could not tell "nothing is staged" from "the
+ * answer has not arrived" (E7).
+ * @module @lmzhen/dsh-evolution-settings-ui/client/pending-state
+ */
+import type { PendingRow, PreviewAnswer } from './api.ts';
+/** What one row's preview is showing while it is open. */
+export type PreviewView = {
+    readonly kind: 'loading';
+} | {
+    readonly kind: 'ready';
+    readonly answer: Extract<PreviewAnswer, {
+        available: true;
+    }>;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly message: string;
+};
+/** What the card is showing right now. */
+export type PendingView = {
+    readonly kind: 'loading';
+} | {
+    readonly kind: 'ready';
+    readonly rows: readonly PendingRow[];
+} | {
+    readonly kind: 'empty';
+} | {
+    readonly kind: 'failed';
+    readonly message: string;
+};
+/** The whole card state: the view, the ids with an action in flight, and the last refusal line. */
+export interface PendingState {
+    readonly view: PendingView;
+    readonly busy: readonly string[];
+    readonly notice: string | null;
+    /** The row whose preview is open, or null. One at a time: a preview is a thing being read. */
+    readonly open: string | null;
+    readonly preview: PreviewView | null;
+}
+/** The state a card mounts in: still loading, nothing in flight, nothing said yet. */
+export declare const INITIAL_PENDING_STATE: PendingState;
+/** Open one row's preview: the row is now the open one and its answer is on the way. */
+export declare function expanded(state: PendingState, id: string): PendingState;
+/** Close whatever preview is open. */
+export declare function collapsed(state: PendingState): PendingState;
+/**
+ * A preview answer arrived. An answer for a row the reader has already left is DROPPED: it would
+ * otherwise paint one row's diff under another row's heading.
+ */
+export declare function previewArrived(state: PendingState, id: string, view: PreviewView): PendingState;
+/** The first load, or a refresh after a decision: back to loading, keeping no stale rows. */
+export declare function loading(state: PendingState): PendingState;
+/**
+ * A list arrived. An empty list is its OWN state — the reader is told the window is clear rather than
+ * being shown the same line a slow answer shows.
+ */
+export declare function loaded(state: PendingState, rows: readonly PendingRow[]): PendingState;
+/** The list could not be read: the reason stays on screen next to a retry control. */
+export declare function failed(state: PendingState, message: string): PendingState;
+/** Mark one record as having an action in flight (its buttons are disabled until it ends). */
+export declare function beginAction(state: PendingState, id: string): PendingState;
+/** The action ended, whatever it answered. */
+export declare function endAction(state: PendingState, id: string): PendingState;
+/** One refusal or failure line under the list; `null` clears it (a later success does). */
+export declare function noticed(state: PendingState, message: string | null): PendingState;
+//# sourceMappingURL=pending-state.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.15.2",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },