@zvndev/darkmown 1.4.0 → 1.5.0

package/src/builder.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { discoverApiRoutes } from "./api-runner.js";
+import { buildCollections } from "./compiler/collections.js";
 import { compilePage, parseFrontmatter } from "./compiler.js";
 import { createPaths } from "./config.js";
 import {
@@ -59,6 +60,12 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
   const routes = discoverRoutes(paths.routesRoot, { includeDrafts: options.includeDrafts });
+  // Build the collection index from the (post-draft-filter) routes — every
+  // site/pages/<name>/ subdirectory's entries become queryable rows a bare-name
+  // `@loop blog into post` resolves against. Drafts are already excluded, so a
+  // draft entry can never appear in a listing. Validates each collection's
+  // `_schema.wd` here (throwing on a bad entry with file:line).
+  const collections = buildCollections(routes, paths);
   // Site identity lives in the HOME page frontmatter (no config loader): the
   // `site_url` origin triggers + prefixes the feeds, reusing `title`/`description`
   // as the RSS channel fields. Resolved once, up front, so every page can link
@@ -80,35 +87,46 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   /** @type {string | undefined} HTML of the `/404/` route, copied to dist/404.html. */
   let notFoundHtml;
 
+  // Extra (paginated 2+) routes the build generates beyond the discovered set —
+  // each is indexable static HTML, so it belongs in the sitemap (it has no own
+  // frontmatter `date:`; it reuses its listing source file for `<lastmod>`).
+  /** @type {Route[]} */
+  const extraRoutes = [];
+
   for (const route of routes) {
-    const page = compilePage(route.file, paths, { feed: feedLink });
-    for (const warning of page.warnings || []) {
-      if (warned.has(warning)) continue;
-      warned.add(warning);
-      console.warn(`hint: ${warning}`);
-    }
-    const outFile = outputPathForRoute(paths.distRoot, route.route);
-    fs.mkdirSync(path.dirname(outFile), { recursive: true });
-    fs.writeFileSync(outFile, page.html);
-    if (route.route === "/404/") notFoundHtml = page.html;
-    emitAssets(page.assets, paths, page.html, warned);
-    if (page.assets.runtime) emitRuntime(paths);
-    emitBehaviors(page.assets, paths);
-    if (page.assets.hasCode) emitHighlight(paths);
-    const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
-    manifest.push({
-      route: route.route,
-      file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
-      assets: {
-        skins: [...page.assets.skins],
-        scripts: [
-          ...(page.assets.runtime ? ["/__wd/runtime.js"] : []),
-          ...behaviorSrcs,
-          ...page.assets.scripts
-        ],
-        runtime: page.assets.runtime
+    // Compile each route's page(s). A normal route yields one page; a route whose
+    // `@loop … paginate N` slices a collection yields page 1 at the route plus
+    // `/<route>/page/<n>/` for pages 2..N — every one static HTML.
+    for (const page of compileRoutePages(route, paths, collections, feedLink)) {
+      if (page.route !== route.route) extraRoutes.push({ ...route, route: page.route });
+      for (const warning of page.warnings || []) {
+        if (warned.has(warning)) continue;
+        warned.add(warning);
+        console.warn(`hint: ${warning}`);
       }
-    });
+      const outFile = outputPathForRoute(paths.distRoot, page.route);
+      fs.mkdirSync(path.dirname(outFile), { recursive: true });
+      fs.writeFileSync(outFile, page.html);
+      if (page.route === "/404/") notFoundHtml = page.html;
+      emitAssets(page.assets, paths, page.html, warned);
+      if (page.assets.runtime) emitRuntime(paths);
+      emitBehaviors(page.assets, paths);
+      if (page.assets.hasCode) emitHighlight(paths);
+      const behaviorSrcs = [...page.assets.behaviors].map((name) => `/__wd/behaviors/${name}.js`);
+      manifest.push({
+        route: page.route,
+        file: path.relative(cwd, route.file).replaceAll(path.sep, "/"),
+        assets: {
+          skins: [...page.assets.skins],
+          scripts: [
+            ...(page.assets.runtime ? ["/__wd/runtime.js"] : []),
+            ...behaviorSrcs,
+            ...page.assets.scripts
+          ],
+          runtime: page.assets.runtime
+        }
+      });
+    }
   }
 
   // Hosts (Vercel, Cloudflare Pages) and the framework's own server auto-serve
@@ -126,8 +144,10 @@ export function buildSite(cwd = process.cwd(), options = {}) {
 
   // Crawler files + feeds. robots.txt is ALWAYS emitted; sitemap.xml + rss.xml
   // need the home `site_url` (else a loud, actionable build hint). Drafts are
-  // already filtered out of `routes`, so neither feed can ever see one.
-  const feeds = emitFeeds(routes, identity, paths);
+  // already filtered out of `routes`, so neither feed can ever see one. The
+  // paginated 2+ routes are indexable HTML too, so they join the sitemap (RSS is
+  // dated-posts-only, which they are not, so it's unaffected).
+  const feeds = emitFeeds([...routes, ...extraRoutes], identity, paths);
 
   // Page-colocated static assets (images, SVG, fonts, …) copy last, so the guard
   // sees every emitted route/framework file already on disk.
@@ -146,6 +166,94 @@ export function buildSite(cwd = process.cwd(), options = {}) {
   return { routes: manifest, distRoot: paths.distRoot, feeds };
 }
 
+/**
+ * A compiled page bound for a concrete output route. Mirrors `CompiledPage` plus
+ * the public `route` it's written to — for a paginated listing, page 1 keeps the
+ * listing route and pages 2+ get `/<route>/page/<n>/`.
+ * @typedef {object} EmittedPage
+ * @property {string} route Public route path this page is written to.
+ * @property {string} html
+ * @property {import("./compiler.js").Assets} assets
+ * @property {string[]} warnings
+ */
+
+/**
+ * Compile a route into the one-or-more static pages it emits. A normal route is
+ * one page. A route whose body paginates a collection (`@loop … paginate N`) is
+ * compiled once to discover the page count, then recompiled per page with the
+ * correct `page` pager seeded into scope — page 1 at the route, pages 2..total at
+ * `/<route>/page/<n>/`. Every emitted page is static HTML (`runtime: false` for a
+ * pure listing).
+ * @param {Route} route
+ * @param {Paths} paths
+ * @param {Map<string, import("./compiler/collections.js").CollectionRow[]>} collections
+ * @param {{ href: string, title: string } | undefined} feedLink
+ * @returns {EmittedPage[]}
+ */
+function compileRoutePages(route, paths, collections, feedLink) {
+  // First compile (discovery): page 1 with a placeholder pager. If the page has
+  // no `paginate`, this is the only compile and we emit it as-is.
+  const first = compilePage(route.file, paths, {
+    feed: feedLink,
+    collections,
+    vars: { page: pagerVars(route.route, 1, 1) }
+  });
+  if (!first.pagination || first.pagination.total <= 1) {
+    return [
+      { route: route.route, html: first.html, assets: first.assets, warnings: first.warnings }
+    ];
+  }
+  // Paginated: recompile every page (including page 1, whose pager `total`/`next`
+  // were unknown on the discovery pass) with the correct pager.
+  const total = first.pagination.total;
+  /** @type {EmittedPage[]} */
+  const pages = [];
+  for (let n = 1; n <= total; n++) {
+    const page = compilePage(route.file, paths, {
+      feed: feedLink,
+      collections,
+      vars: { page: pagerVars(route.route, n, total) }
+    });
+    pages.push({
+      route: pageRoute(route.route, n),
+      html: page.html,
+      assets: page.assets,
+      warnings: page.warnings
+    });
+  }
+  return pages;
+}
+
+/**
+ * The output route for page `n` of a paginated listing: page 1 keeps the
+ * listing's own clean route; pages 2+ live at `/<route>/page/<n>/`.
+ * @param {string} baseRoute Listing route (trailing-slashed).
+ * @param {number} n 1-based page number.
+ * @returns {string}
+ */
+function pageRoute(baseRoute, n) {
+  return n === 1 ? baseRoute : `${baseRoute}page/${n}/`;
+}
+
+/**
+ * Build the `{ page.* }` pager exposed to the template scope of a paginated
+ * listing: `current`/`total` numbers and `prev`/`next` URLs (empty string at the
+ * ends, so `{ page.prev }` renders nothing on page 1). Plain links to the
+ * generated routes — zero JS.
+ * @param {string} baseRoute Listing route.
+ * @param {number} current 1-based current page.
+ * @param {number} total Total page count.
+ * @returns {{ current: number, total: number, prev: string, next: string }}
+ */
+function pagerVars(baseRoute, current, total) {
+  return {
+    current,
+    total,
+    prev: current > 1 ? pageRoute(baseRoute, current - 1) : "",
+    next: current < total ? pageRoute(baseRoute, current + 1) : ""
+  };
+}
+
 /**
  * Resolve the site's identity from the HOME route's frontmatter — the single
  * place site-wide metadata lives this cycle (no config loader). `site_url` is

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,6 +41,17 @@
  *   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
@@ -49,6 +60,12 @@
  * @property {Set<string>} stores Page-global store names (a subset of state keys).
  * @property {string[]} warnings Non-fatal authoring hints.
  * @property {number} sectionCounter Counter for auto-generated section ids.
+ * @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.
  */
 
 /**
@@ -80,6 +97,8 @@
  * @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.
  */
 
 /**
@@ -89,6 +108,8 @@
  * @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.
  */
 
 /**
@@ -115,6 +136,10 @@
  * @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.
  */
 
 /**
@@ -154,7 +179,9 @@ export function createCompilation() {
     state: new Map(),
     stores: new Set(),
     warnings: [],
-    sectionCounter: 0
+    sectionCounter: 0,
+    collections: new Map(),
+    pagination: null
   };
 }