@zvndev/darkmown 0.5.0 → 0.7.0

package/AGENTS.md

@@ -0,0 +1,307 @@
+# 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`. Literal values are JSON. **`:button` is for state actions only** — for a link styled as a button, write raw HTML `<a class="btn" href="…">`.
+
+**Per-row actions (inside a reactive `@loop … into item`):** two actions reference the current row instead of a JSON literal —
+```wd
+@loop products into product
+:button "Add to cart" -> cart += product   ← append a COPY of this row to another :state list
+:::
+@loop cart into line
+:button "Remove" -> cart remove line        ← drop this row from the list being looped
+```
+`cart += product` is the only way to carry a loop item into another list (literals still can't reference rows). `<list> remove <item>`: `<list>` must be the loop's own `:state` source and `<item>` the loop variable (both compile-checked). This is the canonical add-to-cart / remove-line / delete-todo pattern — no `.js` needed. Removal targets the exact row, so it is correct even under a `where` filter.
+
+### 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,22 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.7.0 — 2026-06-13
+
+- **Per-row actions in reactive loops.** A `:button` inside `@loop … into item` can now act on its own row — the canonical add-to-cart / remove-line / delete-todo pattern, with no hand-written JavaScript:
+  - `cart += item` appends a **copy** of the current row to another `:state` list. This is the only way to carry a loop item into another list (literal action values still can't reference rows); the copy means adding the same source row twice yields two independent lines.
+  - `<list> remove <item>` removes the current row from the list being looped. `<list>` must be that loop's own `:state` source and `<item>` the loop variable — both validated at compile time.
+  The runtime resolves the clicked row by stamping each reconciled node with its item, so removal targets the exact row and stays correct even when the loop is filtered with `where` (index-based removal would not). Closes the last gap blocking a real store demo.
+- Live demo: the reactive page's filtering section is now a full mini-shop — search products, add to cart, remove lines — all composing on one page.
+
+## 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.

package/README.md

@@ -74,6 +74,61 @@ 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.
+
+### Editable lists — per-row actions
+
+A `:button` inside a reactive `@loop` can act on its own row. Two row actions exist:
+
+```wd
+:state products = [{"id": 1, "name": "Aurora", "price": 49}]
+:state cart = []
+
+@loop products into product
+::: card
+**{ product.name }** — ${ product.price }
+:button "Add to cart" -> cart += product    <- carry this row into another list
+:::
+@endloop
+
+@loop cart into line
+::: card
+{ line.name }
+:button "Remove" -> cart remove line          <- drop this row from the looped list
+:::
+@endloop
+```
+
+- `cart += <item>` appends a **copy** of the current row to another `:state` list, so adding the same product twice gives two independent lines.
+- `<list> remove <item>` removes the current row from the list being looped. The `<list>` must be that loop's own `:state` source and `<item>` must be the loop variable — both checked at compile time. Removal targets the exact row, so it stays correct even when the loop is filtered with `where`.
+
+That is a full add-to-cart / remove-line flow — and a to-do list with delete — in plain Markdown, no JavaScript.
+
 ## Sections
 
 ```wd

package/docs/spec-alignment.md

@@ -46,6 +46,16 @@ 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`.
+- **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.
+- **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -19,6 +19,7 @@
     "src",
     "site",
     "docs",
+    "AGENTS.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/site/pages/docs/index.wd

@@ -61,6 +61,48 @@ The source decides how the loop behaves:
 
 Loops nest, and `{ card.title }` style dotted paths reach into each row.
 
+### Filtering with `where`
+
+Add `where <predicate>` to filter a loop. Conditions join with `and` / `or`:
+
+```wd
+@loop /products.json into p where p.featured == true and p.price < 80
+- { p.name }
+@endloop
+```
+
+Operators are `==` `!=` `<` `<=` `>` `>=` and `contains` (case-insensitive substring). Operands are item fields, declared `:state`, numbers, or `"strings"` — a validated whitelist, never arbitrary code.
+
+The predicate decides reactivity exactly like the source does: read only the row and the filter runs at build time (zero JS); read a `:state` value and the loop re-filters live. Pair it with `:bind` for a search box 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 — type and the list filters as you go.
+
+### Editable lists with per-row actions
+
+A `:button` inside a reactive loop can act on its own row — the basis for carts and to-do lists:
+
+```wd
+@loop products into product
+:button "Add to cart" -> cart += product
+:::
+@loop cart into line
+:button "Remove" -> cart remove line
+:::
+```
+
+`cart += product` appends a copy of the current row to another `:state` list; `cart remove line` removes the current row from the list being looped. Both are checked against the enclosing loop at compile time — no JavaScript.
+
 ## Interpolation
 
 One syntax everywhere: `{ name }` or `{ name.path }`.

package/site/pages/reactive.skin

@@ -60,3 +60,33 @@ ul
 
 .tally-card h3
   color $warm
+
+.card.product
+  display flex
+  align-items center
+  justify-content space-between
+  gap 1rem
+  border 1px solid $line
+  bg $panel
+  padding .6rem 1rem
+  margin .5rem 0
+  radius $radius
+
+.card.product p
+  margin 0
+
+.card.line
+  display flex
+  align-items center
+  justify-content space-between
+  gap 1rem
+  border 1px solid $line
+  padding .5rem 1rem
+  margin .4rem 0
+  radius $radius
+
+.card.line button
+  bg transparent
+  color $warm
+  border 1px solid $line
+  padding .35rem .8rem

package/site/pages/reactive.wd

@@ -64,6 +64,36 @@ in progress …
 
 Each row picks one of three states from two nested conditionals, all in plain Markdown — no component, no ternary, no JavaScript.
 
+## Live filtering — search in pure Markdown
+
+`@loop … where` filters a list, and because the predicate reads a `:state` value, the loop re-filters live as you type. `:bind` is the input bound two-way to that state. Type below and watch the list narrow — no event handlers, no JavaScript:
+
+: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}, {"id": 5, "name": "Ember Kettle", "price": 64}]
+:state cart = []
+:state q = ""
+
+:bind q placeholder="Search products…"
+
+@loop products into p where p.name contains q
+::: card .product
+**{ p.name }** — ${ p.price }
+:button "Add to cart" -> cart += p
+:::
+@endloop
+
+The predicate whitelist is compile-time validated — item fields, declared state, numbers, and strings only. An item-only predicate (say `where p.price < 50`) would instead filter at build time and ship zero JavaScript.
+
+### …and an editable cart
+
+A `:button` inside a loop can act on its own row. **Add to cart** carries the row into another list; **Remove** drops a line — a whole add/remove flow with no JavaScript:
+
+@loop cart into line
+::: card .line
+{ line.name } — ${ line.price }
+:button "Remove" -> cart remove line
+:::
+@endloop
+
 ## Section-scoped state
 
 Two sections can each own a state value named `tally` without colliding. Buttons resolve to the nearest scope:

package/src/compiler.js

@@ -178,6 +178,11 @@ function compileBody(lines, ctx) {
       out.push(handleInput(line, ctx));
       continue;
     }
+    if (/^:bind\s/.test(line)) {
+      flush();
+      out.push(handleBind(line, ctx));
+      continue;
+    }
     if (/^:submit\s/.test(line)) {
       flush();
       out.push(handleSubmit(line, ctx));
@@ -508,6 +513,38 @@ function handleInput(line, ctx) {
   return `<input type="${escapeHtml(type)}" ${attrs.join(" ")}>`;
 }
 
+// :bind <state> [placeholder="…"] [type=…] — a live two-way input bound to a
+// declared :state. Updates state on every keystroke; reflects state back when
+// not focused. The state must be declared first (with :state).
+function handleBind(line, ctx) {
+  const match = line.match(/^:bind\s+([A-Za-z_$][\w$]*)\s*(.*)$/);
+  if (!match) throw new Error(`Malformed :bind in ${ctx.file}: ${line}. Use: :bind query placeholder="Search"`);
+  const key = resolveStateKey(match[1], ctx);
+  if (!key) {
+    throw new Error(`:bind ${match[1]} in ${ctx.file} has no matching state. Declare it first: :state ${match[1]} = ""`);
+  }
+  ctx.comp.assets.runtime = true;
+  let type = "text";
+  const attrs = [];
+  const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
+  for (const token of (match[2] || "").matchAll(re)) {
+    if (token[3]) {
+      if (!["required", "autofocus"].includes(token[3])) throw new Error(`Unknown :bind flag "${token[3]}" in ${ctx.file}`);
+      attrs.push(token[3]);
+      continue;
+    }
+    const value = stripQuotes(token[2]);
+    if (token[1] === "type") { type = value; continue; }
+    if (!["placeholder", "autocomplete"].includes(token[1])) {
+      throw new Error(`Unknown :bind attribute "${token[1]}" in ${ctx.file}`);
+    }
+    attrs.push(`${token[1]}="${escapeHtml(value)}"`);
+  }
+  const initial = ctx.comp.state.get(key);
+  const valueAttr = initial === undefined || initial === null ? "" : ` value="${escapeHtml(String(initial))}"`;
+  return `<input type="${escapeHtml(type)}" data-wd-bind-input="${key}"${valueAttr} ${attrs.join(" ")}>`;
+}
+
 function handleSubmit(line, ctx) {
   const match = line.match(/^:submit\s+"([^"]+)"\s*$/);
   if (!match) throw new Error(`Malformed :submit in ${ctx.file}: ${line}. Use: :submit "Label"`);
@@ -558,16 +595,17 @@ function handleIf(line, truthyLines, falsyLines, ctx) {
 }
 
 function handleLoop(line, bodyLines, ctx) {
-  const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)\s*$/);
-  if (!match) throw new Error(`Malformed @loop in ${ctx.file}: ${line}. Use: @loop <things> into <thing>`);
+  const match = line.match(/^@loop\s+(.+?)\s+into\s+([A-Za-z_$][\w$]*)(?:\s+where\s+(.+?))?\s*$/);
+  if (!match) throw new Error(`Malformed @loop in ${ctx.file}: ${line}. Use: @loop <things> into <thing> [where <predicate>]`);
   const source = stripQuotes(match[1].trim());
   const itemName = match[2];
+  const where = match[3] ? compilePredicate(match[3].trim(), itemName, ctx) : null;
 
   if (source.startsWith("/") || source.startsWith("./") || source.startsWith("../") || source.endsWith(".json")) {
     const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
     const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
-    return staticUnroll(rows, itemName, bodyLines, ctx);
+    return loopOverData(rows, itemName, bodyLines, ctx, where);
   }
 
   const resolved = lookupPath(source, ctx);
@@ -575,12 +613,12 @@ function handleLoop(line, bodyLines, ctx) {
     if (!Array.isArray(resolved.value)) {
       throw new Error(`@loop ${source} in ${ctx.file} found an in-scope value, but it is not a list`);
     }
-    return staticUnroll(resolved.value, itemName, bodyLines, ctx);
+    return loopOverData(resolved.value, itemName, bodyLines, ctx, where);
   }
 
   if (/^[A-Za-z_$][\w$]*$/.test(source)) {
     const key = resolveStateKey(source, ctx);
-    if (key) return reactiveLoop(key, itemName, bodyLines, ctx);
+    if (key) return reactiveLoop(key, itemName, bodyLines, ctx, where ? { where } : null);
   }
 
   throw new Error(
@@ -588,6 +626,74 @@ function handleLoop(line, bodyLines, ctx) {
   );
 }
 
+// A static source (JSON file / in-scope value). No `where`, or a `where` that
+// only reads the loop item → filter at build time and stay zero-JS. A `where`
+// that reads :state → becomes a reactive filtered loop with the rows baked in.
+function loopOverData(rows, itemName, bodyLines, ctx, where) {
+  if (!where) return staticUnroll(rows, itemName, bodyLines, ctx);
+  if (!where.refsState) return staticUnroll(rows.filter((row) => evalPredicate(where.body, row, ctx)), itemName, bodyLines, ctx);
+  return reactiveLoop(null, itemName, bodyLines, ctx, { where, data: rows });
+}
+
+// Compile a `where` predicate to a safe JS boolean expression over I()/S()/C().
+// Conditions (operand <op> operand) join with `and`/`or`; operands are loop-item
+// paths, declared :state, numbers, or strings. No identifiers survive un-mapped.
+function compilePredicate(raw, itemName, ctx) {
+  const parts = raw.split(/\s+(and|or)\s+/i);
+  const pieces = [];
+  let refsState = false;
+  for (let i = 0; i < parts.length; i++) {
+    if (i % 2 === 1) { pieces.push(parts[i].toLowerCase() === "and" ? "&&" : "||"); continue; }
+    const cond = compileCondition(parts[i].trim(), itemName, ctx);
+    refsState = refsState || cond.usesState;
+    pieces.push(`(${cond.expr})`);
+  }
+  return { body: pieces.join(" "), refsState };
+}
+
+function compileCondition(cond, itemName, ctx) {
+  const m = cond.match(/^(.+?)\s+(contains|==|!=|>=|<=|>|<)\s+(.+)$/i);
+  if (!m) throw new Error(`Malformed where-condition "${cond}" in ${ctx.file}. Use: ${itemName}.field contains state, or ${itemName}.field <op> value.`);
+  const left = compileOperand(m[1].trim(), itemName, ctx);
+  const right = compileOperand(m[3].trim(), itemName, ctx);
+  const usesState = left.usesState || right.usesState;
+  const op = m[2].toLowerCase();
+  if (op === "contains") return { expr: `C(${left.code}, ${right.code})`, usesState };
+  return { expr: `${left.code} ${op} ${right.code}`, usesState };
+}
+
+function compileOperand(tok, itemName, ctx) {
+  if (/^"[^"]*"$/.test(tok) || /^'[^']*'$/.test(tok)) return { code: JSON.stringify(tok.slice(1, -1)), usesState: false };
+  if (/^-?\d+(?:\.\d+)?$/.test(tok)) return { code: tok, usesState: false };
+  if (["true", "false", "null"].includes(tok)) return { code: tok, usesState: false };
+  if (!/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(tok)) {
+    throw new Error(`Unsupported operand "${tok}" in @loop where (${ctx.file}). Use ${itemName}.field, a :state name, a number, or a "string".`);
+  }
+  const segs = tok.split(".");
+  if (segs.some((seg) => ["constructor", "prototype", "__proto__"].includes(seg))) {
+    throw new Error(`Path "${tok}" is not allowed in @loop where (${ctx.file})`);
+  }
+  if (segs[0] === itemName) return { code: `I(${JSON.stringify(segs.slice(1).join("."))})`, usesState: false };
+  const key = resolveStateKey(segs[0], ctx);
+  if (!key) {
+    throw new Error(`@loop where references unknown name "${segs[0]}" in ${ctx.file}. Use the loop item (${itemName}.field) or a declared :state.`);
+  }
+  const rest = segs.slice(1).join(".");
+  return { code: `S(${JSON.stringify(key)}${rest ? `, ${JSON.stringify(rest)}` : ""})`, usesState: true };
+}
+
+const containsHelper = (a, b) => String(a ?? "").toLowerCase().includes(String(b ?? "").toLowerCase());
+
+function evalPredicate(body, item, ctx) {
+  try {
+    const I = (p) => getPath(item, p ? p.split(".") : []);
+    const S = (k, r) => getPath(ctx.comp.state.get(k), r ? r.split(".") : []);
+    return Boolean(new Function("I", "S", "C", `return (${body});`)(I, S, containsHelper));
+  } catch {
+    return false;
+  }
+}
+
 function staticUnroll(rows, itemName, bodyLines, ctx) {
   const out = [];
   for (const row of rows) {
@@ -597,9 +703,9 @@ function staticUnroll(rows, itemName, bodyLines, ctx) {
   return out.join("\n");
 }
 
-function reactiveLoop(key, itemName, bodyLines, ctx) {
+function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
   ctx.comp.assets.runtime = true;
-  const templateCtx = { ...ctx, loopItem: itemName, scope: createScope(ctx.scope) };
+  const templateCtx = { ...ctx, loopItem: itemName, loopKey: key, scope: createScope(ctx.scope) };
   const templateHtml = compileBody(bodyLines, templateCtx).trim();
 
   let wrapperTag = "div";
@@ -612,7 +718,10 @@ function reactiveLoop(key, itemName, bodyLines, ctx) {
     itemTemplate = `<div data-wd-loop-piece>${templateHtml}</div>`;
   }
 
-  const rows = Array.isArray(ctx.comp.state.get(key)) ? ctx.comp.state.get(key) : [];
+  const where = opts?.where || null;
+  const baked = opts?.data || null;       // rows for a static source filtered by state
+  const allRows = key ? (Array.isArray(ctx.comp.state.get(key)) ? ctx.comp.state.get(key) : []) : (baked || []);
+  const rows = where ? allRows.filter((row) => evalPredicate(where.body, row, ctx)) : allRows;
   const counts = new Map();
   const initial = rows
     .map((item) => {
@@ -621,7 +730,9 @@ function reactiveLoop(key, itemName, bodyLines, ctx) {
     })
     .join("");
 
-  return `<div data-wd-loop="${key}"><template data-wd-loop-template>${itemTemplate}</template><${wrapperTag} data-wd-loop-out>${initial}</${wrapperTag}></div>`;
+  const whereAttr = where ? ` data-wd-loop-where="${escapeHtml(where.body)}"` : "";
+  const dataAttr = baked ? ` data-wd-loop-data="${escapeHtml(JSON.stringify(baked))}"` : "";
+  return `<div data-wd-loop="${key || ""}"${whereAttr}${dataAttr}><template data-wd-loop-template>${itemTemplate}</template><${wrapperTag} data-wd-loop-out>${initial}</${wrapperTag}></div>`;
 }
 
 function withLoopKey(template, itemKey) {
@@ -822,17 +933,41 @@ function parseAction(raw, ctx) {
   if (increment) return { op: "inc", target: resolveTarget(increment[1]) };
   const decrement = expression.match(/^([A-Za-z_$][\w$]*)--$/);
   if (decrement) return { op: "dec", target: resolveTarget(decrement[1]) };
+  // Per-row: carry the current loop item into another list — `cart += product`.
+  // Only inside a reactive @loop; the runtime resolves the row from the DOM.
   const add = expression.match(/^([A-Za-z_$][\w$]*)\s*\+=\s*(.+)$/);
   if (add) {
+    const rhs = add[2].trim();
+    if (ctx.loopItem && rhs === ctx.loopItem) {
+      const target = resolveTarget(add[1]);
+      if (!Array.isArray(ctx.comp.state.get(target))) {
+        throw new Error(`Button action "${raw}" needs ${add[1]} to be a :state list (declare it "${add[1]} = []") in ${ctx.file}.`);
+      }
+      return { op: "append-row", target };
+    }
     const target = resolveTarget(add[1]);
-    const value = parseActionLiteral(add[2]);
+    const value = parseActionLiteral(rhs);
     if (Array.isArray(ctx.comp.state.get(target))) return { op: "append", target, value };
     if (typeof value === "number") return { op: "add", target, value };
     throw new Error(`Unsupported button action "${raw}". += with non-number values requires a list state target.`);
   }
+  // Per-row: remove the current row from the list being looped — `todos remove todo`.
+  const remove = expression.match(/^([A-Za-z_$][\w$]*)\s+remove\s+([A-Za-z_$][\w$]*)$/);
+  if (remove) {
+    if (!ctx.loopItem) {
+      throw new Error(`Button action "${raw}" is only valid inside a reactive @loop in ${ctx.file}. Use: :button "Remove" -> list remove item`);
+    }
+    if (remove[2] !== ctx.loopItem) {
+      throw new Error(`Button action "${raw}" must remove the loop item "${ctx.loopItem}" in ${ctx.file}, not "${remove[2]}".`);
+    }
+    if (!ctx.loopKey || resolveStateKey(remove[1], ctx) !== ctx.loopKey) {
+      throw new Error(`Button action "${raw}" must target the :state list being looped (@loop ${remove[1]} into ${ctx.loopItem}) in ${ctx.file}.`);
+    }
+    return { op: "remove", target: ctx.loopKey };
+  }
   const assign = expression.match(/^([A-Za-z_$][\w$]*)\s*=\s*(.+)$/);
   if (assign) return { op: "set", target: resolveTarget(assign[1]), value: parseActionLiteral(assign[2]) };
-  throw new Error(`Unsupported button action "${raw}". Supported actions: count++, count--, count += 1, items += "value", name = "value".`);
+  throw new Error(`Unsupported button action "${raw}". Supported actions: count++, count--, count += 1, items += "value", name = "value", list remove item (in a loop), cart += item (in a loop).`);
 }
 
 function parseActionLiteral(raw) {

package/src/runtime.js

@@ -50,6 +50,17 @@ function recompute() {
   }
 }
 
+const containsFn = (a, b) => String(a ?? "").toLowerCase().includes(String(b ?? "").toLowerCase());
+const predicateCache = new Map();
+function loopPredicate(body) {
+  let fn = predicateCache.get(body);
+  if (!fn) {
+    fn = new Function("I", "S", "C", `return (${body});`);
+    predicateCache.set(body, fn);
+  }
+  return fn;
+}
+
 function loopKeyOf(item, counts) {
   const base =
     item && typeof item === "object"
@@ -91,11 +102,20 @@ function render() {
   }
 
   for (const region of document.querySelectorAll("[data-wd-loop]")) {
-    const rows = state[region.getAttribute("data-wd-loop")];
+    const key = region.getAttribute("data-wd-loop");
+    const data = region.getAttribute("data-wd-loop-data");
+    const rows = key ? state[key] : (data ? JSON.parse(data) : []);
     const template = region.querySelector("template[data-wd-loop-template]");
     const out = region.querySelector("[data-wd-loop-out]");
     if (!template || !out) continue;
-    const list = Array.isArray(rows) ? rows : [];
+    let list = Array.isArray(rows) ? rows : [];
+    const where = region.getAttribute("data-wd-loop-where");
+    if (where) {
+      const predicate = loopPredicate(where);
+      list = list.filter((item) =>
+        predicate((path) => getPath(item, path), (k, r) => getPath(state[k], r || ""), containsFn)
+      );
+    }
 
     const existing = new Map();
     for (const child of [...out.children]) {
@@ -112,6 +132,7 @@ function render() {
       }
       used.add(key);
       fillItem(node, item);
+      node.__wdItem = item; // let per-row actions resolve which row was clicked
       out.appendChild(node);
     }
     for (const [key, node] of existing) {
@@ -122,6 +143,26 @@ function render() {
   for (const node of document.querySelectorAll("[data-wd-bind]")) {
     node.textContent = getPath(state[node.getAttribute("data-wd-bind")], node.getAttribute("data-wd-path")) ?? "";
   }
+
+  for (const input of document.querySelectorAll("[data-wd-bind-input]")) {
+    if (document.activeElement !== input) input.value = state[input.getAttribute("data-wd-bind-input")] ?? "";
+  }
+}
+
+document.addEventListener("input", (event) => {
+  const input = event.target.closest("[data-wd-bind-input]");
+  if (!input) return;
+  state[input.getAttribute("data-wd-bind-input")] = input.value;
+  savePersisted();
+  render();
+});
+
+// The clicked button's row: the nearest reconciled loop node carries its item.
+function clickedRow(el) {
+  const row = el.closest("[data-wd-loop-key]");
+  const region = el.closest("[data-wd-loop]");
+  if (!row || !region) return null;
+  return { srcKey: region.getAttribute("data-wd-loop"), item: row.__wdItem };
 }
 
 document.addEventListener("click", (event) => {
@@ -137,6 +178,20 @@ document.addEventListener("click", (event) => {
   if (op === "add") state[target] = Number(state[target] ?? 0) + Number(value);
   if (op === "append") state[target] = [...(Array.isArray(state[target]) ? state[target] : []), value];
   if (op === "set") state[target] = value;
+  if (op === "remove") {
+    const row = clickedRow(action);
+    if (row && row.srcKey) state[row.srcKey] = (Array.isArray(state[row.srcKey]) ? state[row.srcKey] : []).filter((x) => x !== row.item);
+  }
+  if (op === "append-row") {
+    const row = clickedRow(action);
+    // Clone the row so each appended line is a distinct object — otherwise adding
+    // the same source row twice yields two identical references and a later
+    // remove (filter by !== ref) would delete both lines.
+    if (row && row.item !== undefined) {
+      const copy = row.item && typeof row.item === "object" ? structuredClone(row.item) : row.item;
+      state[target] = [...(Array.isArray(state[target]) ? state[target] : []), copy];
+    }
+  }
   savePersisted();
   render();
 });

package/src/scaffold.js

@@ -62,6 +62,31 @@ export function initProject(root) {
     "  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",
+    "",
     "button",
     "  bg $accent",
     "  color white",
@@ -71,9 +96,25 @@ export function initProject(root) {
   ].join("\n"));
   writeNew(root, "site/_/nav.wd", [
     "<nav>",
-    "  <a href=\"/\">Home</a>",
+    "  <strong>My site</strong>",
+    "  <span class=\"links\">",
+    "    <a href=\"/\">Home</a>",
+    "    <a href=\"/about/\">About</a>",
+    "  </span>",
     "</nav>"
   ].join("\n"));
+  writeNew(root, "site/pages/about.md", [
+    "---",
+    "title: About",
+    "---",
+    "",
+    "# 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.",
+    "",
+    "[Back home](/)"
+  ].join("\n"));
   writeNew(root, "README.md", [
     "# My Darkmown site",
     "",

package/src/skin.js

@@ -5,11 +5,27 @@ const aliases = new Map([
   ["bg", "background"]
 ]);
 
+// `font` is aliased to font-family for the common `font <stack>` case, but the
+// real CSS `font` shorthand (`font 16px/1.4 system-ui`) must pass through. If
+// the value looks like a shorthand (leads with a size or contains `/`), keep it.
+function resolveProp(prop, rest) {
+  if (prop === "font" && (/^[\d.]/.test(rest[0] || "") || rest.join(" ").includes("/"))) return "font";
+  return aliases.get(prop) || prop;
+}
+
 export function compileSkin(source) {
   const lines = source
     .replace(/\r\n?/g, "\n")
+    .replace(/\/\*[\s\S]*?\*\//g, "") // strip /* … */ block comments (any span)
     .split("\n")
-    .filter((raw) => raw.trim() && !raw.trim().startsWith("//"))
+    .filter((raw) => {
+      const t = raw.trim();
+      if (!t || t.startsWith("//")) return false;
+      // Decorative divider lines (----, ====, * * *, ~~~) carry no rule and would
+      // otherwise parse as a bogus selector/declaration. Anything with a letter or
+      // digit is real content; punctuation-only lines are skipped.
+      return /[A-Za-z0-9]/.test(t);
+    })
     .map((raw) => ({ indent: raw.match(/^\s*/)[0].length, text: raw.trim() }));
 
   const stack = [];
@@ -39,16 +55,23 @@ export function compileSkin(source) {
 
     if (opensBlock) {
       const parent = stack.at(-1)?.selector;
-      const selector = normalizeSelector(text, parent);
-      stack.push({ indent, selector });
+      // At-rules (@media, @supports) wrap rules instead of extending selectors:
+      // carry the outer selector through so nested selectors combine normally.
+      if (text.startsWith("@")) {
+        stack.push({ indent, selector: parent ?? null, media: text });
+      } else {
+        stack.push({ indent, selector: normalizeSelector(text, parent) });
+      }
       continue;
     }
 
     const current = stack.at(-1)?.selector || ":root";
+    const media = stack.find((frame) => frame.media)?.media;
     const [prop, ...rest] = text.split(/\s+/);
-    const cssProp = aliases.get(prop) || prop;
+    const cssProp = resolveProp(prop, rest);
     const value = rest.join(" ").replace(/\$([a-zA-Z0-9_-]+)/g, "var(--$1)");
-    css.push(`${current} { ${cssProp}: ${value}; }`);
+    const rule = `${current} { ${cssProp}: ${value}; }`;
+    css.push(media ? `${media} { ${rule} }` : rule);
   }
 
   if (rootVars.length) css.unshift(`:root {\n${rootVars.join("\n")}\n}`);