@mandujs/core 0.23.0 → 0.25.0

package/src/runtime/registry.ts

@@ -0,0 +1,171 @@
+/**
+ * Runtime manifest registry.
+ *
+ * This module provides the **official** accessor for generated content at
+ * runtime. User code must NEVER `import` anything under `.mandu/generated/`
+ * or any path containing `/generated/` — the guard rule
+ * `INVALID_GENERATED_IMPORT` catches that at build time.
+ *
+ * Why the indirection?
+ *
+ * - **Hot reload** — in dev, generated modules are rebuilt and re-imported.
+ *   A direct ESM import caches the first version; the registry re-reads the
+ *   current manifest on every access.
+ * - **Determinism** — compiled binaries (`bun build --compile`) embed a
+ *   fixed manifest. Direct imports would bypass the embedded copy and fail.
+ * - **ESM cache invalidation** — see #184. Transitive generated modules get
+ *   stuck on stale copies when hot-reload fires; the registry's `getManifest`
+ *   is the single choke point that the bundled importer invalidates cleanly.
+ *
+ * @see https://mandujs.com/docs/architect/generated-access
+ */
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Generated artifact map
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Map of generated artifacts keyed by well-known names.
+ *
+ * Extend this interface (via module augmentation) in consumers that emit
+ * their own generated artifacts — collections, resources, db schemas, etc.
+ *
+ * @example Module augmentation
+ * ```ts
+ * declare module "@mandujs/core/runtime" {
+ *   interface GeneratedRegistry {
+ *     collections: Record<string, CollectionIndex>;
+ *   }
+ * }
+ * ```
+ */
+export interface GeneratedRegistry {
+  /** Route manifest — the single source of truth for page/API routes. */
+  routes: RoutesManifest;
+}
+
+/** Union of well-known generated artifact keys. */
+export type GeneratedKey = keyof GeneratedRegistry;
+
+/** Typed accessor — narrows the return shape from the key. */
+export type GeneratedShape<K extends GeneratedKey> = GeneratedRegistry[K];
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Global registry state
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * The live manifest, populated by `registerManifest()` (typically driven by
+ * `registerManifestHandlers()` from `@mandujs/cli`). Kept on `globalThis`
+ * so reloading the core module in dev does not lose registration.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __MANDU_MANIFEST__: Partial<GeneratedRegistry> | undefined;
+}
+
+function ensureGlobalSlot(): Partial<GeneratedRegistry> {
+  if (!globalThis.__MANDU_MANIFEST__) {
+    globalThis.__MANDU_MANIFEST__ = {};
+  }
+  return globalThis.__MANDU_MANIFEST__;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Public API
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Register a generated artifact under a well-known key.
+ *
+ * Called by the framework (typically from `registerManifestHandlers()` in
+ * `@mandujs/cli`) during server boot. User code normally does not call this
+ * directly — the only exception is tests that want to seed a manifest.
+ *
+ * @example Test setup
+ * ```ts
+ * import { registerManifest, clearGeneratedRegistry } from "@mandujs/core/runtime";
+ *
+ * beforeEach(() => clearGeneratedRegistry());
+ * registerManifest("routes", { version: 1, routes: [] });
+ * ```
+ */
+export function registerManifest<K extends GeneratedKey>(
+  key: K,
+  value: GeneratedShape<K>,
+): void {
+  const slot = ensureGlobalSlot();
+  slot[key] = value;
+}
+
+/**
+ * Read a generated artifact by key. Throws a helpful error if the manifest
+ * has not been registered yet — this almost always means the server boot
+ * skipped `registerManifestHandlers()` or the test forgot to seed fixtures.
+ *
+ * @example Reading the route manifest
+ * ```ts
+ * import { getGenerated } from "@mandujs/core/runtime";
+ *
+ * const manifest = getGenerated("routes");
+ * for (const route of manifest.routes) {
+ *   console.log(route.id, route.pattern);
+ * }
+ * ```
+ *
+ * @throws {Error} when the key has not been registered
+ */
+export function getGenerated<K extends GeneratedKey>(key: K): GeneratedShape<K> {
+  const slot = globalThis.__MANDU_MANIFEST__;
+  if (!slot || !(key in slot) || slot[key] === undefined) {
+    throw new Error(
+      `[Mandu] Generated artifact "${String(key)}" not registered. ` +
+        `Call registerManifestHandlers() during server boot, or seed the ` +
+        `manifest with registerManifest("${String(key)}", …) in tests. ` +
+        `See https://mandujs.com/docs/architect/generated-access`,
+    );
+  }
+  return slot[key] as GeneratedShape<K>;
+}
+
+/**
+ * Return the registered artifact, or `undefined` if absent. Prefer
+ * `getGenerated()` for the common case — this variant exists for hot paths
+ * where absence is not an error (e.g., optional collections).
+ */
+export function tryGetGenerated<K extends GeneratedKey>(
+  key: K,
+): GeneratedShape<K> | undefined {
+  const slot = globalThis.__MANDU_MANIFEST__;
+  return slot?.[key] as GeneratedShape<K> | undefined;
+}
+
+/**
+ * Return the full routes manifest. Thin wrapper around `getGenerated("routes")`
+ * kept for call-site readability.
+ *
+ * @throws {Error} when no manifest has been registered yet
+ */
+export function getManifest(): RoutesManifest {
+  return getGenerated("routes");
+}
+
+/**
+ * Find a single route by its stable ID. Returns `undefined` if no match.
+ * Use this instead of `manifest.routes.find(…)` at call sites that already
+ * want the readability of a named helper.
+ */
+export function getRouteById(id: string): RouteSpec | undefined {
+  const manifest = tryGetGenerated("routes");
+  if (!manifest) return undefined;
+  return manifest.routes.find((route) => route.id === id);
+}
+
+/**
+ * Clear all registered artifacts. Test-only — production code should never
+ * call this.
+ */
+export function clearGeneratedRegistry(): void {
+  globalThis.__MANDU_MANIFEST__ = {};
+}

package/src/runtime/server.ts

@@ -4,7 +4,7 @@ import type { BundleManifest } from "../bundler/types";
 import type { ManduFilling, RenderMode } from "../filling/filling";
 import { ManduContext, CookieManager } from "../filling/context";
 import { Router } from "./router";
-import { renderSSR, renderStreamingResponse } from "./ssr";
+import { renderSSR, renderStreamingResponse, resolveAsyncElement } from "./ssr";
 import {
   resolveMetadata,
   renderMetadata,
@@ -49,6 +49,14 @@ import {
 import { validateImportPath } from "./security";
 import { KITCHEN_PREFIX, KitchenHandler, recordRequest } from "../kitchen/kitchen-handler";
 import { eventBus } from "../observability/event-bus";
+import {
+  HEAP_ENDPOINT,
+  METRICS_ENDPOINT,
+  buildHeapResponse,
+  buildMetricsResponse,
+  isObservabilityExposed,
+  recordHttpRequest,
+} from "../observability/metrics";
 import {
   type MiddlewareFn,
   type MiddlewareConfig,
@@ -350,6 +358,47 @@ 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;
+  /**
+   * Phase 17 — observability endpoints.
+   *   - `heapEndpoint`    → `/_mandu/heap` JSON dump of process.memoryUsage()
+   *                         + registered cache sizes. In dev this is on by
+   *                         default; in prod it requires `MANDU_DEBUG_HEAP=1`
+   *                         OR this flag set to `true`.
+   *   - `metricsEndpoint` → `/_mandu/metrics` Prometheus text exposition.
+   *                         Same gating as `heapEndpoint`.
+   * Passing `false` for either in dev force-disables it (useful for
+   * isolating test environments that count listeners).
+   */
+  observability?: {
+    heapEndpoint?: boolean;
+    metricsEndpoint?: boolean;
+  };
 }
 
 export interface ManduServer {
@@ -456,6 +505,34 @@ export interface ServerRegistrySettings {
    * 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;
+  /**
+   * Phase 17 — `/_mandu/heap` JSON exposure. `undefined` uses the
+   * default for the current mode (dev → on, prod → MANDU_DEBUG_HEAP).
+   */
+  heapEndpoint?: boolean;
+  /**
+   * Phase 17 — `/_mandu/metrics` Prometheus exposure. Same defaulting
+   * as `heapEndpoint`.
+   */
+  metricsEndpoint?: boolean;
 }
 
 export class ServerRegistry {
@@ -1876,6 +1953,16 @@ async function renderPageSSR(
       ? route.streaming
       : settings.streaming;
 
+    // Issue #198 — Pre-resolve async server components before handing off
+    // to React's SSR engines. `renderToString` (non-streaming path) does
+    // not support async components; `renderToReadableStream` does, but
+    // the shell-gen step in streaming-ssr also falls through
+    // `collectStreamingHeadTags` → `renderToString`. Resolving up-front
+    // gives consistent, synchronous trees to both paths and keeps the
+    // user-visible contract (`export default async function Page() {...}`
+    // and `export default async function Layout() {...}`) working end to end.
+    app = (await resolveAsyncElement(app)) as React.ReactElement;
+
     if (useStreaming) {
       const streamingResponse = await renderStreamingResponse(app, {
         title: builtMeta.title,
@@ -1889,6 +1976,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}`);
@@ -1924,6 +2014,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) {
@@ -1955,11 +2048,18 @@ async function renderPageSSR(
             errorApp = await wrapWithLayouts(errorApp, route.layoutChain, registry, params, layoutData);
           }
 
+          // Issue #198 — resolve async layouts wrapping the error component
+          // so `async function Layout()` still renders on the 500 surface.
+          errorApp = (await resolveAsyncElement(errorApp)) as React.ReactElement;
+
           const errorHtml = renderSSR(errorApp, {
             // 에러 상태에서는 resolveMetadata 결과를 신뢰할 수 없을 수 있으므로 리터럴 사용
             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);
         }
@@ -2054,10 +2154,18 @@ async function renderNotFoundPage(
       app = await wrapWithLayouts(app, route.layoutChain, registry, params, layoutData);
     }
 
+    // Issue #198 — users may author `not-found.tsx` as an async server
+    // component (e.g. to fetch copy from a CMS). Resolve the async tree
+    // before the sync renderSSR path.
+    app = (await resolveAsyncElement(app)) as React.ReactElement;
+
     const html = renderSSR(app, {
       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.
@@ -2449,6 +2557,28 @@ async function handleRequestInternal(
     return ok(handleEventsRecentRequest(req));
   }
 
+  // Phase 17 — heap snapshot + Prometheus metrics endpoints.
+  //
+  // Gating: dev mode exposes by default so the DX is zero-friction. Prod
+  // requires either `MANDU_DEBUG_HEAP=1` or explicit `observability.heapEndpoint:
+  // true` in `ServerOptions`. Operators can opt-out of even the dev exposure by
+  // passing `observability.heapEndpoint: false` (useful in tests that count
+  // listeners / assert route shape).
+  //
+  // Missing endpoints return 404 via the normal route-not-found path —
+  // scrapers can't distinguish "disabled" from "never existed". See
+  // `docs/ops/metrics.md` for the operator-facing guide.
+  if (pathname === HEAP_ENDPOINT) {
+    if (isObservabilityExposed(settings.isDev, settings.heapEndpoint)) {
+      return ok(buildHeapResponse());
+    }
+  }
+  if (pathname === METRICS_ENDPOINT) {
+    if (isObservabilityExposed(settings.isDev, settings.metricsEndpoint)) {
+      return ok(buildMetricsResponse());
+    }
+  }
+
   // 2. Kitchen dev dashboard (dev mode only)
   if (settings.isDev && pathname.startsWith(KITCHEN_PREFIX) && registry.kitchen) {
     const kitchenResponse = await registry.kitchen.handle(req, pathname);
@@ -2477,14 +2607,19 @@ async function handleRequestInternal(
             console.warn(`[Mandu] not-found.tsx loader threw (unmatched URL):`, loaderError);
           }
         }
-        const app = React.createElement(registration.component, {
+        const rawApp = React.createElement(registration.component, {
           params: {},
           loaderData,
         });
+        // Issue #198 — pre-resolve in case the not-found component is async.
+        const app = (await resolveAsyncElement(rawApp)) as React.ReactElement;
         const html = renderSSR(app, {
           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();
@@ -2586,10 +2721,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,
@@ -2603,6 +2771,10 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     guardConfig = null,
     cache: cacheOption,
     managementToken,
+    transitions,
+    prefetch,
+    devtools,
+    observability: observabilityOption,
   } = options;
 
   // cssPath 처리:
@@ -2638,6 +2810,11 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     rateLimit: rateLimitOptions,
     cssPath,
     managementToken,
+    transitions,
+    prefetch,
+    devtools,
+    heapEndpoint: observabilityOption?.heapEndpoint,
+    metricsEndpoint: observabilityOption?.metricsEndpoint,
   };
 
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
@@ -2704,6 +2881,21 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     },
   } : undefined;
 
+  // Phase 17 — bump the Prometheus request counter once per Response we
+  // actually produce. WebSocket upgrades (return `undefined`) are
+  // deliberately skipped so the counter only reflects plain HTTP traffic.
+  // Errors from `recordHttpRequest` are impossible to surface here — the
+  // Map update is synchronous and self-contained — but we still try/catch
+  // as defence-in-depth.
+  const bumpCounter = (req: Request, res: Response | undefined): void => {
+    if (!res) return;
+    try {
+      recordHttpRequest(req.method, res.status);
+    } catch {
+      // Never let an observability hiccup break a request.
+    }
+  };
+
   // fetch handler: WS upgrade 감지 추가
   const wrappedFetch = hasWsRoutes
     ? async (req: Request, bunServer: Server<undefined>): Promise<Response | undefined> => {
@@ -2718,9 +2910,15 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
             return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
           }
         }
-        return fetchHandler(req);
+        const res = await fetchHandler(req);
+        bumpCounter(req, res);
+        return res;
       }
-    : async (req: Request): Promise<Response> => fetchHandler(req);
+    : async (req: Request): Promise<Response> => {
+        const res = await fetchHandler(req);
+        bumpCounter(req, res);
+        return res;
+      };
 
   const { server, port: actualPort, attempts } = startBunServerWithFallback({
     port,
@@ -2737,8 +2935,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}`);
     }
@@ -2750,10 +2953,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`);
     }