trmnl_preview 0.15.0 → 0.16.0

data/lib/trmnlp/poller.rb

@@ -1,22 +1,34 @@
 # frozen_string_literal: true
 
 require 'active_support/core_ext/hash/conversions'
-require 'faraday'
+require 'csv'
 require 'json'
 
+require_relative 'outbound_request'
 require_relative 'reporter'
 
 module TRMNLP
   class Poller
-    def initialize(config:, paths:, oauth_session:, reporter: Reporter.new)
+    BYTE_ORDER_MARK = "\xEF\xBB\xBF".b
+
+    # trmnl_variables answers the trmnl namespace TRMNL renders polling urls, headers and bodies with.
+    # rubocop:disable-next Metrics/ParameterLists -- keyword collaborators Context wires once
+    def initialize(config:, paths:, oauth_session:, trmnl_variables: -> { {} }, reporter: Reporter.new,
+                   async_callback: nil)
       @config = config
       @paths = paths
       @oauth_session = oauth_session
+      @trmnl_variables = trmnl_variables
       @reporter = reporter
+      @async_callback = async_callback
     end
 
     def poll_data
+      return request_async_data if config.plugin.async_polling?
       return unless config.plugin.polling?
+
+      missing = config.plugin.missing_required_fields
+      return report_warning("Plugin is not configured — fill in: #{missing.join(', ')}") if missing.any?
       raise InvalidConfig, 'config must specify polling_url or polling_urls' if config.plugin.polling_urls.empty?
 
       data = aggregate_responses
@@ -26,27 +38,42 @@ module TRMNLP
     # and keep the preview server alive, not crash the user's session. We
     # deliberately swallow here and return {} so the renderer keeps rendering.
     rescue StandardError => e
-      reporter.info(reporter.yellow("warning: #{e.message}"))
+      report_warning(e.message)
       {}
     end
 
-    def put_webhook(payload)
-      write_user_data(wrap_array(JSON.parse(payload)))
-    # NOTE: Same rationale as #poll_data — a bad webhook payload shouldn't take
-    # down the dev server. Report a warning and keep serving.
-    rescue StandardError => e
-      reporter.info(reporter.yellow("webhook warning: #{e.message}"))
-    end
-
     private
 
-    attr_reader :config, :paths, :oauth_session, :reporter
+    attr_reader :config, :paths, :oauth_session, :trmnl_variables, :reporter, :async_callback
+
+    # Like TRMNL: the API answers 202 and posts the data to callback_url later; the last post renders meanwhile.
+    def request_async_data
+      unless async_callback&.server_url
+        return report_warning('async_polling needs `trmnlp serve` to receive the callback')
+      end
+      return report_warning('Waiting for the async callback; the last data posted renders') if async_callback.awaiting?
+      raise InvalidConfig, 'config must specify polling_url' if config.plugin.polling_urls.empty?
+
+      report_warning('Async callback not received within 15 minutes') if async_callback.expired?
+      response, url = send_async_request(async_callback.start)
+      return if response&.status == 202
+
+      async_callback.cancel
+      report_warning("Async polling failed: HTTP #{response.status} from #{without_query(url)}") if response
+    end
+
+    def send_async_request(callback_url)
+      variables = trmnl_variables.call.merge(oauth_session.liquid_variables)
+      url = config.plugin.polling_urls(extra_variables: variables.merge('callback_url' => callback_url)).first
+      headers = config.plugin.polling_headers(extra_variables: variables)
+      [fetch_one(url, headers, config.plugin.polling_body(extra_variables: variables)), url]
+    end
 
     def aggregate_responses
       fetched = fetch_all
       # Like the hosted service: a token rejected before its expiry gets one refresh and retry.
-      fetched = fetch_all if fetched.any? { |_url, response| response.status == 401 } && oauth_session.force_refresh!
-      responses = fetched.map { |url, response| parse_response(response, url) }
+      fetched = fetch_all if fetched.any? { |_url, response| response&.status == 401 } && oauth_session.force_refresh!
+      responses = fetched.map { |url, response| response ? parse_response(response, url) : {} }
       return responses.first if responses.size == 1
 
       responses.each_with_index.with_object({}) { |(r, i), h| h["IDX_#{i}"] = r }
@@ -55,62 +82,74 @@ module TRMNLP
     def fetch_all
       # Resolve once per attempt (it refreshes as a side effect), then share across
       # every URL, header, and body render.
-      oauth_variables = oauth_session.liquid_variables
-      urls = config.plugin.polling_urls(extra_variables: oauth_variables)
-      urls.map { |url| [url, fetch_one(url, oauth_variables)] }
+      variables = trmnl_variables.call.merge(oauth_session.liquid_variables)
+      headers = config.plugin.polling_headers(extra_variables: variables)
+      body = config.plugin.polling_body(extra_variables: variables)
+      config.plugin.polling_urls(extra_variables: variables).map { |url| [url, fetch_one(url, headers, body)] }
     end
 
-    def fetch_one(url, oauth_variables)
+    def fetch_one(url, headers, body)
       verb = config.plugin.polling_verb.upcase
-      response = perform_request(url, verb, oauth_variables)
-      reporter.info("#{verb} #{url} — received #{response.body.length} bytes (#{response.status} status)")
+      response, failure = outbound_request.call(verb, url, headers:, body:)
+      return report_warning("Unable to fetch data from url: #{without_query(url)} — #{failure}") if failure
+
+      size = response.body.length
+      reporter.info("#{verb} #{without_query(url)} — received #{size} bytes (#{response.status} status)")
       response
     end
 
-    def perform_request(url, verb, oauth_variables)
-      conn = Faraday.new(url:, headers: config.plugin.polling_headers(extra_variables: oauth_variables))
-      if verb == 'POST'
-        conn.post { |req| req.body = config.plugin.polling_body(extra_variables: oauth_variables) }
-      else
-        conn.get
-      end
+    def outbound_request
+      OutboundRequest.new(on_private_address: lambda { |url|
+        report_warning("TRMNL refuses #{without_query(url)}: the url resolves to a private address")
+      })
     end
 
-    # Like the hosted service: an error status is reported, but its body still reaches the data.
+    # Like the hosted service: a client error is reported, but its body still reaches the data.
     def parse_response(response, url)
       success = (200..299).cover?(response.status)
       reporter.info(reporter.yellow("warning: HTTP #{response.status} from #{url}")) unless success
-      parse_body(response.body, response.headers['content-type'])
+      parse_body(without_byte_order_mark(response.body.to_s), response.headers['content-type'])
+    rescue JSON::ParserError, CSV::MalformedCSVError => e
+      report_warning("Malformed #{e.is_a?(CSV::MalformedCSVError) ? 'CSV' : 'JSON'} from url: #{url}")
+      {}
     end
 
+    # Unlisted and missing content types are read as JSON, as TRMNL does.
     def parse_body(body, content_type_header)
-      content_type = content_type_header&.split(';')&.first&.strip
-      case content_type
-      when 'application/json', %r{^application/.+\+json} then wrap_array(JSON.parse(body))
+      case content_type_header&.split(';')&.first&.strip
       when 'text/xml', 'application/xml', %r{^application/.+\+xml} then wrap_array(Hash.from_xml(body))
-      when 'text/html', 'text/plain' then sniff_json(body) || { 'data' => body }
-      else log_unknown_type(content_type_header)
+      when 'text/csv' then wrap_array(CSV.parse(body))
+      when 'text/plain', 'text/html', 'text/markdown', 'text/x-markdown' then parse_textual_body(body)
+      else wrap_array(JSON.parse(body))
       end
     end
 
-    def log_unknown_type(header)
-      reporter.info("unknown content type received: #{header}")
-      {}
+    # Some endpoints serve JSON under a textual content type; anything else passes through under `data`.
+    def parse_textual_body(body)
+      parsed = JSON.parse(body)
+      parsed.is_a?(Hash) || parsed.is_a?(Array) ? wrap_array(parsed) : { 'data' => body }
+    rescue JSON::ParserError
+      { 'data' => body }
     end
 
-    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+    def without_byte_order_mark(body)
+      return body unless body.byteslice(0, BYTE_ORDER_MARK.bytesize)&.b == BYTE_ORDER_MARK
 
-    def sniff_json(body)
-      trimmed = body.to_s.strip
-      return nil unless trimmed.start_with?('{', '[')
+      body.byteslice(BYTE_ORDER_MARK.bytesize..)
+    end
 
-      wrap_array(JSON.parse(trimmed))
-    rescue JSON::ParserError
+    # A polling url often carries its api key in the query string.
+    def without_query(url) = url.split('?').first
+
+    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+
+    def report_warning(message)
+      reporter.info(reporter.yellow("warning: #{message}"))
       nil
     end
 
     def write_user_data(data)
-      paths.create_cache_dir
+      paths.user_data.dirname.mkpath
       paths.user_data.write(JSON.generate(data))
     end
   end

data/lib/trmnlp/rails_helpers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'i18n'
+require 'active_support'
+require 'active_support/number_helper'
+require 'active_support/core_ext/string/inflections'
+
+module TRMNL
+  module Liquid
+    # The ActionView helpers TRMNL::Liquid.load(:rails) gives the filters, without Rails.
+    module RailsHelpers
+      HTML_ESCAPED_OPTIONS = %i[unit separator delimiter].freeze
+
+      module_function
+
+      def number_to_currency(number, **options)
+        number && ActiveSupport::NumberHelper.number_to_currency(number, html_escape_options(options))
+      end
+
+      def number_with_delimiter(number, **options)
+        number && ActiveSupport::NumberHelper.number_to_delimited(number, html_escape_options(options))
+      end
+
+      def pluralize(count, singular, plural: nil, locale: ::I18n.locale)
+        word = count == 1 || count.to_s.match?(/^1(\.0+)?$/) ? singular : plural || singular.pluralize(locale)
+        "#{count || 0} #{word}"
+      end
+
+      def html_escape_options(options)
+        options.to_h { |key, value| [key, HTML_ESCAPED_OPTIONS.include?(key) && value ? ERB::Util.html_escape(value) : value] }
+      end
+    end
+  end
+end
+
+locale_files = Dir[File.expand_path('../../db/data/locales/*.yml', __dir__)]
+I18n.load_path += locale_files
+I18n.available_locales = locale_files.map { |path| File.basename(path, '.yml') }
+I18n.backend.class.include I18n::Backend::Fallbacks
+I18n.fallbacks = I18n::Locale::Fallbacks.new(:en)

data/lib/trmnlp/renderer.rb

@@ -1,12 +1,18 @@
 # frozen_string_literal: true
 
 require 'erb'
+require 'json'
+require 'yaml'
 require 'trmnl/liquid'
 
 require_relative 'screen'
 
 module TRMNLP
   class Renderer
+    # TRMNL refuses to render merge variables past this size.
+    MAX_MERGE_VARIABLES_KB = 100
+    AND_X_MORE = YAML.load_file(File.expand_path('../../db/data/and_x_more.yml', __dir__)).freeze
+
     def initialize(config:, paths:, user_data_assembler:)
       @config = config
       @paths = paths
@@ -23,10 +29,24 @@ module TRMNLP
 
     def framework = config.plugin.framework_version
 
-    def screen_classes(classes = 'screen')
-      classes ||= 'screen' # an explicit nil (omitted screen_classes param) still needs a base
-      classes += ' screen--no-bleed' if config.plugin.no_screen_padding == 'yes'
-      classes
+    def screen_classes(classes = 'screen', theme: nil)
+      classes = (classes || 'screen').split # an explicit nil (omitted screen_classes param) still needs a base
+      # The picker marks every render 1x, which sets the dither ratio; TRMNL's device render has no such class.
+      classes.delete('screen--1x')
+      classes << 'screen--no-bleed' if config.plugin.no_screen_padding == 'yes'
+      classes << 'screen--dark-mode' if config.plugin.dark_mode == 'yes'
+      # Framework 1.x inverts only on the bare dark-mode class.
+      classes << 'dark-mode' if classes.include?('screen--dark-mode')
+      # A new device renders in the TRMNL font unless its owner picks another.
+      classes << 'screen--fonts-trmnl' if classes.none? { it.start_with?('screen--fonts-') }
+      classes << "screen--theme-#{theme}" if FrameworkVersion::THEMES.key?(theme)
+      classes.uniq.join(' ')
+    end
+
+    # TRMNL's window.I18n.andXMore phrase for the user's locale, as [prefix, suffix].
+    def and_x_more
+      locale = config.project.user_data_overrides.dig('trmnl', 'user', 'locale').to_s
+      AND_X_MORE[locale] || AND_X_MORE[locale.split('-').first] || AND_X_MORE['en']
     end
 
     private
@@ -46,8 +66,15 @@ module TRMNLP
     end
 
     def parse_and_render(template_path, device:)
-      Liquid::Template.parse(full_markup(template_path), environment: liquid_environment)
-                      .render(user_data_assembler.call(device:))
+      data = user_data_assembler.call(device:)
+      size = JSON.generate(data.except('trmnl')).bytesize
+      if size > MAX_MERGE_VARIABLES_KB * 1024
+        raise RenderError, "Large payload received (#{size} bytes), should be less than #{MAX_MERGE_VARIABLES_KB}kb."
+      end
+
+      Liquid::Template.parse(full_markup(template_path), environment: liquid_environment).render(data)
+    rescue RenderError
+      raise
     rescue StandardError => e
       raise RenderError, e.message
     end
@@ -65,10 +92,7 @@ module TRMNLP
 
     def liquid_environment
       @liquid_environment ||= TRMNL::Liquid.new do |env|
-        config.project.user_filters.each do |module_name, relative_path|
-          require paths.root_dir.join(relative_path)
-          env.register_filter(Object.const_get(module_name))
-        end
+        config.project.user_filter_modules.each { |filter_module| env.register_filter(filter_module) }
       end
     end
 
@@ -76,8 +100,10 @@ module TRMNLP
     class TemplateBinding
       def initialize(renderer, view, params)
         @view = view
-        @screen_classes = renderer.screen_classes(params[:screen_classes])
+        @screen_classes = renderer.screen_classes(params[:screen_classes], theme: params[:theme])
         @framework = renderer.framework
+        @theme_css_url = @framework.theme_css_url(params[:theme])
+        @and_x_more = renderer.and_x_more
         @mashup_classes = Screen.find(view)&.mashup_classes
       end
 

data/lib/trmnlp/screen_generator.rb

@@ -5,6 +5,17 @@ require_relative 'image_quantizer'
 
 module TRMNLP
   class ScreenGenerator
+    # TRMNL's own copies (Converter::Preprocessor); the CDN refuses a page with no Referer.
+    CHART_LIBRARIES = {
+      'https://code.highcharts.com/highcharts.js' => 'https://trmnl.com/js/highcharts/12.3.0/highcharts.js',
+      'https://code.highcharts.com/12.3.0/highcharts.js' => 'https://trmnl.com/js/highcharts/12.3.0/highcharts.js',
+      'https://cdn.jsdelivr.net/npm/chartkick@5.0.1/dist/chartkick.min.js' => 'https://trmnl.com/js/chartkick/5.0.1/chartkick.min.js',
+      'https://code.highcharts.com/highcharts-more.js' => 'https://trmnl.com/js/highcharts/12.3.0/highcharts-more.js',
+      'https://code.highcharts.com/12.3.0/highcharts-more.js' => 'https://trmnl.com/js/highcharts/12.3.0/highcharts-more.js',
+      'https://code.highcharts.com/modules/pattern-fill.js' => 'https://trmnl.com/js/highcharts/12.3.0/pattern-fill.js',
+      'https://code.highcharts.com/12.3.0/modules/pattern-fill.js' => 'https://trmnl.com/js/highcharts/12.3.0/pattern-fill.js'
+    }.freeze
+
     def initialize(html, opts = {})
       @input = html
       @screenshot = opts[:screenshot]
@@ -14,8 +25,9 @@ module TRMNLP
     end
 
     def process
-      output = @screenshot.call(html: @input, width:, height:)
-      ImageQuantizer.new(depth: color_depth).call(output.path)
+      html = CHART_LIBRARIES.reduce(@input) { |page, (from, to)| page.gsub(from, to) }
+      output = @screenshot.call(html:, width:, height:)
+      ImageQuantizer.new(depth: color_depth, dither: @input.include?('image-dither')).call(output.path)
       output
     end
 

data/lib/trmnlp/screenshot.rb

@@ -7,6 +7,26 @@ require_relative 'errors'
 
 module TRMNLP
   class Screenshot
+    # TRMNL's Converter::Html waits for these flags, longer for a map, then captures what is drawn.
+    READINESS_TIMEOUT_SECONDS = 5
+    READINESS_TIMEOUT_WITH_MAPS_SECONDS = 12
+    MAPS_DOCUMENT_PATTERN = %r{TRMNLMaps\.[a-z]|maplibre-gl(?:\.js|\.css|[/@]\d)}
+    READINESS_CHECK_SCRIPT = <<~JS
+      return document.readyState === 'complete' && window.TRMNL_PLUGINS_READY === true &&
+             window.TRMNL_HIGHCHARTS_DONE === true && window.TRMNL_CHILD_DITHER_DONE !== false
+    JS
+    # Stops timers and animation callbacks from changing the page mid-capture.
+    FREEZE_TIMERS = <<~JS
+      const noop = () => 0;
+      window.setTimeout = window.setInterval = noop;
+      window.requestAnimationFrame = noop;
+      if (window.requestIdleCallback) window.requestIdleCallback = noop;
+      for (let i = 100000; i >= 0; i--) { window.clearTimeout(i); window.clearInterval(i); }
+      if (window.ResizeObserver) window.ResizeObserver.prototype.observe = noop;
+      if (window.MutationObserver) window.MutationObserver.prototype.observe = noop;
+      window.onresize = null;
+    JS
+
     def initialize(pool:, viewport_timeout: 5)
       @pool = pool
       @viewport_timeout = viewport_timeout
@@ -87,16 +107,21 @@ module TRMNLP
         document.close();
       JS
 
-      Selenium::WebDriver::Wait.new(timeout: 5).until do
-        driver.execute_script('return document.readyState') == 'complete'
-      end
-
+      wait_until_ready(driver, html)
       driver.execute_script('return document.fonts && document.fonts.ready')
 
       driver.execute_script(<<~JS)
         document.documentElement.style.overflow = 'hidden';
         document.body.style.overflow = 'hidden';
       JS
+      driver.execute_script(FREEZE_TIMERS)
+    end
+
+    def wait_until_ready(driver, html)
+      timeout = html.match?(MAPS_DOCUMENT_PATTERN) ? READINESS_TIMEOUT_WITH_MAPS_SECONDS : READINESS_TIMEOUT_SECONDS
+      Selenium::WebDriver::Wait.new(timeout:, interval: 0.05).until { driver.execute_script(READINESS_CHECK_SCRIPT) }
+    rescue Selenium::WebDriver::Error::TimeoutError
+      nil
     end
 
     def capture(driver)

data/lib/trmnlp/select_field_choices.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  # A select field's options as TRMNL saves them: "New York" as new_york, { Label: value } as its value.
+  class SelectFieldChoices
+    def initialize(field)
+      options = field['options']
+      @options = options.is_a?(Array) ? options.compact : []
+    end
+
+    def pairs
+      @pairs ||= @options.map do |option|
+        option.is_a?(Hash) ? [option.keys.first, option.values.first] : [option, option.to_s.downcase.tr(' ', '_')]
+      end
+    end
+
+    # A label becomes its value; a value, or anything the options do not list, is kept as it is.
+    def stored_value(input)
+      return input.map { stored_value(it) } if input.is_a?(Array)
+      return input if input.to_s.empty? || pairs.any? { |_, value| value.to_s == input.to_s }
+
+      pairs.find { |label, _| label.to_s == input.to_s }&.last&.to_s || input
+    end
+  end
+end

data/lib/trmnlp/transform_pipeline.rb

@@ -4,6 +4,7 @@ require 'json'
 
 require_relative 'reporter'
 require_relative 'transform_client'
+require_relative 'transform_state'
 
 module TRMNLP
   # Pipes assembled merge_variables through src/transform.{py,rb,php,js}
@@ -13,12 +14,16 @@ module TRMNLP
   # Failure modes surface via #error (rendered in the preview UI), not
   # raised.
   class TransformPipeline
+    # TRMNL's serverless runtime stops a transform after this long.
+    EXECUTION_TIMEOUT_SECONDS = 5
+
     attr_reader :error
 
     def initialize(config:, paths:, reporter: Reporter.new)
       @config = config
       @paths = paths
       @reporter = reporter
+      @transform_state = TransformState.new(paths:, reporter:)
     end
 
     def call(data)
@@ -29,17 +34,27 @@ module TRMNLP
       run(transform_path, inferred_language, data)
     end
 
+    def configured? = !paths.transform_file.first.nil? && !client.nil?
+
+    # What the last run stored for the markup, passed to the next run as trmnl.previous_merge_variables.
+    def previous_output
+      paths.transform_output.exist? ? JSON.parse(paths.transform_output.read) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
     def reset! = @client = nil
 
     private
 
-    attr_reader :config, :paths, :reporter
+    attr_reader :config, :paths, :reporter, :transform_state
 
     def client = @client ||= TransformClient.from_config(config.project)
 
     def run(path, inferred_language, data)
       language = config.plugin.serverless_language || inferred_language
-      result = client.execute(code: path.read, stdin: JSON.generate(data), language:)
+      result = client.execute(code: path.read, stdin: JSON.generate(data), language:,
+                              timeout_seconds: EXECUTION_TIMEOUT_SECONDS)
       report_printed_output(result)
       return record_failure(result, data) unless result.success?
 
@@ -56,18 +71,44 @@ module TRMNLP
     def record_failure(result, fallback)
       @error = result.error || "transform exited #{result.exit_code}: #{result.stderr.strip}"
       reporter.info("transform failed: #{result.error || "exited #{result.exit_code}"}")
-      fallback
+      last_good_output(fallback)
     end
 
+    # TRMNL keeps the last good screen when a transform fails.
+    def last_good_output(fallback) = paths.transform_output.exist? ? previous_output : fallback
+
     def parse_output(output, fallback)
       transformed = JSON.parse(output)
-      transformed.is_a?(Hash) ? transformed : wrap_array(transformed)
+      return reject_non_object_output unless transformed.is_a?(Hash)
+
+      transform_state.extract!(transformed)
+      store_output(without_previous_merge_variables(transformed))
     rescue JSON::ParserError => e
       @error = "transform produced non-JSON output: #{e.message}"
       reporter.info(@error)
-      fallback
+      last_good_output(fallback)
     end
 
-    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+    # TRMNL renders nothing from an array or a scalar, and refuses one from a webhook post.
+    def reject_non_object_output
+      @error = 'Transform output must be a JSON object'
+      reporter.info(@error)
+      {}
+    end
+
+    def store_output(output)
+      paths.transform_output.dirname.mkpath
+      paths.transform_output.write(JSON.generate(output))
+      output
+    end
+
+    # A transform that echoes its input at any depth (`{ data: input }`) would store its history and double every run.
+    def without_previous_merge_variables(value)
+      case value
+      when Hash then value.except('previous_merge_variables').transform_values { without_previous_merge_variables(it) }
+      when Array then value.map { without_previous_merge_variables(it) }
+      else value
+      end
+    end
   end
 end

data/lib/trmnlp/transform_state.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'reporter'
+
+module TRMNLP
+  # The `trmnl_state` key a transform returns is kept for its next run as trmnl.state instead of rendered.
+  class TransformState
+    KEY = 'trmnl_state'
+    MAX_BYTES = 8 * 1024
+
+    def initialize(paths:, reporter: Reporter.new)
+      @paths = paths
+      @reporter = reporter
+    end
+
+    def read
+      paths.transform_state.exist? ? JSON.parse(paths.transform_state.read) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def extract!(output)
+      return unless output.is_a?(Hash) && output.key?(KEY)
+
+      state = output.delete(KEY)
+      rejection = rejection_reason(state)
+      rejection ? reporter.info(reporter.yellow("Ignored #{KEY}: #{rejection}")) : write(state)
+    end
+
+    private
+
+    attr_reader :paths, :reporter
+
+    def rejection_reason(state)
+      return "expected an object, got #{state.class}" unless state.is_a?(Hash)
+
+      size = JSON.generate(state).bytesize
+      "#{size} bytes exceeds the #{MAX_BYTES} byte limit" if size > MAX_BYTES
+    end
+
+    def write(state)
+      paths.transform_state.dirname.mkpath
+      paths.transform_state.write(JSON.generate(state))
+    end
+  end
+end