npm - @mandujs/core - Versions diffs - 0.12.1 → 0.13.0 - Mend

@mandujs/core 0.12.1 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (177) hide show

package/README.ko.md +304 -304
package/README.md +653 -653
package/package.json +8 -8
package/src/brain/architecture/analyzer.ts +28 -26
package/src/brain/doctor/analyzer.ts +1 -1
package/src/bundler/build.ts +91 -91
package/src/bundler/css.ts +302 -302
package/src/bundler/dev.ts +0 -1
package/src/change/history.ts +3 -3
package/src/change/snapshot.ts +10 -9
package/src/change/transaction.ts +2 -2
package/src/client/Link.tsx +227 -227
package/src/client/globals.ts +44 -44
package/src/client/hooks.ts +267 -267
package/src/client/index.ts +5 -5
package/src/client/island.ts +8 -8
package/src/client/router.ts +435 -435
package/src/client/runtime.ts +23 -23
package/src/client/serialize.ts +404 -404
package/src/client/window-state.ts +101 -101
package/src/config/mandu.ts +94 -96
package/src/config/validate.ts +213 -215
package/src/config/watcher.ts +311 -311
package/src/constants.ts +40 -40
package/src/content/content-layer.ts +314 -314
package/src/content/content.test.ts +433 -433
package/src/content/data-store.ts +245 -245
package/src/content/digest.ts +133 -133
package/src/content/index.ts +164 -164
package/src/content/loader-context.ts +172 -172
package/src/content/loaders/api.ts +216 -216
package/src/content/loaders/file.ts +169 -169
package/src/content/loaders/glob.ts +252 -252
package/src/content/loaders/index.ts +34 -34
package/src/content/loaders/types.ts +137 -137
package/src/content/meta-store.ts +209 -209
package/src/content/types.ts +282 -282
package/src/content/watcher.ts +135 -135
package/src/contract/client-safe.test.ts +42 -42
package/src/contract/client-safe.ts +114 -114
package/src/contract/client.ts +16 -16
package/src/contract/define.ts +459 -459
package/src/contract/handler.ts +10 -10
package/src/contract/normalize.test.ts +276 -276
package/src/contract/normalize.ts +404 -404
package/src/contract/registry.test.ts +206 -206
package/src/contract/registry.ts +568 -568
package/src/contract/schema.ts +48 -48
package/src/contract/types.ts +58 -58
package/src/contract/validator.ts +32 -32
package/src/devtools/ai/context-builder.ts +375 -375
package/src/devtools/ai/index.ts +25 -25
package/src/devtools/ai/mcp-connector.ts +465 -465
package/src/devtools/client/catchers/error-catcher.ts +327 -327
package/src/devtools/client/catchers/index.ts +18 -18
package/src/devtools/client/catchers/network-proxy.ts +363 -363
package/src/devtools/client/components/index.ts +39 -39
package/src/devtools/client/components/kitchen-root.tsx +362 -362
package/src/devtools/client/components/mandu-character.tsx +241 -241
package/src/devtools/client/components/overlay.tsx +368 -368
package/src/devtools/client/components/panel/errors-panel.tsx +259 -259
package/src/devtools/client/components/panel/guard-panel.tsx +244 -244
package/src/devtools/client/components/panel/index.ts +32 -32
package/src/devtools/client/components/panel/islands-panel.tsx +304 -304
package/src/devtools/client/components/panel/network-panel.tsx +292 -292
package/src/devtools/client/components/panel/panel-container.tsx +259 -259
package/src/devtools/client/filters/context-filters.ts +282 -282
package/src/devtools/client/filters/index.ts +16 -16
package/src/devtools/client/index.ts +63 -63
package/src/devtools/client/persistence.ts +335 -335
package/src/devtools/client/state-manager.ts +478 -478
package/src/devtools/design-tokens.ts +263 -263
package/src/devtools/hook/create-hook.ts +207 -207
package/src/devtools/hook/index.ts +13 -13
package/src/devtools/index.ts +439 -439
package/src/devtools/init.ts +266 -266
package/src/devtools/protocol.ts +237 -237
package/src/devtools/server/index.ts +17 -17
package/src/devtools/server/source-context.ts +444 -444
package/src/devtools/types.ts +319 -319
package/src/devtools/worker/index.ts +25 -25
package/src/devtools/worker/redaction-worker.ts +222 -222
package/src/devtools/worker/worker-manager.ts +409 -409
package/src/error/classifier.ts +2 -2
package/src/error/domains.ts +265 -265
package/src/error/formatter.ts +32 -32
package/src/error/result.ts +46 -46
package/src/error/stack-analyzer.ts +5 -0
package/src/error/types.ts +6 -6
package/src/errors/extractor.ts +409 -409
package/src/errors/index.ts +19 -19
package/src/filling/auth.ts +308 -308
package/src/filling/context.ts +569 -569
package/src/filling/deps.ts +238 -238
package/src/generator/contract-glue.ts +2 -1
package/src/generator/generate.ts +12 -10
package/src/generator/index.ts +3 -3
package/src/generator/templates.ts +80 -79
package/src/guard/analyzer.ts +360 -360
package/src/guard/ast-analyzer.ts +806 -806
package/src/guard/auto-correct.ts +1 -1
package/src/guard/check.ts +128 -128
package/src/guard/contract-guard.ts +9 -9
package/src/guard/file-type.test.ts +24 -24
package/src/guard/healing.ts +2 -0
package/src/guard/index.ts +2 -0
package/src/guard/negotiation.ts +430 -4
package/src/guard/presets/atomic.ts +70 -70
package/src/guard/presets/clean.ts +77 -77
package/src/guard/presets/cqrs.test.ts +175 -0
package/src/guard/presets/cqrs.ts +107 -0
package/src/guard/presets/fsd.ts +79 -79
package/src/guard/presets/hexagonal.ts +68 -68
package/src/guard/presets/index.ts +291 -288
package/src/guard/reporter.ts +445 -445
package/src/guard/rules.ts +12 -12
package/src/guard/statistics.ts +578 -578
package/src/guard/suggestions.ts +358 -352
package/src/guard/types.ts +348 -347
package/src/guard/validator.ts +834 -834
package/src/guard/watcher.ts +404 -404
package/src/index.ts +1 -0
package/src/intent/index.ts +310 -310
package/src/island/index.ts +304 -304
package/src/logging/index.ts +22 -22
package/src/logging/transports.ts +365 -365
package/src/paths.test.ts +47 -0
package/src/paths.ts +47 -0
package/src/plugins/index.ts +38 -38
package/src/plugins/registry.ts +377 -377
package/src/plugins/types.ts +363 -363
package/src/report/build.ts +1 -1
package/src/report/index.ts +1 -1
package/src/router/fs-patterns.ts +387 -387
package/src/router/fs-routes.ts +344 -401
package/src/router/fs-scanner.ts +497 -497
package/src/router/fs-types.ts +270 -278
package/src/router/index.ts +81 -81
package/src/runtime/boundary.tsx +232 -232
package/src/runtime/compose.ts +222 -222
package/src/runtime/lifecycle.ts +381 -381
package/src/runtime/logger.test.ts +345 -345
package/src/runtime/logger.ts +677 -677
package/src/runtime/router.test.ts +476 -476
package/src/runtime/router.ts +105 -105
package/src/runtime/security.ts +155 -155
package/src/runtime/server.ts +24 -24
package/src/runtime/session-key.ts +328 -328
package/src/runtime/ssr.ts +367 -367
package/src/runtime/streaming-ssr.ts +1245 -1245
package/src/runtime/trace.ts +144 -144
package/src/seo/index.ts +214 -214
package/src/seo/integration/ssr.ts +307 -307
package/src/seo/render/basic.ts +427 -427
package/src/seo/render/index.ts +143 -143
package/src/seo/render/jsonld.ts +539 -539
package/src/seo/render/opengraph.ts +191 -191
package/src/seo/render/robots.ts +116 -116
package/src/seo/render/sitemap.ts +137 -137
package/src/seo/render/twitter.ts +126 -126
package/src/seo/resolve/index.ts +353 -353
package/src/seo/resolve/opengraph.ts +143 -143
package/src/seo/resolve/robots.ts +73 -73
package/src/seo/resolve/title.ts +94 -94
package/src/seo/resolve/twitter.ts +73 -73
package/src/seo/resolve/url.ts +97 -97
package/src/seo/routes/index.ts +290 -290
package/src/seo/types.ts +575 -575
package/src/slot/validator.ts +39 -39
package/src/spec/index.ts +3 -3
package/src/spec/load.ts +76 -76
package/src/spec/lock.ts +56 -56
package/src/utils/bun.ts +8 -8
package/src/utils/lru-cache.ts +75 -75
package/src/utils/safe-io.ts +188 -188
package/src/utils/string-safe.ts +298 -298
package/src/watcher/rules.ts +5 -5

package/src/seo/integration/ssr.ts CHANGED Viewed

@@ -1,307 +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>`
-}
+/**
+ * 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>`
+}