@zvndev/darkmown 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.3.0 — 2026-08-09
+
+A trust release. Every compile error now carries a stable, searchable code; the dependency tree carries zero known advisories; and CI proves the framework on three operating systems and three browser engines instead of one of each. The new coverage found real bugs, including one that had silently broken every Windows user since the project started. No runtime change (7654 B gzipped, unchanged) and no breaking changes.
+
+- **Stable `WDxxx` compile-error codes.** All 138 author-facing compile errors now carry a permanent identifier — `[WD201] Malformed :state in site/pages/index.wd:1: …` — mirrored on the thrown error as `err.wd.code` alongside the existing `file`, `line`, `hint`, and `example`. Codes are grouped by subsystem (`WD1xx` loops, `WD4xx` forms, `WD5xx` fetch, and so on), and a shipped code is a public contract: never renumbered, never reused. The registry (`src/errors.js`) is the single source of truth, [`docs/errors.md`](docs/errors.md) is generated from it, and the catalog exposes it as data. Drift guards run in both directions — an uncoded author-facing throw, a duplicate code, or an undocumented one all fail the build. Genuine internal invariants (the AST parser, the reader contract) deliberately stay plain `Error`s, and that split is enforced by test.
+- **Zero known advisories.** `npm audit --audit-level=high` now exits 0. `image-size` carried a high-severity advisory affecting *every* published version including the latest — no upgrade existed — so its one call site (reading `<img>` dimensions at build time) is now served by an inlined header reader for PNG, JPEG, GIF, WebP, and SVG. Its segment walkers are explicitly bounded, which is the exact failure class the advisory described. `linkify-it` and `esbuild` advisories cleared by upgrade. Runtime code dependencies drop from three to two.
+- **BUGFIX: CRLF source files no longer lose their frontmatter.** `parseFrontmatter` tested for an LF-shaped `---\n` opener, so a file authored on Windows — or checked out anywhere with git's `core.autocrlf`, the default *on* Windows — silently had its entire frontmatter block reclassified as body text. No error was raised: the page just lost its title, layout, `draft` flag, and collection schema fields. Source text is now newline-normalized at the reader boundary and in `parseFrontmatter` itself. If you have ever edited a Darkmown page on Windows, this is the release that fixes it.
+- **CI runs on Windows, macOS, and Linux, across Chromium, Firefox, and WebKit.** Previously ubuntu-only and Chromium-only. The browser matrix is sharded so three engines cost no more wall-clock than one, and browsers are cached by resolved Playwright version. The whole 19-job matrix completes in about two minutes. The Windows job found the CRLF bug on its first run.
+- **TypeScript types actually resolve now.** The `exports` map had no `types` conditions, so consumers on `moduleResolution: node16` / `nodenext` / `bundler` — the default for new TypeScript projects — resolved *no types at all*, and the `./catalog` subpath shipped no declarations. Both entrypoints now carry `types` conditions, `types/catalog.d.ts` is authored, and `@types/markdown-it` moved to `dependencies` (types-only, no runtime code) so the root entrypoint stops erroring. Fixing this exposed that `npm run types` had been failing under TypeScript 6 and emitting nothing, leaving the committed declarations stale; generation is repaired and the output regenerated.
+- **A canary channel.** Merges to `master` publish a prerelease to the `next` dist-tag, so a fix can be exercised before it becomes stable: `npm i @zvndev/darkmown@next`. The tag-triggered stable path is untouched, and the canary job asserts after publishing that it did not become `latest`.
+- **Property tests for the skin compiler and the router,** in the seeded, reproducible style of the existing fuzz suite. They immediately found a real bug: `.skin` token modifiers quoted the attribute *value* but never validated the attribute *name*, so `tokens [{=v]` emitted `:root[{="v"]` — a stray brace that unbalances the stylesheet and makes a CSS parser swallow every rule after it. Fixed, with the case kept as a permanent regression guard.
+- **Internal:** the VS Code extension's `.vsix` is now built and uploaded by CI on every push, so it can be installed from a run without a marketplace listing. `.gitattributes` pins the working tree to LF. The test suite grew from 892 to 989 tests, holding 100% `src` line coverage.
+
 ## 2.2.0 — 2026-07-12
 
 AI authoring becomes a first-class framework surface: a machine-readable directive catalog, a generated prompt cheatsheet, a shipped GBNF grammar for constrained decoding, and compile errors that teach by example — all generated from the compiler's own whitelist tables, so none of it can drift from what actually compiles. Zero runtime impact (7654 B, unchanged).

package/README.md

@@ -39,6 +39,10 @@ npx darkmown dev
 
 The package is `@zvndev/darkmown`; the command it installs is plain `darkmown`.
 
+Every merge to `master` also publishes a prerelease to the `next` tag, so you can try a
+fix before it ships stable: `npm install -D @zvndev/darkmown@next`. Use `@latest` (the
+default) for anything you care about.
+
 Prefer to see it run before you install? The [browser playground](https://darkmown.com/playground/)
 compiles `.wd`/`.md` live in your browser — the same compiler the CLI ships — with
 no install and no build step.
@@ -995,13 +999,41 @@ import { compileFromMemory } from "@zvndev/darkmown";
 try {
   compileFromMemory({ "site/pages/index.wd": ":state x" }, "site/pages/index.wd");
 } catch (err) {
-  err.message; // "Malformed :state in …/index.wd:1: :state x. Use: :state name = value [persist] — e.g. :state count = 0"
-  err.wd;      // { file: "…/index.wd", line: 1, hint: ":state name = value [persist] — e.g. …", example: ":state count = 0" }
+  err.message; // "[WD201] Malformed :state in …/index.wd:1: :state x. Use: :state name = value [persist] — e.g. :state count = 0"
+  err.wd;      // { code: "WD201", file: "…/index.wd", line: 1, hint: ":state name = value [persist] — e.g. …", example: ":state count = 0" }
 }
 ```
 
 `example` is always a concrete, **compilable** line (never a `[placeholder]`), and every corrective `Use:` hint that contains bracket-placeholders ends with a matching `— e.g. <valid line>`. This is a deliberate affordance for small local models, which otherwise copy `[optional]`-style placeholders into source verbatim.
 
+## Compile error codes
+
+Every author-facing compile error opens with a stable `WDxxx` code, so it is searchable, linkable, and matchable by tooling without parsing prose:
+
+```
+[WD201] Malformed :state in site/pages/index.wd:1: :state x.
+        Use: :state name = value [persist] — e.g. :state count = 0
+```
+
+The full list lives in [`docs/errors.md`](docs/errors.md) — code, cause, fix, and a compilable example each. Codes are grouped by subsystem:
+
+| Range | Subsystem |
+| --- | --- |
+| `WD0xx` | Source, frontmatter & block structure |
+| `WD1xx` | Loops & collections |
+| `WD2xx` | State & expressions |
+| `WD3xx` | Button, effect & timer actions |
+| `WD4xx` | Forms & form fields |
+| `WD5xx` | Data fetching & URL safety |
+| `WD6xx` | Includes & page structure |
+| `WD7xx` | Media & embeds |
+| `WD8xx` | Skins & styling |
+| `WD9xx` | Project, routing & CLI |
+
+**A shipped code is a public contract:** it is never renumbered and a retired number is never reused, so an error found in an old log or issue always resolves to a meaningful entry. `docs/errors.md` is generated from the compiler's own registry, and drift guards fail the build if an author-facing error is added without a code, if two errors share one, or if a code goes undocumented.
+
+Genuine *internal* invariants — the expression-AST parser reading the compiler's own validated output, the reader contract — deliberately stay plain `Error`s and carry no code, because they signal a framework bug rather than something you can fix in a page.
+
 ## AI authoring
 
 Darkmown ships its own description of the `.wd` language — the same tables the compiler validates against — so a tool can teach a model to write `.wd` and constrain its output to what compiles.

package/docs/spec-alignment.md

@@ -2,6 +2,16 @@
 
 This audit compares the current Darkmown implementation with the original MARROW/WhateverDown vision and the follow-up decisions made on 2026-06-11.
 
+## 2.3.0 additions — error codes, supply chain, platform coverage (2026-08-09)
+
+- **Every author-facing compile error carries a stable `WDxxx` code.** The original vision treated compile errors as a first-class DX surface ("errors include file path + corrective suggestion"); this closes the last gap by making them *identifiable*. 138 codes, grouped by subsystem, mirrored on `err.wd.code` beside the existing `file`/`line`/`hint`/`example`. `src/errors.js` is the single source of truth, `docs/errors.md` is generated from it, and `directiveCatalog()` exposes it as data for tooling. Drift guards run both directions: an author-facing throw without a code, a duplicate code, or an undocumented code all fail the build. Internal invariants (the AST parser reading the compiler's own validated output, the reader contract) stay plain `Error`s by design — they signal a framework bug, not an authoring mistake — and that split is itself enforced by test.
+- **Zero known advisories, and one fewer runtime dependency.** `image-size` carried a high-severity advisory affecting every published version with no upgrade path, so its single build-time call site is now served by an inlined header reader (PNG/JPEG/GIF/WebP/SVG) with explicitly bounded parse loops. This keeps the project's "few runtime dependencies" posture honest rather than deferring to an unfixable upstream.
+- **BUGFIX — CRLF sources lost their frontmatter.** `parseFrontmatter` tested an LF-shaped `---\n` opener, so any file authored on Windows or checked out with `core.autocrlf` had its whole frontmatter block silently reclassified as body text: no error, but the page lost its title, layout, `draft` flag, and collection schema fields. Newline normalization now happens at the reader boundary and in `parseFrontmatter`. This had been latent since the first commit; it surfaced within minutes of adding a Windows CI job.
+- **Platform coverage is now part of the contract.** CI runs the suite on Linux, Windows, and macOS, and the browser e2e suite against Chromium, Firefox, and WebKit (sharded, so three engines cost roughly one engine's wall-clock). The reactive runtime had only ever been proven in one engine; the CLI's path handling had never executed on Windows at all.
+- **Types resolve for modern TypeScript consumers.** The `exports` map lacked `types` conditions, so `moduleResolution: node16`/`nodenext`/`bundler` consumers got no types from either entrypoint. Fixed, `types/catalog.d.ts` authored, and the declaration build itself repaired (it had been failing silently under TypeScript 6, leaving the committed `.d.ts` stale).
+- **Property tests extended to the skin compiler and the router,** in the existing seeded/reproducible style. They found a real defect on the first run: `.skin` token modifiers quoted the attribute value but never validated the attribute *name*, letting `tokens [{=v]` emit an unbalanced `:root[{="v"]` selector that a CSS parser would use to swallow every following rule.
+- **Release channels:** merges to `master` publish a prerelease to the `next` dist-tag; the tag-triggered stable path is unchanged and the canary job verifies after publishing that it did not take `latest`.
+
 ## 2.1.0 additions — eval-free expression interpreter (2026-07-11)
 
 - **Reactive pages run under a strict CSP with no `'unsafe-eval'`.** This is the headline. Through 2.0.x, the runtime executed validated `:computed` / `@loop … where` / `.class when` / `:if` expressions by building a `new Function` — which forced `script-src 'unsafe-eval'` on every reactive page, the #1 objection from security-minded adopters. The grammar was already a **closed** whitelist (comparisons, `and`/`or`/`not`, arithmetic in `:computed`, the `sum`/`avg`/`min`/`max`/`count` aggregates, literals, and dotted paths with proto-pollution guards), so it is small enough to interpret directly. The compiler now serializes each already-validated expression into a compact **AST** (nested arrays, tags `L`/`S`/`I`/`C`/`A` + the fixed operators — see `src/compiler/expr-ast.js`) emitted into the `data-wd-*` attributes, and the runtime **walks** it with a tiny closed evaluator (`src/runtime.js`). No `new Function`, no `eval`, anywhere on the page. The evaluator applies the *actual* JavaScript operators, so semantics (loose `==`/`!=`, `NaN`/`null` handling, `&&`/`||` short-circuit, string coercion, division) are byte-identical to the old path — guarded by a parity battery (`tests/expr-ast.test.js`) that compares old-`new Function` vs new-AST results across a wide input matrix, plus the fuzz suite (`tests/fuzz.test.js`) which now proves accepted expressions carry only closed op tags (dangerous text can survive only as inert `["L", …]` data) and walk to a pure value.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -12,8 +12,14 @@
   },
   "main": "./src/index.js",
   "exports": {
-    ".": "./src/index.js",
-    "./catalog": "./src/catalog.js",
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./catalog": {
+      "types": "./types/catalog.d.ts",
+      "default": "./src/catalog.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./types/index.d.ts",
@@ -61,18 +67,17 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@types/markdown-it": "^14.1.2",
     "highlight.js": "^11.11.1",
-    "image-size": "^1.2.1",
-    "markdown-it": "^14.2.0"
+    "markdown-it": "^14.3.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.1",
-    "@playwright/test": "^1.49.0",
-    "@types/markdown-it": "^14.1.2",
-    "@types/node": "^26.0.0",
-    "esbuild": "^0.24.2",
+    "@biomejs/biome": "^2.5.7",
+    "@playwright/test": "^1.61.1",
+    "@types/node": "^26.1.1",
+    "esbuild": "^0.28.2",
     "husky": "^9.1.7",
-    "lint-staged": "^16.4.0",
+    "lint-staged": "^17.0.0",
     "typescript": "^6.0.3"
   },
   "repository": {

package/site/pages/docs/index.wd

@@ -47,6 +47,7 @@ Darkmown is a Markdown-native framework for mostly-static sites with tiny reacti
 - [Syntax highlighting](#syntax-highlighting)
 - [Trust boundary](#trust-boundary)
 - [Colocation](#colocation)
+- [Compile error codes](#compile-error-codes)
 - [CLI reference](#cli-reference)
 - [Spec status](#spec-status)
 </nav>
@@ -618,6 +619,19 @@ darkmown catalog --llms > system-prompt.md
 
 Compile errors help here too: every corrective `Use:` hint ends with a concrete `— e.g. <valid line>`, and each thrown error carries a structured `err.wd = { file, line, hint, example }` mirror alongside its message — so an edit-and-retry loop gets the fix without parsing prose.
 
+## Compile error codes
+
+Every author-facing compile error opens with a stable `WDxxx` code, so it is searchable and matchable by tooling without parsing prose:
+
+```
+[WD201] Malformed :state in site/pages/index.wd:1: :state x.
+        Use: :state name = value [persist] — e.g. :state count = 0
+```
+
+The code is mirrored on the thrown error as `err.wd.code`, alongside `file`, `line`, `hint`, and a compilable `example`. Codes are grouped by subsystem — `WD0xx` source and frontmatter, `WD1xx` loops, `WD2xx` state and expressions, `WD3xx` actions, `WD4xx` forms, `WD5xx` fetching, `WD6xx` includes and structure, `WD7xx` media, `WD8xx` skins, `WD9xx` project and CLI.
+
+A shipped code is a public contract: never renumbered, never reused. The full reference — cause, fix, and an example per code — is generated from the compiler's own registry, so it cannot drift from what actually throws.
+
 ## CLI reference
 
 The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool — every command is one word: