fix: stop leaking internal SafeString type through subexpression results (issue #660)

[rexm]

Summary

• ReturnInvoke (added for issue Subexpression encoding/escaping issue #543 on 2026-06-20) wraps every writer-based helper's captured output in an internal sealed class SafeString whenever it's used as a subexpression, so the outer expression doesn't double-encode already-safe content (e.g. content written via WriteSafeString).
• Only a handful of internal call sites were taught to unwrap that type: EncodedTextWriter.Write<T>, HandlebarsExtensions.WriteSafeString(object), HandlebarsUtils.IsFalsy, and PartialBinder. Any other consumer — including reflection-based/typed helper binders in third-party packages this library has no visibility into (e.g. Handlebars.Net.Helpers) — receives an opaque internal type it can neither cast to string nor unwrap.
• Reproduced the reporter's exact failure: a naive (string) arguments[0] cast on a subexpression's result throws InvalidCastException: Unable to cast object of type 'HandlebarsDotNet.SafeString' to type 'System.String'.

Fix

Replaced the wrapper type with SafeStrings (source/Handlebars/IO/SafeStrings.cs), a ConditionalWeakTable<string, object>-backed marker keyed by object reference. ReturnInvoke now returns the captured string itself, invisibly marked as already-encoded, instead of boxing it in a new type.

The value stays a genuine System.String the entire way through — castable, reflectable, and indistinguishable from any other string to every consumer except the encoding writer, which is the only place the "already encoded" signal actually needs to matter. Reference-keyed lookup means marking never affects a string a caller didn't obtain from this exact capture (no risk from string interning, since StringWriter.ToString() always produces a fresh instance).

This also let PartialBinder revert to its original Cast<string>(pex.PartialName) (dynamic partial names no longer need SafeString-aware unwrapping — they're just strings again) and dropped the now-redundant SafeString cases in HandlebarsUtils.IsFalsy and HandlebarsExtensions.WriteSafeString(object).

Fixes #660.

Test plan

• dotnet test — full suite passes (1908/1908)
• Existing Subexpression encoding/escaping issue #543 regression tests (HelperTests.SubexpressionWriteSafeStringNotDoubleEncoded, StandaloneWriteSafeStringNotEncoded) still pass — double-encoding fix is preserved
• Added Issue660_SubexpressionResultIsPlainString — asserts a subexpression's captured result is typeof(string), not the wrapper type
• Added Issue660_SubexpressionResultIsCastableToTypedStringParameter — mirrors the reporter's Append(string, string) helper, direct-casting a subexpression argument to string
• Verified both new tests fail with InvalidCastException : Unable to cast object of type 'HandlebarsDotNet.SafeString' to type 'System.String' when the source fix is reverted, confirming they're a faithful regression guard

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
93.8% Coverage on New Code
2.4% Duplication on New Code

See analysis details on SonarQube Cloud