syrma 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9ef547e116ba3d928630699b7ae95646b0604108499429bc978bf31faa502bf
-  data.tar.gz: 01de9448ef8c33a18af96280ba15a993cf08be62292408de956aa8be78572a8c
+  metadata.gz: b76bd8cacebc9d29ee6b28a913efb6ef5ec7283cdf6462279064343207925a71
+  data.tar.gz: 5ee18a3987ecee83fd8c2a334afee51c1a161f3e892c155d0a9b1ecda3e0e68a
 SHA512:
-  metadata.gz: 15af45c54231f18c6c10b7db2354a644bc206c584c515a169672ad562db43753f5753ececea2c829b04d418b83181c6689c0571be115dea91109425b74bc0342
-  data.tar.gz: 15c60ea282171fb9e17427769fd81b5510218590afb0126d51349bf16a73c5b5a58b9657fe0a27e3d1140a3fcfc3e70270c013c02445dbedc71ce0cbb93b2640
+  metadata.gz: 8166b829a204806d7c53c101bebab2b1568e95d2af3756510aa85eecf76a9234602b656a316388ce5f0c2f09b4e949b6ba18076aaabf8b2b9e2146ba69d88348
+  data.tar.gz: 11694f50f19407679166aa2cc305c1418832a3075166e76d9153cbd17b31996989f7211bd7b9997ba9f8818903a17147f5342196cd6d2ff4a4f7d9aa4ef6214f

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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
+
+- Add Minitest assertions and RSpec matchers for instrumented panels and editor decorations.
+- Support Zaniah 0.2 through 0.5 in headless instrumentation.
+
 ## 0.1.0 - 2026-09-11
 
 - Initial release.

data/README.md

@@ -1,10 +1,44 @@
-# Syrma
+<h1 align="center">Syrma</h1>
 
-Syrma drives [Zaniah](https://github.com/noxdea/zaniah) GUI and TUI applications from Ruby tests. It locates rendered elements, sends input through Zaniah's real event path, waits for redraws, and compares text, trees, terminal output, pixels, and screenshots.
+<p align="center">
+  <strong>Drive and assert <a href="https://github.com/noxdea/zaniah">Zaniah</a> GUI and TUI applications from Ruby tests.</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/syrma"><img src="https://img.shields.io/gem/v/syrma.svg" alt="Gem version"></a>
+  <a href="https://github.com/noxdea/syrma/actions/workflows/main.yml"><img src="https://github.com/noxdea/syrma/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-3.1%2B-CC342D.svg" alt="Ruby 3.1+"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/github/license/noxdea/syrma.svg" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <a href="https://noxdea.github.io/syrma/">Website</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#snapshots-and-diagnostics">Snapshots</a> ·
+  <a href="#documentation">Documentation</a>
+</p>
+
+---
+
+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
+- Locate elements by text, test ID, actionability, or nested queries resolved against the latest frame
+- Assert semantic output first, with tree, terminal, pixel, and screenshot snapshots when needed
+- 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
 
-Add Syrma to the test group in your `Gemfile`:
+Add Syrma and your test framework to the test group in your `Gemfile`:
 
 ```ruby
 group :test do
@@ -13,11 +47,35 @@ group :test do
 end
 ```
 
-Then run `bundle install` and `bundle exec syrma doctor`.
+Then install the bundle and verify the test environment:
+
+```sh
+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.
+
+### 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.
 
-## Minimal test
+## Quick start
 
-Keep window creation separate from the code that mounts your UI:
+Keep window creation separate from the code that mounts the interface:
 
 ```ruby
 module Counter
@@ -32,6 +90,8 @@ module Counter
 end
 ```
 
+### Minitest
+
 ```ruby
 require "syrma/minitest"
 
@@ -43,12 +103,27 @@ class CounterTest < Minitest::Test
   end
 
   def test_increment
-    ui.find(test_id: "increment").click
+    ui.test_id("increment").click
     assert_ui_text "Count: 1"
   end
 end
 ```
 
+### RSpec
+
+```ruby
+require "syrma/rspec"
+
+RSpec.describe "Counter", type: :zaniah do
+  before { zaniah_session(width: 320, height: 200) { |window| Counter.mount(window) } }
+
+  it "increments the count" do
+    ui.test_id("increment").click
+    expect(ui).to have_ui_text("Count: 1")
+  end
+end
+```
+
 `test_id` is provided by Zaniah 0.2 and is safe to use in application code.
 
 ## API at a glance
@@ -61,10 +136,22 @@ end
 | Window/input | `resize`, `close`, `drop_files`, `feed_terminal` |
 | Synchronize | `settle`, `wait_for`, `advance` |
 | Inspect | `tree`, `texts`, `at`, `pixel`, `screenshot`, `terminal_lines`, `menu`, `tooltip` |
-| Assert | text, element, visibility, clickability, background, pixel, tooltip, menu, tree/terminal/image snapshots |
+| 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`.
 
+Panel and decoration assertions use rendered `test_id` instrumentation, so application code does not need a Syrma or Canopus runtime dependency:
+
+```ruby
+assert_panel_visible :problems
+assert_panel_badge :problems, 3
+assert_inline_overlay line: 10, text: ": String"
+assert_gutter_marker line: 5, kind: :breakpoint
+assert_line_highlight line: 12, kind: :debug_position
+```
+
+The corresponding IDs are `syrma:panel:problems`, `syrma:panel:problems:badge`, `syrma:decoration:inline:10`, `syrma:decoration:gutter:5:breakpoint`, and `syrma:decoration:line:12:debug_position`. Lines are zero-based. Instrument the element that was actually laid out and painted; assertions require positive visible bounds. RSpec provides the same names with `have_` in place of `assert_`.
+
 ## Snapshots and diagnostics
 
 ```ruby
@@ -81,24 +168,32 @@ bundle exec syrma snapshots prune --dry-run
 bundle exec syrma report
 ```
 
-## Determinism and speed
+## Determinism and performance
 
 The default text renderer uses only Zaniah's bundled Abel font plus files passed in `fonts:`. Add a repository-owned font for non-Latin screenshot tests. `text: :none` is faster but does not draw glyphs.
 
 On Ruby 4.0 arm64 macOS, the included 101-element benchmark measured `event_frames: :gesture` at 3.1 ms per click/check with `text: :none` and 7.9 ms with deterministic text; Syrma's tree build plus locator resolution was about 0.28 ms. Run `bundle exec ruby -Ilib bench/click_bench.rb gesture` on the target CI host for relevant numbers.
 
-See [the guide](docs/guide.md) and [recipes](docs/recipes.md) for the full workflow.
+## Documentation
+
+- [Guide](docs/guide.md): application structure, sessions, CI, configuration, and troubleshooting
+- [Recipes](docs/recipes.md): interactions, screenshots, TUI sessions, and multiple windows
+- [Changelog](CHANGELOG.md): release history
 
 ## Development
 
 ```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
 ```
 
-Syrma supports Ruby 3.1+ and Zaniah `~> 0.2.0`. Virtual time is scoped to each session.
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/noxdea/syrma).
 
 ## License
 

data/lib/syrma/instrumentation.rb

@@ -6,7 +6,7 @@ module Syrma
 
     module WindowCapture
       attr_reader :testing_root, :testing_clear, :testing_frame
-      attr_accessor :testing_lazy_raster
+      attr_accessor :testing_lazy_raster, :testing_reduce_motion
 
       def on_frame(&callback)
         @testing_on_frame = callback
@@ -29,8 +29,15 @@ module Syrma
         @testing_recorder = recorder
       end
 
-      def render(element, present: true, **options)
-        super(element, present: present && !testing_lazy_raster, **options)
+      def render(element, present: true, **options) = super(element, present: present && !testing_lazy_raster, **options)
+    end
+
+    module FrameContextCapture
+      def theme
+        current = super
+        return current unless window.respond_to?(:testing_reduce_motion) && window.testing_reduce_motion
+
+        current.with(motion: current.motion.with(reduced: true))
       end
     end
 
@@ -56,6 +63,7 @@ module Syrma
         return if @installed
 
         Zaniah::Platform.singleton_class.prepend(BackendOverride)
+        Zaniah::FrameContext.prepend(FrameContextCapture) if Zaniah::FrameContext.method_defined?(:theme)
         @installed = true
       end
 
@@ -69,9 +77,10 @@ module Syrma
         Thread.current[:syrma_window_capture] = previous
       end
 
-      def capture(window, lazy_raster:)
+      def capture(window, lazy_raster:, reduce_motion:)
         window.extend(WindowCapture) unless window.is_a?(WindowCapture)
         window.testing_lazy_raster = lazy_raster
+        window.testing_reduce_motion = reduce_motion
         window.on_frame
         window
       end

data/lib/syrma/internals.rb

@@ -5,9 +5,9 @@ module Syrma
     module_function
 
     def style(element) = element.instance_variable_get(:@style) || {}
-    def background(element) = element.instance_variable_get(:@background)
-    def border_color(element) = element.instance_variable_get(:@border_color)
-    def radius(element) = element.instance_variable_get(:@radius)
+    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)
@@ -22,5 +22,11 @@ module Syrma
     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

data/lib/syrma/minitest.rb

@@ -94,6 +94,35 @@ module Syrma
       end
     end
 
+    def assert_panel_visible(id, session: ui, timeout: session.timeout)
+      test_id = UIAssertions.panel_id(id)
+      assert_ui_instrumentation(session, timeout, test_id, "panel #{id.inspect} to be visible", "#{UIAssertions::PREFIX}:panel:")
+    end
+
+    def assert_panel_badge(id, value, session: ui, timeout: session.timeout)
+      test_id = UIAssertions.panel_id(id, badge: true)
+      assert_ui_instrumentation(session, timeout, test_id, "panel #{id.inspect} badge to be #{value.inspect}",
+                                "#{UIAssertions::PREFIX}:panel:", text: value)
+    end
+
+    def assert_inline_overlay(line:, text:, session: ui, timeout: session.timeout)
+      test_id = UIAssertions.decoration_id(:inline, line)
+      assert_ui_instrumentation(session, timeout, test_id, "inline overlay on line #{line} with text #{text.inspect}",
+                                "#{UIAssertions::PREFIX}:decoration:inline:", text: text)
+    end
+
+    def assert_gutter_marker(line:, kind:, session: ui, timeout: session.timeout)
+      test_id = UIAssertions.decoration_id(:gutter, line, kind)
+      assert_ui_instrumentation(session, timeout, test_id, "#{kind.inspect} gutter marker on line #{line}",
+                                "#{UIAssertions::PREFIX}:decoration:gutter:")
+    end
+
+    def assert_line_highlight(line:, kind:, session: ui, timeout: session.timeout)
+      test_id = UIAssertions.decoration_id(:line, line, kind)
+      assert_ui_instrumentation(session, timeout, test_id, "#{kind.inspect} line highlight on line #{line}",
+                                "#{UIAssertions::PREFIX}:decoration:line:")
+    end
+
     def assert_screenshot(name, session: ui, **options)
       warn "syrma: text: :none does not render text in images" if session.text_mode == :none
       store = Snapshots::Store.new
@@ -154,6 +183,13 @@ module Syrma
       flunk error.message
     end
 
+    def assert_ui_instrumentation(session, timeout, test_id, expectation, prefix, text: UIAssertions::ANY_TEXT)
+      ui_eventually(session, timeout,
+                    -> { "Expected #{expectation}; observed #{UIAssertions.describe(session, prefix)}" }) do
+        UIAssertions.visible?(session, test_id, text: text)
+      end
+    end
+
     def snapshot_path(store, name, extension)
       test_file = self.class.instance_method(self.name.to_sym).source_location&.first || "unknown"
       store.path(test_file: test_file, test_class: self.class.name, name: name, ext: extension)

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/rspec.rb

@@ -102,6 +102,33 @@ module Syrma
       failure_message { |session| "Expected menu items #{labels.inspect} (current: #{session.menu.items.inspect})" }
     end
 
+    {
+      have_panel_visible: ->(id) { [UIAssertions.panel_id(id), UIAssertions::ANY_TEXT, "panel #{id.inspect} to be visible", "#{UIAssertions::PREFIX}:panel:"] },
+      have_panel_badge: ->(id, value) { [UIAssertions.panel_id(id, badge: true), value, "panel #{id.inspect} badge to be #{value.inspect}", "#{UIAssertions::PREFIX}:panel:"] },
+      have_inline_overlay: ->(line:, text:) { [UIAssertions.decoration_id(:inline, line), text, "inline overlay on line #{line} with text #{text.inspect}", "#{UIAssertions::PREFIX}:decoration:inline:"] },
+      have_gutter_marker: ->(line:, kind:) { [UIAssertions.decoration_id(:gutter, line, kind), UIAssertions::ANY_TEXT, "#{kind.inspect} gutter marker on line #{line}", "#{UIAssertions::PREFIX}:decoration:gutter:"] },
+      have_line_highlight: ->(line:, kind:) { [UIAssertions.decoration_id(:line, line, kind), UIAssertions::ANY_TEXT, "#{kind.inspect} line highlight on line #{line}", "#{UIAssertions::PREFIX}:decoration:line:"] }
+    }.each do |name, query|
+      ::RSpec::Matchers.define name do |*args, **keywords|
+        match do |session|
+          @test_id, @text, @expectation, @prefix = query.call(*args, **keywords)
+          @session = session
+          RSpec.eventually(session) { UIAssertions.visible?(session, @test_id, text: @text) }
+        end
+        match_when_negated do |session|
+          @test_id, @text, @expectation, @prefix = query.call(*args, **keywords)
+          @session = session
+          RSpec.eventually(session) { !UIAssertions.visible?(session, @test_id, text: @text) }
+        end
+        failure_message do
+          "Expected #{@expectation}; observed #{UIAssertions.describe(@session, @prefix)}"
+        end
+        failure_message_when_negated do
+          "Expected #{@expectation} not to match; observed #{UIAssertions.describe(@session, @prefix)}"
+        end
+      end
+    end
+
     ::RSpec::Matchers.define :match_screenshot do |name, **options|
       match do |session|
         store = Snapshots::Store.new

data/lib/syrma/session.rb

@@ -68,6 +68,26 @@ 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
 

data/lib/syrma/ui_assertions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Syrma
+  module UIAssertions
+    PREFIX = "syrma"
+    ANY_TEXT = Object.new.freeze
+
+    module_function
+
+    def panel_id(id, badge: false) = [PREFIX, "panel", component(id, "panel id"), badge ? "badge" : nil].compact.join(":")
+
+    def decoration_id(kind, line, type = nil)
+      raise ArgumentError, "line must be a nonnegative integer" unless line.is_a?(Integer) && line >= 0
+
+      kind = component(kind, "decoration kind")
+      type = component(type, "decoration type") unless type.nil?
+      [PREFIX, "decoration", kind, line, type].compact.join(":")
+    end
+
+    def visible?(session, test_id, text: ANY_TEXT)
+      nodes(session, test_id).any? do |node|
+        node.visible? && (text.equal?(ANY_TEXT) || text_match?(node.content_text, text))
+      end
+    end
+
+    def describe(session, prefix)
+      found = session.tree.nodes.select { |node| node.test_id&.start_with?(prefix) }
+      return "none" if found.empty?
+
+      found.first(10).map do |node|
+        "#{node.test_id}=#{node.content_text.inspect} (#{node.visible? ? 'visible' : 'hidden'})"
+      end.join(", ")
+    end
+
+    def nodes(session, test_id) = session.tree.nodes.select { |node| node.test_id == test_id }
+
+    def text_match?(actual, expected)
+      expected.is_a?(Regexp) ? expected.match?(actual) : actual == expected.to_s
+    end
+
+    def component(value, label)
+      valid = value.is_a?(String) || value.is_a?(Symbol)
+      value = value.to_s
+      valid &&= !value.empty? && !value.include?(":") && !value.match?(/[\x00-\x1f\x7f]/)
+      raise ArgumentError, "#{label} must be a nonempty string or symbol without colons or control characters" unless valid
+
+      value
+    end
+    private_class_method :component
+  end
+end

data/lib/syrma/version.rb

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

data/lib/syrma/window_driver.rb

@@ -9,7 +9,7 @@ module Syrma
     def initialize(window, session)
       @window = window
       @session = session
-      Instrumentation.capture(window, lazy_raster: session.raster == :lazy)
+      Instrumentation.capture(window, lazy_raster: session.raster == :lazy, reduce_motion: session.virtual_clock?)
       @builder = SnapshotBuilder.new
     end
 
@@ -162,9 +162,19 @@ module Syrma
     def scroll_until(list, found:, step: 100, max: 50)
       target = find(**found)
       max.times do
-        return target if target.exists? && target.resolve_all.any?(&:visible?)
-
-        scroll(list, dy: step)
+        candidates = target.resolve_all
+        return target if candidates.any?(&:visible?)
+
+        container = resolve_node(list)
+        candidate = candidates.first
+        dy = if candidate && candidate.bounds.y >= container.visible_bounds.y + container.visible_bounds.height
+               candidate.bounds.y - container.visible_bounds.y - container.visible_bounds.height + 1
+             elsif candidate && candidate.bounds.y + candidate.bounds.height <= container.visible_bounds.y
+               candidate.bounds.y + candidate.bounds.height - container.visible_bounds.y - 1
+             else
+               step
+             end
+        scroll(list, dy: dy)
       end
       raise ElementNotFound.new(target, tree)
     end

data/lib/syrma.rb

@@ -10,10 +10,12 @@ require_relative "syrma/clock"
 require_relative "syrma/text_systems"
 require_relative "syrma/snapshot"
 require_relative "syrma/query"
+require_relative "syrma/ui_assertions"
 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

@@ -145,6 +145,9 @@ module Syrma
     def window: (?title: String?, ?index: Integer?) -> untyped
     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
@@ -156,6 +159,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
@@ -258,6 +291,11 @@ module Syrma
     def assert_pixel: (Integer x, Integer y, untyped color, **untyped) -> bool
     def assert_tooltip: (String | Regexp expected, **untyped) -> bool
     def assert_menu_items: (Array[String] labels, **untyped) -> bool
+    def assert_panel_visible: (String | Symbol id, **untyped) -> bool
+    def assert_panel_badge: (String | Symbol id, untyped value, **untyped) -> bool
+    def assert_inline_overlay: (line: Integer, text: String | Regexp, **untyped) -> bool
+    def assert_gutter_marker: (line: Integer, kind: String | Symbol, **untyped) -> bool
+    def assert_line_highlight: (line: Integer, kind: String | Symbol, **untyped) -> bool
     def assert_screenshot: (String name, **untyped) -> bool
     def assert_tree_snapshot: (String name, **untyped) -> bool
     def assert_terminal_snapshot: (String name, **untyped) -> bool

metadata

@@ -1,28 +1,55 @@
 --- !ruby/object:Gem::Specification
 name: syrma
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zaniah
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !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.2.0
+        version: '0.2'
 description: 'Drive Zaniah windows headlessly: locate elements, send real input events,
   and assert text, layout, pixels, and snapshots.'
 email:
@@ -52,6 +79,7 @@ files:
 - 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
@@ -61,18 +89,20 @@ files:
 - lib/syrma/snapshots/terminal_format.rb
 - lib/syrma/snapshots/tree_format.rb
 - lib/syrma/text_systems.rb
+- lib/syrma/ui_assertions.rb
 - lib/syrma/version.rb
 - lib/syrma/visual/comparator.rb
 - lib/syrma/visual/image.rb
 - lib/syrma/window_driver.rb
 - sig/syrma.rbs
-homepage: https://github.com/ydah/syrma
+homepage: https://github.com/noxdea/syrma
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/ydah/syrma
-  changelog_uri: https://github.com/ydah/syrma/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/noxdea/syrma
+  changelog_uri: https://github.com/noxdea/syrma/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -87,7 +117,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: UI testing toolkit for applications built with Zaniah
 test_files: []