@zvndev/darkmown 1.4.0 → 2.0.0

package/src/compiler/frontmatter.js

@@ -12,13 +12,15 @@ import { stripQuotes } from "./interpolation.js";
  */
 
 /**
- * Split a raw file into its frontmatter `meta` and `body`.
+ * Split a raw file into its frontmatter `meta` and `body`. `bodyLine` is the
+ * 0-based file line index the body starts on (the number of lines the
+ * frontmatter block consumed) so compile errors can report true file lines.
  * @param {string} raw Full file contents.
  * @param {string} [file] Source path, used only for error messages.
- * @returns {{ meta: Meta, body: string }}
+ * @returns {{ meta: Meta, body: string, bodyLine: number }}
  */
 export function parseFrontmatter(raw, file) {
-  if (!raw.startsWith("---\n")) return { meta: {}, body: raw };
+  if (!raw.startsWith("---\n")) return { meta: {}, body: raw, bodyLine: 0 };
   const end = raw.indexOf("\n---", 3);
   if (end === -1) {
     const where = file ? ` in ${file}` : "";
@@ -27,14 +29,17 @@ export function parseFrontmatter(raw, file) {
     );
   }
   const front = raw.slice(4, end).trim();
-  const body = raw.slice(end + 4).replace(/^\n/, "");
+  let bodyStart = end + 4;
+  if (raw[bodyStart] === "\n") bodyStart++;
+  const body = raw.slice(bodyStart);
+  const bodyLine = raw.slice(0, bodyStart).split("\n").length - 1;
   /** @type {Meta} */
   const meta = {};
   for (const line of front.split("\n")) {
     const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
     if (match) meta[match[1]] = parseFrontmatterValue(match[2]);
   }
-  return { meta, body };
+  return { meta, body, bodyLine };
 }
 
 /**

package/src/compiler/includes.js

@@ -1,7 +1,8 @@
 // ---------------------------------------------------------------------------
 // Includes / assets: resolve `@include` (and `@loop` data) targets to absolute
 // paths inside `site/pages` or `site/_`, register colocated `.skin`/`.js`
-// siblings, and warn when a plain `.md` file uses `.wd`-only syntax.
+// siblings, detect scoped skins and stamp their subtree HTML (`stampScope`),
+// and warn when a plain `.md` file uses `.wd`-only syntax.
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
@@ -57,6 +58,70 @@ export function scopedSkinFor(file, context) {
   return scopeInfoForSkin(candidate, context.cwd);
 }
 
+/**
+ * Raw-text (`script`, `style`) and escapable-raw-text (`textarea`, `title`)
+ * elements per the HTML spec: their CONTENT is not markup, so `<`/`>` inside them
+ * are plain characters and must never be treated as tags. The content runs to the
+ * first matching close tag.
+ * @type {Set<string>}
+ */
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "textarea", "title"]);
+
+/**
+ * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a
+ * compile-time post-pass over assembled HTML, zero runtime JS. Every element
+ * start tag that doesn't already carry a scope attribute gets one, so the scoped
+ * stylesheet (whose selectors end in `[data-wd-scope="<id>"]`) matches inside
+ * this subtree and nowhere else. Void/self-closing tags are stamped too (the
+ * attribute is valid on any element). Closing tags, comments, doctype, and the
+ * `<!`/`<?` families are left alone. A tag that ALREADY has a `data-wd-scope`
+ * (e.g. a nested include with its own scope) keeps its own — first stamp wins.
+ *
+ * Raw-text / escapable-raw-text elements (`script`, `style`, `textarea`,
+ * `title`) are special-cased: their OPENING tag is stamped (valid), but their
+ * BODY is left byte-intact — `<`/`>` inside a `<script>` are JavaScript, not
+ * markup, so stamping there would corrupt the content. A small tokenizer walks
+ * tag-by-tag (quote-aware in attribute lists) and, on entering a raw-text
+ * element, copies through verbatim until the matching close tag.
+ * @param {string} html Subtree HTML to scope.
+ * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
+ * @returns {string}
+ */
+export function stampScope(html, scopeId) {
+  // Opening tag: name + (quote-aware) attribute list + optional self-close slash.
+  const openTag = /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
+  let out = "";
+  let cursor = 0;
+  for (let m = openTag.exec(html); m; m = openTag.exec(html)) {
+    const [tag, name, attrs, slash] = m;
+    out += html.slice(cursor, m.index); // text/markup before this opening tag
+    const stamped = /\bdata-wd-scope\s*=/.test(attrs)
+      ? tag // first stamp wins — a pre-stamped tag keeps its own scope
+      : `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+    out += stamped;
+    cursor = m.index + tag.length;
+
+    // Raw-text element (not self-closed): copy its body through untouched and
+    // resume scanning after the matching close tag, so nothing inside is stamped.
+    if (!slash && RAW_TEXT_ELEMENTS.has(name.toLowerCase())) {
+      const rest = html.slice(cursor);
+      const closeMatch = new RegExp(`</${name}\\s*>`, "i").exec(rest);
+      if (!closeMatch) {
+        out += rest; // unterminated raw-text element — copy the remainder verbatim
+        cursor = html.length;
+        break;
+      }
+      const through = closeMatch.index + closeMatch[0].length; // body + close tag
+      out += rest.slice(0, through); // byte-intact
+      cursor += through;
+      openTag.lastIndex = cursor; // skip the body the scanner would otherwise re-walk
+    }
+  }
+  out += html.slice(cursor); // trailing text after the last opening tag
+  return out;
+}
+
 /**
  * Register a page's colocated `.skin`/`.js` siblings as emitted assets.
  * @param {string} file

package/src/compiler/index.js

@@ -4,20 +4,32 @@
 //   context.js        shared typedefs + tiny helpers (createCompilation, at, …)
 //   interpolation.js  path/value resolution, state-key lookup, escapeHtml, literals
 //   frontmatter.js    `---` block → meta + body, inline scalar/array parsing
-//   includes.js       @include / @loop-data resolution, colocated assets, .md hints
+//   includes.js       @include / @loop-data resolution, colocated assets,
+//                     scoped-skin detection + the HTML scope stamp, .md hints
 //   predicates.js     where / when / :if / :computed expression compilers
 //   format.js         { value | pipe } format pipes + list aggregates (value layer)
 //   markdown.js       markdown-it instances + plugins + prose interpolation
+//   state.js          :state / :store / :computed / :theme + declare* helpers
+//   actions.js        the :button action parser + :button / :effect / :every
+//   fetch.js          :fetch + the shared URL scheme guard
+//   forms.js          :form + field directives + :bind / :slider
+//   media.js          :video / :audio / :embed
+//   structure.js      @include / ::: container / :if / :carousel + demo directives
+//   directives.js     barrel re-exporting the handle* family from the six above
 //   loops.js          @loop pipeline + row-template initial-paint fill
-//   directives.js     the handle* family + :button action parser + demo directives
 //   body.js           the line-based directive dispatcher (compileBody)
 //   page.js           HTML page shell, image hardening, per-file compile
 //
+// Handlers recurse into nested bodies through `ctx.compileBody` (and `@include`
+// through `ctx.compileFile`), threaded in by `compileFile` — so the graph is an
+// import-cycle-free DAG rooted at context.js.
+//
 // This barrel re-exports the public API; `src/compiler.js` re-exports from here
 // so every existing `import … from "./compiler.js"` keeps working unchanged.
 // ---------------------------------------------------------------------------
 
 export { parseFrontmatter } from "./frontmatter.js";
+export { stampScope } from "./includes.js";
 export { escapeHtml } from "./interpolation.js";
 export { loopKeyOf } from "./loops.js";
-export { compileDocument, compilePage, enhanceImages, stampScope } from "./page.js";
+export { compileDocument, compilePage, enhanceImages } from "./page.js";

package/src/compiler/loops.js

@@ -7,14 +7,14 @@
 // ---------------------------------------------------------------------------
 
 import fs from "node:fs";
-import { compileBody } from "./body.js";
-import { createScope } from "./context.js";
+import { at, createScope, nestedCtx } from "./context.js";
 import { applyPipeline, stagesFromAttr } from "./format.js";
 import { resolveInclude } from "./includes.js";
 import {
   escapeHtml,
   getPath,
   lookupPath,
+  lookupVar,
   resolveStateKey,
   stripQuotes,
   unescapeHtml
@@ -30,15 +30,15 @@ import { compilePredicate, evalPredicate } from "./predicates.js";
 
 // The fixed corrective suggestion shown for any malformed @loop header.
 const LOOP_USAGE =
-  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [sortable]";
+  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable]";
 
 /**
  * Parse the optional clause tail of a `@loop` header in FIXED order:
- * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [sortable]`.
+ * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [paginate N] [sortable]`.
  * @param {string} tail Everything after `@loop src into item`.
  * @param {string} itemName
  * @param {Ctx} ctx
- * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean }}
+ * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean, paginate: number|null }}
  */
 function parseLoopClauses(tail, itemName, ctx) {
   // Peel clauses off the END in reverse fixed-order (limit, offset, reverse,
@@ -53,6 +53,7 @@ function parseLoopClauses(tail, itemName, ctx) {
   /** @type {NumArg|null} */ let limit = null;
   let refsState = false;
   let sortable = false;
+  /** @type {number|null} */ let paginate = null;
   /** @returns {never} */
   const bad = () => {
     throw new Error(`Malformed @loop clause in ${ctx.file}: "${tail.trim()}". ${LOOP_USAGE}`);
@@ -69,6 +70,20 @@ function parseLoopClauses(tail, itemName, ctx) {
       .trim();
   }
 
+  // `paginate N` slices the listing into static pages. Peel it position-
+  // independently (like `sortable`) so `paginate 2 limit 1` parses and handleLoop
+  // can reject the combination with a precise message rather than failing the
+  // fixed-order parse. The count is a positive integer literal — paginating "by a
+  // state value" makes no sense for a build-time route split.
+  const pm = s.match(/(^|\s)paginate\s+(\d+)(?=\s|$)/);
+  if (pm) {
+    paginate = Number(pm[2]);
+    if (paginate < 1) bad();
+    s = (s.slice(0, pm.index) + s.slice((pm.index ?? 0) + pm[0].length))
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+
   let m = s.match(/(^|\s)limit\s+(\d+|[A-Za-z_$][\w$]*)$/);
   if (m) {
     limit = parseNumArg(m[2], ctx);
@@ -109,7 +124,7 @@ function parseLoopClauses(tail, itemName, ctx) {
     // predicate means a clause was written before `where` finished (wrong order).
     if (/(^|\s)(sort\s+by\s|reverse(\s|$))/.test(where)) bad();
   }
-  return { where, sort, reverse, offset, limit, refsState, sortable };
+  return { where, sort, reverse, offset, limit, refsState, sortable, paginate };
 }
 
 /**
@@ -197,9 +212,12 @@ function numArgAttr(arg) {
  * @param {string[]} bodyLines
  * @param {string[] | null} emptyLines
  * @param {Ctx} ctx
+ * @param {number} index 0-based line index of the `@loop` opener.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-export function handleLoop(line, bodyLines, emptyLines, ctx) {
+export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart = 0) {
   const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(\s+.+?)?\s*$/);
   if (!match) throw new Error(`Malformed @loop in ${ctx.file}: ${line}. ${LOOP_USAGE}`);
   const source = stripQuotes(match[1].trim());
@@ -213,18 +231,32 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
         offset: null,
         limit: null,
         refsState: false,
-        sortable: false
+        sortable: false,
+        paginate: null
       };
   const where = clauses.where ? compilePredicate(clauses.where, itemName, ctx) : null;
   // `sortable` reorders the list directly, so it can't combine with a clause that
   // re-derives the visible order (where/sort/reverse) or shows a partial view
-  // (offset/limit) — those would break the 1:1 DOM↔array index mapping.
+  // (offset/limit/paginate) — those would break the 1:1 DOM↔array index mapping.
   if (
     clauses.sortable &&
-    (where || clauses.sort || clauses.reverse || clauses.offset || clauses.limit)
+    (where ||
+      clauses.sort ||
+      clauses.reverse ||
+      clauses.offset ||
+      clauses.limit ||
+      clauses.paginate)
   ) {
     throw new Error(
-      `@loop sortable cannot combine with where/sort/reverse/offset/limit in ${ctx.file}. ${LOOP_USAGE}`
+      `@loop sortable cannot combine with where/sort/reverse/offset/limit/paginate in ${ctx.file}. ${LOOP_USAGE}`
+    );
+  }
+  // `paginate N` OWNS the page slice, so an explicit offset/limit alongside it is
+  // a conflict (which one wins?). Reject it with a clear hint rather than silently
+  // letting one override the other.
+  if (clauses.paginate && (clauses.offset || clauses.limit)) {
+    throw new Error(
+      `@loop paginate cannot combine with offset/limit in ${ctx.file} — paginate already slices each page. ${LOOP_USAGE}`
     );
   }
   /** @type {LoopOpts} */
@@ -235,9 +267,14 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     offset: clauses.offset,
     limit: clauses.limit,
     empty: emptyLines,
+    emptyStart,
     clauseRefsState: clauses.refsState,
-    sortable: clauses.sortable
+    sortable: clauses.sortable,
+    paginate: clauses.paginate
   };
+  // The loop body starts on the line after the opener; nested errors in it (and
+  // in the empty branch, via `opts.emptyStart`) report the true file line.
+  const bodyCtx = nestedCtx(ctx, index + 1);
 
   if (
     source.startsWith("/") ||
@@ -245,20 +282,30 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     source.startsWith("../") ||
     source.endsWith(".json")
   ) {
+    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
     const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
+    ctx.comp.deps.add(dataFile);
     const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
-    return loopOverData(rows, itemName, bodyLines, ctx, opts);
+    return loopOverData(rows, itemName, bodyLines, bodyCtx, opts);
   }
 
   const resolved = lookupPath(source, ctx);
   if (resolved.found) {
+    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+    // A missing/unset field (e.g. an optional frontmatter key) is an EMPTY
+    // list, not an error — the `@empty` branch renders, matching the runtime.
+    if (resolved.value === null || resolved.value === undefined) {
+      return loopOverData([], itemName, bodyLines, bodyCtx, opts);
+    }
     if (!Array.isArray(resolved.value)) {
       throw new Error(
-        `@loop ${source} in ${ctx.file} found an in-scope value, but it is not a list`
+        `@loop ${source} in ${at(ctx, index)} found an in-scope value, but it is not a list ` +
+          `(got ${typeof resolved.value}). Use: a list value (e.g. \`tags: [a, b]\` in frontmatter) — ` +
+          `or leave the field out entirely, which loops zero rows and renders the @empty branch.`
       );
     }
-    return loopOverData(resolved.value, itemName, bodyLines, ctx, opts);
+    return loopOverData(resolved.value, itemName, bodyLines, bodyCtx, opts);
   }
 
   // A bare name OR a dotted path resolving to declared :state (e.g. team.members).
@@ -269,8 +316,17 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     }
     const key = resolveStateKey(segs[0], ctx);
     if (key) {
+      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
-      return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
+      return reactiveLoop(fullKey, itemName, bodyLines, bodyCtx, opts);
+    }
+    // A bare name matching a collection (any `site/pages/<name>/` subdir) resolves
+    // to its entry rows at build time and static-unrolls — zero JS. This is checked
+    // after state so a declared `:state` of the same name still wins.
+    const collection = segs.length === 1 ? ctx.comp.collections.get(source) : undefined;
+    if (collection) {
+      ctx.comp.collectionsUsed.add(source);
+      return loopOverCollection(collection, source, itemName, bodyLines, bodyCtx, opts);
     }
     // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
@@ -280,15 +336,100 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
           `@loop sortable is not supported on a nested (item-relative) loop in ${ctx.file}. ${LOOP_USAGE}`
         );
       }
-      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
+      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
+      return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, bodyCtx, opts);
     }
   }
 
-  throw new Error(
-    `@loop source "${source}" in ${ctx.file} was not found. Loop over a JSON file (@loop /data.json into row), an in-scope value, or a :state list.`
+  throw new Error(unresolvedSourceError(source, ctx));
+}
+
+/**
+ * The "source not found" error for an unresolved `@loop` bare name. Lists the
+ * valid collection names (the `site/pages/<name>/` subdirs) so a typo'd
+ * collection reference is immediately actionable.
+ * @param {string} source
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function unresolvedSourceError(source, ctx) {
+  const names = [...ctx.comp.collections.keys()].sort();
+  const collectionsHint = names.length ? ` Available collections: ${names.join(", ")}.` : "";
+  return (
+    `@loop source "${source}" in ${ctx.file} was not found. Loop over a collection ` +
+    `(a site/pages/<name>/ subdirectory, by its bare name), a JSON file ` +
+    `(@loop /data.json into row), an in-scope value, or a :state list.${collectionsHint}`
+  );
+}
+
+/**
+ * The error for `paginate` on a non-collection source: pagination multiplies
+ * static routes, which only makes sense for a build-time collection listing.
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function paginateOnlyCollections(ctx) {
+  return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
+}
+
+/**
+ * Loop over a build-time collection's entry rows. With no `paginate`, this is a
+ * plain static unroll (filter/sort/reverse/offset/limit at build time, zero JS).
+ * With `paginate N`, it records the pagination intent (so the builder multiplies
+ * routes), then renders only the current page's slice using the injected `page`
+ * pager — `offset = (page.current - 1) * N`, `limit = N`.
+ * @param {import("./collections.js").CollectionRow[]} rows
+ * @param {string} name Collection name, for the pagination record.
+ * @param {string} itemName
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {LoopOpts} opts
+ * @returns {string}
+ */
+function loopOverCollection(rows, name, itemName, bodyLines, ctx, opts) {
+  if (!opts.paginate) {
+    // No pagination → behave exactly like a JSON-file/in-scope source: a pure
+    // listing static-unrolls (zero JS); a `where` that reads :state turns it into
+    // a reactive baked-rows loop. `loopOverData` makes that call.
+    return loopOverData(rows, itemName, bodyLines, ctx, opts);
+  }
+  // Count rows AFTER where/sort/reverse but BEFORE the page slice, so `total`
+  // reflects what the reader will actually page through. Reuse pipelineRows with
+  // offset/limit stripped for the count.
+  const filtered = pipelineRows(rows, opts.where, { ...opts, offset: null, limit: null }, ctx);
+  const perPage = opts.paginate;
+  const total = Math.max(1, Math.ceil(filtered.length / perPage));
+  ctx.comp.pagination = { perPage, total, collection: name };
+  // `page.current` is the 1-based page the builder is rendering (it seeds the
+  // document scope). Slice this page out of the already-filtered/sorted list.
+  const current = currentPage(ctx);
+  const start = (current - 1) * perPage;
+  return staticUnroll(
+    filtered.slice(start, start + perPage),
+    itemName,
+    bodyLines,
+    ctx,
+    opts.empty,
+    opts.emptyStart
   );
 }
 
+/**
+ * The 1-based page the builder is currently rendering, read from the injected
+ * `page.current` scope var. Defaults to page 1 (the discovery compile, before the
+ * builder knows the total, runs with `page.current = 1`).
+ * @param {Ctx} ctx
+ * @returns {number}
+ */
+function currentPage(ctx) {
+  const page = lookupVar(ctx.scope, "page");
+  if (page.found && page.value && typeof page.value === "object") {
+    const current = /** @type {Record<string, unknown>} */ (page.value).current;
+    if (typeof current === "number" && current >= 1) return current;
+  }
+  return 1;
+}
+
 // A static source (JSON file / in-scope value). No `where`, or a `where` that
 // only reads the loop item → filter at build time and stay zero-JS. A `where`
 // that reads :state → becomes a reactive filtered loop with the rows baked in.
@@ -349,7 +490,8 @@ function loopOverData(rows, itemName, bodyLines, ctx, opts) {
     itemName,
     bodyLines,
     ctx,
-    opts.empty
+    opts.empty,
+    opts.emptyStart
   );
 }
 
@@ -359,10 +501,13 @@ function loopOverData(rows, itemName, bodyLines, ctx, opts) {
  * @param {string[]} bodyLines
  * @param {Ctx} ctx
  * @param {string[] | null} [empty] Empty-branch body, rendered when 0 rows.
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
-  if (rows.length === 0 && empty) return compileBody(empty, { ...ctx, loopMeta: true });
+function staticUnroll(rows, itemName, bodyLines, ctx, empty = null, emptyStart = 0) {
+  if (rows.length === 0 && empty)
+    return ctx.compileBody(empty, { ...nestedCtx(ctx, emptyStart), loopMeta: true });
   const out = [];
   const count = rows.length;
   for (let i = 0; i < count; i++) {
@@ -378,7 +523,7 @@ function staticUnroll(rows, itemName, bodyLines, ctx, empty = null) {
       loopMeta: true,
       scope: createScope(ctx.scope, { [itemName]: rows[i], ...meta })
     };
-    out.push(compileBody(bodyLines, rowCtx));
+    out.push(ctx.compileBody(bodyLines, rowCtx));
   }
   return out.join("\n");
 }
@@ -404,7 +549,7 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     loopMeta: true,
     scope: createScope(ctx.scope)
   };
-  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+  const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
 
   const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
@@ -440,7 +585,8 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
           : limit,
       empty: null,
       clauseRefsState: false,
-      sortable: false
+      sortable: false,
+      paginate: null
     },
     ctx
   );
@@ -459,10 +605,12 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     })
     .join("");
 
-  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx);
+  const emptyTemplate = loopEmptyTemplate(emptyLines, ctx, opts?.emptyStart);
   const initialOut =
     count === 0 && emptyLines
-      ? compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()
+      ? ctx
+          .compileBody(emptyLines, { ...nestedCtx(ctx, opts?.emptyStart ?? 0), loopMeta: true })
+          .trim()
       : initial;
 
   // `sortable` tags the region for the drag-reorder behavior (emitted only here)
@@ -497,11 +645,13 @@ function wrapRowTemplate(templateHtml) {
  * there is no empty branch). Shared by top-level and item-relative loops.
  * @param {string[] | null} emptyLines
  * @param {Ctx} ctx
+ * @param {number} [emptyStart] 0-based index the empty branch starts at within
+ *   the loop body, so its nested errors report the true file line.
  * @returns {string}
  */
-function loopEmptyTemplate(emptyLines, ctx) {
+function loopEmptyTemplate(emptyLines, ctx, emptyStart = 0) {
   return emptyLines
-    ? `<template data-wd-loop-empty>${compileBody(emptyLines, { ...ctx, loopMeta: true }).trim()}</template>`
+    ? `<template data-wd-loop-empty>${ctx.compileBody(emptyLines, { ...nestedCtx(ctx, emptyStart), loopMeta: true }).trim()}</template>`
     : "";
 }
 
@@ -550,11 +700,11 @@ function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
     loopMeta: true,
     scope: createScope(ctx.scope)
   };
-  const templateHtml = compileBody(bodyLines, templateCtx).trim();
+  const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
 
   const { wrapperTag, itemTemplate } = wrapRowTemplate(templateHtml);
 
-  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx);
+  const emptyTemplate = loopEmptyTemplate(opts.empty || null, ctx, opts.emptyStart);
   const attrs = loopClauseAttrs({
     where: opts.where || null,
     sort: opts.sort || null,

package/src/compiler/markdown.js

@@ -1,6 +1,6 @@
 // ---------------------------------------------------------------------------
-// Markdown layer: the shared markdown-it instances (raw-HTML default + a lazy
-// `html: false` strict variant), the `wd_binding` inline plugin and `wd_attrs`
+// Markdown layer: the shared markdown-it instances (strict default + a lazy
+// `html: true` raw-HTML variant), the `wd_binding` inline plugin and `wd_attrs`
 // core plugin, and prose rendering with `{ name.path }` interpolation resolved
 // against the loop item / static scope / declared state.
 // ---------------------------------------------------------------------------
@@ -26,29 +26,33 @@ import {
 // with a known language. The callback returns escaped token HTML or `""` to let
 // markdown-it render a plain escaped `<code>` (graceful degradation). Both
 // instances share it so `html: false` pages highlight too.
-const md = new MarkdownIt({ html: true, highlight: highlightCode });
+const md = new MarkdownIt({ html: false, highlight: highlightCode });
 md.use(bindingPlugin);
 md.use(attrsPlugin);
+md.use(anchorPlugin);
 
-// Raw HTML in markdown passes through by default (a documented design choice).
-// Pages can opt out with frontmatter `html: false` for untrusted content; the
-// stricter instance is built lazily so the default path stays a single instance.
+// Raw HTML in markdown is escaped by default: a stray `<script>` or `onerror=`
+// attribute in content renders as inert text, so multi-author content (blog
+// collections, contributed docs) is stored-XSS-safe out of the box. A page
+// whose author writes their own HTML opts in with frontmatter `html: true`;
+// that instance is built lazily so the default path stays a single instance.
 /** @type {MarkdownIt | null} */
-let mdNoHtml = null;
+let mdRawHtml = null;
 /**
- * Pick the markdown-it instance for a page (raw HTML on by default, off with `html: false`).
+ * Pick the markdown-it instance for a page (raw HTML off by default, on with `html: true`).
  * @param {Meta} [meta]
  * @returns {MarkdownIt}
  */
 export function selectMd(meta) {
   // Frontmatter scalars stay strings (no coercion), so accept both forms.
-  if (meta?.html !== false && meta?.html !== "false") return md;
-  if (!mdNoHtml) {
-    mdNoHtml = new MarkdownIt({ html: false, highlight: highlightCode });
-    mdNoHtml.use(bindingPlugin);
-    mdNoHtml.use(attrsPlugin);
+  if (meta?.html !== true && meta?.html !== "true") return md;
+  if (!mdRawHtml) {
+    mdRawHtml = new MarkdownIt({ html: true, highlight: highlightCode });
+    mdRawHtml.use(bindingPlugin);
+    mdRawHtml.use(attrsPlugin);
+    mdRawHtml.use(anchorPlugin);
   }
-  return mdNoHtml;
+  return mdRawHtml;
 }
 
 /**
@@ -59,7 +63,8 @@ export function selectMd(meta) {
 export function renderProse(text, ctx) {
   text = resolveDestinationBindings(text, ctx);
   return (ctx.md ?? md).render(text, {
-    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx)
+    resolveBinding: (/** @type {string} */ expr) => resolveBindingHtml(expr, ctx),
+    headingSlugs: ctx.comp.headingSlugs
   });
 }
 
@@ -197,6 +202,51 @@ export function attrTarget(children, i) {
   return null;
 }
 
+/**
+ * GitHub-style heading slug: lowercase, punctuation stripped (letters, numbers,
+ * whitespace, `_`, and `-` survive), each whitespace character becomes a hyphen.
+ * Punctuation-only headings fall back to `"section"` so the id is never empty.
+ * @param {string} text Plain heading text.
+ * @returns {string}
+ */
+export function slugify(text) {
+  const slug = text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]+/gu, "")
+    .replace(/\s/gu, "-");
+  return slug || "section";
+}
+
+/**
+ * markdown-it plugin (core rule): every heading gets a stable slugified `id`
+ * so long pages are linkable without any JS. Duplicate slugs dedupe with
+ * `-1`/`-2` suffixes; the counters live in `env.headingSlugs` so a page whose
+ * prose renders in chunks (directives between headings) still dedupes across
+ * the whole document. Bindings and inline HTML inside a heading contribute no
+ * slug text — only literal text and inline code do.
+ * @param {MarkdownIt} mdInstance
+ * @returns {void}
+ */
+function anchorPlugin(mdInstance) {
+  mdInstance.core.ruler.push("wd_heading_anchors", (state) => {
+    const counts = (state.env.headingSlugs ??= new Map());
+    const tokens = state.tokens;
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].type !== "heading_open") continue;
+      let text = "";
+      for (const child of tokens[i + 1].children ?? []) {
+        if (child.type === "text" || child.type === "code_inline") text += child.content;
+      }
+      const base = slugify(text);
+      const seen = counts.get(base) ?? 0;
+      counts.set(base, seen + 1);
+      tokens[i].attrSet("id", seen ? `${base}-${seen}` : base);
+    }
+    return false;
+  });
+}
+
 /**
  * Resolve a `{ name.path }` binding to HTML: loop item span, static value, or
  * a reactive bind span. Returns null when nothing in scope matches.