@zvndev/darkmown 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.11.0 — 2026-06-16
+
+Three big `.wd` capabilities for building real apps — global state, a full fetch lifecycle, and complete loop ergonomics — plus a leaner runtime.
+
+- **Global state — `:store`.** `:store cart = []` is durable by default (localStorage), synced across browser tabs in real time, and global by name; opt out of persistence with `ephemeral`. Button actions gained a full vocabulary — `toggle`, `prepend`, `merge`, `delete`, `clear`, `member-toggle`, `remove`/`remove-value`, and `reset` (back to the declared seed) — all working on `:state` and `:store`, with dotted-path targets (`cart.count++`) and `;`-separated multi-action buttons.
+- **Fetch lifecycle.** `:fetch` now exposes `name_loading` and `name_empty` alongside `name_error`, so loading → error → empty → data renders with plain `:if`. URLs interpolate state (`/api/users/{ id }`) and auto-refetch when their inputs change; new `timeout`, `retry`, `method`, `headers`, and `body` options; a `refetch` action; and `@loop` now reads a dotted sub-path of fetched data (`@loop data.items into x`).
+- **Loop ergonomics.** `@loop … sort by key [asc|desc] reverse offset N limit N` (offset/limit accept a `:state` key for reactive paging), per-row `$index` / `$number` / `$first` / `$last` / `$count`, and an `@empty` branch for zero rows. Static loops still resolve at build time and ship zero JS.
+- **Leaner runtime.** The shipped runtime now strips whole-line `//` comments in addition to JSDoc (still no minification — identifiers, structure, and whitespace are preserved), so the source stays fully commented while the download shrinks. Even with all three features above, the reactive runtime is ~4.7 KB gzipped, comfortably under the 5 KB budget.
+- **Security.** The prototype-pollution guard is now a single source of truth shared by the path reader and writer; dotted action targets and dynamic fetch URLs are guarded and URL-encoded.
+
 ## 0.10.0 — 2026-06-15
 
 Launch-readiness: every public claim is now backed by runnable evidence instead of stale copy.

package/README.md

@@ -121,6 +121,67 @@ Operators: `==` `!=` `<` `<=` `>` `>=`, plus `contains` for case-insensitive sub
 
 `: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.
 
+### Sorting, paging, and meta — `sort by`, `limit`, `offset`, `reverse`
+
+Shape a loop without writing JavaScript. Clauses come in a fixed order after `into`:
+
+```
+@loop <src> into <item> [where …] [sort by <key> [asc|desc]] [reverse] [offset <N>] [limit <N>]
+```
+
+```wd
+@loop /posts.json into post sort by post.date desc limit 5
+{ $number }. { post.title }
+@endloop
+```
+
+- `sort by <key> [asc|desc]` — `<key>` must start with the loop item (`post.date`, not `date`). Numbers sort numerically; everything else sorts as text. `asc` is the default.
+- `reverse` — reverse the (already sorted) order.
+- `offset <N>` / `limit <N>` — `<N>` is a non-negative integer **or** a `:state`/`:store` key, which makes pagination reactive:
+
+```wd
+:state pageSize = 10
+
+@loop products into product limit pageSize
+- { product.name }
+@endloop
+```
+
+Each row exposes five meta variables, relative to the rendered slice:
+
+| Variable | Value |
+|---|---|
+| `{ $index }` | 0-based position |
+| `{ $number }` | 1-based position (`$index + 1`) |
+| `{ $first }` | `true` on the first row |
+| `{ $last }` | `true` on the last row |
+| `{ $count }` | number of rendered rows |
+
+They work in interpolation and in `:if`:
+
+```wd
+@loop products into product
+:if $first
+**Top pick:**
+:endif
+{ $number } of { $count } — { product.name }
+@endloop
+```
+
+### Empty lists — `@empty`
+
+Add an `@empty` branch to show a fallback when the loop renders no rows (after `where`, `limit`, and the rest):
+
+```wd
+@loop todos into todo
+- { todo.title }
+@empty
+Nothing left to do.
+@endloop
+```
+
+> **Note:** All of these clauses stay build-time when the source and every clause argument are static — a sorted, limited loop over a JSON file ships **zero JavaScript**. The loop becomes reactive only when the source is `:state`/`:store`/`:fetch` data, or a clause reads reactive state (like `limit pageSize`).
+
 ### Editable lists — per-row actions
 
 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:
@@ -181,18 +242,162 @@ Count is still zero.
 
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in colocated `.js` files.
 
-## Data, forms, and persistence
+### Button actions
+
+A `:button "Label" -> action` mutates one `:state` or `:store` value. The same vocabulary works on both:
+
+| Action | Syntax | Effect |
+|---|---|---|
+| Increment | `n++` | add 1 |
+| Decrement | `n--` | subtract 1 |
+| Add | `n += 5` | add a number |
+| Subtract | `n -= 2` | subtract a number |
+| Set | `name = value` | assign a literal |
+| Toggle | `flag toggle` | flip a boolean |
+| Append | `list append v` or `list += v` | add to the end of an array |
+| Prepend | `list prepend v` | add to the front |
+| Member toggle | `list toggle v` | add `v` if absent, else remove it |
+| Remove value | `list remove v` | remove a value from an array |
+| Clear | `name clear` | empty an array or object |
+| Merge | `obj merge other` | shallow-merge an object (key or inline `{…}`) |
+| Delete | `obj delete "key"` | remove a key |
+| Reset | `name reset` | restore the declared starting value |
+
+Values are literals: a `"string"`, number, `true`/`false`/`null`, or inline JSON (`{…}` / `[…]`).
+
+**Targets can be dotted paths,** so a button can reach into nested state:
+
+```wd
+:state cart = {"count": 0, "total": 0}
+
+:button "Add item" -> cart.count++
+```
+
+**One button can run several actions** with `;`. They apply in order, then the page renders once:
+
+```wd
+:button "Add to cart" -> cart.count++ ; cart.total += 9
+```
+
+> **Pitfall:** `list toggle v` and `list remove v` match members by value (`===`). That is exact for strings, numbers, and booleans, but not reliable for object members — two equal-looking objects are different values. To remove a row object, loop the list and use the per-row `remove` action below.
+
+## Fetching data
+
+`:fetch name from "url"` declares state and fills it from JSON over the network:
+
+```
+:fetch <name> from "<url>" [method=GET] [when=load|visible] [timeout=<ms>] [retry=<N>] [headers=<key>] [body=<key>]
+```
+
+Each fetch automatically declares four state keys you can branch on:
+
+| State | Type | Meaning |
+|---|---|---|
+| `name` | the data | `null` until the response arrives |
+| `name_loading` | boolean | `true` while the request is in flight |
+| `name_error` | string | the error message, or `null` |
+| `name_empty` | boolean | `true` when the data is `null`, `[]`, or `{}` |
+
+### The four-state pattern
+
+Cover loading, errors, empty, and data — `@empty` (from the loops above) absorbs the empty case:
+
+```wd
+:fetch roster from "/__wd/data/team.json" timeout=8000 retry=2
+
+:if roster_loading
+Loading…
+:else
+:if roster_error
+Couldn't load the team: { roster_error }
+:else
+@loop roster into member
+- { member.name }
+@empty
+No team members yet.
+@endloop
+:endif
+:endif
+```
+
+### Options
+
+- `method=` — `GET` (default), `POST`, `PUT`, `PATCH`, or `DELETE`.
+- `when=` — `load` (default) fires on page load; `visible` waits until the spot scrolls into view.
+- `timeout=<ms>` — abort and set `name_error` if the response is too slow.
+- `retry=<N>` — retry on network failure or a 5xx response before surfacing the error.
+- `headers=<key>` — a `:state`/`:store` key holding an object, sent as request headers.
+- `body=<key>` — a `:state`/`:store` key, JSON-serialized as the request body (for non-`GET`).
+
+### Dynamic URLs and refetching
+
+A URL can interpolate state with `{ }`. The fetch re-runs automatically when that state changes (and skips while the value is still empty):
+
+```wd
+:state userId = ""
+
+:fetch profile from "/api/users/{ userId }"
+```
+
+Trigger a reload by hand with the `refetch` action:
+
+```wd
+:button "Reload" -> roster refetch
+```
+
+### Looping into fetched data
+
+Loop a sub-path of fetched (or any) state with a dotted source:
+
+```wd
+:fetch org from "/__wd/data/org.json"
+
+@loop org.members into member
+- { member.name }
+@endloop
+```
+
+> **Note:** Shelf `.json` files are published at `/__wd/data/`, so `:fetch` works on any static host. The `darkmown dev` server also ships a `/__wd/echo` endpoint for demos.
+
+## Global state — `:store`
+
+`:state` is local to its page (and section). `:store` is **global, durable, and shared across tabs** — the right home for a cart, a theme, or a signed-in user.
+
+```wd
+:store cart = []
+
+:button "Add" -> cart += {"id": 1, "name": "Aurora"}
+
+You have { cart } items.
+```
+
+- **Durable by default.** A store is saved to `localStorage` under `wd:store:<name>` and reloaded on the next visit.
+- **Shared across tabs.** Change a store in one tab and every other tab on the same site updates live.
+- **Global by name.** A bare `{ cart }` reads the same store everywhere — stores are never section-scoped.
+- **Same value grammar as `:state`** — string, number, boolean, `null`, array, or object — and the **same** button actions (`cart += …`, `count++`, `theme = "dark"`, and so on).
+
+The declared value is a **seed**: it is used only the first time, when the store is absent from storage. After that the persisted value wins, so visitors keep their data.
+
+### Opt out of persistence
+
+Add `ephemeral` for an in-memory store that resets on reload and does not sync across tabs:
+
+```wd
+:store sidebarOpen = false ephemeral
+```
+
+> **Pitfall:** A store name must be unique. Declaring the same name as both a `:store` and a `:state` on one page is a compile error.
+
+## Forms and persistence
+
+Fetched data and a form live happily on the same page:
 
 ```wd
 :fetch team from "/__wd/data/team.json"
 
-:if team
 @loop team into member
 - { member.name }
 @endloop
-:else
-Loading…
-:endif
 
 :form into profile
 :input name placeholder="Your name" required
@@ -202,11 +407,10 @@ Loading…
 :state cart = [] persist
 ```
 
-- `:fetch name from "url"` declares state and fills it from JSON over the network; `name_error` carries failures. Add `when=visible` to defer the request until the spot scrolls into view.
-- `:computed total = items.length * 4` derives state from state with a compile-time-checked expression (names, numbers, arithmetic, comparisons — nothing else).
 - `:form into name` captures submits straight into state (no backend). `:form action="/url"` emits a plain native form instead — zero JS, full progressive enhancement.
-- `:form action="/url" into reply` does both: with JS the submit posts urlencoded via fetch and the JSON reply lands in state `reply` (`reply_error` on failure); without JS it is the same native POST. Darkmown adapts to any backend — it does not own one. `darkmown dev` ships a `/__wd/echo` endpoint for demos.
-- `:state x = [] persist` keeps that state in localStorage across reloads.
+- `:form action="/url" into reply` does both: with JS the submit posts urlencoded via fetch and the JSON reply lands in state `reply` (`reply_error` on failure); without JS it is the same native POST. Darkmown adapts to any backend — it does not own one.
+- `:state x = [] persist` keeps a single page's state in localStorage across reloads. (For state that is shared across pages and tabs, reach for [`:store`](#global-state--store) instead.)
+- `:computed total = items.length * 4` derives state from state with a compile-time-checked expression (names, numbers, arithmetic, comparisons — nothing else).
 - `:if item.path` works inside reactive loops for per-row branches, and nests — an inner `:if` resolves after the outer branch and stays reactive.
 
 ## The escape hatch

package/docs/spec-alignment.md

@@ -56,18 +56,26 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **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.
 
+## Stage 8 additions (2026-06-16)
+
+Three capability gaps from the 2026-06-16 audit, closed together over a shared `setPath` and an expanded action handler.
+
+- **Global state — `:store`:** `:store name = value [ephemeral]` declares page-global, durable-by-default state. Non-ephemeral stores persist to `localStorage["wd:store:<name>"]`, hydrate the declared value as a seed only when absent (first write wins thereafter), and sync across tabs via a single `storage` listener that re-renders on change. `ephemeral` opts out of persistence and cross-tab sync (in-memory for the session). Stores are never section-scoped; they share the runtime `state` object with `:state`, and a compile-time collision check keeps the two namespaces disjoint (declaring a `:store` and `:state` with one name, or a store twice, is a path-and-suggestion compile error). Reads (`{ cart }`, `:if`, `@loop`, `:computed`) and all actions resolve stores identically to state.
+- **Full action vocabulary:** `:button … ->` now covers `inc`/`dec` (`n++`, `n--`), `add`/`sub` (`n += k`, `n -= k`), `set` (`name = v`), `toggle` (`flag toggle`), `append` (`list append v` / `list += v`), `prepend`, `member-toggle` (`list toggle v`), `remove-value` (`list remove v`), `clear`, `merge` (`obj merge <key|{…}>`), `delete` (`obj delete "key"`), and `reset` (restore the declared seed) — alongside the existing `append-row` (`cart += item`) and per-row `remove`. Targets are dotted-path aware (`cart.count++`) via a safe `setPath` mirroring `getPath` (proto-pollution guards in compiler and runtime). Buttons may carry a `;`-separated action sequence, applied in order with a single render. Operands are the compile-validated literal grammar (string / number / boolean / null / inline JSON; merge also accepts a bare state/store key). **Honest caveat:** `member-toggle` and `remove-value` compare by value with `===`/`includes`, so they are reliable for primitive members but not for object members (two equal-looking objects are distinct values) — remove row objects with the per-row `remove` action instead.
+- **Fetch lifecycle:** `:fetch name from "url" [method=] [when=load|visible] [timeout=ms] [retry=N] [headers=key] [body=key]`. Each fetch auto-declares four states — `name` (null), `name_loading` (false), `name_error` (null), `name_empty` (false, true for `null`/`[]`/`{}`) — enabling the recommended loading → error → empty → data pattern (with `@empty` absorbing the empty case for list fetches). URLs may interpolate `{ state }` and auto-refetch (≈150 ms debounce) when a dependency key changes, skipping while a required value is empty. A `refetch` action (`name refetch`) re-triggers a load on demand. Full HTTP via `method`/`headers`/`body`; `timeout` arms an AbortController; `retry` backs off on network error or 5xx before surfacing the error.
+- **Loop ergonomics:** `@loop src into item [where …] [sort by key [asc|desc]] [reverse] [offset N] [limit N]`, clauses in that fixed order. `sort by` keys must start with the loop item (`item.path`); the comparator is numeric when both values are numbers, else `String(...).localeCompare`. `offset`/`limit` accept an integer **or** a `:state`/`:store` key for reactive pagination. Per-row meta vars — `$index` (0-based), `$number` (1-based), `$first`, `$last`, `$count` — are usable in interpolation and `:if`. An `@empty` branch renders when the post-pipeline row count is 0. **Honest caveat:** `sort by` over null/missing keys is best-effort — those values stringify (`"null"`/`"undefined"`) and fall into the lexicographic `localeCompare` path rather than getting special handling. Every clause stays build-time when the source and all arguments are static, preserving `runtime: false`.
+
 ## Stage 7 additions (2026-06-14)
 
 - **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`.
+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`, `:store`, `:computed`, `:button`, `:bind`, `:if`/`:else`/`:endif`, `:fetch`, `:form`/`:input`/`:submit`, `@loop`/`@empty`/`@endloop` (with `where`, `sort by`, `reverse`, `offset`, `limit`), `@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).
 - **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.
 - 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/_/nav.wd

@@ -4,6 +4,8 @@
   <a href="/docs/">Docs</a>
   <a href="/markdown/">Plain Markdown</a>
   <a href="/reactive/">Reactive</a>
+  <a href="/loops/">Loops</a>
+  <a href="/store/">Store</a>
   <a href="/data/">Data &amp; Forms</a>
   <a href="/app/">Live app</a>
 </nav>

package/site/pages/docs/index.wd

@@ -103,6 +103,44 @@ A `:button` inside a reactive loop can act on its own row — the basis for cart
 
 `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.
 
+### Sorting, paging, and meta variables
+
+Shape a loop with clauses in a fixed order after `into`: `where`, then `sort by`, `reverse`, `offset`, `limit`.
+
+```wd
+@loop /posts.json into post sort by post.date desc limit 5
+{ $number }. { post.title }
+@endloop
+```
+
+- `sort by <key> [asc|desc]` — the key must start with the loop item (`post.date`). Numbers sort numerically; anything else sorts as text. `asc` is the default.
+- `reverse` flips the order; `offset N` / `limit N` slice it. `N` can be an integer or a `:state`/`:store` key, which makes paging reactive (`limit pageSize`).
+
+Every row exposes meta variables — `{ $index }` (0-based), `{ $number }` (1-based), `{ $first }`, `{ $last }`, `{ $count }` — usable in interpolation and `:if`:
+
+```wd
+@loop products into product
+:if $first
+**Top pick:**
+:endif
+{ $number } of { $count } — { product.name }
+@endloop
+```
+
+### Empty lists with `@empty`
+
+Add an `@empty` branch to render a fallback when the loop produces no rows (after filtering and slicing):
+
+```wd
+@loop todos into todo
+- { todo.title }
+@empty
+Nothing left to do.
+@endloop
+```
+
+These clauses stay build-time when the source and every argument are static — a sorted, limited loop over a JSON file ships zero JS. The loop turns reactive only when the source or a clause reads `:state`/`:store`/`:fetch` data.
+
 ## Interpolation
 
 One syntax everywhere: `{ name }` or `{ name.path }`.
@@ -157,12 +195,70 @@ Count is still zero.
 
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in a colocated `.js` file.
 
-## Data, forms, and persistence
+### Button actions
+
+A `:button "Label" -> action` mutates one `:state` or `:store` value. The vocabulary is the same for both:
+
+- Numbers: `n++`, `n--`, `n += 5`, `n -= 2`
+- Set / toggle: `name = value`, `flag toggle`
+- Arrays: `list append v` (or `list += v`), `list prepend v`, `list toggle v`, `list remove v`, `list clear`
+- Objects: `obj merge other`, `obj delete "key"`
+- Universal: `name reset` restores the declared starting value
+
+Values are literals — a `"string"`, number, `true`/`false`/`null`, or inline JSON. Targets may be dotted paths (`cart.count++`), and one button can run several actions separated by `;` (applied in order, rendered once):
+
+```wd
+:button "Add to cart" -> cart.count++ ; cart.total += 9
+```
+
+`list toggle v` and `list remove v` match by value, which is exact for strings and numbers but not for object members — remove row objects with the per-row `remove` action instead.
+
+## Fetching data
+
+`:fetch name from "url"` declares state and fills it from JSON over the network. Shelf `.json` files are served at `/__wd/data/`. Each fetch auto-declares four states you can branch on: `name`, `name_loading`, `name_error`, and `name_empty`.
+
+```wd
+:fetch team from "/__wd/data/team.json" timeout=8000 retry=2
+
+:if team_loading
+Loading…
+:else
+:if team_error
+Couldn't load the team: { team_error }
+:else
+@loop team into member
+- { member.name }
+@empty
+No team members yet.
+@endloop
+:endif
+:endif
+```
+
+Options after the URL: `method=` (default `GET`), `when=load|visible`, `timeout=<ms>`, `retry=<N>`, `headers=<key>`, and `body=<key>` (the last two name a `:state`/`:store` key). A URL can interpolate state (`"/api/users/{ userId }"`) and re-fetches automatically when that state changes; trigger a reload by hand with `:button "Reload" -> team refetch`. Loop a sub-path of fetched data with a dotted source — `@loop team.members into member`.
+
+## Global state — `:store`
+
+`:store` is global, durable, and shared across browser tabs — the right home for a cart, a theme, or a signed-in user. Unlike `:state`, it is never section-scoped and persists by default.
+
+```wd
+:store cart = []
+
+:button "Add" -> cart += {"id": 1, "name": "Aurora"}
+
+You have { cart } items.
+```
+
+- Saved to localStorage under `wd:store:<name>` and reloaded on the next visit; changes sync live to other open tabs.
+- The declared value is a **seed**, used only the first time — afterward the persisted value wins.
+- Same value grammar and the same button actions as `:state`.
+- Add `ephemeral` for an in-memory store that resets on reload: `:store sidebarOpen = false ephemeral`.
+
+## Forms and persistence
 
-- `:fetch name from "url"` declares state and fills it from JSON over the network. Shelf `.json` files are served at `/__wd/data/`.
 - `:form into name` captures submits straight into state — no backend. `:form action="/url"` emits a plain native form with zero JS instead.
 - `:input field placeholder="…" required` and `:submit "Label"` build the form body.
-- `:state cart = [] persist` survives reloads via localStorage.
+- `:state cart = [] persist` survives reloads via localStorage on a single page; use `:store` for state shared across pages and tabs.
 - `:if item.path` works inside reactive loops for per-row branches, and conditionals nest — an inner `:if` resolves after the outer branch, staying reactive.
 - Reactive pages expose `window.wd` (`get`, `set`, `state`, `render`) so colocated `.js` can do anything directives can't. Section state is addressed as `sectionId:name`.
 
@@ -176,6 +272,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 `@loop` over fetched sub-paths. 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. `:store`, the full `:fetch` lifecycle (loading/error/empty states, dynamic URLs, `refetch`, and dotted loop sources), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `: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/`) and HTML-fragment swaps. See `docs/spec-alignment.md` in the package for the full audit.
 
 </main>

package/site/pages/loops.skin

@@ -0,0 +1,80 @@
+tokens
+  ink #171717
+  paper #faf8f3
+  panel #ffffff
+  line #dedbd3
+  accent #16645a
+  warm #a83f2a
+  radius 8px
+
+page
+  margin 0
+  font ui-serif, Georgia, Cambria, serif
+  color $ink
+  bg $paper
+  line-height 1.7
+
+main
+  max-width 820px
+  margin 0 auto
+  padding 3rem 2rem 5rem
+
+h1
+  font-size 3rem
+  line-height 1
+
+h2
+  margin-top 2.4rem
+  border-top 1px solid $line
+  padding-top 1.2rem
+
+a
+  color $accent
+
+button
+  border 1px solid $ink
+  bg $ink
+  color white
+  padding .72rem 1rem
+  margin .3rem .5rem .3rem 0
+  radius $radius
+  font inherit
+  cursor pointer
+
+button:hover
+  bg $accent
+  border-color $accent
+
+input
+  padding .7rem .9rem
+  border 1px solid $line
+  radius $radius
+  font inherit
+  bg $panel
+  width 100%
+  max-width 360px
+  margin 1rem 0
+
+ul
+  border 1px solid $line
+  bg $panel
+  padding 1rem 1rem 1rem 2rem
+  radius $radius
+
+.person-row
+  border 1px solid $line
+  bg $panel
+  padding .65rem 1.1rem
+  margin .5rem 0
+  radius $radius
+  display flex
+  gap .6rem
+  align-items baseline
+  flex-wrap wrap
+
+#paged
+  border 1px dashed $line
+  bg $panel
+  padding .4rem 1.2rem 1.2rem
+  margin 1rem 0
+  radius $radius

package/site/pages/loops.wd

@@ -0,0 +1,86 @@
+---
+title: Loop ergonomics
+---
+
+@include /nav.wd
+
+<main>
+
+# Loop ergonomics
+
+One loop, fully equipped. `@loop` gains `sort by`, `offset`, `limit`, `reverse`,
+an `@empty` branch, and per-row meta variables (`{ $number }`, `{ $first }`,
+`{ $last }`, `{ $count }`) — all in plain Markdown, all reactive when the source
+or a clause argument is `:state`.
+
+:state people = [{"id": 1, "name": "Ada", "age": 36}, {"id": 2, "name": "Cyrus", "age": 71}, {"id": 3, "name": "Bao", "age": 29}, {"id": 4, "name": "Dax", "age": 52}, {"id": 5, "name": "Esme", "age": 44}]
+:state sortOffset = 0
+:state pageSize = 2
+:state query = ""
+:state recent = [{"id": 1, "label": "Item 1"}, {"id": 2, "label": "Item 2"}, {"id": 3, "label": "Item 3"}, {"id": 4, "label": "Item 4"}, {"id": 5, "label": "Item 5"}]
+
+## Sorted, numbered, with first / last markers
+
+`sort by p.age desc` orders the eldest first. Each row reads its position from
+the loop meta vars: `{ $number }` is the 1-based index, and `:if $first` /
+`:if $last` light up only on the boundary rows.
+
+@loop people into p sort by p.age desc offset sortOffset
+::: card .person-row
+**{ $number }. { p.name }** — age { p.age }
+:if $first
+(first)
+:endif
+:if $last
+(last)
+:endif
+:::
+@endloop
+
+The list above is sorted oldest-first. `offset` is wired to a `:state`, so a
+button can slide the window without a reload:
+
+:button "Sort: skip the eldest" -> sortOffset = 1
+:button "Reset order" -> sortOffset = 0
+
+## Reactive paging with `limit`
+
+`limit pageSize` reads a `:state` value, so paging is just a button that bumps
+the number. The runtime re-slices the same loop in place — no extra request, no
+reload.
+
+::: section #paged
+@loop people into p limit pageSize
+::: card .person-row
+{ p.name } — age { p.age }
+:::
+@endloop
+
+:button "Show more" -> pageSize += 2
+:button "Collapse" -> pageSize = 2
+:::
+
+## `where` + `@empty`
+
+`where` filters live as you type, and `@empty` renders the moment the filtered
+set hits zero rows — the one place a loop gets to say "nothing here":
+
+:bind query placeholder="Search people…"
+
+@loop people into p where p.name contains query
+::: card .person-row
+{ p.name }
+:::
+@empty
+No matches.
+@endloop
+
+## `reverse` flips the source order
+
+No sort key needed — `reverse` walks the list back to front:
+
+@loop recent into r reverse
+- { r.label }
+@endloop
+
+</main>