animate_it 0.3.2 → 0.5.0

data/lib/animate_it/chapter_navigation.rb

@@ -0,0 +1,160 @@
+module AnimateIt
+  class ChapterPresenter
+    attr_reader :chapter
+
+    delegate :name, :label, :start_frame, :duration_frames, :end_frame, :metadata, to: :chapter
+
+    def initialize(view, chapter, interactive:, state:)
+      @view = view
+      @chapter = chapter
+      @interactive = interactive
+      @state = state
+    end
+
+    def thumbnail
+      metadata[:thumbnail] || metadata["thumbnail"]
+    end
+
+    def button(content = nil, **attributes, &block)
+      body = block ? @view.capture(self, &block) : (content || label)
+      classes = ["animate-it-chapter", attributes.delete(:class)].compact.join(" ")
+      attributes, data = stateful_attributes(attributes)
+      attributes[:type] ||= "button"
+      attributes[:"aria-label"] ||= "Jump to #{label}"
+      @view.tag.button(body, **attributes, class: classes, data:)
+    end
+
+    def element(content = nil, tag: :div, **attributes, &block)
+      body = block ? @view.capture(self, &block) : (content || label)
+      classes = ["animate-it-chapter", attributes.delete(:class)].compact.join(" ")
+      attributes, data = stateful_attributes(attributes)
+      @view.tag.public_send(tag, body, **attributes, class: classes, data:)
+    end
+
+    def default_control(preset: :pills)
+      progress = @view.tag.svg(
+        @view.tag.rect(x: 1, y: 1, width: 98, height: 38, rx: 19, pathLength: 1),
+        class: "animate-it-chapter__progress", viewBox: "0 0 100 40", preserveAspectRatio: "none", aria: { hidden: true }
+      )
+      body = @view.safe_join([progress, @view.tag.span(label, class: "animate-it-chapter__label")])
+      classes = "animate-it-chapter animate-it-chapter--#{preset}"
+      if @interactive
+        button(body, class: classes.delete_prefix("animate-it-chapter "))
+      else
+        element(body, class: classes.delete_prefix("animate-it-chapter "))
+      end
+    end
+
+    private
+
+    def stateful_attributes(attributes)
+      attributes = attributes.dup
+      data = (attributes.delete(:data) || {}).merge(
+        animate_it_chapter: name,
+        chapter_state: @state.fetch(:state),
+        chapter_position: @state.fetch(:position)
+      )
+      variables = [
+        "--animate-it-chapter-progress: #{@state.fetch(:progress)}",
+        "--animate-it-chapter-active: #{@state.fetch(:active)}",
+        "--animate-it-chapter-complete: #{@state.fetch(:complete)}",
+        attributes.delete(:style)
+      ].compact.join(";")
+      attributes[:style] = variables
+      attributes[:"aria-current"] = "step" if @interactive && @state.fetch(:state) == "current"
+      [attributes, data]
+    end
+  end
+
+  class ChapterNavigationBuilder
+    def initialize(view, composition, interactive:, preset: :pills, mobile: nil, frame: 0)
+      @view = view
+      @composition = composition
+      @interactive = interactive
+      @preset = preset&.to_sym
+      @mobile = mobile&.to_sym
+      @frame = frame.to_i
+    end
+
+    def render(**attributes, &block)
+      current_index = current_chapter_index
+      chapters = @composition.chapters.each_with_index.map do |chapter, index|
+        presenter = ChapterPresenter.new(@view, chapter, interactive: @interactive, state: chapter_state(chapter, index, current_index))
+        block ? @view.capture(presenter, &block) : presenter.default_control(preset: @preset || :pills)
+      end
+      classes = ["animate-it-chapters", @preset && "animate-it-chapters--#{@preset}",
+                 @mobile && "animate-it-chapters--mobile-#{@mobile}", attributes.delete(:class)].compact.join(" ")
+      data = (attributes.delete(:data) || {}).merge(animate_it_chapter_navigation: true)
+      attributes[:"aria-label"] ||= "Animation chapters" if @interactive
+      tag = @interactive ? :nav : :div
+      @view.tag.public_send(tag, @view.safe_join(chapters), **attributes, class: classes, data:)
+    end
+
+    private
+
+    def current_chapter_index
+      @composition.chapters.to_a.rindex { |chapter| @frame >= chapter.start_frame } || -1
+    end
+
+    def chapter_state(chapter, index, current_index)
+      state = if current_index.negative? || index > current_index
+                "upcoming"
+              elsif index < current_index
+                "completed"
+              else
+                "current"
+              end
+      progress = if state == "completed"
+                   1.0
+                 elsif state == "current"
+                   chapter_progress(chapter)
+                 else
+                   0.0
+                 end
+      {
+        state:,
+        position: chapter_position(index, current_index),
+        progress:,
+        active: state == "current" ? 1 : 0,
+        complete: state == "completed" ? 1 : 0
+      }
+    end
+
+    def chapter_progress(chapter)
+      return 1.0 if chapter.duration_frames == 1
+
+      (@frame - chapter.start_frame).fdiv(chapter.duration_frames - 1).clamp(0, 1)
+    end
+
+    def chapter_position(index, current_index)
+      return "hidden" if current_index.negative?
+      return "current" if index == current_index
+      return "previous" if index == current_index - 1
+      return "next" if index == current_index + 1
+
+      "hidden"
+    end
+  end
+
+  module ChapterNavigationHelper
+    def animate_it_chapter_navigation(
+      composition: nil, preset: nil, mobile: nil, hide_when_embedded: false, frame: nil, **attributes, &
+    )
+      target = composition || instance_variable_get(:@composition)
+      raise ArgumentError, "animate_it_chapter_navigation requires a composition" unless target
+
+      target.chapters.validate!
+      data = (attributes.delete(:data) || {}).merge(animate_it_hide_when_embedded: hide_when_embedded ? "true" : "false")
+      attributes[:style] = ["--animate-it-chapter-count: #{target.chapters.count}", attributes[:style]].compact.join(";")
+      builder = ChapterNavigationBuilder.new(
+        self, target, interactive: false, preset:, mobile:, frame: frame || instance_variable_get(:@frame) || 0
+      )
+      safe_join(
+        [
+          tag.style(AnimateIt::EmbedStyles.chapter_source.html_safe, data: { animate_it_chapter_styles: true }),
+          builder.render(**attributes, data:, &)
+        ]
+      )
+    end
+  end
+end

data/lib/animate_it/chapters.rb

@@ -0,0 +1,95 @@
+require "json"
+
+module AnimateIt
+  Chapter = Data.define(:name, :label, :beat_name, :start_frame, :duration_frames, :metadata) do
+    def end_frame
+      start_frame + duration_frames
+    end
+
+    def as_json(*)
+      {
+        "name" => name.to_s,
+        "label" => label,
+        "beat" => beat_name.to_s,
+        "startFrame" => start_frame,
+        "durationFrames" => duration_frames,
+        "endFrame" => end_frame,
+        "metadata" => metadata
+      }
+    end
+  end
+
+  class Chapters
+    include Enumerable
+
+    def initialize(composition)
+      @composition = composition
+      @chapters = []
+    end
+
+    def add(name, beat:, label:, metadata: {})
+      key = name.to_sym
+      raise ArgumentError, "AnimateIt chapter names must be unique: #{name.inspect}" if @chapters.any? { |chapter| chapter.name == key }
+      raise ArgumentError, "AnimateIt chapter labels must not be blank" if label.to_s.strip.empty?
+      raise ArgumentError, "AnimateIt chapter metadata must be a hash" unless metadata.is_a?(Hash)
+
+      JSON.generate(metadata)
+
+      beat_record = @composition.beats.fetch(beat)
+      chapter = Chapter.new(
+        name: key,
+        label: label.to_s,
+        beat_name: beat_record.name,
+        start_frame: beat_record.start_frame,
+        duration_frames: beat_record.duration_frames,
+        metadata: metadata.freeze
+      )
+      validate_after!(@chapters.last, chapter)
+      validate_bounds!(chapter)
+      @chapters << chapter
+      chapter
+    end
+
+    def fetch(name)
+      @chapters.find { |chapter| chapter.name == name.to_sym } ||
+        raise(Error, "Unknown chapter: #{name.inspect}. Declared: #{@chapters.map(&:name).inspect}")
+    end
+
+    def each(&)
+      @chapters.each(&)
+    end
+
+    delegate :empty?, to: :@chapters
+
+    def as_json(*)
+      validate!
+      @chapters.map(&:as_json)
+    end
+
+    def validate!
+      @chapters.each_with_index do |chapter, index|
+        validate_after!(@chapters[index - 1], chapter) if index.positive?
+        validate_bounds!(chapter)
+      end
+      self
+    end
+
+    private
+
+    def validate_after!(previous, chapter)
+      return unless previous
+
+      raise ArgumentError, "AnimateIt chapters must have strictly increasing start frames" if chapter.start_frame <= previous.start_frame
+      return if chapter.start_frame >= previous.end_frame
+
+      raise ArgumentError, "AnimateIt chapters must not overlap: #{previous.name.inspect} and #{chapter.name.inspect}"
+    end
+
+    def validate_bounds!(chapter)
+      return if chapter.start_frame >= 0 && chapter.duration_frames.positive? && chapter.end_frame <= @composition.duration_in_frames
+
+      raise ArgumentError,
+            "AnimateIt chapter #{chapter.name.inspect} must fit within 0...#{@composition.duration_in_frames} frames"
+    end
+  end
+end

data/lib/animate_it/composition.rb

@@ -14,6 +14,9 @@ module AnimateIt
         subclass.instance_variable_set(:@zoom, 1.0)
         subclass.instance_variable_set(:@duration_in_frames, 30)
         subclass.instance_variable_set(:@output_format, :webm)
+        subclass.instance_variable_set(:@verification_props, [{}].freeze)
+        subclass.instance_variable_set(:@public_player_options, nil)
+        subclass.instance_variable_set(:@chapters, Chapters.new(subclass))
         super
       end
 
@@ -65,6 +68,81 @@ module AnimateIt
         AnimateIt.register(self)
       end
 
+      # Opt in to the seekable browser runtime. Legacy compositions continue
+      # rendering individual frames on the server.
+      def client_driven!
+        @client_driven = true
+      end
+
+      def client_driven?
+        @client_driven == true
+      end
+
+      # Explicitly expose this composition through the production-safe public
+      # player endpoint. Studio, frame, filmstrip, props, and render endpoints
+      # remain local-only. Public playback always uses schema-default props.
+      def public_player!(autoplay: false, loop: true)
+        client_driven!
+        @public_player_options = { autoplay: autoplay == true, loop: loop == true }.freeze
+      end
+
+      def public_player?
+        @public_player_options.present?
+      end
+
+      def public_player_options
+        @public_player_options || { autoplay: false, loop: true }.freeze
+      end
+
+      def verification_props(*variants)
+        return @verification_props if variants.empty?
+
+        raise ArgumentError, "verification_props entries must be hashes" unless variants.all?(Hash)
+
+        @verification_props = variants.map(&:deep_symbolize_keys).freeze
+      end
+
+      def structure_epochs(*frames)
+        return @structure_epochs || [] if frames.empty?
+
+        @structure_epochs = frames.map(&:to_i).sort.uniq
+      end
+
+      def structure_layers
+        timeline.segments.each_with_index.flat_map do |segment, segment_index|
+          next [] unless segment.kind == :scene
+
+          segment_end = segment.duration_frames ? segment.from_frame + segment.duration_frames : duration_in_frames
+          epochs = structure_epochs.select { |frame| frame > segment.from_frame && frame < segment_end }
+          bounds = ([segment.from_frame] + epochs).sort.uniq
+          bounds.each_with_index.map do |from_frame, index|
+            Tracks::Layer.new(
+              segment:,
+              segment_index:,
+              from_frame:,
+              to_frame: bounds[index + 1] || segment_end
+            )
+          end
+        end
+      end
+
+      def render_structure(view_context, props: {})
+        resolved_props = props_schema.resolve(props)
+        rendered_layers = structure_layers.map do |layer|
+          context = frame_context(frame: layer.from_frame, props: resolved_props, segment: layer.segment)
+          view_context.tag.div(
+            render_segment(view_context, layer.segment, context),
+            class: "animate-it-layer",
+            data: { animate_layer: layer.key }
+          )
+        end
+        view_context.safe_join(rendered_layers)
+      end
+
+      def track_document(props: {})
+        Tracks::Recorder.new(self, props:).call
+      end
+
       def fps(value = nil)
         return @fps if value.nil?
 
@@ -114,6 +192,20 @@ module AnimateIt
         @beats ||= Beats.new(fps: fps)
       end
 
+      # Public, user-navigable moments. Chapters reference existing beats so
+      # animation timing stays the single source of truth.
+      def chapter(name, beat:, label:, metadata: {})
+        chapters.add(name, beat:, label:, metadata:)
+      end
+
+      def chapters
+        @chapters ||= Chapters.new(self)
+      end
+
+      def player_manifest
+        PlayerManifest.new(self)
+      end
+
       # ----- Outputs path helpers --------------------------------------
       # Declare a directory + basename so `outputs do ... end` entries can
       # be specified by format alone:
@@ -140,12 +232,16 @@ module AnimateIt
       # ----- Audio DSL --------------------------------------------------
       # Loop a track for the full duration (or a slice). Background music.
       def audio_loop(path, duration: nil, from: 0, name: nil, gain: 1.0, track: :background)
-        # Simplest implementation: place the same source once at `from`
-        # for the requested length. The renderer's audio mixer handles
-        # truncation if the underlying file is longer than the segment.
         length = duration || (@duration_in_frames - Units.frames(from, fps: fps))
-        audio(path, duration: length, from: from, name: name || "loop-#{File.basename(path.to_s)}", track: track,
-                    gain: gain)
+        audio(
+          path,
+          duration: length,
+          from:,
+          name: name || "loop-#{File.basename(path.to_s)}",
+          track:,
+          gain:,
+          loop: true
+        )
       end
 
       # Play a voice-over clip at a named beat (or time/frame). The clip's
@@ -212,14 +308,21 @@ module AnimateIt
       # Place an audio segment on its own track. The renderer doesn't draw
       # audio; the studio plays it via <audio> tags synced to the scrubber, and
       # ffmpeg muxes it into the final encode.
-      def audio(path, duration: nil, from: 0, start_at: nil, name: nil, track: :audio, gain: 1.0)
+      def audio(path, duration: nil, from: 0, start_at: nil, name: nil, track: :audio, gain: 1.0, loop: false)
+        begin
+          gain = Float(gain)
+        rescue TypeError, ArgumentError
+          raise ArgumentError, "Audio gain must be a number between 0.0 and 1.0"
+        end
+        raise ArgumentError, "Audio gain must be between 0.0 and 1.0" unless gain.between?(0.0, 1.0)
+
         timeline.add_segment(
           name: name || File.basename(path.to_s),
           from_frame: Units.frames(start_at || from, fps:),
           duration_frames: Units.frames(duration, fps:),
           kind: :audio,
           track:,
-          source: { path: path.to_s, gain: gain.to_f },
+          source: { path: path.to_s, gain:, loop: },
           show_in_timeline: true
         )
       end
@@ -246,14 +349,17 @@ module AnimateIt
         )
       end
 
-      def render_frame(view_context, frame:, props: {})
+      def render_frame(view_context, frame:, props: {}, segment_origins: false)
         resolved_props = props_schema.resolve(props)
         segments = timeline.active_segments(frame.to_i, kind: :scene)
         return "" if segments.empty?
 
         rendered_segments = segments.map do |segment|
           context = frame_context(frame:, props: resolved_props, segment:)
-          render_segment(view_context, segment, context)
+          content = render_segment(view_context, segment, context)
+          next content unless segment_origins
+
+          view_context.tag.div(content, data: { animate_it_segment_origin: segment.from_frame })
         end
         view_context.safe_join(rendered_segments)
       end

data/lib/animate_it/embed_helper.rb

@@ -0,0 +1,214 @@
+require "json"
+
+module AnimateIt
+  class EmbedBuilder
+    attr_reader :composition
+
+    def initialize(view, composition, navigation: {})
+      @view = view
+      @composition = composition
+      @navigation = navigation
+    end
+
+    def chapter_navigation(**attributes, &block)
+      custom = block.present?
+      preset = if attributes.key?(:preset)
+                 attributes.delete(:preset)
+               elsif !custom
+                 @navigation.fetch(:preset, :pills)
+               end
+      mobile = if attributes.key?(:mobile)
+                 attributes.delete(:mobile)
+               elsif !custom
+                 @navigation[:mobile]
+               end
+      style = ["--animate-it-chapter-count: #{@composition.chapters.count}", attributes.delete(:style)].compact.join(";")
+      ChapterNavigationBuilder.new(@view, @composition, interactive: true, preset:, mobile:, frame: 0)
+                              .render(**attributes, style:, &block)
+    end
+  end
+
+  module EmbedHelper
+    def animate_it_player(composition_id, title: nil, **attributes)
+      composition = public_animate_it_composition!(composition_id)
+      defaults = {
+        src: animate_it_public_player_path(composition),
+        title: title || composition.id,
+        loading: "lazy",
+        allow: "autoplay; fullscreen",
+        allowfullscreen: true,
+        style: "border:0;width:100%;aspect-ratio:#{composition.width}/#{composition.height}"
+      }
+      tag.iframe(**defaults, **attributes)
+    end
+
+    def animate_it_embed(
+      composition_id,
+      poster:,
+      variants: [],
+      navigation: { preset: :pills },
+      load_when_visible: 0.25,
+      play_when_visible: 2.0 / 3,
+      pause_offscreen: true,
+      reduced_motion: :poster,
+      autoplay: true,
+      title: nil,
+      **attributes,
+      &block
+    )
+      composition = public_animate_it_composition!(composition_id)
+      navigation = navigation == false ? false : (navigation || {}).to_h.deep_symbolize_keys
+      resolved_variants = resolve_animate_it_variants(composition, poster, variants)
+      validate_animate_it_variant_chapters!(resolved_variants)
+      manifest = animate_it_embed_manifest(
+        title: title || composition.id,
+        variants: resolved_variants,
+        load_when_visible:,
+        play_when_visible:,
+        pause_offscreen:,
+        reduced_motion:,
+        autoplay:
+      )
+      builder = EmbedBuilder.new(self, composition, navigation: navigation || {})
+      navigation_html = if navigation
+                          block ? capture(builder, &block) : builder.chapter_navigation(class: "animate-it-embed__navigation")
+                        end
+      classes = ["animate-it-embed", attributes.delete(:class)].compact.join(" ")
+      data = (attributes.delete(:data) || {}).merge(animate_it_embed: true)
+
+      safe_join(
+        [
+          stylesheet_link_tag(animate_it_embed_asset_path("embed.css"), data: { animate_it_embed_asset: "style" }),
+          javascript_include_tag(
+            animate_it_embed_asset_path("embed.js"), defer: true, data: { animate_it_embed_asset: "script" }
+          ),
+          tag.public_send("animate-it-embed", **attributes, class: classes, data:) do
+            safe_join([
+              navigation_html,
+              animate_it_embed_viewport(resolved_variants, title || composition.id),
+              tag.script(ERB::Util.json_escape(JSON.generate(manifest)).html_safe,
+                         type: "application/json", data: { animate_it_embed_manifest: true })
+            ].compact)
+          end
+        ]
+      )
+    end
+
+    private
+
+    def public_animate_it_composition!(composition_id)
+      AnimateIt.load_compositions!
+      composition = AnimateIt.registry.fetch(composition_id)
+      raise ArgumentError, "AnimateIt composition #{composition_id.inspect} is not public" unless composition.public_player?
+
+      composition
+    end
+
+    def animate_it_mount_prefix
+      respond_to?(:request) && request ? request.script_name.to_s : ""
+    end
+
+    def animate_it_public_player_path(composition)
+      id = ERB::Util.url_encode(composition.id)
+      "#{animate_it_mount_prefix}#{AnimateIt.config.mount_path}/public/compositions/#{id}/player"
+    end
+
+    def animate_it_embed_asset_path(filename)
+      version = ERB::Util.url_encode(AnimateIt::VERSION)
+      "#{animate_it_mount_prefix}#{AnimateIt.config.mount_path}/assets/#{version}/#{filename}"
+    end
+
+    def resolve_animate_it_variants(composition, poster, variants)
+      raise ArgumentError, "animate_it_embed requires a poster" if poster.blank?
+
+      primary = animate_it_variant_hash(composition, poster:, media: nil)
+      responsive = Array(variants).map do |variant|
+        attributes = variant.to_h.deep_symbolize_keys
+        target = public_animate_it_composition!(attributes.fetch(:composition))
+        media = attributes.fetch(:media).to_s
+        raise ArgumentError, "AnimateIt variant media query must not be blank" if media.blank?
+
+        animate_it_variant_hash(target, poster: attributes.fetch(:poster), media:)
+      end
+      duplicate_media = responsive.group_by { |variant| variant.fetch("media") }.select { |_media, group| group.many? }.keys
+      raise ArgumentError, "AnimateIt variant media queries must be unique: #{duplicate_media.join(", ")}" if duplicate_media.any?
+
+      [primary, *responsive]
+    end
+
+    def animate_it_variant_hash(composition, poster:, media:)
+      raise ArgumentError, "AnimateIt variant poster must not be blank" if poster.blank?
+
+      manifest = composition.player_manifest.as_json
+      {
+        "media" => media,
+        "composition" => manifest,
+        "poster" => poster.to_s,
+        "source" => animate_it_public_player_path(composition)
+      }
+    end
+
+    def validate_animate_it_variant_chapters!(variants)
+      expected = variants.first.dig("composition", "chapters").map { |chapter| chapter.values_at("name", "label") }
+      variants.drop(1).each do |variant|
+        actual = variant.dig("composition", "chapters").map { |chapter| chapter.values_at("name", "label") }
+        next if actual == expected
+
+        raise ArgumentError, "AnimateIt responsive variants must expose the same ordered chapter names and labels"
+      end
+    end
+
+    def animate_it_embed_manifest(title:, variants:, load_when_visible:, play_when_visible:, pause_offscreen:, reduced_motion:, autoplay:)
+      load_ratio = Float(load_when_visible)
+      play_ratio = Float(play_when_visible)
+      unless load_ratio.between?(0, 1) && play_ratio.between?(0, 1)
+        raise ArgumentError, "AnimateIt visibility thresholds must be between 0 and 1"
+      end
+      raise ArgumentError, "AnimateIt reduced_motion must be :poster" unless reduced_motion.to_s == "poster"
+
+      {
+        "version" => 1,
+        "title" => title,
+        "variants" => variants,
+        "options" => {
+          "loadWhenVisible" => load_ratio,
+          "playWhenVisible" => play_ratio,
+          "pauseOffscreen" => pause_offscreen == true,
+          "reducedMotion" => reduced_motion.to_s,
+          "autoplay" => autoplay == true,
+          "readyTimeout" => 5000,
+          "crossfadeDuration" => 120
+        }
+      }
+    rescue TypeError, ArgumentError => e
+      raise e if e.message.start_with?("AnimateIt")
+
+      raise ArgumentError, "AnimateIt visibility thresholds must be numbers between 0 and 1"
+    end
+
+    def animate_it_embed_viewport(variants, title)
+      primary = variants.first
+      sources = variants.drop(1).map do |variant|
+        tag.source(media: variant.fetch("media"), srcset: variant.fetch("poster"))
+      end
+      poster = tag.picture(
+        safe_join([*sources, image_tag(primary.fetch("poster"), alt: title, loading: "eager")]),
+        class: "animate-it-embed__poster", data: { animate_it_embed_poster: true }
+      )
+      viewport = tag.div(class: "animate-it-embed__viewport", data: { animate_it_embed_viewport: true }) do
+        safe_join(
+          [
+            poster,
+            tag.div(tag.div("", class: "animate-it-embed__frame", data: { animate_it_embed_frame: true }),
+                    class: "animate-it-embed__shell", data: { animate_it_embed_shell: true }),
+            tag.button(
+              "Play", type: "button", class: "animate-it-embed__control", hidden: true,
+                      data: { animate_it_embed_control: true }, aria: { label: "Play animation", pressed: "false" }
+            )
+          ]
+        )
+      end
+      safe_join([viewport, tag.noscript(image_tag(primary.fetch("poster"), alt: title))])
+    end
+  end
+end