@linkdesk/plugin-docs 0.1.54 → 0.1.56

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.
@@ -91,7 +91,7 @@ async function list(): Promise<FileEntry[]> {
91
91
  | **appearance** | `revealStorage` opens the appearance storage directory (`userData/appearance`) — the main process resolves the path and uses `shell.openPath` to open the Explorer **contents** (not `showItemInFolder`'s single-file highlight); a missing directory is created as well (opening it shows the storage location, and an empty directory is legal), while an `openPath` failure throws and fails loud. Returns `Promise<void>` |
92
92
  | **app** | `app.getVersion` = the host software version (`Promise<string>`, read-only) — the only runtime source = Electron `app.getVersion` (a single point in `package.json`, 02 §2.3); **the entry point for comparing the main software version** (consumed by marketplace minAppVersion and the update check). The shell also has a private `getProductInfo` extension (the data source for the about page's 8 fields — not in the contract, so pool plugins can't call it) |
93
93
  | **tabs** | **Cross-window resource event wiring:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **whole-window broadcast semantics** — the resource holder's tab updates/closes in the main window and in every detached window; `sourceId` is the globally unique resource identity (file path/session id), and a change to it is a global fact (the wiring **does not require the caller to be in the same window as the tab** — a detached window's tab updates the moment the sidebar renames or deletes the resource, matching VS Code). `focusBySourceId(sourceId)` = **routed by originating window** (a view action that focuses one specific window, not a global fact). **No new APIs** — it reuses existing surfaces; this behavior contract is guaranteed by the whole-window broadcast |
94
- | **notifications** | **The default notification surface is the wide status bar bell panel** (the bottom-right **persistent** narrow toast path was deleted wholesale) — no cards popping up, no focus stealing, no blocking; the unread count increments and the user only sees it after clicking. **Don't treat it as a "must be seen" channel**: when the user has to decide right now → `dialog.confirm`. **`show` always returns a handle** (`{ update, finish, cancel }` — **and not only when `progress:true`**); **a notification can only be updated/removed by the handle that created it**, and a `show` with the same text elsewhere = a different notification. `progress:true` turns on a real progress bar: `update(msg, percent?)` gives a determinate 0-100 bar, while omitting percent = an indeterminate animation; `finish(msg?)` closes it and optionally adds a completion notification; `cancel` just closes it with nothing added. `persistent:true` = stays put and doesn't auto-dismiss (for error diagnostics), waiting for the user to click ×. **The persistent quota is bucketed by `source`, 5 each**; overflow evicts the oldest from that same source and shows a summary hint (persistent ≠ archived — write your own file if you want a record). `source` = **the machine-read attribution key, containing no human copy** (the shell resolves the human-readable name) — ⚠️ **it cannot be injected automatically**: the pool is a single-process shared realm and all plugins share one `window.linkdesk`, so the preload has no way to know which plugin's tree issued this `show` ⇒ **only the author can explicitly report their own plugin id** (the shell's own domains use `app.<domain>`); **omit it → everything lands in the "Other" group**. `actions` clicks go through the shell's `executeCommand(command, args)`, with the handler self-registered by the plugin. **`toast:true` (W3a)** = a **light hint** — the entry does not go to the panel but to an **auto-dismissing card** bottom-right (≈4s, paused while hovered) and **never counts as unread**; it is **a receipt for one action**, ⚠️ **not a record channel** (the user may well miss it) — use `persistent:true` or write your own file for anything worth re-reading |
94
+ | **notifications** | **The only notification surface is the wide status bar bell panel** (the narrow bottom-right toast path was deleted wholesale) — no cards popping up, no focus stealing, no blocking; the unread count increments and the user only sees it after clicking. **Don't treat it as a "must be seen" channel**: when the user has to decide right now → `dialog.confirm`. **`show` always returns a handle** (`{ update, finish, cancel }` — **and not only when `progress:true`**); **a notification can only be updated/removed by the handle that created it**, and a `show` with the same text elsewhere = a different notification. `progress:true` turns on a real progress bar: `update(msg, percent?)` gives a determinate 0-100 bar, while omitting percent = an indeterminate animation; `finish(msg?)` closes it and optionally adds a completion notification; `cancel` just closes it with nothing added. `persistent:true` = stays put and doesn't auto-dismiss (for error diagnostics), waiting for the user to click ×. **The persistent quota is bucketed by `source`, 5 each**; overflow evicts the oldest from that same source and shows a summary hint (persistent ≠ archived — write your own file if you want a record). `source` = **the machine-read attribution key, containing no human copy** (the shell resolves the human-readable name) — ⚠️ **it cannot be injected automatically**: the pool is a single-process shared realm and all plugins share one `window.linkdesk`, so the preload has no way to know which plugin's tree issued this `show` ⇒ **only the author can explicitly report their own plugin id** (the shell's own domains use `app.<domain>`); **omit it → everything lands in the "Other" group**. `actions` clicks go through the shell's `executeCommand(command, args)`, with the handler self-registered by the plugin |
95
95
  | **dialog** | `confirm`/`alert`/`open`/`openFile` = shell-rendered modal dialogs (they take focus, with a focus lock). **`confirmContent(options)`** = **rich-content confirmation** — the dialog is still the shell (centered/scrim/Esc/focus lock/click-scrim-to-cancel) while **the content = a plugin-drawn view** (`pluginId` + `viewId` declarative addressing + an opaque `payload`, matching VS Code's "the dialog is the shell, the content is the plugin's"). **How the content side reads it**: once the view mounts, get data through `dialogHost.current?.content?.payload` (`open !== true` → `null`, defensive so you don't get a blank screen); **there are only two settlement paths, `dialogHost.confirm` / `dialogHost.cancel`** (don't close the dialog yourself — the shell won't recognize it). **The fallback is hard**: if `viewId` can't be resolved (undeclared / declaring plugin not installed) → the shell **falls back to a plain text confirmation** (using `title`/`message`); the dialog still appears and never dies silently ⇒ so don't omit `title`/`message`. `payload` crosses IPC by structured clone ⇒ only cloneable data can go in it |
96
96
  | **search** | Full-text search/replace — `searchFiles(opts)` is a single call-and-response executed by the shell/main process over IPC (zero local scanning on the plugin side); the request/result shapes follow the contract's `SearchWireOptions`/`SearchWireResult` |
97
97
  | **encoding** | The encoding detect/convert trio (handled by the main process EncodingService): `detect(buffer)` guesses the encoding name / `decode(buffer, encoding)` bytes→text / `encode(text, encoding)` text→bytes — `Uint8Array` in and out |
@@ -322,8 +322,7 @@ const file = await window.linkdesk.dialog.openFile({
322
322
  > ⚠️ **Notifications are not "auto-vanishing floating cards"** (notification-surface unification and correction): the bottom-right narrow toast pipeline has been deleted entirely, and **the only notification surface = the status bar bell wide panel**. Three things authors need to know:
323
323
  > 1. **Notifications don't pop a card, don't steal focus, and don't block interaction**—they go into the bell (unread count +1), and the user only sees them after opening it. Don't treat notifications as a "must be seen" channel: if the user has to decide on the spot → use `dialog.confirm` (modal, steals focus).
324
324
  > 2. **Persistent notifications per source are quota-limited**—grouped by `options.source`, at most 5 persistent per group; beyond that, the oldest one from the same source is pushed out. A flood won't pile into a wall, but **don't count on notifications for long-term records either**.
325
- > 3. **Keyboard reachability means "the panel is reachable", not "notifications are reachable"**—the bell can be focused and opened with the keyboard, everything inside the panel can be reached with Tab, and `Esc` closes it; but the panel **has no focus trap** (non-modal, focus can leave freely). **Don't write assumptions like "Tab gets you to my notification button"**—the user may never open the panel at all.
326
- > 4. **The one exception is an explicit `toast: true`** (new in W3a): an entry from `show(msg, { toast: true })` **never enters the panel and never counts as unread**; instead a **card auto-appears bottom-right and auto-dismisses** (≈4s; hovering pauses the countdown). It is **a receipt for a single action**—the user may well miss it, so **never route anything worth re-reading through it** (use `persistent: true`, or write your own file). ⚠️ Point 1 above still describes the default: omit `toast` and it is panel-only.
325
+ > 3. **Keyboard reachability means "the panel is reachable", not "notifications are reachable"**—the bell can be focused and opened with the keyboard, everything inside the panel can be reached with Tab, and `Esc` closes it; but the panel **has no focus trap** (non-modal, focus can leave freely). **Don't write assumptions like "Tab gets you to my notification button"**—the user may never open the panel at all; and **don't count on a second surface**: the bell panel is the only notification face (user directive restated 2026-10-01 — the bottom-right "auto-vanishing card" was built twice and deleted twice).
327
326
 
328
327
  **Notification action buttons (`actions` on `notifications.show`):** failure / user-action-required notifications can carry an `actions` button array—clicking runs through the **command system** (modeled after VS Code's `showErrorMessage(msg, { title, command })` actions). Command handlers are registered by the plugin itself (`commands.registerCommand`):
329
328
 
@@ -566,9 +565,8 @@ both stylesheets land on the same element.
566
565
  | `ldk-rn-spin` | the release-notes page's refresh icon spin |
567
566
  | `ldk-boot-mark-breath` | the boot brand screen's breathing |
568
567
  | `ldk-view-skeleton-breath` | the content loading skeleton's breathing |
569
- | `ldk-toast-in` | the light-hint card's entrance animation |
570
- | `ldk-toast-out` | the light-hint card's exit animation |
571
568
  | `ldk-welcome-skeleton-breath` | the welcome recent list loading skeleton's breathing |
569
+ | `ldk-welcome-in` | the welcome page's entrance fade-up (its single authored moment) |
572
570
 
573
571
  **The name you reference has to exist somewhere**—rule 2 above says "when you rename, change the reference in
574
572
  the same commit"; this is the other half, and **the machine checks it**: the name you write in
@@ -91,7 +91,7 @@ async function list(): Promise<FileEntry[]> {
91
91
  | **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
92
92
  | **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion 与更新检查都消费它)。壳内另有 `getProductInfo` 私有扩展(关于页 8 字段数据源,不在契约——池插件不可调) |
93
93
  | **tabs** | **跨窗资源事件联动:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **全窗广播语义**——资源持有者在主窗与全部脱出窗的标签页同步更新/关闭;`sourceId` 为全局唯一资源身份(文件路径/会话 id),变更即全局事实(联动**不依赖调用方与标签页同窗**——脱出窗标签随侧栏改名/删除即时联动,对标 VS Code)。`focusBySourceId(sourceId)` = **按来源窗路由**(视图动作,聚焦到具体某窗,非全局事实)。**无新 API**——复用既有面,此行为契约由全窗广播保证 |
94
- | **notifications** | **默认通知面 = 状态栏铃铛宽面板**(右下**常驻**窄 toast 链路已整删)——不弹卡、不抢焦点、不挡操作;未读计数 +1,用户点开才看见。**别把它当「必须被看见」的通道**:要用户当场决定 → `dialog.confirm`。**`show` 一律返回句柄**(`{ update, finish, cancel }`,——**不是只有 `progress:true` 才有**);**一条通知只能被创建它的那个句柄更新/删除**,别处同文案 `show` = 另一条。`progress:true` 开真进度条:`update(msg, percent?)` 给 0-100 确定条、不传 percent = 不定态动画;`finish(msg?)` 关掉并可选补完成通知;`cancel` 直接关掉不补。`persistent:true` = 长驻不自动消失(错误诊断类),等用户点 ×。**常驻配额按 `source` 分桶各 5 条**,超出顶掉同来源最老的并给汇总提示(长驻 ≠ 留档,要留档写自己的文件)。`source` = **机器读的归属键、不含人类文案**(人类可读名壳解析)——⚠️ **做不到自动注入**:池是单进程共享 realm,所有插件共用一个 `window.linkdesk`,preload 无从知道这次 `show` 是哪个插件的树发的 ⇒ **只能作者显式报自己的插件 id**(壳自身域用 `app.<域>`);**不传 → 全落「其他」组**。`actions` 点击走壳 `executeCommand(command, args)`,handler 插件自注册。**`toast:true`(W3a)** = **轻提示**——进去的不是面板而是右下角一张**自动消失的小卡**(≈4s、悬停暂停)、**不计未读**;它是**「一次操作的回执」**,⚠️ **不是留档通道**(用户可能根本来不及看)——要回看用 `persistent:true` 或写自己的文件 |
94
+ | **notifications** | **唯一通知面 = 状态栏铃铛宽面板**(右下窄 toast 链路已整删)——不弹卡、不抢焦点、不挡操作;未读计数 +1,用户点开才看见。**别把它当「必须被看见」的通道**:要用户当场决定 → `dialog.confirm`。**`show` 一律返回句柄**(`{ update, finish, cancel }`,——**不是只有 `progress:true` 才有**);**一条通知只能被创建它的那个句柄更新/删除**,别处同文案 `show` = 另一条。`progress:true` 开真进度条:`update(msg, percent?)` 给 0-100 确定条、不传 percent = 不定态动画;`finish(msg?)` 关掉并可选补完成通知;`cancel` 直接关掉不补。`persistent:true` = 长驻不自动消失(错误诊断类),等用户点 ×。**常驻配额按 `source` 分桶各 5 条**,超出顶掉同来源最老的并给汇总提示(长驻 ≠ 留档,要留档写自己的文件)。`source` = **机器读的归属键、不含人类文案**(人类可读名壳解析)——⚠️ **做不到自动注入**:池是单进程共享 realm,所有插件共用一个 `window.linkdesk`,preload 无从知道这次 `show` 是哪个插件的树发的 ⇒ **只能作者显式报自己的插件 id**(壳自身域用 `app.<域>`);**不传 → 全落「其他」组**。`actions` 点击走壳 `executeCommand(command, args)`,handler 插件自注册 |
95
95
  | **dialog** | `confirm`/`alert`/`open`/`openFile` = 壳渲染的模态框(抢焦点、有焦点锁)。**`confirmContent(options)`** = **富内容确认**——对话框仍是壳(居中/遮罩/Esc/焦点锁/点遮罩取消),**内容 = 插件自绘视图**(`pluginId` + `viewId` 声明寻址 + 不透明 `payload`,对标 VS Code「对话框是壳、内容插件定」)。**内容侧读法**:视图挂载后经 `dialogHost.current?.content?.payload` 取数(`open !== true` → `null`,防御不白屏);**结算只有 `dialogHost.confirm` / `dialogHost.cancel` 两条路**(别自己关弹窗,壳不认)。**兜底是硬的**:`viewId` 解析不出(未声明/声明插件没装)→ 壳**回落纯文字确认框**(用 `title`/`message`),弹窗照出、不静默死 ⇒ `title`/`message` 别省。`payload` 过 IPC 结构化克隆 ⇒ 只能放可克隆数据 |
96
96
  | **search** | 全文搜索/替换——`searchFiles(opts)` 一发一收,经 IPC 由壳/主进程执行(插件侧零本地扫描);请求/结果形状以契约 `SearchWireOptions`/`SearchWireResult` 为准 |
97
97
  | **encoding** | 编码检测/转换三件套(主进程 EncodingService 代办):`detect(buffer)` 猜编码名 / `decode(buffer, encoding)` 字节→文本 / `encode(text, encoding)` 文本→字节——`Uint8Array` 进出 |
@@ -321,11 +321,10 @@ const file = await window.linkdesk.dialog.openFile({
321
321
 
322
322
  **理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效。完整签名见 `contracts/linkdesk.d.ts`。
323
323
 
324
- > ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的四件事:
324
+ > ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
325
325
  > 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
326
326
  > 2. **同来源常驻有配额**——按 `options.source` 分组,每组常驻最多 5 条,超出顶掉同来源最老的。刷屏不会堆成墙,但**也别指望靠通知留长期记录**。
327
- > 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板。
328
- > 4. **唯一的例外是显式 `toast: true`**(W3a 新增):`show(msg, { toast: true })` 的条目**不进面板、不计未读**,改在右下角弹一张**自动消失的小卡**(≈4s;鼠标停上去暂停计时)。它是**「一次操作的回执」**——用户可能根本来不及看,故**任何要回看的内容都别走它**(那用 `persistent: true`,或写自己的文件)。⚠️ 上面第 1 条「不弹卡」说的仍是缺省行为:不传 `toast` 就是纯面板。
327
+ > 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板;**也别指望有第二呈现面**——通知只有铃铛这一个面(2026-10-01 用户指令重申:右下角「自动消失小卡」这类第二面长过两次、两次都被删)。
329
328
 
330
329
  **通知主动作按钮(`notifications.show` 的 `actions`):** 失败 / 需要用户行动的通知可带 `actions` 按钮数组——点击走**命令系统**执行(对标 VS Code `showErrorMessage(msg, { title, command })` 动作)。命令 handler 由插件自注册(`commands.registerCommand`):
331
330
 
@@ -565,9 +564,8 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
565
564
  | `ldk-rn-spin` | 发行说明页刷新图标的旋转 |
566
565
  | `ldk-boot-mark-breath` | 池首帧品牌过场的呼吸 |
567
566
  | `ldk-view-skeleton-breath` | 内容加载骨架的呼吸 |
568
- | `ldk-toast-in` | 轻提示卡的入场动画 |
569
- | `ldk-toast-out` | 轻提示卡的退场动画 |
570
567
  | `ldk-welcome-skeleton-breath` | 欢迎页最近列表加载骨架的呼吸 |
568
+ | `ldk-welcome-in` | 欢迎页入场 fade-up(全页唯一一处入场) |
571
569
 
572
570
  **引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
573
571
  你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
@@ -380,6 +380,9 @@
380
380
  "minimum": { "type": "number", "description": "Numeric lower bound — applies when type is number (range of the slider/numeric control)" },
381
381
  "maximum": { "type": "number", "description": "Numeric upper bound — applies when type is number (range of the slider/numeric control)" },
382
382
  "step": { "type": "number", "description": "Slider step — meaningful only with uiHint \"slider\". Defaults are derived by SettingsView from the range (0.01 for floating-point ranges)." },
383
+ "unit": { "type": "string", "description": "Value label unit for uiHint \"slider\" — shown with the current value (e.g. \"px\", \"ms\", \"×\" for multipliers). Declaring unit turns the value label on; omitting it keeps a bare slider. An empty string means a label showing the bare value with no unit." },
384
+ "unitPosition": { "type": "string", "description": "Value label position for uiHint \"slider\" — \"before\" | \"after\" (default) place the label outside the stepper buttons on the same row; \"above\" | \"below\" center it over/under the track (intended for custom plugin layouts — keep the default for configuration rows, which have a fixed row height)." },
385
+ "stepper": { "type": "boolean", "description": "Fine-tune stepper for uiHint \"slider\" — renders persistent −/+ buttons on both sides of the track (one step per click, clamped to min/max, disabled at the bounds and when the slider is disabled). Omit for a bare slider." },
383
386
  "group": { "type": "string", "description": "Second-level heading within a group — keys sharing a group are rendered under a subheading on the settings page; without a group they stay flat (zero intrusion for third parties)" }
384
387
  },
385
388
  "additionalProperties": false
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.54",
3
+ "version": "0.1.56",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [