@lmzhen/dsh-evolution-settings-ui 0.17.0-rc.1 → 0.17.1

package/README.md

@@ -54,6 +54,16 @@ A card's inject face carries `hooks: { paramSection: source }` — that is the S
 
 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.
 
+## The seat contract: lazy probe, stable snapshot, one source object
+
+`src/client/source.ts` is the one place that turns `configForms.get(namespace)` into the three things a card needs — a snapshot, a subscription and the two write calls — and it holds three obligations the platform's renderer imposes:
+
+- **The seat is probed lazily.** `apply()` may run before the settings shell that declares this section and provides `configForms`, so a seat captured at apply time would pin the row to the empty state for the life of its fiber. The source reads a `SeatProbe` on every snapshot read; the write face re-probes per call.
+- **The projected snapshot keeps ONE reference until the row's raw snapshot moves.** The renderer binds the `hooks` compartment through `useSyncExternalStoreWithSelector`, which compares by reference: a projection that builds an object per call never compares equal, so React aborts the card (minified invariant #185) and the slot error boundary replaces it with an empty placeholder — that is 0.17.0's "all the cards disappeared". The projection caches per raw snapshot reference, and a projection failure returns the frozen `PROJECTION_FAILED` snapshot instead of throwing: a throw from `getSnapshot()` happens inside the renderer's render pass, where this bundle cannot catch it and where a `try`/`catch` around a hook call would not be legal React.
+- **One source object per namespace.** The renderer caches a hook binding per SOURCE object, so a source built per render re-binds the hook and remounts the card. `createSourceCache(probe)` owns the per-namespace cache and goes away with the fiber.
+
+A card therefore tells three unavailable reasons apart — `seat-missing` (no settings surface composed), `projection-failed` (the seat served the row and reading it failed; the error is logged once) and `not-served` (the row itself is unavailable) — instead of painting one blank state. `N29`/`N30` in the family guard hold the shape of this seam, and `tests/section.client.spec.ts` pins the stable reference, the re-projection on change, the frozen failure value, the per-namespace identity and the late seat.
+
 ## Styling
 
 The card draws from the FAMILY's scale, not from magic numbers: `src/client/tokens.ts` is generated from `packages/scripts/client-tokens.json` (identical bytes in the history panel, which shares it), and its type steps are relative to the surface that hosts the card — `calc(1em - 2px)` for a hint, `calc(1em + 2px)` for the title — so the card no longer resizes itself with the `--dsh-content-font-size*` setting, which is documented as affecting conversation content only and which the platform's own surfaces never read. Fields take the family's single focus ring (`outline: var(--evo-focus-ring)`), the same one the history panel draws, instead of a recoloured border. 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.

package/lib/client.js

@@ -806,6 +806,7 @@ window.__ModuleLoader__.load({
 			loading: "正在读取设置…",
 			unavailable: "这个功能没有启动（对应的插件没有安装）",
 			seatMissing: "这个界面没有提供设置服务，参数只能看不能改",
+			projectionFailed: "这一块读设置时出错，已记入日志；其它参数不受影响",
 			readonly: "本次会话不允许写入设置（临时运行模式）",
 			apply: "保存",
 			reset: "恢复默认值",
@@ -852,6 +853,7 @@ window.__ModuleLoader__.load({
 			loading: "reading settings…",
 			unavailable: "this feature is not running (its plugin is not installed)",
 			seatMissing: "this shell serves no settings surface, so the parameters cannot be edited here",
+			projectionFailed: "reading this row failed and the error is in the log; the other parameters are unaffected",
 			readonly: "settings cannot be written in this session (temporary mode)",
 			apply: "Save",
 			reset: "Reset to default",
@@ -1049,7 +1051,7 @@ window.__ModuleLoader__.load({
 			const [error, setError] = (0, react.useState)("");
 			const [pending, setPending] = (0, react.useState)(null);
 			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(snapshot.reason === "seat-missing" ? "seatMissing" : "unavailable"));
+			if (snapshot.status === "unavailable") return (0, react.createElement)("p", { className: "evolution-param-note" }, t(snapshot.reason === "seat-missing" ? "seatMissing" : snapshot.reason === "projection-failed" ? "projectionFailed" : "unavailable"));
 			const user = isSection$1(snapshot.user) ? snapshot.user : {};
 			const value = isSection$1(snapshot.value) ? snapshot.value : {};
 			const disabled = !snapshot.writable;
@@ -1164,6 +1166,16 @@ window.__ModuleLoader__.load({
 			writable: false,
 			reason: "seat-missing"
 		});
+		/** What a card shows when the seat served the row but projecting it failed. A frozen constant
+		* so a failing row keeps ONE reference: a fresh object per call would reintroduce the
+		* render loop this module exists to prevent. */
+		const PROJECTION_FAILED = Object.freeze({
+			status: "unavailable",
+			value: void 0,
+			user: void 0,
+			writable: false,
+			reason: "projection-failed"
+		});
 		/**
 		* Whether a value is a plain section object.
 		* @param value - the value to test.
@@ -1187,30 +1199,91 @@ window.__ModuleLoader__.load({
 			};
 		}
 		/**
+		* Bind one row's form to a projection that is stable per raw snapshot and never throws.
+		* @param form - the row's client form, as the settings seat hands it over.
+		* @returns the projection the card's hook reads.
+		*/
+		function stableProjection(form) {
+			let lastRaw;
+			let lastOut;
+			let reported = false;
+			const failed = (error) => {
+				if (!reported) {
+					reported = true;
+					console.error("[evolution-settings] projecting one row failed:", error);
+				}
+				return PROJECTION_FAILED;
+			};
+			return () => {
+				let raw;
+				try {
+					raw = form.getSnapshot();
+				} catch (error) {
+					return failed(error);
+				}
+				if (lastOut !== void 0 && raw === lastRaw) return lastOut;
+				try {
+					const next = sectionSnapshotOf(raw);
+					lastRaw = raw;
+					lastOut = next;
+					return next;
+				} catch (error) {
+					return failed(error);
+				}
+			};
+		}
+		/**
 		* The live source one row's card binds.
-		* @param seat - the probed settings seat, when the deployment composed it.
+		* @param probe - the lazily probed settings seat.
 		* @param namespace - the row's entry id.
-		* @returns the source; without a seat it reports the stated empty state and never notifies.
+		* @returns the source; without a seat it reports the stated empty state, and it re-probes on
+		*   every read so a seat that appears later is picked up without a timer.
 		*/
-		function sourceFor(seat, namespace) {
-			if (seat === void 0) return {
-				getSnapshot: () => SEAT_MISSING,
-				subscribe: () => () => {}
+		function sourceFor(probe, namespace) {
+			const listeners = /* @__PURE__ */ new Set();
+			let form;
+			let projected;
+			let offForm;
+			const bind = () => {
+				if (form !== void 0) return;
+				const seat = probe();
+				if (seat === void 0) return;
+				form = seat.get(namespace);
+				projected = stableProjection(form);
+			};
+			const attach = () => {
+				if (form === void 0 || offForm !== void 0) return;
+				offForm = form.subscribe(() => {
+					for (const listener of listeners) listener();
+				});
 			};
-			const form = seat.get(namespace);
 			return {
-				getSnapshot: () => sectionSnapshotOf(form.getSnapshot()),
-				subscribe: (listener) => form.subscribe(listener)
+				getSnapshot: () => {
+					bind();
+					return projected === void 0 ? SEAT_MISSING : projected();
+				},
+				subscribe: (listener) => {
+					listeners.add(listener);
+					bind();
+					attach();
+					return () => {
+						listeners.delete(listener);
+						if (listeners.size === 0) {
+							offForm?.();
+							offForm = void 0;
+						}
+					};
+				}
 			};
 		}
 		/**
 		* The write pair for one row.
-		* @param seat - the probed settings seat, when the deployment composed it.
+		* @param probe - the lazily probed settings seat.
 		* @param namespace - the row's entry id.
 		* @returns the two calls a card's save/reset path uses; without a seat they resolve without writing.
 		*/
-		function writeFaceFor(seat, namespace) {
-			const form = () => seat?.get(namespace);
+		function writeFaceFor(probe, namespace) {
+			const form = () => probe()?.get(namespace);
 			return {
 				write: async (field, value) => {
 					await form()?.set(field, value);
@@ -1220,6 +1293,30 @@ window.__ModuleLoader__.load({
 				}
 			};
 		}
+		/**
+		* One source object per namespace, for the life of the plugin fiber.
+		*
+		* The renderer caches a hook binding per SOURCE OBJECT, so building a source per render
+		* would re-bind the hook and remount the card. The cache is owned by the caller's fiber and
+		* cleared on dispose.
+		* @param probe - the lazily probed settings seat.
+		* @returns the per-namespace source cache and its disposer.
+		*/
+		function createSourceCache(probe) {
+			const sources = /* @__PURE__ */ new Map();
+			return {
+				sourceFor: (namespace) => {
+					const existing = sources.get(namespace);
+					if (existing !== void 0) return existing;
+					const source = sourceFor(probe, namespace);
+					sources.set(namespace, source);
+					return source;
+				},
+				dispose: () => {
+					sources.clear();
+				}
+			};
+		}
 		//#endregion
 		//#region src/client/RowConfigCard.ts
 		/**
@@ -1462,7 +1559,11 @@ window.__ModuleLoader__.load({
 				}
 				return bound(key);
 			};
-			const configForms = ctx.get("configForms");
+			const probe = () => ctx.get("configForms");
+			const sources = createSourceCache(probe);
+			ctx.effect(() => () => {
+				sources.dispose();
+			}, "evolution-settings: sources");
 			seam.slots.inject("settings.section", function* () {
 				yield seam.slots.register({
 					name: "settings.section",
@@ -1478,8 +1579,8 @@ window.__ModuleLoader__.load({
 			});
 			seam.slots.inject(CARD_SLOT, function* () {
 				for (const section of CLIENT_PARAM_SECTIONS) {
-					const source = sourceFor(configForms, section.namespace);
-					const { write, clear } = writeFaceFor(configForms, section.namespace);
+					const source = sources.sourceFor(section.namespace);
+					const { write, clear } = writeFaceFor(probe, section.namespace);
 					const face = () => ({
 						namespace: section.namespace,
 						fields: section.fields,

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

@@ -19,6 +19,7 @@ export declare const zh: {
     readonly loading: "正在读取设置…";
     readonly unavailable: "这个功能没有启动（对应的插件没有安装）";
     readonly seatMissing: "这个界面没有提供设置服务，参数只能看不能改";
+    readonly projectionFailed: "这一块读设置时出错，已记入日志；其它参数不受影响";
     readonly readonly: "本次会话不允许写入设置（临时运行模式）";
     readonly apply: "保存";
     readonly reset: "恢复默认值";

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

@@ -47,7 +47,7 @@ export interface ParamSectionSnapshot {
      * all, or the seat is there and serves no such row. The two read differently to the
      * operator (one is the UI's own gap, the other is a row that is not composed).
      */
-    reason?: 'seat-missing' | 'not-served';
+    reason?: 'seat-missing' | 'not-served' | 'projection-failed';
 }
 /** The reactive source the renderer binds to a `use<Name>` seat. */
 export interface ParamSectionSource {

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

@@ -4,11 +4,31 @@
  * One place maps `configForms.get(entryId)` to the three things a card needs — a
  * snapshot, a subscription and the two write calls — so our own section's cards and the
  * Plugins page's per-row entry cannot drift apart in how they read or write a row.
+ *
+ * Two invariants live here, both required by the renderer's hook seam:
+ *
+ * - **Stable references.** The renderer binds this source through
+ *   `useSyncExternalStoreWithSelector`, which compares the projected snapshot by reference.
+ *   A `getSnapshot()` that builds a new object on every call never compares equal, so the
+ *   card re-renders until React aborts it (minified invariant #185) and the slot error
+ *   boundary replaces the card with an empty placeholder. The projection therefore caches
+ *   per raw snapshot reference.
+ * - **Never throws.** A throw from `getSnapshot()` happens inside the renderer's render pass,
+ *   where this bundle cannot catch it and a card-level `try`/`catch` around a hook call is
+ *   not legal React. Projection failures return a frozen unavailable snapshot instead.
+ *
+ * The seat itself is probed LAZILY: `apply()` runs before the settings shell may be active
+ * (the shell declares `settings.section` and provides `configForms`), so reading the seat at
+ * apply time would capture `undefined` for the whole life of the fiber.
  * @module @lmzhen/dsh-evolution-settings-ui/client
  */
-import type { ConfigFormSnapshotLike, ConfigFormsSeat, ParamSectionSnapshot, ParamSectionSource } from './seam.ts';
+import type { ConfigFormLike, ConfigFormSnapshotLike, ConfigFormsSeat, ParamSectionSnapshot, ParamSectionSource } from './seam.ts';
 /** What a card shows when this UI found no settings seat at all. */
 export declare const SEAT_MISSING: ParamSectionSnapshot;
+/** What a card shows when the seat served the row but projecting it failed. A frozen constant
+ * 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.
@@ -21,21 +41,49 @@ export declare function isSection(value: unknown): value is Record<string, unkno
  * @returns the card's snapshot, with the reason an unavailable one is unavailable.
  */
 export declare function sectionSnapshotOf(snapshot: ConfigFormSnapshotLike): ParamSectionSnapshot;
+/**
+ * Bind one row's form to a projection that is stable per raw snapshot and never throws.
+ * @param form - the row's client form, as the settings seat hands it over.
+ * @returns the projection the card's hook reads.
+ */
+export declare function stableProjection(form: ConfigFormLike): () => ParamSectionSnapshot;
+/**
+ * The lazily probed client settings seat.
+ *
+ * Probed at read time rather than captured at apply time: this row may activate before the
+ * settings shell, and a captured `undefined` would pin every card to the empty state.
+ * @returns the seat, or undefined while no settings surface is composed.
+ */
+export type SeatProbe = () => ConfigFormsSeat | undefined;
 /**
  * The live source one row's card binds.
- * @param seat - the probed settings seat, when the deployment composed it.
+ * @param probe - the lazily probed settings seat.
  * @param namespace - the row's entry id.
- * @returns the source; without a seat it reports the stated empty state and never notifies.
+ * @returns the source; without a seat it reports the stated empty state, and it re-probes on
+ *   every read so a seat that appears later is picked up without a timer.
  */
-export declare function sourceFor(seat: ConfigFormsSeat | undefined, namespace: string): ParamSectionSource;
+export declare function sourceFor(probe: SeatProbe, namespace: string): ParamSectionSource;
 /**
  * The write pair for one row.
- * @param seat - the probed settings seat, when the deployment composed it.
+ * @param probe - the lazily probed settings seat.
  * @param namespace - the row's entry id.
  * @returns the two calls a card's save/reset path uses; without a seat they resolve without writing.
  */
-export declare function writeFaceFor(seat: ConfigFormsSeat | undefined, namespace: string): {
+export declare function writeFaceFor(probe: SeatProbe, namespace: string): {
     write: (field: string, value: unknown) => Promise<void>;
     clear: (field: string) => Promise<void>;
 };
+/**
+ * One source object per namespace, for the life of the plugin fiber.
+ *
+ * The renderer caches a hook binding per SOURCE OBJECT, so building a source per render
+ * would re-bind the hook and remount the card. The cache is owned by the caller's fiber and
+ * cleared on dispose.
+ * @param probe - the lazily probed settings seat.
+ * @returns the per-namespace source cache and its disposer.
+ */
+export declare function createSourceCache(probe: SeatProbe): {
+    sourceFor: (namespace: string) => ParamSectionSource;
+    dispose: () => void;
+};
 //# sourceMappingURL=source.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.17.0-rc.1",
+  "version": "0.17.1",
   "publishConfig": {
     "access": "public"
   },