@zvndev/darkmown 0.20.0 → 1.0.0

package/AGENTS.md

@@ -7,7 +7,7 @@ Darkmown is a Markdown-native web framework. You build sites by writing `.md` an
 - `.md` files are plain CommonMark. Directives stay inert text.
 - `.wd` files are the same Markdown **plus directives** (state, loops, conditionals, includes, forms).
 - To make a `.md` page interactive, **rename it to `.wd`**. ⚠️ Renaming means the old `.md` is **gone** — never leave both `index.md` and `index.wd`, that is a fatal `Duplicate route` build error. Upgrade = delete the `.md`, create the `.wd`.
-- Static pages ship **zero** JavaScript; a page loads the ~5.7 KB gzipped runtime (CI-enforced under 6 KB) only if it declares reactive behavior.
+- Static pages ship **zero** JavaScript; a page loads the ~7.4 KB gzipped runtime (CI-enforced under 8 KB) only if it declares reactive behavior.
 
 ## Project layout & routing
 

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 1.0.0 — 2026-06-27
+
+The 1.0 release. The directive surface is now stable, and this version closes the biggest "I'd have to drop to raw HTML/JS for that" gaps an audit found — display formatting, time, an explicit theme toggle, live table sort, media, and a real escape hatch — while holding the zero-JS-by-default promise. Six additions, all either compile-time or sharing the one runtime, which moves from ~5.8 KB to **~7.4 KB gzipped**; the CI budget is raised 6 KB → **8 KB** to match (still un-minified, fully commented). No source-level breaking changes: existing `.wd` pages compile and behave identically.
+
+- **Format pipes — `{ value | name:arg }`.** Shape a value for display with a Liquid/Angular-style pipe, chainable and argument-taking: `{ price | money }`, `{ joinedAt | date:"medium" }`, `{ bio | truncate:80 }`. The whitelist covers `money` / `number` / `percent` / `round`, `date` / `time` / `datetime` (Intl-backed), `upper` / `lower` / `capitalize`, `truncate` / `trim`, `pluralize`, and `default`. Pipes fold at build time on static values (zero-JS) and re-apply on every render for `:state`/`:store` bindings — same syntax. There is deliberately **no relative "time ago"** formatter, so builds stay reproducible. An unknown pipe is a compile error with the valid list.
+- **Aggregates — `sum` / `avg` / `min` / `max` / `count`.** Usable both in `:computed` (`:computed total = sum(cart, price)`) and as pipes over a list (`{ cart | count }`, `{ cart | sum:"price" | money }`). The field argument is a bare row key. This is the first time `:computed` can roll up a list — previously a hard gap that forced hand-written JS.
+- **Timers — `:every <duration> -> <actions>`.** The one piece of time the framework owns: `:every 10s -> board refetch`, `:every 1s -> secs++`. Durations are `ms`/`s`/`m`; actions are the `:button`/`:effect` vocabulary. Intervals **pause while the tab is hidden** and resume on return, so a backgrounded dashboard stops firing requests.
+- **Manual theme toggle — `:theme`.** Declare `:theme` once and drive it with buttons (`:button "Dark" -> theme = "dark"`); it registers a durable `theme` store and reflects onto `<html data-theme>`. A single `tokens dark` block now compiles to **both** `:root[data-theme="dark"]` (the toggle) and the OS `prefers-color-scheme` media query (scoped to `:not([data-theme="light"])`), so one palette powers OS-auto and the manual switch. `"auto"` clears the attribute and follows the OS again.
+- **Reactive table sort.** `@loop … sort by { sortKey } { sortDir }` — the sort field *and* direction can each be a `{ state }` reference, so a clickable column header re-sorts the table live with no JavaScript. Drives the new Ledger demo.
+- **Media — `:video` / `:audio` / `:embed`.** Three compile-time-only directives (zero `data-wd-*`, so a media page stays zero-JS). `:video`/`:audio` emit a hardened HTML5 player with whitelisted flags/attrs and sane defaults (`preload="metadata"`, `controls`, `autoplay`⇒`muted`); `:embed` rewrites a YouTube/Vimeo URL to its no-cookie/player form in a responsive lazy `16/9` iframe. The shipped CSP now pre-authorizes exactly those two embed origins plus `media-src 'self' https:`, so embeds and remote media work out of the box on the bundled server, Cloudflare `_headers`, and Vercel.
+- **A real escape hatch — `wd.subscribe`.** `window.wd` gains `subscribe(key, cb)` (primes immediately, then fires on every settled change, returns an unsubscribe), joining `get`/`set`/`state`/`render`. This is the bridge for colocated `.js` "behaviors" — the gestural layer the framework deliberately omits (keyboard, drag/touch, canvas). The new Swiper demo is a draggable, keyboard-navigable carousel built entirely on it: the framework owns the `slide` state, dots, and readout declaratively; the behavior owns the gestures and transition.
+- **Hardening.** A multi-line `:state`/`:store` value (e.g. an array opened on the directive line and continued below) is now a clear compile error instead of silently storing the partial `"["` string — these directives take a single-line value. New demos: **Ledger** (sortable expense table), **Swiper** (escape-hatch carousel), and **Media**. The Folio cart now totals with `sum` + `| money`; Pulse live-refreshes with `:every`.
+
 ## 0.20.0 — 2026-06-26
 
 Engineering hardening: a real programmatic API, plus a gold-standard pass on tooling, tests, and internals. No behavior change for existing sites — the runtime is byte-for-byte the same (~5.8 KB gzipped).

package/README.md

@@ -7,7 +7,19 @@
 
 **[darkmown.com](https://darkmown.com)** · Markdown that runs.
 
-Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~5.8 KB gzipped, CI-enforced under 6 KB.
+Darkmown is a Markdown-native web framework. Two formats, one rule: `.md` stays plain CommonMark forever, and renaming a file to `.wd` ("whateverdown") is what unlocks directives — includes, loops, state, conditionals, and sections. Static pages ship **zero** framework JavaScript; reactive pages share one runtime around ~7.4 KB gzipped, CI-enforced under 8 KB.
+
+## Showcase
+
+Five complete apps, each a readable `.wd` file — see them at **[darkmown.com/showcase](https://darkmown.com/showcase/)**:
+
+- **[Folio](https://darkmown.com/folio/)** — a boutique storefront whose cart persists across pages, reloads, and browser tabs (`:store`), with live search and a checkout form.
+- **[Pulse](https://darkmown.com/pulse/)** — a service dashboard driven by `:fetch`: loading / error / empty states, live refresh (`:every`), and status badges, with no hand-written JavaScript.
+- **[Forge](https://darkmown.com/forge/)** — a plan configurator where `:computed` recomputes the price as you toggle features and seats, with conditional upsell hints.
+- **[Compass](https://darkmown.com/compass/)** — a product-finder quiz: a branching state machine expressed entirely as `:if` steps over scored answers.
+- **[Ledger](https://darkmown.com/ledger/)** — a spreadsheet-grade expense table: clickable-header reactive sort, a live filter, running totals via `sum`/`avg`/`max`, `| money`/`| date` format pipes, and a `:theme` toggle.
+
+Plus focused feature demos: a draggable, keyboard-navigable **[Swiper](https://darkmown.com/carousel/)** (the `wd.subscribe` escape hatch) and a zero-JS **[Media](https://darkmown.com/media/)** page (`:video` / `:audio` / `:embed`).
 
 ## Quick start
 
@@ -52,7 +64,7 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 - Files or folders starting with `.`, `-`, or `_` are hidden from routing.
 - `site/_` is the include shelf for `@include /name.wd`.
 - Matching `page.skin` and `page.js` colocate styling and behavior by basename.
-- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~5.8 KB gzipped, CI-enforced under 6 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~7.4 KB gzipped, CI-enforced under 8 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -65,6 +77,24 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 - Anything else stays literal text — braces in prose never break a page or pull in the runtime.
 - Build-time values also resolve **inside a link or image destination** — `[{ item.label }]({ item.url })` or `![{ p.alt }]({ p.src })` — so an `@loop` can drive an `href`/`src` and the page stays static. (Reactive `:state` cannot live in a destination.)
 
+### Format pipes — `{ value | name:arg }`
+
+Shape a value for display with a pipe, Liquid/Angular style: `{ price | money }`, `{ joinedAt | date:"medium" }`, `{ ratio | percent }`. Pipes **chain** left to right (`{ name | trim | capitalize }`) and take literal arguments (`{ total | money:"EUR" }`, `{ bio | truncate:80 }`). They work in static prose (folded at build time, zero-JS) and on live `:state`/`:store` bindings (re-applied on every render) — identical syntax either way. The pipe list is a fixed whitelist compiled to safe calls; there is no custom-function hook and nothing is `eval`'d.
+
+| Pipe | Example | Result |
+|---|---|---|
+| `money[:currency[:locale]]` | `{ 89 \| money }` | `$89.00` |
+| `number[:decimals]` | `{ 1234.5 \| number }` | `1,234.5` |
+| `percent[:decimals]` | `{ 0.082 \| percent }` | `8%` |
+| `round[:decimals]` | `{ 3.14159 \| round:2 }` | `3.14` |
+| `date` / `time` / `datetime` `[:style]` | `{ "2026-06-22" \| date:"medium" }` | `Jun 22, 2026` |
+| `upper` / `lower` / `capitalize` | `{ "draft" \| capitalize }` | `Draft` |
+| `truncate:n` / `trim` | `{ bio \| truncate:80 }` | `…the first 80 chars…` |
+| `pluralize:"item"[:"plural"]` | `{ 3 \| pluralize:"item" }` | `3 items` |
+| `default:"—"` | `{ missing \| default:"—" }` | `—` |
+
+The five **aggregates** double as pipes over a list — `{ cart \| count }`, `{ cart \| sum:"price" \| money }`, plus `avg` / `min` / `max` — and `join:", ":"name"` flattens a list of rows to a string. `date`/`time`/`datetime` are `Intl`-backed (`short` / `medium` / `long`); there is deliberately **no relative "time ago"** formatter, so builds stay byte-for-byte reproducible. An unknown pipe name is a compile error with the valid list.
+
 ## Frontmatter
 
 YAML-style `key: value` frontmatter between `---` fences. Values are strings, plus inline arrays:
@@ -166,6 +196,7 @@ Shape a loop without writing JavaScript. Clauses come in a fixed order after `in
 ```
 
 - `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.
+- **Reactive sort** — the field *and* the direction can each be a `{ state }` reference, so a clickable column header re-sorts the table live without any JavaScript: `sort by { sortKey } { sortDir }`. Drive them with `:state sortKey = "amount"` / `:state sortDir = "desc"` and `:button "Amount" -> sortKey = "amount" ; sortDir = "desc"`. The bare `{ sortKey }` resolves to a field on the loop item at render time.
 - `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:
 
@@ -369,6 +400,35 @@ Values are literals: a `"string"`, number, `true`/`false`/`null`, or inline JSON
 
 > **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.
 
+### Computed values — `:computed`
+
+`:computed name = <expression>` derives state from other state with a compile-time-checked expression — names, numbers, arithmetic (`+ - * /`), comparisons, and the five **aggregates** over a list: `sum(list, field)`, `avg(list, field)`, `min(list, field)`, `max(list, field)`, and `count(list)`. It recomputes whenever an input changes and reads like any other binding (so it pairs naturally with [format pipes](#format-pipes--value--namearg)):
+
+```wd
+:store cart = [{"price": 89}, {"price": 12}]
+:computed subtotal = sum(cart, price)
+:computed tax      = subtotal * 0.08
+:computed total    = subtotal + tax
+
+Subtotal: { subtotal | money } · Tax: { tax | money } · **{ total | money }**
+```
+
+The aggregate's field argument is a bare key on each row (`price`, not `item.price`). There are no function calls beyond the five aggregates and no property access beyond dotted state paths — anything richer belongs in a colocated `.js` behavior.
+
+### Timers — `:every`
+
+`:every <duration> -> <actions>` runs a `:button`-style action on an interval — the one piece of time the framework owns. Durations are `<n>ms` / `<n>s` / `<n>m`, and the actions are the same `;`-chained vocabulary as `:button`/`:effect` (including `name refetch` to re-run a `:fetch`):
+
+```wd
+:fetch board from "/status.json"
+:every 10s -> board refetch        # live-refresh a dashboard
+
+:state secs = 0
+:every 1s -> secs++                # a ticking counter
+```
+
+Intervals **pause while the tab is hidden** (via `visibilitychange`) and resume on return, so a backgrounded dashboard stops firing requests and draining battery.
+
 ### Effects — `:effect`
 
 `:effect <watched> -> <actions>` runs actions whenever a watched state path changes. The actions are the same `:button` vocabulary (`;`-chained) — this is the escape hatch for side effects beyond `:computed` (which derives state) and `:fetch` deps (which auto-refetch):
@@ -542,7 +602,7 @@ Fetched data and a form live happily on the same page:
 - `: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.
 - Field directives: `:input`, `:textarea name [rows=N]`, `:select name`, `:checkbox name`, and `:radio name` (the last three take `- Label` option lines) all capture into `:form into` state the same way. A `:checkbox` group captures **every checked value as an array**; a `:radio` group captures a single value. Each derives a non-visual `aria-label` from its placeholder, else a humanized field name, unless you supply `aria-label`/`aria-describedby`.
 - `: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).
+- `:computed total = items.length * 4` derives state from state with a compile-time-checked expression — names, numbers, arithmetic, comparisons, and list aggregates (`sum`/`avg`/`min`/`max`/`count`). See [Computed values](#computed-values--computed).
 - `:if item.path` works inside reactive loops for per-row branches, and nests — an inner `:if` resolves after the outer branch and stays reactive.
 
 ## Inline attributes
@@ -556,6 +616,21 @@ A trailing `{.class .class #id}` attaches classes / an id to the inline element
 
 The block must follow the element with no space, and works on links, images, emphasis, and inline code. It never collides with `{ name }` interpolation — an interpolation always starts with a name, never a `.` or `#`.
 
+## Media — `:video`, `:audio`, `:embed`
+
+*New in 1.0.* Three one-line directives replace hand-written `<video>` / `<iframe>` markup. They are **compile-time only** — they emit no `data-wd-*`, so a media-only page still ships **zero** framework JavaScript.
+
+```wd
+:video /clip.mp4 poster=/clip.jpg controls
+:audio /track.mp3 controls
+:embed https://youtu.be/aqz-KE-bpKQ title="Big Buck Bunny"
+```
+
+- **`:video` / `:audio`** compile to a hardened HTML5 player. `preload="metadata"` and `controls` are added by default; flags (`controls`, `autoplay`, `loop`, `muted`, `playsinline`) and attributes (`poster`, `width`, `height`, `preload`) are validated against a per-element whitelist, and `autoplay` silently implies `muted` (browsers block sound-on autoplay). The `src`/`poster` URLs run through the same scheme guard as `:fetch` — relative or `http(s)` only.
+- **`:embed`** rewrites a YouTube or Vimeo URL to its **no-cookie / player** form, wraps it in a responsive `16/9` box, and marks the iframe `loading="lazy"` with a locked-down `referrerpolicy`. Any other `http(s)` URL becomes a generic lazy iframe. Add `title="…"` for the accessible name.
+
+Darkmown's shipped CSP pre-authorizes exactly the two embed origins (`youtube-nocookie.com`, `player.vimeo.com`) and `media-src 'self' https:`, so embeds and remote media work out of the box on the bundled server, Cloudflare `_headers`, and Vercel.
+
 ## Dark mode — `tokens dark`
 
 *New in 0.19.0.* A colocated `.skin` file already declares its palette in a `tokens` block (`name value` pairs referenced elsewhere as `$name`). Add a second `tokens dark` block to override any of those tokens under the visitor's OS dark preference — it compiles to a `@media (prefers-color-scheme: dark) :root { … }` rule, so the page follows the system theme with **zero JavaScript**.
@@ -574,11 +649,46 @@ page
   color $ink
 ```
 
-The `tokens dark` values override the matching base tokens only when the OS reports a dark preference; the rules below keep referencing the same `$paper` / `$ink`. The base `tokens` block stays the light default, so a skin with no `tokens dark` block is unchanged.
+A single `tokens dark` block powers **both** theming paths: it compiles to `:root[data-theme="dark"] { … }` (the manual toggle below) **and** `@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { … } }` (the OS preference, unless a visitor has explicitly forced light). The base `tokens` block stays the light default, so a skin with no `tokens dark` block is unchanged.
+
+### Manual toggle — `:theme`
+
+*New in 1.0.* For an explicit light/dark switch alongside (or instead of) the OS preference, declare `:theme` once and drive it with ordinary buttons. It registers a durable `theme` store and reflects its value onto `<html data-theme="…">`:
+
+```wd
+:theme
+:button "Auto"  -> theme = "auto"
+:button "Light" -> theme = "light"
+:button "Dark"  -> theme = "dark"
+```
+
+Because `tokens dark` already emits the `[data-theme="dark"]` rule, **no extra skin block is needed** — the same palette drives the toggle. `"light"` forces the light palette even under OS dark; `"auto"` clears the attribute and follows the OS again; `theme` persists across reloads and tabs like any `:store`. (`:theme name = "light"` renames the store and seeds a different default. The older `tokens [data-theme=dark]` block — a manual-only override — still works for bespoke setups.)
 
 ## The escape hatch
 
-Reactive pages expose `window.wd` — `wd.get(key)`, `wd.set(key, value)`, `wd.state`, `wd.render()` — so colocated `.js` can do anything the directives can't. Section-scoped keys are addressed as `sectionId:name`.
+Reactive pages expose `window.wd` so a colocated `.js` file can do anything the directives deliberately don't — keyboard, drag/touch, canvas, charts, maps:
+
+| Method | Purpose |
+|---|---|
+| `wd.get(key)` | read a state value |
+| `wd.set(key, value)` | write it and re-render |
+| `wd.subscribe(key, cb)` | run `cb(value)` now and on every settled change; returns an unsubscribe |
+| `wd.state` | the live state object |
+| `wd.render()` | force a render |
+
+Section-scoped keys are addressed as `sectionId:name`. The bridge for "behaviors" is `subscribe` — it primes the callback immediately, then fires whenever the value settles, so an imperative widget stays in lockstep with declarative state:
+
+```js
+// index.js, colocated beside the page. Loads after the runtime, so wd is ready.
+const track = document.querySelector("[data-track]");
+wd.subscribe("slide", (i) => {            // framework state → imperative view
+  track.style.transform = `translateX(${-i * 100}%)`;
+});
+document.querySelector("[data-next]")
+  .addEventListener("click", () => wd.set("slide", wd.get("slide") + 1));
+```
+
+That is the whole contract: the framework reconciles state, text, classes, and loops; your behavior owns the gestures; they meet at one shared key. (See the [Swiper demo](https://darkmown.com/carousel/) — a draggable, keyboard-navigable carousel built exactly this way.)
 
 Set `window.wd.debug = true` (it defaults to `false`) to log any `:computed` or `@loop … where` expression that fails to evaluate to the console — useful while authoring reactive pages.
 

package/docs/spec-alignment.md

@@ -6,7 +6,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 
 - **Markdown-first authoring:** `.md` is strict CommonMark rendered by a real parser (markdown-it); `.wd` is the same Markdown plus first-party directives. Renaming the file is the upgrade path — extensions genuinely gate functionality.
 - **Content tree over components:** routing, includes, and repeated fragments are file/document based instead of React-style components.
-- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~5.7 KB gzipped, CI-enforced below the 6 KB target).
+- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~7.4 KB gzipped, CI-enforced below the 8 KB target).
 - **No virtual DOM:** state changes patch direct DOM bindings, conditional regions, and keyed loop regions.
 - **Keyed list patching:** reactive loops reconcile by item key (`id`/`key`/value) instead of re-rendering the region.
 - **Sections with scoped state:** `::: section #id .class` containers scope `:state`; bindings and actions resolve through the nearest scope chain.
@@ -93,6 +93,19 @@ The post-8/10-review sprint: one reactive-loop capability, a deploy-hardening la
 - **Dark-mode theming — `tokens dark`:** a `.skin` file may add a `tokens dark` block alongside its base `tokens`; the dark tokens compile to `@media (prefers-color-scheme: dark) :root { … }`, overriding the matching base tokens under the visitor's OS dark preference. Rules keep referencing the same `$name` tokens, so dark mode is a palette swap with **zero JavaScript** — consistent with the existing zero-JS `.skin` output. A skin with no `tokens dark` block is unchanged.
 - **Test backfill + compile-error line numbers:** the sprint backfilled runtime/compiler tests for the new surface, and compile errors now carry the offending **line number** alongside the file path and corrective suggestion. **Honest caveat:** this entry documents the intended sprint scope; the exact assertion count and the precise error-message format are owned by the test/compiler tracks and were not verified from this docs track.
 
+## Stage 16 additions (2026-06-27, v1.0.0)
+
+The 1.0 release: a value layer, a time primitive, an explicit theme toggle, reactive table sort, media, and a first-class escape hatch — the gaps an audit flagged as "drop to raw HTML/JS." All compile-time or shared-runtime; the runtime moved from ~5.8 KB to ~7.4 KB gzipped and the CI budget was raised 6 KB → **8 KB** to match (still un-minified). No source-level breaking changes.
+
+- **Format pipes — `{ value | name:arg }`:** a fixed formatter whitelist (`money`, `number`, `percent`, `round`, `date`/`time`/`datetime`, `upper`/`lower`/`capitalize`, `truncate`/`trim`, `pluralize`, `default`) applied via chainable, argument-taking pipes. Static-value pipes fold at build time (zero-JS); `:state`/`:store` bindings re-apply on every render via a compact runtime mirror that is **parity-tested** against the compiler's formatter table. Validated to a whitelist, never `eval`'d; an unknown pipe is a compile error. **Honest caveat:** there is deliberately **no** relative/"time ago" formatter — it would make builds non-reproducible — and pipes shape values for display only (no arbitrary expressions).
+- **Aggregates — `sum`/`avg`/`min`/`max`/`count`:** usable in `:computed` (`sum(list, field)`) and as list pipes (`{ cart | count }`, `{ cart | sum:"price" | money }`). In `:computed` they are pre-parsed to a whitelisted `A("name", S("key"), "field")` call before the existing function-call rejection, so the expression grammar stays closed. The field argument is a bare row key.
+- **Timers — `:every <duration> -> <actions>`:** an interval driver (`ms`/`s`/`m`) running the `:button`/`:effect` action vocabulary; supports `name refetch`. Intervals pause on `visibilitychange` (hidden tab) and resume on return. **Honest caveat:** it is wall-clock interval only — no cron syntax, no animation-frame scheduling, no per-element timers.
+- **Manual theme toggle — `:theme`:** registers a durable `theme` store and a `data-wd-theme` reflect marker; the runtime writes the value onto `<html data-theme>`. A single `tokens dark` block now emits **both** `:root[data-theme="dark"]` and `@media (prefers-color-scheme: dark) :root:not([data-theme="light"])`, so one palette powers OS-auto and the manual toggle; `"auto"` clears the attribute. The older bracketed `tokens [data-theme=dark]` manual-only override still compiles.
+- **Reactive table sort:** `@loop … sort by { sortKey } { sortDir }` accepts a `{ state }` reference for the sort field and/or direction (emitted as a `key:` prefix the runtime resolves per render), so a clickable header re-sorts live. Build-time `sort by item.field [asc|desc]` is unchanged.
+- **Media — `:video` / `:audio` / `:embed`:** compile-time only (no `data-wd-*`; a media-only page stays `runtime: false`). `:video`/`:audio` emit a hardened HTML5 player with a per-element flag/attr whitelist and defaults (`preload="metadata"`, `controls`, `autoplay`⇒`muted`); URLs use the `:fetch` scheme guard. `:embed` rewrites YouTube/Vimeo to the no-cookie/player origin in a lazy responsive `16/9` iframe with locked `referrerpolicy`. The shipped CSP gains `media-src 'self' https:` and a `frame-src` scoped to exactly `youtube-nocookie.com` + `player.vimeo.com` (no wildcard), mirrored across `serve`, `dist/_headers`, and `vercel.json`.
+- **Escape hatch — `window.wd.subscribe(key, cb)`:** primes the callback immediately, then fires on every settled change, returning an unsubscribe; joins `get`/`set`/`state`/`render`. The bridge for colocated `.js` "behaviors" (keyboard, drag/touch, canvas) — the Swiper demo is a draggable, keyboard-navigable carousel where the framework owns `slide`/dots/readout declaratively and the behavior owns the gestures. **Honest caveat:** this is an imperative bridge, not a reactive-templating extension; a behavior reaching past `wd.*` into private runtime internals is unsupported.
+- **Hardening:** a multi-line `:state`/`:store`/`:theme` value (a literal opened on the directive line, continued below) is now a located compile error instead of silently storing the partial `"["` string — these directives take a single-line value. Quote bracketed literal text to bypass the guard.
+
 ## Stage 13 additions (2026-06-23, v0.17.0)
 
 - **`:checkbox` and `:radio` field groups:** `:checkbox name` / `:radio name` (with `- Label` option lines) render a labelled `role="group"` / `role="radiogroup"` of `<input>`s that share one `name`, each wrapped in its own `<label>` and deriving an aria-label like the other fields. A `:checkbox` group is marked `data-wd-multi` so the runtime's submit handler collects **every** checked value into an array (`FormData.getAll`) instead of collapsing to the last — the one runtime change (compile-time only otherwise; shipped runtime stays ~5.8 KB). A `:radio` group captures a single value like `:input`. Closes the multi-select / single-choice gap that previously forced raw HTML and lost `:form into` capture.
@@ -116,7 +129,7 @@ Four progressive-disclosure capabilities plus an assets and a security change. T
 
 ## 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`, `:store`, `:computed`, `:effect`, `:button`, `:bind`, `:if`/`:else if`/`:else`/`:endif`, `:fetch` (with `headers`/`refresh`), `:form`/`:input`/`:submit`, `@loop`/`@empty`/`@endloop` (with `where`, `sort by`, `reverse`, `offset`, `limit`), `@include`, and `::: section` (with reactive `.class when`).
+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`, `:effect`, `:every`, `:theme`, `:button`, `:bind`, `:if`/`:else if`/`:else`/`:endif`, `:fetch` (with `headers`/`refresh`), `:form`/`:input`/`:submit`, `:video`/`:audio`/`:embed`, `@loop`/`@empty`/`@endloop` (with `where`, `sort by` — including reactive `{ state }` keys —, `reverse`, `offset`, `limit`), `@include`, and `::: section` (with reactive `.class when`). Interpolation supports **format pipes** (`{ value | name:arg }`) and `:computed`/list-pipe **aggregates** (`sum`/`avg`/`min`/`max`/`count`). The runtime escape hatch is `window.wd` (`get`/`set`/`subscribe`/`state`/`render`).
 
 ## Still missing from the full vision
 
@@ -128,4 +141,4 @@ The compiler recognizes three directives — `:note`, `:try`, and `:sprint` —
 
 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.
 
-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.
+As of **v1.0.0** the public npm package is published as `@zvndev/darkmown`, the project is MIT licensed, and the directive surface is stable. The 1.0 release closes the audit-flagged display/time/theme/sort/media/escape-hatch gaps; the remaining items above are explicitly scoped as post-launch product/distribution work rather than missing core claims.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.20.0",
+  "version": "1.0.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -18,7 +18,7 @@
   "types": "./types/index.d.ts",
   "scripts": {
     "build": "node src/cli.js build",
-    "runtime:size": "node -e \"const fs=require('fs'),zlib=require('zlib'); const size=zlib.gzipSync(fs.readFileSync('dist/__wd/runtime.js')).length; console.log('shipped runtime gzipped: '+size+' bytes (budget: 6144)'); if (size >= 6144) process.exit(1)\"",
+    "runtime:size": "node -e \"const fs=require('fs'),zlib=require('zlib'); const size=zlib.gzipSync(fs.readFileSync('dist/__wd/runtime.js')).length; console.log('shipped runtime gzipped: '+size+' bytes (budget: 8192)'); if (size >= 8192) process.exit(1)\"",
     "dev": "node src/cli.js dev",
     "test": "node --test tests/*.test.js",
     "test:cov": "node scripts/test-coverage-gate.mjs 100",
@@ -44,7 +44,7 @@
     "src",
     "types",
     "site",
-    "!site/_/og.png",
+    "!site/_/og*.png",
     "docs/cli.md",
     "docs/spec-alignment.md",
     "AGENTS.md",

package/site/_/base.skin

@@ -0,0 +1,372 @@
+/* ===================================================================
+   Darkmown design system — the refreshed brand foundation.
+   Warm, literary, premium. Serif for prose, system sans for chrome,
+   a refined mono for code. Ships zero JS; dark mode is OS-driven via
+   `tokens dark` (a pure CSS media query — no flash, no toggle script).
+   Every refreshed page and demo app includes this via /base.wd.
+   =================================================================== */
+
+tokens
+  ink #1c1814
+  ink-soft #4b4239
+  muted #756a5d
+  faint #9b9082
+  paper #faf8f3
+  paper-2 #f4f0e7
+  sunk #efe9dc
+  panel #ffffff
+  line #e7e1d4
+  line-soft #f0ebe0
+  accent #0f6b5e
+  accent-deep #0a4f45
+  accent-soft #e3f0ec
+  warm #b8462e
+  warm-soft #f8eae3
+  gold #b6822b
+  code-bg #1b2420
+  code-ink #e9efe7
+  code-line #2c3b34
+  ring #0f6b5e
+  radius 12px
+  radius-sm 8px
+  radius-lg 20px
+
+tokens dark
+  ink #ece6db
+  ink-soft #c3bbab
+  muted #9a9081
+  faint #6f6657
+  paper #14110d
+  paper-2 #1a1612
+  sunk #221d17
+  panel #1e1913
+  line #2f281f
+  line-soft #261f18
+  accent #5ccab4
+  accent-deep #8fe0cf
+  accent-soft #16302a
+  warm #e88a6f
+  warm-soft #2c1f18
+  gold #d6a24e
+  code-bg #100d0a
+  code-ink #e4ebe2
+  code-line #2a231b
+  ring #5ccab4
+
+/* ── Reset & base ───────────────────────────────────────────────── */
+
+*
+  box-sizing border-box
+
+page
+  margin 0
+  font-family ui-serif, "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, Cambria, serif
+  font-size 18px
+  line-height 1.65
+  color $ink
+  bg $paper
+  -webkit-font-smoothing antialiased
+  text-rendering optimizeLegibility
+
+::selection
+  bg $accent-soft
+  color $accent-deep
+
+/* ── Typography ─────────────────────────────────────────────────── */
+
+h1, h2, h3, h4
+  line-height 1.1
+  letter-spacing -.012em
+  color $ink
+  font-weight 600
+
+h1
+  font-size clamp(2.5rem, 6vw, 4.5rem)
+  letter-spacing -.025em
+  margin .2em 0 .35em
+
+h2
+  font-size clamp(1.6rem, 3vw, 2.25rem)
+  margin 2.4em 0 .6em
+
+h3
+  font-size 1.3rem
+  margin 1.8em 0 .4em
+
+p
+  margin 1em 0
+  max-width 68ch
+
+a
+  color $accent
+  text-underline-offset 2px
+  text-decoration-thickness 1px
+
+a:hover
+  color $accent-deep
+
+strong
+  font-weight 650
+  color $ink
+
+hr
+  border 0
+  border-top 1px solid $line
+  margin 3rem 0
+
+small, .small
+  font-size .82rem
+  color $muted
+
+/* Chrome (nav, buttons, labels, badges) leans on a clean sans for a
+   modern editorial contrast against the serif prose. */
+.topnav, .btn, .eyebrow, .pill, .tag, .badge, .kbd, .sitefooter, .source-reveal summary
+  font-family system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+
+/* ── Layout ─────────────────────────────────────────────────────── */
+
+main
+  max-width 940px
+  margin 0 auto
+  padding 0 1.5rem 5rem
+
+.wide
+  max-width 1140px
+
+.eyebrow
+  display inline-block
+  text-transform uppercase
+  letter-spacing .14em
+  font-size .74rem
+  font-weight 600
+  color $accent
+  margin 0 0 .35rem
+
+/* ── Buttons ────────────────────────────────────────────────────── */
+
+.btn
+  display inline-flex
+  align-items center
+  gap .5rem
+  margin .4rem .5rem .4rem 0
+  padding .7rem 1.15rem
+  font-size .95rem
+  font-weight 550
+  line-height 1
+  color $ink
+  bg $panel
+  border 1px solid $line
+  radius 999px
+  text-decoration none
+  cursor pointer
+  transition transform .12s ease, box-shadow .12s ease, background .12s ease
+
+.btn:hover
+  transform translateY(-1px)
+  box-shadow 0 6px 18px -8px rgba(28,24,20,.35)
+
+.btn.primary
+  bg $accent
+  color #fff
+  border-color $accent
+
+.btn.primary:hover
+  bg $accent-deep
+  color #fff
+
+.btn.warm
+  bg $warm
+  color #fff
+  border-color $warm
+
+.btn.ghost
+  bg transparent
+
+/* ── Cards & surfaces ───────────────────────────────────────────── */
+
+.card
+  bg $panel
+  border 1px solid $line
+  radius $radius
+  padding 1.4rem
+  box-shadow 0 1px 2px rgba(28,24,20,.04)
+
+.grid
+  display grid
+  gap 1.1rem
+
+.grid.cols-2
+  grid-template-columns repeat(2, 1fr)
+
+.grid.cols-3
+  grid-template-columns repeat(3, 1fr)
+
+.grid.auto
+  grid-template-columns repeat(auto-fit, minmax(240px, 1fr))
+
+@media (max-width: 760px)
+  .grid.cols-2, .grid.cols-3
+    grid-template-columns 1fr
+
+/* ── Pills, tags, badges ────────────────────────────────────────── */
+
+.pill, .tag
+  display inline-flex
+  align-items center
+  gap .35rem
+  font-size .72rem
+  font-weight 600
+  text-transform uppercase
+  letter-spacing .06em
+  padding .28rem .6rem
+  radius 999px
+
+.pill
+  bg $accent-soft
+  color $accent-deep
+
+.tag
+  bg $sunk
+  color $muted
+
+.kbd
+  font-family ui-monospace, "SF Mono", Menlo, monospace
+  font-size .8rem
+  padding .15rem .4rem
+  radius 6px
+  bg $panel
+  border 1px solid $line
+  color $ink-soft
+
+/* ── Callout (the demo :note directive renders <aside class="note">) ─ */
+
+.note, .callout
+  margin 1.6rem 0
+  padding 1rem 1.25rem
+  border 1px solid $line
+  border-left 3px solid $accent
+  bg $panel
+  radius $radius-sm
+  color $ink-soft
+  font-size .96rem
+
+/* ── Code ───────────────────────────────────────────────────────── */
+
+code
+  font-family ui-monospace, "SF Mono", Menlo, Consolas, monospace
+  font-size .88em
+  bg $sunk
+  color $accent-deep
+  padding .12rem .36rem
+  radius 6px
+
+h1 code, h2 code, h3 code
+  font-size .82em
+
+pre
+  bg $code-bg
+  color $code-ink
+  padding 1.2rem 1.35rem
+  margin 1.5rem 0
+  radius $radius
+  overflow-x auto
+  line-height 1.62
+  font-size .87rem
+  box-shadow inset 0 0 0 1px $code-line
+
+pre code
+  bg transparent
+  color inherit
+  padding 0
+  font-size 1em
+
+/* ── Tables ─────────────────────────────────────────────────────── */
+
+table
+  border-collapse collapse
+  width 100%
+  margin 1.5rem 0
+  font-size .95rem
+
+th
+  text-align left
+  padding .6rem .9rem
+  border-bottom 2px solid $line
+  color $muted
+  font-weight 600
+  font-size .82rem
+  text-transform uppercase
+  letter-spacing .04em
+
+td
+  padding .6rem .9rem
+  border-bottom 1px solid $line-soft
+
+blockquote
+  margin 1.6rem 0
+  padding .6rem 1.3rem
+  border-left 3px solid $accent
+  color $ink-soft
+  font-style italic
+
+/* ── "View source" reveal — the two-beat trick: a slick app, then the
+     Markdown it's made of. Wrap a fenced ```wd block in <details>. ── */
+
+.source-reveal
+  margin 1.5rem 0
+  border 1px solid $line
+  radius $radius
+  bg $panel
+  overflow hidden
+
+.source-reveal summary
+  cursor pointer
+  padding .85rem 1.1rem
+  font-size .9rem
+  font-weight 600
+  color $accent-deep
+  list-style none
+  display flex
+  align-items center
+  gap .5rem
+
+.source-reveal summary::-webkit-details-marker
+  display none
+
+.source-reveal summary::before
+  content "›"
+  font-size 1.1rem
+  transition transform .15s ease
+
+.source-reveal[open] summary::before
+  transform rotate(90deg)
+
+.source-reveal pre
+  margin 0
+  radius 0
+
+/* ── Footer ─────────────────────────────────────────────────────── */
+
+.sitefooter
+  border-top 1px solid $line
+  margin-top 4rem
+  padding 2.5rem 1.5rem
+  color $muted
+  font-size .9rem
+
+.sitefooter .foot-inner
+  max-width 940px
+  margin 0 auto
+  display flex
+  flex-wrap wrap
+  gap 1rem 2rem
+  align-items center
+  justify-content space-between
+
+.sitefooter a
+  color $muted
+  text-decoration none
+  margin-right 1.1rem
+
+.sitefooter a:hover
+  color $accent