@zvndev/darkmown 0.11.0 → 0.11.2

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,22 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 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.
+
+- **Fully comment-free shipped runtime.** The last two inline comments in `src/runtime.js` are converted to a strippable form, so the emitted `runtime.js` now contains zero comments (the source stays fully documented). The reactive runtime is ~4.7 KB gzipped.
+
 ## 0.11.0 — 2026-06-16
 
 Three big `.wd` capabilities for building real apps — global state, a full fetch lifecycle, and complete loop ergonomics — plus a leaner runtime.
@@ -30,7 +46,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
@@ -41,7 +57,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

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.0",
+  "version": "0.11.2",
   "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 80",
     "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/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

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/cli.js

@@ -28,6 +28,7 @@ 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>} */
@@ -100,19 +101,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);
@@ -924,7 +924,7 @@ 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}`);
     }
     attrs.push(`${token[1]}="${escapeHtml(value)}"`);
@@ -959,7 +959,7 @@ 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}`);
     }
     attrs.push(`${token[1]}="${escapeHtml(value)}"`);
@@ -1571,11 +1571,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 +1590,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 }
 // ---------------------------------------------------------------------------

package/src/runtime.js

@@ -45,7 +45,7 @@ for (const key of persistKeys) {
 for (const name of storeKeys) {
   const stored = localStorage.getItem(`wd:store:${name}`);
   if (stored === null) localStorage.setItem(`wd:store:${name}`, JSON.stringify(state[name] ?? null));
-  else try { state[name] = JSON.parse(stored); } catch { /* keep seed */ }
+  else try { state[name] = JSON.parse(stored); } catch { /** keep seed */ }
 }
 
 function savePersisted() {
@@ -347,7 +347,7 @@ function renderNow() {
       }
       used.add(key);
       fillItem(node, item, { index: i, number: i + 1, first: i === 0, last: i === count - 1, count });
-      node.__wdItem = item; // let per-row actions resolve which row was clicked
+      node.__wdItem = item; /** let per-row actions resolve which row was clicked */
       out.appendChild(node);
     }
     for (const [key, node] of existing) {

package/src/statics.js

@@ -28,7 +28,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");