@linkdesk/plugin-docs 0.1.0

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.
Files changed (49) hide show
  1. package/README.md +58 -0
  2. package/docs/00-readme.md +189 -0
  3. package/docs/01-plugin-api-contract.md +171 -0
  4. package/docs/02-plugin-lifecycle.md +348 -0
  5. package/docs/03-contributes-spec.md +800 -0
  6. package/docs/04-distribution-format.md +172 -0
  7. package/docs/05-ui-conventions.md +549 -0
  8. package/docs/06-plugin-json-spec.md +640 -0
  9. package/docs/07-plugin-to-plugin-communication.md +299 -0
  10. package/docs/08-view-container-api.md +405 -0
  11. package/docs/09-plugin-directory-layout.md +301 -0
  12. package/docs/10-building-a-settings-plugin.md +164 -0
  13. package/docs/11-authoring-themes.md +173 -0
  14. package/docs/12-readme-media-contract.md +74 -0
  15. package/docs/13-development-guide.md +259 -0
  16. package/docs/14-data-pipeline-command-conventions.md +173 -0
  17. package/docs/15-multi-repo-and-local-workspace.md +86 -0
  18. package/docs/16-naming-conventions.md +77 -0
  19. package/docs/17-region-map.md +225 -0
  20. package/docs/18-cross-region-wiring.md +192 -0
  21. package/docs/19-component-cheatsheet.md +108 -0
  22. package/docs/20-adding-a-setting.md +159 -0
  23. package/docs/themes/01-build-a-theme-plugin.md +150 -0
  24. package/docs/themes/02-theme-field-index.md +145 -0
  25. package/docs/zh/00-README.md +189 -0
  26. package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
  27. package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
  28. package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
  29. package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
  30. package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
  31. package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
  32. package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
  33. package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
  34. package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
  35. package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
  36. package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
  37. package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
  38. package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
  39. package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
  40. package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
  41. package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
  42. package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
  43. package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
  44. package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
  45. package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
  46. package/docs/zh/plugin.schema.json +687 -0
  47. package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
  48. package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
  49. package/package.json +20 -0
package/README.md ADDED
@@ -0,0 +1,58 @@
1
+ # @linkdesk/plugin-docs
2
+
3
+ > **LinkDesk plugin-authoring documentation** — learn to build a plugin from zero. **Offline package**: install it and read locally, no need to browse the repository.
4
+
5
+ Written for **plugin authors and their AI assistants**. Start with `docs/00-readme.md` — it is a guided entry point that routes by "what do I want to build" and by "which tier am I in" (10 minutes / 30 minutes / 1 day).
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm i @linkdesk/plugin-docs
11
+ # then read node_modules/@linkdesk/plugin-docs/docs/00-readme.md
12
+ ```
13
+
14
+ > It is not a build dependency — **do not add it to your plugin's `package.json`**. Install it when you want to read.
15
+
16
+ ## What's inside
17
+
18
+ | What you want to do | Read |
19
+ |:--|:--|
20
+ | Pick your tier (10 min / 30 min / 1 day) | `docs/13-development-guide.md` |
21
+ | Know where your plugin lives (Icon Bar / Sidebar / Main Area / Bottom Panel / Status Bar) | `docs/17-region-map.md` |
22
+ | Wire regions together (select → switch view → update the status bar) | `docs/18-cross-region-wiring.md` |
23
+ | Use the UI parts the shell already provides | `docs/19-component-cheatsheet.md` |
24
+ | Add a setting to your plugin | `docs/20-adding-a-setting.md` |
25
+ | Build a theme (no code) | `docs/themes/01-build-a-theme-plugin.md` · `docs/themes/02-theme-field-index.md` |
26
+ | Look up the API (what can I call) | `docs/01-plugin-api-contract.md` |
27
+ | Look up a field | `docs/06-plugin-json-spec.md` · `docs/plugin.schema.json` |
28
+
29
+ Full index → the documentation index in `docs/00-readme.md`.
30
+
31
+ **Chinese version** (the maintainer-facing original, mirrored one-for-one): `docs/zh/00-README.md`.
32
+
33
+ ## 🔴 Where the source of truth is (edit the docs there, not here)
34
+
35
+ ```
36
+ source <repo> docs/03-plugin-authoring/** (English — the author-facing primary)
37
+ <repo> docs/03-插件制造/** (Chinese — the maintainer-facing original)
38
+ ↓ npm run docs:build (scripts/generate-plugin-docs.mjs)
39
+ output this package's docs/** (English at the root, Chinese under zh/) ← generated, do not hand-edit
40
+ ↓ npm run docs:check (wired into npm run check)
41
+ rule byte-for-byte comparison against the source (except the link rewrites below)
42
+ ```
43
+
44
+ - **Links**: targets that point **outside** the doc trees (the API contract, the toolchain docs, the theme variable contract…) are **absolutized to GitHub URLs** at generation time, so they work from inside an npm package too. In-tree links stay relative.
45
+ - So **if you find a documentation problem**: fix it in the repository under `docs/`, not in this package. If the source changes and the package is not regenerated, `npm run check` fails.
46
+
47
+ ## Versions and publishing
48
+
49
+ This package is the **fifth author axis** (the others: `@linkdesk/contracts` / `@linkdesk/plugin-sdk` / `create-linkdesk-plugin` / `@linkdesk/ui`) — **any content change means a PATCH**, and it is independent of the application version.
50
+
51
+ ```bash
52
+ npm publish --registry=https://registry.npmjs.org # pass the registry explicitly (inside a workspace this package's .npmrc is ignored)
53
+ npm run release:mark # record the baseline (verified against the shelf)
54
+ ```
55
+
56
+ ## License
57
+
58
+ MIT
@@ -0,0 +1,189 @@
1
+ # Plugin Development — Start Here
2
+
3
+ > 🌐 **Chinese version(维护者面原文)→ [../03-插件制造/00-README.md](https://github.com/Encaron/linkdesk/blob/electron/docs/03-插件制造/00-README.md)** — this English tree is the **author-facing primary**; the two trees mirror each other one-for-one (the `check-author-docs-bilingual` gate enforces it).
4
+
5
+ > **This directory exists for one purpose: to get plugin authors (and their AIs) from zero to a working plugin, fast.**
6
+ > The LinkDesk core is an empty shell; everything is a plugin. **This page is the tour** — pick your entry point by "what I want to do" or "which tier I'm in"; there's no need to read top to bottom.
7
+
8
+ | | |
9
+ |---|---|
10
+ | Audience | Plugin developers (not core developers) |
11
+ | How to use | Pick an entry point on this page → follow a walkthrough in [13-development-guide](13-development-guide.md) → jump via links when you need details |
12
+ | Also | The [documentation index](#documentation-index) at the bottom of this page lists every doc in this directory — look there when you can't find something |
13
+
14
+ ---
15
+
16
+ ## 1. Where to Start
17
+
18
+ ### Pick by "What I want to do"
19
+
20
+ | What I want to do | Read first | Then |
21
+ |:--|:--|:--|
22
+ | **Build a minimal plugin** (10-minute tier) | "Three tiers" in [13-development-guide](13-development-guide.md) | Just get it running — `npm create` → `npm run dev` |
23
+ | **Build a view plugin** (30-minute tier: get into a region, declare contribution points, use shared components) | [17-region-map](17-region-map.md) | → [the 30-minute tier in 13](13-development-guide.md) → [19-component-cheatsheet](19-component-cheatsheet.md) |
24
+ | **Build an advanced plugin** (1-day tier: data pipeline / cross-plugin / Canvas / LSP) | [the 1-day tier in 13](13-development-guide.md) | → [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) · [14-data-pipeline-command-conventions](14-data-pipeline-command-conventions.md) |
25
+ | **Build a theme** (no code) | [themes/01-build-a-theme-plugin](themes/01-build-a-theme-plugin.md) | → [themes/02-theme-field-index](themes/02-theme-field-index.md) |
26
+ | **Add a setting to my plugin** | [20-adding-a-setting](20-adding-a-setting.md) | → [03-contributes-spec](03-contributes-spec.md) |
27
+ | **Make several regions work together** (sidebar selection → main area switch → status bar update) | [18-cross-region-wiring](18-cross-region-wiring.md) | → [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) |
28
+ | **Look up the API** (what can I call) | [01-plugin-api-contract §3](01-plugin-api-contract.md) (the entry table for the three API surfaces) | → the SDK package README cheatsheet / `linkdesk.d.ts` |
29
+ | **Use the UI parts the shell provides** | [19-component-cheatsheet](19-component-cheatsheet.md) | → [05-ui-conventions](05-ui-conventions.md) |
30
+ | **Look up a specific field** | [06-plugin-json-spec](06-plugin-json-spec.md) | → `plugin.schema.json` (IDE completion) |
31
+ | **Package / share / list** | [04-distribution-format](04-distribution-format.md) | → [steps 8–9 in 13](13-development-guide.md) |
32
+ | **Where to put the project, how to name the repo** | [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) | → [16-naming-conventions](16-naming-conventions.md) |
33
+
34
+ ### Pick by "Which tier I'm in"
35
+
36
+ **The testable version of that claim:** a stranger (or their AI) **asks nobody**, working only from the scaffold output:
37
+
38
+ | Tier | Goal | Walkthrough entry |
39
+ |:--:|:--|:--|
40
+ | ⏱ **10 minutes** | Get a **minimal runnable plugin** | [13-development-guide](13-development-guide.md) steps 1–3 |
41
+ | ⏱ **30 minutes** | Get a **view plugin** (gets into a region, declares contribution points, uses shared components) | + steps 4–6 + [17-region-map](17-region-map.md) |
42
+ | ⏱ **1 day** | Get an **advanced plugin** (data pipeline / cross-plugin / Canvas / LSP class) | + steps 7–9 + [07](07-plugin-to-plugin-communication.md) · [14](14-data-pipeline-command-conventions.md) · [18](18-cross-region-wiring.md) |
43
+
44
+ > 🔴 **An honest note from the writers**: these three tiers are this directory's **acceptance criteria**, not marketing copy. **If any tier doesn't work end to end, the step you got stuck on is the missing-docs list** — please report it back to us.
45
+
46
+ ---
47
+
48
+ ## 2. What Plugins Can Do
49
+
50
+ **There is no API allowlist.** Plugins run in the renderer process (all plugins share one renderer process and talk to each other through the shell), and can `import` any JS library and call any Web API — Canvas, WebGL, WebAssembly, WebRTC, Web Audio… the whole Web platform, no restrictions.
51
+
52
+ System-level capabilities (serial ports, filesystem, configuration, dialogs) are exposed through `window.linkdesk.*` — plugins go through the shell; they cannot call raw Node.js capabilities directly, nor `import` shell-internal source code.
53
+
54
+ | What you want to build | How | Example |
55
+ |------|------|------|
56
+ | GPS map | `import` Leaflet / AMap SDK → React component | AMap plugin |
57
+ | Serial data parsing | `window.linkdesk.protocol.*` (main-process protocol registry) + `window.linkdesk.serial.onData` data pipeline | SBQ protocol plugin |
58
+ | Card visualization | The card workbench is a plugin — `contributes.views` registers views into the card container | Thermometer/waveform cards |
59
+ | Code editor | `import monaco-editor` → React component | Monaco editor plugin |
60
+ | CAD viewer | `import` Three.js → Canvas/WebGL | CAD plugin |
61
+ | Document reader | `import markdown-it` / `<iframe>` | Markdown/HTML reader |
62
+ | Logic analyzer | Canvas 2D + `window.linkdesk.serial` | Timing waveform analyzer |
63
+ | 3D model viewing | `import` Three.js / Babylon.js | STL/STEP viewer |
64
+ | Code intelligence / completion | Speak the LSP protocol or an AI API | clangd / Copilot plugin |
65
+ | Icons/buttons | codicon icon set + CSS variables | Any plugin |
66
+
67
+ ---
68
+
69
+ ## 3. Plugin Contribution Types (what you declare = where it shows up)
70
+
71
+ > The `type` field in `plugin.json` is **deprecated** — the loader auto-detects contribution types from declaration fields such as `entry` / `mode` / `themes` / `languages` / `resources` / `contributes`. **A single plugin can contribute several capabilities at once** (terminal = view + protocol; CAD = view + theme).
72
+
73
+ | Capability | How to declare it | Where it shows up | Example |
74
+ |------|------|------|------|
75
+ | **View** (tab) | `entry` + `appearsIn.tabBar` | Main Area tabs | Terminal/map/CAD/editor |
76
+ | **Sidebar / Bottom Panel** | `contributes.viewsContainers` + `contributes.views` | Sidebar / Bottom Panel | File tree/output/todo |
77
+ | **Status bar item** | top-level `statusBar[]` | Status Bar | Connection status/traffic counter |
78
+ | **Title bar button** | `contributes.titleBar` | Title Bar | One-click run |
79
+ | **Commands / menus / keybindings** | `contributes.commands` / `menus` / `keybindings` | Command palette / context menu / keybindings | — |
80
+ | **Setting** | `contributes.configuration` | The settings page auto-renders a group | → [20](20-adding-a-setting.md) |
81
+ | **Settings UI** (a whole replacement) | `factoryRole: "settings"` + `contributes.views` | Several coexist; the user switches | → [10-building-a-settings-plugin](10-building-a-settings-plugin.md) |
82
+ | **Theme** | `contributes.themes` | Theme picker | → [themes/01](themes/01-build-a-theme-plugin.md) |
83
+ | **Language pack** (UI translation) | `contributes.languages` | Language list | 日本語 / English |
84
+ | **Protocol parsing** | the `mode` field + `window.linkdesk.protocol.*` | Main-process protocol registry | SBQ heart-rate protocol |
85
+ | **Static resources** | the plugin's `resources/` directory declares relative paths | Shipped with the plugin | STM32 reference manual HTML |
86
+
87
+ **What each region is, how they relate to each other, and which snippets to copy** → [17-region-map](17-region-map.md).
88
+
89
+ ---
90
+
91
+ ## 4. The Author Toolchain: Four Packages
92
+
93
+ > Third-party authors write plugins in **their own project root** and never touch the shell repo — from zero to `.linkdesk-plugin` is all npm.
94
+
95
+ | Package | What it does | When authors install it |
96
+ |:--|:--|:--|
97
+ | `create-linkdesk-plugin` | Generates a plugin project skeleton in one line (the yo code equivalent) — **and it creates the git repo for you** | `npm create` when starting a new plugin; one-off, not part of the project |
98
+ | `@linkdesk/plugin-sdk` | The four author-toolchain commands: `dev` (dev host + HMR) / `build` (→ `.linkdesk-plugin`) / `validate` / `lint`; ships `plugin.schema.json` + `theme.schema.json` + the dev host page | devDependencies of every plugin project |
99
+ | `@linkdesk/contracts` | Full TS types for `window.linkdesk.*` (generated contract artifacts — the single source of truth) | **No need to install it yourself** — the SDK depends on it and forwards everything |
100
+ | `@linkdesk/ui` | Shared UI parts (buttons/selects/toggles/color picker/context menu…) | **Optional** — install it when you want your UI to look built-in (automatic theme/glass following) → [19-component-cheatsheet](19-component-cheatsheet.md) |
101
+
102
+ **In one sentence:** `create` generates the project → the project installs `sdk` → `sdk` brings `contracts` (types come along) → `ui` is standalone, installed on demand.
103
+ > Version numbers are not pinned on this page — **just install without a version to get the latest**.
104
+
105
+ **The commands authors actually type:**
106
+
107
+ ```bash
108
+ npm create linkdesk-plugin my-plugin # ① Create the project (once per plugin; auto git init + initial commit)
109
+ cd my-plugin && npm install # ② Install the SDK (types flow into the TS program automatically)
110
+ npm run dev # Preview: browser dev host → HMR on save
111
+ npm run dev:real # Real-machine loop: sub-second debugging inside an installed LinkDesk (for real-IPC plugins)
112
+ npm run validate # Validate plugin.json / theme recipe
113
+ npm run build # Hand off: my-plugin.linkdesk-plugin (install into LinkDesk / publish)
114
+ npm run publish # Publish to your own GitHub repo (step one of listing)
115
+ ```
116
+
117
+ ---
118
+
119
+ ## 5. Zero to Shipped — The Shortest Path
120
+
121
+ ```
122
+ 1. npm create linkdesk-plugin my-plugin → generate the project (pluginId / name / author already filled in, git repo created)
123
+ 2. Write plugin.json + src/index.tsx → declare your plugin, write the first piece of UI
124
+ 3. npm run dev → see it in the browser preview host
125
+ 4. npm run build → produces my-plugin.linkdesk-plugin (a single-file zip)
126
+ 5. Install / publish → to share: one file does it; to list: see below (two steps)
127
+ ```
128
+
129
+ **Listing is two steps — don't stop after the first:**
130
+
131
+ | Step | What you do | Who can see it afterwards |
132
+ |:--:|------|------|
133
+ | ① | `npm run publish` — publish to **your own** GitHub repo (Release asset + `marketplace.json` at the repo root) | Only people who manually add your repo as a "marketplace source" |
134
+ | ② | **Get your plugin into the official catalog** | **All users with default configuration** ← this step is what "listing" really means |
135
+
136
+ Full story → [04-distribution-format §Listing Is Two Steps](04-distribution-format.md) · end-to-end journey → [13-development-guide](13-development-guide.md) step 9.
137
+
138
+ ---
139
+
140
+ ## Hard Constraints — Before You Write Any Plugin Code
141
+
142
+ 1. **All colors go through CSS variables `var(--xxx)`**; hardcoded hex is forbidden
143
+ 2. **All UI text goes through `t()`**; hardcoding display strings to bypass `t()` is forbidden (i18n key = the plugin UI's source text — authors are advised to use their native language: Chinese plugins use Chinese keys, English/French plugins use keys in their own language)
144
+ 3. **Context menus are declarative** — declare them in `plugin.json` `contributes.menus` + consume them with `<ContextMenu>` (or `window.linkdesk.menu.registerItems`); hand-written context menus are forbidden
145
+ 4. **Popups render to `document.body` with `createPortal`**
146
+ 5. **Persistence goes through `window.linkdesk.configuration.get/set/onChange`**; `localStorage.setItem()` is forbidden
147
+ 6. **Plugins may only use the `window.linkdesk.*` API; `import @src/core/...` is forbidden** (ESLint `noCoreImportInPlugin` blocks it at `error` level — both `.tsx` and `.ts`)
148
+ 7. **Don't hide content with conditional rendering** — under the keep-alive architecture all tabs stay mounted
149
+ 8. **The shell doesn't know what your plugin does** — don't depend on any special-casing in the shell
150
+
151
+ ---
152
+
153
+ ## Documentation Index
154
+
155
+ | # | Doc | When to read it |
156
+ |:--:|------|------|
157
+ | ★ | [13-development-guide](13-development-guide.md) | **Start here the first time you write a plugin** — the nine-step walkthrough from `npm create` to listing + the three tiers |
158
+ | 1 | [01-plugin-api-contract](01-plugin-api-contract.md) | Before the first line of code — know which APIs you can call (**the master entry to the three API surfaces**) |
159
+ | 2 | [02-plugin-lifecycle](02-plugin-lifecycle.md) | Understand the whole register→activate→run→uninstall process |
160
+ | 3 | [03-contributes-spec](03-contributes-spec.md) | Register commands/menus/keybindings/settings/views/themes/i18n/title bar buttons |
161
+ | 4 | [04-distribution-format](04-distribution-format.md) | Install and distribute — let others install your plugin (including the **two-step listing** story) |
162
+ | 5 | [05-ui-conventions](05-ui-conventions.md) | Context menus/overlays/persistence/two keybinding tracks/three clipboard channels — must go through the shared facilities |
163
+ | 6 | [06-plugin-json-spec](06-plugin-json-spec.md) | The complete plugin.json field reference — **note: there is no `readme` / `changelog` field here**; the description and changelog are files |
164
+ | 7 | [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) | How plugins pass data to each other — **three communication mechanisms**: event broadcast / command invocation / data pipeline |
165
+ | 8 | [08-view-container-api](08-view-container-api.md) | Every ViewContainer field: registering sidebar/panel views, adding content to someone else's container, titleActions |
166
+ | 9 | [09-plugin-directory-layout](09-plugin-directory-layout.md) | Plugin directory structure — where files go, naming conventions + **the authoritative criteria for `README.md` / `CHANGELOG.md`** |
167
+ | 10 | [10-building-a-settings-plugin](10-building-a-settings-plugin.md) | **A whole replacement for the settings UI** (≠ adding one setting to your own plugin, which is doc 20) |
168
+ | 11 | [11-authoring-themes](11-authoring-themes.md) | Deep reference on recipe authoring (directory conventions / full example / migration and pitfalls) |
169
+ | 12 | [12-readme-media-contract](12-readme-media-contract.md) | How to write images/GIFs/linked cover videos/in-page videos in a README |
170
+ | 13 | [13-development-guide](13-development-guide.md) | **The walkthrough** (same as the first row) |
171
+ | 14 | [14-data-pipeline-command-conventions](14-data-pipeline-command-conventions.md) | Naming and registration conventions for data pipeline commands |
172
+ | 15 | [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) | Where plugin projects live, how to name repos, **the iron rule that a container never hosts a repo** |
173
+ | 16 | [16-naming-conventions](16-naming-conventions.md) | **Seven names, one identity** — how ids are chosen/whether they can change, what the repo is called, version numbers sourced in four places |
174
+ | **17** | **[17-region-map](17-region-map.md)** | **Which region my plugin shows up in** — how to declare each of icon bar/sidebar/main area/Bottom Panel/status bar |
175
+ | **18** | **[18-cross-region-wiring](18-cross-region-wiring.md)** | **How regions wire together** — sidebar selection → main area switch → status bar update (a set of recipes) |
176
+ | **19** | **[19-component-cheatsheet](19-component-cheatsheet.md)** | **Which UI parts the shell provides**, and when to use which |
177
+ | **20** | **[20-adding-a-setting](20-adding-a-setting.md)** | The minimal approach: declare one → it appears on the settings page automatically → read it in code |
178
+ | **T1** | **[themes/01-build-a-theme-plugin](themes/01-build-a-theme-plugin.md)** | The theme-authoring walkthrough (no code) |
179
+ | **T2** | **[themes/02-theme-field-index](themes/02-theme-field-index.md)** | A cross-index of recipe fields and CSS variables |
180
+
181
+ **JSON Schema:** `plugin.schema.json` — IDE autocompletion | Theme recipes: `schemas/theme.schema.json` inside the SDK package
182
+
183
+ ---
184
+
185
+ ## Related
186
+
187
+ - Contract type source of truth: `linkdesk.d.ts` inside the `@linkdesk/contracts` package (arrives with the SDK)
188
+ - Theme system design doc (**the shell's why**; authors need not read it): repo `docs/02-Electron架构/E5.8_归一化基建/外观主题化/`
189
+ - Legacy Tauri-era docs: `docs/01-Tauri_P1至P5.5/` (historical reference only)
@@ -0,0 +1,171 @@
1
+ # 01 — Plugin API Contract
2
+
3
+ > 2026-08-04. **`window.linkdesk.*` — the complete set of system-level capabilities a plugin developer can call.** Web platform capabilities (Canvas/WebGL/WebRTC/fetch, etc.) are unrestricted — only system-level capabilities go through this API.
4
+ >
5
+ > **Update:** after the single-WebView rollback, the `linkdesk.*` API is the only sanctioned way for plugins to reach the shell. ESLint blocks direct imports of `ConfigurationService/FileService/pathUtils` at `error` level.
6
+ >
7
+ > **Update:** this document has changed from a "hand-written namespace table (a second source of truth)" into a **pointer** — method details are no longer hand-written; the single source of truth = the **generated contract file** `contracts/linkdesk.d.ts` (see §3). The principles and navigation remain.
8
+ >
9
+ > **VS Code analogue:** the `vscode` namespace.
10
+
11
+ ---
12
+
13
+ ## 1. Design Principles
14
+
15
+ | Principle | How it shows up |
16
+ |------|------|
17
+ | **Core knows nothing** | The shell doesn't recognize any plugin's pluginId |
18
+ | **Contract first** | Plugins go through `window.linkdesk.*`, not `import @src/core` |
19
+ | **Sync first** | APIs that can be synchronous aren't wrapped asynchronously (`path` is pure functions, no IPC) |
20
+ | **Security** | The plugin preload is narrower than the shell's — **the only missing namespace is `bridge`** (shell-main-control only: the envelope for plugin IPC requests that the main process forwards to shell-side services); and the preload sandbox has zero Node capability (no `require`/`fs`/`child_process`) |
21
+
22
+ ---
23
+
24
+ ## 2. Shell vs Plugin — API Differences
25
+
26
+ Plugins and the shell run in the same renderer process, but the injected namespace surfaces differ. **Which process each surface is available in, and how the pool/shell/mock coverage works — the single source of truth is [Namespace Matrix §2 coverage table](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)**; no second list is hand-written here.
27
+
28
+ A few key points (a summary of Matrix §2; the matrix wins on details):
29
+
30
+ | Fact | Explanation |
31
+ |------|------|
32
+ | **The contract has 40 namespaces** | The pool injects 39 (the only missing one is `bridge`); the shell injects 22; mock injects 12 |
33
+ | **Pool = the plugin runtime source of truth** | Plugins run in the pool preload — namespaces injected by the pool are **required**; `bridge` is real-shell-only |
34
+ | **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** (N1 superset note) — the older version's ❌ shell-only marking for those surfaces was wrong |
35
+ | **Contract required-surface drift is now zero** | D1 `env.get(pluginId)` forwarding, D2 `clipboard.readText` shell completion, D3 `dialog.openFile` shell completion — #20 implemented all of them, with no `?` degradation |
36
+
37
+ ---
38
+
39
+ ## 3. Complete API Definition → Pointer
40
+
41
+ ### 3.0 The Single Source of Truth
42
+
43
+ **Every method signature, parameter, return value, and payload type for `window.linkdesk.*` = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)** (auto-generated; do not hand-edit).
44
+
45
+ - **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (14 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
46
+ - **Generator:** `scripts/generate-contract.mjs` (Route C — the contract type file is the source; pure types bundled into a single file)
47
+ - **Mechanical gate:** the preload on both sides `satisfies` the contract surface types → tsc drift gate; `contracts:check` byte-compares hashes inside `npm run check` (#21)
48
+ - **Coverage matrix:** every namespace × pool/shell/mock coverage → [Namespace Matrix §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
49
+
50
+ ### 3.1 How Plugins Consume It
51
+
52
+ **Path A — repo tsconfig alias (plugins inside this repo):** the root `tsconfig.json` already configures `"@linkdesk/contracts": ["./contracts/linkdesk.d.ts"]`, so type imports go straight to the contract file:
53
+
54
+ ```typescript
55
+ // Types — the named surface interfaces in the contract file (`import type`, zero runtime coupling)
56
+ import type { FileEntry, PluginStateChangedPayload } from "@linkdesk/contracts";
57
+
58
+ // Runtime — ambient types come straight out (the file declares global Window.linkdesk; no import needed)
59
+ async function list(): Promise<FileEntry[]> {
60
+ return window.linkdesk.filesystem.listDir("/workspace");
61
+ }
62
+ ```
63
+
64
+ **Path B — standalone npm package (third-party plugins, #22.6):** after `npm i -D @linkdesk/contracts`, use the same `import type { ... } from "@linkdesk/contracts"`.
65
+
66
+ > **Package shape (built):** `contracts/` is the npm package root (`@linkdesk/contracts`, its `types` entry points straight at `linkdesk.d.ts`, zero build, and the `files` allowlist contains only the d.ts). **Independent version axis (decoupled 2026-09-06, reversing the 22.6 version linkage):** the package version **no longer follows the shell** — a software upgrade (the user axis) ≠ a contract upgrade (the author axis); the version only bumps and publishes when the `window.linkdesk.*` API surface changes. **Content detection is not withdrawn**: d.ts/runtime-shapes are compared byte-for-byte against the shell source, and any drift turns `contracts:check` red (change the API and forget to regenerate = your commit is stuck); **shelf cadence = the check-npm-release yellow light gate** (author-facing content changed + version untouched → a reminder to bump+publish). **Consumption-shape acceptance:** `contracts-example/` at the repo root — a standalone tsconfig + local `file:../contracts` reference, `npx tsc --noEmit` reporting zero errors, and zero `@src/core` throughout (`npm pack` produces a tarball → the real npm package path passes too). **Release state:** ✅ genuinely published `@linkdesk/contracts@0.1.0` (2026-09-04) + `@linkdesk/contracts@0.1.1` (2026-09-06, the first independent-axis version after decoupling) + `@linkdesk/contracts@0.1.2` (same day, 2026-09-06; 0.1.1 shipped with the stale "version linkage" README → README fixed and republished, d.ts unchanged) — third parties can `npm i -D @linkdesk/contracts` to install the real package straight from the registry; real-package tsc acceptance has passed. plugin-sdk and `@linkdesk/ui` were genuinely published in the same period.
67
+
68
+ **Path C — copy the file:** copy `contracts/linkdesk.d.ts` into your plugin project and reference it from tsconfig. The contract file is self-contained (94 declarations, zero import dependencies), so copying just works.
69
+
70
+ > **Pick any one of the three paths; `import type { ... } from "@src/core"` is forbidden** — that's stealing shell source types (see §5).
71
+
72
+ ### 3.2 Runtime Semantic Conventions (the things a d.ts can't express live here)
73
+
74
+ > Method signatures follow the contract file; below are the **behavior contracts** that don't fit into types — plugins must code to them.
75
+
76
+ | Namespace | Runtime convention |
77
+ |------|------|
78
+ | **events** | Channel naming `<plugin id>:<data name>` (e.g. `serial:rawData`, `sbq-protocol:parsed`). The shell broadcast event table is below |
79
+ | **quickPick** | The Promise resolves a **structured copy** (contextBridge structured-clones across worlds, so `===` against the original object won't work); Escape / clicking the scrim / blur / being displaced by a new `show()` → resolves `undefined` (last-wins); a non-array `opts.items` → reject. Shell overlays take priority. **Make the call inside a component effect** — the shell-side execution half calls `show` without this API and is a no-op |
80
+ | **viewContainer** | **Metadata flows one way**: view registration follows plugin.json `contributes.views`; `registerView` on an existing view only overwrites metadata, while `render` keeps the original component; a `descriptor` carrying `render`/`actions`/`pinnedContent` is stripped by the pool-side allowlist (it can't cross IPC); querying a nonexistent container/view → `undefined`/`[]` |
81
+ | **decorations** | **Synchronous contract**: `provideDecoration` returns `FileDecoration \| null \| undefined` and **must not return a Promise** (async providers are skipped); a repeated `registerProvider` for the same pluginId idempotently overwrites; unregister/register automatically fires a full refresh notification `onDidChange([])`; if a provider throws, that entry is self-healed away |
82
+ | **filesystem** | Plugin permissions: read/write its own data directory, read the workspace directory, **other plugins' directories are off-limits** |
83
+ | **configuration** | Config key naming rule `<pluginId>.<property>` (e.g. `editor.fontSize`, `serial-monitor.baudRate`) |
84
+ | **serial** | **Multi-port routing:** the `portName` of the open/close/action-targeting interfaces is **optional** — omitted = the single open port (0 ports throws "serial port not open"; ≥2 ports throws "multiple serial ports open, please specify portName"; **failures are visible, never silent**). The three streaming channels (`onData`/`onStats`/`onSystem`) carry **object** payloads with a `portName` routing key (`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`) — subscribers filter by **their session's port** (key=portName is the generic routing-key pattern: whoever consumes filters; the shell does not collect on their behalf). Each tab is still single-port (D3), and the session-to-port binding lives on the plugin side |
85
+ | **panel** | `panel.reveal(viewId)` focuses a Bottom Panel view through declarative addressing — panel hidden → expand it and switch to that view (the same mechanism as Ctrl+J); already shown → switch and focus; **viewId not in the panel container → no-op** (no error). **`panel.moveToEditor` has been removed** (deprecated content migration — moving position is the job of the layout command). `panel.revealFloating(viewId)` pops a view out as an in-shell Floating Panel (type B) — declared addressing. Declarative addressing = the ViewContainerService global view index (`contributes.views` registers a view in **any container**, not just panel — plugins declare `contributes.floatingPanel.viewId` to reference it). **Identity toggle key (I8-2)**: no panel → open; same view → close (toggle); another panel → replace; **viewId undeclared / declaring plugin not installed → no-op** (no crash). Default panel actions = "Open in main window" (appears only when the declaring plugin can open as a tab) + maximize toggle + close |
86
+ | **hotExit** | Crash recovery only — dirty content is written to disk at `%APPDATA%/linkdesk/hot-exit/` (a single-source path convention owned by the main process; plugins never write there directly); after saving/closing a tab, call `clear` to delete the backup |
87
+ | **shell** | Shell-level OS actions: `showItemInFolder(p)` highlights a single file in Explorer / `openInTerminal(dirPath, terminalExe?, customCommand?)` opens an external terminal / `startDrag(filePath, iconPath?)` drags out to the desktop. **`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` are the plugin-disk-location pair** — the former returns `{ installDir, dataDir } | null` (**it hands over identity, not the right to assemble paths**: the main process resolves paths and the plugin takes the result; not found on disk → `null`; `dataDir` is non-`null` only once the plugin has **actually written to disk**, and empty/absent means that row shouldn't be drawn); the latter's `kind: "install" \| "data"` opens the directory **contents** in Explorer (the same feel as `appearance.revealStorage`, not `showItemInFolder`'s single-file highlight) — the `install` directory not being on disk throws, while `data` creates an empty directory first, then opens. **(G4): `relaunch` genuinely restarts the app** (quits and relaunches the process) — ⚠️ **injected by the shell preload only (the contract marks it `?` optional)**, so pool-side callers must check existence first (`window.linkdesk.shell.relaunch?.`). The difference from `window.location.reload` is **whether the pool survives**: the pool is a separate `WebContentsView` that a shell reload does not rebuild, so after updating a view-type plugin a reload only shows the old bundle; after `relaunch` the current process terminates immediately, so **don't rely on its return value** (the Promise never settles) |
88
+ | **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>` |
89
+ | **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, #57.5). The shell also has a private `getProductInfo` extension (the data source for the about page's 8 fields, #57.14 — not in the contract, so pool plugins can't call it) |
90
+ | **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 |
91
+ | **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 |
92
+ | **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 |
93
+
94
+ **Shell broadcast events (plugins can subscribe via `events.on`):**
95
+
96
+ | Channel | payload | When it fires |
97
+ |------|------|------|
98
+ | `theme:changed` | `{ themeId, themeType, variables }` | The user switches theme (CSS variables are injected automatically; no manual subscription needed). **The `variables` payload includes the font-size variables `--font-size-*` + `--ui-scale`** (global font scaling rides the existing theme channel, with **no new event**; see 05-ui-conventions §10 for font-size consumption tokens) |
99
+ | `iconTheme:changed` | `{ iconThemeId, mappings, fontFaces?, glyphCss? }` | The user switches icon theme (the `app.iconTheme` setting). `iconThemeId` = the chosen icon theme id; `mappings` = that theme's mapping table (an `IconThemeMappings` shape, with image assets already resolved to `linkdesk://` absolute URLs), or `undefined` when it is `"default"` (consumers fall back to codicons as a safety net). `fontFaces`/`glyphCss` = the @font-face specs and glyph class CSS source when the theme declares a custom font (the `font` section at the top level of the mappings JSON) — the pool preload already injects them into the pool document automatically (custom icon font rendering; consumers don't need to handle it); absent when there is no font section or it is `"default"`. The top level of `mappings` may declare 5 default icons `file`/`folder`/`folderExpanded`/`rootFolder`/`rootFolderExpanded` (single entries, matching VS Code iconTheme top-level keys) — when nothing matches the table (ordinary folders/new files/root folder) consumers use the theme's default icon instead of a codicon; absent = codicon safety net. **Only the mapping itself doesn't take effect automatically — plugins that need custom file icon visuals subscribe manually** (e.g. a file tree swapping icons per `mappings`, matching VS Code `onDidChangeProductIconTheme`) |
100
+ | `lang:changed` | `{ lang, resources }` | The user switches language |
101
+ | `workspace:changed` | `{ rootPath }` | The user opens/switches a folder |
102
+ | `plugin:installJobs` | `{ jobs: InstallJob[] }` (**a full snapshot, not a delta**) | The shell-side install/uninstall queue changes (added: stage and percent; added: `kind`·`cancellable`). `InstallJob` = `{ jobId, pluginId, origin: "user"\|"dependency", kind: "install"\|"uninstall", cancellable: boolean, displayName, state: "queued"\|"running"\|"settled", terminal?: "success"\|"failed"\|"parked", error?, stage?, percent?, message? }` — **every broadcast is the whole table**, so consumers **replace their local mirror outright** instead of merging deltas. **Late subscribers get the latest full table**: the pool preload caches one at the top level and replays it synchronously on subscribe (a remounted view never gets stuck on an old snapshot). ⚠️ This is a **public event surface**, not a marketplace-private pipe — any plugin can subscribe and build its own progress UI; ⚠️ **`stage`/`percent`/`message`/`kind`/`cancellable` are additive-only fields**, so older consumers can simply ignore them. ⚠️ `origin: "dependency"` = a dependency some plugin dragged in, nested inside the row that initiated it (`origin: "user"`) |
103
+
104
+ ### 3.3 Differences from the Old Hand-Written Version (note for readers)
105
+
106
+ The old §3.x per-namespace method list has been deleted (= a hand-written second source of truth, guaranteed to drift). The generated contract resolved several places where **the old docs disagreed with the implementation**:
107
+
108
+ | Point | Old hand-written version | Contract/implementation reality (after #20) |
109
+ |------|------|------|
110
+ | `serial.listPorts()` | Written as `getPorts()` | The contract says `listPorts()` — the implementation always used that name; the old doc had a typo |
111
+ | `serial.onData/onStats/onSystem` | `cb: (d: any)` / string | **Object payloads**: `onData(p: SerialDataPayload)` / `onStats(p: SerialStatsPayload)` / `onSystem(p: SerialSystemPayload)` — all three channels carry a `portName` routing key (`SerialStats` was deleted; no dead type tail) |
112
+ | `decorations.provideDecoration` | Written as possibly returning `Promise<FileDecoration>` | The contract is **sync only** (providers that return a Promise are skipped) |
113
+ | `pluginState.onChange` | Comment said "available once multi-WebView is restored" | The pool already injects onChange — subscribing works; subscribe to the wildcard key name via `events.on("plugin-state:changed")` (re-exports `PluginStateChangedPayload`) |
114
+
115
+ ---
116
+
117
+ ## 4. IPC Reliability Conventions
118
+
119
+ 1. **Every invoke has a 10s timeout.** A timeout throws an `Error`
120
+ 2. **Return values can be falsy.** `""`/`0`/`false` are legitimate values. Use `isNaN(n) ? default : n`, not `n || default`
121
+ 3. **Use a ref bridge when an IPC callback needs React state**
122
+ 4. **The `onChange` callback pattern** (configuration/language) — returns an unsubscribe function; call it on component unmount to clean up
123
+
124
+ ---
125
+
126
+ ## 5. Prohibited
127
+
128
+ | ❌ | ✅ Instead |
129
+ |---|---|
130
+ | `import { normalizePath } from "@src/core/pathUtils"` | `lk.path.normalize(p)` |
131
+ | `import { getConfigurationValue } from "@src/core/ConfigurationService"` | `lk.configuration.get(key)` |
132
+ | `import { listDir } from "@src/core/FileService"` | `lk.filesystem.listDir(p)` |
133
+ | `import { getWorkspaceFolders } from "@src/core/WorkspaceService"` | `lk.workspace.getFolders()` |
134
+ | `import type { FileEntry } from "@src/core/types/fileEntry"` | `import type { FileEntry } from "@linkdesk/contracts"` |
135
+
136
+ **ESLint `error` (`noCoreImportInPlugin`, tightened by #20-d):** `import { ... } from "@src/core/..."` **and** `import type { ... } from "@src/core/..."` → 🚫 compile failure. Test files are no longer exempt (the vitest single-process rationale no longer holds).
137
+
138
+ **Allowed imports (shared controls come from the `@linkdesk/ui` npm package; the full `@src/core` exception allowlist lives in `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
139
+ - `@linkdesk/contracts` **types** (`import type`, zero runtime coupling) — the real registry package (see §3.1)
140
+ - `@linkdesk/ui` **shared controls / shared hooks** (ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker, etc., consolidated) — **declare it explicitly in your own project's `dependencies`** (`"@linkdesk/ui": "^0.1.4"`) and build against the published package. 🔴 After that, **official plugins and third-party plugins share one project shape** (the six official ones already have the explicit declaration added); the only exception is those two **dev fixtures** inside the shell repo (still hoisted via the root workspaces). **Never import from `@src/components/shared/*`** (the second entry point for shared controls has been deleted)
141
+ - **Pure-utility allowlist (`@src/core` exceptions)**: `@src/core/pipeline/*` (DataConverter / DataDispatch / RingBuffer / ProtocolParser) + `@src/core/utils/CancellationToken` + `@src/core/registry/commands/MenuRegistry` (the MenuId type/enum only) and so on — treat `eslint-local-rules.js` as the only authority for the full table; don't copy a second one here
142
+ - 🔴 **Review conclusion**: this allowlist **is in practice used only by shell-repo fixtures** — after the official plugins moved out of the shell repo, their source has zero `@src` hits (at runtime everything goes through `window.linkdesk.*`; measured). The allowlist **stays** (the fixtures are still inside `plugins/` and still guarded by that same eslint rule), but **third-party authors should pretend it doesn't exist**: the only three things you can use are `@linkdesk/contracts` / `@linkdesk/ui` / `window.linkdesk.*`
143
+ - **Exception registry**: imports outside the allowlist must be registered before they are permitted (an audit item of the plugin-independence iron rule)
144
+
145
+ > **Shell hooks/services such as `useConfiguration` / `useSendData` / `ViewContainerService` are forbidden to import** (they hold module-level state → the shell process can't see the caller's changes) — plugins read configuration through `window.linkdesk.configuration` and sync state through `window.linkdesk.events` (subscription broadcast) / `serial.onData` and other data pipelines (see `07-plugin-to-plugin-communication.md`).
146
+
147
+ ---
148
+
149
+ ## 6. Device Channel Boundaries
150
+
151
+ > Continuing from "2. Shell vs Plugin" — **how far a device-plugin author can get on their own, and what the platform commits to.** The basis is one shell boundary discipline: **the shell only provides generic channels; it does not build in device business.**
152
+
153
+ **In one sentence: parsing is yours, the channels already exist — no need to ask the shell authors, no need to wait for a shell release.** Channel types are converged by the shell (enumerable); devices are unbounded and belong to plugins.
154
+
155
+ | Layer | Device example | Channel | Author status |
156
+ |:--|:--|:--|:--|
157
+ | **Serial family** (the biggest chunk) | USB-CAN adapters (CH340/CP210x virtual serial), GPS modules (NMEA), USB-TTL, cheap logic analyzers | `linkdesk.serial.*` (after its Phase 6 generalization) | ✅ **Write it today, zero shell dependency**; multi-port/multi-plugin coexistence works |
158
+ | **Custom USB** | Professional logic analyzers (Saleae-class, custom USB endpoints) | A future `usb` channel | ⏳ A versioned evolution after launch adds one generic channel (one-off, isomorphic to serial); **devices of this kind have to wait until it lands** |
159
+ | **Vendor-proprietary DLLs** | High-end devices (vendor SDK/DLL only) | A native channel | ⚠️ A separate architecture topic (the renderer sandbox has no Node permissions); out of current scope |
160
+
161
+ **The platform's responsibility boundary (authors can rely on this):**
162
+ - **Channel correctness + a stable API promise** — the platform authors own the channel (open → streaming read/write → close/errors/multiple instances/resource reclamation); changing the API after launch = versioned evolution (an `engines` declaration) — additions don't break the contract and don't affect existing plugins.
163
+ - **Device protocol correctness belongs to the author** — CAN frames/NMEA/sample parsing are all the plugin's job; the shell doesn't recognize any device.
164
+ - **One physical port has a single consumer** — the OS driver is exclusive (a port opened by `serial-monitor` cannot be opened at the same time by another plugin or tab; multiple plugins coexisting = each opens its own port).
165
+
166
+ > To confirm the ready-made `linkdesk.serial.*` capabilities → the `Serial` domain in [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts). For custom USB/native channels → raise it with the platform authors — that's the "add a channel" category (converged, enumerable, one-off), not doing bespoke work for one plugin.
167
+
168
+ ---
169
+
170
+ > **Next:** `02-plugin-lifecycle.md`
171
+ > **Index:** `00-readme.md`