@spintax/core 0.1.6 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,154 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.0 — 2026-07-19
+
+`#set` goes back to being a macro and a new `#def` carries roll-once. Breaking: it changes what
+existing templates mean. Ships in lockstep with the WordPress plugin 3.0.0, `spintax/core` and the
+OpenCart port; the corpus landed last, after both PHP engines.
+
+### Changed
+
+- **`#set` is a macro.** The value is substituted at every `%var%` reference and whatever brackets
+  it holds resolve independently each time. Until now an enumeration-valued `#set` collapsed once at
+  set-time; that behaviour moved to `#def`.
+
+  Worth recording *why* the revert, because the reasoning is not recoverable from the diff:
+  collapse-once was the newcomer. It shipped in the plugin on 2026-07-04, was announced in one
+  changelog line, and contradicted the project's published documentation from the day it landed.
+  Macro expansion is what the engine did before that and what consumers written against those docs
+  assume.
+
+- **`AST_VERSION` 1 → 2.** `ParsedAst` gained `defDefs`. An `Ast` cached by an older version carries
+  no definition map, so rendering it would silently drop every `#def`; the version guard turns that
+  into an `AstVersionError` instead.
+
+- **`extract()` reports `defs`** alongside `sets`. Additive for readers, but a consumer building a
+  variable list from `sets` alone will now miss `#def` names.
+
+- **`plural.nested-brackets` advice.** "Extract via `#set` first" was correct under collapse-once and
+  is wrong under a macro — the value is substituted verbatim and puts the brackets straight back into
+  the form slot, raising the very error it was meant to avoid. It now says `#def`.
+
+### Added
+
+- **`#def %var% = value` — roll-once.** The value is rendered once per render, as if it were a
+  miniature body, and the result is held for every reference. It covers enumerations *and*
+  permutations, resolves **after** the merged context exists (so it can read globals and runtime
+  variables; a runtime variable of the same name outranks it), and resolves in dependency order —
+  an order that follows aliases **through** macro values, since a `#def` can reach another `#def` by
+  way of a `#set` expanded only at reference time.
+
+  This is where a plural counter now lives: `#def %n% = {1|4|9}` then `{plural %n%: …}` prints and
+  agrees the same number. Under `#set` the two disagree and the block is dropped.
+
+- **Four diagnostics**: `def.malformed`, `definition.duplicate-name` (a name belongs to one
+  directive, once — this also closes silently-last-wins duplicate `#set`s), `def.include-in-value`
+  (includes resolve after a value is frozen; legal inside a `#set`), and `plural.count-macro`.
+
+  `plural.count-macro` is decided by **stage order, not bracket type**: conditionals resolve before
+  plurals and are exempt, enumerations and permutations resolve after and are not, and a nested
+  `{plural …}` resolves in the *same* pass so it is not exempt either. Taint propagates through
+  `#set` → `#set` references to a fixpoint.
+
+### Corpus
+
+The difference between the directives is a difference in how many RNG draws a render consumes, so
+seeded-sequence fixtures pin it exactly and cross-engine — `set/macro-re-rolls-at-every-reference`
+and `def/rolled-once-and-held` share a template and a sequence and differ only in whether the second
+draw is reached. The corpus grew 138 → 160 cases, green against this engine, the WordPress plugin
+and `spintax/core`.
+
+The previous rule here said collapse could only be pinned with RNG-free values, and the consequence
+was that **nothing pinned it at all**: the semantics flipped in the plugin without a single fixture
+noticing. All-identical alternatives are not sufficient either — they render the same under both
+semantics and would pass against an engine implementing `#def` as an alias of `#set`.
+
+### Migration
+
+A `#set` whose value is an enumeration or permutation *and* which is referenced more than once for
+consistency — a plural counter, a brand name that must not vary mid-sentence — becomes `#def`. One
+line per definition; references are untouched.
+
+## 0.2.0 — 2026-07-18
+
+Serbian, Croatian and Bosnian join the 3-form plural family; the plural error model and the
+locale helpers that go with it land in the same release. Minor, not patch: the BCS change
+below alters a **validation verdict**, which §0.1 classes as breaking.
+
+Nothing here shipped separately — 0.2.0 was never published, so these additions fold into it
+rather than minting a version between them. That matters for `@spintax/authoring-prompt`,
+whose peer range `>=0.2.0` would otherwise be satisfiable by a 0.2.0 without the exports it
+now imports at runtime.
+
+### Added
+
+- **`pluralArity(locale?)` and `normalizeBaseLang(locale?)` are public.** Exported so a
+  consumer that must AGREE with the engine about plurals can ask it instead of keeping a copy
+  of the table. The copy is not hypothetical: this repo's own authoring prompt kept one and it
+  drifted twice — once in content (a locale added here and not there) and once in shape
+  (`locale.slice(0, 2)`, which disagrees with this normalization on any 3-letter tag).
+
+  `pluralArity` takes a RAW locale and normalizes internally, unlike the internal helper of the
+  same name — a public function answering 2 for `sr-Latn` would be a trap. Both accept an absent
+  locale, matching `RenderOptions.locale?` / `ValidateOptions.locale?`, so the same optional
+  value can be threaded straight through.
+
+  Note one asymmetry: an absent locale makes `validate()` skip the arity check entirely, while
+  `pluralArity` answers the 2-form default `render()` would apply. It tells you what render will
+  do, not what validate will enforce.
+
+  `findPluralBlocks` is deliberately NOT exported alongside them — it returns byte offsets into
+  the source, and publishing it would freeze a parser internal and invite consumers onto the
+  parse layer, the same reason `Ast` is opaque.
+
+- **`RenderOptions.onPluralError` — an observer for unresolvable `{plural …}` blocks.**
+  The port of the plugin's `on_error` callable, and the missing half of its error model:
+  this engine already behaved exactly like the plugin's *lenient* mode (arity mismatch and
+  nested-bracket errors degrade to fullwidth-brace verbatim, an unresolved count erases the
+  block), but there was no way to learn that it had happened.
+
+  Observation only. Output is byte-identical with and without the callback, and `render()`
+  still never throws on template content (§9.3) — the host decides whether a report is
+  fatal. A report carries the diagnostic `code`, the construct **as the renderer saw it**
+  (after variable expansion), the normalized `locale`, and `expected`/`got` for arity.
+
+  The `plural.count` code has no `validate()` counterpart on purpose: an unresolved count is
+  a runtime-value fact that static analysis cannot see. It is also the case that most needs
+  the seam — erasing leaves no trace, so a host persisting a render otherwise cannot tell an
+  unsubstituted `%Var%` from copy that was meant to be empty.
+
+- **BCS plural buckets — `sr`, `hr`, `bs`.** On integers, BCS shares the East-Slavic rule
+  character for character (`mod10===1 && mod100!==11` → one; `mod10∈[2,4] && mod100∉[12,14]`
+  → few; else → many), so it reuses that branch rather than getting its own. CLDR names the
+  third bucket `other` rather than `many` — positionally the same slot. The genuine
+  BCS/East-Slavic divergence is fractional-only and unreachable here, since a non-numeric
+  count slot is erased to `''` before the bucket math (§3.1).
+
+  **Script and region subtags carry no plural grammar.** `sr-Latn`, `sr-Cyrl` and `sr_RS` all
+  normalise to `sr` and pick identical buckets; the script lives only in the author's form text.
+  Corpus fixtures pin each form, and the arity fixtures pin that a script subtag does not rescue
+  a 2-form template. The ladder runs past two digits, where `mod100` has to beat `mod10`: 101 is
+  `one`, 111 is not.
+
+  Render fixtures probe with `sat` (1 sat / 2 sata / 5 sati) because all three buckets differ
+  there. The tempting `bonus|bonusa|bonusa` collapses few and other, so it would pass against a
+  broken rule.
+
+  Landed in all three engines at once — `@spintax/core`, the WordPress plugin 2.5.0, and
+  `spintax/core` 0.2.0 — because plural buckets are a parity-required item and the golden
+  corpus gates every engine.
+
+### Changed
+
+- **BREAKING (verdict): `{plural 2: one|many}` under `sr`/`hr`/`bs` is now `plural.arity`.**
+  Previously these locales fell through to the EN-style 2-form default, so a 2-form BCS
+  template validated clean and rendered from the wrong bucket set. Any existing BCS template
+  must grow a third form. No other locale changes behaviour.
+- The LLM authoring prompt (`@spintax/authoring-prompt`) now emits a BCS grammar block —
+  agreement rules, the 3-bucket warning, and a "do not mix Latin and Cyrillic inside one
+  template" rule. Without it a model writes 2-form BCS that the validator then rejects.
+
 ## 0.1.6 — 2026-07-13
 
 Two post-process fixes. **Supersedes 0.1.5** — upgrade straight past it. No API change.

package/README.md

@@ -17,8 +17,8 @@ parse, render, validate, extract, analyze, and neutralize spintax templates.
 - **Parity-verified against the [Spintax WordPress plugin](https://wordpress.org/plugins/spintax/).**
   An *independent* TypeScript implementation (not a line-by-line port) held to the plugin's behavior
   contract by a shared golden corpus — the **same** fixtures pass against both this engine and the
-  PHP plugin (deterministic verdicts, plural buckets, conditionals, `#set` collapse, post-process),
-  with no divergence.
+  PHP plugin (deterministic verdicts, plural buckets, conditionals, `#set`/`#def` semantics,
+  post-process), with no divergence.
 - **MIT** licensed.
 
 > **Status: released & stable.** Feature-complete — parse / render / validate / extract / analyze /
@@ -77,7 +77,8 @@ dedupe in the host and cap the retries: a template may simply not have N combina
 | Enumeration | `{a\|b\|c}` | pick one (nestable: `{a\|{b\|c}}`) |
 | Permutation | `[a\|b\|c]` | pick N, shuffle, join — `[<minsize=1;maxsize=2;sep=", ">a\|b\|c]` |
 | Variable | `%var%` | substitute a context value |
-| Local set | `#set %v% = value` | define a variable (one line) |
+| Local set | `#set %v% = value` | define a macro — re-picked at every use |
+| Local def | `#def %v% = value` | define a value — picked once per render, held at every use |
 | Conditional | `{?VAR?then\|else}` | `then` if `VAR` is truthy, else `else` |
 | Plural | `{plural %n%: one\|few\|many}` | grammatical agreement by locale |
 | Include | `#include "slug-or-id"` | embed another template (host-resolved) |

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 // src/internal/ast.ts
-var AST_VERSION = 1;
+var AST_VERSION = 2;
 function walk(nodes, visit) {
   for (const n of nodes) {
     visit(n);
@@ -25,21 +25,39 @@ function isParsedAst(value) {
 
 // src/internal/parser.ts
 var VARIABLE_RE = /^%(\w+)%/;
-var SET_DIRECTIVE_RE = /^[ \t]*#set[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)[ \t]*\r?$/gmu;
+var DIRECTIVE_RE = /^[ \t]*#(set|def)[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)[ \t]*\r?$/gmu;
 var CONDITIONAL_NAME_RE = /^[A-Za-z_]\w*/;
 var PLURAL_PREFIX = "plural ";
 function parseTemplate(src) {
-  const { body, setDefs } = extractSetDirectives(stripComments(src));
-  return { astVersion: AST_VERSION, source: src, setDefs, nodes: parseSequence(body) };
+  const { body, setDefs, defDefs } = extractDirectives(stripComments(src));
+  return { astVersion: AST_VERSION, source: src, setDefs, defDefs, nodes: parseSequence(body) };
 }
-function extractSetDirectives(text) {
+function extractDirectives(text) {
   const setDefs = {};
-  SET_DIRECTIVE_RE.lastIndex = 0;
-  const stripped = text.replace(SET_DIRECTIVE_RE, (_full, name, value) => {
-    setDefs[name.toLowerCase()] = value;
-    return "";
-  });
-  return { body: stripped.replace(/\n{3,}/gu, "\n\n"), setDefs };
+  const defDefs = {};
+  const occurrences = [];
+  DIRECTIVE_RE.lastIndex = 0;
+  const stripped = text.replace(
+    DIRECTIVE_RE,
+    (full, kind, rawName, value, offset) => {
+      const name = rawName.toLowerCase();
+      occurrences.push({
+        kind,
+        name,
+        value,
+        line: countLines(text, offset)
+      });
+      if (kind === "def") defDefs[name] = value;
+      else setDefs[name] = value;
+      return "";
+    }
+  );
+  return { body: stripped.replace(/\n{3,}/gu, "\n\n"), setDefs, defDefs, occurrences };
+}
+function countLines(text, offset) {
+  let line = 1;
+  for (let i = 0; i < offset; i += 1) if (text[i] === "\n") line += 1;
+  return line;
 }
 function stripComments(text) {
   return text.replace(/\/#[\s\S]*?#\//g, "");
@@ -344,6 +362,9 @@ function pluralArity(baseLang) {
     case "ru":
     case "uk":
     case "be":
+    case "sr":
+    case "hr":
+    case "bs":
       return 3;
     default:
       return 2;
@@ -357,6 +378,9 @@ function pluralFor(baseLang, n, forms) {
     case "ru":
     case "uk":
     case "be":
+    case "sr":
+    case "hr":
+    case "bs":
       if (mod10 === 1 && mod100 !== 11) return forms[0] ?? "";
       if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return forms[1] ?? "";
       return forms[2] ?? "";
@@ -372,7 +396,7 @@ function validateTemplate(src, opts = {}) {
   const diagnostics = [];
   const text = stripComments(src);
   checkBrackets(text, diagnostics);
-  checkSetDirectives(text, diagnostics);
+  checkDirectives(text, diagnostics);
   checkPermutationConfigs(text, diagnostics);
   checkPlurals(text, opts.locale, diagnostics);
   checkVariableReferences(text, opts.knownVariables, diagnostics);
@@ -431,17 +455,43 @@ function checkBrackets(text, out) {
     out.push(err("bracket.unclosed", `Unclosed '${unclosed.char}'.`, { line: unclosed.line, column: unclosed.column, endLine: unclosed.line, endColumn: unclosed.column + 1, data: { bracket: unclosed.char } }));
   }
 }
-function checkSetDirectives(text, out) {
+function checkDirectives(text, out) {
   const lines = text.split("\n");
   lines.forEach((lineText, idx) => {
     const trimmed = lineText.replace(/^[ \t]+/, "");
-    if (!trimmed.startsWith("#set ") && !trimmed.startsWith("#set	")) return;
-    if (!/^#set\s+%(\w+)%\s*=\s*(.+)$/u.test(trimmed)) {
+    const kind = ["#set", "#def"].find(
+      (candidate) => trimmed.startsWith(`${candidate} `) || trimmed.startsWith(`${candidate}	`)
+    );
+    if (!kind) return;
+    DIRECTIVE_RE.lastIndex = 0;
+    if (!DIRECTIVE_RE.test(trimmed)) {
       const column = lineText.length - trimmed.length + 1;
       const line = idx + 1;
-      out.push(err("set.malformed", "Malformed #set. Expected: #set %name% = value", { line, column, endLine: line, endColumn: lineText.length + 1 }));
+      const code = kind === "#def" ? "def.malformed" : "set.malformed";
+      out.push(err(code, `Malformed ${kind}. Expected: ${kind} %name% = value`, { line, column, endLine: line, endColumn: lineText.length + 1 }));
     }
   });
+  const { occurrences } = extractDirectives(text);
+  const seen = /* @__PURE__ */ new Map();
+  for (const occurrence of occurrences) {
+    const first = seen.get(occurrence.name);
+    if (first !== void 0) {
+      out.push(err(
+        "definition.duplicate-name",
+        `Variable '${occurrence.name}' is defined more than once (first on line ${first}). A name belongs to one directive, once.`,
+        { line: occurrence.line, column: 1 }
+      ));
+    } else {
+      seen.set(occurrence.name, occurrence.line);
+    }
+    if (occurrence.kind === "def" && /#include\b/u.test(occurrence.value)) {
+      out.push(err(
+        "def.include-in-value",
+        `#include cannot appear in a #def value ('${occurrence.name}'): includes resolve after the value is frozen. Use #set, or put the #include in the body.`,
+        { line: occurrence.line, column: 1 }
+      ));
+    }
+  }
 }
 function checkPermutationConfigs(text, out) {
   for (const m of text.matchAll(/\[<([^>]*?)>/gu)) {
@@ -479,10 +529,20 @@ function checkPermutationConfigs(text, out) {
 function checkPlurals(text, locale, out) {
   const base = locale && locale !== "" ? normalizeBaseLang(locale) : "";
   const arity = base !== "" ? pluralArity(base) : 0;
+  const tainted = macroTaintedNames(text);
   for (const block of findPluralBlocks(text)) {
     const at = span(text, block.start, block.end - block.start);
+    for (const m of block.countSlot.matchAll(/%(\w+)%/gu)) {
+      const name = (m[1] ?? "").toLowerCase();
+      if (!tainted.has(name)) continue;
+      out.push(err(
+        "plural.count-macro",
+        `{plural ...}: the count '${m[1]}' is a #set macro, so it is still unresolved spintax when the plural is decided and the block renders empty. Define it with #def instead.`,
+        at
+      ));
+    }
     if (/[{}[\]]/.test(block.formsRaw)) {
-      out.push(err("plural.nested-brackets", "{plural ...}: forms must not contain nested spintax brackets.", at));
+      out.push(err("plural.nested-brackets", "{plural ...}: forms must not contain nested spintax brackets. Extract via #def first \u2014 a #set is substituted verbatim and would put the brackets straight back.", at));
       continue;
     }
     if (arity > 0) {
@@ -497,11 +557,33 @@ function checkPlurals(text, locale, out) {
     }
   }
 }
+var UNRESOLVED_AT_PLURAL_TIME = /\[|\{(?!\?)/u;
+function macroTaintedNames(text) {
+  const macros = extractDirectives(text).setDefs;
+  const tainted = /* @__PURE__ */ new Set();
+  for (const [name, value] of Object.entries(macros)) {
+    if (UNRESOLVED_AT_PLURAL_TIME.test(value)) tainted.add(name);
+  }
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const [name, value] of Object.entries(macros)) {
+      if (tainted.has(name)) continue;
+      for (const m of value.matchAll(/%(\w+)%/gu)) {
+        if (!tainted.has((m[1] ?? "").toLowerCase())) continue;
+        tainted.add(name);
+        grew = true;
+        break;
+      }
+    }
+  }
+  return tainted;
+}
 function checkVariableReferences(text, known, out) {
   const knownSet = new Set((known ?? []).map((n) => n.toLowerCase()));
   const defs = /* @__PURE__ */ new Map();
   const defPos = /* @__PURE__ */ new Map();
-  for (const m of text.matchAll(/^[ \t]*#set[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)$/gmu)) {
+  for (const m of text.matchAll(/^[ \t]*#(?:set|def)[ \t]+%(\w+)%[ \t]*=[ \t]*(.*?)$/gmu)) {
     const name = (m[1] ?? "").toLowerCase();
     defs.set(name, m[2] ?? "");
     const nameOffset = (m.index ?? 0) + m[0].indexOf("%");
@@ -516,7 +598,7 @@ function checkVariableReferences(text, known, out) {
   for (const name of defs.keys()) {
     detectCycle(name, defs, [name], defPos.get(name) ?? somewhere, out);
   }
-  const body = text.replace(/^[ \t]*#set[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
+  const body = text.replace(/^[ \t]*#(?:set|def)[ \t]+%\w+%[ \t]*=[ \t]*.*?$/gmu, (m) => m.replace(/[^\n]/g, " "));
   const seen = /* @__PURE__ */ new Set();
   const undefinedAt = (name, offset, length) => {
     const key = name.toLowerCase();
@@ -563,19 +645,21 @@ function checkIncludeTargets(text, known, out) {
 
 // src/internal/extract.ts
 var SET_DEF_RE = /^[ \t]*#set[ \t]+%(\w+)%[ \t]*=/gmu;
-var SET_LHS_RE = /^[ \t]*#set[ \t]+%\w+%[ \t]*=/gmu;
+var DEF_DEF_RE = /^[ \t]*#def[ \t]+%(\w+)%[ \t]*=/gmu;
+var DEFINITION_LHS_RE = /^[ \t]*#(?:set|def)[ \t]+%\w+%[ \t]*=/gmu;
 var INCLUDE_RE2 = /^[ \t]*#include[ \t\n\r\f\x0B]+"([^"]+)"[ \t\n\r\f\x0B]*$/gmu;
 var VARIABLE_RE2 = /%(\w+)%/gu;
 var CONDITIONAL_REF_RE = /\{\?!?([A-Za-z_]\w*)\?/gu;
 function extractFromSource(src) {
   const text = stripComments(src);
   const sets = collect(text, SET_DEF_RE, true);
+  const defs = collect(text, DEF_DEF_RE, true);
   const includes = collect(text, INCLUDE_RE2, false);
-  const body = text.replace(SET_LHS_RE, "");
+  const body = text.replace(DEFINITION_LHS_RE, "");
   const refs = /* @__PURE__ */ new Set();
   addAll(refs, body, VARIABLE_RE2, true);
   addAll(refs, body, CONDITIONAL_REF_RE, true);
-  return { refs: [...refs], sets, includes };
+  return { refs: [...refs], sets, defs, includes };
 }
 function collect(text, re, fold) {
   const seen = /* @__PURE__ */ new Set();
@@ -647,8 +731,15 @@ function stripSentinels(text) {
 var MAX_VARIABLE_DEPTH = 50;
 var INCLUDE_LINE_RE = /^[ \t]*#include[ \t\n\r\f\x0B]+"([^"]+)"[ \t\n\r\f\x0B]*$/gmu;
 function renderAst(ast, ctx) {
-  const vars = buildVars(ast.setDefs, ctx.runtimeContext, ctx.rng);
-  const text = renderNodes(ast.nodes, { vars, rng: ctx.rng, locale: ctx.locale, depth: 0 });
+  const base = buildVars(ast.setDefs, ctx.runtimeContext);
+  const walkOpts = {
+    rng: ctx.rng,
+    locale: ctx.locale,
+    depth: 0,
+    onPluralError: ctx.onPluralError
+  };
+  const vars = Object.keys(ast.defDefs).length > 0 ? { ...base, ...rollDefinitions(ast.defDefs, base, ctx.runtimeContext, walkOpts) } : base;
+  const text = renderNodes(ast.nodes, { ...walkOpts, vars });
   return ctx.resolver ? resolveIncludes(text, ctx) : text;
 }
 function resolveIncludes(text, ctx) {
@@ -670,33 +761,65 @@ function resolveIncludes(text, ctx) {
     });
   });
 }
-function buildVars(setDefs, context, rng) {
+function buildVars(setDefs, context) {
   const vars = {};
   for (const [name, value] of Object.entries(setDefs)) {
-    vars[name] = collapseSetValue(value, rng);
+    vars[name] = value;
   }
   for (const [name, value] of Object.entries(context)) {
     vars[name.toLowerCase()] = value;
   }
   return vars;
 }
-function collapseSetValue(value, rng) {
-  if (!value.includes("{")) return value;
-  if (value.includes("{?") || value.includes("{plural ")) return value;
-  return resolveEnumerationsString(value, rng);
-}
-function resolveEnumerationsString(text, rng) {
-  let out = text;
-  for (let guard = 0; guard < 1e3; guard += 1) {
-    let changed = false;
-    out = out.replace(/\{([^{}]*)\}/gu, (_m, inner) => {
-      changed = true;
-      const options = splitTopLevelPipes(inner);
-      return options.length === 0 ? "" : options[randomInt(rng, 0, options.length - 1)] ?? "";
+function rollDefinitions(defDefs, vars, context, opts) {
+  const outranked = new Set(Object.keys(context).map((key) => key.toLowerCase()));
+  const rolled = {};
+  const aliases = {};
+  for (const [name, value] of Object.entries(vars)) {
+    if (name in defDefs && !outranked.has(name)) continue;
+    aliases[name] = value;
+  }
+  for (const name of orderDefinitions(defDefs, aliases)) {
+    if (outranked.has(name)) continue;
+    const value = defDefs[name] ?? "";
+    rolled[name] = renderNodes(parseSequence(value), { ...opts, vars: { ...vars, ...rolled } });
+  }
+  return rolled;
+}
+function orderDefinitions(defDefs, aliases) {
+  const names = Object.keys(defDefs);
+  const blocked = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const reached = referencedNames(defDefs[name] ?? "", aliases);
+    blocked.set(name, new Set(names.filter((candidate) => reached.has(candidate))));
+  }
+  const ordered = [];
+  let pending = names;
+  while (pending.length > 0) {
+    const ready = pending.filter((name) => {
+      const deps = blocked.get(name);
+      return !deps || ![...deps].some((dep) => dep !== name && pending.includes(dep));
     });
-    if (!changed) break;
+    if (ready.length === 0) return [...ordered, ...pending];
+    ordered.push(...ready);
+    pending = pending.filter((name) => !ready.includes(name));
   }
-  return out;
+  return ordered;
+}
+function referencedNames(value, aliases) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = directReferences(value);
+  while (queue.length > 0) {
+    const name = queue.shift();
+    if (seen.has(name)) continue;
+    seen.add(name);
+    const alias = aliases[name];
+    if (alias !== void 0) queue.push(...directReferences(alias));
+  }
+  return seen;
+}
+function directReferences(text) {
+  return [...text.matchAll(/%(\w+)%/gu)].map((match) => (match[1] ?? "").toLowerCase());
 }
 function renderNodes(nodes, opts) {
   let out = "";
@@ -751,17 +874,47 @@ function renderConditional(node, opts) {
 function renderPlural(node, opts) {
   const countRaw = expandVarsOnly(node.countRaw, opts);
   const formsRaw = expandVarsOnly(node.formsRaw, opts);
-  if (/[{}[\]]/u.test(formsRaw)) return fullwidthVerbatim(countRaw, formsRaw);
-  const count = phpTrim2(countRaw);
-  if (!/^-?\d+$/u.test(count)) return "";
   const base = normalizeBaseLang(opts.locale);
+  const report = (issue) => opts.onPluralError?.(issue);
+  if (/[{}[\]]/u.test(formsRaw)) {
+    report({
+      code: "plural.nested-brackets",
+      message: "Plural form slot contains nested spintax brackets; extract via #set first.",
+      construct: rawConstruct(countRaw, formsRaw),
+      locale: base
+    });
+    return fullwidthVerbatim(countRaw, formsRaw);
+  }
+  const count = phpTrim2(countRaw);
+  if (!/^-?\d+$/u.test(count)) {
+    report({
+      code: "plural.count",
+      message: `Plural count slot is empty or non-numeric (${JSON.stringify(count)}); block erased.`,
+      construct: rawConstruct(countRaw, formsRaw),
+      locale: base
+    });
+    return "";
+  }
   const forms = formsRaw.split("|").map((f) => phpTrim2(f));
-  if (forms.length !== pluralArity(base)) return fullwidthVerbatim(countRaw, formsRaw);
+  if (forms.length !== pluralArity(base)) {
+    report({
+      code: "plural.arity",
+      message: `Plural has ${forms.length} form(s); locale "${base}" takes ${pluralArity(base)}.`,
+      construct: rawConstruct(countRaw, formsRaw),
+      locale: base,
+      expected: pluralArity(base),
+      got: forms.length
+    });
+    return fullwidthVerbatim(countRaw, formsRaw);
+  }
   const picked = pluralFor(base, Number.parseInt(count, 10), forms);
   return renderNodes(parseSequence(picked), opts);
 }
+function rawConstruct(countRaw, formsRaw) {
+  return `{plural ${countRaw}:${formsRaw}}`;
+}
 function fullwidthVerbatim(countRaw, formsRaw) {
-  return `{plural ${countRaw}:${formsRaw}}`.replace(/\{/gu, "\uFF5B").replace(/\}/gu, "\uFF5D");
+  return rawConstruct(countRaw, formsRaw).replace(/\{/gu, "\uFF5B").replace(/\}/gu, "\uFF5D");
 }
 function renderEnumeration(options, opts) {
   if (options.length === 0) return "";
@@ -825,26 +978,6 @@ function padSeparator(sep) {
   if (/^\p{L}+$/u.test(trimmed)) return ` ${trimmed} `;
   return sep;
 }
-function splitTopLevelPipes(inner) {
-  const parts = [];
-  let brace = 0;
-  let bracket = 0;
-  let cur = "";
-  for (const ch of inner) {
-    if (ch === "{") brace += 1;
-    else if (ch === "}") brace -= 1;
-    else if (ch === "[") bracket += 1;
-    else if (ch === "]") bracket -= 1;
-    if (ch === "|" && brace === 0 && bracket === 0) {
-      parts.push(cur);
-      cur = "";
-    } else {
-      cur += ch;
-    }
-  }
-  parts.push(cur);
-  return parts;
-}
 var PHP_LTRIM_RE2 = /^[ \t\n\r\0\x0B]+/u;
 var PHP_RTRIM_RE2 = /[ \t\n\r\0\x0B]+$/u;
 function phpTrim2(s) {
@@ -977,7 +1110,8 @@ function renderWith(input, rng, opts = {}) {
     locale: opts.locale ?? "",
     resolver: opts.includeResolver,
     maxDepth: opts.maxDepth ?? DEFAULT_MAX_DEPTH,
-    includeStack: []
+    includeStack: [],
+    onPluralError: opts.onPluralError
   };
   const ast = resolveAst(typeof input === "string" ? stripSentinels(input) : input);
   let out = renderAst(ast, ctx);
@@ -1014,6 +1148,12 @@ function hashString(s) {
 }
 
 // src/index.ts
+function normalizeBaseLang2(locale) {
+  return normalizeBaseLang(locale ?? "");
+}
+function pluralArity2(locale) {
+  return pluralArity(normalizeBaseLang2(locale));
+}
 function parse(src) {
   return parseTemplate(src);
 }
@@ -1072,7 +1212,9 @@ exports.SpintaxError = SpintaxError;
 exports.analyze = analyze;
 exports.extract = extract;
 exports.neutralize = neutralize2;
+exports.normalizeBaseLang = normalizeBaseLang2;
 exports.parse = parse;
+exports.pluralArity = pluralArity2;
 exports.render = render;
 exports.validate = validate;
 //# sourceMappingURL=index.cjs.map