shellfie 1.0.0 → 1.1.0

data/lib/shellfie/dependency_checker.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "rbconfig"
+require "open3"
+require "tempfile"
+require_relative "font_resolver"
 
 module Shellfie
   class DependencyChecker
@@ -15,6 +18,25 @@ module Shellfie
         !imagemagick_path.to_s.empty?
       end
 
+      def ffmpeg_path
+        @ffmpeg_path ||= find_executable(%w[ffmpeg], verify_imagemagick: false)
+      end
+
+      def ensure_ffmpeg!
+        return if ffmpeg_path
+
+        raise DependencyError, "ffmpeg not found; install ffmpeg to generate APNG, MP4, or WebM"
+      end
+
+      def ffmpeg_version
+        return unless ffmpeg_path
+
+        output, = Open3.capture3(ffmpeg_path, "-version")
+        output.lines.first&.strip
+      rescue SystemCallError
+        nil
+      end
+
       def ensure_imagemagick!
         return if imagemagick_available?
 
@@ -32,21 +54,48 @@ module Shellfie
       end
 
       def doctor(output_dir: Dir.pwd)
+        details = imagemagick_details
+        video_version = ffmpeg_version
         [
           check("Ruby", RUBY_VERSION, Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("3.0.0")),
-          check("ImageMagick", imagemagick_path || "not found", imagemagick_available?),
+          check("ImageMagick", details[:version] || "not found", imagemagick_available?),
+          check("Image formats", details[:formats].empty? ? "unavailable" : details[:formats].join(", "),
+                (required_formats - details[:formats]).empty?),
+          check("Image render", details[:render_ok] ? "1x1 PNG generated" : "failed", details[:render_ok]),
+          check("Fonts", details[:font_count].to_s, details[:font_count].positive?),
+          check("Security policy", details[:policy] || "unavailable", !details[:policy].nil?),
+          check("ffmpeg (optional)", video_version || "not found; required only for APNG/MP4/WebM", true),
           check("Writable output", output_dir, File.writable?(output_dir)),
           check("Encoding", Encoding.default_external.name, true)
         ]
       end
 
+      def imagemagick_details
+        return { version: nil, formats: [], font_count: 0, render_ok: false, policy: nil } unless imagemagick_available?
+
+        version_output, _error, version_status = Open3.capture3(imagemagick_path, "-version")
+        formats_output, _error, formats_status = Open3.capture3(imagemagick_path, "-list", "format")
+        fonts_output, _error, fonts_status = Open3.capture3(imagemagick_path, "-list", "font")
+        policy_output, _error, policy_status = Open3.capture3(imagemagick_path, "-list", "policy")
+        {
+          version: version_status.success? ? version_output.lines.first&.strip : nil,
+          formats: formats_status.success? ? required_formats.select { |format| formats_output.match?(/^\s*#{format}\*?\s/im) } : [],
+          font_count: (fonts_status.success? ? fonts_output.scan(/^\s*Font:/).size : 0) +
+            FontResolver::FONT_FILES.values.uniq.count { |path| File.file?(path) },
+          render_ok: render_smoke_test,
+          policy: policy_status.success? ? "#{policy_output.scan(/^\s*Policy:/).size} rules loaded" : nil
+        }
+      rescue SystemCallError
+        { version: nil, formats: [], font_count: 0, render_ok: false, policy: nil }
+      end
+
       private
 
       def check(name, detail, ok)
         { name: name, detail: detail, ok: ok }
       end
 
-      def find_executable(names)
+      def find_executable(names, verify_imagemagick: true)
         paths = ENV.fetch("PATH", "").split(File::PATH_SEPARATOR)
         extensions = executable_extensions
 
@@ -54,7 +103,9 @@ module Shellfie
           paths.each do |path|
             extensions.each do |extension|
               candidate = File.join(path, "#{name}#{extension}")
-              return candidate if File.file?(candidate) && File.executable?(candidate)
+              next unless File.file?(candidate) && File.executable?(candidate)
+              return candidate unless verify_imagemagick
+              return candidate if imagemagick_executable?(candidate)
             end
           end
         end
@@ -62,6 +113,26 @@ module Shellfie
         nil
       end
 
+      def imagemagick_executable?(candidate)
+        output, = Open3.capture3(candidate, "-version")
+        output.include?("ImageMagick")
+      rescue SystemCallError
+        false
+      end
+
+      def required_formats
+        %w[PNG GIF WEBP SVG]
+      end
+
+      def render_smoke_test
+        Tempfile.create(["shellfie-doctor", ".png"]) do |file|
+          _output, _error, status = Open3.capture3(imagemagick_path, "-size", "1x1", "xc:none", file.path)
+          return status.success? && File.binread(file.path, 8) == "\x89PNG\r\n\x1a\n".b
+        end
+      rescue SystemCallError, EOFError
+        false
+      end
+
       def executable_extensions
         return [""] unless windows?
 

data/lib/shellfie/errors.rb

@@ -22,4 +22,5 @@ module Shellfie
 
   class DependencyError < Error; end
   class FileSystemError < Error; end
+  class ExecutionError < Error; end
 end

data/lib/shellfie/ffmpeg_encoder.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+require_relative "errors"
+
+module Shellfie
+  class FfmpegEncoder
+    def self.encode(images, output_path, format:, command:, framerate:, playback_speed:, loop:, loop_count: nil,
+                    apng_prediction: nil)
+      list = Tempfile.new(["shellfie-frames", ".txt"])
+      minimum_delay = 1_000.0 / framerate
+      images.each do |image|
+        list.puts "file '#{image[:path].gsub("'", "'\\''")}'"
+        list.puts "duration #{[image[:delay].to_f, minimum_delay].max / 1_000.0 / playback_speed}"
+      end
+      list.puts "file '#{images.last[:path].gsub("'", "'\\''")}'"
+      list.close
+
+      total_duration = images.sum { |image| [image[:delay].to_f, minimum_delay].max } / 1_000.0 / playback_speed
+      filters = ["fps=#{framerate}"]
+      codec = case format
+              when "mp4"
+                filters << "pad=ceil(iw/2)*2:ceil(ih/2)*2"
+                %w[-c:v libx264 -pix_fmt yuv420p -movflags +faststart]
+              when "webm"
+                filters << "pad=ceil(iw/2)*2:ceil(ih/2)*2"
+                %w[-c:v libvpx-vp9 -pix_fmt yuva420p]
+              when "apng"
+                filters << "format=rgba"
+                options = ["-plays", (loop_count || (loop ? 0 : 1)).to_s]
+                options.concat(["-pred", apng_prediction]) if apng_prediction
+                options.concat(["-f", "apng"])
+              else raise RenderError, "Unsupported ffmpeg format: #{format}"
+              end
+      timing = ["-vf", filters.join(","), "-fps_mode", "cfr", "-t", total_duration.to_s]
+      _stdout, stderr, status = Open3.capture3(command, "-y", "-f", "concat", "-safe", "0", "-i", list.path,
+                                               *timing, *codec, output_path)
+      raise RenderError, "ffmpeg encode failed: #{stderr}" unless status.success?
+
+      output_path
+    ensure
+      list&.close!
+    end
+  end
+end

data/lib/shellfie/font_resolver.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "open3"
+require "digest"
+
 module Shellfie
   class FontResolver
     FONT_FILES = {
@@ -31,6 +34,12 @@ module Shellfie
                 .find { |candidate| font_available?(candidate) }
     end
 
+    def details(font_config)
+      { regular: resolve(font_config, italic: false), italic: resolve(font_config, italic: true) }.transform_values do |font|
+        { name: font, sha256: File.file?(font.to_s) ? Digest::SHA256.file(font).hexdigest : nil }
+      end
+    end
+
     private
 
     def font_available?(font)
@@ -50,7 +59,8 @@ module Shellfie
         if command.empty?
           []
         else
-          `#{command} -list font 2>/dev/null`.scan(/^\s*Font:\s+(.+)$/).flatten
+          stdout, = Open3.capture3(command, "-list", "font")
+          stdout.scan(/^\s*Font:\s+(.+)$/).flatten
         end
       end
     end

data/lib/shellfie/gif_generator.rb

@@ -2,10 +2,12 @@
 
 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"
@@ -23,18 +25,21 @@ module Shellfie
       @frame_builder = AnimationFrameBuilder.new(config)
     end
 
-    def generate(output_path, scale: 1, shadow: true, transparent: false, format: nil)
+    def generate(output_path, scale: 1, shadow: true, transparent: false, format: nil, io: nil)
       check_dependencies!
 
       images = []
       chrome_cache = RenderChromeCache.new
       begin
-        frames = build_animation_frames
+        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")
-        OutputWriter.write(output_path, extension: extension) do |temporary_path|
+        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
@@ -63,16 +68,24 @@ module Shellfie
     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], window_overrides: frame[:window] || {})
+        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, 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, window_overrides: {})
@@ -94,13 +107,28 @@ module Shellfie
     end
 
     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
+
       palette = GifPalette.new(config: config, theme: theme) if format == "gif"
       ImageMagickCommandBuilder.convert do |convert|
         convert.dispose "none" if format == "gif"
-        convert.loop config.animation[:loop] ? 0 : 1
+        convert.loop animation_loop_count
 
-        images.each do |img|
-          convert.delay gif_delay(img[:delay])
+        animation_entries(images).each do |delay, img|
+          convert.delay delay
           convert << img[:path]
         end
 
@@ -115,19 +143,80 @@ module Shellfie
       case format
       when "gif"
         palette.apply(convert, images: images)
-        convert.layers "optimize"
+        convert.layers "optimize" if config.animation[:gif_optimize]
       when "webp"
-        convert.define "webp:lossless=true"
+        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)
       temp_dir = File.dirname(images.first[:path]) if images.any?
       FileUtils.rm_rf(temp_dir) if temp_dir && Dir.exist?(temp_dir)
     end
 
-    def gif_delay(milliseconds)
-      [(milliseconds / 10.0).round, 1].max
+    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)
@@ -143,5 +232,62 @@ module Shellfie
       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

@@ -21,7 +21,7 @@ module Shellfie
       when "theme"
         apply_theme_palette(convert)
       else
-        convert.colors 256
+        convert.colors color_count
       end
     end
 
@@ -35,7 +35,7 @@ module Shellfie
     def apply_global_palette(convert, images)
       palette_path = build_global_palette(images)
       convert.remap palette_path if palette_path
-      convert.colors 256
+      convert.colors color_count
     end
 
     def apply_theme_palette(convert)
@@ -59,7 +59,7 @@ module Shellfie
     end
 
     def build_theme_palette
-      colors = theme_colors.first(256)
+      colors = theme_colors.first(color_count)
       return nil if colors.empty?
 
       path = palette_path
@@ -86,7 +86,7 @@ module Shellfie
     end
 
     def theme_color_count
-      [[theme_colors.size, 16].max, 256].min
+      [[theme_colors.size, [16, color_count].min].max, color_count].min
     end
 
     def theme_colors
@@ -97,5 +97,9 @@ module Shellfie
         @theme.window_decoration[:border]
       ].flatten.compact.uniq
     end
+
+    def color_count
+      @config.animation[:gif_colors]
+    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/line_layout.rb

@@ -39,8 +39,8 @@ module Shellfie
 
     def vertical_line_limit(title_bar_height, padding, line_height)
       limits = [@config.window[:visible_lines], @config.window[:max_lines]].compact
-      if @config.window[:max_height]
-        available_height = @config.window[:max_height] - title_bar_height - padding * 2
+      [@config.window[:height], @config.window[:max_height]].compact.each do |height|
+        available_height = height - title_bar_height - padding * 2
         limits << [(available_height / line_height).floor, 1].max
       end
 
@@ -58,8 +58,8 @@ module Shellfie
       used_cells = 0
 
       line[:segments].each do |segment|
-        segment.text.to_s.each_char do |char|
-          width = TextMetrics.char_width(char)
+        TextMetrics.graphemes(segment.text).each do |char|
+          width = TextMetrics.grapheme_width(char, ambiguous_width: ambiguous_width)
           if used_cells.positive? && used_cells + width > max_cells
             wrapped << { segments: [], selected: line[:selected] }
             used_cells = 0
@@ -78,29 +78,29 @@ module Shellfie
       segments.each_with_object([]) do |segment, result|
         break result if remaining <= 0
 
-        text = TextMetrics.take_cells(segment.text, remaining)
+        text = TextMetrics.take_cells(segment.text, remaining, ambiguous_width: ambiguous_width)
         next if text.empty?
 
         result << copy_segment(segment, text)
-        remaining -= TextMetrics.cell_width(text)
+        remaining -= TextMetrics.cell_width(text, ambiguous_width: ambiguous_width)
       end
     end
 
     def scroll_segments(segments, max_cells)
-      total_cells = segments.sum { |segment| TextMetrics.cell_width(segment.text) }
+      total_cells = segments.sum { |segment| TextMetrics.cell_width(segment.text, ambiguous_width: ambiguous_width) }
       return clip_segments(segments, max_cells) if total_cells <= max_cells
 
       cells_to_drop = total_cells - max_cells
       scrolled = []
 
       segments.each do |segment|
-        segment_cells = TextMetrics.cell_width(segment.text)
+        segment_cells = TextMetrics.cell_width(segment.text, ambiguous_width: ambiguous_width)
         if cells_to_drop >= segment_cells
           cells_to_drop -= segment_cells
           next
         end
 
-        text = cells_to_drop.positive? ? TextMetrics.drop_cells(segment.text, cells_to_drop) : segment.text
+        text = cells_to_drop.positive? ? TextMetrics.drop_cells(segment.text, cells_to_drop, ambiguous_width: ambiguous_width) : segment.text
         cells_to_drop = 0
         scrolled << copy_segment(segment, text) unless text.empty?
       end
@@ -127,11 +127,20 @@ module Shellfie
         segment.bold,
         segment.italic,
         segment.underline,
+        segment.underline_style,
+        segment.underline_color,
         segment.dim,
         segment.reverse,
         segment.strikethrough,
-        segment.overline
+        segment.overline,
+        segment.blink,
+        segment.conceal,
+        segment.link
       ]
     end
+
+    def ambiguous_width
+      @config.window[:ambiguous_width]
+    end
   end
 end

data/lib/shellfie/output_writer.rb

@@ -7,13 +7,18 @@ require "tmpdir"
 module Shellfie
   class OutputWriter
     class << self
-      def write(path, extension:)
+      def write(path, extension:, io: nil)
         FileUtils.mkdir_p(output_directory(path)) unless stdout?(path)
         temp = Tempfile.new(["shellfie", ".#{extension}"], output_directory(path), binmode: true)
         temp.close
         yield temp.path
 
-        return File.binread(temp.path) if stdout?(path)
+        if stdout?(path)
+          return File.binread(temp.path) unless io
+
+          File.open(temp.path, "rb") { |source| IO.copy_stream(source, io) }
+          return path
+        end
 
         FileUtils.mv(temp.path, path)
         path