@linkdesk/plugin-docs 0.1.11 → 0.1.12

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.
@@ -322,6 +322,29 @@ The declaration is metadata-only; theme color data is fetched asynchronously at
322
322
 
323
323
  > **🔥 Recipe JSON contract (now folded into plugin-sdk)**: the recipe file that `path` points to is validated against `theme.schema.json` — inside the repo that is `public/schemas/theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, and a format error turns the light red with exit 1 on the spot instead of staying silent); for npm authors it is the `schemas/theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateThemeJson` (the same schema file, so the rules never drift). At runtime, a `parseThemeRecipe` toast is the second line of defense. Theme files should begin with `"$schema"` pointing at the schema to get editor IntelliSense (for the npm path see [11-authoring-themes](11-authoring-themes.md) §②).
324
324
 
325
+ **id naming rule:** the target shape is `<pluginId>.<name>` (**replace the first segment only, leave the stem untouched**), e.g. `theme-pill.pill-bubble`. **One rule covers three ids** — `themes[].id` (recipe), the top-level `id` inside the recipe JSON that `path` points to (recipe), and `colorways[].id` (colorway variant). The severities mirror the key rule above:
326
+
327
+ | Criterion | Severity | Judged by | What happens |
328
+ |:--|:--:|:--|:--|
329
+ | An id must **not** fall inside the **host fallback-id ledger**'s **own space** column | 🔴 **red (rejected)** | the shell runtime `ThemeRegistry` + the SDK leg `linkdesk/appearance-ownership` | The id **is not registered** (the recipe/colorway is simply absent, so users never see it in the picker) and one `console.error` names the fallback id it collided with. Your plugin **still installs** — what is rejected is this one id, not your plugin |
330
+ | A **new** id's first segment should be this repo's `pluginId` | 🟡 yellow (advisory) | the SDK leg (**the runtime does not enforce it**) | The report carries a `suggested` name with only the first segment replaced. The official theme repos still declare 25 ids that break this rule (`mint-soda`, `kraft`, …); the shell renames and migrates those on its own schedule — **write new ids by the rule** |
331
+ | Two recipes of the **same** plugin sharing one **colorway** id | 🟡 yellow + logged | the SDK leg | The shell's contract is that a **colorway id is globally unique** — a cross-recipe duplicate shows up as duplicate entries in the colorway dropdown |
332
+
333
+ The **host fallback-id ledger** ships inside the SDK package and is **split by space** (recipes and colorways are **two namespaces**: `mint-soda` can be both, so the comparison stays **inside the column**, never across):
334
+
335
+ ```
336
+ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
337
+ → "appearanceRecipeIds": ["dark", "light"] ← recipe column
338
+ "appearanceColorwayIds": ["dark-fallback", "light"] ← colorway column (note: the colorway fallback is dark-fallback, not dark)
339
+ "appearanceIdGrants": { "light": ["theme-defaults"] } ← the exception: who holds that id by grant
340
+ ```
341
+
342
+ A fallback id is the layer that keeps **the app rendering after every theme plugin is uninstalled**, so taking one over means taking over the host's fallback surface. **`appearanceIdGrants` is not an allowlist** — it records, **per id**, who holds it: `light` carries a grant because the official theme repo is the *implementer* of the host's light fallback; your plugin is not in that table (and cannot add itself — it is a shell-side public-surface decision) ⇒ it is always judged red.
343
+
344
+ > **Why "taking a fallback id" is red while "missing your prefix" is only yellow**: taking a fallback id does **real harm** (it takes over the host's fallback surface, so themes break once the plugins are uninstalled); whereas "missing the prefix" has 25 counter-examples in the existing corpus, and a hard rule would break those theme repos on the spot. Different severity = different tolerance, not "the more important rule is written more strictly".
345
+
346
+ **Two plugins declaring the same id:** the shell keeps the **first registrant** — the later id **cannot be registered** and one `console.error` names both sides (who arrived first, who was rejected). This is not the same as taking a fallback id: neither side touched the host's names, but **one name has room for one owner only**, so prefixing your own name is what keeps that day from arriving.
347
+
325
348
  ### 3.7 `contributes.iconThemes` — icon themes
326
349
 
327
350
  ```json
@@ -391,6 +414,12 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
391
414
 
392
415
  > **🔥 mappings JSON contract (established — icon-theme.schema.json rewritten to align with the engine's normalizeIconThemeMappings)**: the mappings file that `path` points to is validated against `icon-theme.schema.json` — inside the repo that is `public/schemas/icon-theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, which also scans `contributes.iconThemes`); for npm authors it is the `schemas/icon-theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateIconThemeJson` (the same schema file, so the rules never drift). A runtime parse failure with warn/toast is the second line of defense. Files should begin with `"$schema"` pointing at the schema to get editor IntelliSense.
393
416
 
417
+ **id naming rule:** an icon-theme id is judged on **one thing only** — it must **not** be the host fallback id `default` (red: the id is not registered, plus one `console.error`). The "carry your repo prefix" criterion is **not applied here**: an icon-theme id is **shown verbatim in the settings page** (the picker renders the id text), so renaming it would change user-visible text ⇒ it stays as it is. If you want it to read better in the dropdown, change the `label` (display name), not the id.
418
+
419
+ ```
420
+ → "appearanceIconThemeIds": ["default"] ← icon-theme column (this is its only entry)
421
+ ```
422
+
394
423
  ### 3.8 `contributes.icons` — shared icons
395
424
 
396
425
  ```json
@@ -408,7 +437,10 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
408
437
 
409
438
  Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource": "shared"`).
410
439
 
411
- ### 3.9 `contributes.languages` — UI language packs + `contributes.i18n` — plugin-bundled translations
440
+ **id naming rule:** the **keys** here *are* the shared icon ids (plugin A contributes, plugin B references) ⇒ prefix them with your repo identity: `<pluginId>.<name>` (🟡 advisory, reported by the SDK leg). The host has no fallback shared icons ⇒ this family has **no red**; but when two plugins declare the **same key**, the later one **cannot be registered** and one `console.error` names both sides (the same arbitration as recipes and colorways).
441
+
442
+ ### 3.9 `contributes.languages` — UI language packs
443
+ + `contributes.i18n` — plugin-bundled translations
412
444
 
413
445
  **Two translation pipelines — don't mix them:**
414
446
 
@@ -663,7 +663,7 @@ pluginId "app" is the host's own identity (the host uses it to register configur
663
663
  a plugin using it ⇒ collision detection never fires, and unregistration removes the host's entry.
664
664
  ```
665
665
 
666
- > ⚠️ **Identity and key names are two different things**: `pluginId` decides *who you are*, while the **key names** in `contributes.configuration` decide *who a key belongs to* (that rule is in [03-contributes-spec §3.4](03-contributes-spec.md)). Neither may touch the host's reserved surface, but the criteria and the reports are separate.
666
+ > ⚠️ **Identity, key names and appearance ids are three different things**: `pluginId` decides *who you are*; the **key names** in `contributes.configuration` decide *who a key belongs to* ([03-contributes-spec §3.4](03-contributes-spec.md)); and the **ids** inside `contributes.themes` / `iconThemes` / `icons` (recipe / colorway variant / icon theme / shared icon) decide *who an appearance name belongs to* (same file, §3.6–3.8). All three are **keys of a global registry** and none may touch the host's reserved surface — but they are **three separate ledgers** with separate criteria and separate reports, so be sure which one you are changing.
667
667
 
668
668
  > The complete directory structure (what goes in `resources/` / `src/utils/` / `__tests__/`, naming conventions) is in `09-plugin-directory-layout.md`.
669
669
 
@@ -322,6 +322,29 @@ useEffect(() => {
322
322
 
323
323
  > **🔥 配方 JSON 契约(已随 plugin-sdk 收编)**:`path` 指向的配方文件按 `theme.schema.json` 校验——repo 内 = `public/schemas/theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs`,格式错当场红灯 exit 1 不静默);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/theme.schema.json` + SDK `validateThemeJson`(同一 schema 文件,规则永不漂移)。运行时 `parseThemeRecipe` toast 是第二道防线。主题文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense(npm 路径见 [11-主题制作](11-主题制作.md) §②)。
324
324
 
325
+ **id 命名规则:** 目标形态 = `<pluginId>.<名字>`(**只换第一段、词干零变化**),如 `theme-pill.pill-bubble`。**一条规则管三个 id**——`themes[].id`(配方)、`path` 指向的配方 JSON 里的顶层 `id`(配方),以及 `colorways[].id`(配色变体)。分级与设置键同形,别混着记:
326
+
327
+ | 判据 | 分级 | 谁判 | 会发生什么 |
328
+ |:--|:--:|:--|:--|
329
+ | id **不得**落在**宿主兜底 id 账**的**本空间**那一栏 | 🔴 **红(拒注册)** | 壳运行时 `ThemeRegistry` + SDK 腿 `linkdesk/appearance-ownership` | 该 id **注册不上**(配方/配色当即缺席,用户在选择器里看不到它)+ 一条 `console.error` 点名撞上的是哪条兜底 id。插件**照常装上**——拒的是这一个 id,不是你的插件 |
330
+ | **新** id 第一段应是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿(**运行时不管**) | 报点带 `suggested` = 只换第一段的新名。存量官方主题仓还有 25 条 id 不合此规(`mint-soda`、`kraft` …),改名与迁移由壳侧统一执行——**新 id 请照规矩写** |
331
+ | 同一插件的**两个配方**用同一个**配色** id | 🟡 黄 + 登记 | SDK 腿 | 壳的契约是「配色变体 id **全局唯一**」——跨配方重复会让配色下拉出现重复项 |
332
+
333
+ **宿主兜底 id 账**随 SDK 包下发,**按空间分栏**(配方与配色是**两个名字空间**:`mint-soda` 可以同时是两者,所以只比**本栏**,绝不跨栏):
334
+
335
+ ```
336
+ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
337
+ → "appearanceRecipeIds": ["dark", "light"] ← 配方栏
338
+ "appearanceColorwayIds": ["dark-fallback", "light"] ← 配色栏(注意:配色兜底叫 dark-fallback,不叫 dark)
339
+ "appearanceIdGrants": { "light": ["theme-defaults"] } ← 例外:为该 id 记了证照的持有者
340
+ ```
341
+
342
+ 兜底 id 是「**全部主题插件卸光后仍能渲染**」的那一层,占它 = 顶替宿主的保底面。**`appearanceIdGrants` 不是白名单**——它**按 id 记**谁持有:`light` 有证照,因为官方主题仓正是宿主亮色兜底的**实现者**;你的插件不在表里(那是壳侧的公共面决策,作者加不进去)⇒ 一律判红。
343
+
344
+ > **为什么"占兜底 id"是红、"没带自己前缀"只是黄**:占兜底 id 有**真害**(顶替宿主保底面,插件全卸光后主题跟着坏);而"没带前缀"在存量里有 25 个反例,一刀切会把既有主题仓当场弄坏。分级不同 = 容忍度不同,不是"更重要的规矩写法更严"。
345
+
346
+ **跨插件撞名(同一个 id 两个插件都声明):** 壳**先者保留**——后注册的那个 id **注册不上**,并给一条 `console.error` 点名双方(谁先到、谁被拒)。它不是"占兜底 id":两边都没碰宿主的名字,但**一个名字只有一份**,所以把自己的名字带上,才不会等到这一天。
347
+
325
348
  ### 3.7 `contributes.iconThemes`——图标主题
326
349
 
327
350
  ```json
@@ -391,6 +414,12 @@ useEffect(() => {
391
414
 
392
415
  > **🔥 mappings JSON 契约(立——icon-theme.schema.json 重写对齐引擎 normalizeIconThemeMappings)**:`path` 指向的 mappings 文件按 `icon-theme.schema.json` 校验——repo 内 = `public/schemas/icon-theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs` 兼扫 `contributes.iconThemes`);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/icon-theme.schema.json` + SDK `validateIconThemeJson`(同一 schema 文件,规则永不漂移)。运行时解析失败 warn/toast 是第二道防线。文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense。
393
416
 
417
+ **id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 会**原样显示在设置页**(选择器直接渲染 id 文本),给它改名 = 用户可见文字变化 ⇒ 本轮不动。想让它在下拉里好看,改的是 `label`(显示名),不是 id。
418
+
419
+ ```
420
+ → "appearanceIconThemeIds": ["default"] ← 图标主题栏(只有这一条)
421
+ ```
422
+
394
423
  ### 3.8 `contributes.icons`——共享图标
395
424
 
396
425
  ```json
@@ -408,7 +437,10 @@ useEffect(() => {
408
437
 
409
438
  插件 A 贡献、插件 B 引用(`"icon": "stm32-chip"` + `"iconSource": "shared"`)。
410
439
 
411
- ### 3.9 `contributes.languages`——UI 语言包 + `contributes.i18n`——插件自带翻译
440
+ **id 命名规则:** 这里的**键**就是共享图标 id(插件 A 贡献、插件 B 引用)⇒ 建议带上本仓归属 `<pluginId>.<名字>`(🟡 建议,SDK 腿报点)。宿主没有兜底共享图标 ⇒ 这一族**没有红**;但两个插件声明**同一个键**时,后注册者**注册不上** + 一条 `console.error` 点名双方(与配方/配色同一条仲裁)。
441
+
442
+ ### 3.9 `contributes.languages`——UI 语言包
443
+ + `contributes.i18n`——插件自带翻译
412
444
 
413
445
  **两条翻译管道,别混:**
414
446
 
@@ -659,7 +659,7 @@ plugins/<pluginId>/ ← repo 源码树(塌平单根;目录名 =
659
659
  pluginId "app" 是宿主自己的身份(宿主用它注册配置/外观/更新),插件用它 ⇒ 冲突检测永不响、注销会摘掉宿主条目。
660
660
  ```
661
661
 
662
- > ⚠️ **身份与键名是两件事**:`pluginId` 决定"你是谁",`contributes.configuration` 的**键名**决定"这个键归谁"(那份规矩见 [03-插件contributes规范 §3.4](03-插件contributes规范.md))。两者都不许碰宿主的保留面,但判据与报点各自独立。
662
+ > ⚠️ **身份、键名、外观 id 是三件事**:`pluginId` 决定"你是谁";`contributes.configuration` 的**键名**决定"这个键归谁"([03-插件contributes规范 §3.4](03-插件contributes规范.md));`contributes.themes` / `iconThemes` / `icons` 里的 **id**(配方 / 配色变体 / 图标主题 / 共享图标)决定"这个外观名归谁"(同篇 §3.6–3.8)。三者都是**全局名册的键**、都不许碰宿主的保留面,但**三本不同的账**、判据与报点各自独立——认准你改的是哪一个。
663
663
 
664
664
  > 完整目录结构(`resources/` / `src/utils/` / `__tests__/` 放什么、命名约定)见 `09-插件目录规范.md`。
665
665
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.11",
3
+ "version": "0.1.12",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [