@linkdesk/plugin-docs 0.1.47 → 0.1.49

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.
@@ -419,6 +419,8 @@ do not need it (`icon` *is* the identity image).
419
419
 
420
420
  > **opt-IN — without declaring `appearsIn.iconBar` there is no icon of yours in the icon bar.** The old `iconLocation` default of `"top"` (opt-OUT — the editor got squeezed into the icon bar even without declaring anything) has been deprecated; it is now controlled declaratively by `appearsIn.iconBar` (`"top"` = the upper icon group, `"bottom"` = the fixed bottom group).
421
421
 
422
+ > 🔴 **`"bottom"` is a geometric position, not "the gear"** (corrected 2026-09-30): the bottom-left gear is a **shell-owned button** (the icon-bar layout's `owned` field) and has nothing to do with any plugin's declaration. Declaring `"bottom"` merely puts your icon in that bottom group, and clicking it **opens your own tab as usual** — the old "clicking a bottom icon opens the gear menu" behaviour has been removed (background: `docs/04-软件更新/待抉择池/齿轮归属与底部图标位/`).
423
+
422
424
  **Two paths to an icon:**
423
425
 
424
426
  | Path | Prerequisite | Description |
@@ -25,7 +25,7 @@ Follow the official settings plugin (= the `plugin.json` in **the settings plugi
25
25
  // omit core — uninstallable; core: true means the UI has no uninstall button (an anti-mistake-deletion flag, not a category)
26
26
  "factoryRole": "settings", // ① the key — declares you are a member of the "settings set" family
27
27
  "entry": "src/index.tsx", // tab entry (appearsIn.tabBar requires entry)
28
- "appearsIn": { "iconBar": "bottom", "tabBar": true },
28
+ "appearsIn": { "tabBar": true }, // ⛔ don't declare iconBar — the bottom-left gear belongs to the shell (bottom is a position, not the gear)
29
29
  "tabBehavior": { "singleton": true }, // singleton — switching won't open a duplicate if it's already open
30
30
  "contributes": {
31
31
  "viewsContainers": {
@@ -115,7 +115,7 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
115
115
  | Host colorway id | `dark-fallback`、`light` | Fallback values of `app.themeColor` and of the colorway source space |
116
116
  | Host icon theme id | `default` | The fallback value of `app.iconTheme` |
117
117
  | Host appearance sentinel | `followTheme` | The "follow the theme" sentinel of a mix source — **it is not an id**, so don't try to shadow it with a plugin id |
118
- | Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
118
+ | Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
119
119
  | Shared-contract context key (plugins **may** set) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | These four are a **public contract**: the official `settings` plugin writes them, host commands read them in `when` clauses — use them as specified, don't change their meaning |
120
120
 
121
121
  **How to check yourself** (from your own repo): once `@linkdesk/plugin-sdk` is installed, your repo's `verify` runs four ownership legs (command ids / config keys / appearance ids / context keys); whichever one you violate is reported with its location plus the suggested fix, **"should start with `<pluginId>.`"**.
@@ -416,6 +416,8 @@ my-plugin/
416
416
 
417
417
  > **opt-IN——不声明 `appearsIn.iconBar` = 图标栏没有你的图标。** 曾经的 `iconLocation` 默认 `"top"`(opt-OUT——编辑器没声明也挤进图标栏)已被废弃,现在由 `appearsIn.iconBar` 声明式控制(`"top"` = 上部图标组,`"bottom"` = 底部固定组)。
418
418
 
419
+ > 🔴 **`"bottom"` 只是几何位置,不是「齿轮」**(2026-09-30 订正):左下角那颗齿轮是**壳自带按钮**(图标栏布局的 `owned` 字段),与任何插件的声明无关。插件声明 `"bottom"` 只是把自己的图标放进底部那一组,点击**照常开自己的标签页**——旧的「点底部图标弹齿轮菜单」行为已废除(背景见 `docs/04-软件更新/待抉择池/齿轮归属与底部图标位/`)。
420
+
419
421
  **两条路拿到图标:**
420
422
 
421
423
  | 路径 | 前提 | 说明 |
@@ -25,7 +25,7 @@
25
25
  // 不填 core —— 可卸载;core: true 则 UI 无卸载按钮(防误删旗标,非类别)
26
26
  "factoryRole": "settings", // ① 关键——声明自己是"设置套"的一份子
27
27
  "entry": "src/index.tsx", // 标签页入口(appearsIn.tabBar 需要 entry)
28
- "appearsIn": { "iconBar": "bottom", "tabBar": true },
28
+ "appearsIn": { "tabBar": true }, // ⛔ 别声明 iconBar——左下齿轮是壳自带的(bottom 只是位置,不是齿轮)
29
29
  "tabBehavior": { "singleton": true }, // 单例——切换时已开就不重复开
30
30
  "contributes": {
31
31
  "viewsContainers": {
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
117
117
  | 宿主配色 id | `dark-fallback`、`light` | `app.themeColor` 与配色来源空间的兜底取值 |
118
118
  | 宿主图标主题 id | `default` | `app.iconTheme` 的保底取值 |
119
119
  | 宿主外观哨兵值 | `followTheme` | 混搭来源的「跟随主题」哨兵——**它不是 id**,别拿一个插件 id 去顶它 |
120
- | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
120
+ | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
121
121
  | 宿主公开约定旗子(插件**可设**) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | 这 4 个是**公开约定面**:官方 `settings` 插件写、宿主命令的 `when` 读——照约定用,别改语义 |
122
122
 
123
123
  **怎么自查**(你自己的仓里就能跑):装上 `@linkdesk/plugin-sdk` 后,你仓里的 `verify` 会跑四条归属腿
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.47",
3
+ "version": "0.1.49",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [