@zeropress/build-core 0.7.1 → 0.7.3

package/README.md

@@ -165,7 +165,7 @@ 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`.
 
-Theme packages use fixed safety limits shared with `@zeropress/theme-validator`: at most 128 entries, 1 MiB per file, and 4 MiB in total expanded 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 also rejected so directory and ZIP adapters use the same cross-platform identity. `buildSite()` validates the same limits for an already-loaded in-memory package. Packaged ZIP input is handled by `@zeropress/theme`, which additionally limits the archive itself to 2 MiB.
+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.
 
@@ -182,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeropress/build-core",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Shared ZeroPress build core",
   "type": "module",
   "license": "MIT",
@@ -30,15 +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.1",
-    "@zeropress/theme-validator": "0.7.1",
-    "highlight.js": "11.11.1",
-    "markdown-it": "14.3.0",
+    "@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.6"
+    "sanitize-html": "2.17.7"
   }
 }

package/src/api/build-site.js

@@ -2,6 +2,7 @@ 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';
@@ -52,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];
@@ -261,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',
       {
@@ -273,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),
@@ -294,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),
@@ -349,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,
@@ -373,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,
@@ -398,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),
@@ -419,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),
@@ -1291,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 || '',
@@ -1348,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 || '',
@@ -1681,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) : '',
@@ -1696,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
@@ -1722,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,
@@ -1964,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,
@@ -1991,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,
@@ -3187,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)

package/src/render/content-renderer.js

@@ -59,7 +59,7 @@ const CONTENT_SANITIZER_OPTIONS = {
   allowIframeRelativeUrls: true,
   parseStyleAttributes: false,
   selfClosing: ['img', 'br', 'hr', 'input', 'source', 'track'],
-  nonTextTags: ['script', 'style', 'textarea', 'option', 'xmp'],
+  nonTextTags: ['script', 'style', 'template', 'noscript', 'textarea', 'option', 'xmp'],
   transformTags: {
     a: transformAnchor,
     th: transformTableCell,