@roottale/cms-renderer-next 0.53.1 → 0.56.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @roottale/cms-renderer-next
 
+## 0.56.0
+
+### Minor Changes
+
+- 422c388: ADR-0105 Amendment 1 — FRONT 가 글 주소를 다시 계산하지 않습니다. `RootTaleBlogList`·
+  `RootTaleBlogPost`(연관 글·빵부스러기)의 기본 글 링크와 `buildPostMetadata` 의 canonical 이
+  플랫폼이 저장한 정규 공개 경로 `post.path` 를 먼저 읽고, 없을 때만 종전처럼 `collections`
+  규칙 → `/blog/{slug}` 로 폴백합니다. `storedPostPath(post)` 헬퍼를 `routes` 에서 내보냅니다.
+  문서(seo·collections·blog)와 Next.js 예제가 같은 규칙으로 갱신됐습니다.
+- 41740c3: ADR-0105 Amendment 1 — 사이트맵·RSS·llms.txt 의 글 URL 이 공개 API 가 내려주는 저장된 정규
+  공개 경로(`post.path`)를 먼저 쓰고, 없으면 종전처럼 컬렉션 규칙·`blogBasePath` 로 계산합니다.
+  어느 유형에도 속하지 않는 레거시 글은 종전대로 사이트 설정을 따릅니다.
+- 86c5712: RootTale 표준 블로그 주소 `/blog/{category}/{slug}` 지원 — `RootTaleSiteConfig.categoryPath`
+  (`"direct"` 면 사이트맵 카테고리 허브가 `/blog/{category}`), collection 모드 사이트맵이 각 컬렉션의
+  `categoryPath` 를 따르며, `makeCategoryHref(basePath, categoryPath)` 를 `server`·`routes` 에서
+  내보냅니다. 문서에 표준 규칙과 라우트 배치를 적었습니다.
+
+### Patch Changes
+
+- Updated dependencies [18aaa9e]
+- Updated dependencies [9eb39e8]
+- Updated dependencies [d303835]
+  - @roottale/cms-client@0.56.0
+  - @roottale/cms-core@0.56.0
+
+## 0.55.0
+
+### Patch Changes
+
+- Updated dependencies [6cb9dd5]
+  - @roottale/cms-client@0.55.0
+  - @roottale/cms-core@0.55.0
+
+## 0.54.0
+
+### Minor Changes
+
+- ad805bd: 글 미리보기를 고객 사이트가 자기 글 템플릿으로 그릴 수 있게 합니다 — 관리자
+  미리보기와 발행 결과가 다르던 문제의 해법.
+  - 공개 API `GET /v1/cms/public/posts/preview?token=`: 관리자 편집기가 발급한
+    1시간짜리 토큰으로 초안(미발행 포함)을 발행 글과 같은 형식으로 돌려줍니다.
+    없는 토큰 404, 만료 410 `preview_expired`, 응답 `cache-control: no-store`.
+  - `@roottale/cms-client/server`: `fetchPostPreview({ apiKey, token })`,
+    `isPreviewExpiredError`, `CmsPostPreviewContent`.
+  - `@roottale/cms-renderer-next`: `RootTaleBlogPost`에 `previewToken`·
+    `previewExpiredElement`(같은 템플릿으로 미리보기), `RootTalePreviewNotice`,
+    `buildPreviewMetadata`(항상 noindex/nofollow).
+  - 문서 `blog.md` "미리보기 페이지"·`api-reference.md`, 예시
+    `examples/nextjs/app/preview/post/[id]/page.tsx`.
+
+### Patch Changes
+
+- 2a7c695: 카테고리 대표 이미지와 검색 문구를 공개 API에서 읽어 카테고리 모음 페이지의
+  검색·공유 메타데이터에 사용할 수 있게 합니다.
+- Updated dependencies [befa5bb]
+- Updated dependencies [ad805bd]
+- Updated dependencies [2a7c695]
+  - @roottale/cms-core@0.54.0
+  - @roottale/cms-client@0.54.0
+
 ## 0.53.1
 
 ### Patch Changes

package/dist/{blog-filter-BKCGM0qd.d.ts → blog-filter-qE9Lj49C.d.ts}

@@ -14,6 +14,11 @@ interface BlogCategory {
 }
 interface BlogCategoryWithCount extends BlogCategory {
     count: number;
+    description?: string;
+    seoTitle?: string;
+    seoDescription?: string;
+    imageUrl?: string;
+    imageAlt?: string;
 }
 /**
  * 글 목록에 등장하는 카테고리를 slug 기준 unique 로 수집. 서버가 보내는 정렬
@@ -25,5 +30,11 @@ declare function collectCategoriesWithCounts(posts: CmsPostContent[]): BlogCateg
 declare function filterPostsByCategory(posts: CmsPostContent[], activeSlug: string | null | undefined): CmsPostContent[];
 /** 기본 카테고리 링크: 전체 → `/blog`, 특정 → `/blog/categories/<slug>`. */
 declare function defaultCategoryHref(slug: string | null): string;
+/**
+ * 카테고리 링크 함수 — 목록·카테고리 허브·빵부스러기의 `categoryHref` 로 넘긴다.
+ * `"direct"` 는 RootTale 표준(`/blog/{category}` 허브, 글은 `/blog/{category}/{slug}`),
+ * `"namespaced"` 는 종전 `/blog/categories/{slug}`. 전체(`null`)는 언제나 목록.
+ */
+declare function makeCategoryHref(basePath: string, categoryPath: "namespaced" | "direct"): (slug: string | null) => string;
 
-export { type BlogCategoryWithCount as B, type BlogCategory as a, collectCategoriesWithCounts as b, collectCategories as c, defaultCategoryHref as d, filterPostsByCategory as f };
+export { type BlogCategoryWithCount as B, type BlogCategory as a, collectCategoriesWithCounts as b, collectCategories as c, defaultCategoryHref as d, filterPostsByCategory as f, makeCategoryHref as m };

package/dist/{chunk-HM5VP7SR.js → chunk-GDP2VGJR.js}

@@ -41,7 +41,16 @@ function filterPostsByCategory(posts, activeSlug) {
   return posts.filter((p) => categoryTerms(p).some((t) => t.slug === activeSlug));
 }
 function defaultCategoryHref(slug) {
-  return slug ? `/blog/categories/${encodeURIComponent(slug)}` : "/blog";
+  return makeCategoryHref("/blog", "namespaced")(slug);
+}
+function makeCategoryHref(basePath, categoryPath) {
+  const base = basePath.replace(/\/+$/, "") || "";
+  const list = base || "/";
+  return (slug) => {
+    if (!slug) return list;
+    const encoded = encodeURIComponent(slug);
+    return categoryPath === "direct" ? `${base}/${encoded}` : `${base}/categories/${encoded}`;
+  };
 }
 function collectCollectionCategories(posts, collections, key) {
   const owned = postsForCollection(posts, collections, key);
@@ -50,9 +59,29 @@ function collectCollectionCategories(posts, collections, key) {
   return collectCategoriesWithCounts(owned).filter((c) => allowed.has(c.slug));
 }
 
+// src/post-public-url.ts
+import { resolvePostUrl as resolvePostUrl2 } from "@roottale/cms-core";
+function trimSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function storedPostPath(post) {
+  if (typeof post.path !== "string" || !post.path.startsWith("/")) return null;
+  if (!post.collectionKey && !post.modelKey) return null;
+  return post.path;
+}
+function postPublicUrl(post, options) {
+  const siteUrl = trimSlash(options.siteUrl);
+  const stored = storedPostPath(post);
+  if (stored) return `${siteUrl}${stored}`;
+  if (options.inCollectionMode) {
+    return resolvePostUrl2(siteUrl, post, options.collections);
+  }
+  return `${siteUrl}${trimSlash(options.blogBasePath)}/${post.slug}`;
+}
+
 // src/routes-shared.ts
 import { fetchPosts } from "@roottale/cms-client/server";
-import { resolvePostCollection as resolvePostCollection2, resolvePostUrl as resolvePostUrl2 } from "@roottale/cms-core";
+import { resolvePostCollection as resolvePostCollection2, resolvePostUrl as resolvePostUrl3 } from "@roottale/cms-core";
 async function resolveCollectionsResult(input) {
   if (typeof input === "function") {
     try {
@@ -70,7 +99,7 @@ async function resolveCollectionsResult(input) {
 async function resolveCollections(input) {
   return (await resolveCollectionsResult(input)).collections;
 }
-function trimSlash(u) {
+function trimSlash2(u) {
   return u.replace(/\/+$/, "");
 }
 async function safeFetchPosts(config, limit) {
@@ -93,12 +122,15 @@ export {
   collectCategoriesWithCounts,
   filterPostsByCategory,
   defaultCategoryHref,
+  makeCategoryHref,
   collectCollectionCategories,
+  storedPostPath,
+  postPublicUrl,
   resolveCollectionsResult,
   resolveCollections,
-  trimSlash,
+  trimSlash2 as trimSlash,
   safeFetchPosts,
   resolvePostCollection2 as resolvePostCollection,
-  resolvePostUrl2 as resolvePostUrl
+  resolvePostUrl3 as resolvePostUrl
 };
-//# sourceMappingURL=chunk-HM5VP7SR.js.map
+//# sourceMappingURL=chunk-GDP2VGJR.js.map

package/dist/chunk-GDP2VGJR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/blog-filter.ts","../src/post-public-url.ts","../src/routes-shared.ts"],"sourcesContent":["/**\n * `RootTaleBlogList` 카테고리 필터 — 순수 헬퍼(서버 필터, client JS 불요).\n *\n * SSR-only 정책 유지: 필터는 `?category=<slug>` URL 파라미터로 동작하고(칩 =\n * 서버 렌더 `<a>` 링크), consumer 가 searchParams 의 category 를 `activeCategory`\n * 로 주입한다. hydration 없이 SEO 친화 + 공유 가능한 URL.\n */\n\nimport type { CmsPostContent, CmsTermRef } from \"@roottale/cms-client/server\";\n\nexport interface BlogCategory {\n  name: string;\n  slug: string;\n}\n\nexport interface BlogCategoryWithCount extends BlogCategory {\n  count: number;\n  description?: string;\n  seoTitle?: string;\n  seoDescription?: string;\n  imageUrl?: string;\n  imageAlt?: string;\n}\n\nfunction categoryTerms(post: CmsPostContent): CmsTermRef[] {\n  return (post.terms ?? []).filter((t) => t.taxonomy === \"category\");\n}\n\n/**\n * 글 목록에 등장하는 카테고리를 slug 기준 unique 로 수집. 서버가 보내는 정렬\n * (category → name asc)을 보존하기 위해 처음 등장 순서를 유지한다.\n */\nexport function collectCategories(posts: CmsPostContent[]): BlogCategory[] {\n  return collectCategoriesWithCounts(posts).map(({ name, slug }) => ({\n    name,\n    slug,\n  }));\n}\n\nexport function collectCategoriesWithCounts(\n  posts: CmsPostContent[],\n): BlogCategoryWithCount[] {\n  const bySlug = new Map<string, BlogCategoryWithCount>();\n  const out: BlogCategoryWithCount[] = [];\n  for (const post of posts) {\n    for (const t of categoryTerms(post)) {\n      const current = bySlug.get(t.slug);\n      if (current) {\n        current.count += 1;\n      } else {\n        const category = { name: t.name, slug: t.slug, count: 1 };\n        bySlug.set(t.slug, category);\n        out.push(category);\n      }\n    }\n  }\n  return out;\n}\n\n/** activeSlug 가 비면 전체 반환. 아니면 그 카테고리를 가진 글만. */\nexport function filterPostsByCategory(\n  posts: CmsPostContent[],\n  activeSlug: string | null | undefined,\n): CmsPostContent[] {\n  if (!activeSlug) return posts;\n  return posts.filter((p) => categoryTerms(p).some((t) => t.slug === activeSlug));\n}\n\n/** 기본 카테고리 링크: 전체 → `/blog`, 특정 → `/blog/categories/<slug>`. */\nexport function defaultCategoryHref(slug: string | null): string {\n  return makeCategoryHref(\"/blog\", \"namespaced\")(slug);\n}\n\n/**\n * 카테고리 링크 함수 — 목록·카테고리 허브·빵부스러기의 `categoryHref` 로 넘긴다.\n * `\"direct\"` 는 RootTale 표준(`/blog/{category}` 허브, 글은 `/blog/{category}/{slug}`),\n * `\"namespaced\"` 는 종전 `/blog/categories/{slug}`. 전체(`null`)는 언제나 목록.\n */\nexport function makeCategoryHref(\n  basePath: string,\n  categoryPath: \"namespaced\" | \"direct\",\n): (slug: string | null) => string {\n  const base = basePath.replace(/\\/+$/, \"\") || \"\";\n  const list = base || \"/\";\n  return (slug) => {\n    if (!slug) return list;\n    const encoded = encodeURIComponent(slug);\n    return categoryPath === \"direct\" ? `${base}/${encoded}` : `${base}/categories/${encoded}`;\n  };\n}\n\n// ── Collections (ADR-0060) — cms-core 라우팅 프리미티브 재export + 렌더 헬퍼 ──────\n//\n// 라우팅 코어(RouteCollection/resolvePostCollection/resolvePostUrl/postsForCollection/\n// validateCollections)는 `@roottale/cms-core` 에 있어 next/astro 가 공유한다\n// (ADR-0029 parity — codex consult `019ef577` 반영). 여기서는 next 소비자 편의를\n// 위해 재export + CmsPostContent 기반 스트림 스코프 카테고리 집계만 추가한다.\nimport {\n  type RouteCollection,\n  postsForCollection,\n} from \"@roottale/cms-core\";\n\nexport {\n  type RouteCollection,\n  type RoutablePost,\n  isInCollectionMode,\n  resolvePostCollection,\n  resolvePostUrl,\n  postsForCollection,\n  postsInAnyCollection,\n  validateCollections,\n} from \"@roottale/cms-core\";\n\n/**\n * 특정 collection 안에서 등장하는 카테고리 집계 — 그 스트림의 카테고리 칩/아카이브용.\n * **전체 정렬 리스트로 first-wins 해석**해 그 스트림에 최종 귀속된 글만 대상(한 글이\n * 여러 스트림 리스트에 중복되는 것을 방지 — codex 지적).\n */\nexport function collectCollectionCategories(\n  posts: CmsPostContent[],\n  collections: readonly RouteCollection[],\n  key: string,\n): BlogCategoryWithCount[] {\n  const owned = postsForCollection(posts, collections, key);\n  const collection = collections.find((c) => c.key === key);\n  const allowed = new Set(collection?.categories ?? []);\n  return collectCategoriesWithCounts(owned).filter((c) => allowed.has(c.slug));\n}\n","/**\n * 글의 공개 URL — ADR-0105 Amendment 1.\n *\n * 플랫폼이 저장한 정규 공개 경로(`post.path`, 공개 API `path`)가 있으면 그것을 쓴다.\n * 없으면(구 서버·물질화 전) 지금까지처럼 컬렉션 규칙(`resolvePostUrl`)이나 레거시\n * `blogBasePath` 로 계산한다. 어느 유형에도 속하지 않는 레거시 글은 사이트 설정의\n * `blogBasePath` 가 진실이라 저장 경로보다 우선한다(플랫폼 폴백은 `/blog` 고정).\n */\nimport { resolvePostUrl, type RoutablePost, type RouteCollection } from \"@roottale/cms-core\";\n\nfunction trimSlash(value: string): string {\n  return value.replace(/\\/+$/, \"\");\n}\n\nexport interface PostPublicUrlOptions {\n  readonly siteUrl: string;\n  readonly collections: RouteCollection[] | undefined;\n  readonly inCollectionMode: boolean;\n  readonly blogBasePath: string;\n}\n\n/** 공개 API 글의 구조적 최소형 — 구 cms-client 에는 `path`·`modelKey` 가 없어도 된다. */\nexport interface PublicUrlPost extends RoutablePost {\n  readonly path?: string | null;\n  readonly modelKey?: string | null;\n}\n\n/** 소속(모델·컬렉션)이 있는 글의 저장 경로. 레거시 미소속 글은 사이트 설정을 따른다. */\nexport function storedPostPath(\n  post: Pick<PublicUrlPost, \"path\" | \"collectionKey\" | \"modelKey\">,\n): string | null {\n  if (typeof post.path !== \"string\" || !post.path.startsWith(\"/\")) return null;\n  if (!post.collectionKey && !post.modelKey) return null;\n  return post.path;\n}\n\n/** 사이트맵·피드·llms 가 함께 쓰는 글 URL. 저장 경로 → 컬렉션 규칙 → 레거시 순. */\nexport function postPublicUrl(\n  post: PublicUrlPost,\n  options: PostPublicUrlOptions,\n): string | null {\n  const siteUrl = trimSlash(options.siteUrl);\n  const stored = storedPostPath(post);\n  if (stored) return `${siteUrl}${stored}`;\n  if (options.inCollectionMode) {\n    return resolvePostUrl(siteUrl, post, options.collections!);\n  }\n  return `${siteUrl}${trimSlash(options.blogBasePath)}/${post.slug}`;\n}\n","/**\n * `routes` 공통 — config 타입, collections resolve, fetch 헬퍼. feed/sitemap/llms/\n * revalidate/og 모듈이 공유한다(순환 import 회피). 공개 표면은 `routes.ts` 배럴.\n */\n\nimport { fetchPosts, type CmsPostContent } from \"@roottale/cms-client/server\";\nimport type { RouteCollection } from \"@roottale/cms-core\";\n\nexport type { RouteCollection };\n// 소비자 가드용 재export (`/blog/[slug]` 에서 스트림 누출 차단 등) — ADR-0060.\nexport { resolvePostCollection, resolvePostUrl } from \"@roottale/cms-core\";\n\nexport interface RootTaleSiteConfig {\n  /** `rtlk_cust_*` — 블로그 조회와 같은 키. 서버에서만(절대 브라우저 금지). */\n  apiKey: string;\n  /** API base 오버라이드. 기본 `https://api.roottale.com`. */\n  apiBase?: string;\n  /** 사이트 절대 URL (뒤 슬래시 없이). 예: `https://kjmtax.roottale.app`. */\n  siteUrl: string;\n  /** 피드/사이트 제목. */\n  title: string;\n  description?: string;\n  /** 기본 \"ko-KR\". */\n  language?: string;\n  /** RSS의 WebSub discovery link. 미지정이면 기존 RSS 출력 유지. */\n  webSubHubUrl?: string;\n  /** 블로그 base path. 기본 \"/blog\". 레거시 단일 스트림 — `collections` 미사용 시. */\n  blogBasePath?: string;\n  /**\n   * 카테고리 허브 주소 형식(레거시 단일 스트림용, `collections` 미사용 시).\n   * `\"namespaced\"`(기본) = `{blogBasePath}/categories/{slug}`,\n   * `\"direct\"` = `{blogBasePath}/{slug}` — RootTale 표준(`/blog/{category}/{slug}` 글 주소와\n   * 짝). collection 모드는 각 컬렉션의 `categoryPath` 를 따른다.\n   */\n  categoryPath?: \"namespaced\" | \"direct\";\n  /**\n   * 다중 스트림 라우팅 (ADR-0060). **길이 > 0 이면 collection 모드** — feed/sitemap/\n   * llms.txt 가 글을 소속 스트림 basePath 로 라우팅하고, 어느 스트림에도 안 속한 글은\n   * 제외한다. 비우거나 미전달 = 레거시 단일 `blogBasePath`(/blog) 동작(하위호환).\n   * 선언 순서 = 우선순위(first-wins).\n   *\n   * 배열 또는 **async resolver**(`() => Promise<RouteCollection[]>`)를 받는다 — 후자는\n   * 사이트가 `@roottale/cms-client` `fetchCollections()` 로 admin 설정을 가져올 때 쓴다.\n   * resolver 가 throw 하면 fail-soft(레거시 단일 /blog).\n   */\n  collections?: CollectionsInput;\n}\n\n/** collections 입력 — 정적 배열 또는 async resolver(admin 설정 fetch 용). */\nexport type CollectionsInput =\n  | RouteCollection[]\n  | (() => RouteCollection[] | Promise<RouteCollection[]>);\n\n/** resolve 결과 — `failed` 로 \"resolver throw\" 를 \"collections 미설정\" 과 구분한다. */\nexport async function resolveCollectionsResult(\n  input: CollectionsInput | undefined,\n): Promise<{ collections: RouteCollection[] | undefined; failed: boolean }> {\n  if (typeof input === \"function\") {\n    try {\n      return { collections: await input(), failed: false };\n    } catch (err) {\n      console.error(\n        \"[@roottale/cms-renderer-next/routes] collections resolver 실패:\",\n        err,\n      );\n      return { collections: undefined, failed: true };\n    }\n  }\n  return { collections: input, failed: false };\n}\n\n/**\n * resolver 면 호출(실패 시 undefined → 레거시), 배열이면 그대로. GET 팩토리(feed/\n * sitemap/llms)는 always-200 철학상 실패를 레거시 /blog 로 흡수 — revalidate 만\n * `resolveCollectionsResult` 로 실패를 구분해 under-invalidation 을 막는다.\n */\nexport async function resolveCollections(\n  input: CollectionsInput | undefined,\n): Promise<RouteCollection[] | undefined> {\n  return (await resolveCollectionsResult(input)).collections;\n}\n\nexport function trimSlash(u: string): string {\n  return u.replace(/\\/+$/, \"\");\n}\n\nexport async function safeFetchPosts(\n  config: RootTaleSiteConfig,\n  limit: number,\n): Promise<CmsPostContent[]> {\n  try {\n    const page = await fetchPosts({\n      apiKey: config.apiKey,\n      baseUrl: config.apiBase,\n      type: \"post\",\n      limit,\n    });\n    return page.items;\n  } catch (err) {\n    // 빌드/런타임 fetch 실패 시 빈 목록 — 라우트는 항상 정상 응답(404 방지).\n    console.error(\"[@roottale/cms-renderer-next/routes] fetchPosts 실패:\", err);\n    return [];\n  }\n}\n"],"mappings":"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","names":["postsForCollection","resolvePostUrl","resolvePostCollection","resolvePostUrl","trimSlash"]}

package/dist/cms-public.css

@@ -323,6 +323,42 @@
   font-style: italic;
 }
 
+/* 미리보기 안내 띠 — 본문 템플릿은 발행 화면과 같게 두고 이 띠만 덧붙인다. */
+[data-roottale-cms] :where(.rt-cms-preview-notice) {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 0.75rem;
+  align-items: center;
+  margin-block-end: 1rem;
+  padding: 0.5rem 0.75rem;
+  border-radius: 0.5rem;
+  /* 테두리·바탕·글자를 경고 색 하나에서 파생한다 — 색은 테넌트 테마(--rt-color-warning)
+     → 플랫폼 상태 토큰(--warning) → 독립 실행 기본값(amber) 순으로 따른다.
+     리터럴 amber 를 세 군데 따로 두지 않는 이유: 사이트가 경고 색을 바꾸면 세 색이
+     같이 움직여야 하고, 토큰 값 리터럴은 brand-hex 불변식이 막는다. */
+  border: 1px solid
+    color-mix(in srgb, var(--rt-color-warning, var(--warning, #d97706)) 35%, transparent);
+  background: color-mix(
+    in srgb,
+    var(--rt-color-warning, var(--warning, #d97706)) 12%,
+    var(--rt-color-background, #fff)
+  );
+  color: color-mix(
+    in srgb,
+    var(--rt-color-warning, var(--warning, #d97706)) 72%,
+    var(--rt-color-foreground, #111)
+  );
+  font-family: var(--rt-font-body, system-ui, sans-serif);
+  font-size: 0.875rem;
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+[data-roottale-cms] :where(.rt-cms-preview-notice__expiry) {
+  font-weight: 400;
+  opacity: 0.85;
+}
+
 [data-roottale-cms] :where(.rt-cms-article) {
   font-family: var(--rt-font-body, system-ui, sans-serif);
   color: var(--rt-color-foreground, #06162f);

package/dist/routes.d.ts

@@ -1,7 +1,8 @@
 import { CmsPostContent, RootTaleRedirect, CmsPostTranslationRef } from '@roottale/cms-client/server';
-import { RouteCollection } from '@roottale/cms-core';
+import { RouteCollection, RoutablePost } from '@roottale/cms-core';
 export { RouteCollection, resolvePostCollection, resolvePostUrl } from '@roottale/cms-core';
-import { B as BlogCategoryWithCount } from './blog-filter-BKCGM0qd.js';
+import { B as BlogCategoryWithCount } from './blog-filter-qE9Lj49C.js';
+export { m as makeCategoryHref } from './blog-filter-qE9Lj49C.js';
 
 /**
  * `routes` 공통 — config 타입, collections resolve, fetch 헬퍼. feed/sitemap/llms/
@@ -24,6 +25,13 @@ interface RootTaleSiteConfig {
     webSubHubUrl?: string;
     /** 블로그 base path. 기본 "/blog". 레거시 단일 스트림 — `collections` 미사용 시. */
     blogBasePath?: string;
+    /**
+     * 카테고리 허브 주소 형식(레거시 단일 스트림용, `collections` 미사용 시).
+     * `"namespaced"`(기본) = `{blogBasePath}/categories/{slug}`,
+     * `"direct"` = `{blogBasePath}/{slug}` — RootTale 표준(`/blog/{category}/{slug}` 글 주소와
+     * 짝). collection 모드는 각 컬렉션의 `categoryPath` 를 따른다.
+     */
+    categoryPath?: "namespaced" | "direct";
     /**
      * 다중 스트림 라우팅 (ADR-0060). **길이 > 0 이면 collection 모드** — feed/sitemap/
      * llms.txt 가 글을 소속 스트림 basePath 로 라우팅하고, 어느 스트림에도 안 속한 글은
@@ -456,6 +464,14 @@ interface PostMetadataInput {
      * 공지/블로그로 구분해 해석한다(`collectionKey:"notice"` → `/notice`).
      */
     collectionKey?: string | null;
+    /** 콘텐츠 모델 key — `path` 가 소속 글의 저장 경로인지 판정하는 데 쓴다. */
+    modelKey?: string | null;
+    /**
+     * ADR-0105 — 플랫폼이 저장한 정규 공개 경로(`CmsPostContent.path`). 원본 post 를
+     * 그대로 넘기면 채워진다. `options.path` 를 명시하지 않았을 때 `collections`
+     * 계산보다 먼저 canonical 경로가 된다 — 사이트가 주소를 다시 계산하지 않아도 된다.
+     */
+    path?: string | null;
     /**
      * ADR-0052 A안 (W4-6 PR C1) — 이 글의 발행된 언어판 목록(자기 자신 포함, PR B
      * 응답 `CmsPostContent.translations`). `options.locales` 와 함께 주면 hreflang
@@ -486,14 +502,15 @@ interface BuildPostMetadataOptions {
     siteUrl?: string;
     /**
      * self-canonical 기본값 경로 (예: `/blog/my-post`). `siteUrl` 과 함께.
-     * 명시하면 `collections` 파생보다 우선한다(단일 라우트 사이트용 명시 경로).
+     * 명시하면 글의 저장 경로·`collections` 파생보다 우선한다(이 화면의 실제 주소를
+     * 사이트가 아는 경우). 보통은 주지 않고 `post.path`(ADR-0105 원장)에 맡긴다.
      */
     path?: string;
     /**
-     * 섹션 정의 (ADR-0060). `path` 를 안 주면 글의 `collectionKey` 로 소속 섹션
-     * basePath 를 찾아 canonical 경로를 **공지/블로그로 구분해 자동 해석**한다
-     * (공지 글 → `/notice/{slug}`, 블로그 글 → `/blog/{slug}`). 어느 섹션에도
-     * 안 속하면(미설정·미존재 key) canonical 을 생략한다. `post.slug` 필요.
+     * 섹션 정의 (ADR-0060). `path` 도 저장 경로(`post.path`)도 없을 때 글의
+     * `collectionKey` 로 소속 섹션 basePath 를 찾아 canonical 경로를 **공지/블로그로
+     * 구분해 자동 해석**한다(공지 글 → `/notice/{slug}`, 블로그 글 → `/blog/{slug}`).
+     * 어느 섹션에도 안 속하면(미설정·미존재 key) canonical 을 생략한다. `post.slug` 필요.
      */
     collections?: readonly RouteCollection[];
     /**
@@ -545,6 +562,21 @@ declare function resolveRobotsMeta(flags: {
     noindex?: boolean;
     nofollow?: boolean;
 }): RobotsMeta | undefined;
+/** `buildPreviewMetadata` 반환 — Next `Metadata` 의 구조적 부분집합. */
+interface PreviewMetadata {
+    title: string;
+    robots: RobotsMeta;
+}
+/**
+ * 글 미리보기 페이지(`/preview/post/[id]?token=`) 의 metadata. 미리보기는 초안이므로
+ * **항상 noindex/nofollow** — 검색엔진이 미리보기 주소를 색인하면 비공개 글이
+ * 새고, 발행 주소와 중복 콘텐츠가 된다. 제목만 받아 `(미리보기)` 접미를 붙인다.
+ * canonical·og 는 일부러 내지 않는다(공유 카드로 초안이 캐시되지 않게).
+ */
+declare function buildPreviewMetadata(input: {
+    title?: string | null;
+    locale?: string;
+}): PreviewMetadata;
 /** Next `Metadata` 의 구조적 부분집합 — 소비자는 그대로 return 가능. */
 interface PostMetadata {
     title: string;
@@ -632,6 +664,23 @@ declare function buildPostMetadata(post: PostMetadataInput, options?: BuildPostM
  */
 declare function buildHreflangLanguages(translations: readonly CmsPostTranslationRef[] | undefined, siteUrl: string, locales: PostLocaleOptions): Record<string, string> | undefined;
 
+/**
+ * 글의 공개 URL — ADR-0105 Amendment 1.
+ *
+ * 플랫폼이 저장한 정규 공개 경로(`post.path`, 공개 API `path`)가 있으면 그것을 쓴다.
+ * 없으면(구 서버·물질화 전) 지금까지처럼 컬렉션 규칙(`resolvePostUrl`)이나 레거시
+ * `blogBasePath` 로 계산한다. 어느 유형에도 속하지 않는 레거시 글은 사이트 설정의
+ * `blogBasePath` 가 진실이라 저장 경로보다 우선한다(플랫폼 폴백은 `/blog` 고정).
+ */
+
+/** 공개 API 글의 구조적 최소형 — 구 cms-client 에는 `path`·`modelKey` 가 없어도 된다. */
+interface PublicUrlPost extends RoutablePost {
+    readonly path?: string | null;
+    readonly modelKey?: string | null;
+}
+/** 소속(모델·컬렉션)이 있는 글의 저장 경로. 레거시 미소속 글은 사이트 설정을 따른다. */
+declare function storedPostPath(post: Pick<PublicUrlPost, "path" | "collectionKey" | "modelKey">): string | null;
+
 /**
  * 아카이브(모음 페이지) 색인 정책 — **단일 SSoT**.
  *
@@ -974,4 +1023,4 @@ interface FleetInfoRouteConfig {
  */
 declare function createFleetInfoRoute(config?: FleetInfoRouteConfig): () => Promise<Response>;
 
-export { ARCHIVE_POST_COUNT_LIMIT, type AlwaysNoindexArchiveKind, type ArchiveCategoriesConfig, type ArchiveCategoriesOptions, type ArchiveIndexDecision, type ArchiveIndexInput, type ArchiveKind, type ArchiveMetadata, type ArchiveMetadataFields, type ArchiveMetadataInput, type ArchivePromotion, type BuildArchiveMetadataOptions, type BuildPostMetadataOptions, type CollectionsInput, type FleetInfoRouteConfig, type ImageResponseLike, type LlmsTxtLink, type LlmsTxtRouteConfig, type LlmsTxtSection, OG_IMAGE_CONTENT_TYPE, OG_IMAGE_SIZE, type OgImageRouteConfig, type PostLocaleOptions, type PostMetadata, type PostMetadataInput, type PostSeoOverrides, type PromotableArchiveKind, type RedirectMiddlewareConfig, type RevalidateRouteConfig, type RobotsMeta, type RootTaleSiteConfig, type SitemapEntry, type SitemapIndexOptions, type SitemapSectionId, buildArchiveMetadata, buildHreflangLanguages, buildPostMetadata, createFeedRoute, createFleetInfoRoute, createLlmsTxtRoute, createPostOgImage, createRedirectMiddleware, createRevalidateRoute, createSitemap, createSitemapIndex, decideArchiveIndex, fetchBlogArchiveCategories, fetchBlogArchivePosts, matchRedirect, normalizeRedirectPath, postRedirectPath, resolveAuthorPromotion, resolveCategoryPromotion, resolveCollections, resolveCollectionsResult, resolveRobotsMeta, safeFetchPosts, trimSlash };
+export { ARCHIVE_POST_COUNT_LIMIT, type AlwaysNoindexArchiveKind, type ArchiveCategoriesConfig, type ArchiveCategoriesOptions, type ArchiveIndexDecision, type ArchiveIndexInput, type ArchiveKind, type ArchiveMetadata, type ArchiveMetadataFields, type ArchiveMetadataInput, type ArchivePromotion, type BuildArchiveMetadataOptions, type BuildPostMetadataOptions, type CollectionsInput, type FleetInfoRouteConfig, type ImageResponseLike, type LlmsTxtLink, type LlmsTxtRouteConfig, type LlmsTxtSection, OG_IMAGE_CONTENT_TYPE, OG_IMAGE_SIZE, type OgImageRouteConfig, type PostLocaleOptions, type PostMetadata, type PostMetadataInput, type PostSeoOverrides, type PreviewMetadata, type PromotableArchiveKind, type PublicUrlPost, type RedirectMiddlewareConfig, type RevalidateRouteConfig, type RobotsMeta, type RootTaleSiteConfig, type SitemapEntry, type SitemapIndexOptions, type SitemapSectionId, buildArchiveMetadata, buildHreflangLanguages, buildPostMetadata, buildPreviewMetadata, createFeedRoute, createFleetInfoRoute, createLlmsTxtRoute, createPostOgImage, createRedirectMiddleware, createRevalidateRoute, createSitemap, createSitemapIndex, decideArchiveIndex, fetchBlogArchiveCategories, fetchBlogArchivePosts, matchRedirect, normalizeRedirectPath, postRedirectPath, resolveAuthorPromotion, resolveCategoryPromotion, resolveCollections, resolveCollectionsResult, resolveRobotsMeta, safeFetchPosts, storedPostPath, trimSlash };

package/dist/routes.js

@@ -1,13 +1,16 @@
 import {
   collectCategoriesWithCounts,
   collectCollectionCategories,
+  makeCategoryHref,
+  postPublicUrl,
   resolveCollections,
   resolveCollectionsResult,
   resolvePostCollection,
   resolvePostUrl,
   safeFetchPosts,
+  storedPostPath,
   trimSlash
-} from "./chunk-HM5VP7SR.js";
+} from "./chunk-GDP2VGJR.js";
 
 // src/routes.ts
 import { CMS_CLIENT_VERSION } from "@roottale/cms-client/server";
@@ -19,8 +22,7 @@ import {
 } from "@roottale/cms-client/server";
 import {
   isInCollectionMode as isInCollectionMode2,
-  resolvePostCollection as resolvePostCollection3,
-  resolvePostUrl as resolvePostUrl3
+  resolvePostCollection as resolvePostCollection3
 } from "@roottale/cms-core";
 
 // src/routes-metadata.ts
@@ -29,6 +31,14 @@ function resolveRobotsMeta(flags) {
   if (!flags.noindex && !flags.nofollow) return void 0;
   return { index: !flags.noindex, follow: !flags.nofollow };
 }
+function buildPreviewMetadata(input) {
+  const suffix = input.locale === "en" ? "(Preview)" : "(\uBBF8\uB9AC\uBCF4\uAE30)";
+  const base = input.title?.trim();
+  return {
+    title: base ? `${base} ${suffix}` : suffix,
+    robots: { index: false, follow: false }
+  };
+}
 function buildPostMetadata(post, options = {}) {
   const seo = post.seo ?? void 0;
   const title = seo?.title || post.title;
@@ -36,7 +46,11 @@ function buildPostMetadata(post, options = {}) {
   const ogImage = seo?.ogImage || post.image || void 0;
   let canonical = seo?.canonical || void 0;
   if (!canonical && options.siteUrl) {
-    let path = options.path;
+    let path = options.path ?? storedPostPath({
+      path: post.path,
+      collectionKey: post.collectionKey ?? null,
+      modelKey: post.modelKey ?? null
+    }) ?? void 0;
     if (!path && options.collections && post.slug) {
       path = resolvePostPath(
         { slug: post.slug, terms: [], collectionKey: post.collectionKey ?? null },
@@ -188,7 +202,11 @@ import {
   fetchBlogSettings,
   fetchPosts as fetchPosts2
 } from "@roottale/cms-client/server";
-import { isInCollectionMode, resolvePostCollection as resolvePostCollection2, resolvePostUrl as resolvePostUrl2 } from "@roottale/cms-core";
+import {
+  isInCollectionMode,
+  resolveCategoryPath,
+  resolvePostCollection as resolvePostCollection2
+} from "@roottale/cms-core";
 
 // src/archive-categories.ts
 import {
@@ -225,7 +243,12 @@ async function fetchServerCategoryCounts(config, options) {
     return result.categories.filter((category) => category.publishedPostCount > 0).map((category) => ({
       name: category.name,
       slug: category.slug,
-      count: category.publishedPostCount
+      count: category.publishedPostCount,
+      ...category.description ? { description: category.description } : {},
+      ...category.seoTitle ? { seoTitle: category.seoTitle } : {},
+      ...category.seoDescription ? { seoDescription: category.seoDescription } : {},
+      ...category.imageUrl ? { imageUrl: category.imageUrl } : {},
+      ...category.imageAlt ? { imageAlt: category.imageAlt } : {}
     }));
   } catch (err) {
     console.warn(
@@ -320,7 +343,12 @@ function postEntries(config, siteUrl, posts, collections, settings, defaultLocal
   const inCollection = isInCollectionMode(collections);
   const blogBase = config.blogBasePath ?? "/blog";
   return posts.flatMap((p) => {
-    const url = inCollection ? resolvePostUrl2(siteUrl, p, collections) : `${siteUrl}${blogBase}/${p.slug}`;
+    const url = postPublicUrl(p, {
+      siteUrl,
+      collections,
+      inCollectionMode: inCollection,
+      blogBasePath: blogBase
+    });
     if (!url) return [];
     const entry = {
       url,
@@ -365,20 +393,22 @@ async function categoryEntries(config, siteUrl, collections, promotedSlugs) {
       if (!cats.length) return [];
       const base = `${siteUrl}${trimSlash(c.basePath)}`;
       return [
-        { url: `${base}/categories` },
-        ...cats.filter(inSitemap).map((category) => ({
-          url: `${base}/categories/${category.slug}`
-        }))
+        ...c.categoryPath === "direct" ? [] : [{ url: `${base}/categories` }],
+        ...cats.filter(inSitemap).flatMap((category) => {
+          const path = resolveCategoryPath(c, category.slug);
+          return path ? [{ url: `${siteUrl}${path}` }] : [];
+        })
       ];
     });
   }
   const categories = await safeBlogArchiveCategories(config);
   if (!categories.length) return [];
   const blogBase = config.blogBasePath ?? "/blog";
+  const categoryHref = makeCategoryHref(blogBase, config.categoryPath ?? "namespaced");
   return [
-    { url: `${siteUrl}${blogBase}/categories` },
+    ...config.categoryPath === "direct" ? [] : [{ url: `${siteUrl}${blogBase}/categories` }],
     ...categories.filter(inSitemap).map((category) => ({
-      url: `${siteUrl}${blogBase}/categories/${category.slug}`
+      url: `${siteUrl}${categoryHref(category.slug)}`
     }))
   ];
 }
@@ -419,7 +449,7 @@ function createFeedRoute(config) {
       language: config.language,
       hubUrl: config.webSubHubUrl,
       items: rssItemsFromPosts(posts, {
-        postUrl: (p) => inCollectionMode ? resolvePostUrl3(siteUrl, p, collections) ?? `${siteUrl}${blogBase}/${p.slug}` : `${siteUrl}${blogBase}/${p.slug}`
+        postUrl: (p) => postPublicUrl(p, { siteUrl, collections, inCollectionMode, blogBasePath: blogBase }) ?? `${siteUrl}${blogBase}/${p.slug}`
       })
     });
     return new Response(xml, {
@@ -487,7 +517,7 @@ function createSitemapIndex(config, staticRoutes = [], opts = {}) {
 }
 
 // src/routes-llms.ts
-import { isInCollectionMode as isInCollectionMode3, resolvePostUrl as resolvePostUrl4 } from "@roottale/cms-core";
+import { isInCollectionMode as isInCollectionMode3 } from "@roottale/cms-core";
 function mdLinkSafe(text) {
   return text.replace(/[[\]()]/g, "").trim();
 }
@@ -515,7 +545,7 @@ function createLlmsTxtRoute(config) {
       const inCollectionMode = isInCollectionMode3(collections);
       lines.push("", inCollectionMode ? "## \uCF58\uD150\uCE20" : "## \uBE14\uB85C\uADF8");
       for (const p of posts) {
-        const url = inCollectionMode ? resolvePostUrl4(siteUrl, p, collections) : `${siteUrl}${blogBase}/${p.slug}`;
+        const url = inCollectionMode ? postPublicUrl(p, { siteUrl, collections, inCollectionMode: true, blogBasePath: blogBase }) : postPublicUrl(p, { siteUrl, collections, inCollectionMode: false, blogBasePath: blogBase });
         if (!url) continue;
         const excerpt = p.excerpt ? `: ${oneLine(p.excerpt)}` : "";
         lines.push(`- [${mdLinkSafe(p.title)}](${url})${excerpt}`);
@@ -895,7 +925,7 @@ function createFleetInfoRoute(config = {}) {
         site: config.site ?? env.VERCEL_PROJECT_PRODUCTION_URL ?? null,
         framework: "next",
         cms_client: CMS_CLIENT_VERSION,
-        cms_renderer: true ? "0.53.1" : "dev",
+        cms_renderer: true ? "0.56.0" : "dev",
         build_sha: env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) ?? null
       },
       { headers: { "cache-control": "public, max-age=300" } }
@@ -909,6 +939,7 @@ export {
   buildArchiveMetadata,
   buildHreflangLanguages,
   buildPostMetadata,
+  buildPreviewMetadata,
   createFeedRoute,
   createFleetInfoRoute,
   createLlmsTxtRoute,
@@ -920,6 +951,7 @@ export {
   decideArchiveIndex,
   fetchBlogArchiveCategories,
   fetchBlogArchivePosts,
+  makeCategoryHref,
   matchRedirect,
   normalizeRedirectPath,
   postRedirectPath,
@@ -931,6 +963,7 @@ export {
   resolvePostUrl,
   resolveRobotsMeta,
   safeFetchPosts,
+  storedPostPath,
   trimSlash
 };
 //# sourceMappingURL=routes.js.map