@zvndev/darkmown 2.6.1-next.11.g82bb8d7 → 2.7.0

package/src/compiler/structure.js

@@ -1,8 +1,8 @@
 // ---------------------------------------------------------------------------
 // Structure: the directives that shape a page's tree — `@include` (sub-file
 // compile + scoped-skin stamp), `::: container` sections, `:if` conditional
-// regions, the `:carousel` block — plus the documentation-demo directives
-// (`:try`/`:note`/`:sprint`). Nested block bodies recurse through
+// regions, the `:carousel` block — plus the documentation-demo directive
+// `:try`. Nested block bodies recurse through
 // `ctx.compileBody` (and `@include` through `ctx.compileFile`), threaded in by
 // the per-file compile so the module graph stays an import-cycle-free DAG.
 //
@@ -12,7 +12,6 @@
 // ---------------------------------------------------------------------------
 
 import { at, createScope, LOOP_META, lineOf, nestedCtx, recordSymbol, wdError } from "./context.js";
-import { astOf, serializeExpr } from "./expr-ast.js";
 import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
 import {
   escapeHtml,
@@ -22,6 +21,7 @@ import {
   parseScalar,
   resolveStateKey
 } from "./interpolation.js";
+import { astAt, serializeExprAt } from "./loops.js";
 import { compileWhen, evalPredicate } from "./predicates.js";
 
 /**
@@ -31,6 +31,9 @@ import { compileWhen, evalPredicate } from "./predicates.js";
 // Concrete, compilable structure examples for the hint tails + the catalog.
 export const INCLUDE_EXAMPLE = "@include /header.wd";
 export const CONTAINER_EXAMPLE = "::: card .featured";
+// The same header carrying the accessibility attributes the whitelist allows —
+// the WD650/WD651 hint tail, so a rejected attribute shows the accepted shape.
+export const CONTAINER_A11Y_EXAMPLE = '::: card .note role="region" aria-label="Notes"';
 export const IF_EXAMPLE = ":if count > 0";
 export const CAROUSEL_EXAMPLE = ":carousel autoplay=3000";
 const INCLUDE_USE = `Use: @include /partial.wd [with key="value"] — e.g. ${INCLUDE_EXAMPLE}`;
@@ -43,6 +46,105 @@ const INCLUDE_USE = `Use: @include /partial.wd [with key="value"] — e.g. ${INC
 // author-supplied — so no tag-injection surface; classes/ids still escape.
 const SEMANTIC_CONTAINER_TAGS = new Set(["nav", "main"]);
 
+// ---------------------------------------------------------------------------
+// The accessibility attribute whitelist, shared by `::: container` headers and
+// `:button` lines.
+//
+// A disclosure widget, a tab list, a menu, or a semantic table needs `role` and
+// `aria-*` on the elements the compiler emits, and until now neither directive
+// accepted any attribute at all — so those patterns simply could not be built
+// (audit 8.3). This opens exactly three shapes and nothing else:
+//
+//   role="…"       one ARIA role
+//   aria-*="…"     any `aria-` attribute
+//   title="…"      the native advisory title
+//
+// The value is STATIC quoted text; it is HTML-escaped on emit. There is no
+// `{ state }` interpolation in an attribute value in this pass — a reactive
+// `aria-expanded` would need a runtime attribute binding, which does not exist.
+// Everything else (`onclick`, `style`, `href`, `class`, `data-*`, `id=`) is a
+// compile error naming the whitelist, so the directive surface cannot quietly
+// become "arbitrary HTML attributes".
+// ---------------------------------------------------------------------------
+
+/** The corrective `Use:` tail every attribute error carries. */
+export const A11Y_ATTR_USE = 'role="…", aria-…="…", or title="…" (quoted static text)';
+
+// `aria-` plus at least one lowercase letter; `role`/`title` exactly. Names are
+// matched against this whitelist, so an emitted name can never carry markup.
+const A11Y_ATTR_NAME = /^(?:role|title|aria-[a-z][a-z0-9-]*)$/;
+
+// One `name="value"` pair at the cursor. The value cannot contain `"`, so the
+// pair always ends where it looks like it ends.
+const ATTR_PAIR = /^([A-Za-z][A-Za-z0-9-]*)="([^"]*)"/;
+// Anything that OPENS like an attribute, so a rejected one gets the whitelist
+// error rather than the generic "unexpected token".
+const ATTR_START = /^([A-Za-z][A-Za-z0-9-]*)\s*=/;
+
+/**
+ * Peel the leading run of whitelisted accessibility attributes off `rest`.
+ *
+ * Stops at the first token that does not open like an attribute (a `.class`, a
+ * `#id`, a `->`, or the end of the line) and hands that remainder back. A token
+ * that DOES open like an attribute but is misspelt, unquoted, or outside the
+ * whitelist is a compile error — never silently skipped.
+ * @param {string} rest Everything from the cursor to the end of the line.
+ * @param {Ctx} ctx
+ * @param {number} index 0-based line index for `file:line` errors.
+ * @param {string} what Directive label for the message, e.g. `:button`.
+ * @returns {{ attrs: [string, string][], rest: string }}
+ */
+export function takeA11yAttrs(rest, ctx, index, what) {
+  /** @type {[string, string][]} */
+  const attrs = [];
+  let s = rest.trim();
+  for (let start = s.match(ATTR_START); start; start = s.match(ATTR_START)) {
+    // The NAME is checked before the quoting, so `onclick=x` reports the
+    // whitelist (the attribute is the problem) rather than sending the author
+    // off to add quotes to something that will still be rejected.
+    if (!A11Y_ATTR_NAME.test(start[1])) {
+      throw wdError(
+        `Attribute "${start[1]}" is not allowed in ${what} at ${at(ctx, index)}. ` +
+          `Only accessibility attributes are: ${A11Y_ATTR_USE}`,
+        {
+          code: "WD650",
+          file: ctx.file,
+          line: lineOf(ctx, index),
+          hint: A11Y_ATTR_USE,
+          example: CONTAINER_A11Y_EXAMPLE
+        }
+      );
+    }
+    const pair = s.match(ATTR_PAIR);
+    if (!pair) {
+      throw wdError(
+        `Attribute "${start[1]}" in ${what} at ${at(ctx, index)} needs a double-quoted value. Use: ${A11Y_ATTR_USE}`,
+        {
+          code: "WD651",
+          file: ctx.file,
+          line: lineOf(ctx, index),
+          hint: A11Y_ATTR_USE,
+          example: CONTAINER_A11Y_EXAMPLE
+        }
+      );
+    }
+    attrs.push([pair[1], pair[2]]);
+    s = s.slice(pair[0].length).trim();
+  }
+  return { attrs, rest: s };
+}
+
+/**
+ * Serialize validated attribute pairs into an HTML attribute string. The NAME
+ * came through {@link A11Y_ATTR_NAME} so it is inert; the VALUE is author text
+ * and is escaped.
+ * @param {[string, string][]} attrs
+ * @returns {string}
+ */
+export function a11yAttrHtml(attrs) {
+  return attrs.map(([name, value]) => ` ${name}="${escapeHtml(value)}"`).join("");
+}
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -138,13 +240,20 @@ export function handleContainer(header, bodyLines, ctx, index) {
   const eachClasses = [];
   /** @type {[string, any[]][]} Global state-driven class bindings (data-wd-class): [class, exprAST]. */
   const stateClasses = [];
+  /** @type {[string, string][]} Whitelisted accessibility attributes: [name, value]. */
+  const a11y = [];
   let id = "";
   // Leading tag/name token (anything not starting with . or #). "section" keeps
   // the <section> tag; a whitelisted semantic landmark (`nav`/`main`) emits that
   // real element AND keeps the name as a class hook (so `.nav`/`.main` skins
   // still cascade); any other name becomes a <div> and also a class. The tag is
   // always one of these fixed constants — never author text — so it can't inject.
-  const lead = rest.match(/^([^\s.#]\S*)/);
+  // …unless the header OPENS with an attribute (`::: role="region" .card`), which
+  // `^([^\s.#]\S*)` would otherwise swallow whole and emit as a class:
+  // `class="role=&quot;region&quot; card"`. An attribute in first position leaves
+  // the tag at its default and falls through to the token loop below, so both
+  // orders work — `::: nav role="navigation"` still gets the <nav> element.
+  const lead = ATTR_START.test(rest) ? null : rest.match(/^([^\s.#]\S*)/);
   let nameToken = "section";
   if (lead) {
     nameToken = lead[1];
@@ -166,6 +275,16 @@ export function handleContainer(header, bodyLines, ctx, index) {
       rest = rest.slice((m ? m[0] : rest).length).trim();
       continue;
     }
+    // `role="…"` / `aria-…="…"` / `title="…"`, in any position among the class
+    // and id tokens. A token that opens like an attribute but is not on the
+    // whitelist throws here rather than reaching the generic unexpected-token
+    // error, so the message names what IS allowed.
+    const taken = takeA11yAttrs(rest, ctx, index, `container "::: ${header.trim()}"`);
+    if (taken.attrs.length) {
+      a11y.push(...taken.attrs);
+      rest = taken.rest;
+      continue;
+    }
     const cm = rest.match(/^\.([A-Za-z_][\w-]*)/);
     if (!cm)
       throw wdError(
@@ -176,14 +295,18 @@ export function handleContainer(header, bodyLines, ctx, index) {
     rest = rest.slice(cm[0].length).trim();
     // Optional `when <predicate>` makes the class reactive. The predicate runs to
     // the next ` .`/` #` token or the end of the header.
-    const whenMatch = rest.match(/^when\s+(.+?)(?=\s+[.#]|$)/);
+    // The predicate runs to the next ` .`/` #` token, the next ATTRIBUTE token,
+    // or the end of the header — without the attribute stop, `.live when a == b
+    // role="status"` swallowed the attribute into the predicate.
+    const whenMatch = rest.match(/^when\s+(.+?)(?=\s+[.#]|\s+[A-Za-z][A-Za-z0-9-]*\s*=|$)/);
     if (whenMatch) {
       rest = rest.slice(whenMatch[0].length).trim();
       const compiled = compileWhen(whenMatch[1].trim(), ctx);
       if (compiled.static) {
         if (compiled.value) extraClass.push(cls);
-      } else if (compiled.item) eachClasses.push([cls, astOf(compiled.body)]);
-      else stateClasses.push([cls, astOf(compiled.body)]);
+      } else if (compiled.item)
+        eachClasses.push([cls, astAt(compiled.body, ctx, index, '"::: … when"')]);
+      else stateClasses.push([cls, astAt(compiled.body, ctx, index, '"::: … when"')]);
     } else {
       extraClass.push(cls);
     }
@@ -200,6 +323,7 @@ export function handleContainer(header, bodyLines, ctx, index) {
   }
   const idAttr = explicitId ? ` id="${escapeHtml(id)}"` : "";
   const classAttr = extraClass.length ? ` class="${escapeHtml(extraClass.join(" "))}"` : "";
+  const a11yAttr = a11yAttrHtml(a11y);
   let classBind = "";
   if (eachClasses.length) {
     ctx.comp.assets.runtime = true;
@@ -209,7 +333,7 @@ export function handleContainer(header, bodyLines, ctx, index) {
     ctx.comp.assets.runtime = true;
     classBind += ` data-wd-class="${escapeHtml(JSON.stringify(stateClasses))}"`;
   }
-  return `<${tag}${idAttr}${classAttr}${classBind}>\n${inner}\n</${tag}>`;
+  return `<${tag}${idAttr}${classAttr}${a11yAttr}${classBind}>\n${inner}\n</${tag}>`;
 }
 
 /**
@@ -288,7 +412,10 @@ function fetchLiveAttr(key, sourceLines, ctx) {
 export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart = index + 1) {
   const truthyCtx = nestedCtx(ctx, index + 1);
   const falsyCtx = nestedCtx(ctx, falsyStart);
-  const condition = line.replace(/^:if\s+/, "").trim();
+  // `\s*` (not `\s+`) so a BARE `:if` yields an empty condition and lands on the
+  // malformed-`:if` error below, instead of falling through with the literal
+  // text `:if` as its condition and reporting a baffling unsupported operand.
+  const condition = line.replace(/^:if\s*/, "").trim();
   recordSymbol(ctx, index, { kind: "if", name: condition, detail: `:if ${condition}` });
   // Fast path: a bare truthy dotted path (`:if open`, `:if item.done`). Keeps the
   // existing markup/behavior identical. Anything with operators (`>`, `==`, `and`,
@@ -313,12 +440,12 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
       // static: the meta boolean is in scope — fall through to the static branch below.
     }
 
-    const staticValue = lookupVar(ctx.scope, head);
-    if (staticValue.found) {
-      const active = Boolean(getPath(staticValue.value, segs.slice(1)));
-      return ctx.compileBody(active ? truthyLines : falsyLines, active ? truthyCtx : falsyCtx);
-    }
-
+    // RESOLUTION ORDER: reactive loop item → static scope → declared state, the
+    // framework-wide order `{ }` interpolation and `@loop … where` already use.
+    // Static scope used to be tried FIRST here, so in a nested static-then-
+    // reactive loop that reuses one item name, `{ it.name }` bound to the
+    // reactive row while `:if it.done` folded against the OUTER static value and
+    // hard-baked a branch with no `data-wd-each-if` — unfixable at runtime.
     if (ctx.loopItem && head === ctx.loopItem) {
       const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
       const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
@@ -327,6 +454,12 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
       return `<span data-wd-each-if${pathAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
     }
 
+    const staticValue = lookupVar(ctx.scope, head);
+    if (staticValue.found) {
+      const active = Boolean(getPath(staticValue.value, segs.slice(1)));
+      return ctx.compileBody(active ? truthyLines : falsyLines, active ? truthyCtx : falsyCtx);
+    }
+
     const key = resolveStateKey(head, ctx);
     if (!key) {
       throw wdError(
@@ -342,7 +475,11 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
     const liveAttr = restPath ? "" : fetchLiveAttr(key, [...truthyLines, ...falsyLines], ctx);
     const initialTruthy = Boolean(getPath(ctx.comp.state.get(key), segs.slice(1)));
     const active = initialTruthy ? truthy : falsy;
-    return `<div data-wd-if="${key}"${pathAttr}${liveAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
+    // The key carries the `::: name #id` section prefix, which is author text.
+    // It is escaped exactly like the `id="…"` attribute beside it — an unescaped
+    // `&`/`"` in a section id closed the attribute early and produced broken
+    // markup with a dead binding.
+    return `<div data-wd-if="${escapeHtml(key)}"${pathAttr}${liveAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
   }
 
   // Predicate path: a comparison / logical condition. Compiles through the same
@@ -368,17 +505,20 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
   ctx.comp.assets.runtime = true;
   const truthy = ctx.compileBody(truthyLines, truthyCtx).trim();
   const falsy = ctx.compileBody(falsyLines, falsyCtx).trim();
-  const exprAttr = ` data-wd-if-expr="${escapeHtml(serializeExpr(compiled.body))}"`;
+  const exprAttr = ` data-wd-if-expr="${escapeHtml(serializeExprAt(compiled.body, ctx, index, '":if"'))}"`;
   if (compiled.item) {
     return `<span data-wd-each-if${exprAttr}><template data-wd-if-true>${truthy}</template><template data-wd-if-false>${falsy}</template><span data-wd-each-if-out></span></span>`;
   }
-  const initialTruthy = evalPredicate(compiled.body, undefined, ctx);
+  const initialTruthy = evalPredicate(compiled.body, undefined, ctx, '":if"');
   const active = initialTruthy ? truthy : falsy;
   return `<div data-wd-if=""${exprAttr} data-wd-if-active="${initialTruthy}"><template data-wd-true>${truthy}</template><template data-wd-false>${falsy}</template><div data-wd-if-out>${active}</div></div>`;
 }
 
 /**
- * Render the documentation-demo directives (`:try`, `:note`, `:sprint`).
+ * Render the documentation-demo directive `:try` (the "Try it" card the homepage
+ * uses). `:note` and `:sprint` lived here too and were deleted: nothing in the
+ * site, the docs, or the public directive set used them, and a directive the
+ * catalog does not list is a trap for an AI author that discovers it in source.
  * @param {string} line
  * @param {Ctx} ctx
  * @returns {string}
@@ -389,16 +529,6 @@ export function renderDemoDirective(line, ctx) {
     const href = validateDemoHref(tryMatch[2], ctx);
     return `<a class="try-card" href="${escapeHtml(href)}"><span>Try</span>${escapeHtml(tryMatch[1])}</a>`;
   }
-  const note = line.match(/^:note\s+"([^"]+)"$/);
-  if (note) return `<aside class="note">${escapeHtml(note[1])}</aside>`;
-  const sprint = line.match(/^:sprint\s+min=(\d+)\s+max=(\d+)\s+roles="([^"]+)"$/);
-  if (sprint) {
-    const roles = sprint[3]
-      .split(",")
-      .map((role) => role.trim())
-      .filter(Boolean);
-    return `<section class="sprint-board" data-min="${sprint[1]}" data-max="${sprint[2]}">${roles.map((role) => `<article><strong>${escapeHtml(role)}</strong><span>active lane</span></article>`).join("")}</section>`;
-  }
   return "";
 }
 

package/src/errors.js

@@ -62,9 +62,16 @@ import {
 } from "./compiler/forms.js";
 import { LOOP_EXAMPLE } from "./compiler/loops.js";
 import { EMBED_EXAMPLE, VIDEO_EXAMPLE } from "./compiler/media.js";
-import { COMPUTED_EXAMPLE, STATE_EXAMPLE, STORE_EXAMPLE, THEME_EXAMPLE } from "./compiler/state.js";
+import {
+  COMPUTED_EXAMPLE,
+  STATE_EXAMPLE,
+  STORE_EXAMPLE,
+  THEME_EXAMPLE,
+  URL_STATE_EXAMPLE
+} from "./compiler/state.js";
 import {
   CAROUSEL_EXAMPLE,
+  CONTAINER_A11Y_EXAMPLE,
   CONTAINER_EXAMPLE,
   IF_EXAMPLE,
   INCLUDE_EXAMPLE
@@ -362,6 +369,20 @@ const ENTRIES = [
     cause: "An entry's value does not match its schema type.",
     fix: "Fix the entry's value, or widen the type in `_schema.wd`."
   },
+  {
+    code: "WD190",
+    title: "Expression could not be compiled",
+    cause:
+      "A `:if` or `::: … when` condition folded a build-time value the expression re-parser cannot read back.",
+    fix: 'Use simpler operands — a field path, a declared `:state`, a plain number, or a `"string"`.'
+  },
+  {
+    code: "WD191",
+    title: "Reactive `@loop` over markdown table rows",
+    cause:
+      "A `@loop` whose body is bare `| … |` cells resolves to a reactive source, and a reactive row is cloned into a `<div>`, which cannot live inside a `<table>`.",
+    fix: "Loop a static source (a JSON file, a frontmatter list, or a collection) for a markdown table — and if the source is already static, drop the `:state` the `where`/`limit`/`sort by` clause reads — or build reactive rows from containers (`::: trow` / `::: td`) instead of `|` cells."
+  },
 
   // --- WD2xx: state and expressions ----------------------------------------
   {
@@ -435,8 +456,9 @@ const ENTRIES = [
   {
     code: "WD211",
     title: "Persistence token on `:computed`",
-    cause: "The expression ends in a bare `persist` or `ephemeral`, which is swallowed into it.",
-    fix: "Computed values are derived, not stored. Persist the state they derive from instead.",
+    cause:
+      "The expression ends in a bare `persist`, `ephemeral`, or `from-url`, which is swallowed into it.",
+    fix: "Computed values are derived, not stored. Put the token on the state they derive from instead.",
     example: COMPUTED_EXAMPLE
   },
   {
@@ -534,6 +556,37 @@ const ENTRIES = [
     fix: "Declare it with `:state`, `:store`, or `:fetch` first.",
     example: COMPUTED_EXAMPLE
   },
+  {
+    code: "WD250",
+    title: "Reserved state declaration name",
+    cause:
+      "A `:state`/`:store`/`:computed`/`:fetch`/`:form`/`:slider`/`:theme` name is `__proto__`, `constructor`, or `prototype`, which the runtime's state object inherits rather than owns.",
+    fix: "Rename the key — any other name works.",
+    example: STATE_EXAMPLE
+  },
+  {
+    code: "WD251",
+    title: "State seeded from another state",
+    cause:
+      "A `:state`/`:store` value is a bare name that is already declared state, so it would be stored as that literal text and never track the value.",
+    fix: "Derive it with `:computed`, or quote the text to keep it literal.",
+    example: COMPUTED_EXAMPLE
+  },
+  {
+    code: "WD260",
+    title: "`from-url` on a keyword that cannot take it",
+    cause:
+      "`:store` and `:theme` are shared by every page and every tab, while a query parameter belongs to one page's address, so the two cannot mean the same thing.",
+    fix: "Declare the value with `:state … from-url`, or drop the token.",
+    example: URL_STATE_EXAMPLE
+  },
+  {
+    code: "WD261",
+    title: "Conflicting persistence modifiers",
+    cause: "A declaration carries `persist` and `ephemeral` at once, or repeats the same modifier.",
+    fix: "Pick one: `persist` keeps the value across reloads, `ephemeral` drops it.",
+    example: STATE_EXAMPLE
+  },
 
   // --- WD3xx: actions ------------------------------------------------------
   {
@@ -627,6 +680,14 @@ const ENTRIES = [
     cause: "The action value is not a quoted string, number, boolean, null, or valid JSON.",
     fix: "Quote strings and use valid JSON for arrays and objects."
   },
+  {
+    code: "WD315",
+    title: "`:every`/`:effect` inside a reactive `@loop`",
+    cause:
+      "A reactive loop clones its body per row, so the timer or watcher would be registered once per row and a removed row's would keep firing.",
+    fix: "Declare it once outside the loop — at page level or inside the `:::` section — and act on the whole list.",
+    example: EVERY_EXAMPLE
+  },
 
   // --- WD4xx: forms and fields ---------------------------------------------
   {
@@ -819,6 +880,32 @@ const ENTRIES = [
     example: RADIO_EXAMPLE
   },
 
+  {
+    code: "WD450",
+    title: "Bound field with no state",
+    cause:
+      "A `:select`/`:radio`/`:checkbox` outside a `:form` names state that is not declared, so there is nothing for it to bind to.",
+    fix: "Declare the state first, or move the field inside a `:form`, where the name is a form field instead.",
+    example: SELECT_EXAMPLE
+  },
+  {
+    code: "WD451",
+    title: "Bound `:checkbox` with several options",
+    cause:
+      "A `:checkbox` bound to state carries one true/false, so a list of options has no meaning.",
+    fix: "Give it one `- Label` line, or use a `:radio` group for a set of choices.",
+    example: CHECKBOX_EXAMPLE
+  },
+
+  {
+    code: "WD452",
+    title: "File field in a GET form",
+    cause:
+      'A `:form` contains an `<input type=file>` and declares `method="get"`. A GET request has no body, so only the file\'s name would travel.',
+    fix: 'Drop `method="get"` — a `:form` posts by default, and a form with a file field is submitted as multipart.',
+    example: FORM_EXAMPLE
+  },
+
   // --- WD5xx: data fetching and URL safety ---------------------------------
   {
     code: "WD501",
@@ -963,6 +1050,21 @@ const ENTRIES = [
       "An `@include` chain reaches a file that is already being compiled, so the compile would never terminate.",
     fix: "Break the loop: remove the `@include` that points back, or move the shared content into a third file both sides include."
   },
+  {
+    code: "WD650",
+    title: "Attribute is not on the accessibility whitelist",
+    cause:
+      "A `::: ` container header or a `:button` carries an attribute outside the accessibility whitelist (`onclick=`, `style=`, `href=`, `class=`, `data-…=`).",
+    fix: 'Keep only `role="…"`, `aria-…="…"`, and `title="…"`; style with `.class` tokens and act with `->` actions.',
+    example: CONTAINER_A11Y_EXAMPLE
+  },
+  {
+    code: "WD651",
+    title: "Accessibility attribute has no quoted value",
+    cause: "An attribute in a container header or a `:button` is missing its double-quoted value.",
+    fix: 'Write the value in double quotes, e.g. `role="region"`.',
+    example: CONTAINER_A11Y_EXAMPLE
+  },
 
   // --- WD7xx: media and embeds ---------------------------------------------
   {
@@ -1063,6 +1165,12 @@ const ENTRIES = [
     title: "Unknown `ai_crawlers` policy",
     cause: "The home page's `ai_crawlers:` is neither `allow` nor `deny`.",
     fix: "Write `ai_crawlers: allow` or `ai_crawlers: deny` (absent means allow)."
+  },
+  {
+    code: "WD950",
+    title: "Invalid `rss_limit`",
+    cause: "The home page's `rss_limit:` is not a positive whole number of items.",
+    fix: "Write `rss_limit: 20` (absent means 20)."
   }
 ];
 

package/src/feeds.js

@@ -190,10 +190,43 @@ export function rssDescription(meta, file, body) {
   return "";
 }
 
+/**
+ * The `<lastmod>` form the sitemap protocol accepts: W3C Datetime, of which
+ * `yyyy-mm-dd` is the shortest legal spelling. Anchored at the start so a full
+ * ISO timestamp (`2026-01-05T10:00:00Z`) matches on its date half.
+ */
+const W3C_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Validate a frontmatter `date:` into a sitemap `<lastmod>` value, or "" when it
+ * is not one.
+ *
+ * This is the only feed value that used to be neither validated nor escaped, and
+ * both halves mattered: `date: 2026<bad&"q"` made the whole document
+ * unparseable, so NOTHING got indexed, and the far likelier `date: Jan 5, 2026`
+ * was silently truncated to `Jan 5, 202` by a blind 10-character slice. Returning
+ * "" (rather than guessing) lets the caller omit the element and say so — a
+ * sitemap entry with no `<lastmod>` is valid; one with a bogus date is not.
+ * @param {string} raw Trimmed frontmatter `date:` value.
+ * @returns {string} `yyyy-mm-dd`, or "" when `raw` is not a real calendar date.
+ */
+export function sitemapDate(raw) {
+  const day = String(raw ?? "")
+    .trim()
+    .slice(0, 10);
+  if (!W3C_DATE.test(day)) return "";
+  // The shape is right; is it a real day? `new Date("2026-02-30")` does NOT
+  // throw — V8 rolls it forward to March 2 — so the only honest check is a round
+  // trip: a genuine calendar date formats back to the string it came from.
+  const parsed = new Date(`${day}T00:00:00Z`);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === day ? day : "";
+}
+
 /**
  * Build `sitemap.xml` from the emitted (post-draft-filter) routes. One `<url>`
  * per route — reactive pages included (they're indexable HTML) — with `<loc>` =
- * `site_url` + path and `<lastmod>` from the supplied date. The `/404/` route is
+ * `site_url` + path and `<lastmod>` from the supplied date. An empty `lastmod`
+ * omits the element rather than emitting a blank one. The `/404/` route is
  * excluded by the caller before this point. No `<priority>`/`<changefreq>` —
  * Google ignores them and they invite bit-rot.
  * @param {DatedRoute[]} entries Absolute loc + ISO lastmod, in route order.
@@ -201,11 +234,15 @@ export function rssDescription(meta, file, body) {
  */
 export function buildSitemap(entries) {
   const urls = entries
-    .map(
-      (entry) =>
-        `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>\n` +
-        `    <lastmod>${entry.lastmod}</lastmod>\n  </url>`
-    )
+    .map((entry) => {
+      const lines = ["  <url>", `    <loc>${escapeXml(entry.loc)}</loc>`];
+      // Escaped even though `sitemapDate` already guarantees a safe value:
+      // this builder is exported and called directly, so the guarantee has to
+      // live where the string is written, not only in one caller.
+      if (entry.lastmod) lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);
+      lines.push("  </url>");
+      return lines.join("\n");
+    })
     .join("\n");
   return (
     '<?xml version="1.0" encoding="UTF-8"?>\n' +
@@ -214,6 +251,67 @@ export function buildSitemap(entries) {
   );
 }
 
+/**
+ * The sitemap protocol's hard cap: 50,000 `<url>` entries per sitemap file. Over
+ * it, Google rejects the document outright — so a large site must split into
+ * numbered sitemaps behind a `<sitemapindex>`.
+ */
+export const SITEMAP_URL_LIMIT = 50000;
+
+/**
+ * Build a `<sitemapindex>` — the document that points at the numbered sitemap
+ * shards. No `<lastmod>` per shard: it would have to be the max over the shard's
+ * entries, which is a number nobody consumes and one more thing to keep true.
+ * @param {string[]} locs Absolute URLs of the shard files, in order.
+ * @returns {string} The full XML document (trailing newline).
+ */
+export function buildSitemapIndex(locs) {
+  const entries = locs
+    .map((loc) => `  <sitemap>\n    <loc>${escapeXml(loc)}</loc>\n  </sitemap>`)
+    .join("\n");
+  return (
+    '<?xml version="1.0" encoding="UTF-8"?>\n' +
+    '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+    `${entries}\n</sitemapindex>\n`
+  );
+}
+
+/**
+ * Plan the sitemap file(s) a set of entries needs.
+ *
+ * At or under {@link SITEMAP_URL_LIMIT} that is one `sitemap.xml`, byte-identical
+ * to what every site got before. Over it, the entries shard into
+ * `sitemap-1.xml`, `sitemap-2.xml`, … and `sitemap.xml` becomes the
+ * `<sitemapindex>` pointing at them — so `robots.txt` keeps naming
+ * `/sitemap.xml` and every existing submission stays valid.
+ *
+ * Returned rather than written so the split is a pure function the tests can
+ * drive with 50,001 synthetic entries without building 50,001 pages.
+ * @param {DatedRoute[]} entries
+ * @param {string} siteUrl Absolute origin, for the index's shard URLs.
+ * @returns {{ file: string, xml: string }[]} Shards first, `sitemap.xml` last.
+ */
+export function sitemapDocuments(entries, siteUrl) {
+  if (entries.length <= SITEMAP_URL_LIMIT) {
+    return [{ file: "sitemap.xml", xml: buildSitemap(entries) }];
+  }
+  /** @type {{ file: string, xml: string }[]} */
+  const shards = [];
+  for (let i = 0; i < entries.length; i += SITEMAP_URL_LIMIT) {
+    shards.push({
+      file: `sitemap-${shards.length + 1}.xml`,
+      xml: buildSitemap(entries.slice(i, i + SITEMAP_URL_LIMIT))
+    });
+  }
+  return [
+    ...shards,
+    {
+      file: "sitemap.xml",
+      xml: buildSitemapIndex(shards.map((shard) => absoluteUrl(siteUrl, `/${shard.file}`)))
+    }
+  ];
+}
+
 /**
  * An RSS item — a dated post in feed order.
  * @typedef {object} RssItem
@@ -392,5 +490,40 @@ export function aiCrawlerPolicy(meta, file) {
   );
 }
 
-/** Most-recent-first RSS post cap — a feed is a recent window, not an archive. */
+/**
+ * The DEFAULT most-recent-first RSS post cap — a feed is a recent window, not an
+ * archive. Overridable per site with `rss_limit:` on the home page
+ * ({@link rssItemLimit}).
+ */
 export const RSS_ITEM_LIMIT = 20;
+
+/**
+ * Resolve the site's RSS item cap from the HOME page's `rss_limit:` frontmatter.
+ *
+ * Darkmown has no config file by design: site-wide settings live in the home
+ * page's frontmatter next to `site_url` / `ai_crawlers`, and this is one of them.
+ * Absent means {@link RSS_ITEM_LIMIT}. A value that is not a positive integer
+ * THROWS rather than silently falling back, for the same reason `ai_crawlers`
+ * does: `rss_limit: 0` and `rss_limit: all` are both attempts to state a policy,
+ * and quietly publishing 20 items instead is the wrong failure direction.
+ * @param {import("./compiler.js").Meta} meta Home page frontmatter.
+ * @param {string} [file] Home page source path, for the error message.
+ * @returns {number} A positive integer.
+ */
+export function rssItemLimit(meta, file) {
+  const raw = meta.rss_limit;
+  if (raw === undefined) return RSS_ITEM_LIMIT;
+  const text = String(raw).trim();
+  // `Number("")` is 0 and `Number("12px")` is NaN — both fail the guard below,
+  // so an empty or non-numeric value lands on the same actionable error.
+  // Digits only: `Number()` would also accept "1e3", "0x10" and "7.0", none
+  // of which is the "positive whole number" the error promises.
+  const value = /^\d+$/.test(text) ? Number(text) : Number.NaN;
+  if (Number.isInteger(value) && value > 0) return value;
+  const hint = "rss_limit: 20";
+  throw wdError(
+    `Invalid rss_limit "${text}"${file ? ` in ${file}` : ""}. ` +
+      `Use a positive whole number of items: ${hint}.`,
+    { code: "WD950", file, hint }
+  );
+}