@mandujs/core 0.21.0 → 0.22.0

package/src/desktop/types.ts

@@ -0,0 +1,158 @@
+/**
+ * @mandujs/core/desktop — type contracts
+ *
+ * Shared types for Mandu's desktop integration. These intentionally mirror
+ * but do NOT import `webview-bun`, so consumers that never touch desktop
+ * features (e.g. web-only apps, CI type-checking without the optional peer
+ * installed) don't pay the cost of loading the FFI module graph.
+ *
+ * The concrete runtime lives in `./window.ts` behind a lazy import.
+ */
+
+/**
+ * Size hint applied to the window. Mirrors `webview-bun` `SizeHint` enum but
+ * exposed here as a string union so callers don't need to import the FFI
+ * module just to pass an option.
+ *
+ * - `"none"`     → window is freely resizable, no constraints.
+ * - `"min"`      → the supplied width/height are treated as minimums.
+ * - `"max"`      → the supplied width/height are treated as maximums.
+ * - `"fixed"`    → window cannot be resized by the user.
+ *
+ * Default: `"none"`.
+ */
+export type WindowSizeHint = "none" | "min" | "max" | "fixed";
+
+/**
+ * Options passed to {@link createWindow}. Only `url` is required — everything
+ * else has a sane default.
+ */
+export interface WindowOptions {
+  /**
+   * URL to navigate to. Mandu's recommended pattern is to start a local HTTP
+   * server on `127.0.0.1:0` and pass `http://127.0.0.1:<port>`. Remote URLs
+   * are technically possible but bypass the security boundary — don't.
+   */
+  url: string;
+  /** Window title. Default: `"Mandu Desktop"`. */
+  title?: string;
+  /** Width in logical pixels. Default: `1024`. */
+  width?: number;
+  /** Height in logical pixels. Default: `768`. */
+  height?: number;
+  /**
+   * Size hint — controls resizability. Default: `"none"` (freely resizable).
+   * Pass `"fixed"` for kiosk-style windows.
+   */
+  hint?: WindowSizeHint;
+  /**
+   * Open DevTools / enable WebInspector. Default: `false`.
+   *
+   * Note: On macOS this requires an entitlement; on Linux GTK builds, DevTools
+   * is baked into WebKitGTK. On Windows WebView2, pressing F12 inside the
+   * running window also works.
+   */
+  debug?: boolean;
+  /**
+   * Pre-register request/response handlers exposed to the page's JavaScript
+   * as global async functions. Equivalent to calling `handle.bind(name, fn)`
+   * for each entry, but registered BEFORE the first navigation — safer
+   * against race conditions where the page calls an unbound global.
+   */
+  handlers?: Record<string, (...args: unknown[]) => unknown>;
+  /**
+   * Invoked once after the window is shown and the first navigation begins.
+   * Runs on the main thread (or Worker, whichever owns the Webview instance).
+   * Exceptions bubble up to the caller's promise.
+   */
+  onReady?: () => void | Promise<void>;
+  /**
+   * Invoked when the user closes the window (title-bar X or Cmd+Q / Alt+F4).
+   * Use this to tear down the HTTP server, flush caches, etc.
+   */
+  onClose?: () => void | Promise<void>;
+}
+
+/**
+ * Opaque handle returned by {@link createWindow}. Provides a minimal, stable
+ * surface over the underlying `webview-bun` instance. Consumers should not
+ * cast this to `Webview` — future Mandu versions may wrap a different backend
+ * (direct FFI, `Bun.WebView`, etc.).
+ */
+export interface WindowHandle {
+  /**
+   * Close the window and release native resources. Idempotent — calling
+   * twice is safe.
+   */
+  close(): Promise<void>;
+  /**
+   * Register a callback for when the window is closed by the user or by
+   * `close()`. Callback fires exactly once.
+   */
+  onClose(cb: () => void): void;
+  /**
+   * Inject JavaScript into the current page. Does NOT return a value — use
+   * `bind()` for host↔page request/response.
+   */
+  eval(js: string): Promise<void>;
+  /**
+   * Expose a host function as a global async function on the page. The
+   * returned value (or its JSON serialization) is resolved by the caller's
+   * awaited `window.<name>(...)` in the page.
+   *
+   * Arguments from the page are JSON-deserialized before being passed in;
+   * returns are JSON-serialized back. Non-serializable values (undefined,
+   * functions, circular refs) will either be dropped or throw.
+   */
+  bind(name: string, fn: (...args: unknown[]) => unknown): void;
+  /**
+   * Resolves when the user closes the window (title-bar X or equivalent),
+   * OR when `close()` is called. Does NOT reject on error — errors are
+   * surfaced via the synchronous throw from `createWindow()` / `eval()`.
+   *
+   * Useful for the common pattern:
+   *   ```ts
+   *   const win = await createWindow(opts);
+   *   await win.closed;
+   *   await server.stop();
+   *   ```
+   */
+  readonly closed: Promise<void>;
+  /**
+   * Start the platform event loop. **Blocking.** Returns when the window
+   * closes. On the main thread, this will freeze the Bun server — launch
+   * a Worker for the HTTP server or wrap the window in a Worker itself.
+   *
+   * Most callers should use {@link closed} instead of managing `run()`
+   * manually; {@link createWindow} auto-invokes `run()` under the hood when
+   * `autoRun: true` (the default).
+   */
+  run(): void;
+}
+
+/**
+ * Messages flowing from the parent thread → Worker that hosts the window.
+ * Exported so callers authoring custom Worker entries have a stable shape.
+ */
+export type WorkerInbound =
+  | {
+      type: "open";
+      /** Serialized {@link WindowOptions}. Functions are stripped — bind handlers must be registered via worker code. */
+      options: Omit<WindowOptions, "handlers" | "onReady" | "onClose">;
+    }
+  | {
+      type: "close";
+    }
+  | {
+      type: "eval";
+      js: string;
+    };
+
+/**
+ * Messages flowing from the Worker → parent thread.
+ */
+export type WorkerOutbound =
+  | { type: "ready" }
+  | { type: "closed" }
+  | { type: "error"; message: string }
+  | { type: "bind-call"; name: string; args: unknown[]; seq: string };

package/src/desktop/window.ts

@@ -0,0 +1,492 @@
+/**
+ * @mandujs/core/desktop — window factory
+ *
+ * Wraps `webview-bun` (optional peer dependency, MIT, tr1ckydev/webview-bun
+ * 2.4.0+). Phase 9c R0 diagnostic:
+ *   - docs/bun/phase-9-diagnostics/webview-bun-ffi.md
+ *
+ * Design rules:
+ *   1. **Lazy import** — `webview-bun` must NOT be loaded when this module is
+ *      merely imported. A web-only project running `bun test` should pass
+ *      even if the peer is absent. The import happens on the first
+ *      `createWindow()` call, with a clear install-me error on failure.
+ *   2. **No side-channel globals** — each handle is self-contained; multiple
+ *      windows are allowed in a single process (though not a common use
+ *      case).
+ *   3. **Never surface the `Webview` instance** — consumers only see
+ *      {@link WindowHandle}. Backend swaps (Bun.WebView native, direct FFI)
+ *      stay transparent.
+ *
+ * Threading model: `webview-bun`'s `run()` is blocking and must be on the
+ * thread that owns the window. For use with `Bun.serve()`, the standard
+ * pattern is **Worker-based**: launch the server on the main thread, spawn
+ * a Worker, and call `createWindow()` inside it. See `./worker.ts` for the
+ * canonical entry. When `autoRun: false`, callers who control their own
+ * event loop (e.g. running the window on the main thread while the HTTP
+ * server sits in a Worker) can call `handle.run()` themselves.
+ */
+
+import type {
+  WindowHandle,
+  WindowOptions,
+  WindowSizeHint,
+} from "./types.js";
+
+// ─── Optional-peer loader ───────────────────────────────────────────────────
+
+/**
+ * Cached module once loaded. We do NOT pre-load at module evaluation — if
+ * `webview-bun` is missing, `import @mandujs/core/desktop` must still succeed
+ * (so `bun test` in a CI without the peer passes cleanly).
+ */
+type WebviewBunModule = {
+  // We intentionally type the imported module as `any` here because
+  // `webview-bun` publishes types that depend on its FFI pointers. A tighter
+  // type contract is not worth pulling the peer's type graph into `core`.
+  // Consumers never see this — they work against WindowHandle.
+  Webview: new (
+    debug?: boolean,
+    size?: { width: number; height: number; hint: number } | null,
+    window?: unknown,
+  ) => {
+    title: string;
+    size: { width: number; height: number; hint: number };
+    navigate(url: string): void;
+    setHTML(html: string): void;
+    init(source: string): void;
+    eval(source: string): void;
+    bind(name: string, cb: (...args: unknown[]) => unknown): void;
+    unbind(name: string): void;
+    run(): void;
+    destroy(): void;
+  };
+  SizeHint: { NONE: number; MIN: number; MAX: number; FIXED: number };
+};
+
+let webviewBunCache: WebviewBunModule | null = null;
+
+/**
+ * Lazy-load `webview-bun`. Throws with an actionable error message when the
+ * peer is missing — the only surface on which end users hit this is desktop
+ * launch, so we can afford a long-form hint.
+ *
+ * @internal
+ */
+export async function _loadWebviewBun(): Promise<WebviewBunModule> {
+  if (webviewBunCache) return webviewBunCache;
+  try {
+    // Dynamic import so `bun test` in a CI without `webview-bun` installed
+    // still passes. The import specifier is a bare module — no file-path
+    // probing — so bundlers can tree-shake the whole desktop subtree in a
+    // web-only build.
+    //
+    // `@ts-ignore` is used because `webview-bun` is an OPTIONAL peer — tsc
+    // must not hard-fail module resolution when the peer is absent. The
+    // runtime behaviour is guarded: the try/catch below rethrows a clean
+    // "please install" error if the import itself rejects at runtime.
+    // @ts-ignore -- optional peer, may not be resolvable at typecheck time
+    const mod = (await import("webview-bun")) as unknown as WebviewBunModule;
+    webviewBunCache = mod;
+    return mod;
+  } catch (cause) {
+    throw new Error(
+      [
+        "[@mandujs/core/desktop] Failed to load the optional peer 'webview-bun'.",
+        "Install it alongside Mandu for desktop targets:",
+        "",
+        "    bun add webview-bun",
+        "",
+        "Then pin the version in package.json. Tested: ^2.4.0 (MIT).",
+        "Docs: https://github.com/tr1ckydev/webview-bun",
+      ].join("\n"),
+      { cause: cause as Error },
+    );
+  }
+}
+
+/**
+ * Reset the lazy-load cache. Tests only.
+ *
+ * @internal
+ */
+export function _resetWebviewBunCache(): void {
+  webviewBunCache = null;
+}
+
+// ─── Size hint mapping ──────────────────────────────────────────────────────
+
+/**
+ * Map the string hint to `webview-bun`'s `SizeHint` numeric enum. We accept
+ * the string because (a) the string survives Worker `postMessage` cleanly
+ * and (b) it doesn't pin our public API to the peer's enum numbering.
+ *
+ * @internal
+ */
+export function _mapSizeHint(
+  hint: WindowSizeHint | undefined,
+  enumRef: WebviewBunModule["SizeHint"],
+): number {
+  switch (hint) {
+    case "fixed":
+      return enumRef.FIXED;
+    case "min":
+      return enumRef.MIN;
+    case "max":
+      return enumRef.MAX;
+    case "none":
+    case undefined:
+    default:
+      return enumRef.NONE;
+  }
+}
+
+// ─── Option validation ──────────────────────────────────────────────────────
+
+/**
+ * Validates `options` before we touch the FFI peer. Throws `TypeError` on
+ * the first problem found.
+ *
+ * @internal
+ */
+export function _validateOptions(options: WindowOptions): void {
+  if (!options || typeof options !== "object") {
+    throw new TypeError(
+      "[@mandujs/core/desktop] createWindow: options must be an object.",
+    );
+  }
+  if (typeof options.url !== "string" || options.url.length === 0) {
+    throw new TypeError(
+      "[@mandujs/core/desktop] createWindow: 'url' must be a non-empty string.",
+    );
+  }
+  // Accept http/https/file/data — reject everything else. Remote URLs work
+  // but are actively discouraged; document that elsewhere.
+  const allowedProtocols = ["http:", "https:", "file:", "data:"];
+  let parsed: URL;
+  try {
+    parsed = new URL(options.url);
+  } catch {
+    throw new TypeError(
+      `[@mandujs/core/desktop] createWindow: 'url' is not a valid URL: ${JSON.stringify(
+        options.url,
+      )}.`,
+    );
+  }
+  if (!allowedProtocols.includes(parsed.protocol)) {
+    throw new TypeError(
+      `[@mandujs/core/desktop] createWindow: 'url' protocol ${parsed.protocol} is not allowed (use http/https/file/data).`,
+    );
+  }
+  if (options.width !== undefined) {
+    if (
+      typeof options.width !== "number" ||
+      !Number.isFinite(options.width) ||
+      options.width <= 0
+    ) {
+      throw new TypeError(
+        "[@mandujs/core/desktop] createWindow: 'width' must be a positive finite number.",
+      );
+    }
+  }
+  if (options.height !== undefined) {
+    if (
+      typeof options.height !== "number" ||
+      !Number.isFinite(options.height) ||
+      options.height <= 0
+    ) {
+      throw new TypeError(
+        "[@mandujs/core/desktop] createWindow: 'height' must be a positive finite number.",
+      );
+    }
+  }
+  if (
+    options.hint !== undefined &&
+    !["none", "min", "max", "fixed"].includes(options.hint)
+  ) {
+    throw new TypeError(
+      `[@mandujs/core/desktop] createWindow: 'hint' must be one of none|min|max|fixed (got ${JSON.stringify(
+        options.hint,
+      )}).`,
+    );
+  }
+  if (options.handlers !== undefined) {
+    if (typeof options.handlers !== "object" || options.handlers === null) {
+      throw new TypeError(
+        "[@mandujs/core/desktop] createWindow: 'handlers' must be an object of functions.",
+      );
+    }
+    for (const [name, fn] of Object.entries(options.handlers)) {
+      if (typeof fn !== "function") {
+        throw new TypeError(
+          `[@mandujs/core/desktop] createWindow: handlers.${name} must be a function.`,
+        );
+      }
+    }
+  }
+}
+
+// ─── Defaults ───────────────────────────────────────────────────────────────
+
+/** @internal */
+export const _DEFAULTS: Required<Pick<WindowOptions, "title" | "width" | "height" | "hint" | "debug">> = {
+  title: "Mandu Desktop",
+  width: 1024,
+  height: 768,
+  hint: "none",
+  debug: false,
+};
+
+// ─── createWindow ───────────────────────────────────────────────────────────
+
+/**
+ * Create a desktop window backed by the system WebView (WebView2 on Windows,
+ * WKWebView on macOS, WebKitGTK on Linux). Optional peer `webview-bun` must
+ * be installed.
+ *
+ * The returned {@link WindowHandle} does NOT auto-start the platform event
+ * loop — callers must either call `handle.run()` (blocking) or await
+ * `handle.closed`. In Worker-based setups the loop is typically started by
+ * the Worker host (see `./worker.ts`).
+ *
+ * @example Main-thread use (window only, no HTTP server):
+ * ```ts
+ * import { createWindow } from "@mandujs/core/desktop";
+ *
+ * const win = await createWindow({
+ *   url: "https://example.com",
+ *   title: "Read later",
+ *   width: 1200,
+ *   height: 800,
+ * });
+ * win.run(); // blocks until user closes
+ * ```
+ *
+ * @example With a Mandu server (Worker pattern — recommended):
+ * ```ts
+ * // main.ts
+ * import { startServer } from "@mandujs/core";
+ * import manifest from "../../.mandu/manifest.json" with { type: "json" };
+ *
+ * const server = startServer(manifest, { port: 0, hostname: "127.0.0.1" });
+ * const worker = new Worker(new URL("./worker.ts", import.meta.url));
+ * worker.postMessage({
+ *   type: "open",
+ *   options: { url: `http://127.0.0.1:${server.server.port}`, title: "My App" },
+ * });
+ * ```
+ */
+export async function createWindow(
+  options: WindowOptions,
+): Promise<WindowHandle> {
+  _validateOptions(options);
+
+  const { Webview, SizeHint } = await _loadWebviewBun();
+
+  const merged = {
+    ..._DEFAULTS,
+    ...options,
+  };
+  const hintNum = _mapSizeHint(merged.hint, SizeHint);
+
+  // Construct the webview. `webview-bun` uses constructor args for size+hint
+  // and exposes setters for title/size post-construction.
+  const wv = new Webview(merged.debug, {
+    width: merged.width,
+    height: merged.height,
+    hint: hintNum,
+  });
+
+  // Title must be set post-ctor — webview-bun API shape.
+  try {
+    wv.title = merged.title;
+  } catch (error) {
+    // Some libwebview builds throw if the window hasn't been realized yet;
+    // best-effort, not fatal.
+    if (merged.debug) {
+      console.warn("[@mandujs/core/desktop] title set warning:", error);
+    }
+  }
+
+  // Pre-register handlers BEFORE navigation so the page's first script doesn't
+  // see an undefined global.
+  if (options.handlers) {
+    for (const [name, fn] of Object.entries(options.handlers)) {
+      try {
+        wv.bind(name, fn);
+      } catch (error) {
+        throw new Error(
+          `[@mandujs/core/desktop] Failed to bind handler "${name}": ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }
+  }
+
+  // Set up closed-signal wiring. `webview-bun` does not expose a native
+  // close event, so we rely on `run()` returning OR an explicit `destroy()`
+  // call to flip the flag.
+  let closed = false;
+  let resolveClosed: (() => void) | null = null;
+  const closedPromise = new Promise<void>((resolve) => {
+    resolveClosed = resolve;
+  });
+  const closeCallbacks: Array<() => void> = [];
+
+  function markClosed(): void {
+    if (closed) return;
+    closed = true;
+    // Run user callbacks first so their exceptions don't prevent Promise
+    // resolution. We swallow exceptions to match `setTimeout` semantics.
+    for (const cb of closeCallbacks) {
+      try {
+        cb();
+      } catch (error) {
+        console.error(
+          "[@mandujs/core/desktop] onClose callback threw:",
+          error,
+        );
+      }
+    }
+    if (options.onClose) {
+      try {
+        const result = options.onClose();
+        if (result instanceof Promise) {
+          result.catch((error) =>
+            console.error(
+              "[@mandujs/core/desktop] onClose (options) threw:",
+              error,
+            ),
+          );
+        }
+      } catch (error) {
+        console.error(
+          "[@mandujs/core/desktop] onClose (options) threw:",
+          error,
+        );
+      }
+    }
+    resolveClosed?.();
+  }
+
+  // Navigate AFTER handlers are registered, so the first page load can
+  // already call any bound globals.
+  try {
+    wv.navigate(merged.url);
+  } catch (error) {
+    // Navigation failure is fatal — tear down and rethrow.
+    try {
+      wv.destroy();
+    } catch {
+      /* ignore cleanup errors */
+    }
+    throw new Error(
+      `[@mandujs/core/desktop] navigate() failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  // Fire onReady on the next microtask so callers that chain `await
+  // createWindow(...)` can attach listeners first.
+  if (options.onReady) {
+    queueMicrotask(() => {
+      try {
+        const result = options.onReady!();
+        if (result instanceof Promise) {
+          result.catch((error) =>
+            console.error(
+              "[@mandujs/core/desktop] onReady threw:",
+              error,
+            ),
+          );
+        }
+      } catch (error) {
+        console.error("[@mandujs/core/desktop] onReady threw:", error);
+      }
+    });
+  }
+
+  const handle: WindowHandle = {
+    async close() {
+      if (closed) return;
+      try {
+        wv.destroy();
+      } catch (error) {
+        // `webview-bun` #35: destroy() from a timer doesn't always interrupt
+        // run(). We still mark closed so the `closed` promise resolves — the
+        // native run() will exit on its own once the user closes the shell.
+        if (merged.debug) {
+          console.warn("[@mandujs/core/desktop] destroy() warning:", error);
+        }
+      }
+      markClosed();
+    },
+    onClose(cb: () => void) {
+      if (closed) {
+        // Match `addEventListener('load')` semantics on a ready document —
+        // fire on the next microtask so ordering is deterministic.
+        queueMicrotask(() => {
+          try {
+            cb();
+          } catch (error) {
+            console.error(
+              "[@mandujs/core/desktop] onClose callback threw:",
+              error,
+            );
+          }
+        });
+        return;
+      }
+      closeCallbacks.push(cb);
+    },
+    async eval(js: string) {
+      if (closed) {
+        throw new Error(
+          "[@mandujs/core/desktop] eval() called on closed window.",
+        );
+      }
+      if (typeof js !== "string" || js.length === 0) {
+        throw new TypeError(
+          "[@mandujs/core/desktop] eval: 'js' must be a non-empty string.",
+        );
+      }
+      wv.eval(js);
+    },
+    bind(name: string, fn: (...args: unknown[]) => unknown) {
+      if (closed) {
+        throw new Error(
+          "[@mandujs/core/desktop] bind() called on closed window.",
+        );
+      }
+      if (typeof name !== "string" || name.length === 0) {
+        throw new TypeError(
+          "[@mandujs/core/desktop] bind: 'name' must be a non-empty string.",
+        );
+      }
+      if (typeof fn !== "function") {
+        throw new TypeError(
+          "[@mandujs/core/desktop] bind: 'fn' must be a function.",
+        );
+      }
+      wv.bind(name, fn);
+    },
+    closed: closedPromise,
+    run() {
+      if (closed) {
+        // No-op — already closed. `webview-bun`'s run() on a destroyed
+        // instance would crash; avoid that class of footgun.
+        return;
+      }
+      try {
+        wv.run();
+      } finally {
+        // run() returned → the window was closed (either natively or via
+        // destroy()). Flip the flag.
+        markClosed();
+      }
+    },
+  };
+
+  return handle;
+}