@opencode/plugin 0.0.0-dev-55 → 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.
- package/dist/gui/browser.d.ts +36 -0
- package/dist/gui/browser.js +3 -0
- package/dist/gui/context.d.ts +223 -0
- package/dist/gui/context.js +0 -0
- package/dist/gui/core.d.ts +560 -0
- package/dist/gui/core.js +86 -0
- package/dist/gui/declarations.d.ts +24 -0
- package/dist/gui/declarations.js +0 -0
- package/dist/gui/file.d.ts +122 -0
- package/dist/gui/file.js +7 -0
- package/dist/gui/host-apis.d.ts +1109 -0
- package/dist/gui/host-apis.js +0 -0
- package/dist/gui/icon-name.d.ts +2 -0
- package/dist/gui/icon-name.js +1 -0
- package/dist/gui/index.d.ts +7 -0
- package/dist/gui/index.js +6 -0
- package/dist/gui/internal.d.ts +44 -0
- package/dist/gui/internal.js +33 -0
- package/dist/gui/main.d.ts +279 -0
- package/dist/gui/main.js +20 -0
- package/dist/gui/modules.d.ts +15 -0
- package/dist/gui/modules.js +30 -0
- package/dist/gui/plugin.d.ts +86 -0
- package/dist/gui/plugin.js +9 -0
- package/dist/gui/reactive.d.ts +93 -0
- package/dist/gui/reactive.js +130 -0
- package/dist/gui/registries.d.ts +770 -0
- package/dist/gui/registries.js +110 -0
- package/dist/gui/review.d.ts +73 -0
- package/dist/gui/review.js +3 -0
- package/dist/gui/scope.d.ts +64 -0
- package/dist/gui/scope.js +85 -0
- package/dist/gui/solid.d.ts +99 -0
- package/dist/gui/solid.js +74 -0
- package/dist/gui/vite.d.ts +24 -0
- package/dist/gui/vite.js +49 -0
- package/dist/host.d.ts +12 -1
- package/dist/host.js +34 -2
- package/dist/runtime-modules.js +3 -1
- package/package.json +54 -10
|
@@ -0,0 +1,560 @@
|
|
|
1
|
+
import type { OpenCodeClient } from "@opencode/client/promise";
|
|
2
|
+
import type { Schema } from "effect";
|
|
3
|
+
/**
|
|
4
|
+
* Undoes a registration, or tears something down. Every `add` and `on` returns one, and so does a window's
|
|
5
|
+
* `provide`; `onCleanup` and a setup's return value take one.
|
|
6
|
+
* Calling it early withdraws at once; a second call does nothing. When the host runs it, a throw or a rejection is
|
|
7
|
+
* logged and the other cleanups still run; main's `Scope` waits for a returned promise until its deadline.
|
|
8
|
+
*/
|
|
9
|
+
export type Cleanup = () => void | Promise<void>;
|
|
10
|
+
/**
|
|
11
|
+
* An operating system, as `Plugin.Declarations.os` and `Desktop.os` name it.
|
|
12
|
+
* - `macos`: macOS.
|
|
13
|
+
* - `windows`: Windows.
|
|
14
|
+
* - `linux`: Linux and every other desktop platform.
|
|
15
|
+
*/
|
|
16
|
+
export type OS = "macos" | "windows" | "linux";
|
|
17
|
+
/** Values a message interpolates: `{{name}}` in a template reads `params.name`. */
|
|
18
|
+
export type Params = Record<string, string | number | boolean>;
|
|
19
|
+
/** One locale's copy: message key to template. Plural keys end in a CLDR category, e.g. `files.one`, `files.other`. */
|
|
20
|
+
export type Messages = Readonly<Record<string, string>>;
|
|
21
|
+
/**
|
|
22
|
+
* A plugin's copy by locale, every locale inline. English fills every key a locale lacks.
|
|
23
|
+
*
|
|
24
|
+
* @example
|
|
25
|
+
* ```ts
|
|
26
|
+
* i18n: { en: { title: "Acme" }, de: { title: "Acme" } }
|
|
27
|
+
* ```
|
|
28
|
+
*/
|
|
29
|
+
export type Catalog = {
|
|
30
|
+
/** English, the source copy and the fallback for every key. */
|
|
31
|
+
readonly en: Messages;
|
|
32
|
+
} & {
|
|
33
|
+
readonly [locale: string]: Messages;
|
|
34
|
+
};
|
|
35
|
+
/** A JSON value, as plugin options in `opencode.json` hold. */
|
|
36
|
+
export type Json = string | number | boolean | null | readonly Json[] | {
|
|
37
|
+
readonly [key: string]: Json;
|
|
38
|
+
};
|
|
39
|
+
/** A plugin's options from its `opencode.json` entry, as server and TUI plugins receive them. */
|
|
40
|
+
export type PluginOptions = {
|
|
41
|
+
readonly [key: string]: Json;
|
|
42
|
+
};
|
|
43
|
+
/** The running app. One shape in the window and in main, with the fields server and TUI plugins get in `ctx.app`. */
|
|
44
|
+
export interface App {
|
|
45
|
+
/** The app's name, `opencode`, as in a server plugin's `ctx.app.name`. */
|
|
46
|
+
readonly name: string;
|
|
47
|
+
/**
|
|
48
|
+
* The app version, e.g. `2.0.20`. Web and desktop windows always know it; it is `""` only in a window whose platform
|
|
49
|
+
* reports none, such as a test or Storybook fixture, as no build-time version constant exists in every build.
|
|
50
|
+
*/
|
|
51
|
+
readonly version: string;
|
|
52
|
+
/**
|
|
53
|
+
* The release channel.
|
|
54
|
+
* - `local`: a build from source, with no channel set.
|
|
55
|
+
* - `dev`: the development channel.
|
|
56
|
+
* - `beta`: the beta channel.
|
|
57
|
+
* - `prod`: the stable release.
|
|
58
|
+
*/
|
|
59
|
+
readonly channel: "local" | "dev" | "beta" | "prod";
|
|
60
|
+
/**
|
|
61
|
+
* Where the code runs. Main is always `desktop`.
|
|
62
|
+
* - `web`: a browser tab.
|
|
63
|
+
* - `desktop`: the Electron app.
|
|
64
|
+
*/
|
|
65
|
+
readonly platform: "web" | "desktop";
|
|
66
|
+
/** A packaged desktop app, not a development run. Always false on the web. */
|
|
67
|
+
readonly packaged: boolean;
|
|
68
|
+
}
|
|
69
|
+
declare const brand: unique symbol;
|
|
70
|
+
/**
|
|
71
|
+
* A token kind: a typed list that accepts contributions. The plugin or host that owns the registry decides how to
|
|
72
|
+
* use its items; others `ctx.add` to it. Define one with `Registry.define`.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```ts
|
|
76
|
+
* export const Badge = Registry.define<{ readonly label: string }>("details.badge")
|
|
77
|
+
* ctx.add(Badge, { label: "New" })
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
80
|
+
export interface Registry<T> {
|
|
81
|
+
/** The token kind. */
|
|
82
|
+
readonly kind: "registry";
|
|
83
|
+
/** The registry's id; contributions are grouped by it. */
|
|
84
|
+
readonly id: string;
|
|
85
|
+
/** Carries the item type `T` at compile time only; never set. */
|
|
86
|
+
readonly [brand]?: T;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* A token kind: an in-process contract one plugin provides from its window entry and others read with `ctx.use`.
|
|
90
|
+
* Any interface, no schema; it never crosses IPC. Define one with `Contract.define` in the provider's `contract.ts`.
|
|
91
|
+
*
|
|
92
|
+
* @example
|
|
93
|
+
* ```ts
|
|
94
|
+
* export const FileTree = Contract.define<FileTree, "file.tree">("file.tree")
|
|
95
|
+
* ctx.provide(FileTree, { open: (path) => reveal(path) })
|
|
96
|
+
* ```
|
|
97
|
+
*/
|
|
98
|
+
export interface Contract<T, Id extends string = string> {
|
|
99
|
+
/** The token kind. */
|
|
100
|
+
readonly kind: "contract";
|
|
101
|
+
/** The contract's id: `<plugin id>` or `<plugin id>.<name>`. */
|
|
102
|
+
readonly id: Id;
|
|
103
|
+
/** Carries the contract type `T` at compile time only; never set. */
|
|
104
|
+
readonly [brand]?: T;
|
|
105
|
+
}
|
|
106
|
+
type Codec = Schema.ConstraintCodec<unknown, unknown>;
|
|
107
|
+
/** One method of an `IpcSpec`. Values cross the bridge encoded by these schemas. */
|
|
108
|
+
export interface IpcMethod {
|
|
109
|
+
/** The argument's schema. Omit it for a method that takes none. */
|
|
110
|
+
readonly input?: Codec;
|
|
111
|
+
/** The result's schema. Omit it for a method that returns nothing. */
|
|
112
|
+
readonly output?: Codec;
|
|
113
|
+
}
|
|
114
|
+
/** The schemas of an Ipc: its state, methods and events. Pass it to `Ipc.define`. */
|
|
115
|
+
export interface IpcSpec {
|
|
116
|
+
/**
|
|
117
|
+
* The Ipc's id: the providing plugin's id, or `<plugin id>.<name>`. Once main has listed that plugin, it starts it
|
|
118
|
+
* on demand when a window subscribes, before the other main plugins start.
|
|
119
|
+
*/
|
|
120
|
+
readonly id: string;
|
|
121
|
+
/** Schema of the state main keeps per window (`IpcImpl.state`) and pushes with `changed`. Omit it for none. */
|
|
122
|
+
readonly state?: Codec;
|
|
123
|
+
/** The methods a window calls, by name. */
|
|
124
|
+
readonly methods: Readonly<Record<string, IpcMethod>>;
|
|
125
|
+
/** Schemas of the events main emits, by name. Omit it for none. */
|
|
126
|
+
readonly events?: Readonly<Record<string, Codec>>;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* A token kind: a contract the main entry provides and window entries use over the IPC bridge, typed by its schemas.
|
|
130
|
+
* Define one with `Ipc.define` in `contract.ts`; provide it from main with `ctx.provide`, and call it from the plugin's
|
|
131
|
+
* windows with `ctx.main`. On the web, where no main process runs, it is inactive and every call rejects.
|
|
132
|
+
*
|
|
133
|
+
* @example
|
|
134
|
+
* ```ts
|
|
135
|
+
* export const Pairing = Ipc.define({
|
|
136
|
+
* id: "pairing",
|
|
137
|
+
* methods: { screenActive: { output: Schema.Boolean }, setScreenActive: { input: Schema.Boolean } },
|
|
138
|
+
* })
|
|
139
|
+
* ```
|
|
140
|
+
*/
|
|
141
|
+
export interface Ipc<S extends IpcSpec = IpcSpec> {
|
|
142
|
+
/** The token kind. */
|
|
143
|
+
readonly kind: "ipc";
|
|
144
|
+
/** The Ipc's id, `spec.id`. */
|
|
145
|
+
readonly id: string;
|
|
146
|
+
/** The schemas the bridge encodes and decodes with. */
|
|
147
|
+
readonly spec: S;
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* Something a plugin provides under its id and other code reads with `ctx.use`.
|
|
151
|
+
* - `Contract`: in-process, from a window entry.
|
|
152
|
+
* - `Ipc`: from a main entry, over the bridge.
|
|
153
|
+
*/
|
|
154
|
+
export type Token = Contract<unknown> | Ipc;
|
|
155
|
+
type TypeOf<C> = C extends Codec ? C["Type"] : void;
|
|
156
|
+
/**
|
|
157
|
+
* How a window calls an Ipc, from `ctx.main` or an active `ctx.use`: one async function per method, plus `state`
|
|
158
|
+
* and `on`. A method encodes its input with the method's schema and decodes the reply; it rejects when encoding fails,
|
|
159
|
+
* when the Ipc is gone, or when main throws.
|
|
160
|
+
*
|
|
161
|
+
* @example
|
|
162
|
+
* ```ts
|
|
163
|
+
* const active = await pairing.screenActive({ signal: ctx.signal })
|
|
164
|
+
* ```
|
|
165
|
+
*/
|
|
166
|
+
export type IpcClient<S extends IpcSpec> = {
|
|
167
|
+
readonly [Name in keyof S["methods"]]: S["methods"][Name] extends {
|
|
168
|
+
readonly input: Codec;
|
|
169
|
+
} ? (
|
|
170
|
+
/** The argument decoded by this method's input schema. */
|
|
171
|
+
input: TypeOf<S["methods"][Name]["input"]>,
|
|
172
|
+
/** Optional per-call cancellation. */
|
|
173
|
+
options?: IpcCallOptions) => Promise<TypeOf<S["methods"][Name]["output"]>> : (
|
|
174
|
+
/** Optional per-call cancellation; no input placeholder is accepted. */
|
|
175
|
+
options?: IpcCallOptions) => Promise<TypeOf<S["methods"][Name]["output"]>>;
|
|
176
|
+
} & {
|
|
177
|
+
/**
|
|
178
|
+
* This window's state, as main's `IpcImpl.state` last pushed it. Undefined until the first snapshot arrives and
|
|
179
|
+
* after the Ipc goes away. An event always wins over an older snapshot. Reactive.
|
|
180
|
+
*/
|
|
181
|
+
state(): TypeOf<S["state"]> | undefined;
|
|
182
|
+
/**
|
|
183
|
+
* Listens to one event. The listener is removed with the current owner (for example a `createKeyed` run), else
|
|
184
|
+
* with the plugin.
|
|
185
|
+
*
|
|
186
|
+
* @param name - The event's name in `spec.events`.
|
|
187
|
+
* @param listener - Receives the decoded event data.
|
|
188
|
+
* @returns Removes the listener.
|
|
189
|
+
*/
|
|
190
|
+
on<Name extends keyof NonNullable<S["events"]> & string>(name: Name, listener: (data: TypeOf<NonNullable<S["events"]>[Name]>) => void): Cleanup;
|
|
191
|
+
};
|
|
192
|
+
/** Options for any Ipc method. A method without an input schema takes these as its only argument. */
|
|
193
|
+
export interface IpcCallOptions {
|
|
194
|
+
/** Aborts the call: main's `Caller.signal` aborts, and the promise rejects. */
|
|
195
|
+
readonly signal?: AbortSignal;
|
|
196
|
+
}
|
|
197
|
+
/** The value a token gives its users: the contract itself, or the client of an Ipc. */
|
|
198
|
+
export type TokenValue<T> = T extends Ipc<infer S> ? IpcClient<S> : T extends Contract<infer V> ? V : never;
|
|
199
|
+
/**
|
|
200
|
+
* A provider as its users see it. The host returns one object per transition, so a reader re-runs only when the
|
|
201
|
+
* provider changes.
|
|
202
|
+
* - `pending`: the provider has not started yet, e.g. while its entry loads or before main is up.
|
|
203
|
+
* - `active`: `value` is the contract or Ipc client. `generation` counts activations: a provider that restarts comes
|
|
204
|
+
* back with a new one.
|
|
205
|
+
* - `inactive`: the provider is gone, and `reason` says why: `disabled` (turned off, absent, or not on this platform,
|
|
206
|
+
* such as every Ipc on the web) or `failed` (its setup threw). A provider that restarts is `pending` until it is
|
|
207
|
+
* back.
|
|
208
|
+
*
|
|
209
|
+
* @example
|
|
210
|
+
* ```ts
|
|
211
|
+
* const live = ctx.use(Changes)()
|
|
212
|
+
* if (live.status === "active") live.value.open(session)
|
|
213
|
+
* ```
|
|
214
|
+
*/
|
|
215
|
+
export type Live<T> = {
|
|
216
|
+
/** The provider has not started yet. */
|
|
217
|
+
readonly status: "pending";
|
|
218
|
+
} | {
|
|
219
|
+
/** The provider is running. */
|
|
220
|
+
readonly status: "active";
|
|
221
|
+
/** The contract, or the Ipc client. */
|
|
222
|
+
readonly value: T;
|
|
223
|
+
/** Counts activations, starting at 1; each restart brings a new one. */
|
|
224
|
+
readonly generation: number;
|
|
225
|
+
} | {
|
|
226
|
+
/** The provider is gone. */
|
|
227
|
+
readonly status: "inactive";
|
|
228
|
+
/**
|
|
229
|
+
* Why the provider is gone.
|
|
230
|
+
* - `disabled`: turned off, not composed, or not on this platform.
|
|
231
|
+
* - `failed`: its setup threw.
|
|
232
|
+
*/
|
|
233
|
+
readonly reason: "disabled" | "failed";
|
|
234
|
+
};
|
|
235
|
+
/** Identifies the window an Ipc call came from. Main uses it to scope state and events. */
|
|
236
|
+
export interface Caller {
|
|
237
|
+
/** The calling window's id (`BrowserWindow.id`); pass it to `changed` or `emit` to reach that window alone. */
|
|
238
|
+
readonly window: number;
|
|
239
|
+
/** Aborts when the window aborts the call or the providing instance goes away. */
|
|
240
|
+
readonly signal: AbortSignal;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* What main passes to `ctx.provide(ipc, impl)`: one function per method, plus `state` when the spec has a state.
|
|
244
|
+
* A method receives the decoded input and the `Caller`; its result is encoded with the method's output schema. A
|
|
245
|
+
* throw rejects the window's call.
|
|
246
|
+
*/
|
|
247
|
+
export type IpcImpl<S extends IpcSpec> = {
|
|
248
|
+
readonly [Name in keyof S["methods"]]: (input: TypeOf<S["methods"][Name]["input"]>, caller: Caller) => TypeOf<S["methods"][Name]["output"]> | Promise<TypeOf<S["methods"][Name]["output"]>>;
|
|
249
|
+
} & (S["state"] extends Codec ? {
|
|
250
|
+
/**
|
|
251
|
+
* The state one window sees. Main reads it when the window subscribes and on every `changed`.
|
|
252
|
+
*
|
|
253
|
+
* @param window - The window's id.
|
|
254
|
+
*/
|
|
255
|
+
state(window: number): TypeOf<S["state"]>;
|
|
256
|
+
} : unknown);
|
|
257
|
+
/**
|
|
258
|
+
* Returned by `ctx.provide(ipc, impl)` in main. Every method does nothing once the provider is withdrawn.
|
|
259
|
+
*
|
|
260
|
+
* @example
|
|
261
|
+
* ```ts
|
|
262
|
+
* const provider = ctx.provide(Downloads, { state: () => downloads.state(), start, cancel })
|
|
263
|
+
* provider.changed()
|
|
264
|
+
* ```
|
|
265
|
+
*/
|
|
266
|
+
export interface IpcProvider<S extends IpcSpec> {
|
|
267
|
+
/**
|
|
268
|
+
* Re-reads `impl.state` and sends it to the windows that subscribed. Call it after every change of the state.
|
|
269
|
+
*
|
|
270
|
+
* @param window - One window's id. Omit it for every window.
|
|
271
|
+
*/
|
|
272
|
+
changed(window?: number): void;
|
|
273
|
+
/**
|
|
274
|
+
* Sends an event, encoded with its schema. An encoding failure is logged, not thrown.
|
|
275
|
+
*
|
|
276
|
+
* @param name - The event's name in `spec.events`; an unknown name throws.
|
|
277
|
+
* @param data - The event's data.
|
|
278
|
+
* @param window - One window's id. Omit it for every window.
|
|
279
|
+
*/
|
|
280
|
+
emit<Name extends keyof NonNullable<S["events"]> & string>(name: Name, data: TypeOf<NonNullable<S["events"]>[Name]>, window?: number): void;
|
|
281
|
+
/**
|
|
282
|
+
* Withdraws the Ipc before the instance goes away. Windows see it `pending`, and calls wait, until it is provided again
|
|
283
|
+
* or the instance goes away. The host also withdraws it then.
|
|
284
|
+
*/
|
|
285
|
+
dispose(): void;
|
|
286
|
+
}
|
|
287
|
+
/**
|
|
288
|
+
* What every entry gets, in the window and in main. Each process adds the APIs its host always provides as properties
|
|
289
|
+
* (`ctx.layout`, `ctx.storage`, …), created on first read, and `provide` for the contracts it hosts.
|
|
290
|
+
*/
|
|
291
|
+
export interface BaseContext {
|
|
292
|
+
/**
|
|
293
|
+
* The plugin's options from `opencode.json`, as `ctx.options` in its server and TUI halves. Empty for a built-in.
|
|
294
|
+
*
|
|
295
|
+
* @example
|
|
296
|
+
* ```ts
|
|
297
|
+
* // "plugins": [{ "package": "opencode-acme", "options": { "team": "core" } }]
|
|
298
|
+
* const team = ctx.options.team
|
|
299
|
+
* ```
|
|
300
|
+
*/
|
|
301
|
+
readonly options: PluginOptions;
|
|
302
|
+
/**
|
|
303
|
+
* The client of the server that runs the plugin, the desktop app's own server, as `context.client` in a TUI plugin.
|
|
304
|
+
* Call the plugin's server part through it. A new client after that server restarts; read it where you call it.
|
|
305
|
+
* While the server is unreachable, every call rejects. A built-in plugin gets a client whose calls all reject.
|
|
306
|
+
*
|
|
307
|
+
* @example
|
|
308
|
+
* ```ts
|
|
309
|
+
* const result = await ctx.client.rpc(Acme).search({ query })
|
|
310
|
+
* ```
|
|
311
|
+
*/
|
|
312
|
+
readonly client: OpenCodeClient;
|
|
313
|
+
/**
|
|
314
|
+
* The plugin's id, as its `Plugin.define` declares it.
|
|
315
|
+
*
|
|
316
|
+
* @example
|
|
317
|
+
* ```ts
|
|
318
|
+
* const key = `${ctx.id}:${tab.id}`
|
|
319
|
+
* ```
|
|
320
|
+
*/
|
|
321
|
+
readonly id: string;
|
|
322
|
+
/**
|
|
323
|
+
* Aborts when the plugin is disabled or reloaded, or when its process ends: the window closes, or the app quits.
|
|
324
|
+
* After an `await`, return if it aborted. A window has no owner after an `await`, so listen to the signal for
|
|
325
|
+
* teardown that starts there.
|
|
326
|
+
*
|
|
327
|
+
* @example
|
|
328
|
+
* ```ts
|
|
329
|
+
* const config = await load({ signal: ctx.signal })
|
|
330
|
+
* if (ctx.signal.aborted) return
|
|
331
|
+
* ```
|
|
332
|
+
*/
|
|
333
|
+
readonly signal: AbortSignal;
|
|
334
|
+
/**
|
|
335
|
+
* Contributes an item that follows reactive state, such as the language: the window re-runs the function when what
|
|
336
|
+
* it reads changes (main reads it on every `list`). Return undefined to withdraw the item until it returns one
|
|
337
|
+
* again. The host withdraws it with the current owner (a `createKeyed` run or a component), else with the plugin;
|
|
338
|
+
* made after that owner or the plugin ended, it is withdrawn at once.
|
|
339
|
+
*
|
|
340
|
+
* @param registry - Where the item goes, such as `Command` or `TitlebarItem`.
|
|
341
|
+
* @param item - Returns the item, or undefined for none.
|
|
342
|
+
* @returns Withdraws the item early.
|
|
343
|
+
*
|
|
344
|
+
* @example
|
|
345
|
+
* ```ts
|
|
346
|
+
* ctx.add(Command, () => ({ id: "toggle", title: ctx.t("toggle"), run: toggle }))
|
|
347
|
+
* ctx.add(TitlebarItem, () => (shown() ? pill : undefined))
|
|
348
|
+
* ```
|
|
349
|
+
*/
|
|
350
|
+
add<T>(registry: Registry<T>, item: () => T | undefined): Cleanup;
|
|
351
|
+
/**
|
|
352
|
+
* Contributes a fixed item to a registry. The host withdraws it with the current owner (a `createKeyed` run or a
|
|
353
|
+
* component), else with the plugin; made after that owner or the plugin ended, it is withdrawn at once. Use the
|
|
354
|
+
* function form for an item whose labels follow the language.
|
|
355
|
+
*
|
|
356
|
+
* @param registry - Where the item goes, such as `Command` or `Style`.
|
|
357
|
+
* @param item - The item.
|
|
358
|
+
* @returns Withdraws the item early.
|
|
359
|
+
*
|
|
360
|
+
* @example
|
|
361
|
+
* ```ts
|
|
362
|
+
* ctx.add(Style, css)
|
|
363
|
+
* ```
|
|
364
|
+
*/
|
|
365
|
+
add<T>(registry: Registry<T>, item: T): Cleanup;
|
|
366
|
+
/**
|
|
367
|
+
* The items every plugin contributed to a registry, in contribution order. Reactive in the window. Use it for a
|
|
368
|
+
* registry your plugin owns.
|
|
369
|
+
*
|
|
370
|
+
* @param registry - The registry to read.
|
|
371
|
+
*
|
|
372
|
+
* @example
|
|
373
|
+
* ```ts
|
|
374
|
+
* const badges = () => ctx.list(Badge)
|
|
375
|
+
* ```
|
|
376
|
+
*/
|
|
377
|
+
list<T>(registry: Registry<T>): readonly T[];
|
|
378
|
+
/**
|
|
379
|
+
* Translates a key from the plugin's catalog in the current locale, then from the app's shared keys
|
|
380
|
+
* (`common.*`). Reactive in the window. Main returns the key itself when no catalog has it.
|
|
381
|
+
*
|
|
382
|
+
* @param key - The message key.
|
|
383
|
+
* @param params - Values for the template's `{{name}}` placeholders.
|
|
384
|
+
*
|
|
385
|
+
* @example
|
|
386
|
+
* ```ts
|
|
387
|
+
* ctx.t("title")
|
|
388
|
+
* ```
|
|
389
|
+
*/
|
|
390
|
+
t(key: string, params?: Params): string;
|
|
391
|
+
/**
|
|
392
|
+
* Translates a count-sensitive message: reads `<key>.<category>` for the locale's plural category of `count`, then
|
|
393
|
+
* `<key>.other`. `{{count}}` is set for you.
|
|
394
|
+
*
|
|
395
|
+
* @param key - The base key, without the category.
|
|
396
|
+
* @param count - The number that picks the category.
|
|
397
|
+
* @param params - Other placeholders.
|
|
398
|
+
*
|
|
399
|
+
* @example
|
|
400
|
+
* ```ts
|
|
401
|
+
* ctx.plural("files", 3) // "3 files" from { "files.one": "{{count}} file", "files.other": "{{count}} files" }
|
|
402
|
+
* ```
|
|
403
|
+
*/
|
|
404
|
+
plural(key: string, count: number, params?: Params): string;
|
|
405
|
+
}
|
|
406
|
+
/**
|
|
407
|
+
* An older home of a stored value, imported once into a store that has no value yet: a stored key of the same
|
|
408
|
+
* storage, such as the key of a store the plugin renamed, e.g. `"plugin.acme.settings"`. Where `from` takes a list,
|
|
409
|
+
* it names several older homes, newest first, and the first that holds a value is imported. The older home keeps its
|
|
410
|
+
* copy until the store is removed.
|
|
411
|
+
*
|
|
412
|
+
* @example
|
|
413
|
+
* ```ts
|
|
414
|
+
* Store.global(Prefs, { expanded: true }, ["plugin.acme.settings.v2", "plugin.acme.settings"])
|
|
415
|
+
* ```
|
|
416
|
+
*/
|
|
417
|
+
export type StoreFrom = string;
|
|
418
|
+
type StoreSchema = Schema.ConstraintCodec<object, unknown>;
|
|
419
|
+
/** A store a plugin declares in `Plugin.define({ stores })`. Build one with `Store.global` or `Store.session`. */
|
|
420
|
+
export interface StoreDeclaration<S extends StoreSchema = StoreSchema, Scope extends "global" | "session" = "global" | "session"> {
|
|
421
|
+
/**
|
|
422
|
+
* Where the value lives.
|
|
423
|
+
* - `global`: one value for the app, loaded before setup.
|
|
424
|
+
* - `session`: one value per session, loaded when the session mounts.
|
|
425
|
+
*/
|
|
426
|
+
readonly scope: Scope;
|
|
427
|
+
/**
|
|
428
|
+
* Decodes the stored JSON; an object schema. A field of a plain struct that is missing or fails to decode takes its
|
|
429
|
+
* `initial` value; a value that fails as a whole reads as `initial`.
|
|
430
|
+
*/
|
|
431
|
+
readonly schema: S;
|
|
432
|
+
/** The value before anything is stored, and after `Storage.remove`. */
|
|
433
|
+
readonly initial: S["Type"];
|
|
434
|
+
/** Older homes the value is imported from once. See `StoreFrom`. */
|
|
435
|
+
readonly from?: StoreFrom | readonly StoreFrom[];
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Declares window state. The store's name in `stores` is its key, stored as `plugin.<id>.<name>`. Desktop windows
|
|
439
|
+
* load storage over IPC, so the host loads declared stores for you before they are read. The main process opens its
|
|
440
|
+
* state with `ctx.storage.store`, which reads synchronously.
|
|
441
|
+
*
|
|
442
|
+
* @example
|
|
443
|
+
* ```ts
|
|
444
|
+
* stores: {
|
|
445
|
+
* prefs: Store.global(Prefs, { shown: true }, "plugin.acme.settings"),
|
|
446
|
+
* view: Store.session(View, { open: [] }),
|
|
447
|
+
* }
|
|
448
|
+
* ```
|
|
449
|
+
*/
|
|
450
|
+
export declare const Store: {
|
|
451
|
+
/**
|
|
452
|
+
* One value for the app. The host loads every global store before setup, so `ctx.stores.name.value` is never
|
|
453
|
+
* undefined. A load that fails fails the plugin's setup.
|
|
454
|
+
*
|
|
455
|
+
* @param schema - Decodes the stored JSON; an object schema.
|
|
456
|
+
* @param initial - The value before anything is stored.
|
|
457
|
+
* @param from - Older homes to import the value from once.
|
|
458
|
+
*/
|
|
459
|
+
global: <S extends StoreSchema>(schema: S, initial: NoInfer<S["Type"]>, from?: StoreFrom | readonly StoreFrom[]) => StoreDeclaration<S, "global">;
|
|
460
|
+
/**
|
|
461
|
+
* One value per session. The host starts loading it when the session mounts, before its regions render;
|
|
462
|
+
* `ctx.stores.name(session).value` is undefined until then and while the session's location is unknown.
|
|
463
|
+
*
|
|
464
|
+
* @param schema - Decodes the stored JSON; an object schema.
|
|
465
|
+
* @param initial - The value before anything is stored.
|
|
466
|
+
* @param from - Older homes to import the value from once.
|
|
467
|
+
*/
|
|
468
|
+
session: <S extends StoreSchema>(schema: S, initial: NoInfer<S["Type"]>, from?: StoreFrom | readonly StoreFrom[]) => StoreDeclaration<S, "session">;
|
|
469
|
+
};
|
|
470
|
+
/**
|
|
471
|
+
* Stored state, the same shape in both processes. `V` is the value's type while it may still be loading: a global
|
|
472
|
+
* declared store and every main store use `T`, so `value` is never undefined.
|
|
473
|
+
*
|
|
474
|
+
* @example
|
|
475
|
+
* ```ts
|
|
476
|
+
* const prefs = ctx.stores.prefs
|
|
477
|
+
* prefs.update((draft) => { draft.shown = !draft.shown })
|
|
478
|
+
* prefs.set({ shown: true })
|
|
479
|
+
* ```
|
|
480
|
+
*/
|
|
481
|
+
export interface Persisted<T, V = T | undefined> {
|
|
482
|
+
/** The stored value; undefined until it has loaded. Reactive in the window. */
|
|
483
|
+
readonly value: V;
|
|
484
|
+
/** The stored value has loaded. Always true in main. Reactive in the window. */
|
|
485
|
+
ready(): boolean;
|
|
486
|
+
/**
|
|
487
|
+
* Mutates a deep-mutable draft, even when the schema's fields are readonly. Return nothing or `undefined`;
|
|
488
|
+
* returning a replacement is a compile error and throws at runtime. Use `set` to replace the value. In the
|
|
489
|
+
* window it waits for load and applies in call order with `set`; in main it writes at once.
|
|
490
|
+
*
|
|
491
|
+
* @param mutate - Edits a draft of the current value in place.
|
|
492
|
+
*/
|
|
493
|
+
update(mutate: (
|
|
494
|
+
/** A deep-mutable copy of the current value; edit it in place. */
|
|
495
|
+
draft: Mutable<T>) => undefined): void;
|
|
496
|
+
/**
|
|
497
|
+
* Replaces the stored value. In the window it waits for load and applies in call order with `update`; in main it
|
|
498
|
+
* writes at once. Use this for primitives or to replace an object or collection.
|
|
499
|
+
*
|
|
500
|
+
* @param next - The complete next value, typed by the store's schema.
|
|
501
|
+
*/
|
|
502
|
+
set(next: T): void;
|
|
503
|
+
}
|
|
504
|
+
/** A stored value's writable draft, recursively removing readonly fields and collection entries. */
|
|
505
|
+
export type Mutable<T> = T extends object ? {
|
|
506
|
+
-readonly [K in keyof T]: Mutable<T[K]>;
|
|
507
|
+
} : T;
|
|
508
|
+
/** The stores a definition declares; `{}` when it declares none. */
|
|
509
|
+
export type DeclaredStores<D> = D extends {
|
|
510
|
+
readonly stores?: infer M;
|
|
511
|
+
} ? M extends Readonly<Record<string, StoreDeclaration>> ? M : {} : {};
|
|
512
|
+
/**
|
|
513
|
+
* Defines registries.
|
|
514
|
+
*
|
|
515
|
+
* @example
|
|
516
|
+
* ```ts
|
|
517
|
+
* export const Badge = Registry.define<{ readonly label: string }>("details.badge")
|
|
518
|
+
* ```
|
|
519
|
+
*/
|
|
520
|
+
export declare const Registry: {
|
|
521
|
+
/**
|
|
522
|
+
* Creates a registry token.
|
|
523
|
+
*
|
|
524
|
+
* @param id - The registry's id; start it with your plugin's id.
|
|
525
|
+
*/
|
|
526
|
+
define: <T>(id: string) => Registry<T>;
|
|
527
|
+
};
|
|
528
|
+
/**
|
|
529
|
+
* Defines in-process contracts.
|
|
530
|
+
*
|
|
531
|
+
* @example
|
|
532
|
+
* ```ts
|
|
533
|
+
* export const Changes = Contract.define<Changes, "review.changes">("review.changes")
|
|
534
|
+
* ```
|
|
535
|
+
*/
|
|
536
|
+
export declare const Contract: {
|
|
537
|
+
/**
|
|
538
|
+
* Creates a contract token.
|
|
539
|
+
*
|
|
540
|
+
* @param id - The contract's id: your plugin's id, or `<id>.<name>`. Only that plugin may provide it.
|
|
541
|
+
*/
|
|
542
|
+
define: <T, const Id extends string>(id: Id) => Contract<T, Id>;
|
|
543
|
+
};
|
|
544
|
+
/**
|
|
545
|
+
* Defines Ipcs between a plugin's main entry and its windows.
|
|
546
|
+
*
|
|
547
|
+
* @example
|
|
548
|
+
* ```ts
|
|
549
|
+
* export const Pairing = Ipc.define({ id: "pairing", methods: { screenActive: { output: Schema.Boolean } } })
|
|
550
|
+
* ```
|
|
551
|
+
*/
|
|
552
|
+
export declare const Ipc: {
|
|
553
|
+
/**
|
|
554
|
+
* Creates an Ipc token from its schemas.
|
|
555
|
+
*
|
|
556
|
+
* @param spec - The Ipc's id, state, methods and events.
|
|
557
|
+
*/
|
|
558
|
+
define: <const S extends IpcSpec>(spec: S) => Ipc<S>;
|
|
559
|
+
};
|
|
560
|
+
export {};
|
package/dist/gui/core.js
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Declares window state. The store's name in `stores` is its key, stored as `plugin.<id>.<name>`. Desktop windows
|
|
3
|
+
* load storage over IPC, so the host loads declared stores for you before they are read. The main process opens its
|
|
4
|
+
* state with `ctx.storage.store`, which reads synchronously.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* stores: {
|
|
9
|
+
* prefs: Store.global(Prefs, { shown: true }, "plugin.acme.settings"),
|
|
10
|
+
* view: Store.session(View, { open: [] }),
|
|
11
|
+
* }
|
|
12
|
+
* ```
|
|
13
|
+
*/
|
|
14
|
+
export const Store = {
|
|
15
|
+
/**
|
|
16
|
+
* One value for the app. The host loads every global store before setup, so `ctx.stores.name.value` is never
|
|
17
|
+
* undefined. A load that fails fails the plugin's setup.
|
|
18
|
+
*
|
|
19
|
+
* @param schema - Decodes the stored JSON; an object schema.
|
|
20
|
+
* @param initial - The value before anything is stored.
|
|
21
|
+
* @param from - Older homes to import the value from once.
|
|
22
|
+
*/
|
|
23
|
+
global: (schema, initial, from) => ({
|
|
24
|
+
scope: "global",
|
|
25
|
+
schema,
|
|
26
|
+
initial,
|
|
27
|
+
from,
|
|
28
|
+
}),
|
|
29
|
+
/**
|
|
30
|
+
* One value per session. The host starts loading it when the session mounts, before its regions render;
|
|
31
|
+
* `ctx.stores.name(session).value` is undefined until then and while the session's location is unknown.
|
|
32
|
+
*
|
|
33
|
+
* @param schema - Decodes the stored JSON; an object schema.
|
|
34
|
+
* @param initial - The value before anything is stored.
|
|
35
|
+
* @param from - Older homes to import the value from once.
|
|
36
|
+
*/
|
|
37
|
+
session: (schema, initial, from) => ({ scope: "session", schema, initial, from }),
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* Defines registries.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* ```ts
|
|
44
|
+
* export const Badge = Registry.define<{ readonly label: string }>("details.badge")
|
|
45
|
+
* ```
|
|
46
|
+
*/
|
|
47
|
+
export const Registry = {
|
|
48
|
+
/**
|
|
49
|
+
* Creates a registry token.
|
|
50
|
+
*
|
|
51
|
+
* @param id - The registry's id; start it with your plugin's id.
|
|
52
|
+
*/
|
|
53
|
+
define: (id) => ({ kind: "registry", id }),
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* Defines in-process contracts.
|
|
57
|
+
*
|
|
58
|
+
* @example
|
|
59
|
+
* ```ts
|
|
60
|
+
* export const Changes = Contract.define<Changes, "review.changes">("review.changes")
|
|
61
|
+
* ```
|
|
62
|
+
*/
|
|
63
|
+
export const Contract = {
|
|
64
|
+
/**
|
|
65
|
+
* Creates a contract token.
|
|
66
|
+
*
|
|
67
|
+
* @param id - The contract's id: your plugin's id, or `<id>.<name>`. Only that plugin may provide it.
|
|
68
|
+
*/
|
|
69
|
+
define: (id) => ({ kind: "contract", id }),
|
|
70
|
+
};
|
|
71
|
+
/**
|
|
72
|
+
* Defines Ipcs between a plugin's main entry and its windows.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```ts
|
|
76
|
+
* export const Pairing = Ipc.define({ id: "pairing", methods: { screenActive: { output: Schema.Boolean } } })
|
|
77
|
+
* ```
|
|
78
|
+
*/
|
|
79
|
+
export const Ipc = {
|
|
80
|
+
/**
|
|
81
|
+
* Creates an Ipc token from its schemas.
|
|
82
|
+
*
|
|
83
|
+
* @param spec - The Ipc's id, state, methods and events.
|
|
84
|
+
*/
|
|
85
|
+
define: (spec) => ({ kind: "ipc", id: spec.id, spec }),
|
|
86
|
+
};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { Catalog, OS, StoreDeclaration } from "./core.js";
|
|
2
|
+
/** The stores a plugin's GUI may declare. */
|
|
3
|
+
export type Stores = Readonly<Record<string, StoreDeclaration>>;
|
|
4
|
+
/**
|
|
5
|
+
* What a plugin's GUI declares: its window state, its copy and the systems it runs on. `Plugin.define` returns this
|
|
6
|
+
* for a definition without setups, so setups in other files are typed from it (`Plugin.Setup<typeof definition>`).
|
|
7
|
+
* The host reads it before any setup runs. The plugin's id is not declared here: the host assigns it (`ctx.id`), from
|
|
8
|
+
* the server plugin for a `./gui-experimental` bundle. Contracts are provided and read at runtime, with `ctx.provide`,
|
|
9
|
+
* `ctx.use` and `ctx.main`.
|
|
10
|
+
*/
|
|
11
|
+
export interface Declarations<S extends Stores = Stores> {
|
|
12
|
+
/**
|
|
13
|
+
* The operating systems the plugin runs on. Omit it to run on every OS. A plugin from the config runs only in the
|
|
14
|
+
* desktop app; a built-in that lists any OS does not run on the web, where no OS is known.
|
|
15
|
+
*/
|
|
16
|
+
readonly os?: readonly OS[];
|
|
17
|
+
/** The plugin's copy. `ctx.t` reads it first, then the app's shared keys such as `common.*`. */
|
|
18
|
+
readonly i18n?: Catalog;
|
|
19
|
+
/**
|
|
20
|
+
* Window state the host stores for the plugin, by store name, loaded before it is read. See `Store`. Keys known only
|
|
21
|
+
* at runtime, and every main-process value, go through `ctx.storage.store`.
|
|
22
|
+
*/
|
|
23
|
+
readonly stores?: S;
|
|
24
|
+
}
|
|
File without changes
|