@zvndev/darkmown 2.8.0 → 2.9.0

package/AGENTS.md

@@ -41,7 +41,7 @@ package.json
 - Files/folders starting with `.`, `-`, or `_` are **hidden** from routing (drafts, partials).
 - A `page.skin` next to `page.wd` attaches styling; a `page.js` attaches behavior. Matched by basename.
 - **Colocated assets:** any other file under `site/pages/` (not a `.md`/`.wd` route, not a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type — so `site/pages/logo.svg` is served at `/logo.svg`. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
-- **Responsive image variants:** export pre-sized copies next to the source image, same directory, same extension, `@<width>` before it (`dr-x@640.webp`, `dr-x@1280.webp`), and a Markdown image gains a `srcset` automatically, the original kept as `src`. Widths are MEASURED from file headers (a `@640` file really holding 600px emits `600w`; the filename is only a fallback), candidates sort ascending, and discovery probes a fixed width list (64 through 3840: 64, 96, 128, 160, 256, 320, 480, 640, 768, 960, 1024, 1280, 1440, 1536, 1920, 2048, 2560, 3840), so an off-list width is a documented miss, never an error. `sizes` is never emitted (write raw `<img srcset sizes>` on an `html: true` page for that). Never wired: bound srcs (`![a]({ photo })`), remote/`data:` sources, query/hash srcs, page-relative or extensionless srcs, and raw-HTML `<img>` tags. Variant files are ordinary colocated assets (they copy to `dist/`, never routes); shelf images resolve variants against `/__wd/media/`. The first image on the page stays eager with `fetchpriority="high"`, the rest lazy-load, and author-set attributes always win. `.md` pages get the width/height/lazy hardening but no srcset.
+- **Responsive image variants:** with sharp installed (`npm i -D sharp`, an optional dependency; builds work without it), the build scans `site/pages` for raster photos (jpg/jpeg/png/webp) over 700px wide and writes resized `name@640.ext` / `name@1280.ext` variants into `dist`, wiring a `srcset` onto the Markdown image with the original kept as `src`. Only widths below the intrinsic size are generated (never upscale), variants keep the source format, and EXIF orientation is applied. **Author-provided `name@<width>.ext` exports win per width**: your file is copied verbatim and measured from its own header (a `@640` file holding 600px emits `600w`), and generation fills only the uncovered widths; other sizes are hand exports on the probe list (64, 96, 128, …, 3840). Skipped silently: images ≤700px, `@width` files, hidden/symlinked paths, svg/gif/avif, and shelf images (the generator covers page-colocated images only). Without sharp the build behaves as before plus one `npm i -D sharp` hint per build; a corrupt image or a sharp failure on one file is a hint naming the file, never a build failure. Resizes cache in `node_modules/.cache/darkmown-images/` (content hash + width + format), so rebuilds and dev reloads do zero sharp work for unchanged images. Never wired: bound srcs (`![a]({ photo })`), remote/`data:`/query-hash srcs, page-relative or extensionless srcs, and raw-HTML `<img>` tags; `sizes` is never emitted (raw `<img srcset sizes>` on an `html: true` page is the way). `.md` pages get the width/height/lazy hardening but no srcset. The first image on the page stays eager with `fetchpriority="high"`, the rest lazy-load, and author-set attributes always win.
 - Shelf `.json` files publish to `/__wd/data/<name>`; every other shelf file publishes to `/__wd/media/<path>`.
 
 Commands: `darkmown dev`, `darkmown build [--drafts]`, `darkmown validate` (compile-check without writing `dist`), `darkmown serve` (previews `dist`, runs `api/` functions like dev, and compresses text responses), `darkmown deploy <vercel|cloudflare>`, `darkmown catalog [--llms|--llms-full]`.

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.9.0 (2026-10-13)
+
+- **Authoring/Assets: responsive image variants are generated at build time.** With [sharp](https://sharp.pixelplumbing.com/) installed (`npm i -D sharp`, declared as an `optionalDependency`, so `dependencies` stays empty and every build works without it), the builder scans `site/pages` for raster photos (jpg/jpeg/png/webp) wider than 700px and writes resized `name@640.ext` / `name@1280.ext` siblings into `dist`, handing the compiler a variant map that wires the `srcset` exactly like author-provided variants: the original stays the `src` fallback and joins the srcset at its intrinsic width. Only widths below the intrinsic size are generated (never upscale), variants keep the source format (webp and jpeg at quality 82, jpeg progressive; png stays png at maximum compression), and EXIF orientation is applied before resizing, so rotated phone photos come out upright. **BEHAVIOR CHANGE: a build with sharp installed now generates variants automatically** where before it shipped the original alone; **without sharp, nothing changes** except one hint per build naming the images that could gain variants (`Run npm i -D sharp to generate them at build time.`). The 2.8.0 `@width` convention becomes the override: an author-provided `name@640.ext` is copied verbatim, measured from its own header, and never overwritten, and generation fills only the widths the author left uncovered. Skipped silently: images at or under 700px, `@width` files themselves, hidden and symlinked paths, svg/gif/avif, and shelf images under `site/_`. A corrupt image (dimensions unreadable) or a sharp failure on one file prints a hint naming that file; the build never fails because of an image. Resizes cache in `node_modules/.cache/darkmown-images/` keyed by content hash + width + format (already gitignored with `node_modules`), so a second build does zero sharp work and a fully cached build never loads sharp; dev rebuilds recompute the variant map from the cache, and changing an image forces a full rebuild, exactly as before. The build summary gains an `image variants (N generated, M cached)` clause whenever variants materialized. The build is synchronous and sharp is not, so the resizes run in one child process per build, and a fully cached build spawns nothing.
+
 ## 2.8.0 (2026-10-13)
 
 A release from a real client-site rebuild: a 67-route marketing site rebuilt in Darkmown, with every friction point the rebuild reported either fixed or written down as a recipe. The `.skin` language learned `@font-face` and `@keyframes`, frontmatter gained favicon, shared-skin, and discovery opt-out keys, format pipes now fold inside raw HTML, and `darkmown serve` reached parity with dev for `api/` functions while adding response compression. One deliberate behavior change (the stylesheet cascade order) is called out below with its migration note. Three new error codes (`WD017`, `WD706`, `WD707`), no breaking API change.

package/README.md

@@ -215,21 +215,23 @@ Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`
 
 **Images are hardened at compile time.** Every `<img>` the compiler emits is stamped with its intrinsic `width`/`height` (read from the source file, so the browser reserves space and the page doesn't reflow as images decode), `decoding="async"`, and a load-priority split — the first image on the page stays eager with `fetchpriority="high"` (the LCP candidate), the rest get `loading="lazy"`. Author-set attributes always win, and remote or unreadable sources just skip the dimensions. The compiler **measures**, it doesn't resize — keep source images web-sized (modern formats, sensible dimensions).
 
-**Responsive variants via the `@width` convention.** Darkmown still resizes nothing, but it wires the variants you already exported. Put pre-sized copies next to the source, same directory, same extension, `@<width>` before it (`dr-x.webp` beside `dr-x@640.webp` and `dr-x@1280.webp`), and a Markdown image gains a `srcset` with the original kept as `src`:
+**Responsive variants, generated at build time.** Drop one photo into `site/pages` and the build does the rest: with [sharp](https://sharp.pixelplumbing.com/) installed (`npm i -D sharp`, an optional dependency; every build works without it), each raster image large enough to matter is resized to the default widths **640 and 1280**, written into `dist/` as `name@<width>.ext` siblings, and the Markdown image that references the original gains a `srcset`:
 
 ```html
-<img src="/doctors/dr-x.webp" alt="Dr X"
-     srcset="/doctors/dr-x@640.webp 600w, /doctors/dr-x@1280.webp 1280w, /doctors/dr-x.webp 2400w"
+<img src="/doctors/dr-aurora.jpg" alt="Dr. Aurora"
+     srcset="/doctors/dr-aurora@640.jpg 640w, /doctors/dr-aurora@1280.jpg 1280w, /doctors/dr-aurora.jpg 2400w"
      width="2400" height="1600" decoding="async" fetchpriority="high">
 ```
 
-- **Descriptor widths are measured, not parsed from the filename.** Each variant's intrinsic width is read from its file header (PNG/JPEG/GIF/WebP/SVG), so a file named `@640` that really holds 600px emits `600w`; the filename width is only the fallback when the bytes cannot be read. The original joins the srcset at its intrinsic width when that can be measured, and all candidates sort ascending, so an original narrower than a variant sorts between them.
-- **Discovery probes a fixed width list** (64, 96, 128, 160, 256, 320, 480, 640, 768, 960, 1024, 1280, 1440, 1536, 1920, 2048, 2560, 3840) through existence checks rather than a directory listing, which is what lets `compileFromMemory` resolve the convention from its in-memory map too. An off-list width like `x@500.webp` is a documented miss: never wired, never an error.
-- **`sizes` is never emitted.** The inline-attribute syntax on images carries only classes and ids, so there is no way to supply `sizes` in Markdown, and the compiler will not invent one. An author who needs `sizes` writes raw `<img srcset sizes>` on an `html: true` page.
-- **Never wired, by design:** a bound src (`![a]({ photo })` or a loop row's `![a]({ p.photo })`, which the runtime repaints and a build-time srcset would contradict), remote (`https://`, protocol-relative) and `data:` sources, srcs with a query/hash, page-relative or extensionless srcs, and raw-HTML `<img>` tags (author territory). With no variant present, the emitted tag is byte-identical to before the feature.
-- Variant files are ordinary colocated assets: they copy to `dist/` at their own path like any image, and an `@`-suffixed filename is never a route. Shelf images work too: variants beside `site/_/team/x.webp` resolve against the `/__wd/media/` public path.
-- The srcset composes with the load-priority split above: the first image stays eager with `fetchpriority="high"`, later variant-wired images get `loading="lazy"`, and author-set `loading`/`decoding`/`fetchpriority`/`width`/`height` are never overwritten.
-- **`.md` caveat:** variant wiring runs in the `.wd` compile path. A plain `.md` page still gets the width/height/lazy hardening but no srcset.
+- **Only widths below the intrinsic size are generated (never upscale)**, and variants keep the source format: webp re-encodes at quality 82, jpeg at quality 82 progressive, png stays png. EXIF orientation is applied before resizing, so rotated phone photos come out upright. (The build is synchronous and sharp is not, so the resizes run in one child process per build; a fully cached build spawns nothing.)
+- **Skipped silently:** images at or under 700px wide (already small everywhere), `name@<width>.ext` files themselves (output, never sources), hidden path segments (`.`, `-`, `_`) and symlinks (matching what the build publishes), and formats that are not resized (svg, gif, avif). The generator scans `site/pages` only; shelf images under `site/_` are not resized, though author-provided shelf variants still wire through the convention below.
+- **Without sharp, the build behaves exactly as before plus one hint per build:** `hint: 5 images could gain responsive variants (site/pages/carousel/slide-1.jpg, ...). Run npm i -D sharp to generate them at build time.` A corrupt image (dimensions unreadable) or a sharp failure on one file prints a hint naming that file, and that image ships without variants; the build never fails because of an image.
+- **Resizes are cached in `node_modules/.cache/darkmown-images/`**, keyed by content hash + width + format. A second build does zero sharp work for unchanged images and does not even load sharp when everything is cached (cached variants ship even if sharp is later removed). The cache lives under `node_modules`, which every project's `.gitignore` already excludes. Dev rebuilds recompute the variant map from the cache (no sharp spawn), so a partially rebuilt page is byte-identical to a full rebuild, srcset included; changing an image itself forces a full rebuild, which re-runs the pre-pass.
+- The build summary reports the pre-pass when variants materialized: `Built 14 routes, sitemap (14 urls), rss (6 posts), image variants (2 generated, 5 cached) into dist`.
+
+**Author-provided variants win (the `@width` convention).** Export `dr-aurora@640.jpg` yourself, same directory, same extension, and the build does not touch that width: your file is copied verbatim and measured from its own header (a `@640` file really holding 600px emits `600w`). Generation fills only the widths you did not provide, and the convention picks up any width on the compiler's fixed probe list (64, 96, 128, …, 3840), so other sizes are a hand export away; an off-list width like `x@500.webp` is a documented miss, never an error. Variant files (yours or generated) are ordinary colocated assets: they copy to `dist/` at their own path, and an `@`-suffixed filename is never a route. Everything else about the wiring is unchanged: descriptor widths are measured from file headers, candidates sort ascending with the original joining at its intrinsic width, `sizes` is never emitted (write raw `<img srcset sizes>` on an `html: true` page for that), and a page with no resizable images emits exactly what it did before.
+
+**Never wired, by design:** a bound src (`![a]({ photo })` or a loop row's `![a]({ p.photo })`, which the runtime repaints), remote (`https://`, protocol-relative) and `data:` sources, srcs with a query/hash, page-relative or extensionless srcs, and raw-HTML `<img>` tags. **`.md` caveat:** variant wiring runs in the `.wd` compile path, so a plain `.md` page gets the width/height/lazy hardening but no srcset.
 
 **Or colocate an asset next to the page that uses it.** Any non-page file under `site/pages/` (anything but `.md`/`.wd` routes and the colocated `.skin`/`.js`) is copied to `dist/` at its own path, so a clean relative URL just works:
 
@@ -357,7 +359,7 @@ draft: true
 
 Drafts are filtered at one point — route discovery — so nothing downstream ever sees them. This is **separate from** the permanent `.`/`-`/`_` filename hiding: a hidden name (`-notes.wd`) is private forever; `draft:` is a toggle you flip when the page is ready to ship.
 
-The `build` summary reports what it emitted: `Built 14 routes, sitemap (14 urls), rss (6 posts) into dist`.
+The `build` summary reports what it emitted: `Built 14 routes, sitemap (14 urls), rss (6 posts) into dist`, with an `image variants (2 generated, 5 cached)` clause appended whenever the image pre-pass produced or served cached responsive variants (see [Static assets](#static-assets)).
 
 ## Loops
 

package/docs/spec-alignment.md

@@ -2,6 +2,10 @@
 
 This audit compares the current Darkmown implementation with the original MARROW/WhateverDown vision and the follow-up decisions made on 2026-06-11.
 
+## 2.9.0 additions (unreleased, 2026-10-13)
+
+- **The framework now makes the image variants itself, closing the rebuild's largest asset gap.** With the optional sharp dependency installed, `darkmown build` resizes page-colocated raster photos over 700px into 640/1280 `name@width.ext` siblings (never upscaling, EXIF-aware, cached by content hash under `node_modules/.cache/darkmown-images/` so rebuilds and dev reloads do no sharp work), the 2.8.0 author-provided `@width` convention stays the per-width override, and a build without sharp behaves exactly like 2.8.0 plus one hint.
+
 ## 2.8.0 additions: the client-site rebuild release (2026-10-13)
 
 A 67-route marketing site rebuilt in Darkmown produced a friction report, and this release is the report answered: every item either became a feature, a coded error, or a documented recipe. Nothing in it moves the core thesis; it rounds out the authoring surface a real design system needs while keeping static pages zero-JS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -88,6 +88,7 @@
     "esbuild": "0.28.2",
     "husky": "^9.1.7",
     "lint-staged": "^17.0.0",
+    "sharp": "^0.35.5",
     "typescript": "^6.0.3"
   },
   "repository": {
@@ -107,5 +108,8 @@
     "zero-js",
     "reactive"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "optionalDependencies": {
+    "sharp": "^0.35.5"
+  }
 }

package/site/pages/docs/index.wd

@@ -441,7 +441,7 @@ Add `transitions: true` to a page's frontmatter for **instant, flash-free naviga
 
 You don't size images by hand. Every `<img>` the compiler emits gets its intrinsic `width`/`height` read from the source file (so the page doesn't reflow as images decode), `decoding="async"`, and a priority split — the first image stays eager with `fetchpriority="high"`, the rest `loading="lazy"`. Anything you set yourself wins. The compiler measures, it doesn't resize, so keep source images web-sized.
 
-**Responsive variants.** Export pre-sized copies next to the source, same directory, same extension, `@<width>` before it (`dr-x@640.webp`, `dr-x@1280.webp`), and a Markdown image gains a `srcset` with the original kept as `src`. Descriptor widths are measured from the file headers (a `@640` file really holding 600px emits `600w`), candidates sort ascending, and the original joins at its intrinsic width. Discovery probes a fixed list of common widths (64 through 3840) rather than reading the directory, so an off-list width is a documented miss, never an error. `sizes` is never emitted; write raw `<img srcset sizes>` on an `html: true` page when you need one. Bound (`![a]({ photo })`), remote, `data:`, query/hash, page-relative, and extensionless srcs are never wired, and neither are raw-HTML `<img>` tags. Variant files are ordinary colocated assets: they copy to `dist/` and are never routes, and shelf images resolve variants against `/__wd/media/`. A `.md` page gets the hardening but no srcset.
+**Responsive variants, generated at build time.** With sharp installed (`npm i -D sharp`, an optional dependency; builds work without it), every raster photo in `site/pages` over 700px wide is resized to 640w and 1280w siblings in `dist/` (only widths below the intrinsic size, never upscaled, EXIF orientation applied), and the Markdown image gains a `srcset` with the original kept as `src`. Export `name@<width>.ext` yourself and your file wins that width verbatim, measured from its own header; generation fills only the widths you left uncovered, and other sizes are a hand export away (the compiler probes 64 through 3840). Skipped silently: small images, `@width` files, hidden or symlinked paths, svg/gif/avif, and shelf images (the generator covers page-colocated images only). Without sharp the build behaves as before plus one `npm i -D sharp` hint per build; a corrupt image or a sharp failure on one file is a hint naming the file, never a build failure. Resizes are cached in `node_modules/.cache/darkmown-images/` by content hash + width + format, so second builds and dev rebuilds do no resizing for unchanged images, and the build summary reports `image variants (N generated, M cached)` when variants materialized. `sizes` is never emitted (write raw `<img srcset sizes>` on an `html: true` page for that); bound (`![a]({ photo })`), remote, `data:`, query/hash, page-relative, and extensionless srcs are never wired, and neither are raw-HTML `<img>` tags. A `.md` page gets the hardening but no srcset.
 
 ## Static assets
 

package/src/builder.js

@@ -21,6 +21,7 @@ import {
 } from "./feeds.js";
 import { BASE_SECURITY_HEADERS, REACTIVE_CSP, STATIC_CSP } from "./headers.js";
 import { HIGHLIGHT_CSS } from "./highlight.js";
+import { generateImageVariants } from "./image-variants.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
 import { compileSkin, scopeIdFor } from "./skin.js";
 
@@ -105,6 +106,9 @@ export function buildSite(cwd = process.cwd(), options = {}) {
  * @property {RouteManifestEntry[]} routes
  * @property {string} distRoot
  * @property {{ sitemap: number | null, rss: number | null }} feeds
+ * @property {{ generated: number, cached: number, unavailable: boolean }} images
+ *   Responsive-variant pre-pass counts (2.9.0): freshly resized, cache-served,
+ *   and whether sharp could not be loaded at all.
  * @property {{ changed: string[], rebuilt: string[], total: number }} [incremental]
  */
 
@@ -119,6 +123,12 @@ function buildFull(cwd, paths, options) {
   fs.rmSync(paths.distRoot, { recursive: true, force: true });
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
+  // Responsive image variants (2.9.0): resize the large raster photos in
+  // site/pages into dist and collect the variant map BEFORE any route compiles,
+  // so the srcset wiring can reference what was generated. With the optional
+  // sharp dependency absent (or everything cache-served) this is cheap and
+  // never fails the build.
+  const images = generateImageVariants(paths, { quiet: options.quietFeedHints });
   const routes = discoverRoutes(paths.routesRoot, { includeDrafts: options.includeDrafts });
   // Build the collection index from the (post-draft-filter) routes — every
   // site/pages/<name>/ subdirectory's entries become queryable rows a bare-name
@@ -152,7 +162,17 @@ function buildFull(cwd, paths, options) {
   const mapRoutes = {};
 
   for (const route of routes) {
-    const built = buildRoute(route, cwd, paths, collections, feedLink, warned, identity, titles);
+    const built = buildRoute(
+      route,
+      cwd,
+      paths,
+      collections,
+      feedLink,
+      warned,
+      identity,
+      titles,
+      images.variants
+    );
     manifest.push(...built.mapEntry.pages);
     if (built.notFoundHtml !== undefined) notFoundHtml = built.notFoundHtml;
     for (const entry of built.mapEntry.pages) {
@@ -192,7 +212,12 @@ function buildFull(cwd, paths, options) {
 
   if (options.depMap) writeDepMap(paths, feedLink, siteInputs(identity, titles), mapRoutes);
 
-  return { routes: manifest, distRoot: paths.distRoot, feeds };
+  return {
+    routes: manifest,
+    distRoot: paths.distRoot,
+    feeds,
+    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable }
+  };
 }
 
 /**
@@ -284,13 +309,30 @@ function buildIncremental(cwd, paths, options, changed) {
     }
   }
 
+  // Rebuilt routes must compile byte-identically to a full rebuild, so the
+  // generated-variant map the srcset wiring consults is recomputed here too.
+  // An image CHANGE never reaches this point (no dependency graph tracks
+  // images, so it already forced a full rebuild above), which makes this scan
+  // all cache hits: it refreshes dist copies and the map, and spawns nothing.
+  const images = generateImageVariants(paths, { quiet: options.quietFeedHints });
+
   const byRoute = new Map(routes.map((route) => [route.route, route]));
   /** @type {Set<string>} */
   const warned = new Set();
   const rebuilt = [...affected].sort();
   for (const routePath of rebuilt) {
     const route = /** @type {Route} */ (byRoute.get(routePath));
-    const built = buildRoute(route, cwd, paths, collections, feedLink, warned, identity, titles);
+    const built = buildRoute(
+      route,
+      cwd,
+      paths,
+      collections,
+      feedLink,
+      warned,
+      identity,
+      titles,
+      images.variants
+    );
     // A shrunk pagination leaves stale `/page/N/` outputs behind — remove any
     // previously-emitted page this rebuild no longer produces.
     const kept = new Set(built.mapEntry.pages.map((entry) => entry.route));
@@ -326,6 +368,7 @@ function buildIncremental(cwd, paths, options, changed) {
     routes: manifest,
     distRoot: paths.distRoot,
     feeds,
+    images: { generated: images.generated, cached: images.cached, unavailable: images.unavailable },
     incremental: { changed, rebuilt, total: routes.length }
   };
 }
@@ -344,10 +387,30 @@ function buildIncremental(cwd, paths, options, changed) {
  * @param {SiteIdentity} identity Resolved site identity (its `siteUrl` is what
  *   makes a canonical URL possible).
  * @param {Map<string, string>} titles Route path → page title, for breadcrumbs.
+ * @param {Map<string, number[]>} imageVariants Generated responsive variants
+ *   (original's absolute source path → widths), threaded into each compile.
  * @returns {{ mapEntry: DepMapEntry, notFoundHtml: string | undefined }}
  */
-function buildRoute(route, cwd, paths, collections, feedLink, warned, identity, titles) {
-  const compiled = compileRoutePages(route, paths, collections, feedLink, identity, titles);
+function buildRoute(
+  route,
+  cwd,
+  paths,
+  collections,
+  feedLink,
+  warned,
+  identity,
+  titles,
+  imageVariants
+) {
+  const compiled = compileRoutePages(
+    route,
+    paths,
+    collections,
+    feedLink,
+    identity,
+    titles,
+    imageVariants
+  );
   /** @type {RouteManifestEntry[]} */
   const entries = [];
   /** @type {string | undefined} */
@@ -694,9 +757,11 @@ function copyChangedAsset(file, cwd, paths) {
  * @param {{ href: string, title: string } | undefined} feedLink
  * @param {SiteIdentity} identity
  * @param {Map<string, string>} titles Route path → page title, for breadcrumbs.
+ * @param {Map<string, number[]>} imageVariants Generated responsive variants
+ *   (original's absolute source path → widths) for the srcset wiring.
  * @returns {{ pages: EmittedPage[], deps: Set<string>, collections: Set<string> }}
  */
-function compileRoutePages(route, paths, collections, feedLink, identity, titles) {
+function compileRoutePages(route, paths, collections, feedLink, identity, titles, imageVariants) {
   /** @type {Set<string>} */
   const deps = new Set();
   /** @type {Set<string>} */
@@ -721,7 +786,8 @@ function compileRoutePages(route, paths, collections, feedLink, identity, titles
     feed: feedLink,
     site: siteFor(route.route),
     collections,
-    vars: { page: pagerVars(route.route, 1, 1) }
+    vars: { page: pagerVars(route.route, 1, 1) },
+    imageVariants
   });
   track(first);
   if (!first.pagination || first.pagination.total <= 1) {
@@ -746,7 +812,8 @@ function compileRoutePages(route, paths, collections, feedLink, identity, titles
       feed: feedLink,
       site: siteFor(pageRoute(route.route, n)),
       collections,
-      vars: { page: pagerVars(route.route, n, total) }
+      vars: { page: pagerVars(route.route, n, total) },
+      imageVariants
     });
     track(page);
     pages.push({

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 } }} result
  * @param {string} relativeRoot `dist` relative to cwd, for the message tail.
  * @returns {string}
  */
@@ -617,6 +617,12 @@ 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)`
+    );
+  }
   return `${parts.join(", ")} into ${relativeRoot}`;
 }
 

package/src/compiler/context.js

@@ -81,6 +81,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
@@ -290,6 +295,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(),

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/page.js

@@ -45,7 +45,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 +53,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
@@ -434,6 +443,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 +455,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,

package/src/compiler.js

@@ -43,7 +43,7 @@ export {
  * a different source (see `compileFromMemory`).
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {import("./config.js").Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
  * @returns {CompiledPage}
  */
 export function compilePage(file, context, options = {}) {
@@ -59,10 +59,20 @@ export function compilePage(file, context, options = {}) {
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
  * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} [collections]
  * @param {import("./compiler/reader.js").Reader} [reader] Source reader.
+ * @param {Map<string, number[]> | null} [imageVariants] Builder-generated
+ *   responsive variants (original's absolute source path → widths).
  * @returns {CompiledDocument}
  */
-export function compileDocument(file, context, stack, vars, collections, reader = fsReader()) {
-  return compileDocumentImpl(file, context, stack, vars, collections, reader);
+export function compileDocument(
+  file,
+  context,
+  stack,
+  vars,
+  collections,
+  reader = fsReader(),
+  imageVariants = null
+) {
+  return compileDocumentImpl(file, context, stack, vars, collections, reader, imageVariants);
 }
 
 /**

package/src/image-variant-resize.js

@@ -0,0 +1,71 @@
+// ---------------------------------------------------------------------------
+// The resize worker for the build-time image pre-pass (2.9.0). Never imported
+// by the builder: the build is synchronous and sharp is not, so
+// src/image-variants.js spawns this file as a child process with a jobs JSON
+// file and reads back a results JSON file.
+//
+// sharp is an OPTIONAL dependency, so it is dynamic-imported inside a
+// try/catch: when it cannot load (not installed, broken native binding), the
+// worker reports `{ unavailable: true }` and exits cleanly — the parent turns
+// that into one hint, and the build ships exactly what 2.8.0 would have.
+// A failure on ONE image is recorded in `failed` and the rest still resize.
+// Nothing here ever exits non-zero over an image.
+//
+// `WD_SHARP_MODULE` overrides the sharp specifier; tests point it at a
+// nonexistent module to exercise the sharp-absent path without uninstalling
+// anything. It is a test seam, not a public knob.
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Run every job in the jobs file and write the results file.
+ * @param {string} jobsFile JSON array of `{ source, out, width, format }`.
+ * @param {string} resultsFile Written with `{ unavailable, failed }`.
+ * @returns {Promise<void>}
+ */
+export async function runJobsFile(jobsFile, resultsFile) {
+  const jobs = JSON.parse(fs.readFileSync(jobsFile, "utf8"));
+  /** @type {(result: { unavailable: boolean, failed: { file: string, width: number, error: string }[] }) => void} */
+  const write = (result) => fs.writeFileSync(resultsFile, JSON.stringify(result));
+  /** @type {any} */
+  let sharp;
+  try {
+    sharp = (await import(process.env.WD_SHARP_MODULE || "sharp")).default;
+  } catch {
+    write({ unavailable: true, failed: [] });
+    return;
+  }
+  /** @type {{ file: string, width: number, error: string }[]} */
+  const failed = [];
+  for (const job of jobs) {
+    try {
+      // `rotate()` honors EXIF orientation before resizing: the emitted variant
+      // loses the EXIF tag with its pixels physically rotated, so it displays
+      // exactly like the tag-carrying original. `withoutEnlargement` is belt and
+      // braces — the pre-pass only ever queues widths below the intrinsic size.
+      let pipeline = sharp(job.source)
+        .rotate()
+        .resize({ width: job.width, withoutEnlargement: true });
+      if (job.format === "webp") pipeline = pipeline.webp({ quality: 82 });
+      else if (job.format === "jpeg") pipeline = pipeline.jpeg({ quality: 82, progressive: true });
+      else pipeline = pipeline.png({ compressionLevel: 9 });
+      fs.mkdirSync(path.dirname(job.out), { recursive: true });
+      await pipeline.toFile(job.out);
+    } catch (err) {
+      failed.push({
+        file: job.source,
+        width: job.width,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  write({ unavailable: false, failed });
+}
+
+// Entry-point guard, one line so importing this module in a test registers the
+// line as executed without running main (same pattern as the coverage gate).
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url)
+  runJobsFile(process.argv[2], process.argv[3]);

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/types/builder.d.ts

@@ -98,6 +98,15 @@ 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;
+    };
     incremental?: {
         changed: string[];
         rebuilt: string[];

package/types/compiler/context.d.ts

@@ -66,6 +66,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
@@ -488,6 +493,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.

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

package/types/compiler.d.ts

@@ -4,7 +4,7 @@
  * a different source (see `compileFromMemory`).
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {import("./config.js").Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader }} [options]
+ * @param {{ feed?: { href: string, title: string }, site?: import("./compiler/page.js").SiteContext, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, vars?: Record<string, unknown>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null }} [options]
  * @returns {CompiledPage}
  */
 export function compilePage(file: string, context: import("./config.js").Paths, options?: {
@@ -16,6 +16,7 @@ export function compilePage(file: string, context: import("./config.js").Paths,
     collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>;
     vars?: Record<string, unknown>;
     reader?: import("./compiler/reader.js").Reader;
+    imageVariants?: Map<string, number[]> | null;
 }): CompiledPage;
 /**
  * Compile a source file into its body HTML, frontmatter, and assets (no page
@@ -26,9 +27,11 @@ export function compilePage(file: string, context: import("./config.js").Paths,
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
  * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} [collections]
  * @param {import("./compiler/reader.js").Reader} [reader] Source reader.
+ * @param {Map<string, number[]> | null} [imageVariants] Builder-generated
+ *   responsive variants (original's absolute source path → widths).
  * @returns {CompiledDocument}
  */
-export function compileDocument(file: string, context: import("./config.js").Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, reader?: import("./compiler/reader.js").Reader): CompiledDocument;
+export function compileDocument(file: string, context: import("./config.js").Paths, stack?: string[], vars?: Record<string, unknown>, collections?: Map<string, import("./compiler/collections.js").CollectionRow[]>, reader?: import("./compiler/reader.js").Reader, imageVariants?: Map<string, number[]> | null): CompiledDocument;
 /**
  * Harden every `<img>` in an assembled page body, reading intrinsic dimensions
  * from the real filesystem by default.

package/types/image-variants.d.ts

@@ -0,0 +1,131 @@
+/**
+ * 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: Paths, options?: {
+    widths?: number[];
+    cacheDir?: string;
+    quiet?: boolean;
+    runJobs?: (jobs: ResizeJob[]) => ResizeResult;
+}): ImageVariantPlan;
+/**
+ * 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: ResizeJob[], spawn?: (cmd: string, args: string[], opts: object) => unknown): ResizeResult;
+/**
+ * @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: number[];
+export type Paths = import("./config.js").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.
+ */
+export type ResizeJob = {
+    /**
+     * Absolute path of the original image.
+     */
+    source: string;
+    /**
+     * Absolute cache path the resized variant is written to.
+     */
+    out: string;
+    /**
+     * Target width in pixels (always below the intrinsic).
+     */
+    width: number;
+    /**
+     * Output encoder, from the source extension.
+     */
+    format: "jpeg" | "png" | "webp";
+};
+/**
+ * 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).
+ */
+export type ResizeResult = {
+    unavailable: boolean;
+    failed: {
+        file: string;
+        width: number;
+        error: string;
+    }[];
+};
+/**
+ * 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).
+ */
+export type ImageVariantPlan = {
+    variants: Map<string, number[]>;
+    /**
+     * Variants resized this build.
+     */
+    generated: number;
+    /**
+     * Variants served from the on-disk cache.
+     */
+    cached: number;
+    /**
+     * sharp could not be loaded.
+     */
+    unavailable: boolean;
+};