@zvndev/darkmown 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.
+
+- **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.

package/README.md

@@ -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
@@ -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
 ```
@@ -117,9 +121,70 @@ 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. 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 +193,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
 ```
@@ -177,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
@@ -198,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
@@ -213,7 +421,7 @@ Set `window.wd.debug = true` (it defaults to `false`) to log any `:computed` or
 
 ## 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

@@ -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)
 
@@ -56,23 +56,31 @@ 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.
-- 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.9.0",
+  "version": "0.11.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -17,9 +17,12 @@
     "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"
+    "prepublishOnly": "npm test",
+    "smoke": "node scripts/smoke-consumer.mjs"
   },
   "files": [
     "src",
@@ -48,7 +51,7 @@
     "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/_/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/_/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

@@ -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 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. `: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/index.wd

@@ -166,4 +166,3 @@ Darkmown itself was built by a small agent team. The board below is a live `@loo
 @include /sprint-loop.wd
 
 </main>
-</content>