@rhinostone/swig 2.7.3 → 2.8.0

package/HISTORY.md

@@ -1,3 +1,18 @@
+[2.8.0](https://github.com/gina-io/swig/tree/v2.8.0) / 2026-08-02
+-----------------------------------------------------------------
+
+* **Added** AOT template registration — swig.register(path, fn) and swig.registerBundle(map) on every flavor store pre-compiled templates in the template cache under loader-normalized keys, wrapped in the locals-binding call shape include expects (priming via swig.run cached the raw template function, which crashed included partials that used variables or filters); swig compile --recursive --register emits a self-registering browser bundle
+
+* **Added** Runtime-only browser build — dist/swig.runtime.js and dist/swig.runtime.min.js execute pre-compiled template bundles (register, registerBundle, run, compileFile, renderFile with the native filter catalog and a root-based memory loader) and ship no parser and no new Function, so pages under a strict Content-Security-Policy without unsafe-eval can render AOT-compiled templates; also exposed to Node as require("@rhinostone/swig/runtime")
+
+* **Fixed** Updated the stale `/docs/swig` and `/docs/swig/migration` documentation links to their canonical `/docs/templating/swig` and `/docs/templating/swig/migration` paths in `README.md` (4 occurrences) and `CONTRIBUTING.md` (1 occurrence) (2026-06-15 link-health scan, gina-io/gina#39). The old URLs still resolved via the 301 redirects added in the 2026-04-23 Templating umbrella restructure, but were no longer canonical and kept accruing redirect hops. Documentation only; no runtime or API change.
+
+* **Fixed** Refreshed two stale external URLs flagged by the 2026-06-22 / 2026-06-29 link-health scans (gina-io/gina#43). `README.md` now links to `https://expressjs.com/` instead of the plain-HTTP `http://expressjs.com/` (the domain 301-redirects HTTP to HTTPS). `browser/comments.js` updates the DateZ `@license` URL from `github.com/ocrybit/DateZ` to `github.com/tomoio/DateZ` — the upstream GitHub user was renamed again (same class as the v2.0.0 `TomoUniversalis` to `ocrybit` rename); the target repo keeps the upstream `LISENCE` spelling. Documentation and comment-only; no runtime or API change.
+
+* **Fixed** De-linked the two remaining live references to the archived `paularmstrong/swig` repository (GitHub topic `unmaintained-dont-use`, last released 2014), flagged by the 2026-07-06 link-health scan (gina-io/gina#47). `README.md` no longer links the "abandoned `paularmstrong/swig`" mention to the archived repo root, and `CONTRIBUTING.md` de-links the "Pull Request 273" historical example (a PR on the archived repo, where contributions are disabled) — both references are preserved as plain text for traceability, matching the de-linking house style from the gina-io/gina#18 and #33 link-health fixes. Documentation only; no runtime or API change.
+
+* **Fixed** Several template-cache paths failed silently and now report the problem. The memory loader rejects a climbing path when a basepath is set, instead of resolving it to a different template than the one requested — with a root basepath it clamped and rendered the wrong file, mirroring the confinement the filesystem loader already enforces. Passing a filepath to run stores the same locals-binding wrapper, under the same resolved key, that a cache lookup expects, so a template primed that way is usable by a later include rather than crashing on the raw function argument shape. The memory cache no longer reads inherited object members, so an identifier-style loader cannot resolve a name such as constructor to a cache hit. Both minified bundles now point at the source map filename that is actually written.
+
 [2.7.3](https://github.com/gina-io/swig/tree/v2.7.3) / 2026-06-10
 -----------------------------------------------------------------
 

package/README.md

@@ -3,11 +3,11 @@ Swig
 
 [![CI](https://github.com/gina-io/swig/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/gina-io/swig/actions/workflows/ci.yml) [![NPM version](https://img.shields.io/npm/v/@rhinostone/swig.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig) [![NPM Downloads](https://img.shields.io/npm/dm/@rhinostone/swig.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig)](https://socket.dev/npm/package/@rhinostone/swig)
 
-> **Multi-flavor template engine** for Node.js and browsers — native Swig syntax (Jinja2/Django-inspired), Twig syntax, Python Jinja2 syntax, and Django Template Language syntax via dedicated frontends sharing one IR backend. [gina-io/swig](https://github.com/gina-io/swig) started as a maintained continuation of the abandoned [paularmstrong/swig](https://github.com/paularmstrong/swig) (last released 2014) and is now a standalone project. Security and bug fixes ship here.
+> **Multi-flavor template engine** for Node.js and browsers — native Swig syntax (Jinja2/Django-inspired), Twig syntax, Python Jinja2 syntax, and Django Template Language syntax via dedicated frontends sharing one IR backend. [gina-io/swig](https://github.com/gina-io/swig) started as a maintained continuation of the abandoned `paularmstrong/swig` (last released 2014) and is now a standalone project. Security and bug fixes ship here.
 
 > **Part of the [Gina](https://github.com/gina-io/gina) ecosystem.** This is the built-in template engine for [Gina](https://gina.io) ([npm](https://www.npmjs.com/package/gina)), a Node.js MVC framework with HTTP/2, multi-bundle architecture, and scope-based data isolation.
 
-Swig is a **Jinja2/Django-inspired** template engine for node.js and browsers. The syntax will feel familiar to Jinja2 and Django users, but Swig is **not drop-in compatible** with either — porting templates from an existing project requires a handful of changes. See the [Migration Guide](https://gina.io/docs/swig/migration) for the full parity list and workaround patterns.
+Swig is a **Jinja2/Django-inspired** template engine for node.js and browsers. The syntax will feel familiar to Jinja2 and Django users, but Swig is **not drop-in compatible** with either — porting templates from an existing project requires a handful of changes. See the [Migration Guide](https://gina.io/docs/templating/swig/migration) for the full parity list and workaround patterns.
 
 > **Coming from Twig?** Install [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) instead — a dedicated Twig-syntax frontend with closer parity than working around incompatibilities here.
 
@@ -32,7 +32,7 @@ Features
 --------
 
 * Available for node.js **and** major web browsers.
-* [Express](http://expressjs.com/) compatible.
+* [Express](https://expressjs.com/) compatible.
 * 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).
@@ -56,7 +56,7 @@ Need Help? Have Questions? Comments?
 ------------------------------------
 
 * File an issue at [gina-io/swig/issues](https://github.com/gina-io/swig/issues).
-* Swig v0.x → v1.x migration notes — the original upstream wiki has been deleted; see `HISTORY.md` entries around v1.0.0 for the individual breaking changes. For porting *from Jinja2 or Django* into Swig, see the [Migration Guide](https://gina.io/docs/swig/migration).
+* Swig v0.x → v1.x migration notes — the original upstream wiki has been deleted; see `HISTORY.md` entries around v1.0.0 for the individual breaking changes. For porting *from Jinja2 or Django* into Swig, see the [Migration Guide](https://gina.io/docs/templating/swig/migration).
 
 Installation
 ------------
@@ -78,7 +78,7 @@ For Django syntax:
 Documentation
 -------------
 
-User-facing documentation lives in the Gina Docusaurus site under the [Swig Template Engine](https://gina.io/docs/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 `lib/loaders/` remain the canonical source-of-truth for the public API and are mirrored into the Docusaurus pages.
 
 Basic Example
 -------------
@@ -139,7 +139,7 @@ Swig is *inspired by* Jinja2 and Django, not a drop-in replacement. Common pitfa
 * **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)`.
 
-Full parity tables and workaround patterns: **[Migration Guide](https://gina.io/docs/swig/migration)**.
+Full parity tables and workaround patterns: **[Migration Guide](https://gina.io/docs/templating/swig/migration)**.
 
 How it works
 ------------

package/ROADMAP.md

@@ -16,11 +16,20 @@ _No near-term scheduled items. See [Future (post-2.0)](#future-post-20) for upco
 | --- | --- |
 | 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. |
 
 ---
 
 ## Completed
 
+### 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')`.
+- 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.
+
 ### v2.7.3 (June 2026)
 
 - Fixed a filter-chain argument leak in the expression parsers: the per-filter argument accumulator was function-scoped and never reset between iterations, so an arg-bearing filter earlier in a chain leaked its arguments onto a later no-arg filter (e.g. `x|default("y")|upper` lowered `upper` with the leaked `["y"]`). Affected nested and parenthesized chains in the shared core parser and all filter chains in the Twig and Jinja2 frontends; the Django frontend already shipped the per-iteration reset. Runtime impact ranged from harmless (filters that ignore extra positional arguments) to wrong output (a no-arg filter consuming a leaked positional argument).

package/bin/swig.js

@@ -27,6 +27,7 @@ var FLAGS = {
   'm': { alias: 'minify', boolean: true },
   'r': { alias: 'recursive' },
   'ext': {},
+  'register': { boolean: true },
   'filters': {},
   'tags': {},
   'options': {},
@@ -313,6 +314,10 @@ function validate(argv) {
     }
   }
 
+  if (argv.register && !argv.r) {
+    throw new Error('--register requires --recursive; it emits a self-registering bundle of the compiled directory.');
+  }
+
   if (argv.ext && !argv.r) {
     throw new Error('--ext is only meaningful with --recursive.');
   }
@@ -344,6 +349,7 @@ function usage() {
     '    -m, --minify        Minify compiled functions with terser',
     '    -r, --recursive     Recursively compile every template in <dir> into a single AOT bundle module.',
     '    --ext               Comma-separated list of file extensions to include when using --recursive (e.g. ".html,.swig"). Defaults to no filter.',
+    '    --register          With --recursive: emit a self-registering bundle (calls swig.registerBundle when a global swig is present; also exports the template map).',
     '    --filters           Custom filters as a CommonJS-style file',
     '    --tags              Custom tags as a CommonJS-style file',
     '    --options           Customize Swig\'s Options from a CommonJS-style file',
@@ -418,6 +424,13 @@ function walkSync(dir) {
  * resolution still happens at render time through the consumer's loader. The
  * bundle is not a closed module against inheritance chains.
  *
+ * With <code>--register</code> the bundle self-registers instead: it calls
+ * <code>swig.registerBundle(map)</code> against a global <code>swig</code>
+ * when one is present (a browser page that loaded the swig bundle first),
+ * and still exports the raw map for Node-side consumers. Run the command
+ * from the template root (<code>swig compile -r . --register</code>) so
+ * baked include paths line up with the bundle's registration keys.
+ *
  * @param  {string}  dir Directory to walk.
  * @return {undefined}   Writes to stdout or to <code>argv.o</code>.
  * @private
@@ -452,7 +465,27 @@ function bundleRecursive(dir) {
     parts.push(JSON.stringify(key) + ': ' + tpl);
   });
 
-  output = 'module.exports = {\n' + parts.join(',\n') + '\n};\n';
+  if (argv.register) {
+    // The engine may be reachable as a bare global (classic script tag) or
+    // only as a property of the global object — under AMD the browser entry
+    // registers a named module and never creates the bare binding, so a
+    // bare-identifier lookup alone would silently register nothing.
+    output = 'var __swigTemplates = {\n' + parts.join(',\n') + '\n};\n' +
+      'if (typeof module !== "undefined" && module.exports) {\n' +
+      '  module.exports = __swigTemplates;\n' +
+      '}\n' +
+      'var __swigEngine = (typeof swig !== "undefined" && swig) ||\n' +
+      '  (typeof window !== "undefined" && window.swig) ||\n' +
+      '  (typeof globalThis !== "undefined" && globalThis.swig) || null;\n' +
+      'if (__swigEngine && __swigEngine.registerBundle) {\n' +
+      '  __swigEngine.registerBundle(__swigTemplates);\n' +
+      '} else if (typeof console !== "undefined" && console.warn) {\n' +
+      '  console.warn("swig: no engine found; ' + parts.length + ' pre-compiled template(s) were not registered. ' +
+      'Load swig before this bundle, or call swig.registerBundle(__swigTemplates) yourself.");\n' +
+      '}\n';
+  } else {
+    output = 'module.exports = {\n' + parts.join(',\n') + '\n};\n';
+  }
 
   if (argv.m) {
     output = loadTerser().minify_sync(output).code;

package/dist/swig.js

@@ -1,5 +1,5 @@
-/*! Swig v2.7.3 | 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/ocrybit/DateZ/blob/master/LISENCE */
+/*! 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 */
 (() => {
   var __getOwnPropNames = Object.getOwnPropertyNames;
   var __commonJS = (cb, mod) => function __require() {
@@ -4176,6 +4176,9 @@
         basepath = basepath ? path.normalize(basepath) : null;
         ret.resolve = function(to, from) {
           if (basepath) {
+            if (/^\.\.([\\/]|$)/.test(path.normalize(to))) {
+              utils.throwError('Template "' + to + '" resolves outside the loader root "' + basepath + '".');
+            }
             from = basepath;
           } else {
             from = from ? path.dirname(from) : "/";
@@ -4376,7 +4379,7 @@
           return;
         }
         if (engineCache === "memory") {
-          return memoryStore[key];
+          return Object.prototype.hasOwnProperty.call(memoryStore, key) ? memoryStore[key] : void 0;
         }
         return engineCache.get(key);
       };
@@ -4475,7 +4478,10 @@
           }
           parentFile = parentFile || options.filename;
           parentFile = deps.resolve(parentName, parentFile);
-          parent = deps.cacheGet(parentFile, options) || deps.parseFile(parentFile, utils.extend({}, options, { filename: parentFile }));
+          parent = deps.cacheGet(parentFile, options);
+          if (!parent || !parent.tokens) {
+            parent = deps.parseFile(parentFile, utils.extend({}, options, { filename: parentFile }));
+          }
           parentName = parent.parent;
           if (parentFiles.indexOf(parentFile) !== -1) {
             throw new Error('Illegal circular extends of "' + parentFile + '".');
@@ -4526,6 +4532,52 @@
             self.cache = {};
           }
         };
+        function buildRegistered(fn) {
+          var context = getLocals(), contextLength = utils.keys(context).length;
+          return function registered(locals, blocks) {
+            var lcls;
+            if (locals && contextLength) {
+              lcls = utils.extend({}, context, locals);
+            } else if (locals && !contextLength) {
+              lcls = locals;
+            } else if (!locals && contextLength) {
+              lcls = context;
+            } else {
+              lcls = {};
+            }
+            return fn(self, lcls, filters, utils, efn, blocks);
+          };
+        }
+        function validateRegistration(path, fn) {
+          if (typeof path !== "string" || !path.length) {
+            throw new Error("Template registration path must be a non-empty string.");
+          }
+          if (typeof fn !== "function") {
+            throw new Error('Registered template for "' + path + '" is not a function. Pass a pre-compiled template function.');
+          }
+          if (!self.options.cache) {
+            throw new Error("Cannot register templates while caching is disabled (cache: " + self.options.cache + "). The registry is the compile cache.");
+          }
+        }
+        self.register = function(path, fn) {
+          validateRegistration(path, fn);
+          cacheSet(self.options.loader.resolve(path), {}, buildRegistered(fn));
+          return self;
+        };
+        self.registerBundle = function(map) {
+          var entries = [];
+          if (!map || typeof map !== "object") {
+            throw new Error("Template bundle must be an object of { path: templateFn } pairs.");
+          }
+          utils.each(map, function(fn, path) {
+            entries.push([path, fn]);
+            validateRegistration(path, fn);
+          });
+          utils.each(entries, function(entry) {
+            self.register(entry[0], entry[1]);
+          });
+          return self;
+        };
         self.setFilter = function(name, method) {
           if (typeof method !== "function") {
             throw new Error('Filter "' + name + '" is not a valid function.');
@@ -4739,7 +4791,7 @@
         self.run = function(tpl, locals, filepath) {
           var context = getLocals({ locals });
           if (filepath) {
-            cacheSet(filepath, {}, tpl);
+            cacheSet(self.options.loader.resolve(filepath), {}, buildRegistered(tpl));
           }
           return tpl(self, context, filters, utils, efn);
         };
@@ -4758,7 +4810,7 @@
       var loaders = require_loaders2();
       var preWalker = require_pre_walker();
       var engine = require_engine();
-      exports.version = "2.7.3";
+      exports.version = "2.8.0";
       var defaultOptions = {
         autoescape: true,
         varControls: ["{{", "}}"],
@@ -4963,6 +5015,8 @@
       exports.renderFile = defaultInstance.renderFile;
       exports.renderFileAsync = defaultInstance.renderFileAsync;
       exports.run = defaultInstance.run;
+      exports.register = defaultInstance.register;
+      exports.registerBundle = defaultInstance.registerBundle;
       exports.invalidateCache = defaultInstance.invalidateCache;
       exports.loaders = loaders;
     }
@@ -5126,6 +5180,17 @@
  * chunk, returning the trimmed tag body (e.g. `extends "x.html"`).
  * @private
  */
+/*!
+ * Wrap a pre-compiled template function in the locals-binding call shape
+ * cached entries have — include-emitted code invokes them as
+ * `(context)`, so the raw five-argument function is the wrong shape.
+ * @private
+ */
+/*!
+ * Shared argument checks for register / registerBundle, so a bundle can be
+ * validated in full before any entry is committed.
+ * @private
+ */
 /*!
  * Export methods publicly
  */