@mandujs/core 0.54.1 → 0.54.3

package/src/runtime/ssr.ts

@@ -6,7 +6,7 @@ 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 { escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
+import { decodeHtmlText, escapeHtmlAttr, escapeHtmlText, escapeJsonForInlineScript } from "./escape";
 import { REACT_INTERNALS_SHIM_SCRIPT } from "./shims";
 import { generateFastRefreshPreamble } from "../bundler/dev";
 import { PREFETCH_HELPER_SCRIPT } from "../client/prefetch-helper";
@@ -46,7 +46,7 @@ export interface SSROptions {
   title?: string;
   lang?: string;
   /** 서버에서 로드한 데이터 (클라이언트로 전달) */
-  serverData?: Record<string, unknown>;
+  serverData?: unknown;
   /** Hydration 설정 */
   hydration?: HydrationConfig;
   /** 번들 매니페스트 */
@@ -255,19 +255,26 @@ 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)}">`);
-    }
-  }
+      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)}">`);
+    }
+  }
 
   // Runtime 로드 (hydrateIslands 실행 - dynamic import 사용)
   if (manifest.shared.runtime) {
@@ -612,8 +619,9 @@ export async function resolveAsyncElement(node: ReactNode): Promise<ReactNode> {
   return React.cloneElement(element, undefined, resolvedChildren);
 }
 
-export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
-  const {
+export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
+  const hasExplicitTitle = options.title !== undefined;
+  const {
     title = "Mandu App",
     lang = "ko",
     serverData,
@@ -705,12 +713,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;
-    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 핫리로드 등)
@@ -721,10 +731,10 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 
   if (needsHydration) {
     // 서버 데이터 스크립트 (클라이언트 hydration에서 사용)
-    if (serverData && routeId) {
-      const wrappedData = {
-        [routeId]: {
-          serverData,
+    if (serverData !== undefined && routeId) {
+      const wrappedData = {
+        [routeId]: {
+          serverData,
           timestamp: Date.now(),
         },
       };
@@ -793,7 +803,7 @@ 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;
@@ -802,7 +812,19 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
     hoistedLinks.push(match);
     return "";
   });
-  const hoistedLinkTags = hoistedLinks.join("\n  ");
+  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);
+  }
 
   // Phase 18.α — Dev Error Overlay injection.
   // Only emitted when `isDev` AND the user has not opted out (via
@@ -820,7 +842,7 @@ 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(title)}</title>
+  <title>${escapeHtmlText(effectiveTitle)}</title>
   ${cssLinkTag}
   ${viewTransitionTag}
   ${prefetchScriptTag}
@@ -832,7 +854,7 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
   ${devErrorOverlayTag}
 </head>
 <body>
-  <div id="root"${rootAttrs}>${bodyContent}</div>
+  <div id="root"${rootAttrs}>${bodyWithoutTitle}</div>
   ${dataScript}
   ${routeScript}
   ${hydrationScripts}
@@ -849,11 +871,11 @@ export function renderToHTML(element: ReactElement, options: SSROptions = {}): s
 /**
  * Client-side Routing: 현재 라우트 정보 스크립트 생성
  */
-function generateRouteScript(
-  routeId: string,
-  pattern: string,
-  _serverData?: Record<string, unknown>
-): string {
+function generateRouteScript(
+  routeId: string,
+  pattern: string,
+  _serverData?: unknown
+): string {
   const routeInfo = {
     id: routeId,
     pattern,
@@ -1154,12 +1176,12 @@ export function renderSSR(element: ReactElement, options: SSROptions = {}): Resp
  */
 export async function renderWithHydration(
   element: ReactElement,
-  options: SSROptions & {
-    routeId: string;
-    serverData: Record<string, 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.

package/src/runtime/static-files.ts

@@ -0,0 +1,289 @@
+import type { BunFile } from "bun";
+import path from "path";
+import fs from "fs/promises";
+
+export interface StaticFileSettings {
+  isDev: boolean;
+  rootDir: string;
+  publicDir: string;
+}
+
+export interface StaticFileResult {
+  handled: boolean;
+  response?: Response;
+}
+
+const MIME_TYPES: Record<string, string> = {
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".ts": "application/typescript",
+  ".css": "text/css",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject",
+  ".pdf": "application/pdf",
+  ".txt": "text/plain",
+  ".xml": "application/xml",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".wasm": "application/wasm",
+  ".map": "application/json",
+};
+
+const PUBLIC_FLAT_ASSET_EXTENSIONS = new Set<string>([
+  ".webp", ".avif", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".ico",
+  ".pdf", ".zip", ".mp4", ".webm", ".mp3", ".wav",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".css", ".js", ".map",
+]);
+
+interface EtagCacheEntry {
+  size: number;
+  mtime: number;
+  etag: string;
+}
+
+const etagCache = new Map<string, EtagCacheEntry>();
+const ETAG_CACHE_MAX = 2048;
+
+function getMimeType(filePath: string): string {
+  const ext = path.extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] || "application/octet-stream";
+}
+
+function hasContentHashInFilename(filename: string): boolean {
+  return /[.\-][a-f0-9]{8,}\.[a-z0-9]+$/i.test(filename);
+}
+
+export function computeStaticCacheControl(filename: string, isDev: boolean): string {
+  if (isDev) return "no-cache, no-store, must-revalidate";
+  if (hasContentHashInFilename(filename)) {
+    return "public, max-age=31536000, immutable";
+  }
+  return "public, max-age=0, must-revalidate";
+}
+
+function evictEtagCacheIfNeeded(): void {
+  if (etagCache.size <= ETAG_CACHE_MAX) return;
+  const oldestKey = etagCache.keys().next().value;
+  if (oldestKey !== undefined) etagCache.delete(oldestKey);
+}
+
+export async function computeStrongEtag(
+  filePath: string,
+  file: BunFile,
+): Promise<string> {
+  const size = file.size;
+  const mtime = file.lastModified;
+
+  const cached = etagCache.get(filePath);
+  if (cached && cached.size === size && cached.mtime === mtime) {
+    return cached.etag;
+  }
+
+  let digest: string;
+  try {
+    const bytes = await file.arrayBuffer();
+    const hash = Bun.hash(bytes);
+    digest = typeof hash === "bigint" ? hash.toString(36) : Number(hash).toString(36);
+  } catch {
+    digest = `${size.toString(36)}-${mtime.toString(36)}`;
+  }
+
+  const etag = `"${digest}"`;
+  etagCache.set(filePath, { size, mtime, etag });
+  evictEtagCacheIfNeeded();
+  return etag;
+}
+
+export function __clearStaticEtagCacheForTests(): void {
+  etagCache.clear();
+}
+
+export function matchesEtag(ifNoneMatch: string, currentEtag: string): boolean {
+  const trimmed = ifNoneMatch.trim();
+  if (trimmed === "*") return true;
+
+  const normalize = (tag: string): string => {
+    const next = tag.trim();
+    return next.startsWith("W/") ? next.slice(2) : next;
+  };
+
+  const currentNormalized = normalize(currentEtag);
+  for (const part of trimmed.split(",")) {
+    if (normalize(part) === currentNormalized) return true;
+  }
+  return false;
+}
+
+async function isPathSafe(filePath: string, allowedDir: string): Promise<boolean> {
+  try {
+    const resolvedPath = path.resolve(filePath);
+    const resolvedAllowedDir = path.resolve(allowedDir);
+
+    if (
+      !resolvedPath.startsWith(resolvedAllowedDir + path.sep) &&
+      resolvedPath !== resolvedAllowedDir
+    ) {
+      return false;
+    }
+
+    try {
+      await fs.access(resolvedPath);
+    } catch {
+      return true;
+    }
+
+    const realPath = await fs.realpath(resolvedPath);
+    const realAllowedDir = await fs.realpath(resolvedAllowedDir);
+
+    return realPath.startsWith(realAllowedDir + path.sep) ||
+      realPath === realAllowedDir;
+  } catch (error) {
+    console.warn(`[Mandu Security] Path validation failed: ${filePath}`, error);
+    return false;
+  }
+}
+
+function createStaticErrorResponse(status: 400 | 403 | 404 | 500): Response {
+  const body = {
+    400: "Bad Request",
+    403: "Forbidden",
+    404: "Not Found",
+    500: "Internal Server Error",
+  }[status];
+
+  return new Response(body, { status });
+}
+
+export async function serveStaticFile(
+  pathname: string,
+  settings: StaticFileSettings,
+  request?: Request,
+): Promise<StaticFileResult> {
+  let filePath: string | null = null;
+  let isBundleFile = false;
+  let isPublicFlatFallback = false;
+  let allowRouteFallbackOnMissing = false;
+  let allowedBaseDir: string;
+  let relativePath: string;
+
+  if (pathname.startsWith("/.mandu/client/")) {
+    relativePath = pathname.slice("/.mandu/client/".length);
+    allowedBaseDir = path.join(settings.rootDir, ".mandu", "client");
+    isBundleFile = true;
+  } else if (pathname.startsWith("/public/")) {
+    relativePath = pathname.slice("/public/".length);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  } else if (pathname.startsWith("/.well-known/")) {
+    relativePath = pathname.slice(1);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+  } else if (
+    pathname === "/favicon.ico" ||
+    pathname === "/robots.txt" ||
+    pathname === "/sitemap.xml" ||
+    pathname === "/manifest.json"
+  ) {
+    relativePath = path.basename(pathname);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+    allowRouteFallbackOnMissing = true;
+  } else if (PUBLIC_FLAT_ASSET_EXTENSIONS.has(path.extname(pathname).toLowerCase())) {
+    relativePath = pathname.slice(1);
+    allowedBaseDir = path.join(settings.rootDir, settings.publicDir);
+    isPublicFlatFallback = true;
+  } else {
+    return { handled: false };
+  }
+
+  let decodedPath: string;
+  try {
+    decodedPath = decodeURIComponent(relativePath);
+  } catch {
+    return { handled: true, response: createStaticErrorResponse(400) };
+  }
+
+  const normalizedPath = path.posix.normalize(decodedPath);
+  if (normalizedPath.includes("\0")) {
+    console.warn(`[Mandu Security] Null byte attack detected: ${pathname}`);
+    return { handled: true, response: createStaticErrorResponse(400) };
+  }
+
+  const normalizedSegments = normalizedPath.split("/");
+  if (normalizedSegments.some((segment) => segment === "..")) {
+    return { handled: true, response: createStaticErrorResponse(403) };
+  }
+
+  const safeRelativePath = normalizedPath.replace(/^\/+/, "");
+  filePath = path.join(allowedBaseDir, safeRelativePath);
+
+  if (!(await isPathSafe(filePath, allowedBaseDir))) {
+    console.warn(`[Mandu Security] Path traversal attempt blocked: ${pathname}`);
+    return { handled: true, response: createStaticErrorResponse(403) };
+  }
+
+  try {
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      if (isPublicFlatFallback || allowRouteFallbackOnMissing) return { handled: false };
+      return { handled: true, response: createStaticErrorResponse(404) };
+    }
+
+    const mimeType = getMimeType(filePath);
+    const filename = path.basename(filePath);
+    let cacheControl: string;
+    if (settings.isDev) {
+      cacheControl = "no-cache, no-store, must-revalidate";
+    } else if (isBundleFile) {
+      cacheControl = computeStaticCacheControl(filename, false);
+    } else {
+      cacheControl = "public, max-age=86400";
+    }
+
+    const etag = isBundleFile
+      ? await computeStrongEtag(filePath, file)
+      : `W/"${file.size.toString(36)}-${file.lastModified.toString(36)}"`;
+
+    const ifNoneMatch = request?.headers.get("If-None-Match");
+    if (ifNoneMatch && matchesEtag(ifNoneMatch, etag)) {
+      return {
+        handled: true,
+        response: new Response(null, {
+          status: 304,
+          headers: { "ETag": etag, "Cache-Control": cacheControl },
+        }),
+      };
+    }
+
+    return {
+      handled: true,
+      response: new Response(file, {
+        headers: {
+          "Content-Type": mimeType,
+          "Cache-Control": cacheControl,
+          "ETag": etag,
+        },
+      }),
+    };
+  } catch {
+    return { handled: true, response: createStaticErrorResponse(500) };
+  }
+}

package/src/runtime/streaming-ssr.ts

@@ -613,13 +613,16 @@ function generateHTMLShell(options: StreamingSSROptions): string {
 }
 </style>`;
 
-  let islandOpenTag = "";
-  if (needsHydration) {
-    const bundle = bundleManifest.bundles[routeId];
-    const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
-    const priority = hydration.priority || "visible";
-    islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
-  }
+  let islandOpenTag = "";
+  const hasRouteBundle = !!(needsHydration && bundleManifest.bundles[routeId]?.js);
+  if (needsHydration) {
+    const bundle = bundleManifest.bundles[routeId];
+    const bundleSrc = bundle?.js ? `${bundle.js}?t=${Date.now()}` : "";
+    const priority = hydration.priority || "visible";
+    if (hasRouteBundle) {
+      islandOpenTag = `<div data-mandu-island="${escapeHtmlAttr(routeId)}" data-mandu-src="${escapeHtmlAttr(bundleSrc)}" data-mandu-priority="${escapeHtmlAttr(priority)}" style="display:contents">`;
+    }
+  }
 
   // Phase 7.1 R2 Agent D: Fast Refresh preamble. Must land in <head>
   // BEFORE any island script evaluates — the stubs it installs for
@@ -697,7 +700,7 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   // 1~8: hydration이 필요한 경우에만 클라이언트 JS 관련 스크립트 삽입
   if (needsHydration) {
     // 1. Critical 데이터 스크립트 (즉시 사용 가능)
-    if (criticalData && routeId) {
+    if (criticalData !== undefined && routeId) {
       const wrappedData = {
         [routeId]: {
           serverData: criticalData,
@@ -746,10 +749,16 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
 
     // 6. Island modulepreload
     const bundle = bundleManifest.bundles[routeId];
-    if (bundle) {
-      const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
-      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
-    }
+    if (bundle) {
+      const cacheBust = `${bundle.js}${bundle.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+      scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+    }
+    if (bundleManifest.partials) {
+      for (const partial of Object.values(bundleManifest.partials)) {
+        const cacheBust = `${partial.js}${partial.js.includes('?') ? '&' : '?'}v=${Date.now()}`;
+        scripts.push(`<link rel="modulepreload" href="${escapeHtmlAttr(cacheBust)}">`);
+      }
+    }
 
     // 7. Runtime 로드
     if (bundleManifest.shared.runtime) {
@@ -783,7 +792,7 @@ function generateHTMLTailContent(options: StreamingSSROptions): string {
   }
 
   // Island wrapper 닫기 (hydration이 필요한 경우)
-  const islandCloseTag = needsHydration ? "</div>" : "";
+  const islandCloseTag = needsHydration && bundleManifest.bundles[routeId]?.js ? "</div>" : "";
 
   return `${islandCloseTag}</div>
   ${scripts.join("\n  ")}`;