@zvndev/darkmown 2.8.0 → 2.10.0

package/site/pages/benchmarks/index.wd

@@ -0,0 +1,126 @@
+---
+title: Benchmarks: a production Next.js site, rebuilt in Markdown
+description: We rebuilt a live production marketing site (Next.js 16, React 19, Tailwind, Vercel) in Darkmown and measured both sides. Same copy, same images, same CMS. A tenth of the JavaScript, a third of the requests, and the two places the rebuild lost, stated plainly.
+image: https://darkmown.com/__wd/media/og.png
+site_url: https://darkmown.com
+transitions: true
+schema: TechArticle
+---
+
+@include /nav.wd
+@include /base.wd
+
+::: main
+
+::: eyebrow
+Benchmarks
+:::
+
+# Same site. Same copy. A tenth of the JavaScript.
+
+We took a live production marketing site, a multi-location dental practice running **Next.js 16, React 19, and Tailwind on Vercel**, and rebuilt it in Darkmown: same copy, same images, same fonts, same CMS content pipeline. Then we measured both. This page is every number we found, including the two categories where the rebuild is worse.
+
+The rebuild lives in a private demo repository, so there is no source link; every figure below is the median of three measured page loads, and the [methodology](#methodology) section says exactly how we measured.
+
+## The headline numbers
+
+::: stats
+
+::: stat
+10x
+::: statlabel
+less JavaScript on the homepage: 22 KB against 225 KB, raw bytes against compressed. Gzip to gzip it is 28x.
+:::
+:::
+
+::: stat
+3.3x
+::: statlabel
+fewer requests per page: 11 to 20 across the four measured routes, against 46 to 70.
+:::
+:::
+
+::: stat
+5.6x
+::: statlabel
+smaller HTML document: 56.7 KB raw against 318 KB. Compressed both ways, still 2.4x leaner.
+:::
+:::
+
+::: stat
+~6x
+::: statlabel
+faster full builds: 2.7 to 3.6 seconds for 67 routes, against 16.6 s cold and 23.2 s warm.
+:::
+:::
+
+:::
+
+## What every page pays
+
+| | Next.js on Vercel | Darkmown rebuild |
+|---|---|---|
+| JavaScript per page | 225 to 227 KB compressed, 16 chunks | 18 to 23 KB total (the whole runtime is 6.6 KB gzipped) |
+| Requests per page | 46 to 70 | 11 to 20 |
+| Homepage HTML document | 318 KB raw, 24.9 KB brotli | 56.7 KB raw, 10.6 KB gzip |
+| Third-party JavaScript | ~357 KB (Google Tag Manager, DoubleClick) | 0 B |
+
+Two things worth saying out loud. The live site sends the **same 16 chunks, byte-identical, on all four measured routes**: whatever route-level code splitting Next.js is doing never showed up, so every page pays the full 226 KB. And the Darkmown column is raw bytes off an uncompressed preview server while the Next.js column is compressed transfer, so the real gap is wider than the table shows.
+
+## Route by route
+
+::: tablewrap
+
+| Route | JS: Next.js | JS: Darkmown | Requests: Next.js | Requests: Darkmown | Total wire: Next.js | Total wire: Darkmown |
+|---|---|---|---|---|---|---|
+| `/` | 225 KB | 22 KB | 50 | 15 | 2.16 MB | 1.79 MB |
+| `/services/dental-implants/` | 226 KB | 18 KB | 54 | 12 | 828 KB | 793 KB |
+| `/doctors/` | 227 KB | 18 KB | 70 | 20 | 965 KB | **1.69 MB** |
+| `/request-appointment/` | 226 KB | 23 KB | 46 | 11 | 784 KB | 678 KB |
+
+:::
+
+The doctors route is the one page where the rebuild's total wire bytes are **higher**, and it is not a rounding error: the rebuild shipped unoptimized headshots where the live site serves CDN width variants. That is the next section.
+
+## Build time and source size
+
+Measured on the same machine, 67 routes on both sides:
+
+| | Next.js 16 | Darkmown |
+|---|---|---|
+| Cold build | 16.6 s | 2.7 to 3.6 s |
+| Warm build | 23.2 s | 2.7 to 3.6 s (there is no build cache) |
+| CPU time per build | ~30 s | ~0.6 s |
+
+| | Next.js project | Darkmown rebuild |
+|---|---|---|
+| Maintained source | ~33,000 lines (24.5k code + 8.4k CMS JSON) | 17,300 lines total |
+| Project on disk | 39 MB | 5.5 MB |
+| `node_modules` | 932 MB | 15 MB (62x smaller) |
+
+## Where Darkmown loses
+
+Both of these were real losses on measured bytes, not hypotheticals, and both shaped what shipped next.
+
+- **Fonts, badly.** The rebuild served three raw variable TTFs: 1.07 MB on the homepage, against `next/font`'s 158 KB of subset woff2. Fonts were the single largest byte category on every rebuilt page. The 2.8 documentation now ships a font recipe (convert to woff2, subset to the glyphs used, `font-display swap`, preload the critical face), and build-time subsetting is on the roadmap.
+- **Photos.** The doctors page shipped 1,045 KB of headshots against the live site's 147 KB of CDN width variants. Darkmown 2.8 added the `@width` convention (drop in `photo@640.jpg` and the build wires the `srcset`), and 2.9 generates those variants at build time when sharp is installed. Run the same rebuild today and this category flips.
+- **A shared cost neither side avoids:** both sites load the same ~594 KB hero video on the homepage. No edge for anyone there.
+
+## Methodology
+
+- Measured on 2026-10-13 with Chromium via Playwright: 1280x900 desktop viewport, cache disabled, three fresh loads per URL, median reported. Wire bytes are CDP `encodedDataLength`, which is compressed transfer size plus response headers.
+- The live site runs on Vercel's edge network; the rebuild was measured from a local static build (`darkmown serve`). Local timings reflect zero network latency, so **we do not compare timing columns at all**. Bytes and request counts are the fair comparison.
+- The preview server did not compress responses in this run, so the rebuild's text wire bytes overstate what the same `dist/` transfers behind a compressing host: its homepage HTML is 57.4 KB on the wire but 10.6 KB gzipped, and any Vercel or Cloudflare deploy of the same output gets brotli and edge caching for free.
+- Four routes measured out of 67. The content pipeline is identical on both sides: the same Capa CMS snapshot drives both sites, and the Darkmown sync regenerates its 41 managed pages byte-identically in 0.05 s.
+- **What Next.js does that Darkmown does not:** server rendering, streaming, per-request personalization, edge caching, an image CDN, and automatic font subsetting. This site exercises none of the dynamic ones; its pages are the same for every visitor, which is exactly the case a static build exists for. Where Next.js's automatic asset optimization (fonts, responsive images) would win, it did win, and that is the section above.
+- Whether a production dental site keeps Google Tag Manager is a business decision, not a framework property. The rebuild demonstrates the site works without it, and the ~357 KB saving is stated as such.
+
+::: bench-cta
+[Read the docs](/docs/){.btn .primary}
+[Try Darkmown in your browser](/playground/){.btn}
+[Darkmown vs. Markdoc](/vs/markdoc/){.btn}
+:::
+
+:::
+
+@include /footer.wd

package/site/pages/docs/index.wd

@@ -60,6 +60,7 @@ Darkmown is a Markdown-native framework for mostly-static sites with tiny reacti
 - [Compile error codes](#compile-error-codes)
 - [CLI reference](#cli-reference)
 - [Editor support](#editor-support)
+- [Benchmarks](#benchmarks)
 - [Accessibility](#accessibility)
 - [Security](#security)
 - [Limits](#limits)
@@ -116,6 +117,44 @@ A directive is a whole line, written flush against the left margin. Four rules c
 - `with title={ feature.title }` passes a value already in scope — including whole objects.
 - Includes inside a loop inherit the loop value automatically.
 
+An include declares fallbacks for its `with` arguments in its own frontmatter with `defaults: [title="Untitled", cta="Learn more"]`. The caller's `with` value always wins; the default fills in when the caller is silent; an argument with neither renders as literal `{ title }` text, as before. Values are strings (frontmatter is string-typed), entries split on top-level commas only (so `cta="Learn more, today"` works), and a malformed `defaults:` is `[WD613]`.
+
+The block form turns an include into a wrapper component. The lines between the call and `@endinclude` compile once in the **caller's** scope (its `:state`, and the loop item inside a `@loop`) and land wherever the include puts a standalone `{ children }` line:
+
+```wd
+@include /card.wd with title="Pricing"
+
+Everything in **this paragraph** is the card body.
+
+@endinclude
+```
+
+with `site/_/card.wd`:
+
+```wd
+---
+defaults: [title="Untitled"]
+---
+
+::: card
+## { title }
+
+{ children }
+:::
+```
+
+The slot is a standalone line only (mid-paragraph or fenced `{ children }` stays literal; on a top-level page it is literal too; a `.md` include cannot host one). Called without a block, the slot renders empty; a block given to an include that never uses `{ children }` is dropped with a build warning. `@endinclude` closes the nearest preceding unpaired `@include`, so an inline `@include` written between opener and closer consumes the pairing; one level of block nesting is supported (deeper is `[WD616]`), and a stray closer is `[WD614]`. There is deliberately no unclosed-block error: an unpaired opener is the inline form, and the inline form must stay legal. Per-row components in a loop are the payoff, and stay zero-JS over a static source:
+
+```wd
+@loop /products.json into product
+@include /card.wd with title={ product.name }
+
+Price: { product.price | money }
+
+@endinclude
+@endloop
+```
+
 ## Loops
 
 `@loop <things> into <thing>` is the only loop. The body is normal Markdown (or more directives) and repeats once per row:
@@ -441,7 +480,7 @@ 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.
+**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
 
@@ -861,6 +900,8 @@ Two CSS at-rules compile as self-contained blocks in a `.skin`, because their in
 
 `@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.
 
+**Build-time font subsetting.** With the wasm toolchain installed (`npm i -D harfbuzzjs wawoff2`, both optional dependencies), a post-pass subsets every project-local `.ttf`/`.otf`/`.woff` referenced by an `@font-face src url(...)` to the site's character set (every code point in the emitted HTML, plus a base set of ASCII, Latin-1, punctuation, arrows, and ★ ☆ ✓ ✕ ✗), encodes it as woff2, emits `<name>-subset.woff2` beside the original, and rewrites the dist CSS so `src:` lists the subset first; the source `.skin` is never touched, and layout features and variable axes survive. Without the toolchain the build is unchanged plus one hint per build, a font that fails to parse ships as-is with its own hint, and the build never fails over a font. Subsets cache in `node_modules/.cache/darkmown-fonts/` keyed by font and charset hashes, and the CSS rewrite is idempotent, so incremental dev builds are safe. The build summary reports `fonts (3 subsetted, 0 cached)` when the post-pass did work.
+
 ## 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:
@@ -1010,6 +1051,10 @@ The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool
 
 A [VS Code extension](https://github.com/ZVN-DEV/darkmown/tree/master/editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding, so a `.wd` file reads as Markdown-plus-directives instead of broken Markdown. Build a `.vsix` from the framework repo and install it with `code --install-extension`; a Marketplace listing is pending.
 
+## Benchmarks
+
+A live production marketing site (Next.js 16, React 19, Tailwind, on Vercel) was rebuilt in Darkmown with the same copy, images, and CMS content pipeline, then both sides were measured (median of three loads, four matched routes): 225-227 KB of compressed JavaScript on every Next.js page vs 18-23 KB total in Darkmown, 46-70 requests vs 11-20, and full builds of 16.6 s cold / 23.2 s warm vs 2.7-3.6 s for all 67 routes. The rebuild lost two categories honestly: raw TTF fonts (1.07 MB vs 158 KB of subset woff2) and unoptimized photos (1,045 KB vs 147 KB of CDN width variants), both addressed by the 2.8/2.9 font recipe and build-time responsive images. The full tables, the per-route breakdown, and the methodology are at [/benchmarks/](/benchmarks/).
+
 ## Accessibility
 
 Landmark and announcement basics are baked in at build time, so they cost zero JavaScript and a static page stays static:
@@ -1042,7 +1087,7 @@ Builds emit security response headers, so a deployed site gets sane defaults wit
 - **`X-Content-Type-Options: nosniff`**, a **`Referrer-Policy`**, and a **`frame-ancestors`** directive (clickjacking protection) on every page.
 - A raw inline `<script>` you write into an `html: true` page is blocked by that policy. Put it in a colocated `.js` file (same-origin, allowed by `'self'`) or widen `script-src` deliberately.
 - Calling another host with `:fetch` or `:form action=`? Widen `connect-src` (and `form-action` for a native form POST) in your deploy config. It is not derived from your page sources.
-- The two embed origins (`youtube-nocookie.com`, `player.vimeo.com`) and `media-src 'self' https:` are pre-authorized, so `:embed` and remote media work out of the box.
+- The two built-in embed origins (`youtube-nocookie.com`, `player.vimeo.com`) are pre-authorized on every page, and any other `:embed` host is unioned into `frame-src` for exactly the pages that embed it, so a third-party booking or checkout iframe works under the shipped headers. `media-src 'self' https:` is unchanged, so `:embed` and remote media work out of the box. The per-route union ships in Cloudflare's `dist/_headers` and is honored by `darkmown serve`; Vercel reads `vercel.json` before the build, so on Vercel you widen `frame-src` in your own `vercel.json` for a non-YouTube/Vimeo host.
 
 ## Limits
 
@@ -1068,7 +1113,7 @@ Darkmown is small on purpose. Here is what it deliberately refuses and what it g
 - **Reactive rows cannot fill a Markdown table.** A reactive row is cloned into a `<div>`, which is not a legal child of `<table>`, so `[WD191]` refuses it. Static loops fill tables fine; for reactive rows, build them from containers (`::: trow` / `::: td`) and style them as a table.
 - **No i18n beyond `lang:`.** No `hreflang`, no message catalog, no ambient locale, no locale routing. A multilingual site means duplicating the tree per locale.
 - **Every framework asset URL is absolute** (`/__wd/...`), so a Darkmown site cannot be mounted at a subpath. It is all-or-nothing per origin.
-- **Includes are macros, not components.** No children, no slots, no default arguments, and a missing argument renders `{ title }` literally rather than erroring.
+- **Includes are macros, not components.** One slot (`{ children }`), string-typed `defaults:` fallbacks, and no props interface beyond `with`; a missing argument with no default still renders `{ title }` literally rather than erroring.
 - **No `darkmown test`.** There is no built-in way to assert your own site's behavior. Use [`compileFromMemory`](#programmatic-compile-compilefrommemory) or a browser test runner.
 
 **Migrating out is easy, and that is on purpose.** `dist/` is portable static HTML plus one runtime file of ~6.6 KB gzipped. No server to port, no proprietary component format, no framework baked into the output. Point any host at the folder, or hand it to whatever you move to next, and the site keeps working.

package/site/pages/index.wd

@@ -188,6 +188,7 @@ The echo endpoint is only live on the deployed site: { reply_error }
 [Deploy to Vercel](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FZVN-DEV%2Fdarkmown){.btn .primary}
 [Read the docs](/docs/){.btn}
 [How it compares to Markdoc](/vs/markdoc/){.btn}
+[Benchmarks vs. a real Next.js site](/benchmarks/){.btn}
 :::
 
 :::

package/src/builder.js

@@ -19,8 +19,10 @@ import {
   sitemapDate,
   sitemapDocuments
 } from "./feeds.js";
-import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
+import { subsetFonts } from "./font-subset.js";
+import { BASE_SECURITY_HEADERS, REACTIVE_CSP, routeCsp } 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";
 
@@ -36,7 +38,10 @@ import { compileSkin, scopeIdFor } from "./skin.js";
  * @typedef {object} RouteManifestEntry
  * @property {string} route Public route path.
  * @property {string} file Source file path, relative to cwd, POSIX-separated.
- * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ * @property {{ skins: string[], scripts: string[], runtime: boolean, embedHosts?: string[] }} assets
+ *   `embedHosts` is present only when the page's `:embed`s frame at least one
+ *   source the base CSP does not already cover — absent keeps a no-embed
+ *   site's routes.json byte-identical.
  */
 
 /**
@@ -59,8 +64,10 @@ import { compileSkin, scopeIdFor } from "./skin.js";
 export const DEP_MAP_FILE = ".wd-dev-deps.json";
 
 // Bumped whenever the map's shape changes, so a stale map from an older
-// Darkmown falls back to a full rebuild instead of being misread.
-const DEP_MAP_VERSION = 2;
+// Darkmown falls back to a full rebuild instead of being misread. (3: manifest
+// entries gained `assets.embedHosts` — a v2 map's entries would silently drop
+// them from a reassembled `_headers`/`routes.json`.)
+const DEP_MAP_VERSION = 3;
 
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
@@ -105,6 +112,12 @@ 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 {{ subsetted: number, cached: number, unavailable: boolean }} fonts
+ *   Font-subset post-pass counts (2.10.0): freshly subsetted, cache-served, and
+ *   whether harfbuzzjs/wawoff2 could not be loaded at all.
  * @property {{ changed: string[], rebuilt: string[], total: number }} [incremental]
  */
 
@@ -119,6 +132,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
@@ -152,7 +171,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) {
@@ -180,6 +209,13 @@ function buildFull(cwd, paths, options) {
   // sees every emitted route/framework file already on disk.
   emitPageAssets(paths);
 
+  // Font subsetting (2.10.0): a post-pass over the emitted dist — every local
+  // font an emitted `@font-face` references is subsetted to the site's charset
+  // as `<name>-subset.woff2` beside the original, and the dist CSS is rewritten
+  // to lead with it. With the optional harfbuzzjs/wawoff2 toolchain absent (or
+  // everything cache-served) this is cheap and never fails the build.
+  const fonts = subsetFonts(paths, { quiet: options.quietFeedHints });
+
   // Surface api/ routing footguns on every build (target-independent): two files
   // that resolve to the same /api path mean one is silently unreachable.
   const apiDir = path.join(cwd, "api");
@@ -192,7 +228,13 @@ 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 },
+    fonts: { subsetted: fonts.subsetted, cached: fonts.cached, unavailable: fonts.unavailable }
+  };
 }
 
 /**
@@ -284,13 +326,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));
@@ -322,10 +381,17 @@ function buildIncremental(cwd, paths, options, changed) {
   const feeds = emitFeeds([...routes, ...extraRoutes], identity, paths, options.quietFeedHints);
   writeDepMap(paths, feedLink, siteInputs(identity, titles), map.routes);
 
+  // The font post-pass re-scans the whole emitted dist (all cache hits when
+  // neither the fonts nor the content changed), so a partially rebuilt route
+  // leaves the rewritten CSS and the subset files whole-site consistent.
+  const fonts = subsetFonts(paths, { quiet: options.quietFeedHints });
+
   return {
     routes: manifest,
     distRoot: paths.distRoot,
     feeds,
+    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable },
+    fonts: { subsetted: fonts.subsetted, cached: fonts.cached, unavailable: fonts.unavailable },
     incremental: { changed, rebuilt, total: routes.length }
   };
 }
@@ -344,10 +410,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} */
@@ -367,6 +453,10 @@ function buildRoute(route, cwd, paths, collections, feedLink, warned, identity,
     emitBehaviors(page.assets, paths);
     if (page.assets.hasCode) emitHighlight(paths);
     const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
+    // The page's :embed frame sources (origins, or 'self'), sorted for a stable
+    // manifest; omitted entirely when empty so a no-embed site's routes.json is
+    // byte-identical to before.
+    const embedHosts = [...page.assets.embedHosts].sort();
     entries.push({
       route: page.route,
       file: relPosix(cwd, route.file),
@@ -377,7 +467,8 @@ function buildRoute(route, cwd, paths, collections, feedLink, warned, identity,
           ...behaviorSrcs,
           ...page.assets.scripts
         ],
-        runtime: page.assets.runtime
+        runtime: page.assets.runtime,
+        ...(embedHosts.length > 0 ? { embedHosts } : {})
       }
     });
   }
@@ -645,7 +736,10 @@ function collectionMemberOf(file) {
  * this point — in practice `@loop` JSON data files, published under
  * `/__wd/data/` (shelf) or beside their page (site/pages). Page/skin/script
  * sources have their own emit paths and hidden segments are never published, so
- * both are skipped.
+ * both are skipped. The publish rules mirror the full sweep exactly, shelf
+ * included: a hidden (`.`, `-`, `_`) segment or a symlink is never copied —
+ * a symlink's target lives outside the project and its bytes would publish
+ * verbatim.
  * @param {string} file Project-relative POSIX path of the changed file.
  * @param {string} cwd
  * @param {Paths} paths
@@ -654,10 +748,12 @@ function collectionMemberOf(file) {
 function copyChangedAsset(file, cwd, paths) {
   const ext = path.posix.extname(file).toLowerCase();
   if ([".md", ".wd", ".skin", ".js"].includes(ext)) return;
+  if (fs.lstatSync(path.join(cwd, file)).isSymbolicLink()) return;
   /** @type {string} */
   let out;
   if (file.startsWith(`${shelfDir}/`)) {
     const rel = file.slice(shelfDir.length + 1);
+    if (rel.split("/").some((segment) => /^[._-]/.test(segment))) return;
     out = path.join(paths.distRoot, ext === ".json" ? "__wd/data" : "__wd/media", rel);
   } else {
     const rel = file.slice(routesDir.length + 1);
@@ -694,9 +790,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>} */
@@ -721,7 +819,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) {
@@ -746,7 +845,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({
@@ -1143,7 +1243,11 @@ export default {
       if (response instanceof Response) return response;
       return Response.json({ ok: false, error: "Handler did not return a Response" }, { status: 500 });
     } catch (err) {
-      return Response.json({ ok: false, error: String((err && err.message) || err) }, { status: 500 });
+      // Log the real error server-side; the client gets a generic 500 — a
+      // handler's message can carry internals (paths, query text) that a
+      // public response must not leak. Dev keeps the message (api-runner).
+      console.error(err);
+      return Response.json({ ok: false, error: "Internal error" }, { status: 500 });
     }
   }
 };
@@ -1188,6 +1292,12 @@ export function stripRuntimeComments(source) {
  *
  * Clean URLs mean a route like `/docs/` is served at both `/docs` and `/docs/`,
  * so each static route emits a path glob (`/docs`, `/docs/*`) that covers both.
+ *
+ * A page whose `:embed`s frame hosts beyond the base policy (a booking widget,
+ * a map) carries those hosts on its manifest entry (`assets.embedHosts`), and
+ * its block — static or reactive — states the unioned per-route policy
+ * ({@link routeCsp}). A reactive route with embed hosts can no longer inherit
+ * the catch-all, so it always gets its own block.
  * @param {RouteManifestEntry[]} manifest
  * @returns {string}
  */
@@ -1198,9 +1308,10 @@ export function renderCloudflareHeaders(manifest) {
   const blocks = [["/*", [...baseLines, `  Content-Security-Policy: ${REACTIVE_CSP}`]]];
 
   for (const entry of manifest) {
-    if (entry.assets.runtime) continue; // reactive routes keep the catch-all (eval-free) CSP
+    if (entry.assets.runtime) continue; // plain reactive routes keep the catch-all (eval-free) CSP
+    const csp = routeCsp(false, entry.assets.embedHosts ?? []);
     for (const pattern of cloudflarePathPatterns(entry.route)) {
-      blocks.push([pattern, [`  Content-Security-Policy: ${STATIC_CSP}`]]);
+      blocks.push([pattern, [`  Content-Security-Policy: ${csp}`]]);
     }
   }
 
@@ -1209,18 +1320,21 @@ export function renderCloudflareHeaders(manifest) {
   // was silently resolving to the static policy from its parent. It is a no-op
   // only while the two policies happen to be identical. A shadowed reactive
   // route therefore re-states its own policy AFTER the static globs, so the
-  // route always lands on the policy its own manifest entry declares.
+  // route always lands on the policy its own manifest entry declares. A
+  // reactive route whose `:embed` hosts widen its policy needs its own block
+  // for the same reason — the catch-all no longer states it.
   const shadowingRoutes = manifest
     .filter((entry) => !entry.assets.runtime && entry.route !== "/")
     .map((entry) => entry.route);
   for (const entry of manifest) {
     if (!entry.assets.runtime) continue;
+    const csp = routeCsp(true, entry.assets.embedHosts ?? []);
     const shadowed = shadowingRoutes.some(
       (parent) => entry.route !== parent && entry.route.startsWith(parent)
     );
-    if (!shadowed) continue;
+    if (!shadowed && csp === REACTIVE_CSP) continue;
     for (const pattern of cloudflarePathPatterns(entry.route)) {
-      blocks.push([pattern, [`  Content-Security-Policy: ${REACTIVE_CSP}`]]);
+      blocks.push([pattern, [`  Content-Security-Policy: ${csp}`]]);
     }
   }
 
@@ -1442,6 +1556,11 @@ function hasColocatedPage(file) {
  * STANDALONE `.skin`/`.js` (no sibling page) is a plain shelf asset the docs
  * promise at `/__wd/media/<path>` (`<script src="/__wd/media/lib/helper.js">`),
  * so it is still published.
+ *
+ * The publish boundary matches `emitPageAssets`: a hidden (`.`, `-`, `_`) path
+ * segment is private framework input, and a symlink is never followed — its
+ * target lives anywhere on the disk and copying it would publish those bytes
+ * verbatim under `/__wd/media/`.
  * @param {Paths} paths
  * @returns {void}
  */
@@ -1452,6 +1571,7 @@ function emitShelfAssets(paths) {
     if (ext === ".md" || ext === ".wd") continue;
     if ((ext === ".skin" || ext === ".js") && hasColocatedPage(file)) continue;
     const rel = path.relative(paths.shelfRoot, file);
+    if (hasHiddenPathSegment(rel) || fs.lstatSync(file).isSymbolicLink()) continue;
     const folder = ext === ".json" ? "__wd/data" : "__wd/media";
     const out = path.join(paths.distRoot, folder, rel);
     fs.mkdirSync(path.dirname(out), { recursive: true });

package/src/catalog.js

@@ -58,7 +58,8 @@ import { ERROR_AREAS, errorCatalog } from "./errors.js";
 /**
  * @typedef {object} DirectiveEntry
  * @property {string} name The directive token (`@loop`, `:state`, `:::`, …).
- * @property {"line" | "block"} kind A single line, or an opener with a closer.
+ * @property {"line" | "block" | "either"} kind A single line, an opener with a
+ *   closer, or a line that may optionally open a block (`@include … @endinclude`).
  * @property {string} syntax One-line schematic (`[…]` = optional, `<…>` = slot).
  * @property {string} description One-line, plain-language summary.
  * @property {string} example One concrete, compilable line.
@@ -97,10 +98,11 @@ import { ERROR_AREAS, errorCatalog } from "./errors.js";
 const DIRECTIVES = [
   {
     name: "@include",
-    kind: "line",
-    syntax: '@include /partial.wd [with key="value" …]',
+    kind: "either",
+    syntax:
+      '@include /partial.wd [with key="value" …]  |  @include /partial.wd [with …] …children… @endinclude',
     description:
-      "Inline another .wd/.md file from site/pages or site/_, passing optional scope args.",
+      'Inline another .wd/.md file from site/pages or site/_, passing optional scope args. Block form compiles the lines before @endinclude in the caller\'s scope and places them where the file puts a standalone `{ children }` line (empty when called without a block). The file may declare `defaults: [name="value"]` frontmatter for args the caller did not pass.',
     example: INCLUDE_EXAMPLE,
     reactive: "static"
   },
@@ -622,6 +624,12 @@ const FRONTMATTER_KEYS = [
     description: "Allow raw HTML in the markdown body (default false).",
     example: "html: true"
   },
+  {
+    name: "defaults",
+    description:
+      'INCLUDE FILES ONLY: fallback values for `with` arguments the caller did not pass (an inline array of name="value" entries; values are strings).',
+    example: 'defaults: [title="Untitled"]'
+  },
   {
     name: "transitions",
     description: "Opt into cross-document view transitions and link prerendering.",
@@ -693,6 +701,7 @@ function blockStructureSection() {
     "- `@loop … @endloop`. `@empty` inside the loop body renders when the list is empty.",
     "- `:if … :endif`, with optional `:else if <condition>` and `:else` branches before the close.",
     "- `:form … :endform`, `:carousel … :endcarousel`, and `::: … :::` (a bare `:::` closes a container).",
+    "- `@include /partial.wd … @endinclude` compiles the lines between in the caller's scope and places them at the partial's standalone `{ children }` line (the slot renders empty when called without a block). `@endinclude` pairs with the nearest preceding unpaired `@include`.",
     ""
   ];
 }