@mandujs/core 0.9.39 → 0.9.40

package/src/index.ts

@@ -13,10 +13,12 @@ export * from "./openapi";
 export * from "./brain";
 export * from "./watcher";
 export * from "./router";
+export * from "./config";
+export * from "./seo";
 
 // Consolidated Mandu namespace
 import { ManduFilling, ManduContext, ManduFillingFactory } from "./filling";
-import { createContract, defineHandler, defineRoute, createClient, contractFetch } from "./contract";
+import { createContract, defineHandler, defineRoute, createClient, contractFetch, createClientContract } from "./contract";
 import type { ContractDefinition, ContractInstance, ContractSchema } from "./contract";
 import type { ContractHandlers, ClientOptions } from "./contract";
 
@@ -83,6 +85,11 @@ export const Mandu = {
    */
   client: createClient,
 
+  /**
+   * Create a client-safe contract
+   */
+  clientContract: createClientContract,
+
   /**
    * Make a type-safe fetch call
    */

package/src/runtime/index.ts

@@ -1,4 +1,5 @@
 export * from "./ssr";
+export * from "./streaming-ssr";
 export * from "./router";
 export * from "./server";
 export * from "./cors";

package/src/runtime/streaming-ssr.ts

@@ -17,6 +17,8 @@ import React, { Suspense } from "react";
 import type { BundleManifest } from "../bundler/types";
 import type { HydrationConfig, HydrationPriority } from "../spec/schema";
 import { serializeProps } from "../client/serialize";
+import type { Metadata, MetadataItem } from "../seo/types";
+import { injectSEOIntoOptions, resolveSEO, type SEOOptions } from "../seo/integration/ssr";
 
 // ========== Types ==========
 
@@ -73,7 +75,7 @@ export interface StreamingMetrics {
 }
 
 export interface StreamingSSROptions {
-  /** 페이지 타이틀 */
+  /** 페이지 타이틀 (SEO metadata 사용 시 자동 설정됨) */
   title?: string;
   /** HTML lang 속성 */
   lang?: string;
@@ -88,8 +90,18 @@ export interface StreamingSSROptions {
   hydration?: HydrationConfig;
   /** 번들 매니페스트 */
   bundleManifest?: BundleManifest;
-  /** 추가 head 태그 */
+  /** 추가 head 태그 (SEO metadata와 병합됨) */
   headTags?: string;
+  /**
+   * SEO 메타데이터 (Layout 체인 또는 단일 객체)
+   * - 배열: [rootLayout, ...nestedLayouts, page] 순서로 병합
+   * - 객체: 단일 정적 메타데이터
+   */
+  metadata?: MetadataItem[] | Metadata;
+  /** 라우트 파라미터 (동적 메타데이터용) */
+  routeParams?: Record<string, string>;
+  /** 쿼리 파라미터 (동적 메타데이터용) */
+  searchParams?: Record<string, string>;
   /** 개발 모드 여부 */
   isDev?: boolean;
   /** HMR 포트 */
@@ -1102,6 +1114,111 @@ export function defer<T>(promise: Promise<T>): Promise<T> {
   return promise;
 }
 
+// ========== SEO Integration ==========
+
+/**
+ * SEO 메타데이터와 함께 Streaming SSR 렌더링
+ *
+ * Layout 체인에서 메타데이터를 자동으로 수집하고 병합하여
+ * HTML head에 삽입합니다.
+ *
+ * @example
+ * ```typescript
+ * // 정적 메타데이터
+ * const response = await renderWithSEO(<Page />, {
+ *   metadata: {
+ *     title: 'Home',
+ *     description: 'Welcome to my site',
+ *     openGraph: { type: 'website' },
+ *   },
+ * })
+ *
+ * // Layout 체인 메타데이터
+ * const response = await renderWithSEO(<Page />, {
+ *   metadata: [
+ *     layoutMetadata,  // { title: { template: '%s | Site' } }
+ *     pageMetadata,    // { title: 'Blog Post' }
+ *   ],
+ *   routeParams: { slug: 'hello' },
+ * })
+ * // → title: "Blog Post | Site"
+ * ```
+ */
+export async function renderWithSEO(
+  element: ReactElement,
+  options: StreamingSSROptions = {}
+): Promise<Response> {
+  const { metadata, routeParams, searchParams, ...restOptions } = options;
+
+  // SEO 메타데이터 처리
+  if (metadata) {
+    const seoOptions: SEOOptions = {
+      routeParams,
+      searchParams,
+    };
+
+    // 배열이면 Layout 체인, 아니면 단일 메타데이터
+    if (Array.isArray(metadata)) {
+      seoOptions.metadata = metadata;
+    } else {
+      seoOptions.staticMetadata = metadata as Metadata;
+    }
+
+    // SEO를 옵션에 주입
+    const optionsWithSEO = await injectSEOIntoOptions(restOptions, seoOptions);
+    return renderStreamingResponse(element, optionsWithSEO);
+  }
+
+  // SEO 없이 기본 렌더링
+  return renderStreamingResponse(element, restOptions);
+}
+
+/**
+ * Deferred 데이터 + SEO 메타데이터와 함께 Streaming SSR 렌더링
+ *
+ * @example
+ * ```typescript
+ * const response = await renderWithDeferredDataAndSEO(<Page />, {
+ *   metadata: {
+ *     title: post.title,
+ *     openGraph: { images: [post.image] },
+ *   },
+ *   deferredPromises: {
+ *     comments: fetchComments(postId),
+ *     related: fetchRelatedPosts(postId),
+ *   },
+ * })
+ * ```
+ */
+export async function renderWithDeferredDataAndSEO(
+  element: ReactElement,
+  options: StreamingSSROptions & {
+    deferredPromises?: Record<string, Promise<unknown>>;
+    deferredTimeout?: number;
+  } = {}
+): Promise<Response> {
+  const { metadata, routeParams, searchParams, ...restOptions } = options;
+
+  // SEO 메타데이터 처리
+  if (metadata) {
+    const seoOptions: SEOOptions = {
+      routeParams,
+      searchParams,
+    };
+
+    if (Array.isArray(metadata)) {
+      seoOptions.metadata = metadata;
+    } else {
+      seoOptions.staticMetadata = metadata as Metadata;
+    }
+
+    const optionsWithSEO = await injectSEOIntoOptions(restOptions, seoOptions);
+    return renderWithDeferredData(element, optionsWithSEO);
+  }
+
+  return renderWithDeferredData(element, restOptions);
+}
+
 // ========== Exports ==========
 
 export {
@@ -1109,3 +1226,7 @@ export {
   generateHTMLTail,
   generateDeferredDataScript,
 };
+
+// Re-export SEO integration utilities
+export { resolveSEO, injectSEOIntoOptions } from "../seo/integration/ssr";
+export type { SEOOptions, SEOResult } from "../seo/integration/ssr";

package/src/seo/index.ts

@@ -0,0 +1,214 @@
+/**
+ * Mandu SEO Module
+ *
+ * Next.js Metadata API 패턴 기반의 SEO 지원
+ *
+ * @example
+ * ```typescript
+ * // app/layout.tsx - 정적 메타데이터
+ * import type { Metadata } from '@mandujs/core'
+ *
+ * export const metadata: Metadata = {
+ *   metadataBase: new URL('https://example.com'),
+ *   title: {
+ *     template: '%s | My Site',
+ *     default: 'My Site',
+ *   },
+ *   description: 'Welcome to my site',
+ *   openGraph: {
+ *     siteName: 'My Site',
+ *     type: 'website',
+ *   },
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app/blog/[slug]/page.tsx - 동적 메타데이터
+ * import type { Metadata, MetadataParams } from '@mandujs/core'
+ *
+ * export async function generateMetadata({ params }: MetadataParams): Promise<Metadata> {
+ *   const post = await getPost(params.slug)
+ *   return {
+ *     title: post.title,
+ *     description: post.excerpt,
+ *     openGraph: {
+ *       title: post.title,
+ *       images: [post.coverImage],
+ *     },
+ *   }
+ * }
+ * ```
+ */
+
+// Types
+export type {
+  // Main types
+  Metadata,
+  ResolvedMetadata,
+  MetadataItem,
+  MetadataParams,
+  GenerateMetadata,
+
+  // Title types
+  Title,
+  TemplateString,
+  AbsoluteString,
+  AbsoluteTemplateString,
+
+  // Basic types
+  Author,
+  ReferrerEnum,
+  ColorSchemeEnum,
+  Robots,
+  ResolvedRobots,
+
+  // Icons
+  Icon,
+  IconURL,
+  IconDescriptor,
+  Icons,
+  ResolvedIcons,
+
+  // Alternates
+  AlternateURLs,
+  ResolvedAlternateURLs,
+  Languages,
+
+  // Verification
+  Verification,
+  ResolvedVerification,
+
+  // Open Graph
+  OpenGraph,
+  OpenGraphType,
+  OpenGraphImage,
+  OpenGraphVideo,
+  OpenGraphAudio,
+  OpenGraphArticle,
+  OpenGraphProfile,
+  OpenGraphBook,
+  ResolvedOpenGraph,
+
+  // Twitter
+  Twitter,
+  TwitterCardType,
+  TwitterImage,
+  TwitterPlayer,
+  TwitterApp,
+  ResolvedTwitter,
+
+  // JSON-LD
+  JsonLd,
+  JsonLdType,
+
+  // Google SEO 최적화
+  GoogleMeta,
+  FormatDetection,
+  ResourceHint,
+  AppLinks,
+  ThemeColor,
+
+  // Metadata Routes
+  Sitemap,
+  SitemapEntry,
+  RobotsFile,
+  RobotsRule,
+  MetadataRoute,
+} from './types'
+
+// Resolve functions
+export {
+  resolveMetadata,
+  mergeMetadata,
+  createDefaultMetadata,
+  resolveTitle,
+  extractTitleTemplate,
+  normalizeMetadataBase,
+  resolveUrl,
+  urlToString,
+  resolveRobots,
+  resolveOpenGraph,
+  resolveTwitter,
+} from './resolve'
+
+// Render functions
+export {
+  renderMetadata,
+  renderTitle,
+  renderBasicMeta,
+  renderVerification,
+  renderAlternates,
+  renderIcons,
+  renderManifest,
+  renderOther,
+  renderOpenGraph,
+  renderTwitter,
+  renderJsonLd,
+  // JSON-LD helpers
+  createArticleJsonLd,
+  createWebSiteJsonLd,
+  createOrganizationJsonLd,
+  createBreadcrumbJsonLd,
+  createFAQJsonLd,
+  createProductJsonLd,
+  createLocalBusinessJsonLd,
+  createVideoJsonLd,
+  createReviewJsonLd,
+  createCourseJsonLd,
+  createEventJsonLd,
+  createSoftwareAppJsonLd,
+  // Google SEO 최적화 렌더링
+  renderGoogle,
+  renderFormatDetection,
+  renderThemeColor,
+  renderViewport,
+  renderResourceHints,
+  renderAppLinks,
+  // Metadata Routes rendering
+  renderSitemap,
+  renderSitemapIndex,
+  renderRobots,
+  createDefaultRobots,
+  createDevRobots,
+} from './render'
+
+// Metadata Routes (sitemap.ts, robots.ts)
+export {
+  createSitemapHandler,
+  createRobotsHandler,
+  createSitemapIndexHandler,
+  buildMetadataRoutes,
+  getMetadataRouteType,
+  createMetadataRouteInfo,
+  createDynamicSitemapRouteInfo,
+  METADATA_ROUTE_PATTERNS,
+} from './routes'
+
+export type {
+  SitemapFunction,
+  RobotsFunction,
+  MetadataRouteModule,
+  MetadataRouteHandler,
+  MetadataRouteConfig,
+  DiscoveredRoutes,
+  MetadataRouteDefinition,
+} from './routes'
+
+// SSR Integration
+export {
+  resolveSEO,
+  resolveSEOSync,
+  injectSEOIntoOptions,
+  layoutEntriesToMetadataItems,
+  metadataToProps,
+  generateHeadUpdateScript,
+} from './integration/ssr'
+
+export type {
+  SEOOptions,
+  SEOResult,
+  LayoutMetadataEntry,
+  SEOContextValue,
+  StreamingSSRWithSEOOptions,
+} from './integration/ssr'

package/src/seo/integration/ssr.ts

@@ -0,0 +1,307 @@
+/**
+ * Mandu SEO - SSR Integration
+ *
+ * Streaming SSR 파이프라인에 SEO 메타데이터 통합
+ *
+ * @example
+ * ```typescript
+ * // app/blog/[slug]/page.tsx
+ * import { renderWithSEO } from '@mandujs/core'
+ *
+ * export default async function handler(req: Request) {
+ *   const slug = getSlug(req)
+ *   const post = await getPost(slug)
+ *
+ *   return renderWithSEO(<BlogPost post={post} />, {
+ *     metadata: [
+ *       layoutMetadata,  // from layout.tsx
+ *       {
+ *         title: post.title,
+ *         description: post.excerpt,
+ *         openGraph: { title: post.title, images: [post.image] },
+ *       },
+ *     ],
+ *     routeParams: { slug },
+ *   })
+ * }
+ * ```
+ */
+
+import type { ReactElement } from 'react'
+import type { Metadata, MetadataItem, ResolvedMetadata } from '../types'
+import { resolveMetadata, createDefaultMetadata } from '../resolve'
+import { renderMetadata } from '../render'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface SEOOptions {
+  /**
+   * 메타데이터 항목들 (Layout 체인 순서)
+   * [rootLayout, ...nestedLayouts, page]
+   */
+  metadata?: MetadataItem[]
+
+  /**
+   * 단일 정적 메타데이터 (간단한 경우)
+   */
+  staticMetadata?: Metadata
+
+  /**
+   * 라우트 파라미터 (동적 메타데이터용)
+   */
+  routeParams?: Record<string, string>
+
+  /**
+   * 쿼리 파라미터 (동적 메타데이터용)
+   */
+  searchParams?: Record<string, string>
+}
+
+export interface SEOResult {
+  /** 해석된 메타데이터 */
+  resolved: ResolvedMetadata
+  /** 렌더링된 HTML 문자열 (<head> 내부) */
+  html: string
+  /** 페이지 타이틀 */
+  title: string | null
+}
+
+// ============================================================================
+// SEO Resolution
+// ============================================================================
+
+/**
+ * SEO 메타데이터 해석 및 렌더링
+ *
+ * @param options - SEO 옵션
+ * @returns 해석된 메타데이터와 HTML
+ */
+export async function resolveSEO(options: SEOOptions = {}): Promise<SEOResult> {
+  const { metadata, staticMetadata, routeParams = {}, searchParams = {} } = options
+
+  let resolved: ResolvedMetadata
+
+  if (metadata && metadata.length > 0) {
+    // Layout 체인에서 메타데이터 해석
+    resolved = await resolveMetadata(metadata, routeParams, searchParams)
+  } else if (staticMetadata) {
+    // 단일 정적 메타데이터
+    const base = createDefaultMetadata()
+    resolved = await resolveMetadata([staticMetadata], routeParams, searchParams)
+  } else {
+    // 기본 메타데이터
+    resolved = createDefaultMetadata()
+  }
+
+  // HTML 렌더링
+  const html = renderMetadata(resolved)
+  const title = resolved.title?.absolute || null
+
+  return { resolved, html, title }
+}
+
+/**
+ * 동기 버전 (정적 메타데이터 전용)
+ *
+ * 주의: 동기 버전은 간단한 메타데이터만 처리합니다.
+ * 복잡한 메타데이터(OG, Twitter 등)는 resolveSEO를 사용하세요.
+ */
+export function resolveSEOSync(staticMetadata: Metadata): SEOResult {
+  const base = createDefaultMetadata()
+
+  // title 해석
+  let resolvedTitle: { absolute: string; template: string | null } | null = null
+  if (staticMetadata.title) {
+    if (typeof staticMetadata.title === 'string') {
+      resolvedTitle = { absolute: staticMetadata.title, template: null }
+    } else if ('absolute' in staticMetadata.title) {
+      resolvedTitle = {
+        absolute: staticMetadata.title.absolute,
+        template: staticMetadata.title.template || null,
+      }
+    } else if ('default' in staticMetadata.title) {
+      resolvedTitle = {
+        absolute: staticMetadata.title.default,
+        template: staticMetadata.title.template || null,
+      }
+    }
+  }
+
+  // 간단한 병합 (동기)
+  const resolved: ResolvedMetadata = {
+    ...base,
+    title: resolvedTitle,
+    description: staticMetadata.description || null,
+    keywords: staticMetadata.keywords
+      ? typeof staticMetadata.keywords === 'string'
+        ? staticMetadata.keywords.split(',').map(k => k.trim())
+        : staticMetadata.keywords
+      : null,
+    robots: staticMetadata.robots
+      ? typeof staticMetadata.robots === 'string'
+        ? { basic: staticMetadata.robots, googleBot: null }
+        : {
+            basic: [
+              staticMetadata.robots.index === false ? 'noindex' : 'index',
+              staticMetadata.robots.follow === false ? 'nofollow' : 'follow',
+            ].join(', '),
+            googleBot: null,
+          }
+      : null,
+  }
+
+  const html = renderMetadata(resolved)
+  const title = resolved.title?.absolute || null
+
+  return { resolved, html, title }
+}
+
+// ============================================================================
+// Streaming SSR Integration
+// ============================================================================
+
+/**
+ * StreamingSSROptions에 추가할 SEO 확장 옵션
+ */
+export interface StreamingSSRWithSEOOptions {
+  /** SEO 옵션 */
+  seo?: SEOOptions
+}
+
+/**
+ * Streaming SSR 옵션에 SEO headTags 주입
+ *
+ * @example
+ * ```typescript
+ * const baseOptions = { routeId: 'blog-post', isDev: true }
+ * const seoOptions = { metadata: [layoutMeta, pageMeta] }
+ *
+ * const options = await injectSEOIntoOptions(baseOptions, seoOptions)
+ * // → { ...baseOptions, title: 'Post Title', headTags: '<meta ...>' }
+ * ```
+ */
+export async function injectSEOIntoOptions<T extends { title?: string; headTags?: string }>(
+  options: T,
+  seoOptions: SEOOptions
+): Promise<T & { title: string; headTags: string }> {
+  const { resolved, html, title } = await resolveSEO(seoOptions)
+
+  // 기존 headTags와 병합
+  const existingHeadTags = options.headTags || ''
+  const mergedHeadTags = html + (existingHeadTags ? '\n' + existingHeadTags : '')
+
+  return {
+    ...options,
+    title: title || options.title || 'Mandu App',
+    headTags: mergedHeadTags,
+  }
+}
+
+// ============================================================================
+// Layout Chain Helpers
+// ============================================================================
+
+/**
+ * 레이아웃 체인에서 메타데이터 수집
+ *
+ * @example
+ * ```typescript
+ * // 파일 시스템 기반 라우팅에서 사용
+ * const chain = await collectLayoutMetadata([
+ *   { path: 'app/layout.tsx', metadata: rootMeta },
+ *   { path: 'app/blog/layout.tsx', metadata: blogMeta },
+ *   { path: 'app/blog/[slug]/page.tsx', generateMetadata: generatePostMeta },
+ * ])
+ * ```
+ */
+export interface LayoutMetadataEntry {
+  /** 레이아웃/페이지 경로 */
+  path: string
+  /** 정적 메타데이터 */
+  metadata?: Metadata
+  /** 동적 메타데이터 생성 함수 */
+  generateMetadata?: (props: {
+    params: Record<string, string>
+    searchParams: Record<string, string>
+  }) => Metadata | Promise<Metadata>
+}
+
+/**
+ * 레이아웃 엔트리를 MetadataItem 배열로 변환
+ */
+export function layoutEntriesToMetadataItems(
+  entries: LayoutMetadataEntry[]
+): MetadataItem[] {
+  return entries.map((entry) => {
+    if (entry.generateMetadata) {
+      return entry.generateMetadata
+    }
+    return entry.metadata || null
+  })
+}
+
+// ============================================================================
+// React Component Integration
+// ============================================================================
+
+/**
+ * SEO Context 타입 (React Context 사용 시)
+ */
+export interface SEOContextValue {
+  metadata: ResolvedMetadata
+  updateMetadata: (partial: Partial<Metadata>) => void
+}
+
+/**
+ * 메타데이터를 React 컴포넌트에서 사용할 수 있는 props로 변환
+ */
+export function metadataToProps(resolved: ResolvedMetadata): {
+  title: string | null
+  description: string | null
+  ogImage: string | null
+  ogUrl: string | null
+} {
+  return {
+    title: resolved.title?.absolute || null,
+    description: resolved.description || null,
+    ogImage: resolved.openGraph?.images?.[0]?.url
+      ? typeof resolved.openGraph.images[0].url === 'string'
+        ? resolved.openGraph.images[0].url
+        : resolved.openGraph.images[0].url.toString()
+      : null,
+    ogUrl: resolved.openGraph?.url?.href || null,
+  }
+}
+
+// ============================================================================
+// Head Component Support
+// ============================================================================
+
+/**
+ * 동적 Head 업데이트를 위한 스크립트 생성
+ * (클라이언트에서 document.title 등 업데이트)
+ */
+export function generateHeadUpdateScript(metadata: ResolvedMetadata): string {
+  const updates: string[] = []
+
+  // Title 업데이트
+  if (metadata.title?.absolute) {
+    updates.push(`document.title = ${JSON.stringify(metadata.title.absolute)};`)
+  }
+
+  // Description 업데이트
+  if (metadata.description) {
+    updates.push(`
+      (function() {
+        var meta = document.querySelector('meta[name="description"]');
+        if (meta) meta.content = ${JSON.stringify(metadata.description)};
+      })();
+    `)
+  }
+
+  if (updates.length === 0) return ''
+
+  return `<script>(function(){${updates.join('')}})()</script>`
+}