@mandujs/core 0.22.1 → 0.23.0

package/src/desktop/__tests__/webview-fallback.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Phase 11 C / M-02 — FFI fallback unit tests.
+ *
+ * Scope:
+ *   1. The module imports cleanly even when the webview-bun peer and the
+ *      libwebview shared library are BOTH absent. Phase 9 released the
+ *      barrel as importable under these conditions; Phase 11 C preserves
+ *      that invariant for the fallback.
+ *   2. `_ffiSymbols` shape is frozen — matches the upstream C ABI we
+ *      pinned in `webview-fallback.ts` header.
+ *   3. `_mapHintToInt` mirrors the upstream `WEBVIEW_HINT_*` enum.
+ *   4. `_getLibraryCandidates()` probes the three expected slots
+ *      (env var → package-relative mirror → system default).
+ *   5. `createFallbackWebview` rejects bad options BEFORE any `dlopen`
+ *      attempt, so a CI without libwebview still passes.
+ *   6. `loadFFILibwebview` failure yields a user-actionable error
+ *      message enumerating every probed path.
+ *   7. (opt-in E2E) On a machine with libwebview installed, a real
+ *      window can be created via the fallback. Gated by
+ *      `MANDU_DESKTOP_FALLBACK_E2E=1`.
+ *
+ * These tests deliberately exercise the FFI contract WITHOUT actually
+ * dlopening the library — CI cannot assume libwebview is installed. The
+ * opt-in block (test 7) is only active under an explicit env flag.
+ *
+ * References:
+ *   docs/bun/phase-9-diagnostics/webview-bun-ffi.md §8 (fallback design)
+ *   packages/core/src/desktop/webview-fallback.ts
+ */
+
+import {
+  describe,
+  it,
+  expect,
+  beforeEach,
+  afterEach,
+} from "bun:test";
+
+describe("@mandujs/core/desktop/webview-fallback — module import", () => {
+  it("imports without loading libwebview", async () => {
+    // The import itself must succeed even when `bun:ffi.dlopen` would
+    // fail (no libwebview). Module-level code must not `dlopen` — that
+    // happens only on `createFallbackWebview()`.
+    const mod = await import("../webview-fallback");
+    expect(typeof mod.createFallbackWebview).toBe("function");
+    expect(typeof mod.loadFFILibwebview).toBe("function");
+    expect(typeof mod._mapHintToInt).toBe("function");
+    expect(typeof mod._getLibraryCandidates).toBe("function");
+    expect(typeof mod._defaultLibName).toBe("function");
+    expect(typeof mod._resetFFICache).toBe("function");
+  });
+
+  it("module import is idempotent — cache loader does not fire on import", async () => {
+    // Import twice; neither call should throw. If `import.meta.url`-based
+    // candidate probing has a side effect, that would manifest on the
+    // second call.
+    const a = await import("../webview-fallback");
+    const b = await import("../webview-fallback");
+    expect(a).toBe(b); // same module instance from Bun's ESM cache
+  });
+});
+
+describe("@mandujs/core/desktop/webview-fallback — FFI symbol contract", () => {
+  it("_ffiSymbols declares the minimal webview C ABI we depend on", async () => {
+    const { _ffiSymbols } = await import("../webview-fallback");
+    // The set of symbols MUST match the upstream webview.h surface we
+    // pinned in Phase 11 C. Test the shape, not the exact order.
+    const expected = [
+      "webview_create",
+      "webview_navigate",
+      "webview_set_title",
+      "webview_set_size",
+      "webview_set_html",
+      "webview_run",
+      "webview_terminate",
+      "webview_destroy",
+    ];
+    for (const sym of expected) {
+      expect(_ffiSymbols).toHaveProperty(sym);
+      const entry = (_ffiSymbols as Record<string, { args: unknown; returns: unknown }>)[sym];
+      expect(Array.isArray(entry.args)).toBe(true);
+      expect(typeof entry.returns).toBe("string");
+    }
+  });
+
+  it("_ffiSymbols is frozen — no mutation allowed at runtime", async () => {
+    const { _ffiSymbols } = await import("../webview-fallback");
+    expect(Object.isFrozen(_ffiSymbols)).toBe(true);
+  });
+
+  it("webview_create returns a pointer and takes (i32, ptr)", async () => {
+    const { _ffiSymbols } = await import("../webview-fallback");
+    expect(_ffiSymbols.webview_create.args).toEqual(["i32", "ptr"]);
+    expect(_ffiSymbols.webview_create.returns).toBe("ptr");
+  });
+
+  it("webview_set_size has 4 args matching (ptr,i32,i32,i32)", async () => {
+    const { _ffiSymbols } = await import("../webview-fallback");
+    expect(_ffiSymbols.webview_set_size.args).toEqual([
+      "ptr",
+      "i32",
+      "i32",
+      "i32",
+    ]);
+  });
+});
+
+describe("@mandujs/core/desktop/webview-fallback — _mapHintToInt", () => {
+  it("matches WEBVIEW_HINT_* enum values from upstream webview.h", async () => {
+    const { _mapHintToInt } = await import("../webview-fallback");
+    expect(_mapHintToInt("none")).toBe(0);
+    expect(_mapHintToInt("min")).toBe(1);
+    expect(_mapHintToInt("max")).toBe(2);
+    expect(_mapHintToInt("fixed")).toBe(3);
+    expect(_mapHintToInt(undefined)).toBe(0);
+  });
+});
+
+describe("@mandujs/core/desktop/webview-fallback — library candidate probe", () => {
+  const ORIGINAL_ENV = process.env.MANDU_LIBWEBVIEW_PATH;
+
+  beforeEach(() => {
+    delete process.env.MANDU_LIBWEBVIEW_PATH;
+  });
+
+  afterEach(() => {
+    if (ORIGINAL_ENV !== undefined) {
+      process.env.MANDU_LIBWEBVIEW_PATH = ORIGINAL_ENV;
+    } else {
+      delete process.env.MANDU_LIBWEBVIEW_PATH;
+    }
+  });
+
+  it("_getLibraryCandidates includes the system default when no env is set", async () => {
+    const { _getLibraryCandidates, _defaultLibName } = await import(
+      "../webview-fallback"
+    );
+    const candidates = _getLibraryCandidates();
+    expect(candidates.length).toBeGreaterThanOrEqual(1);
+    // Last candidate is always the bare lib name.
+    expect(candidates[candidates.length - 1]).toBe(_defaultLibName());
+  });
+
+  it("_getLibraryCandidates prepends MANDU_LIBWEBVIEW_PATH when set", async () => {
+    process.env.MANDU_LIBWEBVIEW_PATH = "/opt/custom/libwebview.so";
+    const { _getLibraryCandidates } = await import("../webview-fallback");
+    const candidates = _getLibraryCandidates();
+    expect(candidates[0]).toBe("/opt/custom/libwebview.so");
+  });
+
+  it("_defaultLibName maps to platform extension", async () => {
+    const { _defaultLibName } = await import("../webview-fallback");
+    const name = _defaultLibName();
+    if (process.platform === "win32") expect(name).toBe("libwebview.dll");
+    else if (process.platform === "darwin")
+      expect(name).toBe("libwebview.dylib");
+    else expect(name).toBe("libwebview.so");
+  });
+});
+
+describe("@mandujs/core/desktop/webview-fallback — createFallbackWebview", () => {
+  it("rejects missing options before any dlopen attempt", async () => {
+    const { createFallbackWebview } = await import("../webview-fallback");
+    // An empty-object options bag must be caught by defensive guards
+    // BEFORE we touch the FFI peer — so this test passes on CI without
+    // libwebview.
+    await expect(
+      createFallbackWebview({} as never),
+    ).rejects.toThrow(TypeError);
+  });
+
+  it("rejects non-string url before any dlopen attempt", async () => {
+    const { createFallbackWebview } = await import("../webview-fallback");
+    await expect(
+      createFallbackWebview({ url: 42 as unknown as string }),
+    ).rejects.toThrow(TypeError);
+  });
+
+  it("rejects empty url before any dlopen attempt", async () => {
+    const { createFallbackWebview } = await import("../webview-fallback");
+    await expect(
+      createFallbackWebview({ url: "" }),
+    ).rejects.toThrow(TypeError);
+  });
+});
+
+describe("@mandujs/core/desktop/webview-fallback — loadFFILibwebview failure surface", () => {
+  const ORIGINAL_ENV = process.env.MANDU_LIBWEBVIEW_PATH;
+
+  beforeEach(async () => {
+    // Force an unreachable path so the loader's failure hint is
+    // exercised without depending on the actual libwebview install
+    // state of the CI runner.
+    process.env.MANDU_LIBWEBVIEW_PATH =
+      "/path/that/definitely/does/not/exist/libwebview.so";
+    const mod = await import("../webview-fallback");
+    mod._resetFFICache();
+  });
+
+  afterEach(async () => {
+    if (ORIGINAL_ENV !== undefined) {
+      process.env.MANDU_LIBWEBVIEW_PATH = ORIGINAL_ENV;
+    } else {
+      delete process.env.MANDU_LIBWEBVIEW_PATH;
+    }
+    const mod = await import("../webview-fallback");
+    mod._resetFFICache();
+  });
+
+  it("throws an actionable error enumerating every probed path", async () => {
+    const { loadFFILibwebview } = await import("../webview-fallback");
+    try {
+      await loadFFILibwebview();
+      throw new Error("unreachable — loadFFILibwebview should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      const msg = (err as Error).message;
+      // Actionable hints — install options + env var hint.
+      expect(msg).toContain("libwebview");
+      expect(msg).toContain("MANDU_LIBWEBVIEW_PATH");
+      expect(msg).toContain("webview/webview");
+      // Should enumerate the failing candidate we injected.
+      expect(msg).toContain("libwebview.so");
+    }
+  });
+});
+
+// ─── Opt-in E2E (real window) ──────────────────────────────────────────────
+//
+// Runs ONLY when MANDU_DESKTOP_FALLBACK_E2E=1 AND platform supports it.
+// CI skips this block unconditionally.
+
+const canOpenFallbackWindow =
+  process.env.MANDU_DESKTOP_FALLBACK_E2E === "1" &&
+  (process.platform === "win32" ||
+    process.platform === "darwin" ||
+    process.platform === "linux");
+
+describe.skipIf(!canOpenFallbackWindow)(
+  "@mandujs/core/desktop/webview-fallback — browser smoke (opt-in)",
+  () => {
+    it("opens a data: URL window via the FFI fallback", async () => {
+      const { createFallbackWebview } = await import("../webview-fallback");
+      const handle = await createFallbackWebview({
+        url: "data:text/html,<h1>Mandu FFI fallback smoke</h1>",
+        title: "Mandu Fallback E2E",
+        width: 400,
+        height: 300,
+      });
+      await handle.close();
+      await handle.closed;
+    });
+  },
+);

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

@@ -165,8 +165,84 @@ describe("@mandujs/core/desktop — createWindow peer loading", () => {
       return;
     }
 
-    await expect(
-      createWindow({ url: "http://127.0.0.1:1" }),
-    ).rejects.toThrow(/webview-bun/);
+    // Ensure the FFI fallback also can't resolve — otherwise `createWindow`
+    // silently flips to the FFI path. We force an unreachable library path
+    // so both paths deterministically fail, which is the state the
+    // actionable error contract guards.
+    const originalFFIPath = process.env.MANDU_LIBWEBVIEW_PATH;
+    process.env.MANDU_LIBWEBVIEW_PATH =
+      "/path/that/does/not/exist/libwebview.so";
+    try {
+      await expect(
+        createWindow({ url: "http://127.0.0.1:1" }),
+      ).rejects.toThrow(/webview-bun/);
+    } finally {
+      if (originalFFIPath !== undefined) {
+        process.env.MANDU_LIBWEBVIEW_PATH = originalFFIPath;
+      } else {
+        delete process.env.MANDU_LIBWEBVIEW_PATH;
+      }
+    }
+  });
+
+  it("MANDU_DESKTOP_INLINE_FFI=1 routes to the FFI fallback path", async () => {
+    // With the env flag set, `createWindow` must import
+    // `./webview-fallback` instead of `webview-bun`. We don't assert on
+    // the exact success/failure of the FFI call (that depends on the
+    // machine's libwebview install state) — we only assert that the
+    // branch is taken. The simplest observable is: when the library
+    // actually loads AND the test machine has a webview backend
+    // (WebView2 on Windows etc.), a real window would open. To stay
+    // CI-safe we monkey-patch dynamic import of the fallback module to
+    // detect invocation.
+    //
+    // Bun's ESM cache makes this tricky — instead we verify the call
+    // selector by checking that `createWindow` does NOT throw the
+    // webview-bun "install me" error when the flag is set. That error
+    // is only reachable via the primary `_loadWebviewBun` path; if the
+    // FFI branch is skipped or the webview-bun import is tried in its
+    // place, the test would observe the install-me error.
+    const originalFlag = process.env.MANDU_DESKTOP_INLINE_FFI;
+    const originalFFIPath = process.env.MANDU_LIBWEBVIEW_PATH;
+    process.env.MANDU_DESKTOP_INLINE_FFI = "1";
+    // Force an unreachable libwebview so the fallback fails deterministically
+    // and the error surfaces the fallback's distinctive language (which
+    // is what we assert on).
+    process.env.MANDU_LIBWEBVIEW_PATH = "/nonexistent/libwebview-test-stub.so";
+
+    try {
+      // Resolve whatever error comes back and assert it's NOT the
+      // webview-bun peer-missing error. The exact failure mode of the
+      // FFI path varies by CI machine (libwebview missing, dlopen
+      // succeeds on a stub, or the FFI cstring call errors), but none
+      // of those produce the distinctive "bun add webview-bun" string
+      // from the primary path.
+      let caught: unknown;
+      try {
+        const handle = await createWindow({ url: "http://127.0.0.1:1" });
+        // Unexpected success — close to clean up, then fail.
+        await handle.close();
+        throw new Error(
+          "unreachable — createWindow should fail with MANDU_DESKTOP_INLINE_FFI=1 + bogus MANDU_LIBWEBVIEW_PATH",
+        );
+      } catch (err) {
+        caught = err;
+      }
+      const msg = caught instanceof Error ? caught.message : String(caught);
+      // The webview-bun install-me message always mentions "bun add webview-bun".
+      // The fallback path's failure never does.
+      expect(msg).not.toContain("bun add webview-bun");
+    } finally {
+      if (originalFlag !== undefined) {
+        process.env.MANDU_DESKTOP_INLINE_FFI = originalFlag;
+      } else {
+        delete process.env.MANDU_DESKTOP_INLINE_FFI;
+      }
+      if (originalFFIPath !== undefined) {
+        process.env.MANDU_LIBWEBVIEW_PATH = originalFFIPath;
+      } else {
+        delete process.env.MANDU_LIBWEBVIEW_PATH;
+      }
+    }
   });
 });