btape 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83f37a580ea032f35ec04083a301339d43bb35bd13881799774d275527558e43
+  data.tar.gz: 6b47a03f994310102fc3534c621d7fe78e782e6ab39653a6c227b56838ba17c0
+SHA512:
+  metadata.gz: 493ebb303b92ba896387e67236c61deaf5cfaed5ba746990e67c9be9ad06d88d1ea34985d3719a87b6edfbbafe06c59b8d052720b05471fc1215589db23da43d
+  data.tar.gz: b5cf6dcfc0995a623f080f30bd5903dc8fed6f456d42f697534a720494d7c8418bcfdeb3917cb0c4537120216382578456642671b849d07b2365c486e9f0a329

data/LICENSE

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

data/README.md

@@ -0,0 +1,70 @@
+# btape
+
+`btape` is a small, VHS-inspired Ruby CLI that runs browser actions from a
+`.tape` file and records them as an animated GIF. Ferrum controls Chromium
+and captures PNG frames, and a pure-Ruby encoder produces the GIF. It
+does not require Playwright, Selenium, ffmpeg, or an external service.
+
+## Commands
+
+```text
+Output <path>
+Viewport <width>x<height>
+Goto <url>
+Click <CSS selector or text=Text>
+Type <CSS selector> <text>
+Sleep <number>ms|s
+```
+
+Arguments containing spaces must be quoted. Empty lines and lines beginning
+with `#` are ignored. `Output` is required; `Viewport` defaults to `1280x720`.
+Output paths are resolved relative to the tape file.
+
+```text
+Output demo.gif
+Viewport 1280x720
+Goto http://localhost:3000
+Click "text=Login"
+Type "#email" "demo@example.com"
+Sleep 1s
+```
+
+## Install and run
+
+Chromium must be installed and discoverable by Ferrum. Then:
+
+```sh
+bundle install
+bundle exec btape demo.tape
+bundle exec rake spec
+```
+
+The recording interval is 100 ms (10 fps). Temporary PNG frames are removed
+after a successful run. They are also isolated in the system temporary
+directory and cleaned when an error unwinds the run.
+
+## Container development with dip or wip
+
+The development image contains Ruby and Chromium.
+
+```sh
+dip provision
+dip test
+dip demo
+
+wip up
+wip dispatch demo
+wip dispatch btape examples/demo.tape
+```
+
+`examples/demo.tape` drives a small static page bundled at
+`examples/demo_app.html`, so the demo is self-contained and needs no other
+service running. Edit the tape (or point `Goto` at a different URL) to record
+something else.
+
+## MVP limitations
+
+The GIF encoder uses a fixed 256-colour RGB332 palette to stay dependency-light.
+This favors portability over photographic colour fidelity and file size. The
+first matching element is used for `Click` and `Type`.
+

data/exe/btape

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'btape'
+
+exit Btape::CLI.new.run(ARGV)

data/lib/btape/cli.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Btape
+  # Entry point invoked by the `btape` executable: parses argv, runs the
+  # script, and reports success or failure.
+  class CLI
+    def initialize(out: $stdout, err: $stderr, runner: Runner.new)
+      @out = out
+      @err = err
+      @runner = runner
+    end
+
+    HELP_COMMANDS = ['Output PATH', 'Viewport WIDTHxHEIGHT', 'Goto URL', 'Click SELECTOR',
+                     'Type SELECTOR TEXT', 'Sleep DURATION'].freeze
+
+    def run(argv)
+      return print_help if argv.empty? || %w[help -h --help].include?(argv.first)
+      raise Error, 'usage: btape SCRIPT.tape' unless argv.length == 1
+
+      script = File.expand_path(argv.first)
+      commands = Parser.new.parse(File.read(script))
+      output = @runner.run(commands, base_directory: File.dirname(script))
+      @out.puts "Created #{output}"
+      0
+    rescue Error, SystemCallError => e
+      @err.puts "btape: #{e.message}"
+      1
+    end
+
+    private
+
+    def print_help
+      @out.puts 'Usage: btape SCRIPT.tape'
+      @out.puts
+      @out.puts 'Commands:'
+      HELP_COMMANDS.each { |command| @out.puts "  #{command}" }
+      0
+    end
+  end
+end

data/lib/btape/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Btape
+  class Error < StandardError; end
+
+  # Raised for a problem in the .tape script itself, carrying the line
+  # number so the CLI can report where the script went wrong.
+  class ScriptError < Error
+    attr_reader :line_number
+
+    def initialize(line_number, message)
+      @line_number = line_number
+      super("line #{line_number}: #{message}")
+    end
+  end
+end

data/lib/btape/gif_encoder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'chunky_png'
+require_relative 'lzw_compressor'
+
+module Btape
+  # A deliberately small GIF89a encoder. RGB332 gives a fixed 256-colour palette,
+  # avoiding a native image or video dependency.
+  class GifEncoder
+    def initialize(delay: 10)
+      @delay = delay
+      @compressor = LzwCompressor.new
+    end
+
+    def write(png_paths, output)
+      raise Error, 'no screenshots were captured' if png_paths.empty?
+
+      images = png_paths.map { |path| ChunkyPNG::Image.from_file(path) }
+      width, height = images.first.dimension.to_a
+      raise Error, 'captured screenshots have different dimensions' unless images.all? do |image|
+        image.dimension.to_a == [width, height]
+      end
+
+      File.binwrite(output, gif(images, width, height))
+    end
+
+    private
+
+    def gif(images, width, height)
+      data = +'GIF89a'.b
+      data << [width, height, 0b11110111, 0, 0].pack('vvCCC') << palette
+      data << "!\xFF\x0BNETSCAPE2.0\x03\x01\x00\x00\x00".b
+      images.each { |image| write_frame(data, image, width, height) }
+      data << ';'.b
+    end
+
+    def write_frame(data, image, width, height)
+      data << "!\xF9\x04\x00".b << [@delay].pack('v') << "\x00\x00".b
+      data << ','.b << [0, 0, width, height, 0].pack('vvvvC')
+      compressed = lzw(image)
+      data << "\x08".b
+      compressed.bytes.each_slice(255) { |slice| data << slice.length.chr << slice.pack('C*') }
+      data << "\x00".b
+    end
+
+    def palette
+      (0..255).map { |i| [((i >> 5) & 7) * 255 / 7, ((i >> 2) & 7) * 255 / 7, (i & 3) * 255 / 3].pack('C3') }.join.b
+    end
+
+    def lzw(image)
+      pixels = image.pixels.map { |pixel| rgb332(pixel) }
+      codes = []
+      @compressor.call(pixels) { |code, width| codes << [code, width] }
+      pack_codes(codes)
+    end
+
+    def rgb332(pixel)
+      (ChunkyPNG::Color.r(pixel) & 0xe0) | ((ChunkyPNG::Color.g(pixel) & 0xe0) >> 3) | (ChunkyPNG::Color.b(pixel) >> 6)
+    end
+
+    def pack_codes(codes)
+      buffer = 0
+      count = 0
+      output = +''.b
+      codes.each do |code, bits|
+        buffer |= code << count
+        count += bits
+        while count >= 8
+          output << (buffer & 0xff).chr
+          buffer >>= 8
+          count -= 8
+        end
+      end
+      output << (buffer & 0xff).chr if count.positive?
+      output
+    end
+  end
+end

data/lib/btape/lzw_compressor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Btape
+  class GifEncoder
+    # Variable-width LZW compression of a flat array of palette indices,
+    # producing (code, width) pairs ready for bit-packing into a GIF stream.
+    class LzwCompressor
+      CLEAR_CODE = 256
+      FINISH_CODE = 257
+      MAX_CODE_WIDTH = 12
+      MAX_DICTIONARY_SIZE = 1 << MAX_CODE_WIDTH
+
+      # Mutable state threaded through compress/advance: the growing code
+      # dictionary, the next free code, the current code width in bits, and
+      # whether a width bump is owed (see #advance).
+      State = Struct.new(:dictionary, :next_code, :code_width, :pending_width_bump)
+
+      def call(pixels, &emit)
+        emit.call(CLEAR_CODE, 9)
+        return emit.call(FINISH_CODE, 9) if pixels.empty?
+
+        compress(pixels, emit)
+      end
+
+      private
+
+      def compress(pixels, emit)
+        state = State.new(root_dictionary, FINISH_CODE + 1, 9, false)
+        current_code = pixels.first
+
+        pixels.drop(1).each do |pixel|
+          key = ((current_code + 1) << 8) | pixel
+          if state.dictionary.key?(key)
+            current_code = state.dictionary[key]
+            next
+          end
+
+          emit.call(current_code, state.code_width)
+          advance(state, key, emit)
+          current_code = pixel
+        end
+
+        emit.call(current_code, state.code_width)
+        emit.call(FINISH_CODE, state.code_width)
+      end
+
+      # A GIF decoder cannot add its own dictionary entry until it has seen two
+      # codes (it has nothing to extend after just the first), so its
+      # code-width bump for a given dictionary slot always lands one code later
+      # than the encoder's. Deferring the bump by one entry here keeps the two
+      # in lockstep.
+      def advance(state, key, emit)
+        if state.next_code == MAX_DICTIONARY_SIZE
+          emit.call(CLEAR_CODE, state.code_width)
+          return reset!(state)
+        end
+
+        state.dictionary[key] = state.next_code
+        state.next_code += 1
+        if state.pending_width_bump
+          state.code_width += 1 if state.code_width < MAX_CODE_WIDTH
+          state.pending_width_bump = false
+        end
+        state.pending_width_bump = true if state.next_code > (1 << state.code_width) - 1
+      end
+
+      def reset!(state)
+        state.dictionary = root_dictionary
+        state.next_code = FINISH_CODE + 1
+        state.code_width = 9
+        state.pending_width_bump = false
+      end
+
+      def root_dictionary
+        (0..255).to_h { |value| [value, value] }
+      end
+    end
+  end
+end

data/lib/btape/parser.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'shellwords'
+
+module Btape
+  Command = Struct.new(:name, :arguments, :line_number, keyword_init: true)
+
+  # Parses .tape scripts into a list of Command structs, raising ScriptError
+  # for unknown commands, wrong argument counts, or invalid argument values.
+  class Parser
+    ARITY = { 'Output' => 1, 'Viewport' => 1, 'Goto' => 1, 'Click' => 1, 'Type' => 2, 'Sleep' => 1 }.freeze
+
+    def parse(source)
+      source.each_line.with_index(1).filter_map do |line, number|
+        text = line.strip
+        next if text.empty? || text.start_with?('#')
+
+        parse_line(text, number)
+      rescue ArgumentError => e
+        raise ScriptError.new(number, e.message)
+      end
+    end
+
+    private
+
+    def parse_line(text, number)
+      words = Shellwords.shellsplit(text)
+      name = words.shift
+      raise ScriptError.new(number, "unknown command #{name.inspect}") unless ARITY.key?(name)
+
+      arity = ARITY.fetch(name)
+      unless words.length == arity
+        raise ScriptError.new(number, "#{name} expects #{arity} argument(s), got #{words.length}")
+      end
+
+      validate(name, words, number)
+      Command.new(name:, arguments: words.freeze, line_number: number)
+    end
+
+    def validate(name, arguments, number)
+      case name
+      when 'Viewport' then validate_viewport(arguments.first, number)
+      when 'Sleep' then validate_sleep(arguments.first, number)
+      end
+    end
+
+    def validate_viewport(value, number)
+      match = /\A(\d+)x(\d+)\z/.match(value)
+      valid = match&.captures&.all? { |part| part.to_i.positive? }
+      raise ScriptError.new(number, 'Viewport must be WIDTHxHEIGHT') unless valid
+    end
+
+    def validate_sleep(value, number)
+      return if /\A(\d+(?:\.\d+)?)(ms|s)\z/.match?(value)
+
+      raise ScriptError.new(number, 'Sleep duration must use ms or s (for example, 500ms or 1.5s)')
+    end
+  end
+end

data/lib/btape/recorder.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Btape
+  # Captures periodic screenshots of a page on a background thread until
+  # stopped, building the frame sequence GifEncoder turns into a GIF.
+  class Recorder
+    def initialize(page, directory, interval: 0.1)
+      @page = page
+      @directory = directory
+      @interval = interval
+      @paths = []
+      @mutex = Mutex.new
+    end
+
+    attr_reader :paths
+
+    def start
+      capture
+      @running = true
+      @thread = Thread.new do
+        loop do
+          sleep @interval
+          capture
+        end
+      rescue StandardError => e
+        @error = e
+      end
+    end
+
+    def stop
+      return unless @running
+
+      @running = false
+      @thread&.kill
+      @thread&.join
+      capture
+      raise @error if @error
+    end
+
+    private
+
+    def capture
+      @mutex.synchronize do
+        path = File.join(@directory, format('frame-%06d.png', @paths.length))
+        screenshot(path)
+        @paths << path
+      end
+    end
+
+    def screenshot(path)
+      @page.screenshot(path: path)
+    end
+  end
+end

data/lib/btape/runner.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'ferrum'
+require 'tmpdir'
+
+module Btape
+  # Drives a headless browser through the parsed commands and captures a
+  # screenshot per step, handing the frames off to GifEncoder.
+  class Runner
+    DEFAULT_VIEWPORT = [1280, 720].freeze
+
+    def initialize(browser_factory: lambda { |options|
+      Ferrum::Browser.new(**options)
+    }, recorder_class: Recorder, gif_encoder: GifEncoder.new)
+      @browser_factory = browser_factory
+      @recorder_class = recorder_class
+      @gif_encoder = gif_encoder
+    end
+
+    def run(commands, base_directory: Dir.pwd)
+      output_path = resolve_output_path(commands, base_directory)
+      width, height = resolve_viewport(commands)
+
+      Dir.mktmpdir('btape-') { |directory| record(commands, directory, width, height, output_path) }
+      output_path
+    end
+
+    private
+
+    def resolve_output_path(commands, base_directory)
+      output = commands.find { |command| command.name == 'Output' }&.arguments&.first
+      raise Error, 'script must contain an Output command' unless output
+
+      path = File.expand_path(output, base_directory)
+      FileUtils.mkdir_p(File.dirname(path))
+      path
+    end
+
+    def resolve_viewport(commands)
+      viewport = commands.find { |command| command.name == 'Viewport' }&.arguments&.first
+      viewport ? viewport.split('x').map(&:to_i) : DEFAULT_VIEWPORT
+    end
+
+    def record(commands, directory, width, height, output_path)
+      browser = nil
+      recorder = nil
+      begin
+        browser = @browser_factory.call(window_size: [width, height])
+        recorder = @recorder_class.new(browser, directory)
+        recorder.start
+        execute(commands, browser)
+        recorder.stop
+        @gif_encoder.write(recorder.paths, output_path)
+      ensure
+        begin
+          recorder&.stop
+        rescue StandardError
+          nil
+        end
+        browser&.quit
+      end
+    end
+
+    def execute(commands, browser)
+      commands.each do |command|
+        perform(command, browser)
+      rescue StandardError => e
+        raise ScriptError.new(command.line_number, "#{command.name} failed: #{e.message}")
+      end
+    end
+
+    def perform(command, browser)
+      case command.name
+      when 'Output', 'Viewport' then nil
+      when 'Goto' then browser.go_to(command.arguments.first)
+      when 'Click' then find(browser, command.arguments.first).click
+      when 'Type' then type(browser, command.arguments)
+      when 'Sleep' then sleep_seconds(command.arguments.first)
+      end
+    end
+
+    def type(browser, arguments)
+      element = find(browser, arguments.first)
+      element.focus
+      element.type(arguments.last)
+    end
+
+    def find(browser, selector)
+      element = if selector.start_with?('text=')
+                  literal = xpath_literal(selector.delete_prefix('text='))
+                  browser.at_xpath("//*[normalize-space(text())=#{literal}]")
+                else
+                  browser.at_css(selector)
+                end
+      element || raise("element not found: #{selector}")
+    end
+
+    def xpath_literal(text)
+      return %("#{text}") unless text.include?('"')
+
+      parts = text.split('"', -1).map { |part| %("#{part}") }
+      "concat(#{parts.join(%q(, '"', ))})"
+    end
+
+    def sleep_seconds(duration)
+      value, unit = duration.match(/\A(\d+(?:\.\d+)?)(ms|s)\z/).captures
+      sleep(value.to_f / (unit == 'ms' ? 1000 : 1))
+    end
+  end
+end

data/lib/btape/version.rb

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

data/lib/btape.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'btape/version'
+require_relative 'btape/error'
+require_relative 'btape/parser'
+require_relative 'btape/gif_encoder'
+require_relative 'btape/recorder'
+require_relative 'btape/runner'
+require_relative 'btape/cli'

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: btape
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- btape contributors
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chunky_png
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+description: A small VHS-inspired browser recorder driven by .tape files.
+executables:
+- btape
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/btape
+- lib/btape.rb
+- lib/btape/cli.rb
+- lib/btape/error.rb
+- lib/btape/gif_encoder.rb
+- lib/btape/lzw_compressor.rb
+- lib/btape/parser.rb
+- lib/btape/recorder.rb
+- lib/btape/runner.rb
+- lib/btape/version.rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Record browser automation scripts as animated GIFs
+test_files: []