@qilin-agent/client-ui-theme 3.1.5 → 3.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.i18n.yaml +17 -14
- package/README.md +12 -8
- package/README.zh.md +12 -8
- package/lib/client.js +671 -220
- package/lib/index.js +155 -42
- package/lib/types/boot-theme.d.ts +11 -11
- package/lib/types/client/FontFamilyRow.d.ts +19 -0
- package/lib/types/client/FontSettingsGroup.d.ts +19 -0
- package/lib/types/client/FontSizeRow.d.ts +20 -5
- package/lib/types/client/font-size-shortcuts.d.ts +13 -0
- package/lib/types/client/index.d.ts +40 -18
- package/lib/types/client/locales.d.ts +41 -9
- package/lib/types/client/settings-store.d.ts +15 -13
- package/lib/types/index.d.ts +49 -7
- package/lib/types/theme-settings.d.ts +102 -0
- package/package.json +17 -15
package/README.i18n.yaml
CHANGED
|
@@ -3,14 +3,14 @@
|
|
|
3
3
|
# After editing either side, bring the other along and re-record with:
|
|
4
4
|
# pnpm run verify-translation-pairing --write packages/client/ui-theme/README.md
|
|
5
5
|
/:
|
|
6
|
-
en:
|
|
7
|
-
zh:
|
|
6
|
+
en: cb1e0973260fb688
|
|
7
|
+
zh: e57f8ac820511b5c
|
|
8
8
|
/qilin-agent-client-ui-theme:
|
|
9
9
|
en: ab0a967b786d021a
|
|
10
10
|
zh: 70b6e02e2dbb7898
|
|
11
11
|
/qilin-agent-client-ui-theme/summary:
|
|
12
|
-
en:
|
|
13
|
-
zh:
|
|
12
|
+
en: eacc3d51381e88c0
|
|
13
|
+
zh: 5ab28d2792ab2a34
|
|
14
14
|
/qilin-agent-client-ui-theme/table-of-contents:
|
|
15
15
|
en: d152484eb41ac6b4
|
|
16
16
|
zh: 09388d293f9be9cb
|
|
@@ -18,26 +18,29 @@
|
|
|
18
18
|
en: 5d1ec38a4bc6cac5
|
|
19
19
|
zh: 9ac70dce67027d62
|
|
20
20
|
/qilin-agent-client-ui-theme/use-this-package/typography:
|
|
21
|
-
en:
|
|
22
|
-
zh:
|
|
21
|
+
en: ff99a7f76165792d
|
|
22
|
+
zh: 6b729ad97b36dda2
|
|
23
|
+
/qilin-agent-client-ui-theme/use-this-package/fonts:
|
|
24
|
+
en: b45d5b48ca799c3a
|
|
25
|
+
zh: 6fb895bec83c2662
|
|
23
26
|
/qilin-agent-client-ui-theme/use-this-package/registering-a-theme:
|
|
24
27
|
en: 2cd32ccaba33b3e9
|
|
25
28
|
zh: 53ea78d19929ea02
|
|
26
29
|
/qilin-agent-client-ui-theme/use-this-package/pre-plugin-palette:
|
|
27
|
-
en:
|
|
28
|
-
zh:
|
|
30
|
+
en: dd5d22d088bedd24
|
|
31
|
+
zh: ff3416fc9cbf8418
|
|
29
32
|
/qilin-agent-client-ui-theme/understand-the-implementation:
|
|
30
|
-
en:
|
|
31
|
-
zh:
|
|
33
|
+
en: 610bb7f255c9d091
|
|
34
|
+
zh: 480ebc9bf5c7a5d0
|
|
32
35
|
/qilin-agent-client-ui-theme/understand-the-implementation/stylesheets:
|
|
33
|
-
en:
|
|
34
|
-
zh:
|
|
36
|
+
en: 3e76ea6bc9e07666
|
|
37
|
+
zh: 4cff930270969b1c
|
|
35
38
|
/qilin-agent-client-ui-theme/understand-the-implementation/scrollbar-rebinding:
|
|
36
39
|
en: 998f0fa103ee6ea5
|
|
37
40
|
zh: 13cae6dc8abd62e6
|
|
38
41
|
/qilin-agent-client-ui-theme/understand-the-implementation/preference-persistence:
|
|
39
|
-
en:
|
|
40
|
-
zh:
|
|
42
|
+
en: 1cd126d438c69c57
|
|
43
|
+
zh: 718b2a1dfff27466
|
|
41
44
|
/qilin-agent-client-ui-theme/further-exploration:
|
|
42
45
|
en: fdd4b91eeaf53ac7
|
|
43
46
|
zh: 715b9706ea7a2717
|
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "Theme and
|
|
2
|
+
description: "Theme, font-size, and font-family settings for the qilin web client: --qilin-* token stylesheets, ThemeRuntime state, the General settings font rows, and the pre-plugin bootstrap."
|
|
3
3
|
kind: "package-reference"
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
|
|
|
9
9
|
|
|
10
10
|
## Summary
|
|
11
11
|
|
|
12
|
-
`qilin-client-ui-theme` lets Web GUI users choose `light`, `dark`, or `system
|
|
12
|
+
`qilin-client-ui-theme` lets Web GUI users choose `light`, `dark`, or `system`, and set the font and font size of text, code, and the sidebar terminal separately in Settings. A loopback client stores these values in the `ui-theme` settings namespace, which the provider persists in `$QILIN_HOME/settings.yaml` by default. The plugin resolves `system` through `prefers-color-scheme` and publishes immutable `ThemeSnapshot`s; ui-layout applies each snapshot to the document. The package also ships the `--qilin-*` token stylesheets and injects a synchronous bootstrap so the selected palette, font sizes, and fonts apply before the shell loads. Third-party themes can register alias-token overrides through `ctx.theme`.
|
|
13
13
|
|
|
14
14
|
## Table of Contents
|
|
15
15
|
|
|
@@ -29,9 +29,13 @@ Users switch the color scheme and content typography from three rows in Settings
|
|
|
29
29
|
|
|
30
30
|
### Typography
|
|
31
31
|
|
|
32
|
-
The plugin registers
|
|
32
|
+
The plugin registers Appearance preference cubes and the text font-size stepper in the General section. A More font settings button after the stepper expands a region below it, collapsed on every settings open, with a font row for each of text, code, and the sidebar terminal, plus the code and terminal font-size steppers. The account menu owns the light/dark/system choice, over the same service. The text stepper accepts integer values from 10 through 22 px and defaults to 14 px. It changes conversation headings and base text by the same increment, including the user bubble and composer draft; flow-row titles, summaries, and tables follow one step under the body size, while small text keeps a fixed size. The code stepper (10–16 px, default 11) sets the code-block size; inline code stays 1 px larger, and the small tool-output variant uses the same size. The terminal stepper (10–20 px, default 13) sets the sidebar terminal cell font size; changing it keeps the shell and output and refits the grid. Each accepted change writes through the Host settings API. Rapid changes serialize in gesture order with namespace revisions, and a rejected latest write reloads the durable values. Non-loopback pages keep these choices process-local.
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
Desktop's fixed `Cmd`/`Ctrl` + `+` (or `=`) and `Cmd`/`Ctrl` + `-` shortcuts change text, code, and terminal sizes together by 1 px, each within its own accepted range. The two actions appear in the shortcut reference and are consumed in the main page and its text inputs; terminal input keeps its own key handling. Web keeps the browser's zoom shortcuts.
|
|
35
|
+
|
|
36
|
+
### Fonts
|
|
37
|
+
|
|
38
|
+
Three rows set the text font (interface and conversation text), the code font (code blocks, inline code, and other `--ds-font-family-code` text), and the sidebar terminal font independently. Each field takes comma-separated family names and commits on blur or Enter; an empty field restores the built-in stack. The service normalizes each list by dropping quotes, backslashes, angle brackets, and control characters and double-quoting every name except CSS generic families, then stores it in `textFontFamily`, `codeFontFamily`, or `terminalFontFamily`. The user list precedes the role's built-in stack, so a font missing on the machine falls back to the default. The field accepts any installed font name; it does not enumerate local fonts.
|
|
35
39
|
|
|
36
40
|
### Registering a theme
|
|
37
41
|
|
|
@@ -39,7 +43,7 @@ A composition can register a third-party theme id with alias-token overrides thr
|
|
|
39
43
|
|
|
40
44
|
### Pre-plugin palette
|
|
41
45
|
|
|
42
|
-
When the host composition includes an HTTP server, the host half embeds the registered `ui-theme` settings, or schema defaults, into each index response. Head CSS selects the document canvas color scheme before any script runs, including a `prefers-color-scheme` query for the `system` preference. A body script then sets `body[data-ds-dark-theme]
|
|
46
|
+
When the host composition includes an HTTP server, the host half embeds the registered `ui-theme` settings, or schema defaults, into each index response. Head CSS selects the document canvas color scheme before any script runs, including a `prefers-color-scheme` query for the `system` preference. A body script then sets `body[data-ds-dark-theme]`, `--qilin-content-font-size`, `--qilin-code-font-size`, `--qilin-terminal-font-size`, and each non-empty `--qilin-font-family-<role>` list before the loading page and application scripts, so the first paint uses the selected palette and text and code sizes, and `ThemeRuntime` starts from the saved sizes and fonts instead of rendering the defaults first.
|
|
43
47
|
|
|
44
48
|
-----
|
|
45
49
|
|
|
@@ -49,7 +53,7 @@ When the host composition includes an HTTP server, the host half embeds the regi
|
|
|
49
53
|
<details>
|
|
50
54
|
<summary>Implementation internals — click to expand</summary>
|
|
51
55
|
|
|
52
|
-
The service owns theme, font-size, and
|
|
56
|
+
The service owns theme, font-size, and font-family state and publishes snapshots. The ui-layout presenter applies those snapshots, and the token sheets own the color and conversation text scales.
|
|
53
57
|
|
|
54
58
|
### Stylesheets
|
|
55
59
|
|
|
@@ -63,7 +67,7 @@ In pointer modality, `html[data-input-modality='pointer'] body :focus-visible:no
|
|
|
63
67
|
|
|
64
68
|
`corner-shape.css` smooths every rounded corner: inside `@supports (corner-shape: superellipse(1.5))` it defines `--qilin-corner-shape` and applies it to all elements and their `::before`/`::after` through the universal selector, so engines without `corner-shape` keep circular corners. Full-round shapes — `border-radius: 50%` circles and pill radii — pair `corner-shape: round` with their radius in the owning component sheet because a superellipse deforms them; the corner-shape stylesheet spec enforces that pairing across every package stylesheet.
|
|
65
69
|
|
|
66
|
-
`gradient-shadow-text.css` derives `--qilin-content-font-delta` from `--qilin-content-font-size` and shifts the Markdown heading and base-text ladder by that increment. It also declares `--qilin-content-leading` on `body` at `0px`; every ladder line height adds that term, so the presenter's leading adjustment moves the rows a tier occupies without changing the size relationships. It also derives the secondary tier `--qilin-content-font-size-secondary` (setting −1 at ≤14, setting −2 above; 13px at the default) with its own `--qilin-content-font-delta-secondary` for the table variants and the flow rows one step under the body. Dense small
|
|
70
|
+
`gradient-shadow-text.css` derives `--qilin-content-font-delta` from `--qilin-content-font-size` and shifts the Markdown heading and base-text ladder by that increment. It also declares `--qilin-content-leading` on `body` at `0px`; every ladder line height adds that term, so the presenter's leading adjustment moves the rows a tier occupies without changing the size relationships. It also derives the secondary tier `--qilin-content-font-size-secondary` (setting −1 at ≤14, setting −2 above; 13px at the default) with its own `--qilin-content-font-delta-secondary` for the table variants and the flow rows one step under the body. Dense small variants stay fixed. The code variants (`--dsw-font-markdown-code`, `-code-block`, `-code-block-small`) shift size and line height by `--qilin-code-font-delta`, the difference between `--qilin-code-font-size` and 11 px. Outside the ladder, the user bubble and composer draft read the body pair directly, and flow-row titles and summaries read the secondary pair. The sheet also owns the shadow scale (`--qilin-shadow-lv*`) and the elevation tokens: `--qilin-elevation-stroke` draws a 0.5px hairline through the rebindable `--qilin-elevation-stroke-color`, and `--qilin-elevation-panel`/`--qilin-elevation-prominent`/`--qilin-elevation-soft` (the composer's larger-blur, lower-alpha tier) layer two faint soft shadows over that stroke, so elevated surfaces set `border: 0` and carry no layout-consuming outline; the derived tokens are re-declared per element so a surface's stroke-color rebind takes effect.
|
|
67
71
|
|
|
68
72
|
### Scrollbar rebinding
|
|
69
73
|
|
|
@@ -71,7 +75,7 @@ In pointer modality, `html[data-input-modality='pointer'] body :focus-visible:no
|
|
|
71
75
|
|
|
72
76
|
### Preference persistence
|
|
73
77
|
|
|
74
|
-
The service provides itself immediately with the schema defaults on a loopback browser, then loads the `ui-theme` namespace and writes each accepted theme, font-size, or
|
|
78
|
+
The service provides itself immediately with the schema defaults on a loopback browser, then loads the `ui-theme` namespace and writes each accepted theme, font-size, or font-family change through the Host settings API. Pushed settings changes and reconnects refetch the namespace. While its own writes are pending, the service ignores refetched sections, so an echo of an earlier write cannot revert a later change; it adopts the durable section once the writes settle. Non-loopback pages do not create that Host-backed scope. The persistence boundary is owned by the [Host-backed preferences note](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md).
|
|
75
79
|
|
|
76
80
|
</details>
|
|
77
81
|
|
package/README.zh.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: "qilin Web
|
|
2
|
+
description: "qilin Web 客户端的主题、字号与字体设置：--qilin-* token 样式表、ThemeRuntime 状态、「通用」设置字体行与插件前引导。"
|
|
3
3
|
kind: "package-reference"
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -9,7 +9,7 @@ kind: "package-reference"
|
|
|
9
9
|
|
|
10
10
|
## 概述
|
|
11
11
|
|
|
12
|
-
`qilin-client-ui-theme` 让 Web GUI 用户在设置中选择 `light`、`dark` 或 `system
|
|
12
|
+
`qilin-client-ui-theme` 让 Web GUI 用户在设置中选择 `light`、`dark` 或 `system`，并分别设置正文、代码与侧栏终端的字体和字号。回环客户端把这些值存入 `ui-theme` 设置命名空间，本地提供方默认将其持久化到 `$QILIN_HOME/settings.yaml`。插件通过 `prefers-color-scheme` 解析 `system` 并发布不可变的 `ThemeSnapshot`；ui-layout 把每份快照应用到 document。本包还提供 `--qilin-*` token 样式表，并注入同步引导，使所选调色板、字号与字体在外壳加载前生效。第三方主题可通过 `ctx.theme` 注册别名 token 覆盖。
|
|
13
13
|
|
|
14
14
|
## 目录
|
|
15
15
|
|
|
@@ -29,9 +29,13 @@ kind: "package-reference"
|
|
|
29
29
|
|
|
30
30
|
### 排版
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
插件在「通用」分区注册外观偏好方块与正文字号步进器。步进器之后有一个「更多字体设置」按钮，展开其下方区域——每次打开设置都保持折叠——内含正文、代码、侧栏终端三个角色的字体行，以及代码与终端字号步进器。明/暗/跟随系统的选择由账户菜单负责，两者共用同一服务。正文字号步进器接受 10 至 22 px 的整数，默认值为 14 px。它以相同增量调整会话标题与基础文本，包括用户气泡与 composer 草稿；流内行的标题、摘要与表格跟随比正文低一档的字号，小号文本保持固定字号。代码步进器（10–16 px，默认 11）设定代码块字号；行内代码大 1 px，小号工具输出变体使用相同字号。终端步进器（10–20 px，默认 13）设定侧栏终端的单元字号；变更后保留 shell 与输出并重新 fitting 网格。每次通过的变更都经 Host settings API 写入。连续快速变更按操作顺序携带命名空间 revision 串行写入，最新写入被拒时重新加载持久值。非 loopback 页面把这些选择都保留在进程内。
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
Desktop 的固定快捷键 `Cmd`/`Ctrl` + `+`（或 `=`）和 `Cmd`/`Ctrl` + `-` 会一起增减正文、代码与终端字号各 1 px，各自不超过自身的取值区间。两个操作显示在快捷键参考中，并在主页面及其文本输入框内生效；终端输入保留自身的按键处理。Web 保留浏览器的缩放快捷键。
|
|
35
|
+
|
|
36
|
+
### 字体
|
|
37
|
+
|
|
38
|
+
三行分别独立设置正文字体（界面与会话正文）、代码字体（代码块、行内代码及其他 `--ds-font-family-code` 文本）与侧栏终端字体。每个输入框接受逗号分隔的字体族名，失焦或回车提交；留空恢复内建字表。服务会规范化每个列表——丢弃引号、反斜杠、尖括号与控制字符，除 CSS 通用族外每个名字加双引号——并存入 `textFontFamily`、`codeFontFamily` 或 `terminalFontFamily`。用户字表排在该角色内建字表之前，机器上缺失的字体回退到默认。输入框接受任何已安装字体名；它不枚举本机字体。
|
|
35
39
|
|
|
36
40
|
### 注册主题
|
|
37
41
|
|
|
@@ -39,7 +43,7 @@ kind: "package-reference"
|
|
|
39
43
|
|
|
40
44
|
### 插件前调色板
|
|
41
45
|
|
|
42
|
-
当主机组合包含 HTTP 服务器时，宿主侧会把已注册的 `ui-theme` 设置或 schema 默认值嵌入每份 index 响应。head CSS 会在任何脚本运行前选择文档画布的配色方案，其中 `system` 偏好使用 `prefers-color-scheme` 查询；随后，body 脚本会在加载页面和应用脚本之前设置 `body[data-ds-dark-theme]
|
|
46
|
+
当主机组合包含 HTTP 服务器时，宿主侧会把已注册的 `ui-theme` 设置或 schema 默认值嵌入每份 index 响应。head CSS 会在任何脚本运行前选择文档画布的配色方案，其中 `system` 偏好使用 `prefers-color-scheme` 查询；随后，body 脚本会在加载页面和应用脚本之前设置 `body[data-ds-dark-theme]`、`--qilin-content-font-size`、`--qilin-code-font-size`、`--qilin-terminal-font-size` 以及每个非空的 `--qilin-font-family-<role>` 字表，因此首帧绘制就采用所选调色板与正文、代码字号，且 `ThemeRuntime` 从已保存的字号与字体出发，而不是先渲染默认值。
|
|
43
47
|
|
|
44
48
|
-----
|
|
45
49
|
|
|
@@ -49,7 +53,7 @@ kind: "package-reference"
|
|
|
49
53
|
<details>
|
|
50
54
|
<summary>实现细节——点击展开</summary>
|
|
51
55
|
|
|
52
|
-
|
|
56
|
+
服务拥有主题、字号与字体状态并发布快照。ui-layout 呈现器应用这些快照，token 样式表则拥有颜色与会话文本尺度。
|
|
53
57
|
|
|
54
58
|
### 样式表
|
|
55
59
|
|
|
@@ -63,7 +67,7 @@ kind: "package-reference"
|
|
|
63
67
|
|
|
64
68
|
`corner-shape.css` 平滑所有圆角：在 `@supports (corner-shape: superellipse(1.5))` 内定义 `--qilin-corner-shape`，并通过通配选择器应用到所有元素及其 `::before`/`::after`，因此不支持 `corner-shape` 的引擎保持普通圆弧。正圆形状——`border-radius: 50%` 的圆与胶囊半径——因超级椭圆会使其变形，须在所属组件样式表中把 `corner-shape: round` 与半径声明配对；corner-shape 样式表 spec 跨全部包样式表强制这一配对。
|
|
65
69
|
|
|
66
|
-
`gradient-shadow-text.css` 从 `--qilin-content-font-size` 派生 `--qilin-content-font-delta`，并以该增量移动 Markdown 标题与基础文本阶梯。它同时在 `body` 上以 `0px` 声明 `--qilin-content-leading`，阶梯里每一档行高都再加这一项，因此呈现器发布的行距调整只移动每档所占的行，不改变尺寸关系。它同时派生低一档变量 `--qilin-content-font-size-secondary`（设置 ≤14 时为设置值 −1，>14 时为设置值 −2；默认设置下为 13px）及配套的 `--qilin-content-font-delta-secondary
|
|
70
|
+
`gradient-shadow-text.css` 从 `--qilin-content-font-size` 派生 `--qilin-content-font-delta`，并以该增量移动 Markdown 标题与基础文本阶梯。它同时在 `body` 上以 `0px` 声明 `--qilin-content-leading`，阶梯里每一档行高都再加这一项，因此呈现器发布的行距调整只移动每档所占的行，不改变尺寸关系。它同时派生低一档变量 `--qilin-content-font-size-secondary`（设置 ≤14 时为设置值 −1，>14 时为设置值 −2；默认设置下为 13px）及配套的 `--qilin-content-font-delta-secondary`，供表格变体与比正文低一档的流内行使用。紧凑的小号文本变体保持固定字号。代码变体（`--dsw-font-markdown-code`、`-code-block`、`-code-block-small`）的字号与行高按 `--qilin-code-font-delta`（`--qilin-code-font-size` 与 11 px 之差）移动。阶梯之外，用户气泡与 composer 草稿直接读取正文档变量对，流内行的标题及摘要读取低一档变量对。该表还持有阴影阶（`--qilin-shadow-lv*`）与 elevation token：`--qilin-elevation-stroke` 经可重绑的 `--qilin-elevation-stroke-color` 画 0.5px 发丝描边，`--qilin-elevation-panel`/`--qilin-elevation-prominent`/`--qilin-elevation-soft`（输入框专用的更大模糊、更低透明度档）在描边之上叠两层极淡柔光，因此高层级表面设 `border: 0`，不再有占布局的轮廓；派生 token 逐元素重声明，使表面对描边色的重绑真实生效。
|
|
67
71
|
|
|
68
72
|
### 滚动条重新绑定
|
|
69
73
|
|
|
@@ -71,7 +75,7 @@ kind: "package-reference"
|
|
|
71
75
|
|
|
72
76
|
### 偏好持久化
|
|
73
77
|
|
|
74
|
-
在 loopback 浏览器上，服务先以 schema 默认值立即提供自身，随后加载 `ui-theme`
|
|
78
|
+
在 loopback 浏览器上，服务先以 schema 默认值立即提供自身，随后加载 `ui-theme` 命名空间，并把每次通过的主题、字号或字体变更经 Host settings API 写入。收到推送的设置变更时或重连后都会重新拉取该命名空间。自身写入未落定期间，服务会忽略重新拉取的节，早期写入的回显不会回滚更晚的变更；写入落定后服务再采纳持久节。非 loopback 页面不会创建该 Host-backed scope。该持久化边界由 [Host 支撑的偏好笔记](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.zh.md) 拥有。
|
|
75
79
|
|
|
76
80
|
</details>
|
|
77
81
|
|