@zvndev/darkmown 1.4.0 → 2.0.0

package/src/compiler/fetch.js

@@ -0,0 +1,159 @@
+// ---------------------------------------------------------------------------
+// `:fetch`: the lifecycle-aware data-loading directive, plus the compile-time
+// URL scheme guard (`validateFetchUrl`) the form/media/embed handlers reuse.
+//
+// Every handler receives the 0-based line `index` so its malformed/invalid
+// errors report `file:line` (via `at`) — matching the unclosed-block errors —
+// while keeping the message text and `Use:` hints intact.
+// ---------------------------------------------------------------------------
+
+import { at } from "./context.js";
+import {
+  escapeHtml,
+  resolveStateKey,
+  safeScriptJson,
+  stripQuotes,
+  validatePath
+} from "./interpolation.js";
+import { declareState } from "./state.js";
+
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+const FETCH_USE =
+  'Use: :fetch name from "url" [method=…] [timeout=ms] [retry=N] [when=visible] [headers=key] [body=key] [refresh=url]';
+
+/**
+ * Parse a keyword-arg `:fetch` directive into a lifecycle-aware marker.
+ * Auto-declares four state keys (value/error/loading/empty), seeds them, and
+ * emits `data-wd-fetch-*` attributes (url/method/when/timeout/retry/headers/
+ * body/deps) consumed by the runtime's `startFetch`.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleFetch(line, ctx, index) {
+  const head = line.match(/^:fetch\s+([A-Za-z_$][\w$]*)\s+from\s+("[^"]+"|\S+)\s*(.*)$/);
+  if (!head) throw new Error(`Malformed :fetch in ${at(ctx, index)}: ${line}. ${FETCH_USE}`);
+  const name = head[1];
+  const url = validateFetchUrl(stripQuotes(head[2]), ctx);
+  /** @type {Record<string, string>} */
+  const opts = {};
+  for (const part of head[3].trim().split(/\s+/).filter(Boolean)) {
+    const kv = part.match(/^([A-Za-z]+)=(.+)$/);
+    if (!kv) throw new Error(`Unknown :fetch option "${part}" in ${at(ctx, index)}. ${FETCH_USE}`);
+    const optName = kv[1];
+    if (!["method", "when", "timeout", "retry", "headers", "body", "refresh"].includes(optName)) {
+      throw new Error(`Unknown :fetch option "${optName}" in ${at(ctx, index)}. ${FETCH_USE}`);
+    }
+    opts[optName] = stripQuotes(kv[2]);
+  }
+
+  if (
+    opts.method &&
+    !["GET", "POST", "PUT", "PATCH", "DELETE"].includes(opts.method.toUpperCase())
+  ) {
+    throw new Error(
+      `:fetch method "${opts.method}" is not allowed in ${at(ctx, index)}. ${FETCH_USE}`
+    );
+  }
+  if (opts.when && !["load", "visible"].includes(opts.when)) {
+    throw new Error(`:fetch when "${opts.when}" is not allowed in ${at(ctx, index)}. ${FETCH_USE}`);
+  }
+  for (const n of ["timeout", "retry"]) {
+    if (opts[n] !== undefined && !/^\d+$/.test(opts[n])) {
+      throw new Error(
+        `:fetch ${n} must be a non-negative integer in ${at(ctx, index)}. ${FETCH_USE}`
+      );
+    }
+  }
+  if (opts.refresh !== undefined) {
+    // Layer 2: a 401 triggers a token-refresh POST to this URL, then one retry.
+    // The new token is written back into the `headers=` state, so it is required.
+    if (!opts.headers) {
+      throw new Error(
+        `:fetch refresh= needs headers= (the state key holding the token to renew) in ${at(ctx, index)}. ${FETCH_USE}`
+      );
+    }
+    opts.refresh = validateFetchUrl(opts.refresh, ctx, ":fetch refresh");
+  }
+
+  // Extract `{ path }` dependency keys from the URL (validated against poison
+  // segments). The runtime fills them from state on each (re)fetch.
+  /** @type {string[]} */
+  const deps = [];
+  for (const dep of url.matchAll(/\{\s*([A-Za-z_$][\w$.]*)\s*\}/g)) {
+    validatePath(dep[1], ctx, FETCH_USE);
+    const headKey = dep[1].split(".")[0];
+    if (!deps.includes(headKey)) deps.push(headKey);
+  }
+
+  // Auto-declare the four lifecycle keys. `name` is declared via declareState
+  // (collision-checked); the derived keys are seeded directly.
+  const key = declareState(name, null, ctx);
+  ctx.comp.fetchKeys.add(key);
+  /** @type {Record<string, unknown>} */
+  const seeds = { [key]: null };
+  for (const [suffix, seed] of [
+    ["_error", null],
+    ["_loading", false],
+    ["_empty", false]
+  ]) {
+    const k = `${key}${suffix}`;
+    if (!ctx.comp.state.has(k)) ctx.comp.state.set(k, seed);
+    seeds[k] = seed;
+  }
+
+  /** @param {string} n @param {string | null | false | undefined} v */
+  const attr = (n, v) =>
+    v != null && v !== false && v !== "" ? ` data-wd-fetch-${n}="${escapeHtml(v)}"` : "";
+  const marker =
+    `<span data-wd-fetch data-wd-fetch-key="${key}" data-wd-fetch-url="${escapeHtml(url)}"` +
+    attr("method", opts.method && opts.method.toUpperCase()) +
+    attr("when", opts.when === "visible" ? "visible" : "") +
+    attr("timeout", opts.timeout) +
+    attr("retry", opts.retry) +
+    attr("headers", opts.headers && resolveStateKey(opts.headers, ctx)) +
+    attr("body", opts.body && resolveStateKey(opts.body, ctx)) +
+    attr("refresh", opts.refresh) +
+    attr("deps", deps.join(",")) +
+    `></span>`;
+  return `<script type="application/json" data-wd-state>${safeScriptJson(seeds)}</script>${marker}`;
+}
+
+/**
+ * Validate a `:fetch` (or `refresh=`) URL's scheme at compile time. Mirrors the
+ * `:try` href guard: relative paths (`/`, `./`, `../`, bare), an `http(s)://`
+ * URL, or a leading `{ state }` interpolation are allowed; a protocol-relative
+ * `//host` or any non-http(s) scheme (`file:`, `data:`, `javascript:`, …) is
+ * rejected. Interpolated values are percent-encoded by the runtime, so a scheme
+ * cannot be injected through state at request time.
+ * @param {string} url
+ * @param {Ctx} ctx
+ * @param {string} [what] Option name for the error message.
+ * @returns {string}
+ */
+export function validateFetchUrl(url, ctx, what = ":fetch") {
+  const value = url.trim();
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional — rejects control characters in URLs/hrefs.
+  if (value !== url || value === "" || /[\u0000-\u001F\u007F]/.test(value)) {
+    throw new Error(
+      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Use a relative path (/, ./, ../), an http(s):// URL, or a { state } interpolation.`
+    );
+  }
+  if (value.startsWith("//")) {
+    throw new Error(
+      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http:// or https:// explicitly.`
+    );
+  }
+  if (value.startsWith("{")) return value; // interpolation-first; the runtime percent-encodes state values
+  const scheme = value.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+  if (scheme && !["http", "https"].includes(scheme[1].toLowerCase())) {
+    throw new Error(
+      `Unsafe ${what} URL "${escapeHtml(url)}" in ${ctx.file}. The "${scheme[1]}:" scheme is not allowed; use http://, https://, or a relative path.`
+    );
+  }
+  return value;
+}

package/src/compiler/format.js

@@ -48,6 +48,17 @@ function toDate(v) {
 const fmtDate = (d, opts, fallback) =>
   Number.isNaN(d.getTime()) ? String(fallback) : new Intl.DateTimeFormat(undefined, opts).format(d);
 
+/**
+ * A date-ONLY ISO string (`2026-06-22`, no time) parses as UTC midnight, so
+ * formatting it in the build machine's local zone can shift the calendar date a
+ * day (e.g. `Jun 21` west of UTC). Format those in UTC so the output is
+ * deterministic and matches the written date; full datetimes keep local behavior.
+ * @param {unknown} v
+ * @returns {{ timeZone: "UTC" } | undefined}
+ */
+const dateOnlyTZ = (v) =>
+  typeof v === "string" && /^\d{4}-\d{2}-\d{2}$/.test(v.trim()) ? { timeZone: "UTC" } : undefined;
+
 // --- aggregates (shared by pipes and `:computed`) --------------------------
 
 /** @type {Record<string, (list: any[], field?: string) => number>} */
@@ -89,13 +100,15 @@ export const FORMATTERS = {
     const p = 10 ** +dec;
     return Math.round(toNum(v) * p) / p;
   },
-  // dates (format a given instant — pure, no "now")
-  date: (v, [style = "medium"]) => fmtDate(toDate(v), { dateStyle: /** @type {any} */ (style) }, v),
-  time: (v, [style = "short"]) => fmtDate(toDate(v), { timeStyle: /** @type {any} */ (style) }, v),
+  // dates (format a given instant — pure, no "now"; date-only strings in UTC)
+  date: (v, [style = "medium"]) =>
+    fmtDate(toDate(v), { dateStyle: /** @type {any} */ (style), ...dateOnlyTZ(v) }, v),
+  time: (v, [style = "short"]) =>
+    fmtDate(toDate(v), { timeStyle: /** @type {any} */ (style), ...dateOnlyTZ(v) }, v),
   datetime: (v, [ds = "medium", ts = "short"]) =>
     fmtDate(
       toDate(v),
-      { dateStyle: /** @type {any} */ (ds), timeStyle: /** @type {any} */ (ts) },
+      { dateStyle: /** @type {any} */ (ds), timeStyle: /** @type {any} */ (ts), ...dateOnlyTZ(v) },
       v
     ),
   // text

package/src/compiler/forms.js

@@ -0,0 +1,456 @@
+// ---------------------------------------------------------------------------
+// Forms + inputs: `:form` (client state / native post / fetch round-trip) and
+// the field directives that feed it — `:input`, `:textarea`, `:select`,
+// `:checkbox`/`:radio` groups, `:submit` — plus the two-way bound controls
+// `:bind` and `:slider`.
+//
+// Every handler receives the 0-based line `index` so its malformed/invalid
+// errors report `file:line` (via `at`) — matching the unclosed-block errors —
+// while keeping the message text and `Use:` hints intact.
+// ---------------------------------------------------------------------------
+
+import { at, nestedCtx } from "./context.js";
+import { validateFetchUrl } from "./fetch.js";
+import {
+  escapeHtml,
+  humanizeName,
+  parseStateValue,
+  resolveStateKey,
+  safeScriptJson,
+  stripQuotes
+} from "./interpolation.js";
+import { declareErrorState, declareState } from "./state.js";
+
+/**
+ * @typedef {import("./context.js").Ctx} Ctx
+ */
+
+/**
+ * @param {string} line
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleForm(line, bodyLines, ctx, index) {
+  const rest = line.slice(":form".length).trim();
+  const rawAction = rest.match(/action="([^"]+)"/)?.[1];
+  const method = rest.match(/method="([^"]+)"/)?.[1] || "post";
+  const into = rest.match(/(?:^|\s)into\s+([A-Za-z_$][\w$]*)/)?.[1];
+  const leftover = rest
+    .replace(/action="[^"]+"/, "")
+    .replace(/method="[^"]+"/, "")
+    .replace(/(?:^|\s)into\s+[A-Za-z_$][\w$]*/, "")
+    .trim();
+  if ((!rawAction && !into) || leftover) {
+    throw new Error(
+      `Malformed :form in ${at(ctx, index)}: ${line}. Use ':form into name' (client state), ':form action="/url"' (native post), or both (fetch round-trip into state).`
+    );
+  }
+  const action = rawAction ? validateFetchUrl(rawAction, ctx, ":form action") : undefined;
+  const inner = ctx.compileBody(bodyLines, nestedCtx(ctx, index + 1)).trim();
+  if (!into) {
+    return `<form action="${escapeHtml(action)}" method="${escapeHtml(method)}">${inner}</form>`;
+  }
+  const key = declareState(into, null, ctx);
+  declareErrorState(key, ctx);
+  const actionAttrs = action
+    ? ` action="${escapeHtml(action)}" method="${escapeHtml(method)}"`
+    : "";
+  return `<script type="application/json" data-wd-state>${safeScriptJson({ [key]: null })}</script><form data-wd-form="${key}"${actionAttrs}>${inner}</form>`;
+}
+
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleInput(line, ctx, index) {
+  const match = line.match(/^:input\s+([A-Za-z_][\w-]*)\s*(.*)$/);
+  if (!match) throw new Error(`Malformed :input in ${at(ctx, index)}: ${line}`);
+  const attrs = [`name="${escapeHtml(match[1])}"`];
+  let type = "text";
+  let placeholder;
+  let hasAria = false;
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[3]) {
+      if (!["required", "autofocus", "disabled", "readonly"].includes(token[3])) {
+        throw new Error(`Unknown :input flag "${token[3]}" in ${at(ctx, index)}`);
+      }
+      attrs.push(token[3]);
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (token[1] === "type") {
+      type = value;
+      continue;
+    }
+    if (
+      ![
+        "placeholder",
+        "value",
+        "min",
+        "max",
+        "step",
+        "pattern",
+        "autocomplete",
+        "aria-label",
+        "aria-describedby"
+      ].includes(token[1])
+    ) {
+      throw new Error(`Unknown :input attribute "${token[1]}" in ${at(ctx, index)}`);
+    }
+    if (token[1] === "placeholder") placeholder = value;
+    if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
+    attrs.push(`${token[1]}="${escapeHtml(value)}"`);
+  }
+  // Accessible name: if the author supplied neither aria-label nor aria-describedby,
+  // derive a non-visual aria-label from the placeholder, else from the field name.
+  // Never overrides an author-supplied aria attribute (zero layout impact).
+  if (!hasAria) {
+    attrs.push(`aria-label="${escapeHtml(placeholder || humanizeName(match[1]))}"`);
+  }
+  return `<input type="${escapeHtml(type)}" ${attrs.join(" ")}>`;
+}
+
+// :bind <state> [placeholder="…"] [type=…] — a live two-way input bound to a
+// declared :state. Updates state on every keystroke; reflects state back when
+// not focused. The state must be declared first (with :state).
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleBind(line, ctx, index) {
+  const match = line.match(/^:bind\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
+  if (!match)
+    throw new Error(
+      `Malformed :bind in ${at(ctx, index)}: ${line}. Use: :bind query placeholder="Search"`
+    );
+  const key = resolveStateKey(match[1], ctx);
+  if (!key) {
+    throw new Error(
+      `:bind ${match[1]} in ${ctx.file} has no matching state. Declare it first: :state ${match[1]} = ""`
+    );
+  }
+  ctx.comp.assets.runtime = true;
+  let type = "text";
+  let placeholder;
+  let hasAria = false;
+  const attrs = [];
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[3]) {
+      if (!["required", "autofocus"].includes(token[3]))
+        throw new Error(`Unknown :bind flag "${token[3]}" in ${at(ctx, index)}`);
+      attrs.push(token[3]);
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (token[1] === "type") {
+      type = value;
+      continue;
+    }
+    if (!["placeholder", "autocomplete", "aria-label", "aria-describedby"].includes(token[1])) {
+      throw new Error(`Unknown :bind attribute "${token[1]}" in ${at(ctx, index)}`);
+    }
+    if (token[1] === "placeholder") placeholder = value;
+    if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
+    attrs.push(`${token[1]}="${escapeHtml(value)}"`);
+  }
+  // Accessible name (see handleInput): default a non-visual aria-label from the
+  // placeholder, else a humanized version of the bound state key. The author's own
+  // aria-label/aria-describedby always wins.
+  if (!hasAria) {
+    attrs.push(`aria-label="${escapeHtml(placeholder || humanizeName(match[1]))}"`);
+  }
+  const initial = ctx.comp.state.get(key);
+  const valueAttr =
+    initial === undefined || initial === null ? "" : ` value="${escapeHtml(String(initial))}"`;
+  return `<input type="${escapeHtml(type)}" data-wd-bind-input="${key}"${valueAttr} ${attrs.join(" ")}>`;
+}
+
+/**
+ * `:slider name [= value] [min=N] [max=N] [step=N] [aria-label="…"] [persist]` — a
+ * range input two-way bound to a NUMBER :state. With `= value` it declares the state
+ * inline (seeding it numeric) and may `persist`; without `=` it binds to an already-
+ * declared :state. Pure compile-time: it reuses the runtime's input binding (range
+ * values coerce to Number), so it ships NO behavior module.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSlider(line, ctx, index) {
+  const head = line.match(/^:slider\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
+  if (!head)
+    throw new Error(
+      `Malformed :slider in ${at(ctx, index)}: ${line}. Use: :slider volume = 50 min=0 max=100 step=1`
+    );
+  const name = head[1];
+  let rest = head[2].trim();
+
+  /** @type {string | undefined} */
+  let initialRaw;
+  if (rest.startsWith("=")) {
+    const valueMatch = rest.match(/^=\s*(\S+)\s*(.*)$/);
+    if (!valueMatch)
+      throw new Error(
+        `Malformed :slider initial value in ${at(ctx, index)}: ${line}. Use: :slider ${name} = 50`
+      );
+    initialRaw = valueMatch[1];
+    rest = valueMatch[2].trim();
+  }
+
+  let min = "0";
+  let max = "100";
+  let step = "1";
+  /** @type {string | undefined} */
+  let ariaLabel;
+  let persist = false;
+  for (const token of rest.matchAll(/([A-Za-z-]+)=("[^"]*"|\S+)|(\bpersist\b)/g)) {
+    if (token[3]) {
+      persist = true;
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (token[1] === "min") min = value;
+    else if (token[1] === "max") max = value;
+    else if (token[1] === "step") step = value;
+    else if (token[1] === "aria-label") ariaLabel = value;
+    else throw new Error(`Unknown :slider attribute "${token[1]}" in ${at(ctx, index)}`);
+  }
+  for (const [label, raw] of [
+    ["min", min],
+    ["max", max],
+    ["step", step]
+  ]) {
+    if (!/^-?\d+(?:\.\d+)?$/.test(raw))
+      throw new Error(`:slider ${label} must be a number in ${at(ctx, index)}: ${raw}`);
+  }
+
+  ctx.comp.assets.runtime = true;
+  /** @type {string} */
+  let key;
+  let seed = "";
+  if (initialRaw !== undefined) {
+    const value = parseStateValue(initialRaw, at(ctx, index));
+    if (typeof value !== "number")
+      throw new Error(
+        `:slider ${name} initial value must be a number in ${at(ctx, index)}: ${initialRaw}`
+      );
+    key = declareState(name, value, ctx);
+    const persistAttr = persist ? ` data-wd-persist="${key}"` : "";
+    seed = `<script type="application/json" data-wd-state${persistAttr}>${safeScriptJson({ [key]: value })}</script>`;
+  } else {
+    if (persist)
+      throw new Error(
+        `:slider persist only applies when declaring state inline (:slider ${name} = 0 … persist) in ${at(ctx, index)}`
+      );
+    const resolved = resolveStateKey(name, ctx);
+    if (!resolved)
+      throw new Error(
+        `:slider ${name} in ${ctx.file} has no matching state. Declare it: :slider ${name} = 0 min=0 max=100`
+      );
+    key = resolved;
+  }
+
+  const initial = ctx.comp.state.get(key);
+  const valueAttr =
+    initial === undefined || initial === null ? "" : ` value="${escapeHtml(String(initial))}"`;
+  const ariaAttr = ` aria-label="${escapeHtml(ariaLabel || humanizeName(name))}"`;
+  return `${seed}<input type="range" data-wd-bind-input="${key}" min="${escapeHtml(min)}" max="${escapeHtml(max)}" step="${escapeHtml(step)}"${valueAttr}${ariaAttr}>`;
+}
+
+/**
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSubmit(line, ctx, index) {
+  const match = line.match(/^:submit\s+"([^"]+)"\s*$/);
+  if (!match)
+    throw new Error(`Malformed :submit in ${at(ctx, index)}: ${line}. Use: :submit "Label"`);
+  return `<button type="submit">${escapeHtml(match[1])}</button>`;
+}
+
+/**
+ * `:textarea name [placeholder="…"] [rows=N] [required]` → a `<textarea>`. Like
+ * `:input`, it derives a non-visual aria-label from the placeholder (else the
+ * humanized name) when the author supplies none. Captured by the runtime's
+ * FormData exactly like `:input` — no runtime change needed.
+ * @param {string} line
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleTextarea(line, ctx, index) {
+  const match = line.match(/^:textarea\s+([A-Za-z_][\w-]*)\s*(.*)$/);
+  if (!match)
+    throw new Error(
+      `Malformed :textarea in ${at(ctx, index)}: ${line}. Use: :textarea name [placeholder="…"] [rows=N] [required]`
+    );
+  const attrs = [`name="${escapeHtml(match[1])}"`];
+  let placeholder;
+  let hasAria = false;
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[3]) {
+      if (!["required", "autofocus", "disabled", "readonly"].includes(token[3])) {
+        throw new Error(`Unknown :textarea flag "${token[3]}" in ${at(ctx, index)}`);
+      }
+      attrs.push(token[3]);
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (
+      ![
+        "placeholder",
+        "rows",
+        "cols",
+        "minlength",
+        "maxlength",
+        "autocomplete",
+        "aria-label",
+        "aria-describedby"
+      ].includes(token[1])
+    ) {
+      throw new Error(`Unknown :textarea attribute "${token[1]}" in ${at(ctx, index)}`);
+    }
+    if (token[1] === "placeholder") placeholder = value;
+    if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
+    attrs.push(`${token[1]}="${escapeHtml(value)}"`);
+  }
+  if (!hasAria) {
+    attrs.push(`aria-label="${escapeHtml(placeholder || humanizeName(match[1]))}"`);
+  }
+  return `<textarea ${attrs.join(" ")}></textarea>`;
+}
+
+/**
+ * `:select name [required]` followed by `- Label` list lines → a `<select>` with
+ * one `<option>` per label (value === label). Derives an aria-label from the
+ * humanized name when none is given. Captured by FormData like the other fields.
+ * @param {string} line
+ * @param {string[]} optionLines The following `- Label` lines consumed by dispatch.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleSelect(line, optionLines, ctx, index) {
+  const match = line.match(/^:select\s+([A-Za-z_][\w-]*)\s*(.*)$/);
+  if (!match)
+    throw new Error(
+      `Malformed :select in ${at(ctx, index)}: ${line}. Use: :select name [required] then "- Label" lines`
+    );
+  const attrs = [`name="${escapeHtml(match[1])}"`];
+  let hasAria = false;
+  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 :select flag "${token[3]}" in ${at(ctx, index)}`);
+      }
+      attrs.push(token[3]);
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (!["autocomplete", "aria-label", "aria-describedby"].includes(token[1])) {
+      throw new Error(`Unknown :select attribute "${token[1]}" in ${at(ctx, index)}`);
+    }
+    if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
+    attrs.push(`${token[1]}="${escapeHtml(value)}"`);
+  }
+  if (!hasAria) {
+    attrs.push(`aria-label="${escapeHtml(humanizeName(match[1]))}"`);
+  }
+  const options = optionLines.map((l) => l.replace(/^\s*-\s+/, "").trim()).filter(Boolean);
+  if (!options.length) {
+    throw new Error(
+      `:select "${match[1]}" in ${at(ctx, index)} has no options. Add "- Label" lines beneath it.`
+    );
+  }
+  const opts = options
+    .map((o) => `<option value="${escapeHtml(o)}">${escapeHtml(o)}</option>`)
+    .join("");
+  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
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @returns {string}
+ */
+export function handleChoiceGroup(line, optionLines, ctx, kind, index) {
+  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 ${at(ctx, index)}: ${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 ${at(ctx, index)}`);
+      }
+      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 ${at(ctx, index)}`);
+  }
+  const options = optionLines.map((l) => l.replace(/^\s*-\s+/, "").trim()).filter(Boolean);
+  if (!options.length) {
+    throw new Error(
+      `${directive} "${name}" in ${at(ctx, index)} 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>`;
+}