@zvndev/darkmown 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
+
+## 0.4.0 — 2026-06-11
+
+- **Renamed**: the framework is now **Darkmown** (formerly Markie). Package `@zvndev/darkmown` (npm's typosquat guard reserves bare `darkmown` as too similar to `markdown`), CLI `darkmown`. The `.wd` format and `/__wd/` asset paths are unchanged.
+- **License**: MIT. Repository is public.
+- Gold-standard launch hardening: CI (Node 20/22/24 matrix, build check, runtime size budget, dependency audit), release automation on tag push, SECURITY.md, CONTRIBUTING.md, CLAUDE.md, this changelog.
+
+## 0.3.0 — 2026-06-11
+
+- `:form action="/url" into reply` — server round-trips against any backend: urlencoded fetch POST with the JSON reply landing in state; degrades to a plain native POST without JS.
+- Dev error overlay: failed rebuilds render the compiler error in the browser and clear on the next good build.
+- `darkmown serve` — preview the built `dist` locally.
+- Dev-only `/__wd/echo` endpoint for round-trip demos.
+
+## 0.2.0 — 2026-06-11
+
+- `:fetch name from "url"` (+ `when=visible` lazy loading via IntersectionObserver).
+- `:computed name = expr` — derived state with a compile-time-validated expression grammar.
+- `:form into name`, `:input`, `:submit` — forms that write state with zero backend.
+- `:state x = v persist` — localStorage-backed state.
+- `:if item.path` inside reactive loops (per-row branches).
+- `window.wd` escape hatch for colocated `.js`.
+- `::: section` containers with scoped state; keyed loop reconciliation.
+- View transitions via `transitions: true` frontmatter.
+- Real CommonMark parsing (markdown-it); strict `.md` (directives stay plain text).
+- `@loop … into … @endloop` — the one loop, replacing `@repeat` and `:for`.
+- Dev server rebuilds in a child process (always-fresh modules).
+
+## 0.1.0 — 2026-06-11
+
+- Initial prototype: folder router, dot/minus hidden pages, `site/_` include shelf, colocated `.skin`/`.js`, `@include`/`@repeat`, `:state`/`:button`/`:if`/`:for`, sub-1 KB runtime, live dev server.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZVN
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# Darkmown
+
+**[darkmown.com](https://darkmown.com)** · markdown, rearranged.
+
+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 under 2 KB gzipped.
+
+## Quick start
+
+```sh
+npx @zvndev/darkmown init my-site
+cd my-site
+npm install
+npm run dev
+```
+
+Or add it to an existing project:
+
+```sh
+npm install -D @zvndev/darkmown
+npx darkmown dev
+```
+
+The package is `@zvndev/darkmown`; the command it installs is plain `darkmown`.
+
+## Working from this repo
+
+```sh
+npm install
+npm test
+npm run dev    # live demo site — the same site that runs darkmown.com
+```
+
+## Commands
+
+- `darkmown init [dir]` scaffolds a new site.
+- `darkmown dev` starts the live compiler with browser reload and an in-browser error overlay when a build fails.
+- `darkmown build` writes static output to `dist`.
+- `darkmown serve` previews the built `dist` locally.
+- `darkmown help` prints CLI usage.
+
+## Authoring model
+
+- `site/pages` is the route tree. `.md` and `.wd` files become pages.
+- `.md` is strict CommonMark (real parser: ordered lists, tables, blockquotes, images, the lot). Directives stay plain text, and the build hints when it spots `.wd` syntax in a `.md` file.
+- 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 ~1.6 KB gzipped).
+- Shelf `.json` files are published at `/__wd/data/` so `:fetch` works on any static host.
+
+## Interpolation
+
+One syntax everywhere: `{ name }` or `{ name.path }`.
+
+- In-scope static values (include arguments, loop values) resolve at build time.
+- Declared `:state` becomes a live binding.
+- Anything else stays literal text — braces in prose never break a page or pull in the runtime.
+
+## Loops
+
+`@loop <things> into <thing>` is the only loop. The source decides the behavior:
+
+```wd
+@loop /features.json into card     <- JSON file: unrolled at build time
+@include /feature-card.wd          <- includes inherit the loop value
+@endloop
+
+:state todos = [{"id": 1, "title": "Route pages"}]
+
+@loop todos into todo              <- :state list: reactive, patched by key
+- { todo.title }
+@endloop
+```
+
+Loops nest, dotted paths reach into rows, and `@include ... with x={ row.field }` reassigns values Liquid-style.
+
+## Sections
+
+```wd
+::: section #cart .dark
+:state count = 0
+
+Cart has { count } items.
+
+:button "Add" -> count++
+:::
+```
+
+State declared inside a section is scoped to it — two sections can both own a `count`. Bindings and actions resolve to the nearest scope.
+
+## Reactive directives
+
+```wd
+:state count = 0
+
+Count: { count }
+
+:button "Increment" -> count++
+
+:if count
+Count has changed.
+:else
+Count is still zero.
+:endif
+```
+
+Directive actions are intentionally narrow and compile-time checked. Arbitrary JavaScript belongs in colocated `.js` files.
+
+## Data, forms, and persistence
+
+```wd
+:fetch team from "/__wd/data/team.json"
+
+:if team
+@loop team into member
+- { member.name }
+@endloop
+:else
+Loading…
+:endif
+
+:form into profile
+:input name placeholder="Your name" required
+:submit "Save"
+:endform
+
+:state cart = [] persist
+```
+
+- `:fetch name from "url"` declares state and fills it from JSON over the network; `name_error` carries failures. Add `when=visible` to defer the request until the spot scrolls into view.
+- `:computed total = items.length * 4` derives state from state with a compile-time-checked expression (names, numbers, arithmetic, comparisons — nothing else).
+- `:form into name` captures submits straight into state (no backend). `:form action="/url"` emits a plain native form instead — zero JS, full progressive enhancement.
+- `:form action="/url" into reply` does both: with JS the submit posts urlencoded via fetch and the JSON reply lands in state `reply` (`reply_error` on failure); without JS it is the same native POST. Darkmown adapts to any backend — it does not own one. `darkmown dev` ships a `/__wd/echo` endpoint for demos.
+- `:state x = [] persist` keeps that state in localStorage across reloads.
+- `:if item.path` works inside reactive loops for per-row branches.
+
+## The escape hatch
+
+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`.
+
+## Spec status
+
+See [docs/spec-alignment.md](docs/spec-alignment.md) for the deep alignment audit against the original vision.

package/docs/cli.md

@@ -0,0 +1,51 @@
+# Darkmown CLI
+
+## Install locally
+
+```sh
+npm install
+npm link
+darkmown help
+```
+
+`package.json` exposes the executable as `darkmown`.
+
+## Commands
+
+### `darkmown init [dir]`
+
+Creates a minimal Darkmown site with:
+
+- `site/pages/index.wd`
+- `site/pages/index.skin`
+- `site/_/nav.wd`
+- `README.md`
+
+Existing files are not overwritten.
+
+After scaffolding:
+
+```sh
+cd my-site
+npm install
+npm run dev
+```
+
+### `darkmown dev`
+
+Runs a live compiler:
+
+- builds once at startup
+- watches `site/` and `src/`
+- debounces rebuilds
+- serves cached `dist`
+- injects `/__wd/dev-client.js`
+- reloads the browser through `/__wd/dev-events`
+
+### `darkmown build`
+
+Compiles `site/pages` into `dist`.
+
+Static pages do not receive `/__wd/runtime.js`; reactive pages do.
+
+When a `.md` file contains `.wd` syntax (directives, includes, loops), the build prints a hint suggesting a rename to `.wd` — the syntax stays plain text in `.md` by design.

package/docs/spec-alignment.md

@@ -0,0 +1,60 @@
+# Spec alignment audit
+
+This audit compares the current Darkmown implementation with the original MARROW/WhateverDown vision and the follow-up decisions made on 2026-06-11.
+
+## Fundamentally aligned
+
+- **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` (~1.1 KB gzipped, below the original 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.
+- **`.skin` language:** indentation-based token styling compiles to CSS.
+- **Folder router:** `site/pages` maps to routes, and `.`, `-`, `_` prefixes hide pages.
+- **Colocation:** matching `.skin` and `.js` files attach to the page by basename, for includes too.
+- **Live DX:** dev mode live-compiles and reloads through a small SSE client.
+
+## Stage 3 additions (2026-06-11, same day)
+
+- **`:fetch name from "url"`:** declarative data loading into reactive state, with `name_error` for failures. Shelf `.json` publishes to `/__wd/data/` so it works on static hosts.
+- **`:form` two ways:** `:form into name` captures submits into client state with zero backend; `:form action="/url"` emits a plain native form and ships no JS — the progressive-enhancement story from the original doc.
+- **`:state x = v persist`:** localStorage-backed state. This is the honest client-side slice of the original `:cart` primitive; server sync remains future work.
+- **`:if item.path` inside reactive loops:** per-row conditional branches, filled at compile time and re-filled by the keyed patcher.
+- **`window.wd` escape hatch:** `get`/`set`/`state`/`render` exposed to colocated `.js` — the adapted form of the original `<script scope>` "infinite extension" idea, aligned with Darkmown's colocation model instead of inline scripts.
+
+## Deliberate adaptations
+
+- **One loop, `@loop … into … @endloop`:** replaces both the original doc's `:for/:endfor` and the earlier `@repeat`. The source decides behavior: JSON file or in-scope value unrolls at build time; a `:state` list compiles to a keyed reactive region. Includes inside a loop inherit the loop value (Liquid-style), and `with x={ row.field }` reassigns.
+- **One interpolation syntax:** `{ name }` / `{ name.path }` everywhere. Static in-scope values resolve at build time, declared state binds live, and unknown names stay literal — braces in prose never pull in the runtime.
+- **`.mdx` removed:** it was a label without semantics. The formats are `.md` (plain) and `.wd` (full surface).
+- **Action safety:** directive actions use a narrow compile-time-checked grammar instead of arbitrary JavaScript. Actions must target declared state.
+- **Name and extension:** MARROW/`.mw` became Darkmown/`.wd` per the follow-up direction.
+
+## Stage 4 additions (2026-06-11, same day)
+
+- **View transitions:** `transitions: true` in frontmatter emits `@view-transition { navigation: auto; }` — the original doc's zero-JS MPA navigation polish.
+- **Lazy loading:** `:fetch … when=visible` defers the request until the marker scrolls into view (IntersectionObserver) — the adapted form of `:lazy`.
+- **Computed state:** `:computed name = expr` with a compile-time-validated grammar (state refs, numbers, strings, arithmetic, comparisons; assignment, calls, and prototype walks rejected). Initial values are evaluated at build time.
+- **Dev self-reload:** `darkmown dev` rebuilds in a child process, so changes to the framework's own `src/` always compile with fresh modules.
+- **Packaging:** version 0.2.0 with repository metadata; `darkmown version` reads package.json.
+
+## Stage 5 additions (2026-06-11, same day)
+
+- **Adapter-style Tier 2 (decided):** Darkmown does not own a server. `:form action="/url" into reply` posts urlencoded via fetch and lands the JSON reply in state, degrading to a plain native POST without JS. Sessions ride on `:fetch` plus ordinary cookies against any backend. A first-party `site/api/` runtime stays open as a future option if a real project demands it.
+- **Dev error overlay:** failed rebuilds render the compiler error in the browser; the overlay clears on the next good build.
+- **`darkmown serve`:** local preview of the built `dist`, no dev client injected.
+- **Packaging:** v0.3.0, license UNLICENSED pending a licensing decision, scaffold pins the live version, npm pack contents covered by tests.
+
+## Still missing from the full vision
+
+- First-party server runtime (`site/api/`), HTML-fragment `swap` semantics, and cart server sync — parked behind the adapter decision until a real project needs them.
+- Nested `:if` over loop items, and `@loop` over fetch sub-paths.
+- `@starting-style` emission and browser fallbacks for older engines.
+- Editor tooling, richer diagnostics, and an actual npm publish (needs a license decision).
+
+## Current claim
+
+Darkmown is faithful to the core thesis: Markdown remains the authoring center, static pages ship zero framework JavaScript, and reactive behavior compiles into tiny direct-DOM islands only where declared. The extension is the feature gate, the loop is one concept with progressive disclosure, and state scopes to document structure.
+
+It is not yet the full production framework described in the original document.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@zvndev/darkmown",
+  "version": "0.4.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "description": "Darkmown — the markdown framework. Plain .md stays plain; rename to .wd for loops, state, includes, and tiny reactive islands. Zero JS on static pages.",
+  "bin": {
+    "darkmown": "./src/cli.js"
+  },
+  "scripts": {
+    "build": "node src/cli.js build",
+    "dev": "node src/cli.js dev",
+    "test": "node --test"
+  },
+  "files": [
+    "src",
+    "site",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "markdown-it": "^14.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZVN-DEV/darkmown.git"
+  },
+  "homepage": "https://github.com/ZVN-DEV/darkmown#readme",
+  "bugs": {
+    "url": "https://github.com/ZVN-DEV/darkmown/issues"
+  },
+  "keywords": [
+    "markdown",
+    "framework",
+    "static-site",
+    "wd",
+    "whateverdown",
+    "zero-js",
+    "reactive"
+  ],
+  "license": "MIT"
+}

package/site/_/feature-card.wd

@@ -0,0 +1,7 @@
+<section class="feature-card">
+
+**{ card.title }**
+
+{ card.body }
+
+</section>

package/site/_/features.json

@@ -0,0 +1,14 @@
+[
+  {
+    "title": "Folder routing without config",
+    "body": "Pages come from site/pages, and hidden work is just dot or minus prefixed."
+  },
+  {
+    "title": "One loop, @loop",
+    "body": "Loop a JSON file, an in-scope value, or a :state list — includes inside inherit the loop value."
+  },
+  {
+    "title": "Colocated behavior",
+    "body": "A matching .skin or .js file beside the page is picked up automatically."
+  }
+]

package/site/_/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#18221d"/><text x="16" y="23" text-anchor="middle" font-family="Georgia,serif" font-size="19" font-weight="bold" fill="#f7f3ea">D</text></svg>

package/site/_/nav.skin

@@ -0,0 +1,84 @@
+tokens
+  ink #171717
+  paper #fbfaf7
+  panel #ffffff
+  line #dedbd3
+  accent #16645a
+  warm #a83f2a
+  codebg #18221d
+  codeink #ecf3ea
+  radius 8px
+
+.topnav
+  display flex
+  gap 1rem
+  align-items center
+  padding 1rem 2rem
+  border-bottom 1px solid $line
+  bg rgba(251,250,247,.85)
+  backdrop-filter blur(8px)
+  position sticky
+  top 0
+  z-index 10
+
+.topnav strong
+  color $warm
+  font-size 1.05rem
+  margin-right .5rem
+
+.topnav a
+  color $accent
+  text-decoration none
+
+.topnav a:hover
+  text-decoration underline
+
+code
+  bg $panel
+  border 1px solid $line
+  padding .1rem .32rem
+  radius 5px
+  font-size .9em
+
+h1 code, h2 code, h3 code
+  font-size .85em
+
+pre
+  bg $codebg
+  color $codeink
+  padding 1.1rem 1.3rem
+  margin 1.2rem 0
+  radius $radius
+  overflow-x auto
+  line-height 1.6
+  font-size .9rem
+  box-shadow inset 0 0 0 1px rgba(255,255,255,.08)
+
+pre code
+  bg transparent
+  border 0
+  padding 0
+  color inherit
+  font-size 1em
+
+table
+  border-collapse collapse
+  bg $panel
+  margin 1rem 0
+
+th
+  text-align left
+  border 1px solid $line
+  padding .5rem .9rem
+  bg #f1ede4
+
+td
+  border 1px solid $line
+  padding .5rem .9rem
+
+blockquote
+  margin 1.2rem 0
+  padding .6rem 1.2rem
+  border-left 3px solid $accent
+  bg $panel
+  radius $radius

package/site/_/nav.wd

@@ -0,0 +1,8 @@
+<nav class="topnav">
+  <strong>Darkmown</strong>
+  <a href="/">Home</a>
+  <a href="/docs/">Docs</a>
+  <a href="/markdown/">Plain Markdown</a>
+  <a href="/reactive/">Reactive</a>
+  <a href="/data/">Data &amp; Forms</a>
+</nav>

package/site/_/quotes.json

@@ -0,0 +1,6 @@
+[
+  "Markdown is the interface.",
+  "Static until proven reactive.",
+  "Rename the file, unlock the power.",
+  "Ship bytes, not frameworks."
+]

package/site/_/sprint-loop.wd

@@ -0,0 +1,11 @@
+## 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.

package/site/_/team.json

@@ -0,0 +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 }
+]

package/site/pages/-draft.wd

@@ -0,0 +1,3 @@
+# Draft
+
+This route should never be emitted.

package/site/pages/data.js

@@ -0,0 +1,8 @@
+const button = document.querySelector("[data-wd-double]");
+
+if (button) {
+  button.addEventListener("click", () => {
+    const items = wd.get("cart:items") || [];
+    wd.set("cart:items", [...items, ...items]);
+  });
+}

package/site/pages/data.skin

@@ -0,0 +1,98 @@
+tokens
+  ink #171717
+  paper #faf8f3
+  panel #ffffff
+  line #dedbd3
+  accent #16645a
+  warm #a83f2a
+  radius 8px
+
+page
+  margin 0
+  font ui-serif, Georgia, Cambria, serif
+  color $ink
+  bg $paper
+  line-height 1.7
+
+main
+  max-width 820px
+  margin 0 auto
+  padding 3rem 2rem 5rem
+
+h1
+  font-size 3rem
+  line-height 1
+
+h2
+  margin-top 2rem
+  border-top 1px solid $line
+  padding-top 1.2rem
+
+button
+  border 1px solid $ink
+  bg $ink
+  color white
+  padding .72rem 1rem
+  margin .3rem .5rem .3rem 0
+  radius $radius
+  font inherit
+  cursor pointer
+
+button:hover
+  bg $accent
+  border-color $accent
+
+a
+  color $accent
+
+ul
+  border 1px solid $line
+  bg $panel
+  padding 1rem 1rem 1rem 2rem
+  radius $radius
+
+.tally-card
+  border 1px solid $line
+  bg $panel
+  padding .25rem 1.2rem 1.2rem
+  margin 1rem 0
+  radius $radius
+
+.tally-card h3
+  color $warm
+
+.member-card
+  border 1px solid $line
+  bg $panel
+  padding .8rem 1.2rem
+  margin .6rem 0
+  radius $radius
+
+form
+  display flex
+  gap .6rem
+  flex-wrap wrap
+  margin 1rem 0
+
+input
+  padding .7rem .9rem
+  border 1px solid $line
+  radius $radius
+  font inherit
+  bg $panel
+
+.pulse-button
+  border 0
+  bg $warm
+  color white
+  padding .85rem 1rem
+  radius $radius
+  font inherit
+  cursor pointer
+
+.tally-card
+  border 1px solid $line
+  bg $panel
+  padding .25rem 1.2rem 1.2rem
+  margin 1rem 0
+  radius $radius