@zvndev/darkmown 2.8.0 → 2.10.0

package/src/image-variants.js

@@ -0,0 +1,294 @@
+// ---------------------------------------------------------------------------
+// BUILD-TIME RESPONSIVE IMAGE VARIANTS (2.9.0).
+//
+// The 2.8.0 `@<width>` convention wires srcset entries for variants the AUTHOR
+// already made; this pre-pass makes them itself. Before routes compile, the
+// builder scans `site/pages` for raster photos (`.jpg`/`.jpeg`/`.png`/`.webp`),
+// and for each one large enough to be worth it writes resized `name@<width>.ext`
+// siblings into `dist/` at their final served paths and hands the compiler a
+// map of what was generated, so markdown.js's srcset wiring treats a generated
+// variant exactly like an author-provided one. The author convention still
+// wins: a `name@640.jpg` already in the source tree is never overwritten, and
+// that width is simply not generated.
+//
+// Resizing needs sharp, and sharp is an OPTIONAL dependency, so every sharp
+// touch is quarantined behind a seam: the actual resize runs in a child
+// process (src/image-variant-resize.js) that dynamic-imports sharp and reports
+// `unavailable` instead of throwing when it is absent. Without sharp the build
+// is byte-identical to 2.8.0 plus ONE hint naming the images that could have
+// gained variants. A corrupt image or a sharp failure on one file is a hint
+// for that file; the build never fails over an image.
+//
+// Resizes are cached in `node_modules/.cache/darkmown-images/` keyed by
+// content hash + width, so a second build does zero sharp work for unchanged
+// images (and needs no sharp at all when everything is cached). The cache
+// lives under node_modules, which every project's .gitignore already excludes.
+//
+// The build is synchronous, sharp is not — that is the whole reason for the
+// child process. `buildSite` stays a sync API; one `spawnSync` per build runs
+// all pending resizes, and a fully cached build spawns nothing.
+// ---------------------------------------------------------------------------
+
+import { spawnSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { imageSize } from "./compiler/image-size.js";
+
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ */
+
+/**
+ * One resize handed to the worker: shrink `source` to `width` pixels wide and
+ * write it (in its own format) to `out`, the cache path.
+ * @typedef {object} ResizeJob
+ * @property {string} source Absolute path of the original image.
+ * @property {string} out Absolute cache path the resized variant is written to.
+ * @property {number} width Target width in pixels (always below the intrinsic).
+ * @property {"jpeg" | "png" | "webp"} format Output encoder, from the source extension.
+ */
+
+/**
+ * What the worker reports back. `unavailable` means sharp could not be loaded
+ * at all (not installed, or a broken native binding) — every pending image
+ * then ships without variants. `failed` carries one entry per image that
+ * sharp itself rejected (corrupt payload, unsupported encoding).
+ * @typedef {object} ResizeResult
+ * @property {boolean} unavailable
+ * @property {{ file: string, width: number, error: string }[]} failed
+ */
+
+/**
+ * The pre-pass result: `variants` is the map the compiler's srcset wiring
+ * consults (original's ABSOLUTE source path → sorted widths generated into
+ * dist), and the counts feed the build summary. `unavailable` marks the
+ * sharp-absent build (which is otherwise identical to not having the feature).
+ * @typedef {object} ImageVariantPlan
+ * @property {Map<string, number[]>} variants
+ * @property {number} generated Variants resized this build.
+ * @property {number} cached Variants served from the on-disk cache.
+ * @property {boolean} unavailable sharp could not be loaded.
+ */
+
+/** The widths generated by default, both comfortably under a typical source. */
+export const DEFAULT_VARIANT_WIDTHS = [640, 1280];
+
+/** The raster formats sharp resizes; everything else (svg, gif, avif) passes through. */
+const RASTER_EXTENSIONS = new Set([".jpg", ".jpeg", ".png", ".webp"]);
+
+/** An image at or below this width is already small everywhere — skip it silently. */
+const SMALL_IMAGE_MAX_WIDTH = 700;
+
+/** The cache root, relative to the project. Under node_modules, so already ignored. */
+const CACHE_DIR = "node_modules/.cache/darkmown-images";
+
+const WORKER_PATH = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "image-variant-resize.js"
+);
+
+/**
+ * Scan `site/pages` for raster images and generate `@<width>` variants into
+ * `dist`, returning the variant map the compiler wires into srcsets.
+ *
+ * Skips, none of them errors: `@<width>` variant files themselves (they are
+ * output, not sources), hidden-path and symlinked files (mirroring
+ * `emitPageAssets`, which would never publish them), images at or under 700px
+ * wide (already small), widths at or above the intrinsic size (never
+ * upscale), and widths the author already provided (their file wins). An image
+ * whose dimensions cannot be read, and one sharp fails on, get a hint naming
+ * the file and ship without variants.
+ * @param {Paths} paths
+ * @param {{ widths?: number[], cacheDir?: string, quiet?: boolean,
+ *   runJobs?: (jobs: ResizeJob[]) => ResizeResult }} [options]
+ *   `widths` overrides {@link DEFAULT_VARIANT_WIDTHS}. `quiet` suppresses the
+ *   hints (dev-server rebuilds, which already printed them at the initial
+ *   build). `runJobs` is the resize seam — the default spawns the worker
+ *   process; tests inject fakes for the unavailable/crash paths.
+ * @returns {ImageVariantPlan}
+ */
+export function generateImageVariants(paths, options = {}) {
+  const widths = options.widths ?? DEFAULT_VARIANT_WIDTHS;
+  const cacheDir = options.cacheDir ?? path.join(paths.cwd, CACHE_DIR);
+  const runJobs = options.runJobs ?? runResizeJobs;
+  const hint = options.quiet ? () => {} : (/** @type {string} */ m) => console.warn(`hint: ${m}`);
+  /** @type {Map<string, number[]>} */
+  const variants = new Map();
+  const stats = { generated: 0, cached: 0, unavailable: false };
+
+  /** @type {ResizeJob[]} */
+  const pending = [];
+  /** @type {{ job: ResizeJob, distOut: string }[]} */
+  const waiting = [];
+  /** @type {string[]} Project-relative paths of images with uncached work, for the sharp-absent hint. */
+  const needingSharp = [];
+
+  /**
+   * Record one materialized variant: copy it from the cache to its served
+   * path and add its width to the compiler map.
+   * @param {string} source Absolute path of the original.
+   * @param {number} width
+   * @param {string} cacheFile
+   * @param {string} distOut
+   */
+  const emitVariant = (source, width, cacheFile, distOut) => {
+    fs.mkdirSync(path.dirname(distOut), { recursive: true });
+    fs.copyFileSync(cacheFile, distOut);
+    const list = variants.get(source) ?? [];
+    list.push(width);
+    variants.set(source, list);
+  };
+
+  if (fs.existsSync(paths.routesRoot)) {
+    for (const file of walk(paths.routesRoot)) {
+      const ext = path.extname(file).toLowerCase();
+      if (!RASTER_EXTENSIONS.has(ext)) continue;
+      const stem = path.basename(file, ext);
+      // A `name@640.jpg` file IS a variant (the author's, or one a previous
+      // run was asked to leave alone) — never treated as a source.
+      if (/@\d+$/.test(stem)) continue;
+      const rel = path.relative(paths.routesRoot, file);
+      if (hasHiddenPathSegment(rel) || fs.lstatSync(file).isSymbolicLink()) continue;
+      /** @type {Uint8Array} */
+      let bytes;
+      try {
+        bytes = fs.readFileSync(file);
+      } catch {
+        hint(`no responsive variants for ${relPosix(paths, file)} — the file could not be read.`);
+        continue;
+      }
+      const intrinsic = imageSize(bytes);
+      if (!intrinsic) {
+        hint(
+          `no responsive variants for ${relPosix(paths, file)} — its dimensions could not be read ` +
+            "(corrupt or unsupported image). The original ships as-is."
+        );
+        continue;
+      }
+      if (intrinsic.width <= SMALL_IMAGE_MAX_WIDTH) continue;
+      const hash = crypto.createHash("sha256").update(bytes).digest("hex").slice(0, 24);
+      const targets = widths.filter(
+        (w) =>
+          w < intrinsic.width && !fs.existsSync(path.join(path.dirname(file), `${stem}@${w}${ext}`))
+      );
+      if (targets.length === 0) continue;
+      /** @type {"jpeg" | "png" | "webp"} */
+      const format = ext === ".png" ? "png" : ext === ".webp" ? "webp" : "jpeg";
+      for (const width of targets) {
+        const cacheFile = path.join(cacheDir, `${hash}@${width}${ext}`);
+        const distOut = path.join(paths.distRoot, path.dirname(rel), `${stem}@${width}${ext}`);
+        if (fs.existsSync(cacheFile)) {
+          emitVariant(file, width, cacheFile, distOut);
+          stats.cached++;
+        } else {
+          const job = { source: file, out: cacheFile, width, format };
+          pending.push(job);
+          waiting.push({ job, distOut });
+          if (!needingSharp.includes(relPosix(paths, file)))
+            needingSharp.push(relPosix(paths, file));
+        }
+      }
+    }
+  }
+
+  if (pending.length > 0) {
+    const result = runJobs(pending);
+    if (result.unavailable) {
+      stats.unavailable = true;
+      hint(
+        `${needingSharp.length} image${needingSharp.length === 1 ? "" : "s"} could gain responsive ` +
+          `variants (${needingSharp.join(", ")}). Run \`npm i -D sharp\` to generate them at build time.`
+      );
+    } else {
+      const failed = new Map(result.failed.map((f) => [`${f.file}@${f.width}`, f.error]));
+      for (const { job, distOut } of waiting) {
+        const error = failed.get(`${job.source}@${job.width}`);
+        if (error !== undefined) {
+          hint(
+            `no ${job.width}px variant for ${relPosix(paths, job.source)} — sharp failed: ${error}. ` +
+              "The image ships without that variant."
+          );
+          continue;
+        }
+        emitVariant(job.source, job.width, job.out, distOut);
+        stats.generated++;
+      }
+    }
+  }
+
+  for (const list of variants.values()) list.sort((a, b) => a - b);
+  return { variants, ...stats };
+}
+
+/**
+ * The default resize seam: run every pending job in ONE child process (the
+ * build is synchronous; sharp is not), communicating through temp JSON files
+ * rather than stdio so a large job list never hits a pipe buffer. The worker
+ * always writes a results file — a missing or unparsable one means the child
+ * itself died, which is reported as `unavailable` (the build then behaves as
+ * if sharp were absent: a hint, no variants, no failure).
+ * @param {ResizeJob[]} jobs
+ * @param {(cmd: string, args: string[], opts: object) => unknown} [spawn]
+ *   Injectable for tests; the real one is `spawnSync`.
+ * @returns {ResizeResult}
+ */
+export function runResizeJobs(jobs, spawn = /** @type {any} */ (spawnSync)) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "wd-img-variants-"));
+  try {
+    const jobsFile = path.join(dir, "jobs.json");
+    const resultsFile = path.join(dir, "results.json");
+    fs.writeFileSync(jobsFile, JSON.stringify(jobs));
+    spawn(process.execPath, [WORKER_PATH, jobsFile, resultsFile], {
+      stdio: ["ignore", "ignore", "inherit"]
+    });
+    if (!fs.existsSync(resultsFile)) return { unavailable: true, failed: [] };
+    try {
+      return JSON.parse(fs.readFileSync(resultsFile, "utf8"));
+    } catch {
+      return { unavailable: true, failed: [] };
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * A project-relative, POSIX-separated path for hint messages.
+ * @param {Paths} paths
+ * @param {string} file Absolute path.
+ * @returns {string}
+ */
+function relPosix(paths, file) {
+  return path.relative(paths.cwd, file).replaceAll(path.sep, "/");
+}
+
+/**
+ * Match the router's (and `emitPageAssets`') hidden-path convention: anything
+ * below a `.`, `-`, or `_` segment is private framework input, not public
+ * output — variants for it would never be served, so it is not scanned.
+ * @param {string} rel
+ * @returns {boolean}
+ */
+function hasHiddenPathSegment(rel) {
+  return rel.split(path.sep).some((segment) => /^[._-]/.test(segment));
+}
+
+/**
+ * All files under `dir`, recursively. Mirrors the builder's own walker; kept
+ * local so this module does not import the builder (which imports this).
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walk(dir) {
+  /** @type {string[]} */
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(abs));
+    else files.push(abs);
+  }
+  return files;
+}

package/src/statics.js

@@ -2,14 +2,16 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 import zlib from "node:zlib";
-import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
+import { BASE_SECURITY_HEADERS, REACTIVE_CSP, routeCsp } from "./headers.js";
 
 /**
  * The security headers (including the right CSP variant) for an HTML response.
  * Mirrors what production ships. Since 2.1 both variants are eval-free (the
  * reactive runtime walks a validated AST, not `new Function`), so a reactive and a
- * static route resolve to the same CSP — the per-route selection is kept for parity
- * with the `_headers` / `vercel.json` structure the same build writes. Anything not
+ * static route resolve to the same base CSP — the per-route selection is kept for
+ * parity with the `_headers` / `vercel.json` structure the same build writes, and
+ * it is what lets a route's own `:embed` hosts (recorded on its manifest entry as
+ * `assets.embedHosts`) widen `frame-src` for exactly that route. Anything not
  * found in `routes.json` (an unknown route, a 404, a missing manifest) falls back
  * to the reactive CSP, exactly like the production `_headers` catch-all block.
  * @param {string} distRoot Absolute path to the build output directory.
@@ -17,9 +19,12 @@ import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
  * @returns {Record<string, string>}
  */
 function htmlSecurityHeaders(distRoot, url) {
+  const entry = routeEntry(distRoot, routeOf(url));
   return {
     ...BASE_SECURITY_HEADERS,
-    "Content-Security-Policy": routeIsReactive(distRoot, routeOf(url)) ? REACTIVE_CSP : STATIC_CSP
+    "Content-Security-Policy": entry
+      ? routeCsp(Boolean(entry.assets?.runtime), entry.assets?.embedHosts ?? [])
+      : REACTIVE_CSP
   };
 }
 
@@ -43,24 +48,23 @@ function routeOf(url) {
 }
 
 /**
- * Whether the route ships the reactive runtime, per the build's `routes.json`.
- * Defaults to `true` (reactive) when the route is absent or the manifest can't be
- * read — matching the production `_headers` catch-all, so an unknown route is
- * never accidentally served the stricter policy.
+ * The route's own manifest entry from the build's `routes.json`, or null when
+ * the route is absent or the manifest can't be read — in which case the caller
+ * falls back to the reactive CSP, matching the production `_headers` catch-all,
+ * so an unknown route is never accidentally served the stricter policy.
  * @param {string} distRoot
  * @param {string | null} route
- * @returns {boolean}
+ * @returns {{ route: string, assets?: { runtime?: boolean, embedHosts?: string[] } } | null}
  */
-function routeIsReactive(distRoot, route) {
-  if (!route) return true;
+function routeEntry(distRoot, route) {
+  if (!route) return null;
   try {
     const manifest = JSON.parse(fs.readFileSync(path.join(distRoot, "routes.json"), "utf8"));
-    const entry = manifest.find((/** @type {{ route: string }} */ e) => e.route === route);
-    if (entry) return Boolean(entry.assets?.runtime);
+    return manifest.find((/** @type {{ route: string }} */ e) => e.route === route) ?? null;
   } catch {
     /* no/unreadable manifest → reactive default (the catch-all policy) */
+    return null;
   }
-  return true;
 }
 
 /**
@@ -256,6 +260,10 @@ export function resolvePublicFile(distRoot, url) {
   } catch {
     return null;
   }
+  // A decoded NUL (%00) is a valid string here but every fs call on the
+  // resulting path throws ERR_INVALID_ARG_VALUE out of the request handler,
+  // killing the server. It can never name a built file, so it is a miss.
+  if (cleanUrl.includes("\0")) return null;
   const base = cleanUrl.startsWith("/__wd/")
     ? cleanUrl
     : path.join(cleanUrl, path.extname(cleanUrl) ? "" : "index.html");

package/types/builder.d.ts

@@ -53,6 +53,12 @@ export function stripRuntimeComments(source: string): string;
  *
  * 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}
  */
@@ -68,7 +74,10 @@ export function renderCloudflareHeaders(manifest: RouteManifestEntry[]): string;
  * @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.
  */
 /**
  * One source route's record in the dev dependency map (`dist/.wd-dev-deps.json`),
@@ -98,6 +107,24 @@ export type BuildResult = {
         sitemap: number | null;
         rss: number | null;
     };
+    /**
+     *   Responsive-variant pre-pass counts (2.9.0): freshly resized, cache-served,
+     *   and whether sharp could not be loaded at all.
+     */
+    images: {
+        generated: number;
+        cached: number;
+        unavailable: boolean;
+    };
+    /**
+     *   Font-subset post-pass counts (2.10.0): freshly subsetted, cache-served, and
+     *   whether harfbuzzjs/wawoff2 could not be loaded at all.
+     */
+    fonts: {
+        subsetted: number;
+        cached: number;
+        unavailable: boolean;
+    };
     incremental?: {
         changed: string[];
         rebuilt: string[];
@@ -159,10 +186,16 @@ export type RouteManifestEntry = {
      * Source file path, relative to cwd, POSIX-separated.
      */
     file: string;
+    /**
+     *   `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.
+     */
     assets: {
         skins: string[];
         scripts: string[];
         runtime: boolean;
+        embedHosts?: string[];
     };
 };
 /**

package/types/catalog.d.ts

@@ -107,9 +107,10 @@ export type DirectiveEntry = {
      */
     name: string;
     /**
-     * A single line, or an opener with a closer.
+     * A single line, an opener with a
+     * closer, or a line that may optionally open a block (`@include … @endinclude`).
      */
-    kind: "line" | "block";
+    kind: "line" | "block" | "either";
     /**
      * One-line schematic (`[…]` = optional, `<…>` = slot).
      */

package/types/compiler/context.d.ts

@@ -26,6 +26,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).
  */
 /**
  * The pagination intent a `@loop … paginate N` records during compile, so the
@@ -66,6 +72,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
@@ -124,6 +135,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`, `:::`,
@@ -405,6 +421,15 @@ export type Assets = {
      * subtree; the HTML stamp uses them to scope the matching page/include subtree.
      */
     scopedSkins: Set<string>;
+    /**
+     * 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).
+     */
+    embedHosts: Set<string>;
 };
 /**
  * The pagination intent a `@loop … paginate N` records during compile, so the
@@ -488,6 +513,14 @@ export type Compilation = {
      * `ctx.comp.reader` in the directive handlers (includes, loop data).
      */
     reader: import("./reader.js").Reader;
+    /**
+     * 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.
+     */
+    imageVariants: Map<string, number[]> | null;
     /**
      * Every declared thing this compile saw, in source
      * order, recorded by {@link recordSymbol} from the handler that parsed it.
@@ -617,6 +650,14 @@ export type Ctx = {
      * Inside a loop body, so `$index`/`$first`/… are valid.
      */
     loopMeta?: boolean | undefined;
+    /**
+     * 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).
+     */
+    includeBlockDepth?: number | undefined;
     /**
      * Markdown-it instance selected for this file.
      */

package/types/compiler/includes.d.ts

@@ -101,6 +101,15 @@ export function resolveInclude(spec: string, fromFile: string, context: Paths, a
  * @returns {boolean}
  */
 export function isAllowedInclude(file: string, context: Paths, reader?: import("./reader.js").Reader): boolean;
+/**
+ * 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: import("./context.js").Ctx): string | null;
 /**
  * Warn when a plain `.md` file contains `.wd`-only syntax that stays inert.
  * @param {string} body
@@ -109,6 +118,20 @@ export function isAllowedInclude(file: string, context: Paths, reader?: import("
  * @returns {void}
  */
 export function scanMarkdownHints(body: string, file: string, comp: Compilation): void;
+/**
+ * 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: RegExp;
 export type Paths = import("./context.js").Paths;
 export type Assets = import("./context.js").Assets;
 export type Compilation = import("./context.js").Compilation;

package/types/compiler/page.d.ts

@@ -2,7 +2,7 @@
  * 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
@@ -10,7 +10,8 @@
  *   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: string, context: Paths, options?: {
@@ -22,6 +23,7 @@ export function compilePage(file: string, context: Paths, options?: {
     collections?: Map<string, import("./collections.js").CollectionRow[]>;
     vars?: Record<string, unknown>;
     reader?: import("./reader.js").Reader;
+    imageVariants?: Map<string, number[]> | null;
 }): CompiledPage;
 /**
  * Harden every `<img>` in the assembled page body — compile-time only, zero
@@ -47,9 +49,13 @@ export function enhanceImages(html: string, paths: Paths, reader: import("./read
  *   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(file: string, context: Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./collections.js").CollectionRow[]>, reader?: import("./reader.js").Reader): CompiledDocument;
+export function compileDocument(file: string, context: Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./collections.js").CollectionRow[]>, reader?: import("./reader.js").Reader, imageVariants?: Map<string, number[]> | null): CompiledDocument;
 /**
  * Compile a single file: parse frontmatter, collect assets, render body.
  * @param {string} file