docs(mobile/v4): performance guide + field-notes from building an app

[LukeTowers]

Draft — opening early so it can grow in small, reviewable commits as I keep building a real NativePHP Mobile v4 app and hit things the docs don't yet cover. Each item below lands as its own commit; happy to split into separate PRs if maintainers prefer.

Included so far

• digging-deeper/performance.md — a practical performance guide. The architecture pages (render-publish-mount, subtree-reuse) document the mechanism well, but there's no developer-facing "why does this tap feel heavy / what do I do" page. This one covers:
  • what a tap costs (event → render → publish → diff+paint), and that reactivity is per-screen — child components are composition, not independent update boundaries (a real point of confusion: it's tempting to split into child components expecting isolated re-renders);
  • that native diff + paint scale with on-screen node count even when little changed — so node count is the practical lever, which slightly nuances the "it's basically free" framing of subtree-reuse;
  • levers in order (key lists, flatten the tree, split heavy screens into their own route, components-for-reuse-not-isolation, lean polling);
  • how to measure with the built-in BenchmarkComponent (event/diff/paint breakdown), with the real-device caveat (simulator RTT/FPS is unreliable; per-stage breakdown still useful).

Planned (separate commits, as I hit/confirm them)

• @navigate quoting gotcha in the routing docs — @navigate='/route' (single quotes = short route form, auto-quoted) vs @navigate="…" (double quotes = raw PHP args). The mismatch is a silent compile break.
• Tooling prerequisites — native:watch requires Watchman (brew install watchman); iOS UI automation (idb) requires the standalone Command Line Tools. Small setup-doc additions.
• Anything else that trips me up while building that turns out to be undocumented.

Notes

• The Xcode 26 / iOS 26 SDK requirement is handled separately in docs(mobile/4): iOS build requires Xcode 26 (iOS 26 SDK) #450.
• All numbers referenced were gathered with the shipped BenchmarkComponent on the iOS simulator; the page is framed as guidance + how-to-measure rather than hard device benchmarks.

🤖 Generated with Claude Code