@roottale/cms-mcp 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @roottale/cms-mcp
 
+## 0.63.0
+
+### Patch Changes
+
+- a858d8e: 목차 배치를 사이트 코드의 `RootTaleBlogPost.tocPosition`으로 관리할 수 있습니다.
+  명시한 값은 CMS 설정보다 우선하며, 생략한 기존 연동은 CMS 배치를 유지합니다.
+  현재 배치를 prop으로 명시하면 실제 화면을 바꾸지 않고 관리 주체를 코드로 옮깁니다.
+
+  공통 블록 디자인은 `RootTaleBlogPost.footerPatternPresentation`과
+  `RootTalePostPattern.presentation`으로 전체 대체할 수 있습니다. `null`은 원격
+  디자인 주입을 생략하고 사이트 CSS에 맡기며, 생략한 기존 연동은 원격값을 유지합니다.
+  고객 콘텐츠와 제작 디자인을 분리하는 문서·발행/미리보기 예제를 함께 갱신합니다.
+
+  공개 `RootTaleCssVars` 타입의 비공개 UI 패키지 참조도 제거해 독립 소비자의
+  strict 타입 검사를 지원합니다.
+
+  섹션 구성·디자인 변경 검사 함수를 공개 CMS core에서 공유해 편집기와 저장 단계가
+  같은 고객 편집 경계를 적용합니다.
+
 ## 0.62.0
 
 ### Minor Changes

package/dist/index.js

@@ -1735,7 +1735,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.62.0" : "dev";
+var VERSION = true ? "0.63.0" : "dev";
 var SERVER_INSTRUCTIONS = `
 roottale-cms-mcp\uB294 RootTale CMS\uB97C \uC678\uBD80 \uC0AC\uC774\uD2B8(\uC8FC\uB85C Next.js)\uC5D0 \uC5F0\uB3D9\uD558\uACE0
 \uAE00\xB7\uC378\uB124\uC77C\xB7\uBCF8\uBB38 \uC774\uBBF8\uC9C0\uB97C \uC790\uB3D9\uD654\uD558\uAE30 \uC704\uD55C \uBB38\uC11C\xB7\uC608\uC2DC \uCF54\uB4DC\xB7API tool\uC744 \uC81C\uACF5\uD569\uB2C8\uB2E4.

package/docs/blog.md

@@ -136,6 +136,9 @@ export default async function PostPage({
       slugOrId={post.id}
       showTableOfContents
       tableOfContentsTitle="목차"
+      tocPosition="inline"
+      theme={null}
+      footerPatternPresentation={null}
       relatedPostsCount={3}
       breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
     />
@@ -166,7 +169,14 @@ export default async function PostPage({
 또는 `collections` 로 라우팅됩니다. 현재 글에 카테고리가 없거나 후보가 없으면
 렌더되지 않습니다.
 
-목차(ToC)·작성자 카드·발행일 표시는 어드민의 블로그 표시 설정으로도 제어됩니다
+목차 위치는 사이트 코드의 `tocPosition="inline" | "sidebar"`로 정합니다. 명시한
+값은 CMS 설정보다 우선하며, 생략한 기존 연동은 CMS의 `tocPosition`을 유지합니다.
+관리 주체를 코드로 옮길 때는 현재 화면의 배치 값을 명시하세요. 발행 페이지와
+미리보기에는 같은 값을 적용합니다. `theme={null}`은 원격 테마 조회·스타일 주입을
+끄고, `footerPatternPresentation={null}`은 공통 블록 디자인을 사이트 CSS에 맡깁니다.
+두 prop을 생략한 기존 연동은 원격 테마·공통 블록 디자인을 계속 사용합니다.
+
+목차(ToC) 노출·작성자 카드·발행일 표시는 어드민의 블로그 표시 설정으로도 제어됩니다
 (`theme-and-settings.md` 참고). 여러 글에 같은 CTA가 필요하면 공통 블록의
 `post_footer` 자리를 쓰세요. 공통 블록으로 아직 옮기지 않은 기존 사이트는
 `RootTaleBlogPost`가 레거시 `postCta`를 계속 렌더하며, 공통 블록이 배치되면

package/docs/theme-and-settings.md

@@ -1,11 +1,12 @@
 ---
 title: 테마·블로그 표시·ROOT-ANALYTICS 설정
-description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵션, ROOT-ANALYTICS 설정을 사이트에서 조회
+description: 고객 운영 정보와 사이트 코드의 디자인 설정을 분리하고 기존 설정 API를 연동
 ---
 
 # 테마·블로그 표시·ROOT-ANALYTICS 설정
 
-어드민에서 설정한 값을 공개 API로 조회해 사이트에 반영합니다. 모두
+고객이 직접 수정할 콘텐츠·운영 정보는 CMS에서 조회하고, 디자인·레이아웃은
+사이트 코드에서 관리합니다. 기존 사이트의 호환용 디자인 API는 유지됩니다. 모두
 `@roottale/cms-client/server`에서 제공하며 같은 API 키를 사용합니다.
 
 ## 저장 즉시 반영 — 캐시 이름표(`tags`)
@@ -28,7 +29,13 @@ description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵
 쪽(웹훅 수신 라우트) 배선은 `revalidation-webhooks.md` §1 "설정 저장"을
 따르세요 — **양쪽을 다 해야** 즉시 반영이 됩니다.
 
-## 디자인 토큰 — fetchTheme
+## 기존 디자인 토큰 연동 — fetchTheme
+
+신규 사이트의 토큰은 프로젝트 CSS·코드에 둡니다. `RootTaleBlogPost`·
+`RootTaleBlogList`·`RootTalePage`·`RootTaleBlogCategories`에 `theme={null}`을 주면
+원격 테마 조회와 CSS 변수 주입을 생략합니다. 명시한 테마 객체는 코드 값을 쓰고,
+prop을 생략하면 기존 호환 동작으로 원격 테마를 조회합니다.
+아래 API는 아직 코드로 이전하지 않은 기존 연동에 사용합니다.
 
 ```ts
 import { THEME_CACHE_TAG, fetchTheme } from "@roottale/cms-client/server";
@@ -45,7 +52,9 @@ const theme = await fetchTheme({
 
 ## 상단 메뉴 — theme.siteNav
 
-같은 `fetchTheme` 응답에 어드민 **설정 > 사이트 > 상단 메뉴**에서 저장한 GNB
+상단 메뉴 구조는 제작자가 관리하는 설정입니다. 고객 콘텐츠 편집 범위에 넣지
+않으며 신규 사이트는 라우트와 함께 코드에 둡니다. 기존 연동은 같은 `fetchTheme`
+응답에 개발자용 어드민 메뉴에서 저장한 GNB
 구조가 함께 담깁니다. 별도 호출이 없고 테마와 같은 캐시 태그로 무효화됩니다.
 
 ```ts
@@ -131,11 +140,16 @@ const settings = await fetchBlogSettings({
 // 검색 제목·설명, null 이면 사이트 이름·사이트 설명으로 폴백) · logoUrl ·
 // faviconUrl · defaultOgImageUrl — 사이트 <head>/OG 폴백 (seo.md 참고)
 
-// 글 단위 오버라이드(metaJson)와 합성해 최종 표시값 계산
-const display = resolvePostDisplay(settings, post);
+// 글 단위 오버라이드(metaJson)와 합성해 노출 여부 계산
+const display = resolvePostDisplay(post, settings);
+// 자체 화면의 배치는 코드가 정합니다. display.tocPosition은 호환용 값입니다.
+const tocPosition = "inline";
 ```
 
-`RootTaleBlogPost` 컴포넌트를 쓰면 위 글 표시 설정이 자동 반영됩니다. 작성자
+`RootTaleBlogPost`는 노출 여부 설정을 자동 반영하되, 목차 배치는 코드 prop
+`tocPosition="inline" | "sidebar"`를 명시하면 CMS 배치보다 우선합니다. 생략하면
+기존 CMS 배치를 유지하므로 기존 사이트의 화면이 바뀌지 않습니다. 관리 주체를
+코드로 옮길 때 현재 배치 값을 명시하고 발행 화면과 미리보기의 prop을 일치시킵니다. 작성자
 사진의 초점은 글에 연결된 작성자 콘텐츠 값을 적용하고, 사진 모양은 사이트의
 시멘틱 토큰/CSS를 따릅니다. 레거시 `postCta`는 아래 공통 블록이 없는 기존 글에서만
 자동 반영되며, 공통 블록이 배치되면 함께 표시되지 않습니다.
@@ -177,15 +191,39 @@ const footer = selectSitePatternForSlot(post?.patternSlots, patterns);
 ```tsx
 // 자체 글 화면 + 공용 렌더러 조합
 import { RootTalePostPattern } from "@roottale/cms-renderer-next/server";
-<RootTalePostPattern apiKey={apiKey} post={post} />
+<RootTalePostPattern apiKey={apiKey} post={post} presentation={null} />
+```
+
+블록의 문구·연락처·링크는 CMS에 두고 카드·버튼·색은 사이트 코드에 둡니다.
+`RootTalePostPattern.presentation` 또는 `RootTaleBlogPost.footerPatternPresentation`에
+아래 값을 지정하세요.
+
+| 값 | 동작 |
+|---|---|
+| `null` | 원격 디자인의 data 속성·CSS 변수 주입을 생략하고 사이트 CSS 사용 |
+| `CmsSitePatternPresentation` 객체 | 원격 디자인 전체를 코드 객체로 대체(부분 병합 아님) |
+| 생략 | 기존 연동 호환을 위해 원격 `pattern.presentation` 사용 |
+
+```tsx
+<RootTaleBlogPost
+  apiKey={apiKey}
+  slugOrId={slug}
+  tocPosition="inline"
+  theme={null}
+  footerPatternPresentation={{
+    layout: "card",
+    background: "#f8f9fa",
+    linkStyle: "buttons",
+    buttonColors: ["#03c75a", "#1a1a1a"],
+  }}
+/>
 ```
 
-블록의 **표시 형태**(`presentation`: `layout` 본문처럼/카드, `background` 카드 배경색,
-`linkStyle` 글자/버튼, `buttonColors` 버튼 색 순서)도 어드민이 정해 내려줍니다. 사이트
-CSS 에 색·모양을 고정하지 말고 `sitePatternPresentationAttributes(pattern.presentation)`
-가 주는 data 속성(`data-pattern-layout`, `data-pattern-link-style`)과 CSS 변수
-(`--rt-pattern-bg`, `--rt-pattern-btn-1..n`)를 래퍼에 얹은 뒤 그 값만 읽으세요.
-`RootTaleBlogPost`·`RootTalePostPattern` 은 이미 그렇게 그립니다.
+객체를 지정하면 `data-pattern-layout`, `data-pattern-link-style`,
+`--rt-pattern-bg`, `--rt-pattern-btn-1..n`으로 전달됩니다. `null`이어도 블록 본문과
+`data-pattern-key`·`data-pattern-slot`은 유지되므로 사이트 CSS에서 선택할 수 있습니다.
+자체 렌더러도 `sitePatternPresentationAttributes`에 CMS 값 대신 프로젝트가 소유한
+디자인 객체를 넘기세요. 기존 `presentation` API 데이터는 삭제하지 않습니다.
 
 블록 목록은 `rt-site-patterns` 캐시 이름표를 가지며, 어드민에서 블록·배치 규칙을
 저장하면 `theme.updated` 웹훅이 다른 설정과 함께 지웁니다(`createRevalidateRoute`

package/examples/nextjs/app/blog/[slug]/page.tsx

@@ -85,6 +85,9 @@ export default async function PostPage({ params }: Props) {
         slugOrId={post.id}
         showTitle={false}
         showTableOfContents
+        tocPosition="inline"
+        theme={null}
+        footerPatternPresentation={null}
         relatedPostsCount={3}
         // opt-in — 시각 브레드크럼 + BreadcrumbList JSON-LD. siteUrl 없으면
         // 시각 브레드크럼만(JSON-LD 미emit).

package/examples/nextjs/app/preview/post/[id]/page.tsx

@@ -62,6 +62,9 @@ export default async function PostPreviewPage({ params, searchParams }: Props) {
         apiKey={process.env.ROOTTALE_API_KEY!}
         baseUrl={process.env.ROOTTALE_API_BASE}
         previewToken={token}
+        tocPosition="inline"
+        theme={null}
+        footerPatternPresentation={null}
         relatedPostsCount={3}
         breadcrumb={{ siteUrl: process.env.NEXT_PUBLIC_SITE_URL }}
       />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.",
   "bin": {