glance-widgets-sdk 1.0.0

data/lib/glance_widgets/pixelate.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  DEFAULT_ALPHA_THRESHOLD = 128
+
+  def pixelate(image, options)
+    width, height, data = image.fetch('width'), image.fetch('height'), image.fetch('data')
+    Raster.integers('Image size', [width, height])
+    width, height = width.to_i, height.to_i
+    unless width >= 1 && height >= 1 && data.length == width * height * 4
+      raise ArgumentError, 'Invalid RGBA dimensions/data length'
+    end
+    raise ArgumentError, 'Unsupported dither' unless DataValues.fetch_or(options, 'dither', 'none') == 'none'
+    palette = DataValues.fetch_or(options, 'palette', []).map { |color| [normalize_color(color), parse_color(color)] }
+    raise ArgumentError, 'Palette must not be empty' if DataValues.set?(options, 'palette') && palette.empty?
+    matrix = Matrix.new(options.fetch('columns'), options.fetch('rows'), DataValues.fetch_or(options, 'matrix', {}))
+    divide_round = ->(n, d) { (2 * n + d).div(2 * d) }
+    matrix.rows.times do |row|
+      top = row * height / matrix.rows
+      bottom = [top + 1, (row + 1) * height / matrix.rows].max
+      matrix.columns.times do |col|
+        left = col * width / matrix.columns
+        right = [left + 1, (col + 1) * width / matrix.columns].max
+        sums, alpha = [0, 0, 0], 0
+        (top...bottom).each do |y|
+          (left...right).each do |x|
+            index = (y * width + x) * 4
+            a = data[index + 3]
+            alpha += a
+            3.times { |k| sums[k] += data[index + k] * a }
+          end
+        end
+        next if divide_round.call(alpha, (bottom - top) * (right - left)) < DataValues.fetch_or(options, 'alphaThreshold', 128)
+        channels = alpha.zero? ? [0, 0, 0] : sums.map { |n| divide_round.call(n, alpha) }
+        average = %w[r g b].zip(channels).to_h.merge('a' => 255)
+        color = if palette.empty?
+                  format_color(average)
+                else
+                  palette.min_by { |_, rgb| %w[r g b].sum { |key| (rgb[key] - average[key])**2 } }[0]
+                end
+        matrix.set(col, row, color)
+      end
+    end
+    matrix
+  end
+end

data/lib/glance_widgets/protocol.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  PROTOCOL_VERSION = 1
+  MAX_RESPONSE_BYTES = 524_288
+  MAX_MATRIX_CELLS = 4096
+  LAYER_ID_PREFIX = 'remote:'
+  MAX_SAFE_NATIVE_INTEGER = 9.2e18
+  CELL_ASPECT_RATIO_MIN = 0.1
+  CELL_ASPECT_RATIO_MAX = 10
+  EDGE_INSET_RATIO_LIMIT = 0.45
+  GAP_RATIO_MAX = 10
+  FRAME_SIZE_MIN = 0.02
+  FRAME_SIZE_MAX = 1.5
+  SHAPE_MIN_SIZE_PT = 24
+  DATA_PATH_PATTERN = /\Adata(?:\.[A-Za-z_][A-Za-z0-9_]*|\[[0-9]+\])*\z/
+
+  class GlanceValidationError < ArgumentError
+    attr_reader :path
+
+    def initialize(path, message)
+      @path = path
+      super("#{path}: #{message}")
+    end
+  end
+
+  # Schema tables are protocol data. Validation itself uses Ruby's JSON types.
+  module Protocol
+    SCHEMAS = DataValues.load('schemas.json')
+    module_function
+
+    def fail_at(path, message)
+      raise GlanceValidationError.new(path, message)
+    end
+
+    def json(value, path)
+      case value
+      when NilClass, String, TrueClass, FalseClass then nil
+      when Numeric
+        unless Numbers.finite?(value) && value.abs < MAX_SAFE_NATIVE_INTEGER
+          fail_at(path, 'number is unsafe for the native renderer')
+        end
+      when Array
+        value.each_with_index { |item, index| json(item, "#{path}[#{index}]") }
+      when Hash
+        value.each do |key, item|
+          fail_at(path, 'JSON object keys must be strings') unless key.is_a?(String)
+          json(item, "#{path}.#{key}")
+        end
+      else fail_at(path, 'value is not JSON')
+      end
+    end
+
+    def rule(value, schema, path)
+      if schema.is_a?(String)
+        valid = case schema
+                when 'number' then Numbers.finite?(value)
+                when 'textValue' then value.is_a?(String) || Numbers.finite?(value)
+                when 'integer' then Numbers.integer?(value)
+                when 'boolean' then value == true || value == false
+                when 'string' then value.is_a?(String)
+                when 'color' then GlanceWidgets.is_app_color(value)
+                end
+        fail_at(path, "expected #{schema}") unless valid
+      elsif schema.key?('enum')
+        fail_at(path, 'invalid enum value') unless schema['enum'].include?(value)
+      elsif schema.key?('arrayOf')
+        unless value.is_a?(Array) && (!schema.key?('length') || value.length == schema['length'])
+          fail_at(path, 'invalid array')
+        end
+        value.each_with_index { |item, index| rule(item, schema['arrayOf'], "#{path}[#{index}]") }
+      elsif schema.key?('object')
+        object(value, schema['object'], path)
+      else
+        fail_at(path, 'expected object') unless value.is_a?(Hash)
+        value.each { |key, item| rule(item, schema['record'], "#{path}.#{key}") }
+      end
+    end
+
+    def object(value, schema, path, strict = false)
+      fail_at(path, 'expected object') unless value.is_a?(Hash)
+      value.each_key { |key| fail_at("#{path}.#{key}", 'unsupported field') unless schema.key?(key) } if strict
+      schema.each { |key, item| rule(value[key], item, "#{path}.#{key}") if value.key?(key) && !value[key].nil? }
+    end
+
+    def matrix(value, path)
+      pixels = value['pixels']
+      unless pixels.is_a?(Array) && !pixels.empty? && pixels[0].is_a?(Array) && !pixels[0].empty?
+        fail_at(path + '.pixels', 'must be a non-empty 2D array')
+      end
+      rows, columns = pixels.length, pixels[0].length
+      fail_at(path + '.pixels', 'matrix exceeds 4096 cells') if rows * columns > MAX_MATRIX_CELLS
+      pixels.each_with_index do |row, y|
+        row_path = "#{path}.pixels[#{y}]"
+        fail_at(row_path, 'inconsistent row width') unless row.is_a?(Array) && row.length == columns
+        row.each_with_index { |pixel, x| object(pixel, SCHEMAS['pixel'], "#{row_path}[#{x}]") unless pixel.nil? }
+      end
+      object(value['default'], SCHEMAS['pixel'], path + '.default') if value.key?('default')
+      object(value['layout'], SCHEMAS['layout'], path + '.layout') if value.key?('layout')
+      return unless value.key?('batch')
+      fail_at(path + '.batch', 'expected array') unless value['batch'].is_a?(Array)
+      value['batch'].each_with_index do |entry, index|
+        batch_path = "#{path}.batch[#{index}]"
+        object(entry, { 'pixel' => { 'object' => SCHEMAS['pixel'] } }, batch_path)
+        coordinates = entry['coordinates']
+        fail_at(batch_path + '.coordinates', 'expected array') unless coordinates.is_a?(Array)
+        coordinates.each_with_index do |pair, position|
+          pair_path = "#{batch_path}.coordinates[#{position}]"
+          rule(pair, { 'arrayOf' => 'integer', 'length' => 2 }, pair_path)
+          unless pair[0] >= 0 && pair[0] < rows && pair[1] >= 0 && pair[1] < columns
+            fail_at(pair_path, 'coordinates outside matrix')
+          end
+        end
+      end
+    end
+
+    def layer(layer, data, path)
+      object(layer, { 'id' => 'string', 'type' => 'string', 'dataPath' => 'string' }, path, true)
+      unless layer['id'].is_a?(String) && layer['id'].start_with?(LAYER_ID_PREFIX) && layer['id'].length > 7
+        fail_at(path + '.id', 'must start with remote:')
+      end
+      schema = SCHEMAS['layers'][layer['type']]
+      fail_at(path + '.type', 'unknown layer type') unless schema
+      binding = layer['dataPath']
+      unless binding.is_a?(String) && DATA_PATH_PATTERN.match(binding)
+        fail_at(path + '.dataPath', 'invalid dataPath')
+      end
+      node(GlanceWidgets.resolve_data_path(data, binding), schema, layer['type'], binding, true)
+    end
+
+    def node(node, schema, kind, path, requires_frame)
+      object(node, {}, path)
+      node.each_key do |key|
+        fail_at(path + '.' + key, 'unsupported field') unless %w[frame zIndex rotation transform content style].include?(key)
+      end
+      frame = node['frame']
+      if (frame || requires_frame) && !(frame.is_a?(Hash) && Numbers.finite?(frame['width']) && Numbers.finite?(frame['height']))
+        fail_at(path + '.frame', 'remote frame needs width and height')
+      end
+      object(frame, SCHEMAS['frame'], path + '.frame', true) unless frame.nil?
+      %w[zIndex rotation].each { |key| rule(node[key], key == 'zIndex' ? 'integer' : 'number', path + '.' + key) unless node[key].nil? }
+      object(node['transform'], SCHEMAS['transform'], path + '.transform', true) unless node['transform'].nil?
+      content = node['content'].nil? ? {} : node['content']
+      if kind == 'matrix'
+        object(content, {}, path + '.content')
+        content.each_key { |key| fail_at(path + '.content.' + key, 'unsupported field') unless %w[pixels default batch layout].include?(key) }
+        content = content.reject { |_, value| value.nil? }
+        if !content['pixels'].nil? || requires_frame
+          matrix(content, path + '.content')
+        elsif !content['batch'].nil?
+          fail_at(path + '.content.batch', 'batch requires pixels')
+        elsif !content['default'].nil?
+          matrix({ 'pixels' => [[nil]], 'default' => content['default'] }, path + '.content')
+        end
+        object(content['layout'], SCHEMAS['layout'], path + '.content.layout', true) unless content['layout'].nil?
+      else
+        object(content, schema['content'], path + '.content', true)
+      end
+      object(node['style'], schema['style'], path + '.style', true) unless node['style'].nil?
+      fail_at(path + '.style.gradientColors', 'must contain at least one color') if node['style'].is_a?(Hash) && node['style']['gradientColors'] == []
+      if %w[image icon].include?(kind)
+        glyph = !content['icon'].nil?
+        if (glyph && !content['url'].nil?) || (!glyph && %w[iconCodePoint iconFont].any? { |key| !content[key].nil? })
+          fail_at(path + '.content.icon', 'choose one artwork source')
+        end
+      end
+    end
+
+  end
+
+  def validate_layer_node(node, type, path = '$', requires_frame = false)
+    Protocol.json(node, path)
+    schema = Protocol::SCHEMAS['layers'][type]
+    Protocol.fail_at(path, 'unknown layer type') unless schema
+    Protocol.node(node, schema, type, path, requires_frame)
+    nil
+  end
+
+  def resolve_data_path(data, path)
+    return nil unless path.is_a?(String) && DATA_PATH_PATTERN.match(path)
+    path[4..-1].scan(/\.([A-Za-z_][A-Za-z0-9_]*)|\[([0-9]+)\]/).each do |key, index|
+      data = if key
+               data.is_a?(Hash) ? data[key] : nil
+             else
+               data.is_a?(Array) ? data[index.to_i] : nil
+             end
+      return nil if data.nil?
+    end
+    data
+  end
+
+  def validate(response)
+    Protocol.fail_at('$', 'response must be a JSON object') unless response.is_a?(Hash)
+    Protocol.json(response, '$')
+    if JSON.generate(response).bytesize > MAX_RESPONSE_BYTES
+      Protocol.fail_at('$', 'response exceeds 512 KB')
+    end
+    if response.key?('protocol') && (!Numbers.finite?(response['protocol']) || response['protocol'] != 1)
+      Protocol.fail_at('$.protocol', 'must be the number 1')
+    end
+    Protocol.matrix(response, '$')
+    data = response['data'].nil? ? {} : response['data']
+    Protocol.fail_at('$.data', 'expected object') unless data.is_a?(Hash)
+    return nil unless response.key?('layers')
+    layers = response['layers']
+    unless layers.is_a?(Array)
+      Protocol.fail_at('$.layers', 'expected array')
+    end
+    ids = {}
+    layers.each_with_index do |item, index|
+      Protocol.layer(item, data, "$.layers[#{index}]")
+      Protocol.fail_at("$.layers[#{index}].id", 'duplicate layer id') if ids[item['id']]
+      ids[item['id']] = true
+    end
+    nil
+  end
+end

data/lib/glance_widgets/raster.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  RASTER_MAX_EXTENT = 4096
+  RASTER_MAX_COORDINATE = 1 << 24
+  ARC_DIRECTION_SCALE = 1 << 20
+
+  module Raster
+    module_function
+
+    def integers(label, values)
+      raise ArgumentError, "#{label} must be integers" unless values.all? { |v| Numbers.integer?(v) }
+    end
+
+    def range(label, values, low, high)
+      integers(label, values)
+      raise ArgumentError, "#{label} outside permitted range" unless values.all? { |v| v.between?(low, high) }
+    end
+
+    def line(x0, y0, x1, y1)
+      dx, dy = (x1 - x0).abs, -(y1 - y0).abs
+      sx, sy = x0 < x1 ? 1 : -1, y0 < y1 ? 1 : -1
+      error, x, y = dx + dy, x0, y0
+      loop do
+        yield x, y
+        break if x == x1 && y == y1
+        twice = 2 * error
+        if twice >= dy
+          error += dy
+          x += sx
+        end
+        if twice <= dx
+          error += dx
+          y += sy
+        end
+      end
+    end
+
+    def mask(x, y, width, height, contains, fill, bounds)
+      inside = ->(i, j) { i >= 0 && j >= 0 && i < width && j < height && contains.call(i, j) }
+      ([0, -y].max.to_i...[height, bounds.rows - y].min.to_i).each do |j|
+        ([0, -x].max.to_i...[width, bounds.columns - x].min.to_i).each do |i|
+          next unless inside.call(i, j)
+          edge = [[1, 0], [-1, 0], [0, 1], [0, -1]].any? { |dx, dy| !inside.call(i + dx, j + dy) }
+          yield x + i, y + j if fill || edge
+        end
+      end
+    end
+
+    def ellipse(x, y, width, height, fill, bounds, &emit)
+      integers('ellipse position', [x, y])
+      range('ellipse size', [width, height], 1, RASTER_MAX_EXTENT)
+      contains = lambda do |i, j|
+        (2 * i + 1 - width)**2 * height**2 + (2 * j + 1 - height)**2 * width**2 <= width**2 * height**2
+      end
+      mask(x, y, width, height, contains, fill, bounds, &emit)
+    end
+
+    def round_rect(x, y, width, height, radius, fill, bounds, &emit)
+      integers('round_rect position/radius', [x, y, radius])
+      range('round_rect size', [width, height], 1, RASTER_MAX_EXTENT)
+      raise ArgumentError, 'Radius must be non-negative' if radius < 0
+      radius = [radius, [width, height].min.div(2)].min
+      contains = lambda do |i, j|
+        qi, qj = [i, width - 1 - i].min, [j, height - 1 - j].min
+        qi >= radius || qj >= radius || (2 * qi + 1 - 2 * radius)**2 +
+          (2 * qj + 1 - 2 * radius)**2 <= 4 * radius**2
+      end
+      mask(x, y, width, height, contains, fill, bounds, &emit)
+    end
+
+    def arc(cx, cy, radius, start_angle, end_angle, thickness, bounds)
+      integers('arc center', [cx, cy])
+      range('arc radius', [radius], 0, RASTER_MAX_EXTENT)
+      range('arc thickness', [thickness], 1, RASTER_MAX_EXTENT)
+      [start_angle, end_angle].each { |v| Numbers.require_finite(v, 'Arc angle') }
+      sweep = end_angle - start_angle
+      return if sweep <= 0
+      direction = lambda do |angle|
+        radians = angle * Math::PI / 180
+        x = Numbers.round(Math.sin(radians) * ARC_DIRECTION_SCALE)
+        [x, -Numbers.round(Math.cos(radians) * ARC_DIRECTION_SCALE)]
+      end
+      sx, sy = direction.call(start_angle)
+      ex, ey = direction.call(end_angle)
+      hole = radius - thickness
+      inner = hole >= 0 ? hole**2 + hole : -1
+      ([0, cy - radius].max.to_i..[bounds.rows - 1, cy + radius].min.to_i).each do |y|
+        ([0, cx - radius].max.to_i..[bounds.columns - 1, cx + radius].min.to_i).each do |x|
+          dx, dy = x - cx, y - cy
+          after, before = sx * dy - sy * dx >= 0, dx * ey - dy * ex >= 0
+          segment = sweep >= 360 || (sweep < 180 ? after && before : after || before)
+          distance = dx**2 + dy**2
+          yield x, y if distance > inner && distance <= radius**2 + radius && segment
+        end
+      end
+    end
+
+    def polygon(points, fill, bounds)
+      raise ArgumentError, 'Polygon needs at least 3 points' unless points.is_a?(Array) && points.length >= 3
+      points.each do |point|
+        raise ArgumentError, 'Polygon points must be pairs' unless point.is_a?(Array) && point.length == 2
+        range('polygon coordinate', point, -RASTER_MAX_COORDINATE, RASTER_MAX_COORDINATE)
+      end
+      edges = points.each_index.map { |i| [points[i], points[(i + 1) % points.length]] }
+      edges.each do |a, b|
+        line(*a, *b) { |x, y| yield x, y if x >= 0 && y >= 0 && x < bounds.columns && y < bounds.rows }
+      end
+      return unless fill
+      xs, ys = points.map(&:first), points.map(&:last)
+      ([0, ys.min].max.to_i..[bounds.rows - 1, ys.max].min.to_i).each do |y|
+        cy = 2 * y + 1
+        spanning = edges.select { |a, b| (2 * a[1] <= cy) != (2 * b[1] <= cy) }
+        ([0, xs.min].max.to_i..[bounds.columns - 1, xs.max].min.to_i).each do |x|
+          right = through = 0
+          spanning.each do |a, b|
+            dy = b[1] - a[1]
+            cross = (2 * a[0] - 2 * x - 1) * dy + (cy - 2 * a[1]) * (b[0] - a[0])
+            if cross.zero?
+              through += 1
+            elsif cross.positive? == dy.positive?
+              right += 1
+            end
+          end
+          yield x, y if right.odd? || (right + through).odd?
+        end
+      end
+    end
+  end
+end

data/lib/glance_widgets/signature.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  TIMESTAMP_HEADER = 'X-GlanceWidgets-Timestamp'
+  SIGNATURE_HEADER = 'X-GlanceWidgets-Signature'
+  DEFAULT_SIGNATURE_TOLERANCE_MS = 300_000
+
+  def sign(timestamp, secret)
+    timestamp = Numbers.text(timestamp) if timestamp.is_a?(Numeric)
+    Base64.strict_encode64(OpenSSL::HMAC.digest('SHA256', secret, "#{timestamp}\n#{secret}"))
+  end
+
+  def verify_signature(request, secret, options = {})
+    timestamp, signature = request['timestamp'], request['signature']
+    return false unless timestamp.is_a?(String) && signature.is_a?(String) && /\A[0-9]+\z/.match(timestamp)
+    now = DataValues.fetch_or(options, 'now', Time.now.to_f * 1000)
+    return false if (now - timestamp.to_f).abs > DataValues.fetch_or(options, 'toleranceMs', DEFAULT_SIGNATURE_TOLERANCE_MS)
+    expected = sign(timestamp, secret)
+    return false unless signature.bytesize == expected.bytesize
+    if OpenSSL.respond_to?(:fixed_length_secure_compare)
+      OpenSSL.fixed_length_secure_compare(signature, expected)
+    else
+      # Ruby 2.6's bundled OpenSSL lacks secure_compare. Inspect every byte;
+      # the only early exit above depends on the public signature length.
+      difference = 0
+      expected.bytes.each_with_index { |byte, index| difference |= byte ^ signature.getbyte(index) }
+      difference.zero?
+    end
+  end
+end

data/lib/glance_widgets/support.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  # Numeric formatting follows ECMAScript because numbers also appear in labels
+  # and signed messages, where an equivalent JSON number is insufficient.
+  module Numbers
+    module_function
+
+    def finite?(value)
+      value.is_a?(Numeric) && value.real? && value.finite?
+    end
+
+    def integer?(value)
+      finite?(value) && value == value.to_i
+    end
+
+    def require_finite(value, label)
+      raise ArgumentError, "#{label} must be finite" unless finite?(value)
+      value
+    end
+
+    # JS Math.round/floor/ceil keep non-finite values; Ruby would raise FloatDomainError.
+    def round(value)
+      value.is_a?(Float) && !value.finite? ? value : (value + 0.5).floor
+    end
+
+    def floor(value)
+      value.is_a?(Float) && !value.finite? ? value : value.floor
+    end
+
+    def ceil(value)
+      value.is_a?(Float) && !value.finite? ? value : value.ceil
+    end
+
+    def clamp(value, low, high)
+      [[value, low].max, high].min
+    end
+
+    def text(number)
+      value = number.to_f
+      return '0' if value.zero?
+      return 'NaN' if value.nan?
+      return value.negative? ? '-Infinity' : 'Infinity' unless value.finite?
+      mantissa, exponent = value.to_s.downcase.split('e')
+      mantissa = mantissa.sub(/\.0\z/, '')
+      return mantissa unless exponent
+      exponent = exponent.to_i
+      if value.abs >= 1e21 || value.abs < 1e-6
+        return "#{mantissa}e#{exponent >= 0 ? '+' : '-'}#{exponent.abs}"
+      end
+      sign = mantissa.start_with?('-') ? '-' : ''
+      digits = mantissa.delete('-')
+      point = (digits.index('.') || digits.length) + exponent
+      digits = digits.delete('.')
+      expanded = if point <= 0
+                   '0.' + '0' * -point + digits
+                 elsif point >= digits.length
+                   digits + '0' * (point - digits.length)
+                 else
+                   digits[0...point] + '.' + digits[point..-1]
+                 end
+      sign + expanded
+    end
+
+    def fixed(number, decimals)
+      # JS toFixed: ToIntegerOrInfinity (NaN -> 0, truncation), then a 0..100 range check.
+      raise ArgumentError, 'decimals must be a number from 0 to 100' unless decimals.is_a?(Numeric) && decimals.real?
+      decimals = decimals.to_f
+      decimals = 0.0 if decimals.nan?
+      raise ArgumentError, 'decimals must be a number from 0 to 100' unless decimals.finite? && decimals.truncate.between?(0, 100)
+      decimals = decimals.truncate
+      value = number.to_f
+      return text(value) unless value.finite? && value.abs < 1e21
+      ratio = value.abs.to_r
+      quotient, remainder = (ratio.numerator * 10**decimals).divmod(ratio.denominator)
+      quotient += 1 if remainder * 2 >= ratio.denominator
+      digits = quotient.to_s.rjust(decimals + 1, '0')
+      result = decimals.zero? ? digits : digits[0...-decimals] + '.' + digits[-decimals..-1]
+      (value.negative? ? '-' : '') + result
+    end
+
+    def format_number(value, decimals)
+      result = fixed(value, decimals)
+      result.sub(/\A-0(?=\z|\.0*\z)/, '0')
+    end
+  end
+
+  module DataValues
+    module_function
+
+    def copy(value)
+      case value
+      when Hash then value.each_with_object({}) { |(key, item), result| result[key] = copy(item) }
+      when Array then value.map { |item| copy(item) }
+      when String then value.dup
+      else value
+      end
+    end
+
+    # Hash#fetch that treats nil like a missing key (JS `options.key ?? default`).
+    def fetch_or(hash, key, default)
+      value = hash[key]
+      value.nil? ? default : value
+    end
+
+    # True when the option is present and not nil (JS `options.key !== undefined` with null as unset).
+    def set?(hash, key)
+      !hash[key].nil?
+    end
+
+    # Deep copy with symbol keys turned into strings, so symbol-keyed options behave like JSON ones.
+    def stringify_keys(value)
+      case value
+      when Hash then value.each_with_object({}) { |(key, item), result| result[key.is_a?(Symbol) ? key.to_s : key] = stringify_keys(item) }
+      when Array then value.map { |item| stringify_keys(item) }
+      else value
+      end
+    end
+
+    # Numbers in canonical form (1.0 -> 1, -0.0 -> 0) so numerically equal values group together.
+    def canonical_numbers(value)
+      case value
+      when Hash then value.each_with_object({}) { |(key, item), result| result[key] = canonical_numbers(item) }
+      when Array then value.map { |item| canonical_numbers(item) }
+      when Float then value.finite? && value == value.floor ? value.to_i : value
+      else value
+      end
+    end
+
+    def load(name)
+      JSON.parse(File.read(File.join(__dir__, 'data', name)))
+    end
+  end
+end

data/lib/glance_widgets/themes.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  OFF_PIXEL_OPACITY = 0.3
+  ROOT_RING_OPACITY_THRESHOLD = 0.4
+
+  def build_theme(name, colors, corner, gap, rotation = 0, halo = 0)
+    palette = %w[on off dim accent].zip(colors).to_h
+    shape = { 'cornerRadius' => corner, 'rotation' => rotation }
+    { 'name' => name, 'palette' => palette,
+      'default' => shape.merge('color' => palette['off'], 'opacity' => 0.3, 'halo' => 0),
+      'base' => shape.merge('color' => palette['on'], 'opacity' => 1, 'halo' => halo),
+      'layout' => { 'gapMode' => gap, 'edgeInsetRatio' => 0, 'cellAspectRatio' => 1 } }
+  end
+  private :build_theme
+
+  THEMES = {
+    'led' => build_theme('led', %w[#FF4D2E #3A1F1B #A33A26 #FFD23F], 0.5, 'far', 0, 0.6),
+    'lcd' => build_theme('lcd', %w[#9BFF6B #27402B #5E9B4A #E6FF8A], 0, 'near'),
+    'dot' => build_theme('dot', %w[#F2F2F7 #48484A #8E8E93 #0A84FF], 0.5, 'extraFar'),
+    'diamond' => build_theme('diamond', %w[#5AC8FA #1C3A4A #3D7C99 #FF9F0A], 0.1, 'extraFar', 45),
+    'soft' => build_theme('soft', %w[#FFE2B8 #4A3F38 #B59A82 #FF7A59], 0.3, 'default', 0, 0.25)
+  }.freeze
+
+  def get_theme(name)
+    DataValues.copy(THEMES.fetch(name) { raise ArgumentError, "Unknown theme: #{name}" })
+  end
+
+  def theme_options(theme, overrides = {})
+    DataValues.copy('default' => overrides.fetch('default', theme['default']),
+                    'base' => theme['base'].merge(DataValues.fetch_or(overrides, 'base', {})),
+                    'layout' => theme['layout'].merge(DataValues.fetch_or(overrides, 'layout', {})))
+  end
+end

data/lib/glance_widgets.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+require 'base64'
+require 'date'
+
+# Builders return ordinary string-keyed Hashes suitable for JSON.generate.
+module GlanceWidgets
+  extend self
+end
+
+require_relative 'glance_widgets/support'
+require_relative 'glance_widgets/color'
+require_relative 'glance_widgets/protocol'
+require_relative 'glance_widgets/geometry'
+require_relative 'glance_widgets/box'
+require_relative 'glance_widgets/output'
+require_relative 'glance_widgets/raster'
+require_relative 'glance_widgets/matrix'
+require_relative 'glance_widgets/font'
+require_relative 'glance_widgets/themes'
+require_relative 'glance_widgets/pixelate'
+require_relative 'glance_widgets/layers'
+require_relative 'glance_widgets/signature'
+require_relative 'glance_widgets/components/shared'
+require_relative 'glance_widgets/components/pixel_progress'
+require_relative 'glance_widgets/components/modern'
+require_relative 'glance_widgets/components/progress'
+require_relative 'glance_widgets/components/ring_progress'
+require_relative 'glance_widgets/components/battery'
+require_relative 'glance_widgets/components/signal'
+require_relative 'glance_widgets/components/status'
+require_relative 'glance_widgets/components/heatmap'
+require_relative 'glance_widgets/components/charts'
+require_relative 'glance_widgets/components/stat'
+require_relative 'glance_widgets/components/pixel_text'
+require_relative 'glance_widgets/options'