herb 0.11.1 → 0.11.2

data/lib/herb/engine/slots/dynamics_compiler.rb

@@ -71,7 +71,8 @@ module Herb
       # An item is keyed by the key its template declares, through `herb-key` or `id` or a
       # `<%# herb:key %>` directive, which is what makes it survive being reordered. `Visitor`
       # decides what that key is and this evaluates it, so an item arrives under the same key the
-      # marker around it carries. A collection that declares none falls back to position.
+      # marker around it carries. A collection that declares none falls back to position, counting
+      # from the first iteration, so a change re-renders every row from the first one that differs.
       #
       # ## A partial keeps its own values
       #
@@ -94,7 +95,7 @@ module Herb
       #
       # ## Blocks
       #
-      # A tag that takes a block, such as `<%= form_with do |f| %>`, owns an entry holding everything
+      # A tag that takes a block, such as `<%= form_with do |f| %>`, owns an entry holding the markup
       # the block rendered, because the helper wraps that output in markup of its own that only the
       # helper can produce. What the template wrote inside the block keeps its own indices alongside:
       #
@@ -105,6 +106,20 @@ module Herb
       # and the whole block. Slot 1 is inside slot 0, which the client already has to reason about
       # for conditionals and collections.
       #
+      # A partial inside a block is the exception to that fallback. It keeps its own values on its slot,
+      # and the block's entry is a String that cannot hold them, so the entry leaves the partial's
+      # markup out:
+      #
+      #     <%= form_with(model: @user) do |f| %><%= render "card" %><% end %>
+      #     #=> { 0 => "<form></form>", 1 => { template: "app/views/_card.html.erb", ... } }
+      #
+      # That entry cannot stand in for the block, so it must not be written over a block holding a
+      # partial. The client never writes a block's entry while the page marks slots inside that block.
+      # It reports the block as deferred instead, even when nothing in the block changed.
+      #
+      # A render that comes back as markup, because its template is not compiled for slots, is written
+      # into the entry as usual, and the entry stays whole.
+      #
       # A block yielding more than once is the exception, since one index cannot stand for the several
       # values its interior took. `each` and the other iterations are compiled as collections for that
       # reason, and a helper that yields repeatedly reports the last value its interior took.
@@ -117,6 +132,7 @@ module Herb
         ITEMS_BUFFER = "__herb_items" #: String
         KEY_BUFFER = "__herb_key" #: String
         OCCURRENCE_BUFFER = "__herb_occurrence" #: String
+        RENDERED_BUFFER = "__herb_rendered" #: String
 
         BRANCHING_NODES = [
           "AST_ERB_IF_NODE",
@@ -297,14 +313,15 @@ module Herb
 
             return super if erb_escaped?(opening)
 
-            should_escape = should_escape_output?(opening)
+            rendering = node.is_a?(Herb::AST::ERBRenderNode)
+            should_escape = !rendering && should_escape_output?(opening)
             index = claim(node)
 
             @tokens << [
               should_escape ? :expr_block_escaped : :expr_block,
               node.content.value.strip,
               current_context,
-              index
+              [index, rendering]
             ]
 
             @last_trim_consumed_newline = false
@@ -335,7 +352,9 @@ module Herb
 
                 @engine.send(:add_dynamic, value, context, index, escaped, nested: nested)
               when :expr_block, :expr_block_escaped
-                @engine.send(:add_dynamic_block, value, extra, type == :expr_block_escaped)
+                index, rendering = extra
+
+                @engine.send(:add_dynamic_block, value, index, type == :expr_block_escaped, rendering: rendering)
               when :expr_block_end
                 @engine.send(:add_expression_block_end, value, escaped: extra)
               end
@@ -461,7 +480,7 @@ module Herb
 
           #: (Integer) -> String?
           def item_key(index)
-            @slot_visitor.slots[index]&.key_expression
+            @slot_visitor.slots[index]&.item_key
           end
 
           #: (untyped, Symbol) -> void
@@ -541,6 +560,7 @@ module Herb
         #: (String, ?Hash[Symbol, untyped]) -> void
         def initialize(input, properties = {})
           @block_depth = 0
+          @nested_renders = [] #: Array[[Integer?]?]
           @scopes = [] #: Array[Integer]
           @withheld = {} #: Hash[Integer, bool]
           @input = input
@@ -599,6 +619,8 @@ module Herb
               return add_block_dynamic("(#{assignment(index, value)}).fetch(-1)")
             end
 
+            return add_block_render(index ? assignment(index, value) : value) if nested
+
             return add_block_dynamic(index ? assignment(index, value) : value)
           end
           return if index.nil?
@@ -611,19 +633,24 @@ module Herb
           @slot_visitor.slots[index]&.type == :boolean_attribute
         end
 
-        #: (String, Integer?, bool) -> void
-        def add_dynamic_block(code, index, escaped)
+        #: (String, Integer?, bool, ?rendering: bool) -> void
+        def add_dynamic_block(code, index, escaped, rendering: false)
           @_in_expression_block = true
           @_expression_block_open_paren = true
 
           opening = escaped ? "#{@escapefunc}((" : "("
+          nested_render = rendering && !@block_depth.zero?
 
           @src << if @block_depth.zero?
                     "; #{current_scope}[#{index}] = #{opening}#{code}"
+                  elsif nested_render
+                    "; #{RENDERED_BUFFER} = #{opening}#{code}"
                   else
                     "; #{@bufvar} << #{opening}#{code}"
                   end
 
+          @nested_renders.push(nested_render ? [index] : nil)
+
           open_block
         end
 
@@ -634,6 +661,14 @@ module Herb
           close_block
 
           super
+
+          nested_render = @nested_renders.pop
+
+          return unless nested_render
+
+          index = nested_render.first
+
+          add_block_render(index ? assignment(index, RENDERED_BUFFER) : RENDERED_BUFFER)
         end
 
         #: () -> String
@@ -738,6 +773,10 @@ module Herb
         #: (Integer) -> void
         def scope_open_collection(index)
           @src << "; #{ITEMS_BUFFER}#{index} = ::Hash.new;"
+
+          slot = @slot_visitor.slots[index]
+
+          @src << "; #{slot.position_variable} = -1;" if slot&.positional?
         end
 
         #: (Integer, ?String?) -> void
@@ -752,17 +791,12 @@ module Herb
         def scope_item_end(index)
           leave_scope(index)
 
-          return unless keyed?(index)
+          return unless @slot_visitor.slots[index]&.item_key
 
           @src << item_seeds(index)
           @src << "; #{ITEMS_BUFFER}#{index}[#{KEY_BUFFER}#{index}.to_s] = #{SCOPE_BUFFER}#{index};"
         end
 
-        #: (Integer) -> bool
-        def keyed?(index)
-          !@slot_visitor.slots[index]&.key_expression.nil?
-        end
-
         #: (Integer) -> String
         def item_seeds(index)
           names = @slot_visitor.seeded_item_states[index]
@@ -826,6 +860,11 @@ module Herb
           @slot_visitor.slots[index]&.interpolated? || false
         end
 
+        #: (String) -> void
+        def add_block_render(value)
+          add_block_dynamic("::Hash === (#{RENDERED_BUFFER} = (#{value})) ? \"\" : #{RENDERED_BUFFER}.to_s")
+        end
+
         #: (String) -> void
         def add_block_dynamic(value)
           @src << "; " << @bufvar << " << (" << value << ");"

data/lib/herb/engine/slots/subtree_compiler.rb

@@ -186,7 +186,7 @@ module Herb
 
           #: (*untyped) { () -> void } -> void
           def indexing(*arrays)
-            marked = arrays.select { |array| array.is_a?(Array) }
+            marked = arrays.grep(Array)
             marked.each { |array| @indexed[array] = true }
 
             yield

data/lib/herb/engine/slots/visitor.rb

@@ -66,6 +66,7 @@ module Herb
         COVERED = "@_herb_covered" #: String
         OCCURRENCES = "@_herb_region_occurrences" #: String
         OCCURRENCE = "_herb_occurrence" #: String
+        POSITION = "__herb_position" #: String
         NAME_ATTRIBUTE = "data-herb-name" #: String
         KEY_ATTRIBUTE = "herb-key" #: String
 
@@ -109,6 +110,15 @@ module Herb
 
           #: () -> bool
           def interpolated? = Types.interpolated?(type)
+
+          #: () -> bool
+          def positional? = type == :collection && key_expression.nil?
+
+          #: () -> String
+          def position_variable = "#{POSITION}#{index}"
+
+          #: () -> String?
+          def item_key = positional? ? "#{position_variable} += 1" : key_expression
         end
 
         #: (String) -> bool
@@ -1886,6 +1896,8 @@ module Herb
               wrap_items(child, slot_index, namespace)
               mark_branches(child, slot_index, namespace)
 
+              index += insert_position_counter(array, index, slot_index)
+
               if slot_index && slot_index != anchored
                 if @slots[slot_index].type == :keyed
                   park_keyed(slot_index, child, namespace)
@@ -2072,12 +2084,23 @@ module Herb
           bodies
         end
 
+        #: (Array[untyped], Integer, Integer?) -> Integer
+        def insert_position_counter(array, index, slot_index)
+          slot = slot_index ? @slots[slot_index] : nil
+
+          return 0 unless slot&.positional?
+
+          array.insert(index, erb_code_node("#{slot.position_variable} = -1"))
+
+          1
+        end
+
         #: (Herb::AST::Node, Integer?, ?Symbol) -> void
         def wrap_items(node, slot_index, namespace = :html)
           return unless slot_index
 
           slot = @slots[slot_index]
-          return unless slot.type == :collection && slot.key_expression
+          return unless slot.type == :collection
 
           BRANCH_BODY_PROPERTIES.each do |property|
             next unless node.respond_to?(property)
@@ -2090,13 +2113,18 @@ module Herb
 
             body.unshift(
               text_node(@markers.item_open_prefix(slot_index)),
-              erb_code_node("#{@bufvar} << ::Herb::Engine.raw((#{slot.key_expression}).to_s)"),
-              text_node(@markers.item_open_suffix)
+              erb_code_node("#{@bufvar} << ::Herb::Engine.raw((#{slot.item_key}).to_s)"),
+              text_node(@markers.item_open_suffix),
+              erb_code_node("begin")
             )
 
             body.insert(3, erb_code_node(%(#{COVERED}[#{covered_key(key).inspect}] = true))) if parked && client?
 
-            body.push(text_node(@markers.item_close(slot_index)))
+            body.push(
+              erb_code_node("ensure"),
+              text_node(@markers.item_close(slot_index)),
+              erb_code_node("end")
+            )
           end
         end
 

data/lib/herb/engine/visitors/instrumentation_visitor.rb

@@ -140,6 +140,8 @@ module Herb
 
         instrument(node)
 
+        return [node] if literal?(node)
+
         if framed?(node)
           [enter_node(node), node, leave_node(node)]
         elsif erb_outputs?(node)
@@ -158,6 +160,12 @@ module Herb
         replacement
       end
 
+      def literal?(node)
+        return false unless node.respond_to?(:tag_opening) && node.tag_opening
+
+        erb_escaped?(node.tag_opening.value)
+      end
+
       def framed?(node)
         return true if node.is_a?(Herb::AST::ERBRenderNode)
 
@@ -197,9 +205,9 @@ module Herb
         body = code(node)
         call = captured?(node) ? "output" : "at"
 
-        return erb_node(node, "<%=", "#{SESSION}.#{call}(#{position(node)}) {\n#{body}\n}") if spans_lines?(body)
+        return rewrapped(node, "#{SESSION}.#{call}(#{position(node)}) {\n#{body}\n}") if spans_lines?(body)
 
-        erb_node(node, "<%=", "#{SESSION}.#{call}(#{position(node)}) { #{body} }")
+        rewrapped(node, "#{SESSION}.#{call}(#{position(node)}) { #{body} }")
       end
 
       def captured?(node)
@@ -221,10 +229,10 @@ module Herb
         body = code(node)
 
         if spans_lines?(body)
-          return erb_node(node, "<%", "#{SESSION}.enter(#{position(node)}); begin\n#{body}\nensure; #{SESSION}.leave; end")
+          return rewrapped(node, "#{SESSION}.enter(#{position(node)}); begin\n#{body}\nensure; #{SESSION}.leave; end")
         end
 
-        erb_node(node, "<%", "#{SESSION}.enter(#{position(node)}); begin; #{body}; ensure; #{SESSION}.leave; end")
+        rewrapped(node, "#{SESSION}.enter(#{position(node)}); begin; #{body}; ensure; #{SESSION}.leave; end")
       end
 
       #: (String) -> bool
@@ -276,11 +284,15 @@ module Herb
         node.content&.value.to_s.strip
       end
 
-      def erb_node(node, opening, code)
+      def rewrapped(node, code)
+        erb_node(node, node.tag_opening.value, code, closing: node.tag_closing&.value || "%>")
+      end
+
+      def erb_node(node, opening, code, closing: "%>")
         Herb::AST::ERBContentNode.build(
           tag_opening: Herb::Token.from("TOKEN_ERB_START", opening),
           content: Herb::Token.from("TOKEN_ERB_CONTENT", " #{code} "),
-          tag_closing: Herb::Token.from("TOKEN_ERB_END", "%>"),
+          tag_closing: Herb::Token.from("TOKEN_ERB_END", closing),
           valid: true,
           location: node.location
         )

data/lib/herb/parser_options.rb

@@ -19,6 +19,7 @@ module Herb
     attr_reader :prism_nodes_deep #: bool
     attr_reader :prism_program #: bool
     attr_reader :render_nodes #: bool
+    attr_reader :ruby_version #: String?
     attr_reader :strict #: bool
     attr_reader :strict_locals #: bool
     attr_reader :timeout #: Numeric
@@ -45,8 +46,8 @@ module Herb
     DEFAULT_TRACK_WHITESPACE = false #: bool
     DEFAULT_TRANSFORM_CONDITIONALS = false #: bool
 
-    #: (?action_view_helpers: bool, ?analyze: bool, ?arena_stats: bool, ?dot_notation_tags: bool, ?erb_openers: Array[String], ?herb_directives: bool, ?html: bool, ?iteration_nodes: bool, ?max_errors: Integer?, ?prism_nodes: bool, ?prism_nodes_deep: bool, ?prism_program: bool, ?render_nodes: bool, ?strict: bool, ?strict_locals: bool, ?timeout: Numeric, ?track_locations: bool, ?track_whitespace: bool, ?transform_conditionals: bool) -> void
-    def initialize(action_view_helpers: DEFAULT_ACTION_VIEW_HELPERS, analyze: DEFAULT_ANALYZE, arena_stats: DEFAULT_CAPTURE_ARENA_STATS, dot_notation_tags: DEFAULT_DOT_NOTATION_TAGS, erb_openers: [], herb_directives: DEFAULT_HERB_DIRECTIVES, html: DEFAULT_HTML, iteration_nodes: DEFAULT_ITERATION_NODES, max_errors: DEFAULT_MAX_ERRORS, prism_nodes: DEFAULT_PRISM_NODES, prism_nodes_deep: DEFAULT_PRISM_NODES_DEEP, prism_program: DEFAULT_PRISM_PROGRAM, render_nodes: DEFAULT_RENDER_NODES, strict: DEFAULT_STRICT, strict_locals: DEFAULT_STRICT_LOCALS, timeout: DEFAULT_TIMEOUT, track_locations: DEFAULT_TRACK_LOCATIONS, track_whitespace: DEFAULT_TRACK_WHITESPACE, transform_conditionals: DEFAULT_TRANSFORM_CONDITIONALS)
+    #: (?action_view_helpers: bool, ?analyze: bool, ?arena_stats: bool, ?dot_notation_tags: bool, ?erb_openers: Array[String], ?herb_directives: bool, ?html: bool, ?iteration_nodes: bool, ?max_errors: Integer?, ?prism_nodes: bool, ?prism_nodes_deep: bool, ?prism_program: bool, ?render_nodes: bool, ?ruby_version: String?, ?strict: bool, ?strict_locals: bool, ?timeout: Numeric, ?track_locations: bool, ?track_whitespace: bool, ?transform_conditionals: bool) -> void
+    def initialize(action_view_helpers: DEFAULT_ACTION_VIEW_HELPERS, analyze: DEFAULT_ANALYZE, arena_stats: DEFAULT_CAPTURE_ARENA_STATS, dot_notation_tags: DEFAULT_DOT_NOTATION_TAGS, erb_openers: [], herb_directives: DEFAULT_HERB_DIRECTIVES, html: DEFAULT_HTML, iteration_nodes: DEFAULT_ITERATION_NODES, max_errors: DEFAULT_MAX_ERRORS, prism_nodes: DEFAULT_PRISM_NODES, prism_nodes_deep: DEFAULT_PRISM_NODES_DEEP, prism_program: DEFAULT_PRISM_PROGRAM, render_nodes: DEFAULT_RENDER_NODES, ruby_version: "4.0", strict: DEFAULT_STRICT, strict_locals: DEFAULT_STRICT_LOCALS, timeout: DEFAULT_TIMEOUT, track_locations: DEFAULT_TRACK_LOCATIONS, track_whitespace: DEFAULT_TRACK_WHITESPACE, transform_conditionals: DEFAULT_TRANSFORM_CONDITIONALS)
       @action_view_helpers = action_view_helpers
       @analyze = analyze
       @arena_stats = arena_stats
@@ -60,6 +61,7 @@ module Herb
       @prism_nodes_deep = prism_nodes_deep
       @prism_program = prism_program
       @render_nodes = render_nodes
+      @ruby_version = ruby_version
       @strict = strict
       @strict_locals = strict_locals
       @timeout = timeout
@@ -68,7 +70,7 @@ module Herb
       @transform_conditionals = transform_conditionals
     end
 
-    #: () -> Hash[Symbol, (bool | Numeric | Array[String] | nil)]
+    #: () -> Hash[Symbol, (bool | Numeric | String | Array[String] | nil)]
     def to_h
       {
         action_view_helpers: @action_view_helpers,
@@ -84,6 +86,7 @@ module Herb
         prism_nodes_deep: @prism_nodes_deep,
         prism_program: @prism_program,
         render_nodes: @render_nodes,
+        ruby_version: @ruby_version,
         strict: @strict,
         strict_locals: @strict_locals,
         timeout: @timeout,

data/lib/herb/project.rb

@@ -332,7 +332,7 @@ module Herb
       return unless issue_type[:key] == :invalid_ruby && file_content
 
       begin
-        engine = Herb::Engine.new(file_content, filename: file_path, escape: true, visitors: [])
+        engine = Herb::Engine.new(file_content, filename: file_path, escape: true, parser_options: engine_parser_options, visitors: [])
         puts ""
         puts "**Compiled Ruby:**"
         puts "```ruby"
@@ -345,6 +345,16 @@ module Herb
 
     private
 
+    #: () -> Hash[Symbol, untyped]
+    def parser_options
+      @parser_options ||= configuration.parser_options
+    end
+
+    #: () -> Hash[Symbol, untyped]
+    def engine_parser_options
+      @engine_parser_options ||= configuration.engine_option("parser_options", {}).transform_keys(&:to_sym).merge(parser_options)
+    end
+
     def process_file(file_path)
       isolate ? process_file_isolated(file_path) : process_file_direct(file_path)
     end
@@ -362,7 +372,7 @@ module Herb
       end
 
       Timeout.timeout(file_timeout) do
-        parse_result = Herb.parse(file_content)
+        parse_result = Herb.parse(file_content, **parser_options)
 
         if parse_result.failed?
           result[:file_content] = file_content
@@ -401,7 +411,7 @@ module Herb
           $stderr.reopen(stderr_file.path, "w")
 
           begin
-            parse_result = Herb.parse(file_content)
+            parse_result = Herb.parse(file_content, **parser_options)
             exit!(parse_result.failed? ? 2 : 0)
           rescue StandardError => e
             warn "Ruby exception: #{e.class}: #{e.message}"
@@ -457,7 +467,7 @@ module Herb
     end
 
     def classify_parse_errors(file_path, file_content)
-      default_result = Herb.parse(file_content)
+      default_result = Herb.parse(file_content, **parser_options)
 
       diagnostics = if default_result.respond_to?(:errors) && default_result.errors.any?
                       default_result.errors.map do |error|
@@ -470,8 +480,8 @@ module Herb
                       end
                     end
 
-      no_strict_result = Herb.parse(file_content, strict: false)
-      no_analyze_result = Herb.parse(file_content, analyze: false)
+      no_strict_result = Herb.parse(file_content, **parser_options, strict: false)
+      no_analyze_result = Herb.parse(file_content, **parser_options, analyze: false)
 
       if no_strict_result.success?
         { status: :strict_parse_error, diagnostics: diagnostics,
@@ -496,6 +506,7 @@ module Herb
         file_content,
         filename: file_path,
         escape: true,
+        parser_options: engine_parser_options,
         validate_ruby: validate_ruby,
         visitors: Herb::Engine::Validators.all
       )
@@ -514,7 +525,7 @@ module Herb
 
       # Retry without validators
       begin
-        Herb::Engine.new(file_content, filename: file_path, escape: true, visitors: [], validate_ruby: validate_ruby)
+        Herb::Engine.new(file_content, filename: file_path, escape: true, parser_options: engine_parser_options, visitors: [], validate_ruby: validate_ruby)
         error_name = e.is_a?(Herb::Engine::SecurityError) ? "SecurityError" : "ValidationError"
         return { status: :validation_error, file_content: file_content,
                  compilation_error: compilation_error,
@@ -526,7 +537,7 @@ module Herb
 
       # Retry without strict mode
       begin
-        Herb::Engine.new(file_content, filename: file_path, escape: true, strict: false, validate_ruby: validate_ruby)
+        Herb::Engine.new(file_content, filename: file_path, escape: true, parser_options: engine_parser_options, strict: false, validate_ruby: validate_ruby)
         return { status: :strict_compilation_failed, file_content: file_content,
                  compilation_error: compilation_error,
                  diagnostics: [{ name: "CompilationError", message: "#{e.message} (strict mode)" }],

data/lib/herb/version.rb

@@ -2,5 +2,5 @@
 # typed: true
 
 module Herb
-  VERSION = "0.11.1"
+  VERSION = "0.11.2"
 end

data/lib/herb.rb

@@ -67,7 +67,7 @@ rescue LoadError => e
 end
 
 module Herb
-  #: (String input, ?track_whitespace: bool, ?track_locations: bool, ?analyze: bool, ?strict: bool, ?action_view_helpers: bool, ?transform_conditionals: bool, ?dot_notation_tags: bool, ?render_nodes: bool, ?strict_locals: bool, ?herb_directives: bool, ?iteration_nodes: bool, ?prism_nodes: bool, ?prism_nodes_deep: bool, ?prism_program: bool, ?html: bool, ?erb_openers: Array[String], ?arena_stats: bool) -> ParseResult
+  #: (String input, ?track_whitespace: bool, ?track_locations: bool, ?analyze: bool, ?strict: bool, ?action_view_helpers: bool, ?transform_conditionals: bool, ?dot_notation_tags: bool, ?render_nodes: bool, ?strict_locals: bool, ?herb_directives: bool, ?iteration_nodes: bool, ?prism_nodes: bool, ?prism_nodes_deep: bool, ?prism_program: bool, ?html: bool, ?erb_openers: Array[String], ?ruby_version: String?, ?arena_stats: bool) -> ParseResult
   def self.parse(...)
     Backend.parse(...)
   end

data/sig/herb/analysis/partial_resolution.rbs

@@ -5,6 +5,8 @@ module Herb
     module PartialResolution
       PARTIAL_PREFIX: String
 
+      VARIANT_SEPARATOR: String
+
       EXTENSIONS: Array[String]
 
       EXTENSION_ALTERNATIVES: String
@@ -41,6 +43,12 @@ module Herb
       # : (Array[String]) -> Array[String]
       def self.by_precedence: (Array[String]) -> Array[String]
 
+      # : (String?) -> String?
+      def self.template_variant: (String?) -> String?
+
+      # : (Array[String], String?) -> String?
+      def self.preferred_for: (Array[String], String?) -> String?
+
       # : (String, String | Pathname) -> String?
       def self.template_name_for: (String, String | Pathname) -> String?
 

data/sig/herb/configuration.rbs

@@ -57,6 +57,9 @@ module Herb
     # : () -> Array[String]
     def erb_openers: () -> Array[String]
 
+    # : () -> String?
+    def ruby_version: () -> String?
+
     # : () -> Hash[Symbol, untyped]
     def parser_options: () -> Hash[Symbol, untyped]
 

data/sig/herb/engine/slots/dynamics_compiler.rbs

@@ -65,7 +65,8 @@ module Herb
       # An item is keyed by the key its template declares, through `herb-key` or `id` or a
       # `<%# herb:key %>` directive, which is what makes it survive being reordered. `Visitor`
       # decides what that key is and this evaluates it, so an item arrives under the same key the
-      # marker around it carries. A collection that declares none falls back to position.
+      # marker around it carries. A collection that declares none falls back to position, counting
+      # from the first iteration, so a change re-renders every row from the first one that differs.
       #
       # ## A partial keeps its own values
       #
@@ -88,7 +89,7 @@ module Herb
       #
       # ## Blocks
       #
-      # A tag that takes a block, such as `<%= form_with do |f| %>`, owns an entry holding everything
+      # A tag that takes a block, such as `<%= form_with do |f| %>`, owns an entry holding the markup
       # the block rendered, because the helper wraps that output in markup of its own that only the
       # helper can produce. What the template wrote inside the block keeps its own indices alongside:
       #
@@ -99,6 +100,20 @@ module Herb
       # and the whole block. Slot 1 is inside slot 0, which the client already has to reason about
       # for conditionals and collections.
       #
+      # A partial inside a block is the exception to that fallback. It keeps its own values on its slot,
+      # and the block's entry is a String that cannot hold them, so the entry leaves the partial's
+      # markup out:
+      #
+      #     <%= form_with(model: @user) do |f| %><%= render "card" %><% end %>
+      #     #=> { 0 => "<form></form>", 1 => { template: "app/views/_card.html.erb", ... } }
+      #
+      # That entry cannot stand in for the block, so it must not be written over a block holding a
+      # partial. The client never writes a block's entry while the page marks slots inside that block.
+      # It reports the block as deferred instead, even when nothing in the block changed.
+      #
+      # A render that comes back as markup, because its template is not compiled for slots, is written
+      # into the entry as usual, and the entry stays whole.
+      #
       # A block yielding more than once is the exception, since one index cannot stand for the several
       # values its interior took. `each` and the other iterations are compiled as collections for that
       # reason, and a helper that yields repeatedly reports the last value its interior took.
@@ -117,6 +132,8 @@ module Herb
 
         OCCURRENCE_BUFFER: String
 
+        RENDERED_BUFFER: String
+
         BRANCHING_NODES: Array[String]
 
         class Compiler < Herb::Engine::Compiler
@@ -249,8 +266,8 @@ module Herb
         # : (Integer) -> bool
         def boolean_presence?: (Integer) -> bool
 
-        # : (String, Integer?, bool) -> void
-        def add_dynamic_block: (String, Integer?, bool) -> void
+        # : (String, Integer?, bool, ?rendering: bool) -> void
+        def add_dynamic_block: (String, Integer?, bool, ?rendering: bool) -> void
 
         # : (String, ?escaped: bool) -> void
         def add_expression_block_end: (String, ?escaped: bool) -> void
@@ -305,9 +322,6 @@ module Herb
         # : (Integer) -> void
         def scope_item_end: (Integer) -> void
 
-        # : (Integer) -> bool
-        def keyed?: (Integer) -> bool
-
         # : (Integer) -> String
         def item_seeds: (Integer) -> String
 
@@ -332,6 +346,9 @@ module Herb
         # : (Integer) -> bool
         def interpolated?: (Integer) -> bool
 
+        # : (String) -> void
+        def add_block_render: (String) -> void
+
         # : (String) -> void
         def add_block_dynamic: (String) -> void
 

data/sig/herb/engine/slots/visitor.rbs

@@ -57,6 +57,8 @@ module Herb
 
         OCCURRENCE: String
 
+        POSITION: String
+
         NAME_ATTRIBUTE: String
 
         KEY_ATTRIBUTE: String
@@ -121,6 +123,15 @@ module Herb
 
           # : () -> bool
           def interpolated?: () -> bool
+
+          # : () -> bool
+          def positional?: () -> bool
+
+          # : () -> String
+          def position_variable: () -> String
+
+          # : () -> String?
+          def item_key: () -> String?
         end
 
         # : (String) -> bool
@@ -562,6 +573,9 @@ module Herb
         # : (untyped) -> Array[Array[Herb::AST::Node]]
         def branch_bodies: (untyped) -> Array[Array[Herb::AST::Node]]
 
+        # : (Array[untyped], Integer, Integer?) -> Integer
+        def insert_position_counter: (Array[untyped], Integer, Integer?) -> Integer
+
         # : (Herb::AST::Node, Integer?, ?Symbol) -> void
         def wrap_items: (Herb::AST::Node, Integer?, ?Symbol) -> void
 

data/sig/herb/engine/visitors/instrumentation_visitor.rbs

@@ -72,6 +72,8 @@ module Herb
       # : (Herb::AST::Node, Herb::AST::Node) -> Herb::AST::Node
       def replacing: (Herb::AST::Node, Herb::AST::Node) -> Herb::AST::Node
 
+      def literal?: (untyped node) -> untyped
+
       def framed?: (untyped node) -> untyped
 
       def assignment?: (untyped node) -> untyped
@@ -105,7 +107,9 @@ module Herb
 
       def code: (untyped node) -> untyped
 
-      def erb_node: (untyped node, untyped opening, untyped code) -> untyped
+      def rewrapped: (untyped node, untyped code) -> untyped
+
+      def erb_node: (untyped node, untyped opening, untyped code, ?closing: untyped) -> untyped
     end
   end
 end