@zeropress/build-core 0.5.0 → 0.5.2

package/src/api/build-site.js

@@ -9,6 +9,7 @@ import { ZeroPressEngine } from '../render/zeropress-engine.js';
 const DEFAULT_OPTIONS = {
   assetHashing: true,
   generateSpecialFiles: true,
+  generateRobotsTxt: true,
   writeManifest: false,
 };
 
@@ -24,16 +25,31 @@ const DEFAULT_PERMALINKS = Object.freeze({
   categories: '/categories/:slug/',
   tags: '/tags/:slug/',
 });
+const DEFAULT_FRONT_PAGE = Object.freeze({
+  type: 'theme_index',
+});
+const DEFAULT_POST_INDEX = Object.freeze({
+  enabled: true,
+  path: '/',
+  paginate: true,
+});
 const PERMALINK_OUTPUT_STYLES = new Set(['directory', 'html-extension']);
 const COMMENT_POLICY_OUTPUT_PATH = '_zeropress/comment-policy.json';
 const OUTPUT_PATH_CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F]/;
 const SAFE_MEDIA_PROTOCOLS = new Set(['http:', 'https:']);
 const SAFE_LINK_PROTOCOLS = new Set(['http:', 'https:', 'mailto:', 'tel:']);
+const MEDIA_DELIVERY_MODES = new Set(['none', 'media_domain']);
+const RESPONSIVE_IMAGE_WIDTHS = [320, 480, 768, 1024, 1280, 1600, 1920];
+const RESPONSIVE_IMAGE_EXTENSIONS = new Set(['jpg', 'jpeg', 'png', 'webp', 'avif']);
 export async function buildSite(input) {
   const options = { ...DEFAULT_OPTIONS, ...(input.options || {}) };
   const state = await createBuildState(input, options);
   assertPlannedOutputPathsSafe(state);
 
+  if (state.renderData.frontPageRoute) {
+    await renderFrontPage(state, state.renderData.frontPageRoute);
+  }
+
   for (const route of state.renderData.indexRoutes) {
     await renderRoute(state, 'index', route);
   }
@@ -82,7 +98,9 @@ export async function buildSite(input) {
       await writeOutput(state.writer, state.summaries, 'sitemap.xml', buildSitemapXml(state.previewData.site, state.emitted, state.generatedAt), 'application/xml');
       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, 'robots.txt', buildRobotsTxt(state.previewData.site), 'text/plain');
+    if (shouldGenerateRobotsTxt(options)) {
+      await writeOutput(state.writer, state.summaries, 'robots.txt', buildRobotsTxt(state.previewData.site), 'text/plain');
+    }
   }
 
   return finalizeBuildResult(state.writer, state.summaries, options);
@@ -99,7 +117,7 @@ async function createBuildState(input, options) {
   const engine = new ZeroPressEngine();
   const assetProcessor = new AssetProcessor();
   const summaries = [];
-  const previewData = normalizePreviewData(input.previewData);
+  const previewData = normalizePreviewData(input.previewData, options);
   const renderData = createRenderData(previewData, themePackage.metadata);
 
   engine.initialize(themePackage);
@@ -125,10 +143,12 @@ async function createBuildState(input, options) {
     assetMap,
     customCssHref: customCssAsset ? `/${customCssAsset.path}` : '',
     customHtml: previewData.custom_html,
+    favicon: previewData.site.favicon,
     commentPolicyContent: buildCommentPolicyManifest(renderData.posts),
     options,
     generatedAt: new Date(),
     emitted: {
+      frontPage: null,
       indexRoutes: [],
       archiveRoutes: [],
       categoryRoutes: [],
@@ -175,13 +195,19 @@ async function finalizeBuildResult(writer, summaries, options) {
 
 async function renderRoute(state, templateName, route) {
   const currentUrl = routePathToPublicUrl(route.path, state.previewData.site.permalinks.output_style);
+  const routeContext = buildRouteContext(route.route_type || templateName, currentUrl, {
+    isFrontPage: route.is_front_page === true,
+    isPostIndex: route.is_post_index === true,
+  });
   let html = await state.engine.render(
     templateName,
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
       ...route,
+      route: routeContext,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
         title: state.previewData.site.title,
@@ -197,6 +223,89 @@ async function renderRoute(state, templateName, route) {
   recordRouteEmission(state, templateName, route, currentUrl);
 }
 
+async function renderFrontPage(state, route) {
+  const currentUrl = '/';
+  const routeContext = buildRouteContext('front_page', currentUrl, {
+    isFrontPage: true,
+    isPostIndex: false,
+  });
+
+  if (route.front_page_type === 'standalone_html') {
+    await writeOutput(state.writer, state.summaries, 'index.html', route.html, 'text/html');
+    state.emitted.frontPage = {
+      url: currentUrl,
+      title: state.previewData.site.title,
+      description: state.previewData.site.description,
+      includeInFeed: false,
+    };
+    return;
+  }
+
+  if (route.front_page_type === 'page') {
+    const page = {
+      ...route.page,
+      url: currentUrl,
+    };
+    let html = await state.engine.render(
+      'page',
+      {
+        menus: state.previewData.menus,
+        widgets: state.widgets,
+        collections: state.renderData.collections,
+        taxonomies: state.renderData.taxonomies,
+        page,
+        route: routeContext,
+        meta: buildPageMeta(state.previewData.site, {
+          currentUrl,
+          title: buildDocumentTitle(page.title, state.previewData.site.title),
+          description: page.excerpt,
+          ogType: 'website',
+          image: page.featured_image,
+        }),
+      },
+      createRenderContext(state.previewData.site, currentUrl),
+    );
+    html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
+    html = injectSiteCustomizations(html, state);
+    await writeOutput(state.writer, state.summaries, 'index.html', html, 'text/html');
+    state.emitted.frontPage = {
+      url: currentUrl,
+      title: page.title,
+      description: page.excerpt,
+      includeInFeed: false,
+    };
+    return;
+  }
+
+  let html = await state.engine.render(
+    'index',
+    {
+      menus: state.previewData.menus,
+      widgets: state.widgets,
+      collections: state.renderData.collections,
+      taxonomies: state.renderData.taxonomies,
+      ...route,
+      route: routeContext,
+      meta: buildPageMeta(state.previewData.site, {
+        currentUrl,
+        title: state.previewData.site.title,
+        description: state.previewData.site.description,
+        ogType: 'website',
+      }),
+    },
+    createRenderContext(state.previewData.site, currentUrl),
+  );
+  html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
+  html = injectSiteCustomizations(html, state);
+  await writeOutput(state.writer, state.summaries, 'index.html', html, 'text/html');
+  state.emitted.frontPage = {
+    url: currentUrl,
+    title: state.previewData.site.title,
+    description: state.previewData.site.description,
+    includeInFeed: false,
+  };
+}
+
 async function renderPost(state, post) {
   const currentUrl = post.url;
   let html = await state.engine.render(
@@ -204,8 +313,10 @@ async function renderPost(state, post) {
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
       post,
+      route: buildRouteContext('post', currentUrl),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
         title: buildDocumentTitle(post.title, state.previewData.site.title),
@@ -233,15 +344,20 @@ async function renderPost(state, post) {
 
 async function renderPage(state, page) {
   const currentUrl = page.url;
+  const outputPath = pageToOutputPath(page, state.previewData.site.permalinks.output_style);
+  const canonicalUrl = normalizeOptionalString(page.canonical_url) || currentUrl;
   let html = await state.engine.render(
     'page',
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
       page,
+      route: buildRouteContext('page', currentUrl),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
+        canonicalUrl,
         title: buildDocumentTitle(page.title, state.previewData.site.title),
         description: page.excerpt,
         ogType: 'website',
@@ -252,12 +368,13 @@ async function renderPage(state, page) {
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
   html = injectSiteCustomizations(html, state);
-  await writeOutput(state.writer, state.summaries, routePathToOutputPath(page.url, state.previewData.site.permalinks.output_style), html, 'text/html');
+  await writeOutput(state.writer, state.summaries, outputPath, html, 'text/html');
   state.emitted.pages.push({
     url: currentUrl,
     title: page.title,
     description: page.excerpt,
     status: page.status,
+    includeInSitemap: page.omit_from_sitemap !== true,
   });
 }
 
@@ -271,7 +388,9 @@ async function maybeRenderNotFoundPage(state) {
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      collections: state.renderData.collections,
       taxonomies: state.renderData.taxonomies,
+      route: buildRouteContext('not_found', '/404.html'),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl: '/404.html',
         title: state.previewData.site.title,
@@ -286,10 +405,14 @@ async function maybeRenderNotFoundPage(state) {
   await writeOutput(state.writer, state.summaries, '404.html', html, 'text/html');
 }
 
-function normalizePreviewData(previewData) {
+function normalizePreviewData(previewData, options = {}) {
   const normalizedSite = {
     ...previewData.site,
     mediaBaseUrl: normalizeOptionalString(previewData.site.mediaBaseUrl),
+    mediaDeliveryMode: MEDIA_DELIVERY_MODES.has(previewData.site.mediaDeliveryMode)
+      ? previewData.site.mediaDeliveryMode
+      : 'none',
+    favicon: normalizeSiteFavicon(previewData.site.favicon || options.favicon),
     postsPerPage: Number.isInteger(previewData.site.postsPerPage) && previewData.site.postsPerPage > 0
       ? previewData.site.postsPerPage
       : DEFAULT_POSTS_PER_PAGE,
@@ -298,39 +421,195 @@ function normalizePreviewData(previewData) {
     timezone: normalizeNonEmptyString(previewData.site.timezone, DEFAULT_TIMEZONE),
     locale: normalizeLocale(previewData.site.locale || DEFAULT_LOCALE),
     disallowComments: previewData.site.disallowComments === true,
+    indexing: previewData.site.indexing !== false,
     permalinks: normalizePermalinks(previewData.site.permalinks),
+    front_page: normalizeFrontPage(previewData.site.front_page),
+    post_index: normalizePostIndex(previewData.site.post_index),
+    footer: normalizeSiteFooter(previewData.site.footer),
   };
+  const media = normalizeContentMedia(previewData.content.media, normalizedSite);
+  const mediaRegistry = buildMediaRegistry(media);
 
   return {
     ...previewData,
     site: normalizedSite,
+    menus: normalizeRecordMap(previewData.menus),
+    collections: normalizeCollections(previewData.collections),
     widgets: normalizeWidgetAreas(previewData.widgets, normalizedSite.mediaBaseUrl),
     custom_css: normalizeCustomCss(previewData.custom_css),
     custom_html: normalizeCustomHtml(previewData.custom_html),
     content: {
       ...previewData.content,
-      authors: previewData.content.authors.map((author) => ({
-        ...author,
-        avatar: normalizeMediaField(author.avatar, normalizedSite.mediaBaseUrl),
-      })),
+      authors: previewData.content.authors.map((author) => {
+        const avatar = normalizeMediaField(author.avatar, normalizedSite.mediaBaseUrl);
+        const avatarMedia = deriveManagedMedia(avatar, mediaRegistry, normalizedSite);
+        return {
+          ...author,
+          avatar,
+          ...(avatarMedia ? { avatar_media: avatarMedia } : {}),
+        };
+      }),
       posts: previewData.content.posts
-        .map((post) => ({
-          ...post,
-          published_at_iso: normalizeIsoTimestamp(post.published_at_iso),
-          updated_at_iso: normalizeIsoTimestamp(post.updated_at_iso),
-          featured_image: normalizeMediaField(post.featured_image, normalizedSite.mediaBaseUrl),
-        }))
+        .map((post) => {
+          const featuredImage = normalizeMediaField(post.featured_image, normalizedSite.mediaBaseUrl);
+          const featuredMedia = deriveManagedMedia(featuredImage, mediaRegistry, normalizedSite);
+          return {
+            ...post,
+            published_at_iso: normalizeIsoTimestamp(post.published_at_iso),
+            updated_at_iso: normalizeIsoTimestamp(post.updated_at_iso),
+            featured_image: featuredImage,
+            ...(featuredMedia ? { featured_media: featuredMedia } : {}),
+          };
+        })
         .sort((left, right) => toDate(right.published_at_iso).getTime() - toDate(left.published_at_iso).getTime()),
-      pages: previewData.content.pages.map((page) => ({
-        ...page,
-        featured_image: normalizeMediaField(page.featured_image, normalizedSite.mediaBaseUrl),
-      })),
+      pages: previewData.content.pages.map((page) => {
+        const featuredImage = normalizeMediaField(page.featured_image, normalizedSite.mediaBaseUrl);
+        const featuredMedia = deriveManagedMedia(featuredImage, mediaRegistry, normalizedSite);
+        return {
+          ...page,
+          featured_image: featuredImage,
+          ...(featuredMedia ? { featured_media: featuredMedia } : {}),
+        };
+      }),
       categories: [...previewData.content.categories],
       tags: [...previewData.content.tags],
+      media,
     },
   };
 }
 
+function normalizeRecordMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  return { ...value };
+}
+
+function normalizeContentMedia(mediaItems, site) {
+  if (!Array.isArray(mediaItems)) {
+    return [];
+  }
+
+  return mediaItems
+    .map((item) => {
+      if (!item || typeof item !== 'object') {
+        return null;
+      }
+      const src = normalizeMediaField(item.src, site.mediaBaseUrl);
+      const width = Number.isInteger(item.width) && item.width > 0 ? item.width : 0;
+      const height = Number.isInteger(item.height) && item.height > 0 ? item.height : 0;
+      if (!src || !width || !height) {
+        return null;
+      }
+      return {
+        src,
+        width,
+        height,
+        alt: typeof item.alt === 'string' ? item.alt : '',
+      };
+    })
+    .filter(Boolean);
+}
+
+function buildMediaRegistry(mediaItems) {
+  const registry = new Map();
+  for (const item of mediaItems) {
+    if (!registry.has(item.src)) {
+      registry.set(item.src, item);
+    }
+  }
+  return registry;
+}
+
+function deriveManagedMedia(src, mediaRegistry, site) {
+  const normalizedSrc = normalizeOptionalString(src);
+  if (!normalizedSrc) {
+    return null;
+  }
+  const media = mediaRegistry.get(normalizedSrc);
+  if (!media) {
+    return null;
+  }
+  return {
+    ...media,
+    srcset: buildResponsiveImageSrcset(media, site),
+  };
+}
+
+function buildResponsiveImageSrcset(media, site) {
+  if (site.mediaDeliveryMode !== 'media_domain') {
+    return '';
+  }
+
+  const mediaBaseUrl = normalizeOptionalString(site.mediaBaseUrl);
+  if (!mediaBaseUrl || !isUrlUnderMediaBase(media.src, mediaBaseUrl) || !isResponsiveRasterImage(media.src)) {
+    return '';
+  }
+
+  const widths = RESPONSIVE_IMAGE_WIDTHS.filter((width) => width <= media.width);
+  if (!widths.includes(media.width)) {
+    widths.push(media.width);
+  }
+
+  return widths
+    .filter((width, index, values) => width > 0 && values.indexOf(width) === index)
+    .map((width) => `${buildResponsiveImageVariantUrl(media.src, width)} ${width}w`)
+    .join(', ');
+}
+
+function buildResponsiveImageVariantUrl(src, width) {
+  try {
+    const url = new URL(src);
+    url.searchParams.set('w', String(width));
+    url.searchParams.set('fit', 'scale-down');
+    url.searchParams.set('format', 'auto');
+    return decodeURI(url.toString());
+  } catch {
+    return src;
+  }
+}
+
+function isUrlUnderMediaBase(src, mediaBaseUrl) {
+  try {
+    const sourceUrl = new URL(src);
+    const baseUrl = new URL(mediaBaseUrl);
+    const basePath = baseUrl.pathname.endsWith('/') ? baseUrl.pathname : `${baseUrl.pathname}/`;
+    return sourceUrl.origin === baseUrl.origin && sourceUrl.pathname.startsWith(basePath);
+  } catch {
+    return false;
+  }
+}
+
+function isResponsiveRasterImage(src) {
+  try {
+    const url = new URL(src);
+    const lastSegment = url.pathname.split('/').pop() || '';
+    const extension = lastSegment.includes('.') ? lastSegment.split('.').pop().toLowerCase() : '';
+    return RESPONSIVE_IMAGE_EXTENSIONS.has(extension);
+  } catch {
+    return false;
+  }
+}
+
+function normalizeCollections(collections) {
+  if (!collections || typeof collections !== 'object' || Array.isArray(collections)) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(collections).map(([collectionId, collection]) => [
+      collectionId,
+      {
+        ...collection,
+        title: normalizeOptionalString(collection?.title),
+        description: normalizeOptionalString(collection?.description),
+        items: Array.isArray(collection?.items) ? collection.items.map((item) => ({ ...item })) : [],
+      },
+    ]),
+  );
+}
+
 function normalizeWidgetAreas(widgetAreas, mediaBaseUrl) {
   if (!widgetAreas || typeof widgetAreas !== 'object') {
     return {};
@@ -350,6 +629,22 @@ function normalizeWidgetAreas(widgetAreas, mediaBaseUrl) {
   );
 }
 
+function normalizeSiteFooter(footer) {
+  const source = footer && typeof footer === 'object' && !Array.isArray(footer) ? footer : {};
+  const attribution = source.attribution && typeof source.attribution === 'object' && !Array.isArray(source.attribution)
+    ? source.attribution
+    : {};
+
+  return {
+    ...source,
+    copyright_text: normalizeOptionalString(source.copyright_text),
+    attribution: {
+      ...attribution,
+      enabled: attribution.enabled !== false,
+    },
+  };
+}
+
 function normalizeWidgetItem(item, mediaBaseUrl) {
   const normalizedItem = {
     ...item,
@@ -391,6 +686,22 @@ function normalizeCustomHtml(customHtml) {
   };
 }
 
+function normalizeSiteFavicon(favicon) {
+  if (!favicon || typeof favicon !== 'object') {
+    return undefined;
+  }
+
+  const normalized = {};
+  for (const key of ['icon', 'svg', 'png', 'apple_touch_icon']) {
+    const value = normalizeOptionalString(favicon[key]);
+    if (value) {
+      normalized[key] = value;
+    }
+  }
+
+  return Object.keys(normalized).length ? normalized : undefined;
+}
+
 function normalizePermalinks(permalinks) {
   const source = permalinks && typeof permalinks === 'object' ? permalinks : {};
   const outputStyle = typeof source.output_style === 'string' && PERMALINK_OUTPUT_STYLES.has(source.output_style)
@@ -406,8 +717,37 @@ function normalizePermalinks(permalinks) {
   };
 }
 
+function normalizeFrontPage(frontPage) {
+  if (!frontPage || typeof frontPage !== 'object') {
+    return { ...DEFAULT_FRONT_PAGE };
+  }
+
+  const type = ['theme_index', 'page', 'standalone_html'].includes(frontPage.type)
+    ? frontPage.type
+    : DEFAULT_FRONT_PAGE.type;
+
+  return {
+    type,
+    ...(type === 'page' ? { page_slug: normalizeOptionalString(frontPage.page_slug) } : {}),
+    ...(type === 'standalone_html' ? { html: normalizeOptionalRawString(frontPage.html) } : {}),
+  };
+}
+
+function normalizePostIndex(postIndex) {
+  if (!postIndex || typeof postIndex !== 'object') {
+    return { ...DEFAULT_POST_INDEX };
+  }
+
+  return {
+    enabled: postIndex.enabled !== false,
+    path: normalizeNonEmptyString(postIndex.path, DEFAULT_POST_INDEX.path),
+    paginate: postIndex.paginate !== false,
+  };
+}
+
 function createRenderData(previewData, themeMetadata = {}) {
   const themeSupportsComments = themeMetadata?.features?.comments === true;
+  const themeSupportsPostIndex = themeMetadata?.features?.postIndex !== false;
   const authorsById = new Map(previewData.content.authors.map((author) => [author.id, author]));
   const categoriesBySlug = new Map(previewData.content.categories.map((category) => [category.slug, category]));
   const tagsBySlug = new Map(previewData.content.tags.map((tag) => [tag.slug, tag]));
@@ -436,24 +776,40 @@ function createRenderData(previewData, themeMetadata = {}) {
   }));
   const pages = previewData.content.pages.map((page) => preparePage(page, previewData.site));
   const postBySlug = new Map(posts.map((post) => [post.slug, post]));
+  const pageBySlug = new Map(pages.map((page) => [page.slug, page]));
+  const frontPage = previewData.site.front_page;
+  const postIndex = previewData.site.post_index;
+  const effectivePostIndexEnabled = postIndex.enabled !== false && themeSupportsPostIndex;
+  const effectivePostIndexPaginate = effectivePostIndexEnabled && postIndex.paginate !== false;
+  const postIndexBasePath = normalizeRoutePath(postIndex.path || DEFAULT_POST_INDEX.path);
+
+  if (frontPage.type !== 'theme_index' && effectivePostIndexEnabled && postIndexBasePath === '/') {
+    throw new Error('Invalid front page configuration: site.front_page occupies "/" so site.post_index.path must not be "/". Set site.post_index.path to a non-root path or disable site.post_index.');
+  }
+
+  const frontPageRoute = buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, postIndexBasePath);
+  const pageFrontPageSlug = frontPage.type === 'page' ? frontPage.page_slug : '';
+  const preparedPages = pageFrontPageSlug
+    ? pages.filter((page) => page.slug !== pageFrontPageSlug)
+    : pages;
 
   return {
     posts,
-    pages,
+    pages: preparedPages,
     postBySlug,
+    collections: resolveCollections(previewData.collections, postBySlug, pageBySlug, frontPage),
     taxonomies: buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug),
-    indexRoutes: buildPaginatedCollection({
+    frontPageRoute,
+    indexRoutes: buildPostIndexRoutes({
+      enabled: effectivePostIndexEnabled,
+      paginate: effectivePostIndexPaginate,
       items: previewData.content.posts,
       postsPerPage: previewData.site.postsPerPage,
-      basePath: '/',
+      basePath: postIndexBasePath,
       outputStyle: previewData.site.permalinks.output_style,
-    }).map((entry) => ({
-      path: entry.path,
-      page: entry.page,
-      totalPages: entry.totalPages,
-      posts: buildStructuredPostCollection(entry.items, postBySlug),
-      pagination: buildStructuredPagination(entry.paginationData),
-    })),
+      postBySlug,
+      frontPage,
+    }),
     archiveRoutes: buildPaginatedCollection({
       items: previewData.content.posts,
       postsPerPage: previewData.site.postsPerPage,
@@ -500,6 +856,147 @@ function buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug)
   };
 }
 
+function resolveCollections(collections, postBySlug, pageBySlug, frontPage) {
+  if (!collections || typeof collections !== 'object') {
+    return {};
+  }
+
+  return Object.fromEntries(
+    Object.entries(collections).map(([collectionId, collection]) => [
+      collectionId,
+      {
+        id: collectionId,
+        title: normalizeOptionalString(collection?.title),
+        description: normalizeOptionalString(collection?.description),
+        items: resolveCollectionItems(collectionId, collection?.items, postBySlug, pageBySlug, frontPage),
+      },
+    ]),
+  );
+}
+
+function resolveCollectionItems(collectionId, items, postBySlug, pageBySlug, frontPage) {
+  if (!Array.isArray(items)) {
+    return [];
+  }
+
+  return items.map((item, index) => resolveCollectionItem(collectionId, item, index, postBySlug, pageBySlug, frontPage));
+}
+
+function resolveCollectionItem(collectionId, item, index, postBySlug, pageBySlug, frontPage) {
+  if (item?.type === 'post') {
+    const post = postBySlug.get(item.slug);
+    if (!post) {
+      throw new Error(`Invalid collection "${collectionId}": item ${index + 1} references missing post slug "${item.slug}".`);
+    }
+    return {
+      type: 'post',
+      meta: post.meta,
+      ...buildStructuredPostSummary(post),
+    };
+  }
+
+  if (item?.type === 'page') {
+    const page = pageBySlug.get(item.slug);
+    if (!page) {
+      throw new Error(`Invalid collection "${collectionId}": item ${index + 1} references missing page slug "${item.slug}".`);
+    }
+    return buildCollectionPageSummary(page, frontPage);
+  }
+
+  throw new Error(`Invalid collection "${collectionId}": item ${index + 1} has unsupported type "${item?.type}".`);
+}
+
+function buildCollectionPageSummary(page, frontPage) {
+  return {
+    type: 'page',
+    title: page.title,
+    slug: page.slug,
+    url: frontPage?.type === 'page' && frontPage.page_slug === page.slug ? '/' : page.url,
+    excerpt: page.excerpt || '',
+    featured_image: page.featured_image || '',
+    ...(page.featured_media ? { featured_media: { ...page.featured_media } } : {}),
+    meta: page.meta,
+  };
+}
+
+function buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, postIndexBasePath) {
+  if (frontPage.type === 'theme_index') {
+    if (effectivePostIndexEnabled && postIndexBasePath === '/') {
+      return null;
+    }
+
+    return {
+      path: '/',
+      front_page_type: 'theme_index',
+      posts: buildStructuredPostCollection([], new Map()),
+      pagination: buildStructuredPagination(buildDisabledPaginationData(0)),
+    };
+  }
+
+  if (frontPage.type === 'page') {
+    const page = pages.find((entry) => entry.slug === frontPage.page_slug);
+    if (!page) {
+      throw new Error(`Invalid front page configuration: site.front_page.page_slug "${frontPage.page_slug}" does not match a page.`);
+    }
+
+    return {
+      path: '/',
+      front_page_type: 'page',
+      page,
+    };
+  }
+
+  if (frontPage.type === 'standalone_html') {
+    if (!normalizeOptionalRawString(frontPage.html)) {
+      throw new Error('Invalid front page configuration: site.front_page.html is required for standalone_html.');
+    }
+
+    return {
+      path: '/',
+      front_page_type: 'standalone_html',
+      html: frontPage.html,
+    };
+  }
+
+  return null;
+}
+
+function buildPostIndexRoutes(options) {
+  if (!options.enabled) {
+    return [];
+  }
+
+  if (!options.paginate) {
+    const items = options.items.slice(0, options.postsPerPage);
+    return [{
+      path: options.basePath,
+      route_type: 'post_index',
+      is_front_page: options.basePath === '/' && options.frontPage.type === 'theme_index',
+      is_post_index: true,
+      page: 1,
+      totalPages: 1,
+      posts: buildStructuredPostCollection(items, options.postBySlug),
+      pagination: buildStructuredPagination(buildDisabledPaginationData(options.items.length)),
+    }];
+  }
+
+  return buildPaginatedCollection({
+    items: options.items,
+    postsPerPage: options.postsPerPage,
+    basePath: options.basePath,
+    outputStyle: options.outputStyle,
+  }).map((entry) => ({
+    path: entry.path,
+    route_type: 'post_index',
+    is_front_page: entry.path === '/' && options.frontPage.type === 'theme_index',
+    is_post_index: true,
+    page: entry.page,
+    totalPages: entry.totalPages,
+    posts: buildStructuredPostCollection(entry.items, options.postBySlug),
+    pagination: buildStructuredPagination(entry.paginationData),
+  }));
+}
+
 function buildGlobalTaxonomyItems(site, permalinkKind, items, countBySlug) {
   return items.map((item) => ({
     name: item.name,
@@ -785,6 +1282,7 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, them
     updated_at_iso: post.updated_at_iso,
     author_id: post.author_id,
     featured_image: post.featured_image,
+    ...(post.featured_media ? { featured_media: { ...post.featured_media } } : {}),
     meta: post.meta,
     status: post.status,
     allow_comments: post.allow_comments,
@@ -794,6 +1292,7 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, them
       id: post.author_id,
       display_name: normalizeNonEmptyString(author?.display_name, post.author_id),
       avatar: author?.avatar || '',
+      ...(author?.avatar_media ? { avatar_media: { ...author.avatar_media } } : {}),
     },
     categories,
     tags,
@@ -904,6 +1403,7 @@ function buildPaginationData(currentPage, totalPages, totalPosts, basePath, outp
   const buildPageUrl = (page) => routePathToPublicUrl(buildPaginatedPath(basePath, page), outputStyle);
 
   return {
+    enabled: true,
     currentPage,
     totalPages,
     totalPosts,
@@ -922,8 +1422,23 @@ function buildPaginationData(currentPage, totalPages, totalPosts, basePath, outp
   };
 }
 
+function buildDisabledPaginationData(totalPosts) {
+  return {
+    enabled: false,
+    currentPage: 1,
+    totalPages: 1,
+    totalPosts,
+    hasNext: false,
+    hasPrev: false,
+    nextUrl: undefined,
+    prevUrl: undefined,
+    pages: [],
+  };
+}
+
 function buildStructuredPagination(paginationData) {
   return {
+    enabled: paginationData.enabled !== false,
     current_page: paginationData.currentPage,
     total_pages: paginationData.totalPages,
     total_items: paginationData.totalPosts,
@@ -1019,9 +1534,11 @@ function buildStructuredPostSummary(post) {
     published_at_iso: post.published_at_iso,
     reading_time: post.reading_time,
     featured_image: post.featured_image,
+    ...(post.featured_media ? { featured_media: { ...post.featured_media } } : {}),
     author: {
       display_name: post.author?.display_name || '',
       avatar: post.author?.avatar || '',
+      ...(post.author?.avatar_media ? { avatar_media: { ...post.author.avatar_media } } : {}),
     },
     categories: Array.isArray(post.categories) ? post.categories.map((category) => ({ ...category })) : [],
     tags: Array.isArray(post.tags) ? post.tags.map((tag) => ({ ...tag })) : [],
@@ -1271,7 +1788,8 @@ async function normalizeAndValidateThemePackage(themePackage) {
     ...(themePackage.metadata.features ? { features: themePackage.metadata.features } : {}),
     ...(themePackage.metadata.menuSlots ? { menuSlots: themePackage.metadata.menuSlots } : {}),
     ...(themePackage.metadata.widgetAreas ? { widgetAreas: themePackage.metadata.widgetAreas } : {}),
-    settings: themePackage.metadata.settings || {},
+    ...(themePackage.metadata.siteMeta ? { siteMeta: themePackage.metadata.siteMeta } : {}),
+    ...(themePackage.metadata.collectionSlots ? { collectionSlots: themePackage.metadata.collectionSlots } : {}),
   }));
 
   for (const [templateName, templateContent] of themePackage.templates.entries()) {
@@ -1307,7 +1825,6 @@ function normalizeThemePackageMetadata(sourceMetadata, manifest) {
   return {
     ...manifest,
     ...(sourceMetadata?.thumbnail ? { thumbnail: sourceMetadata.thumbnail } : {}),
-    settings: sourceMetadata?.settings || {},
   };
 }
 
@@ -1367,10 +1884,20 @@ function createRenderContext(site, currentUrl) {
   };
 }
 
+function buildRouteContext(type, url, options = {}) {
+  return {
+    type,
+    is_front_page: options.isFrontPage === true,
+    is_post_index: options.isPostIndex === true,
+    path: url,
+    url,
+  };
+}
+
 function buildPageMeta(site, options = {}) {
   const resolvedTitle = normalizeNonEmptyString(options.title, site.title);
   const resolvedDescription = normalizeOptionalString(options.description);
-  const canonicalUrl = resolveMetaCanonicalUrl(site, options.currentUrl);
+  const canonicalUrl = resolveMetaCanonicalUrl(site, options.canonicalUrl || options.currentUrl);
   const ogImage = resolveMetaImageUrl(options.image);
   const ogType = normalizeNonEmptyString(options.ogType, 'website');
   const publishedTime = normalizeOptionalString(options.publishedTime);
@@ -1471,7 +1998,7 @@ function normalizeMediaField(value, mediaBaseUrl) {
 
   const normalizedBaseUrl = normalizeOptionalString(mediaBaseUrl);
   if (!normalizedBaseUrl) {
-    return '';
+    return normalizedValue;
   }
 
   try {
@@ -1550,6 +2077,22 @@ function routePathToPublicUrl(routePath, outputStyle = DEFAULT_PERMALINKS.output
   return normalizedPath;
 }
 
+function pagePathToPublicUrl(routePath, outputStyle = DEFAULT_PERMALINKS.output_style) {
+  const normalizedPath = normalizeRoutePath(routePath);
+  if (outputStyle !== 'html-extension') {
+    return routePathToPublicUrl(normalizedPath, outputStyle);
+  }
+
+  const withoutTrailingSlash = normalizedPath.replace(/\/$/, '');
+  if (withoutTrailingSlash === '/index') {
+    return '/';
+  }
+  if (withoutTrailingSlash.endsWith('/index')) {
+    return `${withoutTrailingSlash.slice(0, -'/index'.length)}/`;
+  }
+  return withoutTrailingSlash;
+}
+
 function normalizeRoutePath(routePath) {
   if (!routePath || routePath === '/') {
     return '/';
@@ -1560,7 +2103,7 @@ function normalizeRoutePath(routePath) {
 
 function resolvePagePermalink(site, page) {
   if (normalizeOptionalString(page.path)) {
-    return buildRouteInfo(page.path, site.permalinks.output_style);
+    return buildRouteInfo(page.path, site.permalinks.output_style, { pagePath: true });
   }
   return resolvePermalink(site, 'pages', page);
 }
@@ -1570,15 +2113,21 @@ function resolvePermalink(site, kind, item) {
   return buildRouteInfo(applyPermalinkPattern(pattern, kind, item, site), site.permalinks.output_style);
 }
 
-function buildRouteInfo(routePath, outputStyle) {
+function buildRouteInfo(routePath, outputStyle, options = {}) {
   const path = normalizeRoutePath(routePath);
   return {
     path,
-    url: routePathToPublicUrl(path, outputStyle),
+    url: options.pagePath ? pagePathToPublicUrl(path, outputStyle) : routePathToPublicUrl(path, outputStyle),
     outputPath: routePathToOutputPath(path, outputStyle),
   };
 }
 
+function pageToOutputPath(page, outputStyle) {
+  return normalizeOptionalString(page.path)
+    ? routePathToOutputPath(page.path, outputStyle)
+    : routePathToOutputPath(page.url, outputStyle);
+}
+
 function applyPermalinkPattern(pattern, kind, item, site) {
   const tokenValues = buildPermalinkTokenValues(kind, item, site);
   const body = String(pattern || '').replace(/^\/+|\/+$/g, '');
@@ -1635,7 +2184,7 @@ function assertPlannedOutputPathsSafe(state) {
   }
 
   for (const page of state.renderData.pages) {
-    assertSafeSlugDerivedOutputPath(page.slug, routePathToOutputPath(page.url, outputStyle));
+    assertSafeSlugDerivedOutputPath(page.slug, pageToOutputPath(page, outputStyle));
   }
 
   for (const category of state.previewData.content.categories) {
@@ -1647,6 +2196,10 @@ function assertPlannedOutputPathsSafe(state) {
   }
 
   const routeEntries = [
+    ...(state.renderData.frontPageRoute ? [{
+      url: '/',
+      outputPath: 'index.html',
+    }] : []),
     ...state.renderData.indexRoutes.map((route) => ({
       url: routePathToPublicUrl(route.path, outputStyle),
       outputPath: routePathToOutputPath(route.path, outputStyle),
@@ -1669,7 +2222,7 @@ function assertPlannedOutputPathsSafe(state) {
     })),
     ...state.renderData.pages.map((page) => ({
       url: page.url,
-      outputPath: routePathToOutputPath(page.url, outputStyle),
+      outputPath: pageToOutputPath(page, outputStyle),
     })),
   ];
   assertUniqueRoutes(routeEntries);
@@ -1681,7 +2234,10 @@ function assertPlannedOutputPathsSafe(state) {
   ];
 
   if (state.options.generateSpecialFiles) {
-    plannedPaths.push('404.html', 'robots.txt');
+    plannedPaths.push('404.html');
+    if (shouldGenerateRobotsTxt(state.options)) {
+      plannedPaths.push('robots.txt');
+    }
     if (hasCanonicalSiteUrl(state.previewData.site.url)) {
       plannedPaths.push('sitemap.xml', 'feed.xml');
     }
@@ -1781,11 +2337,43 @@ function sha256(content) {
 }
 
 function injectSiteCustomizations(html, state) {
-  let next = injectCustomCssAssetLink(html, state.customCssHref);
+  let next = injectFaviconLinks(html, state.favicon);
+  next = injectCustomCssAssetLink(next, state.customCssHref);
   next = injectCustomHtml(next, state.customHtml);
   return next;
 }
 
+function injectFaviconLinks(html, favicon) {
+  const links = buildFaviconLinks(favicon);
+  if (!links) {
+    return html;
+  }
+
+  return html.replace('</head>', `${links}\n</head>`);
+}
+
+function buildFaviconLinks(favicon) {
+  if (!favicon || typeof favicon !== 'object') {
+    return '';
+  }
+
+  const lines = [];
+  if (normalizeOptionalString(favicon.icon)) {
+    lines.push(`  <link rel="icon" href="${escapeHtml(favicon.icon)}" sizes="any">`);
+  }
+  if (normalizeOptionalString(favicon.svg)) {
+    lines.push(`  <link rel="icon" href="${escapeHtml(favicon.svg)}" type="image/svg+xml">`);
+  }
+  if (normalizeOptionalString(favicon.png)) {
+    lines.push(`  <link rel="icon" href="${escapeHtml(favicon.png)}" type="image/png">`);
+  }
+  if (normalizeOptionalString(favicon.apple_touch_icon)) {
+    lines.push(`  <link rel="apple-touch-icon" href="${escapeHtml(favicon.apple_touch_icon)}">`);
+  }
+
+  return lines.join('\n');
+}
+
 function injectCustomCssAssetLink(html, href) {
   if (!normalizeOptionalString(href)) {
     return html;
@@ -1811,12 +2399,19 @@ function injectCustomHtml(html, customHtml) {
 
 function buildSitemapXml(site, emitted, generatedAt) {
   const entries = [
+    ...(emitted.frontPage
+      ? [{
+        url: emitted.frontPage.url,
+        changefreq: 'daily',
+        priority: 1.0,
+      }]
+      : []),
     ...emitted.indexRoutes
-      .filter((route) => route.url === '/')
+      .filter((route) => route.page === 1)
       .map((route) => ({
         url: route.url,
         changefreq: 'daily',
-        priority: 1.0,
+        priority: route.url === '/' ? 1.0 : 0.7,
       })),
     ...emitted.posts.map((post) => ({
       url: post.url,
@@ -1824,11 +2419,13 @@ function buildSitemapXml(site, emitted, generatedAt) {
       changefreq: 'weekly',
       priority: 0.8,
     })),
-    ...emitted.pages.map((page) => ({
-      url: page.url,
-      changefreq: 'monthly',
-      priority: 0.7,
-    })),
+    ...emitted.pages
+      .filter((page) => page.includeInSitemap !== false)
+      .map((page) => ({
+        url: page.url,
+        changefreq: 'monthly',
+        priority: 0.7,
+      })),
   ];
 
   const body = entries.map((entry) => {
@@ -1858,13 +2455,23 @@ function buildFeedXml(site, emitted, generatedAt) {
 }
 
 function buildRobotsTxt(site) {
-  const lines = ['User-agent: *', 'Allow: /'];
+  const lines = ['User-agent: *'];
+  if (site.indexing === false) {
+    lines.push('Disallow: /');
+    return `${lines.join('\n')}\n`;
+  }
+
+  lines.push('Allow: /');
   if (site.url) {
     lines.push('', `Sitemap: ${resolveSiteUrl(site.url, '/sitemap.xml')}`);
   }
   return `${lines.join('\n')}\n`;
 }
 
+function shouldGenerateRobotsTxt(options) {
+  return options.generateSpecialFiles && options.generateRobotsTxt !== false;
+}
+
 function getContentType(assetPath) {
   const ext = assetPath.split('.').pop()?.toLowerCase();
   const contentTypes = {