dsh-plugin-core 0.10.0 → 0.11.0

package/dist/ui/css.js

@@ -1,38 +1,15 @@
 import { createStyleKit } from '../design/index.js';
-import { BACK_TO_TOP_CSS, BUTTON_CSS, DATETIME_CSS, FIELD_CSS, HINT_CSS, LOADING_CSS, SEGMENTED_CSS, SPLIT_GROUP_CSS, } from './controls-css.js';
-import { MARQUEE_CSS } from './marquee-css.js';
-import { PICKER_CSS } from './picker-css.js';
-import { FEEDBACK_CSS } from './feedback-css.js';
-import { CARD_CSS } from './card-css.js';
-import { CHIP_CSS } from './chip-css.js';
-import { CODE_VIEWER_CSS } from './code-viewer-css.js';
-import { PANEL_DOCK_CSS } from './panel-dock-css.js';
-import { EXPLORER_CSS } from '../explorer/explorer-css.js';
-import { SESSION_CSS } from '../session/session-css.js';
-export const CONTROLS_DOMAIN = 'controls';
 /**
- * 全部控件样式（数组顺序不可调换：同特异性规则后注入者胜出）。
- * 导出仅供 `test/css-contract.test.mjs` 做文本自检，不作为对外 API。
+ * 旧版「控件样式全量域」名。
+ *
+ * ⚠️ 2026-10-30 起这里**不再**聚合注入全部控件样式：当初是把 17 组 CSS 拼成
+ * `CONTROLS_CSS` 一把 `applyStyle(CONTROLS_DOMAIN, …)`，结果 `css.ts` 静态依赖了
+ * 每一份 CSS —— 打包器无法摇树，插件只用 Button 也会背上全部 71.7 KB 样式文本。
+ * 现在改成每个控件自注入自己那份（见 {@link ensureComponentStyles}）。
+ *
+ * 保留导出只为向后兼容消费方可能引用过它这个常量，值不再参与注入。
  */
-export const CONTROLS_CSS = [
-    SEGMENTED_CSS,
-    BUTTON_CSS,
-    FIELD_CSS,
-    LOADING_CSS,
-    BACK_TO_TOP_CSS,
-    HINT_CSS,
-    PICKER_CSS,
-    DATETIME_CSS,
-    FEEDBACK_CSS,
-    EXPLORER_CSS,
-    SESSION_CSS,
-    CARD_CSS,
-    CHIP_CSS,
-    MARQUEE_CSS,
-    PANEL_DOCK_CSS,
-    CODE_VIEWER_CSS,
-    SPLIT_GROUP_CSS,
-].join('\n');
+export const CONTROLS_DOMAIN = 'controls';
 /**
  * 当前插件的样式设施。
  *
@@ -47,9 +24,29 @@ export function setStyleKit(kit) {
 export function getStyleKit() {
     return current;
 }
-/** 登记 token + 控件样式并确保挂载（幂等）。 */
+/**
+ * 只登记 token 变量（幂等；不挂载 `<style>`）。
+ *
+ * 插件启动时调一次做预热是安全的，但**不是必需的** —— 任何控件首次渲染时
+ * 也会自行登记 token（见 {@link ensureComponentStyles}）。token 域始终排在所有控件域之前
+ * （`style-kit.ts` 的 composeCss 强制），所以颜色 / 变量引用链不受拆分影响。
+ */
 export function ensureControls(kit = current) {
     kit.registerStyle('tokens', kit.tokensCss);
-    kit.applyStyle(CONTROLS_DOMAIN, CONTROLS_CSS);
+}
+/**
+ * 确保某个控件自己的样式已登记、且 `<style>` 已挂载（幂等，可直接在 render 里调）。
+ *
+ * 每个控件**只传自己那份 CSS**：把它依赖的那 1~2 份传进来即可，绝不能顺手把别人的拼上去
+ * （一拼就又退化成全量，包体省不下来）。同理，若是某份 CSS 里带上下文限定的修饰
+ * （如 `.dshpc-split .dshpc-seg`），那份由提供上下文的控件自己负责，消费者不用管。
+ *
+ * @param domain 本控件的样式域，repo 内唯一。
+ * @param css 该控件自己的 CSS 文本。
+ * @param kit 样式设施（默认取当前插件的 kit）。
+ */
+export function ensureComponentStyles(domain, css, kit = current) {
+    kit.registerStyle('tokens', kit.tokensCss);
+    kit.applyStyle(domain, css);
 }
 //# sourceMappingURL=css.js.map

package/dist/ui/css.js.map

@@ -1 +1 @@
-{"version":3,"file":"css.js","sourceRoot":"","sources":["../../src/ui/css.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiB,MAAM,oBAAoB,CAAA;AAClE,OAAO,EACL,eAAe,EACf,UAAU,EACV,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,WAAW,EACX,aAAa,EACb,eAAe,GAChB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AAEvD,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAA;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa;IACb,UAAU;IACV,SAAS;IACT,WAAW;IACX,eAAe;IACf,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,cAAc;IACd,eAAe;IACf,eAAe;CAChB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;;;;GAMG;AACH,IAAI,OAAO,GAAa,cAAc,CAAC,EAAE,EAAE,EAAE,oBAAoB,EAAE,CAAC,CAAA;AAEpE,MAAM,UAAU,WAAW,CAAC,GAAa;IACvC,OAAO,GAAG,GAAG,CAAA;AACf,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,cAAc,CAAC,MAAgB,OAAO;IACpD,GAAG,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;IAC1C,GAAG,CAAC,UAAU,CAAC,eAAe,EAAE,YAAY,CAAC,CAAA;AAC/C,CAAC"}
+{"version":3,"file":"css.js","sourceRoot":"","sources":["../../src/ui/css.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAiB,MAAM,oBAAoB,CAAA;AAElE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAA;AAEzC;;;;;;GAMG;AACH,IAAI,OAAO,GAAa,cAAc,CAAC,EAAE,EAAE,EAAE,oBAAoB,EAAE,CAAC,CAAA;AAEpE,MAAM,UAAU,WAAW,CAAC,GAAa;IACvC,OAAO,GAAG,GAAG,CAAA;AACf,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,MAAgB,OAAO;IACpD,GAAG,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;AAC5C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,GAAW,EAAE,MAAgB,OAAO;IACxF,GAAG,CAAC,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,SAAS,CAAC,CAAA;IAC1C,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;AAC7B,CAAC"}

package/dist/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"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"}

package/dist/ui/index.js

@@ -1,6 +1,7 @@
 // ui —— 基础控件（依赖 design）。
-// 使用前：插件启动时 `setStyleKit(createStyleKit({ id }))` 一次，
-// 再调一次 `ensureControls()` 把 token + 控件样式挂上（幂等）。
+// 使用前：插件启动时 `setStyleKit(createStyleKit({ id }))` 一次。
+// 控件样式**由各控件自注入**：每个控件只登记自己那份 CSS（幂等），用不到的控件其 CSS 不进包；
+// `ensureControls()` 退化为可选的 token 预热，不再需要调。
 export { CONTROLS_DOMAIN, ensureControls, getStyleKit, setStyleKit } from './css.js';
 export { filterGroups, flattenOptions, groupOf, labelsOf, resolveTriggerSizing, toGroups, toggleValue, } from './picker-logic.js';
 export { Picker } from './Picker.js';

package/dist/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ui/index.ts"],"names":[],"mappings":"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"}

package/dist/ui/loading-host.d.ts

@@ -8,6 +8,11 @@ export type LoadingVariant = 'toast' | 'block';
 /** 七向定位：与 Toast 的六向同名，另加 `center`。默认 `bottom-center`。 */
 export type LoadingPosition = 'top-left' | 'top-center' | 'top-right' | 'center' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 /** 浮层定位类名（`center` 走基础规则，不需要修饰类）。 */
+/**
+ * 为什么这里要自注入 `LOADING_CSS`：拿这个类名的调用方通常是**自己画**浮层
+ * （否则直接渲染 `Loading` 组件即可），那时 core 里没有任何组件被渲染 ⇒ 没人登记这份 CSS
+ * ⇒ 浮层会裸奔。类名出口处登记一次，任何拿类名自绘的路径都有样式（幂等）。
+ */
 export declare function loadingOverlayClass(position: LoadingPosition): string;
 export interface LoadingRequest {
     /** 文案；不传走内置字典 `loadingDefault`（数据加载中 / Loading）。 */

package/dist/ui/loading-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loading-host.d.ts","sourceRoot":"","sources":["../../src/ui/loading-host.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAEjD,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,eAA6C,CAAA;AAE1E,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAOtD;AAED,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9C,yDAAyD;AACzD,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,aAAa,GACb,eAAe,GACf,cAAc,CAAA;AAElB,qCAAqC;AACrC,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAErE;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,eAAe,CAAA;IACzB,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,sBAAsB;IACtB,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAAA;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,cAAc,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI;IACnC,OAAO,IAAI,gBAAgB,GAAG,IAAI,CAAA;IAClC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAAA;CAC7C,CAmBA"}
+{"version":3,"file":"loading-host.d.ts","sourceRoot":"","sources":["../../src/ui/loading-host.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAIjD,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,eAA6C,CAAA;AAE1E,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAOtD;AAED,2CAA2C;AAC3C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,OAAO,CAAA;AAE9C,yDAAyD;AACzD,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,YAAY,GACZ,WAAW,GACX,QAAQ,GACR,aAAa,GACb,eAAe,GACf,cAAc,CAAA;AAElB,qCAAqC;AACrC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAGrE;AAED,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,cAAc,CAAA;IACvB,QAAQ,EAAE,eAAe,CAAA;IACzB,mCAAmC;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,sBAAsB;IACtB,SAAS,CAAC,EAAE,SAAS,CAAA;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAAA;CAC7C;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,cAAc,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI;IACnC,OAAO,IAAI,gBAAgB,GAAG,IAAI,CAAA;IAClC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAAA;CAC7C,CAmBA"}

package/dist/ui/loading-host.js

@@ -4,6 +4,8 @@
 // 会在两处各冒一个。这里与 toast-host 同一手法：globalThis 上用 Symbol.for 的单例，
 // 先到场的副本建浮层，其余副本把请求交给它 —— 所有调用落在**同一个屏幕位置**。
 // 纯逻辑、零 DOM / React 依赖 ⇒ Node 单测可直接断言单例语义。
+import { ensureComponentStyles } from './css.js';
+import { LOADING_CSS } from './controls-css.js';
 /** 全局注册表键：Symbol.for 跨 bundle 副本天然共享同一个符号。 */
 export const LOADING_HOST_KEY = Symbol.for('dsh-plugin-core/loading-host');
 /** 全局单例：已注册则直接返回（不触发 create），否则建一个并注册。 */
@@ -17,7 +19,13 @@ export function claimLoadingHost(create) {
     return created;
 }
 /** 浮层定位类名（`center` 走基础规则，不需要修饰类）。 */
+/**
+ * 为什么这里要自注入 `LOADING_CSS`：拿这个类名的调用方通常是**自己画**浮层
+ * （否则直接渲染 `Loading` 组件即可），那时 core 里没有任何组件被渲染 ⇒ 没人登记这份 CSS
+ * ⇒ 浮层会裸奔。类名出口处登记一次，任何拿类名自绘的路径都有样式（幂等）。
+ */
 export function loadingOverlayClass(position) {
+    ensureComponentStyles('loading', LOADING_CSS);
     return `dshpc-loading-overlay dshpc-loading-overlay--${position}`;
 }
 /**

package/dist/ui/loading-host.js.map

@@ -1 +1 @@
-{"version":3,"file":"loading-host.js","sourceRoot":"","sources":["../../src/ui/loading-host.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,oDAAoD;AACpD,6DAA6D;AAC7D,6CAA6C;AAC7C,2CAA2C;AAI3C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAA;AAE1E,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB,CAAI,MAAe;IACjD,MAAM,CAAC,GAAG,UAA2C,CAAA;IACrD,MAAM,QAAQ,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAA;IACpC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAA;IAC3C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAA;IACxB,CAAC,CAAC,gBAAgB,CAAC,GAAG,OAAO,CAAA;IAC7B,OAAO,OAAO,CAAA;AAChB,CAAC;AAeD,qCAAqC;AACrC,MAAM,UAAU,mBAAmB,CAAC,QAAyB;IAC3D,OAAO,gDAAgD,QAAQ,EAAE,CAAA;AACnE,CAAC;AA6BD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAI/B,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,IAAI,OAAO,GAA4B,IAAI,CAAA;IAC3C,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO;QACtB,IAAI,CAAC,OAAuB;YAC1B,MAAM,EAAE,GAAG,EAAE,GAAG,CAAA;YAChB,OAAO,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAA;YACzB,IAAI,MAAM,GAAG,KAAK,CAAA;YAClB,OAAO;gBACL,KAAK;oBACH,qCAAqC;oBACrC,IAAI,MAAM,IAAI,OAAO,EAAE,EAAE,KAAK,EAAE;wBAAE,OAAM;oBACxC,MAAM,GAAG,IAAI,CAAA;oBACb,OAAO,GAAG,IAAI,CAAA;gBAChB,CAAC;aACF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"loading-host.js","sourceRoot":"","sources":["../../src/ui/loading-host.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,EAAE;AACF,oDAAoD;AACpD,6DAA6D;AAC7D,6CAA6C;AAC7C,2CAA2C;AAG3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,8CAA8C;AAC9C,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,8BAA8B,CAAC,CAAA;AAE1E,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB,CAAI,MAAe;IACjD,MAAM,CAAC,GAAG,UAA2C,CAAA;IACrD,MAAM,QAAQ,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAA;IACpC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAA;IAC3C,MAAM,OAAO,GAAG,MAAM,EAAE,CAAA;IACxB,CAAC,CAAC,gBAAgB,CAAC,GAAG,OAAO,CAAA;IAC7B,OAAO,OAAO,CAAA;AAChB,CAAC;AAeD,qCAAqC;AACrC;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAyB;IAC3D,qBAAqB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAA;IAC7C,OAAO,gDAAgD,QAAQ,EAAE,CAAA;AACnE,CAAC;AA6BD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAI/B,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,IAAI,OAAO,GAA4B,IAAI,CAAA;IAC3C,OAAO;QACL,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO;QACtB,IAAI,CAAC,OAAuB;YAC1B,MAAM,EAAE,GAAG,EAAE,GAAG,CAAA;YAChB,OAAO,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,CAAA;YACzB,IAAI,MAAM,GAAG,KAAK,CAAA;YAClB,OAAO;gBACL,KAAK;oBACH,qCAAqC;oBACrC,IAAI,MAAM,IAAI,OAAO,EAAE,EAAE,KAAK,EAAE;wBAAE,OAAM;oBACxC,MAAM,GAAG,IAAI,CAAA;oBACb,OAAO,GAAG,IAAI,CAAA;gBAChB,CAAC;aACF,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/docs/design/architecture.md

@@ -44,8 +44,11 @@ utils（谁都不依赖，谁都可以用）
 插件启动 ──▶ setStyleKit(createStyleKit({ id }))
                     │
                     ▼
-              ensureControls() ──▶ 往 <head> 插一个 <style id="{id}">
-                                    内容 = tokens 域 + 各控件域拼成的 CSS 文本
+        用到的控件首次渲染 ──▶ 自注入自己那份 CSS（幂等）
+                                    │
+                                    ▼
+                       往 <head> 插/更新一个 <style id="{id}">
+                       内容 = tokens 域 + 各「已用到」的控件域拼成的 CSS 文本
 ```
 
 为什么必须运行时注入：DSH 客户端产物是 `window.__ModuleLoader__.load({ id, factory })` 的
@@ -107,7 +110,8 @@ dist/**                产物形态不变，仍由 createStyleKit 拼成一份
 
 ## 触发关系
 
-- `setStyleKit()` / `ensureControls()`：插件启动时调一次（幂等）。
-- 控件渲染时内部会再调 `ensureControls()`，漏了初始化也不会白屏，只是样式可能晚一帧。
-- `ensureControls()` 无 `document` 时静默跳过（SSR / 单测不炸）。
+- `setStyleKit()`：插件启动时调一次；不调则走默认 kit（多插件同页会互相覆盖，务必调）。
+- 控件样式**按需**：各控件首次渲染时自注入自己那份 CSS（幂等），没用到的控件其 CSS 不进包。
+  `ensureControls()` 现只剩「登记 token」一件事，是可选预热而非必需步骤。
+- 自注入无 `document` 时静默跳过（SSR / 单测不炸）。
 - `showToast()` 无 `document` 时静默跳过。

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'
 
@@ -112,8 +113,8 @@ const doc: DocTopic = {
           en: 'IconButton: variant plain|outline|danger (default plain), size (default lg), icon (required), label (required, doubles as a11y name and title).',
         },
         {
-          zh: 'Segmented：`items`（必填）支持单选 / 多选，`size`（默认 lg；三档总高 24 / 28 / 32）、`bordered`（1px 外框，总高不变）、`multiple`（多选）。外观只有一套：灰底轨道 + 白色选中片，选中片的描边环与阴影由宿主 elevation token 提供（离线兜底值没有那圈环）。选中片配色只经 `tone`：传内置色名（与 Chip 同名的 business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate）时底与字由核心定、深浅两主题各自成立；传 `{ bg, fg }` 时两个主题都用调用方这一对颜色（对比度由调用方负责）。段内 `count`（弱化灰字）/ `badge`（红角标）接受 `number | string`：数字 ≤0 不显示，字符串原样显示（如 `1K` / `99+`）。',
-          en: 'Segmented: `items` (required) supports single or multiple selection; `size` (default lg; totals 24 / 28 / 32), `bordered` (1px outer frame, same total height), `multiple` (multi-select). One look only: grey track + white selected pill; its stroke ring and shadow come from the host elevation token (the offline fallback has no ring). The selected pill’s colors go through `tone` only: a built-in color name (business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate, same names as Chip) lets the core pick background and text per theme; `{ bg, fg }` uses that pair verbatim in both themes (contrast is the caller’s call). An item’s `count` (muted text) and `badge` (red pill) take `number | string`: numbers ≤0 render nothing, strings render as given (e.g. `\'1K\'` / `\'99+\'`).',
+          zh: 'Segmented：`items`（必填）支持单选 / 多选，`size`（默认 lg；三档总高 24 / 28 / 32）、`bordered`（1px 外框，总高不变）、`multiple`（多选）。外观只有一套：灰底轨道 + 白色选中片，选中片的描边环与阴影由宿主 elevation token 提供（离线兜底值没有那圈环）。选中片配色只经 `tone`：传内置色名（与 Chip 同名的 business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate）时底与字由核心定、深浅两主题各自成立；传 `{ bg, fg }` 时两个主题都用调用方这一对颜色（对比度由调用方负责）。段内 `count`（弱化灰字，选中段内自动跟着选中片字色提亮）/ `badge`（红角标）接受 `number | string`：数字 ≤0 不显示，字符串原样显示（如 `1K` / `99+`）。',
+          en: 'Segmented: `items` (required) supports single or multiple selection; `size` (default lg; totals 24 / 28 / 32), `bordered` (1px outer frame, same total height), `multiple` (multi-select). One look only: grey track + white selected pill; its stroke ring and shadow come from the host elevation token (the offline fallback has no ring). The selected pill’s colors go through `tone` only: a built-in color name (business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate, same names as Chip) lets the core pick background and text per theme; `{ bg, fg }` uses that pair verbatim in both themes (contrast is the caller’s call). An item’s `count` (muted text; auto-lightened to follow the selected pill’s text color while selected) and `badge` (red pill) take `number | string`: numbers ≤0 render nothing, strings render as given (e.g. `\'1K\'` / `\'99+\'`).',
         },
       ],
       api: [

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
@@ -42,9 +43,9 @@ IconButton：variant: plain|outline|danger（默认 plain）、size（默认 lg
 
 > EN: IconButton: variant plain|outline|danger (default plain), size (default lg), icon (required), label (required, doubles as a11y name and title).
 
-Segmented：`items`（必填）支持单选 / 多选，`size`（默认 lg；三档总高 24 / 28 / 32）、`bordered`（1px 外框，总高不变）、`multiple`（多选）。外观只有一套：灰底轨道 + 白色选中片，选中片的描边环与阴影由宿主 elevation token 提供（离线兜底值没有那圈环）。选中片配色只经 `tone`：传内置色名（与 Chip 同名的 business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate）时底与字由核心定、深浅两主题各自成立；传 `{ bg, fg }` 时两个主题都用调用方这一对颜色（对比度由调用方负责）。段内 `count`（弱化灰字）/ `badge`（红角标）接受 `number | string`：数字 ≤0 不显示，字符串原样显示（如 `1K` / `99+`）。
+Segmented：`items`（必填）支持单选 / 多选，`size`（默认 lg；三档总高 24 / 28 / 32）、`bordered`（1px 外框，总高不变）、`multiple`（多选）。外观只有一套：灰底轨道 + 白色选中片，选中片的描边环与阴影由宿主 elevation token 提供（离线兜底值没有那圈环）。选中片配色只经 `tone`：传内置色名（与 Chip 同名的 business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate）时底与字由核心定、深浅两主题各自成立；传 `{ bg, fg }` 时两个主题都用调用方这一对颜色（对比度由调用方负责）。段内 `count`（弱化灰字，选中段内自动跟着选中片字色提亮）/ `badge`（红角标）接受 `number | string`：数字 ≤0 不显示，字符串原样显示（如 `1K` / `99+`）。
 
-> EN: Segmented: `items` (required) supports single or multiple selection; `size` (default lg; totals 24 / 28 / 32), `bordered` (1px outer frame, same total height), `multiple` (multi-select). One look only: grey track + white selected pill; its stroke ring and shadow come from the host elevation token (the offline fallback has no ring). The selected pill’s colors go through `tone` only: a built-in color name (business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate, same names as Chip) lets the core pick background and text per theme; `{ bg, fg }` uses that pair verbatim in both themes (contrast is the caller’s call). An item’s `count` (muted text) and `badge` (red pill) take `number | string`: numbers ≤0 render nothing, strings render as given (e.g. `'1K'` / `'99+'`).
+> EN: Segmented: `items` (required) supports single or multiple selection; `size` (default lg; totals 24 / 28 / 32), `bordered` (1px outer frame, same total height), `multiple` (multi-select). One look only: grey track + white selected pill; its stroke ring and shadow come from the host elevation token (the offline fallback has no ring). The selected pill’s colors go through `tone` only: a built-in color name (business / success / warning / danger / purple / pink / cyan / teal / orange / indigo / rose / slate, same names as Chip) lets the core pick background and text per theme; `{ bg, fg }` uses that pair verbatim in both themes (contrast is the caller’s call). An item’s `count` (muted text; auto-lightened to follow the selected pill’s text color while selected) and `badge` (red pill) take `number | string`: numbers ≤0 render nothing, strings render as given (e.g. `'1K'` / `'99+'`).
 
 | 参数 | 类型 | 默认 | 说明(zh) | 说明(en) |
 |---|---|---|---|---|

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.0",
+  "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": [