@spintax/core 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -3,6 +3,65 @@
 All notable changes to `@spintax/core` are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.1.5 — 2026-07-13
+
+Spanish post-process fix. No API change.
+
+### Fixed
+
+- **`postProcess` no longer strips the capital from every Spanish sentence.** Spanish is the only
+  European language whose punctuation *opens* a sentence, and the capitalization passes upper-cased
+  the first **character** after a sentence boundary — which, for `¿cómo estás?`, is `¿`. An inverted
+  mark has no uppercase form, so the pass was a no-op and the real first letter stayed lowercase.
+  The spacing pass had the mirror-image gap: it knew "no space *before* closing punctuation" but had
+  no rule for an opener, so `¿ qué tal ?` only half-collapsed.
+
+  ```
+  hola. ¿cómo estás? ¡genial!   →  Hola. ¿Cómo estás? ¡Genial!
+  Hola. ¿ qué tal ?             →  Hola. ¿Qué tal?
+  ```
+
+  A new `SENTENCE_OPENERS = '¿¡'` concept drives both: an opener binds to the word it opens (before
+  capitalization, deliberately), and the four capitalization sites — start of text, after `.!?…`,
+  after a block-level tag, and after a newline — allow an optional opener between the boundary and
+  the letter. HTML paragraphs and multi-line templates were broken exactly like the bare `. ¿` case.
+
+  The opener set is deliberately **narrow**: quotes and brackets both open *and* close, so
+  capitalizing after them would mangle list markers (`Elige una. (a) primero`). Golden-corpus
+  fixtures guard both the fix and its narrowness, in **both** engines.
+
+### Notes
+
+- Mirrored into the PHP plugin engine to hold the post-process parity contract. Verified against the
+  shared golden corpus in both engines: TS 230 tests; the conformance runner against the real plugin
+  engine 99 tests / 112 assertions; the plugin's own suite 578 tests, no regressions.
+- The plugin carries the same fix but ships it in a later release, so for a short window a published
+  plugin and this package can differ on Spanish output. The parity *contract* holds — the engines'
+  behavior agrees and the corpus proves it — only the release timing differs.
+
+## 0.1.4 — 2026-07-13
+
+A post-process bug fix (hit in production) plus docs. No API change.
+
+### Fixed
+
+- **`postProcess` no longer mangles `mailto:` / `tel:` URIs.** They carry no `//` authority,
+  so the URL shield missed them; the email shield then carved the address out from under the
+  prefix, and the "space after a colon" rule split the leftover into a malformed
+  `mailto: contact@example.com` href. They are now shielded as whole tokens (with the same
+  trailing-punctuation handling as URLs) before the email/domain passes. Mirrored into the PHP
+  engine and covered by 4 golden-corpus fixtures, so the post-process parity contract holds
+  in both engines. Reported in [#41](https://github.com/investblog/spintax-js/issues/41).
+
+### Changed
+
+- Docs: a **Use Cases** section (cold email, notifications, chatbots, A/B copy, programmatic
+  SEO, spinning LLM-drafted templates locally) and the N-variants recipe — call `render` N
+  times with different seeds — with the caveat that distinct seeds are *independent draws, not
+  distinct results*, so a low-cardinality template will repeat. Batching stays a host concern.
+- npm keywords broadened (`text-spinner`, `email-template`, `placeholders`, `variables`,
+  `conditionals`) to match how people actually search for this.
+
 ## 0.1.3 — 2026-07-08
 
 Precise diagnostic positions. Backward-compatible — `validate()` verdicts (pass/fail),

package/README.md

@@ -43,6 +43,33 @@ validate('{a|b');          // → [{ severity: 'error', code: 'bracket.unclosed'
 extract('%title% {?promo?Sale}'); // → { refs: ['title', 'promo'], sets: [], includes: [] }
 ```
 
+## Use cases
+
+Anywhere one message has to go out many times without reading like a form letter:
+
+- **Cold email & outreach** — one template, a distinct body per recipient, personalized through `context`.
+- **SMS / push / notifications** — deterministic output in a few kilobytes, no API call per send.
+- **Chatbots & agents** — vary canned replies so a bot doesn't repeat itself verbatim.
+- **A/B and multivariate testing** — enumerate copy variants in the template instead of in application code.
+- **Programmatic SEO / content generation** — thousands of pages from one authored source.
+- **LLM output at scale** — have a model draft the template once, then spin it locally, forever, for free.
+
+The core renders a **single** string per call — batching is a host concern. To emit N variants, call
+`render` N times with different seeds; a seeded call is reproducible, so any variant can be
+regenerated later from its seed alone:
+
+```ts
+const template = '{Hi|Hello|Hey} %name%, {quick|short|small} question about {pricing|billing}';
+const variants = [1, 2, 3].map((seed) => render(template, { context: { name: 'Ada' }, seed }));
+// → [ 'Hello Ada, quick question about billing',
+//     'Hey Ada, quick question about pricing',
+//     'Hey Ada, quick question about pricing' ]   ← same as seed 2; see the caveat below
+```
+
+Distinct seeds are **independent draws, not distinct results** — like any sampling they can repeat,
+and the fewer combinations a template has, the more often they will. If you need N *unique* variants,
+dedupe in the host and cap the retries: a template may simply not have N combinations to give.
+
 ## Spintax syntax
 
 | Construct | Example | Meaning |

package/dist/index.cjs

@@ -906,19 +906,26 @@ var WS = " \\t\\r\\n\\f\\x0B";
 var S = `[${WS}]`;
 var DOMAIN_PART = "(?:(?:(?:xn--)?[\\p{L}\\p{N}]+(?:-[\\p{L}\\p{N}]+)*)\\.)+(?:xn--[a-z0-9\\-]{2,59}|[\\p{L}][\\p{L}\\p{N}-]{1,62})";
 var URL_RE = new RegExp(`(?:https?|ftp):\\/\\/[^${WS}<>"')\\]]+`, "giu");
+var MAILTEL_RE = new RegExp(`(?:mailto|tel):[^${WS}<>"')\\]]+`, "giu");
 var EMAIL_RE = new RegExp(`[a-z0-9._%+\\-]+@${DOMAIN_PART}\\b`, "giu");
 var DOMAIN_RE = new RegExp(`\\b${DOMAIN_PART}\\b`, "giu");
 var DECIMAL_RE = /\b\d+\.\d+\b/gu;
 var MULTI_ABBR_RE = new RegExp(`\\b(?:\\p{L}{1,2}\\.${S}*){2,}`, "gu");
 var SINGLE_ABBR_RE = new RegExp(`(?<![\\p{L}\\p{N}])(?:${SINGLE_ABBREVS.join("|")})\\.(?=${S}|$|<)`, "giu");
 var TRAILING_PUNCT_RE = /([.,;:!]+)$/u;
+var SENTENCE_OPENERS = "\xBF\xA1";
+var OPEN = `[${SENTENCE_OPENERS}]?${S}*`;
 var SPACE_BEFORE_PUNCT_RE = new RegExp(`${S}+([,;:!?.])`, "gu");
 var SPACE_AFTER_COMMA_RE = new RegExp(`([,;:])(?!\\d)(?!${S}|$|<)`, "gu");
 var SPACE_AFTER_SENTENCE_RE = new RegExp(`([.!?])(?!\\d)(?!${S}|$|<)`, "gu");
-var CAP_FIRST_RE = new RegExp(`^(${S}*(?:<[^>]+>${S}*)*)(\\p{Ll})`, "u");
-var CAP_AFTER_SENTENCE_RE = new RegExp(`([.!?\u2026])(${S}*(?:<\\/?[^>]+>${S}*)*)(\\p{Ll})`, "gu");
-var CAP_AFTER_BLOCK_RE = new RegExp(`(<\\/?(?:p|h[1-6]|li|blockquote|div|td|th)[^>]*>${S}*)(\\p{Ll})`, "giu");
-var CAP_AFTER_BREAK_RE = new RegExp(`(\\n${S}*)(\\p{Ll})`, "gu");
+var SPACE_AFTER_OPENER_RE = new RegExp(`([${SENTENCE_OPENERS}])${S}+`, "gu");
+var CAP_FIRST_RE = new RegExp(`^(${S}*(?:<[^>]+>${S}*)*${OPEN})(\\p{Ll})`, "u");
+var CAP_AFTER_SENTENCE_RE = new RegExp(`([.!?\u2026])(${S}*(?:<\\/?[^>]+>${S}*)*${OPEN})(\\p{Ll})`, "gu");
+var CAP_AFTER_BLOCK_RE = new RegExp(
+  `(<\\/?(?:p|h[1-6]|li|blockquote|div|td|th)[^>]*>${S}*${OPEN})(\\p{Ll})`,
+  "giu"
+);
+var CAP_AFTER_BREAK_RE = new RegExp(`(\\n${S}*${OPEN})(\\p{Ll})`, "gu");
 var up = (ch) => ch.toUpperCase();
 function postProcess(input) {
   const placeholders = /* @__PURE__ */ new Map();
@@ -940,6 +947,7 @@ function postProcess(input) {
   };
   let text = input;
   text = text.replace(URL_RE, (m) => storeWithTrailingPunct(m, "URL"));
+  text = text.replace(MAILTEL_RE, (m) => storeWithTrailingPunct(m, "URI"));
   text = text.replace(EMAIL_RE, (m) => store(m, "EMAIL"));
   text = text.replace(DOMAIN_RE, (m) => store(m, "DOM"));
   text = text.replace(DECIMAL_RE, (m) => store(m, "NUM"));
@@ -949,6 +957,7 @@ function postProcess(input) {
   text = text.replace(SPACE_BEFORE_PUNCT_RE, "$1");
   text = text.replace(SPACE_AFTER_COMMA_RE, "$1 ");
   text = text.replace(SPACE_AFTER_SENTENCE_RE, "$1 ");
+  text = text.replace(SPACE_AFTER_OPENER_RE, "$1");
   text = text.replace(CAP_FIRST_RE, (_m, lead, ch) => lead + up(ch));
   text = text.replace(CAP_AFTER_SENTENCE_RE, (_m, p, gap, ch) => p + gap + up(ch));
   text = text.replace(CAP_AFTER_BLOCK_RE, (_m, tag, ch) => tag + up(ch));