@zvndev/darkmown 2.8.0 → 2.10.0

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 } }} 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}
  */
@@ -617,6 +617,16 @@ export function buildSummary(result, relativeRoot) {
   const parts = [`Built ${result.routes.length} routes`];
   if (result.feeds.sitemap !== null) parts.push(`sitemap (${result.feeds.sitemap} urls)`);
   if (result.feeds.rss !== null) parts.push(`rss (${result.feeds.rss} posts)`);
+  // Image pre-pass (2.9.0): worth reporting only when variants materialized.
+  if (result.images && result.images.generated + result.images.cached > 0) {
+    parts.push(
+      `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).
  */
 
 /**
@@ -81,6 +87,11 @@
  *   read threads through — the real filesystem by default, or an in-memory map
  *   for `compileFromMemory`. Set once by `createCompilation` and reached via
  *   `ctx.comp.reader` in the directive handlers (includes, loop data).
+ * @property {Map<string, number[]> | null} imageVariants Build-time-GENERATED
+ *   responsive variants (2.9.0): the original image's absolute source path →
+ *   the sorted `@<width>` sizes the builder's pre-pass resized into dist. Null
+ *   outside a builder-driven compile (e.g. `compileFromMemory`), where the
+ *   srcset wiring probes author-provided variants only.
  * @property {Symbol[]} symbols Every declared thing this compile saw, in source
  *   order, recorded by {@link recordSymbol} from the handler that parsed it.
  *   Surfaced on {@link CompiledPage} so a tool layer can answer "what is in this
@@ -142,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`, `:::`,
@@ -290,6 +306,7 @@ export const LOOP_META = Object.assign(Object.create(null), {
 export function createCompilation(reader) {
   return {
     reader,
+    imageVariants: null,
     assets: {
       skins: new Set(),
       scripts: new Set(),
@@ -297,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/markdown.js

@@ -363,25 +363,36 @@ function attrBindPlugin(mdInstance) {
 }
 
 // ---------------------------------------------------------------------------
-// RESPONSIVE IMAGE VARIANTS (the `@width` convention, 2.8.0 / A2).
+// RESPONSIVE IMAGE VARIANTS (the `@width` convention, 2.8.0 / A2; generated
+// variants, 2.9.0).
 //
-// Darkmown has no image pipeline and never will (no resize dependency), so the
-// convention wires variants the AUTHOR (or their CDN tooling) already made:
+// Variants come from two places, and this wiring treats them identically:
 // next to `/doctors/dr-x.webp` sit `dr-x@640.webp`, `dr-x@1280.webp` — same
 // directory, same extension, `@<width>` before it. When at least one exists,
 // the markdown image gains a `srcset` (variants ascending, then the original
 // at its intrinsic width) so the browser downloads the size it needs instead
 // of the full-resolution file. The original stays the `src` fallback.
 //
-// Discovery is an existence PROBE over {@link VARIANT_WIDTHS} through the
-// injected reader: the Reader contract has no directory listing, so an off-list
-// width (say `@500`) is simply not wired — a deliberate, documented miss, never
-// an error. Each variant's descriptor width is its REAL intrinsic width from
-// the image header (a `@640` file that actually holds 600px says 600w); when
-// the bytes cannot be read or parsed (the in-memory reader has no binaries), the
-// filename width is the fallback. The original's intrinsic width follows the
-// same rule, except it has no filename fallback: unreadable means it is left
-// out of the srcset and stays the plain `src` default.
+//  * AUTHOR-PROVIDED (2.8.0): files the author (or their CDN tooling) placed
+//    beside the source. Discovery is an existence PROBE over
+//    {@link VARIANT_WIDTHS} through the injected reader: the Reader contract
+//    has no directory listing, so an off-list width (say `@500`) is simply not
+//    wired — a deliberate, documented miss, never an error. Each variant's
+//    descriptor width is its REAL intrinsic width from the image header (a
+//    `@640` file that actually holds 600px says 600w); when the bytes cannot
+//    be read or parsed (the in-memory reader has no binaries), the filename
+//    width is the fallback.
+//  * BUILD-TIME GENERATED (2.9.0): the builder's pre-pass (src/image-variants.js)
+//    resized the source with the optional sharp dependency and wrote the
+//    variants into dist. It hands this compile a map (original's absolute
+//    source path → widths) via `comp.imageVariants`; the widths ARE the
+//    descriptor widths because the generator made them so. An author-provided
+//    file at the same width always wins — the generator skips those widths,
+//    and the href dedupe below keeps it that way even against a stale map.
+//
+// The original's intrinsic width follows the same measure-with-fallback rule,
+// except it has no filename fallback: unreadable means it is left out of the
+// srcset and stays the plain `src` default.
 //
 // A bound src (`![alt]({ photo })`) is repainted by the runtime, so a srcset
 // computed from the seed would go stale on the first render — those images are
@@ -483,6 +494,18 @@ function buildSrcset(src, ctx) {
     if (!reader.exists(abs)) continue;
     candidates.push({ href: `${base}@${width}${ext}`, width: measureWidth(abs, reader) ?? width });
   }
+  // Builder-generated variants (2.9.0): resized into dist by the pre-pass, so
+  // the reader cannot probe them — they arrive through the compile instead.
+  // An author-provided sibling at the same width wins (the generator skips
+  // those widths; the href check keeps precedence even against a stale map).
+  const generated = ctx.comp.imageVariants?.get(path.join(root, `${relBase}${ext}`));
+  if (generated) {
+    for (const width of generated) {
+      const href = `${base}@${width}${ext}`;
+      if (candidates.some((c) => c.href === href)) continue;
+      candidates.push({ href, width });
+    }
+  }
   if (!candidates.length) return null;
   const intrinsic = measureWidth(path.join(root, `${relBase}${ext}`), reader);
   if (intrinsic) candidates.push({ href: src, width: intrinsic });

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,
@@ -45,7 +46,7 @@ const SKIP_LINK_STYLE =
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: SiteContext, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
  *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
  *   site has dated posts), `feed` carries its absolute href + title so every page
  *   links it. `site` carries the origin + this page's own route (and its resolved
@@ -53,14 +54,23 @@ const SKIP_LINK_STYLE =
  *   build-time collection index a bare-name `@loop` resolves against; `vars` seeds
  *   the document scope (the pager `page` object on a paginated route). `reader` is
  *   the source reader (fs-backed by default via `src/compiler.js`; in-memory for
- *   `compileFromMemory`).
+ *   `compileFromMemory`). `imageVariants` is the builder's generated-variant map
+ *   (2.9.0): original absolute source path → `@<width>` sizes resized into dist.
  * @returns {CompiledPage}
  */
 export function compilePage(file, context, options = {}) {
   // The raw entry point requires a reader — the Node barrel (`src/compiler.js`)
   // injects `fsReader()`, and `compileFromMemory` injects a `memoryReader`.
   const reader = /** @type {import("./reader.js").Reader} */ (options.reader);
-  const compiled = compileDocument(file, context, [], options.vars, options.collections, reader);
+  const compiled = compileDocument(
+    file,
+    context,
+    [],
+    options.vars,
+    options.collections,
+    reader,
+    options.imageVariants ?? null
+  );
   const title = String(compiled.meta.title || "Darkmown");
   const description = String(compiled.meta.description || "");
   // Per-page document language for the `<html lang>` attribute (`lang: fr` in
@@ -399,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
@@ -414,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.
@@ -434,6 +449,10 @@ function measureImage(src, paths, reader) {
  *   Build-time collection index a bare-name `@loop` resolves against.
  * @param {import("./reader.js").Reader} [reader] Source reader (fs-backed when
  *   omitted via `src/compiler.js`; in-memory for `compileFromMemory`).
+ * @param {Map<string, number[]> | null} [imageVariants] Build-time-generated
+ *   responsive variants (original's absolute source path → widths), threaded by
+ *   the builder so the srcset wiring includes them alongside author-provided
+ *   `@<width>` siblings.
  * @returns {CompiledDocument}
  */
 export function compileDocument(
@@ -442,13 +461,15 @@ export function compileDocument(
   stack = [],
   vars = {},
   collections = new Map(),
-  reader
+  reader,
+  imageVariants = null
 ) {
   // reader is injected by every caller (the Node barrel's `fsReader()` or
   // `compileFromMemory`'s `memoryReader`); it is only trailing-optional here so
   // the defaulted `vars`/`collections` params can precede it.
   const comp = createCompilation(/** @type {import("./reader.js").Reader} */ (reader));
   comp.collections = collections;
+  comp.imageVariants = imageVariants;
   const result = compileFile(
     file,
     context,