zaniah 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 905d6e52f6013be2a7b8e0223ece509526a9cde3a6198c8386e8b59903bf2dde
-  data.tar.gz: 57db74ac492c60d4d0f310c25596005c89faa706e2c8750cb6322b8091ac3671
+  metadata.gz: 00bd64bac42b39487e5b1d5d5c8c259fe2ced7a238dd07d6b073e72b5c3023f7
+  data.tar.gz: e4bf0fbcb4d460a26e47a0abdd941e4a1904906cc6e98546f2ec42a9cac2517f
 SHA512:
-  metadata.gz: 27209b822cd741f79110228e9ddefc63eccf3eee8ffe64f2467570c4dd9fbc126176cf1e39289d8afa3b144577335809a1aa7b77d21deba013050e32eb374fcf
-  data.tar.gz: 739e4c67fd1de82b7fce3e0682aa9ecb1380cdf629f315f61387989f64d89379247840e6d691a36e0d17bb148a30a7eb5fa82cd5d749857b6592c864e2880340
+  metadata.gz: 598ddd2173a36d1bcd284d713da20d36202f679e1d3ef3eaba5c8338120aeeb9e2b30ed3d02d926d09df0608e3d34a50dc3684226bec0ac97005faee9cf511ff
+  data.tar.gz: 6ef86677fcd7e1bcf1fcc76b1917cf499a10d099a6e97b421de5bd4cf7a4f42040d022f9e8cceb4baac54eee5842494fbf01a7f911bfb7863bb0ce43d0c6339d

data/CHANGELOG.md

@@ -1,12 +1,16 @@
 # Changelog
 
-## Unreleased
+## 0.6.2 — 2026-09-21
 
-- Add validated declarative element descriptions with event routing, tree diffs, and keyed surface reuse.
+- Add GIF decoding and a damage-aware terminal grid view.
+
+## 0.6.1 — 2026-09-21
+
+- Add a deterministic headless demo image and regeneration task.
 
 ## 0.6.0 — 2026-09-19
 
-- Add the validated declarative Describe layer for remote UI trees.
+- Add the validated declarative Describe layer for remote UI trees, including event routing, tree diffs, keyed surface reuse, and element descriptions.
 
 ## 0.5.3 — 2026-09-17
 

data/README.md

@@ -28,6 +28,8 @@ Zaniah is a pure Ruby UI toolkit for building desktop and terminal interfaces.
 It renders through native GPU APIs, a deterministic headless backend, or an ANSI
 terminal without extension compilation or a rendering subprocess.
 
+![Zaniah headless rendering](docs/media/overview.png)
+
 Zaniah is named for a star in Virgo. The toolkit is the drawing surface beneath
 the editor, providing the native rendering layer for its UI.
 

data/lib/zaniah/gif.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Zaniah
+  # Small, dependency-free GIF87a/GIF89a decoder. Frames are returned as RGBA
+  # snapshots so callers can choose whether to animate or keep the first frame.
+  module GIF
+    Frame = Data.define(:pixels, :delay, :disposal)
+    module_function
+
+    def decode(bytes, max_pixels: 16_777_216)
+      raise ArgumentError, "not a GIF" unless bytes.start_with?("GIF87a", "GIF89a")
+      reader = Reader.new(bytes)
+      reader.skip(6)
+      width, height, packed, background, = reader.bytes(7).unpack("vvCCC")
+      raise ArgumentError, "GIF too large" unless width.positive? && height.positive? && width * height <= max_pixels
+      global_palette = palette(reader, packed)
+      canvas = Array.new(width * height, [0, 0, 0, 0].freeze)
+      frames, gce = [], {delay: 0, disposal: 0, transparent: nil}
+
+      until reader.eof?
+        marker = reader.byte
+        case marker
+        when 0x3b then break
+        when 0x21
+          label = reader.byte
+          if label == 0xf9
+            reader.byte # block size
+            flags, delay, transparent = reader.bytes(4).unpack("CvvC")
+            reader.byte
+            gce = {delay: delay * 0.01, disposal: (flags >> 2) & 7, transparent: flags.anybits?(1) ? transparent : nil}
+          else
+            skip_subblocks(reader)
+          end
+        when 0x2c
+          frame = read_frame(reader, global_palette, width, height, canvas, gce)
+          frames << frame[:frame]
+          canvas = frame[:canvas]
+          gce = {delay: 0, disposal: 0, transparent: nil}
+        else
+          raise ArgumentError, "invalid GIF block"
+        end
+      end
+      raise ArgumentError, "GIF has no frames" if frames.empty?
+
+      [width, height, frames.freeze]
+    rescue IndexError => error
+      raise ArgumentError, "truncated GIF: #{error.message}"
+    end
+
+    def palette(reader, packed)
+      return [] unless packed.anybits?(0x80)
+      size = 2**((packed & 7) + 1)
+      reader.bytes(size * 3).bytes.each_slice(3).map { |rgb| [*rgb, 255].freeze }.freeze
+    end
+    private_class_method :palette
+
+    def read_frame(reader, global_palette, width, height, previous, gce)
+      left, top, frame_width, frame_height, packed = reader.bytes(9).unpack("vvvvC")
+      local_palette = palette(reader, packed)
+      palette = local_palette.empty? ? global_palette : local_palette
+      raise ArgumentError, "GIF frame has no palette" if palette.empty?
+      interlaced = packed.anybits?(0x40)
+      min_code_size = reader.byte
+      compressed = subblocks(reader)
+      indices = lzw_decode(compressed, min_code_size, frame_width * frame_height)
+      indices = deinterlace(indices, frame_width, frame_height) if interlaced
+      canvas = previous.map(&:dup)
+      saved = canvas.map(&:dup) if gce[:disposal] == 3
+      frame_height.times do |row|
+        frame_width.times do |column|
+          index = indices[row * frame_width + column]
+          next if index == gce[:transparent]
+          color = palette[index] || [0, 0, 0, 0].freeze
+          x, y = left + column, top + row
+          canvas[y * width + x] = color if x.between?(0, width - 1) && y.between?(0, height - 1)
+        end
+      end
+      pixels = canvas.flatten.pack("C*")
+      frame = Frame.new(pixels, gce[:delay], gce[:disposal])
+      disposed = case gce[:disposal]
+      when 2
+        canvas.map.with_index { |color, index| image_in_frame?(index, left, top, frame_width, frame_height, width) ? [0, 0, 0, 0].freeze : color }
+      when 3 then saved || canvas
+      else canvas
+      end
+      {frame: frame, canvas: disposed}
+    end
+    private_class_method :read_frame
+
+    def image_in_frame?(index, left, top, frame_width, frame_height, width)
+      x, y = index % width, index / width
+      x >= left && x < left + frame_width && y >= top && y < top + frame_height
+    end
+    private_class_method :image_in_frame?
+
+    def skip_subblocks(reader)
+      loop do
+        length = reader.byte
+        break if length.zero?
+        reader.skip(length)
+      end
+    end
+    private_class_method :skip_subblocks
+
+    def subblocks(reader)
+      result = +"".b
+      loop do
+        length = reader.byte
+        break if length.zero?
+        result << reader.bytes(length)
+      end
+      result
+    end
+    private_class_method :subblocks
+
+    def deinterlace(indices, width, height)
+      output = Array.new(indices.length)
+      offset = 0
+      [0, 4, 2, 1].zip([8, 8, 4, 2]).each do |start, step|
+        (start...height).step(step) do |row|
+          output[row * width, width] = indices[offset, width]
+          offset += width
+        end
+      end
+      output
+    end
+    private_class_method :deinterlace
+
+    def lzw_decode(bytes, minimum, expected)
+      raise ArgumentError, "invalid GIF LZW size" unless minimum.between?(2, 8)
+      clear, stop, code_size = 1 << minimum, (1 << minimum) + 1, minimum + 1
+      table = (0...clear).map { |value| [value] } + [nil, nil]
+      bit_offset, previous, output = 0, nil, []
+      read_code = lambda do
+        value = 0
+        code_size.times do |bit|
+          byte = bytes.getbyte((bit_offset + bit) / 8) || 0
+          value |= ((byte >> ((bit_offset + bit) % 8)) & 1) << bit
+        end
+        bit_offset += code_size
+        value
+      end
+      loop do
+        code = read_code.call
+        break if code == stop || output.length >= expected
+        if code == clear
+          table = (0...clear).map { |value| [value] } + [nil, nil]
+          code_size = minimum + 1
+          previous = nil
+          next
+        end
+        entry = if code < table.length && table[code]
+          table[code]
+        elsif previous
+          previous + [previous.first]
+        else
+          raise ArgumentError, "invalid GIF LZW code"
+        end
+        output.concat(entry)
+        if previous
+          table << previous + [entry.first]
+          code_size += 1 if table.length == (1 << code_size) && code_size < 12
+        end
+        previous = entry
+      end
+      raise ArgumentError, "truncated GIF image data" if output.length < expected
+      output.first(expected)
+    end
+    private_class_method :lzw_decode
+
+    class Reader
+      def initialize(bytes)
+        @bytes, @offset = bytes, 0
+      end
+
+      def eof? = @offset >= @bytes.bytesize
+      def byte = bytes(1).getbyte(0)
+      def bytes(length)
+        value = @bytes.byteslice(@offset, length)
+        raise IndexError, "unexpected end of input" unless value && value.bytesize == length
+        @offset += length
+        value
+      end
+      def skip(length)
+        bytes(length)
+      end
+    end
+  end
+end

data/lib/zaniah/image.rb

@@ -4,10 +4,21 @@ module Zaniah
   class Image < Element
     def initialize(path)
       super()
-      width, height, pixels = PNG.decode(File.binread(path))
+      bytes = File.binread(path)
+      width, height, pixels = if bytes.start_with?(PNG::SIGNATURE)
+        PNG.decode(bytes)
+      elsif bytes.start_with?("GIF87a", "GIF89a")
+        gif_width, gif_height, frames = GIF.decode(bytes)
+        @frames = frames
+        [gif_width, gif_height, frames.first.pixels]
+      else
+        raise ArgumentError, "unsupported image format"
+      end
       @texture = GPU::Texture.new(width, height, data: pixels)
     end
 
+    attr_reader :frames
+
     def request_layout(_cx)
       @layout_node = Layout::Node.new(style: @style, measure: ->(_width, _height) { [@texture.width, @texture.height] })
     end

data/lib/zaniah/ui/terminal_view.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Zaniah
+  module UI
+    # A fixed-cell terminal surface. It deliberately bypasses child elements:
+    # terminal grids are updated by row and are too dense for an element tree.
+    class TerminalView < Element
+      ANSI_COLORS = %w[#000000 #800000 #008000 #808000 #000080 #800080 #008080 #c0c0c0
+                       #808080 #ff0000 #00ff00 #ffff00 #0000ff #ff00ff #00ffff #ffffff].freeze
+
+      attr_reader :grid, :damage, :cell_width, :cell_height, :selection
+
+      def initialize(grid: nil, cell_width: 8, cell_height: 18, background: "#111318", foreground: "#ddd")
+        super()
+        @cell_width, @cell_height = Float(cell_width), Float(cell_height)
+        raise ArgumentError, "cell dimensions must be positive" unless @cell_width.positive? && @cell_height.positive?
+        @background, @foreground = background, foreground
+        @damage = nil
+        self.grid = grid if grid
+      end
+
+      def grid=(value)
+        unless value.respond_to?(:cells) && value.respond_to?(:columns) && value.respond_to?(:rows)
+          raise ArgumentError, "grid must expose cells, columns, and rows"
+        end
+        @grid = value
+        @damage = 0...value.rows
+        value
+      end
+
+      def update(value = @grid, damage: nil)
+        self.grid = value unless value.equal?(@grid)
+        @damage = damage || value.damage || (0...value.rows)
+        self
+      end
+
+      def select(range)
+        @selection = range && Range === range ? range : nil
+        self
+      end
+
+      def request_layout(_cx)
+        columns = @grid ? @grid.columns : 0
+        rows = @grid ? @grid.rows : 0
+        @layout_node = Layout::Node.new(style: @style,
+          measure: ->(_width, _height) { [columns * @cell_width, rows * @cell_height] })
+      end
+
+      def paint(bounds, state, prepaint, cx)
+        super
+        return self unless @grid
+
+        rows = @damage || (0...@grid.rows)
+        rows = [rows.begin, 0].max...[rows.end, @grid.rows].min
+        cx.scene.clip(bounds) do
+          rows.each { |row| paint_row(row, bounds, cx) }
+          paint_cursor(bounds, cx) if @grid.cursor_visible
+        end
+        @grid.clear_damage if @grid.respond_to?(:clear_damage)
+        @damage = nil
+        self
+      end
+
+      private
+
+      def paint_row(row, bounds, cx)
+        cells = @grid.cells.fetch(row)
+        column = 0
+        while column < cells.length
+          cell = cells[column]
+          if cell.background
+            run = column + 1
+            run += 1 while run < cells.length && cells[run].background == cell.background
+            cx.scene.quad(bounds.x + column * @cell_width, bounds.y + row * @cell_height,
+              (run - column) * @cell_width, @cell_height, color: color(cell.background))
+          end
+          if cell.width != 0 && cell.text != " "
+            paint_text(cell.text, cell.foreground || @foreground, bounds, row, column, cx)
+          end
+          column += 1
+        end
+      end
+
+      def paint_text(text, tint, bounds, row, column, cx)
+        return unless cx.text_system
+        line = cx.text_system.layout_line(text, size: @cell_height * 0.78)
+        cx.text_system.paint_line(cx.scene, line, x: bounds.x + column * @cell_width,
+          y: bounds.y + row * @cell_height + @cell_height * 0.82, color: color(tint))
+      end
+
+      def paint_cursor(bounds, cx)
+        x, y = @grid.cursor_x, @grid.cursor_y
+        cx.scene.layer(Scene::LAYER_SELECTION) do
+          cx.scene.quad(bounds.x + x * @cell_width, bounds.y + y * @cell_height,
+            @cell_width, @cell_height, color: "#ffffff55")
+        end
+      end
+
+      def color(value)
+        return value if value.is_a?(String)
+        return "##{value.map { |part| format("%02x", part) }.join}" if value.is_a?(Array)
+        return ANSI_COLORS.fetch(value, @foreground) if value.is_a?(Integer)
+        @foreground
+      end
+    end
+  end
+end

data/lib/zaniah/ui.rb

@@ -18,3 +18,4 @@ require_relative "ui/tree_view"
 require_relative "ui/charts"
 require_relative "ui/forms"
 require_relative "ui/editors"
+require_relative "ui/terminal_view"

data/lib/zaniah/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zaniah
-  VERSION = "0.6.0"
+  VERSION = "0.6.2"
 end

data/lib/zaniah.rb

@@ -25,6 +25,7 @@ require_relative "zaniah/text_selection"
 require_relative "zaniah/text_buffer"
 require_relative "zaniah/scene"
 require_relative "zaniah/png"
+require_relative "zaniah/gif"
 require_relative "zaniah/gpu"
 require_relative "zaniah/layout"
 require_relative "zaniah/style/style_set"

data/sig/ui_terminal_view.rbs

@@ -0,0 +1,15 @@
+module Zaniah
+  module UI
+    class TerminalView < Zaniah::Element
+      attr_reader grid: untyped?
+      attr_reader damage: Range[Integer]?
+      attr_reader cell_width: Float
+      attr_reader cell_height: Float
+      attr_reader selection: Range[Integer]?
+      def initialize: (grid: untyped?, cell_width: Numeric, cell_height: Numeric, background: String, foreground: String) -> void
+      def grid=: (untyped value) -> untyped
+      def update: (?untyped value, ?damage: Range[Integer]) -> self
+      def select: (Range[Integer]?) -> self
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zaniah
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Yudai Takada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-19 00:00:00.000000000 Z
+date: 2026-09-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: alhena
@@ -151,6 +151,8 @@ files:
 - docs/gallery/tooltip-top-light.png
 - docs/index.html
 - docs/layout.md
+- docs/media/overview.apng
+- docs/media/overview.png
 - docs/native.md
 - docs/process_pool.md
 - docs/site.css
@@ -217,6 +219,7 @@ files:
 - lib/zaniah/ffi/wayland.rb
 - lib/zaniah/frame_context.rb
 - lib/zaniah/geometry.rb
+- lib/zaniah/gif.rb
 - lib/zaniah/gpu.rb
 - lib/zaniah/gpu/buffer.rb
 - lib/zaniah/gpu/frame_encoder.rb
@@ -352,6 +355,7 @@ files:
 - lib/zaniah/ui/primitives.rb
 - lib/zaniah/ui/scrollbar.rb
 - lib/zaniah/ui/structure.rb
+- lib/zaniah/ui/terminal_view.rb
 - lib/zaniah/ui/text_inputs.rb
 - lib/zaniah/ui/tree_view.rb
 - lib/zaniah/ui/variants.rb
@@ -377,6 +381,7 @@ files:
 - sig/text.rbs
 - sig/theme.rbs
 - sig/ui.rbs
+- sig/ui_terminal_view.rbs
 - sig/zaniah.rbs
 - tools/check_dependencies.rb
 - tools/generate_component_gallery.rb