flipbook 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed6c3ae7ae41a6819cbd15890ebe7002b9637c2a2afb51e1f185ac7cf4c4b39c
-  data.tar.gz: 59c4fcbf5f6fce4baa22c359a54334d873403bf2ee6904ab483770cca41a5ab1
+  metadata.gz: 9873e25f97a747f0f45e26e9eb9c503228d6b2daa975a8976f64480c1b3e0ba0
+  data.tar.gz: 90bfb6579e71d4fdea9035fe86561fcde8a4911acb56f9ce8414136d0004abd6
 SHA512:
-  metadata.gz: 3047e42608ce4f1d5653fa4573fc2d9c210e5b732557bb65cf2f41f8087aa8f6b81c1a3e895f4cadc3e03c8c83b532bfaa8ea51a47bd557bcf890bd0fb42e949
-  data.tar.gz: 44abccb00089ba9fe0d6b16657c36c2967d506a69e923e42d31971260b09461d405f755e3d195f6fd5a50aadea68971686b0ba101217d1b74bf524887183f375
+  metadata.gz: eb493019ec22fce32d0f4741bd1db36dbc8403b1528b267f8abb94b99865de2ceed88f50e24efdf145f760de33ea1526ce5206d258b6739043135a87da2ead85
+  data.tar.gz: e9a8476651fbfbe0cf0ff3a8092b0a7c0d3b9ee80a50c95a9a3ae8e0394c8275c84f5be424ce7ed65bcfa722a1002546e98d2f57ae630dd5cd599608caedb937

data/CHANGELOG.md

@@ -1,7 +1,20 @@
 # Changelog
 
-## [0.3.0] - 2026-09-24
+## [0.4.0] - 2026-09-25
 
-- Add GIF89a encoding, animated PNG encoding, and GIF decoding.
-- Add streaming writers, cumulative frame timing, palette quantization, transparency, and frame-difference output.
-- Add the `Flipbook.write` and `Flipbook.read` APIs.
+- Read composited GIF frames with configurable image, frame, and total-pixel limits.
+- Improve APNG writing and changed-region encoding.
+
+## [0.3.0] - 2026-09-25
+
+- Add GIF reading with LZW decoding, interlace handling, frame composition, and disposal methods.
+- Clear transparent GIF frames correctly and retain delta cropping for opaque animations.
+
+## [0.2.0] - 2026-09-25
+
+- Add APNG writing with rational frame delays, alpha, and changed-region cropping.
+- Crop unchanged regions in opaque GIF frames to reduce animation size.
+
+## [0.1.0] - 2026-09-25
+
+Initial release

data/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">Flipbook</h1>
 
-<p align="center">Turn a sequence of RGBA images into animated GIF or APNG files.</p>
+<p align="center">Write optimized animated GIF and APNG files from Ruby images.</p>
 
 <p align="center">
   <a href="https://rubygems.org/gems/flipbook"><img src="https://badge.fury.io/rb/flipbook.svg" alt="Gem version"></a>
@@ -8,20 +8,20 @@
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-750014.svg" alt="License"></a>
 </p>
 
-[Formats](#formats) · [Installation](#installation) · [API](#api) · [Development](#development)
+[Formats](#formats) · [Installation](#installation) · [API](#api) · [Examples](#examples) · [Development](#development)
 
 ---
 
-Flipbook writes animated GIF and APNG from [`Tessel::Image`](https://github.com/rbgfx/tessel) frames. GIF palettes use Tessel's shared quantizer. The library has no runtime dependency beyond Tessel and Ruby's standard library.
+Flipbook writes animated GIFs and APNGs from [`Tessel::Image`](https://github.com/rbgfx/tessel) frames. GIF palettes use Tessel's shared quantizer; APNG keeps full RGBA color. Both writers can crop unchanged frame regions.
 
 ## Formats
 
-| Format | Color | Transparency | Reading |
+| Format | Colors | Transparency | Encoding |
 | --- | --- | --- | --- |
-| GIF | Up to 256 palette entries | One transparent palette index | GIF87a/GIF89a frames, local and global palettes, interlace, and disposal methods |
-| APNG | RGBA8 | Full alpha | First frame through Tessel's PNG reader |
+| GIF | Up to 256 palette entries | One transparent palette index | GIF89a output with global or per-frame palettes and LZW |
+| APNG (`.png`, `.apng`) | Full RGBA | Full alpha | PNG-compatible first frame, `acTL` / `fcTL` / `fdAT` animation chunks |
 
-GIF uses a single global palette by default so colors stay stable across frames. Animated frames with transparent pixels are written as full frames with background disposal so pixels can become transparent correctly. Opaque animations use difference rectangles by default.
+GIF uses a single global palette by default so colors stay stable across frames. Use `palette: :per_frame` when streaming frames with different color ranges. Delta cropping is most effective for opaque GIF frames; APNG supports alpha-safe cropped updates.
 
 ## Installation
 
@@ -43,9 +43,6 @@ frames = 60.times.map do |index|
 end
 
 Flipbook.write("animation.gif", frames, fps: 30, loop: true)
-Flipbook.write("animation.png", frames, fps: 30, loop: true)
-
-decoded_frames = Flipbook.read("animation.gif")
 ~~~
 
 Use `delay:` in seconds instead of `fps:`. It accepts one duration or one duration per frame; `Rational(1, 30)` avoids floating-point timing drift. GIF delays use cumulative centisecond rounding. Viewers may lengthen delays below 1/50 second.
@@ -58,15 +55,41 @@ Flipbook::GIF::Writer.open("recording.gif", width: 320, height: 240, palette: :p
 end
 ~~~
 
-APNG also supports streaming output and patches its frame count when the destination can seek. Otherwise it buffers the animation until close.
+Use a `.png` or `.apng` path for full-color animation. The first frame remains a valid PNG for viewers that do not animate APNG:
+
+~~~ruby
+Flipbook.write("animation.png", frames, fps: 30, loop: true)
+~~~
+
+`optimize: false` writes full-size frames. The default crops each changed frame to its smallest bounding rectangle. GIF cropping is used for opaque frames; APNG cropping preserves alpha changes.
+
+Read GIFs as full-canvas `Tessel::Image` frames. The reader applies frame offsets, transparency, interlacing, and disposal before returning:
+
+~~~ruby
+frames = Flipbook.read("animation.gif")
+~~~
+
+`max_pixels:`, `max_frames:`, and `max_total_pixels:` can lower the decoder's resource limits for untrusted files.
 
 ### API contracts
 
-- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects. The `.gif` extension selects GIF; `.png` and `.apng` select APNG.
-- `Flipbook.read(path)` returns composited GIF frames as `Tessel::Image` objects. `Flipbook::GIF::Reader#delays` returns each frame delay as a `Rational` in seconds.
-- `GIF::Writer#add` and `APNG::Writer#add` raise `TypeError` for non-image frames and `ArgumentError` for invalid dimensions or timing.
+- `Flipbook.write(path, frames, fps: or delay:)` requires one or more same-sized `Tessel::Image` objects and a `.gif`, `.png`, or `.apng` output path.
+- `GIF::Writer#add` raises `TypeError` for non-image frames and `ArgumentError` for invalid dimensions or timing.
+- `APNG::Writer#add` accepts positive numeric delays in seconds and raises for frames that do not match the canvas dimensions.
+- `Flipbook.read(path)` returns fully composited GIF frames and rejects malformed streams or files over its configured limits.
 - GIF palette colors are RGB triples of integer channels from 0 to 255. GIF transparency is binary; partial alpha is encoded as an opaque palette color.
-- APNG chunks use RGBA8 pixels. The first frame is also a valid static PNG image.
+
+## Examples
+
+Generate a rotating square, a color gradient, and transparent GIF/APNG samples:
+
+~~~sh
+ruby examples/generate.rb
+~~~
+
+![A blue square rotating in an animated GIF](docs/assets/spinning-square.gif)
+
+Pass an output directory as the first argument to choose where the files are written.
 
 GIF format acknowledgement: The Graphics Interchange Format© is the Copyright property of CompuServe Incorporated. GIF® is a Service Mark property of CompuServe Incorporated.
 

data/docs/index.html

@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#101318">
+<meta name="description" content="Write optimized animated GIF and APNG files from Ruby images with Flipbook.">
+<title>Flipbook — animation from Ruby frames</title>
+<style>
+:root{color-scheme:dark;--bg:#101318;--panel:#181e27;--line:#2b3441;--text:#f1f4f8;--muted:#9ca9b8;--accent:#38bdf8;--mono:ui-monospace,SFMono-Regular,Menlo,monospace;--sans:Inter,ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
+*{box-sizing:border-box}body{margin:0;background:radial-gradient(ellipse at 75% -12%,#16384c,transparent 45%),var(--bg);color:var(--text);font:16px/1.65 var(--sans)}a{color:inherit;text-decoration:none}a:hover{color:var(--accent)}.wrap{width:min(1080px,calc(100% - 40px));margin:auto}.nav{height:76px;display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid var(--line)}.brand{font-size:20px;font-weight:750;letter-spacing:-.04em}.brand span,.label{color:var(--accent)}.links{display:flex;gap:24px;color:var(--muted);font-size:14px}.hero{padding:84px 0 72px;display:grid;grid-template-columns:1fr .82fr;align-items:center;gap:56px}.label{font:12px var(--mono);text-transform:uppercase;letter-spacing:.14em}h1{font-size:clamp(48px,7vw,78px);line-height:.99;letter-spacing:-.075em;margin:18px 0}.hero p{font-size:18px;color:var(--muted);max-width:600px}.actions{display:flex;gap:12px;flex-wrap:wrap;margin:28px 0 22px}.button{padding:10px 16px;border:1px solid var(--line);border-radius:5px;font-weight:650}.primary{color:#061820;background:var(--accent);border-color:var(--accent)}.install{display:inline-flex;gap:16px;background:#090d12;border:1px solid var(--line);border-radius:6px;padding:12px 15px;font:14px var(--mono)}.install span{color:#6c7886}.visual{padding:20px;border:1px solid var(--line);border-radius:10px;background:linear-gradient(145deg,#1b2632,#11171e);box-shadow:0 24px 80px #0007;transform:rotate(1deg)}.window{height:34px;border-bottom:1px solid var(--line);margin:-2px 0 16px;display:flex;align-items:center;gap:7px}.dot{width:8px;height:8px;border-radius:50%;background:#566170}.filename{margin-left:8px;color:var(--muted);font:11px var(--mono)}.visual img{display:block;width:100%;border-radius:5px;image-rendering:auto}.caption{display:flex;justify-content:space-between;color:var(--muted);font:11px var(--mono);padding:12px 2px 0}.section{border-top:1px solid var(--line);padding:42px 0 66px}.section h2{font-size:28px;letter-spacing:-.04em;margin:8px 0}.section>p{color:var(--muted);max-width:650px}.formats{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin-top:24px}.card{background:var(--panel);border:1px solid var(--line);border-radius:8px;overflow:hidden}.card img{display:block;width:100%;height:200px;object-fit:contain;background:#0b1016;padding:18px}.cardbody{padding:16px 18px}.card h3{margin:0;font-size:16px}.card p{color:var(--muted);font-size:14px;margin:5px 0 0}.code{background:#090d12;border:1px solid var(--line);border-radius:7px;padding:18px;overflow:auto;font:14px/1.8 var(--mono);color:#d5eaf5}.foot{border-top:1px solid var(--line);padding:24px 0 36px;display:flex;justify-content:space-between;gap:16px;color:var(--muted);font-size:13px}
+@media(max-width:740px){.hero{grid-template-columns:1fr;gap:32px;padding:66px 0 54px}.visual{max-width:500px}.links{gap:14px}.formats{grid-template-columns:1fr}.foot{flex-direction:column}}
+</style>
+</head>
+<body><div class="wrap">
+<nav class="nav" aria-label="Main navigation"><a class="brand" href="#top">flip<span>book</span></a><div class="links"><a href="#formats">Formats</a><a href="https://github.com/rbgfx/flipbook">GitHub</a><a href="https://rubygems.org/gems/flipbook">RubyGems</a></div></nav>
+<main id="top">
+<section class="hero"><div><div class="label">Animation from Ruby frames</div><h1>Every frame<br>in its place.</h1><p>Write optimized animated GIF and APNG files from Tessel images. Keep GIF palettes steady, preserve full-color alpha in APNG, and crop unchanged frame regions.</p><div class="actions"><a class="button primary" href="https://github.com/rbgfx/flipbook#api">Explore the API ↗</a><a class="button" href="https://github.com/rbgfx/flipbook/tree/main/examples">See examples</a></div><div class="install"><span>$</span> gem install flipbook</div></div><div class="visual"><div class="window"><i class="dot"></i><i class="dot"></i><i class="dot"></i><span class="filename">spinning-square.gif</span></div><img src="assets/spinning-square.gif" alt="A blue square rotating on a dark background"><div class="caption"><span>GIF · 12 FPS</span><span>24 frames</span></div></div></section>
+<section class="section" id="formats"><div class="label">Pick the right format</div><h2>Palette animation or full color</h2><p>Use GIF for compact, broadly supported animations; choose APNG when full RGBA color and partial transparency matter.</p><div class="formats"><article class="card"><img src="assets/gradient.gif" alt="A blue-to-red color gradient"><div class="cardbody"><h3>GIF · up to 256 palette colors</h3><p>Global palettes keep colors consistent. Per-frame palettes are available for streaming.</p></div></article><article class="card"><img src="assets/transparent.png" alt="An animated pink circle with transparent background"><div class="cardbody"><h3>APNG · full RGBA</h3><p>A standard PNG first frame, with full alpha and optimized animated updates.</p></div></article></div></section>
+<section class="section"><div class="label">Quick start</div><h2>Write from Tessel frames</h2><pre class="code"><code>require "flipbook"
+
+frames = 60.times.map do |index|
+  image = Tessel::Image.new(320, 240, fill: "#101827")
+  image.fill_rect(index * 4 % 320, 100, 32, 32, "#38bdf8")
+  image
+end
+
+Flipbook.write("animation.gif", frames, fps: 30, loop: true)
+Flipbook.write("animation.png", frames, fps: 30, loop: true)</code></pre></section>
+</main><footer class="foot"><span>Flipbook · Animated GIF and APNG for Ruby</span><span><a href="https://github.com/rbgfx/flipbook">Source</a> · MIT License</span></footer>
+</div></body>
+</html>

data/docs/verification.md

@@ -1,14 +1,16 @@
 # File verification
 
-The test suite checks GIF LZW code-width growth and dictionary resets, decodes generated animations, and validates APNG chunk ordering and sequence numbers.
+The test suite checks GIF LZW code-width growth and dictionary resets, frame composition and disposal, resource limits, frame timing, transparent palette entries, cropped frame bounds, APNG sequence numbers, and PNG chunk CRCs.
 
-For an independent local check, install ImageMagick or gifsicle and inspect sample output:
+For an independent local check, install ImageMagick, FFmpeg, or gifsicle and inspect sample output:
 
 ~~~sh
-identify animation.gif animation.png
+identify animation.gif
 magick animation.gif -coalesce /tmp/flipbook-gif-%02d.png
-magick animation.png -coalesce /tmp/flipbook-apng-%02d.png
 gifsicle --info animation.gif
+magick identify animation.png
+ffprobe -v error -count_frames -select_streams v:0 \\
+  -show_entries stream=codec_name,nb_read_frames animation.png
 ~~~
 
 These tools are optional and are not runtime dependencies.

data/examples/generate.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "flipbook"
+
+output = ARGV.fetch(0, "examples/output")
+FileUtils.mkdir_p(output)
+
+frames = 24.times.map do |frame|
+  image = Tessel::Image.new(160, 120, fill: "#111827")
+  angle = frame * Math::PI / 12
+  cos = Math.cos(angle)
+  sin = Math.sin(angle)
+  (35...125).each do |y|
+    (55...105).each do |x|
+      dx = x - 80
+      dy = y - 60
+      next unless (dx * cos + dy * sin).abs <= 17 && (-dx * sin + dy * cos).abs <= 17
+
+      image[x, y] = [56, 189, 248, 255]
+    end
+  end
+  image
+end
+Flipbook.write(File.join(output, "spinning-square.gif"), frames, fps: 12)
+
+gradient = Tessel::Image.new(128, 32)
+gradient.height.times do |y|
+  gradient.width.times do |x|
+    gradient[x, y] = [x * 2, 100, 255 - x * 2, 255]
+  end
+end
+Flipbook.write(File.join(output, "gradient.gif"), [gradient], delay: 1)
+
+transparent = 16.times.map do |frame|
+  image = Tessel::Image.new(96, 96)
+  center_x = 48 + (25 * Math.cos(frame * Math::PI / 8)).round
+  center_y = 48 + (25 * Math.sin(frame * Math::PI / 8)).round
+  96.times do |y|
+    96.times do |x|
+      image[x, y] = [251, 113, 133, 255] if (x - center_x)**2 + (y - center_y)**2 <= 14**2
+    end
+  end
+  image
+end
+Flipbook.write(File.join(output, "transparent.gif"), transparent, fps: 8)
+Flipbook.write(File.join(output, "transparent.png"), transparent, fps: 8)
+
+puts "Wrote GIF and APNG examples to #{output}"

data/lib/flipbook/apng/writer.rb

@@ -6,7 +6,7 @@ module Flipbook
   module APNG
     class Writer
       def self.open(path, **options)
-        io = File.open(path, "wb+")
+        io = File.open(path, "wb")
         writer = new(io, **options)
         writer.instance_variable_set(:@owns_io, true)
         return writer unless block_given?
@@ -22,61 +22,54 @@ module Flipbook
         raise
       end
 
-      def initialize(io, width:, height:, loop: true, optimize: true, level: Zlib::DEFAULT_COMPRESSION, filter: :none)
+      def initialize(io, width:, height:, loop: true, optimize: true, buffered: nil)
         @io = io
         @width = Integer(width)
         @height = Integer(height)
-        raise ArgumentError, "APNG dimensions must be positive" unless @width.positive? && @height.positive?
-        raise ArgumentError, "unknown PNG filter: #{filter}" unless %i[none sub up average paeth adaptive].include?(filter)
+        raise ArgumentError, "APNG dimensions must be between 1 and 2147483647" unless @width.between?(1, 2_147_483_647) && @height.between?(1, 2_147_483_647)
+        raise TypeError, "optimize must be true or false" unless [true, false].include?(optimize)
 
-        @loop = plays(loop)
+        @loop = loop_count(loop)
         @optimize = optimize
-        @level = level
-        @filter = filter
-        @seekable = io.respond_to?(:pos) && io.respond_to?(:seek)
-        @storage = @seekable ? io : StringIO.new("".b)
-        @frames = 0
+        @buffered = buffered.nil? ? !seekable?(io) : buffered
+        @frames = []
+        @previous_image = nil
+        @frame_count = 0
         @sequence = 0
-        @previous = nil
         @closed = false
-        @storage << Tessel::SIGNATURE
-        Tessel::PNG::Chunk.write(@storage, "IHDR", [@width, @height, 8, 6, 0, 0, 0].pack("N2C5"))
-        @animation_offset = @storage.pos
-        write_chunk("acTL", [0, @loop].pack("N2"))
+        write_header unless @buffered
       end
 
       def add(image, delay:)
         raise IOError, "APNG writer is closed" if @closed
         raise TypeError, "frame must be a Tessel::Image" unless image.is_a?(Tessel::Image)
-        raise ArgumentError, "frame dimensions must match the animation" unless image.width == @width && image.height == @height
+        raise ArgumentError, "frame dimensions must match the canvas" unless image.width == @width && image.height == @height
 
         seconds = Timing.duration(delay)
-        left, top, width, height = @optimize ? Diff.bounds(@previous, image) : [0, 0, @width, @height]
-        frame = image.crop(left, top, width, height)
-        numerator, denominator = Timing.apng_fraction(seconds)
-        compressed = idat_data(frame)
-        raise Error, "APNG frame count exceeds the format limit" if @frames >= 0xFFFF_FFFF
-        control = [@sequence, width, height, left, top, numerator, denominator, 0, 0].pack("N5n2C2")
-        write_chunk("fcTL", control)
-        @sequence += 1
-        if @frames.zero?
-          write_chunk("IDAT", compressed)
+        if @buffered
+          @frames << [image.dup, seconds]
         else
-          write_chunk("fdAT", [@sequence].pack("N") + compressed)
-          @sequence += 1
+          write_frame(image, seconds)
         end
-        @frames += 1
-        @previous = image.dup
+        @frame_count += 1
+        @previous_image = image.dup
         self
       end
 
       def close
-        return if @closed
-        raise Error, "APNG contains no frames" if @frames.zero?
+        return self if @closed
+        raise Error, "APNG contains no frames" if @frame_count.zero?
 
-        write_chunk("IEND", "".b)
-        finish_animation_control
-        @io << @storage.string if @storage != @io
+        if @buffered
+          output = StringIO.new("".b)
+          writer = self.class.new(output, width: @width, height: @height, loop: @loop, optimize: @optimize, buffered: false)
+          @frames.each { |image, delay| writer.add(image, delay:) }
+          writer.close
+          @io.write(output.string)
+        else
+          write_chunk("IEND", "".b)
+          patch_animation_control
+        end
         @closed = true
         @io.close if @owns_io && !@io.closed?
         self
@@ -84,40 +77,90 @@ module Flipbook
 
       private
 
-      def plays(value)
+      def seekable?(io)
+        io.respond_to?(:pos) && io.respond_to?(:seek)
+      rescue IOError, SystemCallError
+        false
+      end
+
+      def loop_count(value)
         return 0 if value == true
         return 1 if value == false
-        return value if value.is_a?(Integer) && value.between?(0, 0xFFFF_FFFF)
+        return value if value.is_a?(Integer) && value.between?(0, 0xffff_ffff)
 
         raise ArgumentError, "loop must be true, false, or an integer from 0 to 4294967295"
       end
 
-      def write_chunk(type, data)
-        Tessel::PNG::Chunk.write(@storage, type, data)
+      def write_header
+        @io << Tessel::SIGNATURE
+        write_chunk("IHDR", [@width, @height, 8, 6, 0, 0, 0].pack("N2C5"))
+        @actl_data_position = @io.pos + 8
+        write_chunk("acTL", [1, @loop].pack("N2"))
+      end
+
+      def write_frame(image, delay)
+        rectangle = if @frame_count.zero? || !@optimize
+          [0, 0, @width, @height]
+        else
+          Diff.bounds(@previous_image, image) || [0, 0, 1, 1]
+        end
+        x, y, width, height = rectangle
+        frame = rectangle == [0, 0, @width, @height] ? image : image.crop(x, y, width, height)
+        numerator, denominator = delay_fraction(delay)
+        alpha = frame.bytes.bytes.each_slice(4).any? { |_, _, _, channel| channel < 255 }
+        blend = @frame_count.zero? || alpha ? 0 : 1
+        control = [@sequence, width, height, x, y].pack("N5") + [numerator, denominator, 0, blend].pack("n2C2")
+        write_chunk("fcTL", control)
+        @sequence += 1
+
+        png = Tessel::PNG::Encoder.encode(frame)
+        idat = png_chunks(png).select { |type, _| type == "IDAT" }.map(&:last).join
+        if @frame_count.zero?
+          write_chunk("IDAT", idat)
+        else
+          write_chunk("fdAT", [@sequence].pack("N") + idat)
+          @sequence += 1
+        end
       end
 
-      def idat_data(image)
-        png = Tessel::PNG.encode(image, color_type: :rgba, filter: @filter, level: @level, metadata: {})
-        output = "".b
-        cursor = Tessel::SIGNATURE.bytesize
-        while cursor + 12 <= png.bytesize
-          length = png.byteslice(cursor, 4).unpack1("N")
-          type = png.byteslice(cursor + 4, 4)
-          output << png.byteslice(cursor + 8, length) if type == "IDAT"
-          cursor += length + 12
+      def delay_fraction(delay)
+        raise ArgumentError, "APNG frame delay cannot exceed 65535 seconds" if delay > 65_535
+
+        if delay.numerator <= 65_535 && delay.denominator <= 65_535
+          return [delay.numerator, delay.denominator]
+        end
+
+        denominator = [65_535, (65_535 / delay).floor].min
+        denominator = 65_535 if denominator < 1
+        numerator = (delay * denominator).round.clamp(1, 65_535)
+        [numerator, denominator]
+      end
+
+      def png_chunks(png)
+        chunks = []
+        offset = Tessel::SIGNATURE.bytesize
+        while offset < png.bytesize
+          length = png.unpack1("N", offset:)
+          type = png.byteslice(offset + 4, 4)
+          data = png.byteslice(offset + 8, length)
+          chunks << [type, data]
+          offset += length + 12
           break if type == "IEND"
         end
-        raise Error, "Tessel produced a PNG without image data" if output.empty?
+        chunks
+      end
 
-        output
+      def write_chunk(type, data)
+        Tessel::PNG::Chunk.write(@io, type, data)
       end
 
-      def finish_animation_control
-        control = [@frames, @loop].pack("N2")
-        ending = @storage.pos
-        @storage.seek(@animation_offset)
-        write_chunk("acTL", control)
-        @storage.seek(ending)
+      def patch_animation_control
+        end_position = @io.pos
+        data = [@frame_count, @loop].pack("N2")
+        @io.seek(@actl_data_position)
+        @io.write(data)
+        @io.write([Zlib.crc32("acTL".b + data)].pack("N"))
+        @io.seek(end_position)
       end
     end
   end

data/lib/flipbook/diff.rb

@@ -4,27 +4,38 @@ module Flipbook
   module Diff
     module_function
 
+    # Returns the smallest changed rectangle, or nil when the images match.
     def bounds(previous, current)
-      raise TypeError, "current must be a Tessel::Image" unless current.is_a?(Tessel::Image)
-      return [0, 0, current.width, current.height] unless previous
-      raise TypeError, "previous must be a Tessel::Image" unless previous.is_a?(Tessel::Image)
-      raise ArgumentError, "image dimensions must match" unless previous.width == current.width && previous.height == current.height
+      unless previous.is_a?(Tessel::Image) && current.is_a?(Tessel::Image)
+        raise TypeError, "frames must be Tessel::Image values"
+      end
+      unless previous.width == current.width && previous.height == current.height
+        raise ArgumentError, "frame dimensions must match"
+      end
 
-      old_bytes = previous.bytes
-      new_bytes = current.bytes
-      left, top, right, bottom = current.width, current.height, -1, -1
-      (0...(current.width * current.height)).each do |index|
-        offset = index * 4
-        next if old_bytes.byteslice(offset, 4) == new_bytes.byteslice(offset, 4)
+      left = current.width
+      top = current.height
+      right = -1
+      bottom = -1
+      before = previous.bytes
+      after = current.bytes
+      current.height.times do |y|
+        current.width.times do |x|
+          offset = (y * current.width + x) * 4
+          next if before.byteslice(offset, 4) == after.byteslice(offset, 4)
 
-        x = index % current.width
-        y = index / current.width
-        left = x if x < left
-        top = y if y < top
-        right = x if x > right
-        bottom = y if y > bottom
+          left = x if x < left
+          top = y if y < top
+          right = x if x > right
+          bottom = y if y > bottom
+        end
       end
-      right.negative? ? [0, 0, 1, 1] : [left, top, right - left + 1, bottom - top + 1]
+      right.negative? ? nil : [left, top, right - left + 1, bottom - top + 1]
+    end
+
+    def crop(image, rectangle)
+      x, y, width, height = rectangle
+      image.crop(x, y, width, height)
     end
   end
 end

data/lib/flipbook/gif/lzw.rb

@@ -46,72 +46,6 @@ module Flipbook
         writer.sub_blocks
       end
 
-      def decode(bytes, minimum_code_size, expected_size: nil)
-        raise ArgumentError, "minimum code size must be between 2 and 8" unless minimum_code_size.is_a?(Integer) && minimum_code_size.between?(2, 8)
-
-        bytes = String(bytes).b
-        clear_code = 1 << minimum_code_size
-        end_code = clear_code + 1
-        dictionary = initial_dictionary(clear_code)
-        next_code = end_code + 1
-        code_width = minimum_code_size + 1
-        bit_offset = 0
-        previous = nil
-        output = "".b
-        ended = false
-        loop do
-          code = read_code(bytes, bit_offset, code_width)
-          break if code.nil?
-          bit_offset += code_width
-          if code == clear_code
-            dictionary = initial_dictionary(clear_code)
-            next_code = end_code + 1
-            code_width = minimum_code_size + 1
-            previous = nil
-            next
-          end
-          if code == end_code
-            ended = true
-            break
-          end
-
-          entry = if code < dictionary.length && dictionary[code]
-            dictionary[code]
-          elsif code == next_code && previous
-            previous + [previous.first]
-          else
-            raise Error, "invalid GIF LZW code"
-          end
-          output << entry.pack("C*")
-          raise Error, "GIF frame expands beyond its dimensions" if expected_size && output.bytesize > expected_size
-
-          if previous && next_code < 4096
-            dictionary[next_code] = previous + [entry.first]
-            next_code += 1
-            code_width += 1 if next_code == (1 << code_width) && code_width < 12
-          end
-          previous = entry
-        end
-        raise Error, "GIF LZW data is truncated" unless ended && (!expected_size || output.bytesize == expected_size)
-
-        output
-      end
-
-      def initial_dictionary(clear_code)
-        Array.new(clear_code) { |index| [index] } + [nil, nil]
-      end
-      private_class_method :initial_dictionary
-
-      def read_code(bytes, bit_offset, width)
-        return nil if bit_offset + width > bytes.bytesize * 8
-
-        value = 0
-        width.times do |bit|
-          value |= ((bytes.getbyte((bit_offset + bit) / 8) >> ((bit_offset + bit) % 8)) & 1) << bit
-        end
-        value
-      end
-      private_class_method :read_code
     end
   end
 end