@qilin-agent/client-ui-settings 3.1.4 → 3.1.6

package/README.i18n.yaml

@@ -39,8 +39,8 @@
   en: ffd6c51916031c1d
   zh: 703566b0885fd19e
 /qilin-agent-client-ui-settings/understand-the-implementation/schema-service:
-  en: a9247e83278c5d40
-  zh: 051d24681036639d
+  en: aa86a5f5e64362f3
+  zh: 37e9a4da01cf0cf0
 /qilin-agent-client-ui-settings/further-exploration:
   en: 2ce4e8d3a90e61ce
   zh: 9b5510de7f4b320d

package/README.md

@@ -65,7 +65,7 @@ The plugin injects `remote` with its `settings` namespace, resolves Host persist
 
 ### Schema service
 
-`ctx.settingsSchema` performs synchronous schema rehydration, validation, and immutable path editing for settings plugins. A section that is not a plain object, fails its rehydrated schema, or carries a schema envelope this client cannot rehydrate publishes no value at all.
+`ctx.settingsSchema` performs synchronous schema rehydration, validation, and immutable path editing for settings plugins; it delegates to [`@qilin-agent/client-schema-form`](../schema-form/README.md), the shared model layer that shipped editors import directly. A section that is not a plain object, fails its rehydrated schema, or carries a schema envelope this client cannot rehydrate publishes no value at all.
 
 </details>
 

package/README.zh.md

@@ -65,7 +65,7 @@ kind: "package-reference"
 
 ### Schema 服务
 
-`ctx.settingsSchema` 为设置插件执行同步 schema 重建、校验与不可变路径编辑。分区不是普通对象、未通过其重建后的 schema 校验、或携带本客户端无法重建的 schema 信封时，一律不发布任何值。
+`ctx.settingsSchema` 为设置插件执行同步 schema 重建、校验与不可变路径编辑；它委派给 [`@qilin-agent/client-schema-form`](../schema-form/README.zh.md)——随包发布的编辑器直接导入的共享模型层。分区不是普通对象、未通过其重建后的 schema 校验、或携带本客户端无法重建的 schema 信封时，一律不发布任何值。
 
 </details>
 

package/lib/client.js

@@ -897,19 +897,100 @@ window.__ModuleLoader__.load({
 			"preserve"
 		], ({ inner }, isInner) => inner.toString(isInner));
 		//#endregion
-		//#region lib/types/client/schema.js
-		/** Synchronous schema introspection and immutable settings-draft edits. */
+		//#region ../schema-form/src/model.ts
+		/**
+		* Schema introspection and draft-editing helpers behind settings editors.
+		* The serialized schemastery envelope (`schema.toJSON()`) rehydrates into a
+		* live validator whose node relations (`dict`/`inner`) editors probe for
+		* field presence and roles; drafts are edited immutably by path.
+		* @module @qilin-agent/client-schema-form/model
+		*/
+		/**
+		* Rehydrate a serialized schema envelope into a live validator/node tree.
+		* @param serialized - `schema.toJSON()` output received over the wire.
+		* @returns the root schema node.
+		*/
+		function rehydrateSchema(serialized) {
+			return new Schema(serialized);
+		}
+		/**
+		* Validate a draft against a rehydrated schema.
+		* @param schema - rehydrated root node.
+		* @param draft - candidate value.
+		* @returns the validation failure message, or `undefined` when the draft passes.
+		*/
+		function validateDraft(schema, draft) {
+			try {
+				schema(draft);
+				return;
+			} catch (error) {
+				return error instanceof Error ? error.message : String(error);
+			}
+		}
+		/**
+		* Resolve the schema node at a settings path (the configurable-provider
+		* directory's `settingsPath` vocabulary): object properties by name, dict
+		* entries through `inner`. An unresolvable segment returns `undefined` so
+		* the caller falls back instead of rendering a wrong subtree.
+		* @param root - rehydrated section root node.
+		* @param path - key path from the section root.
+		* @returns the node describing that position, or `undefined`.
+		*/
+		function nodeAtPath(root, path) {
+			let node = root;
+			for (const key of path) {
+				if (node === void 0) return void 0;
+				if (node.type === "object") node = node.dict?.[key];
+				else if (node.type === "dict" || node.type === "array") node = node.inner;
+				else return void 0;
+			}
+			return node;
+		}
+		/**
+		* Read a nested value by path.
+		* @param value - root value (draft or fallback layer).
+		* @param path - key path from the root; array indexes as strings.
+		* @returns the value at the path, or `undefined` along a missing branch.
+		*/
+		function getPath(value, path) {
+			let current = value;
+			for (const key of path) {
+				if (Array.isArray(current)) {
+					current = current[Number(key)];
+					continue;
+				}
+				if (typeof current !== "object" || current === null) return void 0;
+				current = current[key];
+			}
+			return current;
+		}
+		/**
+		* Whether a draft explicitly carries the path (its presence marks a user
+		* override, independent of the value stored there).
+		* @param value - root value (draft or fallback layer).
+		* @param path - key path from the root; array indexes as strings.
+		* @returns whether the path's final key exists on its parent.
+		*/
+		function hasPath(value, path) {
+			if (path.length === 0) return value !== void 0;
+			const parent = getPath(value, path.slice(0, -1));
+			const key = path[path.length - 1];
+			if (Array.isArray(parent)) return Number(key) < parent.length;
+			if (typeof parent !== "object" || parent === null) return false;
+			return key in parent;
+		}
 		function cloneContainer(container, key) {
 			if (Array.isArray(container)) return [...container];
 			if (typeof container === "object" && container !== null) return { ...container };
 			return /^\d+$/.test(key) ? [] : {};
 		}
+		/** Clone the container spine down to the leaf's parent, materializing missing intermediates. */
 		function cloneSpine(root, path) {
 			const result = { ...root };
 			let target = result;
-			for (let index = 0; index < path.length - 1; index++) {
-				const key = path[index];
-				const child = cloneContainer(Array.isArray(target) ? target[Number(key)] : target[key], path[index + 1]);
+			for (let i = 0; i < path.length - 1; i++) {
+				const key = path[i];
+				const child = cloneContainer(Array.isArray(target) ? target[Number(key)] : target[key], path[i + 1]);
 				if (Array.isArray(target)) target[Number(key)] = child;
 				else target[key] = child;
 				target = child;
@@ -921,8 +1002,45 @@ window.__ModuleLoader__.load({
 			};
 		}
 		/**
+		* Immutably set a nested value, materializing missing intermediate containers.
+		* @param root - draft root (never mutated).
+		* @param path - non-empty key path.
+		* @param value - value to store at the path.
+		* @returns the new draft root.
+		* @throws when `path` is empty.
+		*/
+		function setPath(root, path, value) {
+			if (path.length === 0) throw new Error("schema-form: setPath needs a non-empty path");
+			const { result, parent, leaf } = cloneSpine(root, path);
+			if (Array.isArray(parent)) parent[Number(leaf)] = value;
+			else parent[leaf] = value;
+			return result;
+		}
+		/**
+		* Immutably remove a nested key (the per-field reset: the resolved value
+		* falls back to the composition base and schema defaults). Removing along a
+		* missing branch returns the root unchanged.
+		* @param root - draft root (never mutated).
+		* @param path - non-empty key path.
+		* @returns the new draft root.
+		* @throws when `path` is empty.
+		*/
+		function deletePath(root, path) {
+			if (path.length === 0) throw new Error("schema-form: deletePath needs a non-empty path");
+			if (!hasPath(root, path)) return root;
+			const { result, parent, leaf } = cloneSpine(root, path);
+			if (Array.isArray(parent)) parent.splice(Number(leaf), 1);
+			else Reflect.deleteProperty(parent, leaf);
+			return result;
+		}
+		//#endregion
+		//#region lib/types/client/schema.js
+		/** Synchronous schema introspection and immutable settings-draft edits. */
+		/**
 		* Settings-owned synchronous schema service. Dynamic client plugins receive
-		* this Cordis entity instead of importing executable helpers from one another.
+		* this Cordis entity instead of importing executable helpers from one another;
+		* it delegates to the shared schema/draft model layer so one implementation
+		* backs both this service and the shipped editors that import it directly.
 		*/
 		var SettingsSchemaService = class extends _qilin_agent_kylin.Service {
 			/** @param ctx - providing ui-settings context. */
@@ -935,7 +1053,7 @@ window.__ModuleLoader__.load({
 			* @returns live schema node.
 			*/
 			rehydrate(serialized) {
-				return new Schema(serialized);
+				return rehydrateSchema(serialized);
 			}
 			/**
 			* Validate a settings draft.
@@ -944,12 +1062,7 @@ window.__ModuleLoader__.load({
 			* @returns validation failure text, or `undefined` when valid.
 			*/
 			validate(schema, draft) {
-				try {
-					schema(draft);
-					return;
-				} catch (error) {
-					return error instanceof Error ? error.message : String(error);
-				}
+				return validateDraft(schema, draft);
 			}
 			/**
 			* Resolve an object, dict, or array schema node at a settings path.
@@ -958,14 +1071,7 @@ window.__ModuleLoader__.load({
 			* @returns the resolved node, or `undefined` when the path is absent.
 			*/
 			nodeAtPath(root, path) {
-				let node = root;
-				for (const key of path) {
-					if (node === void 0) return void 0;
-					if (node.type === "object") node = node.dict?.[key];
-					else if (node.type === "dict" || node.type === "array") node = node.inner;
-					else return void 0;
-				}
-				return node;
+				return nodeAtPath(root, path);
 			}
 			/**
 			* Read a nested value by a string-key or array-index path.
@@ -974,16 +1080,7 @@ window.__ModuleLoader__.load({
 			* @returns the resolved value, or `undefined` when the path is absent.
 			*/
 			getPath(value, path) {
-				let current = value;
-				for (const key of path) {
-					if (Array.isArray(current)) {
-						current = current[Number(key)];
-						continue;
-					}
-					if (typeof current !== "object" || current === null) return void 0;
-					current = current[key];
-				}
-				return current;
+				return getPath(value, path);
 			}
 			/**
 			* Report whether the final path key exists independently of its value.
@@ -992,12 +1089,7 @@ window.__ModuleLoader__.load({
 			* @returns whether the path exists.
 			*/
 			hasPath(value, path) {
-				if (path.length === 0) return value !== void 0;
-				const parent = this.getPath(value, path.slice(0, -1));
-				const key = path[path.length - 1];
-				if (Array.isArray(parent)) return Number(key) < parent.length;
-				if (typeof parent !== "object" || parent === null) return false;
-				return key in parent;
+				return hasPath(value, path);
 			}
 			/**
 			* Immutably set a nested value, materializing missing containers.
@@ -1008,11 +1100,7 @@ window.__ModuleLoader__.load({
 			* @throws when `path` is empty.
 			*/
 			setPath(root, path, value) {
-				if (path.length === 0) throw new Error("ui-settings: setPath needs a non-empty path");
-				const { result, parent, leaf } = cloneSpine(root, path);
-				if (Array.isArray(parent)) parent[Number(leaf)] = value;
-				else parent[leaf] = value;
-				return result;
+				return setPath(root, path, value);
 			}
 			/**
 			* Immutably remove a nested key, preserving an unchanged missing root.
@@ -1022,12 +1110,7 @@ window.__ModuleLoader__.load({
 			* @throws when `path` is empty.
 			*/
 			deletePath(root, path) {
-				if (path.length === 0) throw new Error("ui-settings: deletePath needs a non-empty path");
-				if (!this.hasPath(root, path)) return root;
-				const { result, parent, leaf } = cloneSpine(root, path);
-				if (Array.isArray(parent)) parent.splice(Number(leaf), 1);
-				else Reflect.deleteProperty(parent, leaf);
-				return result;
+				return deletePath(root, path);
 			}
 		};
 		//#endregion

package/lib/index.js

@@ -5,16 +5,18 @@ import z from "@qilin-agent/schemastery";
 const DEVELOPER_TOOLS_NAMESPACE = "ui-settings";
 /** New installations and missing values enable the full interface. */
 const DeveloperToolsSettingsFields = { enabled: z.boolean().default(true) };
-/** Durable developer-tools schema; also the wire envelope the browser scope validates against. */
-const DeveloperToolsSettingsSchema = z.object({ enabled: DeveloperToolsSettingsFields["enabled"] });
+z.object({ enabled: DeveloperToolsSettingsFields["enabled"] });
 //#endregion
 //#region lib/types/index.js
-/** Host registration for the shared developer-tool preference. */
-/** Register the durable developer-tools section when a provider exists. */
+/** Live preferences projected to the browser. */
+const Config = z.object({ enabled: DeveloperToolsSettingsFields["enabled"].volatile() });
+/** Host preferences are consumed through the configuration form projection.
+* @param ctx Plugin context used for optional settings presentation.
+*/
 function apply(ctx) {
-	ctx.inject(["settings"], (settingsCtx) => {
-		settingsCtx.settings.register(DEVELOPER_TOOLS_NAMESPACE, DeveloperToolsSettingsSchema);
+	ctx.inject(["settings"], (child) => {
+		child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
 	});
 }
 //#endregion
-export { DEVELOPER_TOOLS_NAMESPACE, apply };
+export { Config, DEVELOPER_TOOLS_NAMESPACE, apply };

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

@@ -1,12 +1,13 @@
 /** Synchronous schema introspection and immutable settings-draft edits. */
 import { Service } from '@qilin-agent/kylin';
 import type { Context } from '@qilin-agent/kylin';
-import Schema from '@qilin-agent/schemastery';
-/** Live schemastery node used for settings introspection and validation. */
-export type SchemaNode = Schema;
+import { type SchemaNode } from '@qilin-agent/client-schema-form';
+export type { SchemaNode };
 /**
  * Settings-owned synchronous schema service. Dynamic client plugins receive
- * this Cordis entity instead of importing executable helpers from one another.
+ * this Cordis entity instead of importing executable helpers from one another;
+ * it delegates to the shared schema/draft model layer so one implementation
+ * backs both this service and the shipped editors that import it directly.
  */
 export declare class SettingsSchemaService extends Service {
     /** @param ctx - providing ui-settings context. */

package/lib/types/index.d.ts

@@ -1,6 +1,19 @@
-/** Host registration for the shared developer-tool preference. */
-import type { Context } from '@qilin-agent/kylin';
+import type { Volatile, Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
 export { DEVELOPER_TOOLS_NAMESPACE, type DeveloperToolsSettings } from './developer-tools-settings.ts';
-/** Register the durable developer-tools section when a provider exists. */
+/** Runtime preferences projected to the browser. */
+export interface Config {
+    /** Whether developer tools are enabled. */
+    enabled: Volatile<boolean>;
+}
+/** Live preferences projected to the browser. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    enabled: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/** Host preferences are consumed through the configuration form projection.
+ * @param ctx Plugin context used for optional settings presentation.
+ */
 export declare function apply(ctx: Context): void;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/client-ui-settings",
   "description": "Settings domain base plugin: the settings-namespace scope service and the canonical settings slot-type contract",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "publishConfig": {
     "access": "public"
   },
@@ -38,18 +38,19 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/kylin": "~4.0.3"
+    "@qilin-agent/kylin": "~4.0.5"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
-    "@qilin-agent/api-remotes": "3.1.4",
-    "@qilin-agent/client-store": "3.1.4",
-    "@qilin-agent/client-test-runtime": "3.1.4",
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/client-ui-slots": "3.1.4",
-    "@qilin-agent/settings": "3.1.4",
-    "@qilin-agent/util-values": "3.1.4"
+    "@qilin-agent/api-remotes": "3.1.6",
+    "@qilin-agent/client-schema-form": "3.1.6",
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/client-test-runtime": "3.1.6",
+    "@qilin-agent/client-store": "3.1.6",
+    "@qilin-agent/client-ui-slots": "3.1.6",
+    "@qilin-agent/settings": "3.1.6",
+    "@qilin-agent/util-values": "3.1.6"
   },
   "files": [
     "lib/index.js",
@@ -57,7 +58,7 @@
     "lib/types/**/*.d.ts"
   ],
   "dependencies": {
-    "@qilin-agent/schemastery": "~3.18.3"
+    "@qilin-agent/schemastery": "~3.18.5"
   },
   "scripts": {
     "bundle": "tsdown",