syrma 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0125f382e153f0c3485107cf3cbe4719733da7b250f3e2e7aeac507c7f3beab7
-  data.tar.gz: 53f0fd7a4f089b5a8b42e3ea36a2e0edef6c9aec39c6b1c8d006cd1850dcfa8a
+  metadata.gz: be544217dc4ba67f34fa4cb6a824be44ab74dee130324f615e0824c5ab23fd72
+  data.tar.gz: 970b020a33399800791693b1922aacdfa679d4260947c75ff938838b31ad8794
 SHA512:
-  metadata.gz: 2a124116d448b9c7d85cacb595e57a155b11cbf1f1f4a7ec2b97904d9b99aff2f00c35751c435fd2563a9efaa31ab8a53c098f192954c270fe95ad719d789a66
-  data.tar.gz: 299ed17ddf94e4c81db7f80517e3402640a55af4768386e5e0ac40668f40d015127cc738e79f0e1a9bb5da639ad8a32ce9b59e191a413b5dc700ae55ce770772
+  metadata.gz: a2e0b783bc7e6c66fba35676fc1d10117e4c0436362eb494f32d0d5e857ff2a1ad50f2f743722fd13ae31633a6a5ba9fe9a0475d79cbf1796edf3f94a9a5f878
+  data.tar.gz: f9d84eba21b734e63dc793461b7f3b45fb75be5ffc862915ede839c245e269296b4dd8690c570a3cd29f9236aa02263d31dfc4b06ce278e5934f01e6c309ab9b

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## Unreleased
+## 0.4.0 - 2026-09-24
+
+- Support Zaniah 0.7 inspection snapshots and semantic accessibility queries.
+- Use Zaniah's public font, executor, and frame APIs instead of internal instrumentation.
+
+## 0.3.0 - 2026-09-20
+
+- Add deterministic virtual-clock demo recording with humanized input, pixel-space chrome, and Wezen output hooks.
 
 ## 0.2.0 - 2026-09-15
 

data/README.md

@@ -24,6 +24,8 @@
 
 Syrma locates rendered elements, sends input through Zaniah's real event path, waits for redraws, and compares the observable result. Tests can inspect text, element trees, terminal output, pixels, screenshots, menus, and tooltips without bypassing application input handling.
 
+![Syrma deterministic recording](docs/media/overview.png)
+
 ## Features
 
 - Drive GUI and TUI sessions with pointer, keyboard, clipboard, composition, file-drop, resize, and terminal input
@@ -32,6 +34,7 @@ Syrma locates rendered elements, sends input through Zaniah's real event path, w
 - Keep timing deterministic with a session-scoped virtual clock and explicit frame settling
 - Test with Minitest assertions or RSpec matchers
 - Capture screenshots, hit regions, text runs, and recent events when a test fails
+- Record deterministic APNG/GIF frames and asciinema events from the virtual clock
 
 ## Installation
 
@@ -51,7 +54,24 @@ bundle install
 bundle exec syrma doctor
 ```
 
-Syrma requires Ruby 3.1 or later and supports Zaniah `>= 0.2, < 0.6`. RSpec users can replace Minitest with RSpec in the test group.
+Syrma requires Ruby 3.1 or later and supports Zaniah `>= 0.7, < 1.0`. RSpec users can replace Minitest with RSpec in the test group.
+
+### Demo recording
+
+Install `wezen` alongside Syrma to export a virtual-clock recording:
+
+```ruby
+result = session.record(fps: 12, seed: 42) do |recording|
+  recording.cursor
+  recording.caption("Open the file")
+  recording.type_humanly("README.md")
+  recording.pause(1.0)
+end
+result.write_apng("docs/media/overview.apng")
+```
+
+Recordings require a virtual clock and headless session for repeatable pixels.
+Use `session.record_cast` with a TUI session for asciinema v2 output.
 
 ## Quick start
 
@@ -115,11 +135,13 @@ end
 | Keyboard/text | `press`, `type`, `paste`, `compose`, `commit` |
 | Window/input | `resize`, `close`, `drop_files`, `feed_terminal` |
 | Synchronize | `settle`, `wait_for`, `advance` |
-| Inspect | `tree`, `texts`, `at`, `pixel`, `screenshot`, `terminal_lines`, `menu`, `tooltip` |
+| Inspect | `tree`, `texts`, `at`, `accessibility`, `pixel`, `screenshot`, `terminal_lines`, `menu`, `tooltip` |
 | Assert | Text, element, visibility, panels, decorations, background, pixel, tooltip, menu, tree/terminal/image snapshots |
 
 Locators are lazy: every operation resolves them against the latest rendered frame. Actions wait for visibility and an unobscured matching event handler, then send events through `Window#input`.
 
+`ui.accessibility(role: :button, label: "Save")` searches Zaniah's semantic tree and returns `[node, path]` pairs. Unlike visual locators, semantic nodes need not correspond to a rendered element or have bounds; use `ui.find` for pointer actions.
+
 Panel and decoration assertions use rendered `test_id` instrumentation, so application code does not need a Syrma or Canopus runtime dependency:
 
 ```ruby
@@ -165,6 +187,7 @@ On Ruby 4.0 arm64 macOS, the included 101-element benchmark measured `event_fram
 ```sh
 bundle install
 bundle exec rake
+bundle exec rake demo
 bundle exec ruby -Ilib:test script/test_gesture.rb
 bundle exec rbs -I sig validate
 gem build --strict syrma.gemspec

data/lib/syrma/cli.rb

@@ -40,7 +40,7 @@ module Syrma
       checks = {
         "Ruby" => "#{RUBY_VERSION} (#{RUBY_PLATFORM})",
         "zaniah" => Zaniah::VERSION,
-        "Bundled font" => File.file?(Internals.bundled_font_path) ? Internals.bundled_font_path : nil,
+        "Bundled font" => File.file?(Zaniah.bundled_font_path) ? Zaniah.bundled_font_path : nil,
         "YJIT" => defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled? ? "enabled" : "disabled",
         "External encoding" => Encoding.default_external.name
       }

data/lib/syrma/recording.rb

@@ -0,0 +1,401 @@
+# frozen_string_literal: true
+
+module Syrma
+  class Recording
+    FONT = {
+      "A" => %w[01110 10001 10001 11111 10001 10001 10001], "B" => %w[11110 10001 10001 11110 10001 10001 11110],
+      "C" => %w[01111 10000 10000 10000 10000 10000 01111], "D" => %w[11110 10001 10001 10001 10001 10001 11110],
+      "E" => %w[11111 10000 10000 11110 10000 10000 11111], "F" => %w[11111 10000 10000 11110 10000 10000 10000],
+      "G" => %w[01111 10000 10000 10111 10001 10001 01111], "H" => %w[10001 10001 10001 11111 10001 10001 10001],
+      "I" => %w[11111 00100 00100 00100 00100 00100 11111], "J" => %w[00111 00010 00010 00010 10010 10010 01100],
+      "K" => %w[10001 10010 10100 11000 10100 10010 10001], "L" => %w[10000 10000 10000 10000 10000 10000 11111],
+      "M" => %w[10001 11011 10101 10101 10001 10001 10001], "N" => %w[10001 11001 10101 10011 10001 10001 10001],
+      "O" => %w[01110 10001 10001 10001 10001 10001 01110], "P" => %w[11110 10001 10001 11110 10000 10000 10000],
+      "Q" => %w[01110 10001 10001 10001 10101 10010 01101], "R" => %w[11110 10001 10001 11110 10100 10010 10001],
+      "S" => %w[01111 10000 10000 01110 00001 00001 11110], "T" => %w[11111 00100 00100 00100 00100 00100 00100],
+      "U" => %w[10001 10001 10001 10001 10001 10001 01110], "V" => %w[10001 10001 10001 10001 10001 01010 00100],
+      "W" => %w[10001 10001 10001 10101 10101 11011 10001], "X" => %w[10001 10001 01010 00100 01010 10001 10001],
+      "Y" => %w[10001 10001 01010 00100 00100 00100 00100], "Z" => %w[11111 00001 00010 00100 01000 10000 11111],
+      "0" => %w[01110 10001 10011 10101 11001 10001 01110], "1" => %w[00100 01100 00100 00100 00100 00100 01110],
+      "2" => %w[01110 10001 00001 00010 00100 01000 11111], "3" => %w[11110 00001 00001 01110 00001 00001 11110],
+      "4" => %w[00010 00110 01010 10010 11111 00010 00010], "5" => %w[11111 10000 10000 11110 00001 00001 11110],
+      "6" => %w[01110 10000 10000 11110 10001 10001 01110], "7" => %w[11111 00001 00010 00100 01000 01000 01000],
+      "8" => %w[01110 10001 10001 01110 10001 10001 01110], "9" => %w[01110 10001 10001 01111 00001 00001 01110],
+      "." => %w[00000 00000 00000 00000 00000 00110 00110], "-" => %w[00000 00000 00000 01110 00000 00000 00000],
+      ":" => %w[00000 00110 00110 00000 00110 00110 00000], "/" => %w[00001 00010 00010 00100 01000 01000 10000]
+    }.freeze
+
+    Cast = Data.define(:width, :height, :events)
+    Result = Data.define(:animation, :cast, :frames, :duration_ms) do
+      def write_apng(path, **options)
+        require "wezen"
+        Wezen::APNG.write(path, animation, **options)
+      end
+
+      def write_gif(path, **options)
+        require "wezen"
+        Wezen::GIF.write(path, animation, **options)
+      end
+
+      def write_png(path)
+        raise Error, "recording has no animation" unless animation
+        frame = frames.last || raise(Error, "recording has no frames")
+        Zaniah::PNG.write(path, animation.width, animation.height, frame.rgba)
+        path
+      end
+
+      def write_cast(path, **options)
+        require "wezen"
+        source = cast.is_a?(Cast) ? cast : nil
+        raise Error, "recording has no cast dimensions" unless source
+        Wezen::Cast.write(path, width: source.width, height: source.height, events: source.events, **options)
+      end
+    end
+    Frame = Data.define(:rgba, :delay_ms)
+
+    attr_reader :session, :fps, :scale, :max_frames
+
+    def initialize(session, fps:, scale:, max_frames:, seed: nil, chrome: {}, cast_only: false)
+      @session = session
+      @fps = Float(fps)
+      @scale = Float(scale)
+      @max_frames = Integer(max_frames)
+      raise ArgumentError, "fps must be positive" unless @fps.positive?
+      raise ArgumentError, "scale must be positive" unless @scale.positive?
+      raise ArgumentError, "max_frames must be positive" unless @max_frames.positive?
+
+      @random = Random.new(seed.nil? ? 0 : Integer(seed))
+      @cast_only = cast_only
+      @frames = []
+      @captures = 0
+      @events = []
+      @elapsed = 0.0
+      @frame_remainder = 0.0
+      @cursor_visible = chrome.fetch(:cursor, false)
+      @keycaps_visible = chrome.fetch(:keycaps, false)
+      @cursor_style = :arrow
+      @cursor = [0, 0]
+      @keycap = nil
+      @keycap_until = 0.0
+      @caption_text = nil
+      @caption_until = 0.0
+      @highlight_bounds = nil
+      @highlight_until = 0.0
+      @zoom = nil
+      @zoom_until = 0.0
+      @last_output = ""
+      @events << event(0.0, :resize, "#{terminal_dimensions[0]}x#{terminal_dimensions[1]}") if @cast_only
+    end
+
+    def advance(seconds)
+      seconds = Float(seconds)
+      raise ArgumentError, "time cannot be negative" if seconds.negative?
+
+      interval = 1.0 / @fps
+      remaining = seconds
+      while remaining.positive? && @frame_remainder + remaining >= interval
+        step = interval - @frame_remainder
+        session.advance(step)
+        @elapsed += step
+        remaining -= step
+        @frame_remainder = 0.0
+        capture
+      end
+      if remaining.positive?
+        session.advance(remaining)
+        @elapsed += remaining
+        @frame_remainder += remaining
+      end
+      self
+    end
+
+    def pause(seconds)
+      advance(seconds)
+    end
+
+    def frame(count: 1)
+      Integer(count).times { capture }
+      self
+    end
+
+    def type_humanly(text, cps: 18, jitter: 0.25)
+      cps = Float(cps); jitter = Float(jitter)
+      raise ArgumentError, "cps must be positive" unless cps.positive?
+      raise ArgumentError, "jitter must be between 0 and 1" unless jitter.between?(0.0, 1.0)
+
+      text.each_grapheme_cluster do |character|
+        session.driver.type(character)
+        @keycap = character
+        @keycap_until = @elapsed + (@keycap_duration || 1.2)
+        advance((1.0 / cps) * (1.0 + (@random.rand * 2.0 - 1.0) * jitter))
+      end
+      self
+    end
+
+    def press_slowly(*keystrokes, hold: 0.08, gap: 0.25)
+      keystrokes.each do |keystroke|
+        session.driver.press(keystroke)
+        @keycap = keystroke.to_s
+        @keycap_until = @elapsed + (@keycap_duration || 1.2)
+        advance(hold)
+        advance(gap)
+      end
+      self
+    end
+
+    def click_slowly(target, approach: 0.4, **options)
+      point = point_for(target)
+      session.driver.mouse_move(point)
+      @cursor = [point.x, point.y]
+      advance(approach)
+      session.driver.click(target, **options)
+      self
+    end
+
+    def drag_slowly(from, to, duration: 0.8)
+      start = point_for(from); finish = point_for(to)
+      steps = [(Float(duration) * @fps).round, 1].max
+      session.driver.mouse_move(start)
+      session.driver.mouse_down(start)
+      steps.times do |index|
+        ratio = (index + 1).fdiv(steps)
+        point = Zaniah::Point.new(start.x + (finish.x - start.x) * ratio, start.y + (finish.y - start.y) * ratio)
+        session.driver.mouse_move(point)
+        @cursor = [point.x, point.y]
+        advance(1.0 / @fps)
+      end
+      session.driver.mouse_up(finish)
+      self
+    end
+
+    def scroll_smoothly(target, dy:, duration: 0.6)
+      steps = [(Float(duration) * @fps).round, 1].max
+      steps.times { session.driver.scroll(target, dy: Float(dy) / steps); advance(1.0 / @fps) }
+      self
+    end
+
+    def cursor(visible: true, style: :arrow)
+      @cursor_visible = !!visible
+      @cursor_style = style.to_sym
+      self
+    end
+
+    def keycaps(visible: true, duration: 1.2)
+      @keycaps_visible = !!visible
+      @keycap_duration = Float(duration)
+      self
+    end
+
+    def highlight(target, padding: 8, duration: 1.0)
+      node = target.respond_to?(:resolve) ? target.resolve : target
+      bounds = node.respond_to?(:bounds) ? node.bounds : node
+      @highlight_bounds = [bounds.x - padding, bounds.y - padding, bounds.width + padding * 2, bounds.height + padding * 2]
+      @highlight_until = @elapsed + Float(duration)
+      self
+    end
+
+    def caption(text, duration: 2.0, position: :bottom)
+      @caption_text = text.to_s
+      @caption_position = position.to_sym
+      @caption_until = @elapsed + Float(duration)
+      self
+    end
+
+    def zoom(_target, scale: 2.0, duration: 0.6)
+      factor = Float(scale)
+      raise ArgumentError, "zoom scale must be positive" unless factor.positive?
+      node = _target.respond_to?(:resolve) ? _target.resolve : _target
+      bounds = node.respond_to?(:bounds) ? node.bounds : node
+      @zoom = [bounds.x + bounds.width / 2.0, bounds.y + bounds.height / 2.0, factor]
+      @zoom_until = @elapsed + Float(duration)
+      advance(duration)
+      self
+    end
+
+    def result
+      animation = wezen_available? ? build_animation : nil
+      last_event_time = @events.last&.respond_to?(:time) ? @events.last.time : @events.last&.first
+      if @cast_only && last_event_time && last_event_time.to_f < @elapsed
+        @events << event(@elapsed, :output, "")
+      end
+      cast = @cast_only ? Cast.new(terminal_dimensions[0], terminal_dimensions[1], @events.freeze) : @events.freeze
+      Result.new(animation, cast, @frames.freeze, (@elapsed * 1000).round)
+    end
+
+    def write_apng(path, **options)
+      require_wezen
+      Wezen::APNG.write(path, build_animation, **options)
+    end
+
+    def write_gif(path, **options)
+      require_wezen
+      Wezen::GIF.write(path, build_animation, **options)
+    end
+
+    def write_png(path)
+      frame = @frames.last || raise(Error, "recording has no frames")
+      width, height = dimensions
+      Zaniah::PNG.write(path, width, height, frame.rgba)
+      path
+    end
+
+    def write_cast(path, **options)
+      require_wezen
+      width, height = terminal_dimensions
+      Wezen::Cast.write(path, width: width, height: height, events: @events, **options)
+    end
+
+    private
+
+    def require_wezen
+      require "wezen"
+    rescue LoadError => error
+      raise LoadError, "write_apng/write_gif/write_cast require the wezen gem (#{error.message})"
+    end
+
+    def wezen_available?
+      require "wezen"
+      true
+    rescue LoadError
+      false
+    end
+
+    def capture
+      raise Error, "record exceeded max_frames=#{@max_frames}" if @captures >= @max_frames
+      @captures += 1
+      if @cast_only
+        collect_output
+        return
+      end
+      pixels = session.screenshot_pixels
+      width, height = raw_dimensions
+      if @scale != 1.0
+        require_wezen
+        source_width, source_height = width, height
+        target_width = [(@scale * source_width).round, 1].max
+        target_height = [(@scale * source_height).round, 1].max
+        pixels = Wezen::Image.scale(pixels, source_width, source_height, to_width: target_width, to_height: target_height)
+        width = target_width; height = target_height
+      end
+      pixels = compose(pixels, width, height)
+      delay = (1000.0 / @fps).round
+      if (last = @frames.last) && last.rgba == pixels
+        # Keep one immutable buffer for a static interval; only its duration grows.
+        @frames[-1] = Frame.new(last.rgba, last.delay_ms + delay)
+      else
+        @frames << Frame.new(pixels.freeze, delay)
+      end
+      collect_output
+    end
+
+    def build_animation
+      require_wezen
+      animation = Wezen::Animation.new(width: dimensions.first, height: dimensions.last)
+      @frames.each { |frame| animation.add(frame.rgba, delay_ms: frame.delay_ms) }
+      animation
+    end
+
+    def dimensions
+      raw_dimensions.map { |value| [(@scale * value).round, 1].max }
+    end
+
+    def raw_dimensions
+      size = session.driver.window.content_size
+      [size.width.to_i, size.height.to_i]
+    end
+
+    def terminal_dimensions
+      size = session.driver.window.content_size
+      [size.width.to_i, size.height.to_i]
+    end
+
+    def point_for(target)
+      target = target.resolve if target.respond_to?(:resolve)
+      return target if target.is_a?(Zaniah::Point)
+      return Zaniah::Point.new(*target) if target.is_a?(Array) && target.length == 2
+      target.center
+    end
+
+    def collect_output
+      return unless session.tui?
+      output = session.output_for.string
+      delta = output.byteslice(@last_output.bytesize..)
+      @events << event(@elapsed, :output, delta) if delta && !delta.empty?
+      @last_output = output
+    end
+
+    def event(time, kind, data)
+      if defined?(Wezen::Cast::Event)
+        Wezen::Cast::Event.new(time, kind, data)
+      else
+        [time, kind, data]
+      end
+    end
+
+    def compose(pixels, width, height)
+      pixels = zoom_pixels(pixels, width, height) if @zoom && @elapsed < @zoom_until
+      output = pixels.dup
+      if @highlight_bounds && @elapsed < @highlight_until
+        x, y, w, h = @highlight_bounds
+        height.times do |row|
+          width.times do |column|
+            next if column.between?(x, x + w - 1) && row.between?(y, y + h - 1)
+            index = (row * width + column) * 4
+            red, green, blue, alpha = output.byteslice(index, 4).bytes
+            output[index, 4] = [(red * 0.35).round, (green * 0.35).round, (blue * 0.35).round, alpha].pack("C4")
+          end
+        end
+        rect(output, width, height, x, y, w, h, [255, 192, 0, 255])
+      end
+      rect(output, width, height, @cursor[0], @cursor[1], 2, 2, [255, 255, 255, 255, 255]) if @cursor_visible
+      if @keycaps_visible && @keycap && @elapsed < @keycap_until
+        rect(output, width, height, 12, height - 42, [@keycap.to_s.length * 8 + 20, 28].max, 28, [30, 30, 30, 220])
+        draw_text(output, width, height, @keycap.to_s, 20, height - 35, [255, 255, 255, 255], scale: 2)
+      end
+      if @caption_text && @elapsed < @caption_until
+        y = @caption_position == :top ? 0 : height - 48
+        rect(output, width, height, 0, y, width, 48, [0, 0, 0, 190])
+        draw_text(output, width, height, @caption_text, 12, y + 16, [255, 255, 255, 255], scale: 1)
+      end
+      output
+    end
+
+    def zoom_pixels(pixels, width, height)
+      center_x, center_y, factor = @zoom
+      output = String.new(capacity: pixels.bytesize, encoding: Encoding::BINARY)
+      height.times do |row|
+        source_y = (center_y + (row - height / 2.0) / factor).round
+        width.times do |column|
+          source_x = (center_x + (column - width / 2.0) / factor).round
+          output << if source_x.between?(0, width - 1) && source_y.between?(0, height - 1)
+            pixels.byteslice((source_y * width + source_x) * 4, 4)
+          else
+            "\0\0\0\0".b
+          end
+        end
+      end
+      output
+    end
+
+    def rect(pixels, width, height, x, y, rect_width, rect_height, color)
+      x = x.to_i; y = y.to_i; rect_width = rect_width.to_i; rect_height = rect_height.to_i
+      y0 = [y, 0].max; y1 = [y + rect_height, height].min; x0 = [x, 0].max; x1 = [x + rect_width, width].min
+      (y0...y1).each { |row| (x0...x1).each { |column| pixels[(row * width + column) * 4, 4] = color.pack("C4") } }
+    end
+
+    def draw_text(pixels, width, height, text, x, y, color, scale: 1)
+      text.to_s.upcase.each_char do |character|
+        glyph = FONT[character] || Array.new(7, "10001")
+        glyph.each_with_index do |row, row_index|
+          row.each_char.with_index do |value, column|
+            next unless value == "1"
+
+            rect(pixels, width, height, x + column * scale, y + row_index * scale, scale, scale, color)
+          end
+        end
+        x += 6 * scale
+        break if x >= width
+      end
+    end
+  end
+end

data/lib/syrma/session.rb

@@ -50,7 +50,7 @@ module Syrma
       @outputs = {}
       @windows = attached_windows || [open_window(backend, width, height, window_options, keymap)]
       @drivers = @windows.map { |window| prepare(window, backend, text, fonts) }
-      @font_paths = text == :deterministic ? [Internals.bundled_font_path, *fonts.map { |font| File.expand_path(font) }] : []
+      @font_paths = text == :deterministic ? [Zaniah.bundled_font_path, *fonts.map { |font| File.expand_path(font) }] : []
       @current = 0
       mount&.call(window)
       settle
@@ -69,6 +69,25 @@ module Syrma
     def driver = @drivers[@current]
     def session = self
     def virtual_clock? = @clock.is_a?(Clock)
+    def record(fps: 12, scale: 1.0, max_frames: 600, seed: nil, chrome: {}, &block)
+      raise Error, "record requires a virtual clock" unless virtual_clock?
+      raise Error, "record requires a headless backend" unless @backend == :headless
+      raise ArgumentError, "record requires a block" unless block
+
+      recording = Recording.new(self, fps: fps, scale: scale, max_frames: max_frames, seed: seed, chrome: chrome)
+      block.call(recording)
+      recording.result
+    end
+
+    def record_cast(fps: 12, seed: nil, max_frames: 600, &block)
+      raise UnsupportedBackend, "record_cast is only available for TUI sessions" unless tui?
+      raise Error, "record_cast requires a virtual clock" unless virtual_clock?
+      raise ArgumentError, "record_cast requires a block" unless block
+
+      recording = Recording.new(self, fps: fps, scale: 1.0, max_frames: max_frames, seed: seed, cast_only: true)
+      block.call(recording)
+      recording.result
+    end
     def method_missing(name, ...) = driver.respond_to?(name) ? driver.public_send(name, ...) : super
     def respond_to_missing?(name, include_all = false) = driver.respond_to?(name, include_all) || super
 
@@ -83,7 +102,7 @@ module Syrma
           candidate.tick
           busy = true
         end
-        return self unless busy || (@app && !Internals.executor_idle?(@app.executor))
+        return self unless busy || (@app && !@app.executor.idle?)
       end
       raise UnstableUI, "UI did not stabilize within #{@max_frames} frames (continuous animation?)"
     end

data/lib/syrma/snapshot.rb

@@ -14,10 +14,11 @@ module Syrma
     def inspect = "#<#{type}#{test_id && " @#{test_id}"}#{text && " #{text.inspect}"} #{path.join('.')}>"
   end
 
-  Tree = Data.define(:frame, :size, :root, :nodes, :hits, :text_runs, :menu, :menu_index, :tooltip) do
+  Tree = Data.define(:frame, :size, :root, :nodes, :hits, :text_runs, :menu, :menu_index, :tooltip, :hit_regions) do
     def hit_at(point, event: :mouse_down, button: :left)
-      hits.reverse_each do |bounds, node|
-        next unless bounds.contains?(point)
+      hits.length.times.reverse_each do |index|
+        _bounds, node = hits[index]
+        next unless hit_regions[index].contains?(point)
 
         return node if node.nil? || Tree.handles?(node, event, button)
       end
@@ -27,7 +28,7 @@ module Syrma
     def self.handles?(node, event, button)
       case event
       when :mouse_down
-        (button == :right && Internals.context_menu(node.element)) ||
+        (button == :right && node.element.respond_to?(:context_menu_items) && node.element.context_menu_items) ||
           (node.handlers & %i[mouse_down click drag]).any?
       when :mouse_move then node.handlers.include?(:hover) || node.tooltip
       when :mouse_up then node.handlers.include?(:mouse_up)
@@ -38,40 +39,43 @@ module Syrma
 
   class SnapshotBuilder
     def build(window)
+      snapshot = Zaniah::Inspection.snapshot(window)
       by_element = {}.compare_by_identity
       nodes = []
       viewport = Zaniah::Bounds.new(0, 0, window.content_size.width, window.content_size.height)
-      root = window.testing_root && visit(window.testing_root, viewport, [0], nodes, by_element)
-      hits = window.dispatcher.hits.map { |hit| [hit.bounds, hit.owner && by_element[hit.owner]] }
-      popup = window.popup
-      Tree.new(frame: window.testing_frame, size: window.content_size, root: root,
-               nodes: nodes.freeze, hits: hits.freeze, text_runs: window.text_runs.map(&:dup).freeze,
+      root = snapshot.root && visit(snapshot.root, viewport, [0], nodes, by_element)
+      hits = snapshot.hits.map { |hit| [hit.bounds, hit.owner && by_element[hit.owner]] }
+      popup = snapshot.overlays.popup
+      tooltip = snapshot.overlays.tooltip
+      Tree.new(frame: snapshot.frame.number, size: window.content_size, root: root,
+               nodes: nodes.freeze, hits: hits.freeze, hit_regions: snapshot.hits, text_runs: snapshot.text_runs,
                menu: popup&.labels, menu_index: popup&.selected_index,
-               tooltip: Internals.shown_tooltip(window))
+               tooltip: tooltip && tooltip[:shown] ? tooltip[:text] : nil)
     end
 
     private
 
-    def visit(element, clip, path, nodes, by_element)
-      bounds = element.layout_node&.bounds or return nil
-      style = Internals.style(element)
+    def visit(entry, clip, path, nodes, by_element)
+      bounds = entry.bounds or return nil
+      style = entry.style
       return nil if style[:display] == :none
 
       visible = bounds.intersect(clip)
       child_clip = style[:overflow] == :visible ? clip : visible
       index = nodes.length
       nodes << nil
-      children = element.children.each_with_index.filter_map do |child, child_index|
+      children = entry.children.each_with_index.filter_map do |child, child_index|
         visit(child, child_clip, path + [child_index], nodes, by_element)
       end
+      element = entry.element
       node = Node.new(
-        path: path.freeze, element: element, type: element.class.name.split("::").last.downcase.to_sym,
-        test_id: element.test_id, key: Internals.key(element),
+        path: path.freeze, element: element, type: entry.type.split("::").last.downcase.to_sym,
+        test_id: entry.test_id, key: entry.key,
         text: text_attr(element, :text), color: text_attr(element, :text_color),
         font_size: text_attr(element, :font_size), bounds: bounds, visible_bounds: visible,
-        background: Internals.background(element), border_color: Internals.border_color(element),
-        radius: Internals.radius(element), handlers: element.handlers,
-        tooltip: Internals.tooltip(element), children: children.freeze
+        background: style[:background], border_color: style[:border_color],
+        radius: style[:corner_radii], handlers: entry.handlers,
+        tooltip: entry.tooltip, children: children.freeze
       )
       nodes[index] = node
       by_element[element] = node

data/lib/syrma/text_systems.rb

@@ -9,7 +9,7 @@ module Syrma
       when :none, nil then nil
       when :native then Zaniah::TextSystem::Renderer.new
       when :deterministic
-        paths = [Internals.bundled_font_path, *fonts.map { |font| File.expand_path(font) }]
+        paths = [Zaniah.bundled_font_path, *fonts.map { |font| File.expand_path(font) }]
         missing = paths.reject { |path| File.file?(path) }
         raise ArgumentError, "Fonts not found: #{missing.join(', ')}" unless missing.empty?
 

data/lib/syrma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Syrma
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/syrma/window_driver.rb

@@ -17,7 +17,7 @@ module Syrma
 
     def tree
       session.settle
-      @tree = nil if @tree && @tree.frame != window.testing_frame
+      @tree = nil if @tree && @tree.frame != window.frame_number
       @tree ||= @builder.build(window)
     end
 
@@ -27,6 +27,10 @@ module Syrma
     def text(value) = find(text: value)
     def texts = tree.text_runs.map { |run| run[2] }
     def tooltip = tree.tooltip
+    def accessibility(role: nil, label: nil, states: {})
+      session.settle
+      Zaniah::Inspection.snapshot(window).accessibility.query(role: role, label: label, states: states)
+    end
 
     def button(label)
       find(clickable: true) do |node|
@@ -182,7 +186,7 @@ module Syrma
     def menu = (@menu_driver ||= PopupDriver.new(self))
 
     def dispatch(event)
-      session.event_log.add(window.testing_frame, window.title, event)
+      session.event_log.add(window.frame_number, window.title, event)
       window.input(event)
       session.settle unless @in_gesture && session.event_frames == :gesture
       event

data/lib/syrma.rb

@@ -4,7 +4,6 @@ require "zaniah"
 require_relative "syrma/version"
 require_relative "syrma/configuration"
 require_relative "syrma/errors"
-require_relative "syrma/internals"
 require_relative "syrma/instrumentation"
 require_relative "syrma/clock"
 require_relative "syrma/text_systems"
@@ -15,6 +14,7 @@ require_relative "syrma/event_log"
 require_relative "syrma/event_codec"
 require_relative "syrma/recorder"
 require_relative "syrma/window_driver"
+require_relative "syrma/recording"
 require_relative "syrma/popup_driver"
 require_relative "syrma/session"
 require_relative "syrma/visual/comparator"

data/sig/syrma.rbs

@@ -78,6 +78,7 @@ module Syrma
     attr_reader root: Node?
     attr_reader nodes: Array[Node]
     attr_reader hits: Array[untyped]
+    attr_reader hit_regions: Array[untyped]
     attr_reader text_runs: Array[untyped]
     attr_reader menu: Array[String]?
     attr_reader menu_index: Integer?
@@ -146,6 +147,8 @@ module Syrma
     def driver: () -> WindowDriver
     def session: () -> Session
     def virtual_clock?: () -> bool
+    def record: (?fps: Numeric, ?scale: Numeric, ?max_frames: Integer, ?seed: Integer?, ?chrome: Hash[Symbol, untyped]) { (Recording) -> untyped } -> Recording::Result
+    def record_cast: (?fps: Numeric, ?seed: Integer?, ?max_frames: Integer) { (Recording) -> untyped } -> Recording::Result
     def settle: () -> Session
     def advance: (Numeric seconds) -> Session
     def wait_for: (?untyped message, ?timeout: Numeric) { () -> untyped } -> untyped
@@ -157,6 +160,36 @@ module Syrma
     def method_missing: (Symbol name, *untyped, **untyped) -> untyped
   end
 
+  class Recording
+    class Frame
+      attr_reader rgba: String
+      attr_reader delay_ms: Integer
+    end
+    class Result
+      attr_reader animation: untyped
+      attr_reader cast: untyped
+      attr_reader frames: Array[Frame]
+      attr_reader duration_ms: Integer
+      def write_apng: (String path, **untyped) -> String
+      def write_gif: (String path, **untyped) -> String
+      def write_png: (String path) -> String
+      def write_cast: (String path, **untyped) -> String
+    end
+    def advance: (Numeric seconds) -> self
+    def pause: (Numeric seconds) -> self
+    def frame: (?count: Integer) -> self
+    def type_humanly: (String text, ?cps: Numeric, ?jitter: Numeric) -> self
+    def press_slowly: (*String keystrokes, ?hold: Numeric, ?gap: Numeric) -> self
+    def click_slowly: (untyped target, ?approach: Numeric, **untyped) -> self
+    def drag_slowly: (untyped from, untyped to, ?duration: Numeric) -> self
+    def scroll_smoothly: (untyped target, dy: Numeric, ?duration: Numeric) -> self
+    def cursor: (?visible: bool, ?style: Symbol) -> self
+    def keycaps: (?visible: bool, ?duration: Numeric) -> self
+    def highlight: (untyped target, ?padding: Numeric, ?duration: Numeric) -> self
+    def caption: (String text, ?duration: Numeric, ?position: Symbol) -> self
+    def zoom: (untyped target, ?scale: Numeric, ?duration: Numeric) -> self
+  end
+
   class WindowDriver
     attr_reader window: untyped
     attr_reader session: Session
@@ -168,6 +201,7 @@ module Syrma
     def text: (String | Regexp value) -> Locator
     def texts: () -> Array[String]
     def tooltip: () -> String?
+    def accessibility: (?role: Symbol?, ?label: String | Regexp | nil, ?states: Hash[Symbol, untyped]) -> Array[[untyped, Array[Integer]]]
     def button: (String label) -> Locator
     def at: (untyped x, ?untyped y, ?event: Symbol, ?button: Symbol) -> Node?
     def pixel: (Integer x, Integer y) -> Array[Integer]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: syrma
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yudai Takada
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zaniah
@@ -16,20 +16,40 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: wezen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
       - !ruby/object:Gem::Version
         version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.2'
 description: 'Drive Zaniah windows headlessly: locate elements, send real input events,
   and assert text, layout, pixels, and snapshots.'
 email:
@@ -53,12 +73,12 @@ files:
 - lib/syrma/event_codec.rb
 - lib/syrma/event_log.rb
 - lib/syrma/instrumentation.rb
-- lib/syrma/internals.rb
 - lib/syrma/minitest.rb
 - lib/syrma/popup_driver.rb
 - lib/syrma/query.rb
 - lib/syrma/rake_task.rb
 - lib/syrma/recorder.rb
+- lib/syrma/recording.rb
 - lib/syrma/report.rb
 - lib/syrma/rspec.rb
 - lib/syrma/script_launcher.rb

data/lib/syrma/internals.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Syrma
-  module Internals
-    module_function
-
-    def style(element) = element.instance_variable_get(:@style) || {}
-    def background(element) = paint_value(element, :background, :@background)
-    def border_color(element) = paint_value(element, :border_color, :@border_color)
-    def radius(element) = paint_value(element, :corner_radii, :@radius)
-    def tooltip(element) = element.instance_variable_get(:@tooltip)
-    def context_menu(element) = element.instance_variable_get(:@context_menu)
-    def key(element) = element.instance_variable_get(:@key)
-    def shown_tooltip(window)
-      tip = window.instance_variable_get(:@tooltip)
-      tip && tip[:shown] ? tip[:text] : nil
-    end
-
-    def bundled_font_path
-      _, entry = $LOAD_PATH.resolve_feature_path("zaniah")
-      File.expand_path("../assets/fonts/Abel-Regular.ttf", File.dirname(entry))
-    end
-
-    def executor_idle?(executor) = executor.instance_variable_get(:@foreground).empty?
-
-    def paint_value(element, property, legacy)
-      resolved = element.respond_to?(:resolved_style) ? element.resolved_style : nil
-      resolved&.[](property) || element.instance_variable_get(legacy) || style(element)[property]
-    end
-    private_class_method :paint_value
-  end
-end