@zeropress/build-core 0.7.4 → 0.7.6

package/README.md

@@ -42,7 +42,28 @@ import {
 } from '@zeropress/build-core';
 ```
 
-## Purpose
+## Rendering a document body
+
+For a document body without a theme or filesystem access:
+
+```js
+import { renderDocument } from '@zeropress/build-core/content';
+
+const { html, toc } = renderDocument(source, 'html'); // html, markdown, or plaintext
+```
+
+This entry uses the same sanitization and code rendering as a site build.
+HTML code blocks accept `pre > code` or a `language-*` / `lang-*` class on
+`pre`. Editor line breaks become newlines inside `code`, and recognized
+languages receive highlight.js token classes. Unknown languages and Mermaid
+remain plain code. Code samples longer than 100,000 UTF-16 code units retain
+their text without syntax highlighting. Theme or preview CSS supplies the
+visual styling; `html` is a body fragment, not a complete page.
+
+The content entry can be bundled for browsers. For large documents, render in
+a Web Worker to keep editing responsive.
+
+## Site builds
 
 `@zeropress/build-core` is responsible for:
 
@@ -97,7 +118,8 @@ Returns:
       size: 1234,
       sha256: '...'
     }
-  ]
+  ],
+  warnings: []
 }
 ```
 
@@ -124,6 +146,20 @@ This is useful for local tooling that wants filesystem theme loading but still u
 Theme validation failures from either build entry point carry `error.code === 'THEME_VALIDATION_FAILED'`.
 Their messages preserve report and hint line breaks while escaping terminal control characters in diagnostic values such as paths, messages, and source snippets. CLI consumers can preserve the layout of these reports while escaping arbitrary errors as single-line text.
 
+## Menu depth
+
+`theme.json.menu_slots.<menu_id>.max_depth` optionally limits rendered depth
+(top-level items are depth 1). Omission leaves that menu unchanged. Items at the
+limit remain, with empty `children`; deeper descendants are excluded, without
+changing Preview Data. Direct `menus.<id>.items` loops and `{{menu:<id>}}` use
+the same tree.
+
+Both build APIs always return `warnings`. A depth overrun produces one
+`MENU_MAX_DEPTH_EXCEEDED` warning per menu per build, containing `message`,
+`menuId`, `maxDepth`, `actualDepth`, and `omittedItems` (all excluded
+descendants). It does not fail the build. The library does not print warnings;
+callers decide how to display them.
+
 ## Writers
 
 ### `MemoryWriter`
@@ -193,7 +229,7 @@ Build-core derives:
 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
+- 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 once, 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: ""`
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@zeropress/build-core",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "Shared ZeroPress build core",
   "type": "module",
   "license": "MIT",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./content": {
+      "types": "./src/content.d.ts",
+      "default": "./src/content.js"
+    }
   },
   "types": "./src/index.d.ts",
   "files": [
@@ -34,9 +38,10 @@
   },
   "dependencies": {
     "@zeropress/slug-policy": "0.2.2",
-    "@zeropress/preview-data-validator": "0.7.3",
-    "@zeropress/theme-validator": "0.7.3",
+    "@zeropress/preview-data-validator": "0.7.4",
+    "@zeropress/theme-validator": "0.7.4",
     "highlight.js": "11.12.0",
+    "htmlparser2": "12.0.0",
     "markdown-it": "15.0.2",
     "markdown-it-anchor": "10.0.0",
     "sanitize-html": "2.17.7"

package/src/api/build-site.js

@@ -2,11 +2,12 @@ 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 { extractHtmlText } from '../render/html-text.js';
 import { createThemeValidationError } from '../theme/format-theme-validation.js';
 import { ZeroPressEngine } from '../render/zeropress-engine.js';
+import { prepareRenderMenus } from '../render/menus.js';
 
 const DEFAULT_OPTIONS = {
   assetHashing: true,
@@ -54,7 +55,6 @@ 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];
@@ -137,6 +137,7 @@ export async function buildSite(input) {
 
   return {
     files: state.summaries,
+    warnings: state.warnings,
   };
 }
 
@@ -152,6 +153,7 @@ async function createBuildState(input, options) {
   const assetProcessor = new AssetProcessor();
   const summaries = [];
   const previewData = normalizePreviewData(input.previewData, options);
+  const { menus, warnings } = prepareRenderMenus(previewData.menus, themePackage.metadata.menu_slots);
   const renderData = createRenderData(previewData, themePackage, options);
 
   engine.initialize(themePackage);
@@ -168,6 +170,8 @@ async function createBuildState(input, options) {
   return {
     writer: input.writer,
     previewData,
+    menus,
+    warnings,
     renderData,
     widgets: resolveWidgetAreas(previewData, renderData),
     engine,
@@ -215,7 +219,7 @@ async function renderRoute(state, templateName, route) {
   let html = await state.engine.render(
     templateName,
     {
-      menus: state.previewData.menus,
+      menus: state.menus,
       widgets: state.widgets,
       collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
@@ -268,7 +272,7 @@ async function renderFrontPage(state, route) {
     let html = await state.engine.render(
       'page',
       {
-        menus: state.previewData.menus,
+        menus: state.menus,
         widgets: state.widgets,
         collections: state.renderData.collections,
         taxonomies: state.renderData.taxonomies,
@@ -309,7 +313,7 @@ async function renderFrontPage(state, route) {
   let html = await state.engine.render(
     'index',
     {
-      menus: state.previewData.menus,
+      menus: state.menus,
       widgets: state.widgets,
       collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
@@ -344,7 +348,7 @@ async function renderPost(state, post) {
   let html = await state.engine.render(
     'post',
     {
-      menus: state.previewData.menus,
+      menus: state.menus,
       widgets: state.widgets,
       collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
@@ -392,7 +396,7 @@ async function renderPage(state, page) {
   let html = await state.engine.render(
     'page',
     {
-      menus: state.previewData.menus,
+      menus: state.menus,
       widgets: state.widgets,
       collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
@@ -438,7 +442,7 @@ async function maybeRenderNotFoundPage(state) {
   let html = await state.engine.render(
     '404',
     {
-      menus: state.previewData.menus,
+      menus: state.menus,
       widgets: state.widgets,
       collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
@@ -912,7 +916,7 @@ function normalizeCommentsApiBaseUrl(value) {
   if (!normalized || normalized === '/') {
     return normalized;
   }
-  return normalized.replace(/\/+$/u, '');
+  return trimSlashes(normalized, { leading: false });
 }
 
 function normalizeTargetComments(comments) {
@@ -1840,7 +1844,7 @@ function normalizePaginationBasePath(basePath) {
     return '/';
   }
 
-  const normalized = decodeRoutePath(String(basePath)).replace(/^\/+|\/+$/g, '');
+  const normalized = trimSlashes(decodeRoutePath(String(basePath)));
   return `/${normalized}/`;
 }
 
@@ -2123,7 +2127,7 @@ function formatTimestamp(value, site) {
 }
 
 function calculateReadingTime(html) {
-  const plainText = String(html || '').replace(/<[^>]*>/g, ' ');
+  const plainText = extractHtmlText(html);
   const wordCount = plainText.trim().split(/\s+/).filter(Boolean).length;
   const minutes = Math.max(1, Math.ceil(wordCount / 200));
   return minutes === 1 ? '1 min read' : `${minutes} min read`;
@@ -2624,7 +2628,7 @@ function routePathToOutputPath(routePath, outputStyle = DEFAULT_PERMALINKS.outpu
     return 'index.html';
   }
   if (outputStyle === 'html-extension') {
-    return `${normalizedPath.replace(/^\/+|\/+$/g, '')}.html`;
+    return `${trimSlashes(normalizedPath)}.html`;
   }
   return `${normalizedPath.replace(/^\//, '')}index.html`;
 }
@@ -2656,11 +2660,21 @@ function pagePathToPublicUrl(routePath, outputStyle = DEFAULT_PERMALINKS.output_
   return withoutTrailingSlash;
 }
 
+function trimSlashes(value, { leading = true } = {}) {
+  let start = 0;
+  let end = value.length;
+  if (leading) {
+    while (start < end && value[start] === '/') start += 1;
+  }
+  while (end > start && value[end - 1] === '/') end -= 1;
+  return value.slice(start, end);
+}
+
 function normalizeRoutePath(routePath) {
   if (!routePath || routePath === '/') {
     return '/';
   }
-  const normalized = decodeRoutePath(String(routePath)).replace(/^\/+|\/+$/g, '');
+  const normalized = trimSlashes(decodeRoutePath(String(routePath)));
   return `/${normalized}/`;
 }
 
@@ -2676,8 +2690,7 @@ function resolveEffectivePageReferencePath(site, page) {
 }
 
 function normalizePageReferencePath(value) {
-  const normalized = decodeRoutePath(normalizeOptionalString(value))
-    .replace(/^\/+|\/+$/gu, '')
+  const normalized = trimSlashes(decodeRoutePath(normalizeOptionalString(value)))
     .normalize('NFC');
   return normalized;
 }
@@ -2718,7 +2731,7 @@ function pageToOutputPath(page, outputStyle) {
 
 function applyPermalinkPattern(pattern, kind, item, site) {
   const tokenValues = buildPermalinkTokenValues(kind, item, site);
-  const body = String(pattern || '').replace(/^\/+|\/+$/g, '');
+  const body = trimSlashes(String(pattern || ''));
   const segments = body.split('/').filter(Boolean).map((segment) => {
     if (segment.startsWith(':')) {
       return tokenValues[segment.slice(1)] || '';
@@ -2938,7 +2951,7 @@ function assertUniqueOutputPaths(plannedPaths) {
 }
 
 function normalizeRouteCollisionKey(url) {
-  return String(url || '').replace(/\/+$/, '') || '/';
+  return trimSlashes(String(url || ''), { leading: false }) || '/';
 }
 
 function assertSafeSlugDerivedOutputPath(rawSlug, outputPath) {
@@ -3160,7 +3173,7 @@ function buildSearchIndexItems(state) {
       tags: Array.isArray(post.tags) ? post.tags.map((tag) => tag.name).filter(Boolean) : [],
       published_at_iso: normalizeIsoTimestamp(post.published_at_iso),
       updated_at_iso: normalizeIsoTimestamp(post.updated_at_iso),
-      content_text: htmlToSearchText(post.html),
+      content_text: extractHtmlText(post.html),
     }));
 
   const frontPagePage = state.renderData.frontPageRoute?.front_page_type === 'page'
@@ -3196,7 +3209,7 @@ function buildSearchPageItem(page, url, pageReferencePath) {
     tags: [],
     published_at_iso: '',
     updated_at_iso: normalizeIsoTimestamp(page.updated_at_iso),
-    content_text: htmlToSearchText(page.html),
+    content_text: extractHtmlText(page.html),
   };
 }
 
@@ -3206,7 +3219,7 @@ function buildDocumentSummary(excerpt, html, title) {
     return authoredExcerpt;
   }
 
-  const visibleText = htmlToSummaryText(html, title);
+  const visibleText = extractHtmlText(html, { omitLeadingHeading: title });
   const codePoints = [...visibleText];
   if (codePoints.length <= GENERATED_SUMMARY_MAX_CODE_POINTS) {
     return visibleText;
@@ -3219,83 +3232,12 @@ function buildDocumentSummary(excerpt, html, title) {
   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)
     : [];
 }
 
-function htmlToSearchText(html) {
-  return normalizeSearchText(decodeHtmlEntities(
-    String(html || '')
-      .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ')
-      .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ')
-      .replace(/<!--[\s\S]*?-->/g, ' ')
-      .replace(/<[^>]+>/g, ' '),
-  ));
-}
-
-function decodeHtmlEntities(value) {
-  const namedEntities = {
-    amp: '&',
-    lt: '<',
-    gt: '>',
-    quot: '"',
-    apos: "'",
-    nbsp: ' ',
-  };
-
-  return String(value || '').replace(/&(#x[0-9a-fA-F]+|#\d+|[a-zA-Z][a-zA-Z0-9]+);/g, (match, entity) => {
-    if (entity.startsWith('#x')) {
-      const codePoint = Number.parseInt(entity.slice(2), 16);
-      return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : match;
-    }
-    if (entity.startsWith('#')) {
-      const codePoint = Number.parseInt(entity.slice(1), 10);
-      return Number.isFinite(codePoint) ? String.fromCodePoint(codePoint) : match;
-    }
-    return Object.prototype.hasOwnProperty.call(namedEntities, entity) ? namedEntities[entity] : match;
-  });
-}
-
 function normalizeSearchText(value) {
   return String(value || '').replace(/\s+/g, ' ').trim();
 }

package/src/content.d.ts

@@ -0,0 +1,17 @@
+export type DocumentType = 'html' | 'markdown' | 'plaintext';
+
+export interface ContentHeading {
+  level: number;
+  id: string;
+  title: string;
+  href: string;
+}
+
+export interface RenderedDocument {
+  html: string;
+  toc: ContentHeading[];
+}
+
+/** Render a body using the same sanitization and code highlighting as site builds. */
+export function renderDocument(content: string, documentType?: DocumentType): RenderedDocument;
+export function renderDocumentContent(content: string, documentType?: DocumentType): string;

package/src/content.js

@@ -0,0 +1 @@
+export { renderDocument, renderDocumentContent } from './render/content-renderer.js';

package/src/index.d.ts

@@ -80,8 +80,18 @@ export interface BuildSummaryFile {
   sha256: string;
 }
 
+export interface BuildWarning {
+  code: 'MENU_MAX_DEPTH_EXCEEDED';
+  message: string;
+  menuId: string;
+  maxDepth: number;
+  actualDepth: number;
+  omittedItems: number;
+}
+
 export interface BuildSiteResult {
   files: BuildSummaryFile[];
+  warnings: BuildWarning[];
 }
 
 export function buildSite(input: {

package/src/render/code-blocks.js

@@ -0,0 +1,98 @@
+import hljs from 'highlight.js';
+import { parseDocument } from 'htmlparser2';
+
+const MAX_HIGHLIGHT_LENGTH = 100_000;
+const LANGUAGE_CLASS = /^(?:language|lang)-([a-z\d_+-]+)$/i;
+
+function escapeHtml(value) {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+function languageOf(attributes) {
+  for (const token of (attributes?.class || '').split(/\s+/)) {
+    const match = LANGUAGE_CLASS.exec(token);
+    if (match) return match[1].toLowerCase();
+  }
+  return '';
+}
+
+function attributesHtml(attributes) {
+  return Object.entries(attributes).map(([name, value]) => (
+    ` ${name}="${escapeHtml(value).replace(/"/g, '&quot;')}"`
+  )).join('');
+}
+
+function codeText(children) {
+  const stack = [...children].reverse();
+  const parts = [];
+  while (stack.length) {
+    const node = stack.pop();
+    if (node.type === 'text') parts.push(node.data);
+    else if (node.name === 'br') parts.push('\n');
+    else if (node.children) {
+      for (let index = node.children.length - 1; index >= 0; index--) {
+        stack.push(node.children[index]);
+      }
+    }
+  }
+  return parts.join('');
+}
+
+function highlight(text, language, autoDetect) {
+  if (text.length <= MAX_HIGHLIGHT_LENGTH && !['mermaid', 'none', 'text', 'plaintext'].includes(language)) {
+    try {
+      const result = language && hljs.getLanguage(language)
+        ? hljs.highlight(text, { language }).value
+        : !language && autoDetect ? hljs.highlightAuto(text).value : null;
+      if (result !== null) return result.replace(/&quot;/g, '"').replace(/&#x27;/g, "'");
+    } catch {
+      // A highlighting failure must preserve the readable code sample.
+    }
+  }
+  return escapeHtml(text);
+}
+
+/** Normalize sanitized code blocks without reserializing unrelated authored HTML. */
+export function renderCodeBlocks(html, { autoDetect = false } = {}) {
+  if (!/<pre[\s>]/i.test(html)) return html;
+  const document = parseDocument(html, { withStartIndices: true, withEndIndices: true });
+  const stack = [...document.children].reverse();
+  const replacements = [];
+  while (stack.length) {
+    const node = stack.pop();
+    if (node.name === 'pre') {
+      const code = node.children.find((child) => child.name === 'code');
+      const language = languageOf(code?.attribs) || languageOf(node.attribs);
+      if (!code && !language) continue;
+      const onlyCode = code && node.children.every((child) => (
+        child === code || (child.type === 'text' && !child.data.trim())
+      ));
+      const text = codeText(onlyCode ? code.children : node.children);
+      const attributes = { ...(code?.attribs || {}) };
+      if (language) {
+        attributes.class = [
+          ...(attributes.class || '').split(/\s+/).filter((token) => token && !LANGUAGE_CLASS.test(token)),
+          `language-${language}`,
+        ].join(' ');
+      }
+      replacements.push({
+        start: node.startIndex,
+        end: node.endIndex + 1,
+        html: `<pre${attributesHtml(node.attribs)}><code${attributesHtml(attributes)}>${highlight(text, language, autoDetect)}</code></pre>`,
+      });
+      continue;
+    }
+    if (node.children) {
+      for (let index = node.children.length - 1; index >= 0; index--) stack.push(node.children[index]);
+    }
+  }
+  const parts = [];
+  let start = 0;
+  for (const replacement of replacements) {
+    parts.push(html.slice(start, replacement.start), replacement.html);
+    start = replacement.end;
+  }
+  parts.push(html.slice(start));
+  return parts.join('');
+}

package/src/render/content-renderer.js

@@ -1,7 +1,7 @@
 import MarkdownIt from 'markdown-it';
-import hljs from 'highlight.js';
 import anchor from 'markdown-it-anchor';
 import sanitizeHtmlParser from 'sanitize-html';
+import { renderCodeBlocks } from './code-blocks.js';
 
 const TOC_LEVELS = new Set([2, 3, 4]);
 const ALERT_TYPES = new Map([
@@ -109,7 +109,7 @@ export function renderDocument(content, documentType = 'markdown') {
 
   if (normalizedType === 'html') {
     return {
-      html: sanitizeHtml(normalizedContent),
+      html: renderCodeBlocks(sanitizeHtml(normalizedContent)),
       toc: [],
     };
   }
@@ -122,7 +122,7 @@ function renderMarkdownDocument(content) {
   const markdown = createMarkdownRenderer(toc);
 
   return {
-    html: sanitizeHtml(markdown.render(content)),
+    html: renderCodeBlocks(sanitizeHtml(markdown.render(content)), { autoDetect: true }),
     toc,
   };
 }
@@ -133,21 +133,6 @@ function createMarkdownRenderer(toc) {
     linkify: false,
     typographer: true,
     breaks: false,
-    highlight(value, language) {
-      if (language && hljs.getLanguage(language)) {
-        try {
-          return hljs.highlight(value, { language }).value;
-        } catch {
-          return value;
-        }
-      }
-
-      try {
-        return hljs.highlightAuto(value).value;
-      } catch {
-        return value;
-      }
-    },
   });
 
   markdown.use(markdownAdmonitionContainers);

package/src/render/html-text.js

@@ -0,0 +1,62 @@
+import { parseDocument } from 'htmlparser2';
+
+const NON_VISIBLE_TAGS = new Set(['script', 'style', 'template', 'noscript']);
+const TEXT_BOUNDARY_TAGS = new Set([
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'br', 'hr', 'pre',
+  'ul', 'ol', 'li', 'blockquote', 'aside', 'figure', 'figcaption',
+  'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'div', 'nav',
+]);
+
+/** Extract plain text with entities decoded once; escape it when rendering HTML. */
+export function extractHtmlText(html, { omitLeadingHeading } = {}) {
+  const document = parseDocument(String(html || ''), { decodeEntities: true });
+  return collectText(document.children, omitLeadingHeading);
+}
+
+function collectText(nodes, omitLeadingHeading) {
+  const pending = [...nodes].reverse();
+  const parts = [];
+  let hasVisibleText = false;
+  let foundHeading = false;
+
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (typeof node === 'string') {
+      parts.push(node);
+      continue;
+    }
+    if (node.type === 'text') {
+      parts.push(node.data);
+      hasVisibleText ||= node.data.trim() !== '';
+      continue;
+    }
+    if (node.type !== 'tag' || NON_VISIBLE_TAGS.has(node.name)) continue;
+
+    if (node.name === 'h1' && !foundHeading) {
+      foundHeading = true;
+      if (
+        !hasVisibleText
+        && omitLeadingHeading !== undefined
+        && collectText(node.children).normalize('NFC')
+          === normalizeText(String(omitLeadingHeading)).normalize('NFC')
+      ) {
+        parts.push(' ');
+        continue;
+      }
+    }
+
+    if (TEXT_BOUNDARY_TAGS.has(node.name)) {
+      parts.push(' ');
+      pending.push(' ');
+    }
+    for (let index = node.children.length - 1; index >= 0; index -= 1) {
+      pending.push(node.children[index]);
+    }
+  }
+
+  return normalizeText(parts.join(''));
+}
+
+function normalizeText(value) {
+  return value.replace(/\s+/gu, ' ').trim();
+}

package/src/render/menus.js

@@ -0,0 +1,44 @@
+// Work on rendering copies only; validation and exported Preview Data keep the full tree.
+export function prepareRenderMenus(menus, slots = {}) {
+  const rendered = { ...menus };
+  const warnings = [];
+
+  for (const [menuId, slot] of Object.entries(slots)) {
+    if (slot.max_depth === undefined || !Object.hasOwn(menus, menuId)) continue;
+    const maxDepth = slot.max_depth;
+    const items = [];
+    const stack = [{ source: menus[menuId].items, output: items, depth: 1 }];
+    let actualDepth = 0;
+    let omittedItems = 0;
+
+    while (stack.length) {
+      const { source, output, depth } = stack.pop();
+      for (const item of source) {
+        actualDepth = Math.max(actualDepth, depth);
+        const children = [];
+        if (depth <= maxDepth) {
+          output.push({ ...item, children });
+        } else {
+          omittedItems += 1;
+        }
+        if (item.children.length) {
+          stack.push({ source: item.children, output: children, depth: depth + 1 });
+        }
+      }
+    }
+
+    rendered[menuId] = { ...menus[menuId], items };
+    if (omittedItems > 0) {
+      warnings.push({
+        code: 'MENU_MAX_DEPTH_EXCEEDED',
+        message: `Menu "${menuId}" reaches depth ${actualDepth}; the theme supports ${maxDepth}. ${omittedItems} deeper item(s) were omitted from rendering.`,
+        menuId,
+        maxDepth,
+        actualDepth,
+        omittedItems,
+      });
+    }
+  }
+
+  return { menus: rendered, warnings };
+}