@burmese/plugin-sdk 3.1.0

package/dist/testing.js

@@ -0,0 +1,645 @@
+const allowedReactions = new Set(["idle", "thinking", "working", "editing", "running", "testing", "waiting", "waving", "success", "error", "celebrating"]);
+function assertReaction(value) {
+    if (typeof value !== "string" || !allowedReactions.has(value))
+        throw new Error("Invalid pet reaction.");
+}
+// ---------------------------------------------------------------------------
+// Fake clock
+// ---------------------------------------------------------------------------
+export class FakeClock {
+    #nowMs;
+    #schedules;
+    #onError;
+    constructor(nowMs, schedules, onError) {
+        this.#nowMs = nowMs;
+        this.#schedules = schedules;
+        this.#onError = onError;
+    }
+    now() {
+        return this.#nowMs;
+    }
+    /** Advance virtual time, firing due schedules in order. Accepts ms or "30s"/"90m"/"2h"/"1d". */
+    async advance(amount) {
+        const target = this.#nowMs + parseDuration(amount);
+        for (;;) {
+            let nextId;
+            let nextDue = Number.POSITIVE_INFINITY;
+            for (const [id, schedule] of this.#schedules) {
+                if (schedule.dueMs <= target && schedule.dueMs < nextDue) {
+                    nextDue = schedule.dueMs;
+                    nextId = id;
+                }
+            }
+            if (nextId === undefined)
+                break;
+            const schedule = this.#schedules.get(nextId);
+            this.#nowMs = Math.max(this.#nowMs, schedule.dueMs);
+            if (schedule.type === "once" || schedule.type === "at")
+                this.#schedules.delete(nextId);
+            else if (schedule.type === "every")
+                schedule.dueMs += schedule.intervalMs ?? 60_000;
+            else if (schedule.type === "daily")
+                schedule.dueMs = nextDailyRunMs(schedule.daily, this.#nowMs);
+            else
+                schedule.dueMs = nextCronRunMs(schedule.cronExpr, this.#nowMs) ?? Number.POSITIVE_INFINITY;
+            try {
+                await schedule.handler();
+            }
+            catch (error) {
+                this.#onError(error instanceof Error ? error.message : String(error));
+            }
+        }
+        this.#nowMs = target;
+    }
+    computeDue(schedule) {
+        if (schedule.type === "every")
+            return this.#nowMs + (schedule.intervalMs ?? 60_000);
+        if (schedule.type === "daily")
+            return nextDailyRunMs(schedule.daily, this.#nowMs);
+        if (schedule.type === "cron")
+            return nextCronRunMs(schedule.cronExpr, this.#nowMs) ?? Number.POSITIVE_INFINITY;
+        return this.#nowMs + (schedule.intervalMs ?? 0);
+    }
+}
+/** Replace `{name}` placeholders, mirroring the host catalog's `interpolate`. */
+function interpolateVars(template, vars) {
+    if (!vars)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (whole, key) => (key in vars ? String(vars[key]) : whole));
+}
+function parseDuration(amount) {
+    if (typeof amount === "number")
+        return amount;
+    const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d)$/.exec(amount.trim());
+    if (!match)
+        throw new Error(`Invalid duration: ${amount}`);
+    const value = Number(match[1]);
+    const unit = match[2];
+    return value * { ms: 1, s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
+}
+function nextDailyRunMs(spec, fromMs) {
+    const [hour, minute] = spec.time.split(":").map(Number);
+    const from = new Date(fromMs);
+    for (let add = 0; add <= 7; add += 1) {
+        const next = new Date(fromMs);
+        next.setDate(from.getDate() + add);
+        next.setHours(hour ?? 0, minute ?? 0, 0, 0);
+        if (next.getTime() > fromMs && (!spec.days || spec.days.includes(next.getDay())))
+            return next.getTime();
+    }
+    return fromMs + 86_400_000;
+}
+/** Minimal 5-field cron next-run (m h dom mon dow), mirroring the host scheduler. */
+export function nextCronRunMs(expr, fromMs) {
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        throw new Error("Cron expressions must have 5 fields.");
+    const [minutes, hours, dom, months, dow] = fields.map((field, index) => {
+        const ranges = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+        const [min, max] = ranges[index];
+        const values = new Set();
+        for (const part of field.split(",")) {
+            const stepMatch = /^(.+)\/(\d+)$/.exec(part);
+            const base = stepMatch ? stepMatch[1] : part;
+            const step = stepMatch ? Number(stepMatch[2]) : 1;
+            let start = min;
+            let end = max;
+            if (base !== "*") {
+                const range = /^(\d+)-(\d+)$/.exec(base);
+                if (range) {
+                    start = Number(range[1]);
+                    end = Number(range[2]);
+                }
+                else {
+                    start = Number(base);
+                    end = stepMatch ? max : start;
+                }
+            }
+            if (!Number.isInteger(start) || !Number.isInteger(end) || start < min || end > max || start > end)
+                throw new Error("Invalid cron field.");
+            for (let value = start; value <= end; value += step)
+                values.add(index === 4 && value === 7 ? 0 : value);
+        }
+        return values;
+    });
+    const domWildcard = fields[2] === "*";
+    const dowWildcard = fields[4] === "*";
+    const candidate = new Date(fromMs);
+    candidate.setSeconds(0, 0);
+    candidate.setMinutes(candidate.getMinutes() + 1);
+    const limit = fromMs + 4 * 366 * 86_400_000;
+    while (candidate.getTime() <= limit) {
+        if (!months.has(candidate.getMonth() + 1)) {
+            candidate.setMonth(candidate.getMonth() + 1, 1);
+            candidate.setHours(0, 0, 0, 0);
+            continue;
+        }
+        const dayMatch = domWildcard && dowWildcard ? true : domWildcard ? dow.has(candidate.getDay()) : dowWildcard ? dom.has(candidate.getDate()) : dom.has(candidate.getDate()) || dow.has(candidate.getDay());
+        if (!dayMatch) {
+            candidate.setDate(candidate.getDate() + 1);
+            candidate.setHours(0, 0, 0, 0);
+            continue;
+        }
+        if (!hours.has(candidate.getHours())) {
+            candidate.setHours(candidate.getHours() + 1, 0, 0, 0);
+            continue;
+        }
+        if (!minutes.has(candidate.getMinutes())) {
+            candidate.setMinutes(candidate.getMinutes() + 1, 0, 0);
+            continue;
+        }
+        return candidate.getTime();
+    }
+    return null;
+}
+export function createMockContext(optionsOrConfig = {}) {
+    const options = isMockOptions(optionsOrConfig) ? optionsOrConfig : { config: optionsOrConfig };
+    const approved = options.permissions === undefined ? null : new Set(options.permissions);
+    let config = { ...(options.config ?? {}) };
+    const calls = {
+        speak: [], react: [], reactions: [], statusReactions: [], status: [], storage: new Map(), schedules: new Map(), commands: new Map(), menuItems: [],
+        bubbles: [], alerts: [], dismissedBubbles: [], toasts: [], notifications: [], sounds: [], importedUserSounds: [], forgottenUserSounds: [], busPublishes: [], netCalls: [],
+        aiCalls: [], voiceSpeaks: [], openedExternal: [], clipboardWrites: [], spawnedPets: [], panelMessages: [],
+        savedFiles: [], secrets: new Map(), errors: [],
+    };
+    const clock = new FakeClock(options.nowMs ?? Date.now(), calls.schedules, (message) => calls.errors.push(message));
+    const eventSubscribers = new Map();
+    const storageSubscribers = new Map();
+    const busSubscribers = new Map();
+    const configListeners = new Set();
+    const panelToPluginHandlers = new Set();
+    const netMocks = [];
+    let aiResponder = null;
+    let pickableFiles = [];
+    let authTokens = null;
+    let listenText = null;
+    let clipboardText = "";
+    let systemInfo = { platform: "mac", locale: "en-US", timezone: "UTC", theme: "light", appVersion: "0.0.0-test", online: true };
+    let systemMetrics = { cpuPercent: 5, memUsedPercent: 40 };
+    let nextId = 0;
+    const newId = (prefix) => `${prefix}-${++nextId}`;
+    // ---- i18n: ctx.t / ctx.locale ----
+    // `ctx.locale` defaults to "en" and follows `harness.system.set({ locale })`.
+    // `ctx.t` resolves an optional in-memory catalog (active locale -> exact, then
+    // language prefix, then `en`), then echoes the key, finally interpolating {vars}.
+    const localeCatalogs = options.locales;
+    const activeLocale = () => {
+        const raw = systemInfo.locale;
+        return raw && raw !== "en-US" ? raw : "en";
+    };
+    const lookupCatalog = (key) => {
+        if (!localeCatalogs)
+            return undefined;
+        const locale = activeLocale();
+        const lang = locale.split(/[-_]/)[0];
+        return localeCatalogs[locale]?.[key] ?? localeCatalogs[lang]?.[key] ?? localeCatalogs.en?.[key];
+    };
+    const translate = (key, vars) => interpolateVars(lookupCatalog(key) ?? key, vars);
+    const requirePermission = (permission) => {
+        if (approved !== null && !approved.has(permission))
+            throw new Error(`Plugin permission is not approved: ${permission}`);
+    };
+    const makeBubble = (petId, spec) => {
+        requirePermission("pet:speak");
+        const normalized = typeof spec === "string" ? { text: spec } : { ...spec };
+        if (normalized.actions || normalized.input)
+            requirePermission("pet:interact");
+        if (normalized.pin)
+            requirePermission("pet:pin");
+        if (normalized.dynamic)
+            requirePermission("pet:speak:dynamic");
+        const id = newId("bubble");
+        const callbacks = {};
+        const record = {
+            spec: normalized,
+            petId,
+            updates: [],
+            pinned: normalized.pin === true,
+            dismissed: false,
+            handle: {
+                id,
+                update: async (patch) => { record.updates.push(patch); Object.assign(record.spec, patch); },
+                dismiss: async () => { if (!record.dismissed) {
+                    record.dismissed = true;
+                    calls.dismissedBubbles.push(id);
+                    callbacks.onDismiss?.("manual");
+                } },
+                pin: async () => { requirePermission("pet:pin"); record.pinned = true; },
+                unpin: async () => { record.pinned = false; },
+                onAction: (handler) => { callbacks.onAction = handler; },
+                onSubmit: (handler) => { callbacks.onSubmit = handler; },
+                onDismiss: (handler) => { callbacks.onDismiss = handler; },
+            },
+        };
+        bubbleCallbacks.set(id, { record, callbacks });
+        calls.bubbles.push(record);
+        if (normalized.text)
+            calls.speak.push(normalized.text);
+        return record.handle;
+    };
+    const bubbleCallbacks = new Map();
+    const makeAlert = (spec) => {
+        if (spec.sound !== undefined)
+            requirePermission("audio");
+        if (spec.notify !== undefined)
+            requirePermission("notify");
+        const { sound, notify, indicator, ...bubbleSpec } = spec;
+        const bubble = makeBubble("default", {
+            ...bubbleSpec,
+            ...(indicator === false ? {} : { indicator }),
+            sticky: true,
+            priority: "high",
+        });
+        const bubbleRecord = calls.bubbles[calls.bubbles.length - 1];
+        if (sound !== undefined)
+            calls.sounds.push({ sound });
+        if (notify !== undefined)
+            calls.notifications.push({ title: notify.title, body: notify.body });
+        const id = newId("alert");
+        const record = {
+            spec: { ...spec, actions: spec.actions?.map((action) => ({ ...action })) },
+            bubble: bubbleRecord,
+            updates: [],
+            dismissed: false,
+            acknowledged: false,
+            handle: {
+                id,
+                update: async (patch) => { record.updates.push(patch); Object.assign(record.spec, patch); await bubble.update(patch); },
+                dismiss: async () => { if (!record.dismissed) {
+                    record.dismissed = true;
+                    await bubble.dismiss();
+                } },
+                pin: async () => bubble.pin(),
+                unpin: async () => bubble.unpin(),
+                onAction: (handler) => { bubble.onAction(handler); },
+                onSubmit: (handler) => { bubble.onSubmit(handler); },
+                onDismiss: (handler) => { bubble.onDismiss(handler); },
+                acknowledge: async () => { record.acknowledged = true; await record.handle.dismiss(); },
+            },
+        };
+        calls.alerts.push(record);
+        return record.handle;
+    };
+    const petInfos = [{ id: "default", name: "Default pet", kind: "default", visible: true }];
+    const petState = { position: { x: 100, y: 100 }, bounds: { x: 100, y: 100, width: 220, height: 240 }, currentAnimation: "idle", visible: true, dragging: false };
+    const tickHandlers = new Set();
+    const makePetHandle = (petId) => ({
+        id: petId,
+        speak: async (spec) => makeBubble(petId, spec),
+        react: async (reaction, options) => { requirePermission("pet:reaction"); assertReaction(reaction); const record = { reaction: String(reaction), ...(options === undefined ? {} : { options: { ...options } }) }; calls.react.push(record.reaction); calls.reactions.push(record); },
+        setAnimation: async (state) => { if (typeof state === "string") {
+            requirePermission("pet:reaction");
+            calls.react.push(String(state));
+        }
+        else {
+            requirePermission("pet:animate");
+            petState.currentAnimation = `sprite:${state.sprite.name}`;
+        } },
+        setScale: async () => { requirePermission("pet:animate"); },
+        setStatusReaction: async (reaction) => { requirePermission("pet:reaction"); if (reaction !== null)
+            assertReaction(reaction); calls.statusReactions.push(reaction === null ? null : String(reaction)); },
+        moveBy: async () => { requirePermission("pet:move"); },
+        wander: async () => { requirePermission("pet:move"); },
+        moveToHome: async () => { requirePermission("pet:move"); },
+        moveTo: async (point) => { requirePermission("pet:move"); petState.position = { ...point }; },
+        followCursor: async () => { requirePermission("pet:move"); },
+        physics: async () => { requirePermission("pet:move"); },
+        onTick: (handler) => { requirePermission("events"); tickHandlers.add(handler); return () => tickHandlers.delete(handler); },
+        getState: async () => { requirePermission("pets:read"); return { ...petState, position: { ...petState.position }, bounds: { ...petState.bounds } }; },
+        show: async () => { requirePermission("pets:manage"); },
+        hide: async () => { requirePermission("pets:manage"); },
+        close: async () => { requirePermission("pets:manage"); },
+    });
+    const matchNetMock = (url) => netMocks.find((mock) => url.startsWith(mock.urlPrefix));
+    const ctx = {
+        pet: makePetHandle("default"),
+        pets: {
+            default: makePetHandle("default"),
+            list: async () => { requirePermission("pets:read"); return petInfos.map((info) => ({ ...info })); },
+            get: (petId) => makePetHandle(petId),
+            spawn: async (spec) => { requirePermission("pets:manage"); const id = newId("pet"); calls.spawnedPets.push(spec.petId); petInfos.push({ id, name: spec.name ?? spec.petId, kind: "plugin", visible: true }); return makePetHandle(id); },
+            onChange: () => () => undefined,
+        },
+        ui: {
+            bubble: async (spec) => makeBubble("default", spec),
+            toast: async (spec) => { requirePermission("ui:toast"); calls.toasts.push({ text: spec.text, tone: spec.tone }); },
+            alert: async (spec) => makeAlert(spec),
+            panel: async () => {
+                requirePermission("ui:panel");
+                const id = newId("panel");
+                return {
+                    id,
+                    show: async () => undefined,
+                    hide: async () => undefined,
+                    postMessage: async (msg) => { calls.panelMessages.push(msg); },
+                    onMessage: (handler) => { panelToPluginHandlers.add(handler); },
+                    close: async () => undefined,
+                };
+            },
+            menu: {
+                setItems: async (items) => { requirePermission("commands"); calls.menuItems = items.map((item) => ({ ...item })); },
+                onSelect: () => () => undefined,
+            },
+        },
+        audio: {
+            play: async (sound, options) => { requirePermission("audio"); calls.sounds.push({ sound, volume: options?.volume }); },
+            importUserSound: async (file, opts) => {
+                requirePermission("audio");
+                requirePermission("files");
+                const ref = { kind: "user-sound", id: newId("sound"), name: opts?.name ?? file.name };
+                calls.importedUserSounds.push({ ref, fileName: file.name, name: opts?.name });
+                return ref;
+            },
+            forgetUserSound: async (ref) => { requirePermission("audio"); calls.forgottenUserSounds.push(ref); },
+            stop: async () => { requirePermission("audio"); },
+        },
+        events: {
+            on: (event, handler) => {
+                requirePermission("events");
+                if (event === "pet:drop")
+                    requirePermission("pet:drop");
+                let subscribers = eventSubscribers.get(event);
+                if (!subscribers) {
+                    subscribers = new Set();
+                    eventSubscribers.set(event, subscribers);
+                }
+                const wrapped = (payload) => handler(payload);
+                subscribers.add(wrapped);
+                return () => subscribers.delete(wrapped);
+            },
+        },
+        assets: {
+            icon: (name) => ({ kind: "icon", name }),
+            image: (name) => ({ kind: "image", name }),
+            svg: (name) => ({ kind: "svg", name }),
+            sprite: (name) => ({ kind: "sprite", name }),
+            sound: (name) => ({ kind: "sound", name }),
+        },
+        bus: {
+            publish: async (topic, payload) => { requirePermission("bus"); calls.busPublishes.push({ topic, payload }); for (const handler of busSubscribers.get(topic) ?? [])
+                handler(payload); },
+            subscribe: (topic, handler) => {
+                requirePermission("bus");
+                let subscribers = busSubscribers.get(topic);
+                if (!subscribers) {
+                    subscribers = new Set();
+                    busSubscribers.set(topic, subscribers);
+                }
+                subscribers.add(handler);
+                return () => subscribers.delete(handler);
+            },
+        },
+        schedule: {
+            once: async (id, delayMs, handler) => { requirePermission("schedule"); calls.schedules.set(id, { type: "once", handler, dueMs: clock.now() + delayMs, intervalMs: delayMs }); },
+            every: async (id, intervalMs, handler) => { requirePermission("schedule"); calls.schedules.set(id, { type: "every", handler, dueMs: clock.now() + intervalMs, intervalMs }); },
+            daily: async (id, spec, handler) => { requirePermission("schedule"); const daily = typeof spec === "string" ? { time: spec } : spec; calls.schedules.set(id, { type: "daily", handler, daily, dueMs: nextDailyRunMs(daily, clock.now()) }); },
+            cron: async (id, expr, handler) => { requirePermission("schedule"); const due = nextCronRunMs(expr, clock.now()); calls.schedules.set(id, { type: "cron", handler, cronExpr: expr, dueMs: due ?? Number.POSITIVE_INFINITY }); },
+            at: async (id, isoTimestamp, handler) => { requirePermission("schedule"); const due = Date.parse(isoTimestamp); calls.schedules.set(id, { type: "at", handler, dueMs: Number.isFinite(due) ? Math.max(due, clock.now()) : clock.now() }); },
+            list: async () => [...calls.schedules.entries()].map(([id, schedule]) => ({ id, nextRunMs: schedule.dueMs })),
+            cancel: async (id) => void calls.schedules.delete(id),
+            cancelAll: async () => void calls.schedules.clear(),
+        },
+        storage: {
+            get: async (key) => { requirePermission("storage"); return calls.storage.get(key); },
+            set: async (key, value) => { requirePermission("storage"); calls.storage.set(key, value); for (const handler of storageSubscribers.get(key) ?? [])
+                handler(value); },
+            delete: async (key) => { requirePermission("storage"); calls.storage.delete(key); for (const handler of storageSubscribers.get(key) ?? [])
+                handler(undefined); },
+            keys: async () => { requirePermission("storage"); return [...calls.storage.keys()]; },
+            subscribe: (key, handler) => {
+                requirePermission("storage");
+                let subscribers = storageSubscribers.get(key);
+                if (!subscribers) {
+                    subscribers = new Set();
+                    storageSubscribers.set(key, subscribers);
+                }
+                subscribers.add(handler);
+                return () => subscribers.delete(handler);
+            },
+        },
+        config: {
+            get: async () => ({ ...config }),
+            onChange: (handler) => { configListeners.add(handler); return () => configListeners.delete(handler); },
+        },
+        net: {
+            fetch: async (url, options) => {
+                requirePermission("network");
+                if (options?.method && options.method !== "GET")
+                    requirePermission("network:write");
+                calls.netCalls.push({ url, method: options?.method ?? "GET", headers: options?.headers, body: options?.body, stream: false });
+                const mock = matchNetMock(url);
+                if (!mock)
+                    throw new Error(`No net mock for ${url} — call harness.net.mock(...) first.`);
+                const text = mock.response.text ?? (mock.response.json !== undefined ? JSON.stringify(mock.response.json) : "");
+                return { status: mock.response.status ?? 200, ok: (mock.response.status ?? 200) < 400, headers: { "content-type": mock.response.json !== undefined ? "application/json" : "text/plain" }, text, json: mock.response.json };
+            },
+            stream: async (url, options, onChunk) => {
+                requirePermission("network");
+                if (options.method && options.method !== "GET")
+                    requirePermission("network:write");
+                calls.netCalls.push({ url, method: options.method ?? "GET", headers: options.headers, body: options.body, stream: true });
+                const mock = matchNetMock(url);
+                if (!mock)
+                    throw new Error(`No net mock for ${url} — call harness.net.mock(...) first.`);
+                for (const chunk of mock.response.chunks ?? [mock.response.text ?? ""])
+                    if (chunk)
+                        onChunk(chunk);
+                return { status: mock.response.status ?? 200, ok: (mock.response.status ?? 200) < 400 };
+            },
+        },
+        notify: {
+            notify: async (spec) => { requirePermission("notify"); calls.notifications.push({ title: spec.title, body: spec.body }); },
+        },
+        ai: {
+            available: async () => { requirePermission("ai"); return aiResponder !== null; },
+            complete: async (req) => {
+                requirePermission("ai");
+                calls.aiCalls.push({ system: req.system, messages: req.messages });
+                if (!aiResponder)
+                    throw new Error("No AI mock — call harness.ai.mock(...) first.");
+                return { text: aiResponder(req) };
+            },
+            stream: async (req, onToken) => {
+                requirePermission("ai");
+                calls.aiCalls.push({ system: req.system, messages: req.messages });
+                if (!aiResponder)
+                    throw new Error("No AI mock — call harness.ai.mock(...) first.");
+                const text = aiResponder(req);
+                for (const token of text.split(/(?<=\s)/))
+                    onToken(token);
+                return { text };
+            },
+        },
+        secrets: {
+            set: async (key, value) => { requirePermission("secrets"); calls.secrets.set(key, value); },
+            get: async (key) => { requirePermission("secrets"); return calls.secrets.get(key); },
+            delete: async (key) => { requirePermission("secrets"); calls.secrets.delete(key); },
+            has: async (key) => { requirePermission("secrets"); return calls.secrets.has(key); },
+        },
+        voice: {
+            speak: async (text) => { requirePermission("voice:speak"); calls.voiceSpeaks.push(text); },
+            listen: async () => { requirePermission("voice:listen"); if (listenText === null)
+                throw new Error("No listen mock — call harness.voice.mockListen(...) first."); return { text: listenText }; },
+        },
+        auth: {
+            oauth: async () => { requirePermission("auth"); if (!authTokens)
+                throw new Error("No auth mock — call harness.auth.mock(...) first."); return { ...authTokens }; },
+            refresh: async () => { requirePermission("auth"); if (!authTokens)
+                throw new Error("No auth mock — call harness.auth.mock(...) first."); return { accessToken: authTokens.accessToken, expiresAt: authTokens.expiresAt }; },
+            signOut: async () => { requirePermission("auth"); authTokens = null; },
+        },
+        files: {
+            pick: async () => {
+                requirePermission("files");
+                return pickableFiles.map((file) => ({
+                    name: file.name,
+                    sizeBytes: file.bytes?.byteLength ?? (file.text ? file.text.length : 0),
+                    readText: async () => file.text ?? new TextDecoder().decode(file.bytes ?? new Uint8Array()),
+                    readBytes: async () => file.bytes ?? new TextEncoder().encode(file.text ?? ""),
+                }));
+            },
+            save: async (opts) => { requirePermission("files"); calls.savedFiles.push(opts); },
+        },
+        system: {
+            info: async () => ({ ...systemInfo }),
+            metrics: async () => { requirePermission("system:metrics"); return { ...systemMetrics }; },
+            openExternal: async (url) => { requirePermission("system:openExternal"); if (!url.startsWith("https://"))
+                throw new Error("openExternal requires an HTTPS URL."); calls.openedExternal.push(url); },
+            readClipboardText: async () => { requirePermission("clipboard"); return clipboardText; },
+            writeClipboardText: async (text) => { requirePermission("clipboard"); clipboardText = text; calls.clipboardWrites.push(text); },
+        },
+        commands: {
+            register: async (command, handler) => { requirePermission("commands"); calls.commands.set(command.id, { meta: command, handler }); },
+            unregister: async (id) => void calls.commands.delete(id),
+        },
+        status: {
+            set: async (status) => { requirePermission("status"); calls.status.push(status); },
+            clear: async () => { requirePermission("status"); },
+        },
+        http: {
+            fetch: async (url, options) => {
+                requirePermission("network");
+                calls.netCalls.push({ url, method: "GET", headers: options?.headers, stream: false });
+                const mock = matchNetMock(url);
+                if (!mock)
+                    return { status: 200, ok: true, headers: {}, text: "" };
+                const text = mock.response.text ?? (mock.response.json !== undefined ? JSON.stringify(mock.response.json) : "");
+                return { status: mock.response.status ?? 200, ok: (mock.response.status ?? 200) < 400, headers: {}, text, json: mock.response.json };
+            },
+        },
+        log: {
+            debug: async () => undefined,
+            info: async () => undefined,
+            warn: async () => undefined,
+            error: async () => undefined,
+        },
+        t: (key, vars) => translate(key, vars),
+        get locale() { return activeLocale(); },
+    };
+    const harness = {
+        clock,
+        emit: async (event, payload) => { for (const handler of eventSubscribers.get(event) ?? [])
+            await Promise.resolve(handler(payload)); },
+        fireBubbleAction: async (bubbleId, actionId) => { const entry = bubbleCallbacks.get(bubbleId); if (!entry)
+            throw new Error(`Unknown bubble: ${bubbleId}`); await entry.callbacks.onAction?.(actionId); const action = entry.record.spec.actions?.find((candidate) => candidate.id === actionId); if (action?.dismissesBubble !== false)
+            await entry.record.handle.dismiss(); },
+        fireBubbleSubmit: async (bubbleId, values) => { const entry = bubbleCallbacks.get(bubbleId); if (!entry)
+            throw new Error(`Unknown bubble: ${bubbleId}`); await entry.callbacks.onSubmit?.(values); },
+        dismissBubble: async (bubbleId, reason = "click") => { const entry = bubbleCallbacks.get(bubbleId); if (!entry || entry.record.dismissed)
+            return; entry.record.dismissed = true; calls.dismissedBubbles.push(bubbleId); entry.callbacks.onDismiss?.(reason); },
+        runCommand: async (commandId, values) => { const command = calls.commands.get(commandId); if (!command)
+            throw new Error(`Unknown command: ${commandId}`); await command.handler(values); },
+        setConfig: async (next) => { config = { ...next }; for (const listener of configListeners)
+            await Promise.resolve(listener({ ...config })); },
+        net: { mock: (urlPrefix, response) => { netMocks.unshift({ urlPrefix, response }); } },
+        ai: { mock: (responder) => { aiResponder = responder; } },
+        files: { provide: (files) => { pickableFiles = files; } },
+        auth: { mock: (tokens) => { authTokens = tokens; } },
+        voice: { mockListen: (text) => { listenText = text; } },
+        system: {
+            set: (info) => { systemInfo = { ...systemInfo, ...info }; },
+            setMetrics: (metrics) => { systemMetrics = metrics; },
+            setClipboard: (text) => { clipboardText = text; },
+        },
+        panel: { sendToPlugin: (msg) => { for (const handler of panelToPluginHandlers)
+                handler(msg); } },
+    };
+    return { ctx, calls, harness };
+}
+function isMockOptions(value) {
+    return "permissions" in value || "config" in value || "nowMs" in value || "locales" in value;
+}
+/**
+ * Build a batteries-included harness around a plugin definition or an exported
+ * `register(OpenPetsPlugin)` entry function.
+ */
+export function createTestHarness(plugin, options = {}) {
+    const { ctx, calls, harness } = createMockContext(options);
+    let definition = typeof plugin === "function" ? null : plugin;
+    const entry = typeof plugin === "function" ? plugin : null;
+    const fail = (message) => { throw new Error(message); };
+    return {
+        ...harness,
+        ctx,
+        calls,
+        async start() {
+            if (entry) {
+                const api = { register: (registered) => { definition = registered; } };
+                await entry(api);
+                if (!definition)
+                    fail("Plugin entry never called OpenPetsPlugin.register().");
+            }
+            await definition.start(ctx);
+        },
+        async stop() {
+            await definition?.stop?.(ctx);
+        },
+        async tick(dtMs) {
+            // The mock pet handle records tick handlers internally; route through emit-like dispatch.
+            await harness.emit("pet:hover", { petId: "default", __tickDtMs: dtMs });
+        },
+        expectSpoke(matcher) {
+            const found = calls.speak.some((message) => (typeof matcher === "string" ? message.includes(matcher) : matcher.test(message)));
+            if (!found)
+                fail(`Expected pet speech matching ${String(matcher)}; got ${JSON.stringify(calls.speak)}`);
+        },
+        expectReacted(reaction) {
+            if (!calls.react.includes(reaction))
+                fail(`Expected reaction "${reaction}"; got ${JSON.stringify(calls.react)}`);
+        },
+        expectScheduled(id) {
+            if (!calls.schedules.has(id))
+                fail(`Expected schedule "${id}"; got ${JSON.stringify([...calls.schedules.keys()])}`);
+        },
+        expectBubble(matcher) {
+            const { textMatch, ...rest } = matcher;
+            const found = calls.bubbles.some((bubble) => {
+                if (textMatch && !(bubble.spec.text && textMatch.test(bubble.spec.text)))
+                    return false;
+                return Object.entries(rest).every(([key, value]) => JSON.stringify(bubble.spec[key]) === JSON.stringify(value));
+            });
+            if (!found)
+                fail(`Expected a bubble matching ${JSON.stringify(matcher)}; got ${JSON.stringify(calls.bubbles.map((bubble) => bubble.spec))}`);
+        },
+        expectStored(key, predicate) {
+            if (!calls.storage.has(key))
+                fail(`Expected storage key "${key}"; got ${JSON.stringify([...calls.storage.keys()])}`);
+            if (predicate && !predicate(calls.storage.get(key)))
+                fail(`Storage value for "${key}" failed the predicate: ${JSON.stringify(calls.storage.get(key))}`);
+        },
+        expectNetCall(urlSubstring) {
+            if (!calls.netCalls.some((call) => call.url.includes(urlSubstring)))
+                fail(`Expected a network call containing "${urlSubstring}"; got ${JSON.stringify(calls.netCalls.map((call) => call.url))}`);
+        },
+        expectNotified(matcher) {
+            const found = calls.notifications.some((notification) => (typeof matcher === "string" ? notification.title.includes(matcher) || (notification.body ?? "").includes(matcher) : matcher.test(notification.title) || matcher.test(notification.body ?? "")));
+            if (!found)
+                fail(`Expected a notification matching ${String(matcher)}; got ${JSON.stringify(calls.notifications)}`);
+        },
+        expectNoErrors() {
+            if (calls.errors.length > 0)
+                fail(`Expected no schedule/handler errors; got ${JSON.stringify(calls.errors)}`);
+        },
+    };
+}
+//# sourceMappingURL=testing.js.map