glance-widgets-sdk 1.0.0

data/lib/glance_widgets/geometry.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  GAP_MODE_RATIOS = { 'zero' => 0, 'near' => 0.08, 'default' => 0.16, 'far' => 0.28, 'extraFar' => 0.42 }.freeze
+  FRAME_DECIMALS = 6
+
+  def require_canvas(canvas, operation = 'operation')
+    unless canvas.is_a?(Hash) && canvas['width'].is_a?(Numeric) && canvas['height'].is_a?(Numeric) &&
+           canvas['width'] > 0 && canvas['height'] > 0
+      raise ArgumentError, "#{operation} needs a positive canvas size in points"
+    end
+    canvas
+  end
+
+  def resolve_frame(frame, canvas)
+    require_canvas(canvas, 'resolve_frame')
+    axis = lambda do |start, finish, size, extent, fallback|
+      a = start && start * extent
+      b = finish && finish * extent
+      length = if a && b
+                 [0, extent - a - b].max
+               else
+                 Numbers.clamp(size || fallback, 0.02, 1.5) * extent
+               end
+      [a || (b ? extent - b - length : 0), length]
+    end
+    x, width = axis.call(frame['left'], frame['right'], frame['width'], canvas['width'], 0.4)
+    y, height = axis.call(frame['top'], frame['bottom'], frame['height'], canvas['height'], 0.16)
+    { 'x' => x, 'y' => y, 'width' => width, 'height' => height }
+  end
+
+  def fit_matrix(region, grid, layout)
+    columns, rows = grid.fetch('columns'), grid.fetch('rows')
+    aspect = Numbers.clamp(DataValues.fetch_or(layout, 'cellAspectRatio', 1), 0.1, 10)
+    scale = [aspect, 1].min
+    gap = GAP_MODE_RATIOS.fetch(DataValues.fetch_or(layout, 'gapMode', 'default'), 0.16)
+    gx = Numbers.clamp(DataValues.fetch_or(layout, 'columnGapRatio', gap), 0, 10) * scale
+    gy = Numbers.clamp(DataValues.fetch_or(layout, 'rowGapRatio', gap), 0, 10) * scale
+    inset = Numbers.clamp(DataValues.fetch_or(layout, 'edgeInsetRatio', 0), -0.45, 0.45) * scale
+    cell_height = [region['width'].fdiv(columns * aspect + (columns - 1) * gx + 2 * inset),
+                   region['height'].fdiv(rows + (rows - 1) * gy + 2 * inset)].min
+    cell_width = cell_height * aspect
+    gap_x, gap_y = gx * cell_height, gy * cell_height
+    { 'columns' => columns, 'rows' => rows, 'cellWidth' => cell_width, 'cellHeight' => cell_height,
+      'gapX' => gap_x, 'gapY' => gap_y,
+      'originX' => region['x'] + (region['width'] - columns * cell_width - (columns - 1) * gap_x) / 2.0,
+      'originY' => region['y'] + (region['height'] - rows * cell_height - (rows - 1) * gap_y) / 2.0 }
+  end
+
+  def cell_rect(geometry, x, y)
+    { 'x' => geometry['originX'] + x * (geometry['cellWidth'] + geometry['gapX']),
+      'y' => geometry['originY'] + y * (geometry['cellHeight'] + geometry['gapY']),
+      'width' => geometry['cellWidth'], 'height' => geometry['cellHeight'] }
+  end
+
+  def column_boundary(geometry, index)
+    geometry['originX'] + index * (geometry['cellWidth'] + geometry['gapX']) - geometry['gapX'] / 2.0
+  end
+
+  def row_boundary(geometry, index)
+    geometry['originY'] + index * (geometry['cellHeight'] + geometry['gapY']) - geometry['gapY'] / 2.0
+  end
+
+  def to_ratio_rect(rect, canvas)
+    require_canvas(canvas)
+    { 'x' => rect['x'].fdiv(canvas['width']), 'y' => rect['y'].fdiv(canvas['height']),
+      'width' => rect['width'].fdiv(canvas['width']), 'height' => rect['height'].fdiv(canvas['height']) }
+  end
+
+  def solve_grid(options)
+    region = options.fetch('region')
+    raise ArgumentError, 'solve_grid needs a positive region' unless region['width'] > 0 && region['height'] > 0
+    mode = DataValues.fetch_or(options, 'gapMode', 'default')
+    unless mode.is_a?(String) && GAP_MODE_RATIOS.key?(mode)
+      raise ArgumentError, "solve_grid: unknown gapMode #{mode.inspect}; expected one of #{GAP_MODE_RATIOS.keys.join(', ')}"
+    end
+    gap = DataValues.fetch_or(options, 'gap', GAP_MODE_RATIOS.fetch(mode))
+    inset = DataValues.fetch_or(options, 'edgeInsetRatio', 0)
+    unless Numbers.finite?(gap) && gap.between?(0, 10) && Numbers.finite?(inset) && inset.abs <= 0.45
+      raise ArgumentError, 'Invalid grid gap/inset'
+    end
+    count = ->(extent, cell) { [1, Numbers.round((extent.fdiv(cell) + gap - 2 * inset) / (1 + gap))].max }
+    square = ->(extent, n) { extent.fdiv(n + (n - 1) * gap + 2 * inset) }
+    rows, columns = options['rows'], options['columns']
+    if !rows && !columns
+      raise ArgumentError, 'Give rows, columns or positive cellSize' unless DataValues.fetch_or(options, 'cellSize', 0) > 0
+      rows = count.call(region['height'], options['cellSize'])
+    end
+    rows ||= count.call(region['height'], square.call(region['width'], columns))
+    columns ||= count.call(region['width'], square.call(region['height'], rows))
+    unless [rows, columns].all? { |n| Numbers.integer?(n) && n >= 1 } && rows * columns <= MAX_MATRIX_CELLS
+      raise ArgumentError, 'Invalid grid dimensions'
+    end
+    ratio = region['width'].fdiv(region['height'])
+    extra_x, extra_y = (columns - 1) * gap + 2 * inset, (rows - 1) * gap + 2 * inset
+    aspect = (ratio * (rows + extra_y) - extra_x).fdiv(columns)
+    if aspect < 1
+      denominator = columns + extra_x - ratio * extra_y
+      aspect = denominator > 0 ? ratio * rows / denominator : nil
+      aspect = nil if aspect && !(aspect > 0 && aspect <= 1)
+    end
+    aspect = Numbers.clamp(aspect || 0.1, 0.1, 10) if options['clampAspect'] == true
+    raise ArgumentError, 'Grid exceeds cell aspect limits' unless aspect && aspect.between?(0.1, 10)
+    layout = { 'gapMode' => mode, 'edgeInsetRatio' => inset, 'cellAspectRatio' => aspect }
+    layout.merge!('columnGapRatio' => gap, 'rowGapRatio' => gap) if DataValues.set?(options, 'gap')
+    { 'columns' => columns.to_i, 'rows' => rows.to_i, 'layout' => layout }
+  end
+end

data/lib/glance_widgets/layers.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  DEFAULT_ICON_NAME = 'ph_activity'
+  ICON_CATALOG = DataValues.load('icons.json').fetch('icons')
+  TEXT_DEFAULTS = {
+    'color' => '#FFFFFF', 'textOpacity' => 1, 'opacity' => 0, 'fontSizeRatio' => 0.12,
+    'fontWeight' => '400', 'fontFamily' => 'system', 'letterSpacing' => 0,
+    'horizontalAlignment' => 'left', 'verticalAlignment' => 'top', 'autoWrap' => false, 'paddingRatio' => 0
+  }.freeze
+  LINE_DEFAULTS = {
+    'color' => '#FFFFFF', 'opacity' => 1, 'strokeWidth' => 2, 'pattern' => 'solid', 'cap' => 'butt'
+  }.freeze
+  SHAPE_DEFAULTS = { 'color' => '#2A63D4', 'opacity' => 1, 'cornerRadiusRatio' => 0 }.freeze
+  ICON_DEFAULTS = { 'color' => '#FFFFFF', 'textOpacity' => 1 }.freeze
+  IMAGE_DEFAULTS = { 'opacity' => 1, 'cornerRadiusRatio' => 0 }.freeze
+  CURVE_DEFAULTS = {
+    'color' => '#6BA7FF', 'opacity' => 1, 'strokeWidth' => 2, 'lineCap' => 'round',
+    'lineJoin' => 'round', 'fillOpacity' => 0, 'plotPadding' => 0
+  }.freeze
+
+  def has_icon(name)
+    ICON_CATALOG.key?(name)
+  end
+
+  def icon_names
+    ICON_CATALOG.keys
+  end
+
+  def icon_glyph(name)
+    glyph = ICON_CATALOG.fetch(name) { raise ArgumentError, "Unknown icon: #{name}" }
+    DataValues.copy(glyph).merge('icon' => name)
+  end
+
+  def normalize_style_colors(style)
+    style.each_with_object({}) do |(key, value), result|
+      result[key] = if (key == 'color' || key.end_with?('Color')) && value.is_a?(String)
+                      normalize_color(value)
+                    elsif key == 'gradientColors' && value.is_a?(Array)
+                      value.map { |color| normalize_color(color) }
+                    else
+                      DataValues.copy(value)
+                    end
+    end
+  end
+
+  def layer_base(kind, options)
+    frame = options.fetch('frame')
+    node = { 'frame' => frame.is_a?(Box) ? frame.to_frame : DataValues.copy(frame) }
+    %w[zIndex rotation transform].each { |key| node[key] = DataValues.copy(options[key]) if DataValues.set?(options, key) }
+    path = options['dataPath'] || layer_path(options['id'])
+    { 'layers' => [{ 'id' => layer_id(options.fetch('id')), 'type' => kind, 'dataPath' => path }], 'data' => nest_at_path(path, node) }
+  end
+  private :layer_base
+
+  def finish_layer(base, fields)
+    path = base['layers'][0]['dataPath']
+    node = resolve_data_path(base['data'], path).merge(fields)
+    base['data'] = nest_at_path(path, node)
+    base
+  end
+  private :finish_layer
+
+  def text(options)
+    content = { 'text' => DataValues.fetch_or(options, 'text', '') }
+    finish_layer(layer_base('text', options), 'content' => content,
+                                     'style' => normalize_style_colors(TEXT_DEFAULTS.merge(DataValues.fetch_or(options, 'style', {}))))
+  end
+
+  def line(options)
+    finish_layer(layer_base('line', options),
+      'content' => { 'direction' => options.fetch('direction') },
+      'style' => normalize_style_colors(LINE_DEFAULTS.merge(DataValues.fetch_or(options, 'style', {})))
+    )
+  end
+
+  def horizontal_line(options)
+    axis_line(options, false)
+  end
+
+  def vertical_line(options)
+    axis_line(options, true)
+  end
+
+  def axis_line(options, vertical)
+    length = options.fetch('to') - options.fetch('from')
+    raise ArgumentError, 'Lines need at least .02 of the canvas' if length < 0.02
+    frame = if vertical
+              Box.new(options['at'], options['from'], 0, length)
+            else
+              Box.new(options['from'], options['at'], length, 0)
+            end
+    line(options.merge('frame' => frame, 'direction' => vertical ? 'vertical' : 'horizontal'))
+  end
+  private :axis_line
+
+  def shape(options)
+    frame = options.fetch('frame')
+    if frame.is_a?(Box) && frame.instance_variable_get(:@canvas)
+      rect = frame.to_pt
+      raise ArgumentError, 'Shape smaller than App minimum 24pt' if rect['width'] < 24 || rect['height'] < 24
+    end
+    style = SHAPE_DEFAULTS.merge(DataValues.fetch_or(options, 'style', {}))
+    style['backgroundColor'] = style['color'] unless DataValues.set?(style, 'backgroundColor')
+    finish_layer(layer_base('shape', options), 'content' => {}, 'style' => normalize_style_colors(style))
+  end
+
+  def icon(options)
+    unless %w[name glyph url].count { |key| DataValues.set?(options, key) } == 1
+      raise ArgumentError, 'Icon needs exactly one source'
+    end
+    glyph = options['glyph'] || (DataValues.set?(options, 'name') ? icon_glyph(options['name']) : nil)
+    content = if glyph
+                triple = glyph.select { |key, _| %w[icon iconCodePoint iconFont].include?(key) }
+                triple
+              elsif DataValues.set?(options, 'url')
+                { 'url' => options['url'] }
+              else
+                {}
+              end
+    finish_layer(layer_base('icon', options), 'content' => content,
+                                     'style' => normalize_style_colors(ICON_DEFAULTS.merge(DataValues.fetch_or(options, 'style', {}))))
+  end
+
+  def image(options)
+    raise ArgumentError, 'Image needs exactly one source' unless DataValues.set?(options, 'url')
+    content = DataValues.set?(options, 'url') ? { 'url' => options['url'] } : {}
+    style = normalize_style_colors(IMAGE_DEFAULTS.merge(DataValues.fetch_or(options, 'style', {})))
+    finish_layer(layer_base('image', options), 'content' => content, 'style' => style)
+  end
+
+  def curve(options)
+    data = DataValues.fetch_or(options, 'data', {})
+    function = data['mode'] == 'function' || (!DataValues.set?(data, 'mode') && DataValues.set?(data, 'expression'))
+    if function && (!DataValues.set?(data, 'domain') || !DataValues.set?(data, 'yDomain'))
+      raise ArgumentError, 'Function curve needs domain and yDomain'
+    end
+    if DataValues.fetch_or(data, 'points', []).length > 1024 || DataValues.fetch_or(data, 'markers', []).length > 32
+      raise ArgumentError, 'Curve exceeds point/marker limit'
+    end
+    DataValues.fetch_or(data, 'markers', []).each do |marker|
+      if marker.fetch('at', {}).fetch('offsetPt', [0, 0]).any? { |value| value.abs > 64 }
+        raise ArgumentError, 'Marker offset must stay within 64pt'
+      end
+    end
+    mode = DataValues.fetch_or(data, 'mode', DataValues.set?(data, 'expression') ? 'function' : 'samples')
+    content = DataValues.copy(data).merge('mode' => mode, 'interpolation' => DataValues.fetch_or(data, 'interpolation', 'monotone'))
+    style = CURVE_DEFAULTS.merge(DataValues.fetch_or(options, 'style', {}))
+    style['fillColor'] = style['color'] unless DataValues.set?(style, 'fillColor')
+    finish_layer(layer_base('curve', options), 'content' => content, 'style' => normalize_style_colors(style))
+  end
+end

data/lib/glance_widgets/matrix.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  EMPTY = 'empty'
+  DEFAULT_PIXEL_BASE = {
+    'color' => '#FFFFFF', 'opacity' => 1, 'cornerRadius' => 0, 'rotation' => 0, 'halo' => 0
+  }.freeze
+  BATCH_MIN_OCCURRENCES = 2
+
+  class Matrix
+    attr_reader :columns, :rows
+
+    def initialize(columns, rows, options = {})
+      Raster.integers('Matrix size', [columns, rows])
+      unless columns >= 1 && rows >= 1 && columns * rows <= MAX_MATRIX_CELLS
+        raise ArgumentError, 'Matrix must have positive dimensions and at most 4096 cells'
+      end
+      @columns, @rows = columns.to_i, rows.to_i
+      @layout = { 'gapMode' => 'default', 'edgeInsetRatio' => 0, 'cellAspectRatio' => 1 }
+      known_layout = %w[gapMode edgeInsetRatio cellAspectRatio columnGapRatio rowGapRatio]
+      @layout.merge!((options['layout'] || {}).select { |key, value| known_layout.include?(key) && !value.nil? })
+      raise ArgumentError, 'Unknown gapMode' unless @layout['gapMode'].is_a?(String) && GAP_MODE_RATIOS.key?(@layout['gapMode'])
+      @layout.each { |key, value| Numbers.require_finite(value, 'Layout field') unless key == 'gapMode' }
+      @default = resolve_pixel(DataValues.fetch_or(options, 'default', EMPTY) || EMPTY, DEFAULT_PIXEL_BASE)
+      visible = @default == EMPTY ? DEFAULT_PIXEL_BASE : @default
+      @base = resolve_pixel(visible.merge(options['base'] || {}), DEFAULT_PIXEL_BASE)
+      @cells = Array.new(@columns * @rows)
+    end
+
+    def layout
+      DataValues.copy(@layout)
+    end
+
+    def base
+      DataValues.copy(@base)
+    end
+
+    def default_style
+      DataValues.copy(@default)
+    end
+
+    def contains(x, y)
+      Numbers.integer?(x) && Numbers.integer?(y) && x >= 0 && y >= 0 && x < columns && y < rows
+    end
+
+    def get(x, y)
+      cell = @cells[index(x, y)]
+      DataValues.copy(cell.nil? ? @default : cell)
+    end
+
+    def is_set(x, y)
+      !@cells[index(x, y)].nil?
+    end
+
+    def set(x, y, style)
+      @cells[index(x, y)] = resolve(style)
+      self
+    end
+
+    def fill(style)
+      cell = resolve(style)
+      @cells = Array.new(columns * rows) { DataValues.copy(cell) }
+      self
+    end
+
+    def clear
+      fill(nil)
+    end
+
+    def blit(other, x, y)
+      other.rows.times do |row|
+        other.columns.times do |col|
+          cell = other.raw_cell(col, row)
+          plot(x + col, y + row, DataValues.copy(cell)) unless cell.nil? || cell == EMPTY
+        end
+      end
+      self
+    end
+
+    def line(x0, y0, x1, y1, style)
+      Raster.integers('line coordinates', [x0, y0, x1, y1])
+      cell = resolve(style)
+      Raster.line(x0, y0, x1, y1) { |x, y| plot(x, y, cell) }
+      self
+    end
+
+    def rect(x, y, width, height, style, options = {})
+      Raster.integers('rect arguments', [x, y, width, height])
+      cell = resolve(style)
+      ([0, y].max.to_i...[rows, y + height].min.to_i).each do |row|
+        ([0, x].max.to_i...[columns, x + width].min.to_i).each do |col|
+          edge = row == y || row == y + height - 1 || col == x || col == x + width - 1
+          plot(col, row, cell) if DataValues.fetch_or(options, 'fill', true) || edge
+        end
+      end
+      self
+    end
+
+    def round_rect(x, y, width, height, radius, style, options = {})
+      cell = resolve(style)
+      Raster.round_rect(x, y, width, height, radius, DataValues.fetch_or(options, 'fill', true), self) do |col, row|
+        plot(col, row, cell)
+      end
+      self
+    end
+
+    def ellipse(x, y, width, height, style, options = {})
+      cell = resolve(style)
+      Raster.ellipse(x, y, width, height, DataValues.fetch_or(options, 'fill', true), self) { |col, row| plot(col, row, cell) }
+      self
+    end
+
+    def circle(cx, cy, radius, style, options = {})
+      Raster.integers('circle arguments', [cx, cy, radius])
+      raise ArgumentError, 'Circle radius must be non-negative' if radius < 0
+      ellipse(cx - radius, cy - radius, 2 * radius + 1, 2 * radius + 1, style, options)
+    end
+
+    def arc(cx, cy, radius, start_angle, end_angle, style, options = {})
+      cell = resolve(style)
+      Raster.arc(cx, cy, radius, start_angle, end_angle, DataValues.fetch_or(options, 'thickness', 1), self) do |x, y|
+        plot(x, y, cell)
+      end
+      self
+    end
+
+    def polygon(points, style, options = {})
+      cell = resolve(style)
+      Raster.polygon(points, DataValues.fetch_or(options, 'fill', true), self) { |x, y| plot(x, y, cell) }
+      self
+    end
+
+    def flood_fill(x, y, style, options = {})
+      Raster.integers('flood_fill seed', [x, y])
+      return self unless contains(x, y)
+      target, cell = get(x, y), resolve(style)
+      offsets = [[1, 0], [-1, 0], [0, 1], [0, -1]]
+      offsets += [[1, 1], [1, -1], [-1, 1], [-1, -1]] if options['diagonal'] == true
+      pending, visited = [[x, y]], { [x, y] => true }
+      until pending.empty?
+        col, row = pending.pop
+        plot(col, row, cell)
+        offsets.each do |dx, dy|
+          point = [col + dx, row + dy]
+          next unless contains(*point) && !visited[point] && get(*point) == target
+          visited[point] = true
+          pending << point
+        end
+      end
+      self
+    end
+
+    def text(content, x, y, options = {})
+      Raster.integers('text position', [x, y])
+      cell = resolve(options.key?('style') ? options['style'] : @base)
+      GlanceWidgets.layout_text(content, options)['glyphs'].each do |placed|
+        placed['glyph']['rows'].each_with_index do |row, j|
+          row.each_char.with_index { |ch, i| plot(x + placed['x'] + i, y + placed['y'] + j, cell) if ch == '#' }
+        end
+      end
+      self
+    end
+
+    def clone
+      result = empty_like(columns, rows)
+      @cells.each_with_index { |cell, i| result.store(i % columns, i / columns, DataValues.copy(cell)) }
+      result
+    end
+
+    def flip_x
+      transformed(columns, rows) { |x, y| [columns - 1 - x, y] }
+    end
+
+    def flip_y
+      transformed(columns, rows) { |x, y| [x, rows - 1 - y] }
+    end
+
+    def rotate90(turns = 1)
+      Raster.integers('rotate90 turns', [turns])
+      result = clone
+      (turns.to_i % 4).times do
+        previous = result
+        result = previous.transformed(previous.rows, previous.columns) { |x, y| [previous.rows - 1 - y, x] }
+      end
+      result
+    end
+
+    def crop(x, y, width, height)
+      Raster.integers('crop arguments', [x, y, width, height])
+      result = empty_like(width, height)
+      height.to_i.times do |row|
+        width.to_i.times do |col|
+          result.store(col, row, DataValues.copy(raw_cell(x + col, y + row))) if contains(x + col, y + row)
+        end
+      end
+      result
+    end
+
+    def to_root
+      groups = {}
+      @cells.each_with_index do |cell, i|
+        next if cell.nil? || cell == @default
+        pixel = protocol_pixel(cell)
+        group = groups[DataValues.canonical_numbers(pixel)] ||= { 'pixel' => pixel, 'coordinates' => [] }
+        group['coordinates'] << [i / columns, i % columns]
+      end
+      pixels, batch = Array.new(rows) { Array.new(columns) }, []
+      groups.each_value do |group|
+        if group['coordinates'].length >= BATCH_MIN_OCCURRENCES
+          batch << group
+        else
+          group['coordinates'].each { |row, col| pixels[row][col] = group['pixel'] }
+        end
+      end
+      result = { 'pixels' => pixels, 'default' => protocol_pixel(@default), 'layout' => layout }
+      result['batch'] = batch unless batch.empty?
+      result
+    end
+
+    def to_part
+      { 'content' => to_root }
+    end
+
+    protected
+
+    def raw_cell(x, y)
+      @cells[index(x, y)]
+    end
+
+    def store(x, y, cell)
+      @cells[index(x, y)] = cell
+    end
+
+    def transformed(width, height)
+      result = empty_like(width, height)
+      rows.times do |y|
+        columns.times { |x| result.store(*yield(x, y), DataValues.copy(raw_cell(x, y))) }
+      end
+      result
+    end
+
+    private
+
+    def index(x, y)
+      raise ArgumentError, 'Cell outside matrix' unless contains(x, y)
+      y.to_i * columns + x.to_i
+    end
+
+    def plot(x, y, cell)
+      @cells[y.to_i * columns + x.to_i] = cell if contains(x, y)
+    end
+
+    def resolve(style)
+      style.nil? ? nil : resolve_pixel(style, @base)
+    end
+
+    def resolve_pixel(value, base)
+      return EMPTY if value == EMPTY
+      value = { 'color' => value } if value.is_a?(String)
+      raise ArgumentError, 'Pixel must be a color or style object' unless value.is_a?(Hash)
+      merged = base.merge(value)
+      %w[opacity cornerRadius rotation halo].each { |key| Numbers.require_finite(merged[key], "Pixel #{key}") }
+      { 'color' => GlanceWidgets.normalize_color(merged['color']),
+        'opacity' => Numbers.clamp(merged['opacity'], 0, 1),
+        'cornerRadius' => Numbers.clamp(merged['cornerRadius'], 0, 0.5),
+        'rotation' => merged['rotation'], 'halo' => Numbers.clamp(merged['halo'], 0, 1) }
+    end
+
+    def protocol_pixel(cell)
+      cell == EMPTY ? { 'empty' => true } : DataValues.copy(cell)
+    end
+
+    def empty_like(width, height)
+      Matrix.new(width, height, 'default' => @default, 'base' => @base, 'layout' => @layout)
+    end
+  end
+end

data/lib/glance_widgets/options.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  # Public entry points accept symbol-keyed option hashes (`merge(part, onConflict: 'error')`,
+  # `Matrix.new(3, 3, layout: {...})`); they are normalized to the string keys the SDK uses internally.
+  module OptionKeys
+    def self.wrapper(names)
+      Module.new do
+        names.each do |name|
+          define_method(name) do |*args, &block|
+            super(*args.map { |arg| DataValues.stringify_keys(arg) }, &block)
+          end
+        end
+      end
+    end
+  end
+
+  FUNCTIONS_WITH_OPTIONS = %i[
+    merge place to_response layout_text measure_text text_matrix define_font text line horizontal_line
+    vertical_line shape icon image curve resolve_frame fit_matrix solve_grid to_ratio_rect require_canvas
+    pixelate theme_options verify_signature line_chart area_chart sparkline pixel_progress_bar pixel_ring_progress pixel_bar_chart
+    labeled_pixel_progress_bar progress_bar ring_progress labeled_pixel_ring_progress battery signal stat heatmap
+    calendar_heatmap labeled_calendar_heatmap status_strip labeled_status_strip bar_chart
+    pixel_text_panel pixel_text_root
+  ].freeze
+
+  prepend OptionKeys.wrapper(FUNCTIONS_WITH_OPTIONS)
+  Matrix.prepend OptionKeys.wrapper(%i[initialize set fill text rect round_rect ellipse circle arc polygon flood_fill])
+  Box.prepend OptionKeys.wrapper(%i[initialize inset inset_pt rows columns split])
+  Box.singleton_class.prepend OptionKeys.wrapper(%i[canvas from_frame from_pt])
+end

data/lib/glance_widgets/output.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module GlanceWidgets
+  def layer_id(value)
+    raise ArgumentError, 'Layer id must be a non-empty string' unless value.is_a?(String) && !value.empty?
+    value.start_with?(LAYER_ID_PREFIX) ? value : LAYER_ID_PREFIX + value
+  end
+
+  def merge(*parts)
+    options = parts.last.is_a?(Hash) && parts.last.keys.map(&:to_s) == ['onConflict'] ? DataValues.stringify_keys(parts.pop) : {}
+    strict = options['onConflict'] == 'error'
+    result = { 'protocol' => 1 }
+    root_keys = %w[pixels default layout batch]
+    parts.each do |part|
+      unless part.is_a?(Hash) && !part.key?('content') && !part.key?('style')
+        raise ArgumentError, 'merge requires objects; place a MatrixPart before merging'
+      end
+      if part.key?('protocol') && (!Numbers.finite?(part['protocol']) || part['protocol'] != 1)
+        raise ArgumentError, 'Unsupported protocol'
+      end
+      if root_keys.any? { |key| part.key?(key) }
+        raise ArgumentError, 'Root matrix fields need pixels' unless part.key?('pixels')
+        raise ArgumentError, 'merge conflict: root matrix' if strict && result.key?('pixels')
+        root_keys.each do |key|
+          result.delete(key)
+          result[key] = DataValues.copy(part[key]) if part.key?(key)
+        end
+      end
+      if part.key?('data')
+        raise ArgumentError, 'Data must be an object' unless part['data'].is_a?(Hash)
+        merge_data(result['data'] ||= {}, part['data'], 'data', strict)
+      end
+      next unless part.key?('layers')
+      raise ArgumentError, 'Layers must be an array' unless part['layers'].is_a?(Array)
+      layers = result['layers'] ||= []
+      part['layers'].each do |layer|
+        raise ArgumentError, 'Layer must be an object' unless layer.is_a?(Hash)
+        index = layers.index { |existing| existing['id'] == layer['id'] }
+        raise ArgumentError, 'merge conflict: duplicate layer id' if index && strict
+        index ? layers[index] = DataValues.copy(layer) : layers << DataValues.copy(layer)
+      end
+    end
+    result
+  end
+
+  def merge_data(target, source, path, strict)
+    source.each do |key, value|
+      child = "#{path}.#{key}"
+      if target[key].is_a?(Hash) && value.is_a?(Hash)
+        merge_data(target[key], value, child, strict)
+      elsif strict && target.key?(key)
+        raise ArgumentError, "merge conflict at #{child}"
+      else
+        target[key] = DataValues.copy(value)
+      end
+    end
+  end
+  private :merge_data
+
+  def nest_at_path(path, value)
+    unless path.is_a?(String) && /\Adata(?:\.[A-Za-z_][A-Za-z0-9_]*)+\z/.match(path)
+      raise ArgumentError, 'Expected a path of the form data.name(.name)*'
+    end
+    path.split('.')[1..-1].reverse_each { |key| value = { key => value } }
+    value
+  end
+
+  def layer_path(id)
+    name = layer_id(id)[7..-1]
+    'data.layer_' + name.codepoints.map { |c| (c >= 48 && c <= 57) || (c >= 65 && c <= 90) || (c >= 97 && c <= 122) ? c.chr : "_#{c.to_s(16)}_" }.join
+  end
+
+  def place(part, options)
+    frame = options.fetch('frame')
+    node = { 'frame' => frame.is_a?(Box) ? frame.to_frame : DataValues.copy(frame), 'content' => DataValues.copy(part.fetch('content')), 'style' => {} }
+    %w[zIndex rotation transform].each { |key| node[key] = DataValues.copy(options[key]) if DataValues.set?(options, key) }
+    { 'layers' => [{ 'id' => layer_id(options.fetch('id')), 'type' => 'matrix', 'dataPath' => options.fetch('path') }], 'data' => nest_at_path(options.fetch('path'), node) }
+  end
+
+  def empty_root
+    { 'pixels' => [[{ 'empty' => true }]], 'default' => { 'empty' => true },
+      'layout' => { 'gapMode' => 'default', 'edgeInsetRatio' => 0, 'cellAspectRatio' => 1 } }
+  end
+
+  def to_response(part)
+    result = merge(part)
+    result = merge(empty_root, result) unless result.key?('pixels')
+    validate(result)
+    result
+  end
+end