shellfie 0.1.1 → 1.1.0

data/lib/shellfie/gif_generator.rb

@@ -1,6 +1,17 @@
 # frozen_string_literal: true
 
 require "mini_magick"
+require "fileutils"
+require "json"
+require "tmpdir"
+require_relative "animation_frame_builder"
+require_relative "dependency_checker"
+require_relative "format_resolver"
+require_relative "ffmpeg_encoder"
+require_relative "gif_palette"
+require_relative "image_magick_command_builder"
+require_relative "output_writer"
+require_relative "render_chrome_cache"
 require_relative "renderer"
 
 module Shellfie
@@ -11,141 +22,272 @@ module Shellfie
       @config = config
       @renderer = Renderer.new(config)
       @theme = @renderer.theme
+      @frame_builder = AnimationFrameBuilder.new(config)
     end
 
-    def generate(output_path, scale: 1, shadow: true)
+    def generate(output_path, scale: 1, shadow: true, transparent: false, format: nil, io: nil)
       check_dependencies!
 
-      frames = build_animation_frames
-      images = render_frames(frames, scale: scale, shadow: shadow)
-      combine_to_gif(images, output_path)
-      cleanup_temp_files(images)
-      output_path
+      images = []
+      chrome_cache = RenderChromeCache.new
+      begin
+        frames = playback_frames(coalesce_frames(build_animation_frames))
+        validate_frame_limit!(frames)
+        validate_workload!(frames, scale: scale, shadow: shadow)
+        warn_frame_count(frames)
+        images = render_frames(frames, scale: scale, shadow: shadow, transparent: transparent, chrome_cache: chrome_cache)
+        extension = FormatResolver.resolve(output_path, explicit: format, default: "gif")
+        return write_png_sequence(images, output_path) if extension == "png-sequence"
+
+        OutputWriter.write(output_path, extension: extension, io: io) do |temporary_path|
+          combine_to_animation(images, temporary_path, format: extension)
+        end
+      ensure
+        cleanup_temp_files(images)
+        chrome_cache.cleanup
+      end
+    rescue MiniMagick::Error => e
+      raise RenderError.new("ImageMagick animation render failed: #{e.message}", category: :render)
     end
 
     private
 
     def check_dependencies!
-      result = `which magick 2>/dev/null || which convert 2>/dev/null`.strip
-      if result.empty?
-        raise DependencyError, <<~MSG
-          ImageMagick not found
-            → Please install ImageMagick: brew install imagemagick
-            → Or visit: https://imagemagick.org/script/download.php
-        MSG
-      end
+      DependencyChecker.configure_mini_magick!
+      DependencyChecker.ensure_imagemagick!
     end
 
     def build_animation_frames
-      frames = []
-      current_lines = []
-      animation_settings = config.animation
-
-      config.frames.each do |frame|
-        if frame.type
-          typing_frames = build_typing_frames(
-            current_lines.dup,
-            frame.prompt || "",
-            frame.type,
-            animation_settings[:typing_speed] || 80
-          )
-          frames.concat(typing_frames)
-          current_lines << { prompt: frame.prompt, command: frame.type }
-        end
-
-        if frame.output
-          frame.output.split("\n").each do |line|
-            current_lines << { output: line }
-          end
-          frames << { lines: build_display_lines(current_lines), delay: frame.delay || 100 }
-        end
-
-        if frame.delay && frame.delay > 0 && !frame.output
-          frames << { lines: build_display_lines(current_lines), delay: frame.delay }
-        end
-      end
-
-      frames
-    end
-
-    def build_typing_frames(base_lines, prompt, command, typing_speed)
-      frames = []
-      chars = command.chars
-
-      chars.each_with_index do |_char, i|
-        typed = command[0..i]
-        lines = base_lines.dup
-        lines << { prompt: prompt, command: typed, cursor: true }
-        frames << { lines: build_display_lines(lines), delay: typing_speed }
-      end
-
-      final_lines = base_lines.dup
-      final_lines << { prompt: prompt, command: command }
-      frames << { lines: build_display_lines(final_lines), delay: typing_speed }
-
-      frames
+      @frame_builder.build
     end
 
-    def build_display_lines(lines_data)
-      lines_data.map do |line_data|
-        if line_data[:prompt]
-          text = "#{line_data[:prompt]}#{line_data[:command]}"
-          text += "█" if line_data[:cursor]
-          Line.new(prompt: text, command: nil, output: nil)
-        else
-          Line.new(prompt: nil, command: nil, output: line_data[:output])
-        end
-      end
+    def cursor_text
+      @frame_builder.cursor_text
     end
 
-    def render_frames(frames, scale:, shadow:)
+    def render_frames(frames, scale:, shadow:, transparent:, chrome_cache:)
       temp_dir = Dir.mktmpdir("shellfie")
       images = []
+      complete = false
+      visible_lines = fixed_visible_lines(frames)
 
       frames.each_with_index do |frame, idx|
-        frame_config = create_frame_config(frame[:lines])
-        renderer = Renderer.new(frame_config)
+        frame_config = create_frame_config(
+          frame[:lines],
+          window_overrides: { visible_lines: visible_lines }.merge(frame[:window] || {})
+        )
+        renderer = Renderer.new(frame_config, chrome_cache: chrome_cache)
         output_path = File.join(temp_dir, "frame_#{format("%04d", idx)}.png")
-        renderer.render(output_path, scale: scale, shadow: shadow)
+        renderer.render(output_path, scale: scale, shadow: shadow, transparent: transparent)
         images << { path: output_path, delay: frame[:delay] }
       end
 
+      complete = true
       images
+    ensure
+      FileUtils.rm_rf(temp_dir) if temp_dir && !complete
     end
 
-    def create_frame_config(lines)
+    def create_frame_config(lines, window_overrides: {})
       Config.new(
         theme: config.theme,
+        window_theme: config.window_theme,
+        color_scheme: config.color_scheme,
+        colors: config.colors,
+        window_decoration: config.window_decoration,
         title: config.title,
-        window: config.window,
+        window: config.window.merge(window_overrides),
         font: config.font,
         lines: lines,
+        animation: config.animation,
+        cursor: config.cursor,
+        limits: config.limits,
         headless: config.headless
       )
     end
 
-    def combine_to_gif(images, output_path)
-      MiniMagick.convert do |convert|
-        convert.dispose "none"
-        convert.loop config.animation[:loop] ? 0 : 1
+    def combine_to_animation(images, output_path, format:)
+      if %w[mp4 webm apng].include?(format)
+        DependencyChecker.ensure_ffmpeg!
+        return FfmpegEncoder.encode(
+          images,
+          output_path,
+          format: format,
+          command: DependencyChecker.ffmpeg_path,
+          framerate: config.animation[:framerate],
+          playback_speed: config.animation[:playback_speed],
+          loop: config.animation[:loop],
+          loop_count: config.animation[:loop_count],
+          apng_prediction: config.animation[:apng_prediction]
+        )
+      end
 
-        images.each do |img|
-          delay = (img[:delay] / 10.0).round
+      palette = GifPalette.new(config: config, theme: theme) if format == "gif"
+      ImageMagickCommandBuilder.convert do |convert|
+        convert.dispose "none" if format == "gif"
+        convert.loop animation_loop_count
+
+        animation_entries(images).each do |delay, img|
           convert.delay delay
           convert << img[:path]
         end
 
-        convert.dither "FloydSteinberg"
-        convert.colors 256
-        convert.layers "optimize"
-        convert << output_path
+        configure_animation_format(convert, format, images: images, palette: palette)
+        ImageMagickCommandBuilder.output(convert, output_path, format: format)
+      end
+    ensure
+      palette&.cleanup
+    end
+
+    def configure_animation_format(convert, format, images:, palette:)
+      case format
+      when "gif"
+        palette.apply(convert, images: images)
+        convert.layers "optimize" if config.animation[:gif_optimize]
+      when "webp"
+        convert.define "webp:lossless=#{config.animation[:webp_lossless]}"
+        convert.define "webp:method=#{config.animation[:webp_method]}"
+        convert.define "webp:near-lossless=#{config.animation[:webp_near_lossless]}"
+        convert.quality config.animation[:webp_quality]
       end
     end
 
+    def animation_loop_count
+      config.animation[:loop_count] || (config.animation[:loop] ? 0 : 1)
+    end
+
     def cleanup_temp_files(images)
-      images.each { |img| File.delete(img[:path]) if File.exist?(img[:path]) }
       temp_dir = File.dirname(images.first[:path]) if images.any?
-      Dir.rmdir(temp_dir) if temp_dir && Dir.exist?(temp_dir) && Dir.empty?(temp_dir)
+      FileUtils.rm_rf(temp_dir) if temp_dir && Dir.exist?(temp_dir)
+    end
+
+    def write_png_sequence(images, output_path)
+      if Dir.exist?(output_path) && !replaceable_sequence_directory?(output_path)
+        raise FileSystemError, "Refusing to replace a non-Shellfie directory: #{output_path}"
+      end
+
+      parent = File.dirname(File.expand_path(output_path))
+      FileUtils.mkdir_p(parent)
+      temporary = Dir.mktmpdir(".shellfie-sequence-", parent)
+      frames = images.each_with_index.map do |image, index|
+        filename = "frame_#{format("%04d", index)}.png"
+        FileUtils.cp(image[:path], File.join(temporary, filename))
+        { file: filename, delay_ms: image[:delay] / config.animation[:playback_speed] }
+      end
+      File.write(File.join(temporary, "timeline.json"), JSON.pretty_generate(version: 1, frames: frames))
+      backup = "#{temporary}-previous"
+      File.rename(output_path, backup) if File.exist?(output_path)
+      File.rename(temporary, output_path)
+      FileUtils.rm_rf(backup)
+      output_path
+    rescue StandardError
+      File.rename(backup, output_path) if backup && File.exist?(backup) && !File.exist?(output_path)
+      raise
+    ensure
+      FileUtils.rm_rf(temporary) if temporary && Dir.exist?(temporary)
+      FileUtils.rm_rf(backup) if backup && File.exist?(backup)
+    end
+
+    def replaceable_sequence_directory?(path)
+      entries = Dir.children(path)
+      return true if entries.empty?
+      return false unless entries.include?("timeline.json")
+
+      entries.all? { |entry| entry == "timeline.json" || entry.match?(/\Aframe_\d{4}\.png\z/) }
+    end
+
+    def animation_delays(images)
+      elapsed = 0.0
+      emitted = 0
+      images.map do |image|
+        elapsed += image[:delay] / config.animation[:playback_speed]
+        target = [(elapsed / 10.0).round, emitted + 1].max
+        (target - emitted).tap { emitted = target }
+      end
+    end
+
+    def animation_entries(images)
+      target_ticks = [(images.sum { |image| image[:delay] } / config.animation[:playback_speed] / 10.0).round, 1].max
+      return animation_delays(images).zip(images) if target_ticks >= images.size
+
+      elapsed = 0.0
+      ends = images.map { |image| elapsed += image[:delay] / config.animation[:playback_speed] }
+      indexes = (1..target_ticks).map do |tick|
+        ends.index { |finish| finish >= tick * 10 } || images.size - 1
+      end
+      indexes[-1] = images.size - 1
+      indexes.chunk(&:itself).map { |index, ticks| [ticks.size, images[index]] }
+    end
+
+    def warn_frame_count(frames)
+      max_frames = config.animation[:max_frames]
+      return unless max_frames && frames.size > max_frames
+
+      $stderr.puts "Warning: animation will generate #{frames.size} frames (max_frames is #{max_frames})"
+    end
+
+    def validate_frame_limit!(frames)
+      return if frames.size <= config.limits[:max_render_frames]
+
+      raise ResourceLimitError, "Animation would generate #{frames.size} frames (max #{config.limits[:max_render_frames]})"
+    end
+
+    def coalesce_frames(frames)
+      frames.each_with_object([]) do |frame, result|
+        if result.last && frame_key(result.last) == frame_key(frame)
+          result.last[:delay] += frame[:delay]
+        else
+          result << frame.merge(lines: frame[:lines].dup)
+        end
+      end
+    end
+
+    def frame_key(frame)
+      [frame[:lines].map(&:to_h), frame[:window]]
+    end
+
+    def playback_frames(frames)
+      frames = frames.reverse if config.animation[:direction] == "reverse"
+      offset = config.animation[:loop_offset]
+      if offset >= frames.size
+        raise ValidationError, "animation.loop_offset must be less than the #{frames.size} rendered frames"
+      end
+      frames = frames.rotate(offset)
+      return frames unless config.animation[:direction] == "ping_pong" && frames.size > 2
+
+      frames + frames[1...-1].reverse
+    end
+
+    def validate_workload!(frames, scale:, shadow:)
+      speed = Rational(config.animation[:playback_speed].to_s)
+      encoded_frames = (frames.sum { |frame| frame[:delay] } * config.animation[:framerate] / (1_000 * speed)).ceil
+      if encoded_frames > config.limits[:max_render_frames]
+        raise ResourceLimitError,
+              "Animation timeline would encode #{encoded_frames} frames (max #{config.limits[:max_render_frames]})"
+      end
+
+      visible_lines = fixed_visible_lines(frames)
+      max_pixels = frames.map do |frame|
+        frame_config = create_frame_config(frame[:lines], window_overrides: { visible_lines: visible_lines }.merge(frame[:window] || {}))
+        geometry = Renderer.new(frame_config).estimate(scale: scale, shadow: shadow)
+        geometry[:canvas_width] * geometry[:canvas_height]
+      end.max || 0
+      total_pixels = max_pixels * frames.size
+      if total_pixels > config.limits[:max_total_pixels]
+        raise ResourceLimitError,
+              "Animation workload is too large (#{total_pixels} pixels, max #{config.limits[:max_total_pixels]})"
+      end
+
+      estimated_bytes = total_pixels * 4
+      return if estimated_bytes <= config.limits[:max_temp_bytes]
+
+      raise ResourceLimitError,
+            "Animation temporary data is too large (#{estimated_bytes} bytes, max #{config.limits[:max_temp_bytes]})"
+    end
+
+    def fixed_visible_lines(frames)
+      config.window[:visible_lines] || [frames.map { |frame| frame[:lines].size }.max.to_i, 1].max
     end
+
   end
 end

data/lib/shellfie/gif_palette.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require_relative "image_magick_command_builder"
+
+module Shellfie
+  class GifPalette
+    def initialize(config:, theme:, command_builder: ImageMagickCommandBuilder)
+      @config = config
+      @theme = theme
+      @command_builder = command_builder
+      @temporary_files = []
+    end
+
+    def apply(convert, images: [])
+      convert.dither(dither_mode)
+
+      case @config.animation[:palette]
+      when "global"
+        apply_global_palette(convert, images)
+      when "theme"
+        apply_theme_palette(convert)
+      else
+        convert.colors color_count
+      end
+    end
+
+    def cleanup
+      @temporary_files.each { |file| file.close! if file.respond_to?(:close!) }
+      @temporary_files.clear
+    end
+
+    private
+
+    def apply_global_palette(convert, images)
+      palette_path = build_global_palette(images)
+      convert.remap palette_path if palette_path
+      convert.colors color_count
+    end
+
+    def apply_theme_palette(convert)
+      palette_path = build_theme_palette
+      convert.remap palette_path if palette_path
+      convert.colors(theme_color_count)
+    end
+
+    def build_global_palette(images)
+      return nil if images.empty?
+
+      path = palette_path
+      @command_builder.convert do |convert|
+        images.each { |image| convert << image[:path] }
+        convert.append
+        convert.colors 256
+        convert.unique_colors
+        @command_builder.output(convert, path, format: "png")
+      end
+      path
+    end
+
+    def build_theme_palette
+      colors = theme_colors.first(color_count)
+      return nil if colors.empty?
+
+      path = palette_path
+      @command_builder.convert do |convert|
+        @command_builder.canvas(convert, width: colors.size, height: 1, background: "xc:transparent")
+        colors.each_with_index do |color, index|
+          convert.fill color
+          @command_builder.point(convert, index, 0)
+        end
+        @command_builder.output(convert, path, format: "png")
+      end
+      path
+    end
+
+    def palette_path
+      file = Tempfile.new(["shellfie-palette", ".png"])
+      @temporary_files << file
+      file.close
+      file.path
+    end
+
+    def dither_mode
+      @config.animation[:dither] ? "FloydSteinberg" : "None"
+    end
+
+    def theme_color_count
+      [[theme_colors.size, [16, color_count].min].max, color_count].min
+    end
+
+    def theme_colors
+      @theme_colors ||= [
+        @theme.colors.values,
+        @theme.button_colors,
+        @theme.window_decoration.dig(:shadow, :color),
+        @theme.window_decoration[:border]
+      ].flatten.compact.uniq
+    end
+
+    def color_count
+      @config.animation[:gif_colors]
+    end
+  end
+end

data/lib/shellfie/headless_theme_registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "theme_data"
+
+module Shellfie
+  class HeadlessThemeRegistry
+    VARIANTS = {
+      "plain" => {
+        window_decoration: {
+          title_bar_height: 0,
+          corner_radius: 0,
+          button_size: 0,
+          button_spacing: 0
+        },
+        button_colors: [],
+        button_style: :none,
+        buttons_position: :left,
+        title_alignment: :left
+      }
+    }.freeze
+
+    class << self
+      def build(theme, variant: "plain")
+        settings = VARIANTS.fetch(variant)
+        ThemeData.new(
+          name: theme.name,
+          colors: theme.colors,
+          window_decoration: ThemeData.deep_merge(theme.window_decoration, settings[:window_decoration]),
+          button_colors: settings[:button_colors],
+          buttons_position: settings[:buttons_position],
+          button_style: settings[:button_style],
+          font: theme.font,
+          title_alignment: settings[:title_alignment]
+        )
+      end
+
+      def available_variants
+        VARIANTS.keys
+      end
+    end
+  end
+end

data/lib/shellfie/html_renderer.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require_relative "svg_renderer"
+
+module Shellfie
+  class HtmlRenderer
+    def initialize(config:, theme:)
+      @config = config
+      @svg_renderer = SvgRenderer.new(config: config, theme: theme)
+    end
+
+    def render(geometry, output_path, transparent: false)
+      svg = @svg_renderer.to_svg(geometry, transparent: transparent).sub(/\A<\?xml[^>]+>\s*/, "")
+      transcript = geometry[:lines].map { |line| line[:segments].map(&:text).join }.join("\n")
+      File.write(output_path, <<~HTML)
+        <!doctype html>
+        <html lang="en">
+        <head>
+          <meta charset="utf-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1">
+          <title>#{escape(@config.title)}</title>
+          <style>
+            :root { color-scheme: light dark; }
+            :root[data-theme="light"] { color-scheme: light; }
+            :root[data-theme="dark"] { color-scheme: dark; }
+            body { margin: 0; display: grid; min-height: 100vh; place-items: center; background: Canvas; }
+            main { max-width: 100%; overflow: auto; }
+            button { position: fixed; inset: 1rem 1rem auto auto; font: inherit; }
+            svg { display: block; max-width: 100%; height: auto; }
+            .transcript { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: pre; }
+          </style>
+        </head>
+        <body>
+          <button type="button" aria-label="Toggle color theme">Theme</button>
+          <main aria-label="#{escape(@config.title)}">#{svg}<pre class="transcript">#{escape(transcript)}</pre></main>
+          <script>
+            document.querySelector('button').addEventListener('click', () => {
+              const root = document.documentElement;
+              root.dataset.theme = root.dataset.theme === 'dark' ? 'light' : 'dark';
+            });
+          </script>
+        </body>
+        </html>
+      HTML
+    end
+
+    private
+
+    def escape(value)
+      CGI.escapeHTML(value.to_s)
+    end
+  end
+end

data/lib/shellfie/image_magick_command_builder.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "mini_magick"
+
+module Shellfie
+  class ImageMagickCommandBuilder
+    class << self
+      def convert(&block)
+        MiniMagick.convert(&block)
+      end
+
+      def canvas(convert, width:, height:, background:)
+        convert.size "#{width}x#{height}"
+        convert << background
+      end
+
+      def output(convert, path, format: nil)
+        convert << output_path(path, format: format || File.extname(path).delete_prefix("."))
+      end
+
+      def output_path(path, format:)
+        format == "apng" ? "apng:#{path}" : path
+      end
+
+      def draw(convert, command)
+        convert.draw command
+      end
+
+      def rectangle(convert, x1, y1, x2, y2)
+        draw(convert, "rectangle #{x1},#{y1} #{x2},#{y2}")
+      end
+
+      def rectangles(convert, rectangles)
+        return if rectangles.empty?
+
+        draw(convert, rectangles.map { |rect| "rectangle #{rect[:x1]},#{rect[:y1]} #{rect[:x2]},#{rect[:y2]}" }.join(" "))
+      end
+
+      def round_rectangle(convert, x1, y1, x2, y2, radius)
+        draw(convert, "roundrectangle #{x1},#{y1} #{x2},#{y2} #{radius},#{radius}")
+      end
+
+      def line(convert, x1, y1, x2, y2)
+        draw(convert, "line #{x1},#{y1} #{x2},#{y2}")
+      end
+
+      def lines(convert, lines)
+        return if lines.empty?
+
+        draw(convert, lines.map { |line| "line #{line[:x1]},#{line[:y1]} #{line[:x2]},#{line[:y2]}" }.join(" "))
+      end
+
+      def circle(convert, center_x, center_y, radius)
+        draw(convert, "circle #{center_x},#{center_y} #{center_x + radius},#{center_y}")
+      end
+
+      def point(convert, x, y)
+        draw(convert, "point #{x},#{y}")
+      end
+
+      def region(convert, x:, y:, width:, height:)
+        convert.region "#{width}x#{height}+#{x}+#{y}"
+      end
+
+      def clear_region(convert)
+        convert << "+region"
+      end
+
+      def composite_over(convert)
+        convert.compose "over"
+        convert.composite
+      end
+    end
+  end
+end