@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/plugin/sandbox-worker.js

@@ -0,0 +1,194 @@
+// ============================================================================
+// Sandbox worker entry — runs inside a dedicated Web Worker per worker-js
+// plugin. Receives an init message with the plugin entry URL + granted
+// permissions, restricts globals, then imports the entry and calls its
+// register() with a bridge-backed context.
+//
+// Bridge model: every host capability crosses the boundary as an async
+// `__bridgeCall`/`__bridgeResponse` pair correlated by `callId`. The host
+// side enforces an allowlist of methods and each context API enforces the
+// plugin's permission grant — this worker just forwards calls.
+//
+// This file is the worker entry. The host spawns it with:
+//   new Worker(new URL("./sandbox-worker.ts", import.meta.url), { type: "module" })
+// (the loader does this inline per the BaseWorkerHost Vite rule).
+// ============================================================================
+import { restrictGlobals } from "./sandbox-shim.js";
+// ── Bridge call machinery ──
+let contextId = "";
+let nextCallId = 1;
+const pendingCalls = new Map();
+/** Invoke an allowlisted host method. Awaits the host's response. */
+function bridgeCall(method, args) {
+    const callId = nextCallId++;
+    return new Promise((resolve, reject) => {
+        pendingCalls.set(callId, { resolve, reject });
+        self.postMessage({ __bridgeCall: true, contextId, callId, method, args });
+    });
+}
+/** Fire-and-forget bridge call (publish, subscribe — no meaningful result). */
+function bridgeNotify(method, args) {
+    self.postMessage({ __bridgeCall: true, contextId, method, args });
+}
+// ── Worker-local state ──
+const tickCallbacks = new Set();
+const disposeCallbacks = [];
+const eventHandlers = new Map();
+/** Local KV mirror — get/set/delete/keys are synchronous; save()/load()
+ *  round-trip to the host's store via the bridge. */
+const localState = new Map();
+// ── Message handling ──
+self.addEventListener("message", (ev) => {
+    const msg = ev.data;
+    if (!msg)
+        return;
+    if (msg.__sandboxInit) {
+        void runPlugin(msg);
+        return;
+    }
+    if (msg.__bridgeResponse) {
+        const pending = pendingCalls.get(msg.callId);
+        if (pending) {
+            pendingCalls.delete(msg.callId);
+            if (msg.error !== undefined) {
+                pending.reject(new Error(msg.error));
+            }
+            else {
+                pending.resolve(msg.result);
+            }
+        }
+        return;
+    }
+    // Host-driven tick → ctx.tick.onTick callbacks.
+    if (msg.__tick) {
+        for (const cb of tickCallbacks.values())
+            cb(msg.dt, msg.elapsedTime);
+        return;
+    }
+    // Host-published event → local subscribers (registered via ctx.events.subscribe).
+    if (msg.__event) {
+        const set = eventHandlers.get(msg.event);
+        if (set)
+            for (const h of set.values())
+                h(msg.data);
+        return;
+    }
+    if (msg.__dispose) {
+        disposeCallbacks.forEach((cb) => {
+            try {
+                cb();
+            }
+            catch { /* dispose errors are non-fatal */ }
+        });
+        return;
+    }
+});
+async function runPlugin(init) {
+    try {
+        contextId = init.contextId;
+        // 1. Restrict globals based on granted permissions.
+        restrictGlobals(new Set(init.granted));
+        // 2. Build the bridge-backed context and expose it as `ddPlugin`.
+        const ctx = makeBridgeContext(init.contextId, new Set(init.granted));
+        self.ddPlugin = { ctx };
+        // 3. Dynamically import the plugin entry. @vite-ignore because the URL is
+        //    dynamic (not statically analyzable).
+        const mod = await import(/* @vite-ignore */ init.entryUrl);
+        const entry = mod.default ?? mod;
+        if (typeof entry.register !== "function") {
+            throw new Error(`Plugin entry "${init.entryUrl}" has no register() function`);
+        }
+        // 4. Call register.
+        await entry.register(ctx);
+        // 5. Notify host that registration completed.
+        self.postMessage({ __sandboxReady: true, contextId: init.contextId });
+    }
+    catch (e) {
+        // Report failures so the host's ready-wait rejects instead of hanging.
+        const err = e;
+        self.postMessage({
+            __sandboxError: true,
+            contextId: init.contextId,
+            error: `${err.message}\n${err.stack ?? ""}`,
+        });
+    }
+}
+/** Permissions that map to host-call methods (game mutation API). */
+const HOST_CALL_PERMS = ["assets", "ecs", "physics"];
+const HOST_CALL_METHODS = [
+    "spawnProp",
+    "removeProp",
+    "setPhysics",
+    "getPhysics",
+    "applyImpulse",
+    "applyTorque",
+    "getAssetRef",
+];
+/** Build a ScriptPluginContext that forwards calls to the host via postMessage. */
+function makeBridgeContext(pluginId, granted) {
+    const ctx = {
+        id: pluginId,
+        events: {
+            subscribe(event, handler) {
+                let set = eventHandlers.get(event);
+                if (!set) {
+                    set = new Set();
+                    eventHandlers.set(event, set);
+                    // First local subscriber for this event — subscribe host-side too.
+                    bridgeNotify("events.subscribe", [event]);
+                }
+                set.add(handler);
+                return () => set.delete(handler);
+            },
+            publish(event, data) {
+                // Route through the host's shared bus — it echoes back to every
+                // subscriber (including this worker's own, if subscribed), so
+                // publish semantics match the in-process bus exactly.
+                bridgeNotify("events.publish", [event, data]);
+            },
+        },
+        state: {
+            get: (key) => localState.get(key),
+            set: (key, value) => { localState.set(key, value); },
+            delete: (key) => { localState.delete(key); },
+            keys: () => [...localState.keys()],
+            // Persist to the host's store (storage permission enforced host-side).
+            save: async () => { await bridgeCall("state.save", [[...localState.entries()]]); },
+            load: async () => {
+                const entries = (await bridgeCall("state.load", []));
+                if (entries) {
+                    localState.clear();
+                    entries.forEach(([k, v]) => { localState.set(k, v); ; });
+                }
+            },
+        },
+        tick: {
+            onTick(fn) {
+                const wrapped = (dt, t) => fn(dt, t);
+                tickCallbacks.add(wrapped);
+                return () => tickCallbacks.delete(wrapped);
+            },
+        },
+        log: {
+            info: (m) => self.postMessage({ __pluginLog: true, level: "info", msg: m }),
+            warn: (m) => self.postMessage({ __pluginLog: true, level: "warn", msg: m }),
+            error: (m) => self.postMessage({ __pluginLog: true, level: "error", msg: m }),
+            debug: (m) => self.postMessage({ __pluginLog: true, level: "debug", msg: m }),
+        },
+        onDispose: (fn) => disposeCallbacks.push(fn),
+    };
+    // Expose the host-call bridge when the plugin was granted any host-call
+    // permission. Each method forwards over the bridge; the host enforces the
+    // allowlist + per-method permission gate. Script-tier contexts reject with
+    // "not available on this context".
+    const hasHostCallPerm = HOST_CALL_PERMS.some((p) => granted.has(p));
+    if (hasHostCallPerm) {
+        const hostCalls = {};
+        HOST_CALL_METHODS.forEach((m) => {
+            hostCalls[m] = (...args) => bridgeCall(m, args);
+        });
+        ctx.hostCalls =
+            hostCalls;
+    }
+    return ctx;
+}

package/dist/core/src/plugin/wasm-abi.js

@@ -0,0 +1,62 @@
+// ============================================================================
+// WASM plugin ABI v3 — the contract between the host and WASM plugin modules.
+//
+// WASM plugins always run in their own dedicated worker (stability isolation).
+// The ABI uses WebAssembly linear memory for string/data passing:
+//   - The host provides an `env` import module with functions for logging,
+//     state access, event publishing, and game mutation (host calls).
+//   - The plugin exports `register`, and optionally `tick`, `dispose`,
+//     `on_event`, and `alloc` (for the host to allocate strings in the
+//     plugin's memory).
+//
+// v3 adds host-call imports for game mutation (spawn_prop, remove_prop,
+// set_physics, get_physics, apply_impulse, apply_torque, get_asset_ref).
+// These are async on the host side (forwarded to the game's PluginHostCalls);
+// the host-call imports return a u32 request id, and the host posts the
+// result back via the `on_host_call_result` export (ptr+len for JSON result,
+// or 0 for void / error). v2 imports are unchanged — a v2 plugin works as-is.
+//
+// All string/data passing uses (ptr, len) pairs into the plugin's linear
+// memory. The host calls `alloc(size)` to get a pointer, writes the data,
+// then calls the plugin function.
+// ============================================================================
+/** ABI version — incremented on breaking changes. v3 adds host-call imports. */
+export const WASM_PLUGIN_ABI_VERSION = 3;
+/** Helper: write a string into the plugin's linear memory.
+ *  Returns [ptr, len] or null if alloc failed. */
+export function writeStringToMemory(exports, str) {
+    if (!exports.memory || !exports.alloc)
+        return null;
+    const encoder = new TextEncoder();
+    const bytes = encoder.encode(str);
+    const ptr = exports.alloc(bytes.length);
+    if (ptr === 0)
+        return null;
+    const view = new Uint8Array(exports.memory.buffer, ptr, bytes.length);
+    view.set(bytes);
+    return [ptr, bytes.length];
+}
+/** Helper: read a string from the plugin's linear memory. */
+export function readStringFromMemory(exports, ptr, len) {
+    if (!exports.memory)
+        return "";
+    const view = new Uint8Array(exports.memory.buffer, ptr, len);
+    return new TextDecoder().decode(view);
+}
+/** Helper: write a byte array into the plugin's linear memory. */
+export function writeBytesToMemory(exports, bytes) {
+    if (!exports.memory || !exports.alloc)
+        return null;
+    const ptr = exports.alloc(bytes.length);
+    if (ptr === 0)
+        return null;
+    const view = new Uint8Array(exports.memory.buffer, ptr, bytes.length);
+    view.set(bytes);
+    return [ptr, bytes.length];
+}
+/** Helper: read a byte array from the plugin's linear memory. */
+export function readBytesFromMemory(exports, ptr, len) {
+    if (!exports.memory)
+        return new Uint8Array(0);
+    return new Uint8Array(exports.memory.buffer, ptr, len).slice();
+}

package/dist/core/src/plugin/wasm-worker.js

@@ -0,0 +1,234 @@
+// ============================================================================
+// WASM worker entry — runs inside a dedicated Web Worker per WASM plugin.
+//
+// Receives an init message with the WASM module URL, fetches + instantiates
+// it with the host import module, calls register(), and forwards tick/dispose.
+// ============================================================================
+import { getWarningEngine, METRIC_TASK_LATENCY, recordTaskLatency } from "../profiling/worker-prelude.js";
+import { readStringFromMemory, WASM_PLUGIN_ABI_VERSION, writeBytesToMemory } from "./wasm-abi.js";
+let exports = { alloc: () => 0, register: () => { } };
+let _subscriptions = new Map();
+self.onmessage = async (ev) => {
+    const msg = ev.data;
+    if (msg?.__wasmInit) {
+        await initPlugin(msg.entryUrl, msg.pluginId);
+    }
+    if (msg?.__wasmDispose) {
+        try {
+            exports.dispose?.();
+        }
+        catch { /* */ }
+        self.postMessage({ __wasmDisposed: true });
+    }
+    if (msg?.__wasmTick) {
+        if (typeof exports.tick === "function") {
+            const tickStart = performance.now();
+            exports.tick(msg.dt, msg.elapsedTime);
+            const durationUs = (performance.now() - tickStart) * 1000;
+            recordTaskLatency("wasm", durationUs, "tick");
+            getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+        }
+    }
+    if (msg?.__wasmEvent) {
+        if (typeof exports.on_event === "function") {
+            const json = JSON.stringify(msg.data);
+            const [ptr, len] = writeBytesToMemory(exports, new TextEncoder().encode(json)) ?? [0, 0];
+            if (ptr !== 0) {
+                const evtStart = performance.now();
+                exports.on_event(msg.subId, ptr, len);
+                const durationUs = (performance.now() - evtStart) * 1000;
+                recordTaskLatency("wasm", durationUs, "on_event");
+                getWarningEngine()?.checkInstant(METRIC_TASK_LATENCY, durationUs);
+            }
+        }
+    }
+};
+async function initPlugin(entryUrl, pluginId) {
+    try {
+        const resp = await fetch(entryUrl);
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}`);
+        const bytes = new Uint8Array(await resp.arrayBuffer());
+        // Build host imports — the worker forwards calls to the host via postMessage.
+        const imports = buildWorkerImports();
+        const result = await WebAssembly.instantiate(bytes, imports);
+        exports = resolveExports(result.instance);
+        // Hydrate the state mirror before register() so synchronous state_get
+        // sees persisted values.
+        await hydrateState();
+        if (typeof exports.register !== "function") {
+            throw new Error("WASM module has no register() export");
+        }
+        exports.register();
+        self.postMessage({ __wasmReady: true, pluginId, abiVersion: WASM_PLUGIN_ABI_VERSION });
+    }
+    catch (e) {
+        self.postMessage({ __wasmError: true, pluginId, error: e.message });
+    }
+}
+function resolveExports(instance) {
+    const exp = instance.exports;
+    return {
+        alloc: exp.alloc,
+        register: exp.register,
+        tick: exp.tick,
+        dispose: exp.dispose,
+        on_event: exp.on_event,
+        memory: exp.memory,
+    };
+}
+// Local state mirror — WASM state_get is synchronous, so the worker keeps a
+// KV mirror populated at init (via a bridge "state.load") and mutated locally
+// on state_set/delete. Persistence goes through the bridge.
+const localState = new Map();
+let stateHydrated = false;
+async function hydrateState() {
+    if (stateHydrated)
+        return;
+    try {
+        await bridgeCall("state.load", []);
+        const keys = (await bridgeCall("state.keys", []));
+        if (Array.isArray(keys)) {
+            for (let _i = 0, _it = keys, _n = _it.length; _i < _n; _i++) {
+                const k = _it[_i];
+                localState.set(k, await bridgeCall("state.get", [k]));
+            }
+        }
+    }
+    catch { /* state unavailable — empty mirror is fine */ }
+    stateHydrated = true;
+}
+function bridgeCall(method, args) {
+    return new Promise((resolve, reject) => {
+        const callId = Math.random().toString(36).slice(2);
+        const handler = (ev) => {
+            const msg = ev.data;
+            if (msg?.__wasmBridgeResult && msg.callId === callId) {
+                self.removeEventListener("message", handler);
+                if (msg.error)
+                    reject(new Error(msg.error));
+                else
+                    resolve(msg.result);
+            }
+        };
+        self.addEventListener("message", handler);
+        self.postMessage({ __wasmBridge: true, method, args, callId });
+    });
+}
+function buildWorkerImports() {
+    const readStr = (ptr, len) => readStringFromMemory(exports, ptr, len);
+    let nextReqId = 1;
+    // Host-call result delivery mirrors loader-wasm's dispatchHostCall: resolve
+    // the bridge call, then write the JSON result into wasm memory and invoke
+    // the plugin's on_host_call_result export.
+    const dispatchHostCall = (p, requestId) => {
+        p.then((result) => {
+            const exp = exports;
+            if (!exp.on_host_call_result)
+                return;
+            if (result === undefined) {
+                exp.on_host_call_result(requestId, 0, 0, 0, 0);
+            }
+            else {
+                const json = JSON.stringify(result);
+                const [ptr, len] = writeBytesToMemory(exp, new TextEncoder().encode(json)) ?? [0, 0];
+                exp.on_host_call_result(requestId, ptr, len, 0, 0);
+            }
+        }).catch((err) => {
+            const exp = exports;
+            if (!exp.on_host_call_result)
+                return;
+            const [ptr, len] = writeBytesToMemory(exp, new TextEncoder().encode(err.message)) ?? [0, 0];
+            exp.on_host_call_result(requestId, 0, 0, ptr, len);
+        });
+    };
+    const hostCall = (method, args) => {
+        const reqId = nextReqId++;
+        dispatchHostCall(bridgeCall("hostCall", [method, ...args]), reqId);
+        return reqId;
+    };
+    return {
+        env: {
+            log_info: (ptr, len) => { void bridgeCall("log", ["info", readStr(ptr, len)]); },
+            log_warn: (ptr, len) => { void bridgeCall("log", ["warn", readStr(ptr, len)]); },
+            log_error: (ptr, len) => { void bridgeCall("log", ["error", readStr(ptr, len)]); },
+            log_debug: (ptr, len) => { void bridgeCall("log", ["debug", readStr(ptr, len)]); },
+            state_get: (keyPtr, keyLen) => {
+                const key = readStr(keyPtr, keyLen);
+                const val = localState.get(key);
+                if (val === undefined)
+                    return 0;
+                const json = JSON.stringify(val);
+                const [ptr, len] = writeBytesToMemory(exports, new TextEncoder().encode(json)) ?? [0, 0];
+                if (ptr === 0)
+                    return 0;
+                const mem = exports.memory;
+                const dv = new DataView(mem.buffer, ptr - 4, 4);
+                dv.setUint32(0, len, true);
+                return ptr;
+            },
+            state_set: (keyPtr, keyLen, valPtr, valLen) => {
+                const key = readStr(keyPtr, keyLen);
+                const json = readStr(valPtr, valLen);
+                let val = json;
+                try {
+                    val = JSON.parse(json);
+                }
+                catch { /* raw string */ }
+                localState.set(key, val);
+                void bridgeCall("state.set", [key, val]);
+            },
+            state_delete: (keyPtr, keyLen) => {
+                const key = readStr(keyPtr, keyLen);
+                localState.delete(key);
+                void bridgeCall("state.delete", [key]);
+            },
+            event_publish: (namePtr, nameLen, dataPtr, dataLen) => {
+                const name = readStr(namePtr, nameLen);
+                const data = readStr(dataPtr, dataLen);
+                let parsed = data;
+                try {
+                    parsed = JSON.parse(data);
+                }
+                catch { /* raw string */ }
+                void bridgeCall("events.publish", [name, parsed]);
+            },
+            event_subscribe: (namePtr, nameLen) => {
+                const name = readStr(namePtr, nameLen);
+                const subId = _subscriptions.size + 1;
+                _subscriptions.set(subId, () => { });
+                void bridgeCall("events.subscribe", [name, subId]);
+                return subId;
+            },
+            event_unsubscribe: (subId) => {
+                _subscriptions.delete(subId);
+                void bridgeCall("events.unsubscribe", [subId]);
+            },
+            // ── Host-call bridge (v3) — forwarded to the host's NativePluginContext
+            // bridge; results arrive via on_host_call_result. ──
+            spawn_prop: (contentIdPtr, contentIdLen, x, y, z, qx, qy, qz, qw, scale) => hostCall("spawnProp", [{
+                    contentId: readStr(contentIdPtr, contentIdLen),
+                    position: [x, y, z],
+                    rotation: [qx, qy, qz, qw],
+                    scale,
+                }]),
+            remove_prop: (entityId) => hostCall("removeProp", [entityId]),
+            set_physics: (entityId, mass, restitution, friction, gravityScale) => {
+                const desc = {};
+                if (!Number.isNaN(mass))
+                    desc.mass = mass;
+                if (!Number.isNaN(restitution))
+                    desc.restitution = restitution;
+                if (!Number.isNaN(friction))
+                    desc.friction = friction;
+                if (!Number.isNaN(gravityScale))
+                    desc.gravityScale = gravityScale;
+                return hostCall("setPhysics", [entityId, desc]);
+            },
+            get_physics: (entityId) => hostCall("getPhysics", [entityId]),
+            apply_impulse: (entityId, x, y, z) => hostCall("applyImpulse", [entityId, [x, y, z]]),
+            apply_torque: (entityId, x, y, z) => hostCall("applyTorque", [entityId, [x, y, z]]),
+            get_asset_ref: (assetIdPtr, assetIdLen) => hostCall("getAssetRef", [readStr(assetIdPtr, assetIdLen)]),
+        },
+    };
+}

package/dist/core/src/plugin/workshop.js

@@ -0,0 +1,131 @@
+// ============================================================================
+// Workshop — remote plugin pack discovery, fetch, and cache.
+//
+// A workshop source is an `AssetManifest` (with a `plugins: PluginPackEntry[]`
+// section) served from a BlobStore. The workshop fetcher:
+//   1. Downloads the manifest from the configured store.
+//   2. For each plugin pack entry, fetches the `plugin.json` + declared asset
+//      files, caches them under `<cacheDir>/<id>@<version>/`.
+//   3. Returns the validated `PluginManifest` + the local cache path so the
+//      PluginHost can `discover()` it with source "workshop".
+//
+// Subscription state (which packs are enabled) is persisted via the provided
+// persistence hook (OPFS in production; in-memory in tests).
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+import { validateManifest, } from "../assets/manifest.js";
+import { validatePluginManifest } from "./manifest.js";
+const log = createLogger("info");
+export class WorkshopFetcher {
+    sources = [];
+    opts;
+    /** id → cache path for fetched packs. */
+    cache = new Map();
+    constructor(opts) {
+        this.opts = opts;
+    }
+    addSource(source) {
+        this.sources.push(source);
+    }
+    /**
+     * Fetch all workshop sources, download plugin packs, cache them, and return
+     * validated manifests. Only packs in the subscription list are fetched
+     * (if subscriptions are configured); otherwise all packs in the manifest.
+     */
+    async fetchAll() {
+        const manifests = [];
+        const errors = [];
+        const subscribed = this.opts.loadSubscriptions ? await this.opts.loadSubscriptions() : null;
+        for (let _i = 0, _it = this.sources, _n = _it.length; _i < _n; _i++) {
+            const source = _it[_i];
+            let rawManifest;
+            try {
+                rawManifest = await source.store.get(source.manifestKey);
+            }
+            catch (e) {
+                log.error("workshop-fetcher", `Failed to fetch workshop manifest: ${e.message}`);
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(new TextDecoder().decode(rawManifest));
+            }
+            catch (e) {
+                log.error("workshop-fetcher", `Workshop manifest is not valid JSON: ${e.message}`);
+                continue;
+            }
+            if (!validateManifest(parsed)) {
+                log.error("workshop-fetcher", `Workshop manifest failed schema validation`);
+                continue;
+            }
+            const assetManifest = parsed;
+            const pluginEntries = assetManifest.plugins ?? [];
+            for (let _i = 0, _it = pluginEntries, _n = _it.length; _i < _n; _i++) {
+                const entry = _it[_i];
+                if (subscribed && !subscribed.includes(entry.id))
+                    continue;
+                try {
+                    const result = await this.fetchPack(source, entry);
+                    if (result)
+                        manifests.push(result);
+                }
+                catch (e) {
+                    errors.push({ id: entry.id, error: e.message });
+                }
+            }
+        }
+        return { manifests, errors };
+    }
+    /** Fetch a single plugin pack: download plugin.json + cache the pack. */
+    async fetchPack(source, entry) {
+        const cachePath = `${this.opts.cacheDir}/${entry.id}@${entry.version}`;
+        // Fetch plugin.json from the store.
+        const pluginJsonKey = `${entry.path}/plugin.json`;
+        let pluginJsonBytes;
+        try {
+            pluginJsonBytes = await source.store.get(pluginJsonKey);
+        }
+        catch (e) {
+            throw new Error(`Failed to fetch plugin.json for "${entry.id}": ${e.message}`);
+        }
+        let pluginRaw;
+        try {
+            pluginRaw = JSON.parse(new TextDecoder().decode(pluginJsonBytes));
+        }
+        catch (e) {
+            throw new Error(`plugin.json for "${entry.id}" is not valid JSON: ${e.message}`);
+        }
+        const v = validatePluginManifest(pluginRaw);
+        if (!v.valid) {
+            throw new Error(`plugin.json for "${entry.id}" failed validation: ${v.errors.join("; ")}`);
+        }
+        const manifest = v.normalized;
+        // Verify the manifest id matches the entry id.
+        if (manifest.id !== entry.id) {
+            throw new Error(`Workshop entry id "${entry.id}" does not match plugin.json id "${manifest.id}"`);
+        }
+        this.cache.set(entry.id, cachePath);
+        // Note: actual asset files are fetched lazily by the AssetPluginLoader
+        // via the BlobStore (or eagerly if the game wires a prefetch). The cache
+        // path is exposed so the loader's `resolveBase` can point at it.
+        return { manifest, cachePath };
+    }
+    /** Get the cache path for a fetched plugin id. */
+    getCachePath(id) {
+        return this.cache.get(id);
+    }
+    /** Enable a plugin subscription (persisted). */
+    async subscribe(id) {
+        const current = this.opts.loadSubscriptions ? await this.opts.loadSubscriptions() : [];
+        if (!current.includes(id)) {
+            current.push(id);
+            await this.opts.saveSubscriptions?.(current);
+        }
+    }
+    /** Remove a plugin subscription (persisted). */
+    async unsubscribe(id) {
+        const current = this.opts.loadSubscriptions ? await this.opts.loadSubscriptions() : [];
+        const next = current.filter((x) => x !== id);
+        await this.opts.saveSubscriptions?.(next);
+    }
+}