@zvndev/darkmown 2.1.0 → 2.2.0

package/src/compiler/state.js

@@ -8,7 +8,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at } from "./context.js";
+import { at, lineOf, wdError } from "./context.js";
 import { astOf, evalAst } from "./expr-ast.js";
 import { escapeHtml, parseStateValue, safeScriptJson } from "./interpolation.js";
 import { compileComputedExpr } from "./predicates.js";
@@ -17,6 +17,13 @@ import { compileComputedExpr } from "./predicates.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable one-liners for the state-family hint tails + the catalog.
+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}`;
+
 /**
  * @param {string} line
  * @param {Ctx} ctx
@@ -25,7 +32,13 @@ import { compileComputedExpr } from "./predicates.js";
  */
 export function handleState(line, ctx, index) {
   const match = line.match(/^:state\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+persist)?$/);
-  if (!match) throw new Error(`Malformed :state in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed :state in ${at(ctx, index)}: ${line}. ${STATE_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: STATE_USE.slice("Use: ".length),
+      example: STATE_EXAMPLE
+    });
   const value = parseStateValue(match[2], at(ctx, index));
   const key = declareState(match[1], value, ctx);
   const persistAttr = match[3] ? ` data-wd-persist="${key}"` : "";
@@ -43,8 +56,13 @@ export function declareState(name, value, ctx) {
   if (ctx.loopItem)
     throw new Error(`State cannot be declared inside a reactive @loop body (${ctx.file})`);
   if (ctx.comp.stores.has(name))
-    throw new Error(
-      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    throw wdError(
+      `State "${name}" collides with a :store of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        hint: `:store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   const key = ctx.sections.length ? `${ctx.sections.at(-1)}:${name}` : name;
   if (ctx.comp.state.has(key))
@@ -63,8 +81,14 @@ export function declareState(name, value, ctx) {
 export function handleStore(line, ctx, index) {
   const match = line.match(/^:store\s+([A-Za-z_$][\w$]*)\s*=\s*(.+?)(\s+ephemeral)?$/);
   if (!match)
-    throw new Error(
-      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral]`
+    throw wdError(
+      `Malformed :store in ${at(ctx, index)}: ${line}. Use: :store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:store name = value [ephemeral] — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   const value = parseStateValue(match[2], at(ctx, index));
   const name = declareStore(match[1], value, ctx);
@@ -83,10 +107,22 @@ export function handleStore(line, ctx, index) {
  */
 export function declareStore(name, value, ctx) {
   if (ctx.comp.stores.has(name))
-    throw new Error(`Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value`);
+    throw wdError(
+      `Store "${name}" is declared twice in ${ctx.file}. Use: :store name = value — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        hint: `:store name = value — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
+    );
   if (ctx.comp.state.has(name))
-    throw new Error(
-      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one.`
+    throw wdError(
+      `Store "${name}" collides with a :state of the same name in ${ctx.file}. Use: :store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+      {
+        file: ctx.file,
+        hint: `:store name = value for the global, or rename one — e.g. ${STORE_EXAMPLE}`,
+        example: STORE_EXAMPLE
+      }
     );
   ctx.comp.stores.add(name);
   ctx.comp.state.set(name, value);
@@ -115,9 +151,12 @@ export function declareErrorState(key, ctx) {
 export function handleComputed(line, ctx, index) {
   const match = line.match(/^:computed\s+([A-Za-z_$][\w$]*)\s*=\s*(.+)$/);
   if (!match)
-    throw new Error(
-      `Malformed :computed in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
-    );
+    throw wdError(`Malformed :computed in ${at(ctx, index)}: ${line}. Use: ${COMPUTED_EXAMPLE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: COMPUTED_EXAMPLE,
+      example: COMPUTED_EXAMPLE
+    });
   const expr = compileComputedExpr(match[2].trim(), 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
@@ -127,8 +166,14 @@ export function handleComputed(line, ctx, index) {
   try {
     ast = astOf(expr);
   } catch {
-    throw new Error(
-      `Malformed :computed expression in ${at(ctx, index)}: ${line}. Use: :computed total = items.length * 4`
+    throw wdError(
+      `Malformed :computed expression in ${at(ctx, index)}: ${line}. Use: ${COMPUTED_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: COMPUTED_EXAMPLE,
+        example: COMPUTED_EXAMPLE
+      }
     );
   }
   // Build-time mirror of the runtime: walk the AST (no eval) so `:computed total =
@@ -155,8 +200,14 @@ export function handleComputed(line, ctx, index) {
 export function handleTheme(line, ctx, index) {
   const match = line.match(/^:theme(?:\s+([A-Za-z_$][\w$]*))?(?:\s*=\s*(.+))?$/);
   if (!match) {
-    throw new Error(
-      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto")`
+    throw wdError(
+      `Malformed :theme in ${at(ctx, index)}: ${line}. Use: :theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
+      {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint: `:theme  (or  :theme name = "auto") — e.g. ${THEME_EXAMPLE}`,
+        example: THEME_EXAMPLE
+      }
     );
   }
   const name = match[1] || "theme";

package/src/compiler/structure.js

@@ -11,7 +11,7 @@
 // while keeping the message text and `Use:` hints intact.
 // ---------------------------------------------------------------------------
 
-import { at, createScope, LOOP_META, nestedCtx } from "./context.js";
+import { at, createScope, LOOP_META, lineOf, nestedCtx, wdError } from "./context.js";
 import { astOf, serializeExpr } from "./expr-ast.js";
 import { resolveInclude, scopedSkinFor, stampScope } from "./includes.js";
 import {
@@ -28,6 +28,13 @@ import { compileWhen, evalPredicate } from "./predicates.js";
  * @typedef {import("./context.js").Ctx} Ctx
  */
 
+// Concrete, compilable structure examples for the hint tails + the catalog.
+export const INCLUDE_EXAMPLE = "@include /header.wd";
+export const CONTAINER_EXAMPLE = "::: card .featured";
+export const IF_EXAMPLE = ":if count > 0";
+export const CAROUSEL_EXAMPLE = ":carousel autoplay=3000";
+const INCLUDE_USE = `Use: @include /partial.wd [with key="value"] — e.g. ${INCLUDE_EXAMPLE}`;
+
 // Container names that emit their own semantic landmark element instead of a
 // `<div>`, so scaffolds get real `<nav>`/`<main>` landmarks (accessibility: the
 // skip link targets a genuine main-content region and navigation chrome sits in
@@ -44,7 +51,13 @@ const SEMANTIC_CONTAINER_TAGS = new Set(["nav", "main"]);
  */
 export function handleInclude(line, ctx, index) {
   const match = line.match(/^@include\s+(\S+)(?:\s+with\s+(.+))?$/);
-  if (!match) throw new Error(`Malformed @include in ${at(ctx, index)}: ${line}`);
+  if (!match)
+    throw wdError(`Malformed @include in ${at(ctx, index)}: ${line}. ${INCLUDE_USE}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint: INCLUDE_USE.slice("Use: ".length),
+      example: INCLUDE_EXAMPLE
+    });
   const target = resolveInclude(
     match[1],
     ctx.file,
@@ -215,10 +228,15 @@ export function handleCarousel(line, bodyLines, ctx, index) {
   let autoplayAttr = "";
   if (rest) {
     const auto = rest.match(/^autoplay=(\d+)$/);
-    if (!auto)
-      throw new Error(
-        `Malformed :carousel in ${at(ctx, index)}: ${line}. Use: :carousel [autoplay=3000] … :endcarousel`
-      );
+    if (!auto) {
+      const hint = `:carousel [autoplay=3000] … :endcarousel — e.g. ${CAROUSEL_EXAMPLE}`;
+      throw wdError(`Malformed :carousel in ${at(ctx, index)}: ${line}. Use: ${hint}`, {
+        file: ctx.file,
+        line: lineOf(ctx, index),
+        hint,
+        example: CAROUSEL_EXAMPLE
+      });
+    }
     autoplayAttr = ` data-wd-carousel-autoplay="${auto[1]}"`;
   }
   ctx.comp.assets.behaviors.add("carousel");
@@ -323,10 +341,15 @@ export function handleIf(line, truthyLines, falsyLines, ctx, index, falsyStart =
   // whitelist as `@loop … where` / `.class when` (with `not`), so it folds at
   // build when static, drives a per-row each-if when it reads the loop item, and
   // a global if-region (evaluated each render) when it reads state. No raw eval.
-  if (!condition)
-    throw new Error(
-      `Malformed :if in ${at(ctx, index)}: ${line}. Use ":if name" or ":if a <op> b [and|or|not …]".`
-    );
+  if (!condition) {
+    const hint = `":if name" or ":if a <op> b [and|or|not …]" — e.g. ${IF_EXAMPLE}`;
+    throw wdError(`Malformed :if in ${at(ctx, index)}: ${line}. Use ${hint}`, {
+      file: ctx.file,
+      line: lineOf(ctx, index),
+      hint,
+      example: IF_EXAMPLE
+    });
+  }
   const compiled = compileWhen(condition, ctx, '":if"');
   if (compiled.static)
     return ctx.compileBody(

package/src/grammar.js

@@ -0,0 +1,131 @@
+// ---------------------------------------------------------------------------
+// GBNF grammar generator for `.wd` DIRECTIVE LINES.
+//
+// `generateGrammar()` emits a llama.cpp-compatible GBNF grammar that constrains
+// a small model's decoding to well-formed Darkmown directive lines (plus the
+// `{ path | pipe }` interpolation token). It is generated from the SAME catalog
+// the cheatsheet uses, so the keyword set, `@loop` clauses, comparison operators,
+// and format-pipe names can never drift from what compiles.
+//
+// Scope (stated deliberately): this grammar constrains the SHAPE of a directive
+// line — the leading keyword must be a real directive, `@loop` must be
+// `@loop <src> into <item> …clauses`, a `where`/`:if` condition must be
+// `operand <op> operand`, a `:button` must be `"…" -> <action-chain>`, and an
+// interpolation must pipe through a known formatter. It does NOT try to grammar-
+// check free-form values (arbitrary JSON seeds, URLs, prose) — those are `text`.
+// That is enough to delete the on-device failure class (JS/HTML muscle-memory
+// openers like `::: card class=` or `cart.filter(...)` become unrepresentable)
+// while staying small and maintainable.
+// ---------------------------------------------------------------------------
+
+import { directiveCatalog } from "./catalog.js";
+
+/** Slugify a directive token into a GBNF rule name (`@loop` → `dir-loop`). */
+/** @type {Record<string, string>} */
+const SLUG = {
+  "@include": "dir-include",
+  "@loop": "dir-loop",
+  ":::": "dir-container",
+  ":if": "dir-if",
+  ":state": "dir-state",
+  ":store": "dir-store",
+  ":computed": "dir-computed",
+  ":fetch": "dir-fetch",
+  ":effect": "dir-effect",
+  ":every": "dir-every",
+  ":theme": "dir-theme",
+  ":button": "dir-button",
+  ":form": "dir-form",
+  ":input": "dir-input",
+  ":textarea": "dir-textarea",
+  ":select": "dir-select",
+  ":checkbox": "dir-checkbox",
+  ":radio": "dir-radio",
+  ":submit": "dir-submit",
+  ":bind": "dir-bind",
+  ":slider": "dir-slider",
+  ":video": "dir-video",
+  ":audio": "dir-audio",
+  ":embed": "dir-embed",
+  ":carousel": "dir-carousel"
+};
+
+// The directives given a structured RHS below; every other directive gets the
+// generic `"<keyword>" restofline` rule (keyword pinned, argument tail free).
+const STRUCTURED = new Set(["@loop", ":if", ":button", ":::"]);
+
+/** A GBNF alternation literal list, e.g. `"a" | "b"`. */
+const alt = (/** @type {string[]} */ items) => items.map((s) => `"${s}"`).join(" | ");
+
+/**
+ * Generate the GBNF grammar for `.wd` directive lines from the directive catalog.
+ * @returns {string}
+ */
+export function generateGrammar() {
+  const cat = directiveCatalog();
+  const dirRules = cat.directives.map((d) => SLUG[d.name]).filter(Boolean);
+
+  /** @type {string[]} */
+  const lines = [];
+  lines.push("# Darkmown .wd directive-line grammar — generated by src/grammar.js");
+  lines.push(
+    "# Constrains a directive line (or a { path | pipe } interpolation). Do not edit by hand."
+  );
+  lines.push("");
+  lines.push("root ::= directive | binding");
+  lines.push(`directive ::= ${dirRules.join(" | ")}`);
+  lines.push("");
+
+  // Structured directives.
+  lines.push('dir-loop ::= "@loop" sp operand sp "into" sp ident loop-clauses');
+  lines.push('dir-if ::= ":if" sp ( condition (sp joiner sp condition)* | path )');
+  lines.push('dir-button ::= ":button" sp dqstring sp "->" sp action-chain');
+  lines.push('dir-container ::= ":::" restofline');
+  lines.push("");
+
+  // Generic directives: keyword pinned, argument tail free to end of line.
+  for (const d of cat.directives) {
+    if (STRUCTURED.has(d.name)) continue;
+    lines.push(`${SLUG[d.name]} ::= "${d.name}" restofline`);
+  }
+  lines.push("");
+
+  // @loop clause vocabulary (mirrors the fixed clause order in the catalog).
+  lines.push("loop-clauses ::= ( sp loop-clause )*");
+  lines.push(
+    'loop-clause ::= where-clause | "sort by" sp path ( sp ( "asc" | "desc" ) )? | "reverse" | "offset" sp number | "limit" sp number | "paginate" sp number | "sortable"'
+  );
+  lines.push('where-clause ::= "where" sp condition ( sp joiner sp condition )*');
+  lines.push("condition ::= operand sp op sp operand");
+  lines.push(`op ::= ${alt(cat.predicateOps.map((o) => o.name))}`);
+  lines.push(`joiner ::= ${alt(cat.predicateJoiners.filter((j) => j !== "not"))}`);
+  lines.push("");
+
+  // Button-action vocabulary. Each operator token below is asserted present
+  // against the catalog's action tokens in tests/grammar.test.js.
+  lines.push('action-chain ::= action ( wsopt ";" wsopt action )*');
+  lines.push("action ::= ident action-op");
+  lines.push(
+    'action-op ::= "++" | "--" | sp "+=" sp value | sp "-=" sp value | sp "=" sp value | sp "toggle" ( sp value )? | sp "append" sp value | sp "prepend" sp value | sp "remove" sp value | sp "clear" | sp "merge" sp ident | sp "delete" sp value | sp "reset" | sp "refetch"'
+  );
+  lines.push("");
+
+  // Interpolation binding with format pipes.
+  lines.push('binding ::= "{" wsopt path pipe-chain wsopt "}"');
+  lines.push('pipe-chain ::= ( wsopt "|" wsopt pipe ( ":" value )* )*');
+  lines.push(`pipe ::= ${alt(cat.formatPipes.map((p) => p.name))}`);
+  lines.push("");
+
+  // Terminals.
+  lines.push("operand ::= path | dqstring | number");
+  lines.push("value ::= dqstring | number | path");
+  lines.push("ident ::= [a-zA-Z_$] [a-zA-Z0-9_$]*");
+  lines.push("path ::= [a-zA-Z0-9_$/.~-]+");
+  lines.push("number ::= [0-9]+");
+  lines.push('dqstring ::= "\\"" [^"]* "\\""');
+  lines.push("restofline ::= [^\\n]*");
+  lines.push('sp ::= " "+');
+  lines.push('wsopt ::= " "*');
+  lines.push("");
+  return lines.join("\n");
+}

package/src/index.js

@@ -4,6 +4,7 @@
 // `exports` map; individual modules stay importable by their own path too.
 
 export { buildSite } from "./builder.js";
+export { directiveCatalog, llmsText } from "./catalog.js";
 
 export {
   compileDocument,