@zvndev/darkmown 0.11.1 → 0.12.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 ~3.2 KB runtime only if it declares reactive behavior.
+- Static pages ship **zero** JavaScript; a page loads the ~4.7 KB gzipped runtime (CI-enforced under 5 KB) only if it declares reactive behavior.
 
 ## Project layout & routing
 

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.12.0 — 2026-06-18
+
+Security and deploy-hardening sprint.
+
+- **Critical fix — `:computed` expression injection closed.** String literals inside `:computed` expressions are now escaped with `JSON.stringify` (the same path `@loop where` already used), so a crafted literal can no longer break out of the validated whitelist and execute arbitrary JavaScript at build time or in the browser. Added a regression suite that decodes and evaluates the emitted expression, plus a fuzzer invariant that runs compiled expressions inside a trapped sandbox to catch the whole class.
+- **Honest coverage gate.** Coverage now measures `src/**` only — test files no longer inflate the denominator — and the gate explicitly discloses that the browser runtime is covered by the Playwright e2e job rather than the line gate.
+- **Accessible form inputs by default.** `:input` and `:bind` auto-emit an `aria-label` (from the placeholder, else a humanized field name) when no `aria-label`/`aria-describedby` is supplied. The label is non-visual and never overrides an author-supplied attribute.
+- **Static-host deploys hardened.** Builds emit `dist/404.html`; the preview server serves it on a miss and returns correct content-types for images, SVG, and fonts (unknown types default to `application/octet-stream`). `vercel.json`/`wrangler.toml` document clean-URL and 404 behavior.
+- **Dev server survives a broken build.** A compile error during `darkmown dev` startup no longer crashes the process — the server stays up and the error appears in the overlay, clearing on the next good build.
+- **Trust boundary documented.** README, SECURITY.md, and the docs site now state the trust model plainly: compile only authored content — `html: true` passes raw HTML through, `:fetch` has no URL allowlist, and reactive pages require `script-src 'unsafe-eval'`.
+
+## 0.11.2 — 2026-06-17
+
+Product trust and release-hardening sprint.
+
+- **Public demos fixed.** `/app/` now renders feature bullets from the current data shape, and deploy/form copy clearly distinguishes static hosting from server-backed demo endpoints.
+- **Preview servers safer by default.** `darkmown dev` and `darkmown serve` bind to `127.0.0.1` unless `HOST` is set, and malformed preview URLs no longer crash the server.
+- **Directive hardening.** Demo `:try` links reject dangerous URL schemes; `:input` and `:bind` now carry escaped accessibility attributes.
+- **Release gates tightened.** Tag releases verify Node 20/22/24 before publishing, keep the runtime-size budget enforced, and prepublish checks cover typecheck, coverage, build, size, audit, and consumer smoke.
+- **Runtime guidance synced.** Packaged guidance and public copy now describe the measured ~4.7 KB gzipped runtime with the under-5 KB CI budget.
+
 ## 0.11.1 — 2026-06-17
 
 Maintenance release. No functional changes since 0.11.0.
@@ -36,7 +57,7 @@ The "proof + full test pyramid" release: prove the moat on the homepage, test ev
 - **Full test pyramid.** Unit + integration backfill (grammar whitelists, skin compiler, interpolation, router, every compile-error path), a zero-dependency CLI/pipeline e2e (`darkmown init` → build → serve → fetch → assert), real-browser e2e via Playwright (`npm run test:e2e`), and a seeded property/fuzz suite (5,000 cases/run) for the parser and expression validators. The zero-dep `npm test` suite grew from 98 to ~200 checks; coverage is ~96% lines, gated at 80% in CI.
 - **The fuzzer earned its keep:** it found two real bugs, now fixed — two `:button` action errors that omitted the file path, and bare object interpolation (`{ meta }`) emitting `[object Object]` instead of an actionable error. Arrays now join with `, ` consistently.
 - **Type safety.** Source stays plain JavaScript but is fully type-checked via JSDoc + `checkJs` (`npm run typecheck`, gated in CI), and ships `.d.ts` declarations. `typescript` is a dev-only dependency; the runtime stays zero-dependency.
-- **Lean shipped runtime.** JSDoc is stripped from the runtime on emit, so the browser still downloads ~3.2 KB gzipped even though the source carries full type annotations. The size budget now measures the shipped artifact.
+- **Lean shipped runtime.** JSDoc is stripped from the runtime on emit, so the browser still stays under the shared runtime budget; the current runtime is ~4.7 KB gzipped even as the source carries full type annotations. The size budget now measures the shipped artifact.
 - **Gold-standard hardening (46.5/50 audit).** Release pack-smoke test before publish, `prepublishOnly` guard, `dependabot` (npm + GitHub Actions), CI `concurrency` cancellation, `.github/` PR + issue templates, `CODEOWNERS`, a short `CODE_OF_CONDUCT.md`, an exposed/documented `window.wd.debug`, and repo-root tidy-up.
 
 ## 0.8.2 — 2026-06-14
@@ -47,7 +68,7 @@ Honesty, hardening, and polish pass — every claim in the docs is now backed by
 - **Runtime:** state changes now batch into a single render per tick (`requestAnimationFrame`, falling back to a microtask), so rapid `:bind` input no longer re-runs the reconciler on every keystroke; the final state always renders and the public `wd.render()` stays synchronous. Opt-in `window.wd.debug` surfaces warnings for failed `:computed` / `where` expressions that were previously silent.
 - **Tests:** first runtime/DOM test suite — keyed loop reconcile (node reuse on add/remove/reorder), `getPath` prototype-pollution rejection, loop-key collisions, and render batching — loading the real runtime via `node:vm`, no new dependencies. Suite grew 83 → 98.
 - **Compiler:** unterminated frontmatter now throws an actionable error with the file path instead of silently swallowing the page; empty `---`/`---` blocks parse cleanly.
-- **Docs & claims:** view transitions are now correctly described as parked/disabled (they were advertised but hardcoded off); the "no eval" wording is corrected (`:computed` and `where` compile to a whitelisted grammar run via `new Function`, never raw user content); runtime size corrected to the true ~3.1 KB gzipped across all surfaces; `:note`/`:try`/`:sprint` documented as demo-only; `docs/cli.md` scaffold output synced; VS Code install instructions corrected (build from source; Marketplace listing pending).
+- **Docs & claims:** view transitions are now correctly described as parked/disabled (they were advertised but hardcoded off); the "no eval" wording is corrected (`:computed` and `where` compile to a whitelisted grammar run via `new Function`, never raw user content); runtime size copy corrected across all surfaces; the current runtime is ~4.7 KB gzipped and CI-enforced under 5 KB; `:note`/`:try`/`:sprint` documented as demo-only; `docs/cli.md` scaffold output synced; VS Code install instructions corrected (build from source; Marketplace listing pending).
 - **Site & tooling:** landing-page whitespace fixed (removed the forced `60vh` hero band); mobile nav no longer overflows; tagline locked to "Markdown that runs."; regenerated `package-lock.json` identity (`@zvndev/darkmown`).
 
 ## 0.8.1 — 2026-06-14

package/README.md

@@ -2,7 +2,7 @@
 
 **[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 ~3.2 KB gzipped (CI-enforced under 5 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 ~4.7 KB gzipped, CI-enforced under 5 KB.
 
 ## Quick start
 
@@ -47,7 +47,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 ~3.2 KB gzipped, CI-enforced under 5 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~4.7 KB gzipped, CI-enforced under 5 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -425,7 +425,13 @@ A VS Code extension in [`editors/vscode`](editors/vscode) gives `.wd` and `.skin
 
 ## Security
 
-Darkmown renders Markdown with `html: true`, so **raw HTML in your content passes through verbatim** — by design, like every Markdown site generator. Treat content files as trusted input.
+### Trust boundary
+
+Darkmown is a **trusted-author** site generator: you compile content you wrote, the same way you trust your own source code. Three assumptions hold the model together — know them before you point Darkmown at content from anyone else.
+
+- **Compile only trusted, author-written content.** Do not compile `.md`/`.wd` files you did not write — user-generated content, third-party docs, form input — without sanitizing it first.
+- **Raw HTML passes through by default.** Darkmown runs `markdown-it` with `html: true`, so raw HTML in your content is emitted verbatim — by design, like every Markdown site generator. There is no built-in sanitizer; a raw `<script>` or event-handler attribute in untrusted content would execute in the visitor's browser. A page can opt into strict mode with `html: false` frontmatter, which drops raw HTML entirely.
+- **`:fetch` has no URL allowlist, and reactive pages need `unsafe-eval`.** A `:fetch` URL is taken straight from the page source, so the request goes wherever the author wrote. Reactive pages also require `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` expressions via `new Function` — a strict CSP without `unsafe-eval` will break reactive pages (static pages are unaffected).
 
 > **The single biggest footgun:** do not compile untrusted or user-submitted Markdown without sanitizing it first. There is no built-in sanitizer.
 

package/docs/cli.md

@@ -73,3 +73,9 @@ 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.
+
+## Deployment notes
+
+### Cloudflare Pages
+
+`wrangler.toml` builds and deploys the static `dist/` output for Cloudflare Pages. That configuration does **not** provide the demo `/__wd/echo` endpoint used by server-backed form examples; Vercel handles that route separately through `vercel.json` and `api/echo.js`. Add a Cloudflare Pages Function before advertising that demo endpoint on Cloudflare.

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` (~3.2 KB gzipped, CI-enforced below the 5 KB target).
+- **Tiered output:** static routes emit HTML/CSS and no Darkmown runtime; reactive routes opt into `/__wd/runtime.js` (~4.7 KB gzipped, CI-enforced below the 5 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -13,16 +13,18 @@
   "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: 5120)'); if (size >= 5120) process.exit(1)\"",
     "dev": "node src/cli.js dev",
     "test": "node --test tests/*.test.js",
-    "test:cov": "node --test --experimental-test-coverage tests/*.test.js",
+    "test:cov": "node scripts/test-coverage-gate.mjs 90",
     "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",
-    "smoke": "node scripts/smoke-consumer.mjs"
+    "smoke": "node scripts/smoke-consumer.mjs",
+    "prepublish:check": "npm run typecheck && npm run test:cov && npm run build && npm run runtime:size && npm audit --audit-level=high && npm run smoke",
+    "prepublishOnly": "npm run prepublish:check"
   },
   "files": [
     "src",

package/site/_/team.json

@@ -1,7 +1,7 @@
 [
-  { "id": 1, "name": "PM", "role": "Acceptance & demo proof", "lead": true },
-  { "id": 2, "name": "Dev", "role": "Compiler, router, runtime", "lead": false },
-  { "id": 3, "name": "Research", "role": "Prior art & drift control", "lead": false },
-  { "id": 4, "name": "Testing", "role": "Routes, includes, browser smoke", "lead": false },
-  { "id": 5, "name": "Review", "role": "Blocks sloppy completion", "lead": false }
+  { "id": 1, "name": "Ada", "role": "Product", "lead": true },
+  { "id": 2, "name": "Lin", "role": "Engineering", "lead": false },
+  { "id": 3, "name": "Mateo", "role": "Design", "lead": false },
+  { "id": 4, "name": "Priya", "role": "Research", "lead": false },
+  { "id": 5, "name": "Noah", "role": "Support", "lead": false }
 ]

package/site/pages/404.wd

@@ -0,0 +1,21 @@
+---
+title: Page not found — Darkmown
+description: That route does not exist. Head back to the Darkmown homepage.
+---
+
+@include /nav.wd
+
+<main>
+
+<section class="hero">
+  <p class="eyebrow">404</p>
+
+# This page ran off the page.
+
+The route you asked for is hidden, was never created, or has moved. Nothing was lost — Markdown that runs is still one click away.
+
+<a class="btn primary" href="/">Back to home</a>
+<a class="btn" href="/docs/">Read the docs</a>
+</section>
+
+</main>

package/site/pages/app.wd

@@ -16,10 +16,10 @@ Everything on this page — the prose, the fetched list, the badges, the form, t
 This whole section is plain Markdown. The list below is unrolled **at build time** from a JSON file — it renders into HTML with no runtime at all:
 
 @loop /features.json into feature
-- **{ feature.name }** — { feature.detail }
+- **{ feature.title }** — { feature.body }
 @endloop
 
-<aside class="boundary">If you deleted everything below this line, this page would ship <strong>zero</strong> bytes of JavaScript. Everything above is static HTML. Below is where the one ~2&nbsp;KB runtime loads — and only because the document asks for it.</aside>
+<aside class="boundary">If you deleted everything below this line, this page would ship <strong>zero</strong> bytes of JavaScript. Everything above is static HTML. Below is where the one ~4.7&nbsp;KB gzipped runtime loads (CI-enforced under 5 KB) — and only because the document asks for it.</aside>
 
 ## Fetched data, looped, with nested conditions
 
@@ -68,7 +68,7 @@ Nice — you are tracking the whole near-term roadmap.
 
 ## A form that talks to a real server
 
-This form posts to a live serverless function and shows the reply. With JavaScript it is a `fetch`; without it, the exact same markup is a native POST — Darkmown adapts to your backend instead of owning one:
+This form posts to the demo echo endpoint and shows the reply. With JavaScript it is a `fetch`; without it, the exact same markup is a native POST. On Vercel/dev the sample endpoint replies; on static-only hosts, point `action=` at your own backend — Darkmown adapts instead of owning one:
 
 :form action="/__wd/echo" into reply
 :input note placeholder="Tell us what you'd build with this"

package/site/pages/data.wd

@@ -68,7 +68,7 @@ The reply will appear here.
 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.
+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. On static-only hosts such as a plain Cloudflare Pages deploy, replace `action="/__wd/echo"` with your own API endpoint. Either way, Darkmown itself stays static — sessions ride on `:fetch` plus ordinary cookies against your real API.
 
 ## Persistent state survives reload
 

package/site/pages/docs/index.wd

@@ -1,5 +1,6 @@
 ---
 title: Darkmown docs
+description: Learn Darkmown routing, directives, state, loops, forms, and the static-to-reactive model.
 ---
 
 @include /nav.wd
@@ -169,7 +170,7 @@ tags: [sales, revenue, "q1, q2"]
 
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~3.2 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~4.7 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
 
 ```wd
 :state count = 0
@@ -264,6 +265,16 @@ You have { cart } items.
 
 See it all live on the [Data & Forms page](/data/).
 
+## 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.
+
+- **Compile only content you authored.** Don't run `.md`/`.wd` you didn't write — user-generated content, third-party docs — through the compiler without sanitizing it first.
+- **Raw HTML passes through by default.** Markdown renders with `html: true`, so raw HTML is emitted verbatim and there is no built-in sanitizer. Set `html: false` in a page's frontmatter to drop raw HTML for untrusted content.
+- **`:fetch` has no URL allowlist, and reactive pages need `unsafe-eval`.** Fetch URLs come straight from the page source, and the runtime compiles `:computed` / `@loop … where` expressions via `new Function` — so a reactive page needs `script-src 'unsafe-eval'` in your CSP. Static pages need neither.
+
+See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in the package for the full security model.
+
 ## Colocation
 
 - A matching `.skin` file attaches CSS to the page (indentation-based, compiles to real CSS).

package/site/pages/index.wd

@@ -96,14 +96,14 @@ Markdoc.renderers.react(content, React, {
 
 </section>
 
-:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~3.2 KB runtime loads, never before. JS optional, CSS optional, always."
+:note "Static pages ship zero JavaScript. The moment a page asks for reactivity — like this very homepage — one ~4.7 KB gzipped runtime loads (CI-enforced under 5 KB), never before. JS optional, CSS optional, always."
 
 <section class="props">
 
 ## Three rules, no escape hatch
 
 - **Zero-JS static.** A page with no state ships no framework JavaScript. `/markdown/` and `/docs/` prove it — open them and check the network tab.
-- **One runtime.** Every reactive page shares the same ~3.2 KB runtime. No per-component bundles, no hydration tax that scales with your UI.
+- **One runtime.** Every reactive page shares the same ~4.7 KB gzipped runtime, CI-enforced under 5 KB. No per-component bundles, no hydration tax that scales with your UI.
 - **One loop, one binding.** `@loop … into …` is the only loop; `{ name }` is the only interpolation. Nothing else to learn, nothing else to misuse.
 
 </section>
@@ -151,18 +151,10 @@ This button is powered by `site/pages/index.js`, discovered by matching the page
 
 ## Deploy in one click
 
-`npm run build` emits a plain static `dist/` — no server, no special runtime — so it deploys anywhere that serves files. This very site is a Darkmown build:
+`npm run build` emits a plain static `dist/` — no server, no special runtime — so it deploys anywhere that serves files. This very site is a Darkmown build. The demo form posts to Darkmown's dev/Vercel echo endpoint; on static-only hosts, point `action=` at your own backend or remove that demo.
 
 <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://deploy.workers.cloudflare.com/?url=https%3A%2F%2Fgithub.com%2FZVN-DEV%2Fdarkmown">Deploy static to Cloudflare</a>
 <a class="btn" href="https://github.com/ZVN-DEV/darkmown">Star on GitHub</a>
 
-## Built in the open
-
-Darkmown itself was built by a small agent team. The board below is a live `@loop` over real data — itself a demo of the framework rendering this page:
-
-:sprint min=4 max=6 roles="PM, Development, Research, Testing, Review"
-
-@include /sprint-loop.wd
-
 </main>

package/src/builder.js

@@ -38,6 +38,9 @@ export function buildSite(cwd = process.cwd()) {
   /** @type {Set<string>} */
   const warned = new Set();
 
+  /** @type {string | undefined} HTML of the `/404/` route, copied to dist/404.html. */
+  let notFoundHtml;
+
   for (const route of routes) {
     const page = compilePage(route.file, paths);
     for (const warning of page.warnings || []) {
@@ -48,6 +51,7 @@ export function buildSite(cwd = process.cwd()) {
     const outFile = outputPathForRoute(paths.distRoot, route.route);
     fs.mkdirSync(path.dirname(outFile), { recursive: true });
     fs.writeFileSync(outFile, page.html);
+    if (route.route === "/404/") notFoundHtml = page.html;
     emitAssets(page.assets, paths);
     if (page.assets.runtime) emitRuntime(paths);
     manifest.push({
@@ -61,6 +65,11 @@ export function buildSite(cwd = process.cwd()) {
     });
   }
 
+  // Hosts (Vercel, Cloudflare Pages) and the framework's own server auto-serve
+  // dist/404.html for misses. Prefer the compiled 404 route; fall back to a
+  // minimal page so a 404 is always available.
+  fs.writeFileSync(path.join(paths.distRoot, "404.html"), notFoundHtml ?? defaultNotFoundHtml());
+
   fs.writeFileSync(path.join(paths.distRoot, "routes.json"), JSON.stringify(manifest, null, 2));
   return { routes: manifest, distRoot: paths.distRoot };
 }
@@ -89,6 +98,30 @@ export function stripRuntimeComments(source) {
     .replace(/^[ \t]*\n/gm, "");
 }
 
+/**
+ * A minimal, zero-JS fallback 404 page used only when no `404.wd` route exists.
+ * @returns {string}
+ */
+function defaultNotFoundHtml() {
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    "<title>Page not found</title>",
+    "</head>",
+    "<body>",
+    "<main>",
+    "<h1>Page not found</h1>",
+    "<p>That route does not exist. <a href=\"/\">Back to home</a>.</p>",
+    "</main>",
+    "</body>",
+    "</html>",
+    ""
+  ].join("\n");
+}
+
 /**
  * @param {Paths} paths
  * @returns {void}

package/src/cli.js

@@ -28,12 +28,24 @@ if (command === "help" || command === "--help" || command === "-h") {
   console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
 } else if (command === "dev") {
   const port = Number(process.env.PORT || 5173);
+  const host = process.env.HOST || "127.0.0.1";
   const distRoot = path.join(process.cwd(), "dist");
-  buildSite();
   /** @type {Set<import("node:http").ServerResponse>} */
   const clients = new Set();
   /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timer;
+  /** @type {string | undefined} Last build failure, replayed to clients on connect. */
+  let lastBuildError;
+
+  // A broken initial build must NOT crash the process before the HTTP server —
+  // and thus the error overlay — comes up. Record the error so new SSE clients
+  // see it on connect; the next successful rebuild clears it via `reload`.
+  try {
+    buildSite();
+  } catch (error) {
+    lastBuildError = (error instanceof Error ? error.message : String(error)).trim();
+    console.error(lastBuildError);
+  }
 
   // Rebuild in a child process so changes to Darkmown's own src/ always load
   // fresh modules — an in-process rebuild would reuse the stale import cache.
@@ -44,10 +56,12 @@ if (command === "help" || command === "--help" || command === "-h") {
       execFile(process.execPath, [cliPath, "build"], { cwd: process.cwd() }, (error, stdout, stderr) => {
         if (error) {
           const message = (stderr || stdout || String(error)).trim();
+          lastBuildError = message;
           console.error(message);
           broadcast(clients, `event: builderror\ndata: ${JSON.stringify({ message: message.slice(0, 4000) })}\n\n`);
           return;
         }
+        lastBuildError = undefined;
         const elapsed = Math.round(performance.now() - started);
         if (stderr.trim()) console.warn(stderr.trim());
         broadcast(clients, `event: reload\ndata: ${JSON.stringify({ elapsed })}\n\n`);
@@ -73,6 +87,11 @@ if (command === "help" || command === "--help" || command === "-h") {
         });
         res.write("\n");
         clients.add(res);
+        // Replay a broken build to clients that connect while it's still failing,
+        // so the overlay shows even after a startup or pre-connect compile error.
+        if (lastBuildError) {
+          res.write(`event: builderror\ndata: ${JSON.stringify({ message: lastBuildError.slice(0, 4000) })}\n\n`);
+        }
         req.on("close", () => clients.delete(res));
         return;
       }
@@ -100,19 +119,20 @@ if (command === "help" || command === "--help" || command === "-h") {
       res.end((error instanceof Error && error.stack) || String(error));
     }
   });
-  server.listen(port, () => {
-    console.log(`Darkmown dev server ready at http://localhost:${port}`);
+  server.listen(port, host, () => {
+    console.log(`Darkmown dev server ready at http://${host}:${port}`);
     console.log(`Live compiler watching site/ and src/`);
   });
 } else if (command === "serve") {
   const port = Number(process.env.PORT || 4173);
+  const host = process.env.HOST || "127.0.0.1";
   const distRoot = path.join(process.cwd(), "dist");
   if (!fs.existsSync(distRoot)) {
     console.error("No dist directory found. Run `darkmown build` first.");
     process.exit(1);
   }
-  http.createServer((req, res) => serve(distRoot, req.url || "/", res)).listen(port, () => {
-    console.log(`Darkmown preview of dist at http://localhost:${port}`);
+  http.createServer((req, res) => serve(distRoot, req.url || "/", res)).listen(port, host, () => {
+    console.log(`Darkmown preview of dist at http://${host}:${port}`);
   });
 } else {
   console.error(`Unknown command: ${command}`);

package/src/compiler.js

@@ -400,7 +400,7 @@ function compileBody(lines, ctx) {
       i = block.end;
       continue;
     }
-    const demo = renderDemoDirective(line);
+    const demo = renderDemoDirective(line, ctx);
     if (demo) {
       flush();
       out.push(demo);
@@ -838,7 +838,10 @@ function compileComputedExpr(raw, ctx) {
   /** @type {string[]} */
   const strings = [];
   let expr = raw.replace(/"[^"\\]*"|'[^'\\]*'/g, (literal) => {
-    strings.push(`"${literal.slice(1, -1)}"`);
+    // JSON.stringify fully escapes embedded ", \, etc. so the re-inserted literal
+    // (line below) is an inert JS string and cannot terminate early to smuggle in
+    // live code. Mirrors the SAFE @loop where path (compileOperand).
+    strings.push(JSON.stringify(literal.slice(1, -1)));
     return `__WDSTR${strings.length - 1}__`;
   });
   if (/["'\\`]/.test(expr)) {
@@ -910,6 +913,8 @@ function handleInput(line, ctx) {
   if (!match) throw new Error(`Malformed :input in ${ctx.file}: ${line}`);
   const attrs = [`name="${escapeHtml(match[1])}"`];
   let type = "text";
+  let placeholder;
+  let hasAria = false;
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
   for (const token of (match[2] || "").matchAll(re)) {
     if (token[3]) {
@@ -924,11 +929,19 @@ function handleInput(line, ctx) {
       type = value;
       continue;
     }
-    if (!["placeholder", "value", "min", "max", "step", "pattern", "autocomplete"].includes(token[1])) {
+    if (!["placeholder", "value", "min", "max", "step", "pattern", "autocomplete", "aria-label", "aria-describedby"].includes(token[1])) {
       throw new Error(`Unknown :input attribute "${token[1]}" in ${ctx.file}`);
     }
+    if (token[1] === "placeholder") placeholder = value;
+    if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
     attrs.push(`${token[1]}="${escapeHtml(value)}"`);
   }
+  // Accessible name: if the author supplied neither aria-label nor aria-describedby,
+  // derive a non-visual aria-label from the placeholder, else from the field name.
+  // Never overrides an author-supplied aria attribute (zero layout impact).
+  if (!hasAria) {
+    attrs.push(`aria-label="${escapeHtml(placeholder || humanizeName(match[1]))}"`);
+  }
   return `<input type="${escapeHtml(type)}" ${attrs.join(" ")}>`;
 }
 
@@ -949,6 +962,8 @@ function handleBind(line, ctx) {
   }
   ctx.comp.assets.runtime = true;
   let type = "text";
+  let placeholder;
+  let hasAria = false;
   const attrs = [];
   const re = /([A-Za-z-]+)=("[^"]*"|\S+)|([A-Za-z-]+)/g;
   for (const token of (match[2] || "").matchAll(re)) {
@@ -959,11 +974,19 @@ function handleBind(line, ctx) {
     }
     const value = stripQuotes(token[2]);
     if (token[1] === "type") { type = value; continue; }
-    if (!["placeholder", "autocomplete"].includes(token[1])) {
+    if (!["placeholder", "autocomplete", "aria-label", "aria-describedby"].includes(token[1])) {
       throw new Error(`Unknown :bind attribute "${token[1]}" in ${ctx.file}`);
     }
+    if (token[1] === "placeholder") placeholder = value;
+    if (token[1] === "aria-label" || token[1] === "aria-describedby") hasAria = true;
     attrs.push(`${token[1]}="${escapeHtml(value)}"`);
   }
+  // Accessible name (see handleInput): default a non-visual aria-label from the
+  // placeholder, else a humanized version of the bound state key. The author's own
+  // aria-label/aria-describedby always wins.
+  if (!hasAria) {
+    attrs.push(`aria-label="${escapeHtml(placeholder || humanizeName(match[1]))}"`);
+  }
   const initial = ctx.comp.state.get(key);
   const valueAttr = initial === undefined || initial === null ? "" : ` value="${escapeHtml(String(initial))}"`;
   return `<input type="${escapeHtml(type)}" data-wd-bind-input="${key}"${valueAttr} ${attrs.join(" ")}>`;
@@ -1571,11 +1594,15 @@ export function loopKeyOf(item, counts) {
 /**
  * Render the documentation-demo directives (`:try`, `:note`, `:sprint`).
  * @param {string} line
+ * @param {Ctx} ctx
  * @returns {string}
  */
-function renderDemoDirective(line) {
+function renderDemoDirective(line, ctx) {
   const tryMatch = line.match(/^:try\s+"([^"]+)"\s+href="([^"]+)"$/);
-  if (tryMatch) return `<a class="try-card" href="${tryMatch[2]}"><span>Try</span>${escapeHtml(tryMatch[1])}</a>`;
+  if (tryMatch) {
+    const href = validateDemoHref(tryMatch[2], ctx);
+    return `<a class="try-card" href="${escapeHtml(href)}"><span>Try</span>${escapeHtml(tryMatch[1])}</a>`;
+  }
   const note = line.match(/^:note\s+"([^"]+)"$/);
   if (note) return `<aside class="note">${escapeHtml(note[1])}</aside>`;
   const sprint = line.match(/^:sprint\s+min=(\d+)\s+max=(\d+)\s+roles="([^"]+)"$/);
@@ -1586,6 +1613,30 @@ function renderDemoDirective(line) {
   return "";
 }
 
+/**
+ * Validate demo-card links without adding arbitrary URL passthrough.
+ * @param {string} href
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function validateDemoHref(href, ctx) {
+  const value = href.trim();
+  if (value !== href || /[\u0000-\u001F\u007F]/.test(value)) {
+    throw new Error(`Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`);
+  }
+  if (value.startsWith("//")) {
+    throw new Error(`Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Protocol-relative URLs are not allowed; use http: or https: explicitly.`);
+  }
+  if (value.startsWith("/") || value.startsWith("./") || value.startsWith("../") || value.startsWith("#")) {
+    return value;
+  }
+  const scheme = value.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+  if (scheme && ["http", "https", "mailto"].includes(scheme[1].toLowerCase())) {
+    return value;
+  }
+  throw new Error(`Unsafe :try href "${escapeHtml(href)}" in ${ctx.file}. Use a relative URL starting with /, ./, ../, or #, or an http:, https:, or mailto: URL.`);
+}
+
 // ---------------------------------------------------------------------------
 // Interpolation: one syntax, { name } / { name.path }
 // ---------------------------------------------------------------------------
@@ -2061,6 +2112,23 @@ function stripQuotes(value) {
   return value?.replace(/^["']|["']$/g, "") ?? "";
 }
 
+/**
+ * Turn a field name / state key into a human-readable accessible name, e.g.
+ * `quest` → "Quest", `user-name` → "User name", `firstName` → "First name".
+ * Hyphens, underscores, and camelCase boundaries become spaces; the first letter
+ * is capitalized. Used to auto-derive aria-label on generated form inputs.
+ * @param {string} name
+ * @returns {string}
+ */
+function humanizeName(name) {
+  const words = name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2") // split camelCase
+    .replace(/[-_]+/g, " ")                  // hyphens/underscores → spaces
+    .trim()
+    .toLowerCase();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : name;
+}
+
 /**
  * Escape a value for safe inclusion in HTML text and attribute contexts.
  * @param {unknown} value

package/src/statics.js

@@ -12,7 +12,12 @@ import path from "node:path";
 export function serve(distRoot, url, res) {
   const file = resolvePublicFile(distRoot, url || "/");
   if (!file || !fs.existsSync(file)) {
-    res.writeHead(404, { "content-type": "text/html" });
+    res.writeHead(404, { "content-type": "text/html; charset=utf-8" });
+    const notFound = path.join(distRoot, "404.html");
+    if (fs.existsSync(notFound)) {
+      res.end(fs.readFileSync(notFound));
+      return;
+    }
     res.end("<h1>Not found</h1><p>This route is hidden or has not been created.</p>");
     return;
   }
@@ -28,7 +33,12 @@ export function serve(distRoot, url, res) {
  * @returns {string | null}
  */
 export function resolvePublicFile(distRoot, url) {
-  const cleanUrl = decodeURIComponent(url.split("?")[0]);
+  let cleanUrl;
+  try {
+    cleanUrl = decodeURIComponent(url.split("?")[0]);
+  } catch {
+    return null;
+  }
   const base = cleanUrl.startsWith("/__wd/")
     ? cleanUrl
     : path.join(cleanUrl, path.extname(cleanUrl) ? "" : "index.html");
@@ -39,13 +49,37 @@ export function resolvePublicFile(distRoot, url) {
 }
 
 /**
- * Map a file path to a response content-type, defaulting to `text/html`.
+ * Map a file extension to a response content-type. Unknown types fall back to
+ * `application/octet-stream` so the browser never mis-sniffs an asset as HTML.
+ * @type {Record<string, string>}
+ */
+const contentTypes = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".txt": "text/plain; charset=utf-8",
+  ".xml": "application/xml"
+};
+
+/**
+ * Map a file path to a response content-type by extension, defaulting to
+ * `application/octet-stream` for unknown types.
  * @param {string} file File path or name.
  * @returns {string}
  */
 export function contentType(file) {
-  if (file.endsWith(".css")) return "text/css";
-  if (file.endsWith(".js")) return "text/javascript";
-  if (file.endsWith(".json")) return "application/json";
-  return "text/html";
+  return contentTypes[path.extname(file).toLowerCase()] || "application/octet-stream";
 }

package/site/_/sprint-loop.wd

@@ -1,11 +0,0 @@
-## Long-running session sprinting
-
-Darkmown treats sprinting as a visible operating loop, not as hidden recursion inside Markdown.
-
-- PM keeps the acceptance checklist and decides whether the demo proves the promise.
-- Development owns compiler, router, runtime, and demo integration.
-- Research checks the theory against prior art and keeps naming or platform drift from leaking in.
-- Testing owns route, include, asset, and browser smoke evidence.
-- Review inspects the final diff and blocks sloppy completion.
-
-The standing team size is 4 to 6. If work expands, add a design or architecture lane; if work shrinks, keep PM, development, testing, and review active.