@drift-beacon/plugin 0.1.0 → 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/cli.js

@@ -1,11 +1,3 @@
-/**
- * `dbplugin` (Drift Beacon plugins), run through `bin/dbplugin.js`:
- *
- *   dbplugin prepare [root]              Generate .drift-beacon/ (config types and tsconfigs). Lenient: a manifest
- *                                   problem only warns, because this runs as the plugin's postinstall.
- *   dbplugin pack [root] [--out <dir>]   Typecheck, build fresh and write <out>/<id>.zip (default releases/).
- *                                   Prints only the result JSON on stdout.
- */
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { pack } from "./pack.js";

package/dist/dev.js

@@ -1,8 +1 @@
-/**
- * The `pnpm dev` handshake between `driftBeacon()` and the Drift Beacon server. The dev tool writes a
- * marker into the package's `dist/`; the server polls for it, connects to Vite's HMR socket and trusts
- * the socket only after a `welcome` whose `session` equals the marker's. Messages travel as Vite custom
- * events (`{ type: "custom", event, data }`). All wording is rendered on the server; the tool only prints.
- */
-/** File name of the marker in `dist/`. Written as tmp, then renamed, synchronously. Never packed. */
 export const DEV_MARKER = ".drift-beacon-dev.json";

package/dist/errors.js

@@ -1,4 +1,3 @@
-/** Rejection from a platform operation. Check `code` rather than `instanceof`, which differs between SDK copies. */
 export class PluginError extends Error {
     code;
     constructor(code, message) {

package/dist/index.js

@@ -1,8 +1,3 @@
-/**
- * Drift Beacon plugin SDK: the API for main code (runs on the server). Plugin UIs import from `@drift-beacon/plugin/ui`.
- *
- * At run time the plugin host supplies this module, so `driftBeacon()` keeps it external when building main.
- */
 export { PluginError } from "./errors.js";
 export { definePlugin } from "./main.js";
 export { API_VERSION } from "./version.js";

package/dist/internal/collection.js

@@ -1,16 +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;
-}
-/**
- * A collection of plain rows keyed by id, frozen as they arrive. `replace` applies a full set of rows, keeps the
- * object of every unchanged row (so identity only changes when data does) and reports the changes.
- */
 export class Collection {
     rows = new Map();
     cachedList = null;

package/dist/internal/compatibility.js

@@ -1,12 +1,6 @@
 import { API_VERSION } from "../version.js";
-/**
- * API versions this build of Drift Beacon runs: the newest minor of each supported major.
- * Before 1.0 only the current version is listed, because every 0.x minor may break plugins.
- * From 1.0, the previous major stays listed for at least six months after its successor ships.
- */
 export const SUPPORTED_API_VERSIONS = [API_VERSION];
 const API_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
-/** Parse a `major.minor` API version; null when malformed. */
 export function parseApiVersion(value) {
     if (typeof value !== "string")
         return null;
@@ -15,11 +9,6 @@ export function parseApiVersion(value) {
         return null;
     return { major: Number(match[1]), minor: Number(match[2]) };
 }
-/**
- * Whether a plugin built for `pluginVersion` runs on a build supporting `supported`.
- * Before 1.0 the minor must match exactly; from 1.0 the major must match and the plugin's
- * minor must not be newer than the host's.
- */
 export function checkApiCompatibility(pluginVersion, supported = SUPPORTED_API_VERSIONS) {
     const plugin = parseApiVersion(pluginVersion);
     if (!plugin) {

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/json-equal.js

@@ -1,4 +1,3 @@
-/** Structural equality for JSON-shaped values such as data rows and storage items. */
 export function jsonEqual(a, b) {
     if (a === b)
         return true;

package/dist/internal/manifest.js

@@ -1,9 +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)));
-/** Throws a readable error when `manifest` is not a valid plugin manifest. Shared by the server and the pack tool. */
+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");
@@ -13,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)) {
@@ -35,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/models.js

@@ -1,14 +1,3 @@
-/**
- * The models plugins see: `Activity`, `Category` and `Session` objects over the workspace rows.
- *
- * One `WorkspaceModels` per `ctx`. The plugin host builds it for main code; the UI client builds it
- * inside every UI bundle, so this file is part of the UI wire contract: change it only additively
- * within an API version.
- *
- * Every read goes to the latest snapshot in the collections, synchronously. Nothing is applied ahead
- * of a snapshot. Lists are computed once per snapshot, so they keep their identity until the data
- * changes.
- */
 import { PluginError } from "../errors.js";
 const ACTIVITY_FIELDS = [
     "id",
@@ -43,10 +32,6 @@ const SESSION_FIELDS = [
 ];
 const gone = (what) => Promise.reject(new PluginError("not-found", `${what} no longer exists`));
 const compareText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-/**
- * Give a model its data fields as enumerable getters, so spreading, `JSON.stringify` and
- * `postMessage` copy the current values, then freeze it.
- */
 function seal(model, fields, data) {
     for (const field of fields) {
         Object.defineProperty(model, field, { enumerable: true, get: () => data()[field] });
@@ -170,11 +155,9 @@ export class WorkspaceModels {
     #activities = new Map();
     #categories = new Map();
     #sessions = new Map();
-    /** The last row seen for each id, so a model whose row was removed keeps its values. */
     #lastActivity = new Map();
     #lastCategory = new Map();
     #lastSession = new Map();
-    /** Session rows with `Date` fields, one per row version. Built per `ctx`: a `Date` can't be frozen. */
     #sessionData = new WeakMap();
     #lists = new Map();
     #listsSnapshot = [];
@@ -183,7 +166,6 @@ export class WorkspaceModels {
         this.rows = options.rows;
         this.#actions = options.actions;
     }
-    /** The reads and actions for `ctx`. */
     apis() {
         return {
             activities: {
@@ -205,9 +187,6 @@ export class WorkspaceModels {
             },
         };
     }
-    // --------------------------------------------------------------------------
-    // Reads
-    // --------------------------------------------------------------------------
     activity(id) {
         return this.rows.activities.get(id) ? this.#activityModel(id) : undefined;
     }
@@ -217,7 +196,6 @@ export class WorkspaceModels {
     session(id) {
         return this.rows.sessions.get(id) ? this.#sessionModel(id) : undefined;
     }
-    /** In the app's order: by category (uncategorized last), then `sortOrder`, then name. */
     activities(filter = {}) {
         const { categoryId, trackingType, includeArchived = false } = filter;
         const key = {
@@ -241,13 +219,11 @@ export class WorkspaceModels {
                 .map((row) => this.#activityModel(row.id));
         });
     }
-    /** By `sortOrder`, then name. */
     categories() {
         return this.#list({ list: "categories" }, () => [...this.rows.categories.list()]
             .sort((a, b) => a.sortOrder - b.sortOrder || compareText(a.name, b.name) || compareText(a.id, b.id))
             .map((row) => this.#categoryModel(row.id)));
     }
-    /** Newest first. */
     sessions(filter = {}) {
         const { activityId, status, mine = false } = filter;
         return this.#list({ list: "sessions", activityId, status, mine }, () => this.rows.sessions
@@ -259,9 +235,6 @@ export class WorkspaceModels {
             .sort((a, b) => b.at - a.at || compareText(a.row.id, b.row.id))
             .map(({ row }) => this.#sessionModel(row.id)));
     }
-    // --------------------------------------------------------------------------
-    // Actions
-    // --------------------------------------------------------------------------
     async start(activityId) {
         return this.#result(await this.#actions.start(activityId));
     }
@@ -274,10 +247,6 @@ export class WorkspaceModels {
     async discard(sessionId) {
         await this.#actions.discard(sessionId);
     }
-    // --------------------------------------------------------------------------
-    // Deliveries
-    // --------------------------------------------------------------------------
-    /** Turn the row changes of a snapshot into model changes. Call it after the collections were replaced. */
     update(changes) {
         return {
             activities: changes.activities.map((change) => this.#change(change, this.#lastActivity, (id) => this.#activityModel(id), (row) => row)),
@@ -285,18 +254,11 @@ export class WorkspaceModels {
             sessions: changes.sessions.map((change) => this.#change(change, this.#lastSession, (id) => this.#sessionModel(id), (row) => this.#toSessionData(row))),
         };
     }
-    /**
-     * The model for a session the app sent outside a snapshot (a live event or an action result):
-     * the snapshot's model, or, when the row isn't in the snapshot, a removed model holding these values.
-     */
     sessionFrom(row) {
         if (!this.rows.sessions.get(row.id))
             this.#lastSession.set(row.id, row);
         return this.#sessionModel(row.id);
     }
-    // --------------------------------------------------------------------------
-    // Rows, for the models
-    // --------------------------------------------------------------------------
     activityRow(id) {
         return latest(this.rows.activities.get(id), this.#lastActivity, id);
     }
@@ -306,9 +268,6 @@ export class WorkspaceModels {
     sessionData(id) {
         return this.#toSessionData(latest(this.rows.sessions.get(id), this.#lastSession, id));
     }
-    // --------------------------------------------------------------------------
-    // Internals
-    // --------------------------------------------------------------------------
     #activityModel(id) {
         let model = this.#activities.get(id);
         if (!model) {
@@ -357,7 +316,6 @@ export class WorkspaceModels {
             throw new PluginError("failed", "Drift Beacon did not return the session");
         return this.sessionFrom(value);
     }
-    /** A list computed once per snapshot: the same frozen array until any collection changes. */
     #list(key, compute) {
         const snapshot = [this.rows.activities.list(), this.rows.categories.list(), this.rows.sessions.list()];
         if (snapshot.some((list, index) => list !== this.#listsSnapshot[index])) {
@@ -373,7 +331,6 @@ export class WorkspaceModels {
         return list;
     }
 }
-/** The row in the snapshot, remembered as the last one seen; otherwise the last one seen. */
 function latest(row, last, id) {
     if (row !== undefined) {
         if (last.get(id) !== row)

package/dist/internal/package-layout.js

@@ -1,8 +1,3 @@
-/**
- * The plugin package: `manifest.json`, `package.json`, `main/index.js` (plus chunks) and `ui/index.html`
- * (plus assets and the manifest icon). Shared by the pack tool and the server. Pure: the web app bundles
- * `/internal`, so no `node:` imports.
- */
 export const PACKAGE_LIMITS = {
     entries: 2000,
     fileBytes: 32 * 2 ** 20,
@@ -10,10 +5,8 @@ export const PACKAGE_LIMITS = {
     archiveBytes: 32 * 2 ** 20,
     manifestBytes: 256 * 2 ** 10,
 };
-/** The `package.json` every package gets: main is ESM. */
 export const PACKAGE_JSON = { type: "module", private: true };
 export const REQUIRED_FILES = ["main/index.js", "ui/index.html"];
-/** manifest.json, package.json, main/** and ui/** (directories: main, ui and below). `name` has no trailing slash. */
 export const isPackagePath = (name, directory) => name.startsWith("main/") ||
     name.startsWith("ui/") ||
     (directory ? name === "main" || name === "ui" : name === "manifest.json" || name === "package.json");

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/protocol.js

@@ -1,4 +1,3 @@
-/** Marks our messages so both sides ignore unrelated `postMessage` traffic (dev tools, HMR). */
 export const UI_CHANNEL = "drift-beacon-plugin";
 export function isUiMessage(value) {
     return (typeof value === "object" &&