zaniah 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83f0e9d7ba2790764f55bc1e0eda5e21e31b22a54cd0a92668b24df9000d351c
-  data.tar.gz: 37a96934f06671e69989c1e2e91e30917e0b6902458a09fc05fd5ef3999030f3
+  metadata.gz: e74156d5d7a3d4ed439e9d46aac5e8fb25b65e974013937dcc1743a5ae1aa665
+  data.tar.gz: ad0468ac4a87fc3181974ad2b905a515b3c414e30df4b190ba07b220c3ecfbc6
 SHA512:
-  metadata.gz: 3feda2d8ba35caa3b73821eb9cae80c64d8b549e87c125dd6f55c4382d9789451bd91e0ae2e019709e1f923b662b498265085c6c0fcd268dad3a94ce7ab6c4c3
-  data.tar.gz: ef1e4f76251e22c1a8317677cccc3b80885aec8f3bb917d09df7a363a9dbfb6976ed19e38565a75eb5bf656b2a2f3276daada27156d79eb250d6e734ff1ad62b
+  metadata.gz: f65083c0483107b854879b2303b4bb87d4c05debcaba6167d7335596628d5ccab4d4ccf310d99fd2c10958a3edefa7355d9d9d0229541dc1bc6cba639c8ffc87
+  data.tar.gz: 5881db80886ae7543493bdaebc459301968075b1a41a375e93b0f91a1566829bd5c3169190ff342cfed7e4bd2dc2b573827e7331f2e920a22fd6e2c874d34242

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.0 — 2026-09-11
+
+- Add read-only element, hit-region, popup, and frame inspection APIs.
+- Add injectable monotonic clocks and headless-window keymaps.
+- Keep adjacent compact text rows separate in the TUI renderer.
+
 ## 0.1.0 — 2026-09-11
 
 - Initial release.

data/README.md

@@ -1,29 +1,77 @@
-# Zaniah
+<p align="center">
+  <img src="assets/logo.png" alt="Zaniah logo">
+</p>
 
-A Ruby UI toolkit with native GPU windows, a headless renderer, and a terminal
-backend. CRuby 3.1+; YJIT recommended. Runtime dependencies are Alhena, REXML
-and unicode-display_width.
+<p align="center">
+  <strong>Ruby UI toolkit with native GPU windows, headless rendering, and a terminal backend</strong>
+</p>
 
-The name comes from the white ground laid before paint or gold leaf: this
-toolkit is the drawing surface beneath the editor.
+<p align="center">
+  <a href="https://rubygems.org/gems/zaniah"><img src="https://img.shields.io/gem/v/zaniah.svg?colorB=319e8c" alt="Gem Version"></a>
+  <a href="https://rubygems.org/gems/zaniah"><img src="https://img.shields.io/gem/dt/zaniah.svg" alt="Downloads"></a>
+  <a href="https://github.com/noxdea/zaniah/actions/workflows/main.yml"><img src="https://github.com/noxdea/zaniah/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Ruby-%3E%3D%203.1-CC342D.svg" alt="Ruby 3.1+">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+</p>
 
-## Try it locally
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#platforms">Platforms</a> ·
+  <a href="#documentation">Documentation</a>
+</p>
+
+---
+
+Zaniah is a pure Ruby UI toolkit for building desktop and terminal interfaces.
+It renders through native GPU APIs, a deterministic headless backend, or an ANSI
+terminal without extension compilation or a rendering subprocess.
+
+The name comes from the white ground laid before paint or gold leaf: Zaniah is
+the drawing surface beneath the editor.
+
+## Features
+
+- Flex, constraint, absolute, wrapping, and baseline-aware layouts
+- Rounded rectangles, images, static SVG, shadows, clipping, and glyph atlases
+- Retained element state, subscriptions, and non-blocking background tasks
+- Uniform and variable-height virtual lists
+- OpenType ligatures and horizontal positioning with configurable text providers
+- Native input, IME, clipboard, file-drop, display, and filesystem events
+- RBS declarations for the public API
+
+## Installation
+
+Add Zaniah to your Gemfile:
+
+```ruby
+gem "zaniah"
+```
+
+Then install:
 
 ```sh
 bundle install
-bundle exec rake test
-ruby --yjit examples/native_smoke.rb
-gem build zaniah.gemspec
-gem install --local zaniah-0.1.0.gem
 ```
 
-The gem name is not published or reserved. Install the locally built artifact
-rather than an unverified public gem.
+### Requirements
+
+- CRuby 3.1 or later
+- YJIT recommended
+
+## Quick Start
+
+Create `hello.rb`:
 
 ```ruby
 require "zaniah"
 
-window = Zaniah::Platform.open_window(backend: :headless, width: 480, height: 240)
+window = Zaniah::Platform.open_window(
+  backend: :headless,
+  width: 480,
+  height: 240
+)
 window.text_system = Zaniah::TextSystem::Renderer.new
 window.draw do
   Zaniah::Div.new.flex_col.p(24).gap(12).bg("#161b22")
@@ -35,36 +83,54 @@ window.write_png("hello.png")
 window.close
 ```
 
-Choose `backend: :mac`, `:linux`, `:windows`, or `:tui` and call
-`window.run` for an interactive window. Native rendering uses OS libraries via
-Ruby's Fiddle, without extension compilation or a rendering subprocess.
+Run it to write `hello.png`:
+
+```sh
+bundle exec ruby hello.rb
+```
+
+For an interactive window, choose `backend: :mac`, `:linux`, `:windows`, or
+`:tui`, then call `window.run` instead of `window.tick`.
+
+## Platforms
+
+| Backend | Renderer | Notes |
+| --- | --- | --- |
+| `:mac` | Metal or OpenGL | Native macOS window |
+| `:linux` | Wayland/EGL or X11/GLX | Selected from the current display environment |
+| `:windows` | Win32/WGL | Requires 64-bit Ruby and Windows 10 APIs |
+| `:headless` | Pure Ruby software renderer | Deterministic rendering and PNG output |
+| `:tui` | ANSI terminal | Text-grid rendering and terminal input |
 
-## Toolkit and platforms
+Native backends use the operating system libraries through Ruby's Fiddle. See
+[Native backends](docs/native.md) for platform requirements and checks.
 
-Flex layouts, constraints, absolute positioning, wrapping, baseline alignment,
-clipping, retained element state, and uniform/variable-height virtual lists are
-provided. Generational entities and subscriptions connect state to frames;
-foreground Fibers can await background tasks without blocking the UI.
-Scene primitives include rounded rectangles, images, static SVG, shadows and
-glyph atlases. OpenType ligatures and horizontal positioning use the Ruby shaper.
-Pure Ruby rasterization is the default; explicit CoreText/FreeType providers and
-a licensed Abel fallback font are included.
+## Documentation
+
+- [Native backends](docs/native.md) — windows, displays, file watching, and terminals
+- [Text system](docs/text.md) — font discovery, shaping, rasterization, and caching
+- [SVG and lists](docs/vector_and_list.md) — static vector icons and virtual lists
+- [CPU process workers](docs/process_pool.md) — portable background CPU work
+- [Architecture decisions](docs/adr) — design records and rationale
+- [RBS declarations](sig) — public API signatures
 
 ## Development
 
 ```sh
+bundle install
 bundle exec rake test
-ruby --yjit bench/instances.rb
-ruby --yjit bench/list.rb
+bundle exec rake bench
+gem build --strict zaniah.gemspec
 ```
 
-`BUDGET=1` enables benchmark assertions.
+Set `BUDGET=1` to enable benchmark assertions.
+
+## Contributing
 
-See [native details](docs/native.md), [text configuration and shaping](docs/text.md),
-[SVG and lists](docs/vector_and_list.md), [portable CPU workers](docs/process_pool.md),
-and [decisions](docs/adr).
+Bug reports and pull requests are welcome at
+[github.com/noxdea/zaniah](https://github.com/noxdea/zaniah).
 
 ## License
 
-MIT; see [LICENSE.txt](LICENSE.txt). Included font notices remain alongside the
-font files.
+Zaniah is released under the [MIT License](LICENSE.txt). Included font notices
+remain alongside the font files.

data/lib/zaniah/app.rb

@@ -9,10 +9,11 @@ module Zaniah
   class App
     attr_reader :windows, :executor
 
-    def initialize
+    def initialize(clock: MONOTONIC_CLOCK)
       @slots, @generations, @free, @windows, @globals = [], [], [], [], {}
       @listeners, @effects, @updating, @flushing = {}, [], 0, false
-      @executor = TaskExecutor.new
+      @clock = clock
+      @executor = TaskExecutor.new(clock: clock)
     end
 
     def new_entity
@@ -103,6 +104,7 @@ module Zaniah
     end
 
     def open_window(**options, &render)
+      options[:clock] ||= @clock
       window = Platform.open_window(**options)
       @windows << window
       window.draw(&render) if render

data/lib/zaniah/element.rb

@@ -28,6 +28,8 @@ module Zaniah
     end
 
     def key(value) = (@key = value; self)
+    def test_id(value = (getter = true)) = getter ? @test_id : (@test_id = value.to_s.freeze; self)
+    def handlers = @handlers.keys.freeze
     def with_state(&initial) = (@state_initializer = initial; self)
     def bg(color) = (@background = color; self)
     def border_color(color) = (@border_color = color; self)
@@ -62,7 +64,7 @@ module Zaniah
 
     def prepaint(bounds, _state, cx)
       unless @handlers.empty? && !@tooltip && !@context_menu
-        cx.dispatcher.hit(bounds) do |event|
+        cx.dispatcher.hit(bounds, owner: self) do |event|
           if event.is_a?(Input::MouseDown) && event.button == :right && @context_menu
             cx.window.context_menu(@context_menu, position: event.position)
             next true

data/lib/zaniah/input/dispatcher.rb

@@ -2,6 +2,8 @@
 
 module Zaniah
   module Input
+    Hit = Data.define(:bounds, :owner)
+
     class Dispatcher
       attr_reader :focused
 
@@ -26,10 +28,11 @@ module Zaniah
       end
 
       def clear_hits = @hits.clear
+      def hits = @hits.map { |bounds, _, owner| Hit.new(bounds, owner) }.freeze
 
-      def hit(bounds, clip: nil, &handler)
+      def hit(bounds, clip: nil, owner: nil, &handler)
         bounds = bounds.intersect(@clip) if @clip
-        @hits << [clip ? bounds.intersect(clip) : bounds, handler]
+        @hits << [clip ? bounds.intersect(clip) : bounds, handler, owner]
       end
 
       def clip(bounds)
@@ -46,7 +49,7 @@ module Zaniah
           @capture = nil if event.is_a?(MouseUp)
           return true
         end
-        @hits.reverse_each do |bounds, handler|
+        @hits.reverse_each do |bounds, handler, _owner|
           next unless bounds.contains?(event.position)
           handled = handler.call(event)
           @capture = handler if handled == :capture && event.is_a?(MouseDown)

data/lib/zaniah/input/keymap.rb

@@ -7,8 +7,8 @@ require_relative "context_predicate"
 module Zaniah
   module Input
     class Keymap
-      def initialize(timeout: 1.0)
-        @bindings, @pending, @last_time, @timeout = [], [], 0, timeout
+      def initialize(timeout: 1.0, clock: MONOTONIC_CLOCK)
+        @bindings, @pending, @last_time, @timeout, @clock = [], [], 0, timeout, clock
       end
 
       def bind(keys, action, context: "")
@@ -23,7 +23,7 @@ module Zaniah
         self
       end
 
-      def dispatch(key, context: {}, now: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+      def dispatch(key, context: {}, now: @clock.call)
         @pending.clear if now - @last_time > @timeout
         @last_time = now
         key = Keystroke.normalize(key)

data/lib/zaniah/platform/headless/window.rb

@@ -3,13 +3,21 @@
 module Zaniah
   module Platform
     module Headless
+      Popup = Data.define(:labels, :enabled, :selected_index, :bounds)
+
       class Window
+        DEFAULT_CLEAR = "#181b20"
+
         attr_reader :content_size, :scene, :device, :dispatcher, :scale_factor, :text_runs
         attr_accessor :text_system, :ime_state, :title
 
-        def initialize(width: 800, height: 600, title: "Zaniah UI", scale_factor: 1)
+        def initialize(width: 800, height: 600, title: "Zaniah UI", scale_factor: 1,
+                       keymap: nil, clock: MONOTONIC_CLOCK)
           @content_size, @scale_factor, @title = Size.new(width, height), scale_factor, title
-          @scene, @device, @dispatcher = Scene.new, GPU::Software.new(width, height), Input::Dispatcher.new
+          @scene = Scene.new
+          @device = GPU::Software.new(width, height)
+          @dispatcher = Input::Dispatcher.new(keymap: keymap || Input::Keymap.new(clock: clock))
+          @clock = clock
           @state, @used_state, @text_runs = {}, {}, []
           @dirty, @closed = true, false
         end
@@ -19,12 +27,21 @@ module Zaniah
         def on_close(&block) = @on_close = block
         def on_moved(&block) = @on_moved = block
         def on_tick(&block) = @on_tick = block
+        def on_frame(&block) = @on_frame = block
         def draw(&block) = @draw = block
         def request_frame = @dirty = true
         def dirty? = @dirty
         def closed? = @closed
         def displays = [Display.new(0, "Headless", Bounds.new(0, 0, @content_size.width, @content_size.height), @scale_factor, true)]
 
+        def popup
+          return unless @menu
+
+          Popup.new(labels: @menu[:items].map { |label, _| label.dup.freeze }.freeze,
+                    enabled: @menu[:items].map { |_, callback| !callback.nil? }.freeze,
+                    selected_index: @menu[:index], bounds: popup_bounds(@menu))
+        end
+
         def resize(width, height)
           @content_size = Size.new(width, height)
           @device.resize(width, height)
@@ -49,7 +66,7 @@ module Zaniah
         def offer_tooltip(text, position:, delay: 0.5)
           @tooltip_offered = true
           return if @tooltip && @tooltip[:text] == text
-          @tooltip = {text: text.to_s, position: position, at: Process.clock_gettime(Process::CLOCK_MONOTONIC) + delay, shown: false}
+          @tooltip = {text: text.to_s, position: position, at: @clock.call + delay, shown: false}
         end
 
         def context_menu(items, position: Point.new(0, 0))
@@ -70,7 +87,7 @@ module Zaniah
 
         def tick
           @on_tick&.call
-          if @tooltip && !@tooltip[:shown] && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @tooltip[:at]
+          if @tooltip && !@tooltip[:shown] && @clock.call >= @tooltip[:at]
             @tooltip[:shown] = true
             request_frame
           end
@@ -81,7 +98,7 @@ module Zaniah
           @device.render(result) if result.is_a?(Scene)
         end
 
-        def render(element, clear: "#181b20", present: true)
+        def render(element, clear: DEFAULT_CLEAR, present: true)
           @text_system.scale_factor = @scale_factor if @text_system.respond_to?(:scale_factor=)
           @scene.clear
           @text_runs.clear
@@ -95,6 +112,7 @@ module Zaniah
           element.paint(root.bounds, nil, nil, cx)
           paint_popups
           @state.delete_if { |key, _| !@used_state[key] }
+          @on_frame&.call(element, clear)
           @device.render(@scene, clear: clear) if present
           @text_system.end_frame if @text_system.respond_to?(:end_frame)
         end

data/lib/zaniah/task_executor.rb

@@ -7,9 +7,10 @@ module Zaniah
   class TaskExecutor
     def self.current = Thread.current[:zaniah_executor]
 
-    def initialize(workers: 2)
+    def initialize(workers: 2, clock: MONOTONIC_CLOCK)
       @jobs, @foreground = Queue.new, Queue.new
       @wake, @condition = Mutex.new, ConditionVariable.new
+      @clock = clock
       @timers = []
       @threads = Array.new(workers) do
         Thread.new do
@@ -63,7 +64,7 @@ module Zaniah
       cancellation = owner.on_complete { post { subscription.detach; @timers.delete(deadline) if deadline } }
       if timeout
         raise ArgumentError, "timeout must be nonnegative" unless timeout.is_a?(Numeric) && timeout >= 0
-        deadline = [Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout, -> { finish.call(Task::Timeout.new("task timed out")) }]
+        deadline = [@clock.call + timeout, -> { finish.call(Task::Timeout.new("task timed out")) }]
         @timers << deadline
       end
       Fiber.yield
@@ -81,7 +82,7 @@ module Zaniah
     end
 
     def drain
-      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      now = @clock.call
       due, @timers = @timers.partition { |deadline, _| deadline <= now }
       due.each { |_, callback| callback.call }
       loop { @foreground.pop(true).call }
@@ -91,7 +92,7 @@ module Zaniah
 
     def wait(seconds)
       deadline = @timers.map(&:first).min
-      seconds = [seconds, [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max].min if deadline
+      seconds = [seconds, [deadline - @clock.call, 0].max].min if deadline
       @wake.synchronize { @condition.wait(@wake, seconds) if @foreground.empty? }
     end
 

data/lib/zaniah/text.rb

@@ -2,16 +2,20 @@
 
 module Zaniah
   class Text < Element
+    attr_reader :text, :font_size
+
     def initialize(text, size: 14, color: "#ddd", font: nil)
       super()
       @text, @font_size, @color, @font = text, size, color, font
     end
 
     def measured(&block) = (@measure = block; self)
+    def text_color = @color
 
     def request_layout(cx)
       @line = cx.text_system&.layout_line(@text, font: @font, size: @font_size)
-      measurement = @measure || ->(_width, _height) { [@line ? @line.width : @text.length * @font_size * 0.6, @font_size * 1.4, @font_size] }
+      line_height = @line ? @line.ascent + @line.descent : 0
+      measurement = @measure || ->(_width, _height) { [@line ? @line.width : @text.length * @font_size * 0.6, [@font_size * 1.4, line_height].max, @font_size] }
       @layout_node = Layout::Node.new(style: @style, measure: measurement)
     end
 

data/lib/zaniah/version.rb

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

data/lib/zaniah.rb

@@ -6,6 +6,8 @@ require_relative "zaniah/error"
 require_relative "zaniah/configuration"
 
 module Zaniah
+  MONOTONIC_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
   def self.configuration
     @configuration ||= Configuration.new(font_raster: :native, shaper: :native,
                                         font_db: :native, segmenter: :native)

data/sig/app.rbs

@@ -30,7 +30,7 @@ module Zaniah
   class App
     attr_reader windows: Array[Platform::Headless::Window]
     attr_reader executor: TaskExecutor
-    def initialize: () -> void
+    def initialize: (?clock: clock) -> 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
@@ -43,7 +43,7 @@ module Zaniah
     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 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, ?keymap: Input::Keymap?, ?clock: clock) ?{ (Platform::Headless::Window) -> (Element | Scene | nil) } -> Platform::Headless::Window
     def run: () -> void
   end
 
@@ -62,7 +62,7 @@ module Zaniah
   end
   class TaskExecutor
     def self.current: () -> TaskExecutor?
-    def initialize: (?workers: Integer) -> void
+    def initialize: (?workers: Integer, ?clock: clock) -> void
     def background: [T] () { () -> T } -> Task[T]
     def spawn: [T] () { () -> T } -> Task[T]
     def await: [T] (Task[T] task, ?timeout: Numeric?) -> T

data/sig/elements.rbs

@@ -18,6 +18,9 @@ module Zaniah
                 | (Array[Element?] elements) -> self
     def style: (**Layout::style_value properties) -> self
     def key: (Object value) -> self
+    def test_id: () -> String?
+               | (String value) -> self
+    def handlers: () -> Array[Symbol]
     def with_state: [T] () { () -> T } -> self
     def bg: (color color) -> self
     def border_color: (color color) -> self
@@ -57,6 +60,9 @@ module Zaniah
   class Div < Element
   end
   class Text < Element
+    attr_reader text: String
+    attr_reader font_size: Numeric
+    attr_reader text_color: color
     def initialize: (String text, ?size: Numeric, ?color: color, ?font: TextSystem::_Font?) -> void
     def measured: () { (Numeric width, Numeric height) -> Layout::measurement } -> self
   end

data/sig/input.rbs

@@ -7,6 +7,13 @@ module Zaniah
     type event = KeyDown | KeyUp | TextInput | Composition | mouse_event | FileDrop
     type mouse_event = MouseDown | MouseUp | MouseMove | ScrollWheel
 
+    class Hit < Data
+      attr_reader bounds: Bounds
+      attr_reader owner: Element?
+      def self.new: (Bounds bounds, Element? owner) -> Hit
+                  | (bounds: Bounds, owner: Element?) -> Hit
+    end
+
     class KeyDown < Data
       attr_reader keystroke: String
       attr_reader is_held: bool
@@ -79,7 +86,7 @@ module Zaniah
         def self.new: (Array[String] keys, ContextPredicate predicate, action action) -> Binding
                     | (keys: Array[String], predicate: ContextPredicate, action: action) -> Binding
       end
-      def initialize: (?timeout: Numeric) -> void
+      def initialize: (?timeout: Numeric, ?clock: clock) -> void
       def bind: (String keys, action action, ?context: String) -> self
       def load_json: (String text) -> self
       def dispatch: (String key, ?context: context, ?now: Numeric) -> (action | :pending | nil)
@@ -100,7 +107,8 @@ module Zaniah
       def focus: (FocusHandle? handle) -> void
       def key: (String key) -> (action | :pending | nil)
       def clear_hits: () -> void
-      def hit: (Bounds bounds, ?clip: Bounds?) { (mouse_event | FileDrop) -> (bool | :capture | nil) } -> void
+      def hits: () -> Array[Hit]
+      def hit: (Bounds bounds, ?clip: Bounds?, ?owner: Element?) { (mouse_event | FileDrop) -> (bool | :capture | nil) } -> void
       def clip: [T] (Bounds bounds) { () -> T } -> T
       def mouse: (mouse_event | FileDrop event) -> bool
     end

data/sig/platform.rbs

@@ -15,11 +15,11 @@ module Zaniah
     end
     def self.displays: (?backend: backend | :auto, ?display_server: :auto | :x11 | :wayland) -> Array[Display]
 
-    def self.open_window: (?backend: :headless, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> Headless::Window
-                        | (backend: :tui, ?input: IO, ?output: IO, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> TUI::Window
-                        | (backend: :mac, ?gpu: :metal | :opengl | :gl, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> Mac::Window
-                        | (backend: :linux, ?display_server: :auto | :x11 | :wayland, ?gpu: :opengl | :gl, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> (Linux::Window | Linux::WaylandWindow)
-                        | (backend: :windows, ?gpu: :opengl | :gl, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> Windows::Window
+    def self.open_window: (?backend: :headless, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> Headless::Window
+                        | (backend: :tui, ?input: IO, ?output: IO, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> TUI::Window
+                        | (backend: :mac, ?gpu: :metal | :opengl | :gl, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> Mac::Window
+                        | (backend: :linux, ?display_server: :auto | :x11 | :wayland, ?gpu: :opengl | :gl, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> (Linux::Window | Linux::WaylandWindow)
+                        | (backend: :windows, ?gpu: :opengl | :gl, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> Windows::Window
 
     interface _Watcher
       def poll: (?timeout: Numeric) -> Array[FileEvent]
@@ -35,7 +35,16 @@ module Zaniah
     def self.watch: (String | Array[String] paths, ?latency: Numeric) -> _Watcher
 
     module Headless
+      class Popup < Data
+        attr_reader labels: Array[String]
+        attr_reader enabled: Array[bool]
+        attr_reader selected_index: Integer
+        attr_reader bounds: Bounds
+        def self.new: (Array[String] labels, Array[bool] enabled, Integer selected_index, Bounds bounds) -> Popup
+                    | (labels: Array[String], enabled: Array[bool], selected_index: Integer, bounds: Bounds) -> Popup
+      end
       class Window
+        DEFAULT_CLEAR: String
         attr_reader content_size: Size
         attr_reader scene: Scene
         attr_reader device: GPU::_Device
@@ -45,17 +54,19 @@ module Zaniah
         attr_accessor text_system: TextSystem::_System?
         attr_accessor ime_state: Bounds?
         attr_accessor title: String
-        def initialize: (?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> void
+        def initialize: (?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> void
         def on_input: () { (Input::event) -> void } -> void
         def on_resize: () { (Size) -> void } -> void
         def on_close: () { () -> (bool | nil) } -> void
         def on_moved: () { ([Numeric, Numeric]) -> void } -> void
         def on_tick: () { () -> void } -> void
+        def on_frame: () { (Element, color) -> void } -> void
         def draw: () { (Window) -> (Element | Scene | nil) } -> void
         def request_frame: () -> bool
         def dirty?: () -> bool
         def closed?: () -> bool
         def displays: () -> Array[Display]
+        def popup: () -> Popup?
         def resize: (Numeric width, Numeric height) -> void
         def input: (Input::event event) -> void
         def offer_tooltip: (String text, position: Point, ?delay: Numeric) -> void
@@ -75,7 +86,7 @@ module Zaniah
         def flush_escape: () -> bool
       end
       class Window < Headless::Window
-        def initialize: (?input: IO, ?output: IO, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric) -> void
+        def initialize: (?input: IO, ?output: IO, ?width: Numeric, ?height: Numeric, ?title: String, ?scale_factor: Numeric, ?keymap: Input::Keymap?, ?clock: clock) -> void
         def run: () -> void
         def feed_input: (String bytes) -> void
       end

data/sig/zaniah.rbs

@@ -1,6 +1,8 @@
 module Zaniah
   VERSION: String
+  MONOTONIC_CLOCK: clock
   type color = Color | String | [Numeric, Numeric, Numeric] | [Numeric, Numeric, Numeric, Numeric]
+  type clock = ^() -> Numeric
   type dimension = Numeric | Length | :auto
   type radius = Numeric | [Numeric, Numeric, Numeric, Numeric]
   type menu = Array[[String, (^( ) -> void)?]]

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zaniah
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - ydah
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: alhena
@@ -51,6 +52,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.2'
+description:
 email:
 - t.yudai92@gmail.com
 executables: []
@@ -62,6 +64,7 @@ files:
 - README.md
 - assets/fonts/Abel-Regular.ttf
 - assets/fonts/OFL.txt
+- assets/logo.png
 - docs/adr/000-template.md
 - docs/adr/001-native-gpu-backends.md
 - docs/adr/002-objective-c-aggregates.md
@@ -229,6 +232,7 @@ metadata:
   changelog_uri: https://github.com/noxdea/zaniah/blob/main/CHANGELOG.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -243,7 +247,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: A pure Ruby UI framework with native and headless rendering
 test_files: []