@zvndev/darkmown 0.8.1 → 0.9.0

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 ~2 KB runtime only if it declares reactive behavior.
+- Static pages ship **zero** JavaScript; a page loads the ~3.2 KB runtime only if it declares reactive behavior.
 
 ## Project layout & routing
 

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.9.0 — 2026-06-15
+
+The "proof + full test pyramid" release: prove the moat on the homepage, test everything from unit to browser e2e, and pass a gold-standard open-source audit.
+
+- **Landing: the vs-Markdoc proof.** The homepage is now a side-by-side comparison — the real `.wd` source for a live search-filter + add-to-cart store rendered working on the page, next to the equivalent Markdoc (which has no native loop and needs a React component + hydration for interactivity). The homepage is now itself a reactive `.wd` app; `/markdown/` and `/docs/` stay static (zero JS) to prove the static path.
+- **Full test pyramid.** Unit + integration backfill (grammar whitelists, skin compiler, interpolation, router, every compile-error path), a zero-dependency CLI/pipeline e2e (`darkmown init` → build → serve → fetch → assert), real-browser e2e via Playwright (`npm run test:e2e`), and a seeded property/fuzz suite (5,000 cases/run) for the parser and expression validators. The zero-dep `npm test` suite grew from 98 to ~200 checks; coverage is ~96% lines, gated at 80% in CI.
+- **The fuzzer earned its keep:** it found two real bugs, now fixed — two `:button` action errors that omitted the file path, and bare object interpolation (`{ meta }`) emitting `[object Object]` instead of an actionable error. Arrays now join with `, ` consistently.
+- **Type safety.** Source stays plain JavaScript but is fully type-checked via JSDoc + `checkJs` (`npm run typecheck`, gated in CI), and ships `.d.ts` declarations. `typescript` is a dev-only dependency; the runtime stays zero-dependency.
+- **Lean shipped runtime.** JSDoc is stripped from the runtime on emit, so the browser still downloads ~3.2 KB gzipped even though the source carries full type annotations. The size budget now measures the shipped artifact.
+- **Gold-standard hardening (46.5/50 audit).** Release pack-smoke test before publish, `prepublishOnly` guard, `dependabot` (npm + GitHub Actions), CI `concurrency` cancellation, `.github/` PR + issue templates, `CODEOWNERS`, a short `CODE_OF_CONDUCT.md`, an exposed/documented `window.wd.debug`, and repo-root tidy-up.
+
+## 0.8.2 — 2026-06-14
+
+Honesty, hardening, and polish pass — every claim in the docs is now backed by shipped code.
+
+- **Security:** new per-page `html: false` frontmatter opt-out routes that page's Markdown through a strict renderer that escapes raw HTML — the mitigation for compiling untrusted/user-submitted content (default stays `html: true` for trusted authors). README and SECURITY.md now warn prominently that untrusted Markdown must be sanitized. `escapeHtml` also escapes single quotes.
+- **Runtime:** state changes now batch into a single render per tick (`requestAnimationFrame`, falling back to a microtask), so rapid `:bind` input no longer re-runs the reconciler on every keystroke; the final state always renders and the public `wd.render()` stays synchronous. Opt-in `window.wd.debug` surfaces warnings for failed `:computed` / `where` expressions that were previously silent.
+- **Tests:** first runtime/DOM test suite — keyed loop reconcile (node reuse on add/remove/reorder), `getPath` prototype-pollution rejection, loop-key collisions, and render batching — loading the real runtime via `node:vm`, no new dependencies. Suite grew 83 → 98.
+- **Compiler:** unterminated frontmatter now throws an actionable error with the file path instead of silently swallowing the page; empty `---`/`---` blocks parse cleanly.
+- **Docs & claims:** view transitions are now correctly described as parked/disabled (they were advertised but hardcoded off); the "no eval" wording is corrected (`:computed` and `where` compile to a whitelisted grammar run via `new Function`, never raw user content); runtime size corrected to the true ~3.1 KB gzipped across all surfaces; `:note`/`:try`/`:sprint` documented as demo-only; `docs/cli.md` scaffold output synced; VS Code install instructions corrected (build from source; Marketplace listing pending).
+- **Site & tooling:** landing-page whitespace fixed (removed the forced `60vh` hero band); mobile nav no longer overflows; tagline locked to "Markdown that runs."; regenerated `package-lock.json` identity (`@zvndev/darkmown`).
+
 ## 0.8.1 — 2026-06-14
 
 - Fix: a quoted array item that follows `, ` no longer keeps a leading space — `tags: [a, "b, c"]` parses to `["a", "b, c"]`, not `["a", " b, c"]`.
@@ -33,7 +55,7 @@ All notable changes to Darkmown are documented here. Versions follow [semver](ht
 - **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.
+- 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.
 
 ## 0.4.0 — 2026-06-11
 
@@ -57,7 +79,7 @@ All notable changes to Darkmown are documented here. Versions follow [semver](ht
 - `:if item.path` inside reactive loops (per-row branches).
 - `window.wd` escape hatch for colocated `.js`.
 - `::: section` containers with scoped state; keyed loop reconciliation.
-- View transitions via `transitions: true` frontmatter.
+- View transitions via `transitions: true` frontmatter. **(Disabled since: cross-document `@view-transition` render-blocked deployed pages, hanging navigation. `transitions` is currently hardcoded off in `src/compiler.js`; reintroduction is tracked pending proper activation fallbacks.)**
 - Real CommonMark parsing (markdown-it); strict `.md` (directives stay plain text).
 - `@loop … into … @endloop` — the one loop, replacing `@repeat` and `:for`.
 - Dev server rebuilds in a child process (always-fresh modules).

package/README.md

@@ -1,8 +1,8 @@
 # Darkmown
 
-**[darkmown.com](https://darkmown.com)** · markdown, rearranged.
+**[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 2 KB gzipped (CI-enforced under 5 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 ~3.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 ~2 KB gzipped, CI-enforced under 5 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~3.2 KB gzipped, CI-enforced under 5 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -100,7 +100,7 @@ Add `where <predicate>` to filter a loop. Conditions compare a loop-item field a
 @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`).
+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). Raw user content is never evaluated; the validated predicate compiles to a whitelisted grammar that runs via `new Function`.
 
 **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:
 
@@ -209,9 +209,19 @@ Loading…
 
 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`.
 
+Set `window.wd.debug = true` (it defaults to `false`) to log any `:computed` or `@loop … where` expression that fails to evaluate to the console — useful while authoring reactive pages.
+
 ## 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").
+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. Install it from source by building a `.vsix`: `cd editors/vscode && npx @vscode/vsce package`, then `code --install-extension darkmown-*.vsix`. A Marketplace listing is coming soon.
+
+## Security
+
+Darkmown renders Markdown with `html: true`, so **raw HTML in your content passes through verbatim** — by design, like every Markdown site generator. Treat content files as trusted input.
+
+> **The single biggest footgun:** do not compile untrusted or user-submitted Markdown without sanitizing it first. There is no built-in sanitizer.
+
+Directive actions and `:computed`/`@loop … where` expressions are never `eval`'d as raw user content — they compile to a whitelisted grammar (item paths, declared `:state`, numbers, strings) that runs via `new Function`. See [SECURITY.md](SECURITY.md) for the full security model.
 
 ## Spec status
 

package/docs/cli.md

@@ -16,8 +16,10 @@ darkmown help
 
 Creates a minimal Darkmown site with:
 
+- `package.json` (pins the current `@zvndev/darkmown` version)
 - `site/pages/index.wd`
 - `site/pages/index.skin`
+- `site/pages/about.md`
 - `site/_/nav.wd`
 - `README.md`
 

package/docs/spec-alignment.md

@@ -6,7 +6,7 @@ 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` (~1.1 KB gzipped, below the original 5 KB target).
+- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~3.2 KB gzipped, CI-enforced below the 5 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.
@@ -33,7 +33,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 
 ## Stage 4 additions (2026-06-11, same day)
 
-- **View transitions:** `transitions: true` in frontmatter emits `@view-transition { navigation: auto; }` — the original doc's zero-JS MPA navigation polish.
+- **View transitions (currently disabled):** `transitions: true` in frontmatter was wired to emit `@view-transition { navigation: auto; }` — the original doc's zero-JS MPA navigation polish. **This is turned off as of now:** cross-document `@view-transition` render-blocked deployed pages (stalled rAF, hanging navigation), so `transitions` is hardcoded to `""` in `src/compiler.js`. The frontmatter key is accepted but has no effect today. Reintroduction is tracked pending proper activation fallbacks (see "Still missing from the full vision").
 - **Lazy loading:** `:fetch … when=visible` defers the request until the marker scrolls into view (IntersectionObserver) — the adapted form of `:lazy`.
 - **Computed state:** `:computed name = expr` with a compile-time-validated grammar (state refs, numbers, strings, arithmetic, comparisons; assignment, calls, and prototype walks rejected). Initial values are evaluated at build time.
 - **Dev self-reload:** `darkmown dev` rebuilds in a child process, so changes to the framework's own `src/` always compile with fresh modules.
@@ -49,7 +49,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 ## 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.
+- **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. Raw user content is never evaluated; the validated predicate compiles to the whitelisted grammar and runs via `new Function` at runtime. 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`.
 - **Per-row actions in reactive loops:** a `:button` inside `@loop … into item` can act on its own row — `cart += item` appends a copy of the row to another `:state` list (the only way to carry a loop item into another list), and `list remove item` removes the row from the looped `:state` source (both names compile-checked against the enclosing loop). The runtime resolves the clicked row by stamping each reconciled node with its item, so removal is exact even under a `where` filter. This closes the last "store demo" gap noted in the design memory (per-row `:button` couldn't carry row data); `:if` string-equality remains the only listed gap, now partly covered by `@loop … where`.
 - **`.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.
@@ -60,11 +60,15 @@ This audit compares the current Darkmown implementation with the original MARROW
 
 - **Array frontmatter + readable `meta`:** `parseFrontmatter` now parses inline flow arrays (`tags: [a, b, "x, y"]` → real array; quoted items keep internal commas; a value without a leading `[` stays a scalar — block sequences are intentionally out of scope to keep the parser single-pass). A page's frontmatter is exposed to its body under `meta`, so `{ meta.title }` prints a field, `{ meta.tags }` renders an array joined with `, `, and `@loop meta.tags into tag` iterates a frontmatter array at build time (stays `runtime: false`). Genuine correctness fix on its own, and the groundwork for reading/emitting OKF-style bundles (Google Cloud's Open Knowledge Format — markdown + `type`-bearing frontmatter + cross-links; tracked but deliberately not coupled to its v0.1 Draft).
 
+## Demo-only directives (not part of the public surface)
+
+The compiler recognizes three directives — `:note`, `:try`, and `:sprint` — that exist **only to power the demo site** (darkmown.com). They are **not** part of the supported public directive set, are not documented for authors, and may change or be removed without notice. Do not build pages that depend on them. The supported public directives are the ones catalogued above: `:state`, `:computed`, `:button`, `:bind`, `:if`/`:else`/`:endif`, `:fetch`, `:form`/`:input`/`:submit`, `@loop`/`@endloop` (with `where`), `@include`, and `::: section`.
+
 ## 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.
 - `@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.
+- **View transitions:** re-enabling `transitions: true` with proper activation fallbacks (disabled today — see Stage 4), plus `@starting-style` emission and browser fallbacks for older engines.
 - Editor tooling, richer diagnostics, and an actual npm publish (needs a license decision).
 
 ## Current claim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -10,15 +10,23 @@
   "bin": {
     "darkmown": "./src/cli.js"
   },
+  "types": "./types/index.d.ts",
   "scripts": {
     "build": "node src/cli.js build",
     "dev": "node src/cli.js dev",
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "test:cov": "node --test --experimental-test-coverage tests/*.test.js",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm test"
   },
   "files": [
     "src",
+    "types",
     "site",
-    "docs",
+    "docs/cli.md",
+    "docs/spec-alignment.md",
     "AGENTS.md",
     "README.md",
     "LICENSE",
@@ -30,6 +38,12 @@
   "dependencies": {
     "markdown-it": "^14.2.0"
   },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.19.21",
+    "typescript": "^5.9.3"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ZVN-DEV/darkmown.git"

package/site/_/nav.skin

@@ -15,6 +15,8 @@ tokens
   gap .5rem 1rem
   align-items center
   padding 1rem 2rem
+  max-width 100%
+  box-sizing border-box
   border-bottom 1px solid $line
   bg rgba(251,250,247,.85)
   backdrop-filter blur(8px)
@@ -22,6 +24,11 @@ tokens
   top 0
   z-index 10
 
+@media (max-width: 600px)
+  .topnav
+    padding .85rem 1rem
+    gap .4rem .85rem
+
 .topnav strong
   color $warm
   font-size 1.05rem

package/site/pages/docs/index.wd

@@ -131,7 +131,7 @@ tags: [sales, revenue, "q1, q2"]
 
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~2 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~3.2 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
 
 ```wd
 :state count = 0

package/site/pages/index.skin

@@ -18,16 +18,17 @@ page
   padding 0 0 4rem
 
 .hero
-  min-height 60vh
   display flex
   flex-direction column
   align-items flex-start
   justify-content center
+  padding 2.5rem 0 2.25rem
   border-bottom 1px solid $line
-  margin-bottom 2rem
+  margin-bottom 2.5rem
 
 .hero > p:not(.eyebrow)
   max-width 70ch
+  margin .75rem 0 1.5rem
 
 .eyebrow
   color $accent
@@ -39,16 +40,16 @@ page
 main
   max-width 920px
   margin 0 auto
-  padding 1rem 2rem 2rem
+  padding 0 2rem 2rem
 
 h1
   font-size clamp(2.4rem, 6vw, 5rem)
   line-height .95
-  margin 2rem 0 1rem
-  max-width 10ch
+  margin .75rem 0 1rem
+  max-width 14ch
 
 h2
-  margin-top 2rem
+  margin-top 2.75rem
   border-bottom 1px solid $line
   padding-bottom .35rem
 
@@ -132,3 +133,161 @@ a
   display block
   color $accent
   font-size .9rem
+
+/* ── vs-Markdoc comparison ───────────────────────────────────────── */
+
+.versus
+  display grid
+  grid-template-columns 1fr 1fr
+  gap 1.25rem
+  align-items start
+  margin 2.5rem 0 1rem
+
+.vs-card
+  border 1px solid $line
+  radius $radius
+  bg $panel
+  padding 1.25rem 1.25rem 1.1rem
+  display flex
+  flex-direction column
+  min-width 0
+
+.vs-card.vs-dark
+  bg #fbf7ef
+  border 1px solid #e3d8c4
+  box-shadow 0 1px 0 #efe7d6
+
+.vs-head
+  display flex
+  align-items baseline
+  justify-content space-between
+  gap .75rem
+  margin-bottom .85rem
+
+.vs-tag
+  font-family ui-monospace, SFMono-Regular, Menlo, monospace
+  font-size .72rem
+  font-weight 700
+  text-transform uppercase
+  letter-spacing .08em
+  padding .25rem .55rem
+  radius 999px
+
+.vs-tag-wd
+  color white
+  bg $accent
+
+.vs-tag-md
+  color $muted
+  bg #efece3
+  border 1px solid $line
+
+.vs-sub
+  font-family ui-monospace, SFMono-Regular, Menlo, monospace
+  font-size .82rem
+  color $muted
+
+.vs-card pre
+  margin .25rem 0 0
+  font-size .82rem
+  line-height 1.55
+
+.vs-live-label
+  margin 1rem 0 .35rem
+  font-size .88rem
+  color $muted
+  font-style italic
+
+.vs-live
+  border 1px dashed #cdbfa6
+  radius $radius
+  bg #fffdf8
+  padding 1rem 1.1rem .85rem
+  margin .15rem 0 0
+
+.vs-live input[data-wd-bind-input]
+  width 100%
+  box-sizing border-box
+  font inherit
+  font-size .95rem
+  padding .55rem .7rem
+  border 1px solid $line
+  radius 6px
+  bg white
+  margin 0 0 .75rem
+
+.vs-live .product
+  display flex
+  align-items center
+  justify-content space-between
+  gap .75rem
+  padding .5rem .7rem
+  margin .35rem 0
+  bg $panel
+  border 1px solid $line
+  radius 6px
+  font-size .95rem
+
+.vs-live .product p
+  margin 0
+
+.vs-live .product button
+  border 0
+  bg $accent
+  color white
+  font inherit
+  font-size .82rem
+  padding .35rem .7rem
+  radius 6px
+  cursor pointer
+  flex-shrink 0
+
+.vs-live .product button:hover
+  bg #11514a
+
+.vs-live > p:last-of-type
+  margin .85rem 0 0
+  font-size .95rem
+
+.vs-needs
+  margin 1rem 0 0
+  padding 1rem 1.1rem
+  border-left 3px solid $warm
+  bg #fcf4ef
+  radius 6px
+
+.vs-needs strong
+  color $warm
+  font-size .92rem
+
+.vs-needs pre
+  margin .7rem 0 .6rem
+  font-size .78rem
+
+.vs-needs-foot
+  display block
+  font-size .85rem
+  color $muted
+
+.vs-caption
+  margin auto 0 0
+  padding-top 1rem
+  font-style italic
+  color $ink
+  font-size .95rem
+
+.vs-card.vs-dark .vs-caption
+  color $accent
+
+/* Secondary value-prop row, demoted below the comparison */
+
+.props
+  margin 1.5rem 0 0
+
+.props h2
+  margin-top 1.5rem
+
+@media (max-width: 720px)
+  .versus
+    grid-template-columns 1fr
+    gap 1rem

package/site/pages/index.wd

@@ -1,6 +1,6 @@
 ---
-title: Darkmown — Markdown that runs
-description: Build full websites in plain Markdown. Routing, state, server calls, includes, and reactive islands — no JavaScript or CSS required. Your docs and your code are all just text.
+title: Darkmown — Markdown that runs, not Markdown that needs React
+description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
 ---
 
 @include /nav.wd
@@ -8,17 +8,105 @@ description: Build full websites in plain Markdown. Routing, state, server calls
 <main>
 
 <section class="hero">
-  <p class="eyebrow">The Markdown framework</p>
+  <p class="eyebrow">Darkmown vs. Markdoc</p>
 
-# Markdown that runs
+# Markdown that runs. Not Markdown that needs React.
 
-Not just pages — **full websites**. Routing, state, server calls, embeds, and reactive islands, all from plain Markdown files. No JavaScript or CSS required. Your docs and your code are all just text.
+The left file is Markdown. It is also a running app — a live search filter, add-to-cart, and a running total. The right file is the closest Markdoc can get on its own: a static list. To make it do what the left one already does, you add a React component, hydration, and a build step.
 
 <a class="btn primary" href="/app/">See a whole app in one file</a>
 <a class="btn" href="/docs/">Read the docs</a>
 </section>
 
-:note "Static pages ship zero JavaScript. The moment a page asks for reactivity, one ~2 KB runtime loads — never before. JS optional, CSS optional, always."
+<section class="versus">
+
+::: div .vs-card .vs-dark
+<header class="vs-head"><span class="vs-tag vs-tag-wd">Darkmown</span><span class="vs-sub">store.wd</span></header>
+
+```wd
+:state products = [{"id":1,"name":"Aurora Lamp","price":49},{"id":2,"name":"Briza Fan","price":39},{"id":3,"name":"Cove Speaker","price":89},{"id":4,"name":"Dune Mug","price":12}]
+:state cart = []
+:state q = ""
+:computed count = cart.length
+
+:bind q placeholder="Search products…"
+
+@loop products into p where p.name contains q
+::: card .product
+**{ p.name }** — ${ p.price }
+:button "Add" -> cart += p
+:::
+@endloop
+
+Cart: { count } item(s)
+```
+
+<p class="vs-live-label">↓ and here is that exact file, running</p>
+
+::: div .vs-live
+:state products = [{"id":1,"name":"Aurora Lamp","price":49},{"id":2,"name":"Briza Fan","price":39},{"id":3,"name":"Cove Speaker","price":89},{"id":4,"name":"Dune Mug","price":12}]
+:state cart = []
+:state q = ""
+:computed count = cart.length
+
+:bind q placeholder="Search products…"
+
+@loop products into p where p.name contains q
+::: card .product
+**{ p.name }** — ${ p.price }
+:button "Add" -> cart += p
+:::
+@endloop
+
+Cart: **{ count }** item(s)
+:::
+
+<p class="vs-caption">This is the whole file. It runs.</p>
+:::
+
+::: div .vs-card
+<header class="vs-head"><span class="vs-tag vs-tag-md">Markdoc</span><span class="vs-sub">store.md</span></header>
+
+```text
+{% if $products %}
+- **Aurora Lamp** — $49
+- **Briza Fan** — $39
+- **Cove Speaker** — $89
+- **Dune Mug** — $12
+{% /if %}
+```
+
+<p class="vs-live-label">Markdoc has <code>{% if %}</code>, <code>{% partial %}</code>, and <code>$variables</code> — but no loop tag, so each row is written by hand and the list is static. To filter, add to a cart, or total it, you reach for code:</p>
+
+::: div .vs-needs
+<strong>+ store-widget.jsx</strong> — a React component, registered as a custom tag:
+
+```jsx
+const tags = { store: { render: 'Store' } };
+Markdoc.renderers.react(content, React, {
+  components: { Store } // your filter + cart + total live here
+});
+```
+
+<span class="vs-needs-foot">…plus a React + hydration runtime shipped to the browser, and the build step that wires the tag to the component.</span>
+:::
+
+<p class="vs-caption">Same outcome needs a React component.</p>
+:::
+
+</section>
+
+:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~3.2 KB runtime loads, 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 ~3.2 KB runtime. 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>
 
 ## A whole framework, in text
 
@@ -78,3 +166,4 @@ Darkmown itself was built by a small agent team. The board below is a live `@loo
 @include /sprint-loop.wd
 
 </main>
+</content>