@qilin-agent/client-ui-settings 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,58 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/client/ui-settings/README.md
+/:
+  en: ca8c195b9ae023a5
+  zh: caa2d3f4443bda58
+/qilin-client-ui-settings:
+  en: 18328728f91ac899
+  zh: 5f5d5c9bc9cced76
+/qilin-client-ui-settings/summary:
+  en: 0404ff8b4ec867e0
+  zh: 9c3f03dfd1306cc9
+/qilin-client-ui-settings/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-client-ui-settings/use-this-package:
+  en: 2417d8409aad6ca7
+  zh: 449eee623a2f334b
+/qilin-client-ui-settings/use-this-package/configuration-forms:
+  en: e1203ea54e9e0e1d
+  zh: b36d190d07efb198
+/qilin-client-ui-settings/use-this-package/following-served-namespaces:
+  en: 1e99f28889a84265
+  zh: 62188a24d05b6a9f
+/qilin-client-ui-settings/use-this-package/filling-the-settings-slots:
+  en: 121facd9d5bd61d5
+  zh: 33a1d0acba914867
+/qilin-client-ui-settings/use-this-package/observable-success-and-failures:
+  en: 8fafe99af04f147f
+  zh: 2c6c7190c9b9cfc9
+/qilin-client-ui-settings/understand-the-implementation:
+  en: 36deecb9bd4af281
+  zh: 52f7cadd2efa2037
+/qilin-client-ui-settings/understand-the-implementation/the-describe-mirror:
+  en: 439e8041078cc164
+  zh: 30ba84afd0abfc69
+/qilin-client-ui-settings/understand-the-implementation/shared-entry-forms:
+  en: ffd6c51916031c1d
+  zh: 703566b0885fd19e
+/qilin-client-ui-settings/understand-the-implementation/schema-service:
+  en: a9247e83278c5d40
+  zh: 051d24681036639d
+/qilin-client-ui-settings/further-exploration:
+  en: 2ce4e8d3a90e61ce
+  zh: 9b5510de7f4b320d
+/qilin-client-ui-settings/model-experience:
+  en: 3120df665299c634
+  zh: 1d9f365d091d0d2a
+/qilin-client-ui-settings/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: de54f3467ef3b9be
+/qilin-client-ui-settings/known-limitations-and-deferred-work:
+  en: b692f6ebe4291c07
+  zh: 85d896703dc94940
+/qilin-client-ui-settings/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+---
+description: "Settings domain base plugin: shared configuration forms, schema service, and the canonical settings slot-type contract for the qilin web client."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-ui-settings
+
+English | [中文](README.zh.md)
+
+## Summary
+
+This package lets web-client features expose editable preferences backed by the Host settings document without implementing their own transport or schema handling. Each feature gets namespace-scoped reads and writes, atomic multi-field updates, schema validation, and protection against silently overwriting concurrent changes. It also provides the standard extension points for settings chrome, pages, header actions, plugin tabs, and onboarding while rendering no interface itself. Any preference-owning feature can use it without depending on a presentation package; a separate package provides the settings shell.
+
+## 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.
+
+### Configuration forms
+
+`ctx.configForms.developerTools` owns the Coding Tools switch over the shared `ui-settings.enabled` preference, defaulting to `true`. Its `enabled` observable publishes accepted choices and `setEnabled` uses the same ordered writes; loopback clients persist to the Host document while a remote browser keeps the choice in one browser-local observable until reload. Host-backed clients keep developer features disabled until the first accepted schema-resolved value arrives. [ui-settings-general](../ui-settings-general/README.md#use-this-package) renders the switch.
+
+Feature adapters use `ctx.configForms.get(entryId)` to obtain accepted values and the write queue shared by every editor of that Host entry. A snapshot carries the resolved `value`, the inherited `base`, the raw `user`, revision, writability, and persistence mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` restores inheritance. `set` and `unset` submit one operation and resolve to whether the Host accepted it, 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 form uses the latest queued or mirrored revision.
+
+### Following served namespaces
+
+A page that edits a namespace another plugin owns registers through `ctx.configForms.whileServed(namespaces, register)`: `register` runs once any listed namespace is in the shared mirror, receives the set of namespaces the Host serves, and returns the registration's disposer, which runs when none of them is served any more or when the disposer `whileServed` returns runs. The caller owns that returned disposer and wraps it in `ctx.effect`; unlike `get`, the service registers nothing on the caller's context. A deployment that never composed the owner therefore shows no trace of the page, and a namespace the Host stops serving withdraws it. [ui-settings-plugins](../ui-settings-plugins/README.md) rides it for the four official pages of the Plugins page.
+
+### 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`. The shell-owned About page renders `settings.about.mark`; the QiLin brand package supplies the mark occupant. Cross-namespace surfaces (schema introspection, the served-namespace directory, `hasDocument`) read the same mirror through `ctx.configForms.describe()`.
+
+### Observable success and failures
+
+A shared form 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. 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 `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.configForms.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in).
+
+### Shared entry forms
+
+`ctx.configForms.get(entryId)` returns the one form for that Host entry, built with the providing plugin's own context: the service, not the caller, declares `remote.settings`, and repeated calls return the same form. The form derives from the mirror, so it adds no wire read and a row's activation never blocks on the settings transport. Writes stay per-entry: `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. 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: panel 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 panel occupant.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+None, as the package is a browser-side UI plugin layer that registers nothing model-facing.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+<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

@@ -0,0 +1,113 @@
+---
+description: "设置领域底座插件：共享配置表单、schema 服务，以及 qilin Web 客户端的规范设置 slot 类型约定。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-settings
+
+[English](README.md) | 中文
+
+## 概述
+
+本包使 Web 客户端功能能够公开由宿主设置文档支持的可编辑偏好设置，而无需自行实现传输或 schema 处理。每项功能都可按命名空间读写、原子更新多个字段、校验 schema，并避免静默覆盖并发更改。它还为设置界面框架、页面、标题栏操作、插件标签页和引导流程提供标准扩展点，但自身不渲染任何界面。任何持有偏好设置的功能都可在不依赖呈现包的情况下使用它；设置外壳由单独的包提供。
+
+## 目录
+
+- [使用本包](#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.configForms.developerTools` 管理代码工作工具开关，背后是共享的 `ui-settings.enabled` 偏好，默认为 `true`。其 `enabled` 可观察值发布已接受的选择，`setEnabled` 经同一有序写入；loopback 客户端写入 Host 文档，远程浏览器则把该选择保存在单个浏览器本地可观察值中，刷新后重置。使用 Host 偏好的客户端在首个经过 schema 解析并接受的值到达前保持开发者功能关闭。[ui-settings-general](../ui-settings-general/README.zh.md#use-this-package) 渲染该开关。
+
+功能适配器用 `ctx.configForms.get(entryId)` 取得已接受的值，以及该 Host 条目上所有编辑器共用的写入队列。快照携带解析后的 `value`、继承的 `base`、原始 `user`、revision、可写性与持久化模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会恢复继承。`set` 与 `unset` 提交一个操作，并以 Host 是否接受作为返回值，`mutate` 则原子提交多个有序操作。每次写入都以命名空间 revision 作为 `expectedRevision` 围栏，因此来自另一界面的并发写入会被拒绝，而不是被静默覆盖。暂存编辑器可以把开始草拟时读取的 revision 作为固定围栏传入；否则表单使用最新排队或镜像 revision。
+
+### 跟随被服务的命名空间
+
+编辑另一个插件所拥有命名空间的页面通过 `ctx.configForms.whileServed(namespaces, register)` 注册：只要所列命名空间中的任一个进入共享镜像，`register` 就运行一次，收到 Host 当前服务的命名空间集合，并返回该注册的 disposer；当它们全都不再被服务，或 `whileServed` 返回的 disposer 被调用时，这个 disposer 就运行。调用方持有返回的 disposer 并把它包进 `ctx.effect`；与 `get` 不同，服务不会在调用方的 context 上注册任何东西。因此从未组合过所有者的部署看不到该页面的任何痕迹，Host 停止服务的命名空间会撤下它。[ui-settings-plugins](../ui-settings-plugins/README.zh.md) 用它承载插件页上的四个官方页面。
+
+### 填充设置 slot
+
+设置界面会注册进本包声明的 slot 类型。外壳（`sidebar.settings` 占位方、导航、界面框架）位于 ui-settings-general；功能页面注册 `settings.section` 贡献；「插件」分区承载 `settings.plugins.tab` 页面；首次使用引导步骤注册 `settings.onboarding`。外壳自有的「关于」页面渲染 `settings.about.mark`；QiLin 品牌包为该标识席位提供印章。跨命名空间的表面（schema 内省、已服务命名空间目录、`hasDocument`）通过 `ctx.configForms.describe()` 读同一面镜像。
+
+### 可观察的成功与失败
+
+共享表单会立即反映当前文档 revision；提交成功的写入把应答折回镜像、不再重读。被拒绝或失败的最新写入触发一次镜像恢复读取；被取代的写入把恢复留给后继者。分区不是普通对象或未通过 schema 重建时一律不发布任何值，于是行渲染自己的缺失状态，而不是一份半解码的值。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本包实现一条归属规则：浏览器保留设置文档的一面共享镜像，每个派生表面都读这同一真源，因此任一时刻看到的都是同一份文档 revision。
+
+### Describe 镜像
+
+插件注入 `remote` 及其 `settings` 命名空间，从固定的 `remote.$host` 事实一次性解析 Host 持久化模式，并持有浏览器中唯一的 `settings.describe` 读取方：一面共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内，关闭「提交落在急切读取与 SSE 订阅之间」的窗口）。跨命名空间表面通过 `ctx.configForms.describe()` 读它，这是一个读取/折叠面（`getSnapshot`/`subscribe`/`ensure`，另有把写应答折入的 `acceptView`）。
+
+### 共享条目表单
+
+`ctx.configForms.get(entryId)` 返回该 Host 条目唯一的一份表单，并用提供方插件自己的 context 构造：声明 `remote.settings` 的是服务而不是调用方，重复调用返回同一份表单。表单由镜像派生，因此不新增任何线路读取，某一行的激活绝不会阻塞在设置传输层上。写入仍归各条目：`set` 与 `unset` 是 `mutate` 的单操作形式，后者会复制操作列表，并把多个有序字段操作排在同一个作为 `expectedRevision` 的命名空间 revision 之后。提交成功的 mutation 把应答折回镜像，被拒绝或失败的最新 mutation 触发一次恢复读取，被取代的 mutation 把恢复留给后继者。冷启动读取次数由 `../../../apps/web/tests/startup-rpc-budget.e2e.ts` 钉住；客户端代码中新增直连 `settings.describe` 调用即是对它的回归。
+
+### Schema 服务
+
+`ctx.settingsSchema` 为设置插件执行同步 schema 重建、校验与不可变路径编辑。分区不是普通对象、未通过其重建后的 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>
+## 模型体验
+
+无。该包是浏览器端 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>
+
+无。
+
+</details>