@mandujs/core 0.22.1 → 0.24.0

package/src/bundler/safe-build.test.ts

@@ -125,4 +125,58 @@ describe("safeBuild", () => {
     expect(state.active).toBe(0);
     expect(state.queued).toBe(0);
   });
+
+  it("slot handoff — new callers cannot bypass queued waiters (regression for cap+1 race)", async () => {
+    // Scenario: a build completes with a waiter queued; a NEW safeBuild call
+    // fires on the same microtask. A prior revision decremented `active`
+    // before resolving the waiter, leaving a microtask-sized window where
+    // the new caller saw `active < max`, skipped the wait, and became the
+    // cap+1 concurrent build. This test launches 3*max + 1 builds, samples
+    // active at every slot release, and asserts the peak never exceeds max.
+    const { max } = _getConcurrencyState();
+    const N = max * 3 + 1; // always enough to trigger at least one handoff
+    const entries = await Promise.all(
+      Array.from({ length: N }, (_, i) => makeEntry(`handoff-${i}`)),
+    );
+
+    let peak = 0;
+    let samples = 0;
+    // Sample at microtask granularity — more aggressive than the setInterval
+    // sampler in the earlier test — so the cap+1 window has a realistic
+    // chance of being observed if the bug returned.
+    let stop = false;
+    const sample = async () => {
+      while (!stop) {
+        const { active } = _getConcurrencyState();
+        if (active > peak) peak = active;
+        samples++;
+        await Promise.resolve(); // yield to microtask queue
+      }
+    };
+    const sampler = sample();
+
+    try {
+      const results = await Promise.all(
+        entries.map((entry) =>
+          safeBuild({
+            entrypoints: [entry],
+            outdir: rootDir,
+            target: "browser",
+            naming: path.basename(entry, ".ts") + ".[ext]",
+          }),
+        ),
+      );
+      expect(results.every((r) => r.success)).toBe(true);
+    } finally {
+      stop = true;
+      await sampler;
+    }
+
+    expect(peak).toBeLessThanOrEqual(max);
+    expect(samples).toBeGreaterThan(0);
+
+    const state = _getConcurrencyState();
+    expect(state.active).toBe(0);
+    expect(state.queued).toBe(0);
+  });
 });

package/src/bundler/safe-build.ts

@@ -20,6 +20,15 @@
  * - In-process only. Cross-worker coordination is not this module's job;
  *   per-worker throttling already prevents the observed failure modes in
  *   our test matrix.
+ *
+ * Correctness — slot handoff:
+ * - The semaphore does slot *handoff* rather than release-then-acquire. When
+ *   a build completes with waiters queued, the slot is transferred directly
+ *   to the next waiter (active count never drops). A previous revision had
+ *   a classic acquire race: `releaseSlot()` decremented `active` before the
+ *   waiter's `active++` ran, which opened a microtask-sized window where a
+ *   concurrent `safeBuild()` call could observe `active < max`, skip the
+ *   wait, and join in — yielding `cap+1` concurrent builds.
  */
 
 import type { BuildConfig, BuildOutput } from "bun";
@@ -38,16 +47,36 @@ const maxConcurrent = parseMaxConcurrent();
 let active = 0;
 const waiters: Array<() => void> = [];
 
-function waitForSlot(): Promise<void> {
+/**
+ * Acquire a slot. When `active < max`, increment synchronously and return.
+ * Otherwise, queue and await a direct handoff from a completing build —
+ * the completing build does NOT decrement `active`; it resolves our waiter,
+ * and `active` stays at `max` through the transition. This prevents a
+ * microtask-window race where a third caller could see `active < max` and
+ * skip the wait entirely.
+ */
+function acquireSlot(): Promise<void> {
+  if (active < maxConcurrent) {
+    active++;
+    return Promise.resolve();
+  }
   return new Promise<void>((resolve) => {
     waiters.push(resolve);
   });
 }
 
+/**
+ * Release a slot. If a waiter is queued, hand the slot off directly (keep
+ * `active` at `max`, resolve the waiter). Otherwise decrement `active`.
+ */
 function releaseSlot(): void {
-  active--;
   const next = waiters.shift();
-  if (next) next();
+  if (next) {
+    // Direct handoff — `active` stays at max, waiter resumes holding the slot.
+    next();
+  } else {
+    active--;
+  }
 }
 
 /**
@@ -60,10 +89,7 @@ function releaseSlot(): void {
  * coordination work.
  */
 export async function safeBuild(options: BuildConfig): Promise<BuildOutput> {
-  if (active >= maxConcurrent) {
-    await waitForSlot();
-  }
-  active++;
+  await acquireSlot();
   try {
     return await Bun.build(options);
   } finally {

package/src/client/prefetch-helper.ts

@@ -0,0 +1,55 @@
+/**
+ * Issue #192 — Hover prefetch helper
+ *
+ * Self-contained IIFE that watches `mouseover` events bubbling from
+ * internal `<a href="/...">` anchors and issues a one-shot
+ * `<link rel="prefetch" as="document">` per unique anchor. The browser
+ * cache services the subsequent full-reload navigation, so most
+ * above-the-fold links feel instantaneous without requiring a SPA
+ * runtime.
+ *
+ * Design choices (locked to keep the payload tiny — target ≤500 bytes
+ * minified + gzipped):
+ *
+ *   1. **WeakSet-based dedup**: we never attach per-anchor listeners;
+ *      we use a single `document`-level capture listener and stamp
+ *      each anchor we've seen into a `WeakSet`. Anchors removed from
+ *      the DOM collect automatically.
+ *
+ *   2. **Scope: same-origin `/...` paths only**: we deliberately skip
+ *      absolute URLs, `mailto:`, `tel:`, `javascript:`, hash-only
+ *      fragments, and `#`-on-same-page links. The `a[href^="/"]`
+ *      selector implicitly covers this and avoids a surprise
+ *      cross-origin DNS lookup.
+ *
+ *   3. **Opt-out per-link via `data-no-prefetch`**: mirrors Next.js'
+ *      `prefetch={false}` ergonomics while being framework-agnostic —
+ *      works with plain `<a>` and with Mandu's `<Link>` component.
+ *
+ *   4. **`as="document"` hint**: the correct token for HTML documents
+ *      that will be navigated to via a subsequent click. Without it
+ *      Chrome 121+ logs a `rel=prefetch as=missing` warning.
+ *
+ *   5. **Capture phase + `passive: true`**: listening in the capture
+ *      phase catches the event before any app-level bubble handlers
+ *      can cancel it (defensive against apps that `stopPropagation`
+ *      on `<a>`). `passive` ensures we can never accidentally block
+ *      scroll.
+ *
+ *   6. **Inline, not external bundle**: the helper is under 1KB and
+ *      emitting it as a `<script>` child (rather than
+ *      `<script src=".../_prefetch.js">`) avoids one HTTP round-trip
+ *      on every SSR response and keeps the module graph unchanged.
+ *
+ * The exported `PREFETCH_HELPER_SCRIPT` wraps the IIFE in a
+ * `<script>` tag, ready to paste into `<head>`. Callers MUST keep it
+ * nonce-aware if they plan to enable CSP (future work — right now the
+ * Fast Refresh preamble is the only inline script covered by Mandu's
+ * CSP header).
+ */
+
+/** Inner IIFE — exposed for unit tests that want to parse the source. */
+export const PREFETCH_HELPER_BODY = `(function(){var s=new WeakSet();document.addEventListener("mouseover",function(e){var t=e.target;if(!t||typeof t.closest!=="function")return;var a=t.closest("a[href^='/']");if(!a||s.has(a))return;if(a.dataset&&a.dataset.noPrefetch!==undefined)return;if(a.hasAttribute&&a.hasAttribute("download"))return;if(a.target&&a.target!=="_self")return;s.add(a);try{var l=document.createElement("link");l.rel="prefetch";l.href=a.href;l.as="document";document.head.appendChild(l);}catch(_){}},{passive:true,capture:true});})();`;
+
+/** Ready-to-inject `<script>` tag for SSR `<head>` injection. */
+export const PREFETCH_HELPER_SCRIPT = `<script>${PREFETCH_HELPER_BODY}</script>`;

package/src/config/mandu.ts

@@ -5,8 +5,97 @@ import type { ManduPlugin, ManduHooks } from "../plugins/hooks";
 
 export type GuardRuleSeverity = "error" | "warn" | "warning" | "off";
 
+/**
+ * Test block configuration (Phase 12.1 — testing ecosystem).
+ *
+ * Shapes the CLI `mandu test` command's discovery, fixture, and reporter
+ * behaviour. All fields are optional; omitting the block yields sensible
+ * defaults that match Next.js / SvelteKit user expectations:
+ *
+ *   - unit    → `**\/*.test.ts` / `**\/*.test.tsx`, 30s timeout
+ *   - integration → `tests/integration/**\/*.test.ts`, in-memory fixtures
+ *   - e2e     → reserved for Phase 12.2 (ATE integration)
+ *   - coverage → reserved for Phase 12.3 (bun + playwright merge)
+ */
+export interface TestUnitConfig {
+  /** Glob patterns for unit test files. Default: `["**\/*.test.ts", "**\/*.test.tsx"]`. */
+  include?: string[];
+  /** Glob patterns to exclude (applied after `include`). Default: `["node_modules/**", ".mandu/**", "dist/**"]`. */
+  exclude?: string[];
+  /** Per-test timeout in milliseconds. Default: `30_000` (30s). */
+  timeout?: number;
+}
+
+export interface TestIntegrationConfig {
+  /** Glob patterns for integration test files. Default: `["tests/integration/**\/*.test.ts"]`. */
+  include?: string[];
+  /** Glob patterns to exclude. Default: same as unit defaults. */
+  exclude?: string[];
+  /**
+   * Database URL for fixtures. Default: `"sqlite::memory:"` (in-memory SQLite).
+   * Accepts any Bun.sql-compatible URL — see `@mandujs/core/db` for the schema matrix.
+   */
+  dbUrl?: string;
+  /**
+   * Session storage strategy for `createTestSession`.
+   * - `"memory"` (default): CookieSessionStorage with ephemeral secret
+   * - `"sqlite"`: bun:sqlite-backed (Phase 2.5 storage, requires Phase 4)
+   */
+  sessionStore?: "memory" | "sqlite";
+  /** Per-test timeout. Default: `60_000` (60s — integration work is slower). */
+  timeout?: number;
+}
+
+export interface TestE2EConfig {
+  /** Reserved for Phase 12.2. Currently a typed placeholder. */
+  reserved?: true;
+}
+
+export interface TestCoverageConfig {
+  /** Minimum line coverage percentage (0-100). Reserved for Phase 12.3. */
+  lines?: number;
+  /** Minimum branch coverage percentage (0-100). Reserved for Phase 12.3. */
+  branches?: number;
+}
+
+export interface TestConfig {
+  unit?: TestUnitConfig;
+  integration?: TestIntegrationConfig;
+  e2e?: TestE2EConfig;
+  coverage?: TestCoverageConfig;
+}
+
 export interface ManduConfig {
   adapter?: ManduAdapter;
+  /**
+   * Issue #192 — Enable CSS View Transitions for cross-document
+   * navigations. When `true` (default) Mandu injects
+   * `<style>@view-transition { navigation: auto; }</style>` into the SSR
+   * `<head>`, which lets supporting browsers (Chrome/Edge ≥ 111) play a
+   * crossfade between the outgoing and incoming pages. Non-supporting
+   * browsers ignore the at-rule and fall back to the classic
+   * full-reload — zero regression.
+   *
+   * Set to `false` to opt out entirely (e.g. if your app ships a
+   * hand-rolled navigation animation or a conflicting CSS rule).
+   *
+   * Default: `true`.
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — Enable hover-based link prefetch. When `true` (default)
+   * Mandu injects a ~500-byte inline script that listens for `mouseover`
+   * events on internal links (`<a href="/...">`) and issues a
+   * `<link rel="prefetch">` for each unique target. The browser's HTTP
+   * cache services the subsequent navigation, removing most of the TTFB
+   * for above-the-fold links.
+   *
+   * Per-link opt-out: add `data-no-prefetch` to an `<a>` tag to skip it.
+   * Global opt-out: set this field to `false`.
+   *
+   * Default: `true`.
+   */
+  prefetch?: boolean;
   server?: {
     port?: number;
     hostname?: string;
@@ -47,6 +136,21 @@ export interface ManduConfig {
     watchDirs?: string[];
     /** Observability SQLite 영구 저장 (기본: true) */
     observability?: boolean;
+    /**
+     * Issue #191 — Dev-only `_devtools.js` (~1.15 MB React dev runtime +
+     * Mandu Kitchen panel) injection override.
+     *
+     *   - `true`      → force inject on every page (SSR-only projects that
+     *                   still want the Kitchen panel in dev).
+     *   - `false`     → force skip on every page (Kitchen-off dev loop).
+     *   - `undefined` → default. Inject iff the page's bundle manifest
+     *                   has at least one island. Pure-SSR pages download
+     *                   zero devtools bytes.
+     *
+     * Production builds never emit `_devtools.js`, so this flag is
+     * a no-op in prod regardless of value.
+     */
+    devtools?: boolean;
   };
   fsRoutes?: {
     routesDir?: string;
@@ -59,6 +163,8 @@ export interface ManduConfig {
     defaultTitle?: string;
     titleTemplate?: string;
   };
+  /** Phase 12.1 — `mandu test` configuration block. */
+  test?: TestConfig;
   plugins?: ManduPlugin[];
   hooks?: Partial<ManduHooks>;
 }

package/src/config/validate.ts

@@ -41,7 +41,9 @@ function strictWithWarnings<T extends z.ZodRawShape>(
 const ServerConfigSchema = z
   .object({
     port: z.number().min(1).max(65535).default(3000),
-    hostname: z.string().default("localhost"),
+    // Default 0.0.0.0 so IPv4 `localhost` resolution (Windows default) succeeds.
+    // Users may pin "::1" or "127.0.0.1" explicitly. See issue #190.
+    hostname: z.string().default("0.0.0.0"),
     cors: z
       .union([
         z.boolean(),
@@ -101,6 +103,13 @@ const DevConfigSchema = z
     hmr: z.boolean().default(true),
     watchDirs: z.array(z.string()).default([]),
     observability: z.boolean().default(true),
+    /**
+     * Issue #191 — `_devtools.js` (~1.15 MB React dev runtime + Kitchen
+     * panel) injection override. `undefined` (omitted) = default
+     * auto-detect based on `manifest.hasIslands`. Explicit `true` / `false`
+     * force on / off. Only applies in dev mode.
+     */
+    devtools: z.boolean().optional(),
   })
   .strict();
 
@@ -127,6 +136,59 @@ const SeoConfigSchema = z
   })
   .strict();
 
+/**
+ * Test 설정 스키마 (Phase 12.1 — strict)
+ *
+ * `.strict()` is applied at every nested object so stale / misspelt keys
+ * are caught at config-load time, not when the CLI trips over them. Each
+ * default mirrors the TypeScript documentation in `./mandu.ts`.
+ */
+const TestUnitConfigSchema = z
+  .object({
+    include: z.array(z.string().min(1)).default(["**/*.test.ts", "**/*.test.tsx"]),
+    exclude: z
+      .array(z.string().min(1))
+      .default(["node_modules/**", ".mandu/**", "dist/**"]),
+    timeout: z.number().int().positive().default(30_000),
+  })
+  .strict();
+
+const TestIntegrationConfigSchema = z
+  .object({
+    include: z
+      .array(z.string().min(1))
+      .default(["tests/integration/**/*.test.ts", "tests/integration/**/*.test.tsx"]),
+    exclude: z
+      .array(z.string().min(1))
+      .default(["node_modules/**", ".mandu/**", "dist/**"]),
+    dbUrl: z.string().min(1).default("sqlite::memory:"),
+    sessionStore: z.enum(["memory", "sqlite"]).default("memory"),
+    timeout: z.number().int().positive().default(60_000),
+  })
+  .strict();
+
+const TestE2EConfigSchema = z
+  .object({
+    reserved: z.literal(true).optional(),
+  })
+  .strict();
+
+const TestCoverageConfigSchema = z
+  .object({
+    lines: z.number().min(0).max(100).optional(),
+    branches: z.number().min(0).max(100).optional(),
+  })
+  .strict();
+
+const TestConfigSchema = z
+  .object({
+    unit: TestUnitConfigSchema.default({}),
+    integration: TestIntegrationConfigSchema.default({}),
+    e2e: TestE2EConfigSchema.default({}),
+    coverage: TestCoverageConfigSchema.default({}),
+  })
+  .strict();
+
 const AdapterConfigSchema = z.custom<ManduAdapter | undefined>(
   (value) =>
     value === undefined ||
@@ -165,12 +227,23 @@ const ManduHooksSchema = z.custom<Partial<ManduHooks>>(
 export const ManduConfigSchema = z
   .object({
     adapter: AdapterConfigSchema.optional(),
+    /**
+     * Issue #192 — CSS View Transitions auto-inject. Default `true`.
+     * Set `false` to suppress the `@view-transition` `<style>` block.
+     */
+    transitions: z.boolean().default(true),
+    /**
+     * Issue #192 — Hover prefetch helper. Default `true`.
+     * Set `false` to suppress the ~500-byte prefetch IIFE.
+     */
+    prefetch: z.boolean().default(true),
     server: ServerConfigSchema.default({}),
     guard: GuardConfigSchema.default({}),
     build: BuildConfigSchema.default({}),
     dev: DevConfigSchema.default({}),
     fsRoutes: FsRoutesConfigSchema.default({}),
     seo: SeoConfigSchema.default({}),
+    test: TestConfigSchema.default({}),
     plugins: z.array(ManduPluginSchema).optional(),
     hooks: ManduHooksSchema.optional(),
   })
@@ -178,6 +251,19 @@ export const ManduConfigSchema = z
 
 export type ValidatedManduConfig = z.infer<typeof ManduConfigSchema>;
 
+/** Validated `test` block (convenience re-export for fixtures/CLI). */
+export type ValidatedTestConfig = z.infer<typeof TestConfigSchema>;
+
+/**
+ * Resolve the `test` block with defaults filled in.
+ *
+ * Use this from fixtures / CLI test runners that need a guaranteed-shaped
+ * object without having to validate the whole config.
+ */
+export function resolveTestConfig(raw?: unknown): ValidatedTestConfig {
+  return TestConfigSchema.parse(raw ?? {});
+}
+
 /**
  * 검증 결과
  */

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;
+    });
+  },
+);