animate_it 0.3.2 → 0.4.0

data/lib/animate_it/tracks/document.rb

@@ -0,0 +1,100 @@
+require "json"
+
+module AnimateIt
+  module Tracks
+    # Serializable track document consumed by the client runtime.
+    class Document
+      attr_reader :fps, :duration
+
+      def initialize(fps:, duration:)
+        @fps = fps
+        @duration = duration
+        @samples = Hash.new { |hash, group| hash[group] = {} }
+        @keyframes = Hash.new { |hash, group| hash[group] = {} }
+        @text_samples = {}
+        @group_selectors = {}
+        @text_selectors = {}
+        @layers = []
+      end
+
+      def record_sample(group, var, frame, value, selector: nil)
+        @group_selectors[group.to_s] = selector if selector
+        track = @samples[group.to_s][normalize_var(var)] ||= Array.new(duration)
+        track[frame] = value&.to_s
+      end
+
+      def add_keyframe_track(group, var, frames:, values:, easing: :ease_out, unit: nil, selector: nil)
+        @group_selectors[group.to_s] = selector if selector
+        @keyframes[group.to_s][normalize_var(var)] = {
+          "t" => "kf",
+          "k" => frames.map(&:to_i).zip(values),
+          "e" => easing.to_s,
+          "u" => unit.to_s
+        }
+      end
+
+      def record_text(key, frame, value, selector: nil)
+        @text_selectors[key.to_s] = selector if selector
+        track = @text_samples[key.to_s] ||= Array.new(duration)
+        track[frame] = value.to_s
+      end
+
+      def add_layer(key, from_frame, to_frame, origin_frame:)
+        @layers << {
+          "sel" => %([data-animate-layer="#{key}"]),
+          "from" => from_frame,
+          "to" => to_frame,
+          "origin" => origin_frame
+        }
+      end
+
+      def as_json
+        groups = @samples.transform_values { |vars| vars.transform_values { |track| rle(track) } }
+        @keyframes.each { |group, vars| (groups[group] ||= {}).merge!(vars) }
+
+        {
+          "v" => 2,
+          "fps" => fps,
+          "duration" => duration,
+          "groups" => groups,
+          "groupSelectors" => @group_selectors,
+          "texts" => @text_samples.transform_values { |track| rle(fill(track)) },
+          "textSelectors" => @text_selectors,
+          "layers" => @layers
+        }
+      end
+
+      def to_json(*)
+        JSON.generate(as_json)
+      end
+
+      private
+
+      def normalize_var(var)
+        name = var.to_s.tr("_", "-")
+        name.start_with?("--") ? name : "--#{name}"
+      end
+
+      # Text values hold across inactive gaps. CSS variable gaps stay nil so
+      # the browser can remove a property instead of leaking an earlier value.
+      def fill(track)
+        last = nil
+        forward = track.map { |value| last = value || last }
+        first = forward.find { |value| value } || ""
+        forward.map { |value| value || first }
+      end
+
+      def rle(track)
+        runs = []
+        track.each do |value|
+          if runs.any? && runs.last[0] == value
+            runs.last[1] += 1
+          else
+            runs << [value, 1]
+          end
+        end
+        { "t" => "rle", "r" => runs }
+      end
+    end
+  end
+end

data/lib/animate_it/tracks/layer.rb

@@ -0,0 +1,13 @@
+module AnimateIt
+  module Tracks
+    # One structural slice of a composition: a scene segment's DOM rendered
+    # at `from_frame`, shown by the client runtime for frames in
+    # [from_frame, to_frame). Layers are the union of timeline-segment
+    # windows and `structure_epochs` boundaries.
+    Layer = Data.define(:segment, :segment_index, :from_frame, :to_frame) do
+      def key
+        "s#{segment_index}/e#{from_frame}"
+      end
+    end
+  end
+end

data/lib/animate_it/tracks/recorder.rb

@@ -0,0 +1,149 @@
+module AnimateIt
+  module Tracks
+    # Samples declared variable/text tracks and serializes compact keyframes.
+    class Recorder
+      ANIMATE_GROUP = "animate".freeze
+
+      def initialize(composition, props: {})
+        @composition = composition
+        @props = composition.props_schema.resolve(props)
+        @scene_segments = composition.timeline.segments.each_with_index.filter_map do |segment, index|
+          [segment, index] if segment.kind == :scene
+        end
+        @layers_by_segment = composition.structure_layers.group_by(&:segment_index)
+      end
+
+      def call
+        document = Document.new(fps: @composition.fps, duration: @composition.duration_in_frames)
+        @composition.structure_layers.each do |layer|
+          document.add_layer(layer.key, layer.from_frame, layer.to_frame, origin_frame: layer.segment.from_frame)
+        end
+        record_animate_dsl(document)
+        record_word_reveals(document)
+        record_samples(document)
+        document
+      end
+
+      private
+
+      def record_samples(document)
+        @composition.duration_in_frames.times do |frame|
+          @scene_segments.each do |segment, segment_index|
+            next unless segment.active_at?(frame)
+
+            scene_class = segment.scene_class
+            next unless scene_class
+            next if scene_class.var_groups.empty? && scene_class.text_tracks.empty?
+
+            scene = build_scene(segment, frame)
+            record_frame_vars(document, scene, segment_index, frame)
+            record_frame_texts(document, scene, segment_index, frame)
+          end
+        end
+      end
+
+      def record_frame_vars(document, scene, segment_index, frame)
+        scene.class.var_groups.each_key do |group|
+          vars = evaluate(scene, "track_vars :#{group}", frame) { scene.evaluate_var_group(group) }
+          vars.each do |var, value|
+            document.record_sample(
+              binding_key(segment_index, group), var, frame, value,
+              selector: group_selector(segment_index, group)
+            )
+          end
+        end
+      end
+
+      def record_frame_texts(document, scene, segment_index, frame)
+        scene.class.text_tracks.each_key do |key|
+          value = evaluate(scene, "text_track :#{key}", frame) { scene.evaluate_text_track(key) }
+          document.record_text(
+            binding_key(segment_index, key), frame, value,
+            selector: text_selector(segment_index, key)
+          )
+        end
+      end
+
+      def record_animate_dsl(document)
+        @scene_segments.each do |segment, segment_index|
+          scene_class = segment.scene_class
+          next unless scene_class
+          next if scene_class.animations.elements.empty?
+
+          scene = build_scene(segment, segment.from_frame)
+          scene_class.animations.elements.each_value do |element|
+            element.properties.each do |prop|
+              keyframes = prop.keyframes_to_values.call(scene)
+              document.add_keyframe_track(
+                binding_key(segment_index, ANIMATE_GROUP),
+                prop.var_name(element.name),
+                frames: global_frames(segment, keyframes.keys),
+                values: keyframes.values,
+                unit: prop.unit,
+                selector: group_selector(segment_index, ANIMATE_GROUP)
+              )
+            end
+          end
+        end
+      end
+
+      def record_word_reveals(document)
+        @scene_segments.each do |segment, segment_index|
+          scene_class = segment.scene_class
+          next unless scene_class
+          next if scene_class.word_reveals_registry.empty?
+
+          scene = build_scene(segment, segment.from_frame)
+          scene_class.word_reveals_registry.each_key do |key|
+            scene.word_reveal_tracks(key).each do |track|
+              document.add_keyframe_track(
+                binding_key(segment_index, scene.reveal_group(key)),
+                track[:var],
+                frames: global_frames(segment, track[:frames]),
+                values: track[:values],
+                unit: track[:unit],
+                selector: group_selector(segment_index, scene.reveal_group(key))
+              )
+            end
+          end
+        end
+      end
+
+      def build_scene(segment, frame)
+        context = @composition.frame_context(frame:, props: @props, segment:)
+        segment.scene_class.current_frame = context.local_frame
+        segment.scene_class.new(context:, props: context.props)
+      end
+
+      def binding_key(segment_index, name)
+        "s#{segment_index}:#{name}"
+      end
+
+      def group_selector(segment_index, group)
+        layer_descendant_selector(segment_index, %([data-animate-vars="#{group}"]))
+      end
+
+      def text_selector(segment_index, key)
+        layer_descendant_selector(segment_index, %([data-animate-text="#{key}"]))
+      end
+
+      def layer_descendant_selector(segment_index, descendant)
+        @layers_by_segment.fetch(segment_index).map do |layer|
+          %([data-animate-layer="#{layer.key}"] #{descendant})
+        end.join(",")
+      end
+
+      def global_frames(segment, frames)
+        frames.map { |frame| segment.from_frame + frame }
+      end
+
+      def evaluate(scene, label, frame)
+        yield
+      rescue NoMethodError => e
+        raise Error, "#{label} on #{scene.class} raised at frame #{frame}: #{e.message}. " \
+                     "Track blocks run without a view context — keep them to pure var math " \
+                     "and move rendering concerns into the template."
+      end
+    end
+  end
+end

data/lib/animate_it/verification.rb

@@ -0,0 +1,187 @@
+require "fileutils"
+require "open3"
+require "uri"
+
+module AnimateIt
+  # Pixel-diff harness comparing the client player with legacy filmstrip.
+  class Verification
+    Result = Data.define(:frame, :rgb_psnr, :alpha_psnr, :passed) do
+      def psnr
+        [rgb_psnr, alpha_psnr].min
+      end
+    end
+
+    attr_reader :composition, :host, :step, :threshold, :alpha_threshold, :output_dir, :props, :ready_timeout
+
+    def initialize(
+      composition:,
+      host:,
+      step: 10,
+      threshold: 40.0,
+      alpha_threshold: nil,
+      output_dir: nil,
+      playwright_cli: nil,
+      props: {},
+      ready_timeout: 30_000
+    )
+      @composition = composition
+      @host = host.delete_suffix("/")
+      @step = [step.to_i, 1].max
+      @threshold = threshold.to_f
+      @alpha_threshold = alpha_threshold.nil? ? @threshold : alpha_threshold.to_f
+      @output_dir = Pathname(output_dir || Rails.root.join("tmp/animate_it/verify/#{composition.id}"))
+      @playwright_cli = playwright_cli || ENV.fetch("PLAYWRIGHT_CLI_EXECUTABLE_PATH", "npx playwright")
+      @props = props.to_h
+      @ready_timeout = [ready_timeout.to_i, 1].max
+    end
+
+    def call
+      require "playwright"
+      FileUtils.mkdir_p(output_dir)
+      results = []
+
+      Playwright.create(playwright_cli_executable_path: @playwright_cli) do |playwright|
+        browser = playwright.chromium.launch(
+          headless: true,
+          args: [
+            "--disable-web-security",
+            "--disable-lcd-text",
+            "--disable-gpu-compositing",
+            "--force-color-profile=srgb"
+          ]
+        )
+        begin
+          context = browser.new_context(viewport: { width: composition.width, height: composition.height })
+          legacy = open_page(context, "filmstrip")
+          candidate = open_page(context, "player")
+
+          sample_frames.each do |frame|
+            legacy_shot = screenshot(legacy, frame, "legacy")
+            candidate_shot = screenshot(candidate, frame, "player")
+            results << result_for(frame, legacy_shot, candidate_shot)
+          end
+        ensure
+          browser&.close
+        end
+      end
+
+      results
+    end
+
+    def sample_frames
+      max = composition.duration_in_frames - 1
+      frames = (0..max).step(step).to_a
+      composition.structure_layers.each do |layer|
+        [layer.from_frame, layer.to_frame].each do |edge|
+          frames.push(edge - 1, edge, edge + 1)
+        end
+      end
+      frames.grep(0..max).sort.uniq
+    end
+
+    private
+
+    def open_page(context, endpoint)
+      page = context.new_page
+      url = page_url(endpoint)
+      response = page.goto(url, waitUntil: "networkidle", timeout: ready_timeout)
+      unless response&.ok?
+        status = response ? "#{response.status} #{response.status_text}" : "no HTTP response"
+        raise Error, "Could not open AnimateIt #{endpoint} page at #{url}: #{status}"
+      end
+
+      page.wait_for_function(
+        'document.documentElement.dataset.animateItReady === "1"',
+        timeout: ready_timeout
+      )
+      page
+    rescue Playwright::TimeoutError => e
+      raise Error,
+            "Timed out after #{ready_timeout}ms waiting for the AnimateIt #{endpoint} page at #{url}. " \
+            "Confirm the server is reachable and that the page sets data-animate-it-ready=\"1\". " \
+            "(#{e.message})"
+    end
+
+    def screenshot(page, frame, label)
+      page.evaluate("(n) => window.__animateIt.setFrame(n)", arg: frame)
+      if label == "player"
+        page.evaluate(<<~JS)
+          document.querySelectorAll(".animate-it-layer.is-active").forEach((el) => {
+            el.classList.remove("is-active");
+            void el.offsetHeight;
+            el.classList.add("is-active");
+          });
+        JS
+        page.evaluate("(n) => window.__animateIt.setFrame(n)", arg: frame)
+      end
+      page.evaluate("() => new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)))")
+      path = output_dir.join(format("%<label>s-%<frame>05d.png", label:, frame:))
+      page.screenshot(path: path.to_s, omitBackground: true)
+      path
+    end
+
+    def page_url(endpoint)
+      query = { pp: "disable" }
+      query[:props_json] = JSON.generate(props) unless props.empty?
+      "#{host}#{AnimateIt.config.mount_path}/compositions/#{composition.id}/#{endpoint}?#{URI.encode_www_form(query)}"
+    end
+
+    def psnr_between(reference, candidate)
+      psnr_between_rgba(decoded_rgba(reference), decoded_rgba(candidate))
+    end
+
+    def psnr_between_rgba(reference_rgba, candidate_rgba)
+      unless reference_rgba.bytesize == candidate_rgba.bytesize
+        raise Error,
+              "Cannot compare screenshots with different decoded sizes " \
+              "(#{reference_rgba.bytesize} vs #{candidate_rgba.bytesize} RGBA bytes)"
+      end
+
+      rgb_error = 0.0
+      alpha_error = 0.0
+      offset = 0
+      while offset < reference_rgba.bytesize
+        reference_alpha = reference_rgba.getbyte(offset + 3)
+        candidate_alpha = candidate_rgba.getbyte(offset + 3)
+        alpha_error += (reference_alpha - candidate_alpha)**2
+
+        3.times do |channel|
+          reference_value = reference_rgba.getbyte(offset + channel) * reference_alpha / 255.0
+          candidate_value = candidate_rgba.getbyte(offset + channel) * candidate_alpha / 255.0
+          rgb_error += (reference_value - candidate_value)**2
+        end
+        offset += 4
+      end
+
+      pixels = reference_rgba.bytesize / 4
+      [psnr(rgb_error, pixels * 3), psnr(alpha_error, pixels)]
+    end
+
+    def result_for(frame, reference, candidate)
+      rgb_psnr, alpha_psnr = psnr_between(reference, candidate)
+      result_for_scores(frame, rgb_psnr, alpha_psnr)
+    end
+
+    def result_for_scores(frame, rgb_psnr, alpha_psnr)
+      passed = rgb_psnr >= threshold && alpha_psnr >= alpha_threshold
+      Result.new(frame:, rgb_psnr:, alpha_psnr:, passed:)
+    end
+
+    def decoded_rgba(path)
+      stdout, stderr, status = Open3.capture3(
+        "ffmpeg", "-v", "error", "-i", path.to_s,
+        "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgba", "-"
+      )
+      raise Error, "ffmpeg could not decode #{path}: #{stderr}" unless status.success?
+
+      stdout
+    end
+
+    def psnr(squared_error, samples)
+      return Float::INFINITY if squared_error.zero?
+
+      mean_squared_error = squared_error / samples
+      10 * Math.log10((255.0**2) / mean_squared_error)
+    end
+  end
+end

data/lib/animate_it/version.rb

@@ -1,3 +1,3 @@
 module AnimateIt
-  VERSION = "0.3.2".freeze
+  VERSION = "0.4.0".freeze
 end

data/lib/animate_it/video_renderer.rb

@@ -39,34 +39,49 @@ module AnimateIt
       @output_path = Pathname(output_path)
       @frames_dir = Pathname(frames_dir || Rails.root.join("tmp/animate_it/#{composition.id}"))
       @playwright_cli = playwright_cli || ENV.fetch("PLAYWRIGHT_CLI_EXECUTABLE_PATH", DEFAULT_PLAYWRIGHT_CLI)
-
-      return unless audio_segments.any? && AUDIO_INCAPABLE_FORMATS.include?(@output_format)
-
-      raise Error,
-            "Composition #{composition.id} declares audio but format=#{@output_format} doesn't support audio. Use :webm/:mp4/:mov."
     end
 
     class CancelledError < AnimateIt::Error; end
 
-    def render(frame_range: nil, every_nth_frame: 1, props: {}, on_progress: nil, cancel_check: nil)
+    def render(frame_range: nil, every_nth_frame: 1, props: {}, on_progress: nil, cancel_check: nil,
+               reuse_captured_frames: false)
       FileUtils.mkdir_p(frames_dir)
       FileUtils.mkdir_p(output_path.dirname)
 
       frame_list = frames(frame_range:, every_nth_frame:)
-      capture_status = capture_frames(frame_list, props:, on_progress:, cancel_check:)
+      if reuse_captured_frames
+        validate_captured_frames!(frame_list.size)
+        capture_status = :complete
+      else
+        clear_captured_frames!
+        capture_status = capture_frames(frame_list, props:, on_progress:, cancel_check:)
+      end
 
       if capture_status == :cancelled || cancel_check&.call
         frame_count = contiguous_frame_count
-        encode_video(frame_count:) if frame_count.positive?
+        encode_video(frame_count:, start_frame: frame_list.first) if frame_count.positive?
         raise CancelledError, "Render cancelled"
       end
 
-      encode_video
+      encode_video(frame_count: frame_list.size, start_frame: frame_list.first)
       output_path
     end
 
     private
 
+    def clear_captured_frames!
+      Dir.glob(frames_dir.join("frame-*.png")).each { |path| FileUtils.rm_f(path) }
+    end
+
+    def validate_captured_frames!(frame_count)
+      missing = frame_count.times.find do |index|
+        !frames_dir.join(format("frame-%05d.png", index)).file?
+      end
+      return unless missing
+
+      raise Error, "Captured frame not found: #{frames_dir.join(format("frame-%05d.png", missing))}"
+    end
+
     def frames(frame_range:, every_nth_frame:)
       range = frame_range || (0...composition.duration_in_frames)
       range.step(every_nth_frame).to_a
@@ -87,7 +102,7 @@ module AnimateIt
           )
           page = context.new_page
 
-          page.goto(filmstrip_url(props:), waitUntil: "networkidle")
+          page.goto(page_url(props:), waitUntil: "networkidle")
           page.wait_for_function('document.documentElement.dataset.animateItReady === "1"')
 
           frame_list.each_with_index do |frame, index|
@@ -110,15 +125,19 @@ module AnimateIt
       cancelled || cancel_check&.call ? :cancelled : :complete
     end
 
-    def filmstrip_url(props:)
+    def page_url(props:)
       query = { pp: "disable" }
       query[:props_json] = JSON.generate(props) if props.present?
+      endpoint = composition.client_driven? ? "player" : "filmstrip"
 
-      "#{host}#{AnimateIt.config.mount_path}/compositions/#{composition.id}/filmstrip?#{URI.encode_www_form(query)}"
+      "#{host}#{AnimateIt.config.mount_path}/compositions/#{composition.id}/#{endpoint}?#{URI.encode_www_form(query)}"
     end
 
-    def encode_video(frame_count: nil)
-      return if output_format == :png_sequence # frames already on disk; nothing to encode
+    def encode_video(frame_count: nil, start_frame: 0)
+      if output_format == :png_sequence
+        publish_png_sequence(frame_count || contiguous_frame_count)
+        return
+      end
 
       if output_format == :png
         # Single-frame still: copy the captured PNG straight to output_path.
@@ -131,14 +150,24 @@ module AnimateIt
       command = ["ffmpeg", "-y", "-framerate", composition.fps.to_s,
                  "-i", frames_dir.join("frame-%05d.png").to_s]
 
-      audios = audio_segments
-      audios.each { |seg| command += ["-i", resolve_audio_path!(seg.source[:path])] }
+      clip_frame_count = frame_count || composition.duration_in_frames
+      audios = audio_capable? ? audio_segments(start_frame:, frame_count: clip_frame_count) : []
+      audios.each do |segment|
+        command += ["-stream_loop", "-1"] if segment.source[:loop]
+        command += ["-i", resolve_audio_path!(segment.source[:path])]
+      end
 
       command += video_codec_args
       command += ["-frames:v", frame_count.to_s] if frame_count
 
       if audios.any?
-        command += ["-filter_complex", audio_filter_graph(audios), "-map", "0:v", "-map", "[aout]", "-shortest"]
+        command += [
+          "-filter_complex",
+          audio_filter_graph(audios, start_frame:, frame_count: clip_frame_count),
+          "-map", "0:v",
+          "-map", "[aout]",
+          "-shortest"
+        ]
         command += audio_codec_args
       else
         command += ["-an"] # explicit no-audio so output containers like .mov stay clean
@@ -149,6 +178,19 @@ module AnimateIt
       run!(command)
     end
 
+    def publish_png_sequence(frame_count)
+      FileUtils.mkdir_p(output_path)
+      Dir.glob(output_path.join("frame-*.png")).each { |path| FileUtils.rm_f(path) }
+
+      frame_count.times do |index|
+        filename = format("frame-%05d.png", index)
+        source = frames_dir.join(filename)
+        raise Error, "Captured frame not found: #{source}" unless source.file?
+
+        FileUtils.cp(source, output_path.join(filename))
+      end
+    end
+
     def video_codec_args
       case output_format
       when :mp4
@@ -174,23 +216,44 @@ module AnimateIt
       end
     end
 
-    # Build an `adelay=...|...,volume=g[aN]` chain per audio input, then mix.
-    def audio_filter_graph(audios)
+    # Trim each source to its timeline window before delaying and mixing it.
+    def audio_filter_graph(audios, start_frame: 0, frame_count: composition.duration_in_frames)
       ms_per_frame = 1000.0 / composition.fps
-      legs = audios.each_with_index.map do |seg, i|
-        delay_ms = (seg.from_frame * ms_per_frame).round
-        gain = seg.source[:gain] || 1.0
-        "[#{i + 1}:a]adelay=#{delay_ms}|#{delay_ms},volume=#{gain}[a#{i}]"
+      clip_end_frame = start_frame + frame_count
+      legs = audios.each_with_index.map do |segment, index|
+        segment_end_frame = segment.duration_frames ? segment.from_frame + segment.duration_frames : composition.duration_in_frames
+        overlap_start_frame = [segment.from_frame, start_frame].max
+        overlap_end_frame = [segment_end_frame, clip_end_frame].min
+        source_start_seconds = (overlap_start_frame - segment.from_frame).fdiv(composition.fps)
+        overlap_seconds = (overlap_end_frame - overlap_start_frame).fdiv(composition.fps)
+        delay_ms = ((overlap_start_frame - start_frame) * ms_per_frame).round
+        gain = segment.source[:gain] || 1.0
+        "[#{index + 1}:a]atrim=start=#{source_start_seconds}:duration=#{overlap_seconds}," \
+          "asetpts=PTS-STARTPTS," \
+          "adelay=#{delay_ms}|#{delay_ms},volume=#{gain}[a#{index}]"
       end
       # normalize=0: amix's default rescales every input by 1/N, which
       # silently buries a voice-over under a music bed the moment a second
       # track is declared. Declared gains are the only intended scaling.
-      mix = "#{audios.length.times.map { |i| "[a#{i}]" }.join}amix=inputs=#{audios.length}:duration=longest:normalize=0[aout]"
+      clip_seconds = frame_count.fdiv(composition.fps)
+      mix = "#{audios.length.times.map { |i| "[a#{i}]" }.join}" \
+            "amix=inputs=#{audios.length}:duration=longest:normalize=0," \
+            "apad=whole_dur=#{clip_seconds},atrim=duration=#{clip_seconds}[aout]"
       [legs, mix].flatten.join(";")
     end
 
-    def audio_segments
-      composition.timeline.segments.select { |seg| seg.kind == :audio }
+    def audio_segments(start_frame: 0, frame_count: composition.duration_in_frames)
+      clip_end_frame = start_frame + frame_count
+      composition.timeline.segments.select do |segment|
+        next false unless segment.kind == :audio
+
+        segment_end_frame = segment.duration_frames ? segment.from_frame + segment.duration_frames : composition.duration_in_frames
+        segment.from_frame < clip_end_frame && segment_end_frame > start_frame
+      end
+    end
+
+    def audio_capable?
+      AUDIO_INCAPABLE_FORMATS.exclude?(output_format)
     end
 
     def resolve_audio_path!(path)

data/lib/animate_it/view_helpers.rb

@@ -4,9 +4,14 @@ module AnimateIt
       Style.build(*rules, **properties)
     end
 
-    def absolute_fill(class_name: nil, style: nil, **attributes, &block)
+    def absolute_fill(class_name: nil, style: nil, vars: nil, **attributes, &block)
       content = block.call
 
+      if vars
+        style = [style.presence, animation_vars(vars)].compact.join("; ")
+        attributes = { data: { animate_vars: vars } }.deep_merge(attributes)
+      end
+
       tag.div(
         **attributes,
         class: ["animate-it-absolute-fill", class_name].compact,
@@ -16,6 +21,11 @@ module AnimateIt
       end
     end
 
+    def animate_text(key, tag_name: :span, **attributes)
+      attributes = { data: { animate_text: key } }.deep_merge(attributes)
+      tag.public_send(tag_name, evaluate_text_track(key).to_s, **attributes)
+    end
+
     def render_template(template, assigns: {}, **)
       view_context.render(template:, assigns:, layout: false, **)
     end