@zvndev/darkmown 2.0.0 → 2.0.1

package/AGENTS.md

@@ -7,7 +7,7 @@ Darkmown is a Markdown-native web framework. You build sites by writing `.md` an
 - `.md` files are plain CommonMark. Directives stay inert text.
 - `.wd` files are the same Markdown **plus directives** (state, loops, conditionals, includes, forms).
 - To make a `.md` page interactive, **rename it to `.wd`**. ⚠️ Renaming means the old `.md` is **gone** — never leave both `index.md` and `index.wd`, that is a fatal `Duplicate route` build error. Upgrade = delete the `.md`, create the `.wd`.
-- Static pages ship **zero** JavaScript; a page loads the ~7.4 KB gzipped runtime (CI-enforced under 8 KB) only if it declares reactive behavior.
+- Static pages ship **zero** JavaScript; a page loads the ~7.5 KB gzipped runtime (CI-enforced under 8 KB) only if it declares reactive behavior.
 
 ### ⚠️ Raw HTML is escaped by default (since 2.0.0)
 

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.0.1 — 2026-07-11
+
+A tightening pass from a post-2.0 product review: a silent reactive-loop failure becomes a loud compile error, scaffolds stop shipping the raw-HTML footgun, and every scaffolded page gets real landmarks back. All compile-time — the runtime is byte-identical (7518 B gzipped).
+
+- **A third reactive `@loop` level is now a compile error.** The runtime supports one level of reactive nesting; a third reactive level previously compiled clean and painted the inner region empty at runtime. It now fails the build with `file:line`, the offending opener quoted, and a corrective suggestion — including when the third level arrives through an `@include` (nesting depth threads across the include boundary). Static (build-unrolled) nesting is unaffected at any depth.
+- **`::: nav` and `::: main` containers emit real landmark elements.** A container named `nav` or `main` now compiles to `<nav class="nav">` / `<main class="main">` instead of a `<div>` (the name stays as a class, so existing `.nav`/`.main` skin selectors match unchanged; every other name still emits a `<div>`). With that, the shell reuses the container's `<main>` for its `id="main"` skip-link target instead of wrapping the whole body — nav chrome sits outside `<main>` and "Skip to content" actually skips it.
+- **Scaffold templates no longer set `html: true`.** 2.0.0 made escaped markdown the default and called raw-HTML mode the #1 footgun — while every template scaffolded with the flag on. All five templates now express their nav/layout/CTAs with container directives and `{.class}` inline attributes instead of raw HTML (zero `html: true` anywhere in a fresh scaffold), and with the landmark containers above they keep proper `<nav>`/`<main>` structure. The starter's `about.md` becomes pure CommonMark with a "Back home" link — a `.md` page can't include the shared nav, and the page now says so instead of duplicating raw markup.
+- **`file:line` on the remaining compile errors.** Malformed `@loop` headers and include-resolution failures (unresolvable path, sandbox escape) reported only the file; they now report `file:line` like every other directive error, and the unresolvable-include message gained a hint ("Looked in site/pages and site/_ — check the path and leading slash").
+- **Size prose is drift-guarded.** Docs and site copy quoting the runtime size (now "~7.5 KB" everywhere current-tense) are asserted against `.size-snapshot.json` by a new test, so the number in the prose can never silently diverge from the shipped bytes again.
+- **darkmown.com hero: install one-liner with a copy button.** The landing page now puts `npx @zvndev/darkmown init my-site` (click-to-copy) directly under the CTAs, and the site docs gained a CLI reference section covering all six commands.
+- **Internal: a build-throughput benchmark.** `npm run bench:build` generates a synthetic site (collections, includes, static loops, highlighted code) and reports pages/sec; it refuses to touch a `site/` directory it didn't generate itself.
+
 ## 2.0.0 — 2026-07-11
 
 The raw-HTML markdown default flips to escaped (`html: false` — the breaking change that makes this a major), alongside security hardening and a DX pass from a product review: incremental dev rebuilds, true error line numbers, a docs table of contents, and styled templates. Nearly all build-time and dev-server; the one runtime change — deterministic UTC date pipes — nudges the runtime to 7518 B gzipped, still well under the 8 KB budget.

package/README.md

@@ -7,7 +7,7 @@
 
 **[darkmown.com](https://darkmown.com)** · Markdown that runs.
 
-Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~7.4 KB gzipped, CI-enforced under 8 KB.
+Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~7.5 KB gzipped, CI-enforced under 8 KB.
 
 ## Showcase
 
@@ -65,7 +65,7 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 - Files or folders starting with `.`, `-`, or `_` are hidden from routing.
 - `site/_` is the include shelf for `@include /name.wd`.
 - Matching `page.skin` and `page.js` colocate styling and behavior by basename.
-- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~7.4 KB gzipped, CI-enforced under 8 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~7.5 KB gzipped, CI-enforced under 8 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -353,7 +353,7 @@ That is a full add-to-cart / remove-line flow — and a to-do list with delete
 - Interpolation inside the inner body resolves the inner item first, then the outer item — `{ line.qty }` and `{ order.ref }` are both in scope.
 - Build-time loops over JSON/frontmatter already nest freely (the "loops nest" behavior above); what's new is **reactive-inside-reactive** over a `:state`/`:store`/`:fetch` row field.
 
-> **Honest caveat:** nesting is **one level only** — an inner reactive loop may not itself contain a third reactive loop. Build-time loop nesting is unaffected by this limit.
+> **Honest caveat:** nesting is **one level only** — an inner reactive loop that itself contains a third reactive loop is a **compile error** with a corrective message, not a silent runtime failure. Build-time loop nesting is unaffected by this limit.
 >
 > **Per-row actions inside an inner loop:** `cart += member` (append-row) works from an inner loop — it carries the inner item into a top-level `:state`/`:store` list. But a per-row **`remove`** needs a top-level list as its source, and an inner loop's source is a path off the outer row (`team.members`), so deleting an inner row in place is **not** supported — the compiler rejects it with a corrective message. Carry the row into a top-level list and remove it there.
 
@@ -440,6 +440,8 @@ Cart has { count } items.
 
 State declared inside a section is scoped to it — two sections can both own a `count`. Bindings and actions resolve to the nearest scope.
 
+A container named `nav` or `main` emits the real landmark element (`<nav class="nav">`, `<main class="main">`) instead of a `<div>`, so scaffolded pages keep proper landmarks — a skip link skips a `::: nav`, and `::: main` becomes the page's `<main id="main">`. Any other name stays a `<div>` with that class.
+
 ### Reactive classes — `.class when <predicate>`
 
 A container class can be toggled by a predicate. Static `.class` tokens are unchanged; add `when <predicate>` to make one reactive:

package/docs/spec-alignment.md

@@ -6,10 +6,11 @@ This audit compares the current Darkmown implementation with the original MARROW
 
 - **Markdown-first authoring:** `.md` is strict CommonMark rendered by a real parser (markdown-it); `.wd` is the same Markdown plus first-party directives. Renaming the file is the upgrade path — extensions genuinely gate functionality.
 - **Content tree over components:** routing, includes, and repeated fragments are file/document based instead of React-style components.
-- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~7.4 KB gzipped, CI-enforced below the 8 KB target).
+- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~7.5 KB gzipped, CI-enforced below the 8 KB target).
 - **No virtual DOM:** state changes patch direct DOM bindings, conditional regions, and keyed loop regions.
 - **Keyed list patching:** reactive loops reconcile by item key (`id`/`key`/value) instead of re-rendering the region.
 - **Sections with scoped state:** `::: section #id .class` containers scope `:state`; bindings and actions resolve through the nearest scope chain.
+- **Semantic landmark containers:** `::: nav` / `::: main` emit the real `<nav>`/`<main>` element (keeping the name as a class for styling); other container names stay `<div>`s. Keeps skip links and landmarks intact without raw HTML.
 - **`.skin` language:** indentation-based token styling compiles to CSS.
 - **Folder router:** `site/pages` maps to routes, and `.`, `-`, `_` prefixes hide pages.
 - **Colocation:** matching `.skin` and `.js` files attach to the page by basename, for includes too.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -35,7 +35,8 @@
     "prepare": "husky || true",
     "prepublish:check": "npm run typecheck && npm run test:cov && npm run build && npm run runtime:size && npm audit --audit-level=high && npm run smoke",
     "prepublishOnly": "npm run prepublish:check",
-    "og": "node scripts/og-image.mjs"
+    "og": "node scripts/og-image.mjs",
+    "bench:build": "node scripts/bench-build.mjs"
   },
   "lint-staged": {
     "*.{js,json}": "biome check --no-errors-on-unmatched --files-ignore-unknown=true"

package/site/_/footer.wd

@@ -6,7 +6,7 @@ html: true
   <div class="foot-inner">
     <div>
       <strong>Darkmown</strong> — Markdown that runs.
-      <div class="small">Zero JS on static pages · one ~7.4&nbsp;KB runtime when reactive.</div>
+      <div class="small">Zero JS on static pages · one ~7.5&nbsp;KB runtime when reactive.</div>
     </div>
     <nav class="foot-links">
       <a href="/docs/">Docs</a>

package/site/pages/app.wd

@@ -20,7 +20,7 @@ This whole section is plain Markdown. The list below is unrolled **at build time
 - **{ feature.title }** — { feature.body }
 @endloop
 
-<aside class="boundary">If you deleted everything below this line, this page would ship <strong>zero</strong> bytes of JavaScript. Everything above is static HTML. Below is where the one ~7.4&nbsp;KB gzipped runtime loads (CI-enforced under 8 KB) — and only because the document asks for it.</aside>
+<aside class="boundary">If you deleted everything below this line, this page would ship <strong>zero</strong> bytes of JavaScript. Everything above is static HTML. Below is where the one ~7.5&nbsp;KB gzipped runtime loads (CI-enforced under 8 KB) — and only because the document asks for it.</aside>
 
 ## Fetched data, looped, with nested conditions
 

package/site/pages/blog/zero-js-by-default.md

@@ -15,7 +15,7 @@ none of them pay for it.
 
 That is the whole bargain. A `.md` file is plain CommonMark. Rename it to `.wd`
 and you unlock directives — state, loops, conditionals — but you only ship the
-~7.4 KB runtime on the pages that actually use them. A listing built from a
+~7.5 KB runtime on the pages that actually use them. A listing built from a
 collection loop resolves entirely at build time, so it stays static HTML.
 
 ## The extension is the feature gate

package/site/pages/docs/index.wd

@@ -47,6 +47,7 @@ Darkmown is a Markdown-native framework for mostly-static sites with tiny reacti
 - [Syntax highlighting](#syntax-highlighting)
 - [Trust boundary](#trust-boundary)
 - [Colocation](#colocation)
+- [CLI reference](#cli-reference)
 - [Spec status](#spec-status)
 </nav>
 
@@ -308,9 +309,11 @@ You don't size images by hand. Every `<img>` the compiler emits gets its intrins
 
 `::: section #id .class` opens a container and `:::` closes it. Sections scope state: a `:state` declared inside a section belongs to that section, so two sections can both declare `count` without colliding. Bindings and buttons resolve to the nearest scope.
 
+A container named `nav` or `main` emits the real landmark element (`<nav class="nav">`, `<main class="main">`) so pages keep proper landmarks without raw HTML. Any other name stays a `<div>` with that class.
+
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~7.4 KB gzipped, under a CI-enforced 8 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~7.5 KB gzipped, under a CI-enforced 8 KB budget). Static pages do not.
 
 ```wd
 :state count = 0
@@ -599,6 +602,17 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/master/SECURITY.md) i
 - Both work for included fragments too, by basename.
 - Any other file under `site/pages/` (an image, font, PDF — anything that isn't a `.md`/`.wd` route or a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type. So `site/pages/logo.svg` is served at `/logo.svg`. Assets below hidden path segments (`.`, `-`, or `_`) and symlinked page assets are skipped, matching the routing privacy rule. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
 
+## CLI reference
+
+The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool — every command is one word:
+
+- `darkmown init [dir] [--template <name>]` — scaffold a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`). Existing files are never overwritten.
+- `darkmown dev` — the live compiler: browser reload, an in-browser error overlay, incremental rebuilds, and a local runner for `api/*` functions.
+- `darkmown build [--target cloudflare] [--drafts]` — write 100% static output to `dist/` (plus `sitemap.xml` / `rss.xml` / `robots.txt`); `--drafts` includes `draft: true` pages for a staging deploy.
+- `darkmown serve` — preview the built `dist/` locally (static only; use `dev` to exercise `api/*`).
+- `darkmown deploy <vercel|cloudflare> [--prod]` — build (target-aware) and deploy through the platform CLI, printing your URL; an unauthenticated CLI surfaces the login to run first.
+- `darkmown version` / `darkmown help` — print the installed version, or the full command summary and directive syntax.
+
 ## Spec status
 
 The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:store`, the full `:fetch` lifecycle (loading/error/empty states, dynamic URLs, `refetch`, dotted loop sources, authenticated `headers=` + `refresh=` token renewal), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `:if … :else if … :else`, reactive `.class when …`, `:effect`, `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/) and the [Reactive page](/reactive/). Still on the roadmap: HTML-fragment `swap` semantics and cart server sync. (The serverless `api/` model already shipped in 1.2.0 — see [Backends & deploy](#backends--deploy) above; a `.wd` backend DSL remains a deliberate non-goal.) See `docs/spec-alignment.md` in the package for the full audit.

package/site/pages/index.js

@@ -1,3 +1,22 @@
+const copyBtn = document.querySelector("[data-copy-cmd]");
+
+if (copyBtn) {
+  copyBtn.addEventListener("click", async () => {
+    const cmd = copyBtn.previousElementSibling?.textContent ?? "";
+    try {
+      await navigator.clipboard.writeText(cmd);
+      copyBtn.textContent = "Copied";
+      copyBtn.classList.add("is-copied");
+      setTimeout(() => {
+        copyBtn.textContent = "Copy";
+        copyBtn.classList.remove("is-copied");
+      }, 1600);
+    } catch {
+      copyBtn.textContent = "Select + ⌘C";
+    }
+  });
+}
+
 const button = document.querySelector("[data-wd-demo]");
 
 if (button) {

package/site/pages/index.skin

@@ -29,7 +29,52 @@
 .hero-cta
   display flex
   flex-wrap wrap
-  margin-bottom 2rem
+  margin-bottom 1.5rem
+
+.hero-install
+  display inline-flex
+  align-items center
+  gap .55rem
+  max-width 100%
+  margin 0 0 2rem
+  padding .7rem 1rem
+  border 1px solid $line
+  radius 10px
+  bg $sunk
+  font-family ui-monospace, SFMono-Regular, Menlo, monospace
+  overflow-x auto
+
+.hero-install::before
+  content "$"
+  color $accent
+  font-weight 700
+  flex-shrink 0
+
+.hero-install code
+  font-family inherit
+  font-size .95rem
+  color $ink
+  white-space nowrap
+
+.hero-install .copy-cmd
+  flex-shrink 0
+  margin-left .35rem
+  padding .25rem .65rem
+  border 1px solid $line
+  radius 7px
+  bg transparent
+  color $ink-soft
+  font-family inherit
+  font-size .8rem
+  cursor pointer
+
+.hero-install .copy-cmd:hover
+  color $ink
+  border-color $accent
+
+.hero-install .copy-cmd.is-copied
+  color $accent
+  border-color $accent
 
 .hero-stats
   display grid

package/site/pages/index.wd

@@ -24,9 +24,11 @@ The left file is Markdown. It is also a running app — a live search filter, ad
 <a class="btn" href="/docs/">Read the docs</a>
 </div>
 
+<div class="hero-install"><code>npx @zvndev/darkmown init my-site</code><button type="button" class="copy-cmd" data-copy-cmd aria-label="Copy install command">Copy</button></div>
+
 <ul class="hero-stats">
   <li><strong>0 KB</strong><span>framework JS on static pages</span></li>
-  <li><strong>~7.4 KB</strong><span>one runtime, CI-enforced &lt; 8 KB</span></li>
+  <li><strong>~7.5 KB</strong><span>one runtime, CI-enforced &lt; 8 KB</span></li>
   <li><strong>1</strong><span>loop and one binding to learn</span></li>
   <li><strong>MIT</strong><span>zero runtime dependencies</span></li>
 </ul>
@@ -110,14 +112,14 @@ Markdoc.renderers.react(content, React, {
 
 </section>
 
-:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~7.4 KB gzipped runtime loads (CI-enforced under 8 KB), never before. JS optional, CSS optional, always."
+:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~7.5 KB gzipped runtime loads (CI-enforced under 8 KB), never before. JS optional, CSS optional, always."
 
 <section class="props">
 
 ## Three rules, no escape hatch
 
 - **Zero-JS static.** A page with no state ships no framework JavaScript. `/markdown/` and `/docs/` prove it — open them and check the network tab.
-- **One runtime.** Every reactive page shares the same ~7.4 KB gzipped runtime, CI-enforced under 8 KB. No per-component bundles, no hydration tax that scales with your UI.
+- **One runtime.** Every reactive page shares the same ~7.5 KB gzipped runtime, CI-enforced under 8 KB. No per-component bundles, no hydration tax that scales with your UI.
 - **One loop, one binding.** `@loop … into …` is the only loop; `{ name }` is the only interpolation. Nothing else to learn, nothing else to misuse.
 
 </section>

package/site/pages/showcase/index.wd

@@ -96,7 +96,7 @@ Darkmown's whole pitch is weight. A static page ships **zero** framework JavaScr
 
 ::: card .sc-scale
 - **Static Darkmown page** — `0 KB` framework JS. Forever.
-- **Reactive Darkmown page** — one shared `~7.4 KB` gzipped runtime, no per-component bundles.
+- **Reactive Darkmown page** — one shared `~7.5 KB` gzipped runtime, no per-component bundles.
 - **A typical SPA** — ships a framework runtime in the **~15–60 KB** gzipped range *before* your app code, on every page (Alpine ~15 KB, Vue ~18 KB runtime, React 19 ~59 KB).
 :::
 

package/src/compiler/context.js

@@ -102,15 +102,24 @@
  * @property {string[]} sections Active section-id scope chain.
  * @property {string | null} loopItem Name of the current reactive loop item, if any.
  * @property {string} [loopKey] State key of the list being looped, if any.
+ * @property {number} [reactiveDepth] Number of enclosing REACTIVE `@loop` levels
+ *   (0 at top level). The runtime reconciles at most two nested `data-wd-loop`
+ *   levels — a third paints empty — so a third reactive level is rejected at
+ *   compile time. Static (build-unrolled) loops flatten to markup and don't add
+ *   a level, so they carry the count through without incrementing it.
+ * @property {{ at: string, line: string }} [loopOpener] The current `@loop`
+ *   opener's `file:line` + raw text, set when descending into a loop body so the
+ *   reactive-nesting-depth error can point at the offending opener.
  * @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
+ * @property {(file: string, context: Paths, stack: string[], scope: Scope, comp: Compilation, sections: string[], loopItem: string | null, reactiveDepth?: number, loopOpener?: { at: string, line: string } | null) => { meta: Meta, html: string }} compileFile
  *   The per-file compile, threaded for the same reason so `@include` can
- *   compile its target file.
+ *   compile its target file. `reactiveDepth`/`loopOpener` carry the enclosing
+ *   reactive-loop nesting across the include boundary so the depth guard holds.
  */
 
 /**

package/src/compiler/includes.js

@@ -158,9 +158,13 @@ export function collectColocatedAssets(file, context, assets) {
  * @param {string} fromFile File requesting the include.
  * @param {Paths} context
  * @param {boolean} [allowAny] Allow non-page extensions (e.g. JSON for `@loop`).
+ * @param {string} [loc] Source location (`file:line`) for the error messages, so
+ *   an unresolved/out-of-sandbox include reports the directive's line. Callers
+ *   with a line index pass `at(ctx, index)`; it defaults to `fromFile` (the bare
+ *   path) for any caller without one, preserving the file-only message.
  * @returns {string}
  */
-export function resolveInclude(spec, fromFile, context, allowAny = false) {
+export function resolveInclude(spec, fromFile, context, allowAny = false, loc = fromFile) {
   const clean = stripQuotes(spec);
   const candidates = [];
   if (clean.startsWith("/")) {
@@ -172,13 +176,15 @@ export function resolveInclude(spec, fromFile, context, allowAny = false) {
   for (const candidate of candidates) {
     const resolved = path.resolve(candidate);
     if (!isAllowedInclude(resolved, context)) {
-      throw new Error(`Include "${spec}" from ${fromFile} resolves outside site/pages or site/_`);
+      throw new Error(`Include "${spec}" from ${loc} resolves outside site/pages or site/_`);
     }
     if (!fs.existsSync(resolved)) continue;
     if (!allowAny && !pageIncludeExtensions.includes(path.extname(resolved))) continue;
     return resolved;
   }
-  throw new Error(`Could not resolve include "${spec}" from ${fromFile}`);
+  throw new Error(
+    `Could not resolve include "${spec}" from ${loc}. Looked in site/pages and site/_ — check the path and leading slash.`
+  );
 }
 
 /**

package/src/compiler/loops.js

@@ -219,7 +219,7 @@ function numArgAttr(arg) {
  */
 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}`);
+  if (!match) throw new Error(`Malformed @loop in ${at(ctx, index)}: ${line}. ${LOOP_USAGE}`);
   const source = stripQuotes(match[1].trim());
   const itemName = match[2];
   const clauses = match[3]
@@ -273,8 +273,13 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     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);
+  // in the empty branch, via `opts.emptyStart`) report the true file line. The
+  // opener's location rides on the body ctx so a reactive loop nested inside this
+  // one can point the depth error back at its own opener line.
+  const bodyCtx = {
+    ...nestedCtx(ctx, index + 1),
+    loopOpener: { at: at(ctx, index), line: line.trim() }
+  };
 
   if (
     source.startsWith("/") ||
@@ -283,7 +288,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx, index, emptyStart =
     source.endsWith(".json")
   ) {
     if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
-    const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
+    const dataFile = resolveInclude(source, ctx.file, ctx.context, true, at(ctx, index));
     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}`);
@@ -372,6 +377,27 @@ function paginateOnlyCollections(ctx) {
   return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
 }
 
+/**
+ * Reject a reactive `@loop` that would open a THIRD reactive nesting level. The
+ * runtime reconciles at most two nested `data-wd-loop` levels (an outer loop and
+ * one inner loop); a third level's `data-wd-loop-out` paints empty. This guards
+ * every reactive-region entry point ({@link reactiveLoop}, {@link itemRelativeLoop}),
+ * so a state-key, item-relative, or state-filtered source is all covered. Static
+ * (build-unrolled) loops carry the depth through without incrementing it, so an
+ * interleaved static level neither triggers nor masks the limit.
+ * `ctx.reactiveDepth` is the number of reactive loops already enclosing this one.
+ * @param {Ctx} ctx
+ * @returns {void}
+ */
+function assertReactiveDepth(ctx) {
+  if ((ctx.reactiveDepth ?? 0) < 2) return;
+  const opener = ctx.loopOpener ?? { at: ctx.file, line: "" };
+  throw new Error(
+    `Reactive @loop nesting is limited to one inner level in ${opener.at}: "${opener.line}". ` +
+      `Unroll the outer data at build time (JSON/frontmatter source) or move the innermost list into build-time data.`
+  );
+}
+
 /**
  * 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).
@@ -540,6 +566,7 @@ function staticUnroll(rows, itemName, bodyLines, ctx, empty = null, emptyStart =
  * @returns {string}
  */
 function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
+  assertReactiveDepth(ctx);
   ctx.comp.assets.runtime = true;
   /** @type {Ctx} */
   const templateCtx = {
@@ -547,6 +574,7 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
     loopItem: itemName,
     loopKey: key ?? undefined,
     loopMeta: true,
+    reactiveDepth: (ctx.reactiveDepth ?? 0) + 1,
     scope: createScope(ctx.scope)
   };
   const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();
@@ -689,6 +717,7 @@ function loopClauseAttrs(c) {
  * @returns {string}
  */
 function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
+  assertReactiveDepth(ctx);
   /** @type {Ctx} */
   // loopKey: undefined — an item-relative loop's source is a path off the outer
   // row, not a top-level state key, so a per-row `remove` inside it has no valid
@@ -698,6 +727,7 @@ function itemRelativeLoop(path, itemName, bodyLines, ctx, opts) {
     loopItem: itemName,
     loopKey: undefined,
     loopMeta: true,
+    reactiveDepth: (ctx.reactiveDepth ?? 0) + 1,
     scope: createScope(ctx.scope)
   };
   const templateHtml = ctx.compileBody(bodyLines, templateCtx).trim();

package/src/compiler/page.js

@@ -293,7 +293,17 @@ function measureImage(src, paths) {
 export function compileDocument(file, context, stack = [], vars = {}, collections = new Map()) {
   const comp = createCompilation();
   comp.collections = collections;
-  const result = compileFile(file, context, stack, createScope(null, vars), comp, [], null);
+  const result = compileFile(
+    file,
+    context,
+    stack,
+    createScope(null, vars),
+    comp,
+    [],
+    null,
+    0,
+    null
+  );
   return {
     meta: result.meta,
     html: result.html,
@@ -314,9 +324,24 @@ export function compileDocument(file, context, stack = [], vars = {}, collection
  * @param {Compilation} comp
  * @param {string[]} sections
  * @param {string | null} loopItem
+ * @param {number} [reactiveDepth] Enclosing REACTIVE `@loop` levels, threaded in
+ *   from the including page so an include's body can't bypass the two-level
+ *   reactive-nesting limit at the `@include` boundary.
+ * @param {{ at: string, line: string } | null} [loopOpener] The enclosing `@loop`
+ *   opener, threaded in so a depth error inside the include names the right opener.
  * @returns {{ meta: Meta, html: string }}
  */
-export function compileFile(file, context, stack, scope, comp, sections, loopItem) {
+export function compileFile(
+  file,
+  context,
+  stack,
+  scope,
+  comp,
+  sections,
+  loopItem,
+  reactiveDepth = 0,
+  loopOpener = null
+) {
   const real = fs.realpathSync(file);
   if (stack.includes(real)) {
     throw new Error(
@@ -351,6 +376,8 @@ export function compileFile(file, context, stack, scope, comp, sections, loopIte
     comp,
     sections,
     loopItem,
+    reactiveDepth,
+    ...(loopOpener ? { loopOpener } : {}),
     md: selectMd(meta),
     compileBody,
     compileFile

package/src/compiler/structure.js

@@ -27,6 +27,14 @@ import { compileWhen, evalPredicate } from "./predicates.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Container names that emit their own semantic landmark element instead of a
+// `<div>`, so scaffolds get real `<nav>`/`<main>` landmarks (accessibility: the
+// skip link targets a genuine main-content region and navigation chrome sits in
+// its own landmark). The name is still added as a class, so existing `.nav`/
+// `.main` skin selectors keep working. Fixed compiler-owned constants — never
+// author-supplied — so no tag-injection surface; classes/ids still escape.
+const SEMANTIC_CONTAINER_TAGS = new Set(["nav", "main"]);
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -36,9 +44,13 @@ import { compileWhen, evalPredicate } from "./predicates.js";
 export function handleInclude(line, ctx, index) {
   const match = line.match(/^@include\s+(\S+)(?:\s+with\s+(.+))?$/);
   if (!match) throw new Error(`Malformed @include in ${at(ctx, index)}: ${line}`);
-  const target = resolveInclude(match[1], ctx.file, ctx.context);
+  const target = resolveInclude(match[1], ctx.file, ctx.context, false, at(ctx, index));
   const args = parseIncludeArgs(match[2] || "", ctx);
   const childScope = createScope(ctx.scope, args);
+  // Thread the reactive-nesting depth (and the enclosing loop opener, so a depth
+  // error names the right opener) into the include, exactly as `loopItem` is —
+  // otherwise a reactive @loop inside the include would start counting from zero
+  // and could open a THIRD nested `data-wd-loop` level that silently paints empty.
   const child = ctx.compileFile(
     target,
     ctx.context,
@@ -46,7 +58,9 @@ export function handleInclude(line, ctx, index) {
     childScope,
     ctx.comp,
     ctx.sections,
-    ctx.loopItem
+    ctx.loopItem,
+    ctx.reactiveDepth ?? 0,
+    ctx.loopOpener ?? null
   );
   // An include with its OWN scoped colocated skin stamps just its returned
   // subtree — so a scoped `.card` in the include can't collide with a `.card`
@@ -102,14 +116,22 @@ export function handleContainer(header, bodyLines, ctx, index) {
   const stateClasses = [];
   let id = "";
   // Leading tag/name token (anything not starting with . or #). "section" keeps
-  // the <section> tag; any other name becomes a <div> and also a class.
+  // 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*)/);
   let nameToken = "section";
   if (lead) {
     nameToken = lead[1];
     rest = rest.slice(lead[0].length).trim();
   }
-  if (nameToken !== "section") {
+  if (nameToken === "section") {
+    // default tag, no class
+  } else if (SEMANTIC_CONTAINER_TAGS.has(nameToken)) {
+    tag = nameToken;
+    extraClass.push(nameToken);
+  } else {
     tag = "div";
     extraClass.push(nameToken);
   }

package/src/templates/blog/site/_/nav.wd

@@ -1,10 +1,7 @@
----
-html: true
----
+::: nav
+**My Blog**
 
-<nav>
-  <strong>My Blog</strong>
-  <span class="links">
-    <a href="/">Posts</a>
-  </span>
-</nav>
+::: links
+[Posts](/)
+:::
+:::

package/src/templates/blog/site/pages/index.skin

@@ -27,12 +27,12 @@ page
   line-height 1.6
   -webkit-font-smoothing antialiased
 
-main
+.main
   max-width 720px
   margin 0 auto
   padding 2.5rem 1.5rem
 
-nav
+.nav
   display flex
   align-items center
   justify-content space-between
@@ -40,10 +40,13 @@ nav
   margin 0 auto
   padding 1.25rem 1.5rem
 
-nav strong
+.nav p
+  margin 0
+
+.nav strong
   font-size 1.1rem
 
-nav a
+.nav a
   color $accent
   text-decoration none
 

package/src/templates/blog/site/pages/index.wd

@@ -1,5 +1,4 @@
 ---
-html: true
 title: My Blog
 description: A markdown-native blog built with Darkmown.
 site_url: https://example.com
@@ -8,7 +7,7 @@ transitions: true
 
 @include /nav.wd
 
-<main>
+::: main
 
 # My Blog
 
@@ -28,4 +27,4 @@ config, zero JavaScript; each post's frontmatter is the data.
 No posts yet — add a `.md` file to `site/pages/posts/`.
 @endloop
 
-</main>
+:::

package/src/templates/dashboard/site/_/nav.wd

@@ -1,10 +1,7 @@
----
-html: true
----
+::: nav
+**Dashboard**
 
-<nav>
-  <strong>Dashboard</strong>
-  <span class="links">
-    <a href="/">Overview</a>
-  </span>
-</nav>
+::: links
+[Overview](/)
+:::
+:::

package/src/templates/dashboard/site/pages/index.skin

@@ -18,12 +18,12 @@ page
   line-height 1.55
   -webkit-font-smoothing antialiased
 
-main
+.main
   max-width 880px
   margin 0 auto
   padding 2rem 1.5rem
 
-nav
+.nav
   display flex
   align-items center
   justify-content space-between
@@ -31,10 +31,13 @@ nav
   margin 0 auto
   padding 1.25rem 1.5rem
 
-nav strong
+.nav p
+  margin 0
+
+.nav strong
   font-size 1.1rem
 
-nav a
+.nav a
   color $accent
   text-decoration none
 

package/src/templates/dashboard/site/pages/index.wd

@@ -1,5 +1,4 @@
 ---
-html: true
 title: Dashboard — built with Darkmown
 description: A live dashboard — stat cards fetched from a serverless function, on an otherwise static page.
 transitions: true
@@ -7,7 +6,7 @@ transitions: true
 
 @include /nav.wd
 
-<main>
+::: main
 
 ::: section #dash
 
@@ -73,4 +72,4 @@ The numbers come from `api/metrics.js` — a serverless function that runs in
 
 :::
 
-</main>
+:::

package/src/templates/landing/site/_/nav.wd

@@ -1,10 +1,7 @@
----
-html: true
----
+::: nav
+**Acme**
 
-<nav>
-  <strong>Acme</strong>
-  <span class="links">
-    <a href="#start">Get started</a>
-  </span>
-</nav>
+::: links
+[Get started](#start)
+:::
+:::

package/src/templates/landing/site/pages/index.skin

@@ -27,12 +27,12 @@ page
   line-height 1.6
   -webkit-font-smoothing antialiased
 
-main
+.main
   max-width 900px
   margin 0 auto
   padding 1rem 1.5rem 4rem
 
-nav
+.nav
   display flex
   align-items center
   justify-content space-between
@@ -40,10 +40,13 @@ nav
   margin 0 auto
   padding 1.25rem 1.5rem
 
-nav strong
+.nav p
+  margin 0
+
+.nav strong
   font-size 1.15rem
 
-nav a
+.nav a
   color $accent
   text-decoration none
 
@@ -60,6 +63,9 @@ nav a
   color $muted
   margin 0 0 1.5rem
 
+.lede p
+  margin 0
+
 .cta
   display inline-flex
   align-items center
@@ -186,6 +192,9 @@ input:focus-visible, textarea:focus-visible, select:focus-visible
   color $muted
   font-size .95rem
 
+.quote .who p
+  margin 0
+
 .wd-carousel-prev
   position absolute
   left -.5rem

package/src/templates/landing/site/pages/index.wd

@@ -1,5 +1,4 @@
 ---
-html: true
 title: Acme — ship faster
 description: A marketing one-pager built with Darkmown. Zero framework JS on the static parts, with a testimonials carousel.
 transitions: true
@@ -7,12 +6,16 @@ transitions: true
 
 @include /nav.wd
 
-<main>
+::: main
 
 ::: hero
 # Ship faster with *Acme*
-<p class="lede">The all-in-one toolkit your team actually enjoys using.</p>
-<a class="cta" href="#start">Get started</a>
+
+::: lede
+The all-in-one toolkit your team actually enjoys using.
+:::
+
+[Get started](#start){.cta}
 :::
 
 ::: features
@@ -35,21 +38,31 @@ One command to Vercel or Cloudflare — your API comes along for free.
 :carousel
 ::: quote
 > "Acme cut our launch time in half."
-<p class="who">— Riley, Head of Product</p>
+
+::: who
+— Riley, Head of Product
+:::
 :::
 ::: quote
 > "The simplest stack we've ever shipped on."
-<p class="who">— Sam, CTO</p>
+
+::: who
+— Sam, CTO
+:::
 :::
 ::: quote
 > "Our marketing pages load instantly now."
-<p class="who">— Jordan, Growth</p>
+
+::: who
+— Jordan, Growth
+:::
 :::
 :endcarousel
 
 ::: cta-band #start
 ## Ready to build?
-<a class="cta" href="/">Start now</a>
+
+[Start now](/){.cta}
 :::
 
-</main>
+:::

package/src/templates/starter/site/_/nav.wd

@@ -1,11 +1,8 @@
----
-html: true
----
+::: nav
+**My site**
 
-<nav>
-  <strong>My site</strong>
-  <span class="links">
-    <a href="/">Home</a>
-    <a href="/about/">About</a>
-  </span>
-</nav>
+::: links
+[Home](/)
+[About](/about/)
+:::
+:::

package/src/templates/starter/site/pages/about.md

@@ -1,27 +1,16 @@
 ---
 title: About
-html: true
 ---
 
-<nav>
-  <strong>My site</strong>
-  <span class="links">
-    <a href="/">Home</a>
-    <a href="/about/">About</a>
-  </span>
-</nav>
-
-<main>
-
 # About
 
-This page is plain Markdown (`.md`) — strict CommonMark, zero framework JavaScript.
-Rename it to `.wd` when you want directives like state, loops, or forms — a `.wd`
-page can `@include /nav.wd` instead of repeating the markup above.
+This page is plain Markdown (`.md`) — strict CommonMark, zero framework
+JavaScript, and no raw HTML (Darkmown escapes it by default, so untrusted
+content can't inject markup). That's why there's no shared nav bar here: a
+`.md` page can't `@include` or use directives.
 
-The colocated `about.skin` styles this page; it attaches automatically by
-basename, `.md` or `.wd` alike.
+Rename it to `.wd` when you want that — state, loops, forms, and an
+`@include /nav.wd` for the shared nav. The colocated `about.skin` styles this
+page either way; it attaches automatically by basename, `.md` or `.wd` alike.
 
 [Back home](/)
-
-</main>

package/src/templates/starter/site/pages/about.skin

@@ -32,31 +32,6 @@ main
   margin 0 auto
   padding 3rem 1.5rem
 
-nav
-  display flex
-  align-items center
-  justify-content space-between
-  gap 1rem
-  max-width 760px
-  margin 0 auto
-  padding 1.25rem 1.5rem
-
-nav strong
-  font-size 1.1rem
-
-nav .links
-  display flex
-  gap 1.25rem
-
-nav a
-  color $ink
-  text-decoration none
-  opacity .8
-
-nav a:hover
-  opacity 1
-  color $accent
-
 a
   color $accent
 

package/src/templates/starter/site/pages/index.skin

@@ -27,12 +27,12 @@ page
   line-height 1.6
   -webkit-font-smoothing antialiased
 
-main
+.main
   max-width 760px
   margin 0 auto
   padding 3rem 1.5rem
 
-nav
+.nav
   display flex
   align-items center
   justify-content space-between
@@ -41,19 +41,23 @@ nav
   margin 0 auto
   padding 1.25rem 1.5rem
 
-nav strong
+.nav p
+  margin 0
+
+.nav strong
   font-size 1.1rem
 
-nav .links
+.nav .links p
   display flex
   gap 1.25rem
+  margin 0
 
-nav a
+.nav a
   color $ink
   text-decoration none
   opacity .8
 
-nav a:hover
+.nav a:hover
   opacity 1
   color $accent
 

package/src/templates/starter/site/pages/index.wd

@@ -1,11 +1,10 @@
 ---
-html: true
 title: My Darkmown site
 ---
 
 @include /nav.wd
 
-<main>
+::: main
 
 # My Darkmown site
 
@@ -25,4 +24,4 @@ Count: { count }
 
 :button "Add" -> todos += "Add a loop"
 
-</main>
+:::

package/src/templates/store/site/_/nav.wd

@@ -1,10 +1,7 @@
----
-html: true
----
+::: nav
+**Shop**
 
-<nav>
-  <strong>Shop</strong>
-  <span class="links">
-    <a href="/">Catalog</a>
-  </span>
-</nav>
+::: links
+[Catalog](/)
+:::
+:::

package/src/templates/store/site/pages/index.skin

@@ -27,12 +27,12 @@ page
   line-height 1.55
   -webkit-font-smoothing antialiased
 
-main
+.main
   max-width 860px
   margin 0 auto
   padding 2rem 1.5rem
 
-nav
+.nav
   display flex
   align-items center
   justify-content space-between
@@ -40,10 +40,13 @@ nav
   margin 0 auto
   padding 1.25rem 1.5rem
 
-nav strong
+.nav p
+  margin 0
+
+.nav strong
   font-size 1.1rem
 
-nav a
+.nav a
   color $accent
   text-decoration none
 

package/src/templates/store/site/pages/index.wd

@@ -1,5 +1,4 @@
 ---
-html: true
 title: Shop — built with Darkmown
 description: A storefront in Markdown — live search, a shared cart, and a checkout that posts to a serverless function.
 transitions: true
@@ -7,7 +6,7 @@ transitions: true
 
 @include /nav.wd
 
-<main>
+::: main
 
 ::: section #shop
 
@@ -81,4 +80,4 @@ to { receipt.received.email }. Order { receipt.orderId }.
 
 :::
 
-</main>
+:::