trmnl_preview 0.28.0 → 0.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73458f9c8bc2782cf56c7e5e2ceb2e9b06e16fdc865ee68787a90cd11ab3930d
-  data.tar.gz: 59de88bc00c8168785fe2117b008eed21f4fac9b85d5ef32546882787060624b
+  metadata.gz: 20431d997e72a0c534f9945c0c8e23cf97dcfff3be5119cbbf2d7973b2c3af73
+  data.tar.gz: 4a96842d311255ad1cd618e36dab4ef4eaa0504c58efe394a609ee5ddc043dba
 SHA512:
-  metadata.gz: 58865958ff6709443c7a8789757ce6b7951088561229edf1771db2c80c4dab318dabc6be36f81a75200878adc85111b025d0a36fb90ba74d72dae8adfaa5be7f
-  data.tar.gz: 4e8e15211854ebae382e7f8deaacda24217e2e1a6f77c7aafafe0199e57c0919c4ac170ec7a38953fe2a5e59ac334b469e229b5bb19d0955cfeceace62f9df83
+  metadata.gz: 6dcab087ef567886345b3ef14e90931af73c236680afb0555667357f277fd650eaed3c473fa7bb514196ca701cccbd3a68ee6f19e302e0be3d37a23bb5abcdb1
+  data.tar.gz: '070453995dac9d20fb77914c1a2adcfde9d01f2ccb34899f00b94cf238278b15a3afae3abfe33da9aae17dbacad5f842e34bd080c169ef256c58d144c449b9b5'

data/CHANGELOG.md

@@ -1,6 +1,19 @@
 
 # Changelog
 
+## 0.30.0
+
+- `trmnlp test` quits a Firefox that stopped answering before it starts a new one. The old geckodriver kept running until something killed it.
+- `trmnlp test`'s dark mode check also fails a view where an image, SVG or canvas that shows something in light mode shows nothing in dark mode, such as a checkbox icon drawn in a fixed black, and names it. Before, a view lost to dark mode only when most of its content went, so one lost icon passed.
+- `trmnlp test`'s check for text drawn over other text reads the pixels Firefox draws for each text, in place of glyph outlines estimated from font measurements. It now also fails a glyph that only touches the line next to it, such as the bottom of a quote's last line touching the name under it, which the estimates placed a few pixels off. Text that sits close without touching still passes.
+
+## 0.29.0
+
+- `trmnlp test` fails a screen that draws text over other text, or content text under the title bar, and names both texts, such as a name printed across the last line of a quote. Only glyphs that share inked pixels count, so a unit tucked against a number passes.
+- `trmnlp test`'s publishable recipe group fails "has a mock for every request it makes" when the polling or the transform asks for a url no mock answers, and names each url without its query. Such a request is answered with status 599, so the screens drew the error state as if the API had failed. The matcher is `have_a_mock_for_every_request`.
+- `trmnlp test` checks each view in dark mode on the TRMNL X: a view fails when its layout keeps less than half its content, as when text, lines or icons are drawn in a fixed black and stay black on the black screen. Pass `dark_mode_screen:` to the shared group to check another screen.
+- `trmnlp test` fails a screen where the Framework clamped text whose full text fits on one line in the width its parent gives it, such as a chart title cut to `Egg Pric...`. It names the cut text and the full text.
+
 ## 0.28.0
 
 - `trmnlp test`, `serve` and `build --png` close their headless Firefox when they exit. Each run left one running, with nothing left to stop it, and a loop of runs could fill memory and swap.

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.4.0
+latest: 3.4.2
 versions:
 - number: 0.0.1
   released_at: '2024-06-22'
@@ -94,3 +94,7 @@ versions:
   released_at: '2026-09-18'
 - number: 3.4.0
   released_at: '2026-09-28'
+- number: 3.4.1
+  released_at: '2026-10-14'
+- number: 3.4.2
+  released_at: '2026-10-14'

data/lib/trmnlp/browser_pool.rb

@@ -23,11 +23,7 @@ module TRMNLP
         return if @shutdown
 
         @shutdown = true
-        @drivers.each do |driver|
-          driver.quit
-        rescue StandardError
-          nil
-        end
+        @drivers.each { quit(it) }
         @drivers.clear
       end
     end
@@ -72,9 +68,15 @@ module TRMNLP
 
     def recycle(driver)
       @mutex.synchronize do
-        @drivers.delete(driver)
+        quit(@drivers.delete(driver))
         @driver_factory.call.tap { |d| @drivers << d }
       end
     end
+
+    def quit(driver)
+      driver&.quit
+    rescue StandardError
+      nil
+    end
   end
 end

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,59 @@
+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;
+};
+// A glyph can reach past its line box, above it or below it, by up to about half its font size.
+const widen = (rect, by) => ({ left: rect.left - by, top: rect.top - by, right: rect.right + by, bottom: rect.bottom + by });
+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 fontSize = parseFloat(getComputedStyle(owner).fontSize) || 16;
+  [...range.getClientRects()].map((line) => ({ line: visiblePart(line, owner), rect: visiblePart(widen(line, fontSize / 2), owner) }))
+    .filter(({ line }) => area(line) > 4)
+    .forEach(({ line, rect }) => texts.push({ owner, line, rect, text: node.data.trim().slice(0, 40) }));
+}
+const related = (a, b) => a === b || a.contains(b) || b.contains(a);
+const pairs = [];
+const neighbors = new Map(texts.map((t) => [t.owner, new Set()]));
+texts.forEach((a, i) => texts.slice(i + 1).forEach((b) => {
+  if (a.owner === b.owner || !covers(a.rect, b.rect, 0)) return;
+  neighbors.get(a.owner).add(b.owner);
+  neighbors.get(b.owner).add(a.owner);
+  if (!related(a.owner, b.owner)) pairs.push([a, b]);
+}));
+// Texts whose widened boxes do not meet share a group, and each group one screenshot.
+const groups = new Map();
+pairs.flat().map((t) => t.owner).forEach((owner) => {
+  if (groups.has(owner)) return;
+  const taken = new Set([...neighbors.get(owner)].map((other) => groups.get(other)));
+  let group = 0;
+  while (taken.has(group)) group += 1;
+  groups.set(owner, group);
+});
+groups.forEach((group, owner) => owner.setAttribute('data-trmnlp-text', group));
+const candidates = pairs.map(([a, b]) => {
+  const region = intersect(a.rect, b.rect);
+  return { texts: [groups.get(a.owner), groups.get(b.owner)], names: `"${a.text}" and "${b.text}"`,
+           region: { left: region.left, top: region.top, width: region.right - region.left,
+                     height: region.bottom - region.top } };
+});
+const underTitleBar = [];
+const titleBar = document.querySelector('.view .title_bar');
+if (titleBar) {
+  const bar = titleBar.getBoundingClientRect();
+  texts.filter((t) => !titleBar.contains(t.owner) && covers(t.line, bar, 1 / 3))
+    .forEach((t) => underTitleBar.push(`"${t.text}" and the title bar`));
+}
+return { candidates, under_title_bar: [...new Set(underTitleBar)] };

data/lib/trmnlp/testing/publishable_recipe.rb

@@ -18,6 +18,12 @@ 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
+    DARK_MODE_MIN_LIGHT_IMAGE_INK_PIXELS = 16
+    # Share of an image's ink its dark mode render must keep: lost icons kept 0%, the lowest one shown 17% (10-14).
+    DARK_MODE_MIN_IMAGE_INK_KEPT = 0.05
 
     # Each select field's keyname and the values its options save, from the plugin's settings.yml.
     def self.select_field_values
@@ -32,14 +38,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 +61,14 @@ 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).and keep_each_image_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 +85,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,71 @@ 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
+
+# Each image, SVG and canvas that stands out in light mode must still show in dark mode.
+RSpec::Matchers.define :keep_each_image_of do |light|
+  def ink(screen, box) = TRMNLP::Testing::InkCount.new(screen.png_path, area: box).pixels
+
+  def lost_images(light, dark)
+    light.drawn_images.zip(dark.drawn_images).filter_map do |(name, light_box), (dark_name, dark_box)|
+      next unless name == dark_name
+
+      light_ink = ink(light, light_box)
+      lost = light_ink >= TRMNLP::Testing::DARK_MODE_MIN_LIGHT_IMAGE_INK_PIXELS &&
+             ink(dark, dark_box) < light_ink * TRMNLP::Testing::DARK_MODE_MIN_IMAGE_INK_KEPT
+      "#{name} at #{light_box.left.round},#{light_box.top.round}" if lost
+    end
+  end
+
+  match { |dark| (@lost = lost_images(light, dark)).empty? }
+  failure_message do |dark|
+    "expected #{dark.inspect} in dark mode to keep each image, but #{@lost.join(', ')} shows nothing in dark " \
+      'mode: it is drawn in a fixed black (#000, black). Use currentColor, or image--adaptive on an <img>.'
+  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

@@ -5,6 +5,7 @@ require 'delegate'
 require 'nokogiri'
 
 require_relative 'qr_scanner'
+require_relative 'text_ink'
 
 module TRMNLP
   module Testing
@@ -87,6 +88,51 @@ 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 near enough to touch, and text drawn under the title bar. TextInk decides which pairs touch.
+      OVERLAPPING_TEXT_SCRIPT = File.read(File.join(__dir__, 'overlapping_text.js')).freeze
+
+      # Each drawn image, SVG and canvas in the view but the Framework's adaptive icon, its box cut to the screen.
+      DRAWN_IMAGES_SCRIPT = <<~JS
+        const screen = document.documentElement.getBoundingClientRect();
+        const describe = (el) => el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') +
+          (el.classList.length ? '.' + [...el.classList].join('.') : '');
+        return [...document.querySelectorAll('.view img, .view svg, .view canvas')]
+          .filter((el) => !el.parentElement.closest('svg') && !el.matches('img.image--adaptive[data-adaptive]') &&
+            el.checkVisibility({ opacityProperty: true }))
+          .map((el) => {
+            const box = el.getBoundingClientRect();
+            const left = Math.max(box.left, 0);
+            const top = Math.max(box.top, 0);
+            const right = Math.min(box.right, screen.right);
+            const bottom = Math.min(box.bottom, screen.bottom);
+            return { name: describe(el), left, top, right, bottom, width: right - left, height: bottom - top };
+          }).filter((image) => image.width >= 1 && image.height >= 1);
+      JS
+
       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 +172,21 @@ module TRMNLP
 
       def overflowing(except: nil) = @browser.on(self) { it.execute_script(OVERFLOW_SCRIPT, except) }
 
+      def drawn_images
+        @browser.on(self) { it.execute_script(DRAWN_IMAGES_SCRIPT) }.map do |image|
+          [image['name'], Box.new(**image.slice(*Box.members.map(&:to_s)).transform_keys(&:to_sym))]
+        end
+      end
+
+      def clamped_with_room = @browser.on(self) { it.execute_script(CLAMPED_WITH_ROOM_SCRIPT) }
+
+      def overlapping_text
+        @browser.on(self) do |driver|
+          found = driver.execute_script(OVERLAPPING_TEXT_SCRIPT)
+          TextInk.new(driver).overlapping(found['candidates']) + found['under_title_bar']
+        end
+      end
+
       # Script errors, unhandled rejections, console.error lines and files that failed to load.
       def problems = evaluate('window.__trmnlpProblems || []')
 

data/lib/trmnlp/testing/text_ink.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'mini_magick'
+require 'tempfile'
+
+module TRMNLP
+  module Testing
+    # Which candidate pairs of text share inked pixels, as Firefox draws them.
+    class TextInk
+      MIN_SHARED_INK_PIXELS = 4
+      TEXT_GROUP_ATTRIBUTE = 'data-trmnlp-text'
+      INK_ATTRIBUTE = 'data-trmnlp-ink'
+      HIDE_TEXT_STYLE = <<~CSS.freeze
+        .view, .view * { color: transparent !important; -webkit-text-fill-color: transparent !important;
+                         -webkit-text-stroke-width: 0 !important; text-shadow: none !important; }
+        .view [#{INK_ATTRIBUTE}="black"] { color: #000 !important; -webkit-text-fill-color: #000 !important; }
+        .view [#{INK_ATTRIBUTE}="white"] { color: #fff !important; -webkit-text-fill-color: #fff !important; }
+      CSS
+
+      def initialize(driver)
+        @driver = driver
+        @masks = {}
+      end
+
+      # candidates: { 'texts' => [group, group], 'names' => String, 'region' => { left, top, width, height } }.
+      def overlapping(candidates)
+        return [] if candidates.empty?
+
+        hide_text
+        candidates.select { shared_pixels(it) >= MIN_SHARED_INK_PIXELS }.map { it['names'] }.uniq
+      ensure
+        show_text
+      end
+
+      private
+
+      def shared_pixels(candidate)
+        one, other = candidate['texts'].map { mask(it) }
+        one.shared_with(other, candidate['region'])
+      end
+
+      # One byte per pixel of the screen, above zero where the text inks.
+      Mask = Data.define(:width, :height, :pixels) do
+        def shared_with(other, region)
+          left, top = region.values_at('left', 'top').map { it.floor.clamp(0..) }
+          right = (region['left'] + region['width']).ceil.clamp(..width)
+          bottom = (region['top'] + region['height']).ceil.clamp(..height)
+          (top...bottom).sum { |row| (left...right).count { inked?(it, row) && other.inked?(it, row) } }
+        end
+
+        def inked?(column, row) = pixels.getbyte((row * width) + column).positive?
+      end
+
+      # Where the group inks more than half a pixel: the difference of a black and a white screenshot.
+      def mask(group)
+        @masks[group] ||= begin
+          black, white = %w[black white].map { screenshot_with(group, it) }
+          Tempfile.create(['text-ink', '.pgm']) do |pgm|
+            MiniMagick.convert do |convert|
+              convert << black.path << white.path << '-alpha' << 'off' << '-compose' << 'difference' << '-composite'
+              convert << '-separate' << '-evaluate-sequence' << 'max' << '-threshold' << '50%' << '-depth' << '8'
+              convert << pgm.path
+            end
+            parse_pgm(File.binread(pgm.path))
+          end
+        ensure
+          [black, white].compact.each(&:close!)
+        end
+      end
+
+      # A binary PGM: "P5", width, height and the largest value, then one byte per pixel.
+      def parse_pgm(data)
+        header = data.match(/\AP5\s+(\d+)\s+(\d+)\s+\d+\s/)
+        Mask.new(width: header[1].to_i, height: header[2].to_i, pixels: data.byteslice(header.end(0)..))
+      end
+
+      def screenshot_with(group, color)
+        run_on_group_elements(group, "el.setAttribute('#{INK_ATTRIBUTE}', '#{color}')")
+        Tempfile.new(['text-ink', '.png']).tap { @driver.save_screenshot(it.path) }
+      ensure
+        run_on_group_elements(group, "el.removeAttribute('#{INK_ATTRIBUTE}')")
+      end
+
+      def run_on_group_elements(group, statement)
+        selector = "[#{TEXT_GROUP_ATTRIBUTE}=\"#{group}\"]"
+        @driver.execute_script("document.querySelectorAll('#{selector}').forEach((el) => #{statement})")
+      end
+
+      def hide_text
+        @driver.execute_script(<<~JS, HIDE_TEXT_STYLE)
+          const style = document.createElement('style');
+          style.id = 'trmnlp-text-ink';
+          style.textContent = arguments[0];
+          document.head.appendChild(style);
+        JS
+      end
+
+      def show_text
+        @driver.execute_script("document.getElementById('trmnlp-text-ink')?.remove(); " \
+                               "document.querySelectorAll('[#{TEXT_GROUP_ATTRIBUTE}]')" \
+                               ".forEach((el) => el.removeAttribute('#{TEXT_GROUP_ATTRIBUTE}'))")
+      end
+    end
+  end
+end

data/lib/trmnlp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.30.0
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -480,10 +480,12 @@ files:
 - lib/trmnlp/testing/certificate_authority.rb
 - lib/trmnlp/testing/device_models.rb
 - lib/trmnlp/testing/frozen_clock.rb
+- lib/trmnlp/testing/ink_count.rb
 - lib/trmnlp/testing/memory_sampler.rb
 - lib/trmnlp/testing/mock_proxy.rb
 - lib/trmnlp/testing/mock_table.rb
 - lib/trmnlp/testing/node_version.rb
+- lib/trmnlp/testing/overlapping_text.js
 - lib/trmnlp/testing/page_server.rb
 - lib/trmnlp/testing/plugin.rb
 - lib/trmnlp/testing/publishable_recipe.rb
@@ -494,6 +496,7 @@ files:
 - lib/trmnlp/testing/run.rb
 - lib/trmnlp/testing/screen.rb
 - lib/trmnlp/testing/snapshot.rb
+- lib/trmnlp/testing/text_ink.rb
 - lib/trmnlp/transform_backend/http.rb
 - lib/trmnlp/transform_backend/subprocess.rb
 - lib/trmnlp/transform_backend/which.rb