@linkdesk/plugin-docs 0.1.68 → 0.1.69

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.
@@ -463,6 +463,35 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
463
463
 
464
464
  > **🔥 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.
465
465
 
466
+ **Starting from an existing icon pack (bulk import)**: a few hundred mappings are not something you write by hand. If you are starting from a VS Code `iconTheme` (Material Icon Theme, vscode-icons, …), the SDK converts it and copies only the assets your mappings really reference:
467
+
468
+ ```bash
469
+ npm pack material-icon-theme # any package shipping dist/<x>-icons.json + icons/*.svg
470
+ tar xzf material-icon-theme-*.tgz
471
+ npx @linkdesk/plugin-sdk import-icon-theme package/dist/material-icons.json \
472
+ --name material --out icons/material.json --assets icons/material --list icon-import.json
473
+ ```
474
+
475
+ What it does: `iconDefinitions[k].iconPath` → the `imagePath` form; upstream `fileExtensions` keys gain the leading dot (`ts` → `.ts`); the five top-level default icons above are carried over; **only referenced SVGs are copied** (upstream packs carry a thousand or more). Flags: `--name` (theme name; default = the source file's basename), `--out` (default `icons/<name>.json`), `--assets` (default `icons/<name>/`), `--icons-dir` (where the upstream SVGs live; default `<source dir>/../icons`). It prints a ready-to-paste `contributes.iconThemes` snippet, and reminds you to ship the upstream LICENSE.
476
+
477
+ **Your editing decisions stay in your own repo** — `--list` points at a manifest you keep beside your sources, so the artifact can be regenerated byte-identically later:
478
+
479
+ ```json
480
+ {
481
+ "extensions": ["ts", "tsx", "rs"],
482
+ "fileNames": ["package.json", "readme.md"],
483
+ "folders": ["src", "docs"],
484
+ "overrides": { "o": "lib" },
485
+ "localIcons": { "uvprojx": "uvprojx" }
486
+ }
487
+ ```
488
+
489
+ - `extensions` / `fileNames` / `folders` — which upstream keys you want (omit one = all of them; a key upstream does not have is skipped **and reported**, so a typo is visible instead of silent);
490
+ - `overrides` — send an extension to a different upstream definition (when upstream's own classification does not fit your context);
491
+ - `localIcons` — your own artwork, living at `<assets>/<name>.svg`: written into the mappings, **never copied from upstream**, and a missing file is a hard error (that mapping would 404 at runtime).
492
+
493
+ Leave `--list` off entirely and you get every mapping upstream declares — the zero-setup path when you have no opinion yet.
494
+
466
495
  **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 a **registration key** (the value users store in `app.iconTheme`), so renaming it means migrating old values for no gain ⇒ it stays as it is. ⚠️ **Correction, 2026-10-01**: the dropdown **now renders the `label`** (display path wired up — see the exemption note below) — to make it read better in the dropdown, translate the `label` (in your own dictionary), ⛔ not the id.
467
496
 
468
497
  ```
@@ -736,6 +765,10 @@ useEffect(() => {
736
765
  }, []);
737
766
  ```
738
767
  > **`when: "false"` = a purely programmatic command that stays out of the command palette** — titleActions-only commands are declared this way, which keeps them from cluttering Ctrl+Shift+P. The shell's unified renderer `ViewTitleActions.tsx` has two consumers: the panel tab bar (the active view) + the sidebar section collapse header. For a real example see `08 §3`.
768
+ > ⚠️ The single-parameter `(args)` works here because titleActions hands over **one object** (the `args` field is
769
+ > that object). ⛔ **Do not carry this form over to `ContextMenu` items**: that path **spreads** the payload
770
+ > (`handler(...args)`), so an array payload loses one layer and the menu item silently does nothing. Menu items are
771
+ > always written in **rest form** `(...args)` — see [22, "The menu payload law"](22-menu-contribution-points.md).
739
772
 
740
773
  ### 3.12 `contributes.langDefs` — programming language declarations (main process)
741
774
 
@@ -119,17 +119,25 @@ than by you:
119
119
  | `context` | **Shared by the whole menu.** When the menu is opened by a shared component, that component supplies it (it is not yours to set) |
120
120
 
121
121
  **The menu payload law.** `context` is **shared by the whole menu**; each item's identity must travel in
122
- `MenuItemDescriptor.commandArgs`. The host handler receives `args = [...commandArgs, context]`. A shared
123
- component (for example `PluginCard`) always sends **its own** `context` (`PluginCard` = `{pluginId}`) ⇒
124
- when you consume a shared component's context menu, your handler must tolerate **both** its own payload in
125
- `args[0]` **and** the shared component's context **at the end** — ⛔ never assume `args[0]` is your data
126
- (unless that slot has no shared context at all).
122
+ `MenuItemDescriptor.commandArgs`. The host **spreads** the payload into your handler (`handler(...args)`), so the
123
+ handler receives `args = [...commandArgs, context]`. A shared component (for example `PluginCard`) always sends
124
+ **its own** `context` (`PluginCard` = `{pluginId}`) ⇒ when you consume a shared component's context menu, your
125
+ handler must tolerate **both** its own payload in `args[0]` **and** the shared component's context **at the end**
126
+ — ⛔ never assume `args[0]` is your data (unless that slot has no shared context at all).
127
+
128
+ > 🔴 **Write the handler in rest form `(...args)`** — ⛔ not a single parameter `(args)`. A single parameter
129
+ > receives **only the first** argument (`commandArgs[0]`): an array payload gets **one layer stripped**, the parser
130
+ > finds no target, and the menu item **silently does nothing** — with no error anywhere.
131
+ > This is not hypothetical: on 2026-10-06 both gear menus of the settings file-associations manager turned out to be
132
+ > dead exactly this way, while the unit tests stayed **green** — they handed the whole array in as one argument,
133
+ > which happens to match the parser's expectation. Two mechanical guards pin it: the "spread arguments" cases in
134
+ > `electron/preload-pool/commands.test.ts` (host side) and the "single-parameter shape is always rejected" section in
135
+ > `fileAssociationsGearTarget.test.ts` (plugin side).
127
136
 
128
137
  ```ts
129
- // Consuming PluginCard's gear menu: args = [{ pluginId }, context]
130
- // Your own payload (from commandArgs) first, the shared component's context last.
131
- linkdesk.commands.registerCommand("my-plugin.onCardGear", (args) => {
132
- const mine = args?.[0] as { pluginId?: string } | undefined;
138
+ // Consuming PluginCard's gear menu: the handler receives the SPREAD arguments args = [your payload, shared context]
139
+ linkdesk.commands.registerCommand("my-plugin.onCardGear", (...args) => { // 🔴 rest form, ⛔ not (args)
140
+ const mine = args[0] as { pluginId?: string } | undefined;
133
141
  if (!mine?.pluginId) return; // no target ⇒ do nothing (never "act on an empty one")
134
142
  /* … */
135
143
  });
@@ -458,6 +458,35 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
458
458
 
459
459
  > **🔥 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。
460
460
 
461
+ **从一个现成的图标包起步(批量导入)**:几百条映射不是手写的活。若你手里是一个 VS Code `iconTheme`(Material Icon Theme / vscode-icons …),SDK 负责转换,并且**只拷映射真引用到的资产**:
462
+
463
+ ```bash
464
+ npm pack material-icon-theme # 任何「dist/<x>-icons.json + icons/*.svg」形态的包
465
+ tar xzf material-icon-theme-*.tgz
466
+ npx @linkdesk/plugin-sdk import-icon-theme package/dist/material-icons.json \
467
+ --name material --out icons/material.json --assets icons/material --list icon-import.json
468
+ ```
469
+
470
+ 它干的事:`iconDefinitions[k].iconPath` → `imagePath` 形态;上游 `fileExtensions` 的键补上前导点(`ts` → `.ts`);上面那五枚顶层默认图标原样带过来;**只拷被引用的 SVG**(上游整包上千个)。旗标:`--name`(主题名,缺省 = 源文件主名)、`--out`(缺省 `icons/<名>.json`)、`--assets`(缺省 `icons/<名>/`)、`--icons-dir`(上游 SVG 住哪,缺省 `<源文件目录>/../icons`)。跑完会打印一段**可粘贴的 `contributes.iconThemes` 片段**,并提醒你把上游 LICENSE 一并带上。
471
+
472
+ **选哪些图标——这是你的编辑决定,留在你自己的仓里**:`--list` 指向一份与你源码并排保管的清单 ⇒ 产物日后可**逐字节重跑**:
473
+
474
+ ```json
475
+ {
476
+ "extensions": ["ts", "tsx", "rs"],
477
+ "fileNames": ["package.json", "readme.md"],
478
+ "folders": ["src", "docs"],
479
+ "overrides": { "o": "lib" },
480
+ "localIcons": { "uvprojx": "uvprojx" }
481
+ }
482
+ ```
483
+
484
+ - `extensions` / `fileNames` / `folders`——你要的上游键(**省略某一项 = 全要**;上游没有的键会被跳过**并如实报出**,所以写错是看得见的,不是静默的);
485
+ - `overrides`——把某个扩展名改指上游另一枚定义(上游自己的归类不合你的语境时用);
486
+ - `localIcons`——你自己的图,放在 `<资产目录>/<名>.svg`:只写进映射、**绝不从上游拷**,缺文件直接判错(那条映射运行时会 404)。
487
+
488
+ **完全不传 `--list`** = 导入上游声明的全部映射——你还没拿定主意时的零配置路径。
489
+
461
490
  **id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 是**注册键**(用户选中的值存在 `app.iconTheme` 里),改名 = 要迁移盘上旧值,收益只落在 id 本身 ⇒ 本轮不动。⚠️ **2026-10-01 更正**:下拉**已改为渲染 `label`**(显示面打通,见下文豁免段)——想让它在下拉里好看,改的是 `label` 的**译名**(本仓字典),⛔ 不是改 id。
462
491
 
463
492
  ```
@@ -724,6 +753,9 @@ useEffect(() => {
724
753
  }, []);
725
754
  ```
726
755
  > **`when: "false"` = 纯程序化命令不进命令面板**——titleActions 专属命令都这样声明,防止在 Ctrl+Shift+P 里刷屏。壳统一渲染器 `ViewTitleActions.tsx` 两处消费:面板标签栏(活动视图)+ 侧栏 section 折叠头。真实示例见 `08 §三`。
756
+ > ⚠️ 这里的单参 `(args)` 能吃下,是因为 titleActions 送的就是**一个对象**(`args` 字段即该对象)。
757
+ > ⛔ **别把这个写法搬到 `ContextMenu` 的菜单项上**:那条路壳是**展开**传参(`handler(...args)`),
758
+ > 数组型载荷会被剥掉一层 ⇒ 菜单项静默空转。菜单项一律写 **rest 形式** `(...args)`,见 [22 篇「菜单载荷律」](22-菜单贡献点.md)。
727
759
 
728
760
  ### 3.12 `contributes.langDefs`——编程语言声明(主进程)
729
761
 
@@ -115,15 +115,21 @@
115
115
  | `context` | **整菜单共享**。菜单由共享件弹出时,由那个共享件供给(轮不到你设) |
116
116
 
117
117
  > **菜单载荷律**:`ContextMenu` 的 `context` 是**整菜单共享**的;每一项的身份必须走 `MenuItemDescriptor.commandArgs`。
118
- > 壳 handler 收到 `args = [...commandArgs, context]`。共享件(如 `PluginCard`)会固定送**它自己的** `context`
119
- > (`PluginCard` = `{pluginId}`)⇒ 消费共享件齿轮的插件,handler 必须同时容忍 `args[0]` 是自己的载荷、
120
- > **末尾**是共享件的 context——⛔ 不要假设 `args[0]` 一定是你的数据(除非该槽位无共享 context)。
118
+ > 壳把载荷**展开**喂给你的 handler(`handler(...args)`)⇒ handler 收到的实参是 `args = [...commandArgs, context]`。
119
+ > 共享件(如 `PluginCard`)会固定送**它自己的** `context`(`PluginCard` = `{pluginId}`)⇒ 消费共享件齿轮的插件,
120
+ > handler 必须同时容忍 `args[0]` 是自己的载荷、**末尾**是共享件的 context——⛔ 不要假设 `args[0]` 一定是你的数据
121
+ > (除非该槽位无共享 context)。
122
+
123
+ > 🔴 **所以 handler 必须写成 rest 形式 `(...args)`**——⛔ 不要写单参 `(args)`:单参只收**第一枚**实参
124
+ > (`commandArgs[0]`),数组型载荷会被**剥掉一层**,解析器于是读不到目标 ⇒ 菜单项点了**静默无反应**、不报错。
125
+ > 这不是理论:2026-10-06 实测设置管理器两处齿轮的三条命令全空转,而单测**全绿**——老单测把整包数组当
126
+ > 一枚实参喂进 handler,恰好与解析器同形。机械判据两处:壳侧 `electron/preload-pool/commands.test.ts` 的
127
+ > 「展开实参」两条 + 插件侧 `fileAssociationsGearTarget.test.ts`「单参形状一律判空」一节。
121
128
 
122
129
  ```ts
123
- // 消费 PluginCard 的齿轮菜单:args = [{ pluginId }, context]
124
- // 自己的载荷(来自 commandArgs)在前,共享件的 context 在末。
125
- linkdesk.commands.registerCommand("my-plugin.onCardGear", (args) => {
126
- const mine = args?.[0] as { pluginId?: string } | undefined;
130
+ // 消费 PluginCard 的齿轮菜单:handler 收的是**展开后**的实参 args = [自己的载荷, 共享件的 context]
131
+ linkdesk.commands.registerCommand("my-plugin.onCardGear", (...args) => { // 🔴 rest 形式,⛔ 不是 (args)
132
+ const mine = args[0] as { pluginId?: string } | undefined;
127
133
  if (!mine?.pluginId) return; // 没有目标 ⇒ 什么都不做(⛔ 不「清了个空的」)
128
134
  /* … */
129
135
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.68",
3
+ "version": "0.1.69",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [