npm - @mandujs/core - Versions diffs - 0.54.31 → 0.54.32 - Mend

@mandujs/core 0.54.31 → 0.54.32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/package.json +1 -1
package/src/runtime/server.ts +191 -88

package/package.json CHANGED Viewed

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

package/src/runtime/server.ts CHANGED Viewed

@@ -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,
   };