@zvndev/darkmown 1.2.1 → 1.4.0

package/src/compiler/context.js

@@ -32,6 +32,13 @@
  * @property {Set<string>} behaviors Names of framework behavior modules this page
  *   needs (`slider` is compile-time only and never appears here; `sortable`,
  *   `carousel` each emit a pay-for-what-you-use `/__wd/behaviors/<name>.js`).
+ * @property {boolean} hasCode Whether the page has a build-time-highlighted code
+ *   block, so the framework highlight stylesheet (`/__wd/highlight.css`) is
+ *   emitted and linked — pay-for-what-you-use, zero JS.
+ * @property {Set<string>} scopedSkins Source paths of colocated `.skin` files
+ *   that opted into scoping (`scoped` first line). The builder emits these with
+ *   the scope attribute and runs the unused-selector warning against the stamped
+ *   subtree; the HTML stamp uses them to scope the matching page/include subtree.
  */
 
 /**
@@ -140,7 +147,9 @@ export function createCompilation() {
       scripts: new Set(),
       files: new Map(),
       runtime: false,
-      behaviors: new Set()
+      behaviors: new Set(),
+      hasCode: false,
+      scopedSkins: new Set()
     },
     state: new Map(),
     stores: new Set(),

package/src/compiler/directives.js

@@ -12,7 +12,7 @@
 import { compileBody } from "./body.js";
 import { at, createScope, LOOP_META } from "./context.js";
 import { FORMATTERS } from "./format.js";
-import { resolveInclude } from "./includes.js";
+import { resolveInclude, scopedSkinFor } from "./includes.js";
 import {
   escapeHtml,
   getPath,
@@ -26,7 +26,7 @@ import {
   stripQuotes,
   validatePath
 } from "./interpolation.js";
-import { compileFile } from "./page.js";
+import { compileFile, stampScope } from "./page.js";
 import { compileComputedExpr, compileWhen, evalPredicate } from "./predicates.js";
 
 /**
@@ -45,17 +45,23 @@ export function handleInclude(line, ctx, index) {
   if (!match) throw new Error(`Malformed @include in ${at(ctx.file, index)}: ${line}`);
   const target = resolveInclude(match[1], ctx.file, ctx.context);
   const args = parseIncludeArgs(match[2] || "", ctx);
-  const scope = createScope(ctx.scope, args);
+  const childScope = createScope(ctx.scope, args);
   const child = compileFile(
     target,
     ctx.context,
     ctx.stack,
-    scope,
+    childScope,
     ctx.comp,
     ctx.sections,
     ctx.loopItem
   );
-  return child.html;
+  // An include with its OWN scoped colocated skin stamps just its returned
+  // subtree — so a scoped `.card` in the include can't collide with a `.card`
+  // anywhere else on the page, and the scope never leaks to the include's
+  // siblings (only this child HTML is stamped). The CSS rewrite (builder) uses
+  // the same path-derived id, so attribute and stylesheet line up.
+  const scopedSkin = scopedSkinFor(target, ctx.context);
+  return scopedSkin && scopedSkin.scoped ? stampScope(child.html, scopedSkin.scopeId) : child.html;
 }
 
 /**

package/src/compiler/includes.js

@@ -6,6 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { scopeIdFor } from "../skin.js";
 import { pageIncludeExtensions } from "./context.js";
 import { stripQuotes } from "./interpolation.js";
 
@@ -15,6 +16,47 @@ import { stripQuotes } from "./interpolation.js";
  * @typedef {import("./context.js").Compilation} Compilation
  */
 
+/**
+ * Read a `.skin` file's first meaningful line (skipping `//` line comments,
+ * `/* … *\/` block comments, blanks, and decorative dividers — the same skip
+ * rules `compileSkin` applies) to decide whether it opts into scoping. A skin
+ * scopes its selectors ONLY when that first line is exactly `scoped`; otherwise
+ * it is global and untouched. This is the single source for "is this skin
+ * scoped + what is its id", so the CSS rewrite (builder) and the HTML stamp
+ * (page/include) always agree on both.
+ * @param {string} skinPath Absolute path to the colocated `.skin` file.
+ * @param {string} cwd Project root, for the path-based scope id.
+ * @returns {{ scoped: boolean, scopeId: string }}
+ */
+export function scopeInfoForSkin(skinPath, cwd) {
+  const rel = path.relative(cwd, skinPath).replaceAll(path.sep, "/");
+  const scopeId = scopeIdFor(rel);
+  const src = fs.readFileSync(skinPath, "utf8").replace(/\/\*[\s\S]*?\*\//g, "");
+  for (const raw of src.split("\n")) {
+    const t = raw.trim();
+    if (!t || t.startsWith("//") || !/[A-Za-z0-9]/.test(t)) continue;
+    return { scoped: t === "scoped", scopeId };
+  }
+  return { scoped: false, scopeId };
+}
+
+/**
+ * The scope info for a page/include's OWN colocated `.skin` sibling, or null
+ * when there is no sibling skin. Used by the HTML stamp sites: a route's own
+ * scoped skin → stamp the page body; an include's scoped skin → stamp the
+ * returned subtree. Resolution mirrors `collectColocatedAssets` (same stem,
+ * `.skin` extension).
+ * @param {string} file Absolute path to the page/include source file.
+ * @param {Paths} context
+ * @returns {{ scoped: boolean, scopeId: string } | null}
+ */
+export function scopedSkinFor(file, context) {
+  const ext = path.extname(file);
+  const candidate = `${file.slice(0, -ext.length)}.skin`;
+  if (!fs.existsSync(candidate)) return null;
+  return scopeInfoForSkin(candidate, context.cwd);
+}
+
 /**
  * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
  * @param {string} file
@@ -35,7 +77,12 @@ export function collectColocatedAssets(file, context, assets) {
     const outputExt = assetExt === ".skin" ? ".css" : ".js";
     const publicPath = `/__wd/${folder}/${rel.slice(0, -assetExt.length).replace(/[/.]/g, "_")}${outputExt}`;
     assets.files.set(candidate, publicPath);
-    if (assetExt === ".skin") assets.skins.add(publicPath);
+    if (assetExt === ".skin") {
+      assets.skins.add(publicPath);
+      // Surface "this skin is scoped" so the warning pass (builder) and the HTML
+      // stamp can find the scoped skins among all colocated ones by source path.
+      if (scopeInfoForSkin(candidate, context.cwd).scoped) assets.scopedSkins.add(candidate);
+    }
     if (assetExt === ".js") assets.scripts.add(publicPath);
   }
 }

package/src/compiler/index.js

@@ -20,4 +20,4 @@
 export { parseFrontmatter } from "./frontmatter.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages } from "./page.js";
+export { compileDocument, compilePage, enhanceImages, stampScope } from "./page.js";

package/src/compiler/markdown.js

@@ -6,6 +6,7 @@
 // ---------------------------------------------------------------------------
 
 import MarkdownIt from "markdown-it";
+import { highlightCode } from "../highlight.js";
 import { LOOP_META } from "./context.js";
 import { applyPipeline, fmtAttr, validatePipes } from "./format.js";
 import {
@@ -21,7 +22,11 @@ import {
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
-const md = new MarkdownIt({ html: true });
+// Build-time syntax highlighting: highlight.js runs over every fenced code block
+// with a known language. The callback returns escaped token HTML or `""` to let
+// markdown-it render a plain escaped `<code>` (graceful degradation). Both
+// instances share it so `html: false` pages highlight too.
+const md = new MarkdownIt({ html: true, highlight: highlightCode });
 md.use(bindingPlugin);
 md.use(attrsPlugin);
 
@@ -39,7 +44,7 @@ export function selectMd(meta) {
   // Frontmatter scalars stay strings (no coercion), so accept both forms.
   if (meta?.html !== false && meta?.html !== "false") return md;
   if (!mdNoHtml) {
-    mdNoHtml = new MarkdownIt({ html: false });
+    mdNoHtml = new MarkdownIt({ html: false, highlight: highlightCode });
     mdNoHtml.use(bindingPlugin);
     mdNoHtml.use(attrsPlugin);
   }

package/src/compiler/page.js

@@ -8,10 +8,11 @@
 import fs from "node:fs";
 import path from "node:path";
 import { imageSize } from "image-size";
+import { htmlHasHighlight } from "../highlight.js";
 import { compileBody } from "./body.js";
 import { createCompilation, createScope } from "./context.js";
 import { parseFrontmatter, warnLikelyFrontmatter } from "./frontmatter.js";
-import { collectColocatedAssets, scanMarkdownHints } from "./includes.js";
+import { collectColocatedAssets, scanMarkdownHints, scopedSkinFor } from "./includes.js";
 import { escapeHtml } from "./interpolation.js";
 import { selectMd } from "./markdown.js";
 
@@ -29,9 +30,12 @@ import { selectMd } from "./markdown.js";
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
+ * @param {{ feed?: { href: string, title: string } }} [options] When a site-wide
+ *   RSS feed is emitted (the home page set `site_url` and the site has dated
+ *   posts), `feed` carries its absolute href + title so every page links it.
  * @returns {CompiledPage}
  */
-export function compilePage(file, context) {
+export function compilePage(file, context, options = {}) {
   const compiled = compileDocument(file, context);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
@@ -58,9 +62,21 @@ export function compilePage(file, context) {
   const descriptionTag = social.length ? `\n  ${social.join("\n  ")}` : "";
   const favicon =
     "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2032%2032'%3E%3Crect%20width='32'%20height='32'%20rx='6'%20fill='%2318221d'/%3E%3Ctext%20x='16'%20y='23'%20text-anchor='middle'%20font-family='Georgia,serif'%20font-size='19'%20font-weight='bold'%20fill='%23f7f3ea'%3ED%3C/text%3E%3C/svg%3E";
-  const cssLinks = [...compiled.assets.skins]
+  // The framework highlight stylesheet rides ahead of page skins so a project's
+  // own `$code-*` tokens / overrides still cascade over it. Pay-for-what-you-use:
+  // linked only on pages with a highlighted code block (`hasCode`).
+  const highlightLink = compiled.assets.hasCode
+    ? [`<link rel="stylesheet" href="/__wd/highlight.css">`]
+    : [];
+  const cssLinks = [...highlightLink, ...compiled.assets.skins]
     .map((href) => `<link rel="stylesheet" href="${href}">`)
     .join("\n");
+  // RSS feed discovery: when the site emits an `rss.xml` (home `site_url` set +
+  // at least one dated post), every page advertises it so readers/aggregators
+  // can autodiscover the feed. Build-time only — no client JS.
+  const feedLink = options.feed
+    ? `\n  <link rel="alternate" type="application/rss+xml" title="${escapeHtml(options.feed.title)}" href="${escapeHtml(options.feed.href)}">`
+    : "";
   // Pay-for-what-you-use behavior modules (slider is compile-time and never here;
   // sortable/carousel each emit one) load after the runtime — sortable depends on
   // `window.wd` — and before any colocated page script.
@@ -116,7 +132,14 @@ export function compilePage(file, context) {
     ? `\n  <script type="speculationrules">{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}</script>`
     : "";
 
-  const body = enhanceImages(compiled.html, context);
+  // A route whose OWN colocated skin opted into scoping stamps the whole page
+  // body so its scoped selectors match. Pure compile-time string post-pass (like
+  // enhanceImages) — no runtime, no `data-wd-*` marker, so a static page stays
+  // static. Include-scoped skins are stamped earlier, in handleInclude.
+  const scopedSkin = scopedSkinFor(file, context);
+  const stamped =
+    scopedSkin && scopedSkin.scoped ? stampScope(compiled.html, scopedSkin.scopeId) : compiled.html;
+  const body = enhanceImages(stamped, context);
 
   return {
     meta: compiled.meta,
@@ -126,7 +149,7 @@ export function compilePage(file, context) {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>${descriptionTag}
-  <link rel="icon" href="${favicon}">
+  <link rel="icon" href="${favicon}">${feedLink}
   ${cssLinks}${transitions}${speculation}
 </head>
 <body>
@@ -176,6 +199,30 @@ export function enhanceImages(html, paths) {
   });
 }
 
+/**
+ * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a regex
+ * post-pass over assembled HTML, zero runtime JS. Every element start tag that
+ * doesn't already carry a scope attribute gets one, so the scoped stylesheet
+ * (whose selectors end in `[data-wd-scope="<id>"]`) matches inside this subtree
+ * and nowhere else. Void/self-closing tags are stamped too (the attribute is
+ * valid on any element). Closing tags, comments, doctype, and the `<!`/`<?`
+ * families are left alone. A tag that ALREADY has a `data-wd-scope` (e.g. a
+ * nested include with its own scope) keeps its own — first stamp wins.
+ * @param {string} html Subtree HTML to scope.
+ * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
+ * @returns {string}
+ */
+export function stampScope(html, scopeId) {
+  return html.replace(
+    /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g,
+    (tag, name, attrs, slash) => {
+      if (/\bdata-wd-scope\s*=/.test(attrs)) return tag;
+      return `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+    }
+  );
+}
+
 /**
  * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
  * @param {string} tag
@@ -253,7 +300,9 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
 
   if (path.extname(file) === ".md") {
     scanMarkdownHints(body, file, comp);
-    return { meta, html: selectMd(meta).render(body, {}) };
+    const html = selectMd(meta).render(body, {});
+    if (htmlHasHighlight(html)) comp.assets.hasCode = true;
+    return { meta, html };
   }
 
   // Expose this file's frontmatter to the body under `meta` so `{ meta.title }`,
@@ -269,5 +318,7 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
     loopItem,
     md: selectMd(meta)
   };
-  return { meta, html: compileBody(body.replace(/\r\n?/g, "\n").split("\n"), ctx) };
+  const html = compileBody(body.replace(/\r\n?/g, "\n").split("\n"), ctx);
+  if (htmlHasHighlight(html)) comp.assets.hasCode = true;
+  return { meta, html };
 }

package/src/compiler.js

@@ -22,5 +22,6 @@ export {
   enhanceImages,
   escapeHtml,
   loopKeyOf,
-  parseFrontmatter
+  parseFrontmatter,
+  stampScope
 } from "./compiler/index.js";

package/src/dev.js

@@ -2,15 +2,44 @@ export const devClientPath = "/__wd/dev-client.js";
 export const devEventsPath = "/__wd/dev-events";
 
 /**
- * Inject the dev-client `<script>` before `</body>` (or append it if absent).
+ * Inject the dev-client `<script>` before `</body>` (or append it if absent),
+ * plus — for a `draft: true` page — an inline draft-banner script. Both are
+ * injected at dev-SERVE time only, so neither ever touches the shipped HTML on
+ * disk (a production build excludes drafts entirely; a `build --drafts` staging
+ * build emits clean HTML with no banner).
  * @param {string} html Page HTML to augment.
+ * @param {{ draft?: boolean }} [options] `draft: true` adds the visible banner.
  * @returns {string}
  */
-export function injectDevClient(html) {
-  const script = `<script type="module" src="${devClientPath}"></script>`;
+export function injectDevClient(html, options = {}) {
+  const scripts = [`<script type="module" src="${devClientPath}"></script>`];
+  if (options.draft) scripts.push(`<script>${draftBannerScript()}</script>`);
+  const block = scripts.join("\n");
   return html.includes("</body>")
-    ? html.replace("</body>", `${script}\n</body>`)
-    : `${html}\n${script}`;
+    ? html.replace("</body>", `${block}\n</body>`)
+    : `${html}\n${block}`;
+}
+
+/**
+ * The inline dev-only draft banner: a fixed bar marking the page as an unpublished
+ * draft, so it's unmistakable in `darkmown dev` that this content is excluded from
+ * a production build. Inert (`pointer-events:none`) and high-z so it never blocks
+ * the page; dev-serve-injected, so it's never in shipped output.
+ * @returns {string}
+ */
+export function draftBannerScript() {
+  return `
+const banner = document.createElement("div");
+banner.id = "__wd-draft-banner";
+banner.textContent = "DRAFT — excluded from production build";
+banner.style.cssText = [
+  "position:fixed", "top:0", "left:0", "right:0", "z-index:99998",
+  "background:#b4541b", "color:#fff8f0", "text-align:center",
+  "font:600 12px/2.2 ui-monospace,SFMono-Regular,Menlo,monospace",
+  "letter-spacing:.08em", "pointer-events:none"
+].join(";");
+document.addEventListener("DOMContentLoaded", () => document.body.prepend(banner));
+`;
 }
 
 /**

package/src/feeds.js

@@ -0,0 +1,276 @@
+// ---------------------------------------------------------------------------
+// Feeds & crawler files: sitemap.xml, rss.xml, robots.txt. All build-time only
+// (zero runtime, zero client JS) and emitted from the post-draft-filter route
+// list, so a `draft: true` page never reaches a feed. Site identity (origin,
+// channel title/description) lives in the HOME page frontmatter (`site_url` +
+// the existing `title`/`description`) — there is no config loader this cycle.
+//
+// Mirrors `src/highlight.js`: this module owns the strings; `src/builder.js`
+// owns the emission. Pure string builders + a `lastmodFor(file)` with a
+// git → mtime fallback so scaffolded apps / tarballs (no git repo) still date.
+// ---------------------------------------------------------------------------
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {import("./router.js").Route} Route
+ */
+
+/**
+ * A route paired with its source file's last-modified date (ISO yyyy-mm-dd),
+ * ready for a sitemap `<lastmod>`.
+ * @typedef {object} DatedRoute
+ * @property {string} loc Absolute URL (`site_url` + route path).
+ * @property {string} lastmod ISO date (`yyyy-mm-dd`).
+ */
+
+/**
+ * XML-escape a text value for use inside an element or attribute. Covers the
+ * five predefined XML entities — the same set RSS/sitemap consumers expect.
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeXml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+/**
+ * Join the site origin and a route path into one absolute URL, collapsing the
+ * boundary slash so `https://x.com` + `/about/` → `https://x.com/about/` (the
+ * home route `/` → `https://x.com/`). `siteUrl` is expected without a trailing
+ * slash (the documented contract); a stray one is tolerated.
+ * @param {string} siteUrl Absolute origin, e.g. `https://example.com`.
+ * @param {string} route Route path (always trailing-slashed, e.g. `/about/`).
+ * @returns {string}
+ */
+export function absoluteUrl(siteUrl, route) {
+  return `${siteUrl.replace(/\/$/, "")}${route}`;
+}
+
+/**
+ * The last-modified date for a source file, as an ISO `yyyy-mm-dd` string.
+ * Resolution order: the file's frontmatter `date:` is handled by the caller
+ * (it wins); this helper covers the fallback chain — the git last-commit date
+ * of the file, else the filesystem mtime. Git is wrapped in try/catch so a
+ * scaffolded app or an extracted tarball (no `.git`) degrades to mtime instead
+ * of crashing the build.
+ * @param {string} file Absolute path to the source file.
+ * @returns {string} ISO date (`yyyy-mm-dd`).
+ */
+export function lastmodFor(file) {
+  try {
+    // `%cs` is the committer date in strict ISO short form (yyyy-mm-dd). `-1`
+    // limits to the most recent commit touching this file. A file that is
+    // tracked but never committed (or outside a repo) yields empty stdout.
+    const out = execFileSync("git", ["log", "-1", "--format=%cs", "--", path.basename(file)], {
+      cwd: path.dirname(file),
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    if (out) return out;
+  } catch {
+    /* not a git repo, or git unavailable — fall through to mtime */
+  }
+  return isoDate(fs.statSync(file).mtime);
+}
+
+/**
+ * Format a `Date` as an ISO `yyyy-mm-dd` string (sitemap `<lastmod>` form).
+ * @param {Date} date
+ * @returns {string}
+ */
+export function isoDate(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+const RFC822_DAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+const RFC822_MONTHS = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec"
+];
+
+/**
+ * Format a frontmatter `date:` value as an RFC-822 date for an RSS `<pubDate>`
+ * (e.g. `Sat, 28 Jun 2026 00:00:00 GMT`). Accepts anything `new Date` parses
+ * (an ISO `yyyy-mm-dd`, a full timestamp); an unparseable value returns "" so
+ * the caller can omit the element rather than emit `Invalid Date`.
+ * @param {string} value Raw frontmatter date string.
+ * @returns {string} RFC-822 date in GMT, or "" when unparseable.
+ */
+export function rfc822(value) {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "";
+  const pad = (/** @type {number} */ n) => String(n).padStart(2, "0");
+  const day = RFC822_DAYS[date.getUTCDay()];
+  const month = RFC822_MONTHS[date.getUTCMonth()];
+  return (
+    `${day}, ${pad(date.getUTCDate())} ${month} ${date.getUTCFullYear()} ` +
+    `${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} GMT`
+  );
+}
+
+/**
+ * Read a frontmatter field as a trimmed string, or "" when absent/non-string
+ * (arrays, numbers, booleans don't belong in these single-value feed fields).
+ * @param {import("./compiler.js").Meta} meta
+ * @param {string} key
+ * @returns {string}
+ */
+function metaString(meta, key) {
+  const value = meta[key];
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * Extract the first paragraph of a plain-`.md` body as a single-line snippet —
+ * the RSS description fallback when a `.md` post has neither `excerpt:` nor
+ * `description:`. Deliberately dumb: skip leading blank/frontmatter-less lines,
+ * take the first run of non-blank prose, strip the most common inline markdown
+ * (heading marks, emphasis, inline-code, links → their text), and collapse
+ * whitespace. Returns "" when the body is empty or starts with a non-prose
+ * block (a fence/heading-only doc) — the caller then falls back further.
+ * @param {string} body The post-frontmatter markdown body.
+ * @returns {string}
+ */
+export function firstParagraph(body) {
+  const lines = body.replace(/\r\n?/g, "\n").split("\n");
+  let i = 0;
+  while (i < lines.length && !lines[i].trim()) i++;
+  // A heading or fenced block isn't a description paragraph — bail to the
+  // caller's next fallback rather than emit "# Title" or code as the summary.
+  if (i >= lines.length || /^(#{1,6}\s|```|~~~|>|[-*+]\s|\d+\.\s)/.test(lines[i].trim())) return "";
+  /** @type {string[]} */
+  const collected = [];
+  for (let j = i; j < lines.length && lines[j].trim(); j++) collected.push(lines[j].trim());
+  return collected
+    .join(" ")
+    .replace(/`([^`]+)`/g, "$1") // inline code → its text
+    .replace(/\*\*([^*]+)\*\*/g, "$1") // bold
+    .replace(/\*([^*]+)\*/g, "$1") // italic
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // [text](url) → text
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * The RSS `<description>` for a post: explicit `excerpt:` wins, else the source
+ * `description:`, else (plain `.md` only) the first rendered paragraph. `.wd`
+ * bodies are NOT scanned for a first paragraph — stripping reactive/directive
+ * markup back to clean prose is not worth the fragility, so a `.wd` post without
+ * `excerpt`/`description` simply gets no description.
+ * @param {import("./compiler.js").Meta} meta
+ * @param {string} file Absolute source path (its extension gates `.md` scanning).
+ * @param {string} body The post-frontmatter body.
+ * @returns {string}
+ */
+export function rssDescription(meta, file, body) {
+  const excerpt = metaString(meta, "excerpt");
+  if (excerpt) return excerpt;
+  const description = metaString(meta, "description");
+  if (description) return description;
+  if (path.extname(file) === ".md") return firstParagraph(body);
+  return "";
+}
+
+/**
+ * Build `sitemap.xml` from the emitted (post-draft-filter) routes. One `<url>`
+ * per route — reactive pages included (they're indexable HTML) — with `<loc>` =
+ * `site_url` + path and `<lastmod>` from the supplied date. The `/404/` route is
+ * excluded by the caller before this point. No `<priority>`/`<changefreq>` —
+ * Google ignores them and they invite bit-rot.
+ * @param {DatedRoute[]} entries Absolute loc + ISO lastmod, in route order.
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildSitemap(entries) {
+  const urls = entries
+    .map(
+      (entry) =>
+        `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n` +
+        `    <lastmod>${entry.lastmod}</lastmod>\n  </url>`
+    )
+    .join("\n");
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    `${urls}\n</urlset>\n`
+  );
+}
+
+/**
+ * An RSS item — a dated post in feed order.
+ * @typedef {object} RssItem
+ * @property {string} title
+ * @property {string} link Absolute URL (also used as the `<guid>`).
+ * @property {string} pubDate RFC-822 date, or "" to omit.
+ * @property {string} description
+ */
+
+/**
+ * Build `rss.xml` (RSS 2.0) for the dated posts. The caller selects, sorts
+ * (date desc), and caps the items; this builder just renders. Channel `<title>`
+ * / `<description>` come from the home frontmatter; `<link>` is the site origin
+ * and the `<atom:link rel="self">` points at the feed itself (RSS best practice).
+ * @param {{ title: string, description: string, siteUrl: string, feedUrl: string }} channel
+ * @param {RssItem[]} items
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildRss(channel, items) {
+  const entries = items.map((item) => {
+    const parts = [
+      `      <title>${escapeXml(item.title)}</title>`,
+      `      <link>${escapeXml(item.link)}</link>`,
+      `      <guid isPermaLink="true">${escapeXml(item.link)}</guid>`
+    ];
+    if (item.pubDate) parts.push(`      <pubDate>${item.pubDate}</pubDate>`);
+    if (item.description)
+      parts.push(`      <description>${escapeXml(item.description)}</description>`);
+    return `    <item>\n${parts.join("\n")}\n    </item>`;
+  });
+  const channelLines = [
+    `    <title>${escapeXml(channel.title)}</title>`,
+    `    <link>${escapeXml(channel.siteUrl)}</link>`,
+    `    <description>${escapeXml(channel.description)}</description>`,
+    `    <atom:link href="${escapeXml(channel.feedUrl)}" rel="self" type="application/rss+xml"/>`,
+    ...entries
+  ];
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">\n' +
+    "  <channel>\n" +
+    `${channelLines.join("\n")}\n` +
+    "  </channel>\n</rss>\n"
+  );
+}
+
+/**
+ * Build `robots.txt`. Always allows everything (hidden/draft routes are never
+ * built, so there's nothing to `Disallow`). The `Sitemap:` line is included
+ * ONLY when `siteUrl` is set — a sitemap URL is only meaningful with an origin.
+ * @param {string} [siteUrl] Absolute origin, or "" / undefined to omit the line.
+ * @returns {string} The robots.txt body (trailing newline).
+ */
+export function buildRobots(siteUrl) {
+  const lines = ["User-agent: *", "Allow: /"];
+  if (siteUrl) lines.push(`Sitemap: ${absoluteUrl(siteUrl, "/sitemap.xml")}`);
+  return `${lines.join("\n")}\n`;
+}
+
+/** Most-recent-first RSS post cap — a feed is a recent window, not an archive. */
+export const RSS_ITEM_LIMIT = 20;