@koehler8/cms 1.0.0-beta.8 → 1.0.0

package/src/utils/cookieConsent.js

@@ -3,8 +3,10 @@
  * Handles storing and retrieving user consent for analytics tracking
  */
 
-const CONSENT_KEY = 'cookie_consent';
-const CONSENT_TIMESTAMP_KEY = 'cookie_consent_timestamp';
+import { STORAGE_KEYS, readStorage, writeStorage } from './webStorage.js';
+
+const CONSENT = STORAGE_KEYS.consent;
+const CONSENT_TIMESTAMP = STORAGE_KEYS.consentTimestamp;
 const TRUTHY_ENV_VALUES = new Set(['1', 'true', 'yes', 'on']);
 
 export const ConsentStatus = {
@@ -39,16 +41,11 @@ export function isCookieBannerEnabled() {
  * @returns {string} One of ConsentStatus values
  */
 export function getConsentStatus() {
-  try {
-    const consent = localStorage.getItem(CONSENT_KEY);
-    if (consent === ConsentStatus.ACCEPTED || consent === ConsentStatus.DECLINED) {
-      return consent;
-    }
-    return ConsentStatus.PENDING;
-  } catch (error) {
-    console.warn('Unable to access localStorage for consent:', error);
-    return ConsentStatus.PENDING;
+  const consent = readStorage(CONSENT.kind, CONSENT.key, CONSENT.legacy);
+  if (consent === ConsentStatus.ACCEPTED || consent === ConsentStatus.DECLINED) {
+    return consent;
   }
+  return ConsentStatus.PENDING;
 }
 
 /**
@@ -56,14 +53,17 @@ export function getConsentStatus() {
  * @param {string} status - One of ConsentStatus values
  */
 export function setConsentStatus(status) {
+  const saved = writeStorage(CONSENT.kind, CONSENT.key, status);
+  writeStorage(CONSENT_TIMESTAMP.kind, CONSENT_TIMESTAMP.key, new Date().toISOString());
+  if (!saved) {
+    console.warn('Unable to persist consent status (storage unavailable)');
+  }
+
   try {
-    localStorage.setItem(CONSENT_KEY, status);
-    localStorage.setItem(CONSENT_TIMESTAMP_KEY, new Date().toISOString());
-    
     // Trigger custom event for other parts of the app to react
     window.dispatchEvent(new CustomEvent('consentChanged', { detail: { status } }));
-  } catch (error) {
-    console.error('Unable to save consent status:', error);
+  } catch {
+    /* no window (SSR) */
   }
 }
 
@@ -113,20 +113,34 @@ export function isConsentPending() {
 }
 
 /**
- * Determine if analytics should be active.
- * Pending consent defaults to enabled so tracking starts immediately.
+ * Consent mode — how the PENDING state (visitor hasn't answered the banner
+ * yet) is treated:
  *
- * NOTE: In EU/EEA jurisdictions, GDPR and the ePrivacy Directive require
- * affirmative consent before setting non-essential cookies or loading
- * tracking scripts. If the site targets EU users, consider changing the
- * PENDING case to return false so analytics remain disabled until the
- * user explicitly accepts.
+ *   'opt-out' (default): analytics load while consent is pending. Matches
+ *     the common US posture; tracking starts immediately and stops if the
+ *     visitor declines.
+ *   'opt-in': analytics stay OFF until the visitor explicitly accepts.
+ *     Required posture under GDPR / the ePrivacy Directive for EU/EEA
+ *     audiences — set `"analytics.consentMode": "opt-in"` in site.json.
  *
+ * Configured once at boot from site config (see createCmsApp); ACCEPTED and
+ * DECLINED behave identically in both modes.
+ */
+let analyticsConsentMode = 'opt-out';
+
+export function configureAnalyticsConsentMode(mode) {
+  analyticsConsentMode = mode === 'opt-in' ? 'opt-in' : 'opt-out';
+}
+
+/**
+ * Determine if analytics should be active.
  * @returns {boolean}
  */
 export function shouldEnableAnalytics() {
   const status = getConsentStatus();
-  return status === ConsentStatus.ACCEPTED || status === ConsentStatus.PENDING;
+  if (status === ConsentStatus.ACCEPTED) return true;
+  if (status === ConsentStatus.DECLINED) return false;
+  return analyticsConsentMode === 'opt-out';
 }
 
 let analyticsLoadPromise;

package/src/utils/draftMode.js

@@ -0,0 +1,65 @@
+/**
+ * Pure helpers for "draft mode" — letting authors mark a whole site, a URL
+ * prefix, or a single page as not-yet-public so search engines and casual
+ * visitors stay out while content is being iterated on.
+ *
+ * Used by:
+ *   - vite-plugin.js: emit Disallow lines in robots.txt, skip URLs in sitemap.xml
+ *   - usePageMeta.js: inject <meta name="robots" content="noindex,nofollow">
+ *   - useDraftGate.js: decide whether to render the password gate instead of
+ *     the page contents
+ *
+ * Resolution rule (page wins both ways, then site, then prefixes):
+ *   1. pageData.draft === true  → draft
+ *   2. pageData.draft === false → published (overrides site/prefix)
+ *   3. site.draft === true      → draft
+ *   4. any draftPaths prefix matches → draft
+ *   5. otherwise                → published
+ *
+ * Prefix match is path-segment-aware: "/blog" matches "/blog" and
+ * "/blog/2026/post" but NOT "/blog-archive". The literal prefix "/" matches
+ * only "/" itself; for whole-site draft, set site.draft = true instead.
+ */
+
+export function normalizeDraftPath(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  let p = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  return p || '/';
+}
+
+export function pathMatchesPrefix(prefix, path) {
+  const np = normalizeDraftPath(prefix);
+  const target = normalizeDraftPath(path);
+  if (!np || !target) return false;
+  if (np === target) return true;
+  if (np === '/') return false;
+  return target.startsWith(`${np}/`);
+}
+
+export function isPathDraft(siteData, pagePath, pageData) {
+  if (pageData && typeof pageData === 'object') {
+    if (pageData.draft === true) return true;
+    if (pageData.draft === false) return false;
+  }
+
+  const site = siteData?.site;
+  if (!site || typeof site !== 'object') return false;
+
+  if (site.draft === true) return true;
+
+  const draftPaths = Array.isArray(site.draftPaths) ? site.draftPaths : [];
+  for (const prefix of draftPaths) {
+    if (pathMatchesPrefix(prefix, pagePath)) return true;
+  }
+
+  return false;
+}
+
+export function getDraftPasswordHash(siteData) {
+  const raw = siteData?.site?.draftPasswordHash;
+  if (typeof raw !== 'string') return '';
+  return raw.trim().toLowerCase();
+}

package/src/utils/imageSources.js

@@ -1,5 +1,6 @@
 import { computed, ref, watch, unref } from 'vue';
 import { resolveAsset } from './assetResolver.js';
+import { getImageVariantWidths } from './loadConfig.js';
 
 const DEFAULT_FORMATS = ['avif', 'webp'];
 
@@ -69,7 +70,14 @@ function resolveBestFallback(basePath, widthList, format) {
 export function useResponsiveImage(relativePath, options = {}) {
   const basePath = computed(() => normalizeBasePath(unref(relativePath)));
   const widthInput = options.widths;
-  const widths = computed(() => normalizeWidths(unref(widthInput)));
+  // Default to the build's resolved variant widths: components that hardcode
+  // their own lists drift from what the pipeline generates (missing widths
+  // silently vanish from the srcset), and omitting widths used to disable
+  // responsive images entirely.
+  const widths = computed(() => {
+    const provided = normalizeWidths(unref(widthInput));
+    return provided.length ? provided : normalizeWidths(getImageVariantWidths());
+  });
   const fallbackFormat = computed(() => unref(options.fallbackFormat) || 'jpg');
   const formats = computed(() => {
     const provided = unref(options.formats);

package/src/utils/jsonLd.js

@@ -0,0 +1,66 @@
+/**
+ * Normalize per-page + site-wide JSON-LD blocks into a flat list of
+ * @unhead/vue script descriptors ready for `useHead({ script: [...] })`.
+ *
+ * Authoring conventions in `pages/{id}.json` and `site.json`:
+ *
+ *   "jsonld": { "@context": "https://schema.org", "@type": "Article", ... }
+ *
+ * or for multiple blocks on a page:
+ *
+ *   "jsonld": [
+ *     { "@type": "Article", ... },
+ *     { "@type": "BreadcrumbList", ... }
+ *   ]
+ *
+ * Page blocks ALWAYS append to site blocks (there's no "override" semantic
+ * — each schema.org block is an independent assertion, so listing both is
+ * the right behavior for a sitewide Organization + a page-specific Article).
+ *
+ * Skipped entirely on drafts and 404s; structured data on those would
+ * mislead crawlers (drafts shouldn't be indexed; 404s aren't authoritative).
+ */
+
+function normalizeBlock(block) {
+  if (!block || typeof block !== 'object' || Array.isArray(block)) return null;
+  // Inject the schema.org @context if the author omitted it. JSON-LD blocks
+  // without @context are ignored by all major consumers, so adding it
+  // defensively is the right default.
+  if (!block['@context']) {
+    return { '@context': 'https://schema.org', ...block };
+  }
+  return block;
+}
+
+// JSON.stringify does not escape `<`, so an author string containing
+// "</script>" would terminate the JSON-LD script element early and dump the
+// rest of the block as markup. `<` is the standard hardening — still
+// valid JSON, inert in HTML.
+export function toJsonLdString(value) {
+  return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+
+function collectBlocks(input) {
+  if (!input) return [];
+  if (Array.isArray(input)) {
+    return input.map(normalizeBlock).filter(Boolean);
+  }
+  const single = normalizeBlock(input);
+  return single ? [single] : [];
+}
+
+export function buildJsonLdScripts({ siteData, currentPage, isDraft, isNotFound } = {}) {
+  if (isDraft || isNotFound) return [];
+
+  const siteBlocks = collectBlocks(siteData?.site?.jsonld);
+  const pageBlocks = collectBlocks(currentPage?.jsonld);
+
+  const all = [...siteBlocks, ...pageBlocks];
+  if (all.length === 0) return [];
+
+  return all.map((block, i) => ({
+    type: 'application/ld+json',
+    innerHTML: toJsonLdString(block),
+    key: `jsonld-${block['@type'] || 'block'}-${i}`,
+  }));
+}

package/src/utils/loadConfig.js

@@ -1,5 +1,6 @@
 import { inflateFlatConfig } from './inflateFlatConfig.js';
 import { unwrapDefault } from './unwrapDefault.js';
+import { readStoredLocale } from './webStorage.js';
 
 function normalizeLocaleInput(value) {
     if (value === undefined || value === null) {
@@ -34,6 +35,65 @@ export function cloneConfig(value) {
     return value;
 }
 
+// Reduce a resolved config's `pages` map to a single page, preserving `site`
+// and `shared` (which every page needs globally). Used by the SSG pass when a
+// site opts into `site.trimInitialState` so each pre-rendered page embeds only
+// its own page config in `window.__INITIAL_STATE__` instead of the entire
+// site's pages (which is byte-identical on every page and can dominate the
+// page weight). Marks the result `pagesPartial: true` so the client knows the
+// embedded config can't resolve other pages and must lazy-load the full config
+// before in-SPA navigation (see usePageConfig.hydrateFromSyncCache). Returns
+// the config untouched when the page id is absent — a safe no-op fallback so a
+// mis-resolved route never trims away the page actually being rendered.
+export function trimConfigToPage(config, pageId) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) return config;
+    if (!config.pages || typeof config.pages !== 'object') return config;
+    if (!pageId || !Object.prototype.hasOwnProperty.call(config.pages, pageId)) return config;
+    return { ...config, pages: { [pageId]: config.pages[pageId] }, pagesPartial: true };
+}
+
+// Map a route being pre-rendered to its page id, for the SSG trim above.
+// Strips a leading `/{locale}` segment (non-base locales render at
+// `/{locale}/path`), normalizes trailing/duplicate slashes, and matches against
+// each page's `path` (defaulting a path-less page to '/'). Returns the id only
+// on an UNAMBIGUOUS single match — home, path-less, or colliding routes return
+// null so the caller keeps the full config (a safe no-op). Pure/exported so the
+// locale-strip + matching rules are unit-testable without a full SSG build.
+export function resolvePageIdForRoute(config, routePath, localeParam) {
+    if (typeof routePath !== 'string' || !routePath) return null;
+    let target = routePath;
+    if (localeParam && typeof localeParam === 'string') {
+        const prefix = `/${localeParam}`;
+        if (target === prefix) target = '/';
+        else if (target.startsWith(`${prefix}/`)) target = target.slice(prefix.length);
+    }
+    const normalize = (p) =>
+        (typeof p === 'string' ? p : '/').replace(/\/+/g, '/').replace(/\/+$/, '') || '/';
+    target = normalize(target);
+    const pages = (config && config.pages) || {};
+
+    // The SSG pre-renders `/404` from a site's custom `pages/404.json` (mirrors
+    // usePageConfig.selectPage's `/404` → `404` mapping). That page is
+    // conventionally path-less, so it can't be matched by `path` below — map the
+    // route to it directly. It is also deliberately NOT treated as living at `/`
+    // (see the id === '404' guard in the matcher) so it never collides with
+    // `home` there — the collision that otherwise makes `/` ambiguous on any
+    // site shipping a custom 404 page, suppressing the home-page trim.
+    const notFound = pages['404'];
+    const notFoundPathless = notFound && !(typeof notFound.path === 'string' && notFound.path.trim());
+    if (target === '/404' && notFoundPathless) return '404';
+
+    const matches = Object.entries(pages).filter(([id, data]) => {
+        const hasPath = data && typeof data.path === 'string' && data.path.trim();
+        // A page with no explicit `path` conventionally lives at `/` (home). The
+        // SSG-only `404` page is the exception: it is served at `/404`, never `/`.
+        const pagePath = hasPath ? data.path : (id === '404' ? null : '/');
+        if (pagePath === null) return false;
+        return normalize(pagePath) === target;
+    });
+    return matches.length === 1 ? matches[0][0] : null;
+}
+
 export function mergeConfigTrees(target, source, options = {}) {
     const { cloneTarget = false, skipEmpty = true } = options;
 
@@ -224,12 +284,8 @@ export function createConfigLoader(allModules) {
 
         let locale = explicitLocale;
 
-        if (!locale && typeof localStorage !== 'undefined') {
-            try {
-                locale = normalizeLocaleInput(localStorage.getItem('locale')) || undefined;
-            } catch {
-                locale = undefined;
-            }
+        if (!locale) {
+            locale = normalizeLocaleInput(readStoredLocale()) || undefined;
         }
 
         const normalizedLocale = typeof locale === 'string' ? locale.toLowerCase() : undefined;
@@ -307,13 +363,57 @@ let _loadConfigData = async () => {
 };
 
 let _availableLocales = [];
+let _baseLocale = '';
+let _imageVariantWidths = [];
+
+// Synchronous, client-side cache of the config the SSR/SSG pass already
+// resolved. Warmed once before mount (see main.js, from the vite-ssg-
+// serialized `initialState.siteConfig`) so the first client render can
+// populate synchronously and match the prerendered DOM — eliminating the
+// paint -> blank -> paint flash caused by config arriving asynchronously via
+// lazy dynamic-import chunks. Keyed by normalized locale; SSR never reads it.
+const _syncConfigCache = new Map();
+
+function normalizeConfigCacheKey(locale) {
+  if (typeof locale === 'string') {
+    const trimmed = locale.trim().toLowerCase();
+    if (trimmed) return trimmed;
+  }
+  return 'default';
+}
 
 export function setConfigLoader(instance) {
   if (!instance) return;
   _loadConfigData = instance.loadConfigData;
   _availableLocales = instance.availableLocales || [];
+  _baseLocale = typeof instance.baseLocale === 'string' ? instance.baseLocale : '';
+  _imageVariantWidths = Array.isArray(instance.imageVariantWidths) ? instance.imageVariantWidths : [];
+  _syncConfigCache.clear();
+}
+
+// Store a resolved config for synchronous retrieval during the first client
+// render. Pass the config exactly as the server resolved it (e.g. the
+// serialized `initialState.siteConfig`) so `peekConfigSync` returns a value
+// that matches the prerendered DOM.
+export function primeConfigSync(locale, config) {
+  if (!config || typeof config !== 'object') return;
+  _syncConfigCache.set(normalizeConfigCacheKey(locale), config);
+}
+
+// Retrieve a primed config synchronously, or null on a miss. Client-only fast
+// path used by usePageConfig; a miss falls back to the async loader.
+export function peekConfigSync(locale) {
+  return _syncConfigCache.get(normalizeConfigCacheKey(locale)) || null;
 }
 
 export { _availableLocales as availableLocales };
+export { _baseLocale as baseLocale };
+
+// The resolved image-variant width matrix from the build (site.imageVariants
+// .widths or the pipeline default). useResponsiveImage defaults to this so
+// srcsets only ever reference widths the pipeline actually generates.
+export function getImageVariantWidths() {
+  return _imageVariantWidths;
+}
 
 export const loadConfigData = (...args) => _loadConfigData(...args);

package/src/utils/robotsGenerator.js

@@ -0,0 +1,95 @@
+/**
+ * Build robots.txt body from the inflated site config.
+ *
+ * Replaces the static cms/public/robots.txt — the plugin writes this string
+ * to siteRoot/public/robots.txt at config time so per-site draft state
+ * regenerates the policy on every build.
+ *
+ * Compliance pages (/privacy, /terms, /cookies) are intentionally NOT
+ * disallowed: they are public, footer-linked, emit correct canonicals, and
+ * appear in sitemap.xml — disallowing them contradicts the sitemap and triggers
+ * "Blocked by robots.txt" (pages-in-a-sitemap) errors in Search Console.
+ *
+ * Draft pages and site.draftPaths prefixes are deliberately NOT disallowed
+ * here. robots.txt is public, so a per-path Disallow line is itself the
+ * discovery vector for an otherwise-unlinked draft URL — and a disallowed URL
+ * cannot be crawled, so Google never sees the page's noindex meta and can
+ * still index it URL-only from an external link ("Indexed, though blocked by
+ * robots.txt"). Draft privacy is enforced where it actually works: the
+ * password gate (SSG HTML on disk contains only the gate), the per-page
+ * <meta name="robots" content="noindex, nofollow"> from usePageMeta, and
+ * omission from sitemap.xml. Only the site-wide draft state emits a blanket
+ * "Disallow: /" — a pre-launch site has no individual URLs to disclose.
+ *
+ * site.robots.allowAiCrawlers (opt-in, default off): appends a dedicated block
+ * per known AI/LLM crawler (GPTBot, ClaudeBot, PerplexityBot, CCBot, etc.),
+ * each carrying the exact same Disallow list as the wildcard block — i.e.
+ * identical effective access, just declared explicitly per bot. Several sites
+ * were hand-editing this list directly into public/robots.txt; since that file
+ * is regenerated on every build, the hand edits were silently reverted on the
+ * next `build:ssg`/`generate:public-assets` run. This option makes the
+ * customization durable. Skipped entirely when site.draft === true — a
+ * pre-launch site shouldn't explicitly invite crawlers.
+ *
+ * If sitemapUrl is provided, appends a "Sitemap: <url>" line.
+ */
+
+// No framework-default disallows: every framework route is either public
+// (pages, locales) or non-indexable by construction (/404 emits noindex).
+const FRAMEWORK_DEFAULTS = [];
+
+// Order/grouping mirrors the hand-rolled lists sites had converged on before
+// this became a config option.
+const AI_CRAWLER_GROUPS = [
+  { comment: 'OpenAI / ChatGPT', agents: ['GPTBot', 'OAI-SearchBot', 'ChatGPT-User'] },
+  { comment: 'Anthropic / Claude', agents: ['anthropic-ai', 'ClaudeBot'] },
+  { comment: 'Perplexity', agents: ['PerplexityBot'] },
+  { comment: 'Common Crawl (used by many LLM training datasets)', agents: ['CCBot'] },
+  { comment: 'Google', agents: ['Googlebot', 'Googlebot-Extended'] },
+  { comment: 'Microsoft / Bing', agents: ['Bingbot'] },
+  { comment: 'Meta', agents: ['FacebookBot'] },
+  { comment: 'Diffbot', agents: ['Diffbot'] },
+];
+
+export function buildRobotsTxt(siteConfig, sitemapUrl = '') {
+  const site = siteConfig?.site || {};
+
+  const disallows = [...FRAMEWORK_DEFAULTS];
+
+  if (site.draft === true) {
+    disallows.push('/');
+  }
+
+  const lines = ['User-agent: *'];
+  if (disallows.length === 0) {
+    // A UA record needs a Disallow field; the empty value means "allow all".
+    lines.push('Disallow:');
+  }
+  for (const d of disallows) {
+    lines.push(`Disallow: ${d}`);
+  }
+
+  if (site.robots?.allowAiCrawlers === true && site.draft !== true) {
+    for (const group of AI_CRAWLER_GROUPS) {
+      lines.push('');
+      lines.push(`# ${group.comment}`);
+      for (const agent of group.agents) {
+        lines.push(`User-agent: ${agent}`);
+        if (disallows.length === 0) {
+          lines.push('Disallow:');
+        }
+        for (const d of disallows) {
+          lines.push(`Disallow: ${d}`);
+        }
+      }
+    }
+  }
+
+  const trimmedSitemap = (sitemapUrl || '').trim();
+  if (trimmedSitemap) {
+    lines.push('');
+    lines.push(`Sitemap: ${trimmedSitemap}`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/src/utils/sha256.js

@@ -0,0 +1,20 @@
+/**
+ * SHA-256 hex digest via Web Crypto API.
+ *
+ * Available in Node 19+ (globalThis.crypto.subtle), modern browsers, and
+ * happy-dom test environment (which inherits Node's globalThis.crypto). The
+ * CMS targets Node 20.19, so a single Web Crypto path is sufficient.
+ *
+ * Used by the draft gate: site.draftPassword is hashed at build time (in
+ * the Vite plugin) so the plaintext never reaches the bundle. At runtime,
+ * the user's input is hashed and compared against the stored hash.
+ */
+
+export async function sha256Hex(input) {
+  const text = typeof input === 'string' ? input : String(input ?? '');
+  const bytes = new TextEncoder().encode(text);
+  const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+}

package/src/utils/sitemapGenerator.js

@@ -0,0 +1,112 @@
+/**
+ * Build sitemap.xml from the inflated site config.
+ *
+ * Pages where isPathDraft() is true are skipped — drafts must not be in the
+ * sitemap. Returns '' when site.url is missing (the sitemap protocol requires
+ * absolute URLs); the plugin treats empty output as "do not write the file."
+ *
+ * Single-locale sites emit only <loc> per page. Multi-locale sites emit one
+ * <url> per page × locale — every localized URL is a first-class sitemap
+ * entry (Google's multilingual guidance) — each carrying the full
+ * <xhtml:link rel="alternate" hreflang="..." /> cluster plus an `x-default`
+ * pointing at the base-locale URL. The single-locale output stays
+ * byte-identical to pre-hreflang.
+ */
+
+import { isPathDraft, normalizeDraftPath } from './draftMode.js';
+import { buildCanonicalUrl } from './canonicalUrl.js';
+
+function escapeXml(value) {
+  return String(value).replace(/[<>&'"]/g, (c) => ({
+    '<': '&lt;',
+    '>': '&gt;',
+    '&': '&amp;',
+    "'": '&apos;',
+    '"': '&quot;',
+  }[c]));
+}
+
+export function buildSitemap(siteConfig, options = {}) {
+  const siteUrl = (siteConfig?.site?.url || '').trim().replace(/\/+$/, '');
+  if (!siteUrl) return '';
+  const trailingSlash = siteConfig?.site?.trailingSlash === true;
+
+  // Whole-site draft → no sitemap. robots.txt emits "Disallow: /" in this
+  // state, and listing URLs in the sitemap that the same robots blocks
+  // would be inconsistent (and would cause crawl-error noise in Search
+  // Console). Page-level draft:false in a fully-draft site only affects
+  // the runtime gate; it is not advertised to crawlers.
+  if (siteConfig?.site?.draft === true) return '';
+
+  const baseLocale = typeof options.baseLocale === 'string' ? options.baseLocale.toLowerCase() : '';
+  const availableLocales = Array.isArray(options.availableLocales)
+    ? options.availableLocales.map((l) => (typeof l === 'string' ? l.toLowerCase() : '')).filter(Boolean)
+    : [];
+  const isMultiLocale = availableLocales.length > 1;
+
+  const pages = siteConfig?.pages || {};
+  const entries = [];
+  const seenPaths = new Set();
+
+  for (const [, pageData] of Object.entries(pages)) {
+    if (!pageData || typeof pageData !== 'object') continue;
+    const pagePath = normalizeDraftPath(pageData.path) || '/';
+    if (isPathDraft(siteConfig, pagePath, pageData)) continue;
+    if (seenPaths.has(pagePath)) continue;
+    seenPaths.add(pagePath);
+
+    const baseUrl = buildCanonicalUrl({ siteUrl, baseLocale, locale: baseLocale, path: pagePath, trailingSlash });
+    if (!baseUrl) continue;
+
+    if (!isMultiLocale) {
+      entries.push({ loc: baseUrl, alternates: [] });
+      continue;
+    }
+
+    // Every locale version is its own <url> entry; the alternate cluster is
+    // identical across them (that's the spec — each entry lists all of its
+    // language versions, including itself).
+    const alternates = availableLocales.map((loc) => ({
+      hreflang: loc,
+      href: buildCanonicalUrl({ siteUrl, baseLocale, locale: loc, path: pagePath, trailingSlash }),
+    }));
+    alternates.push({ hreflang: 'x-default', href: baseUrl });
+
+    for (const loc of availableLocales) {
+      const localizedUrl = buildCanonicalUrl({ siteUrl, baseLocale, locale: loc, path: pagePath, trailingSlash });
+      if (localizedUrl) entries.push({ loc: localizedUrl, alternates });
+    }
+  }
+
+  if (entries.length === 0) return '';
+
+  entries.sort((a, b) => a.loc.localeCompare(b.loc));
+
+  const urlsetAttrs = isMultiLocale
+    ? 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml"'
+    : 'xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"';
+
+  const renderUrlEntry = (entry) => {
+    if (entry.alternates.length === 0) {
+      return `  <url><loc>${escapeXml(entry.loc)}</loc></url>`;
+    }
+    const altLines = entry.alternates
+      .map((a) => `    <xhtml:link rel="alternate" hreflang="${escapeXml(a.hreflang)}" href="${escapeXml(a.href)}"/>`)
+      .join('\n');
+    return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n${altLines}\n  </url>`;
+  };
+
+  const urlEntries = entries.map(renderUrlEntry).join('\n');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset ${urlsetAttrs}>
+${urlEntries}
+</urlset>
+`;
+}
+
+export function getSitemapUrl(siteConfig) {
+  const siteUrl = (siteConfig?.site?.url || '').trim().replace(/\/+$/, '');
+  if (!siteUrl) return '';
+  return `${siteUrl}/sitemap.xml`;
+}