@mandujs/core 0.22.1 → 0.24.0

package/src/perf/hmr-markers.ts

@@ -175,6 +175,18 @@ export const HMR_PERF = {
    *  prewarm before the user hits a file save. */
   JIT_PREWARM: "boot:jit-prewarm",
 
+  /** Phase 11 C — Deep-path JIT prewarm extension. Phase 7.3 A closed the
+   *  first-iter gap from 41 ms to 25 ms by prewarming the React hot set;
+   *  R0.3 diagnostics traced the remaining ~15 ms to the
+   *  `registerManifestHandlers` deep-path (cli `util/handlers` +
+   *  `util/bun` bundledImport + `@mandujs/core/bundler/safe-build`
+   *  internals) which only execute on the FIRST SSR reload. This marker
+   *  measures the settling time of the deep-import Promise — still
+   *  fire-and-forget, still NOT on the critical path, so values are
+   *  informational only. Target: first-iter ≤ 15 ms (hard) / ≤ 20 ms
+   *  (soft). See `packages/cli/src/util/jit-prewarm.ts`. */
+  JIT_PREWARM_DEEP: "boot:jit-prewarm-deep",
+
   /** API route handler reload (`handleAPIChange`) — `.route.ts` /
    *  `.route.tsx` change. Symmetric to `SSR_HANDLER_RELOAD` for page /
    *  layout reloads. Phase 7.2 §7.4 flagged that `handleAPIChange` was

package/src/runtime/adapter-bun.ts

@@ -1,62 +1,64 @@
-/**
- * Mandu Bun Adapter (기본 어댑터)
- * Bun.serve() 기반 서버 생성
- */
-
-import type { ManduAdapter, AdapterOptions, AdapterServer } from "./adapter";
-import { startServer, type ManduServer } from "./server";
-
-/**
- * Bun 어댑터 (기본)
- *
- * @example
- * ```typescript
- * // mandu.config.ts
- * import { adapterBun } from "@mandujs/core";
- *
- * export default {
- *   adapter: adapterBun(),
- * };
- * ```
- */
-export function adapterBun(): ManduAdapter {
-  return {
-    name: "adapter-bun",
-
-    createServer(options: AdapterOptions): AdapterServer {
-      let manduServer: ManduServer | null = null;
-
-      return {
-        async fetch(req: Request): Promise<Response> {
-          if (!manduServer) {
-            return new Response("Server not started", { status: 503 });
-          }
-          // 내부 서버로 프록시
-          const url = new URL(req.url);
-          const targetUrl = `http://localhost:${manduServer.server.port}${url.pathname}${url.search}`;
-          return globalThis.fetch(new Request(targetUrl, req));
-        },
-
-        async listen(port: number, hostname?: string) {
-          manduServer = startServer(options.manifest, {
-            ...options.serverOptions,
-            port,
-            hostname,
-            rootDir: options.rootDir,
-            bundleManifest: options.bundleManifest,
-          });
-
-          return {
-            port: manduServer.server.port ?? port,
-            hostname: hostname ?? "localhost",
-          };
-        },
-
-        async close() {
-          manduServer?.stop();
-          manduServer = null;
-        },
-      };
-    },
-  };
-}
+/**
+ * Mandu Bun Adapter (기본 어댑터)
+ * Bun.serve() 기반 서버 생성
+ */
+
+import type { ManduAdapter, AdapterOptions, AdapterServer } from "./adapter";
+import { startServer, type ManduServer } from "./server";
+
+/**
+ * Bun 어댑터 (기본)
+ *
+ * @example
+ * ```typescript
+ * // mandu.config.ts
+ * import { adapterBun } from "@mandujs/core";
+ *
+ * export default {
+ *   adapter: adapterBun(),
+ * };
+ * ```
+ */
+export function adapterBun(): ManduAdapter {
+  return {
+    name: "adapter-bun",
+
+    createServer(options: AdapterOptions): AdapterServer {
+      let manduServer: ManduServer | null = null;
+
+      return {
+        async fetch(req: Request): Promise<Response> {
+          if (!manduServer) {
+            return new Response("Server not started", { status: 503 });
+          }
+          // 내부 서버로 프록시
+          const url = new URL(req.url);
+          const targetUrl = `http://localhost:${manduServer.server.port}${url.pathname}${url.search}`;
+          return globalThis.fetch(new Request(targetUrl, req));
+        },
+
+        async listen(port: number, hostname?: string) {
+          manduServer = startServer(options.manifest, {
+            ...options.serverOptions,
+            port,
+            hostname,
+            rootDir: options.rootDir,
+            bundleManifest: options.bundleManifest,
+          });
+
+          return {
+            port: manduServer.server.port ?? port,
+            // Report the effective bind address. startServer() defaults to
+            // 0.0.0.0 when no hostname is supplied. See #190.
+            hostname: hostname ?? "0.0.0.0",
+          };
+        },
+
+        async close() {
+          manduServer?.stop();
+          manduServer = null;
+        },
+      };
+    },
+  };
+}

package/src/runtime/server.ts

@@ -350,6 +350,32 @@ export interface ServerOptions {
    * 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
+   * `<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
+   * `ManduConfig.transitions`).
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — enable the hover prefetch helper (default `true`).
+   * When `true`, every SSR response gets a ~500-byte inline script that
+   * prefetches same-origin links on hover. Pass `false` to suppress
+   * (typically wired from `ManduConfig.prefetch`). Individual links can
+   * also opt out via `data-no-prefetch`.
+   */
+  prefetch?: boolean;
+  /**
+   * Issue #191 — override dev-mode `_devtools.js` injection.
+   * Wired from `ManduConfig.dev.devtools`.
+   *   - `true`      → force inject on every page (SSR-only + Kitchen).
+   *   - `false`     → force skip on every page.
+   *   - `undefined` → default. Inject iff the page's route has at least
+   *                   one island. Pure-SSR pages download zero devtools.
+   */
+  devtools?: boolean;
 }
 
 export interface ManduServer {
@@ -449,6 +475,31 @@ export interface ServerRegistrySettings {
   cacheStore?: CacheStore;
   /** Internal management token for local runtime control */
   managementToken?: string;
+  /**
+   * Edge runtime flag — disables filesystem-dependent features (static file
+   * serving, Kitchen dashboard, image optimization, SSG fallback loaders).
+   * Set by `@mandujs/edge` adapters (Cloudflare Workers, Deno Deploy, Vercel Edge).
+   * Default: false (Bun/Node runtime with full FS access).
+   */
+  edge?: boolean;
+  /**
+   * Issue #192 — threaded from `ServerOptions.transitions`.
+   * `undefined` is treated as `true` at the SSR call-site (enabled by
+   * default); `false` suppresses the `<style>@view-transition>` injection.
+   */
+  transitions?: boolean;
+  /**
+   * Issue #192 — threaded from `ServerOptions.prefetch`.
+   * `undefined` is treated as `true` at the SSR call-site (enabled by
+   * default); `false` suppresses the hover prefetch `<script>` injection.
+   */
+  prefetch?: boolean;
+  /**
+   * Issue #191 — threaded from `ServerOptions.devtools`. `undefined`
+   * means "use default (islands → inject)"; `true` / `false` force the
+   * dev-mode `_devtools.js` `<script>` injection on / off. No-op in prod.
+   */
+  devtools?: boolean;
 }
 
 export class ServerRegistry {
@@ -1882,6 +1933,9 @@ async function renderPageSSR(
         criticalData: loaderData as Record<string, unknown> | undefined,
         enableClientRouter: true,
         cssPath: settings.cssPath,
+        transitions: settings.transitions,
+        prefetch: settings.prefetch,
+        devtools: settings.devtools,
         onShellReady: () => {
           if (settings.isDev) {
             console.log(`[Mandu Streaming] Shell ready: ${route.id}`);
@@ -1917,6 +1971,9 @@ async function renderPageSSR(
       routePattern: route.pattern,
       cssPath: settings.cssPath,
       islandPreWrapped: !!needsIslandWrap,
+      transitions: settings.transitions,
+      prefetch: settings.prefetch,
+      devtools: settings.devtools,
     });
     return ok(cookies ? cookies.applyToResponse(ssrResponse) : ssrResponse);
   } catch (error) {
@@ -1953,6 +2010,9 @@ async function renderPageSSR(
             title: "Mandu App — Error",
             isDev: settings.isDev,
             cssPath: settings.cssPath,
+            transitions: settings.transitions,
+            prefetch: settings.prefetch,
+            devtools: settings.devtools,
           });
           return ok(cookies ? cookies.applyToResponse(errorHtml) : errorHtml);
         }
@@ -2051,6 +2111,9 @@ async function renderNotFoundPage(
       title: "Not Found",
       isDev: settings.isDev,
       cssPath: settings.cssPath,
+      transitions: settings.transitions,
+      prefetch: settings.prefetch,
+      devtools: settings.devtools,
     });
 
     // renderSSR returns a 200; override to 404 without losing headers.
@@ -2408,18 +2471,23 @@ async function handleRequestInternal(
   }
 
   // 1. 정적 파일 서빙 시도 (최우선)
-  const staticFileResult = await serveStaticFile(pathname, settings, req);
-  if (staticFileResult.handled) {
-    const staticResponse = staticFileResult.response!;
-    if (settings.cors && isCorsRequest(req)) {
-      const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
-      return ok(applyCorsToResponse(staticResponse, req, corsOptions));
+  // Edge runtimes (Cloudflare Workers, etc.) have no filesystem — skip and
+  // let the platform's asset pipeline (Wrangler [assets], Vercel _static, …)
+  // handle static routing instead.
+  if (!settings.edge) {
+    const staticFileResult = await serveStaticFile(pathname, settings, req);
+    if (staticFileResult.handled) {
+      const staticResponse = staticFileResult.response!;
+      if (settings.cors && isCorsRequest(req)) {
+        const corsOptions: CorsOptions = typeof settings.cors === 'object' ? settings.cors : {};
+        return ok(applyCorsToResponse(staticResponse, req, corsOptions));
+      }
+      return ok(staticResponse);
     }
-    return ok(staticResponse);
   }
 
   // 1.5. Image optimization handler (/_mandu/image)
-  if (pathname === "/_mandu/image") {
+  if (!settings.edge && pathname === "/_mandu/image") {
     const imageResponse = await handleImageRequest(req, settings.rootDir, settings.publicDir);
     if (imageResponse) return ok(imageResponse);
   }
@@ -2473,6 +2541,9 @@ async function handleRequestInternal(
           title: "Not Found",
           isDev: settings.isDev,
           cssPath: settings.cssPath,
+          transitions: settings.transitions,
+          prefetch: settings.prefetch,
+          devtools: settings.devtools,
         });
         const headers = new Headers(html.headers);
         const body = await html.text();
@@ -2574,10 +2645,43 @@ function startBunServerWithFallback(options: {
 
 // ========== Server Startup ==========
 
+/**
+ * Format a base URL for startup logging based on the bound hostname.
+ *
+ * When binding to wildcard addresses (`0.0.0.0`, `::`, or empty string),
+ * the server listens on all interfaces — browsers must use `localhost`
+ * or a specific loopback address to connect. We surface both IPv4 and IPv6
+ * loopback URLs so the user can pick whichever their OS prefers.
+ *
+ * Returns `{ primary, additional }` where `primary` is the canonical URL
+ * for UX (open-in-browser, runtime control) and `additional` are supplementary
+ * URLs shown in the startup log.
+ */
+export function formatServerAddresses(
+  hostname: string | undefined,
+  port: number
+): { primary: string; additional: string[] } {
+  const isWildcardV4 = hostname === "0.0.0.0" || hostname === undefined || hostname === "";
+  const isWildcardV6 = hostname === "::" || hostname === "[::]";
+  if (isWildcardV4 || isWildcardV6) {
+    return {
+      primary: `http://localhost:${port}`,
+      additional: [`http://127.0.0.1:${port}`, `http://[::1]:${port}`],
+    };
+  }
+  // Bracket IPv6 literals for URL syntax.
+  const host = hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+  return { primary: `http://${host}:${port}`, additional: [] };
+}
+
 export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
   const {
     port = 3000,
-    hostname = "localhost",
+    // Default to 0.0.0.0 (dual-stack wildcard on IPv4) so `localhost` resolves
+    // to 127.0.0.1 via OS-level IPv4-preferred lookups (e.g., Windows). Users
+    // can still pin `hostname: "::1"` or `hostname: "127.0.0.1"` explicitly.
+    // See issue #190.
+    hostname = "0.0.0.0",
     rootDir = process.cwd(),
     isDev = false,
     hmrPort,
@@ -2591,6 +2695,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     guardConfig = null,
     cache: cacheOption,
     managementToken,
+    transitions,
+    prefetch,
+    devtools,
   } = options;
 
   // cssPath 처리:
@@ -2626,6 +2733,9 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     rateLimit: rateLimitOptions,
     cssPath,
     managementToken,
+    transitions,
+    prefetch,
+    devtools,
   };
 
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
@@ -2725,8 +2835,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     registry.settings = { ...registry.settings, hmrPort: actualPort };
   }
 
+  const addresses = formatServerAddresses(hostname, actualPort);
+
   if (isDev) {
-    console.log(`🥟 Mandu Dev Server running at http://${hostname}:${actualPort}`);
+    console.log(`🥟 Mandu Dev Server listening at ${addresses.primary}`);
+    if (addresses.additional.length > 0) {
+      console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
+    }
     if (registry.settings.hmrPort) {
       console.log(`🔥 HMR enabled on port ${registry.settings.hmrPort + PORTS.HMR_OFFSET}`);
     }
@@ -2738,10 +2853,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
       console.log(`🌊 Streaming SSR enabled`);
     }
     if (registry.kitchen) {
-      console.log(`🍳 Kitchen dashboard at http://${hostname}:${actualPort}/__kitchen`);
+      console.log(`🍳 Kitchen dashboard at ${addresses.primary}/__kitchen`);
     }
   } else {
-    console.log(`🥟 Mandu server running at http://${hostname}:${actualPort}`);
+    console.log(`🥟 Mandu server listening at ${addresses.primary}`);
+    if (addresses.additional.length > 0) {
+      console.log(`   (also reachable at ${addresses.additional.join(", ")})`);
+    }
     if (streaming) {
       console.log(`🌊 Streaming SSR enabled`);
     }
@@ -2769,6 +2887,119 @@ export const pageLoaders = defaultRegistry.pageLoaders;
 export const pageHandlers = defaultRegistry.pageHandlers;
 export const routeComponents = defaultRegistry.routeComponents;
 
+// ========== Runtime-Neutral Fetch Handler Factory ==========
+
+/**
+ * Options for {@link createAppFetchHandler}. Subset of {@link ServerOptions}
+ * that makes sense in edge/serverless runtimes — no listen/port/hmr fields.
+ */
+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;
+  /** Streaming SSR toggle. Default: `false`. */
+  streaming?: boolean;
+  /** Rate limit policy. Memory-backed; edge runtimes should prefer durable stores. */
+  rateLimit?: boolean | RateLimitOptions;
+  /**
+   * CSS link injection target for SSR. Typically `"/.mandu/client/globals.css"`
+   * when Tailwind is in use. `false` disables injection.
+   */
+  cssPath?: string | false;
+  /** Custom registry override (defaults to the global registry). */
+  registry?: ServerRegistry;
+  /**
+   * Mark this handler as edge-hosted. Skips filesystem-dependent features
+   * (static file serving, Kitchen dashboard, image optimization). Set to
+   * `true` by `@mandujs/edge` adapters.
+   */
+  edge?: boolean;
+  /**
+   * Optional global middleware function. When omitted, the handler does not
+   * attempt to auto-load `middleware.ts` from disk (important for edge
+   * bundles where FS is unavailable). Adapters should pass pre-compiled
+   * middleware at build time.
+   */
+  middleware?: {
+    fn: MiddlewareFn;
+    config?: MiddlewareConfig | null;
+  };
+}
+
+/**
+ * Build a runtime-neutral `fetch(req) → Promise<Response>` handler from a
+ * routes manifest. Reuses the same request pipeline as `startServer()`
+ * (CORS, middleware, router, SSR, API handlers) but without binding to
+ * `Bun.serve`. Suitable for Cloudflare Workers, Deno Deploy, Vercel Edge,
+ * Netlify Edge, and any other Web-Fetch host.
+ *
+ * Handler registration (`registerApiHandler`, `registerPageHandler`, …) must
+ * happen *before* calling this factory — same contract as `startServer`.
+ *
+ * @example
+ * ```ts
+ * // Cloudflare Workers entry
+ * import { createAppFetchHandler } from "@mandujs/core";
+ * import manifest from "./.mandu/routes.manifest.json";
+ * import "./.mandu/edge-workers/register.js"; // populates registries
+ *
+ * const fetch = createAppFetchHandler(manifest, {
+ *   rootDir: "/",
+ *   edge: true,
+ *   cssPath: false,
+ * });
+ *
+ * export default { fetch };
+ * ```
+ */
+export function createAppFetchHandler(
+  manifest: RoutesManifest,
+  options: AppFetchHandlerOptions
+): (req: Request) => Promise<Response> {
+  const {
+    rootDir,
+    bundleManifest,
+    cors = false,
+    streaming = false,
+    rateLimit = false,
+    cssPath = false,
+    registry = defaultRegistry,
+    edge = false,
+    middleware,
+  } = options;
+
+  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,
+    edge,
+  };
+
+  registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
+
+  const router = new Router(manifest.routes);
+
+  return createFetchHandler({
+    router,
+    registry,
+    corsOptions,
+    middlewareFn: middleware?.fn ?? null,
+    middlewareConfig: middleware?.config ?? null,
+    handleRequest,
+  });
+}
+
 // ========== Rate Limiting Public API ==========
 
 /**