@mandujs/core 0.23.0 → 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

@@ -1,172 +1,216 @@
-import path from "path";
-import { readJsonFile } from "../utils/bun";
-import type { ManduAdapter } from "../runtime/adapter";
-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;
-  server?: {
-    port?: number;
-    hostname?: string;
-    cors?:
-      | boolean
-      | {
-          origin?: string | string[];
-          methods?: string[];
-          credentials?: boolean;
-        };
-    streaming?: boolean;
-    rateLimit?:
-      | boolean
-      | {
-          windowMs?: number;
-          max?: number;
-          message?: string;
-          statusCode?: number;
-          headers?: boolean;
-        };
-  };
-  guard?: {
-    preset?: "mandu" | "fsd" | "clean" | "hexagonal" | "atomic" | "cqrs";
-    srcDir?: string;
-    exclude?: string[];
-    realtime?: boolean;
-    rules?: Record<string, GuardRuleSeverity>;
-    contractRequired?: GuardRuleSeverity;
-  };
-  build?: {
-    outDir?: string;
-    minify?: boolean;
-    sourcemap?: boolean;
-    splitting?: boolean;
-  };
-  dev?: {
-    hmr?: boolean;
-    watchDirs?: string[];
-    /** Observability SQLite 영구 저장 (기본: true) */
-    observability?: boolean;
-  };
-  fsRoutes?: {
-    routesDir?: string;
-    extensions?: string[];
-    exclude?: string[];
-    islandSuffix?: string;
-  };
-  seo?: {
-    enabled?: boolean;
-    defaultTitle?: string;
-    titleTemplate?: string;
-  };
-  /** Phase 12.1 — `mandu test` configuration block. */
-  test?: TestConfig;
-  plugins?: ManduPlugin[];
-  hooks?: Partial<ManduHooks>;
-}
-
-export const CONFIG_FILES = [
-  "mandu.config.ts",
-  "mandu.config.js",
-  "mandu.config.json",
-  path.join(".mandu", "guard.json"),
-];
-
-export function coerceConfig(raw: unknown, source: string): ManduConfig {
-  if (!raw || typeof raw !== "object") return {};
-
-  // .mandu/guard.json can be guard-only
-  if (source.endsWith("guard.json") && !("guard" in (raw as Record<string, unknown>))) {
-    return { guard: raw as ManduConfig["guard"] };
-  }
-
-  return raw as ManduConfig;
-}
-
-export async function loadManduConfig(rootDir: string): Promise<ManduConfig> {
-  for (const fileName of CONFIG_FILES) {
-    const filePath = path.join(rootDir, fileName);
-    if (!(await Bun.file(filePath).exists())) {
-      continue;
-    }
-
-    if (fileName.endsWith(".json")) {
-      try {
-        const parsed = await readJsonFile(filePath);
-        return coerceConfig(parsed, fileName);
-      } catch {
-        return {};
-      }
-    }
-
-    try {
-      const module = await import(filePath);
-      const raw = module?.default ?? module;
-      return coerceConfig(raw, fileName);
-    } catch {
-      return {};
-    }
-  }
-
-  return {};
-}
+import path from "path";
+import { readJsonFile } from "../utils/bun";
+import type { ManduAdapter } from "../runtime/adapter";
+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;
+    cors?:
+      | boolean
+      | {
+          origin?: string | string[];
+          methods?: string[];
+          credentials?: boolean;
+        };
+    streaming?: boolean;
+    rateLimit?:
+      | boolean
+      | {
+          windowMs?: number;
+          max?: number;
+          message?: string;
+          statusCode?: number;
+          headers?: boolean;
+        };
+  };
+  guard?: {
+    preset?: "mandu" | "fsd" | "clean" | "hexagonal" | "atomic" | "cqrs";
+    srcDir?: string;
+    exclude?: string[];
+    realtime?: boolean;
+    rules?: Record<string, GuardRuleSeverity>;
+    contractRequired?: GuardRuleSeverity;
+  };
+  build?: {
+    outDir?: string;
+    minify?: boolean;
+    sourcemap?: boolean;
+    splitting?: boolean;
+  };
+  dev?: {
+    hmr?: boolean;
+    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;
+    extensions?: string[];
+    exclude?: string[];
+    islandSuffix?: string;
+  };
+  seo?: {
+    enabled?: boolean;
+    defaultTitle?: string;
+    titleTemplate?: string;
+  };
+  /** Phase 12.1 — `mandu test` configuration block. */
+  test?: TestConfig;
+  plugins?: ManduPlugin[];
+  hooks?: Partial<ManduHooks>;
+}
+
+export const CONFIG_FILES = [
+  "mandu.config.ts",
+  "mandu.config.js",
+  "mandu.config.json",
+  path.join(".mandu", "guard.json"),
+];
+
+export function coerceConfig(raw: unknown, source: string): ManduConfig {
+  if (!raw || typeof raw !== "object") return {};
+
+  // .mandu/guard.json can be guard-only
+  if (source.endsWith("guard.json") && !("guard" in (raw as Record<string, unknown>))) {
+    return { guard: raw as ManduConfig["guard"] };
+  }
+
+  return raw as ManduConfig;
+}
+
+export async function loadManduConfig(rootDir: string): Promise<ManduConfig> {
+  for (const fileName of CONFIG_FILES) {
+    const filePath = path.join(rootDir, fileName);
+    if (!(await Bun.file(filePath).exists())) {
+      continue;
+    }
+
+    if (fileName.endsWith(".json")) {
+      try {
+        const parsed = await readJsonFile(filePath);
+        return coerceConfig(parsed, fileName);
+      } catch {
+        return {};
+      }
+    }
+
+    try {
+      const module = await import(filePath);
+      const raw = module?.default ?? module;
+      return coerceConfig(raw, fileName);
+    } catch {
+      return {};
+    }
+  }
+
+  return {};
+}