@zvndev/darkmown 1.2.0 → 1.3.0

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";
 
 /**
  * @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);
@@ -66,6 +94,7 @@ export function buildSite(cwd = process.cwd(), options = {}) {
     emitAssets(page.assets, paths);
     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 };
 }
 
 /**
@@ -387,6 +527,22 @@ 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);
+}
+
 /**
  * @param {Assets} assets
  * @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}

package/src/compiler/context.js

@@ -32,6 +32,9 @@
  * @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.
  */
 
 /**
@@ -140,7 +143,8 @@ export function createCompilation() {
       scripts: new Set(),
       files: new Map(),
       runtime: false,
-      behaviors: new Set()
+      behaviors: new Set(),
+      hasCode: false
     },
     state: new Map(),
     stores: new Set(),

package/src/compiler/index.js

@@ -6,6 +6,7 @@
 //   frontmatter.js    `---` block → meta + body, inline scalar/array parsing
 //   includes.js       @include / @loop-data resolution, colocated assets, .md hints
 //   predicates.js     where / when / :if / :computed expression compilers
+//   format.js         { value | pipe } format pipes + list aggregates (value layer)
 //   markdown.js       markdown-it instances + plugins + prose interpolation
 //   loops.js          @loop pipeline + row-template initial-paint fill
 //   directives.js     the handle* family + :button action parser + demo directives

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,6 +8,7 @@
 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";
@@ -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.
@@ -126,7 +142,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>
@@ -253,7 +269,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 +287,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/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));
+`;
 }
 
 /**