trmnl_preview 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf11a528033d7882be345a627e2a480f1cdf95a5f9cef22d01f51f5b46012635
-  data.tar.gz: 973c3dc1b96f1d7a81ffa8e9fc82f403285d9449463d210684732a43028509d8
+  metadata.gz: 0f80ac8d03e9b67e4ea6c7f18e8cd7745a76c910e9801f910662cc46b5661eb0
+  data.tar.gz: 1022cfae134c303ba7d00201d2d6ca7acb7c23c927371585b9e63a00fa28bfa2
 SHA512:
-  metadata.gz: 39963f376ff877a4170ce57564876e5cb4bd6eacc23de4b1792a6cba6cd01f4252579fe19c8d678f21144f37e9ba050ed03866b38a3f7aaa9a67521aa324fd04
-  data.tar.gz: 835b494bb56d29e9e4b607a482ae05466b08aa527ff38c00fae2a98e87524bbcbb6db78c9abd5dc8288c3b36692008107a1c9bbbdd298c36ddf1d435cd0d2e65
+  metadata.gz: 6667ad132d9b601073db2010c524f8322e6a7fd2b5425d248cf3a53398166d1f579171e8c1142da146247f7fcb96192c50c7fa0e8d9158797bc98d7bc9755eb2
+  data.tar.gz: 189d830c8ee5b2ed2ccd2006ef1fda9c6dadd258488a74d4925ac4476762c581fd4df3961fb94f771ff0943f3ba57cd62d0294cff6e5e1c5f79558c763d534a1

data/CHANGELOG.md

@@ -1,6 +1,24 @@
 
 # Changelog
 
+## 0.8.1
+
+### Added
+
+- `trmnlp build --png` renders a PNG for every view alongside the HTML, with `--width`, `--height`, and `--color-depth` flags to override the defaults (#92)
+- Colour-coded the preview's payload-size badge — yellow from 75 KB, red from 100 KB — so an oversized merge-variable payload is visible at a glance (#67)
+- Added colour to CLI output — `lint` results, warnings, and errors — suppressed automatically when output is piped or redirected (#33)
+
+### Fixed
+
+- `trmnlp init` no longer produces read-only project files when trmnlp itself is installed read-only, such as on NixOS (#83)
+- Non-JSON polling responses (`text/html`, `text/plain`) are exposed to templates as `{{ data }}`, matching the hosted service — previously `{{ text }}` (#81)
+
+### Housekeeping
+
+- Added SimpleCov coverage tracking, gated in CI at a 90% floor, plus dedicated specs for every lint check
+- Extracted the headless-Firefox driver into a shared `FirefoxDriver` module used by both `serve` and `build --png`
+
 ## 0.8.0
 
 ### Housekeeping

data/README.md

@@ -80,7 +80,7 @@ trmnlp push                    # upload
 |---|---|
 | `trmnlp init NAME` | Start a new plugin project |
 | `trmnlp serve` | Start a local dev server |
-| `trmnlp build` | Generate static HTML files |
+| `trmnlp build` | Generate static HTML files, or PNGs with `--png` |
 | `trmnlp lint` | Check plugin code against TRMNL best practices |
 | `trmnlp login` | Authenticate with TRMNL server |
 | `trmnlp list` | List private plugins from TRMNL server |
@@ -91,6 +91,30 @@ 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.
 
+## Building Static Files
+
+`trmnlp build` renders every view to a static file under `_build/` — handy for exporting a snapshot or feeding the output into another pipeline. Run it from inside a plugin project:
+
+```sh
+trmnlp build        # writes _build/full.html, _build/half_horizontal.html, ...
+trmnlp build --png  # also writes a PNG for each view
+```
+
+`--png` renders each view through the same screenshot pipeline `serve` uses. By default a PNG is 800×480 at the bit depth declared by the markup's `screen--Nbit` class (1-bit if none). Override any of those:
+
+```sh
+trmnlp build --png --color-depth 2
+```
+
+| Flag | Purpose |
+|---|---|
+| `--png` | Render a PNG per view alongside the HTML |
+| `--width` | PNG width in pixels (default 800) |
+| `--height` | PNG height in pixels (default 480) |
+| `--color-depth` | PNG bit depth — 1, 2, or 4 — overriding the markup |
+
+`--width`, `--height`, and `--color-depth` apply only with `--png`. PNG rendering needs Firefox and ImageMagick installed; plain `trmnlp build` needs neither.
+
 ## Authentication
 
 The `trmnlp login` command saves your API key to `~/.config/trmnlp/config.yml`.
@@ -310,6 +334,8 @@ To test, run:
 bin/rake
 ```
 
+Specs run under SimpleCov; a coverage report is written to `coverage/`.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/usetrmnl/trmnlp.

data/bin/trmnlp

@@ -11,7 +11,8 @@ ENV['TZ'] = 'UTC'
 begin
   TRMNLP::CLI.start
 rescue TRMNLP::Error => e
-  puts "Error: #{e.message}"
+  reporter = TRMNLP::Reporter.new
+  reporter.info reporter.red("Error: #{e.message}")
   exit 1
 rescue Interrupt
   exit 1

data/lib/trmnlp/app.rb

@@ -18,6 +18,16 @@ module TRMNLP
         bytes < 1024 ? "#{bytes} bytes" : format('%.1f KB', bytes / 1024.0)
       end
 
+      # Colour-codes the payload badge so an author notices when merge
+      # variables approach the size the hosted service starts rejecting.
+      # KB = 1024, matching format_bytes.
+      def payload_size_class(bytes)
+        return 'payload-size--over' if bytes >= 100 * 1024
+        return 'payload-size--warn' if bytes >= 75 * 1024
+
+        'payload-size--ok'
+      end
+
       # NOTE: render_html.erb's layout yields raw plugin HTML through `<%= yield %>`,
       # so a global `escape_html` setting would corrupt the render. Escape per-value.
       def h(text)

data/lib/trmnlp/cli.rb

@@ -19,6 +19,10 @@ module TRMNLP
     def self.default_bind = File.exist?('/.dockerenv') ? '0.0.0.0' : '127.0.0.1'
 
     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)'
+    method_option :height, type: :numeric, desc: 'PNG height in pixels (with --png)'
+    method_option :color_depth, type: :numeric, desc: 'PNG bit depth: 1, 2, or 4 (with --png)'
     def build
       Commands::Build.run(options)
     end

data/lib/trmnlp/commands/base.rb

@@ -50,7 +50,7 @@ module TRMNLP
       # plugin author notices before the field misbehaves in production.
       def report_form_field_warnings
         FormField.validate_all(config.plugin.custom_field_definitions).each do |warning|
-          reporter.info("warning: settings.yml custom_fields — #{warning}")
+          reporter.info(reporter.yellow("warning: settings.yml custom_fields — #{warning}"))
         end
       end
 

data/lib/trmnlp/commands/build.rb

@@ -1,11 +1,17 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 require_relative 'base'
+require_relative '../browser_pool'
+require_relative '../firefox_driver'
+require_relative '../screen_generator'
+require_relative '../screenshot'
 
 module TRMNLP
   module Commands
     class Build < Base
-      Options = Data.define(:dir, :quiet)
+      Options = Data.define(:dir, :quiet, :png, :width, :height, :color_depth)
 
       def call
         context.validate!
@@ -13,13 +19,49 @@ module TRMNLP
         context.poller.poll_data
         context.paths.create_build_dir
 
-        Screen.all.each do |screen|
-          output_path = context.paths.build_dir.join("#{screen.name}.html")
-          reporter.info "Writing #{output_path}..."
-          output_path.write(context.renderer.render_full_page(screen.name))
-        end
+        Screen.all.each { |screen| build_screen(screen) }
 
         reporter.info 'Done!'
+      ensure
+        @browser_pool&.shutdown
+      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
+      end
+
+      def write_html(view, html)
+        path = context.paths.build_dir.join("#{view}.html")
+        reporter.info "Writing #{path}..."
+        path.write(html)
+      end
+
+      # --png is additive: the HTML is rendered either way, so it stays on
+      # disk alongside the PNG rather than being replaced by it.
+      def write_png(view, html)
+        path = context.paths.build_dir.join("#{view}.png")
+        reporter.info "Writing #{path}..."
+        image = screen_generator(html).process
+        FileUtils.cp(image.path, path)
+      ensure
+        image&.close!
+      end
+
+      # --width/--height/--color-depth are optional; nil lets ScreenGenerator
+      # fall back to 800x480 and the screen--Nbit depth sniffed from the markup.
+      def screen_generator(html)
+        ScreenGenerator.new(html, screenshot:, width: options.width,
+                                  height: options.height, color_depth: options.color_depth)
+      end
+
+      def screenshot = @screenshot ||= Screenshot.new(pool: browser_pool)
+
+      def browser_pool
+        @browser_pool ||= BrowserPool.new(driver_factory: FirefoxDriver.method(:build))
       end
     end
   end

data/lib/trmnlp/commands/init.rb

@@ -35,6 +35,10 @@ module TRMNLP
 
           reporter.info "Creating #{destination_pathname}"
           FileUtils.cp(source_pathname, destination_pathname)
+          # NOTE: cp preserves the source mode. Templates installed read-only
+          # (e.g. NixOS /nix/store is 0444) would leave the author unable to
+          # edit their own project. Add owner-write; keep any exec bit.
+          destination_pathname.chmod(destination_pathname.stat.mode | 0o200)
         end
 
         reporter.info <<~HEREDOC

data/lib/trmnlp/commands/serve.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
-require 'selenium-webdriver'
-
 require_relative 'base'
 require_relative '../api_client'
 require_relative '../browser_pool'
+require_relative '../firefox_driver'
 
 module TRMNLP
   module Commands
@@ -20,7 +19,7 @@ module TRMNLP
 
         # Now we can configure things
         App.set(:context, context)
-        App.set(:browser_pool, BrowserPool.new(driver_factory: method(:build_firefox_driver)))
+        App.set(:browser_pool, BrowserPool.new(driver_factory: FirefoxDriver.method(:build)))
         App.set(:bind, options.bind)
         App.set(:port, options.port)
         permit_all_hosts if codespaces?
@@ -37,18 +36,6 @@ module TRMNLP
       def permit_all_hosts
         App.set(:host_authorization, { allow_if: ->(_env) { true } })
       end
-
-      def build_firefox_driver
-        options = Selenium::WebDriver::Firefox::Options.new
-        options.add_argument('--headless')
-        options.add_argument('--disable-web-security')
-        # Disable subpixel antialiasing — its colour fringing quantizes badly on 1-bit e-ink.
-        options.add_preference('gfx.text.disable-aa', true)
-        options.add_preference('gfx.text.subpixel-position.force-disabled', true)
-        Selenium::WebDriver.for(:firefox, options: options).tap do |driver|
-          driver.manage.window.maximize
-        end
-      end
     end
   end
 end

data/lib/trmnlp/firefox_driver.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'selenium-webdriver'
+
+module TRMNLP
+  # Builds the headless Firefox driver that screenshots rendered plugins.
+  # Shared by `trmnlp serve` (the PNG preview route) and `trmnlp build --png`.
+  module FirefoxDriver
+    module_function
+
+    def build
+      Selenium::WebDriver.for(:firefox, options:).tap do |driver|
+        driver.manage.window.maximize
+      end
+    end
+
+    def options
+      Selenium::WebDriver::Firefox::Options.new.tap do |opts|
+        opts.add_argument('--headless')
+        opts.add_argument('--disable-web-security')
+        # Subpixel antialiasing colour-fringes badly when quantized to 1-bit e-ink.
+        opts.add_preference('gfx.text.disable-aa', true)
+        opts.add_preference('gfx.text.subpixel-position.force-disabled', true)
+      end
+    end
+  end
+end

data/lib/trmnlp/poller.rb

@@ -25,7 +25,7 @@ module TRMNLP
     # and keep the preview server alive, not crash the user's session. We
     # deliberately swallow here and return {} so the renderer keeps rendering.
     rescue StandardError => e
-      reporter.info("warning: #{e.message}")
+      reporter.info(reporter.yellow("warning: #{e.message}"))
       {}
     end
 
@@ -34,7 +34,7 @@ module TRMNLP
     # NOTE: Same rationale as #poll_data — a bad webhook payload shouldn't take
     # down the dev server. Report a warning and keep serving.
     rescue StandardError => e
-      reporter.info("webhook warning: #{e.message}")
+      reporter.info(reporter.yellow("webhook warning: #{e.message}"))
     end
 
     private
@@ -76,7 +76,7 @@ module TRMNLP
       case content_type
       when 'application/json', %r{^application/.+\+json} then wrap_array(JSON.parse(body))
       when 'text/xml', 'application/xml', %r{^application/.+\+xml} then wrap_array(Hash.from_xml(body))
-      when 'text/html', 'text/plain' then sniff_json(body) || { 'text' => body }
+      when 'text/html', 'text/plain' then sniff_json(body) || { 'data' => body }
       else log_unknown_type(content_type_header)
       end
     end

data/lib/trmnlp/reporter.rb

@@ -11,6 +11,9 @@ module TRMNLP
       @quiet = quiet
       @stream = stream
       @messages = []
+      # Colour only when the stream is a real terminal, so ANSI codes
+      # never leak into piped or redirected output.
+      @tty = stream.tty?
     end
 
     def info(message)
@@ -20,9 +23,10 @@ module TRMNLP
 
     def green(text) = colorize(text, 32)
     def yellow(text) = colorize(text, 33)
+    def red(text) = colorize(text, 31)
 
     private
 
-    def colorize(text, code) = "\e[#{code}m#{text}\e[0m"
+    def colorize(text, code) = @tty ? "\e[#{code}m#{text}\e[0m" : text
   end
 end

data/lib/trmnlp/screenshot.rb

@@ -3,10 +3,13 @@
 require 'selenium-webdriver'
 require 'tempfile'
 
+require_relative 'errors'
+
 module TRMNLP
   class Screenshot
-    def initialize(pool:)
+    def initialize(pool:, viewport_timeout: 5)
       @pool = pool
+      @viewport_timeout = viewport_timeout
     end
 
     def call(html:, width:, height:)
@@ -50,15 +53,25 @@ module TRMNLP
     # NOTE: A cold Firefox — e.g. the first render after the container boots —
     # applies a window resize lazily. The old fixed sleep raced that reflow and
     # clipped the first screenshot short (800x433 instead of 800x480). Poll the
-    # real viewport instead, re-applying the size until it lands; a resize that
-    # never settles surfaces as a TimeoutError that #call already retries.
+    # real viewport instead, re-applying the size until it lands. A width the
+    # browser refuses to honour (below its ~500px window minimum) never settles;
+    # that surfaces as a clear RenderError rather than an opaque, retried timeout.
     def wait_for_viewport(driver, width, height)
-      Selenium::WebDriver::Wait.new(timeout: 5, interval: 0.1).until do
+      Selenium::WebDriver::Wait.new(timeout: @viewport_timeout, interval: 0.1).until do
         next true if viewport(driver) == [width, height]
 
         apply_window_size(driver, width, height)
         false
       end
+    rescue Selenium::WebDriver::Error::TimeoutError
+      raise RenderError, viewport_clamp_message(driver, width, height)
+    end
+
+    def viewport_clamp_message(driver, width, height)
+      actual_width, actual_height = viewport(driver)
+      "Could not render at #{width}x#{height}: the browser clamped the viewport " \
+        "to #{actual_width}x#{actual_height}. PNG rendering needs a width of " \
+        'roughly 500px or more — headless Firefox will not size its window narrower.'
     end
 
     def viewport(driver)

data/lib/trmnlp/version.rb

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

data/web/public/index.css

@@ -110,6 +110,11 @@ pre > code {
   margin: 0.5em 0 0.2em;
 }
 
+/* A coloured badge is a warning — full opacity so the colour reads true. */
+.payload-size--ok { color: #1a7f37; opacity: 1; }
+.payload-size--warn { color: #bf8700; opacity: 1; }
+.payload-size--over { color: #d1242f; opacity: 1; }
+
 @media (prefers-color-scheme: dark) {
   :root {
     --bg-color: #191b21;

data/web/views/index.erb

@@ -66,7 +66,7 @@
 
         <iframe style="width: 800px; height: 480px; border: 1px solid black; background: white;">Rendering…</iframe>
 
-        <div class="payload-size">Payload: <%= format_bytes(@payload_size) %></div>
+        <div class="payload-size <%= payload_size_class(@payload_size) %>">Payload: <%= format_bytes(@payload_size) %></div>
         <pre id="user-data"><code><%= h @user_data %></code></pre>
     </main>
 </body>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trmnl_preview
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Rockwell Schrock
@@ -284,6 +284,7 @@ files:
 - lib/trmnlp/config/project.rb
 - lib/trmnlp/context.rb
 - lib/trmnlp/errors.rb
+- lib/trmnlp/firefox_driver.rb
 - lib/trmnlp/form_field.rb
 - lib/trmnlp/framework_version.rb
 - lib/trmnlp/image_quantizer.rb