Add deferred partial rendering with Declarative Partial Updates

Introduce an `after` modifier for the render tag using Google's
proposed Declarative Partial Updates format. Initial rendering emits
processing-instruction markers, queues isolated partial renders, and
flushes `<template for=...>` replacement patches from the context.

.github/workflows/liquid.yml

@@ -14,8 +14,21 @@ jobs:
           - { ruby: 3.0, allowed-failure: false } # minimum supported
           - { ruby: 3.2, allowed-failure: false }
           - { ruby: 3.3, allowed-failure: false }
+          - { ruby: 3.3, allowed-failure: false }
           - { ruby: 3.4, allowed-failure: false } # latest
+          - {
+              ruby: 3.4,
+              allowed-failure: false,
+              rubyopt: "--enable-frozen-string-literal",
+            }
+          - { ruby: 3.4, allowed-failure: false, rubyopt: "--yjit" }
           - { ruby: ruby-head, allowed-failure: false }
+          - {
+              ruby: ruby-head,
+              allowed-failure: false,
+              rubyopt: "--enable-frozen-string-literal",
+            }
+          - { ruby: ruby-head, allowed-failure: false, rubyopt: "--yjit" }
     name: Test Ruby ${{ matrix.entry.ruby }}
     steps:
       - uses: actions/checkout@v3
@@ -26,6 +39,8 @@ jobs:
           bundler: latest
       - run: bundle exec rake
         continue-on-error: ${{ matrix.entry.allowed-failure }}
+        env:
+          RUBYOPT: ${{ matrix.entry.rubyopt }}
 
   memory_profile:
     runs-on: ubuntu-latest

History.md

@@ -1,22 +1,34 @@
 # Liquid Change Log
 
-## 5.8.0 (unreleased)
+## 5.8.1 (unreleased)
+
+## 5.8.1
+
+* Fix `{% doc %}` tag to be visitable [Guilherme Carreiro]
+
+## 5.8.0
+
+* Introduce the new `{% doc %}` tag [Guilherme Carreiro]
+
+## 5.7.3
+
+* Raise Liquid::SyntaxError when parsing invalidly encoded strings [Chris AtLee]
 
 ## 5.7.2 2025-01-31
 
-* Fix array filters to not support nested properties
+* Fix array filters to not support nested properties [Guilherme Carreiro]
 
 ## 5.7.1 2025-01-24
 
-* Fix the `find` and `find_index`filters to return `nil` when filtering empty arrays
-* Fix the `has` filter to return `false` when filtering empty arrays
+* Fix the `find` and `find_index`filters to return `nil` when filtering empty arrays [Guilherme Carreiro]
+* Fix the `has` filter to return `false` when filtering empty arrays [Guilherme Carreiro]
 
 ## 5.7.0 2025-01-16
 
 ### Features
 
-* Add `find`, `find_index`, `has`, and `reject` filters to arrays
-* Compatibility with Ruby 3.4
+* Add `find`, `find_index`, `has`, and `reject` filters to arrays [Guilherme Carreiro]
+* Compatibility with Ruby 3.4 [Ian Ker-Seymer]
 
 ## 5.6.4 2025-01-14
 

lib/liquid/context.rb

@@ -64,6 +64,33 @@ module Liquid
       @warnings ||= []
     end
 
+    def after_render_jobs
+      @registers.static[:after_render_jobs] ||= []
+    end
+
+    def next_after_render_id
+      @registers.static[:after_render_sequence] ||= 0
+      @registers.static[:after_render_sequence] += 1
+      "liquid-after-#{@registers.static[:after_render_sequence]}"
+    end
+
+    def enqueue_after_render(job)
+      after_render_jobs << job
+    end
+
+    def render_after_tags_to_output_buffer(output)
+      while (job = after_render_jobs.shift)
+        output << %(<template for="#{job[:id]}">)
+        job[:renderer].call(output)
+        output << %(</template>)
+      end
+      output
+    end
+
+    def render_after_tags
+      render_after_tags_to_output_buffer(+'')
+    end
+
     def strainer
       @strainer ||= @environment.create_strainer(self, @filters)
     end

lib/liquid/lexer.rb

@@ -161,6 +161,12 @@ module Liquid
         end
         # rubocop:enable Metrics/BlockNesting
         output << EOS
+      rescue ::ArgumentError => e
+        if e.message == "invalid byte sequence in #{ss.string.encoding}"
+          raise SyntaxError, "Invalid byte sequence in #{ss.string.encoding}"
+        else
+          raise
+        end
       end
 
       def raise_syntax_error(start_pos, ss)

lib/liquid/locales/en.yml

@@ -2,12 +2,14 @@
   errors:
     syntax:
       tag_unexpected_args: "Syntax Error in '%{tag}' - Valid syntax: %{tag}"
+      block_tag_unexpected_args: "Syntax Error in '%{tag}' - Valid syntax: {% %{tag} %}{% end%{tag} %}"
       assign: "Syntax Error in 'assign' - Valid syntax: assign [var] = [source]"
       capture: "Syntax Error in 'capture' - Valid syntax: capture [var]"
       case: "Syntax Error in 'case' - Valid syntax: case [condition]"
       case_invalid_when: "Syntax Error in tag 'case' - Valid when condition: {% when [condition] [or condition2...] %}"
       case_invalid_else: "Syntax Error in tag 'case' - Valid else condition: {% else %} (no parameters) "
       cycle: "Syntax Error in 'cycle' - Valid syntax: cycle [name :] var [, var2, var3 ...]"
+      doc_invalid_nested: "Syntax Error in 'doc' - Nested doc tags are not allowed"
       for: "Syntax Error in 'for loop' - Valid syntax: for [item] in [collection]"
       for_invalid_in: "For loops require an 'in' clause"
       for_invalid_attribute: "Invalid attribute in for loop. Valid attributes are limit and offset"

lib/liquid/standardfilters.rb

@@ -3,7 +3,6 @@
 require 'cgi'
 require 'base64'
 require 'bigdecimal'
-
 module Liquid
   module StandardFilters
     MAX_I32 = (1 << 31) - 1
@@ -456,7 +455,7 @@ module Liquid
     #   Tests if any item in an array has a specific property value.
     # @liquid_description
     #   This requires you to provide both the property name and the associated value.
-    # @liquid_syntax array | some: string, string
+    # @liquid_syntax array | has: string, string
     # @liquid_return [boolean]
     def has(input, property, target_value = nil)
       filter_array(input, property, target_value, false) { |ary, &block| ary.any?(&block) }
@@ -712,7 +711,16 @@ module Liquid
       input.gsub(/\r?\n/, "<br />\n")
     end
 
-    # Reformat a date using Ruby's core Time#strftime( string ) -> string
+    # @liquid_public_docs
+    # @liquid_type filter
+    # @liquid_category date
+    # @liquid_summary
+    #   Formats a date according to a specified format string.
+    # @liquid_description
+    #   This filter formats a date using various format specifiers. If the format string is empty,
+    #   the original input is returned. If the input cannot be converted to a date, the original input is returned.
+    #
+    #   The following format specifiers can be used:
     #
     #   %a - The abbreviated weekday name (``Sun'')
     #   %A - The  full  weekday  name (``Sunday'')
@@ -741,8 +749,8 @@ module Liquid
     #   %Y - Year with century
     #   %Z - Time zone name
     #   %% - Literal ``%'' character
-    #
-    #   See also: http://www.ruby-doc.org/core/Time.html#method-i-strftime
+    # @liquid_syntax date | date: string
+    # @liquid_return [string]
     def date(input, format)
       str_format = Utils.to_s(format)
       return input if str_format.empty?
@@ -989,7 +997,7 @@ module Liquid
     end
 
     def raise_property_error(property)
-      raise Liquid::ArgumentError, "cannot select the property '#{property}'"
+      raise Liquid::ArgumentError, "cannot select the property '#{Utils.to_s(property)}'"
     end
 
     def apply_operation(input, operand, operation)
@@ -1061,7 +1069,10 @@ module Liquid
       end
 
       def uniq(&block)
-        to_a.uniq(&block)
+        to_a.uniq do |item|
+          item = Utils.to_liquid_value(item)
+          block ? yield(item) : item
+        end
       end
 
       def compact

lib/liquid/tags.rb

@@ -19,6 +19,7 @@ require_relative "tags/comment"
 require_relative "tags/raw"
 require_relative "tags/render"
 require_relative "tags/cycle"
+require_relative "tags/doc"
 
 module Liquid
   module Tags
@@ -42,6 +43,7 @@ module Liquid
       'if' => If,
       'echo' => Echo,
       'tablerow' => TableRow,
+      'doc' => Doc,
     }.freeze
   end
 end

lib/liquid/tags/decrement.rb

@@ -10,7 +10,7 @@ module Liquid
   # @liquid_description
   #   Variables that are declared with `decrement` are unique to the [layout](/themes/architecture/layouts), [template](/themes/architecture/templates),
   #   or [section](/themes/architecture/sections) file that they're created in. However, the variable is shared across
-  #   [snippets](/themes/architecture#snippets) included in the file.
+  #   [snippets](/themes/architecture/snippets) included in the file.
   #
   #   Similarly, variables that are created with `decrement` are independent from those created with [`assign`](/docs/api/liquid/tags/assign)
   #   and [`capture`](/docs/api/liquid/tags/capture). However, `decrement` and [`increment`](/docs/api/liquid/tags/increment) share

lib/liquid/tags/doc.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Liquid
+  # @liquid_public_docs
+  # @liquid_type tag
+  # @liquid_category syntax
+  # @liquid_name doc
+  # @liquid_summary
+  #   Documents template elements with annotations.
+  # @liquid_description
+  #   The `doc` tag allows developers to include documentation within Liquid
+  #   templates. Any content inside `doc` tags is not rendered or outputted.
+  #   Liquid code inside will be parsed but not executed. This facilitates
+  #   tooling support for features like code completion, linting, and inline
+  #   documentation.
+  #
+  #   For detailed documentation syntax and examples, see the
+  #   [`LiquidDoc` reference](/docs/storefronts/themes/tools/liquid-doc).
+  #
+  # @liquid_syntax
+  #   {% doc %}
+  #     Renders a message.
+  #
+  #     @param {string} foo - A string value.
+  #     @param {string} [bar] - An optional string value.
+  #
+  #     @example
+  #     {% render 'message', foo: 'Hello', bar: 'World' %}
+  #   {% enddoc %}
+  class Doc < Block
+    NO_UNEXPECTED_ARGS = /\A\s*\z/
+
+    def initialize(tag_name, markup, parse_context)
+      super
+      ensure_valid_markup(tag_name, markup, parse_context)
+    end
+
+    def parse(tokens)
+      while (token = tokens.shift)
+        tag_name = token =~ BlockBody::FullTokenPossiblyInvalid && Regexp.last_match(2)
+
+        raise_nested_doc_error if tag_name == @tag_name
+
+        if tag_name == block_delimiter
+          parse_context.trim_whitespace = (token[-3] == WhitespaceControl)
+          return
+        end
+      end
+
+      raise_tag_never_closed(block_name)
+    end
+
+    def render_to_output_buffer(_context, output)
+      output
+    end
+
+    def blank?
+      true
+    end
+
+    def nodelist
+      []
+    end
+
+    private
+
+    def ensure_valid_markup(tag_name, markup, parse_context)
+      unless NO_UNEXPECTED_ARGS.match?(markup)
+        raise SyntaxError, parse_context.locale.t("errors.syntax.block_tag_unexpected_args", tag: tag_name)
+      end
+    end
+
+    def raise_nested_doc_error
+      raise SyntaxError, parse_context.locale.t("errors.syntax.doc_invalid_nested")
+    end
+  end
+end

lib/liquid/tags/include.rb

@@ -6,7 +6,7 @@ module Liquid
   # @liquid_category theme
   # @liquid_name include
   # @liquid_summary
-  #   Renders a [snippet](/themes/architecture#snippets).
+  #   Renders a [snippet](/themes/architecture/snippets).
   # @liquid_description
   #   Inside the snippet, you can access and alter variables that are [created](/docs/api/liquid/tags/variable-tags) outside of the
   #   snippet.

lib/liquid/tags/increment.rb

@@ -10,7 +10,7 @@ module Liquid
   # @liquid_description
   #   Variables that are declared with `increment` are unique to the [layout](/themes/architecture/layouts), [template](/themes/architecture/templates),
   #   or [section](/themes/architecture/sections) file that they're created in. However, the variable is shared across
-  #   [snippets](/themes/architecture#snippets) included in the file.
+  #   [snippets](/themes/architecture/snippets) included in the file.
   #
   #   Similarly, variables that are created with `increment` are independent from those created with [`assign`](/docs/api/liquid/tags/assign)
   #   and [`capture`](/docs/api/liquid/tags/capture). However, `increment` and [`decrement`](/docs/api/liquid/tags/decrement) share

lib/liquid/tags/render.rb

@@ -6,7 +6,7 @@ module Liquid
   # @liquid_category theme
   # @liquid_name render
   # @liquid_summary
-  #   Renders a [snippet](/themes/architecture#snippets) or [app block](/themes/architecture/sections/section-schema#render-app-blocks).
+  #   Renders a [snippet](/themes/architecture/snippets) or [app block](/themes/architecture/sections/section-schema#render-app-blocks).
   # @liquid_description
   #   Inside snippets and app blocks, you can't directly access variables that are [created](/docs/api/liquid/tags/variable-tags) outside
   #   of the snippet or app block. However, you can [specify variables as parameters](/docs/api/liquid/tags/render#render-passing-variables-to-a-snippet)
@@ -27,7 +27,11 @@ module Liquid
   # @liquid_syntax_keyword filename The name of the snippet to render, without the `.liquid` extension.
   class Render < Tag
     FOR = 'for'
-    SYNTAX = /(#{QuotedString}+)(\s+(with|#{FOR})\s+(#{QuotedFragment}+))?(\s+(?:as)\s+(#{VariableSegment}+))?/o
+    AFTER = 'after'
+    AFTER_MARKUP = /\s+#{AFTER}(?=\s|,|\z)/o
+    WITH_OR_FOR_MARKUP = /\s+(with|#{FOR})\s+(#{QuotedFragment}+)/o
+    ALIAS_MARKUP = /\s+(?:as)\s+(#{VariableSegment}+)/o
+    SYNTAX = /(#{QuotedString}+)(#{AFTER_MARKUP})?(#{WITH_OR_FOR_MARKUP})?(#{ALIAS_MARKUP})?/o
 
     disable_tags "include"
 
@@ -39,10 +43,11 @@ module Liquid
       raise SyntaxError, options[:locale].t("errors.syntax.render") unless markup =~ SYNTAX
 
       template_name = Regexp.last_match(1)
-      with_or_for = Regexp.last_match(3)
-      variable_name = Regexp.last_match(4)
+      @after = !!Regexp.last_match(2)
+      with_or_for = Regexp.last_match(4)
+      variable_name = Regexp.last_match(5)
 
-      @alias_name = Regexp.last_match(6)
+      @alias_name = Regexp.last_match(7)
       @variable_name_expr = variable_name ? parse_expression(variable_name) : nil
       @template_name_expr = parse_expression(template_name)
       @is_for_loop = (with_or_for == FOR)
@@ -61,6 +66,10 @@ module Liquid
       render_tag(context, output)
     end
 
+    def after?
+      @after
+    end
+
     def render_tag(context, output)
       # The expression should be a String literal, which parses to a String object
       template_name = @template_name_expr
@@ -74,26 +83,43 @@ module Liquid
 
       context_variable_name = @alias_name || template_name.split('/').last
 
-      render_partial_func = ->(var, forloop) {
+      evaluated_attributes = @attributes.transform_values { |value| context.evaluate(value) }
+
+      render_partial_func = ->(var, forloop, render_output) {
         inner_context               = context.new_isolated_subcontext
         inner_context.template_name = partial.name
         inner_context.partial       = true
         inner_context['forloop']    = forloop if forloop
 
-        @attributes.each do |key, value|
-          inner_context[key] = context.evaluate(value)
+        evaluated_attributes.each do |key, value|
+          inner_context[key] = value
         end
         inner_context[context_variable_name] = var unless var.nil?
-        partial.render_to_output_buffer(inner_context, output)
+        partial.render_to_output_buffer(inner_context, render_output)
         forloop&.send(:increment!)
       }
 
       variable = @variable_name_expr ? context.evaluate(@variable_name_expr) : nil
-      if @is_for_loop && variable.respond_to?(:each) && variable.respond_to?(:count)
+
+      if @after
+        id = context.next_after_render_id
+        context.enqueue_after_render(
+          id: id,
+          renderer: ->(after_output) {
+            if @is_for_loop && variable.respond_to?(:each) && variable.respond_to?(:count)
+              forloop = Liquid::ForloopDrop.new(template_name, variable.count, nil)
+              variable.each { |var| render_partial_func.call(var, forloop, after_output) }
+            else
+              render_partial_func.call(variable, nil, after_output)
+            end
+          }
+        )
+        output << %(<?marker name="#{id}">)
+      elsif @is_for_loop && variable.respond_to?(:each) && variable.respond_to?(:count)
         forloop = Liquid::ForloopDrop.new(template_name, variable.count, nil)
-        variable.each { |var| render_partial_func.call(var, forloop) }
+        variable.each { |var| render_partial_func.call(var, forloop, output) }
       else
-        render_partial_func.call(variable, nil)
+        render_partial_func.call(variable, nil, output)
       end
 
       output

lib/liquid/tokenizer.rb

@@ -103,6 +103,12 @@ module Liquid
 
       pos = @ss.pos -= 2
       @source.byteslice(start, pos - start)
+    rescue ::ArgumentError => e
+      if e.message == "invalid byte sequence in #{@ss.string.encoding}"
+        raise SyntaxError, "Invalid byte sequence in #{@ss.string.encoding}"
+      else
+        raise
+      end
     end
 
     def next_variable_token

lib/liquid/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Liquid
-  VERSION = "5.7.2"
+  VERSION = "5.8.6"
 end

proposals/render-after.md

@@ -0,0 +1,208 @@
+# Proposal: Deferred `render` with `after`
+
+## Summary
+
+Add an optional `after` modifier to Liquid's `{% render %}` tag:
+
+```liquid
+{% render 'product-card' after, product: product %}
+```
+
+When `after` is present, Liquid does not render the partial inline. Instead, it emits a stable HTML placeholder marker into the output and records enough information on the current `Liquid::Context` to render the partial later. A new context API then renders all deferred partials, ideally as a stream of out-of-order HTML replacement patches.
+
+This is inspired by Chrome's Declarative Partial Updates proposal: https://developer.chrome.com/blog/declarative-partial-updates. The browser-side idea is to let HTML declare patch targets and stream their replacement content later, enabling the initial shell to be sent quickly while slower islands arrive when ready.
+
+For Liquid, the equivalent is server-side syntax for declaring that a snippet can be delayed without changing template structure.
+
+## Motivation
+
+Liquid templates often have a mix of cheap layout work and expensive isolated snippets. Today, an expensive snippet blocks all subsequent output because `{% render %}` is synchronous and inline.
+
+`render after` would allow templates to produce the main document quickly, reserve exact DOM locations for deferred snippets, and render those snippets later using the same Liquid render semantics.
+
+Example use cases:
+
+- Product recommendations below the fold.
+- Expensive merchandising or personalization blocks.
+- Analytics or SEO metadata fragments that can be patched into known locations.
+- App blocks where the outer page shell should not wait on the block.
+
+## Goals
+
+- Add a small, Liquid-native API for deferring isolated snippet rendering.
+- Preserve existing `{% render %}` isolation semantics.
+- Emit processing-instruction placeholders that can be targeted by a later replacement patch.
+- Store deferred render work in `Liquid::Context`.
+- Add a context method to flush/enumerate/render deferred work.
+- Keep the first prototype simple and non-streaming, while shaping the API so true streaming can be added later.
+
+## Non-goals
+
+- Implement browser support for Declarative Partial Updates.
+- Require JavaScript for the Liquid-side primitive.
+- Make arbitrary tags asynchronous.
+- Allow deferred snippets to mutate the parent scope after the placeholder is emitted.
+- Solve scheduling, prioritization, cancellation, or parallel execution in the first prototype.
+
+## Syntax
+
+The proposed syntax is:
+
+```liquid
+{% render 'snippet' after %}
+{% render 'snippet' after, product: product %}
+{% render 'snippet' after with product as item %}
+{% render 'snippet' after for products as product %}
+```
+
+`after` is a render modifier with no value. It is intentionally boolean and reserved in this position.
+
+The prototype supports bare `after` immediately after the rendered template name, because it reads like a render modifier rather than data passed into the snippet. `after: value` remains a normal named argument passed to the snippet.
+
+## Output shape
+
+When a deferred render is encountered, Liquid emits a Chrome-style processing-instruction placeholder marker with a unique id:
+
+```html
+<?marker name="liquid-after-1">
+```
+
+Later, flushing the deferred renders produces replacement patches. The target shape should be compatible with the direction of Declarative Partial Updates. For example:
+
+```html
+<template for="liquid-after-1">
+  ...rendered snippet HTML...
+</template>
+```
+
+The exact patch attribute names should track the platform proposal as it evolves. Until browser APIs stabilize, Liquid can expose a server-side patch format behind a small formatter object.
+
+For the prototype, the replacement payload is a concatenated HTML patch string:
+
+```ruby
+context.render_after_tags
+# => "<template for=...>...</template>"
+```
+
+## Semantics
+
+### Evaluation timing
+
+When `{% render 'snippet' after ... %}` is encountered:
+
+1. Liquid evaluates the snippet name expression.
+2. Liquid evaluates the `with` / `for` expression, if present.
+3. Liquid evaluates all named render arguments.
+4. Liquid records a deferred render job containing the evaluated values and render metadata.
+5. Liquid emits a placeholder marker.
+
+This means deferred renders capture values at enqueue time, not flush time. That avoids surprising behavior when variables change later in the template.
+
+### Isolation
+
+Deferred render jobs should use the same isolation semantics as normal `{% render %}`:
+
+- The snippet receives only explicitly-passed variables plus globals/environments available to render today.
+- Variables assigned inside the snippet do not leak into the parent template.
+- The `include` tag remains disabled inside rendered snippets.
+
+### Ordering
+
+The queue is FIFO by default. Placeholder ids are monotonically increasing per context render:
+
+```html
+<?marker name="liquid-after-1">
+<?marker name="liquid-after-2">
+```
+
+The streaming API may later render jobs as they become ready, but the prototype can preserve source order.
+
+### Error handling
+
+Deferred renders should use Liquid's existing error handling through `Context#handle_error` and `exception_renderer`.
+
+Open question: if an error occurs while flushing deferred renders after the main template was already sent, should the replacement patch contain the rendered error string, an empty patch, or an out-of-band error? The prototype should match inline render behavior and place the rendered error into the patch body.
+
+## Proposed API
+
+Add queue APIs to `Liquid::Context`:
+
+```ruby
+context.enqueue_after_render(job) # internal
+context.after_render_jobs         # inspection/testing
+context.render_after_tags         # prototype: returns a string of patches
+context.render_after_tags_to_output_buffer(output) # streaming-ready shape
+```
+
+Possible streaming-oriented API:
+
+```ruby
+context.each_after_render_patch do |patch|
+  response.write(patch)
+end
+```
+
+or:
+
+```ruby
+context.render_after_tags_to_output_buffer(response_stream)
+```
+
+The first implementation may buffer each snippet internally. The API should still write to an output object so callers can later stream each completed patch without changing template code.
+
+## Example
+
+Template:
+
+```liquid
+<h1>{{ product.title }}</h1>
+
+{% render 'price', product: product %}
+
+<section>
+  {% render 'recommendations' after, product: product %}
+</section>
+```
+
+Initial output:
+
+```html
+<h1>Snowboard</h1>
+
+<span>$699.00</span>
+
+<section>
+  <?marker name="liquid-after-1">
+</section>
+```
+
+Deferred patch output:
+
+```html
+<template for="liquid-after-1">
+  <ul class="recommendations">...</ul>
+</template>
+```
+
+A Rack-like integration could do:
+
+```ruby
+context = Liquid::Context.build(...)
+body = template.render!(context)
+response.write(body)
+context.render_after_tags_to_output_buffer(response)
+```
+
+The prototype can buffer `body` first. A production integration would stream `body` immediately, then stream each deferred patch as soon as it completes.
+
+## Compatibility
+
+Existing templates are unaffected unless they use bare `after` immediately after the rendered template name.
+
+Because bare `after` becomes reserved syntax for the render tag in that position, this could conflict with unusual templates that currently rely on that token being ignored. Snippets currently receiving an `after:` keyword argument continue to work:
+
+```liquid
+{% render 'divider', after: 'label' %}
+```
+
+This proposal only reserves bare `after`; `after: value` continues to be passed as a normal snippet attribute. That minimizes compatibility risk.

test/integration/standard_filter_test.rb

@@ -560,12 +560,23 @@ class StandardFiltersTest < Minitest::Test
     end
   end
 
-  def test_map_returns_empty_with_no_property
+  def test_map_with_value_property
+    array = [
+      { "handle" => "alpha", "value" => "A" },
+      { "handle" => "beta", "value" => "B" },
+      { "handle" => "gamma", "value" => "C" }
+    ]
+
+    assert_template_result("A B C", "{{ array | map: 'value' | join: ' ' }}", { "array" => array })
+  end
+
+  def test_map_returns_input_with_no_property
     foo = [
       [1],
       [2],
       [3],
     ]
+
     assert_raises(Liquid::ArgumentError) do
       @filters.map(foo, nil)
     end
@@ -1033,6 +1044,23 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result(expected_output, template, { "array" => array })
   end
 
+  def test_where_with_empty_string_is_a_no_op
+    environment = { "array" => ["alpha", "beta", "gamma"] }
+    expected_output = "alpha beta gamma"
+    template = "{{ array | where: '' | join: ' ' }}"
+
+    assert_template_result(expected_output, template, environment)
+  end
+
+  def test_where_with_nil_is_a_no_op
+    environment = { "array" => ["alpha", "beta", "gamma"] }
+    template = "{{ array | where: nil | join: ' ' }}"
+
+    assert_raises(Liquid::ArgumentError) do
+      assert_template_result("alpha beta gamma", template, environment)
+    end
+  end
+
   def test_where_with_value
     array = [
       { "handle" => "alpha", "ok" => true },
@@ -1268,6 +1296,33 @@ class StandardFiltersTest < Minitest::Test
     assert_template_result("0", "{{ input | sum: 'subtotal' }}", { "input" => input })
   end
 
+  def test_sum_with_non_string_property
+    input = [{ true => 1 }, { 1.0 => 0.2, 1 => -0.3 }, { 1..5 => 0.4 }]
+
+    assert_equal(1, @filters.sum(input, true))
+    assert_equal(0.2, @filters.sum(input, 1.0))
+    assert_equal(-0.3, @filters.sum(input, 1))
+    assert_equal(0.4, @filters.sum(input, (1..5)))
+    assert_equal(0, @filters.sum(input, nil))
+    assert_equal(0, @filters.sum(input, ""))
+  end
+
+  def test_uniq_with_to_liquid_value
+    input = [StringDrop.new("foo"), StringDrop.new("bar"), "foo"]
+    expected = [StringDrop.new("foo"), StringDrop.new("bar")]
+    result = @filters.uniq(input)
+
+    assert_equal(expected, result)
+  end
+
+  def test_uniq_with_to_liquid_value_pick_correct_classes
+    input = ["foo", StringDrop.new("foo"), StringDrop.new("bar")]
+    expected = [String, StringDrop]
+    result = @filters.uniq(input).map(&:class)
+
+    assert_equal(expected, result)
+  end
+
   private
 
   def with_timezone(tz)

test/integration/tags/render_tag_test.rb

@@ -46,6 +46,70 @@ class RenderTagTest < Minitest::Test
     )
   end
 
+  def test_render_after_defers_partial_until_context_flush
+    file_system = StubFileSystem.new('snippet' => 'deferred {{ value }}')
+    environment = Liquid::Environment.build(file_system: file_system)
+    template = Liquid::Template.parse('before {% render "snippet" after, value: 1 %} after', environment: environment)
+    registers = Liquid::Registers.new(file_system: file_system)
+    context = Liquid::Context.build(registers: registers, environment: environment)
+
+    assert_equal('before <?marker name="liquid-after-1"> after', template.render(context))
+    assert_equal('<template for="liquid-after-1">deferred 1</template>', context.render_after_tags)
+    assert_empty(context.after_render_jobs)
+  end
+
+  def test_render_after_evaluates_attributes_when_enqueued
+    file_system = StubFileSystem.new('snippet' => '{{ value }}')
+    environment = Liquid::Environment.build(file_system: file_system)
+    template = Liquid::Template.parse('{% assign value = 1 %}{% render "snippet" after, value: value %}{% assign value = 2 %}', environment: environment)
+    registers = Liquid::Registers.new(file_system: file_system)
+    context = Liquid::Context.build(registers: registers, environment: environment)
+
+    assert_equal('<?marker name="liquid-after-1">', template.render(context))
+    assert_equal('<template for="liquid-after-1">1</template>', context.render_after_tags)
+  end
+
+  def test_render_after_supports_with_and_as
+    file_system = StubFileSystem.new('snippet' => '{{ item }}')
+    environment = Liquid::Environment.build(file_system: file_system)
+    template = Liquid::Template.parse('{% render "snippet" after with value as item %}', environment: environment)
+    registers = Liquid::Registers.new(file_system: file_system)
+    context = Liquid::Context.build(static_environments: { 'value' => 'captured' }, registers: registers, environment: environment)
+
+    assert_equal('<?marker name="liquid-after-1">', template.render(context))
+    assert_equal('<template for="liquid-after-1">captured</template>', context.render_after_tags)
+  end
+
+  def test_render_after_supports_for_and_as
+    file_system = StubFileSystem.new('snippet' => '{{ forloop.index }}:{{ item }};')
+    environment = Liquid::Environment.build(file_system: file_system)
+    template = Liquid::Template.parse('{% render "snippet" after for values as item %}', environment: environment)
+    registers = Liquid::Registers.new(file_system: file_system)
+    context = Liquid::Context.build(static_environments: { 'values' => ['a', 'b'] }, registers: registers, environment: environment)
+
+    assert_equal('<?marker name="liquid-after-1">', template.render(context))
+    assert_equal('<template for="liquid-after-1">1:a;2:b;</template>', context.render_after_tags)
+  end
+
+  def test_render_after_preserves_fifo_order
+    file_system = StubFileSystem.new('snippet' => '{{ value }}')
+    environment = Liquid::Environment.build(file_system: file_system)
+    template = Liquid::Template.parse('{% render "snippet" after, value: 1 %}{% render "snippet" after, value: 2 %}', environment: environment)
+    registers = Liquid::Registers.new(file_system: file_system)
+    context = Liquid::Context.build(registers: registers, environment: environment)
+
+    assert_equal('<?marker name="liquid-after-1"><?marker name="liquid-after-2">', template.render(context))
+    assert_equal('<template for="liquid-after-1">1</template><template for="liquid-after-2">2</template>', context.render_after_tags)
+  end
+
+  def test_render_after_colon_remains_a_named_argument
+    assert_template_result(
+      'later',
+      '{% render "snippet", after: "later" %}',
+      partials: { 'snippet' => '{{ after }}' },
+    )
+  end
+
   def test_render_does_not_inherit_parent_scope_variables
     assert_template_result(
       '',

test/test_helper.rb

@@ -146,6 +146,35 @@ class BooleanDrop < Liquid::Drop
   end
 end
 
+class StringDrop < Liquid::Drop
+  include Comparable
+
+  def initialize(value)
+    super()
+    @value = value
+  end
+
+  def to_liquid_value
+    @value
+  end
+
+  def to_s
+    @value
+  end
+
+  def to_str
+    @value
+  end
+
+  def inspect
+    "#<StringDrop @value=#{@value.inspect}>"
+  end
+
+  def <=>(other)
+    to_liquid_value <=> Liquid::Utils.to_liquid_value(other)
+  end
+end
+
 class ErrorDrop < Liquid::Drop
   def standard_error
     raise Liquid::StandardError, 'standard error'

test/unit/block_unit_test.rb

@@ -47,12 +47,18 @@ class BlockUnitTest < Minitest::Test
     )
   end
 
-  def test_with_block
+  def test_comment_tag_with_block
     template = Liquid::Template.parse("  {% comment %} {% endcomment %} ")
     assert_equal([String, Comment, String], block_types(template.root.nodelist))
     assert_equal(3, template.root.nodelist.size)
   end
 
+  def test_doc_tag_with_block
+    template = Liquid::Template.parse("  {% doc %} {% enddoc %} ")
+    assert_equal([String, Doc, String], block_types(template.root.nodelist))
+    assert_equal(3, template.root.nodelist.size)
+  end
+
   private
 
   def block_types(nodelist)

test/unit/lexer_unit_test.rb

@@ -131,6 +131,16 @@ class LexerUnitTest < Minitest::Test
     assert_equal([[:id, "false"], [:number, "1"], [:end_of_string]], tokenize("false 1"))
   end
 
+  def test_error_with_invalid_utf8
+    error = assert_raises(SyntaxError) do
+      tokenize("\x00\xff")
+    end
+    assert_equal(
+      'Liquid syntax error: Invalid byte sequence in UTF-8',
+      error.message,
+    )
+  end
+
   private
 
   def tokenize(input)

test/unit/tags/doc_tag_unit_test.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class DocTagUnitTest < Minitest::Test
+  def test_doc_tag
+    template = <<~LIQUID.chomp
+      {% doc %}
+        Renders loading-spinner.
+
+        @param {string} foo - some foo
+        @param {string} [bar] - optional bar
+
+        @example
+        {% render 'loading-spinner', foo: 'foo' %}
+        {% render 'loading-spinner', foo: 'foo', bar: 'bar' %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_does_not_support_extra_arguments
+    error = assert_raises(Liquid::SyntaxError) do
+      template = <<~LIQUID.chomp
+        {% doc extra %}
+        {% enddoc %}
+      LIQUID
+
+      Liquid::Template.parse(template)
+    end
+
+    exp_error = "Liquid syntax error: Syntax Error in 'doc' - Valid syntax: {% doc %}{% enddoc %}"
+    act_error = error.message
+
+    assert_equal(exp_error, act_error)
+  end
+
+  def test_doc_tag_must_support_valid_tags
+    assert_match_syntax_error("Liquid syntax error (line 1): 'doc' tag was never closed", '{% doc %} foo')
+    assert_match_syntax_error("Liquid syntax error (line 1): Syntax Error in 'doc' - Valid syntax: {% doc %}{% enddoc %}", '{% doc } foo {% enddoc %}')
+    assert_match_syntax_error("Liquid syntax error (line 1): Syntax Error in 'doc' - Valid syntax: {% doc %}{% enddoc %}", '{% doc } foo %}{% enddoc %}')
+  end
+
+  def test_doc_tag_ignores_liquid_nodes
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% if true %}
+        {% if ... %}
+        {%- for ? -%}
+        {% while true %}
+        {%
+          unless if
+        %}
+        {% endcase %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_ignores_unclosed_liquid_tags
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% if true %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_does_not_allow_nested_docs
+    error = assert_raises(Liquid::SyntaxError) do
+      template = <<~LIQUID.chomp
+        {% doc %}
+          {% doc %}
+            {% doc %}
+        {% enddoc %}
+      LIQUID
+
+      Liquid::Template.parse(template)
+    end
+
+    exp_error = "Liquid syntax error: Syntax Error in 'doc' - Nested doc tags are not allowed"
+    act_error = error.message
+
+    assert_equal(exp_error, act_error)
+  end
+
+  def test_doc_tag_ignores_nested_raw_tags
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% raw %}
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_ignores_unclosed_assign
+    template = <<~LIQUID.chomp
+      {% doc %}
+        {% assign foo = "1"
+      {% enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_ignores_malformed_syntax
+    template = <<~LIQUID.chomp
+      {% doc %}
+      {% {{ {%- enddoc %}
+    LIQUID
+
+    assert_template_result('', template)
+  end
+
+  def test_doc_tag_preserves_error_line_numbers
+    template = Liquid::Template.parse(<<~LIQUID.chomp, line_numbers: true)
+      {% doc %}
+        {% if true %}
+      {% enddoc %}
+      {{ errors.standard_error }}
+    LIQUID
+
+    expected = <<~TEXT.chomp
+
+      Liquid error (line 4): standard error
+    TEXT
+
+    assert_equal(expected, template.render('errors' => ErrorDrop.new))
+  end
+
+  def test_doc_tag_whitespace_control
+    # Basic whitespace control
+    assert_template_result("Hello!", "      {%- doc -%}123{%- enddoc -%}Hello!")
+    assert_template_result("Hello!", "{%- doc -%}123{%- enddoc -%}     Hello!")
+    assert_template_result("Hello!", "      {%- doc -%}123{%- enddoc -%}     Hello!")
+    assert_template_result("Hello!", <<~LIQUID.chomp)
+      {%- doc %}Whitespace control!{% enddoc -%}
+      Hello!
+    LIQUID
+  end
+
+  def test_doc_tag_delimiter_handling
+    assert_template_result('', <<~LIQUID.chomp)
+      {% if true %}
+        {% doc %}
+          {% docEXTRA %}wut{% enddocEXTRA %}xyz
+        {% enddoc %}
+      {% endif %}
+    LIQUID
+
+    assert_template_result('', "{% doc %}123{% enddoc xyz %}")
+    assert_template_result('', "{% doc %}123{% enddoc\txyz %}")
+    assert_template_result('', "{% doc %}123{% enddoc\nxyz %}")
+    assert_template_result('', "{% doc %}123{% enddoc\n   xyz  enddoc %}")
+  end
+
+  def test_doc_tag_visitor
+    template_source = '{% doc %}{% enddoc %}'
+
+    assert_equal(
+      [Liquid::Doc],
+      visit(template_source),
+    )
+  end
+
+  private
+
+  def traversal(template)
+    ParseTreeVisitor
+      .for(Template.parse(template).root)
+      .add_callback_for(Liquid::Doc) do |tag|
+        tag_class = tag.class
+        tag_class
+      end
+  end
+
+  def visit(template)
+    traversal(template).visit.flatten.compact
+  end
+end

test/unit/template_unit_test.rb

@@ -35,4 +35,15 @@ class TemplateUnitTest < Minitest::Test
   def test_template_inheritance
     assert_equal("foo", TemplateSubclass.parse("foo").render)
   end
+
+  def test_invalid_utf8
+    input = "\xff\x00"
+    error = assert_raises(SyntaxError) do
+      Liquid::Tokenizer.new(source: input, string_scanner: StringScanner.new(input))
+    end
+    assert_equal(
+      'Liquid syntax error: Invalid byte sequence in UTF-8',
+      error.message,
+    )
+  end
 end