trmnl_preview 0.14.2 → 0.16.0

data/lib/trmnlp/screenshot.rb

@@ -7,6 +7,26 @@ require_relative 'errors'
 
 module TRMNLP
   class Screenshot
+    # TRMNL's Converter::Html waits for these flags, longer for a map, then captures what is drawn.
+    READINESS_TIMEOUT_SECONDS = 5
+    READINESS_TIMEOUT_WITH_MAPS_SECONDS = 12
+    MAPS_DOCUMENT_PATTERN = %r{TRMNLMaps\.[a-z]|maplibre-gl(?:\.js|\.css|[/@]\d)}
+    READINESS_CHECK_SCRIPT = <<~JS
+      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.
+    FREEZE_TIMERS = <<~JS
+      const 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); }
+      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)
       @pool = pool
       @viewport_timeout = viewport_timeout
@@ -87,16 +107,21 @@ module TRMNLP
         document.close();
       JS
 
-      Selenium::WebDriver::Wait.new(timeout: 5).until do
-        driver.execute_script('return document.readyState') == 'complete'
-      end
-
+      wait_until_ready(driver, html)
       driver.execute_script('return document.fonts && document.fonts.ready')
 
       driver.execute_script(<<~JS)
         document.documentElement.style.overflow = 'hidden';
         document.body.style.overflow = 'hidden';
       JS
+      driver.execute_script(FREEZE_TIMERS)
+    end
+
+    def wait_until_ready(driver, html)
+      timeout = html.match?(MAPS_DOCUMENT_PATTERN) ? READINESS_TIMEOUT_WITH_MAPS_SECONDS : READINESS_TIMEOUT_SECONDS
+      Selenium::WebDriver::Wait.new(timeout:, interval: 0.05).until { driver.execute_script(READINESS_CHECK_SCRIPT) }
+    rescue Selenium::WebDriver::Error::TimeoutError
+      nil
     end
 
     def capture(driver)

data/lib/trmnlp/select_field_choices.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TRMNLP
+  # A select field's options as TRMNL saves them: "New York" as new_york, { Label: value } as its value.
+  class SelectFieldChoices
+    def initialize(field)
+      options = field['options']
+      @options = options.is_a?(Array) ? options.compact : []
+    end
+
+    def pairs
+      @pairs ||= @options.map do |option|
+        option.is_a?(Hash) ? [option.keys.first, option.values.first] : [option, option.to_s.downcase.tr(' ', '_')]
+      end
+    end
+
+    # A label becomes its value; a value, or anything the options do not list, is kept as it is.
+    def stored_value(input)
+      return input.map { stored_value(it) } if input.is_a?(Array)
+      return input if input.to_s.empty? || pairs.any? { |_, value| value.to_s == input.to_s }
+
+      pairs.find { |label, _| label.to_s == input.to_s }&.last&.to_s || input
+    end
+  end
+end

data/lib/trmnlp/transform_pipeline.rb

@@ -4,6 +4,7 @@ require 'json'
 
 require_relative 'reporter'
 require_relative 'transform_client'
+require_relative 'transform_state'
 
 module TRMNLP
   # Pipes assembled merge_variables through src/transform.{py,rb,php,js}
@@ -13,12 +14,16 @@ module TRMNLP
   # Failure modes surface via #error (rendered in the preview UI), not
   # raised.
   class TransformPipeline
+    # TRMNL's serverless runtime stops a transform after this long.
+    EXECUTION_TIMEOUT_SECONDS = 5
+
     attr_reader :error
 
     def initialize(config:, paths:, reporter: Reporter.new)
       @config = config
       @paths = paths
       @reporter = reporter
+      @transform_state = TransformState.new(paths:, reporter:)
     end
 
     def call(data)
@@ -29,17 +34,27 @@ module TRMNLP
       run(transform_path, inferred_language, data)
     end
 
+    def configured? = !paths.transform_file.first.nil? && !client.nil?
+
+    # What the last run stored for the markup, passed to the next run as trmnl.previous_merge_variables.
+    def previous_output
+      paths.transform_output.exist? ? JSON.parse(paths.transform_output.read) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
     def reset! = @client = nil
 
     private
 
-    attr_reader :config, :paths, :reporter
+    attr_reader :config, :paths, :reporter, :transform_state
 
     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:)
+      result = client.execute(code: path.read, stdin: JSON.generate(data), language:,
+                              timeout_seconds: EXECUTION_TIMEOUT_SECONDS)
       report_printed_output(result)
       return record_failure(result, data) unless result.success?
 
@@ -56,18 +71,44 @@ module TRMNLP
     def record_failure(result, fallback)
       @error = result.error || "transform exited #{result.exit_code}: #{result.stderr.strip}"
       reporter.info("transform failed: #{result.error || "exited #{result.exit_code}"}")
-      fallback
+      last_good_output(fallback)
     end
 
+    # TRMNL keeps the last good screen when a transform fails.
+    def last_good_output(fallback) = paths.transform_output.exist? ? previous_output : fallback
+
     def parse_output(output, fallback)
       transformed = JSON.parse(output)
-      transformed.is_a?(Hash) ? transformed : wrap_array(transformed)
+      return reject_non_object_output unless transformed.is_a?(Hash)
+
+      transform_state.extract!(transformed)
+      store_output(without_previous_merge_variables(transformed))
     rescue JSON::ParserError => e
       @error = "transform produced non-JSON output: #{e.message}"
       reporter.info(@error)
-      fallback
+      last_good_output(fallback)
     end
 
-    def wrap_array(json) = json.is_a?(Array) ? { data: json } : json
+    # TRMNL renders nothing from an array or a scalar, and refuses one from a webhook post.
+    def reject_non_object_output
+      @error = 'Transform output must be a JSON object'
+      reporter.info(@error)
+      {}
+    end
+
+    def store_output(output)
+      paths.transform_output.dirname.mkpath
+      paths.transform_output.write(JSON.generate(output))
+      output
+    end
+
+    # A transform that echoes its input at any depth (`{ data: input }`) would store its history and double every run.
+    def without_previous_merge_variables(value)
+      case value
+      when Hash then value.except('previous_merge_variables').transform_values { without_previous_merge_variables(it) }
+      when Array then value.map { without_previous_merge_variables(it) }
+      else value
+      end
+    end
   end
 end

data/lib/trmnlp/transform_state.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'reporter'
+
+module TRMNLP
+  # The `trmnl_state` key a transform returns is kept for its next run as trmnl.state instead of rendered.
+  class TransformState
+    KEY = 'trmnl_state'
+    MAX_BYTES = 8 * 1024
+
+    def initialize(paths:, reporter: Reporter.new)
+      @paths = paths
+      @reporter = reporter
+    end
+
+    def read
+      paths.transform_state.exist? ? JSON.parse(paths.transform_state.read) : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def extract!(output)
+      return unless output.is_a?(Hash) && output.key?(KEY)
+
+      state = output.delete(KEY)
+      rejection = rejection_reason(state)
+      rejection ? reporter.info(reporter.yellow("Ignored #{KEY}: #{rejection}")) : write(state)
+    end
+
+    private
+
+    attr_reader :paths, :reporter
+
+    def rejection_reason(state)
+      return "expected an object, got #{state.class}" unless state.is_a?(Hash)
+
+      size = JSON.generate(state).bytesize
+      "#{size} bytes exceeds the #{MAX_BYTES} byte limit" if size > MAX_BYTES
+    end
+
+    def write(state)
+      paths.transform_state.dirname.mkpath
+      paths.transform_state.write(JSON.generate(state))
+    end
+  end
+end

data/lib/trmnlp/user_data_assembler.rb

@@ -4,15 +4,20 @@ require 'active_support'
 require 'active_support/time'
 require 'json'
 
+require_relative 'merged_plugin_locals'
+require_relative 'transform_state'
+
 module TRMNLP
   class UserDataAssembler
     DEFAULT_DEVICE_WIDTH = 800
     DEFAULT_DEVICE_HEIGHT = 480
 
-    def initialize(config:, paths:, transform_pipeline:)
+    def initialize(config:, paths:, transform_pipeline:, oauth_session: nil)
       @config = config
       @paths = paths
       @transform_pipeline = transform_pipeline
+      @oauth_session = oauth_session
+      @transform_state = TransformState.new(paths:)
     end
 
     # Assembles the merged data hash. The trmnl namespace is built first,
@@ -21,41 +26,61 @@ module TRMNLP
     # (overrides included) is re-applied after the transform so it
     # survives even when the transform doesn't pass it through.
     def call(device: {})
-      namespace = base_trmnl_data(device:)
-      merged = assemble(namespace)
-      result = transform_pipeline.call(transform_input(merged))
-      result['trmnl'] = merged['trmnl']
+      merged = assemble(base_trmnl_data(device:), source_data)
+      runs_transform = config.plugin.transforms_on_render? && transform_pipeline.configured?
+      result = runs_transform ? transform_pipeline.call(transform_input(merged)) : merged.except('trmnl')
+      # The markup renders the state this run's transform kept, as on TRMNL.
+      result['trmnl'] = merged['trmnl'].merge('state' => transform_state.read)
       result
     end
 
+    def transform_webhook_post(merge_variables)
+      transform_pipeline.call(transform_input(assemble(base_trmnl_data(device: {}), merge_variables)))
+    end
+
+    # What a polling url, its headers and its body render with on TRMNL.
+    def polling_variables = assemble(base_trmnl_data(device: {}), {}).slice('trmnl')
+
     def device_from_params(params)
-      { 'width' => params[:width]&.to_i, 'height' => params[:height]&.to_i,
-        'model' => params[:model], 'bit_depth' => params[:bit_depth]&.to_i }.compact
+      { 'width' => params[:width]&.to_i, 'height' => params[:height]&.to_i, 'model' => params[:model],
+        'bit_depth' => params[:bit_depth]&.to_i, 'orientation' => params[:orientation] }.compact
     end
 
     private
 
-    attr_reader :config, :paths, :transform_pipeline
+    attr_reader :config, :paths, :transform_pipeline, :transform_state, :oauth_session
 
-    def assemble(namespace)
-      data = namespace.dup
-      merge_source_data!(data)
-      data.deep_merge!(config.project.user_data_overrides)
-      data
+    # The trmnl namespace wins over a trmnl key in the fetched data, as on TRMNL; only .trmnlp.yml overrides it.
+    def assemble(namespace, source)
+      source.merge(namespace).deep_merge(config.project.user_data_overrides)
     end
 
-    # The hosted service exposes only user/device/plugin_settings to the
+    # The hosted service exposes only user/device/plugin_settings/state to the
     # transform; the system namespace is added afterward. Mirror that slice
     # so transforms behave the same locally as in production.
     def transform_input(merged)
-      merged.merge('trmnl' => merged['trmnl'].slice('user', 'device', 'plugin_settings'))
+      trmnl = merged['trmnl'].slice('user', 'device', 'plugin_settings', 'state')
+      trmnl['previous_merge_variables'] = previous_merge_variables
+      oauth = oauth_for_transform
+      trmnl['oauth'] = oauth unless oauth.empty?
+      merged.merge('trmnl' => trmnl)
     end
 
-    def merge_source_data!(data)
+    # The connected account's token, so a transform can make its own authenticated calls.
+    def oauth_for_transform = (oauth_session&.liquid_variables || {}).transform_keys { it.delete_prefix('oauth_') }
+
+    # What the last run stored for the markup: a webhook's stored data, otherwise the last transform output.
+    def previous_merge_variables = config.plugin.webhook? ? source_data : transform_pipeline.previous_output
+
+    def source_data
       if config.plugin.static?
-        data.merge!(config.plugin.static_data)
+        config.plugin.static_data
+      elsif config.plugin.plugin_merge?
+        MergedPluginLocals.new(config:, paths:).call
       elsif paths.user_data.exist?
-        data.merge!(JSON.parse(paths.user_data.read))
+        JSON.parse(paths.user_data.read)
+      else
+        {}
       end
     end
 
@@ -68,7 +93,8 @@ module TRMNLP
         'user' => user_namespace,
         'device' => device_namespace(device),
         'system' => { 'timestamp_utc' => Time.now.utc.to_i },
-        'plugin_settings' => plugin_settings_namespace
+        'plugin_settings' => plugin_settings_namespace,
+        'state' => transform_state.read
       }
     end
 
@@ -89,21 +115,33 @@ module TRMNLP
         'height' => device['height'] || DEFAULT_DEVICE_HEIGHT,
         'width' => device['width'] || DEFAULT_DEVICE_WIDTH,
         'model' => device['model'] || 'og_plus', 'bit_depth' => device['bit_depth'] || 2,
-        'firmware_version' => '1.6.3', 'refresh_interval_seconds' => 900,
+        'orientation' => device['orientation'] || 'landscape',
+        'firmware_version' => '1.8.17', 'refresh_interval_seconds' => 900,
         'sleep_mode_enabled' => false, 'sleep_start_time' => 1320, 'sleep_end_time' => 480
       }
     end
 
     def plugin_settings_namespace
       {
-        'instance_name' => 'instance_name',
+        'instance_name' => config.plugin.settings['name'],
         'refresh_interval_minutes' => config.plugin.refresh_interval,
         '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
-      }
+        'no_screen_padding' => config.plugin.no_screen_padding
+      }.merge(custom_fields_setting, polling_url_setting, data_fetched_setting)
+    end
+
+    def custom_fields_setting
+      values = config.plugin.custom_fields_values
+      values.empty? ? {} : { 'custom_fields_values' => values }
+    end
+
+    # The polling url can carry the author's API key, so TRMNL exposes it only to a polling plugin.
+    def polling_url_setting = config.plugin.polling? ? { 'polling_url' => config.plugin.polling_url_text } : {}
+
+    def data_fetched_setting
+      fetched = !config.plugin.static? && paths.user_data.exist?
+      fetched ? { 'data_fetched_utc' => paths.user_data.mtime.to_i } : {}
     end
   end
 end

data/lib/trmnlp/version.rb

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

data/lib/trmnlp/watcher.rb

@@ -67,7 +67,8 @@ module TRMNLP
     # 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.
+    # preview without re-fetching the API. A webhook plugin's transform
+    # runs only when a post arrives, as on TRMNL.
     def notify(changes)
       data = user_data_assembler.call
       return unless @view_change_callback

data/lib/trmnlp/webhook_payload.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+require 'json'
+
+module TRMNLP
+  # A webhook post as TRMNL takes it: merge_variables inside an object, merged into the
+  # stored data under merge_strategy, which the body or the query string may carry.
+  class WebhookPayload
+    MERGE_STRATEGIES = [nil, 'replace', 'deep_merge', 'stream'].freeze
+    STORED_SIZE_LIMIT_BYTES = 5 * 1024
+
+    def initialize(body, params = {})
+      @params = params.to_h.merge(body.is_a?(Hash) ? body : {})
+    end
+
+    def rejection
+      strategy = params['merge_strategy']
+      return "Invalid merge_strategy: '#{strategy}'" unless MERGE_STRATEGIES.include?(strategy)
+
+      case merge_variables
+      when Hash then nil
+      when nil, Array then 'Must be nested inside a merge_variables payload object'
+      when String then "Received string: '#{merge_variables}', expecting object"
+      else 'Expected an object payload'
+      end
+    end
+
+    def merge_variables
+      return @merge_variables if defined?(@merge_variables)
+
+      value = params['merge_variables']
+      @merge_variables = value.is_a?(String) ? (parsed_object(value) || value) : value
+    end
+
+    # A serverless webhook merges its transform output in place of the posted merge_variables.
+    def merged_into(stored, incoming = merge_variables)
+      case merge_strategy
+      when 'deep_merge' then stored.deep_merge(incoming)
+      when 'stream' then streamed_into(stored, incoming)
+      else incoming
+      end
+    end
+
+    # TRMNL refuses a post past its plan's limit; trmnlp cannot know the plan, so it only warns.
+    def size_warning(merged)
+      size = JSON.generate(merged).bytesize
+      "#{size} bytes stored; TRMNL rejects more than 5 kB (10 kB with TRMNL+)" if size > STORED_SIZE_LIMIT_BYTES
+    end
+
+    private
+
+    attr_reader :params
+
+    def merge_strategy = params['deep_merge'].to_s == 'true' ? 'deep_merge' : params['merge_strategy']
+
+    def parsed_object(text)
+      parsed = JSON.parse(text)
+      parsed if parsed.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def streamed_into(stored, incoming)
+      limit = params['stream_limit'].to_i
+      incoming.to_h do |key, value|
+        next [key, value] unless stored[key].is_a?(Array) && value.is_a?(Array)
+
+        combined = stored[key] + value
+        [key, limit.positive? ? combined.last(limit) : combined]
+      end
+    end
+  end
+end

data/lib/trmnlp/webhook_receiver.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'reporter'
+require_relative 'webhook_payload'
+
+module TRMNLP
+  # Takes a webhook post the way TRMNL does: a serverless plugin transforms the post once, as it
+  # arrives, and the result is merged into the stored data. Answers TRMNL's status and JSON body.
+  class WebhookReceiver
+    MAX_SERVERLESS_INCOMING_BYTES = 1024 * 1024
+
+    def initialize(paths:, transform_pipeline:, user_data_assembler:, reporter: Reporter.new)
+      @paths = paths
+      @transform_pipeline = transform_pipeline
+      @user_data_assembler = user_data_assembler
+      @reporter = reporter
+    end
+
+    def call(body, params = {})
+      payload = WebhookPayload.new(JSON.parse(body), params)
+      return reject(payload, payload.rejection) if payload.rejection
+      return store(payload, payload.merge_variables) unless transform_pipeline.configured?
+
+      transform_and_store(payload)
+    rescue JSON::ParserError => e
+      report_warning(e.message)
+      [400, { message: e.message }]
+    end
+
+    private
+
+    attr_reader :paths, :transform_pipeline, :user_data_assembler, :reporter
+
+    def transform_and_store(payload)
+      oversized = serverless_size_rejection(payload)
+      return reject(payload, oversized) if oversized
+
+      transformed = user_data_assembler.transform_webhook_post(payload.merge_variables)
+      # TRMNL answers before its transform runs, so a failure keeps the stored data and never reaches the poster.
+      if transform_pipeline.error
+        report_warning("Transform failed: #{transform_pipeline.error}")
+      else
+        store(payload, transformed)
+      end
+      [200, { message: nil, merge_variables: payload.merge_variables, processing: 'serverless' }]
+    end
+
+    def serverless_size_rejection(payload)
+      size = JSON.generate(payload.merge_variables).bytesize
+      "Large payload received (#{size} bytes), should be less than 1mb." if size > MAX_SERVERLESS_INCOMING_BYTES
+    end
+
+    def store(payload, incoming)
+      merged = payload.merged_into(stored_data, incoming)
+      payload.size_warning(merged)&.then { report_warning(it) }
+      paths.user_data.dirname.mkpath
+      paths.user_data.write(JSON.generate(merged))
+      [200, { message: nil, merge_variables: merged }]
+    end
+
+    def reject(payload, message)
+      report_warning(message)
+      posted = payload.merge_variables.nil? ? [] : payload.merge_variables
+      [422, { message:, merge_variables: stored_data.empty? ? posted : stored_data }]
+    end
+
+    def stored_data
+      stored = paths.user_data.exist? ? JSON.parse(paths.user_data.read) : {}
+      stored.is_a?(Hash) ? stored : {}
+    rescue JSON::ParserError
+      {}
+    end
+
+    def report_warning(message) = reporter.info(reporter.yellow("webhook warning: #{message}"))
+  end
+end

data/lib/trmnlp.rb

@@ -4,7 +4,7 @@ module TRMNLP; end
 require 'oj'
 require 'trmnl/liquid'
 Oj.mimic_JSON
-TRMNL::Liquid::RailsHelpers = Module.new unless defined?(TRMNL::Liquid::RailsHelpers)
+require_relative 'trmnlp/rails_helpers'
 require_relative 'trmnlp/errors'
 require_relative 'trmnlp/oauth'
 require_relative 'trmnlp/config'

data/trmnl_preview.gemspec

@@ -47,6 +47,9 @@ Gem::Specification.new do |spec|
 
   # HTML rendering
   spec.add_dependency 'activesupport', '~> 8.0'
+  spec.add_dependency 'crass', '~> 1.0'
+  spec.add_dependency 'csv', '~> 3.3'
+  spec.add_dependency 'nokogiri', '~> 1.18'
   spec.add_dependency 'trmnl-liquid', '~> 0.8.2'
 
   # PNG rendering

data/web/public/index.js

@@ -23,7 +23,8 @@ trmnlp.connectLiveRender = function () {
 // trmnl.device values the picked model and palette decide.
 trmnlp.deviceParams = function (state) {
   const bitDepth = Math.ceil(Math.log2(state.palette?.grays || 2));
-  return new URLSearchParams({ width: state.width, height: state.height, model: state.model.name, bit_depth: bitDepth });
+  const orientation = state.isPortrait ? 'portrait' : 'landscape';
+  return new URLSearchParams({ width: state.width, height: state.height, model: state.model.name, bit_depth: bitDepth, orientation });
 };
 
 trmnlp.fetchPreview = function (pickerState) {
@@ -31,6 +32,7 @@ trmnlp.fetchPreview = function (pickerState) {
   const screenClasses = (state?.screenClasses || []).join(" ");
   const encodedScreenClasses = encodeURIComponent(screenClasses);
   let src = `/render/${trmnlp.view}.${trmnlp.formatSelect.value}?screen_classes=${encodedScreenClasses}`;
+  if (trmnlp.themeSelect.value) src += `&theme=${encodeURIComponent(trmnlp.themeSelect.value)}`;
 
   // Pass the device for both HTML and PNG renders so trmnl.device.{width,height,model,bit_depth}
   // in the Liquid context tracks the picker model selection.
@@ -38,9 +40,8 @@ trmnlp.fetchPreview = function (pickerState) {
     src += `&${trmnlp.deviceParams(state)}`;
   }
 
-  // PNG-only: dark mode + color depth from palette
+  // PNG-only: 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 += `&color_depth=${colorDepth}`;
@@ -214,9 +215,13 @@ trmnlp.addSelectFieldRow = function (container, key, selectedValue, options) {
   const row = document.createElement('div');
   row.className = 'custom-field-row';
 
-  const optionsHtml = options.map(opt => {
-    const selected = String(opt) === String(selectedValue) ? 'selected' : '';
-    return `<option value="${trmnlp.escapeHtml(String(opt))}" ${selected}>${trmnlp.escapeHtml(String(opt))}</option>`;
+  // Saved as TRMNL saves them: "New York" as new_york, { Label: value } as its value.
+  const choices = options.map(opt => (opt && typeof opt === 'object')
+    ? [String(Object.keys(opt)[0]), String(Object.values(opt)[0])]
+    : [String(opt), String(opt).toLowerCase().replaceAll(' ', '_')]);
+  const optionsHtml = choices.map(([label, value]) => {
+    const selected = [label, value].includes(String(selectedValue)) ? 'selected' : '';
+    return `<option value="${trmnlp.escapeHtml(value)}" ${selected}>${trmnlp.escapeHtml(label)}</option>`;
   }).join('');
 
   row.innerHTML = `
@@ -261,6 +266,7 @@ document.addEventListener("DOMContentLoaded", async function () {
   trmnlp.view = document.querySelector("meta[name='trmnl-view']").content;
   trmnlp.iframe = document.querySelector("iframe");
   trmnlp.formatSelect = document.querySelector(".select-format");
+  trmnlp.themeSelect = document.querySelector("[data-theme-select]");
   trmnlp.userData = document.getElementById("user-data");
   trmnlp.spinner = document.querySelector(".spinner");
   trmnlp.isLiveReloadEnabled =
@@ -278,6 +284,12 @@ document.addEventListener("DOMContentLoaded", async function () {
     trmnlp.fetchPreview();
   });
 
+  trmnlp.themeSelect.value = localStorage.getItem("trmnlp-theme") || "";
+  trmnlp.themeSelect.addEventListener("change", () => {
+    localStorage.setItem("trmnlp-theme", trmnlp.themeSelect.value);
+    trmnlp.fetchPreview();
+  });
+
   trmnlp.iframe.addEventListener("load", () => {
     trmnlp.spinner.style.display = "none";
   });

data/web/views/index.erb

@@ -46,6 +46,13 @@
                     <span data-dark-mode-text>Light Mode</span>
                 </button>
 
+                <select data-theme-select>
+                    <option value="">Default theme</option>
+                    <% TRMNLP::FrameworkVersion::THEMES.each do |id, name| %>
+                    <option value="<%= id %>"><%= name %></option>
+                    <% end %>
+                </select>
+
                 <!-- Optional: Reset button -->
                 <button class="btn" type="button" data-reset-button>Reset</button>
             </form>