@zeropress/build-core 0.6.13 → 0.7.1

package/src/api/build-site.js

@@ -4,24 +4,29 @@ import { isSafeSlugSegment, normalizeStoredSlug } from '@zeropress/slug-policy';
 import { validateThemeFiles } from '@zeropress/theme-validator';
 import { AssetProcessor } from '../assets/asset-processor.js';
 import { renderDocument, renderDocumentContent } from '../render/content-renderer.js';
+import { formatThemeValidationFailure } from '../theme/format-theme-validation.js';
 import { ZeroPressEngine } from '../render/zeropress-engine.js';
 
 const DEFAULT_OPTIONS = {
   assetHashing: true,
-  generateSpecialFiles: true,
   generateFeed: true,
   generateRobotsTxt: true,
-  writeManifest: false,
 };
 
 const DEFAULT_POSTS_PER_PAGE = 10;
-const DEFAULT_DATETIME_DISPLAY = 'static';
 const DEFAULT_DATE_STYLE = 'medium';
 const DEFAULT_TIME_STYLE = 'none';
 const DEFAULT_TIMEZONE = 'UTC';
 const DEFAULT_LOCALE = 'en-US';
-const DATETIME_DISPLAY_MODES = new Set(['static', 'client']);
+const DEFAULT_COMMENTS_PROVIDER = 'zeropress';
+const DEFAULT_COMMENTS_PER_PAGE = 50;
+const DEFAULT_COMMENTS_ORDER = 'desc';
+const DEFAULT_COMMENTS_THREADING_ENABLED = true;
+const DEFAULT_COMMENTS_THREADING_MAX_DEPTH = 2;
 const DATETIME_STYLES = new Set(['none', 'short', 'medium', 'long', 'full']);
+const COMMENTS_PROVIDERS = new Set(['zeropress', 'wordpress']);
+const COMMENTS_ORDERS = new Set(['asc', 'desc']);
+const DISABLED_COMMENTS_CONTEXT = Object.freeze({ enabled: false });
 const DEFAULT_PERMALINKS = Object.freeze({
   output_style: 'directory',
   posts: '/posts/:slug/',
@@ -43,9 +48,12 @@ const SEARCH_ADAPTER_OUTPUT_PATH = '_zeropress/search.js';
 const SEARCH_PAGEFIND_ADAPTER_OUTPUT_PATH = '_zeropress/search_pagefind.js';
 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:']);
+const SAFE_LINK_PROTOCOLS = new Set(['http:', 'https:']);
 const MEDIA_DELIVERY_MODES = new Set(['none', 'media_domain']);
 const DISCOVERABILITY_VALUES = new Set(['default', 'noindex', 'delist']);
+const CUSTOM_HTML_SLOT_MAX_CODE_POINTS = 65_536;
+const HEAD_CLOSING_TAG_PATTERN = /<\/head\s*>/i;
+const BODY_CLOSING_TAG_PATTERN = /<\/body\s*>/i;
 const RESPONSIVE_IMAGE_WIDTHS = [320, 480, 768, 1024, 1280, 1600, 1920];
 const RESPONSIVE_IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif']);
 const SEARCH_FIELD_WEIGHTS = Object.freeze({
@@ -57,6 +65,7 @@ const SEARCH_FIELD_WEIGHTS = Object.freeze({
   content_text: 1,
 });
 const SEARCH_RECENCY_BOOST_MAX = 0.15;
+const RFC3339_TIMESTAMP_PATTERN = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:)(60|[0-5]\d)(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 export async function buildSite(input) {
   const options = { ...DEFAULT_OPTIONS, ...(input.options || {}) };
   const state = await createBuildState(input, options);
@@ -100,32 +109,32 @@ export async function buildSite(input) {
     await writeOutput(state.writer, state.summaries, assetOutput.path, assetOutput.content, assetOutput.contentType);
   }
 
-  if (shouldGenerateSearchArtifacts(state, options)) {
+  if (shouldGenerateSearchArtifacts(state)) {
     await writeOutput(state.writer, state.summaries, SEARCH_INDEX_OUTPUT_PATH, buildSearchIndexJson(state), 'application/json');
-    await writeOutput(state.writer, state.summaries, SEARCH_ADAPTER_OUTPUT_PATH, buildSearchAdapterJs(), 'application/javascript');
+    await writeOutput(state.writer, state.summaries, SEARCH_ADAPTER_OUTPUT_PATH, buildSearchAdapterJs(state.previewData.site.locale), 'application/javascript');
     await writeOutput(state.writer, state.summaries, SEARCH_PAGEFIND_ADAPTER_OUTPUT_PATH, buildSearchPagefindAdapterJs(), 'application/javascript');
   }
 
-  if (options.generateSpecialFiles) {
-    await maybeRenderNotFoundPage(state);
-    if (hasCanonicalSiteUrl(state.previewData.site.url)) {
-      await writeOutput(
-        state.writer,
-        state.summaries,
-        'sitemap.xml',
-        buildSitemapXml(state.previewData.site, state.emitted, state.generatedAt, options.sitemapStylesheetHref),
-        'application/xml',
-      );
-      if (shouldGenerateFeed(options)) {
-        await writeOutput(state.writer, state.summaries, 'feed.xml', buildFeedXml(state.previewData.site, state.emitted, state.generatedAt), 'application/rss+xml');
-      }
-    }
-    if (shouldGenerateRobotsTxt(options)) {
-      await writeOutput(state.writer, state.summaries, 'robots.txt', buildRobotsTxt(state.previewData.site), 'text/plain');
+  await maybeRenderNotFoundPage(state);
+  if (hasCanonicalSiteUrl(state.previewData.site.url)) {
+    await writeOutput(
+      state.writer,
+      state.summaries,
+      'sitemap.xml',
+      buildSitemapXml(state.previewData.site, state.emitted, options.sitemapStylesheetHref),
+      'application/xml',
+    );
+    if (shouldGenerateFeed(state)) {
+      await writeOutput(state.writer, state.summaries, 'feed.xml', buildFeedXml(state.previewData.site, state.emitted, state.feedGeneratedAt), 'application/rss+xml');
     }
   }
+  if (shouldGenerateRobotsTxt(options)) {
+    await writeOutput(state.writer, state.summaries, 'robots.txt', buildRobotsTxt(state.previewData.site), 'text/plain');
+  }
 
-  return finalizeBuildResult(state.writer, state.summaries, options);
+  return {
+    files: state.summaries,
+  };
 }
 
 async function createBuildState(input, options) {
@@ -140,12 +149,12 @@ async function createBuildState(input, options) {
   const assetProcessor = new AssetProcessor();
   const summaries = [];
   const previewData = normalizePreviewData(input.previewData, options);
-  const renderData = createRenderData(previewData, themePackage.metadata);
+  const renderData = createRenderData(previewData, themePackage, options);
 
   engine.initialize(themePackage);
 
-  const assetOutputs = await buildAssetOutputs(themePackage.assets, assetProcessor, options);
-  const customCssAsset = await buildCustomCssAsset(previewData.custom_css, assetProcessor, options);
+  const assetOutputs = buildAssetOutputs(themePackage.assets, assetProcessor, options);
+  const customCssAsset = buildCustomCssAsset(previewData.custom_css, assetProcessor, options);
   if (customCssAsset) {
     assetOutputs.push(customCssAsset);
   }
@@ -168,7 +177,7 @@ async function createBuildState(input, options) {
     favicon: previewData.site.favicon,
     exposeGenerator: previewData.site.expose_generator !== false,
     options,
-    generatedAt: new Date(),
+    feedGeneratedAt: toDate(previewData.generated_at),
     emitted: {
       frontPage: null,
       indexRoutes: [],
@@ -193,30 +202,9 @@ function assertBuildPreviewData(previewData) {
   }
 }
 
-async function finalizeBuildResult(writer, summaries, options) {
-  let manifest;
-  if (options.writeManifest) {
-    manifest = {
-      generatedAt: formatUtcIsoSeconds(new Date()),
-      files: summaries.map((file) => ({ ...file })),
-    };
-    await writeOutput(
-      writer,
-      summaries,
-      'build-manifest.json',
-      JSON.stringify(manifest, null, 2),
-      'application/json',
-    );
-  }
-
-  return {
-    files: summaries,
-    manifest,
-  };
-}
-
 async function renderRoute(state, templateName, route) {
   const currentUrl = routePathToPublicUrl(route.path, state.previewData.site.permalinks.output_style);
+  const outputPath = routePathToOutputPath(route.path, state.previewData.site.permalinks.output_style);
   const routeContext = buildRouteContext(route.route_type || templateName, currentUrl, {
     isFrontPage: route.is_front_page === true,
     isPostIndex: route.is_post_index === true,
@@ -242,8 +230,11 @@ async function renderRoute(state, templateName, route) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectSiteCustomizations(html, state);
-  await writeOutput(state.writer, state.summaries, routePathToOutputPath(route.path, state.previewData.site.permalinks.output_style), html, 'text/html');
+  html = injectSiteCustomizations(html, state, {
+    route: currentUrl,
+    outputPath,
+  });
+  await writeOutput(state.writer, state.summaries, outputPath, html, 'text/html');
   recordRouteEmission(state, templateName, route, currentUrl);
 }
 
@@ -288,10 +279,17 @@ async function renderFrontPage(state, route) {
           robotsNoindex: shouldNoindexDocument(page),
         }),
       },
-      createRenderContext(state.previewData.site, currentUrl),
+      createRenderContext(
+        state.previewData.site,
+        currentUrl,
+        getTargetCommentsContext(state, 'page', state.renderData.pageReferencePathByPage.get(route.page)),
+      ),
     );
     html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-    html = injectSiteCustomizations(html, state);
+    html = injectSiteCustomizations(html, state, {
+      route: currentUrl,
+      outputPath: 'index.html',
+    });
     await writeOutput(state.writer, state.summaries, 'index.html', html, 'text/html');
     state.emitted.frontPage = {
       url: currentUrl,
@@ -323,7 +321,10 @@ async function renderFrontPage(state, route) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectSiteCustomizations(html, state);
+  html = injectSiteCustomizations(html, state, {
+    route: currentUrl,
+    outputPath: 'index.html',
+  });
   await writeOutput(state.writer, state.summaries, 'index.html', html, 'text/html');
   state.emitted.frontPage = {
     url: currentUrl,
@@ -335,6 +336,7 @@ async function renderFrontPage(state, route) {
 
 async function renderPost(state, post) {
   const currentUrl = post.url;
+  const outputPath = routePathToOutputPath(post.url, state.previewData.site.permalinks.output_style);
   let html = await state.engine.render(
     'post',
     {
@@ -355,11 +357,18 @@ async function renderPost(state, post) {
         robotsNoindex: shouldNoindexDocument(post),
       }),
     },
-    createRenderContext(state.previewData.site, currentUrl),
+    createRenderContext(
+      state.previewData.site,
+      currentUrl,
+      getTargetCommentsContext(state, 'post', post.slug),
+    ),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectSiteCustomizations(html, state);
-  await writeOutput(state.writer, state.summaries, routePathToOutputPath(post.url, state.previewData.site.permalinks.output_style), html, 'text/html');
+  html = injectSiteCustomizations(html, state, {
+    route: currentUrl,
+    outputPath,
+  });
+  await writeOutput(state.writer, state.summaries, outputPath, html, 'text/html');
   if (!isDelistedDocument(post)) {
     state.emitted.posts.push({
       url: currentUrl,
@@ -395,10 +404,17 @@ async function renderPage(state, page) {
         robotsNoindex: shouldNoindexDocument(page),
       }),
     },
-    createRenderContext(state.previewData.site, currentUrl),
+    createRenderContext(
+      state.previewData.site,
+      currentUrl,
+      getTargetCommentsContext(state, 'page', state.renderData.pageReferencePathByPage.get(page)),
+    ),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectSiteCustomizations(html, state);
+  html = injectSiteCustomizations(html, state, {
+    route: currentUrl,
+    outputPath,
+  });
   await writeOutput(state.writer, state.summaries, outputPath, html, 'text/html');
   state.emitted.pages.push({
     url: currentUrl,
@@ -425,53 +441,72 @@ async function maybeRenderNotFoundPage(state) {
       route: buildRouteContext('not_found', '/404.html'),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl: '/404.html',
-        title: state.previewData.site.title,
-        description: state.previewData.site.description,
-        ogType: 'website',
+        title: buildDocumentTitle('Page Not Found', state.previewData.site.title),
+        robotsNoindex: true,
+        includeRichMetadata: false,
+        includeFeedLink: false,
       }),
     },
     createRenderContext(state.previewData.site, '/404.html'),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectSiteCustomizations(html, state);
+  html = injectSiteCustomizations(html, state, {
+    route: '/404.html',
+    outputPath: '404.html',
+  });
   await writeOutput(state.writer, state.summaries, '404.html', html, 'text/html');
 }
 
 function normalizePreviewData(previewData, options = {}) {
-  const media_base_url = normalizeOptionalString(previewData.site.media_base_url);
+  const media_origin = normalizeMediaOrigin(previewData.site.media_origin);
+  const mediaDeliveryMode = MEDIA_DELIVERY_MODES.has(previewData.site.media_delivery_mode)
+    ? previewData.site.media_delivery_mode
+    : 'none';
+  if (mediaDeliveryMode === 'media_domain' && !media_origin) {
+    throw new Error('Invalid preview-data: site.media_origin must be a non-empty HTTP(S) origin when site.media_delivery_mode is "media_domain".');
+  }
+  const {
+    search: siteSearch,
+    feed: siteFeed,
+    archive: siteArchive,
+    comments: siteComments,
+    robots: siteRobots,
+    ...siteFields
+  } = previewData.site;
+  const normalizedComments = normalizeSiteComments(siteComments);
   const normalizedSite = {
-    ...previewData.site,
-    media_base_url,
-    media_delivery_mode: MEDIA_DELIVERY_MODES.has(previewData.site.media_delivery_mode)
-      ? previewData.site.media_delivery_mode
-      : 'none',
+    ...siteFields,
+    url: normalizeSiteOrigin(previewData.site.url),
+    media_origin,
+    media_delivery_mode: mediaDeliveryMode,
     favicon: previewData.site.favicon
-      ? normalizeSiteFavicon(previewData.site.favicon, media_base_url)
+      ? normalizeSiteFavicon(previewData.site.favicon, media_origin)
       : normalizeSiteFavicon(options.favicon, ''),
-    logo: normalizeSiteLogo(previewData.site.logo, media_base_url),
+    logo: normalizeSiteLogo(previewData.site.logo, media_origin),
     newsletter: normalizeSiteNewsletter(previewData.site.newsletter),
     posts_per_page: Number.isInteger(previewData.site.posts_per_page) && previewData.site.posts_per_page > 0
       ? previewData.site.posts_per_page
       : DEFAULT_POSTS_PER_PAGE,
-    datetime_display: DATETIME_DISPLAY_MODES.has(previewData.site.datetime_display)
-      ? previewData.site.datetime_display
-      : DEFAULT_DATETIME_DISPLAY,
     date_style: DATETIME_STYLES.has(previewData.site.date_style)
       ? previewData.site.date_style
       : DEFAULT_DATE_STYLE,
     time_style: DATETIME_STYLES.has(previewData.site.time_style)
       ? previewData.site.time_style
       : DEFAULT_TIME_STYLE,
-    timezone: normalizeNonEmptyString(previewData.site.timezone, DEFAULT_TIMEZONE),
-    locale: normalizeLocale(previewData.site.locale || DEFAULT_LOCALE),
-    disallow_comments: previewData.site.disallow_comments === true,
+    timezone: normalizeTimezone(previewData.site.timezone),
+    locale: normalizeLocale(previewData.site.locale),
     expose_generator: previewData.site.expose_generator !== false,
-    search: previewData.site.search !== false,
-    indexing: previewData.site.indexing !== false,
+    search: normalizeRequestedFeatureState(siteSearch),
+    feed: normalizeRequestedFeatureState(siteFeed),
+    archive: normalizeRequestedFeatureState(siteArchive),
+    robots: {
+      allow_indexing: siteRobots?.allow_indexing !== false,
+    },
     permalinks: normalizePermalinks(previewData.site.permalinks),
     front_page: normalizeFrontPage(previewData.site.front_page),
     post_index: normalizePostIndex(previewData.site.post_index),
     footer: normalizeSiteFooter(previewData.site.footer),
+    ...(normalizedComments ? { comments: normalizedComments } : {}),
   };
   const media = normalizeContentMedia(previewData.content.media, normalizedSite);
   const mediaRegistry = buildMediaRegistry(media);
@@ -479,15 +514,15 @@ function normalizePreviewData(previewData, options = {}) {
   return {
     ...previewData,
     site: normalizedSite,
-    menus: normalizeRecordMap(previewData.menus),
+    menus: normalizeMenus(previewData.menus),
     collections: normalizeCollections(previewData.collections),
-    widgets: normalizeWidgetAreas(previewData.widgets, normalizedSite.media_base_url),
+    widgets: normalizeWidgetAreas(previewData.widgets, normalizedSite.media_origin),
     custom_css: normalizeCustomCss(previewData.custom_css),
     custom_html: normalizeCustomHtml(previewData.custom_html),
     content: {
       ...previewData.content,
       authors: previewData.content.authors.map((author) => {
-        const avatar = normalizeMediaField(author.avatar, normalizedSite.media_base_url);
+        const avatar = normalizeMediaField(author.avatar, normalizedSite.media_origin);
         const avatarMedia = deriveManagedMedia(avatar, mediaRegistry, normalizedSite);
         return {
           ...author,
@@ -497,27 +532,35 @@ function normalizePreviewData(previewData, options = {}) {
       }),
       posts: previewData.content.posts
         .map((post) => {
-          const featuredImage = normalizeMediaField(post.featured_image, normalizedSite.media_base_url);
+          const { comments, ...postFields } = post;
+          const normalizedPostComments = normalizeTargetComments(comments);
+          const featuredImage = normalizeMediaField(post.featured_image, normalizedSite.media_origin);
           const featuredMedia = deriveManagedMedia(featuredImage, mediaRegistry, normalizedSite);
           return {
-            ...post,
+            ...postFields,
             published_at_iso: normalizeIsoTimestamp(post.published_at_iso),
             updated_at_iso: normalizeIsoTimestamp(post.updated_at_iso),
+            allow_comments: post.allow_comments === true,
             discoverability: normalizeDiscoverability(post.discoverability),
             featured_image: featuredImage,
             ...(featuredMedia ? { featured_media: featuredMedia } : {}),
+            ...(normalizedPostComments ? { comments: normalizedPostComments } : {}),
           };
         })
         .sort((left, right) => toDate(right.published_at_iso).getTime() - toDate(left.published_at_iso).getTime()),
       pages: previewData.content.pages.map((page) => {
-        const featuredImage = normalizeMediaField(page.featured_image, normalizedSite.media_base_url);
+        const { comments, ...pageFields } = page;
+        const normalizedPageComments = normalizeTargetComments(comments);
+        const featuredImage = normalizeMediaField(page.featured_image, normalizedSite.media_origin);
         const featuredMedia = deriveManagedMedia(featuredImage, mediaRegistry, normalizedSite);
         return {
-          ...page,
+          ...pageFields,
           ...(page.updated_at_iso ? { updated_at_iso: normalizeIsoTimestamp(page.updated_at_iso) } : {}),
+          allow_comments: page.allow_comments === true,
           discoverability: normalizeDiscoverability(page.discoverability),
           featured_image: featuredImage,
           ...(featuredMedia ? { featured_media: featuredMedia } : {}),
+          ...(normalizedPageComments ? { comments: normalizedPageComments } : {}),
         };
       }),
       categories: [...previewData.content.categories],
@@ -535,6 +578,22 @@ function normalizeRecordMap(value) {
   return { ...value };
 }
 
+function normalizeMenus(menus) {
+  const normalized = normalizeRecordMap(menus);
+  return Object.fromEntries(Object.entries(normalized).map(([menuId, menu]) => [
+    menuId,
+    {
+      ...menu,
+      items: Array.isArray(menu?.items)
+        ? menu.items.map((item) => ({
+            ...item,
+            url: normalizeNavigationUrl(item?.url),
+          }))
+        : [],
+    },
+  ]));
+}
+
 function normalizeDiscoverability(value) {
   return DISCOVERABILITY_VALUES.has(value) ? value : 'default';
 }
@@ -557,7 +616,7 @@ function normalizeContentMedia(mediaItems, site) {
       if (!item || typeof item !== 'object') {
         return null;
       }
-      const src = normalizeMediaField(item.src, site.media_base_url);
+      const src = normalizeMediaField(item.src, site.media_origin);
       const width = Number.isInteger(item.width) && item.width > 0 ? item.width : 0;
       const height = Number.isInteger(item.height) && item.height > 0 ? item.height : 0;
       if (!src || !width || !height) {
@@ -603,8 +662,8 @@ function buildResponsiveImageSrcset(media, site) {
     return '';
   }
 
-  const media_base_url = normalizeOptionalString(site.media_base_url);
-  if (!media_base_url || !isUrlUnderMediaBase(media.src, media_base_url) || !isResponsiveRasterImage(media.src)) {
+  const media_origin = normalizeMediaOrigin(site.media_origin);
+  if (!media_origin || !isUrlAtMediaOrigin(media.src, media_origin) || !isResponsiveRasterImage(media.src)) {
     return '';
   }
 
@@ -631,12 +690,10 @@ function buildResponsiveImageVariantUrl(src, width) {
   }
 }
 
-function isUrlUnderMediaBase(src, media_base_url) {
+function isUrlAtMediaOrigin(src, media_origin) {
   try {
     const sourceUrl = new URL(src);
-    const baseUrl = new URL(media_base_url);
-    const basePath = baseUrl.pathname.endsWith('/') ? baseUrl.pathname : `${baseUrl.pathname}/`;
-    return sourceUrl.origin === baseUrl.origin && sourceUrl.pathname.startsWith(basePath);
+    return sourceUrl.origin === media_origin;
   } catch {
     return false;
   }
@@ -671,7 +728,7 @@ function normalizeCollections(collections) {
   );
 }
 
-function normalizeWidgetAreas(widget_areas, media_base_url) {
+function normalizeWidgetAreas(widget_areas, media_origin) {
   if (!widget_areas || typeof widget_areas !== 'object') {
     return {};
   }
@@ -683,7 +740,7 @@ function normalizeWidgetAreas(widget_areas, media_base_url) {
         ...widgetArea,
         name: normalizeNonEmptyString(widgetArea?.name, widgetAreaId),
         items: Array.isArray(widgetArea?.items)
-          ? widgetArea.items.map((item) => normalizeWidgetItem(item, media_base_url))
+          ? widgetArea.items.map((item) => normalizeWidgetItem(item, media_origin))
           : [],
       },
     ]),
@@ -700,7 +757,7 @@ function normalizeSiteFooter(footer) {
   };
 }
 
-function normalizeWidgetItem(item, media_base_url) {
+function normalizeWidgetItem(item, media_origin) {
   const normalizedItem = {
     ...item,
     title: typeof item?.title === 'string' ? item.title.trim() : '',
@@ -711,7 +768,7 @@ function normalizeWidgetItem(item, media_base_url) {
       ...normalizedItem,
       settings: {
         ...item.settings,
-        avatar: normalizeMediaField(item.settings.avatar, media_base_url),
+        avatar: normalizeMediaField(item.settings.avatar, media_origin),
       },
     };
   }
@@ -720,49 +777,57 @@ function normalizeWidgetItem(item, media_base_url) {
 }
 
 function normalizeCustomCss(customCss) {
-  const content = normalizeOptionalString(customCss?.content);
-  return content ? { content } : undefined;
+  const content = customCss?.content;
+  return typeof content === 'string' && content.trim() ? { content } : undefined;
 }
 
 function normalizeCustomHtml(customHtml) {
-  if (!customHtml || typeof customHtml !== 'object') {
+  if (!customHtml || typeof customHtml !== 'object' || Array.isArray(customHtml)) {
     return undefined;
   }
 
-  const headEnd = normalizeOptionalRawString(customHtml.head_end?.content);
-  const bodyEnd = normalizeOptionalRawString(customHtml.body_end?.content);
+  const headEnd = normalizeCustomHtmlSlot(customHtml.head_end);
+  const bodyEnd = normalizeCustomHtmlSlot(customHtml.body_end);
   if (!headEnd && !bodyEnd) {
     return undefined;
   }
 
   return {
-    ...(headEnd ? { head_end: { content: headEnd } } : {}),
-    ...(bodyEnd ? { body_end: { content: bodyEnd } } : {}),
+    ...(headEnd ? { head_end: headEnd } : {}),
+    ...(bodyEnd ? { body_end: bodyEnd } : {}),
   };
 }
 
-function normalizeSiteFavicon(favicon, media_base_url) {
+function normalizeCustomHtmlSlot(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    return '';
+  }
+
+  return [...value].length <= CUSTOM_HTML_SLOT_MAX_CODE_POINTS ? value : '';
+}
+
+function normalizeSiteFavicon(favicon, media_origin) {
   if (!favicon || typeof favicon !== 'object') {
     return undefined;
   }
 
   const normalized = {};
-  for (const key of ['icon', 'svg', 'png', 'apple_touch_icon']) {
+  for (const key of ['icon', 'icon_dark', 'svg', 'png', 'apple_touch_icon']) {
     const value = normalizeOptionalString(favicon[key]);
     if (value) {
-      normalized[key] = normalizeMediaField(value, media_base_url);
+      normalized[key] = normalizeMediaField(value, media_origin);
     }
   }
 
   return Object.keys(normalized).length ? normalized : undefined;
 }
 
-function normalizeSiteLogo(logo, media_base_url) {
+function normalizeSiteLogo(logo, media_origin) {
   if (!logo || typeof logo !== 'object') {
     return undefined;
   }
 
-  const src = normalizeMediaField(logo.src, media_base_url);
+  const src = normalizeMediaField(logo.src, media_origin);
   if (!src) {
     return undefined;
   }
@@ -782,8 +847,8 @@ function normalizeSiteNewsletter(newsletter) {
   const title = normalizeOptionalString(newsletter.title);
   const description = normalizeOptionalString(newsletter.description);
   const buttonLabel = normalizeOptionalString(newsletter.button_label);
-  const signupUrl = normalizeOptionalString(newsletter.signup_url);
-  const embedUrl = normalizeOptionalString(newsletter.embed_url);
+  const signupUrl = normalizeNavigationUrl(newsletter.signup_url);
+  const embedUrl = normalizeNavigationUrl(newsletter.embed_url);
 
   return {
     enabled: newsletter.enabled === true,
@@ -795,6 +860,66 @@ function normalizeSiteNewsletter(newsletter) {
   };
 }
 
+function normalizeSiteComments(comments) {
+  if (!comments || typeof comments !== 'object' || Array.isArray(comments)) {
+    return undefined;
+  }
+
+  const apiBaseUrl = normalizeCommentsApiBaseUrl(comments.api_base_url);
+  if (!apiBaseUrl) {
+    return undefined;
+  }
+
+  const threading = comments.threading && typeof comments.threading === 'object' && !Array.isArray(comments.threading)
+    ? comments.threading
+    : {};
+
+  return {
+    enabled: comments.enabled === true,
+    provider: COMMENTS_PROVIDERS.has(comments.provider)
+      ? comments.provider
+      : DEFAULT_COMMENTS_PROVIDER,
+    api_base_url: apiBaseUrl,
+    per_page: Number.isInteger(comments.per_page) && comments.per_page >= 1 && comments.per_page <= 100
+      ? comments.per_page
+      : DEFAULT_COMMENTS_PER_PAGE,
+    order: COMMENTS_ORDERS.has(comments.order)
+      ? comments.order
+      : DEFAULT_COMMENTS_ORDER,
+    threading: {
+      enabled: typeof threading.enabled === 'boolean'
+        ? threading.enabled
+        : DEFAULT_COMMENTS_THREADING_ENABLED,
+      max_depth: Number.isInteger(threading.max_depth) && threading.max_depth >= 2 && threading.max_depth <= 10
+        ? threading.max_depth
+        : DEFAULT_COMMENTS_THREADING_MAX_DEPTH,
+    },
+  };
+}
+
+function normalizeRequestedFeatureState(value) {
+  return {
+    enabled: value?.enabled !== false,
+  };
+}
+
+function normalizeCommentsApiBaseUrl(value) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized || normalized === '/') {
+    return normalized;
+  }
+  return normalized.replace(/\/+$/u, '');
+}
+
+function normalizeTargetComments(comments) {
+  if (!comments || typeof comments !== 'object' || Array.isArray(comments)) {
+    return undefined;
+  }
+
+  const requestToken = preserveOpaqueNonBlankString(comments.request_token);
+  return requestToken ? { request_token: requestToken } : undefined;
+}
+
 function normalizePermalinks(permalinks) {
   const source = permalinks && typeof permalinks === 'object' ? permalinks : {};
   const outputStyle = typeof source.output_style === 'string' && PERMALINK_OUTPUT_STYLES.has(source.output_style)
@@ -821,7 +946,7 @@ function normalizeFrontPage(frontPage) {
 
   return {
     type,
-    ...(type === 'page' ? { page_slug: normalizeOptionalString(frontPage.page_slug) } : {}),
+    ...(type === 'page' ? { page_path: normalizePageReferencePath(frontPage.page_path) } : {}),
     ...(type === 'standalone_html' ? { html: normalizeOptionalRawString(frontPage.html) } : {}),
   };
 }
@@ -838,11 +963,31 @@ function normalizePostIndex(post_index) {
   };
 }
 
-function createRenderData(previewData, themeMetadata = {}) {
+function createRenderData(previewData, themePackage = {}, options = {}) {
+  const themeMetadata = themePackage.metadata || {};
   const themeSupportsComments = themeMetadata?.features?.comments === true;
   const themeSupportsPostIndex = themeMetadata?.features?.post_index !== false;
   const themeSupportsSearch = themeMetadata?.features?.search === true;
-  previewData.site.search = previewData.site.search !== false && themeSupportsSearch;
+  const outputStyle = previewData.site.permalinks.output_style;
+  const requestedComments = previewData.site.comments;
+  previewData.site.search = {
+    enabled: previewData.site.search.enabled === true && themeSupportsSearch,
+  };
+  previewData.site.feed = previewData.site.feed.enabled === true
+    && hasCanonicalSiteUrl(previewData.site.url)
+    && options.generateFeed !== false
+    ? { enabled: true, url: '/feed.xml' }
+    : { enabled: false };
+  previewData.site.archive = previewData.site.archive.enabled === true
+    && themePackage.templates?.has('archive') === true
+    ? {
+        enabled: true,
+        url: outputStyle === 'html-extension' ? '/archive' : '/archive/',
+      }
+    : { enabled: false };
+  previewData.site.comments = requestedComments?.enabled === true && themeSupportsComments
+    ? { ...requestedComments, enabled: true }
+    : { enabled: false };
   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]));
@@ -864,7 +1009,38 @@ function createRenderData(previewData, themeMetadata = {}) {
     }
   }
 
-  const preparedPosts = previewData.content.posts.map((post) => preparePost(post, previewData.site, authorsById, categoriesBySlug, tagsBySlug, themeSupportsComments));
+  const rawPageReferencePaths = new Map(previewData.content.pages.map((page) => [
+    page,
+    resolveEffectivePageReferencePath(previewData.site, page),
+  ]));
+  assertUniquePageReferencePaths(rawPageReferencePaths);
+  const commentsByTarget = {
+    posts: new Map(previewData.content.posts.map((post) => [
+      post.slug,
+      buildTargetCommentsContext({
+        site: previewData.site,
+        target: post,
+        targetType: 'post',
+        themeSupportsComments,
+      }),
+    ])),
+    pages: new Map(previewData.content.pages.map((page) => [
+      rawPageReferencePaths.get(page),
+      buildTargetCommentsContext({
+        site: previewData.site,
+        target: page,
+        targetType: 'page',
+        themeSupportsComments,
+      }),
+    ])),
+  };
+  for (const target of previewData.content.posts) {
+    delete target.comments;
+  }
+  for (const target of previewData.content.pages) {
+    delete target.comments;
+  }
+  const preparedPosts = previewData.content.posts.map((post) => preparePost(post, previewData.site, authorsById, categoriesBySlug, tagsBySlug));
   const discoverablePreparedPosts = preparedPosts.filter((post) => !isDelistedDocument(post));
   const adjacentPostsBySlug = new Map(
     discoverablePreparedPosts.map((post, index) => [post.slug, {
@@ -878,30 +1054,50 @@ function createRenderData(previewData, themeMetadata = {}) {
     next: adjacentPostsBySlug.get(post.slug)?.next || null,
   }));
   const pages = previewData.content.pages.map((page) => preparePage(page, previewData.site));
+  const pageReferencePathByPage = new Map(pages.map((page, index) => [
+    page,
+    rawPageReferencePaths.get(previewData.content.pages[index]),
+  ]));
   const postBySlug = new Map(posts.map((post) => [post.slug, post]));
-  const pageBySlug = new Map(pages.map((page) => [page.slug, page]));
+  const pageByPath = new Map(pages.map((page) => [pageReferencePathByPage.get(page), page]));
   const frontPage = previewData.site.front_page;
-  const collections = resolveCollections(previewData.collections, postBySlug, pageBySlug, frontPage);
-  attachCollectionCursors(posts, pages, collections);
+  const collectionTargetByItem = new WeakMap();
+  const collections = resolveCollections(
+    previewData.collections,
+    postBySlug,
+    pageByPath,
+    frontPage,
+    pageReferencePathByPage,
+    collectionTargetByItem,
+  );
+  attachCollectionCursors(collections, collectionTargetByItem);
   const post_index = previewData.site.post_index;
   const effectivePostIndexEnabled = post_index.enabled !== false && themeSupportsPostIndex;
   const effectivePostIndexPaginate = effectivePostIndexEnabled && post_index.paginate !== false;
   const post_indexBasePath = normalizeRoutePath(post_index.path || DEFAULT_POST_INDEX.path);
+  previewData.site.post_index = {
+    ...post_index,
+    enabled: effectivePostIndexEnabled,
+    paginate: effectivePostIndexPaginate,
+  };
 
   if (frontPage.type !== 'theme_index' && effectivePostIndexEnabled && post_indexBasePath === '/') {
     throw new Error('Invalid front page configuration: site.front_page occupies "/" so site.post_index.path must not be "/". Set site.post_index.path to a non-root path or disable site.post_index.');
   }
 
-  const frontPageRoute = buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, post_indexBasePath);
-  const pageFrontPageSlug = frontPage.type === 'page' ? frontPage.page_slug : '';
-  const preparedPages = pageFrontPageSlug
-    ? pages.filter((page) => page.slug !== pageFrontPageSlug)
+  const frontPageRoute = buildFrontPageRoute(frontPage, pageByPath, effectivePostIndexEnabled, post_indexBasePath);
+  const frontPagePage = frontPageRoute?.front_page_type === 'page' ? frontPageRoute.page : null;
+  const preparedPages = frontPagePage
+    ? pages.filter((page) => page !== frontPagePage)
     : pages;
 
   return {
     posts,
     pages: preparedPages,
     postBySlug,
+    pageByPath,
+    pageReferencePathByPage,
+    commentsByTarget,
     collections,
     taxonomies: buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug),
     frontPageRoute,
@@ -915,20 +1111,22 @@ function createRenderData(previewData, themeMetadata = {}) {
       postBySlug,
       frontPage,
     }),
-    archiveRoutes: buildPaginatedCollection({
-      items: discoverableSourcePosts,
-      posts_per_page: previewData.site.posts_per_page,
-      basePath: '/archive/',
-      outputStyle: previewData.site.permalinks.output_style,
-    }).map((entry) => ({
-      path: entry.path,
-      page: entry.page,
-      totalPages: entry.totalPages,
-      archive: {
-        groups: buildArchiveGroups(entry.items, postBySlug),
-      },
-      pagination: buildStructuredPagination(entry.paginationData),
-    })),
+    archiveRoutes: previewData.site.archive.enabled
+      ? buildPaginatedCollection({
+          items: discoverableSourcePosts,
+          posts_per_page: previewData.site.posts_per_page,
+          basePath: '/archive/',
+          outputStyle: previewData.site.permalinks.output_style,
+        }).map((entry) => ({
+          path: entry.path,
+          page: entry.page,
+          totalPages: entry.totalPages,
+          archive: {
+            groups: buildArchiveGroups(entry.items, postBySlug, previewData.site),
+          },
+          pagination: buildStructuredPagination(entry.paginationData),
+        }))
+      : [],
     categoryRoutes: buildTaxonomyRoutes({
       items: previewData.content.categories,
       postsBySlug: categoryPostsBySlug,
@@ -954,6 +1152,55 @@ function createRenderData(previewData, themeMetadata = {}) {
   };
 }
 
+export function buildTargetCommentsContext({ site, target, targetType, themeSupportsComments }) {
+  const targetPublicId = target?.public_id;
+  const comments = site?.comments;
+
+  if (
+    themeSupportsComments !== true ||
+    comments?.enabled !== true ||
+    target?.allow_comments !== true ||
+    !Number.isInteger(targetPublicId) ||
+    targetPublicId <= 0
+  ) {
+    return DISABLED_COMMENTS_CONTEXT;
+  }
+
+  const common = {
+    enabled: true,
+    target_type: targetType,
+    target_public_id: targetPublicId,
+    provider: comments.provider,
+    api_base_url: comments.api_base_url,
+    per_page: comments.per_page,
+    order: comments.order,
+    threading: {
+      enabled: comments.threading.enabled,
+      max_depth: comments.threading.max_depth,
+    },
+  };
+
+  if (comments.provider === 'wordpress') {
+    return common;
+  }
+
+  if (comments.provider !== 'zeropress') {
+    return DISABLED_COMMENTS_CONTEXT;
+  }
+
+  const requestToken = preserveOpaqueNonBlankString(target?.comments?.request_token);
+  return requestToken
+    ? { ...common, request_token: requestToken }
+    : DISABLED_COMMENTS_CONTEXT;
+}
+
+function getTargetCommentsContext(state, targetType, slug) {
+  const targetMap = targetType === 'post'
+    ? state.renderData.commentsByTarget.posts
+    : state.renderData.commentsByTarget.pages;
+  return targetMap.get(slug) || DISABLED_COMMENTS_CONTEXT;
+}
+
 function buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug) {
   return {
     categories: buildGlobalTaxonomyItems(previewData.site, 'categories', previewData.content.categories, categoryCountBySlug),
@@ -961,14 +1208,22 @@ function buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug)
   };
 }
 
-function resolveCollections(collections, postBySlug, pageBySlug, frontPage) {
+function resolveCollections(collections, postBySlug, pageByPath, frontPage, pageReferencePathByPage, collectionTargetByItem) {
   if (!collections || typeof collections !== 'object') {
     return {};
   }
 
   return Object.fromEntries(
     Object.entries(collections).map(([collectionId, collection]) => {
-      const items = resolveCollectionItems(collectionId, collection?.items, postBySlug, pageBySlug, frontPage);
+      const items = resolveCollectionItems(
+        collectionId,
+        collection?.items,
+        postBySlug,
+        pageByPath,
+        frontPage,
+        pageReferencePathByPage,
+        collectionTargetByItem,
+      );
       return [
         collectionId,
         {
@@ -983,44 +1238,58 @@ function resolveCollections(collections, postBySlug, pageBySlug, frontPage) {
   );
 }
 
-function resolveCollectionItems(collectionId, items, postBySlug, pageBySlug, frontPage) {
+function resolveCollectionItems(collectionId, items, postBySlug, pageByPath, frontPage, pageReferencePathByPage, collectionTargetByItem) {
   if (!Array.isArray(items)) {
     return [];
   }
 
-  return items.map((item, index) => resolveCollectionItem(collectionId, item, index, postBySlug, pageBySlug, frontPage));
+  return items.map((item, index) => resolveCollectionItem(
+    collectionId,
+    item,
+    index,
+    postBySlug,
+    pageByPath,
+    frontPage,
+    pageReferencePathByPage,
+    collectionTargetByItem,
+  ));
 }
 
-function resolveCollectionItem(collectionId, item, index, postBySlug, pageBySlug, frontPage) {
+function resolveCollectionItem(collectionId, item, index, postBySlug, pageByPath, frontPage, pageReferencePathByPage, collectionTargetByItem) {
   if (item?.type === 'post') {
     const post = postBySlug.get(item.slug);
     if (!post) {
       throw new Error(`Invalid collection "${collectionId}": item ${index + 1} references missing post slug "${item.slug}".`);
     }
-    return {
+    const resolved = {
       type: 'post',
       meta: post.meta,
       ...buildStructuredPostSummary(post),
     };
+    collectionTargetByItem.set(resolved, post);
+    return resolved;
   }
 
   if (item?.type === 'page') {
-    const page = pageBySlug.get(item.slug);
+    const pagePath = normalizePageReferencePath(item.path);
+    const page = pageByPath.get(pagePath);
     if (!page) {
-      throw new Error(`Invalid collection "${collectionId}": item ${index + 1} references missing page slug "${item.slug}".`);
+      throw new Error(`Invalid collection "${collectionId}": item ${index + 1} references missing page path "${item.path}".`);
     }
-    return buildCollectionPageSummary(page, frontPage);
+    const resolved = buildCollectionPageSummary(page, frontPage, pageReferencePathByPage.get(page));
+    collectionTargetByItem.set(resolved, page);
+    return resolved;
   }
 
   throw new Error(`Invalid collection "${collectionId}": item ${index + 1} has unsupported type "${item?.type}".`);
 }
 
-function buildCollectionPageSummary(page, frontPage) {
+function buildCollectionPageSummary(page, frontPage, pageReferencePath) {
   return {
     type: 'page',
     title: page.title,
     slug: page.slug,
-    url: frontPage?.type === 'page' && frontPage.page_slug === page.slug ? '/' : page.url,
+    url: frontPage?.type === 'page' && frontPage.page_path === pageReferencePath ? '/' : page.url,
     excerpt: page.excerpt || '',
     featured_image: page.featured_image || '',
     updated_at: page.updated_at || '',
@@ -1031,19 +1300,12 @@ function buildCollectionPageSummary(page, frontPage) {
   };
 }
 
-function attachCollectionCursors(posts, pages, collections) {
-  const postTargets = new Map(posts.map((post) => [post.slug, post]));
-  const pageTargets = new Map(pages.map((page) => [page.slug, page]));
-
+function attachCollectionCursors(collections, collectionTargetByItem) {
   for (const [collectionId, collection] of Object.entries(collections || {})) {
     const items = Array.isArray(collection.items) ? collection.items : [];
 
     items.forEach((item, index) => {
-      const target = item.type === 'post'
-        ? postTargets.get(item.slug)
-        : item.type === 'page'
-          ? pageTargets.get(item.slug)
-          : null;
+      const target = collectionTargetByItem.get(item);
 
       if (!target) {
         return;
@@ -1094,7 +1356,7 @@ function buildCollectionCursorItemSummary(item) {
   };
 }
 
-function buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, post_indexBasePath) {
+function buildFrontPageRoute(frontPage, pageByPath, effectivePostIndexEnabled, post_indexBasePath) {
   if (frontPage.type === 'theme_index') {
     if (effectivePostIndexEnabled && post_indexBasePath === '/') {
       return null;
@@ -1109,9 +1371,9 @@ function buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, post_i
   }
 
   if (frontPage.type === 'page') {
-    const page = pages.find((entry) => entry.slug === frontPage.page_slug);
+    const page = pageByPath.get(frontPage.page_path);
     if (!page) {
-      throw new Error(`Invalid front page configuration: site.front_page.page_slug "${frontPage.page_slug}" does not match a page.`);
+      throw new Error(`Invalid front page configuration: site.front_page.page_path "${frontPage.page_path}" does not match a page.`);
     }
 
     return {
@@ -1231,13 +1493,17 @@ function resolveWidgetItem(item, previewData, renderData, widgetAreaId, index) {
     case 'tags':
       return resolveTagsWidget(baseWidget, item.settings, previewData);
     case 'archives':
-      return resolveArchivesWidget(baseWidget, item.settings, previewData);
+      return previewData.site.archive.enabled === true
+        ? resolveArchivesWidget(baseWidget, item.settings, previewData)
+        : null;
     case 'text':
       return resolveTextWidget(baseWidget, item.settings);
     case 'link-list':
       return resolveLinkListWidget(baseWidget, item.settings);
     case 'search':
-      return resolveSearchWidget(baseWidget, item.settings, widgetAreaId, index);
+      return previewData.site.search.enabled === true
+        ? resolveSearchWidget(baseWidget, item.settings, widgetAreaId, index)
+        : null;
     case 'profile':
       return resolveProfileWidget(baseWidget, item.settings);
     default:
@@ -1322,7 +1588,7 @@ function resolveArchivesWidget(baseWidget, settings, previewData) {
     .slice(0, limit)
     .map((entry) => ({
       label: entry.label,
-      url: routePathToPublicUrl('/archive/', previewData.site.permalinks.output_style),
+      url: previewData.site.archive.url,
       count: entry.count,
       year: entry.year,
       month: entry.month,
@@ -1414,9 +1680,11 @@ function preparePage(page, site) {
   const documentType = normalizeDocumentType(page.document_type);
   const renderedDocument = renderDocument(page.content, documentType);
   const permalink = resolvePagePermalink(site, page);
+  const pageFields = { ...page };
+  delete pageFields.comments;
 
   return {
-    ...page,
+    ...pageFields,
     url: permalink.url,
     document_type: documentType,
     html: renderedDocument.html,
@@ -1425,7 +1693,7 @@ function preparePage(page, site) {
   };
 }
 
-function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, themeSupportsComments) {
+function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug) {
   const documentType = normalizeDocumentType(post.document_type);
   const renderedDocument = renderDocument(post.content, documentType);
   const author = authorsById.get(post.author_id);
@@ -1480,7 +1748,6 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, them
     published_at: formatTimestamp(post.published_at_iso, site),
     updated_at: formatTimestamp(post.updated_at_iso, site),
     reading_time: calculateReadingTime(renderedDocument.html),
-    comments_enabled: themeSupportsComments && site.disallow_comments !== true && post.allow_comments === true,
   };
 }
 
@@ -1730,7 +1997,7 @@ function buildAdjacentPostSummary(post) {
   };
 }
 
-function buildArchiveGroups(posts, postBySlug) {
+function buildArchiveGroups(posts, postBySlug, site) {
   const groups = new Map();
 
   for (const post of posts) {
@@ -1739,14 +2006,12 @@ function buildArchiveGroups(posts, postBySlug) {
       continue;
     }
 
-    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 parts = getZonedDateParts(prepared.published_at_iso, site);
+    const label = `${parts.year}-${padDatePart(parts.month)}`;
     const current = groups.get(label) || {
       label,
-      year,
-      month,
+      year: parts.year,
+      month: parts.month,
       items: [],
     };
 
@@ -1754,7 +2019,8 @@ function buildArchiveGroups(posts, postBySlug) {
     groups.set(label, current);
   }
 
-  return Array.from(groups.values());
+  return Array.from(groups.values())
+    .sort((left, right) => right.year - left.year || right.month - left.month);
 }
 
 function buildTaxonomyRouteData(kind, item, countBySlug) {
@@ -1789,25 +2055,31 @@ function buildArchiveEntries(posts, site) {
     }
 
     const date = toDate(publishedAt);
-    const key = `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
-    const current = entries.get(key) || { date, count: 0 };
+    const parts = getZonedDateParts(date, site);
+    const key = `${parts.year}-${padDatePart(parts.month)}`;
+    const current = entries.get(key) || {
+      date,
+      year: parts.year,
+      month: parts.month,
+      count: 0,
+    };
     current.count += 1;
     entries.set(key, current);
   }
 
   return Array.from(entries.values())
-    .sort((left, right) => right.date.getTime() - left.date.getTime())
+    .sort((left, right) => right.year - left.year || right.month - left.month)
     .map((entry) => ({
       label: formatArchiveLabel(entry.date, site),
       count: entry.count,
-      year: entry.date.getUTCFullYear(),
-      month: entry.date.getUTCMonth() + 1,
+      year: entry.year,
+      month: entry.month,
     }));
 }
 
 function formatArchiveLabel(date, site) {
   return new Intl.DateTimeFormat(normalizeLocale(site.locale || DEFAULT_LOCALE), {
-    timeZone: normalizeNonEmptyString(site.timezone, DEFAULT_TIMEZONE),
+    timeZone: normalizeTimezone(site.timezone),
     year: 'numeric',
     month: 'long',
   }).format(date);
@@ -1818,7 +2090,7 @@ function formatTimestamp(value, site) {
   const locale = normalizeLocale(site.locale || DEFAULT_LOCALE);
   const dateStyle = DATETIME_STYLES.has(site.date_style) ? site.date_style : DEFAULT_DATE_STYLE;
   const timeStyle = DATETIME_STYLES.has(site.time_style) ? site.time_style : DEFAULT_TIME_STYLE;
-  const siteTimezone = normalizeNonEmptyString(site.timezone, DEFAULT_TIMEZONE);
+  const siteTimezone = normalizeTimezone(site.timezone);
 
   if (dateStyle === 'none' && timeStyle === 'none') {
     return '';
@@ -1858,32 +2130,43 @@ function normalizeOptionalString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : '';
 }
 
+function preserveOpaqueNonBlankString(value) {
+  return typeof value === 'string' && value.trim() ? value : '';
+}
+
 function normalizeOptionalRawString(value) {
   return typeof value === 'string' && value.trim() ? value : '';
 }
 
 function normalizeLocale(value) {
-  if (typeof value !== 'string' || !value.trim()) {
-    return DEFAULT_LOCALE;
-  }
-
-  const parts = value.trim().replace(/_/g, '-').split('-').filter(Boolean);
-  if (parts.length === 0) {
-    return DEFAULT_LOCALE;
+  const candidate = typeof value === 'string' && value.trim() ? value.trim() : DEFAULT_LOCALE;
+  try {
+    return Intl.getCanonicalLocales(candidate)[0] || DEFAULT_LOCALE;
+  } catch {
+    throw new Error(`Invalid preview-data: site.locale "${candidate}" is not a valid BCP 47 language tag.`);
   }
+}
 
-  return parts.map((part, index) => {
-    if (index === 0) {
-      return part.toLowerCase();
-    }
-    if (part.length === 2 || part.length === 3) {
-      return part.toUpperCase();
+function normalizeTimezone(value) {
+  const candidate = typeof value === 'string' && value.trim() ? value.trim() : DEFAULT_TIMEZONE;
+  const offsetMatch = /^([+-])(\d{2}):(\d{2})$/u.exec(candidate);
+  if (offsetMatch) {
+    const hours = Number(offsetMatch[2]);
+    const minutes = Number(offsetMatch[3]);
+    if (minutes > 59 || hours > 14 || (hours === 14 && minutes !== 0)) {
+      throw new Error(`Invalid preview-data: site.timezone "${candidate}" is outside the supported fixed-offset range.`);
     }
-    if (part.length === 4) {
-      return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+    if (hours === 0 && minutes === 0) {
+      return DEFAULT_TIMEZONE;
     }
-    return part.toLowerCase();
-  }).join('-');
+    return `${offsetMatch[1]}${String(hours).padStart(2, '0')}:${String(minutes).padStart(2, '0')}`;
+  }
+
+  try {
+    return new Intl.DateTimeFormat('en-US', { timeZone: candidate }).resolvedOptions().timeZone;
+  } catch {
+    throw new Error(`Invalid preview-data: site.timezone "${candidate}" is not UTC, an IANA time zone, or a valid fixed offset.`);
+  }
 }
 
 function normalizeDocumentType(value) {
@@ -1967,61 +2250,6 @@ async function normalizeAndValidateThemePackage(themePackage) {
   };
 }
 
-function formatThemeValidationFailure(validation) {
-  const blocks = [
-    [
-      'Theme validation failed',
-      `Errors: ${validation.errors.length}`,
-      `Checked files: ${validation.checkedFiles}`,
-    ].join('\n'),
-    ...validation.errors.map((issue) => formatThemeValidationIssue(issue)),
-  ];
-  return blocks.join('\n\n');
-}
-
-function formatThemeValidationIssue(issue) {
-  if (!issue) {
-    return 'Reason: Unknown error';
-  }
-
-  const lines = [`ERROR ${issue.code || 'THEME_VALIDATION_ERROR'}`];
-  const location = splitIssuePath(issue.path);
-  if (location.file) {
-    lines.push(`File: ${location.file}`);
-  }
-  if (location.path) {
-    lines.push(`Path: ${location.path}`);
-  }
-  if (Number.isInteger(issue.line) && Number.isInteger(issue.column)) {
-    lines.push(`Line: ${issue.line}, Column: ${issue.column}`);
-  }
-  if (issue.category) {
-    lines.push(`Category: ${issue.category}`);
-  }
-  lines.push(`Reason: ${issue.message || 'Unknown error'}`);
-  if (issue.snippet) {
-    const lineLabel = Number.isInteger(issue.line) ? String(issue.line) : '';
-    lines.push('', `${lineLabel} | ${issue.snippet.line}`, `${' '.repeat(lineLabel.length)} | ${issue.snippet.pointer}`);
-  }
-  if (issue.hint) {
-    lines.push('', 'Hint:', issue.hint);
-  }
-
-  return lines.join('\n');
-}
-
-function splitIssuePath(issuePath) {
-  const normalizedPath = String(issuePath || '');
-  if (normalizedPath.startsWith('theme.json.')) {
-    return {
-      file: 'theme.json',
-      path: normalizedPath.slice('theme.json.'.length),
-    };
-  }
-
-  return { file: normalizedPath, path: '' };
-}
-
 function normalizeThemePackageMetadata(sourceMetadata, manifest) {
   return {
     ...manifest,
@@ -2029,59 +2257,47 @@ function normalizeThemePackageMetadata(sourceMetadata, manifest) {
   };
 }
 
-async function buildAssetOutputs(assets, assetProcessor, options) {
+function buildAssetOutputs(assets, assetProcessor, options) {
   const outputs = [];
 
   for (const [assetPath, content] of assets.entries()) {
-    const ext = assetPath.split('.').pop()?.toLowerCase();
-    let processedContent = content;
-    let contentType = getContentType(assetPath);
-
-    if (ext === 'css') {
-      processedContent = await assetProcessor.processCSS(new TextDecoder().decode(content));
-      contentType = 'text/css';
-    } else if (ext === 'js') {
-      processedContent = await assetProcessor.processJavaScript(new TextDecoder().decode(content));
-      contentType = 'application/javascript';
-    }
-
     const hash = options.assetHashing ? `.${assetProcessor.generateAssetHash(content)}` : '';
     const targetPath = `assets/${assetPath.replace(/(\.[^.]+)$/, `${hash}$1`)}`;
 
     outputs.push({
       originalPath: assetPath,
       path: targetPath,
-      content: processedContent,
-      contentType,
+      content,
+      contentType: getContentType(assetPath),
     });
   }
 
   return outputs;
 }
 
-async function buildCustomCssAsset(customCss, assetProcessor, options) {
-  const content = normalizeOptionalString(customCss?.content);
-  if (!content) {
+function buildCustomCssAsset(customCss, assetProcessor, options) {
+  const content = customCss?.content;
+  if (typeof content !== 'string' || !content.trim()) {
     return null;
   }
 
   const sourceBuffer = new TextEncoder().encode(content);
-  const processedContent = await assetProcessor.processCSS(content);
   const hash = options.assetHashing ? `.${assetProcessor.generateAssetHash(sourceBuffer)}` : '';
 
   return {
     originalPath: '__zeropress_custom.css',
     path: `assets/zeropress-custom${hash}.css`,
-    content: processedContent,
+    content,
     contentType: 'text/css',
   };
 }
 
-function createRenderContext(site, currentUrl) {
+function createRenderContext(site, currentUrl, comments = DISABLED_COMMENTS_CONTEXT) {
   return {
     site,
     currentUrl,
     language: site.locale,
+    comments,
   };
 }
 
@@ -2097,23 +2313,26 @@ function buildRouteContext(type, url, options = {}) {
 
 function buildPageMeta(site, options = {}) {
   const resolvedTitle = normalizeNonEmptyString(options.title, site.title);
-  const resolvedDescription = normalizeOptionalString(options.description);
-  const canonicalUrl = resolveMetaCanonicalUrl(site, options.canonicalUrl || options.currentUrl);
-  const ogImage = resolveMetaImageUrl(options.image);
-  const ogType = normalizeNonEmptyString(options.ogType, 'website');
-  const publishedTime = normalizeOptionalString(options.publishedTime);
-  const modifiedTime = normalizeOptionalString(options.modifiedTime);
+  const includeRichMetadata = options.includeRichMetadata !== false;
+  const resolvedDescription = includeRichMetadata ? normalizeOptionalString(options.description) : '';
+  const canonicalUrl = includeRichMetadata
+    ? resolveMetaCanonicalUrl(site, options.canonicalUrl || options.currentUrl)
+    : '';
+  const ogImage = includeRichMetadata ? resolveMetaImageUrl(options.image) : '';
+  const ogType = includeRichMetadata ? normalizeNonEmptyString(options.ogType, 'website') : '';
+  const publishedTime = includeRichMetadata ? normalizeOptionalString(options.publishedTime) : '';
+  const modifiedTime = includeRichMetadata ? normalizeOptionalString(options.modifiedTime) : '';
   const robotsNoindex = options.robotsNoindex === true;
 
   const meta = {
     title: escapeHtml(resolvedTitle),
     description: resolvedDescription ? escapeHtml(resolvedDescription) : '',
     canonical_url: canonicalUrl ? escapeHtml(canonicalUrl) : '',
-    og_title: escapeHtml(resolvedTitle),
-    og_description: resolvedDescription ? escapeHtml(resolvedDescription) : '',
+    og_title: includeRichMetadata ? escapeHtml(resolvedTitle) : '',
+    og_description: includeRichMetadata && resolvedDescription ? escapeHtml(resolvedDescription) : '',
     og_type: escapeHtml(ogType),
-    og_url: canonicalUrl ? escapeHtml(canonicalUrl) : '',
-    og_site_name: escapeHtml(site.title),
+    og_url: includeRichMetadata && canonicalUrl ? escapeHtml(canonicalUrl) : '',
+    og_site_name: includeRichMetadata ? escapeHtml(site.title) : '',
     og_image: ogImage ? escapeHtml(ogImage) : '',
     article_published_time: publishedTime ? escapeHtml(publishedTime) : '',
     article_modified_time: modifiedTime ? escapeHtml(modifiedTime) : '',
@@ -2122,7 +2341,7 @@ function buildPageMeta(site, options = {}) {
 
   return {
     ...meta,
-    head_tags: buildMetaHeadTags(meta),
+    head_tags: buildMetaHeadTags(meta, site, options),
   };
 }
 
@@ -2138,7 +2357,7 @@ function buildFrontPageTitle(site) {
   return resolvedDescription ? `${resolvedSiteTitle} - ${resolvedDescription}` : resolvedSiteTitle;
 }
 
-function buildMetaHeadTags(meta) {
+function buildMetaHeadTags(meta, site, options = {}) {
   const tags = [];
 
   if (meta.description) {
@@ -2150,24 +2369,29 @@ function buildMetaHeadTags(meta) {
   if (meta.canonical_url) {
     tags.push(`<link rel="canonical" href="${meta.canonical_url}">`);
   }
-
-  tags.push(`<meta property="og:title" content="${meta.og_title}">`);
-  if (meta.og_description) {
-    tags.push(`<meta property="og:description" content="${meta.og_description}">`);
-  }
-  tags.push(`<meta property="og:type" content="${meta.og_type}">`);
-  if (meta.og_url) {
-    tags.push(`<meta property="og:url" content="${meta.og_url}">`);
-  }
-  tags.push(`<meta property="og:site_name" content="${meta.og_site_name}">`);
-  if (meta.og_image) {
-    tags.push(`<meta property="og:image" content="${meta.og_image}">`);
+  if (options.includeFeedLink !== false && site.feed?.enabled === true) {
+    tags.push(`<link rel="alternate" type="application/rss+xml" title="${escapeHtml(site.title)} Feed" href="${escapeHtml(site.feed.url)}">`);
   }
-  if (meta.article_published_time) {
-    tags.push(`<meta property="article:published_time" content="${meta.article_published_time}">`);
-  }
-  if (meta.article_modified_time) {
-    tags.push(`<meta property="article:modified_time" content="${meta.article_modified_time}">`);
+
+  if (meta.og_title) {
+    tags.push(`<meta property="og:title" content="${meta.og_title}">`);
+    if (meta.og_description) {
+      tags.push(`<meta property="og:description" content="${meta.og_description}">`);
+    }
+    tags.push(`<meta property="og:type" content="${meta.og_type}">`);
+    if (meta.og_url) {
+      tags.push(`<meta property="og:url" content="${meta.og_url}">`);
+    }
+    tags.push(`<meta property="og:site_name" content="${meta.og_site_name}">`);
+    if (meta.og_image) {
+      tags.push(`<meta property="og:image" content="${meta.og_image}">`);
+    }
+    if (meta.article_published_time) {
+      tags.push(`<meta property="article:published_time" content="${meta.article_published_time}">`);
+    }
+    if (meta.article_modified_time) {
+      tags.push(`<meta property="article:modified_time" content="${meta.article_modified_time}">`);
+    }
   }
 
   return tags.length ? `${tags.join('\n')}\n` : '';
@@ -2194,7 +2418,7 @@ function resolveMetaImageUrl(image) {
   return '';
 }
 
-function normalizeMediaField(value, media_base_url) {
+function normalizeMediaField(value, media_origin) {
   if (value === undefined) {
     return undefined;
   }
@@ -2204,22 +2428,145 @@ function normalizeMediaField(value, media_base_url) {
     return '';
   }
 
-  if (isAbsoluteUrl(normalizedValue)) {
-    return normalizeAbsoluteUrl(normalizedValue, SAFE_MEDIA_PROTOCOLS);
+  const normalizedMediaUrl = normalizeMediaUrl(normalizedValue);
+  if (!normalizedMediaUrl) {
+    return '';
   }
 
-  const normalizedBaseUrl = normalizeOptionalString(media_base_url);
-  if (!normalizedBaseUrl) {
-    return normalizedValue;
+  if (isAbsoluteUrl(normalizedMediaUrl)) {
+    return normalizedMediaUrl;
+  }
+
+  const normalizedOrigin = normalizeMediaOrigin(media_origin);
+  if (!normalizedOrigin) {
+    return normalizedMediaUrl;
+  }
+
+  try {
+    return decodeURI(new URL(normalizedMediaUrl, `${normalizedOrigin}/`).toString());
+  } catch {
+    return '';
+  }
+}
+
+function normalizeMediaOrigin(value) {
+  const normalizedValue = normalizeOptionalString(value);
+  if (!normalizedValue) {
+    return '';
   }
 
   try {
-    return decodeURI(new URL(normalizedValue, normalizedBaseUrl).toString());
+    const url = new URL(normalizedValue);
+    if (
+      !SAFE_MEDIA_PROTOCOLS.has(url.protocol)
+      || url.username
+      || url.password
+      || url.search
+      || url.hash
+      || url.pathname !== '/'
+      || !isSafeUrlText(normalizedValue)
+    ) {
+      return '';
+    }
+    return url.origin;
   } catch {
     return '';
   }
 }
 
+function normalizeSiteOrigin(value) {
+  const normalizedValue = normalizeOptionalString(value);
+  if (!normalizedValue) {
+    return '';
+  }
+
+  try {
+    const url = new URL(normalizedValue);
+    if (
+      !SAFE_LINK_PROTOCOLS.has(url.protocol)
+      || url.username
+      || url.password
+      || url.search
+      || url.hash
+      || url.pathname !== '/'
+      || !isSafeUrlText(normalizedValue)
+    ) {
+      throw new Error('site.url must be an HTTP(S) origin without credentials, path, query, or fragment');
+    }
+    return url.origin;
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(`Invalid preview-data: site.url is not a safe HTTP(S) origin: ${reason}`);
+  }
+}
+
+function normalizeNavigationUrl(value) {
+  return normalizeSafeResourceUrl(value, { allowRoot: true });
+}
+
+function normalizeMediaUrl(value) {
+  return normalizeSafeResourceUrl(value, { allowRoot: false });
+}
+
+function normalizeSafeResourceUrl(value, options) {
+  const normalizedValue = normalizeOptionalString(value);
+  if (!normalizedValue || !isSafeUrlText(normalizedValue)) {
+    return '';
+  }
+
+  if (normalizedValue.startsWith('/')) {
+    if (normalizedValue.startsWith('//')) {
+      return '';
+    }
+    const pathname = normalizedValue.split(/[?#]/u, 1)[0];
+    if ((!options.allowRoot && pathname === '/') || hasDotPathSegment(pathname)) {
+      return '';
+    }
+    return normalizedValue;
+  }
+
+  if (!isAbsoluteUrl(normalizedValue)) {
+    return '';
+  }
+
+  const rawPath = extractAbsoluteUrlPath(normalizedValue);
+  if ((!options.allowRoot && (!rawPath || rawPath === '/')) || hasDotPathSegment(rawPath || '/')) {
+    return '';
+  }
+  return normalizeAbsoluteUrl(normalizedValue, SAFE_LINK_PROTOCOLS);
+}
+
+function isSafeUrlText(value) {
+  if (/[\s\\\u0000-\u001F\u007F]/u.test(value)) {
+    return false;
+  }
+  try {
+    decodeURI(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function extractAbsoluteUrlPath(value) {
+  const match = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#]*(?<path>[^?#]*)/u.exec(value);
+  return match?.groups?.path || '/';
+}
+
+function hasDotPathSegment(pathname) {
+  return String(pathname || '').split('/').some((segment) => {
+    if (!segment) {
+      return false;
+    }
+    try {
+      const decoded = decodeURIComponent(segment).normalize('NFC');
+      return decoded === '.' || decoded === '..';
+    } catch {
+      return true;
+    }
+  });
+}
+
 function isAbsoluteUrl(value) {
   try {
     new URL(value);
@@ -2232,7 +2579,7 @@ function isAbsoluteUrl(value) {
 function normalizeAbsoluteUrl(value, allowedProtocols) {
   try {
     const url = new URL(value);
-    if (!allowedProtocols.has(url.protocol)) {
+    if (!allowedProtocols.has(url.protocol) || url.username || url.password || !isSafeUrlText(value)) {
       return '';
     }
     return decodeURI(url.toString());
@@ -2242,16 +2589,7 @@ function normalizeAbsoluteUrl(value, allowedProtocols) {
 }
 
 function normalizeThemeLinkUrl(value) {
-  const normalizedValue = normalizeOptionalString(value);
-  if (!normalizedValue || normalizedValue.startsWith('//')) {
-    return '';
-  }
-
-  if (isAbsoluteUrl(normalizedValue)) {
-    return normalizeAbsoluteUrl(normalizedValue, SAFE_LINK_PROTOCOLS);
-  }
-
-  return normalizedValue;
+  return normalizeNavigationUrl(value);
 }
 
 async function writeOutput(writer, summaries, path, content, contentType) {
@@ -2320,6 +2658,31 @@ function resolvePagePermalink(site, page) {
   return resolvePermalink(site, 'pages', page);
 }
 
+function resolveEffectivePageReferencePath(site, page) {
+  return normalizePageReferencePath(resolvePagePermalink(site, page).path);
+}
+
+function normalizePageReferencePath(value) {
+  const normalized = decodeRoutePath(normalizeOptionalString(value))
+    .replace(/^\/+|\/+$/gu, '')
+    .normalize('NFC');
+  return normalized;
+}
+
+function assertUniquePageReferencePaths(pageReferencePaths) {
+  const seen = new Map();
+  for (const [page, pagePath] of pageReferencePaths.entries()) {
+    if (!pagePath) {
+      throw new Error(`Invalid preview-data: Page "${page?.slug || ''}" resolves to an empty effective path.`);
+    }
+    const existing = seen.get(pagePath);
+    if (existing) {
+      throw new Error(`Invalid preview-data: Pages "${existing.slug}" and "${page.slug}" resolve to the same effective path "${pagePath}".`);
+    }
+    seen.set(pagePath, page);
+  }
+}
+
 function resolvePermalink(site, kind, item) {
   const pattern = normalizeNonEmptyString(site.permalinks?.[kind], DEFAULT_PERMALINKS[kind]);
   return buildRouteInfo(applyPermalinkPattern(pattern, kind, item, site), site.permalinks.output_style);
@@ -2358,19 +2721,19 @@ function buildPermalinkTokenValues(kind, item, site) {
   };
 
   if (kind === 'posts') {
-    const parts = getPermalinkDateParts(item.published_at_iso, site);
+    const parts = getZonedDateParts(item.published_at_iso, site);
     values.public_id = String(item.public_id);
-    values.year = parts.year;
-    values.month = parts.month;
-    values.day = parts.day;
+    values.year = String(parts.year);
+    values.month = padDatePart(parts.month);
+    values.day = padDatePart(parts.day);
   }
 
   return values;
 }
 
-function getPermalinkDateParts(value, site) {
+function getZonedDateParts(value, site) {
   const date = toDate(value);
-  const timeZone = normalizeNonEmptyString(site.timezone, DEFAULT_TIMEZONE);
+  const timeZone = normalizeTimezone(site.timezone);
   const parts = new Intl.DateTimeFormat('en-US', {
     timeZone,
     year: 'numeric',
@@ -2379,12 +2742,16 @@ function getPermalinkDateParts(value, site) {
   }).formatToParts(date);
 
   return {
-    year: parts.find((part) => part.type === 'year')?.value || String(date.getUTCFullYear()),
-    month: parts.find((part) => part.type === 'month')?.value || String(date.getUTCMonth() + 1).padStart(2, '0'),
-    day: parts.find((part) => part.type === 'day')?.value || String(date.getUTCDate()).padStart(2, '0'),
+    year: Number(parts.find((part) => part.type === 'year')?.value) || date.getUTCFullYear(),
+    month: Number(parts.find((part) => part.type === 'month')?.value) || date.getUTCMonth() + 1,
+    day: Number(parts.find((part) => part.type === 'day')?.value) || date.getUTCDate(),
   };
 }
 
+function padDatePart(value) {
+  return String(value).padStart(2, '0');
+}
+
 function normalizeOutputPath(filePath) {
   return String(filePath || '').replace(/^\/+/, '');
 }
@@ -2437,29 +2804,31 @@ function assertPlannedOutputPathsSafe(state) {
       outputPath: pageToOutputPath(page, outputStyle),
     })),
   ];
-  assertUniqueRoutes(routeEntries);
-
-  const plannedPaths = [
-    ...routeEntries.map((entry) => entry.outputPath),
+  const nonRoutePaths = [
     ...state.assetOutputs.map((assetOutput) => assetOutput.path),
   ];
 
-  if (shouldGenerateSearchArtifacts(state, state.options)) {
-    plannedPaths.push(SEARCH_INDEX_OUTPUT_PATH, SEARCH_ADAPTER_OUTPUT_PATH, SEARCH_PAGEFIND_ADAPTER_OUTPUT_PATH);
+  if (shouldGenerateSearchArtifacts(state)) {
+    nonRoutePaths.push(SEARCH_INDEX_OUTPUT_PATH, SEARCH_ADAPTER_OUTPUT_PATH, SEARCH_PAGEFIND_ADAPTER_OUTPUT_PATH);
   }
 
-  if (state.options.generateSpecialFiles) {
-    plannedPaths.push('404.html');
-    if (shouldGenerateRobotsTxt(state.options)) {
-      plannedPaths.push('robots.txt');
-    }
-    if (hasCanonicalSiteUrl(state.previewData.site.url)) {
-      plannedPaths.push('sitemap.xml');
-      if (shouldGenerateFeed(state.options)) {
-        plannedPaths.push('feed.xml');
-      }
+  if (hasTemplate(state, '404')) {
+    nonRoutePaths.push('404.html');
+  }
+  if (shouldGenerateRobotsTxt(state.options)) {
+    nonRoutePaths.push('robots.txt');
+  }
+  if (hasCanonicalSiteUrl(state.previewData.site.url)) {
+    nonRoutePaths.push('sitemap.xml');
+    if (shouldGenerateFeed(state)) {
+      nonRoutePaths.push('feed.xml');
     }
   }
+  nonRoutePaths.push(...normalizeReservedOutputPaths(state.options.reservedOutputPaths));
+  const plannedPaths = [
+    ...routeEntries.map((entry) => entry.outputPath),
+    ...nonRoutePaths,
+  ];
 
   for (const plannedPath of plannedPaths) {
     const rawPath = String(plannedPath || '');
@@ -2467,29 +2836,92 @@ function assertPlannedOutputPathsSafe(state) {
     assertSafeRelativeOutputPath(rawPath, normalizedPath);
   }
 
+  const publicUrlClaims = [
+    ...routeEntries.flatMap((entry, index) => {
+      const owner = `route:${index}`;
+      return [entry.url, ...buildOutputPublicUrlAliases(entry.outputPath)]
+        .map((url) => ({ url, owner }));
+    }),
+    ...nonRoutePaths.flatMap((outputPath, index) => {
+      const owner = `file:${index}`;
+      return buildOutputPublicUrlAliases(outputPath)
+        .map((url) => ({ url, owner }));
+    }),
+  ];
+  assertUniquePublicUrlClaims(publicUrlClaims);
   assertUniqueOutputPaths(plannedPaths);
 }
 
-function assertUniqueRoutes(routeEntries) {
+function normalizeReservedOutputPaths(value) {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error('reservedOutputPaths must be an array of relative output file paths');
+  }
+  return value.map((outputPath) => {
+    if (typeof outputPath !== 'string') {
+      throw new Error('reservedOutputPaths must contain only relative output file paths');
+    }
+    return outputPath;
+  });
+}
+
+function buildOutputPublicUrlAliases(outputPath) {
+  const normalizedPath = normalizeOutputPath(outputPath);
+  const aliases = new Set([`/${normalizedPath}`]);
+
+  if (normalizedPath.endsWith('.html')) {
+    aliases.add(`/${normalizedPath.slice(0, -'.html'.length)}`);
+  }
+  if (normalizedPath === 'index.html') {
+    aliases.add('/');
+  } else if (normalizedPath.endsWith('/index.html')) {
+    aliases.add(`/${normalizedPath.slice(0, -'index.html'.length)}`);
+  }
+
+  return [...aliases];
+}
+
+function assertUniquePublicUrlClaims(claims) {
   const seenUrls = new Map();
-  for (const entry of routeEntries) {
-    const normalizedUrl = normalizeRouteCollisionKey(entry.url);
-    if (seenUrls.has(normalizedUrl)) {
-      throw new Error(`Duplicate public URL detected: ${entry.url}`);
+  for (const claim of claims) {
+    const normalizedUrl = normalizeRouteCollisionKey(claim.url);
+    const existingOwner = seenUrls.get(normalizedUrl);
+    if (existingOwner !== undefined && existingOwner !== claim.owner) {
+      throw new Error(`Duplicate public URL detected: ${claim.url}`);
     }
-    seenUrls.set(normalizedUrl, entry);
+    seenUrls.set(normalizedUrl, claim.owner);
   }
 }
 
 function assertUniqueOutputPaths(plannedPaths) {
+  const normalizedPaths = plannedPaths.map((plannedPath) => normalizeOutputPath(plannedPath));
   const seenPaths = new Set();
-  for (const plannedPath of plannedPaths) {
-    const normalizedPath = normalizeOutputPath(plannedPath);
+  for (const [index, normalizedPath] of normalizedPaths.entries()) {
     if (seenPaths.has(normalizedPath)) {
-      throw new Error(`Duplicate output path detected: ${plannedPath}`);
+      throw new Error(`Duplicate output path detected: ${plannedPaths[index]}`);
     }
     seenPaths.add(normalizedPath);
   }
+
+  const shallowestFirst = [...seenPaths]
+    .map((outputPath) => ({ outputPath, segments: outputPath.split('/') }))
+    .sort((left, right) => (
+      left.segments.length - right.segments.length
+      || left.outputPath.localeCompare(right.outputPath)
+    ));
+  const processedPaths = new Set();
+  for (const { outputPath, segments } of shallowestFirst) {
+    let ancestorPath = '';
+    for (const segment of segments.slice(0, -1)) {
+      ancestorPath = ancestorPath ? `${ancestorPath}/${segment}` : segment;
+      if (processedPaths.has(ancestorPath)) {
+        throw new Error(`Conflicting output path hierarchy detected: ${ancestorPath} and ${outputPath}`);
+      }
+    }
+    processedPaths.add(outputPath);
+  }
 }
 
 function normalizeRouteCollisionKey(url) {
@@ -2532,6 +2964,7 @@ function assertSafeRelativeOutputPath(rawPath, normalizedPath = normalizeOutputP
   if (
     originalPath.startsWith('/') ||
     originalPath.startsWith('\\') ||
+    originalPath.includes('\\') ||
     /^[A-Za-z]:[\\/]/.test(originalPath) ||
     normalizedSeparators.startsWith('//')
   ) {
@@ -2554,11 +2987,11 @@ function sha256(content) {
   return hash.digest('hex');
 }
 
-function injectSiteCustomizations(html, state) {
+function injectSiteCustomizations(html, state, target) {
   let next = injectFaviconLinks(html, state.favicon);
   next = injectGeneratorMeta(next, state.exposeGenerator);
   next = injectCustomCssAssetLink(next, state.customCssHref);
-  next = injectCustomHtml(next, state.customHtml);
+  next = injectCustomHtml(next, state.customHtml, target);
   return next;
 }
 
@@ -2568,7 +3001,7 @@ function injectFaviconLinks(html, favicon) {
     return html;
   }
 
-  return html.replace('</head>', `${links}\n</head>`);
+  return insertBeforeClosingTag(html, HEAD_CLOSING_TAG_PATTERN, `${links}\n`);
 }
 
 function buildFaviconLinks(favicon) {
@@ -2577,14 +3010,36 @@ function buildFaviconLinks(favicon) {
   }
 
   const lines = [];
-  if (normalizeOptionalString(favicon.icon)) {
-    lines.push(`  <link rel="icon" href="${escapeHtml(favicon.icon)}" sizes="any">`);
-  }
-  if (normalizeOptionalString(favicon.svg)) {
-    lines.push(`  <link rel="icon" href="${escapeHtml(favicon.svg)}" type="image/svg+xml">`);
-  }
-  if (normalizeOptionalString(favicon.png)) {
-    lines.push(`  <link rel="icon" href="${escapeHtml(favicon.png)}" type="image/png">`);
+  const icon = normalizeOptionalString(favicon.icon);
+  const iconDark = normalizeOptionalString(favicon.icon_dark);
+  const svg = normalizeOptionalString(favicon.svg);
+  const png = normalizeOptionalString(favicon.png);
+  const hasDefaultIcon = Boolean(icon || svg || png);
+  const hasBothColorSchemes = Boolean(iconDark && hasDefaultIcon);
+
+  if (iconDark) {
+    lines.push(buildFaviconLink(
+      iconDark,
+      undefined,
+      hasBothColorSchemes ? '(prefers-color-scheme: dark)' : undefined,
+    ));
+  }
+  if (icon) {
+    lines.push(buildFaviconLink(icon, undefined, hasBothColorSchemes ? '(prefers-color-scheme: light)' : undefined));
+  }
+  if (svg) {
+    lines.push(buildFaviconLink(
+      svg,
+      'image/svg+xml',
+      hasBothColorSchemes ? '(prefers-color-scheme: light)' : undefined,
+    ));
+  }
+  if (png) {
+    lines.push(buildFaviconLink(
+      png,
+      'image/png',
+      hasBothColorSchemes ? '(prefers-color-scheme: light)' : undefined,
+    ));
   }
   if (normalizeOptionalString(favicon.apple_touch_icon)) {
     lines.push(`  <link rel="apple-touch-icon" href="${escapeHtml(favicon.apple_touch_icon)}">`);
@@ -2593,12 +3048,20 @@ function buildFaviconLinks(favicon) {
   return lines.join('\n');
 }
 
+function buildFaviconLink(href, type, media) {
+  return `  <link rel="icon" href="${escapeHtml(href)}"${type ? ` type="${type}"` : ''}${media ? ` media="${media}"` : ''}>`;
+}
+
 function injectGeneratorMeta(html, exposeGenerator) {
   if (exposeGenerator === false) {
     return html;
   }
 
-  return html.replace('</head>', '  <meta name="generator" content="ZeroPress">\n</head>');
+  return insertBeforeClosingTag(
+    html,
+    HEAD_CLOSING_TAG_PATTERN,
+    '  <meta name="generator" content="ZeroPress">\n',
+  );
 }
 
 function injectCustomCssAssetLink(html, href) {
@@ -2606,24 +3069,66 @@ function injectCustomCssAssetLink(html, href) {
     return html;
   }
 
-  return html.replace('</head>', `  <link rel="stylesheet" href="${escapeHtml(href)}">\n</head>`);
+  return insertBeforeClosingTag(
+    html,
+    HEAD_CLOSING_TAG_PATTERN,
+    `  <link rel="stylesheet" href="${escapeHtml(href)}">\n`,
+  );
 }
 
-function injectCustomHtml(html, customHtml) {
+function injectCustomHtml(html, customHtml, target) {
   let next = html;
-  const headEnd = normalizeOptionalRawString(customHtml?.head_end?.content);
-  const bodyEnd = normalizeOptionalRawString(customHtml?.body_end?.content);
+  const headEnd = normalizeCustomHtmlSlot(customHtml?.head_end);
+  const bodyEnd = normalizeCustomHtmlSlot(customHtml?.body_end);
 
   if (headEnd) {
-    next = next.replace('</head>', `${headEnd}\n</head>`);
+    next = injectRequiredCustomHtmlSlot(
+      next,
+      'head_end',
+      headEnd,
+      'head',
+      HEAD_CLOSING_TAG_PATTERN,
+      target,
+    );
   }
   if (bodyEnd) {
-    next = next.replace('</body>', `${bodyEnd}\n</body>`);
+    next = injectRequiredCustomHtmlSlot(
+      next,
+      'body_end',
+      bodyEnd,
+      'body',
+      BODY_CLOSING_TAG_PATTERN,
+      target,
+    );
   }
 
   return next;
 }
 
+function injectRequiredCustomHtmlSlot(html, slot, content, tagName, closingTagPattern, target) {
+  let injected = false;
+  const next = String(html).replace(closingTagPattern, (closingTag) => {
+    injected = true;
+    return `${content}\n${closingTag}`;
+  });
+
+  if (injected) {
+    return next;
+  }
+
+  const route = normalizeOptionalString(target?.route) || '<unknown>';
+  const outputPath = normalizeOptionalString(target?.outputPath) || '<unknown>';
+  throw new Error(
+    `Unable to inject custom_html.${slot} for route "${route}" into output "${outputPath}": `
+    + `rendered theme HTML is missing a closing </${tagName}> tag. `
+    + `Add </${tagName}> to the rendered theme layout or remove custom_html.${slot}.`,
+  );
+}
+
+function insertBeforeClosingTag(html, closingTagPattern, content) {
+  return String(html).replace(closingTagPattern, (closingTag) => `${content}${closingTag}`);
+}
+
 function buildSearchIndexJson(state) {
   return `${JSON.stringify(buildSearchIndexItems(state), null, 2)}\n`;
 }
@@ -2649,18 +3154,26 @@ function buildSearchIndexItems(state) {
     ? state.renderData.frontPageRoute.page
     : null;
   const frontPageItems = frontPagePage && frontPagePage.status === 'published' && !isDelistedDocument(frontPagePage)
-    ? [buildSearchPageItem(frontPagePage, '/')]
+    ? [buildSearchPageItem(
+        frontPagePage,
+        '/',
+        state.renderData.pageReferencePathByPage.get(frontPagePage),
+      )]
     : [];
   const pageItems = state.renderData.pages
     .filter((page) => page.status === 'published' && !isDelistedDocument(page))
-    .map((page) => buildSearchPageItem(page, page.url));
+    .map((page) => buildSearchPageItem(
+      page,
+      page.url,
+      state.renderData.pageReferencePathByPage.get(page),
+    ));
 
   return [...posts, ...frontPageItems, ...pageItems];
 }
 
-function buildSearchPageItem(page, url) {
+function buildSearchPageItem(page, url, pageReferencePath) {
   return {
-    id: `page:${page.slug}`,
+    id: `page:${pageReferencePath}`,
     type: 'page',
     title: page.title,
     url,
@@ -2717,11 +3230,13 @@ function normalizeSearchText(value) {
   return String(value || '').replace(/\s+/g, ' ').trim();
 }
 
-function buildSearchAdapterJs() {
+function buildSearchAdapterJs(locale) {
   const fieldWeightsJson = JSON.stringify(SEARCH_FIELD_WEIGHTS, null, 2);
+  const localeJson = JSON.stringify(locale);
   return `const FIELD_WEIGHTS = ${fieldWeightsJson};
 const FIELD_NAMES = Object.keys(FIELD_WEIGHTS);
 const RECENCY_BOOST_MAX = ${SEARCH_RECENCY_BOOST_MAX};
+const SEGMENTER_LOCALE = ${localeJson};
 const DEFAULT_LIMIT = 20;
 const BM25_K1 = 1.2;
 const BM25_B = 0.75;
@@ -2961,44 +3476,59 @@ function tokenize(value) {
   }
 
   const tokens = [];
+  const cjkRuns = Array.from(
+    text.matchAll(/[\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Hangul}]+/gu),
+    (match) => match[0],
+  );
+  const nonCjkText = text.replace(
+    /[\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Hangul}]+/gu,
+    ' ',
+  );
+  let segmented = false;
+
   if (typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function') {
     try {
-      const segmenter = new Intl.Segmenter(undefined, { granularity: 'word' });
-      for (const part of segmenter.segment(text)) {
+      const segmenter = new Intl.Segmenter(SEGMENTER_LOCALE, { granularity: 'word' });
+      for (const part of segmenter.segment(nonCjkText)) {
         if (part.isWordLike && isUsefulToken(part.segment)) {
           tokens.push(part.segment);
         }
       }
+      segmented = true;
     } catch {
       // Fall through to regex tokenization.
     }
   }
 
-  for (const match of text.matchAll(/[\\p{Letter}\\p{Number}]+/gu)) {
-    if (isUsefulToken(match[0])) {
-      tokens.push(match[0]);
+  if (!segmented) {
+    for (const match of nonCjkText.matchAll(/[\\p{Letter}\\p{Number}]+/gu)) {
+      if (isUsefulToken(match[0])) {
+        tokens.push(match[0]);
+      }
     }
   }
 
-  for (const match of text.matchAll(/[\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Hangul}]+/gu)) {
-    tokens.push(...buildNgrams(match[0], 2));
+  for (const run of cjkRuns) {
+    tokens.push(...buildCjkTokens(run));
   }
 
   return tokens;
 }
 
-function buildNgrams(value, size) {
-  const normalized = Array.from(value);
-  if (normalized.length <= size) {
-    return isUsefulToken(value) ? [value] : [];
+function buildCjkTokens(value) {
+  const characters = Array.from(value);
+  const tokens = new Set();
+  if (isUsefulToken(value)) {
+    tokens.add(value);
   }
 
-  const tokens = [];
-  for (let index = 0; index <= normalized.length - size; index += 1) {
-    tokens.push(normalized.slice(index, index + size).join(''));
+  if (characters.length > 2) {
+    for (let index = 0; index <= characters.length - 2; index += 1) {
+      tokens.add(characters.slice(index, index + 2).join(''));
+    }
   }
-  tokens.push(value);
-  return tokens;
+
+  return Array.from(tokens);
 }
 
 function isUsefulToken(value) {
@@ -3104,7 +3634,7 @@ function normalizeLimit(value) {
 `;
 }
 
-function buildSitemapXml(site, emitted, generatedAt, stylesheetHref = '') {
+function buildSitemapXml(site, emitted, stylesheetHref = '') {
   const entries = [
     ...(emitted.frontPage && emitted.frontPage.includeInSitemap !== false
       ? [{
@@ -3153,7 +3683,7 @@ function buildSitemapXml(site, emitted, generatedAt, stylesheetHref = '') {
   return `<?xml version="1.0" encoding="UTF-8"?>${stylesheet}\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${body}\n</urlset>`;
 }
 
-function buildFeedXml(site, emitted, generatedAt) {
+function buildFeedXml(site, emitted, feedGeneratedAt) {
   const channelLink = resolveSiteUrl(site.url, '/');
   const selfLink = resolveSiteUrl(site.url, '/feed.xml');
   const items = [...emitted.posts]
@@ -3165,12 +3695,12 @@ function buildFeedXml(site, emitted, generatedAt) {
     })
     .join('\n');
 
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n  <channel>\n    <title>${escapeXml(site.title)}</title>\n    <link>${escapeXml(channelLink)}</link>\n    <description>${escapeXml(site.description)}</description>\n    <language>${site.locale}</language>\n    <lastBuildDate>${generatedAt.toUTCString()}</lastBuildDate>\n    <atom:link href="${escapeXml(selfLink)}" rel="self" type="application/rss+xml" />\n${items}\n  </channel>\n</rss>`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n  <channel>\n    <title>${escapeXml(site.title)}</title>\n    <link>${escapeXml(channelLink)}</link>\n    <description>${escapeXml(site.description)}</description>\n    <language>${site.locale}</language>\n    <lastBuildDate>${feedGeneratedAt.toUTCString()}</lastBuildDate>\n    <atom:link href="${escapeXml(selfLink)}" rel="self" type="application/rss+xml" />\n${items}\n  </channel>\n</rss>`;
 }
 
 function buildRobotsTxt(site) {
   const lines = ['User-agent: *'];
-  if (site.indexing === false) {
+  if (site.robots?.allow_indexing === false) {
     lines.push('Disallow: /');
     return `${lines.join('\n')}\n`;
   }
@@ -3183,15 +3713,15 @@ function buildRobotsTxt(site) {
 }
 
 function shouldGenerateRobotsTxt(options) {
-  return options.generateSpecialFiles && options.generateRobotsTxt !== false;
+  return options.generateRobotsTxt !== false;
 }
 
-function shouldGenerateFeed(options) {
-  return options.generateSpecialFiles && options.generateFeed !== false;
+function shouldGenerateFeed(state) {
+  return state.previewData.site.feed.enabled === true;
 }
 
-function shouldGenerateSearchArtifacts(state, options) {
-  return options.generateSpecialFiles && state.previewData.site.search === true;
+function shouldGenerateSearchArtifacts(state) {
+  return state.previewData.site.search.enabled === true;
 }
 
 function getContentType(assetPath) {
@@ -3200,6 +3730,7 @@ function getContentType(assetPath) {
     html: 'text/html',
     css: 'text/css',
     js: 'application/javascript',
+    mjs: 'application/javascript',
     json: 'application/json',
     xml: 'application/xml',
     txt: 'text/plain',
@@ -3240,11 +3771,44 @@ function resolveSiteUrl(siteUrl, relativePath) {
 }
 
 function hasCanonicalSiteUrl(siteUrl) {
-  return typeof siteUrl === 'string' && siteUrl.trim() !== '';
+  if (typeof siteUrl !== 'string' || !siteUrl.trim()) {
+    return false;
+  }
+  try {
+    return normalizeSiteOrigin(siteUrl) === siteUrl;
+  } catch {
+    return false;
+  }
 }
 
 function toDate(value) {
-  return value ? new Date(value) : new Date();
+  if (value instanceof Date) {
+    const timestamp = value.getTime();
+    if (!Number.isFinite(timestamp)) {
+      throw new Error('Invalid RFC 3339 timestamp');
+    }
+    return new Date(timestamp);
+  }
+
+  if (typeof value !== 'string' || !value) {
+    throw new Error(`Invalid RFC 3339 timestamp: ${String(value)}`);
+  }
+
+  const timestampMatch = value.match(RFC3339_TIMESTAMP_PATTERN);
+  if (!timestampMatch) {
+    throw new Error(`Invalid RFC 3339 timestamp: ${value}`);
+  }
+
+  const isLeapSecond = timestampMatch[2] === '60';
+  const parseValue = isLeapSecond
+    ? `${timestampMatch[1]}59${timestampMatch[3] || ''}${timestampMatch[4]}`
+    : value;
+  const timestamp = Date.parse(parseValue);
+  if (!Number.isFinite(timestamp)) {
+    throw new Error(`Invalid RFC 3339 timestamp: ${value}`);
+  }
+
+  return new Date(timestamp + (isLeapSecond ? 1000 : 0));
 }
 
 function formatUtcIsoSeconds(value) {