@deepseek-ai/dsh-client-ui-theme 0.0.1-rc.1 → 0.0.1-rc.2

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.
Files changed (10) hide show
  1. package/README.i18n.yaml +2 -2
  2. package/README.md +3 -1
  3. package/README.zh.md +2 -0
  4. package/lib/client.js +12 -6
  5. package/lib/index.js +52 -4
  6. package/lib/types/boot-theme.d.ts +17 -0
  7. package/lib/types/client/index.d.ts +6 -2
  8. package/lib/types/index.d.ts +4 -3
  9. package/package.json +26 -18
  10. package/lib/types/client/settings-contract.d.ts +0 -8
package/README.i18n.yaml CHANGED
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
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
- README.md: 7b81728b02c0dadcbd134a4bca20c49721a3dd52
6
- README.zh.md: 81b64c356749b6ffe12694b218e92eaa483ff739
5
+ README.md: df4d5e0370962bf6f2a8ac0a7b88d669225dc5c5
6
+ README.zh.md: e0f614645a16b44e374e450bb8dd1e3c5805ea42
package/README.md CHANGED
@@ -4,6 +4,8 @@ English | [中文](README.zh.md)
4
4
 
5
5
  Theme plugin: ThemeService over the --dsw-* token base stylesheets (static scale + alias semantic layers). The service owns the live theme preference (`light`/`dark`/`system`), resolves `system` through `prefers-color-scheme`, and publishes immutable `ThemeSnapshot`s on the `theme/change` event; it never touches the DOM — ui-layout's presenter applies the resolved snapshot (`html { color-scheme }`, `body[data-ds-dark-theme]`, and inline alias tokens). A loopback browser provides the service immediately with `system`, then loads `ui-theme.preference` in the background and writes each built-in selection through the Host settings API, whose local provider stores it in `$DSH_HOME/settings.yaml` by default; pushed settings changes and reconnects refetch it, rapid selections are serialized in gesture order with namespace revisions, and a rejected latest write reloads the durable value. A remote browser cannot access the privileged settings API, so its selection remains process-local. Third-party registered theme ids remain an in-process extension and do not cross the built-in settings schema; removing one never overwrites the last durable built-in preference. The [Host-backed preferences decision](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md) owns the persistence boundary.
6
6
 
7
+ When the host composition includes an HTTP server, the host half injects a synchronous bootstrap immediately after the opening `<body>` tag. Each index response embeds the registered Host setting for `ui-theme.preference`, or `system` when no settings provider is present; the browser resolves `system` from the OS scheme, then sets `color-scheme` and `body[data-ds-dark-theme]` before the shell loading page renders. Compositions without an HTTP server remain unaffected, and ThemeService and ui-layout remain authoritative for client state and subsequent DOM updates after the plugin tree activates.
8
+
7
9
  `src/styles/` holds five sheets, all imported by the web shell's `base.css`: `base.css`, `design-platform.css`, `scrollbar.css`, `gradient-shadow-text.css`, and `shiki.css`. `scrollbar.css` is the sole consumer of the `--dsw-alias-scrollbar-*` tokens and must follow `design-platform.css`, which declares them.
8
10
 
9
11
  Scrollbar rebinding contract: `scrollbar.css` binds `--dsh-scrollbar-thumb` and `--dsh-scrollbar-thumb-hover` on `body` to the l1 (base-surface) tokens, and both rendering paths read that pair. An elevated surface (menu, popover, dialog) sets `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` and `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)` on its own container; one rebind retints whichever path the engine took. The pair's other legal target is `transparent`, which draws no thumb at all — [ui-sidebar](../ui-sidebar/README.md) rebinds its column that way while the pointer is elsewhere. A rebind to the l1 pair is not a rebind; it restates the base-surface default.
@@ -20,5 +22,5 @@ None; this package neither assembles nor sends a provider request.
20
22
 
21
23
  ## Known Limitations and Deferred Work
22
24
 
23
- - **Third-party themes are a surface, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
25
+ - **Third-party themes are an extension point, not a product** — registering one means overriding same-named alias variables; no validation exists that an override set is complete.
24
26
  - **The token sheets are the sole color authority** — values absent from cssdesign (for example the design's #4176E6 tab blue) are deliberately not appended; the nearest semantic token wins. Design-owner-approved additions are the exception and enter as a static step plus a semantic alias in the same change (`--dsw-static-blue-900` / `--dsw-alias-label-primary-bluish`).
package/README.zh.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  主题插件：基于 --dsw-* token 基础样式表（静态尺度 + 别名语义层）的 ThemeService。该服务拥有实时主题偏好（`light`／`dark`／`system`），将 `system` 通过 `prefers-color-scheme` 解析为实际主题，并发布不可变的 `ThemeSnapshot`，通过 `theme/change` 事件通知变化；它绝不接触 DOM：ui-layout 的呈现器会应用解析后的快照（`html { color-scheme }`、`body[data-ds-dark-theme]`，以及主题的别名 token 内联变量）。来自回环地址的浏览器会先以 `system` 立即提供该服务，随后在后台加载 `ui-theme.preference`，并将每次内置主题选择通过 Host settings API 写入；其本地提供方默认将设置存入 `$DSH_HOME/settings.yaml`。收到推送的 settings 变更时或重连后，浏览器都会重新拉取该设置；连续快速选择会按操作顺序携带 namespace revision 串行写入，最新写入被拒时则重新加载持久化值。远程浏览器无法访问特权 settings API，因此它的选择仅保留在进程内。已注册的第三方主题 id 仍是进程内扩展，不会跨越内置 settings schema；移除其中任意一个都绝不会覆盖最后一个持久化的内置偏好。该持久化边界由[Host settings 支撑的偏好决策](../../../.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md)拥有。
6
6
 
7
+ 当主机组合包含 HTTP 服务器时，主机侧紧接 `<body>` 起始标签注入同步引导代码。每份 index 响应会嵌入已注册的 Host 设置 `ui-theme.preference`，没有 settings provider 时则嵌入 `system`；浏览器按操作系统配色解析 `system`，随后在外壳加载页面渲染前设置 `color-scheme` 和 `body[data-ds-dark-theme]`。不含 HTTP 服务器的组合不受影响，插件树激活后，ThemeService 与 ui-layout 仍分别是客户端状态和后续 DOM 更新的权威来源。
8
+
7
9
  `src/styles/` 下有五张样式表，全部由 web 壳的 `base.css` 导入：`base.css`、`design-platform.css`、`scrollbar.css`、`gradient-shadow-text.css` 与 `shiki.css`。`scrollbar.css` 是 `--dsw-alias-scrollbar-*` token 的唯一消费方，必须排在声明这些 token 的 `design-platform.css` 之后。
8
10
 
9
11
  滚动条重新绑定约定：`scrollbar.css` 在 `body` 上把 `--dsh-scrollbar-thumb` 与 `--dsh-scrollbar-thumb-hover` 绑定到 l1（基础表面）token，两条渲染路径都读取这一组变量。高层级表面（菜单、浮层、对话框）在自己的容器上设置 `--dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l2)` 与 `--dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l2)`；一次重新绑定即可为引擎实际走的那条路径换色。这组变量的另一个合法目标是 `transparent`，即完全不绘制滑块——[ui-sidebar](../ui-sidebar/README.md) 在指针不在栏内时就这样重新绑定自己的列。绑回 l1 那组不算重新绑定，它只是重述基础表面的默认值。
package/lib/client.js CHANGED
@@ -4,9 +4,9 @@ window.__ModuleLoader__.load({
4
4
  var module = { exports: {} };
5
5
  var exports = module.exports;
6
6
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
7
- let _deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
8
7
  let react_jsx_runtime = require("react/jsx-runtime");
9
8
  let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
9
+ let _deepseek_ai_dsh_client_runtime_client = require("@deepseek-ai/dsh-client-runtime/client");
10
10
  //#region ../../../node_modules/.pnpm/clsx@2.1.1/node_modules/clsx/dist/clsx.mjs
11
11
  function r(e) {
12
12
  var t, f, n = "";
@@ -33,10 +33,10 @@ window.__ModuleLoader__.load({
33
33
  document.head.appendChild(tag);
34
34
  }
35
35
  var AppearanceRow_module_css_default = {
36
+ "themeCube": "_8HJdBW_themeCube",
37
+ "cubeRow": "_8HJdBW_cubeRow",
36
38
  "selected": "_8HJdBW_selected",
37
39
  "group": "_8HJdBW_group",
38
- "cubeRow": "_8HJdBW_cubeRow",
39
- "themeCube": "_8HJdBW_themeCube",
40
40
  "title": "_8HJdBW_title"
41
41
  };
42
42
  //#endregion
@@ -1073,11 +1073,17 @@ window.__ModuleLoader__.load({
1073
1073
  this.ctx.emit("theme/change", this.snapshot);
1074
1074
  }
1075
1075
  };
1076
- /** Required services: settings transport plus slots/locale for the Appearance row. */
1076
+ /**
1077
+ * Required services: settings transport plus slots/locale for the Appearance
1078
+ * row. `remote` carries the forwarded settings invalidation that
1079
+ * `bindSettingsScope` subscribes to on this context.
1080
+ */
1077
1081
  const inject = [
1078
1082
  "slots",
1079
1083
  "locale",
1080
- "connection"
1084
+ "connection",
1085
+ "remote",
1086
+ "settingsScope"
1081
1087
  ];
1082
1088
  /**
1083
1089
  * Client plugin body: provide the theme service and register the
@@ -1086,7 +1092,7 @@ window.__ModuleLoader__.load({
1086
1092
  * @param ctx - client cordis context.
1087
1093
  */
1088
1094
  function apply(ctx) {
1089
- const theme = new ThemeService(ctx, (0, _deepseek_ai_dsh_client_runtime_client.bindSettingsScope)(ctx, { namespace: THEME_SETTINGS_NAMESPACE }));
1095
+ const theme = new ThemeService(ctx, ctx.settingsScope.bind({ namespace: THEME_SETTINGS_NAMESPACE }));
1090
1096
  ctx.provide("theme", theme);
1091
1097
  ctx.effect(() => ctx.locale.register(SETTINGS_NS, {
1092
1098
  zh,
package/lib/index.js CHANGED
@@ -17,15 +17,63 @@ const DEFAULT_PREFERENCE = "system";
17
17
  /** Durable theme schema; also the wire envelope the browser scope validates against. */
18
18
  const ThemeSettingsSchema = z.object({ [THEME_PREFERENCE_FIELD]: z.union([...THEME_PREFERENCES]).default(DEFAULT_PREFERENCE) });
19
19
  //#endregion
20
+ //#region lib/types/boot-theme.js
21
+ /**
22
+ * Host-rendered theme bootstrap for the browser's pre-plugin interval. Each
23
+ * index response embeds the current durable built-in preference; the browser
24
+ * resolves only `system`, then writes the same DOM fields ui-layout's
25
+ * ThemePresenter owns after the client plugin tree activates.
26
+ */
27
+ /** Build the inline script for one schema-validated built-in preference. */
28
+ function bootThemeScript(preference) {
29
+ return `<script>(() => {
30
+ const preference = ${JSON.stringify(preference)}
31
+ const systemDark = preference === 'system'
32
+ && typeof matchMedia !== 'undefined'
33
+ && matchMedia('(prefers-color-scheme: dark)').matches
34
+ const dark = preference === 'dark' || systemDark
35
+ document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
36
+ document.body.toggleAttribute('data-ds-dark-theme', dark)
37
+ })()<\/script>`;
38
+ }
39
+ /**
40
+ * Insert the theme bootstrap immediately after the opening body tag, before
41
+ * the shell mount and module script. Body-less fragments receive it at the
42
+ * end, where the HTML parser has already synthesized a body.
43
+ * @param html - Raw application index HTML.
44
+ * @param preference - Current Host-backed built-in preference.
45
+ * @returns HTML containing the theme bootstrap.
46
+ */
47
+ function injectBootTheme(html, preference = DEFAULT_PREFERENCE) {
48
+ const script = bootThemeScript(preference);
49
+ const body = /<body(?:\s[^>]*)?>/i.exec(html);
50
+ if (body === null) return `${html}${script}`;
51
+ const at = body.index + body[0].length;
52
+ return `${html.slice(0, at)}${script}${html.slice(at)}`;
53
+ }
54
+ //#endregion
20
55
  //#region lib/types/index.js
21
- /** Host registration for the browser theme preference. */
56
+ /** Host registration for the browser theme preference and pre-plugin palette. */
57
+ const THEME_NAMESPACE = settingsNamespace(THEME_SETTINGS_NAMESPACE);
58
+ /** Read the registered preference or use the schema default without a settings provider. */
59
+ function readPreference(ctx) {
60
+ const settings = ctx.get("settings");
61
+ if (settings === void 0) return DEFAULT_PREFERENCE;
62
+ const section = settings.get(THEME_NAMESPACE);
63
+ if (section === void 0) return DEFAULT_PREFERENCE;
64
+ return section.preference;
65
+ }
22
66
  /**
23
- * Register the durable theme section when a settings provider exists.
24
- * @param ctx - Host context whose optional settings service owns the section.
67
+ * Register the durable theme section and initial-theme index transform when
68
+ * their optional Host services are composed.
69
+ * @param ctx - Host context that may acquire settings and HTTP services.
25
70
  */
26
71
  function apply(ctx) {
27
72
  ctx.inject(["settings"], (settingsCtx) => {
28
- settingsCtx.settings.register(settingsNamespace(THEME_SETTINGS_NAMESPACE), ThemeSettingsSchema);
73
+ settingsCtx.settings.register(THEME_NAMESPACE, ThemeSettingsSchema);
74
+ });
75
+ ctx.inject(["httpServer"], (httpCtx) => {
76
+ httpCtx.effect(() => httpCtx.httpServer.tapIndex((html) => injectBootTheme(html, readPreference(ctx))), "client-ui-theme: initial theme bootstrap");
29
77
  });
30
78
  }
31
79
  //#endregion
package/lib/types/boot-theme.d.ts ADDED
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Host-rendered theme bootstrap for the browser's pre-plugin interval. Each
3
+ * index response embeds the current durable built-in preference; the browser
4
+ * resolves only `system`, then writes the same DOM fields ui-layout's
5
+ * ThemePresenter owns after the client plugin tree activates.
6
+ */
7
+ import { type ThemePreference } from './theme-settings.ts';
8
+ /**
9
+ * Insert the theme bootstrap immediately after the opening body tag, before
10
+ * the shell mount and module script. Body-less fragments receive it at the
11
+ * end, where the HTML parser has already synthesized a body.
12
+ * @param html - Raw application index HTML.
13
+ * @param preference - Current Host-backed built-in preference.
14
+ * @returns HTML containing the theme bootstrap.
15
+ */
16
+ export declare function injectBootTheme(html: string, preference?: ThemePreference): string;
17
+ //# sourceMappingURL=boot-theme.d.ts.map
package/lib/types/client/index.d.ts CHANGED
@@ -8,7 +8,7 @@
8
8
  * settings General section — the theme feature owns its own settings surface.
9
9
  */
10
10
  import type { Context } from '@deepseek-ai/cordis';
11
- import { type ClientContext, type SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
11
+ import type { ClientContext, SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
12
12
  import { type ThemeKey } from './locales.ts';
13
13
  import { type ThemePreference, type ThemeSettings } from '../theme-settings.ts';
14
14
  export type { AppearanceRowComponentProps, AppearanceRowInjected } from './AppearanceRow.tsx';
@@ -111,7 +111,11 @@ export declare class ThemeService {
111
111
  private buildSnapshot;
112
112
  private publish;
113
113
  }
114
- /** Required services: settings transport plus slots/locale for the Appearance row. */
114
+ /**
115
+ * Required services: settings transport plus slots/locale for the Appearance
116
+ * row. `remote` carries the forwarded settings invalidation that
117
+ * `bindSettingsScope` subscribes to on this context.
118
+ */
115
119
  export declare const inject: string[];
116
120
  /**
117
121
  * Client plugin body: provide the theme service and register the
package/lib/types/index.d.ts CHANGED
@@ -1,9 +1,10 @@
1
- /** Host registration for the browser theme preference. */
1
+ /** Host registration for the browser theme preference and pre-plugin palette. */
2
2
  import type { Context } from '@deepseek-ai/cordis';
3
3
  export { DEFAULT_PREFERENCE, THEME_PREFERENCE_FIELD, THEME_PREFERENCES, THEME_SETTINGS_NAMESPACE, type ThemePreference, type ThemeSettings, } from './theme-settings.ts';
4
4
  /**
5
- * Register the durable theme section when a settings provider exists.
6
- * @param ctx - Host context whose optional settings service owns the section.
5
+ * Register the durable theme section and initial-theme index transform when
6
+ * their optional Host services are composed.
7
+ * @param ctx - Host context that may acquire settings and HTTP services.
7
8
  */
8
9
  export declare function apply(ctx: Context): void;
9
10
  //# sourceMappingURL=index.d.ts.map
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@deepseek-ai/dsh-client-ui-theme",
3
- "description": "Theme plugin: ThemeService (light/dark/system preference, prefers-color-scheme resolution, theme/change snapshots; no DOM), --dsw-* token base stylesheets; registers the Appearance settings row",
4
- "version": "0.0.1-rc.1",
3
+ "description": "Theme plugin: Host bootstrap for the pre-plugin palette; DOM-free ThemeService for light/dark/system state; --dsw-* token styles and Appearance settings row",
4
+ "version": "0.0.1-rc.2",
5
5
  "publishConfig": {
6
6
  "access": "restricted"
7
7
  },
@@ -35,7 +35,9 @@
35
35
  "inject": [
36
36
  "@deepseek-ai/dsh-client-connection",
37
37
  "@deepseek-ai/dsh-client-runtime",
38
- "@deepseek-ai/dsh-client-locale"
38
+ "@deepseek-ai/dsh-client-locale",
39
+ "@deepseek-ai/dsh-client-ui-settings",
40
+ "@deepseek-ai/dsh-api-remotes"
39
41
  ],
40
42
  "platform": "web",
41
43
  "immediately": true
@@ -44,24 +46,30 @@
44
46
  "license": "BSD-3-Clause",
45
47
  "peerDependencies": {
46
48
  "react": "^18.2.0",
47
- "@deepseek-ai/dsh-client-connection": "^0.0.1-rc.1",
48
- "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
49
- "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
50
- "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
51
- "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
52
- "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
53
- "@deepseek-ai/cordis": "^4.0.1-rc.1"
49
+ "@deepseek-ai/cordis": "^4.0.1-rc.1",
50
+ "@deepseek-ai/dsh-api-remotes": "^0.0.1-rc.2",
51
+ "@deepseek-ai/dsh-client-connection": "^0.0.1-rc.2",
52
+ "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.2",
53
+ "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.2",
54
+ "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.2",
55
+ "@deepseek-ai/dsh-client-ui-settings": "^0.0.1-rc.2",
56
+ "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.2",
57
+ "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.2",
58
+ "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2"
54
59
  },
55
60
  "devDependencies": {
56
61
  "@types/react": "~18.3.1",
57
62
  "react": "^18.2.0",
58
- "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
59
- "@deepseek-ai/dsh-client-test-runtime": "^0.0.1-rc.1",
60
- "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
61
- "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
62
- "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
63
- "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
64
- "@deepseek-ai/cordis": "^4.0.1-rc.1"
63
+ "@deepseek-ai/cordis": "^4.0.1-rc.1",
64
+ "@deepseek-ai/dsh-api-remotes": "^0.0.1-rc.2",
65
+ "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.2",
66
+ "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.2",
67
+ "@deepseek-ai/dsh-client-test-runtime": "^0.0.1-rc.2",
68
+ "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.2",
69
+ "@deepseek-ai/dsh-client-ui-settings": "^0.0.1-rc.2",
70
+ "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.2",
71
+ "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
72
+ "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.2"
65
73
  },
66
74
  "files": [
67
75
  "lib/index.js",
@@ -72,7 +80,7 @@
72
80
  ],
73
81
  "dependencies": {
74
82
  "clsx": "^2.0.0",
75
- "@deepseek-ai/dsh-settings": "^0.0.1-rc.1",
83
+ "@deepseek-ai/dsh-settings": "^0.0.1-rc.2",
76
84
  "@deepseek-ai/schemastery": "^3.18.1-rc.1"
77
85
  },
78
86
  "scripts": {
package/lib/types/client/settings-contract.d.ts DELETED
@@ -1,8 +0,0 @@
1
- /**
2
- * Re-export outlet for the `settings.general.item` slot type consumed by this
3
- * package's Appearance row. The canonical home is the locale package (the
4
- * common dependency of every item registrant); this file exists so row
5
- * modules import the type from within their own package.
6
- */
7
- export type { SettingsGeneralItemOwnerProps } from '@deepseek-ai/dsh-client-locale/client';
8
- //# sourceMappingURL=settings-contract.d.ts.map