@rhinostone/swig 2.8.0 → 2.8.2

package/HISTORY.md

@@ -1,3 +1,79 @@
+[2.8.2](https://github.com/gina-io/swig/tree/v2.8.2) / 2026-10-20
+-----------------------------------------------------------------
+
+* **Fixed** SECURITY.md's supported-versions table now names 2.8.x as the supported release line; it still listed 2.7.x.
+
+* **Fixed** The issue and pull-request templates no longer open with the original project's "Swig is no longer maintained" notice. The issue template asks for the package and version, the environment, and a template with locals that reproduces the problem, and sends security reports to SECURITY.md; the pull-request template points to the develop branch and the test, lint and bundle checks.
+
+* **Fixed** The README no longer says a callback to compileFile is enough to load templates through an async loader: compileFile also needs codegenMode set to async in its options, as its API documentation says, while renderFile switches on loader.async alone. It now also says that, in that mode, the compiled function returns a promise of { output, exports }. The README's documentation section now names packages/swig-core/lib/loaders/, where the loader JSDoc lives, instead of the one-line lib/loaders/ re-exports, and the swig-jinja2 and swig-django READMEs lead with renderFile against an async loader and mark renderFileAsync and compileFileAsync as deprecated.
+
+* **Fixed** A template compiled with codegenMode set to async no longer shares its cache entry with a sync compile of the same file. A sync render or include of a file first compiled in async mode now renders its output instead of [object Promise], and an async-mode compile after a sync one now returns an async function instead of the cached sync one. The fix is in the shared engine, so all four frontends get it; the async entry is cached under its own key.
+
+* **Fixed** An error raised while a template is compiled is now reported when render, compile or precompile is called without an options object; it used to surface as TypeError: Cannot read properties of undefined (reading 'filename'), hiding the template error. An error whose message already names the template file, such as Multiple "else" branches in "if" tag in file page.html, now names it once instead of twice, and an error with no file name to add is thrown unchanged instead of being wrapped again with an "Error: " prefix and a doubled period. All four frontends.
+
+* **Fixed** The varControls, tagControls and cmtControls options are rejected when a control is not a string, with the message Option "<name>" must be an array containing 2 different control strings. A number or a nested array used to pass validation and fail at the first render with str.replace is not a function, and null failed inside the validator with a TypeError. All four frontends.
+
+* **Fixed** The error for a control option that is too short now names the right control: a short open control is reported as the open control and a short close control as the close control; the two words were swapped. All four frontends.
+
+* **Fixed** Jinja2 first, last, reverse, unique, min, max and slice now use the keys of a mapping, as Jinja2 iterates a mapping. first and last give the first and last key, reverse gives the keys in reverse order, unique the unique keys, min and max compare the keys, and slice distributes them; they used the values before. sum and random keep their results on a mapping, where Jinja2 raises.
+
+* **Fixed** Jinja2 batch now follows Jinja2. A new row starts when the current one holds exactly size items, so a size of 0 gives an empty first row and a size that no row length can equal (negative, fractional or not a number) gives a single row; batch returned an empty list for a size of 0, a negative size or one that is not a number, rounded a fractional size up, and read a numeric string such as "2" as a number. A string is now batched by its characters and a mapping by its keys; batch returned an empty list for a string and used the values of a mapping. The fill pads the last row only up to a finite numeric size.
+
+* **Fixed** Jinja2 sort of a string now returns its characters as a sorted list, as Jinja2 does; it joined them back into a string, so "cba" gave "abc" where Jinja2 gives ["a", "b", "c"].
+
+* **Fixed** Jinja2 replace now follows Python. A number input is converted to a string first, so 5|replace("5", "X") gives "X" where it returned the number 5; an empty search string inserts the replacement before each character and at the end, honouring the count, so "abc"|replace("", "X") gives "XaXbXcX" where it returned "abc"; and a negative count replaces every occurrence, where it replaced none.
+
+* **Fixed** Jinja2 format now prints %e and %E with at least two exponent digits, as Python does, so 12345.678 gives "1.234568e+04" where it gave "1.234568e+4". %g and %G now follow Python too: the precision (6 by default) counts significant digits, the number is printed in fixed notation when its decimal exponent is at least -4 and below the precision and in exponential notation otherwise, and trailing zeros are removed; they printed the number as JavaScript does, so 1234567 gave "1234567" where Python gives "1.23457e+06".
+
+* **Fixed** swig-jinja2 wordwrap keeps the separating space when a line is exactly full before a long word, as Python textwrap does, so the output is "abcd |xxxxx|xxxxx" where it was "abcd|xxxxx|xxxxx".
+
+* **Fixed** Django join now joins the characters of a string and the keys of a mapping, as Django does. It returned a string unchanged, so "abc"|join:"," gave "abc" where Django gives "a,b,c", and it returned a mapping itself, which rendered as [object Object].
+
+* **Fixed** Django pluralize now reads its input as Django does. A boolean is compared with 1, so true gives the singular and false the plural, where both gave the empty string; a string must parse as a Python float, so "abc" and the empty string give the empty string where they gave the plural, and "1_000" gives the plural where it gave the singular; a mapping counts its keys, so an empty mapping gives the plural where it gave the empty string.
+
+* **Fixed** Django truncatechars and truncatewords now return the empty string for a count of 0 or less, as Django does, where truncatechars gave the ellipsis alone and truncatewords kept a word or added an ellipsis ("a"|truncatewords:0 gave " …"). They also read the count as Python int() does, so a count string int() rejects, such as "3abc" or "2.5", returns the value unchanged where swig truncated on its leading digits.
+
+* **Fixed** The Jinja2 lower and upper tests now need a cased letter, as Python's islower and isupper do: an empty string, digits, punctuation, whitespace or an uncased script such as Chinese is neither lower nor upper, and so is a null or missing variable; they used to be both.
+
+* **Fixed** The Jinja2 odd test now follows Python's n % 2 == 1, so a non-integer such as 1.5, or an infinity, is not odd, as in Jinja2; it used to call them odd. A negative odd integer is still odd.
+
+* **Fixed** The Jinja2 number test now accepts NaN, as Python's numbers.Number does; it used to reject it.
+
+* **Fixed** Parenthesized sub-expressions keep their grouping when a template compiles, in every flavor. Since 2.0.0-alpha.2 the emitted JavaScript could lose the parentheses of a group, so a group whose operator binds more loosely than the operator outside it was evaluated wrongly ({{ (1 + 2) * 3 }} rendered 7, and {% if (x or y) and z %} took its branch with x true and z false), as were a comparison grouped inside a comparison and a subscript on a + group (("a" + "b")[1] rendered aundefined), and {{ -(-x) }} failed to compile. A group that JavaScript reads the same way without the parentheses, not (...), -(...) and a group followed by a filter rendered correctly.
+
+* **Fixed** swig-jinja2 applies a unary minus or plus before the filters and the ** that follow it, as Jinja2 does: {{ -x|abs }} is the absolute value of -x, so it gives 5 for x 5 where it gave -5, and -2 ** 2 is (-2) ** 2, so it gives 4 where it gave -4.
+
+* **Fixed** swig-jinja2 reads a chain of ** from the left, as Jinja2 does: 2 ** 3 ** 2 is (2 ** 3) ** 2, so it gives 64 where it gave 512.
+
+* **Fixed** swig-jinja2 binds a test to the operand next to it, as Jinja2 does: {{ 1 + 2 is number }} tests 2, so it gives 2 where it gave true, and {% if not x is defined %} negates the test, so it is false for a defined x where it was true. A test also takes one argument without parentheses, as in Jinja2 (x is divisibleby 3, x is sameas false), where that threw an Unexpected token error.
+
+* **Fixed** swig-jinja2 gives not its Jinja2 level, below the comparisons and arithmetic: {% if not x == y %} is not (x == y), so it is true for x 1 and y 2 where it was false, and {% if not x + y %} negates the sum, so it is false for x 0 and y 1 where it was true. A not in another operand position (x == not y) still binds its operand.
+
+* **Fixed** The error messages of the prototype-chain guards, in every package, end with (prototype-chain guard) instead of (CVE-2023-25345). That CVE is the directory traversal through include and extends that 2.7.1 fixed in the filesystem loader, whose message keeps the label; the guards block access to __proto__, constructor and prototype. Code that matched the old text has to match the new one.
+
+* **Fixed** swig-core, swig-twig, swig-jinja2 and swig-django export their version as a string, as swig always has; the property was undefined.
+
+* **Changed** Upgraded the globals dev dependency, which the ESLint config reads, from 16.x to 17.x. Its node global set drops DisposableStack, AsyncDisposableStack and SuppressedError, which no linted file uses, and its mocha set is unchanged, so make lint reports the same clean result.
+
+* **Security** swig-jinja2 wordwrap no longer hangs on a width below 1. A width of 0 or less, given as a number or as a string such as "0", ran for four to six seconds and took more than 2 GB of memory before a RangeError; it now returns the input unchanged (Jinja2 raises). A width between 0 and 1, which hung the same way, now breaks one character at a time, as Python does. Every swig-jinja2 release since 2.5.0 has the hang; reaching it takes an application that passes a width from the request into the filter.
+
+* **Security** swig-twig ranges no longer hang on an infinite bound. With a bound of Infinity, which plain JSON produces for a number such as 1e999, a..b looped until the array overflowed, taking up to about three seconds and more than 2 GB of memory before a RangeError. The range is now empty, as it already was for NaN (PHP 8.3 rejects such a bound). Every release since 2.0.0-alpha.5 has the hang; reaching it takes an application that passes a number from the request into a range bound.
+
+[2.8.1](https://github.com/gina-io/swig/tree/v2.8.1) / 2026-10-20
+-----------------------------------------------------------------
+
+* **Added** A "What's new in v<version>" section at the top of the README, regenerated from the release notes at every cut
+
+* **Fixed** Refreshed stale README claims — the benchmark summary now reflects the latest measured run (swig leads on all five workloads; the previous table predated the 2.2.0 escape-filter rewrite and showed nunjucks ahead on simple var output), and the security bullet no longer pins an exact CVE regression-test count nor conflates the prototype-chain hardening with CVE-2023-25345 (a directory-traversal fix)
+
+* **Fixed** README completeness pass against the 2.x release line — the feature list now covers the async-loader render path (callback dispatch with loader.async, dynamic extends included) and the single-runtime-dependency posture, the "How it works" section explains the runtime-only strict-CSP path, and the Jinja2/Django migration notes no longer list the default filter as absent (it has been built into native swig since upstream 2014)
+
+* **Fixed** The v0.9.0 changelog entry's PHP date-format citation now links to the canonical `https://www.php.net/manual/en/function.date.php` instead of the plain-HTTP `http://php.net/date` it had carried since upstream. The old form still resolves — it 301s through to exactly that URL — so this is the same destination over HTTPS, with the link text unchanged; it removes the last plain-HTTP link a link-health scan can flag in this repo (reported twice, gina-io/gina#51 and #58). Documentation only; no runtime or API change.
+
+* **Fixed** The bundled DateZ attribution banner now points at `https://github.com/tn0ms/DateZ`, following the fourth rename of that upstream account. The previous `tomoio` form still resolves — GitHub 301s a renamed account through to its current owner — so this is the same destination, with the misspelled upstream `LISENCE` filename preserved because that is genuinely how the file is named there. The banner ships in every `dist/` artifact, so the corrected URL reaches consumers at the next publish. Documentation only; no runtime or API change.
+
+* **Changed** Upgraded the ESLint dev dependency from 9.x, which its maintainers no longer support, to 10.x. The flat-config eslint.config.js carries over unchanged, and make lint reports the same results as under 9.x. ESLint 10 raises the lint toolchain Node floor to ^20.19.0, ^22.13.0 or >=24, which affects development and CI only; the published package is unaffected and its only runtime dependency remains @rhinostone/swig-core.
+
 [2.8.0](https://github.com/gina-io/swig/tree/v2.8.0) / 2026-08-02
 -----------------------------------------------------------------
 
@@ -565,7 +641,7 @@ Migrating from v0.x.x? The upstream wiki has since been deleted; see the individ
 * **Added** New `raw` tag.
 * **Changed** Swig is no longer node 0.4 compatible.
 * **Fixed** Filter `date('f')` for 10am times.
-* **Fixed** Filter `date('r')` returns in UTC date format. This is more correct tospec RFC2822, per [php.net/date](http://php.net/date).
+* **Fixed** Filter `date('r')` returns in UTC date format. This is more correct tospec RFC2822, per [php.net/date](https://www.php.net/manual/en/function.date.php).
 * **Fixed** Filter `add` when adding numbers/numbers+strings together.
 * **Fixed** Tests for error messages that changed in node >0.6.0.
 

package/ISSUE_TEMPLATE.md

@@ -1,5 +1,13 @@
-# Swig is no longer maintained
+<!--
+Security problems: do not open a public issue; see SECURITY.md for private reporting.
+-->
 
-Feel free to file an issue. Someone in the community may be able to help.
+**Package and version** (e.g. @rhinostone/swig 2.8.1, or swig-twig, swig-jinja2, swig-django, swig-core):
 
-However, no new releases are being made to this repository. 
+**Node version, or browser and bundle:**
+
+**Template and locals that reproduce it:**
+
+**Expected output:**
+
+**Actual output or error:**

package/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,9 @@
-# Swig is no longer maintained
+<!--
+Please target the develop branch. See CONTRIBUTING.md.
+-->
 
-If you're in need of a fix or a new feature, you should maintain your own fork of this repository.
+**What this changes and why:**
+
+- [ ] Tests added or updated (`make test`)
+- [ ] `make lint` passes
+- [ ] `make test-bundles` passes, if `lib/`, `packages/` or the build changed

package/README.md

@@ -32,15 +32,38 @@ Features
 --------
 
 * Available for node.js **and** major web browsers.
+* **Strict-CSP browser runtime** — AOT-compile templates ahead of time (`swig compile --recursive --register`) and render them with the runtime-only bundle (`dist/swig.runtime.min.js`, ~22 KB) — no parser, no `new Function`, no `unsafe-eval` required.
 * [Express](https://expressjs.com/) compatible.
+* **Async template loading** — back the loader with S3 / Redis / HTTP / any callback API: set `loader.async = true` and pass a callback to `renderFile`, or to `compileFile` with `codegenMode: 'async'` in its options, whose compiled function returns a promise of `{ output, exports }`; `extends` / `include` / `import` resolve at render time, dynamic `{% extends %}` paths included.
 * Object-Oriented template inheritance.
 * Apply filters and transformations to output in your templates.
-* **Hardened against prototype-pollution** — `__proto__` / `constructor` / `prototype` blocked at parser, tag-side, and IR-emission layers. CVE-2023-25345 fully patched. 11 CVE regression cases under [`tests/regressions.test.js`](./tests/regressions.test.js).
+* **Security-hardened** — prototype-pollution vectors (`__proto__` / `constructor` / `prototype`) blocked at parser, tag-side, and IR-emission layers; template-driven file reads outside the loader root rejected (CVE-2023-25345 directory traversal, patched in 2.7.1). Dedicated CVE regression suite in [`tests/regressions.test.js`](./tests/regressions.test.js).
 * Automatically escapes all variable output (HTML by default; configurable per-call).
 * Lots of iteration and conditionals supported.
-* Robust without the bloat.
+* Robust without the bloat — a single runtime dependency ([`@rhinostone/swig-core`](https://www.npmjs.com/package/@rhinostone/swig-core)).
 * Extendable and customizable — register custom filters, tags, and loaders per-instance.
 
+What's new in v2.8.2
+--------------------
+
+> **Upgrade if a template takes a `wordwrap` width or a range bound from request data.** swig-jinja2's `wordwrap` hung on a width below 1 and swig-twig's `a..b` on an infinite bound, which plain JSON produces for a number such as `1e999`; each took seconds and more than 2 GB of memory before failing.
+
+> **Error text changed.** The prototype-chain guards' messages end with `(prototype-chain guard)` instead of `(CVE-2023-25345)`; code that matches the old text has to match the new one.
+
+* **Security — swig-jinja2 `wordwrap` no longer hangs on a width below 1.** A width of 0 or less, as a number or as a string such as `"0"`, ran for four to six seconds and took more than 2 GB of memory before a RangeError; it now returns the input unchanged (Jinja2 raises). A width between 0 and 1 now breaks one character at a time, as Python does. Every swig-jinja2 release since 2.5.0 has the hang.
+* **Security — swig-twig ranges no longer hang on an infinite bound.** `a..b` with a bound of Infinity looped until the array overflowed, taking up to about three seconds and more than 2 GB of memory before a RangeError; the range is now empty, as it already was for NaN. Every release since 2.0.0-alpha.5 has the hang.
+* **Fixed — parenthesized sub-expressions keep their grouping, in every flavor.** Since 2.0.0-alpha.2 a group whose operator binds more loosely than the operator outside it was evaluated wrongly (`{{ (1 + 2) * 3 }}` rendered 7, and `{% if (x or y) and z %}` took its branch with x true and z false), as were a comparison grouped inside a comparison and a subscript on a `+` group, and `{{ -(-x) }}` failed to compile. Groups that JavaScript reads the same way, `not (…)`, `-(…)` and a group followed by a filter were not affected.
+* **Fixed — swig-jinja2 expressions follow Jinja2's precedence.** A unary minus applies before the filters and the `**` that follow it (`-2 ** 2` is 4); `**` reads from the left (`2 ** 3 ** 2` is 64); a test binds to the operand next to it (`{{ 1 + 2 is number }}` tests 2, and `not x is defined` negates the test) and takes one argument without parentheses (`x is divisibleby 3`); and `not` sits below the comparisons and arithmetic (`not x == y` is `not (x == y)`).
+* **Fixed — swig-jinja2 tests.** `lower` and `upper` need a cased letter, `odd` follows Python's `n % 2 == 1`, and `number` accepts NaN, as in Jinja2.
+* **Fixed — swig-jinja2 filters follow Jinja2.** `first`, `last`, `reverse`, `unique`, `min`, `max` and `slice` use a mapping's keys; `batch` starts a row at exactly `size` items and batches a string by its characters; `sort` of a string returns its sorted characters; `replace` converts a number first and handles an empty search string and a negative count as Python does; `format` prints `%e` with at least two exponent digits and `%g` as Python does; and `wordwrap` keeps the separating space when a line is exactly full.
+* **Fixed — swig-django filters follow Django.** `join` joins a string's characters and a mapping's keys; `pluralize` reads a boolean, a string and a mapping as Django does; `truncatechars` and `truncatewords` return the empty string for a count of 0 or less and the value unchanged for a count that Python's `int()` rejects.
+* **Fixed — the shared engine, in all four frontends.** An async-mode compile no longer shares its cache entry with a sync compile of the same file (a sync include of such a file rendered `[object Promise]`); an error raised while a template compiles is reported when no options object is passed, instead of a TypeError, and names its file once; and the `varControls`, `tagControls` and `cmtControls` options reject a control that is not a string, with the open and close controls named the right way round.
+* **Fixed — guard messages and version exports.** The prototype-chain guards' messages end with `(prototype-chain guard)`, and `swig-core`, `swig-twig`, `swig-jinja2` and `swig-django` export their `version`, as `swig` always has.
+* **Fixed — documentation.** SECURITY.md names 2.8.x as the supported line; the issue and pull-request templates no longer open with the original project's "no longer maintained" notice; and the README says that `compileFile` needs `codegenMode: 'async'` for an async loader, that its compiled function then returns a promise of `{ output, exports }`, and how to port `not in` to native swig; the swig-jinja2 and swig-django READMEs lead with `renderFile` against an async loader.
+* **Changed — development only.** The `globals` dev dependency moves to 17.x; `make lint` reports the same clean result.
+
+See the full [HISTORY.md](./HISTORY.md) and [ROADMAP.md](./ROADMAP.md).
+
 Benchmarks
 ----------
 
@@ -50,7 +73,7 @@ Benchmarks
 cd benchmarks && npm install && node render.js
 ```
 
-In production-typical settings (autoescape on), `@rhinostone/swig` outperforms Nunjucks on iteration-heavy templates by 2–3.5× and ties on simple control flow. See [`benchmarks/README.md`](./benchmarks/README.md) for the methodology, the full result table, and how to reproduce on your own hardware.
+In production-typical settings (autoescape on), `@rhinostone/swig` leads Nunjucks on all five workload shapes — from ~1.3× on simple variable output to 5.3–5.9× on iteration-heavy templates (median of 5 runs, 2026-10). See [`benchmarks/README.md`](./benchmarks/README.md) for the methodology, the full result table, and how to reproduce on your own hardware.
 
 Need Help? Have Questions? Comments?
 ------------------------------------
@@ -78,7 +101,7 @@ For Django syntax:
 Documentation
 -------------
 
-User-facing documentation lives in the Gina Docusaurus site under the [Swig Template Engine](https://gina.io/docs/templating/swig) section, maintained in [gina-io/docs](https://github.com/gina-io/docs) at `docs/templating/swig/`. The JSDoc blocks in `lib/swig.js`, `lib/filters.js`, `lib/tags/`, and `lib/loaders/` remain the canonical source-of-truth for the public API and are mirrored into the Docusaurus pages.
+User-facing documentation lives in the Gina Docusaurus site under the [Swig Template Engine](https://gina.io/docs/templating/swig) section, maintained in [gina-io/docs](https://github.com/gina-io/docs) at `docs/templating/swig/`. The JSDoc blocks in `lib/swig.js`, `lib/filters.js`, `lib/tags/`, and `packages/swig-core/lib/loaders/` remain the canonical source-of-truth for the public API and are mirrored into the Docusaurus pages.
 
 Basic Example
 -------------
@@ -130,14 +153,14 @@ Migrating from Jinja2 or Django
 
 Swig is *inspired by* Jinja2 and Django, not a drop-in replacement. Common pitfalls when porting existing templates:
 
-* **No `is` / `is not` / `not in` operators** — rewrite `{% if x is defined %}` as `{% if x !== undefined %}`, `{% if x not in xs %}` as `{% if not (x in xs) %}`.
+* **No `is` / `is not` / `not in` operators** — rewrite `{% if x is defined %}` as `{% if x !== undefined %}`, and `{% if x not in xs %}` for a list as `{% if xs.indexOf(x) === -1 %}` (`in` tests an object's keys or an array's indices, not membership).
 * **Django `forloop.counter` → Swig `loop.index`** (Swig follows Jinja2 loop-variable naming).
 * **`{{ super() }}` / `{{ block.super }}` → `{% parent %}`** — Swig uses a dedicated tag inside the overriding block.
 * **Django filter args use a colon (`|date:"Y-m-d"`) — Swig uses parens (`|date("Y-m-d")`)**.
 * **`{% with x=1 %}` → `{% set x = 1 %}`**, and no block-form `{% set %}…{% endset %}`.
 * **No `{% from "f" import x %}` — use `{% import "f" as ns %}` + `ns.x` instead**.
 * **Method calls require parens** — Django auto-invokes `x.get_absolute_url`; Swig needs `x.get_absolute_url()`.
-* **~25 Jinja2 filters are absent** — `default`, `truncate`, `tojson`, `round`, `int`, `float`, `map`, `select`, `batch`, `trim`, etc. Register them via `swig.setFilter(name, fn)`.
+* **Many Jinja2 filters are absent** — `truncate`, `tojson`, `round`, `int`, `float`, `map`, `select`, `batch`, `trim`, etc. (`default` **is** built in). Register missing ones via `swig.setFilter(name, fn)` — or use [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2), which ships 39 of them natively.
 
 Full parity tables and workaround patterns: **[Migration Guide](https://gina.io/docs/templating/swig/migration)**.
 
@@ -148,6 +171,8 @@ Swig reads template files and translates them into cached JavaScript functions.
 
 In `2.x`, frontend parsers (native Swig syntax in [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig), Twig syntax in [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig), Python Jinja2 syntax in [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2), Django Template Language syntax in [@rhinostone/swig-django](https://www.npmjs.com/package/@rhinostone/swig-django)) emit a shared intermediate representation. The backend in [@rhinostone/swig-core](https://www.npmjs.com/package/@rhinostone/swig-core) lowers IR to JS. New flavors plug in at the frontend without touching the runtime.
 
+For strict-CSP targets the compile pipeline can be skipped entirely: AOT-compile templates with the CLI (`swig compile --recursive --register`) and execute the resulting bundle with the runtime-only build (`dist/swig.runtime.min.js`), which contains no parser and no `new Function`.
+
 License
 -------
 

package/ROADMAP.md

@@ -8,24 +8,39 @@ For bug reports and feature requests, file an issue at [gina-io/swig](https://gi
 
 ## Next
 
-_No near-term scheduled items. See [Future (post-2.0)](#future-post-20) for upcoming work._
+| Status | Item |
+| --- | --- |
+| Planned | `in` tests membership in all four flavors: `x in list` tests the elements and `x in "text"` the substring. Today `in` tests an object's keys or an array's indices, so `3 in [1, 2, 3]` is false. |
+| Planned | swig-jinja2 parity: loop filters (`{% for x in xs if cond %}`), `not(x)` written without a space, the `none` / `True` / `False` constants, for-loops over a mapping and over a list of pairs as Jinja2 iterates them, and the builtin filters `attr`, `filesizeformat`, `forceescape`, `items`, `string` and `urlize`. |
+| Planned | swig-django: two-variable for-loops over a list of pairs unpack each pair, as Django does. |
+| Planned | Unknown filter and test names rejected when a Twig, Jinja2 or Django template compiles; today the error comes only at render, or never when the branch does not run. Native swig already rejects an unknown filter. |
 
 ## Future (post-2.0)
 
 | Status | Item |
 | --- | --- |
 | Planned | Async parse path for the remaining dynamic targets — runtime-resolved `{% import %}` / `{% from %}` paths on the async-codegen branch. Static-target async dispatch shipped in 2.2.0; dynamic `{% extends %}` shipped in 2.5.2 (native + Twig + Jinja2) and dynamic `{% include %}` paths already resolve (the include path has always been an expression). Dynamic `import` / `from` are on hold pending consumer demand. |
-| Planned | Modern browser-test harness. The legacy phantomjs runner was removed; a replacement (e.g. Playwright or JSDOM) has not yet landed, so browser parity is verified in the interim via the production build plus a symbol grep. (The `mocha` → `node:test` runner migration, the `expect.js` → in-repo assertion-shim swap, and the `blanket` → `node:test` built-in coverage migration have all shipped.) |
-| On demand | Runtime-only browser bundles for the Twig, Jinja2, and Django frontends. The shared runtime factory already supports them — each needs its own bundle entry and build target, since filter catalogs are per-flavor. The native `dist/swig.runtime.min.js` shipped in 2.8.0; the flavor bundles land when a consumer needs one. |
+| Planned | Modern browser-test harness. The legacy phantomjs runner was removed; a replacement (e.g. Playwright or JSDOM) has not yet landed. In the interim, CI builds the four browser bundles and renders a template set through each in a Node vm context, comparing the output with the Node library. (The `mocha` → `node:test` runner migration, the `expect.js` → in-repo assertion-shim swap, and the `blanket` → `node:test` built-in coverage migration have all shipped.) |
+| On demand | Ahead-of-time browser support for the Twig, Jinja2, and Django frontends, in two parts that ship together. Runtime-only bundles: the shared runtime factory already supports them, and each flavor needs its own bundle entry and build target, since filter catalogs are per-flavor. A flavor-aware compile step: `swig compile --register` compiles with the native parser only, so flavor templates are precompiled programmatically until it lands. The native `dist/swig.runtime.min.js` shipped in 2.8.0; the flavor pieces land when a consumer needs them. |
 
 ---
 
 ## Completed
 
+### v2.8.2 (October 2026)
+
+- Fixed two hangs that request data can reach. swig-jinja2's `wordwrap` with a width below 1, as a number or as a string such as `"0"`, ran for four to six seconds and took more than 2 GB of memory before a RangeError; it now returns the input unchanged, and a width between 0 and 1 breaks one character at a time. swig-twig's `a..b` with an infinite bound, which plain JSON produces for a number such as `1e999`, looped until the array overflowed; the range is now empty.
+- Fixed parenthesized sub-expressions in every flavor. Since 2.0.0-alpha.2 a group whose operator binds more loosely than the operator outside it, a comparison grouped inside a comparison and a subscript on a `+` group were evaluated without their parentheses, and `-(-x)` failed to compile.
+- Fixed swig-jinja2 expression precedence to follow Jinja2 (a unary minus before the filters and `**`, `**` read from the left, tests bound at the filter level and taking a bare argument, `not` below the comparisons) and its `lower`, `upper`, `odd` and `number` tests.
+- Fixed swig-jinja2 and swig-django filters that diverged from the reference engines: Jinja2 `first`, `last`, `reverse`, `unique`, `min`, `max`, `slice`, `batch`, `sort`, `replace`, `format` and `wordwrap`, and Django `join`, `pluralize`, `truncatechars` and `truncatewords`.
+- Fixed the shared engine in all four frontends: an async-mode compile has its own cache entry, a compile error is reported when no options object is passed, and the control options must be strings.
+- The prototype-chain guards' error messages end with `(prototype-chain guard)` instead of `(CVE-2023-25345)`, which is the loader's directory-traversal CVE, and every package exports its `version`.
+- All five packages released in lockstep at `2.8.2`.
+
 ### v2.8.0 (August 2026)
 
 - Added ahead-of-time template registration: `swig.register(path, fn)` and `swig.registerBundle(map)` place pre-compiled template functions into the template cache under loader-normalized keys, so `include`, `compileFile`, and `renderFile` resolve them without a compiler. Available on all four frontends (native, Twig, Jinja2, Django). `swig compile --recursive --register` emits a bundle that registers itself on load and also exports the template map, so a page needs no per-template wiring.
-- Added a runtime-only browser build — `dist/swig.runtime.js` and `dist/swig.runtime.min.js` (21 KB minified, roughly a quarter of the full bundle). It executes pre-compiled bundles with the full filter catalog but ships no lexer, parser, or code generator, and therefore contains no `new Function`: pages served under a strict Content-Security-Policy without `unsafe-eval` can render AOT-compiled templates. Every compiling entry point throws a clear error naming the CLI workflow instead of failing obscurely. Also available to Node as `require('@rhinostone/swig/runtime')`.
+- Added a runtime-only browser build — `dist/swig.runtime.js` and `dist/swig.runtime.min.js` (22 KB minified, roughly a quarter of the full bundle). It executes pre-compiled bundles with the full filter catalog but ships no lexer, parser, or code generator, and therefore contains no `new Function`: pages served under a strict Content-Security-Policy without `unsafe-eval` can render AOT-compiled templates. Every compiling entry point throws a clear error naming the CLI workflow instead of failing obscurely. Also available to Node as `require('@rhinostone/swig/runtime')`.
 - Fixed several template-cache paths that failed silently. A registered template no longer shadows a loadable `{% extends %}` parent — the parent's source is still read through the loader, where previously registering a layout could make a child that rendered correctly start rendering an empty string with no error. The memory loader rejects a climbing path when a `basepath` is set rather than resolving it to a different template than the one requested. Passing a filepath to `run` now caches an entry a later `include` can actually use. The memory cache no longer treats inherited object members as cache hits. `register` reports a disabled cache for every falsy `cache` value, and `registerBundle` validates a whole bundle before committing any of it, so a malformed map cannot leave the registry half-populated.
 - Fixed browser integration for the new bundles: a self-registering bundle finds the engine whether it is a bare global or a property of the global object (under AMD there is no bare binding, so every template previously went unregistered in silence) and warns when no engine is present; loading a runtime bundle twice, or after the full build, no longer discards existing registrations or replaces a compiler-capable instance; and the runtime entry no longer assumes `window`, so it loads in a worker. Both minified bundles now reference the source map filename that is actually written.
 - All five packages (`@rhinostone/swig`, `@rhinostone/swig-core`, `@rhinostone/swig-twig`, `@rhinostone/swig-jinja2`, `@rhinostone/swig-django`) released in lockstep at `2.8.0`. Lockstep is now required rather than conventional: the frontends reference modules inside `@rhinostone/swig-core` that exist only from this version forward.

package/SECURITY.md

@@ -14,8 +14,8 @@ security fix ships across the family at the same version.
 
 | Version            | Supported          |
 | ------------------ | ------------------ |
-| `2.7.x` (latest)   | :white_check_mark: |
-| `< 2.7.0`          | :x: — upgrade      |
+| `2.8.x` (latest)   | :white_check_mark: |
+| `< 2.8.0`          | :x: — upgrade      |
 
 ## Reporting a vulnerability
 

package/context7.json

@@ -0,0 +1,17 @@
+{
+  "url": "https://context7.com/gina-io/swig",
+  "public_key": "pk_MGD4ulFUKUHnxmzFGuWc8",
+  "projectTitle": "Rhinostone Swig",
+  "description": "Rhinostone Swig is a simple, powerful, and extendable template engine for Node.js and browsers, supporting native Swig, Twig, Python Jinja2, and Django Template Language syntaxes.",
+  "branch": "develop",
+  "excludeFolders": [
+    ".changes"
+  ],
+  "excludeFiles": [
+    "HISTORY.md",
+    "ROADMAP.md",
+    "AUTHORS",
+    "ISSUE_TEMPLATE.md",
+    "PULL_REQUEST_TEMPLATE.md"
+  ]
+}

package/dist/swig.js

@@ -1,9 +1,13 @@
-/*! Swig v2.8.0 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
-/*! DateZ (c) 2011 Tomo Universalis | @license https://github.com/tomoio/DateZ/blob/master/LISENCE */
+/*! Swig v2.8.2 | https://github.com/gina-io/swig | @license https://github.com/gina-io/swig/blob/master/LICENSE */
+/*! DateZ (c) 2011 Tomo Universalis | @license https://github.com/tn0ms/DateZ/blob/master/LISENCE */
 (() => {
   var __getOwnPropNames = Object.getOwnPropertyNames;
   var __commonJS = (cb, mod) => function __require() {
-    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+    try {
+      return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+    } catch (e) {
+      throw mod = 0, e;
+    }
   };
 
   // packages/swig-core/lib/security.js
@@ -120,6 +124,9 @@
       exports.range = function(from, to) {
         var out = [], i, fc, tc;
         if (typeof from === "number" && typeof to === "number") {
+          if (!isFinite(from) || !isFinite(to)) {
+            return out;
+          }
           if (from <= to) {
             for (i = from; i <= to; i += 1) {
               out.push(i);
@@ -1324,7 +1331,7 @@
             throw new Error('Loop variable "' + token.match + '" must be a bare identifier in "for" tag on line ' + line + ".");
           }
           if (_dangerousProps.indexOf(token.match) !== -1) {
-            throw new Error('Unsafe loop variable "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+            throw new Error('Unsafe loop variable "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
           }
           if (!this.out.length) {
             firstVar = true;
@@ -1845,7 +1852,7 @@
         if (d.dangerousProps.indexOf(segment) !== -1) {
           var line = node && node.loc && node.loc.line || void 0;
           var filename = node && node.loc && node.loc.filename || void 0;
-          d.throwError('Unsafe access to "' + segment + '" is not allowed in templates (CVE-2023-25345)', line, filename);
+          d.throwError('Unsafe access to "' + segment + '" is not allowed in templates (prototype-chain guard)', line, filename);
         }
       }
       function emitLiteral(node, d) {
@@ -1905,13 +1912,19 @@
         if (node.key && node.key.type === "Literal" && node.key.kind === "string") {
           checkDangerousSegment(node.key.value, d, node);
         }
-        return emitExpr(node.object, d) + "[" + emitExpr(node.key, d) + "]";
+        return groupOperand(node.object, emitExpr(node.object, d), true) + "[" + emitExpr(node.key, d) + "]";
       }
       function isArithmeticOp(op) {
         return op === "+" || op === "-" || op === "*" || op === "/" || op === "%";
       }
+      function groupOperand(node, js, unary) {
+        if (node && (node.type === "BinaryOp" || unary && node.type === "UnaryOp")) {
+          return "(" + js + ")";
+        }
+        return js;
+      }
       function emitBinaryOp(node, d) {
-        var left = emitExpr(node.left, d), right = emitExpr(node.right, d);
+        var left = groupOperand(node.left, emitExpr(node.left, d)), right = groupOperand(node.right, emitExpr(node.right, d));
         if (isArithmeticOp(node.op)) {
           return left + " " + node.op + " " + right;
         }
@@ -1928,11 +1941,7 @@
         return left + node.op + right;
       }
       function emitUnaryOp(node, d) {
-        var operandJS = emitExpr(node.operand, d);
-        if (node.operand && node.operand.type === "BinaryOp") {
-          operandJS = "(" + operandJS + ")";
-        }
-        return node.op + operandJS;
+        return node.op + groupOperand(node.operand, emitExpr(node.operand, d), true);
       }
       function emitConditional(node, d) {
         return "(" + emitExpr(node.test, d) + " ? " + emitExpr(node.then, d) + " : " + emitExpr(node["else"], d) + ")";
@@ -2307,7 +2316,7 @@
               if (lastState === _t.BRACKETOPEN) {
                 var strippedMatch = match.replace(/^['"]|['"]$/g, "");
                 if (_dangerousProps.indexOf(strippedMatch) !== -1) {
-                  utils.throwError('Unsafe access to "' + strippedMatch + '" via bracket notation is not allowed in templates (CVE-2023-25345)', self.line, self.filename);
+                  utils.throwError('Unsafe access to "' + strippedMatch + '" via bracket notation is not allowed in templates (prototype-chain guard)', self.line, self.filename);
                 }
               }
               self.filterApplyIdx.push(self.out.length);
@@ -2455,7 +2464,7 @@
                 utils.throwError('Unexpected key "' + match + '"', self.line, self.filename);
               }
               if (_dangerousProps.indexOf(match) !== -1) {
-                utils.throwError('Unsafe access to "' + match + '" is not allowed in templates (CVE-2023-25345)', self.line, self.filename);
+                utils.throwError('Unsafe access to "' + match + '" is not allowed in templates (prototype-chain guard)', self.line, self.filename);
               }
               self.out.push("." + match);
               break;
@@ -2481,7 +2490,7 @@
           }
           utils.each(match, function(segment) {
             if (_dangerousProps.indexOf(segment) !== -1) {
-              utils.throwError('Unsafe access to "' + segment + '" is not allowed in templates (CVE-2023-25345)', self.line, self.filename);
+              utils.throwError('Unsafe access to "' + segment + '" is not allowed in templates (prototype-chain guard)', self.line, self.filename);
             }
           });
           self.filterApplyIdx.push(self.out.length);
@@ -2549,12 +2558,12 @@
           }
           function guardSegment(segment) {
             if (_dangerousProps.indexOf(segment) !== -1) {
-              bail('Unsafe access to "' + segment + '" is not allowed in templates (CVE-2023-25345)');
+              bail('Unsafe access to "' + segment + '" is not allowed in templates (prototype-chain guard)');
             }
           }
           function guardBracketString(value) {
             if (_dangerousProps.indexOf(value) !== -1) {
-              bail('Unsafe access to "' + value + '" via bracket notation is not allowed in templates (CVE-2023-25345)');
+              bail('Unsafe access to "' + value + '" via bracket notation is not allowed in templates (prototype-chain guard)');
             }
           }
           function getBinaryOpInfo(tok) {
@@ -3297,7 +3306,7 @@
             return;
           }
           if (_dangerousProps.indexOf(token.match) !== -1) {
-            throw new Error('Unsafe import alias "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+            throw new Error('Unsafe import alias "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
           }
           ctx = token.match;
           self.out.push(ctx);
@@ -3448,21 +3457,21 @@
           }
           if (!name) {
             if (_dangerousProps.indexOf(token.match) !== -1) {
-              throw new Error('Unsafe macro name "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+              throw new Error('Unsafe macro name "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
             }
             name = token.match;
             this.out.push(name);
             return;
           }
           if (_dangerousProps.indexOf(token.match) !== -1) {
-            throw new Error('Unsafe macro argument "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+            throw new Error('Unsafe macro argument "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
           }
           this.out.push({ name: token.match });
         });
         parser.on(types.FUNCTION, function(token) {
           if (!name) {
             if (_dangerousProps.indexOf(token.match) !== -1) {
-              throw new Error('Unsafe macro name "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+              throw new Error('Unsafe macro name "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
             }
             name = token.match;
             this.out.push(name);
@@ -3472,7 +3481,7 @@
         parser.on(types.FUNCTIONEMPTY, function(token) {
           if (!name) {
             if (_dangerousProps.indexOf(token.match) !== -1) {
-              throw new Error('Unsafe macro name "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+              throw new Error('Unsafe macro name "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
             }
             name = token.match;
             this.out.push(name);
@@ -3609,7 +3618,7 @@
             var segments = token.match.split(".");
             for (var i = 0; i < segments.length; i++) {
               if (_dangerousProps.indexOf(segments[i]) !== -1) {
-                throw new Error('Unsafe assignment to "' + segments[i] + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+                throw new Error('Unsafe assignment to "' + segments[i] + '" is not allowed (prototype-chain guard) on line ' + line + ".");
               }
             }
             nameSet += token.match;
@@ -3628,7 +3637,7 @@
           if (propertyName && !this.out.length) {
             var stripped = token.match.replace(/^['"]|['"]$/g, "");
             if (_dangerousProps.indexOf(stripped) !== -1) {
-              throw new Error('Unsafe assignment to "' + stripped + '" via bracket notation is not allowed (CVE-2023-25345) on line ' + line + ".");
+              throw new Error('Unsafe assignment to "' + stripped + '" via bracket notation is not allowed (prototype-chain guard) on line ' + line + ".");
             }
             propertyName += token.match;
             return;
@@ -3648,7 +3657,7 @@
             return true;
           }
           if (_dangerousProps.indexOf(token.match) !== -1) {
-            throw new Error('Unsafe assignment to "' + token.match + '" is not allowed (CVE-2023-25345) on line ' + line + ".");
+            throw new Error('Unsafe assignment to "' + token.match + '" is not allowed (prototype-chain guard) on line ' + line + ".");
           }
           nameSet += "." + token.match;
           return;
@@ -4408,6 +4417,9 @@
       function efn() {
         return "";
       }
+      function compileCacheKey(filename, options) {
+        return options && options.codegenMode === "async" ? filename + "#async" : filename;
+      }
       exports.remapBlocks = function remapBlocks(blocks, tokens) {
         return utils.map(tokens, function(token) {
           var args = token.args ? token.args.join("") : "";
@@ -4648,7 +4660,7 @@
           return { tpl, tokens };
         };
         self.compile = function(source, options) {
-          var key = options ? options.filename : null, cached = key ? cacheGet(key, options) : null, context, contextLength, pre;
+          var key = options && options.filename ? compileCacheKey(options.filename, options) : null, cached = key ? cacheGet(key, options) : null, context, contextLength, pre;
           if (cached) {
             return cached;
           }
@@ -4683,7 +4695,7 @@
           if (!options.filename) {
             options = utils.extend({ filename: pathname }, options);
           }
-          cached = cacheGet(pathname, options);
+          cached = cacheGet(compileCacheKey(pathname, options), options);
           if (cached) {
             if (cb) {
               cb(null, cached);
@@ -4810,7 +4822,7 @@
       var loaders = require_loaders2();
       var preWalker = require_pre_walker();
       var engine = require_engine();
-      exports.version = "2.8.0";
+      exports.version = "2.8.2";
       var defaultOptions = {
         autoescape: true,
         varControls: ["{{", "}}"],
@@ -4865,7 +4877,7 @@
           if (!options.hasOwnProperty(key)) {
             return;
           }
-          if (!utils.isArray(options[key]) || options[key].length !== 2) {
+          if (!utils.isArray(options[key]) || options[key].length !== 2 || typeof options[key][0] !== "string" || typeof options[key][1] !== "string") {
             throw new Error('Option "' + key + '" must be an array containing 2 different control strings.');
           }
           if (options[key][0] === options[key][1]) {
@@ -4873,7 +4885,7 @@
           }
           utils.each(options[key], function(a, i) {
             if (a.length < 2) {
-              throw new Error('Option "' + key + '" ' + (i ? "open " : "close ") + 'control must be at least 2 characters. Saw "' + a + '" instead.');
+              throw new Error('Option "' + key + '" ' + (i ? "close " : "open ") + 'control must be at least 2 characters. Saw "' + a + '" instead.');
             }
           });
         });
@@ -4910,7 +4922,11 @@
           filters: _filters,
           validateOptions,
           onCompileError: function(err, options) {
-            utils.throwError(err, null, options.filename);
+            var filename = options && options.filename;
+            if (err instanceof Error && (!filename || err.message.indexOf(" in file " + filename) !== -1)) {
+              throw err;
+            }
+            utils.throwError(err, null, filename);
           }
         });
         var self = this;
@@ -5139,6 +5155,14 @@
  * COMPARATOR output shape. `in` needs trailing space so the keyword
  * detokenises — `(a)in(b)` parses but `ain(b)` does not. @private
  */
+/*!
+ * Parenthesize an operand whose emitted JS could regroup. The IR tree
+ * carries the grouping (`(a + b) * c` parses to a `*` node whose left
+ * operand is the `+` node), so a nested binary node is wrapped or JS
+ * precedence and associativity regroup it (`a + b * c`). `unary` also
+ * wraps a unary operand, for the positions where its prefix would bind
+ * differently (`-(-x)`, `(-x)[0]`). @private
+ */
 /*!
  * Emit a function / method invocation. Three callee shapes:
  *   1. Single-segment VarRef (`foo(...)`) — FUNCTION-token pattern with