@spintax/core 0.1.3 → 0.1.4

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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.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,6 +906,7 @@ 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;
@@ -940,6 +941,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"));