@zvndev/darkmown 0.20.0 → 1.1.0

package/site/pages/compass/index.wd

@@ -0,0 +1,194 @@
+---
+title: Compass — find your match
+description: A guided product-finder quiz built in one Markdown file. Four questions advance a state machine with :if branching, accumulate scores with :button actions, and a :computed recommendation lands the perfect pick. Zero hand-written JavaScript.
+image: https://darkmown.com/__wd/media/og-compass.png
+transitions: true
+---
+
+@include /nav.wd
+@include /base.wd
+
+<style>@keyframes pop { 0% { transform: scale(0) rotate(-18deg); opacity: 0 } 100% { transform: scale(1) rotate(0); opacity: 1 } }</style>
+
+<main class="app-compass">
+
+:state step = 1
+:state calm = 0
+:state bold = 0
+:state budget = 0
+
+::: section #quiz .compass-stage
+
+::: compass-card .compass-card
+
+:if step <= 4
+
+::: compass-top .compass-top
+
+::: eyebrow .compass-eyebrow
+Question { step } of 4
+:::
+
+::: compass-rail .compass-rail .at-1 when step == 1 .at-2 when step == 2 .at-3 when step == 3 .at-4 when step == 4
+:::
+
+:::
+
+:endif
+
+:if step == 1
+
+## Where should it live?
+
+::: lead .compass-lead
+Picture the spot you'd reach for it most. That tells us a lot.
+:::
+
+::: answers .compass-answers
+:button "🛋️  A cozy nook to unwind" -> calm += 2; step++
+:button "🎉  The room where people gather" -> bold += 2; step++
+:button "🧺  Wherever — it should just be useful" -> budget += 2; step++
+:::
+
+:else if step == 2
+
+## What's the mood you're after?
+
+::: lead .compass-lead
+No wrong answers. Go with your gut.
+:::
+
+::: answers .compass-answers
+:button "🌙  Soft, calm, a little dreamy" -> calm += 2; step++
+:button "⚡  Lively, bold, turn it up" -> bold += 2; step++
+:button "🧘  Fresh and easy — no fuss" -> calm += 1; budget += 1; step++
+:::
+
+:else if step == 3
+
+## How does it earn its keep?
+
+::: lead .compass-lead
+The thing it has to nail before anything else.
+:::
+
+::: answers .compass-answers
+:button "✨  It sets the whole vibe" -> calm += 2; step++
+:button "🔊  It fills the room" -> bold += 2; step++
+:button "💧  It quietly makes the day nicer" -> calm += 1; budget += 1; step++
+:::
+
+:else if step == 4
+
+## And the budget?
+
+::: lead .compass-lead
+Last one — then we'll find your match.
+:::
+
+::: answers .compass-answers
+:button "🌱  Keep it gentle" -> budget += 3; step++
+:button "⚖️  A fair middle" -> budget += 1; step++
+:button "💎  Splurge for the right one" -> bold += 2; step++
+:::
+
+:else
+
+::: result .compass-result
+
+::: burst .compass-burst
+🎉
+:::
+
+::: eyebrow .compass-eyebrow .is-result
+Your match
+:::
+
+:if bold > calm and bold > budget
+
+# The Cove Speaker
+
+::: why .compass-why
+You're here to fill the room. The **Cove Speaker** throws warm, room-filling 360° sound out of a palm-sized shell — the heart of every gathering, turned all the way up.
+:::
+
+[Shop this →](/folio/){.compass-cta}
+
+:else if calm > bold and calm > budget
+
+# The Aurora Lamp
+
+::: why .compass-why
+You want a space that *feels* like something. The **Aurora Lamp** pours a warm, dimmable glow from a hand-turned oak base — the quiet centerpiece of your cozy nook.
+:::
+
+[Shop this →](/folio/){.compass-cta}
+
+:else if budget > calm and budget > bold
+
+# The Haven Diffuser
+
+::: why .compass-why
+You like things that quietly make the day nicer — without the splurge. The **Haven Diffuser** breathes a soft cedar-scented mist into the room, refillable and easy to love.
+:::
+
+[Shop this →](/folio/){.compass-cta}
+
+:else
+
+# The Isle Earbuds
+
+::: why .compass-why
+You're a little of everything — calm, bold, and practical. The **Isle Earbuds** go anywhere you do: active noise cancelling, a 30-hour case, and tap controls for whatever the day brings.
+:::
+
+[Shop this →](/folio/){.compass-cta}
+
+:endif
+
+::: restart .compass-restart
+:button "↺  Start over" -> step reset; calm reset; bold reset; budget reset
+:::
+
+:::
+
+:endif
+
+:::
+
+:::
+
+<details class="source-reveal">
+<summary>View source — it's Markdown</summary>
+
+```wd
+:state step = 1
+:state calm = 0
+:state bold = 0
+:state budget = 0
+
+:if step <= 4
+Question { step } of 4
+:endif
+
+:if step == 1
+## Where should it live?
+:button "🛋️  A cozy nook to unwind" -> calm += 2; step++
+:button "🎉  The room where people gather" -> bold += 2; step++
+:else if step == 2
+## What's the mood you're after?
+:button "🌙  Soft, calm, a little dreamy" -> calm += 2; step++
+... three more questions ...
+:else
+:if bold > calm and bold > budget
+# The Cove Speaker
+:else if calm > bold and calm > budget
+# The Aurora Lamp
+:endif
+:button "↺  Start over" -> step reset; calm reset; bold reset; budget reset
+:endif
+```
+
+</details>
+
+</main>

package/site/pages/docs/index.skin

@@ -1,39 +1,59 @@
-tokens
-  ink #171717
-  paper #fbfaf7
-  panel #ffffff
-  line #dedbd3
-  accent #16645a
-  muted #666158
-  radius 8px
-
-page
-  margin 0
-  font ui-serif, Georgia, Cambria, serif
-  color $ink
-  bg $paper
-  line-height 1.7
+/* Docs — layers on /base.wd (tokens, type, code, dark mode). Refined,
+   readable single-column reference. Only docs-specific layout here. */
 
-main
-  max-width 820px
-  margin 0 auto
-  padding 3rem 2rem 5rem
+main.docs
+  max-width 760px
 
-h1
-  font-size 3rem
-  line-height 1
-  margin 1rem 0
+.docs-hero
+  padding 2rem 0 1.5rem
+  margin-bottom 1rem
+  border-bottom 1px solid $line
+
+.docs-hero h1
+  margin .2rem 0 .5rem
+
+.docs-hero p
+  font-size 1.12rem
+  color $ink-soft
+  max-width 60ch
 
-h2
-  margin-top 2.4rem
-  padding-top 1.2rem
+/* Section headings get a quiet rule above them so the long page scans. */
+main.docs h2
+  margin-top 3rem
+  padding-top 1.4rem
   border-top 1px solid $line
+  font-size 1.55rem
 
-a
+main.docs h3
+  margin-top 2rem
+  color $accent-deep
+
+main.docs p, main.docs li
+  color $ink-soft
+
+main.docs strong
+  color $ink
+
+main.docs a
   color $accent
+  font-weight 550
+
+/* Tight, legible lists for the rule-heavy reference sections. */
+main.docs ul
+  padding-left 1.2rem
+
+main.docs li
+  margin .35rem 0
+
+main.docs li code
+  white-space nowrap
 
 .feature-card
   border 1px solid $line
   bg $panel
-  padding 1rem
+  padding 1.1rem 1.25rem
   radius $radius
+  margin 1rem 0
+
+.feature-card strong
+  color $warm

package/site/pages/docs/index.wd

@@ -5,12 +5,17 @@ transitions: true
 ---
 
 @include /nav.wd
+@include /base.wd
 
-<main>
+<main class="docs">
 
-# Docs
+<header class="docs-hero">
+<span class="eyebrow">Documentation</span>
+
+# The Darkmown docs
 
 Darkmown is a Markdown-native framework for mostly-static sites with tiny reactive islands. Pages are plain files: `.md` stays pure CommonMark, and `.wd` ("whateverdown") is the same Markdown plus first-party directives.
+</header>
 
 @include ./-relative-note.wd
 
@@ -152,6 +157,12 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 - The page's frontmatter is in scope as `meta` — `{ meta.title }` prints a field.
 - Otherwise the text is left exactly as written — braces in prose never break a page or pull in the runtime.
 
+### Format pipes — `{ value | name:arg }`
+
+Shape a value for display with a pipe: `{ price | money }`, `{ joinedAt | date:"medium" }`, `{ ratio | percent }`. Pipes chain (`{ name | trim | capitalize }`) and take literal arguments (`{ total | money:"EUR" }`, `{ bio | truncate:80 }`). The same syntax works on static values (folded at build time, zero-JS) and live bindings (re-applied on render).
+
+The whitelist: `money`, `number`, `percent`, `round`, `date` / `time` / `datetime` (Intl-backed; `short` / `medium` / `long`), `upper` / `lower` / `capitalize`, `truncate:n` / `trim`, `pluralize:"item"`, and `default:"—"`. The five aggregates double as list pipes — `{ cart | count }`, `{ cart | sum:"price" | money }`, plus `avg` / `min` / `max`. No custom functions, nothing `eval`'d; an unknown pipe is a compile error. There is deliberately no relative "time ago" formatter, so builds stay reproducible.
+
 ## Frontmatter
 
 Frontmatter sits between `---` fences. Values are strings, plus inline arrays:
@@ -179,7 +190,7 @@ You don't size images by hand. Every `<img>` the compiler emits gets its intrins
 
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~5.7 KB gzipped, under a CI-enforced 6 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~7.4 KB gzipped, under a CI-enforced 8 KB budget). Static pages do not.
 
 ```wd
 :state count = 0
@@ -205,6 +216,32 @@ Count is still zero.
 
 Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in a colocated `.js` file.
 
+### Computed values and aggregates
+
+`:computed name = expr` derives state from state — arithmetic, comparisons, and the five list aggregates `sum` / `avg` / `min` / `max` / `count`. It recomputes when an input changes and reads like any binding, so it pairs with format pipes:
+
+```wd
+:store cart = [{"price": 89}, {"price": 12}]
+:computed subtotal = sum(cart, price)
+:computed total = subtotal * 1.08
+
+Total: { total | money }
+```
+
+The aggregate's field is a bare row key (`price`, not `item.price`).
+
+### Timers — `:every`
+
+`:every <duration> -> <actions>` runs a `:button`-style action on an interval (`ms` / `s` / `m`). Intervals pause while the tab is hidden and resume on return.
+
+```wd
+:fetch board from "/status.json"
+:every 10s -> board refetch
+
+:state secs = 0
+:every 1s -> secs++
+```
+
 ### Multi-branch conditionals
 
 A condition reads the same predicate grammar as `.class when` — a bare path (truthy), or the comparisons `==` `!=` `<` `<=` `>` `>=` `contains`, joined with `and`, `or`, and `not`. (`@loop … where` is the comparison-only subset.) Chain with `:else if` (any number; a bare `:else` must come last):
@@ -312,6 +349,7 @@ 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`.
+- An array/object seed may span **multiple lines** for readability — open the `[`/`{` on the directive line and let it run until it closes (no blank line inside; an unterminated literal is a compile error). Quote literal bracket text: `:state tag = "[draft]"`.
 - Add `ephemeral` for an in-memory store that resets on reload: `:store sidebarOpen = false ephemeral`.
 
 ## Forms and persistence
@@ -320,10 +358,35 @@ You have { cart } items.
 - `:input field placeholder="…" required` and `:submit "Label"` build the form body.
 - `: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`.
+- Reactive pages expose `window.wd` (`get`, `set`, `subscribe`, `state`, `render`) so colocated `.js` can do anything directives can't. Section state is addressed as `sectionId:name`.
 
 See it all live on the [Data & Forms page](/data/).
 
+## Theme toggle — `:theme`
+
+For an explicit light/dark switch alongside the OS preference, declare `:theme` once and drive it with buttons. It registers a durable `theme` store and reflects onto `<html data-theme>`:
+
+```wd
+:theme
+:button "Auto"  -> theme = "auto"
+:button "Light" -> theme = "light"
+:button "Dark"  -> theme = "dark"
+```
+
+A single `tokens dark` block in your `.skin` already powers both the OS `prefers-color-scheme` query and this toggle — no extra block needed. `"auto"` clears the attribute and follows the OS again. See it on the [Ledger demo](/ledger/).
+
+## Media — `:video`, `:audio`, `:embed`
+
+Three compile-time-only directives (they emit no `data-wd-*`, so a media page stays zero-JS):
+
+```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` emit a hardened HTML5 player — `preload="metadata"` and `controls` by default, whitelisted flags (`autoplay` implies `muted`), and the `:fetch` URL scheme guard. `:embed` rewrites a YouTube/Vimeo link to its no-cookie/player form in a lazy, responsive `16/9` iframe. See the zero-JS [Media demo](/media/).
+
 ## Trust boundary
 
 Darkmown is a trusted-author site generator: you compile content you wrote, the way you trust your own source. Three things define that boundary.
@@ -337,7 +400,7 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in
 ## Colocation
 
 - A matching `.skin` file attaches CSS to the page (indentation-based, compiles to real CSS).
-- A matching `.js` file attaches page behavior.
+- A matching `.js` file attaches page behavior. It loads **after** the runtime, so `window.wd` is ready: `wd.get(key)`, `wd.set(key, value)`, and `wd.subscribe(key, cb)` (runs now and on every settled change) bridge declarative state to imperative widgets — the gestures the framework leaves out (keyboard, drag/touch, canvas). The [Swiper demo](/carousel/) is a draggable carousel built this way.
 - Both work for included fragments too, by basename.
 - Any other file under `site/pages/` (an image, font, PDF — anything that isn't a `.md`/`.wd` route or a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type. So `site/pages/logo.svg` is served at `/logo.svg`. Assets below hidden path segments (`.`, `-`, or `_`) and symlinked page assets are skipped, matching the routing privacy rule. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
 
@@ -345,4 +408,8 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in
 
 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`, dotted loop sources, authenticated `headers=` + `refresh=` token renewal), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `:if … :else if … :else`, reactive `.class when …`, `:effect`, `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/) and the [Reactive page](/reactive/). 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.
 
+See these directives composed into real apps on the [showcase](/showcase/).
+
 </main>
+
+@include /footer.wd