@zvndev/darkmown 2.5.1-next.10.g0f7c9b8 → 2.6.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.6.0 (2026-08-18)
+
+A correctness release for the persistence surface, prompted by a report from outside the framework: the on-device planner research drives the real compiler as a ground-truth oracle, and while chasing a case where its checker accepted an edit the compiled page rejected, it found that Darkmown had two vocabularies for one concept and silently corrupted data when you picked the wrong one. No runtime change (7654 B gzipped, unchanged) and no breaking changes.
+
+- **BUGFIX: a persistence token on the wrong keyword was folded into the value.** `:store count = 0 persist` compiled clean and seeded the **string** `"0 persist"`. So did `:state count = 0 ephemeral`. Each handler stripped only its own token, so the other one stayed glued to the value and `parseStateValue`'s bare-string fallback (the one that makes `:state title = Hello world` work) turned a typo into data. Nothing failed at compile time, at load, or at first render; the page broke later, on the first `count++`, far from the line that caused it. That is the one failure mode a compile-error repair loop cannot see, which is why this is fixed as a language change rather than a new error message: the author wrote something unambiguous, so the compiler now honours it.
+- **`persist` and `ephemeral` are one vocabulary, on every keyword that has a value.** `persist` means "survives a reload" and `ephemeral` means "does not", and both are now accepted on `:state`, `:store`, and `:theme`. The keyword still picks the default (`:state` is ephemeral, `:store` and `:theme` persist); the token, when present, always means what it says. Writing the token that already matches the default is redundant but never wrong, so `:store cart = [] persist` compiles and states its intent on the line itself. Nothing that compiled before compiles differently, except the two corrupting forms above, which now do what they say. A value that genuinely ends in one of these words is quoted, the same escape hatch `:state` has always had.
+- **BUGFIX: `:computed … persist` reported a symbol the author never wrote.** The token was swallowed into the expression and surfaced as `[WD234] :computed references unknown state "persist"`, which names a phantom and points the fix exactly the wrong way. An agent reading that message will declare a state called `persist`, which compiles and is nonsense. It is now `WD211`, which names the real mistake: computed values are derived rather than stored, so persist the state they derive from instead. A page that genuinely declares state by that name still compiles as an ordinary reference, because the check is the same lookup the expression walker does.
+- **`WD004` now says where the persistence token goes on a multi-line literal.** It belongs after the closing bracket on the last line, not on the declaration line. That already worked and was documented nowhere, and guessing it wrong is what produced the unbalanced-literal error in the first place. The message now closes the loop unaided, and the `:state`/`:store` docs say it outright.
+
 ## 2.5.0 (2026-08-16)
 
 Everything Darkmown has shipped for AI authoring so far has been *description*: a directive catalog, a cheatsheet, a corpus, a GBNF grammar. All of it teaches a model to write a `.wd` file from scratch. None of it helps a model edit one it did not write, which is the operation an AI editor actually performs. This release adds the other half: a tool surface the model calls instead of rewriting whole files. No runtime change (7654 B gzipped, unchanged) and no breaking changes.

package/README.md

@@ -774,15 +774,30 @@ You have { cart } items.
 
   The literal must balance with no blank line inside it (a blank line ends the value); an unterminated literal is a compile error. Quote genuinely literal bracket text — `:state tag = "[draft]"`.
 
+  A `persist`/`ephemeral` token goes **after the closing bracket on the last line**, not on the declaration line:
+
+  ```wd
+  :state products = [
+    {"name": "Mug"}
+  ] persist
+  ```
+
 The declared value is a **seed**: it is used only the first time, when the store is absent from storage. After that the persisted value wins, so visitors keep their data.
 
-### Opt out of persistence
+### Choosing persistence
 
-Add `ephemeral` for an in-memory store that resets on reload and does not sync across tabs:
+`persist` means "survives a reload" and `ephemeral` means "does not". Both are accepted on `:state`, `:store`, and `:theme`; the keyword only picks the default:
 
-```wd
-:store sidebarOpen = false ephemeral
-```
+| Declaration | Persisted? |
+| --- | --- |
+| `:state count = 0` | no (the default) |
+| `:state count = 0 persist` | yes, in localStorage for this page |
+| `:store cart = []` | yes (the default), and synced across tabs |
+| `:store sidebarOpen = false ephemeral` | no, in-memory for the session |
+
+Writing the token that matches the default is redundant but never wrong, so `:store cart = [] persist` compiles and means exactly what it says. If a value genuinely ends in one of these words, quote it: `:state note = "0 persist"` seeds the string.
+
+`:computed` takes neither: computed values are derived rather than stored, so persist the state they derive from instead (that mistake is a compile error, `WD211`).
 
 > **Pitfall:** A store name must be unique. Declaring the same name as both a `:store` and a `:state` on one page is a compile error.
 
@@ -1066,8 +1081,8 @@ import { compileFromMemory } from "@zvndev/darkmown";
 try {
   compileFromMemory({ "site/pages/index.wd": ":state x" }, "site/pages/index.wd");
 } catch (err) {
-  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" }
+  err.message; // "[WD201] Malformed :state in …/index.wd:1: :state x. Use: :state name = value [persist|ephemeral] — e.g. :state count = 0"
+  err.wd;      // { code: "WD201", file: "…/index.wd", line: 1, hint: ":state name = value [persist|ephemeral] — e.g. …", example: ":state count = 0" }
 }
 ```
 
@@ -1079,7 +1094,7 @@ Every author-facing compile error opens with a stable `WDxxx` code, so it is sea
 
 ```
 [WD201] Malformed :state in site/pages/index.wd:1: :state x.
-        Use: :state name = value [persist] — e.g. :state count = 0
+        Use: :state name = value [persist|ephemeral] — 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:

package/docs/spec-alignment.md

@@ -63,7 +63,7 @@ The 1.3.0 cycle shipped the crawler *files* (sitemap, rss, robots). This closes
 
 - **`: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.
+- **`:state x = v persist`:** localStorage-backed state. This is the honest client-side slice of the original `:cart` primitive; server sync remains future work. Since 2.6.0 the persistence vocabulary is one vocabulary rather than two: `persist` and `ephemeral` are both accepted on `:state`, `:store`, and `:theme` with their literal meanings, and the keyword only picks the default. Before that each handler stripped only its own token and the other one folded into the value, so `:store count = 0 persist` silently seeded the string `"0 persist"` and first failed at the next `count++`. `:computed` accepts neither and says so (`WD211`) instead of reporting a phantom unknown state.
 - **`:if item.path` inside reactive loops:** per-row conditional branches, filled at compile time and re-filled by the keyed patcher. Conditionals **nest** — an inner `:if` is resolved after the outer branch, both at build time (balanced-region pre-render) and at runtime (recursive fill).
 - **`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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.5.1-next.10.g0f7c9b8",
+  "version": "2.6.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/pages/docs/index.wd

@@ -533,7 +533,9 @@ You have { cart } items.
 - The declared value is a **seed**, used only the first time — afterward the persisted value wins.
 - Same value grammar and the same button actions as `:state`.
 - An array/object seed may span **multiple lines** for readability — open the `[`/`{` on the directive line and let it run until it closes (no blank line inside; an unterminated literal is a compile error). Quote literal bracket text: `:state tag = "[draft]"`.
-- Add `ephemeral` for an in-memory store that resets on reload: `:store sidebarOpen = false ephemeral`.
+- On a multi-line seed, a `persist`/`ephemeral` token goes **after the closing bracket on the last line**, not on the declaration line.
+- `persist` means "survives a reload", `ephemeral` means "does not", and both are accepted on `:state`, `:store`, and `:theme`. The keyword only picks the default. `:store sidebarOpen = false ephemeral` is an in-memory store; `:state cart = [] persist` is a persisted one. Writing the token that matches the default is redundant but never wrong.
+- `:computed` takes neither: computed values are derived rather than stored, so persist the state they derive from instead (`WD211`).
 
 ## Forms and persistence
 

package/site/pages/store.wd

@@ -52,4 +52,25 @@ clean.
 
 Draft says: **{ draft }**
 
+## One vocabulary, either keyword
+
+`persist` means "survives a reload" and `ephemeral` means "does not". Both are
+accepted on `:state`, `:store`, and `:theme`. The **keyword** only picks the
+default, and the **token** always means what it says. So these two counters
+behave identically, and each one states its intent on the line itself.
+
+::: section #twins
+:state kept = 0 persist
+:store also = 0 persist
+
+Persisted `:state`: **{ kept }**, persisted `:store`: **{ also }**
+
+:button "Count the state" -> kept++
+:button "Count the store" -> also++
+
+Bump both, reload, and the pair comes back. Writing the token that already
+matches the default is redundant but never wrong, which is the point: a
+declaration you can read without remembering which keyword defaults which way.
+:::
+
 </main>

package/src/catalog.js

@@ -131,16 +131,17 @@ const DIRECTIVES = [
   {
     name: ":state",
     kind: "line",
-    syntax: ":state name = value [persist]",
-    description: "Declare page-scoped reactive state (persist keeps it across reloads).",
+    syntax: ":state name = value [persist|ephemeral]",
+    description:
+      "Declare page-scoped reactive state. Ephemeral by default; persist keeps it across reloads.",
     example: STATE_EXAMPLE,
     reactive: "reactive"
   },
   {
     name: ":store",
     kind: "line",
-    syntax: ":store name = value [ephemeral]",
-    description: "Declare a page-global store, persisted by default (ephemeral opts out).",
+    syntax: ":store name = value [persist|ephemeral]",
+    description: "Declare a page-global store. Persisted by default; ephemeral opts out.",
     example: STORE_EXAMPLE,
     reactive: "reactive"
   },

package/src/compiler/interpolation.js

@@ -154,7 +154,8 @@ export function parseStateValue(raw, where) {
         `Unbalanced JSON value "${shown}"${where ? ` in ${where}` : ""}: this opens "${open}" but ` +
           `never closes it. :state/:store/:theme accept a multi-line array/object, but the literal ` +
           `must balance (a "${close}" is missing) with no blank lines inside it. ` +
-          `Quote it for literal bracket text (e.g. = "[draft]").`,
+          `A persist/ephemeral token goes AFTER the closing "${close}" on the last line, ` +
+          `not on the declaration line. Quote it for literal bracket text (e.g. = "[draft]").`,
         { code: "WD004" }
       );
     }

package/src/compiler/state.js

@@ -10,7 +10,7 @@
 
 import { at, lineOf, recordSymbol, wdError } from "./context.js";
 import { astOf, evalAst } from "./expr-ast.js";
-import { escapeHtml, parseStateValue, safeScriptJson } from "./interpolation.js";
+import { escapeHtml, parseStateValue, resolveStateKey, safeScriptJson } from "./interpolation.js";
 import { compileComputedExpr } from "./predicates.js";
 
 /**
@@ -22,7 +22,29 @@ export const STATE_EXAMPLE = ":state count = 0";
 export const STORE_EXAMPLE = ":store cart = []";
 export const COMPUTED_EXAMPLE = ":computed total = items.length * 4";
 export const THEME_EXAMPLE = ":theme";
-const STATE_USE = `Use: :state name = value [persist] — e.g. ${STATE_EXAMPLE}`;
+const STATE_USE = `Use: :state name = value [persist|ephemeral] — e.g. ${STATE_EXAMPLE}`;
+
+// ---------------------------------------------------------------------------
+// PERSISTENCE IS ONE VOCABULARY, NOT TWO.
+//
+// `persist` means "survives a reload" and `ephemeral` means "does not", on every
+// keyword that has a value. The keyword picks the DEFAULT — `:state` is
+// ephemeral, `:store` and `:theme` persist — and the token, when present, always
+// means what it says.
+//
+// It did not always. Each handler used to strip only its own token, so the other
+// one stayed glued to the value and `parseStateValue`'s bare-string fallback
+// turned it into data: `:store count = 0 persist` seeded the STRING "0 persist",
+// compiled green, and first failed later at `count++`, far from the line that
+// caused it. That is the one failure mode a compile-error repair loop cannot see,
+// which is why this is a vocabulary change and not a new error message: the
+// author wrote something unambiguous, so the compiler honours it instead of
+// asking again.
+//
+// Text that genuinely ends in one of these words still quotes to keep it, the
+// same escape hatch `:state` has always had.
+// ---------------------------------------------------------------------------
+const PERSISTENCE = String.raw`(?:\s+(persist|ephemeral))?`;
 
 /**
  * @param {string} line
@@ -31,7 +53,9 @@ const STATE_USE = `Use: :state name = value [persist] — e.g. ${STATE_EXAMPLE}`
  * @returns {string}
  */
 export function handleState(line, ctx, index) {
-  const match = line.match(/^:state\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+persist)?$/);
+  const match = line.match(
+    new RegExp(String.raw`^:state\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)${PERSISTENCE}$`)
+  );
   if (!match)
     throw wdError(`Malformed :state in ${at(ctx, index)}: ${line}. ${STATE_USE}`, {
       code: "WD201",
@@ -43,7 +67,7 @@ export function handleState(line, ctx, index) {
   const value = parseStateValue(match[2], at(ctx, index));
   const key = declareState(match[1], value, ctx);
   recordSymbol(ctx, index, { kind: "state", name: key, detail: `${key} = ${match[2].trim()}` });
-  const persistAttr = match[3] ? ` data-wd-persist="${key}"` : "";
+  const persistAttr = match[3] === "persist" ? ` data-wd-persist="${key}"` : "";
   return `<script type="application/json" data-wd-state${persistAttr}>${safeScriptJson({ [key]: value })}</script>`;
 }
 
@@ -88,22 +112,24 @@ export function declareState(name, value, ctx) {
  * @returns {string}
  */
 export function handleStore(line, ctx, index) {
-  const match = line.match(/^:store\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+ephemeral)?$/);
+  const match = line.match(
+    new RegExp(String.raw`^:store\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)${PERSISTENCE}$`)
+  );
   if (!match)
     throw wdError(
-      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [persist|ephemeral] — e.g. ${STORE_EXAMPLE}`,
       {
         code: "WD205",
         file: ctx.file,
         line: lineOf(ctx, index),
-        hint: `:store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+        hint: `:store name = value [persist|ephemeral] — e.g. ${STORE_EXAMPLE}`,
         example: STORE_EXAMPLE
       }
     );
   const value = parseStateValue(match[2], at(ctx, index));
   const name = declareStore(match[1], value, ctx);
   recordSymbol(ctx, index, { kind: "store", name, detail: `${name} = ${match[2].trim()}` });
-  const ephemeral = match[3] ? " data-wd-store-ephemeral" : "";
+  const ephemeral = match[3] === "ephemeral" ? " data-wd-store-ephemeral" : "";
   return `<script type="application/json" data-wd-store="${name}"${ephemeral}>${safeScriptJson(value)}</script>`;
 }
 
@@ -171,7 +197,26 @@ export function handleComputed(line, ctx, index) {
       hint: COMPUTED_EXAMPLE,
       example: COMPUTED_EXAMPLE
     });
-  const expr = compileComputedExpr(match[2].trim(), ctx);
+  const raw = match[2].trim();
+  // A trailing bare `persist`/`ephemeral` used to be swallowed into the
+  // expression and surface as WD234 "references unknown state \"persist\"",
+  // which names something the author never wrote and points the fix the wrong
+  // way: a repair loop reading it will declare a state called `persist`, which
+  // compiles and is nonsense. `resolveStateKey` is the same lookup the
+  // expression walker does, so a page that really does declare state by that
+  // name still compiles as an ordinary reference.
+  const stray = raw.match(/\s+(persist|ephemeral)$/);
+  if (stray && !resolveStateKey(stray[1], ctx)) {
+    const hint = `:computed values are derived, not stored, so they cannot ${stray[1] === "persist" ? "persist" : "be ephemeral"}. Persist the state they derive from instead — e.g. :state count = 0 persist`;
+    throw wdError(`Persistence token on :computed in ${at(ctx, index)}: ${line}. ${hint}`, {
+      code: "WD211",
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: COMPUTED_EXAMPLE
+    });
+  }
+  const expr = compileComputedExpr(raw, ctx);
   // Parse the validated expression to the compact AST the runtime walks. A parse
   // failure means the RHS is syntactically malformed (e.g. `|| <`) — a compile
   // error, not a silently-broken binding.
@@ -214,7 +259,9 @@ export function handleComputed(line, ctx, index) {
  * @returns {string}
  */
 export function handleTheme(line, ctx, index) {
-  const match = line.match(/^:theme(?:\s+([A-Za-z_$][\w$]*))?(?:\s*=\s*(.+))?$/);
+  const match = line.match(
+    new RegExp(String.raw`^:theme(?:\s+([A-Za-z_$][\w$]*))?(?:\s*=\s*(.+?))?${PERSISTENCE}$`)
+  );
   if (!match) {
     throw wdError(
       `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
@@ -235,5 +282,6 @@ export function handleTheme(line, ctx, index) {
     name: storeName,
     detail: `${storeName} = ${JSON.stringify(seed)}`
   });
-  return `<script type="application/json" data-wd-store="${storeName}">${safeScriptJson(seed)}</script><span data-wd-theme="${storeName}" hidden></span>`;
+  const ephemeral = match[3] === "ephemeral" ? " data-wd-store-ephemeral" : "";
+  return `<script type="application/json" data-wd-store="${storeName}"${ephemeral}>${safeScriptJson(seed)}</script><span data-wd-theme="${storeName}" hidden></span>`;
 }

package/src/errors.js

@@ -367,7 +367,7 @@ const ENTRIES = [
   {
     code: "WD201",
     title: "Malformed `:state`",
-    cause: "The line does not read `:state name = value [persist]`.",
+    cause: "The line does not read `:state name = value [persist|ephemeral]`.",
     fix: "Give the state a name and an initial value.",
     example: STATE_EXAMPLE
   },
@@ -393,7 +393,7 @@ const ENTRIES = [
   {
     code: "WD205",
     title: "Malformed `:store`",
-    cause: "The line does not read `:store name = value [ephemeral]`.",
+    cause: "The line does not read `:store name = value [persist|ephemeral]`.",
     fix: "Give the store a name and an initial value.",
     example: STORE_EXAMPLE
   },
@@ -432,6 +432,13 @@ const ENTRIES = [
     fix: "Use a bare `:theme`, or name the store and seed it.",
     example: THEME_EXAMPLE
   },
+  {
+    code: "WD211",
+    title: "Persistence token on `:computed`",
+    cause: "The expression ends in a bare `persist` or `ephemeral`, which is swallowed into it.",
+    fix: "Computed values are derived, not stored. Persist the state they derive from instead.",
+    example: COMPUTED_EXAMPLE
+  },
   {
     code: "WD220",
     title: "Malformed `where` condition",
@@ -1109,7 +1116,7 @@ export function errorsMarkdown() {
   out.push("");
   out.push("```");
   out.push("[WD201] Malformed :state in site/pages/index.wd:1: :state x.");
-  out.push("        Use: :state name = value [persist] — e.g. :state count = 0");
+  out.push("        Use: :state name = value [persist|ephemeral] — e.g. :state count = 0");
   out.push("```");
   out.push("");
   out.push(