trmnl_preview 0.19.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10d19ade9dca541649486f6b8d105277f15400451bbde285591815f4cdc8f9a1
-  data.tar.gz: d83fde4dc7312ec8316027b5f9f6370bca2194228e5ad55dfc92874a260c87d4
+  metadata.gz: d1b736ce74a0385dda5b989fe604d0256d0b1522b1955855aa0eac945ec3dd0b
+  data.tar.gz: f4b4321d72bd9129a025f07d21707f0584e965a5bfe072db3ecc95c2fbf04921
 SHA512:
-  metadata.gz: 25d1251bbb5421d2fe762d46f20ce675d59179e69e42ab44dd6b25ee05dc5bf7609aca22a71bafe77841492b10797aa93153252917078cee61a13b31a2790c59
-  data.tar.gz: 5e1dd277a7aa823e866ca8f2c674751baa04b0e4bcc00b7522064064887eb4c6f246e15f1b3884d8a64fc605005a67c7bc8274364bba7d29bf6fc7739d60def7
+  metadata.gz: 3997799add0b42fd60ffd8f6c7d9d3c99696152fe32316e8925cfe1a24eed73f410a7efc86a432a46697d1fbd7fa0fa44c7d8c63727c48c0ff48778035e993f5
+  data.tar.gz: 12cf46d3ae00fda1f1e82eb80c5ed2bbe2598208ad84de9ecdc878afcb96b51f27e4ed62630195cdb1a0fc60a8d5b6cbc1d6be2f1ef4833aefdc0c370cd1634d

data/CHANGELOG.md

@@ -1,6 +1,38 @@
 
 # Changelog
 
+## 0.21.0
+
+- The `bin/trmnlp` script that `trmnlp init` writes pulls a newer `trmnl/trmnlp` image once a day, so a Docker user stays on the latest release. Before, it ran whatever image was pulled first. The README shows how to install the script as `trmnlp` with Docker alone.
+- The `bin/trmnlp` script that `trmnlp init` writes runs every command in Docker as the gem would. It asked for a terminal it did not have on CI and in scripts (`the input device is not a TTY`), and published port 4567 for every command, so `lint` and `test` failed while `serve` ran and `serve --port` could not be reached. On Linux it runs as you, so snapshots and `_build` are not root's. A plugin's OAuth tokens and saved data are kept between runs, and `CI` and `TRMNL_API_KEY` reach trmnlp. Saved as `trmnlp` on the `PATH`, it no longer starts itself without end. An existing plugin gets the new script from `trmnlp init <its folder>`, answering `y` for `bin/trmnlp` only.
+- The README asks for Ruby >= 4.0 to install the gem, as the gem does. It said 3.4.
+- `trmnlp lint` reports a filter that neither Liquid nor trmnl-liquid defines (`no_unknown_filters`), such as a typo or a LiquidJS filter like `push`. TRMNL outputs the value unfiltered, and `serve` and `build` drew it the same way, so nothing showed the mistake.
+- The Docker image includes geckodriver, so it draws screens on arm64 Linux such as a Raspberry Pi. Selenium downloaded it on every run that draws a screen (`test`, `build`, `serve`), which took about half a second and failed with no network, and on arm64 without x86 emulation it could not download one at all (`Unable to obtain geckodriver`).
+- Every command checks RubyGems for a newer stable release, once a day, and suggests a Gem or Bundler update command on stderr; `trmnlp version` always asks. `--quiet` or `TRMNLP_NO_UPDATE_NOTIFIER=1` skips it, and network failures leave output and exit status unchanged.
+- `have_no_overflow(except: '.forecast')` and `screen.overflowing(except:)` leave out a box that hides content on purpose, and everything inside it.
+
+## 0.20.0
+
+- `trmnlp lint` skips the rules listed under `ignored_lint_rules` in `.trmnlp.yml`, in text and JSON output alike. An unknown rule ID is an error that lists the known ones.
+- `trmnlp lint`, `build` and `serve` accept the `hidden` field type, which TRMNL renders as a hidden input. They warned "unknown field_type: hidden".
+- The README lists `trmnlp test` under Commands, and the guide to testing plugins moved to `docs/testing.md`, with how to share setup through `tests/spec_helper.rb`.
+- `trmnlp test`: `have_qr_code` on an element wholly off the left or top of the screen finds no code. It scanned part of the screen instead, because ImageMagick reads a crop 0 pixels wide as the whole width.
+- `it_behaves_like 'a publishable recipe'` no longer checks overflow. `have_no_overflow` flags text cut short on purpose (`text-overflow: ellipsis`, `-webkit-line-clamp`) on most list and calendar recipes, so authors filtered it out; the matcher stays for examples that call it.
+- `have_no_overflow` passes text cut short on purpose (`text-overflow: ellipsis`, `-webkit-line-clamp`) and text whose font is taller than its line, when only the empty space below it is cut. It reports a box only when a child box or a glyph's ink crosses its edge, so cut descenders still fail, and it now reports a scrolling box (`overflow: auto` or `scroll`) whose content is cut.
+- `have_no_problems` ignores Firefox's "ResizeObserver loop completed with undelivered notifications", which it raises when a ResizeObserver resizes what it observes, as FullCalendar does. Browsers report it as a page error, but nothing is broken.
+- `it_behaves_like 'a publishable recipe'` also uses the group's `variables` (for Plugin Merge recipes) and `now` when the group defines them. It passed only `mocks` and `custom_fields`, so such a recipe was drawn without its variables and on the real clock.
+- `trmnlp test`: under `now:`, the page's clock starts at `now:` when the page runs. It started seconds late, by however long Firefox took to load the page. `Date()` without `new` no longer throws, and `Intl.DateTimeFormat#format` and `#formatToParts` given no date use `now:`.
+- `trmnlp test --report` writes a report per process under parallel_tests (`report`, `report2`, ...) instead of each process overwriting the last. The README shows how to run a plugin's tests in parallel.
+- `serve`, `build` and `test` skip resizing the page when it is already the size asked for, and check a resize every 0.01 s instead of 0.1 s. About 0.04 s faster a render.
+- The bundled list of Framework versions goes up to 3.4.0, so offline, `trmnlp build` and `serve` no longer warn that a plugin pinned to 3.3.0 or later is not a published version. A release refreshes the list before it builds the gem.
+- The `qr_code` filter draws a white border four modules wide inside the code's box, so it scans in dark mode and on a dark page. The box keeps its size and the modules shrink to make room.
+- `trmnlp test`: `data:` reaches a static plugin. It was ignored there, so the test rendered the `static_data` in `settings.yml`.
+- `trmnlp test` takes a screen's PNG only when a test asks for it (`match_snapshot`, `fit_image_size_limit`, `png_path`, `--report`). A test that only reads the page no longer waits for the screenshot and its quantizing, about 0.15 seconds a render. The picture is of the page when it is first asked for, so a page changed with `evaluate` before `match_snapshot` is drawn changed.
+- `trmnlp test` opens each page from a local address instead of writing it into `about:blank` with its stylesheets inlined, so Firefox parses the Framework's 15 MB stylesheet once for the run: 10 renders take 5.5 seconds where they took 10.1, and trmnlp's own suite 89 seconds where it took 114. The page still gets no storage, cookies or `Referer`, as on TRMNL. Its `location` and the `Origin` of its cross-origin requests are `http://127.0.0.1:<port>`, and a relative URL is not found. (#193)
+- Every screenshot is 0.1 to 0.2 s faster, in `test`, `build` and `serve`. Stopping the page's timers before the capture cleared 100,000 timer ids one by one; it now clears only the ids the page has used.
+- A font file that never arrives no longer hangs a render until WebDriver's 30 second limit (`Selenium::WebDriver::Error::ScriptTimeoutError: Timed out after 30000 ms`), in `test`, `build` and `serve`. The page is given 10 seconds for its fonts, loaded once more, and then fails with the names of the fonts still loading.
+- `have_qr_code` checks that a QR code scans in a screen's PNG, and with a String or Regexp what it reads; `within:` scans one element and `screen.qr_codes` lists every text. It uses zbar, which the Docker image now includes.
+
 ## 0.19.0
 
 - `it_behaves_like 'a publishable recipe'` also checks every screen for leaked values (`undefined`, `NaN`, `null`, `[object Object]`, `Liquid error`, raw `{{` or `{%`), draws the full view when the API answers with nothing, answers 500 or cannot be reached, and draws it with each option of every select field. New matchers: `have_no_leaked_text` and `have_no_transform_error`. (#181)

data/README.md

@@ -90,6 +90,7 @@ trmnlp push                    # upload
 | `trmnlp serve` | Start a local dev server |
 | `trmnlp build` | Generate static HTML files, or PNGs with `--png` |
 | `trmnlp lint` | Check plugin code against TRMNL best practices |
+| `trmnlp test` | Run the plugin's tests in `tests/` |
 | `trmnlp login` | Authenticate with TRMNL server |
 | `trmnlp list` | List private plugins from TRMNL server |
 | `trmnlp clone NAME ID` | Copy a plugin project from TRMNL server |
@@ -99,6 +100,17 @@ trmnlp push                    # upload
 
 `trmnlp lint` exits non-zero when it finds issues, so you can gate CI on it. Run `trmnlp help` for all flags.
 
+Every command also checks RubyGems for a newer stable `trmnl_preview` release
+and, when one is available, suggests `gem update trmnl_preview`, or
+`bundle update trmnl_preview` when run through Bundler. An exact Gemfile pin must
+be changed before Bundler can update it. Notices go to stderr, keeping lint JSON
+output and exit status unchanged. The answer is cached for a day, so most runs
+make no request; `trmnlp version` always asks RubyGems. `--quiet` or
+`TRMNLP_NO_UPDATE_NOTIFIER=1` skips the check. Connection and read timeouts are
+two seconds each; current versions and an unavailable registry stay silent. The
+check never installs an update or changes your Gemfile or lockfile. Inside Docker there is no
+check: the `bin/trmnlp` script pulls a newer image once a day instead.
+
 Lint findings include a stable snake_case rule ID, severity and source locations.
 Locations use project-relative paths and one-based line/column numbers, followed
 by a source excerpt (up to 240 characters). Aggregate checks show their contributing
@@ -122,6 +134,12 @@ Liquid in declaration values is counted without rendering the plugin, every bran
 Filters from `custom_filters` in `.trmnlp.yml` exist only in trmnlp. TRMNL does not load them
 and outputs the value unfiltered, so `no_custom_filters` reports each place the markup uses one.
 Filters that trmnl-liquid also provides are not reported.
+A filter that neither Liquid nor trmnl-liquid defines, such as a typo or one from another
+Liquid (Jekyll, LiquidJS), is also output unfiltered on TRMNL, so `no_unknown_filters` reports it.
+
+To accept a rule's findings, list its rule ID under `ignored_lint_rules` in `.trmnlp.yml`.
+`trmnlp lint` then skips that check in both formats, so the CLI and CI agree. An unknown
+rule ID is an error that lists the known ones, so a typo does not pass quietly.
 
 ## Building Static Files
 
@@ -209,13 +227,13 @@ The `bin/trmnlp` script is provided as a convenience. It will use the local Ruby
 
 You can modify the `bin/trmnlp` script to set up environment variables (plugin secrets, etc.) before running the server.
 
-**Gem or Docker?** Install the gem if you already have Ruby >= 3.4 — it has the fastest startup. Use Docker for zero local setup.
+**Gem or Docker?** Install the gem if you already have Ruby >= 4.0 — it has the fastest startup. Use Docker for zero local setup.
 
 ### Installing via RubyGems
 
 Prerequisites:
 
-- Ruby >= 3.4
+- Ruby >= 4.0
 - For PNG rendering (optional):
   - Firefox
   - ImageMagick
@@ -227,6 +245,20 @@ trmnlp serve
 
 ### Installing via Docker
 
+To type `trmnlp` as with the gem, copy the script from the image onto your `PATH`:
+
+```sh
+mkdir -p ~/.local/bin
+docker run --rm --entrypoint cat trmnl/trmnlp /app/templates/init/bin/trmnlp > ~/.local/bin/trmnlp
+chmod +x ~/.local/bin/trmnlp
+```
+
+It runs each command in the image and pulls a newer image once a day. To stay on one release,
+set `IMAGE` in the script to a tag such as `trmnl/trmnlp:v0.20.0`. `trmnlp init` puts the same
+script in each plugin as `bin/trmnlp`.
+
+Or run the image yourself:
+
 ```sh
 docker run \
     --pull always \
@@ -338,6 +370,10 @@ variables:
     plugin_settings:
       instance_name: Kevin Bacon Facts
 
+# rule IDs whose findings `trmnlp lint` drops
+ignored_lint_rules:
+  - no_opacity
+
 # plugin_merge strategy: the plugins this one reads, as "<keyname>_<id>" on TRMNL,
 # each mapped to the trmnlp project whose last fetched data stands in for it
 merged_plugins:
@@ -473,40 +509,7 @@ See [TRMNL documentation](https://help.trmnl.com/en/articles/10542599-importing-
 
 ## Testing Plugins
 
-`trmnlp init` starts a plugin with `tests/plugin_spec.rb` (`it_behaves_like 'a publishable recipe'`, below) and a GitHub workflow that runs it in the `trmnl/trmnlp` image, uploads the report, can rewrite the snapshots on a manual run, and pushes to TRMNL only once lint and tests pass. `trmnlp test` runs the RSpec files in your plugin's `tests/` folder, through the same pipeline `serve` and `build` use, with fake APIs and a fixed clock:
-
-```ruby
-# tests/weather_spec.rb
-RSpec.describe 'Weather' do
-  let(:mocks) { { 'https://api.weather.example/*' => { json: { temp: 12 } } } }
-
-  %w[og_plus v2].each do |device|
-    it "shows the temperature on #{device}" do
-      screen = trmnl.render(device:, now: '2030-01-02T08:00:00Z', custom_fields: { city: 'Amsterdam' }, mocks:)
-
-      expect(screen).to have_text('12°')
-      expect(screen).to have_no_overflow
-      expect(screen.box('.title').bottom).to be <= screen.box('.content').top
-      expect(screen).to match_snapshot
-    end
-  end
-
-  it 'keeps its state when the API has nothing new' do
-    run = trmnl.transform(state: { etag: 'abc' }, mocks: { 'https://api.weather.example/*' => { status: 304 } })
-
-    expect(run.state).to eq('etag' => 'abc')
-  end
-end
-```
-
-- `trmnl.transform(...)` runs the transform and answers `data`, `state`, `requests`, `log`, `error`, `duration_ms` and `max_memory_mb`; `expect(run).to stay_within_serverless_limits` checks TRMNL's 5 seconds and 128 MB. `trmnl.render(view: 'full', ...)` renders a view in Firefox and answers a screen: Capybara's matchers (`have_text`, `have_css`, `within`...) see what is drawn, and `box(selector)`, `evaluate(js)`, `overflowing` and `problems` (script errors, unhandled rejections, `console.error` and files that failed to load; `have_no_problems`) ask the live page; `fresh_browser: true` renders in a new Firefox with nothing cached; `screen.result` holds the run's `data`, `state` and `requests`. `trmnl.plugin(dir)` tests the plugin in another folder, such as a built copy.
-- Inputs, all optional: `device:` (a TRMNL model name, or `{ width:, height:, bit_depth: }`), `palette:`, `orientation: :portrait`, `dark_mode:`, `theme:`, `now:`, `custom_fields:`, `variables:`, `state:`, `previous_merge_variables:`, `data:` (skips polling), `transform: false`. A test's `custom_fields` and `variables` replace those in `.trmnlp.yml`, so development values there never reach a test; the field defaults in `settings.yml` still apply, as on TRMNL.
-- A board drawn by its own script takes `head:` (markup added to the page's `<head>`) and `wait_for:` (a JavaScript expression the page must reach before it is captured, within `wait_for_timeout:` seconds); without it, the capture freezes timers once TRMNL's readiness flags are set.
-- `mocks:` answer every request the run makes: polling urls, and the transform's own requests in any language, HTTPS included. Keys are urls, with `*` wildcards, a Regexp, or a method first (`'POST https://...'`). Values are `{ json:, body:, status:, headers:, delay:, body_delay:, advance_clock:, error: :reset }` (times in seconds: `body_delay:` sends the headers first and the body later, `advance_clock:` moves the transform's clock on when it answers), a string body, a lambda that takes the request, or an array of answers used in order. An unmocked request gets a 599. `requests` lists every request with its `status`, and `aborted: true` for one the transform gave up on before its answer arrived; `duration_ms` is how long the transform ran.
-- `now:` starts every clock: Liquid's, the markup's scripts', and the transform's, through libfaketime (`brew install libfaketime` or `apt-get install libfaketime`; already in the Docker image). On macOS the interpreter must come from brew, mise or similar, since macOS will not hand libfaketime to its own `/usr/bin` binaries.
-- `trmnlp test --report report` also writes `report/index.html` and `report/report.json`: every example with each screen it rendered (with a switch that outlines every drawn box, and the page's problems) and each transform it ran (time, memory, requests). Under GitHub Actions the counts and failures go to the run's summary too.
-- `it_behaves_like 'a publishable recipe'` is what a recipe should hold before it is published: every view draws without overflow or page errors on the TRMNL OG (1-bit, and 2-bit in landscape and portrait) and the TRMNL X (landscape and portrait), and the transform runs without error within TRMNL's limits. Every screen is also checked for leaked values (`undefined`, `NaN`, `null`, `[object Object]`, `Liquid error`, raw `{{`); the full view must still draw when the API answers with nothing, answers 500 or cannot be reached; and it is drawn with each option of every select field (the first and last when a field has more than 20). It uses the group's `mocks` and `custom_fields` when the group defines them; `screens: [{ device: 'kobo_libra_2' }, ...]` draws on other devices.
-- `match_snapshot` stores a missing snapshot under `tests/snapshots/<os>/` and fails one on CI; `trmnlp test --update` rewrites them. Fonts render differently per operating system, so run tests in the Docker image when CI should share your snapshots. `fit_image_size_limit` checks the PNG against the model's limit, `have_no_leaked_text` the drawn text for leaked values, and `have_no_transform_error` a render's transform.
+`trmnlp test` runs the RSpec files in your plugin's `tests/` folder through the same pipeline `serve` and `build` use, with fake APIs and a fixed clock. `trmnlp init` starts a plugin with a test and a GitHub workflow that runs it. See [Testing Plugins](https://github.com/usetrmnl/trmnlp/blob/main/docs/testing.md) for the API, the matchers, snapshots and running tests in parallel.
 
 ## Development
 

data/db/data/form_fields.yml

@@ -19,6 +19,7 @@ field_types:
   - copyable_webhook_url
   - date
   - google_photos_picker
+  - hidden
   - json
   - lat_lon
   - modal_trigger

data/db/data/framework_versions.yml

@@ -1,6 +1,6 @@
 # Mirrored from the TRMNL design-system source.
 # Refresh with `rake framework:sync` — do not edit manually.
-latest: 3.2.0
+latest: 3.4.0
 versions:
 - number: 0.0.1
   released_at: '2024-06-22'
@@ -86,3 +86,11 @@ versions:
   released_at: '2026-07-23'
 - number: 3.2.0
   released_at: '2026-08-05'
+- number: 3.3.0
+  released_at: '2026-08-27'
+- number: 3.3.1
+  released_at: '2026-09-01'
+- number: 3.3.2
+  released_at: '2026-09-18'
+- number: 3.4.0
+  released_at: '2026-09-28'

data/lib/trmnlp/cli.rb

@@ -4,6 +4,8 @@ require 'thor'
 
 require_relative '../trmnlp'
 require_relative '../trmnlp/commands'
+require_relative 'paths'
+require_relative 'update_check'
 
 module TRMNLP
   class CLI < Thor
@@ -22,6 +24,23 @@ module TRMNLP
     def self.in_container? = File.exist?('/.dockerenv') || File.exist?('/run/.containerenv')
     def self.default_bind = in_container? ? '0.0.0.0' : '127.0.0.1'
 
+    no_commands do
+      # Thor routes every command through here, so the update notice covers
+      # them all without each command having to remember it. `version` runs
+      # its own fresh check after printing, and help has nothing to update.
+      def invoke_command(command, *)
+        check_for_update unless %w[help version].include?(command.name)
+        super
+      end
+
+      def check_for_update(fresh: false)
+        # In a container `gem update` does not apply; bin/trmnlp pulls a newer image instead.
+        return if options[:quiet] || UpdateCheck.disabled? || self.class.in_container?
+
+        UpdateCheck.new(Paths.new(options[:dir]).update_check).call(fresh:)
+      end
+    end
+
     desc 'build', 'Generate static HTML files'
     method_option :png, type: :boolean, default: false, desc: 'Also render a PNG per view'
     method_option :width, type: :numeric, desc: 'PNG width in pixels (with --png)'
@@ -96,6 +115,9 @@ module TRMNLP
     desc 'version', 'Show version'
     def version
       puts VERSION
+      # Keep the version first when stdout is a pipe and stderr is not.
+      $stdout.flush
+      check_for_update(fresh: true)
     end
   end
 end

data/lib/trmnlp/commands/lint.rb

@@ -24,12 +24,23 @@ module TRMNLP
       private
 
       def issues
-        @issues ||= TRMNLP::Lint::CHECKS.flat_map do |type|
+        @issues ||= checks.flat_map do |type|
           check = type.new(source)
           check.issues.map { |finding| TRMNLP::Lint::Diagnostic.new(check, source, finding).to_h }
         end.uniq
       end
 
+      def checks
+        checks_by_rule_id = TRMNLP::Lint::CHECKS.to_h { |type| [TRMNLP::Lint.rule_id(type), type] }
+        unknown_rule_ids = config.project.ignored_lint_rules - checks_by_rule_id.keys
+        unless unknown_rule_ids.empty?
+          raise InvalidConfig, ".trmnlp.yml ignored_lint_rules has unknown rule IDs: #{unknown_rule_ids.join(', ')}. " \
+                               "Known rule IDs: #{checks_by_rule_id.keys.join(', ')}"
+        end
+
+        checks_by_rule_id.except(*config.project.ignored_lint_rules).values
+      end
+
       def source
         @source ||= TRMNLP::Lint::Source.new(config:, paths:)
       end

data/lib/trmnlp/config/project.rb

@@ -54,6 +54,8 @@ module TRMNLP
 
       def time_zone = @config['time_zone'] || 'UTC'
 
+      def ignored_lint_rules = Array(@config['ignored_lint_rules'])
+
       # Local override for the framework asset host (offline / mirrored
       # dev). Trmnlp-specific (local dev only) — so it stays in
       # .trmnlp.yml. Consumed by Config::Plugin#framework_version.

data/lib/trmnlp/context.rb

@@ -18,12 +18,13 @@ module TRMNLP
     # The keywords after reporter let `trmnlp test` run the real pipeline with a test's inputs.
     # rubocop:disable-next Metrics/ParameterLists -- the composition root takes what it wires
     def initialize(root_dir, reporter: Reporter.new, cache_dir: nil, project_overrides: {}, outbound_request: nil,
-                   transform_client: nil)
+                   transform_client: nil, source_data: nil)
       @paths = Paths.new(root_dir, cache_dir:)
       @config = Config.new(paths, project_overrides:)
       @reporter = reporter
       @outbound_request = outbound_request
       @transform_client = transform_client
+      @source_data = source_data
     end
 
     # Context is the composition root: it wires and memoizes the runtime
@@ -51,7 +52,8 @@ module TRMNLP
     end
 
     def user_data_assembler
-      @user_data_assembler ||= UserDataAssembler.new(config:, paths:, transform_pipeline:, oauth_session:)
+      @user_data_assembler ||= UserDataAssembler.new(config:, paths:, transform_pipeline:, oauth_session:,
+                                                     source_data: @source_data)
     end
 
     def renderer = @renderer ||= Renderer.new(config:, paths:, user_data_assembler:)

data/lib/trmnlp/firefox_driver.rb

@@ -18,6 +18,9 @@ module TRMNLP
       Selenium::WebDriver::Firefox::Options.new(web_socket_url: true).tap do |opts|
         opts.add_argument('--headless')
         opts.add_argument('--disable-web-security')
+        # A page trmnlp test serves from 127.0.0.1 gets no storage, cookies or Referer, as on TRMNL's about:blank.
+        opts.add_preference('network.cookie.cookieBehavior', 2)
+        opts.add_preference('network.http.sendRefererHeader', 0)
       end
     end
   end

data/lib/trmnlp/lint/checks/no_unknown_filters.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'trmnl/liquid'
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports markup that uses a filter neither Liquid nor trmnl-liquid defines, such
+      # as a typo or a filter from another Liquid (Jekyll, LiquidJS). TRMNL does not fail
+      # on one: it outputs the value unfiltered. custom_filters are no_custom_filters' to report.
+      class NoUnknownFilters < Check
+        def issues
+          unknown_filter_names.map do |name|
+            { message: "Filter '#{name}' is not a Liquid or TRMNL filter. TRMNL outputs the value unfiltered; " \
+                       'check the name, or use a built-in filter or the transform instead.' }
+          end
+        end
+
+        private
+
+        def unknown_filter_names
+          used_filter_names - environment.filter_method_names - source.local_only_filter_names
+        end
+
+        def used_filter_names = source.markup_files.values.flat_map { filter_names(it) }.uniq
+
+        # Liquid's own parse, so a pipe in a string or a raw block is not taken for a filter.
+        def filter_names(markup)
+          names = []
+          template = ::Liquid::Template.parse(markup, environment:)
+          ::Liquid::ParseTreeVisitor.for(template.root)
+                                    .add_callback_for(::Liquid::Variable) { names.concat(it.filters.map(&:first)) }
+                                    .visit
+          names
+        rescue ::Liquid::SyntaxError
+          [] # A template that does not parse fails to render, which says so.
+        end
+
+        # trmnl-liquid's template tag keeps its body as a String, which ParseTreeVisitor cannot walk.
+        def environment = @environment ||= TRMNL::Liquid.new { it.register_tag 'template', ::Liquid::Block }
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -33,9 +33,7 @@ module TRMNLP
 
       attr_reader :check, :source, :finding
 
-      def rule_id
-        check.class.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
-      end
+      def rule_id = Lint.rule_id(check.class)
 
       def locations
         return source.yaml_location('src/settings.yml', SETTINGS_KEYS[rule_id]) if SETTINGS_KEYS.key?(rule_id)
@@ -46,7 +44,7 @@ module TRMNLP
         when 'layouts_have_content' then empty_view_locations
         when 'form_fields_valid' then form_field_locations
         when 'custom_fields_used' then project_field_locations
-        when 'no_custom_filters' then custom_filter_locations
+        when 'no_custom_filters', 'no_unknown_filters' then filter_locations
         when 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
         else []
         end
@@ -57,7 +55,7 @@ module TRMNLP
         css_class ? source.locations(Regexp.new(Regexp.escape(css_class))) : []
       end
 
-      def custom_filter_locations
+      def filter_locations
         source.locations(Checks::NoCustomFilters.usage_pattern(finding[:message][/Filter '([^']+)'/, 1]))
       end
 

data/lib/trmnlp/lint.rb

@@ -19,6 +19,7 @@ require_relative 'lint/checks/image_links_reachable'
 require_relative 'lint/checks/custom_fields_used'
 require_relative 'lint/checks/form_fields_valid'
 require_relative 'lint/checks/no_custom_filters'
+require_relative 'lint/checks/no_unknown_filters'
 
 module TRMNLP
   # Markup best-practice checks behind `trmnlp lint`.
@@ -41,7 +42,10 @@ module TRMNLP
       Checks::ImageLinksReachable,
       Checks::CustomFieldsUsed,
       Checks::FormFieldsValid,
-      Checks::NoCustomFilters
+      Checks::NoCustomFilters,
+      Checks::NoUnknownFilters
     ].freeze
+
+    def self.rule_id(check_type) = check_type.name.split('::').last.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
   end
 end

data/lib/trmnlp/paths.rb

@@ -55,6 +55,9 @@ module TRMNLP
 
     def transform_output = cache_dir.join('transform_output', "#{project_key}.json")
 
+    # One file for every project: the published gem version is not per project.
+    def update_check = cache_dir.join('update_check.json')
+
     def render_template = Pathname.new(__dir__).join('..', '..', 'web', 'views', 'render_html.erb')
 
     def src_files = src_dir.glob('*').select(&:file?)

data/lib/trmnlp/qr_code.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'trmnl/liquid'
+
+module TRMNLP
+  # Mirrors core's config/initializers/trmnl_liquid_qr_code.rb: a white quiet zone inside the code's size.
+  module QrCode
+    QUIET_ZONE_MODULES = 4
+
+    def qr_code(data, size = 11, level = '', view = 'responsive')
+      svg = super
+      side_length = svg[/<rect width="(\d+)"/, 1]
+      return svg unless side_length
+
+      border = size * QUIET_ZONE_MODULES
+      box = side_length.to_i + (2 * border)
+      sizing = %(width="#{side_length}" height="#{side_length}")
+      sizing += ' style="max-width:100%;height:auto"' if view == 'responsive'
+      svg.sub(/ (?:viewBox="[^"]*"|width="\d+" height="\d+")/, '')
+         .sub('<svg ', %(<svg #{sizing} viewBox="-#{border} -#{border} #{box} #{box}" ))
+         .sub(%r{<rect [^>]*?(?=/>)}, %(<rect width="#{box}" height="#{box}" x="-#{border}" y="-#{border}" fill="#fff"))
+    end
+  end
+end
+
+TRMNL::Liquid::Filters.prepend(TRMNLP::QrCode)

data/lib/trmnlp/screen_generator.rb

@@ -24,18 +24,20 @@ module TRMNLP
       @requested_color_depth = opts[:color_depth]
     end
 
+    # The page as it is shown: chart libraries swapped for TRMNL's copies.
+    def html = CHART_LIBRARIES.reduce(@input) { |page, (from, to)| page.gsub(from, to) }
+
     def process
-      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
 
-    private
-
     def width = @requested_width || 800
     def height = @requested_height || 480
 
+    private
+
     def color_depth
       return @requested_color_depth if @requested_color_depth
       return ::Regexp.last_match(1).to_i if @input&.match(/screen--(\d+)bit/)

data/lib/trmnlp/screenshot.rb

@@ -15,21 +15,29 @@ module TRMNLP
       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.
+    # A font file that never arrives would keep the page waiting until WebDriver's own 30 second limit.
+    FONTS_TIMEOUT_SECONDS = 10
+    FONTS_LOADED_SCRIPT = "return !document.fonts || document.fonts.status === 'loaded'"
+    FONTS_LOADING_SCRIPT =
+      "return [...document.fonts].filter((font) => font.status === 'loading').map((font) => font.family)"
+    # Stops timers and animation callbacks from changing the page mid-capture. A window numbers its timeouts
+    # and intervals upward from one counter, so a new timer's id is the highest there is to clear.
     FREEZE_TIMERS = <<~JS
       const noop = () => 0;
+      const newest = window.setTimeout(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); }
+      for (let i = typeof newest === 'number' ? newest : 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)
+    def initialize(pool:, viewport_timeout: 5, fonts_timeout: FONTS_TIMEOUT_SECONDS)
       @pool = pool
       @viewport_timeout = viewport_timeout
+      @fonts_timeout = fonts_timeout
     end
 
     def call(html:, width:, height:)
@@ -48,9 +56,10 @@ module TRMNLP
     # Loads html into driver at width x height and waits until TRMNL would capture it, and until wait_for
     # (a JavaScript expression) is true when given: a page still drawing would be stopped by the frozen timers.
     # rubocop:disable-next Metrics/ParameterLists -- the page, its size, and what to wait for
-    def show(driver, html, width, height, wait_for: nil, wait_for_timeout: READINESS_TIMEOUT_SECONDS)
+    # url: an address that serves html, opened in place of writing html into a blank page.
+    def show(driver, html, width, height, wait_for: nil, wait_for_timeout: READINESS_TIMEOUT_SECONDS, url: nil)
       resize(driver, width, height)
-      load_page(driver, html) { wait_for_expression(driver, wait_for, wait_for_timeout) if wait_for }
+      load_page(driver, html, url:) { wait_for_expression(driver, wait_for, wait_for_timeout) if wait_for }
     end
 
     def capture(driver)
@@ -68,6 +77,8 @@ module TRMNLP
     end
 
     def resize(driver, width, height)
+      return if viewport(driver) == [width, height]
+
       set_viewport(driver, width, height)
       wait_for_viewport(driver, width, height)
     end
@@ -82,7 +93,7 @@ module TRMNLP
     # clipped the first screenshot short (800x433 instead of 800x480). Poll the
     # real viewport instead, re-applying the size until it lands.
     def wait_for_viewport(driver, width, height)
-      Selenium::WebDriver::Wait.new(timeout: @viewport_timeout, interval: 0.1).until do
+      Selenium::WebDriver::Wait.new(timeout: @viewport_timeout, interval: 0.01).until do
         next true if viewport(driver) == [width, height]
 
         set_viewport(driver, width, height)
@@ -97,24 +108,41 @@ module TRMNLP
       driver.execute_script('return [window.innerWidth, window.innerHeight]')
     end
 
-    def load_page(driver, html)
-      driver.navigate.to('about:blank')
+    # A font that stalls is usually a dropped connection, so the page is loaded once more before giving up.
+    def load_page(driver, html, url: nil, &)
+      attempts = 0
+      begin
+        open_page(driver, html, url, &)
+      rescue Selenium::WebDriver::Error::TimeoutError
+        retry if (attempts += 1) <= 1
+        loading = driver.execute_script(FONTS_LOADING_SCRIPT).uniq.join(', ')
+        raise RenderError, "The page's fonts did not load within #{@fonts_timeout}s: #{loading}"
+      end
 
-      driver.execute_script(<<~JS, html)
-        document.open();
-        document.write(arguments[0]);
-        document.close();
+      driver.execute_script(<<~JS)
+        document.documentElement.style.overflow = 'hidden';
+        document.body.style.overflow = 'hidden';
       JS
+      driver.execute_script(FREEZE_TIMERS)
+    end
+
+    def open_page(driver, html, url)
+      url ? driver.navigate.to(url) : write_page(driver, html)
 
       wait_until_ready(driver, html)
       yield if block_given?
-      driver.execute_script('return document.fonts && document.fonts.ready')
+      Selenium::WebDriver::Wait.new(timeout: @fonts_timeout, interval: 0.05)
+                               .until { driver.execute_script(FONTS_LOADED_SCRIPT) }
+    end
 
-      driver.execute_script(<<~JS)
-        document.documentElement.style.overflow = 'hidden';
-        document.body.style.overflow = 'hidden';
+    def write_page(driver, html)
+      driver.navigate.to('about:blank')
+
+      driver.execute_script(<<~JS, html)
+        document.open();
+        document.write(arguments[0]);
+        document.close();
       JS
-      driver.execute_script(FREEZE_TIMERS)
     end
 
     def wait_for_expression(driver, expression, timeout)