# Native Vue Router

Native Vue Router is a gesture-first navigation runtime for Vue 3 and Vue Router 5. It keeps Vue Router in charge of matching, URLs, guards, and history while rendering live route stacks that can be manipulated interactively.

The repository includes a reusable headless core, a platform-adaptive visual preset, Capacitor and Electron adapters, and one messaging demo delivered as a PWA and through native hosts.

## What works

- Interactive edge pop that can be held indefinitely at any progress.
- Ordered horizontal route paging with replace-by-default history.
- Component-originated route dragging with a live target route.
- Interactive push, adjacent-page sibling slide, modal, sheet, fade, and application-defined presentations.
- Concurrent `from` and `to` routes using only public Vue Router 5 APIs.
- Guarded commits: previews do not alter the URL, and rejected navigation springs back.
- Cold-start predictive back through declared parent routes.
- Bounded live view caching, nested router views, focus isolation, RTL, and reduced motion.
- PWA, Electron, and Capacitor iOS/Android hosts.

## Run it

```bash
npm install
npm run dev
```

The default app is the installable messaging PWA. Other useful commands:

```bash
npm run build          # packages, declarations, demo, and service worker
npm test               # core transaction tests
npm run test:e2e       # desktop and mobile Playwright projects
npm run electron       # build and launch the Electron host
npm run cap:sync       # build and synchronize iOS and Android projects
```

Native projects live under `apps/capacitor/ios` and `apps/capacitor/android`. Open or run them from `apps/capacitor` with `npx cap open ios`, `npx cap open android`, or `npx cap run <platform>`.

## Minimal integration

```ts
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import { createNativeRouter } from '@native-vue-router/core'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    { path: '/', component: Home },
    {
      path: '/chat/:id',
      component: Chat,
      meta: {
        native: { presentation: 'push', parent: '/', gesture: 'edge' },
      },
    },
  ],
})

const nativeRouter = createNativeRouter({ router })
createApp(App).use(router).use(nativeRouter).mount('#app')
```

```vue
<script setup lang="ts">
import { NativeGestureLink, NativeNavigator, NativeRouterView } from '@native-vue-router/core'
</script>

<template>
  <NativeNavigator :siblings="['/', '/stories', '/profile']">
    <NativeRouterView />
  </NativeNavigator>
  <NativeGestureLink to="/chat/maya" presentation="reveal">
    Drag this row into the chat route
  </NativeGestureLink>
</template>
```

Import `@native-vue-router/core/style.css` for the built-in presentation layers. The demo imports `@native-vue-router/preset-native/style.css` as well.

Use `nativeRouter.sibling(to)` for tab or peer-route navigation. Direction is derived from `siblingOrder`, repeated navigation to the active route is a no-op, and `siblingHistory: 'replace'` keeps cached tab views out of the back stack.

## Packages

- `@native-vue-router/core` — transactions, route ledger, concurrent views, gestures, caching, and public components/composables.
- `@native-vue-router/preset-native` — adaptive tab/back controls, safe-area CSS, and platform motion defaults.
- `@native-vue-router/capacitor` — hardware back, deep links, pause cancellation, root exit, and haptics.
- `@native-vue-router/electron` — Chromium history-gesture suppression and renderer back/forward bridging.

See [architecture](docs/architecture.md) and [platform integration](docs/platforms.md) for the transaction lifecycle and host-specific behavior.

## Support contract

The target is Vue 3.5+ and Vue Router 5. Installed PWAs, current Electron, and Capacitor 8 are first-class. Normal browser tabs remain functional but browsers can reserve edge gestures that page content cannot consistently override.

MIT