@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,800 @@
1
+ # 03 — Plugin contributes Specification
2
+
3
+ > 2026-07-24 · full rewrite 2026-08-21 · **2026-09-06 reconciled against the implementation** (the contributes surface carries no directory/distribution semantics; a section-by-section review found zero flattening residue, kept as-is). **The `contributes` field of plugin.json — a plugin declaring "what I can do".** Mirrors VS Code's `package.json` contributes. The shell wires everything up for you — without changing any core code.
4
+ > Source of truth: `src/pluginLoader/contributions.ts` (parseContributions — 13 shell-side consumption points) + `electron/plugins/plugin-manifest-loader.ts` (2 main-process consumption points) + `public/schemas/plugin.schema.json` (IDE validation).
5
+
6
+ ---
7
+
8
+ ## 1. Core principles
9
+
10
+ **A plugin declares → the shell wires it up.** Declare `contributes.configuration` and the Settings Editor gains a group. Declare `contributes.commands` and Ctrl+Shift+P gains an entry.
11
+
12
+ **The shell is never told what your plugin does.** All the shell knows is "some plugin registered these commands/menus/keybindings/settings" — not "this is a CAD plugin or a map plugin".
13
+
14
+ ---
15
+
16
+ ## 2. All contribution points
17
+
18
+ > Consumers live in two places: the **shell side** (`parseContributions`, where plugin code runs) and the **main process** (`plugin-manifest-loader`, which scans the disk at startup and rescans the three tables on install/uninstall).
19
+
20
+ ### Shell-side consumers (14)
21
+
22
+ | Contribution point | Status | Description | Shell consumer |
23
+ |------|:--:|------|------|
24
+ | `commands` | ✅ | register commands → command palette/context menus/keybindings | CommandRegistry |
25
+ | `menus` | ✅ | register menu items → context menus/gear menu/menu bar | MenuRegistry |
26
+ | `keybindings` | ✅ | register keybindings | KeybindingRegistry |
27
+ | `configuration` | ✅ | register settings → rendered automatically in the Settings Editor | ConfigurationRegistry |
28
+ | `configurationDefaults` | ✅ | weak defaults — a value set by the user wins | ConfigurationRegistry |
29
+ | `themes` | ✅ | register themes → theme browser/appearance | ThemeRegistry (data loaded asynchronously) |
30
+ | `iconThemes` | ✅ | register icon themes → users switch icon sets | IconRegistry |
31
+ | `icons` | ✅ | shared icons — plugin A contributes, plugin B references | IconRegistry |
32
+ | `languages` | ✅ | register UI language packs | LanguageRegistry (data loaded asynchronously) |
33
+ | `titleBar` | ✅ | top bar left/right slot buttons | MenuRegistry |
34
+ | `viewsContainers` | ✅ | declare sidebar/panel containers | ViewContainerService |
35
+ | `views` | ✅ | register views in a container — any plugin can register in any container | ViewContainerService |
36
+ | `floatingPanel` | ✅ | declare that a view can be shown in a shell-internal floating panel (type B) — `viewId` references an already-registered view; without the declaration there is no "Open in Floating Panel" context menu item | declaration addressing → FloatingPanelService |
37
+ | `i18n` | ✅ | plugin-bundled translation files | i18nResources (i18next namespace) |
38
+
39
+ ### Main-process consumers (2)
40
+
41
+ | Contribution point | Status | Description | Consumer |
42
+ |------|:--:|------|------|
43
+ | `langDefs` | ✅ | **programming language declarations** (ID/extensions/syntax highlighting/LSP) — the main process is the only writer | main-process LangDefRegistry (shell-side registration removed) |
44
+ | `fileAssociations` | ✅ | file extension → plugin routing | main-process FileAssociationService (shell-side registration removed) |
45
+
46
+ ### Top-level fields (not contributes, but often mistaken for it)
47
+
48
+ | Field | Description |
49
+ |------|------|
50
+ | `statusBar` | **status bar entries — a top-level field**, not contributes.statusBar (mirrors the VS Code status bar extension point that lives outside `contributes.views`) |
51
+ | `tabBehavior` | tab behavior (singleton/isFallback/confirmOnClose/identityField) — see `02 §6` |
52
+ | `appearsIn` | where the plugin's UI appears (iconBar/sidePanel/tabBar/statusBar) — replaces the old iconLocation/viewRole |
53
+ | `requires` | plugin-level activation-order dependency (a string array) — see `02 §4` |
54
+ | `factoryRole` | system slot (settings = settings page / marketplace = plugin marketplace) — **fill it in = form two (replacement/slot switching); leave it out = form one (a normal view plugin coexisting)**, see `06 §factoryRole field details`. **Multiple plugins in the same role already coexist**: same-role plugins legally coexist (one-to-many), the default is the first registered in stable order (core:true has no behavioral privilege and does not claim the default), the settings page groups by role + a switch button + the active set occupies the slot, and the active set is persisted and kept across restarts |
55
+ | `pluginRole` | load strategy (view/data) — derived automatically when absent, see `02 §2.1` |
56
+
57
+ ### ❌ Non-existent / removed fake points
58
+
59
+ | Contribution point | Status |
60
+ |------|------|
61
+ | `cards` | **removed** — CardRegistry was deleted wholesale, and the card workbench is a plugin (hard constraint 3). **Writing it has no effect** |
62
+ | `protocols` | **a fake point** — `contributes.protocols` has no consumer. Protocol parsing goes through the `serial.onData` data pipeline + `ProtocolParser` (a whitelisted tool), not through a contributes declaration |
63
+ | `aiFunctions` | never implemented |
64
+
65
+ ---
66
+
67
+ ## 3. Contribution points in detail
68
+
69
+ ### 3.1 `contributes.commands` — commands
70
+
71
+ ```json
72
+ {
73
+ "contributes": {
74
+ "commands": [
75
+ {
76
+ "id": "cad.importDxf",
77
+ "title": "Import DXF…",
78
+ "category": "CAD",
79
+ "when": "activeEditor == 'cad'"
80
+ }
81
+ ]
82
+ }
83
+ }
84
+ ```
85
+
86
+ | Field | Required | Description |
87
+ |------|:--:|------|
88
+ | `id` | ✅ | command ID. Naming: `<pluginId>.<action>`, e.g. `terminal.copy` |
89
+ | `title` | ✅ | display name (an i18n key — the original Chinese text) |
90
+ | `category` | ❌ | command palette grouping — "CAD" / "Terminal" / "File" |
91
+ | `when` | ❌ | context key when condition. Without `when` the command is visible in any context |
92
+
93
+ **Declaring registers metadata (a placeholder):** `contributes.commands` only registers command metadata (id/title/category/when); **the real handler is registered on the pool side** (pool-side `_poolCommands` wins). A command whose handler was never registered is a no-op when invoked (with a diagnostic warn).
94
+
95
+ ```typescript
96
+ // register the real handler on the pool side (when the component mounts)
97
+ useEffect(() => {
98
+ window.linkdesk.commands.registerCommand("cad.importDxf", async () => {
99
+ const paths = await window.linkdesk.dialog.openFile({ filters: [{ name: "DXF files", extensions: ["dxf"] }] });
100
+ // ...
101
+ });
102
+ }, []);
103
+ ```
104
+
105
+ ### 3.2 `contributes.menus` — menu items
106
+
107
+ ```json
108
+ {
109
+ "contributes": {
110
+ "menus": {
111
+ "editorContext": [
112
+ "cad.importDxf",
113
+ { "command": "cad.exportPdf", "when": "activeEditor == 'cad'", "group": "edit" }
114
+ ],
115
+ "tabContext": [
116
+ { "command": "cad.closeAll", "when": "activeEditor == 'cad'" }
117
+ ]
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ **MenuId is an open string (`MenuRegistry` `type MenuId = string`) — a plugin declaring any string makes it a contract, with no shell code needed.** The shell's built-in registration points (the MENU_SLOTS constant table, 14 slots):
124
+
125
+ | MenuId | Scenario |
126
+ |------|------|
127
+ | `commandPalette` | the Ctrl+Shift+P command palette |
128
+ | `tabContext` | right-click on a tab in the tab bar |
129
+ | `panelViewContext` | right-click on the panel tab bar (position/alignment submenu + view visibility list) |
130
+ | `editorContext` | right-click in a tab's main content area |
131
+ | `extensionGear` | the bottom gear menu (settings/command palette/theme picker) |
132
+ | `marketplaceItemGear` | the gear on a marketplace item (enable/disable/uninstall) |
133
+ | `menuBar` | the ☰ hamburger menu bar |
134
+ | `panel` | merging into the "Panel" group of the menu bar (the shell's own entry has been removed — plugin items with `group:"panel"` are still merged into the menu bar as their own group) |
135
+ | `fileContext` | right-click in the file tree |
136
+ | `cardContext` | right-click on a card |
137
+ | `quickSendContext` | right-click on a quick-send pill |
138
+ | `iconBar` | right-click on the icon bar |
139
+ | `settingItemGear` | the gear on a setting row (on row hover in the Settings Editor) |
140
+ | `viewTitleContext` | right-click on a sidebar view title (collapse/reset position/views in the same group) |
141
+
142
+ **Menu item fields:**
143
+
144
+ | Field | Required | Description |
145
+ |------|:--:|------|
146
+ | `command` | ✅ | command ID — may be an empty string when `children` is present (a parent item executes no command, it expands a submenu) |
147
+ | `label` | ❌ | display label — when present it overrides the command title `getCommand(id).title`; required for a parent item (one with no `command`) |
148
+ | `group` | ❌ | grouping — items in the same group are clustered together, groups are separated by a divider. e.g. `"navigation"` / `"edit"` / `"delete"` |
149
+ | `when` | ❌ | context key when condition |
150
+ | `order` | ❌ | sort weight — within a group, smaller comes first |
151
+ | `children` | ❌ | nested submenus — **recursion of arbitrary depth** (mirrors VS Code's `SubmenuAction`); children are homogeneous (`children` can nest further `children`) |
152
+
153
+ **Shorthand:** a bare command-ID string = `{ "command": "<id>" }`
154
+
155
+ **Nested submenu example (any depth):**
156
+ ```json
157
+ {
158
+ "contributes": {
159
+ "menus": {
160
+ "menuBar": [
161
+ { "command": "", "label": "View", "group": "view", "children": [
162
+ { "command": "cad.importDxf", "group": "view" },
163
+ { "command": "", "label": "Interface", "group": "view", "children": [
164
+ { "command": "cad.togglePanel", "label": "Panel", "group": "view" }
165
+ ] }
166
+ ] }
167
+ ]
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ ### 3.3 `contributes.keybindings` — keybindings
174
+
175
+ ```json
176
+ {
177
+ "contributes": {
178
+ "keybindings": [
179
+ { "command": "cad.importDxf", "key": "ctrl+shift+i", "when": "activeEditor == 'cad'" },
180
+ { "command": "cad.exportPdf", "key": "ctrl+shift+e", "when": "activeEditor == 'cad'" }
181
+ ]
182
+ }
183
+ }
184
+ ```
185
+
186
+ | Field | Required | Description |
187
+ |------|:--:|------|
188
+ | `command` | ✅ | command ID |
189
+ | `key` | ✅ | key sequence — `"ctrl+k"` / `"ctrl+shift+p"` / `"ctrl+k ctrl+o"` (a chord) |
190
+ | `when` | ❌ | context key when condition |
191
+
192
+ **⚠️ Track selection (`05 §4`):** only put **non-text keys** in `contributes.keybindings`. Writing text-editing keys such as `ctrl+c` / `ctrl+v` / `f2` here makes the main process's `before-input-event` unconditionally swallow input in every pool text field. The right way to bind text keys / focus-bound keys is a pool-side container `onKeyDown` (DOM focus partitions naturally).
193
+
194
+ ### 3.4 `contributes.configuration` — settings
195
+
196
+ ```json
197
+ {
198
+ "contributes": {
199
+ "configuration": {
200
+ "title": "CAD Viewer",
201
+ "properties": {
202
+ "cad.gridSize": {
203
+ "type": "number",
204
+ "default": 10,
205
+ "description": "Grid size (mm)"
206
+ },
207
+ "cad.units": {
208
+ "type": "string",
209
+ "default": "mm",
210
+ "enum": ["mm", "cm", "inch"],
211
+ "enumDescriptions": ["Millimeters", "Centimeters", "Inches"],
212
+ "description": "Units"
213
+ },
214
+ "cad.autoSave": {
215
+ "type": "boolean",
216
+ "default": true,
217
+ "description": "Auto save"
218
+ },
219
+ "cad.showGrid": {
220
+ "type": "object",
221
+ "default": { "enabled": true, "color": "#555" },
222
+ "description": "Grid appearance (object)"
223
+ },
224
+ "cad.exportFormats": {
225
+ "type": "array",
226
+ "default": ["dxf", "stl"],
227
+ "description": "List of exportable formats"
228
+ }
229
+ }
230
+ }
231
+ }
232
+ }
233
+ ```
234
+
235
+ **Supported types (the full schema):** `"string"` | `"number"` | `"boolean"` | `"object"` | `"array"`
236
+
237
+ > **Note:** there is no `"integer"` — use `"number"`. `minimum`/`maximum` are supported at runtime but are not declared in the schema yet (the IDE will flag them) — advanced usage is allowed, and loading does not validate.
238
+
239
+ **Fields:**
240
+
241
+ | Field | Required | Description |
242
+ |------|:--:|------|
243
+ | `type` | ✅ | string/number/boolean/object/array |
244
+ | `default` | ✅ | default value |
245
+ | `description` | ✅ | description — rendered as a hint by the Settings Editor |
246
+ | `enum` | ❌ | dropdown options (optional for the string type) |
247
+ | `enumDescriptions` | ❌ | option descriptions — one-to-one with enum |
248
+ | `uiHint` | ❌ | rendering hint — SettingsView picks the control from the hint (known values include `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"`; it is an open string — an unknown hint degrades to the default rendering for the type). `"segmented"` = a segmented single-select (the ghost dual-track scheme, declared together with `enum` + `enumDescriptions`; the short label = the part of the enumDescription before `—`, the tooltip = the whole line) |
249
+ | `group` | ❌ | **a second-level heading inside the group** — keys sharing the same `group` value are rendered under a subheading on the settings page; keys without a `group` stay flat. Declaring a Chinese section name is enough for it to display; heading text goes through i18n (the plugin's `contributes.i18n` provides the translation). Zero shell changes — the shell mechanism works exactly the same for plugin keys |
250
+
251
+ **Effect after installation:** the Settings Editor's left navigation tree automatically gains a "CAD Viewer" group → the form is rendered automatically on the right — no hand-written settings UI needed.
252
+
253
+ **Key naming rule:** `<pluginId>.<property>`, e.g. `cad.gridSize`, `terminal.baudRate`
254
+
255
+ **Reading settings from a plugin (the plugin communication iron rule — only through `window.linkdesk.configuration`):**
256
+ ```typescript
257
+ const gridSize = await window.linkdesk.configuration.get<number>("cad.gridSize");
258
+ // or subscribe to changes
259
+ useEffect(() => {
260
+ return window.linkdesk.configuration.onChange<number>("cad.gridSize", (val) => {
261
+ // the user changes the value in the Settings Editor → notified automatically
262
+ });
263
+ }, []);
264
+ ```
265
+
266
+ ### 3.5 `contributes.configurationDefaults` — weak defaults
267
+
268
+ ```json
269
+ {
270
+ "contributes": {
271
+ "configurationDefaults": {
272
+ "terminal.baudRate": 115200,
273
+ "terminal.encoding": "utf-8"
274
+ }
275
+ }
276
+ }
277
+ ```
278
+
279
+ The difference from `configuration`: `configuration` defines **your own** settings. `configurationDefaults` suggests values for **someone else's** settings. A value set by the user wins — a weak default only applies when the user has never set that key.
280
+
281
+ ### 3.6 `contributes.themes` — themes
282
+
283
+ ```json
284
+ {
285
+ "contributes": {
286
+ "themes": [
287
+ { "id": "my-theme-dark", "label": "My Theme Dark", "uiTheme": "dark", "path": "themes/my-dark.json" }
288
+ ]
289
+ }
290
+ }
291
+ ```
292
+
293
+ | Field | Required | Description |
294
+ |------|:--:|------|
295
+ | `id` | ✅ | theme ID |
296
+ | `label` | ✅ | display name |
297
+ | `uiTheme` | ✅ | `"dark"` \| `"light"` \| `"highContrast"` |
298
+ | `path` | ✅ | path to the theme definition JSON file (`appearance` + `colorways[]`) — **relative to the plugin directory** |
299
+
300
+ The declaration is metadata-only; theme color data is fetched asynchronously at load time. A legacy top-level `themes` field is normalized automatically (see `02 §2.1`).
301
+
302
+ > **🔥 Recipe JSON contract (now folded into plugin-sdk)**: the recipe file that `path` points to is validated against `theme.schema.json` — inside the repo that is `public/schemas/theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, and a format error turns the light red with exit 1 on the spot instead of staying silent); for npm authors it is the `schemas/theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateThemeJson` (the same schema file, so the rules never drift). At runtime, a `parseThemeRecipe` toast is the second line of defense. Theme files should begin with `"$schema"` pointing at the schema to get editor IntelliSense (for the npm path see [11-authoring-themes](11-authoring-themes.md) §②).
303
+
304
+ ### 3.7 `contributes.iconThemes` — icon themes
305
+
306
+ ```json
307
+ {
308
+ "contributes": {
309
+ "iconThemes": [
310
+ { "id": "my-icons", "label": "My Icons", "path": "icons/icon-theme.json" }
311
+ ]
312
+ }
313
+ }
314
+ ```
315
+
316
+ Mirrors VS Code's `productIconThemes`. Same fields as themes (id/label/path). **The mappings JSON has two forms** — each entry picks one:
317
+
318
+ ```json
319
+ {
320
+ "files": {
321
+ "readme.md": { "class": "codicon codicon-markdown" },
322
+ "main.rs": { "class": "myfont myfont-rust", "color": "#dea584" },
323
+ "logo.svg": { "imagePath": "icons/logo.svg" }
324
+ },
325
+ "extensions": { ".ts": { "class": "codicon codicon-typescript" } },
326
+ "folders": { "src": { "class": "codicon codicon-folder" } },
327
+ "foldersExpanded": { "src": { "class": "codicon codicon-folder-opened" } }
328
+ }
329
+ ```
330
+
331
+ | Form | Fields | Rendering | Description |
332
+ |------|------|------|------|
333
+ | **font glyph** | `class` (required) + `color?` (optional) | `<span>` | a monochrome/colored font glyph (seti/material are this kind, one color per icon); a custom font goes through `@font-face` (see the `font` section below) |
334
+ | **image asset** | `imagePath` | `<img>` | any multi-color artwork (skeuomorphic/textured); a relative path is resolved by the shell at load time into the absolute `linkdesk://{pluginId}/{path}` URL (zero parsing burden on the consumer) |
335
+
336
+ Both forms can be mixed in one theme. **The picker = the `app.iconTheme` setting** (declared by the shell, default `"default"` = built-in codicon fallback, so the system works even with zero icon-theme plugins; the enum = registered icon themes + default, refreshed dynamically on install/uninstall). Switching is broadcast through the `iconTheme:changed` event (payload + contract in the `01-plugin-api-contract.md` §3.2 shell broadcast event table) — **plugins that need a custom file-icon visual subscribe and apply it themselves**.
337
+
338
+ **Optional top-level `font` section (custom icon fonts)** — declare it when a `class` references a glyph from a custom font; the shell generates the @font-face broadcast into the pool + injects the glyph class CSS, so the author carries zero @font-face burden:
339
+
340
+ ```json
341
+ {
342
+ "font": {
343
+ "path": "icons/fonts/my-icons.woff2",
344
+ "family": "my-icons",
345
+ "glyphs": "icons/my-icons.css"
346
+ },
347
+ "files": { "main.rs": { "class": "my-icons my-icons-rust", "color": "#dea584" } }
348
+ }
349
+ ```
350
+
351
+ | `font` field | Type | Description |
352
+ |------|------|------|
353
+ | `path` | string (required) | relative path to the font asset (or an absolute URL) — the shell resolves `linkdesk://` + generates `@font-face` |
354
+ | `family` | string (required) | font family name — this is what the `font-family` in the glyph CSS writes |
355
+ | `glyphs` | string (optional) | relative path to the glyph class CSS file (`@font-face` must **not** be written inside it — the shell already generates it; write only `.my-icons-x::before{content:"…"}`) |
356
+
357
+ No `font` section → zero custom fonts (codicon fallback / a pure image-asset theme). Font injection is transparent to consumers (handled by the preload mechanical layer), no manual subscription needed.
358
+
359
+ **Top-level default icon five keys (aligned with VS Code's iconTheme top-level keys)** — when the mapping tables (files/extensions/folders/foldersExpanded) do not match, the theme default is used instead of the codicon fallback; entries use the same two forms:
360
+
361
+ ```json
362
+ {
363
+ "file": { "imagePath": "icons/material/file.svg" },
364
+ "folder": { "imagePath": "icons/material/folder.svg" },
365
+ "folderExpanded": { "imagePath": "icons/material/folder-open.svg" },
366
+ "rootFolder": { "imagePath": "icons/material/folder-root.svg" },
367
+ "rootFolderExpanded": { "imagePath": "icons/material/folder-root-open.svg" }
368
+ }
369
+ ```
370
+
371
+ > **🔥 mappings JSON contract (established — icon-theme.schema.json rewritten to align with the engine's normalizeIconThemeMappings)**: the mappings file that `path` points to is validated against `icon-theme.schema.json` — inside the repo that is `public/schemas/icon-theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, which also scans `contributes.iconThemes`); for npm authors it is the `schemas/icon-theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateIconThemeJson` (the same schema file, so the rules never drift). A runtime parse failure with warn/toast is the second line of defense. Files should begin with `"$schema"` pointing at the schema to get editor IntelliSense.
372
+
373
+ ### 3.8 `contributes.icons` — shared icons
374
+
375
+ ```json
376
+ {
377
+ "contributes": {
378
+ "icons": {
379
+ "stm32-chip": {
380
+ "description": "STM32 chip icon",
381
+ "default": { "fontPath": "icons.woff", "fontCharacter": "\\e001" }
382
+ }
383
+ }
384
+ }
385
+ }
386
+ ```
387
+
388
+ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource": "shared"`).
389
+
390
+ ### 3.9 `contributes.languages` — UI language packs + `contributes.i18n` — plugin-bundled translations
391
+
392
+ **Two translation pipelines — don't mix them:**
393
+
394
+ | Pipeline | Declared in | Purpose | Example |
395
+ |------|------|------|------|
396
+ | **UI language pack** | `contributes.languages` | switches the language of the whole UI (global) | Chinese/English/Japanese |
397
+ | **plugin-bundled translations** | `contributes.i18n` | multilingual translations of this plugin's own text (files declared per language code) | `{ "en": "i18n/en.json" }` |
398
+
399
+ ```json
400
+ {
401
+ "contributes": {
402
+ "languages": [
403
+ { "id": "zh", "label": "中文", "path": "lang/zh.json" },
404
+ { "id": "en", "label": "English", "path": "lang/en.json" }
405
+ ],
406
+ "i18n": { "en": "i18n/en.json" }
407
+ }
408
+ }
409
+ ```
410
+
411
+ - In `contributes.i18n` the key = a language code and the value = the path to a JSON translation file (key = the original Chinese text, value = the translation). **No zh.json is needed** — Chinese keys fall back to themselves.
412
+ - Translation files are loaded through `fetchPluginDataFile` (bypassing the Vite glob cache — JSON in a newly installed plugin directory is discovered in real time).
413
+ - The plugin text iron rule: **all UI text goes through `t()`**, and the i18n key is the original Chinese text (`05 §6`).
414
+
415
+ ### 3.10 `contributes.titleBar` — top bar buttons
416
+
417
+ ```json
418
+ {
419
+ "contributes": {
420
+ "titleBar": {
421
+ "right": [
422
+ { "command": "myPlugin.openPanel", "icon": "codicon-graph-line", "when": "myContext" },
423
+ { "command": "myPlugin.runTask", "label": "Run task" },
424
+ { "command": "myPlugin.showStatus", "label": "$myPluginStatus", "when": "myStatusVisible" }
425
+ ]
426
+ }
427
+ }
428
+ }
429
+ ```
430
+
431
+ | Field | Required | Description |
432
+ |------|:--:|------|
433
+ | `command` | ✅ | command ID executed on click |
434
+ | `icon` | ❌ | a codicon icon name or an image path |
435
+ | `label` | ❌ | button text — **when present no icon is rendered** (label wins). A text-only button, whose width adapts to the text |
436
+ | `when` | ❌ | context key when condition — the button is hidden when it is not satisfied |
437
+
438
+ Slots: `left` (left side of the title bar) / `right` (right side).
439
+
440
+ **The two forms of `label`** — distinguished by a **literal prefix**, not by "guessing whether the name looks like a key":
441
+
442
+ | Syntax | Meaning |
443
+ |:--|:--|
444
+ | `"label": "Run task"` | **static text**. It is run through `t()` as an i18n key (in this repo an i18n key is the original Chinese text), and the translation is provided in the plugin's i18n file (§3.9) |
445
+ | `"label": "$myPluginStatus"` | **dynamic text**. What follows `$` is a context key name — the shell takes that key's **current value** as the text, so the button text switches with the key's value (mirrors the idea behind VS Code's `${...}`) |
446
+
447
+ ⚠️ **The dynamic text key is maintained by you**, through `linkdesk.contextKey.set("myPluginStatus", "…")`; when the key does not exist the button displays the literal `$myPluginStatus` (**deliberately conspicuous** — a silent blank is the hardest thing to debug).
448
+
449
+ ⚠️ **The `$` prefix is mandatory:** in this repo i18n keys are not always Chinese (keys such as `EN`/`JSON`/`workspace`/`settings` under an English UI are pure ASCII), so "is this name a live context key?" cannot be determined reliably — without the prefix, another plugin registering a context key with the same name would **silently override** your button text.
450
+
451
+ ⚠️ **The dynamic text value is also an i18n key**: what you `set` should be the original Chinese text (e.g. "运行中"), and the shell still runs it through `t()` ⇒ the English UI follows along. Stuffing a finished translation in directly would bypass the translation layer.
452
+
453
+ ### 3.11 `contributes.viewsContainers` + `contributes.views` — view containers
454
+
455
+ > **Full API documentation: `08-view-container-api.md`** (including the titleActions declaration system, panel.reveal, and runtime metadata updates). Only the field summary is given here.
456
+
457
+ **viewsContainers — declaring sidebar/panel/main-area channels:**
458
+
459
+ ```json
460
+ {
461
+ "contributes": {
462
+ "viewsContainers": {
463
+ "explorer": {
464
+ "title": "Explorer",
465
+ "location": "sidebar",
466
+ "hideIfEmpty": false
467
+ }
468
+ }
469
+ }
470
+ }
471
+ ```
472
+
473
+ | Field | Required | Description |
474
+ |------|:--:|------|
475
+ | `title` | ✅ | the name shown in the sidebar header |
476
+ | `location` | ❌ | `"sidebar"` \| `"panel"` \| `"auxiliarybar"` \| `"main"`. Defaults to `"sidebar"` (sidebar = left / auxiliarybar = right / panel = bottom panel tab bar / main = the main-area tab render surface — contributed only by active factoryRole plugins (the marketplace) through `views."main"[]`, and consumed by the shell's ShellViewRenderer when it resolves plugin-detail-style tabs; it requires a matching `viewsContainers."main"` declaration, see `08-view-container-api.md`) |
477
+ | `hideIfEmpty` | ❌ | hide the container automatically when it has no active view |
478
+ | `order` | ❌ | ordering within the same location. Smaller comes first |
479
+ | `icon` | ❌ | overrides the plugin's own icon |
480
+ | `mergeHeaderWhenSingle` | ❌ | hide the view header when the container has only one view — the title merges into the container header |
481
+
482
+ **views — registering content in a container:**
483
+
484
+ ```json
485
+ {
486
+ "contributes": {
487
+ "views": {
488
+ "explorer": [
489
+ { "id": "folders", "title": "", "render": "src/views/FoldersView.tsx", "order": 0 },
490
+ { "id": "search", "title": "Search", "render": "src/views/SearchView.tsx", "order": 1 }
491
+ ]
492
+ }
493
+ }
494
+ }
495
+ ```
496
+
497
+ | Field | Required | Description |
498
+ |------|:--:|------|
499
+ | `id` | ✅ | unique view ID |
500
+ | `render` | ✅ | component module path — **relative to the plugin directory** |
501
+ | `title` | ❌ | SidebarSection collapse header title. An empty string = no collapse header rendered |
502
+ | `role` | ❌ | `"toolbar"` \| `"section"` — a toolbar sticks to the top and is not overridden by a section |
503
+ | `order` | ❌ | ordering inside the container. Smaller is higher |
504
+ | `collapsed` | ❌ | initially collapsed |
505
+ | `when` | ❌ | context key condition — shown only when satisfied |
506
+ | `canToggleVisibility` | ❌ | ✅ implemented — the user can toggle visibility in the panel switcher / the sidebar "Views" submenu |
507
+ | `canMoveView` | ❌ | ✅ implemented — the user can drag and drop this view into another container |
508
+ | `hideByDefault` | ❌ | ✅ implemented — hidden by default, the user has to turn it on |
509
+ | `singleViewPaneContainerTitle` | ❌ | replaces the container title when there is a single view and the container has `mergeHeaderWhenSingle` |
510
+ | `titleDescription` | ❌ | secondary text next to the title — e.g. `(5 files)` |
511
+ | `showActions` | ❌ | `"always"` \| `"whenExpanded"` \| `"default"` — when the action area is shown |
512
+ | `titleTooltip` | ❌ | title hover tooltip — shows the full title when it is truncated |
513
+ | `minHeight` | ❌ | minimum drag-resize height (px). Default 100 |
514
+ | `titleActions` | ❌ | **the view action area declaration system** — see the subsection below |
515
+
516
+ **Key feature: any plugin** can register a view in someone else's container:
517
+ ```json
518
+ // Git plugin — registers TIMELINE in file-tree's explorer container
519
+ { "contributes": { "views": { "explorer": [{ "id": "timeline", ... }] } } }
520
+ ```
521
+ The file-tree plugin needs zero changes.
522
+
523
+ #### titleActions — the action area on the right of a view header
524
+
525
+ **Mirrors the `[+][🔄][⊟]` on the right of VS Code's view headers / `[+][▾]` in the terminal.** Three widget forms:
526
+
527
+ | Type | Form | Click behavior |
528
+ |------|------|------|
529
+ | `icon` | a single icon button | executes `command` |
530
+ | `dropdown` | a pure dropdown (chevron) | expands the `items` list; clicking an entry executes its `command` |
531
+ | `split` | a main button + dropdown composite | the main button executes `command` (the default action), the chevron on the right expands `items` |
532
+
533
+ **Widget fields:** `id` (unique), `command` (the command ID executed on click), `args` (optional — passed through as the single positional argument of `executeCommand(command, args)`), `icon` (a codicon class name), `title` (tooltip/aria-label), `items` (dropdown/split alternative entries `{ label, command, args }`). **`label`/`title` are i18n keys (the original Chinese text)**.
534
+
535
+ ```json
536
+ {
537
+ "id": "demo-output",
538
+ "title": "Output",
539
+ "render": "src/views/DemoOutputView.tsx",
540
+ "order": 0,
541
+ "titleActions": [
542
+ {
543
+ "type": "split",
544
+ "id": "add-log",
545
+ "command": "panel-demo.addLog",
546
+ "icon": "codicon-add",
547
+ "title": "Add demo log",
548
+ "args": { "level": "info" },
549
+ "items": [
550
+ { "label": "Add info", "command": "panel-demo.addLog", "args": { "level": "info" } },
551
+ { "label": "Add warning", "command": "panel-demo.addLog", "args": { "level": "warn" } }
552
+ ]
553
+ },
554
+ { "type": "icon", "id": "clear-log", "command": "panel-demo.clearLog", "icon": "codicon-clear-all", "title": "Clear output" }
555
+ ]
556
+ }
557
+ ```
558
+
559
+ **Command registration (the source of truth for executing a titleActions command = the pool-side command registry):**
560
+ ```typescript
561
+ useEffect(() => {
562
+ window.linkdesk.commands.registerCommand("panel-demo.addLog", (args) => { addLine(args.level, args.text); });
563
+ }, []);
564
+ ```
565
+ > **`when: "false"` = a purely programmatic command that stays out of the command palette** — titleActions-only commands are declared this way, which keeps them from cluttering Ctrl+Shift+P. The shell's unified renderer `ViewTitleActions.tsx` has two consumers: the panel tab bar (the active view) + the sidebar section collapse header. For a real example see `08 §3`.
566
+
567
+ ### 3.12 `contributes.langDefs` — programming language declarations (main process)
568
+
569
+ > **The only writer is the main process** `plugin-manifest-loader` (disk scan at startup + rescan on install/uninstall). The shell-side `parseContributions` does not consume it. There is nothing for the plugin to manage on the loading side — just declare it.
570
+
571
+ ```json
572
+ {
573
+ "contributes": {
574
+ "langDefs": [
575
+ {
576
+ "id": "python",
577
+ "extensions": [".py", ".pyi"],
578
+ "aliases": ["Python"],
579
+ "monarch": { "tokenizer": { } },
580
+ "lsp": {
581
+ "command": "node",
582
+ "args": ["node_modules/pyright/dist/pyright-langserver.js", "--stdio"]
583
+ }
584
+ }
585
+ ]
586
+ }
587
+ }
588
+ ```
589
+
590
+ | Field | Required | Description |
591
+ |------|:--:|------|
592
+ | `id` | ✅ | language ID — e.g. cpp / python / rust |
593
+ | `extensions` | ✅ | extension list — e.g. `['.cpp', '.cxx', '.h']` |
594
+ | `aliases` | ❌ | aliases — e.g. `['C++', 'C']` |
595
+ | `monarch` | ❌ | a Monarch tokenizer definition (Monaco's built-in syntax highlighting) |
596
+ | `lsp` | ❌ | LSP language server configuration (command/args) |
597
+
598
+ > **`command` = an interpreter or executable name** (e.g. `node` / `clangd` / an absolute path), not a script path — the script path goes first in `args`.
599
+ > **Relative-path arguments in `args` are resolved against the plugin root** (absolutized once at the registration site) — in the example above `node_modules/pyright/dist/pyright-langserver.js` → `<plugin root>/node_modules/pyright/dist/pyright-langserver.js`; flags such as `--stdio` are passed through as-is. **Ship the LSP binary with the plugin**: run `npm install` in the plugin root first, and when the SDK packages the plugin the referenced `node_modules` packages are bundled into the `.linkdesk-plugin` automatically from the `args` references (the shell no longer ships an LSP; the python plugin is a real example).
600
+
601
+ ### 3.13 `contributes.fileAssociations` — file associations (main process)
602
+
603
+ > **The only writer is the main process.** The extension is pointed at the shell — the plugin handles opening it itself.
604
+
605
+ ```json
606
+ {
607
+ "contributes": {
608
+ "fileAssociations": [
609
+ { "extension": "dxf", "command": "cad.openFile", "displayName": "DXF drawing" },
610
+ { "extension": "stl" },
611
+ { "extension": "step" }
612
+ ]
613
+ }
614
+ }
615
+ ```
616
+
617
+ | Field | Required | Description |
618
+ |------|:--:|------|
619
+ | `extension` | ✅ | file extension — **without the dot**, e.g. dxf / stl / step |
620
+ | `command` | ❌ | the command ID executed when opening a file with this extension |
621
+ | `displayName` | ❌ | the display name in the "Open with…" picker |
622
+
623
+ > **The `pluginId` is declared by the top-level `pluginId` field** (it must be written explicitly; do **not** write it under `contributes`). When it is not declared it falls back to "the project directory name" — the fallback path is kept only for legacy third-party plugins outside the repo, and **new plugins always declare it explicitly** (directory names and repository names are free-form, so relying on the fallback means your identity drifts with the name, and none of the five consequences reports an error). See [16-naming-conventions](16-naming-conventions.md).
624
+
625
+ ### 3.14 `statusBar` — status bar entries (a top-level field)
626
+
627
+ ```json
628
+ {
629
+ "statusBar": [
630
+ { "id": "units", "label": "mm", "align": "right" },
631
+ { "id": "zoom", "label": "100%", "align": "right", "onClick": "cad.zoomFit" },
632
+ { "id": "lock", "icon": "codicon-lock", "configurable": true }
633
+ ]
634
+ }
635
+ ```
636
+
637
+ | Field | Required | Description |
638
+ |------|:--:|------|
639
+ | `id` | ✅ | unique identifier |
640
+ | `label` | ❌ | display text |
641
+ | `icon` | ❌ | a codicon name or an SVG path |
642
+ | `align` | ❌ | `"left"` \| `"right"` |
643
+ | `onClick` | ❌ | click behavior — a command name |
644
+ | `configurable` | ❌ | declare `true` → the shell registers the setting automatically + injects the visible prop. The plugin author writes one line of JSON and zero code |
645
+
646
+ **Note:** `statusBar` is a **top-level** field, not `contributes.statusBar`. Place the component at `statusBar.tsx` / `src/statusBar.tsx` / `src/components/statusBar.tsx` (the runtime tries all three paths).
647
+
648
+ ### 3.15 `contributes.floatingPanel` — floating panel declarations
649
+
650
+ > **A shell-internal floating panel (type B)** — the plugin declares that a view can be displayed in a floating panel. The shell resolves the view by declaration addressing (pluginId/renderPath/title), with zero hard-coded plugin IDs (the same consumption style as hard constraints 10/11).
651
+
652
+ ```json
653
+ {
654
+ "contributes": {
655
+ "floatingPanel": { "viewId": "settings" }
656
+ }
657
+ }
658
+ ```
659
+
660
+ | Field | Required | Description |
661
+ |------|:--:|------|
662
+ | `viewId` | ✅ | **a view ID already registered in contributes.views** — declaration addressing resolves the plugin/renderPath/title |
663
+
664
+ **Declaring is consuming — four things appear automatically:**
665
+
666
+ | Effect after declaring | Mechanism |
667
+ |------|------|
668
+ | "Open in Floating Panel" appears in the tab context menu | declaration-driven — it does not appear when undeclared (filtered by declaration) |
669
+ | Three actions inside the panel once it is open (open in main window / maximize / close) | "Open in main window" lands at the end of the currently active group (reusing the file-tree open-placement rule) |
670
+ | `linkdesk.panel.revealFloating(viewId)` opens the panel programmatically | panel identity toggle semantics — no panel → open; same view → close; another panel → replace |
671
+ | Uninstalling the declaring plugin → the menu item disappears + revealFloating no-ops without crashing | the declaration unloads with the plugin lifecycle |
672
+
673
+ **The first declarer = settings** (`core.openSettings`, Ctrl+, opens the panel); **the second declarer, used as a validation vehicle = the `floating-panel-demo` test plugin** (a tab-style view; end-to-end validation of replacement + the right-click return path + unload no-op).
674
+
675
+ ---
676
+
677
+ ## 4. Context Key when conditions
678
+
679
+ The `when` field of menu items and commands uses ContextKeyService expressions:
680
+
681
+ | Operator | Example | Meaning |
682
+ |------|------|------|
683
+ | bare key | `portOpen` | a truthy key value → true |
684
+ | `!` | `!portOpen` | negation |
685
+ | `&&` | `activeEditor == 'cad' && portOpen` | logical and |
686
+ | `\|\|` | `activeEditor == 'a' \|\| activeEditor == 'b'` | logical or |
687
+ | `==` | `activeEditor == 'cad'` | equals |
688
+ | `!=` | `editorCount != 0` | not equals |
689
+ | `in` | `activeEditor in ['cad', 'terminal']` | set membership |
690
+ | `()` | `!(portOpen \|\| editorCount > 1)` | grouping |
691
+
692
+ **Available Context Keys (written by the shell):**
693
+
694
+ | Key | Type | Writer |
695
+ |------|------|------|
696
+ | `activeEditor` | `string \| null` | on tab switch — the pluginId of the currently focused tab |
697
+ | `portOpen` | `boolean` | on serial port open/close |
698
+ | `portName` | `string \| null` | on serial port open/close |
699
+ | `editorCount` | `number` | on tab add/remove |
700
+ | `editorHasSelection` | `boolean` | when the editor has selected text (reserved) |
701
+
702
+ ---
703
+
704
+ ## 5. Full plugin.json example — a CAD plugin (every field aligned with the real consumption surface)
705
+
706
+ ```json
707
+ {
708
+ "$schema": "plugin.schema.json",
709
+ "name": "CAD Viewer",
710
+ "version": "1.0.0",
711
+ "icon": "PencilRuler",
712
+ "iconSource": "lucide",
713
+ "description": "DWG/DXF/STL file viewer",
714
+ "author": "Community",
715
+ "entry": "src/index.tsx",
716
+ "appearsIn": { "iconBar": "top", "tabBar": true },
717
+ "tabBehavior": {
718
+ "singleton": true,
719
+ "confirmOnClose": "Unsaved changes will be lost"
720
+ },
721
+ "requires": ["file-tree"],
722
+ "statusBar": [
723
+ { "id": "units", "label": "mm", "align": "right" }
724
+ ],
725
+ "contributes": {
726
+ "i18n": { "en": "i18n/en.json" },
727
+ "commands": [
728
+ { "id": "cad.importDxf", "title": "Import DXF…", "category": "CAD" },
729
+ { "id": "cad.zoomFit", "title": "Zoom to fit", "category": "CAD", "when": "activeEditor == 'cad'" }
730
+ ],
731
+ "menus": {
732
+ "editorContext": [
733
+ { "command": "cad.importDxf", "group": "navigation" },
734
+ { "command": "cad.zoomFit", "group": "view" }
735
+ ],
736
+ "commandPalette": [
737
+ { "command": "cad.importDxf" },
738
+ { "command": "cad.zoomFit", "when": "activeEditor == 'cad'" }
739
+ ]
740
+ },
741
+ "keybindings": [
742
+ { "command": "cad.zoomFit", "key": "ctrl+0", "when": "activeEditor == 'cad'" }
743
+ ],
744
+ "configuration": {
745
+ "title": "CAD Viewer",
746
+ "properties": {
747
+ "cad.gridSize": { "type": "number", "default": 10, "description": "Grid size" },
748
+ "cad.units": { "type": "string", "default": "mm", "enum": ["mm", "cm", "inch"], "description": "Units" },
749
+ "cad.autoSave": { "type": "boolean", "default": true, "description": "Auto save" }
750
+ }
751
+ },
752
+ "viewsContainers": {
753
+ "cad": { "title": "CAD Viewer", "location": "sidebar" }
754
+ },
755
+ "views": {
756
+ "cad": [
757
+ { "id": "layers", "title": "Layers", "render": "src/views/LayersView.tsx", "order": 0 }
758
+ ]
759
+ },
760
+ "fileAssociations": [
761
+ { "extension": "dxf", "command": "cad.openFile", "displayName": "DXF drawing" },
762
+ { "extension": "dwg" },
763
+ { "extension": "stl" }
764
+ ]
765
+ }
766
+ }
767
+ ```
768
+
769
+ ---
770
+
771
+ ## 6. Comparison with VS Code contributes
772
+
773
+ | VS Code contributes | LinkDesk | Difference |
774
+ |------|------|------|
775
+ | `commands` | ✅ | same — metadata declaration + a handler registered on the pool side |
776
+ | `menus` | ✅ | LinkDesk adds `quickSendContext` / `cardContext` / `viewTitleContext` and more (MenuId is an open string) |
777
+ | `keybindings` | ✅ | same — but text keys go through the pool-side onKeyDown (`05 §4`) |
778
+ | `configuration` | ✅ | same — the types include object/array |
779
+ | `configurationDefaults` | ✅ | same |
780
+ | `themes` | ✅ | same |
781
+ | `productIconThemes` | ✅ `iconThemes` | same |
782
+ | `icons` | ✅ | same (shared icons, iconSource:shared) |
783
+ | `languages` (programming languages) | ✅ `langDefs` | consumed by the **main process** — syntax highlighting/LSP |
784
+ | `languages` (translation packs) | ✅ `languages` | LinkDesk's `languages` = UI language packs (i18n); VS Code uses the l10n system |
785
+ | `views` / `viewsContainers` | ✅ | same + LinkDesk adds the `titleActions` declaration system + visibility/migration/panel.reveal |
786
+ | `titleBar` | ✅ | top bar left/right buttons |
787
+ | `viewsWelcome` | ⏳ | welcome content — future |
788
+ | `fileAssociations` | ✅ | **main process** — VS Code leaves file associations to the operating system, LinkDesk has them built in |
789
+ | `extensionDependencies` | ✅ `requires` | a string array (`02 §4`) |
790
+ | ~~`activationEvents`~~ | ~~✅~~ | **deleted** (retired, 2026-09-09) — the load model is simplified: register the full metadata set at startup, JS loaded by the pool on demand (`02 §5`) |
791
+ | `snippets` / `problemMatchers` | ❌ not planned | shipped by the Monaco/LSP plugins themselves |
792
+ | `breakpoints` / `debuggers` | ❌ not planned | debuggers — not needed for now |
793
+
794
+ ---
795
+
796
+ > **← Previous:** `02-plugin-lifecycle.md`
797
+ > **→ Next:** `04-distribution-format.md`
798
+ > **→ Related:** `08-view-container-api.md` (the full semantics of views)
799
+ > **→ Source of truth:** `src/pluginLoader/contributions.ts` / `public/schemas/plugin.schema.json` (the shape of contributes); theme recipe data = `public/schemas/theme.schema.json`, icon theme mappings data = `public/schemas/icon-theme.schema.json` (theme/icon-theme ship together with `@linkdesk/plugin-sdk`)
800
+ > **All documentation index:** `00-readme.md`