@rhinostone/swig-core 2.4.3 → 2.5.1

package/README.md

@@ -3,7 +3,7 @@
 
 [![NPM version](http://img.shields.io/npm/v/@rhinostone/swig-core.svg?style=flat)](https://www.npmjs.com/package/@rhinostone/swig-core) [![Socket Badge](https://socket.dev/api/badge/npm/package/@rhinostone/swig-core)](https://socket.dev/npm/package/@rhinostone/swig-core)
 
-> **Shared runtime** for the `@rhinostone/swig` family of template engines. Not intended for direct consumption unless you are building a custom frontend. Install [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) for the default Swig (Jinja2/Django-inspired) flavor, or [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) for the Twig flavor — both pull this package in pinned to the matching version.
+> **Shared runtime** for the `@rhinostone/swig` family of template engines. Not intended for direct consumption unless you are building a custom frontend. Install [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) for the default Swig (Jinja2/Django-inspired) flavor, [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) for the Twig flavor, or [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) for the Python Jinja2 flavor — they all pull this package in pinned to the matching version.
 
 Extracted from `@rhinostone/swig@1.6.0` during the `2.0.0-alpha.1` multi-flavor carve. See [ROADMAP.md](https://github.com/gina-io/swig/blob/develop/ROADMAP.md) for the release narrative.
 
@@ -21,6 +21,7 @@ Consumers
 
 * [@rhinostone/swig](https://www.npmjs.com/package/@rhinostone/swig) — default Swig flavor.
 * [@rhinostone/swig-twig](https://www.npmjs.com/package/@rhinostone/swig-twig) — Twig parity frontend.
+* [@rhinostone/swig-jinja2](https://www.npmjs.com/package/@rhinostone/swig-jinja2) — Python Jinja2 frontend.
 
 Versioning
 ----------

package/lib/backend.js

@@ -5,21 +5,21 @@ var utils = require('./utils'),
 /**
  * JS-codegen backend shared across @rhinostone/swig-family frontends.
  *
- * Phase 2 — the template-level walker dispatches on IR node shape. At
+ * The template-level walker dispatches on IR node shape. At
  * entry, each parse-tree token is lifted into an IR node: string tokens
  * become `IRText` (value carried verbatim, escaped at emit time);
  * VarToken / TagToken entries call `token.compile(...)` and the return
  * value is lifted according to its shape: a JS source string becomes
  * `IRLegacyJS` (userland `setTag` contract), a single IR node is spliced
  * in directly, and an array of IR nodes is flattened. The walker then
- * iterates the IR array and dispatches on node shape. Subsequent
- * sessions introduce further real IR emitters (`Autoescape`, `If`,
- * `For`, `Set`, etc.) alongside their matching tag migrations, and each
- * new shape gets its own dispatch branch here.
+ * iterates the IR array and dispatches on node shape. Real IR emitters
+ * (`Autoescape`, `If`, `For`, `Set`, etc.) were introduced alongside
+ * their matching tag migrations, and each new shape gets its own
+ * dispatch branch here.
  *
  * Userland tag `compile` functions keep returning JS source strings —
  * the `(compiler, args, content, parents, options, blockName)` contract
- * is unchanged. Built-in tags migrate per session by returning IR nodes
+ * is unchanged. Built-in tags migrate by returning IR nodes
  * directly. The `new Function(...)` wrapper stays with the native
  * frontend (filename-aware error attribution, per the seam rule).
  */
@@ -101,9 +101,9 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'If') {
-      // Phase 2 Session 14c: multi-branch shape. The native if tag owns
+      // Multi-branch shape. The native if tag owns
       // content scanning and splits at else/elseif marker tokens so each
-      // IRIfBranch carries its own test + body. Session 14b Commit 11
+      // IRIfBranch carries its own test + body. The IR migration
       // widened `test` to `IRExpr | IRLegacyJS | null`: `IRExpr` for
       // clean expressions, `null` for the trailing else, `IRLegacyJS`
       // for the filter-in-test fallback (`if.lowerExpr` bails on
@@ -114,8 +114,7 @@ exports.compile = function (template, parents, options, blockName) {
       //
       // Emission shape matches the pre-carve `} else if (...) {` /
       // `} else {` fragments that else.js and elseif.js used to return
-      // inline — byte-identity held on the session baseline (see
-      // Session 14c notes in roadmap).
+      // inline — byte-identity held on the baseline.
       var ifOut = '';
       utils.each(node.branches, function (br, bi) {
         var bodyJS = '',
@@ -148,7 +147,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'Set') {
-      // Phase 2 Session 14b Commit 10: target is structured IRVarRef
+      // Target is structured IRVarRef
       // for pure-dot LHS shapes (`foo`, `foo.bar.baz`), emitted as a
       // bare `_ctx.<dot.path>` lvalue with a per-segment _dangerousProps
       // guard. Bracket-touched targets (`foo[bar]`, `foo["bar"]`, mixed
@@ -156,7 +155,7 @@ exports.compile = function (template, parents, options, blockName) {
       // bracket-lvalue contract is a cross-flavor design call and is
       // deferred. The frontend's set-tag parse handler retains its own
       // _dangerousProps guards on every LHS path segment.
-      // `value` is an IRExpr node (Session 14b) — backward-compat string
+      // `value` is an IRExpr node — backward-compat string
       // fallback preserved for userland setTag tags that may still hand
       // in a raw JS fragment. Emits `<target> <op> <value>;`.
       var setTargetJS;
@@ -182,10 +181,10 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'For') {
-      // Phase 2: the full loopcache + _utils.each IIFE scaffolding is
+      // The full loopcache + _utils.each IIFE scaffolding is
       // emitted here; the frontend tag surfaces only (value, key,
       // iterable, body) and the backend owns all JS plumbing. `iterable`
-      // is an IRExpr node (Session 14b) — backward-compat string fallback
+      // is an IRExpr node — backward-compat string fallback
       // preserved for userland setTag tags that may still hand in a raw
       // JS fragment. The loopcache identifier uses `Math.random()`
       // per-occurrence to keep nested loops from clobbering each other's
@@ -209,9 +208,24 @@ exports.compile = function (template, parents, options, blockName) {
           return;
         }
       });
+      // `emptyBody` (Twig/Jinja2/Django `{% for … %}{% else %}`) runs when
+      // the iterable is absent or has no items. When unset, the early-return
+      // guard stays byte-identical to the no-else shape.
+      var forEmptyCheck = '  if (!__l) { return; }\n';
+      if (node.emptyBody) {
+        var forEmptyJS = '';
+        utils.each(node.emptyBody, function (b) {
+          if (b.type === 'LegacyJS') { forEmptyJS += b.js; return; }
+          if (b.type === 'Text' || b.type === 'Raw') {
+            forEmptyJS += '_output += "' + escapeTextValue(b.value) + '";\n';
+            return;
+          }
+        });
+        forEmptyCheck = '  if (!__l || !__len) {\n' + forEmptyJS + '  return;\n  }\n';
+      }
       out += '(function () {\n' +
         '  var __l = ' + forIterable + ', __len = (_utils.isArray(__l) || typeof __l === "string") ? __l.length : _utils.keys(__l).length;\n' +
-        '  if (!__l) { return; }\n' +
+        forEmptyCheck +
         '    var ' + ctxloopcache + ' = { loop: ' + ctxloop + ', ' + forVal + ': ' + ctx + forVal + ', ' + forKey + ': ' + ctx + forKey + ' };\n' +
         '    ' + ctxloop + ' = { first: false, index: 1, index0: 0, revindex: __len, revindex0: __len - 1, length: __len, last: false };\n' +
         '  _utils.each(__l, function (' + forVal + ', ' + forKey + ') {\n' +
@@ -231,12 +245,12 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'Macro') {
-      // Phase 2: `params` is IRMacroParam[] (Session 14b Commit 8) —
+      // `params` is IRMacroParam[] —
       // structured `{name, default?}` entries. Backend builds the JS
       // function param list via `names.join(', ')` and the _utils.each
       // shadow-delete indexOf list via `names.map(JSON.stringify).join(',')`.
       // A string[] fallback is preserved for userland setTag tags that
-      // may still hand in the pre-Phase-2 raw-token slice (including
+      // may still hand in the legacy raw-token slice (including
       // the `, ` separator quirk). The frontend's macro parse handler
       // has already applied the CVE-2023-25345 guard on the macro name
       // (FUNCTION/FUNCTIONEMPTY) and every param name (VAR).
@@ -250,10 +264,23 @@ exports.compile = function (template, parents, options, blockName) {
       });
       var macroParams = node.params || [],
         macroSigJS,
-        macroIndexOfJS;
+        macroIndexOfJS,
+        macroDefaultsJS = '';
       if (macroParams.length && typeof macroParams[0] === 'object' && macroParams[0] !== null && typeof macroParams[0].name === 'string') {
         var macroNames = [];
-        utils.each(macroParams, function (p) { macroNames.push(p.name); });
+        utils.each(macroParams, function (p) {
+          macroNames.push(p.name);
+          // Parameter defaults — `{% macro foo(a, b='x') %}` carries an
+          // IRExpr on `p.default`. Emit `if (b === undefined) { b = <expr>; }`
+          // at the top of the macro body, before the _ctx shadow-delete, so a
+          // default expression reads the incoming context (and earlier
+          // parameters) consistently with the macro model. Missing args
+          // arrive as `undefined`, so the guard applies the default while
+          // leaving an explicit falsy value (`0`, `false`, `''`) alone.
+          if (p['default']) {
+            macroDefaultsJS += '  if (' + p.name + ' === undefined) { ' + p.name + ' = ' + exports.emitExpr(p['default']) + '; }\n';
+          }
+        });
         macroSigJS = macroNames.join(', ');
         var macroJsonNames = [];
         utils.each(macroNames, function (n) { macroJsonNames.push(JSON.stringify(n)); });
@@ -265,6 +292,7 @@ exports.compile = function (template, parents, options, blockName) {
       out += '_ctx.' + node.name + ' = function (' + macroSigJS + ') {\n' +
         '  var _output = "",\n' +
         '    __ctx = _utils.extend({}, _ctx);\n' +
+        macroDefaultsJS +
         '  _utils.each(_ctx, function (v, k) {\n' +
         '    if ([' + macroIndexOfJS + '].indexOf(k) !== -1) { delete _ctx[k]; }\n' +
         '  });\n' +
@@ -273,7 +301,7 @@ exports.compile = function (template, parents, options, blockName) {
         '  return _output;\n' +
         '};\n' +
         '_ctx.' + node.name + '.safe = true;\n';
-      // Phase 3 (#T22): async-codegen mirrors the macro into _exports so
+      // Async-codegen mirrors the macro into _exports so
       // {% import %} / Twig's {% from %} can bind macros across templates
       // at runtime. The macro's closure still references _ctx (not
       // _exports) for outer-ctx lookups — sync-semantics-preserving.
@@ -289,7 +317,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'Parent') {
-      // Phase 2: the parent tag walks the parents chain at compile time
+      // The parent tag walks the parents chain at compile time
       // and splices the matched block's pre-resolved body into this node.
       // Emit the body verbatim; no wrapper, no `super()`-style runtime
       // plumbing is needed (the lookup is fully resolved at parse time).
@@ -303,13 +331,13 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'Block') {
-      // Phase 2: block tokens are resolved at parse time by the engine's
+      // Block tokens are resolved at parse time by the engine's
       // remapBlocks / importNonBlocks — by the time the backend walks a
       // block, its body carries whichever generation's content is active.
       // Emit the body verbatim; the block name is carried as metadata for
       // downstream tooling (parent-chain walks happen in the parent tag).
       //
-      // Phase 3 (#T22) async mode: block remapping happens at runtime
+      // Async mode: block remapping happens at runtime
       // instead of parse time. When _blocks is supplied (by an extending
       // child via IRExtendsDeferred-emitted `_parent(_ctx, _mergedBlocks)`)
       // and contains an override for this block name, call the override
@@ -345,8 +373,8 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'Include') {
-      // Phase 2: `path` and `context` are IRExpr nodes (Session 14b
-      // Commit 7) — per-slot dispatch on object-with-.type → emitExpr,
+      // `path` and `context` are IRExpr nodes — per-slot dispatch on
+      // object-with-.type → emitExpr,
       // else verbatim string fallback preserves the userland setTag
       // path (compile functions that still hand in raw JS-source
       // fragments). `resolveFrom` is a plain filesystem path that must
@@ -384,7 +412,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'IncludeDeferred') {
-      // Phase 3 (#T22): async-codegen counterpart to Include. Resolves the
+      // Async-codegen counterpart to Include. Resolves the
       // path via `_swig.getTemplate(...)` at render time (Promise<TemplateFn>),
       // then awaits the resolved template fn's call. The double-await flows
       // correctly whether the loaded tpl is sync (returns string) or async-
@@ -419,7 +447,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'ImportDeferred') {
-      // Phase 3 (#T22): async-codegen counterpart to the parse-time
+      // Async-codegen counterpart to the parse-time
       // import flow. The imported template is loaded via _swig.getTemplate
       // and called with the parent's _ctx so its body's compiled JS
       // closes over outer-ctx vars (sync-semantics-preserving). Only
@@ -439,7 +467,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'FromImportDeferred') {
-      // Phase 3 (#T22): async-codegen counterpart to Twig's `{% from
+      // Async-codegen counterpart to Twig's `{% from
       // "file" import a, b as c %}`. Single getTemplate call, then
       // per-entry bind onto _ctx. Async IIFE keeps `_imp` local so
       // multiple from-imports in the same template don't collide.
@@ -472,7 +500,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'ExtendsDeferred') {
-      // Phase 3 (#T22): async-codegen counterpart to engine.getParents +
+      // Async-codegen counterpart to engine.getParents +
       // engine.precompile's parse-time block remap. Inverts at runtime
       // via the _blocks parameter contract:
       //
@@ -535,7 +563,7 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'With') {
-      // Phase 3 Session 12: scoped-context region (Twig's `{% with %}`).
+      // Scoped-context region (Twig's `{% with %}`).
       // Emits an IIFE that shadows `_ctx` for the body's lexical scope;
       // `_output` stays in the outer scope and is mutated via closure, so
       // body writes still flow to the compiled template's output.
@@ -578,8 +606,8 @@ exports.compile = function (template, parents, options, blockName) {
       return;
     }
     if (node.type === 'Output') {
-      // Phase 2: `expr` is typed IRExpr | IRLegacyJS (Session 14b
-      // Commit 9). The frontend's parseVariable falls back to LegacyJS
+      // `expr` is typed IRExpr | IRLegacyJS. The frontend's parseVariable
+      // falls back to LegacyJS
       // for shapes the flat IROutput.filters chain can't represent
       // (per-operand filter precedence, deep filters, partial consumes,
       // string-valued autoescape). LegacyJS carries the complete
@@ -602,11 +630,20 @@ exports.compile = function (template, parents, options, blockName) {
           outExprJS = '_filters["' + fc.name + '"](' + outExprJS + fcArgsJS + ')';
         });
       }
-      out += '_output += ' + outExprJS + ';\n';
+      // Opt-in null/undefined output coercion. A frontend sets
+      // `node.coerce` on outputs whose expression is not a VarRef (VarRef
+      // already coerces in emitVarRef), so an expression that evaluates to
+      // null / undefined renders as "" instead of the literal word. When
+      // the flag is absent the emit is unchanged.
+      if (node.coerce) {
+        out += '_output += _utils.coerceOutput(' + outExprJS + ');\n';
+      } else {
+        out += '_output += ' + outExprJS + ';\n';
+      }
       return;
     }
     if (node.type === 'Filter') {
-      // Phase 2: `args` is IRExpr[] (Session 14b Commit 6) — per-arg
+      // `args` is IRExpr[] — per-arg
       // dispatch on object-with-.type → emitExpr, else verbatim string
       // fallback preserves the userland setTag path (compile functions
       // that still hand in raw JS-source fragments).
@@ -641,7 +678,7 @@ exports.compile = function (template, parents, options, blockName) {
 
 /**
  * Emit a JS-source fragment for a single IR expression node. Round-trip
- * target for the TokenParser → IRExpr migration (#T15 Session 14+): once
+ * target for the TokenParser → IRExpr migration: once
  * the frontend produces real {@link IRExpr} values, every transitional
  * `IRExpr | string` slot in the statement IR (IRFilter.args,
  * IRIfBranch.test, IRFor.iterable, IRSet.target/value, IRInclude.path/

package/lib/engine.js

@@ -24,7 +24,7 @@ function efn() { return ''; }
 /**
  * Runtime engine plumbing shared across @rhinostone/swig-family frontends.
  *
- * Phase 1 carve — owns the `extends`-chain walker and block-remap helpers.
+ * Owns the `extends`-chain walker and block-remap helpers.
  * The native Swig constructor in lib/swig.js delegates here so each frontend
  * inherits the loader-walk + circular-extends detection + block merge logic
  * for free.

package/lib/filters.js

@@ -3,7 +3,7 @@ var utils = require('./utils');
 /**
  * Filter infrastructure shared across @rhinostone/swig-family frontends.
  *
- * Phase 1 carve — `iterateFilter` and the `.safe` flag convention live
+ * `iterateFilter` and the `.safe` flag convention live
  * here so every flavor's filter catalog (native Swig, Twig, Jinja2,
  * Django) picks up identical recursion + autoescape-bypass semantics.
  * Filter catalogs themselves stay per-flavor.

package/lib/index.js

@@ -2,7 +2,7 @@
  * @rhinostone/swig-core — shared IR, backend, and runtime for the swig
  * family of template engines.
  *
- * Phase 1 scaffold. Subsequent commits move security guards, loader
+ * Initial scaffold. Subsequent commits move security guards, loader
  * contract, filter infra, cache, and the JS-codegen backend in from
  * @rhinostone/swig.
  */

package/lib/ir.js

@@ -49,8 +49,8 @@
  * Output an expression with optional filter chain.
  * `safe: true` bypasses autoescape.
  *
- * `expr` is typed `IRExpr | IRLegacyJS` for Phase 2 — see Session 14b
- * Commit 9. The IR shape can't represent legacy Swig's per-operand
+ * `expr` is typed `IRExpr | IRLegacyJS`. The IR shape can't represent
+ * legacy Swig's per-operand
  * filter precedence (filter binds to the last operand across binary
  * ops, e.g. `{{ a + b|upper }}` → `a + _filters["upper"](b)`); for
  * those outputs the frontend falls back to the legacy JS-string
@@ -91,8 +91,8 @@
  * lowers cleanly, or an {@link IRLegacyJS} escape-hatch when the test
  * contains a top-level filter chain mixed with a binary op (e.g.
  * `{% if a === b|upper %}`) — per-operand filter precedence cannot be
- * represented in a flat IR, same widening as {@link IROutput.expr} in
- * Session 14b Commit 9. The factory is opaque — it accepts any value
+ * represented in a flat IR, same widening as {@link IROutput.expr}.
+ * The factory is opaque — it accepts any value
  * and stores it — but consumers (backends) dispatch on the shape.
  *
  * @typedef {Object} IRIfBranch
@@ -103,7 +103,7 @@
 /**
  * For-loop. `emptyBody` supports Twig/Django `{% for … %}{% else %}`.
  *
- * `iterable` is typed `IRExpr | string` for Phase 2 — the native
+ * `iterable` is typed `IRExpr | string` — the native
  * frontend still hands in a raw JS-source string (its `for` tag has
  * not migrated to expression-level IR), while the Twig frontend lowers
  * to a real {@link IRExpr}. Backends MUST tolerate both shapes — same
@@ -182,7 +182,7 @@
  */
 
 /**
- * Phase 2 Session 14b Commit 10: pure-dot LHS shapes (`foo`, `foo.bar`,
+ * Pure-dot LHS shapes (`foo`, `foo.bar`,
  * `foo.bar.baz`) are now structured {@link IRVarRef} nodes. The
  * bracket-touched path (`foo[bar]`, `foo["bar"]`, mixed dot+bracket)
  * stays on the transitional `string` form — bracket-lvalue semantics
@@ -213,12 +213,12 @@
 /**
  * Emit the parent block's compiled content (super() / block.super).
  *
- * During Phase 2 (#T15), IRParent optionally carries a `body` slot so
+ * IRParent optionally carries a `body` slot so
  * the native frontend's parent tag can resolve the parent-chain lookup
  * at compile time (emitting the matched block's body) without the
  * backend having to re-walk the parents array. Target shape is a bare
  * marker — the backend resolves parent() by itself — reached once the
- * IR owns the extends/blocks graph directly (post-Phase 2).
+ * IR owns the extends/blocks graph directly.
  *
  * @typedef {Object} IRParent
  * @property {'Parent'} type
@@ -271,7 +271,7 @@
  * functions, and built-in tags not yet migrated to real IR nodes. The
  * backend concatenates `js` verbatim into the compiled template body.
  *
- * Transitional per the Phase 2 layering decision (hybrid / option iii).
+ * Transitional per the layering decision (hybrid / option iii).
  *
  * @typedef {Object} IRLegacyJS
  * @property {'LegacyJS'} type
@@ -626,7 +626,7 @@ exports.ifBranch = function (test, body) {
 /**
  * Build an {@link IRFor} node.
  *
- * `iterable` is typed `IRExpr | string` for Phase 2 — see the IRFor typedef
+ * `iterable` is typed `IRExpr | string` — see the IRFor typedef
  * for the transitional shape. The factory stores `iterable` opaquely and
  * does not inspect it.
  *
@@ -659,7 +659,7 @@ exports.block = function (name, body, loc) {
 /**
  * Build an {@link IRInclude} node.
  *
- * `path` and `context` are {@link IRExpr} nodes (Session 14b Commit 7).
+ * `path` and `context` are {@link IRExpr} nodes.
  * The factory stores both opaquely and does not inspect them — backward-
  * compat string fallback is handled at backend emit time for userland
  * setTag tags that may still hand in raw JS-source fragments.
@@ -735,8 +735,8 @@ exports.call = function (callee, args, loc) {
  * Build an {@link IRSet} node. `target` MUST pass the dangerousProps
  * guard at every path segment at backend emit time.
  *
- * `target` is typed `IRVarRef | string` for Phase 2 — pure-dot LHS
- * shapes are structured {@link IRVarRef} (Session 14b Commit 10);
+ * `target` is typed `IRVarRef | string` — pure-dot LHS
+ * shapes are structured {@link IRVarRef};
  * bracket-touched LHS stays a string fragment until the cross-flavor
  * bracket-lvalue contract lands. The factory stores `target` and
  * `value` opaquely and does not inspect them. `op` is the JS assignment
@@ -765,11 +765,11 @@ exports.raw = function (value, loc) {
 /**
  * Build an {@link IRParent} super()-equivalent node.
  *
- * Phase 2: optional `body` slot carries the pre-resolved parent-block
+ * Optional `body` slot carries the pre-resolved parent-block
  * content as IR statements. Swig's parent tag walks the parents chain
  * at compile time and drops the matched block's body here; backends
  * emit the body as-is. A bare Parent (no body) is valid and means the
- * backend will resolve the lookup itself — reached post-Phase 2.
+ * backend will resolve the lookup itself.
  *
  * @param  {IRStatement[]} [body]
  * @param  {IRLoc}         [loc]

package/lib/tokenparser.js

@@ -428,9 +428,9 @@ TokenParser.prototype = {
    * `parseExpr` emits structured IR that {@link backend.emitExpr}
    * later lowers into an equivalent JS-source fragment. `.parse()` is
    * unchanged and remains the production path; `parseExpr` is the
-   * incoming target shape for Phase 2 (#T15), introduced additively in
-   * Session 14b so the IR grammar can be proven against real lexer
-   * output before consumers are flipped in Commits 3-8.
+   * incoming target shape for the IR migration, introduced additively
+   * so the IR grammar can be proven against real lexer output before
+   * consumers are flipped over to it.
    *
    * The CVE-2023-25345 prototype-chain guards (`_dangerousProps` on
    * VAR segments, DOTKEY matches, STRING-inside-BRACKETOPEN values,

package/lib/utils.js

@@ -218,3 +218,96 @@ exports.range = function (from, to) {
   }
   return out;
 };
+
+/**
+ * Python-style slice for arrays and strings. Mirrors Jinja2's
+ * `seq[start:stop:step]` subscript: negative indices count from the end,
+ * omitted bounds (null/undefined) take their step-direction default, and a
+ * negative step walks backwards (`seq[::-1]` reverses). Returns a string
+ * for string input and an array otherwise. A null/undefined object or a
+ * non-indexable value yields an empty result so compiled templates degrade
+ * silently rather than throwing at render time.
+ *
+ * @param  {Array|string} obj
+ * @param  {?number}      start
+ * @param  {?number}      stop
+ * @param  {?number}      step
+ * @return {Array|string}
+ */
+exports.slice = function (obj, start, stop, step) {
+  var isString = (typeof obj === 'string'),
+    length,
+    lower,
+    upper,
+    s,
+    e,
+    result = [],
+    i;
+
+  function toInt(n) {
+    n = Number(n);
+    if (isNaN(n)) { return NaN; }
+    return n < 0 ? Math.ceil(n) : Math.floor(n);
+  }
+
+  function clamp(v, dflt) {
+    if (v === null || v === undefined) { return dflt; }
+    v = toInt(v);
+    if (isNaN(v)) { return dflt; }
+    if (v < 0) {
+      v += length;
+      if (v < lower) { v = lower; }
+    } else if (v > upper) {
+      v = upper;
+    }
+    return v;
+  }
+
+  if (obj === null || obj === undefined || typeof obj.length !== 'number') {
+    return isString ? '' : [];
+  }
+  length = obj.length;
+
+  if (step === null || step === undefined) {
+    step = 1;
+  } else {
+    step = toInt(step);
+    if (isNaN(step) || step === 0) { step = 1; }
+  }
+
+  // Lower / upper bounds depend on walk direction (CPython slice rules).
+  if (step < 0) {
+    lower = -1;
+    upper = length - 1;
+  } else {
+    lower = 0;
+    upper = length;
+  }
+
+  s = clamp(start, (step < 0) ? upper : lower);
+  e = clamp(stop, (step < 0) ? lower : upper);
+
+  if (step > 0) {
+    for (i = s; i < e; i += step) { result.push(obj[i]); }
+  } else {
+    for (i = s; i > e; i += step) { result.push(obj[i]); }
+  }
+
+  return isString ? result.join('') : result;
+};
+
+/**
+ * Coerce a value for string output: `null` and `undefined` become the
+ * empty string, everything else passes through unchanged. Used by the
+ * backend's `Output` emit when a frontend opts in via `IROutput.coerce`,
+ * so a non-VarRef expression that evaluates to null / undefined renders
+ * as "" rather than the literal word "null" / "undefined". (VarRef
+ * outputs already coerce in `emitVarRef`, so frontends only flag
+ * non-VarRef outputs.)
+ *
+ * @param  {*} v
+ * @return {*} `v`, or "" when `v` is null / undefined.
+ */
+exports.coerceOutput = function (v) {
+  return (v === null || v === undefined) ? '' : v;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhinostone/swig-core",
-  "version": "2.4.3",
+  "version": "2.5.1",
   "description": "Shared IR, backend, and runtime for the @rhinostone/swig family of template engines.",
   "keywords": [
     "template",