Add profiler

README.md

@@ -93,6 +93,27 @@ Sibling views are lazy rather than pre-mounted: only the initial route exists on
 
 Call `nativeRouter.unload('/some-route')` to manually unmount inactive instances of one location while retaining their lightweight history descriptors. The active route and views participating in a transition are protected.
 
+### Capture frame pacing on a real device
+
+The Navigation Lab contains an opt-in profiler. Tap **Start profiling**, leave the lab, reproduce the choppy navigation once or twice, return to the lab, tap **Stop**, then **Share JSON**. Installed iOS PWAs use the system share sheet; other browsers download the file. Attach that JSON to a bug report.
+
+The core API is also available directly:
+
+```ts
+import { createNativeNavigationProfiler } from '@native-vue-router/core'
+
+const profiler = createNativeNavigationProfiler(nativeRouter, {
+  metadata: { build: import.meta.env.VITE_BUILD_ID },
+})
+
+profiler.start()
+// Reproduce the navigation issue.
+const report = profiler.stop()
+const json = profiler.toJSON(report)
+```
+
+No rAF loop or browser performance observer runs before `start()`, and `stop()` removes them. Reports contain frame intervals, refresh-rate estimates, per-navigation timing, cold-mount preparation, route loading, cache eviction, visibility changes, and browser-supported Long Task/layout-shift/resource timing. Route params, query values, and application state are omitted.
+
 ## Packages
 
 - `@native-vue-router/core` — transactions, route ledger, concurrent views, gestures, caching, and public components/composables.