@zeropress/build-core 0.7.0 → 0.7.3

package/README.md

@@ -107,7 +107,7 @@ Notes:
 - `previewData` must already satisfy the canonical preview-data contract
 - `themePackage` must already be a validated in-memory theme package
 - `sitemap.xml` is emitted only when `site.url` is a non-empty canonical URL
-- `feed.xml` is emitted only when `site.feed.enabled` is not `false`, `site.url` is a non-empty canonical URL, and `generateFeed` is not `false`
+- `feed.xml` is emitted only when `site.feed.enabled` is not `false`, `site.url` is a non-empty canonical URL, and `generateFeed` is not `false`; its `lastBuildDate` is derived from required `previewData.generated_at`, never the build machine clock
 - callers may pass `sitemapStylesheetHref` to add an XML stylesheet processing instruction to generated `sitemap.xml`
 - fallback `robots.txt` is emitted when `generateRobotsTxt` is not `false`
 - fallback `robots.txt` uses the effective `site.robots.allow_indexing` policy; omitted Preview Data defaults to `true`, `false` emits `Disallow: /`, and `true` emits `Allow: /`
@@ -165,10 +165,14 @@ Theme validation is enforced through:
 
 `buildSiteFromThemeDir()` is the convenience entry point that loads a theme directory and converts it into the required in-memory `themePackage`.
 
-JavaScript theme assets are emitted as provided. Build-core may hash output filenames, but it does not rewrite or minify JavaScript content.
+Theme packages use fixed safety limits shared with `@zeropress/theme-validator`: at most 128 entries, 1 MiB per file, and 4 MiB in total content. `buildSiteFromThemeDir()` normalizes equivalent spellings such as `theme`, `theme/`, and `theme/.` before checking the final entry, requires that final entry to be real rather than a symbolic link, pins an accepted root to its canonical path, checks filesystem sizes before reading file bodies, and rejects every symbolic link inside the root, including links that stay inside the theme directory and dangling links. Symbolic links in ancestor path components are allowed. Package paths reject literal backslashes and exact empty, `.` or `..` segments while ordinary filenames such as `name..txt` remain valid. Directory entries that collide after NFC and case normalization are rejected so every package has one cross-platform path identity. `buildSite()` validates the same limits for an already-loaded in-memory package.
+
+Theme CSS and JavaScript assets are emitted byte-for-byte as provided. `custom_css.content` is checked for nonblank content but otherwise retains its original whitespace, comments, strings, and syntax. Build Core may hash output filenames; every hash is computed from the bytes actually emitted, and Build Core does not rewrite or minify CSS or JavaScript. Both `.js` and `.mjs` outputs use a JavaScript MIME type.
 
 User-defined scalar metadata under `site.meta`, `post.meta`, `page.meta`, and item `meta` is always HTML-escaped during template interpolation. Names ending in `_html` or `_url` do not opt metadata into raw rendering; use the explicit content and custom HTML contracts for trusted raw markup.
 
+Post/Page HTML, Markdown raw HTML, and text-widget HTML pass through a parser-based explicit allowlist. Safe structural, media, table, task-list, and alert markup is retained; event handlers and unsafe URL schemes are removed. Links permit relative URLs, HTTP(S), `mailto:`, and `tel:`. Media and iframe URLs permit relative URLs or HTTP(S), and protocol-relative URLs are rejected. Each `srcset` candidate is checked independently. This sanitizer boundary does not include trusted `custom_html` slots or `standalone_html`, which remain intentionally unchanged.
+
 Build-core derives:
 
 - index/archive/category/tag routes
@@ -178,8 +182,22 @@ Build-core derives:
 - localized fallback `published_at` / `updated_at` values plus unconditional `published_at_iso` / `updated_at_iso` values
 - datetime formatting from `site.locale`, `site.timezone`, `site.date_style`, and `site.time_style`
 - `reading_time`
+- effective `post.summary` and `page.summary` values for theme listings and metadata
 - a route-root `comments` discriminated context
 
+### Authored excerpts and runtime summaries
+
+Preview Data `post.excerpt` and `page.excerpt` are authored values. Build Core does not replace them with body text; an omitted Page excerpt becomes `""` in the runtime context. It derives a separate `summary` once from each prepared Post or Page:
+
+- a trim-nonempty authored excerpt becomes the summary after trimming only its outer whitespace, without a length limit
+- otherwise, Build Core uses visible text from the rendered HTML, removes comments and non-visible `script`, `style`, `template`, and `noscript` content, removes a leading H1 when it matches the document title, decodes entities, and collapses whitespace
+- a derived body summary is at most 160 Unicode code points, including a final `…` when truncated
+- a document with no displayable text has `summary: ""`
+
+Both fields are available on detail Post/Page contexts. The same precomputed summary is propagated to `posts.items[]`, archive and taxonomy items, Post/Page collection items, collection cursor `prev`/`next` items, and `post.prev`/`post.next`. Themes should use `summary` for optional list/card copy and retain `excerpt` for an explicitly authored detail lede.
+
+Post/Page metadata descriptions use `summary`; ordinary detail routes do not fall back to `site.description`. A Page used as the front page uses `site.description` only when neither an authored nor body-derived summary exists. RSS item descriptions use Post summaries. Native/Pagefind search continues to index the authored excerpt separately and creates a query-specific body excerpt when needed; it does not substitute the general runtime summary. User-defined `meta.description` keys remain ordinary generator/theme metadata and receive no special Build Core interpretation.
+
 Every ordinary rendered route receives effective feature state on `site`, regardless of whether the corresponding Preview Data preference was omitted:
 
 ```js
@@ -250,6 +268,10 @@ The active state requires all of the following:
 - the post or page has `allow_comments: true` and a positive `public_id`
 - the ZeroPress provider has a non-empty item `comments.request_token`
 
+Post and Page `allow_comments` are optional Preview Data fields. Omission is
+normalized to `false`; producers should emit `true` only for items that opt in
+to comments.
+
 The theme-facing `request_token` key exists only for the `zeropress` provider. Preview-data items may retain ignored token metadata for `wordpress` or inactive comment states, but Build Core drops it. An active `wordpress` context omits that key entirely. Post/page objects, structured list items, collection items and cursors, adjacent-item summaries, search data, feeds, and non-detail route roots do not receive a copy of the item token. Themes must use the route-root `comments.enabled` discriminator.
 
 The canonical `preview-data v0.7` site contract uses:
@@ -304,7 +326,7 @@ For ordinary theme-rendered HTML routes, site customization order is determinist
 
 Closing `</head>` and `</body>` tags are matched case-insensitively. If a configured custom HTML slot has no matching closing tag, the build fails with the route, output path, missing tag, and remediation guidance instead of silently dropping the configured content. Themes that consume these slots must render the corresponding closing tag. A `site.front_page.type: "standalone_html"` document remains byte-for-byte independent and does not receive favicon, generator, custom CSS, or custom HTML injection.
 
-Native search artifacts are emitted only when preview-data does not set `site.search.enabled: false` and the active theme declares `features.search: true`. When that effective search state is disabled, search widgets are omitted from resolved widget items while their widget areas and non-search siblings remain available. `search_pagefind.js` is a Pagefind adapter that can replace `search.js` after a post-build Pagefind step.
+Native search artifacts are emitted only when preview-data does not set `site.search.enabled: false` and the active theme declares `features.search: true`. When that effective search state is disabled, search widgets are omitted from resolved widget items while their widget areas and non-search siblings remain available. The native adapter tokenizes non-CJK text with `Intl.Segmenter(site.locale)` and falls back to Unicode word matching only when Segmenter is unavailable or fails. CJK runs contribute their full token and unique bigrams while repeated occurrences still contribute term frequency. `search_pagefind.js` is a Pagefind adapter that can replace `search.js` after a post-build Pagefind step.
 
 When archive is disabled or `archive.html` is missing, archive routes and archive widget items are omitted while authored menu items, widget areas, and non-archive siblings remain unchanged. No archive output path is claimed in that state, so content may use `/archive`. Feed behaves the same way for `feed.xml`: a disabled feed neither emits nor claims the file. Enabled feeds add one RSS autodiscovery link to `meta.head_tags` on ordinary theme-rendered routes; `404.html` and standalone front-page HTML do not receive it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeropress/build-core",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "Shared ZeroPress build core",
   "type": "module",
   "license": "MIT",
@@ -30,14 +30,15 @@
     "test": "node --test"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=22.22.0"
   },
   "dependencies": {
     "@zeropress/slug-policy": "0.2.1",
-    "@zeropress/preview-data-validator": "0.7.0",
-    "@zeropress/theme-validator": "0.7.0",
-    "highlight.js": "11.11.1",
-    "markdown-it": "14.3.0",
-    "markdown-it-anchor": "9.2.1"
+    "@zeropress/preview-data-validator": "0.7.3",
+    "@zeropress/theme-validator": "0.7.3",
+    "highlight.js": "11.12.0",
+    "markdown-it": "15.0.0",
+    "markdown-it-anchor": "9.2.1",
+    "sanitize-html": "2.17.7"
   }
 }

package/src/api/build-site.js

@@ -2,8 +2,10 @@ import { createHash } from 'node:crypto';
 import { assertPreviewData } from '@zeropress/preview-data-validator';
 import { isSafeSlugSegment, normalizeStoredSlug } from '@zeropress/slug-policy';
 import { validateThemeFiles } from '@zeropress/theme-validator';
+import sanitizeHtml from 'sanitize-html';
 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 = {
@@ -51,6 +53,8 @@ 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 GENERATED_SUMMARY_MAX_CODE_POINTS = 160;
+const SUMMARY_TEXT_BOUNDARY_TAG_PATTERN = /<\/?(?:h[1-6]|p|br|hr|pre|ul|ol|li|blockquote|aside|figure|figcaption|table|thead|tbody|tfoot|tr|th|td|div|nav)\b[^>]*>/gi;
 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];
@@ -64,6 +68,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);
@@ -109,7 +114,7 @@ export async function buildSite(input) {
 
   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');
   }
 
@@ -119,11 +124,11 @@ export async function buildSite(input) {
       state.writer,
       state.summaries,
       'sitemap.xml',
-      buildSitemapXml(state.previewData.site, state.emitted, state.generatedAt, options.sitemapStylesheetHref),
+      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.generatedAt), 'application/rss+xml');
+      await writeOutput(state.writer, state.summaries, 'feed.xml', buildFeedXml(state.previewData.site, state.emitted, state.feedGeneratedAt), 'application/rss+xml');
     }
   }
   if (shouldGenerateRobotsTxt(options)) {
@@ -151,8 +156,8 @@ async function createBuildState(input, 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);
   }
@@ -175,7 +180,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: [],
@@ -259,6 +264,7 @@ async function renderFrontPage(state, route) {
       ...route.page,
       url: currentUrl,
     };
+    const description = page.summary || state.previewData.site.description;
     let html = await state.engine.render(
       'page',
       {
@@ -271,7 +277,7 @@ async function renderFrontPage(state, route) {
         meta: buildPageMeta(state.previewData.site, {
           currentUrl,
           title: buildFrontPageTitle(state.previewData.site),
-          description: page.excerpt,
+          description,
           ogType: 'website',
           image: page.featured_image,
           robotsNoindex: shouldNoindexDocument(page),
@@ -292,7 +298,7 @@ async function renderFrontPage(state, route) {
     state.emitted.frontPage = {
       url: currentUrl,
       title: page.title,
-      description: page.excerpt,
+      description,
       updatedAt: page.updated_at_iso,
       includeInFeed: false,
       includeInSitemap: !isDelistedDocument(page),
@@ -347,7 +353,7 @@ async function renderPost(state, post) {
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
         title: buildDocumentTitle(post.title, state.previewData.site.title),
-        description: post.excerpt,
+        description: post.summary,
         ogType: 'article',
         image: post.featured_image,
         publishedTime: post.published_at_iso,
@@ -371,7 +377,7 @@ async function renderPost(state, post) {
     state.emitted.posts.push({
       url: currentUrl,
       title: post.title,
-      description: post.excerpt,
+      description: post.summary,
       publishedAt: post.published_at_iso,
       updatedAt: post.updated_at_iso,
       status: post.status,
@@ -396,7 +402,7 @@ async function renderPage(state, page) {
         currentUrl,
         canonicalUrl,
         title: buildDocumentTitle(page.title, state.previewData.site.title),
-        description: page.excerpt,
+        description: page.summary,
         ogType: 'website',
         image: page.featured_image,
         robotsNoindex: shouldNoindexDocument(page),
@@ -417,7 +423,7 @@ async function renderPage(state, page) {
   state.emitted.pages.push({
     url: currentUrl,
     title: page.title,
-    description: page.excerpt,
+    description: page.summary,
     updatedAt: page.updated_at_iso,
     status: page.status,
     includeInSitemap: page.omit_from_sitemap !== true && !isDelistedDocument(page),
@@ -775,8 +781,8 @@ function normalizeWidgetItem(item, media_origin) {
 }
 
 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) {
@@ -1289,6 +1295,7 @@ function buildCollectionPageSummary(page, frontPage, pageReferencePath) {
     slug: page.slug,
     url: frontPage?.type === 'page' && frontPage.page_path === pageReferencePath ? '/' : page.url,
     excerpt: page.excerpt || '',
+    summary: page.summary || '',
     featured_image: page.featured_image || '',
     updated_at: page.updated_at || '',
     updated_at_iso: page.updated_at_iso || '',
@@ -1346,6 +1353,7 @@ function buildCollectionCursorItemSummary(item) {
     slug: item.slug,
     url: item.url,
     excerpt: item.excerpt || '',
+    summary: item.summary || '',
     featured_image: item.featured_image || '',
     updated_at: item.updated_at || '',
     updated_at_iso: item.updated_at_iso || '',
@@ -1679,12 +1687,15 @@ function preparePage(page, site) {
   const renderedDocument = renderDocument(page.content, documentType);
   const permalink = resolvePagePermalink(site, page);
   const pageFields = { ...page };
+  const excerpt = typeof page.excerpt === 'string' ? page.excerpt : '';
   delete pageFields.comments;
 
   return {
     ...pageFields,
     url: permalink.url,
     document_type: documentType,
+    excerpt,
+    summary: buildDocumentSummary(excerpt, renderedDocument.html, page.title),
     html: renderedDocument.html,
     toc: renderedDocument.toc,
     updated_at: page.updated_at_iso ? formatTimestamp(page.updated_at_iso, site) : '',
@@ -1694,6 +1705,7 @@ function preparePage(page, site) {
 function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug) {
   const documentType = normalizeDocumentType(post.document_type);
   const renderedDocument = renderDocument(post.content, documentType);
+  const excerpt = typeof post.excerpt === 'string' ? post.excerpt : '';
   const author = authorsById.get(post.author_id);
   const permalink = resolvePermalink(site, 'posts', post);
   const categories = post.category_slugs
@@ -1720,7 +1732,8 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug) {
     url: permalink.url,
     content: post.content,
     document_type: documentType,
-    excerpt: post.excerpt,
+    excerpt,
+    summary: buildDocumentSummary(excerpt, renderedDocument.html, post.title),
     published_at_iso: post.published_at_iso,
     updated_at_iso: post.updated_at_iso,
     author_id: post.author_id,
@@ -1962,6 +1975,7 @@ function buildStructuredPostSummary(post) {
     slug: post.slug,
     url: post.url,
     excerpt: post.excerpt,
+    summary: post.summary,
     published_at: post.published_at,
     published_at_iso: post.published_at_iso,
     reading_time: post.reading_time,
@@ -1989,6 +2003,7 @@ function buildAdjacentPostSummary(post) {
     slug: post.slug,
     url: post.url,
     excerpt: post.excerpt,
+    summary: post.summary,
     published_at: post.published_at,
     published_at_iso: post.published_at_iso,
     data: post.data,
@@ -2248,61 +2263,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,
@@ -2310,50 +2270,37 @@ 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',
   };
 }
@@ -3253,6 +3200,63 @@ function buildSearchPageItem(page, url, pageReferencePath) {
   };
 }
 
+function buildDocumentSummary(excerpt, html, title) {
+  const authoredExcerpt = String(excerpt || '').trim();
+  if (authoredExcerpt) {
+    return authoredExcerpt;
+  }
+
+  const visibleText = htmlToSummaryText(html, title);
+  const codePoints = [...visibleText];
+  if (codePoints.length <= GENERATED_SUMMARY_MAX_CODE_POINTS) {
+    return visibleText;
+  }
+
+  const truncated = codePoints
+    .slice(0, GENERATED_SUMMARY_MAX_CODE_POINTS - 1)
+    .join('')
+    .trimEnd();
+  return `${truncated}…`;
+}
+
+function htmlToSummaryText(html, title) {
+  let source = removeNonVisibleSummaryHtml(html);
+  const leadingHeading = source.match(/<h1\b[^>]*>([\s\S]*?)<\/h1\s*>/i);
+  if (
+    leadingHeading
+    && htmlFragmentToSummaryText(source.slice(0, leadingHeading.index)) === ''
+    && normalizeComparableSummaryText(htmlFragmentToSummaryText(leadingHeading[1]))
+      === normalizeComparableSummaryText(title)
+  ) {
+    source = source.slice(0, leadingHeading.index)
+      + source.slice(leadingHeading.index + leadingHeading[0].length);
+  }
+
+  return htmlFragmentToSummaryText(source);
+}
+
+function removeNonVisibleSummaryHtml(html) {
+  return String(html || '')
+    .replace(/<(script|style|template|noscript)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+}
+
+function htmlFragmentToSummaryText(html) {
+  const textWithTagBoundaries = String(html || '').replace(SUMMARY_TEXT_BOUNDARY_TAG_PATTERN, ' ');
+  const decodedText = sanitizeHtml(textWithTagBoundaries, {
+    allowedTags: [],
+    allowedAttributes: {},
+    parser: {
+      decodeEntities: true,
+    },
+  });
+  return normalizeSearchText(decodeHtmlEntities(decodedText));
+}
+
+function normalizeComparableSummaryText(value) {
+  return normalizeSearchText(value).normalize('NFC');
+}
+
 function buildSearchHeadings(toc) {
   return Array.isArray(toc)
     ? toc.map((item) => normalizeSearchText(item?.title)).filter(Boolean)
@@ -3296,11 +3300,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;
@@ -3540,44 +3546,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) {
@@ -3683,7 +3704,7 @@ function normalizeLimit(value) {
 `;
 }
 
-function buildSitemapXml(site, emitted, generatedAt, stylesheetHref = '') {
+function buildSitemapXml(site, emitted, stylesheetHref = '') {
   const entries = [
     ...(emitted.frontPage && emitted.frontPage.includeInSitemap !== false
       ? [{
@@ -3732,7 +3753,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]
@@ -3744,7 +3765,7 @@ 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) {
@@ -3779,6 +3800,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',
@@ -3830,7 +3852,33 @@ function hasCanonicalSiteUrl(siteUrl) {
 }
 
 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) {

package/src/assets/asset-processor.js

@@ -1,19 +1,6 @@
 import { createHash } from 'node:crypto';
 
 export class AssetProcessor {
-  async processCSS(css) {
-    return css
-      .replace(/\/\*[\s\S]*?\*\//g, '')
-      .replace(/\s+/g, ' ')
-      .replace(/\s*([{}:;,>+~])\s*/g, '$1')
-      .replace(/;}/g, '}')
-      .trim();
-  }
-
-  async processJavaScript(js) {
-    return js;
-  }
-
   generateAssetHash(content) {
     const hash = createHash('sha256');
     hash.update(content);

package/src/render/content-renderer.js

@@ -1,6 +1,7 @@
 import MarkdownIt from 'markdown-it';
 import hljs from 'highlight.js';
 import anchor from 'markdown-it-anchor';
+import sanitizeHtmlParser from 'sanitize-html';
 
 const TOC_LEVELS = new Set([2, 3, 4]);
 const ALERT_TYPES = new Map([
@@ -19,6 +20,57 @@ const ADMONITION_CONTAINER_TYPES = new Map([
   ['CAUTION', { className: 'caution', title: 'Caution' }],
   ['DANGER', { className: 'caution', title: 'Danger' }],
 ]);
+const CONTENT_ALLOWED_TAGS = [
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'p', 'br', 'hr',
+  'strong', 'b', 'em', 'u', 's', 'sup', 'sub', 'code', 'pre',
+  'a', 'img',
+  'ul', 'ol', 'li',
+  'blockquote', 'aside',
+  'figure', 'figcaption', 'picture', 'source',
+  'video', 'audio', 'track',
+  'table', 'thead', 'tbody', 'tr', 'th', 'td',
+  'div', 'span', 'nav',
+  'iframe', 'input',
+];
+const CONTENT_ALLOWED_ATTRIBUTES = {
+  a: ['href', 'title', 'class', 'id', 'target', 'rel'],
+  aside: ['role', 'class', 'id'],
+  img: ['src', 'srcset', 'sizes', 'alt', 'title', 'class', 'id', 'width', 'height', 'loading', 'decoding'],
+  iframe: ['src', 'width', 'height', 'frameborder', 'allowfullscreen', 'class', 'title'],
+  input: ['type', 'checked', 'disabled', 'class', 'id', 'aria-label'],
+  source: ['src', 'srcset', 'sizes', 'type', 'media', 'width', 'height', 'class', 'id'],
+  th: ['rowspan', 'colspan', 'align', 'class', 'id'],
+  td: ['rowspan', 'colspan', 'align', 'class', 'id'],
+  video: ['src', 'controls', 'controlslist', 'autoplay', 'loop', 'muted', 'playsinline', 'poster', 'preload', 'width', 'height', 'class', 'id', 'title'],
+  audio: ['src', 'controls', 'controlslist', 'autoplay', 'loop', 'muted', 'preload', 'class', 'id', 'title'],
+  track: ['src', 'kind', 'srclang', 'label', 'default', 'class', 'id'],
+  '*': ['class', 'id'],
+};
+const CONTENT_SANITIZER_OPTIONS = {
+  allowedTags: CONTENT_ALLOWED_TAGS,
+  allowedAttributes: CONTENT_ALLOWED_ATTRIBUTES,
+  allowedSchemes: ['http', 'https'],
+  allowedSchemesByTag: {
+    a: ['http', 'https', 'mailto', 'tel'],
+  },
+  allowedSchemesAppliedToAttributes: ['href', 'src', 'poster'],
+  allowProtocolRelative: false,
+  allowIframeRelativeUrls: true,
+  parseStyleAttributes: false,
+  selfClosing: ['img', 'br', 'hr', 'input', 'source', 'track'],
+  nonTextTags: ['script', 'style', 'template', 'noscript', 'textarea', 'option', 'xmp'],
+  transformTags: {
+    a: transformAnchor,
+    th: transformTableCell,
+    td: transformTableCell,
+    video: transformNativeMedia,
+    audio: transformNativeMedia,
+  },
+  exclusiveFilter(frame) {
+    return frame.tag === 'input' && frame.attribs.type !== 'checkbox';
+  },
+};
 
 export function renderDocumentContent(content, documentType = 'markdown') {
   return renderDocument(content, documentType).html;
@@ -429,178 +481,68 @@ function escapeHtml(value) {
 }
 
 function sanitizeHtml(html) {
-  const allowedTags = new Set([
-    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
-    'p', 'br', 'hr',
-    'strong', 'b', 'em', 'u', 's', 'sup', 'sub', 'code', 'pre',
-    'a', 'img',
-    'ul', 'ol', 'li',
-    'blockquote', 'aside',
-    'figure', 'figcaption', 'picture', 'source',
-    'video', 'audio', 'track',
-    'table', 'thead', 'tbody', 'tr', 'th', 'td',
-    'div', 'span', 'nav',
-    'iframe', 'input',
-  ]);
-
-  const allowedAttributes = {
-    a: new Set(['href', 'title', 'class', 'id', 'target', 'rel']),
-    aside: new Set(['role', 'class', 'id']),
-    img: new Set(['src', 'srcset', 'sizes', 'alt', 'title', 'class', 'id', 'width', 'height', 'loading', 'decoding']),
-    iframe: new Set(['src', 'width', 'height', 'frameborder', 'allowfullscreen', 'class', 'title']),
-    input: new Set(['type', 'checked', 'disabled', 'class', 'id', 'aria-label']),
-    source: new Set(['src', 'srcset', 'sizes', 'type', 'media', 'width', 'height', 'class', 'id']),
-    th: new Set(['rowspan', 'colspan', 'align', 'class', 'id']),
-    td: new Set(['rowspan', 'colspan', 'align', 'class', 'id']),
-    video: new Set(['src', 'controls', 'controlslist', 'autoplay', 'loop', 'muted', 'playsinline', 'poster', 'preload', 'width', 'height', 'class', 'id', 'title']),
-    audio: new Set(['src', 'controls', 'controlslist', 'autoplay', 'loop', 'muted', 'preload', 'class', 'id', 'title']),
-    track: new Set(['src', 'kind', 'srclang', 'label', 'default', 'class', 'id']),
-    '*': new Set(['class', 'id']),
-  };
-
-  const safeUriPattern = /^(?:(?:https?|mailto|tel):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
-
-  const stripped = html
-    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '')
-    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, '');
-
-  const sanitized = stripped.replace(/<\/?([a-zA-Z][a-zA-Z0-9]*)\b([^>]*)?\/?>/g, (match, tag, attributeString) => {
-    const normalizedTag = tag.toLowerCase();
-
-    if (match.startsWith('</')) {
-      return allowedTags.has(normalizedTag) ? `</${normalizedTag}>` : '';
-    }
-
-    if (!allowedTags.has(normalizedTag)) {
-      return '';
-    }
-
-    const tagAllowedAttributes = allowedAttributes[normalizedTag] || new Set();
-    const globalAllowedAttributes = allowedAttributes['*'];
-    const filteredAttributes = [];
-    let anchorTarget = '';
-    let anchorRel = '';
-    let tableCellAlignClass = '';
-
-    if (attributeString) {
-      const attributePattern = /([a-zA-Z][a-zA-Z0-9-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
-      let attributeMatch;
-
-      while ((attributeMatch = attributePattern.exec(attributeString)) !== null) {
-        const attributeName = attributeMatch[1].toLowerCase();
-        const attributeValue = attributeMatch[2] ?? attributeMatch[3] ?? attributeMatch[4] ?? '';
-
-        if (!tagAllowedAttributes.has(attributeName) && !globalAllowedAttributes.has(attributeName)) {
-          continue;
-        }
-
-        if ((attributeName === 'href' || attributeName === 'src' || attributeName === 'poster') && !safeUriPattern.test(attributeValue)) {
-          continue;
-        }
-
-        if (normalizedTag === 'a' && attributeName === 'target') {
-          const target = sanitizeAnchorTarget(attributeValue);
-          if (!target) {
-            continue;
-          }
-          anchorTarget = target;
-          continue;
-        }
-
-        if (normalizedTag === 'a' && attributeName === 'rel') {
-          const rel = sanitizeRelList(attributeValue);
-          if (!rel) {
-            continue;
-          }
-          anchorRel = rel;
-          continue;
-        }
-
-        if (attributeName === 'srcset' && !isSafeSrcset(attributeValue, safeUriPattern)) {
-          continue;
-        }
-
-        if (attributeName === 'controlslist') {
-          const controlsList = sanitizeControlsList(attributeValue);
-          if (!controlsList) {
-            continue;
-          }
-          filteredAttributes.push(`${attributeName}="${controlsList}"`);
-          continue;
-        }
+  return sanitizeHtmlParser(html, CONTENT_SANITIZER_OPTIONS);
+}
 
-        if ((normalizedTag === 'th' || normalizedTag === 'td') && (attributeName === 'rowspan' || attributeName === 'colspan')) {
-          const span = sanitizePositiveIntegerAttribute(attributeValue);
-          if (!span) {
-            continue;
-          }
-          filteredAttributes.push(`${attributeName}="${span}"`);
-          continue;
-        }
+function transformAnchor(tagName, attributes) {
+  const transformed = { ...attributes };
+  const target = sanitizeAnchorTarget(transformed.target);
+  const rel = sanitizeRelList(transformed.rel);
 
-        if ((normalizedTag === 'th' || normalizedTag === 'td') && attributeName === 'align') {
-          const alignment = sanitizeTableAlignment(attributeValue);
-          if (!alignment) {
-            continue;
-          }
-          tableCellAlignClass = `zp-align-${alignment}`;
-          continue;
-        }
+  if (target) {
+    transformed.target = target;
+  } else {
+    delete transformed.target;
+  }
 
-        if (normalizedTag === 'input' && attributeName === 'type' && attributeValue !== 'checkbox') {
-          continue;
-        }
+  const safeRel = target === '_blank' ? ensureBlankTargetRel(rel) : rel;
+  if (safeRel) {
+    transformed.rel = safeRel;
+  } else {
+    delete transformed.rel;
+  }
 
-        filteredAttributes.push(`${attributeName}="${attributeValue}"`);
-      }
-    }
+  return { tagName, attribs: transformed };
+}
 
-    if (tableCellAlignClass) {
-      appendClassAttribute(filteredAttributes, tableCellAlignClass);
-    }
+function transformTableCell(tagName, attributes) {
+  const transformed = { ...attributes };
 
-    if (normalizedTag === 'a') {
-      if (anchorTarget) {
-        filteredAttributes.push(`target="${anchorTarget}"`);
-      }
-      if (anchorTarget === '_blank') {
-        anchorRel = ensureBlankTargetRel(anchorRel);
-      }
-      if (anchorRel) {
-        filteredAttributes.push(`rel="${anchorRel}"`);
-      }
+  for (const attributeName of ['rowspan', 'colspan']) {
+    const value = sanitizePositiveIntegerAttribute(transformed[attributeName]);
+    if (value) {
+      transformed[attributeName] = value;
+    } else {
+      delete transformed[attributeName];
     }
+  }
 
-    const isSelfClosing = match.endsWith('/>') || normalizedTag === 'br' || normalizedTag === 'hr' || normalizedTag === 'img' || normalizedTag === 'input' || normalizedTag === 'source' || normalizedTag === 'track';
-    const attributeSuffix = filteredAttributes.length > 0 ? ` ${filteredAttributes.join(' ')}` : '';
-    return isSelfClosing ? `<${normalizedTag}${attributeSuffix} />` : `<${normalizedTag}${attributeSuffix}>`;
-  });
-
-  return sanitized
-    .split(/(<[^>]+>)/g)
-    .map((part) => {
-      if (part.startsWith('<') && part.endsWith('>')) {
-        return part;
-      }
+  const alignment = sanitizeTableAlignment(transformed.align);
+  delete transformed.align;
+  if (alignment) {
+    transformed.class = appendClassName(transformed.class, `zp-align-${alignment}`);
+  }
 
-      return part.replace(/&(?!(?:[a-zA-Z]+|#\d+|#x[0-9a-fA-F]+);)/g, '&amp;');
-    })
-    .join('');
+  return { tagName, attribs: transformed };
 }
 
-function appendClassAttribute(attributes, className) {
-  const classIndex = attributes.findIndex((attribute) => attribute.startsWith('class="'));
-  if (classIndex === -1) {
-    attributes.push(`class="${className}"`);
-    return;
+function transformNativeMedia(tagName, attributes) {
+  const transformed = { ...attributes };
+  const controlsList = sanitizeControlsList(transformed.controlslist);
+  if (controlsList) {
+    transformed.controlslist = controlsList;
+  } else {
+    delete transformed.controlslist;
   }
+  return { tagName, attribs: transformed };
+}
 
-  const existingValue = attributes[classIndex].slice('class="'.length, -1);
-  const classes = existingValue.split(/\s+/).filter(Boolean);
+function appendClassName(value, className) {
+  const classes = String(value || '').split(/\s+/).filter(Boolean);
   if (!classes.includes(className)) {
     classes.push(className);
   }
-  attributes[classIndex] = `class="${classes.join(' ')}"`;
+  return classes.join(' ');
 }
 
 function sanitizePositiveIntegerAttribute(value) {
@@ -668,18 +610,6 @@ function sanitizeControlsList(value) {
   return tokens.join(' ');
 }
 
-function isSafeSrcset(value, safeUriPattern) {
-  const candidates = String(value)
-    .split(',')
-    .map((candidate) => candidate.trim())
-    .filter(Boolean);
-
-  return candidates.length > 0 && candidates.every((candidate) => {
-    const [url] = candidate.split(/\s+/);
-    return Boolean(url) && safeUriPattern.test(url);
-  });
-}
-
 function slugify(value) {
   return String(value || '')
     .toLowerCase()

package/src/theme/format-theme-validation.js

@@ -0,0 +1,54 @@
+export 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: '' };
+}

package/src/theme/load-theme-dir.js

@@ -1,15 +1,51 @@
-import { validateThemeFiles } from '@zeropress/theme-validator';
+import {
+  validateThemeFiles,
+  validateThemePackageLimits,
+} from '@zeropress/theme-validator';
+import { formatThemeValidationFailure } from './format-theme-validation.js';
 
 const TEXT_FILE_EXTENSIONS = new Set(['.html', '.json', '.css', '.js', '.txt', '.svg', '.xml']);
 
 export async function loadThemePackageFromDir(themeDir) {
   const fs = await import('node:fs/promises');
+  const { constants: fsConstants } = await import('node:fs');
   const path = await import('node:path');
+  if (typeof themeDir !== 'string' || !themeDir.trim()) {
+    throw new Error('Theme directory must be a non-empty path');
+  }
+  const requestedThemeDir = path.resolve(themeDir);
 
-  const fileMap = new Map();
-  await readThemeDir(fs, path, themeDir, themeDir, fileMap);
+  const rootStat = await fs.lstat(requestedThemeDir);
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+    throw new Error(`Theme directory must be a real directory and must not be a symbolic link: ${requestedThemeDir}`);
+  }
+  const canonicalThemeDir = await fs.realpath(requestedThemeDir);
+  const confirmedRootStat = await fs.lstat(requestedThemeDir);
+  if (confirmedRootStat.isSymbolicLink() || !confirmedRootStat.isDirectory()) {
+    throw new Error(`Theme directory must be a real directory and must not be a symbolic link: ${requestedThemeDir}`);
+  }
 
-  const validation = await validateThemeFiles(fileMap);
+  const fileMap = new Map();
+  const packageState = {
+    entryCount: 0,
+    fileSizes: new Map(),
+    pathEntries: [],
+    seenCanonicalPaths: new Map(),
+  };
+  await readThemeDir(
+    fs,
+    fsConstants,
+    path,
+    canonicalThemeDir,
+    canonicalThemeDir,
+    fileMap,
+    packageState,
+  );
+
+  const validation = await validateThemeFiles(fileMap, {
+    entryCount: packageState.entryCount,
+    pathEntries: packageState.pathEntries,
+  });
   if (!validation.ok) {
     throw new Error(formatThemeValidationFailure(validation));
   }
@@ -58,82 +94,112 @@ export async function loadThemePackageFromDir(themeDir) {
   };
 }
 
-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),
-    };
+async function readThemeDir(fs, fsConstants, path, rootDir, currentDir, fileMap, packageState) {
+  const entries = [];
+  const directory = await fs.opendir(currentDir);
+  for await (const entry of directory) {
+    packageState.entryCount += 1;
+    assertThemePackageLimits(packageState);
+    entries.push(entry);
   }
-
-  return { file: normalizedPath, path: '' };
-}
-
-async function readThemeDir(fs, path, rootDir, currentDir, fileMap) {
-  const entries = await fs.readdir(currentDir, { withFileTypes: true });
+  entries.sort((left, right) => left.name.localeCompare(right.name, 'en'));
 
   for (const entry of entries) {
     const fullPath = path.join(currentDir, entry.name);
-    const relativePath = path.relative(rootDir, fullPath).replace(/\\/g, '/');
+    const rawRelativePath = path.relative(rootDir, fullPath);
+    const relativePath = rawRelativePath.replace(/\\/g, '/');
+    if (entry.name.includes('\\')) {
+      throw createThemePathError(
+        'PATH_ESCAPE',
+        rawRelativePath,
+        `Backslashes are not allowed in theme package paths: ${rawRelativePath}`,
+        packageState.fileSizes.size,
+      );
+    }
+    const collisionKey = relativePath.normalize('NFC').toLowerCase();
+    const existingPath = packageState.seenCanonicalPaths.get(collisionKey);
+    if (existingPath !== undefined) {
+      throw createThemePathError(
+        'THEME_PATH_COLLISION',
+        relativePath,
+        `Theme package path collision: '${relativePath}' conflicts with '${existingPath}' after NFC and case normalization`,
+        packageState.fileSizes.size,
+      );
+    }
+    packageState.seenCanonicalPaths.set(collisionKey, relativePath);
+    const stat = await fs.lstat(fullPath);
+    const isSymlink = stat.isSymbolicLink();
+    packageState.pathEntries.push({ path: relativePath, isSymlink });
+
+    if (isSymlink) {
+      continue;
+    }
 
-    if (entry.isDirectory()) {
-      await readThemeDir(fs, path, rootDir, fullPath, fileMap);
+    if (stat.isDirectory()) {
+      await readThemeDir(fs, fsConstants, path, rootDir, fullPath, fileMap, packageState);
       continue;
     }
 
-    const ext = path.extname(entry.name).toLowerCase();
-    if (TEXT_FILE_EXTENSIONS.has(ext)) {
-      fileMap.set(relativePath, await fs.readFile(fullPath, 'utf8'));
-    } else {
-      fileMap.set(relativePath, new Uint8Array(await fs.readFile(fullPath)));
+    if (!stat.isFile()) {
+      continue;
+    }
+
+    const noFollow = fsConstants.O_NOFOLLOW || 0;
+    let handle;
+    try {
+      handle = await fs.open(fullPath, fsConstants.O_RDONLY | noFollow);
+      const openedStat = await handle.stat();
+      if (!openedStat.isFile()) {
+        continue;
+      }
+      packageState.fileSizes.set(relativePath, openedStat.size);
+      assertThemePackageLimits(packageState);
+
+      const ext = path.extname(entry.name).toLowerCase();
+      if (TEXT_FILE_EXTENSIONS.has(ext)) {
+        fileMap.set(relativePath, await handle.readFile('utf8'));
+      } else {
+        fileMap.set(relativePath, new Uint8Array(await handle.readFile()));
+      }
+    } catch (error) {
+      if (error?.code === 'ELOOP') {
+        packageState.pathEntries[packageState.pathEntries.length - 1].isSymlink = true;
+        continue;
+      }
+      throw error;
+    } finally {
+      await handle?.close();
     }
   }
 }
 
+function createThemePathError(code, filePath, message, checkedFiles) {
+  return new Error(formatThemeValidationFailure({
+    errors: [{
+      code,
+      path: filePath,
+      message,
+      severity: 'error',
+      category: 'theme_package_paths',
+    }],
+    checkedFiles,
+  }));
+}
+
+function assertThemePackageLimits(packageState) {
+  const errors = validateThemePackageLimits(packageState.fileSizes, {
+    entryCount: packageState.entryCount,
+  });
+  if (errors.length === 0) {
+    return;
+  }
+
+  throw new Error(formatThemeValidationFailure({
+    errors,
+    checkedFiles: packageState.fileSizes.size,
+  }));
+}
+
 function toUint8Array(value) {
   if (value instanceof Uint8Array) {
     return value;