@zvndev/darkmown 2.9.0 → 2.10.1

package/src/api-runner.js

@@ -78,13 +78,17 @@ function dynamicCount(segments) {
 /**
  * Match a request pathname against discovered routes. The pathname is expected
  * to start with `/api`; anything else returns `null` (caller serves static).
+ * A dynamic segment whose percent-encoding is malformed (`%E0%A4%A`) makes
+ * `decodeURIComponent` throw — that is reported as `{ malformed: true }` so the
+ * caller answers a clean 400 instead of crashing the request handler.
  * @param {ApiRoute[]} routes
  * @param {string} pathname Request pathname (no query string).
- * @returns {{ file: string, params: Record<string, string> } | null}
+ * @returns {{ file: string, params: Record<string, string> } | { malformed: true } | null}
  */
 export function matchApiRoute(routes, pathname) {
   if (pathname !== "/api" && !pathname.startsWith("/api/")) return null;
   const parts = pathname.split("/").filter(Boolean).slice(1); // drop leading "api"
+  let sawMalformed = false;
   for (const route of routes) {
     if (route.segments.length !== parts.length) continue;
     /** @type {Record<string, string>} */
@@ -93,7 +97,15 @@ export function matchApiRoute(routes, pathname) {
     for (let i = 0; i < parts.length; i++) {
       const seg = route.segments[i];
       if (seg.startsWith("[") && seg.endsWith("]")) {
-        params[seg.slice(1, -1)] = decodeURIComponent(parts[i]);
+        try {
+          params[seg.slice(1, -1)] = decodeURIComponent(parts[i]);
+        } catch {
+          // Malformed here does not preclude a static match on a later route,
+          // so keep scanning and report only if nothing else claimed the path.
+          sawMalformed = true;
+          ok = false;
+          break;
+        }
       } else if (seg !== parts[i]) {
         ok = false;
         break;
@@ -101,13 +113,15 @@ export function matchApiRoute(routes, pathname) {
     }
     if (ok) return { file: route.file, params };
   }
-  return null;
+  return sawMalformed ? { malformed: true } : null;
 }
 
 /**
  * Build a Web-standard `Request` from a Node `IncomingMessage`. The body (for
- * methods that carry one) is buffered fully — dev endpoints are small and this
- * avoids the `duplex: "half"` streaming dance.
+ * methods that carry one) is buffered up to {@link MAX_BODY_BYTES} — dev and
+ * preview endpoints are small and this avoids the `duplex: "half"` streaming
+ * dance. A larger body rejects with {@link BodyTooLargeError}, which
+ * `handleApiRequest` answers as a 413.
  * @param {import("node:http").IncomingMessage} req
  * @returns {Promise<Request>}
  */
@@ -125,6 +139,15 @@ export async function nodeRequestToWeb(req) {
   return new Request(url, init);
 }
 
+/** Bodies larger than this are rejected with a 413 rather than buffered without bound. */
+const MAX_BODY_BYTES = 10 * 1024 * 1024;
+
+/**
+ * Rejection marker for an over-cap request body, so `handleApiRequest` answers
+ * 413 (a client error) instead of a generic 500.
+ */
+class BodyTooLargeError extends Error {}
+
 /**
  * @param {import("node:http").IncomingMessage} req
  * @returns {Promise<Buffer>}
@@ -133,7 +156,22 @@ function readBody(req) {
   return new Promise((resolve, reject) => {
     /** @type {Buffer[]} */
     const chunks = [];
-    req.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+    let received = 0;
+    let over = false;
+    req.on("data", (chunk) => {
+      received += chunk.length;
+      if (received > MAX_BODY_BYTES) {
+        // Stop accumulating, but keep draining the socket: destroying the
+        // request here would kill the connection before the 413 answer can
+        // reach the client (verified: `req.destroy()` mid-upload → EPIPE).
+        if (!over) {
+          over = true;
+          reject(new BodyTooLargeError(`Request body too large (over ${MAX_BODY_BYTES} bytes)`));
+        }
+        return;
+      }
+      chunks.push(Buffer.from(chunk));
+    });
     req.on("end", () => resolve(Buffer.concat(chunks)));
     req.on("error", reject);
   });
@@ -189,18 +227,41 @@ export async function writeWebResponse(response, res, acceptEncoding) {
  * the handler succeeded or threw), `false` when nothing matched so the caller
  * should fall through to static serving.
  *
+ * Error disclosure: a handler throw is answered as JSON either way, but the
+ * `error` field carries the real message only when `discloseErrors` is set
+ * (the dev server's default — a documented dev convenience). The preview
+ * server passes `false` and the client gets the generic "Internal error",
+ * matching the shape the generated Cloudflare worker ships.
+ *
  * @param {object} io
  * @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).
+ * @param {boolean} [io.discloseErrors] Echo the thrown message to the client
+ *   (default true, the dev behavior). Pass false on any production-shaped path.
  * @returns {Promise<boolean>}
  */
-export async function handleApiRequest({ apiDir, req, res, acceptEncoding }) {
+export async function handleApiRequest({
+  apiDir,
+  req,
+  res,
+  acceptEncoding,
+  discloseErrors = true
+}) {
   const pathname = new URL(req.url || "/", "http://localhost").pathname;
   const match = matchApiRoute(discoverApiRoutes(apiDir), pathname);
   if (!match) return false;
+  if ("malformed" in match) {
+    // A malformed percent-encoded dynamic segment: the URL itself is at fault,
+    // so this is a 400, not a 500 — and it must never reach the caller's catch.
+    await writeWebResponse(
+      Response.json({ ok: false, error: "Malformed URL encoding" }, { status: 400 }),
+      res
+    );
+    return true;
+  }
 
   try {
     const handler = await importHandler(match.file);
@@ -215,7 +276,18 @@ export async function handleApiRequest({ apiDir, req, res, acceptEncoding }) {
     }
     await writeWebResponse(response, res, acceptEncoding);
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof BodyTooLargeError) {
+      await writeWebResponse(
+        Response.json({ ok: false, error: "Request body too large" }, { status: 413 }),
+        res
+      );
+      return true;
+    }
+    const message = discloseErrors
+      ? err instanceof Error
+        ? err.message
+        : String(err)
+      : "Internal error";
     await writeWebResponse(Response.json({ ok: false, error: message }, { status: 500 }), res);
   }
   return true;

package/src/builder.js

@@ -19,7 +19,8 @@ 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";
@@ -37,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.
  */
 
 /**
@@ -60,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));
 
@@ -109,6 +115,9 @@ export function buildSite(cwd = process.cwd(), options = {}) {
  * @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]
  */
 
@@ -200,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");
@@ -216,7 +232,8 @@ function buildFull(cwd, paths, options) {
     routes: manifest,
     distRoot: paths.distRoot,
     feeds,
-    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable }
+    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable },
+    fonts: { subsetted: fonts.subsetted, cached: fonts.cached, unavailable: fonts.unavailable }
   };
 }
 
@@ -364,11 +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 }
   };
 }
@@ -430,6 +453,10 @@ function buildRoute(
     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),
@@ -440,7 +467,8 @@ function buildRoute(
           ...behaviorSrcs,
           ...page.assets.scripts
         ],
-        runtime: page.assets.runtime
+        runtime: page.assets.runtime,
+        ...(embedHosts.length > 0 ? { embedHosts } : {})
       }
     });
   }
@@ -708,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
@@ -717,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);
@@ -1210,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 });
     }
   }
 };
@@ -1255,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}
  */
@@ -1265,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}`]]);
     }
   }
 
@@ -1276,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}`]]);
     }
   }
 
@@ -1417,15 +1464,17 @@ function emitAssets(assets, paths, pageHtml, warned) {
     fs.mkdirSync(path.dirname(out), { recursive: true });
     if (source.endsWith(".skin")) {
       const src = fs.readFileSync(source, "utf8");
+      // `file` threads the source path into compileSkin so a skin authoring
+      // error reports `file:line` like every other compile error.
       if (assets.scopedSkins.has(source)) {
         const rel = path.relative(paths.cwd, source).replaceAll(path.sep, "/");
         const scope = scopeIdFor(rel);
         /** @type {Set<string>} */
         const subjects = new Set();
-        fs.writeFileSync(out, compileSkin(src, { scope, subjects }));
+        fs.writeFileSync(out, compileSkin(src, { scope, subjects, file: source }));
         warnUnusedScoped(subjects, scope, pageHtml, path.basename(source), warned);
       } else {
-        fs.writeFileSync(out, compileSkin(src));
+        fs.writeFileSync(out, compileSkin(src, { file: source }));
       }
     } else {
       fs.copyFileSync(source, out);
@@ -1509,6 +1558,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}
  */
@@ -1519,6 +1573,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`.",
     ""
   ];
 }

package/src/cli.js

@@ -413,7 +413,10 @@ function startDevServer({ cwd, log, warn, error }) {
     }
     // Serverless parity: run a project `api/*.js` function if the path matches,
     // exactly as Vercel/Cloudflare would in production; otherwise serve static. A
-    // throw on either path (e.g. a stat/read error) becomes a clean 500.
+    // throw on either path (e.g. a stat/read error) becomes a clean 500. Dev
+    // DELIBERATELY echoes the stack and the api runner keeps real error messages
+    // (the `discloseErrors` default) — this is the author's own machine; `serve`
+    // is the production-shaped path and discloses nothing.
     handleApiRequest({ apiDir, req, res })
       .then((handled) => {
         if (!handled) serveDev(distRoot, url, res, draftRoutes(cwd), () => lastBuildError);
@@ -473,15 +476,20 @@ function startPreviewServer({ cwd, log, error }) {
   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 })
+    // the path matches; otherwise serve static (compressed when negotiated).
+    // Unlike dev, serve mirrors PRODUCTION disclosure rules: the api runner gets
+    // `discloseErrors: false` (the client sees "Internal error", same shape as
+    // the generated Cloudflare worker), a malformed dynamic segment is a clean
+    // 400 inside the runner, and an unexpected throw here is logged server-side
+    // but never echoed — a stack trace leaks paths and internals to the client.
+    handleApiRequest({ apiDir, req, res, acceptEncoding, discloseErrors: false })
       .then((handled) => {
         if (!handled) serve(distRoot, req.url || "/", res, { acceptEncoding });
       })
       .catch((err) => {
+        error(err instanceof Error && err.stack ? err.stack : String(err));
         res.writeHead(500, { "content-type": "text/plain" });
-        res.end((err instanceof Error && err.stack) || String(err));
+        res.end("Internal Server Error");
       });
   });
   return new Promise((resolve) => {
@@ -604,7 +612,7 @@ Authoring:
  * An incremental (dev `--changed`) build reports what it actually rebuilt —
  * `Rebuilt 2 of 14 routes (/blog/, /blog/hello/) into dist` — naming the routes
  * when there are few enough to read.
- * @param {{ routes: unknown[], feeds: { sitemap: number | null, rss: number | null }, incremental?: { rebuilt: string[], total: number }, images?: { generated: number, cached: number, unavailable: boolean } }} result
+ * @param {{ routes: unknown[], feeds: { sitemap: number | null, rss: number | null }, incremental?: { rebuilt: string[], total: number }, images?: { generated: number, cached: number, unavailable: boolean }, fonts?: { subsetted: number, cached: number, unavailable: boolean } }} result
  * @param {string} relativeRoot `dist` relative to cwd, for the message tail.
  * @returns {string}
  */
@@ -623,6 +631,10 @@ export function buildSummary(result, relativeRoot) {
       `image variants (${result.images.generated} generated, ${result.images.cached} cached)`
     );
   }
+  // Font post-pass (2.10.0): same rule — report only when subsets materialized.
+  if (result.fonts && result.fonts.subsetted + result.fonts.cached > 0) {
+    parts.push(`fonts (${result.fonts.subsetted} subsetted, ${result.fonts.cached} cached)`);
+  }
   return `${parts.join(", ")} into ${relativeRoot}`;
 }
 

package/src/compiler/body.js

@@ -33,8 +33,10 @@ import {
   handleTheme,
   renderDemoDirective
 } from "./directives.js";
+import { CHILDREN_SLOT_LINE, childrenSlot } from "./includes.js";
 import { handleLoop, spliceTables } from "./loops.js";
 import { renderProse } from "./markdown.js";
+import { scanIncludeBlock, strayEndinclude } from "./structure.js";
 
 /**
  * @typedef {import("./context.js").Ctx} Ctx
@@ -148,6 +150,21 @@ export function compileBody(lines, ctx) {
       }
     }
 
+    // A standalone `{ children }` line is an include's slot marker: when the
+    // file being compiled was called as a block-form @include, the compiled
+    // children HTML (built in the caller's context by handleInclude) splices
+    // in here. With no slot in scope — a top-level page — the line falls
+    // through to prose and stays the literal text `{ children }`; an include
+    // called without a block carries an empty slot and splices nothing.
+    if (!inRawBlock && CHILDREN_SLOT_LINE.test(line)) {
+      const slot = childrenSlot(ctx);
+      if (slot !== null) {
+        flush();
+        if (slot) push(slot);
+        continue;
+      }
+    }
+
     // 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
@@ -164,7 +181,15 @@ export function compileBody(lines, ctx) {
 
     if (/^@include\s/.test(line)) {
       flush();
-      push(handleInclude(line, ctx, i));
+      const block = scanIncludeBlock(lines, i);
+      if (block) {
+        const includeAt = ctx.comp.symbols.length;
+        push(handleInclude(line, ctx, i, block.body));
+        stampBlockEnd(ctx, includeAt, block.end);
+        i = block.end;
+      } else {
+        push(handleInclude(line, ctx, i));
+      }
       continue;
     }
     if (/^@loop\s/.test(line)) {
@@ -340,6 +365,10 @@ export function compileBody(lines, ctx) {
         { code: "WD009", file: ctx.file, hint: "@loop items into item ... @endloop" }
       );
     }
+    // `@endinclude` that reached the dispatcher: every opener that could pair
+    // with it already did (scanIncludeBlock consumes paired closers), so this
+    // one has no opener of its own — one obvious fix, its own WD6xx code.
+    if (/^@endinclude(?:\s|$)/.test(line)) strayEndinclude(line, ctx, i);
     // `:endcarousel` joins the family: a closer with no opener is a mistake with
     // one obvious fix, and the vague "matches none" warning it used to get named
     // the wrong problem ("check the spelling") for a token spelled correctly.

package/src/compiler/context.js

@@ -39,6 +39,12 @@
  *   that opted into scoping (`scoped` first line). The builder emits these with
  *   the scope attribute and runs the unused-selector warning against the stamped
  *   subtree; the HTML stamp uses them to scope the matching page/include subtree.
+ * @property {Set<string>} embedHosts Frame sources (origins like
+ *   `https://app.example.com`, or `'self'` for a same-origin embed) of every
+ *   `:embed` on the page, collected AFTER the YouTube/Vimeo rewrite. The builder
+ *   records them on the route manifest entry so the per-route CSP's `frame-src`
+ *   authorizes exactly the hosts this page frames (see `routeCsp` in
+ *   src/headers.js).
  */
 
 /**
@@ -147,6 +153,11 @@
  *   opener's `file:line` + raw text, set when descending into a loop body so the
  *   reactive-nesting-depth error can point at the offending opener.
  * @property {boolean} [loopMeta] Inside a loop body, so `$index`/`$first`/… are valid.
+ * @property {number} [includeBlockDepth] Enclosing block-form `@include`
+ *   CHILDREN levels (0 at page level, absent on a fresh file compile). Set
+ *   while compiling a block's children so a block include nested past one
+ *   level inside children is a compile error (WD616, together with the
+ *   include-stack depth check for include bodies).
  * @property {import("markdown-it").default} [md] Markdown-it instance selected for this file.
  * @property {(lines: string[], ctx: Ctx) => string} compileBody The body
  *   dispatcher, threaded through the context so block handlers (`:if`, `:::`,
@@ -303,7 +314,8 @@ export function createCompilation(reader) {
       runtime: false,
       behaviors: new Set(),
       hasCode: false,
-      scopedSkins: new Set()
+      scopedSkins: new Set(),
+      embedHosts: new Set()
     },
     state: new Map(),
     stores: new Set(),

package/src/compiler/includes.js

@@ -8,7 +8,7 @@
 import path from "node:path";
 import { scopeIdFor } from "../skin.js";
 import { pageIncludeExtensions, wdError } from "./context.js";
-import { stripQuotes } from "./interpolation.js";
+import { lookupVar, stripQuotes } from "./interpolation.js";
 
 /**
  * @typedef {import("./context.js").Paths} Paths
@@ -244,6 +244,49 @@ export function isAllowedInclude(file, context, reader) {
   return contains(canonical(path.resolve(file)), roots.map(canonical));
 }
 
+// ---------------------------------------------------------------------------
+// The `{ children }` slot (block-form @include).
+//
+// `@include /card.wd … @endinclude` compiles the lines between opener and
+// closer in the CALLER's context and hands the resulting HTML to the include
+// file, which places it with a standalone `{ children }` line. The hand-off
+// travels in the static scope chain under a key no author syntax can produce
+// (interpolation, `with` args, and `:state` names are all `[A-Za-z0-9_$-]`
+// shaped), so a `{ children }` interpolation in prose never resolves it — only
+// the body parser's slot-marker intercept reads it. Pure macro expansion: the
+// children compile once, at build time, and the include stays zero-JS unless
+// the children themselves bind state.
+// ---------------------------------------------------------------------------
+
+/**
+ * Scope key carrying the compiled children HTML for the include currently
+ * being compiled. Control-character-prefixed so no author-visible name can
+ * collide with it or read it through `{ }` interpolation.
+ */
+export const INCLUDE_CHILDREN = "\0children";
+
+/**
+ * A line that is exactly the slot marker (`{ children }`, whitespace-tolerant),
+ * matching the spelling freedom of `{ name }` interpolation. Shared by the
+ * body parser (which splices the slot) and the include handler (which scans an
+ * include's body for whether the slot is ever used).
+ * @type {RegExp}
+ */
+export const CHILDREN_SLOT_LINE = /^\s*\{\s*children\s*\}\s*$/;
+
+/**
+ * The compiled children HTML for the include currently compiling, or null when
+ * the file is not being compiled as an include at all (a top-level page) — in
+ * which case a `{ children }` line stays literal text. An include called
+ * WITHOUT a block carries "" (the slot renders empty).
+ * @param {import("./context.js").Ctx} ctx
+ * @returns {string | null}
+ */
+export function childrenSlot(ctx) {
+  const found = lookupVar(ctx.scope, INCLUDE_CHILDREN);
+  return found.found ? /** @type {string} */ (found.value) : null;
+}
+
 // ---------------------------------------------------------------------------
 // Plain .md hints
 // ---------------------------------------------------------------------------