@zvndev/darkmown 0.4.0 → 0.6.0

package/AGENTS.md

@@ -0,0 +1,297 @@
+# Building with Darkmown — agent guide
+
+Darkmown is a Markdown-native web framework. You build sites by writing `.md` and `.wd` files. This sheet is everything you need. Read it fully before writing files, and **always ship styling** — an unstyled page is a failed page.
+
+## The one rule
+
+- `.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 ~2 KB runtime only if it declares reactive behavior.
+
+## Project layout & routing
+
+```
+site/
+  pages/        ← the route tree. index.wd → /, about.wd → /about/, docs/index.wd → /docs/
+  _/            ← include shelf + shared partials (not routed). nav.wd and shelf JSON live here.
+package.json
+```
+- **Folders are routes.** `site/pages/blog/post.wd` serves at `/blog/post/`.
+- Files/folders starting with `.`, `-`, or `_` are **hidden** from routing (drafts, partials).
+- A `page.skin` next to `page.wd` attaches styling; a `page.js` attaches behavior. Matched by basename.
+
+Commands: `darkmown dev`, `darkmown build`, `darkmown serve`.
+
+## Interpolation — one syntax
+
+`{ name }` or `{ name.path }`. Resolves in order: loop item → in-scope value → declared `:state` → otherwise literal text. **Declare state before you bind it** — compilation is line-based, top to bottom, so a `{ x }` or `:if x` must come *after* the `:state x` (or the `:form into x`) that creates it.
+
+## Directives — the complete set (nothing else exists)
+
+### State and buttons
+```wd
+:state count = 0
+:state cart = [] persist          ← persist = localStorage
+
+Count: { count }
+
+:button "Add" -> count++
+:button "Add 5" -> count += 5
+:button "Add item" -> cart += {"id": 1, "name": "Sticker"}
+:button "Reset" -> count = 0
+```
+Button actions are a **fixed whitelist**: `x++`, `x--`, `x += <number>`, `list += <json>`, `x = <json>`. Target must be declared `:state`. Values are JSON literals — they cannot reference loop items or other state. **`:button` is for state actions only** — for a link styled as a button, write raw HTML `<a class="btn" href="…">`.
+
+### Conditionals
+```wd
+:if count
+Shown when truthy.
+:else
+Shown when falsy.
+:endif
+```
+`:if name.path` tests a dotted path. Conditionals nest, including per-row inside a loop.
+
+### Loops — the only loop
+```wd
+@loop /products.json into product       ← JSON file: unrolled at build time
+- **{ product.name }** — { product.price }
+@endloop
+
+:state todos = [{"id": 1, "title": "Ship"}]
+@loop todos into todo                    ← :state list: reactive, patched by key
+- { todo.title }
+@endloop
+```
+Source: a JSON file path, an in-scope value, or a `:state` list. Loops nest; `:if todo.done` branches per row.
+
+### Filtering — `@loop … where` + live search with `:bind`
+```wd
+@loop /products.json into p where p.featured == true and p.price < 80
+- { p.name }                              ← item-only predicate → filtered at BUILD time, stays zero-JS
+@endloop
+
+:state products = [{"id":1,"name":"Aurora"},{"id":2,"name":"Briza"}]
+:state q = ""
+:bind q placeholder="Search"             ← <input> bound two-way to :state q
+@loop products into p where p.name contains q   ← predicate reads :state → reactive, re-filters live
+- { p.name }
+@endloop
+```
+`where` joins conditions with `and` / `or`. Operators: `==` `!=` `<` `<=` `>` `>=` and `contains` (case-insensitive substring). Operands are item paths (`p.field`), declared `:state`, numbers, or `"strings"` — whitelist-validated, no expressions. **Rule that decides JS: if the predicate only reads the row, it filters at build time and the page stays static; if it reads any `:state`, the loop becomes reactive.** `:bind name` is the input primitive for live filtering — it accepts `type=` (default `text`), `placeholder=`, `autocomplete=`, and `required` / `autofocus`.
+
+### Includes & sections
+```wd
+@include /nav.wd                         ← partial from site/_/
+@include /card.wd with title={ row.name }
+
+::: section #cart .panel                 ← container with id/classes; state inside is scoped to it
+:state items = []
+{ items.length } items
+:::
+```
+
+### Data, forms, computed
+```wd
+:fetch team from "/__wd/data/team.json"   ← loads JSON into state; sets team_error on failure
+:fetch quotes from "/q.json" when=visible ← lazy, on scroll into view
+
+:form into profile                        ← captures submit into state (declares `profile`), no backend
+:input name placeholder="Your name" required
+:input email type=email placeholder="Email"   ← set type= for email/number/etc (default is text)
+:submit "Save"
+:endform
+
+:if profile                               ← read form state AFTER :endform (see rule below)
+Thanks, **{ profile.name }**!
+:endif
+
+:computed total = items.length * 4         ← derived state; arithmetic & comparisons only
+```
+Shelf `.json` files (in `site/_/`) publish to `/__wd/data/`. `:form action="/api/x" into reply` posts urlencoded and lands the JSON reply in state (without JS it degrades to a native POST). Darkmown owns no backend — point forms at your own API.
+
+**Form-state rules (these cause most form failures):**
+- `:form into x` declares `x` only at `:endform`. A `:if x` (or `{ x.field }`) that reads it must come **after `:endform`**, never inside the form body.
+- State declared inside a `::: section` is **scoped to that section** (as `sectionId:x`). If you wrap a `:form into x` in a section, a `:if x` *outside* that section can't see it. Keep the form and the `:if` that reads it in the **same scope** — or don't wrap the form in a section.
+
+## What HTML each directive emits — target these in `.skin`
+
+Your `.skin` selectors must match the **real** output. The emitted HTML is:
+
+| You write | It renders as |
+|---|---|
+| `# Heading`, prose, `- list` | normal `<h1>`, `<p>`, `<ul><li>` (style by tag) |
+| `::: section #id .card … :::` | `<section id="id" class="card">…</section>` |
+| `::: name .card … :::` (non-`section`) | `<div class="card">…</div>` |
+| `:button "x" -> …` | `<button>x</button>` |
+| `:input email …` | `<input type="…">` |
+| `:bind q placeholder="…"` | `<input>` bound two-way to `:state q` |
+| `:submit "Go"` | `<button type="submit">Go</button>` |
+| `:form …` | `<form>…</form>` |
+| reactive `@loop` of a list | `<ul>`/`<ol>` (or `<div>`) of items |
+| `{ name }` | a text node |
+
+So style with real selectors: `section`, `.card`, `button`, `input`, `form`, `h1`. **To add a class to a container, use `::: name .class`. For any other custom element, write raw HTML `<div class="…">`. There is NO `{.class}` attribute syntax.**
+
+## Styling with `.skin` — ship this on every page
+
+A colocated `.skin` compiles to CSS. It is indentation-structural: a line is a **selector** if the next line is indented under it; otherwise it is a `property value` declaration. Start from a real design system — tokens, a type scale, spacing, a responsive grid:
+
+```skin
+tokens                       ← becomes :root CSS variables ($name → var(--name))
+  ink #14181f
+  muted #5b6470
+  paper #ffffff
+  bg #f6f7f9
+  accent #4f46e5
+  line #e6e8ec
+  radius 14px
+
+body
+  margin 0
+  font 16px/1.6 ui-sans-serif, system-ui, -apple-system, sans-serif
+  color $ink
+  background $bg
+
+main
+  max-width 960px
+  margin 0 auto
+  padding 4rem 1.5rem
+
+h1
+  font-size 3rem
+  line-height 1.05
+  letter-spacing -0.03em
+  margin 0 0 1rem
+
+.hero
+  padding 5rem 2rem
+  border-radius $radius
+  background linear-gradient(135deg, #4f46e5, #9333ea)
+  color white
+
+.grid
+  display grid
+  grid-template-columns repeat(3, 1fr)
+  gap 1.25rem
+
+.card
+  background $paper
+  border 1px solid $line
+  border-radius $radius
+  padding 1.5rem
+
+.actions
+  display flex
+  gap .75rem
+  flex-wrap wrap
+
+button
+  font-size 1rem
+  padding .7rem 1.2rem
+  border 0
+  border-radius 10px
+  background $accent
+  color white
+  cursor pointer
+  transition transform .15s ease, box-shadow .15s ease
+
+button:hover
+  transform translateY(-1px)
+  box-shadow 0 6px 20px rgba(79,70,229,.3)
+
+input
+  width 100%
+  padding .7rem .9rem
+  border 1px solid $line
+  border-radius 10px
+  font-size 1rem
+
+input:focus-visible
+  outline 2px solid $accent
+  outline-offset 2px
+
+@media (max-width: 640px)
+  .grid
+    grid-template-columns 1fr
+  h1
+    font-size 2.1rem
+```
+Always include: a tokens block, a real type scale, generous spacing, a `max-width` centered `main`, styled `button`/`input` with `:hover`/`:focus-visible` states, and a responsive `@media` rule (`.skin` supports `@media` — its indented rules are wrapped automatically). The `font` property is the CSS shorthand when it leads with a size (`font 16px/1.6 system-ui`) and `font-family` otherwise. Prefer `.skin`; a plain `<style>` block in a `.wd` also works.
+
+**Layout gotcha — CTAs and link rows.** Markdown wraps adjacent links/buttons on consecutive lines into a single `<p>`, so putting `display:flex` on their container won't space them. To lay out a row of buttons or nav links, wrap them in explicit raw HTML and style that:
+```wd
+<div class="actions">
+<a class="btn" href="/signup">Start free</a>
+<a class="btn ghost" href="/docs">Docs</a>
+</div>
+```
+
+### Page structure & hierarchy — required for styles to apply
+- **Wrap every page's body in `<main>`.** Your `main { … }` rules (centering, `max-width`, page padding) are dead unless the element exists.
+- **One `#` per page** (the H1/title). Use `##` for section headings (they render as `<h2>` — style those). Never emit two `<h1>`s.
+- **Only style classes you actually attach.** Add a class with `::: name .card` (container) or raw HTML `class="…"`. Don't write `.thanks { … }` then forget to put `.thanks` on the element — the styling silently does nothing. (Wrap a styled confirmation in `::: section .thanks … :::`.)
+- **Make cards feel real:** a subtle `box-shadow`, a `:hover` lift, and a distinct price/secondary-text color or weight. Avoid emoji as icons — they read as a default-AI tell; prefer an inline SVG or a styled monogram.
+- **Markdown is NOT parsed inside raw HTML blocks.** `**bold**` or `_em_` written inside a `<div>…</div>` renders as literal asterisks. Inside raw HTML use real tags (`<strong>`, `<em>`); use Markdown `**` only in plain prose lines.
+
+## The escape hatch — for logic directives can't express
+
+Directives are narrow on purpose. For real logic (filtering, custom interactions), use a colocated `.js` with `window.wd` (`wd.get`, `wd.set`, `wd.state`, `wd.render`). Section state is keyed `sectionId:name`.
+
+**Canonical "filter a list" pattern** (filtering is not a directive). Keep the fetched/source list intact and filter the rendered DOM — do not overwrite the source state, do not poll with setInterval:
+```wd
+<input id="q" placeholder="Search" autocomplete="off">
+
+:fetch products from "/__wd/data/products.json"
+:if products
+@loop products into p
+::: section .card
+**{ p.name }** — { p.price }
+:::
+@endloop
+:endif
+```
+```js
+// products.js
+const q = document.getElementById("q");
+q.addEventListener("input", () => {
+  const term = q.value.toLowerCase();
+  for (const card of document.querySelectorAll(".card")) {
+    card.style.display = card.textContent.toLowerCase().includes(term) ? "" : "none";
+  }
+});
+```
+This visual DOM filter is fine for a static fetched list. (Note: a `wd.render()` triggered by other state changes can reset the toggled `display`; for a list that also mutates reactively, re-apply the filter after such changes.)
+
+## Hard rules — do not break these
+
+1. **Never invent directives or syntax.** These do NOT exist: `@section`/`@endsection`, `{% if %}`, `{.class}` attribute lists, `:for`, `v-if`, JSX. The only container is `::: … :::`; the only loop is `@loop`; the only interpolation is `{ }`.
+2. **Always ship styling.** A `.skin` (or `<style>`) with a modern type scale, spacing, and a responsive rule — every page. Unstyled = failure.
+3. **`.skin` must target emitted HTML** (see the table). Verify selectors match real elements.
+4. **Rename = delete.** Upgrading `.md`→`.wd` means removing the `.md`. Never leave both.
+5. **Declare before you bind.** `:state` (or `:form into x`) must appear before any `{ x }` / `:if x` that reads it.
+6. **Whitelisted grammars only.** Button/`:computed` actions are fixed forms; arbitrary logic goes in a `.js` escape hatch.
+
+## Minimal complete page
+
+```wd
+---
+title: Hello
+---
+
+@include /nav.wd
+
+<main class="hero">
+
+# Hello
+
+:state count = 0
+
+You clicked { count } times.
+
+:button "Click" -> count++
+
+</main>
+```
+…with a colocated `index.skin` styling `.hero`, `button`, and the type scale.

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.6.0 — 2026-06-13
+
+- **State-driven list filtering — `@loop … where <predicate>`.** Filter any loop with conditions that join via `and` / `or`. Operators: `==` `!=` `<` `<=` `>` `>=` and `contains` (case-insensitive substring). Operands are item paths, declared `:state`, numbers, or `"strings"` — a compile-time whitelist (no expressions, no `eval`; `constructor`/`prototype`/`__proto__` rejected in compiler and runtime). **The predicate decides reactivity:** an item-only predicate filters at build time and the page stays zero-JS; a predicate that reads `:state` compiles to a reactive filtered loop driven by the keyed reconciler (rows are baked in for static JSON sources). This replaces the fragile DOM-toggle escape hatch — the #1 gap surfaced by the agent-eval benchmark.
+- **`:bind <state>`** — a two-way `<input>` bound to a `:state` value, the input primitive behind live search. Accepts `type=` (default `text`), `placeholder=`, `autocomplete=`, and the `required` / `autofocus` flags. The field reflects state changes back unless it is focused.
+- **`.skin` robustness:** `/* … */` block comments and decorative divider lines (`----`, `* * *`) are skipped instead of mis-parsed as rules.
+- Scaffold (`darkmown init`): ships a styled default nav (brand + links, hover states) and an `about.md` companion page so a fresh project looks finished and the nav links resolve.
+- Live demo: the reactive page now includes a real "search in pure Markdown" section powered by `@loop … where` + `:bind`.
+
+## 0.5.0 — 2026-06-12
+
+- **Nested `:if` over loop items.** Conditionals inside a reactive `@loop` now nest — an inner `:if` resolves after the outer branch, per row, both at build time (balanced-region pre-render) and at runtime (recursive fill). Previously the compiler threw "not supported yet"; the loop-template fill no longer relies on a non-greedy regex that broke on nesting.
+- **VS Code extension** (`editors/vscode`): syntax highlighting, snippets, and folding for `.wd` and `.skin` files. Grammars are tested through the real VS Code tokenizer (vscode-textmate) in CI.
+- New `/app/` demo — a whole live app in one `.wd` file: static build-time loop, fetched data looped with nested conditionals, a persistent counter with a computed milestone, and a form that round-trips to a real server. It is the framework's elevator pitch as a single page.
+- Site: landing page repositioned around the core wedge ("Markdown that runs" — full reactive websites in plain Markdown). `description`/Open Graph/Twitter meta tags now emit from frontmatter. Runtime-size claims corrected to the true ~2 KB; mobile nav wraps instead of overflowing.
+
 ## 0.4.0 — 2026-06-11
 
 - **Renamed**: the framework is now **Darkmown** (formerly Markie). Package `@zvndev/darkmown` (npm's typosquat guard reserves bare `darkmown` as too similar to `markdown`), CLI `darkmown`. The `.wd` format and `/__wd/` asset paths are unchanged.

package/README.md

@@ -2,7 +2,7 @@
 
 **[darkmown.com](https://darkmown.com)** · markdown, rearranged.
 
-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 under 2 KB gzipped.
+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 2 KB gzipped (CI-enforced under 5 KB).
 
 ## Quick start
 
@@ -45,7 +45,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 ~1.6 KB gzipped).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~2 KB gzipped, CI-enforced under 5 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -74,6 +74,33 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 
 Loops nest, dotted paths reach into rows, and `@include ... with x={ row.field }` reassigns values Liquid-style.
 
+### Filtering — `@loop … where`
+
+Add `where <predicate>` to filter a loop. Conditions compare a loop-item field against a number, a string, or another value, and join with `and` / `or`:
+
+```wd
+@loop /products.json into p where p.featured == true and p.price < 80
+- { p.name }
+@endloop
+```
+
+Operators: `==` `!=` `<` `<=` `>` `>=`, plus `contains` for case-insensitive substring match. The predicate is a compile-time-validated whitelist — only item paths, declared `:state`, numbers, and `"strings"` are allowed (no arbitrary expressions, no `eval`).
+
+**The source decides reactivity, just like the loop itself.** If the predicate only reads the row, the filter runs at build time and the page stays **zero-JS**. If the predicate reads a `:state` value, the loop becomes reactive and re-filters live as that state changes — a live search in pure Markdown:
+
+```wd
+:state products = [{"id":1,"name":"Aurora Lamp"},{"id":2,"name":"Briza Fan"}]
+:state q = ""
+
+:bind q placeholder="Search"
+
+@loop products into p where p.name contains q
+- { p.name }
+@endloop
+```
+
+`:bind <state>` renders an `<input>` wired two-way to a `:state` value — typing updates the state, and the state reflects back into the field. It accepts `type=` (default `text`), `placeholder=`, `autocomplete=`, and the `required` / `autofocus` flags.
+
 ## Sections
 
 ```wd
@@ -132,12 +159,16 @@ Loading…
 - `:form into name` captures submits straight into state (no backend). `:form action="/url"` emits a plain native form instead — zero JS, full progressive enhancement.
 - `:form action="/url" into reply` does both: with JS the submit posts urlencoded via fetch and the JSON reply lands in state `reply` (`reply_error` on failure); without JS it is the same native POST. Darkmown adapts to any backend — it does not own one. `darkmown dev` ships a `/__wd/echo` endpoint for demos.
 - `:state x = [] persist` keeps that state in localStorage across reloads.
-- `:if item.path` works inside reactive loops for per-row branches.
+- `:if item.path` works inside reactive loops for per-row branches, and nests — an inner `:if` resolves after the outer branch and stays reactive.
 
 ## The escape hatch
 
 Reactive pages expose `window.wd` — `wd.get(key)`, `wd.set(key, value)`, `wd.state`, `wd.render()` — so colocated `.js` can do anything the directives can't. Section-scoped keys are addressed as `sectionId:name`.
 
+## Editor support
+
+A VS Code extension in [`editors/vscode`](editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding — so a `.wd` file reads as Markdown-plus-directives, never as broken Markdown. Build it with `cd editors/vscode && npx @vscode/vsce package`, or install the published extension from the Marketplace (search "Darkmown").
+
 ## Spec status
 
 See [docs/spec-alignment.md](docs/spec-alignment.md) for the deep alignment audit against the original vision.

package/docs/spec-alignment.md

@@ -20,7 +20,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **`:fetch name from "url"`:** declarative data loading into reactive state, with `name_error` for failures. Shelf `.json` publishes to `/__wd/data/` so it works on static hosts.
 - **`:form` two ways:** `:form into name` captures submits into client state with zero backend; `:form action="/url"` emits a plain native form and ships no JS — the progressive-enhancement story from the original doc.
 - **`:state x = v persist`:** localStorage-backed state. This is the honest client-side slice of the original `:cart` primitive; server sync remains future work.
-- **`:if item.path` inside reactive loops:** per-row conditional branches, filled at compile time and re-filled by the keyed patcher.
+- **`:if item.path` inside reactive loops:** per-row conditional branches, filled at compile time and re-filled by the keyed patcher. Conditionals **nest** — an inner `:if` is resolved after the outer branch, both at build time (balanced-region pre-render) and at runtime (recursive fill).
 - **`window.wd` escape hatch:** `get`/`set`/`state`/`render` exposed to colocated `.js` — the adapted form of the original `<script scope>` "infinite extension" idea, aligned with Darkmown's colocation model instead of inline scripts.
 
 ## Deliberate adaptations
@@ -46,10 +46,19 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **`darkmown serve`:** local preview of the built `dist`, no dev client injected.
 - **Packaging:** v0.3.0, license UNLICENSED pending a licensing decision, scaffold pins the live version, npm pack contents covered by tests.
 
+## Stage 6 additions (2026-06-13)
+
+- **Nested `:if` over loop items (v0.5.0):** conditionals nest inside reactive `@loop`, per row. Both fill paths fixed — build-time balanced `matchElement` recursion and runtime `fillItem` recursion.
+- **State-driven list filtering — `@loop … where <predicate>`:** the #1 need surfaced by the agent-eval benchmark. Conditions (`field <op> value`, plus `contains`) join with `and` / `or` over a compile-time-validated whitelist — item paths, declared `:state`, numbers, strings; `constructor`/`prototype`/`__proto__` rejected, no `eval`. The source decides reactivity, matching the loop itself: an item-only predicate filters at build time and stays zero-JS; a predicate that reads `:state` compiles to a reactive filtered loop (rows baked in for static sources). This replaces the fragile DOM-toggle escape hatch with the keyed reconciler.
+- **`:bind <state>`:** two-way `<input>` bound to a `:state` value — the input primitive that powers live search. Accepts `type=`, `placeholder=`, `autocomplete=`, `required`, `autofocus`.
+- **`.skin` robustness:** `@media`/`@supports` at-rules wrap nested rules; the `font` shorthand passes through (size-led or containing `/`) while `font <stack>` still aliases to `font-family`; `/* … */` block comments and decorative divider lines are skipped.
+- **Editor tooling:** VS Code extension (`editors/vscode`) ships `.wd` + `.skin` TextMate grammars, snippets, and folding, grammar-tested in CI.
+- **`AGENTS.md`:** a model-facing build guide (shipped in the npm files array), tuned over a 5-round agent-eval benchmark that lifted build quality from 2.78→4.51/5.
+
 ## Still missing from the full vision
 
 - First-party server runtime (`site/api/`), HTML-fragment `swap` semantics, and cart server sync — parked behind the adapter decision until a real project needs them.
-- Nested `:if` over loop items, and `@loop` over fetch sub-paths.
+- `@loop` over fetch sub-paths (looping a path *inside* fetched state rather than top-level state).
 - `@starting-style` emission and browser fallbacks for older engines.
 - Editor tooling, richer diagnostics, and an actual npm publish (needs a license decision).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -13,12 +13,13 @@
   "scripts": {
     "build": "node src/cli.js build",
     "dev": "node src/cli.js dev",
-    "test": "node --test"
+    "test": "node --test tests/*.test.js"
   },
   "files": [
     "src",
     "site",
     "docs",
+    "AGENTS.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/site/_/nav.skin

@@ -11,7 +11,8 @@ tokens
 
 .topnav
   display flex
-  gap 1rem
+  flex-wrap wrap
+  gap .5rem 1rem
   align-items center
   padding 1rem 2rem
   border-bottom 1px solid $line

package/site/_/nav.wd

@@ -5,4 +5,5 @@
   <a href="/markdown/">Plain Markdown</a>
   <a href="/reactive/">Reactive</a>
   <a href="/data/">Data &amp; Forms</a>
+  <a href="/app/">Live app</a>
 </nav>

package/site/_/roadmap.json

@@ -0,0 +1,7 @@
+[
+  { "id": "loops", "title": "Nested conditionals in loops", "shipped": true, "blocked": false },
+  { "id": "editor", "title": "VS Code syntax highlighting", "shipped": true, "blocked": false },
+  { "id": "filter", "title": "State-driven list filtering", "shipped": false, "blocked": false },
+  { "id": "api", "title": "First-party site/api/ runtime", "shipped": false, "blocked": true },
+  { "id": "swap", "title": "HTML-fragment swap responses", "shipped": false, "blocked": false }
+]

package/site/pages/app.skin

@@ -0,0 +1,76 @@
+tokens
+  ink #171717
+  paper #fbfaf7
+  panel #ffffff
+  line #e4e1d8
+  accent #16645a
+  warm #a83f2a
+  radius 10px
+
+main
+  max-width 760px
+  margin 0 auto
+  padding 2.5rem 1.5rem 4rem
+  font ui-sans-serif, system-ui, sans-serif
+  color $ink
+
+h1
+  font-size 2.1rem
+  letter-spacing -0.02em
+
+.boundary
+  margin 1.5rem 0
+  padding 1rem 1.2rem
+  border-left 3px solid $warm
+  background #fcf4ef
+  border-radius $radius
+  font-size .95rem
+
+.roadmap-row
+  display flex
+  align-items center
+  justify-content space-between
+  gap 1rem
+  padding .75rem 1rem
+  margin .5rem 0
+  background $panel
+  border 1px solid $line
+  border-radius $radius
+
+.badge
+  font-size .8rem
+  font-weight 600
+  padding .2rem .6rem
+  border-radius 999px
+  white-space nowrap
+
+.badge.shipped
+  background #e3f3ec
+  color $accent
+
+.badge.wip
+  background #fef0e6
+  color $warm
+
+.badge.blocked
+  background #f3e3e3
+  color #9a2a2a
+
+button
+  background $accent
+  color white
+  border 0
+  padding .55rem .9rem
+  margin .25rem .4rem .25rem 0
+  border-radius 8px
+  font-size .95rem
+  cursor pointer
+
+input
+  font-size 1rem
+  padding .6rem .7rem
+  border 1px solid $line
+  border-radius 8px
+  width 100%
+  max-width 22rem
+  margin .3rem 0

package/site/pages/app.wd

@@ -0,0 +1,92 @@
+---
+title: A live app in one Markdown file
+description: One .wd file — static prose, fetched data, looped results with nested conditionals, a persistent counter, and a form that round-trips to a real server. No JavaScript written, no components, no build config.
+---
+
+@include /nav.wd
+
+<main>
+
+# A live app, in one Markdown file
+
+Everything on this page — the prose, the fetched list, the badges, the form, the counter — is a single `.wd` file. No components. No JSX. No build config. Watch where JavaScript actually enters.
+
+## Static until proven reactive
+
+This whole section is plain Markdown. The list below is unrolled **at build time** from a JSON file — it renders into HTML with no runtime at all:
+
+@loop /features.json into feature
+- **{ feature.name }** — { feature.detail }
+@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 ~2&nbsp;KB runtime loads — and only because the document asks for it.</aside>
+
+## Fetched data, looped, with nested conditions
+
+`:fetch` pulls JSON over the network into reactive state — from a static file here, or any API. Until it lands, the page shows a fallback. Each row then decides its own badge from **nested** conditionals, in plain Markdown:
+
+:fetch roadmap from "/__wd/data/roadmap.json"
+
+:if roadmap
+@loop roadmap into item
+::: card .roadmap-row
+**{ item.title }**
+:if item.blocked
+<span class="badge blocked">blocked</span>
+:else
+:if item.shipped
+<span class="badge shipped">shipped ✓</span>
+:else
+<span class="badge wip">in progress</span>
+:endif
+:endif
+:::
+@endloop
+:else
+Loading the roadmap…
+:endif
+
+No ternaries, no `.map()`, no framework — the outer `:if` checks `blocked`, the inner one checks `shipped`, per row, and both stay reactive.
+
+## A counter that survives reload
+
+`:state … persist` keeps this in `localStorage`, and `:computed` derives from it. Star a few, reload the page, and it holds:
+
+::: section #watch
+:state stars = 0 persist
+:computed milestone = stars >= 3
+
+You are watching { stars } item(s).
+
+:button "★ Watch one" -> stars++
+:button "Reset" -> stars = 0
+
+:if milestone
+Nice — you are tracking the whole near-term roadmap.
+:endif
+:::
+
+## A form that talks to a real server
+
+This form posts to a live serverless function and shows the reply. With JavaScript it is a `fetch`; without it, the exact same markup is a native POST — Darkmown adapts to your backend instead of owning one:
+
+:form action="/__wd/echo" into reply
+:input note placeholder="Tell us what you'd build with this"
+:submit "Send to the server"
+:endform
+
+:if reply
+The server got it and answered at **{ reply.at }**.
+:else
+Your reply will appear here.
+:endif
+
+:if reply_error
+Something went wrong: { reply_error }
+:endif
+
+---
+
+That was one file. Static prose, build-time loops, fetched data, nested conditionals, persistent state, computed values, and a server round-trip — and the only JavaScript on the page is the shared runtime Darkmown loads for you. [Read the docs](/docs/) or [deploy your own](/#deploy).
+
+</main>