@linkdesk/plugin-docs 0.1.74 → 0.1.76

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.
@@ -513,9 +513,14 @@ Leave `--list` off entirely and you get every mapping upstream declares — the
513
513
  }
514
514
  ```
515
515
 
516
- Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource": "shared"`).
516
+ **Two default forms:**
517
517
 
518
- **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).
518
+ - `fontPath` + `fontCharacter` — an icon-font glyph (the VS Code icon extension point form). Renders only where that font itself is loaded; the shared `PluginIcon` (pool side) does not load plugin fonts today, so a font-only icon falls back there.
519
+ - `url` — an image asset (added 2026-11-18, case 04). **Rendered as an ink silhouette**: `mask` + `--icon-ink`, following the theme's text ink (VS Code product-icon semantics — shared icons are chrome, not merchandise). Colorful identity art belongs in your own `icon`/`marketIcon`, **not here**.
520
+
521
+ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource": "shared"`). The reference resolves wherever the consumer injects the shared-icons snapshot (broadcast on `iconTheme:changed`); the settings nav resolves it today (a config contribution's `icon` field), and any component can through `PluginIcon`'s `sharedIcons` prop.
522
+
523
+ **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). 🔴 **Host defaults live in this space too** (`app.group-*` — the settings nav's built-in group icons, 2026-11-18): declaring one of those names is **red** (`host-reserved` — the host registers them at startup, so the runtime rejects your registration and names both sides). For your own keys the family stays advisory; 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).
519
524
 
520
525
  ### 3.9 `contributes.languages` — UI language packs
521
526
  + `contributes.i18n` — plugin-bundled translations
@@ -227,7 +227,7 @@ Multi-theme package:
227
227
  | `core` | `boolean` | `true` = **UI accidental-uninstall guard flag** (matching the newer wording in the field table above) — the uninstall button on the detail page is hidden/disabled; **no behavioral privileges and not a category**: the API/command layers can still uninstall and disable it, and uninstalling writes a `removed` tombstone. Defaults to `false` |
228
228
  | `distribution` | `string` | ⚠️ **Legacy field** (since the single-root flattening on 2026-09-05 it no longer maps to any directory; the install side always normalizes it to `user`; already marked deprecated in the schema). **Third parties must not fill this in** |
229
229
  | `factoryRole` | `string` | System slot role: `"settings"` \| `"marketplace"`. **Filling it in = form 2 (replace / switch into the slot); omitting it = form 1 (coexist as an ordinary view plugin)** — see "The `factoryRole` field in depth" below |
230
- | `iconSource` | `string` | `"codicon"` (default) / `"svg"` / `"url"` |
230
+ | `iconSource` | `string` | `"codicon"` (default) / `"svg"` / `"url"` / `"lucide"` / `"shared"` — `"shared"` references an IconRegistry shared icon **by name** (your own `contributes.icons` key, or a host default such as `app.group-*`); rendering needs the consumer to inject the shared-icons snapshot (settings nav does today) |
231
231
  | `marketIcon` | `string` | The **coloured identity image** for marketplace display (list row + detail header). Unlike `icon`: plugins on the icon bar use it to supply a colour image. Missing → falls back to `icon` → then to the unified default block. See "The marketplace image `marketIcon`" below |
232
232
  | `marketIconSource` | `string` | Same enum as `iconSource`. When the value is `resources/…` you can **just omit it** (inferred from the value) |
233
233
  | `description` | `string` | One-line description shown on the plugin detail page. Multi-line is supported |
@@ -508,9 +508,14 @@ npx @linkdesk/plugin-sdk import-icon-theme package/dist/material-icons.json \
508
508
  }
509
509
  ```
510
510
 
511
- 插件 A 贡献、插件 B 引用(`"icon": "stm32-chip"` + `"iconSource": "shared"`)。
511
+ **default 两种形态:**
512
512
 
513
- **id 命名规则:** 这里的**键**就是共享图标 id(插件 A 贡献、插件 B 引用)⇒ 建议带上本仓归属 `<pluginId>.<名字>`(🟡 建议,SDK 腿报点)。宿主没有兜底共享图标 ⇒ 这一族**没有红**;但两个插件声明**同一个键**时,后注册者**注册不上** + 一条 `console.error` 点名双方(与配方/配色同一条仲裁)。
513
+ - `fontPath` + `fontCharacter`——图标字体字形(VS Code icon 扩展点形态)。只在**字体本身被加载**的地方渲染;共享件 `PluginIcon`(池侧)今天不加载插件字体,纯字体图标在那里兜底回退。
514
+ - `url`——图片资产(2026-11-18 增,04 案)。**按 ink 剪影渲染**:`mask` + `--icon-ink`,跟随主题文字墨色(VS Code product-icon 语义——共享图标是界面骨架,不是货架商品)。彩色身份图请放你自己的 `icon`/`marketIcon`,**不放这里**。
515
+
516
+ 插件 A 贡献、插件 B 引用(`"icon": "stm32-chip"` + `"iconSource": "shared"`)。引用在**消费方注入共享图标快照**的地方解析(快照随 `iconTheme:changed` 广播);设置页导航今天已接(配置贡献的 `icon` 字段),任何组件都能经 `PluginIcon` 的 `sharedIcons` prop 消费。
517
+
518
+ **id 命名规则:** 这里的**键**就是共享图标 id(插件 A 贡献、插件 B 引用)⇒ 建议带上本仓归属 `<pluginId>.<名字>`(🟡 建议,SDK 腿报点)。🔴 **宿主默认项也住这个空间**(`app.group-*`——设置页导航本体组图标,2026-11-18):声明这些名字判**红**(`host-reserved`——宿主启动期先注册,运行时拒绝你的注册并点名双方)。自己的键照旧只是建议级;但两个插件声明**同一个键**时,后注册者**注册不上** + 一条 `console.error` 点名双方(与配方/配色同一条仲裁)。
514
519
 
515
520
  ### 3.9 `contributes.languages`——UI 语言包
516
521
  + `contributes.i18n`——插件自带翻译
@@ -227,7 +227,7 @@ my-plugin/
227
227
  | `core` | `boolean` | `true` = **UI 防误删旗标**(对齐上文字段表 :44 新版措辞)——详情页卸载按钮不显示/禁用;**无行为特权、非类别**:API/命令层可卸可禁,卸走写 removed 墓碑。默认 `false` |
228
228
  | `distribution` | `string` | ⚠️ **遗留字段**(2026-09-05 塌平单根后不再对应任何目录,安装侧恒归一化为 `user`;schema 已标废弃)。**第三方请勿填写** |
229
229
  | `factoryRole` | `string` | 系统插槽角色:`"settings"` \| `"marketplace"`。**填 = 形态二(替换/进槽位切换);不填 = 形态一(普通视图插件并存)**——详见下方「`factoryRole` 字段详解」 |
230
- | `iconSource` | `string` | `"codicon"`(默认)/ `"svg"` / `"url"` |
230
+ | `iconSource` | `string` | `"codicon"`(默认)/ `"svg"` / `"url"` / `"lucide"` / `"shared"`——`"shared"` = **按名引用** IconRegistry 共享图标(自己的 `contributes.icons` 键,或宿主默认项 `app.group-*`);渲染需消费方注入共享图标快照(设置页导航今天已接) |
231
231
  | `marketIcon` | `string` | 市场展示位的**身份彩色图**(列表行 + 详情顶)。与 `icon` 不同:进图标栏的插件用它补一张彩色图。缺省 → 回退 `icon` → 再缺 → 统一默认彩色块。详见下方「市场展示图 `marketIcon`」 |
232
232
  | `marketIconSource` | `string` | 与 `iconSource` 同枚举。写 `resources/…` 时**省略即可**(按值推断) |
233
233
  | `description` | `string` | 一句话描述,插件详情页展示。支持多行 |
@@ -67,7 +67,7 @@
67
67
  "iconSource": {
68
68
  "type": "string",
69
69
  "description": "Icon source",
70
- "enum": ["codicon", "svg", "url", "lucide"],
70
+ "enum": ["codicon", "svg", "url", "lucide", "shared"],
71
71
  "default": "codicon"
72
72
  },
73
73
  "marketIcon": {
@@ -438,7 +438,8 @@
438
438
  "type": "object",
439
439
  "properties": {
440
440
  "fontPath": { "type": "string", "description": "Font file path" },
441
- "fontCharacter": { "type": "string", "description": "Font character code — e.g. \\e001" }
441
+ "fontCharacter": { "type": "string", "description": "Font character code — e.g. \\e001" },
442
+ "url": { "type": "string", "description": "Image asset default (2026-11-18, case 04) — resolved to an absolute URL; rendered as an ink silhouette (mask + --icon-ink, following the theme text ink). Colorful identity art belongs in icon/marketIcon, not here." }
442
443
  },
443
444
  "additionalProperties": false
444
445
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.74",
3
+ "version": "0.1.76",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [
@@ -16,5 +16,8 @@
16
16
  "docs",
17
17
  "authoring"
18
18
  ],
19
- "license": "MIT"
19
+ "license": "MIT",
20
+ "scripts": {
21
+ "prepublishOnly": "node ../../scripts/prepublish-auth-preflight.mjs --npm"
22
+ }
20
23
  }