Module spatial 

Spatial navigation: arrow-key focus movement based on widget geometry.

Given a set of focusable nodes with bounding rectangles, finds the best candidate in a given direction using a quadrant-based search with weighted distance scoring.

Algorithm

1. Check for explicit edge override in the graph (takes precedence).
2. Filter candidates to the correct quadrant relative to the current node.
3. Score each candidate: primary_distance + 0.3 × orthogonal_distance.
4. Return the candidate with the lowest score.

Invariants

• Explicit graph edges always take precedence over spatial search.
• Only focusable nodes are considered.
• If no candidate exists in the direction, None is returned.
• The algorithm is deterministic: same layout → same navigation path.

Functions

build_spatial_edges

Build spatial edges for all nodes in the graph.

spatial_navigate

Find the best spatial navigation target from origin in dir.