@zvndev/darkmown 0.11.2 → 0.12.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 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.1 — 2026-06-18
+
+Release-hygiene and DX polish (post-0.12.0 smoke audit).
+
+- **Clean compile errors.** `darkmown build` prints a single `✗ <message>` line on a compile error instead of a raw Node.js stack trace (the dev rebuild log inherits the same clean output). The message still carries the file path and corrective hint.
+- **Bare `darkmown` prints help.** Running the command with no arguments shows usage instead of silently running a build.
+- **Social-share images.** A new `image:` frontmatter key sets `og:image` / `twitter:image` and upgrades the Twitter card to `summary_large_image`. The home page now ships an Open Graph card.
+- **`SECURITY.md` ships in the package** so the README's in-package security link resolves for npm consumers.
+- **Static assets documented.** README explains that non-page shelf files (`site/_/`) are copied to `/__wd/media/` (and `.json` to `/__wd/data/`).
+- **README badges** added (npm version, CI, provenance, license).
+
+## 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

@@ -1,5 +1,10 @@
 # Darkmown
 
+[![npm](https://img.shields.io/npm/v/@zvndev/darkmown)](https://www.npmjs.com/package/@zvndev/darkmown)
+[![CI](https://github.com/ZVN-DEV/darkmown/actions/workflows/ci.yml/badge.svg)](https://github.com/ZVN-DEV/darkmown/actions/workflows/ci.yml)
+[![provenance](https://img.shields.io/badge/npm-provenance-blue)](https://www.npmjs.com/package/@zvndev/darkmown)
+[![license](https://img.shields.io/npm/l/@zvndev/darkmown)](./LICENSE)
+
 **[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 ~4.7 KB gzipped, CI-enforced under 5 KB.
@@ -74,6 +79,17 @@ tags: [sales, revenue, "q1, q2"]
 - `@loop meta.tags into tag` iterates an array field at build time (stays static, zero-JS).
 - Arrays are inline flow only (`[a, b]`); quoted items keep internal commas (`"q1, q2"`). A value without a leading `[` stays a plain string.
 
+Three keys also drive the document `<head>`: `title` sets `<title>`, `description` adds the meta description plus Open Graph / Twitter tags, and `image` (an absolute URL) sets the social-share preview (`og:image` / `twitter:image` and a `summary_large_image` card).
+
+## Static assets
+
+Images, fonts, icons, and other non-page files live on the include shelf at `site/_/` and are copied into the build untouched:
+
+- Any non-`.md`/`.wd` file in `site/_/` → served at `/__wd/media/<path>` (e.g. `site/_/logo.svg` → `/__wd/media/logo.svg`).
+- `.json` files → served at `/__wd/data/<name>` (this is what `:fetch` reads).
+
+Reference them with a normal URL: `![logo](/__wd/media/logo.svg)`. The preview/`serve` layer returns the correct `Content-Type` per extension. (Files dropped in `site/pages/` are treated as routes, not assets — put shareable assets on the shelf.)
+
 ## Loops
 
 `@loop <things> into <thing>` is the only loop. The source decides the behavior:
@@ -425,7 +441,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/SECURITY.md

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Supported versions
+
+Darkmown is pre-1.0. Only the latest published minor version receives security fixes.
+
+## Reporting a vulnerability
+
+Please report vulnerabilities privately via [GitHub Security Advisories](https://github.com/ZVN-DEV/darkmown/security/advisories/new). Do not open public issues for security reports.
+
+You can expect an initial response within 72 hours. If the report is accepted, a fix ships as the next patch release and the advisory is published after the fix is available.
+
+## Trust boundary / threat model
+
+Darkmown is a **trusted-author** static site generator. The threat model assumes you compile content you wrote yourself, the same way you trust your own source code — it does not assume the content is hostile. Within that boundary the guarantees below hold; three assumptions define the boundary itself:
+
+1. **Compile only trusted, author-written content.** Do not compile `.md`/`.wd` files you did not write — user-generated content, third-party docs, or form input — without applying your own sanitization first.
+2. **Raw HTML passes through by default.** `markdown-it` runs with `html: true`, so raw HTML in content is emitted verbatim. There is no built-in sanitizer, so 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 strips raw HTML.
+3. **`:fetch` has no URL allowlist, and reactive pages require `unsafe-eval`.** A `:fetch` URL is read directly from the page source, so requests go wherever the author wrote them. Reactive pages also need `script-src 'unsafe-eval'` in your Content-Security-Policy, because the runtime compiles validated `:computed` / `@loop … where` expressions through `new Function`; a strict CSP without `unsafe-eval` breaks reactive pages (static pages are unaffected).
+
+This is the same trust posture as every Markdown SSG: the framework is safe for the trusted-author use case it targets, and unsafe content is the author's responsibility to sanitize before it reaches the compiler.
+
+## Security model
+
+Things Darkmown deliberately guards at compile time and runtime:
+
+- **No arbitrary JavaScript in content files.** Directive actions (`:button -> …`), `:computed` expressions, and `@loop … where` predicates compile through strict whitelisted grammars — only item paths, declared `:state`, numbers, and strings are allowed. Assignment, function calls, and unknown syntax are compile errors. Raw user content is never `eval`'d; what runs at runtime is the *validated* expression, compiled to the whitelisted grammar and executed via `new Function` (see `src/runtime.js`).
+- **Prototype-walk protection.** Path lookups (`{ a.b.c }`, computed expressions) reject `constructor`, `prototype`, and `__proto__` segments in both the compiler and the runtime.
+- **Include sandboxing.** `@include` and `@loop` data sources must resolve inside `site/pages` or `site/_`; traversal outside the site tree is a compile error, and include cycles are detected.
+- **Output escaping.** Interpolated values are HTML-escaped; state scripts escape `<` to prevent script-tag breakout.
+- **Static server path containment.** The dev/preview servers resolve requests strictly inside `dist`.
+
+## The biggest footgun: raw HTML passthrough
+
+Darkmown configures markdown-it with `html: true`, so **raw HTML in `.md`/`.wd` files is passed through verbatim** — by design, like every Markdown site generator. This is the single most important thing to understand about Darkmown's security model.
+
+- Treat all content files as **trusted input**, the same way you trust your own source code.
+- **Do not compile untrusted or user-submitted Markdown** (comments, form input, third-party docs) without sanitizing it first. Darkmown ships no built-in sanitizer; raw `<script>` and event-handler attributes in untrusted content would execute in the visitor's browser.
+- If you must render untrusted content, sanitize it (for example with a library like DOMPurify) before it reaches the compiler.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "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",
@@ -34,6 +34,7 @@
     "docs/spec-alignment.md",
     "AGENTS.md",
     "README.md",
+    "SECURITY.md",
     "LICENSE",
     "CHANGELOG.md"
   ],

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

@@ -1,6 +1,7 @@
 ---
 title: Darkmown — Markdown that runs, not Markdown that needs React
 description: A live store widget — search filter, add-to-cart, running total — written as one Markdown file that runs. The same outcome in Markdoc needs a React component, hydration, and a build step. Compare them side by side.
+image: https://darkmown.com/__wd/media/og.png
 ---
 
 @include /nav.wd

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

@@ -10,7 +10,9 @@ import { initProject } from "./scaffold.js";
 import { contentType, resolvePublicFile, serve } from "./statics.js";
 
 const cliPath = fileURLToPath(import.meta.url);
-const command = process.argv[2] || "build";
+// Bare `darkmown` prints help (discovery) rather than silently building — a new
+// user typing the command alone expects to see what it can do, not a no-op build.
+const command = process.argv[2] || "help";
 
 if (command === "help" || command === "--help" || command === "-h") {
   printHelp();
@@ -18,23 +20,44 @@ if (command === "help" || command === "--help" || command === "-h") {
   const pkg = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
   console.log(pkg.version);
 } else if (command === "init") {
-  const target = process.argv[3] || ".";
-  const result = initProject(path.resolve(process.cwd(), target));
-  const relativeRoot = path.relative(process.cwd(), result.root) || ".";
-  console.log(`Created Darkmown project at ${relativeRoot}`);
-  console.log(`Next: ${nextStep(relativeRoot)}`);
+  try {
+    const target = process.argv[3] || ".";
+    const result = initProject(path.resolve(process.cwd(), target));
+    const relativeRoot = path.relative(process.cwd(), result.root) || ".";
+    console.log(`Created Darkmown project at ${relativeRoot}`);
+    console.log(`Next: ${nextStep(relativeRoot)}`);
+  } catch (error) {
+    failClean(error);
+  }
 } else if (command === "build") {
-  const result = buildSite();
-  console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
+  try {
+    const result = buildSite();
+    console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
+  } catch (error) {
+    // A compile error has a clear, file-pathed message — print just that, not a
+    // Node stack trace, so a typo reads as "fix your page", not "the tool crashed".
+    failClean(error);
+  }
 } 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.
@@ -45,10 +68,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 +99,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;
       }
@@ -152,6 +182,17 @@ function broadcast(clients, message) {
   for (const client of clients) client.write(message);
 }
 
+/**
+ * Print a compile/CLI error as a single clean line and exit non-zero — no Node
+ * stack trace. The thrown Error already carries the file path + corrective hint.
+ * @param {unknown} error
+ * @returns {never}
+ */
+function failClean(error) {
+  console.error(`✗ ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}
+
 function printHelp() {
   console.log(`Darkmown
 

package/src/compiler.js

@@ -110,13 +110,24 @@ export function compilePage(file, context) {
   const compiled = compileDocument(file, context);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
-  const descriptionTag = description
-    ? `\n  <meta name="description" content="${escapeHtml(description)}">
-  <meta property="og:title" content="${escapeHtml(title)}">
-  <meta property="og:description" content="${escapeHtml(description)}">
-  <meta property="og:type" content="website">
-  <meta name="twitter:card" content="summary">`
-    : "";
+  // Optional `image:` frontmatter sets the social-share preview (absolute URL).
+  const image = typeof compiled.meta.image === "string" ? compiled.meta.image : "";
+  /** @type {string[]} */
+  const social = [];
+  if (description) social.push(`<meta name="description" content="${escapeHtml(description)}">`);
+  if (description || image) {
+    social.push(`<meta property="og:title" content="${escapeHtml(title)}">`);
+    if (description) social.push(`<meta property="og:description" content="${escapeHtml(description)}">`);
+    social.push(`<meta property="og:type" content="website">`);
+  }
+  if (image) {
+    social.push(`<meta property="og:image" content="${escapeHtml(image)}">`);
+    social.push(`<meta name="twitter:image" content="${escapeHtml(image)}">`);
+  }
+  if (description || image) {
+    social.push(`<meta name="twitter:card" content="${image ? "summary_large_image" : "summary"}">`);
+  }
+  const descriptionTag = social.length ? `\n  ${social.join("\n  ")}` : "";
   const favicon = "data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2032%2032'%3E%3Crect%20width='32'%20height='32'%20rx='6'%20fill='%2318221d'/%3E%3Ctext%20x='16'%20y='23'%20text-anchor='middle'%20font-family='Georgia,serif'%20font-size='19'%20font-weight='bold'%20fill='%23f7f3ea'%3ED%3C/text%3E%3C/svg%3E";
   const cssLinks = [...compiled.assets.skins].map((href) => `<link rel="stylesheet" href="${href}">`).join("\n");
   const scriptSrcs = compiled.assets.runtime ? ["/__wd/runtime.js", ...compiled.assets.scripts] : [...compiled.assets.scripts];
@@ -838,7 +849,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 +924,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 +943,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 +973,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 +988,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 +2123,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.