zaniah 0.1.0

data/lib/zaniah/png.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Zaniah
+  # Runtime headless output uses only the Ruby standard distribution.
+  module PNG
+    SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+    module_function
+
+    def encode(width, height, rgba)
+      raise ArgumentError, "invalid image dimensions" unless width.positive? && height.positive? && rgba.bytesize == width * height * 4
+      scanlines = String.new(encoding: Encoding::BINARY)
+      height.times { |row| scanlines << "\0" << rgba.byteslice(row * width * 4, width * 4) }
+      SIGNATURE + chunk("IHDR", [width, height, 8, 6, 0, 0, 0].pack("NNC5")) +
+        chunk("IDAT", Zlib::Deflate.deflate(scanlines)) + chunk("IEND", "".b)
+    end
+
+    def write(path, width, height, rgba) = File.binwrite(path, encode(width, height, rgba))
+
+    def decode(bytes, max_pixels: 16_777_216)
+      raise ArgumentError, "not a PNG" unless bytes.start_with?(SIGNATURE)
+
+      header, compressed = parse_chunks(bytes)
+      width, height, type, channels = decode_header(header, max_pixels)
+      stride = width * channels
+      raw = inflate(compressed, (stride + 1) * height)
+      [width, height, decode_scanlines(raw, width, height, type, channels)]
+    end
+
+    def parse_chunks(bytes)
+      offset, compressed, header, ended = 8, String.new(encoding: Encoding::BINARY), nil, false
+      while offset + 12 <= bytes.bytesize
+        size = bytes.byteslice(offset, 4).unpack1("N")
+        raise ArgumentError, "truncated PNG" if offset + 12 + size > bytes.bytesize
+        kind = bytes.byteslice(offset + 4, 4)
+        data = bytes.byteslice(offset + 8, size)
+        crc = bytes.byteslice(offset + 8 + size, 4).unpack1("N")
+        raise ArgumentError, "PNG checksum mismatch" unless Zlib.crc32(kind + data) == crc
+        case kind
+        when "IHDR" then header = data.unpack("NNC5")
+        when "IDAT" then compressed << data
+        when "IEND" then ended = true; break
+        end
+        offset += size + 12
+      end
+      raise ArgumentError, "missing PNG header or end" unless header && ended
+
+      [header, compressed]
+    end
+
+    def decode_header(header, max_pixels)
+      width, height, depth, type, compression, filter, interlace = header
+      raise ArgumentError, "unsupported PNG encoding" unless depth == 8 && compression == 0 && filter == 0 && interlace == 0 && [0, 2, 4, 6].include?(type)
+      raise ArgumentError, "PNG too large" unless width.positive? && height.positive? && width * height <= max_pixels
+      channels = {0 => 1, 2 => 3, 4 => 2, 6 => 4}.fetch(type)
+
+      [width, height, type, channels]
+    end
+
+    def inflate(compressed, expected)
+      raw = String.new(encoding: Encoding::BINARY)
+      inflater = Zlib::Inflate.new
+      begin
+        inflater.inflate(compressed) do |part|
+          raise ArgumentError, "excess PNG data" if raw.bytesize + part.bytesize > expected
+          raw << part
+        end
+      ensure
+        inflater.close
+      end
+      raise ArgumentError, "incorrect PNG data length" unless raw.bytesize == expected
+
+      raw
+    end
+
+    def decode_scanlines(raw, width, height, type, channels)
+      stride = width * channels
+      previous = Array.new(stride, 0)
+      rgba = String.new(capacity: width * height * 4, encoding: Encoding::BINARY)
+      height.times do |row|
+        method = raw.getbyte(row * (stride + 1))
+        raise ArgumentError, "invalid PNG filter" unless (0..4).cover?(method)
+        current = raw.byteslice(row * (stride + 1) + 1, stride).bytes
+        stride.times do |i|
+          left = i < channels ? 0 : current[i - channels]
+          up, upper_left = previous[i], i < channels ? 0 : previous[i - channels]
+          prediction = case method
+          when 0 then 0
+          when 1 then left
+          when 2 then up
+          when 3 then (left + up) / 2
+          when 4
+            p = left + up - upper_left
+            [left, up, upper_left].min_by { |v| (p - v).abs }
+          end
+          current[i] = (current[i] + prediction) & 255
+        end
+        current.each_slice(channels) do |pixel|
+          rgba << case type
+          when 0 then [pixel[0], pixel[0], pixel[0], 255].pack("C4")
+          when 2 then [*pixel, 255].pack("C4")
+          when 4 then [pixel[0], pixel[0], pixel[0], pixel[1]].pack("C4")
+          when 6 then pixel.pack("C4")
+          end
+        end
+        previous = current
+      end
+      rgba
+    end
+
+    def chunk(kind, data)
+      [data.bytesize].pack("N") + kind + data + [Zlib.crc32(kind + data)].pack("N")
+    end
+
+    private_class_method :parse_chunks, :decode_header, :inflate, :decode_scanlines
+  end
+end

data/lib/zaniah/point.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Zaniah
+  Point = Data.define(:x, :y) do
+    def +(other) = Point.new(x + other.x, y + other.y)
+    def -(other) = Point.new(x - other.x, y - other.y)
+  end
+end

data/lib/zaniah/process_pool/worker.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Zaniah
+  class ProcessPool
+    Worker = Struct.new(:pid, :reader, :writer, :task, :retire, :thread)
+  end
+end

data/lib/zaniah/process_pool.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "process_wire"
+
+module Zaniah
+  # Fixed parallelism, bounded data-only IPC, portable spawn or legacy fork.
+  class ProcessPool
+    def initialize(workers: 2, handler: nil, requires: [], load_paths: [], max_pending: workers * 2, max_bytes: 16 << 20, &block)
+      raise ArgumentError, "workers must be in 1..32" unless workers.is_a?(Integer) && workers.between?(1, 32)
+      raise ArgumentError, "max_pending must be in 1..1024" unless max_pending.is_a?(Integer) && max_pending.between?(1, 1024)
+      raise ArgumentError, "max_bytes must be in 4096..67108864" unless max_bytes.is_a?(Integer) && max_bytes.between?(4096, 64 << 20)
+      raise ArgumentError, "provide a named handler or a block, not both" if !!handler == !!block
+      if handler
+        raise ArgumentError, "handler must be a constant name" unless handler.is_a?(String) && handler.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/)
+      elsif !Process.respond_to?(:fork)
+        raise Error, "block workers require fork; use handler: and requires: on this platform"
+      end
+      @requires = checked_paths(requires, file: true)
+      @load_paths = checked_paths(load_paths, file: false)
+      @handler, @block, @max_pending, @max_bytes = handler&.dup&.freeze, block, max_pending, max_bytes
+      @mutex, @condition, @queue, @pending, @control = Mutex.new, ConditionVariable.new, [], {}, Queue.new
+      @workers = Array.new(workers) { Worker.new }
+      @supervisor = Thread.new { supervise }
+      @workers.each { |entry| entry.thread = Thread.new { run_worker(entry) } }
+    end
+
+    # Snapshot before enqueueing, so later caller mutations cannot race IPC.
+    # Large snapshots should be submitted from a TaskExecutor background task.
+    def submit(data)
+      @mutex.synchronize { ensure_accepting_tasks }
+      bytes = ProcessWire.encode_frame(data, @max_bytes)
+      task = Task.new
+      task.on_complete do
+        @mutex.synchronize do
+          @pending.delete(task)
+          @queue.delete_if { |queued, _| queued.equal?(task) }
+        end
+        @control << task # Cancellation never waits on a pipe or child process.
+      end
+      @mutex.synchronize do
+        ensure_accepting_tasks
+        @pending[task] = true
+        @queue << [task, bytes]
+        @condition.signal
+      end
+      task
+    end
+
+    def shutdown(timeout: 2)
+      raise ArgumentError, "timeout must be finite and positive" unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+      tasks = @mutex.synchronize do
+        @closed = true
+        saved = @pending.keys
+        @queue.clear
+        @condition.broadcast
+        saved
+      end
+      @control << :shutdown
+      tasks.each { |task| complete_task(task, error: Task::Cancelled.new("process pool shut down")) }
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      [@supervisor, *@workers.map(&:thread)].each do |thread|
+        next if thread.equal?(Thread.current)
+        remaining = [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
+        raise Task::Timeout, "process pool cleanup is still running" unless thread.join(remaining)
+      end
+      nil
+    end
+
+    private
+
+    def checked_paths(paths, file:)
+      raise ArgumentError, "worker paths must be an array" unless paths.is_a?(Array)
+      paths.map do |path|
+        raise ArgumentError, "worker paths must be absolute existing paths" unless path.is_a?(String) &&
+          File.absolute_path(path) == path && (file ? File.file?(path) : File.directory?(path))
+        path.dup.freeze
+      end.freeze
+    end
+
+    def ensure_accepting_tasks
+      raise Error, "process pool is shut down" if @closed
+      raise Error, "process pool queue is full" if @pending.length >= @max_pending
+    end
+
+    def take_job(entry)
+      @mutex.synchronize do
+        @condition.wait(@mutex) while @queue.empty? && !@closed
+        return if @closed
+        task, bytes = @queue.shift
+        entry.task = task
+        [task, bytes]
+      end
+    end
+
+    def run_worker(entry)
+      while (job = take_job(entry))
+        task, bytes = job
+        value = error = nil
+        begin
+          unless task.done?
+            start_worker(entry) unless entry.pid
+            unless task.done? || @closed
+              entry.writer.write(bytes)
+              body = ProcessWire.read_payload(entry.reader, @max_bytes)
+              raise Error, "process worker exited without a response" unless body
+              response = ProcessWire.decode_payload(body)
+              raise Error, "invalid process worker response" unless response.is_a?(Array) && response.length == 2 && [true, false].include?(response[0])
+              unless response[0]
+                raise Error, "invalid process worker error" unless response[1].is_a?(String)
+                raise Error, response[1]
+              end
+              value = response[1]
+            end
+          end
+        rescue StandardError => failure
+          error = failure
+        ensure
+          retire = @mutex.synchronize do
+            entry.task = nil
+            @pending.delete(task)
+            entry.retire || @closed || task.done? || error
+          end
+          stop_worker(entry) if retire
+        end
+        complete_task(task, value, error: error)
+      end
+    ensure
+      stop_worker(entry)
+    end
+
+    def complete_task(task, value = nil, error: nil)
+      task.resolve(value, error: error)
+    rescue StandardError => failure
+      begin
+        warn "Process task callback failed: #{ProcessWire.error_message(failure)}"
+      rescue StandardError
+        nil
+      end
+    end
+
+    def supervise
+      loop do
+        task = @control.pop
+        @mutex.synchronize do
+          @workers.each do |entry|
+            next unless task == :shutdown || entry.task.equal?(task)
+            next if entry.retire
+            entry.retire = true
+            terminate_worker_process(entry.pid) if entry.pid
+          end
+        end
+        break if task == :shutdown
+      end
+    end
+
+    def start_worker(entry)
+      child_in, writer = IO.pipe
+      reader, child_out = IO.pipe
+      [reader, writer, child_in, child_out].each(&:binmode)
+      writer.sync = true
+      pid = if @handler
+        jit = defined?(RubyVM::YJIT) && RubyVM::YJIT.enabled? ? ["--yjit"] : []
+        command = [RbConfig.ruby, *jit, *@load_paths.flat_map { |path| ["-I", path] },
+          File.expand_path("process_wire.rb", __dir__), @handler, @max_bytes.to_s, *@requires]
+        options = {in: child_in, out: child_out, err: STDERR, close_others: true}
+        options[windows? ? :new_pgroup : :pgroup] = true
+        Process.spawn({"RUBYOPT" => nil, "RUBYLIB" => nil}, *command, **options)
+      else
+        Process.fork do
+          Process.setpgrp
+          reader.close
+          writer.close
+          @workers.each { |other| [other.reader, other.writer].compact.each { |io| io.close unless io.closed? } }
+          begin
+            ProcessWire.serve(child_in, child_out, @max_bytes, @block)
+            exit! 0
+          rescue Exception
+            exit! 1
+          end
+        end
+      end
+      @mutex.synchronize do
+        entry.pid, entry.reader, entry.writer, entry.retire = pid, reader, writer, false
+        terminate_worker_process(pid) if @closed || entry.task.done?
+      end
+    rescue Exception
+      [reader, writer].compact.each { |io| io.close unless io.closed? }
+      raise
+    ensure
+      [child_in, child_out].compact.each { |io| io.close unless io.closed? }
+    end
+
+    def windows? = /mswin|mingw/.match?(RbConfig::CONFIG.fetch("host_os"))
+
+    def terminate_worker_process(pid)
+      Process.kill("KILL", windows? ? pid : -pid)
+    rescue Errno::EPERM => error
+      # macOS can report EPERM for a group whose last process just exited.
+      # Do not mask a real permission failure against a still-existing child.
+      begin
+        windows? ? Process.kill(0, pid) : Process.getpgid(pid)
+      rescue Errno::ESRCH
+        return
+      end
+      raise error
+    rescue Errno::ESRCH
+      begin
+        Process.kill("KILL", pid) # A just-forked child may not have set its group yet.
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+
+    def stop_worker(entry)
+      pid = @mutex.synchronize do
+        saved, entry.pid = entry.pid, nil
+        saved
+      end
+      return unless pid
+      unless Process.waitpid(pid, Process::WNOHANG)
+        terminate_worker_process(pid)
+        Process.wait(pid)
+      end
+    rescue Errno::ECHILD
+      nil
+    rescue StandardError
+      # Retain the exact child identity if the OS denies termination/reaping;
+      # a later shutdown must not mistake a failed cleanup for no child.
+      @mutex.synchronize { entry.pid = pid } if pid
+      raise
+    ensure
+      [entry.reader, entry.writer].compact.each { |io| io.close unless io.closed? }
+      entry.reader = entry.writer = nil
+    end
+  end
+end
+
+require_relative "process_pool/worker"

data/lib/zaniah/process_wire.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Zaniah
+  # Only primitive JSON data crosses this local, trusted-code boundary. No
+  # Marshal hooks, constant reconstruction, source text or eval is involved.
+  module ProcessWire
+    MAX_DEPTH = 64
+    MAX_NODES = 1_000_000
+
+    def self.validate_payload(value, depth = 0, budget = [MAX_NODES, nil, nil], freeze: false)
+      raise ArgumentError, "IPC data is too deeply nested" if depth > MAX_DEPTH
+      raise ArgumentError, "IPC data has too many values" if (budget[0] -= 1).negative?
+      case value.class.name
+      when "NilClass", "TrueClass" then charge_budget(budget, 4)
+      when "FalseClass" then charge_budget(budget, 5)
+      when "Integer"
+        raise ArgumentError, "IPC integer exceeds byte budget" if budget[1] && value.bit_length > budget[1] * 4
+        charge_budget(budget, value.to_s.bytesize)
+      when "Float"
+        raise ArgumentError, "IPC numbers must be finite" unless value.finite?
+        charge_budget(budget, value.to_s.bytesize)
+      when "String"
+        raise ArgumentError, "IPC strings must be valid UTF-8" unless value.valid_encoding? &&
+          (value.encoding == Encoding::UTF_8 || value.ascii_only?)
+        if budget[1]
+          charge_budget(budget, value.bytesize + 2)
+          # JSON escapes quotes/backslashes and control characters. Count in
+          # native String scans before generating any potentially large JSON.
+          charge_budget(budget, value.count('"') + value.count("\\") +
+            value.count("\x00-\x1f") * 5 - value.count("\b\t\n\f\r") * 4)
+        end
+      when "Array"
+        charge_budget(budget, 2 + [value.length - 1, 0].max)
+        value.each { |item| validate_payload(item, depth + 1, budget, freeze: freeze) }
+      when "Hash"
+        charge_budget(budget, 2 + value.length + [value.length - 1, 0].max)
+        value.each do |key, item|
+          raise ArgumentError, "IPC object keys must be strings" unless key.instance_of?(String)
+          validate_payload(key, depth + 1, budget, freeze: freeze)
+          validate_payload(item, depth + 1, budget, freeze: freeze)
+        end
+      else
+        raise ArgumentError, "IPC values must be plain JSON data"
+      end
+      value.freeze if freeze
+      value
+    end
+
+    def self.charge_budget(budget, bytes)
+      return unless budget[1]
+      raise ArgumentError, "IPC frame exceeds #{budget[2]} bytes" if (budget[1] -= bytes).negative?
+    end
+
+    def self.encode_frame(value, max_bytes)
+      validate_payload(value, 0, [MAX_NODES, max_bytes, max_bytes])
+      body = JSON.generate(value, max_nesting: MAX_DEPTH)
+      raise ArgumentError, "IPC frame exceeds #{max_bytes} bytes" if body.bytesize > max_bytes
+      [body.bytesize].pack("N") + body.b
+    end
+
+    def self.read_payload(io, max_bytes)
+      header = io.read(4)
+      return if header.nil?
+      raise IOError, "truncated IPC header" unless header.bytesize == 4
+      length = header.unpack1("N")
+      raise IOError, "invalid IPC frame length" unless length.between?(1, max_bytes)
+      body = io.read(length)
+      raise IOError, "truncated IPC payload" unless body && body.bytesize == length
+      body.force_encoding(Encoding::UTF_8)
+      raise IOError, "invalid IPC UTF-8" unless body.valid_encoding?
+      body
+    end
+
+    def self.decode_payload(body)
+      validate_payload(JSON.parse(body, max_nesting: MAX_DEPTH, create_additions: false), freeze: true)
+    end
+
+    def self.error_message(error)
+      "#{error.class}: #{error.message}".encode(Encoding::UTF_8, invalid: :replace, undef: :replace).byteslice(0, 2048).scrub("")
+    end
+
+    private_class_method :validate_payload, :charge_budget
+
+    def self.serve(input, output, max_bytes, handler)
+      input.binmode
+      output.binmode
+      output.sync = true
+      while (body = read_payload(input, max_bytes))
+        response = begin
+          encode_frame([true, handler.call(decode_payload(body))], max_bytes)
+        rescue StandardError => error
+          encode_frame([false, error_message(error)], max_bytes)
+        end
+        output.write(response)
+      end
+    end
+
+    def self.run
+      # Keep protocol output private; even a required file's `puts` is harmless.
+      output = STDOUT.dup
+      STDOUT.reopen(STDERR)
+      $stdout = STDERR
+      name, maximum, *requires = ARGV
+      raise ArgumentError, "invalid worker handler" unless name&.match?(/\A[A-Z]\w*(?:::[A-Z]\w*)*\z/)
+      max_bytes = Integer(maximum)
+      requires.each { |path| require path }
+      handler = name.split("::").reduce(Object) { |scope, part| scope.const_get(part, false) }
+      raise ArgumentError, "worker handler must respond to .call" unless handler.is_a?(Module) && handler.respond_to?(:call)
+      serve(STDIN, output, max_bytes, handler)
+    rescue StandardError => error
+      output.write(encode_frame([false, error_message(error)], max_bytes)) if output && max_bytes
+    ensure
+      output&.close
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  # Ruby does not put its entry script in $LOADED_FEATURES. A handler may load
+  # zaniah, which requires this file again through ProcessPool; register it
+  # before loading handlers so that require cannot re-enter worker startup.
+  path = File.realpath(__FILE__)
+  $LOADED_FEATURES << path unless $LOADED_FEATURES.include?(path)
+  Zaniah::ProcessWire.run
+end

data/lib/zaniah/quad_packer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zaniah
+  class QuadPacker
+    attr_reader :bytes
+
+    def initialize = @bytes = String.new(capacity: 1 << 20, encoding: Encoding::BINARY)
+
+    def pack(scene)
+      @bytes.clear
+      @bytes << scene.quads.pack("f*")
+      @bytes
+    end
+  end
+end

data/lib/zaniah/scene/sprite_batch.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Zaniah
+  class Scene
+    SpriteBatch = Data.define(:bytes, :texture)
+  end
+end

data/lib/zaniah/scene.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Zaniah
+  # Primitive payloads are flat arrays; command order preserves alpha compositing.
+  class Scene
+    QUAD_STRIDE = 17
+    SPRITE_INSTANCE_BYTES = 24 * 4
+    attr_reader :quads, :paths, :commands, :textures, :sprite_batches
+
+    def initialize
+      @quads, @sprites, @paths, @commands, @textures = [], [], [], [], []
+      @sprite_batches, @expanded_batches = [], {}
+      @clips, @layers = [], [0]
+      @colors, @last_layer, @ordered = {}, -Float::INFINITY, true
+    end
+
+    def clear
+      [@quads, @sprites, @paths, @commands, @textures, @clips].each(&:clear)
+      @sprite_batches.clear
+      @expanded_batches.clear
+      @layers.replace([0])
+      @last_layer, @ordered = -Float::INFINITY, true
+      self
+    end
+
+    def quad(x, y, width, height, color:, radius: 0, border_width: 0, border_color: "#0000")
+      return self if width <= 0 || height <= 0
+      offset = @quads.length
+      if radius.is_a?(Numeric)
+        @quads.push(x, y, width, height, *color_values(color), radius, radius, radius, radius, border_width, *color_values(border_color))
+      else
+        corners = radius.to_a
+        raise ArgumentError, "four radii required" unless corners.length == 4
+        @quads.push(x, y, width, height, *color_values(color), *corners, border_width, *color_values(border_color))
+      end
+      command(:quad, offset)
+      self
+    end
+
+    def push_quad(x, y, width, height, bg, radius, border_width, border_color, order = 0)
+      layer(order) { quad(x, y, width, height, color: bg, radius: radius,
+                          border_width: border_width, border_color: border_color) }
+    end
+
+    def sprite(x, y, width, height, texture:, color: "#fff", source: nil)
+      source ||= Bounds.new(0, 0, texture.width, texture.height)
+      id = @textures.index(texture) || @textures.push(texture).length - 1
+      offset = @sprites.length
+      @sprites.push(x, y, width, height, *color_values(color), id,
+                    source.x, source.y, source.width, source.height)
+      command(:sprite, offset)
+      self
+    end
+
+    # Prepacked GPU instances retain ordinary sprite alpha/clip/layer ordering.
+    def sprite_batch(bytes, texture: nil)
+      batch = bytes if bytes.is_a?(SpriteBatch)
+      bytes, texture = batch.bytes, batch.texture if batch
+      raise ArgumentError, "invalid packed sprite bytes" unless bytes.is_a?(String) && bytes.bytesize % SPRITE_INSTANCE_BYTES == 0
+      raise ArgumentError, "packed sprites need a texture" unless texture.is_a?(GPU::Texture)
+      return self if bytes.empty?
+      @textures << texture unless @textures.include?(texture)
+      offset = @sprite_batches.length
+      @sprite_batches << (batch && bytes.frozen? ? batch : SpriteBatch.new(bytes.frozen? ? bytes : bytes.dup.freeze, texture))
+      command(:sprite_batch, offset)
+      self
+    end
+
+    # Preserve the public flat-sprite inspection API; native packing does not
+    # materialize these arrays, while the software renderer can reuse them.
+    def sprites
+      @sprite_batches.each_index { |index| expand_sprite_batch(index) }
+      @sprites
+    end
+    def sprite_data = @sprites
+    def expand_sprite_batch(index)
+      @expanded_batches[index] ||= begin
+        batch = @sprite_batches.fetch(index)
+        texture = batch.texture
+        id = @textures.index(texture)
+        offset = @sprites.length
+        batch.bytes.unpack("f*").each_slice(24) do |values|
+          @sprites.push(*values[0, 8], id, values[20] * texture.width, values[21] * texture.height,
+                        values[22] * texture.width, values[23] * texture.height)
+        end
+        [offset, batch.bytes.bytesize / SPRITE_INSTANCE_BYTES]
+      end
+    end
+
+    def triangle(points, color:)
+      raise ArgumentError, "three points required" unless points.length == 6
+      offset = @paths.length
+      @paths.push(*points, *color_values(color))
+      command(:triangle, offset)
+      self
+    end
+
+    def shadow(x, y, width, height, color: "#0006", blur: 8, radius: 0)
+      raise ArgumentError, "blur must be positive" unless blur.positive?
+      # A small sequence of expanding translucent rounded rectangles approximates
+      # a Gaussian convolution without a temporary render target.
+      8.downto(1) do |step|
+        spread = blur * step / 8.0
+        alpha = Math.exp(-2.0 * (step / 8.0)**2) / 10.0
+        quad(x - spread, y - spread, width + 2 * spread, height + 2 * spread,
+             color: Color.parse(color).opacity(alpha), radius: radius + spread)
+      end
+      self
+    end
+
+    def underline(x, y, width, color:, thickness: 1, wave: false)
+      return quad(x, y, width, thickness, color: color) unless wave
+      width.ceil.times do |i|
+        quad(x + i, y + Math.sin(i * Math::PI / 4) * thickness, 1, thickness, color: color)
+      end
+      self
+    end
+
+    def clip(bounds)
+      @clips << (@clips.empty? ? bounds : @clips.last.intersect(bounds))
+      yield
+    ensure
+      @clips.pop
+    end
+    def current_clip = @clips.last
+
+    def layer(order)
+      @layers << order
+      yield
+    ensure
+      @layers.pop
+    end
+
+    def each_command
+      return enum_for(__method__) unless block_given?
+      if @ordered
+        index = 0
+        while index < @commands.length
+          yield @commands[index], @commands[index + 1], @commands[index + 3]
+          index += 4
+        end
+        return
+      end
+      indices = (0...@commands.length).step(4).to_a
+      indices.sort_by! { |i| [@commands[i + 2], i] }
+      indices.each { |i| yield @commands[i], @commands[i + 1], @commands[i + 3] }
+    end
+
+    private
+
+    def color_values(value)
+      @colors.clear if @colors.length > 256
+      @colors[value] ||= Color.parse(value).to_a.freeze
+    end
+
+    def command(kind, offset)
+      @ordered = false if @layers.last < @last_layer
+      @last_layer = @layers.last
+      @commands.push(kind, offset, @layers.last, @clips.last)
+    end
+  end
+
+end
+
+require_relative "scene/sprite_batch"
+require_relative "quad_packer"
+require_relative "scene_renderer"