[sabind]

Why

Four confirmed bugs and one privately reported security issue in 3.0.1, found while reviewing the repo to solidify it:

• Subject and plain-text bodies are HTML-escaped at render time #26: subject lines and plain-text bodies were HTML-escaped, so a recipient named O'Brien saw O'Brien in the subject.
• render() silently drops all data when template data has a key named "style" #27: template data with a key named style was mistaken for a render context and every placeholder rendered empty, with no error.
• CI and release fail on npm audit for dev-only advisories #28: every CI run since August failed at the audit step, and the release workflow would have refused to publish.
• Nested blocks with the same name pair the outer open with the inner close #29: a block nested under its own key paired with the inner close tag and left the tail as text.
• GHSA-25x2-qphj-x3cv (draft advisory, published with this release): values substituted inside a {{#block}} were parsed as template syntax on a second pass. A client-supplied value such as a display name could read any other variable in the same render, or pull in trusted slot HTML unescaped. The HTML body is the only place the library promises escaping, and this bypassed it for every value that passed through a block.

What

The renderer now runs in a single pass, so rendered values are never rescanned; subject and text render as plain text; render-context detection only triggers on object-valued data and style; nested blocks that share a name close innermost first; CI and release install from the lockfile and audit production dependencies. Version bumped to 3.0.2.

Changes

• Single-pass template renderer (src/template.ts, tests, README). Plain text between blocks and each block body are rendered as separate pieces and concatenated, so no output is reparsed. Slot HTML that itself contains {{...}} is now output literally as a side effect. Fixes the advisory.
• Subject and text render without HTML escaping (src/compile.ts, src/types.ts, tests, README). renderTemplate takes an escape option, default true; the compiled template turns it off for subject and text. The HTML body is unchanged. Fixes Subject and plain-text bodies are HTML-escaped at render time #26.
• Render-context detection (src/compile.ts, tests, README). Input is a { data, style } context only when every key is one of those two and both are plain objects when present. Fixes render() silently drops all data when template data has a key named "style" #27.
• CI audit gate (both workflows, README, CONTRIBUTING, lockfile). Lockfile refreshed with npm audit fix; both workflows use npm ci and npm audit --audit-level=high --omit=dev. The advisories were in juice's production tree, not dev-only as the issue and the commit message first said; the lockfile bump is what clears them, and --omit=dev stays as policy because the dev tree is not shipped. Fixes CI and release fail on npm audit for dev-only advisories #28.
• Post-review tidy and regression tests (src/template.ts, src/compile.ts, README, CONTRIBUTING, tests). Combined text pattern hoisted to a module constant, an unreachable fallback removed, context detection reuses the renderer's plain-object check, contributor setup says npm ci, and eleven tests pin the adversarial and ordinary cases the independent review ran by hand.
• Stack-based block matching (src/template.ts, tests, README). Top-level blocks are found by scanning open and close tags with a stack, so a close pops the innermost open block of that name. Stray closes and unclosed opens stay literal. Done now because it rewrites the same matcher as the advisory fix and belongs in the same release. Fixes Nested blocks with the same name pair the outer open with the inner close #29.
• Version 3.0.2 (package.json, lockfile). Bumped so the fix for CI and the new version ship together.

Testing

• Full suite: 6 files, 38 tests, passing. Build clean, examples render, npm pack --dry-run unchanged at 29 files.
• Each of the four original fixes was independently reviewed: the reviewer reproduced the bug on the base commit, confirmed the new tests fail there and pass here, and accepted. The advisory reviewer ran twenty adversarial inputs against the renderer, including a value containing a complete block, a slot reference two blocks deep, a value trying to close its enclosing block, and a split {{ token; all held, and every ordinary case was byte-identical to the base.
• Both audit forms exit 1 on the base commit and 0 here. package.json dependencies unchanged.
• Visual regression tests were not run locally; CI runs them.

Risk and rollout

• Visible output change: an ampersand or apostrophe in a subject or text body is no longer entity-encoded. Worth a release note.
• Slot HTML containing {{...}} is no longer expanded.
• render({ style: null }) is now read as template data rather than a context; output is identical either way.
• After merge: tag v3.0.2 and push the tag to trigger the release workflow, then publish advisory GHSA-25x2-qphj-x3cv against 3.0.2. The first CI run on GitHub's runners is the real confirmation of the audit fix, since the advisory database moves.

Notes for reviewers

• The stack-based block matcher landed after the independent review of the renderer, so that review covers the single-pass property but not the scanner. The eleven regression tests from the review all pass against it.
• The commit "Fix CI audit gate failing on dev-only advisories (CI and release fail on npm audit for dev-only advisories #28)" has the wrong cause in its message; the corrected cause is in this description and on CI and release fail on npm audit for dev-only advisories #28.
• Mismatched close tags inside an open block are ignored rather than reported.
• Whether to keep the custom renderer or move to mustache.js is tracked separately in Decide whether to keep the custom template renderer or adopt mustache.js #30.

🤖 Generated with Claude Code

[sabind]

Should we default to escape true?

[sabind]

It already does. renderTemplate(template, data) escapes, and the only place the default lives is options.escape ?? true in src/template.ts. The HTML body two lines up uses that default.

Subject and text are the two callers that opt out, because they are not HTML. Escaping them is what produced O'Brien in the subject line (#26), so passing escape: true here would bring that bug back.

If the inline { escape: false } reads too much like a footgun, the alternative is a named helper such as renderPlainText(template, data) that wraps it, so the opt-out is visible by name at the call site. Happy to add that if you prefer it.