zaniah 0.1.0

data/lib/zaniah/text_system/typesetter.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "font_db"
+require_relative "glyph"
+require_relative "line_layout"
+require_relative "shaper"
+
+module Zaniah
+  module TextSystem
+    # Layout-only state can belong to a background worker without GPU atlases or
+    # sharing the rendering thread's mutable caches. Providers are owner-local.
+    class Typesetter
+      attr_reader :font_db, :font, :shaper, :segmenter
+
+      def initialize(font: nil, font_db: Zaniah.configuration.font_db, capacity: 2000,
+        shaper: Zaniah.configuration.shaper, segmenter: Zaniah.configuration.segmenter)
+        require "alhena"
+        raise ArgumentError, "layout cache capacity must be positive" unless capacity.is_a?(Integer) && capacity.positive?
+        @font_db = provider(font_db, :font_db, %i[find fallback]) { FontDB.new }
+        @shaper = provider(shaper, :shaper, [:shape]) { Shaper.new }
+        @segmenter = provider(segmenter, :segmenter, [:grapheme_clusters]) { Unicode }
+        @font, @capacity = font || @font_db.find, capacity
+        @cache = {}
+        @layout_lookup, @layout_keys = [nil, nil, nil], {}
+      end
+
+      def layout_line(text, font: nil, size: 14)
+        raise ArgumentError, "text must be valid UTF-8" unless text.is_a?(String) && text.encoding == Encoding::UTF_8 && text.valid_encoding?
+        raise ArgumentError, "font size must be finite and positive" unless size.is_a?(Numeric) && size.finite? && size.positive?
+        font ||= @font
+        cached = cached_layout(text, font, size)
+        return cached if cached
+
+        text = text.dup.freeze
+        boundaries = grapheme_boundaries(text)
+        glyphs = shape_glyphs(glyphs_for(text, font, size), text, size)
+        scale = size.to_f / font.units_per_em
+        line = LineLayout.new(text, glyphs.freeze, glyphs.sum(&:advance), font.ascent * scale,
+          -font.descent * scale, size, carets_for(glyphs, boundaries).freeze)
+        cache_layout(line, text, font, size)
+      end
+
+      # Copy only layout state, never a Renderer's atlases/rasterizer. Custom
+      # providers explicitly deep-copy their state without mutating the source.
+      def fork(capacity: @capacity)
+        copies = []
+        options = {font: @font, font_db: @font_db, shaper: @shaper, segmenter: @segmenter}.to_h do |kind, value|
+          copy = layout_copy(kind, value)
+          copies << copy unless copy.equal?(value)
+          [kind, copy]
+        end
+        Typesetter.new(**options, capacity: capacity).tap { |copy| copy.instance_variable_set(:@owned_font, options[:font]) }
+      rescue StandardError
+        copies.reverse.uniq(&:object_id).each do |copy|
+          copy.close if copy.respond_to?(:close)
+        rescue StandardError
+          nil # Preserve the original copy/validation error.
+        end
+        raise
+      end
+
+      def close
+        return if @closed
+        @closed = true
+        @cache.clear
+        @layout_keys.clear
+        [@shaper, @segmenter, @font_db, @owned_font].uniq(&:object_id).each { |value| value.close if value.respond_to?(:close) }
+      end
+
+      private
+
+      def cached_layout(text, font, size)
+        @layout_lookup[0], @layout_lookup[1], @layout_lookup[2] = text, font, size
+        return unless (cached = @cache.delete(@layout_lookup))
+        @cache[@layout_keys.fetch(cached.object_id)] = cached
+      end
+
+      def grapheme_boundaries(text)
+        characters = @segmenter.grapheme_clusters(text)
+        raise Error, "segmenter must partition the UTF-8 text into nonempty strings" unless characters.is_a?(Array) && characters.all? { |part| part.is_a?(String) && !part.empty? && part.valid_encoding? } && characters.join == text
+        boundaries, byte = [0], 0
+        characters.each { |character| boundaries << (byte += character.bytesize) }
+        boundaries
+      end
+
+      def glyphs_for(text, font, size)
+        x, offset, glyphs = 0.0, 0, []
+        text.each_char do |character|
+          if (character.ord.between?(0xFE00, 0xFE0F) || character.ord.between?(0xE0100, 0xE01EF)) && !glyphs.empty?
+            previous = glyphs.pop
+            base = text.byteslice(previous.start, previous.finish - previous.start).each_char.first
+            id = previous.font.glyph_id(base, variation_selector: character.ord)
+            glyphs << Glyph.new(previous.font, id, previous.start, offset + character.bytesize, previous.x, previous.advance)
+            offset += character.bytesize
+            next
+          end
+          selected = @font_db.fallback(character.ord, font)
+          id = selected.glyph_id(character)
+          advance = selected.advance(id, size: size)
+          glyphs << Glyph.new(selected, id, offset, offset + character.bytesize, x, advance)
+          x += advance
+          offset += character.bytesize
+        end
+        glyphs
+      end
+
+      def shape_glyphs(glyphs, text, size)
+        glyphs = @shaper.shape(glyphs, size: size, text: text)
+        valid = glyphs.is_a?(Array) && glyphs.all? do |glyph|
+          glyph.is_a?(Glyph) && glyph.start.is_a?(Integer) && glyph.finish.is_a?(Integer) &&
+            glyph.start >= 0 && glyph.finish.between?(glyph.start + 1, text.bytesize) &&
+            glyph.x.is_a?(Numeric) && glyph.x.finite? && glyph.advance.is_a?(Numeric) && glyph.advance.finite?
+        end
+        raise Error, "shaper must return finite Glyph values with valid UTF-8 byte ranges" unless valid
+        glyphs
+      end
+
+      def carets_for(glyphs, boundaries)
+        carets, pen, boundary = [[0, 0.0]], 0.0, 1
+        glyphs.chunk { |glyph| [glyph.start, glyph.finish] }.each do |(first, last), cluster|
+          advance = cluster.sum(&:advance)
+          first_boundary = boundary
+          boundary += 1 while boundary < boundaries.length && boundaries[boundary] <= last
+          count = boundary - first_boundary
+          count.times do |index|
+            carets << [boundaries[first_boundary + index], pen + advance * (index + 1) / count]
+          end
+          pen += advance
+        end
+        carets
+      end
+
+      def cache_layout(line, text, font, size)
+        @layout_keys.delete(@cache.shift.last.object_id) if @cache.length >= @capacity
+        key = @layout_keys[line.object_id] = [text, font, size].freeze
+        @cache[key] = line
+      end
+
+      def layout_copy(kind, value)
+        native = value.singleton_methods.empty?
+        return Alhena::Font.new(value.data, index: value.index, axes: value.axis_values) if kind == :font && native && value.instance_of?(Alhena::Font)
+        return FontDB.new(paths: value.paths) if kind == :font_db && native && value.instance_of?(FontDB)
+        return Shaper.new if kind == :shaper && native && value.instance_of?(Shaper)
+        return Unicode if kind == :segmenter && value.equal?(Unicode)
+        raise CopyError, "#{kind} provider must implement #layout_copy for independent text layout" unless value.respond_to?(:layout_copy)
+        copy = value.layout_copy
+        methods = {font: %i[units_per_em ascent descent family glyph_id advance tables], font_db: %i[find fallback], shaper: [:shape], segmenter: [:grapheme_clusters]}.fetch(kind)
+        unless !copy.equal?(value) && methods.all? { |name| copy.respond_to?(name) }
+          copy.close if !copy.equal?(value) && copy.respond_to?(:close)
+          raise CopyError, "#{kind} #layout_copy must return an independent provider responding to #{methods.join(', ')}"
+        end
+        copy
+      rescue CopyError
+        raise
+      rescue StandardError => error
+        raise CopyError, "#{kind} layout copy failed: #{error.message}"
+      end
+
+      def provider(value, kind, methods)
+        return yield if value == :native
+        raise ArgumentError, "unsupported #{kind} provider #{value.inspect}; use :native or an object responding to #{methods.join(', ')}" unless methods.all? { |name| value.respond_to?(name) }
+        value
+      end
+    end
+  end
+end
+
+require_relative "typesetter/copy_error"

data/lib/zaniah/text_system.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "text_system/glyph"
+require_relative "text_system/line_layout"
+require_relative "text_system/font_db"
+require_relative "text_system/shaper"
+require_relative "text_system/atlas"
+require_relative "text_system/typesetter"
+require_relative "text_system/renderer"

data/lib/zaniah/unicode.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Zaniah
+  module Unicode
+    # Ruby's Unicode-aware regexp engine implements extended grapheme clusters.
+    def self.grapheme_clusters(text) = text.grapheme_clusters
+    def self.width(text, ambiguous: 1)
+      require "rbconfig"
+      require "unicode/display_width"
+      ::Unicode::DisplayWidth.of(text, ambiguous, emoji: :rgi)
+    end
+  end
+end

data/lib/zaniah/uniform_list.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Zaniah
+  class UniformList < Element
+    attr_accessor :scroll_y
+    attr_reader :visible_range
+
+    def initialize(count:, row_height:, &render_item)
+      super()
+      raise ArgumentError, "invalid list dimensions" unless count >= 0 && row_height.positive?
+      @count, @row_height, @render_item, @scroll_y = count, row_height, render_item, 0
+      style(overflow: :hidden)
+    end
+
+    def request_layout(cx)
+      viewport = @style[:height]
+      viewport = viewport.resolve(cx.window.content_size.height) if viewport.is_a?(Length)
+      viewport = cx.window.content_size.height unless viewport.is_a?(Numeric)
+      @scroll_y = @scroll_y.clamp(0, [@count * @row_height - viewport, 0].max)
+      first = (@scroll_y / @row_height).floor
+      last = [first + (viewport / @row_height).ceil + 1, @count].min
+      @visible_range = first...last
+      @children = @visible_range.map do |index|
+        @render_item.call(index).style(position: :absolute, left: 0, right: 0,
+          top: index * @row_height - @scroll_y, height: @row_height)
+      end
+      super
+    end
+  end
+end

data/lib/zaniah/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Zaniah
+  VERSION = "0.1.0"
+end

data/lib/zaniah/view.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Zaniah
+  class View
+    include LengthUnits
+
+    def div = Div.new
+    def text(value, **options) = Text.new(value, **options)
+    def list(**options, &render_item) = List.new(**options, &render_item)
+    def svg(source, **options) = SVG.new(source, **options)
+    def render(_cx) = raise NotImplementedError, "implement View#render"
+  end
+end

data/lib/zaniah.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "zaniah/version"
+require_relative "zaniah/data_compat"
+require_relative "zaniah/error"
+require_relative "zaniah/configuration"
+
+module Zaniah
+  def self.configuration
+    @configuration ||= Configuration.new(font_raster: :native, shaper: :native,
+                                        font_db: :native, segmenter: :native)
+  end
+  def self.configure = yield(configuration)
+end
+
+require_relative "zaniah/geometry"
+require_relative "zaniah/unicode"
+require_relative "zaniah/scene"
+require_relative "zaniah/png"
+require_relative "zaniah/gpu"
+require_relative "zaniah/layout"
+require_relative "zaniah/app"
+require_relative "zaniah/process_pool"
+require_relative "zaniah/input"
+require_relative "zaniah/element"
+Zaniah.autoload(:SVG, File.expand_path("zaniah/svg", __dir__))
+require_relative "zaniah/list"
+require_relative "zaniah/platform"
+require_relative "zaniah/text_system"

data/sig/app.rbs

@@ -0,0 +1,80 @@
+module Zaniah
+  class Subscription
+    def initialize: () { () -> void } -> void
+    def detach: () -> void
+    def attached?: () -> bool
+  end
+
+  class Entity[T] < Data
+    attr_reader id: Integer
+    attr_reader generation: Integer
+    def self.new: [U] (Integer id, Integer generation) -> Entity[U]
+                | [U] (id: Integer, generation: Integer) -> Entity[U]
+    def read: (App app) -> T
+    def update: [U] (App app) { (T, EntityContext[T]) -> U } -> U
+    def release: (App app) -> void
+  end
+  class EntityContext[T]
+    attr_reader app: App
+    attr_reader entity: Entity[T]
+    def initialize: (App app, Entity[T] entity) -> void
+    def notify: () -> void
+    def emit: [E] (E event) -> void
+    def observe: [U] (Entity[U] target) { (T, U, EntityContext[T]) -> void } -> Subscription
+    def subscribe: [U, E] (Entity[U] target) { (T, U, E, EntityContext[T]) -> void } -> Subscription
+    def spawn: [U] () { (EntityContext[T]) -> U } -> Task[U]
+    def background: [U] () { () -> U } -> U
+    def update: () { (App) -> void } -> void
+    def theme: () -> untyped
+  end
+  class App
+    attr_reader windows: Array[Platform::Headless::Window]
+    attr_reader executor: TaskExecutor
+    def initialize: () -> void
+    def new_entity: [T] () { (EntityContext[T]) -> T } -> Entity[T]
+    def read: [T] (Entity[T] entity) -> T
+    def update: [T, U] (Entity[T] entity) { (T, EntityContext[T]) -> U } -> U
+    def release: [T] (Entity[T] entity) -> void
+    def alive?: [T] (Entity[T] entity) -> bool
+    def entity_count: () -> Integer
+    # Global values are application-owned heterogeneous state.
+    def global: (Symbol | String key) -> untyped
+              | [T] (Symbol | String key, T value) -> T
+    def listen: [T] (:notify | :emit kind, Entity[T] target, ?owner: Entity[untyped]?) { (*untyped) -> void } -> Subscription
+    def enqueue: (:notify | :emit kind, Entity[untyped] entity, ?untyped event) -> void
+    def flush_effects: () -> void
+    def open_window: (?backend: Platform::backend, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?input: IO, ?output: IO, ?gpu: :metal | :opengl | :gl, ?display_server: :auto | :x11 | :wayland) ?{ (Platform::Headless::Window) -> (Element | Scene | nil) } -> Platform::Headless::Window
+    def run: () -> void
+  end
+
+  # Task is the framework's cancellable future, shared by both executor queues.
+  class Task[T]
+    class Cancelled < Error
+    end
+    class Timeout < Error
+    end
+    def initialize: () -> void
+    def resolve: (?T? value, ?error: Exception?) -> void
+    def await: (?timeout: Numeric?) -> T
+    def cancel: () -> void
+    def done?: () -> bool
+    def on_complete: () { () -> void } -> Subscription
+  end
+  class TaskExecutor
+    def self.current: () -> TaskExecutor?
+    def initialize: (?workers: Integer) -> void
+    def background: [T] () { () -> T } -> Task[T]
+    def spawn: [T] () { () -> T } -> Task[T]
+    def await: [T] (Task[T] task, ?timeout: Numeric?) -> T
+    def post: () { () -> void } -> void
+    def drain: () -> void
+    def wait: (Numeric seconds) -> void
+    def shutdown: () -> void
+  end
+  class ProcessPool[Input, Output]
+    def initialize: (?workers: Integer, handler: String, ?requires: Array[String], ?load_paths: Array[String], ?max_pending: Integer, ?max_bytes: Integer) -> void
+                  | (?workers: Integer, ?max_pending: Integer, ?max_bytes: Integer) { (Input) -> Output } -> void
+    def submit: (Input data) -> Task[Output]
+    def shutdown: (?timeout: Numeric) -> void
+  end
+end

data/sig/elements.rbs

@@ -0,0 +1,129 @@
+module Zaniah
+  class FrameContext
+    attr_reader window: Platform::Headless::Window
+    attr_reader scene: Scene
+    attr_reader dispatcher: Input::Dispatcher
+    attr_reader text_system: TextSystem::_System?
+    def initialize: (Platform::Headless::Window window) -> void
+    def state: [T] (Object key) { () -> T } -> T
+  end
+
+  class Element
+    include LengthUnits
+    attr_reader layout_node: Layout::Node?
+    # Child constructors forward their render blocks through super(); ignored here.
+    def initialize: () ?{ (*untyped) -> void } -> void
+    def child: (Element? element) -> self
+    def children: () -> Array[Element]
+                | (Array[Element?] elements) -> self
+    def style: (**Layout::style_value properties) -> self
+    def key: (Object value) -> self
+    def with_state: [T] () { () -> T } -> self
+    def bg: (color color) -> self
+    def border_color: (color color) -> self
+    def rounded: (radius radius) -> self
+    def tooltip: (String text) -> self
+    def context_menu: (menu items) -> self
+    def flex: () -> self
+    def flex_row: () -> self
+    def flex_col: () -> self
+    def items_center: () -> self
+    def justify_center: () -> self
+    def w_full: () -> self
+    def h_full: () -> self
+    def flex_1: () -> self
+    def overflow_hidden: () -> self
+    def w: (dimension value) -> self
+    def h: (dimension value) -> self
+    def min_w: (dimension value) -> self
+    def min_h: (dimension value) -> self
+    def max_w: (dimension value) -> self
+    def max_h: (dimension value) -> self
+    def p: (Layout::style_value value) -> self
+    def m: (Layout::style_value value) -> self
+    def gap: (dimension value) -> self
+    def border: (Layout::style_value value) -> self
+    def border_b: (dimension value) -> self
+    def on_click: () { (Input::MouseDown, FrameContext) -> void } -> self
+    def on_hover: () { (Input::MouseMove, FrameContext) -> void } -> self
+    def on_drag: () { (Input::MouseMove, FrameContext) -> void } -> self
+    def on_scroll_wheel: () { (Input::ScrollWheel, FrameContext) -> void } -> self
+    def on_mouse_down: () { (Input::MouseDown, FrameContext) -> void } -> self
+    def on_mouse_up: () { (Input::MouseUp, FrameContext) -> void } -> self
+    def request_layout: (FrameContext context) -> Layout::Node
+    def prepaint: (Bounds bounds, Object? state, FrameContext context) -> void
+    def paint: (Bounds bounds, Object? state, Object? prepaint, FrameContext context) -> void
+  end
+  class Div < Element
+  end
+  class Text < Element
+    def initialize: (String text, ?size: Numeric, ?color: color, ?font: TextSystem::_Font?) -> void
+    def measured: () { (Numeric width, Numeric height) -> Layout::measurement } -> self
+  end
+  class Image < Element
+    def initialize: (String path) -> void
+  end
+  class Canvas < Element
+    def initialize: () { (Bounds, FrameContext) -> void } -> void
+  end
+  class Overlay < Div
+  end
+  class Anchored < Div
+    def initialize: (anchor: Point, ?offset: Point) -> void
+  end
+  class UniformList < Element
+    attr_accessor scroll_y: Numeric
+    attr_reader visible_range: Range[Integer]?
+    def initialize: (count: Integer, row_height: Numeric) { (Integer) -> Element } -> void
+  end
+
+  class SVG < Element
+    interface _Outline
+      def commands: () -> Array[Symbol]
+      def coordinates: () -> Array[Float]
+      def empty?: () -> bool
+      def bounds: () -> [Numeric, Numeric, Numeric, Numeric]
+    end
+    class Path
+      def self.parse: (String source) -> _Outline
+      def initialize: (String source) -> void
+      def parse: () -> _Outline
+    end
+    attr_reader width: Numeric
+    attr_reader height: Numeric
+    attr_reader view_box: Array[Numeric]
+    def self.parse: (String source, ?color: String) -> SVG
+    def self.open: (String path, ?color: String) -> SVG
+    def initialize: (String source, ?color: String) -> void
+    def texture: (?width: Integer, ?height: Integer, ?color: String) -> GPU::Texture
+  end
+
+  class List < Element
+    attr_reader scroll_y: Float
+    attr_reader visible_range: Range[Integer]
+    attr_reader heights: HeightIndex
+    def initialize: (count: Integer, ?estimated_height: Numeric, ?overscan: Integer) { (Integer) -> Element } -> void
+    def scroll_y=: (Numeric value) -> Numeric
+    def total_height: () -> Float
+    def update_height: (Integer index, Numeric height) -> self
+    def scroll_to: (Integer index, ?align: :start | :center | :end | :nearest) -> self
+    class HeightIndex
+      attr_reader count: Integer
+      def initialize: (Integer count, Numeric estimate) -> void
+      def []: (Integer index) -> Float
+      def update: (Integer index, Numeric height) -> Float
+      def prefix: (Integer index) -> Float
+      def total: () -> Float
+      def index_at: (Numeric y) -> Integer
+    end
+  end
+
+  class View
+    include LengthUnits
+    def div: () -> Div
+    def text: (String value, ?size: Numeric, ?color: color, ?font: TextSystem::_Font?) -> Text
+    def render: (FrameContext | EntityContext[untyped] context) -> Element
+    def svg: (String source, ?color: String) -> SVG
+    def list: (count: Integer, ?estimated_height: Numeric, ?overscan: Integer) { (Integer) -> Element } -> List
+  end
+end

data/sig/gpu.rbs

@@ -0,0 +1,108 @@
+module Zaniah
+  module GPU
+    type format = :r8 | :rgba8
+    type shader = :quad | :mono_sprite | :poly_sprite
+    interface _Device
+      def width: () -> Numeric
+      def height: () -> Numeric
+      def pixels: () -> String
+      def resize: (Numeric width, Numeric height) -> void
+      def create_texture: (Integer width, Integer height, ?format: format, ?data: String?) -> Texture
+      def create_buffer: (Integer size, ?usage: Symbol, ?mutable: bool) -> Buffer
+      def create_pipeline: (shader: shader, ?blend: Symbol) -> Pipeline
+      def begin_frame: (?clear: color) -> FrameEncoder
+      def render: (Scene scene, ?clear: color) -> void
+      def write_png: (String path) -> Integer
+      def release: () -> void
+    end
+    def self.create: (?Platform::Headless::Window? window, ?backend: :software | :metal | :opengl, ?width: Numeric?, ?height: Numeric?) -> _Device
+
+    class Buffer
+      attr_reader size: Integer
+      attr_reader usage: Symbol
+      attr_reader data: String
+      def initialize: (Integer size, ?usage: Symbol, ?mutable: bool) -> void
+      def write: (String bytes, ?offset: Integer) -> self
+      def release: () -> String
+    end
+    class Texture
+      attr_reader width: Integer
+      attr_reader height: Integer
+      attr_reader format: format
+      attr_reader data: String
+      attr_reader revision: Integer
+      def initialize: (Integer width, Integer height, ?format: format, ?data: String?) -> void
+      def upload: (Integer x, Integer y, Integer width, Integer height, String bytes) -> self
+      def release: () -> Integer
+    end
+    class Pipeline < Data
+      attr_reader shader: shader
+      attr_reader blend: Symbol
+      def self.new: (shader shader, Symbol blend) -> Pipeline
+                  | (shader: shader, blend: Symbol) -> Pipeline
+    end
+    class FrameEncoder
+      def initialize: (_Device device, color clear) -> void
+      def set_pipeline: (Pipeline pipeline) -> Pipeline
+      def set_uniforms: (**Numeric | Array[Numeric] values) -> Hash[Symbol, Numeric | Array[Numeric]]
+      def set_texture: (Integer slot, Texture texture) -> Texture
+      def set_scissor: (Bounds? bounds) -> Bounds?
+      def draw_instanced: (vertex_count: Integer, instance_buffer: Buffer, instance_count: Integer) -> void
+      def present: () -> void
+    end
+    class Software
+      attr_reader width: Integer
+      attr_reader height: Integer
+      attr_reader pixels: String
+      def initialize: (Numeric width, Numeric height) -> void
+      def resize: (Numeric width, Numeric height) -> void
+      def create_texture: (Integer width, Integer height, ?format: format, ?data: String?) -> Texture
+      def create_buffer: (Integer size, ?usage: Symbol, ?mutable: bool) -> Buffer
+      def create_pipeline: (shader: shader, ?blend: Symbol) -> Pipeline
+      def begin_frame: (?clear: color) -> FrameEncoder
+      def render: (Scene scene, ?clear: color) -> String
+      def write_png: (String path) -> Integer
+      def release: () -> String
+    end
+    class Metal
+      attr_reader width: Numeric
+      attr_reader height: Numeric
+      attr_reader draw_calls: Integer
+      def initialize: (Platform::Mac::Window window) -> void
+      def resize: (Numeric width, Numeric height) -> void
+      def create_texture: (Integer width, Integer height, ?format: format, ?data: String?) -> Texture
+      def create_buffer: (Integer size, ?usage: Symbol, ?mutable: bool) -> Buffer
+      def create_pipeline: (shader: shader, ?blend: Symbol) -> Pipeline
+      def begin_frame: (?clear: color) -> FrameEncoder
+      def render: (Scene scene, ?clear: color) -> void
+      def pixels: () -> String
+      def write_png: (String path) -> Integer
+      def release: () -> void
+    end
+    class OpenGL
+      attr_reader width: Numeric
+      attr_reader height: Numeric
+      attr_reader draw_calls: Integer
+      def resize: (Numeric width, Numeric height) -> void
+      def create_texture: (Integer width, Integer height, ?format: format, ?data: String?) -> Texture
+      def create_buffer: (Integer size, ?usage: Symbol, ?mutable: bool) -> Buffer
+      def create_pipeline: (shader: shader, ?blend: Symbol) -> Pipeline
+      def begin_frame: (?clear: color) -> FrameEncoder
+      def render: (Scene scene, ?clear: color, ?capture: bool) -> void
+      def pixels: () -> String
+      def write_png: (String path) -> Integer
+      def release: () -> void
+    end
+    # Optional offscreen triangle probe, not a full window-renderer interface.
+    class Vulkan
+      attr_reader width: Integer
+      attr_reader height: Integer
+      attr_reader pixels: String
+      attr_reader device_name: String
+      def initialize: (?width: Integer, ?height: Integer) -> void
+      def render_triangle: (vertex_spirv: String, fragment_spirv: String) -> void
+      def write_png: (String path) -> Integer
+      def release: () -> void
+    end
+  end
+end