skinsuite 0.2.0 → 0.2.1

package/README.md

@@ -288,6 +288,22 @@ npm test            # 先构建，再用 node:test 跑 dist 产物
 
 ⚠️ `src/` 里的相对 import **必须带 `.js` 后缀**：包以 `moduleResolution: NodeNext` 编译，TS 会把 `.js` 映射回 `.ts` 源码，而产物里的相对说明符是原样保留的 —— 不带后缀浏览器与 Node 的原生 ESM 都解析不到。
 
+### 关于 exports：类型统一指向 `src/`，运行时才分 `dist/`
+
+```jsonc
+".":      { "types": "./src/index.ts", "import": "./dist/index.js" },
+"./vue":  { "types": "./src/vue/index.ts", "import": "./src/vue/index.ts" },
+"./vite": { "types": "./src/vite/index.ts", "import": "./src/vite/index.ts" }
+```
+
+`./vue` / `./vite` 含 `.vue` 与构建期代码，**只能以源码形态发布**（`tsc` 编不出 SFC）。
+于是根入口的类型也必须指向 `src/index.ts`：若它指向 `dist/index.d.ts`，同一个类型在
+一个程序里会有**两个身份**（dist 的 d.ts 与 vue 层引用的 src），composite 项目做声明
+产出时直接红 —— `TS2883: The inferred type of 'X' cannot be named without a reference
+to '...' from '../../node_modules/skinsuite/src/types'`。
+
+`dist/` 仍然保留（`.js` + `.d.ts` + sourcemap），运行时走它，纯 JS 消费者不受影响。
+
 ---
 
 ## License

package/docs/onboarding.md

@@ -235,16 +235,23 @@ VITE_THEME_DIR=src/theme
 
 缺省就是 `src/theme`，可不写。**换目录只改这一个变量，不动代码。**
 
-### 5.2 tsconfig / env 类型（可选）
+### 5.2 tsconfig / env 类型（必做一行）
 
-`skinsuite/vite` 自带 `virtual:theme` 的类型声明，宿主通过引入 `skinsuite/vite` 即可获得，
-一般无需自写。若你的 `vue-tsc` 报找不到 `virtual:theme`，确认 `vite.config.ts` 已被 tsconfig
-纳入检查范围，或补一句：
+`skinsuite/vite` 自带 `virtual:theme` 的类型声明（`src/vite/theme.d.ts`），但**类型声明只有在
+被纳入 TS 程序时才有意义**。在你项目的 `src/vite-env.d.ts` 里加一行：
 
 ```ts
-/// <reference types="skinsuite/vite" />
+/// <reference types="vite/client" />
+import "skinsuite/vite";   // 让 theme.d.ts 的 declare module 'virtual:theme' 进程序
 ```
 
+🔴 **不要写 `/// <reference types="skinsuite/vite" />`**——`reference types` 解析不到包的
+**子路径**入口，症状是 `vue-tsc -b` 报 `Cannot find module or type declarations for side-effect
+import of 'virtual:theme'`（TS2882），而 `vite build` / 浏览器全正常，很容易误判成「只是编辑器问题」。
+
+`import` 写在 `.d.ts` 里是**纯类型侧**的：不产生任何运行时代码，也不会把插件打进产物，只是
+把 `src/vite/index.ts` 上的 `/// <reference path="./theme.d.ts" />` 带进程序。
+
 ---
 
 ## 六、bootstrap.ts（启动编排，从这开始写）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skinsuite",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "多主题 / 多版式机制的纯内核（零运行时依赖）：目录名与默认值的白名单常量、主题包契约类型、明暗 mode 与色系 tone、CSS 变量 token 的安全校验、设备维度 URL 参数读取。不碰 DOM / 构建器 / 路由，可在任意前端（Vue / React / Node / SSR）复用。",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,7 +8,7 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./vue": {