@mandujs/core 0.24.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",
@@ -13,11 +13,13 @@
     "./auth/reset": "./src/auth/reset.ts",
     "./auth/verification": "./src/auth/verification.ts",
     "./client": "./src/client/index.ts",
+    "./content": "./src/content/index.ts",
     "./db": "./src/db/index.ts",
     "./desktop": "./src/desktop/index.ts",
     "./desktop/worker": "./src/desktop/worker.ts",
     "./email": "./src/email/index.ts",
     "./filling/session-sqlite": "./src/filling/session-sqlite.ts",
+    "./kitchen": "./src/kitchen/index.ts",
     "./middleware": "./src/middleware/index.ts",
     "./middleware/oauth": "./src/middleware/oauth/index.ts",
     "./middleware/secure": "./src/middleware/secure/index.ts",

package/src/bundler/build.test.ts

@@ -62,14 +62,24 @@ afterAll(async () => {
   }
 });
 
-// Bun.build has observed cross-worker races under bun:test's parallel file
-// execution — when tests shuffle under --randomize, this file sometimes
-// collides with another bundler test in a sibling worker and fails with
-// "AggregateError: Bundle failed" + missing shim outputs. Gate on an env
-// var so CI can run randomize-mode across everything else, then run this
-// suite in a dedicated serial pass. Local `bun run test:core` (no env set)
-// still runs these tests fully. Tracked as Phase 0.6.
-describe.skipIf(process.env.MANDU_SKIP_BUNDLER_TESTS === "1")("buildClientBundles vendor shims", () => {
+// Historical note — `MANDU_SKIP_BUNDLER_TESTS` gate REMOVED.
+//
+// A previous revision gated this describe block behind
+// `describe.skipIf(MANDU_SKIP_BUNDLER_TESTS === "1")` because running
+// `bun test src/bundler/` without the gate hung indefinitely on Windows
+// (see Phase 0.6 and `docs/qa/wave-R2-integration-report.md`). Root cause
+// was NOT actually in THIS file — it was a deadlock in `safe-build.test.ts`'s
+// "slot handoff" regression test, which drove Bun's microtask queue with a
+// `while (!stop) { await Promise.resolve() }` sampler. That starved libuv
+// I/O callbacks, so the 7 parallel `safeBuild()` calls never completed, the
+// whole test process hung, and downstream test files (including this one
+// when run in the same invocation) looked flaky when they were simply
+// never reached. The handoff sampler now yields via `setImmediate`, which
+// unblocks Bun.build completion and makes `bun test src/bundler/` finish
+// deterministically in ~35s on Windows. Confirmed green 3/3 runs without
+// the gate on 2026-04-20. If you are tempted to re-introduce the skip here,
+// first check whether a sibling test is starving the event loop.
+describe("buildClientBundles vendor shims", () => {
   test("build succeeds", () => {
     if (!result.success) {
       console.error("[build.test] errors:", result.errors);

package/src/bundler/build.ts

@@ -859,11 +859,34 @@ function getListeners() {
   return window.__MANDU_ROUTER_LISTENERS__;
 }
 
-// 패턴 매칭 캐시
+// 패턴 매칭 캐시 (Phase 17 — bounded LRU, inlined to keep the runtime
+// bundle self-contained. Same semantics as packages/core/src/utils/lru-cache.ts
+// but hand-written here so the client-side shim has no server imports.)
+var PATTERN_CACHE_MAX = 200;
 var patternCache = new Map();
 
+function patternCacheGet(key) {
+  if (!patternCache.has(key)) return undefined;
+  var value = patternCache.get(key);
+  // Promote to MRU.
+  patternCache.delete(key);
+  patternCache.set(key, value);
+  return value;
+}
+
+function patternCacheSet(key, value) {
+  if (patternCache.has(key)) {
+    patternCache.delete(key);
+  } else if (patternCache.size >= PATTERN_CACHE_MAX) {
+    var oldest = patternCache.keys().next().value;
+    if (oldest !== undefined) patternCache.delete(oldest);
+  }
+  patternCache.set(key, value);
+}
+
 function compilePattern(pattern) {
-  if (patternCache.has(pattern)) return patternCache.get(pattern);
+  var cached = patternCacheGet(pattern);
+  if (cached) return cached;
 
   const paramNames = [];
   let paramIndex = 0;
@@ -881,7 +904,7 @@ function compilePattern(pattern) {
   });
 
   const compiled = { regex: new RegExp('^' + regexStr + '$'), paramNames };
-  patternCache.set(pattern, compiled);
+  patternCacheSet(pattern, compiled);
   return compiled;
 }
 

package/src/bundler/dev.ts

@@ -22,6 +22,8 @@ import {
 } from "./reverse-import-graph";
 import path from "path";
 import fs from "fs";
+import { LRUCache } from "../utils/lru-cache";
+import { registerCacheSize, unregisterCacheSize } from "../observability/metrics";
 
 /**
  * #184: 공통 디렉토리 변경 시 사용하는 sentinel.
@@ -685,8 +687,19 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
    * Lifecycle: timers are created by `scheduleFileChange`, cleared on flush or
    * on `close()`. We call `.delete(key)` on flush to keep the Map bounded —
    * no leak from editing a single file repeatedly.
+   *
+   * Phase 17 — upgraded to `LRUCache` with an `onEvict` hook so
+   *   (a) a pathological watcher (millions of distinct files) cannot leak
+   *   (b) evicted entries still get `clearTimeout` called (no dangling refs)
+   *   (c) the size is registered with `/_mandu/metrics`
+   * Max 2000 entries is generous for even large monorepos (each entry is a
+   * single in-flight debounce token; flush cycle is 100 ms).
    */
-  const perFileTimers = new Map<string, ReturnType<typeof setTimeout>>();
+  const perFileTimers = new LRUCache<string, ReturnType<typeof setTimeout>>({
+    maxSize: 2000,
+    onEvict: (_key, timer) => clearTimeout(timer),
+  });
+  registerCacheSize("perFileTimers", () => perFileTimers.size);
 
   /**
    * B2 fix — multi-file pending build queue (Phase 7.0 R1 Agent A).
@@ -1515,10 +1528,11 @@ export async function startDevBundler(options: DevBundlerOptions): Promise<DevBu
     initialBuild,
     close: () => {
       // B6: clear all per-file timers to release event-loop refs.
-      for (const timer of perFileTimers.values()) {
-        clearTimeout(timer);
-      }
+      // Phase 17 — `LRUCache.clear()` fires the registered `onEvict`
+      // (`clearTimeout(timer)`) for every entry before dropping them,
+      // so we no longer need an explicit loop.
       perFileTimers.clear();
+      unregisterCacheSize("perFileTimers");
       for (const watcher of watchers) {
         watcher.close();
       }

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

@@ -141,16 +141,34 @@ describe("safeBuild", () => {
 
     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.
+    // Sample active-slot count while the build burst is in flight. An earlier
+    // revision of this test used a `while (!stop) { await Promise.resolve() }`
+    // microtask busy-loop to push sampling granularity below setInterval's
+    // Windows 4ms-ish clamp. That deadlocks under Bun 1.3.x on Windows:
+    // `await Promise.resolve()` stays on the microtask queue, which runs
+    // to exhaustion before Bun's libuv I/O phase — so Bun.build completion
+    // callbacks never fire, `releaseSlot()` never runs, and the promises
+    // returned by the 7 parallel `safeBuild()` calls hang indefinitely.
+    // Reproduction: `bun test src/bundler/safe-build.test.ts` times out with
+    // only the banner printed (confirmed with a standalone repro of the
+    // sampler + 7 safeBuild calls — hung at "start" past 60s).
+    //
+    // Fix: yield to the macrotask queue via `setImmediate`. This lets
+    // libuv I/O callbacks run between samples, so Bun.build completes and
+    // `releaseSlot()` advances the queue. Per-tick granularity on Node/Bun
+    // is still sub-millisecond and fires ~hundreds of times during a 7-
+    // build burst — more than enough to statistically catch the cap+1
+    // regression window if it ever returned (the window is microtask-sized,
+    // but any cross-tick sampling with high fan-out has a realistic chance
+    // of landing inside it). The strict assertion is still `peak <= max`.
     let stop = false;
     const sample = async () => {
       while (!stop) {
         const { active } = _getConcurrencyState();
         if (active > peak) peak = active;
         samples++;
-        await Promise.resolve(); // yield to microtask queue
+        // Yield to libuv I/O phase so Bun.build callbacks can fire.
+        await new Promise<void>((resolve) => setImmediate(resolve));
       }
     };
     const sampler = sample();

package/src/client/globals.ts

@@ -1,44 +1,61 @@
-/**
- * Mandu 전역 타입 선언
- * 클라이언트 측 전역 상태의 타입 정의
- */
-import type { Root } from "react-dom/client";
-import type { RouterState } from "./router";
-
-interface ManduRouteInfo {
-  id: string;
-  pattern: string;
-  params: Record<string, string>;
-}
-
-interface ManduDataEntry {
-  serverData: unknown;
-  timestamp?: number;
-}
-
-declare global {
-  interface Window {
-    /** 서버에서 전달된 데이터 (routeId → data) */
-    __MANDU_DATA__?: Record<string, ManduDataEntry>;
-
-    /** 직렬화된 서버 데이터 (raw JSON) */
-    __MANDU_DATA_RAW__?: string;
-
-    /** 현재 라우트 정보 */
-    __MANDU_ROUTE__?: ManduRouteInfo;
-
-    /** 클라이언트 라우터 상태 */
-    __MANDU_ROUTER_STATE__?: RouterState;
-
-    /** 라우터 상태 변경 리스너 */
-    __MANDU_ROUTER_LISTENERS__?: Set<(state: RouterState) => void>;
-
-    /** Hydrated roots 추적 (unmount용) */
-    __MANDU_ROOTS__?: Map<string, Root>;
-
-    /** React 인스턴스 공유 */
-    __MANDU_REACT__?: typeof import("react");
-  }
-}
-
-export {};
+/**
+ * Mandu 전역 타입 선언
+ * 클라이언트 측 전역 상태의 타입 정의
+ */
+import type { Root } from "react-dom/client";
+import type { RouterState } from "./router";
+
+interface ManduRouteInfo {
+  id: string;
+  pattern: string;
+  params: Record<string, string>;
+}
+
+interface ManduDataEntry {
+  serverData: unknown;
+  timestamp?: number;
+}
+
+declare global {
+  interface Window {
+    /** 서버에서 전달된 데이터 (routeId → data) */
+    __MANDU_DATA__?: Record<string, ManduDataEntry>;
+
+    /** 직렬화된 서버 데이터 (raw JSON) */
+    __MANDU_DATA_RAW__?: string;
+
+    /** 현재 라우트 정보 */
+    __MANDU_ROUTE__?: ManduRouteInfo;
+
+    /** 클라이언트 라우터 상태 */
+    __MANDU_ROUTER_STATE__?: RouterState;
+
+    /** 라우터 상태 변경 리스너 */
+    __MANDU_ROUTER_LISTENERS__?: Set<(state: RouterState) => void>;
+
+    /** Hydrated roots 추적 (unmount용) */
+    __MANDU_ROOTS__?: Map<string, Root>;
+
+    /** React 인스턴스 공유 */
+    __MANDU_REACT__?: typeof import("react");
+
+    /**
+     * Issue #193 — global SPA navigation toggle.
+     *
+     *   - `undefined` (not set) → default. Plain `<a href="/about">`
+     *     is intercepted and routed through the client-side router.
+     *   - `false`               → legacy opt-in behavior. Only `<a>`
+     *     tags with `data-mandu-link` are intercepted; all other
+     *     internal links perform a full browser navigation.
+     *   - `true`                → same as undefined; present only for
+     *     symmetry and forward compat.
+     *
+     * SSR injects this global only when `mandu.config.ts` sets
+     * `spa: false` — the default case emits nothing to keep the
+     * typical response payload unchanged.
+     */
+    __MANDU_SPA__?: boolean;
+  }
+}
+
+export {};

package/src/client/router.ts

@@ -15,6 +15,7 @@ import {
 } from "./window-state";
 import { LRUCache } from "../utils/lru-cache";
 import { LIMITS } from "../constants";
+import { registerCacheSize } from "../observability/metrics";
 
 // ========== Types ==========
 
@@ -158,6 +159,12 @@ interface CompiledPattern {
 
 const patternCache = new LRUCache<string, CompiledPattern>(LIMITS.ROUTER_PATTERN_CACHE);
 
+// Phase 17 — expose the cache size to the /_mandu/heap + /_mandu/metrics
+// endpoints so long-running processes can detect runaway growth.
+// The registration happens at module init — safe to call once per process
+// because `registerCacheSize` replaces any prior reporter under the same key.
+registerCacheSize("patternCache", () => patternCache.size);
+
 /**
  * 패턴을 정규식으로 컴파일
  */
@@ -435,40 +442,105 @@ export function getNavigationState(): NavigationState {
 // ========== Link Click Handler ==========
 
 /**
- * 링크 클릭 이벤트 핸들러 (이벤트 위임용)
+ * Issue #193 — Link click handler (event delegation).
+ *
+ * Mandu v0.22+ reversed the default from opt-in to opt-out SPA navigation.
+ * Every internal same-origin `<a href="/...">` click is intercepted and
+ * routed through the client-side router unless one of the explicit escape
+ * hatches fires:
+ *
+ *   - `data-no-spa`                 → per-link opt-out (always skip).
+ *   - `<a>` without `href`          → degenerate anchor, let the browser decide.
+ *   - `href="#fragment"`            → same-page anchor, browser handles scroll.
+ *   - `href="mailto:"` / `tel:` /   → non-http schemes the browser owns.
+ *     `javascript:` / `data:` / …
+ *   - `target="_blank" / "_top" /   → any target other than `_self` means the
+ *     "_parent" / "framename"         user wants a new browsing context.
+ *   - `download` attribute present  → file download, never a navigation.
+ *   - Modifier keys (Ctrl / Cmd /   → browser shortcut for new tab, bookmark,
+ *     Shift / Alt)                    save, or save-as.
+ *   - Non-left click                → middle-click opens a new tab, right-click
+ *                                     opens context menu.
+ *   - `event.defaultPrevented`      → another listener already handled it.
+ *   - Cross-origin href             → full document navigation required.
+ *
+ * The legacy opt-in attribute `data-mandu-link` still works for
+ * backward compatibility — it is simply a no-op under the new default
+ * because we already intercept by default. Teams that want the old
+ * opt-in behavior back can set `spa: false` in `mandu.config.ts`, which
+ * surfaces as `window.__MANDU_SPA__ === false` and re-introduces the
+ * requirement that `<a>` tags carry `data-mandu-link`.
  */
 function handleLinkClick(event: MouseEvent): void {
-  // 기본 동작 조건 체크
+  // Pre-filter: obvious browser-owned events.
   if (
     event.defaultPrevented ||
-    event.button !== 0 ||
-    event.metaKey ||
-    event.altKey ||
-    event.ctrlKey ||
-    event.shiftKey
+    event.button !== 0 ||  // middle-click / right-click — browser decides.
+    event.metaKey ||       // Cmd (macOS) — new tab.
+    event.altKey ||        // Alt — "save-as" in most browsers.
+    event.ctrlKey ||       // Ctrl (Windows/Linux) — new tab.
+    event.shiftKey         // Shift — new window / bookmark.
   ) {
     return;
   }
 
-  // 가장 가까운 앵커 태그 찾기
-  const anchor = (event.target as HTMLElement).closest("a");
+  // Find the closest anchor ancestor — users commonly nest `<span>` /
+  // `<img>` inside `<a>` and the event target is the inner element.
+  const anchor = (event.target as HTMLElement | null)?.closest("a");
   if (!anchor) return;
 
-  // data-mandu-link 속성이 있는 링크만 처리
-  if (!anchor.hasAttribute("data-mandu-link")) return;
+  // Escape hatch 1: explicit per-link opt-out always wins.
+  if (anchor.hasAttribute("data-no-spa")) return;
+
+  // Escape hatch 2: global config `spa: false` — reverts to the legacy
+  // opt-in behavior (only `data-mandu-link` intercepts). SSR injects
+  // `window.__MANDU_SPA__ = false` when the user sets `spa: false`.
+  const spaGlobal = (globalThis as { window?: { __MANDU_SPA__?: boolean } }).window?.__MANDU_SPA__;
+  if (spaGlobal === false && !anchor.hasAttribute("data-mandu-link")) return;
 
+  // `<a>` without `href` is a degenerate anchor — the browser will not
+  // navigate, but a listener somewhere might. Don't intercept.
   const href = anchor.getAttribute("href");
   if (!href) return;
 
-  // 외부 링크 체크
+  // Same-page fragment link — let the browser handle scroll / focus.
+  if (href.startsWith("#")) return;
+
+  // `target` other than `_self` (or absent) signals the user wants a
+  // new browsing context. `target="_blank"` is the common case but we
+  // also pass through `_top`, `_parent`, and framed targets.
+  const target = anchor.getAttribute("target");
+  if (target && target !== "_self") return;
+
+  // `download` attribute means the user wants to save the resource,
+  // never navigate to it.
+  if (anchor.hasAttribute("download")) return;
+
+  // URL parsing — catches both cross-origin and non-http schemes.
+  let url: URL;
   try {
-    const url = new URL(href, window.location.origin);
-    if (url.origin !== window.location.origin) return;
+    url = new URL(href, window.location.origin);
   } catch {
+    // Malformed href — let the browser produce its own error.
     return;
   }
 
-  // 기본 동작 방지 및 Client-side 네비게이션
+  // Only same-origin http(s) navigations are eligible for SPA handling.
+  // `mailto:`, `tel:`, `javascript:`, `data:`, `blob:`, chrome-extension,
+  // etc. all fail this check because `new URL("mailto:foo@bar").origin`
+  // is the string `"null"` (spec-defined), never equal to
+  // `window.location.origin`.
+  if (url.origin !== window.location.origin) return;
+
+  // Only intercept http / https schemes. Defense-in-depth against any
+  // exotic same-origin scheme we haven't considered (e.g. a custom
+  // protocol handler installed by a browser extension).
+  if (url.protocol !== "http:" && url.protocol !== "https:") return;
+
+  // All clear — prevent the default full-page navigation and hand off
+  // to the client-side router. `href` preserves the user's original
+  // string (relative paths, fragments, query strings) so the router
+  // can normalize as needed.
   event.preventDefault();
   navigate(href);
 }
@@ -828,3 +900,9 @@ if (typeof window !== "undefined") {
 // can exercise the schema-check path directly without round-tripping
 // through `window.__MANDU_ROUTER_REVALIDATE__`.
 export { applyHDRUpdate as _testOnly_applyHDRUpdate };
+
+// Issue #193: export the link-click handler for unit tests so we can
+// drive every exclusion case without installing a real DOM click
+// listener. Keeping this under a `_testOnly_` prefix to signal it is
+// not part of the public API.
+export { handleLinkClick as _testOnly_handleLinkClick };