@spintax/core 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,34 @@
 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.1 — 2026-07-21
+
+Author markup is sanitised in one place, so a handle renders exactly like its source.
+
+### Fixed
+
+- **`render(parse(src))` no longer diverges from `render(src)`** when the template contains an
+  author-typed engine sentinel (the reserved range U+E000–U+E005). The strip that keeps stray
+  sentinels out of a tree lived at the render entry points, so `parse()` and `analyze(str)` — two
+  of the three doors into the parser — skipped it, and the mandatory safety-restore then rewrote
+  the author's character into a structural glyph they never wrote:
+
+  ```js
+  const src = `a${String.fromCharCode(0xe000)}b`;
+  render(src, { postProcess: false }); // "ab"
+  render(parse(src), { postProcess: false }); // "a{b"  ← before this release
+  ```
+
+  The strip now lives in `parseTemplate`, the single door from author source into an AST, so all
+  three entry points agree. `parseSequence` is deliberately **not** sanitised — it re-parses a
+  variable's *value*, where sentinels a host `neutralize()`d are legitimate and must survive to the
+  restore — and `ParsedAst.source` still keeps the original bytes so diagnostics point at what was
+  typed. ([#51](https://github.com/investblog/spintax-js/issues/51))
+
+  Templates that contain no reserved-range characters are unaffected: the strip is a no-op on them.
+  The Python port fixed the same defect the same way; the PHP engines never had it (no `parse()`
+  handle, no PUA sentinels).
+
 ## 0.3.0 — 2026-07-19
 
 `#set` goes back to being a macro and a new `#def` carries roll-once. Breaking: it changes what

package/README.md

@@ -153,7 +153,7 @@ render('%bio%', { context: { bio: neutralize('Save {50|60}% today') }, postProce
 
 With a `seed`, `render` is reproducible within this engine. Cross-engine RNG-sequence parity
 with the PHP plugin is a **non-goal** — only the *deterministic* behavior (validation verdicts,
-plural buckets, conditional truthiness, `#set` collapse, post-process output) is parity-gated.
+plural buckets, conditional truthiness, `#set`/`#def` semantics, post-process output) is parity-gated.
 
 ## Links
 

package/dist/index.cjs

@@ -23,13 +23,38 @@ function isParsedAst(value) {
   return typeof value === "object" && value !== null && value.astVersion === AST_VERSION && typeof value.source === "string" && Array.isArray(value.nodes);
 }
 
+// src/internal/neutralize.ts
+var STRUCTURAL = ["{", "}", "[", "]", "%", "#"];
+var SENTINEL_BASE = 57344;
+var SHIELD = /* @__PURE__ */ new Map();
+var RESTORE = /* @__PURE__ */ new Map();
+STRUCTURAL.forEach((ch, i) => {
+  const sentinel = String.fromCharCode(SENTINEL_BASE + i);
+  SHIELD.set(ch, sentinel);
+  RESTORE.set(sentinel, ch);
+});
+var SHIELD_RE = /[{}[\]%#]/gu;
+var RESTORE_RE = new RegExp(
+  `[${String.fromCharCode(SENTINEL_BASE)}-${String.fromCharCode(SENTINEL_BASE + STRUCTURAL.length - 1)}]`,
+  "gu"
+);
+function neutralize(value) {
+  return value.replace(SHIELD_RE, (ch) => SHIELD.get(ch) ?? ch);
+}
+function safetyRestore(text) {
+  return text.replace(RESTORE_RE, (ch) => RESTORE.get(ch) ?? ch);
+}
+function stripSentinels(text) {
+  return text.replace(RESTORE_RE, "");
+}
+
 // src/internal/parser.ts
 var VARIABLE_RE = /^%(\w+)%/;
 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, defDefs } = extractDirectives(stripComments(src));
+  const { body, setDefs, defDefs } = extractDirectives(stripComments(stripSentinels(src)));
   return { astVersion: AST_VERSION, source: src, setDefs, defDefs, nodes: parseSequence(body) };
 }
 function extractDirectives(text) {
@@ -702,31 +727,6 @@ var NotImplementedError = class extends SpintaxError {
   }
 };
 
-// src/internal/neutralize.ts
-var STRUCTURAL = ["{", "}", "[", "]", "%", "#"];
-var SENTINEL_BASE = 57344;
-var SHIELD = /* @__PURE__ */ new Map();
-var RESTORE = /* @__PURE__ */ new Map();
-STRUCTURAL.forEach((ch, i) => {
-  const sentinel = String.fromCharCode(SENTINEL_BASE + i);
-  SHIELD.set(ch, sentinel);
-  RESTORE.set(sentinel, ch);
-});
-var SHIELD_RE = /[{}[\]%#]/gu;
-var RESTORE_RE = new RegExp(
-  `[${String.fromCharCode(SENTINEL_BASE)}-${String.fromCharCode(SENTINEL_BASE + STRUCTURAL.length - 1)}]`,
-  "gu"
-);
-function neutralize(value) {
-  return value.replace(SHIELD_RE, (ch) => SHIELD.get(ch) ?? ch);
-}
-function safetyRestore(text) {
-  return text.replace(RESTORE_RE, (ch) => RESTORE.get(ch) ?? ch);
-}
-function stripSentinels(text) {
-  return text.replace(RESTORE_RE, "");
-}
-
 // src/internal/render.ts
 var MAX_VARIABLE_DEPTH = 50;
 var INCLUDE_LINE_RE = /^[ \t]*#include[ \t\n\r\f\x0B]+"([^"]+)"[ \t\n\r\f\x0B]*$/gmu;
@@ -753,7 +753,7 @@ function resolveIncludes(text, ctx) {
       throw new IncludeResolverError(`includeResolver threw for "${ref}"`, { cause });
     }
     if (included === null) return "";
-    return renderAst(parseTemplate(stripSentinels(included)), {
+    return renderAst(parseTemplate(included), {
       ...ctx,
       runtimeContext: ctx.runtimeContext,
       // child inherits runtime, not parent #set
@@ -879,7 +879,7 @@ function renderPlural(node, opts) {
   if (/[{}[\]]/u.test(formsRaw)) {
     report({
       code: "plural.nested-brackets",
-      message: "Plural form slot contains nested spintax brackets; extract via #set first.",
+      message: "Plural form slot contains nested spintax brackets; extract via #def first \u2014 a #set is substituted verbatim and would put the brackets straight back.",
       construct: rawConstruct(countRaw, formsRaw),
       locale: base
     });
@@ -1113,7 +1113,7 @@ function renderWith(input, rng, opts = {}) {
     includeStack: [],
     onPluralError: opts.onPluralError
   };
-  const ast = resolveAst(typeof input === "string" ? stripSentinels(input) : input);
+  const ast = resolveAst(input);
   let out = renderAst(ast, ctx);
   if (opts.postProcess !== false) out = postProcess(out);
   return safetyRestore(out);