@zvndev/darkmown 0.16.0 → 0.18.0

package/AGENTS.md

@@ -156,13 +156,16 @@ Your `.skin` selectors must match the **real** output. The emitted HTML is:
 | `::: name .card … :::` (non-`section`) | `<div class="card">…</div>` |
 | `:button "x" -> …` | `<button>x</button>` |
 | `:input email …` | `<input type="…">` |
+| `:textarea note …` | `<textarea>` |
+| `:select name` + `- Label` lines | `<select>` of `<option>`s |
+| `:checkbox name` / `:radio name` + `- Label` lines | labelled `<input type=checkbox\|radio>` group (`:checkbox` captures an **array**, `:radio` one value) |
 | `:bind q placeholder="…"` | `<input>` bound two-way to `:state q` |
 | `:submit "Go"` | `<button type="submit">Go</button>` |
 | `:form …` | `<form>…</form>` |
 | reactive `@loop` of a list | `<ul>`/`<ol>` (or `<div>`) of items |
 | `{ name }` | a text node |
 
-So style with real selectors: `section`, `.card`, `button`, `input`, `form`, `h1`. **To add a class to a container, use `::: name .class`. For any other custom element, write raw HTML `<div class="…">`. There is NO `{.class}` attribute syntax.** A container class can also be reactive: `::: card .on-sale when p.price < 50` toggles the class from a predicate (same grammar as `:if`).
+So style with real selectors: `section`, `.card`, `button`, `input`, `form`, `h1`. **To add a class to a container, use `::: name .class`; to add one to a single inline element (link, image, emphasis, inline code), use a trailing `{.class .class #id}` — e.g. `[Get started](/start/){.btn}`.** A container class can also be reactive: `::: card .on-sale when p.price < 50` toggles the class from a predicate (same grammar as `:if`).
 
 ## Styling with `.skin` — ship this on every page
 

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.18.0 — 2026-06-24
+
+Navigation goes instant and flash-free, and images are hardened at compile time.
+
+- **Prerendered, gap-free navigation.** `transitions: true` now also emits a declarative `<script type="speculationrules">` that **prerenders** same-origin links on hover/pointerdown (eagerness `moderate`). The next page is fully rendered before the click, so activation is instant — eliminating the white render-gap flash that plain navigation (and even prefetch, which only warms the cache) leaves for the view transition to paper over. It is browser-interpreted JSON, not framework runtime JS, so static pages stay zero-JS; unsupported browsers (or those with preloading disabled) ignore it and navigate normally. Mark a link `{.no-prefetch}` to opt it out; `rel=nofollow` links are never speculated. (Chrome disables prerendering while DevTools is open — verify on the built site with DevTools closed.)
+- **Directional view transition.** The root transition is no longer the UA cross-fade, which left both pages superimposed at ~50 % opacity mid-navigation — a visible double-exposure ghost. `transitions: true` now emits a short directional fade+slide (old lifts up and out, new rises up and in, 200 ms eased) so pages move past each other instead of stacking. Honors `prefers-reduced-motion`.
+- **Compile-time image hardening.** Every `<img>` is stamped with its intrinsic `width`/`height` (read from the file on disk via `image-size`, a new build-time dependency — no runtime cost), `decoding="async"`, and a load-priority split: the first image stays eager with `fetchpriority="high"` (the LCP candidate), the rest get `loading="lazy"`. This removes the layout-shift "jump" as images decode and stops below-the-fold images competing for bandwidth. Author-set attributes are never overwritten; remote or unreadable sources degrade gracefully (no dimensions, no error).
+- All three are compile-time only — the shipped reactive runtime is unchanged (still ~5.8 KB gzipped, under the 6 KB budget). The demo site (`site/pages/`) now opts into `transitions: true` to dogfood the navigation.
+
+## 0.17.0 — 2026-06-23
+
+Multi-select and single-choice form groups: **`:checkbox` and `:radio`**.
+
+- **`:checkbox name` and `:radio name`** (each followed by `- Label` option lines) render a labelled group of `<input>`s that share one `name`, wrapped in `<label>`s inside a `role="group"` / `role="radiogroup"` container with a derived aria-label. They join `:input`/`:textarea`/`:select` as `:form into` field directives.
+- **Checkbox groups capture an array.** A `:checkbox` group is marked `data-wd-multi`, and the runtime's submit handler now collects every checked value via `FormData.getAll` instead of collapsing duplicate names to the last one. A `:radio` group captures a single value like `:input`. This is the only runtime change (shipped reactive runtime is 5836 B gzipped, still under the 6 KB budget); everything else is compile-time.
+- Live demo on `/data/` (the inquiry form), and the AGENTS.md inline-`{.class}` note is corrected (it had stale "no `{.class}` syntax" copy from before 0.15.0).
+
 ## 0.16.0 — 2026-06-23
 
 Cross-document **view transitions** return as a per-page opt-in.

package/README.md

@@ -82,7 +82,7 @@ tags: [sales, revenue, "q1, q2"]
 
 Three keys also drive the document `<head>`: `title` sets `<title>`, `description` adds the meta description plus Open Graph / Twitter tags, and `image` (an absolute URL) sets the social-share preview (`og:image` / `twitter:image` and a `summary_large_image` card).
 
-`transitions: true` opts a page into **cross-document view transitions** — a smooth same-origin cross-fade on navigation, emitted as the CSS-only `@view-transition { navigation: auto; }` rule. It ships zero JavaScript, only animates between same-origin pages that both opt in, and is silently ignored by browsers without support (the navigation just doesn't fade). Off by default; opt out explicitly with `transitions: false`.
+`transitions: true` opts a page into **instant, flash-free navigation** — zero JavaScript, all declarative. It emits a directional fade+slide **view transition** for the page swap (old lifts up and out, new rises up and in — replacing the default cross-fade, which left both pages ghosted at ~50 % opacity mid-navigation), plus a **`<script type="speculationrules">` prerender** hint that renders the next same-origin page on hover/pointerdown so the click activates an already-painted page (no white render-gap flash). It honors `prefers-reduced-motion`. Only same-origin pages that both opt in transition; browsers without support — or with page-preloading disabled — navigate normally. Off by default; opt out with `transitions: false`. Mark a link `{.no-prefetch}` to exclude it from prerendering. (Chrome disables prerendering while DevTools is open, so test the built site with DevTools closed.)
 
 ## Static assets
 
@@ -93,6 +93,8 @@ Images, fonts, icons, and other non-page files live on the include shelf at `sit
 
 Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`serve` layer returns the correct `Content-Type` per extension.
 
+**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).
+
 **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:
 
 - `site/pages/logo.svg` → `dist/logo.svg` → `![logo](/logo.svg)`
@@ -495,6 +497,12 @@ Fetched data and a form live happily on the same page:
 :select topic
 - General
 - Billing
+:checkbox channels
+- Email
+- SMS
+:radio plan
+- Basic
+- Pro
 :textarea note placeholder="Anything else?"
 :submit "Save"
 :endform
@@ -504,7 +512,7 @@ Fetched data and a form live happily on the same page:
 
 - `:form into name` captures submits straight into state (no backend). `:form action="/url"` emits a plain native form instead — zero JS, full progressive enhancement. Form actions use the same URL scheme guard as `:fetch`: relative paths, explicit `http(s)://`, or leading `{ state }` interpolation; protocol-relative and non-http(s) schemes are compile errors.
 - `:form action="/url" into reply` does both: with JS the submit posts urlencoded via fetch and the JSON reply lands in state `reply` (`reply_error` on failure); without JS it is the same native POST. Darkmown adapts to any backend — it does not own one.
-- Field directives: `:input`, `:textarea name [rows=N]`, and `:select name` (with `- Label` option lines) all capture into `:form into` state the same way. Each derives a non-visual `aria-label` from its placeholder, else a humanized field name, unless you supply `aria-label`/`aria-describedby`.
+- Field directives: `:input`, `:textarea name [rows=N]`, `:select name`, `:checkbox name`, and `:radio name` (the last three take `- Label` option lines) all capture into `:form into` state the same way. A `:checkbox` group captures **every checked value as an array**; a `:radio` group captures a single value. Each derives a non-visual `aria-label` from its placeholder, else a humanized field name, unless you supply `aria-label`/`aria-describedby`.
 - `:state x = [] persist` keeps a single page's state in localStorage across reloads. (For state that is shared across pages and tabs, reach for [`:store`](#global-state--store) instead.)
 - `:computed total = items.length * 4` derives state from state with a compile-time-checked expression (names, numbers, arithmetic, comparisons — nothing else).
 - `:if item.path` works inside reactive loops for per-row branches, and nests — an inner `:if` resolves after the outer branch and stays reactive.

package/docs/spec-alignment.md

@@ -79,6 +79,15 @@ Three capability gaps from the 2026-06-16 audit, closed together over a shared `
 - **Interpolation in link/image destinations:** `{ name.path }` now resolves inside a markdown destination — `[{ it.label }]({ it.url })`, `![{ p.alt }]({ p.src })` — so a build-time `@loop` can drive `href`/`src` and the page stays static. Only build-time (static-scope) values substitute; reactive `:state` is left untouched (it cannot live in a destination).
 - **Inline attributes (`{.class #id}`):** a trailing attribute block attaches classes / an id to the inline element before it (link, image, emphasis, code), so a link can be styled as a button without a wrapper container. The block must follow with no space; it never collides with `{ name }` interpolation (which always starts with a name, not `.`/`#`).
 
+## Stage 14 additions (2026-06-24, v0.18.0)
+
+- **Instant, flash-free navigation under `transitions: true`:** alongside the cross-document view transition, the page emits a declarative `<script type="speculationrules">` that **prerenders** same-origin links at `moderate` eagerness (hover/pointerdown). A prerendered page activates instantly, so there is no render-gap white flash for the transition to cover; the transition itself is now a directional fade+slide (old lifts out, new rises in, 200 ms eased) instead of the UA cross-fade that superimposed both pages at ~50 % opacity. Browser-interpreted JSON, not framework JS — static pages stay zero-JS; `prefers-reduced-motion` is honored; `{.no-prefetch}` / `rel=nofollow` opt links out. (Chrome disables prerendering while DevTools is open.)
+- **Compile-time image hardening:** every emitted `<img>` is stamped with intrinsic `width`/`height` (read from disk via the `image-size` build-time dependency — no runtime cost), `decoding="async"`, and `fetchpriority="high"` on the first image / `loading="lazy"` on the rest. Eliminates cumulative layout shift and de-prioritizes below-the-fold images. Author attributes are never overwritten; remote/unreadable sources degrade to no dimensions.
+
+## Stage 13 additions (2026-06-23, v0.17.0)
+
+- **`:checkbox` and `:radio` field groups:** `:checkbox name` / `:radio name` (with `- Label` option lines) render a labelled `role="group"` / `role="radiogroup"` of `<input>`s that share one `name`, each wrapped in its own `<label>` and deriving an aria-label like the other fields. A `:checkbox` group is marked `data-wd-multi` so the runtime's submit handler collects **every** checked value into an array (`FormData.getAll`) instead of collapsing to the last — the one runtime change (compile-time only otherwise; shipped runtime stays ~5.8 KB). A `:radio` group captures a single value like `:input`. Closes the multi-select / single-choice gap that previously forced raw HTML and lost `:form into` capture.
+
 ## Stage 11 additions (2026-06-19, v0.14.1)
 
 - **Release hardening — page asset privacy:** page-colocated assets now honor the same hidden-path convention as routes. A file under `site/pages` is emitted only when no relative path segment starts with `.`, `-`, or `_`; symlinked page assets are skipped too. This preserves normal colocated media (`logo.svg`, `blog/cover.png`) while preventing accidental publication of `.env`, `_private/*`, `-draft/*`, or symlink-to-outside files.
@@ -103,7 +112,7 @@ The compiler recognizes three directives — `:note`, `:try`, and `:sprint` —
 ## Still missing from the full vision
 
 - First-party server runtime (`site/api/`), HTML-fragment `swap` semantics, and cart server sync — parked behind the adapter decision until a real project needs them.
-- **View transitions:** named/typed transitions (`view-transition-name`, per-element morphs) and `@starting-style` emission on top of the opt-in cross-document fade shipped in 0.16.0 (see Stage 4).
+- **View transitions:** named/typed transitions (`view-transition-name`, per-element morphs) and `@starting-style` emission, on top of the directional fade + speculation-rules prerender shipped in 0.18.0 (see Stage 4 / Stage 14).
 - Richer diagnostics and package-consumer QA in regular CI. Editor tooling exists as a source-installable VS Code extension; public Marketplace/Open VSX distribution remains a launch/distribution follow-up.
 
 ## Current claim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -42,6 +42,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "image-size": "^1.2.1",
     "markdown-it": "^14.2.0"
   },
   "devDependencies": {

package/site/pages/data.wd

@@ -1,5 +1,6 @@
 ---
 title: Data, forms, and persistence
+transitions: true
 ---
 
 @include /nav.wd
@@ -150,7 +151,7 @@ Scroll me into view and I will load.
 
 ## Richer form controls
 
-`:textarea` and `:select` join `:input`, all captured into the same `:form into` state with no backend:
+`:textarea`, `:select`, `:checkbox`, and `:radio` join `:input`, all captured into the same `:form into` state with no backend. A `:checkbox` group captures every checked value as an **array**; a `:radio` group captures a single value:
 
 :form into inquiry
 :input fullname placeholder="Your full name"
@@ -158,12 +159,18 @@ Scroll me into view and I will load.
 - General question
 - New case
 - Billing
+:checkbox services
+- Cleaning
+- Whitening
+:radio urgency
+- Routine
+- Urgent
 :textarea message placeholder="How can we help?"
 :submit "Send inquiry"
 :endform
 
 :if inquiry
-Thanks **{ inquiry.fullname }** — we logged your "{ inquiry.topic }" note.
+Thanks **{ inquiry.fullname }** — we logged your "{ inquiry.topic }" note. Services: { inquiry.services }. Urgency: { inquiry.urgency }.
 :else
 Pick a topic and send — it is captured client-side, no backend.
 :endif

package/site/pages/docs/index.wd

@@ -1,6 +1,7 @@
 ---
 title: Darkmown docs
 description: Learn Darkmown routing, directives, state, loops, forms, and the static-to-reactive model.
+transitions: true
 ---
 
 @include /nav.wd
@@ -164,6 +165,14 @@ tags: [sales, revenue, "q1, q2"]
 
 `{ meta.title }` prints a scalar and `{ meta.tags }` joins an array with `, `. You can loop a frontmatter array at build time — `@loop meta.tags into tag` — and the page stays static. Arrays are inline flow only (`[a, b]`); quoted items keep their commas.
 
+## Instant navigation
+
+Add `transitions: true` to a page's frontmatter for **instant, flash-free navigation** — zero JavaScript. It emits a directional fade+slide view transition for the page swap and a `<script type="speculationrules">` prerender hint, so the browser renders the next same-origin page on hover/pointerdown and the click activates an already-painted page (no white render-gap). It honors `prefers-reduced-motion`, and only same-origin pages that both opt in transition. Off by default; opt out with `transitions: false`, or exclude a single link from prerendering with `{.no-prefetch}`. (Chrome turns prerendering off while DevTools is open — test the built site with DevTools closed.)
+
+## Images
+
+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.
+
 ## Sections
 
 `::: section #id .class` opens a container and `:::` closes it. Sections scope state: a `:state` declared inside a section belongs to that section, so two sections can both declare `count` without colliding. Bindings and buttons resolve to the nearest scope.

package/site/pages/index.wd

@@ -2,6 +2,7 @@
 title: Darkmown — Markdown that runs, not Markdown that needs React
 description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
 image: https://darkmown.com/__wd/media/og.png
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/loops.wd

@@ -1,5 +1,6 @@
 ---
 title: Loop ergonomics
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/markdown.md

@@ -1,5 +1,6 @@
 ---
 title: Plain Markdown
+transitions: true
 ---
 
 # Plain Markdown stays plain

package/site/pages/reactive.wd

@@ -1,5 +1,6 @@
 ---
 title: Reactive Markdown
+transitions: true
 ---
 
 @include /nav.wd

package/site/pages/store.wd

@@ -1,5 +1,6 @@
 ---
 title: Global store
+transitions: true
 ---
 
 @include /nav.wd

package/src/compiler.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import MarkdownIt from "markdown-it";
+import { imageSize } from "image-size";
 
 /**
  * @typedef {import("./config.js").Paths} Paths
@@ -135,12 +136,48 @@ export function compilePage(file, context) {
   const scriptSrcs = compiled.assets.runtime ? ["/__wd/runtime.js", ...compiled.assets.scripts] : [...compiled.assets.scripts];
   const scripts = scriptSrcs.map((src) => `<script type="module" src="${src}"></script>`).join("\n");
   // Cross-document view transitions: opt in per page with `transitions: true` in
-  // frontmatter to emit the CSS-only @view-transition rule — a smooth same-origin
-  // cross-fade on navigation, with zero JavaScript. Ignored by browsers without
-  // support (graceful fade-free fallback) and only applies to same-origin
+  // frontmatter to emit a CSS-only stylesheet — a smooth same-origin transition
+  // on navigation, with zero JavaScript. Ignored by browsers without support
+  // (graceful, transition-free fallback) and only applies to same-origin
   // navigations where both the outgoing and incoming page opt in.
+  //
+  // The default UA animation cross-fades the root: outgoing opacity 1→0 while
+  // incoming 0→1, both at once. Mid-navigation that leaves the two pages
+  // superimposed at ~50% opacity — headings ghost over headings. We override it
+  // with a directional fade+slide (old lifts up and out, new rises up and in) so
+  // the pages move past each other instead of stacking. Short + eased = peppy.
   const wantTransitions = compiled.meta.transitions === true || compiled.meta.transitions === "true";
-  const transitions = wantTransitions ? `\n  <style>@view-transition { navigation: auto; }</style>` : "";
+  const transitions = wantTransitions
+    ? `\n  <style>
+    @view-transition { navigation: auto; }
+    ::view-transition-old(root) { animation: wd-nav-out 200ms cubic-bezier(0.4, 0, 1, 1) both; }
+    ::view-transition-new(root) { animation: wd-nav-in 200ms cubic-bezier(0, 0, 0.2, 1) both; }
+    @keyframes wd-nav-out { to { opacity: 0; transform: translateY(-1rem); } }
+    @keyframes wd-nav-in { from { opacity: 0; transform: translateY(1rem); } }
+    @media (prefers-reduced-motion: reduce) {
+      ::view-transition-old(root), ::view-transition-new(root) { animation-duration: 1ms; }
+      @keyframes wd-nav-out { to { opacity: 0; } }
+      @keyframes wd-nav-in { from { opacity: 0; } }
+    }
+  </style>`
+    : "";
+
+  // The latency half of smooth navigation — and what kills the white flash. A
+  // declarative speculationrules script (the browser interprets it — not
+  // framework runtime JS, so the zero-JS invariant holds) *prerenders* the next
+  // same-origin page on hover/pointerdown. Prefetch only warms the cache, so the
+  // page still has to render on click — that render gap is the white flash. A
+  // prerender renders the whole page in a hidden tab ahead of the click, so
+  // activation is instant: no render gap, and the view transition fires on the
+  // already-painted page. Safe now that pages are light. Eagerness `moderate` =
+  // ~200ms hover / pointerdown, capped at two. Mark a link `{.no-prefetch}` to
+  // opt it out; `rel=nofollow` links are never speculated. Browsers without
+  // support (or with preloading disabled) ignore the tag and navigate normally.
+  const speculation = wantTransitions
+    ? `\n  <script type="speculationrules">{"prerender":[{"where":{"and":[{"href_matches":"/*"},{"not":{"selector_matches":".no-prefetch"}},{"not":{"selector_matches":"[rel~=nofollow]"}}]},"eagerness":"moderate"}]}</script>`
+    : "";
+
+  const body = enhanceImages(compiled.html, context);
 
   return {
     meta: compiled.meta,
@@ -151,10 +188,10 @@ export function compilePage(file, context) {
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>${descriptionTag}
   <link rel="icon" href="${favicon}">
-  ${cssLinks}${transitions}
+  ${cssLinks}${transitions}${speculation}
 </head>
 <body>
-${compiled.html}
+${body}
 ${scripts}
 </body>
 </html>`,
@@ -163,6 +200,80 @@ ${scripts}
   };
 }
 
+/**
+ * Harden every `<img>` in the assembled page body — compile-time only, zero
+ * runtime JS. Bare markdown images reflow the page as they decode (cumulative
+ * layout shift — the literal "jump" on navigation) and load eagerly. This
+ * stamps intrinsic `width`/`height` (read from the file on disk so the browser
+ * reserves space), `decoding="async"` on all, and a load-priority split: the
+ * first image is the LCP candidate (eager + `fetchpriority="high"`), the rest
+ * lazy-load. Author-set attributes are never overwritten.
+ * @param {string} html Assembled page body HTML.
+ * @param {Paths} paths Resolved project paths.
+ * @returns {string}
+ */
+export function enhanceImages(html, paths) {
+  let index = 0;
+  return html.replace(/<img\b[^>]*?\/?>/g, (tag) => {
+    const i = index++;
+    const has = (/** @type {string} */ attr) => new RegExp(`\\b${attr}\\s*=`, "i").test(tag);
+    /** @type {string[]} */
+    const add = [];
+    // Dimensions only when the author hasn't sized it — adding one axis to a
+    // manually-sized image would distort its aspect ratio.
+    if (!has("width") && !has("height")) {
+      const dim = measureImage(srcOf(tag), paths);
+      if (dim) add.push(`width="${dim.width}"`, `height="${dim.height}"`);
+    }
+    if (!has("decoding")) add.push(`decoding="async"`);
+    if (i === 0) {
+      // First image is the LCP candidate: stays eager, gets a priority hint.
+      if (!has("fetchpriority")) add.push(`fetchpriority="high"`);
+    } else if (!has("loading")) {
+      add.push(`loading="lazy"`);
+    }
+    if (!add.length) return tag;
+    return `${tag.replace(/\s*\/?>\s*$/, "")} ${add.join(" ")}>`;
+  });
+}
+
+/**
+ * Extract the `src` attribute value from an `<img>` tag, or "" if absent.
+ * @param {string} tag
+ * @returns {string}
+ */
+function srcOf(tag) {
+  const m = tag.match(/\bsrc\s*=\s*["']([^"']*)["']/i);
+  return m ? m[1] : "";
+}
+
+/**
+ * Read an image's intrinsic dimensions from disk, or null when the src is
+ * remote/relative/unreadable. Resolution mirrors the asset emit: `/__wd/media/x`
+ * comes from the shelf (`site/_`), other absolute paths from `site/pages`.
+ * @param {string} src
+ * @param {Paths} paths
+ * @returns {{ width: number, height: number } | null}
+ */
+function measureImage(src, paths) {
+  if (!src || /^(https?:)?\/\//i.test(src) || src.startsWith("data:")) return null;
+  let filePath;
+  if (src.startsWith("/__wd/media/")) {
+    filePath = path.join(paths.shelfRoot, src.slice("/__wd/media/".length));
+  } else if (src.startsWith("/")) {
+    filePath = path.join(paths.routesRoot, src.slice(1));
+  } else {
+    return null; // page-relative: the source directory is lost after assembly
+  }
+  try {
+    const { width, height } = imageSize(fs.readFileSync(filePath));
+    if (typeof width === "number" && typeof height === "number") return { width, height };
+  } catch {
+    /* missing or unreadable — degrade to no dimensions */
+  }
+  return null;
+}
+
 /**
  * Compile a source file into its body HTML, frontmatter, and assets (no page shell).
  * @param {string} file Absolute path to the source file.
@@ -413,6 +524,16 @@ function compileBody(lines, ctx) {
       i = j - 1;
       continue;
     }
+    const choiceMatch = line.match(/^:(checkbox|radio)\s/);
+    if (choiceMatch) {
+      flush();
+      const opts = [];
+      let j = i + 1;
+      while (j < lines.length && /^\s*-\s+/.test(lines[j])) { opts.push(lines[j]); j++; }
+      out.push(handleChoiceGroup(line, opts, ctx, /** @type {"checkbox" | "radio"} */ (choiceMatch[1])));
+      i = j - 1;
+      continue;
+    }
     if (/^:bind\s/.test(line)) {
       flush();
       out.push(handleBind(line, ctx));
@@ -1209,6 +1330,66 @@ function handleSelect(line, optionLines, ctx) {
   return `<select ${attrs.join(" ")}>${opts}</select>`;
 }
 
+/**
+ * `:checkbox name [required]` / `:radio name [required]` followed by `- Label`
+ * lines → a labelled group of `<input type=checkbox|radio>`, each sharing `name`
+ * with value === label and wrapped in its own `<label>`. The group is a
+ * `role="group"` / `role="radiogroup"` container with an aria-label (explicit or
+ * humanized from the name). Checkbox groups are marked `data-wd-multi="name"` so
+ * the runtime captures every checked value as an array (`FormData.getAll`); radio
+ * groups capture a single value like `:input`. Flags: `required` (radio → the
+ * group; not emitted on checkboxes, where "at least one" has no native HTML form),
+ * `disabled` (whole group), `autofocus` (first control).
+ * @param {string} line
+ * @param {string[]} optionLines The following `- Label` lines consumed by dispatch.
+ * @param {Ctx} ctx
+ * @param {"checkbox" | "radio"} kind
+ * @returns {string}
+ */
+function handleChoiceGroup(line, optionLines, ctx, kind) {
+  const directive = `:${kind}`;
+  const match = line.match(kind === "checkbox" ? /^:checkbox\s+([A-Za-z_][\w-]*)\s*(.*)$/ : /^:radio\s+([A-Za-z_][\w-]*)\s*(.*)$/);
+  if (!match) throw new Error(`Malformed ${directive} in ${ctx.file}: ${line}. Use: ${directive} name [required] then "- Label" lines`);
+  const name = match[1];
+  const flags = [];
+  let ariaLabel = null;
+  let ariaDescribedby = null;
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[3]) {
+      if (!["required", "disabled", "autofocus"].includes(token[3])) {
+        throw new Error(`Unknown ${directive} flag "${token[3]}" in ${ctx.file}`);
+      }
+      flags.push(token[3]);
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (token[1] === "aria-label") ariaLabel = value;
+    else if (token[1] === "aria-describedby") ariaDescribedby = value;
+    else throw new Error(`Unknown ${directive} attribute "${token[1]}" in ${ctx.file}`);
+  }
+  const options = optionLines.map((l) => l.replace(/^\s*-\s+/, "").trim()).filter(Boolean);
+  if (!options.length) {
+    throw new Error(`${directive} "${name}" in ${ctx.file} has no options. Add "- Label" lines beneath it.`);
+  }
+  const isCheckbox = kind === "checkbox";
+  const groupAttrs = [`class="wd-${isCheckbox ? "checkboxes" : "radios"}"`, `role="${isCheckbox ? "group" : "radiogroup"}"`];
+  if (isCheckbox) groupAttrs.push(`data-wd-multi="${escapeHtml(name)}"`);
+  groupAttrs.push(`aria-label="${escapeHtml(ariaLabel || humanizeName(name))}"`);
+  if (ariaDescribedby) groupAttrs.push(`aria-describedby="${escapeHtml(ariaDescribedby)}"`);
+  const disabled = flags.includes("disabled");
+  const required = flags.includes("required");
+  const autofocus = flags.includes("autofocus");
+  const controls = options.map((opt, idx) => {
+    const a = [`type="${kind}"`, `name="${escapeHtml(name)}"`, `value="${escapeHtml(opt)}"`];
+    if (disabled) a.push("disabled");
+    if (required && !isCheckbox) a.push("required");
+    if (autofocus && idx === 0) a.push("autofocus");
+    return `<label><input ${a.join(" ")}> ${escapeHtml(opt)}</label>`;
+  }).join("");
+  return `<div ${groupAttrs.join(" ")}>${controls}</div>`;
+}
+
 /**
  * @param {string} line
  * @param {Ctx} ctx

package/src/runtime.js

@@ -557,7 +557,14 @@ document.addEventListener("submit", (event) => {
   const action = form.getAttribute("action");
 
   if (!action) {
-    state[key] = Object.fromEntries(new FormData(form));
+    const fd = new FormData(form);
+    const data = /** @type {Record<string, any>} */ (Object.fromEntries(fd));
+    // :checkbox groups share one name; collect every checked value as an array.
+    for (const group of form.querySelectorAll("[data-wd-multi]")) {
+      const field = group.getAttribute("data-wd-multi");
+      if (field) data[field] = fd.getAll(field);
+    }
+    state[key] = data;
     savePersisted();
     render();
     return;