@zvndev/darkmown 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 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.

package/README.md

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -16,7 +16,7 @@
     "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 scripts/test-coverage-gate.mjs 80",
+    "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",

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/docs/index.wd

@@ -265,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/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

@@ -30,11 +30,22 @@ if (command === "help" || command === "--help" || command === "-h") {
   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.
@@ -45,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`);
@@ -74,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;
       }

package/src/compiler.js

@@ -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]) {
@@ -927,8 +932,16 @@ function handleInput(line, ctx) {
     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)) {
@@ -962,8 +977,16 @@ function handleBind(line, ctx) {
     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(" ")}>`;
@@ -2089,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;
   }
@@ -44,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.