@zvndev/darkmown 2.9.0 → 2.10.0

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:
@@ -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,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}`]]);
     }
   }
 
@@ -1509,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}
  */
@@ -1519,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`.",
     ""
   ];
 }

package/src/cli.js

@@ -604,7 +604,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 +623,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
 // ---------------------------------------------------------------------------

package/src/compiler/media.js

@@ -175,6 +175,7 @@ export function handleEmbed(line, ctx, index) {
   const sizing = embedSizing(attrs, ctx, index);
   const allow = embedAllow(attrs, ctx, index);
   const { url, label } = resolveEmbed(raw, ctx);
+  recordEmbedHost(ctx, url);
   const title = attrs.get("title") || "";
   const iframe =
     `<iframe src="${escapeHtml(url)}" title="${escapeHtml(title || label)}" loading="lazy" ` +
@@ -237,6 +238,30 @@ function embedAllow(attrs, ctx, index) {
   return tokens.join("; ");
 }
 
+/**
+ * Record the frame source the emitted iframe actually loads, so the builder can
+ * union it into this route's CSP `frame-src`. An absolute http(s) URL contributes
+ * its origin; a relative URL frames the page's own origin, so it contributes
+ * `'self'`. A `{ state }`-driven URL is unknowable at compile time and records
+ * nothing (widening that policy is the app's deploy-config decision, exactly
+ * like a remote `:fetch` target widening `connect-src`).
+ * @param {Ctx} ctx
+ * @param {string} url The FINAL iframe src (post YouTube/Vimeo rewrite).
+ * @returns {void}
+ */
+function recordEmbedHost(ctx, url) {
+  if (url.startsWith("{")) return;
+  if (!/^https?:\/\//i.test(url)) {
+    ctx.comp.assets.embedHosts.add("'self'");
+    return;
+  }
+  try {
+    ctx.comp.assets.embedHosts.add(new URL(url).origin);
+  } catch {
+    /* a malformed-but-scheme-valid URL paints as-is; nothing to authorize */
+  }
+}
+
 /**
  * Map a watch/share URL to its embeddable form. YouTube → no-cookie embed, Vimeo →
  * player; anything else is validated as a generic http(s) iframe source.

package/src/compiler/page.js

@@ -14,6 +14,7 @@ import { parseFrontmatter, resolveSharedSkins, warnLikelyFrontmatter } from "./f
 import { imageSize } from "./image-size.js";
 import {
   collectColocatedAssets,
+  isAllowedInclude,
   scanMarkdownHints,
   scopedSkinFor,
   scopeInfoForSkin,
@@ -408,6 +409,10 @@ function srcOf(tag) {
  * Read an image's intrinsic dimensions from disk, or null when the src is
  * remote/relative/unreadable. Resolution mirrors the asset emit: `/__wd/media/x`
  * comes from the shelf (`site/_`), other absolute paths from `site/pages`.
+ * Containment mirrors the `@include` sandbox ({@link isAllowedInclude}): a src
+ * that resolves OUTSIDE those roots — `![x](/../../anywhere.png)`, or a symlink
+ * pointing out — is treated exactly like a missing image (no dimensions), never
+ * read.
  * @param {string} src
  * @param {Paths} paths
  * @param {import("./reader.js").Reader} reader
@@ -423,6 +428,7 @@ function measureImage(src, paths, reader) {
   } else {
     return null; // page-relative: the source directory is lost after assembly
   }
+  if (!isAllowedInclude(filePath, paths, reader)) return null;
   try {
     // `imageSize` itself never throws (an unsupported or malformed image is just
     // null); the try/catch is for the read, which does throw on a missing file.