wezen 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 371481b9c7234ab5048aeb49b4ee4413c71aee57c46331130c09b7ae3868250a
+  data.tar.gz: 1c37ec6416541d255d5714e168357d1a0aa5e750d7cf32aef48f20bdf6439814
+SHA512:
+  metadata.gz: 8efe1a7a8ef558760ebcdcd99c047863c1fbafdb59b97ddff81667a2ef081f3613795c6e01ad24b0a4b2e58f146ba8302f37986f3d6c2f9c02768eed9c6e7a22
+  data.tar.gz: 7f40b04e14c5ee213997189150c8b50c91b4b07bbf01f632850046b80064b212fe324bb8beab8f47a7f0fdfb382b1da05f81e5fdf9b419d84b079b0b61309987

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-20
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,52 @@
+# Wezen
+
+Wezen is named for δ Canis Majoris, whose IAU name comes from the Arabic
+*al-wazn* (“the weight”). It is a dependency-free Ruby encoder for deterministic
+demo media.
+
+## Features
+
+- Lossless APNG and PNG output with optional frame rectangles
+- GIF89a output with deterministic median-cut palettes and dithering
+- Pixel scaling, cropping, alpha blending, and change bounds
+- Asciinema v2 JSON Lines casts
+- No runtime dependencies beyond Ruby's `zlib` and `json` standard libraries
+
+## Installation
+
+```sh
+gem install wezen
+```
+
+## Quick start
+
+```ruby
+require "wezen"
+
+animation = Wezen::Animation.new(width: 2, height: 1)
+animation.add([255, 0, 0, 255, 0, 0, 255, 255].pack("C*"), delay_ms: 100)
+animation.add([255, 0, 0, 255, 0, 255, 0, 255].pack("C*"), delay_ms: 100)
+
+Wezen::APNG.write("demo.apng", animation)
+Wezen::GIF.write("demo.gif", animation, dither: :bayer)
+```
+
+`Animation` accepts RGBA strings in row-major order. Repeated frames are
+coalesced and their delays are added. Encoding the same animation twice yields
+the same bytes.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rbs -I sig validate
+gem build --strict wezen.gemspec
+```
+
+The runtime gem intentionally contains encoders only; decoder helpers belong in
+tests so the package stays small and dependency-free.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/docs/adr/000-template.md

@@ -0,0 +1,24 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its compatibility, data,
+runtime, or component constraints. Operational workflow and release policy do
+not belong in this directory; see [the scope](README.md).
+
+Name the credible alternatives. If there was no meaningful alternative, record
+the behavior in reference documentation instead of creating an ADR.
+
+## Decision
+
+Describe the durable boundary or architecture choice. Leave command syntax,
+field-by-field formats, test evidence, benchmark results, and migration steps
+in their authoritative documents.
+
+## Consequences
+
+Describe the important positive and negative trade-offs, including what would
+make this decision worth revisiting.

data/docs/adr/001-encode-only.md

@@ -0,0 +1,26 @@
+# ADR 001: Encode-only scope
+
+- Status: Accepted
+- Date: 2026-09-20
+
+## Context
+
+Wezen is a small, dependency-free library for turning frames and terminal
+events into portable media. Adding decoders would increase the runtime surface
+and introduce format-specific behavior that callers do not need to produce
+media.
+
+The credible alternatives were to ship decoders with the gem, depend on an
+external image library, or keep decoding support in tests only.
+
+## Decision
+
+Wezen writes deterministic APNG, GIF, PNG, and asciinema streams. Decoders
+remain test support and are not part of the runtime gem.
+
+## Consequences
+
+The runtime remains small, portable, and dependency-free, while round-trip
+tests still validate the encoders. Callers that need to inspect or decode
+media must provide that capability separately; revisit this decision only if
+encoding users also require a stable decoding API.

data/docs/adr/002-global-palette.md

@@ -0,0 +1,27 @@
+# ADR 002: Deterministic global palette
+
+- Status: Accepted
+- Date: 2026-09-20
+
+## Context
+
+GIF has a single global color table in the common output path, while recorded
+animations may contain more colors than that table can hold. Per-frame
+palettes could preserve local colors better, but make frame differences and
+output size less predictable.
+
+The credible alternatives were a per-frame palette, a fixed application
+palette, or one deterministic palette for the complete animation.
+
+## Decision
+
+GIF uses one median-cut palette for the animation. Palette axes, color ordering,
+and tie-breaking are stable so identical inputs produce byte-identical output.
+
+## Consequences
+
+Palette construction is reproducible and shared across frames, which keeps
+GIF output simple and suitable for size budgets. A global palette can represent
+some local gradients less accurately than a per-frame palette; revisit this if
+measured media quality requires adaptive palettes without compromising
+determinism.

data/docs/adr/003-apng-default.md

@@ -0,0 +1,26 @@
+# ADR 003: APNG is the default
+
+- Status: Accepted
+- Date: 2026-09-20
+
+## Context
+
+Recorded UI frames commonly use transparency and more than 256 colors. GIF is
+widely supported but requires palette quantization and has limited alpha
+semantics. APNG preserves the source pixel format while remaining a portable
+single-file animation.
+
+The credible alternatives were GIF as the only output, a sequence of PNG
+files, or APNG as the lossless default with GIF for compatibility.
+
+## Decision
+
+APNG is the default animation output and preserves RGBA pixels. GIF remains an
+explicit compatibility output with deterministic palette quantization.
+
+## Consequences
+
+The default path keeps colors and transparency intact, while callers targeting
+GIF-only viewers can opt in to the documented quantization behavior. APNG
+support is not universal in every legacy viewer; revisit the default only if
+the supported playback targets change.

data/docs/adr/README.md

@@ -0,0 +1,10 @@
+# Architecture decision records
+
+These records document durable implementation boundaries and choices. Commands,
+formats, benchmarks, and release steps belong in the README or their
+implementation documents.
+
+- [ADR template](000-template.md)
+- [ADR 001: Encode-only scope](001-encode-only.md)
+- [ADR 002: Deterministic global palette](002-global-palette.md)
+- [ADR 003: APNG is the default](003-apng-default.md)

data/lib/wezen/animation.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Wezen
+  Frame = Data.define(:rgba, :delay_ms)
+
+  class Animation
+    include Enumerable
+
+    attr_reader :width, :height, :loop
+
+    def initialize(width:, height:, loop: 0)
+      @width = Integer(width)
+      @height = Integer(height)
+      @loop = Integer(loop)
+      raise ArgumentError, "invalid animation dimensions" unless @width.positive? && @height.positive?
+      raise ArgumentError, "loop must be non-negative" if @loop.negative?
+
+      @frames = []
+    end
+
+    def add(rgba, delay_ms:)
+      pixels = String(rgba).b
+      delay = Integer(delay_ms)
+      raise ArgumentError, "invalid RGBA frame" unless pixels.bytesize == @width * @height * 4
+      raise ArgumentError, "delay_ms must be non-negative" if delay.negative?
+
+      if (last = @frames.last) && last.rgba == pixels
+        @frames[-1] = Frame.new(last.rgba, last.delay_ms + delay)
+      else
+        @frames << Frame.new(pixels.freeze, delay)
+      end
+      self
+    end
+
+    def <<(frame)
+      raise ArgumentError, "expected Wezen::Frame" unless frame.respond_to?(:rgba) && frame.respond_to?(:delay_ms)
+
+      add(frame.rgba, delay_ms: frame.delay_ms)
+    end
+
+    def size = @frames.size
+    def duration_ms = @frames.sum(&:delay_ms)
+    def each(&block) = block ? @frames.each(&block) : @frames.each
+
+    def coalesce(tolerance: 0)
+      tolerance = Integer(tolerance)
+      raise ArgumentError, "tolerance must be non-negative" if tolerance.negative?
+
+      result = self.class.new(width: @width, height: @height, loop: @loop)
+      @frames.each do |frame|
+        frames = result.instance_variable_get(:@frames)
+        if (last = frames.last) && same?(last.rgba, frame.rgba, tolerance)
+          frames[-1] = Frame.new(last.rgba, last.delay_ms + frame.delay_ms)
+        else
+          result << frame
+        end
+      end
+      result
+    end
+
+    def scale(to_width:, to_height:)
+      result = self.class.new(width: to_width, height: to_height, loop: @loop)
+      each { |frame| result.add(Image.scale(frame.rgba, @width, @height, to_width: to_width, to_height: to_height), delay_ms: frame.delay_ms) }
+      result
+    end
+
+    def crop(bounds)
+      x, y, width, height = Image.bounds(bounds)
+      result = self.class.new(width: width, height: height, loop: @loop)
+      each { |frame| result.add(Image.crop(frame.rgba, @width, @height, [x, y, width, height]), delay_ms: frame.delay_ms) }
+      result
+    end
+
+    def drop_to(fps:)
+      fps = Float(fps)
+      raise ArgumentError, "fps must be positive" unless fps.positive?
+      interval = 1000.0 / fps
+      result = self.class.new(width: @width, height: @height, loop: @loop)
+      elapsed = 0.0
+      next_sample = 0.0
+      each do |frame|
+        frame_start = elapsed
+        frame_end = elapsed + frame.delay_ms
+        while next_sample < frame_end || (result.size.zero? && next_sample == frame_start)
+          result.add(frame.rgba, delay_ms: interval.round)
+          next_sample += interval
+        end
+        elapsed = frame_end
+      end
+      result
+    end
+
+    private
+
+    def same?(left, right, tolerance)
+      return true if left == right
+      return false unless tolerance.positive? && left.bytesize == right.bytesize
+
+      left.bytes.zip(right.bytes).all? { |a, b| (a - b).abs <= tolerance }
+    end
+  end
+end

data/lib/wezen/apng.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Wezen
+  module APNG
+    module_function
+
+    def encode(animation, compression: 9, diff: true)
+      raise ArgumentError, "animation must contain at least one frame" if animation.size.zero?
+      frames = animation.each.to_a
+      sequence = 0
+      output = PNG::SIGNATURE.dup
+      output << PNG.chunk("IHDR", [animation.width, animation.height, 8, 6, 0, 0, 0].pack("NNC5"))
+      output << PNG.chunk("acTL", [frames.length, animation.loop].pack("N2"))
+      previous = nil
+      frames.each_with_index do |frame, index|
+        rect, pixels, blend = rectangle(animation, previous, frame.rgba, diff && index.positive?)
+        delay_num, delay_den = delay(frame.delay_ms)
+        output << PNG.chunk("fcTL", [sequence, rect[2], rect[3], rect[0], rect[1], delay_num, delay_den, 0, blend].pack("N5n2C2"))
+        sequence += 1
+        scanlines = scanlines(pixels, rect[2], rect[3])
+        compressed = Zlib::Deflate.deflate(scanlines, Integer(compression))
+        if index.zero?
+          output << PNG.chunk("IDAT", compressed)
+        else
+          output << PNG.chunk("fdAT", [sequence].pack("N") + compressed)
+          sequence += 1
+        end
+        previous = frame.rgba
+      end
+      output << PNG.chunk("IEND", "".b)
+    end
+
+    def write(path, animation, **options)
+      File.binwrite(path, encode(animation, **options))
+      path
+    end
+
+    def rectangle(animation, previous, current, use_diff)
+      return [[0, 0, animation.width, animation.height], current, 0] unless use_diff && previous
+
+      bounds = Image.diff_bounds(previous, current, animation.width, animation.height)
+      return [[0, 0, 1, 1], "\0\0\0\0".b, 1] unless bounds
+
+      x, y, width, height = bounds
+      patch = Image.crop(current, animation.width, animation.height, bounds)
+      # APNG source blending is exact for the opaque UI pixels this encoder targets.
+      # Fall back to a complete frame when alpha would make source-over lossy.
+      if patch.bytes.each_slice(4).any? { |pixel| pixel[3] != 255 }
+        [[0, 0, animation.width, animation.height], current, 0]
+      else
+        [[x, y, width, height], patch, 1]
+      end
+    end
+
+    def scanlines(rgba, width, height)
+      raw = String.new(encoding: Encoding::BINARY)
+      height.times { |row| raw << "\0" << rgba.byteslice(row * width * 4, width * 4) }
+      raw
+    end
+
+    def delay(milliseconds)
+      milliseconds = Integer(milliseconds)
+      return [0, 1000] if milliseconds.zero?
+      denominator = 1000
+      numerator = milliseconds
+      common = numerator.gcd(denominator)
+      [numerator / common, denominator / common]
+    end
+    private_class_method :rectangle, :scanlines, :delay
+  end
+end

data/lib/wezen/cast.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Wezen
+  module Cast
+    Event = Data.define(:time, :kind, :data)
+
+    module_function
+
+    def encode(width:, height:, events:, title: nil, env: {})
+      width = Integer(width); height = Integer(height)
+      raise ArgumentError, "invalid terminal dimensions" unless width.positive? && height.positive?
+      header = { "version" => 2, "width" => width, "height" => height, "timestamp" => 0, "env" => env.transform_keys(&:to_s).transform_values(&:to_s) }
+      header["title"] = title.to_s if title
+      lines = [JSON.generate(header)]
+      last_time = 0.0
+      Array(events).each do |event|
+        event = event.is_a?(Event) ? event : Event.new(*event)
+        event = Event.new(Float(event.time), event.kind.to_sym, event.data.to_s)
+        raise ArgumentError, "cast events must be chronological" if event.time < last_time
+        raise ArgumentError, "event time must be non-negative" if event.time.negative?
+        raise ArgumentError, "unknown cast event: #{event.kind}" unless %i[output input resize].include?(event.kind)
+        kind = { output: "o", input: "i", resize: "r" }.fetch(event.kind)
+        lines << JSON.generate([event.time, kind, event.data])
+        last_time = event.time
+      end
+      lines.join("\n") + "\n"
+    end
+
+    def write(path, **options)
+      File.write(path, encode(**options), mode: "wb")
+      path
+    end
+  end
+end

data/lib/wezen/gif.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Wezen
+  module GIF
+    module_function
+
+    def encode(animation, colors: 256, palette: :global, dither: :floyd_steinberg, diff: true)
+      raise ArgumentError, "animation must contain at least one frame" if animation.size.zero?
+      raise ArgumentError, "palette must be :global, :adaptive, or a Palette" unless palette == :global || palette == :adaptive || palette.respond_to?(:colors)
+      limit = Integer(colors)
+      raise ArgumentError, "colors must be between 2 and 256" unless limit.between?(2, 256)
+
+      source_palette = palette.respond_to?(:colors) ? palette : Quantize.palette(animation, colors: limit)
+      needs_transparency = diff && animation.each_cons(2).any? { |left, right| left.rgba == right.rgba }
+      source_palette = reserve_transparency(source_palette, limit) if needs_transparency && source_palette.transparent_index.nil?
+      table_size = [source_palette.colors.length, 2].max
+      bits = [[Math.log2(table_size).ceil, 1].max, 8].min
+      table_size = 1 << bits
+      colors_table = source_palette.colors + Array.new(table_size - source_palette.colors.length, [0, 0, 0])
+      output = "GIF89a".b
+      output << [animation.width, animation.height, 0x80 | ((bits - 1) << 4) | (bits - 1), 0, 0].pack("vvC3")
+      colors_table.each { |color| output << color.pack("C3") }
+      output << loop_extension(animation.loop)
+
+      previous = nil
+      animation.each.with_index do |frame, index|
+        indices = Quantize.apply_with_size(frame.rgba, source_palette, width: animation.width, height: animation.height, dither: dither)
+        rect, patch = if index.zero? || !diff || previous.nil?
+          [[0, 0, animation.width, animation.height], indices]
+        else
+          bounds = Image.diff_bounds(previous, frame.rgba, animation.width, animation.height)
+          if bounds
+            [bounds, indexed_crop(indices, animation.width, bounds)]
+          else
+            [[0, 0, 1, 1], source_palette.transparent_index.chr]
+          end
+        end
+        transparent = source_palette.transparent_index && frame.rgba.bytes.each_slice(4).any? { |pixel| pixel[3] < 128 }
+        output << graphic_control(frame.delay_ms, transparent ? source_palette.transparent_index : nil)
+        output << image_descriptor(rect, bits)
+        output << sub_blocks(lzw(patch, [bits, 2].max), [bits, 2].max)
+        previous = frame.rgba
+      end
+      output << "\x3B".b
+    end
+
+    def write(path, animation, **options)
+      File.binwrite(path, encode(animation, **options))
+      path
+    end
+
+    def reserve_transparency(palette, limit)
+      opaque = palette.colors.reject.with_index { |_color, index| index == palette.transparent_index }
+      Palette.new([[0, 0, 0], *opaque.first(limit - 1)], 0)
+    end
+
+    def loop_extension(loop)
+      "!\xFF\x0BNETSCAPE2.0\x03\x01".b + [loop].pack("v") + "\0".b
+    end
+
+    def graphic_control(delay_ms, transparent_index)
+      delay = [[(Integer(delay_ms) / 10.0).round, 0].max, 65_535].min
+      packed = transparent_index ? 1 : 0
+      "!\xF9\x04".b + [packed, delay, transparent_index || 0].pack("CvC") + "\0".b
+    end
+
+    def image_descriptor(rect, bits)
+      x, y, width, height = rect
+      [44, x, y, width, height, 0].pack("CvvvvC")
+    end
+
+    def indexed_crop(indices, width, rect)
+      x, y, crop_width, crop_height = rect
+      output = String.new(capacity: crop_width * crop_height, encoding: Encoding::BINARY)
+      crop_height.times { |row| output << indices.byteslice((y + row) * width + x, crop_width) }
+      output
+    end
+
+    def sub_blocks(bytes, minimum_code_size)
+      output = minimum_code_size.chr
+      bytes.bytes.each_slice(255) { |slice| output << slice.length.chr << slice.pack("C*") }
+      output << "\0".b
+    end
+
+    def lzw(indices, minimum_code_size)
+      clear = 1 << minimum_code_size
+      ending = clear + 1
+      dictionary = {}
+      next_code = ending + 1
+      code_size = minimum_code_size + 1
+      writer = BitWriter.new
+      writer.write(clear, code_size)
+      prefix = nil
+      indices.bytes.each do |value|
+        if prefix.nil?
+          prefix = value
+          next
+        end
+        key = [prefix, value]
+        if dictionary.key?(key)
+          prefix = dictionary[key]
+          next
+        end
+        writer.write(prefix, code_size)
+        if next_code < 4096
+          dictionary[key] = next_code
+          next_code += 1
+          code_size += 1 if next_code == (1 << code_size) && code_size < 12
+        else
+          writer.write(clear, code_size)
+          dictionary.clear
+          next_code = ending + 1
+          code_size = minimum_code_size + 1
+        end
+        prefix = value
+      end
+      writer.write(prefix, code_size) unless prefix.nil?
+      writer.write(ending, code_size)
+      writer.finish
+    end
+
+    class BitWriter
+      def initialize
+        @bytes = String.new(encoding: Encoding::BINARY)
+        @buffer = 0
+        @bits = 0
+      end
+
+      def write(value, width)
+        @buffer |= value << @bits
+        @bits += width
+        while @bits >= 8
+          @bytes << (@buffer & 255)
+          @buffer >>= 8
+          @bits -= 8
+        end
+      end
+
+      def finish
+        @bytes << (@buffer & 255) if @bits.positive?
+        @bytes
+      end
+    end
+
+    private_class_method :reserve_transparency, :loop_extension, :graphic_control, :image_descriptor,
+      :indexed_crop, :sub_blocks, :lzw
+  end
+end

data/lib/wezen/image.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Wezen
+  module Image
+    module_function
+
+    def scale(rgba, width, height, to_width:, to_height:)
+      width = Integer(width); height = Integer(height)
+      to_width = Integer(to_width); to_height = Integer(to_height)
+      validate!(rgba, width, height)
+      raise ArgumentError, "invalid target dimensions" unless to_width.positive? && to_height.positive?
+
+      output = String.new(capacity: to_width * to_height * 4, encoding: Encoding::BINARY)
+      to_height.times do |dy|
+        y0 = dy * height.fdiv(to_height); y1 = (dy + 1) * height.fdiv(to_height)
+        to_width.times do |dx|
+          x0 = dx * width.fdiv(to_width); x1 = (dx + 1) * width.fdiv(to_width)
+          sx0 = x0.floor; sx1 = [x1.ceil, width].min
+          sy0 = y0.floor; sy1 = [y1.ceil, height].min
+          count = 0; sum = [0, 0, 0, 0]
+          (sy0...sy1).each do |sy|
+            (sx0...sx1).each do |sx|
+              pixel = rgba.byteslice((sy * width + sx) * 4, 4).bytes
+              4.times { |channel| sum[channel] += pixel[channel] }
+              count += 1
+            end
+          end
+          output << sum.map { |value| (value.to_f / count).round }.pack("C4")
+        end
+      end
+      output
+    end
+
+    def crop(rgba, width, height, bounds)
+      x, y, crop_width, crop_height = self.bounds(bounds)
+      validate!(rgba, width, height)
+      raise ArgumentError, "crop is outside image" unless x >= 0 && y >= 0 && crop_width.positive? && crop_height.positive? && x + crop_width <= width && y + crop_height <= height
+
+      output = String.new(capacity: crop_width * crop_height * 4, encoding: Encoding::BINARY)
+      crop_height.times { |row| output << rgba.byteslice(((y + row) * width + x) * 4, crop_width * 4) }
+      output
+    end
+
+    def blend(dst, dst_width, src, src_width, src_height, x:, y:, opacity: 1.0)
+      dst_width = Integer(dst_width); src_width = Integer(src_width); src_height = Integer(src_height)
+      destination = String(dst).b.dup
+      raise ArgumentError, "invalid source image" unless src.bytesize == src_width * src_height * 4
+      raise ArgumentError, "invalid destination image" unless destination.bytesize % 4 == 0 && dst_width.positive?
+      dst_height = destination.bytesize / 4 / dst_width
+      alpha = Float(opacity)
+      raise ArgumentError, "opacity must be between 0 and 1" unless alpha.between?(0.0, 1.0)
+
+      src_height.times do |sy|
+        dy = Integer(y) + sy
+        next unless dy.between?(0, dst_height - 1)
+        src_width.times do |sx|
+          dx = Integer(x) + sx
+          next unless dx.between?(0, dst_width - 1)
+          si = (sy * src_width + sx) * 4; di = (dy * dst_width + dx) * 4
+          sr, sg, sb, sa = src.byteslice(si, 4).bytes
+          sa = (sa * alpha).round
+          dr, dg, db, da = destination.byteslice(di, 4).bytes
+          source_alpha = sa / 255.0; destination_alpha = da / 255.0
+          out_alpha = source_alpha + destination_alpha * (1.0 - source_alpha)
+          if out_alpha.zero?
+            destination[di, 4] = "\0\0\0\0".b
+          else
+            destination[di, 4] = [
+              ((sr * source_alpha + dr * destination_alpha * (1.0 - source_alpha)) / out_alpha).round,
+              ((sg * source_alpha + dg * destination_alpha * (1.0 - source_alpha)) / out_alpha).round,
+              ((sb * source_alpha + db * destination_alpha * (1.0 - source_alpha)) / out_alpha).round,
+              (out_alpha * 255).round
+            ].pack("C4")
+          end
+        end
+      end
+      dst.replace(destination) if dst.respond_to?(:replace) && !dst.frozen?
+      destination
+    end
+
+    def diff_bounds(previous, current, width, height)
+      validate!(previous, width, height); validate!(current, width, height)
+      min_x = width; min_y = height; max_x = -1; max_y = -1
+      (0...(width * height)).each do |index|
+        next if previous.byteslice(index * 4, 4) == current.byteslice(index * 4, 4)
+        x = index % width; y = index / width
+        min_x = x if x < min_x; min_y = y if y < min_y; max_x = x if x > max_x; max_y = y if y > max_y
+      end
+      max_x.negative? ? nil : [min_x, min_y, max_x - min_x + 1, max_y - min_y + 1]
+    end
+
+    def bounds(value)
+      values = value.respond_to?(:to_a) ? value.to_a : value
+      raise ArgumentError, "bounds must contain x, y, width, height" unless values && values.length == 4
+      values.map { |item| Integer(item) }
+    end
+
+    def validate!(rgba, width, height)
+      raise ArgumentError, "invalid dimensions" unless Integer(width).positive? && Integer(height).positive?
+      raise ArgumentError, "invalid RGBA pixels" unless rgba.bytesize == width * height * 4
+    end
+    private_class_method :validate!
+  end
+end

data/lib/wezen/palette.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wezen
+  Palette = Data.define(:colors, :transparent_index)
+end

data/lib/wezen/png.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wezen
+  module PNG
+    SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+    module_function
+
+    def encode(width, height, rgba, compression: 9)
+      validate(width, height, rgba)
+      scanlines = String.new(encoding: Encoding::BINARY)
+      height.times { |row| scanlines << "\0" << rgba.byteslice(row * width * 4, width * 4) }
+      SIGNATURE + chunk("IHDR", [width, height, 8, 6, 0, 0, 0].pack("NNC5")) +
+        chunk("IDAT", Zlib::Deflate.deflate(scanlines, Integer(compression))) + chunk("IEND", "".b)
+    end
+
+    def write(path, width, height, rgba, **options)
+      File.binwrite(path, encode(width, height, rgba, **options))
+      path
+    end
+
+    def chunk(kind, data)
+      [data.bytesize].pack("N") + kind + data + [Zlib.crc32(kind + data)].pack("N")
+    end
+
+    def validate(width, height, rgba)
+      raise ArgumentError, "invalid image dimensions" unless width.to_i.positive? && height.to_i.positive?
+      raise ArgumentError, "invalid RGBA pixels" unless rgba.bytesize == width * height * 4
+    end
+    private_class_method :validate
+  end
+end

data/lib/wezen/quantize.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Wezen
+  module Quantize
+    module_function
+
+    def palette(animation, colors:, method: :median_cut)
+      raise ArgumentError, "unsupported quantizer: #{method}" unless %i[median_cut octree].include?(method)
+      limit = Integer(colors)
+      raise ArgumentError, "colors must be between 2 and 256" unless limit.between?(2, 256)
+      pixels = animation.each.flat_map { |frame| frame.rgba.bytes.each_slice(4).reject { |pixel| pixel[3] < 128 }.map { |pixel| pixel[0, 3] } }
+      pixels = [[0, 0, 0]] if pixels.empty?
+      transparent = animation.each.any? { |frame| frame.rgba.bytes.each_slice(4).any? { |pixel| pixel[3] < 128 } }
+      opaque_limit = transparent ? limit - 1 : limit
+      colors_out = median_cut(pixels, opaque_limit)
+      if transparent
+        colors_out = [[0, 0, 0], *colors_out]
+        Palette.new(colors_out, 0)
+      else
+        Palette.new(colors_out, nil)
+      end
+    end
+
+    def apply(rgba, palette, width: nil, height: nil, dither: :floyd_steinberg)
+      raise ArgumentError, "unknown dither: #{dither}" unless %i[none bayer floyd_steinberg].include?(dither)
+      raise ArgumentError, "palette must be a Wezen::Palette" unless palette.respond_to?(:colors)
+      width ||= rgba.bytesize / 4
+      height ||= 1
+      apply_with_size(rgba, palette, width: width, height: height, dither: dither)
+    end
+
+    def apply_with_size(rgba, palette, width:, height:, dither: :floyd_steinberg)
+      raise ArgumentError, "invalid RGBA pixels" unless rgba.bytesize == Integer(width) * Integer(height) * 4
+      colors = palette.colors
+      output = String.new(capacity: width * height, encoding: Encoding::BINARY)
+      errors = Array.new(width * 3, 0.0)
+      next_errors = Array.new(width * 3, 0.0)
+      rgba.bytes.each_slice(4).with_index do |pixel, index|
+        x = index % width; y = index / width
+        alpha = pixel[3]
+        if alpha < 128 && palette.transparent_index
+          output << palette.transparent_index
+          next
+        end
+        adjusted = pixel[0, 3].map.with_index do |channel, component|
+          value = channel.to_f
+          value += errors[x * 3 + component] if dither == :floyd_steinberg
+          if dither == :bayer
+            value += bayer(x, y) * 16 - 8
+          end
+          value.clamp(0, 255)
+        end
+        index_color = nearest(adjusted, colors, palette.transparent_index)
+        output << index_color
+        next unless dither == :floyd_steinberg
+
+        chosen = colors[index_color]
+        delta = 3.times.map { |channel| adjusted[channel] - chosen[channel] }
+        distribute(errors, next_errors, x, width, delta)
+        if x == width - 1
+          errors = next_errors
+          next_errors = Array.new(width * 3, 0.0)
+        end
+      end
+      output
+    end
+
+    def median_cut(pixels, limit)
+      boxes = [pixels.sort_by { |pixel| pixel[0] * 65_536 + pixel[1] * 256 + pixel[2] }]
+      while boxes.length < limit
+        candidate = boxes.each_with_index.max_by do |box, index|
+          ranges = 3.times.map { |axis| box.map { |pixel| pixel[axis] }.then { |values| values.max - values.min } }
+          [box.length, *ranges, -index]
+        end
+        break unless candidate
+        box, index = candidate
+        axis = 3.times.max_by { |item| [box.map { |pixel| pixel[item] }.then { |values| values.max - values.min }, -item] }
+        ordered = box.sort_by { |pixel| [pixel[axis], pixel[0], pixel[1], pixel[2]] }
+        cut = [ordered.length / 2, 1].max
+        break if cut >= ordered.length
+        boxes[index] = ordered[0, cut]
+        boxes << ordered[cut..]
+      end
+      boxes.map do |box|
+        box.transpose.map { |channel| (channel.sum.fdiv(channel.length)).round }
+      end.sort
+    end
+
+    def nearest(pixel, colors, transparent_index)
+      colors.each_with_index.reject { |_color, index| index == transparent_index }.min_by do |color, index|
+        [pixel.each_with_index.sum { |value, channel| (value - color[channel])**2 }, index]
+      end.last
+    end
+
+    def bayer(x, y)
+      [[0, 8], [12, 4]][y % 2][x % 2] / 16.0
+    end
+
+    def distribute(errors, next_errors, x, width, delta)
+      add = ->(array, column, factor) { 3.times { |channel| array[column * 3 + channel] += delta[channel] * factor } if column.between?(0, width - 1) }
+      add.call(errors, x + 1, 7.0 / 16)
+      add.call(next_errors, x - 1, 3.0 / 16)
+      add.call(next_errors, x, 5.0 / 16)
+      add.call(next_errors, x + 1, 1.0 / 16)
+    end
+    private_class_method :median_cut, :nearest, :bayer, :distribute
+  end
+end

data/lib/wezen/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Wezen
+  VERSION = "0.1.0"
+end

data/lib/wezen.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "zlib"
+require_relative "wezen/version"
+
+# Ruby 3.2 added Data. Keep the gem usable on the minimum supported Ruby too.
+unless defined?(Data) && Data.respond_to?(:define)
+  Object.send(:remove_const, :Data) if defined?(Data)
+  Data = Struct
+  def Data.define(*members, &block)
+    Struct.new(*members) do
+      members.each { |member| undef_method :"#{member}=" }
+      define_method(:initialize) do |*values, **keywords|
+        values = members.map { |member| keywords.fetch(member) } if values.empty? && keywords.any?
+        raise ArgumentError, "wrong number of members" unless values.length == members.length
+
+        super(*values)
+        freeze
+      end
+      define_method(:with) { |**changes| self.class.new(**to_h.merge(changes)) }
+      class_eval(&block) if block
+    end
+  end
+end
+
+require_relative "wezen/animation"
+require_relative "wezen/image"
+require_relative "wezen/palette"
+require_relative "wezen/quantize"
+require_relative "wezen/png"
+require_relative "wezen/apng"
+require_relative "wezen/gif"
+require_relative "wezen/cast"
+
+module Wezen
+  class Error < StandardError; end
+end

data/sig/wezen.rbs

@@ -0,0 +1,68 @@
+module Wezen
+  VERSION: String
+  class Error < StandardError
+  end
+
+  class Frame
+    attr_reader rgba: String
+    attr_reader delay_ms: Integer
+  end
+
+  class Animation
+    attr_reader width: Integer
+    attr_reader height: Integer
+    attr_reader loop: Integer
+    def initialize: (width: Integer, height: Integer, ?loop: Integer) -> void
+    def add: (String rgba, delay_ms: Integer) -> self
+    def <<: (Frame frame) -> self
+    def size: () -> Integer
+    def duration_ms: () -> Integer
+    def each: () { (Frame) -> void } -> self
+    def coalesce: (?tolerance: Integer) -> Animation
+    def scale: (to_width: Integer, to_height: Integer) -> Animation
+    def crop: (untyped bounds) -> Animation
+    def drop_to: (fps: Numeric) -> Animation
+  end
+
+  class Palette
+    attr_reader colors: Array[Array[Integer]]
+    attr_reader transparent_index: Integer?
+  end
+
+  module Image
+    def self.scale: (String rgba, Integer width, Integer height, to_width: Integer, to_height: Integer) -> String
+    def self.crop: (String rgba, Integer width, Integer height, untyped bounds) -> String
+    def self.blend: (String dst, Integer dst_width, String src, Integer src_width, Integer src_height, x: Integer, y: Integer, ?opacity: Numeric) -> String
+    def self.diff_bounds: (String previous, String current, Integer width, Integer height) -> [Integer, Integer, Integer, Integer]?
+  end
+
+  module Quantize
+    def self.palette: (Animation animation, colors: Integer, ?method: Symbol) -> Palette
+    def self.apply: (String rgba, Palette palette, ?width: Integer?, ?height: Integer?, ?dither: Symbol) -> String
+  end
+
+  module PNG
+    def self.encode: (Integer width, Integer height, String rgba, ?compression: Integer) -> String
+    def self.write: (String path, Integer width, Integer height, String rgba, **untyped) -> String
+  end
+
+  module APNG
+    def self.encode: (Animation animation, ?compression: Integer, ?diff: bool) -> String
+    def self.write: (String path, Animation animation, **untyped) -> String
+  end
+
+  module GIF
+    def self.encode: (Animation animation, ?colors: Integer, ?palette: Symbol | Palette, ?dither: Symbol, ?diff: bool) -> String
+    def self.write: (String path, Animation animation, **untyped) -> String
+  end
+
+  module Cast
+    class Event
+      attr_reader time: Numeric
+      attr_reader kind: Symbol
+      attr_reader data: String
+    end
+    def self.encode: (width: Integer, height: Integer, events: Array[Event | Array[untyped]], ?title: String?, ?env: Hash[untyped, untyped]) -> String
+    def self.write: (String path, **untyped) -> String
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: wezen
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Pure Ruby encoders and pixel primitives for deterministic demo recordings.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/adr/000-template.md
+- docs/adr/001-encode-only.md
+- docs/adr/002-global-palette.md
+- docs/adr/003-apng-default.md
+- docs/adr/README.md
+- lib/wezen.rb
+- lib/wezen/animation.rb
+- lib/wezen/apng.rb
+- lib/wezen/cast.rb
+- lib/wezen/gif.rb
+- lib/wezen/image.rb
+- lib/wezen/palette.rb
+- lib/wezen/png.rb
+- lib/wezen/quantize.rb
+- lib/wezen/version.rb
+- sig/wezen.rbs
+homepage: https://github.com/noxdea/wezen
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/noxdea/wezen
+  source_code_uri: https://github.com/noxdea/wezen/tree/main
+  changelog_uri: https://github.com/noxdea/wezen/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Deterministic GIF, APNG, PNG, and asciinema encoders for Ruby
+test_files: []