@zvndev/darkmown 1.2.1 → 1.4.0

package/site/pages/highlight/index.wd

@@ -0,0 +1,142 @@
+---
+title: Syntax highlighting — code that dark-modes for free
+description: Build-time syntax highlighting in plain Markdown. Fenced code blocks highlight at compile time (zero client JS) and recolor with your theme through the same tokens dark / :theme system — flip the toggle and watch every language recolor at once.
+image: https://darkmown.com/__wd/media/og-showcase.png
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main class="wide app-highlight">
+
+::: section #highlight
+
+:theme
+
+::: hl-head
+::: eyebrow .hl-eyebrow
+Build-time syntax highlighting
+:::
+
+# *Highlighted code*
+
+::: hl-tagline
+Fenced code blocks highlight at **build time** — HTML and CSS only, no client
+JavaScript. Colors come from your skin's `$code-*` tokens, so highlighting
+recolors with the theme through the same `tokens dark` / `:theme` system that
+drives the rest of the page. Flip the toggle and watch every block below recolor
+at once — no toggle script for the code, no flash.
+:::
+:::
+
+::: theme-switch
+Theme
+:button "Auto" -> theme = "auto"
+:button "Light" -> theme = "light"
+:button "Dark" -> theme = "dark"
+:::
+
+::: grid .cols-2 .hl-grid
+
+::: card .hl-panel
+### JavaScript
+
+```js
+// A tiny reactive island, declared in Markdown.
+const cart = wd.state("cart");
+function total(items) {
+  return items.reduce((sum, it) => sum + it.price, 0);
+}
+wd.subscribe("cart", (items) => {
+  document.title = `Cart (${items.length})`;
+});
+```
+:::
+
+::: card .hl-panel
+### Python
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Expense:
+    merchant: str
+    amount: float  # in dollars
+
+def total(rows: list[Expense]) -> float:
+    return sum(r.amount for r in rows)
+```
+:::
+
+::: card .hl-panel
+### CSS
+
+```css
+.card {
+  background: var(--panel, #fff);
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 1.4rem;
+}
+```
+:::
+
+::: card .hl-panel
+### JSON
+
+```json
+{
+  "name": "@zvndev/darkmown",
+  "type": "module",
+  "zeroJsOnStaticPages": true,
+  "runtimeBudgetKb": 8
+}
+```
+:::
+
+::: card .hl-panel
+### Bash
+
+```bash
+npx @zvndev/darkmown init --template blog
+cd blog && npx darkmown dev   # live reload on :5173
+```
+:::
+
+::: card .hl-panel
+### HTML
+
+```html
+<main class="wide">
+  <a class="btn primary" href="/docs/">Read the docs</a>
+</main>
+```
+:::
+
+:::
+
+::: hl-note
+**How it works.** The highlighter is [highlight.js](https://highlightjs.org/),
+wired into Markdown's fenced-code path and mapped onto `$code-*` skin tokens.
+The stylesheet is **pay-for-what-you-use** — emitted and linked only on pages
+with a highlighted block. The highlighting itself ships zero JavaScript; the only
+reactive thing on this page is the theme toggle above (so you can demo the
+recolor without changing your OS setting). A fence with an unknown or absent
+language renders as plain escaped `<code>`, and inline `` `code` `` is never
+highlighted.
+:::
+
+::: hl-note .hl-degrade
+**Graceful degradation.** A bare fence (no language) or an unknown one stays
+plain — no highlighting, no error:
+
+```
+just a plain block — no language, so no highlighting
+```
+:::
+
+:::
+
+</main>

package/site/pages/index.wd

@@ -2,6 +2,7 @@
 title: Darkmown — Markdown that runs, not Markdown that needs React
 description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
 image: https://darkmown.com/__wd/media/og.png
+site_url: https://darkmown.com
 transitions: true
 ---
 

package/site/pages/scoped/index.skin

@@ -0,0 +1,23 @@
+scoped
+
+/* Page-scoped skin for this route. The whole page body is stamped, so these
+   selectors style only this page's own markup — proving page-level scoping
+   alongside the two include-scoped components. A :global() escape hatch shows a
+   single rule opting back out to a plain, unscoped selector. */
+
+.intro
+  margin 2rem 0 3rem
+
+.duo
+  margin 3rem 0
+
+.how
+  margin 4rem 0 2rem
+
+.how ul
+  color $ink-soft
+
+/* :global escape — this selector ships UNSCOPED, matching site-wide. */
+:global(.scoped-note)
+  font-size .85rem
+  color $muted

package/site/pages/scoped/index.wd

@@ -0,0 +1,47 @@
+---
+title: Scoped styles — same class name, zero collision
+description: Two components reuse the class name .card and never clash. Compile-time scoped styles stamp each component's subtree with a path-derived id and rewrite its skin's selectors to match only there. Zero runtime JS — a static page stays static.
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 1.4</span>
+
+# Scoped styles
+
+Two components on this page both call their root element `.card`. In plain CSS the second skin would overwrite the first. Here they coexist: a `.skin` whose first line is `scoped` only ever styles the subtree it ships with. It's pure compile time — a path-derived id stamped onto the HTML and appended to the skin's selectors. No runtime, no class hashing in your markup, no collision.
+
+</section>
+
+<section class="duo">
+
+<div class="grid cols-2">
+
+@include /scoped-promo.wd
+@include /scoped-stat.wd
+
+</div>
+
+</section>
+
+<section class="how">
+
+## What actually shipped
+
+- The `.card` in the warm promo and the `.card` in the dark stat tile are **different rules**, scoped to different ids.
+- This page also uses a **global** skin (`base.skin`, via `/base.wd`) — `.btn`, `.eyebrow`, `.grid` still work everywhere, unscoped.
+- Design **tokens stay global**: every scoped skin still reads `$accent`, `$warm`, `$radius` from `:root`, so dark mode keeps working for free.
+- A `:global(.x)` selector inside a scoped skin opts a single rule back out.
+
+<a class="btn primary" href="/docs/">Read the docs</a>
+
+</section>
+
+</main>
+
+@include /footer.wd

package/src/builder.js

@@ -2,15 +2,28 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverApiRoutes } from "./api-runner.js";
-import { compilePage } from "./compiler.js";
+import { compilePage, parseFrontmatter } from "./compiler.js";
 import { createPaths } from "./config.js";
+import {
+  absoluteUrl,
+  buildRobots,
+  buildRss,
+  buildSitemap,
+  lastmodFor,
+  RSS_ITEM_LIMIT,
+  rfc822,
+  rssDescription
+} from "./feeds.js";
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
+import { HIGHLIGHT_CSS } from "./highlight.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
-import { compileSkin } from "./skin.js";
+import { compileSkin, scopeIdFor } from "./skin.js";
 
 /**
  * @typedef {import("./config.js").Paths} Paths
  * @typedef {import("./compiler.js").Assets} Assets
+ * @typedef {import("./compiler.js").Meta} Meta
+ * @typedef {import("./router.js").Route} Route
  */
 
 /**
@@ -34,15 +47,30 @@ const moduleDir = path.dirname(fileURLToPath(import.meta.url));
  * `/api/*` to those same functions and serves everything else as a static asset.
  *
  * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
- * @param {{ target?: string }} [options] `target: "cloudflare"` emits the Pages worker.
- * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
+ * @param {{ target?: string, includeDrafts?: boolean }} [options] `target:
+ *   "cloudflare"` emits the Pages worker. `includeDrafts: true` keeps `draft:
+ *   true` pages in the build + feeds (dev / `build --drafts`); default excludes
+ *   them at route discovery so feeds never see a draft.
+ * @returns {{ routes: RouteManifestEntry[], distRoot: string, feeds: { sitemap: number | null, rss: number | null } }}
  */
 export function buildSite(cwd = process.cwd(), options = {}) {
   const paths = createPaths(cwd);
   fs.rmSync(paths.distRoot, { recursive: true, force: true });
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
-  const routes = discoverRoutes(paths.routesRoot);
+  const routes = discoverRoutes(paths.routesRoot, { includeDrafts: options.includeDrafts });
+  // Site identity lives in the HOME page frontmatter (no config loader): the
+  // `site_url` origin triggers + prefixes the feeds, reusing `title`/`description`
+  // as the RSS channel fields. Resolved once, up front, so every page can link
+  // the feed during the loop.
+  const identity = siteIdentity(routes);
+  // Advertise the feed in every page's <head> only when rss.xml will actually be
+  // emitted: the home set `site_url` AND there is at least one dated post. A
+  // stale `<link>` to a missing feed would 404 for aggregators.
+  const feedLink =
+    identity.siteUrl && hasDatedPost(routes)
+      ? { href: absoluteUrl(identity.siteUrl, "/rss.xml"), title: identity.title }
+      : undefined;
   /** @type {RouteManifestEntry[]} */
   const manifest = [];
 
@@ -53,7 +81,7 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   let notFoundHtml;
 
   for (const route of routes) {
-    const page = compilePage(route.file, paths);
+    const page = compilePage(route.file, paths, { feed: feedLink });
     for (const warning of page.warnings || []) {
       if (warned.has(warning)) continue;
       warned.add(warning);
@@ -63,9 +91,10 @@ export function buildSite(cwd = process.cwd(), options = {}) {
     fs.mkdirSync(path.dirname(outFile), { recursive: true });
     fs.writeFileSync(outFile, page.html);
     if (route.route === "/404/") notFoundHtml = page.html;
-    emitAssets(page.assets, paths);
+    emitAssets(page.assets, paths, page.html, warned);
     if (page.assets.runtime) emitRuntime(paths);
     emitBehaviors(page.assets, paths);
+    if (page.assets.hasCode) emitHighlight(paths);
     const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
     manifest.push({
       route: route.route,
@@ -95,6 +124,11 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   // one. A catch-all keeps assets and any future path covered.
   fs.writeFileSync(path.join(paths.distRoot, "_headers"), renderCloudflareHeaders(manifest));
 
+  // Crawler files + feeds. robots.txt is ALWAYS emitted; sitemap.xml + rss.xml
+  // need the home `site_url` (else a loud, actionable build hint). Drafts are
+  // already filtered out of `routes`, so neither feed can ever see one.
+  const feeds = emitFeeds(routes, identity, paths);
+
   // Page-colocated static assets (images, SVG, fonts, …) copy last, so the guard
   // sees every emitted route/framework file already on disk.
   emitPageAssets(paths);
@@ -109,7 +143,113 @@ export function buildSite(cwd = process.cwd(), options = {}) {
     emitCloudflareWorker(paths, apiDir, apiRoutes);
   }
 
-  return { routes: manifest, distRoot: paths.distRoot };
+  return { routes: manifest, distRoot: paths.distRoot, feeds };
+}
+
+/**
+ * Resolve the site's identity from the HOME route's frontmatter — the single
+ * place site-wide metadata lives this cycle (no config loader). `site_url` is
+ * the absolute origin (no trailing slash) that triggers and prefixes the feeds;
+ * `title`/`description` double as the RSS channel fields. A site with no `/`
+ * route, or a home page without `site_url`, yields an empty `siteUrl` and the
+ * feeds are skipped (robots still emits).
+ * @param {Route[]} routes
+ * @returns {{ siteUrl: string, title: string, description: string }}
+ */
+function siteIdentity(routes) {
+  const home = routes.find((route) => route.route === "/");
+  const meta = home ? home.meta : {};
+  const read = (/** @type {string} */ key) =>
+    typeof meta[key] === "string" ? String(meta[key]).trim() : "";
+  return {
+    siteUrl: read("site_url").replace(/\/$/, ""),
+    title: read("title") || "Darkmown",
+    description: read("description")
+  };
+}
+
+/**
+ * Whether any emitted route is a "post" — has a frontmatter `date:`. That's the
+ * RSS inclusion signal, and (collectively) the trigger for emitting rss.xml at
+ * all alongside the home `site_url`.
+ * @param {Route[]} routes
+ * @returns {boolean}
+ */
+function hasDatedPost(routes) {
+  return routes.some((route) => typeof route.meta.date === "string" && route.meta.date.trim());
+}
+
+/**
+ * Emit robots.txt (always) and, when the home page set `site_url`, sitemap.xml
+ * (every non-404 route) and rss.xml (dated posts only). Returns the URL/item
+ * counts (`null` when a feed was skipped) for the CLI build summary.
+ *
+ * The sitemap `<lastmod>` for each route is the frontmatter `date:` if present,
+ * else `lastmodFor(file)` (git last-commit date → file mtime). RSS items are the
+ * routes with a `date:`, newest first, capped at {@link RSS_ITEM_LIMIT}.
+ * @param {Route[]} routes Emitted (post-draft-filter) routes.
+ * @param {{ siteUrl: string, title: string, description: string }} identity
+ * @param {Paths} paths
+ * @returns {{ sitemap: number | null, rss: number | null }}
+ */
+function emitFeeds(routes, identity, paths) {
+  fs.writeFileSync(path.join(paths.distRoot, "robots.txt"), buildRobots(identity.siteUrl));
+
+  if (!identity.siteUrl) {
+    console.warn(
+      "hint: set site_url in site/pages/index frontmatter to emit sitemap.xml + rss.xml " +
+        "(e.g. `site_url: https://example.com`). robots.txt was still written."
+    );
+    return { sitemap: null, rss: null };
+  }
+
+  // The `/404/` route is never a feed entry — it's not an indexable page and
+  // not a post. Filter it out once; both feeds work off the result.
+  const feedable = routes.filter((route) => route.route !== "/404/");
+
+  // Sitemap: one <url> per emitted route (404 excluded above).
+  const sitemapEntries = feedable.map((route) => ({
+    loc: absoluteUrl(identity.siteUrl, route.route),
+    lastmod:
+      typeof route.meta.date === "string" && route.meta.date.trim()
+        ? String(route.meta.date).trim().slice(0, 10)
+        : lastmodFor(route.file)
+  }));
+  fs.writeFileSync(path.join(paths.distRoot, "sitemap.xml"), buildSitemap(sitemapEntries));
+
+  // RSS: dated posts only, newest first, capped. The `date:` is the "this is a
+  // post" signal. With no dated post there is nothing to syndicate, so rss.xml
+  // is skipped entirely (and the per-page `<link rel=alternate>` is too) — an
+  // empty feed file would just 404-by-content for aggregators.
+  const posts = feedable
+    .filter((route) => typeof route.meta.date === "string" && route.meta.date.trim())
+    .sort((a, b) => String(b.meta.date).localeCompare(String(a.meta.date)))
+    .slice(0, RSS_ITEM_LIMIT);
+  if (posts.length === 0) return { sitemap: sitemapEntries.length, rss: null };
+
+  const items = posts.map((route) => {
+    const { body } = parseFrontmatter(fs.readFileSync(route.file, "utf8"), route.file);
+    return {
+      title: typeof route.meta.title === "string" ? route.meta.title : "Untitled",
+      link: absoluteUrl(identity.siteUrl, route.route),
+      pubDate: rfc822(String(route.meta.date)),
+      description: rssDescription(route.meta, route.file, body)
+    };
+  });
+  fs.writeFileSync(
+    path.join(paths.distRoot, "rss.xml"),
+    buildRss(
+      {
+        title: identity.title,
+        description: identity.description,
+        siteUrl: identity.siteUrl,
+        feedUrl: absoluteUrl(identity.siteUrl, "/rss.xml")
+      },
+      items
+    )
+  );
+
+  return { sitemap: sitemapEntries.length, rss: items.length };
 }
 
 /**
@@ -388,22 +528,111 @@ function emitBehaviors(assets, paths) {
 }
 
 /**
+ * Emit the framework syntax-highlighting stylesheet `/__wd/highlight.css`, called
+ * only for a page that has a build-time-highlighted code block (`assets.hasCode`).
+ * It is CSS only — highlighting is build-time HTML + this stylesheet, with zero
+ * runtime JS — and maps highlight.js token classes onto the `$code-*` skin tokens,
+ * so code dark-modes for free through `tokens dark` / `:theme`. Idempotent: writing
+ * the same content per code-bearing page is harmless and keeps the call site simple.
+ * @param {Paths} paths
+ * @returns {void}
+ */
+function emitHighlight(paths) {
+  const out = path.join(paths.distRoot, "__wd/highlight.css");
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, HIGHLIGHT_CSS);
+}
+
+/**
+ * Emit a page's colocated assets. `.skin` files compile through {@link compileSkin}
+ * (other files copy verbatim). A skin that opted into scoping (`assets.scopedSkins`)
+ * compiles in scoped mode: the scope id is derived here from its PROJECT-RELATIVE
+ * PATH — the single coordination point with the HTML stamp, which derives the same
+ * id from the same path — and threaded into `compileSkin({ scope })`. The compiler
+ * also reports the scoped subject selectors, which we check against the stamped page
+ * HTML to warn (never remove) on a scoped selector that matches no element.
  * @param {Assets} assets
  * @param {Paths} paths
+ * @param {string} pageHtml Assembled page HTML (carries the `data-wd-scope` stamps).
+ * @param {Set<string>} warned Cross-route dedupe set for emitted hints.
  * @returns {void}
  */
-function emitAssets(assets, paths) {
+function emitAssets(assets, paths, pageHtml, warned) {
   for (const [source, href] of assets.files) {
     const out = path.join(paths.distRoot, href);
     fs.mkdirSync(path.dirname(out), { recursive: true });
     if (source.endsWith(".skin")) {
-      fs.writeFileSync(out, compileSkin(fs.readFileSync(source, "utf8")));
+      const src = fs.readFileSync(source, "utf8");
+      if (assets.scopedSkins.has(source)) {
+        const rel = path.relative(paths.cwd, source).replaceAll(path.sep, "/");
+        const scope = scopeIdFor(rel);
+        /** @type {Set<string>} */
+        const subjects = new Set();
+        fs.writeFileSync(out, compileSkin(src, { scope, subjects }));
+        warnUnusedScoped(subjects, scope, pageHtml, path.basename(source), warned);
+      } else {
+        fs.writeFileSync(out, compileSkin(src));
+      }
     } else {
       fs.copyFileSync(source, out);
     }
   }
 }
 
+/**
+ * Warn (do NOT remove) when a scoped selector's subject never appears in its
+ * stamped subtree — a likely typo or stale rule. We only have a class/element/id
+ * to look for, so we scan the elements actually stamped with THIS scope id in the
+ * assembled page and check each subject against them. A colocated `.js` may add
+ * classes at runtime, so this stays advisory: the rule is always emitted. An empty
+ * subject token (a bare attribute-selector subject) is unknowable here and skipped.
+ * @param {Set<string>} subjects Scoped subject tokens (`.card`, `h2`, `#id`).
+ * @param {string} scope Scope id.
+ * @param {string} pageHtml Assembled page HTML.
+ * @param {string} skinName Skin filename for the message.
+ * @param {Set<string>} warned Cross-route dedupe set.
+ * @returns {void}
+ */
+function warnUnusedScoped(subjects, scope, pageHtml, skinName, warned) {
+  // The opening tags carrying this scope id — the only elements the scoped
+  // stylesheet can match. One scan, reused for every subject.
+  const stamped = pageHtml.match(
+    new RegExp(`<[a-zA-Z][\\w-]*[^>]*\\bdata-wd-scope="${scope}"[^>]*>`, "g")
+  );
+  const tags = stamped ?? [];
+  for (const subject of subjects) {
+    if (!subject) continue;
+    const present = tags.some((tag) => subjectMatchesTag(subject, tag));
+    if (present) continue;
+    const warning = `scoped selector "${subject}" in ${skinName} matches no element`;
+    if (warned.has(warning)) continue;
+    warned.add(warning);
+    console.warn(`hint: ${warning}`);
+  }
+}
+
+/**
+ * Whether a scoped subject token (`.card` / `#id` / a bare tag like `h2`) could
+ * match a single stamped opening tag. Class subjects look in the tag's `class`
+ * attribute; id subjects in `id`; a bare tag compares the element name.
+ * @param {string} subject
+ * @param {string} tag A single opening tag string.
+ * @returns {boolean}
+ */
+function subjectMatchesTag(subject, tag) {
+  if (subject.startsWith(".")) {
+    const cls = subject.slice(1);
+    const m = tag.match(/\bclass\s*=\s*"([^"]*)"/);
+    return m ? m[1].split(/\s+/).includes(cls) : false;
+  }
+  if (subject.startsWith("#")) {
+    const m = tag.match(/\bid\s*=\s*"([^"]*)"/);
+    return m ? m[1] === subject.slice(1) : false;
+  }
+  const name = tag.match(/^<([a-zA-Z][\w-]*)/);
+  return name ? name[1].toLowerCase() === subject.toLowerCase() : false;
+}
+
 /**
  * Copy non-page shelf assets (JSON data, media) into `dist/__wd`.
  * @param {Paths} paths

package/src/cli.js

@@ -6,8 +6,10 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { handleApiRequest } from "./api-runner.js";
 import { buildSite } from "./builder.js";
+import { createPaths } from "./config.js";
 import { DEPLOY_TARGETS, deploy } from "./deploy.js";
 import { devClientPath, devClientScript, devEventsPath, injectDevClient } from "./dev.js";
+import { discoverRoutes, isDraft, outputPathForRoute } from "./router.js";
 import { availableTemplates, initProject } from "./scaffold.js";
 import { contentType, resolvePublicFile, serve } from "./statics.js";
 
@@ -64,8 +66,11 @@ export async function run(argv, env = {}) {
   }
   if (command === "build") {
     const target = flagValue(argv, "--target");
-    const result = buildSite(cwd, { target });
-    log(`Built ${result.routes.length} routes into ${path.relative(cwd, result.distRoot)}`);
+    // `--drafts` includes `draft: true` pages in the build + feeds (staging);
+    // the default production build excludes them at route discovery.
+    const includeDrafts = argv.includes("--drafts");
+    const result = buildSite(cwd, { target, includeDrafts });
+    log(buildSummary(result, path.relative(cwd, result.distRoot)));
     if (target === "cloudflare")
       log("Emitted dist/_worker.js for Cloudflare Pages api/* functions");
     return { command: "build" };
@@ -131,8 +136,10 @@ function startDevServer({ cwd, log, warn, error }) {
   // A broken initial build must NOT crash the process before the HTTP server —
   // and thus the error overlay — comes up. Record the error so new SSE clients
   // see it on connect; the next successful rebuild clears it via `reload`.
+  // Dev builds + serves `draft: true` pages (they're work-in-progress you want
+  // to preview); the dev client stamps a visible banner so a draft is obvious.
   try {
-    buildSite(cwd);
+    buildSite(cwd, { includeDrafts: true });
   } catch (err) {
     lastBuildError = (err instanceof Error ? err.message : String(err)).trim();
     error(lastBuildError);
@@ -144,7 +151,7 @@ function startDevServer({ cwd, log, warn, error }) {
     clearTimeout(timer);
     timer = setTimeout(() => {
       const started = performance.now();
-      execFile(process.execPath, [cliPath, "build"], { cwd }, (err, stdout, stderr) => {
+      execFile(process.execPath, [cliPath, "build", "--drafts"], { cwd }, (err, stdout, stderr) => {
         if (err) {
           const message = (stderr || stdout || String(err)).trim();
           lastBuildError = message;
@@ -204,7 +211,7 @@ function startDevServer({ cwd, log, warn, error }) {
     // throw on either path (e.g. a stat/read error) becomes a clean 500.
     handleApiRequest({ apiDir, req, res })
       .then((handled) => {
-        if (!handled) serveDev(distRoot, url, res);
+        if (!handled) serveDev(distRoot, url, res, draftRoutes(cwd));
       })
       .catch((err) => {
         res.writeHead(500, { "content-type": "text/plain" });
@@ -262,9 +269,11 @@ function startPreviewServer({ cwd, log, error }) {
  * @param {string} distRoot
  * @param {string} url
  * @param {import("node:http").ServerResponse} res
+ * @param {Set<string>} draftFiles Absolute dist HTML paths of draft pages — each
+ *   gets the dev-only draft banner injected (never written to disk).
  * @returns {void}
  */
-function serveDev(distRoot, url, res) {
+function serveDev(distRoot, url, res, draftFiles) {
   const file = resolvePublicFile(distRoot, url);
   if (!file || !fs.existsSync(file)) {
     serve(distRoot, url, res);
@@ -274,7 +283,7 @@ function serveDev(distRoot, url, res) {
     // Read BEFORE writing headers: if the read throws (e.g. the path is a
     // directory), the handler's catch can still send a clean 500 instead of
     // failing to overwrite an already-sent 200.
-    const html = injectDevClient(fs.readFileSync(file, "utf8"));
+    const html = injectDevClient(fs.readFileSync(file, "utf8"), { draft: draftFiles.has(file) });
     res.writeHead(200, { "content-type": "text/html" });
     res.end(html);
     return;
@@ -283,6 +292,24 @@ function serveDev(distRoot, url, res) {
   fs.createReadStream(file).pipe(res);
 }
 
+/**
+ * The set of absolute dist HTML paths that correspond to `draft: true` source
+ * pages, so the dev server can banner exactly those. Recomputed per HTML request
+ * (cheap, and stays correct as a page gains/loses `draft:` during a dev session).
+ * Returns an empty set when the project has no `site/pages` yet.
+ * @param {string} cwd Project working directory.
+ * @returns {Set<string>}
+ */
+function draftRoutes(cwd) {
+  const paths = createPaths(cwd);
+  /** @type {Set<string>} */
+  const drafts = new Set();
+  for (const route of discoverRoutes(paths.routesRoot, { includeDrafts: true })) {
+    if (isDraft(route.meta)) drafts.add(outputPathForRoute(paths.distRoot, route.route));
+  }
+  return drafts;
+}
+
 /**
  * @param {Set<import("node:http").ServerResponse>} clients
  * @param {string} message
@@ -303,6 +330,7 @@ Usage:
   darkmown init [dir] [--template <name>]   Scaffold a new project from a template
   darkmown dev                              Start the live compiler dev server
   darkmown build [--target cloudflare]      Compile site/pages into dist
+            [--drafts]                      Include draft: true pages (staging)
   darkmown deploy <${DEPLOY_TARGETS.join("|")}> [--prod]    Build + deploy to a platform
   darkmown serve                            Preview the built dist locally
   darkmown version                          Print the installed Darkmown version
@@ -320,6 +348,22 @@ Authoring:
 `;
 }
 
+/**
+ * The one-line `build` summary: route count plus, when the feeds were emitted
+ * (home `site_url` set), the sitemap URL and RSS post counts — e.g.
+ * `Built 14 routes, sitemap (14 urls), rss (6 posts) into dist`. When no
+ * `site_url` is set the feed clauses are omitted (a hint was already warned).
+ * @param {{ routes: unknown[], feeds: { sitemap: number | null, rss: number | null } }} result
+ * @param {string} relativeRoot `dist` relative to cwd, for the message tail.
+ * @returns {string}
+ */
+export function buildSummary(result, relativeRoot) {
+  const parts = [`Built ${result.routes.length} routes`];
+  if (result.feeds.sitemap !== null) parts.push(`sitemap (${result.feeds.sitemap} urls)`);
+  if (result.feeds.rss !== null) parts.push(`rss (${result.feeds.rss} posts)`);
+  return `${parts.join(", ")} into ${relativeRoot}`;
+}
+
 /**
  * @param {string} relativeRoot
  * @returns {string}