@zvndev/darkmown 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 0.10.0 — 2026-06-15
+
+Launch-readiness: every public claim is now backed by runnable evidence instead of stale copy.
+
+- **Provable docs.** README, `docs/cli.md`, `docs/spec-alignment.md`, and the gold-standard audit are re-synced to the shipped code — loop semantics, the build-time vs reactive split, and per-row `:button` actions (`cart += product` carries the row into another list; `cart remove line` drops it) are documented exactly as they compile. A docs-snippet test compiles the README/docs examples so the copy can't drift from the code again.
+- **Consumer smoke script.** `npm run smoke` packs the tarball, installs it into a throwaway project, scaffolds, and builds it the way a real consumer would — the same supply-chain check the release workflow runs, now available locally.
+- **CLI + scaffold polish.** `darkmown version` prints the installed package version; first-run scaffold output and CLI guidance now match the docs.
+- **Editor + packaging scripts.** `npm run test:extension` and `npm run pack:extension` build and tokenize-test the VS Code grammar from the repo root; the extension ships its own `LICENSE` and a corrected README.
+- **`homepage` now points at https://darkmown.com.**
+
 ## 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.

package/README.md

@@ -27,7 +27,8 @@ The package is `@zvndev/darkmown`; the command it installs is plain `darkmown`.
 ```sh
 npm install
 npm test
-npm run dev    # live demo site — the same site that runs darkmown.com
+npm run smoke   # pack, install, scaffold, and build a temporary consumer app
+npm run dev     # live demo site — the same site that runs darkmown.com
 ```
 
 ## Commands
@@ -36,6 +37,7 @@ npm run dev    # live demo site — the same site that runs darkmown.com
 - `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 version` prints the installed package version.
 - `darkmown help` prints CLI usage.
 
 ## Authoring model
@@ -76,14 +78,16 @@ tags: [sales, revenue, "q1, q2"]
 
 `@loop <things> into <thing>` is the only loop. The source decides the behavior:
 
+A JSON-file loop is unrolled at build time; includes inside inherit the loop value. A `:state` list loop is reactive and patched by key.
+
 ```wd
-@loop /features.json into card     <- JSON file: unrolled at build time
-@include /feature-card.wd          <- includes inherit the loop value
+@loop /features.json into card
+@include /feature-card.wd
 @endloop
 
 :state todos = [{"id": 1, "title": "Route pages"}]
 
-@loop todos into todo              <- :state list: reactive, patched by key
+@loop todos into todo
 - { todo.title }
 @endloop
 ```
@@ -119,7 +123,7 @@ Operators: `==` `!=` `<` `<=` `>` `>=`, plus `contains` for case-insensitive sub
 
 ### Editable lists — per-row actions
 
-A `:button` inside a reactive `@loop` can act on its own row. Two row actions exist:
+A `:button` inside a reactive `@loop` can act on its own row. `cart += product` carries the current row into another list; `cart remove line` drops the current row from the looped list:
 
 ```wd
 :state products = [{"id": 1, "name": "Aurora", "price": 49}]
@@ -128,14 +132,14 @@ A `:button` inside a reactive `@loop` can act on its own row. Two row actions ex
 @loop products into product
 ::: card
 **{ product.name }** — ${ product.price }
-:button "Add to cart" -> cart += product    <- carry this row into another list
+:button "Add to cart" -> cart += product
 :::
 @endloop
 
 @loop cart into line
 ::: card
 { line.name }
-:button "Remove" -> cart remove line          <- drop this row from the looped list
+:button "Remove" -> cart remove line
 :::
 @endloop
 ```
@@ -213,7 +217,7 @@ Set `window.wd.debug = true` (it defaults to `false`) to log any `:computed` or
 
 ## 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.
+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. For launch, it is source-installable: build a `.vsix` with `npm run pack:extension`, then install `editors/vscode/darkmown-*.vsix` with VS Code. Marketplace/Open VSX publishing is tracked as post-launch distribution work, so the public package does not imply store availability yet.
 
 ## Security
 

package/docs/cli.md

@@ -12,6 +12,14 @@ darkmown help
 
 ## Commands
 
+### `darkmown help` / `darkmown --help`
+
+Prints the command summary, authoring directories, and common directive syntax.
+
+### `darkmown version` / `darkmown --version`
+
+Prints the installed package version.
+
 ### `darkmown init [dir]`
 
 Creates a minimal Darkmown site with:
@@ -23,7 +31,7 @@ Creates a minimal Darkmown site with:
 - `site/_/nav.wd`
 - `README.md`
 
-Existing files are not overwritten.
+Existing files are not overwritten. The scaffolded `package.json` is private by default, includes `dev`, `build`, and `preview` scripts, and names the app after the target directory.
 
 After scaffolding:
 
@@ -50,4 +58,18 @@ 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.
+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.
+
+### `darkmown serve`
+
+Serves the already-built `dist` directory for local preview. Run `darkmown build` first.
+
+## Smoke checks
+
+From this repository, run:
+
+```sh
+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.

package/docs/spec-alignment.md

@@ -44,7 +44,7 @@ This audit compares the current Darkmown implementation with the original MARROW
 - **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.
+- **Packaging:** v0.3.0 introduced package metadata and pack tests; the current public package is MIT licensed and scaffolded projects pin the live Darkmown version.
 
 ## Stage 6 additions (2026-06-13)
 
@@ -69,10 +69,10 @@ The compiler recognizes three directives — `:note`, `:try`, and `:sprint` —
 - 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.
 - `@loop` over fetch sub-paths (looping a path *inside* fetched state rather than top-level state).
 - **View transitions:** re-enabling `transitions: true` with proper activation fallbacks (disabled today — see Stage 4), plus `@starting-style` emission and browser fallbacks for older engines.
-- Editor tooling, richer diagnostics, and an actual npm publish (needs a license decision).
+- Richer diagnostics and package-consumer QA in regular CI. Editor tooling exists as a source-installable VS Code extension; public Marketplace/Open VSX distribution remains a launch/distribution follow-up.
 
 ## 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.
+The public npm package is published as `@zvndev/darkmown`, the project is MIT licensed, and the remaining gaps are explicitly scoped as post-launch product/distribution work rather than missing v0.9 claims.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -17,9 +17,12 @@
     "test": "node --test tests/*.test.js",
     "test:cov": "node --test --experimental-test-coverage tests/*.test.js",
     "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"
+    "prepublishOnly": "npm test",
+    "smoke": "node scripts/smoke-consumer.mjs"
   },
   "files": [
     "src",
@@ -48,7 +51,7 @@
     "type": "git",
     "url": "git+https://github.com/ZVN-DEV/darkmown.git"
   },
-  "homepage": "https://github.com/ZVN-DEV/darkmown#readme",
+  "homepage": "https://darkmown.com",
   "bugs": {
     "url": "https://github.com/ZVN-DEV/darkmown/issues"
   },

package/site/_/roadmap.json

@@ -1,7 +1,7 @@
 [
-  { "id": "loops", "title": "Nested conditionals in loops", "shipped": true, "blocked": false },
+  { "id": "loops", "title": "Nested `:if` inside loop rows", "shipped": true, "blocked": false },
   { "id": "editor", "title": "VS Code syntax highlighting", "shipped": true, "blocked": false },
-  { "id": "filter", "title": "State-driven list filtering", "shipped": false, "blocked": false },
+  { "id": "filter", "title": "Reactive `@loop where` filtering", "shipped": true, "blocked": false },
   { "id": "api", "title": "First-party site/api/ runtime", "shipped": false, "blocked": true },
   { "id": "swap", "title": "HTML-fragment swap responses", "shipped": false, "blocked": false }
 ]

package/site/pages/docs/index.wd

@@ -176,6 +176,6 @@ See it all live on the [Data & Forms page](/data/).
 
 ## Spec status
 
-The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:fetch`, `:form` (including server round-trips), `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/). Still on the roadmap: a first-party server runtime (`site/api/`), HTML-fragment swaps, and nested `:if` over loop items. See `docs/spec-alignment.md` in the package for the full audit.
+The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:fetch`, `:form` (including server round-trips), `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/). Still on the roadmap: a first-party server runtime (`site/api/`), HTML-fragment swaps, and `@loop` over fetched sub-paths. See `docs/spec-alignment.md` in the package for the full audit.
 
 </main>

package/site/pages/index.wd

@@ -166,4 +166,3 @@ Darkmown itself was built by a small agent team. The board below is a live `@loo
 @include /sprint-loop.wd
 
 </main>
-</content>

package/src/cli.js

@@ -20,8 +20,9 @@ if (command === "help" || command === "--help" || command === "-h") {
 } else if (command === "init") {
   const target = process.argv[3] || ".";
   const result = initProject(path.resolve(process.cwd(), target));
-  console.log(`Created Darkmown project at ${path.relative(process.cwd(), result.root) || "."}`);
-  console.log(`Next: cd ${path.relative(process.cwd(), result.root) || "."} && npm install && npm run dev`);
+  const relativeRoot = path.relative(process.cwd(), result.root) || ".";
+  console.log(`Created Darkmown project at ${relativeRoot}`);
+  console.log(`Next: ${nextStep(relativeRoot)}`);
 } else if (command === "build") {
   const result = buildSite();
   console.log(`Built ${result.routes.length} routes into ${path.relative(process.cwd(), result.distRoot)}`);
@@ -157,6 +158,7 @@ Usage:
   darkmown dev          Start the live compiler dev server
   darkmown build        Compile site/pages into dist
   darkmown serve        Preview the built dist locally
+  darkmown version      Print the installed Darkmown version
   darkmown help         Show this help
 
 Authoring:
@@ -167,3 +169,13 @@ Authoring:
   *.js                Colocated page behavior
 `);
 }
+
+
+/**
+ * @param {string} relativeRoot
+ * @returns {string}
+ */
+function nextStep(relativeRoot) {
+  if (relativeRoot === ".") return "npm install && npm run dev";
+  return `cd ${relativeRoot} && npm install && npm run dev`;
+}

package/src/scaffold.js

@@ -13,9 +13,12 @@ const darkmownVersion = JSON.parse(
 export function initProject(root) {
   fs.mkdirSync(root, { recursive: true });
   writeNew(root, "package.json", JSON.stringify({
+    name: packageNameFromRoot(root),
+    private: true,
     scripts: {
       dev: "darkmown dev",
-      build: "darkmown build"
+      build: "darkmown build",
+      preview: "darkmown serve"
     },
     devDependencies: {
       "@zvndev/darkmown": `^${darkmownVersion}`
@@ -146,3 +149,19 @@ function writeNew(root, file, content) {
   fs.mkdirSync(path.dirname(target), { recursive: true });
   fs.writeFileSync(target, `${content}\n`);
 }
+
+
+/**
+ * Derive a safe default npm package name from the scaffold target directory.
+ * @param {string} root Absolute target directory.
+ * @returns {string}
+ */
+function packageNameFromRoot(root) {
+  const base = path.basename(root) || "darkmown-site";
+  const normalized = base
+    .toLowerCase()
+    .replace(/^@/, "")
+    .replace(/[^a-z0-9._~-]+/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "");
+  return normalized || "darkmown-site";
+}