@zvndev/darkmown 0.8.2 → 0.10.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 ~3.1 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,27 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.10.0 — 2026-06-15
+
+Launch-readiness: every public claim is now backed by runnable evidence instead of stale copy.
+
+- **Provable docs.** README, `docs/cli.md`, `docs/spec-alignment.md`, and the gold-standard audit are re-synced to the shipped code — loop semantics, the build-time vs reactive split, and per-row `:button` actions (`cart += product` carries the row into another list; `cart remove line` drops it) are documented exactly as they compile. A docs-snippet test compiles the README/docs examples so the copy can't drift from the code again.
+- **Consumer smoke script.** `npm run smoke` packs the tarball, installs it into a throwaway project, scaffolds, and builds it the way a real consumer would — the same supply-chain check the release workflow runs, now available locally.
+- **CLI + scaffold polish.** `darkmown version` prints the installed package version; first-run scaffold output and CLI guidance now match the docs.
+- **Editor + packaging scripts.** `npm run test:extension` and `npm run pack:extension` build and tokenize-test the VS Code grammar from the repo root; the extension ships its own `LICENSE` and a corrected README.
+- **`homepage` now points at https://darkmown.com.**
+
+## 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.

package/README.md

@@ -2,7 +2,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 ~3.1 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
 
@@ -27,7 +27,8 @@ The package is `@zvndev/darkmown`; the command it installs is plain `darkmown`.
 ```sh
 npm install
 npm test
-npm run dev    # live demo site — the same site that runs darkmown.com
+npm run smoke   # pack, install, scaffold, and build a temporary consumer app
+npm run dev     # live demo site — the same site that runs darkmown.com
 ```
 
 ## Commands
@@ -36,6 +37,7 @@ npm run dev    # live demo site — the same site that runs darkmown.com
 - `darkmown dev` starts the live compiler with browser reload and an in-browser error overlay when a build fails.
 - `darkmown build` writes static output to `dist`.
 - `darkmown serve` previews the built `dist` locally.
+- `darkmown version` prints the installed package version.
 - `darkmown help` prints CLI usage.
 
 ## Authoring model
@@ -45,7 +47,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 ~3.1 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
@@ -76,14 +78,16 @@ tags: [sales, revenue, "q1, q2"]
 
 `@loop <things> into <thing>` is the only loop. The source decides the behavior:
 
+A JSON-file loop is unrolled at build time; includes inside inherit the loop value. A `:state` list loop is reactive and patched by key.
+
 ```wd
-@loop /features.json into card     <- JSON file: unrolled at build time
-@include /feature-card.wd          <- includes inherit the loop value
+@loop /features.json into card
+@include /feature-card.wd
 @endloop
 
 :state todos = [{"id": 1, "title": "Route pages"}]
 
-@loop todos into todo              <- :state list: reactive, patched by key
+@loop todos into todo
 - { todo.title }
 @endloop
 ```
@@ -119,7 +123,7 @@ Operators: `==` `!=` `<` `<=` `>` `>=`, plus `contains` for case-insensitive sub
 
 ### Editable lists — per-row actions
 
-A `:button` inside a reactive `@loop` can act on its own row. Two row actions exist:
+A `:button` inside a reactive `@loop` can act on its own row. `cart += product` carries the current row into another list; `cart remove line` drops the current row from the looped list:
 
 ```wd
 :state products = [{"id": 1, "name": "Aurora", "price": 49}]
@@ -128,14 +132,14 @@ A `:button` inside a reactive `@loop` can act on its own row. Two row actions ex
 @loop products into product
 ::: card
 **{ product.name }** — ${ product.price }
-:button "Add to cart" -> cart += product    <- carry this row into another list
+:button "Add to cart" -> cart += product
 :::
 @endloop
 
 @loop cart into line
 ::: card
 { line.name }
-:button "Remove" -> cart remove line          <- drop this row from the looped list
+:button "Remove" -> cart remove line
 :::
 @endloop
 ```
@@ -209,9 +213,11 @@ 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. 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.
+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. For launch, it is source-installable: build a `.vsix` with `npm run pack:extension`, then install `editors/vscode/darkmown-*.vsix` with VS Code. Marketplace/Open VSX publishing is tracked as post-launch distribution work, so the public package does not imply store availability yet.
 
 ## Security
 

package/docs/cli.md

@@ -12,6 +12,14 @@ darkmown help
 
 ## Commands
 
+### `darkmown help` / `darkmown --help`
+
+Prints the command summary, authoring directories, and common directive syntax.
+
+### `darkmown version` / `darkmown --version`
+
+Prints the installed package version.
+
 ### `darkmown init [dir]`
 
 Creates a minimal Darkmown site with:
@@ -23,7 +31,7 @@ Creates a minimal Darkmown site with:
 - `site/_/nav.wd`
 - `README.md`
 
-Existing files are not overwritten.
+Existing files are not overwritten. The scaffolded `package.json` is private by default, includes `dev`, `build`, and `preview` scripts, and names the app after the target directory.
 
 After scaffolding:
 
@@ -50,4 +58,18 @@ Compiles `site/pages` into `dist`.
 
 Static pages do not receive `/__wd/runtime.js`; reactive pages do.
 
-When a `.md` file contains `.wd` syntax (directives, includes, loops), the build prints a hint suggesting a rename to `.wd` — the syntax stays plain text in `.md` by design.
+When a `.md` file contains `.wd` syntax (directives, includes, loops), the build prints a hint suggesting a rename to `.wd` — the syntax stays plain text in `.md` by design.
+
+### `darkmown serve`
+
+Serves the already-built `dist` directory for local preview. Run `darkmown build` first.
+
+## Smoke checks
+
+From this repository, run:
+
+```sh
+npm run smoke
+```
+
+The smoke script packs the local tarball, installs the packed CLI in a temporary driver project, scaffolds a consumer app through that installed bin, installs the same tarball into the app, builds it, verifies the reactive home route, and verifies the plain `.md` about route stays zero-JS.

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` (~3.1 KB gzipped, CI-enforced below the 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.
@@ -44,7 +44,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **Adapter-style Tier 2 (decided):** Darkmown does not own a server. `:form action="/url" into reply` posts urlencoded via fetch and lands the JSON reply in state, degrading to a plain native POST without JS. Sessions ride on `:fetch` plus ordinary cookies against any backend. A first-party `site/api/` runtime stays open as a future option if a real project demands it.
 - **Dev error overlay:** failed rebuilds render the compiler error in the browser; the overlay clears on the next good build.
 - **`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.
+- **Packaging:** v0.3.0 introduced package metadata and pack tests; the current public package is MIT licensed and scaffolded projects pin the live Darkmown version.
 
 ## Stage 6 additions (2026-06-13)
 
@@ -69,10 +69,10 @@ The compiler recognizes three directives — `:note`, `:try`, and `:sprint` —
 - 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).
 - **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).
+- Richer diagnostics and package-consumer QA in regular CI. Editor tooling exists as a source-installable VS Code extension; public Marketplace/Open VSX distribution remains a launch/distribution follow-up.
 
 ## Current claim
 
 Darkmown is faithful to the core thesis: Markdown remains the authoring center, static pages ship zero framework JavaScript, and reactive behavior compiles into tiny direct-DOM islands only where declared. The extension is the feature gate, the loop is one concept with progressive disclosure, and state scopes to document structure.
 
-It is not yet the full production framework described in the original document.
+The public npm package is published as `@zvndev/darkmown`, the project is MIT licensed, and the remaining gaps are explicitly scoped as post-launch product/distribution work rather than missing v0.9 claims.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.8.2",
+  "version": "0.10.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -10,15 +10,26 @@
   "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",
+    "test:extension": "npm --prefix editors/vscode ci && npm --prefix editors/vscode test",
+    "pack:extension": "cd editors/vscode && npx --yes @vscode/vsce package",
+    "typecheck": "tsc --noEmit",
+    "types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm test",
+    "smoke": "node scripts/smoke-consumer.mjs"
   },
   "files": [
     "src",
+    "types",
     "site",
-    "docs",
+    "docs/cli.md",
+    "docs/spec-alignment.md",
     "AGENTS.md",
     "README.md",
     "LICENSE",
@@ -30,11 +41,17 @@
   "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"
   },
-  "homepage": "https://github.com/ZVN-DEV/darkmown#readme",
+  "homepage": "https://darkmown.com",
   "bugs": {
     "url": "https://github.com/ZVN-DEV/darkmown/issues"
   },

package/site/_/roadmap.json

@@ -1,7 +1,7 @@
 [
-  { "id": "loops", "title": "Nested conditionals in loops", "shipped": true, "blocked": false },
+  { "id": "loops", "title": "Nested `:if` inside loop rows", "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": "filter", "title": "Reactive `@loop where` filtering", "shipped": true, "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/docs/index.wd

@@ -131,7 +131,7 @@ tags: [sales, revenue, "q1, q2"]
 
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~3.1 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
@@ -176,6 +176,6 @@ See it all live on the [Data & Forms page](/data/).
 
 ## 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. `:fetch`, `:form` (including server round-trips), `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/). Still on the roadmap: a first-party server runtime (`site/api/`), HTML-fragment swaps, and nested `:if` over loop items. See `docs/spec-alignment.md` in the package for the full audit.
+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. `:fetch`, `:form` (including server round-trips), `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/). Still on the roadmap: a first-party server runtime (`site/api/`), HTML-fragment swaps, and `@loop` over fetched sub-paths. See `docs/spec-alignment.md` in the package for the full audit.
 
 </main>

package/site/pages/index.skin

@@ -133,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 ~3.1 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