@tokamakdev/tok 0.1.0-beta.37 → 0.1.1-beta.100

package/README.md

@@ -1,15 +1,51 @@
 # @tokamakdev/tok
 
-The tokamak CLI, published from the tokamak workspace. The version is the
-workspace Cargo version, with a `-beta.N` suffix for automated pre-releases.
+The tokamak CLI, Vite plugin and app API, published from the tokamak
+workspace. The version is the workspace Cargo version, with a `-beta.N` suffix
+for automated pre-releases.
 
 ```sh
-npm install -g @tokamakdev/tok@beta
-tok targets
+npm install --save-dev @tokamakdev/tok
+npx tok targets
 ```
 
-The package installs the `tok` binary for the current platform through an
+| Entry | Contents |
+| --- | --- |
+| `@tokamakdev/tok` | The `Config` type of the Vite plugin's options |
+| `@tokamakdev/tok/events` | The app's events, `onStart`, `onResume` and `onSuspend`, and `getLifecycleStage()` |
+| `@tokamakdev/tok/vite` | The Vite plugin, `tokamak()` |
+| `tok` | The CLI |
+
+The Vite plugin goes next to Cloudflare's, and its options are the app's
+tokamak configuration:
+
+```ts
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { tokamak } from "@tokamakdev/tok/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [cloudflare(), tokamak({ name: "My App", version: "1.0.0" })],
+});
+```
+
+It does nothing unless `tok` runs the build or development command. Then it
+makes the entry Worker import `src/tokamak.ts` and export the entrypoint the
+runtime delivers events through. In development it delivers the device's
+events to the development Worker through Cloudflare's dev registry, and passes
+the development Worker's plugin calls to the device.
+
+The package installs the `tok` binary for the current machine through an
 optional dependency (`@tokamakdev/tok-darwin-arm64`, `-darwin-x64`,
-`-linux-x64`, or `-win32-x64`). Building apps also needs the target packs,
-which the tokamak installer places under `~/.local/share/tokamak`; `tok`
-finds them there, or wherever `TOKAMAK_TARGET_PACK_DIR` points.
+`-linux-x64`, or `-win32-x64`), and the platform packs the machine can build
+as `@tokamakdev/platform-<target>` optional dependencies:
+
+| Machine | Platform packs |
+| --- | --- |
+| macOS, Apple silicon | `android-arm64`, `ios-arm64`, `ios-simulator-arm64`, `macos-arm64` |
+| macOS, Intel | `android-arm64`, `ios-arm64`, `ios-simulator-x64`, `macos-x64` |
+| Windows x64 | `android-arm64`, `windows-x64` |
+| Linux x64 | `android-arm64` |
+
+The launcher passes the installed platform packs to `tok` in
+`TOKAMAK_PLATFORM_PACK_PATH`, unless that variable is already set.

package/bin/tok.js

@@ -2,7 +2,8 @@
 "use strict";
 
 const { spawnSync } = require("node:child_process");
-const { binaryPath } = require("../platform.js");
+const path = require("node:path");
+const { binaryPath, platformPackRoots } = require("../platform.js");
 
 let binary;
 try {
@@ -16,7 +17,13 @@ try {
 // so the launcher only waits for it.
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(signal, () => {});
 
-const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+const env = { ...process.env };
+if (!env.TOKAMAK_PLATFORM_PACK_PATH) {
+  const roots = platformPackRoots(require.resolve);
+  if (roots.length > 0) env.TOKAMAK_PLATFORM_PACK_PATH = roots.join(path.delimiter);
+}
+
+const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit", env });
 if (result.error) {
   console.error(`could not run ${binary}: ${result.error.message}`);
   process.exit(1);

package/dist/dev-socket.d.mts

@@ -0,0 +1,23 @@
+/** The header that carries the device's session token, which `tok dev`'s relay forwards. */
+export declare const SESSION_HEADER = "x-tokamak-session";
+/** A plugin's result, as the page's native transport receives it. */
+export interface PluginResult {
+    value?: unknown;
+    error?: {
+        name: string;
+        message: string;
+    };
+    done: boolean;
+}
+/** The loopback server the device's dev WebSocket reaches through `tok dev`'s relay. */
+export interface DevSocket {
+    readonly port: number;
+    close(): Promise<void>;
+}
+/**
+ * Listens on a loopback port, with `token`, for the device's dev WebSocket and the development
+ * Worker's plugin calls. Delivers each event the device sends to `TokamakEvents` in the
+ * development Worker `workerName`, and passes each plugin call the Worker posts to `/call` or
+ * `/subscribe` to the device.
+ */
+export declare function openDevSocket(workerName: string | undefined, token: string | undefined): Promise<DevSocket>;

package/dist/dev-socket.mjs

@@ -0,0 +1,241 @@
+import http from "node:http";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { WebSocketServer } from "ws";
+/** The header that carries the device's session token, which `tok dev`'s relay forwards. */
+export const SESSION_HEADER = "x-tokamak-session";
+/** How long a plugin call waits for the device to connect. */
+const CONNECT_TIMEOUT = 10_000;
+/** Calls `TokamakEvents` in the Worker its `TOKAMAK` service binding names, through the dev registry. */
+const CALLER = `export default {
+  async fetch(request, env) {
+    const { name, event } = await request.json();
+    try {
+      const { reply } = await env.TOKAMAK.dispatch(name, event);
+      return Response.json({ reply: reply ?? null });
+    } catch (error) {
+      return new Response(error?.stack ?? String(error), { status: 500 });
+    }
+  },
+};`;
+/**
+ * Listens on a loopback port, with `token`, for the device's dev WebSocket and the development
+ * Worker's plugin calls. Delivers each event the device sends to `TokamakEvents` in the
+ * development Worker `workerName`, and passes each plugin call the Worker posts to `/call` or
+ * `/subscribe` to the device.
+ */
+export async function openDevSocket(workerName, token) {
+    const worker = new DevWorker(workerName);
+    const device = new Device();
+    const server = http.createServer((request, response) => {
+        if (!token || request.headers[SESSION_HEADER] !== token) {
+            response.writeHead(401).end();
+            return;
+        }
+        if (request.method === "POST" && (request.url === "/call" || request.url === "/subscribe")) {
+            void forward(device, request, response);
+            return;
+        }
+        response.writeHead(request.method === "GET" ? 426 : 404).end();
+    });
+    const sockets = new WebSocketServer({ noServer: true });
+    server.on("upgrade", (request, socket, head) => {
+        if (!token || request.headers[SESSION_HEADER] !== token) {
+            socket.end("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            return;
+        }
+        sockets.handleUpgrade(request, socket, head, (websocket) => serve(websocket, worker, device));
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    return {
+        port: server.address().port,
+        async close() {
+            for (const websocket of sockets.clients)
+                websocket.terminate();
+            server.closeAllConnections();
+            server.close();
+            await worker.dispose();
+        },
+    };
+}
+function serve(websocket, worker, device) {
+    device.connect(websocket);
+    // The device opens another dev WebSocket after this one fails.
+    websocket.on("error", () => websocket.terminate());
+    websocket.on("message", (data) => {
+        const message = parseMessage(String(data));
+        if (message?.type === "result") {
+            device.receive(message.id, message.result);
+            return;
+        }
+        if (message?.type !== "event")
+            return;
+        worker.dispatch(message.name, message.event).then((reply) => websocket.send(JSON.stringify({ type: "reply", id: message.id, reply })), (error) => websocket.send(JSON.stringify({ type: "error", id: message.id, message: String(error) })));
+    });
+}
+/**
+ * Passes the plugin call `request` carries to the device. A call's response is its result; a
+ * subscription's streams each result as a line of JSON until one is done, and closing it ends the
+ * subscription.
+ */
+async function forward(device, request, response) {
+    let call;
+    try {
+        call = JSON.parse(await readBody(request));
+    }
+    catch {
+        response.writeHead(400).end();
+        return;
+    }
+    response.writeHead(200, { "content-type": "application/json" });
+    if (request.url === "/call") {
+        response.end(JSON.stringify(await new Promise((resolve) => device.send("call", call, resolve))));
+        return;
+    }
+    response.flushHeaders();
+    const cancel = device.send("subscribe", call, (result) => {
+        response.write(`${JSON.stringify(result)}\n`);
+        if (result.done)
+            response.end();
+    });
+    response.once("close", () => {
+        if (!response.writableEnded)
+            cancel();
+    });
+}
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on("data", (chunk) => chunks.push(chunk));
+        request.once("end", () => resolve(Buffer.concat(chunks).toString()));
+        request.once("error", reject);
+    });
+}
+function parseMessage(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A failed result, which ends a subscription. */
+function failure(name, message) {
+    return { error: { name, message }, done: true };
+}
+/** The device, through its latest dev WebSocket, and the plugin calls waiting for its results. */
+class Device {
+    #socket;
+    #connected = [];
+    #nextId = 1;
+    #pending = new Map();
+    connect(socket) {
+        this.#socket = socket;
+        for (const connected of this.#connected.splice(0))
+            connected();
+        socket.once("close", () => {
+            if (this.#socket === socket)
+                this.#socket = undefined;
+            for (const [id, pending] of this.#pending) {
+                if (pending.socket !== socket)
+                    continue;
+                this.#pending.delete(id);
+                pending.receive(failure("NetworkError", "The device disconnected"));
+            }
+        });
+    }
+    receive(id, result) {
+        const pending = this.#pending.get(id);
+        if (!pending)
+            return;
+        if (result.done || pending.type === "call")
+            this.#pending.delete(id);
+        pending.receive(result);
+    }
+    /**
+     * Sends a call or subscription once the device is connected, waiting up to 10 seconds for it,
+     * and passes each of its results to `receive`. Returns the function that unsubscribes.
+     */
+    send(type, request, receive) {
+        const id = this.#nextId++;
+        let cancelled = false;
+        void this.#connection().then((socket) => {
+            if (cancelled)
+                return;
+            if (!socket) {
+                receive(failure("NetworkError", "The device is not connected"));
+                return;
+            }
+            this.#pending.set(id, { type, socket, receive });
+            socket.send(JSON.stringify({ type, id, ...request }));
+        });
+        return () => {
+            cancelled = true;
+            const pending = this.#pending.get(id);
+            if (!pending)
+                return;
+            this.#pending.delete(id);
+            pending.socket.send(JSON.stringify({ type: "unsubscribe", id }));
+        };
+    }
+    /** The open dev WebSocket, once the device connects, or undefined after 10 seconds without. */
+    #connection() {
+        if (this.#socket)
+            return Promise.resolve(this.#socket);
+        return new Promise((resolve) => {
+            const connected = () => {
+                clearTimeout(timer);
+                resolve(this.#socket);
+            };
+            const timer = setTimeout(() => {
+                this.#connected.splice(this.#connected.indexOf(connected), 1);
+                resolve(undefined);
+            }, CONNECT_TIMEOUT);
+            this.#connected.push(connected);
+        });
+    }
+}
+/** The development Worker's `TokamakEvents`, called through a Miniflare session started on first use. */
+class DevWorker {
+    name;
+    #miniflare;
+    constructor(name) {
+        this.name = name;
+    }
+    async dispatch(name, event) {
+        this.#miniflare ??= this.#start().catch((error) => {
+            this.#miniflare = undefined;
+            throw error;
+        });
+        const miniflare = await this.#miniflare;
+        const response = await miniflare.dispatchFetch("http://tokamak/", {
+            method: "POST",
+            body: JSON.stringify({ name, event }),
+        });
+        if (!response.ok)
+            throw new Error(await response.text());
+        return (await response.json()).reply;
+    }
+    async dispose() {
+        await (await this.#miniflare?.catch(() => undefined))?.dispose();
+    }
+    /** A Miniflare session from the Miniflare that Cloudflare's plugin uses. */
+    async #start() {
+        if (!this.name)
+            throw new Error("the Wrangler configuration names no Worker to deliver events to");
+        const require = createRequire(import.meta.resolve("@cloudflare/vite-plugin"));
+        const module = (await import(pathToFileURL(require.resolve("miniflare")).href));
+        const miniflare = new module.Miniflare(module.convertV4MiniflareOptions({
+            modules: true,
+            script: CALLER,
+            compatibilityDate: "2025-01-01",
+            serviceBindings: { TOKAMAK: { name: this.name, entrypoint: "TokamakEvents" } },
+            unsafeDevRegistryPath: module.getDefaultDevRegistryPath(),
+        }));
+        await miniflare.ready;
+        return miniflare;
+    }
+}

package/dist/events.d.mts

@@ -0,0 +1,16 @@
+/** Runs once per runtime start, including when the system starts the app in the background. */
+export declare const onStart: (listener: import("@tokamakdev/plugin/events").Listener<{
+    readonly foreground: boolean;
+}, void>) => void;
+/** Runs each time the app moves into the foreground, but not when it starts there. */
+export declare const onResume: (listener: import("@tokamakdev/plugin/events").Listener<Readonly<Record<string, never>>, void>) => void;
+/** Runs each time the app moves out of the foreground. */
+export declare const onSuspend: (listener: import("@tokamakdev/plugin/events").Listener<Readonly<Record<string, never>>, void>) => void;
+/** Whether the app is on screen. */
+export type LifecycleStage = "foreground" | "background";
+/**
+ * The app's stage now, which can differ from the last event delivered: an `onSuspend` listener
+ * that runs late reads `"foreground"` once the user has returned. Rejects with
+ * `NotSupportedError` outside a tokamak Worker.
+ */
+export declare function getLifecycleStage(): Promise<LifecycleStage>;

package/dist/events.mjs

@@ -0,0 +1,26 @@
+import { Plugin } from "@tokamakdev/plugin";
+import { defineEvent } from "@tokamakdev/plugin/events";
+/** Runs once per runtime start, including when the system starts the app in the background. */
+export const onStart = defineEvent("start");
+/** Runs each time the app moves into the foreground, but not when it starts there. */
+export const onResume = defineEvent("resume");
+/** Runs each time the app moves out of the foreground. */
+export const onSuspend = defineEvent("suspend");
+/** The functions the runtime answers itself, as the reserved plugin `tokamak`. */
+class Tokamak extends Plugin {
+    constructor() {
+        super("tokamak");
+    }
+    lifecycleStage() {
+        return this.call("lifecycleStage");
+    }
+}
+const tokamak = new Tokamak();
+/**
+ * The app's stage now, which can differ from the last event delivered: an `onSuspend` listener
+ * that runs late reads `"foreground"` once the user has returned. Rejects with
+ * `NotSupportedError` outside a tokamak Worker.
+ */
+export function getLifecycleStage() {
+    return tokamak.lifecycleStage();
+}

package/dist/index.d.mts

@@ -0,0 +1,42 @@
+/** A setting value. */
+export type Value = string | number | boolean;
+/** One platform's settings: the shared keys and the settings its platform pack declares. */
+export interface PlatformConfig {
+    /** Display name. */
+    name?: string;
+    /** Application identifier. */
+    identifier?: string;
+    /** Icon in the platform's format, relative to the Vite root. */
+    icon?: string;
+    /** A setting the platform pack declares; `tok` validates it. */
+    [key: string]: Value | undefined;
+}
+/** One plugin's settings: values for every platform, and each platform's own. */
+export interface PluginConfig {
+    android?: Record<string, Value | undefined>;
+    ios?: Record<string, Value | undefined>;
+    macos?: Record<string, Value | undefined>;
+    windows?: Record<string, Value | undefined>;
+    /** A setting the plugin declares; `tok` validates it. */
+    [key: string]: Value | Record<string, Value | undefined> | undefined;
+}
+/**
+ * The app's tokamak configuration: the tokamak Vite plugin's options other than `module`. Other
+ * keys are plugins' settings, by plugin ID.
+ */
+export interface Config {
+    /** Display name for every platform. */
+    name?: string;
+    /** Application identifier for every platform. */
+    identifier?: string;
+    /** Icon for every platform, relative to the Vite root. */
+    icon?: string;
+    /** App version. */
+    version?: string;
+    android?: PlatformConfig;
+    ios?: PlatformConfig;
+    macos?: PlatformConfig;
+    windows?: PlatformConfig;
+    /** A plugin's settings, by its ID. */
+    [plugin: string]: string | PlatformConfig | PluginConfig | undefined;
+}

package/dist/index.mjs

@@ -0,0 +1 @@
+export {};

package/dist/native.d.mts

@@ -0,0 +1,6 @@
+/**
+ * Defines `__tokamakNativeCall` and `__tokamakNativeListen`, which post to the plugin's loopback
+ * `port` with the session `token`. `waitUntil` keeps each listener's invocation running, as
+ * `waitUntil` from `cloudflare:workers` does.
+ */
+export declare function defineNativeCalls(port: number, token: string, waitUntil: (promise: Promise<unknown>) => void): void;

package/dist/native.mjs

@@ -0,0 +1,73 @@
+// Defines the development Worker's native calls, which reach the device through the tokamak Vite
+// plugin. The plugin's entry Worker transform imports this module in development only.
+/**
+ * Defines `__tokamakNativeCall` and `__tokamakNativeListen`, which post to the plugin's loopback
+ * `port` with the session `token`. `waitUntil` keeps each listener's invocation running, as
+ * `waitUntil` from `cloudflare:workers` does.
+ */
+export function defineNativeCalls(port, token, waitUntil) {
+    const post = async (path, plugin, method, arguments_, signal) => {
+        const response = await fetch(`http://127.0.0.1:${String(port)}${path}`, {
+            method: "POST",
+            headers: { "x-tokamak-session": token },
+            body: JSON.stringify({ plugin, method, arguments: arguments_ }),
+            signal,
+        });
+        if (!response.ok)
+            throw new Error(`the tokamak Vite plugin answered HTTP ${String(response.status)}`);
+        return response;
+    };
+    globalThis.__tokamakNativeCall = async (plugin, method, arguments_ = null) => {
+        let result;
+        try {
+            result = (await (await post("/call", plugin, method, arguments_)).json());
+        }
+        catch (error) {
+            throw networkError(error);
+        }
+        if (result.error)
+            throw new DOMException(result.error.message, result.error.name);
+        return result.value;
+    };
+    globalThis.__tokamakNativeListen = (plugin, method, arguments_, next, error) => {
+        const listening = new AbortController();
+        const deliver = (result) => {
+            try {
+                if (result.error)
+                    error(new DOMException(result.error.message, result.error.name));
+                else
+                    next(result.value);
+            }
+            catch (thrown) {
+                reportError(thrown);
+            }
+        };
+        const listen = async () => {
+            const response = await post("/subscribe", plugin, method, arguments_ ?? null, listening.signal);
+            for await (const result of lines(response))
+                deliver(result);
+        };
+        waitUntil(listen().catch((failure) => {
+            if (!listening.signal.aborted)
+                deliver({ error: networkError(failure), done: true });
+        }));
+        return () => {
+            listening.abort();
+        };
+    };
+}
+/** Each line of `response`'s body, parsed as a result. */
+async function* lines(response) {
+    const decoder = new TextDecoder();
+    let text = "";
+    for await (const chunk of response.body ?? []) {
+        text += decoder.decode(chunk, { stream: true });
+        const complete = text.split("\n");
+        text = complete.pop() ?? "";
+        for (const line of complete)
+            yield JSON.parse(line);
+    }
+}
+function networkError(error) {
+    return new DOMException(`The device could not be reached: ${String(error)}`, "NetworkError");
+}

package/dist/vite.d.mts

@@ -0,0 +1,17 @@
+import { type Plugin } from "vite";
+import type { Config } from "./index.mjs";
+/**
+ * Reports the app's tokamak configuration, and the development server's
+ * address, HTTPS certificate, Worker name and dev socket port, to `tok`, and
+ * makes the entry Worker import `module` and export `TokamakEvents`. In
+ * development, the entry Worker also defines native calls that reach the
+ * device through the dev socket. Without `TOKAMAK_VITE_OUTPUT`, which `tok`
+ * sets, it adds no hooks.
+ */
+export declare function tokamak({ module, ...config }?: Config & {
+    /**
+     * The module the entry Worker imports, relative to the Vite root; by
+     * default `src/tokamak.ts`, then `src/tokamak.js`, when one exists.
+     */
+    module?: string;
+}): Plugin[];

package/dist/vite.mjs

@@ -0,0 +1,213 @@
+import { X509Certificate } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { normalizePath, } from "vite";
+import { openDevSocket } from "./dev-socket.mjs";
+/** Modules tried in order when the options name none. */
+const DEFAULT_MODULES = ["src/tokamak.ts", "src/tokamak.js"];
+/** Wrangler configuration files Cloudflare's plugin tries in order. */
+const WRANGLER_FILES = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
+const MIDDLEWARE_MODE_ERROR = "Vite is running in middleware mode, so tokamak cannot find the development server's address; tok dev needs Vite's own dev server";
+/** The module that defines the development Worker's native calls. */
+const NATIVE_CALLS = normalizePath(fileURLToPath(new URL("./native.mjs", import.meta.url)));
+/**
+ * Reports the app's tokamak configuration, and the development server's
+ * address, HTTPS certificate, Worker name and dev socket port, to `tok`, and
+ * makes the entry Worker import `module` and export `TokamakEvents`. In
+ * development, the entry Worker also defines native calls that reach the
+ * device through the dev socket. Without `TOKAMAK_VITE_OUTPUT`, which `tok`
+ * sets, it adds no hooks.
+ */
+export function tokamak({ module, ...config } = {}) {
+    const output = process.env.TOKAMAK_VITE_OUTPUT;
+    if (!output) {
+        return [];
+    }
+    let file;
+    const events = import.meta.resolve("@tokamakdev/plugin/events");
+    /** The module that defines `TokamakEvents`. */
+    const entrypoint = normalizePath(fileURLToPath(new URL("./entrypoint.js", events)));
+    /** The module that holds event listeners. */
+    const registryFile = normalizePath(fileURLToPath(new URL("./registry.ts", events)));
+    /** The module IDs of each entry environment's inputs. */
+    const entryIds = new Map();
+    /** The entry environments whose input exports `TokamakEvents`. */
+    const exporting = new Set();
+    /** The development server's dev socket, once open. */
+    let devSocket;
+    const token = process.env.TOKAMAK_SESSION_TOKEN;
+    return [
+        {
+            name: "tokamak",
+            // Keeps @tokamakdev/plugin out of pre-bundled dependencies, so they
+            // share the one module that holds event listeners.
+            configEnvironment() {
+                return { optimizeDeps: { exclude: ["@tokamakdev/plugin"] } };
+            },
+            configResolved({ root }) {
+                file = findModule(root, module);
+                writeJson(output, "config.json", { root, config });
+            },
+            // Runs before plugins that load the entry Worker, whose native calls
+            // need the dev socket's port.
+            configureServer: {
+                order: "pre",
+                async handler(server) {
+                    const httpServer = server.httpServer;
+                    // A middleware-mode server beside a reported one, such as the server
+                    // Astro syncs content with, leaves the report in place.
+                    if (!httpServer) {
+                        if (!fs.existsSync(path.join(output, "server.json"))) {
+                            writeJson(output, "server.json", { error: MIDDLEWARE_MODE_ERROR });
+                        }
+                        return;
+                    }
+                    const worker = await readWorker(server.config.root);
+                    const socket = await openDevSocket(worker?.name, token);
+                    devSocket = socket;
+                    httpServer.once("close", () => void socket.close());
+                    httpServer.once("listening", () => {
+                        const urls = server.resolvedUrls;
+                        writeJson(output, "server.json", {
+                            url: urls?.local[0] ?? urls?.network[0],
+                            workerName: worker?.topLevelName ?? worker?.name,
+                            certificates: endEntityCertificates(server.config.server.https),
+                            socketPort: socket.port,
+                        });
+                    });
+                },
+            },
+            async buildApp(builder) {
+                const environments = Object.values(builder.environments);
+                if (!environments.some((environment) => buildsEntryWorker(environment.config))) {
+                    throw new Error("no environment builds the entry Worker to export TokamakEvents from");
+                }
+            },
+        },
+        {
+            name: "tokamak:entry",
+            applyToEnvironment: ({ config }) => buildsEntryWorker(config),
+            async transform(code, id) {
+                const environment = this.environment;
+                const ids = entryIds.get(environment.name) ??
+                    Promise.all(inputs(environment.config.build).map(async (input) => (await this.resolve(input))?.id));
+                entryIds.set(environment.name, ids);
+                if (!(await ids).includes(id)) {
+                    return;
+                }
+                exporting.add(environment.name);
+                // In Cloudflare's Worker entry, which dev and build both start from,
+                // this follows the imports of its polyfills and of the app's entry.
+                const imports = file ? `import ${JSON.stringify(file)};\n` : "";
+                const native = environment.mode === "dev" && devSocket && token ? nativeCalls(devSocket.port, token) : "";
+                return {
+                    code: `${code}\n${imports}export { TokamakEvents } from ${JSON.stringify(entrypoint)};\n${native}`,
+                    map: null,
+                };
+            },
+            // A module that registers listeners adds them again each time it
+            // evaluates, so when an update re-evaluates one, the registry and every
+            // module that imports it evaluate again too.
+            async hotUpdate({ modules, timestamp }) {
+                const graph = this.environment.moduleGraph;
+                const registry = graph.getModuleById(registryFile);
+                if (!registry) {
+                    return;
+                }
+                const entries = (await entryIds.get(this.environment.name)) ?? [];
+                const registering = [...withImporters(registry)].filter((module) => !entries.some((id) => id === module.id));
+                const updated = new Set(modules.flatMap((changed) => [...withImporters(changed)]));
+                if (registering.some((module) => updated.has(module))) {
+                    graph.invalidateModule(registry, new Set(), timestamp, true);
+                }
+            },
+            generateBundle() {
+                if (!exporting.has(this.environment.name)) {
+                    this.error(`the input of the ${this.environment.name} environment did not export TokamakEvents`);
+                }
+            },
+        },
+    ];
+}
+/**
+ * Code that defines the development Worker's native calls on the dev socket's
+ * `port`, with the session `token`, which only the entry Worker's environment
+ * sees.
+ */
+function nativeCalls(port, token) {
+    return `import { waitUntil as __tokamakWaitUntil } from "cloudflare:workers";
+import { defineNativeCalls as __tokamakDefineNativeCalls } from ${JSON.stringify(NATIVE_CALLS)};
+__tokamakDefineNativeCalls(${String(port)}, ${JSON.stringify(token)}, __tokamakWaitUntil);
+`;
+}
+/** `module` and every module that imports it, directly or through others. */
+function withImporters(module) {
+    const found = new Set();
+    const pending = [module];
+    for (let current = pending.pop(); current; current = pending.pop()) {
+        if (!found.has(current)) {
+            found.add(current);
+            pending.push(...current.importers);
+        }
+    }
+    return found;
+}
+/** The module `name` under `root`, or else the first default under `root` that exists. */
+function findModule(root, name) {
+    const candidates = (name ? [name] : DEFAULT_MODULES).map((candidate) => normalizePath(path.resolve(root, candidate)));
+    const file = candidates.find((candidate) => fs.existsSync(candidate));
+    if (name && !file) {
+        throw new Error(`tokamak module not found: ${candidates[0]}`);
+    }
+    return file;
+}
+/**
+ * The Worker in the Wrangler configuration file in `root`, read as
+ * Cloudflare's plugin reads it without `configPath`, in the `CLOUDFLARE_ENV`
+ * environment: its name, and its name without the environment's suffix.
+ */
+async function readWorker(root) {
+    const file = WRANGLER_FILES.map((name) => path.join(root, name)).find((candidate) => fs.existsSync(candidate));
+    if (!file) {
+        return undefined;
+    }
+    const { unstable_readConfig } = await import("wrangler");
+    return unstable_readConfig({ config: file, env: process.env.CLOUDFLARE_ENV }, { hideWarnings: true });
+}
+/**
+ * The PEM of the end-entity certificate of each chain in `https.cert`, which
+ * Vite reads from a file when a string names one.
+ */
+function endEntityCertificates(https) {
+    const cert = typeof https?.cert === "string" ? readFileIfExists(https.cert) : https?.cert;
+    return cert && [cert].flat().map((chain) => new X509Certificate(chain).toString()).join("");
+}
+function readFileIfExists(file) {
+    try {
+        return fs.readFileSync(path.resolve(file));
+    }
+    catch {
+        return file;
+    }
+}
+/**
+ * Whether an environment builds from the entry Worker: Cloudflare's plugin
+ * gives a manifest to its entry and prerender Workers, and Astro to its server
+ * and prerender environments.
+ */
+function buildsEntryWorker(config) {
+    return config.consumer === "server" && Boolean(config.build.manifest);
+}
+/** The modules an environment's build starts from. */
+function inputs(build) {
+    const { input } = build.rollupOptions;
+    return typeof input === "string" ? [input] : Object.values(input ?? {});
+}
+/** Writes `value` to `name` whole, as `tok` reads the file as soon as it exists. */
+function writeJson(output, name, value) {
+    const file = path.join(output, name);
+    fs.mkdirSync(output, { recursive: true });
+    fs.writeFileSync(`${file}.tmp`, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(`${file}.tmp`, file);
+}

package/package.json

@@ -1,28 +1,80 @@
 {
   "name": "@tokamakdev/tok",
-  "version": "0.1.0-beta.37",
-  "description": "The tokamak CLI: build native apps from a Cloudflare Workers codebase",
+  "version": "0.1.1-beta.100",
+  "description": "The tokamak CLI, Vite plugin and app API: build native apps from a Cloudflare Workers codebase",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mantty/tokamak.git",
     "directory": "tokamak-cli/npm"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./events": {
+      "types": "./dist/events.d.mts",
+      "default": "./dist/events.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "default": "./dist/vite.mjs"
+    }
+  },
   "bin": {
     "tok": "bin/tok.js"
   },
   "files": [
     "bin",
+    "dist",
     "platform.js",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "node --test"
+  },
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "@tokamakdev/plugin": "0.1.0-beta.100",
+    "ws": "^8.22.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/vite-plugin": "^1.54.0",
+    "vite": "^7.0.0 || ^8.0.0",
+    "wrangler": "^4.126.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/vite-plugin": {
+      "optional": true
+    },
+    "wrangler": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "1.62.5",
+    "@types/node": "22.19.15",
+    "@types/ws": "8.18.2",
+    "typescript": "5.9.3",
+    "vite": "8.3.2",
+    "wrangler": "4.147.0"
+  },
   "optionalDependencies": {
-    "@tokamakdev/tok-darwin-arm64": "0.1.0-beta.37",
-    "@tokamakdev/tok-darwin-x64": "0.1.0-beta.37",
-    "@tokamakdev/tok-linux-x64": "0.1.0-beta.37",
-    "@tokamakdev/tok-win32-x64": "0.1.0-beta.37"
+    "@tokamakdev/platform-android-arm64": "0.1.1-beta.100",
+    "@tokamakdev/platform-ios-arm64": "0.1.1-beta.100",
+    "@tokamakdev/platform-ios-simulator-arm64": "0.1.1-beta.100",
+    "@tokamakdev/platform-ios-simulator-x64": "0.1.1-beta.100",
+    "@tokamakdev/platform-macos-arm64": "0.1.1-beta.100",
+    "@tokamakdev/platform-macos-x64": "0.1.1-beta.100",
+    "@tokamakdev/platform-windows-x64": "0.1.1-beta.100",
+    "@tokamakdev/tok-darwin-arm64": "0.1.1-beta.100",
+    "@tokamakdev/tok-darwin-x64": "0.1.1-beta.100",
+    "@tokamakdev/tok-linux-x64": "0.1.1-beta.100",
+    "@tokamakdev/tok-win32-x64": "0.1.1-beta.100"
   },
   "publishConfig": {
     "access": "public"

package/platform.js

@@ -1,5 +1,8 @@
 "use strict";
 
+const path = require("node:path");
+const { optionalDependencies } = require("./package.json");
+
 const PACKAGES = {
   "darwin-arm64": "@tokamakdev/tok-darwin-arm64",
   "darwin-x64": "@tokamakdev/tok-darwin-x64",
@@ -7,6 +10,8 @@ const PACKAGES = {
   "win32-x64": "@tokamakdev/tok-win32-x64",
 };
 
+const PLATFORM_PACKS = Object.keys(optionalDependencies).filter((name) => name.startsWith("@tokamakdev/platform-"));
+
 function packageFor(platform, arch) {
   const name = PACKAGES[`${platform}-${arch}`];
   if (!name) throw new Error(`tokamak does not publish a CLI for ${platform} ${arch}`);
@@ -23,4 +28,15 @@ function binaryPath(platform, arch, resolve) {
   }
 }
 
-module.exports = { packageFor, binaryPath };
+// npm installs only the platform packs whose os and cpu match this host.
+function platformPackRoots(resolve) {
+  return PLATFORM_PACKS.flatMap((name) => {
+    try {
+      return [path.dirname(resolve(`${name}/package.json`))];
+    } catch {
+      return [];
+    }
+  });
+}
+
+module.exports = { PLATFORM_PACKS, packageFor, binaryPath, platformPackRoots };