Reveal targets through unloaded ancestors

[RayZhao1998]

Parent

#16

What to build

Reveal, optionally select, focus, and scroll to a target whose ancestors have not yet been discovered by a lazy model.

Because an unknown target ID cannot identify its own ancestors, callers must be able to provide an explicit root-to-target identity path or a provider path resolver. TreeKit should walk that path in order, reuse existing in-flight branch loads, validate each discovered edge, and apply the final interaction only after the target exists.

Acceptance criteria

• Lazy models expose an async reveal operation that accepts an explicit root-to-target ID path.
• Providers may optionally resolve a target ID into that path without making path resolution mandatory for basic lazy expansion.
• Reveal loads only missing ancestors in order and coalesces branch requests already in flight.
• Invalid roots, missing children, mismatched edges, provider failures, and cancellation produce typed errors without leaving a partially selected target.
• Successful reveal preserves existing expansion state, expands required ancestors, and applies select, focus, and scroll position with the same semantics as eager reveal.
• Repeated reveal of an already discovered target takes the eager fast path and performs no provider work.
• SwiftUI, AppKit, and UIKit consume the same final reveal request and native viewport alignment.
• The Demo can reveal deterministic deep targets through completely unloaded and partially loaded paths.
• Tests cover explicit paths, provider-resolved paths, partial caches, concurrent reveal and expansion, cancellation, invalid edges, hidden expansion intent, and all scroll positions.
• Documentation explains why a bare unknown ID is insufficient and when to use explicit paths versus a resolver.

Blocked by

• Make lazy expansion race-safe across collapse and reset #19