@zeropress/build-core 0.1.14 → 0.1.16

package/src/api/build-site.js

@@ -9,7 +9,6 @@ import { ZeroPressEngine } from '../render/zeropress-engine.js';
 const DEFAULT_OPTIONS = {
   assetHashing: true,
   generateSpecialFiles: true,
-  injectHtmx: true,
   writeManifest: false,
 };
 
@@ -18,7 +17,10 @@ const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD';
 const DEFAULT_TIME_FORMAT = 'HH:mm';
 const DEFAULT_TIMEZONE = 'UTC';
 const DEFAULT_LOCALE = 'en-US';
+const COMMENT_POLICY_OUTPUT_PATH = '_zeropress/comment-policy.json';
 const OUTPUT_PATH_CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F]/;
+const SAFE_MEDIA_PROTOCOLS = new Set(['http:', 'https:']);
+const SAFE_LINK_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);
 export async function buildSite(input) {
   const options = { ...DEFAULT_OPTIONS, ...(input.options || {}) };
   const state = await createBuildState(input, options);
@@ -58,6 +60,14 @@ export async function buildSite(input) {
     await writeOutput(state.writer, state.summaries, assetOutput.path, assetOutput.content, assetOutput.contentType);
   }
 
+  await writeOutput(
+    state.writer,
+    state.summaries,
+    COMMENT_POLICY_OUTPUT_PATH,
+    state.commentPolicyContent,
+    'application/json',
+  );
+
   if (options.generateSpecialFiles) {
     await maybeRenderNotFoundPage(state);
     if (hasCanonicalSiteUrl(state.previewData.site.url)) {
@@ -77,14 +87,13 @@ async function createBuildState(input, options) {
   }
 
   assertPreviewData(input.previewData);
-  await assertValidThemePackage(input.themePackage);
+  const themePackage = await normalizeAndValidateThemePackage(input.themePackage);
 
   const engine = new ZeroPressEngine();
   const assetProcessor = new AssetProcessor();
   const summaries = [];
-  const themePackage = input.themePackage;
   const previewData = normalizePreviewData(input.previewData);
-  const renderData = createRenderData(previewData);
+  const renderData = createRenderData(previewData, themePackage.metadata);
 
   engine.initialize(themePackage);
 
@@ -101,13 +110,14 @@ async function createBuildState(input, options) {
     writer: input.writer,
     previewData,
     renderData,
-    renderedWidgets: renderWidgetAreas(previewData, renderData),
+    widgets: resolveWidgetAreas(previewData, renderData),
     engine,
     assetProcessor,
     summaries,
     assetOutputs,
     assetMap,
     customCssHref: customCssAsset ? `/${customCssAsset.path}` : '',
+    commentPolicyContent: buildCommentPolicyManifest(renderData.posts),
     options,
     generatedAt: new Date(),
     emitted: {
@@ -149,7 +159,7 @@ async function renderRoute(state, templateName, route) {
     templateName,
     {
       menus: state.previewData.menus,
-      widgets: state.renderedWidgets,
+      widgets: state.widgets,
       ...route,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -172,7 +182,7 @@ async function renderPost(state, post) {
     'post',
     {
       menus: state.previewData.menus,
-      widgets: state.renderedWidgets,
+      widgets: state.widgets,
       post,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -188,9 +198,6 @@ async function renderPost(state, post) {
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
   html = injectCustomCssAssetLink(html, state.customCssHref);
-  if (state.options.injectHtmx) {
-    html = injectHtmxScript(html);
-  }
   await writeOutput(state.writer, state.summaries, `posts/${encodeSlugSegment(post.slug)}/index.html`, html, 'text/html');
   state.emitted.posts.push({
     url: currentUrl,
@@ -208,7 +215,7 @@ async function renderPage(state, page) {
     'page',
     {
       menus: state.previewData.menus,
-      widgets: state.renderedWidgets,
+      widgets: state.widgets,
       page,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -240,7 +247,7 @@ async function maybeRenderNotFoundPage(state) {
     '404',
     {
       menus: state.previewData.menus,
-      widgets: state.renderedWidgets,
+      widgets: state.widgets,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl: '/404.html',
         title: state.previewData.site.title,
@@ -320,7 +327,7 @@ function normalizeWidgetAreas(widgetAreas, mediaBaseUrl) {
 function normalizeWidgetItem(item, mediaBaseUrl) {
   const normalizedItem = {
     ...item,
-    title: normalizeNonEmptyString(item?.title, 'Widget'),
+    title: typeof item?.title === 'string' ? item.title.trim() : '',
   };
 
   if (item?.type === 'profile' && item?.settings && typeof item.settings === 'object') {
@@ -341,7 +348,8 @@ function normalizeCustomCss(customCss) {
   return content ? { content } : undefined;
 }
 
-function createRenderData(previewData) {
+function createRenderData(previewData, themeMetadata = {}) {
+  const themeSupportsComments = themeMetadata?.features?.comments === true;
   const authorsById = new Map(previewData.content.authors.map((author) => [author.id, author]));
   const categoriesBySlug = new Map(previewData.content.categories.map((category) => [category.slug, category]));
   const tagsBySlug = new Map(previewData.content.tags.map((tag) => [tag.slug, tag]));
@@ -362,11 +370,14 @@ function createRenderData(previewData) {
     }
   }
 
-  const posts = previewData.content.posts.map((post) => preparePost(post, previewData.site, authorsById, categoriesBySlug, tagsBySlug));
+  const preparedPosts = previewData.content.posts.map((post) => preparePost(post, previewData.site, authorsById, categoriesBySlug, tagsBySlug, themeSupportsComments));
+  const posts = preparedPosts.map((post, index) => ({
+    ...post,
+    prev: index > 0 ? buildAdjacentPostSummary(preparedPosts[index - 1]) : null,
+    next: index < preparedPosts.length - 1 ? buildAdjacentPostSummary(preparedPosts[index + 1]) : null,
+  }));
   const pages = previewData.content.pages.map((page) => preparePage(page));
   const postBySlug = new Map(posts.map((post) => [post.slug, post]));
-  const categoryLinks = renderCategoryLinks(previewData.content.categories, categoryCountBySlug);
-  const tagLinks = renderTagLinks(previewData.content.tags, tagCountBySlug);
 
   return {
     posts,
@@ -380,10 +391,8 @@ function createRenderData(previewData) {
       path: entry.path,
       page: entry.page,
       totalPages: entry.totalPages,
-      posts: renderPostList(entry.items, postBySlug),
-      categories: categoryLinks,
-      tags: tagLinks,
-      pagination: renderPagination(entry.paginationData),
+      posts: buildStructuredPostCollection(entry.items, postBySlug),
+      pagination: buildStructuredPagination(entry.paginationData),
     })),
     archiveRoutes: buildPaginatedCollection({
       items: previewData.content.posts,
@@ -393,29 +402,35 @@ function createRenderData(previewData) {
       path: entry.path,
       page: entry.page,
       totalPages: entry.totalPages,
-      posts: renderArchive(entry.items, postBySlug),
-      pagination: renderPagination(entry.paginationData),
+      archive: {
+        groups: buildArchiveGroups(entry.items, postBySlug),
+      },
+      pagination: buildStructuredPagination(entry.paginationData),
     })),
     categoryRoutes: buildTaxonomyRoutes({
       items: previewData.content.categories,
       postsBySlug: categoryPostsBySlug,
+      postBySlug,
       postsPerPage: previewData.site.postsPerPage,
       buildBasePath: (category) => `/categories/${encodeSlugSegment(category.slug)}/`,
-      renderList: (postsForRoute) => renderPostList(postsForRoute, postBySlug),
-      renderExtras: () => ({ categories: categoryLinks }),
+      renderExtras: (category) => ({
+        taxonomy: buildTaxonomyRouteData('category', category, categoryCountBySlug),
+      }),
     }),
     tagRoutes: buildTaxonomyRoutes({
       items: previewData.content.tags,
       postsBySlug: tagPostsBySlug,
+      postBySlug,
       postsPerPage: previewData.site.postsPerPage,
       buildBasePath: (tag) => `/tags/${encodeSlugSegment(tag.slug)}/`,
-      renderList: (postsForRoute) => renderPostList(postsForRoute, postBySlug),
-      renderExtras: () => ({ tags: tagLinks }),
+      renderExtras: (tag) => ({
+        taxonomy: buildTaxonomyRouteData('tag', tag, tagCountBySlug),
+      }),
     }),
   };
 }
 
-function renderWidgetAreas(previewData, renderData) {
+function resolveWidgetAreas(previewData, renderData) {
   if (!previewData.widgets || typeof previewData.widgets !== 'object') {
     return {};
   }
@@ -423,243 +438,223 @@ function renderWidgetAreas(previewData, renderData) {
   return Object.fromEntries(
     Object.entries(previewData.widgets).map(([widgetAreaId, widgetArea]) => [
       widgetAreaId,
-      renderWidgetArea(widgetArea, previewData, renderData, widgetAreaId),
+      resolveWidgetArea(widgetArea, previewData, renderData, widgetAreaId),
     ]),
   );
 }
 
-function renderWidgetArea(widgetArea, previewData, renderData, widgetAreaId) {
-  if (!widgetArea || !Array.isArray(widgetArea.items) || widgetArea.items.length === 0) {
-    return '';
+function resolveWidgetArea(widgetArea, previewData, renderData, widgetAreaId) {
+  if (!widgetArea || !Array.isArray(widgetArea.items)) {
+    return {
+      name: normalizeNonEmptyString(widgetArea?.name, widgetAreaId),
+      items: [],
+    };
   }
 
-  return widgetArea.items
-    .map((item, index) => renderWidgetItem(item, previewData, renderData, widgetAreaId, index))
-    .filter(Boolean)
-    .join('\n');
+  return {
+    name: normalizeNonEmptyString(widgetArea?.name, widgetAreaId),
+    items: widgetArea.items
+      .map((item, index) => resolveWidgetItem(item, previewData, renderData, widgetAreaId, index))
+      .filter(Boolean),
+  };
 }
 
-function renderWidgetItem(item, previewData, renderData, widgetAreaId, index) {
-  if (!item || typeof item !== 'object') {
-    return '';
+function resolveWidgetItem(item, previewData, renderData, widgetAreaId, index) {
+  if (!item || typeof item !== 'object' || typeof item.type !== 'string') {
+    return null;
   }
 
-  const title = normalizeNonEmptyString(item.title, 'Widget');
+  const baseWidget = {
+    id: `${widgetAreaId}-${index + 1}`,
+    type: item.type,
+    title: typeof item.title === 'string' ? item.title : '',
+    empty: false,
+  };
 
   switch (item.type) {
     case 'recent-posts':
-      return renderRecentPostsWidget(title, item.settings, renderData);
+      return resolveRecentPostsWidget(baseWidget, item.settings, renderData);
     case 'categories':
-      return renderCategoriesWidget(title, item.settings, previewData);
+      return resolveCategoriesWidget(baseWidget, item.settings, previewData);
     case 'tags':
-      return renderTagsWidget(title, item.settings, previewData);
+      return resolveTagsWidget(baseWidget, item.settings, previewData);
     case 'archives':
-      return renderArchivesWidget(title, item.settings, previewData);
-    case 'image':
-      return renderImageWidget(title, item.settings);
+      return resolveArchivesWidget(baseWidget, item.settings, previewData);
     case 'text':
-      return renderTextWidget(title, item.settings);
+      return resolveTextWidget(baseWidget, item.settings);
     case 'link-list':
-      return renderLinkListWidget(title, item.settings);
+      return resolveLinkListWidget(baseWidget, item.settings);
     case 'search':
-      return renderSearchWidget(title, item.settings, widgetAreaId, index);
+      return resolveSearchWidget(baseWidget, item.settings, widgetAreaId, index);
     case 'profile':
-      return renderProfileWidget(title, item.settings);
+      return resolveProfileWidget(baseWidget, item.settings);
     default:
-      return '';
+      return null;
   }
 }
 
-function renderRecentPostsWidget(title, settings, renderData) {
+function resolveRecentPostsWidget(baseWidget, settings, renderData) {
   const limit = clampInteger(settings?.limit, 5, 1, 20);
-  const showDate = settings?.show_date !== false;
   const items = renderData.posts
     .slice(0, limit)
-    .map((post) => {
-      const dateMeta = showDate
-        ? `<span class="widget-list__meta">${escapeHtml(post.published_at)}</span>`
-        : '';
-
-      return `<li class="widget-list__item"><a href="/posts/${escapeHtml(encodeSlugSegment(post.slug))}/">${escapeHtml(post.title)}</a>${dateMeta}</li>`;
-    })
-    .join('');
+    .map((post) => ({
+      title: post.title,
+      url: `/posts/${encodeSlugSegment(post.slug)}/`,
+      published_at: post.published_at,
+      published_at_iso: post.published_at_iso,
+    }));
 
-  if (!items) {
-    return '';
+  if (items.length === 0) {
+    return null;
   }
 
-  return renderWidgetCard(title, 'recent-posts', `<ul class="widget-list">${items}</ul>`);
+  return {
+    ...baseWidget,
+    show_date: settings?.show_date !== false,
+    items,
+  };
 }
 
-function renderCategoriesWidget(title, settings, previewData) {
+function resolveCategoriesWidget(baseWidget, settings, previewData) {
   const countBySlug = buildTaxonomyCountMap(previewData.content.posts, 'category_slugs');
   const items = previewData.content.categories
-    .map((category) => {
-      const count = countBySlug.get(category.slug) || 0;
-      if (count === 0) {
-        return '';
-      }
-
-      const suffix = settings?.show_count === true ? ` <span class="widget-taxonomy__count">(${count})</span>` : '';
-      return `<a href="/categories/${escapeHtml(encodeSlugSegment(category.slug))}/" class="category-link">${escapeHtml(category.name)}${suffix}</a>`;
-    })
-    .filter(Boolean)
-    .join('');
+    .map((category) => ({
+      name: category.name,
+      slug: category.slug,
+      url: `/categories/${encodeSlugSegment(category.slug)}/`,
+      count: countBySlug.get(category.slug) || 0,
+      depth: 0,
+    }))
+    .filter((category) => category.count > 0);
 
-  if (!items) {
-    return '';
+  if (items.length === 0) {
+    return null;
   }
 
-  return renderWidgetCard(title, 'categories', `<div class="taxonomy-list taxonomy-list--stack widget-taxonomy">${items}</div>`);
+  return {
+    ...baseWidget,
+    show_count: settings?.show_count === true,
+    hierarchical: settings?.hierarchical === true,
+    items,
+  };
 }
 
-function renderTagsWidget(title, settings, previewData) {
+function resolveTagsWidget(baseWidget, settings, previewData) {
   const countBySlug = buildTaxonomyCountMap(previewData.content.posts, 'tag_slugs');
   const limit = clampInteger(settings?.limit, 20, 1, 100);
   const items = previewData.content.tags
     .map((tag) => ({
-      ...tag,
+      name: tag.name,
+      slug: tag.slug,
+      url: `/tags/${encodeSlugSegment(tag.slug)}/`,
       count: countBySlug.get(tag.slug) || 0,
     }))
     .filter((tag) => tag.count > 0)
-    .slice(0, limit)
-    .map((tag) => {
-      const suffix = settings?.show_count === true ? ` <span class="widget-taxonomy__count">(${tag.count})</span>` : '';
-      return `<a href="/tags/${escapeHtml(encodeSlugSegment(tag.slug))}/" class="tag-link">${escapeHtml(tag.name)}${suffix}</a>`;
-    })
-    .join('');
+    .slice(0, limit);
 
-  if (!items) {
-    return '';
+  if (items.length === 0) {
+    return null;
   }
 
-  return renderWidgetCard(title, 'tags', `<div class="taxonomy-list widget-taxonomy">${items}</div>`);
+  return {
+    ...baseWidget,
+    show_count: settings?.show_count === true,
+    items,
+  };
 }
 
-function renderArchivesWidget(title, settings, previewData) {
+function resolveArchivesWidget(baseWidget, settings, previewData) {
   const limit = clampInteger(settings?.limit, 12, 1, 120);
-  const archiveEntries = buildArchiveEntries(previewData.content.posts, previewData.site).slice(0, limit);
-  const items = archiveEntries
-    .map((entry) => `<li class="widget-list__item"><a href="/archive/">${escapeHtml(entry.label)}</a><span class="widget-list__meta">${entry.count} posts</span></li>`)
-    .join('');
-
-  if (!items) {
-    return '';
-  }
-
-  return renderWidgetCard(title, 'archives', `<ul class="widget-list">${items}</ul>`);
-}
+  const items = buildArchiveEntries(previewData.content.posts, previewData.site)
+    .slice(0, limit)
+    .map((entry) => ({
+      label: entry.label,
+      url: '/archive/',
+      count: entry.count,
+      year: entry.year,
+      month: entry.month,
+      meta: `${entry.count} posts`,
+    }));
 
-function renderImageWidget(title, settings) {
-  const src = normalizeOptionalString(settings?.src);
-  if (!src) {
-    return '';
+  if (items.length === 0) {
+    return null;
   }
 
-  const alt = escapeHtml(normalizeOptionalString(settings?.alt));
-  const caption = normalizeOptionalString(settings?.caption);
-  const href = normalizeOptionalString(settings?.href);
-  const target = normalizeLinkTarget(settings?.target);
-  const rel = target === '_blank' ? ' rel="noreferrer noopener"' : '';
-  const image = `<img class="widget-image__media" src="${escapeHtml(src)}" alt="${alt}">`;
-  const linkedImage = href ? `<a href="${escapeHtml(href)}" target="${target}"${rel}>${image}</a>` : image;
-  const captionHtml = caption ? `<figcaption class="widget-image__caption">${escapeHtml(caption)}</figcaption>` : '';
-
-  return renderWidgetCard(title, 'image', `<figure class="widget-image">${linkedImage}${captionHtml}</figure>`);
+  return {
+    ...baseWidget,
+    items,
+  };
 }
 
-function renderTextWidget(title, settings) {
+function resolveTextWidget(baseWidget, settings) {
   const content = typeof settings?.content === 'string' ? settings.content : '';
   const html = renderDocumentContent(content, normalizeDocumentType(settings?.document_type));
+
   if (!normalizeOptionalString(html)) {
-    return '';
+    return null;
   }
 
-  return renderWidgetCard(title, 'text', `<div class="widget-copy">${html}</div>`);
+  return {
+    ...baseWidget,
+    html,
+  };
 }
 
-function renderLinkListWidget(title, settings) {
-  const links = Array.isArray(settings?.links) ? settings.links : [];
-  const items = links
+function resolveLinkListWidget(baseWidget, settings) {
+  const items = (Array.isArray(settings?.links) ? settings.links : [])
     .map((link) => {
       const label = normalizeOptionalString(link?.label);
-      const url = normalizeOptionalString(link?.url);
+      const url = normalizeThemeLinkUrl(link?.url);
       if (!label || !url) {
-        return '';
+        return null;
       }
 
       const target = normalizeLinkTarget(link?.target);
-      const rel = target === '_blank' ? ' rel="noreferrer noopener"' : '';
-      return `<a href="${escapeHtml(url)}" target="${target}"${rel}>${escapeHtml(label)}</a>`;
+      return {
+        label,
+        url,
+        target,
+        rel: target === '_blank' ? 'noreferrer noopener' : '',
+      };
     })
-    .filter(Boolean)
-    .join('');
+    .filter(Boolean);
 
-  if (!items) {
-    return '';
+  if (items.length === 0) {
+    return null;
   }
 
-  return renderWidgetCard(title, 'link-list', `<div class="taxonomy-list taxonomy-list--stack widget-link-list">${items}</div>`);
+  return {
+    ...baseWidget,
+    items,
+  };
 }
 
-function renderSearchWidget(title, settings, widgetAreaId, index) {
-  const placeholder = escapeHtml(normalizeNonEmptyString(settings?.placeholder, 'Search...'));
-  const buttonLabel = escapeHtml(normalizeNonEmptyString(settings?.button_label, 'Search'));
-  const searchId = `widget-search-${widgetAreaId}-${index + 1}`;
-
-  return renderWidgetCard(title, 'search', [
-    '<div class="widget-search" data-search-root>',
-    `  <label class="sr-only" for="${escapeHtml(searchId)}">${escapeHtml(title)}</label>`,
-    '  <form class="search-theme-wrapper" data-search-form>',
-    `    <input id="${escapeHtml(searchId)}" class="search-input" data-theme-search type="search" placeholder="${placeholder}" autocomplete="off" enterkeyhint="search">`,
-    `    <button class="widget-search-button" type="submit">${buttonLabel}</button>`,
-    '  </form>',
-    '  <div class="search-results" data-search-results hidden></div>',
-    '  <p class="search-feedback search-feedback--sidebar" data-search-feedback aria-live="polite"></p>',
-    '</div>',
-  ].join('\n'));
+function resolveSearchWidget(baseWidget, settings, widgetAreaId, index) {
+  return {
+    ...baseWidget,
+    placeholder: normalizeNonEmptyString(settings?.placeholder, 'Search...'),
+    button_label: normalizeNonEmptyString(settings?.button_label, 'Search'),
+    dom_id: `widget-search-${widgetAreaId}-${index + 1}`,
+  };
 }
 
-function renderProfileWidget(title, settings) {
+function resolveProfileWidget(baseWidget, settings) {
   const displayName = normalizeOptionalString(settings?.display_name);
   const affiliation = normalizeOptionalString(settings?.affiliation);
-  const bioShort = normalizeOptionalString(settings?.bio_short);
-  const avatar = normalizeOptionalString(settings?.avatar);
-
-  if (!displayName && !bioShort && !avatar) {
-    return '';
-  }
-
-  const avatarHtml = avatar
-    ? `<img class="widget-profile__avatar" src="${escapeHtml(avatar)}" alt="${escapeHtml(displayName || title)}">`
-    : '';
-  const affiliationHtml = affiliation ? `<p class="widget-profile__affiliation">${escapeHtml(affiliation)}</p>` : '';
-  const bioHtml = bioShort ? `<p class="sidebar-copy">${escapeHtml(bioShort)}</p>` : '';
-
-  return renderWidgetCard(title, 'profile', [
-    '<div class="widget-profile">',
-    avatarHtml,
-    '  <div class="widget-profile__body">',
-    displayName ? `    <p class="widget-profile__name">${escapeHtml(displayName)}</p>` : '',
-    affiliationHtml ? `    ${affiliationHtml}` : '',
-    bioHtml ? `    ${bioHtml}` : '',
-    '  </div>',
-    '</div>',
-  ].filter(Boolean).join('\n'));
-}
+  const bioText = normalizeOptionalString(settings?.bio_short);
+  const avatarUrl = normalizeMediaField(settings?.avatar);
 
-function renderWidgetCard(title, modifier, body) {
-  if (!normalizeOptionalString(body)) {
-    return '';
+  if (!displayName && !affiliation && !bioText && !avatarUrl) {
+    return null;
   }
 
-  return [
-    `<section class="content-card sidebar-card widget-card widget-card--${escapeHtml(modifier)}">`,
-    '  <p class="section-kicker">Widget</p>',
-    `  <h2>${escapeHtml(title)}</h2>`,
-    `  ${body}`,
-    '</section>',
-  ].join('\n');
+  return {
+    ...baseWidget,
+    display_name: displayName,
+    affiliation,
+    avatar_url: avatarUrl,
+    bio_text: bioText,
+  };
 }
 
 function preparePage(page) {
@@ -672,66 +667,68 @@ function preparePage(page) {
   };
 }
 
-function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug) {
+function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, themeSupportsComments) {
   const documentType = normalizeDocumentType(post.document_type);
   const html = renderDocumentContent(post.content, documentType);
   const author = authorsById.get(post.author_id);
+  const categories = post.category_slugs
+    .map((slug) => categoriesBySlug.get(slug))
+    .filter(Boolean)
+    .map((category) => ({
+      name: category.name,
+      slug: category.slug,
+      url: `/categories/${encodeSlugSegment(category.slug)}/`,
+    }));
+  const tags = post.tag_slugs
+    .map((slug) => tagsBySlug.get(slug))
+    .filter(Boolean)
+    .map((tag) => ({
+      name: tag.name,
+      slug: tag.slug,
+      url: `/tags/${encodeSlugSegment(tag.slug)}/`,
+    }));
 
   return {
-    ...post,
+    public_id: post.public_id,
+    title: post.title,
+    slug: post.slug,
+    url: `/posts/${encodeSlugSegment(post.slug)}/`,
+    content: post.content,
     document_type: documentType,
+    excerpt: post.excerpt,
+    published_at_iso: post.published_at_iso,
+    updated_at_iso: post.updated_at_iso,
+    author_id: post.author_id,
+    featured_image: post.featured_image,
+    status: post.status,
+    allow_comments: post.allow_comments,
+    category_slugs: post.category_slugs,
+    tag_slugs: post.tag_slugs,
+    author: {
+      id: post.author_id,
+      display_name: normalizeNonEmptyString(author?.display_name, post.author_id),
+      avatar: author?.avatar || '',
+    },
+    categories,
+    tags,
     html,
-    author_name: normalizeNonEmptyString(author?.display_name, post.author_id),
-    author_avatar: author?.avatar,
     published_at: formatTimestamp(post.published_at_iso, site),
     updated_at: formatTimestamp(post.updated_at_iso, site),
     reading_time: calculateReadingTime(html),
-    categories_html: renderInlineTaxonomyLinks(post.category_slugs, categoriesBySlug, 'category'),
-    tags_html: renderInlineTaxonomyLinks(post.tag_slugs, tagsBySlug, 'tag'),
-    comments_html: renderCommentsContainer(site, post),
+    comments_enabled: themeSupportsComments && site.disallowComments !== true && post.allow_comments === true,
   };
 }
 
-function renderCommentsContainer(site, post) {
-  if (site.disallowComments === true || post.allow_comments !== true) {
-    return '';
-  }
+function buildCommentPolicyManifest(posts) {
+  const commentablePosts = posts
+    .filter((post) => post.status === 'published' && post.comments_enabled === true)
+    .map((post) => post.public_id)
+    .filter((value) => Number.isInteger(value) && value > 0);
 
-  const safePostId = encodeURIComponent(post.id);
-  return `<section id="comments" class="zp-comments">
-  <h2>댓글</h2>
-  <div id="comment-list"
-       hx-get="/api/comments/${safePostId}"
-       hx-trigger="load"
-       hx-swap="innerHTML">
-    <p class="zp-comments-loading">댓글을 불러오는 중...</p>
-  </div>
-  <form id="comment-form"
-        hx-post="/api/comments/${safePostId}"
-        hx-target="#comment-form-result"
-        hx-swap="innerHTML">
-    <div id="comment-form-result"></div>
-    <div>
-      <label for="author_name">이름</label>
-      <input type="text" id="author_name" name="author_name" required>
-    </div>
-    <div>
-      <label for="author_email">이메일</label>
-      <input type="email" id="author_email" name="author_email" required>
-    </div>
-    <div>
-      <label for="content">댓글</label>
-      <textarea id="content" name="content" required minlength="1" maxlength="5000"></textarea>
-    </div>
-    <div style="position:absolute;left:-9999px;" aria-hidden="true">
-      <input type="text" name="website" tabindex="-1" autocomplete="off">
-    </div>
-    <button type="submit">댓글 작성</button>
-  </form>
-  <noscript>
-    <p>댓글 기능을 사용하려면 JavaScript를 활성화해 주세요.</p>
-  </noscript>
-</section>`;
+  return JSON.stringify({
+    version: 1,
+    commentable_posts: commentablePosts,
+  }, null, 2);
 }
 
 function buildTaxonomyRoutes(options) {
@@ -755,8 +752,8 @@ function buildTaxonomyRoutes(options) {
         slug: item.slug,
         page: entry.page,
         totalPages: entry.totalPages,
-        posts: options.renderList(entry.items),
-        pagination: renderPagination(entry.paginationData),
+        posts: buildStructuredPostCollection(entry.items, options.postBySlug),
+        pagination: buildStructuredPagination(entry.paginationData),
         ...options.renderExtras(item),
       });
     }
@@ -788,6 +785,12 @@ function buildPaginatedCollection(options) {
   return pages;
 }
 
+function buildStructuredPostCollection(posts, postBySlug) {
+  return {
+    items: buildStructuredPostItems(posts, postBySlug),
+  };
+}
+
 function buildPaginatedPath(basePath, page) {
   const normalizedBasePath = normalizePaginationBasePath(basePath);
   if (page <= 1) {
@@ -828,124 +831,99 @@ function buildPaginationData(currentPage, totalPages, totalPosts, basePath) {
   };
 }
 
-function renderPostList(posts, postBySlug) {
-  if (posts.length === 0) {
-    return '<p>No posts</p>';
-  }
+function buildStructuredPagination(paginationData) {
+  return {
+    current_page: paginationData.currentPage,
+    total_pages: paginationData.totalPages,
+    total_items: paginationData.totalPosts,
+    has_prev: paginationData.hasPrev,
+    has_next: paginationData.hasNext,
+    has_multiple_pages: paginationData.totalPages > 1,
+    prev_url: paginationData.prevUrl || '',
+    next_url: paginationData.nextUrl || '',
+    pages: paginationData.pages.map((page) => ({
+      number: page.number,
+      url: page.url,
+      current: page.current,
+    })),
+  };
+}
 
+function buildStructuredPostItems(posts, postBySlug) {
   return posts
-    .map((post) => {
-      const prepared = postBySlug.get(post.slug);
-      if (!prepared) {
-        return '';
-      }
-
-      return [
-        '<article class="post-list-item">',
-        `  <h2><a href="/posts/${escapeHtml(encodeSlugSegment(post.slug))}/">${escapeHtml(post.title)}</a></h2>`,
-        `  <div class="post-meta"><time datetime="${escapeHtml(prepared.published_at_iso)}">${escapeHtml(prepared.published_at)}</time> • ${escapeHtml(prepared.reading_time)}</div>`,
-        `  <div class="post-excerpt">${escapeHtml(prepared.excerpt)}</div>`,
-        '</article>',
-      ].join('\n');
-    })
+    .map((post) => postBySlug.get(post.slug))
     .filter(Boolean)
-    .join('\n');
+    .map((post) => buildStructuredPostSummary(post));
 }
 
-function renderArchive(posts, postBySlug) {
-  if (posts.length === 0) {
-    return '<p>No posts</p>';
-  }
-
-  const groups = new Map();
-
-  for (const post of posts) {
-    const key = `${toDate(post.published_at_iso).getUTCFullYear()}-${String(toDate(post.published_at_iso).getUTCMonth() + 1).padStart(2, '0')}`;
-    const items = groups.get(key) || [];
-    items.push(post);
-    groups.set(key, items);
-  }
-
-  return Array.from(groups.entries())
-    .map(([key, groupPosts]) => {
-      const items = groupPosts
-        .map((post) => {
-          const prepared = postBySlug.get(post.slug);
-          if (!prepared) {
-            return '';
-          }
-
-          return `<li><a href="/posts/${escapeHtml(encodeSlugSegment(post.slug))}/">${escapeHtml(post.title)}</a> <time datetime="${escapeHtml(prepared.published_at_iso)}">${escapeHtml(prepared.published_at)}</time></li>`;
-        })
-        .filter(Boolean)
-        .join('\n');
-
-      return `<section class="archive-group"><h2>${escapeHtml(key)}</h2><ul>${items}</ul></section>`;
-    })
-    .join('\n');
+function buildStructuredPostSummary(post) {
+  return {
+    title: post.title,
+    slug: post.slug,
+    url: post.url,
+    excerpt: post.excerpt,
+    published_at: post.published_at,
+    published_at_iso: post.published_at_iso,
+    reading_time: post.reading_time,
+    featured_image: post.featured_image,
+    author: {
+      display_name: post.author?.display_name || '',
+      avatar: post.author?.avatar || '',
+    },
+    categories: Array.isArray(post.categories) ? post.categories.map((category) => ({ ...category })) : [],
+    tags: Array.isArray(post.tags) ? post.tags.map((tag) => ({ ...tag })) : [],
+  };
 }
 
-function renderCategoryLinks(categories, countBySlug) {
-  return categories
-    .map((category) => {
-      const count = countBySlug.get(category.slug) || 0;
-      if (count === 0) {
-        return null;
-      }
+function buildAdjacentPostSummary(post) {
+  if (!post) {
+    return null;
+  }
 
-      return `<a href="/categories/${escapeHtml(encodeSlugSegment(category.slug))}/" class="category-link">${escapeHtml(category.name)} (${count})</a>`;
-    })
-    .filter(Boolean)
-    .join('\n');
+  return {
+    title: post.title,
+    slug: post.slug,
+    url: post.url,
+    excerpt: post.excerpt,
+    published_at: post.published_at,
+    published_at_iso: post.published_at_iso,
+  };
 }
 
-function renderTagLinks(tags, countBySlug) {
-  return tags
-    .map((tag) => {
-      const count = countBySlug.get(tag.slug) || 0;
-      if (count === 0) {
-        return null;
-      }
+function buildArchiveGroups(posts, postBySlug) {
+  const groups = new Map();
 
-      return `<a href="/tags/${escapeHtml(encodeSlugSegment(tag.slug))}/" class="tag-link">${escapeHtml(tag.name)} (${count})</a>`;
-    })
-    .filter(Boolean)
-    .join('\n');
-}
+  for (const post of posts) {
+    const prepared = postBySlug.get(post.slug);
+    if (!prepared?.published_at_iso) {
+      continue;
+    }
 
-function renderInlineTaxonomyLinks(slugs, taxonomyBySlug, kind) {
-  const links = slugs
-    .map((slug) => taxonomyBySlug.get(slug))
-    .filter(Boolean)
-    .map((item) => {
-      const base = kind === 'category' ? '/categories/' : '/tags/';
-      const className = kind === 'category' ? 'category-link' : 'tag-link';
-      return `<a href="${base}${escapeHtml(encodeSlugSegment(item.slug))}/" class="${className}">${escapeHtml(item.name)}</a>`;
-    });
+    const date = toDate(prepared.published_at_iso);
+    const year = date.getUTCFullYear();
+    const month = date.getUTCMonth() + 1;
+    const label = `${year}-${String(month).padStart(2, '0')}`;
+    const current = groups.get(label) || {
+      label,
+      year,
+      month,
+      items: [],
+    };
 
-  if (links.length === 0) {
-    return '';
+    current.items.push(buildStructuredPostSummary(prepared));
+    groups.set(label, current);
   }
 
-  return kind === 'category' ? links.join(', ') : links.join(' ');
+  return Array.from(groups.values());
 }
 
-function renderPagination(paginationData) {
-  if (paginationData.totalPages <= 1) {
-    return '';
-  }
-
-  const prevLink = paginationData.hasPrev && paginationData.prevUrl
-    ? `<a href="${paginationData.prevUrl}" class="prev">Previous</a>`
-    : '';
-  const nextLink = paginationData.hasNext && paginationData.nextUrl
-    ? `<a href="${paginationData.nextUrl}" class="next">Next</a>`
-    : '';
-  const pageLinks = paginationData.pages
-    .map((page) => `<a href="${page.url}" class="page-link ${page.current ? 'current' : ''}">${page.number}</a>`)
-    .join(' ');
-
-  return `<nav class="pagination">\n  ${prevLink}\n  <span class="pages">${pageLinks}</span>\n  ${nextLink}\n</nav>`;
+function buildTaxonomyRouteData(kind, item, countBySlug) {
+  return {
+    kind,
+    slug: item.slug,
+    name: item.name,
+    count: countBySlug.get(item.slug) || 0,
+  };
 }
 
 function buildTaxonomyCountMap(posts, fieldName) {
@@ -982,6 +960,8 @@ function buildArchiveEntries(posts, site) {
     .map((entry) => ({
       label: formatArchiveLabel(entry.date, site),
       count: entry.count,
+      year: entry.date.getUTCFullYear(),
+      month: entry.date.getUTCMonth() + 1,
     }));
 }
 
@@ -1115,7 +1095,7 @@ function recordRouteEmission(state, templateName, route, currentUrl) {
   });
 }
 
-async function assertValidThemePackage(themePackage) {
+async function normalizeAndValidateThemePackage(themePackage) {
   if (!themePackage?.templates || !themePackage?.partials || !themePackage?.assets || !themePackage?.metadata) {
     throw new Error('Invalid themePackage: expected metadata, templates, partials, and assets');
   }
@@ -1131,6 +1111,7 @@ async function assertValidThemePackage(themePackage) {
     ...(themePackage.metadata.author ? { author: themePackage.metadata.author } : {}),
     ...(themePackage.metadata.description ? { description: themePackage.metadata.description } : {}),
     ...(themePackage.metadata.thumbnail ? { thumbnail: themePackage.metadata.thumbnail } : {}),
+    ...(themePackage.metadata.features ? { features: themePackage.metadata.features } : {}),
     ...(themePackage.metadata.menuSlots ? { menuSlots: themePackage.metadata.menuSlots } : {}),
     ...(themePackage.metadata.widgetAreas ? { widgetAreas: themePackage.metadata.widgetAreas } : {}),
     settings: themePackage.metadata.settings || {},
@@ -1152,6 +1133,25 @@ async function assertValidThemePackage(themePackage) {
   if (!validation.ok) {
     throw new Error(`Theme validation failed: ${validation.errors[0]?.message || 'Unknown error'}`);
   }
+
+  if (!validation.manifest) {
+    throw new Error('Theme validation failed: normalized manifest not available');
+  }
+
+  return {
+    metadata: normalizeThemePackageMetadata(themePackage.metadata, validation.manifest),
+    templates: themePackage.templates,
+    partials: themePackage.partials,
+    assets: themePackage.assets,
+  };
+}
+
+function normalizeThemePackageMetadata(sourceMetadata, manifest) {
+  return {
+    ...manifest,
+    ...(sourceMetadata?.thumbnail ? { thumbnail: sourceMetadata.thumbnail } : {}),
+    settings: sourceMetadata?.settings || {},
+  };
 }
 
 async function buildAssetOutputs(assets, assetProcessor, options) {
@@ -1292,7 +1292,7 @@ function resolveMetaImageUrl(image) {
   }
 
   if (isAbsoluteUrl(normalizedImage)) {
-    return normalizedImage;
+    return normalizeAbsoluteUrl(normalizedImage, SAFE_MEDIA_PROTOCOLS);
   }
 
   return '';
@@ -1309,7 +1309,7 @@ function normalizeMediaField(value, mediaBaseUrl) {
   }
 
   if (isAbsoluteUrl(normalizedValue)) {
-    return normalizedValue;
+    return normalizeAbsoluteUrl(normalizedValue, SAFE_MEDIA_PROTOCOLS);
   }
 
   const normalizedBaseUrl = normalizeOptionalString(mediaBaseUrl);
@@ -1333,6 +1333,31 @@ function isAbsoluteUrl(value) {
   }
 }
 
+function normalizeAbsoluteUrl(value, allowedProtocols) {
+  try {
+    const url = new URL(value);
+    if (!allowedProtocols.has(url.protocol)) {
+      return '';
+    }
+    return decodeURI(url.toString());
+  } catch {
+    return '';
+  }
+}
+
+function normalizeThemeLinkUrl(value) {
+  const normalizedValue = normalizeOptionalString(value);
+  if (!normalizedValue || normalizedValue.startsWith('//')) {
+    return '';
+  }
+
+  if (isAbsoluteUrl(normalizedValue)) {
+    return normalizeAbsoluteUrl(normalizedValue, SAFE_LINK_PROTOCOLS);
+  }
+
+  return normalizedValue;
+}
+
 async function writeOutput(writer, summaries, path, content, contentType) {
   const rawPath = String(path || '');
   const normalizedPath = normalizeOutputPath(rawPath);
@@ -1391,6 +1416,7 @@ function assertPlannedOutputPathsSafe(state) {
     ...state.renderData.posts.map((post) => `posts/${encodeSlugSegment(post.slug)}/index.html`),
     ...state.renderData.pages.map((page) => `${encodeSlugSegment(page.slug)}/index.html`),
     ...state.assetOutputs.map((assetOutput) => assetOutput.path),
+    COMMENT_POLICY_OUTPUT_PATH,
   ];
 
   if (state.options.generateSpecialFiles) {
@@ -1465,10 +1491,6 @@ function sha256(content) {
   return hash.digest('hex');
 }
 
-function injectHtmxScript(html) {
-  return html.replace('</body>', '<script src="https://unpkg.com/htmx.org@2.0.4" crossorigin="anonymous"></script>\n</body>');
-}
-
 function injectCustomCssAssetLink(html, href) {
   if (!normalizeOptionalString(href)) {
     return html;