@drift-beacon/plugin 0.1.1 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 The plugin SDK for [Drift Beacon](https://driftbeacon.app). A plugin has **main code**, which runs on your Drift Beacon server, and a **UI**, which opens in the web app. This package gives you their APIs, a Vite plugin that builds both, and the `dbplugin` command that packages a release.
 
-Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers that run API 0.1.
+Plugin API version: **0.2**. SDK `0.2.x` builds plugins for Drift Beacon servers that run API 0.2.
 
 ## Contents
 
@@ -16,6 +16,8 @@ Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers
 - [Storage](#storage)
 - [Configuration](#configuration)
 - [MQTT and HTTP routes](#mqtt-and-http-routes)
+- [Commands between plugins](#commands-between-plugins)
+- [Events, state and status between plugins](#events-state-and-status-between-plugins)
 - [Errors and limits](#errors-and-limits)
 - [Developing against your server](#developing-against-your-server)
 - [Releasing a plugin](#releasing-a-plugin)
@@ -27,7 +29,7 @@ Plugin API version: **0.1**. SDK `0.1.x` builds plugins for Drift Beacon servers
 mkdir my-plugin && cd my-plugin
 npm init -y
 npm pkg set type=module
-npm install --save-dev @drift-beacon/plugin@0.1 vite typescript @types/node
+npm install --save-dev @drift-beacon/plugin@0.2 vite typescript @types/node
 ```
 
 `package.json` scripts:
@@ -65,7 +67,7 @@ export default defineConfig({ plugins: [driftBeacon()] }); // with React: [react
   "id": "hello",
   "name": "Hello",
   "version": "1.0.0",
-  "apiVersion": "0.1",
+  "apiVersion": "0.2",
   "description": "Says hello when a session starts",
   "author": { "name": "You" },
   "category": "plugin",
@@ -127,7 +129,7 @@ Then `npm run build` writes `dist/`, and `npm run release` writes `releases/hell
 my-plugin/
 ├── package.json        # "type": "module"
 ├── vite.config.ts      # plugins: [driftBeacon()]
-├── tsconfig.json       # references .drift-beacon/tsconfig.{main,ui}.json
+├── tsconfig.json       # references the main and UI tsconfigs
 ├── manifest.json       # identity, API version, icon, settings
 ├── main/src/index.ts   # main code: runs on the server
 ├── ui/                 # the UI: an ordinary Vite app, shown in an iframe in the web app
@@ -142,14 +144,28 @@ my-plugin/
 |---|---|
 | `vite` (`npm run dev`) | Serves the UI with hot reload and rebuilds main on every save. A Drift Beacon server in development mode applies each build and prints the plugin's status and logs in the same terminal. |
 | `vite build` | Production build into `dist/`: `manifest.json`, `package.json`, `main/index.js` and `ui/`. |
-| `dbplugin pack` | Typechecks main and the UI, builds fresh into a temporary folder and writes `releases/<id>.zip`. Prints `{ id, version, tag, asset, archivePath }` as JSON on stdout. `dist/` is untouched. `--out <dir>` picks another folder. |
+| `dbplugin pack` | Typechecks main and the UI (see [Compiler options](#compiler-options)), builds fresh into a temporary folder and writes `releases/<id>.zip`. Prints `{ id, version, tag, asset, archivePath }` as JSON on stdout. `dist/` is untouched. `--out <dir>` picks another folder. |
 | `dbplugin prepare` | Writes `.drift-beacon/`: typed settings and the two tsconfigs. Runs on install and on every build. |
 
 Run `dbplugin` through your package scripts or `npx dbplugin …` inside the plugin folder: it's the copy from your installed SDK.
 
 - **Main** is bundled into one ESM file with every dependency except `@drift-beacon/plugin`, which the server supplies at run time. Native modules aren't supported.
 - **The UI** bundles its own dependencies, including `@drift-beacon/plugin/ui`. Use any framework and library versions you like.
-- `driftBeacon()` owns Vite's `root` (`ui/`), `base` and `build.outDir`: don't set them. It works with Vite 7 and 8.
+- `driftBeacon()` owns Vite's `root` (`ui/`), `base` and `build.outDir`: don't set them. It works with Vite 7 and 8. Under Vitest it only adds the build, so your tests can share `vite.config.ts` while `npm run dev` runs.
+
+### Compiler options
+
+`dbplugin prepare` generates `.drift-beacon/tsconfig.main.json` and `.drift-beacon/tsconfig.ui.json` (React JSX in the UI). To change a compiler option, add `main/tsconfig.json` or `ui/tsconfig.json` that extends the generated file, and reference it from `tsconfig.json` instead. `dbplugin pack` typechecks it in place of the generated one. For a Preact UI:
+
+```json
+{ "extends": "../.drift-beacon/tsconfig.ui.json", "compilerOptions": { "jsxImportSource": "preact" } }
+```
+
+```json
+{ "files": [], "references": [{ "path": "./.drift-beacon/tsconfig.main.json" }, { "path": "./ui/tsconfig.json" }] }
+```
+
+Keep `extends`: the generated file brings the settings types, the SDK's module resolution and the source folders.
 
 | Import | Used by | Contents |
 |---|---|---|
@@ -163,12 +179,14 @@ Run `dbplugin` through your package scripts or `npx dbplugin …` inside the plu
 |---|---|
 | `id` | Lowercase letters, digits and hyphens, starting with a letter or digit, at most 64 characters |
 | `version` | Semantic version (`1.2.3`); build metadata is allowed, prereleases are not |
-| `apiVersion` | `major.minor` of the SDK you build with (`"0.1"`) |
+| `apiVersion` | `major.minor` of the SDK you build with (`"0.2"`) |
 | `name`, `description` | Required text |
 | `author` | `{ name, email? }` |
 | `category` | `plugin`, `utility` or `ui` |
 | `icon` | A file name in `ui/public/`, or `""` |
 | `configuration` | Settings (see [Configuration](#configuration)) |
+| `provides` | Optional: commands, events and state other plugins can use (see [Commands between plugins](#commands-between-plugins) and [Events, state and status](#events-state-and-status-between-plugins)) |
+| `uses` | Optional: the plugins this one uses, by manifest id, with a version range (`{ "magic-cube": "^1.1.0" }`) |
 
 Settings items have `name` (unique), `title`, `type` and optional `description` and `required`:
 
@@ -196,11 +214,13 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 | `onDataChange` | ✓ | ✓ | The data changed |
 | `sessions.onStarted`, `onEnded`, `onMarked` | ✓ | | Live session events |
 | `storage` | ✓ | ✓ | Key-value storage |
+| `plugins` | ✓ | ✓ | The plugins it uses and itself: status, state and commands (and events, in main code) |
+| `commands`, `events`, `state` | ✓ | | What it provides to other plugins |
 | `mqtt`, `routes`, `log`, `onStop` | ✓ | | Main code only |
 
 ## UI
 
-`connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings or storage).
+`connect()` performs a handshake with the web app and resolves to the UI `ctx`. It rejects with `unsupported` when the app doesn't run this UI's API version, and with `unavailable` outside Drift Beacon or after 10 seconds without an answer. `ctx.onDataChange` fires after every update (data, settings, storage, or other plugins' status and state).
 
 With React, re-render on every update:
 
@@ -294,7 +314,7 @@ Never trigger actions from data changes. Live events fire for everyone's session
 
 ## Storage
 
-Per plugin, user and workspace, shared by main code and the UI. Values must be JSON.
+Per plugin, user and workspace, shared by main code and the UI. Values must be JSON: anything else rejects with `invalid`, and setting `undefined` removes the key. `set` and `remove` apply at once and resolve when Drift Beacon has accepted the write.
 
 ```ts
 const faces = ctx.storage.get<Record<string, string>>("faces") ?? {};
@@ -307,6 +327,8 @@ ctx.storage.onChange((key, value) => { /* changed by main code, a UI or another
 
 `ctx.config` holds the settings from the manifest's `configuration`. `dbplugin prepare` turns them into types (`.drift-beacon/config.d.ts`), so `ctx.config.mqttTopic` is typed in main code and the UI. A setting is optional unless it is `required` or has a `default`. An instance only runs with valid settings; changing them restarts it.
 
+A UI can open before setup is finished. Until then its `ctx.config` holds the defaults under whatever the user has saved, unvalidated: a `required` setting can still be missing. Check before relying on one.
+
 ## MQTT and HTTP routes
 
 Main code only.
@@ -322,6 +344,65 @@ ctx.routes.get("status", () => ({ body: { live: ctx.sessions.live({ mine: true }
 - MQTT uses the workspace's broker; `publish` rejects with `unavailable` without one.
 - Routes are served at `<server>/api/plugins/<plugin id>/api/<name>` (`ctx.plugin.apiPath` is the path up to `/api`). Callers send `Authorization: Bearer <workspace API key>`, which picks the user and workspace. Handlers return `{ status?, body? }`; `body` is sent as JSON.
 
+## Commands between plugins
+
+Main code provides commands; main code and UIs run them. A plugin declares the commands it provides in `manifest.json` and handles them; another plugin lists it in `uses` and runs them, as the same user in the same workspace.
+
+```jsonc
+// magic-cube/manifest.json
+"provides": { "commands": { "selectPreset": {
+  "title": "Select preset",
+  "input": { "type": "object", "properties": { "preset": { "type": ["string", "null"] } }, "required": ["preset"] },
+  "output": { "type": "object", "properties": { "activePresetId": { "type": ["string", "null"] } } }
+} } }
+// cartridge-reader/manifest.json
+"uses": { "magic-cube": "^1.1.0" }
+```
+
+```ts
+// magic-cube
+ctx.commands.handle("selectPreset", async ({ preset }, meta) => ({ activePresetId: await select(preset) }));
+// cartridge-reader
+const result = await ctx.plugins.get("magic-cube").command("selectPreset", { preset: "Focus" });
+```
+
+- Names are camelCase. Schemas are a subset of JSON Schema: `type` (a name or a list such as `["string", "null"]`), `enum`, `properties`, `required`, `additionalProperties` (objects are closed by default), `items`, `minimum`, `maximum`, `title`, `description`, `default`. Other keywords are rejected.
+- The input is checked before the command runs (`invalid`), the output after (`failed`). Throw a `PluginError` to answer with its code.
+- It fails fast: `not-installed`, `disabled`, `incompatible` (outside your range) or `unavailable` (not running; it didn't run). `timeout` and `stopped` mean it may have run.
+- `timeoutMs` defaults to 10 s (at most 30 s). A command run inside another continues its chain and shares what's left of its time; the ninth step of a chain is refused with `loop`.
+- From a UI: `ctx.plugins.get(id).command(…)` as in main code. The UI waits the command's time plus 2 s, then rejects `timeout`.
+- `dbplugin prepare` types what you provide (`.drift-beacon/config.d.ts`): `ctx.commands.handle`, `ctx.events.emit` and `ctx.state` take only declared names, with their declared types (none for a kind you declare nothing of). Plugins you use aren't typed yet.
+
+## Events, state and status between plugins
+
+Main code emits and publishes; UIs read state and status (not events). A plugin emits the events and publishes the state it declares in `provides`; the plugins that use it (and the plugin itself, through `ctx.plugins.self`) receive them, and see its status.
+
+```jsonc
+// magic-cube/manifest.json
+"provides": {
+  "events": { "faceChanged": { "title": "Face changed", "payload": { "type": "integer", "minimum": 1, "maximum": 6 } } },
+  "state": { "activePreset": { "title": "Active preset", "schema": { "type": ["string", "null"] } } }
+}
+```
+
+```ts
+// magic-cube
+ctx.events.emit("faceChanged", 3);
+ctx.state.set("activePreset", "focus"); // undefined removes it
+// cartridge-reader
+const cube = ctx.plugins.get("magic-cube");
+cube.onEvent("faceChanged", (face, meta) => ctx.log.info(`Face ${face}, step ${meta.depth}`));
+cube.state.get("activePreset"); // read it in onStart, then follow cube.state.onChange
+cube.onStatusChange(({ state, reason }) => ctx.log.info(state, reason ?? ""));
+```
+
+- `emit` and `set` throw `invalid` for an undeclared name, a value that doesn't match its schema, or over 64 KiB (256 KiB of state in all). Received values are frozen.
+- Events reach listeners registered by then (from `onStart` on); earlier ones are missed. State is kept in memory while the provider runs, cleared when it stops, never persisted.
+- In main code, a command handler's events and state changes arrive before its caller's `await` resumes.
+- Listeners continue the chain of what caused them; past 8 steps, events are dropped (with a warning) and state changes call no callbacks.
+- `status.state` is `running`, `starting`, `unavailable`, `disabled`, `incompatible` or `not-installed`, with the resolved `version` and a `reason`.
+- In a UI, status and state arrive within about 250 ms (and `ctx.onDataChange` fires), as the latest at each update (changes close together arrive as one), so a command's effects can show just after it resolves: render from `onChange`, or use its output.
+
 ## Errors and limits
 
 Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
@@ -329,11 +410,13 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 | Code | Meaning |
 |---|---|
 | `unsupported` | The app doesn't support this API version or request |
-| `invalid` | Bad arguments (tracking a point with `start()`, a value that isn't JSON, …) |
+| `invalid` | Bad arguments (tracking a point with `start()`, a value that isn't JSON, an undeclared event, …) |
 | `not-found` | The activity or session doesn't exist, or the model was removed |
 | `unavailable` | Something needed isn't there: no MQTT broker, no answer from the app |
 | `stopped` | The instance has stopped |
 | `failed` | Anything else, such as tracking an archived activity |
+| `not-installed`, `disabled`, `incompatible` | The plugin you ran a command on isn't installed, is disabled here, or is outside your `uses` range |
+| `loop`, `timeout` | A chain of commands went deeper than 8 steps; a command didn't answer in time (it may have run) |
 
 | | Limit |
 |---|---|
@@ -341,6 +424,7 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 | Blocking the event loop | The server restarts the plugin host after 10 s |
 | Actions | 10 s, then `unavailable` |
 | Route handlers | 30 s, then 504 |
+| Commands to other plugins | 10 s by default (at most 30 s), then `timeout`; 8 steps deep; 64 KiB in and out |
 | Release package | 32 MiB zipped, 128 MiB unpacked, 2,000 files |
 
 ## Developing against your server
@@ -360,7 +444,7 @@ Users add the repository URL in **Plugins → Store** and install from there. Do
 ## Versions
 
 - `apiVersion` in the manifest must match the SDK: `dbplugin`, `vite build` and the server all check it.
-- Before 1.0, each minor version (`0.1`, `0.2`) may change the API, and a server runs only its exact version. Install the SDK with `@0.1` to stay on it.
+- Before 1.0, each minor version (`0.1`, `0.2`) may change the API, and a server runs only its exact version. Install the SDK with `@0.2` to stay on it.
 - Minor releases may add fields and new string values (such as a new `trackingType`): ignore what you don't recognise.
 
 ## License

package/dist/internal/collection.js

@@ -1,12 +1,5 @@
+import { deepFreeze } from "./freeze.js";
 import { jsonEqual } from "./json-equal.js";
-function deepFreeze(value) {
-    if (value && typeof value === "object" && !Object.isFrozen(value)) {
-        for (const child of Object.values(value))
-            deepFreeze(child);
-        Object.freeze(value);
-    }
-    return value;
-}
 export class Collection {
     rows = new Map();
     cachedList = null;

package/dist/internal/freeze.js

@@ -0,0 +1,8 @@
+export function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}

package/dist/internal/manifest.js

@@ -1,8 +1,9 @@
 import { parseApiVersion } from "./compatibility.js";
-const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-export const isStableVersion = (value) => typeof value === "string" &&
-    STABLE_VERSION.test(value) &&
-    (value.split("+")[0] ?? "").split(".").every((part) => Number.isSafeInteger(Number(part)));
+import { PEER_LIMITS, PEER_NAME } from "./peers.js";
+import { validateSchema } from "./schema.js";
+import { isStableVersion, validateRange } from "./semver.js";
+const PLUGIN_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export const isManifestId = (id) => PLUGIN_ID.test(id);
 export function validateManifest(manifest) {
     if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
         throw new Error("Invalid plugin manifest");
@@ -12,8 +13,8 @@ export function validateManifest(manifest) {
         if (typeof text !== "string" || !text.trim())
             throw new Error(`Plugin manifest missing required field: ${field}`);
     }
-    const { id, version, apiVersion, author, category, icon, configuration } = value;
-    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(id)) {
+    const { id, version, apiVersion, author, category, icon, configuration, provides, uses } = value;
+    if (!PLUGIN_ID.test(id)) {
         throw new Error("Plugin id must contain only lowercase letters, numbers and hyphens (maximum 64 characters)");
     }
     if (!isStableVersion(version)) {
@@ -34,6 +35,79 @@ export function validateManifest(manifest) {
     const names = new Set();
     for (const item of configuration)
         validateConfigurationItem(item, names);
+    if (provides !== undefined)
+        validateProvides(provides);
+    if (uses !== undefined)
+        validateUses(uses, id);
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const DECLARATION_FIELDS = {
+    commands: ["title", "description", "input", "output"],
+    events: ["title", "description", "payload"],
+    state: ["title", "description", "schema"],
+};
+function validateProvides(provides) {
+    if (!isRecord(provides))
+        throw new Error("provides: must be an object");
+    for (const [kind, declarations] of Object.entries(provides)) {
+        if (!Object.hasOwn(DECLARATION_FIELDS, kind))
+            throw new Error(`provides: "${kind}" is not supported`);
+        const fields = DECLARATION_FIELDS[kind];
+        const at = `provides.${kind}`;
+        if (!isRecord(declarations))
+            throw new Error(`${at}: must be an object`);
+        const entries = Object.entries(declarations);
+        if (entries.length > PEER_LIMITS.declarations)
+            throw new Error(`${at}: at most ${PEER_LIMITS.declarations}`);
+        for (const [name, declaration] of entries) {
+            if (!PEER_NAME.test(name))
+                throw new Error(`${at}: "${name}" must be camelCase (letters and digits, up to 48)`);
+            const path = `${at}.${name}`;
+            if (!isRecord(declaration))
+                throw new Error(`${path}: must be an object`);
+            for (const field of Object.keys(declaration))
+                if (!fields.includes(field))
+                    throw new Error(`${path}: "${field}" is not supported`);
+            if (typeof declaration.title !== "string" || !declaration.title.trim())
+                throw new Error(`${path}: title is required`);
+            if (declaration.description !== undefined && typeof declaration.description !== "string")
+                throw new Error(`${path}: description must be text`);
+            if (kind === "commands") {
+                if (declaration.input !== undefined) {
+                    validateSchema(declaration.input, `${path}.input`);
+                    if (declaration.input.type !== "object")
+                        throw new Error(`${path}.input: must be an object schema (named fields)`);
+                }
+                if (declaration.output !== undefined)
+                    validateSchema(declaration.output, `${path}.output`);
+            }
+            else if (kind === "events") {
+                if (declaration.payload !== undefined)
+                    validateSchema(declaration.payload, `${path}.payload`);
+            }
+            else
+                validateSchema(declaration.schema, `${path}.schema`);
+        }
+    }
+}
+function validateUses(uses, id) {
+    if (!isRecord(uses))
+        throw new Error("uses: must be an object of plugin ids and version ranges");
+    const entries = Object.entries(uses);
+    if (entries.length > PEER_LIMITS.uses)
+        throw new Error(`uses: at most ${PEER_LIMITS.uses} plugins`);
+    for (const [plugin, range] of entries) {
+        if (!PLUGIN_ID.test(plugin))
+            throw new Error(`uses: "${plugin}" is not a plugin id`);
+        if (plugin === id)
+            throw new Error("uses: a plugin can always reach itself; don't list it");
+        try {
+            validateRange(range);
+        }
+        catch (error) {
+            throw new Error(`uses.${plugin}: ${error.message}`);
+        }
+    }
 }
 function validateConfigurationItem(value, names) {
     const item = value;

package/dist/internal/peers.js

@@ -0,0 +1,55 @@
+import { schemaError } from "./schema.js";
+export const PEER_NAME = /^[a-z][A-Za-z0-9]{0,47}$/;
+export const PEER_LIMITS = {
+    declarations: 64,
+    uses: 32,
+    valueBytes: 64 * 1024,
+    stateBytes: 256 * 1024,
+    depth: 8,
+};
+export const COMMAND_TIMEOUT = { defaultMs: 10_000, maxMs: 30_000, minimumMs: 100 };
+export const commandBudgetMs = (timeoutMs) => Math.min(timeoutMs ?? COMMAND_TIMEOUT.defaultMs, COMMAND_TIMEOUT.maxMs);
+export function commandArgumentsProblem(command, input, options) {
+    if (typeof command !== "string" || !command)
+        return "Command name must be a non-empty string";
+    if (input !== undefined && (typeof input !== "object" || input === null || Array.isArray(input)))
+        return "Command input must be an object of named fields";
+    const timeoutMs = options?.timeoutMs;
+    if (timeoutMs !== undefined && (typeof timeoutMs !== "number" || !(timeoutMs > 0)))
+        return "timeoutMs must be a positive number of milliseconds";
+    return null;
+}
+export const PLUGIN_ERROR_CODES = [
+    "unsupported",
+    "invalid",
+    "not-found",
+    "unavailable",
+    "stopped",
+    "failed",
+    "not-installed",
+    "disabled",
+    "incompatible",
+    "loop",
+    "timeout",
+];
+export function checkedValue(schema, value, path) {
+    let json;
+    try {
+        json = JSON.stringify(value);
+    }
+    catch {
+        return { ok: false, problem: `${path} isn't JSON` };
+    }
+    if (json === undefined) {
+        const problem = schema ? schemaError(schema, undefined, path) : null;
+        return problem ? { ok: false, problem } : { ok: true, value: undefined, size: 0 };
+    }
+    if (!schema)
+        return { ok: false, problem: `${path}: none is declared` };
+    if (json.length > PEER_LIMITS.valueBytes)
+        return { ok: false, problem: `${path} is over ${PEER_LIMITS.valueBytes / 1024} KiB` };
+    const plain = JSON.parse(json);
+    const problem = schemaError(schema, plain, path);
+    return problem ? { ok: false, problem } : { ok: true, value: plain, size: json.length };
+}
+export const samePluginStatus = (a, b) => a.state === b.state && a.version === b.version && a.reason === b.reason;

package/dist/internal/schema.js

@@ -0,0 +1,156 @@
+export const SCHEMA_LIMITS = { depth: 6, nodes: 256 };
+const TYPES = ["string", "number", "integer", "boolean", "null", "object", "array"];
+const KEYWORDS = new Set([
+    "type",
+    "enum",
+    "properties",
+    "required",
+    "additionalProperties",
+    "items",
+    "minimum",
+    "maximum",
+    "title",
+    "description",
+    "default",
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const typesOf = (schema) => typeof schema.type === "string" ? [schema.type] : schema.type;
+export function validateSchema(schema, path) {
+    let nodes = 0;
+    const visit = (node, at, depth) => {
+        if (depth > SCHEMA_LIMITS.depth)
+            throw new Error(`${path}: nested more than ${SCHEMA_LIMITS.depth} levels`);
+        if (++nodes > SCHEMA_LIMITS.nodes)
+            throw new Error(`${path}: more than ${SCHEMA_LIMITS.nodes} schemas`);
+        if (!isRecord(node))
+            throw new Error(`${at}: type must be one of ${TYPES.join(", ")}`);
+        for (const key of Object.keys(node))
+            if (!KEYWORDS.has(key))
+                throw new Error(`${at}: "${key}" is not supported`);
+        const types = typeof node.type === "string" ? [node.type] : node.type;
+        if (!Array.isArray(types) ||
+            types.length === 0 ||
+            types.some((type) => !TYPES.includes(type)) ||
+            new Set(types).size !== types.length)
+            throw new Error(`${at}: type must be one of ${TYPES.join(", ")}, or a list of them`);
+        const schema = node;
+        const has = (type) => types.includes(type);
+        if (schema.title !== undefined && typeof schema.title !== "string")
+            throw new Error(`${at}: title must be text`);
+        if (schema.description !== undefined && typeof schema.description !== "string")
+            throw new Error(`${at}: description must be text`);
+        if (schema.minimum !== undefined || schema.maximum !== undefined) {
+            if (!has("number") && !has("integer"))
+                throw new Error(`${at}: minimum and maximum need type number or integer`);
+            for (const bound of [schema.minimum, schema.maximum])
+                if (bound !== undefined && (typeof bound !== "number" || !Number.isFinite(bound)))
+                    throw new Error(`${at}: minimum and maximum must be numbers`);
+            if (schema.minimum !== undefined && schema.maximum !== undefined && schema.minimum > schema.maximum)
+                throw new Error(`${at}: minimum exceeds maximum`);
+        }
+        if (schema.properties !== undefined || schema.required !== undefined || schema.additionalProperties !== undefined) {
+            if (!has("object"))
+                throw new Error(`${at}: properties need type object`);
+        }
+        if (has("object")) {
+            if (schema.properties !== undefined && !isRecord(schema.properties))
+                throw new Error(`${at}: properties must be an object`);
+            if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== "boolean")
+                throw new Error(`${at}: additionalProperties must be true or false`);
+            for (const [name, property] of Object.entries(schema.properties ?? {}))
+                visit(property, `${at}.properties.${name}`, depth + 1);
+            if (schema.required !== undefined) {
+                if (!Array.isArray(schema.required))
+                    throw new Error(`${at}: required must be a list of property names`);
+                for (const name of schema.required)
+                    if (typeof name !== "string" || !Object.hasOwn(schema.properties ?? {}, name))
+                        throw new Error(`${at}: required "${String(name)}" is not in properties`);
+            }
+        }
+        if (schema.items !== undefined && !has("array"))
+            throw new Error(`${at}: items need type array`);
+        if (has("array")) {
+            if (schema.items === undefined)
+                throw new Error(`${at}: an array needs items`);
+            visit(schema.items, `${at}.items`, depth + 1);
+        }
+        if (schema.enum !== undefined) {
+            if (!Array.isArray(schema.enum) || schema.enum.length === 0)
+                throw new Error(`${at}: enum must be a list of values`);
+            for (const [index, value] of schema.enum.entries()) {
+                const scalar = value === null || ["string", "number", "boolean"].includes(typeof value);
+                if (!scalar || valueError({ ...schema, enum: undefined }, value, `${at}.enum[${index}]`))
+                    throw new Error(`${at}.enum[${index}]: must be a ${types.join(" or ")} value`);
+            }
+        }
+        if (schema.default !== undefined) {
+            const error = valueError(schema, schema.default, `${at}.default`);
+            if (error)
+                throw new Error(error);
+        }
+    };
+    visit(schema, path, 1);
+}
+export function schemaError(schema, value, path) {
+    return valueError(schema, value, path);
+}
+function valueError(schema, value, path) {
+    const types = typesOf(schema);
+    const matches = (type) => {
+        switch (type) {
+            case "null":
+                return value === null;
+            case "boolean":
+                return typeof value === "boolean";
+            case "string":
+                return typeof value === "string";
+            case "number":
+                return typeof value === "number" && Number.isFinite(value);
+            case "integer":
+                return typeof value === "number" && Number.isInteger(value);
+            case "array":
+                return Array.isArray(value);
+            case "object":
+                return isRecord(value) && Object.getPrototypeOf(value) === Object.prototype;
+        }
+    };
+    const type = types.find(matches);
+    if (!type)
+        return `${path}: expected ${types.join(" or ")}`;
+    if (schema.enum && !schema.enum.includes(value))
+        return `${path}: must be one of ${schema.enum.map((option) => JSON.stringify(option)).join(", ")}`;
+    if (typeof value === "number") {
+        if (schema.minimum !== undefined && value < schema.minimum)
+            return `${path}: below the minimum ${schema.minimum}`;
+        if (schema.maximum !== undefined && value > schema.maximum)
+            return `${path}: above the maximum ${schema.maximum}`;
+    }
+    if (type === "array" && schema.items) {
+        for (const [index, item] of value.entries()) {
+            const error = valueError(schema.items, item, `${path}[${index}]`);
+            if (error)
+                return error;
+        }
+    }
+    if (type === "object") {
+        const object = value;
+        const properties = schema.properties ?? {};
+        for (const name of schema.required ?? [])
+            if (object[name] === undefined)
+                return `${path}: missing "${name}"`;
+        for (const [name, property] of Object.entries(object)) {
+            if (property === undefined)
+                continue;
+            const declared = properties[name];
+            if (!declared) {
+                if (schema.additionalProperties)
+                    continue;
+                return `${path}: unexpected "${name}"`;
+            }
+            const error = valueError(declared, property, `${path}.${name}`);
+            if (error)
+                return error;
+        }
+    }
+    return null;
+}

package/dist/internal/semver.js

@@ -0,0 +1,47 @@
+const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const isStableVersion = (value) => typeof value === "string" &&
+    STABLE_VERSION.test(value) &&
+    (value.split("+")[0] ?? "").split(".").every((part) => Number.isSafeInteger(Number(part)));
+const parts = (version) => {
+    const [major = 0, minor = 0, patch = 0] = (version.split("+")[0] ?? "").split(".").map(Number);
+    return [major, minor, patch];
+};
+export function compareVersions(left, right) {
+    if (!isStableVersion(left) || !isStableVersion(right))
+        throw new Error("Expected a stable semantic version");
+    const a = parts(left);
+    const b = parts(right);
+    for (let i = 0; i < 3; i++)
+        if (a[i] !== b[i])
+            return (a[i] ?? 0) > (b[i] ?? 0) ? 1 : -1;
+    return 0;
+}
+const RANGE = /^(\^|~|>=)?(.+)$/;
+export function validateRange(range) {
+    if (range === "*")
+        return;
+    const match = typeof range === "string" ? RANGE.exec(range) : null;
+    if (!match?.[2] || !isStableVersion(match[2]) || match[2].includes("+"))
+        throw new Error(`Unsupported version range "${String(range)}": use 1.2.3, ^1.2.3, ~1.2.3, >=1.2.3 or *`);
+}
+export function satisfiesRange(version, range) {
+    validateRange(range);
+    if (range === "*")
+        return true;
+    const [, operator = "", base = ""] = RANGE.exec(range) ?? [];
+    if (compareVersions(version, base) < 0)
+        return false;
+    if (operator === "")
+        return compareVersions(version, base) === 0;
+    if (operator === ">=")
+        return true;
+    const [major, minor, patch] = parts(base);
+    const [vMajor, vMinor, vPatch] = parts(version);
+    if (operator === "~")
+        return vMajor === major && vMinor === minor;
+    if (major > 0)
+        return vMajor === major;
+    if (minor > 0)
+        return vMajor === 0 && vMinor === minor;
+    return vMajor === 0 && vMinor === 0 && vPatch === patch;
+}

package/dist/main.d.ts

@@ -1,4 +1,4 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PeerStateApi, PluginConfig, PluginInfo, PluginPeer, PluginsApi, Session, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export type SessionEndReason = "completed" | "discarded";
 export interface MainSessionsApi extends SessionsApi {
     /**
@@ -51,6 +51,94 @@ export interface LogApi {
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
 }
+/** Who ran a command: another plugin's main code (by manifest id), a plugin UI, or an integration such as Home Assistant. */
+export type CommandCaller = {
+    readonly kind: "plugin";
+    readonly plugin: string;
+} | {
+    readonly kind: "ui";
+    readonly plugin: string;
+} | {
+    readonly kind: "integration";
+};
+/** The commands this plugin provides. `dbplugin prepare` fills this in from manifest.json `provides` (.drift-beacon/config.d.ts). */
+export interface PluginCommands {
+}
+/** The events this plugin emits. `dbplugin prepare` fills this in from manifest.json `provides`. */
+export interface PluginEvents {
+}
+/** The state this plugin publishes. `dbplugin prepare` fills this in from manifest.json `provides`. */
+export interface PluginState {
+}
+/** A declared map, or any name when nothing is declared (a plugin without generated types). */
+type Declared<T, Fallback> = keyof T extends never ? {
+    readonly [name: string]: Fallback;
+} : T;
+type Commands = Declared<PluginCommands, {
+    readonly input: Readonly<Record<string, unknown>>;
+    readonly output: unknown;
+}>;
+type Events = Declared<PluginEvents, unknown>;
+type States = Declared<PluginState, unknown>;
+type CommandName = keyof Commands & string;
+type EventName = keyof Events & string;
+type StateKey = keyof States & string;
+/** The chain a call belongs to: commands, events and state changes a handler or listener causes continue it. */
+export interface ChainInfo {
+    readonly chainId: string;
+    /**
+     * 1 for anything started outside a handler or listener; one more per step. Past 8, commands fail (`loop`),
+     * events are dropped and state changes run no callbacks. 0 for changes Drift Beacon makes itself (a plugin
+     * stopping or being replaced).
+     */
+    readonly depth: number;
+}
+export interface CommandMeta extends ChainInfo {
+    readonly caller: CommandCaller;
+    /** When the caller stops waiting (epoch milliseconds). */
+    readonly deadline: number;
+    /** Aborts at the deadline: pass it to `fetch` and the like. */
+    readonly signal: AbortSignal;
+}
+/** Handles a command: `input` has the declared fields (`{}` when it declares none); the result is the command's output. */
+export type CommandHandler<K extends CommandName = CommandName> = (input: Commands[K]["input"], meta: CommandMeta) => undefined extends Commands[K]["output"] ? unknown : Commands[K]["output"] | Promise<Commands[K]["output"]>;
+export interface CommandsApi {
+    /** Handle a command declared in manifest.json `provides.commands`. One handler per command; throws `invalid` otherwise. */
+    handle<K extends CommandName>(name: K, handler: CommandHandler<K>): Unsubscribe;
+}
+export interface EventsApi {
+    /**
+     * Send a declared event (manifest.json `provides.events`) to the plugins that use this one, and to this plugin
+     * itself. Throws `invalid` for an undeclared event or a payload that doesn't match its schema (or is over 64 KiB).
+     */
+    emit<K extends EventName>(name: K, ...payload: undefined extends Events[K] ? [payload?: Events[K]] : [payload: Events[K]]): void;
+}
+/** The state this plugin publishes to the plugins that use it (manifest.json `provides.state`). Kept in memory while it runs. */
+export interface StateApi {
+    get<K extends StateKey>(key: K): States[K] | undefined;
+    keys(): readonly StateKey[];
+    /**
+     * Publish a value (`undefined` removes it). Throws `invalid` for an undeclared key, a value that doesn't match
+     * its schema, over 64 KiB, or over 256 KiB of state in all.
+     */
+    set<K extends StateKey>(key: K, value: States[K] | undefined): void;
+}
+/** Another plugin's state, with the chain of the change that caused each callback. */
+export interface MainPeerStateApi extends PeerStateApi {
+    onChange(callback: (key: string, value: unknown, meta: ChainInfo) => void | Promise<void>): Unsubscribe;
+}
+export interface MainPluginPeer extends PluginPeer {
+    readonly state: MainPeerStateApi;
+    /**
+     * Called for each of its events with this name. Commands, events and state changes the callback causes continue
+     * its chain. A throw, or a rejection of the promise it returns, stops the instance.
+     */
+    onEvent(name: string, callback: (payload: unknown, meta: ChainInfo) => void | Promise<void>): Unsubscribe;
+}
+export interface MainPluginsApi extends PluginsApi {
+    get(id: string): MainPluginPeer;
+    readonly self: MainPluginPeer;
+}
 /** Everything a plugin's main code can use. One `ctx` per instance: a plugin for one user in one workspace. */
 export interface MainContext {
     readonly plugin: PluginInfo;
@@ -66,6 +154,14 @@ export interface MainContext {
     readonly storage: StorageApi;
     readonly mqtt: MqttApi;
     readonly routes: RoutesApi;
+    /** The commands this plugin provides to other plugins, its UI and integrations. */
+    readonly commands: CommandsApi;
+    /** The events this plugin emits to the plugins that use it. */
+    readonly events: EventsApi;
+    /** The state this plugin publishes to the plugins that use it. */
+    readonly state: StateApi;
+    /** The plugins this one uses, and itself. */
+    readonly plugins: MainPluginsApi;
     readonly log: LogApi;
     /**
      * Run when the instance stops: disabled, reconfigured, updated or shut down. `ctx` still works
@@ -89,4 +185,5 @@ export interface PluginDefinition {
  * ```
  */
 export declare function definePlugin(definition: PluginDefinition): PluginDefinition;
+export {};
 //# sourceMappingURL=main.d.ts.map

package/dist/pack.js

@@ -90,15 +90,14 @@ export async function pack(root, options = {}) {
         const typescript = require.resolve("typescript/package.json");
         const { bin } = JSON.parse(await readFile(typescript, "utf8"));
         const tsc = path.join(path.dirname(typescript), bin.tsc);
-        for (const project of ["tsconfig.main.json", "tsconfig.ui.json"]) {
-            const result = spawnSync(process.execPath, [tsc, "-p", path.join(".drift-beacon", project)], {
-                cwd: pkg,
-                stdio: ["ignore", 2, 2],
-            });
+        for (const part of ["main", "ui"]) {
+            const authored = `${part}/tsconfig.json`;
+            const project = existsSync(path.join(pkg, authored)) ? authored : `.drift-beacon/tsconfig.${part}.json`;
+            const result = spawnSync(process.execPath, [tsc, "-p", project], { cwd: pkg, stdio: ["ignore", 2, 2] });
             if (result.error)
                 throw result.error;
             if (result.status !== 0)
-                throw new Error(`Type errors (.drift-beacon/${project}); nothing was packed`);
+                throw new Error(`Type errors (${project}); nothing was packed`);
         }
         temp = await mkdtemp(path.join(tmpdir(), "dbplugin-pack-"));
         const vite = await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve("vite")).href));

package/dist/prepare.js

@@ -46,7 +46,7 @@ export function prepare(root, { strict }) {
     const out = path.join(root, ".drift-beacon");
     mkdirSync(out, { recursive: true });
     writeIfChanged(path.join(out, ".gitignore"), "*\n");
-    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest.configuration));
+    writeIfChanged(path.join(out, "config.d.ts"), configTypes(manifest));
     writeIfChanged(path.join(out, "tsconfig.main.json"), `${JSON.stringify(TSCONFIG_MAIN, null, 2)}\n`);
     writeIfChanged(path.join(out, "tsconfig.ui.json"), `${JSON.stringify(TSCONFIG_UI, null, 2)}\n`);
     return loaded;
@@ -74,23 +74,68 @@ export function loadManifest(root) {
         throw new Error(`${file}: ${compatibility.message}`);
     return { manifest, bytes };
 }
-function configTypes(configuration) {
+function configTypes(manifest) {
     const lines = [
         "// Generated by dbplugin prepare from manifest.json. Do not edit.",
         'import type {} from "@drift-beacon/plugin";',
         'declare module "@drift-beacon/plugin" {',
         "  interface PluginConfig {",
     ];
-    for (const item of configuration) {
-        const doc = [item.title, item.description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+    const member = (title, description, name, type) => {
+        const doc = docComment(title, description);
         if (doc)
-            lines.push(`    /** ${doc} */`);
+            lines.push(`    ${doc}`);
+        lines.push(`    ${name}: ${type};`);
+    };
+    for (const item of manifest.configuration) {
         const optional = item.required === true || item.default !== undefined ? "" : "?";
-        lines.push(`    ${JSON.stringify(item.name)}${optional}: ${valueType(item)};`);
+        member(item.title, item.description, `${JSON.stringify(item.name)}${optional}`, valueType(item));
     }
-    lines.push("  }", "}", "");
+    lines.push("  }");
+    const { commands = {}, events = {}, state = {} } = manifest.provides ?? {};
+    const block = (name, declarations, type) => {
+        if (!manifest.provides)
+            return;
+        lines.push(`  interface ${name} {`);
+        if (Object.keys(declarations).length === 0)
+            lines.push("    readonly [name: string]: never;");
+        for (const [key, declaration] of Object.entries(declarations))
+            member(declaration.title, declaration.description, JSON.stringify(key), type(declaration));
+        lines.push("  }");
+    };
+    block("PluginCommands", commands, ({ input, output }) => {
+        const inputType = input ? tsType(input) : NO_PROPERTIES;
+        return `{ readonly input: ${inputType}; readonly output: ${output ? tsType(output) : "undefined"} }`;
+    });
+    block("PluginEvents", events, ({ payload }) => (payload ? tsType(payload) : "undefined"));
+    block("PluginState", state, ({ schema }) => tsType(schema));
+    lines.push("}", "");
     return lines.join("\n");
 }
+const docComment = (title, description) => {
+    const doc = [title, description].filter(Boolean).join(": ").replaceAll("*/", "*\\/");
+    return doc ? `/** ${doc} */` : "";
+};
+const NO_PROPERTIES = "{ readonly [key: string]: never }";
+const SCALAR_TYPES = { string: "string", number: "number", integer: "number", boolean: "boolean", null: "null" };
+function tsType(schema) {
+    if (schema.enum)
+        return unique(schema.enum.map((value) => JSON.stringify(value)));
+    const types = typeof schema.type === "string" ? [schema.type] : schema.type;
+    return unique(types.map((type) => type === "array"
+        ? `readonly (${schema.items ? tsType(schema.items) : "unknown"})[]`
+        : type === "object"
+            ? objectType(schema)
+            : SCALAR_TYPES[type]));
+}
+function objectType(schema) {
+    const required = new Set(schema.required ?? []);
+    const members = Object.entries(schema.properties ?? {}).map(([name, property]) => `readonly ${JSON.stringify(name)}${required.has(name) ? "" : "?"}: ${tsType(property)}`);
+    if (schema.additionalProperties === true)
+        members.push("readonly [key: string]: unknown");
+    return members.length === 0 ? NO_PROPERTIES : `{ ${members.join("; ")} }`;
+}
+const unique = (types) => [...new Set(types)].join(" | ");
 const valueType = (item) => item.type !== "dropdown"
     ? item.type
     : item.data.length === 0

package/dist/types.d.ts

@@ -182,12 +182,67 @@ export interface SessionsApi {
 export interface StorageApi {
     get<T = unknown>(key: string): T | undefined;
     keys(): readonly string[];
-    /** Applies locally at once and resolves when the server has stored it. */
+    /**
+     * Applies locally at once and resolves when Drift Beacon has accepted the write. `undefined` removes the key;
+     * a value that isn't JSON-compatible rejects with `invalid`.
+     */
     set(key: string, value: unknown): Promise<void>;
+    /** Applies locally at once and resolves when Drift Beacon has accepted the removal. */
     remove(key: string): Promise<void>;
     /** Called for changes made anywhere else: main code, a UI or another device. */
     onChange(callback: (key: string, value: unknown) => void): Unsubscribe;
 }
-/** Error codes on rejected operations (`error.code`). */
-export type PluginErrorCode = "unsupported" | "invalid" | "not-found" | "unavailable" | "stopped" | "failed";
+/**
+ * Error codes on rejected operations (`error.code`). For a command to another plugin: `unavailable`
+ * means it didn't run (the plugin isn't running here); `timeout` and `stopped` mean it may have run.
+ */
+export type PluginErrorCode = "unsupported" | "invalid" | "not-found" | "unavailable" | "stopped" | "failed" | "not-installed" | "disabled" | "incompatible" | "loop" | "timeout";
+export interface CommandOptions {
+    /** How long to wait, in milliseconds (default 10 s, at most 30 s). Inside a command, at most what its caller has left. */
+    readonly timeoutMs?: number;
+}
+export type PluginStatusState = "running" | "starting" | "unavailable" | "disabled" | "incompatible" | "not-installed";
+/** Whether another plugin can run for this user in this workspace now. */
+export interface PluginStatus {
+    readonly state: PluginStatusState;
+    /** The version it resolved to, when one did. */
+    readonly version?: string;
+    /** Why it isn't running, when known. */
+    readonly reason?: string;
+}
+/** Another plugin's published state (or this plugin's own, as others see it: after a round trip). Values are read-only. */
+export interface PeerStateApi {
+    get<T = unknown>(key: string): T | undefined;
+    keys(): readonly string[];
+    /** A key changed, or was removed (`undefined`). */
+    onChange(callback: (key: string, value: unknown) => void): Unsubscribe;
+}
+/** Another plugin this one uses (listed in manifest.json `uses`), or this plugin itself. */
+export interface PluginPeer {
+    /** Its manifest id. */
+    readonly id: string;
+    /**
+     * The same object until it changes. In main code, updated at once when the plugin starts, finishes starting or
+     * stops, and otherwise within 250 ms; in a UI, within about 250 ms.
+     */
+    readonly status: PluginStatus;
+    /** Called when its `state`, `version` or `reason` changes. */
+    onStatusChange(callback: (status: PluginStatus) => void): Unsubscribe;
+    /**
+     * Run one of its commands (manifest.json `provides.commands`) as this user in this workspace and wait for
+     * the result. Fails fast with `not-installed`, `disabled`, `incompatible` or `unavailable` when it can't run;
+     * `timeout` means it may have run. In main code, the state it published reaches this plugin before this resolves;
+     * in a UI, it (like storage and workspace data the command changed) can arrive just after.
+     */
+    command<T = unknown>(name: string, input?: Readonly<Record<string, unknown>>, options?: CommandOptions): Promise<T>;
+    /** The state it publishes (manifest.json `provides.state`). */
+    readonly state: PeerStateApi;
+}
+/** The plugins this one uses. */
+export interface PluginsApi {
+    /** A plugin listed in manifest.json `uses`, or this plugin's own manifest id. Anything else throws `invalid`. */
+    get(id: string): PluginPeer;
+    /** This plugin itself, as other plugins see it. */
+    readonly self: PluginPeer;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/ui.d.ts

@@ -1,9 +1,10 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
 export { PluginError } from "./errors.ts";
 export type * from "./types.ts";
 export { API_VERSION } from "./version.ts";
 /** Everything a plugin UI can use. */
 export interface UiContext {
+    /** The installed plugin; it can change while the UI is open, for example to a new version. */
     readonly plugin: PluginInfo;
     readonly user: UserInfo;
     readonly workspace: WorkspaceInfo;
@@ -12,9 +13,17 @@ export interface UiContext {
     readonly activities: ActivitiesApi;
     readonly categories: CategoriesApi;
     readonly sessions: SessionsApi;
-    /** Called after each update from the app (workspace data, config or storage) and after local storage writes. */
+    /**
+     * Called after each update from the app (workspace data, config, storage, or other plugins' status and state) and
+     * after local storage writes.
+     */
     onDataChange(callback: () => void): Unsubscribe;
     readonly storage: StorageApi;
+    /**
+     * Its own plugin and the plugins it uses: their status and published state (within about 250 ms of a change), and
+     * their commands. A command's effects on their state, storage or data can arrive just after it resolves.
+     */
+    readonly plugins: PluginsApi;
 }
 export interface ConnectOptions {
     /** How long to wait for the app to answer. Default 10 seconds. */

package/dist/ui.js

@@ -1,13 +1,30 @@
 import { PluginError } from "./errors.js";
 import { Collection } from "./internal/collection.js";
+import { deepFreeze } from "./internal/freeze.js";
 import { jsonEqual } from "./internal/json-equal.js";
 import { WorkspaceModels } from "./internal/models.js";
+import { commandArgumentsProblem, commandBudgetMs, samePluginStatus } from "./internal/peers.js";
 import { isUiMessage, UI_CHANNEL, } from "./internal/protocol.js";
 import { API_VERSION } from "./version.js";
 export { PluginError } from "./errors.js";
 export { API_VERSION } from "./version.js";
 const HELLO_INTERVAL_MS = 250;
 const REQUEST_TIMEOUT_MS = 10_000;
+const COMMAND_GRACE_MS = 2_000;
+const NO_PEERS = Object.freeze({
+    state: "unavailable",
+    reason: "This version of Drift Beacon doesn't share other plugins with plugin UIs",
+});
+const UNLISTED = Object.freeze({ state: "unavailable", reason: "No longer in manifest.json uses" });
+const PAGE = (() => {
+    const bytes = new Uint8Array(6);
+    if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function")
+        crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    return Array.from(bytes, (byte) => byte.toString(36).padStart(2, "0")).join("");
+})();
 let connection = null;
 export function connect(options = {}) {
     connection ??= open(options.timeoutMs ?? 10_000);
@@ -63,6 +80,7 @@ class UiClient {
     post;
     context;
     config;
+    plugin;
     rows = {
         activities: new Collection(),
         categories: new Collection(),
@@ -81,9 +99,19 @@ class UiClient {
     nextWrite = 0;
     pending = new Map();
     nextRequest = 0;
+    peersShared;
+    listed = new Set();
+    selfId;
+    peerViews = new Map();
+    peerObjects = new Map();
     constructor(welcome, post) {
         this.post = post;
         this.config = welcome.config;
+        this.plugin = welcome.plugin;
+        this.peersShared = welcome.peers !== undefined;
+        this.selfId = welcome.peers?.self ?? welcome.plugin.id;
+        if (welcome.peers)
+            this.applyPeers(welcome.peers);
         this.serverStorage = welcome.storage;
         this.storage = new Map(Object.entries(welcome.storage));
         this.models = new WorkspaceModels({
@@ -104,7 +132,9 @@ class UiClient {
             return () => listeners.delete(callback);
         };
         this.context = {
-            plugin: welcome.plugin,
+            get plugin() {
+                return self.plugin;
+            },
             user: welcome.user,
             workspace: welcome.workspace,
             get config() {
@@ -117,20 +147,136 @@ class UiClient {
             storage: {
                 get: (key) => this.storage.get(key),
                 keys: () => [...this.storage.keys()],
-                set: (key, value) => this.write(key, JSON.parse(JSON.stringify(value))),
+                set: (key, value) => {
+                    if (value === undefined)
+                        return this.write(key, undefined);
+                    let plain;
+                    try {
+                        plain = JSON.parse(JSON.stringify(value));
+                    }
+                    catch {
+                        return Promise.reject(new PluginError("invalid", `Storage value for "${key}" is not JSON-compatible`));
+                    }
+                    return this.write(key, plain);
+                },
                 remove: (key) => this.write(key, undefined),
                 onChange: (callback) => subscribe(this.storageListeners, callback),
             },
+            plugins: {
+                get: (id) => this.peer(id),
+                get self() {
+                    return self.peer(self.selfId);
+                },
+            },
         };
     }
+    peer(id) {
+        const problem = this.unreachable(id);
+        if (problem)
+            throw problem;
+        const existing = this.peerObjects.get(id);
+        if (existing)
+            return existing;
+        const view = this.viewOf(id);
+        const subscribe = (listeners, callback) => {
+            listeners.add(callback);
+            return () => listeners.delete(callback);
+        };
+        const peer = Object.freeze({
+            id,
+            get status() {
+                return view.status;
+            },
+            onStatusChange: (callback) => subscribe(view.statusListeners, callback),
+            command: (name, input, options) => this.command(id, name, input, options),
+            state: Object.freeze({
+                get: (key) => view.state.get(key),
+                keys: () => [...view.state.keys()],
+                onChange: (callback) => subscribe(view.stateListeners, callback),
+            }),
+        });
+        this.peerObjects.set(id, peer);
+        return peer;
+    }
+    unreachable(id) {
+        return typeof id !== "string" || (this.peersShared && !this.listed.has(id))
+            ? new PluginError("invalid", `List "${String(id)}" in manifest.json uses to reach it`)
+            : null;
+    }
+    viewOf(id) {
+        let view = this.peerViews.get(id);
+        if (!view) {
+            view = { status: NO_PEERS, state: new Map(), statusListeners: new Set(), stateListeners: new Set() };
+            this.peerViews.set(id, view);
+        }
+        return view;
+    }
+    applyPeers(peers) {
+        this.peersShared = true;
+        this.selfId = peers.self;
+        this.listed = new Set(Object.keys(peers.plugins));
+        const statusChanges = [];
+        const stateChanges = [];
+        const unlisted = [...this.peerViews.keys()]
+            .filter((id) => !this.listed.has(id))
+            .map((id) => [id, { status: UNLISTED, state: {} }]);
+        for (const [id, next] of [...Object.entries(peers.plugins), ...unlisted]) {
+            const view = this.viewOf(id);
+            if (!samePluginStatus(view.status, next.status)) {
+                const status = deepFreeze({ ...next.status });
+                view.status = status;
+                statusChanges.push(() => notify(view.statusListeners, (listener) => listener(status)));
+            }
+            const state = new Map(Object.entries(next.state).map(([key, value]) => [key, deepFreeze(value)]));
+            for (const key of new Set([...view.state.keys(), ...state.keys()])) {
+                if (view.state.has(key) === state.has(key) && jsonEqual(view.state.get(key), state.get(key)))
+                    continue;
+                const value = state.get(key);
+                stateChanges.push(() => notify(view.stateListeners, (listener) => listener(key, value)));
+            }
+            view.state = state;
+        }
+        for (const change of [...statusChanges, ...stateChanges])
+            change();
+    }
+    command(plugin, command, input, options) {
+        const unreachable = this.unreachable(plugin);
+        if (unreachable)
+            return Promise.reject(unreachable);
+        const problem = commandArgumentsProblem(command, input, options);
+        if (problem)
+            return Promise.reject(new PluginError("invalid", problem));
+        let plain;
+        try {
+            plain = input === undefined ? undefined : JSON.parse(JSON.stringify(input));
+        }
+        catch {
+            return Promise.reject(new PluginError("invalid", "Command input must be JSON-compatible"));
+        }
+        const timeoutMs = options?.timeoutMs;
+        return this.request({
+            method: "plugins.command",
+            params: {
+                plugin,
+                command,
+                ...(plain === undefined ? {} : { input: plain }),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+            },
+        }, {
+            ms: commandBudgetMs(timeoutMs) + COMMAND_GRACE_MS,
+            error: () => new PluginError("timeout", `${plugin} didn't answer "${command}" in time; it may have run`),
+        });
+    }
     receive(message) {
         if (message.type === "welcome") {
+            this.plugin = message.plugin;
             this.receive({
                 channel: message.channel,
                 type: "state",
                 config: message.config,
                 data: message.data,
                 storage: message.storage,
+                ...(message.peers ? { peers: message.peers } : {}),
             });
             return;
         }
@@ -156,6 +302,8 @@ class UiClient {
             this.writesSincePush.clear();
             this.reconcileStorage();
         }
+        if (message.peers)
+            this.applyPeers(message.peers);
         notify(this.dataListeners, (listener) => listener());
     }
     applyData(data) {
@@ -221,16 +369,19 @@ class UiClient {
                 notify(this.dataListeners, (listener) => listener());
         }
     }
-    request(request) {
-        const id = String(++this.nextRequest);
+    request(request, timeout = {
+        ms: REQUEST_TIMEOUT_MS,
+        error: () => new PluginError("unavailable", `${request.method} timed out`),
+    }) {
+        const id = `${PAGE}-${++this.nextRequest}`;
         return new Promise((resolve, reject) => {
             this.pending.set(id, { resolve, reject });
             this.post({ channel: UI_CHANNEL, type: "request", id, ...request });
             setTimeout(() => {
                 if (!this.pending.delete(id))
                     return;
-                reject(new PluginError("unavailable", `${request.method} timed out`));
-            }, REQUEST_TIMEOUT_MS);
+                reject(timeout.error());
+            }, timeout.ms);
         });
     }
 }

package/dist/version.d.ts

@@ -2,5 +2,5 @@
  * The plugin API version this SDK describes, `major.minor`. It matches the package version's
  * major and minor. Before 1.0 every minor version may break plugins.
  */
-export declare const API_VERSION = "0.1";
+export declare const API_VERSION = "0.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1 +1 @@
-export const API_VERSION = "0.1";
+export const API_VERSION = "0.2";

package/dist/vite.js

@@ -40,6 +40,8 @@ export function driftBeacon() {
             return { root: path.join(pkg, "ui"), base: "./", build: { outDir: path.join(dist, "ui"), emptyOutDir: true } };
         },
         configureServer(server) {
+            if (process.env.VITEST)
+                return;
             serveDev(server, devStates.get(pkg) ?? startDev(pkg, dist, manifest, manifestBytes, server.config.logger));
         },
         async writeBundle() {
@@ -90,6 +92,7 @@ function startDev(pkg, dist, manifest, bytes, logger) {
         manifest,
         manifestBytes: bytes,
         watcher: Promise.resolve(undefined),
+        idle: Promise.resolve(),
         buildId: hashDist(dist),
         uiUrl: null,
         socket: null,
@@ -110,8 +113,13 @@ async function watchMain(state) {
     const staging = path.join(state.pkg, ".drift-beacon/main-next");
     const options = { outDir: staging, minify: false, sourcemap: true, watch: {}, logLevel: "silent" };
     const watcher = (await vite.build(mainBuild(vite, state.pkg, options)));
+    let built = () => { };
     watcher.on("event", (event) => {
-        if (event.code === "BUNDLE_END") {
+        if (event.code === "START")
+            state.idle = new Promise((resolve) => (built = resolve));
+        else if (event.code === "END")
+            built();
+        else if (event.code === "BUNDLE_END") {
             try {
                 moveFiles(staging, path.join(state.dist, "main"));
                 const changed = writeDevMarker(state);
@@ -132,6 +140,7 @@ async function watchMain(state) {
             });
         }
     });
+    await new Promise((resolve) => watcher.on("event", () => resolve()));
     return watcher;
 }
 function serveDev(server, state) {
@@ -154,14 +163,13 @@ function serveDev(server, state) {
                 print(state.logger, { level: "warn", text: noServerHint(state) });
         }, HINT_DELAY_MS).unref();
     });
-    const close = server.close.bind(server);
+    const { watcher } = server;
+    const closeWatcher = watcher.close.bind(watcher);
     let open = true;
-    server.close = () => {
-        if (open) {
-            open = false;
-            release(state);
-        }
-        return close();
+    watcher.close = async () => {
+        const released = open ? release(state) : undefined;
+        open = false;
+        await Promise.all([closeWatcher(), released]);
     };
     server.ws.on("drift-beacon:hello", (data, client) => {
         if (data?.session !== state.session)
@@ -183,13 +191,15 @@ function serveDev(server, state) {
             print(state.logger, data);
     });
 }
-function release(state) {
+async function release(state) {
     if (--state.servers > 0)
         return;
     clearTimeout(state.hint);
     if (devStates.get(state.pkg) === state)
         devStates.delete(state.pkg);
-    void state.watcher.then((watcher) => watcher?.close());
+    const watcher = await state.watcher;
+    await state.idle;
+    await watcher?.close();
 }
 function updateManifest(state) {
     try {
@@ -290,8 +300,14 @@ function writeMarker(dist, { pluginId, session, uiUrl }) {
 function hashDist(dist) {
     if (!existsSync(path.join(dist, "main/index.js")))
         return null;
+    const ui = existsSync(path.join(dist, "ui"))
+        ? readdirSync(path.join(dist, "ui"), { recursive: true, withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => path.relative(dist, path.join(entry.parentPath, entry.name)).split(path.sep).join("/"))
+            .sort()
+        : [];
     const hash = createHash("sha256");
-    for (const name of ["manifest.json", "main/index.js", "main/index.js.map", "ui/index.html"]) {
+    for (const name of ["manifest.json", "main/index.js", "main/index.js.map", ...ui]) {
         const file = path.join(dist, name);
         if (existsSync(file))
             hash.update(`${name}\0`).update(readFileSync(file));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drift-beacon/plugin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The Drift Beacon plugin SDK: APIs for plugin main code and UIs, the driftBeacon() Vite plugin and the dbplugin CLI",
   "license": "MIT",
   "author": {