@zvndev/darkmown 1.4.0 → 2.0.0

package/src/compiler/body.js

@@ -82,9 +82,9 @@ export function compileBody(lines, ctx) {
     }
     if (/^@loop\s/.test(line)) {
       flush();
-      const block = scanBlock(lines, i, /^@loop\s/, "@endloop", ctx.file);
+      const block = scanBlock(lines, i, /^@loop\s/, "@endloop", ctx);
       const split = splitEmptyBranch(block.body);
-      out.push(handleLoop(line, split.body, split.empty, ctx));
+      out.push(handleLoop(line, split.body, split.empty, ctx, i, split.emptyStart));
       i = block.end;
       continue;
     }
@@ -93,7 +93,7 @@ export function compileBody(lines, ctx) {
       flush();
       if (!container[1].trim())
         throw new Error(`Stray ::: close with no open container in ${ctx.file}`);
-      const block = scanContainer(lines, i, ctx.file);
+      const block = scanContainer(lines, i, ctx);
       out.push(handleContainer(container[1].trim(), block.body, ctx, i));
       i = block.end;
       continue;
@@ -152,14 +152,14 @@ export function compileBody(lines, ctx) {
     }
     if (/^:form\s/.test(line)) {
       flush();
-      const block = scanBlock(lines, i, /^:form\s/, ":endform", ctx.file);
+      const block = scanBlock(lines, i, /^:form\s/, ":endform", ctx);
       out.push(handleForm(line, block.body, ctx, i));
       i = block.end;
       continue;
     }
     if (/^:carousel(?:\s|$)/.test(line)) {
       flush();
-      const block = scanBlock(lines, i, /^:carousel(?:\s|$)/, ":endcarousel", ctx.file);
+      const block = scanBlock(lines, i, /^:carousel(?:\s|$)/, ":endcarousel", ctx);
       out.push(handleCarousel(line, block.body, ctx, i));
       i = block.end;
       continue;
@@ -223,8 +223,8 @@ export function compileBody(lines, ctx) {
     }
     if (/^:if\s/.test(line)) {
       flush();
-      const block = scanConditional(lines, i, ctx.file);
-      out.push(handleIf(line, block.truthy, block.falsy, ctx, i));
+      const block = scanConditional(lines, i, ctx);
+      out.push(handleIf(line, block.truthy, block.falsy, ctx, i, block.falsyStart));
       i = block.end;
       continue;
     }
@@ -342,10 +342,10 @@ function joinValueDirective(lines, start) {
  * @param {number} start Index of the opening line.
  * @param {RegExp} openRe Pattern that re-opens a nested block.
  * @param {string} endToken Literal closing token (e.g. `@endloop`).
- * @param {string} file Source path for errors.
+ * @param {Ctx} ctx Compile context, for `file:line` errors.
  * @returns {{ body: string[], end: number }}
  */
-function scanBlock(lines, start, openRe, endToken, file) {
+function scanBlock(lines, start, openRe, endToken, ctx) {
   /** @type {string[]} */
   const body = [];
   let depth = 0;
@@ -371,25 +371,29 @@ function scanBlock(lines, start, openRe, endToken, file) {
     }
     body.push(line);
   }
-  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${at(file, start)}`);
+  throw new Error(`Missing ${endToken} for "${lines[start]}" in ${at(ctx, start)}`);
 }
 
 /**
  * Split a `@loop` body at a top-level `@empty` into the rows body and the empty
  * branch. Honors nested `@loop … @endloop` (so an inner loop's `@empty` is not
- * mistaken for the outer one) and fenced code.
+ * mistaken for the outer one) and fenced code. `emptyStart` is the index within
+ * `body` the empty branch starts at (the line after `@empty`), so nested errors
+ * in that branch still report the true file line.
  * @param {string[]} body
- * @returns {{ body: string[], empty: string[] | null }}
+ * @returns {{ body: string[], empty: string[] | null, emptyStart: number }}
  */
 function splitEmptyBranch(body) {
   /** @type {string[]} */
   const rows = [];
   /** @type {string[] | null} */
   let empty = null;
+  let emptyStart = 0;
   let target = rows;
   let depth = 0;
   let fence = null;
-  for (const line of body) {
+  for (let i = 0; i < body.length; i++) {
+    const line = body[i];
     const fenceMatch = line.match(/^(```+|~~~+)/);
     if (fence) {
       if (fenceMatch && fenceMatch[1][0] === fence[0] && fenceMatch[1].length >= fence.length)
@@ -406,22 +410,23 @@ function splitEmptyBranch(body) {
     if (line.trim() === "@endloop") depth--;
     if (depth === 0 && line.trim() === "@empty") {
       empty = [];
+      emptyStart = i + 1;
       target = empty;
       continue;
     }
     target.push(line);
   }
-  return { body: rows, empty };
+  return { body: rows, empty, emptyStart };
 }
 
 /**
  * Capture the body of a `:::` container up to its matching close, honoring nesting.
  * @param {string[]} lines
  * @param {number} start Index of the opening line.
- * @param {string} file Source path for errors.
+ * @param {Ctx} ctx Compile context, for `file:line` errors.
  * @returns {{ body: string[], end: number }}
  */
-function scanContainer(lines, start, file) {
+function scanContainer(lines, start, ctx) {
   /** @type {string[]} */
   const body = [];
   let depth = 0;
@@ -452,7 +457,7 @@ function scanContainer(lines, start, file) {
     }
     body.push(line);
   }
-  throw new Error(`Missing closing ::: for "${lines[start]}" in ${at(file, start)}`);
+  throw new Error(`Missing closing ::: for "${lines[start]}" in ${at(ctx, start)}`);
 }
 
 /**
@@ -463,16 +468,21 @@ function scanContainer(lines, start, file) {
  * `compileBody`/`handleIf` recursively. A whole `:if/:else if/:else` chain
  * therefore compiles to nested `data-wd-if` regions the runtime already drives —
  * identical behavior for static, reactive, and loop-row conditionals.
+ *
+ * `falsyStart` is the index within `lines` the falsy body starts at — the line
+ * after a bare `:else`, or the `:else if` line itself (its synthesized `:if`
+ * stands in for it) — so nested errors in that branch report the true file line.
  * @param {string[]} lines
  * @param {number} start Index of the `:if` line.
- * @param {string} file Source path for errors.
- * @returns {{ truthy: string[], falsy: string[], end: number }}
+ * @param {Ctx} ctx Compile context, for `file:line` errors.
+ * @returns {{ truthy: string[], falsy: string[], end: number, falsyStart: number }}
  */
-function scanConditional(lines, start, file) {
+function scanConditional(lines, start, ctx) {
   /** @type {string[]} */
   const truthy = [];
   /** @type {string[]} */
   const falsy = [];
+  let falsyStart = start + 1;
   let current = truthy;
   // "truthy": collecting the :if body. "else": a bare :else closed the chain —
   // no further branches allowed. "elseif": the first :else if was desugared into
@@ -499,7 +509,7 @@ function scanConditional(lines, start, file) {
     if (line.trim() === ":endif") {
       if (depth === 0) {
         if (mode === "elseif") falsy.push(":endif"); // close the synthesized nested :if
-        return { truthy, falsy, end: i };
+        return { truthy, falsy, end: i, falsyStart };
       }
       depth--;
     }
@@ -509,9 +519,10 @@ function scanConditional(lines, start, file) {
       if (elseIf) {
         if (mode === "else")
           throw new Error(
-            `":else if" after ":else" in ${file}. ":else" must be the last branch — order the "else if" conditions before the bare ":else".`
+            `":else if" after ":else" in ${ctx.file}. ":else" must be the last branch — order the "else if" conditions before the bare ":else".`
           );
         falsy.push(`:if ${elseIf[1]}`); // desugar the chain tail into a nested :if
+        falsyStart = i;
         current = falsy;
         mode = "elseif";
         continue;
@@ -519,8 +530,9 @@ function scanConditional(lines, start, file) {
       if (t === ":else") {
         if (mode === "else")
           throw new Error(
-            `Duplicate ":else" in ${file}. A conditional may have only one bare ":else".`
+            `Duplicate ":else" in ${ctx.file}. A conditional may have only one bare ":else".`
           );
+        falsyStart = i + 1;
         current = falsy;
         mode = "else";
         continue;
@@ -528,5 +540,5 @@ function scanConditional(lines, start, file) {
     }
     current.push(line);
   }
-  throw new Error(`Missing :endif for "${lines[start]}" in ${at(file, start)}`);
+  throw new Error(`Missing :endif for "${lines[start]}" in ${at(ctx, start)}`);
 }

package/src/compiler/collections.js

@@ -0,0 +1,316 @@
+// ---------------------------------------------------------------------------
+// Typed content collections. ANY `site/pages/<name>/` subdirectory is a
+// queryable collection, referenced by its bare name in `@loop` (no `content/`
+// root, no marker file). The index is built from the router's already-parsed
+// `route.meta` — frontmatter is never re-parsed here — and each entry becomes a
+// row the existing where/sort/format-pipe/`:if`/`:every` machinery consumes
+// UNCHANGED: every frontmatter field plus the derived `url` (entry route),
+// `slug` (filename stem), and an `excerpt` (frontmatter `excerpt:` → first
+// paragraph of a `.md` body).
+//
+// An optional `_schema.wd` at the collection root opts the collection into
+// build-time validation: every entry's frontmatter is checked against a small,
+// closed type DSL (`field: string|number|boolean|date|string[]`, `?` = optional)
+// with `file:line` errors. No `_schema.wd` = no validation (opt-in, like
+// `scoped`/`draft`).
+// ---------------------------------------------------------------------------
+
+import fs from "node:fs";
+import path from "node:path";
+import { firstParagraph } from "../feeds.js";
+import { parseFrontmatter } from "./frontmatter.js";
+
+/**
+ * @typedef {import("./context.js").Paths} Paths
+ * @typedef {import("./context.js").Meta} Meta
+ * @typedef {import("../router.js").Route} Route
+ */
+
+/**
+ * A collection entry row: every frontmatter field, plus derived `url`/`slug`/
+ * `excerpt`. Keyed loosely so authors' custom frontmatter keys pass through to
+ * `{ post.whatever }` and `where`/`sort` without a closed schema here.
+ * @typedef {Record<string, unknown> & { url: string, slug: string, excerpt: string }} CollectionRow
+ */
+
+/** The closed type vocabulary for `_schema.wd`. `?` (optional) is a modifier. */
+const SCHEMA_TYPES = new Set(["string", "number", "boolean", "date", "string[]"]);
+
+/**
+ * Build the collection index from the router's discovered routes: one entry per
+ * `site/pages/<name>/…` route, grouped under the FIRST path segment (the
+ * collection name). The home route, top-level pages, and the synthetic `/404/`
+ * route are not entries. Reuses each route's already-parsed `meta` (no re-parse)
+ * and reads the `.md` body only for the excerpt fallback. When a collection has
+ * a `_schema.wd`, every entry is validated against it here (throwing on the
+ * first violation), so a malformed entry fails the build with a `file:line`.
+ *
+ * @param {Route[]} routes Post-draft-filter routes from `discoverRoutes`.
+ * @param {Paths} paths Resolved project paths (`routesRoot` for `_schema.wd`).
+ * @returns {Map<string, CollectionRow[]>} Collection name → entry rows.
+ */
+export function buildCollections(routes, paths) {
+  /** @type {Map<string, CollectionRow[]>} */
+  const collections = new Map();
+  for (const route of routes) {
+    const name = collectionNameOf(route.route);
+    if (!name) continue;
+    const rows = collections.get(name) || [];
+    rows.push(rowFor(route));
+    collections.set(name, rows);
+  }
+  for (const [name, rows] of collections) {
+    const schema = readSchema(name, paths);
+    if (schema) validateRows(rows, schema, name);
+  }
+  return collections;
+}
+
+/**
+ * The collection name a route belongs to: the first path segment of a nested
+ * route (`/blog/hello/` → `blog`), or null for the home page, a top-level page
+ * (`/about/` → no nesting), or the `/404/` route (never a collection entry).
+ * @param {string} route Public route path (trailing-slashed).
+ * @returns {string | null}
+ */
+function collectionNameOf(route) {
+  if (route === "/" || route === "/404/") return null;
+  const parts = route.replace(/^\/|\/$/g, "").split("/");
+  return parts.length >= 2 ? parts[0] : null;
+}
+
+/**
+ * Build one collection row from a route: spread its frontmatter, then add the
+ * derived `url` (the route path), `slug` (filename stem), and `excerpt`
+ * (frontmatter `excerpt:` wins; else the first paragraph of a `.md` body; `.wd`
+ * bodies are not scanned — directive markup isn't clean prose). The derived keys
+ * are added AFTER the spread so a stray frontmatter `url:`/`slug:` can't shadow
+ * the real route data the loop relies on.
+ * @param {Route} route
+ * @returns {CollectionRow}
+ */
+function rowFor(route) {
+  const slug = path.basename(route.file, path.extname(route.file));
+  /** @type {Record<string, unknown>} */
+  const fields = {};
+  for (const [key, value] of Object.entries(route.meta)) fields[key] = coerceScalar(value);
+  return {
+    ...fields,
+    url: route.route,
+    slug: slug === "index" ? path.basename(path.dirname(route.file)) : slug,
+    excerpt: excerptFor(route)
+  };
+}
+
+/**
+ * Coerce a frontmatter scalar to its natural type for querying. The frontmatter
+ * parser yields scalars as STRINGS (`true`, `42` arrive as `"true"`, `"42"`), but
+ * a collection loop should behave like a JSON loop, where `where p.featured ==
+ * true` and numeric `sort`/comparisons just work. So a bare `true`/`false` becomes
+ * a boolean and a numeric string becomes a number; quoted/other strings and
+ * arrays pass through untouched. This coercion is scoped to collection rows only —
+ * it never touches the global frontmatter parser (a `:state`/`{ meta.x }` value
+ * keeps its existing string form).
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function coerceScalar(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (typeof value === "string" && /^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  return value;
+}
+
+/**
+ * The excerpt for an entry: the frontmatter `excerpt:` string if present, else
+ * (plain `.md` only) the first paragraph of its body, else "". Mirrors the RSS
+ * description fallback so a collection card and the feed read the same snippet.
+ * @param {Route} route
+ * @returns {string}
+ */
+function excerptFor(route) {
+  const fromMeta = route.meta.excerpt;
+  if (typeof fromMeta === "string" && fromMeta.trim()) return fromMeta.trim();
+  if (path.extname(route.file) !== ".md") return "";
+  const { body } = parseFrontmatter(fs.readFileSync(route.file, "utf8"), route.file);
+  return firstParagraph(body);
+}
+
+/**
+ * A parsed `_schema.wd` field rule.
+ * @typedef {object} SchemaField
+ * @property {string} name Field name.
+ * @property {string} type One of {@link SCHEMA_TYPES}.
+ * @property {boolean} optional Whether the field may be absent (`?` modifier).
+ */
+
+/**
+ * Read + parse a collection's `_schema.wd`, or null when the file is absent
+ * (validation is opt-in). The schema is frontmatter-shaped — one `field: type`
+ * line per rule inside the `---` block — so authors write it exactly like the
+ * frontmatter it validates. Each type must be in the closed {@link SCHEMA_TYPES}
+ * vocabulary (`?` suffix = optional); an unknown token is a compile error in the
+ * schema file itself, pointing at the offending line.
+ * @param {string} name Collection name.
+ * @param {Paths} paths
+ * @returns {SchemaField[] | null}
+ */
+export function readSchema(name, paths) {
+  const file = path.join(paths.routesRoot, name, "_schema.wd");
+  if (!fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, "utf8");
+  return parseSchema(raw, file);
+}
+
+/**
+ * Parse a `_schema.wd` source into field rules. The schema fields live in the
+ * frontmatter block; the body (if any) is ignored, so a schema file can carry a
+ * prose note after its `---` fence. Each field line is `name: type` where type
+ * is a closed token with an optional trailing `?`.
+ * @param {string} raw `_schema.wd` file contents.
+ * @param {string} file Absolute path, for `file:line` errors.
+ * @returns {SchemaField[]}
+ */
+export function parseSchema(raw, file) {
+  // Use the same `---` extraction as page frontmatter so the schema block is
+  // delimited identically. A schema with no fence is read as bare lines.
+  const lines = raw.replace(/\r\n?/g, "\n").split("\n");
+  /** @type {SchemaField[]} */
+  const fields = [];
+  let fenced = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (trimmed === "---") {
+      // First `---` opens the block; the second closes it and ends the schema.
+      if (!fenced && fields.length === 0) {
+        fenced = true;
+        continue;
+      }
+      if (fenced) break; // closing fence — rest of the file is prose, ignore it
+    }
+    if (!trimmed || trimmed.startsWith("#")) continue; // blank line or comment
+    const match = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.+)$/);
+    if (!match) {
+      throw new Error(
+        `Malformed schema line in ${file}:${i + 1}: "${trimmed}". Use: field: type (e.g. \`title: string\`, \`tags: string[]\`, \`featured: boolean?\`).`
+      );
+    }
+    fields.push(parseSchemaField(match[1], match[2].trim(), file, i + 1));
+  }
+  return fields;
+}
+
+/**
+ * Parse one `name: type` schema rule, validating the type against the closed
+ * vocabulary and peeling the optional `?` modifier.
+ * @param {string} name
+ * @param {string} rawType Type token (may end in `?`).
+ * @param {string} file
+ * @param {number} lineNo 1-based line number for the error.
+ * @returns {SchemaField}
+ */
+function parseSchemaField(name, rawType, file, lineNo) {
+  const optional = rawType.endsWith("?");
+  const type = optional ? rawType.slice(0, -1).trim() : rawType;
+  if (!SCHEMA_TYPES.has(type)) {
+    throw new Error(
+      `Unknown schema type "${rawType}" for field "${name}" in ${file}:${lineNo}. Use one of: ${[...SCHEMA_TYPES].join(", ")} (append "?" to make a field optional).`
+    );
+  }
+  return { name, type, optional };
+}
+
+/**
+ * Validate every collection row against the schema, throwing on the first
+ * violation with a `file:line` (the entry's own path) and the offending field.
+ * A missing required field, a wrong type, or an unknown extra field all fail —
+ * unknown keys are rejected so a typo'd frontmatter key (`titel:`) is caught
+ * rather than silently dropped.
+ * @param {CollectionRow[]} rows
+ * @param {SchemaField[]} schema
+ * @param {string} name Collection name, for the error message.
+ * @returns {void}
+ */
+function validateRows(rows, schema, name) {
+  const allowed = new Set(schema.map((field) => field.name));
+  // Framework-recognized keys never need a schema declaration: `url`/`slug`/
+  // `excerpt` are derived (always present), and `draft` is the routing gate
+  // (present on `--drafts` builds). Allow them implicitly so they don't trip the
+  // unknown-key check.
+  for (const reserved of ["url", "slug", "excerpt", "draft"]) allowed.add(reserved);
+  for (const row of rows) {
+    const where = `${String(row.url)} (collection "${name}")`;
+    for (const field of schema) validateField(row, field, where);
+    for (const key of Object.keys(row)) {
+      if (allowed.has(key)) continue;
+      throw new Error(
+        `Unknown frontmatter field "${key}" in ${where}: it is not declared in _schema.wd. Add \`${key}: <type>\` to the schema, or remove the field.`
+      );
+    }
+  }
+}
+
+/**
+ * Validate one field of one row against its schema rule.
+ * @param {CollectionRow} row
+ * @param {SchemaField} field
+ * @param {string} where Human-readable entry location for the error.
+ * @returns {void}
+ */
+function validateField(row, field, where) {
+  const present = field.name in row && row[field.name] !== null && row[field.name] !== "";
+  if (!present) {
+    if (field.optional) return;
+    throw new Error(
+      `Missing required field "${field.name}" (${field.type}) in ${where}. Add \`${field.name}: …\` to the entry's frontmatter, or mark it optional with "${field.name}: ${field.type}?" in _schema.wd.`
+    );
+  }
+  const value = row[field.name];
+  if (!matchesType(value, field.type)) {
+    throw new Error(
+      `Field "${field.name}" in ${where} should be ${field.type} but is "${describe(value)}". Fix the entry's frontmatter or the schema.`
+    );
+  }
+}
+
+/**
+ * Whether a frontmatter value satisfies a schema type. Frontmatter scalars are
+ * already strings/numbers/booleans/arrays (the parser produces no Date object),
+ * so `date` is "a string that `Date` can parse" and `number` accepts a numeric
+ * string too (frontmatter `42` parses to a number, but a quoted `"42"` stays a
+ * string — both are acceptable for a `number` field). The `type` is always one of
+ * {@link SCHEMA_TYPES} (parseSchemaField rejected anything else), so a missing
+ * checker can't occur — every {@link SCHEMA_TYPES} member has an entry below.
+ * @param {unknown} value
+ * @param {string} type
+ * @returns {boolean}
+ */
+function matchesType(value, type) {
+  return TYPE_CHECKS[type](value);
+}
+
+/**
+ * The per-type value checker for each closed schema type. Keyed exactly by
+ * {@link SCHEMA_TYPES}, so the indexed call in {@link matchesType} always lands on
+ * a real checker (no unreachable fallback branch to cover).
+ * @type {Record<string, (value: unknown) => boolean>}
+ */
+const TYPE_CHECKS = {
+  string: (value) => typeof value === "string",
+  number: (value) =>
+    typeof value === "number" || (typeof value === "string" && /^-?\d+(?:\.\d+)?$/.test(value)),
+  boolean: (value) => typeof value === "boolean" || value === "true" || value === "false",
+  date: (value) => typeof value === "string" && !Number.isNaN(new Date(value).getTime()),
+  "string[]": (value) => Array.isArray(value) && value.every((item) => typeof item === "string")
+};
+
+/**
+ * A short, safe description of a value for a validation error message.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describe(value) {
+  if (Array.isArray(value)) return `[${value.join(", ")}]`;
+  return String(value);
+}

package/src/compiler/context.js

@@ -41,14 +41,42 @@
  *   subtree; the HTML stamp uses them to scope the matching page/include subtree.
  */
 
+/**
+ * The pagination intent a `@loop … paginate N` records during compile, so the
+ * builder can multiply routes (page 1 at the listing route, 2+ at
+ * `/<route>/page/<n>/`). `total` is the post-`where`/`sort` page count for the
+ * collection the loop drew from.
+ * @typedef {object} Pagination
+ * @property {number} perPage Rows per page (the `paginate N` value).
+ * @property {number} total Total page count (≥ 1).
+ * @property {string} collection Collection name the loop paginated.
+ */
+
 /**
  * Per-document compilation accumulator shared across includes/sections.
  * @typedef {object} Compilation
  * @property {Assets} assets
  * @property {Map<string, unknown>} state Declared state keys → initial values.
  * @property {Set<string>} stores Page-global store names (a subset of state keys).
+ * @property {Set<string>} fetchKeys Base state keys declared by `:fetch`, so
+ *   bare `:if <key>_loading` / `:if <key>_error` regions get compile-time
+ *   `role`/`aria-live` announcements.
  * @property {string[]} warnings Non-fatal authoring hints.
  * @property {number} sectionCounter Counter for auto-generated section ids.
+ * @property {Map<string, number>} headingSlugs Heading-slug occurrence counts,
+ *   shared across prose chunks and includes so anchor ids dedupe document-wide.
+ * @property {Map<string, import("./collections.js").CollectionRow[]>} collections
+ *   Collection name → entry rows, built from the router's routes and threaded in
+ *   so a bare-name `@loop blog into post` resolves to its entries at build time.
+ * @property {import("./context.js").Pagination | null} pagination The pagination
+ *   intent a `@loop … paginate N` recorded this compile, or null. The builder
+ *   reads it to multiply routes; one paginated loop per page is supported.
+ * @property {Set<string>} deps Absolute paths of every source file this compile
+ *   read: the page itself, every `@include` target, and every `@loop` JSON data
+ *   file. The dev builder unions these (plus colocated assets) into the per-route
+ *   dependency map that drives incremental rebuilds.
+ * @property {Set<string>} collectionsUsed Names of the collections this compile
+ *   looped, so a change to any entry of a collection rebuilds its consumers.
  */
 
 /**
@@ -62,6 +90,11 @@
  * Per-file compile context threaded through the directive handlers.
  * @typedef {object} Ctx
  * @property {string} file Absolute path to the file being compiled.
+ * @property {number} [bodyLine] 0-based file line the compiled body starts on
+ *   (the frontmatter offset), so `at` reports true file line numbers.
+ * @property {number} [lineOffset] 0-based body line the current `compileBody`
+ *   slice starts on. Block handlers recurse with {@link nestedCtx}, so a line
+ *   index inside a nested block body still maps to the true file line.
  * @property {Paths} context Resolved project paths.
  * @property {string[]} stack Include stack (real paths) for cycle detection.
  * @property {Scope} scope Static value scope chain.
@@ -71,6 +104,13 @@
  * @property {string} [loopKey] State key of the list being looped, if any.
  * @property {boolean} [loopMeta] Inside a loop body, so `$index`/`$first`/… are valid.
  * @property {import("markdown-it").default} [md] Markdown-it instance selected for this file.
+ * @property {(lines: string[], ctx: Ctx) => string} compileBody The body
+ *   dispatcher, threaded through the context so block handlers (`:if`, `:::`,
+ *   `:form`, `@loop`, …) recurse into nested bodies without importing the
+ *   dispatcher back — the module graph stays an import-cycle-free DAG.
+ * @property {(file: string, context: Paths, stack: string[], scope: Scope, comp: Compilation, sections: string[], loopItem: string | null) => { meta: Meta, html: string }} compileFile
+ *   The per-file compile, threaded for the same reason so `@include` can
+ *   compile its target file.
  */
 
 /**
@@ -80,6 +120,10 @@
  * @property {string} html
  * @property {Assets} assets
  * @property {string[]} warnings
+ * @property {Pagination | null} pagination The pagination intent a paginated
+ *   `@loop` recorded, or null. The builder reads it to multiply routes.
+ * @property {Set<string>} deps Absolute source-file dependencies of this compile.
+ * @property {Set<string>} collectionsUsed Collection names this compile looped.
  */
 
 /**
@@ -89,6 +133,10 @@
  * @property {string} html
  * @property {Assets} assets
  * @property {string[]} warnings
+ * @property {Pagination | null} pagination The pagination intent a paginated
+ *   `@loop` recorded, or null. The builder reads it to multiply routes.
+ * @property {Set<string>} deps Absolute source-file dependencies of this compile.
+ * @property {Set<string>} collectionsUsed Collection names this compile looped.
  */
 
 /**
@@ -112,9 +160,15 @@
  * @property {NumArg | null} offset
  * @property {NumArg | null} limit
  * @property {string[] | null} empty Empty-branch body lines, if any.
+ * @property {number} [emptyStart] 0-based index the empty branch starts at
+ *   within the loop body, so its nested errors report the true file line.
  * @property {boolean} clauseRefsState Whether offset/limit reference state.
  * @property {boolean} sortable Drag-to-reorder the underlying :state/:store list
  *   (the `sortable` clause). Only valid on a plain reactive state-key loop.
+ * @property {number | null} paginate Rows-per-page for a `paginate N` clause, or
+ *   null. Only valid on a collection loop; multiplies the listing into static
+ *   pages (page 1 at the route, 2+ at `/<route>/page/<n>/`) and exposes a `page`
+ *   pager to the template scope.
  */
 
 /**
@@ -153,8 +207,14 @@ export function createCompilation() {
     },
     state: new Map(),
     stores: new Set(),
+    fetchKeys: new Set(),
     warnings: [],
-    sectionCounter: 0
+    sectionCounter: 0,
+    headingSlugs: new Map(),
+    collections: new Map(),
+    pagination: null,
+    deps: new Set(),
+    collectionsUsed: new Set()
   };
 }
 
@@ -170,11 +230,28 @@ export function createScope(parent, vars = {}) {
 /**
  * Format a source location as `file:line` (1-based) for compile errors. Keeps the
  * file path intact so existing message matchers still pass, while pointing at the
- * directive's (or unclosed opener's) line.
- * @param {string} file
- * @param {number} index 0-based line index.
+ * directive's (or unclosed opener's) line. `index` is 0-based into the current
+ * `compileBody` slice; `ctx.lineOffset` (where that slice starts in the body,
+ * accumulated by {@link nestedCtx} as block handlers recurse) and `ctx.bodyLine`
+ * (the frontmatter offset) shift it back to the true file line.
+ * @param {Pick<Ctx, "file" | "bodyLine" | "lineOffset">} ctx
+ * @param {number} index 0-based line index into the current body slice.
  * @returns {string}
  */
-export function at(file, index) {
-  return `${file}:${index + 1}`;
+export function at(ctx, index) {
+  return `${ctx.file}:${index + 1 + (ctx.bodyLine ?? 0) + (ctx.lineOffset ?? 0)}`;
+}
+
+/**
+ * The compile context for a nested block body that starts `start` lines into the
+ * current slice. The offset accumulates, so errors inside arbitrarily nested
+ * blocks (`::: container`, `:form`, `@loop`, `:if`, `:carousel`) still report
+ * the true file line through {@link at}.
+ * @template {Pick<Ctx, "lineOffset">} T
+ * @param {T} ctx
+ * @param {number} start 0-based index the nested body starts at in the current slice.
+ * @returns {T}
+ */
+export function nestedCtx(ctx, start) {
+  return { ...ctx, lineOffset: (ctx.lineOffset ?? 0) + start };
 }