zaniah 0.11.0 → 0.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a6d77e1edea911ee42064986e375f163213f45bedaeda9c6f3e409b42914cbd
-  data.tar.gz: 21970a583f79a01502abf982811820361a7628dc0ffffca0a2f308fa4852a6b7
+  metadata.gz: 2880a0bf76786c774939df0c5d8c02cc287789607221c6a1739d71b50fcc2248
+  data.tar.gz: f2ccf99f464295d8e7af77e61a0b38911f133728b979f868b4ede8ce2f4a5fdd
 SHA512:
-  metadata.gz: 83d536f11608784994079181c05524fb3935cddf6076728967b78fc54b48ae91889c387efc047159f767dac8743ae5cb89f7c3497f75afa7b733133f6bc7e982
-  data.tar.gz: caa3b692cbe5435abc9571b0ccc3a09dc46db71c022a0ab2f80903dab7336c3818c3ae05ecc3ee6a0aa8ba657fb45bfa61a5218ec236546f229ba9d80614ace2
+  metadata.gz: e1a950ab9299a1a0121469d98310c945b7dbefb611b87f286c28d769fbbcdb3d14fb3cc20d12c135b5620071cbcc1ac75dc3ac083bc4c6c4978558d1fd75fb36
+  data.tar.gz: d31dd8cd5722a4bccccdc73f54e0cff07770d1094fe67a5d3ef000f097b950228f8b6a9f9ac05b0adc380d61a393c82ef24b66ff3810ffda3b8fdd8e3a904c8c

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.12.1 — 2026-10-02
+
+- Prevent obsolete focus controls from accumulating across redraws, reducing memory use and keeping keyboard navigation on current controls.
+
+## 0.12.0 — 2026-10-02
+
+- Add streaming virtual tables with lazy cells, stable selection, row styling, configurable columns, and tail following.
+- Add virtual hexadecimal and ASCII byte views with linked selection, highlights, keyboard navigation, and copying.
+- Preserve scrolling and height measurements when virtual list counts change, with optional bottom following.
+- Avoid stale rows and duplicated drawing when scrolling keyed virtual lists.
+- Reduce layout work for fixed-size containers and reuse unchanged visible byte rows for faster redraws.
+- Speed up vector recording by reusing resolved paint colors.
+- Add text-field validation states and token completion with keyboard selection and Unicode-safe replacement.
+- Add programmatic tree selection and item context menus.
+- Add suggested filenames, starting directories, and extension filters for native file dialogs.
+- Fix inspection snapshots for nested UI components, including select controls in dialogs.
+- Preserve accessible content and actions inside wrapped split panes.
+
 ## 0.11.0 — 2026-09-25
 
 - Add segmented controls, alerts, hover cards, calendar and date-range inputs.

data/README.md

@@ -114,7 +114,7 @@ For an interactive window, choose `backend: :mac`, `:linux`, `:windows`, or
 | `:tui` | ANSI terminal | Text-grid rendering and terminal input |
 
 Native backends use the operating system libraries through Ruby's Fiddle. See
-[Native backends](docs/native.md) for platform requirements and checks.
+[Native backends](https://noxdea.github.io/zaniah/docs/guides/native.html) for platform requirements.
 
 Native macOS, Windows, and X11 windows can be moved to a display returned by
 `Zaniah::Platform.displays` with `window.move_to_display(display)`. Headless and
@@ -124,37 +124,18 @@ compositor to fullscreen on that output, but the compositor may choose otherwise
 
 ## Documentation
 
-- [Native backends](docs/native.md) — windows, displays, file watching, and terminals
-- [Text system](docs/text.md) — font discovery, shaping, rasterization, and caching
-- [Images](docs/images.md) — PNG, GIF, baseline JPEG, and orientation support
-- [SVG and lists](docs/vector_and_list.md) — static vector icons and virtual lists
-- [Drag-and-drop reordering](docs/drag_drop.md) — stable IDs, virtual targets, and keyboard access
-- [Layout and scrolling](docs/layout.md) — Grid, resizable pane grids, scrolling, sticky positioning, and RTL foundations
-- [Themes](docs/theme.md) — semantic tokens and state styles
-- [Components](docs/components.md) — controls, overlays, data views, charts, and forms
-- [Animation](docs/animation.md) — easing, springs, transitions, and reduced motion
-- [Accessibility](docs/accessibility.md) — semantic trees, diffs, and native bridges
-- [Terminal UI](docs/tui.md) — deterministic component degradation
-- [CPU process workers](docs/process_pool.md) — portable background CPU work
-- [Declarative elements](docs/describe.md) — validated vocabularies, event routing, diffs, and surfaces
-- [Architecture decisions](docs/adr) — design records and rationale
+- [Getting started](https://noxdea.github.io/zaniah/docs/) — installation and your first render
+- [Guides](https://noxdea.github.io/zaniah/docs/guides/) — platforms, layout, text, themes, accessibility, and advanced APIs
+- [Components](https://noxdea.github.io/zaniah/docs/components/) — rendered examples, code, and API summaries
+- [Component API reference](https://noxdea.github.io/zaniah/docs/guides/component-reference.html) — all constructors and variants in one table
+- [Contributing guidelines](.github/CONTRIBUTING.md) — development and platform checks
+- [Architecture decisions](docs/adr) — implementation rationale
 - [RBS declarations](sig) — public API signatures
 
-## Development
-
-```sh
-bundle install
-bundle exec rake test
-bundle exec rake bench
-gem build --strict zaniah.gemspec
-```
-
-Set `BUDGET=1` to enable benchmark assertions.
-
 ## Contributing
 
-Bug reports and pull requests are welcome at
-[github.com/noxdea/zaniah](https://github.com/noxdea/zaniah).
+Bug reports and pull requests are welcome. See the
+[contributing guidelines](.github/CONTRIBUTING.md) for checks and documentation updates.
 
 ## License
 

data/assets/fonts/NotoSans-LICENSE.txt

@@ -0,0 +1,94 @@
+Copyright 2018 The Noto Project Authors (github.com/googlei18n/noto-fonts)
+
+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/_templates/page.erb

@@ -0,0 +1,123 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="<%= h(page.fetch("lead")) %>">
+  <meta name="theme-color" content="#0b1220">
+  <link rel="canonical" href="https://noxdea.github.io/zaniah/docs/<%= path == "index.html" ? "" : path %>">
+  <link rel="stylesheet" href="<%= link_from(path, "site.css") %>">
+  <title><%= h(page.fetch("title")) %> · Zaniah Docs</title>
+</head>
+<body>
+  <a class="skip-link" href="#content">Skip to content</a>
+  <header class="site-header">
+    <div class="header-inner">
+      <a class="brand" href="<%= link_from(path, "index.html") %>" aria-label="Zaniah documentation home"><span class="brand-symbol" aria-hidden="true">Z</span><span>Zaniah <small>Docs</small></span></a>
+      <nav class="header-links" aria-label="Global navigation">
+        <a href="<%= link_from(path, "index.html") %>">Docs</a>
+        <a href="<%= link_from(path, "guides/index.html") %>">Guides</a>
+        <a href="<%= link_from(path, "components/index.html") %>">Components</a>
+        <a href="https://github.com/noxdea/zaniah">GitHub</a>
+      </nav>
+    </div>
+  </header>
+
+  <div class="docs-shell">
+    <aside class="sidebar" aria-label="Documentation navigation">
+      <% groups.each do |group, items| %>
+        <div class="nav-group"><h2><%= h(group) %></h2>
+          <% items.each do |item| %>
+            <a href="<%= link_from(path, item.fetch("path")) %>"<%= ' aria-current="page"' if item["path"] == path %>><%= h(item.fetch("title")) %></a>
+          <% end %>
+        </div>
+      <% end %>
+    </aside>
+
+    <main id="content" class="content">
+      <details class="mobile-nav"><summary>Browse documentation</summary><nav aria-label="Mobile documentation navigation">
+        <% groups.each do |group, items| %>
+          <strong><%= h(group) %></strong>
+          <% items.each do |item| %>
+            <a href="<%= link_from(path, item.fetch("path")) %>"<%= ' aria-current="page"' if item["path"] == path %>><%= h(item.fetch("title")) %></a>
+          <% end %>
+        <% end %>
+      </nav></details>
+      <div class="page-heading">
+        <p class="breadcrumb"><a href="<%= link_from(path, "index.html") %>">Docs</a><span aria-hidden="true">/</span><%= h(page.fetch("group")) %></p>
+        <h1><%= h(page.fetch("title")) %></h1>
+        <p class="lead"><%= inline(page.fetch("lead")) %></p>
+      </div>
+      <% if page["kind"] == "component" %>
+        <section class="doc-section" id="import"><h2>Import</h2>
+          <p>Load the optional component layer before using the examples below.</p>
+          <div class="code-example"><div class="code-label">Ruby</div><pre><code>require "zaniah/ui"</code></pre></div>
+        </section>
+      <% end %>
+
+      <% if page["kind"] == "index" %>
+        <% index_groups.each do |group| %>
+          <% items = groups.fetch(group) %>
+          <% items = items.reject { |item| item["kind"] == "index" } %>
+          <section class="doc-section" id="<%= h(group.downcase.gsub(/[^a-z0-9]+/, "-")) %>">
+            <h2><%= h(group) %></h2>
+            <div class="directory">
+              <% items.each do |item| %>
+                <a href="<%= link_from(path, item.fetch("path")) %>"><strong><%= h(item.fetch("title")) %></strong><span><%= h(item.fetch("lead")) %></span></a>
+              <% end %>
+            </div>
+          </section>
+        <% end %>
+      <% elsif page["kind"] == "markdown" %>
+        <article class="markdown"><%= guide_html %></article>
+      <% else %>
+        <% page.fetch("sections", []).each do |section| %>
+          <section class="doc-section" id="<%= section_id(section) %>">
+            <h2><%= h(section.fetch("heading")) %></h2>
+            <% Array(section["text"]).each do |paragraph| %><p><%= inline(paragraph) %></p><% end %>
+            <% if section["image"] %>
+              <% image_width, image_height = image_dimensions(section.fetch("image")) %>
+              <figure class="example"><div class="example-label">Rendered example</div><img src="<%= link_from(path, section.fetch("image")) %>" alt="<%= h(section.fetch("alt")) %>" width="<%= image_width %>" height="<%= image_height %>" loading="lazy"><figcaption>Rendered by Zaniah's headless backend.</figcaption></figure>
+            <% end %>
+            <% if section["code"] %>
+              <div class="code-example"><div class="code-label"><%= h(section.fetch("code_label", "Ruby")) %></div><pre><code><%= h(section.fetch("code")) %></code></pre></div>
+            <% end %>
+            <% if section["note"] %><p class="note"><%= inline(section.fetch("note")) %></p><% end %>
+          </section>
+        <% end %>
+        <% if page["kind"] == "component" %>
+          <section class="doc-section" id="api"><h2>API summary</h2><p>Constructor options and behaviors are drawn from the <a href="<%= link_from(path, "guides/component-reference.html") %>">component reference</a>.</p>
+            <div class="table-scroll"><table><thead><tr><th>Component</th><th>Constructor and methods</th><th>Variants or behavior</th></tr></thead><tbody>
+              <% rows.each do |row| %><tr><td><code><%= h(row[:names].join(", ")) %></code></td><td><%= inline(row[:constructor]) %></td><td><%= inline(row[:variants]) %></td></tr><% end %>
+            </tbody></table></div>
+          </section>
+          <section class="doc-section" id="accessibility"><h2>Accessibility</h2>
+            <% if page["a11y"] %><p><%= inline(page["a11y"]) %></p><% end %>
+            <div class="table-scroll"><table><thead><tr><th>Component</th><th>Semantic role</th></tr></thead><tbody>
+              <% rows.each do |row| %><tr><td><code><%= h(row[:names].join(", ")) %></code></td><td><%= h(row[:role]) %></td></tr><% end %>
+            </tbody></table></div>
+          </section>
+        <% end %>
+      <% end %>
+
+      <nav class="pagination" aria-label="Adjacent pages">
+        <% if previous_page %><a href="<%= link_from(path, previous_page.fetch("path")) %>"><small>Previous</small><strong><%= h(previous_page.fetch("title")) %></strong></a><% end %>
+        <% if next_page %><a href="<%= link_from(path, next_page.fetch("path")) %>"><small>Next</small><strong><%= h(next_page.fetch("title")) %></strong></a><% end %>
+      </nav>
+    </main>
+
+    <aside class="toc" aria-label="On this page"><p>On this page</p>
+      <% if page["kind"] == "index" %>
+        <% index_groups.each do |group| %><a href="#<%= h(group.downcase.gsub(/[^a-z0-9]+/, "-")) %>"><%= h(group) %></a><% end %>
+      <% elsif page["kind"] == "markdown" %>
+        <% guide_toc.each do |anchor, heading| %><a href="#<%= h(anchor) %>"><%= heading %></a><% end %>
+      <% else %>
+        <% if page["kind"] == "component" %><a href="#import">Import</a><% end %>
+        <% page.fetch("sections", []).each do |section| %><a href="#<%= section_id(section) %>"><%= h(section.fetch("heading")) %></a><% end %>
+        <% if page["kind"] == "component" %><a href="#api">API summary</a><a href="#accessibility">Accessibility</a><% end %>
+      <% end %>
+    </aside>
+  </div>
+  <footer class="site-footer"><span>Zaniah is open source under the MIT License.</span><a href="https://github.com/noxdea/zaniah">Source on GitHub</a></footer>
+</body>
+</html>

data/docs/components.md

@@ -21,10 +21,21 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 }
 ```
 
+`VirtualTable`, `HexView`, and `TreeView` accept `viewport_height=` when a window
+or split pane resizes. This updates their internal list viewport while retaining
+scroll state and selection. `VirtualTable#follow_tail=` toggles bottom following;
+call `scroll_to(source.count - 1, align: :end)` to resume immediately from elsewhere.
+
+`TreeView#on_context_menu { |item, cx| menu }` selects the item under a right
+click before opening the returned menu at the pointer. The callback receives the
+same item value as `on_select`.
+
 ## Component reference
 
 | Layer | Component | Main constructor/options | Variants | Accessibility role |
 | --- | --- | --- | --- | --- |
+| L4 | `VirtualTable` | `(source, columns:, height:, row_height:, selection:, follow_tail:)`; lazy `count`/`cell` source | stable row IDs, sortable/resizable headers, column visibility/order, row colors | table |
+| L4 | `HexView` | `(bytes, bytes_per_row:, group:, offset_digits:, height:)`; `highlights=`, `select`, `scroll_to_offset` | viewport rows; synchronized hex/ASCII selection and copying | group |
 | L0 | `Label` | `(text, tone:, size:, wrap:)` | tone: default/muted/inverse; size: xs–xl | text |
 | L0 | `Icon` | `(source, size:, color:, label:)` | bundled: check/close/search/menu/info/warning | image when labeled |
 | L0 | `Divider` | `(axis:)` | horizontal/vertical | separator |
@@ -56,7 +67,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L2 | `ContextMenu`, `Menu` | `(items, anchor:, open:)` | pointer + arrows/Home/End/Enter/Esc | menu/menuitem |
 | L2 | `MenuBar` | `(menus)` or `.from(app.menu_bar)` | declarative menu model or legacy pairs | menubar |
 | L2 | `Dropdown` | `(label, items:, value:)`; `on_change` | menu-backed | button |
-| L2 | `TextField` | `(value, placeholder:, label:, prefix:, suffix:, error:, max_length:, clearable:)` | IME, selection, counter | textbox |
+| L2 | `TextField` | `(value, placeholder:, label:, prefix:, suffix:, error:, max_length:, clearable:)`; `status(kind, message:)`, `completion(provider)` | IME, selection, counter, validation, token completion | textbox |
 | L2 | `TextArea` | TextField plus `rows:` | multiline/wrapped | textbox/multiline |
 | L2 | `SearchInput` | TextField options | search + clear icons | searchbox |
 | L2 | `PasswordInput` | TextField options | masked display | textbox |
@@ -93,7 +104,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L3 | `ListView` | `(items, height:, row_height:, selected:)`; `on_select` | virtual rows and keyboard selection | list/listitem |
 | L4 | `Table`, `DataGrid` | `(rows, columns:, height:, selection:, row_key:)`; `on_sort`, `on_select`, `on_edit`, `on_copy`, `on_paste` | virtual rows, sorting, resizing, editing, typed clipboard hooks | table/row/cell |
 | L4 | `Grid` | `(rows:, columns:, row_height:, column_width:, frozen_rows:, frozen_columns:)`; `scroll_to`, range `selection`, `on_select`, `on_edit`, `on_fill`, `on_resize`, `on_copy`, `on_paste` | two-axis virtualization, frozen panes, visible-cell resize/fill and typed clipboard hooks | table |
-| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
+| L4 | `TreeView` | `(items, height:, selected:)`; `select_id`, `on_context_menu`, `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
 | L4 | `PropertyGrid` | `(schema, values, height:, row_height:)`; `on_change`, `set` | typed existing controls, `Validation`, virtual rows | table/row/cell |
 | L5 | `Sparkline` | `(values, width:, height:, color:, label:)` | line + tooltip | image |
 | L5 | `LineChart`, `BarChart`, `StackedBarChart`, `AreaChart` | `(series, width:, height:, colors:, label:)`; `AreaChart(stacked:)` | shared axes, ticks, grid lines, color-keyed legend, tooltip | image |
@@ -199,6 +210,3 @@ resize. Grid and Table clipboard hooks receive half-open `Grid::Area` ranges;
 Table areas follow the current display order without changing its stable-ID
 selection. See [Layout](layout.md#two-axis-virtual-grid). Tree views use Up/Down to select, Right to expand or enter the first child,
 and Left to collapse or return to the parent.
-
-Run `bundle exec ruby tools/generate_component_gallery.rb` to rebuild the dark,
-light, and high-contrast component sheets plus overlay variants in all three themes.

data/docs/inspection.md

@@ -16,4 +16,6 @@ Zaniah::Inspection.perform(window, node, :press)
 
 The snapshot containers and copied collections are frozen. `entry.element` is deliberately a live element reference: use it only in the same frame, because the next render may replace it. Accessibility nodes are copied for inspection; pass one to `Inspection.perform` to invoke an action on its current source node. Actions require a node from the current frame. To wait for a settled UI, call `Zaniah::Inspection.idle?(app)` after draining queued work and rendering dirty windows.
 
-The public API is declared in [`sig/inspection.rbs`](../sig/inspection.rbs), and its independently runnable contract test is [`test/inspection_contract_test.rb`](../test/inspection_contract_test.rb). Breaking changes receive at least one minor version of deprecation during 0.x, as recorded in [ADR 013](adr/013-public-inspection-api.md).
+The public API is declared in [`sig/inspection.rbs`](../sig/inspection.rbs).
+Breaking changes receive at least one minor version of deprecation during 0.x,
+as recorded in [ADR 013](adr/013-public-inspection-api.md).

data/docs/layout.md

@@ -96,14 +96,6 @@ remains a set of stable row IDs; hook arguments are `Grid::Area` ranges in the
 current sorted display order, covering all columns. Disjoint selected rows
 produce separate areas. The application retains ownership of table data.
 
-`bench/grid.rb` measures a headless 800×600 viewport over a 1,000,000×16,000
-grid at 23 sequential scroll positions, including cell construction, layout,
-prepaint, and paint. `BUDGET=1 ruby bench/grid.rb` asserts a 16.67 ms median
-frame limit. A local run on 2026-09-23 measured 12.964 ms and constructed an
-average of 250 cells per frame. This microbenchmark does not include an
-application's backing store, expensive cell renderers, or a native compositor;
-rerun it on target hardware for deployment decisions.
-
 `ScrollView` accepts one child and clips it to the viewport. Its `axis` is
 `:vertical`, `:horizontal`, or `:both`; use `scroll_to` for programmatic
 scrolling and `scroll_state` for offsets and edge checks.

data/docs/native.md

@@ -42,6 +42,18 @@ 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.
 
+## File dialogs
+
+Native file dialogs accept a starting directory, suggested filename, and extension filters:
+
+```ruby
+window.prompt_for_paths(save: true, default_name: "capture.pcapng", directory: Dir.home,
+  filters: [{label: "Capture files", patterns: ["*.pcapng", "*.pcap"]}])
+```
+
+Patterns support `*` and `*.extension`. macOS combines the allowed extensions;
+Linux and Windows also show each named filter. Cancel returns an empty array.
+
 ## Clipboard representations
 
 `Clipboard::Item` holds eager MIME-keyed data. `text/*` values are UTF-8 text;
@@ -145,20 +157,3 @@ 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
-ruby examples/native_menu.rb              # macOS only
-```
-
-Linux XIM composition is exercised in CI with Xvfb and IBus/KKC. Native input,
-IME on macOS and Windows, dialogs, and terminal integration also require manual
-checks on the target operating system.