Ship the lazy-tree demo and large-scale performance gates

[RayZhao1998]

Parent

#16

What to build

Ship the lazy-tree capability with a complete Demo, cross-platform verification, documentation, and reproducible large-scale performance gates.

The final integration should let adopters compare eager and lazy models under the same behavior, observe loading/failure/retry/reveal flows, and reproduce evidence that undiscovered nodes no longer contribute model or renderer storage.

Acceptance criteria

• The Demo can switch between eager and lazy data using equivalent content and controls.
• Demo scenarios cover delayed roots, unloaded disclosure, expansion, concurrent interactions, collapse/reset, failure/retry, deep reveal, invalid data, and retained state.
• AppKit and SwiftUI Demo surfaces exercise the same model; an iOS test host or Demo verifies UIKit behavior, focus, RTL, and accessibility.
• Automated tests cover the complete lazy acceptance matrix on supported platforms, and CI builds/tests macOS plus type-checks or tests the iOS target with Swift 6 warnings treated as errors.
• Reproducible performance runs compare eager and lazy modes at 2,500, 100,000, and at least 500,000 potential nodes.
• Results report discovered and loaded node counts, provider calls, physical and peak footprint, main-thread time, and visible-content update latency.
• The suite has documented regression thresholds or comparison rules that account for platform and run-to-run variance.
• README and DocC document eager versus lazy setup, loading/retry/reveal behavior, cache lifetime, cancellation, validation, and migration without breaking eager call sites.
• Documentation clearly keeps filesystem enumeration, watching, persistence, Git state, and automatic cache eviction outside TreeKit core.
• Add lazy child loading for large and remote trees #16's acceptance criteria are demonstrably satisfied by its linked child issues.

Blocked by

• Reveal targets through unloaded ancestors #20
• Validate and atomically publish lazy children #22