@mandujs/core 0.24.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,
@@ -376,6 +384,21 @@ export interface ServerOptions {
    *                   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 {
@@ -500,6 +523,16 @@ export interface ServerRegistrySettings {
    * 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 {
@@ -1920,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,
@@ -2005,6 +2048,10 @@ 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",
@@ -2107,6 +2154,11 @@ 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,
@@ -2505,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);
@@ -2533,10 +2607,12 @@ 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,
@@ -2698,6 +2774,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     transitions,
     prefetch,
     devtools,
+    observability: observabilityOption,
   } = options;
 
   // cssPath 처리:
@@ -2736,6 +2813,8 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     transitions,
     prefetch,
     devtools,
+    heapEndpoint: observabilityOption?.heapEndpoint,
+    metricsEndpoint: observabilityOption?.metricsEndpoint,
   };
 
   registry.rateLimiter = rateLimitOptions ? new MemoryRateLimiter() : null;
@@ -2802,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> => {
@@ -2816,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,

package/src/runtime/ssr.ts

@@ -1,7 +1,7 @@
 import { getRenderToString } from "./react-renderer";
 import { serializeProps } from "../client/serialize";
 import { createRequire } from "module";
-import type { ReactElement } from "react";
+import React, { type ReactElement, type ReactNode } from "react";
 import type { BundleManifest } from "../bundler/types";
 import { isSafeManduUrl } from "../bundler/manifest-schema";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
@@ -104,6 +104,18 @@ export interface SSROptions {
    * `ManduConfig.prefetch`.
    */
   prefetch?: boolean;
+  /**
+   * Issue #193 — control opt-out SPA navigation. When `true` (default)
+   * the client-side router intercepts every internal same-origin `<a>`
+   * click; when `false` the router reverts to the legacy opt-in
+   * behavior (only `<a data-mandu-link>` is intercepted).
+   *
+   * Wired from `ManduConfig.spa`. Emitted to the client as
+   * `window.__MANDU_SPA__ = false` ONLY when explicitly `false` — the
+   * default case emits nothing so the typical response payload is
+   * unchanged.
+   */
+  spa?: boolean;
   /**
    * Issue #191 — control dev-mode injection of the `_devtools.js` bundle
    * (~1.15 MB React dev runtime + Mandu Kitchen panel).
@@ -432,6 +444,99 @@ export function _testOnly_getAttachedCspNonce(options: SSROptions): string | und
   return OPTIONS_TO_NONCE.get(options as object);
 }
 
+/**
+ * Issue #198 — Pre-resolve async server components before handing the
+ * element tree to React's synchronous `renderToString`.
+ *
+ * React 19 supports async components natively in `renderToReadableStream`
+ * but NOT in `renderToString`. When a user writes:
+ *
+ *   export default async function Page() {
+ *     const data = await fetch(...).then(r => r.json());
+ *     return <h1>{data.title}</h1>;
+ *   }
+ *
+ * `React.createElement(Page)` returns an element whose `type` is an async
+ * function. Passing it to `renderToString` yields the opaque error
+ * "async/await is not yet supported in Client Components, only Server
+ * Components" (or silently renders the Promise as `[object Promise]`
+ * on older React builds). This helper walks the element tree, invokes
+ * each async component, awaits the resolved React tree, and recursively
+ * resolves nested async components — producing a fully-synchronous tree
+ * that `renderToString` can handle.
+ *
+ * Design notes:
+ *   - Only `typeof type === "function"` elements whose constructor is
+ *     `AsyncFunction` are invoked. Regular sync function components pass
+ *     through unchanged so React's normal render lifecycle (hooks,
+ *     Suspense, etc.) stays intact during `renderToString`.
+ *   - We recurse into `children` AND invoke async components whose
+ *     returned tree itself contains more async components — common in
+ *     `async Layout → async Page` nesting.
+ *   - Arrays, fragments, portals, and forward-refs are handled by the
+ *     same recursion (fragments and arrays expose children via props;
+ *     forwardRef/memo wrappers surface the underlying component via
+ *     `type.render` / `type.type`, which we do NOT unwrap — those are
+ *     opaque to us and sync by construction).
+ *   - If an async component throws, the rejection propagates up — the
+ *     caller (renderSSR / renderStreamingResponse) wraps it with the
+ *     existing `createSSRErrorResponse` 500 path. No new error surface.
+ *
+ * The helper returns a `ReactNode` (not strictly `ReactElement`) because
+ * async components may legitimately return primitives, arrays, null, or
+ * fragments.
+ */
+export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
+  // null | undefined | boolean | string | number — pass through. React
+  // treats these as leaf content.
+  if (node == null || typeof node !== "object") return node;
+
+  // Arrays (iterables of children) — resolve each entry in parallel.
+  // `Promise.all` is safe because order is preserved and async components
+  // are independent within an array.
+  if (Array.isArray(node)) {
+    return Promise.all(node.map((child) => resolveAsyncElement(child))) as Promise<ReactNode>;
+  }
+
+  // Non-element objects (Promises, iterables, etc.). React will handle
+  // Promises itself in streaming SSR, but for the sync path we forbid
+  // them — return as-is and let React error loudly.
+  if (!React.isValidElement(node)) return node;
+
+  const element = node as ReactElement;
+  const type = element.type;
+  const props = element.props as Record<string, unknown> | null | undefined;
+
+  // Async function component: invoke with props, await, recurse.
+  // `type.constructor.name === "AsyncFunction"` is the standard detection
+  // used throughout Mandu (see filling/filling.ts, runtime/compose.ts).
+  // We intentionally do NOT attempt to resolve generators or
+  // AsyncGeneratorFunctions — React has no semantics for those as
+  // components.
+  if (typeof type === "function" && (type as { constructor?: { name?: string } }).constructor?.name === "AsyncFunction") {
+    const resolved = await (type as (p: unknown) => Promise<ReactNode>)(props ?? {});
+    // Recurse — the resolved tree may itself contain more async components
+    // (e.g. async layout returning async page content).
+    return resolveAsyncElement(resolved);
+  }
+
+  // Sync element — recurse into children only. React handles sync
+  // function/class components itself during renderToString, so we
+  // do NOT invoke them here (that would disable their hooks, Context,
+  // Suspense boundaries, etc.).
+  if (!props) return element;
+  const rawChildren = props.children as ReactNode | undefined;
+  if (rawChildren === undefined) return element;
+
+  const resolvedChildren = await resolveAsyncElement(rawChildren);
+  if (resolvedChildren === rawChildren) return element;
+
+  // Clone with the resolved children. React.cloneElement preserves the
+  // element's key, ref, and internal `$$typeof` markers — a plain spread
+  // does not.
+  return React.cloneElement(element, undefined, resolvedChildren);
+}
+
 export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
   const {
     title = "Mandu App",
@@ -450,6 +555,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     islandPreWrapped,
     transitions = true,
     prefetch = true,
+    spa,
     devtools,
   } = options;
 
@@ -573,6 +679,16 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     devtoolsScript = generateDevtoolsScript(bundleManifest);
   }
 
+  // Issue #193 — surface `spa: false` to the client.
+  // We emit the global ONLY when explicitly `false` because `true` is
+  // the router's default, and a missing global is indistinguishable
+  // from `true` in the router's `handleLinkClick` check. This keeps
+  // the typical response payload (where `spa` is unset or `true`)
+  // byte-identical to pre-#193 output.
+  const spaFlagScript = spa === false
+    ? `<script>window.__MANDU_SPA__=false;</script>`
+    : "";
+
   // #179: body 내 <link> 태그를 <head>로 호이스팅
   // React 컴포넌트(layout.tsx 등)에서 <link>를 렌더링하면 body 안에 위치하게 되는데,
   // 폰트/스타일시트는 <head>에 있어야 FOUT 없이 로드됨
@@ -604,6 +720,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   ${routeScript}
   ${hydrationScripts}
   ${needsHydration ? REACT_INTERNALS_SHIM_SCRIPT : ""}
+  ${spaFlagScript}
   ${routerScript}
   ${hmrScript}
   ${devtoolsScript}

package/src/runtime/streaming-ssr.ts

@@ -1012,7 +1012,17 @@ export async function renderToStream(
   let shellSent = false;
   let timedOut = false;
 
-  // React renderToReadableStream 호출
+  // Issue #198 — `renderToReadableStream` natively supports async server
+  // components in React 19. If `export default async function Page()`
+  // lands here directly (without going through `server.ts`'s
+  // `resolveAsyncElement` pre-pass), React's streaming pipeline
+  // suspends on the awaiting component and flushes a fallback until
+  // the promise resolves. `collectStreamingHeadTags` above uses the
+  // sync `renderToString` and will throw on async trees — its
+  // try/catch safely returns an empty string in that case, and any
+  // `useHead`-pushed tags from async components are instead picked
+  // up by `buildHtmlTail` on the way out. No additional wiring is
+  // needed on this code path.
   // 실패 시 throw → renderStreamingResponse에서 500 처리
   const renderToReadableStream = getRenderToReadableStream();
   const reactStream = await renderToReadableStream(element, {