Improve caching

docs/architecture.md

@@ -32,7 +32,7 @@ interface NativeRouteOptions {
   siblingGroup?: string
   siblingOrder?: number
   siblingHistory?: 'push' | 'replace'
-  cache?: boolean
+  cache?: boolean | 'pin'
   gesture?: boolean | 'edge' | 'full'
 }
 ```
@@ -57,4 +57,29 @@ Applications can call `beginInteractive()`, `updateInteractive()`, and `finishIn
 
 ## Cache semantics
 
-The active route and recent inactive routes remain mounted. The default limit is eight inactive views per runtime. Older entries keep their route descriptor but are unmounted and lazily restored when revisited. Application data that must survive eviction belongs in an application store.
+The cache is lazy: application startup mounts the current route, not every sibling. A replace-style sibling is created when it is first visited or previewed and can then remain mounted without becoming a browser-back entry. Recent history targets can also stay warm so predictive Back restores component-local state such as a scrolled list immediately.
+
+The default limit is four inactive views per runtime. `cache: false` always unmounts an inactive route, while `cache: 'pin'` exempts it from ordinary LRU and manual trimming. A pushed detail route that is popped or dismissed is unmounted after its exit animation unless it is explicitly pinned. If a guard rejects a cached destination, that component tree is evicted because it is no longer a valid navigation target. Older entries keep lightweight route descriptors and are lazily reconstructed if history reaches them again.
+
+This is deliberately not implemented with a single Vue `<KeepAlive>`. An interactive transition must render the current and destination route instances concurrently, while one `<KeepAlive>` outlet normally activates one selected child. Separate temporary wrappers would themselves be removed and lose their caches. The runtime therefore owns the small multi-view cache and exposes equivalent route-aware lifecycle signals:
+
+```ts
+import {
+  onNativeViewActivate,
+  onNativeViewDeactivate,
+  onNativeViewEvict,
+  useNativeViewActiveEffect,
+  useNativeViewLifecycle,
+} from '@native-vue-router/core'
+
+const view = useNativeViewLifecycle()
+
+useNativeViewActiveEffect(() => {
+  const timer = startPolling()
+  return () => stopPolling(timer)
+})
+
+onNativeViewEvict((reason) => saveDraft(view.route.value, reason))
+```
+
+`isActive` means the route is authoritative. `isVisible` also includes either side of an in-progress transition. Use `useNativeViewActiveEffect` for polling and other work that should pause in a cached tab, or `useNativeViewVisibleEffect` for work needed during the animation. Application data that must survive eviction belongs in an application store.