@zvndev/darkmown 2.7.1-next.14.g3f67070 → 2.9.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, generated at build time.** With sharp installed (`npm i -D sharp`, an optional dependency; builds work without it), every raster photo in `site/pages` over 700px wide is resized to 640w and 1280w siblings in `dist/` (only widths below the intrinsic size, never upscaled, EXIF orientation applied), and the Markdown image gains a `srcset` with the original kept as `src`. Export `name@<width>.ext` yourself and your file wins that width verbatim, measured from its own header; generation fills only the widths you left uncovered, and other sizes are a hand export away (the compiler probes 64 through 3840). Skipped silently: small images, `@width` files, hidden or symlinked paths, svg/gif/avif, and shelf images (the generator covers page-colocated images only). Without sharp the build behaves as before plus one `npm i -D sharp` hint per build; a corrupt image or a sharp failure on one file is a hint naming the file, never a build failure. Resizes are cached in `node_modules/.cache/darkmown-images/` by content hash + width + format, so second builds and dev rebuilds do no resizing for unchanged images, and the build summary reports `image variants (N generated, M cached)` when variants materialized. `sizes` is never emitted (write raw `<img srcset sizes>` on an `html: true` page for that); bound (`![a]({ photo })`), remote, `data:`, query/hash, page-relative, and extensionless srcs are never wired, and neither are raw-HTML `<img>` tags. 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,
@@ -20,6 +21,7 @@ import {
 } from "./feeds.js";
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
 import { HIGHLIGHT_CSS } from "./highlight.js";
+import { generateImageVariants } from "./image-variants.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
 import { compileSkin, scopeIdFor } from "./skin.js";
 
@@ -104,6 +106,9 @@ export function buildSite(cwd = process.cwd(), options = {}) {
  * @property {RouteManifestEntry[]} routes
  * @property {string} distRoot
  * @property {{ sitemap: number | null, rss: number | null }} feeds
+ * @property {{ generated: number, cached: number, unavailable: boolean }} images
+ *   Responsive-variant pre-pass counts (2.9.0): freshly resized, cache-served,
+ *   and whether sharp could not be loaded at all.
  * @property {{ changed: string[], rebuilt: string[], total: number }} [incremental]
  */
 
@@ -118,6 +123,12 @@ function buildFull(cwd, paths, options) {
   fs.rmSync(paths.distRoot, { recursive: true, force: true });
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
+  // Responsive image variants (2.9.0): resize the large raster photos in
+  // site/pages into dist and collect the variant map BEFORE any route compiles,
+  // so the srcset wiring can reference what was generated. With the optional
+  // sharp dependency absent (or everything cache-served) this is cheap and
+  // never fails the build.
+  const images = generateImageVariants(paths, { quiet: options.quietFeedHints });
   const routes = discoverRoutes(paths.routesRoot, { includeDrafts: options.includeDrafts });
   // Build the collection index from the (post-draft-filter) routes — every
   // site/pages/<name>/ subdirectory's entries become queryable rows a bare-name
@@ -151,7 +162,17 @@ function buildFull(cwd, paths, options) {
   const mapRoutes = {};
 
   for (const route of routes) {
-    const built = buildRoute(route, cwd, paths, collections, feedLink, warned, identity, titles);
+    const built = buildRoute(
+      route,
+      cwd,
+      paths,
+      collections,
+      feedLink,
+      warned,
+      identity,
+      titles,
+      images.variants
+    );
     manifest.push(...built.mapEntry.pages);
     if (built.notFoundHtml !== undefined) notFoundHtml = built.notFoundHtml;
     for (const entry of built.mapEntry.pages) {
@@ -191,7 +212,12 @@ function buildFull(cwd, paths, options) {
 
   if (options.depMap) writeDepMap(paths, feedLink, siteInputs(identity, titles), mapRoutes);
 
-  return { routes: manifest, distRoot: paths.distRoot, feeds };
+  return {
+    routes: manifest,
+    distRoot: paths.distRoot,
+    feeds,
+    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable }
+  };
 }
 
 /**
@@ -283,13 +309,30 @@ function buildIncremental(cwd, paths, options, changed) {
     }
   }
 
+  // Rebuilt routes must compile byte-identically to a full rebuild, so the
+  // generated-variant map the srcset wiring consults is recomputed here too.
+  // An image CHANGE never reaches this point (no dependency graph tracks
+  // images, so it already forced a full rebuild above), which makes this scan
+  // all cache hits: it refreshes dist copies and the map, and spawns nothing.
+  const images = generateImageVariants(paths, { quiet: options.quietFeedHints });
+
   const byRoute = new Map(routes.map((route) => [route.route, route]));
   /** @type {Set<string>} */
   const warned = new Set();
   const rebuilt = [...affected].sort();
   for (const routePath of rebuilt) {
     const route = /** @type {Route} */ (byRoute.get(routePath));
-    const built = buildRoute(route, cwd, paths, collections, feedLink, warned, identity, titles);
+    const built = buildRoute(
+      route,
+      cwd,
+      paths,
+      collections,
+      feedLink,
+      warned,
+      identity,
+      titles,
+      images.variants
+    );
     // A shrunk pagination leaves stale `/page/N/` outputs behind — remove any
     // previously-emitted page this rebuild no longer produces.
     const kept = new Set(built.mapEntry.pages.map((entry) => entry.route));
@@ -325,6 +368,7 @@ function buildIncremental(cwd, paths, options, changed) {
     routes: manifest,
     distRoot: paths.distRoot,
     feeds,
+    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable },
     incremental: { changed, rebuilt, total: routes.length }
   };
 }
@@ -343,10 +387,30 @@ function buildIncremental(cwd, paths, options, changed) {
  * @param {SiteIdentity} identity Resolved site identity (its `siteUrl` is what
  *   makes a canonical URL possible).
  * @param {Map<string, string>} titles Route path → page title, for breadcrumbs.
+ * @param {Map<string, number[]>} imageVariants Generated responsive variants
+ *   (original's absolute source path → widths), threaded into each compile.
  * @returns {{ mapEntry: DepMapEntry, notFoundHtml: string | undefined }}
  */
-function buildRoute(route, cwd, paths, collections, feedLink, warned, identity, titles) {
-  const compiled = compileRoutePages(route, paths, collections, feedLink, identity, titles);
+function buildRoute(
+  route,
+  cwd,
+  paths,
+  collections,
+  feedLink,
+  warned,
+  identity,
+  titles,
+  imageVariants
+) {
+  const compiled = compileRoutePages(
+    route,
+    paths,
+    collections,
+    feedLink,
+    identity,
+    titles,
+    imageVariants
+  );
   /** @type {RouteManifestEntry[]} */
   const entries = [];
   /** @type {string | undefined} */
@@ -450,7 +514,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 {
@@ -691,9 +757,11 @@ function copyChangedAsset(file, cwd, paths) {
  * @param {{ href: string, title: string } | undefined} feedLink
  * @param {SiteIdentity} identity
  * @param {Map<string, string>} titles Route path → page title, for breadcrumbs.
+ * @param {Map<string, number[]>} imageVariants Generated responsive variants
+ *   (original's absolute source path → widths) for the srcset wiring.
  * @returns {{ pages: EmittedPage[], deps: Set<string>, collections: Set<string> }}
  */
-function compileRoutePages(route, paths, collections, feedLink, identity, titles) {
+function compileRoutePages(route, paths, collections, feedLink, identity, titles, imageVariants) {
   /** @type {Set<string>} */
   const deps = new Set();
   /** @type {Set<string>} */
@@ -718,7 +786,8 @@ function compileRoutePages(route, paths, collections, feedLink, identity, titles
     feed: feedLink,
     site: siteFor(route.route),
     collections,
-    vars: { page: pagerVars(route.route, 1, 1) }
+    vars: { page: pagerVars(route.route, 1, 1) },
+    imageVariants
   });
   track(first);
   if (!first.pagination || first.pagination.total <= 1) {
@@ -743,7 +812,8 @@ function compileRoutePages(route, paths, collections, feedLink, identity, titles
       feed: feedLink,
       site: siteFor(pageRoute(route.route, n)),
       collections,
-      vars: { page: pagerVars(route.route, n, total) }
+      vars: { page: pagerVars(route.route, n, total) },
+      imageVariants
     });
     track(page);
     pages.push({
@@ -898,8 +968,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).",