@roottale/cms-mcp 0.61.1 → 0.63.0

package/docs/api-reference.md

@@ -5,6 +5,9 @@ description: 공개 API raw 엔드포인트 — JS 외 스택이나 저수준
 
 # HTTP API 레퍼런스
 
+팝업·배너의 v2 결정 조회와 수정안·예약·일시 중지 API는
+[팝업·배너와 예약 표시](popups-and-banners.md)를 참고하세요.
+
 베이스 URL: `https://api.roottale.com`
 인증: 모든 요청에 `Authorization: Bearer rtlk_cust_...` 헤더.
 

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/content-models-and-exposures.md

@@ -314,6 +314,10 @@ const internalLinks = await fetchInternalContentPathIndex({ apiKey, revalidate:
 
 ## 노출 슬롯과 캠페인
 
+전용 관리 화면과 예약 시작·종료, 수정안 저장 및 공통 Next.js runtime 연결은
+[팝업·배너와 예약 표시](popups-and-banners.md)를 따릅니다. 아래 단일 슬롯 조회는
+이전 연동과의 호환용입니다.
+
 노출 슬롯은 FRONT의 사이트 콘텐츠 계약에서 옵니다. 관리 API로 슬롯을 만들거나
 수정할 수 없습니다.
 
@@ -325,7 +329,8 @@ const internalLinks = await fetchInternalContentPathIndex({ apiKey, revalidate:
 
 생성은 항상 초안입니다. 수정·발행·보관은 `version`을 확인합니다. 발행 응답의
 `overlap`은 같은 슬롯·경로·기간에 겹치는 캠페인 수와 ID를 알려 줍니다. 겹침은
-오류가 아니며, 공개 FRONT는 우선순위와 최신순 규칙으로 한 건을 선택합니다.
+오류가 아닙니다. 새 공통 runtime은 같은 위치의 유효한 항목을 순서대로 캐러셀로
+표시합니다. 아래 호환용 단일 조회는 우선순위와 최신순으로 한 건을 선택합니다.
 
 ```json
 {

package/docs/popups-and-banners.md

@@ -0,0 +1,198 @@
+---
+title: 팝업·배너와 예약 표시
+description: 모든 ROOT-ADMIN 고객 사이트의 전용 운영 메뉴, 예약·종료와 Next.js 공통 표시 코드
+---
+
+# 팝업·배너와 예약 표시
+
+ROOT-ADMIN의 `콘텐츠 > 팝업·배너`에서 팝업과 배너를 관리합니다. 작성 권한이 있는
+모든 고객사에 두 메뉴를 제공합니다. 홈페이지 연결은 제작자가 담당하며, 고객이
+API 키나 예약 작업을 설정할 필요는 없습니다.
+
+## 운영 화면
+
+편집 화면은 `내용`, `표시 기간`, `표시할 페이지`로 구성됩니다. 표시할 페이지는
+메인 홈으로 고정되어 있으며, 하위 페이지에서는 팝업과 배너가 나타나지 않습니다. 이미지 선택·업로드,
+문구와 링크, PC·모바일 미리보기를 한 화면에서 사용할 수 있습니다. PC 이미지와
+모바일 이미지를 따로 선택할 수 있고, 이미지의 핵심 내용을 대체 텍스트로 입력합니다.
+
+기간은 `지금 / 예약 시작`과 `종료 없음 / 종료일`을 각각 선택합니다. 날짜만 정하면
+시작일 자정부터 종료일이 끝날 때까지 표시합니다. 정확한 시간이 필요하면 분 단위로
+입력합니다. 화면에 안내한 시간대가 기준이며 기본은 한국 시간(`Asia/Seoul`)입니다.
+`7일간`은 시작일을 포함한 7일입니다. 9월 20일에 시작하면 9월 26일이 끝날 때 종료합니다.
+
+`임시 저장`과 `수정안 저장`은 홈페이지에 반영하지 않습니다. 공개 버튼을 누르면
+현재 내용과 일정이 반영됩니다. 이미 공개한 항목의 수정안을 저장해도 현재 안내는
+계속 표시됩니다. `일정 변경`은 공개본의 일정만 바꾸므로 저장해 둔 문구·이미지
+수정안이 함께 발행되지 않습니다.
+
+| 상태 | 사용할 작업 |
+|---|---|
+| 초안 | 편집, 발행·예약 |
+| 예약 | 일정 변경, 예약 취소 |
+| 게시 중 | 수정안 저장, 변경 반영, 종료일 변경, 일시 중지 |
+| 일시 중지 | 편집, 유효한 기간 내 재개 |
+| 종료 | 새 초안으로 다시 사용 |
+| 보관 | 초안으로 복원 |
+
+## 자동 슬라이드와 모바일 동작
+
+같은 위치에 기간·기기 조건이 맞는 항목을 여러 개 발행하면 자동 캐러셀이 됩니다.
+기본 전환 간격은 5초이며, 순서는 우선순위·발행 시각·ID로 결정합니다. 한 위치에
+동시에 표시 가능한 항목은 최대 20개입니다. 서로 겹치지 않는 예약은 이 제한에
+합산하지 않습니다. 팝업은 한 창 안에서 순환하므로 여러 창이 겹쳐 열리지 않습니다.
+
+진행 막대와 남은 초는 **다음 슬라이드 전환까지의 시간**입니다. 행사 종료일까지의
+남은 시간을 뜻하지 않습니다. 이전·다음, 슬라이드 선택, 재생·일시정지를 제공하며,
+가리키거나 조작하는 동안에는 진행도 멈춥니다. 움직임 줄이기 설정에서는 자동 재생을
+시작하지 않고 방문자가 직접 재생할 수 있습니다.
+
+모바일에서는 가로 스와이프로 넘길 수 있습니다. 상단·하단 배너는 아래로 스크롤할 때
+숨기고 위로 스크롤하면 다시 표시하며, 본문 배너는 본문 흐름을 따릅니다. 팝업은 화면
+하단에 맞추고 닫기·오늘 그만 보기·슬라이드 조작 영역을 확보합니다.
+
+닫기와 표시 기록은 해당 사이트의 쿠키에 저장합니다. 일반 닫기는 현재 묶음을 함께
+닫고 항목의 재표시 설정을 따릅니다. `오늘 그만 보기`는 해당 위치 전체를 사이트
+시간대의 다음 자정까지 숨기므로 그날 추가된 슬라이드도 다시 열리지 않습니다.
+방문 중 한 번은 세션 쿠키를 사용하며, 이전 runtime의 localStorage/sessionStorage
+기록도 읽어서 기존 숨김 선택을 존중합니다. 로그인 계정이나 다른 기기에 공유되지는
+않습니다. 쿠키가 차단된 경우 현재 화면의 메모리 상태로 중복 표시를 막습니다.
+
+## Next.js 연결
+
+이 API는 `@roottale/cms-client`와 `@roottale/cms-renderer-next` **0.62.0 이상**을
+사용합니다. 실제 위치가 배치된 사이트만 연결 완료로 봅니다. 전체 예제는
+`examples/nextjs`에 있으며 실제 신규 사이트 생성 템플릿에도 포함됩니다.
+
+1. 서버 전용 `/api/exposures` 경로를 만듭니다.
+2. 최상위 공개 레이아웃에 Provider와 상단·하단·팝업 위치를 배치합니다.
+3. 홈 본문의 원하는 위치에 본문 배너를 배치합니다.
+4. 실제 위치 계약을 제작자의 인증된 배포·provisioning 과정에서 동기화합니다.
+
+```ts
+// app/api/exposures/route.ts — CMS 키는 서버 환경 변수에만 보관합니다.
+import { createExposureRoute } from "@roottale/cms-renderer-next/routes";
+
+export const dynamic = "force-dynamic";
+export const GET = createExposureRoute({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  siteId: process.env.ROOTTALE_SITE_ID,
+  slots: ["site-banner", "home-banner", "site-bottom-banner", "site-popup"],
+  homePaths: ["/"],
+});
+```
+
+```tsx
+"use client";
+import { usePathname } from "next/navigation";
+import { RootTaleExposureProvider, RootTaleExposureSlot } from "@roottale/cms-renderer-next/exposures";
+
+const slots = ["site-banner", "home-banner", "site-bottom-banner", "site-popup"];
+
+export function SiteExposures({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname();
+  return <RootTaleExposureProvider endpoint="/api/exposures" pathname={pathname ?? "/"} slots={slots} homePaths={["/"]}>
+    <RootTaleExposureSlot slotKey="site-banner" placement="top" allowedVariants={["card"]} />
+    {children}
+    <RootTaleExposureSlot slotKey="site-bottom-banner" placement="bottom" allowedVariants={["card"]} />
+    <RootTaleExposureSlot slotKey="site-popup" placement="popup" allowedVariants={["card", "image-card"]} />
+  </RootTaleExposureProvider>;
+}
+
+// 위 Provider 내부의 실제 홈 본문에 배치합니다.
+export function HomeBanner() {
+  return <RootTaleExposureSlot slotKey="home-banner" placement="inline" allowedVariants={["card", "image-card"]} />;
+}
+```
+
+루트 레이아웃에서 `@roottale/cms-renderer-next/styles`를 한 번 불러옵니다. 기존
+공지바는 상단 슬롯의 `fallback`으로 전달하면 새 배너와 중복되지 않습니다. 기존
+공지바의 하위 페이지 표시 범위는 유지하며, 새 ROOT-ADMIN 안내만 홈 전용입니다. 고정
+상담 버튼·하단 내비게이션은 Provider의 `--rt-exposure-bottom-height`를 오프셋에
+반영합니다. 고정 헤더는 `--rt-exposure-top-height`를 사용할 수 있습니다. 모바일
+배너를 기존 고정 헤더 아래에 놓으려면 `--rt-exposure-top-offset`으로 시작 위치를 지정합니다.
+
+기본 홈 경로는 `/`입니다. 실제 언어별 홈이 있는 사이트는 `homePaths`에 `/ko`, `/en`
+같은 정확한 경로를 선언하고 Provider·조회 경로·슬롯 계약에서 같은 값을 사용합니다.
+`/en/about`은 홈이 아닙니다. `slideDurationMs`의 기본값은 `5000`,
+`hideMobileBannersOnScroll`은 기본 `true`이며 제작자가 사이트 코드에서 조정합니다.
+
+API 키, upstream 주소, site ID, 허용 슬롯은 서버 코드가 소유합니다. 브라우저가
+조회할 수 있는 값은 현재 `path`와 `device`뿐입니다. API 키를 `NEXT_PUBLIC_*`
+환경 변수나 Provider props로 넘기지 않습니다.
+
+## 예약과 캐시
+
+Next.js의 시간 기반 `revalidate` 값만으로는 예약 시각에 열린 화면이 바뀌지 않습니다.
+팝업·배너의 최종 노출 결과는 별도 `no-store` 조회를 사용합니다. 응답에는 서버의
+판단 시각, 다음 변경 시각, 유효 기한이 포함되며, 현재 표시할 항목이 없어도 다음
+예약 시작 시각을 반환합니다.
+
+Provider는 최초 진입·페이지 이동·기기 조건 변경·다음 예약 경계에서 다시 조회합니다.
+열려 있는 탭은 60초마다 변경 여부를 확인하고, 숨겨진 탭은 돌아올 때 갱신합니다.
+알고 있는 종료 시각이 지나면 표시를 종료합니다. 조회 장애나 유효 기한 만료는
+팝업·배너만 숨기며 홈페이지 본문 렌더링을 중단하지 않습니다. 저장 변경은 이 조회
+주기 안에 반영되므로 이미 열려 있는 모든 화면에 서버 푸시를 보내는 기능은 아닙니다.
+
+기존 CMS 웹훅과 `createRevalidateRoute`는 그대로 유지합니다. 발행·일시 중지·일정
+변경은 `rt-exposures` 및 관련 경로의 캐시 무효화를 통지합니다. 페이지 전체의 ISR
+설정이나 다른 CMS 캐시를 끌 필요는 없습니다.
+
+## 슬롯 계약과 연결 상태
+
+슬롯은 고객 관리 API로 만들지 않습니다. 제작자가 실제 배치한 위치의 안정된 key,
+종류, 지원 형태와 이미지 크기, `runtimeVersion: 2`, `placement`를 계약에 선언합니다.
+기존 슬롯 key는 유지합니다. 새 메타데이터가 없는 이전 계약의 checksum은 바뀌지 않습니다.
+
+```json
+{
+  "key": "site-popup", "kind": "popup", "variants": ["card", "image-card"],
+  "assetKinds": ["image"], "pathPrefixes": ["/"],
+  "repeatOptions": ["session", "day", "never"],
+  "runtimeVersion": 2, "placement": "popup", "label": "홈 팝업",
+  "homePaths": ["/"], "pathRules": [{ "path": "/", "match": "exact" }]
+}
+```
+
+`/.well-known/roottale.json`에 `createFleetInfoRoute({ exposures: { runtimeVersion: 2,
+endpoint: "/api/exposures", slots } })`를 연결하면 RootTale가 배포 상태를 대조할 수
+있습니다. 소스의 실제 위치와 서버에 등록한 계약, 이 응답이 일치해야 합니다.
+홈페이지 업데이트가 필요한 경우 관리자 메뉴와 기존 항목은 유지하되 발행을 막습니다.
+
+기존 단일 슬롯 `fetchExposure`와 `/server`의 `RootTaleExposureSlot`은 호환용입니다.
+v2 표시 조건이 있는 항목은 이전 renderer에서 노출되지 않습니다. 기존 사이트는
+Provider와 조회 경로를 함께 업데이트한 뒤 v2 계약을 등록합니다.
+
+## 작성 중 미리보기
+
+`RootTaleExposurePreview`는 한 항목의 실제 콘텐츠를 표시합니다. 여러 항목을 함께
+확인할 때는 `RootTaleExposureCarouselPreview`에 공개 DTO 형태의 `campaigns`와
+`placement`, `device`를 전달합니다. 두 미리보기 모두 API 조회·방문 기록·숨김 쿠키를
+변경하지 않으며, 캐러셀 미리보기는 같은 슬라이드 조작과 진행 표시를 사용합니다.
+관리자 기본 편집 미리보기는 현재 수정하는 한 항목을 표시합니다.
+
+## 자동화 API·MCP·CLI
+
+관리 API는 `expected_version`으로 동시 수정을 검사합니다. 수정안을 저장할 때는
+`POST /v1/cms/exposures/{id}/draft`, 일정만 바꿀 때는 `POST .../{id}/schedule`을
+사용합니다. `POST .../{id}/pause`, `/resume`, `/cancel`, `/duplicate`, `/restore`도
+같은 버전 검사를 합니다. `POST /v1/cms/exposures/preview`는 저장 없이 조건을 확인합니다.
+수정 미리보기에는 `exposure_id`(MCP에서는 `exposureId`)를 전달하면 기존 항목을
+미리보기 내용으로 대체하여 다른 발행 항목과의 실제 순서를 확인합니다.
+공개 조회는 `GET /v1/cms/public/exposure-decisions?slot_keys=...&path=...&device=desktop`입니다.
+
+MCP에는 `saveCmsExposureDraft`, `updateCmsExposureSchedule`, `pauseCmsExposure`,
+`resumeCmsExposure`, `cancelCmsExposureReservation`, `duplicateCmsExposure`,
+`restoreCmsExposure`, `previewCmsExposure`가 추가됩니다. MCP·CLI 입력은 camelCase,
+HTTP API의 콘텐츠와 `delivery`·`schedule` 필드는 snake_case입니다.
+
+```bash
+npx @roottale/cms-mcp cli exposures save-draft <id> --input-file draft.json
+npx @roottale/cms-mcp cli exposures schedule <id> --input-file schedule.json
+npx @roottale/cms-mcp cli exposures pause <id> --expected-version 7
+npx @roottale/cms-mcp cli exposures preview --input-file preview.json
+```
+
+`exposures:write`는 작성·수정안 저장에, `exposures:publish`는 공개본 변경에 필요합니다.
+기존 `PATCH /v1/cms/exposures/{id}`는 공개본 수정 의미를 유지하므로 수정안 저장에는
+사용하지 않습니다. 다른 고객사·사이트의 미디어는 연결할 수 없습니다.

package/docs/revalidation-webhooks.md

@@ -5,6 +5,10 @@ description: 글 발행/수정 시 사이트 캐시를 near-real-time으로 갱
 
 # 발행 웹훅 — 캐시 자동 갱신
 
+팝업·배너의 예약 시작·종료는 [별도 노출 runtime](popups-and-banners.md)이
+처리합니다. 아래 웹훅은 저장 변경에 따른 캐시 무효화 계약이며 시간 경과 자체가
+웹훅을 발생시키지는 않습니다.
+
 어드민에서 글을 발행/수정/삭제하면 RootTale이 고객 사이트의 revalidate
 엔드포인트로 **ES256 서명된 웹훅**을 보냅니다. 사이트는 서명을 검증하고
 `revalidatePath`를 호출해 즉시 갱신합니다.

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/.well-known/roottale.json/route.ts

@@ -1,4 +1,6 @@
-// RootTale fleet 프로브 — 운영 측이 배포 버전·헬스를 확인하는 well-known 라우트.
 import { createFleetInfoRoute } from "@roottale/cms-renderer-next/routes";
+import { EXPOSURE_SLOTS } from "../../../lib/exposure-slots";
 
-export const GET = createFleetInfoRoute({ site: "example" });
+export const GET = createFleetInfoRoute({
+  exposures: { runtimeVersion: 2, endpoint: "/api/exposures", slots: EXPOSURE_SLOTS },
+});

package/examples/nextjs/app/api/exposures/route.ts

@@ -0,0 +1,10 @@
+import { createExposureRoute } from "@roottale/cms-renderer-next/routes";
+import { EXPOSURE_HOME_PATHS, EXPOSURE_SLOTS } from "../../../lib/exposure-slots";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request: Request): Promise<Response> {
+  const apiKey = process.env.ROOTTALE_API_KEY;
+  if (!apiKey) return new Response(null, { status: 503, headers: { "Cache-Control": "no-store" } });
+  return createExposureRoute({ apiKey, siteId: process.env.ROOTTALE_SITE_ID, slots: EXPOSURE_SLOTS, homePaths: EXPOSURE_HOME_PATHS })(request);
+}

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/layout.tsx

@@ -1,5 +1,6 @@
 // root layout — 렌더러 스타일은 여기서 1회 import (getting-started.md).
 import "@roottale/cms-renderer-next/styles";
+import { SiteExposures } from "../components/site-exposures";
 
 import {
   BUSINESS_CACHE_TAG,
@@ -43,7 +44,7 @@ export default async function RootLayout({
             }}
           />
         ) : null}
-        {children}
+        <SiteExposures>{children}</SiteExposures>
       </body>
     </html>
   );

package/examples/nextjs/app/page.tsx

@@ -0,0 +1,5 @@
+import { HomeBanner } from "../components/site-exposures";
+
+export default function HomePage() {
+  return <main><h1>홈페이지</h1><HomeBanner /><p>사이트 소개와 소식을 확인하세요.</p></main>;
+}

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/examples/nextjs/cms/exposure-slots.json

@@ -0,0 +1,127 @@
+[
+  {
+    "key": "site-banner",
+    "kind": "banner",
+    "variants": [
+      "card"
+    ],
+    "assetKinds": [
+      "image"
+    ],
+    "pathPrefixes": [
+      "/"
+    ],
+    "repeatOptions": [
+      "always",
+      "session",
+      "day",
+      "never"
+    ],
+    "runtimeVersion": 2,
+    "placement": "top",
+    "label": "홈 상단",
+    "homePaths": [
+      "/"
+    ],
+    "pathRules": [
+      {
+        "path": "/",
+        "match": "exact"
+      }
+    ]
+  },
+  {
+    "key": "home-banner",
+    "kind": "banner",
+    "variants": [
+      "card",
+      "image-card"
+    ],
+    "assetKinds": [
+      "image"
+    ],
+    "pathPrefixes": [
+      "/"
+    ],
+    "repeatOptions": [
+      "always",
+      "session",
+      "day",
+      "never"
+    ],
+    "runtimeVersion": 2,
+    "placement": "inline",
+    "label": "홈 본문",
+    "pathRules": [
+      {
+        "path": "/",
+        "match": "exact"
+      }
+    ],
+    "homePaths": [
+      "/"
+    ]
+  },
+  {
+    "key": "site-bottom-banner",
+    "kind": "banner",
+    "variants": [
+      "card"
+    ],
+    "assetKinds": [
+      "image"
+    ],
+    "pathPrefixes": [
+      "/"
+    ],
+    "repeatOptions": [
+      "always",
+      "session",
+      "day",
+      "never"
+    ],
+    "runtimeVersion": 2,
+    "placement": "bottom",
+    "label": "홈 하단",
+    "homePaths": [
+      "/"
+    ],
+    "pathRules": [
+      {
+        "path": "/",
+        "match": "exact"
+      }
+    ]
+  },
+  {
+    "key": "global-popup",
+    "kind": "popup",
+    "variants": [
+      "card",
+      "image-card"
+    ],
+    "assetKinds": [
+      "image"
+    ],
+    "pathPrefixes": [
+      "/"
+    ],
+    "repeatOptions": [
+      "session",
+      "day",
+      "never"
+    ],
+    "runtimeVersion": 2,
+    "placement": "popup",
+    "label": "홈 팝업",
+    "homePaths": [
+      "/"
+    ],
+    "pathRules": [
+      {
+        "path": "/",
+        "match": "exact"
+      }
+    ]
+  }
+]

package/examples/nextjs/components/global-popup.tsx

@@ -1,13 +1,13 @@
-import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/server";
+"use client";
 
-export async function GlobalPopup({ path }: { path: string }) {
+import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/exposures";
+
+export function GlobalPopup() {
   return (
     <RootTaleExposureSlot
-      apiKey={process.env.ROOTTALE_API_KEY!}
       slotKey="global-popup"
-      path={path}
+      placement="popup"
       allowedVariants={["card", "image-card"]}
-      revalidate={60}
     />
   );
 }

package/examples/nextjs/components/site-exposures.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { RootTaleExposureProvider, RootTaleExposureSlot } from "@roottale/cms-renderer-next/exposures";
+import { EXPOSURE_HOME_PATHS, EXPOSURE_SLOTS } from "../lib/exposure-slots";
+import { GlobalPopup } from "./global-popup";
+
+export function SiteExposures({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname();
+  return (
+    <RootTaleExposureProvider endpoint="/api/exposures" pathname={pathname ?? "/"} slots={EXPOSURE_SLOTS} homePaths={EXPOSURE_HOME_PATHS}>
+      <RootTaleExposureSlot slotKey="site-banner" placement="top" allowedVariants={["card"]} />
+      {children}
+      <RootTaleExposureSlot slotKey="site-bottom-banner" placement="bottom" allowedVariants={["card"]} />
+      <GlobalPopup />
+    </RootTaleExposureProvider>
+  );
+}
+
+export function HomeBanner() {
+  return <RootTaleExposureSlot slotKey="home-banner" placement="inline" allowedVariants={["card", "image-card"]} />;
+}

package/examples/nextjs/lib/exposure-slots.ts

@@ -0,0 +1,3 @@
+// 실제로 배치한 위치만 선언합니다. API 키는 이 파일에 넣지 않습니다.
+export const EXPOSURE_SLOTS = ["site-banner", "home-banner", "site-bottom-banner", "global-popup"] as const;
+export const EXPOSURE_HOME_PATHS = ["/"] as const;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.61.1",
+  "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": {