@zvndev/darkmown 2.6.1-next.11.g82bb8d7 → 2.7.0

package/site/pages/blog/darkmown-2-7-0.md

@@ -0,0 +1,176 @@
+---
+title: "Darkmown 2.7.0: no more silent failures"
+description: A release built around one question asked of every code path, when this goes wrong does the author find out. Plus a minified runtime that paid for five new features.
+date: 2026-09-04
+excerpt: A brace in a link destination used to stay literal text with no warning. A line that was just ":state" rendered as prose. Both are fixed, and the runtime got small enough to afford five new features.
+schema: BlogPosting
+tags: [release, compiler, runtime]
+---
+
+# Darkmown 2.7.0: no more silent failures
+
+Most framework bugs announce themselves. You get a stack trace, a red screen,
+a test that goes from green to red. The bugs worth being afraid of are the
+other kind: the page compiles, the build says `Built 38 routes`, and something
+on it is quietly wrong.
+
+This release came out of an audit that asked one question of every path in the
+compiler, the builder and the runtime. **When this goes wrong, does the author
+find out?** Too often the honest answer was no.
+
+Four examples, all of which shipped in 2.6.0 and none of which printed a word:
+
+- `[Read more](/docs/{ post.slug }/)` left the literal text `/docs/{ post.slug }/`
+  in the `href`. The brace resolved only when it filled the entire destination.
+- A line that was exactly `:state`, with no name and no value, rendered as the
+  text `:state` on the page.
+- A static `@loop` over `| … |` table rows produced a header-only table
+  followed by three paragraphs reading `| Ash | 3 | 12 |`.
+- A `:every 5s -> n++` inside a reactive `@loop` registered one interval per
+  row, and a row removed from the list kept ticking forever.
+
+Every one of those is now either compiled correctly or refused with a coded
+error that names the fix. That is the whole shape of the release.
+
+## Braces resolve, and then they bind
+
+The destination case turned out to be worth more than a bug fix. Once every
+brace in a destination resolves, the obvious next question is what happens when
+the value is reactive. It binds:
+
+```wd
+:state region = "eu"
+
+:button "EU" -> region = "eu"
+:button "US" -> region = "us"
+
+[Open the docs for this region](/docs/{ region }/)
+```
+
+Click a button and the `href` changes. The compiler emits the destination as a
+small template (the literal parts plus a reader) and the runtime rebuilds the
+whole value on every render. The build-time paint is still the seed, so the
+link works before the runtime loads and a crawler following it lands somewhere
+real.
+
+Two guards came with it. A value in URL position is percent-encoded, so a `)`
+arriving from your data cannot close the link and hand the rest back to the
+Markdown parser. And the runtime re-checks the scheme of the value it
+assembled, refusing `javascript:`, `data:` and `vbscript:` with an empty
+attribute rather than a half-applied one, because the compiler cannot see a
+value that only exists at runtime.
+
+Raw HTML attributes still do not bind. `<a href="{ url }">` is painted once,
+and now says so in a warning that names the position that does bind.
+
+## The URL is state
+
+Here is the feature I have wanted longest. A filter nobody can link to is half
+a feature:
+
+```wd
+:state q = "" from-url
+
+:bind q placeholder="Search products"
+
+:state products = [{"name": "Aurora Lamp"}, {"name": "Briza Fan"}]
+
+@loop products into p where p.name contains q
+- **{ p.name }**
+@empty
+Nothing matches that search.
+@endloop
+```
+
+Type in the box and the address bar becomes `?q=aurora`. Reload and the search
+comes back. Send the URL to somebody and they open on the same view.
+
+`from-url` is a third word in the persistence vocabulary, next to `persist` and
+`ephemeral`, and it is on `:state` only. Writes go through
+`history.replaceState`, so filtering never fills the back button with one entry
+per keystroke. A value back at its declared seed drops its parameter, so the
+default page keeps a clean URL. Combine it with `persist` and the precedence is
+URL, then storage, then seed: a link somebody sent you beats what this browser
+remembers.
+
+Putting it on a `:store` is a compile error rather than a guess, and the error
+says why. A `:store` is shared by every page and every tab, while a query
+parameter belongs to one page's address. Those cannot mean the same thing.
+
+## What the API actually said
+
+A failed `:fetch` used to set `name_error` to `Error: HTTP 422`, no matter what
+the server had gone to the trouble of explaining. Now, when the response body
+is JSON, `name_error` is the body's own `error` or `message` field, and the
+whole parsed body lands in a new `name_error_body`:
+
+```wd
+:fetch signup from "/api/signup" method=POST
+
+:if signup_error
+**{ signup_error }**
+:if signup_error_body
+Photo: { signup_error_body.fields.photo }
+:endif
+:endif
+```
+
+Given a 422 whose body is
+`{"error": "Pick a file first.", "fields": {"photo": "No file was attached."}}`,
+the page renders *Pick a file first.* and the per-field message underneath it.
+No JavaScript of your own.
+
+## Smaller runtime, more features
+
+None of the above would have fit. The runtime shipped as comment-stripped
+readable source, and the audit fixes alone had taken it to 8036 bytes gzipped
+out of a budget of 8192. Adding the five features below would have put the same
+file at 8886, well over the line.
+
+It now ships minified: a committed esbuild artifact, with an external sourcemap
+served next to it so DevTools still shows the readable source with real names
+and real comments. That bought about 2 KB back, and this release spent it:
+attribute binding, `from-url`, bound `:select`/`:radio`/`:checkbox` outside a
+form, server error bodies, and real multipart file upload. Total after all five:
+**6584 bytes gzipped**, against the same 8192 byte budget.
+
+The budget did not move. That is the point of having one.
+
+## Things that now fail loudly
+
+Some of the audit findings could not be fixed by making them work, because
+there was nothing correct to do. Those became errors:
+
+- **`WD191`**, a reactive `@loop` over Markdown table rows. A reactive row is
+  cloned into a `<div>`, which is not a legal child of `<table>`. The hint names
+  both ways out: a static source, or containers styled as table rows.
+- **`WD315`**, `:every` or `:effect` inside a reactive loop body. Neither has a
+  per-row meaning to salvage.
+- **A bare directive keyword**, which now throws that directive's own error with
+  that directive's own `Use:` hint. To show a directive name as text, escape it
+  with a backslash: `\:fetch`.
+- **`WD251`**, `:state b = a` where `a` is declared state. It used to seed the
+  literal string `"a"` and track nothing. Derive it with `:computed` instead.
+
+There are thirteen new codes in all, each with a cause, a fix and a compilable
+example in `darkmown catalog --llms-full`.
+
+## The rest
+
+`:::` containers and `:button` now take `role`, `aria-*` and `title`, which was
+the one place the no-attribute-syntax rule genuinely blocked a correct page.
+A `:state` declared inside a closed `:if` branch is finally hydrated when the
+branch opens. A static `@loop` fills a Markdown table. Renders settle, so a row
+cloned mid-render gets its own `:if` state in the same pass. Rows keep their
+place, so a re-render no longer steals focus from an input.
+
+The [changelog](https://github.com/ZVN-DEV/darkmown/blob/master/CHANGELOG.md)
+has all of it, and six new demo pages have it running:
+[reactive links](/attr-binding/), [URL state](/url-state/),
+[bound controls](/settings/), [server errors](/api-errors/),
+[file upload](/upload/), and [closed-branch state](/branch-state/).
+
+Upgrade with `npm install -D @zvndev/darkmown@latest`. Read the behavior
+changes in the changelog first: interpolation now resolves in positions where
+it used to stay literal, so a page that showed braces in an `href` will start
+showing values.

package/site/pages/blog/darkmown-2-7-0.skin

@@ -0,0 +1,127 @@
+/* Colocated post styling — a .skin next to a .md attaches automatically, so
+   these prose pages stay static (zero JS) yet still read on-brand. A .md can't
+   @include /base.wd, so this reading skin carries the site's tokens itself.
+   Kept in sync with site/_/base.skin; copy it beside each new post. */
+
+tokens
+  ink #1c1814
+  ink-soft #4b4239
+  muted #756a5d
+  paper #faf8f3
+  panel #ffffff
+  sunk #efe9dc
+  line #e7e1d4
+  accent #0f6b5e
+  accent-deep #0a4f45
+  accent-soft #e3f0ec
+  code-bg #1b2420
+  code-ink #e9efe7
+  code-line #2c3b34
+  radius 12px
+
+tokens dark
+  ink #ece6db
+  ink-soft #c3bbab
+  muted #9a9081
+  paper #14110d
+  panel #1e1913
+  sunk #221d17
+  line #2f281f
+  accent #5ccab4
+  accent-deep #8fe0cf
+  accent-soft #16302a
+  code-bg #100d0a
+  code-ink #e4ebe2
+  code-line #2a231b
+
+html
+  bg $paper
+
+page
+  max-width 720px
+  margin 0 auto
+  padding 3rem 1.5rem 5rem
+  font-family ui-serif, "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, Cambria, serif
+  font-size 18px
+  line-height 1.7
+  color $ink
+  bg $paper
+  -webkit-font-smoothing antialiased
+  text-rendering optimizeLegibility
+
+h1
+  font-size clamp(2rem, 5vw, 2.8rem)
+  line-height 1.12
+  letter-spacing -.022em
+  margin 1rem 0 1.25rem
+  color $ink
+
+h2
+  font-size 1.5rem
+  line-height 1.2
+  letter-spacing -.012em
+  margin 2.4rem 0 .6rem
+  color $ink
+
+h3
+  font-size 1.2rem
+  margin 1.8rem 0 .4rem
+  color $ink
+
+p
+  margin 1.1rem 0
+
+a
+  color $accent
+  text-underline-offset 2px
+
+a:hover
+  color $accent-deep
+
+strong
+  font-weight 650
+  color $ink
+
+hr
+  border 0
+  border-top 1px solid $line
+  margin 2.5rem 0
+
+ul, ol
+  margin 1.1rem 0
+  padding-left 1.4rem
+
+li
+  margin .35rem 0
+
+code
+  font-family ui-monospace, "SF Mono", Menlo, Consolas, monospace
+  font-size .88em
+  bg $sunk
+  color $accent-deep
+  padding .12rem .36rem
+  radius 6px
+
+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
+
+blockquote
+  margin 1.6rem 0
+  padding .6rem 1.3rem
+  border-left 3px solid $accent
+  color $ink-soft
+  font-style italic

package/site/pages/blog/no-unsafe-eval.md

@@ -0,0 +1,66 @@
+---
+title: Reactive pages with no unsafe-eval
+description: Since 2.1.0 the runtime interprets a validated expression AST instead of building a function, so reactive and static pages ship the same strict Content-Security-Policy.
+date: 2026-07-11
+excerpt: A reactive page used to force 'unsafe-eval' into your CSP. It no longer does, because the runtime stopped compiling expressions to JavaScript and started interpreting them.
+schema: BlogPosting
+tags: [security, runtime]
+---
+
+# Reactive pages with no unsafe-eval
+
+Every reactive framework has to answer one question honestly: how does the
+browser evaluate `p.price < 50`?
+
+Through Darkmown 2.0.x the answer was `new Function`. A `:computed`, a
+`@loop … where`, a `.class when`, and a `:if` comparison were all validated at
+compile time against a closed whitelist, then emitted as a small JavaScript
+fragment that the runtime turned back into a callable. That is safe from the
+injection angle, because nothing an author writes reaches the fragment unless it
+matched the grammar first. It is not safe from the *deployment* angle, because
+`new Function` needs `script-src 'unsafe-eval'`, and a security-minded adopter
+who reads your CSP does not care how carefully you validated the input. They
+care that the policy has a hole in it.
+
+## What changed
+
+The compiler still validates the expression exactly as before. What it emits is
+different: instead of a JavaScript fragment, it serializes the already-validated
+expression into a compact AST and puts it in the `data-wd-*` attribute. The
+runtime walks that AST with a closed evaluator. Readers, unary operators, and a
+fixed arithmetic, comparison, and logical set. An unknown op tag is a hard
+error, never a fallthrough.
+
+No `new Function`. No `eval`. Nothing on the page turns text into code.
+
+## What it buys
+
+The shipped policy is now byte-identical for static and reactive pages, across
+`dist/_headers`, `vercel.json`, and the local `serve` layer:
+
+```
+script-src 'self'
+```
+
+No `'unsafe-inline'`, no `'unsafe-eval'`, on any page the framework emits. The
+one inline script Darkmown ships (the `transitions: true` speculation-rules
+block) is authorized by a build-time `'sha256-…'` hash, and the inline state
+seed is a JSON data block that CSP does not gate at all.
+
+## What it cost
+
+136 bytes. The runtime went from 7,518 to 7,654 bytes gzipped, still under the
+8 KB budget that CI enforces on every commit.
+
+Semantics did not move. The interpreter applies the same JavaScript operators
+the generated fragments used to, and a parity battery compares the two
+evaluators across a wide matrix of expressions, states, and loop items, asserting
+identical results. The fuzz suite still proves that hostile text survives only as
+inert literal data.
+
+## The rule underneath
+
+Compile-time validation is the security layer, and it always was. Dropping
+`eval` did not make the language safer against a malicious author, because the
+whitelist already did that. It made the language **deployable** somewhere a
+strict CSP is not negotiable, which is most places worth deploying.

package/site/pages/blog/no-unsafe-eval.skin

@@ -0,0 +1,127 @@
+/* Colocated post styling — a .skin next to a .md attaches automatically, so
+   these prose pages stay static (zero JS) yet still read on-brand. A .md can't
+   @include /base.wd, so this reading skin carries the site's tokens itself.
+   Kept in sync with site/_/base.skin; copy it beside each new post. */
+
+tokens
+  ink #1c1814
+  ink-soft #4b4239
+  muted #756a5d
+  paper #faf8f3
+  panel #ffffff
+  sunk #efe9dc
+  line #e7e1d4
+  accent #0f6b5e
+  accent-deep #0a4f45
+  accent-soft #e3f0ec
+  code-bg #1b2420
+  code-ink #e9efe7
+  code-line #2c3b34
+  radius 12px
+
+tokens dark
+  ink #ece6db
+  ink-soft #c3bbab
+  muted #9a9081
+  paper #14110d
+  panel #1e1913
+  sunk #221d17
+  line #2f281f
+  accent #5ccab4
+  accent-deep #8fe0cf
+  accent-soft #16302a
+  code-bg #100d0a
+  code-ink #e4ebe2
+  code-line #2a231b
+
+html
+  bg $paper
+
+page
+  max-width 720px
+  margin 0 auto
+  padding 3rem 1.5rem 5rem
+  font-family ui-serif, "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, Cambria, serif
+  font-size 18px
+  line-height 1.7
+  color $ink
+  bg $paper
+  -webkit-font-smoothing antialiased
+  text-rendering optimizeLegibility
+
+h1
+  font-size clamp(2rem, 5vw, 2.8rem)
+  line-height 1.12
+  letter-spacing -.022em
+  margin 1rem 0 1.25rem
+  color $ink
+
+h2
+  font-size 1.5rem
+  line-height 1.2
+  letter-spacing -.012em
+  margin 2.4rem 0 .6rem
+  color $ink
+
+h3
+  font-size 1.2rem
+  margin 1.8rem 0 .4rem
+  color $ink
+
+p
+  margin 1.1rem 0
+
+a
+  color $accent
+  text-underline-offset 2px
+
+a:hover
+  color $accent-deep
+
+strong
+  font-weight 650
+  color $ink
+
+hr
+  border 0
+  border-top 1px solid $line
+  margin 2.5rem 0
+
+ul, ol
+  margin 1.1rem 0
+  padding-left 1.4rem
+
+li
+  margin .35rem 0
+
+code
+  font-family ui-monospace, "SF Mono", Menlo, Consolas, monospace
+  font-size .88em
+  bg $sunk
+  color $accent-deep
+  padding .12rem .36rem
+  radius 6px
+
+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
+
+blockquote
+  margin 1.6rem 0
+  padding .6rem 1.3rem
+  border-left 3px solid $accent
+  color $ink-soft
+  font-style italic

package/site/pages/blog/zero-js-by-default.md

@@ -16,7 +16,7 @@ none of them pay for it.
 
 That is the whole bargain. A `.md` file is plain CommonMark. Rename it to `.wd`
 and you unlock directives — state, loops, conditionals — but you only ship the
-~7.7 KB runtime on the pages that actually use them. A listing built from a
+~6.6 KB runtime on the pages that actually use them. A listing built from a
 collection loop resolves entirely at build time, so it stays static HTML.
 
 ## The extension is the feature gate

package/site/pages/branch-state/index.wd

@@ -0,0 +1,68 @@
+---
+html: true
+title: State inside a closed branch
+description: A :state, :store or :theme declared inside an :if branch that starts closed is now hydrated the moment the branch opens, instead of starting undefined and never persisting.
+---
+
+@include /nav.wd
+@include /base.wd
+
+<main>
+
+<section class="intro">
+  <span class="eyebrow">Darkmown 2.7</span>
+
+# State inside a closed branch
+
+A closed `:if` branch lives in a `<template>`, and `querySelectorAll` does not look inside one. Anything declared in there was therefore never hydrated: it started `undefined`, ignored its `persist` token, and stayed that way for the life of the page. Now the runtime re-claims seed scripts whenever a render changes structure, so a branch that opens brings its declarations with it.
+
+</section>
+
+<section>
+
+## Open the panel
+
+:state panel = false
+
+:button "Toggle the advanced panel" -> panel toggle
+
+:if panel
+
+::: section .panel
+
+:state retries = 3 persist
+
+The `:state retries` line above lives **inside** this branch. Before this change it was never declared at all: the counter below read empty and nothing was ever written to storage.
+
+Retries: **{ retries }**
+
+:button "More" -> retries++
+:button "Fewer" -> retries--
+
+Change it, close the panel, reopen it: the value you set is still there, because re-opening a branch does not re-seed a key state already holds. Reload the page and it is still there too, because `persist` now works from in here.
+
+:::
+
+:else
+
+The panel is closed. Everything inside it, including its `:state`, is still in a `<template>`.
+
+:endif
+
+</section>
+
+<section>
+
+## The rules
+
+- A seed is claimed once **per key**, not per node. Re-opening a branch clones fresh `<script>` nodes, so a per-node claim would have reset the reader's value every time.
+- The seed recorded when the key is claimed is also its `reset` baseline, so a late declaration is resettable like any other.
+- `persist` and `:store` read through storage at claim time, so a durable value declared in a branch comes back the first time the branch opens.
+
+<a class="btn primary" href="/docs/#reactive-directives">Read the docs on reactive directives</a>
+
+</section>
+
+</main>
+
+@include /footer.wd