@deepseek-ai/dsh-client-ui-settings 0.1.1-rc.2 → 0.1.2-alpha.3

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/ui-settings/README.md
-README.md: 990469573309b3a92b5eeb8bc41d89b226dbd0d4
-README.zh.md: a0ce9d5cf6d4633cec9fbf466083c7a11a947e8e
+README.md: 1dbefefe51086a68d1f2afd36d098a118337f0b9
+README.zh.md: 7009b4a7f156a613a7a1ef4e38b14c11d40fa85a

package/README.md

@@ -1,13 +1,87 @@
+---
+description: "Settings domain base plugin: the settings-namespace scope service, schema service, and the canonical settings slot-type contract for the dsh web client."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-client-ui-settings
 
 English | [中文](README.zh.md)
 
-The settings domain's base layer, with no presentation of its own. It provides `ctx.settingsScope`, the Host transport every preference row binds its durable namespace section through; `ctx.settingsSchema`, the synchronous schema-rehydration, validation, and immutable path-editing service used by settings plugins; and the settings slot types registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.action` (ordered content-header actions), `settings.section` (one page per feature), `settings.plugins.tab` (feature-owned pages inside the Plugins section), and `settings.onboarding` (ordered feature-owned pages). It depends on no `ui-*` presentation package, so any feature that owns a preference can reach it; the settings SHELL — the `sidebar.settings` occupant, its navigation, and the chrome — lives in ui-settings-general, because a shell dependency on ui-sidebar would close a reference graph cycle through ui-layout and ui-theme. The shell's own contract types live beside the shell for the same reason.
+## Summary
+
+`dsh-client-ui-settings` is the base every preference surface in the dsh web client builds on: a feature plugin binds a namespace and stores or edits its preference rows in the Host settings document without re-implementing transport or schema handling. `ctx.settingsScope` derives a per-namespace scope from the shared document mirror with revision fencing, so a concurrent write from another surface is refused instead of silently overwritten; `ctx.settingsSchema` rehydrates and validates schemas and edits immutable paths synchronously. It declares the slot types settings surfaces fill — `settings.trigger`/`settings.header`/`settings.close` (chrome), `settings.action` (ordered header actions), `settings.section` (one page per feature), `settings.plugins.tab`, and `settings.onboarding` — and renders nothing itself. Because it depends on no `ui-*` presentation package, any feature that owns a preference can reach it; the settings shell itself lives in ui-settings-general.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Feature plugins use this package to store and edit their preferences without re-implementing transport or schema handling. Mount it once per composition; it injects the `remote` service with its `settings` namespace and owns the single `settings.describe` reader in the browser.
+
+### Binding a namespace
+
+A feature calls `ctx.settingsScope.bind(spec)` with a per-namespace spec and gets a scope derived from the shared document mirror. The scope snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` clears that override. Writes go through the scope: `set` and `unset` submit one operation, while `mutate` submits several ordered operations atomically. Each write is fenced by the namespace revision as `expectedRevision`, so a concurrent write from another surface is refused instead of silently overwritten. A staged editor can supply the revision where its draft began as a fixed fence; otherwise the scope uses the latest queued or mirrored revision.
+
+### Filling the settings slots
+
+A settings surface registers into the slot types this package declares. The shell (`sidebar.settings` occupant, navigation, chrome) lives in ui-settings-general; feature pages register `settings.section` contributions; the Plugins section hosts `settings.plugins.tab` pages; onboarding steps register `settings.onboarding`. Cross-namespace surfaces (schema introspection, the served-namespace directory, `hasDocument`) read the same mirror through `ctx.settingsScope.describe()`.
+
+### Observable success and failures
+
+A bound scope reflects the current document revision immediately; a committed write folds its answer back into the mirror with no re-read. A rejected or failed latest write triggers one mirror recovery read; a superseded write leaves recovery to its successor. Without a `decode` in the spec, a section that is not a plain object or fails schema rehydration publishes no value, so a row renders its own absent state instead of a half-decoded one.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The package realizes one ownership rule: the browser keeps one shared mirror of the settings document, and every derived surface reads that single source, so any moment in time shows the same document revision.
+
+### The describe mirror
 
-The plugin injects `connection` and `remote` and owns the one `settings.describe` reader in the browser: a shared mirror holding the whole answer, refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included — that read closes the window where a commit lands between the eager read and the SSE subscription). Schema operations are synchronous and live on the `settingsSchema` service. `ctx.settingsScope.bind(spec)` returns a per-namespace scope DERIVED from the mirror on the CALLER's context — the scope's disposer belongs to the calling fiber, binding adds no wire read, a row's activation never blocks on the settings transport, and every derived surface shows the same document revision at any moment. Cross-namespace surfaces (schema introspection, the served-namespace directory, `hasDocument`) read the same mirror through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in). The scope snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` clears that override. Writes stay per-scope: one field path fenced by the namespace revision as `expectedRevision`; a committed write folds its answer back into the mirror with no re-read, a rejected or failed latest write triggers one mirror recovery read, and a superseded one leaves recovery to its successor. Without a `decode` in the spec, 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, so a row renders its own absent state instead of a half-decoded one. The cold-boot read count is pinned by `apps/web/tests/startup-rpc-budget.e2e.ts`; a new direct `settings.describe` caller in client code is a regression against it.
+The plugin injects `remote` with its `settings` namespace, resolves Host persistence once from the fixed `remote.$host` facts, and owns the one `settings.describe` reader in the browser: a shared mirror refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included, closing the window where a commit lands between the eager read and the SSE subscription). Cross-namespace surfaces read it through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in).
+
+### Scope derivation
+
+`ctx.settingsScope.bind(spec)` returns a per-namespace scope derived from the mirror on the caller's context: the scope's disposer belongs to the calling fiber, binding adds no wire read, and a row's activation never blocks on the settings transport. Writes stay per-scope: `set` and `unset` are single-operation forms of `mutate`, which copies and queues several ordered field operations behind one namespace revision as `expectedRevision`. A committed mutation folds its answer in, a rejected or failed latest mutation triggers one recovery read, and a superseded one leaves recovery to its successor. The cold-boot read count is pinned by `../../../apps/web/tests/startup-rpc-budget.e2e.ts`; a new direct `settings.describe` caller in client code is a regression against it.
+
+### Schema service
+
+`ctx.settingsSchema` performs synchronous schema rehydration, validation, and immutable path editing for settings plugins. Without a `decode` in the spec, 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>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+These pages cover the settings surface family and the durable seam behind it.
+
+- [ui-settings-general](../ui-settings-general/README.md) — the settings shell: trigger chrome, navigation, General section, onboarding projection.
+- [ui-settings-plugins](../ui-settings-plugins/README.md) — the Plugins section and its configurable host-plane cards.
+- [ui-settings-models](../ui-settings-models/README.md) — the Models page and DeepSeek onboarding over this base.
+- [settings](../../settings/README.md) — the durable user-settings seam and its file provider.
+- [ui-sidebar](../ui-sidebar/README.md) — the sidebar shell whose bottom seat hosts the settings trigger.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-None, as the settings domain base serves browser preference storage and slot declarations; nothing here reaches a model request.
+None, as the package is a browser-side UI plugin layer that registers nothing model-facing.
 
 #### KV Cache effect
 
@@ -15,5 +89,19 @@ None; this package neither assembles nor sends a provider request.
 
 ## Known Limitations and Deferred Work
 
-- **Remote browsers get no durable settings** — the settings RPCs are loopback-only, so a scope bound in a non-loopback browser starts `unavailable` and never crosses the wire; every row it backs is inert there.
-- **One field per write** — `set` sends a single `set` op, so a row that must move two fields together has no transaction and publishes two revisions.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the settings transport cannot reach; they are current package constraints.
+
+- **Non-loopback pages get no durable settings** — this Client keeps Host persistence disabled there, so a scope starts `unavailable` and never crosses the wire; every row it backs is inert even though Connection authentication covers the API.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,19 +1,107 @@
+---
+description: "设置领域底座插件：设置命名空间 scope 服务、schema 服务，以及 dsh Web 客户端的规范设置 slot 类型约定。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-client-ui-settings
 
 [English](README.md) | 中文
 
-设置领域的底座，本身不含任何呈现内容。它提供 `ctx.settingsScope`——每个偏好设置行绑定自己那份持久化命名空间分区所用的宿主传输层；`ctx.settingsSchema`——设置插件使用的同步 schema 重建、校验与不可变路径编辑服务；并声明由注册方填充的设置 slot 类型：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）、`settings.plugins.tab`（“插件”分区内由各功能持有的页面）和 `settings.onboarding`（由各功能持有的有序页面）。它不依赖任何 `ui-*` 呈现包，因此任何持有偏好设置的功能都能够到它；设置**外壳**——`sidebar.settings` 占位方、它的导航与界面框架——位于 ui-settings-general，因为外壳一旦依赖 ui-sidebar，就会经 ui-layout 与 ui-theme 闭合出一条引用图环路。外壳自身的契约类型出于同一原因与外壳放在一起。
+## 概述
+
+`dsh-client-ui-settings` 是 dsh Web 客户端每个偏好设置界面都依赖的底座：功能插件绑定一个命名空间，即可在宿主设置文档中存储或编辑自己的偏好设置行，而无需重新实现传输层或 schema 处理。`ctx.settingsScope` 从共享文档镜像派生按命名空间的 scope，并以 revision 设栅，因此来自另一界面的并发写入会被拒绝，而不是被静默覆盖；`ctx.settingsSchema` 同步重建并校验 schema、编辑不可变路径。它声明设置界面所填充的 slot 类型——`settings.trigger`/`settings.header`/`settings.close`（界面框架）、`settings.action`（有序标题栏操作）、`settings.section`（每项功能一页）、`settings.plugins.tab` 与 `settings.onboarding`——而自身不渲染任何内容。由于它不依赖任何 `ui-*` 呈现包，任何持有偏好设置的功能都能够到它；设置外壳本身位于 ui-settings-general。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+功能插件用本包存储与编辑自己的偏好设置，而无需重新实现传输层或 schema 处理。每个组合挂载一次即可；它注入 `remote` 服务及其 `settings` 命名空间，并持有浏览器中唯一的 `settings.describe` 读取方。
+
+### 绑定命名空间
+
+功能调用 `ctx.settingsScope.bind(spec)` 并传入按命名空间的 spec，得到一个由共享文档镜像派生的 scope。scope 快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host/内存模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会清除该覆盖。写入经 scope 进行：`set` 与 `unset` 提交一个操作，`mutate` 则原子提交多个有序操作。每次写入都以命名空间 revision 作为 `expectedRevision` 围栏，因此来自另一界面的并发写入会被拒绝，而不是被静默覆盖。暂存编辑器可以把开始草拟时读取的 revision 作为固定围栏传入；否则 scope 使用最新排队或镜像 revision。
+
+### 填充设置 slot
+
+设置界面会注册进本包声明的 slot 类型。外壳（`sidebar.settings` 占位方、导航、界面框架）位于 ui-settings-general；功能页面注册 `settings.section` 贡献；「插件」分区承载 `settings.plugins.tab` 页面；首次使用引导步骤注册 `settings.onboarding`。跨命名空间的表面（schema 内省、已服务命名空间目录、`hasDocument`）通过 `ctx.settingsScope.describe()` 读同一面镜像。
+
+### 可观察的成功与失败
+
+绑定后的 scope 会立即反映当前文档 revision；提交成功的写入把应答折回镜像、不再重读。被拒绝或失败的最新写入触发一次镜像恢复读取；被取代的写入把恢复留给后继者。若 spec 未提供 `decode`，则分区不是普通对象或未通过 schema 重建时一律不发布任何值，于是行渲染自己的缺失状态，而不是一份半解码的值。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本包实现一条归属规则：浏览器保留设置文档的一面共享镜像，每个派生表面都读这同一真源，因此任一时刻看到的都是同一份文档 revision。
+
+### Describe 镜像
 
-该插件注入 `connection` 与 `remote`，并持有浏览器中唯一的 `settings.describe` 读取方：一面持有完整应答的共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内——这次读取关闭了「提交落在急切读取与 SSE 订阅之间、其失效通知丢失」的窗口）。schema 操作为同步调用，由 `settingsSchema` 服务承载。`ctx.settingsScope.bind(spec)` 在**调用方**的 context 上返回一个由镜像**派生**的按命名空间 scope——scope 的 disposer 归调用方 fiber 所有，绑定不新增任何线路读取，某一行的激活绝不会阻塞在设置传输层上，且任一时刻每个派生面看到的都是同一份文档 revision。跨命名空间的表面（schema 内省、已服务命名空间目录、`hasDocument`）通过 `ctx.settingsScope.describe()` 读同一面镜像，这是一个读取／折叠面（`getSnapshot`／`subscribe`／`ensure`，另有把写应答折入的 `acceptView`）。scope 快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host／内存模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会清除该覆盖。写入仍归各 scope：单一字段路径，以命名空间 revision 作为 `expectedRevision` 围栏；提交成功的写入将应答折回镜像、不再重读，被拒绝或失败的最新写入触发一次镜像恢复读取，被取代的写入则把恢复留给后继者。若 spec 未提供 `decode`，则分区不是普通对象、未通过其重建后的 schema 校验、或携带本客户端无法重建的 schema 信封时，一律不发布任何值，于是行渲染自己的缺失状态，而不是一份半解码的值。冷启动读取次数由 `apps/web/tests/startup-rpc-budget.e2e.ts` 钉住；客户端代码中新增直连 `settings.describe` 调用即是对它的回归。
+插件注入 `remote` 及其 `settings` 命名空间，从固定的 `remote.$host` 事实一次性解析 Host 持久化模式，并持有浏览器中唯一的 `settings.describe` 读取方：一面共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内，关闭「提交落在急切读取与 SSE 订阅之间」的窗口）。跨命名空间表面通过 `ctx.settingsScope.describe()` 读它，这是一个读取/折叠面（`getSnapshot`/`subscribe`/`ensure`，另有把写应答折入的 `acceptView`）。
+
+### Scope 派生
+
+`ctx.settingsScope.bind(spec)` 在调用方的 context 上返回一个由镜像派生的按命名空间 scope：scope 的 disposer 归调用方 fiber 所有，绑定不新增任何线路读取，某一行的激活绝不会阻塞在设置传输层上。写入仍归各 scope：`set` 与 `unset` 是 `mutate` 的单操作形式，后者会复制操作列表，并把多个有序字段操作排在同一个作为 `expectedRevision` 的命名空间 revision 之后。提交成功的 mutation 把应答折回镜像，被拒绝或失败的最新 mutation 触发一次恢复读取，被取代的 mutation 把恢复留给后继者。冷启动读取次数由 `../../../apps/web/tests/startup-rpc-budget.e2e.ts` 钉住；客户端代码中新增直连 `settings.describe` 调用即是对它的回归。
+
+### Schema 服务
+
+`ctx.settingsSchema` 为设置插件执行同步 schema 重建、校验与不可变路径编辑。若 spec 未提供 `decode`，则分区不是普通对象、未通过其重建后的 schema 校验、或携带本客户端无法重建的 schema 信封时，一律不发布任何值。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+以下页面覆盖设置界面家族及其背后的持久化 seam。
+
+- [ui-settings-general](../ui-settings-general/README.zh.md)——设置外壳：触发控件、导航、「通用」分区、引导投影。
+- [ui-settings-plugins](../ui-settings-plugins/README.zh.md)——「插件」分区及其可配置宿主平面卡片。
+- [ui-settings-models](../ui-settings-models/README.zh.md)——建立在本底座之上的 Models 页面与 DeepSeek 引导。
+- [settings](../../settings/README.zh.md)——持久化用户设置 seam 及其文件提供方。
+- [ui-sidebar](../ui-sidebar/README.zh.md)——底部席位承载设置触发控件的侧边栏外壳。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-无。设置领域底座为浏览器提供偏好设置存储与 slot 声明；这里没有任何内容进入模型请求。
+无。该包是浏览器端 UI 插件层，不注册任何面向模型的内容。
 
 #### KV Cache 影响
 
 无；该包既不组装也不发送提供方请求。
 
-## 已知限制与暂缓事项
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明设置传输层够不到的地方；它们是当前包约束。
+
+- **非 loopback 页面没有持久化设置**：本 Client 在那里禁用 Host 持久化，因此 scope 以 `unavailable` 起步且从不跨线路；尽管 Connection 认证覆盖 API，它支撑的每一行仍在那里无效。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
 
-- **远程浏览器没有持久化设置**：设置 RPC 仅限 loopback，因此在非 loopback 浏览器中绑定的 scope 以 `unavailable` 起步且从不跨线路，它支撑的每一行在那里都是无效的。
-- **每次写入仅一个字段**：`set` 只发送单个 `set` op，因此需要同时改动两个字段的行没有事务可用，会发布两个 revision。
+</details>

package/lib/client.js

@@ -5,7 +5,7 @@ window.__ModuleLoader__.load({
 		var exports = module.exports;
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 		let _deepseek_ai_cordis = require("@deepseek-ai/cordis");
-		let _deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
+		let _deepseek_ai_dsh_client_store = require("@deepseek-ai/dsh-client-store");
 		//#region ../../../vendor/cosmokit/src/misc.ts
 		/** Return true when a value is `null` or `undefined`. */
 		function isNullable(value) {
@@ -934,11 +934,9 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region lib/types/client/settings-scope.js
 		/**
-		* Host transport for the settings-namespace scope contract. The contract types
-		* live in `dsh-client-runtime` (the common dependency of every feature that
-		* owns a preference); this file owns the per-namespace derivation over the
-		* shared {@link SettingsDescribeMirror} and the serialized write path, both of
-		* which are Settings-surface concerns. Reads never touch the wire here: the
+		* Host transport for the settings-namespace scope contract. This file owns the
+		* per-namespace derivation over the shared {@link SettingsDescribeMirror} and
+		* the serialized write path. Reads never touch the wire here: the
 		* mirror is the one `settings.describe` reader, and every scope is a selector
 		* over its snapshot.
 		*/
@@ -949,7 +947,7 @@ window.__ModuleLoader__.load({
 		* the operation already crossing the wire.
 		*/
 		var SettingsScopeController = class {
-			api;
+			ctx;
 			spec;
 			mirror;
 			persistence;
@@ -966,19 +964,20 @@ window.__ModuleLoader__.load({
 			*/
 			pendingRevision;
 			/**
-			* @param api - settings wire face (writes only; reads ride the mirror).
+			* @param ctx - the providing plugin's context, whose `remote.settings`
+			* namespace carries this scope's writes (reads ride the mirror).
 			* @param spec - namespace identity and optional narrowing decoder.
 			* @param mirror - the shared describe mirror this scope derives from.
-			* @param persistence - remote browsers remain process-local because settings RPCs are loopback-only.
+			* @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
 			* @param schema - settings-owned schema operations.
 			*/
-			constructor(api, spec, mirror, persistence, schema) {
-				this.api = api;
+			constructor(ctx, spec, mirror, persistence, schema) {
+				this.ctx = ctx;
 				this.spec = spec;
 				this.mirror = mirror;
 				this.persistence = persistence;
 				this.schema = schema;
-				this.store = (0, _deepseek_ai_dsh_client_runtime_client.createSnapshotStore)({
+				this.store = (0, _deepseek_ai_dsh_client_store.createSnapshotStore)({
 					status: persistence === "host" ? "loading" : "unavailable",
 					value: void 0,
 					base: void 0,
@@ -1014,11 +1013,11 @@ window.__ModuleLoader__.load({
 			* @returns settlement after the write and any latest-write recovery read.
 			*/
 			set(field, value) {
-				return this.write({
+				return this.mutate([{
 					op: "set",
 					path: [field],
 					value
-				});
+				}]);
 			}
 			/**
 			* Queue one field clear; see {@link SettingsScope.unset} for the ordering,
@@ -1027,35 +1026,32 @@ window.__ModuleLoader__.load({
 			* @returns settlement after the clear and any latest-write recovery read.
 			*/
 			unset(field) {
-				return this.write({
+				return this.mutate([{
 					op: "unset",
 					path: [field]
-				});
+				}]);
 			}
-			write(op) {
+			/**
+			* Queue one atomic namespace mutation; see {@link SettingsScope.mutate}.
+			* @param ops - ordered field operations copied when queued.
+			* @param expectedRevision - optional fixed revision read by the domain editor.
+			* @returns settlement after the mutation and any latest-write recovery read.
+			*/
+			mutate(ops, expectedRevision) {
+				const ownedOps = structuredClone(ops);
 				const generation = ++this.writeGeneration;
 				return this.enqueue(async () => {
-					const revision = this.pendingRevision ?? this.getSnapshot().revision;
-					let response;
-					try {
-						response = await this.api.settings.mutate({
-							ns: this.spec.namespace,
-							ops: [op],
-							...revision === void 0 ? {} : { expectedRevision: revision }
-						});
-					} catch (_settingsWriteFailure) {
-						await this.recover(generation);
-						return;
-					}
-					if (!response.result.ok) {
+					const revision = expectedRevision ?? this.pendingRevision ?? this.getSnapshot().revision;
+					const response = await this.ctx.remote.settings.mutate(this.spec.namespace, ownedOps, revision);
+					if (!response.ok) {
 						await this.recover(generation);
 						return;
 					}
 					if (this.disposed) return;
 					if (generation === this.writeGeneration) {
 						this.pendingRevision = void 0;
-						this.mirror.acceptView(response.result.value);
-					} else this.pendingRevision = response.result.value.revision;
+						this.mirror.acceptView(response.value);
+					} else this.pendingRevision = response.value.revision;
 				});
 			}
 			/** Reload Host state for the latest failed write; superseded failures leave recovery to it. */
@@ -1130,15 +1126,25 @@ window.__ModuleLoader__.load({
 		var SettingsScopeBinder = class extends _deepseek_ai_cordis.Service {
 			mirror;
 			schema;
+			persistence;
+			/**
+			* The PROVIDING fiber, kept because a Service reads `ctx` as its *consumer's*
+			* fiber: letting a bound scope write through the caller's context would make
+			* every caller declare `remote.settings` in its own `inject`.
+			*/
+			owner;
 			/**
 			* @param ctx - the providing plugin's context.
 			* @param config - the shared describe mirror every bound scope derives from,
-			* plus the settings-owned schema operations.
+			* the settings-owned schema operations, and the Host persistence the provider
+			* resolved from `remote.$host`.
 			*/
 			constructor(ctx, config) {
 				super(ctx, "settingsScope");
 				this.mirror = config.mirror;
 				this.schema = config.schema;
+				this.persistence = config.persistence;
+				this.owner = ctx;
 			}
 			/**
 			* The shared mirror's read/fold face for cross-namespace surfaces (schema
@@ -1162,8 +1168,7 @@ window.__ModuleLoader__.load({
 			*/
 			bind(spec) {
 				const ctx = this.ctx;
-				const connection = ctx.get("connection");
-				const controller = new SettingsScopeController(connection.api, spec, this.mirror, connection.isLoopback ? "host" : "memory", this.schema);
+				const controller = new SettingsScopeController(this.owner, spec, this.mirror, this.persistence, this.schema);
 				ctx.effect(() => {
 					this.mirror.ensure();
 					return async () => {
@@ -1191,20 +1196,21 @@ window.__ModuleLoader__.load({
 		* so an invalidation arriving mid-read is never lost and never duplicated.
 		*/
 		var SettingsDescribeMirror = class {
-			api;
+			ctx;
 			persistence;
 			store;
 			inFlight;
 			rerun = false;
 			generation = 0;
 			/**
-			* @param api - settings wire face.
-			* @param persistence - remote browsers stay process-local because settings RPCs are loopback-only.
+			* @param ctx - the providing plugin's context, whose `remote.settings`
+			* namespace answers the describe read.
+			* @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
 			*/
-			constructor(api, persistence = "host") {
-				this.api = api;
+			constructor(ctx, persistence = "host") {
+				this.ctx = ctx;
 				this.persistence = persistence;
-				this.store = (0, _deepseek_ai_dsh_client_runtime_client.createSnapshotStore)({
+				this.store = (0, _deepseek_ai_dsh_client_store.createSnapshotStore)({
 					status: persistence === "host" ? "idle" : "unavailable",
 					view: void 0,
 					error: null
@@ -1290,8 +1296,8 @@ window.__ModuleLoader__.load({
 						const generation = ++this.generation;
 						let outcome;
 						try {
-							const response = await this.api.settings.describe({});
-							outcome = response.result.ok ? { view: response.result.value } : { failure: response.result.error.message };
+							const response = await this.ctx.remote.settings.describe();
+							outcome = response.ok ? { view: response.value } : { failure: response.error.message };
 						} catch (error) {
 							outcome = { failure: error instanceof Error ? error.message : String(error) };
 						}
@@ -1321,10 +1327,10 @@ window.__ModuleLoader__.load({
 		//#endregion
 		//#region lib/types/client/index.js
 		/**
-		* Required services: the wire handle for the mirror's reads and the forwarded
-		* settings invalidation the mirror refreshes on.
+		* Required services: the Remote namespace the mirror reads through and the
+		* forwarded settings invalidation it refreshes on.
 		*/
-		const inject = ["connection", "remote"];
+		const inject = ["remote", "remote.settings"];
 		/**
 		* Provide the settings-namespace scope service over one shared describe
 		* mirror, and keep that mirror fresh on the two signals that can move the
@@ -1336,10 +1342,10 @@ window.__ModuleLoader__.load({
 		*/
 		function apply(ctx) {
 			const schema = new SettingsSchemaService(ctx);
-			const connection = ctx.get("connection");
-			const mirror = new SettingsDescribeMirror(connection.api, connection.isLoopback ? "host" : "memory");
+			const persistence = ctx.remote.$host.isLoopback ? "host" : "memory";
+			const mirror = new SettingsDescribeMirror(ctx, persistence);
 			ctx.effect(() => {
-				const disposers = [ctx.get("remote").$on("settings/document-updated", () => {
+				const disposers = [ctx.remote.$on("settings/document-updated", () => {
 					mirror.load();
 				}), ctx.on("connection/reset", () => {
 					mirror.load();
@@ -1351,7 +1357,8 @@ window.__ModuleLoader__.load({
 			}, "ui-settings: describe mirror invalidations");
 			new SettingsScopeBinder(ctx, {
 				mirror,
-				schema
+				schema,
+				persistence
 			});
 		}
 		//#endregion

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

@@ -11,15 +11,16 @@
  * ui-sidebar would close a reference cycle through ui-layout and ui-theme.
  * Export discipline: packages/client/AGENTS.md.
  */
-import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import type { Context } from '@deepseek-ai/cordis';
 export type { SettingsGeneralItemOwnerProps, SettingsHeaderOwnerProps, SettingsOnboardingOwnerProps, SettingsPluginsTabOwnerProps, SettingsSectionOwnerProps, SettingsTriggerOwnerProps, } from './contract/slots.ts';
 export type { SettingsScopeController, SettingsScopeBinder } from './settings-scope.ts';
+export type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-contract.ts';
 export type { SettingsSchemaService } from './schema.ts';
 export type { SchemaNode } from './schema.ts';
-export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot } from './settings-mirror.ts';
+export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot, } from './settings-mirror.ts';
 /**
- * Required services: the wire handle for the mirror's reads and the forwarded
- * settings invalidation the mirror refreshes on.
+ * Required services: the Remote namespace the mirror reads through and the
+ * forwarded settings invalidation it refreshes on.
  */
 export declare const inject: string[];
 /**
@@ -31,5 +32,5 @@ export declare const inject: string[];
  * bound to each consuming plugin's context.
  * @param ctx - client root context.
  */
-export declare function apply(ctx: ClientContext): void;
+export declare function apply(ctx: Context): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/client/settings-contract.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Settings-namespace scope contracts owned beside the settings transport.
+ */
+import type { SettingsPathOpView } from '@deepseek-ai/dsh-api-remotes/client';
+/** Client-side sync state of one settings namespace. */
+export interface SettingsScopeSnapshot<T> {
+    /**
+     * `loading` until the first accepted section, `ready` while one stands, and
+     * `unavailable` when the namespace is not exposed to this client or the
+     * connection keeps preferences process-local (memory mode).
+     */
+    status: 'loading' | 'ready' | 'unavailable';
+    /** Last accepted schema-resolved section; undefined before the first acceptance. */
+    value: T | undefined;
+    /**
+     * Composition layer the Host resolved {@link value} over, when the owning
+     * plugin declared one. What a field reverts to once cleared.
+     */
+    base: unknown;
+    /**
+     * Raw user layer as stored, when one exists. A field's PRESENCE here is what
+     * marks it overridden — an override whose value equals the composition
+     * default is still an override, and comparing values could not see it.
+     */
+    user: unknown;
+    /** Namespace revision fencing the next write; undefined before the first Host view. */
+    revision: number | undefined;
+    /** Whether the Host document accepts writes; memory mode never does. */
+    writable: boolean;
+    /** `host` syncs with the Host document; `memory` keeps a remote browser process-local. */
+    mode: 'host' | 'memory';
+}
+/** Domain-owned description of one settings namespace consumed by a browser plugin. */
+export interface SettingsScopeSpec<T> {
+    /** Settings namespace registered by the owning Host plugin. */
+    namespace: string;
+    /**
+     * Narrow one wire section; undefined keeps the last accepted value. The
+     * default validates the section against the namespace's own serialized wire
+     * schema, so domains add a decoder only to narrow beyond that schema.
+     */
+    decode?: (section: unknown) => T | undefined;
+}
+/**
+ * Reactive owner handle over one namespace's durable section — the browser
+ * mirror of the Host-side `SettingsScope` owner seam. Domain services read
+ * and observe the snapshot and route explicit user choices through its
+ * mutation methods.
+ */
+export interface SettingsScope<T> {
+    /** @returns the current sync snapshot (stable reference until the next change). */
+    getSnapshot(): SettingsScopeSnapshot<T>;
+    /**
+     * Observe snapshot replacements.
+     * @param listener - invoked after each snapshot change.
+     * @returns the disposer removing this listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Queue one atomic namespace mutation. All operations share one revision
+     * fence, Host validation, persistence decision, and recovery read. Supplying
+     * `expectedRevision` preserves an earlier read as the fence instead of using
+     * the latest queued or mirrored revision.
+     * @param ops - ordered field operations copied when queued.
+     * @param expectedRevision - optional fixed revision read by the domain editor.
+     * @returns settlement after the mutation and any latest-write recovery read.
+     */
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<void>;
+    /**
+     * Queue one field write. Rapid writes preserve mutation order, each carries
+     * the latest known namespace revision, and only the latest settlement may
+     * publish; a rejected or failed latest write reloads Host state instead.
+     * @param field - scalar field inside the namespace section.
+     * @param value - JSON-shaped value selected by the user.
+     * @returns settlement after the write and any latest-write recovery read.
+     */
+    set(field: string, value: unknown): Promise<void>;
+    /**
+     * Queue one field clear, so the field re-inherits the composition layer.
+     * Shares {@link set}'s ordering, revision, and recovery contract.
+     * @param field - scalar field inside the namespace section.
+     * @returns settlement after the clear and any latest-write recovery read.
+     */
+    unset(field: string): Promise<void>;
+}
+//# sourceMappingURL=settings-contract.d.ts.map

package/lib/types/client/settings-mirror.d.ts

@@ -8,8 +8,8 @@
  * invalidations its owning plugin subscribes to and folds write answers in
  * through {@link SettingsDescribeMirror.acceptView}.
  */
-import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client';
-type SettingsFace = Pick<IApiClient, 'settings'>;
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client';
 /** The full `settings.describe` answer the mirror serves. */
 export interface SettingsDescribeView {
     /** Every namespace a live Host plugin registered, as the Host reported it. */
@@ -65,17 +65,18 @@ export interface SettingsDescribeFace {
  * so an invalidation arriving mid-read is never lost and never duplicated.
  */
 export declare class SettingsDescribeMirror implements SettingsDescribeFace {
-    private readonly api;
+    private readonly ctx;
     private readonly persistence;
     private readonly store;
     private inFlight;
     private rerun;
     private generation;
     /**
-     * @param api - settings wire face.
-     * @param persistence - remote browsers stay process-local because settings RPCs are loopback-only.
+     * @param ctx - the providing plugin's context, whose `remote.settings`
+     * namespace answers the describe read.
+     * @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
      */
-    constructor(api: SettingsFace, persistence?: 'host' | 'memory');
+    constructor(ctx: ClientContext, persistence?: 'host' | 'memory');
     /** @returns the current sync snapshot (stable reference until the next change). */
     getSnapshot(): SettingsMirrorSnapshot;
     /**
@@ -114,5 +115,4 @@ export declare class SettingsDescribeMirror implements SettingsDescribeFace {
     private run;
     private shouldRerun;
 }
-export {};
 //# sourceMappingURL=settings-mirror.d.ts.map

package/lib/types/client/settings-scope.d.ts

@@ -1,19 +1,16 @@
 /**
- * Host transport for the settings-namespace scope contract. The contract types
- * live in `dsh-client-runtime` (the common dependency of every feature that
- * owns a preference); this file owns the per-namespace derivation over the
- * shared {@link SettingsDescribeMirror} and the serialized write path, both of
- * which are Settings-surface concerns. Reads never touch the wire here: the
+ * Host transport for the settings-namespace scope contract. This file owns the
+ * per-namespace derivation over the shared {@link SettingsDescribeMirror} and
+ * the serialized write path. Reads never touch the wire here: the
  * mirror is the one `settings.describe` reader, and every scope is a selector
  * over its snapshot.
  */
 import { Service } from '@deepseek-ai/cordis';
 import type { Context } from '@deepseek-ai/cordis';
-import type { IApiClient } from '@deepseek-ai/dsh-api-remotes/client';
-import { type SettingsScope, type SettingsScopeSnapshot, type SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client';
+import type { SettingsPathOpView } from '@deepseek-ai/dsh-api-remotes/client';
 import type { SettingsSchemaService } from './schema.ts';
+import type { SettingsScope, SettingsScopeSnapshot, SettingsScopeSpec } from './settings-contract.ts';
 import { SettingsDescribeMirror, type SettingsDescribeFace } from './settings-mirror.ts';
-type SettingsFace = Pick<IApiClient, 'settings'>;
 /**
  * One namespace's derived view over the shared describe mirror, plus that
  * namespace's serialized Host writes. Writes carry the latest known namespace
@@ -21,7 +18,7 @@ type SettingsFace = Pick<IApiClient, 'settings'>;
  * the operation already crossing the wire.
  */
 export declare class SettingsScopeController<T> implements SettingsScope<T> {
-    private readonly api;
+    private readonly ctx;
     private readonly spec;
     private readonly mirror;
     private readonly persistence;
@@ -38,13 +35,14 @@ export declare class SettingsScopeController<T> implements SettingsScope<T> {
      */
     private pendingRevision;
     /**
-     * @param api - settings wire face (writes only; reads ride the mirror).
+     * @param ctx - the providing plugin's context, whose `remote.settings`
+     * namespace carries this scope's writes (reads ride the mirror).
      * @param spec - namespace identity and optional narrowing decoder.
      * @param mirror - the shared describe mirror this scope derives from.
-     * @param persistence - remote browsers remain process-local because settings RPCs are loopback-only.
+     * @param persistence - client-selected Host persistence; non-loopback pages may remain process-local.
      * @param schema - settings-owned schema operations.
      */
-    constructor(api: SettingsFace, spec: SettingsScopeSpec<T>, mirror: SettingsDescribeMirror, persistence: 'host' | 'memory', schema: SettingsSchemaService);
+    constructor(ctx: Context, spec: SettingsScopeSpec<T>, mirror: SettingsDescribeMirror, persistence: 'host' | 'memory', schema: SettingsSchemaService);
     /** @returns the current sync snapshot (stable reference until the next change). */
     getSnapshot(): SettingsScopeSnapshot<T>;
     /**
@@ -68,7 +66,13 @@ export declare class SettingsScopeController<T> implements SettingsScope<T> {
      * @returns settlement after the clear and any latest-write recovery read.
      */
     unset(field: string): Promise<void>;
-    private write;
+    /**
+     * Queue one atomic namespace mutation; see {@link SettingsScope.mutate}.
+     * @param ops - ordered field operations copied when queued.
+     * @param expectedRevision - optional fixed revision read by the domain editor.
+     * @returns settlement after the mutation and any latest-write recovery read.
+     */
+    mutate(ops: readonly SettingsPathOpView[], expectedRevision?: number): Promise<void>;
     /** Reload Host state for the latest failed write; superseded failures leave recovery to it. */
     private recover;
     /**
@@ -96,14 +100,23 @@ declare module '@deepseek-ai/cordis' {
 export declare class SettingsScopeBinder extends Service {
     private readonly mirror;
     private readonly schema;
+    private readonly persistence;
+    /**
+     * The PROVIDING fiber, kept because a Service reads `ctx` as its *consumer's*
+     * fiber: letting a bound scope write through the caller's context would make
+     * every caller declare `remote.settings` in its own `inject`.
+     */
+    private readonly owner;
     /**
      * @param ctx - the providing plugin's context.
      * @param config - the shared describe mirror every bound scope derives from,
-     * plus the settings-owned schema operations.
+     * the settings-owned schema operations, and the Host persistence the provider
+     * resolved from `remote.$host`.
      */
     constructor(ctx: Context, config: {
         mirror: SettingsDescribeMirror;
         schema: SettingsSchemaService;
+        persistence: 'host' | 'memory';
     });
     /**
      * The shared mirror's read/fold face for cross-namespace surfaces (schema
@@ -125,5 +138,4 @@ export declare class SettingsScopeBinder extends Service {
      */
     bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>;
 }
-export {};
 //# sourceMappingURL=settings-scope.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-ui-settings",
   "description": "Settings domain base plugin: the settings-namespace scope service and the canonical settings slot-type contract",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -32,36 +32,27 @@
   "dsh": {
     "client": {
       "inject": [
-        "@deepseek-ai/dsh-client-connection",
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-api-remotes"
       ],
       "platform": "web"
     }
   },
   "license": "MIT",
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
-  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
     "@types/react": "~18.3.1",
     "react": "^18.2.0",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-test-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-store": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.3"
   },
   "files": [
     "lib/index.js",