@zvndev/darkmown 0.8.2 → 0.9.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.1 KB runtime only if it declares reactive behavior.
+- Static pages ship **zero** JavaScript; a page loads the ~3.2 KB runtime only if it declares reactive behavior.
 
 ## Project layout & routing
 

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.9.0 — 2026-06-15
+
+The "proof + full test pyramid" release: prove the moat on the homepage, test everything from unit to browser e2e, and pass a gold-standard open-source audit.
+
+- **Landing: the vs-Markdoc proof.** The homepage is now a side-by-side comparison — the real `.wd` source for a live search-filter + add-to-cart store rendered working on the page, next to the equivalent Markdoc (which has no native loop and needs a React component + hydration for interactivity). The homepage is now itself a reactive `.wd` app; `/markdown/` and `/docs/` stay static (zero JS) to prove the static path.
+- **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.
+- **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
 
 Honesty, hardening, and polish pass — every claim in the docs is now backed by shipped code.

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.1 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 ~3.2 KB gzipped (CI-enforced under 5 KB).
 
 ## Quick start
 
@@ -45,7 +45,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.1 KB gzipped, CI-enforced under 5 KB).
+- Static pages ship zero Darkmown runtime. Reactive pages share `/__wd/runtime.js` (currently ~3.2 KB gzipped, CI-enforced under 5 KB).
 - Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
 
 ## Interpolation
@@ -209,6 +209,8 @@ Loading…
 
 Reactive pages expose `window.wd` — `wd.get(key)`, `wd.set(key, value)`, `wd.state`, `wd.render()` — so colocated `.js` can do anything the directives can't. Section-scoped keys are addressed as `sectionId:name`.
 
+Set `window.wd.debug = true` (it defaults to `false`) to log any `:computed` or `@loop … where` expression that fails to evaluate to the console — useful while authoring reactive pages.
+
 ## Editor support
 
 A VS Code extension in [`editors/vscode`](editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding — so a `.wd` file reads as Markdown-plus-directives, never as broken Markdown. Install it from source by building a `.vsix`: `cd editors/vscode && npx @vscode/vsce package`, then `code --install-extension darkmown-*.vsix`. A Marketplace listing is coming soon.

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.1 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` (~3.2 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.8.2",
+  "version": "0.9.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -10,15 +10,23 @@
   "bin": {
     "darkmown": "./src/cli.js"
   },
+  "types": "./types/index.d.ts",
   "scripts": {
     "build": "node src/cli.js build",
     "dev": "node src/cli.js dev",
-    "test": "node --test tests/*.test.js"
+    "test": "node --test tests/*.test.js",
+    "test:cov": "node --test --experimental-test-coverage tests/*.test.js",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm test"
   },
   "files": [
     "src",
+    "types",
     "site",
-    "docs",
+    "docs/cli.md",
+    "docs/spec-alignment.md",
     "AGENTS.md",
     "README.md",
     "LICENSE",
@@ -30,6 +38,12 @@
   "dependencies": {
     "markdown-it": "^14.2.0"
   },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^22.19.21",
+    "typescript": "^5.9.3"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ZVN-DEV/darkmown.git"

package/site/pages/docs/index.wd

@@ -131,7 +131,7 @@ tags: [sales, revenue, "q1, q2"]
 
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~3.1 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~3.2 KB gzipped, under a CI-enforced 5 KB budget). Static pages do not.
 
 ```wd
 :state count = 0

package/site/pages/index.skin

@@ -133,3 +133,161 @@ a
   display block
   color $accent
   font-size .9rem
+
+/* ── vs-Markdoc comparison ───────────────────────────────────────── */
+
+.versus
+  display grid
+  grid-template-columns 1fr 1fr
+  gap 1.25rem
+  align-items start
+  margin 2.5rem 0 1rem
+
+.vs-card
+  border 1px solid $line
+  radius $radius
+  bg $panel
+  padding 1.25rem 1.25rem 1.1rem
+  display flex
+  flex-direction column
+  min-width 0
+
+.vs-card.vs-dark
+  bg #fbf7ef
+  border 1px solid #e3d8c4
+  box-shadow 0 1px 0 #efe7d6
+
+.vs-head
+  display flex
+  align-items baseline
+  justify-content space-between
+  gap .75rem
+  margin-bottom .85rem
+
+.vs-tag
+  font-family ui-monospace, SFMono-Regular, Menlo, monospace
+  font-size .72rem
+  font-weight 700
+  text-transform uppercase
+  letter-spacing .08em
+  padding .25rem .55rem
+  radius 999px
+
+.vs-tag-wd
+  color white
+  bg $accent
+
+.vs-tag-md
+  color $muted
+  bg #efece3
+  border 1px solid $line
+
+.vs-sub
+  font-family ui-monospace, SFMono-Regular, Menlo, monospace
+  font-size .82rem
+  color $muted
+
+.vs-card pre
+  margin .25rem 0 0
+  font-size .82rem
+  line-height 1.55
+
+.vs-live-label
+  margin 1rem 0 .35rem
+  font-size .88rem
+  color $muted
+  font-style italic
+
+.vs-live
+  border 1px dashed #cdbfa6
+  radius $radius
+  bg #fffdf8
+  padding 1rem 1.1rem .85rem
+  margin .15rem 0 0
+
+.vs-live input[data-wd-bind-input]
+  width 100%
+  box-sizing border-box
+  font inherit
+  font-size .95rem
+  padding .55rem .7rem
+  border 1px solid $line
+  radius 6px
+  bg white
+  margin 0 0 .75rem
+
+.vs-live .product
+  display flex
+  align-items center
+  justify-content space-between
+  gap .75rem
+  padding .5rem .7rem
+  margin .35rem 0
+  bg $panel
+  border 1px solid $line
+  radius 6px
+  font-size .95rem
+
+.vs-live .product p
+  margin 0
+
+.vs-live .product button
+  border 0
+  bg $accent
+  color white
+  font inherit
+  font-size .82rem
+  padding .35rem .7rem
+  radius 6px
+  cursor pointer
+  flex-shrink 0
+
+.vs-live .product button:hover
+  bg #11514a
+
+.vs-live > p:last-of-type
+  margin .85rem 0 0
+  font-size .95rem
+
+.vs-needs
+  margin 1rem 0 0
+  padding 1rem 1.1rem
+  border-left 3px solid $warm
+  bg #fcf4ef
+  radius 6px
+
+.vs-needs strong
+  color $warm
+  font-size .92rem
+
+.vs-needs pre
+  margin .7rem 0 .6rem
+  font-size .78rem
+
+.vs-needs-foot
+  display block
+  font-size .85rem
+  color $muted
+
+.vs-caption
+  margin auto 0 0
+  padding-top 1rem
+  font-style italic
+  color $ink
+  font-size .95rem
+
+.vs-card.vs-dark .vs-caption
+  color $accent
+
+/* Secondary value-prop row, demoted below the comparison */
+
+.props
+  margin 1.5rem 0 0
+
+.props h2
+  margin-top 1.5rem
+
+@media (max-width: 720px)
+  .versus
+    grid-template-columns 1fr
+    gap 1rem

package/site/pages/index.wd

@@ -1,6 +1,6 @@
 ---
-title: Darkmown — Markdown that runs
-description: Build full websites in plain Markdown. Routing, state, server calls, includes, and reactive islands — no JavaScript or CSS required. Your docs and your code are all just text.
+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.
 ---
 
 @include /nav.wd
@@ -8,17 +8,105 @@ description: Build full websites in plain Markdown. Routing, state, server calls
 <main>
 
 <section class="hero">
-  <p class="eyebrow">The Markdown framework</p>
+  <p class="eyebrow">Darkmown vs. Markdoc</p>
 
-# Markdown that runs.
+# Markdown that runs. Not Markdown that needs React.
 
-Not just pages — **full websites**. Routing, state, server calls, embeds, and reactive islands, all from plain Markdown files. No JavaScript or CSS required. Your docs and your code are all just text.
+The left file is Markdown. It is also a running app — a live search filter, add-to-cart, and a running total. The right file is the closest Markdoc can get on its own: a static list. To make it do what the left one already does, you add a React component, hydration, and a build step.
 
 <a class="btn primary" href="/app/">See a whole app in one file</a>
 <a class="btn" href="/docs/">Read the docs</a>
 </section>
 
-:note "Static pages ship zero JavaScript. The moment a page asks for reactivity, one ~3.1 KB runtime loads — never before. JS optional, CSS optional, always."
+<section class="versus">
+
+::: div .vs-card .vs-dark
+<header class="vs-head"><span class="vs-tag vs-tag-wd">Darkmown</span><span class="vs-sub">store.wd</span></header>
+
+```wd
+:state products = [{"id":1,"name":"Aurora Lamp","price":49},{"id":2,"name":"Briza Fan","price":39},{"id":3,"name":"Cove Speaker","price":89},{"id":4,"name":"Dune Mug","price":12}]
+:state cart = []
+:state q = ""
+:computed count = cart.length
+
+:bind q placeholder="Search products…"
+
+@loop products into p where p.name contains q
+::: card .product
+**{ p.name }** — ${ p.price }
+:button "Add" -> cart += p
+:::
+@endloop
+
+Cart: { count } item(s)
+```
+
+<p class="vs-live-label">↓ and here is that exact file, running</p>
+
+::: div .vs-live
+:state products = [{"id":1,"name":"Aurora Lamp","price":49},{"id":2,"name":"Briza Fan","price":39},{"id":3,"name":"Cove Speaker","price":89},{"id":4,"name":"Dune Mug","price":12}]
+:state cart = []
+:state q = ""
+:computed count = cart.length
+
+:bind q placeholder="Search products…"
+
+@loop products into p where p.name contains q
+::: card .product
+**{ p.name }** — ${ p.price }
+:button "Add" -> cart += p
+:::
+@endloop
+
+Cart: **{ count }** item(s)
+:::
+
+<p class="vs-caption">This is the whole file. It runs.</p>
+:::
+
+::: div .vs-card
+<header class="vs-head"><span class="vs-tag vs-tag-md">Markdoc</span><span class="vs-sub">store.md</span></header>
+
+```text
+{% if $products %}
+- **Aurora Lamp** — $49
+- **Briza Fan** — $39
+- **Cove Speaker** — $89
+- **Dune Mug** — $12
+{% /if %}
+```
+
+<p class="vs-live-label">Markdoc has <code>{% if %}</code>, <code>{% partial %}</code>, and <code>$variables</code> — but no loop tag, so each row is written by hand and the list is static. To filter, add to a cart, or total it, you reach for code:</p>
+
+::: div .vs-needs
+<strong>+ store-widget.jsx</strong> — a React component, registered as a custom tag:
+
+```jsx
+const tags = { store: { render: 'Store' } };
+Markdoc.renderers.react(content, React, {
+  components: { Store } // your filter + cart + total live here
+});
+```
+
+<span class="vs-needs-foot">…plus a React + hydration runtime shipped to the browser, and the build step that wires the tag to the component.</span>
+:::
+
+<p class="vs-caption">Same outcome needs a React component.</p>
+:::
+
+</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."
+
+<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 loop, one binding.** `@loop … into …` is the only loop; `{ name }` is the only interpolation. Nothing else to learn, nothing else to misuse.
+
+</section>
 
 ## A whole framework, in text
 
@@ -78,3 +166,4 @@ Darkmown itself was built by a small agent team. The board below is a live `@loo
 @include /sprint-loop.wd
 
 </main>
+</content>

package/src/builder.js

@@ -6,16 +6,36 @@ import { createPaths } from "./config.js";
 import { discoverRoutes, outputPathForRoute } from "./router.js";
 import { compileSkin } from "./skin.js";
 
+/**
+ * @typedef {import("./config.js").Paths} Paths
+ * @typedef {import("./compiler.js").Assets} Assets
+ */
+
+/**
+ * A built route entry written to `dist/routes.json`.
+ * @typedef {object} RouteManifestEntry
+ * @property {string} route Public route path.
+ * @property {string} file Source file path, relative to cwd, POSIX-separated.
+ * @property {{ skins: string[], scripts: string[], runtime: boolean }} assets
+ */
+
 const moduleDir = path.dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Compile the whole site under `cwd` into `dist`, returning the route manifest.
+ * @param {string} [cwd] Project working directory (defaults to `process.cwd()`).
+ * @returns {{ routes: RouteManifestEntry[], distRoot: string }}
+ */
 export function buildSite(cwd = process.cwd()) {
   const paths = createPaths(cwd);
   fs.rmSync(paths.distRoot, { recursive: true, force: true });
   fs.mkdirSync(paths.distRoot, { recursive: true });
   emitShelfAssets(paths);
   const routes = discoverRoutes(paths.routesRoot);
+  /** @type {RouteManifestEntry[]} */
   const manifest = [];
 
+  /** @type {Set<string>} */
   const warned = new Set();
 
   for (const route of routes) {
@@ -45,12 +65,41 @@ export function buildSite(cwd = process.cwd()) {
   return { routes: manifest, distRoot: paths.distRoot };
 }
 
+/**
+ * Strip JSDoc `/** ... *\/` blocks from the runtime before it ships.
+ * The source keeps full type annotations (for `checkJs` + `.d.ts`), but the
+ * browser never needs to download them — this keeps the shipped runtime lean
+ * and the gzip budget honest (measured against what users actually receive).
+ * Only `/** ... *\/` blocks are removed; code and string literals are untouched.
+ * @param {string} source
+ * @returns {string}
+ */
+export function stripRuntimeComments(source) {
+  return source
+    // Remove the JSDoc block text only — never the surrounding newlines, so an
+    // inline `/** @type {x} */ code` keeps its line and never glues onto a
+    // preceding `//` comment.
+    .replace(/\/\*\*[\s\S]*?\*\//g, "")
+    // Drop the now blank/whitespace-only lines the removed blocks leave behind.
+    .replace(/^[ \t]*\n/gm, "");
+}
+
+/**
+ * @param {Paths} paths
+ * @returns {void}
+ */
 function emitRuntime(paths) {
   const out = path.join(paths.distRoot, "__wd/runtime.js");
   fs.mkdirSync(path.dirname(out), { recursive: true });
-  fs.copyFileSync(path.join(moduleDir, "runtime.js"), out);
+  const source = fs.readFileSync(path.join(moduleDir, "runtime.js"), "utf8");
+  fs.writeFileSync(out, stripRuntimeComments(source));
 }
 
+/**
+ * @param {Assets} assets
+ * @param {Paths} paths
+ * @returns {void}
+ */
 function emitAssets(assets, paths) {
   for (const [source, href] of assets.files) {
     const out = path.join(paths.distRoot, href);
@@ -63,6 +112,11 @@ function emitAssets(assets, paths) {
   }
 }
 
+/**
+ * Copy non-page shelf assets (JSON data, media) into `dist/__wd`.
+ * @param {Paths} paths
+ * @returns {void}
+ */
 function emitShelfAssets(paths) {
   if (!fs.existsSync(paths.shelfRoot)) return;
   for (const file of walk(paths.shelfRoot)) {
@@ -76,7 +130,12 @@ function emitShelfAssets(paths) {
   }
 }
 
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
 function walk(dir) {
+  /** @type {string[]} */
   const files = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const abs = path.join(dir, entry.name);

package/src/cli.js

@@ -29,7 +29,9 @@ if (command === "help" || command === "--help" || command === "-h") {
   const port = Number(process.env.PORT || 5173);
   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;
 
   // Rebuild in a child process so changes to Darkmown's own src/ always load
@@ -94,7 +96,7 @@ if (command === "help" || command === "--help" || command === "-h") {
       serveDev(distRoot, url, res);
     } catch (error) {
       res.writeHead(500, { "content-type": "text/plain" });
-      res.end(error.stack || String(error));
+      res.end((error instanceof Error && error.stack) || String(error));
     }
   });
   server.listen(port, () => {
@@ -117,6 +119,12 @@ if (command === "help" || command === "--help" || command === "-h") {
   process.exit(1);
 }
 
+/**
+ * @param {string} distRoot
+ * @param {string} url
+ * @param {import("node:http").ServerResponse} res
+ * @returns {void}
+ */
 function serveDev(distRoot, url, res) {
   const file = resolvePublicFile(distRoot, url);
   if (!file || !fs.existsSync(file)) {
@@ -132,6 +140,11 @@ function serveDev(distRoot, url, res) {
   fs.createReadStream(file).pipe(res);
 }
 
+/**
+ * @param {Set<import("node:http").ServerResponse>} clients
+ * @param {string} message
+ * @returns {void}
+ */
 function broadcast(clients, message) {
   for (const client of clients) client.write(message);
 }