@zvndev/darkmown 0.4.0

package/site/pages/data.wd

@@ -0,0 +1,110 @@
+---
+title: Data, forms, and persistence
+---
+
+@include /nav.wd
+
+<main>
+
+# Data, forms, and persistence
+
+This page demos the Tier 1.5 surface: declarative fetch, forms that write state, persistent state, and the JavaScript escape hatch.
+
+## Fetched data drives reactive loops
+
+`:fetch team from "/__wd/data/team.json"` declares state and fills it from the network. Until it lands, the page shows the fallback branch:
+
+:fetch team from "/__wd/data/team.json"
+
+:if team
+@loop team into member
+::: card .member-card
+**{ member.name }** — { member.role }
+:if member.lead
+Team lead ★
+:else
+Crew
+:endif
+:::
+@endloop
+:else
+Loading the team…
+:endif
+
+That loop also proves `:if` over loop items: the lead badge is decided per row.
+
+## Forms write state, no backend required
+
+`:form into profile` captures the submit straight into state. With `action="/url"` instead, Darkmown emits a plain native form and stays out of the way entirely:
+
+:form into profile
+:input name placeholder="Your name" required
+:input quest placeholder="Your quest"
+:submit "Save profile"
+:endform
+
+:if profile
+Hello **{ profile.name }** — good luck with { profile.quest }.
+:else
+Submit the form and this sentence reacts. Nothing leaves the page.
+:endif
+
+## Server round-trips, adapter style
+
+Darkmown does not own your backend — point a form at any endpoint. With JS, the submit becomes a fetch and the JSON reply lands in state; without JS, the same markup is a plain native POST:
+
+:form action="/__wd/echo" into reply
+:input message placeholder="Say something to the server"
+:submit "Send to server"
+:endform
+
+:if reply
+The server answered with { reply.received.message } at { reply.at }.
+:else
+The reply will appear here.
+:endif
+
+:if reply_error
+The request failed: { reply_error }
+:endif
+
+In `darkmown dev` the echo endpoint is built into the dev server; on darkmown.com it is a real serverless function behind the same URL. Either way, Darkmown itself stays static — sessions ride on `:fetch` plus ordinary cookies against your real API.
+
+## Persistent state survives reload
+
+`:state items = [] persist` keeps this section in localStorage. Add a few, reload the page, and the count holds:
+
+::: section #cart
+:state items = [] persist
+:computed total = items.length * 4
+
+The cart holds { items.length } item(s) worth ${ total }.
+
+:button "Add sticker" -> items += {"id": "sticker", "name": "Sticker"}
+:button "Add poster" -> items += {"id": "poster", "name": "Poster"}
+:button "Empty cart" -> items = []
+:::
+
+`:computed total = items.length * 4` derives state from state — the price updates with every cart change, persistence included.
+
+## The escape hatch
+
+Colocated `data.js` uses the `window.wd` API (`wd.get`, `wd.set`) for anything directives can't say. Section state is addressed as `cart:items`:
+
+<button class="pulse-button" data-wd-double>Double the cart via window.wd</button>
+
+## Lazy loading
+
+The list below uses `when=visible` — the request only fires once this section scrolls into view. Watch the network tab:
+
+:fetch quotes from "/__wd/data/quotes.json" when=visible
+
+:if quotes
+@loop quotes into quote
+- { quote }
+@endloop
+:else
+Scroll me into view and I will load.
+:endif
+
+</main>

package/site/pages/docs/-relative-note.wd

@@ -0,0 +1,5 @@
+<section class="feature-card">
+
+**Relative include:** this hidden block lives beside the docs page as `-relative-note.wd`, so it can be included without becoming a route.
+
+</section>

package/site/pages/docs/.secret.wd

@@ -0,0 +1,3 @@
+# Secret
+
+This hidden nested page should never be emitted.

package/site/pages/docs/index.skin

@@ -0,0 +1,39 @@
+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
+
+main
+  max-width 820px
+  margin 0 auto
+  padding 3rem 2rem 5rem
+
+h1
+  font-size 3rem
+  line-height 1
+  margin 1rem 0
+
+h2
+  margin-top 2.4rem
+  padding-top 1.2rem
+  border-top 1px solid $line
+
+a
+  color $accent
+
+.feature-card
+  border 1px solid $line
+  bg $panel
+  padding 1rem
+  radius $radius

package/site/pages/docs/index.wd

@@ -0,0 +1,125 @@
+---
+title: Darkmown docs
+---
+
+@include /nav.wd
+
+<main>
+
+# 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.
+
+@include ./-relative-note.wd
+
+## Install
+
+```sh
+npx @zvndev/darkmown init my-site
+cd my-site
+npm install
+npm run dev
+```
+
+Or add Darkmown to an existing project with `npm install -D @zvndev/darkmown`. The package is scoped; the command it installs is plain `darkmown`.
+
+## The two formats
+
+- `.md` is strict CommonMark. Directives, includes, and `{ bindings }` stay plain text, and the build prints a hint if it spots `.wd` syntax in a `.md` file.
+- `.wd` is Markdown plus directives. Renaming a file from `.md` to `.wd` is the upgrade path — nothing else changes.
+
+## Routing rules
+
+- `site/pages/index.wd` becomes `/`.
+- `site/pages/docs/index.wd` becomes `/docs/`.
+- `.secret.wd`, `-draft.wd`, and hidden folders do not become pages.
+- `site/_/` is the include shelf, never a route.
+
+## Includes
+
+- `@include /nav.wd` resolves from `site/_`.
+- `@include ./-relative-note.wd` resolves beside the current page.
+- `@include /card.wd with title="Hello" count=3` passes values into the include.
+- `with title={ feature.title }` passes a value already in scope — including whole objects.
+- Includes inside a loop inherit the loop value automatically.
+
+## Loops
+
+`@loop <things> into <thing>` is the only loop. The body is normal Markdown (or more directives) and repeats once per row:
+
+```wd
+@loop /features.json into card
+@include /feature-card.wd
+@endloop
+```
+
+The source decides how the loop behaves:
+
+- A JSON file path (`/features.json`, `./data.json`) unrolls at build time — pure static HTML.
+- An in-scope value (an include argument or an outer loop value) also unrolls at build time.
+- A `:state` list compiles to a reactive region the runtime patches by key.
+
+Loops nest, and `{ card.title }` style dotted paths reach into each row.
+
+## Interpolation
+
+One syntax everywhere: `{ name }` or `{ name.path }`.
+
+- If the name is a static value in scope (include argument, loop value), it is resolved at build time.
+- If the name is declared `:state`, it becomes a live binding.
+- Otherwise the text is left exactly as written — braces in prose never break a page or pull in the runtime.
+
+## Sections
+
+`::: section #id .class` opens a container and `:::` closes it. Sections scope state: a `:state` declared inside a section belongs to that section, so two sections can both declare `count` without colliding. Bindings and buttons resolve to the nearest scope.
+
+## Reactive directives
+
+Reactive pages opt into `/__wd/runtime.js` (under 1 KB gzipped). Static pages do not.
+
+```wd
+:state count = 0
+
+The count is { count }.
+
+:button "Increment" -> count++
+
+:if count
+Count has changed.
+:else
+Count is still zero.
+:endif
+
+:state todos = [{"id": 1, "title": "Route pages"}]
+
+@loop todos into todo
+- { todo.title }
+@endloop
+
+:button "Add" -> todos += {"id": 2, "title": "Live compile"}
+```
+
+Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in a colocated `.js` file.
+
+## Data, 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.
+- `:if item.path` works inside reactive loops for per-row branches.
+- 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`.
+
+See it all live on the [Data & Forms page](/data/).
+
+## Colocation
+
+- A matching `.skin` file attaches CSS to the page (indentation-based, compiles to real CSS).
+- A matching `.js` file attaches page behavior.
+- Both work for included fragments too, by basename.
+
+## 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`, `:session`, `:cart`, and server-driven fragments remain roadmap work — see `docs/spec-alignment.md` in the package for the full audit.
+
+</main>

package/site/pages/index.js

@@ -0,0 +1,10 @@
+const button = document.querySelector("[data-wd-demo]");
+
+if (button) {
+  button.addEventListener("click", () => {
+    button.classList.toggle("is-on");
+    button.textContent = button.classList.contains("is-on")
+      ? "Colocated index.js is active"
+      : "Script is waiting";
+  });
+}

package/site/pages/index.skin

@@ -0,0 +1,134 @@
+tokens
+  ink #171717
+  paper #fbfaf7
+  panel #ffffff
+  line #dedbd3
+  accent #16645a
+  warm #a83f2a
+  muted #666158
+  gap 1rem
+  radius 8px
+
+page
+  margin 0
+  font ui-serif, Georgia, Cambria, serif
+  color $ink
+  bg $paper
+  line-height 1.6
+  padding 0 0 4rem
+
+.hero
+  min-height 60vh
+  display flex
+  flex-direction column
+  align-items flex-start
+  justify-content center
+  border-bottom 1px solid $line
+  margin-bottom 2rem
+
+.hero > p:not(.eyebrow)
+  max-width 70ch
+
+.eyebrow
+  color $accent
+  text-transform uppercase
+  letter-spacing .08em
+  font-size .78rem
+  margin 0
+
+main
+  max-width 920px
+  margin 0 auto
+  padding 1rem 2rem 2rem
+
+h1
+  font-size clamp(2.4rem, 6vw, 5rem)
+  line-height .95
+  margin 2rem 0 1rem
+  max-width 10ch
+
+h2
+  margin-top 2rem
+  border-bottom 1px solid $line
+  padding-bottom .35rem
+
+a
+  color $accent
+
+.btn
+  display inline-block
+  margin .5rem .5rem .5rem 0
+  padding .75rem 1rem
+  border 1px solid $line
+  radius $radius
+  bg $panel
+  text-decoration none
+
+.btn.primary
+  bg $ink
+  color white
+  border 1px solid $ink
+
+.note
+  border 1px solid $line
+  bg $panel
+  padding 1rem
+  radius $radius
+
+.try-card
+  display inline-flex
+  align-items center
+  gap .65rem
+  margin .35rem .5rem .35rem 0
+  padding .75rem 1rem
+  border 1px solid $line
+  radius $radius
+  bg $panel
+  text-decoration none
+
+.try-card span
+  color white
+  bg $accent
+  padding .1rem .45rem
+  radius 999px
+
+.feature-card
+  display grid
+  gap .35rem
+  margin 1rem 0
+  padding 1rem
+  bg $panel
+  border 1px solid $line
+  radius $radius
+
+.feature-card strong
+  color $warm
+
+.pulse-button
+  border 0
+  bg $ink
+  color white
+  padding .85rem 1rem
+  radius $radius
+  font inherit
+  cursor pointer
+
+.pulse-button.is-on
+  bg $warm
+
+.sprint-board
+  display grid
+  grid-template-columns repeat(auto-fit, minmax(130px, 1fr))
+  gap $gap
+  margin 1rem 0
+
+.sprint-board article
+  bg $panel
+  border 1px solid $line
+  padding 1rem
+  radius $radius
+
+.sprint-board span
+  display block
+  color $accent
+  font-size .9rem

package/site/pages/index.wd

@@ -0,0 +1,64 @@
+---
+title: Darkmown
+---
+
+@include /nav.wd
+
+<main>
+
+<section class="hero">
+  <p class="eyebrow">Markdown-native framework</p>
+
+# Darkmown
+
+Markdown pages that compile into fast, mostly-static websites, with tiny reactive islands only where the document asks for them.
+
+<a class="btn primary" href="/docs/">Read the docs</a>
+<a class="btn" href="/reactive/">Try reactivity</a>
+</section>
+
+:note "Two formats, one rule: .md stays plain CommonMark forever, and renaming to .wd is what unlocks directives, includes, loops, and state."
+
+## What to try
+
+:try "Open the docs route, a .wd page full of includes" href="/docs/"
+:try "Open a plain .md page and see directives stay inert" href="/markdown/"
+:try "Open the reactive page: state, keyed loops, scoped sections" href="/reactive/"
+:try "Open the data page: :fetch, forms into state, persistence" href="/data/"
+:try "Open a hidden route and confirm it 404s" href="/-draft/"
+
+## Loops that read like prose
+
+`@loop` is the only loop. Point it at a JSON file, an in-scope value, or a `:state` list, and the body repeats once per row. Includes inside the loop inherit the loop value:
+
+```wd
+@loop /features.json into card
+@include /feature-card.wd
+@endloop
+```
+
+@loop /features.json into card
+@include /feature-card.wd
+@endloop
+
+## Colocated behavior
+
+This button is powered by `site/pages/index.js`, discovered by matching the page basename:
+
+<button class="pulse-button" data-wd-demo>Script is waiting</button>
+
+## Deploy in one click
+
+This repo doubles as a template — `npm run build` emits a plain static `dist/`, so it deploys anywhere that serves files:
+
+<a class="btn primary" href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FZVN-DEV%2Fdarkmown">Deploy to Vercel</a>
+<a class="btn" href="https://deploy.workers.cloudflare.com/?url=https%3A%2F%2Fgithub.com%2FZVN-DEV%2Fdarkmown">Deploy to Cloudflare</a>
+<a class="btn" href="https://github.com/ZVN-DEV/darkmown">Star on GitHub</a>
+
+## Sprint board
+
+:sprint min=4 max=6 roles="PM, Development, Research, Testing, Review"
+
+@include /sprint-loop.wd
+
+</main>

package/site/pages/markdown.md

@@ -0,0 +1,36 @@
+---
+title: Plain Markdown
+---
+
+# Plain Markdown stays plain
+
+This page is `markdown.md`. Darkmown renders it with a real CommonMark parser and adds nothing — no runtime, no directives, no surprises.
+
+## Everything CommonMark works
+
+1. Ordered lists
+2. With proper numbering
+   1. And nesting
+
+> Blockquotes render correctly, including **inline emphasis**.
+
+| Feature | Status |
+| --- | --- |
+| Tables | Working |
+| Ordered lists | Working |
+| Blockquotes | Working |
+| Images | Working |
+
+![Darkmown logo](/__wd/media/logo.svg)
+
+## Directives stay inert here
+
+The next line is `.wd` syntax, left as plain text on purpose:
+
+:state count = 0
+
+And `{ count }` braces in prose are just braces: { count }
+
+Rename this file to `markdown.wd` and all of it comes alive. That is the whole upgrade path.
+
+[Back home](/)

package/site/pages/markdown.skin

@@ -0,0 +1,63 @@
+tokens
+  ink #171717
+  paper #fbfaf7
+  panel #ffffff
+  line #dedbd3
+  accent #16645a
+  radius 8px
+
+html
+  bg $paper
+
+page
+  max-width 760px
+  margin 0 auto
+  padding 3rem 2rem 5rem
+  font ui-serif, Georgia, Cambria, serif
+  color $ink
+  bg $paper
+  line-height 1.7
+
+h1
+  font-size 3rem
+  line-height 1
+  margin 2rem 0 1rem
+
+h2
+  margin-top 2.4rem
+  padding-top 1.2rem
+  border-top 1px solid $line
+
+a
+  color $accent
+
+code
+  bg $panel
+  border 1px solid $line
+  padding .08rem .28rem
+  radius 5px
+
+blockquote
+  margin 1rem 0
+  padding .5rem 1.2rem
+  border-left 3px solid $accent
+  bg $panel
+  radius $radius
+
+table
+  border-collapse collapse
+  bg $panel
+
+th
+  text-align left
+  border 1px solid $line
+  padding .5rem .9rem
+  bg #f1ede4
+
+td
+  border 1px solid $line
+  padding .5rem .9rem
+
+img
+  width 64px
+  height 64px

package/site/pages/reactive.skin

@@ -0,0 +1,62 @@
+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 2rem
+  border-top 1px solid $line
+  padding-top 1.2rem
+
+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
+
+a
+  color $accent
+
+ul
+  border 1px solid $line
+  bg $panel
+  padding 1rem 1rem 1rem 2rem
+  radius $radius
+
+.tally-card
+  border 1px solid $line
+  bg $panel
+  padding .25rem 1.2rem 1.2rem
+  margin 1rem 0
+  radius $radius
+
+.tally-card h3
+  color $warm