Add experiments folder. Add usage.md and SKILL.md. Fix Sheet interactions and add dynamic sheet mode.

skills/integrate-native-vue-router/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: integrate-native-vue-router
+description: Integrate, migrate, configure, or debug Native Vue Router in new or existing Vue 3 applications. Use when adding @native-vue-router/core, converting a Vue Router app to native route surfaces, defining parent or sibling topology, adding gesture links and modal/sheet navigation, handling cached-view lifecycle, composing Vue built-ins with NativeRouterView, creating custom presentations, or wiring Capacitor and Electron adapters.
+---
+
+# Integrate Native Vue Router
+
+Implement Native Vue Router as a visual transaction layer around Vue Router.
+Keep Vue Router authoritative for committed URLs, history, guards, redirects, and
+route matching.
+
+Read [references/integration-reference.md](references/integration-reference.md)
+before changing a project. Treat it as the API baseline for version `0.1.x`. If
+the installed package version or local source differs, inspect that version's
+`package.json`, exported declarations, and source before editing.
+
+## Choose the adoption path
+
+Determine whether the target is:
+
+- A new Vue application: establish the native route shell and topology while
+  creating the router.
+- An existing Vue Router application: preserve its history mode, routes,
+  guards, redirects, nested outlets, state, and deep links while migrating the
+  visual root and selected navigation calls.
+- A host integration: add the core first, then add Capacitor or Electron as an
+  adapter at the application boundary.
+- A targeted enhancement: adopt imperative animated navigation first and defer
+  predictive gestures or sibling paging.
+
+Do not widen the task into a framework upgrade without user authorization. If
+the project is below Vue 3.5 or Vue Router 5, report the compatibility gap and
+the exact upgrade it requires before changing dependencies.
+
+## Inspect the target
+
+Before editing, identify:
+
+1. Package manager, workspace layout, Vue version, and Vue Router version.
+2. The router creation file, history implementation, route records, guards,
+   redirects, scroll behavior, and lazy components.
+3. The app entry and plugin installation order.
+4. Every root and nested `RouterView`, plus wrappers such as `KeepAlive`,
+   `Transition`, and `Suspense`.
+5. Calls to `router.push`, `router.replace`, `router.back`, `RouterLink`, tab
+   controls, modal routing, and bespoke swipe handlers.
+6. Route-local side effects in setup/mount hooks, including analytics,
+   subscriptions, polling, media, and mutations.
+7. Deep-linkable child routes, ordered peer routes, and routes whose local state
+   can or cannot be evicted.
+8. Horizontal gesture owners such as carousels, maps, editors, and canvases.
+9. Browser/PWA, Capacitor, Electron, SSR, and accessibility requirements.
+
+Summarize the route topology before implementation when it is non-trivial.
+
+## Install and bootstrap
+
+Add `@native-vue-router/core` and its stylesheet. Add preset or platform packages
+only when needed. Match the project's package manager and formatting style.
+
+Create exactly one native runtime for one authoritative root route surface:
+
+1. Create the Vue Router normally.
+2. Pass that router to `createNativeRouter`.
+3. Call `app.use(router)` before `app.use(nativeRouter)`.
+4. Wait for `router.isReady()` when the application already does so or relies on
+   deterministic initial rendering.
+5. Replace the root visual `RouterView` with `NativeRouterView`.
+6. Wrap it in `NativeNavigator` only when predictive Back or sibling paging is
+   required.
+
+Retain nested `RouterView` components inside route components. Do not add nested
+independent native runtimes without an explicit ownership design.
+
+## Model route topology
+
+Add the smallest route metadata needed for the requested behavior:
+
+- Use `presentation` for a route's default visual treatment.
+- Add `parent` to directly addressable child or presented routes so a cold start
+  has a predictive Back destination.
+- Add numeric `siblingOrder` to peer routes whose direction must be stable.
+- Choose `siblingHistory: "replace"` for tabs and other peers that should not
+  grow Back history; use `"push"` only when Back should revisit peer selection.
+- Use `cache: false` for routes that must be destroyed when inactive and
+  `cache: "pin"` only for deliberately retained views.
+- Use `gesture: false` to disable navigator gesture handling for a route.
+
+Preserve params, query, and hash in dynamic `parent` functions whenever they are
+part of the logical parent location. Do not infer parentage from the mounted
+cache or route registration order.
+
+`navigator` and `siblingGroup` are reserved labels in `0.1.x`; do not claim that
+they automatically create navigator ownership. Pass sibling locations to
+`NativeNavigator` explicitly.
+
+## Migrate navigation intentionally
+
+Use native runtime methods for navigation that needs preview-driven motion:
+
+- `push` or `NativeLink` for forward stack navigation.
+- `replace` for no-growth replacement.
+- `sibling` for ordered peers.
+- `pop` for Back.
+- `present` and `dismiss` for modal or sheet routes.
+- `NativeSheet` for safe-area-contained, content-height, or snapping sheet
+  surfaces.
+- `NativeGestureLink` for component-originated horizontal dragging.
+- `NativeDismissGesture` for downward dismissal.
+
+Leave raw Vue Router navigation in place when it is an intentional redirect,
+non-animated control flow, or external integration. The runtime reconciles such
+navigation, but it cannot preview it before commit.
+
+Preserve standard link semantics. Prefer `NativeLink` when a true anchor is
+needed. If using `NativeGestureLink`, select a semantic `as` element and retain
+keyboard activation and accessible naming.
+
+## Make preview mounts safe
+
+Assume a destination can run setup and mount before its route guard approves the
+navigation, and can then unmount without becoming current.
+
+Move committed-screen side effects from unconditional setup/mount code to
+`useNativeViewActiveEffect`, `onNativeViewActivate`, or explicit user actions.
+Use `useNativeViewVisibleEffect` only for work needed while the route is active
+or participating in a transition. Keep durable data in a store or persistence
+layer because the bounded native cache may evict component instances.
+
+Do not replace the native multi-route cache with a single Vue `KeepAlive`.
+`KeepAlive`, `Transition`, `Teleport`, and `Suspense` may still be composed
+inside the `NativeRouterView` slot. Gate teleported overlays on native view
+visibility because teleported DOM is outside the inactive layer's `inert` and
+`aria-hidden` boundary.
+
+For partial sheets, use `NativeSheet` rather than styling a route component with
+an arbitrary viewport height. Use no breakpoints for content height, or
+fractional breakpoints for snap points. Keep `presentation: "sheet"` in route
+metadata so direct entries retain safe-area and underlay behavior.
+Preserve the built-in scroll body unless replacing its gesture arbitration:
+normal content scrolling owns interior positions, while top/down and bottom/up
+overscroll started at a boundary hands off to sheet resizing. Keep one owner for
+the complete physical gesture; never reinterpret accumulated content-scroll
+distance as sheet movement after an edge is reached or direction reverses.
+
+Use scoped `useRoute()` or Options API `$route` inside route trees. During a
+preview, do not substitute `router.currentRoute`: it intentionally remains the
+committed source location until navigation succeeds.
+
+## Add gesture ownership safely
+
+Wrap only the intended route surface in `NativeNavigator`. Give the container a
+definite height and import core CSS.
+
+Mark nested horizontal interaction regions with
+`data-native-gesture="ignore"`. Confirm vertical scrolling, controls, text
+selection, RTL behavior, reduced motion, keyboard navigation, focus, and screen
+reader isolation after adding gestures.
+
+Do not promise deterministic browser-edge ownership. Recommend Capacitor when a
+product requires native-level suppression of host Back gestures.
+
+## Add host adapters at the boundary
+
+For Capacitor, install the adapter in `createNativeRouter` and configure hardware
+Back, haptics, deep-link mapping, background cache trimming, and root exit. Do
+not assume Universal Links or App Links are configured by JavaScript alone.
+
+For Electron, call `disableElectronHistoryGestures(app.commandLine)` before
+`app.whenReady()` in the main process. Expose only the renderer callbacks needed
+by `createElectronRendererAdapter` through a secure preload. Preserve hash or
+custom-protocol history behavior used by packaged applications.
+
+Keep host detection and host APIs out of route components unless the product
+experience genuinely differs.
+
+## Verify the integration
+
+Run the target project's formatter, type checker, unit tests, build, and relevant
+end-to-end tests. Add tests or manual verification for the changed behavior:
+
+- Direct entry and reload on deep child URLs.
+- Params, query, hash, redirects, and nested route injection.
+- Both routes remain live during a held gesture while the URL stays unchanged.
+- Gesture cancellation preserves the source URL and state.
+- Accepted and rejected guards settle correctly.
+- Browser Back/Forward and cold-start parent Back.
+- Sibling direction and replace/push history behavior.
+- Cached state, eviction, unload, and active/visible effects.
+- Vue built-ins, provide/inject, Options API `$route`, and lifecycle hooks used
+  by the application.
+- Teleported overlay cleanup and inactive-route focus isolation.
+- Gesture conflicts, RTL, reduced motion, keyboard behavior, and target hosts.
+
+Use `runtime.entries`, `activeKey`, `transaction`, `canGoBack`, `cacheStats`, and
+`onDiagnostic` for focused diagnostics. Use the profiler only when measuring
+frame behavior; it is opt-in and should be stopped/disposed after capture.
+
+## Report the result
+
+State which routes and navigation paths became native-aware, which raw Vue Router
+paths remain intentionally unchanged, what lifecycle work moved, and what was
+verified. Call out unresolved host limitations, missing parent topology, or
+dependency incompatibility explicitly.