animate_it 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0675f1e382659072fd53a4b9453d2a44b1bf8a208075bc43974522195540df1f
-  data.tar.gz: c3804ff10fa75939fd23716e555054b64ea0ba45f1eaa9beb36c8b23e5b7c025
+  metadata.gz: 7ec5ae62f97bd3388e29dfc63ea1b7580a233973e2201873cbbed0ee7e9234ab
+  data.tar.gz: 7af5a47d46d966a785d89d13d0fc31dfa2a83945966481c6209beacb286c460d
 SHA512:
-  metadata.gz: 06fe263c48072dc834609a78c5f3f3f09a2897872740e11d54fd8edcf2dcd986113ae1338ffd941f491077de0c4a3feb100cda5b679ef161052c8cbe123a55f3
-  data.tar.gz: d2f7f86b39e2aa3308dc98e9e6cd5bc4956716e03e0e81cc2a5857892ac9f1dea584634b13f3632450561285f361dbb3491964ac58a10296118e2a1375499b26
+  metadata.gz: 49f073e22fe939dd1223d91bce55a364da6923e9ad458580f98f4369d618b4d43dd7cb981c5925699ea1a6bab72834482caadfb14a5bf115182358d054926ba3
+  data.tar.gz: 2c066b3b7a44093330743a0f4e88a0fdc309388eed285d67dfcb4b65554c0af7722df1a5581fd112ec29eae277f184b33d4f36462c8a0fe62f6e4f129e0a764c

data/CHANGELOG.md

@@ -6,6 +6,66 @@ 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
+- Declarative schema-v2 track recording for sampled CSS variables, dynamic
+  text, word reveals, and compact keyframe tracks.
+- Browser-driven `/player` playback and export. Client-driven compositions
+  render once per structural layer and seek deterministically without a Rails
+  request for every frame.
+- `client_driven!`, `structure_epochs`, `track_vars`, `text_track`,
+  `verification_props`, and deterministic native CSS/Web Animation seeking.
+- Secure production frontend playback with explicit `public_player!`
+  allowlisting, a responsive `animate_it_player` iframe helper, autonomous
+  Play/Pause/loop transport, and synchronized byte-range audio.
+- Player-versus-filmstrip verification with RGB and alpha comparison, props
+  matrices, structural-boundary sampling, and an every-frame `verify_all` gate.
+- Checksum and provenance preflight for host-owned composition source assets.
+
+### Changed
+- Studio playback and seeking use the same client runtime as export for
+  client-driven compositions.
+- Animated outputs preserve declared audio trim, loop, gain, and partial-range
+  alignment; GIF and PNG outputs remain silent.
+- PNG sequences are published to their declared destination directory.
+- Declared outputs covering the same frame range now share one browser capture
+  instead of repeating every screenshot for each output format.
+- Removed the no-op Studio render-concurrency settings; capture remains
+  sequential so ordering, progress, and cancellation are deterministic.
+
+### Compatibility
+- Continued support for Ruby >= 3.3, Rails >= 7.2, HAML >= 6.3, HAML and ERB
+  sidecars, the packaged renderer executable, configurable mount paths and host
+  stylesheets, and the Rails 7.2 / Rails 8.1 appraisal matrix.
+
 ## [0.3.2] - 2026-07-23
 
 ### Fixed
@@ -63,7 +123,9 @@ 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.3.2...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
 [0.3.0]: https://github.com/growth-constant/animate_it/compare/v0.2.0...v0.3.0

data/README.md

@@ -11,9 +11,9 @@
 </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.4-CC342D.svg" alt="Ruby >= 3.4">
+  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.3-CC342D.svg" alt="Ruby >= 3.3">
 </p>
 
 ---
@@ -22,16 +22,27 @@
 **AnimateIt brings the same idea to Ruby on Rails** — without React, a JavaScript
 project, or a video editor.
 
-You describe a video as a Ruby class and a HAML template, preview it frame-by-frame
-in a bundled **Studio** UI, and render it to MP4/WebM/MOV/GIF. Every frame is a real
-web page, so you get the full power of CSS and — crucially — **your app's own
-components, styles, fonts, and real data**. A headless browser captures each frame
-and FFmpeg stitches them into a video.
+You describe a video as a Ruby class and a HAML or ERB template, preview it in a
+bundled **Studio** UI, and render it to MP4/WebM/MOV/GIF. The declarative runtime
+renders the template once per structural layer, records compact animation tracks,
+and seeks those tracks in the browser. You still get your app's own components,
+styles, fonts, and real data without asking Rails to render every frame.
 
 It's built for indie hackers and Rails developers who want to promote their projects
 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)
@@ -72,10 +83,16 @@ and reload in development.
 # app/videos/hello_video.rb
 class HelloVideo < AnimateIt::Composition
   id "hello"
+  client_driven!
   fps 30
   size 1080, 1080
   duration 3.seconds
 
+  props do
+    integer :counter_start, default: 0
+  end
+  verification_props({}, { counter_start: 100 })
+
   assets_dir "app/assets/images/videos"
   output_basename "hello"
 
@@ -88,9 +105,16 @@ class HelloVideo < AnimateIt::Composition
   beat :intro, at: 0, length: 45
 
   class Scene < AnimateIt::Scene
+    track_vars :root do
+      { title_opacity: at_act(:intro, [0, 30], [0, 1]) }
+    end
+
+    text_track(:counter) { (props[:counter_start] + local_frame).to_s }
+
     def body
-      expose(vars: animation_vars(title_opacity: at_act(:intro, [0, 30], [0, 1])))
-      tag.div(class: "hero-render-canvas") { render_scene_template("canvas") }
+      absolute_fill(vars: :root) do
+        safe_join([render_scene_template("canvas"), animate_text(:counter)])
+      end
     end
   end
 
@@ -102,14 +126,142 @@ end
 -# app/videos/hello_video/canvas.html.haml
 :css
   .title { opacity: var(--title-opacity, 1); font-size: 6rem; font-weight: 800; }
-.stage{style: @vars}
+.stage
   .title Hello 👋
 ```
 
-Animation helpers (`at_global`, `at_act`, `beat_frame`, `beat_range`), a per-frame
-CSS-variable bag (`animation_vars`), named `beat`s, and `audio` / `audio_loop`
-tracks are all available. Compositions can render your app's real partials and
-ViewComponents — see `AnimateIt.config.render_stylesheets` below.
+Animation helpers (`at_global`, `at_act`, `beat_frame`, `beat_range`), sampled
+CSS variables (`track_vars`), dynamic text (`text_track`), named `beat`s, and
+`audio` / `audio_loop` tracks are available. Compositions can render your app's
+real partials and ViewComponents — see `AnimateIt.config.render_stylesheets`
+below.
+
+### Browser playback runtime
+
+`client_driven!` switches export and Studio playback to `/player`. Rails renders
+each structural layer once and records a schema-v2 track document; then
+`window.__animateIt.setFrame(frame)` updates CSS variables, text, layer
+visibility, word reveals, and native CSS/Web Animations without another frame
+request.
+
+Use `structure_epochs` only when a template's DOM shape changes. Each epoch adds
+one pre-rendered layer. Track schema v2 scopes bindings to their timeline segment;
+the player still accepts v1 documents and rejects unknown versions.
+
+```ruby
+structure_epochs 60, 120
+
+class Scene < AnimateIt::Scene
+  track_vars(:card) { { x: "#{at_global([0, 30], [-20, 0])}px" } }
+  text_track(:score) { (progress * 100).round }
+
+  def body
+    absolute_fill(vars: :card) do
+      safe_join([render_scene_template("canvas"), animate_text(:score)])
+    end
+  end
+end
+```
+
+### Production frontend playback
+
+Public playback is opt-in per composition. `public_player!` enables the
+standalone browser clock, Play/Pause control, looping, and synchronized
+music/voice/SFX. It does not expose Studio, frame, filmstrip, props, or render
+endpoints, and public playback always uses the composition's default props.
+
+```ruby
+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
+```
+
+Mount the engine in every environment, then embed the allowlisted composition
+from a host view:
+
+```ruby
+# config/routes.rb
+mount AnimateIt::Engine, at: AnimateIt.config.mount_path
+```
+
+```erb
+<%= animate_it_player "hello", title: "Hello product demo" %>
+```
+
+`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
 
@@ -118,9 +270,9 @@ Scene sidecar templates can be authored in **HAML** (`canvas.html.haml`) or
 mix engines across scenes. The HAML canvas above is equivalent to:
 
 ```erb
--# app/videos/hello_video/canvas.html.erb
+<%# app/videos/hello_video/canvas.html.erb %>
 <style>.title { opacity: var(--title-opacity, 1); font-size: 6rem; font-weight: 800; }</style>
-<div class="stage" style="<%= @vars %>">
+<div class="stage">
   <div class="title">Hello 👋</div>
 </div>
 ```
@@ -130,8 +282,9 @@ app to use it — ERB-only apps work out of the box.
 
 ## Rendering
 
-The renderer needs your Rails **server running** (it drives a real browser against
-the Studio's filmstrip endpoint).
+The renderer needs your Rails **server running**. It drives a real browser
+against `/player` for client-driven compositions and the legacy `/filmstrip`
+endpoint for other compositions.
 
 ```bash
 # start the app
@@ -141,6 +294,10 @@ bin/rails server
 bin/rails 'animate_it:render[hello]'
 bin/rails 'animate_it:render[hello,0..45]'   # just a frame range
 
+# compare /player with the legacy /filmstrip (step 1 checks every frame)
+bin/rails 'animate_it:verify[hello,1]'
+bin/rails animate_it:verify_all
+
 # or the packaged CLI (writes to tmp/animate_it/ by default)
 bundle exec render_animate_it_video hello
 bundle exec render_animate_it_video hello tmp/hello.mp4
@@ -173,8 +330,42 @@ AnimateIt.configure do |config|
 end
 ```
 
-Render concurrency for the Studio's background renderer is tunable via
-`ANIMATE_IT_RENDER_CONCURRENCY` and `ANIMATE_IT_RENDER_STARTS_PER_SECOND`.
+When one composition declares multiple formats for the same frame range,
+AnimateIt captures the ordered Chromium frames once and reuses them for each
+encoder. Studio rendering intentionally keeps one sequential capture stream so
+frame ordering, progress, and cancellation stay deterministic.
+
+## Deterministic asset preflight
+
+Host applications can record local composition inputs in
+`config/animate_it_assets.yml`. `bin/rails animate_it:preflight` checks that each
+file exists, matches its SHA-256 checksum, and has a provenance provider. Media
+stays in the host app and is not packaged in the gem.
+
+```yaml
+version: 1
+assets:
+  - path: app/audio/launch/music.mp3
+    kind: music
+    compositions: [hello]
+    sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
+    provenance:
+      provider: elevenlabs
+      generated_with_ai: true
+      model_id: not-recorded
+      generation_id: not-recorded
+```
+
+For parameterized compositions, declare `verification_props` or override them
+at the command line:
+
+```bash
+ANIMATE_IT_PROPS_JSON='{"title":"Variant"}' bin/rails 'animate_it:verify[hello,1]'
+ANIMATE_IT_PROPS_MATRIX_JSON='[{}, {"title":"Variant"}]' bin/rails animate_it:verify_all
+```
+
+Verification requires a running server and writes comparison screenshots under
+`tmp/animate_it/verify`.
 
 ## Claude skill
 
@@ -195,6 +386,7 @@ The skill source lives in [`skills/`](skills/).
 bin/setup                # bundle install
 bundle exec rspec        # unit + request specs (uses spec/dummy)
 bundle exec rubocop
+gem build animate_it.gemspec
 
 # full render smoke test (needs ffmpeg + Playwright chromium)
 RUN_RENDER_SMOKE=1 bundle exec rspec spec/rendering_spec.rb

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

@@ -18,5 +18,15 @@ module AnimateIt
       @composition = composition
       @props = preview_props
     end
+
+    def player
+      @composition = composition
+      @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

@@ -0,0 +1,73 @@
+module AnimateIt
+  # The only production-accessible AnimateIt surface. Compositions must opt in
+  # explicitly with `public_player!`; all Studio and rendering controllers keep
+  # their local-environment guard.
+  class PublicPlayersController < ApplicationController
+    AUDIO_BASE = Rails.root.join("app/audio").freeze
+
+    layout false
+    skip_before_action :ensure_local_environment
+    before_action :ensure_public_player
+
+    def show
+      @props = {}
+      @track_document = composition.track_document
+      TrackDocumentSchema.validate!(@track_document)
+      @player_manifest = composition.player_manifest
+      @audio_segments = audio_segments
+      @public_player = true
+      @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
+
+    def audio
+      segment = audio_segments[params[:index].to_i]
+      return head :not_found unless segment
+
+      file_path = resolve_audio_path(segment.source[:path])
+      return head :not_found unless file_path
+
+      serve_with_byte_ranges(file_path)
+    end
+
+    private
+
+    def ensure_public_player
+      head :not_found unless composition.public_player? && composition.client_driven?
+    end
+
+    def audio_segments
+      @audio_segments ||= composition.timeline.segments.select { |segment| segment.kind == :audio }
+    end
+
+    def public_audio_path(index)
+      animate_it_path("/public/compositions/#{composition.id}/audio/#{index}")
+    end
+    helper_method :public_audio_path
+
+    def serve_with_byte_ranges(file_path)
+      status, headers, body = Rack::Files.new(file_path.dirname.to_s).serving(request, file_path.to_s)
+      headers["content-type"] = Mime::Type.lookup_by_extension(file_path.extname.delete(".")).to_s
+      headers["content-disposition"] = "inline"
+      headers["accept-ranges"] = "bytes"
+      self.status = status
+      self.response_body = body
+      headers.each { |key, value| response.headers[key] = value }
+    end
+
+    def resolve_audio_path(path)
+      return if path.blank?
+
+      base = AUDIO_BASE.realpath
+      candidate = Pathname.new(path)
+      candidate = base.join(candidate) unless candidate.absolute?
+      resolved = candidate.realpath
+      resolved if resolved.to_s.start_with?("#{base}#{File::SEPARATOR}")
+    rescue Errno::ENOENT, Errno::EACCES
+      nil
+    end
+  end
+end

data/app/controllers/animate_it/renders_controller.rb

@@ -32,7 +32,7 @@ module AnimateIt
         output_path: @output_path
       )
       start_render(@render_id, @composition.id, request.base_url, @output_path.to_s, frames_dir(@render_id).to_s,
-                   preview_props, render_options)
+                   preview_props)
 
       render status: :accepted
     end
@@ -57,24 +57,10 @@ module AnimateIt
       path&.relative_path_from(Rails.root)&.to_s
     end
 
-    def render_options
-      {
-        "concurrency" => env_with_legacy("ANIMATE_IT_RENDER_CONCURRENCY", "RAILS_MOTION_RENDER_CONCURRENCY", "3").to_i,
-        "starts_per_second" => env_with_legacy("ANIMATE_IT_RENDER_STARTS_PER_SECOND",
-                                               "RAILS_MOTION_RENDER_STARTS_PER_SECOND", "2").to_f
-      }
-    end
-
-    # Prefer the new ANIMATE_IT_* name; fall back to the legacy RAILS_MOTION_*
-    # name for one release so existing setups don't break, then the default.
-    def env_with_legacy(new_key, legacy_key, default)
-      ENV[new_key].presence || ENV[legacy_key].presence || default
-    end
-
-    def start_render(render_id, composition_id, host, output_path, frame_dir, props, options)
+    def start_render(render_id, composition_id, host, output_path, frame_dir, props)
       Thread.new do
         Rails.application.executor.wrap do
-          RenderJob.perform_now(render_id, composition_id, host, output_path, frame_dir, props, options)
+          RenderJob.perform_now(render_id, composition_id, host, output_path, frame_dir, props)
         end
       end
     end

data/app/controllers/animate_it/studio_controller.rb

@@ -9,6 +9,7 @@ module AnimateIt
       @composition = composition
       @compositions = AnimateIt.compositions
       @frame_base_url = animate_it_path("/compositions/#{@composition.id}/frame")
+      @player_url = animate_it_path("/compositions/#{@composition.id}/player")
       @last_frame = @composition.duration_in_frames - 1
       @props_json = JSON.pretty_generate(@composition.props.defaults)
       @renders = RenderStore.all

data/app/jobs/animate_it/render_job.rb

@@ -2,6 +2,8 @@ module AnimateIt
   class RenderJob < ApplicationJob
     queue_as :default
 
+    # `_options` remains as a compatibility slot for render jobs serialized by
+    # releases that exposed concurrency settings but never applied them.
     def perform(render_id, composition_id, host, output_path, frames_dir, props = {}, _options = {})
       AnimateIt.load_compositions!
       composition = AnimateIt.registry.fetch(composition_id)

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

@@ -24,6 +24,9 @@
       body, main, .hero-render-canvas {
         background-color: transparent !important;
       }
+      *, *::before, *::after {
+        transition: none !important;
+      }
       .animate-it-frame {
         position: absolute;
         inset: 0;
@@ -40,26 +43,54 @@
   %body
     - (0...@composition.duration_in_frames).each do |frame|
       .animate-it-frame{ class: ('is-active' if frame.zero?), data: { frame: frame } }
-        = @composition.render_frame(self, frame: frame, props: @props)
+        = @composition.render_frame(self, frame: frame, props: @props, segment_origins: true)
     -# See app/views/animate_it/frames/show.html.haml for why these are at the
     -# bottom of body. Host-app accumulator helpers — emit only when present.
     - if respond_to?(:render_page_stylesheets)
       = render_page_stylesheets
     - if respond_to?(:render_component_stylesheets)
       = render_component_stylesheets
+    = javascript_tag AnimateIt::Runtime.source.html_safe
     :javascript
       (() => {
         const frames = Array.from(document.querySelectorAll(".animate-it-frame"));
+        const segmentRoots = new WeakMap();
+        frames.forEach((frame) => {
+          const segments = Array.from(frame.querySelectorAll(":scope > [data-animate-it-segment-origin]"));
+          segmentRoots.set(frame, segments.map((segment) => {
+            const entry = {
+              origin: Number(segment.dataset.animateItSegmentOrigin) || 0,
+              roots: Array.from(segment.children)
+            };
+            segment.replaceWith(...segment.childNodes);
+            return entry;
+          }));
+        });
         let active = frames[0] || null;
         window.__animateIt = {
           totalFrames: frames.length,
           setFrame(n) {
-            const target = frames[n];
-            if (!target || target === active) return;
-            if (active) active.classList.remove("is-active");
-            target.classList.add("is-active");
-            active = target;
+            const frame = Math.max(0, Math.min(frames.length - 1, Math.round(Number(n) || 0)));
+            const target = frames[frame];
+            if (!target) return frame;
+            if (target !== active) {
+              if (active) active.classList.remove("is-active");
+              target.classList.add("is-active");
+              active = target;
+            }
+            const segments = segmentRoots.get(target) || [];
+            if (segments.length) {
+              segments.forEach((segment) => {
+                segment.roots.forEach((root) => {
+                  window.AnimateItRuntimeApi.seekAnimations(root, frame - segment.origin, #{@composition.fps});
+                });
+              });
+            } else {
+              window.AnimateItRuntimeApi.seekAnimations(target, frame, #{@composition.fps});
+            }
+            return frame;
           }
         };
+        window.__animateIt.setFrame(0);
         document.documentElement.dataset.animateItReady = "1";
       })();