animate_it 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72d2eaa2997ddbdf969a2f9abaed9632439891facecc856352a9f24228895d58
-  data.tar.gz: 78e5d03556d7af69c22179095ef5ffd3d6c87622797e5ff6b114e87ee4411fe5
+  metadata.gz: 7ec5ae62f97bd3388e29dfc63ea1b7580a233973e2201873cbbed0ee7e9234ab
+  data.tar.gz: 7af5a47d46d966a785d89d13d0fc31dfa2a83945966481c6209beacb286c460d
 SHA512:
-  metadata.gz: 5031e03befe521c448ed4a68f4a7ef1774e5609286b6ee1f6f94ca5daf719c74a2adf852b79c18b8d2d297ad91572f7d7300077e1c7641eb46d2e5fefa8fa4ca
-  data.tar.gz: 29ce4f2eb2d61720a38815190ed173cd8f16bfde8b5c07e32fc5c7c42bfafc3e7b4c06121a574ff7941fe542ac5dc3a528166b486279e7e2d9a6a92f5350904c
+  metadata.gz: 49f073e22fe939dd1223d91bce55a364da6923e9ad458580f98f4369d618b4d43dd7cb981c5925699ea1a6bab72834482caadfb14a5bf115182358d054926ba3
+  data.tar.gz: 2c066b3b7a44093330743a0f4e88a0fdc309388eed285d67dfcb4b65554c0af7722df1a5581fd112ec29eae277f184b33d4f36462c8a0fe62f6e4f129e0a764c

data/CHANGELOG.md

@@ -6,6 +6,33 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-13
+
+### Added
+- User-navigable `chapter` declarations backed by existing beats, with a
+  versioned player manifest and normalized progress/state variables.
+- `animate_it_embed`, a poster-first custom-element embed with responsive
+  composition variants, proportional scaling, readiness crossfade, visibility
+  playback, offscreen pausing, reduced-motion fallback, and accessible controls.
+- Headless Rails chapter builders for arbitrary controls plus optional desktop
+  and mobile-carousel pill presets and canvas-side chapter navigation.
+- Stable transport commands and `ready`, `framechange`, `chapterchange`, `play`,
+  `pause`, `ended`, and `error` events over a source-checked same-origin message
+  protocol.
+- Versioned, immutable JavaScript and CSS endpoints that work independently of
+  Stimulus and the host application's asset pipeline.
+
+### Changed
+- Public player readiness now waits for fonts, eager images, and two paint
+  frames. `AnimateItTransport` remains available as a compatibility alias.
+- Repository and package metadata now point at `joinbuildit/animate_it`.
+- Every automated GitHub release now publishes the matching curated changelog
+  section as its release description and fails safely when that entry is missing.
+
+### Compatibility
+- `animate_it_player`, track schema v2, existing compositions, Studio playback,
+  and video rendering remain backward compatible.
+
 ## [0.4.0] - 2026-08-01
 
 ### Added
@@ -96,7 +123,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `render_animate_it_video` executable and `animate_it:render` rake task.
 - `animate_it:install` generator.
 
-[Unreleased]: https://github.com/joinbuildit/animate_it/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/joinbuildit/animate_it/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/joinbuildit/animate_it/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/joinbuildit/animate_it/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/joinbuildit/animate_it/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/joinbuildit/animate_it/compare/v0.3.0...v0.3.1

data/README.md

@@ -11,7 +11,7 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/growth-constant/animate_it/actions/workflows/ci.yml"><img src="https://github.com/growth-constant/animate_it/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/joinbuildit/animate_it/actions/workflows/ci.yml"><img src="https://github.com/joinbuildit/animate_it/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://rubygems.org/gems/animate_it"><img src="https://img.shields.io/gem/v/animate_it.svg" alt="Gem Version"></a>
   <img src="https://img.shields.io/badge/ruby-%3E%3D%203.3-CC342D.svg" alt="Ruby >= 3.3">
 </p>
@@ -32,6 +32,17 @@ It's built for indie hackers and Rails developers who want to promote their proj
 with polished product demos, launch clips, and social ads — reusing the UI they've
 already built, staying in Ruby, and skipping the whole "learn a video editor" detour.
 
+<p align="center">
+  <img src="assets/animate-it-demo.gif" alt="AnimateIt turns a Ruby composition into smooth, seekable browser animation" width="640">
+</p>
+
+<p align="center">
+  <em>A five-second Ruby composition rendered by AnimateIt's client-driven browser runtime.</em><br>
+  <a href="https://github.com/joinbuildit/animate_it/blob/main/spec/dummy/app/videos/readme_demo_video.rb">View the Ruby composition</a>
+  ·
+  <a href="https://github.com/joinbuildit/animate_it/blob/main/spec/dummy/app/videos/readme_demo_video/canvas.html.erb">View the HTML/CSS template</a>
+</p>
+
 ## Requirements
 
 - Ruby >= 3.3, Rails >= 7.2 (tested against Rails 7.2 and 8.1)
@@ -163,6 +174,10 @@ endpoints, and public playback always uses the composition's default props.
 class HelloVideo < AnimateIt::Composition
   id "hello"
   public_player! autoplay: false, loop: true
+  beat :intro, at: 0, length: 45
+  beat :details, at: 45, length: 45
+  chapter :intro, beat: :intro, label: "Intro"
+  chapter :details, beat: :details, label: "Details"
   # ...
 end
 ```
@@ -179,9 +194,74 @@ mount AnimateIt::Engine, at: AnimateIt.config.mount_path
 <%= animate_it_player "hello", title: "Hello product demo" %>
 ```
 
-The iframe renders each structural layer once and advances entirely in the
-browser. Audio-capable players fall back to the visible Play button when the
-browser blocks autoplay.
+`animate_it_player` remains the low-level responsive iframe. For a complete
+production embed with accessible chapter navigation, a poster-first handoff,
+visibility playback, reduced-motion behavior, and offscreen pausing, use:
+
+```erb
+<%= animate_it_embed(
+  "hello",
+  poster: image_path("hello.webp"),
+  variants: [
+    {
+      media: "(max-width: 767px)",
+      composition: "hello-mobile",
+      poster: image_path("hello-mobile.webp")
+    }
+  ],
+  navigation: { preset: :pills, mobile: :carousel },
+  load_when_visible: 0.25,
+  play_when_visible: 2.0 / 3
+) %>
+```
+
+Responsive compositions may use different sizes and chapter frames, but must
+declare the same ordered chapter names and labels. The embed swaps by media
+query and restores the current chapter by name.
+
+The pill rail is optional. Build cards, tabs, thumbnails, dots, or custom SVG
+with the headless Rails builder:
+
+```erb
+<%= animate_it_embed("hello", poster: image_path("hello.webp")) do |embed| %>
+  <%= embed.chapter_navigation(class: "product-demo-cards") do |chapter| %>
+    <%= chapter.button(class: "product-demo-card") do %>
+      <strong><%= chapter.label %></strong>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+Every control receives `data-chapter-state`, `data-chapter-position`, and the
+normalized CSS variables `--animate-it-chapter-progress`,
+`--animate-it-chapter-active`, and `--animate-it-chapter-complete`. The player
+emits `animateit:ready`, `animateit:framechange`, `animateit:chapterchange`,
+`animateit:play`, `animateit:pause`, `animateit:ended`, and `animateit:error`
+events. Host commands use a source-checked same-origin message
+boundary instead of reaching into iframe globals.
+
+For direct player integrations, `window.AnimateItPlayer` exposes `play`,
+`pause`, `toggle`, `seek`, `seekChapter`, `playing`, and `currentFrame`.
+`window.AnimateItTransport` remains an alias for compatibility with 0.4.
+
+To include the same chapter visualization in Studio and rendered media:
+
+```erb
+<%= animate_it_chapter_navigation preset: :pills, hide_when_embedded: true %>
+```
+
+The iframe still renders each structural layer once and advances entirely in
+the browser. Audio-capable players fall back to the visible Play button when
+the browser blocks autoplay.
+
+### Migrating a custom iframe controller
+
+Replace application-owned iframe scaling, `IntersectionObserver`, poster
+crossfade, breakpoint swapping, frame polling, and `contentWindow` transport
+calls with `animate_it_embed`. Keep application CSS by overriding the documented
+`--animate-it-*` tokens or render completely custom chapter controls through the
+headless builder. Continue using `animate_it_player` when the application truly
+needs to own the entire lifecycle.
 
 ### HAML or ERB
 

data/app/controllers/animate_it/embed_assets_controller.rb

@@ -0,0 +1,25 @@
+module AnimateIt
+  class EmbedAssetsController < ApplicationController
+    layout false
+    skip_before_action :ensure_local_environment
+    skip_forgery_protection
+
+    def javascript
+      serve_asset(EmbedRuntime.javascript, "application/javascript")
+    end
+
+    def stylesheet
+      serve_asset(EmbedRuntime.stylesheet, "text/css")
+    end
+
+    private
+
+    def serve_asset(source, content_type)
+      return head :not_found unless params[:version] == AnimateIt::VERSION
+
+      expires_in 1.year, public: true, immutable: true
+      response.set_header("X-Content-Type-Options", "nosniff")
+      render plain: source, content_type:
+    end
+  end
+end

data/app/controllers/animate_it/frames_controller.rb

@@ -24,6 +24,9 @@ module AnimateIt
       @props = preview_props
       @track_document = @composition.track_document(props: @props)
       TrackDocumentSchema.validate!(@track_document)
+      @player_manifest = @composition.player_manifest
+      @embedded_player = false
+      @host_navigation = false
     end
   end
 end

data/app/controllers/animate_it/public_players_controller.rb

@@ -13,9 +13,13 @@ module AnimateIt
       @props = {}
       @track_document = composition.track_document
       TrackDocumentSchema.validate!(@track_document)
+      @player_manifest = composition.player_manifest
       @audio_segments = audio_segments
       @public_player = true
-      @public_player_options = composition.public_player_options
+      @embedded_player = params[:embedded] == "1"
+      @host_navigation = params[:host_navigation] == "1"
+      @public_player_options = composition.public_player_options.merge(autoplay: false) if @embedded_player
+      @public_player_options ||= composition.public_player_options
       render "animate_it/frames/player"
     end
 

data/app/views/animate_it/frames/player.html.haml

@@ -1,5 +1,8 @@
 !!!
-%html{ lang: "en" }
+%html{ lang: "en", data: {
+  animate_it_embedded: @embedded_player ? "true" : "false",
+  animate_it_host_navigation: @host_navigation ? "true" : "false"
+} }
   %head
     %title= "#{@composition.id} player (#{@composition.duration_in_frames} frames)"
     %meta{ name: "viewport", content: "width=#{@composition.width}, initial-scale=1" }
@@ -52,6 +55,12 @@
         font: 600 14px/1 system-ui, sans-serif;
         cursor: pointer;
       }
+      html[data-animate-it-host-navigation="true"] [data-animate-it-hide-when-embedded="true"] {
+        display: none !important;
+      }
+      html[data-animate-it-embedded="true"] .animate-it-public-play {
+        display: none !important;
+      }
   %body
     .animate-it-stage
       = @composition.render_structure(self, props: @props)
@@ -78,4 +87,6 @@
       animate_it_loop: @public_player_options&.fetch(:loop, true) ? "true" : "false"
     } }
       != ERB::Util.json_escape(@track_document.to_json)
+    %script{ type: "application/json", data: { animate_it_manifest: true } }
+      != ERB::Util.json_escape(@player_manifest.as_json.to_json)
     = javascript_tag AnimateIt::Runtime.source.html_safe

data/config/routes.rb

@@ -1,4 +1,9 @@
 AnimateIt::Engine.routes.draw do
+  get "assets/:version/embed.js", to: "embed_assets#javascript", as: :embed_javascript,
+                                  constraints: { version: /[0-9A-Za-z._-]+/ }
+  get "assets/:version/embed.css", to: "embed_assets#stylesheet", as: :embed_stylesheet,
+                                   constraints: { version: /[0-9A-Za-z._-]+/ }
+
   root "studio#index"
 
   get "public/compositions/:id/player", to: "public_players#show", as: :public_composition_player

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

@@ -16,6 +16,7 @@ module AnimateIt
         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
 
@@ -191,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: