@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
@@ -0,0 +1,640 @@
1
+ # The plugin.json Spec
2
+
3
+ > **2026-09-06 reconciliation against the implementation** (audit): flattened single root `plugins/<id>` (no builtin/user two-tier) · there is only one kind of plugin (`core:true` = an accidental-uninstall guard flag, not a category) · `distribution` = ⚠️ legacy field, do not fill it in.
4
+ > πŸ”΄ **Throughout this document, "the root" always means the root of the plugin's own repo**: plugin source lives in **its own repo**; the `plugins/` folder of the shell repo holds only two development fixtures.
5
+ > Every bare path in this document (`plugin.json` / `src/…` / `resources/…`) is **relative to the plugin repo root** β€” do not go looking for a shipped plugin's source under the shell repo's `plugins/` (it is not there).
6
+ > The single entry point for plugin metadata. One plugin = one folder + one `plugin.json` + one entry file.
7
+ > **Aligned with VS Code: the `type` field is no longer needed β€” the loader detects the contribution type from the declared fields.**
8
+
9
+ ---
10
+
11
+ ## Plugin directory structure
12
+
13
+ A plugin is just a folder (a source directory). In the repo source tree it is `plugins/<id>/` (flattened single root, directory name = plugin ID); third-party authors develop at **their own project root** and build a `.linkdesk-plugin` for distribution (see [04-distribution-format Β§1](04-distribution-format.md)). **There is no builtin/user two-tier.**
14
+
15
+ ```
16
+ my-plugin/
17
+ β”œβ”€β”€ plugin.json # Plugin metadata (the only required file)
18
+ β”œβ”€β”€ README.md # Plugin description β€” data source for the "Details" tab of the detail page
19
+ β”œβ”€β”€ CHANGELOG.md # Changelog β€” the single source of truth for the "Changelog" tab of the detail page
20
+ β”œβ”€β”€ resources/ # Static assets β€” icons / images / fonts
21
+ β”‚ └── icon.svg # Icon (SVG recommended)
22
+ β”œβ”€β”€ src/ # Source code
23
+ β”‚ β”œβ”€β”€ index.tsx # Entry component
24
+ β”‚ β”œβ”€β”€ sidebar.tsx # Sidebar component (if any)
25
+ β”‚ └── styles.css # Styles
26
+ └── i18n/ # Translation files (optional, declared by contributes.i18n)
27
+ ```
28
+
29
+ | File | Description |
30
+ |------|------|
31
+ | `plugin.json` | **The only required file.** The file name is fixed and cannot be renamed |
32
+ | `README.md` | Plugin description β€” data source for the "Details" tab of the detail page. **The file name is fixed and it is not written into `plugin.json`** (see [09-plugin-directory-layout](09-plugin-directory-layout.md)) |
33
+ | `CHANGELOG.md` | Changelog β€” the **single source of truth** for the "Changelog" tab of the detail page. **The file name is fixed and it is not written into `plugin.json`**; the section-heading format is in [09-plugin-directory-layout](09-plugin-directory-layout.md) |
34
+ | `src/` | **Recommended**: put source under a `src/` subdirectory instead of leaving it flat. The `entry`/`sidebar` paths are relative to `plugin.json`, e.g. `"entry": "src/index.tsx"` |
35
+ | `resources/` | Static assets such as icons. Aligned with the `resources/` / `assets/` directories common in VS Code extensions |
36
+ | `icon` field | A path relative to `plugin.json`, e.g. `"icon": "resources/icon.svg"` |
37
+ | `i18n/` | Translation files β€” one JSON per language (the path is declared by `contributes.i18n`) |
38
+ | `__tests__/` | Test files; `src/__tests__/` is recommended |
39
+
40
+ > **A plugin source directory produces no `dist/`** (distribution build artifacts are produced by plugin-sdk into the `.linkdesk-plugin` (`index.bundle.js` + `views/*.bundle.js` + a rewritten plugin.json); authors do not care). The complete directory conventions are in `09-plugin-directory-layout.md`.
41
+
42
+ ---
43
+
44
+ ## There is only one kind of plugin β€” identity differences live in declared fields, not in directories
45
+
46
+ **After the single-root flattening (2026-09-05) there are no longer "builtin/user" kinds**: repo `plugins/<id>` and installed-state `{userData}/plugins/<id>` are both **flat single roots** β€” plugins shipped with the shell and third-party installs sit side by side in the same tree. The only difference is in plugin.json fields:
47
+
48
+ | Field | Meaning | Who should fill it in |
49
+ |------|------|:--|
50
+ | `core: true` | **UI accidental-uninstall guard flag** β€” the uninstall button is hidden/disabled (the shell depends on it for baseline interactions such as the settings page and the plugin marketplace). **No behavioral privileges, not a category** | These official ones: `editor` `file-tree` `marketplace` `settings` |
51
+ | `distribution` | ⚠️ **Legacy field** (already marked deprecated in the schema, do not fill it in) β€” it no longer maps to any directory and the install side always normalizes it to `user` | **Third parties must not fill this in** |
52
+
53
+ ### Creating a plugin (third party, your own project root)
54
+
55
+ ```jsonc
56
+ // my-plugin/plugin.json
57
+ {
58
+ "name": "My Plugin",
59
+ "version": "1.0.0",
60
+ "entry": "src/index.tsx"
61
+ // Do not fill in core β€” an ordinary plugin the user can freely install and uninstall
62
+ // Do not fill in distribution β€” a legacy field; once installed into the app it is always normalized to user
63
+ }
64
+ ```
65
+
66
+ Build β†’ `<id>.linkdesk-plugin` β†’ the user installs it β†’ `{userData}/plugins/<id>/` (see [04 Β§2](04-distribution-format.md)).
67
+
68
+ ### core:true official plugins (shipped with the shell)
69
+
70
+ ```jsonc
71
+ // plugins/file-tree/plugin.json (actual state of the repo's single root)
72
+ {
73
+ "name": "File Tree",
74
+ "version": "1.0.0",
75
+ "core": true, // πŸ”₯ uninstall guard β€” no uninstall button in the UI
76
+ "entry": "src/index.tsx"
77
+ }
78
+ ```
79
+
80
+ > **Wording discipline (hard constraint 11):** "builtin / shipped with the shell" refers to that copy of `bundled-plugins/*.linkdesk-plugin` and the boot auto-install path, **not to a kind of plugin**. Say "a plugin with core:true", "a plugin shipped with the shell" β€” do not say "builtin plugins are…" as a category definition. An official plugin distributed through the marketplace is just as much an ordinary plugin when it does not set core β€” whether it is bundled is decided by whether it goes into bundled-plugins, not by the field.
81
+
82
+ ---
83
+
84
+ ## Minimal example (a view plugin)
85
+
86
+ ```json
87
+ {
88
+ "pluginId": "gps-map",
89
+ "name": "GPS Map",
90
+ "version": "1.0.0",
91
+ "icon": "resources/map.svg",
92
+ "description": "Interactive map view, supports Leaflet/Amap",
93
+ "author": "Community",
94
+ "entry": "src/index.tsx"
95
+ }
96
+ ```
97
+ The `entry` field β†’ the loader automatically recognizes this as a view plugin. `pluginId` = **the plugin's identity, forever immutable after publication** β€” although it runs without one (it falls back to the project directory name), **new plugins should always declare it explicitly**: repo names and local directory names are free-form, and relying on the fallback lets identity drift along with the name.
98
+
99
+ ## Contribution detection rules
100
+
101
+ | Declared field | Auto-detected as | Load behavior |
102
+ |---------|-----------|---------|
103
+ | `entry` | view | dynamic import β†’ registered into viewRegistry |
104
+ | `themes` | theme | registered into ThemeEngine |
105
+ | `languages` | language | registered into i18next |
106
+ | `mode` | protocol | protocol registration (fully implemented in Phase 5)|
107
+ | `resources` | resource | resource registration (fully implemented in Phase 5)|
108
+ | `sidebar` | view + sidebar | the sidebar component is registered together with the view |
109
+ | `statusBar` | view + statusBar | the status bar contribution is registered together with the view |
110
+ | `contributes.commands` | β€” | registered into CommandRegistry β†’ command palette / context menus / keybindings |
111
+ | `contributes.configuration` | β€” | registered into ConfigurationRegistry β†’ rendered automatically by the Settings Editor |
112
+ | `contributes.menus` | β€” | registered into MenuService β†’ context menus generated dynamically |
113
+ | `contributes.keybindings` | β€” | registered into KeybindingRegistry β†’ global keyboard listening |
114
+ | `contributes.themes` | theme (P6) | registered into ThemeRegistry β†’ theme browser |
115
+ | `contributes.languages` | language (P6) | registered into LanguageRegistry |
116
+ | `contributes.fileAssociations` | β€” (P6) | registered into FileAssociationService β†’ double-clicking a file opens it automatically |
117
+ | `contributes.floatingPanel` | β€” | Declares that the view can be displayed in a floating panel inside the shell β€” viewId references an already-registered view; without the declaration there is no "Open in Floating Panel" context-menu item |
118
+
119
+ **A plugin can declare several contributions at once.** A view plugin, for example, can have `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands` β€” each is registered independently and does not affect the others.
120
+
121
+ ## Complete examples
122
+
123
+ ### View + sidebar + status bar
124
+
125
+ ```json
126
+ {
127
+ "name": "Terminal",
128
+ "version": "1.0.0",
129
+ "icon": "terminal",
130
+ "entry": "index.tsx",
131
+ "sidebar": "sidebar.tsx",
132
+ "statusBar": [
133
+ { "id": "connection", "label": "Not connected", "align": "left" },
134
+ { "id": "stats", "label": "TX:0 RX:0", "align": "left" }
135
+ ]
136
+ ```
137
+
138
+ ### Theme plugin
139
+
140
+ ```json
141
+ {
142
+ "name": "Dracula",
143
+ "version": "1.0.0",
144
+ "icon": "color-mode",
145
+ "description": "The classic Dracula dark theme",
146
+ "author": "Community",
147
+ "file": "dracula.json"
148
+ }
149
+ ```
150
+
151
+ Multi-theme package:
152
+
153
+ ```json
154
+ {
155
+ "name": "Dracula Official",
156
+ "version": "1.0.0",
157
+ "themes": [
158
+ { "id": "dracula", "name": "Dracula", "file": "dark.json" },
159
+ { "id": "dracula-soft", "name": "Dracula Soft", "file": "soft.json" }
160
+ ]
161
+ }
162
+ ```
163
+
164
+ ### Language pack plugin
165
+
166
+ ```json
167
+ {
168
+ "languages": [{ "code": "ja", "name": "ζ—₯本θͺž", "file": "ja.json" }],
169
+ "name": "ζ—₯本θͺž",
170
+ "version": "1.0.0",
171
+ "icon": "globe",
172
+ "description": "Japanese UI translation",
173
+ "author": "Community",
174
+ "file": "ja.json"
175
+ }
176
+ ```
177
+
178
+ ### Protocol plugin
179
+
180
+ ```json
181
+ {
182
+ "mode": "text",
183
+ "name": "SBQ Heart-Rate Protocol",
184
+ "version": "1.0.0",
185
+ "icon": "circuit-board",
186
+ "description": "Heart-rate protocol parser with a single-character packet header",
187
+ "author": "Community",
188
+ "entry": "index.ts",
189
+ "mode": "text"
190
+ }
191
+ ```
192
+
193
+ ### Static resource plugin
194
+
195
+ ```json
196
+ {
197
+ "name": "STM32 Register Manual",
198
+ "version": "1.0.0",
199
+ "icon": "book",
200
+ "description": "STM32F103 reference manual HTML",
201
+ "author": "Community",
202
+ "resources": ["manual.html"]
203
+ }
204
+ ```
205
+
206
+ ---
207
+
208
+ ## Field reference
209
+
210
+ ### Required fields
211
+
212
+ | Field | Type | Description |
213
+ |---|---|---|
214
+ | `name` | `string` | Display name, visible to users. **Required at the schema level** (alongside `version`; these are the only two that are mandatory) |
215
+ | `version` | `string` | Semantic version, e.g. `"1.0.0"`. **Required at the schema level.** πŸ”΄ **It is also the single source of truth for the "same version in four places"** (`CHANGELOG.md` section heading ↔ this field ↔ the catalog entry `versions[].version` ↔ `package.json.version`) β€” rules in [09-plugin-directory-layout](09-plugin-directory-layout.md) under "version synchronization"; **this table does not duplicate them** |
216
+ | `entry` | `string` | Entry file path, relative to the plugin directory. **Needed only by view / tab plugins** β€” it is not required at the schema level (an entryless sidebar plugin has zero entry; see "When an icon appears in the icon bar") |
217
+ | `icon` | `string` | Icon identifier β€” a codicon/Lucide name or an SVG path (optional; a default icon is used if omitted) |
218
+
219
+ > **The `type` field is deprecated** (no longer required, and not on the schema's required list) β€” the loader detects the contribution type automatically from the declared fields `entry`/`themes`/`languages`/`mode`/`resources`/`contributes`.
220
+
221
+ ### Optional fields
222
+
223
+ | Field | Type | Description |
224
+ |---|---|---|
225
+ | `$schema` | `string` | JSON Schema reference path |
226
+ | `pluginId` | `string` | πŸ”΄ **The plugin's identity β€” forever immutable after publication** (VS Code's `publisher.name` is the counterpart). The install directory `{userData}/plugins/<pluginId>/`, the distribution file name `<pluginId>.linkdesk-plugin`, the marketplace catalog dedupe key, the uninstall tombstone key and update reconciliation all key off it. **Declaring it explicitly is strongly recommended**: without a declaration it falls back to the "project directory name", and repo names and local directory names are free-form β€” rename the directory and the identity changes with it, with **nothing ever reporting an error**. Charset `^[A-Za-z0-9][A-Za-z0-9._-]*$`. Rules and the empirical evidence behind them are in [16-naming-conventions](16-naming-conventions.md) |
227
+ | `core` | `boolean` | `true` = **UI accidental-uninstall guard flag** (matching the newer wording in the field table above) β€” the uninstall button on the detail page is hidden/disabled; **no behavioral privileges and not a category**: the API/command layers can still uninstall and disable it, and uninstalling writes a `removed` tombstone. Defaults to `false` |
228
+ | `distribution` | `string` | ⚠️ **Legacy field** (since the single-root flattening on 2026-09-05 it no longer maps to any directory; the install side always normalizes it to `user`; already marked deprecated in the schema). **Third parties must not fill this in** |
229
+ | `factoryRole` | `string` | System slot role: `"settings"` \| `"marketplace"`. **Filling it in = form 2 (replace / switch into the slot); omitting it = form 1 (coexist as an ordinary view plugin)** β€” see "The `factoryRole` field in depth" below |
230
+ | `iconSource` | `string` | `"codicon"` (default) / `"svg"` / `"url"` |
231
+ | `description` | `string` | One-line description shown on the plugin detail page. Multi-line is supported |
232
+ | `author` | `string` | Author name |
233
+ | `sidebar` | `string` | Sidebar component path; only effective for the `view` type |
234
+ | `tabBehavior` | `object` | Tab behavior declaration, see below |
235
+ | `statusBar` | `array` | Status bar contribution entries, see below. Only effective for the `view` type |
236
+ | `file` | `string` | Single-file entry β€” the `.json` of a `theme` or a `language`. Mutually exclusive with `themes`/`languages` |
237
+ | `themes` | `array` | Multiple themes `[{ id, name, file }]`. `theme` type only |
238
+ | `languages` | `array` | Multiple languages `[{ code, name, file }]`. `language` type only |
239
+ | `mode` | `string` | Protocol mode: `"text"` (available in Phase 4) / `"binary"` (Phase 6+ WASM). `protocol` type only |
240
+ | `resources` | `string[]` | List of resource files β€” HTML/images and so on. `resource` type only |
241
+ | `recommends` | `array` | Plugins recommended to be installed as well `[{ plugin: string, reason: string }]` |
242
+ | `suggests` | `array` | Optionally related plugins `[{ plugin: string, reason: string }]` |
243
+ | `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 |
244
+ | `screenshots` | `string[]` | Array of screenshot URLs (enabled in Phase 5+) |
245
+ | `minAppVersion` | `string` | Minimum app version requirement |
246
+ | `docs` | `string` | Bundled documentation path (for resource plugins) |
247
+ | `cardDocMap` | `object` | Card ID β†’ documentation anchor mapping |
248
+ | `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 |
249
+ | `cssVars` | `object` | Plugin-defined CSS variables `{ "--name": { "dark": "#fff", "light": "#000" } }` |
250
+ | `permissions` | `string[]` | Permission declarations `["serial", "filesystem", "network"]` (enabled in Phase 5+) |
251
+
252
+ ### Why are there no `readme` / `changelog` fields here?
253
+
254
+ The description and the changelog **are file-based** β€” `README.md` / `CHANGELOG.md` in the plugin root directory (location, format and their relationship to the detail page are in [09-plugin-directory-layout](09-plugin-directory-layout.md)).
255
+
256
+ These two fields did exist during early development, but they **never had a reader** (readers read files inside the package by **fixed file name** and never look at any declared field), so they **were removed on 2026-09-11**.
257
+
258
+ > **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.**
259
+
260
+ ### The `requires` field in depth
261
+
262
+ Plugin-level activation ordering β€” declares which plugins must be activated before this one is activated.
263
+
264
+ **VS Code's `extensionDependencies` is the counterpart**: the same family of mechanism, and this field is its normalized consolidation (see "Naming boundaries" below).
265
+
266
+ **Semantics:**
267
+ - The value = an array of the dependency plugins' `pluginId`s (no version constraints β€” activation ordering carries no version semantics; version matching is the marketplace's business)
268
+ - The loader loads in topological order: plugins in `requires` are activated first, then this plugin β€” scan order no longer affects activation order
269
+ - Missing dependency β†’ this plugin is suspended (PENDING) and loads automatically once the dependency is installed/enabled
270
+ - Dependency uninstalled/disabled β†’ this plugin is uninstalled along with it (consumers first, reverse topological order)
271
+ - A dependency cycle (A→B→A) → detected at load time and reported as an error; the plugin is not activated
272
+
273
+ **Example:**
274
+
275
+ ```json
276
+ {
277
+ "name": "Serial Enhancements",
278
+ "version": "1.0.0",
279
+ "icon": "package",
280
+ "requires": ["serial-core"]
281
+ }
282
+ ```
283
+
284
+ **Naming boundaries (three kinds of "dependency" that must not be confused):**
285
+
286
+ | Field | Level | Meaning |
287
+ |---|---|---|
288
+ | `requires` | Plugin level (top level of plugin.json) | Activation ordering dependency β€” dependencies first, then this plugin |
289
+ | `dependsOn` | Setting level (inside a `contributes.configuration` entry) | One setting depends on the value of another setting |
290
+ | `extensionDependencies` | Plugin level (historical field) | Deprecated β€” folded into `requires` (shipped) |
291
+
292
+ ### ~~`activationEvents`~~ β€” removed (retired, 2026-09-09)
293
+
294
+ > πŸ”΄ This field has been deleted from both the schema and the runtime; **do not write it again** (writing it raises no error β€” the schema root's `additionalProperties: true` tolerates old manifests, but it has no effect whatsoever).
295
+ > Why it was retired: once all the shell-side deferred-activation tracks were deleted, the load model was simplified to "register all metadata at startup + lazily load JS by URL from the pool" β€” no event field is needed for fine-grained control.
296
+ > **The current JS load-timing contract is in `02-plugin-lifecycle.md` Β§5**: surface mount (import when a view opens) βˆͺ on-command activation (command miss β†’ import the owning entry; for pure command plugins the handlers must sit at the top level of the entry).
297
+
298
+ ### The `factoryRole` field in depth β€” form 1 (coexist) vs form 2 (replace)
299
+
300
+ > **In one sentence: want your own icon/UI to appear *side by side* with the official one β†’ do not fill in `factoryRole` (an ordinary view plugin, coexisting by nature); want to *replace* the official one and become the system default (settings page / plugin marketplace) β†’ fill in `factoryRole` (enter the slot, switch between them).**
301
+
302
+ | | Form 1 (coexist) | Form 2 (replace) |
303
+ |---|---|---|
304
+ | Declaration | **Do not fill in** `factoryRole` | **Fill in** `factoryRole:"settings"` / `"marketplace"` |
305
+ | Essence | An ordinary view plugin (`appearsIn.iconBar` + its own view) | One candidate for that role, entering a FactorySlots slot |
306
+ | Icon bar | Its own icon **side by side** with the official one | The active set's icon **occupies the slot**; inactive sets are hidden |
307
+ | Switching | None β€” the user clicks whichever one they want | The settings page automatically shows a **group named after the role** + a switch button |
308
+ | Possible today? | βœ… Zero shell changes | βœ… Already shipped |
309
+
310
+ **Names play no part in the mechanism.** The shell has no "compare names" logic whatsoever β€” pluginIds are distinct and never collide; view ids are immune to collision thanks to the `(pluginId, viewId)` composite key; the display name is only for users. What is called a "group of the same name" is really a "**group of the same role**" β€” groups are named after the **role name** (e.g. "Plugin Marketplace"), so whether you call yours "Marketplace" or "Map Store", as long as you declare the same `factoryRole` you land in the same group.
311
+
312
+ **How to choose (the author's own expression):**
313
+ - **Want coexistence β†’ do not fill it in.** Example: a third party builds an entirely new marketplace UI; an extra icon of their own appears next to the official one in the icon bar, clicking it shows their UI, pulling the same data as the official one
314
+ - **Want replacement β†’ fill it in.** Example: declaring `factoryRole:"marketplace"` β†’ the settings page shows a "Plugin Marketplace" group + a switch button, and once switched, the icon/content become yours
315
+
316
+ **Form 2 implementation details** (already shipped; reference entities `plugins/settings` (the official core:true settings set) + `10-building-a-settings-plugin.md`):
317
+
318
+ - **β‘  One-to-many slots**: several plugins declaring the same `factoryRole` = **legitimately coexisting**; all are collected as slot candidates (no more "first one wins"). The **default** (when the user has never switched / on open) = first-registered stable order (core:true has no behavioral privilege and does not grab the default β€” registration order does not rely on a coincidence of scan order). Multiple coexisting candidates are no longer silent β€” the shell console fail-louds, naming every candidate + the default (re-emitted only when the candidate set for that role changes).
319
+ - **β‘‘ Active set = the user's switch choice, persisted to disk** (survives restarts). The public enumeration/switching surface is `window.linkdesk.factorySlots.*` (a generic enumeration surface, role-agnostic and taking a role parameter; the settings role additionally has the compatible alias `window.linkdesk.settings.*`, which forwards everything as-is internally):
320
+
321
+ | Method | Purpose |
322
+ |------|------|
323
+ | `factorySlots.listRoles()` | All filled role names (registration order) β€” the settings page enumerates roles first, then calls list(role) to judge the candidate count |
324
+ | `factorySlots.list(role)` | All candidates for that role `[{ pluginId, title, viewId? }]` β€” title = the raw display name, viewId = that set's `contributes.floatingPanel.viewId` (undefined if not declared) |
325
+ | `factorySlots.getActive(role)` | The active set's plugin ID β€” reads the persisted value; with no record / after uninstall it falls back to the default (the first-registered candidate, no core preference) |
326
+ | `factorySlots.setActive(role, pluginId)` | Switch the active set β€” validates the candidate, then persists; **a non-candidate fail-louds with an error** |
327
+
328
+ - **β‘’ Switch entry point = a role group on the settings page (appearing dynamically)**: when the settings UI opens it enumerates `listRoles()` β†’ for every **non-settings-plugin role** it calls `list(role)` β†’ **a group is created only when there are β‰₯2 candidates** (a single candidate makes switching meaningless). Group shape = the switch button on top (listing every candidate for that role, the active one highlighted) + the active set's own configuration below; it reuses a group of the same name where possible (finding the active candidate's own configuration group by pluginId), and only creates a new one otherwise; if the active set has no settings, it shows an empty state. Switching = `setActive` β†’ refetch data β†’ the configuration follows the active set. Switching your settings plugin's **own role** (settings) = the button in the generic area at the top (see `10-building-a-settings-plugin.md`).
329
+ - **β‘£ Icon bar slot occupancy**: for plugins that declare `factoryRole` (form 2), the icon bar **renders only the active set's icon** and hides inactive ones β€” "swap the official one out for yours"; form 1 plugins that do not declare it still all show up side by side as before.
330
+ - **β‘€ Routing seam**: opening settings (`Ctrl+,` / the gear) = `factorySlots.getActive("settings")` β†’ if a tab is already open, focus it / if `floatingPanel` is declared β†’ the floating panel (the payload carries pluginId for composite addressing) / if nothing is declared β†’ open a tab. After switching the active set, all subsequent opens go through the new set, consistently on both ends.
331
+ - **β‘₯ Switching sets on the plugin side** (the switch button's click, zero shell changes): `setActive` β†’ tab form = close this set's tab β†’ open the target set (singleton dedupe focuses it if it already exists); floating panel form = `panel.revealFloating(viewId, pluginId?)` **replacing the panel content in place with composite addressing** (no leftover tab popping up behind; if the target set declares no floatingPanel β†’ fall back to opening a tab). Deleting any set β†’ `onPluginLifecycleChange` β†’ refetch β†’ the button disappears on its own.
332
+
333
+ **Two-scenario example (official + third-party plugin marketplace):**
334
+
335
+ | | Form 1 (coexist) | Form 2 (replace) |
336
+ |---|---|---|
337
+ | Third-party declaration | Do not fill in `factoryRole` β€” an ordinary view plugin (`appearsIn.iconBar` + its own view + `pluginManager.*` data) | Fill in `factoryRole: "marketplace"` |
338
+ | Icon bar | Your own icon sits side by side next to the official Marketplace; the two marketplaces are fully independent | Only the **active set's** icon is shown (default = the first-registered candidate, no core preference); inactive sets are hidden |
339
+ | Settings page | No notion of slots | Shows a "Plugin Marketplace" role group (2 candidates) + a switch button |
340
+ | User switching | None β€” click whichever you want | Switch to your Map Store β†’ the icon/open behavior all become yours, persisted across restarts |
341
+ | Data | The same `pluginManager.*` API, each building its own UI | The same data, with the UI swapped for the active set |
342
+
343
+
344
+ ### The `icon` field in depth
345
+
346
+ The icon appears in the icon bar, the tab bar, the welcome page and the [+] menu β€” the same icon everywhere, rendered uniformly by the `<PluginIcon>` component.
347
+
348
+ **Aligned with VS Code:** icon files sit inside the plugin's own directory, and the `icon` field just names the file.
349
+
350
+ **Three ways to specify an icon:**
351
+
352
+ | Way | `icon` value | `iconSource` | File location |
353
+ |------|-----------|-------------|---------|
354
+ | Built-in codicon | `"package"` | Omit (defaults to `"codicon"`) | No file needed β€” the built-in codicon font |
355
+ | Built-in Lucide icon | `"FolderTree"` | `"lucide"` | No file needed β€” the shell's built-in Lucide icon set (whitelist in PluginIcon's `LUCIDE_MAP`: FolderTree/Folder/File/Package and so on) |
356
+ | Custom SVG / PNG | `"resources/icon.svg"` | Omit | `<plugin directory>/resources/icon.svg` (the `resources/` subdirectory is recommended) |
357
+ | Custom PNG (no extension) | `"resources/icon"` | Omit | `<plugin directory>/resources/icon.png` (`.png` is appended automatically) |
358
+ | External URL | `"https://..."` | `"url"` | Any reachable URL |
359
+
360
+ **Examples:**
361
+
362
+ ```json
363
+ // Built-in codicon β€” zero files, just write the codicon name
364
+ { "icon": "package" }
365
+
366
+ // Custom SVG β€” recommended; vectors stay sharp and fill="currentColor" follows the theme
367
+ { "icon": "resources/icon.svg" }
368
+ // Put the file in the plugin directory: my-plugin/resources/icon.svg
369
+
370
+ // Custom PNG β€” a bitmap, may look blurry at multiple sizes
371
+ { "icon": "resources/icon.png" }
372
+ // Put the file in the plugin directory: my-plugin/resources/icon.png
373
+
374
+ // External URL
375
+ { "icon": "https://example.com/icon.svg", "iconSource": "url" }
376
+ ```
377
+
378
+ > **SVG + `fill="currentColor"` is recommended:** one file fits every size (24px in the icon bar, 14px in the tab bar, 24px/16px on the welcome page) and recolors automatically for light/dark themes. PNG gets blurry when scaled up and is not recommended.
379
+
380
+ ### When an icon appears in the icon bar (appearsIn.iconBar)
381
+
382
+ > **opt-IN β€” without declaring `appearsIn.iconBar` there is no icon of yours in the icon bar.** The old `iconLocation` default of `"top"` (opt-OUT β€” the editor got squeezed into the icon bar even without declaring anything) has been deprecated; it is now controlled declaratively by `appearsIn.iconBar` (`"top"` = the upper icon group, `"bottom"` = the fixed bottom group).
383
+
384
+ **Two paths to an icon:**
385
+
386
+ | Path | Prerequisite | Description |
387
+ |------|------|------|
388
+ | **Has an `entry`** | `entry` + `appearsIn.iconBar` | The classic form β€” the entry component registers into viewRegistry, giving an icon + openable as a tab |
389
+ | **entryless** | **No `entry`** + `contributes.viewsContainers` containing a sidebar container + `appearsIn.iconBar` | The simplest path for sidebar-only plugins β€” **no need to write a dummy `src/index.tsx`**. The shell registers a component-less entry and the icon still appears |
390
+
391
+ **Who does not get an icon:**
392
+ - **Data plugins** (zero sidebar containers, e.g. a language pack) β€” deliberately not shown. Gated by `pluginRole: "data"`, so nobody is forced to write an empty shell just to get an icon
393
+ - **Pure panel / auxiliarybar containers** β€” the icon bar's semantics are "open a sidebar container", and panel / auxiliarybar do not count
394
+ - **entryless plugins are never tabs** β€” `appearsIn.tabBar: true` must be paired with `entry` (tab rendering depends on the entry component)
395
+
396
+ **Minimal entryless sidebar plugin β€” zero index.tsx:**
397
+
398
+ ```json
399
+ {
400
+ "name": "Sidebar Tools",
401
+ "icon": "globe",
402
+ "appearsIn": { "iconBar": "top" },
403
+ "contributes": {
404
+ "viewsContainers": {
405
+ "my-sidebar": { "title": "Sidebar Tools", "location": "sidebar" }
406
+ },
407
+ "views": {
408
+ "my-sidebar": [
409
+ { "id": "main", "title": "Main View", "render": "src/views/MainView.tsx", "order": 0 }
410
+ ]
411
+ }
412
+ }
413
+ }
414
+ ```
415
+
416
+ Views are loaded by ViewContainerService from `contributes.views[].render`, and the icon goes through the shell's component-less registration path. **For a sidebar-only plugin to get an icon = `appearsIn.iconBar` + a sidebar `viewsContainers`, with no `entry` and no `src/index.tsx` needed**; **only plugins that need tabs need `entry`**.
417
+
418
+ ### The `contributes` field (Phase 5+) β€” aligned with VS Code
419
+
420
+ > **Once a plugin declares `contributes`, the system wires it up automatically β€” no core code changes needed.**
421
+
422
+ #### contributes.configuration β€” plugin settings appear automatically in the Settings Editor
423
+
424
+ After installation, the Settings Editor's left-hand tree automatically gains a group and the right-hand side renders a form automatically. **No hand-written settings UI required.**
425
+
426
+ ```json
427
+ {
428
+ "contributes": {
429
+ "configuration": {
430
+ "title": "CAD Viewer",
431
+ "properties": {
432
+ "cad.gridSize": {
433
+ "type": "number",
434
+ "default": 10,
435
+ "minimum": 1,
436
+ "maximum": 100,
437
+ "description": "Grid size (mm)"
438
+ },
439
+ "cad.units": {
440
+ "type": "string",
441
+ "default": "mm",
442
+ "enum": ["mm", "cm", "inch"],
443
+ "description": "Units"
444
+ },
445
+ "cad.darkThemeOverride": {
446
+ "type": "boolean",
447
+ "default": false,
448
+ "description": "Force a dark view"
449
+ }
450
+ }
451
+ }
452
+ }
453
+ }
454
+ ```
455
+
456
+ **Supported types:** `"string"` | `"number"` | `"boolean"` | `"integer"`
457
+ **Supported constraints:** `enum` (dropdown list) | `minimum` / `maximum` (numeric range) | `default` (default value)
458
+
459
+ **Reading settings from plugin code (through `window.linkdesk.configuration` β€” an iron rule of plugin communication; `import @src/core/...` is forbidden):**
460
+ ```typescript
461
+ function CadView() {
462
+ const [gridSize, setGridSize] = useState<number | undefined>(10);
463
+
464
+ useEffect(() => {
465
+ window.linkdesk.configuration.get<number>("cad.gridSize").then(setGridSize);
466
+ return window.linkdesk.configuration.onChange<number>("cad.gridSize", setGridSize);
467
+ }, []);
468
+ // The user changes the value in the Settings Editor β†’ onChange callback β†’ the component re-renders automatically
469
+ }
470
+ ```
471
+
472
+ #### contributes.commands β€” plugin-registered commands that appear in the command palette
473
+
474
+ ```json
475
+ {
476
+ "contributes": {
477
+ "commands": [
478
+ {
479
+ "id": "cad.importDxf",
480
+ "title": "Import DXF…",
481
+ "category": "CAD"
482
+ },
483
+ {
484
+ "id": "cad.exportPdf",
485
+ "title": "Export PDF…",
486
+ "category": "CAD",
487
+ "when": "activeEditor == 'cad'"
488
+ }
489
+ ]
490
+ }
491
+ }
492
+ ```
493
+
494
+ **`when` conditions:** evaluated in real time by the Phase 5 ContextKeyService. Expression syntax:
495
+
496
+ | Operator | Example | Meaning |
497
+ |--------|------|------|
498
+ | bare key | `portOpen` | the key's value is truthy β†’ true |
499
+ | `!` | `!portOpen` | negation |
500
+ | `&&` | `activeEditor == 'terminal' && portOpen` | logical AND |
501
+ | `\|\|` | `activeEditor == 'a' \|\| activeEditor == 'b'` | logical OR |
502
+ | `==` | `activeEditor == 'terminal'` | equals (value comparison) |
503
+ | `!=` | `editorCount != 0` | not equals |
504
+ | `in [a, b]` | `activeEditor in ['terminal', 'cad']` | set membership |
505
+ | `()` | `!(portOpen \|\| editorCount > 1)` | grouping |
506
+
507
+ **Available context keys:**
508
+
509
+ | Key | Type | Description | Written by |
510
+ |-----|------|------|--------|
511
+ | `activeEditor` | `string \| null` | The pluginId of the currently focused tab | App.tsx (on tab switch) |
512
+ | `portOpen` | `boolean` | Whether the serial port is open | App.tsx (on serial port open/close) |
513
+ | `portName` | `string \| null` | The current serial port name, e.g. `"COM3"` | App.tsx (on serial port open/close) |
514
+ | `editorCount` | `number` | The total number of open tabs | App.tsx (on tab add/remove) |
515
+ | `editorHasSelection` | `boolean` | Whether the editor has selected text | Reserved (Phase 6 CM6 selection listener) |
516
+
517
+ > **Rule for writing `when`: every plugin command should declare a `when`.** Omitting `when` = visible in every context β€” the command would show up in the command palette even on multi-tab pages, confusing the user.
518
+
519
+ #### contributes.menus β€” plugins declaring context menu items
520
+
521
+ ```json
522
+ {
523
+ "contributes": {
524
+ "menus": {
525
+ "editorContext": [
526
+ "cad.importDxf",
527
+ "cad.exportPdf"
528
+ ],
529
+ "tabContext": [
530
+ { "command": "cad.closeAll", "when": "activeEditor == 'cad'" }
531
+ ]
532
+ }
533
+ }
534
+ }
535
+ ```
536
+
537
+ **Available menu IDs:** `editorContext` (right-click inside tab content) | `tabContext` (right-click on the tab bar) | `fileContext` (right-click in the file tree, Phase 6) | `cardContext` (right-click on a card, Phase 7) | MenuId is an open string (`menuBar` / any newly registered point)
538
+
539
+ **Menu item fields:** `command` (command ID; may be empty when `children` is present) | `label` (overrides the command title) | `group` | `when` | `order` (ordering within the same group) | `children` (nested submenus, **recursive to any depth** β€”). See `03-contributes-spec.md Β§3.2`.
540
+
541
+ **Menu positions (MenuId) are defined by the framework; you only decide what command goes where.** The framework registers built-in items of its own β€” "Close" and "Split" belong to the framework, "Clear" and "Pause" to the terminal plugin, "Import DXF" to the CAD plugin. The menu a user sees on right-click = framework built-ins + terminal + CAD + your plugin β€” many contributors, merged at render time.
542
+
543
+ #### contributes.keybindings β€” plugins declaring keyboard shortcuts
544
+
545
+ ```json
546
+ {
547
+ "contributes": {
548
+ "keybindings": [
549
+ {
550
+ "command": "cad.importDxf",
551
+ "key": "ctrl+shift+i",
552
+ "when": "activeEditor == 'cad'"
553
+ }
554
+ ]
555
+ }
556
+ }
557
+ ```
558
+
559
+ ---
560
+
561
+ ### The `tabBehavior` field
562
+
563
+ ```json
564
+ {
565
+ "tabBehavior": {
566
+ "isFallback": false,
567
+ "singleton": false,
568
+ "confirmOnClose": "Closing this tab will disconnect the serial port"
569
+ }
570
+ }
571
+ ```
572
+
573
+ | Property | Type | Description |
574
+ |---|---|---|
575
+ | `isFallback` | `boolean` | Automatically creates this tab when no tab is present, and it cannot be closed. Only the welcome page declares it |
576
+ | `singleton` | `boolean` | Only one instance is allowed globally; creating another β†’ focuses the existing one. E.g. the settings page |
577
+ | `confirmOnClose` | `string` | Shows a confirmation dialog before closing, with this value as the prompt text. E.g. the terminal |
578
+
579
+ ### `statusBar` entries
580
+
581
+ ```json
582
+ {
583
+ "statusBar": [
584
+ { "id": "connection", "icon": "circle-filled", "label": "COM3 connected", "align": "left" },
585
+ { "id": "txrx", "label": "TX:0 RX:0", "align": "left" }
586
+ ]
587
+ }
588
+ ```
589
+
590
+ | Property | Type | Description |
591
+ |---|---|---|
592
+ | `id` | `string` βœ… | Unique identifier |
593
+ | `icon` | `string` | codicon name or SVG path |
594
+ | `label` | `string` | Display text |
595
+ | `align` | `string` | `"left"` (default) / `"right"` |
596
+ | `onClick` | `string` | Click behavior β€” a command name |
597
+
598
+ ---
599
+
600
+ ## Directory structure conventions
601
+
602
+ ```
603
+ plugins/<pluginId>/ ← repo source tree (flat single root; directory name = plugin ID)
604
+ {userData}/plugins/<pluginId>/ ← installed state (where the .linkdesk-plugin zip is extracted)
605
+ ```
606
+
607
+ `<pluginId>` = folder name = the plugin's unique identifier (the only source of identity β€” the loader derives pluginId from the directory name; the schema has no top-level pluginId field). Naming rules:
608
+ - lowercase English + hyphens: `gps-map`, `protocol-sbq`, `theme-dracula`
609
+ - no app name, no version number: `terminal`, not `v3-terminal`
610
+
611
+ > The complete directory structure (what goes in `resources/` / `src/utils/` / `__tests__/`, naming conventions) is in `09-plugin-directory-layout.md`.
612
+
613
+ ---
614
+
615
+ ## Validation rules
616
+
617
+ The loader validates `plugin.json` (the `type` field takes no part in validation β€” it is deprecated; the loader detects types automatically from the declared fields):
618
+
619
+ **Install time (intercepted before extracting into `{userData}/plugins/<id>/`):**
620
+ 1. **Missing `plugin.json`** β†’ installation fails (not a valid plugin)
621
+ 2. **Malformed JSON** β†’ installation fails, with an error message
622
+ 3. **`validateInstallManifest` validation** (pluginId/version/name resolvable) β†’ fails before copying if invalid
623
+
624
+ **Load time (startup scan + runtime loads):**
625
+ 1. **File does not exist** β†’ skip that directory, log it
626
+ 2. **Malformed JSON** β†’ skip, notify the user with a toast
627
+ 3. **A view plugin missing `entry` / whose entry file does not export a default component** β†’ skip, toast (does not block other plugins)
628
+ 4. **`minAppVersion` higher than the current version** β†’ skip, marked "needs upgrade"
629
+ 5. **Duplicate plugin with the same name** β†’ the higher version wins, toast notification
630
+
631
+ A plugin that fails any validation does not block other plugins from loading.
632
+
633
+ ---
634
+
635
+ ## Related
636
+
637
+ - `04-distribution-format.md` β€” distribution/installation/version compatibility
638
+ - `09-plugin-directory-layout.md` β€” source directory structure and naming conventions
639
+ - [Third-party author journey](https://github.com/Encaron/linkdesk/blob/electron/docs/02-ElectronζžΆζž„/E6_ζ’δ»Άη”Ÿζ€δΈŽε‘εΈƒ/05-ζ–‡ζ‘£δΈŽε‘εΈƒ/00-η¬¬δΈ‰ζ–Ήδ½œθ€…ζ—…η¨‹.md) β€” the complete path from zero to publication
640
+ - `plugin.schema.json` β€” the JSON Schema file in the same directory (the authoritative version, one of the three-copy gate)