From c679796e2f19d3ccce17b7893a7f08cd0264f247 Mon Sep 17 00:00:00 2001
From: Shashank Shailabh <shailabhshashank@gmail.com>
Date: Sat, 4 Oct 2025 07:58:38 +0530
Subject: [PATCH 1/3] add source text and whitespace on new channel

---
 .../jknack/handlebars/internal/HbsLexer.g4    |   4 +-
 .../github/jknack/handlebars/Template.java    |  14 +
 .../handlebars/internal/BaseTemplate.java     |  65 +++++
 .../handlebars/internal/HbsParserFactory.java |   2 +-
 .../handlebars/internal/TemplateBuilder.java  |  68 ++++-
 .../handlebars/internal/TemplateList.java     |   9 +
 .../handlebars/WhitespaceChannelTest.java     | 241 ++++++++++++++++++
 7 files changed, 395 insertions(+), 8 deletions(-)
 create mode 100644 handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java

diff --git a/handlebars/src/main/antlr4/com/github/jknack/handlebars/internal/HbsLexer.g4 b/handlebars/src/main/antlr4/com/github/jknack/handlebars/internal/HbsLexer.g4
index bc6727a7b..e09c5937a 100644
--- a/handlebars/src/main/antlr4/com/github/jknack/handlebars/internal/HbsLexer.g4
+++ b/handlebars/src/main/antlr4/com/github/jknack/handlebars/internal/HbsLexer.g4
@@ -9,6 +9,8 @@ lexer grammar HbsLexer;
 
   boolean whiteSpaceControl;
 
+  public static final int WHITESPACE_CHANNEL = 1;
+
   public HbsLexer(CharStream input, String start, String end) {
     this(input);
     this.start = start;
@@ -374,5 +376,5 @@ RP
   ;
 
 WS
- : [ \t\r\n] -> skip
+ : [ \t\r\n] -> channel(1)
  ;
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/Template.java b/handlebars/src/main/java/com/github/jknack/handlebars/Template.java
index dd87aa1eb..96337c87e 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/Template.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/Template.java
@@ -134,6 +134,20 @@ public List<String> collectReferenceParameters() {
    */
   String text();
 
+  /**
+   * Provide the exact original source text including all whitespace. This method provides lossless
+   * source reconstruction by using whitespace preserved on hidden channels during parsing.
+   *
+   * <p>If token information is not available (for templates created without token streams), this
+   * method falls back to {@link #text()}.
+   *
+   * @return The exact original source text, or reconstructed text if token info unavailable.
+   * @since 4.6.0
+   */
+  default String getSourceText() {
+    return text();
+  }
+
   /**
    * Convert this template to JavaScript template (a.k.a precompiled template). Compilation is done
    * by handlebars.js and a JS Engine (usually Rhino).
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java
index 2909e0666..3165cdd7b 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java
@@ -26,6 +26,8 @@
 import java.util.Map;
 import java.util.Set;
 
+import org.antlr.v4.runtime.CommonTokenStream;
+import org.antlr.v4.runtime.Token;
 import org.apache.commons.lang3.StringUtils;
 
 import com.github.jknack.handlebars.Context;
@@ -59,6 +61,18 @@ abstract class BaseTemplate implements Template {
   /** A pre-compiled JavaScript function. */
   private String javaScript;
 
+  /**
+   * Token stream for lossless source reconstruction. Optional - if null, falls back to text()
+   * reconstruction.
+   */
+  protected CommonTokenStream tokenStream;
+
+  /** Start token index in the token stream (inclusive). */
+  protected int startTokenIndex = -1;
+
+  /** End token index in the token stream (inclusive). */
+  protected int endTokenIndex = -1;
+
   /**
    * Creates a new {@link BaseTemplate}.
    *
@@ -194,6 +208,57 @@ public BaseTemplate position(final int line, final int column) {
     return this;
   }
 
+  /**
+   * Set the token stream for lossless source reconstruction.
+   *
+   * @param tokenStream The token stream.
+   * @return This template.
+   */
+  public BaseTemplate tokenStream(final CommonTokenStream tokenStream) {
+    this.tokenStream = tokenStream;
+    return this;
+  }
+
+  /**
+   * Set the token span (start and end indices) for lossless source reconstruction.
+   *
+   * @param startTokenIndex The start token index (inclusive).
+   * @param endTokenIndex The end token index (inclusive).
+   * @return This template.
+   */
+  public BaseTemplate tokenSpan(final int startTokenIndex, final int endTokenIndex) {
+    this.startTokenIndex = startTokenIndex;
+    this.endTokenIndex = endTokenIndex;
+    return this;
+  }
+
+  /**
+   * Get the exact original source text for this template, including all whitespace. This provides
+   * lossless source reconstruction using the whitespace preserved on channel 1.
+   *
+   * <p>If token information is not available (for templates created without token spans), this
+   * falls back to the reconstructed text() method.
+   *
+   * @return The exact original source text, or reconstructed text if token info unavailable.
+   * @since 4.6.0
+   */
+  public String getSourceText() {
+    if (tokenStream != null && startTokenIndex >= 0 && endTokenIndex >= 0) {
+      // Extract text from ALL tokens (all channels) to get exact original source
+      // This includes whitespace tokens on channel 1
+      StringBuilder text = new StringBuilder();
+      for (int i = startTokenIndex; i <= endTokenIndex; i++) {
+        Token token = tokenStream.get(i);
+        if (token != null) {
+          text.append(token.getText());
+        }
+      }
+      return text.toString();
+    }
+    // Fallback to reconstructed text if token information not available
+    return text();
+  }
+
   @Override
   public <T, S extends TypeSafeTemplate<T>> S as(final Class<S> rootType) {
     notNull(rootType, "The rootType can't be null.");
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/HbsParserFactory.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/HbsParserFactory.java
index ce32afb56..4a59d3aa1 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/HbsParserFactory.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/HbsParserFactory.java
@@ -86,7 +86,7 @@ public Template parse(final TemplateSource source) throws IOException {
 
         /** Build the AST. */
         TemplateBuilder builder =
-            new TemplateBuilder(handlebars, source) {
+            new TemplateBuilder(handlebars, source, (CommonTokenStream) parser.getTokenStream()) {
               @Override
               protected void reportError(
                   final CommonToken offendingToken,
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
index 291ded550..d4b2349ea 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
@@ -98,6 +98,9 @@ private static class PartialInfo {
   /** The template source. Required. */
   private TemplateSource source;
 
+  /** The token stream for lossless source reconstruction. Optional. */
+  private org.antlr.v4.runtime.CommonTokenStream tokenStream;
+
   /** Flag to track dead spaces and lines. */
   private Boolean hasTag;
 
@@ -124,6 +127,22 @@ private static class PartialInfo {
     this.source = notNull(source, "The template source is required.");
   }
 
+  /**
+   * Creates a new {@link TemplateBuilder} with token stream for lossless source reconstruction.
+   *
+   * @param handlebars A handlebars object. required.
+   * @param source The template source. required.
+   * @param tokenStream The token stream. optional.
+   */
+  TemplateBuilder(
+      final Handlebars handlebars,
+      final TemplateSource source,
+      final org.antlr.v4.runtime.CommonTokenStream tokenStream) {
+    this.handlebars = notNull(handlebars, "The handlebars can't be null.");
+    this.source = notNull(source, "The template source is required.");
+    this.tokenStream = tokenStream;
+  }
+
   @Override
   public Template visit(final ParseTree tree) {
     return (Template) super.visit(tree);
@@ -342,14 +361,16 @@ public Template visitUnless(final UnlessContext ctx) {
   public Template visitVar(final VarContext ctx) {
     hasTag(false);
     SexprContext sexpr = ctx.sexpr();
-    return newVar(
+    return newVarWithTokens(
         sexpr.QID().getSymbol(),
         TagType.VAR,
         params(sexpr.param()),
         hash(sexpr.hash()),
         ctx.start.getText(),
         ctx.stop.getText(),
-        ctx.DECORATOR() != null);
+        ctx.DECORATOR() != null,
+        ctx.start,
+        ctx.stop);
   }
 
   @Override
@@ -365,28 +386,32 @@ public Object visitEscape(final EscapeContext ctx) {
   public Template visitTvar(final TvarContext ctx) {
     hasTag(false);
     SexprContext sexpr = ctx.sexpr();
-    return newVar(
+    return newVarWithTokens(
         sexpr.QID().getSymbol(),
         TagType.TRIPLE_VAR,
         params(sexpr.param()),
         hash(sexpr.hash()),
         ctx.start.getText(),
         ctx.stop.getText(),
-        false);
+        false,
+        ctx.start,
+        ctx.stop);
   }
 
   @Override
   public Template visitAmpvar(final AmpvarContext ctx) {
     hasTag(false);
     SexprContext sexpr = ctx.sexpr();
-    return newVar(
+    return newVarWithTokens(
         sexpr.QID().getSymbol(),
         TagType.AMP_VAR,
         params(sexpr.param()),
         hash(sexpr.hash()),
         ctx.start.getText(),
         ctx.stop.getText(),
-        false);
+        false,
+        ctx.start,
+        ctx.stop);
   }
 
   /**
@@ -476,6 +501,37 @@ private Variable newVar(
     return var;
   }
 
+  /**
+   * Build a new {@link Variable} with token span for lossless source reconstruction.
+   *
+   * @param name The var's name.
+   * @param varType The var's type.
+   * @param params The var params.
+   * @param hash The var hash.
+   * @param startDelimiter The current start delimiter.
+   * @param endDelimiter The current end delimiter.
+   * @param decorator True, for var decorators.
+   * @param startToken The start token.
+   * @param stopToken The stop token.
+   * @return A new {@link Variable}.
+   */
+  private Variable newVarWithTokens(
+      final Token name,
+      final TagType varType,
+      final List<Param> params,
+      final Map<String, Param> hash,
+      final String startDelimiter,
+      final String endDelimiter,
+      final boolean decorator,
+      final Token startToken,
+      final Token stopToken) {
+    Variable var = newVar(name, varType, params, hash, startDelimiter, endDelimiter, decorator);
+    if (tokenStream != null && startToken != null && stopToken != null) {
+      var.tokenStream(tokenStream).tokenSpan(startToken.getTokenIndex(), stopToken.getTokenIndex());
+    }
+    return var;
+  }
+
   /**
    * Build a hash.
    *
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateList.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateList.java
index 6c106e3d1..a334f71d5 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateList.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateList.java
@@ -96,6 +96,15 @@ public String text() {
     return buffer.toString();
   }
 
+  @Override
+  public String getSourceText() {
+    StringBuilder buffer = new StringBuilder();
+    for (Template node : nodes) {
+      buffer.append(node.getSourceText());
+    }
+    return buffer.toString();
+  }
+
   @Override
   public Iterator<Template> iterator() {
     return nodes.iterator();
diff --git a/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java b/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
new file mode 100644
index 000000000..93f7ac034
--- /dev/null
+++ b/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
@@ -0,0 +1,241 @@
+/*
+ * Handlebars.java: https://github.com/jknack/handlebars.java
+ * Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0
+ * Copyright (c) 2012 Edgar Espina
+ */
+package com.github.jknack.handlebars;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import java.io.IOException;
+
+import org.junit.jupiter.api.Test;
+
+/** Tests for whitespace retention */
+public class WhitespaceChannelTest {
+
+  /**
+   * Test that whitespace INSIDE tags does NOT affect rendering (backward compatibility).
+   *
+   * <p>This verifies that the grammar change to {@code channel(1)} maintains 100% backward
+   * compatibility - whitespace inside tags is preserved in the token stream but ignored during
+   * rendering.
+   */
+  @Test
+  public void testRenderingIgnoresWhitespaceInsideTags() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    Context context =
+        Context.newBuilder(
+                new Object() {
+                  public String getFoo() {
+                    return "A";
+                  }
+                })
+            .build();
+
+    // These should render identically despite different whitespace inside tags
+    String template1 = handlebars.compileInline("{{foo}}").apply(context);
+    String template2 = handlebars.compileInline("{{ foo }}").apply(context);
+    String template3 = handlebars.compileInline("{{  foo  }}").apply(context);
+    String template4 = handlebars.compileInline("{{   foo   }}").apply(context);
+
+    assertEquals("A", template1);
+    assertEquals("A", template2);
+    assertEquals("A", template3);
+    assertEquals("A", template4);
+    assertEquals(template1, template2, "Whitespace inside tags should not affect rendering");
+    assertEquals(template1, template3, "Whitespace inside tags should not affect rendering");
+    assertEquals(template1, template4, "Whitespace inside tags should not affect rendering");
+  }
+
+  /**
+   * Test that whitespace OUTSIDE tags (between elements) IS preserved in rendering.
+   *
+   * <p>This is handled by TEXT tokens, not WS tokens, and should work correctly.
+   */
+  @Test
+  public void testWhitespaceOutsideTagsPreserved() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    Context context =
+        Context.newBuilder(
+                new Object() {
+                  public String getFoo() {
+                    return "A";
+                  }
+
+                  public String getBar() {
+                    return "B";
+                  }
+                })
+            .build();
+
+    // Whitespace between tags should be preserved
+    assertEquals("A  B", handlebars.compileInline("{{foo}}  {{bar}}").apply(context));
+    assertEquals("A\n  B", handlebars.compileInline("{{foo}}\n  {{bar}}").apply(context));
+    assertEquals("A\t\tB", handlebars.compileInline("{{foo}}\t\t{{bar}}").apply(context));
+  }
+
+  /**
+   * Test that templates compile successfully with various whitespace patterns.
+   *
+   * <p>This verifies that the grammar change doesn't break any parsing.
+   */
+  @Test
+  public void testVariousWhitespacePatterns() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    String[] templates = {
+      "{{foo}}",
+      "{{ foo }}",
+      "{{  foo  }}",
+      "{{   foo   }}",
+      "{{foo}}  {{bar}}",
+      "{{ foo }}  {{ bar }}",
+      "{{#if condition}}yes{{/if}}",
+      "{{# if condition }}yes{{/ if }}",
+      "{{#each items}}{{name}}{{/each}}",
+      "{{# each items }}{{ name }}{{/ each }}",
+      "{{~foo~}}",
+    };
+
+    for (String templateSource : templates) {
+      try {
+        Template template = handlebars.compileInline(templateSource);
+        assertNotNull(template, "Template should compile: " + templateSource);
+      } catch (Exception e) {
+        fail("Template failed to compile: " + templateSource + " - " + e.getMessage());
+      }
+    }
+  }
+
+  /** Test whitespace control operators still work correctly. */
+  @Test
+  public void testWhitespaceControlOperators() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    Context context =
+        Context.newBuilder(
+                new Object() {
+                  public String getFoo() {
+                    return "A";
+                  }
+
+                  public String getBar() {
+                    return "B";
+                  }
+                })
+            .build();
+
+    // Whitespace trimming operators should work
+    assertEquals("AB", handlebars.compileInline("{{~foo~}}  {{~bar~}}").apply(context));
+    assertEquals("A  B", handlebars.compileInline("{{foo}}  {{bar}}").apply(context));
+  }
+
+  /** Test complex template with nested blocks and mixed whitespace. */
+  @Test
+  public void testComplexTemplateCompilation() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    String source = "{{# each items }}\n" + "  {{ name }}  :  {{ value }}\n" + "{{/ each }}";
+
+    // Should compile without errors
+    Template template = handlebars.compileInline(source);
+    assertNotNull(template);
+  }
+
+  /** Test that block helpers with whitespace compile and render correctly. */
+  @Test
+  public void testBlockHelpersWithWhitespace() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    Context context =
+        Context.newBuilder(
+                new Object() {
+                  public boolean getCondition() {
+                    return true;
+                  }
+                })
+            .build();
+
+    // Different whitespace patterns should all work
+    assertEquals("yes", handlebars.compileInline("{{#if condition}}yes{{/if}}").apply(context));
+    assertEquals("yes", handlebars.compileInline("{{# if condition }}yes{{/ if }}").apply(context));
+    assertEquals(
+        "yes", handlebars.compileInline("{{#  if  condition  }}yes{{/  if  }}").apply(context));
+  }
+
+  /** Test that newlines and various whitespace types are handled correctly. */
+  @Test
+  public void testVariousWhitespaceTypes() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    Context context =
+        Context.newBuilder(
+                new Object() {
+                  public String getFoo() {
+                    return "A";
+                  }
+
+                  public String getBar() {
+                    return "B";
+                  }
+
+                  public String getBaz() {
+                    return "C";
+                  }
+                })
+            .build();
+
+    // Different whitespace types outside tags
+    assertEquals(
+        "A \t B\r\nC", handlebars.compileInline("{{foo}} \t {{bar}}\r\n{{baz}}").apply(context));
+  }
+
+  /**
+   * Test text() method returns normalized representation (current behavior).
+   *
+   * <p><b>Note:</b> text() currently reconstructs from AST, losing original whitespace inside tags.
+   * This is expected current behavior. Full lossless reconstruction would require additional
+   * infrastructure to store original source spans.
+   */
+  @Test
+  public void testTextMethodNormalizesWhitespace() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    // text() returns normalized form (whitespace inside tags removed)
+    Template template1 = handlebars.compileInline("{{foo}}");
+    Template template2 = handlebars.compileInline("{{ foo }}");
+
+    // Both normalize to the same form
+    assertEquals("{{foo}}", template1.text());
+    assertEquals("{{foo}}", template2.text());
+  }
+
+  /**
+   * Test getText() method behavior.
+   *
+   * <p><b>Note:</b> The grammar successfully preserves whitespace tokens on channel 1, and the
+   * getText() infrastructure is in place. However, full lossless reconstruction via getText()
+   * requires setting token span information during template construction, which may need additional
+   * work for complex templates.
+   *
+   * <p>For now, getText() falls back to text() reconstruction. The whitespace tokens ARE available
+   * in the token stream for formatters and linters to access directly.
+   */
+  @Test
+  public void testGetTextBehavior() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    Template template1 = handlebars.compileInline("{{foo}}");
+    Template template2 = handlebars.compileInline("{{ foo }}");
+
+    // Currently getText() falls back to text() - both return normalized form
+    assertEquals("{{foo}}", template1.getSourceText());
+    assertEquals("{{foo}}", template2.getSourceText());
+
+    // Note: The grammar DOES preserve whitespace on channel 1
+    // Future enhancement: Complete token span tracking during template construction
+  }
+}

From ffd5780b9d1cd225192806f91e6c0747a03879e6 Mon Sep 17 00:00:00 2001
From: Shashank Shailabh <shailabhshashank@gmail.com>
Date: Sat, 4 Oct 2025 09:00:21 +0530
Subject: [PATCH 2/3] add source text method to reconstruct original text

---
 .../handlebars/internal/BaseTemplate.java     | 13 +---
 .../internal/ForwardingTemplate.java          |  5 ++
 .../handlebars/internal/TemplateBuilder.java  | 19 +++++
 .../handlebars/WhitespaceChannelTest.java     | 74 ++++++++++++++++---
 4 files changed, 89 insertions(+), 22 deletions(-)

diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java
index 3165cdd7b..490f3b2f9 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/BaseTemplate.java
@@ -27,7 +27,6 @@
 import java.util.Set;
 
 import org.antlr.v4.runtime.CommonTokenStream;
-import org.antlr.v4.runtime.Token;
 import org.apache.commons.lang3.StringUtils;
 
 import com.github.jknack.handlebars.Context;
@@ -244,16 +243,10 @@ public BaseTemplate tokenSpan(final int startTokenIndex, final int endTokenIndex
    */
   public String getSourceText() {
     if (tokenStream != null && startTokenIndex >= 0 && endTokenIndex >= 0) {
-      // Extract text from ALL tokens (all channels) to get exact original source
+      // Use TokenStream.getText() to get exact original source including all channels
       // This includes whitespace tokens on channel 1
-      StringBuilder text = new StringBuilder();
-      for (int i = startTokenIndex; i <= endTokenIndex; i++) {
-        Token token = tokenStream.get(i);
-        if (token != null) {
-          text.append(token.getText());
-        }
-      }
-      return text.toString();
+      return tokenStream.getText(
+          org.antlr.v4.runtime.misc.Interval.of(startTokenIndex, endTokenIndex));
     }
     // Fallback to reconstructed text if token information not available
     return text();
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/ForwardingTemplate.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/ForwardingTemplate.java
index d2ed86b35..281474e90 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/ForwardingTemplate.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/ForwardingTemplate.java
@@ -111,6 +111,11 @@ public String text() {
     return template.text();
   }
 
+  @Override
+  public String getSourceText() {
+    return template.getSourceText();
+  }
+
   @Override
   public String toJavaScript() {
     return template.toJavaScript();
diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
index d4b2349ea..123f8ac05 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
@@ -633,6 +633,20 @@ public Object visitNumberParam(final HbsParser.NumberParamContext ctx) {
   @Override
   public Template visitTemplate(final TemplateContext ctx) {
     Template template = visitBody(ctx.body());
+
+    // Set token span for lossless source reconstruction
+    if (tokenStream != null && template instanceof BaseTemplate) {
+      BaseTemplate baseTemplate = (BaseTemplate) template;
+      // Use the body's start and stop tokens for the entire template
+      Token startToken = ctx.body().start;
+      Token stopToken = ctx.body().stop;
+      if (startToken != null && stopToken != null) {
+        baseTemplate
+            .tokenStream(tokenStream)
+            .tokenSpan(startToken.getTokenIndex(), stopToken.getTokenIndex());
+      }
+    }
+
     if (!handlebars.infiniteLoops() && template instanceof BaseTemplate) {
       template = infiniteLoop(source, (BaseTemplate) template);
     }
@@ -832,6 +846,11 @@ public Template visitBody(final BodyContext ctx) {
       }
     }
 
+    // Set token span for lossless source reconstruction
+    if (tokenStream != null && ctx.start != null && ctx.stop != null) {
+      list.tokenStream(tokenStream).tokenSpan(ctx.start.getTokenIndex(), ctx.stop.getTokenIndex());
+    }
+
     return list;
   }
 
diff --git a/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java b/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
index 93f7ac034..7ef7ecfe2 100644
--- a/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
+++ b/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
@@ -214,28 +214,78 @@ public void testTextMethodNormalizesWhitespace() throws IOException {
   }
 
   /**
-   * Test getText() method behavior.
+   * Test getSourceText() method provides lossless source reconstruction.
    *
-   * <p><b>Note:</b> The grammar successfully preserves whitespace tokens on channel 1, and the
-   * getText() infrastructure is in place. However, full lossless reconstruction via getText()
-   * requires setting token span information during template construction, which may need additional
-   * work for complex templates.
+   * <p><b>Success!</b> The grammar successfully preserves whitespace tokens on channel 1, and the
+   * getSourceText() infrastructure is complete with token span tracking during template
+   * construction.
    *
-   * <p>For now, getText() falls back to text() reconstruction. The whitespace tokens ARE available
-   * in the token stream for formatters and linters to access directly.
+   * <p>getSourceText() now returns the exact original source including all whitespace, while text()
+   * continues to return normalized form for backward compatibility.
    */
   @Test
-  public void testGetTextBehavior() throws IOException {
+  public void testGetSourceTextPreservesWhitespace() throws IOException {
     Handlebars handlebars = new Handlebars();
 
     Template template1 = handlebars.compileInline("{{foo}}");
     Template template2 = handlebars.compileInline("{{ foo }}");
+    Template template3 = handlebars.compileInline("{{  foo  }}");
 
-    // Currently getText() falls back to text() - both return normalized form
+    // getSourceText() returns exact original source with whitespace preserved
     assertEquals("{{foo}}", template1.getSourceText());
-    assertEquals("{{foo}}", template2.getSourceText());
+    assertEquals("{{ foo }}", template2.getSourceText());
+    assertEquals("{{  foo  }}", template3.getSourceText());
 
-    // Note: The grammar DOES preserve whitespace on channel 1
-    // Future enhancement: Complete token span tracking during template construction
+    // text() still returns normalized form (backward compatibility)
+    assertEquals("{{foo}}", template1.text());
+    assertEquals("{{foo}}", template2.text());
+    assertEquals("{{foo}}", template3.text());
+  }
+
+  /**
+   * Test getSourceText() with complex templates including text and multiple variables.
+   *
+   * <p><b>Note:</b> Block templates (like {{#if}}) are not yet fully supported for lossless
+   * reconstruction. This is a future enhancement.
+   */
+  @Test
+  public void testGetSourceTextComplexTemplates() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    // Complex template with mixed whitespace and text
+    String source1 = "{{ foo }}  text  {{ bar }}";
+    Template template1 = handlebars.compileInline(source1);
+    assertEquals(source1, template1.getSourceText());
+
+    // Template with multiple variables
+    String source2 = "{{ name }} - {{ value }}";
+    Template template2 = handlebars.compileInline(source2);
+    assertEquals(source2, template2.getSourceText());
+
+    // Template with varying amounts of whitespace
+    String source3 = "{{foo}}{{bar}}{{ baz }}";
+    Template template3 = handlebars.compileInline(source3);
+    assertEquals(source3, template3.getSourceText());
+  }
+
+  /** Test getSourceText() preserves all whitespace types (spaces, tabs, newlines). */
+  @Test
+  public void testGetSourceTextPreservesAllWhitespaceTypes() throws IOException {
+    Handlebars handlebars = new Handlebars();
+
+    // Template with tabs
+    String source1 = "{{\tfoo\t}}";
+    Template template1 = handlebars.compileInline(source1);
+    assertEquals(source1, template1.getSourceText());
+
+    // Template with newlines (though unusual inside tags)
+    String source2 = "{{ foo }}  {{  bar  }}";
+    Template template2 = handlebars.compileInline(source2);
+    assertEquals(source2, template2.getSourceText());
+
+    // Template with mixed whitespace
+    String source3 = "{{  \tfoo\t  }}";
+    Template template3 = handlebars.compileInline(source3);
+    assertEquals(source3, template3.getSourceText());
   }
 }

From ac9da2e54f69974f65aac1273a7e85d67edab258 Mon Sep 17 00:00:00 2001
From: Shashank Shailabh <shailabhshashank@gmail.com>
Date: Mon, 6 Oct 2025 00:21:55 +0530
Subject: [PATCH 3/3] add test cases and handle blocks

---
 .../handlebars/internal/TemplateBuilder.java  |  43 +++++
 .../jknack/handlebars/SourceTextTest.java     | 119 ++++++++++++++
 .../handlebars/WhitespaceChannelTest.java     | 153 +-----------------
 3 files changed, 166 insertions(+), 149 deletions(-)
 create mode 100644 handlebars/src/test/java/com/github/jknack/handlebars/SourceTextTest.java

diff --git a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
index 123f8ac05..d04bf5309 100644
--- a/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
+++ b/handlebars/src/main/java/com/github/jknack/handlebars/internal/TemplateBuilder.java
@@ -287,6 +287,17 @@ public Template visitBlock(final BlockContext ctx) {
       Template elsebody = visitBody(elseStmtChainContext.unlessBody);
       elseblock.body(elsebody);
 
+      // Set token span for lossless source reconstruction (else if blocks)
+      if (tokenStream != null
+          && elseStmtChainContext.start != null
+          && elseStmtChainContext.stop != null) {
+        elseblock
+            .tokenStream(tokenStream)
+            .tokenSpan(
+                elseStmtChainContext.start.getTokenIndex(),
+                elseStmtChainContext.stop.getTokenIndex());
+      }
+
       String inverseLabel = elseStmtChainContext.inverseToken.getText();
       if (inverseLabel.startsWith(startDelim)) {
         inverseLabel = inverseLabel.substring(startDelim.length());
@@ -314,6 +325,12 @@ public Template visitBlock(final BlockContext ctx) {
       paramStack.removeLast();
     }
     level -= 1;
+
+    // Set token span for lossless source reconstruction
+    if (tokenStream != null && ctx.start != null && ctx.stop != null) {
+      block.tokenStream(tokenStream).tokenSpan(ctx.start.getTokenIndex(), ctx.stop.getTokenIndex());
+    }
+
     return block;
   }
 
@@ -354,6 +371,12 @@ public Template visitUnless(final UnlessContext ctx) {
     }
     hasTag(true);
     level -= 1;
+
+    // Set token span for lossless source reconstruction
+    if (tokenStream != null && ctx.start != null && ctx.stop != null) {
+      block.tokenStream(tokenStream).tokenSpan(ctx.start.getTokenIndex(), ctx.stop.getTokenIndex());
+    }
+
     return block;
   }
 
@@ -718,6 +741,16 @@ public Template visitPartial(final PartialContext ctx) {
             .filename(source.filename())
             .position(info.token.getLine(), info.token.getCharPositionInLine());
 
+    // Set token span for lossless source reconstruction
+    if (tokenStream != null
+        && partial instanceof BaseTemplate
+        && ctx.start != null
+        && ctx.stop != null) {
+      ((BaseTemplate) partial)
+          .tokenStream(tokenStream)
+          .tokenSpan(ctx.start.getTokenIndex(), ctx.stop.getTokenIndex());
+    }
+
     return partial;
   }
 
@@ -748,6 +781,16 @@ public Object visitPartialBlock(final PartialBlockContext ctx) {
             .filename(source.filename())
             .position(info.token.getLine(), info.token.getCharPositionInLine());
 
+    // Set token span for lossless source reconstruction
+    if (tokenStream != null
+        && partial instanceof BaseTemplate
+        && ctx.start != null
+        && ctx.stop != null) {
+      ((BaseTemplate) partial)
+          .tokenStream(tokenStream)
+          .tokenSpan(ctx.start.getTokenIndex(), ctx.stop.getTokenIndex());
+    }
+
     return partial;
   }
 
diff --git a/handlebars/src/test/java/com/github/jknack/handlebars/SourceTextTest.java b/handlebars/src/test/java/com/github/jknack/handlebars/SourceTextTest.java
new file mode 100644
index 000000000..7d967564b
--- /dev/null
+++ b/handlebars/src/test/java/com/github/jknack/handlebars/SourceTextTest.java
@@ -0,0 +1,119 @@
+/*
+ * Handlebars.java: https://github.com/jknack/handlebars.java
+ * Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0
+ * Copyright (c) 2012 Edgar Espina
+ */
+package com.github.jknack.handlebars;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.io.IOException;
+
+import org.junit.jupiter.api.Test;
+
+/** Unit test for {@link Template#getSourceText()} */
+public class SourceTextTest extends AbstractTest {
+
+  @Test
+  public void testGetSourceTextPreservesWhitespace() throws IOException {
+    assertEquals("{{foo}}", compile("{{foo}}").getSourceText());
+    assertEquals("{{ foo }}", compile("{{ foo }}").getSourceText());
+    assertEquals("{{  foo  }}", compile("{{  foo  }}").getSourceText());
+
+    // text() still returns normalized form (backward compatibility)
+    assertEquals("{{foo}}", compile("{{foo}}").text());
+    assertEquals("{{foo}}", compile("{{ foo }}").text());
+    assertEquals("{{foo}}", compile("{{  foo  }}").text());
+  }
+
+  @Test
+  public void testGetSourceTextVarAmp() throws IOException {
+    assertEquals("{{&var}}", compile("{{&var}}").getSourceText());
+    assertEquals("{{& var }}", compile("{{& var }}").getSourceText());
+    assertEquals("{{&  var  }}", compile("{{&  var  }}").getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextVar3() throws IOException {
+    assertEquals("{{{var}}}", compile("{{{var}}}").getSourceText());
+    assertEquals("{{{ var }}}", compile("{{{ var }}}").getSourceText());
+    assertEquals("{{{  var  }}}", compile("{{{  var  }}}").getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextSection() throws IOException {
+    assertEquals(
+        "{{#section}}content{{/section}}",
+        compile("{{#section}}content{{/section}}").getSourceText());
+    assertEquals(
+        "{{# section }}content{{/ section }}",
+        compile("{{# section }}content{{/ section }}").getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextInvertedSection() throws IOException {
+    assertEquals(
+        "{{^section}}content{{/section}}",
+        compile("{{^section}}content{{/section}}").getSourceText());
+    assertEquals(
+        "{{^ section }}content{{/ section }}",
+        compile("{{^ section }}content{{/ section }}").getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextPartial() throws IOException {
+    assertEquals("{{>user}}", compile("{{>user}}", $(), $("user", "{{user}}")).getSourceText());
+    assertEquals("{{> user }}", compile("{{> user }}", $(), $("user", "{{user}}")).getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextPartialWithContext() throws IOException {
+    assertEquals(
+        "{{>user context}}",
+        compile("{{>user context}}", $(), $("user", "{{user}}")).getSourceText());
+    assertEquals(
+        "{{> user context }}",
+        compile("{{> user context }}", $(), $("user", "{{user}}")).getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextHelper() throws IOException {
+    assertEquals(
+        "{{with context arg0 hash=hash0}}",
+        compile("{{with context arg0 hash=hash0}}").getSourceText());
+    assertEquals(
+        "{{ with context arg0 hash=hash0 }}",
+        compile("{{ with context arg0 hash=hash0 }}").getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextBlockHelper() throws IOException {
+    assertEquals(
+        "{{#with context}}content{{/with}}",
+        compile("{{#with context}}content{{/with}}").getSourceText());
+    assertEquals(
+        "{{# with context }}content{{/ with }}",
+        compile("{{# with context }}content{{/ with }}").getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextPreservesAllWhitespaceTypes() throws IOException {
+    // Template with tabs
+    String source1 = "{{\tfoo\t}}";
+    assertEquals(source1, compile(source1).getSourceText());
+
+    // Template with multiple spaces
+    String source2 = "{{ foo }}  {{  bar  }}";
+    assertEquals(source2, compile(source2).getSourceText());
+
+    // Template with mixed whitespace
+    String source3 = "{{  \tfoo\t  }}";
+    assertEquals(source3, compile(source3).getSourceText());
+  }
+
+  @Test
+  public void testGetSourceTextWithTextContent() throws IOException {
+    String source = "Hello {{ name }}, welcome!";
+    assertEquals(source, compile(source).getSourceText());
+  }
+}
diff --git a/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java b/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
index 7ef7ecfe2..a13b4fbd0 100644
--- a/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
+++ b/handlebars/src/test/java/com/github/jknack/handlebars/WhitespaceChannelTest.java
@@ -11,15 +11,11 @@
 
 import org.junit.jupiter.api.Test;
 
-/** Tests for whitespace retention */
 public class WhitespaceChannelTest {
 
   /**
-   * Test that whitespace INSIDE tags does NOT affect rendering (backward compatibility).
-   *
-   * <p>This verifies that the grammar change to {@code channel(1)} maintains 100% backward
-   * compatibility - whitespace inside tags is preserved in the token stream but ignored during
-   * rendering.
+   * Test that whitespace INSIDE tags does NOT affect rendering. The whitespace inside tags is
+   * preserved in the token stream but ignored during rendering.
    */
   @Test
   public void testRenderingIgnoresWhitespaceInsideTags() throws IOException {
@@ -49,39 +45,7 @@ public String getFoo() {
     assertEquals(template1, template4, "Whitespace inside tags should not affect rendering");
   }
 
-  /**
-   * Test that whitespace OUTSIDE tags (between elements) IS preserved in rendering.
-   *
-   * <p>This is handled by TEXT tokens, not WS tokens, and should work correctly.
-   */
-  @Test
-  public void testWhitespaceOutsideTagsPreserved() throws IOException {
-    Handlebars handlebars = new Handlebars();
-
-    Context context =
-        Context.newBuilder(
-                new Object() {
-                  public String getFoo() {
-                    return "A";
-                  }
-
-                  public String getBar() {
-                    return "B";
-                  }
-                })
-            .build();
-
-    // Whitespace between tags should be preserved
-    assertEquals("A  B", handlebars.compileInline("{{foo}}  {{bar}}").apply(context));
-    assertEquals("A\n  B", handlebars.compileInline("{{foo}}\n  {{bar}}").apply(context));
-    assertEquals("A\t\tB", handlebars.compileInline("{{foo}}\t\t{{bar}}").apply(context));
-  }
-
-  /**
-   * Test that templates compile successfully with various whitespace patterns.
-   *
-   * <p>This verifies that the grammar change doesn't break any parsing.
-   */
+  /** Test that templates compile successfully with various whitespace patterns. */
   @Test
   public void testVariousWhitespacePatterns() throws IOException {
     Handlebars handlebars = new Handlebars();
@@ -166,40 +130,7 @@ public boolean getCondition() {
         "yes", handlebars.compileInline("{{#  if  condition  }}yes{{/  if  }}").apply(context));
   }
 
-  /** Test that newlines and various whitespace types are handled correctly. */
-  @Test
-  public void testVariousWhitespaceTypes() throws IOException {
-    Handlebars handlebars = new Handlebars();
-
-    Context context =
-        Context.newBuilder(
-                new Object() {
-                  public String getFoo() {
-                    return "A";
-                  }
-
-                  public String getBar() {
-                    return "B";
-                  }
-
-                  public String getBaz() {
-                    return "C";
-                  }
-                })
-            .build();
-
-    // Different whitespace types outside tags
-    assertEquals(
-        "A \t B\r\nC", handlebars.compileInline("{{foo}} \t {{bar}}\r\n{{baz}}").apply(context));
-  }
-
-  /**
-   * Test text() method returns normalized representation (current behavior).
-   *
-   * <p><b>Note:</b> text() currently reconstructs from AST, losing original whitespace inside tags.
-   * This is expected current behavior. Full lossless reconstruction would require additional
-   * infrastructure to store original source spans.
-   */
+  /** Test text() method returns normalized representation which remove whitespaces. */
   @Test
   public void testTextMethodNormalizesWhitespace() throws IOException {
     Handlebars handlebars = new Handlebars();
@@ -212,80 +143,4 @@ public void testTextMethodNormalizesWhitespace() throws IOException {
     assertEquals("{{foo}}", template1.text());
     assertEquals("{{foo}}", template2.text());
   }
-
-  /**
-   * Test getSourceText() method provides lossless source reconstruction.
-   *
-   * <p><b>Success!</b> The grammar successfully preserves whitespace tokens on channel 1, and the
-   * getSourceText() infrastructure is complete with token span tracking during template
-   * construction.
-   *
-   * <p>getSourceText() now returns the exact original source including all whitespace, while text()
-   * continues to return normalized form for backward compatibility.
-   */
-  @Test
-  public void testGetSourceTextPreservesWhitespace() throws IOException {
-    Handlebars handlebars = new Handlebars();
-
-    Template template1 = handlebars.compileInline("{{foo}}");
-    Template template2 = handlebars.compileInline("{{ foo }}");
-    Template template3 = handlebars.compileInline("{{  foo  }}");
-
-    // getSourceText() returns exact original source with whitespace preserved
-    assertEquals("{{foo}}", template1.getSourceText());
-    assertEquals("{{ foo }}", template2.getSourceText());
-    assertEquals("{{  foo  }}", template3.getSourceText());
-
-    // text() still returns normalized form (backward compatibility)
-    assertEquals("{{foo}}", template1.text());
-    assertEquals("{{foo}}", template2.text());
-    assertEquals("{{foo}}", template3.text());
-  }
-
-  /**
-   * Test getSourceText() with complex templates including text and multiple variables.
-   *
-   * <p><b>Note:</b> Block templates (like {{#if}}) are not yet fully supported for lossless
-   * reconstruction. This is a future enhancement.
-   */
-  @Test
-  public void testGetSourceTextComplexTemplates() throws IOException {
-    Handlebars handlebars = new Handlebars();
-
-    // Complex template with mixed whitespace and text
-    String source1 = "{{ foo }}  text  {{ bar }}";
-    Template template1 = handlebars.compileInline(source1);
-    assertEquals(source1, template1.getSourceText());
-
-    // Template with multiple variables
-    String source2 = "{{ name }} - {{ value }}";
-    Template template2 = handlebars.compileInline(source2);
-    assertEquals(source2, template2.getSourceText());
-
-    // Template with varying amounts of whitespace
-    String source3 = "{{foo}}{{bar}}{{ baz }}";
-    Template template3 = handlebars.compileInline(source3);
-    assertEquals(source3, template3.getSourceText());
-  }
-
-  /** Test getSourceText() preserves all whitespace types (spaces, tabs, newlines). */
-  @Test
-  public void testGetSourceTextPreservesAllWhitespaceTypes() throws IOException {
-    Handlebars handlebars = new Handlebars();
-
-    // Template with tabs
-    String source1 = "{{\tfoo\t}}";
-    Template template1 = handlebars.compileInline(source1);
-    assertEquals(source1, template1.getSourceText());
-
-    // Template with newlines (though unusual inside tags)
-    String source2 = "{{ foo }}  {{  bar  }}";
-    Template template2 = handlebars.compileInline(source2);
-    assertEquals(source2, template2.getSourceText());
-
-    // Template with mixed whitespace
-    String source3 = "{{  \tfoo\t  }}";
-    Template template3 = handlebars.compileInline(source3);
-    assertEquals(source3, template3.getSourceText());
-  }
 }