animate_it 0.1.0

data/lib/animate_it/render_store.rb

@@ -0,0 +1,189 @@
+module AnimateIt
+  class RenderStore
+    CHANNEL = "animate_it_renders".freeze
+    TARGET = "animate_it_renders".freeze
+
+    Render = Data.define(
+      :id,
+      :composition_id,
+      :status,
+      :current_frame,
+      :total_frames,
+      :output_path,
+      :error
+    ) do
+      def progress_percent
+        return 0 if total_frames.to_i.zero?
+
+        ((current_frame.to_f / total_frames) * 100).round
+      end
+    end
+
+    class << self
+      def create!(id:, composition_id:, total_frames:, output_path:)
+        render = nil
+        synchronize do
+          render = Render.new(id, composition_id, :queued, 0, total_frames, output_path.to_s, nil)
+          renders[id] = render
+        end
+        broadcast_append(render)
+      end
+
+      def start!(id)
+        update!(id, status: :rendering)
+      end
+
+      def progress!(id, frame:, total_frames:)
+        update!(id, status: :rendering, current_frame: frame, total_frames:)
+      end
+
+      def complete!(id)
+        render = fetch(id)
+        update!(id, status: :complete, current_frame: render.total_frames)
+      end
+
+      def fail!(id, error)
+        update!(id, status: :failed, error: error.message)
+      end
+
+      def cancel!(id)
+        update!(id, status: :cancelled, error: "Cancelled by user")
+      end
+
+      def cancelled?(id)
+        fetch(id).status == :cancelled
+      rescue KeyError
+        true
+      end
+
+      def all
+        synchronize { renders.values.reverse }
+      end
+
+      def fetch(id)
+        synchronize { renders.fetch(id) }
+      end
+
+      # nil-tolerant lookup — returns nil when the render isn't registered
+      # (e.g. server restart cleared the in-memory store but a tab still
+      # holds the old render id).
+      def find(id)
+        synchronize { renders[id] }
+      end
+
+      def broadcast_replace(render)
+        return unless defined?(Turbo::StreamsChannel)
+
+        Turbo::StreamsChannel.broadcast_replace_to(
+          CHANNEL,
+          target: row_id(render.id),
+          html: render_row(render)
+        )
+      end
+
+      def broadcast_append(render)
+        return unless defined?(Turbo::StreamsChannel)
+
+        Turbo::StreamsChannel.broadcast_append_to(
+          CHANNEL,
+          target: TARGET,
+          html: render_row(render)
+        )
+      end
+
+      def html
+        <<~HTML
+          <div id="#{TARGET}" class="animate-it-renders-list">
+            #{render_rows}
+          </div>
+        HTML
+      end
+
+      private
+
+      def update!(id, **attributes)
+        updated = synchronize do
+          render = renders.fetch(id)
+          renders[id] = Render.new(
+            id,
+            attributes.fetch(:composition_id, render.composition_id),
+            attributes.fetch(:status, render.status),
+            attributes.fetch(:current_frame, render.current_frame),
+            attributes.fetch(:total_frames, render.total_frames),
+            attributes.fetch(:output_path, render.output_path),
+            attributes.fetch(:error, render.error)
+          )
+          renders[id]
+        end
+        broadcast_replace(updated)
+      end
+
+      def render_row(render)
+        output = render.output_path.to_s
+        link = output_link(render, output)
+        kill = %i[queued rendering].include?(render.status) ? kill_button(render) : ""
+        error = render.error.present? ? %(<p style="color: #b91c1c;">#{ERB::Util.html_escape(render.error)}</p>) : ""
+
+        <<~HTML
+          <div id="#{row_id(render.id)}" class="animate-it-render-row">
+            <strong>#{ERB::Util.html_escape(render.composition_id)}</strong>
+            <span>#{ERB::Util.html_escape(render.status.to_s)}</span>
+            <span>frame #{render.current_frame} / #{render.total_frames}</span>
+            <progress max="100" value="#{render.progress_percent}"></progress>
+            <code class="animate-it-render-path" title="#{ERB::Util.html_escape(output)}">#{ERB::Util.html_escape(output)}</code>
+            #{link}
+            #{kill}
+            #{error}
+          </div>
+        HTML
+      end
+
+      def render_rows
+        rows = all.map { |render| render_row(render) }.join
+        return rows if rows.present?
+
+        <<~HTML
+          <p id="animate_it_renders_empty" style="color: #6b7280;">No renders yet.</p>
+        HTML
+      end
+
+      def row_id(render_id)
+        "animate_it_render_#{render_id}"
+      end
+
+      def output_link(render, output)
+        return "" unless %i[complete cancelled].include?(render.status)
+        return "" unless File.exist?(output)
+
+        %(<a href="#{AnimateIt.config.mount_path}/renders/#{render.id}?download=1" target="_blank" rel="noopener">Open MP4</a>)
+      end
+
+      def kill_button(render)
+        <<~HTML
+          <form action="#{AnimateIt.config.mount_path}/renders/#{render.id}/cancel" method="post" data-turbo="true">
+            <input type="hidden" name="authenticity_token" value="#{ERB::Util.html_escape(authenticity_token)}">
+            <button type="submit" class="button is-danger is-small">Kill render</button>
+          </form>
+        HTML
+      end
+
+      def authenticity_token
+        ApplicationController.renderer.instance_eval { form_authenticity_token }
+      rescue StandardError
+        ""
+      end
+
+      def renders
+        @renders ||= {}
+      end
+
+      def synchronize(&)
+        mutex.synchronize(&)
+      end
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+    end
+  end
+end

data/lib/animate_it/scene.rb

@@ -0,0 +1,237 @@
+module AnimateIt
+  class Scene
+    include AnimationHelpers
+    include ViewHelpers
+
+    attr_reader :context, :props, :view_context
+
+    def initialize(context:, props:)
+      @context = context
+      @props = props
+    end
+
+    delegate :frame, :local_frame, :fps, :progress, :interpolate, :spring, to: :context
+
+    # ----- class-level DSL -----------------------------------------------
+    class << self
+      # Sidecar template name. Defaults to "canvas" — i.e. a scene whose
+      # composition is `MyHero` looks for `app/videos/my_hero/canvas.html.haml`.
+      # Override to point to a sibling template instead.
+      def template(name = nil)
+        @template = name.to_s if name
+        @template ||= "canvas"
+      end
+
+      # Outer wrapper class for the scene's content. Defaults to
+      # "hero-render-canvas" (the convention used by all current heros).
+      def canvas_class(value = nil)
+        @canvas_class = value.to_s if value
+        @canvas_class ||= "hero-render-canvas"
+      end
+
+      # Declare an animatable element by name. Animation properties are
+      # attached via the block:
+      #
+      #   animate :step_1 do
+      #     fade  during: 10..30
+      #     slide during: 10..30, from: 16
+      #   end
+      #
+      # The framework auto-generates the `[data-anim="step_1"]` CSS rules
+      # and the per-frame CSS variables — no `:css` block in the HAML.
+      def animate(name, &block)
+        animations.add(name, block)
+      end
+
+      def animations
+        @animations ||= AnimationSet.new
+      end
+
+      # Composition class this scene belongs to. Set by the engine when the
+      # scene is mounted via `composition.scene MyScene` / single-scene
+      # auto-mount; lets animation property procs reach `Composition.beats`.
+      attr_accessor :composition_class
+
+      # Set automatically at the start of every `render` to the scene's
+      # current local_frame. Fixture closures (e.g. a singleton-method
+      # stub that needs to vary by frame) can call `MyScene.current_frame`
+      # without the scene having to remember to assign it in `body`.
+      attr_accessor :current_frame
+
+      # Declare a class-level fixture builder. With a block, registers the
+      # builder *lazily* (no work done at class load). Without a block,
+      # invokes the registered builder once behind a mutex — `Faker::Config.random`
+      # is reset to `Random.new(seed)` first (when `seed:` was given) and
+      # `FactoryBot.find_definitions` is invoked if no factories are loaded.
+      # Subsequent calls return the memoized hash.
+      #
+      #   class HeroScene < AnimateIt::Scene
+      #     fixtures(seed: 42) do
+      #       company = build_stubbed_company
+      #       { company:, job: build_stubbed_job(company) }
+      #     end
+      #   end
+      #
+      #   HeroScene.fixtures  # → builds once, returns hash
+      def fixtures(seed: nil, &block)
+        if block
+          @fixtures_block = block
+          @fixtures_seed = seed
+          return nil
+        end
+
+        return @fixtures_value if defined?(@fixtures_value) && @fixtures_value
+
+        @fixtures_mutex ||= Mutex.new
+        @fixtures_mutex.synchronize do
+          next @fixtures_value if @fixtures_value
+
+          FactoryBot.find_definitions if defined?(FactoryBot) && FactoryBot.factories.none?
+          Faker::Config.random = Random.new(@fixtures_seed) if defined?(Faker) && @fixtures_seed
+          @fixtures_value = @fixtures_block&.call
+        end
+      end
+
+      def reset_fixtures!
+        return unless @fixtures_mutex
+
+        @fixtures_mutex.synchronize { @fixtures_value = nil }
+      end
+
+      # Toggles fragment caching off for the rendering controller before
+      # `body` runs. Defeats the dev-environment `cache do ... end` blocks
+      # in production partials that key on stable record `updated_at`s and
+      # would otherwise reuse frame 1's HTML for every subsequent frame.
+      def disable_fragment_caching!
+        @disable_fragment_caching = true
+      end
+
+      def fragment_caching_disabled?
+        @disable_fragment_caching == true
+      end
+
+      # Class-side mirror of ViewHelpers#stub_methods so class-method
+      # fixture builders (which run before any Scene instance exists)
+      # can also use the helper to define singleton-method stubs on
+      # build_stubbed records.
+      def stub_methods(object, **stubs)
+        stubs.each do |name, value|
+          body = value.respond_to?(:call) ? value : ->(*) { value }
+          object.define_singleton_method(name) { |*args| body.call(*args) }
+        end
+        object
+      end
+    end
+
+    # ----- runtime --------------------------------------------------------
+
+    # Stash view_context so helpers (`tag`, `safe_join`, `capture`) work,
+    # then call `body` for the actual markup. Subclasses should override
+    # `body` (no args) — view_context is already available via the
+    # accessor.
+    #
+    # The framework's filmstrip + frame controllers call `render(view_context)`;
+    # don't override that signature unless you really need to.
+    def render(view_context)
+      @view_context = view_context
+      self.class.current_frame = local_frame
+      if self.class.fragment_caching_disabled? &&
+         view_context.respond_to?(:controller) &&
+         view_context.controller.respond_to?(:perform_caching=)
+        view_context.controller.perform_caching = false
+      end
+      body
+    end
+
+    # Set ivars on the view_context so templates rendered via
+    # `render_scene_template` / `view_context.render(template:)` can read
+    # them as `@foo`. ActionView's `assigns:` keyword doesn't propagate
+    # through template-level renders, so we push ivars directly onto the
+    # same view context the template will be evaluated against.
+    #
+    #   expose(:job, :user, from: fixtures, top_match: matches.first)
+    #
+    # The positional `keys` are pulled from the `from:` hash by name; the
+    # keyword args are set verbatim.
+    def expose(*keys, from: nil, **ivars)
+      keys.each { |k| view_context.instance_variable_set("@#{k}", from[k]) } if from
+      ivars.each { |k, v| view_context.instance_variable_set("@#{k}", v) }
+    end
+
+    # Default markup: canvas wrapper + sidecar template + auto-generated
+    # animation CSS. Override in a subclass when the composition is
+    # programmatic (no sidecar template) or has multiple acts.
+    def body
+      tag.div(class: self.class.canvas_class, style: canvas_style) do
+        absolute_fill(style: animation_var_style) do
+          parts = []
+          parts << generated_animation_styles if self.class.animations.elements.any?
+          parts << render_scene_template(self.class.template)
+          view_context.safe_join(parts)
+        end
+      end
+    end
+
+    # Convenience: when a subclass overrides `render` it can call this to
+    # get the same wrapper + animation-var div around custom content.
+    def with_canvas(&block)
+      tag.div(class: self.class.canvas_class, style: canvas_style) do
+        absolute_fill(style: animation_var_style) do
+          parts = []
+          parts << generated_animation_styles if self.class.animations.elements.any?
+          parts << view_context.capture(&block) if block
+          view_context.safe_join(parts)
+        end
+      end
+    end
+
+    # CSS var bag computed from this frame's animations. Available inside
+    # custom render methods that want extra inline styles.
+    def animation_vars(**extras)
+      Style.vars(**self.class.animations.vars_for(self), **extras)
+    end
+
+    delegate :composition_class, to: :class
+
+    private
+
+    def tag
+      view_context.tag
+    end
+
+    def safe_join(...)
+      view_context.safe_join(...)
+    end
+
+    def capture(...)
+      view_context.capture(...)
+    end
+
+    def generated_animation_styles
+      view_context.tag.style(self.class.animations.css_rules.html_safe)
+    end
+
+    def canvas_style
+      Style.build(
+        "position: relative",
+        "width: 100%",
+        "height: 100%",
+        "display: flex",
+        "align-items: center",
+        "justify-content: center",
+        "padding: 40px 80px",
+        "box-sizing: border-box",
+        "font-family: League Spartan, Arial, Helvetica, sans-serif",
+        "background: transparent"
+      )
+    end
+
+    def animation_var_style
+      Style.build(
+        "align-items: center",
+        "justify-content: center",
+        animation_vars
+      )
+    end
+  end
+end

data/lib/animate_it/style.rb

@@ -0,0 +1,23 @@
+module AnimateIt
+  module Style
+    module_function
+
+    def build(*rules, **properties)
+      property_rules = properties.filter_map do |property, value|
+        next if value.nil?
+
+        "#{property.to_s.tr("_", "-")}: #{value}"
+      end
+
+      (rules.flatten.compact + property_rules).join("; ")
+    end
+
+    def vars(**properties)
+      properties.filter_map do |property, value|
+        next if value.nil?
+
+        "--#{property.to_s.tr("_", "-")}: #{value}"
+      end.join("; ")
+    end
+  end
+end

data/lib/animate_it/timeline.rb

@@ -0,0 +1,81 @@
+module AnimateIt
+  class Timeline
+    Segment = Data.define(
+      :name,
+      :from_frame,
+      :duration_frames,
+      :scene_class,
+      :renderer,
+      :layout,
+      :class_name,
+      :style,
+      :show_in_timeline,
+      :kind,
+      :transition,
+      :track,
+      :source
+    ) do
+      def active_at?(frame)
+        return frame >= from_frame if duration_frames.nil?
+
+        frame >= from_frame && frame < from_frame + duration_frames
+      end
+
+      def local_frame(frame)
+        frame - from_frame
+      end
+    end
+
+    attr_reader :segments
+
+    def initialize
+      @segments = []
+    end
+
+    def add_segment(
+      name:,
+      from_frame:,
+      duration_frames:,
+      scene_class: nil,
+      renderer: nil,
+      layout: :none,
+      class_name: nil,
+      style: nil,
+      show_in_timeline: true,
+      kind: :scene,
+      transition: nil,
+      track: :main,
+      source: nil
+    )
+      segments << Segment.new(
+        name,
+        from_frame,
+        duration_frames,
+        scene_class,
+        renderer,
+        layout,
+        class_name,
+        style,
+        show_in_timeline,
+        kind,
+        transition,
+        track,
+        source
+      )
+    end
+
+    def active_segments(frame, kind: nil)
+      result = segments.select { |segment| segment.active_at?(frame) }
+      kind ? result.select { |segment| segment.kind == kind } : result
+    end
+
+    # Tracks in declaration order — first time a segment names a track wins.
+    def tracks
+      segments.map(&:track).uniq
+    end
+
+    def segments_for_track(track)
+      segments.select { |segment| segment.track == track }
+    end
+  end
+end

data/lib/animate_it/timing.rb

@@ -0,0 +1,63 @@
+module AnimateIt
+  module Timing
+    module_function
+
+    def interpolate(input, input_range, output_range, easing: :linear, extrapolate_left: :extend,
+                    extrapolate_right: :extend)
+      unless input_range.size == output_range.size
+        raise ArgumentError,
+              "input_range and output_range must have the same size"
+      end
+      raise ArgumentError, "interpolation needs at least two points" if input_range.size < 2
+
+      validate_extrapolation!(extrapolate_left)
+      validate_extrapolation!(extrapolate_right)
+
+      left_index = segment_index(input, input_range)
+      right_index = left_index + 1
+      input_start = input_range[left_index]
+      input_end = input_range[right_index]
+
+      if input < input_range.first
+        return output_range.first if extrapolate_left == :clamp
+        return input if extrapolate_left == :identity
+      end
+
+      if input > input_range.last
+        return output_range.last if extrapolate_right == :clamp
+        return input if extrapolate_right == :identity
+      end
+      return output_range[left_index] if input_end == input_start
+
+      progress = (input - input_start).to_f / (input_end - input_start)
+      eased = Easing.resolve(easing).call(progress)
+
+      output_start = output_range[left_index]
+      output_end = output_range[right_index]
+
+      output_start + ((output_end - output_start) * eased)
+    end
+
+    def spring(frame:, fps:, from: 0.0, to: 1.0, stiffness: 100.0, damping: 10.0, mass: 1.0)
+      seconds = [frame.to_f / fps, 0].max
+      angular_frequency = Math.sqrt(stiffness / mass)
+      decay = Math.exp((-damping / (2 * mass)) * seconds)
+      progress = 1 - (decay * Math.cos(angular_frequency * seconds))
+
+      from + ((to - from) * progress)
+    end
+
+    def segment_index(input, input_range)
+      return 0 if input <= input_range.first
+
+      index = input_range.each_cons(2).find_index { |left, right| input.between?(left, right) }
+      index || (input_range.size - 2)
+    end
+
+    def validate_extrapolation!(mode)
+      return if %i[clamp extend identity].include?(mode)
+
+      raise ArgumentError, "Unsupported extrapolation mode: #{mode.inspect}"
+    end
+  end
+end

data/lib/animate_it/units.rb

@@ -0,0 +1,38 @@
+module AnimateIt
+  module Units
+    module_function
+
+    # Time-string regex: accepts "1s", "1.5s", "300ms", "2m", "1m30s".
+    TIME_STRING = /\A(?:(\d+)m)?\s*(\d+(?:\.\d+)?)?\s*(s|ms)?\z/
+
+    def frames(value, fps:)
+      case value
+      when ActiveSupport::Duration
+        (value.to_f * fps).round
+      when FrameDuration, Numeric
+        value.to_i
+      when String
+        seconds = parse_time_string(value)
+        raise ArgumentError, "Cannot convert #{value.inspect} to frames" if seconds.nil?
+
+        (seconds * fps).round
+      when nil
+        nil
+      else
+        raise ArgumentError, "Cannot convert #{value.inspect} to frames"
+      end
+    end
+
+    # Parses "1s", "1.5s", "300ms", "2m", "1m30s" into seconds (Float).
+    def parse_time_string(str)
+      m = str.strip.match(TIME_STRING)
+      return nil if m.nil? || (m[1].nil? && m[2].nil?)
+
+      minutes = m[1].to_i
+      number = m[2].to_f
+      unit = m[3] || "s"
+      base = unit == "ms" ? number / 1000.0 : number
+      (minutes * 60) + base
+    end
+  end
+end

data/lib/animate_it/version.rb

@@ -0,0 +1,3 @@
+module AnimateIt
+  VERSION = "0.1.0".freeze
+end