animate_it 0.3.2 → 0.5.0

data/lib/animate_it/text_effects.rb

@@ -0,0 +1,104 @@
+module AnimateIt
+  # Declarative word-by-word headline reveals that can be recorded as compact
+  # keyframe tracks while retaining server-rendered fallback values.
+  module TextEffects
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def word_reveal(key, text, start:, offset: 0, stagger: 4, dur: 12, rise: 18)
+        own_word_reveals[key.to_sym] = { kind: :rise, text:, start:, offset:, stagger:, dur:, rise: }
+      end
+
+      def punch_reveal(key, text, start:, offset: 0, stagger: 5, dur: 10)
+        own_word_reveals[key.to_sym] = { kind: :punch, text:, start:, offset:, stagger:, dur: }
+      end
+
+      def word_reveals_registry
+        inherited = superclass.respond_to?(:word_reveals_registry) ? superclass.word_reveals_registry : {}
+        inherited.merge(own_word_reveals)
+      end
+
+      def own_word_reveals
+        @own_word_reveals ||= {}
+      end
+    end
+
+    def word_reveal_tracks(key)
+      spec = self.class.word_reveals_registry.fetch(key.to_sym)
+      base = resolve_reveal_start(spec)
+      spec[:text].split.each_with_index.flat_map do |_word, index|
+        from = base + (index * spec[:stagger])
+        to = from + spec[:dur]
+        if spec[:kind] == :punch
+          [
+            { var: "#{key}-w#{index}-op", frames: [from, to], values: [0, 1], unit: "" },
+            {
+              var: "#{key}-w#{index}-sc",
+              frames: [from, from + (spec[:dur] * 0.6).round, to],
+              values: [1.3, 1.06, 1.0],
+              unit: ""
+            }
+          ]
+        else
+          [
+            { var: "#{key}-w#{index}-op", frames: [from, to], values: [0, 1], unit: "" },
+            { var: "#{key}-w#{index}-y", frames: [from, to], values: [spec[:rise], 0], unit: "px" }
+          ]
+        end
+      end
+    end
+
+    def reveal_words(key)
+      spec = self.class.word_reveals_registry.fetch(key.to_sym)
+      static = word_reveal_tracks(key).to_h do |track|
+        value = interpolate(
+          local_frame,
+          track[:frames],
+          track[:values],
+          easing: :ease_out,
+          extrapolate_left: :clamp,
+          extrapolate_right: :clamp
+        ).round(4)
+        [track[:var].to_sym, "#{value}#{track[:unit]}"]
+      end
+
+      spans = spec[:text].split.each_with_index.map do |word, index|
+        tag.span(word, style: reveal_word_style(spec, key, index))
+      end
+
+      tag.span(
+        safe_join(spans, " "),
+        data: { animate_vars: reveal_group(key) },
+        style: Style.build("display: contents", Style.vars(**static))
+      )
+    end
+
+    def reveal_plain_words(key)
+      spec = self.class.word_reveals_registry.fetch(key.to_sym)
+      safe_join(spec[:text].split.map { |word| tag.span(word) }, " ")
+    end
+
+    def reveal_group(key)
+      "textfx-#{key.to_s.tr("_", "-")}"
+    end
+
+    private
+
+    def resolve_reveal_start(spec)
+      base = spec[:start].is_a?(Symbol) ? beat_frame(spec[:start]) : spec[:start]
+      base + spec[:offset]
+    end
+
+    def reveal_word_style(spec, key, index)
+      if spec[:kind] == :punch
+        "display:inline-block; opacity: var(--#{key}-w#{index}-op, 0); " \
+          "transform: scale(var(--#{key}-w#{index}-sc, 1.3));"
+      else
+        "display:inline-block; opacity: var(--#{key}-w#{index}-op, 0); " \
+          "transform: translateY(var(--#{key}-w#{index}-y, #{spec[:rise]}px));"
+      end
+    end
+  end
+end

data/lib/animate_it/track_document_schema.rb

@@ -0,0 +1,71 @@
+module AnimateIt
+  # Validates the server/browser track-document boundary before embedding it.
+  module TrackDocumentSchema
+    CURRENT_VERSION = 2
+    SUPPORTED_VERSIONS = [1, CURRENT_VERSION].freeze
+
+    module_function
+
+    def validate!(document)
+      data = document.respond_to?(:as_json) ? document.as_json : document
+      raise Error, "AnimateIt track document must be a JSON object" unless data.is_a?(Hash)
+
+      version = data["v"]
+      unless SUPPORTED_VERSIONS.include?(version)
+        raise Error,
+              "Unsupported AnimateIt track schema #{version.inspect}; " \
+              "supported versions are #{SUPPORTED_VERSIONS.join(", ")}"
+      end
+
+      validate_positive_number!(data, "fps")
+      validate_positive_integer!(data, "duration")
+      validate_hash!(data, "groups")
+      validate_hash!(data, "texts")
+      validate_array!(data, "layers")
+      validate_v2!(data) if version == CURRENT_VERSION
+      data
+    end
+
+    def validate_v2!(data)
+      validate_hash!(data, "groupSelectors")
+      validate_hash!(data, "textSelectors")
+      validate_selector_keys!(data["groups"], data["groupSelectors"], "group")
+      validate_selector_keys!(data["texts"], data["textSelectors"], "text")
+    end
+    private_class_method :validate_v2!
+
+    def validate_selector_keys!(tracks, selectors, kind)
+      extra = selectors.keys - tracks.keys
+      return if extra.empty?
+
+      raise Error, "AnimateIt v2 #{kind} selectors reference missing tracks: #{extra.join(", ")}"
+    end
+    private_class_method :validate_selector_keys!
+
+    def validate_positive_number!(data, key)
+      value = data[key]
+      return if value.is_a?(Numeric) && value.positive?
+
+      raise Error, "AnimateIt track document #{key} must be a positive number"
+    end
+    private_class_method :validate_positive_number!
+
+    def validate_positive_integer!(data, key)
+      value = data[key]
+      return if value.is_a?(Integer) && value.positive?
+
+      raise Error, "AnimateIt track document #{key} must be a positive integer"
+    end
+    private_class_method :validate_positive_integer!
+
+    def validate_hash!(data, key)
+      raise Error, "AnimateIt track document #{key} must be an object" unless data[key].is_a?(Hash)
+    end
+    private_class_method :validate_hash!
+
+    def validate_array!(data, key)
+      raise Error, "AnimateIt track document #{key} must be an array" unless data[key].is_a?(Array)
+    end
+    private_class_method :validate_array!
+  end
+end

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.5.0".freeze
 end