liquid_xlsx 0.1.0

data/lib/liquid_xlsx/renderer.rb

@@ -0,0 +1,775 @@
+# frozen_string_literal: true
+
+require "date"
+
+module LiquidXlsx
+  # Renders a single worksheet by parsing the template AST and
+  # rebuilding the sheet data with Liquid-rendered values.
+  class Renderer # rubocop:disable Metrics/ClassLength
+    attr_reader :worksheet, :options
+    attr_accessor :sheet_r_id
+
+    # Pattern for a simple variable-only template (no filters, no mixed text).
+    SINGLE_VAR = /\A\{\{\s*([\w.]+)\s*\}\}\z/
+
+    # Maximum size of the per-renderer Liquid::Template parse cache.
+    # When exceeded the entire cache is cleared (simple FIFO-like eviction).
+    TEMPLATE_CACHE_MAX_SIZE = 512
+
+    # Epoch for Excel 1900 date system (accounts for the leap-year bug).
+    # Serial = days since this date. For dates after 1900-02-28 the spurious
+    # 1900-02-29 absorbs the one-day offset, producing correct serials for
+    # all modern dates.
+    # TODO: support 1904 date system if workbookPr/@date1904 is accessible.
+    #       Currently the Renderer has no access to package/workbook.xml;
+    #       when date1904 detection is added, switch epoch to Date.new(1904,1,1).
+    DATE_1900_EPOCH = Date.new(1899, 12, 30)
+    SECONDS_PER_DAY = 86_400.0
+    DATE_TIME_CLASSES = [Date, Time].freeze
+
+    def initialize(worksheet, options = {})
+      @worksheet = worksheet
+      @options = options
+      @template_cache = {}
+    end
+
+    # Render the worksheet with data.
+    #
+    # `data` may be a Hash, a Liquid::Drop, or any object responding to
+    # `#to_liquid` that returns a Hash or a Drop. Plain objects without `[]` /
+    # `#key?` are not supported because Liquid::Context looks variables up via
+    # these methods on the root environment.
+    #
+    # `extra_scope` adds variables that take priority over `data` (used by
+    # dynamic sheets to inject the per-op local variable without merging —
+    # which would otherwise require `data` to be a Hash). It is passed as the
+    # second argument of Liquid::Context, the outer scope, which has higher
+    # precedence than environments.
+    #
+    # @param data [Hash, Liquid::Drop, #to_liquid] data to render
+    # @param workbook_ops [Array] mutable array to collect {% sheet %} operations
+    # @param image_ops [Array] mutable array to collect {% image_tag %} operations
+    # @param extra_scope [Hash{String,Symbol=>Object}] extra variables with
+    #   priority over `data` (e.g. for dynamic sheets)
+    # @return [String] XML content of the rendered worksheet
+    def render(data, workbook_ops: nil, image_ops: nil, extra_scope: nil)
+      rows = worksheet.parse_rows
+      return worksheet.to_xml if rows.empty?
+
+      # Quick scan: skip sheet if no Liquid tags at all
+      has_tags = rows.any? do |r|
+        r[:cells].any? { |c| c[:template] }
+      end
+      return worksheet.to_xml unless has_tags
+
+      # Build AST
+      parser = TemplateParser.new(rows, worksheet.name)
+      ast = parser.parse
+
+      strict_vars = @options.fetch(:strict_variables, false)
+      strict_filts = @options.fetch(:strict_filters, false)
+
+      # One Liquid::Context per worksheet — shared across all cells.
+      # Normalize arbitrary #to_liquid objects (AR models, Struct, …) into a
+      # Hash or Drop the context can look variables up in. Hash and Drop pass
+      # through unchanged (Drop#to_liquid returns self).
+      normalized = normalize_data(data)
+      data_hash = stringify_keys(normalized)
+      registers = { liquid_xlsx_workbook_ops: workbook_ops,
+                    liquid_xlsx_image_ops: image_ops || [],
+                    liquid_xlsx_dynamic_sheets: @options.fetch(:dynamic_sheets, false),
+                    liquid_xlsx_sheet_name: @worksheet.name,
+                    liquid_xlsx_sheet_r_id: @sheet_r_id }
+      liquid_context = ::Liquid::Context.new(data_hash, {}, registers, true)
+      # `extra_scope` is applied AFTER context construction on purpose: passing
+      # it as the second (outer_scope) argument would let Liquid's
+      # `squash_instance_assigns_with_environments` (invoked at the end of
+      # `Context#initialize`) shadow each key with the corresponding value
+      # from the environment. For a Drop environment that is fatal, because
+      # `Drop#key?` always returns `true`, so unknown methods yield `nil` and
+      # overwrite the explicit extra variables. Assigning directly onto the
+      # context bypasses squash entirely and still wins lookup priority
+      # because scopes are searched before environments.
+      if extra_scope
+        stringify_keys(extra_scope).each do |k, v|
+          liquid_context[k] = v
+        end
+      end
+      liquid_context.strict_variables = strict_vars
+      liquid_context.strict_filters = strict_filts
+      apply_resource_limits(liquid_context)
+
+      # Get original merge cells
+      original_merges = worksheet.merge_cells
+      merge_transformer = MergeCellsTransformer.new
+
+      # Render AST to produce new rows + merge info
+      formula_translator = FormulaTranslator.new
+      state = RenderState.new(merge_transformer, original_merges, formula_translator)
+
+      rendered = render_ast(ast, liquid_context, data_hash, rows, strict_filts, state)
+
+      # Check for merge cells crossing structural block boundaries
+      state.check_block_boundaries(worksheet.name)
+
+      # Build merge ranges list
+      merge_ranges = state.build_merge_ranges
+
+      # Translate formulas now that all loop expansions are known
+      finalize_formulas(rendered, state.formula_translator)
+
+      # Rebuild sheet data (always: an empty result must clear template rows too)
+      worksheet.rebuild_sheet_data(rendered, 1)
+
+      # Update dimension
+      worksheet.update_dimension(rendered.length)
+
+      # Always update merge cells (clears old ones even if result is empty)
+      worksheet.update_merge_cells(merge_ranges)
+
+      # Remove cached formula values if recalculating
+      if @options[:recalculate_formulas]
+        worksheet.remove_cached_formula_values
+      end
+
+      worksheet.to_xml
+    end
+
+    private
+
+    def stringify_keys(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = stringify_value(v) }
+    end
+
+    def stringify_value(value)
+      case value
+      when Hash then stringify_keys(value)
+      when Array then value.map { |v| stringify_value(v) }
+      else value
+      end
+    end
+
+    # Normalize the root `data` argument into something Liquid::Context can
+    # look variables up in. Liquid::Context treats its first argument as an
+    # "environment" and calls `[]` / `key?` on it during lookup, so a plain
+    # object with only `#to_liquid` (but no `[]`) would raise NoMethodError.
+    # Hash and Liquid::Drop already satisfy the lookup contract and pass
+    # through unchanged; everything else that responds to `#to_liquid` is
+    # converted once at the boundary (AR models, Struct, OpenStruct, …).
+    def normalize_data(data)
+      return data if data.is_a?(Hash) || data.is_a?(::Liquid::Drop)
+      return data unless data.respond_to?(:to_liquid)
+
+      result = data.to_liquid
+      return result if result.is_a?(Hash) || result.is_a?(::Liquid::Drop)
+
+      raise RenderError,
+            "#to_liquid returned #{result.class}; " \
+            "expected a Hash or Liquid::Drop"
+    end
+
+    # Whether a numeric value can be written to OOXML `<v>` directly.
+    # Rational and Complex produce invalid numeric lexemes ("1/2", "1+2i"),
+    # and Float NaN/Infinity are not valid in OOXML either. Anything failing
+    # this check falls through to normal string rendering.
+    def numeric_for_excel?(value)
+      return false unless value.is_a?(Numeric)
+      return false if value.is_a?(Rational) || value.is_a?(Complex)
+      return false if value.respond_to?(:finite?) && !value.finite?
+
+      true
+    end
+
+    def render_ast(ast, liquid_context, data_hash, original_rows, strict_filters, state)
+      rendered_rows = []
+
+      ast.each do |node|
+        process_node(node, liquid_context, data_hash, rendered_rows, original_rows,
+                     strict_filters, state)
+      end
+
+      rendered_rows
+    end
+
+    def process_node(node, liquid_context, data_hash, rendered_rows, original_rows,
+                     strict_filters, state)
+      case node
+      when Nodes::RowNode
+        template_row_num = node.row_data[:row_number]
+        new_row_num = rendered_rows.length + 1
+
+        cells = render_row_cells(node, liquid_context, data_hash, state,
+                                 new_row_num)
+
+        # Build row info hash preserving original attributes
+        row_info = {
+          cells: cells,
+          original_row_num: template_row_num,
+          row_attrs: node.row_data[:row_attrs]
+        }
+        rendered_rows << row_info
+
+        # Record merge cells for this row
+        state.record_row(template_row_num, new_row_num)
+      when Nodes::ForNode
+        collection = resolve_for_collection(liquid_context, data_hash, node)
+
+        if collection.empty? && node.else_body
+          state.enter_block(:for_else, node.for_row, node.endfor_row)
+          node.else_body.each do |child|
+            process_node(child, liquid_context, data_hash, rendered_rows, original_rows,
+                         strict_filters, state)
+          end
+          state.leave_block
+          return
+        end
+
+        # Record block boundary using TEMPLATE row numbers
+        state.enter_block(:for, node.for_row, node.endfor_row)
+        state.start_loop
+
+        collection.each_with_index do |item, index|
+          state.start_iteration(index)
+
+          liquid_context.stack do
+            liquid_context[node.variable_name] = stringify_value(item)
+            liquid_context["forloop"] = {
+              "index" => index + 1,
+              "index0" => index,
+              "first" => index == 0,
+              "last" => index == collection.length - 1,
+              "length" => collection.length
+            }
+
+            node.body.each do |child|
+              process_node(child, liquid_context, data_hash, rendered_rows, original_rows,
+                           strict_filters, state)
+            end
+          end
+
+          state.end_iteration
+        end
+
+        execution_rows = state.end_loop
+        expansion_path = state.current_path
+
+        # Recursively collect all RowNode template rows, including those
+        # inside nested IfNode / ForNode bodies.
+        body_template_rows = collect_body_rows(node.body)
+        if body_template_rows.any?
+          rows_map = body_template_rows.to_h { |t| [t, execution_rows[t] || []] }
+          state.formula_translator.register_expansion(
+            rows: rows_map,
+            block_first: node.for_row,
+            block_last: node.endfor_row,
+            path: expansion_path
+          )
+        end
+
+        state.leave_block
+      when Nodes::IfNode
+        state.enter_block(:if, node.if_row, node.endif_row)
+
+        node.branches.each do |branch|
+          if branch[:condition].nil?
+            # else branch
+            branch[:body].each do |child|
+              process_node(child, liquid_context, data_hash, rendered_rows, original_rows,
+                           strict_filters, state)
+            end
+            state.leave_block
+            return
+          end
+
+          condition_result = evaluate_condition(branch[:condition], liquid_context, node.if_row)
+          next unless condition_result
+
+          branch[:body].each do |child|
+            process_node(child, liquid_context, data_hash, rendered_rows, original_rows,
+                         strict_filters, state)
+          end
+          state.leave_block
+          return
+        end
+
+        state.leave_block
+      end
+    end
+
+    # Recursively collect template row numbers of all RowNode descendants
+    # in a list of AST nodes, including those inside nested IfNode branches
+    # and ForNode bodies.
+    def collect_body_rows(nodes)
+      nodes.flat_map do |child|
+        case child
+        when Nodes::RowNode
+          [child.row_data[:row_number]]
+        when Nodes::ForNode
+          rows = collect_body_rows(child.body)
+          rows += collect_body_rows(child.else_body) if child.else_body
+          rows
+        when Nodes::IfNode
+          child.branches.flat_map { |branch| collect_body_rows(branch[:body]) }
+        else
+          []
+        end
+      end
+    end
+
+    def resolve_collection(liquid_context, _data_hash, path)
+      safe_context_lookup(liquid_context, path)
+    end
+
+    # Resolve and validate a for-loop collection. nil becomes an empty
+    # collection; non-Enumerable values raise a clear error instead of a raw
+    # NoMethodError on #each.
+    #
+    # In strict-variables mode the collection name is looked up through a
+    # raw Liquid::Context#[] call so that UndefinedVariable /
+    # UndefinedDropMethod errors propagate (and are converted to
+    # MissingVariableError). A defined variable whose value is nil produces
+    # an empty loop — it is NOT treated as a missing variable.
+    # In lenient mode the safe lookup path is used (errors are swallowed
+    # and nil is returned, yielding an empty loop).
+    def resolve_for_collection(liquid_context, data_hash, node)
+      collection = if liquid_context.strict_variables
+                     strict_collection_lookup(liquid_context, node)
+                   else
+                     resolve_collection(liquid_context, data_hash, node.collection_name)
+                   end
+      return [] if collection.nil?
+      return collection if collection.is_a?(Array)
+
+      raise RenderError.new(
+        "Cannot iterate over #{collection.class} " \
+        "in '{% for #{node.variable_name} in #{node.collection_name} %}': " \
+        "expected an Array (list).",
+        sheet: @worksheet.name,
+        row: node.for_row
+      )
+    end
+
+    # Look up a for-loop collection name in strict mode. Liquid::Context#[]
+    # resolves Drops, loop variables and {% assign %} in a single pass and
+    # raises UndefinedVariable / UndefinedDropMethod when the variable is
+    # genuinely absent under strict_variables. We catch those and convert
+    # them to a MissingVariableError with sheet/row/template context.
+    # Defined-variable-with-nil-value returns nil (no exception) — nil
+    # becomes an empty loop just like in lenient mode.
+    def strict_collection_lookup(liquid_context, node)
+      liquid_context[node.collection_name]
+    rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod => e
+      raise MissingVariableError.new(
+        "Missing variable in for-loop: #{e.message}",
+        sheet: @worksheet.name,
+        row: node.for_row,
+        template: "{% for #{node.variable_name} in #{node.collection_name} %}"
+      )
+    end
+
+    def evaluate_condition(condition, liquid_context, row_num = nil)
+      template_text = "{% if #{condition} %}true{% endif %}"
+      template = cached_parse(template_text)
+      result = template.render(liquid_context)
+      result.strip == "true"
+    rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod => e
+      raise MissingVariableError.new(
+        "Missing variable in condition: #{e.message}",
+        sheet: @worksheet.name,
+        row: row_num,
+        template: "{% if #{condition} %}"
+      )
+    rescue Liquid::Error => e
+      raise RenderError.new(
+        "Liquid error in condition: #{e.message}",
+        sheet: @worksheet.name,
+        row: row_num,
+        template: "{% if #{condition} %}"
+      )
+    end
+
+    # Apply optional Liquid resource limits from options[:liquid_resource_limits].
+    def apply_resource_limits(liquid_context)
+      limits = @options[:liquid_resource_limits]
+      return unless limits.is_a?(Hash)
+
+      rl = liquid_context.resource_limits
+      rl.render_length_limit = limits[:render_length_limit] if limits[:render_length_limit]
+      rl.render_score_limit = limits[:render_score_limit] if limits[:render_score_limit]
+      rl.assign_score_limit = limits[:assign_score_limit] if limits[:assign_score_limit]
+    end
+
+    # Translate all pending formulas once every loop expansion is registered.
+    # This must run after the full AST walk: formulas above a loop would
+    # otherwise be translated before the loop's expansion is known.
+    def finalize_formulas(rendered_rows, translator)
+      rendered_rows.each do |row_info|
+        next unless row_info
+
+        (row_info[:cells] || []).each do |cell|
+          next unless cell && cell[:formula] && cell[:formula_row_delta]
+
+          template_row = cell[:formula_template_row]
+          copied = translator.copied_row?(template_row)
+          cell[:formula] = translator.translate(
+            cell[:formula], cell[:formula_row_delta], 0,
+            template_row: template_row, copied: copied,
+            formula_path: cell[:formula_path] || []
+          )
+          next unless (attrs = cell[:formula_attrs]) && attrs["ref"]
+
+          attrs = cell[:formula_attrs] = attrs.dup
+          attrs["ref"] = translator.translate(
+            attrs["ref"], cell[:formula_row_delta], 0,
+            template_row: template_row, copied: copied,
+            formula_path: cell[:formula_path] || []
+          )
+        end
+      end
+    end
+
+    def render_row_cells(node, liquid_context, data_hash, state, new_row_num)
+      cells = node.row_data[:cells]
+      return [] unless cells
+
+      template_row_num = node.row_data[:row_number]
+
+      cells.map do |cell_data|
+        result = cell_data.dup
+
+        # Set anchor coordinates for {% image_tag %} (render row/col)
+        # These are set for EVERY cell so image_tag picks them up
+        liquid_context.registers[:liquid_xlsx_anchor_row] = new_row_num
+        liquid_context.registers[:liquid_xlsx_anchor_col] = cell_data[:col]
+        liquid_context.registers[:liquid_xlsx_template_anchor_row] = template_row_num
+
+        if cell_data[:formula]
+          # Defer translation until all loop expansions are registered
+          # (see #finalize_formulas).
+          result[:formula_row_delta] = new_row_num - template_row_num
+          result[:formula_template_row] = template_row_num
+          result[:formula_path] = state.current_path
+          result[:original_type] = cell_data[:type]
+          result[:inline_str] = false
+          result[:template] = nil
+        elsif cell_data[:template]
+          rendered = render_cell_template(cell_data, liquid_context, data_hash, template_row_num)
+          result[:rendered_value] = rendered
+          # Preserve numeric/boolean types: don't set inlineStr for them.
+          # Non-finite floats (NaN/Infinity) cannot be written as numbers.
+          # Date/Time values are converted to numeric serials in the fast path,
+          # so they also flow through as Numeric here.
+          numeric = rendered.is_a?(Numeric) &&
+                    !(rendered.is_a?(Float) && !rendered.finite?)
+          result[:inline_str] = !(numeric ||
+                                  rendered.is_a?(TrueClass) ||
+                                  rendered.is_a?(FalseClass))
+          result[:type] = nil
+          result[:template] = nil
+        else
+          # Non-template cell: preserve original content with type intact
+          if cell_data[:type] == "inlineStr"
+            result[:rendered_value] = cell_data[:text]
+            result[:inline_str] = true
+          elsif cell_data[:type] == "s"
+            # Keep as shared string reference (no change needed)
+            result[:inline_str] = false
+          elsif cell_data[:value]
+            # Plain value cell (numeric, boolean, raw) — preserve value and type
+            result[:original_value] = cell_data[:value]
+            result[:original_type] = cell_data[:type]
+            result[:inline_str] = false
+          end
+        end
+
+        result
+      end
+    end
+
+    # Render a cell template through the shared Liquid::Context.
+    # Tries to preserve numeric/boolean/date types when possible.
+    def render_cell_template(cell_data, liquid_context, _data_hash, row_num)
+      template_text = cell_data[:template]
+      cell_ref = "#{cell_data[:col]}#{row_num}"
+
+      # For simple {{ var }} templates without filters, try direct extraction
+      # to preserve numeric/boolean/date types for Excel. `safe_context_lookup`
+      # resolves Drops, `to_liquid`, loop variables and `{% assign %}` in a
+      # single pass through Liquid::Context (which respects scope priority),
+      # so a hand-rolled Hash fallback is neither needed nor correct for
+      # non-Hash data. See `numeric_for_excel?` for why some Numeric subtypes
+      # are deliberately routed through normal rendering.
+      var_match = template_text.strip.match(SINGLE_VAR)
+      if var_match
+        ctx_val = safe_context_lookup(liquid_context, var_match[1])
+        return ctx_val if numeric_for_excel?(ctx_val)
+        return ctx_val if ctx_val.is_a?(TrueClass) || ctx_val.is_a?(FalseClass)
+        return date_time_to_serial(ctx_val) if date_time?(ctx_val)
+      end
+
+      # Render through shared Liquid context
+      begin
+        # Set source coordinates for {% sheet %} tag error reporting in registers
+        liquid_context.registers[:liquid_xlsx_source_row] = row_num
+        liquid_context.registers[:liquid_xlsx_source_cell] = cell_ref
+
+        template = cached_parse(template_text)
+        rendered = template.render(liquid_context)
+      rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod => e
+        raise MissingVariableError.new(
+          "Missing variable: #{e.message}",
+          sheet: @worksheet.name,
+          row: row_num,
+          cell: cell_ref,
+          template: template_text
+        )
+      rescue Liquid::Error => e
+        raise RenderError.new(
+          "Liquid render error: #{e.message}",
+          sheet: @worksheet.name,
+          row: row_num,
+          cell: cell_ref,
+          template: template_text
+        )
+      end
+
+      coerce_value(rendered)
+    end
+
+    # Look up a variable in Liquid context, suppressing strict-variable errors.
+    # Returns nil if the variable is undefined (used for type-preserving fast
+    # path). Catches both `UndefinedVariable` (missing Hash key) and
+    # `UndefinedDropMethod` (missing Drop method under `strict_variables`) —
+    # these are sibling subclasses of Liquid::Error, not a parent/child pair,
+    # so both must be listed explicitly.
+    def safe_context_lookup(liquid_context, path)
+      liquid_context[path]
+    rescue Liquid::UndefinedVariable, Liquid::UndefinedDropMethod
+      nil
+    end
+
+    def coerce_value(value)
+      return value.to_s if value.nil?
+      return value if value.is_a?(Integer) || value.is_a?(Float)
+      return value if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+      return value if value.is_a?(Date) || value.is_a?(Time)
+
+      value.to_s
+    end
+
+    # -------------------------------------------------------------------
+    # Template cache — avoids re-parsing identical Liquid templates.
+    # Liquid::Template instances are stateless after compilation; the
+    # same instance can be safely rendered against different contexts.
+    # `strict_variables` / `strict_filters` are context-level settings
+    # (set on @liquid_context, lines 80-81), not template-level.
+    # `environment` (LiquidXlsx.liquid_environment) carries only tag
+    # registries and is identical for every cell/condition parse.
+    # -------------------------------------------------------------------
+
+    # Parse or fetch from cache a Liquid::Template for the given text.
+    # When the cache exceeds TEMPLATE_CACHE_MAX_SIZE, the entire cache is
+    # cleared on the next miss (simple eviction — fast path templates are
+    # few and conditions even fewer for typical workbooks).
+    def cached_parse(template_text)
+      if @template_cache.size >= TEMPLATE_CACHE_MAX_SIZE && !@template_cache.key?(template_text)
+        @template_cache.clear
+      end
+      @template_cache[template_text] ||= ::Liquid::Template.parse(template_text,
+                                                                  environment: LiquidXlsx.liquid_environment)
+    end
+
+    # -------------------------------------------------------------------
+    # Date / Time → Excel serial number conversion (1900 date system).
+    # Uses local time as-is via #to_time (no timezone adjustment).
+    # Serial = integer days + fractional day (seconds / 86_400).
+    # The style (s=) from the template cell is preserved, so if the
+    # template has a date format applied, Excel displays the serial
+    # correctly as a date.
+    # -------------------------------------------------------------------
+
+    def date_time?(value)
+      DATE_TIME_CLASSES.any? { |klass| value.is_a?(klass) }
+    end
+
+    def date_time_to_serial(value)
+      time = value.to_time
+      days = (time.to_date - DATE_1900_EPOCH).to_i
+      fraction = ((time.hour * 3600) + (time.min * 60) + time.sec +
+                  (time.nsec / 1_000_000_000.0)) / SECONDS_PER_DAY
+      serial = days + fraction
+      serial == serial.to_i ? serial.to_i : serial
+    rescue NoMethodError
+      value
+    end
+  end
+
+  # Tracks merge cells, formula expansions, and block boundaries.
+  class RenderState
+    attr_reader :formula_translator
+
+    def initialize(merge_transformer, original_merges, formula_translator)
+      @merge_transformer = merge_transformer
+      @original_merges = original_merges
+      @formula_translator = formula_translator
+
+      # Map: template_row_num => [new_row_num, ...] (multiple for loop iterations)
+      @row_map = {}
+      # Structural block boundaries (template row numbers) for merge crossing detection
+      @blocks = []
+      # Current loop state
+      # Each frame: { iterations: [...], current_iteration: {row_map: {}, index:} or nil }
+      @loop_stack = []
+    end
+
+    def record_row(template_row_num, new_row_num)
+      @row_map[template_row_num] ||= []
+      @row_map[template_row_num] << new_row_num
+
+      # Also write to all active per-iteration row maps for later aggregation
+      @loop_stack.each do |frame|
+        iter = frame[:current_iteration]
+        next unless iter
+
+        iter[:row_map][template_row_num] ||= []
+        iter[:row_map][template_row_num] << new_row_num
+      end
+    end
+
+    def enter_block(type, for_row, endfor_row)
+      @blocks << { type: type, start: for_row, end: endfor_row } if for_row && endfor_row
+    end
+
+    def leave_block
+      # Block already recorded in enter_block
+    end
+
+    def start_loop
+      @loop_stack.push(iterations: [], current_iteration: nil)
+    end
+
+    def start_iteration(index)
+      @loop_stack.last[:current_iteration] = { row_map: {}, index: index }
+    end
+
+    def end_iteration
+      @loop_stack.last[:iterations] << @loop_stack.last[:current_iteration]
+      @loop_stack.last[:current_iteration] = nil
+    end
+
+    # Aggregate per-iteration row maps of the current loop execution into
+    # a single {template_row => [rendered_row, ...]} hash and pop the frame.
+    def end_loop
+      frame = @loop_stack.pop
+      aggregate = {}
+      frame[:iterations].each do |iter|
+        iter[:row_map].each do |t_row, r_rows|
+          aggregate[t_row] ||= []
+          aggregate[t_row].concat(r_rows)
+        end
+      end
+      aggregate
+    end
+
+    # Current iteration path: indices of all active loop iterations.
+    # Used for formula-path and expansion-path visibility filtering.
+    def current_path
+      @loop_stack.filter_map { |f| f[:current_iteration]&.dig(:index) }
+    end
+
+    # Check if any merge cell crosses a structural block boundary.
+    # Both block bounds and merge bounds use template row numbers.
+    def check_block_boundaries(sheet_name)
+      @original_merges.each do |merge_info|
+        merge_start = merge_info[:start_row]
+        merge_end = merge_info[:end_row]
+
+        @blocks.each do |block|
+          next unless crosses_boundary?(merge_start, merge_end, block[:start], block[:end])
+
+          raise UnsupportedTemplateError.new(
+            "Merged cell '#{merge_info[:ref]}' crosses a #{block[:type]} block boundary " \
+            "(template rows #{block[:start]}-#{block[:end]})",
+            sheet: sheet_name,
+            block_rows: "rows #{block[:start]}-#{block[:end]}"
+          )
+        end
+      end
+    end
+
+    def build_merge_ranges
+      result = []
+
+      @original_merges.each do |merge_info|
+        ref = merge_info[:ref]
+        start_template_row = merge_info[:start_row]
+        end_template_row = merge_info[:end_row]
+
+        # Skip merges on structural rows (consumed by parser)
+        unless @row_map.key?(start_template_row) || @row_map.key?(end_template_row)
+          next
+        end
+
+        if @row_map.key?(start_template_row) && @row_map.key?(end_template_row)
+          start_rows = @row_map[start_template_row]
+          end_rows = @row_map[end_template_row]
+
+          start_rows.each_with_index do |sr, i|
+            er = end_rows[i] || sr
+            cloned = clone_merge(ref, sr - start_template_row, er - end_template_row)
+            result << cloned if cloned
+          end
+        elsif @row_map.key?(start_template_row)
+          @row_map[start_template_row].each do |nr|
+            cloned = clone_merge_row(ref, nr - start_template_row)
+            result << cloned if cloned
+          end
+        else
+          result << ref
+        end
+      end
+
+      result
+    end
+
+    private
+
+    def crosses_boundary?(merge_start, merge_end, block_start, block_end)
+      # Merge entirely above or below the block
+      return false if merge_end < block_start || merge_start > block_end
+
+      # Merge strictly inside the block body (between the tag rows)
+      return false if merge_start > block_start && merge_end < block_end
+
+      # Merge entirely on a single structural tag row (it is consumed with it)
+      return false if merge_start == merge_end && (merge_start == block_start || merge_start == block_end)
+
+      # Any other overlap = crossing (including merges that swallow a tag row)
+      true
+    end
+
+    def clone_merge(ref, start_offset, end_offset)
+      parts = ref.split(":")
+      return nil if parts.length < 2
+
+      start_ref = CellReference.new(parts[0])
+      end_ref = CellReference.new(parts[1])
+
+      new_start = start_ref.shift(start_offset)
+      new_end = end_ref.shift(end_offset)
+      "#{new_start}:#{new_end}"
+    end
+
+    def clone_merge_row(ref, offset)
+      parts = ref.split(":")
+      start_ref = CellReference.new(parts[0])
+      end_ref = CellReference.new(parts[1] || parts[0])
+
+      new_start = start_ref.shift(offset)
+      new_end = end_ref.shift(offset)
+      "#{new_start}:#{new_end}"
+    end
+  end
+end