@tokamakdev/plugin 0.1.0-beta.106 → 0.1.0-beta.112

package/README.md

@@ -1,49 +1,65 @@
 # @tokamakdev/plugin
 
-The shared base of tokamak plugins: the native transport, Worker events, and
-test fakes.
+Native plugin APIs, endpoint codecs, event contracts and test fixtures.
 
 | Entry | Contents |
 | --- | --- |
-| `@tokamakdev/plugin` | `Plugin`, the base class of a plugin's API, which the page and the Worker call alike |
-| `@tokamakdev/plugin/events` | `defineEvent`, which defines a plugin's Worker events |
-| `@tokamakdev/plugin/testing` | A fake native transport, and `dispatch`, which runs event listeners as the runtime does |
+| `@tokamakdev/plugin` | `Plugin`, `TokamakContext`, JSON codec and value types |
+| `@tokamakdev/plugin/streams` | Bounded push streams and typed JSON stream decoding |
+| `@tokamakdev/plugin/events` | `defineEvent` |
+| `@tokamakdev/plugin/testing` | Invocation fixture and event dispatch |
 
-A plugin lists `@tokamakdev/plugin` as a peer dependency, so an app has one
-copy of it, shared with `@tokamakdev/tok`, which depends on it.
-
-## Calls
-
-A plugin's API extends `Plugin`, whose `call` and `listen` reach its native
-code from the page through the shell's bridge, and from the Worker through the
-runtime. `hasNativeTransport` is false outside a tokamak app, such as on the
-web and Cloudflare, where the plugin uses its web implementation or rejects
-with `NotSupportedError`:
+Plugin packages declare this package as a peer dependency. Native APIs require
+the receiving Tokamak worker invocation's context:
 
 ```ts
-import { Plugin } from "@tokamakdev/plugin";
+import { Plugin, type TokamakContext } from "@tokamakdev/plugin";
 
 class Alarms extends Plugin {
-  constructor() {
-    super("alarms");
-  }
+  constructor(ctx: TokamakContext) { super(ctx, "alarms"); }
+  set(at: number): Promise<void> { return this.call("set", { at }); }
+  rings(): ReadableStream<Uint8Array> { return this.stream("rings"); }
+}
+export function alarms(ctx: TokamakContext) { return new Alarms(ctx); }
+```
 
-  set(at: number): Promise<void> {
-    return this.call("set", { at });
-  }
+`call` uses the standard JSON endpoint codec. `callBytes` sends and receives
+opaque bytes. `stream` exposes JSON values as a cancellable byte stream;
+`decodeValues<T>` consumes it. Errors terminate a stream. A slow consumer
+exceeding its bounded buffer receives `QuotaExceededError`.
 
-  onRing(next: (id: string) => void, error: (error: DOMException) => void): () => void {
-    return this.listen("onRing", next, error);
-  }
-}
+Declare the factory in `tokamak-plugin.json` alongside native build metadata:
 
-export const alarms = new Alarms();
+```json
+{
+  "schemaVersion": 2,
+  "id": "alarms",
+  "api": { "module": "src/index.ts", "export": "alarms" }
+}
 ```
 
-The native side runs each call and subscription on the main thread, for the
-page and the Worker alike. A `subscribe` that throws, as for a method the
-plugin does not have, ends the subscription; a failure it replies with does
-not.
+Tooling generates the `example-alarms/client` default export for pages and the
+`env.TOKAMAK_ALARMS` binding for the main worker. Public API methods use the
+supported service-value and byte-stream types. Callback parameters, native
+objects and arbitrary classes are rejected at build time.
+
+An optional `web` module/export reference supplies an object implementing
+frontend methods. Those methods return promises; omitted methods reject with
+`NotSupportedError`. Browser code belongs in that module, separate from the
+native factory. A native factory never tests browser globals.
+
+In `src/tokamak.ts`, call `alarms(ctx).set(at)` using the context passed to an
+event handler, or `alarms(this.ctx)` in a `TokamakEntrypoint` method. Dependencies
+and build tooling belong to the same app project.
+
+Tests construct an invocation without installing global transports:
+
+```ts
+const native = connectNative();
+const result = alarms(native.ctx).set(123);
+native.respond({ value: null });
+await result;
+```
 
 ## Showing UI
 
@@ -67,7 +83,7 @@ so only calls that would show UI fail:
 
 ## Worker events
 
-A plugin's native code delivers events to the app's Worker, whose listeners
+A plugin's native code delivers events to the app's Tokamak worker, whose listeners
 register in `src/tokamak.ts` and run even when no page is loaded, such as when
 the system starts the app in the background.
 
@@ -118,3 +134,14 @@ import { dispatch } from "@tokamakdev/plugin/testing";
 onRing(() => 5);
 const { reply, reported } = await dispatch("alarms.ring", { id: "a1" }, env);
 ```
+## WebView controls
+
+Inside the Tokamak worker, use `this.ctx.webview.navigate("/recipes")`,
+`await this.ctx.webview.getCurrentPage()`, or
+`await this.ctx.webview.postMessage({ recipeId: "42" })`. A page receives messages
+through its standard `window.addEventListener("message", handler)`.
+
+Navigation accepts URLs within the app's origin and resolves when the native
+view accepts the navigation. Messaging resolves after dispatch into the current
+page. These operations reject with `InvalidStateError` when no page is loaded;
+they neither create a view nor queue messages for a later page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/plugin",
-  "version": "0.1.0-beta.106",
+  "version": "0.1.0-beta.112",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
@@ -9,8 +9,13 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
+    "./streams": "./src/streams.ts",
+    "./bindings": "./src/bindings.ts",
     "./events": "./src/events.ts",
-    "./testing": "./src/testing.ts"
+    "./worker": "./src/worker.ts",
+    "./testing": "./src/testing.ts",
+    "./native-protocol": "./src/native-protocol.mjs",
+    "./capabilities": "./src/capabilities.mjs"
   },
   "files": [
     "src"

package/src/bindings.ts

@@ -0,0 +1,260 @@
+import { nativeConnection, type TokamakContext } from "./context.js";
+import { decodeJson, encodeJson } from "./codec.js";
+import { nativeError, type NativeFailure } from "./native-protocol.mjs";
+import { NativeReference, ownerOf } from "./resources.js";
+import { byteStream } from "./streams.js";
+
+export type { TokamakContext } from "./context.js";
+export { NativeReference } from "./resources.js";
+
+/** The reference `object` views: pass it to another class's constructor or to a plugin's native endpoint. */
+export let referenceOf: (object: NativeObject) => NativeReference;
+
+/**
+ * A native object that a generated binding returned. Its class mirrors the native class; every
+ * member is asynchronous. The invocation that received it owns it until `release`, the
+ * invocation's end, or garbage collection.
+ */
+export class NativeObject {
+  readonly #reference: NativeReference;
+
+  static {
+    referenceOf = (object) => object.#reference;
+  }
+
+  /** Views the object `reference` holds as this class. The native side checks the type at each call. */
+  constructor(reference: NativeReference) {
+    this.#reference = reference;
+  }
+}
+
+/** Releases `object` for every view of it. Later calls on it reject with `InvalidStateError`. */
+export function release(object: NativeObject): void {
+  referenceOf(object).close();
+}
+
+type NativeClass = new (reference: NativeReference) => NativeObject;
+
+/** The classes of a binding module, by native name. */
+export type Classes = Readonly<Record<string, NativeClass>>;
+
+/** The calls of one generated binding module, whose native plugin is `plugin`. */
+export class Bindings {
+  readonly #plugin: string;
+  readonly #classes: () => Classes;
+
+  /** `classes` returns the module's classes once they are defined. */
+  constructor(plugin: string, classes: () => Classes) {
+    this.#plugin = plugin;
+    this.#classes = classes;
+  }
+
+  /**
+   * Calls `member` of `target`, the object or, for a static member, the invocation's context.
+   * Aborting `signal` cancels an asynchronous member's task.
+   */
+  async call<T>(target: TokamakContext | NativeObject, member: string, args: readonly unknown[], signal?: AbortSignal): Promise<T> {
+    const ctx = contextOf(target);
+    const reply = await ctx[nativeConnection].call(this.#plugin, member, await request(ctx, target, args), { signal });
+    return this.#decode(ctx, reply) as T;
+  }
+
+  /**
+   * The key of the first of `overloads` whose parameters take `args`: each parameter lists the
+   * kinds of value it takes, a class or a `typeof` name, `"array"`, `"bytes"`, `"date"`, `"object"`
+   * (a plain object), `"null"` or `"any"`.
+   */
+  overload(args: readonly unknown[], overloads: readonly (readonly [string, readonly (readonly Kind[])[]])[]): string {
+    const found = overloads.find(([, params]) =>
+      params.length === args.length && params.every((kinds, index) => kinds.some((kind) => takes(kind, args[index]))));
+    if (!found) throw new TypeError("No overload takes these arguments");
+    return found[0];
+  }
+
+  /** The elements of the native sequence `member` of `target` returns. Cancelling the stream ends it. */
+  stream<T>(target: TokamakContext | NativeObject, member: string, args: readonly unknown[]): ReadableStream<T> {
+    const ctx = contextOf(target);
+    const elements = byteStream((next, error, close) => {
+      let stop: (() => void) | undefined;
+      let stopped = false;
+      request(ctx, target, args).then((payload) => {
+        if (stopped) return;
+        stop = ctx[nativeConnection].listen(this.#plugin, member, payload, {
+          next: (value, done) => { if (done) close(); else next(value); },
+          error,
+        });
+      }, error);
+      return () => {
+        stopped = true;
+        stop?.();
+      };
+    });
+    return elements.pipeThrough(new TransformStream<Uint8Array, T>({
+      transform: (element, controller) => { controller.enqueue(this.#decode(ctx, element) as T); },
+    }));
+  }
+
+  /**
+   * A native object implementing `protocol` whose `methods`, where `handlers` has them, call
+   * `handlers` in order. Its platform defaults remain for the methods `handlers` lacks.
+   */
+  async implement<T extends NativeObject>(
+    ctx: TokamakContext,
+    Protocol: new (reference: NativeReference) => T,
+    protocol: string,
+    methods: readonly string[],
+    handlers: object,
+  ): Promise<T> {
+    const handled = methods.filter((method) => typeof Reflect.get(handlers, method) === "function");
+    const payload = encodeJson({ scope: await scopeOf(ctx), methods: handled });
+    const reference = await NativeReference.acquire(ctx, this.#plugin, protocol, payload, (value) => {
+      const { method, arguments: args } = decodeJson<{ method: string; arguments: Wire[] }>(value);
+      const classes = this.#classes();
+      try {
+        const handler = Reflect.get(handlers, method) as (...values: unknown[]) => unknown;
+        Promise.resolve(handler.apply(handlers, args.map((arg) => fromWire(arg, ctx, classes)))).catch((error: unknown) => {
+          reportError(error);
+        });
+      } catch (error) {
+        reportError(error);
+      }
+    });
+    return new Protocol(reference);
+  }
+
+  #decode(ctx: TokamakContext, payload: Uint8Array): unknown {
+    return fromWire(decodeJson<Wire>(payload), ctx, this.#classes());
+  }
+}
+
+/** A kind of value an overload's parameter takes. */
+type Kind = string | (abstract new (reference: NativeReference) => NativeObject);
+
+/** The kinds named by strings other than `typeof` results. */
+const named = new Map<string, (value: unknown) => boolean>([
+  ["any", () => true],
+  ["null", (value) => value === null || value === undefined],
+  ["array", (value) => Array.isArray(value)],
+  ["bytes", (value) => value instanceof Uint8Array],
+  ["date", (value) => value instanceof Date],
+  ["object", (value) => typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof NativeObject)],
+]);
+
+function takes(kind: Kind, value: unknown): boolean {
+  if (typeof kind === "function") return value instanceof kind;
+  const takes = named.get(kind);
+  return takes ? takes(value) : typeof value === kind;
+}
+
+/** The Android application `Context`. */
+export function applicationContext(ctx: TokamakContext): Promise<NativeReference> {
+  return root(ctx, "context");
+}
+
+/** The Android activity the app shows. Rejects with `NeedsUIError` while the app cannot show UI. */
+export function foregroundActivity(ctx: TokamakContext): Promise<NativeReference> {
+  return root(ctx, "activity");
+}
+
+/**
+ * The Apple object a native screen is presented from: the top `UIViewController` on iOS, the
+ * `NSWindow` on macOS. Rejects with `NeedsUIError` while the app cannot show UI.
+ */
+export function presenter(ctx: TokamakContext): Promise<NativeReference> {
+  return root(ctx, "presenter");
+}
+
+async function root(ctx: TokamakContext, name: string): Promise<NativeReference> {
+  const payload = encodeJson({ scope: await scopeOf(ctx), name });
+  const id = decodeJson<string>(await ctx[nativeConnection].call("tokamak", "resource.root", payload));
+  return NativeReference.scoped(ctx, id);
+}
+
+const scopes = new WeakMap<TokamakContext, Promise<string>>();
+
+/** The scope that keeps the objects the invocation `ctx` receives until it ends. */
+function scopeOf(ctx: TokamakContext): Promise<string> {
+  let scope = scopes.get(ctx);
+  if (!scope) {
+    // The subscription stays open for the invocation, whose end releases the scope's objects.
+    scope = new Promise((resolve, reject) => {
+      ctx[nativeConnection].listen("tokamak", "resource.scope", encodeJson(null), {
+        next: (value) => { resolve(decodeJson<string>(value)); },
+        error: reject,
+      });
+    });
+    scopes.set(ctx, scope);
+  }
+  return scope;
+}
+
+function contextOf(target: TokamakContext | NativeObject): TokamakContext {
+  return target instanceof NativeObject ? ownerOf(referenceOf(target)) : target;
+}
+
+async function request(ctx: TokamakContext, target: TokamakContext | NativeObject, args: readonly unknown[]): Promise<Uint8Array> {
+  return encodeJson({
+    scope: await scopeOf(ctx),
+    target: target instanceof NativeObject ? toWire(target, ctx) : undefined,
+    arguments: args.map((arg) => toWire(arg, ctx)),
+  });
+}
+
+/**
+ * Binding values as JSON. Objects tagged `#` carry what JSON lacks: native objects, dates, bytes,
+ * errors, non-finite numbers, and records whose own keys include `#`.
+ */
+type Wire = null | boolean | number | string | Wire[] | { [key: string]: Wire };
+
+function toWire(value: unknown, ctx: TokamakContext): Wire {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "number" && !Number.isFinite(value)) return { "#": "number", value: String(value) };
+  if (typeof value !== "object") return value as Wire;
+  return objectToWire(value, ctx);
+}
+
+function objectToWire(value: object, ctx: TokamakContext): Wire {
+  const reference = value instanceof NativeObject ? referenceOf(value) : value;
+  if (reference instanceof NativeReference) return { "#": "object", id: reference.idFor(ctx) };
+  if (value instanceof Date) return { "#": "date", value: value.getTime() };
+  if (value instanceof Uint8Array) return { "#": "bytes", value: toBase64(value) };
+  if (Array.isArray(value)) return value.map((item) => toWire(item, ctx));
+  const fields = Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toWire(item, ctx)]));
+  return "#" in fields ? { "#": "record", value: fields } : fields;
+}
+
+type Tagged = Record<string, Wire>;
+
+/** The decoder of each tag. */
+const tags = new Map<string, (value: Tagged, ctx: TokamakContext, classes: Classes) => unknown>([
+  ["object", (value, ctx, classes) => {
+    const Class = (value.types as string[]).map((type) => classes[type]).find(Boolean) ?? NativeObject;
+    return new Class(NativeReference.scoped(ctx, value.id as string));
+  }],
+  ["number", (value) => Number(value.value)],
+  ["date", (value) => new Date(value.value as number)],
+  ["bytes", (value) => fromBase64(value.value as string)],
+  ["error", (value) => nativeError(value as unknown as NativeFailure)],
+  ["record", (value, ctx, classes) => fields(value.value as Tagged, ctx, classes)],
+]);
+
+function fromWire(value: Wire, ctx: TokamakContext, classes: Classes): unknown {
+  if (Array.isArray(value)) return value.map((item) => fromWire(item, ctx, classes));
+  if (value === null || typeof value !== "object") return value;
+  const decode = typeof value["#"] === "string" ? tags.get(value["#"]) : undefined;
+  return decode ? decode(value, ctx, classes) : fields(value, ctx, classes);
+}
+
+function fields(value: Record<string, Wire>, ctx: TokamakContext, classes: Classes): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fromWire(item, ctx, classes)]));
+}
+
+function toBase64(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function fromBase64(text: string): Uint8Array {
+  return Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+}

package/src/capabilities.d.mts

@@ -0,0 +1,11 @@
+/** A native platform the host runs on. */
+export type NativePlatform = "ios" | "macos" | "android" | "windows" | "linux";
+
+/** The native platforms of each plugin operation, by plugin ID and operation name. */
+export type Availability = Readonly<Record<string, Readonly<Record<string, readonly NativePlatform[]>>>>;
+
+/** Whether each operation of each plugin in `availability` has an implementation on `platform`. */
+export function capabilitiesFor(
+  availability: Availability,
+  platform: NativePlatform | undefined,
+): Record<string, Record<string, boolean>>;

package/src/capabilities.mjs

@@ -0,0 +1,8 @@
+/** Whether each operation of each plugin in `availability` has an implementation on `platform`. */
+export function capabilitiesFor(availability, platform) {
+  return Object.fromEntries(Object.entries(availability).map(([plugin, operations]) => [
+    plugin,
+    Object.fromEntries(Object.entries(operations).map(([operation, platforms]) =>
+      [operation, platform !== undefined && platforms.includes(platform)])),
+  ]));
+}

package/src/codec.ts

@@ -0,0 +1,15 @@
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+
+/** Encodes the standard structured-value endpoint payload. */
+export function encodeJson(value: unknown): Uint8Array {
+  return encoder.encode(JSON.stringify(value ?? null));
+}
+
+/** Decodes the standard structured-value endpoint payload. */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- the endpoint signature supplies the decoded type.
+export function decodeJson<T>(payload: Uint8Array): T {
+  return JSON.parse(decoder.decode(payload)) as T;
+}

package/src/context.ts

@@ -0,0 +1,91 @@
+import { capabilitiesFor, type Availability, type NativePlatform } from "./capabilities.mjs";
+import { webview, type WebView } from "./webview.js";
+
+/** The native connection supplied by the host. */
+export const nativeConnection = Symbol.for("tokamak.native");
+
+/** Each plugin operation's native platforms, by plugin ID, which the plugins' manifests declare. */
+export const nativeAvailability = Symbol.for("tokamak.availability");
+
+export type { Availability, NativePlatform } from "./capabilities.mjs";
+
+/** A native call's request body and cancellation. */
+export interface CallOptions {
+  /** Bytes the native endpoint reads one chunk at a time, as it needs them. */
+  readonly body?: ReadableStream<Uint8Array>;
+  /** Cancels the call, which then rejects with the signal's reason. */
+  readonly signal?: AbortSignal;
+}
+
+/** What a subscription does with a value that arrives while its buffer is full. */
+export type Overflow = "error" | "dropOldest";
+
+/** Receives a native subscription's values and failures. */
+export interface NativeListener {
+  readonly next: (value: Uint8Array, done: boolean) => void;
+  readonly error: (error: DOMException, done: boolean) => void;
+  /** What happens to values a slow reader has not taken; `"error"` by default. */
+  readonly overflow?: Overflow;
+}
+
+export interface NativeConnection {
+  /** The platform the host runs on. */
+  readonly platform?: NativePlatform;
+  call(plugin: string, method: string, payload: Uint8Array, options?: CallOptions): Promise<Uint8Array>;
+  /** Subscribes `listener` until the returned function is called. */
+  listen(plugin: string, method: string, payload: Uint8Array, listener: NativeListener): () => void;
+}
+
+/** The receiving invocation and its native connection. */
+export interface TokamakContext {
+  waitUntil(promise: Promise<unknown>): void;
+  readonly webview: WebView;
+  /** The native platform the app runs on, or undefined without a native host. */
+  readonly platform: NativePlatform | undefined;
+  readonly [nativeConnection]: NativeConnection;
+  readonly [nativeAvailability]: Availability;
+}
+
+function unavailable(): never {
+  throw new DOMException("The native device is not connected.", "NotSupportedError");
+}
+
+const disconnected: NativeConnection = {
+  call: () => Promise.resolve().then(unavailable),
+  listen: unavailable,
+};
+
+/**
+ * The receiving execution context with its native connection, `connection` or the one the host
+ * attached to `ctx`, and the plugins' `availability`. Without a connection, native calls reject
+ * with `NotSupportedError`.
+ */
+export function createNativeContext(
+  ctx: Pick<TokamakContext, "waitUntil"> & { readonly [nativeConnection]?: NativeConnection },
+  connection = ctx[nativeConnection],
+  availability: Availability = {},
+): TokamakContext {
+  const native = connection ?? disconnected;
+  return Object.assign(ctx, {
+    [nativeConnection]: native,
+    [nativeAvailability]: availability,
+    platform: native.platform,
+    webview: webview(native),
+  });
+}
+
+/**
+ * Whether each operation of `plugin` has an implementation on the platform `ctx` runs on. It does
+ * not report permission or promise that a call succeeds.
+ */
+export function capabilitiesOf(ctx: TokamakContext, plugin: string): Readonly<Record<string, boolean>> {
+  return Object.freeze(capabilitiesFor({ [plugin]: ctx[nativeAvailability][plugin] ?? {} }, ctx.platform)[plugin] ?? {});
+}
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- the generated app declarations supply the native bindings.
+  namespace Tokamak {
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the app's generated types declare the members.
+    interface Env {}
+  }
+}
+

package/src/entrypoint.js

@@ -1,12 +1,25 @@
-// The tokamak Vite plugin exports this class from the entry Worker in tokamak builds and
-// development, where the runtime and `tok dev` call `dispatch` to deliver events.
 import { WorkerEntrypoint } from "cloudflare:workers";
 
-import { dispatch } from "./registry.ts";
+import { dispatch, eventCodec, listenedEvents } from "./registry.ts";
+import { TokamakEntrypoint } from "./worker.ts";
 
-export class TokamakEvents extends WorkerEntrypoint {
-  /** Runs the listeners of the event `name` and returns `{ reply, listened }`. */
-  dispatch(name, event) {
-    return dispatch(name, event, this.env, this.ctx);
-  }
+/**
+ * The host's event adapter for the application's native entrypoint. Event data and replies are
+ * bytes until this endpoint decodes and encodes them with the event's codec.
+ */
+export function eventEntrypoint(Worker, nativeContext) {
+  return class extends WorkerEntrypoint {
+    async dispatch(type, payload) {
+      const ctx = nativeContext(this.ctx);
+      const worker = new Worker(ctx, this.env);
+      const codec = eventCodec(type);
+      const data = codec.decode(payload);
+      // Worker classes without an event handler use registered listeners.
+      const listening = typeof worker.event !== "function" || worker.event === TokamakEntrypoint.prototype.event;
+      const reply = typeof worker.event === "function"
+        ? await worker.event({ type, data })
+        : (await dispatch(type, data, this.env, ctx)).reply;
+      return { reply: codec.encode(reply), listened: listening ? listenedEvents() : undefined };
+    }
+  };
 }

package/src/events.ts

@@ -1,35 +1,57 @@
-import { register, type RegisteredListener } from "./registry.js";
+import { register, setCodec, type EventCodec, type RegisteredListener } from "./registry.js";
+import type { TokamakContext } from "./context.js";
+
+export type { EventCodec } from "./registry.js";
 
 declare global {
-  // eslint-disable-next-line @typescript-eslint/no-namespace -- `wrangler types` declares the Worker's bindings here.
-  namespace Cloudflare {
-    // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the app's `wrangler types` declares the members.
-    interface Env {}
+  // eslint-disable-next-line @typescript-eslint/no-namespace -- plugins add their events by declaration merging.
+  namespace Tokamak {
+    /** Each event's data, by event type. A plugin adds its events as `"<plugin>.<name>"`. */
+    interface Events {
+      /** The runtime started, including when the system started the app in the background. */
+      start: { readonly foreground: boolean };
+      /** The app moved into the foreground, other than when it started there. */
+      resume: Readonly<Record<string, never>>;
+      /** The app moved out of the foreground. */
+      suspend: Readonly<Record<string, never>>;
+    }
+    /** The reply of each event that takes one, by event type. */
+    // eslint-disable-next-line @typescript-eslint/no-empty-object-type -- plugins declare the members.
+    interface EventReplies {}
   }
 }
 
+/** The type of a lifecycle or plugin event. */
+export type EventType = keyof Tokamak.Events;
+
+/** What listeners of the event `Type` may reply. */
+// eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- listeners of events without replies return void.
+export type EventReply<Type extends EventType> = Type extends keyof Tokamak.EventReplies ? Tokamak.EventReplies[Type] : void;
+
+/** One lifecycle or plugin event delivered by the native host. */
+export type TokamakEvent = { [Type in EventType]: { readonly type: Type; readonly data: Tokamak.Events[Type] } }[EventType];
+
 /** The invocation a listener runs in. */
-export interface EventContext {
-  /** Keeps the event running until `promise` settles or the event's deadline passes. */
-  waitUntil(promise: Promise<unknown>): void;
-}
+export type EventContext = TokamakContext;
 
-/** Receives an event of type `T` with the Worker's `env`, and may return a `Reply`. */
+/** Receives an event's data with the Worker's `env`, and may return a `Reply`. */
 export type Listener<T, Reply = void> = (
   event: T,
-  env: Cloudflare.Env,
+  env: Tokamak.Env,
   ctx: EventContext,
 ) => Reply | undefined | Promise<Reply | undefined>;
 
 /**
- * Defines the event `name` and returns the function that registers its listeners. The event's
- * reply is the first value, in registration order, that a listener returns other than
- * `undefined`.
+ * Defines the event `type`, whose data and reply travel as JSON unless `codec` encodes them, and
+ * returns the function that registers its listeners. The event's reply is the first value, in
+ * registration order, that a listener returns other than `undefined`.
  */
-export function defineEvent<T, Reply = void>(
-  name: string,
-): (listener: Listener<T, Reply>) => void {
+export function defineEvent<Type extends EventType>(
+  type: Type,
+  codec?: EventCodec<Tokamak.Events[Type], EventReply<Type>>,
+): (listener: Listener<Tokamak.Events[Type], EventReply<Type>>) => void {
+  if (codec) setCodec(type, codec);
   return (listener) => {
-    register(name, listener as RegisteredListener);
+    register(type, listener as RegisteredListener);
   };
 }