trmnl_preview 0.31.3 → 0.32.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c07e1813b7c71b84fc849092cdd5062c567999d0e0a86751e6307dd0e776eeb1
-  data.tar.gz: 575ed56ce3f0138f1018028be28dc0d415ea53c8cfc9fe858194d2f61e36ca1a
+  metadata.gz: 3466bcd07fed1c8ff658708ab71e6a7d8c42c70395baff5f72de8671dbdec9d2
+  data.tar.gz: 871fdb7df75979caf9a19727f26621653a028fd0d37a9d39afeee10c67ac920f
 SHA512:
-  metadata.gz: 88e02be63365d656f4bd9556df374874a510fcaeb90765738a209ca6dff2fc6194015d2a3c78a0796694c5daa8b63eefbbd2186f96d27029d6e16bf50986b7fc
-  data.tar.gz: 3af42a4e80fdae57cc2e68a9d426e21d5f765101a6cbf52ff416551faee09a3aa657b9e25848682ddd5bad1a0f8ccd17f581ef1b738ad852a523a634c068f958
+  metadata.gz: d818264f98865e742f29d61bc8514726f951ccc3c0074e78a00472d19e10fd7c4071940506228a389d07989a6231f47d16342f7d119027a231ba514b415e020e
+  data.tar.gz: 69f1e91eacc992904e2de3a6d289e5abda4b65caf51dcc6948f602b5794322b993dd8628e7a946cffe8aad2a757a24759ad12c5390bd2e96b9cdf4b69861a749

data/CHANGELOG.md

@@ -1,6 +1,14 @@
 
 # Changelog
 
+## 0.32.1
+
+- `trmnlp test`'s publishable recipe fails a view that has no markup file and no shared markup. It drew only "Missing template", and passed. The message now names the file from the plugin folder, such as `src/full.liquid`, not the folders on your computer.
+
+## 0.32.0
+
+- `asset_overrides` in `.trmnlp.yml` replaces a literal URL, or a URL prefix ending in `/`, with a local file, a local folder or another URL, so a plugin can be previewed and tested with a local build of its own script, images or fonts before they are published. `trmnlp serve`, `trmnlp test` and `trmnlp build --png` serve the overrides from the asset cache; `trmnlp build` keeps the published URLs, and `--bundle-assets` copies the files next to the HTML. A test can set its own overrides, also as inline content, and `--report` lists every swap. `trmnlp serve` redraws when an overridden file changes, from a local folder or from another URL such as a bundler's dev server.
+
 ## 0.31.3
 
 - The Docker image draws TRMNLMaps maps. Firefox on Linux gets a WebGL context only from an X display, so maps drew blank under `trmnlp test` and `trmnlp serve` in the image; it now starts Xvfb and allows software WebGL, as TRMNL's render boxes do.

data/README.md

@@ -385,8 +385,18 @@ ignored_lint_rules:
 # each mapped to the trmnlp project whose last fetched data stands in for it
 merged_plugins:
   private_plugin_42: ../weather
+
+# replace literal asset URLs during serve, test, and build --png
+asset_overrides:
+  https://example.com/logo.svg: assets/logo.svg
+  https://example.com/icons/: assets/icons
+  https://example.com/app.js: https://mirror.example.com/app.js
 ```
 
+`asset_overrides` keys are literal URLs. A key ending in `/` matches a URL prefix and maps to a local folder or a URL prefix ending in `/`; the longest matching key wins. Other keys map to a local file or another URL. Local paths are relative to the plugin directory. Wildcards, regular expressions and placeholders are not supported. A missing local file is an error. `build` keeps published URLs in HTML by default; `build --bundle-assets` copies overridden assets into `_build/assets/` and uses relative links. In a plugin test, `trmnl.render(asset_overrides: { 'https://example.com/app.js' => { body: 'window.ready = true', content_type: 'text/javascript' } })` adds an override for that test. The test mapping wins on the same key, and `content_type` defaults to the URL's file type. `trmnl.transform` accepts the same mapping.
+
+`trmnlp serve` redraws when an overridden local file or folder changes, without adding it to `watch`. For an override that points at another URL, such as a bundler's dev server, the open preview asks again every second for the files it loaded and redraws when one changes; trmnlp keeps each file as long as that server's cache-control allows.
+
 An `async_polling` plugin gets `{{ callback_url }}` in its polling url. It points at
 `trmnlp serve`'s `/callback` route, where the API posts `merge_variables` after answering 202.
 

data/lib/trmnlp/app.rb

@@ -81,6 +81,8 @@ module TRMNLP
       redirect '/full'
     end
 
+    get('/overrides/*') { settings.asset_cache.override_response(request.path_info, request.user_agent) || halt(502) }
+
     get '/data' do
       content_type :json
       device = @user_data_assembler.device_from_params(params)
@@ -213,12 +215,14 @@ module TRMNLP
       end
 
       get "/render/#{view}.html" do
-        Screenshot.live_preview(@renderer.render_full_page(view, params))
+        html = Screenshot.live_preview(@renderer.render_full_page(view, params))
+        settings.asset_cache.point_overrides_at(html, overrides: @context.config.project.asset_overrides)
       end
 
       get "/render/#{view}.png" do
         @view = view
         html = @renderer.render_full_page(view, params)
+        html = settings.asset_cache.rewrite_if_configured(html, overrides: @context.config.project.asset_overrides)
         temp_image = render_png(html, params)
 
         send_file temp_image.path, type: 'image/png', disposition: 'inline'

data/lib/trmnlp/cli.rb

@@ -43,6 +43,8 @@ module TRMNLP
 
     desc 'build', 'Generate static HTML files'
     method_option :png, type: :boolean, default: false, desc: 'Also render a PNG per view'
+    method_option :bundle_assets, type: :boolean, default: false,
+                                  desc: 'Copy overridden assets into _build/assets and use relative links'
     method_option :width, type: :numeric, desc: 'PNG width in pixels (with --png)'
     method_option :height, type: :numeric, desc: 'PNG height in pixels (with --png)'
     method_option :color_depth, type: :numeric, desc: 'PNG bit depth: 1-8 (with --png)'

data/lib/trmnlp/commands/build.rb

@@ -7,11 +7,14 @@ require_relative '../browser_pool'
 require_relative '../firefox_driver'
 require_relative '../screen_generator'
 require_relative '../screenshot'
+require_relative '../testing/asset_cache'
 
 module TRMNLP
   module Commands
     class Build < Base
-      Options = Data.define(:dir, :quiet, :png, :width, :height, :color_depth)
+      Options = Data.define(:dir, :quiet, :png, :width, :height, :color_depth, :bundle_assets) do
+        def initialize(bundle_assets: false, **) = super(**, bundle_assets:)
+      end
 
       def call
         context.validate!
@@ -25,14 +28,23 @@ module TRMNLP
         reporter.info 'Done!'
       ensure
         @browser_pool&.shutdown
+        @asset_cache&.stop
       end
 
       private
 
       def build_screen(screen)
         html = context.renderer.render_full_page(screen.name)
-        write_html(screen.name, html)
-        write_png(screen.name, html) if options.png
+        overrides = context.config.project.asset_overrides
+        built = if options.bundle_assets && overrides.any?
+                  asset_cache.rewrite(html, overrides:,
+                                            bundle_dir: context.paths.build_dir)
+                else
+                  html
+                end
+        write_html(screen.name, built)
+        preview = options.png && overrides.any? ? asset_cache.rewrite(html, overrides:) : html
+        write_png(screen.name, preview) if options.png
       end
 
       def write_html(view, html)
@@ -61,6 +73,10 @@ module TRMNLP
 
       def screenshot = @screenshot ||= Screenshot.new(pool: browser_pool)
 
+      def asset_cache
+        @asset_cache ||= Testing::AssetCache.new(dir: context.paths.cache_dir.join('assets')).start
+      end
+
       def browser_pool
         @browser_pool ||= BrowserPool.new(driver_factory: FirefoxDriver.method(:build))
       end

data/lib/trmnlp/commands/serve.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../api_client'
 require_relative '../browser_pool'
 require_relative '../firefox_driver'
+require_relative '../testing/asset_cache'
 
 module TRMNLP
   module Commands
@@ -12,6 +13,7 @@ module TRMNLP
 
       def call
         context.validate!
+        context.config.project.asset_overrides
         report_form_field_warnings
         report_framework_version_warning
 
@@ -20,6 +22,8 @@ module TRMNLP
 
         # Now we can configure things
         App.set(:context, context)
+        @asset_cache = Testing::AssetCache.new(dir: context.paths.cache_dir.join('assets')).start
+        App.set(:asset_cache, @asset_cache)
         App.set(:browser_pool, BrowserPool.new(driver_factory: FirefoxDriver.method(:build)))
         App.set(:bind, options.bind)
         App.set(:port, options.port)
@@ -31,6 +35,8 @@ module TRMNLP
 
         # Finally, start the app!
         App.run!
+      ensure
+        @asset_cache&.stop
       end
 
       private

data/lib/trmnlp/commands/test.rb

@@ -11,6 +11,7 @@ module TRMNLP
 
       def call(paths = [])
         context.validate!
+        context.config.project.asset_overrides
         require 'rspec/core'
 
         ENV['TRMNLP_PLUGIN_DIR'] = context.paths.root_dir.to_s

data/lib/trmnlp/config/project.rb

@@ -2,6 +2,7 @@
 
 require 'trmnl/liquid'
 require 'yaml'
+require 'uri'
 
 require_relative '../errors'
 require_relative '../framework_version'
@@ -33,7 +34,7 @@ module TRMNLP
       def live_render? = !watch_paths.empty?
 
       def watch_paths
-        (@config['watch'] || []).map { |watch_path| paths.expand(watch_path) }.uniq
+        ((@config['watch'] || []) + local_asset_override_targets).map { |watch_path| paths.expand(watch_path) }.uniq
       end
 
       def custom_fields = @config.fetch('custom_fields', {}).transform_values { |v| stringify_field_value(v) }
@@ -61,6 +62,13 @@ module TRMNLP
       # .trmnlp.yml. Consumed by Config::Plugin#framework_version.
       def asset_host = @config['framework_asset_host'] || FrameworkVersion::DEFAULT_ASSET_HOST
 
+      def asset_overrides(extra = {}, allow_inline: false)
+        mapping = @config.fetch('asset_overrides', {}) || {}
+        raise InvalidConfig, 'asset_overrides must be a mapping' unless mapping.is_a?(Hash)
+
+        normalize_asset_overrides(mapping).merge(normalize_asset_overrides(extra, allow_inline:))
+      end
+
       # Toggles serverless transform support. Enabled by default; set to
       # 'disabled' in .trmnlp.yml to turn it off. A transform only runs
       # when a src/transform.* file is also present, so the default is
@@ -89,6 +97,68 @@ module TRMNLP
 
       private
 
+      # Read without asset_overrides' checks, so a deleted file does not stop the watcher.
+      def local_asset_override_targets
+        mapping = @config['asset_overrides']
+        mapping.is_a?(Hash) ? mapping.values.grep(String).grep_v(%r{\Ahttps?://}) : []
+      end
+
+      def normalize_asset_overrides(mapping, allow_inline: false)
+        raise InvalidConfig, 'asset_overrides must be a mapping' unless mapping.is_a?(Hash)
+
+        mapping.to_h do |source, target|
+          validate_asset_key!(source)
+          [source, normalize_asset_target(source, target, allow_inline:)]
+        rescue URI::InvalidURIError
+          raise InvalidConfig, "asset_overrides key must be a literal URL: #{source.inspect}"
+        end
+      end
+
+      def validate_asset_key!(source)
+        uri = URI.parse(source.to_s)
+        valid = source.is_a?(String) && %w[http https].include?(uri.scheme) && uri.host &&
+                !source.match?(/[*{}\[\]\\()|]/)
+        raise InvalidConfig, "asset_overrides key must be a literal URL: #{source.inspect}" unless valid
+      end
+
+      def normalize_asset_target(source, target, allow_inline:)
+        return inline_asset_target(source, target, allow_inline:) if target.is_a?(Hash)
+        return url_asset_target(source, target) if target.is_a?(String) && target.match?(%r{\Ahttps?://})
+
+        local_asset_target(source, target)
+      end
+
+      def inline_asset_target(source, target, allow_inline:)
+        raise InvalidConfig, "asset_overrides #{source}: inline body needs a literal file URL" if source.end_with?('/')
+        unless allow_inline && (target.key?(:body) || target.key?('body'))
+          raise InvalidConfig, "asset_overrides #{source}: inline body is only allowed in tests"
+        end
+
+        target.transform_keys(&:to_sym)
+      end
+
+      def url_asset_target(source, target)
+        uri = URI.parse(target)
+        unless uri.host && (!source.end_with?('/') || target.end_with?('/'))
+          raise InvalidConfig, "asset_overrides #{source}: a URL prefix target must end in /"
+        end
+
+        target
+      end
+
+      def local_asset_target(source, target)
+        path = paths.expand(target.to_s)
+        raise InvalidConfig, "asset_overrides #{source}: local path does not exist: #{path}" unless path.exist?
+        if source.end_with?('/') && !path.directory?
+          raise InvalidConfig, "asset_overrides #{source}: a URL prefix needs a local folder"
+        end
+        if !source.end_with?('/') && path.directory?
+          raise InvalidConfig, "asset_overrides #{source}: a folder needs a URL prefix ending in /"
+        end
+
+        path.to_s
+      end
+
       def read_config
         return {} unless paths.trmnlp_config.exist?
 

data/lib/trmnlp/renderer.rb

@@ -64,7 +64,7 @@ module TRMNLP
     def render_liquid_template(view, device: {})
       template_path = paths.template(view)
       unless template_path.exist? || paths.shared_template.exist?
-        raise RenderError, "Missing template: #{template_path}"
+        raise RenderError, "Missing template: #{template_path.relative_path_from(paths.root_dir)}"
       end
 
       parse_and_render(template_path, device:)

data/lib/trmnlp/testing/asset_cache.rb

@@ -4,9 +4,12 @@ require 'digest'
 require 'fileutils'
 require 'json'
 require 'net/http'
+require 'rack/mime'
 require 'socket'
+require 'uri'
 
 require_relative '../framework_version'
+require_relative '../errors'
 
 module TRMNLP
   module Testing
@@ -18,10 +21,15 @@ module TRMNLP
       SAFE_PATH = %r{\A/(?:[\w.-]+/)*[\w.-]+\z}
       DOWNLOAD_TIMEOUT_SECONDS = 10
       BAD_GATEWAY = "HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\nconnection: close\r\n\r\n"
+      URL_LINK = %r{https?://[^\s"'<>),;]+}
+      OVERRIDE_PATH = %r{\A/overrides/(\h{16})/(.*)\z}
+      LOCAL = { 'cache_control' => 'no-store', 'allow_origin' => '*' }.freeze
 
       def initialize(dir:, clock: -> { Time.now })
         @dir = dir.to_s
         @clock = clock
+        @overrides = {}
+        @lock = Mutex.new
       end
 
       def start
@@ -37,10 +45,126 @@ module TRMNLP
 
       def url = "http://127.0.0.1:#{@server.addr[1]}"
 
-      def point_framework_links_at_cache(html) = point_google_fonts_at_cache(html.gsub(FRAMEWORK_LINK, url))
+      def rewrite_if_configured(html, overrides:) = overrides.empty? ? html : rewrite(html, overrides:)
+
+      # Rewrites text, including URL strings in scripts, before the normal Framework and font substitutions.
+      def rewrite(html, overrides: {}, swaps: nil, bundle_dir: nil)
+        rewritten = point_overrides_at(html, overrides:, base: "#{url}/overrides", swaps:, bundle_dir:)
+        return rewritten if bundle_dir
+
+        rewritten = rewritten.gsub(FRAMEWORK_LINK) do
+          original = ::Regexp.last_match(0) + ::Regexp.last_match.post_match[/\A[^\s"'<>),;]*/].to_s
+          swaps&.push(url: original, target: original.sub(HOST, url), kind: 'framework')
+          url
+        end
+        rewritten.gsub(GOOGLE_FONTS_LINK) do
+          host = ::Regexp.last_match(1)
+          original = ::Regexp.last_match(0) + ::Regexp.last_match.post_match[/\A[^\s"'<>),;]*/].to_s
+          swaps&.push(url: original, target: original.sub('https://', "#{url}/"), kind: 'fonts')
+          "#{url}/#{host}/"
+        end
+      end
+
+      # A folder key keeps the rest of the URL, so files the asset links relative to itself resolve in the same folder.
+      # The default base is the page's own server, so serve's preview reaches it from outside a container.
+      def point_overrides_at(html, overrides:, base: '/overrides', swaps: nil, bundle_dir: nil)
+        html.gsub(URL_LINK) do |source|
+          key = overrides.keys.select { folder?(it) ? source.start_with?(it) : source == it }.max_by(&:length)
+          next source unless key
+
+          target = overrides.fetch(key)
+          rest = folder?(key) ? source.delete_prefix(key) : File.basename(URI(source).path)
+          check_local_file!(source, key, target, rest)
+          swaps&.push(url: source, target: target.is_a?(Hash) ? '[inline body]' : resolve(key, target, rest),
+                      kind: 'override')
+          id = register_override(key, target)
+          bundle_dir ? bundle_asset(id, key, target, rest, bundle_dir) : "#{base}/#{id}/#{rest}"
+        end
+      end
+
+      def override_response(path, user_agent)
+        asset = override_asset(path, user_agent) or return
+        [200, { 'content-type' => asset['content_type'], 'cache-control' => asset['cache_control'],
+                'access-control-allow-origin' => asset['allow_origin'] }.compact, [asset['body']]]
+      end
 
       private
 
+      def override_asset(path, user_agent)
+        id, rest = path.match(OVERRIDE_PATH)&.captures
+        key, target = @lock.synchronize { @overrides[id] }
+        return unless key
+
+        rest = URI.decode_uri_component(rest)
+        return published_neighbor(key, rest, user_agent) unless folder?(key) || rest == File.basename(URI(key).path)
+
+        overridden(key, target, rest, user_agent)
+      end
+
+      def folder?(key) = key.end_with?('/')
+
+      def url?(target) = target.is_a?(String) && target.match?(%r{\Ahttps?://})
+
+      def overridden(key, target, rest, user_agent)
+        found = resolve(key, target, rest)
+        type = mime(folder?(key) ? "#{key}#{rest}" : key)
+        if found.is_a?(Hash)
+          { 'body' => found.fetch(:body).to_s, 'content_type' => found[:content_type] || type }.merge(LOCAL)
+        elsif url?(found) then remote_asset(found, user_agent)
+        elsif found && File.file?(found) then { 'body' => File.binread(found), 'content_type' => type }.merge(LOCAL)
+        end
+      end
+
+      # The file, URL or inline content an overridden URL stands for; nil for a path outside the folder.
+      def resolve(key, target, rest)
+        return target unless folder?(key)
+        return "#{target}#{rest}" if url?(target)
+
+        path = File.expand_path(rest.split('?', 2).first.to_s, target)
+        path if path == File.expand_path(target) || path.start_with?("#{File.expand_path(target)}/")
+      end
+
+      def check_local_file!(source, key, target, rest)
+        return if target.is_a?(Hash) || url?(target) || rest.empty?
+
+        path = resolve(key, target, rest)
+        raise InvalidConfig, "asset_overrides #{source}: no local file at #{path}" unless File.exist?(path.to_s)
+      end
+
+      # Keyed by what is swapped, so a page rewritten again gets the same address and the table stays one row per key.
+      def register_override(key, target)
+        Digest::SHA256.hexdigest("#{key} #{target.inspect}")[0, 16].tap { |id| @lock.synchronize { @overrides[id] = [key, target] } }
+      end
+
+      # A file next to an overridden single file comes from where it was published, on the same host.
+      def published_neighbor(key, rest, user_agent)
+        neighbor = URI.join(key, rest)
+        remote_asset(neighbor.to_s, user_agent) if neighbor.host == URI(key).host
+      end
+
+      def bundle_asset(id, key, target, rest, dir)
+        folder = File.join(dir, 'assets', id)
+        if folder?(key) && !url?(target)
+          FileUtils.mkdir_p(folder)
+          FileUtils.cp_r("#{target}/.", folder)
+        elsif !rest.empty? && !rest.end_with?('/')
+          body = overridden(key, target, rest, nil)&.fetch('body')
+          raise InvalidConfig, "asset_overrides #{key}: could not fetch #{resolve(key, target, rest)}" unless body
+
+          FileUtils.mkdir_p(File.dirname(destination = File.join(folder, rest.split('?', 2).first)))
+          File.binwrite(destination, body)
+        end
+        "assets/#{id}/#{rest}"
+      end
+
+      def remote_asset(target, user_agent)
+        key = "/remote/#{Digest::SHA256.hexdigest(target)}"
+        cached = cached(key)
+        cached && cached['expires_at'] > @clock.call.to_i ? cached : download(key, URI(target), user_agent) || cached
+      end
+
+      def mime(source) = Rack::Mime.mime_type(File.extname(URI(source).path), 'application/octet-stream')
+
       def point_google_fonts_at_cache(text) = text.gsub(GOOGLE_FONTS_LINK) { "#{url}/#{::Regexp.last_match(1)}/" }
 
       def serve(socket)
@@ -49,9 +173,11 @@ module TRMNLP
         while (line = socket.gets) && !line.strip.empty?
           user_agent = line.split(':', 2).last.strip if line.downcase.start_with?('user-agent:')
         end
-        asset = !path.to_s.include?('..') && path.to_s.match?(SAFE_PATH) && asset(path, query, user_agent)
+        asset = if path.to_s.start_with?('/overrides/') then override_asset(path, user_agent)
+                elsif !path.to_s.include?('..') && path.to_s.match?(SAFE_PATH) then asset(path, query, user_agent)
+                end
         socket.write(asset ? response(asset) : BAD_GATEWAY)
-      rescue IOError, SystemCallError
+      rescue IOError, SystemCallError, URI::Error
         nil
       ensure
         socket.close unless socket.closed?
@@ -82,7 +208,9 @@ module TRMNLP
       def download(key, uri, user_agent)
         headers = { 'Origin' => url, 'User-Agent' => user_agent }.compact
         timeouts = { open_timeout: DOWNLOAD_TIMEOUT_SECONDS, read_timeout: DOWNLOAD_TIMEOUT_SECONDS }
-        answer = Net::HTTP.start(uri.host, uri.port, use_ssl: true, **timeouts) { it.get(uri.request_uri, headers) }
+        answer = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', **timeouts) do |http|
+          http.get(uri.request_uri, headers)
+        end
         answer.is_a?(Net::HTTPSuccess) ? cache_download(key, answer) : nil
       rescue StandardError
         nil

data/lib/trmnlp/testing/browser.rb

@@ -32,7 +32,8 @@ module TRMNLP
       # Loads the screen's page; its picture is only taken when a test asks for it.
       def load(screen)
         generator = generator(screen)
-        html = @asset_cache.point_framework_links_at_cache(generator.html)
+        screen.asset_swaps = []
+        html = @asset_cache.rewrite(generator.html, overrides: screen.asset_overrides, swaps: screen.asset_swaps)
         @pages[screen] = [html, generator.width, generator.height, @page_server.add(html)]
         show(screen)
       end

data/lib/trmnlp/testing/plugin.rb

@@ -6,6 +6,8 @@ require_relative 'device_models'
 require_relative 'report'
 require_relative 'run'
 require_relative 'screen'
+require_relative '../config/project'
+require_relative '../paths'
 
 module TRMNLP
   module Testing
@@ -58,7 +60,8 @@ module TRMNLP
       # The plugin in another folder, rendered in the same browser: a built copy, say.
       def plugin(dir) = self.class.new(File.expand_path(dir), browser: @browser, authority: @authority)
 
-      def transform(device: 'og_plus', orientation: :landscape, now: nil, **)
+      def transform(device: 'og_plus', orientation: :landscape, now: nil, asset_overrides: {}, **)
+        overrides(asset_overrides)
         device = DeviceModels.find(device, orientation:)
         run(now, **).transform(device: device.render_params).tap { Report.current&.record_run(it) }
       end
@@ -67,19 +70,25 @@ module TRMNLP
       # JavaScript expression the page must reach before it is captured) and wait_for_timeout: (seconds).
       # rubocop:disable-next Metrics/ParameterLists -- one keyword per choice a render offers
       def render(view: 'full', device: 'og_plus', orientation: :landscape, palette: nil, dark_mode: false, theme: nil,
-                 now: nil, head: nil, wait_for: nil, wait_for_timeout: 5, fresh_browser: false, **)
+                 now: nil, head: nil, wait_for: nil, wait_for_timeout: 5, fresh_browser: false,
+                 asset_overrides: {}, **)
         device = DeviceModels.find(device, orientation:, palette:)
         classes = [device.screen_classes, ('screen--dark-mode' if dark_mode)].compact.join(' ')
         result = run(now, **).render(view:, device: device.render_params, screen_classes: classes, theme:)
         html = with_problems_trap(with_head(with_page_clock(result.html, now), head))
         browser = fresh_browser ? @browser.fresh : @browser
         Report.current&.record_run(result)
-        Screen.new(html:, device:, view:, browser:, result:, wait_for:, wait_for_timeout:)
+        Screen.new(html:, device:, view:, browser:, result:, wait_for:, wait_for_timeout:,
+                   asset_overrides: overrides(asset_overrides))
               .tap { Report.current&.record_screen(it) }
       end
 
       private
 
+      def overrides(extra)
+        Config::Project.new(Paths.new(@dir)).asset_overrides(extra, allow_inline: true)
+      end
+
       def run(now, **) = Run.new(plugin: @dir, authority: @authority, now: time(now), **)
 
       def time(value)

data/lib/trmnlp/testing/report.html.erb

@@ -67,6 +67,9 @@
         <% end %></table>
       <% end %>
     <% end %>
+    <% example[:screens].flat_map { it[:asset_swaps] || [] }.each do |swap| %>
+      <div class="run"><%= h(swap[:kind]) %>: <%= h(swap[:url]) %> → <%= h(swap[:target]) %></div>
+    <% end %>
     <div class="screens">
     <% example[:screens].each do |screen| %>
       <figure>

data/lib/trmnlp/testing/report.rb

@@ -40,7 +40,8 @@ module TRMNLP
         remember_full_landscape(screen, image)
         entry[:screens].push(
           label: "#{screen.device.name} · #{screen.view}", width: screen.device.width, height: screen.device.height,
-          image:, outlines: screen.evaluate(OUTLINES_SCRIPT), problems: screen.problems
+          image:, outlines: screen.evaluate(OUTLINES_SCRIPT), problems: screen.problems,
+          asset_swaps: screen.asset_swaps
         )
       end
 

data/lib/trmnlp/testing/rspec.rb

@@ -21,8 +21,9 @@ require_relative 'snapshot'
 module TRMNLP
   module Testing
     PLUGIN_DIR_ENV_KEY = 'TRMNLP_PLUGIN_DIR'
-    # What a template or script draws when its data is missing.
-    LEAKED_TEXT_PATTERN = /Liquid (?:syntax )?error|\bundefined\b|\bNaN\b|\bnull\b|\[object Object\]|\{\{|\{%/
+    # What a page draws when its data or one of its templates is missing.
+    LEAKED_TEXT_PATTERN = Regexp.union(/Missing template|Liquid (?:syntax )?error/,
+                                       /\bundefined\b|\bNaN\b|\bnull\b|\[object Object\]|\{\{|\{%/)
 
     def self.plugin_dir = ENV.fetch(PLUGIN_DIR_ENV_KEY, Dir.pwd)
 

data/lib/trmnlp/testing/screen.rb

@@ -145,10 +145,12 @@ module TRMNLP
         return copy.outerHTML;
       JS
 
-      attr_reader :html, :device, :view, :result, :wait_for, :wait_for_timeout
+      attr_reader :html, :device, :view, :result, :wait_for, :wait_for_timeout, :asset_overrides
+      attr_accessor :asset_swaps
 
       # rubocop:disable-next Metrics/ParameterLists -- what a render produced and how to wait for it
-      def initialize(html:, device:, view:, browser:, result:, wait_for: nil, wait_for_timeout: 5)
+      def initialize(html:, device:, view:, browser:, result:, wait_for: nil, wait_for_timeout: 5,
+                     asset_overrides: {})
         @html = html
         @wait_for = wait_for
         @wait_for_timeout = wait_for_timeout
@@ -156,6 +158,7 @@ module TRMNLP
         @view = view
         @browser = browser
         @result = result
+        @asset_overrides = asset_overrides
         browser.load(self)
         super(Capybara.string(drawn_dom(browser.on(self) { it.execute_script(DRAWN_DOM_SCRIPT) })))
       end

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = '0.31.3'
+  VERSION = '0.32.1'
 end

data/web/public/index.js

@@ -20,6 +20,26 @@ trmnlp.connectLiveRender = function () {
 };
 
 
+// The file watcher cannot see an override served by another URL, such as a bundler's dev server.
+trmnlp.watchOverrides = function () {
+  let bodies = new Map();
+  trmnlp.iframe.addEventListener("load", () => { bodies = new Map(); });
+
+  const poll = async () => {
+    const entries = trmnlp.iframe.contentWindow?.performance?.getEntriesByType("resource") || [];
+    for (const { name } of entries.filter((entry) => new URL(entry.name).pathname.startsWith("/overrides/"))) {
+      const body = await fetch(name, { cache: "no-store" }).then((response) => response.text()).catch(() => null);
+      if (bodies.has(name) && bodies.get(name) !== body) {
+        trmnlp.fetchPreview();
+        break;
+      }
+      bodies.set(name, body);
+    }
+    setTimeout(poll, 1000);
+  };
+  poll();
+};
+
 // trmnl.device values the picked model and palette decide.
 trmnlp.deviceParams = function (state) {
   const bitDepth = Math.ceil(Math.log2(state.palette?.grays || 2));
@@ -274,6 +294,7 @@ document.addEventListener("DOMContentLoaded", async function () {
 
   if (trmnlp.isLiveReloadEnabled) {
     trmnlp.connectLiveRender();
+    trmnlp.watchOverrides();
   }
 
   const formatValue = localStorage.getItem("trmnlp-format") || "html";

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.31.3
+  version: 0.32.1
 platform: ruby
 authors:
 - Rockwell Schrock