@mandujs/core 0.54.21 → 0.54.22

package/package.json

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

package/src/client/router.ts

@@ -165,42 +165,42 @@ const patternCache = new LRUCache<string, CompiledPattern>(LIMITS.ROUTER_PATTERN
 // because `registerCacheSize` replaces any prior reporter under the same key.
 registerCacheSize("patternCache", () => patternCache.size);
 
-/**
- * 패턴을 정규식으로 컴파일
- */
-function compilePattern(pattern: string): CompiledPattern {
-  const cached = patternCache.get(pattern);
-  if (cached) return cached;
-
-  const paramNames: string[] = [];
-  const normalized = pattern === "/" ? "/" : pattern.replace(/\/+$/, "") || "/";
-  const segments = normalized.split("/").filter(Boolean);
-
-  const regexStr = segments.length === 0
-    ? "/"
-    : segments.map((segment) => {
-        if (segment === "*") {
-          return "/.+";
-        }
-
-        const wildcardMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\*(\?)?$/);
-        if (wildcardMatch) {
-          paramNames.push(wildcardMatch[1]);
-          return wildcardMatch[2] === "?" ? "(?:/(.*))?" : "/(.+)";
-        }
-
-        const paramMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)$/);
-        if (paramMatch) {
-          paramNames.push(paramMatch[1]);
-          return "/([^/]+)";
-        }
-
-        return `/${escapePatternSegment(segment)}`;
-      }).join("");
-
-  const compiled = {
-    regex: new RegExp(`^${regexStr}$`),
-    paramNames,
+/**
+ * 패턴을 정규식으로 컴파일
+ */
+function compilePattern(pattern: string): CompiledPattern {
+  const cached = patternCache.get(pattern);
+  if (cached) return cached;
+
+  const paramNames: string[] = [];
+  const normalized = pattern === "/" ? "/" : pattern.replace(/\/+$/, "") || "/";
+  const segments = normalized.split("/").filter(Boolean);
+
+  const regexStr = segments.length === 0
+    ? "/"
+    : segments.map((segment) => {
+        if (segment === "*") {
+          return "/.+";
+        }
+
+        const wildcardMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)\*(\?)?$/);
+        if (wildcardMatch) {
+          paramNames.push(wildcardMatch[1]);
+          return wildcardMatch[2] === "?" ? "(?:/(.*))?" : "/(.+)";
+        }
+
+        const paramMatch = segment.match(/^:([a-zA-Z_][a-zA-Z0-9_]*)$/);
+        if (paramMatch) {
+          paramNames.push(paramMatch[1]);
+          return "/([^/]+)";
+        }
+
+        return `/${escapePatternSegment(segment)}`;
+      }).join("");
+
+  const compiled = {
+    regex: new RegExp(`^${regexStr}$`),
+    paramNames,
   };
 
   patternCache.set(pattern, compiled);
@@ -219,17 +219,17 @@ function extractParamsFromPath(
 
   if (!match) return {};
 
-  const params: Record<string, string> = {};
-  compiled.paramNames.forEach((name, index) => {
-    params[name] = match[index + 1] ?? "";
-  });
-
-  return params;
-}
-
-function escapePatternSegment(segment: string): string {
-  return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
+  const params: Record<string, string> = {};
+  compiled.paramNames.forEach((name, index) => {
+    params[name] = match[index + 1] ?? "";
+  });
+
+  return params;
+}
+
+function escapePatternSegment(segment: string): string {
+  return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 
 // ========== Navigation ==========
 
@@ -324,6 +324,16 @@ export async function navigate(
     // json 파싱 사이에 새 네비게이션이 시작됐을 수 있음
     if (controller.signal.aborted) return;
 
+    // #316: server-only target (no client-renderable route component). A
+    // client-side state update would change the URL but not the content
+    // ("click does nothing / goes back"). Fall back to a full document
+    // navigation so the server SSRs the page. `=== false` is intentional:
+    // older servers omit the flag, and we must not regress those.
+    if (data.clientRenderable === false) {
+      window.location.href = url.href;
+      return;
+    }
+
     // 상태 + History + 스크롤을 한 번에 적용하는 함수
     const applyUpdate = () => {
       const historyState = { routeId: data.routeId, params: data.params };

package/src/runtime/server.ts

@@ -2638,11 +2638,22 @@ async function handlePageRoute(
     // in prod is zero-value attack surface (request-triggered response
     // header reflection). Silently ignore the request header instead.
     const isHDR = settings.isDev && req.headers.get("x-mandu-hdr") === "1";
+    // #316: tell the full SPA router whether it can render this route on the
+    // client. Server-only pages (no route-level client hydration bundle) have
+    // no client component, so a pushState + state update leaves the URL changed
+    // but the content stale. When false, the router must fall back to a full
+    // document navigation so the server re-renders the page.
+    const clientRenderable = !!(
+      route.hydration &&
+      route.hydration.strategy !== "none" &&
+      settings.bundleManifest?.bundles[route.id]?.js
+    );
     const jsonResponse = Response.json({
       routeId: route.id,
       pattern: route.pattern,
       params,
       loaderData: loaderData ?? null,
+      clientRenderable,
       timestamp: Date.now(),
     });
     if (isHDR) {

package/src/runtime/ssr.ts

@@ -6,13 +6,13 @@ import type { BundleManifest } from "../bundler/types";
 import { isSafeManduUrl } from "../bundler/manifest-schema";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { PORTS, TIMEOUTS } from "../constants";
-import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
+import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
-import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
+import { generateFastRefreshPreamble } from "../bundler/fast-refresh-preamble";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
 import { SPA_NAV_HELPER_SCRIPT } from "../client/spa-nav-helper";
-import { maybeInjectDevOverlay } from "../dev-error-overlay";
-import { renderWithManduClientBoundaryManifest } from "../internal/client-boundary";
+import { maybeInjectDevOverlay } from "../dev-error-overlay";
+import { renderWithManduClientBoundaryManifest } from "../internal/client-boundary";
 
 /**
  * Issue #192 — `@view-transition` at-rule block.
@@ -47,7 +47,7 @@ export interface SSROptions {
   title?: string;
   lang?: string;
   /** 서버에서 로드한 데이터 (클라이언트로 전달) */
-  serverData?: unknown;
+  serverData?: unknown;
   /** Hydration 설정 */
   hydration?: HydrationConfig;
   /** 번들 매니페스트 */
@@ -256,36 +256,36 @@ function generateHydrationScripts(
     ? Object.values(manifest.islands).filter((ib) => ib.route === routeId)
     : [];
 
-  if (routeIslands.length > 0) {
-    for (const ib of routeIslands) {
-      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
+  if (routeIslands.length > 0) {
+    for (const ib of routeIslands) {
+      const cacheBust = `${ib.js}${ib.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
   } else {
     // Fallback: route-level bundle (backward compat)
     const bundle = manifest.bundles[routeId];
     if (bundle) {
       const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
-
-  if (manifest.partials) {
-    for (const partial of Object.values(manifest.partials)) {
-      const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
-
-  if (manifest.boundaries) {
-    for (const boundary of Object.values(manifest.boundaries)) {
-      if (boundary.route !== routeId) continue;
-      const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
-  }
-
-  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  if (manifest.partials) {
+    for (const partial of Object.values(manifest.partials)) {
+      const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  if (manifest.boundaries) {
+    for (const boundary of Object.values(manifest.boundaries)) {
+      if (boundary.route !== routeId) continue;
+      const cacheBust = `${boundary.js}${boundary.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+  }
+
+  // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
     scripts.push(`<script type="module" src="${escapeHtmlAttr(manifest.shared.runtime)}"></script>`);
   }
@@ -628,9 +628,9 @@ export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
   return React.cloneElement(element, undefined, resolvedChildren);
 }
 
-export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const hasExplicitTitle = options.title !== undefined;
-  const {
+export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
+  const hasExplicitTitle = options.title !== undefined;
+  const {
     title = "Mandu App",
     lang = "ko",
     serverData,
@@ -712,9 +712,9 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   } catch { /* client 모듈 로드 실패 시 무시 */ }
 
   const renderToString = getRenderToString();
-  let content = renderWithManduClientBoundaryManifest(routeId, bundleManifest, () =>
-    renderToString(element),
-  );
+  let content = renderWithManduClientBoundaryManifest(routeId, bundleManifest, () =>
+    renderToString(element),
+  );
 
   // 렌더링 중 수집된 head 태그
   collectedHeadTags = headGet?.() ?? "";
@@ -724,14 +724,14 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   const needsHydration =
     hydration && hydration.strategy !== "none" && routeId && bundleManifest;
 
-  if (needsHydration && !islandPreWrapped) {
-    // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
-    const bundle = bundleManifest.bundles[routeId];
-    const bundleSrc = bundle?.js;
-    if (bundleSrc) {
-      content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
-    }
-  }
+  if (needsHydration && !islandPreWrapped) {
+    // v0.8.0: bundleSrc를 data-mandu-src 속성으로 전달 (Runtime이 dynamic import로 로드)
+    const bundle = bundleManifest.bundles[routeId];
+    const bundleSrc = bundle?.js;
+    if (bundleSrc) {
+      content = wrapWithIsland(content, routeId, hydration.priority, bundleSrc);
+    }
+  }
 
   // Zero-JS 모드: island이 없는 페이지에서는 클라이언트 JS 번들을 전송하지 않음
   // HMR/DevTools는 dev 환경에서만 유지 (CSS 핫리로드 등)
@@ -742,10 +742,10 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 
   if (needsHydration) {
     // 서버 데이터 스크립트 (클라이언트 hydration에서 사용)
-    if (serverData !== undefined && routeId) {
-      const wrappedData = {
-        [routeId]: {
-          serverData,
+    if (serverData !== undefined && routeId) {
+      const wrappedData = {
+        [routeId]: {
+          serverData,
           timestamp: Date.now(),
         },
       };
@@ -814,28 +814,52 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     ? `<script>window.__MANDU_SPA__=false;</script>`
     : "";
 
-  // #179: body 내 <link> 태그를 <head>로 호이스팅
+  // #179: body 내 <link> 태그를 <head>로 호이스팅
   // React 컴포넌트(layout.tsx 등)에서 <link>를 렌더링하면 body 안에 위치하게 되는데,
   // 폰트/스타일시트는 <head>에 있어야 FOUT 없이 로드됨
   const linkTagPattern = /<link\s[^>]*(?:rel=["'](?:stylesheet|preconnect|preload|icon|dns-prefetch)["'][^>]*|href=["'][^"']+["'][^>]*)\/?\s*>/gi;
   const hoistedLinks: string[] = [];
-  const bodyContent = content.replace(linkTagPattern, (match) => {
+  const bodyAfterLinks = content.replace(linkTagPattern, (match) => {
     hoistedLinks.push(match);
     return "";
   });
-  const hoistedLinkTags = hoistedLinks.join("\n  ");
-
-  // #273 F15 — React 19 renders document metadata such as <title> from a
-  // page component into the body string in this SSR path. Hoist the first
-  // body title into <head> when no metadata/generateMetadata title was
-  // provided, and always strip body titles to avoid duplicate/invalid HTML.
-  let effectiveTitle = title;
-  const titleTagPattern = /<title(?:\s[^>]*)?>([\s\S]*?)<\/title>/i;
-  const bodyTitleMatch = bodyContent.match(titleTagPattern);
-  const bodyWithoutTitle = bodyContent.replace(/<title(?:\s[^>]*)?>[\s\S]*?<\/title>/gi, "");
-  if (!hasExplicitTitle && bodyTitleMatch) {
-    effectiveTitle = decodeHtmlText(bodyTitleMatch[1] ?? title);
-  }
+  const hoistedLinkTags = hoistedLinks.join("\n  ");
+
+  // #317: hoist body <meta> (og:*, twitter:*, description, …) and JSON-LD into
+  // <head>. The legacy renderToString path does not perform React 19's
+  // document-metadata hoisting, so without this og/twitter cards land in the
+  // body where crawlers ignore them. Mirrors React 19's rule: <meta> is
+  // hoistable document metadata EXCEPT microdata (`itemprop`), which is
+  // content and must stay where it was authored.
+  const metaTagPattern = /<meta\s[^>]*?\/?>/gi;
+  const hoistedMetas: string[] = [];
+  const bodyAfterMeta = bodyAfterLinks.replace(metaTagPattern, (match) => {
+    if (/\bitemprop[\s=]/i.test(match)) return match;
+    hoistedMetas.push(match);
+    return "";
+  });
+  const hoistedMetaTags = hoistedMetas.join("\n  ");
+
+  const ldJsonPattern =
+    /<script\s[^>]*type=["']application\/ld\+json["'][^>]*>[\s\S]*?<\/script>/gi;
+  const hoistedLdJson: string[] = [];
+  const bodyContent = bodyAfterMeta.replace(ldJsonPattern, (match) => {
+    hoistedLdJson.push(match);
+    return "";
+  });
+  const hoistedLdJsonTags = hoistedLdJson.join("\n  ");
+
+  // #273 F15 — React 19 renders document metadata such as <title> from a
+  // page component into the body string in this SSR path. Hoist the first
+  // body title into <head> when no metadata/generateMetadata title was
+  // provided, and always strip body titles to avoid duplicate/invalid HTML.
+  let effectiveTitle = title;
+  const titleTagPattern = /<title(?:\s[^>]*)?>([\s\S]*?)<\/title>/i;
+  const bodyTitleMatch = bodyContent.match(titleTagPattern);
+  const bodyWithoutTitle = bodyContent.replace(/<title(?:\s[^>]*)?>[\s\S]*?<\/title>/gi, "");
+  if (!hasExplicitTitle && bodyTitleMatch) {
+    effectiveTitle = decodeHtmlText(bodyTitleMatch[1] ?? title);
+  }
 
   // Phase 18.α — Dev Error Overlay injection.
   // Only emitted when `isDev` AND the user has not opted out (via
@@ -853,19 +877,21 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${escapeHtmlText(effectiveTitle)}</title>
+  <title>${escapeHtmlText(effectiveTitle)}</title>
   ${cssLinkTag}
   ${viewTransitionTag}
   ${prefetchScriptTag}
   ${spaNavHelperTag}
   ${hoistedLinkTags}
+  ${hoistedMetaTags}
+  ${hoistedLdJsonTags}
   ${headTags}
   ${collectedHeadTags}
   ${fastRefreshPreamble}
   ${devErrorOverlayTag}
 </head>
 <body>
-  <div id="root"${rootAttrs}>${bodyWithoutTitle}</div>
+  <div id="root"${rootAttrs}>${bodyWithoutTitle}</div>
   ${dataScript}
   ${routeScript}
   ${hydrationScripts}
@@ -882,11 +908,11 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 /**
  * Client-side Routing: 현재 라우트 정보 스크립트 생성
  */
-function generateRouteScript(
-  routeId: string,
-  pattern: string,
-  _serverData?: unknown
-): string {
+function generateRouteScript(
+  routeId: string,
+  pattern: string,
+  _serverData?: unknown
+): string {
   const routeInfo = {
     id: routeId,
     pattern,
@@ -1187,12 +1213,12 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
  */
 export async function renderWithHydration(
   element: ReactElement,
-  options: SSROptions & {
-    routeId: string;
-    serverData: unknown;
-    hydration: HydrationConfig;
-    bundleManifest: BundleManifest;
-  }
+  options: SSROptions & {
+    routeId: string;
+    serverData: unknown;
+    hydration: HydrationConfig;
+    bundleManifest: BundleManifest;
+  }
 ): Promise<Response> {
   const html = renderToHTML(element, options);
   // Phase 7.2 R1 Agent C (H1) — same CSP header logic as renderSSR.