zaniah 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6787d1edc51a6a692859fe62834270cfa2339ade8b00e596e8861632eb59913
-  data.tar.gz: 7407abf9f7a64c80fc307843ffeadd9d130cfb45a12673a85f6cbedf2710a3e4
+  metadata.gz: 0a864e71f3de289770aafa36f520440c0adab078b763412544bca3f9fb32cacb
+  data.tar.gz: fc0e6fb0c05f8d0769305954cc5a730258947845b8438328df6d66ca172e80ad
 SHA512:
-  metadata.gz: 35cdfc811f06f704d21202e60029c2869eb5b01698c4e52cde3ce2b7c0e45eaa0c6c5a60ec46e9e9f4e15fd2e1b7f88a75b71b9ec829423540259238739cf468
-  data.tar.gz: beaae799ef7227cf30d354819b4d896ee1957666c1617d4a43a15fd8d0112180b0dcf74dadf930c6df8376eaa0045663c83400cca2f6bf019142ab9cb2af0592
+  metadata.gz: 16ff7f0e3cc0ce444b502eaff32faaab6cf503af5bf0a4ad547a305aa9394c91d9960052e60bc94ce775521bd54e42ddadfff49b6f896147ca00771e3e4aa59f
+  data.tar.gz: 959e485686a3e92a155916a306afc0eb7848f6556d5c1bc6cbfe9c30a605701213dd37c79c978d49b807c60b25e9a47a3cc1e3fff9731cf0ae5a0432a7522f51

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.5.1 — 2026-09-16
+
+- Let lazy tree views accept externally loaded children and invalidate cached subtrees without blocking the UI thread.
+- Prevent replacement tree sources from inheriting stale lazy children.
+
+## 0.5.0 — 2026-09-15
+
+- Make tree views lazy and viewport-virtualized while preserving stable-ID state across source rebuilds.
+- Add bounded, thread-safe low-resolution text textures with per-line invalidation and repeated-shape raster reuse for minimaps.
+- Add stable-ID pointer and keyboard reordering with virtual targets and live accessibility status.
+- Add arbitrary stable-ID pane grids with resizable fixed, fractional, and minmax tracks.
+- Preserve screen-reader identity across virtualization and reordering, with direct tree and pane actions plus native focus and live-region events.
+
 ## 0.4.0 — 2026-09-15
 
 - Add inline and block text overlays with wrapping-aware layout, hit testing, and row-local relayout.

data/README.md

@@ -37,10 +37,12 @@ the drawing surface beneath the editor.
 - Gradients, transforms, paths, SVG, shadows, clipping, and GPU glyph atlases
 - Retained element state, subscriptions, and non-blocking background tasks
 - Scroll views, inertial input, and uniform or variable-height virtual lists
-- OpenType shaping, font fallback, Japanese wrapping, text overlays, selection, editing, and IME
+- Stable-ID pointer and keyboard reordering without materializing virtual collections
+- Stable-ID split-pane grids with fixed, fractional, and minmax tracks
+- OpenType shaping, font fallback, Japanese wrapping, text overlays, low-resolution text caching, selection, editing, and IME
 - Themes, state styles, keyed animation, springs, and reduced-motion support
-- Opt-in controls, overlays, tables, trees, charts, forms, and terminal fallbacks
-- Spatial keyboard focus and a diffed cross-platform accessibility tree
+- Opt-in controls, overlays, tables, externally completable lazy virtual trees, charts, forms, and terminal fallbacks
+- Spatial keyboard focus and a stable-ID, event-diffed cross-platform accessibility tree
 - F12 inspector, frame statistics, hot reload, and headless golden-image tests
 - Native input, IME, clipboard, file-drop, display, and filesystem events
 - RBS declarations for the public API
@@ -114,7 +116,8 @@ Native backends use the operating system libraries through Ruby's Fiddle. See
 - [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
-- [Layout and scrolling](docs/layout.md) — Grid, ScrollView, sticky positioning, and RTL foundations
+- [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

data/docs/accessibility.md

@@ -1,9 +1,9 @@
 # Accessibility
 
 Every window maintains a backend-neutral `Accessibility::Tree` beside its render
-tree. Components expose role, label, value, bounds, states, children, and actions
-through `Accessibility::Node`. The window publishes a notification only when the
-semantic tree changes.
+tree. Components expose a stable ID, role, label, value, bounds, states, children,
+and actions through `Accessibility::Node`. The window publishes notifications only
+when the semantic tree changes.
 
 ```ruby
 window.accessibility_tree.each do |node, path|
@@ -11,10 +11,13 @@ window.accessibility_tree.each do |node, path|
 end
 ```
 
-`window.accessibility_revision` increments after each semantic change, and
-`window.accessibility_tree.changes` contains `added`, `removed`, or `updated`
-records. This makes accessibility assertions deterministic on the headless
-backend without mocking an operating system API.
+`window.accessibility_revision` increments after each semantic change.
+`window.accessibility_tree.changes` contains `added`, `removed`, `updated`, or
+`moved` records; stable IDs let a reorder remain a move instead of two unrelated
+updates. IDs must be immutable and unique among siblings. The accompanying
+`events` reduce those changes to deterministic `structure`, `property`, `layout`,
+`focus`, and `announcement` events. This makes accessibility assertions
+deterministic on the headless backend without mocking an operating system API.
 
 ## Component semantics
 
@@ -30,6 +33,7 @@ Custom components implement the same method:
 def accessibility_node(_cx)
   Zaniah::Accessibility.node(
     role: :button,
+    id: :refresh,
     label: "Refresh",
     states: {busy: @loading},
     actions: @loading ? [] : [:press]
@@ -37,20 +41,42 @@ def accessibility_node(_cx)
 end
 ```
 
+If a component synthesizes semantic descendants, it can route their actions
+without coordinate hit testing:
+
+```ruby
+def accessibility_action(node, action)
+  refresh(node.id) if action == :press
+end
+```
+
+`TreeView` uses item IDs for its viewport-only descendants and reports the
+selected descendant as focused while the tree owns keyboard focus. Its select,
+expand, and collapse actions call the tree model directly. `PaneGrid` gives panes
+and dividers stable IDs and routes divider increment, decrement, minimum, and
+maximum actions through the same resizing path as the keyboard. A
+`DragDrop::Reorder` exposes keyboard reorder actions and a stable, atomic polite
+live region for move and cancellation results. Offscreen virtual rows remain
+unmaterialized; when they re-enter the viewport, their IDs reconnect them to the
+same native identity.
+
 Decorative content should return `nil`. Container elements without an explicit
 node retain semantic descendants in a generated `group` node.
 
 ## Native bridges
 
-- macOS publishes an `NSAccessibilityElement` hierarchy with roles, labels,
-  values, state, bounds, and children, then posts `AXLayoutChanged`.
+- macOS publishes an `NSAccessibilityElement` hierarchy with identifiers, roles,
+  labels, values, state, bounds, and children, then posts layout, value, focus,
+  and announcement notifications from semantic events.
 - Windows answers `WM_GETOBJECT` with `IRawElementProviderSimple`, fragment,
   fragment-root, and Invoke providers. UI Automation clients can navigate and
-  query the semantic hierarchy rather than relying on refresh events alone.
+  query stable Automation IDs and receive structure, property, layout, focus,
+  and live-region events rather than relying on refresh events alone.
 - Linux registers `Accessible`, `Component`, `Action`, and `Application`
   objects on the AT-SPI D-Bus, embeds the application root in the registry,
-  and emits object-change events. Actions route back through the normal input
-  dispatcher on every platform.
+  retains stable `AccessibleId` values and object paths, and emits matching
+  object, state, and announcement events. Actions route back through the normal
+  input dispatcher or a component's direct semantic action on every platform.
 
 The Linux provider is exercised in CI inside a private D-Bus session. Native
 macOS and Windows objects retain the same `Accessibility::NativeTree` path and

data/docs/adr/011-stable-accessibility-identity.md

@@ -0,0 +1,26 @@
+# ADR 011: Match accessibility descendants by stable identity
+
+- Status: Accepted
+- Date: 2026-09-15
+- Decision deadline: before screen-reader virtualization support
+
+## Context
+
+Position-only semantic paths change when a virtual viewport scrolls or siblings
+are reordered. Native bridges then expose a previously known item as a different
+object, and coordinate-generated actions can target the wrong virtual row.
+
+## Decision
+
+Let semantic nodes carry an optional immutable ID that is unique among siblings.
+Match identified siblings by ID when diffing and retain native runtime IDs across
+tree publications. Keep offscreen rows absent. Route actions on synthesized nodes
+back to their owning component, and derive native structure, property, layout,
+focus, and live-region events from the shared semantic diff.
+
+## Consequences
+
+Virtual tree rows, reordered panes, and live status nodes regain their native
+identity when their semantic node moves. Components remain responsible for stable
+domain IDs and expose no platform objects. Unidentified nodes retain positional
+matching and coordinate action fallback for compatibility.

data/docs/components.md

@@ -79,11 +79,12 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L3 | `Toast` | `(message, variant:, queue:)`; `dismiss` | info/success/warning/danger | live status |
 | L3 | `CommandPalette` | `(commands, open:, placeholder:)` | searchable modal | dialog/list |
 | L3 | `SplitPane` | `(first, second, orientation:, ratio:, min:, max:)`; `on_change` | horizontal/vertical, draggable separator | group/separator |
+| L3 | `PaneGrid` | `(panes, columns:, rows:, divider_size:, minimum:, keyboard_step:)`; `replace`, `on_resize` | arbitrary resizable grid, stable pane IDs | group/separator |
 | L3 | `Resizable` | `(content, width:, height:, min_width:, min_height:, max_width:, max_height:)`; `on_resize` | drag or keyboard resize | group/separator |
 | L3 | `DockPanel` | `(center:, top:, right:, bottom:, left:)` | five-region layout | group |
 | 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` | virtual rows, sorting, resizing, editing | table/row/cell |
-| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, lazy `children` proc | arrows/Home/End | tree/treeitem |
+| L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
 | L5 | `Sparkline` | `(values, width:, height:, color:, label:)` | line + tooltip | image |
 | L5 | `LineChart`, `BarChart` | `(series, width:, height:, colors:, label:)` | axes, legend, tooltip | image |
 | L5 | `Validation` | `required`, `format`, `length`, `number`, `rule` | composable rules | n/a |
@@ -98,12 +99,26 @@ the previous focus. See [TUI](tui.md) for terminal representations.
 
 Table columns are hashes with `key`, and optional `label`, `width`, `sortable`,
 `resizable`, `editable`, and `render`. Tree items accept hashes containing `id`,
-`label`, and either an array or lazy proc in `children`.
+`label`, and either an array or lazy proc in `children`. A lazy proc receives the
+item value, runs on first expansion, and is cached after it succeeds; a raised
+exception leaves it available for retry. A loader can return a placeholder while
+work runs elsewhere; call `replace_children(id, children)` on the UI thread to
+apply the result without changing selection, focus, or expansion. It returns
+`false` when the ID is missing or is not lazy. `invalidate(id)` likewise returns
+`false` for missing or non-lazy items; otherwise it discards that lazy result and
+its loaded descendants so the next expansion calls the loader again. Omit the ID
+to invalidate all loaded results. `replace(items)` starts a
+new source generation, so it never inherits loaded children from the old source.
+Completed children must be an array with unique, non-nil stable IDs, at most 64
+levels deep and 100,000 items total. Invalid results leave the previous children
+unchanged. Tree rows and accessibility nodes are built only for the current
+viewport.
 
 In a table, Up/Down/Home/End/Page keys move and select rows, Shift+Up/Down extends
 a range, and Cmd/Ctrl+A selects every row in multiple-selection mode. Sortable
 headers and resize handles are separate Tab stops; Enter sorts and arrow/Page keys
-resize. Tree views use Up/Down to select and Left/Right to collapse or expand.
+resize. 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/drag_drop.md

@@ -0,0 +1,46 @@
+# Drag-and-drop reordering
+
+`DragDrop::Reorder` coordinates pointer and keyboard reordering without owning the
+application's collection. It identifies items by stable IDs and reports a
+`DragDrop::Target` whose position is `before`, `after`, or `inside`.
+
+```ruby
+reorder = Zaniah::DragDrop::Reorder.new(
+  threshold: 4,
+  locate: ->(point, source_id) { target_at(point, excluding: source_id) },
+  keyboard: ->(id, direction) { adjacent_target(id, direction) },
+  label: ->(id) { item_label(id) }
+).on_drop do |event|
+  move_item(event.source_id, event.target.id, event.target.position)
+end
+
+row
+  .on_mouse_down { |event, _| reorder.press(row_id, event.position) }
+  .on_drag { |event, _| reorder.move(event.position) }
+  .on_mouse_up { |event, _| reorder.release(event.position) }
+  .focusable(context: {reorderable: true}) { |action| reorder.action(row_id, action) }
+```
+
+The pointer locator is called only after the drag threshold is crossed. Virtual
+lists can derive a row with `List::HeightIndex#index_at`; uniform lists can use
+division by row height. Tree views can resolve a visible segment and return an
+`inside` target only for containers. No API requires enumerating or rendering the
+whole collection. Return `nil` for collection-specific no-ops, such as placing an
+item after its current predecessor.
+
+Listen with `on_event` for `press`, `start`, `enter`, `over`, `leave`, `drop`, and
+`cancel`. Call `remove(id)` when application data removes a source or current
+target, and call `cancel` when an enclosing interaction ends. Callback failures
+reset transient drag state before being re-raised. Callbacks may update the
+application collection, but must not re-enter their `Reorder` controller; an
+attempt raises `Zaniah::Error` and cancels the active operation.
+
+For keyboard access, mark the focused element with `reorderable: true`. Alt+Up
+and Alt+Down dispatch `reorder_before` and `reorder_after`; Escape dispatches
+`cancel_reorder`. `accessibility_actions(id)` returns the actions a containing
+item should expose, and `action(id, action)` routes them without pointer geometry.
+`accessibility_node` exposes the last result as a stable, atomic polite `status`
+node. Include that node in the containing component's accessibility children, or
+forward `on_announce` to its existing live region. Native file drops are separate
+and are not handled by this primitive. The controller belongs to its UI owner:
+call it on that owner's event thread and `cancel` before the owner is discarded.

data/docs/layout.md

@@ -17,6 +17,26 @@ Zaniah::Div.new.style(
 Place an item with `grid_column: 2` or span inclusive tracks with
 `grid_column: 1..3`. Named areas and `auto-fit`/`auto-fill` are not supported.
 
+`UI::PaneGrid` turns a rectangular matrix into independently resizable rows and
+columns. Each non-empty cell is a `PaneGrid::Pane`, an `id`/`content` hash, or
+an `[id, content]` pair. IDs must be unique and remain stable when `replace` is
+used so retained pane state survives source rebuilds. Tracks accept fixed pixel
+numbers, `px`, `fr`, or `minmax` values.
+
+```ruby
+grid = Zaniah::UI::PaneGrid.new(
+  [[[:editor, editor], [:terminal, terminal]]],
+  columns: [Zaniah.minmax(Zaniah.px(240), Zaniah.fr(2)), Zaniah.fr(1)],
+  rows: [Zaniah.fr(1)]
+)
+grid.on_resize { |event, _context| save_split(event.axis, event.divider, event.before) }
+```
+
+Dividers support pointer drag, arrow keys, Page Up/Down, Home, and End. Their
+stable accessibility IDs, focus state, value, orientation, and direct increment,
+decrement, minimum, and maximum actions use the same clamped resize path. Nested
+`PaneGrid` instances compose without owning editor, terminal, or document state.
+
 `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/text.md

@@ -79,6 +79,24 @@ 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.
 
+For minimaps and other compact previews, cache Alhena's downsampled outlines as
+one R8 texture per source line:
+
+```ruby
+cache = Zaniah::TextSystem::LowResolutionTextCache.new(
+  width: 100, height: 2, scale: 0.1
+)
+texture = cache.texture(42, outlines: outlines)
+cache.invalidate(42) # regenerate only the edited source line on next access
+cache.close
+```
+
+The cache is thread-safe, count- and byte-bounded, and uses least-recently-used
+eviction. Textures already returned to a scene remain valid after eviction or
+invalidation. A cache has fixed width, height, and scale; invalidate a line when
+its outlines change for any reason, including a font change. Call `close` when
+the cache is no longer needed.
+
 ## Development checks
 
 ```sh

data/docs/tui.md

@@ -21,7 +21,7 @@ tests and non-window integrations.
 | ScrollView, Scrollbar | clipped child content and `│`/`─` track |
 | Breadcrumb, Pagination, bars | slash-separated path, page status, space-separated content |
 | Modal, Dialog, Drawer, CommandPalette | box-drawing overlay; focus stays inside until dismissed |
-| SplitPane, Resizable, DockPanel | `│`/`─` separators, resize corner, or ordered dock regions |
+| SplitPane, PaneGrid, Resizable, DockPanel | `│`/`─` separators, resize corner, or ordered dock regions |
 | ListView | visible rows with `>` on the selected item |
 | Toast | live status text |
 | Table, DataGrid | header and visible rows separated with `|` |

data/lib/zaniah/accessibility/linux/service.rb

@@ -84,15 +84,15 @@ module Zaniah
           parse_interfaces
         end
 
-        def update(root)
+        def update(root, events: [])
           application = Accessibility.node(role: :application, label: window_title,
             bounds: root.bounds, children: [root])
-          @tree = NativeTree.new(application)
+          @tree = NativeTree.new(application, previous: @tree)
           @entries = @tree.to_h { |entry| [path(entry), entry] }
           (@registrations.keys - @entries.keys).each { |object_path| unregister(object_path) }
           (@entries.keys - @registrations.keys).each { |object_path| register(object_path) }
           embed unless @embedded
-          emit_change
+          emit_changes(events)
           true
         end
 
@@ -179,10 +179,23 @@ module Zaniah
           @embedded = true
         end
 
-        def emit_change
-          parameters = tuple(string(""), int32(0), int32(0), variant(string("")), array("{sv}", []))
-          gio.fn(:g_dbus_connection_emit_signal, [P, P, P, P, P, P, P], I)
-            .call(@connection, 0, ROOT_PATH, "org.a11y.atspi.Event.Object", "VisibleDataChanged", parameters, 0)
+        def emit_changes(events)
+          events = [nil] if events.empty?
+          events.each do |event|
+            member, detail, active = case event&.kind
+            when :structure then ["ChildrenChanged", event.node.id.to_s, 1]
+            when :property then ["PropertyChange", event.node.id.to_s, 0]
+            when :focus then ["StateChanged", "focused", 1]
+            when :announcement then ["Announcement", event.node.label.to_s, 1]
+            else ["VisibleDataChanged", "", 0]
+            end
+            entry = event && @tree[[0, *event.path]] unless %i[structure layout].include?(event&.kind)
+            parameters = tuple(string(detail), int32(active), int32(0),
+              variant(string(event&.node&.label || "")), array("{sv}", []))
+            gio.fn(:g_dbus_connection_emit_signal, [P, P, P, P, P, P, P], I)
+              .call(@connection, 0, entry ? path(entry) : ROOT_PATH,
+                "org.a11y.atspi.Event.Object", member, parameters, 0)
+          end
         end
 
         def method_call(object_path, interface, method, parameters, invocation)
@@ -269,7 +282,9 @@ module Zaniah
           when [ACCESSIBLE, "Parent"] then reference(entry.parent)
           when [ACCESSIBLE, "ChildCount"] then int32(entry.children.length)
           when [ACCESSIBLE, "Locale"] then string(ENV["LANG"] || "C")
-          when [ACCESSIBLE, "AccessibleId"] then string(entry.runtime_id.to_s)
+          when [ACCESSIBLE, "AccessibleId"]
+            id = entry.node.id
+            string((id.nil? ? entry.runtime_id : id).to_s)
           when [ACTION, "NActions"] then int32(entry.node.actions.length)
           when [APPLICATION, "ToolkitName"] then string("Zaniah")
           when [APPLICATION, "Version"], [APPLICATION, "ToolkitVersion"] then string(Zaniah::VERSION)

data/lib/zaniah/accessibility/linux.rb

@@ -11,7 +11,7 @@ module Zaniah
       def publish(window, root, _changes)
         return false unless root
         service = services[window.object_id] ||= Service.new(window)
-        service.update(root)
+        service.update(root, events: window.accessibility_tree.events)
       rescue Fiddle::DLError, Errno::ENOENT, Error
         false
       end

data/lib/zaniah/accessibility/mac.rb

@@ -28,7 +28,8 @@ module Zaniah
         return unless root && defined?(Platform::Mac::O) && window.respond_to?(:view)
         install
         ELEMENTS.delete_if { |_element, (owner, _node)| owner.equal?(window) }
-        tree = NativeTree.new(root)
+        previous = window.instance_variable_get(:@native_accessibility_tree)
+        tree = NativeTree.new(root, previous: previous)
         children = mutable_array
         append(children, native_element(window, tree, tree.root, window.view))
         object = window.view
@@ -72,8 +73,9 @@ module Zaniah
           o.string(ROLES.fetch(node.role, "AXGroup")), screen_bounds(window, tree.bounds(entry)),
           o.string(node.label || node.value&.to_s || node.role.to_s), parent,
           args: [:pointer, :rect, :pointer, :pointer])
-        ELEMENTS[element] = [window, node, tree.bounds(entry)]
+        ELEMENTS[element] = [window, node, tree.bounds(entry), entry.runtime_id]
         o.send(element, "setAccessibilityFrameInParentSpace:", parent_bounds(tree, entry), args: [:rect], result: :void)
+        o.send(element, "setAccessibilityIdentifier:", o.string(node.id.to_s), args: [:pointer], result: :void) unless node.id.nil?
         o.send(element, "setAccessibilityEnabled:", node.states[:disabled] ? 0 : 1, args: [:bool], result: :void)
         o.send(element, "setAccessibilityValue:", native_value(node.value), args: [:pointer], result: :void) unless node.value.nil?
         set_boolean(element, "setAccessibilitySelected:", node.states[:selected]) if node.states.key?(:selected)
@@ -126,9 +128,22 @@ module Zaniah
       def notify(window, object)
         function = Platform::Mac::APPKIT.fn(:NSAccessibilityPostNotification,
           [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID)
-        function.call(object, Platform::Mac::O.string("AXLayoutChanged"))
-        if window.accessibility_tree.changes.any? { |change| change.after&.role == :status }
-          function.call(object, Platform::Mac::O.string("AXAnnouncementRequested"))
+        notifications(window.accessibility_tree.events).each do |event, name|
+          runtime_id = window.instance_variable_get(:@native_accessibility_tree)&.[](event.path)&.runtime_id unless %i[structure layout].include?(event.kind)
+          target = ELEMENTS.find { |_element, (owner, _node, _bounds, id)| owner.equal?(window) && id == runtime_id }&.first || object
+          function.call(target, Platform::Mac::O.string(name))
+        end
+      end
+
+      def notifications(events)
+        events.filter_map do |event|
+          name = case event.kind
+          when :structure, :layout then "AXLayoutChanged"
+          when :property then "AXValueChanged"
+          when :focus then "AXFocusedUIElementChanged"
+          when :announcement then "AXAnnouncementRequested"
+          end
+          [event, name] if name
         end
       end
     end

data/lib/zaniah/accessibility/native_tree.rb

@@ -9,9 +9,11 @@ module Zaniah
 
       attr_reader :root
 
-      def initialize(root)
+      def initialize(root, previous: nil)
         @entries = {}
-        @next_runtime_id = 1
+        @identities = {}
+        @previous_ids = previous ? previous.__send__(:runtime_ids).dup : {}
+        @next_runtime_id = (@previous_ids.values.max || 0) + 1
         @root = build(root, nil, []) if root
       end
 
@@ -32,6 +34,8 @@ module Zaniah
       end
 
       def focused(window)
+        semantic = find { |entry| entry.node.states[:focused] }
+        return semantic if semantic
         bounds = window.dispatcher.focused&.bounds
         bounds && hit(Point.new(bounds.x + bounds.width / 2.0, bounds.y + bounds.height / 2.0))
       end
@@ -39,14 +43,20 @@ module Zaniah
       private
 
       def build(node, parent, path)
-        entry = NativeEntry.new(path: path.freeze, node: node, parent: parent, children: [], runtime_id: next_runtime_id)
+        path = path.freeze
+        key = [(parent && identity(parent)), node.id.nil? ? [:index, path.last] : [:id, node.id]].freeze
+        runtime_id = @previous_ids[key] ||= next_runtime_id
+        entry = NativeEntry.new(path: path, node: node, parent: parent, children: [], runtime_id: runtime_id)
         @entries[entry.path] = entry
+        @identities[entry.object_id] = key
         children = node.children.map.with_index { |child, index| build(child, entry, path + [index]) }.freeze
         entry.children.replace(children)
         entry.children.freeze
         entry
       end
 
+      def identity(entry) = @identities.fetch(entry.object_id)
+      def runtime_ids = @previous_ids
       def next_runtime_id = (@next_runtime_id += 1) - 1
     end
   end

data/lib/zaniah/accessibility/node.rb

@@ -2,9 +2,12 @@
 
 module Zaniah
   module Accessibility
-    Node = Data.define(:role, :label, :value, :bounds, :states, :children, :actions)
+    Node = Data.define(:role, :label, :value, :bounds, :states, :children, :actions) do
+      def id = states[:accessibility_id]
+    end
 
-    def self.node(role:, label: nil, value: nil, bounds: nil, states: {}, children: [], actions: [])
+    def self.node(role:, id: nil, label: nil, value: nil, bounds: nil, states: {}, children: [], actions: [])
+      states = states.merge(accessibility_id: id) unless id.nil?
       Node.new(role: role.to_sym, label: label&.to_s, value: value, bounds: bounds,
         states: states.dup.freeze, children: children.dup.freeze, actions: actions.map(&:to_sym).freeze)
     end