@linkdesk/plugin-docs 0.1.69 → 0.1.70

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.
@@ -102,10 +102,26 @@ Wording discipline (hard constraint 11): don't frame it as two categories "built
102
102
 
103
103
  ### minAppVersion / requires / permissions
104
104
 
105
- All three are declared in the schema (see [03-contributes](03-contributes-spec.md)) and none is enforced at install time—their semantics align with [02 Lifecycle §9](02-plugin-lifecycle.md):
105
+ All three are declared in the schema (see [03-contributes](03-contributes-spec.md)) and none is enforced at install time—their semantics align with [02 Lifecycle §9](02-plugin-lifecycle.md).
106
+
107
+ #### minAppVersion — **the oldest app version your plugin runs on**
108
+
109
+ Below it the **loader refuses to load you** (toast "requires app version ≥X" + `markLoadFailed`). 🔴 What the user gets is **the whole plugin unusable**, not "one feature missing" — so **too low is far more dangerous than too high**.
110
+
111
+ **How you set it: not the shell you tested on, the things you actually use.**
112
+
113
+ - Shared components are **served by the shell** (only the shell's copy exists at runtime, see [19 §2](19-component-cheatsheet.md)); "which shell first shipped this export" is a **fact** — that is exactly [the table in 19 §2.1](19-component-cheatsheet.md) (generated from the shell repo's export-surface ledger, ⛔ not hand-written).
114
+ - You **imported** an export statically ⇒ you need at least the shell that first had it. Take the **maximum** `since` over all imported names — that is your floor.
115
+ - **You never compute it yourself**: `@linkdesk/plugin-sdk` does. `npm run lint` prints the number to use; `npm run verify` turns CI red; `build` / `publish` block **before writing a distribution artifact** (⛔ a dishonest declaration should never be packaged). ⚠️ `lint` is **WARN-level and never fails** — it tells you, it does not stop you; do not read "lint ran clean" as "the declaration is right".
116
+
117
+ **Three things that catch people out:**
118
+
119
+ - 🔴 **A static `import` has no partial downgrade.** Importing an export that an older shell lacks at the top level means **the whole plugin fails to link** (not "that feature does not appear"). If you want users on older shells to keep the rest of your plugin, switch that one to a **dynamic `import()`** or a **runtime guard** — ⚠️ **that is your choice, not a requirement**: when to load is your call, the shell does not make it for you and the gate will not fail you for it.
120
+ - 🔴 **The default `dev` cannot show you this class of problem.** The default `dev` = **mocked host + the `@latest` ui from your `node_modules`** — every component is there and renders fine, so everything stays green. **To expose it you must either `dev --real` against a real shell or install the package into a real shell.**
121
+ - 🔴 **`dev --real` is one-directional**: it answers "**does this run on this shell**", **not** "**what is the oldest shell I can run on**". For the floor, read the gate output above.
122
+
123
+ #### requires / permissions
106
124
 
107
- - `minAppVersion` — checked at load time (not satisfied → toast + skip)
108
- - **Mechanical gate (SDK lint)**: consuming `@linkdesk/ui` at runtime ⇒ `plugin.json` must declare `minAppVersion` ≥ `0.2.13` (the UI re-anchor version — vendor supply of shared components exists only from that shell onward; `import type` is exempt as compile-time-erased). Enforced by `linkdesk-plugin-sdk lint` (`check-ui-min-app-version`), no disable exit
109
125
  - `requires` — runtime dependency orchestration applies (missing dependency → suspend as PENDING + cycle fail-loud + cascading uninstall in reverse topological order, see [02 §4](02-plugin-lifecycle.md))
110
126
  - **Auto-install at install time (shell-side, opt-in via the request)**: when the install request carries a catalog source URL (the marketplace passes the listing's source), missing `requires` dependencies are installed automatically **inside the same install job** — inline and recursive, no second concurrency slot; a failing dependency fails the parent job (naming the dependency) and rolls back the parent's extracted files so a retry starts clean. Already-installed dependencies are skipped; disabled ones are never auto-enabled. Declaring `requires` is all an author does — no shell changes needed
111
127
  - `permissions` — declaring them informs the user; the authorization model is still pending
@@ -244,7 +244,7 @@ Multi-theme package:
244
244
  | `suggests` | `array` | Optionally related plugins `[{ plugin: string, reason: string }]` |
245
245
  | `requires` | `string[]` | Plugin-level activation dependencies — declared by pluginId; at load time dependencies are loaded before this plugin. No version constraints. See "The `requires` field in depth" below |
246
246
  | `screenshots` | `string[]` | Array of screenshot URLs (enabled in Phase 5+) |
247
- | `minAppVersion` | `string` | Minimum app version requirement |
247
+ | `minAppVersion` | `string` | Minimum app version requirement — **an older shell refuses to load the whole plugin**; gated when you consume `@linkdesk/ui`, see "The `minAppVersion` field in depth" below |
248
248
  | `docs` | `string` | Bundled documentation path (for resource plugins) |
249
249
  | `cardDocMap` | `object` | Card ID → documentation anchor mapping |
250
250
  | `i18n` | `object` | Plugin-bundled translations `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }` — key = the plugin UI's source text (the author's native language is recommended). It lives under `contributes.i18n`, not at the top level. 🔴 **Text your plugin declares must be translated in your own repo** (whoever declares it translates it — see `03 §3.9`) |
@@ -259,6 +259,21 @@ These two fields did exist during early development, but they **never had a read
259
259
 
260
260
  > **Writing them into `plugin.json` has no effect; they are simply ignored** (the top level uses lenient validation, so writing them raises no error — which makes them a lie). **If you copied these two fields from an old tutorial or an old commit → delete them and switch to files.**
261
261
 
262
+ ### The `minAppVersion` field in depth
263
+
264
+ **Semantics**: the **oldest app version your plugin runs on**. Below it the loader **refuses to load the whole plugin** (toast "requires app version ≥X" + `markLoadFailed`) — the user sees a **plugin that does not work**, not "one feature missing". ⇒ **too low is far more dangerous than too high**.
265
+
266
+ **How you set it**: **not the shell you tested on, the things you actually use**. Shared components are served by the shell, and "which shell first shipped this export" is a fact (that is [the table in 19 §2.1](19-component-cheatsheet.md), generated from the shell repo's ledger); take the **maximum** `since` over the exports you **import statically** and that is your floor. **You never compute it yourself** — the tooling does:
267
+
268
+ **This is gated** (leg `check-ui-min-app-version`, shipped inside `@linkdesk/plugin-sdk`):
269
+
270
+ - `npm run lint` prints the number to use (⚠️ WARN-level, **never fails** — it tells you, it does not stop you); `npm run verify` turns your CI red; `build` / `publish` block **before writing the artifact**.
271
+ - The rule: declared ≥ floor (floor = baseline ∪ max `since` over your imported names); importing a name that is not in the ledger ⇒ red (a typo or a private API is not a promised export surface).
272
+ - ⛔ **No disable exit** (a disable comment has no effect) — "knowingly putting older-shell users on a shell that lacks that export" is a semantic error, not a legitimate deviation.
273
+ - A plugin that does not consume `@linkdesk/ui` is out of scope for this leg (`minAppVersion` itself is always optional; how to set it when you only use newer shell commands / IPC is your judgement).
274
+
275
+ Full semantics, the three traps (a static import has no partial downgrade / the default `dev` cannot show it / `dev --real` is one-directional) and how to read the error: [04-distribution-format §minAppVersion](04-distribution-format.md).
276
+
262
277
  ### The `requires` field in depth
263
278
 
264
279
  Plugin-level activation ordering — declares which plugins must be activated before this one is activated.
@@ -49,6 +49,20 @@ The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is
49
49
  - **When you do have to move**: only when a **new component / new prop you want** appears in a higher version — that's a deliberate upgrade on your side, not something you're forced into.
50
50
  - **Curious which shell a package was cut from**: check `dist/shell-provenance.json` inside the package (shell version + short commit + date).
51
51
 
52
+ 🔴 **But one number does need a table: `since` — the shell version an export first appeared in.** "The package moves on its own" is about the **package**; `minAppVersion` compares **shell versions**, and those two numbers are not the same thing. The table below is generated from the shell repo's export-surface ledger (⛔ hand-editing it fails `npm run check`):
53
+
54
+ <!-- ui-since:begin ⚠️ do not touch this line or the closing one — the lines in between are generated by `npm run ui-surface:regen` -->
55
+ | Since | Components | Hooks & helpers | Types |
56
+ |:--|:--|:--|:--|
57
+ | **0.2.13** | `Badge`, `Button`, `ColorPicker`, `Combobox`, `ContextMenu`, `DynamicSelect`, `FileIconResolver`, `FilePathInput`, `FontFamilySelect`, `FormRow`, `HintCard`, `InlineInput`, `MarkdownView`, `NumberInput`, `OverlayPortal`, `PluginIcon`, `SegmentedRadio`, `SelectBox`, `Slider`, `StringListEditor`, `ThemePicker`, `Toggle` | `useClickPreview`, `useClipboardKeys`, `useDebouncedInput`, `DEFAULT_PLUGIN_IDENTITY_URI`, `inferSliderStep`, `pickIdentityArt`, `urlSourceKey` | `ContextMenuProps`, `IconDescriptor`, `InlineInputHandle`, `ManifestIconShape`, `ResolvedIcon` |
58
+ | **0.2.20** | `HintTip` | — | `HintTipProps` |
59
+ | **0.2.22** | `ReadOnlyText`, `SectionSubtitle` | — | — |
60
+ | **0.2.40** | `BackgroundImagePicker`, `EffectiveBadge`, `SegmentPreviewSwatch`, `SegmentPreviewText`, `SourceBadge` | `useStatusPolling`, `CONFIG_NONE_SENTINEL`, `MIX_FOLLOW_THEME_SENTINEL`, `SETTINGS_RENDER_HINTS`, `SETTINGS_UI_HINTS`, `formatEffectiveValue`, `isSettingsUiHint`, `splitStringList` | `BackgroundImagePickerProps`, `EffectiveBadgeProps`, `RunStatusCommand`, `SourceBadgeKind`, `SourceBadgeProps`, `SourceBadgeSource` |
61
+ | **0.2.48** | `OpenWithPicker`, `PluginCard` | — | `OpenWithHandler`, `OpenWithPickerProps`, `OpenWithRequest` |
62
+ <!-- ui-since:end -->
63
+
64
+ **How to use it**: look up every export you **import statically** and take the largest `since` — that is your `minAppVersion` floor (below it, the whole plugin **fails to load** on that older shell, it is not "one component missing"). You do not have to compute it yourself: `npm run lint` tells you the number to put in (see [04-distribution-format §minAppVersion](04-distribution-format.md)).
65
+
52
66
  ### 2.2 Three promises the shell makes to authors (each backed by a mechanical gate)
53
67
 
54
68
  | Promise | What it means | Backstop |
@@ -102,10 +102,26 @@ my-plugin/
102
102
 
103
103
  ### minAppVersion / requires / permissions
104
104
 
105
- 三者 schema 均已声明(见 [03-contributes](03-插件contributes规范.md)),安装期不强制——语义与 [02 生命周期 §九](02-插件生命周期.md) 对齐:
105
+ 三者 schema 均已声明(见 [03-contributes](03-插件contributes规范.md)),安装期不强制——语义与 [02 生命周期 §九](02-插件生命周期.md) 对齐。
106
+
107
+ #### minAppVersion —— **你的插件要求的最低主软件版本**
108
+
109
+ 低于它 ⇒ **加载器直接拒载**(toast「需要应用版本 ≥X」+ `markLoadFailed`)。🔴 用户拿到的是**整只插件不可用**,不是「少个功能」——所以**写低比写高危险得多**。
110
+
111
+ **它怎么定:不是你测过的壳,是你实际用到的东西。**
112
+
113
+ - 共享组件由**壳**供给(运行时只有壳那一份,见 [19 §二](19-组件速查.md));「某个导出从哪个壳版本起才有」是**事实**——[19 §2.1 那张表](19-组件速查.md)就是它(由壳仓导出面账本生成,⛔ 不手写)。
114
+ - 你**静态导入**了某个导出 ⇒ 你至少要那个壳版本。把所有导入名的 `since` 取**最大值**,就是你的下限。
115
+ - **不用自己推**:`@linkdesk/plugin-sdk` 会替你算。`npm run lint` 报出该填多少;`npm run verify` 让你的 CI 变红;`build` / `publish` **产包前**也会拦(⛔ 声明不诚实的分发件不该被造出来)。⚠️ `lint` 是 **WARN 级、永不 fail**——它告诉你,但不拦你,别把「lint 跑过了」当成「声明对了」。
116
+
117
+ **三条容易踩的:**
118
+
119
+ - 🔴 **静态 `import` 没有「局部降级」**。顶层导入一个旧壳没有的导出 ⇒ **整只插件链接失败**(不是「那个功能不出现」)。想让老壳用户还能用上你的其余部分,就换成**动态 `import()`** 或**运行时 guard**——⚠️ **这是你的选择,不是要求**:什么时候加载是你的事,壳不替你做这个决定,门禁也不会因此判你红。
120
+ - 🔴 **默认 `dev` 测不出这类问题**。默认 `dev` = **mock 宿主 + 你 `node_modules` 里的 `@latest` ui**——组件全在、渲染正常,怎么点都是绿的。**要暴露必须 `dev --real` 对真壳,或把包装进真壳试**。
121
+ - 🔴 **`dev --real` 是单向的**:它回答「**在这个壳上跑得起来吗**」,**不回答**「**我最老能在哪个壳上跑**」。要拿下限,看上面那条门禁的输出。
122
+
123
+ #### requires / permissions
106
124
 
107
- - `minAppVersion` —— 加载期校验(不满足 → toast + 跳过)
108
- - **机械门禁(SDK lint)**:运行时消费 `@linkdesk/ui` ⇒ `plugin.json` 必须声明 `minAppVersion` ≥ `0.2.13`(重锚号——共享组件的集中供给自这一版才存在;`import type` 编译期擦除、豁免)。由 `linkdesk-plugin-sdk lint` 判红(`check-ui-min-app-version`),无豁免出口
109
125
  - `requires` —— 运行期依赖编排生效(缺依赖挂起 PENDING + 环 fail-loud + 连带卸载逆拓扑,见 [02 §四](02-插件生命周期.md))
110
126
  - **安装期自动装依赖(壳侧,随请求启用)**:安装请求携带来源市场目录时(市场插件随请求带条目来源 URL),`requires` 里缺失的依赖会在**同一个安装任务内**自动先装——内联递归、不占第二个并发槽;某个依赖失败 ⇒ 父任务失败并指名依赖,且父插件本次解压产物自动回滚、重试干净可用。已装的依赖跳过;禁用的**不自动启用**。作者只需声明 `requires`,无需为壳做任何适配
111
127
  - `permissions` —— 声明即用户知情,运行期授权模型尚未定案(声明不会带来额外能力)
@@ -244,7 +244,7 @@ my-plugin/
244
244
  | `suggests` | `array` | 可选相关插件 `[{ plugin: string, reason: string }]` |
245
245
  | `requires` | `string[]` | 插件级激活依赖——按 pluginId 声明,加载时先加载依赖再加载本插件。无版本约束。详见下方「`requires` 字段详解」 |
246
246
  | `screenshots` | `string[]` | 截图 URL 数组(Phase 5+ 启用) |
247
- | `minAppVersion` | `string` | 最低软件版本要求 |
247
+ | `minAppVersion` | `string` | 最低主软件版本要求——**低于它的旧壳拒载整只插件**;消费 `@linkdesk/ui` 时被门禁校验,详见下方「`minAppVersion` 字段详解」 |
248
248
  | `docs` | `string` | 附带文档路径(资源插件联动) |
249
249
  | `cardDocMap` | `object` | 卡片 ID → 文档锚点映射 |
250
250
  | `i18n` | `object` | 插件自带翻译 `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }`——key=插件 UI 原文(建议作者母语)。放在 `contributes.i18n` 下,非顶层。🔴 **本插件自己声明的可渲染文案,译名必须住本仓**(「谁的仓谁译文」——规则与判据见 `03 §3.9`) |
@@ -259,6 +259,21 @@ my-plugin/
259
259
 
260
260
  > **写进 `plugin.json` 不会生效,只会被忽略**(顶层是宽松校验,写了不报错——所以它骗人)。**若你从旧教程 / 旧提交抄到了这两个字段 → 删掉,改写成文件。**
261
261
 
262
+ ### `minAppVersion` 字段详解
263
+
264
+ **语义**:你的插件要求的**最低主软件版本**。低于它 ⇒ 加载器**拒载整只插件**(toast「需要应用版本 ≥X」+ `markLoadFailed`)——用户看到的是**插件不可用**,不是「少个功能」。⇒ **写低比写高危险得多**。
265
+
266
+ **它怎么定**:**不是你测过的壳,是你实际用到的东西**。共享组件由壳供给,「某个导出从哪个壳版本起才有」是事实([19 §2.1 的表](19-组件速查.md) 就是它,由壳仓账本生成);把你**静态导入**的导出名的 `since` 取最大值,就是你的下限。**不用自己算**——工具会算:
267
+
268
+ **这是被门禁校验的**(腿名 `check-ui-min-app-version`,随 `@linkdesk/plugin-sdk` 下发):
269
+
270
+ - `npm run lint` 报出该填多少(⚠️ WARN 级、**永不 fail**——它告诉你,但不拦你);`npm run verify` 让你的 CI 变红;`build` / `publish` **产包前**拦。
271
+ - 判据:声明 ≥ 地板(地板 = 基线 ∪ 你导入名的 `since` 的最大值);导入了账本里没有的名字 ⇒ 红(拼错 / 私有 API 都不是许诺的导出面)。
272
+ - ⛔ **无豁免出口**(disable 注释无效)——「知情地把旧壳用户放到没有那个导出的壳上」是语义错误,不是合法偏离。
273
+ - 不消费 `@linkdesk/ui` 的插件本条腿不管(`minAppVersion` 本身始终可选;只用了壳的新命令 / 新 IPC 时该填多少由你自己判断)。
274
+
275
+ 完整语义、三条易踩的坑(静态导入无局部降级 / 默认 `dev` 测不出 / `dev --real` 是单向的)、报错怎么读:[04-插件分发格式 §minAppVersion](04-插件分发格式.md)。
276
+
262
277
  ### `requires` 字段详解
263
278
 
264
279
  插件级激活顺序依赖——声明本插件激活前必须先激活哪些插件。
@@ -50,6 +50,20 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
50
50
  - **什么时候必须动**:只有当你**要用的新组件 / 新 prop** 出现在更高版本时——那是你主动升,不是被迫跟。
51
51
  - **想知道手里的包剪自哪个壳**:看包里 `dist/shell-provenance.json`(壳版号 + 短 hash + 日期)。
52
52
 
53
+ 🔴 **但有一个数要查表:`since`——「这个导出从哪个壳版本起才有」。** 「包版本自走」说的是**包**;而 `minAppVersion` 比的是**壳版本**,两个号不是一回事。下表由壳仓导出面账本生成(⛔ 手改会被 `npm run check` 打回):
54
+
55
+ <!-- ui-since:begin ⚠️ 本行与下面那行勿动——中间那几行由 `npm run ui-surface:regen` 生成 -->
56
+ | 起于 | 组件 | Hooks / 工具函数 | 类型 |
57
+ |:--|:--|:--|:--|
58
+ | **0.2.13** | `Badge`、`Button`、`ColorPicker`、`Combobox`、`ContextMenu`、`DynamicSelect`、`FileIconResolver`、`FilePathInput`、`FontFamilySelect`、`FormRow`、`HintCard`、`InlineInput`、`MarkdownView`、`NumberInput`、`OverlayPortal`、`PluginIcon`、`SegmentedRadio`、`SelectBox`、`Slider`、`StringListEditor`、`ThemePicker`、`Toggle` | `useClickPreview`、`useClipboardKeys`、`useDebouncedInput`、`DEFAULT_PLUGIN_IDENTITY_URI`、`inferSliderStep`、`pickIdentityArt`、`urlSourceKey` | `ContextMenuProps`、`IconDescriptor`、`InlineInputHandle`、`ManifestIconShape`、`ResolvedIcon` |
59
+ | **0.2.20** | `HintTip` | — | `HintTipProps` |
60
+ | **0.2.22** | `ReadOnlyText`、`SectionSubtitle` | — | — |
61
+ | **0.2.40** | `BackgroundImagePicker`、`EffectiveBadge`、`SegmentPreviewSwatch`、`SegmentPreviewText`、`SourceBadge` | `useStatusPolling`、`CONFIG_NONE_SENTINEL`、`MIX_FOLLOW_THEME_SENTINEL`、`SETTINGS_RENDER_HINTS`、`SETTINGS_UI_HINTS`、`formatEffectiveValue`、`isSettingsUiHint`、`splitStringList` | `BackgroundImagePickerProps`、`EffectiveBadgeProps`、`RunStatusCommand`、`SourceBadgeKind`、`SourceBadgeProps`、`SourceBadgeSource` |
62
+ | **0.2.48** | `OpenWithPicker`、`PluginCard` | — | `OpenWithHandler`、`OpenWithPickerProps`、`OpenWithRequest` |
63
+ <!-- ui-since:end -->
64
+
65
+ **怎么用**:把你**静态导入**的每个导出查一遍,取最大的那个 `since` ⇒ 就是你的 `minAppVersion` 下限(低了,旧壳上**整只插件加载失败**——不是「那个组件不显示」)。不用自己算:`npm run lint` 会直接告诉你该填多少(见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
66
+
53
67
  ### 2.2 壳对作者的三条承诺(都有机械兜底)
54
68
 
55
69
  | 承诺 | 意思 | 兜底 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.69",
3
+ "version": "0.1.70",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [