@mandujs/core 0.21.0 → 0.22.1

package/src/desktop/__tests__/smoke.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @mandujs/core/desktop — smoke tests
+ *
+ * Integration-shaped assertions: the barrel re-exports what we expect, the
+ * optional peer is genuinely optional (tests pass with it absent), and the
+ * demo fixture is present.
+ *
+ * The browser-visible smoke (actual WebView window opening) runs only when
+ * a `MANDU_DESKTOP_E2E=1` env flag is set AND the peer is installed. CI
+ * skips it unconditionally.
+ */
+
+import { describe, it, expect } from "bun:test";
+import path from "path";
+import fs from "fs";
+
+const repoRoot = path.resolve(__dirname, "..", "..", "..", "..", "..");
+const demoPath = path.join(repoRoot, "demo", "desktop-starter");
+
+describe("@mandujs/core/desktop — smoke", () => {
+  it("barrel exports createWindow and the type surface", async () => {
+    const mod = await import("../index");
+    expect(typeof mod.createWindow).toBe("function");
+    // Type-only exports don't survive runtime introspection; the fact
+    // that the import succeeds without throwing is the meaningful part.
+  });
+
+  it("worker entry is importable without a running Worker host", async () => {
+    // Importing worker.ts outside a Worker context must not crash — the
+    // module guards on `globalThis.addEventListener` presence. In Bun main
+    // thread, `addEventListener` exists on globalThis (as a DOM-compat
+    // shim), so the installer runs but just doesn't receive messages.
+    const mod = await import("../worker");
+    expect(typeof mod._installHandler).toBe("function");
+    expect(typeof mod._postToParent).toBe("function");
+  });
+
+  it("demo/desktop-starter fixture exists", () => {
+    const exists = fs.existsSync(demoPath);
+    expect(exists).toBe(true);
+  });
+
+  it("demo/desktop-starter has a package.json with webview-bun peer", () => {
+    const pkgPath = path.join(demoPath, "package.json");
+    const pkgRaw = fs.readFileSync(pkgPath, "utf-8");
+    const pkg = JSON.parse(pkgRaw);
+    expect(pkg.name).toBe("mandu-desktop-starter");
+    // webview-bun should appear either in dependencies or peerDependencies
+    const combined = {
+      ...(pkg.dependencies ?? {}),
+      ...(pkg.peerDependencies ?? {}),
+      ...(pkg.optionalDependencies ?? {}),
+    };
+    expect("webview-bun" in combined).toBe(true);
+  });
+
+  it("demo/desktop-starter has a desktop entry file", () => {
+    const entryPath = path.join(demoPath, "src", "desktop", "main.ts");
+    const exists = fs.existsSync(entryPath);
+    expect(exists).toBe(true);
+    const contents = fs.readFileSync(entryPath, "utf-8");
+    // The entry should wire Worker + startServer — sanity-check key symbols.
+    expect(contents).toContain("startServer");
+    expect(contents).toContain("Worker");
+  });
+
+  it("demo/desktop-starter has minimal app/ routes", () => {
+    const appDir = path.join(demoPath, "app");
+    const exists = fs.existsSync(appDir);
+    expect(exists).toBe(true);
+    const pagePath = path.join(appDir, "page.tsx");
+    expect(fs.existsSync(pagePath)).toBe(true);
+  });
+});
+
+// Describe block that runs only when explicitly enabled. Left as a
+// placeholder for local Windows smoke — no assertions on CI.
+const canOpenWindow =
+  process.env.MANDU_DESKTOP_E2E === "1" &&
+  (process.platform === "win32" ||
+    process.platform === "darwin" ||
+    process.platform === "linux");
+
+describe.skipIf(!canOpenWindow)(
+  "@mandujs/core/desktop — browser smoke (opt-in)",
+  () => {
+    it("opens and closes a data: URL window", async () => {
+      const { createWindow } = await import("../window");
+      const handle = await createWindow({
+        url: "data:text/html,<h1>Mandu smoke</h1>",
+        title: "Mandu E2E",
+        width: 400,
+        height: 300,
+      });
+      // Close immediately — we only assert the handle is constructible.
+      await handle.close();
+      await handle.closed;
+    });
+  },
+);

package/src/desktop/__tests__/window.test.ts

@@ -0,0 +1,172 @@
+/**
+ * @mandujs/core/desktop — window factory tests
+ *
+ * These tests run **without actually loading `webview-bun`**: we either
+ * stub the optional peer via a mocked import cache or exercise option
+ * validation / size-hint mapping / error paths that never need the FFI
+ * peer at all. CI does not have WebView2 / WKWebView available, so any
+ * test that would open a real window is marked describe.skipIf.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import {
+  _DEFAULTS,
+  _mapSizeHint,
+  _resetWebviewBunCache,
+  _validateOptions,
+  createWindow,
+} from "../window";
+import type { WindowOptions } from "../types";
+
+describe("@mandujs/core/desktop — types & validation", () => {
+  it("_DEFAULTS match the documented contract", () => {
+    expect(_DEFAULTS.title).toBe("Mandu Desktop");
+    expect(_DEFAULTS.width).toBe(1024);
+    expect(_DEFAULTS.height).toBe(768);
+    expect(_DEFAULTS.hint).toBe("none");
+    expect(_DEFAULTS.debug).toBe(false);
+  });
+
+  it("_mapSizeHint translates strings to peer enum values", () => {
+    const fakeEnum = { NONE: 0, MIN: 1, MAX: 2, FIXED: 3 };
+    expect(_mapSizeHint("none", fakeEnum)).toBe(0);
+    expect(_mapSizeHint("min", fakeEnum)).toBe(1);
+    expect(_mapSizeHint("max", fakeEnum)).toBe(2);
+    expect(_mapSizeHint("fixed", fakeEnum)).toBe(3);
+    expect(_mapSizeHint(undefined, fakeEnum)).toBe(0); // default → NONE
+  });
+
+  it("_validateOptions rejects missing url", () => {
+    expect(() => _validateOptions({} as WindowOptions)).toThrow(/url/);
+  });
+
+  it("_validateOptions rejects non-string url", () => {
+    expect(() =>
+      _validateOptions({ url: 123 as unknown as string }),
+    ).toThrow(/url/);
+  });
+
+  it("_validateOptions rejects malformed url", () => {
+    expect(() => _validateOptions({ url: "not a url" })).toThrow(/valid URL/);
+  });
+
+  it("_validateOptions rejects forbidden protocols", () => {
+    expect(() =>
+      _validateOptions({ url: "javascript:alert(1)" }),
+    ).toThrow(/protocol/);
+    expect(() =>
+      _validateOptions({ url: "chrome://version" }),
+    ).toThrow(/protocol/);
+  });
+
+  it("_validateOptions accepts http, https, file, and data URLs", () => {
+    expect(() =>
+      _validateOptions({ url: "http://127.0.0.1:3333/" }),
+    ).not.toThrow();
+    expect(() =>
+      _validateOptions({ url: "https://example.com/" }),
+    ).not.toThrow();
+    expect(() =>
+      _validateOptions({ url: "file:///tmp/index.html" }),
+    ).not.toThrow();
+    expect(() =>
+      _validateOptions({ url: "data:text/html,<h1>hi</h1>" }),
+    ).not.toThrow();
+  });
+
+  it("_validateOptions rejects non-positive width/height", () => {
+    expect(() =>
+      _validateOptions({ url: "http://x", width: 0 }),
+    ).toThrow(/width/);
+    expect(() =>
+      _validateOptions({ url: "http://x", height: -50 }),
+    ).toThrow(/height/);
+    expect(() =>
+      _validateOptions({
+        url: "http://x",
+        width: Number.NaN,
+      }),
+    ).toThrow(/width/);
+  });
+
+  it("_validateOptions rejects unknown hint values", () => {
+    expect(() =>
+      _validateOptions({
+        url: "http://x",
+        hint: "resizable" as never,
+      }),
+    ).toThrow(/hint/);
+  });
+
+  it("_validateOptions rejects non-function handlers", () => {
+    expect(() =>
+      _validateOptions({
+        url: "http://x",
+        handlers: { foo: "not a function" as unknown as () => void },
+      }),
+    ).toThrow(/handlers\.foo/);
+  });
+
+  it("_validateOptions accepts a fully-specified options bag", () => {
+    expect(() =>
+      _validateOptions({
+        url: "http://127.0.0.1:3333/",
+        title: "Test",
+        width: 1280,
+        height: 800,
+        hint: "fixed",
+        debug: true,
+        handlers: { greet: () => "hi" },
+      }),
+    ).not.toThrow();
+  });
+});
+
+describe("@mandujs/core/desktop — createWindow peer loading", () => {
+  beforeEach(() => {
+    _resetWebviewBunCache();
+  });
+
+  it("validates options before attempting to load the peer", async () => {
+    // Bad options should throw TypeError *before* the peer import runs, so
+    // this test passes even on CI without webview-bun installed.
+    await expect(
+      createWindow({ url: "" } as WindowOptions),
+    ).rejects.toThrow(TypeError);
+    await expect(
+      createWindow({} as WindowOptions),
+    ).rejects.toThrow(TypeError);
+    await expect(
+      createWindow({
+        url: "javascript:evil()",
+      } as WindowOptions),
+    ).rejects.toThrow(/protocol/);
+  });
+
+  it("throws an actionable error when webview-bun is not installed", async () => {
+    // Only run this when the peer is genuinely absent — if a developer has
+    // `webview-bun` installed locally, the import will succeed and we'd
+    // open a real window. Probe via dynamic import.
+    //
+    // @ts-ignore -- optional peer, resolution may fail at typecheck time
+    const probe = () => import("webview-bun");
+    let peerInstalled = false;
+    try {
+      await probe();
+      peerInstalled = true;
+    } catch {
+      peerInstalled = false;
+    }
+
+    if (peerInstalled) {
+      // On Windows with the peer installed, we'd end up creating a real
+      // window. Skip the assertion — the actionable-error guarantee is only
+      // meaningful when the peer is missing.
+      return;
+    }
+
+    await expect(
+      createWindow({ url: "http://127.0.0.1:1" }),
+    ).rejects.toThrow(/webview-bun/);
+  });
+});

package/src/desktop/__tests__/worker.test.ts

@@ -0,0 +1,266 @@
+/**
+ * @mandujs/core/desktop — Worker protocol tests
+ *
+ * The Worker file auto-installs a global message listener on module
+ * evaluation, so to test the protocol we reach for the exported
+ * `_installHandler` helper and drive it with a mock message emitter and
+ * a mock `createWindow` implementation. No real Worker spawn, no FFI.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { _installHandler } from "../worker";
+import type {
+  WindowHandle,
+  WindowOptions,
+  WorkerInbound,
+  WorkerOutbound,
+} from "../types";
+
+type MessageListener = (ev: { data: WorkerInbound }) => Promise<void> | void;
+
+/**
+ * Stand in for `addEventListener('message', ...)` — retains the listener
+ * and exposes a `fire()` helper so tests can synchronously drive messages.
+ */
+function createEmitter(): {
+  listen: (cb: MessageListener) => void;
+  fire: (data: WorkerInbound) => Promise<void>;
+} {
+  let listener: MessageListener | null = null;
+  return {
+    listen(cb) {
+      listener = cb;
+    },
+    async fire(data) {
+      if (!listener) throw new Error("no listener installed");
+      await listener({ data });
+    },
+  };
+}
+
+/**
+ * A fake WindowHandle we can wire up to _installHandler so we don't need a
+ * real Webview. Tracks every call so tests can assert order.
+ */
+function createFakeHandle(options: WindowOptions): {
+  handle: WindowHandle;
+  calls: string[];
+  closed: () => void;
+} {
+  const calls: string[] = [];
+  calls.push(`ctor:${options.url}`);
+  let resolveClosed: (() => void) | null = null;
+  const closedPromise = new Promise<void>((r) => {
+    resolveClosed = r;
+  });
+  const handle: WindowHandle = {
+    async close() {
+      calls.push("close");
+      resolveClosed?.();
+    },
+    onClose(cb) {
+      closedPromise.then(cb);
+    },
+    async eval(js) {
+      calls.push(`eval:${js}`);
+    },
+    bind() {
+      calls.push("bind");
+    },
+    closed: closedPromise,
+    run() {
+      calls.push("run");
+      // Run returns synchronously in tests — no blocking.
+    },
+  };
+  return {
+    handle,
+    calls,
+    closed: () => resolveClosed?.(),
+  };
+}
+
+describe("@mandujs/core/desktop — Worker protocol", () => {
+  it("handles open → ready sequence and stores handle", async () => {
+    const emitter = createEmitter();
+    let fake: ReturnType<typeof createFakeHandle> | null = null;
+    const outbound: WorkerOutbound[] = [];
+
+    // Install message handler with a fake createWindow.
+    const installed = _installHandler(emitter.listen, async (opts) => {
+      fake = createFakeHandle(opts);
+      return fake.handle;
+    });
+
+    // Intercept `postMessage` on globalThis to capture outbound messages.
+    const prevPost = (globalThis as { postMessage?: unknown }).postMessage;
+    (globalThis as { postMessage?: unknown }).postMessage = (
+      msg: WorkerOutbound,
+    ) => {
+      outbound.push(msg);
+    };
+
+    try {
+      await emitter.fire({
+        type: "open",
+        options: { url: "http://127.0.0.1:3333/" },
+      });
+
+      // Give the microtask queue a chance to drain the deferred run() call.
+      await new Promise((r) => setTimeout(r, 10));
+
+      expect(fake).not.toBeNull();
+      expect(fake!.calls).toContain("ctor:http://127.0.0.1:3333/");
+      expect(fake!.calls).toContain("run");
+      expect(outbound.some((m) => m.type === "ready")).toBe(true);
+      expect(installed.getHandle()).not.toBeNull();
+    } finally {
+      (globalThis as { postMessage?: unknown }).postMessage = prevPost;
+    }
+  });
+
+  it("rejects duplicate open messages", async () => {
+    const emitter = createEmitter();
+    const outbound: WorkerOutbound[] = [];
+
+    _installHandler(emitter.listen, async (opts) =>
+      createFakeHandle(opts).handle,
+    );
+
+    const prevPost = (globalThis as { postMessage?: unknown }).postMessage;
+    (globalThis as { postMessage?: unknown }).postMessage = (
+      msg: WorkerOutbound,
+    ) => {
+      outbound.push(msg);
+    };
+
+    try {
+      await emitter.fire({
+        type: "open",
+        options: { url: "http://127.0.0.1:3333/" },
+      });
+      outbound.length = 0; // reset
+      await emitter.fire({
+        type: "open",
+        options: { url: "http://127.0.0.1:3333/" },
+      });
+      const error = outbound.find((m) => m.type === "error");
+      expect(error).toBeDefined();
+      if (error && error.type === "error") {
+        expect(error.message).toMatch(/already open/);
+      }
+    } finally {
+      (globalThis as { postMessage?: unknown }).postMessage = prevPost;
+    }
+  });
+
+  it("handles eval after open", async () => {
+    const emitter = createEmitter();
+    let fake: ReturnType<typeof createFakeHandle> | null = null;
+
+    _installHandler(emitter.listen, async (opts) => {
+      fake = createFakeHandle(opts);
+      return fake.handle;
+    });
+
+    const prevPost = (globalThis as { postMessage?: unknown }).postMessage;
+    (globalThis as { postMessage?: unknown }).postMessage = () => {};
+
+    try {
+      await emitter.fire({
+        type: "open",
+        options: { url: "http://127.0.0.1:3333/" },
+      });
+      await emitter.fire({
+        type: "eval",
+        js: "console.log('hi')",
+      });
+      expect(fake!.calls).toContain("eval:console.log('hi')");
+    } finally {
+      (globalThis as { postMessage?: unknown }).postMessage = prevPost;
+    }
+  });
+
+  it("reports error when eval is received before open", async () => {
+    const emitter = createEmitter();
+    const outbound: WorkerOutbound[] = [];
+
+    _installHandler(emitter.listen, async (opts) =>
+      createFakeHandle(opts).handle,
+    );
+
+    const prevPost = (globalThis as { postMessage?: unknown }).postMessage;
+    (globalThis as { postMessage?: unknown }).postMessage = (
+      msg: WorkerOutbound,
+    ) => {
+      outbound.push(msg);
+    };
+
+    try {
+      await emitter.fire({
+        type: "eval",
+        js: "console.log('early')",
+      });
+      const error = outbound.find((m) => m.type === "error");
+      expect(error).toBeDefined();
+      if (error && error.type === "error") {
+        expect(error.message).toMatch(/before 'open'/);
+      }
+    } finally {
+      (globalThis as { postMessage?: unknown }).postMessage = prevPost;
+    }
+  });
+
+  it("handles close message gracefully when no window is open", async () => {
+    const emitter = createEmitter();
+    const outbound: WorkerOutbound[] = [];
+
+    _installHandler(emitter.listen, async (opts) =>
+      createFakeHandle(opts).handle,
+    );
+
+    const prevPost = (globalThis as { postMessage?: unknown }).postMessage;
+    (globalThis as { postMessage?: unknown }).postMessage = (
+      msg: WorkerOutbound,
+    ) => {
+      outbound.push(msg);
+    };
+
+    try {
+      await emitter.fire({ type: "close" });
+      // Should not throw or emit an error — close on nothing is a no-op.
+      expect(outbound.filter((m) => m.type === "error").length).toBe(0);
+    } finally {
+      (globalThis as { postMessage?: unknown }).postMessage = prevPost;
+    }
+  });
+
+  it("reports errors for unknown message types", async () => {
+    const emitter = createEmitter();
+    const outbound: WorkerOutbound[] = [];
+
+    _installHandler(emitter.listen, async (opts) =>
+      createFakeHandle(opts).handle,
+    );
+
+    const prevPost = (globalThis as { postMessage?: unknown }).postMessage;
+    (globalThis as { postMessage?: unknown }).postMessage = (
+      msg: WorkerOutbound,
+    ) => {
+      outbound.push(msg);
+    };
+
+    try {
+      await emitter.fire({
+        type: "bogus" as unknown as "open",
+      } as WorkerInbound);
+      const error = outbound.find((m) => m.type === "error");
+      expect(error).toBeDefined();
+      if (error && error.type === "error") {
+        expect(error.message).toMatch(/Unknown message type/);
+      }
+    } finally {
+      (globalThis as { postMessage?: unknown }).postMessage = prevPost;
+    }
+  });
+});

package/src/desktop/index.ts

@@ -0,0 +1,43 @@
+/**
+ * @mandujs/core/desktop
+ *
+ * Native desktop windowing for Mandu apps via `webview-bun` (optional peer).
+ * Phase 9c — see `docs/bun/phase-9-diagnostics/webview-bun-ffi.md`.
+ *
+ * Supported backends (from the peer):
+ *   - Windows: WebView2 (Chromium Evergreen; 10/11)
+ *   - macOS:   WKWebView (11+)
+ *   - Linux:   WebKitGTK 6 + GTK 4
+ *
+ * `webview-bun` is declared as an **optional peer dependency** — Mandu's core
+ * runtime continues to work on web-only projects that never install it.
+ * Importing this module is safe in any environment; loading only occurs the
+ * first time `createWindow()` is called, at which point a missing peer throws
+ * with an actionable install message.
+ *
+ * @example Minimal desktop entry
+ * ```ts
+ * import { startServer } from "@mandujs/core";
+ * import { createWindow } from "@mandujs/core/desktop";
+ * import manifest from "../../.mandu/manifest.json" with { type: "json" };
+ *
+ * const server = startServer(manifest, { port: 0, hostname: "127.0.0.1" });
+ * const win = await createWindow({
+ *   url: `http://127.0.0.1:${server.server.port}`,
+ *   title: "My App",
+ *   width: 1280,
+ *   height: 800,
+ * });
+ * win.run();  // blocking; returns on user close
+ * server.stop();
+ * ```
+ */
+
+export { createWindow } from "./window.js";
+export type {
+  WindowHandle,
+  WindowOptions,
+  WindowSizeHint,
+  WorkerInbound,
+  WorkerOutbound,
+} from "./types.js";