@deepseek-ai/dsh-client-locale 0.1.6-alpha.1 → 0.1.7-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/locale/README.md
-README.md: 56a9cff9c3ec18dcc395378fcd1691207c022284
-README.zh.md: 1b7a7b7de48843961f3cbac3f4ee99cff641d212
+README.md: a21f61dd931204f990e6865419ac19476c957ff4
+README.zh.md: c93b555f96e459ddad56faaf46d267cf319218ad

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-Use `dsh-client-locale` to switch the web GUI between the shipped English and Chinese locales or languages added by client plugins. User selections take effect immediately; loopback pages persist them in `$DSH_HOME/settings.yaml`, while non-loopback pages keep them only for the current process. New browsers use the first supported language requested by the browser until an allowed stored preference arrives. Plugin authors add typed namespace dictionaries and translate through the public locale API; slot-rendered copy updates without a reload.
+Use `dsh-client-locale` to switch the web GUI between the shipped English and Chinese locales or languages added by client plugins. User selections take effect immediately; loopback pages persist them in `$DSH_HOME/cordis.patch.yml`, while non-loopback pages keep them only for the current process. New browsers use the first supported language requested by the browser until an allowed stored preference arrives. Plugin authors add typed namespace dictionaries and translate through the public locale API; slot-rendered copy updates without a reload.
 
 ## Table of Contents
 
@@ -31,10 +31,16 @@ Use it wherever the web GUI needs a language switch or translated copy: the ship
 
 Open Settings → General and select a registered language. The active locale is applied immediately: the UI copy switches, `<html lang>` points at the external id or built-in document tag, and the choice is written to the durable settings section. A browser without an explicit Host preference selects the first registered language that matches `navigator` by full tag and then primary subtag, falling back to English. A stored external locale waits for its definition to register instead of becoming active while unavailable.
 
+Native shells may provide `__DSH_LOCALE__` with an asynchronous `read()` and an `onChange(locale)` callback. Initialization supplies the current Host preference and ordered OS languages before the Client mounts. Automatic selection stays provisional; only Settings selections write `locale.preference`. A fresh read on each page load prevents a stale preload preference after reload. Ordinary browsers keep navigator-based detection and their existing settings-scope policy.
+
 ### Registering a dictionary
 
 Call `ctx.locale.register(ns, { zh, en })` with a namespace merged into `LocaleNamespaceMap`; the compiler checks every key against the namespace's typed key union and requires both shipped locales. Consumers translate through `ctx.locale.bind(ns)` or the framework-injected `t` seat. A dictionary registered after the UI is already mounted is picked up without a remount.
 
+### Resolving package text
+
+Use `ctx.locale.resolveText(text)` for [`LocalizedText`](../../util/package-manifest/README.md), such as installed plugin titles and descriptions. Literal strings are returned unchanged. Translation maps use lowercase language ids, require an `en` fallback, and follow the active language's declared fallback chain. They do not consult or register namespace dictionaries.
+
 ### Registering a language pack
 
 An external client plugin registers the language definition and each translated namespace as owned effects; definitions and dictionaries may register in either order:
@@ -83,6 +89,8 @@ The provisional locale comes from the browser (`navigator.languages` matched by
 
 ### Dictionary lookup
 
+Document language synchronization writes `<html lang>` only when its value changes; dictionary-only revisions leave the attribute untouched.
+
 The typed object form requires complete dictionaries for both built-in locales. The per-locale form lets language packs register each namespace independently. For each key, lookup walks the active language's declared fallback chain in the requested namespace, repeats that chain in `common`, then displays the key itself. Bound translate functions retain stable identity per namespace so they can ride inject surfaces without breaking memoization.
 
 ### Source map

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-使用 `dsh-client-locale` 可在 web GUI 中切换内置的英文和中文 locale，或 client 插件添加的语言。用户选择会立即生效；loopback 页面把选择持久化到 `$DSH_HOME/settings.yaml`，非 loopback 页面则只为当前进程保留选择。全新浏览器会使用浏览器请求的第一个受支持语言，直到允许读取的已存储偏好到达。插件作者可添加类型化命名空间字典，并通过公开 locale API 翻译；经 slot 渲染的文案无需重新加载即可随语言切换更新。
+使用 `dsh-client-locale` 可在 web GUI 中切换内置的英文和中文 locale，或 client 插件添加的语言。用户选择会立即生效；loopback 页面把选择持久化到 `$DSH_HOME/cordis.patch.yml`，非 loopback 页面则只为当前进程保留选择。全新浏览器会使用浏览器请求的第一个受支持语言，直到允许读取的已存储偏好到达。插件作者可添加类型化命名空间字典，并通过公开 locale API 翻译；经 slot 渲染的文案无需重新加载即可随语言切换更新。
 
 ## 目录
 
@@ -31,10 +31,16 @@ kind: "package-reference"
 
 打开“设置 → 常规”并选择一种已注册语言。生效中的 locale 会立即应用：UI 文案切换、`<html lang>` 指向外部 id 或内置语言的文档标签，选择写入持久设置分区。没有显式 Host 偏好的浏览器会按完整标签、再按主语言子标签选择 `navigator` 请求的第一个已注册语言，无法匹配时回退到英文。已存储的外部 locale 会等待其定义注册，不会在不可用时生效。
 
+原生壳可以提供包含异步 `read()` 和 `onChange(locale)` 回调的 `__DSH_LOCALE__`。初始化在 Client 挂载前提供当前 Host 偏好和有序的系统语言列表。自动选择保持临时状态；只有设置中的选择会写入 `locale.preference`。每次加载页面都重新读取，避免重载后沿用过期的 preload 偏好。普通浏览器继续使用 navigator 检测和原有的设置作用域策略。
+
 ### 注册字典
 
 用已合并进 `LocaleNamespaceMap` 的命名空间调用 `ctx.locale.register(ns, { zh, en })`；编译器会对照该命名空间的类型化键并集检查每个键，并要求两个内置 locale 齐全。消费方通过 `ctx.locale.bind(ns)` 或框架注入的 `t` 席位翻译。UI 已挂载后再注册的字典无需重新挂载即可生效。
 
+### 解析包文本
+
+使用 `ctx.locale.resolveText(text)` 解析 [`LocalizedText`](../../util/package-manifest/README.zh.md)，例如已安装插件的标题与描述。字面字符串原样返回。翻译映射使用小写语言 id，必须提供 `en` 回退值，并沿当前语言声明的回退链查找。它们不查询或注册命名空间字典。
+
 ### 注册语言包
 
 外部 client 插件把语言定义和每个已翻译命名空间注册为自身拥有的 effect；定义与字典可以按任意顺序注册：
@@ -83,6 +89,8 @@ Host 通过 settings 服务为 loopback 页面持久化偏好。Client 会刻意
 
 ### 字典查找
 
+文档语言同步只在值变化时写入 `<html lang>`；仅更新字典的 revision 不改动该属性。
+
 带类型的对象形式要求两个内置 locale 都有完整字典；逐 locale 形式允许语言包独立注册每个命名空间。逐键查找会先在请求命名空间中沿生效语言声明的 fallback 链查找，再在 `common` 中重复该链，最后显示键本身。绑定的翻译函数按命名空间保持稳定身份，因此可通过 inject 机制传递，且不会破坏 memoization。
 
 ### 源码地图

package/lib/client.js

@@ -8,7 +8,22 @@ window.__ModuleLoader__.load({
 		let react = require("react");
 		let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
 		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
-		//#region ../../../vendor/cosmokit/src/misc.ts
+		//#region lib/types/client/bootstrap.js
+		/** Locale initialization supplied by a native shell before its Client tree mounts. */
+		/**
+		* Validate initialization data returned over the preload IPC bridge.
+		* @param value - untrusted IPC response.
+		* @returns language initialization with no persistence side effects.
+		*/
+		function parseLocaleBootstrap(value) {
+			if (typeof value !== "object" || value === null || !("languages" in value) || !Array.isArray(value.languages) || !value.languages.every((language) => typeof language === "string") || !("preference" in value) || value.preference !== null && typeof value.preference !== "string") throw new TypeError("locale: invalid native initialization data");
+			return {
+				languages: value.languages,
+				preference: value.preference
+			};
+		}
+		//#endregion
+		//#region ../../../vendor/cosmokit/lib/index.js
 		/** Return true when a value is `null` or `undefined`. */
 		function isNullable(value) {
 			return value === null || value === void 0;
@@ -32,8 +47,43 @@ window.__ModuleLoader__.load({
 			for (const key of keys) if (forced || source[key] !== void 0) result[key] = source[key];
 			return result;
 		}
-		//#endregion
-		//#region ../../../vendor/cosmokit/src/types.ts
+		/** Shared config references used by schema validators and plugin runtimes. */
+		const write = Symbol.for("cosmokit.volatile.write");
+		function snapshot(value, ancestors = /* @__PURE__ */ new Set()) {
+			if (typeof value === "function") throw new TypeError("volatile config cannot contain functions");
+			if (value === null || typeof value !== "object") return value;
+			if (ancestors.has(value)) throw new TypeError("volatile config cannot contain cycles");
+			ancestors.add(value);
+			try {
+				if (Array.isArray(value)) return Object.freeze(value.map((item) => snapshot(item, ancestors)));
+				if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new TypeError("volatile config objects must be plain objects or arrays");
+				return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, snapshot(item, ancestors)])));
+			} finally {
+				ancestors.delete(value);
+			}
+		}
+		/**
+		* Create a detached reference containing an immutable copy of the supplied data.
+		* @param value - validated config data; class instances and functions are unsupported.
+		* @returns a reference whose value is updated only by its owning runtime.
+		*/
+		function createVolatile(value) {
+			let current = snapshot(value);
+			return Object.freeze({
+				get: () => current,
+				[write]: (value) => {
+					current = value;
+				}
+			});
+		}
+		/**
+		* Identify references across ESM/CJS copies of the shared library.
+		* @param value - a parsed config value.
+		* @returns whether the value implements the shared reference protocol.
+		*/
+		function isVolatile(value) {
+			return typeof value === "object" && value !== null && write in value;
+		}
 		/** Test values using `instanceof` with a `toStringTag` fallback. */
 		function is(type, value) {
 			if (arguments.length === 1) return (value) => is(type, value);
@@ -45,15 +95,16 @@ window.__ModuleLoader__.load({
 		function isArrayBufferSource(value) {
 			return isArrayBufferLike(value) || ArrayBuffer.isView(value);
 		}
-		let Binary;
-		(function(_Binary) {
-			_Binary.is = isArrayBufferLike;
-			_Binary.isSource = isArrayBufferSource;
+		/** Binary source detection and base64/hex conversion helpers. */
+		var Binary;
+		(function(Binary) {
+			Binary.is = isArrayBufferLike;
+			Binary.isSource = isArrayBufferSource;
 			function fromSource(source) {
 				if (ArrayBuffer.isView(source)) return source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength);
 				else return source;
 			}
-			_Binary.fromSource = fromSource;
+			Binary.fromSource = fromSource;
 			function toBase64(source) {
 				source = fromSource(source);
 				if (typeof Buffer !== "undefined") return Buffer.from(source).toString("base64");
@@ -62,18 +113,18 @@ window.__ModuleLoader__.load({
 				for (let i = 0; i < bytes.byteLength; i++) binary += String.fromCharCode(bytes[i]);
 				return btoa(binary);
 			}
-			_Binary.toBase64 = toBase64;
+			Binary.toBase64 = toBase64;
 			function fromBase64(source) {
 				if (typeof Buffer !== "undefined") return fromSource(Buffer.from(source, "base64"));
 				return Uint8Array.from(atob(source), (c) => c.charCodeAt(0));
 			}
-			_Binary.fromBase64 = fromBase64;
+			Binary.fromBase64 = fromBase64;
 			function toHex(source) {
 				source = fromSource(source);
 				if (typeof Buffer !== "undefined") return Buffer.from(source).toString("hex");
 				return Array.from(new Uint8Array(source), (byte) => byte.toString(16).padStart(2, "0")).join("");
 			}
-			_Binary.toHex = toHex;
+			Binary.toHex = toHex;
 			function fromHex(source) {
 				if (typeof Buffer !== "undefined") return fromSource(Buffer.from(source, "hex"));
 				const hex = source.length % 2 === 0 ? source : source.slice(0, source.length - 1);
@@ -81,7 +132,7 @@ window.__ModuleLoader__.load({
 				for (let i = 0; i < hex.length; i += 2) buffer.push(parseInt(`${hex[i]}${hex[i + 1]}`, 16));
 				return Uint8Array.from(buffer).buffer;
 			}
-			_Binary.fromHex = fromHex;
+			Binary.fromHex = fromHex;
 		})(Binary || (Binary = {}));
 		Binary.fromBase64;
 		Binary.toBase64;
@@ -113,58 +164,78 @@ window.__ModuleLoader__.load({
 			}
 			return result;
 		}
-		/** Deeply compare arrays, dates, regexps, buffers, and plain object fields. */
+		/**
+		* Compare values recursively, treating two volatile references as equal regardless of value.
+		* Strict comparison distinguishes null/undefined, treats opaque objects by identity,
+		* compares URLs by normalized href, treats array holes as undefined, and considers distinct cyclic structures unequal.
+		* @param a - first value.
+		* @param b - second value.
+		* @param strict - whether to require strict data equality outside volatile references.
+		* @returns whether the values compare equal.
+		*/
 		function deepEqual(a, b, strict) {
-			if (a === b) return true;
-			if (!strict && isNullable(a) && isNullable(b)) return true;
-			if (typeof a !== typeof b) return false;
-			if (typeof a !== "object") return false;
-			if (!a || !b) return false;
-			function check(test, then) {
-				return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : void 0;
+			const ancestors = /* @__PURE__ */ new Set();
+			function compare(a, b) {
+				if (a === b) return true;
+				if (isVolatile(a) || isVolatile(b)) return isVolatile(a) && isVolatile(b);
+				if (!strict && isNullable(a) && isNullable(b)) return true;
+				if (typeof a !== typeof b || typeof a !== "object" || !a || !b) return false;
+				if (ancestors.has(a)) return false;
+				function check(test, then) {
+					return test(a) ? test(b) ? then(a, b) : false : test(b) ? false : void 0;
+				}
+				ancestors.add(a);
+				try {
+					return check(Array.isArray, (a, b) => {
+						if (a.length !== b.length) return false;
+						for (let index = 0; index < a.length; index++) if (!compare(a[index], b[index])) return false;
+						return true;
+					}) ?? check(is("Date"), (a, b) => a.valueOf() === b.valueOf()) ?? check(is("URL"), (a, b) => a.href === b.href) ?? check(is("RegExp"), (a, b) => a.source === b.source && a.flags === b.flags) ?? check(isArrayBufferLike, (a, b) => {
+						if (a.byteLength !== b.byteLength) return false;
+						const viewA = new Uint8Array(a);
+						const viewB = new Uint8Array(b);
+						for (let i = 0; i < viewA.length; i++) if (viewA[i] !== viewB[i]) return false;
+						return true;
+					}) ?? ((!strict || [a, b].every((value) => Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) && Object.keys({
+						...a,
+						...b
+					}).every((key) => compare(a[key], b[key])));
+				} finally {
+					ancestors.delete(a);
+				}
 			}
-			return check(Array.isArray, (a, b) => a.length === b.length && a.every((item, index) => deepEqual(item, b[index]))) ?? check(is("Date"), (a, b) => a.valueOf() === b.valueOf()) ?? check(is("RegExp"), (a, b) => a.source === b.source && a.flags === b.flags) ?? check(isArrayBufferLike, (a, b) => {
-				if (a.byteLength !== b.byteLength) return false;
-				const viewA = new Uint8Array(a);
-				const viewB = new Uint8Array(b);
-				for (let i = 0; i < viewA.length; i++) if (viewA[i] !== viewB[i]) return false;
-				return true;
-			}) ?? Object.keys({
-				...a,
-				...b
-			}).every((key) => deepEqual(a[key], b[key], strict));
+			return compare(a, b);
 		}
-		//#endregion
-		//#region ../../../vendor/cosmokit/src/time.ts
-		let Time;
-		(function(_Time) {
-			_Time.millisecond = 1;
-			const second = _Time.second = 1e3;
-			const minute = _Time.minute = second * 60;
-			const hour = _Time.hour = minute * 60;
-			const day = _Time.day = hour * 24;
-			const week = _Time.week = day * 7;
+		/** Time constants plus parsing and formatting helpers. */
+		var Time;
+		(function(Time) {
+			Time.millisecond = 1;
+			Time.second = 1e3;
+			Time.minute = Time.second * 60;
+			Time.hour = Time.minute * 60;
+			Time.day = Time.hour * 24;
+			Time.week = Time.day * 7;
 			let timezoneOffset = (/* @__PURE__ */ new Date()).getTimezoneOffset();
 			function setTimezoneOffset(offset) {
 				timezoneOffset = offset;
 			}
-			_Time.setTimezoneOffset = setTimezoneOffset;
+			Time.setTimezoneOffset = setTimezoneOffset;
 			function getTimezoneOffset() {
 				return timezoneOffset;
 			}
-			_Time.getTimezoneOffset = getTimezoneOffset;
+			Time.getTimezoneOffset = getTimezoneOffset;
 			function getDateNumber(date = /* @__PURE__ */ new Date(), offset) {
 				if (typeof date === "number") date = new Date(date);
 				if (offset === void 0) offset = timezoneOffset;
-				return Math.floor((date.valueOf() / minute - offset) / 1440);
+				return Math.floor((date.valueOf() / Time.minute - offset) / 1440);
 			}
-			_Time.getDateNumber = getDateNumber;
+			Time.getDateNumber = getDateNumber;
 			function fromDateNumber(value, offset) {
-				const date = new Date(value * day);
+				const date = new Date(value * Time.day);
 				if (offset === void 0) offset = timezoneOffset;
-				return new Date(+date + offset * minute);
+				return new Date(+date + offset * Time.minute);
 			}
-			_Time.fromDateNumber = fromDateNumber;
+			Time.fromDateNumber = fromDateNumber;
 			const numeric = /\d+(?:\.\d+)?/.source;
 			const timeRegExp = new RegExp(`^${[
 				"w(?:eek(?:s)?)?",
@@ -176,9 +247,9 @@ window.__ModuleLoader__.load({
 			function parseTime(source) {
 				const capture = timeRegExp.exec(source);
 				if (!capture) return 0;
-				return (parseFloat(capture[1]) * week || 0) + (parseFloat(capture[2]) * day || 0) + (parseFloat(capture[3]) * hour || 0) + (parseFloat(capture[4]) * minute || 0) + (parseFloat(capture[5]) * second || 0);
+				return (parseFloat(capture[1]) * Time.week || 0) + (parseFloat(capture[2]) * Time.day || 0) + (parseFloat(capture[3]) * Time.hour || 0) + (parseFloat(capture[4]) * Time.minute || 0) + (parseFloat(capture[5]) * Time.second || 0);
 			}
-			_Time.parseTime = parseTime;
+			Time.parseTime = parseTime;
 			function parseDate(date) {
 				const parsed = parseTime(date);
 				if (parsed) date = Date.now() + parsed;
@@ -186,27 +257,27 @@ window.__ModuleLoader__.load({
 				else if (/^\d{1,2}-\d{1,2}-\d{1,2}(:\d{1,2}){1,2}$/.test(date)) date = `${(/* @__PURE__ */ new Date()).getFullYear()}-${date}`;
 				return date ? new Date(date) : /* @__PURE__ */ new Date();
 			}
-			_Time.parseDate = parseDate;
+			Time.parseDate = parseDate;
 			function format(ms) {
 				const abs = Math.abs(ms);
-				if (abs >= day - hour / 2) return Math.round(ms / day) + "d";
-				else if (abs >= hour - minute / 2) return Math.round(ms / hour) + "h";
-				else if (abs >= minute - second / 2) return Math.round(ms / minute) + "m";
-				else if (abs >= second) return Math.round(ms / second) + "s";
+				if (abs >= Time.day - Time.hour / 2) return Math.round(ms / Time.day) + "d";
+				else if (abs >= Time.hour - Time.minute / 2) return Math.round(ms / Time.hour) + "h";
+				else if (abs >= Time.minute - Time.second / 2) return Math.round(ms / Time.minute) + "m";
+				else if (abs >= Time.second) return Math.round(ms / Time.second) + "s";
 				return ms + "ms";
 			}
-			_Time.format = format;
+			Time.format = format;
 			function toDigits(source, length = 2) {
 				return source.toString().padStart(length, "0");
 			}
-			_Time.toDigits = toDigits;
+			Time.toDigits = toDigits;
 			function template(template, time = /* @__PURE__ */ new Date()) {
 				return template.replace("yyyy", time.getFullYear().toString()).replace("yy", time.getFullYear().toString().slice(2)).replace("MM", toDigits(time.getMonth() + 1)).replace("dd", toDigits(time.getDate())).replace("hh", toDigits(time.getHours())).replace("mm", toDigits(time.getMinutes())).replace("ss", toDigits(time.getSeconds())).replace("SSS", toDigits(time.getMilliseconds(), 3));
 			}
-			_Time.template = template;
+			Time.template = template;
 		})(Time || (Time = {}));
 		//#endregion
-		//#region ../../../vendor/schemastery/src/index.ts
+		//#region ../../../vendor/schemastery/lib/index.mjs
 		const kSchema = Symbol.for("schemastery");
 		const kValidationError = Symbol.for("ValidationError");
 		globalThis.__schemastery_index__ ??= 0;
@@ -382,6 +453,7 @@ window.__ModuleLoader__.load({
 			return schema;
 		};
 		Schema.prototype.simplify = function simplify(value) {
+			if (isVolatile(value)) value = value.get();
 			if (deepEqual(value, this.meta.default, this.type === "dict")) return null;
 			if (isNullable(value)) return value;
 			if (this.type === "object" || this.type === "dict") {
@@ -438,12 +510,49 @@ window.__ModuleLoader__.load({
 			};
 			return schema;
 		} });
+		Schema.prototype.volatile = function volatile() {
+			if (this.meta.volatile) throw new TypeError("volatile schema is already wrapped");
+			return this.extra("volatile", true);
+		};
 		const resolvers = {};
+		const checkedVolatile = Symbol("checked-volatile-schema");
+		function validateVolatileSchema(schema, path = [], blocked = false, seen = /* @__PURE__ */ new Map()) {
+			const states = seen.get(schema) ?? /* @__PURE__ */ new Set();
+			if (states.has(blocked)) return;
+			states.add(blocked);
+			seen.set(schema, states);
+			if (schema.meta?.volatile && blocked) throw new ValidationError("volatile fields require a fixed object path without an enclosing volatile field", { path });
+			const nested = blocked || !!schema.meta?.volatile;
+			if (schema.dict) for (const [key, child] of Object.entries(schema.dict)) validateVolatileSchema(child, [...path, key], nested, seen);
+			if (schema.sKey) validateVolatileSchema(schema.sKey, [...path, "<key>"], true, seen);
+			if (schema.inner && (schema.type !== "lazy" || schema.inner[kSchema])) validateVolatileSchema(schema.inner, [...path, "*"], true, seen);
+			if (schema.list) for (let index = 0; index < schema.list.length; index++) validateVolatileSchema(schema.list[index], [...path, String(index)], true, seen);
+		}
 		Schema.extend = function extend(type, resolve) {
 			resolvers[type] = resolve;
 		};
 		Schema.resolve = function resolve(data, schema, options = {}, strict = false) {
 			if (!schema) return [data];
+			if (!options[checkedVolatile]) {
+				validateVolatileSchema(schema, options.path);
+				options = {
+					...options,
+					[checkedVolatile]: true
+				};
+			}
+			if (schema.meta?.volatile) {
+				const inner = Schema(schema);
+				inner.meta = {
+					...schema.meta,
+					volatile: false
+				};
+				const [value, adapted] = Schema.resolve(data, inner, options, strict);
+				try {
+					return [createVolatile(value), adapted];
+				} catch (error) {
+					throw new ValidationError(error instanceof Error ? error.message : String(error), options);
+				}
+			}
 			if (options.ignore?.(data, schema)) return [data];
 			if (isNullable(data) && schema.type !== "lazy") {
 				if (schema.meta.required) throw new ValidationError(`missing required value`, options);
@@ -546,6 +655,7 @@ window.__ModuleLoader__.load({
 					...schema.meta,
 					...schema.inner.meta
 				};
+				validateVolatileSchema(schema.inner, options.path, true);
 			}
 			return Schema.resolve(data, schema.inner, options, strict);
 		});
@@ -645,7 +755,7 @@ window.__ModuleLoader__.load({
 			} catch (e) {
 				if (!options?.autofix) throw e;
 				delete data[key];
-				return schema.meta.default;
+				return schema.meta.volatile ? createVolatile(schema.meta.default) : schema.meta.default;
 			}
 		}
 		Schema.extend("array", (data, { inner, meta }, options) => {
@@ -810,7 +920,9 @@ window.__ModuleLoader__.load({
 		const LOCALE_ID_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
 		/** Locale identifiers shipped by the browser client. */
 		const LOCALE_IDS = ["zh", "en"];
-		Schema.object({ [LOCALE_PREFERENCE_FIELD]: Schema.string().pattern(LOCALE_ID_PATTERN).required(false) });
+		/** Durable locale schema; also the wire envelope the browser scope validates against. */
+		const LocaleSettingsFields = { [LOCALE_PREFERENCE_FIELD]: Schema.string().pattern(LOCALE_ID_PATTERN).required(false) };
+		Schema.object(LocaleSettingsFields);
 		//#endregion
 		//#region lib/types/locales/zh.js
 		/** zh base dictionary for the common namespace: cross-feature standard words. */
@@ -970,7 +1082,7 @@ window.__ModuleLoader__.load({
 						onClick: () => {
 							setOpen((v) => !v);
 						},
-						children: [activeLabel, (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14, { className: LanguageRow_module_css_default.chevron })]
+						children: [activeLabel, (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutlineRegular, { className: LanguageRow_module_css_default.chevron })]
 					})
 				})]
 			});
@@ -1051,7 +1163,8 @@ window.__ModuleLoader__.load({
 		*/
 		function syncDocumentLanguage(snapshot) {
 			if (typeof document === "undefined") return;
-			document.documentElement.lang = snapshot.active === "zh" ? "zh-CN" : snapshot.active;
+			const language = snapshot.active === "zh" ? "zh-CN" : snapshot.active;
+			if (document.documentElement.lang !== language) document.documentElement.lang = language;
 		}
 		/**
 		* Dictionary registry plus locale preference. Lookup walks the active
@@ -1064,6 +1177,7 @@ window.__ModuleLoader__.load({
 		* `ctx.slots.installLocale`.
 		*/
 		var LocaleRuntime = class {
+			bootstrap;
 			dicts = /* @__PURE__ */ new Map();
 			bound = /* @__PURE__ */ new Map();
 			catalog = /* @__PURE__ */ new Map();
@@ -1081,15 +1195,18 @@ window.__ModuleLoader__.load({
 			* listener is released through ctx.effect on dispose).
 			* @param host - durable preference scope owned by the providing plugin;
 			* absent compositions (standalone dictionary registries) stay process-local.
+			* @param bootstrap - native initialization; absent in ordinary browsers.
 			*/
-			constructor(ctx, host) {
+			constructor(ctx, host, bootstrap) {
+				this.bootstrap = bootstrap;
 				this.ctx = ctx;
 				this.host = host;
 				for (const locale of BUILT_IN_LOCALES) this.catalog.set(localeKey(locale.id), locale);
 				const locales = this.localeList();
-				this.provisional = resolveInitialLocale(locales);
+				this.provisional = resolveInitialLocale(locales, bootstrap?.languages);
+				this.preference = bootstrap?.preference ?? void 0;
 				this.snapshot = Object.freeze({
-					active: this.provisional,
+					active: this.resolveActive(),
 					locales,
 					revision: 0
 				});
@@ -1108,6 +1225,16 @@ window.__ModuleLoader__.load({
 				return this.snapshot;
 			}
 			/**
+			* Resolve package text through the active language's declared fallback chain.
+			* Plain strings stay verbatim; maps do not consult registered dictionaries.
+			* @param text - package text whose locale keys are lowercase and include English.
+			* @returns the first available translation, including an empty string.
+			*/
+			resolveText(text) {
+				if (typeof text === "string") return text;
+				return this.fallbackChain(this.snapshot.active).reduceRight((resolved, locale) => text[localeKey(locale)] ?? resolved, text.en);
+			}
+			/**
 			* LocaleFace getSnapshot: the current snapshot (carries `revision`; stable
 			* reference between changes, uSES-safe).
 			* @returns the current snapshot.
@@ -1200,7 +1327,7 @@ window.__ModuleLoader__.load({
 			publishCatalog() {
 				this.fallbackChains.clear();
 				const locales = this.localeList();
-				this.provisional = resolveInitialLocale(locales);
+				this.provisional = resolveInitialLocale(locales, this.bootstrap?.languages);
 				const active = this.resolveActive();
 				this.publish(active, active !== this.snapshot.active, locales);
 			}
@@ -1323,8 +1450,8 @@ window.__ModuleLoader__.load({
 		* The browser's own language wins over {@link FALLBACK_LOCALE}; an explicit
 		* Host preference may replace this provisional value after plugin activation.
 		*/
-		function resolveInitialLocale(locales) {
-			return detectBrowserLocale(locales) ?? "en";
+		function resolveInitialLocale(locales, languages) {
+			return detectBrowserLocale(locales, languages) ?? "en";
 		}
 		/**
 		* The first registered locale the browser asks for. Each browser tag first
@@ -1335,12 +1462,15 @@ window.__ModuleLoader__.load({
 		* locale for non-browser runs. `navigator.language` trails the ordered
 		* `languages` list and covers hosts exposing only the single tag.
 		* @param locales - definitions currently available to the browser.
+		* @param languages - native system language order, when supplied by a shell.
 		* @returns the first matching locale id, or undefined.
 		*/
-		function detectBrowserLocale(locales) {
-			if (typeof window === "undefined") return void 0;
-			const languages = navigator.languages;
-			for (const tag of [...languages ?? [], navigator.language]) {
+		function detectBrowserLocale(locales, languages) {
+			if (languages === void 0) {
+				if (typeof window === "undefined") return void 0;
+				languages = [...navigator.languages ?? [], navigator.language];
+			}
+			for (const tag of languages) {
 				const requested = localeKey(tag);
 				const exact = locales.find((locale) => localeKey(locale.id) === requested);
 				if (exact !== void 0) return exact.id;
@@ -1353,16 +1483,30 @@ window.__ModuleLoader__.load({
 		const inject = [
 			"slots",
 			"remote",
-			"settingsScope"
+			"configForms"
 		];
 		/**
 		* Client plugin body: provide the locale service with base dictionaries and
 		* register the feature-owned Language preference row into the General
 		* section's item slot (a feature owns its settings surface).
 		* @param ctx - client cordis context.
+		* @returns resolves after native language initialization and plugin registration.
 		*/
-		function apply(ctx) {
-			const locale = new LocaleRuntime(ctx, ctx.settingsScope.bind({ namespace: LOCALE_SETTINGS_NAMESPACE }));
+		async function apply(ctx) {
+			const bridge = globalThis.__DSH_LOCALE__;
+			let bootstrap;
+			if (bridge !== void 0) {
+				let value;
+				try {
+					value = await bridge.read();
+				} catch (error) {
+					if (ctx.fiber.uid === null) return;
+					throw error;
+				}
+				if (ctx.fiber.uid === null) return;
+				bootstrap = parseLocaleBootstrap(value);
+			}
+			const locale = new LocaleRuntime(ctx, ctx.configForms.get(LOCALE_SETTINGS_NAMESPACE), bootstrap);
 			locale.register(COMMON_NS, {
 				zh: zh$1,
 				en: en$1
@@ -1372,6 +1516,12 @@ window.__ModuleLoader__.load({
 				en
 			});
 			ctx.provide("locale", locale);
+			if (bridge !== void 0) {
+				ctx.on("locale/change", (snapshot) => {
+					bridge.onChange(snapshot.active);
+				});
+				bridge.onChange(locale.getSnapshot().active);
+			}
 			ctx.slots.installLocale(locale);
 			const store = createLanguageRowStore();
 			let bound;

package/lib/index.js

@@ -10,18 +10,19 @@ const LOCALE_ID_PATTERN = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/u;
 /** Locale identifiers shipped by the browser client. */
 const LOCALE_IDS = ["zh", "en"];
 /** Durable locale schema; also the wire envelope the browser scope validates against. */
-const LocaleSettingsSchema = z.object({ [LOCALE_PREFERENCE_FIELD]: z.string().pattern(LOCALE_ID_PATTERN).required(false) });
+const LocaleSettingsFields = { [LOCALE_PREFERENCE_FIELD]: z.string().pattern(LOCALE_ID_PATTERN).required(false) };
+z.object(LocaleSettingsFields);
 //#endregion
 //#region lib/types/index.js
-/** Host registration for the browser locale preference. */
-/**
-* Register the durable locale section when a settings provider exists.
-* @param ctx - Host context whose optional settings service owns the section.
+/** Live preferences projected to the browser. */
+const Config = z.object({ [LOCALE_PREFERENCE_FIELD]: LocaleSettingsFields[LOCALE_PREFERENCE_FIELD].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(LOCALE_SETTINGS_NAMESPACE, LocaleSettingsSchema);
+	ctx.inject(["settings"], (child) => {
+		child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
 	});
 }
 //#endregion
-export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, apply };
+export { Config, LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, apply };

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

@@ -0,0 +1,22 @@
+/** Locale initialization supplied by a native shell before its Client tree mounts. */
+/** System languages and the existing Host preference for one page load. */
+export interface LocaleBootstrap {
+    /** Operating-system language tags in preference order. */
+    readonly languages: readonly string[];
+    /** Stored locale.preference; null preserves automatic language selection. */
+    readonly preference: string | null;
+}
+/** Optional page-global bridge named __DSH_LOCALE__; ordinary browsers omit it. */
+export interface LocaleBridge {
+    /** Read current initialization data through the shell's isolated preload. @returns unvalidated IPC data. */
+    read(): Promise<unknown>;
+    /** Publish the resolved Client locale without writing another preference. @param locale - active registered locale id. */
+    onChange(locale: string): void;
+}
+/**
+ * Validate initialization data returned over the preload IPC bridge.
+ * @param value - untrusted IPC response.
+ * @returns language initialization with no persistence side effects.
+ */
+export declare function parseLocaleBootstrap(value: unknown): LocaleBootstrap;
+//# sourceMappingURL=bootstrap.d.ts.map

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

@@ -5,8 +5,10 @@
  * its own settings surface.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { LocalizedText } from '@deepseek-ai/dsh-package-manifest';
 import { type LocaleDictOf, type LocaleNamespaceMap, type Translate, type TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
-import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type LocaleBootstrap } from './bootstrap.ts';
 import { type BuiltInLocaleId, type LocaleId, type LocaleSettings } from '../locale-settings.ts';
 import { type CommonKey } from '../locales/index.ts';
 import { type SettingsLocaleKey } from '../locales/settings.ts';
@@ -93,6 +95,7 @@ export declare const SETTINGS_NS = "settings.locale";
  * `ctx.slots.installLocale`.
  */
 export declare class LocaleRuntime {
+    private readonly bootstrap?;
     private dicts;
     private bound;
     private catalog;
@@ -110,13 +113,21 @@ export declare class LocaleRuntime {
      * listener is released through ctx.effect on dispose).
      * @param host - durable preference scope owned by the providing plugin;
      * absent compositions (standalone dictionary registries) stay process-local.
+     * @param bootstrap - native initialization; absent in ordinary browsers.
      */
-    constructor(ctx: ClientContext, host?: SettingsScope<LocaleSettings>);
+    constructor(ctx: ClientContext, host?: ConfigForm<LocaleSettings>, bootstrap?: LocaleBootstrap | undefined);
     /**
      * Read the current immutable locale snapshot.
      * @returns the current snapshot (stable reference until the next change).
      */
     getLocale(): LocaleSnapshot;
+    /**
+     * Resolve package text through the active language's declared fallback chain.
+     * Plain strings stay verbatim; maps do not consult registered dictionaries.
+     * @param text - package text whose locale keys are lowercase and include English.
+     * @returns the first available translation, including an empty string.
+     */
+    resolveText(text: LocalizedText): string;
     /**
      * LocaleFace getSnapshot: the current snapshot (carries `revision`; stable
      * reference between changes, uSES-safe).
@@ -231,6 +242,7 @@ export declare const inject: string[];
  * register the feature-owned Language preference row into the General
  * section's item slot (a feature owns its settings surface).
  * @param ctx - client cordis context.
+ * @returns resolves after native language initialization and plugin registration.
  */
-export declare function apply(ctx: ClientContext): void;
+export declare function apply(ctx: ClientContext): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -1,9 +1,19 @@
-/** Host registration for the browser locale preference. */
-import type { Context } from '@deepseek-ai/cordis';
+import type { Volatile, Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 export { LOCALE_IDS, LOCALE_PREFERENCE_FIELD, LOCALE_SETTINGS_NAMESPACE, type BuiltInLocaleId, type LocaleId, type LocaleSettings, } from './locale-settings.ts';
-/**
- * Register the durable locale section when a settings provider exists.
- * @param ctx - Host context whose optional settings service owns the section.
+/** Runtime preferences projected to the browser. */
+export interface Config {
+    /** Explicit locale; omission follows the browser. */
+    preference: Volatile<string | undefined>;
+}
+/** Live preferences projected to the browser. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    preference: z<string, string, "volatile">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    preference: z<string, string, "volatile">;
+}>>, "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/lib/types/locale-settings.d.ts

@@ -18,5 +18,13 @@ export interface LocaleSettings {
     preference?: LocaleId;
 }
 /** Durable locale schema; also the wire envelope the browser scope validates against. */
-export declare const LocaleSettingsSchema: z<LocaleSettings>;
+export declare const LocaleSettingsFields: {
+    preference: z<string, string, "plain">;
+};
+/** Schema for the shared locale preference. */
+export declare const LocaleSettingsSchema: z<Schemastery.ObjectS<NoInfer<{
+    preference: z<string, string, "plain">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    preference: z<string, string, "plain">;
+}>>, "plain">;
 //# sourceMappingURL=locale-settings.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-locale",
   "description": "Locale plugin: Host-backed preference, extensible language catalog, browser fallback, and typed built-in dictionaries",
-  "version": "0.1.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -39,24 +39,25 @@
   },
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-client-test-runtime": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-client-connection": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-settings": "^0.1.6-alpha.1"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-package-manifest": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-connection": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.7-alpha.1"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "^3.18.3"
   },
   "files": [
     "lib/index.js",