dsh-plugin-core 0.10.1 → 0.11.0

package/docs/design/style.md

@@ -17,6 +17,56 @@ What stays here is what you must honour when **changing styles in this repo**.
 EN: The client bundle is a CJS closure loaded by `window.__ModuleLoader__.load`, so `import './x.css'` produces a
 separate asset the kernel never loads — CSS must be injected at runtime as a TS string.
 
+## 控件样式按需：每个控件只注入自己那份
+
+> EN: Per-control styles: every control injects only its own
+
+（2026-10-30 起）**注入是按控件的，不是一把全量**：每个控件在 render 里调
+`ensureComponentStyles('<域>', <自己那份 CSS>)`（幂等，每次 render 调都安全），用不到的控件其 CSS
+不进消费方的包 —— 实测只用 `Button` 时样式文本从 71.7 KB 降到 9.4 KB。
+
+EN: Injection is per control, not one big blob. Each control calls `ensureComponentStyles('<domain>', <its own CSS>)`
+during render (idempotent); CSS of controls you never use never reaches your bundle.
+
+新增控件照做：import 自己那份 `*_CSS` 常量 + 在组件里调一次 `ensureComponentStyles`。
+
+1. **不要顺手把别人的 CSS 一起传进去** —— 传了就退化成全量，包体省不下来。
+2. **跨控件的修饰一律用更高特异性表达**（`.dshpc-split .dshpc-seg`），由提供上下文的那个控件
+   负责它自己那份；**绝不靠注入顺序** —— 顺序 = 控件首次渲染顺序，不固定。
+   有自检盯着：`test/css-contract.test.mjs` 禁止跨常量出现同名选择器（含 `@media` 内）。
+3. **CSS 必须是 `export const X_CSS` 的字符串常量**（被显式引用的值）：`package.json` 的
+   `sideEffects: false` 既不会误删它、又能让用不到的那份被摇掉。
+   **绝不能退回 `import './x.css'`** —— 那是副作用式导入，webpack 官方点名它会在 `sideEffects:false`
+   下被连样式一起摇掉（组件渲染出来没样式）。
+
+EN: (1) never bundle someone else's CSS into your call; (2) express cross-control overrides with higher
+specificity, never with injection order (order = first-render order, not fixed) — the contract test forbids
+same-name selectors across constants; (3) keep CSS as exported string constants — never go back to
+`import './x.css'`, which `sideEffects:false` would drop along with the styles.
+
+### 为什么不用 `@layer` 分层（评估过，有意不做）
+
+> EN: Why we deliberately do not use `@layer`
+
+`@layer`（CSS Cascading and Inheritance L5，Baseline 2022-03）能让层序显式固定、不受注入时机影响，
+听上去正好治「顺序不确定」。**但它在这里会适得其反**：
+
+- **未分层样式压过任何层**：层级裁决优先于特异性。一旦把 dshpc 样式包进 `@layer dshpc`，
+  宿主任何**未分层的元素级重置**（`button { font-size: 14px }` 之类）就会反过来压过我们，
+  层内特异性再高也没用 ⇒ 控件被宿主皮肤吃掉。
+- **不分层反而更稳**：现状下我们的 `.dshpc-btn`（0,1,0）靠特异性就能压过宿主的 `button`（0,0,1）。
+
+所以「不分层」是**有意为之，不是遗漏**。真要分层，必须先把宿主的元素级样式摸清楚；而且只能整套一层
+（`@layer dshpc`），**不能按组件拆层** —— 层间忽略特异性会直接打掉 `.dshpc-split .dshpc-seg` 这类
+靠特异性生效的拼接定制。
+
+EN: `@layer` would let layer order be explicit and immune to injection timing, but here it backfires:
+unlayered styles beat anything inside a layer, and layer judgement precedes specificity. Wrapping our styles
+in `@layer dshpc` would let the host's unlayered element resets (`button { font-size }`) override our rules no
+matter how specific they are. Staying unlayered is deliberate — `.dshpc-btn` (0,1,0) already beats the host's
+`button` (0,0,1) on specificity. If layering ever becomes necessary: one layer for the whole kit, never per
+control.
+
 ## 交互态颜色（hover / active）
 
 > EN: Interaction colors (hover / active)

package/docs/help/integration.doc.ts

@@ -4,11 +4,11 @@ import type { DocTopic } from '../design/doc-format.js'
 const install = `pnpm add dsh-plugin-core`
 const initStyle = `// 插件 client 入口
 import { createStyleKit } from 'dsh-plugin-core/design'
-import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
+import { setStyleKit } from 'dsh-plugin-core/ui'
 
 const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
 setStyleKit(kit)
-ensureControls()`
+// 只需这一行：控件首次渲染时自注入自己那份 CSS，token 也一并登记。`
 const useControl = `import { Button, Input, Picker, showToast } from 'dsh-plugin-core/ui'
 
 h(Input, { value: name, onChange: setName, placeholder: '任务名', error: nameError })

package/docs/help/integration.md

@@ -47,11 +47,11 @@ pnpm add dsh-plugin-core
 ```ts id="integration-init-style"
 // 插件 client 入口
 import { createStyleKit } from 'dsh-plugin-core/design'
-import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
+import { setStyleKit } from 'dsh-plugin-core/ui'
 
 const kit = createStyleKit({ id: 'dsh-task-reminder-ui' })
 setStyleKit(kit)
-ensureControls()
+// 只需这一行：控件首次渲染时自注入自己那份 CSS，token 也一并登记。
 ```
 
 ```tsx id="integration-use-control"

package/docs/help/style.md

@@ -78,3 +78,38 @@ or by grepping `tokens-css.ts`.
 EN: Reskin by reassigning the same variables inside your own style domain (no fork needed). Add a domain with
 `kit.registerStyle('widget', css)`; re-registering a domain overwrites it. The `tokens` domain always comes
 first — core maintains that ordering. Skin lives in the caller’s domain; components only read tokens.
+
+## 怎么应用：样式是按需的
+
+> EN: How to apply it: styles are on demand
+
+（2026-10-30 起）插件入口**只需 `setStyleKit` 一行**；控件首次渲染时自注入自己那份 CSS（幂等），
+没用到的控件其 CSS 不进你的包。`ensureControls()` 现只登记 token，是**可选**预热，不必再调。
+
+```ts
+import { createStyleKit } from 'dsh-plugin-core/design'
+import { setStyleKit } from 'dsh-plugin-core/ui'
+
+setStyleKit(createStyleKit({ id: 'dsh-task-reminder-ui' }))
+```
+
+EN: Since 2026-10-30 the entry needs only `setStyleKit`; each control self-injects its own CSS on first render,
+and CSS of controls you never use stays out of your bundle. `ensureControls()` now only registers tokens and is
+optional.
+
+## 避免什么
+
+> EN: What to avoid
+
+1. **不要 `import * as core from 'dsh-plugin-core/ui'` / `require('dsh-plugin-core/ui')`** —— 打包器无法摇树，
+   所有控件 CSS 全进你的包（实测差 62.3 KB）。一律**具名导入**。
+2. **不要把多份 CSS 自己拼起来注册成一个域** —— 那等于重建全量注入，按需收益归零。
+   要加自己的皮肤，用 `kit.registerStyle('你的域', css)` 单独注册。
+3. **不要写「靠注入顺序才对」的规则** —— 顺序 = 控件首次渲染顺序，不固定。
+   要覆盖就用更高特异性（多加一个类限定），跨来源的层次用 `@layer`。
+4. **不要退回 `import './x.css'`** —— 客户端产物是 JS 闭包，`.css` 内核不加载；且在
+   `sideEffects: false` 下会被连样式一起摇掉。
+
+EN: (1) Never namespace-import or `require` the barrel − it defeats tree-shaking (62.3 KB difference); use named
+imports. (2) Do not concatenate several CSS constants into one domain − that rebuilds full injection. (3) Never
+rely on injection order; override with higher specificity. (4) Never go back to `import './x.css'`.

package/docs/help/ui.doc.ts

@@ -2,10 +2,11 @@
 import type { DocTopic } from '../design/doc-format.js'
 
 const setup = `import { createStyleKit } from 'dsh-plugin-core/design'
-import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
+import { setStyleKit } from 'dsh-plugin-core/ui'
 
 setStyleKit(createStyleKit({ id: 'dsh-task-reminder-ui' }))
-ensureControls()`
+// 控件样式不用你挂：每个控件首次渲染时自注入自己那份 CSS（幂等），
+// 用不到的控件其 CSS 也不会进你的包。`
 
 const cardExample = `import { Card, Chip, StripCard } from 'dsh-plugin-core/ui'
 

package/docs/help/ui.md

@@ -24,10 +24,11 @@
 
 ```ts id="ui-setup"
 import { createStyleKit } from 'dsh-plugin-core/design'
-import { ensureControls, setStyleKit } from 'dsh-plugin-core/ui'
+import { setStyleKit } from 'dsh-plugin-core/ui'
 
 setStyleKit(createStyleKit({ id: 'dsh-task-reminder-ui' }))
-ensureControls()
+// 控件样式不用你挂：每个控件首次渲染时自注入自己那份 CSS（幂等），
+// 用不到的控件其 CSS 也不会进你的包。
 ```
 
 ## Button / IconButton / Segmented

package/docs/requirements.md

@@ -120,6 +120,12 @@ dsh-plugin-core/
 
 ⇒ 必须是 `createStyleKit({ id })`：每个插件调一次领一套自己的（`<style>` 标签 id 按插件唯一）。
 
+**（2026-10-30）注入按控件粒度**：每个控件自注入自己那份 CSS（`ensureComponentStyles(domain, css)`，幂等），
+**不许再聚合成一把全量**。全量聚合会让入口模块静态依赖所有 CSS，打包器无法摇树 —— 插件只用 Button 也会
+背上全部 71.7 KB 样式文本。`ensureControls()` 因此收敛为「只登记 token」的可选预热。
+配套约束：消费方须**具名导入**（`import * as` / CJS `require` 会让按需收益归零）；跨控件修饰只许用
+更高特异性表达，不许依赖注入顺序。
+
 ### 5.3 明暗色判据（别跟错）
 
 - 判据 = **`body[data-ds-dark-theme]`**（宿主启动脚本 `toggleAttribute` 写入，
@@ -175,6 +181,7 @@ dsh-plugin-core/
 | v2 | `explorer`（用户拍板要抽） | ✅ 已完成（浏览面板 + 预览；**选择器后移至 ui**，见 §2.4） |
 | v2+ | `explorer` 重做（2026-10-20） | ✅ 已完成（FileBrowser 面板 + `openFilePreview` / `pickWorkspaceFile` 两能力 + 全量预览：md / 代码高亮 / HTML / PDF / Office；官方件经 `./ui/official` 子路径） |
 | v3 | `session` | ⚠️ **半完成**：契约与三种承载已好，**官方会话 UI 镜像未搬**（只做最简渲染） |
+| v3+ | 控件样式按需注入（2026-10-30） | ✅ 已完成（`css.ts` 停全量聚合；27 个组件各自注入自己那份；只 `import { Button }` 时 CSS 文本 71.7 KB → 9.4 KB。**不采用 `@layer`**：未分层样式压过任何层且层级裁决优先于特异性，包进层会被宿主元素级重置反压） |
 | 文档 | README 接入指南 | ✅ 已完成 |
 
 **未做**（按重要性）：消费者插件接入 / 会话 UI 镜像 / 类名隔离 /

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-core",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "packageManager": "pnpm@12.3.4",
   "description": "Shared base for DSH plugins: design tokens, UI controls, utils, workspace explorer, session preview",
   "keywords": [