btape 0.1.0 → 0.3.0

data/lib/btape/llm/prompt.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative '../parser'
+require_relative '../settings'
+
+module Btape
+  module LLM
+    # What the model is told before it is asked for a tape.
+    #
+    # The command list and the settings table are built from Parser and
+    # Settings rather than written out again here, so a command added to the
+    # language is a command the model is told about, and a setting cannot be
+    # described to it with a default it no longer has.
+    module Prompt
+      RULES = [
+        'Answer with the contents of a .tape file and nothing else: no explanation, no code fences.',
+        'The script must contain exactly one Output line, naming a .gif file, and it comes first.',
+        'One command per line. Lines starting with # are comments.',
+        'The line is split like a shell command, so any argument containing a space must be quoted ' \
+        'with double quotes.',
+        'Click, WaitFor and Frame take a CSS selector, or text=Some text to match on visible text.',
+        'Durations are a number followed by ms or s, such as 500ms or 1.5s.',
+        'Prefer WaitFor or WaitForJS over Sleep for anything the page has to finish doing; ' \
+        'Sleep is for holding a finished frame on screen long enough to be seen.',
+        'Use only the commands and settings listed above. Do not invent either, ' \
+        'and do not use a shell, a comment or a blank line to stand in for one.'
+      ].freeze
+
+      EXAMPLE = <<~TAPE
+        # Signing in, recorded at half size
+        Output signin.gif
+        Viewport 1280x720
+        Set Scale 0.5
+
+        Goto http://localhost:3000/signin
+        WaitFor "#email"
+        Type "#email" "demo@example.com"
+        Type "#password" "correct horse"
+        Click "text=Sign in"
+        WaitFor "text=Welcome back" 5s
+        Sleep 2s
+      TAPE
+
+      # What a setting takes, as the coercions in Settings enforce it. A
+      # default is shown as a tape would have to write it rather than as
+      # Settings holds it, since `Set FrameDelay 0.1` is not something the
+      # parser would accept back.
+      VALUES = {
+        duration: 'a duration',
+        url: "a #{Settings::URL_SCHEMES.join(', ')} url",
+        count: 'a whole number, 0 or more',
+        positive_integer: 'a whole number, 1 or more',
+        positive_float: 'a number'
+      }.freeze
+
+      module_function
+
+      def system
+        <<~PROMPT
+          You write btape scripts. btape runs a .tape file against Chromium and records
+          the run as an animated GIF, so a tape is a short, deliberate demonstration
+          rather than a test: it moves at a pace somebody can watch.
+
+          The commands, one per line:
+
+          #{indent(commands)}
+
+          A run is configured with `Set NAME VALUE`:
+
+          #{indent(settings)}
+
+          Rules:
+
+          #{indent(RULES.map { |rule| "- #{rule}" }.join("\n"))}
+
+          An example of a whole tape:
+
+          #{indent(EXAMPLE)}
+        PROMPT
+      end
+
+      def user(description, context: nil)
+        return description if context.nil? || context.strip.empty?
+
+        <<~PROMPT
+          #{description}
+
+          Context about the page being recorded — prefer the selectors it names over
+          any you would otherwise guess at:
+
+          #{context}
+        PROMPT
+      end
+
+      # A tape that did not parse goes back with the parser's own complaint,
+      # which names the line and what was wrong with it. Saying so beats
+      # asking again and hoping, since the model can see what it wrote.
+      def repair(reason)
+        <<~PROMPT
+          btape rejected that tape: #{reason}
+
+          Answer with the whole corrected tape, and nothing else.
+        PROMPT
+      end
+
+      def commands
+        Parser::SIGNATURES.map { |name, arguments| "#{name} #{arguments}".strip }.join("\n")
+      end
+
+      def settings
+        Settings::DEFINITIONS.map do |name, (_attribute, coercion, default)|
+          takes = coercion.is_a?(Array) ? coercion.join('|') : VALUES.fetch(coercion)
+          "Set #{name} <#{takes}>#{" — #{literal(coercion, default)} by default" unless default.nil?}"
+        end.join("\n")
+      end
+
+      # A coerced default as a tape would write it: durations are held in
+      # seconds and go back to the ms or s they were read from.
+      def literal(coercion, default)
+        return default.to_s unless coercion == :duration
+        return "#{(default * 1000).round}ms" if default < 1
+
+        "#{default.to_i == default ? default.to_i : default}s"
+      end
+
+      # Blank lines are left alone, so that indenting a block into the prompt
+      # does not leave trailing whitespace through the middle of it.
+      def indent(text)
+        text.strip.gsub(/^(?=.)/, '  ')
+      end
+    end
+  end
+end

data/lib/btape/null_logger.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Btape
+  # Stands in when no logger was given, so the rest of the code can log
+  # unconditionally. Only the three levels btape uses are defined, and any
+  # Logger — Rails' included — can be passed instead.
+  class NullLogger
+    def debug(*); end
+
+    def info(*); end
+
+    def warn(*); end
+  end
+end

data/lib/btape/palette.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require 'chunky_png'
+
+module Btape
+  # The 256 colours a GIF frame is written in, and the mapping from a pixel to
+  # one of them.
+  #
+  # Fixed spreads its colours evenly across the whole RGB cube regardless of
+  # what is being encoded, which costs nothing to build but wastes most of the
+  # palette on colours the image does not contain. Adaptive chooses the
+  # colours from the image itself, which is what keeps text edges and
+  # gradients from banding.
+  module Palette
+    SIZE = 256
+    # Colours are bucketed to five bits per channel before anything looks at
+    # them. It collapses a screenshot's million pixels into a few thousand
+    # distinct entries, and the error it introduces is below what the 256
+    # colours of a GIF can express anyway.
+    LEVELS = 32
+    CELLS = LEVELS**3
+
+    module_function
+
+    def build(quantizer, images)
+      quantizer.to_sym == :adaptive ? Adaptive.from(images) : Fixed.new
+    end
+
+    def cell(pixel)
+      ((ChunkyPNG::Color.r(pixel) >> 3) << 10) |
+        ((ChunkyPNG::Color.g(pixel) >> 3) << 5) |
+        (ChunkyPNG::Color.b(pixel) >> 3)
+    end
+
+    def rgb(cell)
+      [((cell >> 10) & 31) * 255 / 31, ((cell >> 5) & 31) * 255 / 31, (cell & 31) * 255 / 31]
+    end
+
+    # Pads a list of colours out to a full global colour table.
+    def colour_table(colours)
+      colours.map { |colour| colour.pack('C3') }.join.b.ljust(SIZE * 3, "\x00".b)
+    end
+
+    # Three bits of red, three of green, two of blue. Cheap, and independent
+    # of the image, but only eight distinct levels of red to spend on a
+    # gradient that may need far more.
+    class Fixed
+      def index_for(pixel)
+        (ChunkyPNG::Color.r(pixel) & 0xe0) |
+          ((ChunkyPNG::Color.g(pixel) & 0xe0) >> 3) |
+          (ChunkyPNG::Color.b(pixel) >> 6)
+      end
+
+      def to_gct
+        Palette.colour_table(
+          (0...SIZE).map { |i| [((i >> 5) & 7) * 255 / 7, ((i >> 2) & 7) * 255 / 7, (i & 3) * 255 / 3] }
+        )
+      end
+    end
+
+    # Colours chosen from the frames themselves by median cut.
+    class Adaptive
+      # Enough of each frame to describe what colours it uses. Reading every
+      # pixel of every frame would cost far more and change the answer very
+      # little.
+      MAX_SAMPLES_PER_IMAGE = 60_000
+
+      def self.from(images)
+        new(histogram(images))
+      end
+
+      def self.histogram(images)
+        counts = Hash.new(0)
+        images.each do |image|
+          pixels = image.pixels
+          stride = [pixels.length / MAX_SAMPLES_PER_IMAGE, 1].max
+          index = 0
+          while index < pixels.length
+            counts[Palette.cell(pixels[index])] += 1
+            index += stride
+          end
+        end
+        counts
+      end
+
+      def initialize(histogram)
+        @colours = MedianCut.new(histogram).colours
+        # One entry per five-bit colour cell, filled in as cells are met. A
+        # screenshot touches a small fraction of them, so searching the
+        # palette for the rest would be work thrown away.
+        @lookup = Array.new(CELLS)
+      end
+
+      attr_reader :colours
+
+      def index_for(pixel)
+        cell = Palette.cell(pixel)
+        @lookup[cell] || (@lookup[cell] = nearest(cell))
+      end
+
+      def to_gct
+        Palette.colour_table(@colours)
+      end
+
+      private
+
+      def nearest(cell)
+        red, green, blue = Palette.rgb(cell)
+        best = 0
+        shortest = nil
+        @colours.each_with_index do |(r, g, b), index|
+          distance = ((red - r)**2) + ((green - g)**2) + ((blue - b)**2)
+          next unless shortest.nil? || distance < shortest
+
+          shortest = distance
+          best = index
+        end
+        best
+      end
+    end
+
+    # Repeatedly splits the colours in use along their widest axis, so that
+    # each of the 256 boxes it ends up with holds a similar share of the
+    # pixels. Colours a frame leans on get more of the palette than colours it
+    # barely touches.
+    class MedianCut
+      # Colours in a box, as [red, green, blue, weight] entries. The stats a
+      # split needs are worked out once per box: they are read every round,
+      # and the box they describe never changes.
+      class Box
+        def initialize(entries)
+          @entries = entries
+          @bounds = compute_bounds
+          @axis = (0..2).max_by { |channel| @bounds[channel].last - @bounds[channel].first }
+          @weight = entries.sum(&:last)
+        end
+
+        attr_reader :entries, :axis, :weight
+
+        def splittable?
+          @entries.length > 1
+        end
+
+        # Both how far the box spreads and how many pixels are in it: a wide
+        # box nothing is using does not deserve the palette entry.
+        def priority
+          (@bounds[@axis].last - @bounds[@axis].first) * @weight
+        end
+
+        def split
+          sorted = @entries.sort_by { |entry| entry[@axis] }
+          [Box.new(sorted.shift(median_index(sorted))), Box.new(sorted)]
+        end
+
+        def colour
+          (0..2).map { |channel| @entries.sum { |entry| entry[channel] * entry.last } / @weight }
+        end
+
+        private
+
+        def compute_bounds
+          (0..2).map { |channel| @entries.map { |entry| entry[channel] }.minmax }
+        end
+
+        # Splits where half the weight lies, leaving at least one entry each
+        # side however lopsided the weights are.
+        def median_index(sorted)
+          half = @weight / 2.0
+          running = 0
+          taken = sorted.take_while do |entry|
+            running += entry.last
+            running < half
+          end.length
+          taken.clamp(1, sorted.length - 1)
+        end
+      end
+
+      def initialize(histogram, size: SIZE)
+        @entries = histogram.map { |cell, weight| Palette.rgb(cell) << weight }
+        @size = size
+      end
+
+      def colours
+        return [[0, 0, 0]] if @entries.empty?
+
+        boxes = [Box.new(@entries)]
+        while boxes.length < @size
+          index = widest(boxes)
+          break unless index
+
+          boxes[index, 1] = boxes[index].split
+        end
+        boxes.map(&:colour)
+      end
+
+      private
+
+      def widest(boxes)
+        boxes.each_index.select { |index| boxes[index].splittable? }.max_by { |index| boxes[index].priority }
+      end
+    end
+  end
+end

data/lib/btape/parser.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require 'shellwords'
+require_relative 'duration'
+require_relative 'recorder'
+require_relative 'settings'
 
 module Btape
   Command = Struct.new(:name, :arguments, :line_number, keyword_init: true)
@@ -8,7 +11,24 @@ module Btape
   # 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
+    # An arity is either an exact count or a range, for commands whose last
+    # argument is optional.
+    ARITY = {
+      'Output' => 1, 'Viewport' => 1, 'Goto' => 1, 'Click' => 1, 'Type' => 2, 'Sleep' => 1,
+      'Set' => 2, 'Screenshot' => 0..1, 'Evaluate' => 1, 'WaitFor' => 1..2, 'WaitForJS' => 1..2,
+      'Frame' => 1, 'Press' => 1..2
+    }.freeze
+
+    # The same commands as they read to somebody being told about them, which
+    # is what `btape help` prints and what a model is handed before it is
+    # asked for a tape. ARITY is what a script is held to; a spec keeps the
+    # two lists from drifting apart.
+    SIGNATURES = {
+      'Output' => 'PATH', 'Viewport' => 'WIDTHxHEIGHT', 'Goto' => 'URL', 'Click' => 'SELECTOR',
+      'Type' => 'SELECTOR TEXT', 'Press' => 'KEY [COUNT]', 'Frame' => 'SELECTOR|main',
+      'Evaluate' => 'JAVASCRIPT', 'WaitFor' => 'SELECTOR [TIMEOUT]', 'WaitForJS' => 'JAVASCRIPT [TIMEOUT]',
+      'Screenshot' => '[NAME]', 'Sleep' => 'DURATION', 'Set' => 'NAME VALUE'
+    }.freeze
 
     def parse(source)
       source.each_line.with_index(1).filter_map do |line, number|
@@ -29,7 +49,7 @@ module Btape
       raise ScriptError.new(number, "unknown command #{name.inspect}") unless ARITY.key?(name)
 
       arity = ARITY.fetch(name)
-      unless words.length == arity
+      unless arity === words.length # rubocop:disable Style/CaseEquality
         raise ScriptError.new(number, "#{name} expects #{arity} argument(s), got #{words.length}")
       end
 
@@ -41,9 +61,35 @@ module Btape
       case name
       when 'Viewport' then validate_viewport(arguments.first, number)
       when 'Sleep' then validate_sleep(arguments.first, number)
+      when 'Set' then Settings.validate!(*arguments)
+      when 'Screenshot' then validate_frame_name(arguments.first, number)
+      when 'WaitFor', 'WaitForJS' then validate_wait_timeout(name, arguments, number)
+      when 'Press' then validate_press_count(arguments[1], number)
       end
     end
 
+    def validate_press_count(value, number)
+      return if value.nil? || (/\A\d+\z/.match?(value) && value.to_i.positive?)
+
+      raise ScriptError.new(number, 'Press count must be a positive integer')
+    end
+
+    def validate_wait_timeout(name, arguments, number)
+      timeout = arguments[1]
+      return if timeout.nil? || Duration.valid?(timeout)
+
+      raise ScriptError.new(number, "#{name} timeout #{Duration::DESCRIPTION}")
+    end
+
+    # The name becomes part of a filename, so keep it to something that
+    # cannot escape the frames directory. Recorder rejects the same names, but
+    # catching it here names the line the script has to fix.
+    def validate_frame_name(value, number)
+      return if value.nil? || Recorder::FRAME_NAME.match?(value)
+
+      raise ScriptError.new(number, 'Screenshot name must be letters, numbers, dashes, dots or underscores')
+    end
+
     def validate_viewport(value, number)
       match = /\A(\d+)x(\d+)\z/.match(value)
       valid = match&.captures&.all? { |part| part.to_i.positive? }
@@ -51,9 +97,9 @@ module Btape
     end
 
     def validate_sleep(value, number)
-      return if /\A(\d+(?:\.\d+)?)(ms|s)\z/.match?(value)
+      return if Duration.valid?(value)
 
-      raise ScriptError.new(number, 'Sleep duration must use ms or s (for example, 500ms or 1.5s)')
+      raise ScriptError.new(number, "Sleep duration #{Duration::DESCRIPTION}")
     end
   end
 end

data/lib/btape/recorder.rb

@@ -1,20 +1,41 @@
 # frozen_string_literal: true
 
+require 'monitor'
+
 module Btape
-  # Captures periodic screenshots of a page on a background thread until
-  # stopped, building the frame sequence GifEncoder turns into a GIF.
+  # Captures the frames a GIF is built from.
+  #
+  # In :interval mode it screenshots the page on a background thread until
+  # stopped. In :manual mode it captures only when the script asks with a
+  # Screenshot command, which is what a tape wants when it needs one frame per
+  # page rather than a few hundred near-identical ones.
   class Recorder
-    def initialize(page, directory, interval: 0.1)
+    # A name becomes part of a filename, so it may not carry anything that
+    # would put the frame somewhere other than the frames directory. Parser
+    # checks it too, to report a bad Screenshot line with its line number;
+    # this is the check for everyone else, since capture is public API.
+    FRAME_NAME = /\A[\w.-]+\z/
+
+    def initialize(page, directory, interval: 0.1, mode: :interval, on_frame: nil, max_frames: nil,
+                   lock: Monitor.new)
       @page = page
       @directory = directory
       @interval = interval
+      @mode = mode.to_sym
+      @on_frame = on_frame
+      @max_frames = max_frames
+      # Shared with the executor, so a screenshot and a command are never in
+      # flight against the same page at once.
+      @lock = lock
       @paths = []
-      @mutex = Mutex.new
+      @named_paths = {}
     end
 
-    attr_reader :paths
+    attr_reader :paths, :named_paths
 
     def start
+      return if manual?
+
       capture
       @running = true
       @thread = Thread.new do
@@ -37,14 +58,46 @@ module Btape
       raise @error if @error
     end
 
-    private
+    # Captures one frame now. A name puts it at a predictable path, so a
+    # caller can pick a particular frame out of the run.
+    def capture(name: nil)
+      validate_name!(name)
+      path, index = @lock.synchronize do
+        exhausted! if @max_frames && @paths.length >= @max_frames
 
-    def capture
-      @mutex.synchronize do
-        path = File.join(@directory, format('frame-%06d.png', @paths.length))
+        path = File.join(@directory, filename(name))
         screenshot(path)
+        index = @paths.length
         @paths << path
+        @named_paths[name] = path if name
+        [path, index]
       end
+      # Outside the lock: the callback is the caller's code and may take as
+      # long as it likes without holding up the next capture.
+      @on_frame&.call(path, index)
+      path
+    end
+
+    private
+
+    # A page that hangs would otherwise be screenshotted until the disk ran
+    # out, which on a shared host takes more than this run down with it.
+    def exhausted!
+      raise Error, "stopped after #{@max_frames} frames; raise Set MaxFrames to record for longer"
+    end
+
+    def manual?
+      @mode == :manual
+    end
+
+    def validate_name!(name)
+      return if name.nil? || FRAME_NAME.match?(name)
+
+      raise Error, "frame name must be letters, numbers, dashes, dots or underscores: #{name.inspect}"
+    end
+
+    def filename(name)
+      name ? "frame-#{name}.png" : format('frame-%06d.png', @paths.length)
     end
 
     def screenshot(path)

data/lib/btape/result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Btape
+  # What a run produced. `output_path` is where the GIF was written, or nil
+  # when the caller passed an IO for it to be written into instead.
+  #
+  # Callers that want the frames themselves (to attach a still somewhere, say)
+  # pass `frames_directory:` to Runner#run and read `frame_paths`.
+  #
+  # Without a `frames_directory:` the frames live in a temporary directory
+  # that is removed as the run unwinds, so `frame_paths` and `named_frames`
+  # are empty rather than lists of paths that no longer exist. `frame_count`
+  # is always the number of frames that went into the GIF.
+  #
+  # `named_frames` maps the name a `Screenshot NAME` command gave a frame to
+  # its path, for picking one particular frame out of a run.
+  Result = Struct.new(:output_path, :frame_paths, :named_frames, :frame_count, :width, :height, keyword_init: true)
+end