@drift-beacon/plugin 0.2.0 → 0.2.3

package/README.md

@@ -201,9 +201,9 @@ Settings items have `name` (unique), `title`, `type` and optional `description`
 
 `main/src/index.ts` default-exports `definePlugin({ onStart(ctx) { … } })`. The server runs one **instance** for each user and workspace that enabled the plugin; each gets its own `ctx`.
 
-- **Start.** `onStart(ctx)` may be async and must finish within 15 seconds. If it throws, the instance doesn't start.
+- **Start.** `onStart(ctx)` may be async and must finish within 15 seconds. Callbacks and routes work as soon as they are registered. If it throws, the instance doesn't start.
 - **Register through `ctx`.** Callbacks, routes and MQTT subscriptions made through `ctx` are released when the instance stops. Keep per-instance state inside `onStart`, never at module scope: the module is shared by every instance.
-- **Stop.** `ctx.onStop(fn)` callbacks run newest first, 5 seconds in total. Afterwards every `ctx` call throws `PluginError` with code `stopped`.
+- **Stop.** `ctx.onStop(fn)` callbacks run newest first, 5 seconds in total, whatever stops the instance (a fault or server shutdown too, even when something else stops it meanwhile). Afterwards every `ctx` call throws `PluginError` with code `stopped`. A server that is killed rather than shut down cuts them short.
 - **Faults.** An uncaught error or unhandled rejection stops only that instance, which is retried after 5, 30 and 120 seconds.
 
 | `ctx` member | Main | UI | |
@@ -214,13 +214,15 @@ 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) |
+| `plugins` | ✓ | ✓ | The plugins it uses and itself: status, state, events and commands |
 | `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, storage, or other plugins' status and state).
+`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; not their events).
+
+The app runs a built UI in a sandboxed frame (`allow-scripts` only): it has no storage, cookies, popups or modal dialogs, and a `<form>` never submits. Handle Enter and your button's press yourself instead of relying on a form's `submit`.
 
 With React, re-render on every update:
 
@@ -256,6 +258,8 @@ Models keep their identity when their data changes: key `React.memo` and `useMem
 const activity = ctx.activities.get(id);
 activity?.category?.name;   // links
 activity?.isLive;           // the current user has a live session of it
+activity?.isPinned;         // the current user has it pinned
+activity?.goal;             // { type: "duration", seconds } or { type: "count", count }, or null
 await activity?.track();    // start a span / mark a point
 activity?.data;             // the plain row, a new frozen object whenever it changes
 
@@ -277,10 +281,22 @@ ctx.sessions.live({ mine: true });
 {activity.iconPath && <svg viewBox="0 0 24 24" fill="currentColor"><path d={activity.iconPath} /></svg>}
 ```
 
+- From 0.2.2, activities carry their goal, its period and their pins:
+  - `goal` is `{ type: "duration", seconds }` or `{ type: "count", count }`, or `null` when the activity has none. A point activity's goal always counts marks; a span activity's counts sessions or totals their duration, as the user chose.
+  - `period` is `"day"`, `"week"`, `"month"` or `"year"`: calendar periods from local midnight, weeks starting on Sunday. `null` means progress covers all history. Local means the browser's time zone in a UI, like the app's own progress, but the server's (its `TZ` environment variable) in main code: if the server runs in UTC and the user doesn't, main code's periods are off by the whole difference, all period long. Set `TZ` on the server to the household's zone.
+  - `pinnedBy` lists the users who have the activity pinned (each user pins at most one). Main code sees every user's pins, a UI only its own user's. `isPinned` is the current user's pin in both.
+  - Progress isn't included: add up `sessions()` in the current period. Drift Beacon counts every member's completed sessions from the period's start (a span counts on the day it started), plus the time so far of the current user's live session.
+  - A Drift Beacon older than 0.2.2 provides none of these, to main code as well as to UIs (main code uses the models of the Drift Beacon that runs it): `goal`, `period` and `pinnedBy` are `undefined`, which is why they are optional and how to tell (from 0.2.2, `pinnedBy` is always an array), and `isPinned` is `false` in a UI but `undefined` in main code. Test `isPinned` for truthiness.
+
+```ts
+// The activity to show: the user's live one, else the one they pinned.
+const shown = ctx.sessions.live({ mine: true })[0]?.activity ?? ctx.activities.list().find((a) => a.isPinned);
+```
+
 | Activity | |
 |---|---|
-| `id`, `name`, `description`, `trackingType`, `icon`, `iconPath`, `color`, `categoryId`, `archived`, `sortOrder`, `unit` | Fields (`color` is resolved from the category when needed) |
-| `isSpan`, `isPoint`, `isLive`, `category` | Derived values and links |
+| `id`, `name`, `description`, `trackingType`, `icon`, `iconPath`, `color`, `categoryId`, `archived`, `sortOrder`, `unit`, `goal`, `period`, `pinnedBy` | Fields (`color` is resolved from the category when needed) |
+| `isSpan`, `isPoint`, `isLive`, `isPinned`, `category` | Derived values and links |
 | `sessions(filter?)`, `live({ mine? })` | Its sessions |
 | `start()`, `mark()`, `track()`, `end()` | Actions (`end()` ends the current user's live session of it) |
 
@@ -301,7 +317,7 @@ await ctx.sessions.end(sessionId);      // or session.end(), activity.end()
 await ctx.sessions.discard(sessionId);  // or session.discard()
 ```
 
-Actions run as the current user and resolve once `ctx` shows their result. Starting a session ends the user's other live session, as in the app.
+Actions run as the current user and resolve once `ctx` shows their result. Starting a session ends the user's other live session, as in the app. An id that isn't a non-empty string rejects with `invalid`.
 
 | | Live session events | Data change events |
 |---|---|---|
@@ -314,7 +330,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: 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.
+Per plugin, user and workspace, shared by main code and the UI. Keys are non-empty strings and 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") ?? {};
@@ -327,7 +343,7 @@ 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.
+The app blocks opening a UI when required settings are missing or blank. This presence check does not validate every setting: if saved values fail schema validation, the UI receives defaults under the saved values while main does not run. Check values before relying on them.
 
 ## MQTT and HTTP routes
 
@@ -341,12 +357,12 @@ ctx.routes.post("webhook", async ({ body }) => ({ status: 202, body: { ok: true
 ctx.routes.get("status", () => ({ body: { live: ctx.sessions.live({ mine: true }).length } }));
 ```
 
-- 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.
+- MQTT uses the workspace's broker; `publish` rejects with `unavailable` without one or while it isn't connected, and with `invalid` for an empty topic or a payload that isn't a string (nothing is sent).
+- 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. While `onStart` runs, a route not registered yet answers 503 (retry after 5 s).
 
 ## 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.
+Main code provides commands; main code, UIs and Home Assistant 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
@@ -371,11 +387,25 @@ const result = await ctx.plugins.get("magic-cube").command("selectPreset", { pre
 - 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.
+- In Home Assistant, each command is an action, `drift_beacon.<manifest id>_<command in snake_case>` (`drift_beacon.magic_cube_select_preset`), on a workspace's device: its fields are your input's properties; if you declare `output`, a call on one workspace can ask for the response `{ output }`. It runs as that workspace's user with `meta.caller` `{ kind: "integration" }` and 10 s, and needs no `uses`. Renaming a command or input field breaks automations as it breaks other plugins.
+- `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 for you: keep a copy of the types you need, written from their manifest. `command<T>()` and `state.get<T>()` take the type, and an event's payload is `unknown` until you narrow it. Update the copy along with your `uses` range.
+
+```ts
+// cartridge-reader: what it uses from magic-cube ^1.1.0, kept by hand
+interface SelectPresetOutput {
+  activePresetId: string | null;
+}
+
+const cube = ctx.plugins.get("magic-cube");
+const { activePresetId } = await cube.command<SelectPresetOutput>("selectPreset", { preset: "Focus" });
+const preset = cube.state.get<string | null>("activePreset");
+cube.onEvent("faceChanged", (face) => showFace(face as number));
+```
 
 ## 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.
+Main code emits and publishes; main code and UIs receive them. 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
@@ -397,11 +427,13 @@ 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.
+- Events reach listeners registered by then (from `onStart` on; in a UI, right after `connect()`); earlier ones are missed. State is kept in memory while the provider runs, cleared when it stops, never persisted.
+- A plugin can emit 50 events a second on average, in bursts up to 100; Drift Beacon drops the rest, with a warning in your console at most every 10 s (each after the first says how many it dropped). For a value that changes faster, publish the latest as state (not limited) or send fewer, bigger events.
 - 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.
+- In a UI (from 0.2.1), events come with those updates, each after the state its plugin set before it. None are replayed (reconnects, reloads, more than about 100 between two updates), every open copy of the UI gets each one, and a command a UI listener runs starts a new chain: render in UI listeners, and react with commands in main code. On an older Drift Beacon they never arrive.
 
 ## Errors and limits
 
@@ -410,7 +442,7 @@ 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, an undeclared event, …) |
+| `invalid` | Bad arguments (an empty id or storage key, an MQTT payload that isn't a string, 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 |
@@ -429,7 +461,7 @@ Operations reject with `PluginError`. Check `error.code`, not `instanceof`:
 
 ## Developing against your server
 
-On a Drift Beacon server you run yourself, set `DEV_PLUGINS_PATH` to the folder that contains your plugin folders and start the server in development mode. It lists each plugin under **Plugins → Development**. Enable it in a workspace, then run `npm run dev` in the plugin folder: every save rebuilds main, the server restarts the plugin, and its status, logs and errors (with stack traces pointing at your source) print in your terminal. The UI updates in place.
+On a Drift Beacon server you run yourself, set `DEV_PLUGINS_PATH` to the folder that contains your plugin folders and start the server in development mode. It lists each plugin under **Plugins → Repositories → Local development**. Enable it in a workspace, then run `npm run dev` in the plugin folder: every save rebuilds main, the server restarts the plugin, and its status, logs and errors (with stack traces pointing at your source) print in your terminal. The UI updates in place.
 
 ## Releasing a plugin
 
@@ -439,14 +471,31 @@ Plugins are published on GitHub. In a public repository, each immediate child fo
 2. Run `npm run release` (or `npx dbplugin pack`), which writes `releases/<id>.zip`.
 3. Create a GitHub release tagged `<id>-<version>` (for example `hello-1.0.0`) and attach `<id>.zip`.
 
-Users add the repository URL in **Plugins → Store** and install from there. Don't commit `dist/` or `releases/`.
+Users add the repository URL in **Plugins → Repositories** and install from there. Don't commit `dist/` or `releases/`.
 
 ## 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.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.
+- Patch releases (`0.2.x`) fix bugs and may add to API 0.2. An addition that needs the app, such as UI events in 0.2.1 or activity goals and pins in 0.2.2, does nothing on an older Drift Beacon. Ignore fields and string values you don't recognise (such as a new `trackingType`).
 
 ## License
 
 MIT
+
+## Host theme (SDK 0.2.3)
+
+`connect()` installs the host's theme as `--db-*` CSS variables on `<html>` before resolving. It keeps them synchronized without reloading the UI. It also sets `data-color-mode`, `color-scheme`, and the `light`/`dark` class. Use semantic tokens instead of copying the app's palette or forcing a dark class.
+
+```css
+body { background: var(--db-background); color: var(--db-foreground); }
+.card { background: var(--db-surface); color: var(--db-surface-foreground); border: 1px solid var(--db-border); }
+```
+
+The tokens are `background`, `foreground`, `surface`, `surface-foreground`, `surface-raised`, `muted`, `border`, `accent`, `accent-foreground`, `danger`, `danger-foreground`, `success`, `success-foreground`, `warning`, `warning-foreground`, and `focus`, all prefixed with `--db-`. `background` is the containing surface; `surface` is a card; `surface-raised` is a more prominent surface. Values are complete CSS colors, not HSL channels. Activity and device colors remain domain data, separate from these UI colors.
+
+`ctx.theme: UiTheme` is an immutable snapshot (`mode: "light" | "dark"`, `colors: UiThemeColors` using camelCase token names). `ctx.onThemeChange(callback): Unsubscribe` runs after CSS is updated, only when the theme changes. Canvas/chart renderers can subscribe here; theme-only updates do not fire `onDataChange`. Convert CSS colors to sRGB if the rendering library does not accept modern CSS color syntax.
+
+Older hosts omit the theme. The SDK then supplies a stable dark fallback palette; an old-host reconnect restores that fallback. Missing theme fields in ordinary state updates leave the current theme unchanged. Invalid theme snapshots are ignored. Older UI bundles ignore the new fields and keep their existing appearance; rebuild and migrate their styles to adopt them.
+
+Render the main UI after `connect()` resolves. Give loading/error UI fallback colors, and handle a rejected connection. Framework adapters should map their library's colors to these tokens; the SDK does not require React or HeroUI.

package/dist/internal/actions.js

@@ -1 +1,23 @@
-export {};
+const nonEmpty = (value, what) => typeof value === "string" && value !== "" ? null : `${what} must be a non-empty string`;
+const ARGUMENTS = {
+    startSession: (action) => nonEmpty(action.activityId, "Activity id"),
+    markPoint: (action) => nonEmpty(action.activityId, "Activity id"),
+    endSession: (action) => nonEmpty(action.sessionId, "Session id"),
+    discardSession: (action) => nonEmpty(action.sessionId, "Session id"),
+    storageSet: (action) => nonEmpty(action.key, "Storage key"),
+    storageRemove: (action) => nonEmpty(action.key, "Storage key"),
+    mqttSubscribe: (action) => nonEmpty(action.topic, "MQTT topic"),
+    mqttUnsubscribe: (action) => nonEmpty(action.topic, "MQTT topic"),
+    mqttPublish: (action) => nonEmpty(action.topic, "MQTT topic") ??
+        (typeof action.payload === "string" ? null : "MQTT payload must be a string"),
+};
+export function checkedAction(value) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const action = value;
+    const name = action.name;
+    if (typeof name !== "string" || !Object.hasOwn(ARGUMENTS, name))
+        return null;
+    const problem = ARGUMENTS[name](action);
+    return problem === null ? { ok: true, action: action } : { ok: false, problem };
+}

package/dist/internal/models.js

@@ -11,6 +11,9 @@ const ACTIVITY_FIELDS = [
     "archived",
     "sortOrder",
     "unit",
+    "goal",
+    "period",
+    "pinnedBy",
 ];
 const CATEGORY_FIELDS = [
     "id",
@@ -61,6 +64,9 @@ class ActivityModel {
     get isLive() {
         return this.live({ mine: true }).length > 0;
     }
+    get isPinned() {
+        return this.data.pinnedBy?.includes(this.#models.userId) ?? false;
+    }
     get category() {
         const categoryId = this.data.categoryId;
         return categoryId === null ? undefined : this.#models.category(categoryId);

package/dist/internal/peers.js

@@ -6,9 +6,14 @@ export const PEER_LIMITS = {
     valueBytes: 64 * 1024,
     stateBytes: 256 * 1024,
     depth: 8,
+    eventsPerSecond: 50,
+    eventBurst: 100,
 };
 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 const eventNameProblem = (name) => typeof name === "string" && PEER_NAME.test(name)
+    ? null
+    : `Event names are camelCase letters and digits (got "${String(name)}")`;
 export function commandArgumentsProblem(command, input, options) {
     if (typeof command !== "string" || !command)
         return "Command name must be a non-empty string";

package/dist/internal/theme.js

@@ -0,0 +1,75 @@
+export const THEME_COLOR_KEYS = [
+    "background",
+    "foreground",
+    "surface",
+    "surfaceForeground",
+    "surfaceRaised",
+    "muted",
+    "border",
+    "accent",
+    "accentForeground",
+    "danger",
+    "dangerForeground",
+    "success",
+    "successForeground",
+    "warning",
+    "warningForeground",
+    "focus",
+];
+export function fallbackTheme(mode = "dark") {
+    const dark = mode === "dark";
+    return Object.freeze({
+        mode,
+        colors: Object.freeze({
+            background: dark ? "#09090b" : "#f8f8f8",
+            foreground: dark ? "#fafafa" : "#18181b",
+            surface: dark ? "#18181b" : "#ffffff",
+            surfaceForeground: dark ? "#fafafa" : "#18181b",
+            surfaceRaised: dark ? "#27272a" : "#f4f4f5",
+            muted: dark ? "#a1a1aa" : "#71717a",
+            border: dark ? "#3f3f46" : "#d4d4d8",
+            accent: "#2563eb",
+            accentForeground: "#ffffff",
+            danger: dark ? "#ef4444" : "#b91c1c",
+            dangerForeground: "#ffffff",
+            success: dark ? "#4ade80" : "#15803d",
+            successForeground: dark ? "#052e16" : "#ffffff",
+            warning: dark ? "#fbbf24" : "#a16207",
+            warningForeground: dark ? "#422006" : "#ffffff",
+            focus: "#3b82f6",
+        }),
+    });
+}
+export function readTheme(value) {
+    if (!value || typeof value !== "object")
+        return;
+    const { mode, colors } = value;
+    if ((mode !== "light" && mode !== "dark") || !colors || typeof colors !== "object")
+        return;
+    const result = {};
+    for (const key of THEME_COLOR_KEYS) {
+        const color = colors[key];
+        if (typeof color !== "string" ||
+            !color.trim() ||
+            color.length > 512 ||
+            /[;{}]/.test(color) ||
+            /(?:var|url)\s*\(/i.test(color))
+            return;
+        if (typeof CSS !== "undefined" && CSS.supports && !CSS.supports("color", color))
+            return;
+        result[key] = color;
+    }
+    return Object.freeze({ mode, colors: Object.freeze(result) });
+}
+export function applyTheme(theme) {
+    if (typeof document === "undefined")
+        return;
+    const root = document.documentElement;
+    for (const key of THEME_COLOR_KEYS) {
+        root.style.setProperty(`--db-${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`, theme.colors[key]);
+    }
+    root.dataset.colorMode = theme.mode;
+    root.style.colorScheme = theme.mode;
+    root.classList.toggle("dark", theme.mode === "dark");
+    root.classList.toggle("light", theme.mode === "light");
+}

package/dist/main.d.ts

@@ -19,9 +19,15 @@ export interface MqttMessage {
 export interface MqttApi {
     /** Subscribe to a topic filter. `+` matches one level and `#` the remaining levels. */
     subscribe(topic: string, callback: (message: MqttMessage) => void): Unsubscribe;
-    /** Rejects when no broker is configured or the broker refuses the message. */
+    /**
+     * Rejects with `invalid` when the topic is empty or the payload isn't a string (nothing is sent), and with
+     * `unavailable` when the workspace has no broker, the broker isn't connected, or it refuses the message.
+     */
     publish(topic: string, payload: string): Promise<void>;
-    /** `unavailable` when no broker is configured for the workspace. */
+    /**
+     * `unavailable` when the workspace has no broker: none is configured, or the server couldn't connect to it when
+     * it was saved or when the server started.
+     */
     readonly status: MqttStatus;
     onStatusChange(callback: (status: MqttStatus) => void): Unsubscribe;
 }

package/dist/types.d.ts

@@ -4,11 +4,25 @@
  * Workspace data comes as models: an `Activity`, `Category` or `Session` with its fields, links,
  * derived values and actions. Models read the latest snapshot the app sent, synchronously; there is
  * one model per row for the life of a `ctx`, and `model.data` is its plain, frozen row. Later API
- * versions may add fields and new values to string unions such as `trackingType`, so plugins must
- * ignore what they don't recognise.
+ * versions may add fields and new values to string unions such as `trackingType`, `goal.type` and
+ * `period`, so plugins must ignore what they don't recognise.
  */
 /** Stops a subscription. Subscriptions made through `ctx` also stop when the instance stops. */
 export type Unsubscribe = () => void;
+/** An activity's goal: a total duration (seconds) or a number of times, per period. */
+export type ActivityGoal = {
+    readonly type: "duration";
+    readonly seconds: number;
+} | {
+    readonly type: "count";
+    readonly count: number;
+};
+/**
+ * The calendar period a goal resets over, starting at local midnight (weeks start on Sunday). Local is the browser's
+ * time zone in a UI, like the app's own progress, but the server process's (its `TZ`) in main code, which can be hours
+ * off the user's for the whole period.
+ */
+export type GoalPeriod = "day" | "week" | "month" | "year";
 /** An activity's plain row: what `activity.data` returns. */
 export interface ActivityData {
     readonly id: string;
@@ -25,6 +39,24 @@ export interface ActivityData {
     /** Position within the activity's category. */
     readonly sortOrder: number;
     readonly unit: string | null;
+    /**
+     * The activity's goal (from 0.2.2), or null when it has none. A point activity's goal is always a count of marks; a
+     * span activity's counts sessions or totals their duration, as the user chose. Progress isn't included: work it out
+     * from the sessions in the current `period`. `undefined` when the Drift Beacon running the plugin predates goals
+     * (main code and UIs alike).
+     */
+    readonly goal?: ActivityGoal | null;
+    /**
+     * The period progress towards `goal` covers (from 0.2.2), or null when it covers all history. `undefined` when the
+     * Drift Beacon running the plugin predates goals.
+     */
+    readonly period?: GoalPeriod | null;
+    /**
+     * Users who have this activity pinned, sorted (from 0.2.2); a user pins at most one activity. Main code sees every
+     * user's pins, a UI only its own user's: use `isPinned` for the current user. `undefined` when the Drift Beacon
+     * running the plugin predates pins.
+     */
+    readonly pinnedBy?: readonly string[];
 }
 /** A category's plain row: what `category.data` returns. */
 export interface CategoryData {
@@ -63,6 +95,11 @@ export interface Activity extends Readonly<ActivityData>, Model<ActivityData> {
     readonly isPoint: boolean;
     /** The current user has a live session of this activity. */
     readonly isLive: boolean;
+    /**
+     * The current user has this activity pinned (from 0.2.2). Test it for truthiness: main code gets its models from the
+     * Drift Beacon running it, and on one older than 0.2.2 this is `undefined` (a UI bundles its own models: false).
+     */
+    readonly isPinned: boolean;
     readonly category: Category | undefined;
     /** This activity's sessions, newest first. */
     sessions(filter?: Omit<SessionFilter, "activityId">): readonly Session[];
@@ -178,13 +215,13 @@ export interface SessionsApi {
     /** Data change events. They can arrive in bursts after a sync; don't use them to trigger actions. */
     onChange(callback: (change: Change<Session>) => void): Unsubscribe;
 }
-/** The plugin's own key-value storage, per user and workspace. Values must be JSON-compatible. */
+/** The plugin's own key-value storage, per user and workspace: non-empty string keys, JSON-compatible values. */
 export interface StorageApi {
     get<T = unknown>(key: string): T | undefined;
     keys(): readonly string[];
     /**
      * 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`.
+     * an empty key or 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. */
@@ -237,6 +274,13 @@ export interface PluginPeer {
     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;
+    /**
+     * Called for each of its events with this name (manifest.json `provides.events`), with the payload (frozen). In a
+     * UI (from 0.2.1): from `connect()` on, with the state its plugin set before it, not replayed, errors logged, and
+     * every open copy of the UI gets each one; against an older Drift Beacon it's never called. In main code, see
+     * `MainPluginPeer.onEvent`. Throws `invalid` for a name that isn't camelCase.
+     */
+    onEvent(name: string, callback: (payload: unknown) => void): Unsubscribe;
 }
 /** The plugins this one uses. */
 export interface PluginsApi {
@@ -245,4 +289,28 @@ export interface PluginsApi {
     /** This plugin itself, as other plugins see it. */
     readonly self: PluginPeer;
 }
+/** Semantic colors supplied by the UI host (SDK 0.2.3). Values are complete CSS colors. */
+export interface UiThemeColors {
+    readonly background: string;
+    readonly foreground: string;
+    readonly surface: string;
+    readonly surfaceForeground: string;
+    readonly surfaceRaised: string;
+    readonly muted: string;
+    readonly border: string;
+    readonly accent: string;
+    readonly accentForeground: string;
+    readonly danger: string;
+    readonly dangerForeground: string;
+    readonly success: string;
+    readonly successForeground: string;
+    readonly warning: string;
+    readonly warningForeground: string;
+    readonly focus: string;
+}
+/** An immutable theme snapshot. background is the surface containing this plugin. */
+export interface UiTheme {
+    readonly mode: "light" | "dark";
+    readonly colors: Readonly<UiThemeColors>;
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/ui.d.ts

@@ -1,9 +1,13 @@
-import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, Unsubscribe, UserInfo, WorkspaceInfo } from "./types.ts";
+import type { ActivitiesApi, CategoriesApi, PluginConfig, PluginInfo, PluginsApi, SessionsApi, StorageApi, UiTheme, 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 {
+    /** Current host theme; SDK 0.2.3 applies --db-* variables before connect resolves. Older hosts use a dark fallback. */
+    readonly theme: UiTheme;
+    /** Theme-only updates do not fire onDataChange. CSS updates before this callback runs. */
+    onThemeChange(callback: (theme: UiTheme) => void): Unsubscribe;
     /** The installed plugin; it can change while the UI is open, for example to a new version. */
     readonly plugin: PluginInfo;
     readonly user: UserInfo;
@@ -15,13 +19,14 @@ export interface UiContext {
     readonly sessions: SessionsApi;
     /**
      * Called after each update from the app (workspace data, config, storage, or other plugins' status and state) and
-     * after local storage writes.
+     * after local storage writes; not for other plugins' events.
      */
     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.
+     * Its own plugin and the plugins it uses: their status and published state (within about 250 ms of a change),
+     * their events (with them), and their commands. A command's effects on their state, storage or data, and its events,
+     * can arrive just after it resolves.
      */
     readonly plugins: PluginsApi;
 }

package/dist/ui.js

@@ -1,10 +1,12 @@
 import { PluginError } from "./errors.js";
+import { checkedAction } from "./internal/actions.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 { commandArgumentsProblem, commandBudgetMs, eventNameProblem, samePluginStatus } from "./internal/peers.js";
 import { isUiMessage, UI_CHANNEL, } from "./internal/protocol.js";
+import { applyTheme, fallbackTheme, readTheme } from "./internal/theme.js";
 import { API_VERSION } from "./version.js";
 export { PluginError } from "./errors.js";
 export { API_VERSION } from "./version.js";
@@ -79,6 +81,8 @@ function open(timeoutMs) {
 class UiClient {
     post;
     context;
+    theme;
+    themeListeners = new Set();
     config;
     plugin;
     rows = {
@@ -106,6 +110,8 @@ class UiClient {
     peerObjects = new Map();
     constructor(welcome, post) {
         this.post = post;
+        this.theme = readTheme(welcome.theme) ?? fallbackTheme();
+        applyTheme(this.theme);
         this.config = welcome.config;
         this.plugin = welcome.plugin;
         this.peersShared = welcome.peers !== undefined;
@@ -127,11 +133,11 @@ class UiClient {
         this.applyData(welcome.data);
         const apis = this.models.apis();
         const self = this;
-        const subscribe = (listeners, callback) => {
-            listeners.add(callback);
-            return () => listeners.delete(callback);
-        };
         this.context = {
+            get theme() {
+                return self.theme;
+            },
+            onThemeChange: (callback) => subscribe(self.themeListeners, callback),
             get plugin() {
                 return self.plugin;
             },
@@ -178,10 +184,6 @@ class UiClient {
         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() {
@@ -194,6 +196,20 @@ class UiClient {
                 keys: () => [...view.state.keys()],
                 onChange: (callback) => subscribe(view.stateListeners, callback),
             }),
+            onEvent: (name, callback) => {
+                const invalidName = eventNameProblem(name);
+                if (invalidName)
+                    throw new PluginError("invalid", invalidName);
+                const problem = this.unreachable(id);
+                if (problem)
+                    throw problem;
+                let listeners = view.eventListeners.get(name);
+                if (!listeners) {
+                    listeners = new Set();
+                    view.eventListeners.set(name, listeners);
+                }
+                return subscribe(listeners, callback);
+            },
         });
         this.peerObjects.set(id, peer);
         return peer;
@@ -206,7 +222,13 @@ class UiClient {
     viewOf(id) {
         let view = this.peerViews.get(id);
         if (!view) {
-            view = { status: NO_PEERS, state: new Map(), statusListeners: new Set(), stateListeners: new Set() };
+            view = {
+                status: NO_PEERS,
+                state: new Map(),
+                statusListeners: new Set(),
+                stateListeners: new Set(),
+                eventListeners: new Map(),
+            };
             this.peerViews.set(id, view);
         }
         return view;
@@ -270,6 +292,7 @@ class UiClient {
     receive(message) {
         if (message.type === "welcome") {
             this.plugin = message.plugin;
+            this.updateTheme(readTheme(message.theme) ?? fallbackTheme());
             this.receive({
                 channel: message.channel,
                 type: "state",
@@ -291,8 +314,17 @@ class UiClient {
                 pending.resolve(message.result);
             return;
         }
+        if (message.type === "event") {
+            this.applyEvent(message);
+            return;
+        }
         if (message.type !== "state")
             return;
+        if (message.theme) {
+            const theme = readTheme(message.theme);
+            if (theme)
+                this.updateTheme(theme);
+        }
         if (message.config)
             this.config = message.config;
         if (message.data)
@@ -304,7 +336,25 @@ class UiClient {
         }
         if (message.peers)
             this.applyPeers(message.peers);
-        notify(this.dataListeners, (listener) => listener());
+        if (message.config || message.data || message.storage || message.peers) {
+            notify(this.dataListeners, (listener) => listener());
+        }
+    }
+    updateTheme(theme) {
+        if (jsonEqual(this.theme, theme))
+            return;
+        this.theme = theme;
+        applyTheme(theme);
+        notify(this.themeListeners, (listener) => listener(theme));
+    }
+    applyEvent({ plugin, event, payload }) {
+        if (!this.listed.has(plugin))
+            return;
+        const listeners = this.peerViews.get(plugin)?.eventListeners.get(event);
+        if (!listeners?.size)
+            return;
+        const frozen = deepFreeze(payload);
+        notify(listeners, (listener) => listener(frozen));
     }
     applyData(data) {
         const changes = this.models.update({
@@ -341,6 +391,9 @@ class UiClient {
         return changed;
     }
     async write(key, value) {
+        const checked = checkedAction(value === undefined ? { name: "storageRemove", key } : { name: "storageSet", key, value });
+        if (checked?.ok === false)
+            throw new PluginError("invalid", checked.problem);
         const writeId = ++this.nextWrite;
         this.pendingWrites.set(key, (this.pendingWrites.get(key) ?? 0) + 1);
         this.writesSincePush.set(key, writeId);
@@ -385,13 +438,24 @@ class UiClient {
         });
     }
 }
+function subscribe(listeners, callback) {
+    if (typeof callback !== "function")
+        throw new PluginError("invalid", "Callback must be a function");
+    listeners.add(callback);
+    return () => listeners.delete(callback);
+}
+const logListenerError = (error) => console.error("[drift-beacon] Error in plugin listener:", error);
 function notify(listeners, call) {
-    for (const listener of listeners) {
+    for (const listener of [...listeners]) {
+        if (!listeners.has(listener))
+            continue;
         try {
-            call(listener);
+            const result = call(listener);
+            if (result && typeof result.then === "function")
+                result.then(undefined, logListenerError);
         }
         catch (error) {
-            console.error("[drift-beacon] Error in plugin listener:", error);
+            logListenerError(error);
         }
     }
 }

package/package.json

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