@opencode/plugin 0.0.0-dev-51 → 0.0.0-dev-56

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 (42) hide show
  1. package/dist/effect/integration.d.ts +5 -2
  2. package/dist/gui/browser.d.ts +36 -0
  3. package/dist/gui/browser.js +3 -0
  4. package/dist/gui/context.d.ts +223 -0
  5. package/dist/gui/context.js +0 -0
  6. package/dist/gui/core.d.ts +560 -0
  7. package/dist/gui/core.js +86 -0
  8. package/dist/gui/declarations.d.ts +24 -0
  9. package/dist/gui/declarations.js +0 -0
  10. package/dist/gui/file.d.ts +122 -0
  11. package/dist/gui/file.js +7 -0
  12. package/dist/gui/host-apis.d.ts +1109 -0
  13. package/dist/gui/host-apis.js +0 -0
  14. package/dist/gui/icon-name.d.ts +2 -0
  15. package/dist/gui/icon-name.js +1 -0
  16. package/dist/gui/index.d.ts +7 -0
  17. package/dist/gui/index.js +6 -0
  18. package/dist/gui/internal.d.ts +44 -0
  19. package/dist/gui/internal.js +33 -0
  20. package/dist/gui/main.d.ts +279 -0
  21. package/dist/gui/main.js +20 -0
  22. package/dist/gui/modules.d.ts +15 -0
  23. package/dist/gui/modules.js +30 -0
  24. package/dist/gui/plugin.d.ts +86 -0
  25. package/dist/gui/plugin.js +9 -0
  26. package/dist/gui/reactive.d.ts +93 -0
  27. package/dist/gui/reactive.js +130 -0
  28. package/dist/gui/registries.d.ts +770 -0
  29. package/dist/gui/registries.js +110 -0
  30. package/dist/gui/review.d.ts +73 -0
  31. package/dist/gui/review.js +3 -0
  32. package/dist/gui/scope.d.ts +64 -0
  33. package/dist/gui/scope.js +85 -0
  34. package/dist/gui/solid.d.ts +99 -0
  35. package/dist/gui/solid.js +74 -0
  36. package/dist/gui/vite.d.ts +24 -0
  37. package/dist/gui/vite.js +49 -0
  38. package/dist/host.d.ts +12 -1
  39. package/dist/host.js +34 -2
  40. package/dist/promise/integration.d.ts +5 -2
  41. package/dist/runtime-modules.js +3 -1
  42. package/package.json +54 -10
@@ -0,0 +1,1109 @@
1
+ import type { Data } from "@opencode/client/solid";
2
+ import type { LocationRef, OpenCodeClient, ProjectListOutput, WorktreeDirectory } from "@opencode/client/promise";
3
+ import type { Schema } from "effect";
4
+ import type { JSX } from "solid-js";
5
+ import type { Store } from "solid-js/store";
6
+ import type { Cleanup, OS, Persisted, StoreFrom } from "./core.js";
7
+ import type { IconName, Link, SessionPanelMenuItem } from "./registries.js";
8
+ /**
9
+ * A server the app lists. One ref per id that follows the live connection: read `client`, `data` and `url` from it
10
+ * each time, as a restarted or re-authenticated server gets a new controller under the same id.
11
+ */
12
+ export interface ServerRef {
13
+ /** Host key: "sidecar", an http URL, or `${plugin}:${id}` for servers a plugin contributes. */
14
+ readonly id: string;
15
+ /** Display name; the id when the server has none. */
16
+ readonly name: string;
17
+ /** The server's base URL. */
18
+ readonly url: string;
19
+ /** The HTTP basic password the user configured; undefined when there is none. */
20
+ readonly password?: string;
21
+ /** The server's API client. */
22
+ readonly client: OpenCodeClient;
23
+ /** The server's synced data (sessions, projects, …). Reactive. */
24
+ readonly data: Data;
25
+ /** The built-in local server or a loopback http server. */
26
+ readonly local: boolean;
27
+ /** The app's own server, the desktop sidecar. */
28
+ readonly builtin: boolean;
29
+ /** The server's version works with this app; false after a health check found it incompatible. */
30
+ readonly compatible: boolean;
31
+ /** The event connection to this server is up. */
32
+ readonly connected: boolean;
33
+ }
34
+ /** A session owned by an open shell tab, mounted or not. */
35
+ export interface SessionRef {
36
+ /** `${server id}\n${session id}`: unique across servers. Key per-session state by it. */
37
+ readonly key: string;
38
+ /** The session's id on its server. */
39
+ readonly id: string;
40
+ /** The key of the shell tab that owns the session. */
41
+ readonly tab: string;
42
+ /** The session's server. */
43
+ readonly server: ServerRef;
44
+ /** The server is still creating the session. */
45
+ readonly pending: boolean;
46
+ /**
47
+ * Where the session runs. Undefined until the server reports it, and again while it is unknown, e.g. after the
48
+ * server re-authenticates. Layout reads return nothing meanwhile; layout writes wait for it.
49
+ */
50
+ readonly location: LocationRef | undefined;
51
+ }
52
+ /** A project as the sidebar lists it, with the worktrees found on disk and the user's local name and icon. */
53
+ export type Project = Omit<ProjectListOutput[number], "canonical"> & {
54
+ /** The project's root directory. */
55
+ worktree: string;
56
+ /** The project's worktrees. */
57
+ worktrees: WorktreeDirectory[];
58
+ };
59
+ /** A file's content as the server read it. */
60
+ export type FileContent = {
61
+ /**
62
+ * How to read `content`.
63
+ * - `text`: `content` is the text.
64
+ * - `binary`: `bytes` holds the raw bytes, `content` is base64 when `encoding` says so, or empty when only `size` is known.
65
+ */
66
+ type: "text" | "binary";
67
+ /** The text, or the base64 bytes of a binary file. */
68
+ content: string;
69
+ /** The raw bytes of a binary file, when kept without base64 encoding. */
70
+ bytes?: Uint8Array;
71
+ /** A unified diff of the file's uncommitted change, when there is one. */
72
+ diff?: string;
73
+ /** The same change, parsed. */
74
+ patch?: {
75
+ /** The file's name before the change. */
76
+ oldFileName: string;
77
+ /** The file's name after the change. */
78
+ newFileName: string;
79
+ /** The header of the old side. */
80
+ oldHeader?: string;
81
+ /** The header of the new side. */
82
+ newHeader?: string;
83
+ /** The changed regions. */
84
+ hunks: Array<{
85
+ /** First line of the hunk in the old file. */
86
+ oldStart: number;
87
+ /** Lines of the hunk in the old file. */
88
+ oldLines: number;
89
+ /** First line of the hunk in the new file. */
90
+ newStart: number;
91
+ /** Lines of the hunk in the new file. */
92
+ newLines: number;
93
+ /** The hunk's lines, each prefixed with " ", "+" or "-". */
94
+ lines: string[];
95
+ }>;
96
+ /** The diff's index line. */
97
+ index?: string;
98
+ };
99
+ /** `base64` when `content` holds encoded bytes. */
100
+ encoding?: "base64";
101
+ /** The file's MIME type, when the server knows it. */
102
+ mimeType?: string;
103
+ /** On-disk size when the bytes themselves are not retained. */
104
+ size?: number;
105
+ /** A URL the server streams the file from with range requests, set instead of `bytes` for images, audio and video. */
106
+ url?: string;
107
+ };
108
+ /** A range of lines in a file, or in one side of its diff. */
109
+ export interface LineRange {
110
+ /** The first line. */
111
+ start: number;
112
+ /** The last line. */
113
+ end: number;
114
+ /**
115
+ * The diff side `start` is on. Omit it for the file itself.
116
+ * - `additions`: the new side.
117
+ * - `deletions`: the old side.
118
+ */
119
+ side?: "additions" | "deletions";
120
+ /** The diff side `end` is on, when it differs from `side`. */
121
+ endSide?: "additions" | "deletions";
122
+ }
123
+ /** One file of the session's workspace as the file model holds it. */
124
+ export interface FileState {
125
+ /** The workspace-relative path. */
126
+ path: string;
127
+ /** The file's name. */
128
+ name: string;
129
+ /** The content has loaded at least once. */
130
+ loaded?: boolean;
131
+ /** A load is in flight. */
132
+ loading?: boolean;
133
+ /** The last load found no such file. */
134
+ notFound?: boolean;
135
+ /** The last load's error message. */
136
+ error?: string;
137
+ /** The loaded content. */
138
+ content?: FileContent;
139
+ }
140
+ /** An entry of the workspace file tree. */
141
+ export interface FileNode {
142
+ /** The entry's name. */
143
+ name: string;
144
+ /** The workspace-relative path. */
145
+ path: string;
146
+ /** The absolute path. */
147
+ absolute: string;
148
+ /**
149
+ * What the entry is.
150
+ * - `file`: a file.
151
+ * - `directory`: a directory.
152
+ */
153
+ type: "file" | "directory";
154
+ /** Ignored by the workspace's ignore files. */
155
+ ignored: boolean;
156
+ }
157
+ /** The session screen's workspace files: content, view state and the file tree, of the routed session. */
158
+ export interface Files {
159
+ /** The workspace root directory. */
160
+ readonly root: string;
161
+ /** The per-file view state (selection, scroll) has loaded. Reactive. */
162
+ ready(): boolean;
163
+ /**
164
+ * Normalizes a path, URL or `file://` link to a workspace-relative path. A path outside the root stays absolute.
165
+ *
166
+ * @param path - Any path or link to a file.
167
+ */
168
+ resolve(path: string): string;
169
+ /**
170
+ * Whether a normalized path is absolute, and so outside the workspace.
171
+ *
172
+ * @param path - A path from `resolve`.
173
+ */
174
+ absolute(path: string): boolean;
175
+ /**
176
+ * The file's state; undefined until `sync` first loads it. Reactive.
177
+ *
178
+ * @param path - A workspace-relative path.
179
+ */
180
+ get(path: string): FileState | undefined;
181
+ /**
182
+ * The last load found no such file. Unlike `get`, it does not touch the content cache.
183
+ *
184
+ * @param path - A workspace path.
185
+ */
186
+ missing(path: string): boolean;
187
+ /**
188
+ * Loads the file's content, once unless forced, and asks the server to watch a workspace file for changes.
189
+ *
190
+ * @param path - A workspace path.
191
+ * @param options - Load options.
192
+ */
193
+ sync(path: string, options?: {
194
+ /** Reloads even when the content has loaded. Defaults to false. */
195
+ readonly force?: boolean;
196
+ /** Suppresses the error toast when the load fails. Defaults to false. */
197
+ readonly silent?: boolean;
198
+ }): Promise<void>;
199
+ /**
200
+ * Stops the server watch `sync` started, for a file whose tab closed.
201
+ *
202
+ * @param path - A workspace path.
203
+ */
204
+ unwatch(path: string): void;
205
+ /**
206
+ * Whether a file exists, checked by listing its directory without reading the file.
207
+ *
208
+ * @param path - A workspace-relative or absolute path.
209
+ * @returns False when the file is missing or its directory cannot be listed.
210
+ */
211
+ exists(path: string): Promise<boolean>;
212
+ /**
213
+ * Searches the workspace by fuzzy path.
214
+ *
215
+ * @param query - The search text.
216
+ * @param options - Search options.
217
+ * @returns Matching workspace-relative paths, best first.
218
+ */
219
+ search(query: string, options?: {
220
+ /**
221
+ * What to match. Defaults to `file`.
222
+ * - `file`: files only.
223
+ * - `any`: files and directories.
224
+ */
225
+ readonly kind?: "file" | "any";
226
+ /** The most results to return. Defaults to the server's limit. */
227
+ readonly limit?: number;
228
+ /** Aborts the search, which then rejects. A search that fails otherwise resolves with no results. */
229
+ readonly signal?: AbortSignal;
230
+ }): Promise<string[]>;
231
+ /** The selected line range per file, kept with the session's view state. */
232
+ readonly selection: {
233
+ /**
234
+ * The file's selected range: null when the selection was cleared, undefined when none is stored. Reactive.
235
+ *
236
+ * @param path - A workspace path.
237
+ */
238
+ get(path: string): LineRange | null | undefined;
239
+ /**
240
+ * Selects a range, or clears the selection with null.
241
+ *
242
+ * @param path - A workspace path.
243
+ * @param range - The range to select.
244
+ */
245
+ set(path: string, range: LineRange | null): void;
246
+ };
247
+ /** The scroll offset per file, kept with the session's view state. */
248
+ readonly scroll: {
249
+ /**
250
+ * The file's stored scroll offset.
251
+ *
252
+ * @param path - A workspace path.
253
+ */
254
+ get(path: string): {
255
+ /** Vertical offset in CSS pixels; undefined when none is stored. */
256
+ readonly top?: number;
257
+ /** Horizontal offset in CSS pixels; undefined when none is stored. */
258
+ readonly left?: number;
259
+ };
260
+ /**
261
+ * Stores the file's scroll offset. An offset left out keeps its stored value.
262
+ *
263
+ * @param path - A workspace path.
264
+ * @param value - The offsets to store.
265
+ */
266
+ set(path: string, value: {
267
+ /** Vertical offset in CSS pixels. */
268
+ readonly top?: number;
269
+ /** Horizontal offset in CSS pixels. */
270
+ readonly left?: number;
271
+ }): void;
272
+ };
273
+ /** The workspace file tree, loaded one directory at a time. */
274
+ readonly tree: {
275
+ /**
276
+ * The loaded entries of a directory; empty until `sync` loads it. Reactive.
277
+ *
278
+ * @param path - A workspace-relative directory; "" for the root.
279
+ */
280
+ list(path: string): readonly FileNode[];
281
+ /**
282
+ * A directory's tree state; undefined before anything touched it. Reactive.
283
+ *
284
+ * @param path - A workspace-relative directory.
285
+ */
286
+ state(path: string): {
287
+ /** The directory is expanded. */
288
+ expanded: boolean;
289
+ /** Its entries have loaded. */
290
+ loaded?: boolean;
291
+ /** A load is in flight. */
292
+ loading?: boolean;
293
+ /** The last load's error message. */
294
+ error?: string;
295
+ } | undefined;
296
+ /**
297
+ * Loads a directory's entries, once unless forced.
298
+ *
299
+ * @param path - A workspace-relative directory.
300
+ * @param options - Load options.
301
+ */
302
+ sync(path: string, options?: {
303
+ /** Lists the directory again even when it has loaded. Defaults to false. */
304
+ readonly force?: boolean;
305
+ }): Promise<void>;
306
+ /**
307
+ * Expands a directory.
308
+ *
309
+ * @param path - A workspace-relative directory.
310
+ * @param options - Expand options.
311
+ */
312
+ expand(path: string, options?: {
313
+ /** False expands without loading its entries. Defaults to true. */
314
+ readonly list?: boolean;
315
+ }): void;
316
+ /**
317
+ * Collapses a directory.
318
+ *
319
+ * @param path - A workspace-relative directory.
320
+ */
321
+ collapse(path: string): void;
322
+ };
323
+ }
324
+ /** A line comment the user left on a workspace file, before it is sent. */
325
+ export interface Comment {
326
+ /** The comment's id. */
327
+ id: string;
328
+ /** When it was made, in milliseconds since the epoch. */
329
+ time: number;
330
+ /** The workspace path of the file. */
331
+ file: string;
332
+ /** The lines it is about. */
333
+ selection: LineRange;
334
+ /** The comment text. */
335
+ comment: string;
336
+ }
337
+ /** The session screen's line comments, by file, of the routed session's next prompt. */
338
+ export interface Comments {
339
+ /**
340
+ * The comments on one file, or on every file. Reactive.
341
+ *
342
+ * @param file - A workspace path; omit it for all comments.
343
+ */
344
+ list(file?: string): readonly Comment[];
345
+ /**
346
+ * Adds a comment and focuses it.
347
+ *
348
+ * @param input - The comment without its id and time.
349
+ * @returns The comment with its id and time.
350
+ */
351
+ add(input: Omit<Comment, "id" | "time">): Comment;
352
+ /**
353
+ * Replaces a comment's text. An unknown id does nothing.
354
+ *
355
+ * @param id - The comment's id.
356
+ * @param comment - The new text.
357
+ */
358
+ update(id: string, comment: string): void;
359
+ /**
360
+ * Removes a comment. An unknown id does nothing.
361
+ *
362
+ * @param id - The comment's id.
363
+ */
364
+ remove(id: string): void;
365
+ /** The comment a view should reveal and edit, e.g. the one just added. */
366
+ readonly focus: {
367
+ /** The focused comment, or null. Reactive. */
368
+ current(): {
369
+ /** The comment's file. */
370
+ readonly file: string;
371
+ /** The comment's id. */
372
+ readonly id: string;
373
+ } | null;
374
+ /**
375
+ * Focuses a comment, or clears the focus with null.
376
+ *
377
+ * @param value - The comment's file and id.
378
+ */
379
+ set(value: {
380
+ /** The comment's file. */
381
+ readonly file: string;
382
+ /** The comment's id. */
383
+ readonly id: string;
384
+ } | null): void;
385
+ };
386
+ /** The comment views mark as current. */
387
+ readonly active: {
388
+ /** The current comment, or null. Reactive. */
389
+ current(): {
390
+ /** The comment's file. */
391
+ readonly file: string;
392
+ /** The comment's id. */
393
+ readonly id: string;
394
+ } | null;
395
+ /**
396
+ * Marks a comment as current, or clears the mark with null.
397
+ *
398
+ * @param value - The comment's file and id.
399
+ */
400
+ set(value: {
401
+ /** The comment's file. */
402
+ readonly file: string;
403
+ /** The comment's id. */
404
+ readonly id: string;
405
+ } | null): void;
406
+ };
407
+ }
408
+ /** A workspace file attached to the composer, with an optional line selection and comment. */
409
+ export interface ComposerFile {
410
+ /** The part kind. */
411
+ type: "file";
412
+ /** The workspace path. */
413
+ path: string;
414
+ /** The selected text, when only part of the file is attached. */
415
+ selection?: {
416
+ /** First selected line. */
417
+ startLine: number;
418
+ /** Last selected line. */
419
+ endLine: number;
420
+ /** First selected character on `startLine`. */
421
+ startChar: number;
422
+ /** Character after the selection on `endLine`. */
423
+ endChar: number;
424
+ };
425
+ /** Text the chip previews. */
426
+ preview?: string;
427
+ /** The user's comment on the attachment. */
428
+ comment?: string;
429
+ /** The id that `Composer.update` and `detach` take. */
430
+ commentID?: string;
431
+ /**
432
+ * The view the comment was made in.
433
+ * - `review`: the review panel.
434
+ * - `file`: a file tab.
435
+ */
436
+ commentOrigin?: "review" | "file";
437
+ }
438
+ /**
439
+ * A comment on something other than workspace lines, such as an element picked in a page. The model reads
440
+ * "The user made the following comment regarding <subject>: <comment>".
441
+ */
442
+ export interface ComposerNote {
443
+ /** The part kind. */
444
+ type: "note";
445
+ /** The plugin that attached it. Opening the chip routes `Links.open({ href, origin })` to its LinkHandler. */
446
+ origin: string;
447
+ /** The id that `Composer.update` and `detach` take. */
448
+ commentID: string;
449
+ /** Chip text naming the subject, e.g. `button#save`. */
450
+ label: string;
451
+ /** Chip icon. */
452
+ icon: IconName;
453
+ /** What the comment is about, for the model. Quote untrusted text such as page content. */
454
+ subject: string;
455
+ /** The user's comment. */
456
+ comment: string;
457
+ /** The link opening the chip routes, with `origin`. */
458
+ href?: string;
459
+ /**
460
+ * Replaces `subject` and `href` while the note stays in this app process, for references only this process
461
+ * can resolve (e.g. a page element ref). A stored draft and a sent message restored by revert or fork drop it.
462
+ */
463
+ live?: {
464
+ /** The subject while the note stays in this process. */
465
+ readonly subject: string;
466
+ /** The link while the note stays in this process. */
467
+ readonly href?: string;
468
+ };
469
+ }
470
+ /**
471
+ * Text the user quoted from something the plugin shows, such as terminal output, with an optional comment. It
472
+ * renders like a quote from the session timeline, under the source's icon and label. The model reads "The user quoted
473
+ * the following from <subject>:" and the text, each line prefixed with `> `, then the comment when there is one.
474
+ */
475
+ export interface ComposerQuote {
476
+ /** The part kind. */
477
+ type: "quote";
478
+ /** The id that `Composer.update`, `detach` and `focus` take. */
479
+ commentID: string;
480
+ /** The quoted text, as plain text. */
481
+ text: string;
482
+ /** The user's comment on the quote. Omit it to let the user add one from the chip. */
483
+ comment?: string;
484
+ /** Where the text came from. It stays with the draft and the sent message. */
485
+ source: {
486
+ /** Chip text while the quote has no comment, e.g. `Terminal`. */
487
+ readonly label: string;
488
+ /** Chip icon. */
489
+ readonly icon: IconName;
490
+ /** Where the text came from, for the model, e.g. `the terminal`. Not localized. */
491
+ readonly subject: string;
492
+ };
493
+ }
494
+ /** The session screen's composer: the parts attached to the routed session's next prompt. */
495
+ export interface Composer {
496
+ /**
497
+ * Attaches a file, a note or a quote to the next prompt. Focus stays where it is; call `focus` to move it.
498
+ *
499
+ * @param part - The part to attach.
500
+ */
501
+ attach(part: ComposerFile | ComposerNote | ComposerQuote): void;
502
+ /**
503
+ * Whether the composer takes quotes now. False in a subagent's session, which has no composer, and while the
504
+ * composer runs shell commands. Reactive.
505
+ *
506
+ * @example
507
+ * if (screen.composer.quotable()) screen.composer.attach(quote)
508
+ */
509
+ quotable(): boolean;
510
+ /**
511
+ * Moves focus to the prompt, at its cursor. With the `commentID` of an attached quote, opens that quote's comment
512
+ * editor instead. While the composer is not shown, such as on a narrow screen showing a panel, the prompt keeps
513
+ * its focus and the comment editor opens once the composer shows.
514
+ *
515
+ * @param commentID - The attached quote whose comment editor to open. Omit it to focus the prompt.
516
+ */
517
+ focus(commentID?: string): void;
518
+ /**
519
+ * Changes an attached part. Files, notes and quotes alike; a note or a quote takes only `comment`.
520
+ *
521
+ * @param id - The part's `commentID`.
522
+ * @param patch - The fields to change.
523
+ */
524
+ update(id: string, patch: {
525
+ /** The new comment. */
526
+ readonly comment?: string;
527
+ /** The new preview, for a file. */
528
+ readonly preview?: string;
529
+ }): void;
530
+ /**
531
+ * Removes an attached part.
532
+ *
533
+ * @param id - The part's `commentID`.
534
+ */
535
+ detach(id: string): void;
536
+ }
537
+ /** Work the session moved to the background. */
538
+ export interface BackgroundTask {
539
+ /** The task's id. */
540
+ id: string;
541
+ /**
542
+ * What runs.
543
+ * - `shell`: a shell command.
544
+ * - `subagent`: a subagent.
545
+ */
546
+ type: "shell" | "subagent";
547
+ /** The task's display label. */
548
+ label: string;
549
+ /** The subagent's name, for `subagent` tasks. */
550
+ agent?: string;
551
+ }
552
+ /**
553
+ * A routed session on the session screen: its identity and data, and nothing that acts on whichever session is
554
+ * routed. Slot inputs and panel renders receive it, and `Sessions.current` returns it. One frozen object per routed
555
+ * session and directory: a new one each time a session is routed, each time the routed session moves to another
556
+ * directory, and once its shell tab is known. `key`, `id`, `tab`, `server`, `directory` and `visit` never change on
557
+ * one object, and the other fields read this session's own data, never the route's. A render receives each new
558
+ * object through its reactive input instead of remounting, so read `input.session` or `props.session` where you use
559
+ * it rather than copying it. Key per-session state by `key`, which a move keeps. The workspace files, comments and
560
+ * composer follow the route instead, so they belong to the screen: see `Screen`.
561
+ */
562
+ export interface MountedSession extends SessionRef {
563
+ /** This routing visit: a new object each time the session is routed, e.g. after Home and back; a move keeps it. */
564
+ readonly visit: object;
565
+ /**
566
+ * This session's project. `sandboxes` includes worktrees found on disk; `name` and `icon` carry the user's local
567
+ * overrides. Reactive.
568
+ */
569
+ readonly project: Project | undefined;
570
+ /**
571
+ * The sidebar project whose worktree or a sandbox is this session's directory, with the user's local name and
572
+ * icon. Undefined when no listed project is opened there, e.g. for a session in a project subfolder. Reactive.
573
+ */
574
+ readonly listedProject: {
575
+ /** The project's root directory. */
576
+ readonly worktree: string;
577
+ /** The user's local name for the project. */
578
+ readonly name?: string;
579
+ /** The project's icon. */
580
+ readonly icon?: Project["icon"];
581
+ } | undefined;
582
+ /** The session's workspace directory. When the session moves, the next object carries the new one. */
583
+ readonly directory: string;
584
+ /** The session runs in the project root rather than a worktree. Reactive. */
585
+ readonly local: boolean;
586
+ /** Shell commands and subagents the session moved to the background; empty once another session is routed. */
587
+ readonly background: readonly BackgroundTask[];
588
+ }
589
+ /**
590
+ * The session screen: the app's view that shows the routed session, and stays the same object while it routes A, then
591
+ * B, then A again. It follows the route on purpose: its files, comments and composer are the screen's workspace models,
592
+ * and every action through them targets the session routed at that moment. Read it where you act, or pass it to the
593
+ * views that render inside it; a `MountedSession` you keep never acts on another session.
594
+ */
595
+ export interface SessionScreen {
596
+ /** The routed workspace's files. */
597
+ readonly file: Files;
598
+ /** The line comments of the routed session's next prompt. */
599
+ readonly comment: Comments;
600
+ /** The routed session's composer. */
601
+ readonly composer: Composer;
602
+ }
603
+ /** The session screen, while it routes the mounted session. */
604
+ export interface Screen {
605
+ /**
606
+ * The mounted session screen: the same object for as long as it stays mounted, whichever session it routes. Defined
607
+ * exactly when `Sessions.current()` is, after the screen's first render; undefined on Home, on a draft,
608
+ * while the route has left the mounted screen, and before the app interface mounts. Panel callbacks and session
609
+ * slots receive a non-null screen directly. Reactive.
610
+ */
611
+ current(): SessionScreen | undefined;
612
+ }
613
+ /** The sessions of open shell tabs. */
614
+ export interface Sessions {
615
+ /** Sessions owned by open shell tabs. Empty until the app interface mounts. Reactive. */
616
+ list(): readonly SessionRef[];
617
+ /**
618
+ * The routed, mounted session: a new object each time a session is routed. Undefined on Home, on a draft, and
619
+ * before the app interface mounts and during the screen's first render. Defined exactly when `Screen.current()`
620
+ * is, after that first render. Panel and session-slot inputs are available during render directly.
621
+ * Reactive.
622
+ */
623
+ current(): MountedSession | undefined;
624
+ }
625
+ /**
626
+ * Where a panel key stands in a session.
627
+ * - `closed`: not in the strip.
628
+ * - `open`: in the strip, not the tab its pane shows.
629
+ * - `active`: the tab its pane shows, with the pane hidden (the side region closed, or the bottom pane hidden).
630
+ * - `visible`: the tab its pane shows, on screen.
631
+ */
632
+ export type PanelState = "closed" | "open" | "active" | "visible";
633
+ /** How `Layout.open` places a tab. */
634
+ export interface OpenOptions {
635
+ /**
636
+ * How the tab lands in the strip. Defaults to `open`.
637
+ * - `open`: select it, reusing the preview slot.
638
+ * - `preview`: select it as the new preview tab.
639
+ * - `append`: add it at the end without selecting it, changing neither the region nor the preview tab.
640
+ * - `select`: add it at the end and select it, keeping the preview tab. Like `background`, it keeps the
641
+ * narrow-screen view, and opens the side region.
642
+ */
643
+ readonly tab?: "open" | "preview" | "append" | "select";
644
+ /**
645
+ * On narrow screens, keep the current view, and open the side region so the tab shows when the window
646
+ * is wide. Pass it when the user stays where they are (a palette pick, a composer chip) or the agent opened the tab.
647
+ * Defaults to false.
648
+ */
649
+ readonly background?: boolean;
650
+ }
651
+ /**
652
+ * The session layout: side panel tabs, scroll offsets, and the settings and project dialogs. Panel keys are
653
+ * `${plugin}:${tab id}`. Nothing throws before the app interface mounts: `ready()` is false, reads return what an
654
+ * empty layout holds (each says its default), and writes (`open`, `close`, `toggle`, `hide`, `side.toggle`, `scroll.set`,
655
+ * `settings`, `project`) wait and apply in call order once it mounts.
656
+ */
657
+ export interface Layout {
658
+ /** Viewport under 768px. Reactive. */
659
+ narrow(): boolean;
660
+ /** Stored layout (tabs, scroll) has loaded; false before the app interface mounts. Reactive. */
661
+ ready(): boolean;
662
+ /**
663
+ * Opens a panel tab. Works for sessions that are not mounted. On narrow screens, an `open` or `preview` selects the
664
+ * panel's mobile view; opening a tab its panel does not list, or a `transient` tab, stores nothing. A transient tab
665
+ * is never selected on narrow screens, but a stored one stays the preview slot. Writes (`open`, `close`, `toggle`, `scroll.set`) made while `session.location` is
666
+ * unknown wait until it is known, and apply in order.
667
+ *
668
+ * @param key - `${plugin}:${tab id}`.
669
+ * @param session - The session whose strip changes.
670
+ * @param options - How the tab lands; see `OpenOptions`.
671
+ */
672
+ open(key: string, session: SessionRef, options?: OpenOptions): void;
673
+ /**
674
+ * Removes a tab from the strip and calls its panel's `close`.
675
+ *
676
+ * @param key - `${plugin}:${tab id}`.
677
+ * @param session - The session whose strip changes.
678
+ */
679
+ close(key: string, session: SessionRef): void;
680
+ /**
681
+ * Closes a visible tab, else opens it. Closing the last panel the side region was opened for also closes the region.
682
+ *
683
+ * @param key - `${plugin}:${tab id}`.
684
+ * @param session - The session whose strip changes.
685
+ */
686
+ toggle(key: string, session: SessionRef): void;
687
+ /**
688
+ * Hides the pane that shows a visible tab without closing the tab: the side region for a tab in the side panes, the
689
+ * bottom pane for a tab the user moved there. Does nothing unless `state` is "visible". Opening the tab again shows
690
+ * its pane.
691
+ *
692
+ * @param key - `${plugin}:${tab id}`.
693
+ * @param session - The session whose pane hides.
694
+ */
695
+ hide(key: string, session: SessionRef): void;
696
+ /**
697
+ * Where a key stands. "closed" while the session's location is unknown and before the app interface mounts.
698
+ * Reactive.
699
+ *
700
+ * @param key - `${plugin}:${tab id}`.
701
+ * @param session - Any session.
702
+ */
703
+ state(key: string, session: SessionRef): PanelState;
704
+ /**
705
+ * This plugin's tab ids stored in the session's side strip, mounted or not. Empty while the session's location
706
+ * is unknown, as `state` is then "closed", and before the app interface mounts. Reactive.
707
+ *
708
+ * @param session - Any session.
709
+ */
710
+ stored(session: SessionRef): readonly string[];
711
+ /** The side region. */
712
+ readonly side: {
713
+ /**
714
+ * The side region is open; false before the app interface mounts. Reactive.
715
+ *
716
+ * @param session - Any session.
717
+ */
718
+ opened(session: SessionRef): boolean;
719
+ /**
720
+ * Opens or closes the side region.
721
+ *
722
+ * @param session - Any session.
723
+ */
724
+ toggle(session: SessionRef): void;
725
+ /**
726
+ * The + menu's items: every plugin's `session.panel` `MenuItem`, in `order`. Use it to list them on a page of
727
+ * your own, such as a new tab page. Empty before the app interface mounts. Reactive.
728
+ *
729
+ * @example
730
+ * ```ts
731
+ * const launchers = () => ctx.layout.side.menu().filter((item) => !item.primary && !item.opened)
732
+ * ```
733
+ */
734
+ menu(): readonly SessionPanelMenuItem[];
735
+ };
736
+ /**
737
+ * The inner sidebar preference every side panel shares, which `usePanel().sidebar` also reads inside a panel render.
738
+ * One value for the app, for code outside a render such as a tab's fields. Reactive.
739
+ */
740
+ readonly sidebar: {
741
+ /** The inner sidebar is open; true until a session screen shows the preference. Reactive. */
742
+ opened(): boolean;
743
+ };
744
+ /** Scroll offsets the host stores per session and key. */
745
+ readonly scroll: {
746
+ /**
747
+ * The stored offset; undefined when none is stored, the location is unknown, or the app interface is not mounted.
748
+ *
749
+ * @param session - Any session.
750
+ * @param key - Your own key, e.g. a panel key.
751
+ */
752
+ get(session: SessionRef, key: string): {
753
+ /** Horizontal offset in CSS pixels. */
754
+ readonly x: number;
755
+ /** Vertical offset in CSS pixels. */
756
+ readonly y: number;
757
+ } | undefined;
758
+ /**
759
+ * Stores an offset. Waits while the session's location is unknown.
760
+ *
761
+ * @param session - Any session.
762
+ * @param key - Your own key, e.g. a panel key.
763
+ * @param value - The offset.
764
+ */
765
+ set(session: SessionRef, key: string, value: {
766
+ /** Horizontal offset in CSS pixels. */
767
+ readonly x: number;
768
+ /** Vertical offset in CSS pixels. */
769
+ readonly y: number;
770
+ }): void;
771
+ };
772
+ /**
773
+ * Opens Settings.
774
+ *
775
+ * @param page - A `SettingsPage` id you contributed, or a host page tab; defaults to `general`.
776
+ */
777
+ settings(page?: string): void;
778
+ /**
779
+ * Opens a project on a server: a directory picker titled `title`, then a new draft. Waits until the server is listed.
780
+ *
781
+ * @param server - The server's `ServerRef.id`.
782
+ * @param title - The picker's title.
783
+ */
784
+ project(server: string, title: string): void;
785
+ /**
786
+ * Opens a new draft session in a directory on a server with its prompt filled in, for the user to review and send.
787
+ * The draft opens in its own tab, as a new session from Home does. Does nothing when the app does not list the
788
+ * server.
789
+ *
790
+ * @param input - Where the draft runs and what it asks.
791
+ *
792
+ * @example
793
+ * ```ts
794
+ * ctx.layout.draft({ server: session.server.id, directory, prompt: ctx.t("setup.prompt") })
795
+ * ```
796
+ */
797
+ draft(input: {
798
+ /** The server's `ServerRef.id`. */
799
+ readonly server: string;
800
+ /** The directory the new session runs in. */
801
+ readonly directory: string;
802
+ /** The prompt the draft starts with. */
803
+ readonly prompt: string;
804
+ }): void;
805
+ }
806
+ /**
807
+ * Where `Storage.store` keeps a value.
808
+ * - `"global"`: one value for the app. The default.
809
+ * - `{ server, directory? }`: one value per server, or per workspace directory on it. Opens once the app interface
810
+ * mounts; until then `value` is undefined and `update` waits.
811
+ * - `{ session }`: one value per session. Also waits for the session's location, and opens again in a new directory;
812
+ * a declared `Store.session` does the same for every session.
813
+ */
814
+ export type StorageScope = "global" | {
815
+ /** The server's `ServerRef.id`. */
816
+ readonly server: string;
817
+ /** A workspace directory on that server; omit it for one value per server. */
818
+ readonly directory?: string;
819
+ } | {
820
+ /** The session. */
821
+ readonly session: SessionRef;
822
+ };
823
+ /** What `Storage.store` opens. */
824
+ export interface StoreOptions<S extends Schema.ConstraintCodec<object, unknown>> {
825
+ /** Decodes the stored JSON, as `StoreDeclaration.schema` does. */
826
+ readonly schema: S;
827
+ /** The value before anything is stored, and after `remove`. */
828
+ readonly initial: S["Type"];
829
+ /** Where the value lives. Defaults to `"global"`. */
830
+ readonly scope?: StorageScope;
831
+ /**
832
+ * Imports an older key of the same storage once (the raw stored key, e.g. `"plugin.acme.recent"`), or the first of
833
+ * several that holds a value. See `StoreFrom`.
834
+ */
835
+ readonly from?: StoreFrom | readonly StoreFrom[];
836
+ }
837
+ /**
838
+ * Window storage, in the plugin's namespace (`plugin.<id>.<key>`). Synced across windows. On desktop it loads
839
+ * over IPC, so a value is undefined until it loads; on the web it is synchronous.
840
+ */
841
+ export interface Storage {
842
+ /**
843
+ * Opens a durable, schema-decoded store. For keys only known at runtime, such as one per server and directory;
844
+ * declare `stores` in the definition for keys known up front. Derive nothing from it, such as a request, before
845
+ * `value` is defined.
846
+ *
847
+ * @param key - The store's key in your namespace.
848
+ * @param options - Its schema, initial value, scope and older homes.
849
+ */
850
+ store<S extends Schema.ConstraintCodec<object, unknown>>(key: string, options: StoreOptions<S>): Persisted<S["Type"]>;
851
+ /**
852
+ * Window-local state that survives plugin reloads, but not a window reload. The first open of a key creates it;
853
+ * later opens return the same store and ignore `initial`.
854
+ *
855
+ * @param key - The store's key in your namespace.
856
+ * @param options - The store's options.
857
+ * @returns The store and its setter, which edits a draft.
858
+ */
859
+ memory<T extends object>(key: string, options: {
860
+ /** The value the first open creates. */
861
+ readonly initial: T;
862
+ }): readonly [Store<T>, (mutation: (draft: T) => void) => void];
863
+ /**
864
+ * Deletes the value, so opening the key again reads its `initial`. Pass the store's `scope` and `from`: an older key
865
+ * `from` names is deleted too, so it is never imported again. A server or session store's removal waits, in call
866
+ * order, until the app interface mounts and the session's location is known.
867
+ *
868
+ * @param key - The store's key in your namespace.
869
+ * @param options - The store's scope and older homes.
870
+ */
871
+ remove(key: string, options?: {
872
+ /** The store's scope. Defaults to `"global"`. */
873
+ readonly scope?: StorageScope;
874
+ /** The store's `from`. */
875
+ readonly from?: StoreFrom | readonly StoreFrom[];
876
+ }): void;
877
+ }
878
+ /** System services that work on every platform. */
879
+ export interface System {
880
+ /**
881
+ * Copies text to the clipboard.
882
+ *
883
+ * @param text - The text to copy.
884
+ */
885
+ copy(text: string): Promise<void>;
886
+ /**
887
+ * Saves a file: a save dialog on desktop, a download on the web.
888
+ *
889
+ * @param file - The suggested name and the content.
890
+ * @returns False when the user cancelled the desktop dialog; always true on the web.
891
+ */
892
+ save(file: {
893
+ /** The suggested file name. */
894
+ readonly name: string;
895
+ /** The file's content. */
896
+ readonly content: string;
897
+ }): Promise<boolean>;
898
+ /**
899
+ * Opens a URL in the system browser; desktop opens file:// URLs with the default app. For links inside the app,
900
+ * use `Links.open`.
901
+ *
902
+ * @param url - The URL to open.
903
+ */
904
+ openExternal(url: string): void;
905
+ }
906
+ /** Desktop-only abilities; `ctx.desktop` is undefined on the web. */
907
+ export interface Desktop {
908
+ /** The operating system. */
909
+ readonly os: OS;
910
+ /** The window's zoom factor; 1 is 100%. */
911
+ zoom(): number;
912
+ /**
913
+ * Opens a path with an app, or with the default app.
914
+ *
915
+ * @param path - An absolute path.
916
+ * @param app - The app's name or path; omit it for the default app.
917
+ */
918
+ launch(path: string, app?: string): Promise<void>;
919
+ /**
920
+ * Shows a path in the system file manager.
921
+ *
922
+ * @param path - An absolute path.
923
+ * @returns False when it could not.
924
+ */
925
+ reveal(path: string): Promise<boolean>;
926
+ /**
927
+ * Whether an app is installed.
928
+ *
929
+ * @param app - The app's name.
930
+ */
931
+ installed(app: string): Promise<boolean>;
932
+ }
933
+ /** The interface language and its writing direction. */
934
+ export interface Locale {
935
+ /** BCP 47 locale of the interface language, for Intl formatting. Reactive. */
936
+ locale(): string;
937
+ /**
938
+ * The writing direction. Reactive.
939
+ * - `ltr`: left to right.
940
+ * - `rtl`: right to left.
941
+ */
942
+ direction(): "ltr" | "rtl";
943
+ }
944
+ /** The user's appearance settings. */
945
+ export interface Appearance {
946
+ /**
947
+ * The CSS font family the user chose; the default mono font before the app interface mounts. Reactive.
948
+ *
949
+ * @param kind - `mono`, the terminal font.
950
+ */
951
+ font(kind: "mono"): string;
952
+ }
953
+ /** The app's route. */
954
+ export interface Router {
955
+ /** A route transition is in progress. Reactive. */
956
+ routing(): boolean;
957
+ /** The current route path with its query string; "" before the app interface mounts. Reactive. */
958
+ path(): string;
959
+ }
960
+ /** The effective keybinds of published commands. */
961
+ export interface Keybinds {
962
+ /**
963
+ * Display parts of a published command's effective keybind, e.g. ["Ctrl", "K"]. Empty when unbound. Reactive.
964
+ *
965
+ * @param command - A published command id, `${plugin}.${id}`.
966
+ */
967
+ keybind(command: string): readonly string[];
968
+ /**
969
+ * Display parts of a chord the app does not own, e.g. "mod+shift+c" that a page handles itself.
970
+ *
971
+ * @param bind - A chord in keybind syntax.
972
+ */
973
+ keys(bind: string): readonly string[];
974
+ /**
975
+ * The event matches a published command's effective keybind.
976
+ *
977
+ * @param command - A published command id.
978
+ * @param event - The keyboard event.
979
+ */
980
+ matches(command: string, event: KeyboardEvent): boolean;
981
+ }
982
+ /** The servers the app lists. */
983
+ export interface Servers {
984
+ /** Ids of the servers the app lists (`ServerRef.id`). Reactive. */
985
+ list(): readonly string[];
986
+ /**
987
+ * A listed server's ref, already authenticated for this window: the desktop's own server included, whose credentials
988
+ * stay in the main process. The same ref for the same id; read its `client` each time you call it. Reactive.
989
+ *
990
+ * @param id - The server's id, as `list()` returns it.
991
+ * @returns Undefined while the app does not list the server, and before the app interface mounts.
992
+ *
993
+ * @example
994
+ * ```ts
995
+ * const builtin = () => ctx.servers.list().map((id) => ctx.servers.get(id)).find((server) => server?.builtin)
996
+ * const info = () => builtin()?.client.server.info()
997
+ * ```
998
+ */
999
+ get(id: string): ServerRef | undefined;
1000
+ }
1001
+ /** Workspace lifecycle events. */
1002
+ export interface Workspaces {
1003
+ /**
1004
+ * Listens to an event. The listener is removed with the current owner, else with the plugin.
1005
+ *
1006
+ * @param event - `remove`: the user removed a workspace directory from a server.
1007
+ * @param handler - Receives the server's id and the directory.
1008
+ * @returns Removes the listener.
1009
+ */
1010
+ on(event: "remove", handler: (value: {
1011
+ /** The server's `ServerRef.id`. */
1012
+ readonly server: string;
1013
+ /** The removed directory. */
1014
+ readonly directory: string;
1015
+ }) => void): Cleanup;
1016
+ }
1017
+ /** Routes local links to the plugins that handle them. */
1018
+ export interface Links {
1019
+ /**
1020
+ * Routes a local link to the LinkHandler with the highest priority that matches it.
1021
+ *
1022
+ * @param link - The link to open.
1023
+ * @returns False when no handler matches.
1024
+ */
1025
+ open(link: Link): boolean;
1026
+ /**
1027
+ * Whether a link's target exists, so text that names it can be styled as a link. Asks the LinkHandler `open` would
1028
+ * use. Untracked: calling it inside an effect does not subscribe that effect.
1029
+ *
1030
+ * @param link - The candidate link.
1031
+ * @returns False when no handler matches, the handler has no `exists`, or the target does not exist.
1032
+ */
1033
+ exists(link: Link): boolean | Promise<boolean>;
1034
+ }
1035
+ /** One dialog `Dialogs.open` opened. */
1036
+ export interface DialogHandle {
1037
+ /**
1038
+ * Closes this dialog, wherever it is in the stack; another dialog stays open. A dialog that still waits for the app
1039
+ * interface never shows. Does nothing once the dialog closed, including when it never opened because its plugin
1040
+ * went away first.
1041
+ */
1042
+ close(): void;
1043
+ }
1044
+ /**
1045
+ * Dialogs. The render runs with this plugin's context. A dialog closes when the owner that opened it ends (the
1046
+ * component or `createKeyed` run), else when the plugin goes away.
1047
+ */
1048
+ export interface Dialogs {
1049
+ /**
1050
+ * Opens a dialog above the open ones. Opening is deferred to a transition, so a dialog opened while its owner ends
1051
+ * never shows. Before the app interface mounts, as during setup, the dialog waits and shows after the interface's
1052
+ * first render, behind the writes made before it: never behind the startup screen, and never before the restored
1053
+ * route takes focus. A render that throws closes the dialog and records the error.
1054
+ *
1055
+ * @param render - Renders the dialog's content; receives the dialog's handle, so the content can close itself.
1056
+ * @param options - How the dialog opens.
1057
+ * @returns The dialog's handle.
1058
+ *
1059
+ * @example
1060
+ * ```ts
1061
+ * const dialog = ctx.dialogs.open((dialog) => <Confirm onDone={dialog.close} />)
1062
+ * ```
1063
+ */
1064
+ open(render: (dialog: DialogHandle) => JSX.Element, options?: {
1065
+ /** Closes every open dialog first, the host's and other plugins' too. Defaults to false. */
1066
+ readonly replace?: boolean;
1067
+ }): DialogHandle;
1068
+ /** Some dialog is open. Reactive. */
1069
+ active(): boolean;
1070
+ }
1071
+ /** Props of `Embeds.View`. */
1072
+ export interface EmbedProps {
1073
+ /** An embed the plugin's main entry created with `Embeds.create`. Undefined renders the box alone. */
1074
+ readonly id: string | undefined;
1075
+ /** The embed should be on screen. The host also hides it while the window is hidden or a dialog is open. */
1076
+ readonly visible: boolean;
1077
+ /** Paints a still of the embed in place of the live view, so DOM content can float above it. */
1078
+ readonly frozen?: boolean;
1079
+ /**
1080
+ * What the embed shows, such as its URL. While a panel moves, the host paints a still of the embed in its place; a
1081
+ * still taken while this had another value is dropped rather than shown.
1082
+ */
1083
+ readonly page?: string;
1084
+ /** Radius of the bottom corners in CSS pixels. */
1085
+ readonly radius?: number;
1086
+ /** CSS color the rounded corners show; defaults to the app backdrop behind the panel. */
1087
+ readonly background?: string;
1088
+ /** Classes of the box. */
1089
+ readonly class?: string;
1090
+ /** Rendered inside the box, under the embed. */
1091
+ readonly children?: JSX.Element;
1092
+ }
1093
+ /** Web pages (Electron WebContentsViews) the plugin's main entry placed in the window layout. */
1094
+ export interface Embeds {
1095
+ /**
1096
+ * The box a main-process embed fills. The host measures it (webview zoom included), pushes
1097
+ * coalesced layouts, masks the rounded corners, hides the embed while it is invisible or unmounted,
1098
+ * and paints a still of it while floating content covers it. Children render inside the box.
1099
+ *
1100
+ * @param props - The embed and how to show it.
1101
+ */
1102
+ View(props: EmbedProps): JSX.Element;
1103
+ /**
1104
+ * A JPEG still of a shown embed; undefined while it is hidden, and always on the web.
1105
+ *
1106
+ * @param id - The embed's id.
1107
+ */
1108
+ capture(id: string): Promise<Uint8Array | undefined>;
1109
+ }