@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,549 @@
1
+ # Plugin UI Authoring Conventions
2
+
3
+ > **In one line: the core already provides the standard components and registries—don't hand-roll wheels. Hand-rolling = inconsistent style + something to tear out at the next normalization.**
4
+ > Skim this before writing a plugin, to avoid B62-style rework.
5
+ > **Reconciled against the implementation on 2026-09-06**: flatten-to-single-root (no plugins/{builtin,user}) · shared controls go through @linkdesk/ui · distribution = `.linkdesk-plugin` zip. References to the corresponding mechanisms have been cleaned out of this page.
6
+
7
+ ---
8
+
9
+ ## 1. Context Menu → `<ContextMenu>` + MenuRegistry
10
+
11
+ **❌ Forbidden:** hand-writing `<div className="my-menu">` + `useState` + a click-outside listener.
12
+
13
+ **✅ Right:**
14
+ ```json
15
+ // ① Declare the menu items—plugin.json contributes.menus (preferred, declarative)
16
+ {
17
+ "contributes": {
18
+ "menus": {
19
+ "editorContext": [
20
+ { "command": "myPlugin.copy", "group": "navigation" },
21
+ { "command": "myPlugin.clear", "group": "edit" }
22
+ ]
23
+ }
24
+ }
25
+ }
26
+ ```
27
+
28
+ ```tsx
29
+ // Dynamic registration at runtime (equivalent)—window.linkdesk.menu.registerItems(menuId, pluginId, items)
30
+ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
31
+ { command: "myPlugin.copy", group: "navigation" },
32
+ { command: "myPlugin.clear", group: "edit" },
33
+ ]);
34
+
35
+ // ② Use the unified component—MenuId is an open string, so just write a string literal
36
+ <ContextMenu menuId="editorContext" />
37
+ ```
38
+
39
+ **Rationale:** `<ContextMenu>` brings its own backdrop + four blur paths (Escape / backdrop click / window blur / option click) + keyboard navigation + when-condition filtering. You can't hand-roll those four blur paths—B62 lesson.
40
+
41
+ **MenuId is an open string (`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)—a plugin declaring any string at all is the contract; no shell code change is needed.** Shell built-in registration points (the MENU_SLOTS constant table):
42
+
43
+ | MenuId (string literal) | Scenario |
44
+ |---|---|
45
+ | `commandPalette` | Ctrl+Shift+P command palette |
46
+ | `tabContext` | Tab Bar tab right-click |
47
+ | `panelViewContext` | Panel tab bar right-click (position/alignment submenu + view show/hide list) |
48
+ | `editorContext` | Tab page main content area right-click |
49
+ | `extensionGear` | Bottom gear menu (settings/command palette/theme picker) |
50
+ | `marketplaceItemGear` | Marketplace entry gear (enable/disable/uninstall) |
51
+ | `menuBar` | ☰ hamburger menu bar |
52
+ | `panel` | The "Panel" menu in the menu bar |
53
+ | `fileContext` | File tree right-click |
54
+ | `cardContext` | Card right-click |
55
+ | `quickSendContext` | Quick-send pill right-click |
56
+ | `iconBar` | Icon bar right-click |
57
+ | `settingItemGear` | Setting item gear (Settings Editor row hover) |
58
+ | `viewTitleContext` | Sidebar view title right-click (collapse/reset position/group the view) |
59
+
60
+ New context-menu scenarios → just declare a new open-string MenuId (e.g. `"myMenu"`): declare `contributes.menus.myMenu` + consume it with `<ContextMenu menuId="myMenu" />`—**zero shell changes** (the plugin-independence iron rule). The shell only needs to add a MENU_SLOTS entry if it wants to provide a unified render point for that scenario.
61
+
62
+ ---
63
+
64
+ ## 2. Overlays / Dialogs → `createPortal`
65
+
66
+ **❌ Forbidden:** a dialog nested deep inside a div in the component tree.
67
+
68
+ **✅ Right:**
69
+ ```tsx
70
+ import { createPortal } from "react-dom";
71
+
72
+ return createPortal(
73
+ <div className="my-dialog">{/* ... */}</div>,
74
+ document.body // ← the key: render into body
75
+ );
76
+ ```
77
+
78
+ **Rationale:** under the keep-alive architecture inactive tabs are `display: none`, and children aren't visible even with `position: fixed` (B54 lesson). Only rendering into `document.body` escapes the component-tree constraint.
79
+
80
+ ---
81
+
82
+ ## 3. Persistence → `window.linkdesk.configuration` (declared via plugin.json contributes.configuration)
83
+
84
+ **❌ Forbidden:** `localStorage.setItem()` / `PreferenceService.loadPrefs()` / hand-written file I/O / `import ... from "@src/core/..."`.
85
+
86
+ **✅ Right—go through `window.linkdesk.configuration` (plugin communication iron rule: only `window.linkdesk.*`, never `import` from @src/core):**
87
+ ```tsx
88
+ // Read configuration (a Promise—the value is dynamic at runtime)
89
+ useEffect(() => {
90
+ window.linkdesk.configuration.get<boolean>("myPlugin.showLineNumbers").then((v) => {
91
+ setShowLineNumbers(v);
92
+ });
93
+ }, []);
94
+
95
+ // Write configuration
96
+ await window.linkdesk.configuration.set("myPlugin.showLineNumbers", true);
97
+
98
+ // Subscribe to changes—returns an unsubscribe; call it on unmount
99
+ useEffect(() => {
100
+ return window.linkdesk.configuration.onChange<boolean>("myPlugin.showLineNumbers", (v) => {
101
+ setShowLineNumbers(v);
102
+ });
103
+ }, []);
104
+ ```
105
+
106
+ **Declaring configuration items in plugin.json:**
107
+ ```json
108
+ {
109
+ "contributes": {
110
+ "configuration": {
111
+ "title": "My Plugin",
112
+ "properties": {
113
+ "myPlugin.showLineNumbers": {
114
+ "type": "boolean",
115
+ "default": true,
116
+ "description": "Show line numbers"
117
+ }
118
+ }
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ **Rationale:** the shell persists automatically + restores on restart + the Settings Editor renders it automatically. Hand-rolled localStorage → you lose Settings Editor integration + get the next persistence bug.
125
+
126
+ ---
127
+
128
+ ## 4. Keyboard Shortcuts → Two Tracks: Declarative (non-text keys) + Pool-side self-handling (text keys / focus-bound keys)
129
+
130
+ Shortcuts have **two tracks**, and which one you pick depends on the nature of the key. **Picking the wrong track = a dead key or a hijack of the whole pool** (lesson).
131
+
132
+ ### 4.1 Track one: `contributes.keybindings` (visible in the settings panel)—**non-text keys only**
133
+
134
+ **❌ Forbidden:** putting **text-editing keys** such as `ctrl+c` / `ctrl+v` / `ctrl+x` / `ctrl+a` / `f2` into `contributes.keybindings`.
135
+
136
+ **✅ Right:** (non-text keys—such as `ctrl+k` / `ctrl+shift+e` / `f5`)
137
+ ```json
138
+ {
139
+ "contributes": {
140
+ "keybindings": [
141
+ {
142
+ "key": "ctrl+k",
143
+ "command": "myPlugin.clear",
144
+ "when": "activeEditor == 'myPlugin'"
145
+ }
146
+ ]
147
+ }
148
+ }
149
+ ```
150
+
151
+ **Rationale (why text keys are a landmine):** declared/registered keys sync into the main-process keyCache → when `before-input-event` hits, the key is **swallowed unconditionally** (it doesn't respect when, doesn't respect an editable state, doesn't respect whether a handler even exists). Register one `ctrl+c` in the shell and you swallow the native `ctrl+c` of every input box / Monaco instance in the whole pool. The right answer for text keys = track two.
152
+
153
+ ### 4.2 Track two: pool-side self-handling (container onKeyDown)—the right answer for text keys + focus-bound keys
154
+
155
+ **✅ Right:** a component handles its own keyboard interaction inside its own **container's `onKeyDown`**:
156
+
157
+ ```tsx
158
+ <div
159
+ tabIndex={0} // makes the container focusable—clicking a child makes the browser give focus to the nearest focusable ancestor
160
+ onKeyDown={(e) => {
161
+ if (e.key === "F2") { e.preventDefault(); startRename(); }
162
+ }}
163
+ >
164
+ {items}
165
+ </div>
166
+ ```
167
+
168
+ **Why this is the right answer:** every plugin in the pool shares one document—**DOM focus partitions naturally**. Only a focused container receives the key; a focused Monaco doesn't, and multiple plugins can each do their own `ctrl+c` without stepping on each other. No when needed, no conflict detection needed. File tree clipboard keys = the shared `useClipboardKeys` hook + the same command chain. Clipboard-related keys can reuse `src/pool/hooks/useClipboardKeys` (declarative `onCopy`/`onCut`/`onPaste` callbacks, one implementation and one fix location for the mechanism).
169
+
170
+ **❌ Anti-pattern (red flag):** `document.addEventListener("keydown", ...)` / `window.addEventListener("keydown", ...)` = **global hijack**—it bypasses the partitioning premise, and while the plugin has an active session it hijacks that key across the whole pool (serial F2 once hijacked the file tree's F2). **`tabIndex` + container `onKeyDown` is the right answer for focus partitioning**; non-focusable elements don't trigger it, so add `tabIndex={0}` to receive keys.
171
+
172
+ **Note:** track-two keys **do not appear in the keyboard shortcuts settings panel**—the panel only shows KeybindingRegistry bindings (track one). This is a design trade-off (registering means swallowing across the pool, see 4.1), not a bug.
173
+
174
+ ### 4.3 Clipboard channel picker
175
+
176
+ | What you want to copy | Channel | Example |
177
+ |---|---|---|
178
+ | Text inside an editable element (input/textarea/Monaco) | **Browser native**—write nothing | Ctrl+C/V inside an input box |
179
+ | Arbitrary text | `window.linkdesk.clipboard.writeText` | Copy selected text to the system clipboard |
180
+ | File/path list | `window.linkdesk.clipboard.writeFileList` | File tree copy → pasteable in Explorer (CF_HDROP) |
181
+
182
+ **Note:** editable elements take the browser-native path—**don't** declare a shortcut and don't intercept it; Electron/Chromium wires up the system clipboard automatically.
183
+
184
+ ---
185
+
186
+ ## 5. Colors → CSS Variables `var(--xxx)`
187
+
188
+ **❌ Forbidden:** hardcoding `#0078d4` / `#1e1e1e` / `#ffffff`.
189
+
190
+ **✅ Right:**
191
+ ```css
192
+ .my-element {
193
+ color: var(--text-primary);
194
+ background: var(--bg-input);
195
+ border: 1px solid var(--border);
196
+ }
197
+ ```
198
+
199
+ **Rationale:** after a theme switch hardcoded colors stay the same → under a dark theme you get white text on a white background. See `src/index.css` for all available CSS variables.
200
+
201
+ ---
202
+
203
+ ## 6. Text → `t()` Internationalization
204
+
205
+ **❌ Forbidden:** bypassing `t()` and hardcoding display strings (`<button>发送</button>` / `<button>Send</button>`).
206
+
207
+ **✅ Right:**
208
+ ```tsx
209
+ import { useTranslation } from "react-i18next";
210
+ const { t } = useTranslation();
211
+ <button>{t("发送")}</button> // the i18n key = the plugin UI's source text (a Chinese plugin uses Chinese, an English/French plugin uses its own language)
212
+ ```
213
+
214
+ ---
215
+
216
+ ## 7. Sidebar List Item Selection → `onMouseDown` (not `onClick`)
217
+
218
+ **❌ Forbidden:** using `onClick` to select items in a vertical Sidebar list.
219
+
220
+ **✅ Right:**
221
+ ```tsx
222
+ <div
223
+ className={`my-list-item${isActive ? " active" : ""}`}
224
+ onMouseDown={() => onSelect(item.id)}
225
+ >
226
+ <span>{item.label}</span>
227
+ </div>
228
+ ```
229
+
230
+ **Rationale:** sidebar items sit vertically adjacent—on a fast click the mousedown lands on item A and the mouseup slides onto item B. Per the browser `click` event spec: when mousedown and mouseup land on different elements → click is dispatched to their common ancestor → React finds no handler on the ancestor → the event is silently lost. `onMouseDown` only cares about where the press happened and doesn't require the release on the same element—eliminating lost events on fast clicks.
231
+
232
+ **Aligned with VS Code:** the Explorer file tree selects files with `onMouseDown`, not `onClick`. This is a pattern validated by tens of millions of users; don't design your own.
233
+
234
+ **When it applies:** any clickable list in a Sidebar that is vertically arranged with small gaps between items—session lists, file trees, database connections, MQTT topics, device lists, and so on.
235
+
236
+ **Handling child elements:** action buttons/input boxes inside an item need `onMouseDown={(e) => e.stopPropagation()}` to avoid accidentally selecting the parent item:
237
+ ```tsx
238
+ <button
239
+ onMouseDown={(e) => e.stopPropagation()}
240
+ onClick={(e) => { e.stopPropagation(); handleDelete(); }}
241
+ >
242
+ ✕
243
+ </button>
244
+ ```
245
+
246
+ ---
247
+
248
+ ## 8. Plugin-Owned Data Models → `Emitter` Reactive Pattern
249
+
250
+ **❌ Forbidden:** mutating the model in a command handler and then manually calling `rerender()` / `setVersion()` / passing a `treeVersion` prop.
251
+
252
+ **✅ Right—the web-standard `EventTarget` (zero core imports; plugin-owned classes extend it directly):**
253
+ ```typescript
254
+ class MyModel extends EventTarget {
255
+ private _items: Item[] = [];
256
+
257
+ add(item: Item): void {
258
+ this._items.push(item);
259
+ this.dispatchEvent(new CustomEvent("change")); // ← dispatch at the end of every state-changing method
260
+ }
261
+
262
+ remove(id: string): void {
263
+ this._items = this._items.filter(i => i.id !== id);
264
+ this.dispatchEvent(new CustomEvent("change"));
265
+ }
266
+ }
267
+ ```
268
+
269
+ ```tsx
270
+ // Subscribe on component mount, clean up on unmount
271
+ function MyView({ model }: { model: MyModel }) {
272
+ const [version, setVersion] = useState(0);
273
+
274
+ useEffect(() => {
275
+ const onChange = () => setVersion(v => v + 1);
276
+ model.addEventListener("change", onChange);
277
+ return () => model.removeEventListener("change", onChange); // auto-unregistered on unmount
278
+ }, [model]);
279
+
280
+ const items = useMemo(() => computeItems(model), [model, version]);
281
+ // ...
282
+ }
283
+ ```
284
+
285
+ **Rationale:** three timing bugs (badge stuck at 0 / when stops working / refresh doesn't update the tree) all traced back to a module-level command handler mutating a mutable model, with React unable to perceive it. The model announces its own changes (`EventTarget`/`CustomEvent` are web standards; you don't need the shell's `Emitter`)—handlers only mutate the model and never touch React.
286
+
287
+ **When it applies:** a plugin has module-level command handlers that need to trigger a UI refresh after changing data.
288
+
289
+ **⚠️ Plugins must not `import { Emitter } from "@src/core/CoreEvents"`—that is a shell-internal implementation (plugin communication iron rule + ESLint `noCoreImportInPlugin` at error level). Plugin-owned models use the web-standard `EventTarget`; events between plugins, or between a plugin and the shell, go through `window.linkdesk.events` (see `07-plugin-to-plugin-communication.md`).**
290
+
291
+ ---
292
+
293
+ ## 9. System UI Overlays → linkdesk API (quickPick / notifications / dialog)
294
+
295
+ **❌ Forbidden:** hand-rolled picker overlays / `window.alert()` / `window.confirm()` / `import ... from "@src/core/..."`.
296
+
297
+ **✅ Right:**
298
+ ```tsx
299
+ // Picker—window.linkdesk.quickPick.show({ items, placeholder, prefix })
300
+ const picked = await window.linkdesk.quickPick.show({
301
+ placeholder: "Select target session",
302
+ items: [
303
+ { label: "Session A", description: "/dev/ttyUSB0" },
304
+ { label: "Session B", description: "/dev/ttyUSB1" },
305
+ ],
306
+ });
307
+
308
+ // Notification—window.linkdesk.notifications.show(message, { type })
309
+ await window.linkdesk.notifications.show("Connected", { type: "info" });
310
+ await window.linkdesk.notifications.show("Validation failed", { type: "error" });
311
+
312
+ // Confirm / alert / file picker—window.linkdesk.dialog
313
+ const ok = await window.linkdesk.dialog.confirm("Delete this session?");
314
+ await window.linkdesk.dialog.alert("Version conflict, skipped");
315
+ const file = await window.linkdesk.dialog.openFile({
316
+ filters: [{ name: "DXF files", extensions: ["dxf"] }],
317
+ });
318
+ ```
319
+
320
+ **Rationale:** all three are rendered uniformly by the in-pool host (QuickPickHost / **the bell wide notification panel** / DialogHost)—styles match the shell and scale with the theme and font size. Hand-rolled overlays = inconsistent style + `position: fixed` breaking under keep-alive (B54). Full signatures are in `contracts/linkdesk.d.ts`.
321
+
322
+ > ⚠️ **Notifications are not "auto-vanishing floating cards"** (notification-surface unification and correction): the bottom-right narrow toast pipeline has been deleted entirely, and **the only notification surface = the status bar bell wide panel**. Three things authors need to know:
323
+ > 1. **Notifications don't pop a card, don't steal focus, and don't block interaction**—they go into the bell (unread count +1), and the user only sees them after opening it. Don't treat notifications as a "must be seen" channel: if the user has to decide on the spot → use `dialog.confirm` (modal, steals focus).
324
+ > 2. **Persistent notifications per source are quota-limited**—grouped by `options.source`, at most 5 persistent per group; beyond that, the oldest one from the same source is pushed out. A flood won't pile into a wall, but **don't count on notifications for long-term records either**.
325
+ > 3. **Keyboard reachability means "the panel is reachable", not "notifications are reachable"**—the bell can be focused and opened with the keyboard, everything inside the panel can be reached with Tab, and `Esc` closes it; but the panel **has no focus trap** (non-modal, focus can leave freely). **Don't write assumptions like "Tab gets you to my notification button"**—the user may never open the panel at all.
326
+
327
+ **Notification action buttons (`actions` on `notifications.show`):** failure / user-action-required notifications can carry an `actions` button array—clicking runs through the **command system** (modeled after VS Code's `showErrorMessage(msg, { title, command })` actions). Command handlers are registered by the plugin itself (`commands.registerCommand`):
328
+
329
+ ```tsx
330
+ // Failure toast + [Retry]/[View dependencies]—command = a command the plugin registered itself
331
+ await window.linkdesk.notifications.show("Install failed: cannot connect to source", {
332
+ type: "error", // error toasts linger 8s (enough to read the diagnostics); info/warning linger 6s
333
+ actions: [
334
+ { id: "retry", label: "Retry", isPrimary: true, command: "myplugin.retryInstall" },
335
+ { id: "deps", label: "View dependencies", command: "myplugin.openDeps" },
336
+ ],
337
+ });
338
+ // Commands can take arguments—clicking runs command(...args)
339
+ await window.linkdesk.notifications.show("Save conflict", {
340
+ type: "warning",
341
+ actions: [{ label: "Force save", command: "myplugin.saveForce", args: [filePath] }],
342
+ });
343
+ ```
344
+
345
+ Button text = the final display text (the shell does not translate it a second time); `isPrimary: true` = primary button (accent), unset = secondary text button. **Not passing `actions` = no buttons today, zero behavioral change.** Full types are in `contracts/linkdesk.d.ts` (the `actions` of the `notifications.show` options).
346
+
347
+ **Progress notifications + persistent notifications + source identity:** `show` **always returns a handle** (it isn't only progress bars that get one). The three easiest things to get wrong:
348
+
349
+ ```tsx
350
+ // ① Progress notification—the handle drives the same single notification (it won't spawn N of them)
351
+ const h = await window.linkdesk.notifications.show("Downloading…", {
352
+ progress: true, // turns on a real progress bar; not passing percent = indeterminate animation
353
+ source: "myplugin", // see ③
354
+ });
355
+ await h.update("Downloading…", 42); // 0-100; passing only message keeps it indeterminate
356
+ await h.finish("Download complete"); // closes the progress bar, optionally adds a completion notification
357
+ // or await h.cancel(); // close it outright, no completion notification
358
+
359
+ // ② Persistent notification—doesn't auto-dismiss, waits for the user to click × (use for error diagnostics)
360
+ await window.linkdesk.notifications.show("Port is in use, please close other programs", {
361
+ type: "error",
362
+ persistent: true,
363
+ });
364
+
365
+ // ③ Source identity—the panel groups by it, 5 persistent slots per group
366
+ await window.linkdesk.notifications.show("Sync failed", { source: "myplugin" });
367
+ ```
368
+
369
+ **Three things you must know:**
370
+
371
+ 1. **The handle is the only key**: a notification **can only be updated/removed by the handle that created it**. A `show` with the same text elsewhere = another notification, and you can't retract theirs. To retract a persistent notification (e.g. a failed `persistent`), use its own handle or let the user click ×.
372
+ 2. **`source` must be self-reported**: the pool is a single process sharing one realm, all plugins share the same `window.linkdesk`, and preload **cannot** know which plugin issued this `show` ⇒ only the author can pass it explicitly. **Not passing it → everything lands in the "Other" group**; plugins pass their own plugin id, and the shell's own domains use `app.<domain>`.
373
+ 3. **`persistent` has a quota**: at most 5 persistent per group (by `source`); beyond that the oldest of the same source is pushed out and a summary hint is shown. **Persistent ≠ unlimited retention**—if you need retention, write your own file.
374
+
375
+ > The full **behavior contract** (not signatures—for signatures see `contracts/linkdesk.d.ts`) is in the `notifications` row of [`01-plugin-api-contract.md`](01-plugin-api-contract.md) §3.2—this section only covers usage, and that one is authoritative for semantics.
376
+
377
+ **Rich-content confirm dialogs (`dialog.confirmContent`):** use this when the confirm dialog needs **more than one line of text** (a form / list / screenshot / custom layout)—**the dialog is the shell (centered, masking, Esc, focus lock, click-mask to cancel) and your view draws the content** (modeled after VS Code's "the dialog is the shell, the plugin defines the content"):
378
+
379
+ ```tsx
380
+ // 1) First declare the view for this content in plugin.json (any contributes.views container works)
381
+ // 2) In code, address and open it by the "declared id"
382
+ const ok = await window.linkdesk.dialog.confirmContent({
383
+ pluginId: "myplugin", // the plugin the content belongs to (the shell uses this for composite addressing)
384
+ viewId: "myplugin.confirmImport", // declared id of the content view
385
+ title: "Confirm import", // fallback title—if the content view fails to resolve, the shell falls back to a plain-text confirm
386
+ message: "3 entries will be overwritten", // fallback body
387
+ payload: { files: ["a.ts", "b.ts"] }, // opaque payload: the shell doesn't interpret it, your view reads it itself
388
+ });
389
+ if (ok) { /* user confirmed */ } // false = cancelled / closed
390
+ ```
391
+
392
+ The other half—the content view (**another view in the same code**, reading the payload and stating a verdict):
393
+
394
+ ```tsx
395
+ // In your content view component—mounting opens it, reading once is enough (every new dialog is a fresh mount)
396
+ function MyConfirmContent() {
397
+ const data = window.linkdesk.dialogHost.current();
398
+ if (!data || data.open !== true) return null; // defensive: don't render blank
399
+ const payload = data.content?.payload as MyPayload;
400
+ return (
401
+ <div>
402
+ {/* The body layout and the buttons are entirely yours to draw */}
403
+ <button onClick={() => window.linkdesk.dialogHost.cancel()}>Cancel</button>
404
+ <button onClick={() => window.linkdesk.dialogHost.confirm()}>OK</button>
405
+ </div>
406
+ );
407
+ }
408
+ ```
409
+
410
+ **The fallback is hard**: if `viewId` can't be resolved (view not declared / the declaring plugin isn't installed) → the shell **falls back to a plain-text confirm** (using `title`/`message`), the dialog still appears and **never dies silently**. So don't skip `title`/`message`. The payload crosses IPC via structured clone, so only cloneable data can go in it (no functions/React elements). There are only two ways to settle: `dialogHost.confirm()` / `dialogHost.cancel()`—**don't close the dialog yourself with `setState`**; the shell won't recognize it.
411
+
412
+ ---
413
+
414
+ ## 10. Font Sizes → `--font-size-*` tokens + `--ui-scale` (measurement-system normalization)
415
+
416
+ **❌ Forbidden:** writing bare `px` for plugin text font sizes (`font-size: 14px`)—the `check-font-scale-audit` gate (`npm run check`) rejects it mechanically.
417
+
418
+ **✅ Right:** font sizes consume `var(--font-size-*)`; line-height is unitless (`1.5`) or `calc(... * var(--ui-scale))`; fixed upper bounds (input box/button/status bar heights) are written as `calc(Npx * var(--ui-scale))` to scale with the global setting. Unified global font-size scaling (the `app.uiFontScale` setting, 85–150%, always shown and always in effect).
419
+
420
+ **Scale table** (100% render = `--ui-scale: 1`; the engine computes the final px from the scale factor):
421
+
422
+ | Step | Base px | Meaning |
423
+ |---|---|---|
424
+ | `--font-size-2xs` | 11 | badges/paths |
425
+ | `--font-size-xs` | 12 | secondary text/buttons/stats |
426
+ | `--font-size-sm` | 13 | main UI text (aligned with VS Code's 13px) |
427
+ | `--font-size-md` | 14 | menus/tabs/file tree name |
428
+ | `--font-size-lg` | 16 | icon glyphs/content icons (paired with 14px text) |
429
+ | `--font-size-xl` | 18 | region titles |
430
+ | `--font-size-2xl` | 22 | row icons/large text |
431
+ | `--font-size-3xl` | 28 | pd-name |
432
+ | `--font-size-4xl` | 30 | welcome-title |
433
+
434
+ **Iron rules + boundaries (see the archive's §5 icon rulings / §6.2 monaco island decision):**
435
+ - **Standalone display icons do not scale with font size** (decorative/brand semantics, not directly adjacent to text)—`.icon-btn .plugin-icon--codicon` 24 / `.plugin-icon--emoji` 24 / `.hamburger-btn` 20 / hero-icon 48 / row icons 20, and so on; for whitelist exemptions see `scripts/check-font-scale-audit.mjs`.
436
+ - **Content-level font sizes go through `contributes.configuration`** (e.g. `editor.fontSize`)—large text areas/editor content are controlled by the plugin's own configuration and don't follow `--ui-scale`.
437
+ - **The monaco content island precedent**: editor content reads `editor.fontSize`, while chrome (status bar/breadcrumbs) follows the global setting—two orthogonal axes, each minding its own business.
438
+ - **Mapping rule**: migrating existing `NNpx` to the scale table goes "up one step"—`12→sm / 13→md / 11→xs / 10→2xs / 14→lg / 18→xl` (at 100% this enlarges to the new default baseline, aligned with VS Code).
439
+
440
+ ---
441
+
442
+ ## 11. The Token Contract—Six-Domain Matrix + Honest Boundaries + Data Discipline (.5)
443
+
444
+ > **In one line:** before writing UI, check the 11.1 six-domain matrix—forms/controls/surfaces written with `var(--*)` **follow the theme + glass + global scaling automatically**, with zero plugin awareness. Doing it right is driven by recommendations, doing it wrong shows red through the gate but only as a WARN, and bypassing it takes a knowing declaration via a standard eslint-disable (content/brand fixed colors are legitimately exempt—see 11.2).
445
+ > The gate = `linkdesk-plugin-sdk lint` (built into `@linkdesk/plugin-sdk`): the eslint rule leg + the three-check scanner leg, dual-track; all 15 items are **WARNs that never fail the build/upload**—advice, not a lockdown. Run it once at your project root; a violation shows red with self-explanatory fix text.
446
+
447
+ ### 11.1 The six-domain token matrix—authors can only write "follows automatically" if they know what variables exist
448
+
449
+ | Domain | var() keys (the full list always defers to `src/index.css`) | How authors write it | Gate coverage |
450
+ |---|---|---|---|
451
+ | **Color** | `--text-primary/--text-secondary/--text-muted` (the text-color source is controlled by fontTone) + `--bg-window/--bg-side-panel/--bg-card/--bg-input/--bg-selection` + `--accent/--accent-hover` | `color: var(--text-primary)` | `linkdesk/no-hardcoded-hex` |
452
+ | **Surface** | `--bg-*` surface fills + `--surface-radius` (follows the shell's global corner-radius slider) | `background: var(--bg-card)` | `linkdesk/no-hardcoded-hex` |
453
+ | **Radius** | `--radius-xs/sm/md/lg/xl/2xl` + `--surface-radius` | `border-radius: var(--radius-md)` | `linkdesk/no-hardcoded-radius` (bare px in border-radius is red) |
454
+ | **Glass** | `--glass-blur/--glass-saturate/--glass-tint/--glass-morph/--glass-specular…` (the full group in `src/index.css`) | `backdrop-filter: blur(var(--glass-blur)) …` | contract guidance—composite forms are beyond per-item gating |
455
+ | **Font size** | `--font-size-2xs … 4xl` + `--ui-scale` (the scaling axis for `app.uiFontScale`; the scale table is in §10) | `font-size: var(--font-size-md)` / em/rem | `check-font-scale` (the check leg—a bare px font size is red) |
456
+ | **Font family** | `--font-ui` / `--font-mono` | `font-family: var(--font-ui)` | contract guidance (authors may legitimately choose their own font) |
457
+
458
+ `var(--*)` = theme/glass/global scaling follow automatically, with zero plugin awareness—**this is exactly why the @linkdesk/ui control layer can be "follow without thinking"** (54b/54c: controls are all tokens, and a plugin that does `npm i @linkdesk/ui` and consumes them follows along). Control reuse always imports from `@linkdesk/ui` (see §Quick Reference)—don't hand-roll wheels.
459
+
460
+ ### 11.2 Honest boundaries / knowing bypasses—content and brand colors can have their own sky
461
+
462
+ **Three gate tiers (07 §6):** recommended (copy it and you're right) / warning (15 self-explanatory items, red but **a WARN never fails**) / knowing bypass (a standard eslint-disable declaration with a reason). **No ecosystem can stop an author from hardcoding colors**—VS Code also has extensions that don't follow the theme. What the gate does is make "doing it right" the default and "doing it wrong" explicitly red but **knowingly bypassable**: a comment carrying a reason = the "proceed anyway" informed confirmation on a browser danger page, not silently switching off the light.
463
+
464
+ **Legitimate exemption categories:** var() fallback hex (`color: var(--x, #fff)` = a compliant form, not blocked) / color-picker swatches / canvas drawing / engine regions / **view-level exemption for content canvases**.
465
+
466
+ **The content vs. chrome boundary (empirically validated by the Angry Birds test):** a game / data visualization / canvas Main Area = **a content world, not UI chrome**—UI chrome follows the theme (var()/t()/@linkdesk/ui), while content can have its own sky (grass green / health-bar red / sky blue need not follow the theme). Authors **declare a view-level exemption once**, and the gate doesn't light up item by item inside content regions (item-by-item disables for the 5-10 hardcoded values in a game are far too noisy):
467
+
468
+ ```tsx
469
+ /* eslint-disable linkdesk/no-hardcoded-hex, linkdesk/no-hardcoded-radius -- content canvas: the game main area draws itself */
470
+ export function GameBoard() {
471
+ return <canvas /* draws blue sky, green grass, red health bar—a content world, not UI chrome */ />;
472
+ }
473
+ ```
474
+
475
+ ```tsx
476
+ // Line-level knowing bypass (a brand fixed-color badge—exempts only this line, other lines are still blocked)
477
+ // eslint-disable-next-line linkdesk/no-hardcoded-hex -- brand fixed-color badge
478
+ const PRO_BADGE = <span style={{ color: "#ff6b00" }}>PRO</span>;
479
+ ```
480
+
481
+ ```css
482
+ /* The same format in CSS (the check script recognizes it)—a color-picker swatch with a fixed value, exempt on this line */
483
+ /* eslint-disable-next-line linkdesk/no-hardcoded-hex -- color-picker swatch */
484
+ .swatch--brand { background: #ffd700; }
485
+ ```
486
+
487
+ **Semantics:** a line that hits an exemption goes **entirely silent** and doesn't light up (aligned with eslint's native suppress—after a disable declaration nothing is reported item by item); **no declaration = an unhandled deviation**, and `linkdesk-plugin-sdk lint` reports it with a normal WARN. **This is not new syntax**—it's the same format as the shell's existing `no-hardcoded-hex` error suggestion. **Backgrounds not being glassed holds inherently at the mechanism layer**—backdrop-filter only paints shell surface elements and is not applied to a plugin view's root node, so content the author draws is simply never glassed.
488
+
489
+ ### 11.3 Non-CSS engine adaptation—the translation bridge (self-rendering engines don't use CSS variables)
490
+
491
+ monaco-style self-rendering engines (canvas / WebGL / rich-text engines likewise) don't consume CSS variables—following the theme requires a **translation bridge**: subscribe to theme changes → translate into the engine's own theme API. Precedent: `src/services/theme-sync.ts` (it lives in **the editor plugin's own repo**, `Encaron/linkdesk-plugin-editor`—shipped plugin source is not in the shell repo):
492
+
493
+ ```ts
494
+ // Subscribe to theme changes (the event may fire before mount → register at top level or guard on active, see 11.5)
495
+ const off = window.linkdesk.events.on("theme:changed", () => {
496
+ engine.updateTheme(translateTheme()); // translate your tokens → the engine's theme object
497
+ });
498
+ ```
499
+
500
+ monaco's current opaque background and two-state (light/dark) following is **a transitional workaround, not a settled boundary**—full theme adaptation may come later.
501
+
502
+ ### 11.4 Plugin-private data channels—choosing a channel when you build your own settings UI / manage your own saves
503
+
504
+ When authors build their own settings UI or manage their own saves (without going through a shell settings-page declaration), pick the data landing spot by semantics:
505
+
506
+ | Channel | Good for | Example |
507
+ |---|---|---|
508
+ | `window.linkdesk.pluginState` (**preferred**) | plugin-managed saves—centralized caching + file persistence (a proper API: `get/set/onChange(pluginId, key)`) | game score / level progress / high-score board / skin preference |
509
+ | `window.linkdesk.configuration.set(key)` private namespace | follows settings semantics, readable by other plugins/themes, **must appear in the shell settings-page UI** (declaring contributes.configuration puts it there) | plugin parameters (declared = UI; undeclared = a purely private key that still persists when written) |
510
+ | `window.linkdesk.filesystem` | large files / binary / cross-plugin sharing | screenshot export / save files |
511
+ | `localStorage` | supplementary—in-pool temporary cache (no cross-machine, no shell management) | high-frequency temporary values within a session |
512
+
513
+ **Iron rule: private keys that don't declare `contributes.configuration` do not appear in the shell settings-page UI**—`config.set` writes and persists even without a schema (only enums get filtered), so authors who want the shell settings page declare a contribution, and those who want their own UI write private keys directly; the two don't interfere.
514
+
515
+ ### 11.5 Shell-discipline handoff list—each non-UI discipline sinks into the doc where it lands
516
+
517
+ | Discipline | Where it's specified |
518
+ |---|---|
519
+ | The plugin's only entry is `window.linkdesk.*`; **importing @src/core (including any @src subpath) is forbidden** | `01-plugin-api-contract.md` |
520
+ | Configuration: **subscribe, don't read once** (linkdesk.configuration is event-driven) | §3 of this file |
521
+ | linkdesk.events subscription **timing**—the event may fire before mount (IPC buffering) → register at top level or guard on active | `02-plugin-lifecycle.md` |
522
+ | **Don't hardcode other plugins' IDs** (differential behavior goes through plugin.json declaration fields, consumed via the Registry pattern) | `03-contributes-spec.md` |
523
+ | Configuration keys **must have a default** | `06-plugin-json-spec.md` |
524
+ | **Use only documented API namespaces** (don't casually hang undocumented `linkdesk.xxx` off the API) | `01-plugin-api-contract.md` |
525
+ | Controls always come from `@linkdesk/ui` (since 54c built-in controls are imported from the npm package; `@src/components/shared/*` is forbidden) | §Quick Reference of this file |
526
+
527
+ ---
528
+
529
+ ## Quick Reference
530
+
531
+ | What you want to do | Core facility | How to bring it in |
532
+ |---|---|---|
533
+ | Context menu | `<ContextMenu>` (open-string menuId) | `@linkdesk/ui` (ContextMenu) + a `plugin.json contributes.menus` declaration (or `window.linkdesk.menu.registerItems`, see §1) |
534
+ | Overlay/dialog | `createPortal` | `react-dom` (render into `document.body`, see §2) |
535
+ | Persistence | `window.linkdesk.configuration.get/set/onChange` | plugin communication iron rule—only `window.linkdesk.*` (see §3) |
536
+ | System picker | `window.linkdesk.quickPick.show` | uniform rendering by the in-pool QuickPickHost (see §9) |
537
+ | Notifications | `window.linkdesk.notifications.show` | uniform rendering by the in-pool **bell wide notification panel** (see §9; semantics in `01-plugin-api-contract.md` §3.2) |
538
+ | Confirm/alert/file picker | `window.linkdesk.dialog.confirm/alert/open/openFile` | uniform rendering by the in-pool DialogHost (see §9) |
539
+ | Rich-content confirm | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | the in-pool DialogHost renders the shell, **the content = a plugin-drawn view** (see §9) |
540
+ | Shortcuts (non-text keys) | `plugin.json contributes.keybindings` | — (putting text keys here = swallowing the whole pool, see §4.1) |
541
+ | Shortcuts (text keys / focus-bound keys) | container `onKeyDown` + `tabIndex` | pool-side self-handling, see §4.2 (document/window keydown is forbidden) |
542
+ | Colors | CSS variables | `var(--xxx)`, list in `src/index.css` |
543
+ | Font sizes | CSS variables | `var(--font-size-*)` + `--ui-scale`, bare px forbidden (#180 gate, see §10) |
544
+ | Six-domain token overview | see the §11.1 matrix | color/surface/radius/glass/font size/font family—`var(--*)` follows theme+glass+scaling automatically; full list in `src/index.css` |
545
+ | UI discipline gate | `linkdesk-plugin-sdk lint` | all 15 items are WARNs that never fail; a knowing bypass = a standard eslint-disable declaration (see §11.2) |
546
+ | Text | `t()` | `useTranslation()` from `react-i18next` |
547
+ | Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
548
+
549
+ **Use these facilities when writing plugins; don't hand-roll. Even if you write one, it'll have to be torn out later—better to normalize from day one.**