@roottale/cms-renderer-next 0.51.1 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # @roottale/cms-renderer-next
 
+## 0.53.0
+
+### Minor Changes
+
+- a133f27: 블로그 상세 글의 작성·출력 기준을 하나로 맞췄습니다.
+  - 이미지 대체 텍스트를 한 줄, 최대 160자로 정규화하는 공용 계약을 추가했습니다.
+  - 상세 글 위에 카테고리를 연결하고, 발행일과 실제로 다른 수정일을 구분해 표시합니다.
+  - 본문의 공식 출처 블록을 제목과 목록이 있는 시맨틱 구간으로 렌더합니다.
+  - 블로그 전용 SEO 점검에서 목차, 외부 링크가 있는 공식 출처, 내용이 채워진 FAQ를 확인합니다.
+  - Next.js 상세 라우트가 글을 먼저 조회한 뒤 `notFound()`를 호출해야 실제 404가 된다는 통합 예제를 보강했습니다.
+
+- e3e7ba8: 블로그 상세 상단에 CMS에서 기록한 내용 검토일과 검토자를 표시합니다.
+- 7d1a551: 글 메타데이터가 OG 이미지 대체 텍스트와 Google의 큰 이미지 미리보기 지시자를 함께 출력합니다.
+- 3dc6e1d: 공개 CMS runtime에서 RootTale의 private 마케팅 섹션 공장을 분리했습니다.
+  - `templates`, `templates/styles`, `validate`, `templates/seo-checks` 공개 subpath를 제거했습니다.
+  - 글·페이지 본문, 테마 bridge, 문의, feed·sitemap·webhook runtime은 그대로 유지합니다.
+  - `section` 노드는 공개 renderer가 자동으로 해석하지 않으며, 내부 제작 경로가 명시적으로 renderer를 등록해야 합니다.
+  - 같은 릴리스 묶음의 `@roottale/cms-core` 변경과 함께 배포해야 합니다.
+
+### Patch Changes
+
+- 2eb82d3: 블로그 작성자 프로필의 기준을 글에 지정된 사이트 작성자 한 곳으로 통합했습니다.
+  - 작성자가 없는 글은 전역 설정으로 작성자 카드가 만들어지지 않습니다.
+  - 작성자 이름·사진·소개는 글 응답의 작성자 프로필만 사용합니다.
+  - 레거시 전역 작성자 응답 필드는 호환을 위해 남지만 항상 `null`입니다.
+
+- 3ab5570: RSS 생성기에 선택적인 WebSub `atom:hub` 링크를 추가했다. `createFeedRoute`는
+  `webSubHubUrl`을 받아 이를 피드에 전달하며, 값을 주지 않은 기존 사이트의 출력은
+  바뀌지 않는다. Site Kit은 Google WebSub hub를 기본 연결하고 IndexNow 소유권 확인용
+  `/indexnow-key.txt` 라우트를 제공한다.
+- Updated dependencies [a133f27]
+- Updated dependencies [f743a06]
+- Updated dependencies [3ab5570]
+  - @roottale/cms-core@0.53.0
+  - @roottale/cms-client@0.53.0
+
+## 0.52.0
+
+### Minor Changes
+
+- 01f5534: 어드민에서 **설정**을 고치면 사이트에 즉시 반영된다 — 지금까지 글·디자인만 즉시였고 사업장 정보(전화·주소)·상단 메뉴·블로그 표시 설정·콘텐츠 유형은 최대 30분 걸렸다.
+
+  원인은 두 개였다. ① 그 설정들을 읽는 조회 함수에 **캐시 이름표를 붙일 방법이 없었다**. ② 그래서 `revalidatePath` 로는 그 조회의 응답 캐시(Next.js Data Cache)를 지울 수 없었다 — 경로 캐시만 지워지고 옛 전화번호가 그대로 남았다.
+
+  **`@roottale/cms-client`**
+  - `fetchBusinessProfile` · `fetchMenu` · `fetchMenus` · `fetchBlogSettings` · `fetchCollections` 가 `tags?: string[]` 를 받는다(이미 있던 `fetchTheme` 와 같은 방식).
+  - 이름표 상수를 내보낸다: `BUSINESS_CACHE_TAG`("rt-business") · `MENUS_CACHE_TAG`("rt-menus") · `BLOG_SETTINGS_CACHE_TAG`("rt-blog-settings") · `COLLECTIONS_CACHE_TAG`("rt-collections"). 다섯 개(테마 포함)를 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 함께.
+  - **`tags` 를 안 넘기면 동작이 예전과 한 글자도 다르지 않다** — `next` 키 자체를 만들지 않는다. 기존 코드는 그대로 두어도 된다.
+
+  **`@roottale/cms-renderer-next`** — `createRevalidateRoute` 의 설정 저장 신호(`theme.updated`) 처리
+  - 테마 이름표만이 아니라 위 다섯 개를 **함께** 지운다. 무엇이 바뀌었는지 웹훅 본문에 없기 때문이고, 쓰지 않는 이름표를 지우는 것은 아무 일도 일어나지 않으므로 해가 없다.
+  - `themeTag` 를 커스텀 이름으로 덮어썼다면 그 이름을 쓴다(기본 `rt-theme` 는 건드리지 않는다).
+  - **본문 `paths` 도 함께 갱신한다**(전에는 무시했다). 콘텐츠 유형 저장이 `/sitemap.xml`·`/feed.xml`·`/llms.txt` 를 보내는데, 이건 route handler 라서 레이아웃 무효화에 딸려 온다고 가정할 수 없다. 디자인 저장처럼 `paths` 가 비어 있으면 아무 일도 일어나지 않는다.
+  - **하나가 실패해도 나머지를 전부 시도한다.** 이름표 하나에서 멈추면 남은 이름표와 레이아웃 무효화까지 건너뛰기 때문이다. 하나라도 실패하면 성공으로 위장하지 않고 **500** 과 `failed[]`(무엇이·왜)를 돌려줘 플랫폼이 재시도하게 한다.
+  - `revalidateTag` 를 주입하지 않은 사이트의 동작은 **그대로**다(이름표 생략 + 레이아웃 재검증, 응답 200).
+  - 응답 본문이 늘었다: `revalidated` 에 `requestedTags: string[]`(콜백에 **넘긴** 이름표 — 실제로 지워졌는지는 Next 가 알려주지 않아 "요청한" 목록이다)와 `paths: string[]` 가 추가됐다. 기존 `tag` 필드는 테마 이름표를 담은 채 그대로 있다 — 로그를 파싱하던 쪽이 깨지지 않는다.
+
+  **사이트에서 할 일** — 두 군데를 함께 손봐야 즉시 반영이 된다. 한쪽만 하면 아무 오류 없이 "가끔 늦게 반영"으로만 보인다.
+
+  ```ts
+  // 1) app/api/revalidate/route.ts — 이름표를 지울 수 있게 주입
+  import { revalidatePath, revalidateTag } from "next/cache";
+  import { THEME_CACHE_TAG } from "@roottale/cms-client/server";
+  import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
+
+  export const POST = createRevalidateRoute({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    // 2번째 인자(type)를 반드시 그대로 넘긴다 — `(path) => …` 로 감싸면
+    // 레이아웃 전역 무효화가 페이지 1개 무효화로 줄어든다.
+    revalidate: (path, type) => revalidatePath(path, type),
+    // { expire: 0 } = 즉시 만료. 다른 프로파일("max" 등)은 expire 가 0 이 아니라
+    // Next 가 stale-while-revalidate 로 취급해 다음 요청이 여전히 옛 값을 받는다
+    // ("max" 의 expire 는 1년). updateTag 는 서버 액션 전용이라 여기서 throw 한다.
+    revalidateTag: (tag: string) => revalidateTag(tag, { expire: 0 }),
+    themeTag: THEME_CACHE_TAG,
+  });
+
+  // 2) 설정 조회마다 이름표를 붙인다
+  const business = await fetchBusinessProfile({
+    apiKey,
+    tags: [BUSINESS_CACHE_TAG],
+  });
+  ```
+
+  확인 방법: 웹훅 응답의 `revalidated.requestedTags` 가 비어 있으면 1번 주입이 빠진 것이다.
+
+  > **이벤트 변경 안내** — 어드민의 사업장 정보·메뉴·블로그 표시 설정·콘텐츠 유형 저장이 이제 `post.updated` 대신 `theme.updated` 를 보낸다(디자인·상단 메뉴·공지 배너·상담바는 원래 그랬다). `createRevalidateRoute` 를 쓰면 신경 쓸 것이 없다. 이벤트 이름으로 직접 분기하는 수신기를 손으로 짰다면 `theme.updated` 분기를 추가하라.
+
+### Patch Changes
+
+- 9cbd8e5: 블로그 목록 카드가 한 행에서 서로 다른 높이로 끝나던 문제를 고쳤다. 카드 링크의
+  `min-block-size: 100%` 는 부모(`li`)의 높이가 확정돼야 풀리는데 `li` 가 일반
+  블록이라 auto 로 접혔다. `li` 를 grid 로 만들어 링크가 행 높이를 채우게 한다.
+- Updated dependencies [01f5534]
+  - @roottale/cms-client@0.52.0
+
 ## 0.51.1
 
 ### Patch Changes

package/README.md

@@ -6,7 +6,9 @@ Drop-in `<RootTaleBlogList>` / `<RootTaleBlogPost>` / `<RootTaleLeadForm>` for N
 
 Pair with [`@roottale/cms-client`](https://www.npmjs.com/package/@roottale/cms-client) (the fetch client) and the RootTale CMS admin (`mysite.roottale.com`) where you author the content.
 
-Astro counterpart: [`@roottale/cms-renderer-astro`](https://www.npmjs.com/package/@roottale/cms-renderer-astro) — equivalent surface (ADR-0034 §1.5).
+이 public package는 글·페이지 본문과 CMS 연동 runtime만 제공한다. RootTale의
+전문직·B2B 마케팅 섹션, variants와 `SectionSchema`는 private 제작 공장에 있으며
+고객 사이트에는 선택된 결과만 local source로 전달한다.
 
 ## Install
 
@@ -47,17 +49,46 @@ are fallback only.
 
 ```ts
 // app/api/revalidate/route.ts
-import { revalidatePath } from "next/cache";
+import { revalidatePath, revalidateTag } from "next/cache";
 
+import { THEME_CACHE_TAG } from "@roottale/cms-client/server";
 import { createRevalidateRoute } from "@roottale/cms-renderer-next/routes";
 
 export const POST = createRevalidateRoute({
   apiKey: process.env.ROOTTALE_API_KEY!,
   apiBase: process.env.ROOTTALE_API_BASE,
-  revalidate: revalidatePath,
+  // Pass the second argument through. The factory calls
+  // `revalidate("/", "layout")` on settings saves; a `(path) => …` callback
+  // silently drops `"layout"` and downgrades a full layout purge to one page.
+  revalidate: (path, type) => revalidatePath(path, type),
+  // Required for settings (design tokens, site nav, business profile, blog
+  // display, content collections) to land immediately: `revalidatePath` cannot
+  // evict the Data Cache entry behind `fetchTheme`/`fetchBusinessProfile`/
+  // `fetchMenus`, so the route evicts them by cache tag instead.
+  //
+  // The profile must be `{ expire: 0 }` — Next treats any profile with a
+  // non-zero `expire` as a stale-while-revalidate update, so the next request
+  // still serves the old value (the built-in `"max"` profile expires in a
+  // year). `updateTag` is immediate but Server-Action only and throws inside a
+  // Route Handler, so it cannot be used here.
+  revalidateTag: (tag: string) => revalidateTag(tag, { expire: 0 }),
+  themeTag: THEME_CACHE_TAG,
 });
 ```
 
+On `theme.updated` the route evicts every tag in `SETTINGS_CACHE_TAGS`
+(`@roottale/cms-client/server`), revalidates `/` as a layout, and then
+revalidates the body `paths` (content-collection saves send `/sitemap.xml`,
+`/feed.xml`, `/llms.txt` — route handlers that a layout purge cannot be assumed
+to cover). Every step is attempted even if an earlier one throws; if anything
+failed the route answers `500` with a `failed[]` list so the platform retries.
+
+Attach the matching tag to each settings fetch — `tags: [THEME_CACHE_TAG]`,
+`[BUSINESS_CACHE_TAG]`, `[MENUS_CACHE_TAG]`, `[BLOG_SETTINGS_CACHE_TAG]`,
+`[COLLECTIONS_CACHE_TAG]`. Without `revalidateTag` the route still works and
+returns 200, but settings changes only land after each fetch's `revalidate`
+window (`revalidated.requestedTags` comes back empty — that is the tell).
+
 ADMIN setup: open `/s/{tenant-slug}/sites/{site-id}`, set **Webhook URL** to
 `https://<customer-domain>/api/revalidate`, keep it enabled, and save. See
 [`docs/cms-revalidation-webhooks.md`](../../docs/cms-revalidation-webhooks.md)
@@ -117,7 +148,9 @@ export default async function CategoryPage({
 ## Blog post — `app/blog/[slug]/page.tsx`
 
 ```tsx
+import { fetchPost } from "@roottale/cms-client/server";
 import { RootTaleBlogPost } from "@roottale/cms-renderer-next/server";
+import { notFound } from "next/navigation";
 
 export default async function PostPage({
   params,
@@ -125,13 +158,21 @@ export default async function PostPage({
   params: Promise<{ slug: string }>;
 }) {
   const { slug } = await params;
+  const post = await fetchPost({
+    apiKey: process.env.ROOTTALE_API_KEY!,
+    slugOrId: slug,
+  });
+  if (!post) notFound();
+
   return (
     <main>
       <RootTaleBlogPost
         apiKey={process.env.ROOTTALE_API_KEY!}
-        slugOrId={slug}
+        slugOrId={post.id}
         showTableOfContents
         tableOfContentsTitle="목차"
+        breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
+        relatedPostsCount={3}
       />
     </main>
   );
@@ -142,6 +183,15 @@ export default async function PostPage({
 already renders that title, pass `showTitle={false}` to avoid a duplicate
 heading. The excerpt, post metadata, and body remain visible.
 
+Fetch the post in the route and call Next.js `notFound()` before rendering, as
+shown above. `notFoundElement` only changes the component fallback; it cannot
+turn a successful route response into an HTTP 404.
+
+When present, category links render above the `<h1>`. The metadata row labels
+the published date and displays a separate modified date only when its calendar
+date differs. Body images always receive a one-line alt value capped at 160
+characters.
+
 ## Lead form — `app/contact/page.tsx`
 
 ```tsx

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

@@ -101,4 +101,4 @@ export {
   resolvePostCollection2 as resolvePostCollection,
   resolvePostUrl2 as resolvePostUrl
 };
-//# sourceMappingURL=chunk-U2IM6OCQ.js.map
+//# sourceMappingURL=chunk-HM5VP7SR.js.map

package/dist/{chunk-U2IM6OCQ.js.map → chunk-HM5VP7SR.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/blog-filter.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}\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 slug ? `/blog/categories/${encodeURIComponent(slug)}` : \"/blog\";\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 * `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  /** 블로그 base path. 기본 \"/blog\". 레거시 단일 스트림 — `collections` 미사용 시. */\n  blogBasePath?: string;\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":";AA0EA;AAAA,EAEE;AAAA,OACK;AAEP;AAAA,EAGE;AAAA,EACA;AAAA,EACA;AAAA,EACA,sBAAAA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AArEP,SAAS,cAAc,MAAoC;AACzD,UAAQ,KAAK,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,aAAa,UAAU;AACnE;AAMO,SAAS,kBAAkB,OAAyC;AACzE,SAAO,4BAA4B,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO;AAAA,IACjE;AAAA,IACA;AAAA,EACF,EAAE;AACJ;AAEO,SAAS,4BACd,OACyB;AACzB,QAAM,SAAS,oBAAI,IAAmC;AACtD,QAAM,MAA+B,CAAC;AACtC,aAAW,QAAQ,OAAO;AACxB,eAAW,KAAK,cAAc,IAAI,GAAG;AACnC,YAAM,UAAU,OAAO,IAAI,EAAE,IAAI;AACjC,UAAI,SAAS;AACX,gBAAQ,SAAS;AAAA,MACnB,OAAO;AACL,cAAM,WAAW,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,OAAO,EAAE;AACxD,eAAO,IAAI,EAAE,MAAM,QAAQ;AAC3B,YAAI,KAAK,QAAQ;AAAA,MACnB;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAGO,SAAS,sBACd,OACA,YACkB;AAClB,MAAI,CAAC,WAAY,QAAO;AACxB,SAAO,MAAM,OAAO,CAAC,MAAM,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,UAAU,CAAC;AAChF;AAGO,SAAS,oBAAoB,MAA6B;AAC/D,SAAO,OAAO,oBAAoB,mBAAmB,IAAI,CAAC,KAAK;AACjE;AA6BO,SAAS,4BACd,OACA,aACA,KACyB;AACzB,QAAM,QAAQ,mBAAmB,OAAO,aAAa,GAAG;AACxD,QAAM,aAAa,YAAY,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG;AACxD,QAAM,UAAU,IAAI,IAAI,YAAY,cAAc,CAAC,CAAC;AACpD,SAAO,4BAA4B,KAAK,EAAE,OAAO,CAAC,MAAM,QAAQ,IAAI,EAAE,IAAI,CAAC;AAC7E;;;ACnGA,SAAS,kBAAuC;AAKhD,SAAS,yBAAAC,wBAAuB,kBAAAC,uBAAsB;AAmCtD,eAAsB,yBACpB,OAC0E;AAC1E,MAAI,OAAO,UAAU,YAAY;AAC/B,QAAI;AACF,aAAO,EAAE,aAAa,MAAM,MAAM,GAAG,QAAQ,MAAM;AAAA,IACrD,SAAS,KAAK;AACZ,cAAQ;AAAA,QACN;AAAA,QACA;AAAA,MACF;AACA,aAAO,EAAE,aAAa,QAAW,QAAQ,KAAK;AAAA,IAChD;AAAA,EACF;AACA,SAAO,EAAE,aAAa,OAAO,QAAQ,MAAM;AAC7C;AAOA,eAAsB,mBACpB,OACwC;AACxC,UAAQ,MAAM,yBAAyB,KAAK,GAAG;AACjD;AAEO,SAAS,UAAU,GAAmB;AAC3C,SAAO,EAAE,QAAQ,QAAQ,EAAE;AAC7B;AAEA,eAAsB,eACpB,QACA,OAC2B;AAC3B,MAAI;AACF,UAAM,OAAO,MAAM,WAAW;AAAA,MAC5B,QAAQ,OAAO;AAAA,MACf,SAAS,OAAO;AAAA,MAChB,MAAM;AAAA,MACN;AAAA,IACF,CAAC;AACD,WAAO,KAAK;AAAA,EACd,SAAS,KAAK;AAEZ,YAAQ,MAAM,iEAAuD,GAAG;AACxE,WAAO,CAAC;AAAA,EACV;AACF;","names":["postsForCollection","resolvePostCollection","resolvePostUrl"]}
+{"version":3,"sources":["../src/blog-filter.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}\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 slug ? `/blog/categories/${encodeURIComponent(slug)}` : \"/blog\";\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 * `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   * 다중 스트림 라우팅 (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":";AA0EA;AAAA,EAEE;AAAA,OACK;AAEP;AAAA,EAGE;AAAA,EACA;AAAA,EACA;AAAA,EACA,sBAAAA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AArEP,SAAS,cAAc,MAAoC;AACzD,UAAQ,KAAK,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,aAAa,UAAU;AACnE;AAMO,SAAS,kBAAkB,OAAyC;AACzE,SAAO,4BAA4B,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO;AAAA,IACjE;AAAA,IACA;AAAA,EACF,EAAE;AACJ;AAEO,SAAS,4BACd,OACyB;AACzB,QAAM,SAAS,oBAAI,IAAmC;AACtD,QAAM,MAA+B,CAAC;AACtC,aAAW,QAAQ,OAAO;AACxB,eAAW,KAAK,cAAc,IAAI,GAAG;AACnC,YAAM,UAAU,OAAO,IAAI,EAAE,IAAI;AACjC,UAAI,SAAS;AACX,gBAAQ,SAAS;AAAA,MACnB,OAAO;AACL,cAAM,WAAW,EAAE,MAAM,EAAE,MAAM,MAAM,EAAE,MAAM,OAAO,EAAE;AACxD,eAAO,IAAI,EAAE,MAAM,QAAQ;AAC3B,YAAI,KAAK,QAAQ;AAAA,MACnB;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAGO,SAAS,sBACd,OACA,YACkB;AAClB,MAAI,CAAC,WAAY,QAAO;AACxB,SAAO,MAAM,OAAO,CAAC,MAAM,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,EAAE,SAAS,UAAU,CAAC;AAChF;AAGO,SAAS,oBAAoB,MAA6B;AAC/D,SAAO,OAAO,oBAAoB,mBAAmB,IAAI,CAAC,KAAK;AACjE;AA6BO,SAAS,4BACd,OACA,aACA,KACyB;AACzB,QAAM,QAAQ,mBAAmB,OAAO,aAAa,GAAG;AACxD,QAAM,aAAa,YAAY,KAAK,CAAC,MAAM,EAAE,QAAQ,GAAG;AACxD,QAAM,UAAU,IAAI,IAAI,YAAY,cAAc,CAAC,CAAC;AACpD,SAAO,4BAA4B,KAAK,EAAE,OAAO,CAAC,MAAM,QAAQ,IAAI,EAAE,IAAI,CAAC;AAC7E;;;ACnGA,SAAS,kBAAuC;AAKhD,SAAS,yBAAAC,wBAAuB,kBAAAC,uBAAsB;AAqCtD,eAAsB,yBACpB,OAC0E;AAC1E,MAAI,OAAO,UAAU,YAAY;AAC/B,QAAI;AACF,aAAO,EAAE,aAAa,MAAM,MAAM,GAAG,QAAQ,MAAM;AAAA,IACrD,SAAS,KAAK;AACZ,cAAQ;AAAA,QACN;AAAA,QACA;AAAA,MACF;AACA,aAAO,EAAE,aAAa,QAAW,QAAQ,KAAK;AAAA,IAChD;AAAA,EACF;AACA,SAAO,EAAE,aAAa,OAAO,QAAQ,MAAM;AAC7C;AAOA,eAAsB,mBACpB,OACwC;AACxC,UAAQ,MAAM,yBAAyB,KAAK,GAAG;AACjD;AAEO,SAAS,UAAU,GAAmB;AAC3C,SAAO,EAAE,QAAQ,QAAQ,EAAE;AAC7B;AAEA,eAAsB,eACpB,QACA,OAC2B;AAC3B,MAAI;AACF,UAAM,OAAO,MAAM,WAAW;AAAA,MAC5B,QAAQ,OAAO;AAAA,MACf,SAAS,OAAO;AAAA,MAChB,MAAM;AAAA,MACN;AAAA,IACF,CAAC;AACD,WAAO,KAAK;AAAA,EACd,SAAS,KAAK;AAEZ,YAAQ,MAAM,iEAAuD,GAAG;AACxE,WAAO,CAAC;AAAA,EACV;AACF;","names":["postsForCollection","resolvePostCollection","resolvePostUrl"]}

package/dist/chunk-KSPPYX22.js

@@ -0,0 +1,14 @@
+// src/section-render-context.ts
+var sectionNodeRenderer = null;
+function setSectionNodeRenderer(renderer) {
+  sectionNodeRenderer = renderer;
+}
+function getSectionNodeRenderer() {
+  return sectionNodeRenderer;
+}
+
+export {
+  setSectionNodeRenderer,
+  getSectionNodeRenderer
+};
+//# sourceMappingURL=chunk-KSPPYX22.js.map

package/dist/chunk-KSPPYX22.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/section-render-context.ts"],"sourcesContent":["/**\n * 섹션 렌더러 주입 지점 — ADR-0040 P2 단방향 계약(코어 ◄ site-sections).\n *\n * 본문(tiptap) 안의 `section` 노드는 비공개 `site-sections` 컴포넌트로 그리지만,\n * 공개 코어가 비공개 패키지를 직접 import 하면 순환·번들\n * 오염이 된다(dependency-cruiser `no-renderer-core-to-templates`). 그래서 코어는\n * \"섹션을 그리는 함수\" 의 자리만 비워두고, private\n * `@roottale/site-sections`를 import 하는 내부 제작 경로에서만 채운다.\n *\n * 등록 없이 `section` 노드를 만나면 dev 경고 후 skip — 미지 섹션 타입을 만났을\n * 때와 같은 fail-soft 동작이다.\n */\nimport type { ReactElement, ReactNode } from \"react\";\nimport type { CmsPostContent } from \"@roottale/cms-client/server\";\n\n/** 발행 API 호출에 필요한 최소 컨텍스트(공개 키 + 베이스 URL). */\nexport type CmsBoundContext = { apiKey: string; baseUrl?: string };\n\nexport type BlogListProps = {\n  apiKey: string;\n  baseUrl?: string;\n  limit?: number;\n  emptyMessage?: string;\n  postHref?: (post: CmsPostContent) => string;\n};\n\nexport type SectionRenderContext = {\n  cms: CmsBoundContext | null;\n  renderBlogList: (props: BlogListProps) => ReactNode;\n  isDev: () => boolean;\n};\n\n/** `section` 노드 하나를 그리는 함수 — templates 쪽 구현이 주입된다. */\nexport type SectionNodeRenderer = (\n  node: { type?: string; attrs?: Record<string, unknown> },\n  key: number,\n  context: SectionRenderContext,\n) => ReactElement | null;\n\nlet sectionNodeRenderer: SectionNodeRenderer | null = null;\n\n/**\n * private 섹션 공장이 로드되며 호출한다. 공개 CMS runtime만 쓰는 고객 FRONT는\n * 이 함수를 호출하지 않으며 `section` 노드를 마케팅 페이지 구조로 사용하지 않는다.\n */\nexport function setSectionNodeRenderer(renderer: SectionNodeRenderer): void {\n  sectionNodeRenderer = renderer;\n}\n\nexport function getSectionNodeRenderer(): SectionNodeRenderer | null {\n  return sectionNodeRenderer;\n}\n"],"mappings":";AAuCA,IAAI,sBAAkD;AAM/C,SAAS,uBAAuB,UAAqC;AAC1E,wBAAsB;AACxB;AAEO,SAAS,yBAAqD;AACnE,SAAO;AACT;","names":[]}

package/dist/cms-public.css

@@ -120,6 +120,14 @@
 
 [data-roottale-cms] :where(.rt-cms-list-item) {
   min-inline-size: 0;
+  /*
+   * 카드 링크가 행 높이를 채우게 한다. 링크에 `min-block-size: 100%` 가 있지만
+   * 퍼센트는 부모 높이가 확정돼야 풀리는데, `li` 가 일반 블록이면 높이가 auto 라
+   * 그 100% 가 내용 높이로 접힌다 — 한 행의 카드들이 제목 줄 수에 따라 제각각
+   * 끝나는 원인이었다(2026-07-28 실측: 243·243·273px). `li` 를 grid 로 만들면
+   * 링크가 grid item 이 되어 stretch 로 행 높이를 채운다.
+   */
+  display: grid;
 }
 
 [data-roottale-cms] :where(.rt-cms-card-link) {
@@ -418,6 +426,27 @@
   border-block-end: 1px solid color-mix(in srgb, var(--rt-color-border, #dceef3) 72%, transparent);
 }
 
+[data-roottale-cms] :where(.rt-cms-post-categories) {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--rt-spacing-2, 0.5rem);
+  margin-block-end: var(--rt-spacing-3, 0.75rem);
+}
+
+[data-roottale-cms] :where(.rt-cms-post-category) {
+  display: inline-flex;
+  align-items: center;
+  min-block-size: 1.75rem;
+  padding-inline: 0.625rem;
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--rt-color-primary, #06162f) 9%, transparent);
+  color: var(--rt-color-primary, #06162f);
+  font-size: var(--rt-font-size-sm, 0.8125rem);
+  font-weight: var(--rt-font-weight-bold, 700);
+  line-height: 1.2;
+  text-decoration: none;
+}
+
 [data-roottale-cms] :where(.rt-cms-post-header .rt-cms-title) {
   font-size: clamp(1.75rem, 1.35rem + 1.9vw, 2.375rem);
   font-weight: var(--rt-font-weight-bold, 800);
@@ -829,6 +858,23 @@
   font-weight: 600;
 }
 
+/* 공식 출처 — 일반 목록과 구분되는 근거 묶음. */
+[data-roottale-cms] :where(.rt-cms-references) {
+  padding: var(--rt-spacing-5, 1.25rem);
+  border: 1px solid color-mix(in srgb, var(--rt-color-border, #dceef3) 88%, transparent);
+  border-radius: var(--rt-radius-md, 0.5rem);
+  background: color-mix(in srgb, var(--rt-color-muted, #f7f8f7) 34%, transparent);
+}
+
+[data-roottale-cms] :where(.rt-cms-references .rt-cms-references__title) {
+  margin: 0 0 var(--rt-spacing-3, 0.75rem);
+  font-size: var(--rt-font-size-xl, 1.375rem);
+}
+
+[data-roottale-cms] :where(.rt-cms-references > ul) {
+  margin: 0;
+}
+
 /* 글 하단 고정 CTA — 본문 끝 리드 전환 블록. */
 [data-roottale-cms] :where(.rt-cms-post-cta) {
   max-inline-size: var(--rt-cms-measure, 42.5rem);

package/dist/routes.d.ts

@@ -20,6 +20,8 @@ interface RootTaleSiteConfig {
     description?: string;
     /** 기본 "ko-KR". */
     language?: string;
+    /** RSS의 WebSub discovery link. 미지정이면 기존 RSS 출력 유지. */
+    webSubHubUrl?: string;
     /** 블로그 base path. 기본 "/blog". 레거시 단일 스트림 — `collections` 미사용 시. */
     blogBasePath?: string;
     /**
@@ -198,11 +200,26 @@ interface RevalidateRouteConfig {
      * Next 의 `revalidatePath` (또는 동등 콜백) 주입. 2번째 인자(`"layout"`)로
      * 레이아웃 전역 무효화를 지원 — `theme.updated` 시 정적 페이지까지 반영하려면
      * 필요(next `revalidatePath(path, "layout")` 시그니처와 호환).
+     *
+     * **콜백으로 감쌀 때 2번째 인자를 반드시 그대로 넘겨라.** `(path) =>
+     * revalidatePath(path)` 처럼 1개만 받으면 이 팩토리가 호출하는
+     * `revalidate("/", "layout")` 의 `"layout"` 이 사라져 레이아웃 전역 무효화가
+     * 페이지 1개 무효화로 줄어든다(정적 고객 페이지가 안 바뀐다).
+     * 올바른 모양: `(path, type) => revalidatePath(path, type)`.
      */
     revalidate: (path: string, type?: "layout" | "page") => void | Promise<void>;
     /**
      * Next 의 `revalidateTag` (또는 동등 콜백) 주입 — `theme.updated`(W0-4) 시
-     * 테마 fetch 캐시 tag 를 무효화한다. 미지정 시 tag 무효화 생략(layout 만).
+     * 테마 + 설정류 fetch 캐시 tag(ADR-0096 Phase C)를 무효화한다. 미지정 시 tag
+     * 무효화 생략(layout 만) — 그러면 `fetchTheme`·`fetchBusinessProfile` 등의
+     * Data Cache 엔트리는 각자의 `revalidate` 초만큼 낡은 값을 계속 낸다.
+     * **주입을 권장한다.**
+     *
+     * **즉시 만료 프로파일을 넘겨라** — `(tag) => revalidateTag(tag, { expire: 0 })`.
+     * Next 는 `expire: 0` 이 아닌 프로파일을 stale-while-revalidate 업데이트로
+     * 취급해 다음 요청이 여전히 낡은 값을 받는다(`"max"` 는 expire 가 1년이라 즉시
+     * 만료가 아니다). `updateTag` 는 서버 액션 전용이어서 이 라우트에서는 throw
+     * 한다 — 쓰지 마라.
      */
     revalidateTag?: (tag: string) => void | Promise<void>;
     /** 테마 fetch 캐시 tag 이름. 기본 "rt-theme"(cms-client `THEME_CACHE_TAG`). */
@@ -407,6 +424,8 @@ interface PostSeoOverrides {
     canonical?: string;
     /** OG 이미지 — 비면 글 대표 이미지 사용. */
     ogImage?: string;
+    /** OG 이미지 대체 텍스트 — 비면 글 제목 사용. */
+    ogImageAlt?: string;
     /** 색인 제외. */
     noindex?: boolean;
     /** 링크 추적 제외. */
@@ -508,6 +527,11 @@ interface PostLocaleOptions {
 interface RobotsMeta {
     index: boolean;
     follow: boolean;
+    googleBot?: {
+        index: boolean;
+        follow: boolean;
+        "max-image-preview": "large";
+    };
 }
 /**
  * noindex/nofollow 플래그 → `Metadata.robots`. **글과 아카이브가 공유하는 단

package/dist/routes.js

@@ -7,7 +7,7 @@ import {
   resolvePostUrl,
   safeFetchPosts,
   trimSlash
-} from "./chunk-U2IM6OCQ.js";
+} from "./chunk-HM5VP7SR.js";
 
 // src/routes.ts
 import { CMS_CLIENT_VERSION } from "@roottale/cms-client/server";
@@ -56,7 +56,9 @@ function buildPostMetadata(post, options = {}) {
   if (post.section) openGraph.section = post.section;
   if (post.tags && post.tags.length > 0) openGraph.tags = [...post.tags];
   if (post.authors && post.authors.length > 0) openGraph.authors = [...post.authors];
-  if (ogImage) openGraph.images = [{ url: ogImage, alt: title }];
+  if (ogImage) {
+    openGraph.images = [{ url: ogImage, alt: seo?.ogImageAlt || title }];
+  }
   const meta = { title, openGraph };
   if (description) meta.description = description;
   if (canonical) {
@@ -80,11 +82,21 @@ function buildPostMetadata(post, options = {}) {
       }
     };
   }
-  const robots = resolveRobotsMeta({
+  const baseRobots = resolveRobotsMeta({
     ...seo?.noindex !== void 0 && { noindex: seo.noindex },
     ...seo?.nofollow !== void 0 && { nofollow: seo.nofollow }
   });
-  if (robots) meta.robots = robots;
+  const index = baseRobots?.index ?? true;
+  const follow = baseRobots?.follow ?? true;
+  meta.robots = {
+    index,
+    follow,
+    googleBot: {
+      index,
+      follow,
+      "max-image-preview": "large"
+    }
+  };
   if (post.id) meta.other = { "rt:content-id": post.id };
   const twitter = { card: "summary_large_image", title };
   if (description) twitter.description = description;
@@ -405,6 +417,7 @@ function createFeedRoute(config) {
       feedUrl: `${siteUrl}/feed.xml`,
       description: config.description,
       language: config.language,
+      hubUrl: config.webSubHubUrl,
       items: rssItemsFromPosts(posts, {
         postUrl: (p) => inCollectionMode ? resolvePostUrl3(siteUrl, p, collections) ?? `${siteUrl}${blogBase}/${p.slug}` : `${siteUrl}${blogBase}/${p.slug}`
       })
@@ -520,6 +533,10 @@ function createLlmsTxtRoute(config) {
 }
 
 // src/routes-revalidate.ts
+import {
+  SETTINGS_CACHE_TAGS,
+  THEME_CACHE_TAG
+} from "@roottale/cms-client/server";
 import {
   verifyRootTaleWebhook
 } from "@roottale/cms-client/webhook";
@@ -549,15 +566,56 @@ function createRevalidateRoute(config) {
       return Response.json({ ok: false, reason: result.reason }, { status: 401 });
     }
     if (result.event === "theme.updated") {
-      const themeTag = config.themeTag ?? "rt-theme";
-      if (config.revalidateTag) await config.revalidateTag(themeTag);
-      await config.revalidate("/", "layout");
-      return Response.json({
-        ok: true,
-        event: result.event,
-        deliveryId: result.deliveryId,
-        revalidated: { tag: config.revalidateTag ? themeTag : null, layout: "/" }
-      });
+      const themeTag = config.themeTag ?? THEME_CACHE_TAG;
+      const requestedTags = [
+        .../* @__PURE__ */ new Set([
+          themeTag,
+          ...SETTINGS_CACHE_TAGS.filter((t) => t !== THEME_CACHE_TAG)
+        ])
+      ];
+      const paths2 = pathsFromBody(rawBody);
+      const failed = [];
+      const attempt = async (target, run) => {
+        try {
+          await run();
+        } catch (e) {
+          const reason = e instanceof Error ? e.message : String(e);
+          failed.push({ target, reason });
+          console.error(
+            `[@roottale/cms-renderer-next/routes] theme.updated \uBB34\uD6A8\uD654 \uC2E4\uD328(${target}):`,
+            reason
+          );
+        }
+      };
+      if (config.revalidateTag) {
+        const revalidateTag = config.revalidateTag;
+        for (const tag of requestedTags) {
+          await attempt(`tag:${tag}`, () => revalidateTag(tag));
+        }
+      }
+      await attempt("layout:/", () => config.revalidate("/", "layout"));
+      for (const p of paths2) {
+        await attempt(`path:${p}`, () => config.revalidate(p));
+      }
+      return Response.json(
+        {
+          ok: failed.length === 0,
+          event: result.event,
+          deliveryId: result.deliveryId,
+          revalidated: {
+            // `tag` 는 테마 tag 만 담는 기존 필드(로그 호환).
+            tag: config.revalidateTag ? themeTag : null,
+            // 콜백에 **넘긴** tag 목록이다. 콜백이 실제로 무엇을 지웠는지는 이
+            // 라우트가 알 수 없다(Next 가 결과를 돌려주지 않는다) — 실패한 것만
+            // `failed` 로 구분된다. `revalidateTag` 미주입이면 빈 배열.
+            requestedTags: config.revalidateTag ? requestedTags : [],
+            layout: "/",
+            paths: paths2
+          },
+          ...failed.length > 0 ? { failed } : {}
+        },
+        { status: failed.length === 0 ? 200 : 500 }
+      );
     }
     const INVARIANTS = [
       "/feed.xml",
@@ -830,7 +888,7 @@ function createFleetInfoRoute(config = {}) {
         site: config.site ?? env.VERCEL_PROJECT_PRODUCTION_URL ?? null,
         framework: "next",
         cms_client: CMS_CLIENT_VERSION,
-        cms_renderer: true ? "0.51.1" : "dev",
+        cms_renderer: true ? "0.53.0" : "dev",
         build_sha: env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) ?? null
       },
       { headers: { "cache-control": "public, max-age=300" } }