@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.
- package/README.md +58 -0
- package/docs/00-readme.md +189 -0
- package/docs/01-plugin-api-contract.md +171 -0
- package/docs/02-plugin-lifecycle.md +348 -0
- package/docs/03-contributes-spec.md +800 -0
- package/docs/04-distribution-format.md +172 -0
- package/docs/05-ui-conventions.md +549 -0
- package/docs/06-plugin-json-spec.md +640 -0
- package/docs/07-plugin-to-plugin-communication.md +299 -0
- package/docs/08-view-container-api.md +405 -0
- package/docs/09-plugin-directory-layout.md +301 -0
- package/docs/10-building-a-settings-plugin.md +164 -0
- package/docs/11-authoring-themes.md +173 -0
- package/docs/12-readme-media-contract.md +74 -0
- package/docs/13-development-guide.md +259 -0
- package/docs/14-data-pipeline-command-conventions.md +173 -0
- package/docs/15-multi-repo-and-local-workspace.md +86 -0
- package/docs/16-naming-conventions.md +77 -0
- package/docs/17-region-map.md +225 -0
- package/docs/18-cross-region-wiring.md +192 -0
- package/docs/19-component-cheatsheet.md +108 -0
- package/docs/20-adding-a-setting.md +159 -0
- package/docs/themes/01-build-a-theme-plugin.md +150 -0
- package/docs/themes/02-theme-field-index.md +145 -0
- package/docs/zh/00-README.md +189 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
- 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
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
- 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
- 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
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
- 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
- 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
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
- 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
- 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
- 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
- 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
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
- package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
- 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
- package/docs/zh/plugin.schema.json +687 -0
- 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
- 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
- package/package.json +20 -0
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
# 07 — Plugin-to-Plugin Communication
|
|
2
|
+
|
|
3
|
+
> 2026-07-28 · full update 2026-08-21 · **2026-09-06 reconciliation against the implementation** (the three communication mechanisms have not changed since they were settled; verified section by section with zero leftovers, kept as-is). **How do plugins pass data between each other?** It is not "the terminal opens a door for the protocol" — all communication goes through pipes provided by the core. Plugins only consume them; they never build them.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 1. Core principles
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
❌ Plugin ⇄ Plugin (direct handshake — LinkDesk does not allow this)
|
|
11
|
+
|
|
12
|
+
✅ Plugin → Core → Plugin (the core provides the pipe; plugins just use it)
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
**Only the core builds APIs. Plugins do not build APIs.** A plugin does one thing: call the functions the core hands it and read/write data through the pipes.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 2. The three communication mechanisms — provided by the core, chosen by the plugin
|
|
20
|
+
|
|
21
|
+
| | Broadcast `events` | Commands `commands` | Data pipeline |
|
|
22
|
+
|------|------|------|------|
|
|
23
|
+
| API | `events.emit/on` | `registerCommand` / `executeCommand` | `serial.onData/onStats/onSystem` + `lsp.onData` + `filesystem.watch` |
|
|
24
|
+
| Semantics | whoever subscribes receives it (filtered by channel within the same pool) | a named, callable action | high-frequency push — a **stream**, not an event |
|
|
25
|
+
| Does the producer know the consumer? | No | No (anyone can call a command) | No |
|
|
26
|
+
| Target not online | Doesn't matter — if nobody listens, nobody listens | Command not registered → no-op | The subscriber is responsible |
|
|
27
|
+
| Good for | event broadcasting, state changes, data sharing | exposing capabilities for others to call | serial data, LSP output, directory changes |
|
|
28
|
+
| Analogy | a loudspeaker in the square | a service counter calling numbers | a water tap |
|
|
29
|
+
|
|
30
|
+
**All three can be used at once.** When the terminal receives a burst of serial data it can simultaneously:
|
|
31
|
+
- broadcast it to the logger plugin via `events.emit` (everyone who should know gets it)
|
|
32
|
+
- push it to the protocol parser through the data pipeline `serial.onData` (high-frequency, streaming, carrying a port routing key)
|
|
33
|
+
- expose `registerCommand('xxx.send', handler)` so other plugins can send data back to the device
|
|
34
|
+
|
|
35
|
+
> Historically there was a "back-door p2p" as a second pipe — see §4: it is implemented, but its `target` routing has been removed and its semantics were normalized to in-pool broadcast.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 3. Broadcast `events` — a loudspeaker in the square
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
Terminal Protocol Logger plugin
|
|
43
|
+
│ │ │
|
|
44
|
+
│ events.emit( │ │
|
|
45
|
+
│ 'serial:rawData', │ │
|
|
46
|
+
│ { portName, text } │ │
|
|
47
|
+
│ ) │ │
|
|
48
|
+
│ ↓ │ │
|
|
49
|
+
│ Core broadcast │ │
|
|
50
|
+
│ (pool + shell, by channel) │ │
|
|
51
|
+
│ ↓ ↓ ↓
|
|
52
|
+
│ events.on( events.on(
|
|
53
|
+
│ 'serial:rawData', 'serial:rawData',
|
|
54
|
+
│ callback callback
|
|
55
|
+
│ ) )
|
|
56
|
+
│ parse bytes log entries
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**The sender does not know who is listening.** Zero listeners, one listener, ten listeners — all the same; `emit` and it is done.
|
|
60
|
+
|
|
61
|
+
**Channel names are strings.** The core has no idea what `'serial:rawData'` means. The naming convention is `<pluginId>:<dataName>`.
|
|
62
|
+
|
|
63
|
+
**Code (the `on<T>` generic — the payload type is inferred from the subscriber's callback; for cross-process type safety see §11):**
|
|
64
|
+
```typescript
|
|
65
|
+
// ── Emit data (plugin A) ──
|
|
66
|
+
window.linkdesk.events.emit('serial:rawData', {
|
|
67
|
+
portName: 'COM3',
|
|
68
|
+
text: '\xAA\x01\x02'
|
|
69
|
+
})
|
|
70
|
+
|
|
71
|
+
// ── Receive data (plugin B) ──
|
|
72
|
+
const unsub = window.linkdesk.events.on<{ portName: string; text: string }>(
|
|
73
|
+
'serial:rawData',
|
|
74
|
+
(data) => {
|
|
75
|
+
console.log(data.portName, data.text) // COM3, \xAA\x01\x02
|
|
76
|
+
}
|
|
77
|
+
)
|
|
78
|
+
// Clean up when the component unmounts
|
|
79
|
+
// unsub()
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**The channel broadcasts to "pool + shell".** A pool emit → main process `plugin:emit` → broadcast `plugin:push` → both the pool and the shell receive it. To send from the pool directly to the shell without coming back = `p2p` (§4).
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## 4. The `p2p` back door — a phone in a private room (implemented; `target` routing removed)
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
Terminal Protocol
|
|
90
|
+
│ │
|
|
91
|
+
│ p2p.send( │
|
|
92
|
+
│ 'sbq-protocol', ← specifies the recipient (historical semantics)
|
|
93
|
+
│ 'serial:raw', │
|
|
94
|
+
│ data │
|
|
95
|
+
│ ) │
|
|
96
|
+
│ ↓ │
|
|
97
|
+
│ Main process sends to pool │
|
|
98
|
+
│ (bypassing broadcast) │
|
|
99
|
+
│ ↓ │
|
|
100
|
+
│ p2p.on('serial:raw', callback)
|
|
101
|
+
│ filtered by channel — not broadcast
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**Status: implemented, no longer a "plan".** Signature:
|
|
105
|
+
|
|
106
|
+
```typescript
|
|
107
|
+
interface P2pApi {
|
|
108
|
+
send(target: string, channel: string, data: unknown): void; // fire-and-forget
|
|
109
|
+
on(channel: string, cb: (data: unknown) => void): () => void; // returns an unsubscribe
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
**⚠️ `target` routing has been removed.** Now that per-tab WebViews (one instance per plugin) no longer exist, the only receiver is the pool — the `target` parameter is kept (for backward compatibility; the signature is not deleted) but **it takes no part in routing**: whatever you send goes to the pool, and whoever calls `p2p.on` on the same channel receives it. **Zero validation, zero errors** — a wrong target will not report "target not running".
|
|
114
|
+
|
|
115
|
+
**How p2p differs from events today:**
|
|
116
|
+
- `events.emit` → broadcast `plugin:push` → **both the pool and the shell** receive it (the shell can add bridge wiring, see §11)
|
|
117
|
+
- `p2p.send` → the main process sends straight to the **pool** (a separate `p2p:data` channel), bypassing the broadcast
|
|
118
|
+
|
|
119
|
+
So: if you need shell wiring → use events; if you only intend to pass data between plugins and do not want to trigger the shell bridge → p2p. In high-frequency scenarios the performance difference no longer matters (dispatch happens in-process within a single pool). New code defaults to events; p2p is for a targeted test channel that does not disturb the shell's broadcast path (serial-monitor's `test-p2p` is exactly that usage).
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 5. Commands `commands` — calling numbers at the service counter
|
|
124
|
+
|
|
125
|
+
**A plugin's "capability" = a set of named commands.** Someone else (the shell or another plugin) invoking it = `executeCommand`.
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
// ── Plugin A registers a capability (on component mount) ──
|
|
129
|
+
window.linkdesk.commands.registerCommand('serial-monitor.send', (args?: { text: string }) => {
|
|
130
|
+
// Send data to the serial port
|
|
131
|
+
})
|
|
132
|
+
|
|
133
|
+
// ── Plugin B invokes the capability ──
|
|
134
|
+
await window.linkdesk.commands.executeCommand('serial-monitor.send', { text: 'AT\r\n' })
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
**Registration semantics:**
|
|
138
|
+
- `registerCommand` is idempotent (Map.set overwrites) — safe under StrictMode double-mounting
|
|
139
|
+
- `when: "false"` = a purely programmatic command that does not enter the command palette (commands dedicated to `titleActions` are declared this way; see `08`)
|
|
140
|
+
- **Commands are the delivery mechanism for `titleActions`** — the declarative `titleActions` widget's `command` field is executed on click by the pool side via `executeCommand` (pool-side registry first, shell IPC as fallback)
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 6. The data pipeline — a stream, not an event
|
|
145
|
+
|
|
146
|
+
Broadcast `events` handles "one-off notifications"; **the data pipeline handles "a continuous flow being poured in"**. Serial data, LSP output and directory changes are all streams — not "telling you once" but "pouring into you continuously".
|
|
147
|
+
|
|
148
|
+
| Pipeline | API | Payload | Routing key |
|
|
149
|
+
|------|------|------|------|
|
|
150
|
+
| Serial data | `serial.onData(cb)` | `SerialDataPayload` | `portName` (multiple ports) |
|
|
151
|
+
| Serial stats | `serial.onStats(cb)` | `SerialStatsPayload` | `portName` |
|
|
152
|
+
| Serial system events | `serial.onSystem(cb)` | `SerialSystemPayload` | `portName` |
|
|
153
|
+
| LSP output | `lsp.onData(cb)` | `(channelId: string, data: string)` | `channelId` |
|
|
154
|
+
| Directory changes | `filesystem.watch(dir, cb)` | `FileChangeEvent` | — (internally `filesystem:changed:<watcherId>`) |
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
// Subscribe to serial data — the payload is an object carrying the portName routing key: multiple ports coexist, each receives its own
|
|
158
|
+
const unsub = window.linkdesk.serial.onData((p) => {
|
|
159
|
+
if (p.portName !== 'COM3') return; // the consumer filters — the shell does not collect on your behalf
|
|
160
|
+
handleBytes(p.data);
|
|
161
|
+
});
|
|
162
|
+
// Cleanup on unmount
|
|
163
|
+
// unsub()
|
|
164
|
+
|
|
165
|
+
// Watch directory changes — returns an unsubscribe
|
|
166
|
+
const off = await window.linkdesk.filesystem.watch('/workspace', (e) => {
|
|
167
|
+
// e: FileChangeEvent
|
|
168
|
+
});
|
|
169
|
+
// off()
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
**Stream semantics (the RingBuffer lesson):**
|
|
173
|
+
- **Data is a stream, not an event.** It is not "notify once" — it is "pour in continuously". The subscriber provides its own buffering/filtering.
|
|
174
|
+
- **Consumers filter by routing key** (`portName` / `channelId`) — this is the general routing-key pattern: the consumer filters, the shell does not collect on anyone's behalf.
|
|
175
|
+
- **Consumers that need the full history** can `import { RingBuffer } from "@src/core/pipeline/RingBuffer"` (a pure-utility whitelist — `@src/core/pipeline/*` is the exception plugins are allowed to import, see `01 §5`). RingBuffer is a standard part for streaming consumption, not an event bus.
|
|
176
|
+
- **Internal normalization:** underneath, `serial.onData/onStats/onSystem` are simply `events.on("serial:data"/"stats"/"system")` — the three channels run over the broadcast pipe, with no separate direct channel. Plugins do not need to know these details; `serial.onXxx` is the only entry point.
|
|
177
|
+
|
|
178
|
+
---
|
|
179
|
+
|
|
180
|
+
## 7. The terminal — the first plugin to hand out data (historical reference)
|
|
181
|
+
|
|
182
|
+
> 2026-08-21 note: this section is a historical record from an early development phase, and **the terminal plugin's current implementation differs from the tasks below** (its data sources have been normalized onto the data pipeline). It is kept as a pattern reference for "how the first data-source plugin did it".
|
|
183
|
+
|
|
184
|
+
The terminal plugin originally handed three things to the hall:
|
|
185
|
+
|
|
186
|
+
| Step | What it does | Which API | Who benefits |
|
|
187
|
+
|---|--------|-----------|--------|
|
|
188
|
+
| 1 | Pushes raw serial data | `events.emit('serial:rawData', data)` | Protocol plugins subscribe and parse it |
|
|
189
|
+
| 2 | Broadcasts connection state | `events.emit('serial:connected', {...})` | The status bar / other plugins |
|
|
190
|
+
| 3 | Accepts a send command | `registerCommand('serial-monitor.send', handler)` | Workbench cards send data back to the MCU |
|
|
191
|
+
|
|
192
|
+
**The terminal did not build any API.** It only called functions the core already had: `events.emit`, `registerCommand`. Today's terminal runs over the `serial.onData/onStats/onSystem` data pipeline (§6) + commands (§5) — an evolved version of the same principle.
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
## 8. What every plugin does from here on
|
|
197
|
+
|
|
198
|
+
When a new plugin comes in, it answers two questions:
|
|
199
|
+
|
|
200
|
+
**1. What data do I have that others might need?**
|
|
201
|
+
→ If the data is a stream → use the data pipeline (§6, for serial/LSP/file scenarios) or `events.emit('channel-name', data)`. Name the channel by convention.
|
|
202
|
+
|
|
203
|
+
**2. What capabilities do I have that others might need to call?**
|
|
204
|
+
→ Call `registerCommand('command-name', handler)`. You pick the command name. `handler` is the function you write.
|
|
205
|
+
|
|
206
|
+
Once those two questions are answered, the plugin has no extra work to do. **The table belongs to the core, the pipes belong to the core, the functions belong to the core. Plugins only consume.**
|
|
207
|
+
|
|
208
|
+
---
|
|
209
|
+
|
|
210
|
+
## 9. Why it works this way
|
|
211
|
+
|
|
212
|
+
> "The terminal builds an API, and the protocol connects to the terminal's API"
|
|
213
|
+
|
|
214
|
+
**That is not the LinkDesk model.** That is the "open a door" model — every plugin you add means opening N×(N-1) doors among N plugins.
|
|
215
|
+
|
|
216
|
+
The LinkDesk model:
|
|
217
|
+
|
|
218
|
+
- **Pipes are built once by the core.** `events.emit`, `events.on`, `p2p.send`, `p2p.on`, `registerCommand`, `serial.onData` — these functions belong to the core, not to any plugin.
|
|
219
|
+
- **Channel names/command names are picked by the plugin.** `'serial:rawData'`, `'sbq-protocol:parsed'` — just strings; the core does not know what they mean.
|
|
220
|
+
- **A new data source = no core changes needed.** A new plugin calls the same `events.emit('new-channel-name', data)` line, and the core code changes by zero lines.
|
|
221
|
+
|
|
222
|
+
**The core's workload is O(1), not O(N).** That is what plugin freedom means.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 10. Related
|
|
227
|
+
|
|
228
|
+
- `01-plugin-api-contract.md` — §3.2 `events` (channel naming + the shell broadcast event table) and the `commands` runtime conventions; the single source of truth for method signatures = `contracts/linkdesk.d.ts` (`DataAPI.events/p2p` / `CommandsAPI`)
|
|
229
|
+
- `05-ui-conventions.md` — §8 plugin-owned data models (EventTarget); §9 system UI overlays (quickPick/notifications/dialog)
|
|
230
|
+
- `08-view-container-api.md` — how declarative `titleActions` are delivered through `executeCommand`
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## 🔥 11. Required reading for AI developers — how to add a new communication path when a new plugin needs one
|
|
235
|
+
|
|
236
|
+
> 2026-08-04. **A pattern discovered after the React Fallback retirement.**
|
|
237
|
+
> This is also the core loop of LinkDesk's plugin freedom — it is not a bug, it is the normal development process.
|
|
238
|
+
|
|
239
|
+
**Ask first: does this communication need the shell to take part?** The answer decides where you change things.
|
|
240
|
+
|
|
241
|
+
### 11.1 Scenario
|
|
242
|
+
|
|
243
|
+
You are developing a new plugin. It needs to receive some kind of external instruction (data sent by the shell or another plugin), but there is no matching event type in the existing `window.linkdesk.events`.
|
|
244
|
+
|
|
245
|
+
**Example:** the editor plugin needs to know which file was opened. But there is no `editor:openFile` event today — the editor's `sourceId` is passed via the React prop `<EditorView sourceId="xxx" />`.
|
|
246
|
+
|
|
247
|
+
### 11.2 Three cases, three kinds of change
|
|
248
|
+
|
|
249
|
+
| Case | Where to change | Does the shell need to change? |
|
|
250
|
+
|:--|:--|:--|
|
|
251
|
+
| **Plugin ↔ plugin** — just passing data between two plugins | **Zero changes.** `events.emit('myPlugin:xxx', payload)` + the other side's `events.on`. The channel is a free-form string contract; the subscriber narrows the payload | ❌ No |
|
|
252
|
+
| **Plugin → shell wiring** — the shell must react (close a tab / switch a view / show or hide) | **Add a bridge in `src/App/bridges.ts` (`useUiBridges`)**: a chunk of `events.on("channel", ...)` → `shellEvents.emit(...)` | ✅ Add a bridge only, no architecture change |
|
|
253
|
+
| **A cross-process payload needs type safety** | Define the payload type in the `src/core/api/` generation source → re-run `contracts:gen` to regenerate the contract → `import type` on both ends | ✅ Mechanically gated contract |
|
|
254
|
+
|
|
255
|
+
**Plugin ↔ plugin (most common, zero shell changes):**
|
|
256
|
+
```typescript
|
|
257
|
+
// Plugin A — send
|
|
258
|
+
window.linkdesk.events.emit('editor:openFile', { filePath: 'xxx' })
|
|
259
|
+
|
|
260
|
+
// Plugin B — receive (zero shell changes)
|
|
261
|
+
window.linkdesk.events.on('editor:openFile', ({ filePath }) => { ... })
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
**Plugin → shell wiring (add a bridge — the existing bridge list in `bridges.ts`):**
|
|
265
|
+
|
|
266
|
+
| Bridge (built into `bridges.ts`) | What the shell wiring does |
|
|
267
|
+
|:--|:--|
|
|
268
|
+
| `icon:selected` / `icon:reordered` | Icon bar click opens a tab / drag-to-reorder is persisted |
|
|
269
|
+
| `file:deleted` / `file:renamed` | File-tree resource events → TabManager closes a tab / migrates a label |
|
|
270
|
+
| `panel:viewSelected` / `panel:resize` / `panel:toggleViewVisibility` | Panel switches view / drag to change height / checkbox shows-hides |
|
|
271
|
+
| `panel:createView` | Panel [+] → QuickPick view picker |
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
// Template for adding a bridge on the shell side (compare with the existing file:deleted bridge):
|
|
275
|
+
useEffect(() => {
|
|
276
|
+
const off = window.linkdesk?.events?.on("myPlugin:someEvent", (payload) => {
|
|
277
|
+
shellEvents.emit("myPlugin:someEvent", payload);
|
|
278
|
+
});
|
|
279
|
+
return () => { off?.(); };
|
|
280
|
+
}, []);
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
**Shell-side event types** (the payloads of `shellEvents.emit`) are defined in `src/core/react/events/ShellEvents.ts` — add a line to the type table when needed.
|
|
284
|
+
|
|
285
|
+
### 11.3 When communication is actually needed
|
|
286
|
+
|
|
287
|
+
| Scenario | Communication needed? | Which one |
|
|
288
|
+
|:--|:--|:--|
|
|
289
|
+
| A new plugin needs to receive shell instructions | ✅ Yes | Add a bridge in the shell's `bridges.ts` → subscribe with `events.on` |
|
|
290
|
+
| A new plugin pushes data to other plugins | ✅ Yes | `events.emit` (events) or the data pipeline (streams) |
|
|
291
|
+
| A new plugin only manages state internally | ❌ No | Component state / a plugin-owned EventTarget model (`05 §8`) |
|
|
292
|
+
| A new plugin needs to read configuration | ❌ No | `linkdesk.configuration.get()` |
|
|
293
|
+
| A new plugin needs to manipulate files | ❌ No | `linkdesk.filesystem` |
|
|
294
|
+
|
|
295
|
+
### 11.4 Key principles
|
|
296
|
+
|
|
297
|
+
- **`contracts/linkdesk.d.ts` is the single source of truth for API signatures; `bridges.ts` is the collection of shell↔pool bridges.** A new AI only needs to read these two to know the entire communication surface.
|
|
298
|
+
- **Adding communication is normal, not a hack.** LinkDesk is designed so that "the shell is empty and the APIs grow inside the pipes". VS Code grew from 10 APIs to 1000+; LinkDesk works the same way — the channel table keeps growing.
|
|
299
|
+
- **Do not write plugin-specific branches into the shell.** The shell only forwards `emit`/`on` — plugins handle their own business logic.
|