@mandujs/core 0.25.0 → 0.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/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/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/runtime/server.ts

@@ -1547,7 +1547,27 @@ async function loadPageData(
       const exportedObj = exported as Record<string, unknown> | null;
       const component = typeof exported === "function"
         ? (exported as RouteComponent)
-        : (exportedObj?.component ?? exported);
+        : (exportedObj?.component ?? undefined);
+      // DX-1: pageLoader 경로에서 malformed default export를 silent 404 로
+      //보내지 않고 명시적 에러로 즉시 실패시킨다. 이전에는
+      //   `export default "hello"` / `export default undefined` / named-only
+      // 같은 실수가 registerRouteComponent(undefined) → defaultCreateApp
+      // 에서 404로 렌더되어 사용자가 원인을 추적하기 어려웠음. 여기서 throw
+      // 하면 try/catch(아래) 의 createPageLoadErrorResponse 가 500 응답과
+      // 함께 route.id + pattern 을 출력해주므로 개발자가 바로 인지한다.
+      if (typeof component !== "function") {
+        const defaultSummary =
+          exported === undefined
+            ? "undefined (missing `export default`)"
+            : exported === null
+              ? "null"
+              : `type ${typeof exported}`;
+        throw new Error(
+          `[Mandu] Page module for '${route.id}' (pattern ${route.pattern}) has an invalid default export: ${defaultSummary}. ` +
+            "Expected `export default function Page() {…}` or `export default { component, filling }`. " +
+            "If the page file is empty or only has named exports, add a default-exported React component."
+        );
+      }
       registry.registerRouteComponent(route.id, component as RouteComponent);
 
       // #186: page 모듈에서 metadata / generateMetadata export 캐싱
@@ -2201,8 +2221,22 @@ async function handlePageRoute(
   const cache = settings.cacheStore;
   // Only call ensurePageRouteMetadata when a pageHandler exists;
   // routes registered via registerPageLoader are handled by loadPageData instead.
+  // DX-1: if the pageHandler returns a malformed registration (component is
+  // not a function), ensurePageRouteMetadata now throws with a descriptive
+  // message. Catch it here so the request becomes a loud 500 instead of
+  // bubbling up as an opaque "Internal Server Error".
   if (registry.pageHandlers.has(route.id)) {
-    await ensurePageRouteMetadata(route.id, registry);
+    try {
+      await ensurePageRouteMetadata(route.id, registry);
+    } catch (error) {
+      const pageError = createPageLoadErrorResponse(
+        route.id,
+        route.pattern,
+        error instanceof Error ? error : new Error(String(error))
+      );
+      console.error(`[Mandu] ${pageError.errorType}:`, pageError.message);
+      return err(pageError);
+    }
   }
   const renderMode = getRenderModeForRoute(route.id, registry);
 
@@ -2467,6 +2501,19 @@ async function ensurePageRouteMetadata(
   }
 
   const registration = await handler();
+  // DX-1: pageHandler가 malformed registration을 반환해도 silent 404 대신
+  // 명시적 에러로 실패. handlers.ts 의 auto-promote 블록이 function 기본값을
+  // { component } 로 감싸주지만, 직접 registerPageHandler 를 쓰는 경우나
+  // 사용자 코드가 이상한 값을 반환하는 경우를 방어한다.
+  if (typeof registration?.component !== "function") {
+    const t = registration === null || registration === undefined
+      ? String(registration)
+      : typeof registration.component;
+    throw new Error(
+      `[Mandu] Page handler for '${routeId}' returned an invalid registration: component is ${t}. ` +
+        "Expected `{ component: ReactComponent, filling? }` from the page module's default export."
+    );
+  }
   const component = registration.component as RouteComponent;
   registry.registerRouteComponent(routeId, component);