Selkie.git | docs/api/ | Selkie--Tree.md
NAME
====
Selkie::Tree - Tree-walking helpers used by widgets that need to reach beyond their own subtree
SYNOPSIS
========
```raku
use Selkie::Tree;
# Mark every widget whose plane intersects this absolute screen rect
# as dirty — used by Image.destroy-blit-plane to repaint cells under
# the removed sprixel.
mark-widgets-in-rect-dirty(
abs-y => 5, abs-x => 10,
rows => 4, cols => 16,
);
# The active modal (or Nil), used by widgets that need to skip
# rendering when occluded.
my $modal = current-active-modal;
# Every walk up a parent chain takes its hops through next-ancestor,
# which turns a cyclic tree into a loud death instead of a frozen
# render thread.
my $node = $some-widget;
my int $hops = 0;
while $node.defined {
last if $node === $wanted;
$node = next-ancestor($node, $hops);
$hops = $hops + 1;
}
```
DESCRIPTION
===========
A small set of free subs that bridge between a widget and the wider tree it lives in, without requiring the widget to walk up to the [Selkie::App](Selkie--App.md) instance manually. [Selkie::App](Selkie--App.md) at init populates two class-level provider closures — one returning the live list of tree roots (active screen + modal stack + toast), the other returning the active modal — and the helpers here read through them.
This pattern keeps widgets like [Selkie::Widget::Image](Selkie--Widget--Image.md) from needing a circular import on Selkie::App while still letting them participate in app-level coordination (cell cleanup after sprixel destroy, modal occlusion checks, etc.).
`next-ancestor` is the other half of that job: the single hop primitive every parent-chain walk in Selkie goes through. It is a guard, not a convenience — see "Cycle-safe parent walks" below.
`mark-widgets-in-rect-dirty` walks whole trees, so it is written to stay cheap on the trees it actually meets: it prunes any subtree whose root is parked (see `Selkie::Widget.is-parked` — notcurses carries bound child planes with their parent, so a parked subtree owns no on-screen cells), and it duck-types `children` / `content` through `nqp::can`. Both details matter for correctness as much as speed; see the sub's own documentation.
Cycle-safe parent walks
-----------------------
A widget tree is a tree by convention, not by construction: `parent` is a plain writable attribute that layouts set when they adopt a child. One mis-ordered reparent — a container adopting a widget that is already one of its own ancestors — turns every `while $node.defined { $node = $node.parent }` loop into an infinite spin. Several of those loops run on the frame path (focus validation, dirty propagation, event bubbling), so the symptom is the worst shape a TUI failure can take: the screen freezes, every key is dead, nothing crashes, and there is no stack to look at.
`next-ancestor` is the hop primitive that makes that impossible. Take each step through it, passing the number of hops taken so far, and a cyclic chain dies at `PARENT-CHAIN-LIMIT` hops with an `X::Selkie::WidgetCycle` naming the widgets in the loop:
```raku
my $node = $widget;
my int $hops = 0;
while $node.defined {
return True if $node === $root;
$node = next-ancestor($node, $hops);
$hops = $hops + 1;
}
```
[X::Selkie::WidgetCycle](X::Selkie::WidgetCycle) is a compunit of its own, so `CATCH { when X::Selkie::WidgetCycle { … } }` names it exactly as written.
The limit is deliberately far above any real nesting depth (a deep production layout is tens of widgets, not hundreds), so tripping it is never a false positive and always an upstream bug. It fails loudly on purpose: a silently truncated walk would leave focus, dirty marking and event routing quietly wrong for the rest of the session.
The guard costs one integer comparison per hop and allocates nothing — the walks it protects run per frame.
Widget teardown notifications
-----------------------------
`Selkie::Widget`'s plane-destroy chokepoint calls `notify-widget-destroyed`, so app-level bookkeeping that holds widget references (mouse capture, for one) can drop them instead of routing later events into a torn-down widget. `Selkie::App` installs the observer at init through `set-widget-destroyed-observer`.
The observer runs on whatever thread destroyed the widget — including the GC finalizer thread, since `Widget.DESTROY` routes to `destroy`. Observers must therefore be thread-safe and must not touch app data structures the render thread owns; the supported shape is to set an atomic flag and let the render thread do the actual pruning.
### sub set-tree-roots-provider
```raku
sub set-tree-roots-provider(
&p
) returns Nil
```
Set the tree-roots provider — a closure returning an iterable of widget roots. `Selkie::App` calls this during init so tree-walking helpers can find the live trees without each helper needing a direct reference to the app.
### sub current-tree-roots
```raku
sub current-tree-roots() returns List
```
The current list of widget tree roots. Used internally by helpers in this module; apps don't typically call this directly.
### sub set-modal-provider
```raku
sub set-modal-provider(
&p
) returns Nil
```
Set the active-modal provider — a closure returning the topmost open modal widget or Nil. `Selkie::App` calls this on init.
### sub current-active-modal
```raku
sub current-active-modal() returns Mu
```
The topmost open modal widget, or Nil if no modal is open.
### sub set-widget-destroyed-observer
```raku
sub set-widget-destroyed-observer(
&p
) returns Nil
```
Set the widget-destroyed observer — a closure called with each widget as its plane is destroyed. `Selkie::App` calls this on init. The observer may run on the GC finalizer thread; keep it thread-safe and allocation-light.
### sub notify-widget-destroyed
```raku
sub notify-widget-destroyed(
Mu $widget
) returns Nil
```
Notify the registered observer that `$widget` is being destroyed. Called by `Selkie::Widget`; apps don't call this directly. Never lets an observer failure escape into a teardown path: a destroy that throws would abandon the rest of the widget's cleanup (and, from a finalizer, take down the GC thread's work item).
### sub next-ancestor
```raku
sub next-ancestor(
Mu $node,
int $hops
) returns Mu
```
One hop up a parent chain, with the cycle guard applied. `$hops` is the number of hops already taken on this walk; pass 0 on the first call and increment from there. Returns `$node.parent` — the walk's own `.defined` test is what ends it at the root. Throws `X::Selkie::WidgetCycle` once a single walk has taken `PARENT-CHAIN-LIMIT` hops. See the "Cycle-safe parent walks" section above for why this fails loudly rather than truncating.
### sub widget-occluded-by-active-modal
```raku
sub widget-occluded-by-active-modal(
Mu $widget
) returns Bool
```
True when `$widget` is outside the active modal tree and therefore should suppress out-of-band painting such as sprixels. Widgets inside the active modal, including descendants of its content tree, are not occluded.
### sub mark-widgets-in-rect-dirty
```raku
sub mark-widgets-in-rect-dirty(
Int :$abs-y!,
Int :$abs-x!,
Int :$rows! where { ... },
Int :$cols! where { ... }
) returns Nil
```
Walk every tree root and mark dirty any widget whose absolute screen bounds intersect the given rectangle. Used by sprixel-bearing widgets after they destroy a blit-plane: the cells under the removed sprixel may belong to a widget that has nothing else changing this frame, so without an explicit dirty mark the widget won't repaint and the cells will continue to show whatever was cached pre-sprixel-removal. Called once per blit teardown. Two properties keep this affordable on the trees it actually runs against (a long chat transcript in a consumer app is ~10k widgets): =item **Parked subtrees are pruned.** A widget whose `is-parked` latch is set has been moved to `park-y`, and notcurses carries every bound descendant plane along with it — so neither it nor anything beneath it owns an on-screen cell, and none of them can intersect an on-screen rect. Skipping the subtree is not an approximation. It also breaks a feedback loop: without the prune, tearing a sprixel down re-dirties the parked cards whose stale `abs-y` still overlaps the rect, which re-renders them, which tears more sprixels down. =item **Capability tests go through `nqp::can`.** `children` and `content` are duck-typed here on purpose — `Selkie::Widget::CardList` and `ViewportedCardList` expose `children` without composing `Selkie::Container`, so a `~~ Selkie::Container` test would walk past every card in the list. `nqp::can` answers the same question as `.^can` from the method cache, without building the candidate list `.^can` returns.