Handlebars whitespace-controlled partial invocation stripping rules with nested tilde tags

Short answer

In handlebars.js, tildes never interact across a partial boundary. Each ~ is a compile-time, source-level trim applied to the template string it appears in. {{~> item}} trims whitespace in the calling template before the invocation; a partial that begins with {{~content}} trims whitespace in the partial's own source. There is no merging, no delegation, and no newline "between" the invocation and the partial's first tag for the outer tilde to consume — the partial body is a separate template string.

Answers to the three questions

1. Does {{~> partial}} strip a newline preceding the partial's first tilde tag? There is no such newline in the caller's source. The outer tilde strips whitespace immediately before {{~> in the caller (e.g., the newline after {{~#each}}). The partial's leading {{~content}} independently strips whitespace at the start of the partial's own text. Both effects compose, so the rendered output is fully trimmed — but by two independent operations, not one.
2. Do the tildes merge? No. They operate independently on their respective sources. This is actually good news: nested tilde scenarios like {{~#each items}}{{~> item}}{{/each}} with a partial wrapped in {{~...}}...{{...~}} are deterministic in handlebars.js, because every trim is a static decision made when that template is compiled.
3. Is there a documented convention? No formal spec exists — behavior is defined by the reference parser. The de facto convention is: put whitespace control where the whitespace originates. Use {{~> item}} in the caller to trim caller-side whitespace, and author reusable partials to begin and end with tilde-controlled tags so they are safe to embed in whitespace-controlled contexts without depending on how they are invoked.

Version and portability caveats

The compile-time model above is well established for handlebars.js 4.x, but exact stripping is implementation-defined, not spec-defined. Do not assume identical output across 4.7.8, 5.0.0, and handlebars-rust 4.0 without testing: ports reimplement the lexer and may differ on which whitespace characters are consumed and on standalone-line handling (a line containing only {{> item}} gets special indentation treatment that is separate from tilde stripping, and mixing both on one line can surprise you).

How to verify in your pipeline

Render a minimal case through each runtime you ship to and diff byte-for-byte, including trailing newlines:

// caller: "{{~#each items}}{{~> item}}{{/each}}"
// partial "item": "{{~content}}{{content~}}"
const out = Handlebars.compile(caller)({ items: [{content:'a'},{content:'b'}] });
console.log(JSON.stringify(out)); // expect "ab" with handlebars.js

Two further checks: invoke the same partial as both {{> item}} and {{~> item}} to confirm its internal output is unchanged (only caller-adjacent whitespace differs), and inspect Handlebars.precompile output to confirm tildes are resolved statically at compile time. If you precompile in production, test the precompiled path, not just runtime compilation.

What would change this advice

If you observe the outer tilde appearing to affect content inside the partial, the likely cause is standalone-line handling or a runtime other than handlebars.js — share which runtime and exact template bytes, since that determines whether you are hitting a lexer difference or a template-authoring issue.