@mandujs/core 0.54.30 → 0.54.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.54.30",
+  "version": "0.54.32",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/bundler/__tests__/jsx-runtime-shim.test.ts

@@ -18,6 +18,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import {
   _testOnly_generateJsxDevRuntimeShimSource,
   _testOnly_generateJsxRuntimeShimSource,
@@ -32,10 +33,9 @@ describe("JSX runtime shim sources (issues #322 / #323)", () => {
     // the import statement, not comment mentions of the path.)
     expect(source).not.toMatch(/from\s*['"]react\/jsx-dev-runtime['"]/);
 
-    // Correct: jsxDEV + Fragment come from bare 'react' (→ _react.js).
-    expect(source).toMatch(
-      /import\s*\{\s*jsxDEV\s*,\s*Fragment\s*\}\s*from\s*['"]react['"]/,
-    );
+    // Correct: jsxDEV (+ jsx/jsxs fallback inputs) come from bare 'react'
+    // (→ _react.js). Import includes jsxDEV and resolves from "react".
+    expect(source).toMatch(/import\s*\{[^}]*\bjsxDEV\b[^}]*\}\s*from\s*['"]react['"]/);
 
     // Shim still re-exports what the import map expects.
     expect(source).toContain("export { jsxDEV, Fragment }");
@@ -83,4 +83,58 @@ describe("JSX runtime shim sources (issues #322 / #323)", () => {
       await rm(dir, { recursive: true, force: true });
     }
   });
+
+  // #323 re-regression (0.54.30): a SOURCE/static check passed but at RUNTIME
+  // `_react.js`'s jsxDEV was `undefined` (jsxDEV is a React dev-only export;
+  // a production-built _react.js drops it while keeping jsx/jsxs). The shim
+  // re-exported that undefined → "jsxDEV is not a function". Guard the VALUE:
+  // build the dev shim against a `react` stub whose jsxDEV is undefined (the
+  // exact failing condition) and assert the shim still exposes a callable
+  // jsxDEV via its jsx/jsxs fallback.
+  test("dev shim exposes a callable jsxDEV even when react.jsxDEV is undefined (runtime value)", async () => {
+    const dir = await mkdtemp(path.join(tmpdir(), "mandu-jsx-shim-rt-"));
+    try {
+      // Stub for bare 'react' = a production-built _react.js: jsx/jsxs are real
+      // functions, jsxDEV is missing.
+      const reactStub = path.join(dir, "react-stub.js");
+      await writeFile(
+        reactStub,
+        [
+          "export const jsx = (type) => ({ type, runtime: 'jsx' });",
+          "export const jsxs = (type) => ({ type, runtime: 'jsxs' });",
+          "export const Fragment = Symbol.for('react.fragment');",
+          "export const jsxDEV = undefined;",
+        ].join("\n"),
+        "utf-8",
+      );
+
+      // Generate the real shim source, but resolve its bare `react` import to
+      // the stub so we can drive the undefined-jsxDEV condition.
+      const shimSource = _testOnly_generateJsxDevRuntimeShimSource().replace(
+        /from\s*['"]react['"]/g,
+        `from ${JSON.stringify(reactStub.replace(/\\/g, "/"))}`,
+      );
+      const shimSrc = path.join(dir, "_jsx-dev-runtime.src.js");
+      await writeFile(shimSrc, shimSource, "utf-8");
+
+      const result = await Bun.build({
+        entrypoints: [shimSrc],
+        target: "browser",
+        define: { "process.env.NODE_ENV": JSON.stringify("production") },
+      });
+      expect(result.success).toBe(true);
+
+      const outPath = path.join(dir, "_jsx-dev-runtime.built.js");
+      await writeFile(outPath, await result.outputs[0]!.text(), "utf-8");
+      const mod = await import(`${pathToFileURL(outPath).href}?t=${Date.now()}`);
+
+      // The whole point of #323's re-regression: jsxDEV must be CALLABLE.
+      expect(typeof mod.jsxDEV).toBe("function");
+      // Fallback routes static-children to jsxs, otherwise jsx.
+      expect(mod.jsxDEV("div", {}, undefined, false).runtime).toBe("jsx");
+      expect(mod.jsxDEV("div", {}, undefined, true).runtime).toBe("jsxs");
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
 });

package/src/bundler/build.ts

@@ -660,12 +660,24 @@ function generateJsxDevRuntimeShimSource(): string {
  * Development JSX 변환용
  *
  * #323: import map의 'react/jsx-dev-runtime'이 다시 이 셰임을 가리키므로
- * 'react/jsx-dev-runtime'에서 import하면 순환 self-import가 되어 jsxDEV가
- * undefined가 된다. 대신 'react'(→ _react.js, external 없이 react 전체를
- * 인라인하며 jsxDEV/Fragment를 re-export하는 vendor 번들)에서 가져와
- * 순환을 끊는다.
+ * 'react/jsx-dev-runtime'에서 import하면 순환 self-import가 된다. 대신
+ * 'react'(→ _react.js, react 전체를 인라인하는 vendor 번들)에서 가져온다.
+ *
+ * #323 재발(0.54.30): jsxDEV는 React의 **dev 전용** export다. _react.js가
+ * production NODE_ENV로 번들되면 'react/jsx-dev-runtime'이 production 변형으로
+ * 해소되어 jsxDEV 값이 undefined가 된다(jsx/jsxs는 둘 다 존재). 그 결과 dev
+ * island가 'jsxDEV is not a function'으로 전멸했다. _react.js가 어떤 NODE_ENV로
+ * 빌드되든 안전하도록, jsxDEV가 함수가 아니면 jsx/jsxs로 폴백한다(dev 경고만
+ * 잃고 렌더는 정상). isStaticChildren일 때는 jsxs로 라우팅한다.
  */
-import { jsxDEV, Fragment } from 'react';
+import { jsx, jsxs, jsxDEV as __manduReactJsxDEV, Fragment } from 'react';
+
+const jsxDEV =
+  typeof __manduReactJsxDEV === 'function'
+    ? __manduReactJsxDEV
+    : function jsxDEV(type, config, key, isStaticChildren) {
+        return (isStaticChildren ? jsxs : jsx)(type, config, key);
+      };
 
 // Named exports
 export { jsxDEV, Fragment };

package/src/runtime/server.ts

@@ -117,11 +117,12 @@ import {
   resolvePrerenderedFile,
   type PrerenderIndex,
 } from "../bundler/prerender";
-import {
-  buildOverlayErrorHtml,
-  buildPayloadFromError,
-  shouldInjectOverlay,
-} from "../dev-error-overlay";
+import {
+  buildOverlayErrorHtml,
+  buildPayloadFromError,
+  OVERLAY_CUSTOM_EVENT,
+  shouldInjectOverlay,
+} from "../dev-error-overlay";
 // Phase 18.μ — i18n dispatch. `resolveLocale()` is pure (no side effects),
 // `createTranslator()` binds a per-request `t()` to the registry.
 import {
@@ -209,15 +210,24 @@ export interface ServerOptions {
    *                    자동으로 캐싱됨 (Next.js `export const revalidate` 등가).
    * - `false`/undefined : 캐시 비활성화
    */
-  cache?: boolean | CacheStore | CacheConfig;
-  /**
-   * Internal management token for local CLI/runtime control endpoints.
-   * When set, token-protected endpoints such as `/_mandu/cache` become available.
-   */
-  managementToken?: string;
-  /**
-   * Issue #192 — enable CSS View Transitions auto-inject (default `true`).
-   * When `true`, every SSR response gets
+  cache?: boolean | CacheStore | CacheConfig;
+  /**
+   * Internal management token for local CLI/runtime control endpoints.
+   * When set, token-protected endpoints such as `/_mandu/cache` become available.
+   */
+  managementToken?: string;
+  /**
+   * Phase 18.κ — override initial `.mandu/client/*` health state when
+   * starting a dev server.
+   */
+  clientBundleHealthy?: boolean;
+  /** Optional failure reason surfaced by dev overlay when unhealthy. */
+  clientBundleFailureReason?: string;
+  /** Optional route ID associated with the latest client-bundle failure. */
+  clientBundleFailureRouteId?: string;
+  /**
+   * Issue #192 — enable CSS View Transitions auto-inject (default `true`).
+   * When `true`, every SSR response gets
    * `<style>@view-transition{navigation:auto}</style>` in its `<head>`,
    * giving supported browsers a default crossfade on cross-document
    * navigation. Pass `false` to suppress (typically wired from
@@ -533,19 +543,29 @@ type CreateAppFn = (context: AppContext) => React.ReactElement;
  * 같은 프로세스에서 여러 서버를 띄울 때 핸들러가 섞이는 문제 방지
  */
 export interface ServerRegistrySettings {
-  isDev: boolean;
-  hmrPort?: number;
-  bundleManifest?: BundleManifest;
-  rootDir: string;
-  publicDir: string;
-  cors?: CorsOptions | false;
-  streaming: boolean;
-  rateLimit?: NormalizedRateLimitOptions | false;
-  /**
-   * CSS 파일 경로 (SSR 링크 주입용)
-   * - string: 해당 경로로 <link> 주입
-   * - false: CSS 링크 주입 비활성화
-   * - undefined: false로 처리 (404 방지)
+  isDev: boolean;
+  hmrPort?: number;
+  bundleManifest?: BundleManifest;
+  rootDir: string;
+  publicDir: string;
+  cors?: CorsOptions | false;
+  streaming: boolean;
+  rateLimit?: NormalizedRateLimitOptions | false;
+  /**
+   * Internal flag controlled by the CLI dev bundler lifecycle.
+   * `false` disables serving `.mandu/client/*` while the latest
+   * client bundle build is unhealthy.
+   */
+  clientBundleHealthy?: boolean;
+  /** Last client bundle failure message emitted by the dev bundler. */
+  clientBundleFailureReason?: string;
+  /** Route ID associated with the last client bundle failure. */
+  clientBundleFailureRouteId?: string;
+  /**
+   * CSS 파일 경로 (SSR 링크 주입용)
+   * - string: 해당 경로로 <link> 주입
+   * - false: CSS 링크 주입 비활성화
+   * - undefined: false로 처리 (404 방지)
    */
   cssPath?: string | false;
   /** ISR/SWR 캐시 스토어 */
@@ -700,14 +720,17 @@ export class ServerRegistry {
   readonly pageGenerateMetadata: Map<string, GenerateMetadata> = new Map();
   readonly layoutMetadata: Map<string, Metadata | null> = new Map();
   readonly layoutGenerateMetadata: Map<string, GenerateMetadata> = new Map();
-  settings: ServerRegistrySettings = {
-    isDev: false,
-    rootDir: process.cwd(),
-    publicDir: "public",
-    cors: false,
-    streaming: false,
-    rateLimit: false,
-  };
+  settings: ServerRegistrySettings = {
+    isDev: false,
+    rootDir: process.cwd(),
+    clientBundleHealthy: true,
+    clientBundleFailureReason: undefined,
+    clientBundleFailureRouteId: undefined,
+    publicDir: "public",
+    cors: false,
+    streaming: false,
+    rateLimit: false,
+  };
 
   registerApiHandler(routeId: string, handler: ApiHandler): void {
     this.apiHandlers.set(routeId, handler);
@@ -3187,15 +3210,70 @@ function paramsInStaticSet(
     if (allMatch) return true;
   }
   return false;
-}
-// ─── End Issue #214 ─────────────────────────────────────────────────────────
-
-async function handleRequestInternal(
-  req: Request,
-  router: Router,
-  registry: ServerRegistry,
-  skipMiddleware: boolean = false
-): Promise<Result<Response>> {
+}
+// ─── End Issue #214 ─────────────────────────────────────────────────────────
+
+function buildClientBundleFailureResponse(pathname: string, settings: ServerRegistrySettings): Response {
+  const reason = settings.clientBundleFailureReason ?? "Client bundle build failed.";
+  const routeId = settings.clientBundleFailureRouteId;
+  const failureDetails = routeId ? ` Route: ${routeId}.` : "";
+  const extension = path.extname(pathname).toLowerCase();
+  const isCss = extension === ".css";
+  const payload = buildPayloadFromError(
+    new Error(`${reason}${failureDetails}`),
+    {
+      kind: "manual",
+      routeId,
+      url: pathname,
+    },
+  );
+  const payloadJson = JSON.stringify(payload).replace(/</g, "\\u003c");
+  const reasonPayload = JSON.stringify({
+    message: reason,
+    routeId,
+    pathname,
+  }).replace(/</g, "\\u003c");
+
+  if (isCss) {
+    const cssBody = `/* Mandu: client bundle unavailable in dev. ${reason}${failureDetails} */`;
+    return new Response(cssBody, {
+      status: 503,
+      headers: {
+        "Content-Type": "text/css; charset=utf-8",
+        "Cache-Control": "no-cache, no-store, must-revalidate",
+      },
+    });
+  }
+
+  const jsBody = [
+    "(function(){",
+    `var payload = ${payloadJson};`,
+    "if (typeof console !== \"undefined\" && console && console.warn) {",
+    `console.warn("Mandu: client bundle is unavailable in dev mode.", ${reasonPayload});`,
+    "}",
+    "if (typeof window !== \"undefined\") {",
+    "try {",
+    `window.dispatchEvent(new CustomEvent(${JSON.stringify(OVERLAY_CUSTOM_EVENT)}, { detail: payload }));`,
+    "} catch (_) {}",
+    "}",
+    "})();",
+  ].join("");
+
+  return new Response(jsBody, {
+    status: 503,
+    headers: {
+      "Content-Type": "application/javascript; charset=utf-8",
+      "Cache-Control": "no-cache, no-store, must-revalidate",
+    },
+  });
+}
+
+async function handleRequestInternal(
+  req: Request,
+  router: Router,
+  registry: ServerRegistry,
+  skipMiddleware: boolean = false
+): Promise<Result<Response>> {
   const url = new URL(req.url);
   const pathname = url.pathname;
   const settings = registry.settings;
@@ -3217,16 +3295,20 @@ async function handleRequestInternal(
   // HMR signals "full reload" — user saves a file, reloads, and the old
   // prerendered output wins. Production `mandu start` always runs with
   // `isDev: false`, so prod behavior is unchanged.
-  if (!settings.isDev) {
-    const prerendered = await tryServePrerendered(pathname, settings, req.method, req);
-    if (prerendered) {
-      if (settings.cors && isCorsRequest(req)) {
-        const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
-        return ok(applyCorsToResponse(prerendered, req, corsOptions));
-      }
-      return ok(prerendered);
-    }
-  }
+  if (!settings.isDev) {
+    const prerendered = await tryServePrerendered(pathname, settings, req.method, req);
+    if (prerendered) {
+      if (settings.cors && isCorsRequest(req)) {
+        const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
+        return ok(applyCorsToResponse(prerendered, req, corsOptions));
+      }
+      return ok(prerendered);
+    }
+  }
+
+  if (settings.isDev && settings.clientBundleHealthy === false && pathname.startsWith("/.mandu/client/")) {
+    return ok(buildClientBundleFailureResponse(pathname, settings));
+  }
 
   // ─── Phase 18.μ — i18n dispatch ─────────────────────────────────────────
   // Runs AFTER γ's prerendered check (static HTML per-locale is already
@@ -3750,12 +3832,15 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     cors = false,
     streaming = false,
     rateLimit = false,
-    cssPath: cssPathOption,
-    registry = defaultRegistry,
-    guardConfig = null,
-    cache: cacheOption,
-    managementToken,
-    transitions,
+    cssPath: cssPathOption,
+    registry = defaultRegistry,
+    guardConfig = null,
+    cache: cacheOption,
+    managementToken,
+    clientBundleHealthy = true,
+    clientBundleFailureReason,
+    clientBundleFailureRouteId,
+    transitions,
     prefetch,
     spa,
     devtools,
@@ -3857,16 +3942,19 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
   });
 
   // Registry settings 저장 (초기값)
-  registry.settings = {
-    isDev,
-    hmrPort,
-    bundleManifest,
-    rootDir,
-    publicDir,
-    cors: corsOptions,
-    streaming,
-    rateLimit: rateLimitOptions,
-    cssPath,
+  registry.settings = {
+    isDev,
+    hmrPort,
+    bundleManifest,
+    rootDir,
+    publicDir,
+    clientBundleHealthy,
+    clientBundleFailureReason,
+    clientBundleFailureRouteId,
+    cors: corsOptions,
+    streaming,
+    rateLimit: rateLimitOptions,
+    cssPath,
     managementToken,
     transitions,
     prefetch,
@@ -4158,10 +4246,19 @@ export const routeComponents = defaultRegistry.routeComponents;
 export interface AppFetchHandlerOptions {
   /** Project root (used for module path validation). Required. */
   rootDir: string;
-  /** Bundle manifest (Island hydration). Optional in pure-SSR apps. */
-  bundleManifest?: BundleManifest;
-  /** CORS config — `true` allows all origins, object for fine-grained rules. */
-  cors?: boolean | CorsOptions;
+  /** Bundle manifest (Island hydration). Optional in pure-SSR apps. */
+  bundleManifest?: BundleManifest;
+  /**
+   * Phase 18.κ — override initial `.mandu/client/*` health state when using
+   * a runtime-neutral fetch handler.
+   */
+  clientBundleHealthy?: boolean;
+  /** Optional failure reason surfaced by dev overlay when unhealthy. */
+  clientBundleFailureReason?: string;
+  /** Optional route ID associated with the latest client-bundle failure. */
+  clientBundleFailureRouteId?: string;
+  /** CORS config — `true` allows all origins, object for fine-grained rules. */
+  cors?: boolean | CorsOptions;
   /** Streaming SSR toggle. Default: `false`. */
   streaming?: boolean;
   /** Rate limit policy. Memory-backed; edge runtimes should prefer durable stores. */
@@ -4221,11 +4318,14 @@ export function createAppFetchHandler(
   manifest: RoutesManifest,
   options: AppFetchHandlerOptions
 ): (req: Request) => Promise<Response> {
-  const {
-    rootDir,
-    bundleManifest,
-    cors = false,
-    streaming = false,
+  const {
+    rootDir,
+    bundleManifest,
+    clientBundleHealthy = true,
+    clientBundleFailureReason,
+    clientBundleFailureRouteId,
+    cors = false,
+    streaming = false,
     rateLimit = false,
     cssPath = false,
     registry = defaultRegistry,
@@ -4236,15 +4336,18 @@ export function createAppFetchHandler(
   const corsOptions: CorsOptions | false = cors === true ? {} : cors;
   const rateLimitOptions = normalizeRateLimitOptions(rateLimit);
 
-  registry.settings = {
-    isDev: false,
-    bundleManifest,
-    rootDir,
-    publicDir: "public",
-    cors: corsOptions,
-    streaming,
-    rateLimit: rateLimitOptions,
-    cssPath,
+  registry.settings = {
+    isDev: false,
+    bundleManifest,
+    rootDir,
+    publicDir: "public",
+    clientBundleHealthy,
+    clientBundleFailureReason,
+    clientBundleFailureRouteId,
+    cors: corsOptions,
+    streaming,
+    rateLimit: rateLimitOptions,
+    cssPath,
     edge,
   };