@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,405 @@
1
+ # 08 — The ViewContainer API
2
+
3
+ > 2026-07-30 · full update 2026-08-21. **How plugins register sidebar/panel views.** Aligned with VS Code's `contributes.viewsContainers` + `contributes.views`.
4
+ > Every plugin with a sidebar (file-tree/marketplace/serial-monitor) goes through this API. Panel views (`location: "panel"`) use the same mechanism.
5
+ > **2026-09-06 reconciliation against the implementation** (audit): flattened single root (no plugins/{builtin,user}) · shared widgets live in @linkdesk/ui · distribution = a .linkdesk-plugin zip. The corresponding mechanism references on this page have been cleaned out.
6
+
7
+ ---
8
+
9
+ ## 1. Concepts
10
+
11
+ ```
12
+ ┌────────────────────────────────────────┐
13
+ │ Sidebar (SidebarZone) │
14
+ │ ┌────────────────────────────────────┐ │
15
+ │ │ Explorer [◀ Collapse][+][🔄] │ │ ← container header (ViewContainer.title) + titleActions
16
+ │ ├────────────────────────────────────┤ │
17
+ │ │ ▶ FOLDERS │ │ ← view (SidebarSection — independently collapsible)
18
+ │ │ src/ │ │
19
+ │ │ docs/ │ │
20
+ │ │ │ │
21
+ │ │ ▶ OUTLINE (language plugin) │ │ ← a view registered by another plugin — file-tree knows nothing about it
22
+ │ │ functionA() │ │
23
+ │ │ │ │
24
+ │ │ ▶ TIMELINE (Git plugin) │ │ ← yet another plugin's registered view
25
+ │ │ M modified.ts │ │
26
+ │ └────────────────────────────────────┘ │
27
+ └────────────────────────────────────────┘
28
+
29
+ ┌────────────────────────────────────────┐
30
+ │ Bottom Panel (PanelZone) │ ← containers with location: "panel" render here
31
+ │ ┌─────────┬─────────┐ │
32
+ │ │ Output │ To-do │ │ ← panel tab bar (switcher) + the active view's titleActions
33
+ │ └─────────┴─────────┘ │
34
+ └────────────────────────────────────────┘
35
+ ```
36
+
37
+ - **ViewContainer** = one "channel" of the sidebar/panel. Click the icon in the icon bar to switch. Examples: `explorer` / `marketplace` / `serial-monitor` / `panel-demo`.
38
+ - **View** = one collapsible section inside a container. Examples: `folders` / `sessions` / `settings`.
39
+ - **Any plugin** can register views into someone else's container. The container's owner neither knows nor cares.
40
+ - **Where it renders is decided by `location`**: `"sidebar"` → the left sidebar SidebarZone; `"panel"` → the bottom panel PanelZone (the tab bar switches views); `"auxiliarybar"` → the right auxiliary sidebar RightSidebarZone — ⚠ **not wired up in the shell today (it does not render; the region is dormant)**: declaring an auxiliarybar container/view = no surface, nothing visible. For third-party sidebar/panel needs use `"sidebar"`/`"panel"`. Every region renders views with the same `PoolSectionStack` (SidebarSection is wrapped automatically).
41
+
42
+ ---
43
+
44
+ ## 2. Declarative registration — plugin.json (the right way)
45
+
46
+ **🔥 Every view must be declared in plugin.json.** `render` is a component module path string — the loader loads the component and registers it into the shell. **The `render` field is a function/component and cannot cross IPC** — a render passed to the runtime `registerView` (§4) is stripped by the pool-side whitelist. So: **components always come from a plugin.json declaration; runtime calls only update metadata.**
47
+
48
+ ```json
49
+ {
50
+ "contributes": {
51
+ "viewsContainers": {
52
+ "explorer": {
53
+ "title": "Explorer",
54
+ "location": "sidebar",
55
+ "hideIfEmpty": false,
56
+ "order": 100
57
+ }
58
+ },
59
+ "views": {
60
+ "explorer": [
61
+ {
62
+ "id": "folders",
63
+ "title": "",
64
+ "render": "src/views/FoldersView.tsx",
65
+ "order": 0,
66
+ "collapsed": false,
67
+ "titleActions": []
68
+ }
69
+ ]
70
+ }
71
+ }
72
+ }
73
+ ```
74
+
75
+ ### viewsContainers fields
76
+
77
+ | Field | Required | Type | Description |
78
+ |------|:--:|------|------|
79
+ | `title` | ✅ | string | The name shown in the sidebar header. E.g. "Explorer" |
80
+ | `location` | ❌ | `"sidebar"` \| `"panel"` \| `"auxiliarybar"` \| `"main"` | Container location. Defaults to `"sidebar"` (see the render regions in §1). `"main"` = the main-area tab render surface — declared only by the active factoryRole plugin (the marketplace), consumed by the shell's ShellViewRenderer |
81
+ | `hideIfEmpty` | ❌ | boolean | Hide automatically when there are no active views. Defaults to `false` |
82
+ | `order` | ❌ | number | Ordering among containers in the same location. Smaller values come first |
83
+ | `icon` | ❌ | string | Container icon — overrides the plugin's own icon |
84
+ | `mergeHeaderWhenSingle` | ❌ | boolean | When the container holds only one view, hide the view's collapse header — the title merges into the container header. Aligned with VS Code's `mergeViewWithContainerWhenSingleView` (the `panel-demo` sidebar container uses exactly this mode) |
85
+
86
+ ### views fields (full table)
87
+
88
+ | Field | Required | Type | Description |
89
+ |------|:--:|------|------|
90
+ | `id` | ✅ | string | Unique view ID. Naming suggestion: `<feature-name>`, e.g. `folders` / `sessions` |
91
+ | `render` | ✅ | string | Component module path. **Relative to the plugin directory.** E.g. `"src/views/FoldersView.tsx"` |
92
+ | `title` | ❌ | string | SidebarSection collapse-header title. An empty string = no collapse header, the content renders directly |
93
+ | `role` | ❌ | `"toolbar"` \| `"section"` | Container role. Defaults to `"section"` (has a collapse header); `"toolbar"` = stuck to the top, not covered by sections. Replaces the empty-title hack |
94
+ | `order` | ❌ | number | Ordering within the container. Smaller values on top |
95
+ | `collapsed` | ❌ | boolean | Initially collapsed. Defaults to `false` |
96
+ | `when` | ❌ | string | Context key condition — the view is shown only when satisfied. E.g. `"explorerFocus"` |
97
+ | `canToggleVisibility` | ❌ | boolean | ✅ Implemented — the user can toggle visibility from the panel switcher / the sidebar's "Views" submenu |
98
+ | `canMoveView` | ❌ | boolean | ✅ Implemented — the user can drag this view into another container |
99
+ | `hideByDefault` | ❌ | boolean | ✅ Implemented — hidden by default; the user must switch it on manually from the view menu |
100
+ | `titleDescription` | ❌ | string | Secondary text next to the title. Aligned with VS Code's `ViewPane.titleDescription` |
101
+ | `singleViewPaneContainerTitle` | ❌ | string | With a single view and `mergeHeaderWhenSingle`, the container header shows this title instead of the container title |
102
+ | `minHeight` | ❌ | number | Minimum height for drag-resizing (px). Defaults to 100 if not declared |
103
+ | `showActions` | ❌ | `"always"` \| `"whenExpanded"` \| `"default"` | Controls when the action area is shown. Aligned with VS Code's `ViewPaneShowActions` |
104
+ | `titleTooltip` | ❌ | string | Title hover tooltip — shows the full text when the title is truncated |
105
+ | `badge` | ❌ | string \| number | Marker to the right of the title — a number or short text (e.g. the installed count "15") |
106
+ | `titleActions` | ❌ | `TitleActionWidget[]` | **The view action area's declaration system** — see §3 |
107
+
108
+ ---
109
+
110
+ ## 3. Declarative titleActions — the action area on the right of a view header
111
+
112
+ **Aligned with VS Code's `[+][🔄][⊟]` on the right of a view header / the terminal's `[+][▾]`.** Declared in `contributes.views[].titleActions` and consumed by the shell's uniform renderer `ViewTitleActions.tsx` — **it travels with the view, and moves with the view** (when the view moves between the panel and the sidebar, the action area comes along).
113
+
114
+ ### The three widget forms
115
+
116
+ | Type | Form | Click behavior |
117
+ |------|------|------|
118
+ | `icon` | A single icon button | Executes `command` |
119
+ | `dropdown` | A pure dropdown (chevron) | Expands the `items` list; clicking an entry executes its `command` |
120
+ | `split` | A primary button + dropdown combined | The primary button executes `command` (the default action); the chevron on the right expands the `items` alternatives |
121
+
122
+ **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, e.g. `"codicon-add"`), `title` (tooltip/aria-label/text when there is no icon), `items` (the alternative entries of a dropdown/split: `{ label, command, args }`).
123
+
124
+ ### A real example — panel-demo (the official verification plugin)
125
+
126
+ ```json
127
+ {
128
+ "id": "demo-output",
129
+ "title": "Output",
130
+ "render": "src/views/DemoOutputView.tsx",
131
+ "order": 0,
132
+ "titleActions": [
133
+ {
134
+ "type": "split",
135
+ "id": "add-log",
136
+ "command": "panel-demo.addLog",
137
+ "icon": "codicon-add",
138
+ "title": "Add a demo log",
139
+ "args": { "level": "info", "text": "The primary button — add an info log" },
140
+ "items": [
141
+ { "label": "Add info", "command": "panel-demo.addLog", "args": { "level": "info" } },
142
+ { "label": "Add warning", "command": "panel-demo.addLog", "args": { "level": "warn" } },
143
+ { "label": "Add error", "command": "panel-demo.addLog", "args": { "level": "error" } }
144
+ ]
145
+ },
146
+ {
147
+ "type": "icon",
148
+ "id": "clear-log",
149
+ "command": "panel-demo.clearLog",
150
+ "icon": "codicon-clear-all",
151
+ "title": "Clear output"
152
+ }
153
+ ]
154
+ }
155
+ ```
156
+
157
+ ### Registering titleActions commands
158
+
159
+ The source of truth for executing a `command` declared in `titleActions` = **the pool-side command registry** (`executeCommand` prefers the pool side, with shell IPC as fallback). Command handlers are registered inside the view component:
160
+
161
+ ```tsx
162
+ // DemoOutputView.tsx (the real panel-demo code)
163
+ useEffect(() => {
164
+ const api = window.linkdesk?.commands;
165
+ api?.registerCommand?.(
166
+ "panel-demo.addLog",
167
+ (args?: { level?: LogLevel; text?: string }) => {
168
+ addLine(args?.level ?? "info", args?.text ?? "");
169
+ },
170
+ // Registered through the pool-side registerCommand — `when` is left to the declaration system;
171
+ // when:"false" = a purely programmatic command that does not enter the command palette (titleActions-only)
172
+ );
173
+ api?.registerCommand?.("panel-demo.clearLog", () => clearLines());
174
+ }, []);
175
+ ```
176
+
177
+ > **`when: "false"` = a purely programmatic command that does not enter the command palette** — commands dedicated to titleActions are all declared this way, to keep them from flooding Ctrl+Shift+P.
178
+
179
+ ### Render locations (one renderer, two consumers)
180
+
181
+ - **Panel containers (PanelZone)**: the action area on the right of the tab bar — rendered from the **active view**'s titleActions (`PanelZone.tsx`)
182
+ - **Sidebar containers (SidebarZone/RightSidebarZone)**: on the right of a section's collapse header — each view renders its own (`PoolSectionStack` injects the SidebarSection actions slot); with `mergeHeaderWhenSingle` and a single view, the container header is the view header and it consumes the same way
183
+
184
+ **Zero declarations (`titleActions: []`) → renders null (the right side stays blank, preserving the status quo).** The widget is a general-purpose part, not something built for the terminal — whoever declares it, uses it (the iron rule of plugin independence: a third party declares and it just works, with zero shell changes).
185
+
186
+ ---
187
+
188
+ ## 4. Runtime updates and queries — `window.linkdesk.viewContainer`
189
+
190
+ **The declarative side (§2) governs "which views exist"; the runtime API governs "metadata updates + queries".** The source of truth for a view's metadata is the shell's `ViewContainerService` (the pool reaches it over real IPC).
191
+
192
+ ```typescript
193
+ // Query — returns a DTO (serializable public fields; render/actions are stripped)
194
+ const views = await window.linkdesk.viewContainer.getViews("explorer"); // ViewDto[]
195
+ const view = await window.linkdesk.viewContainer.getView("folders"); // ViewDto | undefined
196
+ const container = await window.linkdesk.viewContainer.getViewContainer("explorer");
197
+
198
+ // Update metadata — the title follows the data (aligned with VS Code's registerViews update)
199
+ // Calling repeatedly with the same (pluginId, viewId) = update the existing view; render is kept
200
+ // (render cannot cross IPC and is stripped by the pool-side whitelist)
201
+ await window.linkdesk.viewContainer.registerView("file-tree", "explorer", {
202
+ id: "folders",
203
+ title: newFolderName, // Update the title only — other fields are optional
204
+ minHeight: 180,
205
+ });
206
+ ```
207
+
208
+ **Rules:**
209
+ - Calling `registerView` repeatedly with the same `(pluginId, viewId)` pair = **updating the existing view**. A field you omit keeps its original value.
210
+ - **`render` is a function — it cannot cross IPC** (invoke's structured clone throws `DataCloneError`; the pool-side whitelist `toViewMetaDto` strips it). **Never pass a component through runtime registration** — components must be declared in plugin.json (§2); the runtime only updates metadata.
211
+ - Querying a container/view that does not exist → `undefined` / `[]`.
212
+
213
+ ### View change broadcasts
214
+
215
+ A change to the shell's registry triggers `events.emit("viewContainer:changed", { containerId, views: DTO[] })` — plugins can subscribe (marketplace uses it to refresh its UI after views are registered):
216
+
217
+ ```typescript
218
+ const unsub = window.linkdesk.events.on<{ containerId: string }>(
219
+ "viewContainer:changed",
220
+ ({ containerId }) => { refresh(containerId); }
221
+ );
222
+ ```
223
+
224
+ ### Shell-side write APIs (plugins never call these directly — cross-plugin interaction goes through the UI/bridges)
225
+
226
+ The following methods live in the shell's `ViewContainerService` (`src/core/services/layout/ViewContainerService.ts`) — the plugin side is **forbidden to import that module** (the ESLint `noCoreImportInPlugin` error level, see `01 §5`). **User actions** that show/hide, move or reorder views are carried automatically from the pool-side UI to the shell over an IPC bridge:
227
+
228
+ | Shell method | Meaning | How a plugin triggers it |
229
+ |--------|------|------|
230
+ | `setVisible(containerId, viewId, visible)` / `isVisible` / `toggleViewVisibility` | View visibility (+ persistence) | Checking a box in the panel switcher, via the `panel:toggleViewVisibility` bridge |
231
+ | `moveView(viewId, from, to, newIndex?)` | Cross-container migration | Drag and drop (the `viewDragProtocol` MIME) |
232
+ | `reorderView(containerId, viewId, newIndex)` | Reorder within a container (+ persistence) | Drag a header to reorder |
233
+ | `registerViewEmptyContent(containerId, viewId, content, when?)` | View empty-state placeholder (shown when there is no data) | — |
234
+
235
+ > A plugin that wants to show/hide or move views "programmatically" = go through `executeCommand` (calling the shell-side service inside a command handler registered by the shell or a plugin), or `panel.reveal` (see §5).
236
+
237
+ ---
238
+
239
+ ## 5. Panel views — `location: "panel"` + `panel.reveal`
240
+
241
+ Panel containers (`location: "panel"`) render in the bottom PanelZone, with the tab bar switching views. **Focusing a bottom-panel view = `window.linkdesk.panel.reveal(viewId)`** (aligned with VS Code's view-promotion semantics):
242
+
243
+ ```typescript
244
+ await window.linkdesk.panel.reveal("demo-output"); // focus the demo-output view in the bottom panel
245
+ ```
246
+
247
+ - Panel hidden → expand it and switch to that view (the same mechanism as Ctrl+J)
248
+ - Panel already shown → switch focus
249
+ - `viewId` not in a panel container → **no-op** (no error)
250
+
251
+ **Complete panel container example — panel-demo:**
252
+
253
+ ```json
254
+ {
255
+ "contributes": {
256
+ "viewsContainers": {
257
+ "panel-demo": { "title": "Panel Demo", "location": "panel" },
258
+ "panel-demo-sidebar": { "title": "Panel Demo", "location": "sidebar" }
259
+ },
260
+ "views": {
261
+ "panel-demo": [
262
+ { "id": "demo-output", "title": "Output", "render": "src/views/DemoOutputView.tsx", "order": 0, "titleActions": [/* §3 */] },
263
+ { "id": "demo-todo", "title": "To-do", "render": "src/views/DemoTodoView.tsx", "order": 1 }
264
+ ],
265
+ "panel-demo-sidebar": [
266
+ { "id": "demo-sidebar", "title": "Sidebar Demo", "render": "src/views/DemoSidebarView.tsx", "order": 0, "titleActions": [/* §3 */] }
267
+ ]
268
+ }
269
+ }
270
+ }
271
+ ```
272
+
273
+ > The same plugin can declare a panel container and a sidebar container at the same time (each belongs to its own zone). **`panel.moveToEditor` has been removed** — moving zones is the job of layout commands.
274
+
275
+ ---
276
+
277
+ ## 6. View component authoring conventions
278
+
279
+ ### Component signature
280
+
281
+ ```typescript
282
+ // src/views/MyView.tsx
283
+ export default function MyView() {
284
+ // A standard React component — exactly like writing any ordinary component
285
+ return <div>...</div>;
286
+ }
287
+ ```
288
+
289
+ ### Do not wrap SidebarSection yourself
290
+
291
+ **❌ Wrong:**
292
+ ```tsx
293
+ export default function MyView() {
294
+ return (
295
+ <SidebarSection title="My View">
296
+ <div>content</div>
297
+ </SidebarSection>
298
+ );
299
+ }
300
+ ```
301
+
302
+ **✅ Right:**
303
+ ```tsx
304
+ export default function MyView() {
305
+ // PoolSectionStack wraps it in SidebarSection automatically — no need to wrap it yourself
306
+ return <div>content</div>;
307
+ }
308
+ ```
309
+
310
+ The render loop (shell `usePoolSync` → pool `PoolSectionStack`):
311
+ ```tsx
312
+ views.map(view => (
313
+ <SidebarSection key={view.id} title={view.title} defaultOpen={!view.collapsed}>
314
+ <PluginComponent renderPath={view._renderPath} />
315
+ </SidebarSection>
316
+ ))
317
+ ```
318
+
319
+ A view component is responsible only for the **content area**. Collapsing/expanding and the title are managed uniformly by SidebarSection.
320
+
321
+ ### An empty title string
322
+
323
+ `"title": ""` → SidebarSection does not render the collapse header — the content shows directly. Suited to the "single view, no collapsing needed" case. E.g. file-tree's `folders` view. For a multi-section scenario use `role` rather than a title hack.
324
+
325
+ ### Toolbar buttons
326
+
327
+ A view may freely place toolbar buttons at the top of its content — these are not SidebarSection's header actions (those go through the declarative titleActions, §3). The content area is entirely free:
328
+
329
+ ```tsx
330
+ export default function MyView() {
331
+ return (
332
+ <>
333
+ <div className="my-toolbar">
334
+ <button onClick={...}>+ New</button>
335
+ </div>
336
+ <div className="my-content">...</div>
337
+ </>
338
+ );
339
+ }
340
+ ```
341
+
342
+ ---
343
+
344
+ ## 7. Full example — a Git plugin registering TIMELINE into Explorer
345
+
346
+ ```json
347
+ // git/plugin.json
348
+ {
349
+ "contributes": {
350
+ "views": {
351
+ "explorer": [
352
+ {
353
+ "id": "timeline",
354
+ "title": "TIMELINE",
355
+ "render": "src/views/TimelineView.tsx",
356
+ "order": 100,
357
+ "when": "gitOpen"
358
+ }
359
+ ]
360
+ }
361
+ }
362
+ }
363
+ ```
364
+
365
+ ```typescript
366
+ // git/src/views/TimelineView.tsx
367
+ export default function TimelineView() {
368
+ // ... read the git log → render the list ...
369
+ return <div className="git-timeline">...</div>;
370
+ }
371
+ ```
372
+
373
+ The file-tree plugin changes by zero lines. TimelineView shows up automatically below FOLDERS.
374
+
375
+ ---
376
+
377
+ ## 8. Lifecycle
378
+
379
+ ```
380
+ Plugin load
381
+ → loader parseContributions → declarative registration of viewsContainers + views (loading render components)
382
+ → component mount → runtime registerView updates metadata (title/order/minHeight)
383
+ → shell usePoolSync → pool PoolSectionStack renders getActiveViews(containerId)
384
+
385
+ Plugin unload
386
+ → ViewContainerService.unregisterAll(pluginId) (the reversible-registration tracker rolls back in reverse order)
387
+ → all of that plugin's containers + all its views are removed
388
+ → events.emit("viewContainer:changed") broadcast
389
+ → the pool re-renders — other plugins' views are unaffected
390
+ ```
391
+
392
+ ## 9. When to use declarative vs. runtime
393
+
394
+ | Scenario | Approach |
395
+ |------|------|
396
+ | The view title never changes | plugin.json, declarative (§2) |
397
+ | The view title follows the data (e.g. "Send/Receive Settings — COM3") | plugin.json declaration + a runtime `registerView({ title: newTitle })` metadata update (§4) |
398
+ | A fixed number of views | plugin.json, declarative |
399
+ | The view needs an action area (buttons/dropdown on the right of the header) | the declarative `titleActions` in plugin.json (§3) |
400
+ | Need to focus a bottom-panel view | `window.linkdesk.panel.reveal(viewId)` (§5) |
401
+
402
+ ---
403
+
404
+ > **← Overview:** `00-readme.md`
405
+ > **→ Related:** `01-plugin-api-contract.md` `03-contributes-spec.md` `07-plugin-to-plugin-communication.md`