trmnl_preview 0.27.0 → 0.29.0

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Small gray text dithers into dots on a 1-bit screen, so it needs a 1bit: class
+      # (1bit:text--black, or 1bit:text--white on a black panel) on the same element.
+      class GrayTextHasOneBitClass < Check
+        SMALL = /\A(?:label|text|description)--x?small\z/
+        GRAY = /\A(?:text--gray(?:-\d+)?|label--gray)\z/
+        LEARN_MORE = 'https://trmnl.com/framework/docs/3.4/text_color'
+
+        def issues
+          offending_elements.map { |_, element| self.class.class_list(element) }.uniq.map do |classes|
+            { message: "'#{classes}' is small gray text with no 1bit: class, so it breaks up " \
+                       'into dots on 1-bit screens. Add 1bit:text--black (1bit:text--white on a black background).',
+              learn_more: LEARN_MORE }
+          end
+        end
+
+        def offending_elements
+          @offending_elements ||= source.html_fragments.flat_map do |path, fragment|
+            fragment.css('[class]').select { small_gray_without_one_bit?(it['class'].split) }.map { [path, it] }
+          end
+        end
+
+        def self.class_list(element) = element['class'].split.join(' ')
+
+        private
+
+        def small_gray_without_one_bit?(classes)
+          classes.any?(SMALL) && classes.any?(GRAY) && classes.none? { it.start_with?('1bit:') }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports a custom field that sets how often the content changes. The refresh rate and the
+      # playlist already decide that, so the field repeats them. A field must both be named for
+      # it (rotation, refresh, new …) and offer intervals, so data such as "collected every 2 weeks" passes.
+      class NoRefreshRateField < Check
+        NAME = /rotat|refresh|frequen|interval|how often|\bnew\b|\bnext\b/i
+        INTERVAL_OPTION = /\A(?:daily|hourly|(?:once|twice|\d+\stimes)\s(?:a|per)\s(?:day|hour)|
+                           every\s(?:\d+\s)?(?:minute|hour|day)s?|\d+\s*(?:minutes?|mins?|hours?|hrs?)\b)/ix
+        TIME_UNIT = /\b(?:minutes?|hours?)\b/i
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/11395668-recipe-best-practices'
+
+        def issues
+          offending_fields.map do |field|
+            { message: "Form field '#{field['keyname']}' sets how often the content changes. Remove it and let " \
+                       'the refresh rate and the playlist decide.', learn_more: LEARN_MORE }
+          end
+        end
+
+        def offending_fields = source.custom_field_definitions.select { refresh_rate_field?(it) }
+
+        private
+
+        def refresh_rate_field?(field)
+          return false unless "#{field['keyname'].to_s.tr('_', ' ')} #{field['name']}".match?(NAME)
+
+          case field['field_type']
+          when 'select' then interval_options?(field['options'])
+          when 'number', 'string' then [field['keyname'], field['name'],
+                                        field['description']].join(' ').match?(TIME_UNIT)
+          else false
+          end
+        end
+
+        def interval_options?(options)
+          labels = Array(options).map { it.is_a?(Hash) ? it.keys.first.to_s : it.to_s }
+          labels.count { it.match?(INTERVAL_OPTION) } >= 2
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports <style> rules that redo what the framework does across screens: fixed font
+      # sizes (no lg: scaling), hand-written line clamping and orientation reflows. CSS for
+      # art, charts and SVG text is left alone.
+      class NoStyleRestylingFramework < Check
+        STYLE_BLOCK = %r{<style\b[^>]*>(.*?)</style>}mi
+        RULE = /([^{}]*)\{([^{}]*)\}/
+        FIXED_FONT_SIZE = /font-size\s*:\s*[\d.]+\s*(?:px|pt)\b/i
+        SVG_OR_CHART = /(?:\A|[\s>+~,])(?:svg|text|tspan)\b|highcharts|chart/i
+        KINDS = {
+          font_size: ['A <style> block sets font-size in px or pt, so the text keeps one size on every screen. ' \
+                      'Use the element sizes (label, value, description, title) with lg: steps.',
+                      'https://trmnl.com/framework/docs/3.4/element_sizes'],
+          line_clamp: ['A <style> block clamps lines with -webkit-line-clamp. Use data-clamp="N" on the element.',
+                       'https://trmnl.com/framework/docs/3.4/clamp'],
+          orientation: ['A <style> block reflows with @media (orientation …). ' \
+                        'Use the portrait: and lg:portrait: prefixes.',
+                        'https://trmnl.com/framework/docs/3.4/responsive']
+        }.freeze
+
+        def issues
+          occurrences.keys.map { |kind| { message: KINDS[kind][0], learn_more: KINDS[kind][1] } }
+        end
+
+        # kind => [[path, offset], ...] for each place in a <style> block.
+        def occurrences
+          @occurrences ||= places.group_by(&:first).transform_values { it.map { |_, path, offset| [path, offset] } }
+        end
+
+        private
+
+        def places
+          source.markup_files.flat_map do |path, markup|
+            markup.to_enum(:scan, STYLE_BLOCK).flat_map do
+              start = Regexp.last_match.begin(1)
+              style_block_offsets(Regexp.last_match(1)).map { |kind, offset| [kind, path, start + offset] }
+            end
+          end
+        end
+
+        def style_block_offsets(css)
+          offsets = css.to_enum(:scan, RULE).filter_map do
+            selector, declarations = Regexp.last_match.captures
+            next if selector.match?(SVG_OR_CHART) || !declarations.match?(FIXED_FONT_SIZE)
+
+            [:font_size, Regexp.last_match.begin(2) + declarations.index(FIXED_FONT_SIZE)]
+          end
+          offsets + pattern_offsets(css, /-webkit-line-clamp/i, :line_clamp) +
+            pattern_offsets(css, /@media[^{]*orientation/i, :orientation)
+        end
+
+        def pattern_offsets(css, pattern, kind) = css.to_enum(:scan, pattern).map { [kind, Regexp.last_match.begin(0)] }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../check'
+
+module TRMNLP
+  module Lint
+    module Checks
+      # Reports a select option written as one quoted string, 'Voyager 1: voyager1'. TRMNL reads
+      # a string option as a label and saves it lowercased with spaces as underscores, so the
+      # value the markup sees is 'voyager_1:_voyager1'. Unquoted, YAML makes it a label and a value.
+      class SelectOptionsSplitLabelAndValue < Check
+        LABEL_AND_VALUE = /\A[^:]+:\s+\S/
+        LEARN_MORE = 'https://help.trmnl.com/en/articles/10513740-custom-plugin-form-builder'
+
+        def issues
+          split_options.map do |field_index, option_index|
+            field = source.custom_field_definitions[field_index]
+            option = field['options'][option_index]
+            { message: "Form field '#{field['keyname']}' has the option '#{option}' as one string, so TRMNL saves " \
+                       "'#{option.downcase.tr(' ', '_')}'. Write it as 'Label': value to save the value.",
+              learn_more: LEARN_MORE }
+          end
+        end
+
+        # [field index, option index] of the first such option in each select field.
+        def split_options
+          source.custom_field_definitions.each_with_index.filter_map do |field, field_index|
+            options = field['options']
+            next unless field['field_type'] == 'select' && options.is_a?(Array)
+
+            option_index = options.index { |option| option.is_a?(String) && option.match?(LABEL_AND_VALUE) }
+            [field_index, option_index] if option_index
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trmnlp/lint/diagnostic.rb

@@ -37,6 +37,7 @@ module TRMNLP
 
       def rule_id = Lint.rule_id(check.class)
 
+      # rubocop:disable-next Metrics/CyclomaticComplexity -- one branch per rule that locates its own findings
       def locations
         return source.yaml_location('src/settings.yml', SETTINGS_KEYS[rule_id]) if SETTINGS_KEYS.key?(rule_id)
         return source.locations(MARKUP_PATTERNS[rule_id]) if MARKUP_PATTERNS.key?(rule_id)
@@ -47,17 +48,22 @@ module TRMNLP
         when 'form_fields_valid' then form_field_locations
         when 'custom_field_links_embedded' then custom_field_description_locations
         when 'custom_fields_used' then project_field_locations
+        when 'no_refresh_rate_field' then settings_field_locations
         when 'no_custom_filters', 'no_unknown_filters' then filter_locations
         when 'title_bar_outside_layout', 'no_nested_layouts'
           check.misplaced_elements.map { |path, element| source.element_location(path, element) }
+        when 'gray_text_has_one_bit_class' then gray_text_locations
         when 'image_links_reachable' then source.locations(Regexp.union(check.unreachable_urls))
+        when 'select_options_split_label_and_value' then split_option_locations
+        when 'no_style_restyling_framework' then style_block_locations
         else []
         end
       end
 
       def class_locations
         css_class = finding[:message][/\A'([^']+)'/, 1]
-        css_class ? source.locations(Regexp.new(Regexp.escape(css_class))) : []
+        # Up to the end of the class, so `lg:title` does not also find `lg:title--small`.
+        css_class ? source.locations(Regexp.new("#{Regexp.escape(css_class)}(?![\\w-])")) : []
       end
 
       def filter_locations
@@ -74,6 +80,29 @@ module TRMNLP
         end
       end
 
+      def split_option_locations
+        check.split_options.flat_map do |field, option|
+          source.yaml_location('src/settings.yml', 'custom_fields', field, 'options', option)
+        end
+      end
+
+      def gray_text_locations
+        classes = finding[:message][/\A'([^']+)'/, 1]
+        check.offending_elements.select { |_, element| Checks::GrayTextHasOneBitClass.class_list(element) == classes }
+             .map { |path, element| source.element_location(path, element) }
+      end
+
+      def style_block_locations
+        kind = Checks::NoStyleRestylingFramework::KINDS.find { |_, (message, _)| message == finding[:message] }&.first
+        check.occurrences.fetch(kind, []).map { |path, offset| source.offset_location(path, offset) }
+      end
+
+      def settings_field_locations
+        keyname = finding[:message][/Form field '([^']+)'/, 1]
+        index = source.custom_field_definitions.index { it['keyname'].to_s == keyname }
+        index ? source.yaml_location('src/settings.yml', 'custom_fields', index) : []
+      end
+
       def form_field_locations
         warning = finding[:message].split(' — ', 2).last
         source.custom_field_definitions.each_with_index.flat_map do |field, index|

data/lib/trmnlp/lint/source.rb

@@ -87,16 +87,17 @@ module TRMNLP
 
       def locations(pattern, files: markup_files)
         files.flat_map do |path, contents|
-          contents.to_enum(:scan, pattern).map do
-            offset = Regexp.last_match.begin(0)
-            prefix = contents[0...offset]
-            line = prefix.count("\n") + 1
-            { path:, line:, column: offset - (prefix.rindex("\n") || -1),
-              snippet: contents.lines[line - 1].to_s.chomp[0, 240] }
-          end
+          contents.to_enum(:scan, pattern).map { offset_location(path, Regexp.last_match.begin(0), contents:) }
         end.uniq
       end
 
+      def offset_location(path, offset, contents: markup_files.fetch(path))
+        prefix = contents[0...offset]
+        line = prefix.count("\n") + 1
+        { path:, line:, column: offset - (prefix.rindex("\n") || -1),
+          snippet: contents.lines[line - 1].to_s.chomp[0, 240] }
+      end
+
       def yaml_location(file, *keys)
         path = file == '.trmnlp.yml' ? paths.trmnlp_config : paths.plugin_config
         contents = raw_read(path)

data/lib/trmnlp/lint.rb

@@ -10,15 +10,19 @@ require_relative 'lint/checks/layouts_have_content'
 require_relative 'lint/checks/no_async_functions'
 require_relative 'lint/checks/waits_for_dom_load'
 require_relative 'lint/checks/limited_inline_styles'
+require_relative 'lint/checks/no_style_restyling_framework'
 require_relative 'lint/checks/no_size_classes'
 require_relative 'lint/checks/arbitrary_values_in_range'
 require_relative 'lint/checks/no_opacity'
+require_relative 'lint/checks/gray_text_has_one_bit_class'
 require_relative 'lint/checks/highcharts_animations_disabled'
 require_relative 'lint/checks/highcharts_elements_unique'
 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/yes_no_selects_are_boolean'
+require_relative 'lint/checks/select_options_split_label_and_value'
+require_relative 'lint/checks/no_refresh_rate_field'
 require_relative 'lint/checks/coordinates_use_lat_lon'
 require_relative 'lint/checks/no_custom_filters'
 require_relative 'lint/checks/no_unknown_filters'
@@ -45,15 +49,19 @@ module TRMNLP
       Checks::NoAsyncFunctions,
       Checks::WaitsForDomLoad,
       Checks::LimitedInlineStyles,
+      Checks::NoStyleRestylingFramework,
       Checks::NoSizeClasses,
       Checks::ArbitraryValuesInRange,
       Checks::NoOpacity,
+      Checks::GrayTextHasOneBitClass,
       Checks::HighchartsAnimationsDisabled,
       Checks::HighchartsElementsUnique,
       Checks::ImageLinksReachable,
       Checks::CustomFieldsUsed,
       Checks::FormFieldsValid,
       Checks::YesNoSelectsAreBoolean,
+      Checks::SelectOptionsSplitLabelAndValue,
+      Checks::NoRefreshRateField,
       Checks::CoordinatesUseLatLon,
       Checks::NoCustomFilters,
       Checks::NoUnknownFilters,

data/lib/trmnlp/testing/ink_count.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+
+module TRMNLP
+  module Testing
+    # How many pixels of a PNG stand out from its background, the gray level most pixels have; area: a box
+    # counts only inside it.
+    class InkCount
+      # Half the gray scale: text and lines pass; a faint tint or frame does not, on white or on black.
+      MIN_DIFFERENCE = 128
+
+      def initialize(path, area: nil)
+        @path = path
+        @area = area
+      end
+
+      def pixels
+        levels = histogram
+        return 0 if levels.empty?
+
+        background = levels.max_by(&:last).first
+        levels.sum { |level, count| (level - background).abs > MIN_DIFFERENCE ? count : 0 }
+      end
+
+      private
+
+      # [gray level 0-255, pixel count] for each level the picture uses.
+      def histogram
+        output = MiniMagick.convert do |convert|
+          convert << @path
+          convert << '-crop' << crop_geometry << '+repage' if @area
+          convert << '-colorspace' << 'gray' << '-depth' << '8' << '-format' << '%c' << 'histogram:info:-'
+        end
+        output.lines.filter_map do |line|
+          (match = line.match(/\A\s*(\d+):\s*\(\s*(\d+)/)) && [match[2].to_i, match[1].to_i]
+        end
+      end
+
+      def crop_geometry = "#{@area.width.round}x#{@area.height.round}+#{@area.left.round}+#{@area.top.round}"
+    end
+  end
+end

data/lib/trmnlp/testing/overlapping_text.js

@@ -0,0 +1,96 @@
+const shown = (el) => el.checkVisibility({ opacityProperty: true, visibilityProperty: true });
+const intersect = (a, b) => ({ left: Math.max(a.left, b.left), top: Math.max(a.top, b.top),
+                               right: Math.min(a.right, b.right), bottom: Math.min(a.bottom, b.bottom) });
+const area = (r) => Math.max(0, r.right - r.left) * Math.max(0, r.bottom - r.top);
+const covers = (a, b, share) => area(intersect(a, b)) > Math.min(area(a), area(b)) * share;
+const visiblePart = (rect, el) => {
+  let part = rect;
+  for (let parent = el; parent; parent = parent.parentElement) {
+    if (getComputedStyle(parent).overflow !== 'visible') part = intersect(part, parent.getBoundingClientRect());
+  }
+  return part;
+};
+const textMeasuringContext = document.createElement('canvas').getContext('2d');
+// A text range's box is as tall as its line, so the font's own box sits in the middle of it.
+const baselineOf = (rect, metrics) => rect.top + metrics.fontBoundingBoxAscent +
+  (rect.height - metrics.fontBoundingBoxAscent - metrics.fontBoundingBoxDescent) / 2;
+const inkOf = (rect, text, style, oneLine) => {
+  textMeasuringContext.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+  const metrics = textMeasuringContext.measureText(text);
+  const baseline = baselineOf(rect, metrics);
+  const left = oneLine ? rect.left - metrics.actualBoundingBoxLeft : rect.left;
+  const right = oneLine ? rect.left + metrics.actualBoundingBoxRight : rect.right;
+  return { left, right, top: baseline - metrics.actualBoundingBoxAscent,
+           bottom: baseline + metrics.actualBoundingBoxDescent };
+};
+const texts = [];
+const range = document.createRange();
+const walker = document.createTreeWalker(document.querySelector('.view') || document.body, NodeFilter.SHOW_TEXT);
+for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+  const owner = node.parentElement;
+  if (!node.data.trim() || owner instanceof SVGElement || owner.closest('script, style, svg') || !shown(owner)) continue;
+  range.selectNodeContents(node);
+  const style = getComputedStyle(owner);
+  const lines = [...range.getClientRects()];
+  lines.map((rect) => visiblePart(inkOf(rect, node.data.trim(), style, lines.length === 1), owner))
+    .filter((rect) => area(rect) > 4)
+    .forEach((rect) => texts.push({ node, owner, rect, text: node.data.trim().slice(0, 40) }));
+}
+const SHARED_INK_PIXELS = 4;
+const glyphCache = new Map();
+const glyphsOf = (node) => {
+  if (glyphCache.has(node)) return glyphCache.get(node);
+  const style = getComputedStyle(node.parentElement);
+  const font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+  const glyphs = [];
+  for (let start = 0; start < node.data.length;) {
+    const end = start + String.fromCodePoint(node.data.codePointAt(start)).length;
+    const glyph = node.data.slice(start, end);
+    if (glyph.trim()) {
+      range.setStart(node, start);
+      range.setEnd(node, end);
+      [...range.getClientRects()].forEach((rect) => {
+        textMeasuringContext.font = font;
+        const metrics = textMeasuringContext.measureText(glyph);
+        const box = visiblePart(inkOf(rect, glyph, style, false), node.parentElement);
+        if (area(box) > 1) glyphs.push({ glyph, font, box, x: rect.left, baseline: baselineOf(rect, metrics) });
+      });
+    }
+    start = end;
+  }
+  glyphCache.set(node, glyphs);
+  return glyphs;
+};
+// Draws each glyph where the page put it and counts the pixels both inked, so a glyph tucked into the
+// empty corner of another glyph's box does not count.
+const inkPixels = (glyph, region) => {
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.ceil(region.right - region.left);
+  canvas.height = Math.ceil(region.bottom - region.top);
+  const context = canvas.getContext('2d');
+  context.font = glyph.font;
+  context.fillText(glyph.glyph, glyph.x - region.left, glyph.baseline - region.top);
+  const alpha = context.getImageData(0, 0, canvas.width, canvas.height).data;
+  const inked = new Set();
+  for (let i = 3; i < alpha.length; i += 4) if (alpha[i] > 127) inked.add(i);
+  return inked;
+};
+const inkOverlaps = (one, other) => {
+  const shared = intersect(one.box, other.box);
+  if (area(shared) < 1) return false;
+  const otherInk = inkPixels(other, shared);
+  return [...inkPixels(one, shared)].filter((pixel) => otherInk.has(pixel)).length >= SHARED_INK_PIXELS;
+};
+const inkTouches = (a, b) => glyphsOf(a.node).some((glyph) => glyphsOf(b.node).some((other) => inkOverlaps(glyph, other)));
+const related = (a, b) => a === b || a.contains(b) || b.contains(a);
+const found = [];
+texts.forEach((a, i) => texts.slice(i + 1).forEach((b) => {
+  if (!related(a.owner, b.owner) && covers(a.rect, b.rect, 0) && inkTouches(a, b)) found.push(`"${a.text}" and "${b.text}"`);
+}));
+const titleBar = document.querySelector('.view .title_bar');
+if (titleBar) {
+  const bar = titleBar.getBoundingClientRect();
+  texts.filter((t) => !titleBar.contains(t.owner) && covers(t.rect, bar, 1 / 3))
+    .forEach((t) => found.push(`"${t.text}" and the title bar`));
+}
+return [...new Set(found)];

data/lib/trmnlp/testing/publishable_recipe.rb

@@ -18,6 +18,9 @@ module TRMNLP
     }.freeze
     # A field with more options than this is drawn with its first and last.
     PUBLISHABLE_RECIPE_MAX_OPTIONS = 20
+    # Share of a layout's ink its dark mode render must keep. Of 17 recipes measured on 10-13, those that draw
+    # well in dark mode kept 85% or more; those whose text turned black on black kept 0% to 15%.
+    DARK_MODE_MIN_INK_KEPT = 0.5
 
     # Each select field's keyname and the values its options save, from the plugin's settings.yml.
     def self.select_field_values
@@ -32,14 +35,18 @@ module TRMNLP
 end
 
 # rubocop:disable-next Metrics/BlockLength -- one shared group, one check per example
-RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLISHABLE_RECIPE_SCREENS|
+RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLISHABLE_RECIPE_SCREENS,
+                                                 dark_mode_screen: { device: 'v2' }|
   let(:recipe_inputs) do
     { mocks: respond_to?(:mocks) ? mocks : {}, custom_fields: respond_to?(:custom_fields) ? custom_fields : {},
       variables: respond_to?(:variables) ? variables : {}, now: respond_to?(:now) ? now : nil,
       data: respond_to?(:data) ? data : nil }
   end
 
-  def draw_cleanly = have_no_problems.and(have_no_leaked_text)
+  def draw_cleanly
+    have_no_problems.and(have_no_leaked_text)
+                    .and(have_no_text_clamped_with_room_to_spare).and(have_no_overlapping_text)
+  end
 
   TRMNLP::Testing::PUBLISHABLE_RECIPE_VIEWS.product(screens).each do |view, screen|
     device = screen[:device].is_a?(Hash) ? screen[:device][:model] : screen[:device]
@@ -51,6 +58,13 @@ RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLI
     end
   end
 
+  TRMNLP::Testing::PUBLISHABLE_RECIPE_VIEWS.each do |view|
+    it "keeps the #{view} view's content in dark mode" do
+      light = trmnl.render(view:, **dark_mode_screen, **recipe_inputs)
+      expect(trmnl.render(view:, **dark_mode_screen, **recipe_inputs, dark_mode: true)).to keep_the_content_of(light)
+    end
+  end
+
   TRMNLP::Testing::PUBLISHABLE_RECIPE_API_FAILURES.each do |failure, answer|
     it "draws the full view when the API #{failure}" do
       screen = trmnl.render(**screens.first, **recipe_inputs, mocks: { '*' => answer })
@@ -67,6 +81,10 @@ RSpec.shared_examples 'a publishable recipe' do |screens: TRMNLP::Testing::PUBLI
     end
   end
 
+  it 'has a mock for every request it makes' do
+    expect(trmnl.transform(device: screens.first[:device], **recipe_inputs)).to have_a_mock_for_every_request
+  end
+
   it 'runs its transform without error' do
     expect(trmnl.transform(device: screens.first[:device], **recipe_inputs).error).to be_nil
   end

data/lib/trmnlp/testing/rspec.rb

@@ -10,6 +10,7 @@ require_relative '../browser_pool'
 require_relative '../firefox_driver'
 require_relative 'browser'
 require_relative 'certificate_authority'
+require_relative 'ink_count'
 require_relative 'page_server'
 require_relative 'plugin'
 require_relative 'report'
@@ -75,6 +76,49 @@ RSpec::Matchers.define :have_no_transform_error do
   failure_message { |screen| "expected the transform to run without error, but: #{screen.result.error}" }
 end
 
+# A request no mock answers gets status 599, which draws the plugin's error screen as if its API failed.
+RSpec::Matchers.define :have_a_mock_for_every_request do
+  def unmocked(run) = run.requests.reject { it[:mocked] }.map { "#{it[:method]} #{it[:url].split('?', 2).first}" }.uniq
+
+  match { |run| unmocked(run).empty? }
+  failure_message do |run|
+    "expected a mock for every request, but none answers: #{unmocked(run).join(', ')}. " \
+      'Add them to tests/mocks.json; without one the screen shows the error state.'
+  end
+end
+
+# Dark mode recolors the Framework's text and lines; anything drawn in a fixed black stays black on the black screen.
+RSpec::Matchers.define :keep_the_content_of do |light|
+  match do |dark|
+    @light, @dark = [light, dark].map { TRMNLP::Testing::InkCount.new(it.png_path, area: content_box(it)).pixels }
+    @light.zero? || @dark >= @light * TRMNLP::Testing::DARK_MODE_MIN_INK_KEPT
+  end
+  # The layout only: a mashup slot's frame is too faint to count on white but stands out on black.
+  def content_box(screen) = screen.has_css?('.layout', wait: false) ? screen.box('.layout') : nil
+
+  failure_message do |dark|
+    "expected #{dark.inspect} in dark mode to keep its content, but it keeps #{(100 * @dark / @light).round}% of " \
+      "it (#{@dark} of #{@light} pixels that stand out): text, lines or icons drawn in a fixed black (#000, black) " \
+      'stay black on the black screen. Use currentColor or Framework classes.'
+  end
+end
+
+RSpec::Matchers.define :have_no_text_clamped_with_room_to_spare do
+  match { |screen| screen.clamped_with_room.empty? }
+  failure_message do |screen|
+    "expected no text cut short with room to spare on #{screen.inspect}, but it cuts: " \
+      "#{screen.clamped_with_room.join('; ')}."
+  end
+end
+
+RSpec::Matchers.define :have_no_overlapping_text do
+  match { |screen| screen.overlapping_text.empty? }
+  failure_message do |screen|
+    "expected no text drawn over other text on #{screen.inspect}, but it draws #{screen.overlapping_text.join('; ')} " \
+      'over each other.'
+  end
+end
+
 RSpec::Matchers.define :have_no_problems do
   match { |screen| screen.problems.empty? }
   failure_message { |screen| "expected no problems on #{screen.inspect}, but: #{screen.problems.join('; ')}" }

data/lib/trmnlp/testing/screen.rb

@@ -87,6 +87,34 @@ module TRMNLP
         }).map(describe);
       JS
 
+      # Each element the Framework clamped although its full text fits on one line of the width its parent gives it.
+      CLAMPED_WITH_ROOM_SCRIPT = <<~JS
+        const textMeasuringContext = document.createElement('canvas').getContext('2d');
+        const px = (value) => parseFloat(value) || 0;
+        const sharesItsRow = (style) => style.display.includes('grid') ||
+          (style.display.includes('flex') && !style.flexDirection.startsWith('column'));
+        const fullTextWidth = (el, text) => {
+          const style = getComputedStyle(el);
+          textMeasuringContext.font = `${style.fontStyle} ${style.fontWeight} ${style.fontSize} ${style.fontFamily}`;
+          const shown = style.textTransform === 'uppercase' ? text.toUpperCase() : text;
+          return textMeasuringContext.measureText(shown).width + px(style.letterSpacing) * shown.length +
+            px(style.paddingLeft) + px(style.paddingRight) + px(style.marginLeft) + px(style.marginRight);
+        };
+        return [...document.querySelectorAll('.view [data-clamp-original]')].filter((el) => {
+          const original = el.getAttribute('data-clamp-original').trim();
+          const parent = el.parentElement;
+          if (!original || el.innerText.trim() === original || !el.getClientRects().length || !parent) return false;
+          const parentStyle = getComputedStyle(parent);
+          if (sharesItsRow(parentStyle)) return false;
+          const room = parent.clientWidth - px(parentStyle.paddingLeft) - px(parentStyle.paddingRight);
+          return fullTextWidth(el, original) <= room - 2;
+        }).map((el) => `"${el.innerText.trim()}" (all of "${el.getAttribute('data-clamp-original').trim()}" fits)`);
+      JS
+
+      # Pairs of text whose ink is drawn over each other, and text drawn under the title bar. Each line's ink is cut
+      # to what its clipping parents show; two count when their glyphs share inked pixels.
+      OVERLAPPING_TEXT_SCRIPT = File.read(File.join(__dir__, 'overlapping_text.js')).freeze
+
       HIDDEN_MARK = 'data-trmnlp-hidden'
       # The DOM with every element Firefox does not draw marked, so Capybara's visible text is what is on screen.
       DRAWN_DOM_SCRIPT = <<~JS.freeze
@@ -126,6 +154,9 @@ module TRMNLP
 
       def overflowing(except: nil) = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT, except) }
 
+      def clamped_with_room = @browser.on(self) { it.execute_script(CLAMPED_WITH_ROOM_SCRIPT) }
+      def overlapping_text = @browser.on(self) { it.execute_script(OVERLAPPING_TEXT_SCRIPT) }
+
       # Script errors, unhandled rejections, console.error lines and files that failed to load.
       def problems = evaluate('window.__trmnlpProblems || []')
 

data/lib/trmnlp/version.rb

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