@zvndev/darkmown 2.7.1-next.14.g3f67070 → 2.8.0

package/site/pages/docs/index.wd

@@ -50,6 +50,7 @@ Darkmown is a Markdown-native framework for mostly-static sites with tiny reacti
 - [Interactions](#interactions--slider-sortable-carousel)
 - [Theme toggle — `:theme`](#theme-toggle--theme)
 - [Scoped styles — `scoped`](#scoped-styles--scoped)
+- [Skin at-rules](#skin-at-rules-font-face-and-keyframes)
 - [Inline attributes](#inline-attributes)
 - [Media directives](#media--video-audio-embed)
 - [Syntax highlighting](#syntax-highlighting)
@@ -301,6 +302,7 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 - Otherwise the text is left exactly as written — braces in prose never break a page or pull in the runtime.
 - Values resolve **inside a link or image destination** too, and every brace in the destination resolves, not just one filling the whole value: `[Docs](/docs/{ region }/)` works.
 - Values resolve in **raw HTML** as well (attributes and html blocks, HTML-escaped) on an `html: true` page, but those are painted once at build time rather than bound. Fenced code blocks and inline code spans are never rewritten, so a page can still show `` `[x](/p/{ p.slug }/)` `` as syntax.
+- `{ $build.year }`, `{ $build.date }`, and `{ $build.datetime }` fold the build's date at compile time, in prose, raw HTML, and link destinations. They always fold, so a page using only `$build` bindings stays zero-JS. An unknown `$build.*` name stays literal text, and `.md` files are never folded.
 
 ### Destinations that bind
 
@@ -333,6 +335,8 @@ The value being piped must be **in scope** — a loop variable, `:state`/`:store
 
 The whitelist: `money`, `number`, `percent`, `round`, `date` / `time` / `datetime` (Intl-backed; `short` / `medium` / `long`), `upper` / `lower` / `capitalize`, `truncate:n` / `trim`, `pluralize:"item"`, and `default:"—"`. The five aggregates double as list pipes — `{ cart | count }`, `{ cart | sum:"price" | money }`, plus `avg` / `min` / `max`. No custom functions, nothing `eval`'d; an unknown pipe is a compile error. There is deliberately no relative "time ago" formatter, so builds stay reproducible.
 
+Pipes also fold inside **raw HTML** on an `html: true` page: a static value (a collection row, a JSON row, `meta`) in an attribute or html block formats at build time, so a static loop with pipes in raw HTML stays zero-JS. A reactive value there can never fold (raw HTML is a one-time paint), so it is painted once with a build hint, instead of staying silently literal as before 2.8.
+
 ## Frontmatter
 
 Frontmatter sits between `---` fences. Values are strings, plus inline arrays:
@@ -348,6 +352,14 @@ tags: [sales, revenue, "q1, q2"]
 
 `lang:` sets the document language on `<html lang>` per page (`lang: fr`, `lang: pt-BR`, …); it defaults to `en`. Every page also ships a visually-hidden-until-focused **skip-to-content link** targeting the main landmark — your own `<main>` is reused (an existing `id` wins as the target; an id-less one gets `id="main"`), and a page without one is wrapped in `<main id="main">`. Restyle it via `.wd-skip-link` in a skin. All compile-time — static pages stay zero-JS.
 
+Three more keys arrived in 2.8:
+
+- **`icon: /path`** sets the favicon verbatim (`<link rel="icon">`, with a `type` for `.svg`/`.png`/`.ico`). Without it, the first of `site/pages/icon.svg`, `icon.png`, or `favicon.ico` wins; without either, the built-in mark stays the fallback.
+- **`noindex: true`** builds the page but removes it from discovery: a robots `noindex,nofollow` meta, plus exclusion from `sitemap.xml`, `rss.xml`, and the generated `llms.txt`/`llms-full.txt`. On a collection entry with a `_schema.wd`, declare it as `noindex: boolean?`.
+- **`skins: [/base.skin]`** (an inline array) loads shared `.skin` files for that page only, resolved like `@include` paths; a missing file, a non-`.skin` file, or a path outside `site/pages`/`site/_` is `[WD017]`. A shared skin whose first line is `scoped` scopes to the whole page body, so keep to one scoped skin per page.
+
+**Cascade order changed in 2.8.** Stylesheet links emit the highlight sheet first (code pages), then include skins, then `skins:` entries in listed order, and **the page's own colocated `.skin` last**, so the page wins ties at equal specificity. Before 2.8 the page's skin came first; a page rule that unknowingly relied on losing to an include rule now wins.
+
 ## SEO & feeds
 
 `darkmown build` writes `sitemap.xml`, `rss.xml`, and `robots.txt` — all build-time, zero client JS. There's no config file: the **home page** frontmatter carries the site's identity. Add `site_url` (absolute origin, no trailing slash) and the sitemap and feed switch on, prefixed with that origin and titled with the home `title`/`description`.
@@ -429,6 +441,8 @@ Add `transitions: true` to a page's frontmatter for **instant, flash-free naviga
 
 You don't size images by hand. Every `<img>` the compiler emits gets its intrinsic `width`/`height` read from the source file (so the page doesn't reflow as images decode), `decoding="async"`, and a priority split — the first image stays eager with `fetchpriority="high"`, the rest `loading="lazy"`. Anything you set yourself wins. The compiler measures, it doesn't resize, so keep source images web-sized.
 
+**Responsive variants.** Export pre-sized copies next to the source, same directory, same extension, `@<width>` before it (`dr-x@640.webp`, `dr-x@1280.webp`), and a Markdown image gains a `srcset` with the original kept as `src`. Descriptor widths are measured from the file headers (a `@640` file really holding 600px emits `600w`), candidates sort ascending, and the original joins at its intrinsic width. Discovery probes a fixed list of common widths (64 through 3840) rather than reading the directory, so an off-list width is a documented miss, never an error. `sizes` is never emitted; write raw `<img srcset sizes>` on an `html: true` page when you need one. Bound (`![a]({ photo })`), remote, `data:`, query/hash, page-relative, and extensionless srcs are never wired, and neither are raw-HTML `<img>` tags. Variant files are ordinary colocated assets: they copy to `dist/` and are never routes, and shelf images resolve variants against `/__wd/media/`. A `.md` page gets the hardening but no srcset.
+
 ## Static assets
 
 Non-page files live on the include shelf at `site/_/` and are copied into the build untouched:
@@ -820,10 +834,33 @@ compiles to `.card[data-wd-scope="wd-7c21"] { … }`, and the component's markup
 | A selector rule | Scoped — attribute on the subject, before any `:hover`/`::before` |
 | `tokens` / `tokens dark` | **Global** on `:root` — `$vars` and dark mode keep working site-wide |
 | `:global(.toast)` (whole selector) | Opts back out — plain unscoped `.toast { … }` |
+| `@font-face` / `@keyframes` | **Global**, never stamped, same contract as `tokens` |
 | `page` / `*` / `html` / `body` / `::selection` | Compile error — page-level styles belong in a global skin |
 
 Honest limits this release: only **whole-selector** `:global()` (no `.card :global(.x)` yet), and an **unused** scoped selector **warns but is not removed** (a colocated `.js` may add the class). See the side-by-side [Scoped demo](/scoped/).
 
+## Skin at-rules: `@font-face` and `@keyframes`
+
+Two CSS at-rules compile as self-contained blocks in a `.skin`, because their indented children are font descriptors and keyframe selectors rather than page selectors:
+
+```skin
+@font-face
+  font-family "Newsreader"
+  src url("/fonts/newsreader.woff2") format("woff2")
+  font-weight 200 800
+  font-display swap
+
+@keyframes fade-in
+  from
+    opacity 0
+  50%, 75%
+    opacity .5
+  to
+    opacity 1
+```
+
+`@font-face` takes plain declarations, several blocks per skin allowed. `@keyframes <name>` requires a plain identifier; each indented child is a keyframe selector (`from`, `to`, a percentage, or a comma list) with its declarations one level deeper, and anything else is a compile error, so a keyframe selector is never misread as a declaration. Aliases and `$token` refs work inside both, both can nest under an `@media` line (the home for `prefers-reduced-motion` animation guards), and both stay **global** in a `scoped` skin, same as `tokens` blocks.
+
 ## Inline attributes
 
 A trailing `{.class .class #id}` attaches classes or an id to the inline element directly before it, most often to style a link as a button without a wrapper:
@@ -834,6 +871,14 @@ A trailing `{.class .class #id}` attaches classes or an id to the inline element
 
 The block must follow the element with no space. It works on links, images, and emphasis, and it does **not** attach to inline code. It never collides with `{ name }` interpolation, because an interpolation always starts with a name, never a `.` or `#`. This page uses it: a link marked `{.no-prefetch}` is excluded from the `transitions: true` prerender hint.
 
+**Consecutive raw-HTML lines collapse into one paragraph.** On an `html: true` page, a run of lines that each start with an inline-level or unknown tag (`<a class="card">`, `<picture>`, a custom element) parses as ONE paragraph, so the elements render inline inside a single `<p>` instead of as layout siblings; a card grid collapses to one column this way. Lines starting with a block-level tag (`<div>`, `<section>`, …) never hit this, because CommonMark hoists them into an HTML block. The compiler warns once per run when 2+ consecutive lines of one paragraph each open with a component-looking tag (one carrying a `class` or `id`; classless prose links stay quiet):
+
+```
+site/pages/index.wd:6: 16 sibling HTML block lines will render inline in one <p>; wrap them in a container (e.g. a raw <div>)
+```
+
+The fix is the wrap: put the run inside a raw `<div class="grid">…</div>`. The hint stays silent inside a raw container, inside fenced code, on blank-line-separated lines, on `{ state }`-led lines, and on `.md` pages; a run inside a `:::` directive container DOES warn, because directive containers are not raw HTML.
+
 ## Media — `:video`, `:audio`, `:embed`
 
 Three compile-time-only directives (they emit no `data-wd-*`, so a media page stays zero-JS):
@@ -844,7 +889,7 @@ Three compile-time-only directives (they emit no `data-wd-*`, so a media page st
 :embed https://youtu.be/aqz-KE-bpKQ title="Big Buck Bunny"
 ```
 
-`:video`/`:audio` emit a hardened HTML5 player — `preload="metadata"` and `controls` by default, whitelisted flags (`autoplay` implies `muted`), and the `:fetch` URL scheme guard. `:embed` rewrites a YouTube/Vimeo link to its no-cookie/player form in a lazy, responsive `16/9` iframe. See the zero-JS [Media demo](/media/).
+`:video`/`:audio` emit a hardened HTML5 player with `preload="metadata"` and `controls` by default, whitelisted flags (`autoplay` implies `muted`), and the `:fetch` URL scheme guard. `:embed` rewrites a YouTube/Vimeo link to its no-cookie/player form in a lazy, responsive `16/9` iframe, and takes three sizing and permission attributes: `aspect=4:3` swaps the ratio box, `height=400px` pins the height instead (units `px`/`rem`/`em`/`vh`/`vw`/`%`, wins over `aspect=`), and `allow="payment"` replaces the default iframe permissions with tokens from a fixed whitelist (`payment`, `autoplay`, `encrypted-media`, `fullscreen`, `picture-in-picture`, `clipboard-write`, `camera`, `microphone`, `geolocation`). A bad token is `[WD706]`, a bad ratio or length `[WD707]`. See the zero-JS [Media demo](/media/).
 
 ## Syntax highlighting
 
@@ -955,7 +1000,8 @@ The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool
 - `darkmown init [dir] [--template <name>]` scaffolds a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`). It also writes agent context at the project root: `AGENTS.md` (the full directive reference, copied from the installed package so it can never teach syntax the compiler rejects), a `CLAUDE.md` pointing at it, and a `.gitignore`. Existing files are never overwritten.
 - `darkmown dev` — the live compiler: browser reload, an in-browser error overlay, incremental rebuilds, and a local runner for `api/*` functions.
 - `darkmown build [--target cloudflare] [--drafts]` — write 100% static output to `dist/` (plus `sitemap.xml` / `rss.xml` / `robots.txt`); `--drafts` includes `draft: true` pages for a staging deploy.
-- `darkmown serve` — preview the built `dist/` locally (static only; use `dev` to exercise `api/*`).
+- `darkmown validate [path]` — compile-check every route under `site/pages/` (drafts included), or one file or directory, without writing `dist/`. Each page reports `compiles.` with its static/reactive status, warnings as bullets, or the coded `WD` error with file, line, and fix hint; the exit code is 1 when any page fails, so it gates CI.
+- `darkmown serve`: preview the built `dist/` locally. It runs the project's `api/*` functions with the same contract as dev and the production hosts (so `:form` posts and `:fetch` demos against `/api/…` work in the preview), and it compresses text responses, brotli preferred then gzip, negotiated off `Accept-Encoding` with `Vary: Accept-Encoding` set.
 - `darkmown catalog [--llms|--llms-full]`: print the `.wd` directive catalog as JSON, a compact cheatsheet for priming an AI model, or the complete reference including every error code (see [AI authoring](#ai-authoring)).
 - `darkmown deploy <vercel|cloudflare> [--prod]` — build (target-aware) and deploy through the platform CLI, printing your URL; an unauthenticated CLI surfaces the login to run first.
 - `darkmown version` / `darkmown help` — print the installed version, or the full command summary and directive syntax.

package/site/pages/index.js

@@ -6,6 +6,21 @@
 // stays free of raw HTML. The copy button is added here instead: progressive
 // enhancement, so the command is still readable and selectable with JS off.
 
+// Little Friend click ids for the calls to action. Markdown links take no
+// data attributes, so they are stamped here.
+const ctaIds = [
+  ["/docs/", "cta.docs"],
+  ["/playground/", "cta.playground"],
+  ["/vs/markdoc/", "cta.compare"],
+  ["https://github.com/", "cta.github"],
+  ["https://vercel.com/new/", "cta.deploy_vercel"]
+];
+for (const link of document.querySelectorAll(".hero-cta a")) {
+  const href = link.getAttribute("href") || "";
+  const match = ctaIds.find(([prefix]) => href.startsWith(prefix));
+  if (match) link.dataset.lf = match[1];
+}
+
 const installBlock = document.querySelector(".hero pre > code");
 
 if (installBlock && navigator.clipboard) {
@@ -21,6 +36,8 @@ if (installBlock && navigator.clipboard) {
   button.addEventListener("click", async () => {
     try {
       await navigator.clipboard.writeText(installBlock.textContent.trim());
+      // Little Friend is loaded on production builds only.
+      if (typeof window.lf === "function") window.lf("track", "install.copy");
       button.textContent = "Copied";
       button.classList.add("is-copied");
       setTimeout(() => {

package/src/api-runner.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { appendVary, compressBody, isCompressibleType, negotiateEncoding } from "./statics.js";
 
 /**
  * The local-dev serverless API runner. Gives `darkmown dev` the SAME `/api/*`
@@ -140,11 +141,19 @@ function readBody(req) {
 
 /**
  * Write a Web-standard `Response` back onto a Node `ServerResponse`.
+ *
+ * `acceptEncoding` is the request's Accept-Encoding header when the caller
+ * negotiates compression (the preview server); a JSON/text/svg body is then
+ * sent brotli- or gzip-compressed with `Content-Encoding` + `Vary`. When it
+ * is omitted (the dev server) the response is written exactly as before — no
+ * re-encoding, no extra headers. A handler that already set Content-Encoding
+ * is never double-compressed.
  * @param {Response} response
  * @param {import("node:http").ServerResponse} res
+ * @param {string | string[] | undefined} [acceptEncoding]
  * @returns {Promise<void>}
  */
-export async function writeWebResponse(response, res) {
+export async function writeWebResponse(response, res, acceptEncoding) {
   /** @type {Record<string, string | string[]>} */
   const headers = {};
   // `Headers.forEach` folds multiple Set-Cookie into one comma-joined value, which
@@ -158,8 +167,19 @@ export async function writeWebResponse(response, res) {
   const cookies =
     typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [];
   if (cookies.length > 0) headers["set-cookie"] = cookies;
+  let buffer = /** @type {Buffer} */ (Buffer.from(await response.arrayBuffer()));
+  const encoding = negotiateEncoding(acceptEncoding);
+  if (encoding && isCompressibleType(String(headers["content-type"] || ""))) {
+    if (!headers["content-encoding"]) {
+      headers["content-encoding"] = encoding;
+      headers.vary = appendVary(
+        /** @type {string | undefined} */ (headers.vary),
+        "Accept-Encoding"
+      );
+      buffer = compressBody(buffer, encoding);
+    }
+  }
   res.writeHead(response.status, headers);
-  const buffer = Buffer.from(await response.arrayBuffer());
   res.end(buffer);
 }
 
@@ -173,9 +193,11 @@ export async function writeWebResponse(response, res) {
  * @param {string} io.apiDir Absolute path to the project's `api/` directory.
  * @param {import("node:http").IncomingMessage} io.req
  * @param {import("node:http").ServerResponse} io.res
+ * @param {string | string[] | undefined} [io.acceptEncoding] The request's
+ *   Accept-Encoding header, when the caller negotiates compression (preview).
  * @returns {Promise<boolean>}
  */
-export async function handleApiRequest({ apiDir, req, res }) {
+export async function handleApiRequest({ apiDir, req, res, acceptEncoding }) {
   const pathname = new URL(req.url || "/", "http://localhost").pathname;
   const match = matchApiRoute(discoverApiRoutes(apiDir), pathname);
   if (!match) return false;
@@ -191,11 +213,10 @@ export async function handleApiRequest({ apiDir, req, res }) {
           "Use: return Response.json({ ... })"
       );
     }
-    await writeWebResponse(response, res);
+    await writeWebResponse(response, res, acceptEncoding);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    res.writeHead(500, { "content-type": "application/json" });
-    res.end(JSON.stringify({ ok: false, error: message }));
+    await writeWebResponse(Response.json({ ok: false, error: message }, { status: 500 }), res);
   }
   return true;
 }

package/src/builder.js

@@ -11,6 +11,7 @@ import {
   aiCrawlerPolicy,
   buildRobots,
   buildRss,
+  isNoindex,
   lastmodFor,
   rfc822,
   rssDescription,
@@ -450,7 +451,9 @@ function breadcrumbTrail(routePath, titles, siteUrl) {
  */
 function siteCorpus(routes, identity) {
   const pages = routes
-    .filter((route) => route.route !== "/404/")
+    // `/404/` is not content, and a `noindex: true` page opted out of being
+    // enumerated anywhere — feeds, sitemap, and this corpus alike.
+    .filter((route) => route.route !== "/404/" && !isNoindex(route.meta))
     .map((route) => {
       const { body } = parseFrontmatter(fs.readFileSync(route.file, "utf8"), route.file);
       return {
@@ -898,8 +901,10 @@ function emitFeeds(routes, identity, paths, quietHints = false) {
   }
 
   // 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/");
+  // not a post — and a `noindex: true` route has opted out of both, exactly as
+  // it opted out of the index with its robots meta. Filter once; both feeds
+  // work off the result.
+  const feedable = routes.filter((route) => route.route !== "/404/" && !isNoindex(route.meta));
 
   // Sitemap: one <url> per emitted route (404 excluded above). A frontmatter
   // `date:` wins, but only when it IS a date — an unparseable one warns and

package/src/catalog.js

@@ -296,8 +296,9 @@ const DIRECTIVES = [
   {
     name: ":embed",
     kind: "line",
-    syntax: ':embed <url> [title="…"]',
-    description: "A lazy, privacy-friendly YouTube/Vimeo/iframe embed.",
+    syntax: ':embed <url> [title="…"] [aspect=<w>:<h>] [height=<length>] [allow="token …"]',
+    description:
+      "A lazy, privacy-friendly YouTube/Vimeo/iframe embed. aspect= swaps the 16:9 ratio box, height= pins the frame, allow= replaces the permission set (whitelisted tokens).",
     example: EMBED_EXAMPLE,
     reactive: "static"
   },
@@ -598,6 +599,24 @@ const FRONTMATTER_KEYS = [
     description: "Excluded from builds and feeds until published.",
     example: "draft: true"
   },
+  {
+    name: "noindex",
+    description:
+      "Keep the page out of discovery surfaces: robots noindex meta, sitemap.xml, rss.xml, llms.txt.",
+    example: "noindex: true"
+  },
+  {
+    name: "icon",
+    description:
+      "Favicon path or URL. Overrides the site/pages/icon.svg|png|favicon.ico convention and the built-in mark.",
+    example: "icon: /icon.svg"
+  },
+  {
+    name: "skins",
+    description:
+      "Shared .skin files to load for this page, before its colocated skin (inline array).",
+    example: "skins: [/base.skin]"
+  },
   {
     name: "html",
     description: "Allow raw HTML in the markdown body (default false).",

package/src/cli.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "node:url";
 import { handleApiRequest } from "./api-runner.js";
 import { buildSite } from "./builder.js";
 import { directiveCatalog, llmsFullText, llmsText } from "./catalog.js";
+import { buildCollections } from "./compiler/collections.js";
 import { createPaths } from "./config.js";
 import { DEPLOY_TARGETS, deploy } from "./deploy.js";
 import {
@@ -20,6 +21,7 @@ import {
 import { discoverRoutes, isDraft, outputPathForRoute } from "./router.js";
 import { availableTemplates, initProject } from "./scaffold.js";
 import { contentType, isServableFile, pipeFile, resolvePublicFile, serve } from "./statics.js";
+import { validate as validateSource } from "./tools/validate.js";
 
 const cliPath = fileURLToPath(import.meta.url);
 
@@ -103,6 +105,10 @@ export async function run(argv, env = {}) {
       log("Emitted dist/_worker.js for Cloudflare Pages api/* functions");
     return { command: "build" };
   }
+  if (command === "validate") {
+    const target = argv.slice(1).find((arg) => !arg.startsWith("-"));
+    return runValidate({ cwd, target, log, error });
+  }
   if (command === "dev") {
     return startDevServer({ cwd, log, warn, error });
   }
@@ -142,6 +148,159 @@ export class CliError extends Error {
   }
 }
 
+/**
+ * File extensions the compiler can read as TEXT during a page compile: page and
+ * include sources, colocated `.skin`/`.js` siblings, and `@loop` JSON data.
+ * Everything else under `site/` (images, fonts) is either binary or never read
+ * by the compiler, so the in-memory copy `validate` runs against skips it.
+ * @type {Set<string>}
+ */
+const VALIDATE_SOURCE_EXTENSIONS = new Set([".md", ".wd", ".skin", ".js", ".json"]);
+
+/**
+ * `darkmown validate [path]`: compile-check pages without writing `dist`.
+ *
+ * Every check goes through the SAME validator the agent tools surface exposes
+ * (`src/tools/validate.js`), against an in-memory copy of `site/` — so this
+ * command and a tool-loop `validate` call can never disagree about what
+ * compiles, and the headline vocabulary (`compiles. …`, `compiles with N
+ * warnings. …` plus a bullet per warning) is shared byte-for-byte. Collections
+ * are resolved project-wide (validating `_schema.wd` entries first), exactly as
+ * the build resolves them, so a `@loop blog into post` page checks clean.
+ *
+ * Drafts are included: `darkmown dev` serves them, so a broken draft is a
+ * broken project even though a production build skips it. Throws `CliError`
+ * (exit 1) when any page fails.
+ * @param {{ cwd: string, target: string | undefined, log: typeof console.log, error: typeof console.error }} io
+ * @returns {{ command: "validate" }}
+ */
+function runValidate({ cwd, target, log, error }) {
+  const paths = createPaths(cwd);
+  if (!fs.existsSync(paths.routesRoot)) {
+    error("No site/pages directory found. Run `darkmown init` to scaffold a project first.");
+    throw new CliError("No site/pages directory found.", { silent: true });
+  }
+  const files = slurpSiteSources(cwd);
+  const routes = discoverRoutes(paths.routesRoot, { includeDrafts: true });
+  let collections;
+  try {
+    collections = buildCollections(routes, paths);
+  } catch (err) {
+    // A `_schema.wd` violation is a project-level failure, not one page's: the
+    // message already carries the entry file, line, and corrective hint.
+    error(`✗ ${err instanceof Error ? err.message : String(err)}`);
+    throw new CliError("Collection validation failed.", { silent: true });
+  }
+
+  const entries = validateEntries({ cwd, target, routes, files, error });
+  let failures = 0;
+  let warnings = 0;
+  for (const entry of entries) {
+    // The pager vars mirror the build's discovery compile (page 1 of 1, no
+    // prev/next), so a paginated listing's `:if page.prev` / `{ page.next }`
+    // resolve exactly the way its first compile resolves them.
+    const result = validateSource(files, entry, {
+      collections,
+      vars: { page: { current: 1, total: 1, prev: "", next: "" } }
+    });
+    const [headline, ...rest] = result.text.split("\n");
+    if (result.ok) {
+      warnings += rest.length;
+      log(`✓ ${entry} — ${headline}`);
+      for (const line of rest) log(`  ${line}`);
+    } else {
+      failures++;
+      error(`✗ ${entry} — ${headline}`);
+      for (const line of rest) error(`  ${line}`);
+    }
+  }
+  if (failures > 0) {
+    error(`✗ ${failures} of ${entries.length} ${plural(entries.length, "page")} failed validation`);
+    throw new CliError("Validation failed.", { silent: true });
+  }
+  log(
+    `✓ ${entries.length} ${plural(entries.length, "page")} validated` +
+      (warnings ? `, ${warnings} ${plural(warnings, "warning")}` : "")
+  );
+  return { command: "validate" };
+}
+
+/**
+ * Which pages `validate` checks, as project-relative POSIX keys into the
+ * in-memory source map: every route for no argument, the routes under a
+ * directory argument, or the one file for a file argument (which may be a shelf
+ * include — anything under `site/` the compiler can read).
+ * @param {{ cwd: string, target: string | undefined, routes: import("./router.js").Route[], files: Record<string, string>, error: typeof console.error }} io
+ * @returns {string[]}
+ */
+function validateEntries({ cwd, target, routes, files, error }) {
+  const keyOf = (/** @type {string} */ abs) => path.relative(cwd, abs).split(path.sep).join("/");
+  if (!target) return routes.map((route) => keyOf(route.file));
+
+  const abs = path.resolve(cwd, target);
+  if (!fs.existsSync(abs)) {
+    error(`Nothing to validate at "${target}": no such file or directory.`);
+    throw new CliError(`No such file or directory: ${target}`, { silent: true });
+  }
+  if (fs.statSync(abs).isDirectory()) {
+    const prefix = `${abs}${path.sep}`;
+    const entries = routes
+      .filter((route) => route.file.startsWith(prefix))
+      .map((route) => keyOf(route.file));
+    if (entries.length === 0) {
+      error(`No pages found under "${target}".`);
+      throw new CliError(`No pages found under ${target}`, { silent: true });
+    }
+    return entries;
+  }
+  const ext = path.extname(abs);
+  if (ext !== ".md" && ext !== ".wd") {
+    error(`Cannot validate "${target}": only .md and .wd sources compile.`);
+    throw new CliError(`Not a page source: ${target}`, { silent: true });
+  }
+  const key = keyOf(abs);
+  if (!(key in files)) {
+    error(`Cannot validate "${target}": validate checks pages and includes under site/.`);
+    throw new CliError(`Outside site/: ${target}`, { silent: true });
+  }
+  return [key];
+}
+
+/**
+ * Read every compiler-readable text source under `site/` into the
+ * project-relative key → contents map `compileFromMemory` compiles against.
+ * @param {string} cwd Project working directory.
+ * @returns {Record<string, string>}
+ */
+function slurpSiteSources(cwd) {
+  /** @type {Record<string, string>} */
+  const files = {};
+  /** @param {string} dir */
+  const walk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(abs);
+        continue;
+      }
+      if (!VALIDATE_SOURCE_EXTENSIONS.has(path.extname(entry.name))) continue;
+      files[path.relative(cwd, abs).split(path.sep).join("/")] = fs.readFileSync(abs, "utf8");
+    }
+  };
+  const siteRoot = path.join(cwd, "site");
+  if (fs.existsSync(siteRoot)) walk(siteRoot);
+  return files;
+}
+
+/**
+ * @param {number} n
+ * @param {string} word
+ * @returns {string}
+ */
+function plural(n, word) {
+  return n === 1 ? word : `${word}s`;
+}
+
 /**
  * Start the live-compiler dev server. Builds once (recording, not crashing on, a
  * broken initial build), watches `site/` and `src/`, and serves dist with the
@@ -293,6 +452,12 @@ function startDevServer({ cwd, log, warn, error }) {
 /**
  * Start the static preview server for an existing `dist/`. Throws `CliError`
  * when there is nothing built to serve.
+ *
+ * Preview mirrors production more closely than dev in two ways: project
+ * `api/*.js` functions run on `/api/*` (same runner and `(request) => Response`
+ * contract as dev — a project without `api/` falls straight through to static),
+ * and compressible responses are brotli/gzip-negotiated off Accept-Encoding so
+ * local weight checks see transfer sizes, not raw bytes.
  * @param {{ cwd: string, log: typeof console.log, error: typeof console.error }} io
  * @returns {Promise<{ command: "serve", server: import("node:http").Server, close: () => Promise<void> }>}
  */
@@ -304,7 +469,21 @@ function startPreviewServer({ cwd, log, error }) {
     error("No dist directory found. Run `darkmown build` first.");
     throw new CliError("No dist directory found. Run `darkmown build` first.", { silent: true });
   }
-  const server = http.createServer((req, res) => serve(distRoot, req.url || "/", res));
+  const apiDir = path.join(cwd, "api");
+  const server = http.createServer((req, res) => {
+    const acceptEncoding = req.headers["accept-encoding"];
+    // Serverless parity, exactly as in dev: run a project api/*.js function when
+    // the path matches; otherwise serve static (compressed when negotiated). A
+    // throw on either path (e.g. a malformed dynamic segment) becomes a clean 500.
+    handleApiRequest({ apiDir, req, res, acceptEncoding })
+      .then((handled) => {
+        if (!handled) serve(distRoot, req.url || "/", res, { acceptEncoding });
+      })
+      .catch((err) => {
+        res.writeHead(500, { "content-type": "text/plain" });
+        res.end((err instanceof Error && err.stack) || String(err));
+      });
+  });
   return new Promise((resolve) => {
     server.listen(port, host, () => {
       log(`Darkmown preview of dist at http://${host}:${port}`);
@@ -398,6 +577,7 @@ Usage:
   darkmown dev                              Start the live compiler dev server
   darkmown build [--target cloudflare]      Compile site/pages into dist
             [--drafts]                      Include draft: true pages (staging)
+  darkmown validate [path]                  Compile-check pages without building (exit 1 on errors)
   darkmown deploy <${DEPLOY_TARGETS.join("|")}> [--prod]    Build + deploy to a platform
   darkmown serve                            Preview the built dist locally
   darkmown catalog [--llms|--llms-full]     Print the .wd directive catalog (JSON, --llms cheatsheet, or --llms-full reference)

package/src/compiler/body.js

@@ -88,6 +88,13 @@ export function compileBody(lines, ctx) {
   // reports the offending line and not the top of the file.
   let proseStart = 0;
   let fence = null;
+  // Raw <style>/<script> block tracking (pages with `html: true`). Inside one,
+  // lines are CSS/JS, not directive territory, so the "looks like a directive"
+  // hint is suppressed — otherwise every `@font-face {` / `@keyframes x {` in
+  // an author's raw <style> warns once per page. Line-based like the fence
+  // tracking above; a `</style>` inside a CSS string is out of scope.
+  /** @type {"style" | "script" | null} */
+  let rawTag = null;
 
   // Append one chunk, splicing it into the previous one when the seam between
   // them is a table split in half. Markdown only sees a table when a header row
@@ -127,6 +134,20 @@ export function compileBody(lines, ctx) {
       continue;
     }
 
+    // Update the raw-block state BEFORE the line is classified, so both the
+    // opener's contents and the closing tag line itself count as "inside".
+    // A same-line `<script src="…"></script>` opens and closes at once and
+    // never suppresses anything.
+    const inRawBlock = rawTag !== null;
+    if (rawTag) {
+      if (RAW_BLOCK_CLOSE.test(line)) rawTag = null;
+    } else {
+      const rawOpen = line.match(RAW_BLOCK_OPEN);
+      if (rawOpen && !RAW_BLOCK_CLOSE.test(line)) {
+        rawTag = /** @type {"style" | "script"} */ (rawOpen[1].toLowerCase());
+      }
+    }
+
     // A directive name ALONE on a line is a mistake with one obvious fix: it is
     // missing its arguments. Every dispatcher below requires a space after the
     // keyword, so such a line used to fall through to prose — and because
@@ -331,7 +352,7 @@ export function compileBody(lines, ctx) {
         file: ctx.file
       });
     }
-    warnUnknownDirective(line, ctx);
+    if (!inRawBlock) warnUnknownDirective(line, ctx);
     prose.push(line);
   }
 
@@ -351,6 +372,14 @@ export function compileBody(lines, ctx) {
 // from the demo handler and are gone from here for exactly that reason.)
 const KNOWN_DIRECTIVE =
   /^(?:(?:@(?:include|loop|empty|endloop)|:(?:state|store|fetch|computed|effect|every|theme|video|audio|embed|form|endform|input|textarea|select|checkbox|radio|bind|slider|submit|button|carousel|endcarousel|if|endif|else))(?:\s|$)|:try\s)/;
+
+// Raw HTML blocks whose contents are CSS/JS, never directive territory. The
+// lookalike hint is suppressed between `<style …>`/`<script …>` and their
+// close tag (line-based, matching the rest of this dispatcher). The close is
+// deliberately tag-agnostic: `<style>` and `<script>` never nest, so either
+// closer ends the open block.
+const RAW_BLOCK_OPEN = /<(style|script)(?=[\s>])/i;
+const RAW_BLOCK_CLOSE = /<\/(?:style|script)\s*>/i;
 /**
  * @param {string} line
  * @param {Ctx} ctx