trmnl_preview 0.7.1 → 0.8.0

data/lib/trmnlp/transform_client.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  # Strategy host for serverless transform execution. Local plugin
+  # development hits the Subprocess backend by default — transforms
+  # run in trmnlp's own image alongside Ruby, no daemon required.
+  # Setting `serverless_daemon_url` in .trmnlp.yml swaps in the Http
+  # backend so plugin authors can target a real remote transform
+  # daemon (production parity testing, shared team daemons, etc.).
+  class TransformClient
+    # Mirrors the remote daemon's ExecResponse. `output` is the canonical
+    # JSON result; `stdout` carries user prints.
+    Result = Data.define(:stdout, :stderr, :output, :exit_code, :duration_ms, :error) do
+      def success? = error.nil? && exit_code.zero?
+    end
+
+    attr_reader :backend
+
+    # Returns nil when serverless is disabled in .trmnlp.yml so the
+    # pipeline can short-circuit without a per-request check.
+    def self.from_config(project_config)
+      runtime = project_config.transform_runtime
+      return nil if runtime.nil? || runtime.to_s == 'disabled'
+
+      new(backend: backend_for(project_config))
+    end
+
+    def self.backend_for(project_config)
+      if (url = project_config.serverless_daemon_url)
+        TransformBackend::Http.new(url: url, api_key: project_config.serverless_daemon_api_key)
+      else
+        TransformBackend::Subprocess.new
+      end
+    end
+
+    def initialize(backend:)
+      @backend = backend
+    end
+
+    def execute(code:, language:, stdin: '', timeout_seconds: 30)
+      backend.execute(code:, language:, stdin:, timeout_seconds:)
+    end
+  end
+end
+
+require_relative 'transform_backend/subprocess'
+require_relative 'transform_backend/http'

data/lib/trmnlp/transform_pipeline.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'reporter'
+require_relative 'transform_client'
+
+module TRMNLP
+  # Pipes assembled merge_variables through src/transform.{py,rb,php,js}
+  # when a serverless runtime is configured. Mirrors the hosted
+  # transform behavior: the transform receives the data (including the
+  # trmnl namespace) on stdin and its stdout JSON replaces the data.
+  # Failure modes surface via #error (rendered in the preview UI), not
+  # raised.
+  class TransformPipeline
+    attr_reader :error
+
+    def initialize(config:, paths:, reporter: Reporter.new)
+      @config = config
+      @paths = paths
+      @reporter = reporter
+    end
+
+    def call(data)
+      @error = nil
+      transform_path, inferred_language = paths.transform_file
+      return data unless transform_path && client
+
+      run(transform_path, inferred_language, data)
+    end
+
+    def reset! = @client = nil
+
+    private
+
+    attr_reader :config, :paths, :reporter
+
+    def client = @client ||= TransformClient.from_config(config.project)
+
+    def run(path, inferred_language, data)
+      language = config.plugin.serverless_language || inferred_language
+      result = client.execute(code: path.read, stdin: JSON.generate(data), language:)
+      return record_failure(result, data) unless result.success?
+
+      parse_output(result.output, data)
+    end
+
+    def record_failure(result, fallback)
+      @error = result.error || "transform exited #{result.exit_code}: #{result.stderr.strip}"
+      reporter.info("transform failed: #{@error}")
+      fallback
+    end
+
+    def parse_output(output, fallback)
+      transformed = JSON.parse(output)
+      transformed.is_a?(Hash) ? transformed : wrap_array(transformed)
+    rescue JSON::ParserError => e
+      @error = "transform produced non-JSON output: #{e.message}"
+      reporter.info(@error)
+      fallback
+    end
+
+    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+  end
+end

data/lib/trmnlp/user_data_assembler.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/time'
+require 'json'
+
+module TRMNLP
+  class UserDataAssembler
+    DEFAULT_DEVICE_WIDTH = 800
+    DEFAULT_DEVICE_HEIGHT = 480
+
+    def initialize(config:, paths:, transform_pipeline:)
+      @config = config
+      @paths = paths
+      @transform_pipeline = transform_pipeline
+    end
+
+    # Assembles the merged data hash. The trmnl namespace is built first,
+    # layered with static_data / cached polled data / user_data_overrides,
+    # then piped through the transform. The trmnl namespace is re-applied
+    # after the transform so device, user, and plugin_settings survive
+    # even when the transform doesn't pass them through.
+    def call(device: {})
+      namespace = base_trmnl_data(device:)
+      merged = assemble(namespace)
+      result = transform_pipeline.call(merged)
+      result['trmnl'] = namespace['trmnl']
+      result
+    end
+
+    def device_from_params(params)
+      { 'width' => params[:width]&.to_i, 'height' => params[:height]&.to_i }.compact
+    end
+
+    private
+
+    attr_reader :config, :paths, :transform_pipeline
+
+    def assemble(namespace)
+      data = namespace.dup
+      merge_source_data!(data)
+      data.deep_merge!(config.project.user_data_overrides)
+      data
+    end
+
+    def merge_source_data!(data)
+      if config.plugin.static?
+        data.merge!(config.plugin.static_data)
+      elsif paths.user_data.exist?
+        data.merge!(JSON.parse(paths.user_data.read))
+      end
+    end
+
+    def base_trmnl_data(device:)
+      { 'trmnl' => trmnl_namespace(device:) }
+    end
+
+    def trmnl_namespace(device:)
+      {
+        'user' => user_namespace,
+        'device' => device_namespace(device),
+        'system' => { 'timestamp_utc' => Time.now.utc.to_i },
+        'plugin_settings' => plugin_settings_namespace
+      }
+    end
+
+    def user_namespace
+      tz = ActiveSupport::TimeZone.find_tzinfo(config.project.time_zone)
+      iana = tz.name
+      {
+        'name' => 'name', 'first_name' => 'first_name', 'last_name' => 'last_name',
+        'locale' => 'en', 'time_zone' => ActiveSupport::TimeZone::MAPPING.invert[iana] || iana,
+        'time_zone_iana' => iana, 'utc_offset' => tz.utc_offset
+      }
+    end
+
+    def device_namespace(device)
+      {
+        'friendly_id' => 'ABC123', 'percent_charged' => 85.0, 'wifi_strength' => 90,
+        'height' => device['height'] || DEFAULT_DEVICE_HEIGHT,
+        'width' => device['width'] || DEFAULT_DEVICE_WIDTH
+      }
+    end
+
+    def plugin_settings_namespace
+      {
+        'instance_name' => 'instance_name',
+        'strategy' => config.plugin.strategy,
+        'dark_mode' => config.plugin.dark_mode,
+        'polling_headers' => config.plugin.polling_headers_encoded,
+        'polling_url' => config.plugin.polling_url_text,
+        'custom_fields_values' => config.project.custom_fields
+      }
+    end
+  end
+end

data/lib/trmnlp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TRMNLP
-  VERSION = "0.7.1".freeze
+  VERSION = '0.8.0'
 end

data/lib/trmnlp/watcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'filewatcher'
+
+require_relative 'reporter'
+
+module TRMNLP
+  class Watcher
+    def initialize(config:, user_data_assembler:, transform_pipeline:, reporter: Reporter.new)
+      @config = config
+      @user_data_assembler = user_data_assembler
+      @transform_pipeline = transform_pipeline
+      @reporter = reporter
+    end
+
+    def start
+      @start ||= Thread.new { run }
+    end
+
+    def on_change(&block)
+      @view_change_callback = block
+    end
+
+    private
+
+    attr_reader :config, :user_data_assembler, :transform_pipeline, :reporter
+
+    def run
+      loop do
+        watch_cycle
+      rescue StandardError => e
+        reporter.info("error during live render: #{e}")
+      end
+    end
+
+    def watch_cycle
+      Filewatcher.new(config.project.watch_paths).watch do |changes|
+        reload_config!
+        notify(changes)
+      end
+    end
+
+    def reload_config!
+      config.project.reload!
+      config.plugin.reload!
+      transform_pipeline.reset! # config may have changed runtime config
+    end
+
+    # NOTE: transform.* changes don't trigger a re-poll — the transform
+    # runs inside user_data on every render against the cached polled
+    # response (or static_data), so editing the transform updates the
+    # preview without re-fetching the API.
+    def notify(changes)
+      data = user_data_assembler.call
+      return unless @view_change_callback
+
+      changes.each_key { |path| @view_change_callback.call(File.basename(path, '.liquid'), data) }
+    end
+  end
+end

data/lib/trmnlp.rb

@@ -2,13 +2,9 @@
 
 module TRMNLP; end
 require 'oj'
-Oj.mimic_JSON()
-require_relative "trmnlp/config"
-require_relative "trmnlp/context"
-require_relative "trmnlp/version"
-
-module TRMNLP
-  VIEWS = %w{full half_horizontal half_vertical quadrant}
-
-  class Error < StandardError; end
-end
+Oj.mimic_JSON
+require_relative 'trmnlp/errors'
+require_relative 'trmnlp/config'
+require_relative 'trmnlp/context'
+require_relative 'trmnlp/screen'
+require_relative 'trmnlp/version'

data/templates/init/bin/trmnlp

@@ -1,4 +1,4 @@
-#! /bin/bash
+#!/usr/bin/env bash
 #
 # This script was automatically generated by `trmnlp init` but it's yours to modify!
 # Use this opportunity to set up environment variables, install dependencies, etc.

data/templates/init/src/settings.yml

@@ -9,6 +9,7 @@ no_screen_padding: 'no'
 dark_mode: 'no'
 static_data: ''
 polling_verb: get
+framework_version: latest
 polling_url: ''
 polling_headers: ''
 name: My Plugin

data/templates/init/src/transform.py.example

@@ -0,0 +1,14 @@
+# Optional serverless transform.
+# Rename this file to `transform.py` (or transform.rb / transform.php / transform.js)
+# and it runs automatically — serverless transforms are enabled by default.
+# (Set `transform_runtime: disabled` in .trmnlp.yml to turn them off.)
+#
+# Define a `run(input)` function that takes the polled response (parsed
+# JSON, including the trmnl namespace) and returns any JSON-serialisable
+# value. The bundled transform-runtime wraps this and handles stdin/stdout.
+# This matches the hosted serverless contract — the same code runs in production.
+
+
+def run(input):
+    # Reshape `input` however you like, then return.
+    return input

data/trmnl_preview.gemspec

@@ -1,27 +1,29 @@
 # frozen_string_literal: true
 
-require_relative "lib/trmnlp/version"
+require_relative 'lib/trmnlp/version'
 
 Gem::Specification.new do |spec|
-  spec.name = "trmnl_preview"
+  spec.name = 'trmnl_preview'
   spec.version = TRMNLP::VERSION
-  spec.authors = ["Rockwell Schrock"]
-  spec.email = ["rockwell@schrock.me"]
+  spec.authors = ['Rockwell Schrock']
+  spec.email = ['rockwell@schrock.me']
 
-  spec.summary = "Local web server to preview TRMNL plugins"
-  spec.description = "Automatically rebuild and preview TRNML plugins in multiple views"
-  spec.homepage = "https://github.com/usetrmnl/trmnlp"
-  spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.summary = 'Local web server to preview TRMNL plugins'
+  spec.description = 'Automatically rebuild and preview TRNML plugins in multiple views'
+  spec.homepage = 'https://github.com/usetrmnl/trmnlp'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
 
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/usetrmnl/trmnlp"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/usetrmnl/trmnlp'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 
   spec.files = Dir.chdir(__dir__) do
     [
       'bin/**/*',
+      'db/**/*',
       'lib/**/*',
       'templates/**/{*,.*}',
       'web/**/*',
@@ -31,37 +33,35 @@ Gem::Specification.new do |spec|
       'trmnl_preview.gemspec'
     ].flat_map { |glob| Dir[glob] }
   end
-  spec.bindir = "bin"
-  spec.executables = ["trmnlp"]
-  spec.require_paths = ["lib"]
-
+  spec.bindir = 'bin'
+  spec.executables = ['trmnlp']
+  spec.require_paths = ['lib']
 
   # Web server
-  spec.add_dependency "sinatra", "~> 4.1"
-  spec.add_dependency "rackup", "~> 2.2"
-  spec.add_dependency "puma", "~> 6.5"
-  spec.add_dependency "faye-websocket", "~> 0.11.3"
+  spec.add_dependency 'puma', '~> 8.0'
+  spec.add_dependency 'rackup', '~> 2.2'
+  spec.add_dependency 'sinatra', '~> 4.1'
 
   # HTML rendering
-  spec.add_dependency "activesupport", "~> 8.0"
-  spec.add_dependency "trmnl-liquid", "~> 0.4.0"
+  spec.add_dependency 'activesupport', '~> 8.0'
+  spec.add_dependency 'trmnl-liquid', '~> 0.7.0'
 
   # PNG rendering
   # spec.add_dependency 'puppeteer-ruby', '~> 0.45.6'
-  spec.add_dependency 'selenium-webdriver', '~> 4.39'
-  spec.add_dependency 'mini_magick', '~> 4.12.0'
+  spec.add_dependency 'mini_magick', '~> 5.3'
+  spec.add_dependency 'selenium-webdriver', '~> 4.44'
 
   # Utilities
-  spec.add_dependency "filewatcher", "~> 2.1"
-  spec.add_dependency "faraday", "~> 2.1"
-  spec.add_dependency "faraday-multipart", "~> 1.1"
-  spec.add_dependency "xdg", "~> 9.1"
-  spec.add_dependency "rubyzip", "~> 2.3.0"
-  spec.add_dependency "thor", "~> 1.3"
-  spec.add_dependency "oj", "~> 3.16.9"
-  spec.add_dependency "tzinfo-data", "~> 1.2025"
-  spec.add_dependency "pathname", "~> 0.4"
-  spec.add_dependency "rexml", "~> 3.4"
+  spec.add_dependency 'cgi', '~> 0.5'
+  spec.add_dependency 'faraday', '~> 2.1'
+  spec.add_dependency 'faraday-multipart', '~> 1.1'
+  spec.add_dependency 'filewatcher', '~> 3.0'
+  spec.add_dependency 'oj', '~> 3.17'
+  spec.add_dependency 'rexml', '~> 3.4'
+  spec.add_dependency 'rubyzip', '~> 3.3'
+  spec.add_dependency 'thor', '~> 1.3'
+  spec.add_dependency 'tzinfo-data', '~> 1.2025'
+  spec.add_dependency 'xdg', '~> 10.2'
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html

data/web/public/index.css

@@ -104,6 +104,12 @@ pre > code {
   }
 }
 
+.payload-size {
+  font-size: 0.85em;
+  opacity: 0.6;
+  margin: 0.5em 0 0.2em;
+}
+
 @media (prefers-color-scheme: dark) {
   :root {
     --bg-color: #191b21;

data/web/public/index.js

@@ -1,14 +1,15 @@
 const trmnlp = {};
 
 trmnlp.connectLiveRender = function () {
-  const ws = new WebSocket("/live_reload");
+  // EventSource reconnects automatically, so no manual retry loop is needed.
+  const source = new EventSource("/live_reload");
 
-  ws.onopen = function () {
-    console.log("Connected to live reload socket");
+  source.onopen = function () {
+    console.log("Connected to live reload stream");
   };
 
-  ws.onmessage = function (msg) {
-    const payload = JSON.parse(msg.data);
+  source.onmessage = function (event) {
+    const payload = JSON.parse(event.data);
 
     if (payload.type === "reload") {
       trmnlp.fetchPreview();
@@ -16,37 +17,48 @@ trmnlp.connectLiveRender = function () {
       hljs.highlightAll();
     }
   };
-
-  ws.onclose = function () {
-    console.log("Reconnecting to live reload socket...");
-    setTimeout(trmnlp.connectLiveRender, 1000);
-  };
 };
 
 
 trmnlp.fetchPreview = function (pickerState) {
-  const screenClasses = (pickerState?.screenClasses || trmnlp.picker.state.screenClasses).join(" ");
+  const state = pickerState || trmnlp.picker?.state;
+  const screenClasses = (state?.screenClasses || []).join(" ");
   const encodedScreenClasses = encodeURIComponent(screenClasses);
   let src = `/render/${trmnlp.view}.${trmnlp.formatSelect.value}?screen_classes=${encodedScreenClasses}`;
 
-  // If requesting a PNG, also include dimensions, dark mode, and color depth
-  if (trmnlp.formatSelect.value === 'png') {
-    const state = pickerState || trmnlp.picker.state;
+  // Pass dimensions for both HTML and PNG renders so trmnl.device.{width,height}
+  // in the Liquid context tracks the picker model selection.
+  if (state) {
     const width = encodeURIComponent(state.width);
     const height = encodeURIComponent(state.height);
-    const isDarkMode = state.isDarkMode ? 1 : 0;
+    src += `&width=${width}&height=${height}`;
+  }
 
-    // derive numeric color depth from classes like 'screen--1bit'
+  // PNG-only: dark mode + color depth from palette
+  if (trmnlp.formatSelect.value === 'png' && state) {
+    const isDarkMode = state.isDarkMode ? 1 : 0;
     const grays = state.palette.grays || 2;
     const colorDepth = Math.ceil(Math.log2(grays));
-
-    src += `&width=${width}&height=${height}&color_depth=${colorDepth}`;
+    src += `&color_depth=${colorDepth}`;
   }
 
   trmnlp.spinner.style.display = "inline-block";
   trmnlp.iframe.src = src;
 };
 
+trmnlp.refreshUserData = async function (state) {
+  if (!state) return;
+  const params = new URLSearchParams({ width: state.width, height: state.height });
+  try {
+    const response = await fetch(`/data?${params}`);
+    if (!response.ok) return;
+    trmnlp.userData.textContent = await response.text();
+    hljs.highlightAll();
+  } catch (e) {
+    console.warn("Failed to refresh user-data:", e);
+  }
+};
+
 document.addEventListener("DOMContentLoaded", async function () {
   trmnlp.view = document.querySelector("meta[name='trmnl-view']").content;
   trmnlp.iframe = document.querySelector("iframe");
@@ -77,6 +89,7 @@ document.addEventListener("DOMContentLoaded", async function () {
     trmnlp.iframe.style.height = `${event.detail.height}px`;
 
     trmnlp.fetchPreview(event.detail);
+    trmnlp.refreshUserData(event.detail);
   });
 
   trmnlp.picker = await TRMNLPicker.create('picker-form', { localStorageKey: 'trmnlp-picker' });

data/web/views/index.erb

@@ -60,9 +60,14 @@
             </div>
         </menu>
 
+        <% if @transform_error %>
+          <div class="transform-error" style="padding: 0.5em 0.75em; margin: 0.5em 0; background: #fee; border: 1px solid #c33; border-radius: 4px; color: #900; font-family: monospace; white-space: pre-wrap;">Transform error: <%= h @transform_error %></div>
+        <% end %>
+
         <iframe style="width: 800px; height: 480px; border: 1px solid black; background: white;">Rendering…</iframe>
 
-        <pre id="user-data"><code><%= @user_data %></code></pre>
+        <div class="payload-size">Payload: <%= format_bytes(@payload_size) %></div>
+        <pre id="user-data"><code><%= h @user_data %></code></pre>
     </main>
 </body>
 </html>

data/web/views/render_html.erb

@@ -1,8 +1,10 @@
 <!DOCTYPE html>
 <html>
   <head>
-    <link rel="stylesheet" href="https://trmnl.com/css/latest/plugins.css" />
-    <script src="https://trmnl.com/js/latest/plugins.js"></script>
+    <link rel="stylesheet" href="<%= @framework.css_url %>" />
+    <script src="<%= @framework.js_url %>"></script>
+    <meta name="trmnl-framework-version" content="<%= @framework.number %>" />
+    <meta name="trmnl-framework-pinned" content="<%= @framework.pinned? %>" />
 
     <!-- Begin Inter font -->
     <link rel="preconnect" href="https://fonts.googleapis.com">