herb 0.10.4-x86_64-linux-gnu → 0.11.1-x86_64-linux-gnu

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

@@ -0,0 +1,2267 @@
+# frozen_string_literal: true
+# typed: true
+
+require "digest"
+
+require_relative "../../ruby_program"
+require_relative "../../visitor"
+require_relative "../../visitor/context_aware"
+require_relative "../../visitor/diagnostics"
+require_relative "../../visitor/experimental"
+require_relative "annotation"
+require_relative "identifier"
+require_relative "manifest/channel"
+require_relative "components"
+require_relative "types"
+require_relative "state_compiler"
+require_relative "markers"
+require_relative "statics"
+require_relative "state_directives"
+require_relative "render_bindings"
+require_relative "callee"
+
+module Herb
+  class Engine
+    module Slots
+      # Records where a template's dynamic content ends up, and marks those places in the output so
+      # something outside Ruby can find them again:
+      #
+      #     visitor = Herb::Engine::Slots::Visitor.new
+      #
+      #     Herb::Engine.new(source, visitors: [visitor], filename: "app/views/posts/index.html.erb")
+      #
+      #     visitor.slots
+      #
+      # Templates can also ask for this themselves with a `<%# herb:slots %>` directive, and say who
+      # renders their branches with `<%# herb:slots client %>`. Deciding what that means belongs to
+      # whoever builds the stack, so the directive is only read here:
+      #
+      #     mode = Herb::Engine::Slots::Visitor.directive_mode(source)
+      #     visitors = mode ? [Herb::Engine::Slots::Visitor.new(mode: mode)] : []
+      #
+      class Visitor < Herb::Visitor
+        STATE_FAMILIES = [:read, :compare, :declaration, :conditional, :count, :assignment, :unknown, :binding].freeze #: Array[Symbol]
+
+        extend Herb::Visitor::Experimental
+        include Herb::Visitor::ContextAware
+        include Herb::Visitor::Diagnostics
+
+        recommended_parser_option iteration_nodes: true, render_nodes: true, strict_locals: true, prism_program: true
+        required_parser_option action_view_helpers: true, track_locations: true, herb_directives: true
+        experimental "Slots are experimental. Their markers, payload and client API may change."
+
+        attr_accessor :bufvar #: String
+        attr_reader :markers #: Markers
+        attr_reader :slots #: Array[Slot]
+        attr_reader :states #: StateCompiler
+        attr_reader :document #: untyped
+        attr_reader :warnings #: Array[Herb::Warnings::Warning]
+        attr_reader :static_markup #: String?
+        attr_reader :slot_nodes #: Array[untyped]
+
+        SLOTS_DIRECTIVE = /<%#-?\s*herb:slots\b(?<mode>[^%]*?)-?%>/ #: Regexp
+        MODE_OPTION = /\b(server|client)\b/ #: Regexp
+        MODES = [:server, :client].freeze #: Array[Symbol]
+        DELIVERIES = [:inline, :hoist, :none].freeze #: Array[Symbol]
+        COVERED = "@_herb_covered" #: String
+        OCCURRENCES = "@_herb_region_occurrences" #: String
+        OCCURRENCE = "_herb_occurrence" #: String
+        NAME_ATTRIBUTE = "data-herb-name" #: String
+        KEY_ATTRIBUTE = "herb-key" #: String
+
+        CAPTURING = /\b(?:content_for|provide|capture)\b/ #: Regexp
+        LISTENER_ATTRIBUTES = ["data-herb-set", "data-herb-toggle", "data-herb-increment", "data-herb-decrement", "data-herb-reset"].freeze #: Array[String]
+        OPEN_TAG_TYPES = [Herb::AST::HTMLOpenTagNode, Herb::AST::ERBOpenTagNode].freeze #: Array[Herb::AST::HTMLOpenTagNode|Herb::AST::ERBOpenTagNode]
+        BRANCH_BODY_PROPERTIES = [:statements, :body, :children, :conditions].freeze #: Array[Symbol]
+        BRANCH_CONTINUATION_PROPERTIES = [:subsequent, :else_clause, :rescue_clause, :ensure_clause].freeze #: Array[Symbol]
+
+        Slot = Data.define(
+          :index,          #: Integer
+          :type,           #: Symbol
+          :node_path,      #: Array[Integer]
+          :expression,     #: String?
+          :attribute,      #: String?
+          :key_source,     #: Symbol?
+          :key_expression, #: String?
+          :name,           #: String?
+          :tag,            #: String?
+          :merged_paths    #: Array[Array[Integer]]
+        )
+
+        class Slot
+          #: () -> bool
+          def structural? = Types.structural?(type)
+
+          #: () -> bool
+          def attribute? = Types.attribute?(type)
+
+          #: () -> bool
+          def anchored? = Types.element_anchored?(type)
+
+          #: () -> bool
+          def nameable? = Types.nameable?(type)
+
+          #: () -> bool
+          def valued? = Types.valued?(type)
+
+          #: () -> bool
+          def presence? = type == :boolean_attribute
+
+          #: () -> bool
+          def interpolated? = Types.interpolated?(type)
+        end
+
+        #: (String) -> bool
+        def self.directive?(source)
+          SLOTS_DIRECTIVE.match?(source)
+        end
+
+        #: (String) -> Symbol?
+        def self.directive_mode(source)
+          match = SLOTS_DIRECTIVE.match(source)
+
+          return nil unless match
+
+          named = MODE_OPTION.match(match[:mode])
+          mode = named && named[1]
+
+          mode ? mode.to_sym : :server
+        end
+
+        #: () -> bool
+        def self.reads_erb_source?
+          true
+        end
+
+        #: (?markers: Markers, ?mode: Symbol, ?identifier: (Symbol | ^(String) -> String), ?mark: bool, ?deliver: Symbol, ?fatal: bool, ?static_markup: bool) -> void
+        def initialize(markers: Markers.new, mode: :server, identifier: :path, mark: true, deliver: :hoist, fatal: true, static_markup: false)
+          super(fatal: fatal)
+
+          raise ArgumentError, "`mode: #{mode.inspect}` is not a slot mode. Pass one of #{MODES.map(&:inspect).join(", ")}." unless MODES.include?(mode)
+          raise ArgumentError, "`deliver: #{deliver.inspect}` is not a delivery. Pass one of #{DELIVERIES.map(&:inspect).join(", ")}." unless DELIVERIES.include?(deliver)
+
+          @markers = markers
+          @mark = mark
+          @degraded = false
+          @deliver = deliver
+          @capture_static_markup = static_markup
+          @static_markup = nil #: String?
+          @bufvar = "_buf"
+          @mode = mode
+          @statics = {} #: Hash[String, String]?
+          @identify = identifier
+
+          @slots = [] #: Array[Slot]
+          @warnings = [] #: Array[Herb::Warnings::Warning]
+          @path = [] #: Array[Integer]
+
+          @annotations = [] #: Array[Annotation]
+
+          standing = {} #: Hash[untyped, Annotation]
+          annotation_of = {} #: Hash[untyped, Annotation]
+          element_anchored = {} #: Hash[untyped, Array[Annotation]]
+          continuations = {} #: Hash[untyped, bool]
+          indices = {} #: Hash[untyped, Integer]
+
+          @standing = standing.compare_by_identity
+          @annotation_of = annotation_of.compare_by_identity
+          @element_anchored = element_anchored.compare_by_identity
+          @continuations = continuations.compare_by_identity
+          @indices = indices.compare_by_identity
+
+          @slot_nodes = [] #: Array[untyped]
+          @tag_stack = [] #: Array[String]
+          @named_elements = [] #: Array[Hash[Symbol, untyped]]
+          attribute_open_tags = {} #: Hash[untyped, untyped]
+          @attribute_open_tags = attribute_open_tags.compare_by_identity
+          render_bindings = {} #: Hash[untyped, Hash[Symbol, untyped]]
+          @render_bindings = render_bindings.compare_by_identity
+          @interpolated_attributes = [] #: Array[untyped]
+          @states = StateCompiler.new(self)
+          @collection_nodes = [] #: Array[untyped]
+          @collection_body_depths = [] #: Array[Integer]
+          keyed_elements = {} #: Hash[untyped, String]
+          @keyed_elements = keyed_elements.compare_by_identity
+          @container_depth = 0
+
+          @in_attribute = false
+          @in_open_tag = false
+          @displaced = [] #: Array[untyped]
+          @in_html_comment = false
+          @in_html_doctype = false
+          @raw_text_depth = 0
+          @rcdata_depth = 0
+          @rcdata_mixed_depth = 0
+          @rcdata_interpolated_depth = 0
+          @interpolated_rcdata = [] #: Array[untyped]
+          @listener_stack = [] #: Array[Array[String]]
+          listener_written = {} #: Hash[untyped, Array[String]]
+          @listener_written = listener_written.compare_by_identity
+          @current_open_tag = nil
+
+          fragment_nodes = {} #: Hash[untyped, Hash[String, untyped]]
+          fragment_fallbacks = {} #: Hash[untyped, Array[untyped]]
+          deferred_nodes = {} #: Hash[untyped, Hash[Symbol, untyped]]
+          assignment_nodes = {} #: Hash[untyped, bool]
+
+          @fragment_nodes = fragment_nodes.compare_by_identity
+          @fragment_fallbacks = fragment_fallbacks.compare_by_identity
+          @exposed_fallbacks = [] #: Array[untyped]
+          @deferred_nodes = deferred_nodes.compare_by_identity
+          @assignment_nodes = assignment_nodes.compare_by_identity
+        end
+
+        #: () -> bool
+        def degraded?
+          @degraded
+        end
+
+        #: () -> bool
+        def client?
+          @mode == :client
+        end
+
+        #: () -> void
+        def state_overrides!
+          @state_overrides = true
+        end
+
+        #: () -> bool
+        def state_overrides?
+          !!@state_overrides
+        end
+
+        #: (Integer, Array[String]) -> bool
+        def listener_writes?(index, names)
+          written = @listener_written[@slot_nodes[index]]
+
+          !written.nil? && written.intersect?(names)
+        end
+
+        #: (Integer) -> Array[Integer]
+        def slots_inside(index)
+          node = @slot_nodes[index]
+
+          return [] unless node
+
+          branch_bodies(node).flat_map { |body| slot_indices_within(body) }.uniq
+        end
+
+        #: (untyped) -> bool
+        def fragment?(node)
+          @fragment_nodes.key?(node)
+        end
+
+        #: () -> Array[Integer]
+        def fragment_indexes
+          @fragment_nodes.keys.filter_map { |node| @indices[node] }
+        end
+
+        #: (Integer) -> Hash[String, untyped]
+        def fragment_timing_for(index)
+          node = @slot_nodes[index]
+
+          return {} unless node
+
+          @fragment_nodes[node] || {}
+        end
+
+        #: (Array[untyped]) -> Array[untyped]
+        def transform_component_children(children)
+          children.flat_map { |child| transformed(child) }
+        end
+
+        #: (untyped, Array[untyped], Hash[String, untyped]) -> void
+        def record_fragment(node, fallback_children, timing)
+          @fragment_nodes[node] = timing
+          @fragment_fallbacks[node] = fallback_children
+        end
+
+        #: (Array[untyped]) -> void
+        def register_fallback_reads(children)
+          children.each do |child|
+            if child.is_a?(Herb::AST::ERBContentNode) && erb_outputs?(child) && fallback_state_read?(child)
+              record_slot(child, :child)
+
+              next
+            end
+
+            BRANCH_BODY_PROPERTIES.each do |property|
+              next unless child.respond_to?(property)
+
+              array = child.send(property)
+
+              register_fallback_reads(array) if array.is_a?(Array)
+            end
+          end
+        end
+
+        #: (untyped) -> bool
+        def fallback_state_read?(node)
+          name = expression_for(node).to_s.strip
+
+          return false unless name.match?(/\A[a-z_][a-zA-Z0-9_]*\z/)
+
+          state_declarations[:region].any? { |entry| entry[:name] == name && !entry[:derived] }
+        end
+
+        #: (untyped, mode: String, state: String, timing: Hash[String, Integer]) -> void
+        def record_deferred(node, mode:, state:, timing:)
+          @deferred_nodes[node] = { mode: mode, state: state, timing: timing }
+        end
+
+        #: (untyped) -> untyped
+        def record_assignment(node)
+          @assignment_nodes[node] = true
+
+          node
+        end
+
+        #: (untyped) -> bool
+        def assignment_node?(node)
+          @assignment_nodes.key?(node)
+        end
+
+        #: () -> Hash[Integer, Hash[Symbol, untyped]]
+        def deferred_entries
+          entries = {} #: Hash[Integer, Hash[Symbol, untyped]]
+
+          @deferred_nodes.each do |node, info|
+            index = @indices[node]
+
+            entries[index] = info if index
+          end
+
+          entries
+        end
+
+        #: (Integer) -> Array[Array[Integer]]
+        def slots_by_branch(index)
+          node = @slot_nodes[index]
+
+          return [] unless node
+
+          branch_bodies(node).map { |body| slot_indices_within(body) }
+        end
+
+        #: (String, Herb::Location?, Symbol, ?suggestion: String?) -> nil
+        def slot_error(message, location, family, suggestion: nil)
+          error(message, location, code: diagnostic_code_for(family), suggestion: suggestion)
+
+          @degraded = true
+
+          nil
+        end
+
+        #: (String, untyped, Symbol, ?suggestion: String?) -> void
+        def slot_warning(message, location, family, suggestion: nil)
+          warning(message, location, code: diagnostic_code_for(family), suggestion: suggestion)
+        end
+
+        #: (Symbol) -> String
+        def diagnostic_code_for(family)
+          STATE_FAMILIES.include?(family) ? "herb-state-#{family}" : "herb-slots-#{family}"
+        end
+
+        #: () -> String
+        def version
+          @version ||= Digest::SHA256.hexdigest(version_projection.join(",")).slice(0, 8).to_s
+        end
+
+        #: () -> Hash[Symbol, untyped]
+        def state_declarations
+          @states.state_declarations
+        end
+
+        #: () -> Array[Hash[Symbol, untyped]]
+        def state_entries
+          @states.state_entries
+        end
+
+        #: () -> Hash[Integer, Hash[Symbol, untyped]]
+        def state_conditional_entries
+          @states.state_conditional_entries
+        end
+
+        #: () -> Hash[Integer, String]
+        def state_conditional_signatures
+          @states.state_conditional_signatures
+        end
+
+        #: () -> Array[Hash[Symbol, untyped]]
+        def state_count_entries
+          @states.state_count_entries
+        end
+
+        #: () -> Hash[Integer, untyped]
+        def state_presence
+          @states.state_presence
+        end
+
+        #: () -> Hash[Integer, untyped]
+        def state_values
+          @states.state_values
+        end
+
+        #: () -> Array[String]
+        def seeded_region_states
+          @states.seeded_region_states
+        end
+
+        #: () -> Hash[Integer, Array[String]]
+        def seeded_item_states
+          @states.seeded_item_states
+        end
+
+        #: () -> untyped
+        def current_collection
+          @collection_nodes.last
+        end
+
+        #: (untyped) -> Array[String]
+        def block_locals(scope)
+          nodes = @collection_nodes.include?(scope) ? @collection_nodes.take(@collection_nodes.index(scope) + 1) : [scope]
+
+          nodes.compact.flat_map { |node| parameter_names(node) }
+        end
+
+        #: (untyped) -> Array[String]
+        def parameter_names(node)
+          return [] unless node.respond_to?(:block_arguments)
+
+          (node.block_arguments || []).filter_map { |parameter| parameter.name&.value&.to_s if parameter.respond_to?(:name) }
+        end
+
+        #: () -> bool
+        def in_item_body?
+          @container_depth == @collection_body_depths.last
+        end
+
+        #: () -> bool
+        def inline?
+          @in_open_tag || @in_attribute
+        end
+
+        #: (untyped) -> untyped
+        def open_tag_for(node)
+          @attribute_open_tags[node]
+        end
+
+        #: (untyped) -> untyped
+        def scope_of(node)
+          annotation = @annotation_of[node]
+
+          annotation && [annotation.scope, annotation.depth]
+        end
+
+        #: (Integer, Slot) -> void
+        def replace_slot(index, slot)
+          @slots[index] = slot
+        end
+
+        #: (untyped, Integer) -> void
+        def assign_index(node, index)
+          @indices[node] = index
+        end
+
+        #: () -> bool
+        def marking?
+          @mark
+        end
+
+        #: () -> Array[String]
+        def version_projection
+          conditionals = state_conditional_signatures
+
+          slots = @slots.map { |slot|
+            [
+              slot.index,
+              slot.type,
+              slot.node_path,
+              slot.attribute,
+              slot.name,
+              slot.key_source,
+              conditionals[slot.index]
+            ].inspect
+          }
+
+          declarations = state_entries.map { |entry|
+            [entry[:name], entry[:kind], entry[:default], entry[:scope], entry[:derived] && StateDirectives.condition_source(entry[:derived])].inspect
+          }
+
+          counts = @states.count_signatures
+
+          bindings = manifest_bindings.map { |index, entry| [index, entry["identifier"], entry["states"]].inspect }
+
+          slots + declarations + counts + bindings
+        end
+
+        #: () -> String
+        def inspect
+          parts = [self.class.name, @mode.to_s] #: Array[String]
+
+          parts << "#{@identify} ids" unless @identify == :path
+          parts << "deliver=#{@deliver}" unless @deliver == :hoist
+          parts << "fatal=#{fatal?}" unless fatal?
+
+          "#<#{parts.join(" ")}>"
+        end
+
+        #: () -> String
+        def identifier
+          @identifier ||= Identifier.new(@identify).call(context.relative_file_path)
+        end
+
+        #: () -> Hash[String, untyped]
+        def manifest
+          {
+            "file" => context.relative_file_path,
+            "identifier" => identifier,
+            "version" => version,
+            "names" => manifest_names,
+            "parts" => manifest_parts,
+            "bindings" => manifest_bindings,
+            "states" => @states.manifest,
+          }
+        end
+
+        #: () -> Hash[String, Hash[String, untyped]]
+        def manifest_bindings
+          bindings = {} #: Hash[String, Hash[String, untyped]]
+
+          @render_bindings.each do |node, binding|
+            index = @indices[node]
+
+            next unless index
+            next if binding.fetch(:bound).empty?
+
+            bindings[index.to_s] = {
+              "identifier" => binding.fetch(:identifier),
+              "partial" => binding.fetch(:partial),
+              "states" => binding.fetch(:bound),
+            }
+          end
+
+          bindings
+        end
+
+        #: (String) -> bool
+        def counted_state?(name)
+          @states.counted_state?(name)
+        end
+
+        #: () -> Hash[String, Integer]
+        def manifest_names
+          names = {} #: Hash[String, Integer]
+
+          @slots.each do |slot|
+            name = slot.name
+
+            names[name] = slot.index if name
+          end
+
+          names
+        end
+
+        #: () -> Hash[String, Array[String]]
+        def manifest_parts
+          parts = {} #: Hash[String, Array[String]]
+
+          @interpolated_attributes.each do |node|
+            index = @indices[node]
+
+            next unless index
+
+            segments = attribute_segments(node)
+
+            next unless segments
+
+            parts[index.to_s] = segments
+          end
+
+          @interpolated_rcdata.each do |node|
+            index = @indices[node]
+
+            next unless index
+
+            segments = rcdata_segments(node.body)
+
+            next unless segments
+
+            parts[index.to_s] = segments
+          end
+
+          parts
+        end
+
+        #: () -> Hash[Symbol, untyped]
+        def schema
+          {
+            file: context.relative_file_path,
+            identifier: identifier,
+            version: version,
+            slots: slot_entries,
+          }
+        end
+
+        #: () -> Array[Hash[Symbol, untyped]]
+        def slot_entries
+          @slot_entries ||= @slots.map { |slot|
+            entry = { index: slot.index, type: slot.type, node_path: slot.node_path }
+            entry = entry.merge(attribute: slot.attribute) if slot.attribute
+            entry = entry.merge(key_source: slot.key_source) if slot.key_source
+            entry = entry.merge(name: slot.name) if slot.name
+
+            entry
+          }
+        end
+
+        #: () -> Array[String]
+        def recorded_expressions
+          @annotations.map { |annotation| annotation.expression.to_s }
+        end
+
+        #: (untyped) -> Integer?
+        def index_for(node)
+          @indices[node]
+        end
+
+        #: () -> String
+        def occurrence_expression
+          "((#{OCCURRENCES} ||= ::Hash.new(0))[#{identifier.inspect}] += 1) - 1"
+        end
+
+        #: (Herb::Location?) -> Herb::RubyProgram::Resolved?
+        def ruby_at(location)
+          return nil unless location
+
+          unless @ruby_program_built
+            @ruby_program_built = true
+            @ruby_program = @document ? Herb::RubyProgram.for(@document) : nil
+          end
+
+          @ruby_program&.resolve(location)
+        end
+
+        def visit_document_node(node)
+          @document = node
+
+          if declares_slots?(node)
+            transform_components(node)
+            detect_keyed_elements(node)
+          end
+
+          visit_children_with_paths(node.children)
+
+          @fragment_fallbacks.each_value { |body| register_fallback_reads(body) }
+
+          collapse_invariant_conditionals
+          apply_names
+          number_slots
+
+          @states.apply_states
+
+          wrap_bound_renders
+          expose_fallbacks(node)
+        end
+
+        #: () -> Hash[String, String]?
+        def statics
+          @statics&.dup
+        end
+
+        #: (untyped) -> void
+        def finish(node)
+          withdraw_fallbacks(node)
+          follow_replacements
+
+          return unless @mark
+
+          return wrap_region(node) if @degraded
+
+          insert_markers(node)
+          wrap_displaced
+
+          @static_markup = Statics.new(@standing, @element_anchored).markup(node.children) if @capture_static_markup
+
+          wrap_region(node)
+          append_statics(node)
+          deliver_manifest(node)
+        end
+
+        #: () -> void
+        def follow_replacements
+          replacements = context.replacements
+
+          return unless replacements.any?
+
+          replacements.each do |replacement, original|
+            annotations = @standing[original]
+            @standing[replacement] = annotations if annotations
+
+            index = @indices[original]
+            @indices[replacement] = index if index
+          end
+        end
+
+        #: (untyped) -> void
+        def deliver_manifest(document_node)
+          return if @deliver == :none
+
+          built = manifest
+
+          return if built["names"].empty? && built["parts"].empty? && built["states"].nil? && built["bindings"].empty?
+
+          json = JSON.generate(built, script_safe: true)
+          key = "#{identifier}:#{version}"
+
+          if @deliver == :hoist
+            document_node.children.push(erb_code_node("::Herb::Engine::Slots::Manifest::Channel.record(#{key.dump}, #{json.dump})"))
+
+            return
+          end
+
+          document_node.children.unshift(erb_code_node("#{COVERED} ||= {}"))
+
+          ref = "#{COVERED}[#{"manifest:#{key}".inspect}]"
+
+          document_node.children.push(
+            erb_code_node("unless #{ref}"),
+            text_node(@markers.manifests_open),
+            text_node("{#{JSON.generate(key)}:#{json}}"),
+            text_node(@markers.manifests_close),
+            erb_code_node("#{ref} = true"),
+            erb_code_node("end")
+          )
+        end
+
+        def visit_html_element_node(node)
+          record_slot(node, :keyed) if @keyed_elements.key?(node)
+
+          tag_name = node.tag_name&.value&.downcase.to_s
+          raw_text = Herb::HTML::Util.raw_text_element?(tag_name)
+          rcdata = Herb::HTML::Util.rcdata_element?(tag_name)
+          segments = rcdata && mixed_rcdata_body?(node.body) ? rcdata_segments(node.body) : nil
+          mixed = rcdata && segments.nil? && mixed_rcdata_body?(node.body)
+
+          @raw_text_depth += 1 if raw_text
+          @rcdata_depth += 1 if rcdata
+          @rcdata_mixed_depth += 1 if mixed
+          @rcdata_interpolated_depth += 1 if segments
+
+          previous_open_tag = @current_open_tag
+          @current_open_tag = node.open_tag
+          @tag_stack.push(tag_name)
+          @listener_stack.push(listener_names_for(node))
+
+          if segments
+            record_slot(node, :raw_text_interpolation)
+            @interpolated_rcdata << node
+          end
+
+          name_attribute = attributes_for(node).find { |attribute| attribute_name_for(attribute)&.downcase == NAME_ATTRIBUTE }
+          base = @annotations.size
+          base_scope = @collection_nodes.last
+          base_depth = @container_depth
+
+          visit(node.open_tag) if node.open_tag
+          visit_children_with_paths(node.body)
+          visit(node.close_tag) if node.close_tag
+
+          record_named_element(node, name_attribute, base, base_scope, base_depth) if name_attribute
+
+          @listener_stack.pop
+          @tag_stack.pop
+          @current_open_tag = previous_open_tag
+
+          @rcdata_interpolated_depth -= 1 if segments
+          @rcdata_mixed_depth -= 1 if mixed
+          @rcdata_depth -= 1 if rcdata
+          @raw_text_depth -= 1 if raw_text
+        end
+
+        def visit_erb_strict_locals_node(node)
+          (node.locals || []).each do |parameter|
+            name = parameter.name&.value.to_s
+            next if name.empty?
+
+            @states.declare_local(name, parameter.default_value&.content)
+          end
+
+          super
+        end
+
+        def visit_html_open_tag_node(node)
+          @in_open_tag = true
+          super
+          @in_open_tag = false
+        end
+
+        def visit_erb_open_tag_node(node)
+          @in_open_tag = true
+          super
+          @in_open_tag = false
+        end
+
+        def visit_html_attribute_node(node)
+          if dynamic?(node)
+            record_slot(node, attribute_type_for(node))
+            @attribute_open_tags[node] = @current_open_tag
+            @interpolated_attributes << node if attribute_type_for(node) == :attribute_interpolation
+          end
+
+          @in_attribute = true
+          super
+          @in_attribute = false
+        end
+
+        def visit_html_comment_node(node)
+          record_slot(node, :comment) if dynamic?(node)
+
+          @in_html_comment = true
+          super
+          @in_html_comment = false
+        end
+
+        def visit_html_doctype_node(node)
+          @in_html_doctype = true
+          super
+          @in_html_doctype = false
+        end
+
+        def visit_erb_content_node(node)
+          record_slot(node, erb_outputs?(node) ? :child : nil)
+
+          super
+        end
+
+        def visit_erb_render_node(node)
+          bind_render_states(node) if node.bound_state?
+
+          record_slot(node, erb_outputs?(node) ? :child : nil)
+
+          super
+        end
+
+        #: (untyped) -> void
+        def bind_render_states(node)
+          location = node.location
+
+          unless node.static_partial?
+            slot_error("`state:` needs a partial the compiler can see, and this render picks its template at runtime.", location, :binding, suggestion: "Render the partial by its literal name, like `render \"shared/card\", state: { ... }`.")
+
+            return
+          end
+
+          if node.end_node
+            slot_error("`state:` cannot bind a partial rendered with a block, since the binding wraps the whole call.", location, :binding, suggestion: "Render the partial without a block, or move the block's content into the partial.")
+
+            return
+          end
+
+          if inline? || @in_html_comment || !erb_outputs?(node)
+            slot_error("`state:` binds a partial rendered as page content, not one inside an attribute, a comment or a silent tag.", location, :binding, suggestion: "Render the partial with `<%= render ... %>` in the page body.")
+
+            return
+          end
+
+          token = node.content
+          analysis = RenderBindings.analyze(node)
+
+          unless token && analysis
+            slot_error("`state:` on this render could not be read.", location, :binding, suggestion: "Write it as `state: { name: value }` after the partial's locals.")
+
+            return
+          end
+
+          analysis.problems.each { |message, suggestion, where| slot_error(message, where || location, :binding, suggestion: suggestion) }
+
+          return unless analysis.problems.empty?
+
+          partial = node.partial_path.to_s
+          twice = node.local_names & analysis.entries.map(&:name)
+
+          analysis.entries.each do |entry|
+            next unless twice.include?(entry.name)
+
+            slot_error("`#{entry.name}` goes to `#{partial}` both as a local and as a state, and the state assignment would overwrite the local.", entry.location || location, :binding, suggestion: "Pass `#{entry.name}` one way. A local is a snapshot the partial reads, a state is a value the client can write.")
+          end
+
+          return unless twice.empty?
+
+          unless partial.include?("/")
+            slot_error("`state:` needs the partial's directory in its name, since `#{partial}` resolves through the controller's view paths at render and the compiler cannot follow that.", location, :binding, suggestion: "Name it from the view root, like `render \"#{File.basename(File.dirname(context.relative_file_path))}/#{partial}\", state: { ... }`.")
+
+            return
+          end
+
+          relative, absolute = child_template_for(node)
+
+          unless relative && absolute
+            similar = similar_partials_for(node).map { |name| "`#{name}`" }
+            advice = similar.empty? ? "Check the partial's path." : "Did you mean #{similar.join(", ")}?"
+
+            slot_error("`#{partial}` could not be found from `#{context.relative_file_path}`, and `state:` needs a partial the compiler can open.", location, :binding, suggestion: advice)
+
+            return
+          end
+
+          callee = Callee.for(absolute)
+
+          slot_warning("`#{partial}` could not be compiled from `#{context.relative_file_path}`, so its states go unchecked.", location, :binding, suggestion: "A partial that renders its own caller is checked from the other side only.") unless callee
+
+          failed = callee&.errors&.first
+
+          if failed
+            slot_error("`#{partial}` did not compile, so `state:` cannot check its states. Its compile said #{failed.message}", location, :binding, suggestion: "Fix the partial first.")
+
+            return
+          end
+
+          bound = {} #: Hash[String, String]
+          seeded = {} #: Hash[String, String]
+
+          analysis.entries.each { |entry| classify_binding(entry, partial, callee, bound, seeded, entry.location || location) }
+
+          return if @degraded
+
+          token.value.replace(analysis.stripped)
+
+          @render_bindings[node] = { identifier: Identifier.new(@identify).call(relative), partial: partial, bound: bound, seeded: seeded }
+        rescue FrozenError
+          slot_error("`state:` on this render could not be rewritten, since the template's source was frozen before the compile could edit it.", node.location, :binding, suggestion: "Report this with the template that raised it.")
+        end
+
+        #: (RenderBindings::Entry, String, Callee?, Hash[String, String], Hash[String, String], Herb::Location?) -> void
+        def classify_binding(entry, partial, callee, bound, seeded, location)
+          child = callee&.declaration(entry.name)
+
+          if callee && child.nil?
+            known = callee.names.map { |name| "`#{name}`" }.join(", ")
+            advice = known.empty? ? "Declare `#{entry.name}` in the partial with `<%# herb:state (#{entry.name}: ...) %>`." : "The partial declares #{known}."
+
+            slot_error("`#{partial}` declares no state `#{entry.name}`, so `state:` has nothing to bind it to.", location, :binding, suggestion: advice)
+
+            return
+          end
+
+          if child && (child.derived || child.counted)
+            slot_error("`#{entry.name}` is a #{child.derived ? "derived" : "counted"} state of `#{partial}`, and the partial computes it itself.", location, :binding, suggestion: "Bind or seed the states it computes from instead.")
+
+            return
+          end
+
+          candidate = entry.candidate
+          declaration = candidate ? @states.region_declaration(candidate) : nil
+
+          if declaration && candidate
+            if declaration.derived || @states.counted_state?(candidate)
+              slot_error("`#{candidate}` is a #{declaration.derived ? "derived" : "counted"} state, and a binding needs a state the partial can write back to.", location, :binding, suggestion: "Bind a plain state, or bind the states `#{candidate}` computes from.")
+
+              return
+            end
+
+            if child && !compatible_kinds?(child.kind, declaration.kind)
+              slot_error("`#{entry.name}` on `#{partial}` is #{with_article(child.kind)} state and `#{candidate}` is #{with_article(declaration.kind)} one.", location, :binding, suggestion: "Bind a state of the same kind, or change the partial's default.")
+
+              return
+            end
+
+            bound[entry.name] = candidate
+
+            return
+          end
+
+          warn_binding_near_miss(candidate, location) if candidate
+
+          reason = RenderBindings::REFUSED[entry.kind]
+
+          if reason
+            slot_error("`#{entry.source}` seeds `#{entry.name}` on `#{partial}` with #{StateKinds::ARTICLES.fetch(entry.kind.to_s)}. #{reason}", location, :binding, suggestion: "Pass it as a local instead.")
+
+            return
+          end
+
+          if child && !compatible_kinds?(child.kind, entry.kind)
+            slot_error("`#{entry.name}` on `#{partial}` is #{with_article(child.kind)} state, and `#{entry.source}` seeds it with #{with_article(entry.kind)} value.", location, :binding, suggestion: "Seed it with #{with_article(child.kind)} value.")
+
+            return
+          end
+
+          seeded[entry.name] = entry.source
+        end
+
+        #: (Symbol, Symbol) -> bool
+        def compatible_kinds?(declared, given)
+          return true if declared == given
+          return true if declared == :seeded || given == :seeded
+
+          declared == :nil || given == :nil
+        end
+
+        #: (Symbol) -> String
+        def with_article(kind)
+          spelled = kind.to_s
+
+          spelled.start_with?("a", "e", "i", "o", "u") ? "an #{spelled}" : "a #{spelled}"
+        end
+
+        #: (String, Herb::Location?) -> void
+        def warn_binding_near_miss(candidate, location)
+          suggestions = DidYouMean::SpellChecker.new(dictionary: @states.region_state_names).correct(candidate)
+
+          return if suggestions.empty?
+
+          slot_warning("`#{candidate}` is not a state of this template, so it seeds the partial once and never follows a change. Did you mean `#{suggestions.first}`?", location, :binding, suggestion: "Bind `#{suggestions.first}` to keep the two in step.")
+        end
+
+        #: (untyped) -> [String?, Pathname?]
+        def child_template_for(node)
+          resolved = context.resolver.resolve(node.partial_path.to_s, from: context.file_path)
+
+          resolved ? [resolved.identifier, resolved.path] : [nil, nil]
+        end
+
+        #: (untyped) -> Array[String]
+        def similar_partials_for(node)
+          context.resolver.similar(node.partial_path.to_s, from: context.file_path)
+        end
+
+        #: () -> void
+        def wrap_bound_renders
+          return if @degraded
+
+          @render_bindings.each do |node, binding|
+            token = node.content
+
+            next unless token
+
+            bound = binding.fetch(:bound).map { |child, parent| "#{child.inspect} => #{parent}" }.join(", ")
+            seeded = binding.fetch(:seeded).map { |child, expression| "#{child.inspect} => (#{expression})" }.join(", ")
+            call = token.value.strip
+
+            token.value.replace(" ::Herb::Engine::Slots::Bindings.with(#{binding.fetch(:identifier).inspect}, bound: { #{bound} }, seeded: { #{seeded} }) { #{call} } ")
+          rescue FrozenError
+            next
+          end
+        end
+
+        def visit_erb_yield_node(node)
+          record_slot(node, :child)
+
+          super
+        end
+
+        def visit_erb_if_node(node)
+          unless fragment?(node)
+            return if @states.register_count_fold(node)
+            return if convert_helper_boolean_attribute(node)
+          end
+
+          record_slot(node, :conditional) unless continuation?(node)
+
+          visit_branching_node(node)
+        end
+
+        def visit_erb_unless_node(node)
+          record_slot(node, :conditional) unless continuation?(node)
+
+          visit_branching_node(node)
+        end
+
+        def visit_erb_else_node(node)
+          register_branch_directives(node)
+          super
+        end
+
+        def visit_erb_when_node(node)
+          register_branch_directives(node)
+          super
+        end
+
+        #: (untyped) -> void
+        def register_branch_directives(node)
+          BRANCH_BODY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            body = node.send(property)
+            next unless body.is_a?(Array)
+
+            body.each { |child| @states.register_state_directive(child, body) }
+          end
+        end
+
+        def visit_erb_case_node(node)
+          record_slot(node, :conditional) unless continuation?(node)
+
+          visit_branching_node(node)
+        end
+
+        def visit_erb_block_node(node)
+          record_slot(node, :block) if erb_outputs?(node)
+
+          @displaced << node if CAPTURING.match?(expression_for(node).to_s)
+
+          visit_branching_node(node)
+        end
+
+        def visit_erb_iteration_block_node(node)
+          visit_collection_node(node)
+        end
+
+        def visit_erb_while_node(node)
+          visit_collection_node(node)
+        end
+
+        def visit_erb_until_node(node)
+          visit_collection_node(node)
+        end
+
+        def visit_erb_for_node(node)
+          visit_collection_node(node)
+        end
+
+        def visit_collection_node(node)
+          record_slot(node, :collection)
+
+          @collection_nodes.push(node)
+          @collection_body_depths.push(@container_depth + 1)
+          visit_branching_node(node)
+          @collection_body_depths.pop
+          @collection_nodes.pop
+        end
+
+        #: (untyped) -> bool
+        def continuation?(node)
+          @continuations.key?(node)
+        end
+
+        #: (untyped) -> bool
+        def exhaustive?(node)
+          current = continuation_of(node) #: untyped
+          last = current #: untyped
+
+          while current
+            last = current
+            current = continuation_of(current)
+          end
+
+          last.is_a?(Herb::AST::ERBElseNode)
+        end
+
+        #: (untyped) -> Array[untyped]
+        def conditional_chain(node)
+          chain = [] #: Array[untyped]
+          current = node #: untyped
+
+          while current
+            chain << current
+            current = continuation_of(current)
+          end
+
+          chain
+        end
+
+        #: (untyped) -> bool
+        def blank_child?(node)
+          return true if node.is_a?(Herb::AST::WhitespaceNode)
+
+          if node.is_a?(Herb::AST::HTMLTextNode) || node.is_a?(Herb::AST::LiteralNode)
+            return node.content.to_s.strip.empty?
+          end
+
+          false
+        end
+
+        #: (untyped) -> untyped
+        def continuation_of(node)
+          subsequent = node.respond_to?(:subsequent) ? node.subsequent : nil
+
+          subsequent || (node.respond_to?(:else_clause) ? node.else_clause : nil)
+        end
+
+        def text_node(content)
+          Herb::AST::HTMLTextNode.build(content: content.dup)
+        end
+
+        def erb_code_node(code)
+          Herb::AST::ERBContentNode.build(
+            tag_opening: token(:erb_start, "<%"),
+            content: token(:erb_content, " #{code} "),
+            tag_closing: token(:erb_end, "%>"),
+            valid: true
+          )
+        end
+
+        def erb_output_node(code)
+          Herb::AST::ERBContentNode.build(
+            tag_opening: token(:erb_start, "<%="),
+            content: token(:erb_content, " #{code} "),
+            tag_closing: token(:erb_end, "%>"),
+            valid: true
+          )
+        end
+
+        #: (Array[untyped], Integer) -> String
+        def attribute_spacing(children, position)
+          position.positive? && children[position - 1].is_a?(Herb::AST::WhitespaceNode) ? "" : " "
+        end
+
+        private
+
+        def visit_children_with_paths(children)
+          return unless children.is_a?(Array)
+
+          children.each_with_index do |child, index|
+            @states.register_state_directive(child, children)
+            @states.check_state_assignment(child)
+
+            @path.push(index)
+            record_slot(child, :child) if child.is_a?(Herb::AST::RubyLiteralNode)
+            visit(child)
+            @path.pop
+          end
+        end
+
+        def visit_branching_node(node)
+          @container_depth += 1
+
+          BRANCH_BODY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            visit_children_with_paths(node.send(property))
+          end
+
+          BRANCH_CONTINUATION_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            child = node.send(property)
+            next unless child
+
+            @continuations[child] = true
+            visit(child)
+          end
+
+          @container_depth -= 1
+        end
+
+        #: (untyped) -> bool
+        def declares_slots?(node)
+          node.children.any? { |child|
+            child.is_a?(Herb::AST::HerbDirectiveNode) && child.directive == "slots"
+          }
+        end
+
+        #: (untyped) -> void
+        def transform_components(node)
+          return unless node.is_a?(Herb::AST::Node)
+
+          BRANCH_BODY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            value = node.send(property)
+
+            case value
+            when Array
+              if property == :conditions
+                value.each { |arm| transform_components(arm) }
+              else
+                value.replace(value.flat_map { |child| transformed(child) })
+              end
+            when Herb::AST::Node
+              transform_components(value)
+            end
+          end
+
+          BRANCH_CONTINUATION_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            continuation = node.send(property)
+
+            transform_components(continuation) if continuation
+          end
+        end
+
+        #: (untyped) -> Array[untyped]
+        def transformed(child)
+          unless Components.element?(child)
+            transform_components(child)
+
+            return [child]
+          end
+
+          name = child.tag_name&.value.to_s
+          component = Components.for(name)
+
+          return component.transform(child, self) if component
+
+          slot_error("`<#{name}>` is not a component Herb knows.", child.location, :component, suggestion: "The built-in components are #{Components::BUILT_IN.map { |built_in| "`<#{built_in}>`" }.join(" and ")}.")
+
+          [child]
+        end
+
+        #: () -> void
+        def collapse_invariant_conditionals
+          @standing.each_value do |annotation|
+            next unless annotation.type == :conditional
+            next if fragment?(annotation.node)
+            next unless exhaustive?(annotation.node)
+
+            bodies = branch_bodies(annotation.node)
+            next unless bodies.size > 1
+
+            signatures = bodies.filter_map { |body| Statics.new(@standing, @element_anchored).signature(body) }
+            next unless signatures.size == bodies.size
+
+            shapes = signatures.map { |shape, _| shape }
+            next unless shapes.uniq.one?
+            next if branching_shape?(shapes.fetch(0))
+
+            positions = signatures.map { |_, found| found }
+            shared = positions.fetch(0)
+
+            annotation.dropped = true
+
+            shared.each { |survivor| survivor.covered << annotation }
+
+            positions.drop(1).each do |found|
+              found.each_with_index do |other, position|
+                survivor = shared.fetch(position)
+
+                other.merged_into = survivor
+                survivor.covered << other
+              end
+            end
+          end
+
+          @standing.delete_if { |_node, annotation| annotation.dropped }
+        end
+
+        #: (untyped) -> Array[Integer]
+        def slot_indices_within(nodes)
+          children = Array(nodes) #: Array[untyped]
+
+          children.compact.flat_map { |child|
+            next [] unless child.is_a?(Herb::AST::Node)
+
+            inside = slot_indices_within(child.compact_child_nodes)
+            index = @indices[child]
+
+            index ? [index, *inside] : inside
+          }
+        end
+
+        #: (String) -> bool
+        def branching_shape?(shape)
+          Types::STRUCTURAL.any? { |type| shape.include?("\u0000#{type}\u0000") }
+        end
+
+        #: () -> void
+        def number_slots
+          surviving = @annotations.reject(&:gone?)
+
+          surviving.each_with_index { |annotation, index| annotation.index = index }
+
+          @slots = surviving.each_with_index.map { |annotation, index| annotation.to_slot(index) }
+          @slot_nodes = surviving.map(&:node)
+
+          @annotations.each do |annotation|
+            next if annotation.dropped
+
+            @indices[annotation.node] = annotation.survivor.index
+          end
+        end
+
+        #: (untyped, Symbol?) -> void
+        def record_slot(node, type)
+          return unless type
+
+          type = anchored_type_for(type)
+
+          return unless type
+          return if @in_html_comment || @in_html_doctype
+          return if type == :raw_text && @rcdata_interpolated_depth.positive?
+          return refuse_mixed_rcdata(node) if type == :raw_text && @rcdata_mixed_depth.positive?
+
+          key_source, key_expression = keys_for(node, type)
+
+          annotation = Annotation.new(
+            node: node,
+            type: type,
+            node_path: @path.dup,
+            expression: expression_for(node),
+            attribute: attribute_name_for(node),
+            key_source: key_source,
+            key_expression: key_expression,
+            tag: @tag_stack.last,
+            scope: @collection_nodes.last,
+            depth: @container_depth
+          )
+
+          @annotations << annotation
+          @annotation_of[node] = annotation
+
+          written = @listener_stack.flatten
+          @listener_written[node] = written unless written.empty?
+
+          if type == :collection && key_source == :index
+            @warnings << Herb::Warnings::UnkeyedCollectionWarning.new(
+              node.location,
+              expression_for(node),
+              tag_name: keyable_tag_name_for(node)
+            )
+          end
+
+          if !annotation.anchored?
+            @standing[node] = annotation
+          elsif @current_open_tag
+            anchored = @element_anchored[@current_open_tag] || [] #: Array[Annotation]
+            anchored << annotation
+
+            @element_anchored[@current_open_tag] = anchored
+          end
+        end
+
+        #: (Symbol) -> Symbol?
+        def anchored_type_for(type)
+          return type if type == :raw_text_interpolation
+          return type if Types.attribute_value?(type)
+
+          return nil if @in_attribute
+          return :element if @in_open_tag
+          return nil if @raw_text_depth.positive?
+          return :raw_text if @rcdata_depth.positive?
+
+          type
+        end
+
+        #: (Array[untyped]) -> Array[String]?
+        def rcdata_segments(children)
+          segments = [+""]
+
+          Array(children).each do |child|
+            case child
+            when Herb::AST::HTMLTextNode, Herb::AST::LiteralNode
+              segments.last << child.content.to_s
+            when Herb::AST::WhitespaceNode
+              segments.last << child.value&.value.to_s
+            when Herb::AST::ERBContentNode
+              return nil unless erb_outputs?(child)
+
+              segments << +""
+            else
+              return nil
+            end
+          end
+
+          segments.size > 1 ? segments : nil
+        end
+
+        #: (untyped) -> Array[String]
+        def listener_names_for(node)
+          attributes_for(node).flat_map { |attribute|
+            name = attribute_name_for(attribute)&.downcase
+
+            next [] unless name && LISTENER_ATTRIBUTES.include?(name)
+
+            value = static_attribute_value(attribute)
+
+            next [] unless value
+
+            value.split.filter_map { |clause|
+              rest = clause.split("->", 2).last.to_s
+              target = name == "data-herb-set" ? rest.split("=", 2).first : rest
+              cleaned = target.to_s.strip
+
+              cleaned unless cleaned.empty?
+            }
+          }
+        end
+
+        #: (untyped) -> String?
+        def rcdata_expression_for(node)
+          outputs = Array(node.body).grep(Herb::AST::ERBContentNode) #: Array[untyped]
+
+          return nil unless outputs.one?
+
+          outputs.fetch(0).content&.value&.strip
+        end
+
+        #: (Array[untyped]) -> bool
+        def mixed_rcdata_body?(children)
+          outputs = children.count { |child| child.is_a?(Herb::AST::ERBContentNode) && erb_outputs?(child) }
+
+          return false if outputs.zero?
+          return true if outputs > 1
+
+          children.any? { |child|
+            (child.is_a?(Herb::AST::HTMLTextNode) || child.is_a?(Herb::AST::LiteralNode)) && !child.content.to_s.strip.empty?
+          }
+        end
+
+        #: (untyped) -> nil
+        def refuse_mixed_rcdata(node)
+          expression = expression_for(node)
+          tag = @tag_stack.last
+
+          slot_warning(
+            "`<%= #{expression} %>` shares the `<#{tag}>` content with other text. The client writes this content as one piece and would discard the rest, so the expression stays server-rendered and never updates.",
+            node.location,
+            :content,
+            suggestion: "Make `<%= #{expression} %>` the only content of the `<#{tag}>`, or move the other text outside it."
+          )
+
+          nil
+        end
+
+        #: (untyped) -> Symbol
+        def attribute_type_for(node)
+          return :element unless attribute_name_for(node)
+
+          children = node.value&.children || []
+
+          children.one? ? :attribute : :attribute_interpolation
+        end
+
+        #: (untyped) -> untyped
+        def convert_helper_boolean_attribute(node)
+          open_tag = @current_open_tag
+
+          return nil unless @in_open_tag && (open_tag.is_a?(Herb::AST::ERBOpenTagNode) || open_tag.is_a?(Herb::AST::HTMLOpenTagNode))
+          return nil if continuation?(node)
+          return nil unless node.respond_to?(:subsequent) && node.subsequent.nil?
+
+          children = open_tag.children
+
+          position = children.index { |child| child.equal?(node) }
+          return nil unless position
+
+          statements = node.statements
+          return nil unless statements.is_a?(Array) && statements.one?
+
+          attribute = statements.fetch(0)
+          return nil unless attribute.is_a?(Herb::AST::HTMLAttributeNode) && !dynamic?(attribute)
+
+          name = attribute_name_for(attribute)
+          return nil unless name && Herb::HTML::Util.boolean_attribute?(name)
+
+          condition = @states.condition_expression(node)
+          replacement = erb_output_node(%[("#{attribute_spacing(children, position)}#{name}" if #{condition})])
+
+          children[position] = replacement
+          record_slot(replacement, :attribute)
+
+          annotation = @annotation_of[replacement]
+          return nil unless annotation
+
+          annotation.type = :boolean_attribute
+          annotation.attribute = name
+          annotation.expression = condition
+
+          @attribute_open_tags[replacement] = open_tag
+
+          replacement
+        end
+
+        #: (untyped, untyped, Integer, untyped, Integer) -> void
+        def record_named_element(node, name_attribute, base, base_scope, base_depth)
+          name = static_attribute_value(name_attribute)
+
+          unless name && !name.empty?
+            return slot_error("`#{NAME_ATTRIBUTE}` on `<#{node.tag_name&.value}>` is computed or empty. A slot name is an address the browser looks up, so it has to be known before the page renders.", name_attribute.location, :name, suggestion: "Give it a static, non-empty value.")
+          end
+
+          candidates = @annotations[base..].to_a.select { |annotation|
+            annotation.scope.equal?(base_scope) && annotation.depth == base_depth && annotation.nameable?
+          }
+
+          @named_elements << {
+            node: node,
+            open_tag: node.open_tag,
+            attribute: name_attribute,
+            name: name,
+            candidates: candidates,
+            scope: base_scope,
+          }
+        end
+
+        #: (untyped) -> String?
+        def static_attribute_value(attribute)
+          children = attribute.value&.children || []
+
+          return nil unless children.all?(Herb::AST::LiteralNode)
+
+          children.map { |child| child.content.to_s }.join.strip
+        end
+
+        #: () -> void
+        def apply_names
+          taken = {} #: Hash[untyped, Hash[String, Annotation]]
+
+          @named_elements.each { |named| bind_name(named, taken[named[:scope]] ||= {}) }
+        end
+
+        #: (Hash[Symbol, untyped], Hash[String, Annotation]) -> void
+        def bind_name(named, scope_names)
+          name = named[:name] #: String
+          annotation = resolve_named_slot(named)
+
+          return unless annotation
+
+          if scope_names.key?(name)
+            return slot_error("Two slots in the same scope are both named `#{name}`. A slot name is an address, and two slots cannot share one.", name_location(named), :name, suggestion: "Give one of them a different name.")
+          end
+
+          if (existing = annotation.name)
+            return slot_error("`#{NAME_ATTRIBUTE}=\"#{name}\"` claims the slot already named `#{existing}`. Both elements hold the same slot.", name_location(named), :name, suggestion: "Keep one of the two names, or wrap what each should address in its own element.")
+          end
+
+          if attribute_conflict?(name, annotation, named[:scope])
+            return slot_error("The name `#{name}` collides with the `#{name}` attribute slot in the same scope. An attribute slot is already addressable by its attribute.", name_location(named), :name, suggestion: "Drop the name, or rename it.")
+          end
+
+          scope_names[name] = annotation
+
+          annotation.name = name
+        end
+
+        #: (Hash[Symbol, untyped]) -> Annotation?
+        def resolve_named_slot(named)
+          name = named[:name]
+          tag = named[:node].tag_name&.value
+          candidates = named[:candidates].reject(&:dropped).map(&:survivor).uniq
+
+          if candidates.empty?
+            return slot_error("`#{NAME_ATTRIBUTE}=\"#{name}\"` on `<#{tag}>` names no slot, since the element holds nothing dynamic.", name_location(named), :name, suggestion: "Move the name onto an element that wraps an ERB output, or remove it.")
+          end
+
+          unless candidates.one?
+            return slot_error("`#{NAME_ATTRIBUTE}=\"#{name}\"` on `<#{tag}>` is ambiguous between #{candidates.size} slots.", name_location(named), :name, suggestion: "Wrap the one it should name in its own element.")
+          end
+
+          candidates.fetch(0)
+        end
+
+        #: (Hash[Symbol, untyped]) -> Herb::Location?
+        def name_location(named)
+          named[:attribute]&.location || named[:node]&.location
+        end
+
+        #: (String, Annotation, untyped) -> bool
+        def attribute_conflict?(name, annotation, scope)
+          @annotations.any? { |other|
+            !other.gone? && other.attribute == name && !other.equal?(annotation) && other.scope.equal?(scope)
+          }
+        end
+
+        #: (untyped) -> void
+        def detect_keyed_elements(node)
+          iteration = node.is_a?(Herb::AST::ERBIterationBlockNode) || node.is_a?(Herb::AST::ERBForNode) || node.is_a?(Herb::AST::ERBWhileNode) || node.is_a?(Herb::AST::ERBUntilNode)
+
+          BRANCH_BODY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            array = node.send(property)
+
+            next unless array.is_a?(Array)
+
+            sole_element = iteration && array.grep(Herb::AST::HTMLElementNode).one?
+
+            array.each do |child|
+              detect_keyed_elements(child)
+
+              next unless child.is_a?(Herb::AST::HTMLElementNode)
+              next if sole_element
+
+              expression = keyed_element_expression(child)
+
+              next unless expression
+
+              remove_herb_key_attribute(child)
+
+              @keyed_elements[child] = expression
+            end
+          end
+        end
+
+        #: (untyped) -> String?
+        def keyed_element_expression(element)
+          attribute = attributes_for(element).find { |candidate| attribute_name_for(candidate)&.downcase == KEY_ATTRIBUTE }
+
+          return nil unless attribute
+
+          key_expression_for(attribute)
+        end
+
+        #: (untyped) -> void
+        def remove_herb_key_attribute(element)
+          open_tag = element.open_tag
+
+          return unless OPEN_TAG_TYPES.any? { |type| open_tag.is_a?(type) }
+
+          children = open_tag.children
+          at = children.index { |child| attribute_name_for(child)&.downcase == KEY_ATTRIBUTE }
+
+          return unless at
+
+          children.delete_at(at)
+          children.delete_at(at - 1) if at.positive? && children[at - 1].is_a?(Herb::AST::WhitespaceNode)
+        end
+
+        #: (untyped, Symbol) -> [Symbol?, String?]
+        def keys_for(node, type)
+          return key_for(node) if type == :collection
+          return [:herb_key, @keyed_elements.fetch(node)] if type == :keyed
+
+          [nil, nil]
+        end
+
+        #: (untyped) -> [Symbol, String?]
+        def key_for(node)
+          body = collection_body(node)
+
+          directive = key_directive_in(body)
+          return [:directive, directive] if directive
+
+          elements = body.grep(Herb::AST::HTMLElementNode)
+          return [:index, nil] unless elements.one?
+
+          attributes = attributes_for(elements.first)
+
+          [KEY_ATTRIBUTE, "id"].each do |name|
+            attribute = attributes.find { |candidate| attribute_name_for(candidate)&.downcase == name }
+            next unless attribute
+
+            expression = key_expression_for(attribute)
+            next unless expression
+
+            return [name == KEY_ATTRIBUTE ? :herb_key : :id, expression]
+          end
+
+          [:index, nil]
+        end
+
+        #: (untyped) -> String?
+        def keyable_tag_name_for(node)
+          elements = collection_body(node).grep(Herb::AST::HTMLElementNode)
+          return nil unless elements.one?
+
+          elements.first.tag_name&.value&.downcase
+        end
+
+        #: (Array[untyped]) -> String?
+        def key_directive_in(body)
+          body.each do |child|
+            next unless child.is_a?(Herb::AST::HerbDirectiveNode)
+            next unless child.directive == "key"
+
+            expression = child.argument
+
+            return expression unless expression.empty?
+          end
+
+          nil
+        end
+
+        #: (untyped) -> String?
+        def key_expression_for(attribute)
+          parts = key_parts_for(attribute)
+
+          return nil if parts.nil?
+          return nil unless parts.any? { |kind, _| kind == :expression }
+          return parts.first[1] if parts.one?
+
+          interpolated = parts.map { |kind, value|
+            kind == :expression ? "\#{#{value}}" : escape_key_literal(value)
+          }
+
+          %("#{interpolated.join}")
+        end
+
+        #: (untyped) -> Array[[Symbol, String]]?
+        def key_parts_for(attribute)
+          children = attribute.value&.children || []
+          return nil if children.empty?
+
+          children.map { |child|
+            case child
+            when Herb::AST::ERBContentNode
+              expression = child.content&.value.to_s.strip
+              return nil if expression.empty?
+
+              [:expression, expression]
+            when Herb::AST::LiteralNode
+              [:literal, child.content.to_s]
+            when Herb::AST::RubyLiteralNode
+              expression = child.content.to_s.strip
+              return nil if expression.empty?
+
+              [:expression, expression]
+            else
+              return nil
+            end
+          }
+        end
+
+        #: (String) -> String
+        def escape_key_literal(literal)
+          literal.gsub(/["\\]|\#\{/) { |match| "\\#{match}" }
+        end
+
+        #: (untyped) -> Array[untyped]
+        def collection_body(node)
+          BRANCH_BODY_PROPERTIES.filter_map { |property|
+            node.send(property) if node.respond_to?(property)
+          }.flatten
+        end
+
+        #: (untyped) -> Array[Herb::AST::HTMLAttributeNode]
+        def attributes_for(element)
+          open_tag = element.open_tag
+          return [] unless OPEN_TAG_TYPES.any? { |type| open_tag.is_a?(type) }
+
+          open_tag.children.grep(Herb::AST::HTMLAttributeNode)
+        end
+
+        #: (untyped) -> String?
+        def attribute_name_for(node)
+          return nil unless node.is_a?(Herb::AST::HTMLAttributeNode)
+
+          children = node.name&.children || []
+
+          return nil if children.empty?
+          return nil unless children.all?(Herb::AST::LiteralNode)
+
+          children.filter_map { |child| child.content if child.respond_to?(:content) }.join
+        end
+
+        #: (untyped) -> bool
+        def dynamic?(node)
+          return true if node.type.to_s.start_with?("AST_ERB_")
+          return true if node.is_a?(Herb::AST::RubyLiteralNode)
+
+          node.compact_child_nodes.any? { |child| dynamic?(child) }
+        end
+
+        def expression_for(node)
+          return attribute_expression_for(node) if node.is_a?(Herb::AST::HTMLAttributeNode)
+          return rcdata_expression_for(node) if node.is_a?(Herb::AST::HTMLElementNode)
+          return nil unless node.respond_to?(:content)
+
+          content = node.content
+          value = content.respond_to?(:value) ? content.value : content
+
+          value&.to_s&.strip
+        end
+
+        #: (untyped) -> String?
+        def attribute_expression_for(node)
+          children = node.value&.children || []
+          literal = children.grep(Herb::AST::RubyLiteralNode)
+
+          return literal.fetch(0).content.to_s.strip if literal.one? && children.one?
+          return nil unless children.all? { |child| child.is_a?(Herb::AST::LiteralNode) || child.is_a?(Herb::AST::ERBContentNode) }
+
+          outputs = children.grep(Herb::AST::ERBContentNode)
+
+          return nil unless outputs.one?
+          return nil unless erb_outputs?(outputs.fetch(0))
+
+          outputs.fetch(0).content&.value&.strip
+        end
+
+        #: (untyped, ?Symbol) -> untyped
+        def insert_markers(node, namespace = :html)
+          anchored = content_anchor_index(node)
+          namespace = Markers.namespace_within(namespace, node.tag_name&.value&.downcase.to_s) if node.is_a?(Herb::AST::HTMLElementNode)
+
+          each_child_array(node, namespace) do |array|
+            index = 0
+
+            while index < array.size
+              child = array[index]
+              slot_index = @standing[child]&.survivor&.index
+
+              insert_markers(child, namespace)
+              wrap_items(child, slot_index, namespace)
+              mark_branches(child, slot_index, namespace)
+
+              if slot_index && slot_index != anchored
+                if @slots[slot_index].type == :keyed
+                  park_keyed(slot_index, child, namespace)
+
+                  array.insert(
+                    index,
+                    text_node(@markers.keyed_open_prefix(slot_index)),
+                    erb_code_node("#{@bufvar} << ::Herb::Engine.raw((#{@slots[slot_index].key_expression}).to_s)"),
+                    text_node(@markers.keyed_open_suffix)
+                  )
+                  array.insert(index + 4, comment_node(@markers.slot_close(slot_index)))
+
+                  index += 5
+                else
+                  array.insert(index, comment_node(@markers.slot_open(slot_index, @slots[slot_index].type)))
+                  array.insert(index + 2, comment_node(@markers.slot_close(slot_index)))
+
+                  index += 3
+                end
+              else
+                index += 1
+              end
+            end
+          end
+
+          anchor_attributes(node, anchored)
+        end
+
+        #: (untyped) -> Integer?
+        def content_anchor_index(node)
+          return nil unless node.is_a?(Herb::AST::HTMLElementNode)
+
+          body = node.body
+          return nil unless body.is_a?(Array) && body.size == 1
+
+          annotation = @standing[body[0]]&.survivor
+          return nil unless annotation
+          return nil unless annotation.type == :child
+          return nil if @render_bindings.key?(body[0])
+
+          annotation.index
+        end
+
+        #: (untyped, Integer?, ?Symbol) -> void
+        def mark_branches(node, slot_index, namespace = :html)
+          return unless slot_index
+          return unless @slots[slot_index].type == :conditional
+
+          branch_bodies(node).each_with_index do |body, branch_index|
+            marker = @markers.branch(slot_index, branch_index)
+
+            park_branch(@markers.statics_key(slot_index, branch_index), marker, body, namespace)
+
+            body.unshift(text_node(marker))
+          end
+        end
+
+        #: (String, String, Array[untyped], Symbol) -> void
+        def park_branch(key, marker, body, namespace)
+          statics = @statics
+          return unless statics
+
+          markup = Statics.new(@standing).markup(body)
+          return unless markup
+
+          statics[key] = "#{marker}#{@markers.foreign(markup, namespace)}"
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def append_statics(document_node)
+          return unless client?
+
+          statics = @statics
+          entries = (statics || {}).sort_by { |key, _| key.split(":").map(&:to_i) } #: Array[[String, (String | Array[untyped])]]
+
+          withheld = deferred_entries.keys.to_set { |index| "#{index}:0" }
+          entries.reject! { |key, _| withheld.include?(key) }
+
+          entries.concat(fallback_statics_entries)
+
+          return if entries.empty?
+
+          seen = entries.map { |key, _| "#{COVERED}[#{covered_key(key).inspect}]" }.join(" && ")
+
+          nodes = [
+            erb_code_node("unless #{seen}"),
+            text_node(@markers.statics_open(identifier, version))
+          ] #: Array[Herb::AST::Node]
+
+          entries.each do |key, parked|
+            reference = "#{COVERED}[#{covered_key(key).inspect}]"
+
+            nodes.push(erb_code_node("unless #{reference}"))
+
+            if parked.is_a?(String)
+              nodes.push(text_node(parked))
+            else
+              nodes.concat(parked)
+            end
+
+            nodes.push(erb_code_node("#{reference} = true"), erb_code_node("end"))
+          end
+
+          nodes.push(text_node(@markers.statics_close), erb_code_node("end"))
+
+          document_node.children.unshift(erb_code_node("#{COVERED} ||= {}"))
+          document_node.children.concat(nodes)
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def expose_fallbacks(document_node)
+          return if @fragment_fallbacks.empty?
+
+          @exposed_fallbacks = @fragment_fallbacks.each_value.flat_map { |body| body } #: Array[untyped]
+
+          document_node.children.concat(@exposed_fallbacks)
+
+          nil
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def withdraw_fallbacks(document_node)
+          exposed = @exposed_fallbacks
+
+          return if exposed.empty?
+
+          document_node.children.reject! { |child| exposed.any? { |node| node.equal?(child) } }
+          @exposed_fallbacks = [] #: Array[untyped]
+
+          nil
+        end
+
+        #: () -> Array[[String, Array[untyped]]]
+        def fallback_statics_entries
+          @fragment_fallbacks.filter_map { |node, body|
+            index = @indices[node]
+
+            next unless index
+
+            [@markers.statics_key(index, 1), [text_node(@markers.branch(index, 1)), *marked_fallback(body)]]
+          }
+        end
+
+        #: (Array[untyped]) -> Array[untyped]
+        def marked_fallback(children)
+          children.flat_map do |child|
+            insert_markers(child)
+
+            slot_index = @standing[child]&.survivor&.index
+
+            next [child] unless slot_index
+
+            [
+              comment_node(@markers.slot_open(slot_index, @slots[slot_index].type)),
+              child,
+              comment_node(@markers.slot_close(slot_index))
+            ]
+          end
+        end
+
+        #: (String) -> String
+        def covered_key(key)
+          "#{identifier}:#{key}"
+        end
+
+        #: (untyped) -> Array[Array[Herb::AST::Node]]
+        def branch_bodies(node)
+          bodies = [] #: Array[Array[Herb::AST::Node]]
+
+          if node.respond_to?(:conditions)
+            node.conditions.each { |arm| bodies << arm.statements if arm.respond_to?(:statements) }
+          elsif node.respond_to?(:statements)
+            bodies << node.statements
+          end
+
+          current = continuation_of(node) #: untyped
+
+          while (branch = current)
+            bodies << branch.statements if branch.respond_to?(:statements)
+
+            current = continuation_of(branch)
+          end
+
+          bodies
+        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
+
+          BRANCH_BODY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            body = node.send(property)
+            next unless body.is_a?(Array) && !body.empty?
+
+            key = @markers.item_statics_key(slot_index)
+            parked = park_item(key, body, namespace)
+
+            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)
+            )
+
+            body.insert(3, erb_code_node(%(#{COVERED}[#{covered_key(key).inspect}] = true))) if parked && client?
+
+            body.push(text_node(@markers.item_close(slot_index)))
+          end
+        end
+
+        #: (untyped) -> Array[String]?
+        def attribute_segments(node)
+          segments = [+""]
+
+          (node.value&.children || []).each do |child|
+            case child
+            when Herb::AST::LiteralNode
+              segments.last << child.content.to_s
+            when Herb::AST::ERBContentNode
+              return nil unless erb_outputs?(child)
+
+              segments << +""
+            when Herb::AST::ERBIfNode, Herb::AST::ERBUnlessNode, Herb::AST::ERBCaseNode
+              segments << +""
+            else
+              return nil
+            end
+          end
+
+          segments.size > 1 ? segments : nil
+        end
+
+        #: (Integer, untyped, Symbol) -> void
+        def park_keyed(slot_index, element, namespace)
+          statics = @statics
+          return unless statics
+
+          markup = Statics.new(@standing).markup([element.open_tag, *element.body, element.close_tag].compact)
+          return unless markup
+
+          statics[@markers.item_statics_key(slot_index)] = "#{@markers.branch(slot_index, Markers::ITEM_STATICS)}#{@markers.foreign(markup, namespace)}"
+        end
+
+        #: (untyped, untyped, Symbol) -> Array[untyped]?
+        def park_item(key, body, namespace)
+          statics = @statics
+          return unless statics
+
+          slot_index = key.split(":").first.to_i
+          markup = Statics.new(@standing).markup(body)
+          return unless markup
+
+          item = [
+            @markers.item_open_prefix(slot_index),
+            @markers.item_open_suffix,
+            markup,
+            @markers.item_close(slot_index)
+          ].join
+
+          statics[key] = "#{@markers.branch(slot_index, Markers::ITEM_STATICS)}#{@markers.foreign(item, namespace)}"
+        end
+
+        def anchor_attributes(node, content_index = nil)
+          return unless node.is_a?(Herb::AST::HTMLElementNode)
+
+          open_tag = node.open_tag
+          targets = open_tags_for(open_tag)
+
+          return if targets.empty?
+
+          anchors = (@element_anchored[open_tag] || []).map { |annotation|
+            slot = @slots.fetch(annotation.survivor.index)
+
+            [slot.index, slot.type, anchor_name_for(slot)]
+          }
+
+          anchors << [content_index, :child, nil] if content_index
+
+          return if anchors.empty?
+
+          value = @markers.element_anchors(anchors)
+
+          targets.each { |target| target.children << attribute_node("data-herb-slot", value) }
+        end
+
+        #: (Slot) -> String?
+        def anchor_name_for(slot)
+          name = slot.attribute
+
+          return nil if name.nil? || name.include?(",")
+
+          name
+        end
+
+        #: (Herb::AST::Node, ?Symbol) { (Array[untyped]) -> void } -> void
+        def each_child_array(node, namespace = :html)
+          BRANCH_BODY_PROPERTIES.each do |property|
+            next unless node.respond_to?(property)
+
+            array = node.send(property)
+            yield array if array.is_a?(Array)
+          end
+
+          (BRANCH_CONTINUATION_PROPERTIES + [:end_node, :open_tag]).each do |property|
+            next unless node.respond_to?(property)
+
+            child = node.send(property)
+            insert_markers(child, namespace) if child
+          end
+        end
+
+        #: (Herb::AST::DocumentNode) -> void
+        def wrap_region(document_node)
+          document_node.children.unshift(
+            erb_code_node("#{OCCURRENCE} = #{occurrence_expression}"),
+            *region_open
+          )
+
+          document_node.children.push(comment_node(@markers.region_close(identifier)))
+        end
+
+        #: () -> void
+        def wrap_displaced
+          @displaced.each do |node|
+            BRANCH_BODY_PROPERTIES.each do |property|
+              next unless node.respond_to?(property)
+
+              body = node.send(property)
+              next unless body.is_a?(Array) && !body.empty?
+
+              body.unshift(*region_open)
+              body.push(comment_node(@markers.region_close(identifier)))
+            end
+          end
+        end
+
+        def region_open
+          [
+            text_node(@markers.region_open_prefix(identifier, version)),
+            erb_output_node(OCCURRENCE),
+            text_node(@markers.region_open_suffix)
+          ]
+        end
+
+        def comment_node(text)
+          Herb::AST::HTMLCommentNode.build(
+            comment_start: token(:html_comment_start, text),
+            comment_end: token(:html_comment_end, "")
+          )
+        end
+
+        def attribute_node(name, value)
+          name_node = Herb::AST::HTMLAttributeNameNode.build(children: [literal(name)])
+
+          value_node = Herb::AST::HTMLAttributeValueNode.build(
+            open_quote: token(:quote, '"'),
+            children: [literal(value)],
+            close_quote: token(:quote, '"'),
+            quoted: true
+          )
+
+          Herb::AST::HTMLAttributeNode.build(name: name_node, equals: token(:equals, "="), value: value_node)
+        end
+
+        def literal(content)
+          Herb::AST::LiteralNode.build(content: content.dup)
+        end
+
+        def token(type, value)
+          Herb::Token.new(value.dup, Herb::Range.zero, Herb::Location.zero, type.to_s)
+        end
+      end
+    end
+  end
+end