@roottale/cms-renderer-astro 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @roottale/cms-renderer-astro
+
+## 0.2.0
+
+### Minor Changes
+
+- d1b5d35: cms-\* public renderer 패키지 npm public publish — Phase 1 dogfood.
+
+  ADR-0029 §0 amend (publish-only dormant) 는 design system 5 패키지 (tokens, ui-css, ui-react, ui-astro, ui-admin) 에 한정. cms-\* 는 별도 정책 — 실행 로직 + 5-20 외부 customer site 직접 의존 + schema 호환 + 보안 경계. Codex consult verdict (session `019e6703…`) 정합.
+
+  변경:
+  - 4 패키지 `private: true` 해제 + `publishConfig.access: "public"`
+  - `@roottale/cms-renderer-next` 에서 `@roottale/tokens/tokens.css` import 제거 — 모든 `--rt-*` 변수에 static fallback 으로 self-contained. tokens dormant 와 무관하게 동작.
+  - `RootTaleLeadForm` RSC 추가 — 외부 사이트 진단 폼 (`vertical`/`redirectUrl` props, medical 국외이전 동의 자동).
+  - README + repository / homepage / keywords 메타 정비
+  - `peerDependencies.react: ^19` 명시 (cms-renderer-next)
+  - `cms-renderer-astro` 도 동등 surface 유지를 위해 동시 publish
+
+  후속:
+  - ADR 신규 — cms-\* publish 정책 (별 PR)
+  - Astro 측 LeadForm 컴포넌트 (현재 `@roottale/ui-astro` 위치, `cms-renderer-astro` 로 이동 검토)
+
+### Patch Changes
+
+- Updated dependencies [d1b5d35]
+  - @roottale/cms-core@0.2.0
+  - @roottale/cms-client@0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @roottale/cms-renderer-astro
+
+RootTale CMS public renderer for **Astro 6** sites — companion of [`@roottale/cms-renderer-next`](https://www.npmjs.com/package/@roottale/cms-renderer-next). Equivalent surface (`renderBlogList` / `renderBlogPost`), zero JS by default (ADR-0034 §1.5 amended).
+
+## Install
+
+```bash
+npm install @roottale/cms-renderer-astro @roottale/cms-client
+# or
+pnpm add @roottale/cms-renderer-astro @roottale/cms-client
+```
+
+## Setup
+
+```bash
+# .env — server / build-time only
+ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxx
+```
+
+## Blog list — `src/pages/blog/index.astro`
+
+```astro
+---
+import { renderBlogList } from "@roottale/cms-renderer-astro";
+
+const html = await renderBlogList({
+  apiKey: import.meta.env.ROOTTALE_API_KEY,
+  limit: 20,
+});
+---
+
+<Fragment set:html={html} />
+```
+
+## Blog post — `src/pages/blog/[slug].astro`
+
+```astro
+---
+import { renderBlogPost } from "@roottale/cms-renderer-astro";
+
+const { slug } = Astro.params;
+const html = await renderBlogPost({
+  apiKey: import.meta.env.ROOTTALE_API_KEY,
+  slugOrId: slug!,
+});
+---
+
+<Fragment set:html={html} />
+```
+
+## Other exports
+
+- `renderBlocks` — Block JSON → HTML string
+- `renderTiptapDoc` — Tiptap doc → HTML string
+- SEO helpers — `generateArticleSchema`, `generateSitemapXml`, `generateRobotsTxt`
+
+## Security
+
+Same model as the Next renderer: server/build-time only (`@roottale/cms-client` throws if used in the browser). Block JSON is rendered through hardcoded mark/node mappings — link `href` passes an allowlist; no raw HTML escape hatch for authored content.
+
+## License
+
+Proprietary (UNLICENSED). Issued under the RootTale customer contract.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@roottale/cms-renderer-astro",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "RootTale CMS Astro 6 SSG/SSR public renderer. renderBlogList / renderBlogPost helpers + Tiptap → HTML. Companion of @roottale/cms-renderer-next (ADR-0034 §1.5 amended).",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@roottale/cms-core": "^0.2.0",
+    "@roottale/cms-client": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "roottale",
+    "cms",
+    "astro",
+    "blog",
+    "renderer",
+    "ssg"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/RootTale/roottale-platform/tree/main/packages/cms-renderer-astro",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RootTale/roottale-platform.git",
+    "directory": "packages/cms-renderer-astro"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/block-to-html.ts

@@ -0,0 +1,114 @@
+// ADR-0034 §1.5 + §5 — block JSON → HTML
+//
+// Astro 가 public page 렌더링 시 본 함수로 block tree 를 server-side HTML 로 변환.
+// 7 block (paragraph/heading/image/list/quote/code/columns) Phase 1 핸들러.
+// 우리가 schema 정의 안 한 block 은 rawHtml 출력 (codex v3 verdict #4, opaque
+// atom round-trip 보존).
+
+import type { Block } from "@roottale/cms-core";
+
+/** XSS 차단: text content escape */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+/** attribute value escape (XSS) */
+function escapeAttr(value: string): string {
+  return value.replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+function renderInner(blocks: readonly Block[]): string {
+  return blocks.map((b) => renderBlock(b)).join("");
+}
+
+/**
+ * 단일 block 을 HTML 로 변환.
+ * 알려진 `core/<x>` block name 은 dedicated handler. 그 외 = rawHtml 출력
+ * (Tiptap opaque atom node 보존).
+ */
+export function renderBlock(block: Block): string {
+  switch (block.name) {
+    case "core/paragraph": {
+      const text = typeof block.attributes.content === "string"
+        ? block.attributes.content
+        : (block.rawHtml ?? "");
+      return `<p data-block-id="${escapeAttr(block._id)}">${text}</p>`;
+    }
+    case "core/heading": {
+      const levelRaw = block.attributes.level;
+      const level = typeof levelRaw === "number" && levelRaw >= 1 && levelRaw <= 6 ? levelRaw : 2;
+      const text = typeof block.attributes.content === "string"
+        ? block.attributes.content
+        : (block.rawHtml ?? "");
+      return `<h${level} data-block-id="${escapeAttr(block._id)}">${text}</h${level}>`;
+    }
+    case "core/image": {
+      const src = typeof block.attributes.url === "string"
+        ? escapeAttr(block.attributes.url)
+        : "";
+      const alt = typeof block.attributes.alt === "string"
+        ? escapeAttr(block.attributes.alt)
+        : "";
+      const caption = typeof block.attributes.caption === "string"
+        ? block.attributes.caption
+        : null;
+      const img = `<img src="${src}" alt="${alt}" loading="lazy">`;
+      const inner = caption ? `${img}<figcaption>${escapeHtml(caption)}</figcaption>` : img;
+      return `<figure data-block-id="${escapeAttr(block._id)}">${inner}</figure>`;
+    }
+    case "core/list": {
+      const ordered = block.attributes.ordered === true;
+      const tag = ordered ? "ol" : "ul";
+      const items = (block.innerBlocks ?? [])
+        .map((item) => `<li>${item.rawHtml ?? renderInner(item.innerBlocks ?? [])}</li>`)
+        .join("");
+      return `<${tag} data-block-id="${escapeAttr(block._id)}">${items}</${tag}>`;
+    }
+    case "core/quote": {
+      const inner = renderInner(block.innerBlocks ?? []);
+      const cite = typeof block.attributes.citation === "string"
+        ? `<cite>${escapeHtml(block.attributes.citation)}</cite>`
+        : "";
+      return `<blockquote data-block-id="${escapeAttr(block._id)}">${inner}${cite}</blockquote>`;
+    }
+    case "core/code": {
+      const code = typeof block.attributes.content === "string"
+        ? escapeHtml(block.attributes.content)
+        : escapeHtml(block.rawHtml ?? "");
+      const lang = typeof block.attributes.language === "string"
+        ? ` data-language="${escapeAttr(block.attributes.language)}"`
+        : "";
+      return `<pre data-block-id="${escapeAttr(block._id)}"${lang}><code>${code}</code></pre>`;
+    }
+    case "core/columns": {
+      const inner = renderInner(block.innerBlocks ?? []);
+      return `<div class="rt-columns" data-block-id="${escapeAttr(block._id)}">${inner}</div>`;
+    }
+    case "core/separator":
+      return `<hr data-block-id="${escapeAttr(block._id)}">`;
+    case "core/spacer": {
+      const heightRaw = block.attributes.height;
+      const height = typeof heightRaw === "string" ? heightRaw : "32px";
+      return `<div class="rt-spacer" data-block-id="${escapeAttr(block._id)}" style="height:${escapeAttr(height)}"></div>`;
+    }
+    case "core/group": {
+      const inner = renderInner(block.innerBlocks ?? []);
+      return `<div class="rt-group" data-block-id="${escapeAttr(block._id)}">${inner}</div>`;
+    }
+    default: {
+      // 알려지지 않은 block = opaque atom (codex v3 #4). rawHtml 출력만, 편집 X.
+      const inner = block.rawHtml ?? renderInner(block.innerBlocks ?? []);
+      return `<div class="rt-unknown-block" data-block-id="${escapeAttr(block._id)}" data-block-name="${escapeAttr(block.name)}">${inner}</div>`;
+    }
+  }
+}
+
+/** Block tree 전체를 HTML 문서 body 로 직렬화. */
+export function renderBlocks(blocks: readonly Block[]): string {
+  return blocks.map((b) => renderBlock(b)).join("\n");
+}

package/src/blog.ts

@@ -0,0 +1,156 @@
+// ADR-0034 §1.5 amended — Astro public renderer = first-class with Next.
+//
+// External Astro 사이트가 cms-client `fetchPosts`/`fetchPost` 결과를 HTML 로
+// 변환하는 helper. cms-renderer-next 의 `<RootTaleBlogList>` / `<RootTaleBlogPost>`
+// 와 동등 surface.
+//
+// 사용 예 (.astro):
+// ```astro
+// ---
+// import { renderBlogList } from "@roottale/cms-renderer-astro";
+// const html = await renderBlogList({ apiKey: import.meta.env.ROOTTALE_API_KEY! });
+// ---
+// <Fragment set:html={html} />
+// ```
+
+import {
+  fetchPost,
+  fetchPosts,
+  type CmsPostContent,
+  type CmsPostType,
+} from "@roottale/cms-client/server";
+
+import { renderTiptapDoc } from "./tiptap-to-html";
+
+/** XSS 차단: text content escape (block-to-html.ts 와 동일 정책) */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+function formatPublishedDate(iso: string): string {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return "";
+  return new Intl.DateTimeFormat("ko-KR", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(d);
+}
+
+export interface RenderBlogListOptions {
+  /** `rtlk_cust_*` API key (server-side only). */
+  apiKey: string;
+  /** Override the API base URL. Defaults to `https://api.roottale.com`. */
+  baseUrl?: string;
+  /** Page size, 1-100, default 20. */
+  limit?: number;
+  /** Filter by post type. Default `post` (blog list 의도). */
+  type?: CmsPostType;
+  /** Override the auto-resolved site id. */
+  siteId?: string;
+  /** Customer-side URL builder. Defaults to `/blog/${slug}`. */
+  postHref?: (post: CmsPostContent) => string;
+  /** Rendered when the tenant has no published posts yet. */
+  emptyMessage?: string;
+}
+
+function defaultPostHref(post: CmsPostContent): string {
+  return `/blog/${post.slug}`;
+}
+
+function renderPostCard(
+  post: CmsPostContent,
+  href: (p: CmsPostContent) => string,
+): string {
+  const date = escapeHtml(formatPublishedDate(post.publishedAt));
+  const title = escapeHtml(post.title);
+  const excerptHtml = post.excerpt
+    ? `<p class="rt-cms-excerpt">${escapeHtml(post.excerpt)}</p>`
+    : "";
+  const url = escapeAttr(href(post));
+  return (
+    `<article data-roottale-cms="card" class="rt-cms-card">` +
+    `<a class="rt-cms-card-link" href="${url}">` +
+    `<p class="rt-cms-meta">${date}</p>` +
+    `<h2 class="rt-cms-title">${title}</h2>` +
+    `${excerptHtml}` +
+    `</a></article>`
+  );
+}
+
+export async function renderBlogList(
+  options: RenderBlogListOptions,
+): Promise<string> {
+  const {
+    apiKey,
+    baseUrl,
+    limit,
+    siteId,
+    type = "post",
+    postHref = defaultPostHref,
+    emptyMessage = "아직 발행된 글이 없습니다.",
+  } = options;
+
+  const page = await fetchPosts({ apiKey, baseUrl, limit, type, siteId });
+  if (page.items.length === 0) {
+    return `<div data-roottale-cms="list"><p class="rt-cms-empty">${escapeHtml(emptyMessage)}</p></div>`;
+  }
+  const items = page.items
+    .map(
+      (post) =>
+        `<li class="rt-cms-list-item">${renderPostCard(post, postHref)}</li>`,
+    )
+    .join("");
+  return `<div data-roottale-cms="list"><ul class="rt-cms-list">${items}</ul></div>`;
+}
+
+export interface RenderBlogPostOptions {
+  apiKey: string;
+  baseUrl?: string;
+  /** Slug (kebab-case) or UUIDv7 id. */
+  slugOrId: string;
+  /** Override the auto-resolved site id. */
+  siteId?: string;
+  /** Rendered when the slug is not found or not published. */
+  notFoundHtml?: string;
+}
+
+export async function renderBlogPost(
+  options: RenderBlogPostOptions,
+): Promise<string> {
+  const { apiKey, baseUrl, slugOrId, siteId, notFoundHtml } = options;
+  const post = await fetchPost({ apiKey, baseUrl, slugOrId, siteId });
+  if (!post) {
+    return (
+      notFoundHtml ??
+      `<div data-roottale-cms="post-missing"><p class="rt-cms-empty">글을 찾을 수 없습니다.</p></div>`
+    );
+  }
+
+  const bodyHtml = renderTiptapDoc(post.bodyJson);
+  const date = escapeHtml(formatPublishedDate(post.publishedAt));
+  const title = escapeHtml(post.title);
+  const excerpt = post.excerpt
+    ? `<p class="rt-cms-excerpt">${escapeHtml(post.excerpt)}</p>`
+    : "";
+
+  return (
+    `<article data-roottale-cms="post" class="rt-cms-article">` +
+    `<header>` +
+    `<p class="rt-cms-meta">${date}</p>` +
+    `<h1 class="rt-cms-title">${title}</h1>` +
+    `${excerpt}` +
+    `</header>` +
+    `<div data-roottale-cms="body">${bodyHtml}</div>` +
+    `</article>`
+  );
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// @roottale/cms-renderer-astro — ADR-0034 §1.5 amended (Astro + Next 둘 다 1급
+// public renderer). 동등 surface = @roottale/cms-renderer-next (RSC).
+export * from "./block-to-html";
+export * from "./tiptap-to-html";
+export * from "./blog";
+export * from "./seo";
+export * from "./sitemap";
+export * from "./robots";

package/src/robots.ts

@@ -0,0 +1,39 @@
+// ADR-0034 §7.1.1 test #1 — robots.txt 자동.
+
+export interface RobotsConfig {
+  /** User-agent 별 rule. 기본 "*" */
+  rules?: Array<{
+    userAgent: string;
+    allow?: readonly string[];
+    disallow?: readonly string[];
+  }>;
+  /** sitemap.xml 의 절대 URL */
+  sitemapUrl?: string;
+  /** 기본 disallow (draft preview 등 차단) */
+  defaultDisallow?: readonly string[];
+}
+
+export function renderRobotsTxt(config: RobotsConfig = {}): string {
+  const rules = config.rules ?? [
+    {
+      userAgent: "*",
+      disallow: config.defaultDisallow ?? ["/admin", "/api/", "/preview"],
+    },
+  ];
+
+  const parts: string[] = [];
+  for (const rule of rules) {
+    parts.push(`User-agent: ${rule.userAgent}`);
+    for (const path of rule.allow ?? []) {
+      parts.push(`Allow: ${path}`);
+    }
+    for (const path of rule.disallow ?? []) {
+      parts.push(`Disallow: ${path}`);
+    }
+    parts.push("");
+  }
+  if (config.sitemapUrl) {
+    parts.push(`Sitemap: ${config.sitemapUrl}`);
+  }
+  return parts.join("\n");
+}

package/src/seo.ts

@@ -0,0 +1,99 @@
+// ADR-0034 §1 + §7.1.1 test #5 — Technical SEO 95+ 의 비타협 약속.
+//
+// Phase 1 Exit Contract test #1 + #5 + #8 (sitemap/robots/canonical 자동 주입).
+
+export interface PostSeoInput {
+  title: string;
+  description?: string | null;
+  canonicalUrl: string;
+  siteName: string;
+  ogImage?: string | null;
+  publishedAt?: Date | null;
+  modifiedAt?: Date | null;
+  authorName?: string | null;
+  locale?: string; // default "ko_KR"
+  noIndex?: boolean;
+}
+
+/**
+ * <head> 메타 태그를 HTML 문자열로 생성. Astro layout 안에서 `<head>` 내부에 inject.
+ * - title (헌장 §1 = Technical SEO 95+ 의 비타협 약속)
+ * - meta description (있는 경우)
+ * - canonical link (slug change 시 301 redirect 와 정합)
+ * - Open Graph (basic)
+ * - robots noindex (옵션)
+ * - Schema.org Article JSON-LD
+ */
+export function renderSeoHead(input: PostSeoInput): string {
+  const locale = input.locale ?? "ko_KR";
+  const parts: string[] = [];
+
+  parts.push(`<title>${escapeText(input.title)}</title>`);
+
+  if (input.description) {
+    parts.push(`<meta name="description" content="${escapeAttr(input.description)}">`);
+  }
+
+  parts.push(`<link rel="canonical" href="${escapeAttr(input.canonicalUrl)}">`);
+
+  if (input.noIndex) {
+    parts.push(`<meta name="robots" content="noindex,follow">`);
+  }
+
+  // Open Graph
+  parts.push(`<meta property="og:type" content="article">`);
+  parts.push(`<meta property="og:title" content="${escapeAttr(input.title)}">`);
+  if (input.description) {
+    parts.push(`<meta property="og:description" content="${escapeAttr(input.description)}">`);
+  }
+  parts.push(`<meta property="og:url" content="${escapeAttr(input.canonicalUrl)}">`);
+  parts.push(`<meta property="og:site_name" content="${escapeAttr(input.siteName)}">`);
+  parts.push(`<meta property="og:locale" content="${escapeAttr(locale)}">`);
+  if (input.ogImage) {
+    parts.push(`<meta property="og:image" content="${escapeAttr(input.ogImage)}">`);
+  }
+
+  // Twitter card
+  parts.push(`<meta name="twitter:card" content="${input.ogImage ? "summary_large_image" : "summary"}">`);
+  parts.push(`<meta name="twitter:title" content="${escapeAttr(input.title)}">`);
+  if (input.description) {
+    parts.push(`<meta name="twitter:description" content="${escapeAttr(input.description)}">`);
+  }
+  if (input.ogImage) {
+    parts.push(`<meta name="twitter:image" content="${escapeAttr(input.ogImage)}">`);
+  }
+
+  // Schema.org Article JSON-LD
+  const schema: Record<string, unknown> = {
+    "@context": "https://schema.org",
+    "@type": "Article",
+    headline: input.title,
+    mainEntityOfPage: input.canonicalUrl,
+  };
+  if (input.description) schema.description = input.description;
+  if (input.publishedAt) schema.datePublished = input.publishedAt.toISOString();
+  if (input.modifiedAt) schema.dateModified = input.modifiedAt.toISOString();
+  if (input.authorName) {
+    schema.author = { "@type": "Person", name: input.authorName };
+  }
+  if (input.ogImage) schema.image = input.ogImage;
+  parts.push(
+    `<script type="application/ld+json">${JSON.stringify(schema)}</script>`,
+  );
+
+  return parts.join("\n");
+}
+
+function escapeText(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeAttr(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;");
+}

package/src/sitemap.ts

@@ -0,0 +1,47 @@
+// ADR-0034 §7.1.1 test #1 — sitemap include 의무
+//
+// Per-site sitemap.xml 생성. published post/page 만 포함.
+
+export interface SitemapEntry {
+  url: string;
+  lastModified?: Date | null;
+  changeFreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+  priority?: number; // 0.0~1.0
+}
+
+/**
+ * sitemap.xml 문자열 생성 (XML 1.0).
+ * Phase 1 = flat list. Phase 2+ = index sitemap (chunk by 50k entries).
+ */
+export function renderSitemapXml(entries: readonly SitemapEntry[]): string {
+  const xmlEntries = entries
+    .map((e) => {
+      const parts = [`  <url>`, `    <loc>${escapeXml(e.url)}</loc>`];
+      if (e.lastModified) {
+        parts.push(`    <lastmod>${e.lastModified.toISOString()}</lastmod>`);
+      }
+      if (e.changeFreq) {
+        parts.push(`    <changefreq>${e.changeFreq}</changefreq>`);
+      }
+      if (typeof e.priority === "number") {
+        parts.push(`    <priority>${e.priority.toFixed(1)}</priority>`);
+      }
+      parts.push(`  </url>`);
+      return parts.join("\n");
+    })
+    .join("\n");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${xmlEntries}
+</urlset>`;
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}

package/src/tiptap-to-html.test.ts

@@ -0,0 +1,248 @@
+import { describe, expect, it } from "vitest";
+
+import { renderTiptapDoc } from "./tiptap-to-html";
+
+function doc(...content: unknown[]) {
+  return { type: "doc", content };
+}
+
+function p(...content: unknown[]) {
+  return { type: "paragraph", content };
+}
+
+function text(value: string, marks: Array<{ type: string; attrs?: Record<string, unknown> }> = []) {
+  return { type: "text", text: value, marks };
+}
+
+describe("renderTiptapDoc — node coverage", () => {
+  it("renders paragraph + heading + horizontalRule + hardBreak", () => {
+    const html = renderTiptapDoc(
+      doc(
+        { type: "heading", attrs: { level: 2 }, content: [text("타이틀")] },
+        p(text("문단")),
+        { type: "horizontalRule" },
+        p(text("위"), { type: "hardBreak" }, text("아래")),
+      ),
+    );
+    expect(html).toContain("<h2>타이틀</h2>");
+    expect(html).toContain("<p>문단</p>");
+    expect(html).toContain("<hr>");
+    expect(html).toContain("<p>위<br>아래</p>");
+  });
+
+  it("clamps heading level to 1..3 and adds id when present", () => {
+    const html = renderTiptapDoc(
+      doc(
+        { type: "heading", attrs: { level: 9 }, content: [text("clamp")] },
+        {
+          type: "heading",
+          attrs: { level: 3, id: "section-a" },
+          content: [text("with id")],
+        },
+      ),
+    );
+    expect(html).toContain("<h3>clamp</h3>");
+    expect(html).toContain('<h3 id="section-a">with id</h3>');
+  });
+
+  it("applies textAlign style on paragraph and heading", () => {
+    const html = renderTiptapDoc(
+      doc(
+        p({ ...text("center"), attrs: undefined }),
+        {
+          type: "paragraph",
+          attrs: { textAlign: "center" },
+          content: [text("center")],
+        },
+        {
+          type: "heading",
+          attrs: { level: 2, textAlign: "right" },
+          content: [text("right")],
+        },
+      ),
+    );
+    expect(html).toContain('<p style="text-align:center">center</p>');
+    expect(html).toContain('<h2 style="text-align:right">right</h2>');
+  });
+
+  it("renders lists + blockquote + codeBlock", () => {
+    const html = renderTiptapDoc(
+      doc(
+        {
+          type: "bulletList",
+          content: [
+            { type: "listItem", content: [p(text("a"))] },
+            { type: "listItem", content: [p(text("b"))] },
+          ],
+        },
+        { type: "blockquote", content: [p(text("q"))] },
+        { type: "codeBlock", content: [text("hello < world")] },
+      ),
+    );
+    expect(html).toContain("<ul><li><p>a</p></li><li><p>b</p></li></ul>");
+    expect(html).toContain("<blockquote><p>q</p></blockquote>");
+    expect(html).toContain("<pre><code>hello &lt; world</code></pre>");
+  });
+
+  it("renders image (src/alt/title/lazy) and skips missing src", () => {
+    const html = renderTiptapDoc(
+      doc(
+        {
+          type: "image",
+          attrs: {
+            src: "https://x.test/a.png",
+            alt: "alt",
+            title: "title",
+          },
+        },
+        { type: "image", attrs: {} },
+      ),
+    );
+    expect(html).toContain(
+      '<img src="https://x.test/a.png" alt="alt" title="title" loading="lazy">',
+    );
+    expect(html).not.toContain("<img>");
+  });
+
+  it("renders columns / column wrappers", () => {
+    const html = renderTiptapDoc(
+      doc({
+        type: "columns",
+        content: [
+          { type: "column", content: [p(text("L"))] },
+          { type: "column", content: [p(text("R"))] },
+        ],
+      }),
+    );
+    expect(html).toContain(
+      '<div class="rt-columns"><div class="rt-column"><p>L</p></div><div class="rt-column"><p>R</p></div></div>',
+    );
+  });
+});
+
+describe("renderTiptapDoc — mark coverage", () => {
+  it("renders bold / italic / underline / strike / code", () => {
+    const html = renderTiptapDoc(
+      doc(
+        p(
+          text("B", [{ type: "bold" }]),
+          text("I", [{ type: "italic" }]),
+          text("U", [{ type: "underline" }]),
+          text("S", [{ type: "strike" }]),
+          text("C", [{ type: "code" }]),
+        ),
+      ),
+    );
+    expect(html).toContain("<strong>B</strong>");
+    expect(html).toContain("<em>I</em>");
+    expect(html).toContain("<u>U</u>");
+    expect(html).toContain("<s>S</s>");
+    expect(html).toContain("<code>C</code>");
+  });
+
+  it("renders highlight (with and without color attr)", () => {
+    const html = renderTiptapDoc(
+      doc(
+        p(
+          text("a", [{ type: "highlight", attrs: { color: "#FEF3C7" } }]),
+          text("b", [{ type: "highlight" }]),
+        ),
+      ),
+    );
+    expect(html).toContain('<mark style="background:#FEF3C7">a</mark>');
+    expect(html).toContain("<mark>b</mark>");
+  });
+
+  it("renders textStyle only when color attr is set", () => {
+    const html = renderTiptapDoc(
+      doc(
+        p(
+          text("red", [{ type: "textStyle", attrs: { color: "#EF4444" } }]),
+          text("plain", [{ type: "textStyle" }]),
+        ),
+      ),
+    );
+    expect(html).toContain('<span style="color:#EF4444">red</span>');
+    // textStyle 가 color 없으면 wrapping 안 함 — escape 된 텍스트만 남음
+    expect(html).toContain("plain");
+    expect(html).not.toContain("<span>plain</span>");
+  });
+
+  it("blocks unsafe href schemes (javascript:/data:/vbscript:) → '#'", () => {
+    const unsafe = ["javascript:alert(1)", "JaVaScRiPt:1", "data:text/html,x", "vbscript:msgbox", "  javascript:foo  "];
+    for (const u of unsafe) {
+      const html = renderTiptapDoc(
+        doc(p(text("x", [{ type: "link", attrs: { href: u } }]))),
+      );
+      expect(html).toContain('<a href="#" rel="noopener noreferrer" target="_blank">x</a>');
+      expect(html).not.toContain("javascript:");
+      expect(html).not.toContain("data:text/html");
+      expect(html).not.toContain("vbscript:");
+    }
+  });
+
+  it("allows http(s) / mailto / tel / root-relative / fragment / query href", () => {
+    const ok = [
+      "https://x.test/",
+      "http://x.test/",
+      "mailto:a@b.com",
+      "tel:+1",
+      "/path?q=1",
+      "#section",
+      "?q=2",
+    ];
+    for (const u of ok) {
+      const html = renderTiptapDoc(
+        doc(p(text("x", [{ type: "link", attrs: { href: u } }]))),
+      );
+      expect(html).toContain(`href="${u.replace(/"/g, "&quot;")}"`);
+    }
+  });
+
+  it("renders link with rel=noopener and target=_blank", () => {
+    const html = renderTiptapDoc(
+      doc(
+        p(
+          text("click", [
+            { type: "link", attrs: { href: "https://x.test/path" } },
+          ]),
+        ),
+      ),
+    );
+    expect(html).toContain(
+      '<a href="https://x.test/path" rel="noopener noreferrer" target="_blank">click</a>',
+    );
+  });
+});
+
+describe("renderTiptapDoc — safety / edge", () => {
+  it("escapes html in text nodes", () => {
+    const html = renderTiptapDoc(doc(p(text("<script>x</script>"))));
+    expect(html).not.toContain("<script>");
+    expect(html).toContain("&lt;script&gt;x&lt;/script&gt;");
+  });
+
+  it("escapes quotes in link href attribute", () => {
+    const html = renderTiptapDoc(
+      doc(
+        p(
+          text("x", [
+            {
+              type: "link",
+              attrs: { href: 'https://x.test/"><img src=x' },
+            },
+          ]),
+        ),
+      ),
+    );
+    expect(html).not.toContain('href="https://x.test/"><img');
+    expect(html).toContain("&quot;");
+  });
+
+  it("returns empty string for malformed input", () => {
+    expect(renderTiptapDoc(undefined)).toBe("");
+    expect(renderTiptapDoc(null)).toBe("");
+    expect(renderTiptapDoc({})).toBe("");
+    expect(renderTiptapDoc({ content: "not array" })).toBe("");
+  });
+});

package/src/tiptap-to-html.ts

@@ -0,0 +1,164 @@
+// Tiptap JSON doc → HTML 문자열.
+//
+// `block-to-html.ts` (Block JSON 처리) 와 별개 — 본 파일은 admin-tenant 가
+// 저장하는 Tiptap doc (type:"doc", content:[...nodes]) 을 그대로 변환.
+// cms-renderer-next 의 `RenderTiptap` (server.tsx) 과 1:1 동등 surface.
+
+type TiptapMark = { type?: string; attrs?: Record<string, unknown> };
+type TiptapNode = {
+  type?: string;
+  text?: string;
+  attrs?: Record<string, unknown>;
+  content?: TiptapNode[];
+  marks?: TiptapMark[];
+};
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+}
+
+function escapeAttr(value: string): string {
+  return value.replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+
+/**
+ * Defense-in-depth: even though admin LinkButton.normalizeUrl filters input,
+ * legacy imports / direct DB / external tenants can still emit unsafe href.
+ * Allow only http(s)/mailto/tel/root-relative/fragment/query — falls back to "#".
+ */
+function isSafeHref(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  if (v.length === 0) return false;
+  if (v.startsWith("/") || v.startsWith("#") || v.startsWith("?")) return true;
+  return /^(https?:|mailto:|tel:)/i.test(v);
+}
+
+function alignStyleAttr(node: TiptapNode): string {
+  const a = node.attrs?.textAlign;
+  if (typeof a !== "string" || a === "" || a === "left") return "";
+  if (a === "center" || a === "right" || a === "justify") {
+    return ` style="text-align:${a}"`;
+  }
+  return "";
+}
+
+function applyMarks(marks: TiptapMark[], inner: string): string {
+  let out = inner;
+  for (const m of marks) {
+    switch (m.type) {
+      case "bold":
+        out = `<strong>${out}</strong>`;
+        break;
+      case "italic":
+        out = `<em>${out}</em>`;
+        break;
+      case "underline":
+        out = `<u>${out}</u>`;
+        break;
+      case "strike":
+        out = `<s>${out}</s>`;
+        break;
+      case "code":
+        out = `<code>${out}</code>`;
+        break;
+      case "highlight": {
+        const color = m.attrs?.color;
+        const style =
+          typeof color === "string" && color.length > 0
+            ? ` style="background:${escapeAttr(color)}"`
+            : "";
+        out = `<mark${style}>${out}</mark>`;
+        break;
+      }
+      case "textStyle": {
+        const color = m.attrs?.color;
+        if (typeof color === "string" && color.length > 0) {
+          out = `<span style="color:${escapeAttr(color)}">${out}</span>`;
+        }
+        break;
+      }
+      case "link": {
+        const raw = m.attrs?.href;
+        const safe = isSafeHref(raw) ? escapeAttr(raw) : "#";
+        out = `<a href="${safe}" rel="noopener noreferrer" target="_blank">${out}</a>`;
+        break;
+      }
+      default:
+        out = `<span>${out}</span>`;
+    }
+  }
+  return out;
+}
+
+function renderNodes(nodes: TiptapNode[]): string {
+  return nodes.map((n) => renderNode(n)).join("");
+}
+
+function renderNode(node: TiptapNode): string {
+  if (!node || typeof node !== "object") return "";
+  const children = Array.isArray(node.content) ? renderNodes(node.content) : "";
+  switch (node.type) {
+    case "paragraph":
+      return `<p${alignStyleAttr(node)}>${children}</p>`;
+    case "heading": {
+      const levelRaw = Number(node.attrs?.level ?? 2);
+      const level = Math.min(Math.max(Number.isFinite(levelRaw) ? levelRaw : 2, 1), 3);
+      const idRaw = node.attrs?.id;
+      const idAttr =
+        typeof idRaw === "string" && idRaw.length > 0
+          ? ` id="${escapeAttr(idRaw)}"`
+          : "";
+      return `<h${level}${idAttr}${alignStyleAttr(node)}>${children}</h${level}>`;
+    }
+    case "bulletList":
+      return `<ul>${children}</ul>`;
+    case "orderedList":
+      return `<ol>${children}</ol>`;
+    case "listItem":
+      return `<li>${children}</li>`;
+    case "blockquote":
+      return `<blockquote>${children}</blockquote>`;
+    case "codeBlock":
+      return `<pre><code>${children}</code></pre>`;
+    case "horizontalRule":
+      return "<hr>";
+    case "hardBreak":
+      return "<br>";
+    case "image": {
+      const src = node.attrs?.src;
+      if (typeof src !== "string" || src.length === 0) return "";
+      const alt = typeof node.attrs?.alt === "string" ? node.attrs.alt : "";
+      const title =
+        typeof node.attrs?.title === "string"
+          ? ` title="${escapeAttr(node.attrs.title)}"`
+          : "";
+      return `<img src="${escapeAttr(src)}" alt="${escapeAttr(alt)}"${title} loading="lazy">`;
+    }
+    case "columns":
+      return `<div class="rt-columns">${children}</div>`;
+    case "column":
+      return `<div class="rt-column">${children}</div>`;
+    case "text": {
+      const text = typeof node.text === "string" ? escapeHtml(node.text) : "";
+      const marks = Array.isArray(node.marks) ? node.marks : [];
+      if (marks.length === 0) return text;
+      return applyMarks(marks, text);
+    }
+    default:
+      return children ? `<span>${children}</span>` : "";
+  }
+}
+
+/** Tiptap doc (admin-tenant 저장 형식) 을 HTML 문자열로 변환. */
+export function renderTiptapDoc(doc: unknown): string {
+  if (!doc || typeof doc !== "object") return "";
+  const content = (doc as { content?: unknown }).content;
+  if (!Array.isArray(content)) return "";
+  return renderNodes(content as TiptapNode[]);
+}