zaniah 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83f0e9d7ba2790764f55bc1e0eda5e21e31b22a54cd0a92668b24df9000d351c
+  data.tar.gz: 37a96934f06671e69989c1e2e91e30917e0b6902458a09fc05fd5ef3999030f3
+SHA512:
+  metadata.gz: 3feda2d8ba35caa3b73821eb9cae80c64d8b549e87c125dd6f55c4382d9789451bd91e0ae2e019709e1f923b662b498265085c6c0fcd268dad3a94ce7ab6c4c3
+  data.tar.gz: ef1e4f76251e22c1a8317677cccc3b80885aec8f3bb917d09df7a363a9dbfb6976ed19e38565a75eb5bf656b2a2f3276daada27156d79eb250d6e734ff1ad62b

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 — 2026-09-11
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+# Zaniah
+
+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.
+
+The name comes from the white ground laid before paint or gold leaf: this
+toolkit is the drawing surface beneath the editor.
+
+## Try it locally
+
+```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.
+
+```ruby
+require "zaniah"
+
+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")
+    .child(Zaniah::Text.new("Hello, Ruby", size: 24))
+    .child(Zaniah::Text.new("A native toolkit, written in Ruby."))
+end
+window.tick
+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.
+
+## Toolkit and platforms
+
+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.
+
+## Development
+
+```sh
+bundle exec rake test
+ruby --yjit bench/instances.rb
+ruby --yjit bench/list.rb
+```
+
+`BUDGET=1` enables benchmark assertions.
+
+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).
+
+## License
+
+MIT; see [LICENSE.txt](LICENSE.txt). Included font notices remain alongside the
+font files.

data/assets/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright (c) 2011, Matthew Desmond (http://www.madtype.com | mattdesmond@gmail.com),with Reserved Font Name Abel.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

data/docs/adr/000-template.md

@@ -0,0 +1,24 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its compatibility, data,
+runtime, or component constraints. Operational workflow and release policy do
+not belong in this directory; see [the scope](README.md).
+
+Name the credible alternatives. If there was no meaningful alternative, record
+the behavior in reference documentation instead of creating an ADR.
+
+## Decision
+
+Describe the durable boundary or architecture choice. Leave command syntax,
+field-by-field formats, test evidence, benchmark results, and migration steps
+in their authoritative documents.
+
+## Consequences
+
+Describe the important positive and negative trade-offs, including what would
+make this decision worth revisiting.

data/docs/adr/001-native-gpu-backends.md

@@ -0,0 +1,36 @@
+# ADR 001: Use Metal on macOS and OpenGL on Linux and Windows
+
+- Status: Accepted
+- Date: 2026-09-10
+
+## Context
+
+Native windows need GPU rendering while keeping the gem free of compiled
+extensions. Rendering must preserve scene order, clipping, and alpha blending,
+and Ruby callbacks must not enter the VM from unsupported operating-system
+threads.
+
+The credible alternatives were one OpenGL backend for every desktop, native
+Metal on macOS with OpenGL elsewhere, software rendering only, or a compiled
+bridge that could safely receive display-link callbacks.
+
+## Decision
+
+macOS defaults to a `CAMetalLayer` and runtime-compiled Metal shaders, with
+OpenGL as an explicit alternative. Linux uses OpenGL through GLX or EGL, and
+Windows uses OpenGL through WGL. Headless rendering remains a separate software
+backend.
+
+Compatible adjacent scene commands are batched without reordering them. The Ruby
+main thread polls native events and presents synchronized frames; native display
+threads do not call Ruby through Fiddle.
+
+## Consequences
+
+Applications get native GPU windows without compiling repository code, and each
+platform can use a supported presentation path. The project must maintain both
+Metal and OpenGL renderers and test native behavior on each target platform.
+
+Revisit this decision if a compiled bridge becomes acceptable, Ruby gains a safe
+foreign-thread callback boundary, or maintaining parallel rendering APIs costs
+more than the platform-specific benefits.

data/docs/adr/002-objective-c-aggregates.md

@@ -0,0 +1,34 @@
+# ADR 002: Describe Objective-C aggregate values with system libffi
+
+- Status: Accepted
+- Date: 2026-09-10
+
+## Context
+
+AppKit and related frameworks pass values such as `NSRect` and `NSRange` by
+value. Fiddle function signatures expose scalar types but cannot describe these
+aggregate arguments and return values accurately. Their calling conventions also
+differ between arm64 and x86_64.
+
+The credible alternatives were treating aggregates as pointers, writing a C
+extension or generated trampoline for each signature, or describing the native
+ABI through the system libffi library already used by Fiddle.
+
+## Decision
+
+`FFI::Struct::Signature` describes aggregate layouts to system libffi and invokes
+them with `ffi_call`. The same mechanism creates closures with aggregate
+arguments and returns. Objective-C dispatch signatures are cached; arm64 uses
+its native aggregate ABI, while x86_64 uses `objc_msgSend_stret` where required.
+
+Native pointers and Ruby closures have explicit owners, and callbacks are retained
+for as long as native code may invoke them.
+
+## Consequences
+
+Aggregate calls follow each platform ABI without a compiler or C extension. The
+trade-off is a small internal FFI layer that must model architecture-specific
+dispatch and object lifetimes correctly.
+
+Revisit this decision if Fiddle gains complete aggregate signatures or if the
+project adopts a compiled native boundary for other reasons.

data/docs/adr/003-fiddle-call-boundary.md

@@ -0,0 +1,33 @@
+# ADR 003: Batch frame work across the Fiddle boundary
+
+- Status: Accepted
+- Date: 2026-09-10
+
+## Context
+
+Crossing from Ruby into native functions has fixed conversion and dispatch cost.
+A renderer that makes one native call per primitive scales that cost with scene
+size. Objective-C calls may also reenter Ruby on the current thread, while
+terminal reads may block for an unbounded period.
+
+The credible alternatives were per-primitive native calls, cached wrappers with
+batched frame data, or moving frame encoding into a compiled extension.
+
+## Decision
+
+Native function wrappers are cached by their full signature. Compatible adjacent
+GPU commands are packed into instance buffers and submitted in batches rather
+than one primitive at a time.
+
+Objective-C dispatch keeps the GVL because callbacks may reenter Ruby. Blocking
+ConPTY reads release it so other Ruby threads can continue.
+
+## Consequences
+
+Native-call overhead depends primarily on batch boundaries instead of primitive
+count, while draw order and clipping remain explicit. Batching adds packing code,
+and material, texture, or clip changes still split batches.
+
+Revisit this decision if profiling shows boundary calls are no longer material,
+batch construction dominates frame time, or a compiled renderer becomes an
+accepted dependency.

data/docs/adr/README.md

@@ -0,0 +1,10 @@
+# Architecture Decision Records
+
+This directory records durable implementation choices that affect component or
+runtime boundaries and had credible alternatives. API reference, command syntax,
+field formats, test evidence, benchmark results, migrations, release policy, and
+operational workflow belong in their authoritative documentation instead.
+
+Copy [ADR 000](000-template.md) when recording a decision. Decision records use
+three-digit numbers starting at `001`, assigned without gaps. Keep accepted,
+rejected, and superseded records so later entries do not need renumbering.

data/docs/native.md

@@ -0,0 +1,66 @@
+# Native backends
+
+Zaniah provides native windows on macOS, Linux, and Windows. Headless and
+terminal backends are available when a graphical window is unnecessary.
+
+```ruby
+window = Zaniah::Platform.open_window(
+  backend: :mac,
+  gpu: :metal,
+  width: 800,
+  height: 600,
+  title: "Zaniah"
+)
+
+window.on_input { |event| p event }
+window.draw { Zaniah::Div.new.bg("#123") }
+window.run
+```
+
+| Backend | Renderer | Notes |
+| --- | --- | --- |
+| `:mac` | Metal (default) or OpenGL | Requires a graphical macOS session |
+| `:linux` | Wayland/EGL or X11/GLX | Selected from `WAYLAND_DISPLAY` and `DISPLAY` |
+| `:windows` | Win32/WGL | Requires 64-bit Ruby and Windows 10 APIs |
+| `:headless` | Ruby software renderer | Deterministic rendering and PNG output |
+| `:tui` | ANSI terminal | Text-grid rendering and terminal input |
+
+On Linux, pass `display_server: :wayland` or `:x11` to require one display
+server. On macOS, pass `gpu: :opengl` to use OpenGL instead of Metal.
+
+Native backends require Ruby's Fiddle library and the platform graphics
+libraries. Fiddle is not a default gem on Ruby 4, so applications using native
+windows must install it. Linux file dialogs and URL opening use `zenity` and
+`xdg-open` when available.
+
+Native windows support input and IME events, resizing, display scale, clipboard,
+file drops, fullscreen, cursors, URL opening, file dialogs, appearance changes,
+and PNG capture. Platform availability differs; see [the RBS declarations](../sig/native.rbs)
+and [platform declarations](../sig/platform.rbs) for the exact API.
+
+## Displays, file watching, and terminals
+
+`Zaniah::Platform.displays` returns the available displays for a backend.
+`Zaniah::Platform.watch(paths, latency:)` creates a native filesystem watcher;
+call `poll(timeout:)` for events and `close` when finished. Overflow events mean
+the application should rescan the watched paths.
+
+On Windows, require `zaniah/platform/windows/terminal` to use
+`Zaniah::Platform::Windows::Terminal`, which wraps ConPTY. It supports starting
+a child process, nonblocking reads, writes, resizing, liveness checks, and
+explicit cleanup. ConPTY requires Windows 10 version 1809 or later.
+
+## Development checks
+
+Run checks on the matching host and display server:
+
+```sh
+ruby examples/native_smoke.rb --check /tmp/zaniah.png
+ruby examples/native_smoke.rb --gl --check /tmp/zaniah-gl.png
+ruby examples/linux_smoke.rb
+ruby examples/linux_smoke.rb --wayland
+ruby examples/native_watch.rb
+```
+
+Native input, IME, dialogs, and terminal integration also require manual checks
+on the target operating system.

data/docs/process_pool.md

@@ -0,0 +1,67 @@
+# CPU process workers
+
+`ProcessPool` runs trusted CPU work in reusable Ruby child processes. For
+portable spawning, put the handler in a loadable file and expose `.call(data)`:
+
+```ruby
+# /absolute/path/word_count.rb
+module WordCount
+  def self.call(data)
+    {"words" => data.fetch("text").split.length}
+  end
+end
+```
+
+```ruby
+require "zaniah"
+require "zaniah/process_pool"
+
+pool = Zaniah::ProcessPool.new(
+  workers: 2,
+  handler: "WordCount",
+  requires: [File.expand_path("word_count.rb")],
+  max_pending: 4
+)
+
+task = pool.submit("text" => "Hello Ruby")
+result = task.await(timeout: 2)
+pool.shutdown
+```
+
+`requires:` accepts existing absolute Ruby filenames and `load_paths:` accepts
+absolute directories. Workers start lazily, may keep process-local caches, and
+do not guarantee that related requests use the same process. Failed workers are
+replaced; lost work is not replayed.
+
+## Data and limits
+
+Arguments and results must be plain JSON values: nil, booleans, integers, finite
+floats, valid UTF-8 strings, arrays, and string-keyed hashes. Values are copied
+at submission and received values are frozen. Custom objects, symbols, cycles,
+excessive nesting, and invalid strings are rejected.
+
+The default message limit is 16 MiB. `workers:` accepts 1–32 and `max_pending:`
+defaults to twice the worker count. Submitting to a full or shut-down pool raises
+`Zaniah::Error` immediately. Handlers are application code: the pool is not a
+sandbox for untrusted Ruby.
+
+## Cancellation and cleanup
+
+`Task#cancel` cancels queued work or terminates the child running that task. An
+`await` timeout does not cancel work, so call `cancel` when abandoning a task.
+Cancellation cannot undo external side effects already performed by a handler.
+
+`shutdown(timeout: 2)` rejects new submissions, cancels outstanding tasks, and
+cleans up workers. It is idempotent. If cleanup misses the deadline it raises
+`Task::Timeout`, and shutdown may be retried.
+
+The block form remains available on platforms with `fork`, but named handlers
+are preferred for portability and for applications that own threads or native
+resources. Both forms use the same JSON-only data contract.
+
+See [the RBS declarations](../sig/app.rbs) for the complete API. Run the worker
+tests with:
+
+```sh
+ruby -Itest test/process_pool_test.rb
+```

data/docs/text.md

@@ -0,0 +1,90 @@
+# Text system
+
+`TextSystem::Renderer` provides layout, glyph rasterization, atlas management, and
+painting. `TextSystem::Typesetter` provides layout and caret measurements without
+allocating glyph textures.
+
+```ruby
+db = Zaniah::TextSystem::FontDB.new
+font = db.find(family: "Menlo", weight: 700, width: 5, style: :normal)
+system = Zaniah::TextSystem::Renderer.new(font: font, font_db: db)
+window.text_system = system
+```
+
+`FontDB` discovers TTF, OTF, TTC, and OTC fonts in platform directories. It
+selects faces by family, weight (`1..1000`), width (`1..9`), and style
+(`:normal`, `:italic`, or `:oblique`). A bundled Abel font is the final fallback.
+Call `refresh` to clear cached discovery results.
+
+## Providers and shaping
+
+Defaults can be configured globally or supplied to a constructor:
+
+```ruby
+Zaniah.configure do |config|
+  config.font_db = :native
+  config.shaper = :native
+  config.segmenter = :native
+  config.font_raster = :native
+end
+```
+
+Provider objects may be supplied instead of symbols:
+
+| Setting | Required method | Result |
+| --- | --- | --- |
+| `font_db` | `find(...)`, `fallback(codepoint, primary_font)` | A font compatible with Alhena |
+| `shaper` | `shape(glyphs, size:, text:)` | `Array[TextSystem::Glyph]` with UTF-8 byte clusters |
+| `segmenter` | `grapheme_clusters(text)` | Strings that exactly partition the input |
+| `font_raster` | `rasterize(font, glyph_id, size:, subpixel_x:)` | A glyph bitmap |
+
+Providers may implement `close`; the text system closes them when it closes.
+Custom mutable providers used by `fork` must also implement `layout_copy` and
+return an independent provider.
+
+The default Ruby shaper supports horizontal Latin, CJK, and kana text, including
+common OpenType ligatures, contextual substitutions, pair positioning, and
+legacy kerning. It is not a replacement for full complex-script shaping:
+Arabic/Indic reordering, AAT `morx`, vertical text, complete mark positioning,
+and variation-index positioning are unsupported.
+
+Built-in rasterizers are `:native`/`:alhena`, `:freetype`, and `:coretext`
+(`:core_text` is an alias). FreeType and CoreText require their platform library.
+Unimplemented symbolic adapters raise `ArgumentError`; pass a provider object to
+integrate another shaper, segmenter, font database, or rasterizer.
+
+## Background layout and startup cache
+
+Create an independent layout-only typesetter for background work:
+
+```ruby
+typesetter = system.fork(capacity: 32)
+# use typesetter on one background worker
+typesetter.close
+```
+
+Do not mutate one text system or atlas concurrently. Font bytes may be shared,
+but mutable providers and caches must be copied.
+
+Disk-backed atlas caching is opt-in. Prewarm only after the window scale is known:
+
+```ruby
+system = Zaniah::TextSystem::Renderer.new(cache_dir: "/path/to/app-cache/glyphs")
+system.scale_factor = window.scale_factor
+system.prewarm(size: 14)
+window.text_system = system
+```
+
+A missing, corrupt, or read-only cache does not prevent rendering. Applications
+own cache-directory retention. See [the RBS declarations](../sig/text.rbs) for
+the complete API.
+
+## Development checks
+
+```sh
+BUDGET=1 ruby --yjit bench/text_frame.rb
+ruby --yjit bench/atlas_startup.rb
+ruby --yjit -Ilib script/shaper_oracle assets/fonts/Abel-Regular.ttf /path/to/font.ttf
+```
+
+The shaping oracle is optional and requires `hb-shape`; it is not used at runtime.

data/docs/vector_and_list.md

@@ -0,0 +1,52 @@
+# Vector icons and variable-height lists
+
+`SVG` and `List` are normal elements and participate in layout, clipping, hit
+testing, and scene painting.
+
+## Static SVG icons
+
+```ruby
+icon = Zaniah::SVG.open("assets/search.svg", color: "#d8e4f0").w(24).h(24)
+icon = Zaniah::SVG.parse(
+  '<svg viewBox="0 0 24 24"><path d="M4 12H20" stroke="currentColor"/></svg>'
+)
+```
+
+The renderer supports SVG paths, basic shapes, groups, transforms, view boxes,
+inherited fill and stroke, `currentColor`, opacity, local `defs`/`use`, and
+user-space clip paths. It is intended for static icons, not arbitrary web SVG.
+
+Scripts, external references, CSS stylesheets, gradients, filters, masks, images,
+text, markers, dash arrays, nested viewports, and object-bounding-box clips are
+unsupported and raise `ArgumentError`. Input is bounded to 2 MiB, 10,000 XML
+nodes, 64 levels, and 100,000 path operations; each output texture is limited to
+one megapixel.
+
+## Variable-height lists
+
+```ruby
+rows = Zaniah::List.new(count: 1_000_000, estimated_height: 24, overscan: 2) do |index|
+  Zaniah::Div.new
+    .h(index.even? ? 20 : 28)
+    .child(Zaniah::Text.new("Row #{index}"))
+end.w(600).h(400)
+
+rows.scroll_to(500_000, align: :center)
+```
+
+Give the list a viewport height. Only visible rows and the overscan margin are
+instantiated; other rows retain estimated heights until measured. Persistent row
+state belongs in keyed window state or the application model.
+
+`scroll_y=` changes the pixel offset. `scroll_to(index, align:)` accepts `:start`,
+`:center`, `:end`, and `:nearest`. `update_height` supplies a measurement before
+rendering, `visible_range` returns the instantiated exclusive-end range, and
+`total_height` includes estimates. A list's item count is fixed; create a new
+list when the count changes.
+
+See [the element declarations](../sig/elements.rbs) for the complete API. Run:
+
+```sh
+ruby -Ilib -Itest test/svg_and_list_test.rb
+ruby --yjit -Ilib bench/list.rb
+```

data/examples/ffi_bench.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "benchmark"
+
+library = Fiddle.dlopen(RUBY_PLATFORM.match?(/mingw|mswin/) ? "msvcrt.dll" : nil)
+count = Integer(ENV.fetch("N", "1000000"))
+text = "a" * 16
+pointer = Fiddle::Pointer[text]
+[true, false].each do |gvl|
+  function = Fiddle::Function.new(library["strlen"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_SIZE_T, need_gvl: gvl)
+  [text, pointer].each do |value|
+    elapsed = Benchmark.realtime { count.times { function.call(value) } }
+    puts "strlen gvl=#{gvl} #{value.class}: #{(elapsed * 1e6 / count).round(3)}us/call"
+  end
+end